react-x11 1.2.0 → 2.0.0

package/src/portal.js

@@ -0,0 +1,461 @@
+// xdg-desktop-portal: the shared machinery every portal-backed feature needs,
+// and nothing user-visible.
+//
+// A portal is a D-Bus API, not a widget. An app asks "the desktop" to run a
+// dialog *in another process* and hand back the answer — which is how a
+// sandboxed app gets a file picker it is not allowed to draw, and how a Qt app
+// on GNOME gets a GTK dialog with your bookmarks in it.
+//
+// ## The one thing that is easy to get wrong
+//
+// Every portal method that shows UI has the same shape: it returns an object
+// path **immediately** and answers later with a
+// `org.freedesktop.portal.Request.Response` signal. Subscribe after the call
+// returns and you can lose the answer — the dialog can be dismissed before
+// your match rule is in place.
+//
+// So the path is predictable *by design*. From the upstream
+// `org.freedesktop.portal.Request.xml`:
+//
+// > Since version 0.9 of xdg-desktop-portal, the handle will be of the form
+// > `/org/freedesktop/portal/desktop/request/SENDER/TOKEN` where SENDER is the
+// > callers unique name, with the initial ':' removed and all '.' replaced by
+// > '_' […] This change was made to let applications subscribe to the Response
+// > signal before making the initial portal call, thereby avoiding a race
+// > condition.
+//
+// `portalRequest()` is that subscribe-then-call, written once, so every portal
+// added later is a method name and an options dict rather than a race to
+// re-solve.
+
+import { loadTransport, sessionBus } from './bus.js';
+
+export const PORTAL_NAME = 'org.freedesktop.portal.Desktop';
+export const PORTAL_PATH = '/org/freedesktop/portal/desktop';
+const REQUEST_IFACE = 'org.freedesktop.portal.Request';
+
+/** The portal answered; `response` is what it means. */
+export const RESPONSE_OK = 0;
+export const RESPONSE_CANCELLED = 1;
+export const RESPONSE_ENDED = 2;
+
+/**
+ * There is no portal here — no bus, no service, or a version too old for what
+ * was asked. A **typed** rejection rather than a crash: it is the signal that
+ * a caller should fall back to something it can draw itself, which is exactly
+ * what the file dialog does.
+ */
+export class NoPortalError extends Error {
+  constructor(message, cause) {
+    super(`react-x11: ${message}`, { cause });
+    this.name = 'NoPortalError';
+  }
+}
+
+/** The user closed the dialog, or the desktop ended the request some other way. */
+export class PortalCancelledError extends Error {
+  constructor(response = RESPONSE_CANCELLED) {
+    super(
+      response === RESPONSE_CANCELLED
+        ? 'react-x11: the portal dialog was cancelled'
+        : 'react-x11: the portal request ended without an answer',
+    );
+    this.name = 'PortalCancelledError';
+    /** 1 when the user cancelled, 2 when it ended some other way. */
+    this.response = response;
+  }
+}
+
+/**
+ * `':1.42'` → `'1_42'`.
+ *
+ * The transform is three characters of code and the whole reason the Request
+ * race is avoidable, so it is named and tested rather than inlined.
+ */
+export const senderPath = (uniqueName) =>
+  uniqueName.replace(/^:/, '').replaceAll('.', '_');
+
+/**
+ * A token that is a legal object-path element and not guessable — the XML asks
+ * for "a per-library prefix combined with a random number", so: ours plus
+ * eight random bytes.
+ */
+async function newToken() {
+  const { randomBytes } = await import('node:crypto');
+  return `rx11_${randomBytes(8).toString('hex')}`;
+}
+
+// --------------------------------------------------------------------------
+// hasService
+// --------------------------------------------------------------------------
+
+/**
+ * Cache per bus generation. `NameOwnerChanged` would invalidate it precisely;
+ * a portal appearing mid-session is rare enough that the cheap version — cache
+ * only the *positive* answer — is the honest trade. A false negative that
+ * cached would be the bug (a feature disabled for the life of the process),
+ * and this cannot produce one.
+ */
+const reachable = new Map();
+
+/**
+ * Is `name` reachable — owned right now, **or activatable on demand**?
+ *
+ * `NameHasOwner` alone is the wrong question and gets this wrong on a healthy
+ * desktop. `org.freedesktop.portal.Desktop` ships a D-Bus service file:
+ *
+ *     [D-BUS Service]
+ *     Name=org.freedesktop.portal.Desktop
+ *     Exec=…/xdg-desktop-portal
+ *
+ * so on a GNOME session where no app has touched a portal yet the name has no
+ * owner and would answer *false* — and a feature gated on it takes the
+ * fallback path forever, on a machine where the portal works perfectly.
+ */
+export async function hasService(name, busRef) {
+  if (reachable.get(name)) return true;
+  const ref = busRef ?? (await sessionBus());
+  if (!ref) return false;
+  try {
+    const [owned, activatable] = await Promise.all([
+      ref.bus.listNames(),
+      ref.bus.listActivatableNames().catch(() => []),
+    ]);
+    const found = owned.includes(name) || activatable.includes(name);
+    if (found) reachable.set(name, true);
+    return found;
+  } catch {
+    return false;
+  } finally {
+    if (!busRef) await ref.release();
+  }
+}
+
+/** Test seam, not public: forget what was learned about the bus. */
+export function _resetServiceCache() {
+  reachable.clear();
+  versions.clear();
+}
+
+// --------------------------------------------------------------------------
+// portalVersion
+// --------------------------------------------------------------------------
+
+/**
+ * Positive answers only, like {@link hasService}'s cache and for the same
+ * reason: a version can only move by the portal restarting, which is rare
+ * enough to ignore, while a cached "not there" would disable a feature for
+ * the life of the process on a machine where the portal appears one call
+ * later.
+ */
+const versions = new Map();
+
+/**
+ * The version of one portal *interface*, or `0` when it is not there.
+ *
+ * `hasService()` answers a different question. The portal service being
+ * reachable says nothing about which interfaces its backends provide —
+ * XFCE's portal has no `Screenshot` interface at all, and a GNOME old enough
+ * has it at version 1, before `PickColor` existed. Capability lives in the
+ * interface's own `version` property, so gating a feature means reading it:
+ *
+ * ```js
+ * if ((await portalVersion('org.freedesktop.portal.Screenshot', ref)) >= 2) {
+ *   // PickColor is there
+ * }
+ * ```
+ *
+ * `0` collapses "no bus", "no portal", "no such interface" and "no version
+ * property" into one answer, because every caller would branch the same way
+ * on all four.
+ */
+export async function portalVersion(iface, busRef) {
+  const cached = versions.get(iface);
+  if (cached !== undefined) return cached;
+  const ref = busRef ?? (await sessionBus());
+  if (!ref) return 0;
+  try {
+    const value = await ref.bus.invoke(
+      {
+        destination: PORTAL_NAME,
+        path: PORTAL_PATH,
+        interface: 'org.freedesktop.DBus.Properties',
+        member: 'Get',
+        signature: 'ss',
+        body: [iface, 'version'],
+      },
+      { timeout: 10_000 },
+    );
+    // dbus-native unwraps the `v` reply to its value.
+    const version = typeof value === 'number' && value > 0 ? value : 0;
+    if (version > 0) versions.set(iface, version);
+    return version;
+  } catch {
+    // `org.freedesktop.DBus.Error.InvalidArgs` — the portal is there and the
+    // interface is not, which is XFCE today for Screenshot. Or no portal at
+    // all. The caller's branch is the same either way.
+    return 0;
+  } finally {
+    if (!busRef) await ref.release();
+  }
+}
+
+// --------------------------------------------------------------------------
+// The Request helper
+// --------------------------------------------------------------------------
+
+/**
+ * Call a portal method that answers through a `Request`, with the
+ * subscription already in place before the call goes out.
+ *
+ * ```js
+ * const { response, results } = await portalRequest(ref, {
+ *   iface: 'org.freedesktop.portal.FileChooser',
+ *   member: 'OpenFile',
+ *   parentWindow: 'x11:1a00007',
+ *   title: 'Open',
+ *   options: { multiple: true },
+ * });
+ * ```
+ *
+ * The default argument shape is FileChooser's, `(s parent_window, s title,
+ * a{sv} options)` — but that shape is FileChooser's alone. Every other portal
+ * that answers through a `Request` has its own leading arguments
+ * (`Screenshot.PickColor` has no title, `Print` carries a serial, …), so a
+ * caller states them, as `signature` and `args` together:
+ *
+ * ```js
+ * await portalRequest(ref, {
+ *   iface: 'org.freedesktop.portal.Screenshot',
+ *   member: 'PickColor',
+ *   signature: 'sa{sv}',
+ *   args: [parentWindow],
+ * });
+ * ```
+ *
+ * `signature` is the method's full argument signature and must end in
+ * `a{sv}` — the options dict is where `handle_token` rides, so a method
+ * without one cannot be Request-shaped. `args` is everything before it;
+ * the options dict itself stays in `options` and is appended here.
+ *
+ * Three things it owns, so that no caller reimplements them:
+ *
+ * - **Cancellation.** An `AbortSignal` calls `Request.Close()` on the same
+ *   path. Per the XML that means **no `Response` is emitted**, so the promise
+ *   has to be settled here rather than left waiting for one. The listener goes
+ *   on **before the first await**, because `addEventListener('abort')` on a
+ *   signal that has already fired never runs: an abort that lands while
+ *   `AddMatch` or the initial call is still in flight would otherwise be
+ *   dropped, leaving a promise nothing can settle and a dialog on screen with
+ *   nobody listening — the exact leak this is here to prevent.
+ * - **Deadlines.** There is deliberately **no timeout on the answer** — a
+ *   dialog can legitimately be open for an hour, which is the whole reason
+ *   portals are request-shaped instead of plain calls. Only the initial method
+ *   call gets a short one: a portal that does not hand back a handle in a few
+ *   seconds is not there.
+ * - **A pre-0.9 portal** that returns an unpredictable path. Cheap insurance:
+ *   re-subscribe on whatever came back.
+ *
+ * @param {{ bus: any, uniqueName: string }} busRef
+ * @returns {Promise<{ response: number, results: object }>}
+ */
+export async function portalRequest(
+  busRef,
+  {
+    iface,
+    member,
+    parentWindow = '',
+    title = '',
+    signature,
+    args,
+    options = {},
+    signal,
+  },
+) {
+  // They travel as a pair: the signature says what the args are, and either
+  // half alone is a call that marshals wrong at the far end with no error
+  // anywhere near the mistake.
+  if ((signature === undefined) !== (args === undefined)) {
+    throw new Error(
+      `react-x11: portalRequest(${iface}.${member}) got ` +
+        `${signature === undefined ? '`args` without `signature`' : '`signature` without `args`'}` +
+        " — they describe each other, so pass both (e.g. signature: 'sa{sv}'," +
+        ' args: [parentWindow]), or neither for the FileChooser shape.',
+    );
+  }
+  if (signature === undefined) {
+    signature = 'ssa{sv}';
+    args = [parentWindow, title];
+  } else if (!signature.endsWith('a{sv}')) {
+    throw new Error(
+      `react-x11: portalRequest(${iface}.${member}) — the signature ` +
+        `'${signature}' does not end in the options dict (a{sv}). ` +
+        'handle_token rides in that dict, so a method without one does not ' +
+        'answer through a Request; call bus.invoke directly instead.',
+    );
+  }
+
+  const { bus, uniqueName } = busRef;
+  const token = await newToken();
+  const path = `${PORTAL_PATH}/request/${senderPath(uniqueName)}/${token}`;
+
+  if (signal?.aborted) throw signal.reason ?? new PortalCancelledError();
+
+  const subscribe = async (requestPath) => {
+    const sub = await bus.watch(
+      `type='signal',sender='${PORTAL_NAME}',` +
+        `interface='${REQUEST_IFACE}',member='Response',path='${requestPath}'`,
+    );
+    const key = bus.mangle(requestPath, REQUEST_IFACE, 'Response');
+    return { sub, key };
+  };
+
+  const closeRequest = (requestPath) =>
+    bus
+      .invoke({
+        destination: PORTAL_NAME,
+        path: requestPath,
+        interface: REQUEST_IFACE,
+        member: 'Close',
+        signature: '',
+        body: [],
+      })
+      .catch(() => {
+        // The request may already be gone — that is the outcome we wanted.
+      });
+
+  // The abort wiring, before anything that can suspend. `sent` is the guard on
+  // Close(): there is no request to close until the call has actually gone out,
+  // and the path the portal will answer on is the predictable one from here
+  // until a pre-0.9 portal says otherwise.
+  let sent = false;
+  let requestPath = path;
+  /** The path the abort actually closed, if it has fired. */
+  let closedPath = null;
+  let onAbort;
+  let aborted;
+  if (signal) {
+    aborted = new Promise((_, reject) => {
+      onAbort = () => {
+        if (sent) {
+          closedPath = requestPath;
+          closeRequest(requestPath);
+        }
+        reject(signal.reason ?? new PortalCancelledError());
+      };
+      signal.addEventListener('abort', onAbort, { once: true });
+    });
+    // Nothing awaits `aborted` until the races below, and an abort can land
+    // before then. Mark it handled so a rejection in that window is not an
+    // unhandled one; the races still see it.
+    aborted.catch(() => {});
+  }
+
+  // Subscribe FIRST. Everything else in this function is bookkeeping around
+  // the fact that this line comes before the invoke. It is not raced against
+  // the abort: a match rule half-added is a match rule leaked, so let it
+  // finish and let the `finally` below take it away again.
+  let { sub, key } = await subscribe(path);
+  const answered = new Promise((resolve) => {
+    // `bus.signals` emits the signal's argument array.
+    bus.signals.once(key, ([response, results]) =>
+      resolve({ response, results: results ?? {} }),
+    );
+  });
+
+  try {
+    // An abort during `AddMatch` above: nothing has been asked for yet, so
+    // there is nothing to Close — just leave, and let the `finally` unsubscribe.
+    if (signal?.aborted) throw signal.reason ?? new PortalCancelledError();
+
+    // `sent` flips *before* the await, not after: from the moment the call is
+    // on the wire the portal may already have a dialog up, and an abort in that
+    // window has to Close it even though no handle has come back yet.
+    sent = true;
+    const call = bus
+      .invoke(
+        {
+          destination: PORTAL_NAME,
+          path: PORTAL_PATH,
+          interface: iface,
+          member,
+          signature,
+          body: [...args, { ...options, handle_token: token }],
+        },
+        { timeout: 10_000 },
+      )
+      // Settled either way, so that an abort winning the race below does not
+      // leave this one rejecting into nobody's hands.
+      .then(
+        (handle) => ({ handle }),
+        (cause) => ({ cause }),
+      );
+
+    // A pre-0.9 portal that picks its own path is the one case where an abort
+    // that beat the reply closed the wrong one — and which path it really was
+    // is not knowable until the handle arrives, quite possibly after this
+    // function has already rejected.
+    call.then(({ handle }) => {
+      if (closedPath && typeof handle === 'string' && handle !== closedPath) {
+        closeRequest(handle);
+      }
+    });
+
+    const { handle, cause } = await Promise.race([call, aborted ?? call]);
+    if (cause)
+      throw new NoPortalError(`${iface}.${member} did not answer`, cause);
+
+    // Pre-0.9 portals chose their own path. Re-subscribe on the real one; the
+    // first subscription stays until the finally below, which is cheaper than
+    // getting the ordering wrong.
+    if (typeof handle === 'string' && handle !== path) {
+      requestPath = handle;
+      const moved = await subscribe(handle);
+      bus.signals.once(moved.key, ([response, results]) => {
+        bus.signals.emit(key, [response, results]);
+      });
+      sub = { remove: () => Promise.all([sub.remove(), moved.sub.remove()]) };
+    }
+
+    // `Close()` produces no Response, so the abort has to settle the race
+    // itself rather than wait for one that will never arrive.
+    return await Promise.race([answered, aborted ?? answered]);
+  } finally {
+    if (onAbort) signal.removeEventListener('abort', onAbort);
+    await sub.remove().catch(() => {});
+  }
+}
+
+/**
+ * A `parent_window` handle for the portal, or `''` when there is no window to
+ * name — which is legal and just means the dialog floats.
+ *
+ * Lowercase hex, no `0x`. Both shipping backends tolerate a prefix, which is
+ * precisely why it is easy to get wrong and never notice; Qt's parser answers
+ * 0 on failure with no error path, so a third backend would silently give an
+ * unparented, non-modal dialog rather than throw.
+ */
+export function parentWindowHandle(xid) {
+  return typeof xid === 'number' && xid > 0 ? `x11:${xid.toString(16)}` : '';
+}
+
+/**
+ * `Variant`, from the one copy of the transport the bus layer loaded.
+ *
+ * Needed for the option types inference cannot produce — `a(sa(us))` for
+ * filters, `u` where a plain number would marshal as `i`.
+ */
+export async function variant(signature, value) {
+  const dbus = await loadTransport();
+  return new dbus.Variant(signature, value);
+}
+
+/**
+ * A NUL-terminated byte array, which is how the FileChooser portal spells a
+ * path in its options (`current_folder`, `current_file`). A plain string there
+ * marshals as `s` and the backend ignores it — silently, which is the failure
+ * mode worth writing a helper to avoid.
+ */
+export function pathBytes(value) {
+  return Buffer.from(`${value}\0`, 'utf8');
+}

package/src/priority.js

@@ -27,6 +27,32 @@ export function resolveUpdatePriority() {
     : DefaultEventPriority;
 }
 
+// The renderer's `flushSyncWork`, registered by Reconciler.js when it builds
+// the reconciler. The dispatcher needs it and cannot import the Reconciler
+// back without a cycle, and there is only ever one reconciler per process.
+let syncFlush = null;
+
+export function setSyncFlush(fn) {
+  syncFlush = fn;
+}
+
+/**
+ * Land every discrete-priority update React is holding, now.
+ *
+ * `scheduleMicrotask` in the host config is what makes this necessary: a
+ * sync-lane update is committed in a microtask, so an event handler that has
+ * returned has *not* yet seen React's half of its own response. Painting
+ * before this ran would show the default action's half — the `:active` flip,
+ * the caret — and leave React's to the next frame, which is both a frame
+ * late and a second paint.
+ *
+ * A no-op when there is nothing pending, and when React is already rendering
+ * or committing (`flushSyncWork` checks its own execution context).
+ */
+export function flushSyncWork() {
+  syncFlush?.();
+}
+
 /** Run fn (an event handler batch) at the given update priority. */
 export function runWithPriority(priority, fn) {
   const previous = currentUpdatePriority;

package/src/refresh/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `react-x11/refresh` — the runtime half of state-preserving hot reload.
+ * Run the app under the loader (`node --import react-x11/refresh/register`)
+ * and import from here only for the two seams below.
+ */
+
+/** One applied hot-reload batch. */
+export interface ReloadEvent {
+  /** Canonical URLs of the refresh-boundary modules that re-evaluated. */
+  urls: string[];
+  /** False when the batch left no component updates to apply. */
+  refreshed: boolean;
+}
+
+/**
+ * Called after each hot-reload batch has re-rendered the edited
+ * components in place. Returns an unsubscribe function.
+ */
+export function onReload(listener: (event: ReloadEvent) => void): () => void;
+
+/** Apply pending component updates now. Returns null if nothing was pending. */
+export function performReactRefresh(): unknown;
+
+/**
+ * Internal surface for the loader's injected prelude/footer — reached as
+ * the default export because only default bindings initialize
+ * synchronously inside a hot module. Not part of the public API.
+ */
+declare const runtime: {
+  register(type: unknown, id: string): void;
+  createSignatureFunctionForTransform(): unknown;
+  moduleReady(
+    hot: unknown,
+    url: string,
+    exportsMap: Record<string, unknown> | null,
+  ): void;
+  performReactRefresh: typeof performReactRefresh;
+  onReload: typeof onReload;
+};
+export default runtime;

package/src/refresh/index.js

@@ -0,0 +1,122 @@
+// react-x11/refresh — the runtime half of state-preserving hot reload
+// (Fast Refresh). The loader half is ./loader.js; `react-x11/refresh/register`
+// wires both up for `node --import`. See docs/ecosystem/dev-tooling.md.
+//
+// Import order is what this module exists to own:
+//
+//   1. injectIntoGlobalHook must patch the DevTools global hook before any
+//      renderer registers with it — so the renderer import below is dynamic,
+//      after the patch;
+//   2. injectIntoDevTools hands the reconciler's internals (dev build:
+//      scheduleRefresh & friends) to the patched hook, which is how
+//      react-refresh learns to re-render mounted roots. It must run before
+//      the first commit or the root won't be tracked.
+//
+// A host app does not need to import this module at all: the loader injects
+// an import of it into every hot module's prelude, and the entry is itself a
+// hot module, so the patch always lands before the app's own imports
+// evaluate React or the renderer. Importing it explicitly is only for the
+// two exports — `onReload` and `performReactRefresh`.
+//
+// react-refresh/runtime lives in node_modules, outside the hot graph, so
+// every reloaded module registers into this one runtime instance.
+import RefreshRuntime from 'react-refresh/runtime';
+
+RefreshRuntime.injectIntoGlobalHook(globalThis);
+
+const ReactX11 = await import('../index.js');
+// no argument: react-reconciler 0.33 takes none, and the renderer metadata
+// comes from the host config in src/Reconciler.js
+ReactX11.Renderer.injectIntoDevTools();
+
+const listeners = new Set();
+
+/**
+ * Called after a hot-reload batch has been applied: the edited components
+ * have re-rendered in place. The seam a dev tool sits on — log the reload,
+ * clear an error state, update a workbench UI. Returns an unsubscribe.
+ */
+export function onReload(listener) {
+  if (typeof listener !== 'function') {
+    throw new TypeError(
+      `react-x11/refresh: onReload takes a function, got ${typeof listener}.`,
+    );
+  }
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** Manual seam: apply pending component updates now. null = nothing pending. */
+export function performReactRefresh() {
+  return RefreshRuntime.performReactRefresh();
+}
+
+// A reload batch re-evaluates each module along the changed → accepting
+// path as a separate dynamic import, and an editor save can fire the file
+// watcher more than once — so the refresh is debounced. The delay is
+// imperceptible next to the save itself; what it buys is one re-render and
+// one onReload event per save instead of one per module.
+const REFRESH_DEBOUNCE_MS = 30;
+const pendingUrls = new Set();
+let pendingTimer = null;
+
+function flushRefresh() {
+  pendingTimer = null;
+  const urls = [...pendingUrls];
+  pendingUrls.clear();
+  const result = RefreshRuntime.performReactRefresh();
+  const event = { urls, refreshed: result !== null };
+  for (const listener of [...listeners]) {
+    try {
+      listener(event);
+    } catch (err) {
+      console.error('react-x11/refresh: onReload listener threw', err);
+    }
+  }
+}
+
+// The loader's injected footer calls this at the end of every hot module's
+// evaluation, handing over the module's exported values (or null when the
+// exports cannot all be named statically — re-exports, an anonymous
+// default). A module whose exports are all components is a refresh
+// boundary: it self-accepts, so an edit to it (or to anything below it
+// with no boundary of its own) re-evaluates up to here and no further,
+// and the re-evaluation schedules the refresh. Anything else stays
+// un-accepted and the change propagates to the nearest boundary above.
+function moduleReady(hot, url, exportsMap) {
+  const boundary =
+    exportsMap !== null &&
+    Object.values(exportsMap).every((value) =>
+      RefreshRuntime.isLikelyComponentType(value),
+    );
+  if (boundary) {
+    hot.accept();
+  } else {
+    // The hot context survives reloads, so an edit that adds a
+    // non-component export must also retract the acceptance the previous
+    // version registered — otherwise importers keep stale values forever.
+    // hot-module-replacement has no public un-accept, hence the field.
+    hot._selfAccepted = false;
+  }
+  const busted = /\?hmr=\d+$/.test(url);
+  if (boundary && busted) {
+    pendingUrls.add(url.replace(/\?hmr=\d+$/, ''));
+    if (pendingTimer) clearTimeout(pendingTimer);
+    pendingTimer = setTimeout(flushRefresh, REFRESH_DEBOUNCE_MS);
+  }
+}
+
+// The injected prelude and footer reach everything through this default
+// export: inside a hot module, named imports are rewritten to live
+// bindings that initialize in a microtask, and module-scope code runs
+// before that — only the default binding is initialized synchronously.
+export default {
+  register(type, id) {
+    RefreshRuntime.register(type, id);
+  },
+  createSignatureFunctionForTransform:
+    RefreshRuntime.createSignatureFunctionForTransform,
+  moduleReady,
+  performReactRefresh,
+  onReload,
+};

package/src/refresh/loader.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `react-x11/refresh/loader` — the loader half of state-preserving hot
+ * reload. `react-x11/refresh/register` calls registerRefresh() with the
+ * defaults; a tool that needs the seams writes its own --import module.
+ */
+
+export interface RefreshOptions {
+  /** File extensions treated as hot modules. Default: ['.jsx']. */
+  extensions?: string[];
+  /**
+   * Keep additional modules out of the hot graph (identity that must
+   * survive a reload: contexts, stores). node_modules and react-x11's own
+   * sources are always excluded.
+   */
+  ignore?: (path: string) => boolean;
+  /**
+   * Only 'classic' is supported: the automatic runtime injects an import
+   * that breaks under the hot-module import rewrite. Passing anything
+   * else throws.
+   */
+  jsxRuntime?: 'classic';
+  /**
+   * Extra statements injected into every hot module, one statement per
+   * entry — an entry holding two statements or a newline throws.
+   */
+  prelude?: string[];
+}
+
+/** Register the loader + hot-module hooks. Once per process. */
+export function registerRefresh(options?: RefreshOptions): Promise<void>;
+
+/** The transform alone, for a tool hosting its own module hooks. */
+export function createTransformer(options?: RefreshOptions): Promise<{
+  preludeLineCount: number;
+  matches(pathname: string): boolean;
+  transform(source: string, filename: string): { code: string };
+}>;