react-x11 1.2.0 → 2.0.0

package/src/frame/index.js

@@ -0,0 +1,444 @@
+// <Frame>: a pane of this application, running in its own process.
+//
+// The composition is deliberately thin, because both halves already exist:
+// the window boundary is `<foreign>` (the pane's window, embedded and laid
+// out like any child — docs/embedding.md), and the process boundary is a
+// forked node with `src/frame/child.js` as its entry. What this file owns is
+// the contract between them, and the contract is narrow on purpose:
+//
+//  - **`props` is a bag of data**, snapshotted per parent commit and sent
+//    whole (structured clone; `serialization: 'advanced'`). Functions in it
+//    become RPC stubs — fire and forget, one direction (src/frame/protocol.js).
+//  - **Context crosses only through the bridge** (src/frame/env.js):
+//    `createFrameContext` values, and the theme by default, because a pane
+//    that silently loses the app's palette looks broken in a way that
+//    indicts the whole feature. `bridge={false}` (or an allowlist) is the
+//    off switch that default owes.
+//  - **The pane owns its data and its animation.** Props are for queries,
+//    ids, ranges — an update is an IPC hop plus a child commit, the right
+//    cost for "show this now", the wrong one for driving a spinner at 60fps.
+//
+// What a process boundary is here, and is not: an uncaught throw, a leak or
+// a GC pause in the pane stays in the pane, and the shell's event loop never
+// waits for it. It is **not a security boundary** — the pane holds a
+// full-privilege connection to the same X server (docs/security.md), so
+// `<Frame>` contains a pane's *failures*, not its intentions.
+//
+// Lifecycle, from both sides: the child reports `ready` (→ `onStarted`,
+// and the embed), `fatal` (why the exit about to happen is one) and exit
+// (→ `onExit`, and `fallback` when the host did not ask for it). The host
+// closes a pane by message first — `useFrameClose` handlers run there —
+// and only escalates to signals when asked nicely stops working.
+
+import { fork } from 'node:child_process';
+import { isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import React, {
+  useCallback,
+  useContext,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from 'react';
+
+import { FrameEnv } from './env.js';
+import { CallbackTable, PROTOCOL } from './protocol.js';
+
+const h = React.createElement;
+
+/** The forked entry's path — resolved at first spawn, not at import. The
+ * website playground bundles this module with throw-on-call stubs for the
+ * node builtins, and a top-level `fileURLToPath` would throw on *load*;
+ * lazily, `<Frame>` imports everywhere and says "needs a desktop" only
+ * when something actually spawns. */
+let childEntry = null;
+const childPath = () =>
+  (childEntry ??= fileURLToPath(new URL('./child.js', import.meta.url)));
+
+/**
+ * @typedef {object} FrameTransport The parent's end of the wire to a pane.
+ * @property {(msg: object) => void} send may throw when the channel is gone
+ * @property {(cb: (msg: object) => void) => () => void} onMessage
+ * @property {(cb: (info: { code: number|null, signal: string|null }) => void) => () => void} onExit
+ * @property {(signal: string) => void} [kill] escalation; absent on
+ *   transports with nothing to kill
+ * @property {number} [pid]
+ */
+
+/** The default transport: fork this package's child entry. `execArgv` is
+ * inherited, which is what carries a dev loader (tsx, the refresh loader)
+ * into the pane; a bundled app forks plain JS and needs none. */
+function forkTransport({ src, display }) {
+  const child = fork(childPath(), [], {
+    serialization: 'advanced',
+    // dev loaders (tsx, the refresh loader) follow into the pane; the test
+    // runner's own flags must not — `--test` in execArgv would run the pane
+    // entry as a test file
+    execArgv: process.execArgv.filter(
+      (a) => a !== '--test' && !a.startsWith('--test-'),
+    ),
+    env: {
+      ...process.env,
+      REACT_X11_FRAME: '1',
+      ...(display ? { DISPLAY: display } : {}),
+    },
+  });
+  void src; // resolved by the child from the hello, not from argv
+  return {
+    send: (msg) => {
+      if (!child.connected) throw new Error('the pane process is gone');
+      child.send(msg);
+    },
+    onMessage: (cb) => {
+      child.on('message', cb);
+      return () => child.off('message', cb);
+    },
+    onExit: (cb) => {
+      const onExit = (code, signal) => cb({ code, signal });
+      const onError = (err) =>
+        cb({ code: null, signal: null, error: err ?? null });
+      child.on('exit', onExit);
+      child.on('error', onError);
+      return () => {
+        child.off('exit', onExit);
+        child.off('error', onError);
+      };
+    },
+    kill: (signal) => {
+      try {
+        child.kill(signal);
+      } catch {
+        // already gone, which is what the signal was for
+      }
+    },
+    pid: child.pid,
+  };
+}
+
+function srcString(src) {
+  if (src !== null && typeof src === 'object' && typeof src.href === 'string') {
+    return src.href;
+  }
+  if (
+    typeof src === 'string' &&
+    (/^[a-z][a-z0-9+.-]*:/i.test(src) || isAbsolute(src))
+  ) {
+    return src;
+  }
+  throw new Error(
+    'react-x11: <Frame src> must be a URL or an absolute path — a relative ' +
+      "one would resolve against react-x11's own files, not yours. Pass " +
+      "src={new URL('./pane.js', import.meta.url)}.",
+  );
+}
+
+/** Bridged values are data; here is where that is enforced. A value that
+ * cannot cross is dropped with its key named — once — rather than taking
+ * the whole update down with a DataCloneError deep in a send. */
+const cloneable = new WeakSet();
+const warnedKeys = new Set();
+function bridgedEnv(env, bridge) {
+  if (bridge === false) return new Map();
+  const allow = Array.isArray(bridge) ? new Set(bridge) : null;
+  const out = new Map();
+  for (const [key, value] of env) {
+    if (allow && !allow.has(key)) continue;
+    if (value !== null && typeof value === 'object' && !cloneable.has(value)) {
+      try {
+        structuredClone(value);
+        cloneable.add(value);
+      } catch (err) {
+        if (!warnedKeys.has(key)) {
+          warnedKeys.add(key);
+          console.warn(
+            `react-x11: <Frame> cannot bridge context '${key}' ` +
+              `(${err.message}) — bridged values are data only; dispatchers ` +
+              'and other functions travel in props (docs/frame.md)',
+          );
+        }
+        continue;
+      }
+    } else if (typeof value === 'function') {
+      if (!warnedKeys.has(key)) {
+        warnedKeys.add(key);
+        console.warn(
+          `react-x11: <Frame> cannot bridge context '${key}': it is a ` +
+            'function — bridged values are data only (docs/frame.md)',
+        );
+      }
+      continue;
+    }
+    out.set(key, value);
+  }
+  return out;
+}
+
+/** One `Object.is` pass over the bag, so a parent that re-renders without
+ * touching the pane's inputs does not wake the pane. Inline handlers defeat
+ * it — a new closure is a new value — and that only costs the send. */
+function shallowEqual(a, b) {
+  if (a === b) return true;
+  const ak = Object.keys(a);
+  const bk = Object.keys(b);
+  if (ak.length !== bk.length) return false;
+  for (const k of ak) if (!Object.is(a[k], b[k])) return false;
+  return true;
+}
+
+const EMPTY_PROPS = {};
+
+/**
+ * A module of this application, mounted in its own process, its window
+ * embedded here.
+ *
+ * ```jsx
+ * <Frame
+ *   src={new URL('./charts.pane.js', import.meta.url)}
+ *   props={{ rows, range, onPick }}
+ *   style={{ flexGrow: 1, backgroundColor: '$surface' }}
+ *   fallback={({ error, restart }) => <Crashed error={error} onRetry={restart} />}
+ * />
+ * ```
+ *
+ * The pane module's default export is the component; it receives `props`
+ * (functions arrive as fire-and-forget stubs), under the bridged context
+ * providers. `ref` exposes `{ restart(), pid }`.
+ */
+export function Frame({
+  src,
+  props = EMPTY_PROPS,
+  style,
+  display,
+  bridge = true,
+  fallback,
+  focusable,
+  onStarted,
+  onExit,
+  transport,
+  ref,
+}) {
+  const env = useContext(FrameEnv);
+  const [state, setState] = useState({
+    phase: 'starting',
+    windowId: null,
+    error: null,
+  });
+  const [generation, setGeneration] = useState(0);
+  const session = useRef(null);
+  // the latest render's callbacks and bags, for the long-lived effect
+  const current = useRef(null);
+  current.current = { props, env, bridge, onStarted, onExit };
+
+  const restart = useCallback(() => {
+    setState({ phase: 'starting', windowId: null, error: null });
+    setGeneration((g) => g + 1);
+  }, []);
+  useImperativeHandle(ref, () => ({
+    restart,
+    get pid() {
+      return session.current?.transport?.pid ?? null;
+    },
+  }));
+
+  const source = srcString(src);
+  const makeTransport = transport ?? forkTransport;
+  const containerRef = useRef(null);
+
+  // The session: one child process per (src, display, transport, restart).
+  // Declared before the update effect so that on the mounting commit the
+  // hello goes out first and the update pass sees itself already sent.
+  useEffect(() => {
+    let alive = true;
+    const fail = (error) => {
+      if (!alive) return;
+      setState({ phase: 'failed', windowId: null, error });
+    };
+
+    let t;
+    try {
+      t = makeTransport({ src: source, display });
+    } catch (err) {
+      fail(Object.assign(err, { phase: 'spawn' }));
+      return undefined;
+    }
+    const s = {
+      transport: t,
+      table: new CallbackTable(),
+      closing: false,
+      fatal: null,
+      sent: null,
+      shutdown: null,
+    };
+    session.current = s;
+
+    const trySend = (msg) => {
+      try {
+        t.send(msg);
+        return true;
+      } catch (err) {
+        // hello or an update that would not serialize (or a channel that
+        // closed mid-send): the pane cannot follow the app from here
+        if (!s.closing) fail(Object.assign(err, { phase: 'send' }));
+        return false;
+      }
+    };
+    s.trySend = trySend;
+
+    // Both listeners live until the *exit*, not until the effect cleanup: a
+    // `useFrameClose` handler flushing through a callback prop sends its
+    // `invoke` after the unmount message, and dropping it would make the
+    // close hook useless for the one thing it is for.
+    let offMessage = t.onMessage((msg) => {
+      if (msg?.type === 'ready') {
+        if (!alive || s.closing) return;
+        setState({ phase: 'running', windowId: msg.windowId, error: null });
+        current.current.onStarted?.({
+          pid: t.pid ?? null,
+          windowId: msg.windowId,
+        });
+      } else if (msg?.type === 'invoke') {
+        s.table.invoke(msg.id, msg.args);
+      } else if (msg?.type === 'fatal') {
+        s.fatal = msg;
+      }
+    });
+
+    let clearEscalation = null;
+    let offExit = null;
+    const detach = () => {
+      offMessage?.();
+      offMessage = null;
+      offExit?.();
+      offExit = null;
+    };
+    offExit = t.onExit(({ code = null, signal = null, error } = {}) => {
+      clearEscalation?.();
+      detach();
+      const expected = s.closing;
+      if (alive && !expected) {
+        const f = s.fatal;
+        const err = Object.assign(
+          new Error(
+            f?.message ??
+              error?.message ??
+              `the pane exited (${signal ?? `code ${code}`})`,
+          ),
+          { phase: f?.phase ?? 'exit', code, signal },
+        );
+        if (f?.stack) err.stack = f.stack;
+        fail(err);
+      }
+      // Deliberately not gated on `alive`: the exit a graceful close ends in
+      // arrives *after* the unmount that asked for it, and `expected: true`
+      // would otherwise be an event no one can ever receive. The exit
+      // belongs to the session, not to the mounted lifetime.
+      current.current.onExit?.({ code, signal, expected });
+    });
+
+    // Ask first, signal later. The message lets `useFrameClose` handlers
+    // run and the root unmount cleanly; the signals are for a pane that
+    // stopped listening — which a crashed or wedged one has.
+    s.shutdown = () => {
+      if (s.closing) return;
+      s.closing = true;
+      let sent = false;
+      try {
+        t.send({ type: 'unmount' });
+        sent = true;
+      } catch {
+        // never came up, or already gone — straight to the signal
+      }
+      const term = setTimeout(() => t.kill?.('SIGTERM'), sent ? 1500 : 0);
+      const kill = setTimeout(() => t.kill?.('SIGKILL'), 4000);
+      term.unref?.();
+      kill.unref?.();
+      clearEscalation = () => {
+        clearTimeout(term);
+        clearTimeout(kill);
+      };
+    };
+
+    // The hello carries everything the first paint needs — above all the
+    // bridged theme, so the pane's first frame is in the app's palette
+    // rather than one frame of default before an update lands.
+    const { props: p, env: e, bridge: b } = current.current;
+    const node = containerRef.current;
+    const rect = {
+      width: Math.max(1, Math.round(node?.abs?.width || 0)) || 400,
+      height: Math.max(1, Math.round(node?.abs?.height || 0)) || 300,
+    };
+    s.sent = { props: p, env: e, bridge: b };
+    trySend({
+      type: 'hello',
+      protocol: PROTOCOL,
+      src: source,
+      display,
+      rect,
+      props: s.table.snapshot(p),
+      env: bridgedEnv(e, b),
+    });
+
+    return () => {
+      alive = false;
+      s.shutdown();
+      // the listeners and escalation timers outlive the effect on purpose:
+      // the listeners deliver what the close handlers still send and clear
+      // the escalation on exit, the timers bound a pane that ignores the
+      // ask, and everything is unref'd so nothing holds the host open
+      if (session.current === s) session.current = null;
+    };
+  }, [source, display, generation, makeTransport]);
+
+  // One update per commit that changed the pane's inputs, props and env in
+  // the same message — so a theme flip and the state change that caused it
+  // land in the child as one commit, not a torn pair.
+  useEffect(() => {
+    const s = session.current;
+    if (!s || s.closing || !s.sent) return;
+    if (
+      shallowEqual(s.sent.props, props) &&
+      s.sent.env === env &&
+      s.sent.bridge === bridge
+    ) {
+      return;
+    }
+    s.sent = { props, env, bridge };
+    s.trySend({
+      type: 'update',
+      props: s.table.snapshot(props),
+      env: bridgedEnv(env, bridge),
+    });
+  }, [props, env, bridge, generation]);
+
+  if (state.phase === 'running') {
+    return h('foreign', {
+      ref: containerRef,
+      windowId: state.windowId,
+      style,
+      ...(focusable === undefined ? {} : { focusable }),
+      onError: (err) => {
+        session.current?.shutdown?.();
+        setState({
+          phase: 'failed',
+          windowId: null,
+          error: Object.assign(err, { phase: 'embed' }),
+        });
+      },
+      // the exit path owns the state change; the window vanishing first is
+      // just the order X delivers the same death in
+      onClientGone: () => {},
+    });
+  }
+  const showFallback = state.phase === 'failed' && fallback !== undefined;
+  return h(
+    'box',
+    { ref: containerRef, style },
+    showFallback
+      ? typeof fallback === 'function'
+        ? fallback({ error: state.error, restart })
+        : fallback
+      : null,
+  );
+}

package/src/frame/lifecycle.js

@@ -0,0 +1,67 @@
+// The pane's side of the frame lifecycle — the two things a module loaded
+// into a `<Frame>` can ask about the world it landed in. Its own file so a
+// pane (and the components it imports) can use these without pulling in the
+// parent-side supervisor or the child bootstrap, neither of which belongs in
+// a bundle of UI code.
+
+import { useEffect } from 'react';
+
+/**
+ * Whether this process is a `<Frame>` pane. An environment fact rather
+ * than a hook, so a module can branch at load time — the usual reason to
+ * ask is "am I my own application?", and a pane module's
+ * `import.meta.main`-style autorun guard is where that question is asked.
+ *
+ * The env var is what the fork sets and what load-time code reads; the
+ * flag beside it is `runFrameChild` saying so directly, which is what
+ * makes a pane run behind a custom transport — no fork, no env — answer
+ * the same.
+ */
+let framed = false;
+export function isFramed() {
+  return framed || process.env.REACT_X11_FRAME === '1';
+}
+
+/** `runFrameChild`'s mark. Internal. */
+export function markFramed() {
+  framed = true;
+}
+
+/** What `runCloseHandlers` drains. Module state, like the compose table:
+ * one pane process has one close, however many components listen for it. */
+const closeHandlers = new Set();
+
+/**
+ * `handler` runs when the host is letting this pane go — the `<Frame>`
+ * unmounted, the host app is exiting — and the pane has a moment to flush
+ * what it would mind losing. It may return a promise; the host's patience
+ * is bounded (the parent escalates to SIGTERM), so "a moment" is meant
+ * literally: hundreds of milliseconds, not a sync.
+ *
+ * Not called when the pane crashes, and not called when the host is killed
+ * outright — a close handler is a courtesy, and anything that must survive
+ * a crash belongs on disk before the close.
+ *
+ * Outside a frame it registers nothing and the handler never runs.
+ */
+export function useFrameClose(handler) {
+  useEffect(() => {
+    if (!isFramed() || typeof handler !== 'function') return undefined;
+    closeHandlers.add(handler);
+    return () => closeHandlers.delete(handler);
+  }, [handler]);
+}
+
+/**
+ * Run every close handler, bounded by `timeout`. The bootstrap calls this
+ * on the `unmount` message, before unmounting the root — so a handler still
+ * has its tree, its connection and its state.
+ */
+export async function runCloseHandlers(timeout = 800) {
+  if (closeHandlers.size === 0) return;
+  const pending = [...closeHandlers].map(async (handler) => handler());
+  await Promise.race([
+    Promise.allSettled(pending),
+    new Promise((resolve) => setTimeout(resolve, timeout).unref?.()),
+  ]);
+}

package/src/frame/protocol.js

@@ -0,0 +1,179 @@
+// The wire between a `<Frame>` and its pane process. Pure data — no React,
+// no X11, no `child_process` — so the same protocol runs over node's IPC
+// channel (the fork transport), a loopback pair (the tests), or whatever a
+// custom transport is built on.
+//
+// Six messages, all objects with a `type`:
+//
+//   parent → child
+//     hello    { protocol, src, display, rect, props, env }   first, once
+//     update   { props, env }        full snapshots, one per parent commit
+//     unmount  {}                    run close handlers, unmount, exit
+//
+//   child → parent
+//     ready    { windowId }          the pane mounted; embed this
+//     invoke   { id, args }          a bridged callback fired
+//     fatal    { phase, message, stack }   why the exit about to happen is one
+//
+// Values cross by **structured clone** (fork uses `serialization:
+// 'advanced'`), so Dates, Maps, TypedArrays and cycles survive — and
+// functions do not, which is what the callback bridge is for: the parent
+// swaps each function in `props` for a `{ [CALLBACK]: id }` marker and keeps
+// the function; the child revives markers as stubs that send `invoke` back.
+// Fire and forget — a stub returns undefined, because a return value would
+// make every event handler an await and every await a frame of latency.
+//
+// Ids are **monotonic across updates**, never reused. The table keeps the
+// current snapshot's entries and the previous one's: React recreates handler
+// closures render to render, so a click that raced a props update arrives
+// with the previous snapshot's id and must still land — one snapshot of
+// grace covers the in-flight window, while an id from two updates ago is
+// dropped (with a warning) rather than delivered to the wrong function.
+// Functions the caller keeps stable (`useCallback`) keep their id, which is
+// what makes the grace window about racing messages rather than about how
+// the app was written.
+
+export const PROTOCOL = 1;
+
+/** The marker key a function in `props` becomes on the wire. */
+export const CALLBACK = '$$reactX11FrameCallback';
+
+const isPlainObject = (v) =>
+  v !== null &&
+  typeof v === 'object' &&
+  (Object.getPrototypeOf(v) === Object.prototype ||
+    Object.getPrototypeOf(v) === null);
+
+/**
+ * The parent's side of the callback bridge: give out wire snapshots of a
+ * props bag, answer `invoke` messages with the function each id stood for.
+ */
+export class CallbackTable {
+  constructor({ warn = console.warn } = {}) {
+    this._ids = new WeakMap(); // fn → id, stable across snapshots
+    this._seq = 0;
+    this._live = new Map(); // id → fn, the latest snapshot
+    this._prev = new Map(); // …and the one before it: the grace window
+    this._warn = warn;
+  }
+
+  /**
+   * Deep-copy `props` with every function replaced by its marker. Walks
+   * plain objects and arrays — a function buried in a `Map` value is not
+   * found, and the send will refuse the clone, which is the honest failure.
+   * Cycle-safe: a value already walked keeps one wire identity.
+   */
+  snapshot(props) {
+    const found = new Map();
+    const seen = new Map();
+    const walk = (value) => {
+      if (typeof value === 'function') {
+        let id = this._ids.get(value);
+        if (id === undefined) {
+          id = this._seq++;
+          this._ids.set(value, id);
+        }
+        found.set(id, value);
+        return { [CALLBACK]: id };
+      }
+      if (Array.isArray(value)) {
+        if (seen.has(value)) return seen.get(value);
+        const out = [];
+        seen.set(value, out);
+        for (const item of value) out.push(walk(item));
+        return out;
+      }
+      if (isPlainObject(value)) {
+        if (seen.has(value)) return seen.get(value);
+        const out = {};
+        seen.set(value, out);
+        for (const key of Object.keys(value)) out[key] = walk(value[key]);
+        return out;
+      }
+      return value;
+    };
+    const wire = walk(props);
+    this._prev = this._live;
+    this._live = found;
+    return wire;
+  }
+
+  /** Answer an `invoke` from the child. Returns whether an entry was found. */
+  invoke(id, args = []) {
+    const fn = this._live.get(id) ?? this._prev.get(id);
+    if (!fn) {
+      this._warn(
+        `react-x11: <Frame> dropped a callback (id ${id}) that outlived ` +
+          'two props updates — the child held a stub outside the props flow',
+      );
+      return false;
+    }
+    fn(...args);
+    return true;
+  }
+}
+
+/**
+ * The child's side: rebuild `props` with each marker replaced by a stub
+ * that sends `invoke(id, args)`. Same walk, other direction.
+ */
+export function reviveCallbacks(wire, invoke) {
+  const seen = new Map();
+  const walk = (value) => {
+    if (Array.isArray(value)) {
+      if (seen.has(value)) return seen.get(value);
+      const out = [];
+      seen.set(value, out);
+      for (const item of value) out.push(walk(item));
+      return out;
+    }
+    if (isPlainObject(value)) {
+      if (CALLBACK in value) {
+        const id = value[CALLBACK];
+        return (...args) => invoke(id, sanitizeArgs(args));
+      }
+      if (seen.has(value)) return seen.get(value);
+      const out = {};
+      seen.set(value, out);
+      for (const key of Object.keys(value)) out[key] = walk(value[key]);
+      return out;
+    }
+    return value;
+  };
+  return walk(wire);
+}
+
+/**
+ * Callback arguments, made sendable. A pane calls `onPick(item, ev)` the
+ * way it would call any handler, and `ev` is full of functions and node
+ * references — dropping what cannot cross (functions become `undefined`,
+ * everything else is kept) beats throwing away the whole call, which is
+ * what an unfiltered structured clone would do.
+ */
+export function sanitizeArgs(args) {
+  const seen = new Map();
+  const walk = (value) => {
+    if (typeof value === 'function') return undefined;
+    if (Array.isArray(value)) {
+      if (seen.has(value)) return seen.get(value);
+      const out = [];
+      seen.set(value, out);
+      for (const item of value) out.push(walk(item));
+      return out;
+    }
+    if (isPlainObject(value)) {
+      if (seen.has(value)) return seen.get(value);
+      const out = {};
+      seen.set(value, out);
+      for (const key of Object.keys(value)) {
+        const walked = walk(value[key]);
+        if (walked !== undefined || value[key] === undefined) {
+          out[key] = walked;
+        }
+      }
+      return out;
+    }
+    return value;
+  };
+  return args.map(walk);
+}