@shenora/react 0.10.0 → 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

@@ -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,

package/dist/fileDialogs.js

@@ -1,8 +1,8 @@
 /**
- * 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
+ * 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';
@@ -10,7 +10,7 @@ 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,7 +19,7 @@ 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) {

package/dist/hooks.d.ts

@@ -1,7 +1,15 @@
 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 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;

package/dist/hooks.js

@@ -1,10 +1,19 @@
-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.

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, } 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, MediaPlayerCommands, type MediaPlayerReport, type MediaPlayerReportState, type UseMediaPlayerOptions, } from './mediaPlayer.js';

package/dist/index.js

@@ -3,24 +3,36 @@
 // 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
+export { IpcRequestStates, 
+// The event vocabulary + the default module name. `createRequestsStore` 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';
+IpcRequestEventTypes, 
+// The ROUTE half of that same wire, and it was the one left behind: an app cancelling a request
+// without `useShenoraRequests` had the module name and the event names but had to hard-code
+// 'CANCEL'. Pinned by `WireMirrorTests.Request_route_names_match_the_hosts_module`.
+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.
 export { mediaUrl, encodeMediaPayload, decodeMediaPayload } from './media.js';
+export { parseManifest, pickMediaSource, nextSegment, segmentMimeType, codecsFromInitSegment, } 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.
+// One hook, and the page stops deciding anything about formats.
+export { useMediaPlayer, MEDIA_PLAYER_MODULE, MEDIA_PLAYER_REPORT, MediaPlayerCommands, } from './mediaPlayer.js';

package/dist/mediaPlayer.d.ts

@@ -0,0 +1,86 @@
+import { type RefObject } from 'react';
+import { type ShenoraBridge } from './bridge.js';
+import { type ShenoraEventBus } from './eventBus.js';
+/**
+ * The module the player speaks on. Matches `MediaPlayerOptions.Access.Module` on the host (the
+ * containment/module boundary every media delivery path shares — `MediaAccessOptions`, D71), which
+ * defaults to the same string — change one and you must change the other.
+ *
+ * ⚠ The `SHENORA.` prefix is RESERVED for the kit's own modules (D64), beside the handshake's bare
+ * `SHENORA`. It exists so your app stays free to own a module called plainly `MEDIA`.
+ */
+export declare const MEDIA_PLAYER_MODULE = "SHENORA.MEDIA";
+/**
+ * Commands the host sends. **A wire contract**: these strings are duplicated in C# as
+ * `MediaPlayerEvents`, and the two halves agree by string or not at all.
+ */
+export declare const MediaPlayerCommands: {
+    readonly load: "PLAYER_LOAD";
+    readonly play: "PLAYER_PLAY";
+    readonly pause: "PLAYER_PAUSE";
+    readonly seek: "PLAYER_SEEK";
+    readonly rate: "PLAYER_RATE";
+    readonly unload: "PLAYER_UNLOAD";
+};
+/** The one message the page sends back. The host turns it into `MediaPlayer.Report(...)`. */
+export declare const MEDIA_PLAYER_REPORT = "PLAYER_REPORT";
+/**
+ * What the element is doing, in the host's vocabulary (`MediaPlayerState`).
+ *
+ * ⚠ `opening` and `buffering` are distinct, matching the host: opening is "no position yet", buffering is
+ * "had one and it stopped moving". Collapsing them makes a UI extrapolate a position that is not advancing.
+ */
+export type MediaPlayerReportState = 'Empty' | 'Opening' | 'Paused' | 'Playing' | 'Buffering' | 'Ended' | 'Failed';
+/** One state report, sent on TRANSITIONS only. */
+export interface MediaPlayerReport {
+    state: MediaPlayerReportState;
+    /** Seconds. */
+    position: number;
+    /** Seconds, or null for a live stream / not yet known. */
+    duration: number | null;
+    /** A short reason when `state` is `Failed`; never the platform's raw text. */
+    error?: string;
+}
+/** Inputs for {@link useMediaPlayer}. */
+export interface UseMediaPlayerOptions {
+    /** Override the module. Must match the host's `MediaPlayerOptions.Access.Module`. */
+    module?: string;
+    /** Test seams. */
+    bridge?: ShenoraBridge;
+    eventBus?: ShenoraEventBus;
+}
+/**
+ * Bind a `<video>`/`<audio>` element to the HOST's player: the element becomes the display and the sound,
+ * and .NET owns the lifecycle (D58).
+ *
+ * ```tsx
+ * const ref = useRef<HTMLVideoElement>(null);
+ * useMediaPlayer(ref);
+ * return <video ref={ref} playsInline />;
+ * ```
+ *
+ * **That is the whole page-side integration.** No `src`, no play button wiring, no state machine — the app
+ * calls `IMediaPlayer.OpenAsync/PlayAsync` in C#, and this drives the element to match. The page keeps what
+ * it is good at (rendering) and gives up what it was never good at (deciding whether a file can be played
+ * at all, which needs a probe and a device capability query).
+ *
+ * ⚠ **The host half needs nothing from you.** The reports posted here are an ordinary IPC message
+ * (`PLAYER_REPORT` on {@link MEDIA_PLAYER_MODULE}) and the kit's own `MediaPlayerModule` answers it,
+ * registered by the media feature itself. If you wrote that route by hand against a build from before
+ * 2026-08-07, **delete it** — two facades on one module is a duplicate the host rejects.
+ *
+ * ⚠ **The element must exist when this effect first runs.** `ref.current` is read once, and a `useRef`
+ * object is stable, so an element rendered CONDITIONALLY (`{ready && <video ref={ref} />}`) mounts after
+ * the effect and never binds — silently. Render the element unconditionally and hide it with CSS, or key
+ * the component so the hook remounts with it.
+ *
+ * ⚠ **It reports on TRANSITIONS, never on `timeupdate`.** That event fires ~4×/second and forwarding it
+ * would cost battery and IPC to tell the host something it can extrapolate from a position and a rate. If
+ * you need a moving scrubber, read `element.currentTime` in your own render loop — locally, at the rate you
+ * actually redraw.
+ *
+ * ⚠ **Autoplay policies still apply.** A `PLAYER_PLAY` arriving before any user gesture can be refused by
+ * the browser, and the element reports `Failed`. That is the platform's rule, not the kit's, and the host
+ * hears about it rather than silently believing playback started.
+ */
+export declare function useMediaPlayer(ref: RefObject<HTMLMediaElement | null>, options?: UseMediaPlayerOptions): void;