@shenora/react 0.9.1 → 0.11.0

package/dist/clipboard.js

@@ -0,0 +1,126 @@
+/**
+ * The page's half of the host's `SHENORA.CLIPBOARD` module — the parts of the native clipboard the web
+ * platform withholds.
+ *
+ * 🔴 **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 —
+ *
+ * 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.
+ */
+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` and without `btoa(String.fromCharCode(...bytes))`.
+ *
+ * ⚠ 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.
+ */
+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**, which is the half `navigator.clipboard.read()` cannot give you.
+     */
+    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();
+    // 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.
+    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

@@ -44,7 +44,14 @@ 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, 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".
  */
 export declare function installDevInterceptor(options?: DevInterceptorOptions): void;

package/dist/devInterceptor.js

@@ -15,19 +15,30 @@
 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, 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".
  */
 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 now 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.
+    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,12 @@
 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
+ * `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.
  */
-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,14 @@
 /**
  * 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
+ * `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.
  */
-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;
     }

package/dist/eventBus.d.ts

@@ -16,7 +16,7 @@ export interface SubscribeOptions {
  * Event enums/maps are app schema, so apps layer their own typed wrappers on top (headless per D13).
  * A throwing handler is isolated: it never breaks the other subscribers or the emitter.
  *
- * Three subscription breadths, mirroring the host's `Shenora.Core.IEventBus`: an exact
+ * Three subscription breadths, mirroring the host's `Shenora.IEventBus`: an exact
  * `(module, type)` pair, a whole {@link subscribeToModule | module}, or
  * {@link subscribeToAll | everything}. The broad two were added in P6.4 — the host had shipped them
  * from the start (`WebViewIpcBridge` itself consumes `SubscribeToAll`), so the client was the
@@ -63,10 +63,20 @@ export declare class ShenoraEventBus {
     /** Remove every subscription (tests). */
     clear(): void;
     /**
-     * Subscription count (diagnostics). With no arguments: every subscription of any breadth. With a
-     * `(module, type)`: every subscription that WOULD receive that pair — exact, whole-module and
-     * catch-all — because "how many listeners does this event have?" is the question a diagnostic is
-     * actually asking. Scope is not applied; a count is not a delivery.
+     * Subscription count (diagnostics). Every form answers "how many subscriptions WOULD receive this?",
+     * which is the question a diagnostic is actually asking — so each includes the broader breadths that
+     * would also fire. Scope is not applied; a count is not a delivery.
+     *
+     * - no arguments — every subscription of any breadth.
+     * - `(module)` — everything that would receive ANY event of that module: its exact-type
+     *   subscriptions, its whole-module ones, and the catch-alls.
+     * - `(module, type)` — everything that would receive that one pair.
+     *
+     * 🔴 **The one-argument form used to silently answer the GLOBAL total.** The guard read
+     * `if (module && type)`, so passing a module alone fell through to the count-everything branch — a
+     * plausible number, for a different question, with nothing to indicate the substitution. The fix is
+     * at RUNTIME rather than in an overload signature because this package ships JavaScript: a
+     * type-level restriction would leave a JS consumer receiving exactly the same wrong number.
      */
     getSubscriptionCount(module?: string, type?: string): number;
 }

package/dist/eventBus.js

@@ -4,7 +4,7 @@
  * Event enums/maps are app schema, so apps layer their own typed wrappers on top (headless per D13).
  * A throwing handler is isolated: it never breaks the other subscribers or the emitter.
  *
- * Three subscription breadths, mirroring the host's `Shenora.Core.IEventBus`: an exact
+ * Three subscription breadths, mirroring the host's `Shenora.IEventBus`: an exact
  * `(module, type)` pair, a whole {@link subscribeToModule | module}, or
  * {@link subscribeToAll | everything}. The broad two were added in P6.4 — the host had shipped them
  * from the start (`WebViewIpcBridge` itself consumes `SubscribeToAll`), so the client was the
@@ -86,17 +86,37 @@ export class ShenoraEventBus {
         this.all.clear();
     }
     /**
-     * Subscription count (diagnostics). With no arguments: every subscription of any breadth. With a
-     * `(module, type)`: every subscription that WOULD receive that pair — exact, whole-module and
-     * catch-all — because "how many listeners does this event have?" is the question a diagnostic is
-     * actually asking. Scope is not applied; a count is not a delivery.
+     * Subscription count (diagnostics). Every form answers "how many subscriptions WOULD receive this?",
+     * which is the question a diagnostic is actually asking — so each includes the broader breadths that
+     * would also fire. Scope is not applied; a count is not a delivery.
+     *
+     * - no arguments — every subscription of any breadth.
+     * - `(module)` — everything that would receive ANY event of that module: its exact-type
+     *   subscriptions, its whole-module ones, and the catch-alls.
+     * - `(module, type)` — everything that would receive that one pair.
+     *
+     * 🔴 **The one-argument form used to silently answer the GLOBAL total.** The guard read
+     * `if (module && type)`, so passing a module alone fell through to the count-everything branch — a
+     * plausible number, for a different question, with nothing to indicate the substitution. The fix is
+     * at RUNTIME rather than in an overload signature because this package ships JavaScript: a
+     * type-level restriction would leave a JS consumer receiving exactly the same wrong number.
      */
     getSubscriptionCount(module, type) {
-        if (module && type) {
+        if (module !== undefined && type !== undefined) {
             return (this.exact.get(eventKey(module, type))?.size ?? 0)
                 + (this.byModule.get(module)?.size ?? 0)
                 + this.all.size;
         }
+        if (module !== undefined) {
+            let total = this.all.size + (this.byModule.get(module)?.size ?? 0);
+            // The exact map is keyed `module\0type`, so a module's own entries are its prefix — compared
+            // against the separator so that a module named `APP` cannot pick up `APPLE`'s subscriptions.
+            const prefix = `${module}\0`;
+            for (const [key, set] of this.exact)
+                if (key.startsWith(prefix))
+                    total += set.size;
+            return total;
+        }
         let total = this.all.size;
         for (const set of this.exact.values())
             total += set.size;
@@ -135,10 +155,9 @@ function addTo(collection, key, subscription) {
  * the colliding form, so the two halves of one contract disagreed. `'\0'` cannot appear in a JS string
  * literal a developer types by accident, which is what makes it safe as a separator.
  *
- * The broad subscriptions deliberately do NOT reuse this with a `"*"` sentinel the way the host's
- * pattern matcher does: a module or type legitimately named `*` would then silently become a
- * catch-all. Separate collections cannot collide with an app string at all — same lesson as above,
- * applied before it could be earned a second time.
+ * The broad subscriptions use separate collections rather than a wildcard key. That is an
+ * implementation choice here, not a correction of the host: the host's pattern matcher takes `"*"` and
+ * that is fine, because a module or type named `*` is not a name any app has or wants.
  */
 function eventKey(module, type) {
     return `${module}\0${type}`;

package/dist/fileDialogs.d.ts

@@ -0,0 +1,153 @@
+import type { ShenoraBridge } from './bridge.js';
+import { BaseModuleService } from './moduleService.js';
+/** One dialog filter row (e.g. `{ name: 'Images', extensions: ['png', 'jpg'] }`). */
+export interface FileDialogFilter {
+    name: string;
+    /** Extensions WITHOUT the dot or wildcard — `'png'`, not `'*.png'`. */
+    extensions: string[];
+}
+/**
+ * What EVERY dialog call takes. The per-dialog shapes below add what only that dialog can honour —
+ * which is the point: a save-only field on a folder pick will not compile.
+ */
+export interface FileDialogOptions {
+    /** Dialog title. Omit for a neutral per-dialog default. */
+    title?: string;
+    /** Start location when nothing is remembered. */
+    defaultPath?: string;
+    /**
+     * Key under which the host remembers the last-used directory and restores it next time.
+     * Remembered PER KEY, so "import" and "export" stay separate. Omit for no memory.
+     */
+    rememberPathKey?: string;
+}
+/** Inputs for {@link FileDialogs.openFile}. */
+export interface OpenFileOptions extends FileDialogOptions {
+    /** Filter rows; omit/empty = "All Files". */
+    filters?: FileDialogFilter[];
+    /** Initial file name shown in the dialog. */
+    fileName?: string;
+    /** Require the picked file to exist. Default true. Desktop hint — a mobile picker ignores it. */
+    checkFileExists?: boolean;
+    /** Require the path to exist. Default true. Desktop hint. */
+    checkPathExists?: boolean;
+    /** Validate the host's file-name rules. Default true. Desktop hint. */
+    validateNames?: boolean;
+}
+/** Inputs for {@link FileDialogs.openFolder}. */
+export interface OpenFolderOptions extends FileDialogOptions {
+    /** Also allow picking a FILE. The host swaps in a file dialog with relaxed validation. */
+    allowFileSelection?: boolean;
+    /** Filter rows for the FILE half — ⚠ ignored unless {@link allowFileSelection} is set. */
+    filters?: FileDialogFilter[];
+}
+/** Inputs for {@link FileDialogs.saveFile} and {@link FileDialogs.saveText}. */
+export interface SaveFileOptions extends FileDialogOptions {
+    /** Filter rows; omit/empty = "All Files". */
+    filters?: FileDialogFilter[];
+    /** The name being suggested. */
+    fileName?: string;
+    /** Extension appended when the user omits one (no dot). */
+    defaultExtension?: string;
+    /** Prompt before overwriting. Default true. Desktop hint. */
+    overwritePrompt?: boolean;
+    /** Require the path to exist. Default true. Desktop hint. */
+    checkPathExists?: boolean;
+}
+/**
+ * A dialog outcome. ⚠ **THREE outcomes, not two** — and the third is the one that surprises people:
+ * cancelled (`success: false`); succeeded with an addressable location (`filePath` set); and
+ * **succeeded with NO location**, which is what {@link FileDialogs.saveText} returns on a phone,
+ * because the bytes went to a revocable grant rather than somewhere the app may reopen.
+ *
+ * So `success && filePath === undefined` is legitimate, and `result.filePath!` after checking
+ * `success` is a null-reference waiting for a mobile shell.
+ */
+export interface FileDialogResult {
+    success: boolean;
+    filePath?: string;
+}
+interface FileDialogRequests {
+    OPEN_FILE: {
+        options?: OpenFileOptions;
+    };
+    OPEN_FOLDER: {
+        options?: OpenFolderOptions;
+    };
+    SAVE_FILE: {
+        options?: SaveFileOptions;
+    };
+    SAVE_TEXT: {
+        text: string;
+        options?: SaveFileOptions;
+    };
+}
+/**
+ * Typed client for the host's `SHENORA.DIALOGS` module (`FileDialogModule`).
+ *
+ * ⚠ **Two of these are DESKTOP capabilities.** `openFolder` and `saveFile` have no expression on a
+ * phone and reject with `IpcErrorCodes.capabilityNotSupported` there. Do not catch that — ask first,
+ * via {@link useFileDialogs}, and do not render the control at all. `openFile` and `saveText` work
+ * everywhere.
+ */
+export declare class FileDialogs extends BaseModuleService<FileDialogRequests> {
+    constructor(bridge?: ShenoraBridge);
+    /** Pick an existing file. Available on every shell. */
+    openFile(options?: OpenFileOptions): Promise<FileDialogResult>;
+    /**
+     * Pick a folder. ⚠ DESKTOP only — gate on {@link FileDialogsHandle.canPickFolder}.
+     *
+     * On mobile "open folder" means the camera roll, the app's own space, or a scoped grant: the same
+     * word with a different guarantee, which is why there is no portable version of it.
+     */
+    openFolder(options?: OpenFolderOptions): Promise<FileDialogResult>;
+    /**
+     * Pick a save destination and get the PATH back. ⚠ DESKTOP only — gate on
+     * {@link FileDialogsHandle.canPickSavePath}. "Give me somewhere to write later" has no mobile
+     * expression; use {@link saveText} in portable code, which also works on the desktop.
+     */
+    saveFile(options?: SaveFileOptions): Promise<FileDialogResult>;
+    /**
+     * Pick a destination AND write `text` to it, in one call — the PORTABLE save, working everywhere
+     * because the HOST does the writing.
+     *
+     * ⚠ For text a page legitimately holds: an export, a report, a config. The content crosses the IPC
+     * envelope as JSON, so anything large or binary should be produced host-side and saved through the
+     * host's own `IFileDialogs.SaveAsync`, where it never enters a message.
+     */
+    saveText(text: string, options?: SaveFileOptions): Promise<FileDialogResult>;
+}
+/** What {@link useFileDialogs} returns: the client, plus what this shell will actually honour. */
+export interface FileDialogsHandle {
+    /** The typed client. Stable across renders. */
+    dialogs: FileDialogs;
+    /** This shell can pick an existing file. */
+    canPickFile: boolean;
+    /** This shell can pick a FOLDER — desktop only (see {@link FileDialogs.openFolder}). */
+    canPickFolder: boolean;
+    /** This shell can return a save PATH — desktop only (see {@link FileDialogs.saveFile}). */
+    canPickSavePath: boolean;
+}
+/**
+ * The dialogs client together with what the CURRENT shell can honour — read from the ready
+ * handshake, not sniffed from the platform (D36).
+ *
+ * ```tsx
+ * const { dialogs, canPickFolder } = useFileDialogs();
+ * return (
+ *   <>
+ *     <button onClick={() => dialogs.openFile()}>Choose a file</button>
+ *     {canPickFolder && <button onClick={() => dialogs.openFolder()}>Choose a folder</button>}
+ *   </>
+ * );
+ * ```
+ *
+ * ⚠ **Use these to decide what to RENDER, not what to catch.** A refused call rejects with
+ * `IpcErrorCodes.capabilityNotSupported`, which is the honest answer to a question that should not
+ * have been asked — the button should not have been there.
+ *
+ * ⚠ Every flag 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 useFileDialogs(dialogs?: FileDialogs): FileDialogsHandle;
+export {};

package/dist/fileDialogs.js

@@ -0,0 +1,90 @@
+/**
+ * The page's half of the host's `SHENORA.DIALOGS` module — native file/folder/save dialogs, and the
+ * capability gating that lets ONE bundle ship to every shell.
+ *
+ * Mirrors `Shenora.Core.Ipc.FileDialogModule`. The wire names here are pinned against the host's own
+ * constants by `WireMirrorTests`, not by care.
+ */
+import { useMemo } from 'react';
+import { useShellInfo } from './hooks.js';
+import { BaseModuleService } from './moduleService.js';
+import { ShellCapabilities } from './types.js';
+/**
+ * Typed client for the host's `SHENORA.DIALOGS` module (`FileDialogModule`).
+ *
+ * ⚠ **Two of these are DESKTOP capabilities.** `openFolder` and `saveFile` have no expression on a
+ * phone and reject with `IpcErrorCodes.capabilityNotSupported` there. Do not catch that — ask first,
+ * via {@link useFileDialogs}, and do not render the control at all. `openFile` and `saveText` work
+ * everywhere.
+ */
+export class FileDialogs extends BaseModuleService {
+    constructor(bridge) {
+        super('SHENORA.DIALOGS', bridge);
+    }
+    /** Pick an existing file. Available on every shell. */
+    openFile(options) {
+        return this.send('OPEN_FILE', { payload: { options } });
+    }
+    /**
+     * Pick a folder. ⚠ DESKTOP only — gate on {@link FileDialogsHandle.canPickFolder}.
+     *
+     * On mobile "open folder" means the camera roll, the app's own space, or a scoped grant: the same
+     * word with a different guarantee, which is why there is no portable version of it.
+     */
+    openFolder(options) {
+        return this.send('OPEN_FOLDER', { payload: { options } });
+    }
+    /**
+     * Pick a save destination and get the PATH back. ⚠ DESKTOP only — gate on
+     * {@link FileDialogsHandle.canPickSavePath}. "Give me somewhere to write later" has no mobile
+     * expression; use {@link saveText} in portable code, which also works on the desktop.
+     */
+    saveFile(options) {
+        return this.send('SAVE_FILE', { payload: { options } });
+    }
+    /**
+     * Pick a destination AND write `text` to it, in one call — the PORTABLE save, working everywhere
+     * because the HOST does the writing.
+     *
+     * ⚠ For text a page legitimately holds: an export, a report, a config. The content crosses the IPC
+     * envelope as JSON, so anything large or binary should be produced host-side and saved through the
+     * host's own `IFileDialogs.SaveAsync`, where it never enters a message.
+     */
+    saveText(text, options) {
+        return this.send('SAVE_TEXT', { payload: { text, options } });
+    }
+}
+/**
+ * The dialogs client together with what the CURRENT shell can honour — read from the ready
+ * handshake, not sniffed from the platform (D36).
+ *
+ * ```tsx
+ * const { dialogs, canPickFolder } = useFileDialogs();
+ * return (
+ *   <>
+ *     <button onClick={() => dialogs.openFile()}>Choose a file</button>
+ *     {canPickFolder && <button onClick={() => dialogs.openFolder()}>Choose a folder</button>}
+ *   </>
+ * );
+ * ```
+ *
+ * ⚠ **Use these to decide what to RENDER, not what to catch.** A refused call rejects with
+ * `IpcErrorCodes.capabilityNotSupported`, which is the honest answer to a question that should not
+ * have been asked — the button should not have been there.
+ *
+ * ⚠ Every flag 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 useFileDialogs(dialogs) {
+    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 useWindowMaximized caches one.
+    const client = useMemo(() => dialogs ?? new FileDialogs(), [dialogs]);
+    const capabilities = shell?.capabilities;
+    return useMemo(() => ({
+        dialogs: client,
+        canPickFile: capabilities?.includes(ShellCapabilities.filePicker) ?? false,
+        canPickFolder: capabilities?.includes(ShellCapabilities.folderPicker) ?? false,
+        canPickSavePath: capabilities?.includes(ShellCapabilities.savePicker) ?? false,
+    }), [client, capabilities]);
+}

package/dist/hooks.d.ts

@@ -1,11 +1,41 @@
 import { type ShenoraBridge } from './bridge.js';
 import { type ShenoraEventBus } from './eventBus.js';
-import type { EventMessage } from './types.js';
-/** Host access for components: the (default) bridge and whether a host transport exists. */
+import type { EventMessage, ShellInfo } from './types.js';
+/**
+ * Host access for components: the (default) bridge and whether a host transport exists.
+ *
+ * ⚠ The result is MEMOIZED, and that is not a micro-optimisation. A fresh object every render is a
+ * fresh dependency for every `useEffect`/`useMemo`/`useCallback` that lists it, so the natural
+ * `const shenora = useShenora(); useEffect(…, [shenora])` re-runs on EVERY render — a subscribe/
+ * unsubscribe cycle per frame in the worst case. The identity changes only when the bridge itself does,
+ * or when `isAvailable` flips as a host attaches, which are the two moments a consumer means to react to.
+ */
 export declare function useShenora(): {
     isAvailable: boolean;
     bridge: ShenoraBridge;
 };
+/**
+ * What the host IS and what it can do — the way one bundle renders correctly on every shell.
+ * Branch on {@link ShellInfo.capabilities}, never on {@link ShellInfo.name}.
+ *
+ * ```tsx
+ * const shell = useShellInfo();
+ * return <>{shell?.capabilities.includes(ShellCapabilities.windowChrome) && <TitleBar />}</>;
+ * ```
+ *
+ * `undefined` means no host said anything — a plain browser tab, a host predating the handshake, or a
+ * handshake that has not finished. **Treat absent as "assume nothing", never as "assume desktop".**
+ *
+ * ⚠ **Await `bridge.notifyReady()` before rendering the tree that depends on this.** The value is read
+ * SYNCHRONOUSLY from the bridge's cache, deliberately — a capability learned after layout is a visible
+ * flash — which means this hook does not re-render when a handshake lands later. A component mounted
+ * mid-handshake sees `undefined` and keeps seeing it, which is the documented "assume nothing" tree
+ * rather than a wrong one, but it is not the tree you wanted.
+ *
+ * ⚠ This hook was referenced by two doc examples in this package for several releases before it
+ * existed — `bridge.shell` was the only way to read it. If you wrote that workaround, this replaces it.
+ */
+export declare function useShellInfo(bridge?: ShenoraBridge): ShellInfo | undefined;
 /**
  * Subscribe to one (module, type) event for the component's lifetime, ported from the primary
  * desktop sibling. The handler receives the unwrapped payload (plus the full event). DEVIATION

package/dist/hooks.js

@@ -1,10 +1,43 @@
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { getBridge } from './bridge.js';
 import { eventBus as defaultEventBus } from './eventBus.js';
-/** Host access for components: the (default) bridge and whether a host transport exists. */
+/**
+ * Host access for components: the (default) bridge and whether a host transport exists.
+ *
+ * ⚠ The result is MEMOIZED, and that is not a micro-optimisation. A fresh object every render is a
+ * fresh dependency for every `useEffect`/`useMemo`/`useCallback` that lists it, so the natural
+ * `const shenora = useShenora(); useEffect(…, [shenora])` re-runs on EVERY render — a subscribe/
+ * unsubscribe cycle per frame in the worst case. The identity changes only when the bridge itself does,
+ * or when `isAvailable` flips as a host attaches, which are the two moments a consumer means to react to.
+ */
 export function useShenora() {
     const bridge = getBridge();
-    return { isAvailable: bridge.isAvailable, bridge };
+    const isAvailable = bridge.isAvailable;
+    return useMemo(() => ({ isAvailable, bridge }), [isAvailable, bridge]);
+}
+/**
+ * What the host IS and what it can do — the way one bundle renders correctly on every shell.
+ * Branch on {@link ShellInfo.capabilities}, never on {@link ShellInfo.name}.
+ *
+ * ```tsx
+ * const shell = useShellInfo();
+ * return <>{shell?.capabilities.includes(ShellCapabilities.windowChrome) && <TitleBar />}</>;
+ * ```
+ *
+ * `undefined` means no host said anything — a plain browser tab, a host predating the handshake, or a
+ * handshake that has not finished. **Treat absent as "assume nothing", never as "assume desktop".**
+ *
+ * ⚠ **Await `bridge.notifyReady()` before rendering the tree that depends on this.** The value is read
+ * SYNCHRONOUSLY from the bridge's cache, deliberately — a capability learned after layout is a visible
+ * flash — which means this hook does not re-render when a handshake lands later. A component mounted
+ * mid-handshake sees `undefined` and keeps seeing it, which is the documented "assume nothing" tree
+ * rather than a wrong one, but it is not the tree you wanted.
+ *
+ * ⚠ This hook was referenced by two doc examples in this package for several releases before it
+ * existed — `bridge.shell` was the only way to read it. If you wrote that workaround, this replaces it.
+ */
+export function useShellInfo(bridge) {
+    return (bridge ?? getBridge()).shell;
 }
 /**
  * Subscribe to one (module, type) event for the component's lifetime, ported from the primary