@shenora/react 0.9.1 → 0.11.0

package/dist/requests.js

@@ -0,0 +1,146 @@
+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.
+ */
+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.
+ */
+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.
+     */
+    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}.
+ */
+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
+ * `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}
+ * 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.
+ */
+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.
+        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 (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.
+            [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: () => 
+            // 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, {
+                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
+ * 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.
+ *
+ * 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.
+ */
+export const useShenoraRequests = createRequestsStore();

package/dist/segmentBinder.d.ts

@@ -0,0 +1,87 @@
+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:
+ *
+ * - **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.
+ * - **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 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.
+ */
+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}, 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.
+     */
+    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 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.
+ */
+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 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.
+ */
+export declare function bindSegmentStream(options: SegmentBinderOptions): Promise<SegmentBinding>;

package/dist/segmentBinder.js

@@ -0,0 +1,256 @@
+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.
+ */
+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.
+ */
+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 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.
+ */
+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.
+     */
+    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 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.
+    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.
+    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 — a real case, per the
+        // remarks on codec derivation above.
+        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 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
+     * 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: 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.
+     */
+    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", 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;
+                }
+                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);
+        },
+    };
+}

package/dist/segmentStream.d.ts

@@ -0,0 +1,136 @@
+/**
+ * The page half of the host's segment route (D71 piece 4) — reading the manifest it serves, choosing the
+ * MediaSource this browser actually has, and deciding what to fetch next.
+ *
+ * 🔴 **Everything in this module is PURE, and the split is deliberate.** The DECISIONS live here, where a
+ * test pins them exactly, and `segmentBinder.ts` holds the imperative half — creating a `SourceBuffer`,
+ * appending bytes, listening to element events. That is the same division `SegmentGrid` makes on the host
+ * side, for the same reason.
+ *
+ * ⚠ **"The imperative half cannot be verified anywhere this repo runs" was true and is no longer.** jsdom
+ * still has no MediaSource and both real implementations still live on devices — but the binder takes its
+ * source and its fetch as PARAMETERS, so a fake drives every branch of it. What a fake cannot say is
+ * whether a real implementation accepts the bytes; that is measured on hardware and recorded in
+ * `docs/design/media.md`.
+ */
+/** 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 produces 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 emits. Deliberately NOT a general playlist parser: this reads what
+ * `SegmentStream` writes, and anything it does not understand is ignored rather than guessed at.
+ *
+ * ⚠ Unknown tags are skipped silently BY DESIGN — a playlist gains tags over time and a parser that threw
+ * on the first one it had not met would break on a host newer than the page.
+ */
+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**.
+ *
+ * 🔴 **The order is the decision, and it is not "newest wins".** iOS on iPhone has only
+ * `ManagedMediaSource`; Android has only `MediaSource`. Where BOTH exist the managed one is still preferred,
+ * because it is the one that tells the page when the platform actually wants data — a page that streams
+ * regardless is what the managed variant was introduced to stop.
+ *
+ * ✅ **Measured rather than assumed** (iPhone 16 Pro simulator, iOS 26, 2026-08-14): `window.MediaSource` is
+ * `false` there and `ManagedMediaSource` is `true`. So on iOS this is not a preference at all — **a binder
+ * that only knows `window.MediaSource` does nothing**, and the naming here is what makes one bundle work on
+ * both shells.
+ *
+ * ⚠ **`'managed'` carries an obligation, which is why this returns a KIND rather than just a constructor.**
+ * A managed source only wants data between its `startstreaming` and `endstreaming` events, and fetching
+ * outside that window is the thing it exists to prevent. A caller that ignores the kind has not merely
+ * missed an optimisation.
+ */
+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 here is a decision whose failure is SILENT in a browser**, which is why it is a pure
+ * function with a test rather than an `if` inside an event handler:
+ *
+ * - **Not streaming → null.** A managed source that is fetched while it said stop is the exact misuse it
+ *   exists to detect, and on iOS the penalty is the platform tearing the source down.
+ * - **Enough buffered → null.** Fetching further ahead than the policy asks does not make playback smoother;
+ *   it fills a quota, and a `QuotaExceededError` on append arrives as a stall with no obvious cause.
+ * - **Otherwise the segment CONTAINING `currentTime`, or the first unappended one after it.** Starting from
+ *   "the next index after the last one appended" instead is what breaks seeking: after a jump the last
+ *   append is nowhere near where the user is now.
+ */
+export declare function nextSegment(state: FetchState, policy: FetchPolicy): number | null;
+/**
+ * The MIME type to open a `SourceBuffer` with.
+ *
+ * ⚠ **The codecs parameter is REQUIRED, not decorative.** `addSourceBuffer('video/mp4')` throws
+ * `NotSupportedError` on every implementation — the buffer has to know what it is about to be fed before the
+ * init segment arrives. The default is H.264 High 4.0 plus AAC-LC.
+ *
+ * 🔴 **And the default is a DEFAULT rather than a guarantee, because the host copies whatever the source
+ * already holds** (D76): a segment's picture keeps the profile and level the original encoder chose, and an
+ * HEVC source arrives as `hvc1` and not `avc1` at all. The family is what an implementation actually checks,
+ * so an H.264 source of any profile plays through the default — **an HEVC one needs its own string**, e.g.
+ * `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 is the part that must be right, and getting it wrong is fatal rather than
+ * degraded.** Measured against Chromium 151 on the kit's own segments: a video-only init segment
+ * appended to a buffer opened with the two-track default (`avc1.640028,mp4a.40.2`) fails the FIRST
+ * append and plays nothing at all — while the same bytes with `avc1.640015` play. A source with no
+ * soundtrack is ordinary, so a fixed default cannot serve both.
+ *
+ * ⚠ **The profile and level, by contrast, are barely checked.** The same measurement fed High 2.1
+ * content to a buffer opened as Baseline 3.0 (`avc1.42E01E`) and it played. That is why this returns a
+ * precise string when the configuration is there to read and a family default when it is not: precision
+ * where it is free, and never a guess about which tracks exist.
+ *
+ * @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;