mkvpeek 0.1.0

package/dist/matroska/header.js

@@ -0,0 +1,531 @@
+import * as E from "../ebml.js";
+import { gathered } from "../io/lanes.js";
+import { HEAD_BYTES } from "../io/source.js";
+import { windowAt } from "../io/windows.js";
+import { CLUSTER_PROBE_BYTES, headerNeed, hopTopLevel, pastSegment, readClusterTime, readPastHead, } from "./chain.js";
+export async function readContainer(source, depth, { concurrency = 1, signal: stop, ...wants }) {
+    const opened = await openContainer(source, stop);
+    if (typeof opened === "string")
+        return opened;
+    const { segment } = opened;
+    const noTags = new Map();
+    const noCues = new Map();
+    const noInfo = emptyInfo();
+    const noAttachments = [];
+    const parseCuesIn = (w, el) => parseCues(w, el, segment);
+    const wantsInfo = wants.info || depth !== "tracks";
+    const fetchTrackTags = () => fetchedOptional(opened, E.ID.segment.TAGS, noTags, parseTrackTags);
+    const fetchInfo = wantsInfo
+        ? () => fetchedOptional(opened, E.ID.segment.INFO, noInfo, parseInfo)
+        : () => Promise.resolve(noInfo);
+    const fetchAttachments = wants.attachments
+        ? () => readAttachments(opened)
+        : () => Promise.resolve(noAttachments);
+    const fetchTimedFields = depth !== "tracks" ? () => readTimedFields(opened) : () => Promise.resolve(null);
+    const fetchCues = depth === "indexed"
+        ? () => fetchedOptional(opened, E.ID.segment.CUES, noCues, parseCuesIn)
+        : () => Promise.resolve(null);
+    const fetches = [
+        fetchTrackTags,
+        fetchInfo,
+        fetchAttachments,
+        fetchTimedFields,
+        fetchCues,
+    ];
+    const [trackTags, info, attachments, timed, cues] = await gathered(fetches, concurrency, stop);
+    return {
+        ...opened.headerSoFar,
+        trackTags,
+        info,
+        attachments,
+        ...(timed === null ? {} : { head: opened.head, ...timed }),
+        ...(cues === null ? {} : { cues }),
+    };
+}
+const ELEMENT_PROBE_BYTES = 4096;
+const MAX_HEADER_ELEMENT_BYTES = 64 * 1024 ** 2;
+const MAX_ATTACHMENT_CHILDREN = 4096;
+const emptyInfo = () => ({
+    title: null,
+    muxingApp: null,
+    writingApp: null,
+    durationMs: null,
+    timestampScale: E.DEFAULT_TIMESTAMP_SCALE,
+});
+const readsAs = (el, id) => E.decoded(el) && el.id === id;
+const nulTrimmed = (padded) => padded.replace(/\0+$/, "");
+const fetchedOptional = (opened, id, fallback, parse) => optional(fallback, async (fall) => {
+    const el = await fetchElement(opened, id);
+    if (el === null)
+        return fall;
+    return parse(el.window, el.element) ?? fall;
+});
+function probed(opened, at, limit, held) {
+    const need = headerNeed(at, limit);
+    if (E.covers(held, at, need))
+        return Promise.resolve(held);
+    const width = Math.min(ELEMENT_PROBE_BYTES, limit - at);
+    return readPastHead(opened, at, width, held);
+}
+function flagOf(window, field) {
+    const value = E.readUint(window, field);
+    return value === null ? null : value === 1;
+}
+function simpleTag(window, { size, body }) {
+    let name = "";
+    let value = "";
+    for (const part of E.children(window, body, size)) {
+        if (part.id === E.ID.tag.NAME) {
+            name = E.readUtf8(window, part);
+        }
+        else if (part.id === E.ID.tag.STRING) {
+            value = E.readUtf8(window, part);
+        }
+    }
+    return { name: nulTrimmed(name), value: nulTrimmed(value) };
+}
+async function openContainer(source, signal) {
+    const fileSize = await source.size();
+    const head = await windowAt({ source, fileSize }, 0, HEAD_BYTES);
+    const ebml = E.readElement(head, 0);
+    if (!readsAs(ebml, E.ID.root.EBML))
+        return "not-matroska";
+    const segmentEl = E.readElement(head, ebml.next);
+    if (typeof segmentEl === "string" || segmentEl.id !== E.ID.root.SEGMENT) {
+        return "malformed";
+    }
+    const segment = {
+        body: segmentEl.body,
+        end: "open" in segmentEl ? fileSize : segmentEl.next,
+    };
+    const located = locateTopLevel(head, segment);
+    const pass = { source, segment, head, signal, offsets: located };
+    const tracksEl = await fetchElement(pass, E.ID.segment.TRACKS);
+    if (tracksEl === null)
+        return "malformed";
+    const tracks = parseTracks(tracksEl.window, tracksEl.element);
+    if (typeof tracks === "string")
+        return tracks;
+    return { ...pass, headerSoFar: { segment, trackEntries: tracks, fileSize } };
+}
+async function readTimedFields(opened) {
+    const firstClusterTicks = await optional(null, () => readFirstClusterTime(opened));
+    return { firstClusterTicks };
+}
+async function optional(fallback, read) {
+    try {
+        return await read(fallback);
+    }
+    catch (error) {
+        if (!E.isGrammarError(error))
+            throw error;
+        return fallback;
+    }
+}
+async function readFirstClusterTime(opened) {
+    let at = opened.offsets.get(E.ID.segment.CLUSTER);
+    let held = opened.head;
+    if (at === undefined) {
+        for await (const hop of hopTopLevel(opened)) {
+            if (hop.el.id === E.ID.segment.CLUSTER) {
+                at = hop.at;
+                held = hop.window;
+                break;
+            }
+        }
+    }
+    if (at === undefined)
+        return null;
+    const window = await readPastHead(opened, at, CLUSTER_PROBE_BYTES, held);
+    const cluster = E.readElement(window, at);
+    if (typeof cluster === "string" || cluster.id !== E.ID.segment.CLUSTER)
+        return null;
+    return readClusterTime(window, cluster);
+}
+function locateTopLevel(head, segment) {
+    const offsets = new Map();
+    let pos = segment.body;
+    const seekHeads = [];
+    while (pos < segment.end) {
+        const el = E.readElement(head, pos);
+        if (typeof el === "string")
+            break;
+        if ("open" in el) {
+            if (el.id === E.ID.segment.CLUSTER && !offsets.has(el.id)) {
+                offsets.set(el.id, pos);
+            }
+            break;
+        }
+        if (pastSegment(el, segment))
+            break;
+        if (!offsets.has(el.id)) {
+            offsets.set(el.id, pos);
+        }
+        if (el.id === E.ID.segment.SEEK_HEAD)
+            seekHeads.push(el);
+        if (el.id === E.ID.segment.CLUSTER)
+            break;
+        pos = el.next;
+    }
+    try {
+        for (const seekHead of seekHeads) {
+            for (const seek of E.children(head, seekHead.body, seekHead.size)) {
+                if (seek.id !== E.ID.seek.ENTRY)
+                    continue;
+                let id = null;
+                let position = null;
+                for (const field of E.children(head, seek.body, seek.size)) {
+                    if (field.id === E.ID.seek.ID) {
+                        id = E.readUint(head, field);
+                    }
+                    else if (field.id === E.ID.seek.POSITION) {
+                        position = E.readUint(head, field);
+                    }
+                }
+                if (id !== null && position !== null && !offsets.has(id)) {
+                    offsets.set(id, segment.body + position);
+                }
+            }
+        }
+    }
+    catch (error) {
+        if (!E.isGrammarError(error))
+            throw error;
+    }
+    return offsets;
+}
+function parseCues(window, cues, segment) {
+    const byTrack = new Map();
+    const { bytes } = window;
+    const startOf = (at, need) => {
+        const start = at - window.at;
+        if (start < 0 || start + need > bytes.length)
+            throw new E.GrammarError();
+        return start;
+    };
+    const cursor = { id: 0, body: 0, next: 0 };
+    const readElementHead = (at, end) => {
+        const idStart = startOf(at, 1);
+        const idLength = E.vintLength(bytes[idStart]);
+        if (idLength > E.MAX_VINT_BYTES)
+            throw new E.GrammarError();
+        startOf(at, idLength);
+        cursor.id = E.vintValue(bytes, idStart, idLength, "id");
+        const sizeAt = at + idLength;
+        const sizeStart = startOf(sizeAt, 1);
+        const sizeLength = E.vintLength(bytes[sizeStart]);
+        if (sizeLength > E.MAX_VINT_BYTES)
+            throw new E.GrammarError();
+        startOf(sizeAt, sizeLength);
+        if (E.vintAllOnes(bytes, sizeStart, sizeLength))
+            throw new E.GrammarError();
+        cursor.body = sizeAt + sizeLength;
+        cursor.next = cursor.body + E.vintValue(bytes, sizeStart, sizeLength, "size");
+        if (cursor.next > end)
+            throw new E.GrammarError();
+    };
+    const end = cues.body + cues.size;
+    let at = cues.body;
+    while (at < end) {
+        readElementHead(at, end);
+        const pointId = cursor.id;
+        const pointBody = cursor.body;
+        const pointNext = cursor.next;
+        if (pointId === E.ID.cue.POINT) {
+            let fieldAt = pointBody;
+            while (fieldAt < pointNext) {
+                readElementHead(fieldAt, pointNext);
+                const fieldId = cursor.id;
+                const fieldBody = cursor.body;
+                const fieldNext = cursor.next;
+                if (fieldId === E.ID.cue.TRACK_POSITIONS) {
+                    let track = null;
+                    let clusterPos = null;
+                    let relPos = 0;
+                    let itemAt = fieldBody;
+                    while (itemAt < fieldNext) {
+                        readElementHead(itemAt, fieldNext);
+                        const itemId = cursor.id;
+                        const size = cursor.next - cursor.body;
+                        const start = startOf(cursor.body, size);
+                        const value = E.uintFits(size) ? E.uintAt(bytes, start, size) : null;
+                        if (itemId === E.ID.cue.TRACK) {
+                            track = value;
+                        }
+                        else if (itemId === E.ID.cue.CLUSTER_POSITION) {
+                            clusterPos = value;
+                        }
+                        else if (itemId === E.ID.cue.RELATIVE_POSITION) {
+                            relPos = value;
+                        }
+                        itemAt = cursor.next;
+                    }
+                    if (track === null || clusterPos === null || relPos === null)
+                        return null;
+                    const entry = { clusterPos: segment.body + clusterPos, relPos };
+                    const list = byTrack.get(track);
+                    if (list === undefined)
+                        byTrack.set(track, [entry]);
+                    else
+                        list.push(entry);
+                }
+                fieldAt = fieldNext;
+            }
+        }
+        at = pointNext;
+    }
+    return byTrack;
+}
+async function fetchElement(opened, id) {
+    const at = opened.offsets.get(id);
+    if (at === undefined)
+        return null;
+    const probe = await probed(opened, at, opened.head.fileSize, opened.head);
+    const header = E.readElement(probe, at);
+    if (!readsAs(header, id))
+        return null;
+    if (header.next - at > MAX_HEADER_ELEMENT_BYTES)
+        return null;
+    const window = await readPastHead(opened, at, header.next - at, probe);
+    const element = E.readElement(window, at);
+    return E.decoded(element) ? { window, element } : null;
+}
+function parseTracks(window, tracks) {
+    const entries = [];
+    const numbers = new Set();
+    let streamIndex = 0;
+    for (const entry of E.children(window, tracks.body, tracks.size)) {
+        if (entry.id !== E.ID.track.ENTRY)
+            continue;
+        const track = {
+            streamIndex: streamIndex++,
+            number: -1,
+            uid: null,
+            codecId: "",
+            codecPrivate: "",
+            codecDelayNs: 0,
+            type: -1,
+            language: null,
+            languageIetf: null,
+            name: null,
+            flags: {
+                enabled: true,
+                default: true,
+                forced: false,
+                hearingImpaired: null,
+                visualImpaired: null,
+                textDescriptions: null,
+                original: null,
+                commentary: null,
+            },
+            encoded: false,
+        };
+        for (const field of E.children(window, entry.body, entry.size)) {
+            const { id } = field;
+            if (id === E.ID.track.NUMBER) {
+                const number = E.readUint(window, field);
+                if (number === null)
+                    return "malformed";
+                track.number = number;
+            }
+            else if (id === E.ID.track.UID) {
+                track.uid = E.readUid(window, field);
+            }
+            else if (id === E.ID.track.TYPE) {
+                const type = E.readUint(window, field);
+                if (type === null)
+                    return "malformed";
+                track.type = type;
+            }
+            else if (id === E.ID.track.CODEC_ID) {
+                track.codecId = E.readAscii(window, field);
+            }
+            else if (id === E.ID.track.CODEC_PRIVATE) {
+                track.codecPrivate = E.readUtf8(window, field);
+            }
+            else if (id === E.ID.track.CODEC_DELAY) {
+                const delay = E.readUint(window, field);
+                if (delay === null)
+                    return "malformed";
+                track.codecDelayNs = delay;
+            }
+            else if (id === E.ID.track.LANGUAGE) {
+                track.language = E.readAscii(window, field);
+            }
+            else if (id === E.ID.track.LANGUAGE_IETF) {
+                track.languageIetf = E.readAscii(window, field);
+            }
+            else if (id === E.ID.track.NAME) {
+                track.name = E.readUtf8(window, field);
+            }
+            else if (id === E.ID.track.FLAG_FORCED) {
+                track.flags.forced = flagOf(window, field) ?? track.flags.forced;
+            }
+            else if (id === E.ID.track.FLAG_DEFAULT) {
+                track.flags.default = flagOf(window, field) ?? track.flags.default;
+            }
+            else if (id === E.ID.track.FLAG_ENABLED) {
+                track.flags.enabled = flagOf(window, field) ?? track.flags.enabled;
+            }
+            else if (id === E.ID.track.FLAG_HEARING_IMPAIRED) {
+                track.flags.hearingImpaired = flagOf(window, field) ?? track.flags.hearingImpaired;
+            }
+            else if (id === E.ID.track.FLAG_VISUAL_IMPAIRED) {
+                track.flags.visualImpaired = flagOf(window, field) ?? track.flags.visualImpaired;
+            }
+            else if (id === E.ID.track.FLAG_TEXT_DESCRIPTIONS) {
+                track.flags.textDescriptions = flagOf(window, field) ?? track.flags.textDescriptions;
+            }
+            else if (id === E.ID.track.FLAG_ORIGINAL) {
+                track.flags.original = flagOf(window, field) ?? track.flags.original;
+            }
+            else if (id === E.ID.track.FLAG_COMMENTARY) {
+                track.flags.commentary = flagOf(window, field) ?? track.flags.commentary;
+            }
+            else if (id === E.ID.track.CONTENT_ENCODINGS) {
+                track.encoded = true;
+            }
+        }
+        if (track.number < 0)
+            return "malformed";
+        if (numbers.has(track.number))
+            return "malformed";
+        numbers.add(track.number);
+        entries.push(track);
+    }
+    return entries;
+}
+function parseTimestampScale(window, info) {
+    for (const field of E.children(window, info.body, info.size)) {
+        if (field.id !== E.ID.info.TIMESTAMP_SCALE)
+            continue;
+        const scale = E.readUint(window, field);
+        if (scale !== null && scale > 0)
+            return scale;
+    }
+    return E.DEFAULT_TIMESTAMP_SCALE;
+}
+async function eachChildIn(opened, parent, held, visit) {
+    let window = held;
+    let pos = parent.body;
+    let children = 0;
+    while (pos < parent.next) {
+        children += 1;
+        if (children > MAX_ATTACHMENT_CHILDREN)
+            return null;
+        window = await probed(opened, pos, parent.next, window);
+        const field = E.readElement(window, pos);
+        if (!E.decoded(field))
+            return window;
+        if (!E.fits(field, parent.next))
+            return null;
+        const next = await visit(pos, field, window);
+        if (next === null)
+            return null;
+        window = next;
+        pos = field.next;
+    }
+    return window;
+}
+async function readAttachments(opened) {
+    const at = opened.offsets.get(E.ID.segment.ATTACHMENTS);
+    if (at === undefined)
+        return [];
+    const read = async (fallback) => {
+        const window = await probed(opened, at, opened.head.fileSize, opened.head);
+        const attachments = E.readElement(window, at);
+        if (!readsAs(attachments, E.ID.segment.ATTACHMENTS))
+            return fallback;
+        const out = [];
+        const visit = async (_at, fileEl, held) => {
+            if (fileEl.id !== E.ID.attachment.FILE)
+                return held;
+            const file = await readAttachedFile(opened, fileEl, held);
+            if (file === null)
+                return null;
+            out.push(file.file);
+            return file.window;
+        };
+        const last = await eachChildIn(opened, attachments, window, visit);
+        return last === null ? fallback : out;
+    };
+    return optional([], read);
+}
+async function readAttachedFile(opened, fileEl, held) {
+    const out = { fileName: null, mimeType: null, description: null, size: 0, uid: null };
+    const visit = async (at, field, carried) => {
+        if (field.id === E.ID.attachment.FILE_DATA) {
+            out.size = field.size;
+            return carried;
+        }
+        if (field.next - at > ELEMENT_PROBE_BYTES)
+            return carried;
+        const window = await readPastHead(opened, at, field.next - at, carried);
+        if (field.id === E.ID.attachment.FILE_NAME) {
+            out.fileName = nulTrimmed(E.readUtf8(window, field));
+        }
+        else if (field.id === E.ID.attachment.FILE_MIME) {
+            out.mimeType = E.readAscii(window, field);
+        }
+        else if (field.id === E.ID.attachment.FILE_DESCRIPTION) {
+            out.description = nulTrimmed(E.readUtf8(window, field));
+        }
+        else if (field.id === E.ID.attachment.FILE_UID) {
+            out.uid = E.readUid(window, field);
+        }
+        return window;
+    };
+    const last = await eachChildIn(opened, fileEl, held, visit);
+    return last === null ? null : { file: out, window: last };
+}
+function parseInfo(window, info) {
+    const scale = parseTimestampScale(window, info);
+    const out = { ...emptyInfo(), timestampScale: scale };
+    for (const field of E.children(window, info.body, info.size)) {
+        const { id } = field;
+        if (id === E.ID.info.TITLE) {
+            out.title = nulTrimmed(E.readUtf8(window, field));
+        }
+        else if (id === E.ID.info.MUXING_APP) {
+            out.muxingApp = nulTrimmed(E.readUtf8(window, field));
+        }
+        else if (id === E.ID.info.WRITING_APP) {
+            out.writingApp = nulTrimmed(E.readUtf8(window, field));
+        }
+        else if (id === E.ID.info.DURATION) {
+            const ticks = E.readFloat(window, field);
+            if (ticks !== null) {
+                const ms = (ticks * scale) / 1_000_000;
+                if (Number.isFinite(ms) && ms >= 0) {
+                    out.durationMs = ms;
+                }
+            }
+        }
+    }
+    return out;
+}
+function parseTrackTags(window, tags) {
+    const bags = new Map();
+    for (const tag of E.children(window, tags.body, tags.size)) {
+        if (tag.id !== E.ID.tag.ENTRY)
+            continue;
+        let uid = null;
+        const tags = [];
+        for (const field of E.children(window, tag.body, tag.size)) {
+            if (field.id === E.ID.tag.TARGETS) {
+                for (const target of E.children(window, field.body, field.size)) {
+                    if (target.id === E.ID.tag.TRACK_UID) {
+                        uid = E.readUid(window, target);
+                    }
+                }
+            }
+            else if (field.id === E.ID.tag.SIMPLE) {
+                tags.push(simpleTag(window, field));
+            }
+        }
+        if (uid === null || tags.length === 0)
+            continue;
+        bags.set(uid, [...(bags.get(uid) ?? []), ...tags]);
+    }
+    return bags;
+}

package/dist/peek/contract.d.ts

@@ -0,0 +1,57 @@
+import type { Track } from "../tracks/core.js";
+import type { Attachment, ContainerInfo, PeekCode, RefusalCode, Wants } from "../vocabulary.js";
+/** The options every entry point shares. */
+export interface PeekOptions {
+    /** Opt in to container-level facts in the envelope. */
+    info?: boolean;
+    /** Opt in to attachment metadata in the envelope. */
+    attachments?: boolean;
+    /**
+     * The signal that aborts the read.
+     *
+     * The returned {@linkcode PeekOutcome.code} is `cancelled`.
+     *
+     * @example
+     * const stop = new AbortController();
+     * const patience = setTimeout(() => stop.abort(), 5_000);
+     * await peekTracks(url, { signal: stop.signal }).finally(() => clearTimeout(patience));
+     */
+    signal?: AbortSignal;
+}
+/**
+ * The answer every read returns.
+ *
+ * Served or refused, it comes as a value and never as a throw.
+ */
+export interface PeekOutcome<T extends Track> extends HeaderAnswer<T> {
+    code: PeekCode;
+}
+/** What the header answered, as one piece. */
+interface HeaderAnswer<T extends Track> {
+    /** Comes with a refusal too, as long as the header was read. */
+    tracks: T[];
+    info?: ContainerInfo | null;
+    attachments?: Attachment[];
+}
+/** The two opt-in siblings, either what the header read or the absent answer. */
+interface Siblings {
+    info: ContainerInfo | null;
+    attachments: Attachment[];
+}
+export declare const served: <T extends Track>(answer: HeaderAnswer<T>) => PeekOutcome<T>;
+/**
+ * The outcome of a refusal.
+ *
+ * It carries the answer bought if the header was read, and {@linkcode absent} if it was not.
+ */
+export declare const refused: <T extends Track>(code: RefusalCode, answer: HeaderAnswer<T>) => PeekOutcome<T>;
+export declare const wantsOf: (options: PeekOptions) => Wants;
+/**
+ * The answer when the header was not read.
+ *
+ * No tracks can exist, and a requested sibling stands as its absent answer.
+ */
+export declare const absent: (wants: Wants) => HeaderAnswer<never>;
+/** An answer carrying only the siblings that were asked for. */
+export declare function answerOf<T extends Track>(read: Siblings, tracks: T[], wants: Wants): HeaderAnswer<T>;
+export {};

package/dist/peek/contract.js

@@ -0,0 +1,24 @@
+export const served = (answer) => ({
+    ...answer,
+    code: "served",
+});
+export const refused = (code, answer) => ({
+    ...answer,
+    code,
+});
+export const wantsOf = (options) => ({
+    info: options.info === true,
+    attachments: options.attachments === true,
+});
+export const absent = (wants) => answerOf(ABSENT_SIBLINGS, [], wants);
+export function answerOf(read, tracks, wants) {
+    const answer = { tracks };
+    if (wants.info) {
+        answer.info = read.info;
+    }
+    if (wants.attachments) {
+        answer.attachments = read.attachments;
+    }
+    return answer;
+}
+const ABSENT_SIBLINGS = { info: null, attachments: [] };

package/dist/peek/engine.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The engine that produces an envelope at header depth.
+ *
+ * Which kind of answer it becomes is decided by the projection plugged in.
+ */
+import { type Source } from "../io/source.js";
+import { type TracksHeader } from "../matroska/header.js";
+import type { Track } from "../tracks/core.js";
+import { type ListedTrack } from "../tracks/list.js";
+import type { RefusalCode } from "../vocabulary.js";
+import { type PeekOptions, type PeekOutcome } from "./contract.js";
+/**
+ * Folds what was caught (an abort, a source failure, a grammar error) into a refusal.
+ *
+ * The caller picks the code for a grammar error; `error` is only asked whether it is one.
+ */
+export declare function thrownRefusal(error: unknown, grammarCode: "malformed" | "unreadable", signal: AbortSignal | undefined): RefusalCode;
+export declare function fromHeader<T extends Track>(source: Source, options: PeekOptions, projection: (header: TracksHeader) => T[]): Promise<PeekOutcome<T>>;
+export declare function peekTracksFrom(source: Source, options?: PeekOptions): Promise<PeekOutcome<ListedTrack>>;

package/dist/peek/engine.js

@@ -0,0 +1,32 @@
+import * as E from "../ebml.js";
+import { abortReason, stopIfAborted } from "../io/source.js";
+import { readContainer } from "../matroska/header.js";
+import { allTracks } from "../tracks/list.js";
+import { absent, answerOf, refused, served, wantsOf, } from "./contract.js";
+export function thrownRefusal(error, grammarCode, signal) {
+    if (abortReason(signal) !== null)
+        return "cancelled";
+    if (!E.isGrammarError(error))
+        return "source-failed";
+    return grammarCode;
+}
+export async function fromHeader(source, options, projection) {
+    const wants = wantsOf(options);
+    const absentAnswer = absent(wants);
+    try {
+        stopIfAborted(options.signal);
+        const readOptions = { ...wants, signal: options.signal };
+        const header = await readContainer(source, "tracks", readOptions);
+        if (typeof header === "string")
+            return refused(header, absentAnswer);
+        const projected = projection(header);
+        return served(answerOf(header, projected, wants));
+    }
+    catch (error) {
+        const refusal = thrownRefusal(error, "malformed", options.signal);
+        return refused(refusal, absentAnswer);
+    }
+}
+export async function peekTracksFrom(source, options = {}) {
+    return fromHeader(source, options, allTracks);
+}

package/dist/peek/target.d.ts

@@ -0,0 +1,11 @@
+import { type Source } from "../io/source.js";
+import type { Track } from "../tracks/core.js";
+import type { RefusalCode } from "../vocabulary.js";
+import { type PeekOptions, type PeekOutcome } from "./contract.js";
+/** A path (Node) or URL string, bytes in hand, or a {@linkcode Source} opened by the caller. */
+export type Target = Source | ArrayBufferView | ArrayBuffer | string;
+export type Opener = (target: string, signal: AbortSignal | undefined) => Promise<Source | RefusalCode>;
+type Work<T extends Track, O extends PeekOptions> = (source: Source, options: O) => Promise<PeekOutcome<T>>;
+export declare const urlRefusal: (parsed: URL) => RefusalCode | null;
+export declare function overTarget<T extends Track, O extends PeekOptions>(target: Target, options: O, work: Work<T, O>, open?: Opener): Promise<PeekOutcome<T>>;
+export {};