cursedbelt-core 1.0.0

package/dist/core/master-lock/policy.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The numbers — how long an unlock survives being ignored, and how hard it is to guess at.
+ *
+ * Pure functions with no clock and no I/O of their own, so every edge of the schedule is a
+ * unit test rather than a wait. The engine in `../../server/master-lock/` supplies `now`.
+ */
+/** The owner's default: *"default to 5 minutes if I haven't configured it"*. */
+export declare const DEFAULT_IDLE_MS: number;
+/** Short enough to be a real lock, long enough that typing a password is not the task. */
+export declare const MIN_IDLE_MS = 30000;
+/** A day. Past this the timer is not what is protecting anything — the manual lock is. */
+export declare const MAX_IDLE_MS: number;
+/** Clamp a submitted idle timeout into the usable band. A value that is not a finite
+ *  number at all falls back to the default rather than to a bound: a corrupt record must
+ *  not silently become "locks in 30 seconds" or "never locks". */
+export declare function clampIdleMs(value: unknown): number;
+/** Consecutive failures that cost nothing. */
+export declare const FREE_ATTEMPTS = 5;
+/** The first enforced wait once those are spent. Doubles thereafter. */
+export declare const BASE_DELAY_MS = 30000;
+/** The ceiling on that wait. */
+export declare const MAX_DELAY_MS: number;
+/**
+ * How long must pass after `failures` consecutive failures before another attempt is
+ * evaluated. `failures` includes the one that just happened.
+ *
+ *   ≤5 → 0 · 6 → 30s · 7 → 60s · 8 → 2m · … · ≥11 → 15m (capped)
+ */
+export declare function delayAfter(failures: number): number;
+/** Milliseconds still to wait, given the failure count, when the last one happened, and
+ *  now. `0` means "evaluate it". */
+export declare function windowRemaining(failures: number, lastFailureAt: number, now: number): number;

package/dist/core/master-lock/policy.js

@@ -0,0 +1,52 @@
+/**
+ * The numbers — how long an unlock survives being ignored, and how hard it is to guess at.
+ *
+ * Pure functions with no clock and no I/O of their own, so every edge of the schedule is a
+ * unit test rather than a wait. The engine in `../../server/master-lock/` supplies `now`.
+ */
+/** The owner's default: *"default to 5 minutes if I haven't configured it"*. */
+export const DEFAULT_IDLE_MS = 5 * 60_000;
+/** Short enough to be a real lock, long enough that typing a password is not the task. */
+export const MIN_IDLE_MS = 30_000;
+/** A day. Past this the timer is not what is protecting anything — the manual lock is. */
+export const MAX_IDLE_MS = 24 * 60 * 60_000;
+/** Clamp a submitted idle timeout into the usable band. A value that is not a finite
+ *  number at all falls back to the default rather than to a bound: a corrupt record must
+ *  not silently become "locks in 30 seconds" or "never locks". */
+export function clampIdleMs(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return DEFAULT_IDLE_MS;
+    return Math.min(MAX_IDLE_MS, Math.max(MIN_IDLE_MS, Math.round(value)));
+}
+// ── The guess throttle ──────────────────────────────────────────────────────
+// The same schedule `apps/vault`'s unlock guard implements, and for the same reason: the
+// owner mistypes, an attacker iterates. Never a lockout — the owner locking themselves out
+// of their own laptop is a worse outcome than a slow attacker.
+/** Consecutive failures that cost nothing. */
+export const FREE_ATTEMPTS = 5;
+/** The first enforced wait once those are spent. Doubles thereafter. */
+export const BASE_DELAY_MS = 30_000;
+/** The ceiling on that wait. */
+export const MAX_DELAY_MS = 15 * 60_000;
+/**
+ * How long must pass after `failures` consecutive failures before another attempt is
+ * evaluated. `failures` includes the one that just happened.
+ *
+ *   ≤5 → 0 · 6 → 30s · 7 → 60s · 8 → 2m · … · ≥11 → 15m (capped)
+ */
+export function delayAfter(failures) {
+    if (failures <= FREE_ATTEMPTS)
+        return 0;
+    // Clamp the EXPONENT, not the product: a client that keeps hammering must not shift
+    // past a finite number into Infinity.
+    const exponent = Math.min(failures - FREE_ATTEMPTS - 1, 32);
+    return Math.min(BASE_DELAY_MS * 2 ** exponent, MAX_DELAY_MS);
+}
+/** Milliseconds still to wait, given the failure count, when the last one happened, and
+ *  now. `0` means "evaluate it". */
+export function windowRemaining(failures, lastFailureAt, now) {
+    const delay = delayAfter(failures);
+    if (delay === 0)
+        return 0;
+    return Math.max(0, lastFailureAt + delay - now);
+}

package/dist/core/master-lock/presence.d.ts

@@ -0,0 +1,52 @@
+/**
+ * "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 declare 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 declare function isPresenceMedia(element: PresenceMedia): boolean;
+/** Is ANY of them? The whole question the idle watcher asks each tick. */
+export declare function isSomebodyWatching(elements: Iterable<PresenceMedia>): boolean;

package/dist/core/master-lock/presence.js

@@ -0,0 +1,61 @@
+/**
+ * "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";
+/**
+ * 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) {
+    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) {
+    for (const element of elements) {
+        if (isPresenceMedia(element))
+            return true;
+    }
+    return false;
+}

package/dist/core/master-lock/wire.d.ts

@@ -0,0 +1,139 @@
+/**
+ * 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 declare const MASTER_LOCK_PREFIX = "/__lock";
+export declare const MASTER_LOCK_PATHS: {
+    /** The lock page itself. Also what a locked HTML request is answered with, in place. */
+    readonly page: "/__lock/";
+    readonly style: "/__lock/lock.css";
+    readonly script: "/__lock/lock.js";
+    /** Readable while locked — it carries the KDF params the browser needs to derive. */
+    readonly status: "/__lock/status";
+    readonly unlock: "/__lock/unlock";
+    /** Slides the idle window. Sent on real INTERACTION only — see the engine. */
+    readonly ping: "/__lock/ping";
+    readonly lock: "/__lock/lock";
+    readonly change: "/__lock/change";
+    readonly settings: "/__lock/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.
+     */
+    readonly enroll: "/__lock/enroll";
+};
+/**
+ * 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 declare 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 declare function masterLockCookieName(appKey?: string): string;
+/** Non-browser callers (a smoke, a curl) may present the token here instead. */
+export declare 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 declare 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/dist/core/master-lock/wire.js

@@ -0,0 +1,81 @@
+/**
+ * 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`,
+};
+/**
+ * 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) {
+    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";

package/dist/core/media/bgRemoval.d.ts

@@ -0,0 +1,27 @@
+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]>;
+}
+/**
+ * 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 declare function floodFillBGS(pixels: Uint8Array, opts: FloodFillBGOptions): Uint8Array;

package/dist/core/media/bgRemoval.js

@@ -0,0 +1,101 @@
+// 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.
+const DEFAULT_TOLERANCE = 32;
+/** Default seeds: the four corners of the image. */
+function cornerSeeds(width, height) {
+    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, opts) {
+    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/dist/core/media/ffmpeg.d.ts

@@ -0,0 +1,57 @@
+import type { VideoFormat, VideoProgressEvent, VideoQuality, VideoTrimSpec } from './types';
+/** Codec + rate-control plan for an output container at a quality preset. */
+export interface VideoCodecPlan {
+    videoCodec: string;
+    audioCodec: string;
+    /** Constant Rate Factor — lower is higher quality (x264 ~18 visually lossless). */
+    crf: number;
+    preset: string;
+    /** Container-specific extra output flags (e.g. faststart for mp4). */
+    extraOutputArgs: string[];
+}
+/**
+ * Resolve the codec plan for a trim. mp4 → H.264/AAC (universal playback) with
+ * `+faststart` so the moov atom is up front (web streaming); webm → VP9/Opus.
+ */
+export declare function videoCodecPlan(format?: VideoFormat, quality?: VideoQuality): VideoCodecPlan;
+/**
+ * Build the ffmpeg argv (without the `ffmpeg` binary) for a re-encoding trim.
+ * Uses accurate input seeking (`-ss` before `-i`, accurate when transcoding) plus
+ * `-t duration` so the clip is exactly `end - start` long regardless of keyframes.
+ */
+export declare function buildTrimArgs(spec: VideoTrimSpec): string[];
+/** ffprobe argv for `probeMedia` — quiet JSON with streams + format. */
+export declare function buildProbeArgs(inputPath: string): string[];
+/** ffmpeg argv to grab a single frame at `atSeconds` and write it to `output`. */
+export declare function buildThumbnailArgs(inputPath: string, atSeconds: number, output: string): string[];
+/** Parse an ffmpeg `HH:MM:SS.ss` (or bare seconds) timestamp into seconds. */
+export declare function ffmpegTimeToSeconds(time: string): number;
+/**
+ * Parse one line/chunk of ffmpeg stderr into a progress event. ffmpeg emits
+ * `frame=… time=00:00:03.00 …` (carriage-return-updated). Returns an `encode`
+ * event with a clamped percent when `totalSeconds` is known, else just the phase;
+ * `null` when the line carries no timestamp.
+ */
+export declare function parseFfmpegProgress(line: string, totalSeconds?: number): VideoProgressEvent | null;
+export interface ProbeResult {
+    width: number;
+    height: number;
+    durationSeconds: number;
+    format: string;
+}
+/** Shape of the bits of ffprobe JSON we read. */
+interface FfprobeJson {
+    streams?: Array<{
+        codec_type?: string;
+        width?: number;
+        height?: number;
+        duration?: string;
+    }>;
+    format?: {
+        duration?: string;
+        format_name?: string;
+    };
+}
+/** Extract width/height/duration/format from parsed ffprobe JSON. */
+export declare function parseFfprobe(json: FfprobeJson): ProbeResult;
+export {};