@shenora/react 0.11.0 → 0.12.0

package/dist/segmentStream.d.ts

@@ -2,17 +2,25 @@
  * The page half of the host's segment route (D71 piece 4) — reading the manifest it serves, choosing the
  * MediaSource this browser actually has, and deciding what to fetch next.
  *
- * 🔴 **Everything in this module is PURE, and the split is deliberate.** The DECISIONS live here, where a
- * test pins them exactly, and `segmentBinder.ts` holds the imperative half — creating a `SourceBuffer`,
- * appending bytes, listening to element events. That is the same division `SegmentGrid` makes on the host
- * side, for the same reason.
+ * Everything here is PURE: the decisions live in this module and `segmentBinder.ts` holds the
+ * imperative half — creating a `SourceBuffer`, appending bytes, listening to element events.
+ */
+/**
+ * The reserved path segment naming a source by the handle the HOST issued for it:
+ * `{routePath}${SEGMENT_REMOTE_PREFIX}{handle}/index.m3u8`.
  *
- * ⚠ **"The imperative half cannot be verified anywhere this repo runs" was true and is no longer.** jsdom
- * still has no MediaSource and both real implementations still live on devices — but the binder takes its
- * source and its fetch as PARAMETERS, so a fake drives every branch of it. What a fake cannot say is
- * whether a real implementation accepts the bytes; that is measured on hardware and recorded in
- * `docs/design/media.md`.
+ * 🔴 **A page cannot name a remote url, only a handle.** The host's `MediaSourceRegistry` issues one when
+ * the app authorises a source, and the route accepts nothing else. Mirrors
+ * `SegmentStreamOptions.RemotePrefix`.
  */
+export declare const SEGMENT_REMOTE_PREFIX = "~remote/";
+/**
+ * The manifest url for a handle the app handed this page.
+ *
+ * ⚠ The handle is opaque and is NOT a url — do not build one from it, and do not log it beside anything
+ * that identifies the user. It is a capability: whoever holds it can stream that source.
+ */
+export declare function remoteSegmentUrl(routePath: string, handle: string, resource?: string): string;
 /** One entry in the playlist the host serves. */
 export interface SegmentEntry {
     /** Relative to the manifest — `seg12.m4s`. */
@@ -26,8 +34,8 @@ export interface SegmentManifest {
      * The initialisation segment (`#EXT-X-MAP`), which carries the tracks and their decoder configuration.
      *
      * ⚠ **Null means the playlist declared none, and that is not playable through MediaSource** — a fragment
-     * repeats no configuration, so appending one without this produces a silent decode error. The kit's host
-     * route always writes it; a foreign playlist may not.
+     * repeats no configuration, so appending one without this is a silent decode error. The kit's host route
+     * always writes it; a foreign playlist may not.
      */
     initUri: string | null;
     /** The longest a segment may be, from `#EXT-X-TARGETDURATION`. */
@@ -35,11 +43,9 @@ export interface SegmentManifest {
     segments: SegmentEntry[];
 }
 /**
- * Parse the subset of HLS the host emits. Deliberately NOT a general playlist parser: this reads what
- * `SegmentStream` writes, and anything it does not understand is ignored rather than guessed at.
+ * Parse the subset of HLS the host's `SegmentStream` emits — not a general playlist parser.
  *
- * ⚠ Unknown tags are skipped silently BY DESIGN — a playlist gains tags over time and a parser that threw
- * on the first one it had not met would break on a host newer than the page.
+ * ⚠ An unknown tag is SKIPPED, never an error, so a host newer than the page still parses.
  */
 export declare function parseManifest(text: string): SegmentManifest;
 /** Which MediaSource implementation this browser has, if any. */
@@ -52,20 +58,13 @@ export interface MediaSourceGlobals {
 /**
  * Which MediaSource to use — **`ManagedMediaSource` first where it exists**.
  *
- * 🔴 **The order is the decision, and it is not "newest wins".** iOS on iPhone has only
- * `ManagedMediaSource`; Android has only `MediaSource`. Where BOTH exist the managed one is still preferred,
- * because it is the one that tells the page when the platform actually wants data — a page that streams
- * regardless is what the managed variant was introduced to stop.
- *
- * ✅ **Measured rather than assumed** (iPhone 16 Pro simulator, iOS 26, 2026-08-14): `window.MediaSource` is
- * `false` there and `ManagedMediaSource` is `true`. So on iOS this is not a preference at all — **a binder
- * that only knows `window.MediaSource` does nothing**, and the naming here is what makes one bundle work on
- * both shells.
+ * 🔴 **iOS has ONLY `ManagedMediaSource` and Android has ONLY `MediaSource`**, so a binder that knows
+ * just `window.MediaSource` does nothing at all on iOS. Where both exist the managed one still wins:
+ * it is the one that says when the platform actually wants data. (Measured — `docs/design/media.md`.)
  *
- * ⚠ **`'managed'` carries an obligation, which is why this returns a KIND rather than just a constructor.**
- * A managed source only wants data between its `startstreaming` and `endstreaming` events, and fetching
- * outside that window is the thing it exists to prevent. A caller that ignores the kind has not merely
- * missed an optimisation.
+ * ⚠ **`'managed'` carries an obligation, which is why this returns a KIND and not a constructor.** A
+ * managed source only wants data between its `startstreaming` and `endstreaming` events, and fetching
+ * outside that window is the misuse it exists to detect.
  */
 export declare function pickMediaSource(globals: MediaSourceGlobals): MediaSourceKind;
 /** What {@link nextSegment} needs to know about the element and the buffer. */
@@ -88,29 +87,25 @@ export interface FetchPolicy {
 /**
  * The next segment index to fetch, or null for "nothing right now".
  *
- * 🔴 **Every branch here is a decision whose failure is SILENT in a browser**, which is why it is a pure
- * function with a test rather than an `if` inside an event handler:
+ * 🔴 **Every branch is a decision whose failure is SILENT in a browser:**
  *
- * - **Not streaming → null.** A managed source that is fetched while it said stop is the exact misuse it
- *   exists to detect, and on iOS the penalty is the platform tearing the source down.
- * - **Enough buffered → null.** Fetching further ahead than the policy asks does not make playback smoother;
- *   it fills a quota, and a `QuotaExceededError` on append arrives as a stall with no obvious cause.
- * - **Otherwise the segment CONTAINING `currentTime`, or the first unappended one after it.** Starting from
- *   "the next index after the last one appended" instead is what breaks seeking: after a jump the last
- *   append is nowhere near where the user is now.
+ * - **Not streaming → null.** On iOS the penalty for fetching past `endstreaming` is the platform
+ *   tearing the source down.
+ * - **Enough buffered → null.** Fetching further ahead fills a quota, and a `QuotaExceededError` on
+ *   append arrives as a stall with no obvious cause.
+ * - **Otherwise the segment CONTAINING `currentTime`, or the first unappended one after it** — never
+ *   "the next index after the last append", which breaks seeking.
  */
 export declare function nextSegment(state: FetchState, policy: FetchPolicy): number | null;
 /**
- * The MIME type to open a `SourceBuffer` with.
+ * The MIME type to open a `SourceBuffer` with. The default is H.264 High 4.0 plus AAC-LC.
  *
  * ⚠ **The codecs parameter is REQUIRED, not decorative.** `addSourceBuffer('video/mp4')` throws
- * `NotSupportedError` on every implementation — the buffer has to know what it is about to be fed before the
- * init segment arrives. The default is H.264 High 4.0 plus AAC-LC.
+ * `NotSupportedError` on every implementation — the buffer has to know what it is about to be fed
+ * before the init segment arrives.
  *
- * 🔴 **And the default is a DEFAULT rather than a guarantee, because the host copies whatever the source
- * already holds** (D76): a segment's picture keeps the profile and level the original encoder chose, and an
- * HEVC source arrives as `hvc1` and not `avc1` at all. The family is what an implementation actually checks,
- * so an H.264 source of any profile plays through the default — **an HEVC one needs its own string**, e.g.
+ * ⚠ The default is not a guarantee: the host copies whatever the source already holds (D76), so an
+ * **HEVC source arrives as `hvc1` and needs its own string**, e.g.
  * `segmentMimeType('hvc1.1.6.L93.B0,mp4a.40.2')`.
  */
 export declare function segmentMimeType(codecs?: string): string;
@@ -118,16 +113,10 @@ export declare function segmentMimeType(codecs?: string): string;
  * Read the codecs parameter out of an initialisation segment, so the `SourceBuffer` is opened for the
  * tracks it will actually be fed.
  *
- * 🔴 **The TRACK SET is the part that must be right, and getting it wrong is fatal rather than
- * degraded.** Measured against Chromium 151 on the kit's own segments: a video-only init segment
- * appended to a buffer opened with the two-track default (`avc1.640028,mp4a.40.2`) fails the FIRST
- * append and plays nothing at all — while the same bytes with `avc1.640015` play. A source with no
- * soundtrack is ordinary, so a fixed default cannot serve both.
- *
- * ⚠ **The profile and level, by contrast, are barely checked.** The same measurement fed High 2.1
- * content to a buffer opened as Baseline 3.0 (`avc1.42E01E`) and it played. That is why this returns a
- * precise string when the configuration is there to read and a family default when it is not: precision
- * where it is free, and never a guess about which tracks exist.
+ * 🔴 **The TRACK SET must be right, and getting it wrong is fatal rather than degraded**: a video-only
+ * init segment appended to a buffer opened with the two-track default fails the FIRST append and plays
+ * nothing. A source with no soundtrack is ordinary, so no fixed default serves both. (The profile and
+ * level, by contrast, are barely checked — `docs/design/media.md` has the measurements.)
  *
  * @param init The bytes of the `#EXT-X-MAP` segment.
  * @returns A codecs string for {@link segmentMimeType}, or null when no track could be read — the caller

package/dist/segmentStream.js

@@ -2,23 +2,32 @@
  * The page half of the host's segment route (D71 piece 4) — reading the manifest it serves, choosing the
  * MediaSource this browser actually has, and deciding what to fetch next.
  *
- * 🔴 **Everything in this module is PURE, and the split is deliberate.** The DECISIONS live here, where a
- * test pins them exactly, and `segmentBinder.ts` holds the imperative half — creating a `SourceBuffer`,
- * appending bytes, listening to element events. That is the same division `SegmentGrid` makes on the host
- * side, for the same reason.
+ * Everything here is PURE: the decisions live in this module and `segmentBinder.ts` holds the
+ * imperative half — creating a `SourceBuffer`, appending bytes, listening to element events.
+ */
+/**
+ * The reserved path segment naming a source by the handle the HOST issued for it:
+ * `{routePath}${SEGMENT_REMOTE_PREFIX}{handle}/index.m3u8`.
+ *
+ * 🔴 **A page cannot name a remote url, only a handle.** The host's `MediaSourceRegistry` issues one when
+ * the app authorises a source, and the route accepts nothing else. Mirrors
+ * `SegmentStreamOptions.RemotePrefix`.
+ */
+export const SEGMENT_REMOTE_PREFIX = '~remote/';
+/**
+ * The manifest url for a handle the app handed this page.
  *
- * ⚠ **"The imperative half cannot be verified anywhere this repo runs" was true and is no longer.** jsdom
- * still has no MediaSource and both real implementations still live on devices — but the binder takes its
- * source and its fetch as PARAMETERS, so a fake drives every branch of it. What a fake cannot say is
- * whether a real implementation accepts the bytes; that is measured on hardware and recorded in
- * `docs/design/media.md`.
+ * ⚠ The handle is opaque and is NOT a url — do not build one from it, and do not log it beside anything
+ * that identifies the user. It is a capability: whoever holds it can stream that source.
  */
+export function remoteSegmentUrl(routePath, handle, resource = 'index.m3u8') {
+    const base = routePath.endsWith('/') ? routePath : `${routePath}/`;
+    return `${base}${SEGMENT_REMOTE_PREFIX}${encodeURIComponent(handle)}/${resource}`;
+}
 /**
- * Parse the subset of HLS the host emits. Deliberately NOT a general playlist parser: this reads what
- * `SegmentStream` writes, and anything it does not understand is ignored rather than guessed at.
+ * Parse the subset of HLS the host's `SegmentStream` emits — not a general playlist parser.
  *
- * ⚠ Unknown tags are skipped silently BY DESIGN — a playlist gains tags over time and a parser that threw
- * on the first one it had not met would break on a host newer than the page.
+ * ⚠ An unknown tag is SKIPPED, never an error, so a host newer than the page still parses.
  */
 export function parseManifest(text) {
     const segments = [];
@@ -54,20 +63,13 @@ export function parseManifest(text) {
 /**
  * Which MediaSource to use — **`ManagedMediaSource` first where it exists**.
  *
- * 🔴 **The order is the decision, and it is not "newest wins".** iOS on iPhone has only
- * `ManagedMediaSource`; Android has only `MediaSource`. Where BOTH exist the managed one is still preferred,
- * because it is the one that tells the page when the platform actually wants data — a page that streams
- * regardless is what the managed variant was introduced to stop.
+ * 🔴 **iOS has ONLY `ManagedMediaSource` and Android has ONLY `MediaSource`**, so a binder that knows
+ * just `window.MediaSource` does nothing at all on iOS. Where both exist the managed one still wins:
+ * it is the one that says when the platform actually wants data. (Measured — `docs/design/media.md`.)
  *
- * ✅ **Measured rather than assumed** (iPhone 16 Pro simulator, iOS 26, 2026-08-14): `window.MediaSource` is
- * `false` there and `ManagedMediaSource` is `true`. So on iOS this is not a preference at all — **a binder
- * that only knows `window.MediaSource` does nothing**, and the naming here is what makes one bundle work on
- * both shells.
- *
- * ⚠ **`'managed'` carries an obligation, which is why this returns a KIND rather than just a constructor.**
- * A managed source only wants data between its `startstreaming` and `endstreaming` events, and fetching
- * outside that window is the thing it exists to prevent. A caller that ignores the kind has not merely
- * missed an optimisation.
+ * ⚠ **`'managed'` carries an obligation, which is why this returns a KIND and not a constructor.** A
+ * managed source only wants data between its `startstreaming` and `endstreaming` events, and fetching
+ * outside that window is the misuse it exists to detect.
  */
 export function pickMediaSource(globals) {
     if (typeof globals.ManagedMediaSource === 'function')
@@ -79,16 +81,14 @@ export function pickMediaSource(globals) {
 /**
  * The next segment index to fetch, or null for "nothing right now".
  *
- * 🔴 **Every branch here is a decision whose failure is SILENT in a browser**, which is why it is a pure
- * function with a test rather than an `if` inside an event handler:
+ * 🔴 **Every branch is a decision whose failure is SILENT in a browser:**
  *
- * - **Not streaming → null.** A managed source that is fetched while it said stop is the exact misuse it
- *   exists to detect, and on iOS the penalty is the platform tearing the source down.
- * - **Enough buffered → null.** Fetching further ahead than the policy asks does not make playback smoother;
- *   it fills a quota, and a `QuotaExceededError` on append arrives as a stall with no obvious cause.
- * - **Otherwise the segment CONTAINING `currentTime`, or the first unappended one after it.** Starting from
- *   "the next index after the last one appended" instead is what breaks seeking: after a jump the last
- *   append is nowhere near where the user is now.
+ * - **Not streaming → null.** On iOS the penalty for fetching past `endstreaming` is the platform
+ *   tearing the source down.
+ * - **Enough buffered → null.** Fetching further ahead fills a quota, and a `QuotaExceededError` on
+ *   append arrives as a stall with no obvious cause.
+ * - **Otherwise the segment CONTAINING `currentTime`, or the first unappended one after it** — never
+ *   "the next index after the last append", which breaks seeking.
  */
 export function nextSegment(state, policy) {
     if (!state.streaming)
@@ -97,8 +97,8 @@ export function nextSegment(state, policy) {
         return null;
     if (policy.segments.length === 0)
         return null;
-    // Walk the playlist's own durations rather than assuming a fixed grid: the LAST segment is short, so
-    // dividing by the target duration puts the tail index past the end.
+    // Walk the playlist's own durations rather than assuming a fixed grid: the LAST segment is short,
+    // so dividing by the target duration puts the tail index past the end.
     let at = 0;
     let index = 0;
     for (; index < policy.segments.length; index++) {
@@ -114,16 +114,14 @@ export function nextSegment(state, policy) {
     return null;
 }
 /**
- * The MIME type to open a `SourceBuffer` with.
+ * The MIME type to open a `SourceBuffer` with. The default is H.264 High 4.0 plus AAC-LC.
  *
  * ⚠ **The codecs parameter is REQUIRED, not decorative.** `addSourceBuffer('video/mp4')` throws
- * `NotSupportedError` on every implementation — the buffer has to know what it is about to be fed before the
- * init segment arrives. The default is H.264 High 4.0 plus AAC-LC.
+ * `NotSupportedError` on every implementation — the buffer has to know what it is about to be fed
+ * before the init segment arrives.
  *
- * 🔴 **And the default is a DEFAULT rather than a guarantee, because the host copies whatever the source
- * already holds** (D76): a segment's picture keeps the profile and level the original encoder chose, and an
- * HEVC source arrives as `hvc1` and not `avc1` at all. The family is what an implementation actually checks,
- * so an H.264 source of any profile plays through the default — **an HEVC one needs its own string**, e.g.
+ * ⚠ The default is not a guarantee: the host copies whatever the source already holds (D76), so an
+ * **HEVC source arrives as `hvc1` and needs its own string**, e.g.
  * `segmentMimeType('hvc1.1.6.L93.B0,mp4a.40.2')`.
  */
 export function segmentMimeType(codecs = 'avc1.640028,mp4a.40.2') {
@@ -133,16 +131,10 @@ export function segmentMimeType(codecs = 'avc1.640028,mp4a.40.2') {
  * Read the codecs parameter out of an initialisation segment, so the `SourceBuffer` is opened for the
  * tracks it will actually be fed.
  *
- * 🔴 **The TRACK SET is the part that must be right, and getting it wrong is fatal rather than
- * degraded.** Measured against Chromium 151 on the kit's own segments: a video-only init segment
- * appended to a buffer opened with the two-track default (`avc1.640028,mp4a.40.2`) fails the FIRST
- * append and plays nothing at all — while the same bytes with `avc1.640015` play. A source with no
- * soundtrack is ordinary, so a fixed default cannot serve both.
- *
- * ⚠ **The profile and level, by contrast, are barely checked.** The same measurement fed High 2.1
- * content to a buffer opened as Baseline 3.0 (`avc1.42E01E`) and it played. That is why this returns a
- * precise string when the configuration is there to read and a family default when it is not: precision
- * where it is free, and never a guess about which tracks exist.
+ * 🔴 **The TRACK SET must be right, and getting it wrong is fatal rather than degraded**: a video-only
+ * init segment appended to a buffer opened with the two-track default fails the FIRST append and plays
+ * nothing. A source with no soundtrack is ordinary, so no fixed default serves both. (The profile and
+ * level, by contrast, are barely checked — `docs/design/media.md` has the measurements.)
  *
  * @param init The bytes of the `#EXT-X-MAP` segment.
  * @returns A codecs string for {@link segmentMimeType}, or null when no track could be read — the caller
@@ -151,8 +143,8 @@ export function segmentMimeType(codecs = 'avc1.640028,mp4a.40.2') {
 export function codecsFromInitSegment(init) {
     const view = new DataView(init.buffer, init.byteOffset, init.byteLength);
     const codecs = [];
-    /** Bytes are read through the view rather than by index: `noUncheckedIndexedAccess` types `init[i]`
-     * as possibly-undefined, and a `!` on every read would hide the one that IS out of range. */
+    /** Read through the view, not by index: a `!` on every `init[i]` would hide the one that IS out of
+     * range, where `getUint8` throws. */
     const u8 = (at) => view.getUint8(at);
     const fourcc = (at) => String.fromCharCode(u8(at), u8(at + 1), u8(at + 2), u8(at + 3));
     const hex2 = (n) => n.toString(16).padStart(2, '0');
@@ -178,9 +170,8 @@ export function codecsFromInitSegment(init) {
     };
     /** The `avcC`/`hvcC`/`esds` inside a sample entry, whose own fields come first. */
     const configuration = (format, start, end) => {
-        // Measured against the host's own init segment: an `avc1` entry holds 132 bytes of content and a
-        // 54-byte `avcC`, so the child boxes start 78 in — the 8-byte SampleEntry base (6 reserved + a data
-        // reference index) plus VisualSampleEntry's 70. An `mp4a` entry is that base plus 20.
+        // The child boxes start after the sample entry's own fields: the 8-byte SampleEntry base
+        // (6 reserved + a data reference index) plus VisualSampleEntry's 70, or plus 20 for `mp4a`.
         const visual = format === 'avc1' || format === 'avc3' || format === 'hvc1' || format === 'hev1';
         const at = start + (visual ? 78 : 28);
         let derived = '';
@@ -206,8 +197,8 @@ export function codecsFromInitSegment(init) {
                     `${tier ? 'H' : 'L'}${level}`;
             }
             else if (type === 'esds' && s + 21 <= end) {
-                // The object type indication, then the audio object type from the DecoderSpecificInfo's first
-                // 5 bits. Only AAC is ever copied here, so the walk stays a search rather than a full parser.
+                // The audio object type, from the DecoderSpecificInfo's first 5 bits. Only AAC is ever copied
+                // here, so the walk stays a search rather than a full descriptor parser.
                 for (let p = s; p + 2 < end; p++) {
                     if (u8(p) === 0x04 && u8(p + 2) === 0x40) {
                         derived = `mp4a.40.${u8(p + 3) || 2}`;

package/dist/store.d.ts

@@ -17,12 +17,9 @@ export interface ShenoraStoreIo<TState = unknown> {
      * action can fully decide by itself. The host stays authoritative for everything a `snapshot`/`on`
      * reducer covers; this is for state the ACTION already knows and the host would only echo back.
      *
-     * 🔴 **Reach for it only when the host has no event to tell you.** This used to be documented with
-     * the kit's own `clearFinished` doing an optimistic prune, and that example was WITHDRAWN: the
-     * moment `REQUEST_REMOVED` existed, the local prune became a second thing deciding which rows are
-     * gone, able to disagree with the host about it. If the host emits an event for the change, let the
-     * reducer own it — an optimistic path beside a wire event is a divergence waiting to happen, not a
-     * latency win.
+     * 🔴 **Reach for it only when the host has no event to tell you.** If one exists, let the reducer
+     * own it: an optimistic path beside a wire event is a second thing deciding the same state, and it
+     * can disagree with the host.
      */
     setState: (reduce: (state: TState) => TState) => void;
 }
@@ -34,15 +31,16 @@ export interface ShenoraStoreSnapshot<TState> {
     /** Fold the response into state. */
     apply: (state: TState, data: unknown) => TState;
 }
+/** Inputs for {@link createShenoraStore}. */
 export interface ShenoraStoreOptions<TState, TActions> {
     /** State before anything has arrived. */
     initial: TState;
     /**
      * Load the CURRENT state when the first component subscribes.
      *
-     * Not optional in spirit, even though it is in the type: a component that mounts while work is
-     * already in flight has MISSED the events, and a stream cannot be replayed. Snapshot-then-deltas
-     * is the contract; deltas alone silently work only for whoever was watching from the start.
+     * ⚠ Optional in the type only. A component that mounts while work is already in flight has MISSED
+     * those events and a stream cannot be replayed, so deltas alone work silently only for whoever was
+     * watching from the start.
      */
     snapshot?: ShenoraStoreSnapshot<TState>;
     /** Event type (within this module) → PURE reducer over state. */
@@ -75,28 +73,19 @@ export interface ShenoraStore<TState, TActions> {
     reset: () => void;
 }
 /**
- * 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 `.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.
+ * A store fed by one module's host event stream, shared by every component that reads it — for the
+ * status- and progress-driven UI that is inherently many-watchers, where a full panel and a compact
+ * progress strip want the same live state.
  *
  * What it guarantees:
  * - **One subscription per event type, however many components read it.** Mounting N components does
  *   not open N subscriptions; unmounting the last one tears them down.
  * - **A late mounter sees current state**, via {@link ShenoraStoreOptions.snapshot} on the first
- *   subscription. This is the part that cannot be retrofitted by subscribing harder.
- * - **No state library.** Built on React's `useSyncExternalStore`, which exists for exactly this and
- *   is tearing-free under concurrent rendering. The kit imposes no store dependency (D13's spirit —
- *   apps bring their own); every sibling reached for the same one, and baking that in would have been
- *   solving their stack rather than their problem.
- * - **Reducers are PURE and isolated**: they take state + payload and return state, so a store is
- *   testable with no bridge, and a throwing reducer is reported rather than corrupting shared state.
- *
- * Headless (D13/D21): the kit ships the MECHANISM. What an operation is — its phases, its progress
- * shape, whether it queues — stays in the app; there is deliberately no job/queue/progress type here.
+ *   subscription.
+ * - **No state library.** Built on React's `useSyncExternalStore`, so it is tearing-free under
+ *   concurrent rendering and imposes no store dependency on the app.
+ * - **Reducers are PURE and isolated**: state + payload in, state out, so a store is testable with no
+ *   bridge and a throwing reducer is reported rather than corrupting shared state.
  *
  * @example
  * const useDeploy = createShenoraStore('DEPLOY', {

package/dist/store.js

@@ -1,16 +1,12 @@
 import { useCallback, useDebugValue, useRef, useSyncExternalStore } from 'react';
 import { getBridge } from './bridge.js';
 import { eventBus as defaultEventBus } from './eventBus.js';
-/** Inputs for {@link createShenoraStore}. */
 /**
  * Is the fresh selector result the same VALUE as the previous one, for re-render purposes?
  *
  * `Object.is` plus ONE level of own-key comparison. The shallow step is what lets an inline selector
  * that derives a new object work — `s => ({ count: s.lines.length })` builds a different object every
- * call, and without this every call would look like a change and loop.
- *
- * ⚠ Deliberately one level. Deep equality would make an unchanged NESTED value hide a changed outer
- * one only by cost, and a store whose selectors need deep comparison is selecting too much.
+ * call, and without it every call would look like a change and loop.
  */
 function equivalent(a, b) {
     if (Object.is(a, b))
@@ -28,28 +24,19 @@ function equivalent(a, b) {
         && Object.is(a[k], b[k]));
 }
 /**
- * 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 `.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.
+ * A store fed by one module's host event stream, shared by every component that reads it — for the
+ * status- and progress-driven UI that is inherently many-watchers, where a full panel and a compact
+ * progress strip want the same live state.
  *
  * What it guarantees:
  * - **One subscription per event type, however many components read it.** Mounting N components does
  *   not open N subscriptions; unmounting the last one tears them down.
  * - **A late mounter sees current state**, via {@link ShenoraStoreOptions.snapshot} on the first
- *   subscription. This is the part that cannot be retrofitted by subscribing harder.
- * - **No state library.** Built on React's `useSyncExternalStore`, which exists for exactly this and
- *   is tearing-free under concurrent rendering. The kit imposes no store dependency (D13's spirit —
- *   apps bring their own); every sibling reached for the same one, and baking that in would have been
- *   solving their stack rather than their problem.
- * - **Reducers are PURE and isolated**: they take state + payload and return state, so a store is
- *   testable with no bridge, and a throwing reducer is reported rather than corrupting shared state.
- *
- * Headless (D13/D21): the kit ships the MECHANISM. What an operation is — its phases, its progress
- * shape, whether it queues — stays in the app; there is deliberately no job/queue/progress type here.
+ *   subscription.
+ * - **No state library.** Built on React's `useSyncExternalStore`, so it is tearing-free under
+ *   concurrent rendering and imposes no store dependency on the app.
+ * - **Reducers are PURE and isolated**: state + payload in, state out, so a store is testable with no
+ *   bridge and a throwing reducer is reported rather than corrupting shared state.
  *
  * @example
  * const useDeploy = createShenoraStore('DEPLOY', {
@@ -73,8 +60,8 @@ export function createShenoraStore(module, options) {
     let state = initial;
     let snapshotLoaded = false;
     // Bumped on detach. A snapshot response from an earlier subscriber epoch resolving late must be
-    // DROPPED: the current epoch has (or will have) its own, fresher request, and applying the old
-    // body after the new one is a lost update wearing a success path.
+    // DROPPED — the current epoch has its own fresher request, and applying the old body over the new
+    // one is a lost update wearing a success path.
     let snapshotEpoch = 0;
     const listeners = new Set();
     let unsubscribes = [];
@@ -95,16 +82,15 @@ export function createShenoraStore(module, options) {
             setState(reduce(state, event.payload, event));
         }
         catch (error) {
-            // A throwing reducer must not corrupt shared state or break the other subscribers — the same
-            // guarded-callback rule the host applies to app code (Shenora.AppCallback).
+            // A throwing reducer must not corrupt shared state or break the other subscribers.
             report(error, { module, type });
         }
     };
     const loadSnapshot = () => {
         if (!snapshot || snapshotLoaded)
             return;
-        snapshotLoaded = true; // set BEFORE awaiting: two components mounting in the same tick must not
-        // both fire the request (React StrictMode double-invokes effects, which is precisely this case).
+        snapshotLoaded = true; // set BEFORE awaiting: two components mounting in the same tick (React
+        // StrictMode double-invokes effects) must not both fire the request.
         const epoch = snapshotEpoch;
         bridge()
             .invoke(module, snapshot.type, { payload: snapshot.payload, scope })
@@ -120,8 +106,8 @@ export function createShenoraStore(module, options) {
         }, (error) => {
             if (epoch !== snapshotEpoch)
                 return;
-            // Allow a later retry: a snapshot that failed because the host was not ready yet should not
-            // leave the store permanently empty for the rest of the session.
+            // Allow a later retry: a snapshot that failed because the host was not ready yet must not
+            // leave the store permanently empty.
             snapshotLoaded = false;
             report(error, { module, type: snapshot.type });
         });
@@ -134,17 +120,15 @@ export function createShenoraStore(module, options) {
         for (const off of unsubscribes)
             off();
         unsubscribes = [];
-        // The next mount must RE-LOAD: with no bus subscription live, everything the host emits from
-        // here on is missed, so the snapshot the flag was guarding is stale the moment this returns.
-        // The flag exists to dedupe same-tick double-mounts (StrictMode), not to span subscriber epochs —
-        // and the epoch bump orphans any request still in flight, so its late answer cannot clobber the
-        // next epoch's fresher one.
+        // The next mount must RE-LOAD: with no bus subscription live, everything the host emits from here
+        // on is missed, so the snapshot the flag was guarding is stale the moment this returns. The epoch
+        // bump orphans any request still in flight, so its late answer cannot clobber the next one.
         snapshotLoaded = false;
         snapshotEpoch++;
     };
     const subscribe = (listener) => {
-        // ONE subscription per event type for the whole store — the property that makes this worth
-        // existing. The first listener attaches; the last one to leave detaches.
+        // ONE subscription per event type for the whole store: the first listener attaches, the last one
+        // to leave detaches.
         if (listeners.size === 0)
             attach();
         listeners.add(listener);
@@ -164,26 +148,14 @@ export function createShenoraStore(module, options) {
     /**
      * Subscribe to the store, optionally through a selector.
      *
-     * 🔴 **The selector is RE-RUN every time and the previous RESULT is reused when equivalent.** It used
-     * to be memoized against STATE identity alone, which looked like the careful thing and was wrong: a
-     * selector whose closure changed while the state did not returned the PREVIOUS selector's value. A
-     * list row doing `useShenoraRequests(s => s.byId[id])` whose `id` prop changes — virtualised reuse, a
-     * route change — rendered the previous row's data until some unrelated event replaced the state.
-     *
-     * ⚠ <b>Two requirements pull against each other and both are met by comparing RESULTS rather than
-     * inputs.</b> `useSyncExternalStore` re-renders whenever `getSnapshot` returns something new by
-     * `Object.is`, so:
-     * <list type="bullet">
-     * <item>keying the cache on STATE alone gives stale values when the selector changes — the bug above;</item>
-     * <item>keying it on the SELECTOR too loops forever for an inline selector that derives a new object
-     * (`s => ({ count: s.lines.length })`) — a fresh identity each render, a fresh object each call.
-     * zustand v5 has exactly that behaviour and answers it with an opt-in `useShallow`.</item>
-     * </list>
-     * Comparing the RESULT shallowly gives both: a derived object that is field-for-field the same reuses
-     * the previous reference and does not re-render, while a genuinely different row does.
+     * 🔴 **The selector is RE-RUN every time and the previous RESULT is reused when equivalent** — never
+     * cached against the state or the selector, both of which fail silently. Keying on STATE alone
+     * returns the PREVIOUS selector's value when the closure changes (a list row doing
+     * `s => s.byId[id]` whose `id` prop changes renders the previous row's data); keying on the SELECTOR
+     * too loops forever for an inline selector that derives a new object (`s => ({ n: s.lines.length })`).
      */
     function useStore(selector) {
-        // The last result handed to React. Reused whenever the fresh one is equivalent, which is what keeps
+        // The last result handed to React, reused whenever the fresh one is equivalent — what keeps
         // getSnapshot stable without pinning it to an input that can go stale.
         const previous = useRef(null);
         const getSelected = useCallback(() => {

package/dist/transport.d.ts

@@ -10,14 +10,9 @@ export interface ShenoraTransport {
     subscribe(listener: (message: string) => void): () => void;
 }
 /**
- * True when running inside ANY Shenora host — a WebView2 desktop shell or a MAUI
- * `HybridWebView` — i.e. when a transport to the host exists. In a plain browser this is false and
- * callers should fall back to browser-only behavior.
- *
- * It used to test WebView2 alone, which answered FALSE on the MAUI shell: an app would have
- * concluded it was in a plain browser tab while a perfectly good host sat on the other side of the
- * channel. Widened when the second shell arrived — the question this function is asked is "is there
- * a host", never "is it WebView2".
+ * True when running inside ANY Shenora host — a WebView2 desktop shell or a MAUI `HybridWebView` — i.e.
+ * when a transport to the host exists. In a plain browser this is false and callers should fall back to
+ * browser-only behavior. The question is "is there a host", never "is it WebView2".
  */
 export declare function isShenoraAvailable(): boolean;
 /** The WebView2 postMessage transport, or null outside a WebView2 host. */
@@ -25,20 +20,16 @@ export declare function createWebView2Transport(): ShenoraTransport | null;
 /**
  * The MAUI `HybridWebView` transport, or null outside a MAUI host.
  *
- * Asymmetric by the platform's design, which is the only thing interesting here: sending goes
- * through `window.HybridWebView.SendRawMessage`, while receiving is a `HybridWebViewMessageReceived`
- * CustomEvent dispatched on `window`. Both directions carry the same JSON envelopes the desktop
- * shell speaks — the host side is `Shenora.Maui.MauiIpcBridge`, and the envelope itself never
- * changed, which is the whole point of the transport seam (D16).
+ * Asymmetric by the platform's design: sending goes through `window.HybridWebView.SendRawMessage`,
+ * while receiving is a `HybridWebViewMessageReceived` CustomEvent dispatched on `window`. Both
+ * directions carry the same JSON envelopes the desktop shell speaks; the host side is
+ * `Shenora.Maui.MauiIpcBridge`.
  */
 export declare function createHybridWebViewTransport(): ShenoraTransport | null;
 /**
  * The transport for whichever Shenora host this page is running in, or null in a plain browser.
  * This is what the bridge uses by default, so an app that simply calls `invoke`/`post` works on the
- * desktop shell and the MAUI shell without knowing which one it is.
- *
- * WebView2 is probed FIRST for no deeper reason than that it is the older shell and a page can only
- * ever be in one of them; if both objects were somehow present, preferring the one the desktop host
- * injects keeps existing behaviour byte-identical.
+ * desktop shell and the MAUI shell without knowing which one it is. A page is only ever in one of
+ * them; WebView2 wins if both objects are somehow present.
  */
 export declare function createHostTransport(): ShenoraTransport | null;