@shenora/react 0.10.0 → 0.12.0

package/dist/eventBus.d.ts

@@ -4,24 +4,19 @@ export interface SubscribeOptions {
     /**
      * Only receive events carrying this app-defined scope. Omit to receive EVERY scope.
      *
-     * The semantics mirror the host's `EventBus` exactly, and both halves matter: an unscoped
-     * subscription sees every scope, AND a scope-less (global) event still reaches scoped subscribers —
-     * so an app-wide announcement is not swallowed by a per-scope listener.
+     * ⚠ Both halves of the host's `EventBus` rule apply: an unscoped subscription sees every scope, AND
+     * a scope-less (global) event still reaches scoped subscribers.
      */
     scope?: string;
 }
 /**
- * The client-side event hub, ported from the primary desktop sibling: host notifications are
- * unbundled into it by the bridge, and app code (or the dev interceptor) can emit locally.
- * 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.
+ * The client-side event hub: the bridge unbundles each host notification BATCH into it, and app code
+ * (or the dev interceptor) can emit locally. Event enums and maps are app schema, so apps layer their
+ * own typed wrappers on top. 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
- * `(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
- * asymmetric half of one concept and an observer that cannot enumerate the event vocabulary up front
- * had no supported expression at all.
+ * Three subscription breadths, mirroring the host's `Shenora.IEventBus`: an exact `(module, type)`
+ * pair, a whole {@link subscribeToModule | module}, or {@link subscribeToAll | everything}.
  */
 export declare class ShenoraEventBus {
     /** Exact `(module, type)` subscriptions, keyed by {@link eventKey}. */
@@ -39,34 +34,34 @@ export declare class ShenoraEventBus {
      * Subscribe to EVERY event from one module, whatever its type; returns the cleanup function.
      *
      * For a feature whose event vocabulary is open — plug-in-contributed types, a module that grows
-     * types over time — where enumerating pairs would mean editing the subscriber every time the host
-     * gains an event.
+     * types over time — where enumerating pairs means editing the subscriber for every new event.
      */
     subscribeToModule<TPayload = unknown>(module: string, handler: (event: EventMessage<TPayload>) => void, options?: SubscribeOptions): () => void;
     /**
      * Subscribe to EVERY event on the bus; returns the cleanup function.
      *
-     * The breadth is the point, so use it for cross-cutting observers — a diagnostics overlay, a
-     * telemetry tap, a bridge that folds the whole stream into another state library, or an adoption
-     * shim keeping a legacy "every host message" handler alive while individual features migrate onto
-     * exact pairs. It is NOT the way to consume one feature's events: prefer {@link subscribe}, which
-     * says what it listens for and does not wake for unrelated traffic.
+     * For cross-cutting observers — a diagnostics overlay, a telemetry tap, a bridge that folds the
+     * whole stream into another state library. ⚠ NOT the way to consume one feature's events: prefer
+     * {@link subscribe}, which says what it listens for and does not wake for unrelated traffic.
      */
     subscribeToAll<TPayload = unknown>(handler: (event: EventMessage<TPayload>) => void, options?: SubscribeOptions): () => void;
     /**
      * Emit to every matching subscriber (see {@link SubscribeOptions.scope} for the scope rule).
      *
-     * Delivery order is stable: exact pair, then whole-module, then catch-all — narrowest first, so a
-     * broad observer never runs ahead of the feature code it is observing.
+     * Delivery order is stable and narrowest-first: exact pair, then whole-module, then catch-all.
      */
     emit(event: EventMessage): void;
     /** 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.
      */
     getSubscriptionCount(module?: string, type?: string): number;
 }

package/dist/eventBus.js

@@ -1,15 +1,11 @@
 /**
- * The client-side event hub, ported from the primary desktop sibling: host notifications are
- * unbundled into it by the bridge, and app code (or the dev interceptor) can emit locally.
- * 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.
+ * The client-side event hub: the bridge unbundles each host notification BATCH into it, and app code
+ * (or the dev interceptor) can emit locally. Event enums and maps are app schema, so apps layer their
+ * own typed wrappers on top. 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
- * `(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
- * asymmetric half of one concept and an observer that cannot enumerate the event vocabulary up front
- * had no supported expression at all.
+ * Three subscription breadths, mirroring the host's `Shenora.IEventBus`: an exact `(module, type)`
+ * pair, a whole {@link subscribeToModule | module}, or {@link subscribeToAll | everything}.
  */
 export class ShenoraEventBus {
     constructor() {
@@ -31,8 +27,7 @@ export class ShenoraEventBus {
      * Subscribe to EVERY event from one module, whatever its type; returns the cleanup function.
      *
      * For a feature whose event vocabulary is open — plug-in-contributed types, a module that grows
-     * types over time — where enumerating pairs would mean editing the subscriber every time the host
-     * gains an event.
+     * types over time — where enumerating pairs means editing the subscriber for every new event.
      */
     subscribeToModule(module, handler, options = {}) {
         return addTo(this.byModule, module, newSubscription(handler, options));
@@ -40,11 +35,9 @@ export class ShenoraEventBus {
     /**
      * Subscribe to EVERY event on the bus; returns the cleanup function.
      *
-     * The breadth is the point, so use it for cross-cutting observers — a diagnostics overlay, a
-     * telemetry tap, a bridge that folds the whole stream into another state library, or an adoption
-     * shim keeping a legacy "every host message" handler alive while individual features migrate onto
-     * exact pairs. It is NOT the way to consume one feature's events: prefer {@link subscribe}, which
-     * says what it listens for and does not wake for unrelated traffic.
+     * For cross-cutting observers — a diagnostics overlay, a telemetry tap, a bridge that folds the
+     * whole stream into another state library. ⚠ NOT the way to consume one feature's events: prefer
+     * {@link subscribe}, which says what it listens for and does not wake for unrelated traffic.
      */
     subscribeToAll(handler, options = {}) {
         const subscription = newSubscription(handler, options);
@@ -54,19 +47,17 @@ export class ShenoraEventBus {
     /**
      * Emit to every matching subscriber (see {@link SubscribeOptions.scope} for the scope rule).
      *
-     * Delivery order is stable: exact pair, then whole-module, then catch-all — narrowest first, so a
-     * broad observer never runs ahead of the feature code it is observing.
+     * Delivery order is stable and narrowest-first: exact pair, then whole-module, then catch-all.
      */
     emit(event) {
         const exact = this.exact.get(eventKey(event.module, event.type));
         const byModule = this.byModule.get(event.module);
         if (!exact?.size && !byModule?.size && this.all.size === 0)
             return;
-        // Snapshot ALL THREE breadths before invoking any handler, not one at a time. A handler may
-        // subscribe or unsubscribe during delivery, and one event must reach exactly the subscribers
-        // that existed when it was emitted. Reading the broad collections lazily — after the exact
-        // handlers had already run — would let a handler that subscribes broadly while handling receive
-        // the very event it is handling. Copying per-set was enough while there was only one set.
+        // Snapshot ALL THREE breadths before invoking any handler, never one at a time: a handler may
+        // subscribe or unsubscribe during delivery, and one event must reach exactly the subscribers that
+        // existed when it was emitted. Reading the broad collections lazily would let a handler that
+        // subscribes broadly while handling receive the very event it is handling.
         for (const subscription of [...(exact ?? []), ...(byModule ?? []), ...this.all]) {
             if (!scopeMatches(subscription.scope, event.scope))
                 continue;
@@ -86,17 +77,31 @@ 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.
      */
     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;
@@ -109,7 +114,7 @@ export class ShenoraEventBus {
 function newSubscription(handler, options) {
     return { handler: handler, scope: options.scope };
 }
-/** Shared add-and-prune for the two keyed collections (an empty key is removed, as it always was). */
+/** Shared add-and-prune for the two keyed collections; an emptied key is removed. */
 function addTo(collection, key, subscription) {
     let set = collection.get(key);
     if (!set) {
@@ -127,18 +132,11 @@ function addTo(collection, key, subscription) {
     };
 }
 /**
- * `'\0'`-joined, NOT `.`-joined (P5.5 H6).
+ * `'\0'`-joined, NOT `.`-joined, matching the host's `EventBus`.
  *
- * Module and type are both arbitrary app-defined strings, so a `.` separator makes
+ * 🔴 Module and type are both arbitrary app-defined strings, so a `.` separator makes
  * `("APP", "TASK.DONE")` and `("APP.TASK", "DONE")` the same key — one app's events silently delivered
- * to another's subscribers. The host's `EventBus` fixed exactly this and documented it; the client kept
- * 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.
+ * to another's subscribers. `'\0'` cannot appear in a string literal a developer types by accident.
  */
 function eventKey(module, type) {
     return `${module}\0${type}`;

package/dist/fileDialogs.d.ts

@@ -7,8 +7,8 @@ export interface FileDialogFilter {
     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.
+ * What EVERY dialog call takes. The per-dialog shapes below add what only that dialog can honour, so a
+ * save-only field on a folder pick does not compile.
  */
 export interface FileDialogOptions {
     /** Dialog title. Omit for a neutral per-dialog default. */
@@ -83,7 +83,7 @@ interface FileDialogRequests {
     };
 }
 /**
- * Typed client for the host's `FILE_DIALOGS` module (`FileDialogFacade`).
+ * 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,
@@ -95,10 +95,9 @@ export declare class FileDialogs extends BaseModuleService<FileDialogRequests> {
     /** 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.
+     * Pick a folder. ⚠ DESKTOP only — gate on {@link FileDialogsHandle.canPickFolder}. There is no
+     * portable version: on mobile "open folder" means the camera roll, the app's own space, or a scoped
+     * grant — the same word with a different guarantee.
      */
     openFolder(options?: OpenFolderOptions): Promise<FileDialogResult>;
     /**
@@ -111,9 +110,8 @@ export declare class FileDialogs extends BaseModuleService<FileDialogRequests> {
      * 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.
+     * ⚠ 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` instead.
      */
     saveText(text: string, options?: SaveFileOptions): Promise<FileDialogResult>;
 }
@@ -143,8 +141,7 @@ export interface FileDialogsHandle {
  * ```
  *
  * ⚠ **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.
+ * `IpcErrorCodes.capabilityNotSupported` — 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.

package/dist/fileDialogs.js

@@ -1,16 +1,16 @@
 /**
- * The page's half of the host's `FILE_DIALOGS` module — native file/folder/save dialogs, and the
+ * 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.Ipc.FileDialogFacade`. The wire names here are pinned against the host's own
- * constants by `WireMirrorTests`, not by care.
+ * Mirrors `Shenora.Core.Ipc.FileDialogModule`, pinned against the host's own constants by
+ * `WireMirrorTests`.
  */
 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 `FILE_DIALOGS` module (`FileDialogFacade`).
+ * 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,
@@ -19,17 +19,16 @@ import { ShellCapabilities } from './types.js';
  */
 export class FileDialogs extends BaseModuleService {
     constructor(bridge) {
-        super('FILE_DIALOGS', 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.
+     * Pick a folder. ⚠ DESKTOP only — gate on {@link FileDialogsHandle.canPickFolder}. There is no
+     * portable version: on mobile "open folder" means the camera roll, the app's own space, or a scoped
+     * grant — the same word with a different guarantee.
      */
     openFolder(options) {
         return this.send('OPEN_FOLDER', { payload: { options } });
@@ -46,9 +45,8 @@ export class FileDialogs extends BaseModuleService {
      * 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.
+     * ⚠ 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` instead.
      */
     saveText(text, options) {
         return this.send('SAVE_TEXT', { payload: { text, options } });
@@ -69,16 +67,14 @@ export class FileDialogs extends BaseModuleService {
  * ```
  *
  * ⚠ **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.
+ * `IpcErrorCodes.capabilityNotSupported` — 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.
+    // Cached so it is usable as an effect dependency, not because the service is expensive.
     const client = useMemo(() => dialogs ?? new FileDialogs(), [dialogs]);
     const capabilities = shell?.capabilities;
     return useMemo(() => ({

package/dist/hooks.d.ts

@@ -1,7 +1,13 @@
 import { type ShenoraBridge } from './bridge.js';
 import { type ShenoraEventBus } from './eventBus.js';
 import type { EventMessage, ShellInfo } from './types.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 not as a micro-optimisation. A fresh object every render is a fresh
+ * dependency for every hook that lists it, so `useEffect(…, [shenora])` would re-run on EVERY render.
+ * The identity changes only when the bridge does, or when `isAvailable` flips as a host attaches.
+ */
 export declare function useShenora(): {
     isAvailable: boolean;
     bridge: ShenoraBridge;
@@ -19,25 +25,18 @@ export declare function useShenora(): {
  * 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.
+ * SYNCHRONOUSLY from the bridge's cache — a capability learned after layout is a visible flash — so
+ * this hook does NOT re-render when a handshake lands later. A component mounted mid-handshake sees
+ * `undefined` and keeps seeing it: the "assume nothing" tree, not the one you wanted.
  */
 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
- * from the source: instead of a deps array re-subscribing on change, the latest handler is kept
- * in a ref — no re-subscribe churn, no stale-closure trap.
+ * Subscribe to one (module, type) event for the component's lifetime. The handler receives the
+ * unwrapped payload plus the full event, and is kept in a ref rather than in the effect key — no
+ * re-subscribe churn, no stale-closure trap.
  *
- * Pass `scope` for a scoped app: the wire carries a scope and the host keys on it, but this hook had
- * no way to express one, so a component in profile A also woke for profile B's events with no filter
- * available (P5.5 H6). Omitting it still means "every scope", and a global (scope-less) event still
- * reaches a scoped subscriber — the host's rule, mirrored.
+ * Pass `scope` for a scoped app, or a component in profile A also wakes for profile B's events.
+ * Omitting it means "every scope", and a global (scope-less) event still reaches a scoped subscriber.
  */
 export declare function useShenoraEvent<TPayload = unknown>(module: string, type: string, handler: (payload: TPayload, event: EventMessage<TPayload>) => void, options?: {
     bus?: ShenoraEventBus;
@@ -53,10 +52,10 @@ export interface ShenoraQueryResult<TData> {
     refetch: () => void;
 }
 /**
- * Fetch-on-mount over the bridge: `invoke` + `{data, error, loading, refetch}`. Deliberately
- * minimal — no caching, no dedup, no background refresh (headless, D13): apps with data-layer
- * needs bring their own query library and call `bridge.invoke` from it. The payload participates
- * in the effect key BY VALUE (JSON), so inline object literals don't refetch every render.
+ * Fetch-on-mount over the bridge: `invoke` + `{data, error, loading, refetch}`. Minimal — no caching,
+ * no dedup, no background refresh; an app with data-layer needs brings its own query library and calls
+ * `bridge.invoke` from it. The payload participates in the effect key BY VALUE (JSON), so an inline
+ * object literal does not refetch every render.
  */
 export declare function useShenoraQuery<TData = unknown, TPayload = unknown>(module: string, type: string, options?: {
     payload?: TPayload;

package/dist/hooks.js

@@ -1,10 +1,17 @@
-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 not as a micro-optimisation. A fresh object every render is a fresh
+ * dependency for every hook that lists it, so `useEffect(…, [shenora])` would re-run on EVERY render.
+ * The identity changes only when the bridge does, or when `isAvailable` flips as a host attaches.
+ */
 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.
@@ -19,27 +26,20 @@ export function useShenora() {
  * 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.
+ * SYNCHRONOUSLY from the bridge's cache — a capability learned after layout is a visible flash — so
+ * this hook does NOT re-render when a handshake lands later. A component mounted mid-handshake sees
+ * `undefined` and keeps seeing it: the "assume nothing" tree, not the one you wanted.
  */
 export function useShellInfo(bridge) {
     return (bridge ?? getBridge()).shell;
 }
 /**
- * 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
- * from the source: instead of a deps array re-subscribing on change, the latest handler is kept
- * in a ref — no re-subscribe churn, no stale-closure trap.
+ * Subscribe to one (module, type) event for the component's lifetime. The handler receives the
+ * unwrapped payload plus the full event, and is kept in a ref rather than in the effect key — no
+ * re-subscribe churn, no stale-closure trap.
  *
- * Pass `scope` for a scoped app: the wire carries a scope and the host keys on it, but this hook had
- * no way to express one, so a component in profile A also woke for profile B's events with no filter
- * available (P5.5 H6). Omitting it still means "every scope", and a global (scope-less) event still
- * reaches a scoped subscriber — the host's rule, mirrored.
+ * Pass `scope` for a scoped app, or a component in profile A also wakes for profile B's events.
+ * Omitting it means "every scope", and a global (scope-less) event still reaches a scoped subscriber.
  */
 export function useShenoraEvent(module, type, handler, options = {}) {
     const handlerRef = useRef(handler);
@@ -49,10 +49,10 @@ export function useShenoraEvent(module, type, handler, options = {}) {
     useEffect(() => bus.subscribe(module, type, (event) => handlerRef.current(event.payload, event), { scope }), [module, type, bus, scope]);
 }
 /**
- * Fetch-on-mount over the bridge: `invoke` + `{data, error, loading, refetch}`. Deliberately
- * minimal — no caching, no dedup, no background refresh (headless, D13): apps with data-layer
- * needs bring their own query library and call `bridge.invoke` from it. The payload participates
- * in the effect key BY VALUE (JSON), so inline object literals don't refetch every render.
+ * Fetch-on-mount over the bridge: `invoke` + `{data, error, loading, refetch}`. Minimal — no caching,
+ * no dedup, no background refresh; an app with data-layer needs brings its own query library and calls
+ * `bridge.invoke` from it. The payload participates in the effect key BY VALUE (JSON), so an inline
+ * object literal does not refetch every render.
  */
 export function useShenoraQuery(module, type, options = {}) {
     const { payload, scope, enabled = true } = options;
@@ -68,8 +68,8 @@ export function useShenoraQuery(module, type, options = {}) {
     payloadRef.current = payload;
     useEffect(() => {
         if (!enabled) {
-            // A fetch in flight when enabled flipped false was marked stale by the cleanup — without
-            // this, `loading` would stay true forever (a spinner that never stops).
+            // The cleanup marked any in-flight fetch stale, so without this `loading` would stay true
+            // forever: a spinner that never stops.
             setState((previous) => (previous.loading ? { ...previous, loading: false } : previous));
             return;
         }
@@ -79,11 +79,8 @@ export function useShenoraQuery(module, type, options = {}) {
             .invoke(module, type, { payload: payloadRef.current, scope })
             .then((data) => { if (!stale)
             setState({ data, error: undefined, loading: false }); }, 
-        // KEEP the previous data alongside the error (P5.5 H2). This used to set `data: undefined`, so
-        // a failed REFETCH — a transient host hiccup, one timed-out call — blanked data the UI was
-        // already showing correctly, turning a recoverable error into an empty screen. The caller has
-        // both fields and can decide: render stale data with an error banner, or hide it. Blanking it
-        // for them removes that choice. (A first fetch has no previous data, so it is unaffected.)
+        // KEEP the previous data alongside the error, so a failed REFETCH does not blank a screen the
+        // UI was showing correctly. The caller has both fields and decides which to render.
         (error) => { if (!stale)
             setState((previous) => ({ data: previous.data, error, loading: false })); });
         return () => { stale = true; };

package/dist/index.d.ts

@@ -1,14 +1,20 @@
 export { IpcCategories, IpcErrorCodes, HANDSHAKE_MODULE, HANDSHAKE_TYPE, type IpcRequest, type IpcResponse, type IpcError, type IpcNotification, type IpcNotificationBatch, type EventMessage, ShellCapabilities, type ShellInfo, } from './types.js';
-export { OperationError } from './errors.js';
+export { ShenoraError } from './errors.js';
 export { isShenoraAvailable, createHostTransport, createWebView2Transport, createHybridWebViewTransport, type ShenoraTransport, } from './transport.js';
 export { ShenoraEventBus, eventBus, type SubscribeOptions, } from './eventBus.js';
 export { ShenoraBridge, getBridge, configureBridge, type ShenoraBridgeOptions, type InvokeOptions, type PostOptions, type PostFailure, } from './bridge.js';
 export { createShenoraStore, type ShenoraStore, type ShenoraStoreOptions, type ShenoraStoreIo, type ShenoraStoreSnapshot, } from './store.js';
 export { BaseModuleService } from './moduleService.js';
-export { OperationStatuses, OperationEventTypes, OperationModuleName, createOperationsStore, useShenoraOperations, type OperationStatus, type OperationLabel, type OperationProgress, type OperationInfo, type OperationsState, type OperationsActions, type OperationsStoreOptions, } from './operations.js';
+export { IpcRequestStates, IpcRequestEventTypes, IpcRequestRoutes, IpcRequestsModuleName, createRequestsStore, useShenoraRequests, type IpcRequestState, type IpcLabel, type IpcProgress, type IpcRequestStatus, type RequestsState, type RequestsActions, type RequestsStoreOptions, } from './requests.js';
 export { WindowCommands, useWindowMaximized, type WindowResizeEdge, type CaptionButtonKind, type CaptionButtonRect, } from './windowCommands.js';
 export { useDropZone, DROP_ZONE_MODULE, type DropZoneFileDrop, type UseDropZoneOptions, } from './useDropZone.js';
 export { useShenora, useShenoraEvent, useShenoraQuery, useShellInfo, type ShenoraQueryResult, } from './hooks.js';
 export { FileDialogs, useFileDialogs, type FileDialogFilter, type FileDialogOptions, type OpenFileOptions, type OpenFolderOptions, type SaveFileOptions, type FileDialogResult, type FileDialogsHandle, } from './fileDialogs.js';
+export { ClipboardAccess, useClipboard, PNG_IMAGE, HTML, type ClipboardContent, type ClipboardHandle, } from './clipboard.js';
 export { installDevInterceptor, type DevInterceptorOptions, type DevIpcEntry, type DevEventEntry, } from './devInterceptor.js';
 export { mediaUrl, encodeMediaPayload, decodeMediaPayload } from './media.js';
+export { parseManifest, pickMediaSource, nextSegment, segmentMimeType, codecsFromInitSegment, remoteSegmentUrl, SEGMENT_REMOTE_PREFIX, } from './segmentStream.js';
+export { bindSegmentStream, SegmentBinderError } from './segmentBinder.js';
+export type { SegmentBinderOptions, SegmentBinding } from './segmentBinder.js';
+export type { SegmentEntry, SegmentManifest, MediaSourceKind, MediaSourceGlobals, FetchState, FetchPolicy, } from './segmentStream.js';
+export { useMediaPlayer, MEDIA_PLAYER_MODULE, MEDIA_PLAYER_REPORT, MEDIA_PLAYER_STATUS, MediaPlayerCommands, MediaConversionEvents, MediaConversionErrorCodes, type MediaPlayerReport, type MediaPlayerReportState, type UseMediaPlayerOptions, } from './mediaPlayer.js';

package/dist/index.js

@@ -3,24 +3,28 @@
 // React hooks, and the dev interceptor for CDP-driven testing. Headless by design (D13): no UI
 // components, no design-system dependency — apps bring their own.
 export { IpcCategories, IpcErrorCodes, HANDSHAKE_MODULE, HANDSHAKE_TYPE, ShellCapabilities, } from './types.js';
-export { OperationError } from './errors.js';
+export { ShenoraError } from './errors.js';
 export { isShenoraAvailable, createHostTransport, createWebView2Transport, createHybridWebViewTransport, } from './transport.js';
 export { ShenoraEventBus, eventBus, } from './eventBus.js';
 export { ShenoraBridge, getBridge, configureBridge, } from './bridge.js';
 export { createShenoraStore, } from './store.js';
 export { BaseModuleService } from './moduleService.js';
-export { OperationStatuses, 
-// The event vocabulary + the default module name. `createOperationsStore` deliberately does NOT
-// subscribe to RESUME_REQUESTED / WAIT_REQUESTED — those target the OWNING module's own service,
-// not the generic store — so the app writing that handler needs both symbols, and until now had
-// neither: it had to hard-code the literals the wire-mirror tests exist to keep it from doing.
-OperationEventTypes, OperationModuleName, createOperationsStore, useShenoraOperations, } from './operations.js';
+export { IpcRequestStates, 
+// The event and route vocabulary + the default module name, so an app handling or cancelling a
+// request without `useShenoraRequests` never types the wire literals by hand.
+IpcRequestEventTypes, IpcRequestRoutes, IpcRequestsModuleName, createRequestsStore, useShenoraRequests, } from './requests.js';
 export { WindowCommands, useWindowMaximized, } from './windowCommands.js';
 export { useDropZone, DROP_ZONE_MODULE, } from './useDropZone.js';
 export { useShenora, useShenoraEvent, useShenoraQuery, useShellInfo, } from './hooks.js';
-// Native dialogs, capability-gated. The client half of the host's FILE_DIALOGS module.
+// Native dialogs, capability-gated. The client half of the host's SHENORA.DIALOGS module.
 export { FileDialogs, useFileDialogs, } from './fileDialogs.js';
+// The native clipboard, for the two things navigator.clipboard cannot do: FILES, and access with no
+// user gesture. The client half of the host's SHENORA.CLIPBOARD module.
+export { ClipboardAccess, useClipboard, PNG_IMAGE, HTML, } from './clipboard.js';
 export { installDevInterceptor, } from './devInterceptor.js';
-// Addressing local content the page cannot reach itself. A pure function, not a hook — building the URL
-// needs no React, and a `useMediaSource` can follow if an adopter wants load/error state.
+// Addressing local content the page cannot reach itself. Pure functions, not hooks.
 export { mediaUrl, encodeMediaPayload, decodeMediaPayload } from './media.js';
+export { parseManifest, pickMediaSource, nextSegment, segmentMimeType, codecsFromInitSegment, remoteSegmentUrl, SEGMENT_REMOTE_PREFIX, } from './segmentStream.js';
+export { bindSegmentStream, SegmentBinderError } from './segmentBinder.js';
+// The HOST-owned player (D58): .NET holds the lifecycle, the page's element is the display and the sound.
+export { useMediaPlayer, MEDIA_PLAYER_MODULE, MEDIA_PLAYER_REPORT, MEDIA_PLAYER_STATUS, MediaPlayerCommands, MediaConversionEvents, MediaConversionErrorCodes, } from './mediaPlayer.js';

package/dist/internal.d.ts

@@ -1,12 +1,6 @@
 /**
  * Shared internals for `@shenora/react`. NOT exported from the barrel — nothing here is public
  * surface, and it must not become so by accident.
- *
- * These lived as per-file copies until a second consumer appeared for each (P5.5 H2): the debounce
- * helper was private to `useDropZone` and `useWindowMaximized` needed the same thing, and the
- * `randomUUID`-with-fallback pair had drifted into two spellings. H4.5 deliberately left both alone
- * at the time, on the grounds that the package had no shared-internals home and inventing one for a
- * single consumer is speculation — this file exists now because the need is real.
  */
 /** A debounced void callback with a `cancel` for effect teardown. */
 export interface Debounced {
@@ -19,7 +13,7 @@ export interface Debounced {
  */
 export declare function debounce(fn: () => void, ms: number): Debounced;
 /**
- * A unique id, optionally prefixed. Correlation ids and zone ids only need uniqueness, not entropy,
- * so the non-`crypto` fallback (ancient or non-secure-context environments) is fine.
+ * A unique id, optionally prefixed. Correlation ids and zone ids need uniqueness, not entropy, so the
+ * non-`crypto` fallback for a non-secure context is fine.
  */
 export declare function randomId(prefix?: string): string;