@shenora/react 0.10.0 → 0.12.0

package/dist/segmentStream.d.ts

@@ -0,0 +1,125 @@
+/**
+ * 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 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 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`. */
+    uri: string;
+    /** What the playlist declares this segment lasts, in seconds. */
+    seconds: number;
+}
+/** What a playlist says, reduced to the three things a binder acts on. */
+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 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`. */
+    targetSeconds: number;
+    segments: SegmentEntry[];
+}
+/**
+ * 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 declare function parseManifest(text: string): SegmentManifest;
+/** Which MediaSource implementation this browser has, if any. */
+export type MediaSourceKind = 'managed' | 'standard' | 'none';
+/** A window-shaped object, so the pick is testable without a browser. */
+export interface MediaSourceGlobals {
+    MediaSource?: unknown;
+    ManagedMediaSource?: unknown;
+}
+/**
+ * Which MediaSource to use — **`ManagedMediaSource` first where it exists**.
+ *
+ * 🔴 **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 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. */
+export interface FetchState {
+    /** Where playback is, in seconds. */
+    currentTime: number;
+    /** How many seconds are already buffered AHEAD of `currentTime`. */
+    bufferedAhead: number;
+    /** Indices already appended, so a seek back into them costs nothing. */
+    appended: ReadonlySet<number>;
+    /** False while a managed source has told us to stop — see {@link pickMediaSource}. */
+    streaming: boolean;
+}
+/** How far ahead to keep the buffer, and how much of the playlist there is. */
+export interface FetchPolicy {
+    segments: readonly SegmentEntry[];
+    /** Stop fetching once this many seconds are buffered ahead. */
+    targetAheadSeconds: number;
+}
+/**
+ * The next segment index to fetch, or null for "nothing right now".
+ *
+ * 🔴 **Every branch is a decision whose failure is SILENT in a browser:**
+ *
+ * - **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 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 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;
+/**
+ * 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 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
+ *   should treat that as "do not open a SourceBuffer", not as "use the default".
+ */
+export declare function codecsFromInitSegment(init: Uint8Array): string | null;

package/dist/segmentStream.js

@@ -0,0 +1,239 @@
+/**
+ * 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 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 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 = [];
+    let initUri = null;
+    let targetSeconds = 0;
+    let pending = null;
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (line.length === 0)
+            continue;
+        if (line.startsWith('#EXT-X-MAP:')) {
+            // URI="init.mp4" — quoted per the spec, and the quotes are not optional there.
+            initUri = /URI="([^"]*)"/.exec(line)?.[1] ?? null;
+            continue;
+        }
+        if (line.startsWith('#EXT-X-TARGETDURATION:')) {
+            targetSeconds = Number(line.slice('#EXT-X-TARGETDURATION:'.length)) || 0;
+            continue;
+        }
+        if (line.startsWith('#EXTINF:')) {
+            // `#EXTINF:6.000,` — the trailing comma introduces an optional title.
+            pending = Number(line.slice('#EXTINF:'.length).split(',')[0]) || 0;
+            continue;
+        }
+        if (line.startsWith('#'))
+            continue;
+        // A bare line is a URI, and it belongs to the EXTINF above it.
+        segments.push({ uri: line, seconds: pending ?? 0 });
+        pending = null;
+    }
+    return { initUri, targetSeconds, segments };
+}
+/**
+ * Which MediaSource to use — **`ManagedMediaSource` first where it exists**.
+ *
+ * 🔴 **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 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')
+        return 'managed';
+    if (typeof globals.MediaSource === 'function')
+        return 'standard';
+    return 'none';
+}
+/**
+ * The next segment index to fetch, or null for "nothing right now".
+ *
+ * 🔴 **Every branch is a decision whose failure is SILENT in a browser:**
+ *
+ * - **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)
+        return null;
+    if (state.bufferedAhead >= policy.targetAheadSeconds)
+        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.
+    let at = 0;
+    let index = 0;
+    for (; index < policy.segments.length; index++) {
+        const end = at + policy.segments[index].seconds;
+        if (state.currentTime < end)
+            break;
+        at = end;
+    }
+    for (let i = Math.min(index, policy.segments.length - 1); i < policy.segments.length; i++) {
+        if (!state.appended.has(i))
+            return i;
+    }
+    return null;
+}
+/**
+ * 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 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') {
+    return `video/mp4; codecs="${codecs}"`;
+}
+/**
+ * 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 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
+ *   should treat that as "do not open a SourceBuffer", not as "use the default".
+ */
+export function codecsFromInitSegment(init) {
+    const view = new DataView(init.buffer, init.byteOffset, init.byteLength);
+    const codecs = [];
+    /** 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');
+    /** Walk the direct children of [start, end), calling `visit` with (type, contentStart, contentEnd). */
+    const children = (start, end, visit) => {
+        let at = start;
+        while (at + 8 <= end) {
+            let size = view.getUint32(at);
+            let header = 8;
+            if (size === 1) {
+                if (at + 16 > end)
+                    return;
+                size = Number(view.getBigUint64(at + 8));
+                header = 16;
+            }
+            if (size === 0)
+                size = end - at;
+            if (size < header || at + size > end)
+                return;
+            visit(fourcc(at + 4), at + header, at + size);
+            at += size;
+        }
+    };
+    /** The `avcC`/`hvcC`/`esds` inside a sample entry, whose own fields come first. */
+    const configuration = (format, start, end) => {
+        // 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 = '';
+        children(at, end, (type, s) => {
+            if ((type === 'avcC') && s + 4 <= end) {
+                // configurationVersion, AVCProfileIndication, profile_compatibility, AVCLevelIndication
+                derived = `${format}.${hex2(u8(s + 1))}${hex2(u8(s + 2))}${hex2(u8(s + 3))}`;
+            }
+            else if (type === 'hvcC' && s + 13 <= end) {
+                // ISO 14496-15 §8.3.3: profile_space/tier/idc, then 4 compatibility bytes, 6 constraint bytes,
+                // then the level. Rendered in the form Chromium and Safari both accept.
+                const space = (u8(s + 1) >> 6) & 0x3;
+                const tier = (u8(s + 1) >> 5) & 0x1;
+                const idc = u8(s + 1) & 0x1f;
+                const compat = view.getUint32(s + 2);
+                const level = u8(s + 12);
+                const spaces = ['', 'A', 'B', 'C'][space];
+                // The compatibility flags travel REVERSED, as a bit string, per the spec's C.1.
+                let reversed = 0;
+                for (let bit = 0; bit < 32; bit++)
+                    reversed |= ((compat >>> bit) & 1) << (31 - bit);
+                derived = `${format}.${spaces}${idc}.${(reversed >>> 0).toString(16).toUpperCase()}.` +
+                    `${tier ? 'H' : 'L'}${level}`;
+            }
+            else if (type === 'esds' && s + 21 <= end) {
+                // 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}`;
+                        break;
+                    }
+                }
+                if (!derived)
+                    derived = 'mp4a.40.2';
+            }
+        });
+        if (derived)
+            return derived;
+        // No configuration to read: name the FAMILY, which is what an implementation actually checks.
+        return format === 'mp4a' ? 'mp4a.40.2' : format;
+    };
+    const stsd = (start, end) => {
+        // FullBox header (4) + entry_count (4), then the entries.
+        let at = start + 8;
+        while (at + 8 <= end) {
+            const size = view.getUint32(at);
+            if (size < 8 || at + size > end)
+                return;
+            codecs.push(configuration(fourcc(at + 4), at + 8, at + size));
+            at += size;
+        }
+    };
+    const descend = (start, end) => {
+        children(start, end, (type, s, e) => {
+            if (type === 'stsd')
+                stsd(s, e);
+            else if (type === 'moov' || type === 'trak' || type === 'mdia' || type === 'minf' || type === 'stbl') {
+                descend(s, e);
+            }
+        });
+    };
+    descend(0, init.byteLength);
+    return codecs.length > 0 ? codecs.join(',') : null;
+}

package/dist/store.d.ts

@@ -13,12 +13,13 @@ export interface ShenoraStoreIo<TState = unknown> {
     /** 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.
+     * Apply a local state change with NO host round trip and NO wire event — an optimistic update an
+     * 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.** 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;
 }
@@ -37,9 +38,9 @@ export interface ShenoraStoreOptions<TState, TActions> {
     /**
      * 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. */
@@ -72,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

@@ -2,28 +2,41 @@ import { useCallback, useDebugValue, useRef, useSyncExternalStore } from 'react'
 import { getBridge } from './bridge.js';
 import { eventBus as defaultEventBus } from './eventBus.js';
 /**
- * A store fed by one module's host event stream, shared by every component that reads it.
+ * Is the fresh selector result the same VALUE as the previous one, for re-render purposes?
  *
- * 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.
+ * `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 it every call would look like a change and loop.
+ */
+function equivalent(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
+        return false;
+    // Arrays and plain objects only — anything exotic (Map, Date, a class) falls back to identity above.
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    return aKeys.every((k) => Object.prototype.hasOwnProperty.call(b, k)
+        && Object.is(a[k], b[k]));
+}
+/**
+ * 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', {
@@ -46,6 +59,10 @@ export function createShenoraStore(module, options) {
         ?? ((error, context) => console.error(`[shenora] store ${context.module}.${context.type} failed:`, error));
     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 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 = [];
     const bridge = () => options.bridge ?? getBridge();
@@ -65,19 +82,21 @@ 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.Core.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 })
             .then((data) => {
+            if (epoch !== snapshotEpoch)
+                return; // a previous epoch's answer — the live one owns state
             try {
                 setState(snapshot.apply(state, data));
             }
@@ -85,8 +104,10 @@ export function createShenoraStore(module, options) {
                 report(error, { module, type: snapshot.type });
             }
         }, (error) => {
-            // 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.
+            if (epoch !== snapshotEpoch)
+                return;
+            // 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 });
         });
@@ -99,10 +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 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);
@@ -119,23 +145,30 @@ export function createShenoraStore(module, options) {
         getState,
         setState: (reduce) => setState(reduce(getState())),
     };
+    /**
+     * Subscribe to the store, optionally through a selector.
+     *
+     * 🔴 **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) {
-        // getSnapshot must return a STABLE value for an unchanged store, or React throws
-        // "The result of getSnapshot should be cached" and can loop. So the selector result is memoized
-        // against the state identity: recomputed only when state actually changed.
-        const cache = useRef(null);
-        const selectorRef = useRef(selector);
-        selectorRef.current = selector;
+        // 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(() => {
             const current = getState();
-            const select = selectorRef.current;
-            if (!select)
+            if (!selector)
                 return current;
-            if (cache.current === null || !Object.is(cache.current.state, current)) {
-                cache.current = { state: current, selected: select(current) };
+            const next = selector(current);
+            if (previous.current !== null && equivalent(previous.current.value, next)) {
+                return previous.current.value;
             }
-            return cache.current.selected;
-        }, []);
+            previous.current = { value: next };
+            return next;
+        }, [selector]);
         const value = useSyncExternalStore(subscribe, getSelected, getSelected);
         useDebugValue(value);
         return value;

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;