@shenora/react 0.11.0 → 0.13.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`.
  *
- * ⚠ **"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 const SEGMENT_REMOTE_PREFIX = '~remote/';
 /**
- * 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.
+ * The manifest url for a handle the app handed this page.
  *
- * ⚠ 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.
+ * ⚠ 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's `SegmentStream` emits — not a general playlist parser.
+ *
+ * ⚠ 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.
- *
- * ✅ **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 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');
@@ -176,11 +168,52 @@ export function codecsFromInitSegment(init) {
             at += size;
         }
     };
+    /**
+     * An ISO 14496-1 "expandable" descriptor length: 1–4 bytes, each with the high bit meaning "continue".
+     * Returns the value and the offset just past it.
+     */
+    const expandable = (at) => {
+        let value = 0;
+        let p = at;
+        for (let i = 0; i < 4; i++) {
+            const b = u8(p++);
+            value = (value << 7) | (b & 0x7f);
+            if ((b & 0x80) === 0)
+                break;
+        }
+        return [value, p];
+    };
+    /**
+     * The AAC audio object type declared inside an `esds`, or null when it cannot be read.
+     *
+     * Tolerant by design: it finds the DecoderConfigDescriptor rather than parsing the ES_Descriptor's
+     * optional fields, then steps its FIXED 13 bytes to the nested DecoderSpecificInfo, whose first 5 bits
+     * are the object type (2 = AAC-LC, 5 = HE-AAC, 29 = HE-AACv2, 42 = xHE-AAC).
+     */
+    const audioObjectType = (from, to) => {
+        for (let p = from; p + 2 < to; p++) {
+            if (u8(p) !== 0x04)
+                continue; // DecoderConfigDescriptor
+            const [, afterLength] = expandable(p + 1);
+            if (afterLength >= to || u8(afterLength) !== 0x40)
+                continue; // MPEG-4 Audio, or not ours
+            // objectTypeIndication(1) streamType(1) bufferSizeDB(3) maxBitrate(4) avgBitrate(4)
+            const nested = afterLength + 13;
+            if (nested + 1 >= to || u8(nested) !== 0x05)
+                continue; // DecoderSpecificInfo
+            const [, config] = expandable(nested + 1);
+            if (config >= to)
+                continue;
+            const aot = u8(config) >> 3;
+            // 31 is the escape for an extended type; not worth decoding for a codec string, and 0 is invalid.
+            return aot === 0 || aot === 31 ? null : aot;
+        }
+        return null;
+    };
     /** 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 = '';
@@ -205,17 +238,16 @@ export function codecsFromInitSegment(init) {
                 derived = `${format}.${spaces}${idc}.${(reversed >>> 0).toString(16).toUpperCase()}.` +
                     `${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.
-                for (let p = s; p + 2 < end; p++) {
-                    if (u8(p) === 0x04 && u8(p + 2) === 0x40) {
-                        derived = `mp4a.40.${u8(p + 3) || 2}`;
-                        break;
-                    }
-                }
-                if (!derived)
-                    derived = 'mp4a.40.2';
+            else if (type === 'esds' && s + 8 <= end) {
+                // 🔴 THE AUDIO OBJECT TYPE LIVES IN THE DecoderSpecificInfo, not beside objectTypeIndication.
+                // This used to read the byte straight after the `0x40`, which is the STREAM TYPE — for audio
+                // that is `(5 << 2) | 1` = 0x15, so every short-form esds produced `mp4a.40.21`,
+                // `addSourceBuffer` threw, and nothing played. It also assumed a ONE-byte descriptor length; the
+                // length is "expandable" (up to 4 bytes, high bit continues). The kit's own muxer always writes
+                // the 4-byte form, so the old scan never matched OUR files and the fallback hid it — the bug was
+                // reachable only from a foreign muxer, which is exactly what this parser is for.
+                const aot = audioObjectType(s, end);
+                derived = `mp4a.40.${aot ?? 2}`;
             }
         });
         if (derived)

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', {