@shenora/react 0.10.0 → 0.11.0

package/dist/mediaPlayer.js

@@ -0,0 +1,192 @@
+import { useEffect } from 'react';
+import { getBridge } from './bridge.js';
+import { eventBus as defaultEventBus } 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 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 const MediaPlayerCommands = {
+    load: 'PLAYER_LOAD',
+    play: 'PLAYER_PLAY',
+    pause: 'PLAYER_PAUSE',
+    seek: 'PLAYER_SEEK',
+    rate: 'PLAYER_RATE',
+    unload: 'PLAYER_UNLOAD',
+};
+/** The one message the page sends back. The host turns it into `MediaPlayer.Report(...)`. */
+export const MEDIA_PLAYER_REPORT = 'PLAYER_REPORT';
+/**
+ * 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 function useMediaPlayer(ref, options = {}) {
+    const { module = MEDIA_PLAYER_MODULE, bridge, eventBus = defaultEventBus } = options;
+    useEffect(() => {
+        const element = ref.current;
+        if (!element)
+            return;
+        const link = bridge ?? getBridge();
+        // The element is the only clock: the host asks IT for position rather than tracking its own, so a
+        // report always carries what the element actually believes.
+        const report = (state, error) => {
+            const duration = Number.isFinite(element.duration) ? element.duration : null;
+            const payload = {
+                state,
+                position: Number.isFinite(element.currentTime) ? element.currentTime : 0,
+                duration,
+                ...(error ? { error } : {}),
+            };
+            link.post(module, MEDIA_PLAYER_REPORT, { payload });
+        };
+        // The PENDING start-at seek, if any. 🔴 It has to be cancellable: `{ once: true }` removes a listener
+        // only when it FIRES, and a second PLAYER_LOAD calls `element.load()`, which aborts the first load so
+        // its `loadedmetadata` never comes. The stale listener then survives and runs on the NEXT track's
+        // metadata — so loading A at 10:00 and then B at 0:00 starts B ten minutes in, because B sets no
+        // listener of its own and A's is still attached.
+        let pendingSeek = null;
+        const cancelPendingSeek = () => {
+            if (pendingSeek)
+                element.removeEventListener('loadedmetadata', pendingSeek);
+            pendingSeek = null;
+        };
+        // ── host → element ────────────────────────────────────────────────────────────────────────────
+        const subscriptions = [
+            eventBus.subscribe(module, MediaPlayerCommands.load, (message) => {
+                const { uri, startAt } = message.payload ?? { uri: '', startAt: 0 };
+                element.src = uri;
+                // load() rather than trusting the src assignment: a second load on the same element keeps the
+                // previous buffer otherwise, and a seek then lands in the OLD media.
+                element.load();
+                cancelPendingSeek(); // this load supersedes any earlier one — see pendingSeek
+                if (startAt > 0) {
+                    const seek = () => { pendingSeek = null; element.currentTime = startAt; };
+                    // `loadedmetadata` is the earliest point currentTime is settable — before it, the assignment is
+                    // silently dropped and the item starts at zero.
+                    pendingSeek = seek;
+                    element.addEventListener('loadedmetadata', seek, { once: true });
+                }
+            }),
+            eventBus.subscribe(module, MediaPlayerCommands.play, () => {
+                // A rejected play() is an autoplay refusal, and the host must hear it rather than assume success.
+                // ⚠ Read `.name` STRUCTURALLY rather than testing `instanceof Error`: the value browsers reject
+                // with is a DOMException, which is not an Error subclass everywhere (jsdom's is not), and a page
+                // can reject with anything at all. The name is the stable, app-safe part — `NotAllowedError` is
+                // what an autoplay block actually says, and it is the one an adopter will want to branch on.
+                void element.play().catch((cause) => {
+                    const name = cause?.name;
+                    report('Failed', typeof name === 'string' && name ? name : 'PlayRejected');
+                });
+            }),
+            eventBus.subscribe(module, MediaPlayerCommands.pause, () => element.pause()),
+            eventBus.subscribe(module, MediaPlayerCommands.seek, (message) => {
+                element.currentTime = message.payload?.position ?? 0;
+            }),
+            eventBus.subscribe(module, MediaPlayerCommands.rate, (message) => {
+                element.playbackRate = message.payload?.rate ?? 1;
+            }),
+            eventBus.subscribe(module, MediaPlayerCommands.unload, () => {
+                element.pause();
+                element.removeAttribute('src');
+                // ⚠ load() after clearing src is what actually FREES the buffer. Without it the element keeps the
+                // decoded data alive, which on a phone is the difference between releasing memory and not.
+                element.load();
+                report('Empty');
+            }),
+        ];
+        // ── element → host ────────────────────────────────────────────────────────────────────────────
+        // Transitions only. `timeupdate` is deliberately absent — see the remarks.
+        const listeners = [
+            ['loadedmetadata', () => report('Paused')],
+            ['canplay', () => report(element.paused ? 'Paused' : 'Playing')],
+            ['play', () => report('Playing')],
+            ['playing', () => report('Playing')],
+            ['pause', () => report(element.ended ? 'Ended' : 'Paused')],
+            ['waiting', () => report('Buffering')],
+            ['seeked', () => report(element.paused ? 'Paused' : 'Playing')],
+            ['ended', () => report('Ended')],
+            ['error', () => report('Failed', mediaErrorReason(element))],
+        ];
+        for (const [event, handler] of listeners)
+            element.addEventListener(event, handler);
+        // 🔴 REPORT WHEN THE PAGE IS ABOUT TO BE HIDDEN, or the host's position is whatever the last
+        // TRANSITION left — which for steady playback is the moment it started.
+        //
+        // Measured on an Android emulator 2026-08-15: with transition-only reporting the page sat at 19.79 s
+        // while the host believed 0.01 s, and `BackgroundPlaybackTransfer` handed the native player 0.01 s.
+        // The user backgrounds mid-film and resumes from the beginning. The platform's `pause` at background
+        // time does fire, but not in time to cross IPC before the process is frozen.
+        //
+        // ⚠ `visibilitychange` rather than `pagehide`: this fires while the document is still alive and the
+        // bridge can still post, and it is the signal both mobile shells raise on the way to the background.
+        // It costs ONE report per background — nothing like `timeupdate`'s ~4/second, which is why that one
+        // is still deliberately absent.
+        const onHidden = () => {
+            if (document.visibilityState !== 'hidden')
+                return;
+            report(element.paused ? (element.ended ? 'Ended' : 'Paused') : 'Playing');
+        };
+        document.addEventListener('visibilitychange', onHidden);
+        return () => {
+            for (const subscription of subscriptions)
+                subscription();
+            for (const [event, handler] of listeners)
+                element.removeEventListener(event, handler);
+            cancelPendingSeek();
+            document.removeEventListener('visibilitychange', onHidden);
+        };
+    }, [ref, module, bridge, eventBus]);
+}
+/**
+ * A short, stable reason from `MediaError`.
+ *
+ * ⚠ Deliberately NOT `error.message`: browsers put decoder internals and sometimes the full URL in it, and
+ * this string crosses to the host and can reach a log. The host applies the same rule to platform errors.
+ */
+function mediaErrorReason(element) {
+    switch (element.error?.code) {
+        case 1: return 'Aborted';
+        case 2: return 'Network';
+        case 3: return 'Decode';
+        case 4: return 'SourceNotSupported';
+        default: return 'Unknown';
+    }
+}

package/dist/moduleService.d.ts

@@ -9,11 +9,18 @@ import { type ShenoraBridge } from './bridge.js';
  * interface NoteRequests { GET_ALL: void; ADD: { title: string } }
  * class NoteService extends BaseModuleService<NoteRequests> {
  *   constructor() { super('NOTES'); }
- *   getAll() { return this.send<Note[]>('GET_ALL'); }
- *   add(title: string) { return this.send<Note>('ADD', { payload: { title } }); }
+ *   getAll(): Promise<Note[]> { return this.send('GET_ALL'); }
+ *   add(title: string): Promise<Note> { return this.send('ADD', { payload: { title } }); }
  * }
  * ```
  *
+ * 🔴 **DECLARE THE RETURN TYPE; NEVER WRITE `send<Note>(…)`.** TypeScript has no partial type-argument
+ * inference, so naming the response argument makes `TType` fall back to its DEFAULT — the union of every
+ * key — and `payload` collapses to the union of every route's payload. The check silently stops
+ * checking: `send<Note>('ADD', { payload: { notAField: 1 } })` compiles clean, while the same call
+ * without the type argument is a TS2353. The response is inferred from the method's declared return
+ * type instead, which every method here has anyway. `moduleService.test.ts` pins both halves.
+ *
  * DEVIATION from the source: its boolean/array/optional convenience wrappers were pure casts
  * around the same call — the response generic already expresses them, so they're gone.
  *

package/dist/moduleService.js

@@ -9,11 +9,18 @@ import { getBridge } from './bridge.js';
  * interface NoteRequests { GET_ALL: void; ADD: { title: string } }
  * class NoteService extends BaseModuleService<NoteRequests> {
  *   constructor() { super('NOTES'); }
- *   getAll() { return this.send<Note[]>('GET_ALL'); }
- *   add(title: string) { return this.send<Note>('ADD', { payload: { title } }); }
+ *   getAll(): Promise<Note[]> { return this.send('GET_ALL'); }
+ *   add(title: string): Promise<Note> { return this.send('ADD', { payload: { title } }); }
  * }
  * ```
  *
+ * 🔴 **DECLARE THE RETURN TYPE; NEVER WRITE `send<Note>(…)`.** TypeScript has no partial type-argument
+ * inference, so naming the response argument makes `TType` fall back to its DEFAULT — the union of every
+ * key — and `payload` collapses to the union of every route's payload. The check silently stops
+ * checking: `send<Note>('ADD', { payload: { notAField: 1 } })` compiles clean, while the same call
+ * without the type argument is a TS2353. The response is inferred from the method's declared return
+ * type instead, which every method here has anyway. `moduleService.test.ts` pins both halves.
+ *
  * DEVIATION from the source: its boolean/array/optional convenience wrappers were pure casts
  * around the same call — the response generic already expresses them, so they're gone.
  *

package/dist/requests.d.ts

@@ -0,0 +1,176 @@
+import type { ShenoraBridge } from './bridge.js';
+import type { ShenoraEventBus } from './eventBus.js';
+import { type ShenoraStore } from './store.js';
+import type { IpcError } from './types.js';
+/**
+ * Mirrors `Shenora.Core.Ipc.IpcRequestState` (design §4.2) — crosses the wire as its camelCase name for
+ * free: `IpcJson` already installs a camelCase `JsonStringEnumConverter`, so no per-type wiring is
+ * needed on either side. Pinned against the host by
+ * `WireMirrorTests.Every_request_state_exists_on_both_sides` — a status added on one side and
+ * not the other fails that test by name, not by a green suite that never looked.
+ */
+export declare const IpcRequestStates: {
+    readonly Running: "running";
+    readonly Completed: "completed";
+    readonly Failed: "failed";
+    readonly Cancelled: "cancelled";
+};
+/** One of {@link IpcRequestStates}. */
+export type IpcRequestState = (typeof IpcRequestStates)[keyof typeof IpcRequestStates];
+/**
+ * Mirrors `Shenora.Core.Ipc.IpcRequestEvents` — pinned against the host by
+ * `WireMirrorTests.Request_event_names_match_the_host` (ALSO IN THIS BATCH, whole-branch review):
+ * these were bare string literals with nothing comparing them to the host's own constants, so a host
+ * rename left the suite green and the client permanently deaf to the renamed event.
+ */
+export declare const IpcRequestEventTypes: {
+    readonly Updated: "REQUEST_UPDATED";
+    /**
+     * One or more request ids left the host with no corresponding `Updated` snapshot — history eviction
+     * and `CLEAR_FINISHED`. Payload is `{ requestIds: string[] }`; {@link createRequestsStore} folds it
+     * by deleting those ids. One authoritative event, so a client never has to guess what the host
+     * removed.
+     */
+    readonly Removed: "REQUEST_REMOVED";
+};
+/**
+ * Mirrors the route names `Shenora.Modules.Requests.IpcRequestsModule` switches on (its own
+ * `ListType`/`CancelType`/`ClearFinishedType`/`ResumeType` constants) — pinned by
+ * `WireMirrorTests.Request_route_names_match_the_hosts_module`, same rationale as
+ * {@link IpcRequestEventTypes}.
+ */
+export declare const IpcRequestRoutes: {
+    readonly List: "LIST";
+    readonly Cancel: "CANCEL";
+    readonly ClearFinished: "CLEAR_FINISHED";
+};
+/**
+ * Default `Shenora.Core.Ipc.IpcRequestTrackerOptions.ModuleName` — pinned by
+ * `WireMirrorTests.The_default_requests_module_name_matches_the_host`.
+ */
+export declare const IpcRequestsModuleName = "SHENORA.REQUESTS";
+/**
+ * Mirrors `Shenora.Core.Ipc.IpcLabel` — human-facing text the HOST never renders itself: an
+ * untranslated fallback plus an app i18n key and interpolation parameters (headless, D13).
+ */
+export interface IpcLabel {
+    text?: string;
+    key?: string;
+    parameters?: Record<string, string>;
+}
+/**
+ * Mirrors `Shenora.Core.Ipc.IpcProgress` — how far a tracked operation has gotten, in the APP's own
+ * unit, never a kit-assumed percent (generic-library audit, before publish: percent is not the
+ * mechanism, it is one way an app happens to measure). `total` is the denominator when one is known;
+ * `undefined` means there is NO known total — an absolute count with nothing to divide by (bytes
+ * streamed so far off a chunked response, say), never zero. `unit` is app-defined, like `kind`
+ * (`'bytes'`, `'files'`, `'percent'`) — the kit never interprets it and ships no percent helper: render
+ * a ratio only when `total` is set, e.g. `total ? (value / total) * 100 : undefined` — that division
+ * is the consumer's own policy (see the README example).
+ */
+export interface IpcProgress {
+    value: number;
+    total?: number;
+    unit?: string;
+}
+/**
+ * Mirrors `Shenora.Core.Ipc.IpcRequestStatus` — a full snapshot of one tracked operation. Every lifecycle
+ * transition (start, progress, terminal) publishes one of these under `REQUEST_UPDATED`, so the
+ * client folds by `id`: last write wins, with no cross-type ordering hazard.
+ */
+export interface IpcRequestStatus {
+    id: string;
+    module: string;
+    type: string;
+    scope?: string;
+    state: IpcRequestState;
+    progress?: IpcProgress;
+    detail?: IpcLabel;
+    error?: IpcError;
+    startedAt: string;
+    finishedAt?: string;
+}
+/**
+ * State behind {@link useShenoraRequests}. TWO bands, because a request is in flight or done:
+ *
+ * | Band | Getter |
+ * |---|---|
+ * | In flight | {@link running} |
+ * | Finished | {@link finished} — prunable via `clearFinished` |
+ *
+ * Every getter is DERIVED from `byId` on each read — never a second copy a fold has to remember to
+ * keep in sync. `byId` is the only thing any reducer here writes.
+ *
+ * ⚠ Most requests never appear at all: one that finishes inside the host's grace period is never
+ * announced, so this store is a list of work that is actually TAKING A WHILE rather than a log of
+ * every call the page made.
+ */
+export interface RequestsState {
+    byId: Record<string, IpcRequestStatus>;
+    /** Every currently-running operation, in `byId` order. */
+    readonly running: IpcRequestStatus[];
+    /** Every operation that reached a terminal status (completed/failed/cancelled). */
+    readonly finished: IpcRequestStatus[];
+}
+/** Fire-and-forget actions exposed on {@link useShenoraRequests}, routed to `IpcRequestsModule`. */
+export interface RequestsActions {
+    /** `CANCEL { requestId }` — the app-level cancel route `ipc-contracts` prescribes. */
+    cancel: (requestId: string) => string;
+    /**
+     * `CLEAR_FINISHED { scope? }` — drop retained finished history, forwarding this store's own
+     * configured scope (generic-library audit finding 1) so a scoped store's "clear completed" cannot
+     * wipe another scope's history host-side. No local mutation here: the host's
+     * `REQUEST_REMOVED` (finding 4) is the only thing that removes a row from this store now — see
+     * {@link IpcRequestEventTypes.Removed}. It used to carry an optimistic local prune of every TERMINAL
+     * entry, added because removals had no wire event at all; that guess is retired now that one exists.
+     */
+    clearFinished: () => string;
+}
+/** Test/alternate-transport seams, a renamed host module, and an optional scope filter, for {@link createRequestsStore}. */
+export interface RequestsStoreOptions {
+    /**
+     * The request/event module this store talks to. Must match the host's
+     * `IpcRequestTrackerOptions.ModuleName` — default `'SHENORA.REQUESTS'` on both sides — when an app
+     * renamed it to avoid a collision with one of its own module names (the duplicate-module guard
+     * `IpcRequestsModule`'s own docs describe). A store bound to the default name cannot reach a
+     * renamed host at all, which is exactly the gap this field closes.
+     */
+    module?: string;
+    /**
+     * Optional app-defined scope, applied to THREE places so the store stays internally consistent:
+     * the bus subscription (only deltas whose event scope matches are folded), the actions' request
+     * envelope, and the initial `LIST` snapshot's payload (`IpcRequestsModule` reads its scope filter
+     * from the payload, not the envelope — see `IpcRequestsModule.RouteMessageAsync`). Threading it
+     * into only the first two would load every scope on first subscribe and never remove the
+     * out-of-scope rows, since no delta for them ever arrives: a silent, permanent leak.
+     */
+    scope?: string;
+    /** Test/multi-transport seams. Default: the shared bridge and event bus. */
+    bridge?: ShenoraBridge;
+    bus?: ShenoraEventBus;
+}
+/**
+ * Build a store instance over the requests module — the factory {@link useShenoraRequests}
+ * itself is built from. Exposed (rather than only the ready-made hook) for the same reason
+ * `WindowCommands` takes an optional bridge: a test needs a fake bridge/bus
+ * (`requests.test.ts`), an app that renamed the host's `IpcRequestTrackerOptions.ModuleName`
+ * needs a store bound to that name instead of the unreachable default, and an app running a
+ * secondary window or auxiliary session needs its own scope-filtered instance instead of being
+ * stuck with the shared, unscoped default.
+ */
+export declare function createRequestsStore(options?: RequestsStoreOptions): ShenoraStore<RequestsState, RequestsActions>;
+/**
+ * The client side of the operations primitive (design §4.6, `IpcRequestsModule` +
+ * `IIpcRequestTracker`): snapshots via `LIST` on first subscribe, then folds `REQUEST_UPDATED` by
+ * id — one subscription however many components read it, and a late mounter renders CURRENT state
+ * because the host is authoritative (the store primitive's own late-mounter case is now
+ * host-backed end to end). `running`/`finished` are selectors an activity panel or status bar reads
+ * directly: `useShenoraRequests((s) => s.running)`. There is no `waiting` band and no `waitReason` —
+ * a request is IN FLIGHT or DONE, the same two states `XMLHttpRequest` has, since D66. Bound to the
+ * default module/no scope — use {@link createRequestsStore} directly for a renamed module or a
+ * scope-filtered instance.
+ *
+ * Headless, per D13: no component, no UI opinion, no `ProcessType`-style enum — what an operation
+ * IS stays the app's `kind` string; this only carries the uniform lifecycle around it.
+ */
+export declare const useShenoraRequests: ShenoraStore<RequestsState, RequestsActions>;

package/dist/requests.js

@@ -0,0 +1,146 @@
+import { createShenoraStore } from './store.js';
+/**
+ * Mirrors `Shenora.Core.Ipc.IpcRequestState` (design §4.2) — crosses the wire as its camelCase name for
+ * free: `IpcJson` already installs a camelCase `JsonStringEnumConverter`, so no per-type wiring is
+ * needed on either side. Pinned against the host by
+ * `WireMirrorTests.Every_request_state_exists_on_both_sides` — a status added on one side and
+ * not the other fails that test by name, not by a green suite that never looked.
+ */
+export const IpcRequestStates = {
+    Running: 'running',
+    Completed: 'completed',
+    Failed: 'failed',
+    Cancelled: 'cancelled',
+    // NO 'waiting'. A request is IN FLIGHT or DONE — the XHR model this mirrors has no parked state,
+    // and neither does the host since D66. Work that parks awaiting a human is host-initiated work
+    // (a queued mission), which reports on its own event stream rather than as a request.
+};
+/**
+ * Mirrors `Shenora.Core.Ipc.IpcRequestEvents` — pinned against the host by
+ * `WireMirrorTests.Request_event_names_match_the_host` (ALSO IN THIS BATCH, whole-branch review):
+ * these were bare string literals with nothing comparing them to the host's own constants, so a host
+ * rename left the suite green and the client permanently deaf to the renamed event.
+ */
+export const IpcRequestEventTypes = {
+    Updated: 'REQUEST_UPDATED',
+    /**
+     * One or more request ids left the host with no corresponding `Updated` snapshot — history eviction
+     * and `CLEAR_FINISHED`. Payload is `{ requestIds: string[] }`; {@link createRequestsStore} folds it
+     * by deleting those ids. One authoritative event, so a client never has to guess what the host
+     * removed.
+     */
+    Removed: 'REQUEST_REMOVED',
+};
+/**
+ * Mirrors the route names `Shenora.Modules.Requests.IpcRequestsModule` switches on (its own
+ * `ListType`/`CancelType`/`ClearFinishedType`/`ResumeType` constants) — pinned by
+ * `WireMirrorTests.Request_route_names_match_the_hosts_module`, same rationale as
+ * {@link IpcRequestEventTypes}.
+ */
+export const IpcRequestRoutes = {
+    List: 'LIST',
+    Cancel: 'CANCEL',
+    ClearFinished: 'CLEAR_FINISHED',
+    // THREE routes — the same three `XMLHttpRequest` offers. RESUME/WAIT/DISMISS went with the waiting
+    // band (D66), and the wire-mirror test pins this object's SIZE so a retired name cannot creep back.
+};
+/**
+ * Default `Shenora.Core.Ipc.IpcRequestTrackerOptions.ModuleName` — pinned by
+ * `WireMirrorTests.The_default_requests_module_name_matches_the_host`.
+ */
+export const IpcRequestsModuleName = 'SHENORA.REQUESTS';
+/** The terminal states — everything that is not in flight. */
+const TERMINAL_STATES = new Set([
+    IpcRequestStates.Completed,
+    IpcRequestStates.Failed,
+    IpcRequestStates.Cancelled,
+]);
+function index(list) {
+    const byId = {};
+    for (const operation of list)
+        byId[operation.id] = operation;
+    return byId;
+}
+/**
+ * The one place `running`/`finished` are computed — wrap `byId` here, nowhere else.
+ */
+function makeState(byId) {
+    return {
+        byId,
+        get running() {
+            return Object.values(byId).filter((request) => request.state === IpcRequestStates.Running);
+        },
+        get finished() {
+            return Object.values(byId).filter((request) => TERMINAL_STATES.has(request.state));
+        },
+    };
+}
+/**
+ * Build a store instance over the requests module — the factory {@link useShenoraRequests}
+ * itself is built from. Exposed (rather than only the ready-made hook) for the same reason
+ * `WindowCommands` takes an optional bridge: a test needs a fake bridge/bus
+ * (`requests.test.ts`), an app that renamed the host's `IpcRequestTrackerOptions.ModuleName`
+ * needs a store bound to that name instead of the unreachable default, and an app running a
+ * secondary window or auxiliary session needs its own scope-filtered instance instead of being
+ * stuck with the shared, unscoped default.
+ */
+export function createRequestsStore(options = {}) {
+    const module = options.module ?? IpcRequestsModuleName;
+    return createShenoraStore(module, {
+        initial: makeState({}),
+        // LIST is the snapshot source (design §4.6): a store cannot replay a stream, so a component
+        // that mounts while work is already running gets it from here before folding any deltas.
+        // The payload carries `scope` so the initial load is filtered the SAME way the deltas are
+        // (below, and via createShenoraStore's own `scope` option) — both halves must agree, or a
+        // scoped store loads every scope once and then never sheds the out-of-scope rows.
+        snapshot: {
+            type: IpcRequestRoutes.List,
+            payload: options.scope !== undefined ? { scope: options.scope } : undefined,
+            apply: (_state, data) => makeState(index(data)),
+        },
+        on: {
+            // ONE event type for every transition (design §4.3) — last-write-wins by id, so folding needs
+            // no ordering logic and no cross-type races.
+            [IpcRequestEventTypes.Updated]: (state, payload) => makeState({ ...state.byId, [payload.id]: payload }),
+            // The ONE removal delta (Finding 4, generic-library audit), replacing the two hand-written
+            // optimistic prunes `clearFinished`/`resume` used to carry (see their own docs below) — deletes
+            // exactly the ids the host named, regardless of status; an id this store never had is a no-op.
+            [IpcRequestEventTypes.Removed]: (state, payload) => {
+                const byId = { ...state.byId };
+                for (const id of payload.requestIds)
+                    delete byId[id];
+                return makeState(byId);
+            },
+        },
+        actions: ({ post }) => ({
+            cancel: (requestId) => post(IpcRequestRoutes.Cancel, { payload: { requestId } }),
+            clearFinished: () => 
+            // Forward THIS store's own configured scope (Finding 1, generic-library audit) — the same
+            // key the LIST snapshot payload already carries above. No local mutation here any more
+            // (Finding 4): the host's REQUEST_REMOVED is the ONLY thing that removes a row now, which
+            // is also what makes the scope threading safe to add — nothing here can diverge from what
+            // the host actually cleared.
+            post(IpcRequestRoutes.ClearFinished, {
+                payload: options.scope !== undefined ? { scope: options.scope } : undefined,
+            }),
+        }),
+        scope: options.scope,
+        bridge: options.bridge,
+        bus: options.bus,
+    });
+}
+/**
+ * The client side of the operations primitive (design §4.6, `IpcRequestsModule` +
+ * `IIpcRequestTracker`): snapshots via `LIST` on first subscribe, then folds `REQUEST_UPDATED` by
+ * id — one subscription however many components read it, and a late mounter renders CURRENT state
+ * because the host is authoritative (the store primitive's own late-mounter case is now
+ * host-backed end to end). `running`/`finished` are selectors an activity panel or status bar reads
+ * directly: `useShenoraRequests((s) => s.running)`. There is no `waiting` band and no `waitReason` —
+ * a request is IN FLIGHT or DONE, the same two states `XMLHttpRequest` has, since D66. Bound to the
+ * default module/no scope — use {@link createRequestsStore} directly for a renamed module or a
+ * scope-filtered instance.
+ *
+ * Headless, per D13: no component, no UI opinion, no `ProcessType`-style enum — what an operation
+ * IS stays the app's `kind` string; this only carries the uniform lifecycle around it.
+ */
+export const useShenoraRequests = createRequestsStore();

package/dist/segmentBinder.d.ts

@@ -0,0 +1,87 @@
+import { type MediaSourceGlobals } from './segmentStream.js';
+/**
+ * The imperative half of the segment route (D71 piece 4b): open a `SourceBuffer`, feed it, and stop when
+ * the platform says stop.
+ *
+ * 🔴 **Everything here was written against measurements rather than against the specification**, because
+ * three implementations disagree in ways the spec permits and none of it is guessable:
+ *
+ * - **Attachment is not portable.** iOS takes `srcObject` — a `ManagedMediaSource` is a valid
+ *   `MediaSourceHandle` — and Chromium refuses it outright ("not of type '(MediaSourceHandle or
+ *   MediaStream)'"), wanting an object URL. Feature-detected, not branched on the shell: which one works
+ *   is a property of the MediaSource, not of the OS.
+ * - **The codecs are read from the init segment, never assumed.** The track set is a fact about the
+ *   DEVICE, not the source: the same file yields a two-track init on iOS and a video-only one on Android,
+ *   which cannot decode its AC-3 soundtrack. A mismatch kills the FIRST append and plays nothing.
+ * - **The streaming gate is real on iOS and absent elsewhere.** `endstreaming` fires once enough is
+ *   buffered (measured: at 60 s, not at 6 s), and fetching past it is the misuse `ManagedMediaSource`
+ *   exists to detect. A plain `MediaSource` has neither event nor a `streaming` property, and its absence
+ *   means "always streaming" — never "never asked".
+ *
+ * ⚠ **The dependencies are INJECTABLE so this is testable without a browser.** jsdom has no MediaSource,
+ * and "cannot be verified anywhere this repo runs" was true of the whole file until the seams below
+ * existed. A fake source and a fake fetch drive every branch here.
+ */
+export interface SegmentBinderOptions {
+    /** The playlist URL. Segment URIs are resolved relative to it. */
+    manifest: string;
+    /** The element to play into. Only the members this binder touches are required. */
+    element: HTMLMediaElement;
+    /** Where to look for a MediaSource. Defaults to `globalThis`. */
+    globals?: MediaSourceGlobals;
+    /** Defaults to `globalThis.fetch`. */
+    fetch?: (url: string) => Promise<{
+        ok: boolean;
+        status: number;
+        arrayBuffer(): Promise<ArrayBuffer>;
+        text(): Promise<string>;
+    }>;
+    /** Defaults to `URL.createObjectURL`. Only used when `srcObject` is refused. */
+    createObjectURL?: (source: object) => string;
+    /**
+     * Defaults to `URL.revokeObjectURL`. The pair to {@link createObjectURL}, and injectable for the same
+     * reason: without it the failure paths that must revoke — a source that closes before opening, a
+     * codec the device refuses — cannot be asserted, only hoped for.
+     */
+    revokeObjectURL?: (url: string) => void;
+    /** Stop fetching once this many seconds are buffered ahead. Defaults to 30. */
+    targetAheadSeconds?: number;
+    /** Diagnostics. Every decision that could stall playback reports through here. */
+    onDiagnostic?: (line: string) => void;
+}
+/** A live binding. Dispose it when the element goes away — it detaches every listener it added. */
+export interface SegmentBinding {
+    /** Indices appended so far. */
+    readonly appended: ReadonlySet<number>;
+    /** False while a managed source has said stop. Always true where the platform has no such signal. */
+    readonly streaming: boolean;
+    /** Which attachment this implementation accepted — the difference between the two shells. */
+    readonly attachedBy: 'srcObject' | 'objectURL';
+    /** What the SourceBuffer was opened with, read from the init segment. */
+    readonly codecs: string;
+    /** Detach listeners and release the object URL, if one was minted. */
+    dispose(): void;
+}
+/**
+ * Thrown for every reason a stream cannot start, so a caller has one thing to catch.
+ *
+ * ⚠ **Not literally every reason** — a `TypeError` from the manifest fetch failing at the network layer,
+ * and a `RangeError` from a truncated init segment, both propagate as themselves. Catch broadly if you
+ * need to be exhaustive.
+ */
+export declare class SegmentBinderError extends Error {
+    constructor(message: string);
+}
+/**
+ * Open a MediaSource for `options.manifest` and keep it fed.
+ *
+ * Resolves once the init segment has been appended — the point after which the element can play — and
+ * goes on fetching in the background until every segment is in or {@link SegmentBinding.dispose} is called.
+ *
+ * ⚠ **There is deliberately NO `useSegmentStream` hook.** This needs no React — it takes an element and
+ * returns a handle, exactly as `mediaUrl` takes a path and returns a string — so a hook would add a
+ * lifecycle without adding a capability. The case that would earn one is an app wanting load/error
+ * state as component state, and the shape of that hook depends on what such an app actually asks for;
+ * inventing it first is how a seam nothing consults gets built (D63). Call this from an effect.
+ */
+export declare function bindSegmentStream(options: SegmentBinderOptions): Promise<SegmentBinding>;