react-x11 1.2.0 → 2.0.0

package/src/frame/childmain.js

@@ -0,0 +1,274 @@
+// The pane process, from hello to exit. `src/frame/child.js` is the file
+// the parent actually forks; everything it does beyond `process.send`
+// plumbing is here, behind an injectable transport — so the tests run a
+// real pane (module, root, window, props, callbacks, close handlers) in
+// process, over a loopback pair, against the in-process X server. The fork
+// boundary itself is the only thing this seam cannot cover, and the only
+// thing the forked entry adds.
+//
+// Order matters three times in this file:
+//
+//  - The **update listener goes up before the module import starts.** The
+//    import is the slow part of booting a pane, the parent sends updates
+//    whenever its commits produce them, and a listener scoped to the
+//    mounted tree would drop everything that arrived in between. So the
+//    listener is a store the tree subscribes to later: the last update
+//    always wins, however early it came.
+//
+//  - The module is imported **before** the root is created. A `src` that
+//    does not resolve is the commonest way a frame fails, and failing it
+//    should not cost an X connection — or worse, report a connection error
+//    when the truth is a typo in a path.
+//
+//  - `ready` is sent only once the pane's window has an id, which is after
+//    the commit that realizes it. The parent embeds on `ready`; an id sent
+//    early would have the embedder reparenting a window that does not
+//    exist.
+//
+// The window is `<window embeddable>`: created unmapped, because a window
+// waiting to be embedded is unmapped — that is what waiting looks like —
+// and the embedder maps it once it is reparented (ntk's XEmbedSocket).
+
+import { isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import React, { useEffect, useMemo, useRef, useSyncExternalStore } from 'react';
+
+import { createRoot } from '../index.js';
+import { windowIdOf } from '../windowid.js';
+import { registeredFrameContext } from './env.js';
+import { markFramed, runCloseHandlers } from './lifecycle.js';
+import { PROTOCOL, reviveCallbacks } from './protocol.js';
+
+const h = React.createElement;
+
+/**
+ * @typedef {object} ChildTransport The child's end of the wire.
+ * @property {(msg: object) => void} send
+ * @property {(cb: (msg: object) => void) => () => void} onMessage
+ * @property {(cb: () => void) => () => void} onDisconnect the parent's end
+ *   closed — there is nobody left to talk to
+ */
+
+/** Recreate the bridged providers around the pane's window, outermost
+ * first — the parent's own nesting order, which the env Map records and
+ * structured clone preserves. A key the pane never registered wraps
+ * nothing: no module in this process reads it. Providers registered
+ * `innermost` (the theme) wrap directly around the window, inside the
+ * rest — see registerFrameProvider (src/frame/env.js) for why the
+ * adjacency matters. */
+function wrapEnv(env, inner) {
+  const wrap = (tree, [key, value]) => {
+    const registered = registeredFrameContext(key);
+    if (!registered) return tree;
+    return registered.render
+      ? registered.render(value, tree)
+      : h(
+          registered.Context.Provider,
+          { value: registered.revive ? registered.revive(value) : value },
+          tree,
+        );
+  };
+  const entries = [...env];
+  const isInnermost = ([key]) =>
+    registeredFrameContext(key)?.innermost === true;
+  let tree = inner;
+  for (const entry of entries.filter(isInnermost).reverse()) {
+    tree = wrap(tree, entry);
+  }
+  for (const entry of entries.filter((e) => !isInnermost(e)).reverse()) {
+    tree = wrap(tree, entry);
+  }
+  return tree;
+}
+
+function Bridge({ Component, store, rect, invoke, onReady }) {
+  const wire = useSyncExternalStore(
+    (cb) => {
+      store.listeners.add(cb);
+      return () => store.listeners.delete(cb);
+    },
+    () => store.value,
+  );
+  const snapshot = useMemo(
+    () => ({
+      props: reviveCallbacks(wire.props ?? {}, invoke),
+      env: new Map(wire.env ?? []),
+    }),
+    [wire, invoke],
+  );
+  const ref = useRef(null);
+
+  // The window realizes in the commit this effect follows — but `ready`
+  // must carry its id, so a beat where the ref is still empty retries on a
+  // fresh task rather than reporting a pane with no window.
+  useEffect(() => {
+    let cancelled = false;
+    const report = (tries) => {
+      if (cancelled) return;
+      const windowId = windowIdOf(ref);
+      if (windowId) onReady(windowId);
+      else if (tries > 0) setTimeout(() => report(tries - 1), 10);
+      else onReady(null);
+    };
+    report(200);
+    return () => {
+      cancelled = true;
+    };
+  }, [onReady]);
+
+  // The bridged providers wrap the *window*, not the pane component — the
+  // same position they held in the host. ThemeProvider plants the palette
+  // on a window it finds among its children (theme.js, `planted`), and the
+  // window is where it has to land: the window's own background follows the
+  // palette, and it is the top of the node tree every `$token` beneath
+  // resolves through. Mounted inside the window, the palette reached a box
+  // and the window kept resolving against the pane process's own desktop —
+  // a dark-desktop pane in a light-themed app, wrong in both directions.
+  return wrapEnv(
+    snapshot.env,
+    h(
+      'window',
+      {
+        ref,
+        embeddable: true,
+        width: Math.max(1, rect?.width ?? 400),
+        height: Math.max(1, rect?.height ?? 300),
+      },
+      h(Component, snapshot.props),
+    ),
+  );
+}
+
+/**
+ * Run the pane: handshake, load `src`, mount its default export, follow
+ * updates, and exit when told to (or when the parent goes away).
+ *
+ * `exit` and `rootOptions` are the test seams: a test passes a loopback
+ * transport, a borrowed in-process connection (`rootOptions.app`) and an
+ * `exit` that resolves instead of killing the runner.
+ */
+export async function runFrameChild(transport, options = {}) {
+  const {
+    exit = (code) => process.exit(code),
+    rootOptions,
+    // The pane process's last resort: an async throw nothing else caught is
+    // reported before the exit it forces. Off in the in-process tests,
+    // where "the process" is the test runner and trapping its errors would
+    // convert a failing test into a politely-reported pane crash.
+    trapProcessErrors = true,
+  } = options;
+
+  const fatal = (phase, err) => {
+    try {
+      transport.send({
+        type: 'fatal',
+        phase,
+        message: err?.message ?? String(err),
+        stack: err?.stack,
+      });
+    } catch {
+      // the channel is gone; the exit code still says what happened
+    }
+    console.error(`react-x11 frame pane (${phase}):`, err);
+    exit(1);
+  };
+
+  if (trapProcessErrors) {
+    process.on('uncaughtException', (err) => fatal('runtime', err));
+    process.on('unhandledRejection', (err) => fatal('runtime', err));
+  }
+  markFramed();
+
+  const hello = await new Promise((resolve) => {
+    const off = transport.onMessage((msg) => {
+      if (msg?.type !== 'hello') return;
+      off();
+      resolve(msg);
+    });
+  });
+  if (hello.protocol !== PROTOCOL) {
+    return fatal(
+      'handshake',
+      new Error(
+        `frame protocol ${hello.protocol} from the host, ${PROTOCOL} here — ` +
+          'host and pane are running different react-x11 versions',
+      ),
+    );
+  }
+
+  // From here every update is kept, mounted tree or not: last one wins.
+  const store = {
+    value: { props: hello.props ?? {}, env: hello.env ?? [] },
+    listeners: new Set(),
+  };
+  transport.onMessage((msg) => {
+    if (msg?.type !== 'update') return;
+    store.value = { props: msg.props ?? {}, env: msg.env ?? [] };
+    for (const listener of [...store.listeners]) listener();
+  });
+
+  let Component;
+  try {
+    const url = isAbsolute(hello.src)
+      ? pathToFileURL(hello.src).href
+      : hello.src;
+    const mod = await import(url);
+    Component = mod.default;
+    if (typeof Component !== 'function' && typeof Component !== 'object') {
+      throw new Error(`${hello.src} has no default export to mount`);
+    }
+  } catch (err) {
+    return fatal('load', err);
+  }
+
+  let root;
+  try {
+    root = await createRoot({
+      ...(hello.display ? { display: hello.display } : {}),
+      ...rootOptions,
+      onUncaughtError: (err) => fatal('runtime', err),
+    });
+  } catch (err) {
+    return fatal('connect', err);
+  }
+
+  let closing = false;
+  const close = async () => {
+    if (closing) return;
+    closing = true;
+    try {
+      await runCloseHandlers();
+      await root.unmount();
+    } catch {
+      // exiting is the point; nothing downstream of it to protect
+    }
+    exit(0);
+  };
+
+  transport.onMessage((msg) => {
+    if (msg?.type === 'unmount') close();
+  });
+  transport.onDisconnect(close);
+
+  root.render(
+    h(Bridge, {
+      Component,
+      store,
+      rect: hello.rect,
+      invoke: (id, args) => {
+        try {
+          transport.send({ type: 'invoke', id, args });
+        } catch {
+          // the host is going away; its shutdown handles the rest
+        }
+      },
+      onReady: (windowId) => {
+        if (windowId) transport.send({ type: 'ready', windowId });
+        else fatal('runtime', new Error('the pane window never realized'));
+      },
+    }),
+  );
+
+  return { root, close };
+}

package/src/frame/env.js

@@ -0,0 +1,140 @@
+// The frame environment: which context values cross into a `<Frame>`.
+//
+// React context cannot cross a process boundary — a context object is
+// process-local, and React has no API for enumerating "the providers above
+// this node". Both halves of that problem are answered here with one
+// structure:
+//
+//  - **Identity** is a string key plus a module both sides import. A pane's
+//    components read a context by importing the module that created it, and
+//    creating it (`createFrameContext`) is what registers it — so by the
+//    time the child bridge has a value to recreate, the context it belongs
+//    to is in the registry *by construction*. A key that arrives with no
+//    registration means the pane never imported the module, which means
+//    nothing in the pane reads it: skipped, silently.
+//
+//  - **Enumeration** is an accumulator: every bridging provider also merges
+//    its value into `FrameEnv`, a single internal context holding a
+//    `Map(key → value)`. `<Frame>` reads that one context at its own tree
+//    position and gets exactly the values an in-process child would have
+//    seen there — and re-renders when any of them changes, which is the
+//    entire subscription mechanism. Map insertion order is the parent's
+//    provider nesting order (outermost first), v8's structured clone
+//    preserves it, and the child recreates providers in that order.
+//
+// What deliberately does not cross: functions. Props run the callback
+// bridge because props are visible per-frame wiring; a context is ambient,
+// and bridging a `{ state, dispatch }` pair would hand live RPC stubs to
+// every pane under the provider — invisible IPC, with an unanswerable
+// question about which incarnation of a restarted child holds which stub.
+// A bridged value that fails structured clone is dropped with a warning
+// naming the key (src/frame/index.js), and dispatchers travel in `props`.
+//
+// The other line this file draws: bridge what the **app** defines, and let
+// each process resolve what the **desktop** defines. Appearance, locale,
+// desktop settings and fonts are read from the environment identically on
+// both sides of the boundary, so bridging them would only add a stale copy.
+// The theme is the one ambient thing the app authors, which is why
+// `ThemeProvider` publishes here by default (src/components/theme.js).
+
+import React, { useContext, useMemo } from 'react';
+
+const h = React.createElement;
+
+const EMPTY = new Map();
+
+/** `Map(key → serialized value)` of every bridged context above here. */
+export const FrameEnv = React.createContext(EMPTY);
+
+/** The env a `<Frame>` at this position would hand its child. */
+export function useFrameEnv() {
+  return useContext(FrameEnv);
+}
+
+/**
+ * key → how the child recreates the provider:
+ * `{ Context, revive }` from `createFrameContext`, or `{ render }` from
+ * `registerFrameProvider`. Last registration wins, which is what lets a
+ * hot-reloaded module re-register itself without a guard.
+ */
+const registry = new Map();
+
+/** The child bridge's lookup (src/frame/childmain.js). */
+export function registeredFrameContext(key) {
+  return registry.get(key) ?? null;
+}
+
+/**
+ * Register how the child side recreates `key` — for a provider that is more
+ * than `Context.Provider`, like `ThemeProvider`, which also plants the
+ * palette on a node so `$token` styles resolve. `render(value, children)`
+ * returns the wrapped element.
+ *
+ * `innermost: true` puts the provider directly around the pane's window,
+ * inside every other bridged provider. ThemeProvider needs the adjacency:
+ * it plants the palette on a window it finds among its *direct* children,
+ * and the window is where the palette must land — the window's own
+ * background follows it, and the node tree under it is what every `$token`
+ * resolves through. Plain context providers have no such constraint and
+ * keep the host's nesting order outside.
+ */
+export function registerFrameProvider(key, render, { innermost = false } = {}) {
+  registry.set(key, { render, innermost });
+}
+
+/**
+ * Publish one `key → value` into the frame environment. Used by
+ * `createFrameContext`'s Provider and by `ThemeProvider`; not part of the
+ * public API.
+ */
+export function EnvValue({ k, value, children }) {
+  const env = useContext(FrameEnv);
+  const next = useMemo(() => new Map(env).set(k, value), [env, k, value]);
+  return h(FrameEnv.Provider, { value: next }, children);
+}
+
+/**
+ * A React context whose value follows the app into its `<Frame>` panes.
+ *
+ * ```js
+ * // contexts.js — imported by the app *and* by the pane's components
+ * export const Session = createFrameContext('session', null);
+ *
+ * // app side
+ * <Session.Provider value={{ user, database }}>
+ *   <Frame src={paneUrl} … />
+ * </Session.Provider>
+ *
+ * // pane side — no wiring; the value was in force where the Frame stood
+ * const { user } = Session.use();
+ * ```
+ *
+ * In-process it is an ordinary context. Across a `<Frame>` the value is
+ * snapshotted with structured clone, sent with the frame's props, and
+ * recreated as a real Provider around the pane — one direction, data only.
+ *
+ * `key` names the value on the wire and must be unique per app;
+ * `serialize`/`revive` are for values structured clone cannot carry
+ * (a class instance), and default to identity.
+ */
+export function createFrameContext(key, defaultValue, options = {}) {
+  if (typeof key !== 'string' || key.length === 0) {
+    throw new Error('react-x11: createFrameContext needs a string key');
+  }
+  const { serialize, revive } = options;
+  const Context = React.createContext(defaultValue);
+  registry.set(key, { Context, revive });
+  function Provider({ value, children }) {
+    return h(
+      EnvValue,
+      { k: key, value: serialize ? serialize(value) : value },
+      h(Context.Provider, { value }, children),
+    );
+  }
+  return {
+    key,
+    Context,
+    Provider,
+    use: () => useContext(Context),
+  };
+}