react-x11 2.8.3 → 2.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-x11",
-  "version": "2.8.3",
+  "version": "2.9.1",
   "description": "react renderer with X11 as a target",
   "main": "./src/index.js",
   "files": [
@@ -32,6 +32,7 @@
     "examples:tooltips": "tsx examples/tooltips.jsx",
     "examples:chat": "tsx examples/chat.jsx",
     "examples:clipboard": "tsx examples/clipboard.jsx",
+    "examples:calendar": "tsx examples/calendar.jsx",
     "labs:urischeme": "tsx examples/labs/urischeme.jsx",
     "filedialog:probe": "node scripts/filedialog-probe.mjs",
     "a11y:probe": "node scripts/a11y-probe.mjs",
@@ -92,13 +93,14 @@
     "node": ">=20.19"
   },
   "dependencies": {
+    "ical.js": "^2.2.1",
     "linebreak": "^1.1.0",
     "ntk": "^8.7.0",
     "react-reconciler": "^0.33.0",
     "yoga-layout": "^3.2.1"
   },
   "optionalDependencies": {
-    "@windowkit/appkit": "^0.6.0",
+    "@windowkit/appkit": "^0.8.0",
     "dbus-native": "^0.15.1",
     "x11-dri": "^0.7.0"
   },

package/src/Reconciler.js

@@ -33,6 +33,7 @@ import {
   windowAttributes,
   setTextStripBelow,
 } from './nodes.js';
+import { setFrameRateDefault } from './pacing.js';
 import { hasDropProps } from './dnd.js';
 import { AppProvider } from './appcontext.js';
 import {
@@ -796,6 +797,12 @@ export async function createRoot(options = {}) {
   // default, 0 for glyphs at every size.
   setTextStripBelow(app, rest.textStripBelow);
 
+  // How this root's windows pace their frames when their content changes
+  // faster than the display refreshes (src/pacing.js): `'display'` — every
+  // frame the clock gives — unless the root says otherwise; a window's own
+  // `frameRate` prop wins over this, and REACT_X11_FRAME_RATE over both.
+  setFrameRateDefault(app, rest.frameRate);
+
   // Whether a subtree coming back out of hiding — a `<Suspense>` boundary
   // resolving, an `<Activity>` shown again — takes the keyboard back with it
   // (src/events.js, `subtreeRevealed`). On by default; `false` is the

package/src/cocoa/app.js

@@ -25,6 +25,7 @@ import { CocoaGLArea, cocoaGLConfig, resolveCocoaGLRuntime } from './glarea.js';
 import { CocoaDockMenu } from './dock.js';
 import { CocoaGlobalMenuExport } from './globalmenu.js';
 import { CocoaStatusItem } from './statusitem.js';
+import { CocoaCalendars } from './calendar.js';
 import { CocoaNotifications } from './notifications.js';
 import { CocoaPaneHost } from './panehost.js';
 import { CocoaPermissions } from './permissions.js';
@@ -177,6 +178,17 @@ export class CocoaApp {
         ? new CocoaNotifications(this)
         : null;
 
+    // EventKit (src/cocoa/calendar.js). Present exactly when the bridge has
+    // it (>= 0.8), and its presence is the top rung of
+    // src/desktopcalendar.js's ladder for this app — an older bridge leaves
+    // the ladder to find `osascript` instead, which answers the same
+    // questions out of the same framework.
+    this.calendars =
+      typeof native.calendars === 'function' &&
+      typeof native.eventsBetween === 'function'
+        ? new CocoaCalendars(this)
+        : null;
+
     // The GL policy, glbackend.js's shape. No GLX exists here, so the
     // default is 'auto' (the direct backend where the runtime loads);
     // useSupports('shaders') stays false until the first <glarea> resolves
@@ -537,8 +549,25 @@ export class CocoaApp {
     for (const wnd of this._windows.values()) wnd.liveResizing = false;
   }
 
+  /**
+   * `requestAnimationFrame`, for a window or for the app's own clock. A
+   * frame asked for between two pump ticks used to wait for the next tick
+   * to look at it — up to a pump interval on top of whatever the clock
+   * owed. Now, while the pump runs, the first request into an empty queue
+   * arms the same one-shot a tick arms for a frame it just missed
+   * (`_armFrameTimer`), at the moment the clock is due; a request for a
+   * clock due after the next tick leaves it to the tick, as before. What
+   * a frame is and how many there are does not change — the clock still
+   * gates every one — only when it is looked at, which is what makes a
+   * paced claim (src/pacing.js) land at its wait rather than at its wait
+   * rounded up to the pump.
+   */
   _requestFrame(cb, wnd = null) {
     this._rafQueue.push({ cb, wnd });
+    if (this._pump && this._rafQueue.length === 1) {
+      const now = performance.now();
+      this._armFrameTimer(Math.max(1, this._frameWait(wnd ?? this, now)), now);
+    }
     return this._rafQueue.length;
   }
 
@@ -750,6 +779,12 @@ export class CocoaApp {
       case 'notification-dismissed':
         this.notifications?.route(ev);
         return this._afterInput();
+      case 'calendar-store-changed':
+        // EventKit's own notification, which names nothing that changed. A
+        // watcher's answer is to query again, and that query's result is a
+        // render, so the frame goes out the way an input's does.
+        this.calendars?.route(ev);
+        return this._afterInput();
       case 'animation-end':
         // the presenter that added the animation registered for its id; an
         // id nobody knows is an animation already forgotten (cancelled, or

package/src/cocoa/calendar.js

@@ -0,0 +1,186 @@
+// The user's calendars on the cocoa backend — EventKit (`EKEventStore`)
+// through @windowkit/appkit (>= 0.8), the top rung of
+// src/desktopcalendar.js's ladder. `CocoaApp.calendars` is this object and
+// its *presence* is the capability, the rule `filePanels`, `permissions` and
+// `notifications` follow, so the ladder never names a backend.
+//
+// EventKit is the macOS counterpart of Evolution Data Server plus GNOME
+// Online Accounts in one framework: every account the user added in System
+// Settings > Internet Accounts — iCloud, Google, Exchange, CalDAV, a
+// subscribed feed — is served by one store, the desktop did the OAuth, and
+// the app never sees a credential.
+//
+// Three things about the framework shape the code here:
+//
+// - **It expands recurrences itself.** `predicateForEventsWithStartDate…`
+//   answers occurrences, so there is no `ical.js` on this rung and no
+//   recurrence arithmetic to get wrong. The EDS rung pays for that
+//   client-side; this one does not.
+// - **The predicate spans at most four years** (the framework's own limit),
+//   so a longer range is asked for in chunks and the pieces are merged —
+//   `chunkSpan` in ../desktopcalendar.js, shared with the `osascript` rung
+//   because it is the same framework underneath.
+// - **An all-day event ends at the last second of its last day.** Every
+//   other rung, and `byDay`, read `end` as exclusive, so it is normalised
+//   here — at the edge, once, rather than in every consumer.
+//
+// A change to anything in the store arrives as one `calendar-store-changed`
+// backend event that names nothing, so `watch` reports `kind: 'changed'`
+// with a null calendar and no count. Re-query; do not try to patch.
+
+import {
+  calendarBackendName,
+  chunkSpan,
+  hexFromComponents,
+  sortEvents,
+  withExclusiveEnd,
+} from '../desktopcalendar.js';
+
+/** `EKCalendar` as the shape every rung answers with. */
+export function calendarInfo(cal) {
+  return {
+    uid: String(cal.id),
+    name: cal.title ?? '',
+    // EventKit has no "unchecked in the sidebar" state to report — a
+    // calendar hidden in Calendar.app is still in the store — so every
+    // calendar here is enabled, which is what `enabled` means to a caller
+    // filtering the list.
+    enabled: true,
+    color: hexFromComponents(cal.color),
+    backend: calendarBackendName(cal.type),
+    readOnly: cal.allowsModifications === false || cal.immutable === true,
+    // The account the calendar came from, which is what the EDS rung's
+    // `account` is too: an `EKSource` is the Internet Accounts entry.
+    account: cal.source?.title ?? undefined,
+  };
+}
+
+/** One occurrence from the bridge as the shape every rung answers with. */
+export function desktopEvent(ev, byId) {
+  const meta = byId.get(String(ev.calendar));
+  const start = new Date(ev.start);
+  return {
+    uid: String(ev.id ?? ev.itemId ?? `${ev.calendar}:${ev.start}`),
+    summary: ev.title ?? '',
+    location: ev.location ?? undefined,
+    description: ev.notes ?? undefined,
+    start,
+    end: withExclusiveEnd(new Date(ev.end), Boolean(ev.allDay)),
+    allDay: Boolean(ev.allDay),
+    recurring: Boolean(ev.recurring),
+    calendar: meta
+      ? { uid: meta.uid, name: meta.name, color: meta.color }
+      : { uid: String(ev.calendar), name: '' },
+  };
+}
+
+export class CocoaCalendars {
+  constructor(app) {
+    this.app = app;
+    this._native = app._native;
+    this.backend = 'cocoa';
+    this._watchers = new Set();
+  }
+
+  /**
+   * The TCC grant, read without prompting. `'write-only'` is macOS 14's
+   * partial grant, which is a refusal to a reader — but its own word, so a
+   * caller that only saves events can tell it from a denial.
+   */
+  async access() {
+    return this.app.permissions
+      ? this.app.permissions.status('calendars')
+      : 'unknown';
+  }
+
+  /** The system prompt, once per app; the status after the user answered. */
+  async requestAccess() {
+    return this.app.permissions
+      ? this.app.permissions.request('calendars')
+      : 'unknown';
+  }
+
+  listCalendars() {
+    return new Promise((resolve, reject) => {
+      this._native.calendars((err, list) =>
+        err ? reject(err) : resolve((list ?? []).map(calendarInfo)),
+      );
+    });
+  }
+
+  _events(range) {
+    return new Promise((resolve, reject) => {
+      this._native.eventsBetween(range, (err, events) =>
+        err ? reject(err) : resolve(events ?? []),
+      );
+    });
+  }
+
+  /**
+   * The occurrences in a range, already expanded by the framework.
+   *
+   * `errors` is always empty here: there is one store, and a failure in it
+   * is a failure of the whole read rather than of one account. The EDS rung
+   * is the one where a single unreachable CalDAV server must not blank the
+   * month.
+   */
+  async eventsBetween(from, to, options = {}) {
+    const metas = options.calendars ?? (await this.listCalendars());
+    // "These calendars, of which there are none" is not "every calendar",
+    // which is what an empty filter means to the predicate underneath. A
+    // caller whose filter matched nothing must get nothing.
+    if (options.calendars && metas.length === 0) {
+      return { events: [], errors: [] };
+    }
+    const byId = new Map(metas.map((meta) => [meta.uid, meta]));
+    const ids = options.calendars ? metas.map((meta) => meta.uid) : undefined;
+
+    const events = [];
+    const seen = new Set();
+    for (const [start, end] of chunkSpan(from, to)) {
+      const raw = await this._events({ start, end, calendars: ids });
+      for (const one of raw) {
+        // An occurrence that straddles a chunk boundary is reported by both
+        // predicates; the caller must not see it twice.
+        const key = `${one.id} ${one.start}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        events.push(desktopEvent(one, byId));
+      }
+    }
+    return { events: sortEvents(events), errors: [] };
+  }
+
+  /**
+   * `EKEventStoreChangedNotification`, as the ladder's change signal.
+   *
+   * The notification names neither the calendar nor what happened — a
+   * detail EventKit does not have — so the change carries a null calendar
+   * and no count, and re-querying is the only correct answer. Every watcher
+   * hears every change, whatever range it asked for, because a change
+   * outside a range can still move what is inside it (a recurrence master
+   * edited months away).
+   */
+  async watch(from, to, onChange) {
+    const entry = { onChange };
+    this._watchers.add(entry);
+    return async () => {
+      this._watchers.delete(entry);
+    };
+  }
+
+  /** `calendar-store-changed`, routed from the app's backend callback. */
+  route() {
+    for (const entry of [...this._watchers]) {
+      try {
+        entry.onChange({ calendar: null, kind: 'changed', count: null });
+      } catch {
+        // a watcher that throws is not the other watchers' problem
+      }
+    }
+  }
+
+  /** Nothing to release: the store belongs to the process, and a handle's
+   *  own watchers are dropped by the stop function `watch` returned. */
+  async close() {}
+}

package/src/cocoa/context2d.js

@@ -85,13 +85,23 @@ const clamp01 = (v) => Math.min(1, Math.max(0, Number(v) || 0));
 /**
  * The Render ops text draws with, numbered as XRender numbers them so a
  * caller's `ctx.Render?.PictOp?.Over ?? 3` reads the same on both
- * backends. Every op draws as Over here: the bridge composites glyph
- * coverage with the context's fill and offers no blend-mode switch, and
- * for the opaque inks text uses Src and Over agree.
+ * backends. The `op` a `drawGlyphs` call names is ignored here: the bridge
+ * composites glyph coverage with the context's fill through the context's
+ * own blend mode — `globalCompositeOperation`, below — and for the opaque
+ * inks text uses Src and Over agree.
  */
 const PICT_OP = Object.freeze({ Src: 1, Over: 3 });
 const RENDER = Object.freeze({ PictOp: PICT_OP });
 
+/**
+ * `_state.clip` when the clip in force is not one this class can name — a
+ * rounded corner, a glyph, an arc, or a rect under a rotation. Null means
+ * nothing is clipped and a rect means that rect, in surface pixels; this
+ * means "there is one and I cannot tell you where", which is the answer
+ * that turns the memcpy blit off (see `_blit`).
+ */
+const NON_RECT = Symbol('non-rectangular clip');
+
 /**
  * The path, recorded alongside the native one, so `stroke` can re-issue it
  * in pieces — `CGContextStrokePath` is QUADRATIC in the number of subpaths
@@ -189,7 +199,18 @@ export class CocoaContext2D {
       shadowOffsetY: 0,
       shadowColor: 'rgba(0,0,0,0)',
       ctm: [1, 0, 0, 1, 0, 0],
+      gco: 'source-over',
+      // null: nothing clipped. A rect (surface pixels): that rect. NON_RECT:
+      // a clip this class cannot name.
+      clip: null,
     };
+    // What this bridge can do, asked once. Both verbs arrived together in
+    // @windowkit/appkit 0.7.0, and anything older is a bridge that draws
+    // every composite as `source-over` through a CGImage — so the property
+    // refuses what it cannot honour rather than lying about it, and the
+    // blit path is simply never taken.
+    this._blendModes = typeof native.ctxSetBlendMode === 'function';
+    this._blits = typeof native.blitSurface === 'function';
     this._onDirty = null;
     // the recorded path, and whether the native one still matches it (a
     // chunked stroke leaves only its last chunk behind)
@@ -211,6 +232,13 @@ export class CocoaContext2D {
       n.ctxSetLineJoin(surface, st.lineJoin);
       n.ctxSetGlobalAlpha(surface, st.globalAlpha);
       n.ctxSetLineDash(surface, st.dash, st.dashOffset);
+      // a fresh surface is already at source-over, so only a context
+      // holding another op has anything to say
+      if (this._blendModes && st.gco !== 'source-over') {
+        n.ctxSetBlendMode(surface, st.gco);
+      }
+      // a fresh surface is unclipped, whatever the old one had in force
+      st.clip = null;
       this._stack.length = 0;
       // the path went with the surface it was built on; nothing may
       // replay it onto the new one
@@ -282,6 +310,47 @@ export class CocoaContext2D {
     }
   }
 
+  get globalCompositeOperation() {
+    return this._state.gco;
+  }
+
+  /**
+   * The vocabulary is the **bridge's**, not a table kept here: the names are
+   * canvas's own, `ctxSetBlendMode` answers false for one it does not have,
+   * and that answer is what decides whether the assignment sticks. So this
+   * class never goes stale against a bridge that grows an op, and never
+   * claims one it would not actually draw.
+   *
+   * Which makes the detection a caller writes canvas's own — an unknown
+   * value is *ignored* there too, leaving the op in force — so the way to
+   * ask is to assign and read back:
+   *
+   *     ctx.globalCompositeOperation = 'copy';
+   *     if (ctx.globalCompositeOperation === 'copy') { ... }
+   *
+   * A bridge with no `ctxSetBlendMode` at all — @windowkit/appkit before
+   * 0.7.0 — draws everything as source-over, so source-over is the one
+   * value that sticks on it. That is exactly true rather than a fallback.
+   *
+   * One divergence from a browser, shared with ntk and so the same on both
+   * backends: an op applies inside what the draw covers, not across the
+   * whole surface. A browser's `copy` clears everything the drawing missed;
+   * `kCGBlendModeCopy` and XRender's `Src` both leave it alone.
+   */
+  set globalCompositeOperation(value) {
+    if (typeof value !== 'string') return;
+    if (!this._blendModes) {
+      if (value === 'source-over') this._state.gco = value;
+      return;
+    }
+    // false is the bridge saying it left its own mode alone; anything else
+    // means the mode is now `value`, and the two must not drift — a JS state
+    // ahead of the native one would take the memcpy path in `_blit` for a
+    // composite the fallback draw would have blended.
+    if (this._native.ctxSetBlendMode(this._s(), value) === false) return;
+    this._state.gco = value;
+  }
+
   /**
    * Whether a stroke of a path with many subpaths may go out as several
    * `CGContextStrokePath` calls — on by default, because the alternative
@@ -776,9 +845,70 @@ export class CocoaContext2D {
     ) {
       return;
     }
+    this._state.clip = this._clipAfter();
     this._native.ctxClip(this._path());
   }
 
+  /**
+   * The current path as a whole-pixel rect in surface coordinates, or null
+   * for anything else. CoreGraphics owns the real clip and this is only a
+   * shadow of it, kept for the one caller that draws *around* the context —
+   * `_blit`, whose memcpy cannot see a CGContext's clip at all.
+   *
+   * So the answer has to be exact, never merely close: a rect that does not
+   * land on whole pixels is refused rather than rounded, because rounding
+   * out would copy pixels the clip excludes and rounding in would leave a
+   * seam of whatever the destination held. The clips a paint pass actually
+   * sets — the damage rect, a scroll viewport, a square-cornered `overflow`
+   * — are whole pixels under a translate, and those are the ones this
+   * recognises.
+   */
+  _pathRect() {
+    const cmds = this._cmds;
+    if (cmds.length !== 5 || cmds[0] !== P_RECT) return null;
+    const [, x, y, w, h] = cmds;
+    const [a, b, c, d, e, f] = this._state.ctm;
+    if (b !== 0 || c !== 0) return null; // rotated or skewed: not a rect here
+    const x0 = a * x + e;
+    const y0 = d * y + f;
+    const x1 = a * (x + w) + e;
+    const y1 = d * (y + h) + f;
+    const rect = {
+      x: Math.min(x0, x1),
+      y: Math.min(y0, y1),
+      width: Math.abs(x1 - x0),
+      height: Math.abs(y1 - y0),
+    };
+    for (const v of [rect.x, rect.y, rect.width, rect.height]) {
+      if (!Number.isInteger(v)) return null;
+    }
+    return rect;
+  }
+
+  /** The clip `clip()` is about to leave in force: the current one
+   *  intersected with the path, or NON_RECT as soon as either is one. */
+  _clipAfter() {
+    const current = this._state.clip;
+    if (current === NON_RECT) return NON_RECT;
+    const rect = this._pathRect();
+    if (!rect) return NON_RECT;
+    if (!current) return rect;
+    const x = Math.max(current.x, rect.x);
+    const y = Math.max(current.y, rect.y);
+    return {
+      x,
+      y,
+      width: Math.max(
+        0,
+        Math.min(current.x + current.width, rect.x + rect.width) - x,
+      ),
+      height: Math.max(
+        0,
+        Math.min(current.y + current.height, rect.y + rect.height) - y,
+      ),
+    };
+  }
+
   fillRect(x, y, w, h) {
     if (!(w > 0) || !(h > 0)) return;
     const style = this._state.fillStyle;
@@ -843,10 +973,96 @@ export class CocoaContext2D {
       dw = sw;
       dh = sh;
     }
-    this._native.ctxDrawSurface(this._s(), src, sx, sy, sw, sh, dx, dy, dw, dh);
+    if (!this._blit(src, sx, sy, sw, sh, dx, dy, dw, dh)) {
+      this._native.ctxDrawSurface(
+        this._s(),
+        src,
+        sx,
+        sy,
+        sw,
+        sh,
+        dx,
+        dy,
+        dw,
+        dh,
+      );
+    }
     this._dirty();
   }
 
+  /**
+   * `drawImage` as a row memcpy, for the one shape where a copy is all it
+   * ever was: a surface composited into another at a translate, whole
+   * pixels, same size in as out, under `globalCompositeOperation = 'copy'`.
+   * Answers false for everything else, and the caller draws.
+   *
+   * That shape is what an element with a surface of its own presents every
+   * frame — a terminal's grid, a retained scene — and the CoreGraphics
+   * route to it is `CGBitmapContextCreateImage` of the whole source plus
+   * `CGContextDrawImage`: 1.7ms of a 6ms frame for a 125x45 terminal, where
+   * the memcpy is 1.0 (sidorares/react-x11-components#69 §6). The saving is
+   * per frame rather than per flood, which is why the frame pacer (#497)
+   * had to land first for it to be worth anything.
+   *
+   * Every condition below is a way the memcpy would differ from the draw,
+   * and a difference is a bug rather than a slower frame — so each is a
+   * refusal, never a fixup:
+   *
+   * - **the op.** Only `copy` writes the source over the destination
+   *   without reading it. `source-over` is a blend, and blending is what
+   *   CoreGraphics is for.
+   * - **the transform.** A pure translate at whole pixels. A scale or a
+   *   rotation resamples; a fractional offset resamples too (surfaces are
+   *   created with `kCGInterpolationMedium`).
+   * - **`globalAlpha`, and a shadow.** Both are things `CGContextDrawImage`
+   *   does to the source on its way down that a memcpy does not do at all.
+   * - **the clip.** A memcpy cannot see a CGContext's clip, so the rect it
+   *   copies is intersected with the one this class tracked — and a clip it
+   *   could not track (NON_RECT) means it does not know, so it draws.
+   * - **the same surface twice.** Overlapping memcpy rows have no defined
+   *   result. The check here is on the handle; the bridge's is on the
+   *   backing store, which also catches two handles onto one bitmap — the
+   *   two ends of a shared IOSurface — and throws rather than corrupting it.
+   */
+  _blit(src, sx, sy, sw, sh, dx, dy, dw, dh) {
+    if (!this._blits) return false;
+    const st = this._state;
+    if (st.gco !== 'copy') return false;
+    if (st.clip === NON_RECT) return false;
+    if (st.globalAlpha < 1) return false;
+    if (st.shadowBlur > 0 && parseColor(st.shadowColor)[3] > 0) return false;
+    if (sw !== dw || sh !== dh) return false;
+    const [a, b, c, d, e, f] = st.ctm;
+    if (a !== 1 || b !== 0 || c !== 0 || d !== 1) return false;
+    const x = dx + e;
+    const y = dy + f;
+    if (
+      !Number.isInteger(x) ||
+      !Number.isInteger(y) ||
+      !Number.isInteger(sx) ||
+      !Number.isInteger(sy) ||
+      !Number.isInteger(sw) ||
+      !Number.isInteger(sh)
+    ) {
+      return false;
+    }
+    const dst = this._s();
+    if (dst === src) return false;
+    const clip = st.clip;
+    this._native.blitSurface(
+      src,
+      sx,
+      sy,
+      sw,
+      sh,
+      dst,
+      x,
+      y,
+      clip ? [clip.x, clip.y, clip.width, clip.height] : null,
+    );
+    return true;
+  }
+
   /**
    * Browser contract: a blank RGBA pixel block for the caller to fill and
    * hand back to putImageData. Pure allocation — nothing touches the

package/src/cocoa/native.js

@@ -11,10 +11,27 @@
 // is CommonJS + a .node binary, so `createRequire` is the honest loader.
 import { createRequire } from 'node:module';
 
-const require = createRequire(import.meta.url);
-
 const PACKAGE = '@windowkit/appkit';
 
+// The loader is made on first use, and from the executable when there is
+// no module URL to make it from. A bundle built for Node's single-executable
+// format (docs/packaging.md, tier 3) is CommonJS, and esbuild leaves
+// `import.meta` an empty object in that output — so a module-scope
+// `createRequire(import.meta.url)` threw ERR_INVALID_ARG_VALUE the moment
+// the backend loaded, in every cocoa app shipped as a SEA, before this
+// could say what it was trying to load. `createRequire(process.execPath)`
+// is the loader Node's SEA docs prescribe (the embedded main's `__filename`
+// *is* the executable), and it answers both specs below: an absolute
+// REACT_X11_CALAYERS_PATH resolves from anywhere, and the bare package name
+// resolves through a `node_modules` beside the binary. Made lazily, a
+// loader that cannot be made at all is reported by the error at the bottom
+// rather than by a throw at import.
+let require = null;
+function load(spec) {
+  require ??= createRequire(import.meta.url ?? process.execPath);
+  return require(spec);
+}
+
 let cached = null;
 
 export function loadNative() {
@@ -30,7 +47,7 @@ export function loadNative() {
   const path = process.env.REACT_X11_CALAYERS_PATH;
   for (const spec of [path, PACKAGE].filter(Boolean)) {
     try {
-      const mod = require(spec);
+      const mod = load(spec);
       // the package's index.js exports the raw addon as `native`; a direct
       // path to a built checkout may be the addon itself
       cached = mod.native ?? mod;

package/src/cocoa/permissions.js

@@ -13,23 +13,32 @@
 // bundled app must carry the usage-description keys
 // (`NSCameraUsageDescription` and friends) or a request never prompts.
 
-/** Apple's four words as the ladder's. */
+/** Apple's words as the ladder's. `writeOnly` is macOS 14's partial grant
+ *  for EventKit — a grant to a writer, a refusal to a reader — and stays its
+ *  own word for exactly that reason. */
 const STATUS = Object.freeze({
   authorized: 'granted',
   denied: 'denied',
   restricted: 'restricted',
   notDetermined: 'prompt',
+  writeOnly: 'write-only',
 });
 
 export function statusFromBridge(status) {
   return STATUS[status] ?? 'unknown';
 }
 
-/** The bridge's options for a kind: `automation` carries its target. */
+/** The bridge's options for a kind: `automation` carries its target, and
+ *  `calendars` the level being asked for (`reminders` has no write-only
+ *  grant, and the bridge refuses one with a TypeError). */
 function bridgeOptions(kind, options = {}) {
-  return kind === 'automation' && options.target != null
-    ? { target: String(options.target) }
-    : undefined;
+  if (kind === 'automation' && options.target != null) {
+    return { target: String(options.target) };
+  }
+  if (kind === 'calendars' && options.access != null) {
+    return { access: String(options.access) };
+  }
+  return undefined;
 }
 
 export class CocoaPermissions {