@shenora/react 0.9.1 → 0.11.0

package/dist/useDropZone.js

@@ -2,8 +2,8 @@ import { useEffect, useRef, useState } from 'react';
 import { getBridge } from './bridge.js';
 import { eventBus as defaultEventBus } from './eventBus.js';
 import { debounce, randomId } from './internal.js';
-/** The reserved module the drop-zone stack speaks (host: `DropZoneManager`/`DropZoneFacade`). */
-export const DROP_ZONE_MODULE = 'DROP_ZONE';
+/** The reserved module the drop-zone stack speaks (host: `DropZoneManager`/`DropZoneModule`). */
+export const DROP_ZONE_MODULE = 'SHENORA.DROPZONE';
 const newZoneId = () => randomId('drop-zone-');
 /**
  * **The file-drop API for a Shenora page. Do not use the DOM's own drop event for files —
@@ -30,13 +30,34 @@ const newZoneId = () => randomId('drop-zone-');
  */
 export function useDropZone(options) {
     const { targetRef, enabled = true } = options;
-    const zoneIdRef = useRef(options.zoneId ?? newZoneId());
+    // ⚠ LAZY, because `useRef(newZoneId())` evaluates its argument on EVERY render and keeps only the
+    // first — so the generator ran a `crypto.randomUUID()` per render of every drop zone, for a value
+    // used once. The empty string is a safe sentinel: a generated id is never empty, and a caller who
+    // passes `zoneId: ''` short-circuits the `??` and so still never reaches the generator.
+    const zoneIdRef = useRef('');
+    if (zoneIdRef.current === '')
+        zoneIdRef.current = options.zoneId ?? newZoneId();
+    // ⚠ Read ONCE, like the id, and unlike `onDrop`/`bridge` below which track the latest value. That is
+    // deliberate rather than an oversight: the hover effect captures this class for its cleanup, while
+    // the FILE_DROP effect reads it live, so a value that could change mid-hover would let one path add
+    // class A and another remove class B — leaving A stuck on the element with no drag in progress. The
+    // default is a constant, so unlike the id there is nothing here worth making lazy.
     const dropClassRef = useRef(options.dropClassName ?? 'shenora-drop-hover');
     const onDropRef = useRef(options.onDrop);
     onDropRef.current = options.onDrop;
     const bridgeRef = useRef(options.bridge);
     bridgeRef.current = options.bridge;
     const bus = options.bus ?? defaultEventBus;
+    // Tracks the latest handler (like `onDrop`), so a cleanup that runs long after mount still reports
+    // through the sink the app has NOW. Only when the app supplied none does this log — a caller that
+    // took `onError` owns its reporting and must not be double-logged, the rule the package's other
+    // three sinks follow.
+    const onErrorRef = useRef(options.onError);
+    onErrorRef.current = options.onError;
+    const reportRef = useRef(() => { });
+    reportRef.current = (error, route) => onErrorRef.current
+        ? onErrorRef.current(error, route)
+        : console.error(`[shenora] drop-zone ${route} failed:`, error);
     // Make the ref's CONTENT reactive (P5.5 H2). `targetRef` is a stable object, so effects keyed on it
     // run exactly once — and if `targetRef.current` was null on that run (a conditionally-rendered
     // target, or any order where the ref is attached after the first commit) the effect bailed out and
@@ -91,7 +112,7 @@ export function useDropZone(options) {
                 .then(() => {
                 if (epochRef.current === epoch)
                     isRegisteredRef.current = true;
-            }, (error) => console.error('[shenora] drop-zone REGISTER failed:', error))
+            }, (error) => reportRef.current(error, 'REGISTER'))
                 .finally(() => {
                 if (epochRef.current === epoch)
                     registeringRef.current = false;
@@ -101,7 +122,7 @@ export function useDropZone(options) {
             lastBoundsRef.current = bounds;
             bridge
                 .invoke(DROP_ZONE_MODULE, 'UPDATE', { payload: { zoneId: zoneIdRef.current, ...bounds } })
-                .catch((error) => console.error('[shenora] drop-zone UPDATE failed:', error));
+                .catch((error) => reportRef.current(error, 'UPDATE'));
         }
     };
     // Track the element and keep the native overlay in sync.
@@ -115,7 +136,7 @@ export function useDropZone(options) {
         const sendShow = debounce(() => {
             (bridgeRef.current ?? getBridge())
                 .invoke(DROP_ZONE_MODULE, 'SHOW', { payload: { zoneId: zoneIdRef.current } })
-                .catch((error) => console.error('[shenora] drop-zone SHOW failed:', error));
+                .catch((error) => reportRef.current(error, 'SHOW'));
         }, 100);
         // The element's mouseleave (and the window losing focus) re-arm the overlay — native
         // MouseLeave alone is unreliable through the WebView.
@@ -152,7 +173,7 @@ export function useDropZone(options) {
             if (attemptedRef.current) {
                 (bridgeRef.current ?? getBridge())
                     .invoke(DROP_ZONE_MODULE, 'UNREGISTER', { payload: { zoneId: zoneIdRef.current } })
-                    .catch((error) => console.error('[shenora] drop-zone UNREGISTER failed:', error));
+                    .catch((error) => reportRef.current(error, 'UNREGISTER'));
                 epochRef.current++; // invalidate any in-flight REGISTER's ack (see epochRef)
                 isRegisteredRef.current = false;
                 registeringRef.current = false; // a remount must re-send immediately

package/dist/windowCommands.d.ts

@@ -33,7 +33,7 @@ interface WindowRequests {
     };
 }
 /**
- * Typed client for the host's `WINDOW` module (`WindowCommandFacade` in Shenora.Windows) —
+ * Typed client for the host's `SHENORA.WINDOW` module (`WindowCommandModule` in Shenora.Windows) —
  * drive the frameless window's chrome from the page: chrome buttons call
  * `minimize`/`toggleMaximize`/`close`, the header's `onMouseDown` calls `startDrag` (the window
  * then drags natively — snap and multi-monitor included), and a thin strip at the very top

package/dist/windowCommands.js

@@ -2,7 +2,7 @@ import { useEffect, useRef, useState } from 'react';
 import { debounce } from './internal.js';
 import { BaseModuleService } from './moduleService.js';
 /**
- * Typed client for the host's `WINDOW` module (`WindowCommandFacade` in Shenora.Windows) —
+ * Typed client for the host's `SHENORA.WINDOW` module (`WindowCommandModule` in Shenora.Windows) —
  * drive the frameless window's chrome from the page: chrome buttons call
  * `minimize`/`toggleMaximize`/`close`, the header's `onMouseDown` calls `startDrag` (the window
  * then drags natively — snap and multi-monitor included), and a thin strip at the very top
@@ -11,7 +11,7 @@ import { BaseModuleService } from './moduleService.js';
  */
 export class WindowCommands extends BaseModuleService {
     constructor(bridge) {
-        super('WINDOW', bridge);
+        super('SHENORA.WINDOW', bridge);
     }
     minimize() {
         return this.send('MINIMIZE');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shenora/react",
-  "version": "0.9.1",
-  "description": "React client for Shenora desktop hosts: correlated invoke/send/subscribe over the WebView2 bridge, typed module services, hooks, and a browser fallback for pure-UI development.",
+  "version": "0.11.0",
+  "description": "React client for Shenora hosts on Windows, Android and iOS: correlated invoke/send/subscribe over the desktop postMessage bridge or the MAUI HybridWebView transport, typed module services, host-backed stores, and hooks for request tracking and media playback. Drop zones and window commands are desktop-only, because the capabilities are. Ships a browser fallback for pure-UI development.",
   "license": "MIT",
   "author": "Jiarong Gu",
   "repository": {
@@ -14,6 +14,10 @@
     "shenora",
     "webview2",
     "desktop",
+    "android",
+    "ios",
+    "maui",
+    "hybrid",
     "ipc",
     "react",
     "winforms",
@@ -44,7 +48,9 @@
     "//typecheck": "The ONLY thing that type-checks the tests — `build` excludes them and vitest transpiles without checking, so `@ts-expect-error` assertions (which pin the typed-service generic) are inert without this. Run by dev.mjs verify.",
     "typecheck": "tsc -p tsconfig.json",
     "test": "vitest run",
-    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\""
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "//typecheck:floor": "The peerDependency FLOOR is a tested claim, not an assumption: type-checks the SHIPPED sources against React 18 types while everything else builds on 19, so an API that does not exist in 18 (useActionState, use, …) fails HERE instead of in a React 18 consumer's build. Run by dev.mjs verify.",
+    "typecheck:floor": "tsc -p tsconfig.react18.json"
   },
   "peerDependencies": {
     "react": ">=18"
@@ -52,6 +58,7 @@
   "devDependencies": {
     "@testing-library/react": "^16.3.2",
     "@types/react": "^19.2.17",
+    "@types/react18": "npm:@types/react@^18",
     "jsdom": "^29.1.1",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",

package/dist/operations.d.ts

@@ -1,256 +0,0 @@
-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.Ipc.OperationStatus` (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_operation_status_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 OperationStatuses: {
-    readonly Running: "running";
-    readonly Completed: "completed";
-    readonly Failed: "failed";
-    readonly Cancelled: "cancelled";
-    /**
-     * Not progressing, awaiting a decision — the APP names why via {@link OperationInfo.waitReason}
-     * (e.g. `'credentials'`/`'dns'`/`'queued'`/`'rate-limited'`), never a kit-owned reason enum. Not
-     * one of the terminal statuses in {@link OperationsState.finished}, and never pruned as history —
-     * a waiting entry is a pending offer, not something finished.
-     *
-     * Reached ONE way, and that is the point: the host's `IOperation.Wait` on a live operation. The
-     * body is parked, not gone, so there is always something to resume. Exits via the host's
-     * `IOperation.Resume` (back to `running`), the `DISMISS` route (to `cancelled`), or a direct
-     * complete/fail.
-     *
-     * Two simplifications got it here, both undoing the same mistake — encoding HOW an entry arrived
-     * rather than WHAT state it is in. It was once two values (`paused` and `interrupted`) that every
-     * host transition already treated as one band, and the host once also accepted crash-checkpoint
-     * entries with no live body at all (`RegisterWaiting` + `resumePayload`), which forced every caller
-     * to answer "does this one have a handle?". The checkpoint half was cut in 0.2.0: crash recovery is
-     * the APP's business — it owns the checkpoint, and a resumed run is a fresh `Start()` like any other.
-     */
-    readonly Waiting: "waiting";
-};
-/** One of {@link OperationStatuses}. */
-export type OperationStatus = (typeof OperationStatuses)[keyof typeof OperationStatuses];
-/**
- * Mirrors `Shenora.Ipc.OperationEvents` — pinned against the host by
- * `WireMirrorTests.Operation_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 OperationEventTypes: {
-    readonly Updated: "OPERATION_UPDATED";
-    readonly ResumeRequested: "OPERATION_RESUME_REQUESTED";
-    /**
-     * A client asked to wait a running operation (generic-library audit finding 3, renamed from
-     * `PAUSE_REQUESTED`) — the owning module should call the host's `IOperation.Wait` once it has
-     * actually stopped. Not subscribed by {@link createOperationsStore} itself, same as
-     * {@link ResumeRequested}: it targets the owning module's own service, not the generic operations
-     * store.
-     */
-    readonly WaitRequested: "OPERATION_WAIT_REQUESTED";
-    /**
-     * One or more operation ids left the host registry with no corresponding `Updated` snapshot —
-     * `MaxHistory` eviction, `CLEAR_FINISHED`, and the interrupted-entry drop on `RESUME` (Finding 4,
-     * generic-library audit). Payload is `{ operationIds: string[] }`; {@link createOperationsStore}
-     * folds it by deleting those ids, which is what let the two hand-written optimistic prunes
-     * (`clearFinished`/`resume` used to carry one each) be removed — one authoritative event that
-     * cannot diverge from what the host actually did, replacing two guesses that could.
-     */
-    readonly Removed: "OPERATION_REMOVED";
-};
-/**
- * Mirrors the route names `Shenora.Ipc.OperationsFacade` switches on (its own
- * `ListType`/`CancelType`/`ClearFinishedType`/`ResumeType` constants) — pinned by
- * `WireMirrorTests.Operation_route_names_match_the_hosts_facade`, same rationale as
- * {@link OperationEventTypes}.
- */
-export declare const OperationRoutes: {
-    readonly List: "LIST";
-    readonly Cancel: "CANCEL";
-    readonly ClearFinished: "CLEAR_FINISHED";
-    readonly Resume: "RESUME";
-    /** Decline a pending Waiting offer by id — mirrors {@link Cancel}'s shape. */
-    readonly Dismiss: "DISMISS";
-    /**
-     * Ask the owning module to wait a running operation by id (generic-library audit finding 3,
-     * renamed from `PAUSE`) — mirrors {@link Resume}'s shape (`{ operationId }` → `{ requested }`).
-     * Asking is not acting: the owning module's own `IOperation.Wait` is what actually stops the work
-     * and publishes the transition, same split as {@link Resume} vs the host's `IOperation.Resume`.
-     */
-    readonly Wait: "WAIT";
-};
-/**
- * Default `Shenora.Ipc.OperationRegistryOptions.ModuleName` — pinned by
- * `WireMirrorTests.The_default_operations_module_name_matches_the_host`.
- */
-export declare const OperationModuleName = "OPERATIONS";
-/**
- * Mirrors `Shenora.Ipc.OperationLabel` — human-facing text the HOST never renders itself: an
- * untranslated fallback plus an app i18n key and interpolation parameters (headless, D13).
- */
-export interface OperationLabel {
-    text?: string;
-    key?: string;
-    parameters?: Record<string, string>;
-}
-/**
- * Mirrors `Shenora.Ipc.OperationProgress` — 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 OperationProgress {
-    value: number;
-    total?: number;
-    unit?: string;
-}
-/**
- * Mirrors `Shenora.Ipc.OperationInfo` — a full snapshot of one tracked operation. Every lifecycle
- * transition (start, progress, terminal) publishes one of these under `OPERATION_UPDATED`, so the
- * client folds by `id`: last write wins, with no cross-type ordering hazard.
- */
-export interface OperationInfo {
-    id: string;
-    module: string;
-    kind: string;
-    scope?: string;
-    status: OperationStatus;
-    progress?: OperationProgress;
-    title?: OperationLabel;
-    detail?: OperationLabel;
-    /** Why the operation is `'waiting'` — an app-defined string, like `kind`; the kit never interprets it. */
-    waitReason?: string;
-    error?: IpcError;
-    cancellable: boolean;
-    startedAt: string;
-    finishedAt?: string;
-}
-/**
- * State behind {@link useShenoraOperations}. Mirrors the host's THREE bands (design §5A.2):
- *
- * | Band | Getter | Exits |
- * |---|---|---|
- * | Active | {@link running} | complete / fail / cancel / wait |
- * | Waiting — stopped, resumable, awaiting a decision | {@link waiting} | resume / dismiss / complete / fail |
- * | Terminal | {@link finished} | — (prunable via `clearFinished`) |
- *
- * `waiting` is now the WHOLE band, not a union of two getters — the host's `OperationStatus` carries
- * only one waiting value (the former `paused`/`interrupted` pair collapsed into it, since every host
- * transition already treated them as one band). A waiting entry is a pending offer, not finished
- * history: the host never prunes it on its own, and only `Resume` or `Dismiss` removes it. Every
- * getter here is DERIVED from `byId` on every read — never a second copy a fold has to remember to
- * keep in sync. `byId` itself is the only thing any reducer here ever writes.
- */
-export interface OperationsState {
-    byId: Record<string, OperationInfo>;
-    /** Every currently-running operation, in `byId` order. */
-    readonly running: OperationInfo[];
-    /**
-     * The WAITING band (design §5A.2): stopped, resumable, awaiting a decision — exactly what
-     * `Dismiss`/`RequestResume` both accept, so a status bar can render "needs you" as one bucket.
-     * Every entry here reached the band the same way (a live `Wait()` on the host), so there is no
-     * sub-case to distinguish — see {@link OperationStatuses.Waiting}.
-     */
-    readonly waiting: OperationInfo[];
-    /** Every operation that reached a terminal status (completed/failed/cancelled). */
-    readonly finished: OperationInfo[];
-}
-/** Fire-and-forget actions exposed on {@link useShenoraOperations}, routed to `OperationsFacade`. */
-export interface OperationsActions {
-    /** `CANCEL { operationId }` — the app-level cancel route `ipc-contracts` prescribes. */
-    cancel: (operationId: string) => string;
-    /**
-     * `DISMISS { operationId }` — decline a pending `waiting` offer (design §5A.3), mirroring
-     * {@link cancel}'s shape. No optimistic local prune: the host's `Dismiss` transitions the entry to
-     * `cancelled` and publishes an ordinary `OPERATION_UPDATED` snapshot for it (same as a real
-     * cancel), so the store already folds the result from the wire.
-     */
-    dismiss: (operationId: 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
-     * `OPERATION_REMOVED` (finding 4) is the only thing that removes a row from this store now — see
-     * {@link OperationEventTypes.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;
-    /**
-     * `RESUME { operationId }` — ask the host to resume a waiting operation, mirroring {@link wait}.
-     * No local mutation: asking never changes state by itself — the owning module's own
-     * `IOperation.Resume` publishes the `running` transition, and the store folds it from the wire like
-     * any other `OPERATION_UPDATED`.
-     *
-     * This action carried an optimistic local prune through two designs and was the source of the
-     * release's only Critical — it deleted a row the host deliberately kept, making a still-waiting
-     * operation unreachable. The prune existed because the host's `RequestResume` was ASYMMETRIC
-     * (removing crash-checkpoint entries, keeping live ones). The 0.2.0 design pass cut the checkpoint
-     * half, so the asymmetry is gone at the source and there is nothing left for a client to mirror.
-     */
-    resume: (operationId: string) => string;
-    /**
-     * `WAIT { operationId }` — ask the owning module to wait a running operation (generic-library
-     * audit finding 3, renamed from `pause`), mirroring {@link dismiss}'s shape. No optimistic local
-     * prune: asking never changes the state by itself — the owning module's own `IOperation.Wait` is
-     * what publishes the `waiting` transition, and the store folds it from the wire like any other
-     * `OPERATION_UPDATED`.
-     */
-    wait: (operationId: string) => string;
-}
-/** Test/alternate-transport seams, a renamed host module, and an optional scope filter, for {@link createOperationsStore}. */
-export interface OperationsStoreOptions {
-    /**
-     * The request/event module this store talks to. Must match the host's
-     * `OperationRegistryOptions.ModuleName` — default `'OPERATIONS'` on both sides — when an app
-     * renamed it to avoid a collision with one of its own module names (the duplicate-module guard
-     * `OperationsFacade`'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 (`OperationsFacade` reads its scope filter
-     * from the payload, not the envelope — see `OperationsFacade.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 operations module — the factory {@link useShenoraOperations}
- * 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
- * (`operations.test.ts`), an app that renamed the host's `OperationRegistryOptions.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 createOperationsStore(options?: OperationsStoreOptions): ShenoraStore<OperationsState, OperationsActions>;
-/**
- * The client side of the operations primitive (design §4.6, `OperationsFacade` +
- * `IOperationRegistry`): snapshots via `LIST` on first subscribe, then folds `OPERATION_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`/`waiting`/`finished` are selectors an activity panel or status
- * bar reads directly: `useShenoraOperations((s) => s.waiting)` for the one "needs you" bucket
- * (every entry in it reached the band the same way, so there is no sub-case to filter for; read
- * `waitReason` for WHY it is waiting). Bound to the default module/no scope — use
- * {@link createOperationsStore} 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 useShenoraOperations: ShenoraStore<OperationsState, OperationsActions>;

package/dist/operations.js

@@ -1,191 +0,0 @@
-import { createShenoraStore } from './store.js';
-/**
- * Mirrors `Shenora.Ipc.OperationStatus` (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_operation_status_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 OperationStatuses = {
-    Running: 'running',
-    Completed: 'completed',
-    Failed: 'failed',
-    Cancelled: 'cancelled',
-    /**
-     * Not progressing, awaiting a decision — the APP names why via {@link OperationInfo.waitReason}
-     * (e.g. `'credentials'`/`'dns'`/`'queued'`/`'rate-limited'`), never a kit-owned reason enum. Not
-     * one of the terminal statuses in {@link OperationsState.finished}, and never pruned as history —
-     * a waiting entry is a pending offer, not something finished.
-     *
-     * Reached ONE way, and that is the point: the host's `IOperation.Wait` on a live operation. The
-     * body is parked, not gone, so there is always something to resume. Exits via the host's
-     * `IOperation.Resume` (back to `running`), the `DISMISS` route (to `cancelled`), or a direct
-     * complete/fail.
-     *
-     * Two simplifications got it here, both undoing the same mistake — encoding HOW an entry arrived
-     * rather than WHAT state it is in. It was once two values (`paused` and `interrupted`) that every
-     * host transition already treated as one band, and the host once also accepted crash-checkpoint
-     * entries with no live body at all (`RegisterWaiting` + `resumePayload`), which forced every caller
-     * to answer "does this one have a handle?". The checkpoint half was cut in 0.2.0: crash recovery is
-     * the APP's business — it owns the checkpoint, and a resumed run is a fresh `Start()` like any other.
-     */
-    Waiting: 'waiting',
-};
-/**
- * Mirrors `Shenora.Ipc.OperationEvents` — pinned against the host by
- * `WireMirrorTests.Operation_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 OperationEventTypes = {
-    Updated: 'OPERATION_UPDATED',
-    ResumeRequested: 'OPERATION_RESUME_REQUESTED',
-    /**
-     * A client asked to wait a running operation (generic-library audit finding 3, renamed from
-     * `PAUSE_REQUESTED`) — the owning module should call the host's `IOperation.Wait` once it has
-     * actually stopped. Not subscribed by {@link createOperationsStore} itself, same as
-     * {@link ResumeRequested}: it targets the owning module's own service, not the generic operations
-     * store.
-     */
-    WaitRequested: 'OPERATION_WAIT_REQUESTED',
-    /**
-     * One or more operation ids left the host registry with no corresponding `Updated` snapshot —
-     * `MaxHistory` eviction, `CLEAR_FINISHED`, and the interrupted-entry drop on `RESUME` (Finding 4,
-     * generic-library audit). Payload is `{ operationIds: string[] }`; {@link createOperationsStore}
-     * folds it by deleting those ids, which is what let the two hand-written optimistic prunes
-     * (`clearFinished`/`resume` used to carry one each) be removed — one authoritative event that
-     * cannot diverge from what the host actually did, replacing two guesses that could.
-     */
-    Removed: 'OPERATION_REMOVED',
-};
-/**
- * Mirrors the route names `Shenora.Ipc.OperationsFacade` switches on (its own
- * `ListType`/`CancelType`/`ClearFinishedType`/`ResumeType` constants) — pinned by
- * `WireMirrorTests.Operation_route_names_match_the_hosts_facade`, same rationale as
- * {@link OperationEventTypes}.
- */
-export const OperationRoutes = {
-    List: 'LIST',
-    Cancel: 'CANCEL',
-    ClearFinished: 'CLEAR_FINISHED',
-    Resume: 'RESUME',
-    /** Decline a pending Waiting offer by id — mirrors {@link Cancel}'s shape. */
-    Dismiss: 'DISMISS',
-    /**
-     * Ask the owning module to wait a running operation by id (generic-library audit finding 3,
-     * renamed from `PAUSE`) — mirrors {@link Resume}'s shape (`{ operationId }` → `{ requested }`).
-     * Asking is not acting: the owning module's own `IOperation.Wait` is what actually stops the work
-     * and publishes the transition, same split as {@link Resume} vs the host's `IOperation.Resume`.
-     */
-    Wait: 'WAIT',
-};
-/**
- * Default `Shenora.Ipc.OperationRegistryOptions.ModuleName` — pinned by
- * `WireMirrorTests.The_default_operations_module_name_matches_the_host`.
- */
-export const OperationModuleName = 'OPERATIONS';
-/**
- * Statuses that count as finished history. Deliberately excludes `waiting` — a resumable operation
- * (whether a live `Wait()` or a crash-announced checkpoint) is a pending offer, "distinct from
- * finished history" (`Shenora.Ipc.OperationStatus.Waiting`), not a terminal outcome.
- */
-const TERMINAL_STATUSES = new Set([
-    OperationStatuses.Completed,
-    OperationStatuses.Failed,
-    OperationStatuses.Cancelled,
-]);
-function index(list) {
-    const byId = {};
-    for (const operation of list)
-        byId[operation.id] = operation;
-    return byId;
-}
-/**
- * The one place `running`/`waiting`/`finished` are computed — wrap `byId` here, nowhere else.
- */
-function makeState(byId) {
-    return {
-        byId,
-        get running() {
-            return Object.values(byId).filter((operation) => operation.status === OperationStatuses.Running);
-        },
-        get waiting() {
-            return Object.values(byId).filter((operation) => operation.status === OperationStatuses.Waiting);
-        },
-        get finished() {
-            return Object.values(byId).filter((operation) => TERMINAL_STATUSES.has(operation.status));
-        },
-    };
-}
-/**
- * Build a store instance over the operations module — the factory {@link useShenoraOperations}
- * 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
- * (`operations.test.ts`), an app that renamed the host's `OperationRegistryOptions.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 createOperationsStore(options = {}) {
-    const module = options.module ?? OperationModuleName;
-    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: OperationRoutes.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.
-            [OperationEventTypes.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.
-            [OperationEventTypes.Removed]: (state, payload) => {
-                const byId = { ...state.byId };
-                for (const id of payload.operationIds)
-                    delete byId[id];
-                return makeState(byId);
-            },
-        },
-        actions: ({ post }) => ({
-            cancel: (operationId) => post(OperationRoutes.Cancel, { payload: { operationId } }),
-            dismiss: (operationId) => post(OperationRoutes.Dismiss, { payload: { operationId } }),
-            wait: (operationId) => post(OperationRoutes.Wait, { payload: { operationId } }),
-            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 OPERATION_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(OperationRoutes.ClearFinished, {
-                payload: options.scope !== undefined ? { scope: options.scope } : undefined,
-            }),
-            resume: (operationId) => post(OperationRoutes.Resume, { payload: { operationId } }),
-        }),
-        scope: options.scope,
-        bridge: options.bridge,
-        bus: options.bus,
-    });
-}
-/**
- * The client side of the operations primitive (design §4.6, `OperationsFacade` +
- * `IOperationRegistry`): snapshots via `LIST` on first subscribe, then folds `OPERATION_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`/`waiting`/`finished` are selectors an activity panel or status
- * bar reads directly: `useShenoraOperations((s) => s.waiting)` for the one "needs you" bucket
- * (every entry in it reached the band the same way, so there is no sub-case to filter for; read
- * `waitReason` for WHY it is waiting). Bound to the default module/no scope — use
- * {@link createOperationsStore} 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 useShenoraOperations = createOperationsStore();