@shenora/react 0.10.0 → 0.12.0

package/dist/requests.d.ts

@@ -0,0 +1,145 @@
+import type { ShenoraBridge } from './bridge.js';
+import type { ShenoraEventBus } from './eventBus.js';
+import { type ShenoraStore } from './store.js';
+import type { IpcError } from './types.js';
+/**
+ * Mirrors `Shenora.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";
+    readonly Completed: "completed";
+    readonly Failed: "failed";
+    readonly Cancelled: "cancelled";
+};
+/** 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`.
+ */
+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.
+     */
+    readonly Removed: "REQUEST_REMOVED";
+};
+/**
+ * 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";
+    readonly Cancel: "CANCEL";
+    readonly ClearFinished: "CLEAR_FINISHED";
+};
+/**
+ * Default `Shenora.Core.Ipc.IpcRequestTrackerOptions.ModuleName` — pinned by
+ * `WireMirrorTests.The_default_requests_module_name_matches_the_host`.
+ */
+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.
+ */
+export interface IpcLabel {
+    text?: string;
+    key?: string;
+    parameters?: Record<string, string>;
+}
+/**
+ * Mirrors `Shenora.Core.Ipc.IpcProgress` — how far a tracked operation has gotten, in the APP's own
+ * 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;
+    total?: number;
+    unit?: string;
+}
+/**
+ * Mirrors `Shenora.Core.Ipc.IpcRequestStatus` — a full snapshot of one tracked operation. Every lifecycle
+ * transition (start, progress, terminal) publishes one of these under `REQUEST_UPDATED`, so the
+ * client folds by `id`: last write wins, with no cross-type ordering hazard.
+ */
+export interface IpcRequestStatus {
+    id: string;
+    module: string;
+    type: string;
+    scope?: string;
+    state: IpcRequestState;
+    progress?: IpcProgress;
+    detail?: IpcLabel;
+    error?: IpcError;
+    startedAt: string;
+    finishedAt?: string;
+}
+/**
+ * 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 lists work that is actually TAKING A WHILE, not every call the page made.
+ */
+export interface RequestsState {
+    byId: Record<string, IpcRequestStatus>;
+    /** Every currently-running operation, in `byId` order. */
+    readonly running: IpcRequestStatus[];
+    /** Every operation that reached a terminal status (completed/failed/cancelled). */
+    readonly finished: IpcRequestStatus[];
+}
+/** Fire-and-forget actions exposed on {@link useShenoraRequests}, routed to `IpcRequestsModule`. */
+export interface RequestsActions {
+    /** `CANCEL { requestId }` — the app-level cancel route `ipc-contracts` prescribes. */
+    cancel: (requestId: string) => string;
+    /**
+     * `CLEAR_FINISHED { scope? }` — drop retained finished history, forwarding this store's own
+     * 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;
+}
+/** Test/alternate-transport seams, a renamed host module, and an optional scope filter, for {@link createRequestsStore}. */
+export interface RequestsStoreOptions {
+    /**
+     * The request/event module this store talks to. Must match the host's
+     * `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: 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. */
+    bridge?: ShenoraBridge;
+    bus?: ShenoraEventBus;
+}
+/**
+ * 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.
+ * `running`/`finished` are selectors an activity panel reads directly:
+ * `useShenoraRequests((s) => s.running)`.
+ *
+ * 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

@@ -0,0 +1,113 @@
+import { createShenoraStore } from './store.js';
+/**
+ * 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',
+};
+/**
+ * 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.
+     */
+    Removed: 'REQUEST_REMOVED',
+};
+/**
+ * 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',
+};
+/**
+ * Default `Shenora.Core.Ipc.IpcRequestTrackerOptions.ModuleName` — pinned by
+ * `WireMirrorTests.The_default_requests_module_name_matches_the_host`.
+ */
+export const IpcRequestsModuleName = 'SHENORA.REQUESTS';
+/** The terminal states — everything that is not in flight. */
+const TERMINAL_STATES = new Set([
+    IpcRequestStates.Completed,
+    IpcRequestStates.Failed,
+    IpcRequestStates.Cancelled,
+]);
+function index(list) {
+    const byId = {};
+    for (const operation of list)
+        byId[operation.id] = operation;
+    return byId;
+}
+/** The one place `running`/`finished` are computed — wrap `byId` here, nowhere else. */
+function makeState(byId) {
+    return {
+        byId,
+        get running() {
+            return Object.values(byId).filter((request) => request.state === IpcRequestStates.Running);
+        },
+        get finished() {
+            return Object.values(byId).filter((request) => TERMINAL_STATES.has(request.state));
+        },
+    };
+}
+/**
+ * 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.
+        snapshot: {
+            type: IpcRequestRoutes.List,
+            payload: options.scope !== undefined ? { scope: options.scope } : undefined,
+            apply: (_state, data) => makeState(index(data)),
+        },
+        on: {
+            // ONE event type for every transition (design §4.3) — last-write-wins by id, so folding needs
+            // no ordering logic and no cross-type races.
+            [IpcRequestEventTypes.Updated]: (state, payload) => makeState({ ...state.byId, [payload.id]: payload }),
+            // 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)
+                    delete byId[id];
+                return makeState(byId);
+            },
+        },
+        actions: ({ post }) => ({
+            cancel: (requestId) => post(IpcRequestRoutes.Cancel, { payload: { requestId } }),
+            clearFinished: () => post(IpcRequestRoutes.ClearFinished, {
+                payload: options.scope !== undefined ? { scope: options.scope } : undefined,
+            }),
+        }),
+        scope: options.scope,
+        bridge: options.bridge,
+        bus: options.bus,
+    });
+}
+/**
+ * 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.
+ * `running`/`finished` are selectors an activity panel reads directly:
+ * `useShenoraRequests((s) => s.running)`.
+ *
+ * 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

@@ -0,0 +1,74 @@
+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.
+ *
+ * 🔴 **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`); 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.** 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 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. */
+    manifest: string;
+    /** The element to play into. Only the members this binder touches are required. */
+    element: HTMLMediaElement;
+    /** Where to look for a MediaSource. Defaults to `globalThis`. */
+    globals?: MediaSourceGlobals;
+    /** Defaults to `globalThis.fetch`. */
+    fetch?: (url: string) => Promise<{
+        ok: boolean;
+        status: number;
+        arrayBuffer(): Promise<ArrayBuffer>;
+        text(): Promise<string>;
+    }>;
+    /** Defaults to `URL.createObjectURL`. Only used when `srcObject` is refused. */
+    createObjectURL?: (source: object) => string;
+    /** 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;
+    /** Diagnostics. Every decision that could stall playback reports through here. */
+    onDiagnostic?: (line: string) => void;
+}
+/** A live binding. Dispose it when the element goes away — it detaches every listener it added. */
+export interface SegmentBinding {
+    /** Indices appended so far. */
+    readonly appended: ReadonlySet<number>;
+    /** False while a managed source has said stop. Always true where the platform has no such signal. */
+    readonly streaming: boolean;
+    /** Which attachment this implementation accepted — the difference between the two shells. */
+    readonly attachedBy: 'srcObject' | 'objectURL';
+    /** What the SourceBuffer was opened with, read from the init segment. */
+    readonly codecs: string;
+    /** Detach listeners and release the object URL, if one was minted. */
+    dispose(): void;
+}
+/**
+ * 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 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);
+}
+/**
+ * Open a MediaSource for `options.manifest` and keep it fed.
+ *
+ * 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 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

@@ -0,0 +1,239 @@
+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, 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 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) {
+        super(message);
+        this.name = 'SegmentBinderError';
+    }
+}
+/** Join a segment URI to the manifest's own location. */
+function resolve(manifestUrl, uri) {
+    const slash = manifestUrl.lastIndexOf('/');
+    return slash < 0 ? uri : manifestUrl.slice(0, slash + 1) + uri;
+}
+/** Seconds already buffered ahead of `currentTime`, across whichever range holds it. */
+function bufferedAhead(element) {
+    const ranges = element.buffered;
+    for (let i = 0; i < ranges.length; i++) {
+        if (element.currentTime >= ranges.start(i) - 0.1 && element.currentTime <= ranges.end(i)) {
+            return ranges.end(i) - element.currentTime;
+        }
+    }
+    return 0;
+}
+/**
+ * Open a MediaSource for `options.manifest` and keep it fed.
+ *
+ * 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 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: 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);
+    if (kind === 'none')
+        throw new SegmentBinderError('this browser has no MediaSource of either kind');
+    const Source = (kind === 'managed' ? globals.ManagedMediaSource : globals.MediaSource);
+    // ── the manifest, and the init segment it names ──────────────────────────────────────────────────
+    const playlist = await doFetch(manifestUrl);
+    if (!playlist.ok)
+        throw new SegmentBinderError(`the manifest answered ${playlist.status}`);
+    const parsed = parseManifest(await playlist.text());
+    if (!parsed.initUri) {
+        // A fragment repeats no decoder configuration, so appending one without this decodes nothing.
+        throw new SegmentBinderError('the playlist declares no #EXT-X-MAP, which is not playable');
+    }
+    if (parsed.segments.length === 0)
+        throw new SegmentBinderError('the playlist declares no segments');
+    const initResponse = await doFetch(resolve(manifestUrl, parsed.initUri));
+    if (!initResponse.ok)
+        throw new SegmentBinderError(`the init segment answered ${initResponse.status}`);
+    const init = new Uint8Array(await initResponse.arrayBuffer());
+    // 🔴 The TRACK SET, from the bytes rather than from a constant — see the module remarks.
+    const codecs = codecsFromInitSegment(init);
+    if (!codecs)
+        throw new SegmentBinderError('no track could be read from the init segment');
+    const mime = segmentMimeType(codecs);
+    say(`segments: opening ${mime} (${kind})`);
+    // ── attach ──────────────────────────────────────────────────────────────────────────────────────
+    const source = new Source();
+    const revoke = options.revokeObjectURL ?? ((u) => URL.revokeObjectURL(u));
+    let attachedBy = 'srcObject';
+    let objectUrl;
+    try {
+        element.srcObject = source;
+    }
+    catch {
+        attachedBy = 'objectURL';
+        const mint = options.createObjectURL ?? ((s) => URL.createObjectURL(s));
+        objectUrl = mint(source);
+        element.src = objectUrl;
+    }
+    // ⚠ The object URL is minted BEFORE anything below can fail, so EVERY failure between the mint and
+    // 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`. 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();
+        const settle = (finish) => () => {
+            clearTimeout(timer);
+            source.removeEventListener('sourceopen', onOpen);
+            source.removeEventListener('sourceclose', onClose);
+            finish();
+        };
+        const onOpen = settle(() => res());
+        const onClose = settle(() => rej(new SegmentBinderError('the MediaSource closed before it opened')));
+        const timer = setTimeout(settle(() => rej(new SegmentBinderError(`the MediaSource did not open within ${ATTACH_TIMEOUT_MS} ms (attached by ${attachedBy})`))), ATTACH_TIMEOUT_MS);
+        source.addEventListener('sourceopen', onOpen);
+        source.addEventListener('sourceclose', onClose);
+    }).catch(revokeAndRethrow);
+    let buffer;
+    try {
+        // Throws synchronously for a codecs string this implementation refuses.
+        buffer = source.addSourceBuffer(mime);
+    }
+    catch (e) {
+        revokeAndRethrow(e);
+    }
+    // ── state ───────────────────────────────────────────────────────────────────────────────────────
+    const appended = new Set();
+    // Absent signals mean ALWAYS streaming. A managed source flips this on its own events.
+    let streaming = true;
+    let disposed = false;
+    let pumping = false;
+    /**
+     * 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 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) => {
+        const done = (settle) => () => {
+            buffer.removeEventListener('updateend', onDone);
+            buffer.removeEventListener('error', onFail);
+            settle();
+        };
+        const onDone = done(() => res());
+        const onFail = done(() => rej(new SegmentBinderError('appendBuffer failed')));
+        buffer.addEventListener('updateend', onDone);
+        buffer.addEventListener('error', onFail);
+        try {
+            buffer.appendBuffer(bytes);
+        }
+        catch (e) {
+            // A synchronous throw settles nothing through the events, so shed them here too.
+            buffer.removeEventListener('updateend', onDone);
+            buffer.removeEventListener('error', onFail);
+            rej(new SegmentBinderError(`appendBuffer threw: ${e.message}`));
+        }
+    });
+    await append(init).catch(revokeAndRethrow);
+    say('segments: init appended');
+    /**
+     * Fetch and append whatever {@link nextSegment} asks for, one at a time.
+     *
+     * ⚠ 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.
+     */
+    const pump = async () => {
+        if (pumping || disposed)
+            return;
+        pumping = true;
+        try {
+            for (;;) {
+                if (disposed)
+                    return;
+                const index = nextSegment({ currentTime: element.currentTime, bufferedAhead: bufferedAhead(element), appended, streaming }, { segments: parsed.segments, targetAheadSeconds });
+                if (index === null)
+                    break;
+                const entry = parsed.segments[index];
+                const response = await doFetch(resolve(manifestUrl, entry.uri));
+                if (disposed)
+                    return;
+                if (!response.ok) {
+                    // 503 is the host saying "still producing" — a WAIT, not a failure. The route answers it
+                    // rather than 404ing a source that is merely not ready yet.
+                    fail(`segments: ${entry.uri} answered ${response.status}`);
+                    break;
+                }
+                await append(new Uint8Array(await response.arrayBuffer()));
+                appended.add(index);
+                if (disposed)
+                    return;
+            }
+            // Every segment in: say so, or the element never learns it has reached the end.
+            if (appended.size === parsed.segments.length && source.readyState === 'open') {
+                source.endOfStream();
+                say('segments: endOfStream');
+            }
+        }
+        catch (e) {
+            fail(`segments: ${e.message}`);
+        }
+        finally {
+            pumping = false;
+        }
+    };
+    // ── the events that should make us reconsider ───────────────────────────────────────────────────
+    const onStart = () => { streaming = true; say('segments: startstreaming'); void pump(); };
+    const onEnd = () => { streaming = false; say('segments: endstreaming'); };
+    const wake = () => { void pump(); };
+    source.addEventListener('startstreaming', onStart);
+    source.addEventListener('endstreaming', onEnd);
+    element.addEventListener('timeupdate', wake);
+    element.addEventListener('seeking', wake);
+    element.addEventListener('waiting', wake);
+    void pump();
+    return {
+        get appended() { return appended; },
+        get streaming() { return streaming; },
+        attachedBy,
+        codecs,
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            source.removeEventListener('startstreaming', onStart);
+            source.removeEventListener('endstreaming', onEnd);
+            element.removeEventListener('timeupdate', wake);
+            element.removeEventListener('seeking', wake);
+            element.removeEventListener('waiting', wake);
+            if (objectUrl)
+                revoke(objectUrl);
+        },
+    };
+}