@shenora/react 0.11.0 → 0.12.0

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,9 +80,7 @@ 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;
     /**
@@ -96,28 +92,17 @@ export declare class ShenoraBridge {
     /**
      * 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. ⚠ Reporting it means the id IS remembered — see {@link ShenoraBridgeOptions.maxTrackedPosts},
-     * which caps the set drop-oldest so a host that never answers cannot grow it without bound. No TIMER is
-     * set, though, so there is no deadline and nothing to fire later.
+     * 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;
     /**
@@ -127,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. */

package/dist/bridge.js

@@ -8,10 +8,10 @@ const newId = () => randomId();
 const isThenable = (value) => typeof value === 'object' && value !== null
     && typeof value.then === 'function';
 /**
- * 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.
@@ -20,7 +20,7 @@ export class ShenoraBridge {
     constructor(options = {}) {
         this.pending = new Map();
         // Ids of one-way sends, kept ONLY so a failed response can be reported instead of vanishing.
-        // Insertion-ordered and capped: a Map is used for its ordered keys, not for the values.
+        // A Map for its insertion-ordered keys, so the cap can evict the oldest.
         this.unawaited = new Map();
         this.disposed = false;
         this.transport = options.transport !== undefined ? options.transport : createHostTransport();
@@ -34,9 +34,7 @@ export class ShenoraBridge {
     }
     /**
      * 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() {
         return !this.disposed && this.transport !== null;
@@ -48,9 +46,8 @@ export class ShenoraBridge {
      */
     invoke(module, type, options = {}) {
         if (this.disposed) {
-            // Fail fast: the transport subscription is gone, so a response could never correlate —
-            // without this the call would burn the full timeout (stale references after
-            // configureBridge replaced the default are the typical way here).
+            // Fail fast: the transport subscription is gone, so a response could never correlate and the
+            // call would otherwise burn the full timeout.
             return Promise.reject(new ShenoraError({
                 code: IpcErrorCodes.noTransport,
                 message: `Bridge disposed — ${module}.${type} cannot be sent.`,
@@ -74,18 +71,12 @@ export class ShenoraBridge {
                 catch (error) {
                     return Promise.reject(error);
                 }
-                // A fallback may be async (a scripted preview harness commonly is), and this path used to
-                // bypass the timeout entirely — so a fallback that never settled hung the caller forever, with
-                // none of the diagnostics the real path gives (P5.5 H2). Only a thenable needs racing; a plain
-                // value is already settled.
+                // An async fallback is raced against the timeout too, or one that never settles hangs the
+                // caller forever. Only a thenable needs racing; a plain value has already settled.
                 if (!isThenable(result))
                     return Promise.resolve(result);
-                // ⚠ The loser's timer must be CLEARED, as every other path in this file does — the real invoke's
-                // timeout handler, its transport-throw catch, its response path and `dispose`. Leaving it holds a
-                // live timer per call for the full timeout
-                // (30 s by default), each holding its closure. Harmless to a caller, because `race` has already
-                // settled and has a rejection handler attached either way, but it is the same "one site out of
-                // N" shape the rest of this file is careful about, and it keeps timers pending in a test run.
+                // ⚠ The loser's timer is cleared in `finally` — otherwise every call holds a live timer, and
+                // its closure, for the full timeout.
                 let timer;
                 return Promise.race([
                     Promise.resolve(result),
@@ -130,28 +121,17 @@ export class ShenoraBridge {
     /**
      * 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.
+     * 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.
      *
-     * ⚠ 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.
+     * 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.
      *
-     * 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. ⚠ Reporting it means the id IS remembered — see {@link ShenoraBridgeOptions.maxTrackedPosts},
-     * which caps the set drop-oldest so a host that never answers cannot grow it without bound. No TIMER is
-     * set, though, so there is no deadline and nothing to fire later.
-     *
-     * 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(module, type, options = {}) {
         const request = {
@@ -164,8 +144,7 @@ export class ShenoraBridge {
         };
         if (this.disposed || !this.transport)
             return request.id;
-        // Remember it ONLY to report a failure. Drop-oldest at the cap so a host that never answers
-        // cannot grow this without bound; an evicted id simply loses its error report.
+        // Remembered ONLY to report a failure, drop-oldest at the cap.
         if (this.unawaited.size >= this.maxTrackedPosts) {
             const oldest = this.unawaited.keys().next();
             if (!oldest.done)
@@ -196,14 +175,10 @@ export 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.
      */
@@ -211,14 +186,9 @@ export class ShenoraBridge {
         if (!this.transport)
             return undefined;
         // The host answers with what it IS and what it can do, so a page can render one tree on every
-        // shell instead of sniffing the platform. A host that says nothing (no descriptor configured, or
-        // one predating this) leaves it UNDEFINED — absent means "assume nothing", never "assume
-        // desktop".
-        //
-        // undefined rather than null on purpose: JSON null means absent on this wire and the client
-        // convention is undefined (see .claude/knowledge/ipc-contracts.md). Returning null broke two
-        // existing tests that assert this resolves to undefined, which is the convention catching a
-        // deviation exactly where it should.
+        // shell instead of sniffing the platform. A host that says nothing leaves it UNDEFINED (never
+        // null — JSON null means absent on this wire) — and absent means "assume nothing", never
+        // "assume desktop".
         const shell = await this.invoke(HANDSHAKE_MODULE, HANDSHAKE_TYPE, { payload });
         this.shellInfo = shell && typeof shell === 'object' && typeof shell.name === 'string'
             ? { name: shell.name, capabilities: Array.isArray(shell.capabilities) ? shell.capabilities : [] }
@@ -227,8 +197,8 @@ export class ShenoraBridge {
     }
     /**
      * 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() {
         return this.shellInfo;
@@ -244,8 +214,7 @@ export class ShenoraBridge {
             entry.reject(new ShenoraError({ code: IpcErrorCodes.noTransport, message: 'Bridge disposed.' }));
             this.pending.delete(id);
         }
-        // Unawaited ids are pure bookkeeping with nothing to settle — drop them so a disposed bridge
-        // holds no references (this is the instance `configureBridge` replaces).
+        // Pure bookkeeping with nothing to settle — dropped so a disposed bridge holds no references.
         this.unawaited.clear();
     }
     onHostMessage(message) {
@@ -257,10 +226,9 @@ export class ShenoraBridge {
             console.error('[shenora] ignored unparseable host message:', error);
             return;
         }
-        // A literal `null` is VALID JSON, so it survives the parse and then `parsed.category` threw a
-        // TypeError — out of a transport listener, i.e. an uncaught page error with no caller to catch it
-        // (P5.5 H2). Primitives (`"str"`, `123`, `true`) never threw because property access on them just
-        // yields undefined; null and only null did. Anything that isn't an object simply isn't ours.
+        // ⚠ A literal `null` is VALID JSON and survives the parse, and property access on it throws —
+        // out of a transport listener, i.e. an uncaught page error with no caller to catch it. Anything
+        // that is not an object simply is not ours.
         if (parsed === null || typeof parsed !== 'object')
             return;
         const envelope = parsed;
@@ -270,10 +238,9 @@ export class ShenoraBridge {
                 return;
             const entry = this.pending.get(response.id);
             if (!entry) {
-                // No pending call. Either this answers a one-way `post` — in which case a FAILURE must be
-                // surfaced, because there is no promise to reject and dropping it here is exactly how a
-                // feature "just stops working" with nothing to grep for — or it is a late/foreign response,
-                // which stays ignored.
+                // No pending call. Either this answers a one-way `post`, whose FAILURE must be surfaced
+                // because there is no promise to reject, or it is a late/foreign response, which stays
+                // ignored.
                 const posted = this.unawaited.get(response.id);
                 if (posted) {
                     this.unawaited.delete(response.id);

package/dist/clipboard.d.ts

@@ -5,11 +5,9 @@ export declare const PNG_IMAGE = "image/png";
 /** Media type for UTF-8 HTML, for a paste that keeps its formatting. */
 export declare const HTML = "text/html";
 /**
- * One clipboard item and every representation it offers.
- *
- * `text` and `files` are named because every platform has a first-class API for them; everything else
- * lives in `formats`, keyed by media type — {@link PNG_IMAGE}, {@link HTML}, or your own
- * `application/…` type, which the host carries verbatim so a paste can round-trip it losslessly.
+ * One clipboard item and every representation it offers. `text` and `files` are named because every
+ * platform has a first-class API for them; everything else lives in `formats`, keyed by media type —
+ * {@link PNG_IMAGE}, {@link HTML}, or your own `application/…` type, which the host carries verbatim.
  */
 export interface ClipboardContent {
     /** The plain-text representation. */
@@ -45,7 +43,7 @@ export declare class ClipboardAccess extends BaseModuleService<ClipboardRequests
     constructor(bridge?: ShenoraBridge);
     /**
      * Everything the clipboard is offering — **no user gesture, no permission prompt, no focus
-     * requirement**, which is the half `navigator.clipboard.read()` cannot give you.
+     * requirement**, unlike `navigator.clipboard.read()`.
      */
     read(): Promise<ClipboardContent>;
     /**
@@ -62,10 +60,7 @@ export declare class ClipboardAccess extends BaseModuleService<ClipboardRequests
 export interface ClipboardHandle {
     /** The typed client. Stable across renders. */
     clipboard: ClipboardAccess;
-    /**
-     * This shell can put a FILE LIST on the clipboard — desktop only. Decide what to RENDER with it; a
-     * refused call rejects, which is the honest answer to a question that should not have been asked.
-     */
+    /** This shell can put a FILE LIST on the clipboard — desktop only. Use it to decide what to RENDER. */
     canCopyFiles: boolean;
 }
 /**

package/dist/clipboard.js

@@ -1,23 +1,18 @@
 /**
  * The page's half of the host's `SHENORA.CLIPBOARD` module — the parts of the native clipboard the web
- * platform withholds.
+ * platform withholds. Mirrors `Shenora.Modules.Clipboard.ClipboardModule`, pinned by `WireMirrorTests`.
  *
- * 🔴 **Reach for `navigator.clipboard` first.** The page runs in a real browser: a gesture-driven "copy
- * this text" or "copy this image" already works, needs no host round trip, and is what the platform
- * expects. Two things it cannot do are why this module exists —
+ * 🔴 **Reach for `navigator.clipboard` first.** A gesture-driven "copy this text" or "copy this image"
+ * already works and needs no host round trip. Two things it cannot do are why this module exists —
  *
  * 1. **Files.** No web API puts a file list on the clipboard, so the user cannot paste into Explorer,
  *    Finder or a file manager. There is no polyfill.
  * 2. **Access with no user gesture or focus.** `navigator.clipboard.read()` needs transient activation,
  *    document focus and a permission. A host has none of those constraints.
  *
- * ⚠ **And the choice is per-COPY, not per-format**, because a clipboard set is atomic: one item, last
- * writer wins outright. An item that includes files must be written entirely through
- * {@link ClipboardAccess.write}
- * — writing its text half with `navigator.clipboard` and the files here leaves only the files, silently.
- *
- * Mirrors `Shenora.Modules.Clipboard.ClipboardModule`. The wire names are pinned against the host's own
- * constants by `WireMirrorTests`, not by care.
+ * ⚠ **The choice is per-COPY, not per-format**: a clipboard set is atomic, one item, last writer wins.
+ * An item that includes files must be written entirely through {@link ClipboardAccess.write} — writing
+ * its text half with `navigator.clipboard` and the files here leaves only the files, silently.
  */
 import { useMemo } from 'react';
 import { useShellInfo } from './hooks.js';
@@ -28,11 +23,10 @@ export const PNG_IMAGE = 'image/png';
 /** Media type for UTF-8 HTML, for a paste that keeps its formatting. */
 export const HTML = 'text/html';
 /**
- * Base64 without a `Buffer` and without `btoa(String.fromCharCode(...bytes))`.
+ * Base64 without a `Buffer`.
  *
- * ⚠ The spread form is the idiom everyone writes and it throws `RangeError` on a large image — the
- * argument list overflows the call stack somewhere north of ~100 kB, which is a small screenshot. A
- * chunked loop has no such ceiling.
+ * ⚠ Never `btoa(String.fromCharCode(...bytes))`: the spread overflows the argument list and throws
+ * `RangeError` on anything past roughly a small screenshot. A chunked loop has no such ceiling.
  */
 function toBase64(bytes) {
     let binary = '';
@@ -61,7 +55,7 @@ export class ClipboardAccess extends BaseModuleService {
     }
     /**
      * Everything the clipboard is offering — **no user gesture, no permission prompt, no focus
-     * requirement**, which is the half `navigator.clipboard.read()` cannot give you.
+     * requirement**, unlike `navigator.clipboard.read()`.
      */
     async read() {
         const wire = await this.send('READ');
@@ -115,8 +109,7 @@ export class ClipboardAccess extends BaseModuleService {
  */
 export function useClipboard(clipboard) {
     const shell = useShellInfo();
-    // The service is stateless and holds only its module name, but a fresh instance per render would
-    // still make it useless as an effect dependency — the same reason useFileDialogs caches one.
+    // Cached so it is usable as an effect dependency, not because the service is expensive.
     const client = useMemo(() => clipboard ?? new ClipboardAccess(), [clipboard]);
     const capabilities = shell?.capabilities;
     return useMemo(() => ({

package/dist/devInterceptor.d.ts

@@ -1,11 +1,10 @@
 /**
- * Dev-only IPC + event-hub interceptor, ported from the primary desktop sibling (NEVER ship it
- * in prod — gate the single call site with `import.meta.env.DEV`).
+ * Dev-only IPC + event-hub interceptor. ⚠ NEVER ship it in prod — gate the single call site with
+ * `import.meta.env.DEV`.
  *
- * Why: during desktop-app testing the agent drives the UI over CDP, but native dialogs and
- * event-driven flows can't be exercised by clicking. This wraps the bridge's `invoke` (the IPC
- * seam) and the event bus's `emit` (the event hub) to (1) record + console.debug every
- * request/response/event into ring buffers, and (2) expose a window global so a CDP eval can
+ * For driving a page over CDP, where native dialogs and event-driven flows cannot be exercised by
+ * clicking. It wraps the bridge's `invoke` and the event bus's `emit` to (1) record + console.debug
+ * every request/response/event into ring buffers, and (2) expose a window global so a CDP eval can
  * invoke ANY IPC directly and await events:
  *
  *   window.__shenora.call('NOTES', 'ADD', { title: 'x' })   // drive an IPC, bypass the UI
@@ -47,11 +46,8 @@ export interface DevInterceptorOptions {
  * Install the interceptor. Idempotent across HMR and StrictMode's double-invoke.
  *
  * 🔴 **Idempotency is keyed on WHICH bridge and bus were wrapped, not on "something is installed".**
- * The wrapping mutates a specific `ShenoraBridge` INSTANCE, but the guard used to ask only whether the
- * window global existed — so `configureBridge()`, which disposes the default bridge and builds a new
- * one, left the interceptor pointing at the dead instance and a second install returning early without
- * wrapping the live one. The tool then looked installed and recorded NOTHING, while
- * `window.__shenora.call` drove a disposed bridge. A dev tool that fails silently is worse than one that
- * is absent, because its silence reads as "no traffic".
+ * The wrapping mutates a specific `ShenoraBridge` INSTANCE, so a guard that only asks whether the
+ * window global exists leaves the interceptor pointing at the bridge `configureBridge()` disposed:
+ * installed-looking, recording NOTHING, and its silence reads as "no traffic".
  */
 export declare function installDevInterceptor(options?: DevInterceptorOptions): void;

package/dist/devInterceptor.js

@@ -1,11 +1,10 @@
 /**
- * Dev-only IPC + event-hub interceptor, ported from the primary desktop sibling (NEVER ship it
- * in prod — gate the single call site with `import.meta.env.DEV`).
+ * Dev-only IPC + event-hub interceptor. ⚠ NEVER ship it in prod — gate the single call site with
+ * `import.meta.env.DEV`.
  *
- * Why: during desktop-app testing the agent drives the UI over CDP, but native dialogs and
- * event-driven flows can't be exercised by clicking. This wraps the bridge's `invoke` (the IPC
- * seam) and the event bus's `emit` (the event hub) to (1) record + console.debug every
- * request/response/event into ring buffers, and (2) expose a window global so a CDP eval can
+ * For driving a page over CDP, where native dialogs and event-driven flows cannot be exercised by
+ * clicking. It wraps the bridge's `invoke` and the event bus's `emit` to (1) record + console.debug
+ * every request/response/event into ring buffers, and (2) expose a window global so a CDP eval can
  * invoke ANY IPC directly and await events:
  *
  *   window.__shenora.call('NOTES', 'ADD', { title: 'x' })   // drive an IPC, bypass the UI
@@ -18,12 +17,9 @@ import { eventBus as defaultEventBus } from './eventBus.js';
  * Install the interceptor. Idempotent across HMR and StrictMode's double-invoke.
  *
  * 🔴 **Idempotency is keyed on WHICH bridge and bus were wrapped, not on "something is installed".**
- * The wrapping mutates a specific `ShenoraBridge` INSTANCE, but the guard used to ask only whether the
- * window global existed — so `configureBridge()`, which disposes the default bridge and builds a new
- * one, left the interceptor pointing at the dead instance and a second install returning early without
- * wrapping the live one. The tool then looked installed and recorded NOTHING, while
- * `window.__shenora.call` drove a disposed bridge. A dev tool that fails silently is worse than one that
- * is absent, because its silence reads as "no traffic".
+ * The wrapping mutates a specific `ShenoraBridge` INSTANCE, so a guard that only asks whether the
+ * window global exists leaves the interceptor pointing at the bridge `configureBridge()` disposed:
+ * installed-looking, recording NOTHING, and its silence reads as "no traffic".
  */
 export function installDevInterceptor(options = {}) {
     if (typeof window === 'undefined')
@@ -31,11 +27,10 @@ export function installDevInterceptor(options = {}) {
     const globalName = options.globalName ?? '__shenora';
     const w = window;
     const ringSize = options.ringSize ?? 300;
-    // Resolved BEFORE the guard, because the guard's question is now about these two objects.
+    // Resolved BEFORE the guard, because the guard's question is about these two objects.
     const bridge = options.bridge ?? getBridge();
     const bus = options.bus ?? defaultEventBus;
-    // Same pair = the HMR/StrictMode case this exists for; wrapping twice would double every log line and
-    // stack a second recorder on the first.
+    // Same pair = the HMR/StrictMode case; wrapping twice doubles every log line.
     const installed = w[globalName];
     if (installed && installed.bridge === bridge && installed.eventBus === bus)
         return;

package/dist/errors.d.ts

@@ -1,10 +1,9 @@
 import type { IpcError } from './types.js';
 /**
- * The rejection type for every failed bridge call — the client mirror of the host's
- * `ShenoraException` (the `Error` suffix is the TS idiom; the C# type keeps the platform's
- * `Exception` suffix). Carries the structured code + parameters so callers translate
- * `errors.{code}` instead of matching message strings. Client-side failures (timeout, missing
- * transport) reject through this same shape with the client-reserved codes.
+ * The rejection type for every failed bridge call — the client mirror of the host's `ShenoraException`.
+ * Carries the structured code + parameters so callers translate `errors.{code}` instead of matching
+ * message strings. Client-side failures (timeout, missing transport) reject through this same shape
+ * with the client-reserved codes.
  */
 export declare class ShenoraError extends Error {
     /** Error code / i18n key (e.g. `"IMPORT_FAILED"`, `"TIMEOUT"`). */

package/dist/errors.js

@@ -1,9 +1,8 @@
 /**
- * The rejection type for every failed bridge call — the client mirror of the host's
- * `ShenoraException` (the `Error` suffix is the TS idiom; the C# type keeps the platform's
- * `Exception` suffix). Carries the structured code + parameters so callers translate
- * `errors.{code}` instead of matching message strings. Client-side failures (timeout, missing
- * transport) reject through this same shape with the client-reserved codes.
+ * The rejection type for every failed bridge call — the client mirror of the host's `ShenoraException`.
+ * Carries the structured code + parameters so callers translate `errors.{code}` instead of matching
+ * message strings. Client-side failures (timeout, missing transport) reject through this same shape
+ * with the client-reserved codes.
  */
 export class ShenoraError extends Error {
     constructor(error) {