@shenora/react 0.10.0 → 0.12.0

package/README.md

@@ -1,165 +1,152 @@
-# @shenora/react
-
-React client for [Shenora](https://github.com/JiarongGu/Shenora) desktop hosts (.NET + WinForms +
-WebView2). The typed bridge between a React frontend and the Shenora host: correlated `invoke`
-with timeouts and structured errors, the event hub host notifications stream into, typed module
-services, React hooks, and a pluggable transport with a browser fallback so the UI can be
-developed in a plain browser. Headless by design — no UI components, bring your own design
-system. Versioned in lockstep with the `Shenora.*` NuGet packages.
-
-```ts
-import {
-  getBridge, useShenoraEvent, useShenoraQuery, BaseModuleService, createShenoraStore,
-} from '@shenora/react';
-
-// Once at startup, after your listeners are attached: it starts notification delivery (anything the
-// host buffered arrives in the first batch). Drop zones need no particular ordering against it — the
-// host clears them when a new DOCUMENT loads, not on this handshake.
-await getBridge().notifyReady();
-
-// a typed service per backend module:
-interface NoteRequests { GET_ALL: void; ADD: { title: string } }
-class NoteService extends BaseModuleService<NoteRequests> {
-  constructor() { super('NOTES'); }
-  getAll() { return this.send<Note[]>('GET_ALL'); }
-  add(title: string) { return this.send<Note>('ADD', { payload: { title } }); }
-}
-
-// in components:
-const { data, loading, refetch } = useShenoraQuery<Note[]>('NOTES', 'GET_ALL');
-useShenoraEvent<Note>('NOTES', 'ADDED', (note) => refetch());
-```
-
-Failed calls reject with `OperationError` — a structured `code` (an i18n key: translate
-`errors.{code}`) plus interpolation `parameters`, never raw host exception text.
-
-### Long-running work: post, then read a store
-
-`invoke` awaits a correlated reply and carries a timeout, and its handler's synchronous segment runs
-on the host's **UI thread** — so it is for calls that are quick and UI-thread-safe. Everything else
-posts and streams results back as events:
-
-```ts
-const useDeploy = createShenoraStore('DEPLOY', {
-  initial: { status: 'idle', lines: [] as string[] },
-  // Loaded on the FIRST subscriber, so a component that mounts mid-run isn't empty:
-  // events it missed cannot be replayed.
-  snapshot: { type: 'GET_STATE', apply: (s, d) => ({ ...s, ...(d as object) }) },
-  on: {
-    PROGRESS: (s, p: { line: string }) => ({ ...s, lines: [...s.lines, p.line] }),
-    ENDED: (s, p: { ok: boolean }) => ({ ...s, status: p.ok ? 'done' : 'failed' }),
-  },
-  actions: ({ post }) => ({ start: (cfg: unknown) => post('START', { payload: cfg }) }),
-});
-
-// any number of components share ONE subscription:
-const status = useDeploy((s) => s.status);
-useDeploy.actions.start({ env: 'prod' });
-```
-
-Use the **store for shared or long-lived state** and **`useShenoraEvent` for a one-off reaction in a
-single component**. A failed `post` has no promise to reject, so it is reported through the bridge's
-`onPostError` rather than vanishing — it is bridge-wide, so wire it once at startup
-(`getBridge()` takes no options):
-
-```ts
-configureBridge({ onPostError: (failure) => log.error(failure.module, failure.type, failure.error) });
-```
-
-### Tracked operations: a ready-made progress store
-
-For work the host tracks with `Shenora.Ipc`'s operation registry (an `IModuleContext.Run`/`Start`
-route on the C# side), `useShenoraOperations()` is a `createShenoraStore` instance built the same
-way as the example above — no per-feature event wiring needed:
-
-```ts
-import { useShenoraOperations } from '@shenora/react';
-
-const running = useShenoraOperations((s) => s.running);         // every in-flight operation
-const waiting = useShenoraOperations((s) => s.waiting);          // stopped, awaiting a decision — "needs you", one bucket
-const importJob = useShenoraOperations((s) => s.byId[jobId]);   // one, by id
-
-useShenoraOperations.actions.cancel(jobId);       // only does anything if the op opted into Cancellable
-useShenoraOperations.actions.dismiss(jobId);      // decline a waiting offer — refuses a running one
-useShenoraOperations.actions.wait(jobId);         // ASK the host to wait running work — refuses anything not running
-useShenoraOperations.actions.clearFinished();
-```
-
-`operation.progress` is an exported `OperationProgress` (`{ value: number; total?: number; unit?:
-string }`) — import the type rather than re-declaring the shape — the APP's own unit
-(bytes-of-a-known-total, items-of-a-known-total, an absolute count with no known total, or a genuine
-percent), never a kit-assumed percentage: `total` is the denominator when one is known and `undefined`
-when there isn't one, and `unit` is app-defined and uninterpreted, exactly like `kind`. The kit ships
-no percent helper — render a ratio only when you have a `total`:
-
-```ts
-import type { OperationProgress } from '@shenora/react';
-
-function format(progress?: OperationProgress): string {
-  if (!progress) return 'starting…';
-  return progress.total
-    ? `${Math.round((progress.value / progress.total) * 100)}%`
-    : `${progress.value}${progress.unit ? ` ${progress.unit}` : ''}`;   // no known total
-}
-```
-
-That division is your own policy, not the kit's, which is why it lives here instead of in `src/`.
-
-For the two events the store deliberately does NOT subscribe to — `OPERATION_RESUME_REQUESTED` and
-`OPERATION_WAIT_REQUESTED`, which target the OWNING module's service rather than this generic store —
-the module name and the event vocabulary are exported too, so you match by symbol and stay inside the
-host↔client mirror the wire tests pin:
-
-```ts
-import { OperationEventTypes, OperationModuleName, useShenoraEvent } from '@shenora/react';
-
-useShenoraEvent(OperationModuleName, OperationEventTypes.ResumeRequested, (payload) => …);
-```
-
-It snapshots via `LIST` on first subscribe (so a progress strip that mounts mid-run isn't empty), then
-folds `OPERATION_UPDATED` by id — one subscription however many components read it. The client
-mirrors the host's three bands (design §5A.2): `running` (Active), `waiting` (Waiting), and `finished`
-(Terminal). All three are derived from `byId` on every read, never a second copy to keep in sync —
-`waiting` is a single-status filter, exactly like `running`. `OperationStatus` carries ONE waiting
-value reached ONE way — the host's `IOperation.Wait` on a live operation — so there is no sub-case to
-tell apart. Filtering by your own `module`/`kind` is a plain `Array.filter` over any of them. A
-`waiting` operation carries `waitReason` — an app-defined string, like `kind`, OPTIONAL on the host
-side — for your UI to branch on. The host never prunes a waiting entry on its own: it stays until
-someone resumes, dismisses, or finishes it. `resume`/`dismiss`/`wait` are all fire-and-forget client
-requests — the host's own `IOperation.Wait`/`Resume` (called by whoever owns the operation, hearing
-`OPERATION_WAIT_REQUESTED`/`OPERATION_RESUME_REQUESTED`) is what actually changes the state; asking
-is not acting. `clearFinished`/`resume`/`wait` do not touch local state themselves at all: the host's
-`OPERATION_REMOVED { operationIds }` is the ONE authoritative removal signal the store folds, deleting
-exactly the named ids — `MaxHistory` eviction and `clearFinished`
-publish it, so a long-lived store's mirror of bounded host history cannot drift from what the host
-actually did (this replaced two hand-written optimistic local prunes that a past release carried —
-one of which was this project's only Critical, a `resume` prune that dropped a still-waiting row).
-`dismiss` never needed one, since the host's `Dismiss` publishes an ordinary terminal snapshot over
-the wire, the same as a real cancel. Use `createOperationsStore({ module, scope })` instead of the
-default export if your host renamed `OperationRegistryOptions.ModuleName` or
-you need a scope-filtered instance (a secondary window, an auxiliary session) — `clearFinished`
-forwards that scope so clearing history in one window cannot wipe another's.
-
-### Observing the whole stream
-
-`useShenoraEvent` and `createShenoraStore` listen for an exact `(module, type)`. When the vocabulary
-isn't knowable up front — plug-in-contributed events, a diagnostics tap, or an adoption shim keeping
-a legacy "every host message" handler alive while features migrate one at a time — subscribe broadly
-instead. Both mirror the host's `IEventBus` and return an unsubscribe:
-
-```ts
-const off = eventBus.subscribeToAll((event) => log.debug(event.module, event.type, event.payload));
-eventBus.subscribeToModule('DEPLOY', (event) => audit(event));   // every type from one module
-```
-
-Delivery is narrowest-first — exact pair, then module, then catch-all — so a broad observer never
-runs ahead of the feature code it is observing. Prefer `subscribe` when you know the pair: a
-catch-all wakes for every event on the bus.
-
-Pure-UI development in a plain browser: pass a `fallback` to `configureBridge` (gated behind
-`import.meta.env.DEV`) to answer requests with canned data. Other shells (WebSocket,
-mobile/Capacitor) implement the small `ShenoraTransport` seam and speak the same envelopes.
-For CDP-driven testing, `installDevInterceptor()` records IPC/event traffic into ring buffers
-and exposes `window.__shenora.call()/waitEvent()`.
-
-MIT © Jiarong Gu
+# @shenora/react
+
+React client for [Shenora](https://github.com/JiarongGu/Shenora) desktop hosts (.NET + WinForms +
+WebView2). The typed bridge between a React frontend and the Shenora host: correlated `invoke`
+with timeouts and structured errors, the event hub host notifications stream into, typed module
+services, React hooks, and a pluggable transport with a browser fallback so the UI can be
+developed in a plain browser. Headless by design — no UI components, bring your own design
+system. Versioned in lockstep with the `Shenora.*` NuGet packages.
+
+```ts
+import {
+  getBridge, useShenoraEvent, useShenoraQuery, BaseModuleService, createShenoraStore,
+} from '@shenora/react';
+
+// Once at startup, after your listeners are attached: it starts notification delivery (anything the
+// host buffered arrives in the first batch). Drop zones need no particular ordering against it — the
+// host clears them when a new DOCUMENT loads, not on this handshake.
+await getBridge().notifyReady();
+
+// a typed service per backend module:
+interface NoteRequests { GET_ALL: void; ADD: { title: string } }
+class NoteService extends BaseModuleService<NoteRequests> {
+  constructor() { super('NOTES'); }
+  getAll() { return this.send<Note[]>('GET_ALL'); }
+  add(title: string) { return this.send<Note>('ADD', { payload: { title } }); }
+}
+
+// in components:
+const { data, loading, refetch } = useShenoraQuery<Note[]>('NOTES', 'GET_ALL');
+useShenoraEvent<Note>('NOTES', 'ADDED', (note) => refetch());
+```
+
+Failed calls reject with `ShenoraError` — a structured `code` (an i18n key: translate
+`errors.{code}`) plus interpolation `parameters`, never raw host exception text.
+
+### Long-running work: post, then read a store
+
+`invoke` awaits a correlated reply and carries a timeout, and its handler's synchronous segment runs
+on the host's **UI thread** — so it is for calls that are quick and UI-thread-safe. Everything else
+posts and streams results back as events:
+
+```ts
+const useDeploy = createShenoraStore('DEPLOY', {
+  initial: { status: 'idle', lines: [] as string[] },
+  // Loaded on the FIRST subscriber, so a component that mounts mid-run isn't empty:
+  // events it missed cannot be replayed.
+  snapshot: { type: 'GET_STATE', apply: (s, d) => ({ ...s, ...(d as object) }) },
+  on: {
+    PROGRESS: (s, p: { line: string }) => ({ ...s, lines: [...s.lines, p.line] }),
+    ENDED: (s, p: { ok: boolean }) => ({ ...s, status: p.ok ? 'done' : 'failed' }),
+  },
+  actions: ({ post }) => ({ start: (cfg: unknown) => post('START', { payload: cfg }) }),
+});
+
+// any number of components share ONE subscription:
+const status = useDeploy((s) => s.status);
+useDeploy.actions.start({ env: 'prod' });
+```
+
+Use the **store for shared or long-lived state** and **`useShenoraEvent` for a one-off reaction in a
+single component**. A failed `post` has no promise to reject, so it is reported through the bridge's
+`onPostError` rather than vanishing — it is bridge-wide, so wire it once at startup
+(`getBridge()` takes no options):
+
+```ts
+configureBridge({ onPostError: (failure) => log.error(failure.module, failure.type, failure.error) });
+```
+
+### Requests in flight: a ready-made progress store
+
+Every request the host handles is tracked automatically — there is nothing to declare on either side.
+`useShenoraRequests()` is a `createShenoraStore` instance built the same way as the example above:
+
+```ts
+import { useShenoraRequests } from '@shenora/react';
+
+const running = useShenoraRequests((s) => s.running);           // every request still in flight
+const finished = useShenoraRequests((s) => s.finished);         // retained history, newest first
+const importJob = useShenoraRequests((s) => s.byId[requestId]); // one, by id
+
+useShenoraRequests.actions.cancel(requestId);   // XMLHttpRequest.abort() — the id you sent with
+useShenoraRequests.actions.clearFinished();
+```
+
+🔴 **The id is the one you already have.** `requestId` is the `id` of the request you sent — there is no
+second identity to correlate. Cancelling it targets the token the route is running under.
+
+⚠ **Most requests never appear here, and that is the design.** The host stays SILENT for the first
+50 ms (`IpcRequestTrackerOptions.GracePeriod`): a request that finishes inside that window emits no
+event at all — no running snapshot, no completion, nothing retained. So this store is a list of work
+that is actually *taking a while*, not a log of every call your page made. Nobody wants a spinner for
+five milliseconds of work, and the clock decides that at run time rather than a module author guessing
+at authoring time.
+
+`request.progress` is an exported `IpcProgress` (`{ value: number; total?: number; unit?: string }`) —
+import the type rather than re-declaring the shape. It is the APP's own unit (bytes of a known total,
+items of a known total, an absolute count with no known total, or a genuine percent), never a
+kit-assumed percentage: `total` is the denominator when one is known and `undefined` when there is
+none, and `unit` is app-defined and uninterpreted. The kit ships no percent helper — render a ratio
+only when you have a `total`:
+
+```ts
+import type { IpcProgress } from '@shenora/react';
+
+function format(progress?: IpcProgress): string {
+  if (!progress) return 'starting…';
+  return progress.total
+    ? `${Math.round((progress.value / progress.total) * 100)}%`
+    : `${progress.value}${progress.unit ? ` ${progress.unit}` : ''}`;   // no known total
+}
+```
+
+That division is your own policy, not the kit's, which is why it lives here instead of in `src/`.
+
+The store snapshots via `LIST` on first subscribe (so a progress strip that mounts mid-run is not
+empty), then folds `REQUEST_UPDATED` by id — one subscription however many components read it. Two
+bands, both derived from `byId` on every read: `running` and `finished`. Filtering by your own
+`module`/`type` is a plain `Array.filter` over either.
+
+`clearFinished` does not touch local state itself: the host's `REQUEST_REMOVED { requestIds }` is the
+one authoritative removal signal the store folds, deleting exactly the named ids. History eviction and
+`clearFinished` both publish it, so a long-lived store's mirror of bounded host history cannot drift
+from what the host actually did.
+
+⚠ **Work nobody requested does not belong here.** A scheduled job, a background sync, anything the host
+starts on its own — those have no request behind them and no response to wait for, so they report on
+their own event stream via `useShenoraEvent`. Squeezing them in here is what the previous design did,
+and it is why it needed a "waiting" state nothing else could explain.
+
+### Observing the whole stream
+
+`useShenoraEvent` and `createShenoraStore` listen for an exact `(module, type)`. When the vocabulary
+isn't knowable up front — plug-in-contributed events, a diagnostics tap, or an adoption shim keeping
+a legacy "every host message" handler alive while features migrate one at a time — subscribe broadly
+instead. Both mirror the host's `IEventBus` and return an unsubscribe:
+
+```ts
+const off = eventBus.subscribeToAll((event) => log.debug(event.module, event.type, event.payload));
+eventBus.subscribeToModule('DEPLOY', (event) => audit(event));   // every type from one module
+```
+
+Delivery is narrowest-first — exact pair, then module, then catch-all — so a broad observer never
+runs ahead of the feature code it is observing. Prefer `subscribe` when you know the pair: a
+catch-all wakes for every event on the bus.
+
+Pure-UI development in a plain browser: pass a `fallback` to `configureBridge` (gated behind
+`import.meta.env.DEV`) to answer requests with canned data. Other shells (WebSocket,
+mobile/Capacitor) implement the small `ShenoraTransport` seam and speak the same envelopes.
+For CDP-driven testing, `installDevInterceptor()` records IPC/event traffic into ring buffers
+and exposes `window.__shenora.call()/waitEvent()`.
+
+MIT © Jiarong Gu

package/dist/bridge.d.ts

@@ -6,7 +6,7 @@ export interface ShenoraBridgeOptions {
     /**
      * The channel to the host. Default: whichever Shenora host this page is in — WebView2 postMessage
      * on the desktop shell, `HybridWebView` on the MAUI shell — else null (plain browser). Supply your
-     * own for another shell (a WebSocket, D16) or a scripted fake for tests/preview harnesses.
+     * own for another shell, or a scripted fake for tests and preview harnesses.
      */
     transport?: ShenoraTransport | null;
     /** The event bus host notifications are unbundled into. Default: the shared bus. */
@@ -14,25 +14,23 @@ export interface ShenoraBridgeOptions {
     /** Per-request timeout in ms when the call doesn't set one. Family default: 30 000. */
     defaultTimeoutMs?: number;
     /**
-     * Pure-UI development seam: answers requests when NO transport exists (plain browser tab —
-     * component/layout work without the desktop host). Return the response data (or a promise;
-     * throw to reject). Generalized from the source app's hardcoded dev mocks: the mocks are app
-     * schema, so the app supplies them — gate with `import.meta.env.DEV` at the call site so
-     * production stays hard-failing.
+     * Pure-UI development seam: answers requests when NO transport exists (a plain browser tab).
+     * Return the response data, or a promise; throw to reject.
+     *
+     * ⚠ Gate the call site with `import.meta.env.DEV` so production stays hard-failing.
      */
     fallback?: (request: IpcRequest) => unknown;
     /**
      * Where a FAILED {@link ShenoraBridge.post} is reported. Default: `console.error`.
      *
-     * A one-way send has no promise to reject, so without this its failures would be invisible — and an
-     * unmatched response is dropped silently by the inbound handler, which is exactly how a feature
-     * "just stops working" with nothing to grep for. Route it into the app's logger/toast instead.
+     * ⚠ Route it into the app's logger or toast. A one-way send has no promise to reject, so its
+     * failures are otherwise invisible.
      */
     onPostError?: (error: PostFailure) => void;
     /**
      * How many unawaited {@link ShenoraBridge.post} ids to remember for error reporting. Default 256.
-     * Capped (drop-oldest) so a host that never answers cannot grow the set without bound — the same
-     * shape as the host's own bounded notification queue. Evicting an id only loses its error report.
+     * Capped drop-oldest, so a host that never answers cannot grow the set without bound; evicting an
+     * id only loses its error report.
      */
     maxTrackedPosts?: number;
 }
@@ -59,10 +57,10 @@ export interface PostOptions<TPayload = unknown> {
     scope?: string;
 }
 /**
- * The client side of the Shenora IPC contract, ported from the primary desktop sibling:
- * correlated request/response over a pluggable transport, category routing of host messages
- * (`ipc` → resolve the pending call, `notification` → unbundle the batch into the event bus),
- * per-request timeout, the ready handshake, and a browser fallback seam for pure-UI development.
+ * The client side of the Shenora IPC contract: correlated request/response over a pluggable
+ * transport, category routing of host messages (`ipc` → resolve the pending call, `notification` →
+ * unbundle the batch into the event bus), per-request timeout, the ready handshake, and a browser
+ * fallback seam for pure-UI development.
  *
  * Most apps use the lazy default instance via {@link getBridge}/{@link configureBridge}; create
  * instances directly for tests or multi-transport setups.
@@ -82,40 +80,29 @@ export declare class ShenoraBridge {
     constructor(options?: ShenoraBridgeOptions);
     /**
      * True when this bridge can actually send: a transport to a host exists AND the bridge has not been
-     * disposed. It used to ignore `disposed`, so a stale reference to a bridge that `configureBridge`
-     * replaced still reported itself available while every `invoke` on it rejected with `NO_TRANSPORT` —
-     * the exact case the disposed check in `invoke` exists for (P5.5 H2).
+     * disposed. The check to make on a reference that may have outlived a {@link configureBridge} swap.
      */
     get isAvailable(): boolean;
     /**
      * Send a request and await its typed response data. A failed response rejects with the
-     * structured {@link OperationError} (code + parameters); no response within the timeout
+     * structured {@link ShenoraError} (code + parameters); no response within the timeout
      * rejects with code `TIMEOUT`; no transport and no fallback rejects with `NO_TRANSPORT`.
      */
     invoke<TData = unknown, TPayload = unknown>(module: string, type: string, options?: InvokeOptions<TPayload>): Promise<TData>;
     /**
      * Send WITHOUT awaiting a reply, and return the request id.
      *
-     * This is the default shape for a desktop shell, and {@link invoke} is the special case — see
-     * `docs/DECISIONS.md` D23. Two reasons: a correlated call carries a deadline
-     * (30 s by default) and real work does not; and request/response is UI-THREAD-COUPLED here by
-     * design, because the dispatch pipeline preserves the caller's synchronization context so facades
-     * can touch the window. Reserve `invoke` for calls that are quick AND safe on the UI thread — the
-     * window commands are the model — and post everything else, streaming results back as notifications.
-     *
-     * ⚠ Posting is only HALF of freeing the UI thread. The host still dispatches on the UI thread
-     * whether or not the client awaits, so a handler that does heavy work synchronously stalls the
-     * window either way. The other half is the host's: return from the route immediately and stream.
+     * This is the default shape for a desktop shell and {@link invoke} is the special case (D23):
+     * reserve `invoke` for calls that are quick AND safe on the host's UI thread, and post everything
+     * else, streaming results back as notifications.
      *
-     * Failures are not silent. There is no promise to reject, so a failed response is reported through
-     * `onPostError` (default `console.error`) rather than being dropped the way an unmatched response
-     * otherwise is. Nothing is queued and no timer is set, so there is nothing to leak and no deadline.
+     * A failed response is reported through `onPostError` (default `console.error`) rather than
+     * dropped. The id is remembered for that — see {@link ShenoraBridgeOptions.maxTrackedPosts}. No
+     * timer is set, so there is no deadline.
      *
-     * No transport (a plain browser tab) is a silent no-op, matching the fire-and-forget contract —
-     * unlike `invoke`, there is no caller waiting to be told. **A DISPOSED bridge is the same silent
-     * no-op**, and that one can surprise: `invoke` on a disposed bridge rejects with `NO_TRANSPORT`
-     * while `post` just returns the id, so a stale reference kept across a `configureBridge` swap looks
-     * like it is still sending. `isAvailable` is the check.
+     * ⚠ No transport (a plain browser tab) is a silent no-op, and **so is a DISPOSED bridge** — where
+     * `invoke` would reject with `NO_TRANSPORT`, this just returns the id, so a stale reference kept
+     * across a {@link configureBridge} swap looks like it is still sending. `isAvailable` is the check.
      */
     post<TPayload = unknown>(module: string, type: string, options?: PostOptions<TPayload>): string;
     /**
@@ -125,22 +112,18 @@ export declare class ShenoraBridge {
      * also the host's cue to reset per-page state. No-transport is a silent no-op so browser dev
      * doesn't error.
      *
-     * Ordering used to matter here and no longer does for drop zones: the host cleared the previous
-     * page's overlays on this handshake, so a `REGISTER` sent before `READY` was wiped even though it
-     * was acked. `DropZoneManager` now clears on DOCUMENT CHANGE instead, which cannot race the client.
-     * The general point still stands for any per-page state YOUR host resets here — a reset keyed on
-     * the handshake races anything the page sends before it, and in React that is structural rather
-     * than a mistake, because CHILD effects run before PARENT effects.
+     * ⚠ Any per-page state YOUR host resets on this handshake races whatever the page sent before it,
+     * and in React that is structural rather than bad luck: CHILD effects run before PARENT effects.
      *
-     * The returned promise REJECTS on a failed handshake (disposed bridge, timeout). Handle it —
+     * ⚠ The returned promise REJECTS on a failed handshake (disposed bridge, timeout). Handle it —
      * `void bridge.notifyReady()` turns that into an unhandled rejection, which in a WebView2 page is
      * a silent console error.
      */
     notifyReady<TPayload = unknown>(payload?: TPayload): Promise<ShellInfo | undefined>;
     /**
      * What the host said it was during {@link notifyReady} — undefined before the handshake, or when
-     * the host advertised nothing. Cached so components can read it synchronously while rendering,
-     * which is the whole point: a capability learned after layout is a flash.
+     * the host advertised nothing. Cached so components can read it synchronously while rendering; a
+     * capability learned after layout is a visible flash.
      */
     get shell(): ShellInfo | undefined;
     /** Reject everything in flight and detach from the transport. */