@joewinke/jatui 0.10.0 → 0.12.0

package/dist/video/advisors/quiet-listening.js

@@ -0,0 +1,292 @@
+/**
+ * "Night ears": loudness-compensated quiet listening. Ported verbatim from
+ * extension-library `lib/quiet-listening.js` (mos-5lzns.27). The graph builder
+ * lands here as mos-5lzns.31's contract promised (audio.ts is that task's
+ * wiring target); `amountFor` is the piece every caller can already use.
+ *
+ * This module owns TONE, never LEVEL. The host's loudness matching already
+ * rides the gain toward a target and a limiter catches the peaks; nothing in
+ * here adds makeup gain, and the fact that it doesn't is the whole reason the
+ * two can run at once without fighting. If this file ever grows a gain node
+ * that isn't pinned at unity, the rider downstream will chase it and you'll get
+ * the pumping that loudness matching was written to stop.
+ *
+ * The problem it does solve: your ears are not flat, and they get less flat the
+ * quieter things are. Equal-loudness contours (Fletcher–Munson, and the ISO 226
+ * revision that corrected them) fall off at both ends as level drops — at 2am
+ * at a volume that won't wake anyone, the bass has gone and the air on top has
+ * gone with it, and what's left is a midrange smear where dialogue used to be.
+ * The usual response is to keep nudging the volume up for the quiet line and
+ * back down for the next loud one. This tilts the spectrum back instead, and
+ * tightens the dynamics just enough that a whispered line rides above the room
+ * noise of a fridge and a fan.
+ *
+ * Rejected: a real ISO 226 inverse curve per SPL. It needs the absolute
+ * playback SPL to mean anything, and a browser cannot know the amp, the
+ * speakers, or the room — a curve derived from a number we can't measure is
+ * theatre. Two shelves and a presence bump are the honest version of the same
+ * idea: right shape, calibration left as one dial the listener can hear.
+ *
+ *   createQuietChain(ctx) -> { input, output, setAmount, dispose }
+ *   amountFor(volume, nightOn, opts) -> 0..1
+ *
+ * Module rules (src/lib/video/README.md): reads no settings, touches no
+ * <video> — the graph builder is the audio graph's one sanctioned exception
+ * and it takes an AudioContext(-shaped) object, never the element.
+ */
+// ── the shape ───────────────────────────────────────────────────────────────
+// Every number below is a maximum, reached only at amount 1, and every one of
+// them is deliberately modest. This effect is wrong if you can point at it.
+const LOW_HZ = 110; // under the fundamental of most speech (male ~85–180Hz), so
+//                     the shelf lifts weight and room without thickening vowels
+//                     — a 200Hz shelf muddies exactly what we're trying to keep
+const LOW_DB = 4.5; // the tilt an equal-loudness contour asks for over roughly
+//                     20 phon of level drop. Past ~6dB it stops reading as
+//                     "correct" and starts reading as "bass boost".
+const HIGH_HZ = 7000; // sibilance and cymbal air live above here; below ~5kHz a
+//                       shelf starts lifting the presence region twice, since
+//                       the peak below already owns it
+const HIGH_DB = 4.5; // matched to the low shelf on purpose: the compensation is
+//                      a symmetric smile, not a tone preference
+const PRES_HZ = 2500; // consonant band — the t/k/s/f transients that carry
+//                       intelligibility, and the first thing lost when a mix is
+//                       played quietly through small speakers
+const PRES_DB = 2; // half the shelves, and capped hard: this region is where
+//                    "harsh" lives, and 3dB+ here makes long viewing tiring
+const PRES_Q = 0.9; // wide (~1.5 octaves). A narrow, surgical peak sounds like
+//                     a formant and follows the voice around; a wide one just
+//                     tips the band
+const COMP_THRESHOLD = -28; // low, because the material we care about IS quiet.
+//                             A -12dB threshold only ever touches the loud half
+//                             and does nothing for the mumbled line.
+const COMP_RATIO = 3; // gentle. Above ~4:1 you can hear the level moving, and a
+//                       dynamics effect you can hear is worse than the problem.
+const COMP_ATTACK = 0.01; // 10ms: catches a shouted word without clipping the
+//                           leading transient of a consonant, which is what
+//                           makes fast-attack compression sound lispy
+const COMP_RELEASE = 0.3; // ~one syllable group. Faster pumps on speech rhythm;
+//                           much slower and the compressor is still holding the
+//                           level down through the quiet line it should lift
+const COMP_KNEE = 12; // very soft — the transition into compression should be
+//                       inaudible, and with ratio 1 (amount 0) knee is inert
+//                       anyway, so a wide one costs nothing at rest
+// Ramp constant for every parameter move. ~150ms is under the threshold where a
+// tone change reads as an event and over the one where it clicks.
+//
+// Deliberately NOT shortened under prefers-reduced-motion. That preference is
+// about visual and vestibular motion; applying it here would mean stepping gain
+// and filter coefficients instantly, which is an audible click — the
+// accessibility trade runs the wrong way. Motion this module can be blamed for
+// is all in the host's UI, and it honors the preference there.
+const RAMP_TAU = 0.15;
+// A chain that passes audio through untouched — what we degrade to rather than
+// throwing or handing the host a null it will splice into its graph. A missing
+// feature is a shrug; a broken audio graph is silence with no way back, because
+// createMediaElementSource is irreversible once the host has used it.
+function wireChain(ctx) {
+    try {
+        // Bound call — ctx.createGain() not `const make = ctx.createGain; make()`.
+        // WebIDL methods (a real AudioContext's) enforce the receiver and an
+        // unbound call throws "Illegal invocation" — which would degrade a perfectly
+        // good context to the null wire on the partial-graph teardown path below.
+        // (Node's plain-object test doubles don't enforce receivers, which is why
+        // the arrow-function stand-ins never caught this; the class-based one in
+        // the suite does.)
+        const node = ctx?.createGain?.();
+        if (node?.gain)
+            node.gain.value = 1;
+        return {
+            input: node ?? null,
+            output: node ?? null,
+            setAmount() { },
+            dispose() {
+                try {
+                    node?.disconnect?.();
+                }
+                catch {
+                    /* already disconnected */
+                }
+            },
+        };
+    }
+    catch {
+        return { input: null, output: null, setAmount() { }, dispose() { } };
+    }
+}
+export function createQuietChain(ctx) {
+    // duck-typed, not instanceof: OfflineAudioContext, a vendor-prefixed context
+    // and a test double are all legitimate here, and instanceof would reject the
+    // first two for no reason
+    if (!ctx ||
+        typeof ctx.createBiquadFilter !== "function" ||
+        typeof ctx.createGain !== "function") {
+        return wireChain(ctx);
+    }
+    const anyCtx = ctx;
+    let low, pres, high, comp, input, output;
+    try {
+        // Unity gain nodes at both ends are splice points, not level controls, and
+        // they never move off 1. They exist so the host can connect once and keep
+        // its references while everything between them is re-tuned — and so a
+        // future reorder inside this file can't invalidate the host's graph.
+        input = anyCtx.createGain();
+        output = anyCtx.createGain();
+        input.gain.value = 1;
+        output.gain.value = 1;
+        // The per-property `if (x.param)` guards below are deliberate (the
+        // extension just assigns — it trusts the real WebAudio factories). Here the
+        // degrade-to-wire contract is the whole point: a stubbed or incomplete
+        // context must still yield a working chain, never a throw from assigning
+        // into a missing AudioParam. Every param the returned closure touches is
+        // read through the same guards, and setAmount's ramp() no-ops per-param, so
+        // a node missing (say) its Q param degrades that one knob, not the graph.
+        low = anyCtx.createBiquadFilter();
+        low.type = "lowshelf";
+        if (low.frequency)
+            low.frequency.value = LOW_HZ;
+        if (low.gain)
+            low.gain.value = 0;
+        pres = anyCtx.createBiquadFilter();
+        pres.type = "peaking";
+        if (pres.frequency)
+            pres.frequency.value = PRES_HZ;
+        if (pres.Q)
+            pres.Q.value = PRES_Q;
+        if (pres.gain)
+            pres.gain.value = 0;
+        high = anyCtx.createBiquadFilter();
+        high.type = "highshelf";
+        if (high.frequency)
+            high.frequency.value = HIGH_HZ;
+        if (high.gain)
+            high.gain.value = 0;
+        comp = anyCtx.createDynamicsCompressor();
+        // At rest: threshold 0dB and ratio 1:1 — the compressor's transfer function
+        // is the identity line, so it applies no reduction anywhere. (Honest
+        // caveat: WebAudio's compressor keeps its fixed internal lookahead delay
+        // even at ratio 1, so "bit-transparent" here means no gain and no tone
+        // change, not sample-aligned. Removing that delay would mean building and
+        // tearing down the node on every amount crossing, and rebuilding a live
+        // graph mid-playback clicks — a constant few ms of latency on a video whose
+        // audio track is already routed through WebAudio is the cheaper trade.)
+        if (comp.threshold)
+            comp.threshold.value = 0;
+        if (comp.ratio)
+            comp.ratio.value = 1;
+        if (comp.knee)
+            comp.knee.value = COMP_KNEE;
+        if (comp.attack)
+            comp.attack.value = COMP_ATTACK;
+        if (comp.release)
+            comp.release.value = COMP_RELEASE;
+        // EQ before compression, on purpose: the compressor should react to the
+        // spectrum you'll actually hear. Compressing first and tilting after means
+        // the shelves lift material the compressor has already decided was quiet.
+        input.connect(low);
+        low.connect(pres);
+        pres.connect(high);
+        high.connect(comp);
+        comp.connect(output);
+    }
+    catch {
+        // a partially-built graph is worse than none — tear down whatever exists
+        for (const n of [input, low, pres, high, comp, output]) {
+            try {
+                n?.disconnect?.();
+            }
+            catch {
+                /* never throw out of teardown */
+            }
+        }
+        return wireChain(ctx);
+    }
+    let disposed = false;
+    const ramp = (param, value) => {
+        if (!param)
+            return;
+        const now = Number.isFinite(anyCtx.currentTime) ? anyCtx.currentTime : 0;
+        // setTargetAtTime, not linearRampToValueAtTime: an exponential approach has
+        // no corner at either end, and it needs no scheduled end time — which
+        // matters because setAmount is called from a volume drag, many times a
+        // second, and each call must simply retarget the one already in flight
+        // rather than queue another segment behind it.
+        try {
+            param.setTargetAtTime(value, now, RAMP_TAU);
+        }
+        catch {
+            try {
+                param.value = value;
+            }
+            catch {
+                /* a read-only param is a shrug — the tone just doesn't move */
+            }
+        }
+    };
+    return {
+        input,
+        output,
+        setAmount(a) {
+            if (disposed)
+                return;
+            // garbage in reads as "off", never as an exception: this is called from a
+            // volume handler, and a throw there would take the player's UI with it
+            const n = typeof a === "number" && Number.isFinite(a)
+                ? Math.min(1, Math.max(0, a))
+                : 0;
+            ramp(low.gain, LOW_DB * n);
+            ramp(high.gain, HIGH_DB * n);
+            ramp(pres.gain, PRES_DB * n);
+            // Linear in dB for the threshold (0 → -28) and linear in ratio (1 → 3).
+            // Both curves are wrong in theory and right in practice: what the ear
+            // tracks is how much reduction is happening, and reduction is the product
+            // of the two, so the perceived effect already comes out gently
+            // accelerating without shaping either one.
+            ramp(comp.threshold, COMP_THRESHOLD * n);
+            ramp(comp.ratio, 1 + (COMP_RATIO - 1) * n);
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            for (const n of [input, low, pres, high, comp, output]) {
+                try {
+                    n.disconnect?.();
+                }
+                catch {
+                    /* never throw out of teardown */
+                }
+            }
+        },
+    };
+}
+// ── how much ────────────────────────────────────────────────────────────────
+const KNEE_DEFAULT = 0.35; // above about a third of the way up, a normal room
+//                            is loud enough that the contours are near flat and
+//                            compensation would just be a tone control
+const NIGHT_FLOOR = 0.35; // "a little on after dark" — enough to hear on a
+export function amountFor(volume, nightOn, opts) {
+    const floor = nightOn ? NIGHT_FLOOR : 0;
+    // knee comes from a caller and may be anything; an unusable one falls back
+    // rather than producing a divide-by-zero amount
+    let knee = KNEE_DEFAULT;
+    if (opts &&
+        typeof opts === "object" &&
+        typeof opts.knee === "number" &&
+        Number.isFinite(opts.knee) &&
+        opts.knee > 0) {
+        knee = Math.min(1, opts.knee);
+    }
+    // an unreadable volume means we know nothing about how loud this is, so we
+    // apply only what the time of day justifies — guessing "very quiet" from NaN
+    // would slam full compensation on at an unknown level
+    if (typeof volume !== "number" || !Number.isFinite(volume))
+        return floor;
+    const v = Math.min(1, Math.max(0, volume));
+    const t = Math.min(1, Math.max(0, 1 - v / knee)); // 1 at silence, 0 at/above knee
+    // smoothstep, not linear: a linear taper has a corner exactly where you cross
+    // the knee while dragging the volume, and that corner is audible as a lurch
+    // in tone at the one moment you're paying attention to level. This one leaves
+    // and arrives with zero slope, so crossing the knee is a non-event.
+    const taper = t * t * (3 - 2 * t);
+    return Math.min(1, Math.max(taper, floor));
+}

package/dist/video/advisors/resume-point.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Resume at a sentence, never at a second. Ported verbatim from
+ * extension-library `lib/resume-point.js` (mos-5lzns.27).
+ *
+ * Reopening a video drops you back at the exact float you left on, which is
+ * almost always mid-word, so the first thing anyone does is scrub backwards a
+ * few seconds to get their bearings. That scrub is the bug. The data to avoid
+ * it is already on disk — transcript segment starts, diarized turns, chapter
+ * marks — so snap the stored time back to the nearest real boundary at or
+ * before it and hand the caller a line it can say out loud.
+ *
+ *   snapResume(seconds, ctx, opts) -> { at, reason, label }
+ *   resumeLabel(seconds, ctx)      -> the line alone
+ *
+ * reason is one of "exact" | "start" | "sentence" | "turn" | "chapter", and
+ * only "exact" is a promise: at === seconds, nothing moved, safe for a
+ * caller to skip the seek entirely. The two near-the-beginning guards used
+ * to hand back "exact" while quietly relocating the playhead to 0 or to the
+ * maxBack floor — a caller trusting the label sat stuck wherever the clamp
+ * put it. They report "start" now: you are at the beginning of the video,
+ * not resuming, which is a true statement whether or not the number moved.
+ *
+ * ctx  = { transcript, speakers, chapters } — any may be null/empty/unsorted
+ * opts = { maxBack } — the most it may ever rewind. A hard ceiling, not a
+ *   hint: a resume that lands a minute early is worse than one that lands
+ *   mid-word, because it silently replays content you already watched and you
+ *   don't find out until you recognise it.
+ *
+ * CLOSEST WINS, not most-specific-wins. An earlier ranking tried sentence >
+ * turn > chapter outright and it was wrong in the common case: a chapter mark
+ * 0.3s back is obviously the right place to land, and burning 9s to reach a
+ * sentence start instead just to honour a hierarchy throws away the thing the
+ * user actually recognises. Specificity only breaks ties.
+ *
+ * No motion lives here — this returns a number, and whether the player seeks
+ * hard or eases is the player's call. A module that decides *where* to land
+ * should not also decide how the landing animates.
+ *
+ * Input shapes (read structurally, extension spellings): transcript entries
+ * carry `start`/`end`/`text`/`speaker`; speaker turns carry
+ * `start`/`end`/`name`/`ad`; chapters carry `start`/`title`. mos-5lzns.34 owns
+ * the component wiring (resume-at-sentence) — persistence there is a
+ * host-supplied state adapter, never a jatui API call.
+ */
+export type ResumeReason = "exact" | "start" | "sentence" | "turn" | "chapter";
+export interface ResumePoint {
+    at: number;
+    reason: ResumeReason;
+    label: string;
+}
+export interface ResumeCtx {
+    /** Transcript segments: { start, end, text, speaker? }. */
+    transcript?: unknown;
+    /** Diarized turns: { start, end, name, ad? }. */
+    speakers?: unknown;
+    /** Chapter marks: { start, title? }. */
+    chapters?: unknown;
+}
+export interface ResumeOpts {
+    maxBack?: number;
+}
+/**
+ * Snap a stored resume time back to the nearest natural boundary.
+ * Returns { at, reason, label } — always, never throws.
+ */
+export declare function snapResume(seconds: unknown, ctx?: ResumeCtx | null, opts?: ResumeOpts | null): ResumePoint;
+/**
+ * The human line alone: who was talking and roughly what about.
+ * Returns "" when there is nothing worth saying.
+ */
+export declare function resumeLabel(seconds: unknown, ctx?: ResumeCtx | null): string;

package/dist/video/advisors/resume-point.js

@@ -0,0 +1,302 @@
+/**
+ * Resume at a sentence, never at a second. Ported verbatim from
+ * extension-library `lib/resume-point.js` (mos-5lzns.27).
+ *
+ * Reopening a video drops you back at the exact float you left on, which is
+ * almost always mid-word, so the first thing anyone does is scrub backwards a
+ * few seconds to get their bearings. That scrub is the bug. The data to avoid
+ * it is already on disk — transcript segment starts, diarized turns, chapter
+ * marks — so snap the stored time back to the nearest real boundary at or
+ * before it and hand the caller a line it can say out loud.
+ *
+ *   snapResume(seconds, ctx, opts) -> { at, reason, label }
+ *   resumeLabel(seconds, ctx)      -> the line alone
+ *
+ * reason is one of "exact" | "start" | "sentence" | "turn" | "chapter", and
+ * only "exact" is a promise: at === seconds, nothing moved, safe for a
+ * caller to skip the seek entirely. The two near-the-beginning guards used
+ * to hand back "exact" while quietly relocating the playhead to 0 or to the
+ * maxBack floor — a caller trusting the label sat stuck wherever the clamp
+ * put it. They report "start" now: you are at the beginning of the video,
+ * not resuming, which is a true statement whether or not the number moved.
+ *
+ * ctx  = { transcript, speakers, chapters } — any may be null/empty/unsorted
+ * opts = { maxBack } — the most it may ever rewind. A hard ceiling, not a
+ *   hint: a resume that lands a minute early is worse than one that lands
+ *   mid-word, because it silently replays content you already watched and you
+ *   don't find out until you recognise it.
+ *
+ * CLOSEST WINS, not most-specific-wins. An earlier ranking tried sentence >
+ * turn > chapter outright and it was wrong in the common case: a chapter mark
+ * 0.3s back is obviously the right place to land, and burning 9s to reach a
+ * sentence start instead just to honour a hierarchy throws away the thing the
+ * user actually recognises. Specificity only breaks ties.
+ *
+ * No motion lives here — this returns a number, and whether the player seeks
+ * hard or eases is the player's call. A module that decides *where* to land
+ * should not also decide how the landing animates.
+ *
+ * Input shapes (read structurally, extension spellings): transcript entries
+ * carry `start`/`end`/`text`/`speaker`; speaker turns carry
+ * `start`/`end`/`name`/`ad`; chapters carry `start`/`title`. mos-5lzns.34 owns
+ * the component wiring (resume-at-sentence) — persistence there is a
+ * host-supplied state adapter, never a jatui API call.
+ */
+const START_FLOOR = 2; // s — below this you are at the beginning, not resuming
+const DEFAULT_MAX_BACK = 15; // s
+const EPS = 1e-3; // float slop; boundaries arrive as parsed JSON floats
+const LABEL_WORDS = 8;
+// below this a "snap" is a rounding artefact, not a landing worth announcing
+const MIN_MOVE = 0.25;
+// Raw diarizer labels are not names. "picking up where SPEAKER_01 was saying"
+// is worse than saying nothing, so an unresolved label is treated as absent.
+const RAW_LABEL = /^SPEAKER[_\s-]?\d+$/i;
+function sortedByStart(list) {
+    if (!Array.isArray(list))
+        return [];
+    const out = [];
+    for (const e of list) {
+        if (!e || typeof e !== "object")
+            continue;
+        const start = Number(e.start);
+        if (!Number.isFinite(start))
+            continue;
+        const s = Math.max(0, start);
+        const rawEnd = Number(e.end);
+        // a missing/degenerate end means the entry covers only its own instant —
+        // never extrapolate one, an invented end makes resumeLabel claim coverage
+        // over silence it knows nothing about
+        out.push({
+            start: s,
+            end: Number.isFinite(rawEnd) && rawEnd > s ? rawEnd : s,
+            src: e,
+        });
+    }
+    out.sort((a, b) => a.start - b.start);
+    return out;
+}
+function lastAtOrBefore(list, t) {
+    let lo = 0;
+    let hi = list.length - 1;
+    let ans = -1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        if (list[mid].start <= t + EPS) {
+            ans = mid;
+            lo = mid + 1;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    return ans;
+}
+// Does this text finish a thought? Trailing quotes and brackets are stripped
+// first so `he said "we're done."` still counts — the punctuation that matters
+// is under the wrapper, and diarized transcripts are full of wrappers.
+//
+// An ellipsis is deliberately NOT terminal: "so anyway…" is the middle of a
+// sentence that the speaker trailed out of, and landing there is exactly the
+// mid-thought drop this module exists to prevent. It has to be excluded
+// explicitly because "..." ends in a period.
+function endsSentence(text) {
+    if (typeof text !== "string")
+        return false; // no text is no evidence, not a boundary
+    const t = text.trim().replace(/["'”’»)\]]+$/, "");
+    if (!t)
+        return false;
+    if (/(\.\.\.|…)$/.test(t))
+        return false;
+    return /[.?!]$/.test(t);
+}
+// A segment start is only a SENTENCE start if the segment before it closed one.
+// Segment boundaries are decoder chunk edges, not grammar — an ASR pass will
+// happily split "if you drag the / trim handles over here" across two of them,
+// and snapping to the second is the same mid-word landing with extra steps.
+// Index 0 is always a sentence start: nothing precedes it.
+function isSentenceStart(segs, i) {
+    if (i <= 0)
+        return i === 0;
+    return endsSentence(segs[i - 1].src.text);
+}
+function sentenceCandidate(segs, seconds, floor) {
+    // Walk back from the latest segment at-or-before `seconds` until one is a
+    // real sentence start. The walk is bounded by the same window as everything
+    // else, so a long unbroken monologue simply yields no sentence candidate
+    // rather than rewinding to wherever the last full stop happened to be.
+    for (let i = lastAtOrBefore(segs, seconds); i >= 0; i--) {
+        if (segs[i].start < floor - EPS)
+            break;
+        if (isSentenceStart(segs, i))
+            return { at: segs[i].start, reason: "sentence", rank: 3 };
+    }
+    return null;
+}
+function turnCandidate(turns, seconds, floor) {
+    // Ad reads are not landing points: "picking up where the sponsor was
+    // reading" is never what you wanted. The walk STOPS at one rather than
+    // stepping over it — the comment here used to claim that and the code did
+    // the opposite (`continue`, not `break`), so a resume a few seconds into a
+    // sponsor read walked back past the whole thing and made you sit through it
+    // again. Landing before an ad you had already got past is the one outcome
+    // worse than landing mid-word.
+    for (let i = lastAtOrBefore(turns, seconds); i >= 0; i--) {
+        if (turns[i].start < floor - EPS)
+            break;
+        if (turns[i].src.ad === true)
+            return null;
+        return { at: turns[i].start, reason: "turn", rank: 2 };
+    }
+    return null;
+}
+// The ad ranges, for the two candidate paths that have no idea speakers exist.
+// Ads live in the SPEAKERS lane, not the transcript, so without this a resume
+// inside a sponsor read falls straight through to the sentence path, lands on
+// the ad's first sentence, and quotes the sponsor back to you in the toast.
+function adRanges(turns) {
+    const out = [];
+    for (const t of turns) {
+        if (t.src.ad === true && Number.isFinite(t.end) && t.end > t.start)
+            out.push([t.start, t.end]);
+    }
+    return out;
+}
+const insideAd = (t, ads) => ads.some(([a, b]) => t >= a - EPS && t <= b + EPS);
+function chapterCandidate(chaps, seconds, floor) {
+    const i = lastAtOrBefore(chaps, seconds);
+    if (i < 0 || chaps[i].start < floor - EPS)
+        return null;
+    return { at: chaps[i].start, reason: "chapter", rank: 1 };
+}
+/**
+ * Snap a stored resume time back to the nearest natural boundary.
+ * Returns { at, reason, label } — always, never throws.
+ */
+export function snapResume(seconds, ctx, opts) {
+    const t = Number(seconds);
+    const o = opts && typeof opts === "object" ? opts : {};
+    const rawBack = Number(o.maxBack);
+    // an unreadable maxBack falls back to the default rather than to zero: the
+    // caller clearly wanted snapping, and silently disabling it produces a bug
+    // that looks exactly like "the feature doesn't work"
+    const maxBack = Number.isFinite(rawBack)
+        ? Math.max(0, rawBack)
+        : DEFAULT_MAX_BACK;
+    // Garbage input (NaN, undefined, Infinity, negative) has no honest place to
+    // resume to, so the safe neutral value is 0 — the house rule of "bad input
+    // returns a neutral value" applied to a timeline. Reason is "start", not
+    // "exact": for anything other than a literal 0 this still moved the number
+    // (a negative or non-finite `seconds` is never equal to the 0 we hand
+    // back), and "exact" is reserved for at === seconds.
+    if (!Number.isFinite(t) || t <= 0)
+        return { at: 0, reason: "start", label: "" };
+    const c = ctx && typeof ctx === "object" ? ctx : {};
+    const floor = Math.max(0, t - maxBack);
+    // Near the top of a video there is nothing to pick up from — you have not
+    // watched enough to have lost your place, and any snap here is just 0 with
+    // extra reasoning attached. Still clamped to the window: with the default
+    // maxBack this is plain 0, but the two rules genuinely collide when a caller
+    // passes maxBack < 2, and the ceiling is the one that was called a hard
+    // promise, so it wins.
+    //
+    // Found by adversarial review: this used to report "exact" here, which is
+    // wrong whenever the window clamp actually bites — snapResume(1.5, ctx,
+    // {maxBack: 0.5}) moved the playhead a full half second (floor = 1) and
+    // called itself unchanged. Callers key off "exact" to mean "skip the seek",
+    // so that lie meant a real half-second seek silently got dropped. "start"
+    // says what is actually true: you're at the beginning, not resuming —
+    // regardless of whether `floor` happened to land on 0 or on the window edge.
+    if (t < START_FLOOR)
+        return { at: floor, reason: "start", label: "" };
+    const turns = sortedByStart(c.speakers);
+    const ads = adRanges(turns);
+    // Already inside a sponsor read: every rewind from here lands in it or
+    // before it, and both mean listening to it again. Stay exactly where you
+    // are and say nothing — the one case where mid-word is the right answer.
+    if (insideAd(t, ads))
+        return { at: t, reason: "exact", label: "" };
+    const found = [
+        sentenceCandidate(sortedByStart(c.transcript), t, floor),
+        turnCandidate(turns, t, floor),
+        chapterCandidate(sortedByStart(c.chapters), t, floor),
+    ];
+    let best = null;
+    for (const cand of found) {
+        if (!cand)
+            continue;
+        if (insideAd(cand.at, ads))
+            continue; // never land in an ad, whatever found it
+        if (!best || cand.at > best.at + EPS)
+            best = cand;
+        else if (Math.abs(cand.at - best.at) <= EPS && cand.rank > best.rank)
+            best = cand;
+    }
+    if (!best)
+        return { at: t, reason: "exact", label: "" };
+    const at = Math.min(t, Math.max(floor, best.at)); // belt-and-braces on the contract
+    // No label when nothing moved — and this is now enforced rather than merely
+    // described. A toast that fires on a no-op trains you to ignore toasts, and
+    // "picking up where X was saying" is a lie when the playhead has not moved.
+    const moved = at < t - MIN_MOVE;
+    return { at, reason: best.reason, label: moved ? resumeLabel(at, c) : "" };
+}
+// ── the line ────────────────────────────────────────────────────────────────
+function coveringAt(list, t) {
+    const i = lastAtOrBefore(list, t);
+    if (i < 0)
+        return null;
+    return t <= list[i].end + EPS ? list[i] : null; // a gap covers nothing
+}
+function displayName(raw) {
+    if (typeof raw !== "string")
+        return "";
+    const n = raw.trim();
+    return !n || RAW_LABEL.test(n) ? "" : n;
+}
+// Words a quote should never END on. Cutting at a fixed count lands on "…it
+// snaps to the…" about a third of the time, which reads as a glitch rather
+// than a truncation; dropping the dangling function words costs nothing and
+// the line ends on something that carries meaning. Only applied when the quote
+// was actually cut, and never below three words.
+const DANGLING = /^(a|an|the|and|but|or|of|to|in|on|at|for|with|that|is|was|it|as|so)$/i;
+function firstWords(text, n) {
+    if (typeof text !== "string")
+        return "";
+    const words = text.trim().replace(/\s+/g, " ").split(" ").filter(Boolean);
+    if (!words.length)
+        return "";
+    if (words.length <= n)
+        return words.join(" ");
+    const head = words.slice(0, n);
+    while (head.length > 3 && DANGLING.test(head[head.length - 1]))
+        head.pop();
+    // a trailing comma or dash before an ellipsis reads as a typo, not a cut
+    return head.join(" ").replace(/[,;:—–-]+$/, "") + "…";
+}
+/**
+ * The human line alone: who was talking and roughly what about.
+ * Returns "" when there is nothing worth saying.
+ */
+export function resumeLabel(seconds, ctx) {
+    const t = Number(seconds);
+    if (!Number.isFinite(t) || t < 0)
+        return "";
+    const c = ctx && typeof ctx === "object" ? ctx : {};
+    const seg = coveringAt(sortedByStart(c.transcript), t);
+    // Turns are the better source (they carry resolved names and survive a
+    // rename), but a segment's own speaker field is the fallback for libraries
+    // that were transcribed before diarization ran.
+    const name = displayName(coveringAt(sortedByStart(c.speakers), t)?.src.name) ||
+        displayName(seg?.src.speaker);
+    const words = firstWords(seg?.src.text, LABEL_WORDS);
+    // Quoted, never paraphrased. Paraphrasing needs a model, and a summary that
+    // is subtly wrong about what you were watching is more disorienting than the
+    // mid-word drop this whole module is fixing.
+    if (name && words)
+        return `picking up where ${name} was saying “${words}”`;
+    if (words)
+        return `picking up at “${words}”`;
+    if (name)
+        return `picking up where ${name} was talking`;
+    return "";
+}