@shenora/react 0.10.0 → 0.12.0

package/dist/bridge.js

@@ -1,4 +1,4 @@
-import { OperationError } from './errors.js';
+import { ShenoraError } from './errors.js';
 import { eventBus as defaultEventBus } from './eventBus.js';
 import { randomId } from './internal.js';
 import { createHostTransport } from './transport.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,24 +34,21 @@ 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;
     }
     /**
      * 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(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).
-            return Promise.reject(new OperationError({
+            // 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,24 +71,25 @@ 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 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),
                     new Promise((_, reject) => {
-                        setTimeout(() => reject(new OperationError({
+                        timer = setTimeout(() => reject(new ShenoraError({
                             code: IpcErrorCodes.timeout,
                             message: `${module}.${type} timed out after ${timeoutMs} ms (in the configured fallback).`,
                             parameters: { module, type },
                         })), timeoutMs);
                     }),
-                ]);
+                ]).finally(() => clearTimeout(timer));
             }
-            return Promise.reject(new OperationError({
+            return Promise.reject(new ShenoraError({
                 code: IpcErrorCodes.noTransport,
                 message: `No transport for ${module}.${type} — not inside a Shenora host, and no fallback is configured.`,
             }));
@@ -99,7 +97,7 @@ export class ShenoraBridge {
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
                 this.pending.delete(request.id);
-                reject(new OperationError({
+                reject(new ShenoraError({
                     code: IpcErrorCodes.timeout,
                     message: `${module}.${type} timed out after ${timeoutMs} ms.`,
                     parameters: { module, type },
@@ -123,26 +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. Nothing is queued and no timer is set, so there is nothing to leak and 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(module, type, options = {}) {
         const request = {
@@ -155,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)
@@ -187,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.
      */
@@ -202,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 : [] }
@@ -218,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;
@@ -232,11 +211,10 @@ export class ShenoraBridge {
         this.unsubscribe?.();
         for (const [id, entry] of this.pending) {
             clearTimeout(entry.timer);
-            entry.reject(new OperationError({ code: IpcErrorCodes.noTransport, message: 'Bridge disposed.' }));
+            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) {
@@ -248,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;
@@ -261,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);
@@ -285,7 +261,7 @@ export class ShenoraBridge {
                 entry.resolve(response.data);
             }
             else {
-                entry.reject(new OperationError(response.error ?? { code: IpcErrorCodes.unknownError }));
+                entry.reject(new ShenoraError(response.error ?? { code: IpcErrorCodes.unknownError }));
             }
             return;
         }

package/dist/clipboard.d.ts

@@ -0,0 +1,89 @@
+import type { ShenoraBridge } from './bridge.js';
+import { BaseModuleService } from './moduleService.js';
+/** Media type for PNG bytes — the interchange image format every platform and browser reads. */
+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.
+ */
+export interface ClipboardContent {
+    /** The plain-text representation. */
+    text?: string;
+    /**
+     * Absolute paths, for the copy a file manager can paste.
+     * ⚠ DESKTOP only — gate on {@link ClipboardHandle.canCopyFiles}.
+     */
+    files?: string[];
+    /** Every other representation, as raw bytes keyed by media type. */
+    formats?: Record<string, Uint8Array>;
+}
+/** What actually crosses the wire: the same shape with the byte payloads base64-encoded. */
+interface ClipboardWire {
+    text?: string;
+    files?: string[];
+    formats?: Record<string, string>;
+}
+interface ClipboardRequests {
+    READ: undefined;
+    WRITE: {
+        content: ClipboardWire;
+    };
+    CLEAR: undefined;
+}
+/**
+ * Typed client for the host's `SHENORA.CLIPBOARD` module (`ClipboardModule`).
+ *
+ * ⚠ **`files` is a DESKTOP capability** and rejects with `IpcErrorCodes.capabilityNotSupported` on a
+ * phone. Do not catch that — ask first, via {@link useClipboard}, and do not render the control.
+ */
+export declare class ClipboardAccess extends BaseModuleService<ClipboardRequests> {
+    constructor(bridge?: ShenoraBridge);
+    /**
+     * Everything the clipboard is offering — **no user gesture, no permission prompt, no focus
+     * requirement**, unlike `navigator.clipboard.read()`.
+     */
+    read(): Promise<ClipboardContent>;
+    /**
+     * Replace the clipboard with one item, every representation at once.
+     *
+     * ⚠ Bytes cross the IPC envelope as base64, so a large picture is a large message. A page copying
+     * something big should hand the host a path and let it read the file instead.
+     */
+    write(content: ClipboardContent): Promise<void>;
+    /** Leave the clipboard holding nothing. */
+    clear(): Promise<void>;
+}
+/** What {@link useClipboard} returns: the client, plus what this shell will actually honour. */
+export interface ClipboardHandle {
+    /** The typed client. Stable across renders. */
+    clipboard: ClipboardAccess;
+    /** This shell can put a FILE LIST on the clipboard — desktop only. Use it to decide what to RENDER. */
+    canCopyFiles: boolean;
+}
+/**
+ * The clipboard client together with what the CURRENT shell can honour — read from the ready
+ * handshake, not sniffed from the platform (D36).
+ *
+ * ```tsx
+ * const { clipboard, canCopyFiles } = useClipboard();
+ * return (
+ *   <>
+ *     <button onClick={() => navigator.clipboard.writeText(name)}>Copy name</button>
+ *     {canCopyFiles && (
+ *       <button onClick={() => clipboard.write({ text: name, files: [path] })}>Copy file</button>
+ *     )}
+ *   </>
+ * );
+ * ```
+ *
+ * ⚠ Note the first button: plain text on a click is the browser's job and stays there. This hook is for
+ * the file copy beside it.
+ *
+ * ⚠ `canCopyFiles` is `false` until the handshake has landed, so await `bridge.notifyReady()` before
+ * rendering this tree — see {@link useShellInfo} for why the read is synchronous.
+ */
+export declare function useClipboard(clipboard?: ClipboardAccess): ClipboardHandle;
+export {};

package/dist/clipboard.js

@@ -0,0 +1,119 @@
+/**
+ * The page's half of the host's `SHENORA.CLIPBOARD` module — the parts of the native clipboard the web
+ * platform withholds. Mirrors `Shenora.Modules.Clipboard.ClipboardModule`, pinned by `WireMirrorTests`.
+ *
+ * 🔴 **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.
+ *
+ * ⚠ **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';
+import { BaseModuleService } from './moduleService.js';
+import { ShellCapabilities } from './types.js';
+/** Media type for PNG bytes — the interchange image format every platform and browser reads. */
+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`.
+ *
+ * ⚠ 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 = '';
+    const chunk = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunk) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+    }
+    return btoa(binary);
+}
+function fromBase64(value) {
+    const binary = atob(value);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+/**
+ * Typed client for the host's `SHENORA.CLIPBOARD` module (`ClipboardModule`).
+ *
+ * ⚠ **`files` is a DESKTOP capability** and rejects with `IpcErrorCodes.capabilityNotSupported` on a
+ * phone. Do not catch that — ask first, via {@link useClipboard}, and do not render the control.
+ */
+export class ClipboardAccess extends BaseModuleService {
+    constructor(bridge) {
+        super('SHENORA.CLIPBOARD', bridge);
+    }
+    /**
+     * Everything the clipboard is offering — **no user gesture, no permission prompt, no focus
+     * requirement**, unlike `navigator.clipboard.read()`.
+     */
+    async read() {
+        const wire = await this.send('READ');
+        const formats = {};
+        for (const [mediaType, value] of Object.entries(wire.formats ?? {})) {
+            formats[mediaType] = fromBase64(value);
+        }
+        return { text: wire.text, files: wire.files, formats };
+    }
+    /**
+     * Replace the clipboard with one item, every representation at once.
+     *
+     * ⚠ Bytes cross the IPC envelope as base64, so a large picture is a large message. A page copying
+     * something big should hand the host a path and let it read the file instead.
+     */
+    write(content) {
+        const formats = {};
+        for (const [mediaType, bytes] of Object.entries(content.formats ?? {})) {
+            formats[mediaType] = toBase64(bytes);
+        }
+        return this.send('WRITE', {
+            payload: { content: { text: content.text, files: content.files, formats } },
+        });
+    }
+    /** Leave the clipboard holding nothing. */
+    clear() {
+        return this.send('CLEAR');
+    }
+}
+/**
+ * The clipboard client together with what the CURRENT shell can honour — read from the ready
+ * handshake, not sniffed from the platform (D36).
+ *
+ * ```tsx
+ * const { clipboard, canCopyFiles } = useClipboard();
+ * return (
+ *   <>
+ *     <button onClick={() => navigator.clipboard.writeText(name)}>Copy name</button>
+ *     {canCopyFiles && (
+ *       <button onClick={() => clipboard.write({ text: name, files: [path] })}>Copy file</button>
+ *     )}
+ *   </>
+ * );
+ * ```
+ *
+ * ⚠ Note the first button: plain text on a click is the browser's job and stays there. This hook is for
+ * the file copy beside it.
+ *
+ * ⚠ `canCopyFiles` is `false` until the handshake has landed, so await `bridge.notifyReady()` before
+ * rendering this tree — see {@link useShellInfo} for why the read is synchronous.
+ */
+export function useClipboard(clipboard) {
+    const shell = useShellInfo();
+    // 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(() => ({
+        clipboard: client,
+        canCopyFiles: capabilities?.includes(ShellCapabilities.clipboardFiles) ?? false,
+    }), [client, capabilities]);
+}

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
@@ -44,7 +43,11 @@ export interface DevInterceptorOptions {
     bus?: ShenoraEventBus;
 }
 /**
- * Install the interceptor (idempotent across HMR / StrictMode double-invoke — keyed on the
- * window global).
+ * 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, 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
@@ -15,19 +14,26 @@
 import { getBridge } from './bridge.js';
 import { eventBus as defaultEventBus } from './eventBus.js';
 /**
- * Install the interceptor (idempotent across HMR / StrictMode double-invoke — keyed on the
- * window global).
+ * 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, 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')
         return;
     const globalName = options.globalName ?? '__shenora';
     const w = window;
-    if (w[globalName])
-        return;
     const ringSize = options.ringSize ?? 300;
+    // 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; wrapping twice doubles every log line.
+    const installed = w[globalName];
+    if (installed && installed.bridge === bridge && installed.eventBus === bus)
+        return;
     const ipc = [];
     const events = [];
     const push = (buffer, entry) => {

package/dist/errors.d.ts

@@ -1,12 +1,11 @@
 import type { IpcError } from './types.js';
 /**
- * The rejection type for every failed bridge call — the client mirror of the host's
- * `OperationException` (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 OperationError extends Error {
+export declare class ShenoraError extends Error {
     /** Error code / i18n key (e.g. `"IMPORT_FAILED"`, `"TIMEOUT"`). */
     readonly code: string;
     /** Values the client interpolates into the translated message. */

package/dist/errors.js

@@ -1,14 +1,13 @@
 /**
- * The rejection type for every failed bridge call — the client mirror of the host's
- * `OperationException` (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 OperationError extends Error {
+export class ShenoraError extends Error {
     constructor(error) {
         super(error.message ?? error.code);
-        this.name = 'OperationError';
+        this.name = 'ShenoraError';
         this.code = error.code;
         this.parameters = error.parameters;
     }