@shenora/react 0.11.0 → 0.13.0

package/dist/requests.d.ts

@@ -3,11 +3,8 @@ import type { ShenoraEventBus } from './eventBus.js';
 import { type ShenoraStore } from './store.js';
 import type { IpcError } from './types.js';
 /**
- * Mirrors `Shenora.Core.Ipc.IpcRequestState` (design §4.2) — crosses the wire as its camelCase name for
- * free: `IpcJson` already installs a camelCase `JsonStringEnumConverter`, so no per-type wiring is
- * needed on either side. Pinned against the host by
- * `WireMirrorTests.Every_request_state_exists_on_both_sides` — a status added on one side and
- * not the other fails that test by name, not by a green suite that never looked.
+ * Mirrors `Shenora.Core.Ipc.IpcRequestState` (design §4.2), pinned against the host by
+ * `WireMirrorTests.Every_request_state_exists_on_both_sides`.
  */
 export declare const IpcRequestStates: {
     readonly Running: "running";
@@ -18,26 +15,21 @@ export declare const IpcRequestStates: {
 /** One of {@link IpcRequestStates}. */
 export type IpcRequestState = (typeof IpcRequestStates)[keyof typeof IpcRequestStates];
 /**
- * Mirrors `Shenora.Core.Ipc.IpcRequestEvents` — pinned against the host by
- * `WireMirrorTests.Request_event_names_match_the_host` (ALSO IN THIS BATCH, whole-branch review):
- * these were bare string literals with nothing comparing them to the host's own constants, so a host
- * rename left the suite green and the client permanently deaf to the renamed event.
+ * Mirrors `Shenora.Core.Ipc.IpcRequestEvents`, pinned against the host by
+ * `WireMirrorTests.Request_event_names_match_the_host`.
  */
 export declare const IpcRequestEventTypes: {
     readonly Updated: "REQUEST_UPDATED";
     /**
      * One or more request ids left the host with no corresponding `Updated` snapshot — history eviction
      * and `CLEAR_FINISHED`. Payload is `{ requestIds: string[] }`; {@link createRequestsStore} folds it
-     * by deleting those ids. One authoritative event, so a client never has to guess what the host
-     * removed.
+     * by deleting those ids.
      */
     readonly Removed: "REQUEST_REMOVED";
 };
 /**
- * Mirrors the route names `Shenora.Modules.Requests.IpcRequestsModule` switches on (its own
- * `ListType`/`CancelType`/`ClearFinishedType`/`ResumeType` constants) — pinned by
- * `WireMirrorTests.Request_route_names_match_the_hosts_module`, same rationale as
- * {@link IpcRequestEventTypes}.
+ * Mirrors the route names `Shenora.Modules.Requests.IpcRequestsModule` switches on, pinned by
+ * `WireMirrorTests.Request_route_names_match_the_hosts_module`.
  */
 export declare const IpcRequestRoutes: {
     readonly List: "LIST";
@@ -51,7 +43,7 @@ export declare const IpcRequestRoutes: {
 export declare const IpcRequestsModuleName = "SHENORA.REQUESTS";
 /**
  * Mirrors `Shenora.Core.Ipc.IpcLabel` — human-facing text the HOST never renders itself: an
- * untranslated fallback plus an app i18n key and interpolation parameters (headless, D13).
+ * untranslated fallback plus an app i18n key and interpolation parameters.
  */
 export interface IpcLabel {
     text?: string;
@@ -60,13 +52,11 @@ export interface IpcLabel {
 }
 /**
  * Mirrors `Shenora.Core.Ipc.IpcProgress` — how far a tracked operation has gotten, in the APP's own
- * unit, never a kit-assumed percent (generic-library audit, before publish: percent is not the
- * mechanism, it is one way an app happens to measure). `total` is the denominator when one is known;
- * `undefined` means there is NO known total — an absolute count with nothing to divide by (bytes
- * streamed so far off a chunked response, say), never zero. `unit` is app-defined, like `kind`
- * (`'bytes'`, `'files'`, `'percent'`) — the kit never interprets it and ships no percent helper: render
- * a ratio only when `total` is set, e.g. `total ? (value / total) * 100 : undefined` — that division
- * is the consumer's own policy (see the README example).
+ * unit rather than a kit-assumed percent. `unit` is app-defined (`'bytes'`, `'files'`, `'percent'`)
+ * and the kit never interprets it.
+ *
+ * ⚠ `total` undefined means there is NO known total — an absolute count with nothing to divide by,
+ * never zero. Render a ratio only when it is set; the README has the example.
  */
 export interface IpcProgress {
     value: number;
@@ -91,19 +81,11 @@ export interface IpcRequestStatus {
     finishedAt?: string;
 }
 /**
- * State behind {@link useShenoraRequests}. TWO bands, because a request is in flight or done:
- *
- * | Band | Getter |
- * |---|---|
- * | In flight | {@link running} |
- * | Finished | {@link finished} — prunable via `clearFinished` |
- *
- * Every getter is DERIVED from `byId` on each read — never a second copy a fold has to remember to
- * keep in sync. `byId` is the only thing any reducer here writes.
+ * State behind {@link useShenoraRequests}. `byId` is the only thing a reducer writes; the two bands
+ * are derived from it on every read.
  *
  * ⚠ Most requests never appear at all: one that finishes inside the host's grace period is never
- * announced, so this store is a list of work that is actually TAKING A WHILE rather than a log of
- * every call the page made.
+ * announced, so this lists work that is actually TAKING A WHILE, not every call the page made.
  */
 export interface RequestsState {
     byId: Record<string, IpcRequestStatus>;
@@ -118,11 +100,9 @@ export interface RequestsActions {
     cancel: (requestId: string) => string;
     /**
      * `CLEAR_FINISHED { scope? }` — drop retained finished history, forwarding this store's own
-     * configured scope (generic-library audit finding 1) so a scoped store's "clear completed" cannot
-     * wipe another scope's history host-side. No local mutation here: the host's
-     * `REQUEST_REMOVED` (finding 4) is the only thing that removes a row from this store now — see
-     * {@link IpcRequestEventTypes.Removed}. It used to carry an optimistic local prune of every TERMINAL
-     * entry, added because removals had no wire event at all; that guess is retired now that one exists.
+     * configured scope so a scoped store's "clear completed" cannot wipe another scope's history
+     * host-side. Nothing is mutated locally: the host's {@link IpcRequestEventTypes.Removed} is the only
+     * thing that removes a row.
      */
     clearFinished: () => string;
 }
@@ -130,19 +110,17 @@ export interface RequestsActions {
 export interface RequestsStoreOptions {
     /**
      * The request/event module this store talks to. Must match the host's
-     * `IpcRequestTrackerOptions.ModuleName` — default `'SHENORA.REQUESTS'` on both sides — when an app
-     * renamed it to avoid a collision with one of its own module names (the duplicate-module guard
-     * `IpcRequestsModule`'s own docs describe). A store bound to the default name cannot reach a
-     * renamed host at all, which is exactly the gap this field closes.
+     * `IpcRequestTrackerOptions.ModuleName` — default `'SHENORA.REQUESTS'` on both sides — for an app
+     * that renamed it to avoid colliding with one of its own modules.
      */
     module?: string;
     /**
-     * Optional app-defined scope, applied to THREE places so the store stays internally consistent:
-     * the bus subscription (only deltas whose event scope matches are folded), the actions' request
-     * envelope, and the initial `LIST` snapshot's payload (`IpcRequestsModule` reads its scope filter
-     * from the payload, not the envelope — see `IpcRequestsModule.RouteMessageAsync`). Threading it
-     * into only the first two would load every scope on first subscribe and never remove the
-     * out-of-scope rows, since no delta for them ever arrives: a silent, permanent leak.
+     * Optional app-defined scope, applied to THREE places: the bus subscription, the actions' request
+     * envelope, and the initial `LIST` snapshot's PAYLOAD (`IpcRequestsModule` reads its scope filter
+     * from the payload, not the envelope).
+     *
+     * ⚠ All three or none. Threading it into only the first two loads every scope on first subscribe and
+     * then never sheds the out-of-scope rows, since no delta for them ever arrives.
      */
     scope?: string;
     /** Test/multi-transport seams. Default: the shared bridge and event bus. */
@@ -150,27 +128,18 @@ export interface RequestsStoreOptions {
     bus?: ShenoraEventBus;
 }
 /**
- * Build a store instance over the requests module — the factory {@link useShenoraRequests}
- * itself is built from. Exposed (rather than only the ready-made hook) for the same reason
- * `WindowCommands` takes an optional bridge: a test needs a fake bridge/bus
- * (`requests.test.ts`), an app that renamed the host's `IpcRequestTrackerOptions.ModuleName`
- * needs a store bound to that name instead of the unreachable default, and an app running a
- * secondary window or auxiliary session needs its own scope-filtered instance instead of being
- * stuck with the shared, unscoped default.
+ * Build a store instance over the requests module — the factory {@link useShenoraRequests} is built
+ * from. Use it directly for a renamed host module, a scope-filtered instance, or a fake bridge/bus.
  */
 export declare function createRequestsStore(options?: RequestsStoreOptions): ShenoraStore<RequestsState, RequestsActions>;
 /**
  * The client side of the operations primitive (design §4.6, `IpcRequestsModule` +
  * `IIpcRequestTracker`): snapshots via `LIST` on first subscribe, then folds `REQUEST_UPDATED` by
- * id — one subscription however many components read it, and a late mounter renders CURRENT state
- * because the host is authoritative (the store primitive's own late-mounter case is now
- * host-backed end to end). `running`/`finished` are selectors an activity panel or status bar reads
- * directly: `useShenoraRequests((s) => s.running)`. There is no `waiting` band and no `waitReason` —
- * a request is IN FLIGHT or DONE, the same two states `XMLHttpRequest` has, since D66. Bound to the
- * default module/no scope — use {@link createRequestsStore} directly for a renamed module or a
- * scope-filtered instance.
+ * id — one subscription however many components read it, and a late mounter renders CURRENT state.
+ * `running`/`finished` are selectors an activity panel reads directly:
+ * `useShenoraRequests((s) => s.running)`.
  *
- * Headless, per D13: no component, no UI opinion, no `ProcessType`-style enum — what an operation
- * IS stays the app's `kind` string; this only carries the uniform lifecycle around it.
+ * Bound to the default module and no scope — use {@link createRequestsStore} for a renamed module or
+ * a scope-filtered instance.
  */
 export declare const useShenoraRequests: ShenoraStore<RequestsState, RequestsActions>;

package/dist/requests.js

@@ -1,48 +1,35 @@
 import { createShenoraStore } from './store.js';
 /**
- * Mirrors `Shenora.Core.Ipc.IpcRequestState` (design §4.2) — crosses the wire as its camelCase name for
- * free: `IpcJson` already installs a camelCase `JsonStringEnumConverter`, so no per-type wiring is
- * needed on either side. Pinned against the host by
- * `WireMirrorTests.Every_request_state_exists_on_both_sides` — a status added on one side and
- * not the other fails that test by name, not by a green suite that never looked.
+ * Mirrors `Shenora.Core.Ipc.IpcRequestState` (design §4.2), pinned against the host by
+ * `WireMirrorTests.Every_request_state_exists_on_both_sides`.
  */
 export const IpcRequestStates = {
     Running: 'running',
     Completed: 'completed',
     Failed: 'failed',
     Cancelled: 'cancelled',
-    // NO 'waiting'. A request is IN FLIGHT or DONE — the XHR model this mirrors has no parked state,
-    // and neither does the host since D66. Work that parks awaiting a human is host-initiated work
-    // (a queued mission), which reports on its own event stream rather than as a request.
 };
 /**
- * Mirrors `Shenora.Core.Ipc.IpcRequestEvents` — pinned against the host by
- * `WireMirrorTests.Request_event_names_match_the_host` (ALSO IN THIS BATCH, whole-branch review):
- * these were bare string literals with nothing comparing them to the host's own constants, so a host
- * rename left the suite green and the client permanently deaf to the renamed event.
+ * Mirrors `Shenora.Core.Ipc.IpcRequestEvents`, pinned against the host by
+ * `WireMirrorTests.Request_event_names_match_the_host`.
  */
 export const IpcRequestEventTypes = {
     Updated: 'REQUEST_UPDATED',
     /**
      * One or more request ids left the host with no corresponding `Updated` snapshot — history eviction
      * and `CLEAR_FINISHED`. Payload is `{ requestIds: string[] }`; {@link createRequestsStore} folds it
-     * by deleting those ids. One authoritative event, so a client never has to guess what the host
-     * removed.
+     * by deleting those ids.
      */
     Removed: 'REQUEST_REMOVED',
 };
 /**
- * Mirrors the route names `Shenora.Modules.Requests.IpcRequestsModule` switches on (its own
- * `ListType`/`CancelType`/`ClearFinishedType`/`ResumeType` constants) — pinned by
- * `WireMirrorTests.Request_route_names_match_the_hosts_module`, same rationale as
- * {@link IpcRequestEventTypes}.
+ * Mirrors the route names `Shenora.Modules.Requests.IpcRequestsModule` switches on, pinned by
+ * `WireMirrorTests.Request_route_names_match_the_hosts_module`.
  */
 export const IpcRequestRoutes = {
     List: 'LIST',
     Cancel: 'CANCEL',
     ClearFinished: 'CLEAR_FINISHED',
-    // THREE routes — the same three `XMLHttpRequest` offers. RESUME/WAIT/DISMISS went with the waiting
-    // band (D66), and the wire-mirror test pins this object's SIZE so a retired name cannot creep back.
 };
 /**
  * Default `Shenora.Core.Ipc.IpcRequestTrackerOptions.ModuleName` — pinned by
@@ -61,9 +48,7 @@ function index(list) {
         byId[operation.id] = operation;
     return byId;
 }
-/**
- * The one place `running`/`finished` are computed — wrap `byId` here, nowhere else.
- */
+/** The one place `running`/`finished` are computed — wrap `byId` here, nowhere else. */
 function makeState(byId) {
     return {
         byId,
@@ -76,23 +61,16 @@ function makeState(byId) {
     };
 }
 /**
- * Build a store instance over the requests module — the factory {@link useShenoraRequests}
- * itself is built from. Exposed (rather than only the ready-made hook) for the same reason
- * `WindowCommands` takes an optional bridge: a test needs a fake bridge/bus
- * (`requests.test.ts`), an app that renamed the host's `IpcRequestTrackerOptions.ModuleName`
- * needs a store bound to that name instead of the unreachable default, and an app running a
- * secondary window or auxiliary session needs its own scope-filtered instance instead of being
- * stuck with the shared, unscoped default.
+ * Build a store instance over the requests module — the factory {@link useShenoraRequests} is built
+ * from. Use it directly for a renamed host module, a scope-filtered instance, or a fake bridge/bus.
  */
 export function createRequestsStore(options = {}) {
     const module = options.module ?? IpcRequestsModuleName;
     return createShenoraStore(module, {
         initial: makeState({}),
-        // LIST is the snapshot source (design §4.6): a store cannot replay a stream, so a component
-        // that mounts while work is already running gets it from here before folding any deltas.
-        // The payload carries `scope` so the initial load is filtered the SAME way the deltas are
-        // (below, and via createShenoraStore's own `scope` option) — both halves must agree, or a
-        // scoped store loads every scope once and then never sheds the out-of-scope rows.
+        // LIST is the snapshot source (design §4.6): a store cannot replay a stream, so a component that
+        // mounts while work is already running gets it from here before folding any deltas. The payload
+        // carries `scope` so the initial load is filtered the same way the deltas are.
         snapshot: {
             type: IpcRequestRoutes.List,
             payload: options.scope !== undefined ? { scope: options.scope } : undefined,
@@ -102,9 +80,8 @@ export function createRequestsStore(options = {}) {
             // ONE event type for every transition (design §4.3) — last-write-wins by id, so folding needs
             // no ordering logic and no cross-type races.
             [IpcRequestEventTypes.Updated]: (state, payload) => makeState({ ...state.byId, [payload.id]: payload }),
-            // The ONE removal delta (Finding 4, generic-library audit), replacing the two hand-written
-            // optimistic prunes `clearFinished`/`resume` used to carry (see their own docs below) — deletes
-            // exactly the ids the host named, regardless of status; an id this store never had is a no-op.
+            // The ONE removal delta: deletes exactly the ids the host named, regardless of status. An id
+            // this store never had is a no-op.
             [IpcRequestEventTypes.Removed]: (state, payload) => {
                 const byId = { ...state.byId };
                 for (const id of payload.requestIds)
@@ -114,13 +91,7 @@ export function createRequestsStore(options = {}) {
         },
         actions: ({ post }) => ({
             cancel: (requestId) => post(IpcRequestRoutes.Cancel, { payload: { requestId } }),
-            clearFinished: () => 
-            // Forward THIS store's own configured scope (Finding 1, generic-library audit) — the same
-            // key the LIST snapshot payload already carries above. No local mutation here any more
-            // (Finding 4): the host's REQUEST_REMOVED is the ONLY thing that removes a row now, which
-            // is also what makes the scope threading safe to add — nothing here can diverge from what
-            // the host actually cleared.
-            post(IpcRequestRoutes.ClearFinished, {
+            clearFinished: () => post(IpcRequestRoutes.ClearFinished, {
                 payload: options.scope !== undefined ? { scope: options.scope } : undefined,
             }),
         }),
@@ -132,15 +103,11 @@ export function createRequestsStore(options = {}) {
 /**
  * The client side of the operations primitive (design §4.6, `IpcRequestsModule` +
  * `IIpcRequestTracker`): snapshots via `LIST` on first subscribe, then folds `REQUEST_UPDATED` by
- * id — one subscription however many components read it, and a late mounter renders CURRENT state
- * because the host is authoritative (the store primitive's own late-mounter case is now
- * host-backed end to end). `running`/`finished` are selectors an activity panel or status bar reads
- * directly: `useShenoraRequests((s) => s.running)`. There is no `waiting` band and no `waitReason` —
- * a request is IN FLIGHT or DONE, the same two states `XMLHttpRequest` has, since D66. Bound to the
- * default module/no scope — use {@link createRequestsStore} directly for a renamed module or a
- * scope-filtered instance.
+ * id — one subscription however many components read it, and a late mounter renders CURRENT state.
+ * `running`/`finished` are selectors an activity panel reads directly:
+ * `useShenoraRequests((s) => s.running)`.
  *
- * Headless, per D13: no component, no UI opinion, no `ProcessType`-style enum — what an operation
- * IS stays the app's `kind` string; this only carries the uniform lifecycle around it.
+ * Bound to the default module and no scope — use {@link createRequestsStore} for a renamed module or
+ * a scope-filtered instance.
  */
 export const useShenoraRequests = createRequestsStore();

package/dist/segmentBinder.d.ts

@@ -3,24 +3,20 @@ import { type MediaSourceGlobals } from './segmentStream.js';
  * The imperative half of the segment route (D71 piece 4b): open a `SourceBuffer`, feed it, and stop when
  * the platform says stop.
  *
- * 🔴 **Everything here was written against measurements rather than against the specification**, because
- * three implementations disagree in ways the spec permits and none of it is guessable:
+ * 🔴 **Three implementations disagree in ways the spec permits, so none of this is guessable** — the
+ * measurements are in `docs/design/media.md`:
  *
- * - **Attachment is not portable.** iOS takes `srcObject` — a `ManagedMediaSource` is a valid
- *   `MediaSourceHandle` — and Chromium refuses it outright ("not of type '(MediaSourceHandle or
- *   MediaStream)'"), wanting an object URL. Feature-detected, not branched on the shell: which one works
- *   is a property of the MediaSource, not of the OS.
+ * - **Attachment is not portable.** iOS takes `srcObject` (a `ManagedMediaSource` is a valid
+ *   `MediaSourceHandle`); Chromium refuses it and wants an object URL. Feature-detected, not branched on
+ *   the shell: which one works is a property of the MediaSource, not of the OS.
  * - **The codecs are read from the init segment, never assumed.** The track set is a fact about the
  *   DEVICE, not the source: the same file yields a two-track init on iOS and a video-only one on Android,
  *   which cannot decode its AC-3 soundtrack. A mismatch kills the FIRST append and plays nothing.
- * - **The streaming gate is real on iOS and absent elsewhere.** `endstreaming` fires once enough is
- *   buffered (measured: at 60 s, not at 6 s), and fetching past it is the misuse `ManagedMediaSource`
- *   exists to detect. A plain `MediaSource` has neither event nor a `streaming` property, and its absence
- *   means "always streaming" — never "never asked".
+ * - **The streaming gate is real on iOS and absent elsewhere.** Fetching past `endstreaming` is the
+ *   misuse `ManagedMediaSource` exists to detect. A plain `MediaSource` has neither the event nor a
+ *   `streaming` property, and its absence means "always streaming" — never "never asked".
  *
- * ⚠ **The dependencies are INJECTABLE so this is testable without a browser.** jsdom has no MediaSource,
- * and "cannot be verified anywhere this repo runs" was true of the whole file until the seams below
- * existed. A fake source and a fake fetch drive every branch here.
+ * The dependencies below are injectable, so a fake source and a fake fetch drive every branch here.
  */
 export interface SegmentBinderOptions {
     /** The playlist URL. Segment URIs are resolved relative to it. */
@@ -38,11 +34,7 @@ export interface SegmentBinderOptions {
     }>;
     /** Defaults to `URL.createObjectURL`. Only used when `srcObject` is refused. */
     createObjectURL?: (source: object) => string;
-    /**
-     * Defaults to `URL.revokeObjectURL`. The pair to {@link createObjectURL}, and injectable for the same
-     * reason: without it the failure paths that must revoke — a source that closes before opening, a
-     * codec the device refuses — cannot be asserted, only hoped for.
-     */
+    /** Defaults to `URL.revokeObjectURL`. The pair to {@link createObjectURL}. */
     revokeObjectURL?: (url: string) => void;
     /** Stop fetching once this many seconds are buffered ahead. Defaults to 30. */
     targetAheadSeconds?: number;
@@ -65,9 +57,8 @@ export interface SegmentBinding {
 /**
  * Thrown for every reason a stream cannot start, so a caller has one thing to catch.
  *
- * ⚠ **Not literally every reason** — a `TypeError` from the manifest fetch failing at the network layer,
- * and a `RangeError` from a truncated init segment, both propagate as themselves. Catch broadly if you
- * need to be exhaustive.
+ * ⚠ **Not literally every reason** — a `TypeError` from the manifest fetch and a `RangeError` from a
+ * truncated init segment propagate as themselves. Catch broadly if you need to be exhaustive.
  */
 export declare class SegmentBinderError extends Error {
     constructor(message: string);
@@ -78,10 +69,6 @@ export declare class SegmentBinderError extends Error {
  * Resolves once the init segment has been appended — the point after which the element can play — and
  * goes on fetching in the background until every segment is in or {@link SegmentBinding.dispose} is called.
  *
- * ⚠ **There is deliberately NO `useSegmentStream` hook.** This needs no React — it takes an element and
- * returns a handle, exactly as `mediaUrl` takes a path and returns a string — so a hook would add a
- * lifecycle without adding a capability. The case that would earn one is an app wanting load/error
- * state as component state, and the shape of that hook depends on what such an app actually asks for;
- * inventing it first is how a seam nothing consults gets built (D63). Call this from an effect.
+ * There is no `useSegmentStream` hook: this needs no React, so call it from an effect.
  */
 export declare function bindSegmentStream(options: SegmentBinderOptions): Promise<SegmentBinding>;

package/dist/segmentBinder.js

@@ -1,19 +1,15 @@
 import { codecsFromInitSegment, nextSegment, parseManifest, pickMediaSource, segmentMimeType, } from './segmentStream.js';
 /**
- * How long to wait for the attached MediaSource to reach `open`.
- *
- * Attachment is local and immediate — there is no network in it — so this is a deadline for "something
- * is wrong", not a budget. It exists because the alternative to a deadline here is an await that never
- * returns: the element can refuse or tear down an attachment without ever raising an event this side
- * can name.
+ * How long to wait for the attached MediaSource to reach `open`. Attachment is local and immediate, so
+ * this is a deadline for "something is wrong": the element can refuse or tear down an attachment
+ * without raising any event this side can name, and the await would never return.
  */
 const ATTACH_TIMEOUT_MS = 10000;
 /**
  * Thrown for every reason a stream cannot start, so a caller has one thing to catch.
  *
- * ⚠ **Not literally every reason** — a `TypeError` from the manifest fetch failing at the network layer,
- * and a `RangeError` from a truncated init segment, both propagate as themselves. Catch broadly if you
- * need to be exhaustive.
+ * ⚠ **Not literally every reason** — a `TypeError` from the manifest fetch and a `RangeError` from a
+ * truncated init segment propagate as themselves. Catch broadly if you need to be exhaustive.
  */
 export class SegmentBinderError extends Error {
     constructor(message) {
@@ -42,27 +38,17 @@ function bufferedAhead(element) {
  * Resolves once the init segment has been appended — the point after which the element can play — and
  * goes on fetching in the background until every segment is in or {@link SegmentBinding.dispose} is called.
  *
- * ⚠ **There is deliberately NO `useSegmentStream` hook.** This needs no React — it takes an element and
- * returns a handle, exactly as `mediaUrl` takes a path and returns a string — so a hook would add a
- * lifecycle without adding a capability. The case that would earn one is an app wanting load/error
- * state as component state, and the shape of that hook depends on what such an app actually asks for;
- * inventing it first is how a seam nothing consults gets built (D63). Call this from an effect.
+ * There is no `useSegmentStream` hook: this needs no React, so call it from an effect.
  */
 export async function bindSegmentStream(options) {
     const { manifest: manifestUrl, element, globals = globalThis, targetAheadSeconds = 30, onDiagnostic, } = options;
     const doFetch = options.fetch ?? ((url) => fetch(url));
     const say = (line) => onDiagnostic?.(line);
     /**
-     * A FAILURE, as opposed to a trace line.
-     *
-     * 🔴 **`onDiagnostic` is optional, so failures used to go nowhere by default.** A segment answering 500
-     * or an `appendBuffer` `QuotaExceededError` produced no console output, no rejection and no state
-     * change — playback simply stalled, with nothing anywhere to explain it. Every other error path in this
-     * package already defaults to `console.error` (`bridge.ts`'s `onPostError`, `store.ts`'s `onError`,
-     * `eventBus.ts`); this one was the exception.
-     *
-     * ⚠ Only when the app supplied NO handler. A caller that took `onDiagnostic` owns its reporting and
-     * must not be double-logged — the same rule the two sinks above follow.
+     * A FAILURE, as opposed to a trace line: reported to `console.error` when the app supplied no
+     * `onDiagnostic`, so a segment answering 500 or an `appendBuffer` `QuotaExceededError` cannot stall
+     * playback with nothing anywhere to explain it. A caller that took `onDiagnostic` owns its reporting
+     * and is not double-logged.
      */
     const fail = (line) => (onDiagnostic ? onDiagnostic(line) : console.error(`[shenora] ${line}`));
     const kind = pickMediaSource(globals);
@@ -105,19 +91,18 @@ export async function bindSegmentStream(options) {
         element.src = objectUrl;
     }
     // ⚠ The object URL is minted BEFORE anything below can fail, so EVERY failure between the mint and
-    // the returned binding has to revoke it itself — bindSegmentStream has not returned, so the caller
-    // holds no binding to dispose, and the document keeps the MediaSource alive for its lifetime. That
-    // is three places, not one: the open wait, addSourceBuffer, and the init append.
+    // the returned binding must revoke it itself — the caller holds no binding to dispose yet, and the
+    // document keeps the MediaSource alive for its lifetime. Three places: the open wait,
+    // addSourceBuffer, and the init append.
     const revokeAndRethrow = (e) => {
         if (objectUrl)
             revoke(objectUrl);
         throw e;
     };
-    // 🔴 `error` IS NOT A MediaSource EVENT. The spec fires `sourceopen`, `sourceended` and
-    // `sourceclose`, so the only rejection path here could never fire — and an attachment that CLOSES
-    // rather than opening (the element detached from the document before load, an attachment refused)
-    // left this await pending FOREVER: no error, no diagnostic, no way to reach dispose(), and the object
-    // URL never revoked. `sourceclose` is the real signal, and the deadline covers whatever is neither.
+    // 🔴 `error` IS NOT A MediaSource EVENT — the spec fires `sourceopen`, `sourceended` and
+    // `sourceclose`. An attachment that CLOSES rather than opening (the element detached before load, an
+    // attachment refused) leaves this await pending FOREVER on any other listener: no error, no
+    // diagnostic, no way to reach dispose(). The deadline covers whatever is neither.
     await new Promise((res, rej) => {
         if (source.readyState === 'open')
             return res();
@@ -135,8 +120,7 @@ export async function bindSegmentStream(options) {
     }).catch(revokeAndRethrow);
     let buffer;
     try {
-        // Throws synchronously for a codecs string this implementation refuses — a real case, per the
-        // remarks on codec derivation above.
+        // Throws synchronously for a codecs string this implementation refuses.
         buffer = source.addSourceBuffer(mime);
     }
     catch (e) {
@@ -152,9 +136,8 @@ export async function bindSegmentStream(options) {
      * Append one buffer and settle when the source buffer says so.
      *
      * 🔴 **Both listeners come off on EITHER outcome.** `{ once: true }` removes only the listener that
-     * FIRES, and the success path fires `updateend` — so the `error` listener stayed attached, once per
-     * appended segment, each retaining a settled `rej` closure. A two-hour stream at six-second segments
-     * accumulates ~1,200 dead listeners on one `SourceBuffer`, none of which `dispose()` could shed, and a
+     * FIRES, and the success path fires `updateend` — so with it the `error` listener stays attached once
+     * per appended segment, each retaining a settled `rej` closure that `dispose()` cannot shed, and one
      * later real `error` invokes every one of them.
      */
     const append = (bytes) => new Promise((res, rej) => {
@@ -182,10 +165,37 @@ export async function bindSegmentStream(options) {
     /**
      * Fetch and append whatever {@link nextSegment} asks for, one at a time.
      *
-     * ⚠ Re-entrancy is guarded rather than queued: this is driven by element events that fire far faster
-     * than an append completes, and two concurrent `appendBuffer` calls on one SourceBuffer throw
-     * `InvalidStateError` — which surfaces as a stall with no obvious cause.
+     * ⚠ Re-entrancy is guarded rather than queued: element events fire far faster than an append
+     * completes, and two concurrent `appendBuffer` calls on one SourceBuffer throw `InvalidStateError`,
+     * which surfaces as a stall with no obvious cause.
      */
+    /** Consecutive 503s, so a source that is slow to produce backs off instead of hammering. */
+    let waits = 0;
+    let waitTimer = null;
+    /**
+     * Come back for a segment the host has not finished producing.
+     *
+     * ⚠ Bounded, and it says so when it gives up: a wait that retries for ever is the same permanent
+     * spinner by a slower route. The cap is generous because the host's own 503 already means it is
+     * working — this is not a failure budget, it is a politeness one.
+     */
+    const retryLater = (uri) => {
+        if (disposed)
+            return;
+        if (++waits > 40) {
+            fail(`segments: ${uri} still answering 503 after ${waits} attempts — giving up`);
+            return;
+        }
+        const delay = Math.min(2000, 100 * waits);
+        say(`segments: ${uri} not ready (503) — retrying in ${delay}ms`);
+        if (waitTimer !== null)
+            clearTimeout(waitTimer);
+        waitTimer = setTimeout(() => {
+            waitTimer = null;
+            if (!disposed)
+                void pump();
+        }, delay);
+    };
     const pump = async () => {
         if (pumping || disposed)
             return;
@@ -201,12 +211,20 @@ export async function bindSegmentStream(options) {
                 const response = await doFetch(resolve(manifestUrl, entry.uri));
                 if (disposed)
                     return;
+                if (response.status === 503) {
+                    // 🔴 503 IS THE HOST SAYING "still producing" — a WAIT, and it must actually be waited FOR.
+                    // This used to say exactly that in a comment and then `fail()` and break, with nothing
+                    // scheduled to resume: a permanent spinner, on the one path the segment route uses to mean
+                    // "ask again". The producing side waits its own budget before answering, so both halves said
+                    // "wait" and neither came back.
+                    retryLater(entry.uri);
+                    break;
+                }
                 if (!response.ok) {
-                    // 503 is the host saying "still producing", which is a WAIT and not a failure — the route
-                    // answers it deliberately rather than 404ing a source that is merely not ready.
                     fail(`segments: ${entry.uri} answered ${response.status}`);
                     break;
                 }
+                waits = 0; // progress: the next stall starts its backoff from the bottom again
                 await append(new Uint8Array(await response.arrayBuffer()));
                 appended.add(index);
                 if (disposed)
@@ -244,6 +262,11 @@ export async function bindSegmentStream(options) {
             if (disposed)
                 return;
             disposed = true;
+            // The 503 retry must not outlive the binding — it would re-enter a pump over a torn-down source.
+            if (waitTimer !== null) {
+                clearTimeout(waitTimer);
+                waitTimer = null;
+            }
             source.removeEventListener('startstreaming', onStart);
             source.removeEventListener('endstreaming', onEnd);
             element.removeEventListener('timeupdate', wake);