@shenora/react 0.9.1 → 0.11.0

package/dist/index.d.ts

@@ -1,13 +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 } from './eventBus.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, type ShenoraQueryResult } from './hooks.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,22 +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 { 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 } from './hooks.js';
+export { useShenora, useShenoraEvent, useShenoraQuery, useShellInfo, } from './hooks.js';
+// 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;

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>;