@shenora/react 0.1.2 → 0.4.0

package/README.md

@@ -66,6 +66,80 @@ single component**. A failed `post` has no promise to reject, so it is reported
 configureBridge({ onPostError: (failure) => log.error(failure.module, failure.type, failure.error) });
 ```
 
+### Tracked operations: a ready-made progress store
+
+For work the host tracks with `Shenora.Ipc`'s operation registry (an `IModuleContext.Run`/`Start`
+route on the C# side), `useShenoraOperations()` is a `createShenoraStore` instance built the same
+way as the example above — no per-feature event wiring needed:
+
+```ts
+import { useShenoraOperations } from '@shenora/react';
+
+const running = useShenoraOperations((s) => s.running);         // every in-flight operation
+const waiting = useShenoraOperations((s) => s.waiting);          // stopped, awaiting a decision — "needs you", one bucket
+const importJob = useShenoraOperations((s) => s.byId[jobId]);   // one, by id
+
+useShenoraOperations.actions.cancel(jobId);       // only does anything if the op opted into Cancellable
+useShenoraOperations.actions.dismiss(jobId);      // decline a waiting offer — refuses a running one
+useShenoraOperations.actions.wait(jobId);         // ASK the host to wait running work — refuses anything not running
+useShenoraOperations.actions.clearFinished();
+```
+
+`operation.progress` is an exported `OperationProgress` (`{ value: number; total?: number; unit?:
+string }`) — import the type rather than re-declaring the shape — the APP's own unit
+(bytes-of-a-known-total, items-of-a-known-total, an absolute count with no known total, or a genuine
+percent), never a kit-assumed percentage: `total` is the denominator when one is known and `undefined`
+when there isn't one, and `unit` is app-defined and uninterpreted, exactly like `kind`. The kit ships
+no percent helper — render a ratio only when you have a `total`:
+
+```ts
+import type { OperationProgress } from '@shenora/react';
+
+function format(progress?: OperationProgress): string {
+  if (!progress) return 'starting…';
+  return progress.total
+    ? `${Math.round((progress.value / progress.total) * 100)}%`
+    : `${progress.value}${progress.unit ? ` ${progress.unit}` : ''}`;   // no known total
+}
+```
+
+That division is your own policy, not the kit's, which is why it lives here instead of in `src/`.
+
+For the two events the store deliberately does NOT subscribe to — `OPERATION_RESUME_REQUESTED` and
+`OPERATION_WAIT_REQUESTED`, which target the OWNING module's service rather than this generic store —
+the module name and the event vocabulary are exported too, so you match by symbol and stay inside the
+host↔client mirror the wire tests pin:
+
+```ts
+import { OperationEventTypes, OperationModuleName, useShenoraEvent } from '@shenora/react';
+
+useShenoraEvent(OperationModuleName, OperationEventTypes.ResumeRequested, (payload) => …);
+```
+
+It snapshots via `LIST` on first subscribe (so a progress strip that mounts mid-run isn't empty), then
+folds `OPERATION_UPDATED` by id — one subscription however many components read it. The client
+mirrors the host's three bands (design §5A.2): `running` (Active), `waiting` (Waiting), and `finished`
+(Terminal). All three are derived from `byId` on every read, never a second copy to keep in sync —
+`waiting` is a single-status filter, exactly like `running`. `OperationStatus` carries ONE waiting
+value reached ONE way — the host's `IOperation.Wait` on a live operation — so there is no sub-case to
+tell apart. Filtering by your own `module`/`kind` is a plain `Array.filter` over any of them. A
+`waiting` operation carries `waitReason` — an app-defined string, like `kind`, OPTIONAL on the host
+side — for your UI to branch on. The host never prunes a waiting entry on its own: it stays until
+someone resumes, dismisses, or finishes it. `resume`/`dismiss`/`wait` are all fire-and-forget client
+requests — the host's own `IOperation.Wait`/`Resume` (called by whoever owns the operation, hearing
+`OPERATION_WAIT_REQUESTED`/`OPERATION_RESUME_REQUESTED`) is what actually changes the state; asking
+is not acting. `clearFinished`/`resume`/`wait` do not touch local state themselves at all: the host's
+`OPERATION_REMOVED { operationIds }` is the ONE authoritative removal signal the store folds, deleting
+exactly the named ids — `MaxHistory` eviction and `clearFinished`
+publish it, so a long-lived store's mirror of bounded host history cannot drift from what the host
+actually did (this replaced two hand-written optimistic local prunes that a past release carried —
+one of which was this project's only Critical, a `resume` prune that dropped a still-waiting row).
+`dismiss` never needed one, since the host's `Dismiss` publishes an ordinary terminal snapshot over
+the wire, the same as a real cancel. Use `createOperationsStore({ module, scope })` instead of the
+default export if your host renamed `OperationRegistryOptions.ModuleName` or
+you need a scope-filtered instance (a secondary window, an auxiliary session) — `clearFinished`
+forwards that scope so clearing history in one window cannot wipe another's.
+
 ### Observing the whole stream
 
 `useShenoraEvent` and `createShenoraStore` listen for an exact `(module, type)`. When the vocabulary

package/dist/bridge.d.ts

@@ -96,7 +96,7 @@ export declare class ShenoraBridge {
      * Send WITHOUT awaiting a reply, and return the request id.
      *
      * This is the default shape for a desktop shell, and {@link invoke} is the special case — see
-     * `docs/2026-07-31-shenora-oneway-ipc-design.md`. Two reasons: a correlated call carries a deadline
+     * `docs/DECISIONS.md` D23. Two reasons: a correlated call carries a deadline
      * (30 s by default) and real work does not; and request/response is UI-THREAD-COUPLED here by
      * design, because the dispatch pipeline preserves the caller's synchronization context so facades
      * can touch the window. Reserve `invoke` for calls that are quick AND safe on the UI thread — the
@@ -111,7 +111,10 @@ export declare class ShenoraBridge {
      * otherwise is. Nothing is queued and no timer is set, so there is nothing to leak and no deadline.
      *
      * No transport (a plain browser tab) is a silent no-op, matching the fire-and-forget contract —
-     * unlike `invoke`, there is no caller waiting to be told.
+     * unlike `invoke`, there is no caller waiting to be told. **A DISPOSED bridge is the same silent
+     * no-op**, and that one can surprise: `invoke` on a disposed bridge rejects with `NO_TRANSPORT`
+     * while `post` just returns the id, so a stale reference kept across a `configureBridge` swap looks
+     * like it is still sending. `isAvailable` is the check.
      */
     post<TPayload = unknown>(module: string, type: string, options?: PostOptions<TPayload>): string;
     /**

package/dist/bridge.js

@@ -124,7 +124,7 @@ export class ShenoraBridge {
      * Send WITHOUT awaiting a reply, and return the request id.
      *
      * This is the default shape for a desktop shell, and {@link invoke} is the special case — see
-     * `docs/2026-07-31-shenora-oneway-ipc-design.md`. Two reasons: a correlated call carries a deadline
+     * `docs/DECISIONS.md` D23. Two reasons: a correlated call carries a deadline
      * (30 s by default) and real work does not; and request/response is UI-THREAD-COUPLED here by
      * design, because the dispatch pipeline preserves the caller's synchronization context so facades
      * can touch the window. Reserve `invoke` for calls that are quick AND safe on the UI thread — the
@@ -139,7 +139,10 @@ export class ShenoraBridge {
      * otherwise is. Nothing is queued and no timer is set, so there is nothing to leak and no deadline.
      *
      * No transport (a plain browser tab) is a silent no-op, matching the fire-and-forget contract —
-     * unlike `invoke`, there is no caller waiting to be told.
+     * unlike `invoke`, there is no caller waiting to be told. **A DISPOSED bridge is the same silent
+     * no-op**, and that one can surprise: `invoke` on a disposed bridge rejects with `NO_TRANSPORT`
+     * while `post` just returns the id, so a stale reference kept across a `configureBridge` swap looks
+     * like it is still sending. `isAvailable` is the check.
      */
     post(module, type, options = {}) {
         const request = {

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export { ShenoraEventBus, eventBus } 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 { 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';

package/dist/index.js

@@ -9,6 +9,12 @@ export { ShenoraEventBus, eventBus } from './eventBus.js';
 export { ShenoraBridge, getBridge, configureBridge, } from './bridge.js';
 export { createShenoraStore, } from './store.js';
 export { BaseModuleService } from './moduleService.js';
+export { OperationStatuses, 
+// The event vocabulary + the default module name. `createOperationsStore` deliberately does NOT
+// subscribe to RESUME_REQUESTED / WAIT_REQUESTED — those target the OWNING module's own service,
+// not the generic store — so the app writing that handler needs both symbols, and until now had
+// neither: it had to hard-code the literals the wire-mirror tests exist to keep it from doing.
+OperationEventTypes, OperationModuleName, createOperationsStore, useShenoraOperations, } from './operations.js';
 export { WindowCommands, useWindowMaximized, } from './windowCommands.js';
 export { useDropZone, DROP_ZONE_MODULE, } from './useDropZone.js';
 export { useShenora, useShenoraEvent, useShenoraQuery } from './hooks.js';

package/dist/operations.d.ts

@@ -0,0 +1,256 @@
+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

@@ -0,0 +1,191 @@
+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();

package/dist/store.d.ts

@@ -1,8 +1,8 @@
 import { type ShenoraBridge, type PostOptions } from './bridge.js';
 import { type ShenoraEventBus } from './eventBus.js';
 import type { EventMessage } from './types.js';
-/** The IPC handles a store's `actions` are built over. */
-export interface ShenoraStoreIo {
+/** The IPC handles + local-state seam a store's `actions` are built over. */
+export interface ShenoraStoreIo<TState = unknown> {
     /** Fire-and-forget send to this store's module. Returns the request id. */
     post: <TPayload = unknown>(type: string, options?: PostOptions<TPayload>) => string;
     /** Correlated request to this store's module — for calls that are quick AND UI-thread-safe. */
@@ -10,6 +10,17 @@ export interface ShenoraStoreIo {
         payload?: TPayload;
         timeoutMs?: number;
     }) => Promise<TData>;
+    /** Current state — for an action that needs to compute an OPTIMISTIC update from it. */
+    getState: () => TState;
+    /**
+     * Apply a local state change with NO host round trip and NO wire event — the seam for an
+     * optimistic update an action can fully decide by itself (e.g. dropping the rows a
+     * `CLEAR_FINISHED`-style action just told the host to drop). The host stays authoritative for
+     * everything a `snapshot`/`on` reducer already covers; this exists for the narrow case where the
+     * action already knows the answer and a host round trip would only be a delivery delay, not new
+     * information.
+     */
+    setState: (reduce: (state: TState) => TState) => void;
 }
 /** How a store loads the state that already exists before anyone was watching. */
 export interface ShenoraStoreSnapshot<TState> {
@@ -34,7 +45,7 @@ export interface ShenoraStoreOptions<TState, TActions> {
     /** Event type (within this module) → PURE reducer over state. */
     on?: Record<string, (state: TState, payload: never, event: EventMessage) => TState>;
     /** Fire-and-forget senders / requests, exposed on the returned hook. */
-    actions?: (io: ShenoraStoreIo) => TActions;
+    actions?: (io: ShenoraStoreIo<TState>) => TActions;
     /** Optional app-defined routing scope, applied to both the subscriptions and the sends. */
     scope?: string;
     /** Test/multi-transport seams. Default: the shared bridge and event bus. */
@@ -64,7 +75,7 @@ export interface ShenoraStore<TState, TActions> {
  * A store fed by one module's host event stream, shared by every component that reads it.
  *
  * This is the shape a desktop app needs and the one three sibling apps each hand-built before it
- * existed here — see `docs/2026-07-31-shenora-oneway-ipc-design.md` §5 for the survey. It exists
+ * existed here — see `.claude/knowledge/generic-library.md`'s worked example for that survey. It exists
  * because status- and progress-driven UI is inherently MANY-WATCHERS: a full panel and a compact
  * progress strip want the same live state, and without a shared store each re-implements the wiring,
  * each opens its own subscription, and each starts empty.

package/dist/store.js

@@ -5,7 +5,7 @@ import { eventBus as defaultEventBus } from './eventBus.js';
  * A store fed by one module's host event stream, shared by every component that reads it.
  *
  * This is the shape a desktop app needs and the one three sibling apps each hand-built before it
- * existed here — see `docs/2026-07-31-shenora-oneway-ipc-design.md` §5 for the survey. It exists
+ * existed here — see `.claude/knowledge/generic-library.md`'s worked example for that survey. It exists
  * because status- and progress-driven UI is inherently MANY-WATCHERS: a full panel and a compact
  * progress strip want the same live state, and without a shared store each re-implements the wiring,
  * each opens its own subscription, and each starts empty.
@@ -116,6 +116,8 @@ export function createShenoraStore(module, options) {
     const io = {
         post: (type, postOptions) => bridge().post(module, type, { scope, ...postOptions }),
         invoke: (type, invokeOptions) => bridge().invoke(module, type, { scope, ...invokeOptions }),
+        getState,
+        setState: (reduce) => setState(reduce(getState())),
     };
     function useStore(selector) {
         // getSnapshot must return a STABLE value for an unchanged store, or React throws

package/dist/useDropZone.d.ts

@@ -42,6 +42,17 @@ export interface UseDropZoneOptions {
     bus?: ShenoraEventBus;
 }
 /**
+ * **The file-drop API for a Shenora page. Do not use the DOM's own drop event for files —
+ * it is not an alternative here, it is the thing this exists to replace.**
+ *
+ * A page-side `onDrop` gets a `File` handle whose only accessor is its CONTENT. In a shell
+ * architecture the page is UI and the host does the file work, so those bytes have to be read into
+ * the renderer and then pushed across the IPC boundary: a full copy of every dropped file, EAGERLY,
+ * at drop time, before the app knows whether it wants any of them. Drop 200 files to filter by
+ * extension and you pay for all 200; drop a multi-GB asset and you pay that, to reach a file the
+ * host could have opened off the same disk. This hook gives you `string[]` paths instead — open
+ * lazily, stream, hash incrementally, move or link without copying, watch for changes.
+ *
  * Sync a native drop-zone overlay to a page element, ported from the primary desktop sibling
  * (its fix-history comments kept below): the host positions a transparent WinForms overlay
  * over the element to capture REAL OS file paths — including drags started while the app is in

package/dist/useDropZone.js

@@ -6,6 +6,17 @@ import { debounce, randomId } from './internal.js';
 export const DROP_ZONE_MODULE = 'DROP_ZONE';
 const newZoneId = () => randomId('drop-zone-');
 /**
+ * **The file-drop API for a Shenora page. Do not use the DOM's own drop event for files —
+ * it is not an alternative here, it is the thing this exists to replace.**
+ *
+ * A page-side `onDrop` gets a `File` handle whose only accessor is its CONTENT. In a shell
+ * architecture the page is UI and the host does the file work, so those bytes have to be read into
+ * the renderer and then pushed across the IPC boundary: a full copy of every dropped file, EAGERLY,
+ * at drop time, before the app knows whether it wants any of them. Drop 200 files to filter by
+ * extension and you pay for all 200; drop a multi-GB asset and you pay that, to reach a file the
+ * host could have opened off the same disk. This hook gives you `string[]` paths instead — open
+ * lazily, stream, hash incrementally, move or link without copying, watch for changes.
+ *
  * Sync a native drop-zone overlay to a page element, ported from the primary desktop sibling
  * (its fix-history comments kept below): the host positions a transparent WinForms overlay
  * over the element to capture REAL OS file paths — including drags started while the app is in

package/dist/windowCommands.d.ts

@@ -72,9 +72,13 @@ export declare class WindowCommands extends BaseModuleService<WindowRequests> {
 }
 /**
  * The max/restore-glyph resync pattern from the source app: the authoritative maximize state,
- * re-queried on every window resize (a maximize/restore always resizes the window, and the DOM
- * has no other signal for the manual work-area maximize). Failures (plain browser, no host)
- * leave it false.
+ * re-queried when a resize SETTLES (a maximize/restore always resizes the window, and the DOM has no
+ * other signal for the manual work-area maximize). Failures (plain browser, no host) leave it false.
+ *
+ * Read once immediately, then on the TRAILING edge of a 100 ms debounce — not once per `resize`
+ * event, which a window drag fires ~180 times in three seconds. Coalescing is the correct semantics
+ * here, not just the cheap one: maximize/restore is a single step, so only the end state matters. Do
+ * not build on intermediate values during a drag; there are none.
  */
 export declare function useWindowMaximized(commands?: WindowCommands): boolean;
 export {};

package/dist/windowCommands.js

@@ -60,9 +60,13 @@ export class WindowCommands extends BaseModuleService {
 }
 /**
  * The max/restore-glyph resync pattern from the source app: the authoritative maximize state,
- * re-queried on every window resize (a maximize/restore always resizes the window, and the DOM
- * has no other signal for the manual work-area maximize). Failures (plain browser, no host)
- * leave it false.
+ * re-queried when a resize SETTLES (a maximize/restore always resizes the window, and the DOM has no
+ * other signal for the manual work-area maximize). Failures (plain browser, no host) leave it false.
+ *
+ * Read once immediately, then on the TRAILING edge of a 100 ms debounce — not once per `resize`
+ * event, which a window drag fires ~180 times in three seconds. Coalescing is the correct semantics
+ * here, not just the cheap one: maximize/restore is a single step, so only the end state matters. Do
+ * not build on intermediate values during a drag; there are none.
  */
 export function useWindowMaximized(commands) {
     const [maximized, setMaximized] = useState(false);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shenora/react",
-  "version": "0.1.2",
+  "version": "0.4.0",
   "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.",
   "license": "MIT",
   "author": "Jiarong Gu",