cursedbelt-core 1.0.0

package/src/core/master-lock/presence.ts

@@ -0,0 +1,71 @@
+/**
+ * "Somebody is still here" — evidence the idle watcher accepts that is not a keypress.
+ *
+ * ── The owner's ask (2026-08-25) ────────────────────────────────────────────
+ * *"apps that lock like collections with a master password should not lock when I am
+ * watching a video even if the timer runs out."*
+ *
+ * The idle watcher is deliberately built on INTERACTION rather than on traffic — see
+ * `MasterLockProvider`'s module note, which is right and stays. Watching a film is the
+ * one activity that produces no interaction at all and is nevertheless the most
+ * attentive thing a person does with these apps. Ninety minutes of sitting still was
+ * indistinguishable from ninety minutes of an empty room, and the empty room is what
+ * the feature is for, so the wrong one won.
+ *
+ * ── 🔴 Why this is a predicate over ELEMENTS and not a flag an app sets ─────
+ * A `watching` flag would need collections, flix, music, family and every future
+ * player to remember to raise it, and to lower it on pause, on end, on unmount and on
+ * a navigation — five chances each to leave the site permanently unlockable, which is
+ * strictly worse than locking too eagerly. The DOM already knows: a `<video>` that is
+ * playing is playing. Nothing to raise, nothing to lower, and a player that unmounts
+ * takes its evidence with it.
+ *
+ * ── 🔴 Why a decorative loop is NOT presence ────────────────────────────────
+ * The failure mode that would make this a security hole is an ambient background clip
+ * — muted, looping, autoplaying, running forever with nobody in the building. That is
+ * a recognisable signature (`muted` AND `loop`) and it is refused. A film the owner is
+ * actually watching is not both at once; a muted film that loops is not something this
+ * fleet renders. Where a component knows better than the heuristic, it says so:
+ * `data-master-lock-presence="watch"` counts unconditionally, `"ignore"` never does.
+ */
+
+/** The attribute a component uses to overrule the heuristic below. */
+export const PRESENCE_ATTRIBUTE = "data-master-lock-presence";
+
+/** The subset of `HTMLMediaElement` this needs — declared so the predicate is
+ *  testable without a DOM and cannot drift into reading anything else. */
+export interface PresenceMedia {
+	paused: boolean;
+	ended: boolean;
+	muted: boolean;
+	loop: boolean;
+	/** Seconds. `0` for a stream that has not started, `NaN` before metadata. */
+	duration: number;
+	getAttribute(name: string): string | null;
+}
+
+/**
+ * Is this one element evidence that a person is watching or listening right now?
+ *
+ * Order matters: the explicit attribute wins over everything, because a component that
+ * says "ignore me" is describing itself better than any heuristic can.
+ */
+export function isPresenceMedia(element: PresenceMedia): boolean {
+	const declared = element.getAttribute(PRESENCE_ATTRIBUTE);
+	if (declared === "ignore") return false;
+	if (element.paused || element.ended) return false;
+	if (declared === "watch") return true;
+	// The decorative-loop signature. See the module note.
+	if (element.muted && element.loop) return false;
+	// A clip with no duration yet is a stream still negotiating, not a person watching.
+	// `Infinity` is a live stream, which counts.
+	return element.duration > 0;
+}
+
+/** Is ANY of them? The whole question the idle watcher asks each tick. */
+export function isSomebodyWatching(elements: Iterable<PresenceMedia>): boolean {
+	for (const element of elements) {
+		if (isPresenceMedia(element)) return true;
+	}
+	return false;
+}

package/src/core/master-lock/wire.ts

@@ -0,0 +1,155 @@
+/**
+ * The wire — paths and payloads shared by the lock page, the in-app controls and the server.
+ *
+ * One module both halves import, so a rename cannot make the browser talk to a route that
+ * no longer exists.
+ */
+import type { MasterLockKdfParams } from "./kdf";
+
+/**
+ * The mount prefix. Everything under it is reachable while LOCKED (it is how you unlock);
+ * everything else on the origin is not.
+ *
+ * `__` because a path a user could plausibly want must never collide with it: collections
+ * routes on the hash, and the binary-server inspector owns `/api`, `/raw` and `/preview`.
+ */
+export const MASTER_LOCK_PREFIX = "/__lock";
+
+export const MASTER_LOCK_PATHS = {
+	/** The lock page itself. Also what a locked HTML request is answered with, in place. */
+	page: `${MASTER_LOCK_PREFIX}/`,
+	style: `${MASTER_LOCK_PREFIX}/lock.css`,
+	script: `${MASTER_LOCK_PREFIX}/lock.js`,
+	/** Readable while locked — it carries the KDF params the browser needs to derive. */
+	status: `${MASTER_LOCK_PREFIX}/status`,
+	unlock: `${MASTER_LOCK_PREFIX}/unlock`,
+	/** Slides the idle window. Sent on real INTERACTION only — see the engine. */
+	ping: `${MASTER_LOCK_PREFIX}/ping`,
+	lock: `${MASTER_LOCK_PREFIX}/lock`,
+	change: `${MASTER_LOCK_PREFIX}/change`,
+	settings: `${MASTER_LOCK_PREFIX}/settings`,
+	/**
+	 * Set the FIRST master password for a principal that has none.
+	 *
+	 * Reachable while locked, like {@link MASTER_LOCK_PATHS.unlock}, and for the same
+	 * reason: it is the only way in. It is refused outright unless the lock is
+	 * `enrollable` AND has no record — so it can never overwrite a password, only
+	 * create the one that was never set. Rotation is `change`, which demands the
+	 * current one.
+	 */
+	enroll: `${MASTER_LOCK_PREFIX}/enroll`,
+} as const;
+
+/**
+ * The base name of the cookie the unlock token rides in. Callers want
+ * {@link masterLockCookieName}, not this.
+ *
+ * 🔴 **A cookie is scoped by HOST, never by ORIGIN**, and this constant used to carry a
+ * comment claiming the opposite — *"each app is its own origin, so unlocking one never
+ * unlocks another … falls out of the browser's own rules"*. It does not. The browser
+ * ignores the PORT when deciding which cookies to send, so two locked apps on `localhost`
+ * share one jar and each unlock overwrites the other's token.
+ *
+ * Found 2026-09-11 by walking the feature in a browser, which is the only way it shows:
+ * production is fine (collections and the inspector are different hostnames), but on the
+ * Mac — where every app is `localhost:<port>` — opening the binary-server inspector left
+ * `collections` holding a token its own server had never minted. Nothing is DISCLOSED by
+ * that, because an app-wide lock reads the ambient `unlocked` state, so the site stayed
+ * exactly as visible as it already was. What broke is every route that requires
+ * `presents(req)`, and it broke SILENTLY:
+ *
+ *   · `POST /__lock/lock`     — "Lock this site" did nothing but reload an open page
+ *   · `POST /__lock/settings` — the idle timeout could not be changed
+ *   · `POST /__lock/change`   — the master password could not be rotated
+ *   · `POST /__lock/ping`     — activity stopped sliding the idle clock
+ *
+ * i.e. three of the owner's clauses, on the machine his whole reason for asking is about.
+ * The name is now per app, so the collision cannot happen on any host.
+ */
+export const MASTER_LOCK_COOKIE = "master_lock";
+
+/**
+ * The cookie name for ONE app — `master_lock` for an app that names no key, and
+ * `master_lock_<key>` for one that does.
+ *
+ * The bare name is kept as the no-key answer so an app that has not been given a key
+ * behaves exactly as it did, and so a single locked app on a host needs no migration.
+ * `presentedTokens` reads every `master_lock*` cookie a request carries, so a browser
+ * holding several presents them all and each app matches only its own live tokens —
+ * which is the same constant-time comparison that already decided this.
+ */
+export function masterLockCookieName(appKey?: string): string {
+	const slug = (appKey ?? "")
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+	return slug ? `${MASTER_LOCK_COOKIE}_${slug}` : MASTER_LOCK_COOKIE;
+}
+/** Non-browser callers (a smoke, a curl) may present the token here instead. */
+export const MASTER_LOCK_HEADER = "x-master-lock";
+/** Set on every refusal this feature authors, so a client can tell "you are locked out"
+ *  apart from every other 401 an app might answer with. */
+export const MASTER_LOCK_STATE_HEADER = "x-master-lock-state";
+
+/** What `GET /__lock/status` answers. Readable by anyone who got past the app's own auth,
+ *  and it discloses nothing: a salt, an iteration count and a verdict.
+ *
+ *  @surface output — this DTO is PRODUCED by `MasterLock.status()` and only ever
+ *  read by consumers (`res.json() as MasterLockStatus` in `MasterLockProvider`);
+ *  nothing in the fleet constructs one. So adding a required field to it is
+ *  additive, and without this annotation it is the residual false MAJOR that
+ *  Phase −1's M-B measured and had no cheap fix for (F4). `release/surface.ts`
+ *  records the annotation; `release/classify.ts` honours it. */
+export interface MasterLockStatus {
+	/** Is a master password set at all? False only on an app that was never seeded,
+	 *  or — in per-person mode — for a person who has not chosen one yet. */
+	configured: boolean;
+	/**
+	 * May the caller set a first master password right now (`POST /__lock/enroll`)?
+	 *
+	 * True only in per-person mode and only while `configured` is false. It is what
+	 * lets the lock page show "choose your master password" instead of a box that
+	 * nothing can open — the state a NEW person is in the first time they sign in.
+	 *
+	 * 🔴 Never true once a record exists, so it is not a road to overwriting one.
+	 */
+	enrollable: boolean;
+	locked: boolean;
+	/** The params to derive under. `null` when unconfigured. */
+	kdf: MasterLockKdfParams | null;
+	/** The idle timeout in force, so the page can count down with the server. */
+	idleMs: number;
+	/** Milliseconds of idleness left before this session lapses; `0` when locked. */
+	remainingMs: number;
+	/** Milliseconds until another guess will be evaluated. `0` normally. */
+	retryAfterMs: number;
+}
+
+export interface MasterLockUnlockRequest {
+	verifier: string;
+}
+
+/** Choosing a first master password: fresh params, and the verifier under them. */
+export interface MasterLockEnrollRequest {
+	kdf: MasterLockKdfParams;
+	verifier: string;
+}
+
+export interface MasterLockChangeRequest {
+	/** Derived under the CURRENT params — proof that the person changing it is the person
+	 *  who knows it, re-typed rather than inherited from the open session. */
+	currentVerifier: string;
+	/** The NEW params (a fresh salt) and the verifier derived under them. */
+	kdf: MasterLockKdfParams;
+	verifier: string;
+}
+
+export interface MasterLockSettingsRequest {
+	idleMs: number;
+}
+
+/** Why an unlock was refused. `wrong` and `throttled` are deliberately answered with the
+ *  SAME status and shape on the wire; the distinction exists so the page can show a
+ *  countdown, and it is only ever sent once the caller has already proved they are past
+ *  the app's own auth. */
+export type MasterLockRefusal = "wrong" | "throttled" | "unconfigured" | "locked";

package/src/core/media/bgRemoval.spec.ts

@@ -0,0 +1,120 @@
+import { describe, expect, test } from 'bun:test';
+import { floodFillBGS } from './bgRemoval';
+
+/** Build a `w×h` RGB buffer from a `pick(x,y) → [r,g,b]` function. */
+function rgb(
+  w: number,
+  h: number,
+  pick: (x: number, y: number) => [number, number, number],
+): Uint8Array {
+  const buf = new Uint8Array(w * h * 3);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const [r, g, b] = pick(x, y);
+      const i = (y * w + x) * 3;
+      buf[i] = r;
+      buf[i + 1] = g;
+      buf[i + 2] = b;
+    }
+  }
+  return buf;
+}
+
+const alphaAt = (out: Uint8Array, w: number, x: number, y: number) => out[(y * w + x) * 4 + 3];
+
+describe('floodFillBGS', () => {
+  test('clears a uniform red border but preserves an enclosed blue subject', () => {
+    const w = 4;
+    const h = 4;
+    // Red everywhere except a 2×2 blue block in the middle (x,y ∈ {1,2}).
+    const pixels = rgb(w, h, (x, y) =>
+      x >= 1 && x <= 2 && y >= 1 && y <= 2 ? [0, 0, 255] : [255, 0, 0],
+    );
+    const out = floodFillBGS(pixels, { width: w, height: h, channels: 3 });
+
+    // Output is RGBA, same pixel count.
+    expect(out.length).toBe(w * h * 4);
+    // Every red border pixel is now transparent.
+    expect(alphaAt(out, w, 0, 0)).toBe(0);
+    expect(alphaAt(out, w, 3, 0)).toBe(0);
+    expect(alphaAt(out, w, 0, 3)).toBe(0);
+    // The blue subject stays fully opaque.
+    expect(alphaAt(out, w, 1, 1)).toBe(255);
+    expect(alphaAt(out, w, 2, 2)).toBe(255);
+    // ...and keeps its color.
+    const blue = (1 * w + 1) * 4;
+    expect([out[blue], out[blue + 1], out[blue + 2]]).toEqual([0, 0, 255]);
+  });
+
+  test('an interior pocket matching the background color but walled off is preserved', () => {
+    const w = 5;
+    const h = 5;
+    // Green ring (the subject) around a single red center pixel; red border outside.
+    const pixels = rgb(w, h, (x, y) => {
+      const onRing = x >= 1 && x <= 3 && y >= 1 && y <= 3 && !(x === 2 && y === 2);
+      if (onRing) return [0, 255, 0];
+      return [255, 0, 0]; // border + the enclosed center
+    });
+    const out = floodFillBGS(pixels, { width: w, height: h, channels: 3 });
+    // Outer red border: transparent.
+    expect(alphaAt(out, w, 0, 0)).toBe(0);
+    // The red center is enclosed by green → NOT reachable from a corner seed → opaque.
+    expect(alphaAt(out, w, 2, 2)).toBe(255);
+  });
+
+  test('tolerance lets near-colors count as background', () => {
+    const w = 3;
+    const h = 1;
+    // Near-white, near-white, black — seed only from the left so the black stays.
+    const pixels = new Uint8Array([250, 250, 250, 245, 248, 250, 0, 0, 0]);
+    const tight = floodFillBGS(pixels, {
+      width: w,
+      height: h,
+      channels: 3,
+      tolerance: 2,
+      seeds: [[0, 0]],
+    });
+    // Only the seed pixel (250,250,250) clears; the (245,248,250) is >2 away.
+    expect(alphaAt(tight, w, 0, 0)).toBe(0);
+    expect(alphaAt(tight, w, 1, 0)).toBe(255);
+
+    const loose = floodFillBGS(pixels, {
+      width: w,
+      height: h,
+      channels: 3,
+      tolerance: 20,
+      seeds: [[0, 0]],
+    });
+    expect(alphaAt(loose, w, 0, 0)).toBe(0);
+    expect(alphaAt(loose, w, 1, 0)).toBe(0); // within tolerance now
+    expect(alphaAt(loose, w, 2, 0)).toBe(255); // black is still far from the seed
+  });
+
+  test('respects RGBA input and custom seeds', () => {
+    const w = 3;
+    const h = 1;
+    const pixels = new Uint8Array([
+      10,
+      10,
+      10,
+      255, // x0 black
+      10,
+      10,
+      10,
+      255, // x1 black
+      99,
+      99,
+      99,
+      255, // x2 gray
+    ]);
+    // Seed only from x2 (the gray): the two blacks are untouched.
+    const out = floodFillBGS(pixels, { width: w, height: h, channels: 4, seeds: [[2, 0]] });
+    expect(alphaAt(out, w, 2, 0)).toBe(0);
+    expect(alphaAt(out, w, 0, 0)).toBe(255);
+  });
+
+  test('throws on an undersized buffer and returns empty for a zero-size image', () => {
+    expect(() => floodFillBGS(new Uint8Array(3), { width: 4, height: 4, channels: 3 })).toThrow();
+    expect(floodFillBGS(new Uint8Array(0), { width: 0, height: 0, channels: 3 }).length).toBe(0);
+  });
+});

package/src/core/media/bgRemoval.ts

@@ -0,0 +1,123 @@
+// Pure background removal — a breadth-first flood fill from the image edges that
+// turns the uniform, edge-connected background transparent. Lives in media-core so
+// it is identical in the Bun server (run on sharp's raw RGBA buffer), the browser,
+// and tests; it touches no DOM, no Bun, no npm dep — just a typed pixel array.
+
+export interface FloodFillBGOptions {
+  /** Pixel width of the source buffer. */
+  width: number;
+  /** Pixel height of the source buffer. */
+  height: number;
+  /** Source channel count: 3 (RGB) or 4 (RGBA). Output is always RGBA. */
+  channels: 3 | 4;
+  /**
+   * Max color distance (euclidean over RGB, 0–441) from a seed for a pixel to be
+   * considered "background". 0 removes only the exact seed color; higher values
+   * tolerate gradients/compression noise. Default 32.
+   */
+  tolerance?: number;
+  /**
+   * Seed pixels to fill from, as `[x, y]`. Defaults to the four corners — the usual
+   * "remove the backdrop around a subject" case. Out-of-range seeds are ignored.
+   */
+  seeds?: ReadonlyArray<readonly [number, number]>;
+}
+
+const DEFAULT_TOLERANCE = 32;
+
+/** Default seeds: the four corners of the image. */
+function cornerSeeds(width: number, height: number): Array<readonly [number, number]> {
+  const x1 = width - 1;
+  const y1 = height - 1;
+  return [
+    [0, 0],
+    [x1, 0],
+    [0, y1],
+    [x1, y1],
+  ];
+}
+
+/**
+ * Flood-fill the background to transparent and return a fresh RGBA buffer
+ * (`width * height * 4`). The input is never mutated. A pixel is cleared when it is
+ * reachable from a seed through 4-connected neighbors that are all within
+ * `tolerance` of THAT seed's color — so an interior region matching the background
+ * color but walled off by the subject is preserved.
+ */
+export function floodFillBGS(pixels: Uint8Array, opts: FloodFillBGOptions): Uint8Array {
+  const { width, height, channels } = opts;
+  const tolerance = opts.tolerance ?? DEFAULT_TOLERANCE;
+  const tolSq = tolerance * tolerance;
+  const pxCount = width * height;
+
+  if (width <= 0 || height <= 0) return new Uint8Array(0);
+  if (pixels.length < pxCount * channels) {
+    throw new Error(
+      `floodFillBGS: buffer too small (${pixels.length} bytes for ${width}×${height}×${channels})`,
+    );
+  }
+
+  // Always work in RGBA so the result carries an alpha channel.
+  const out = new Uint8Array(pxCount * 4);
+  for (let i = 0; i < pxCount; i++) {
+    const s = i * channels;
+    out[i * 4] = pixels[s];
+    out[i * 4 + 1] = pixels[s + 1];
+    out[i * 4 + 2] = pixels[s + 2];
+    out[i * 4 + 3] = channels === 4 ? pixels[s + 3] : 255;
+  }
+
+  const cleared = new Uint8Array(pxCount); // visited+removed marker, 0/1
+  const seeds = opts.seeds ?? cornerSeeds(width, height);
+
+  // A flat queue of pixel indices (head pointer → O(1) dequeue). Shared across
+  // seeds: `cleared` prevents re-visiting, so one pass over all seeds is correct.
+  const queue = new Int32Array(pxCount);
+
+  for (const [sx, sy] of seeds) {
+    if (sx < 0 || sy < 0 || sx >= width || sy >= height) continue;
+    const seedIdx = sy * width + sx;
+    if (cleared[seedIdx]) continue;
+    const sr = out[seedIdx * 4];
+    const sg = out[seedIdx * 4 + 1];
+    const sb = out[seedIdx * 4 + 2];
+
+    let head = 0;
+    let tail = 0;
+    cleared[seedIdx] = 1;
+    queue[tail++] = seedIdx;
+
+    while (head < tail) {
+      const idx = queue[head++];
+      out[idx * 4 + 3] = 0; // transparent
+      const x = idx % width;
+      const y = (idx - x) / width;
+      // 4-connected neighbors, each enqueued when within tolerance of THIS seed.
+      for (let n = 0, k = 0; k < 4; k++) {
+        if (k === 0) {
+          if (x === 0) continue;
+          n = idx - 1;
+        } else if (k === 1) {
+          if (x === width - 1) continue;
+          n = idx + 1;
+        } else if (k === 2) {
+          if (y === 0) continue;
+          n = idx - width;
+        } else {
+          if (y === height - 1) continue;
+          n = idx + width;
+        }
+        if (cleared[n]) continue;
+        const dr = out[n * 4] - sr;
+        const dg = out[n * 4 + 1] - sg;
+        const db = out[n * 4 + 2] - sb;
+        if (dr * dr + dg * dg + db * db <= tolSq) {
+          cleared[n] = 1;
+          queue[tail++] = n;
+        }
+      }
+    }
+  }
+
+  return out;
+}

package/src/core/media/ffmpeg.spec.ts

@@ -0,0 +1,135 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  buildProbeArgs,
+  buildThumbnailArgs,
+  buildTrimArgs,
+  ffmpegTimeToSeconds,
+  parseFfmpegProgress,
+  parseFfprobe,
+  videoCodecPlan,
+} from './ffmpeg';
+import type { VideoTrimSpec } from './types';
+
+const trim = (over: Partial<VideoTrimSpec> = {}): VideoTrimSpec => ({
+  inputPath: '/in.mp4',
+  outputPath: '/out.mp4',
+  startSeconds: 2,
+  endSeconds: 8,
+  ...over,
+});
+
+describe('videoCodecPlan', () => {
+  test('mp4 → x264/aac with faststart, quality maps to crf', () => {
+    const p = videoCodecPlan('mp4', 'high');
+    expect(p.videoCodec).toBe('libx264');
+    expect(p.audioCodec).toBe('aac');
+    expect(p.crf).toBe(18);
+    expect(p.extraOutputArgs).toContain('+faststart');
+  });
+
+  test('webm → vp9/opus', () => {
+    const p = videoCodecPlan('webm', 'low');
+    expect(p.videoCodec).toBe('libvpx-vp9');
+    expect(p.audioCodec).toBe('libopus');
+    expect(p.crf).toBe(37);
+  });
+
+  test('defaults to mp4 medium', () => {
+    expect(videoCodecPlan()).toMatchObject({ videoCodec: 'libx264', crf: 23 });
+  });
+});
+
+describe('buildTrimArgs', () => {
+  test('uses accurate input seek + duration, in the right order', () => {
+    const args = buildTrimArgs(trim());
+    // -ss before -i (accurate seek when transcoding).
+    expect(args.indexOf('-ss')).toBeLessThan(args.indexOf('-i'));
+    // duration = end - start = 6.
+    const t = args[args.indexOf('-t') + 1];
+    expect(Number(t)).toBe(6);
+    expect(args[args.indexOf('-ss') + 1]).toBe('2');
+    expect(args[args.indexOf('-i') + 1]).toBe('/in.mp4');
+    // output path is last.
+    expect(args[args.length - 1]).toBe('/out.mp4');
+    expect(args).toContain('-crf');
+  });
+
+  test('honors format/quality', () => {
+    const args = buildTrimArgs(trim({ format: 'webm', quality: 'high' }));
+    expect(args).toContain('libvpx-vp9');
+    expect(args[args.indexOf('-crf') + 1]).toBe('24');
+  });
+});
+
+describe('buildProbeArgs / buildThumbnailArgs', () => {
+  test('probe asks for quiet json streams + format', () => {
+    const a = buildProbeArgs('/v.mp4');
+    expect(a).toEqual([
+      '-v',
+      'quiet',
+      '-print_format',
+      'json',
+      '-show_streams',
+      '-show_format',
+      '/v.mp4',
+    ]);
+  });
+
+  test('thumbnail seeks then grabs one frame', () => {
+    const a = buildThumbnailArgs('/v.mp4', 3.5, '/t.jpg');
+    expect(a[a.indexOf('-ss') + 1]).toBe('3.5');
+    expect(a).toContain('-frames:v');
+    expect(a[a.indexOf('-frames:v') + 1]).toBe('1');
+    expect(a[a.length - 1]).toBe('/t.jpg');
+  });
+
+  test('thumbnail clamps a negative timestamp to 0', () => {
+    const a = buildThumbnailArgs('/v.mp4', -2, '/t.jpg');
+    expect(a[a.indexOf('-ss') + 1]).toBe('0');
+  });
+});
+
+describe('ffmpegTimeToSeconds', () => {
+  test('parses HH:MM:SS.ss and bare seconds', () => {
+    expect(ffmpegTimeToSeconds('00:00:06.00')).toBeCloseTo(6, 5);
+    expect(ffmpegTimeToSeconds('01:02:03')).toBe(3723);
+    expect(ffmpegTimeToSeconds('12.5')).toBe(12.5);
+    expect(Number.isNaN(ffmpegTimeToSeconds('N/A'))).toBe(true);
+  });
+});
+
+describe('parseFfmpegProgress', () => {
+  test('extracts a percent from a stderr line when total is known', () => {
+    const ev = parseFfmpegProgress(
+      'frame=  60 fps= 30 q=28.0 size=… time=00:00:03.00 bitrate=…',
+      6,
+    );
+    expect(ev).toEqual({ phase: 'encode', progressPercent: 50 });
+  });
+
+  test('clamps to 100 and reports phase without total', () => {
+    expect(parseFfmpegProgress('time=00:00:09.00', 6)?.progressPercent).toBe(100);
+    expect(parseFfmpegProgress('time=00:00:01.00')).toEqual({ phase: 'encode' });
+  });
+
+  test('returns null for a line with no timestamp', () => {
+    expect(parseFfmpegProgress('Press [q] to stop')).toBeNull();
+  });
+});
+
+describe('parseFfprobe', () => {
+  test('reads dimensions/duration/format from the video stream + format block', () => {
+    const r = parseFfprobe({
+      streams: [
+        { codec_type: 'audio' },
+        { codec_type: 'video', width: 1920, height: 1080, duration: '12.0' },
+      ],
+      format: { duration: '12.34', format_name: 'mov,mp4,m4a' },
+    });
+    expect(r).toEqual({ width: 1920, height: 1080, durationSeconds: 12.34, format: 'mov,mp4,m4a' });
+  });
+
+  test('tolerates missing fields', () => {
+    expect(parseFfprobe({})).toEqual({ width: 0, height: 0, durationSeconds: 0, format: '' });
+  });
+});