cbrowser 18.70.0 → 18.72.0

package/dist/recording/timing.js

@@ -0,0 +1,251 @@
+/**
+ * CBrowser - Cognitive Browser Automation
+ * Copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com
+ * Learn more at https://cbrowser.ai - MIT License
+ */
+/**
+ * Minimum per-frame delay. GIF and WebP treat sub-20ms delays inconsistently
+ * (many decoders silently substitute 100ms), so delays are floored here.
+ */
+export const MIN_DELAY_MS = 20;
+/**
+ * Maximum per-frame delay.
+ *
+ Sharp validates each delay against 0..65535 and rejects the whole encode
+ * otherwise: "Expected integer or an array of integers between 0 and 65535 for
+ * delay". A capture left running while the page goes quiet produces exactly
+ * that: the last frame's delay stretches to cover the silent tail, and one
+ * out-of-range value destroys the artifact.
+ *
+ * Note this is sharp's API limit, not the format's. GIF stores delay as a
+ * uint16 of CENTIseconds, so a single frame can legally be held for up to
+ * 655_350ms — ten times what sharp will accept in one value. That gap is what
+ * {@link expandForPlayback} exploits: libvips merges identical consecutive
+ * frames and SUMS their delays, so N legal repeats collapse back into one page
+ * holding for their combined duration. Verified end-to-end in
+ * tests/recording-encoder-delays.test.ts.
+ *
+ * Emitting an illegal delay is therefore not a caller error to validate — it is
+ * this function's job to make impossible. See {@link expandForPlayback} for
+ * holding a frame longer than this ceiling without lying about the timing.
+ */
+export const MAX_DELAY_MS = 65535;
+/** Tolerance for float comparisons on millisecond sums. */
+const EPS = 1e-9;
+/**
+ * Per-frame display delay in milliseconds, derived from consecutive timestamps.
+ *
+ * Frame `i` is displayed for `tMs[i + 1] - tMs[i]`; the last frame is displayed
+ * until `totalDurationMs`. Any lead-in before the first frame (`tMs[0] > 0`) is
+ * folded into frame 0's delay, so the delays describe the whole recording.
+ *
+ * Clamp behaviour, applied in this order:
+ *
+ *  1. FLOOR at {@link MIN_DELAY_MS}. When the floor inflates the total, the
+ *     surplus is reclaimed from the frames that have headroom above it,
+ *     proportionally to how much headroom each has, so the sum stays exactly
+ *     `totalDurationMs` and no frame is singled out. If the recording is too
+ *     short for every frame to hold the floor
+ *     (`frames * MIN_DELAY_MS > totalDurationMs`), the floor wins and the sum is
+ *     `frames * MIN_DELAY_MS` — the animation is then longer than the capture,
+ *     which is the only way to keep all frames visible.
+ *  2. CEILING at {@link MAX_DELAY_MS}, last, so the reclaim cannot push a delay
+ *     back over it. A capped delay means the returned timeline is SHORTER than
+ *     `totalDurationMs`: a frame held past the ceiling cannot be expressed as a
+ *     single delay. That truncation is the safe failure — the alternative is an
+ *     encode that dies and takes the whole artifact with it. To keep real-time
+ *     playback across a long hold, use {@link expandForPlayback}, which repeats
+ *     the held frame instead of truncating it.
+ *
+ * Resulting guarantee: every returned delay is within
+ * `[MIN_DELAY_MS, MAX_DELAY_MS]`, for every input this function accepts.
+ *
+ * @throws if `tMs` is empty, contains negative or decreasing values, or if
+ *         `totalDurationMs` is shorter than the last timestamp.
+ */
+export function delaysFromTimestamps(tMs, totalDurationMs, options = {}) {
+    if (tMs.length === 0) {
+        throw new Error("delaysFromTimestamps: timestamps must not be empty");
+    }
+    if (!Number.isFinite(totalDurationMs) || totalDurationMs < 0) {
+        throw new Error(`delaysFromTimestamps: totalDurationMs must be a non-negative finite number, got ${totalDurationMs}`);
+    }
+    for (let i = 0; i < tMs.length; i++) {
+        const t = tMs[i];
+        if (!Number.isFinite(t) || t < 0) {
+            throw new Error(`delaysFromTimestamps: timestamp ${i} is not a non-negative finite number`);
+        }
+        if (i > 0 && t < tMs[i - 1]) {
+            throw new Error(`delaysFromTimestamps: timestamps must be non-decreasing (index ${i}: ${tMs[i - 1]} -> ${t})`);
+        }
+    }
+    const last = tMs[tMs.length - 1];
+    if (totalDurationMs + EPS < last) {
+        throw new Error(`delaysFromTimestamps: totalDurationMs (${totalDurationMs}) is before the last timestamp (${last})`);
+    }
+    const n = tMs.length;
+    const delays = new Array(n);
+    for (let i = 0; i < n; i++) {
+        const end = i === n - 1 ? totalDurationMs : tMs[i + 1];
+        delays[i] = end - tMs[i];
+    }
+    // Fold the lead-in so the delays cover [0, totalDurationMs].
+    delays[0] = delays[0] + tMs[0];
+    let total = 0;
+    let headroom = 0;
+    for (let i = 0; i < n; i++) {
+        if (delays[i] < MIN_DELAY_MS)
+            delays[i] = MIN_DELAY_MS;
+        total += delays[i];
+        headroom += delays[i] - MIN_DELAY_MS;
+    }
+    const maxDelayMs = options.maxDelayMs ?? MAX_DELAY_MS;
+    if (maxDelayMs < MIN_DELAY_MS) {
+        throw new Error(`delaysFromTimestamps: maxDelayMs (${maxDelayMs}) is below MIN_DELAY_MS (${MIN_DELAY_MS})`);
+    }
+    let surplus = total - totalDurationMs;
+    if (surplus <= EPS || headroom <= 0)
+        return applyCeiling(delays, maxDelayMs);
+    // Proportional reclaim: cannot push any frame below the floor because each
+    // frame gives up at most its own share of the available headroom.
+    const take = Math.min(surplus, headroom);
+    for (let i = 0; i < n; i++) {
+        const room = delays[i] - MIN_DELAY_MS;
+        if (room <= 0)
+            continue;
+        delays[i] = delays[i] - (room / headroom) * take;
+        if (delays[i] < MIN_DELAY_MS)
+            delays[i] = MIN_DELAY_MS;
+    }
+    // Second pass absorbs float drift from the proportional split.
+    let achieved = 0;
+    for (let i = 0; i < n; i++)
+        achieved += delays[i];
+    surplus = achieved - totalDurationMs;
+    for (let i = 0; i < n && surplus > EPS; i++) {
+        const room = delays[i] - MIN_DELAY_MS;
+        if (room <= 0)
+            continue;
+        const shave = Math.min(room, surplus);
+        delays[i] = delays[i] - shave;
+        surplus -= shave;
+    }
+    return applyCeiling(delays, maxDelayMs);
+}
+/** Cap in place. Applied last so nothing can push a delay back over the limit. */
+function applyCeiling(delays, maxDelayMs) {
+    for (let i = 0; i < delays.length; i++) {
+        if (delays[i] > maxDelayMs)
+            delays[i] = maxDelayMs;
+    }
+    return delays;
+}
+/**
+ * Pair items (frame paths, buffers) with legal delays, repeating any item held
+ * longer than the ceiling instead of truncating its delay.
+ *
+ * `delaysFromTimestamps` must cap a long hold, which shortens playback. This
+ * keeps real time: a frame held for 166_768ms becomes three copies of that same
+ * frame at ~55_589ms each. The result pairs 1:1 with its items, which is what
+ * the encoders require (`delays.length === frames.length`), and the delays sum
+ * to the same total as the uncapped timeline.
+ *
+ * Splitting evenly rather than emitting `[65535, 65535, 35698]` keeps the
+ * repeats visually indistinguishable in a scrubber and avoids a stray short
+ * frame at the end of a hold.
+ *
+ * @param items One entry per frame, in capture order.
+ * @throws if `items` and `tMs` differ in length, or on any input
+ *         `delaysFromTimestamps` rejects.
+ */
+export function expandForPlayback(items, tMs, totalDurationMs, options = {}) {
+    if (items.length !== tMs.length) {
+        throw new Error(`expandForPlayback: ${items.length} items but ${tMs.length} timestamps - they must pair 1:1`);
+    }
+    const maxDelayMs = options.maxDelayMs ?? MAX_DELAY_MS;
+    // Uncapped, so the true duration of a long hold survives to be split.
+    const trueDelays = delaysFromTimestamps(tMs, totalDurationMs, {
+        maxDelayMs: Number.POSITIVE_INFINITY,
+    });
+    const outItems = [];
+    const outDelays = [];
+    for (let i = 0; i < items.length; i++) {
+        const delay = trueDelays[i];
+        if (delay <= maxDelayMs) {
+            outItems.push(items[i]);
+            outDelays.push(delay);
+            continue;
+        }
+        const repeats = Math.ceil(delay / maxDelayMs);
+        const each = delay / repeats;
+        for (let r = 0; r < repeats; r++) {
+            outItems.push(items[i]);
+            outDelays.push(each);
+        }
+    }
+    return { items: outItems, delays: outDelays };
+}
+/**
+ * Intervals where capture stalled: a delta larger than
+ * `gapFactor * (1000 / targetFps)`.
+ *
+ * @throws if `targetFps` or `gapFactor` are not positive.
+ */
+export function findFrameGaps(tMs, targetFps, gapFactor = 3) {
+    if (!Number.isFinite(targetFps) || targetFps <= 0) {
+        throw new Error(`findFrameGaps: targetFps must be positive, got ${targetFps}`);
+    }
+    if (!Number.isFinite(gapFactor) || gapFactor <= 0) {
+        throw new Error(`findFrameGaps: gapFactor must be positive, got ${gapFactor}`);
+    }
+    const threshold = gapFactor * (1000 / targetFps);
+    const gaps = [];
+    for (let i = 0; i + 1 < tMs.length; i++) {
+        const delta = tMs[i + 1] - tMs[i];
+        if (delta > threshold)
+            gaps.push({ after_index: i, gap_ms: delta });
+    }
+    return gaps;
+}
+/**
+ * Clamp a capture rect into the viewport.
+ *
+ * Origin is clamped to the viewport first, then the extent is trimmed to what
+ * remains. `clamped` is true whenever any component changed, which the manifest
+ * surfaces as `region_clamped`.
+ *
+ * @throws if the input rect or the viewport has zero/negative area, or if the
+ *         rect lies entirely outside the viewport (nothing left to capture).
+ */
+export function clampRect(rect, viewport) {
+    if (!Number.isFinite(viewport.width) || !Number.isFinite(viewport.height)) {
+        throw new Error("clampRect: viewport dimensions must be finite");
+    }
+    if (viewport.width <= 0 || viewport.height <= 0) {
+        throw new Error(`clampRect: viewport must have positive area, got ${viewport.width}x${viewport.height}`);
+    }
+    if (!Number.isFinite(rect.x) ||
+        !Number.isFinite(rect.y) ||
+        !Number.isFinite(rect.width) ||
+        !Number.isFinite(rect.height)) {
+        throw new Error("clampRect: rect components must be finite");
+    }
+    if (rect.width <= 0 || rect.height <= 0) {
+        throw new Error(`clampRect: rect must have positive area, got ${rect.width}x${rect.height}`);
+    }
+    const x = Math.min(Math.max(rect.x, 0), viewport.width);
+    const y = Math.min(Math.max(rect.y, 0), viewport.height);
+    // Trim the far edge back inside the viewport, then re-measure from the
+    // clamped origin so the width can never go negative.
+    const right = Math.min(rect.x + rect.width, viewport.width);
+    const bottom = Math.min(rect.y + rect.height, viewport.height);
+    const width = Math.max(right - x, 0);
+    const height = Math.max(bottom - y, 0);
+    if (width <= 0 || height <= 0) {
+        throw new Error(`clampRect: rect ${rect.width}x${rect.height} at (${rect.x}, ${rect.y}) lies outside the ` +
+            `${viewport.width}x${viewport.height} viewport`);
+    }
+    const clamped = x !== rect.x || y !== rect.y || width !== rect.width || height !== rect.height;
+    return { rect: { x, y, width, height }, clamped };
+}
+//# sourceMappingURL=timing.js.map

package/dist/recording/timing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.js","sourceRoot":"","sources":["../../src/recording/timing.ts"],"names":[],"mappings":"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"}

package/dist/recording/types.d.ts

@@ -0,0 +1,316 @@
+/**
+ * CBrowser - Cognitive Browser Automation
+ * Copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com
+ * Learn more at https://cbrowser.ai - MIT License
+ */
+/**
+ * Recording manifest contract.
+ *
+ * The manifest is the single artifact that describes a recording run: how it
+ * was captured, what was captured, and every frame that made it into the
+ * output. Encoders, the CLI, and any downstream consumer read this file rather
+ * than re-deriving state from the frame directory.
+ *
+ * Schemas are zod v4; every exported TS type is inferred from its schema so the
+ * runtime contract and the compile-time contract cannot drift.
+ */
+import { z } from "zod";
+/**
+ * Manifest format version emitted by this build.
+ *
+ * v2 (2026-07-19) added the two-tier change signal: `key_frames`,
+ * `change_points_saturated` and `ssim_thresholds`, all OPTIONAL in the schema
+ * (expand-contract, so older files keep parsing) but always emitted, so
+ * `version >= 2` reliably signals their presence.
+ *
+ * v3 (2026-07-19) changed the DETECTOR behind those fields from global SSIM to
+ * {@link SSIM_THRESHOLDS} window-min ({@link changeScore}), and re-tuned the
+ * thresholds to the new scale (0.999/0.9 -> 0.95/0.6). The field shapes are
+ * unchanged, but a v3 `change_points` is not numerically comparable to a v2
+ * one — the version is the signal for that, since the values in
+ * `ssim_thresholds` alone cannot convey that the underlying metric changed.
+ * Readers wanting a uniform view across versions should use {@link changeSignal}.
+ */
+export declare const MANIFEST_VERSION = 3;
+/**
+ * Change-detection thresholds for the two-tier signal.
+ *
+ * These are measured against the {@link changeScore} scale (minimum SSIM over an
+ * 8x8 window grid on a 128px signature), NOT global SSIM. The scale is entirely
+ * different from a whole-frame metric and the two are not interchangeable — a
+ * localized text change reads ~0.87 under changeScore versus ~0.9998 under
+ * global SSIM. The producer MUST feed these thresholds changeScore values;
+ * `ssim_thresholds` records them in every manifest so a reader never guesses.
+ *
+ * `CHANGE` (0.95) — "did anything change". Below the practical noise floor
+ * (an unchanging page scores exactly 1.0; window-min does not fire on codec
+ * noise) and above a 12px counter tick (~0.87), which is the localized change
+ * global SSIM could not see at any resolution.
+ *
+ * `KEY` (0.6) — "did something notable happen". The sparse tier, and the same
+ * signal that sets each frame's `anomaly` flag. It sits in the wide gap between
+ * a minor tick (~0.87, excluded) and a real interaction like a form fill
+ * (~0.21, included), so background chrome does not flood it. Because KEY <
+ * CHANGE, `key_frames` is necessarily a subset of `change_points`;
+ * {@link changeSignalIssues} checks a manifest honours it.
+ *
+ * Derived from measurement on five fixtures (static / ticking counter / two
+ * form fills / banner toggle / full-viewport animation), 2026-07-19. The
+ * counter fixture is why the two tiers matter: change_points fires on every
+ * tick and saturates, while key_frames stays empty — so key_frames is the
+ * usable signal precisely when change_points is not.
+ */
+export declare const SSIM_THRESHOLDS: {
+    readonly change: 0.95;
+    readonly key: 0.6;
+};
+/**
+ * Fraction of frames above which `change_points` is considered saturated —
+ * carrying no discriminating information for that capture.
+ */
+export declare const CHANGE_SATURATION_RATIO = 0.7;
+export declare const EngineSchema: z.ZodEnum<{
+    chromium: "chromium";
+    firefox: "firefox";
+    webkit: "webkit";
+}>;
+export declare const CaptureMethodSchema: z.ZodEnum<{
+    "cdp-screencast": "cdp-screencast";
+    "screenshot-loop": "screenshot-loop";
+}>;
+export declare const ViewportSchema: z.ZodObject<{
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    deviceScaleFactor: z.ZodNumber;
+}, z.core.$strip>;
+export declare const RectSchema: z.ZodObject<{
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, z.core.$strip>;
+export declare const DimsSchema: z.ZodObject<{
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * What the recorder was pointed at. Discriminated on `kind` so encoders can
+ * switch exhaustively without guessing from the presence of optional fields.
+ */
+export declare const TargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"viewport">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"region">;
+    rect: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"element">;
+    selector: z.ZodString;
+    padding: z.ZodNumber;
+}, z.core.$strip>], "kind">;
+/**
+ * Console and network records are kept deliberately permissive: the recorder
+ * owns their exact shape and may attach engine-specific extras. Only the fields
+ * the encoders and reports actually read are required; unknown keys survive
+ * parsing untouched.
+ */
+export declare const ConsoleEntrySchema: z.ZodObject<{
+    t_ms: z.ZodNumber;
+    type: z.ZodString;
+    text: z.ZodString;
+}, z.core.$loose>;
+export declare const NetworkEntrySchema: z.ZodObject<{
+    t_ms: z.ZodNumber;
+    url: z.ZodString;
+    method: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodNumber>;
+    failed: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+export declare const FrameSchema: z.ZodObject<{
+    index: z.ZodNumber;
+    t_ms: z.ZodNumber;
+    path: z.ZodString;
+    crop: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>;
+    ssim_prev: z.ZodNullable<z.ZodNumber>;
+    anomaly: z.ZodBoolean;
+    tracking: z.ZodNullable<z.ZodEnum<{
+        ok: "ok";
+        stale: "stale";
+    }>>;
+    console: z.ZodArray<z.ZodObject<{
+        t_ms: z.ZodNumber;
+        type: z.ZodString;
+        text: z.ZodString;
+    }, z.core.$loose>>;
+    network: z.ZodArray<z.ZodObject<{
+        t_ms: z.ZodNumber;
+        url: z.ZodString;
+        method: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodNumber>;
+        failed: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>>;
+}, z.core.$strip>;
+export declare const FrameGapSchema: z.ZodObject<{
+    after_index: z.ZodNumber;
+    gap_ms: z.ZodNumber;
+}, z.core.$strip>;
+export declare const RecordingManifestSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    slug: z.ZodString;
+    engine: z.ZodEnum<{
+        chromium: "chromium";
+        firefox: "firefox";
+        webkit: "webkit";
+    }>;
+    capture_method: z.ZodEnum<{
+        "cdp-screencast": "cdp-screencast";
+        "screenshot-loop": "screenshot-loop";
+    }>;
+    target_fps: z.ZodNumber;
+    actual_fps: z.ZodNumber;
+    viewport: z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        deviceScaleFactor: z.ZodNumber;
+    }, z.core.$strip>;
+    target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"viewport">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"region">;
+        rect: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"element">;
+        selector: z.ZodString;
+        padding: z.ZodNumber;
+    }, z.core.$strip>], "kind">;
+    start_trigger: z.ZodNullable<z.ZodString>;
+    stop_trigger: z.ZodNullable<z.ZodString>;
+    trigger_timeout: z.ZodBoolean;
+    started_at: z.ZodString;
+    duration_ms: z.ZodNumber;
+    output_dims: z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>;
+    frames: z.ZodArray<z.ZodObject<{
+        index: z.ZodNumber;
+        t_ms: z.ZodNumber;
+        path: z.ZodString;
+        crop: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>;
+        ssim_prev: z.ZodNullable<z.ZodNumber>;
+        anomaly: z.ZodBoolean;
+        tracking: z.ZodNullable<z.ZodEnum<{
+            ok: "ok";
+            stale: "stale";
+        }>>;
+        console: z.ZodArray<z.ZodObject<{
+            t_ms: z.ZodNumber;
+            type: z.ZodString;
+            text: z.ZodString;
+        }, z.core.$loose>>;
+        network: z.ZodArray<z.ZodObject<{
+            t_ms: z.ZodNumber;
+            url: z.ZodString;
+            method: z.ZodOptional<z.ZodString>;
+            status: z.ZodOptional<z.ZodNumber>;
+            failed: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>;
+    }, z.core.$strip>>;
+    change_points: z.ZodArray<z.ZodNumber>;
+    key_frames: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    change_points_saturated: z.ZodOptional<z.ZodBoolean>;
+    ssim_thresholds: z.ZodOptional<z.ZodObject<{
+        change: z.ZodNumber;
+        key: z.ZodNumber;
+    }, z.core.$strip>>;
+    method: z.ZodOptional<z.ZodString>;
+    frame_gaps: z.ZodArray<z.ZodObject<{
+        after_index: z.ZodNumber;
+        gap_ms: z.ZodNumber;
+    }, z.core.$strip>>;
+    region_clamped: z.ZodOptional<z.ZodBoolean>;
+    artifacts: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strip>;
+export type Engine = z.infer<typeof EngineSchema>;
+export type CaptureMethod = z.infer<typeof CaptureMethodSchema>;
+export type Viewport = z.infer<typeof ViewportSchema>;
+export type Rect = z.infer<typeof RectSchema>;
+export type Dims = z.infer<typeof DimsSchema>;
+export type RecordingTarget = z.infer<typeof TargetSchema>;
+export type ConsoleEntry = z.infer<typeof ConsoleEntrySchema>;
+export type NetworkEntry = z.infer<typeof NetworkEntrySchema>;
+export type Frame = z.infer<typeof FrameSchema>;
+export type FrameGap = z.infer<typeof FrameGapSchema>;
+export type RecordingManifest = z.infer<typeof RecordingManifestSchema>;
+/**
+ * Parse and validate a manifest.
+ *
+ * Accepts an already-parsed object or a raw JSON string. Throws an `Error`
+ * whose message lists every failing path, so a malformed manifest reports all
+ * of its problems at once instead of one per run.
+ */
+/**
+ * Uniform view of the change signal across manifest versions.
+ *
+ * A pre-v2 manifest has only `change_points`, computed with a whole-frame
+ * (global) SSIM detector — a DIFFERENT metric from the current window-min
+ * {@link SSIM_THRESHOLDS} scale, so the two are not numerically comparable. For
+ * such a file this returns the single list it has as both tiers rather than
+ * inventing a key/change split it never carried, and marks `legacy: true` so a
+ * reader knows the tiers are not really separated and the thresholds are not on
+ * the current scale. `saturated` is false because the old global detector could
+ * not saturate the way window-min can.
+ *
+ * This is NOT the exact identity an earlier version of this comment claimed:
+ * once the detector changed from global SSIM to window-min, an old file's
+ * change points stopped mapping onto today's `key_frames`. Reporting the one
+ * list for both tiers is the honest fallback, not a translation.
+ *
+ * Use this in readers instead of touching the optional fields directly, so a
+ * pre-v2 file does not read as "no key frames" when its change_points are the
+ * only signal it has.
+ */
+export declare function changeSignal(manifest: RecordingManifest): {
+    changePoints: number[];
+    keyFrames: number[];
+    saturated: boolean;
+    thresholds: {
+        change: number;
+        key: number;
+    };
+    legacy: boolean;
+    manifestVersion: number;
+};
+/**
+ * Consistency problems in a manifest's change signal, as human-readable
+ * strings. Empty means consistent.
+ *
+ * These are invariants the two-tier design guarantees by construction, so a
+ * violation means the producer is miscomputing rather than that the file is
+ * merely old. Deliberately NOT enforced inside {@link parseManifest}: readers
+ * such as `capture status` open whatever manifest is most recent, and failing
+ * the read outright would turn a reporting bug into an unreadable capture. Call
+ * this where you want the check — tests, or a diagnostic path.
+ */
+export declare function changeSignalIssues(manifest: RecordingManifest): string[];
+export declare function parseManifest(input: unknown): RecordingManifest;
+//# sourceMappingURL=types.d.ts.map

package/dist/recording/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/recording/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,eAAe;;;CAAsC,CAAC;AAEnE;;;GAGG;AACH,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAM3C,eAAO,MAAM,YAAY;;;;EAA4C,CAAC;AAEtE,eAAO,MAAM,mBAAmB;;;EAAgD,CAAC;AAEjF,eAAO,MAAM,cAAc;;;;iBAIzB,CAAC;AAEH,eAAO,MAAM,UAAU;;;;;iBAKrB,CAAC;AAEH,eAAO,MAAM,UAAU;;;iBAGrB,CAAC;AAMH;;;GAGG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;2BAQvB,CAAC;AAMH;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB;;;;iBAMrB,CAAC;AAEX,eAAO,MAAM,kBAAkB;;;;;;iBAQrB,CAAC;AAMX,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiBtB,CAAC;AAEH,eAAO,MAAM,cAAc;;;iBAIzB,CAAC;AAMH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgElC,CAAC;AAMH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAClD,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AACtD,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAC9C,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAC9C,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAC3D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAChD,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AACtD,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAMxE;;;;;;GAMG;AACH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,iBAAiB,GAAG;IACzD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,MAAM,EAAE,OAAO,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;CACzB,CAaA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,EAAE,CA2CxE;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,CAsB/D"}