cursedbelt-server 1.0.0

package/dist/server/master-lock/principals.js

@@ -0,0 +1,157 @@
+/**
+ * PER-PERSON master locks — one record, one password and one unlock per account.
+ *
+ * ── What this changes, and what it deliberately does not ────────────────────
+ * The engine next door (`masterLock.ts`) was built for an app with exactly one user, and
+ * its module note says so at length: *"There is exactly ONE unlock at a time, not one per
+ * browser session … the unit is the SITE."* That is still true of `apps/collections` and
+ * the binary-server inspector, and this file does not touch them.
+ *
+ * It stops being true the moment a second person may open the app. The owner, 2026-08-25:
+ * *"I would pick one that only I know and use and she could pick one for only she knows
+ * just like we did for the vault app."* Two people cannot share one record — the first to
+ * rotate it locks the second out of an app they were granted — and they must not share one
+ * unlock either, or her phone opens his desk.
+ *
+ * So the unit here is the PERSON. Each principal gets its own {@link MasterLock}: its own
+ * KDF salt, its own `argon2id(verifier)`, its own idle clock, its own guess throttle and
+ * its own in-memory unlock. Everything the engine already reasons about holds per person
+ * instead of per app, unchanged.
+ *
+ * ── 🔴 Three properties this file is responsible for ────────────────────────
+ *
+ * **1. One principal's unlock can never open another's.** Falls out of the construction —
+ * a token is compared only against the session of the lock it was minted by, and the lock
+ * is selected by the principal on the request's own signed-in session, never by anything
+ * the caller sends. There is no code path that takes a token and searches for a matching
+ * lock, and there must never be one.
+ *
+ * **2. A principal id can never reach the storage key.** Ids in this fleet are sometimes
+ * uuids and sometimes raw email addresses (`apps/auth` carries ca's originals verbatim),
+ * so they are attacker-adjacent strings of unbounded shape. They are HASHED into the key
+ * rather than interpolated: a fixed-length hex suffix cannot collide with another key,
+ * cannot escape the namespace, and cannot smuggle a `:` that makes one person's row look
+ * like another's.
+ *
+ * **3. There is no seed.** `MASTER_LOCK_SEED` arms an app-wide lock from the vault's own
+ * record; per-person there is nothing sensible to seed a *stranger's* password from, and
+ * an env var that pre-set someone's password would be exactly the "one credential opens
+ * everybody" shape this replaces. A principal with no record is `awaitingEnrollment` —
+ * locked, and offered the choose-a-password form.
+ */
+import { createHash } from "node:crypto";
+import { MasterLock, readRecord } from "./masterLock";
+/** Namespace for every per-person record, so one glance at the table says what they are. */
+export const MASTER_LOCK_PRINCIPAL_KEY_PREFIX = "master_lock:principal:";
+/**
+ * The storage key for one principal.
+ *
+ * SHA-256 hex of the id — see property 2 in the module note. It is not a security
+ * boundary (the id is not a secret and the hash is not salted); it is a SHAPE boundary,
+ * which is the thing that was actually at risk.
+ */
+export function masterLockPrincipalKey(principalId) {
+    const digest = createHash("sha256").update(principalId, "utf8").digest("hex");
+    return `${MASTER_LOCK_PRINCIPAL_KEY_PREFIX}${digest}`;
+}
+/**
+ * Every person's lock, made on first sight and held for the process's life.
+ *
+ * Locks live in memory alongside their unlock, exactly as the single-app engine's do, so
+ * a restart re-locks everybody. That is the correct default for a wall whose whole risk
+ * model is "this browser is somewhere it should not be".
+ */
+export class MasterLockDirectory {
+    locks = new Map();
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * This principal's lock, created on first sight.
+     *
+     * 🔴 `principalId` must come from the request's own verified session and never from a
+     * header, a query parameter or a body field. The guard's `resolve` is the one place
+     * that decides it; see property 1 in the module note.
+     */
+    for(principalId) {
+        const existing = this.locks.get(principalId);
+        if (existing)
+            return existing;
+        const key = masterLockPrincipalKey(principalId);
+        const { kv } = this.options;
+        const store = {
+            read: () => kv.get(key) ?? null,
+            write: (json) => kv.set(key, json),
+        };
+        const lock = new MasterLock({
+            store,
+            enrollable: true,
+            ...(this.options.now ? { now: this.options.now } : {}),
+            ...(this.options.log
+                ? { log: (line) => this.options.log?.(`[${principalId}] ${line}`) }
+                : {}),
+        });
+        this.locks.set(principalId, lock);
+        return lock;
+    }
+    /** Has this principal chosen a master password? Reads storage, so it is true of a
+     *  person who enrolled in a previous boot and has not been seen in this one. */
+    isEnrolled(principalId) {
+        return this.for(principalId).configured;
+    }
+    /**
+     * Install a PRE-DERIVED record for one principal, if and only if it has none.
+     *
+     * ── What this is for, and what it is not ───────────────────────────────────
+     * A machine account — `apps/orch`'s deploy smoke is the only one so far. Its master
+     * password lives 0600 on the owner's Mac, so there is no browser to type it in, and
+     * the alternative shapes are both worse: letting the smoke `POST /__lock/enroll` makes
+     * it WRITE to a live production site (which `scripts/smokeCleanup.test.ts` refuses, on
+     * the owner's rule), and giving the smoke a bypass makes the wall unproven.
+     *
+     * 🔴 It is NOT an opening and cannot become one. `json` is `{kdf, verifierHash}` —
+     * already derived, the same shape `MASTER_LOCK_SEED` has carried since 2026-08-15 — so
+     * no password passes through this process, and whoever unlocks still has to present a
+     * verifier that matches. Seeding an account only decides that it HAS a password, never
+     * that anybody may skip it.
+     *
+     * Refuses when a record already exists, so it can never rotate one out from under the
+     * person holding it. Returns whether it installed anything.
+     */
+    seed(principalId, json) {
+        const key = masterLockPrincipalKey(principalId);
+        const { kv } = this.options;
+        if (readRecord(kv.get(key) ?? null))
+            return false;
+        const record = readRecord(json);
+        if (!record)
+            return false;
+        kv.set(key, JSON.stringify(record));
+        // Drop any lock built before the row existed, so `for()` re-reads it rather than
+        // serving the cached "unconfigured" one. Nothing can be unlocked yet by definition.
+        this.locks.delete(principalId);
+        return true;
+    }
+    /** Lock every open session — the "I am handing this laptop over" button, fleet-wide.
+     *  Only ever reaches principals seen since boot, which is all that can be unlocked. */
+    lockAll() {
+        for (const lock of this.locks.values())
+            lock.lock();
+    }
+    /** How many principals hold a live unlock right now. For `/healthz` and the boot log;
+     *  a COUNT discloses nothing about who. */
+    unlockedCount() {
+        let count = 0;
+        for (const lock of this.locks.values())
+            if (lock.unlocked)
+                count += 1;
+        return count;
+    }
+    /** Drop every in-memory lock — for tests between cases. */
+    resetForTest() {
+        for (const lock of this.locks.values())
+            lock.resetForTest();
+        this.locks.clear();
+    }
+}

package/dist/server/master-lock/seed.d.ts

@@ -0,0 +1,47 @@
+import { type MasterLockKdfParams } from "cursedbelt-core/master-lock/kdf";
+import type { MasterLockRecord } from "./masterLock";
+/**
+ * The idle window a freshly minted lock starts with.
+ *
+ * 🔴 It is `DEFAULT_IDLE_MS` ITSELF, not a copy that claims to match it. Until
+ * 2026-08-25 this read `15 * 60 * 1000` under a comment saying "matches the store's
+ * default", which is 5 minutes — so any app armed through `mintMasterLockSeed` would
+ * have silently got three times the window the owner asked for. Live prod was spared
+ * only by accident: both seeds omit `idleMs` entirely, so the store's own default
+ * applied. A second constant that must equal a first is a drift waiting for a reader
+ * who trusts the comment; there is now only one number.
+ */
+export declare const DEFAULT_SEED_IDLE_MS: number;
+export interface MintMasterLockSeedOptions {
+    /** Override the idle timeout baked into the seed. */
+    idleMs?: number;
+    /** Reuse existing params instead of generating a salt — for a rotation. */
+    kdf?: MasterLockKdfParams;
+}
+/**
+ * `password` → the record an app can be seeded with.
+ *
+ * Returns the parsed record; {@link serializeMasterLockSeed} is what turns it
+ * into the env value, because that step has its own trap (see below).
+ */
+export declare function mintMasterLockSeed(password: string, options?: MintMasterLockSeedOptions): Promise<MasterLockRecord>;
+/**
+ * The record as it belongs in a 0600 `.env` file.
+ *
+ * 🔴 **SINGLE-QUOTED, and this is not cosmetic.** An argon2id PHC string contains
+ * `$`, the file is sourced by a shell, and an unquoted value therefore arrives at
+ * the app with `$argon2id` expanded to nothing. `readRecord` strips exactly this
+ * quote pair — `apps/collections` shipped a *doubly*-quoted hash to prod on
+ * 2026-08-12 and spent a day being told its correct passphrase was wrong, which
+ * is why the strip is on the whole blob rather than on the field.
+ */
+export declare function serializeMasterLockSeed(record: MasterLockRecord): string;
+/**
+ * A password worth typing into a stage: unambiguous, and long enough that the
+ * hostname being on the internet behind Cloudflare Access is not the only thing
+ * protecting it.
+ *
+ * No `l`, `1`, `O` or `0` — a stage password gets read out of a terminal and
+ * typed into a browser by hand, and this is the one place where that matters.
+ */
+export declare function generateStagePassword(words?: number): string;

package/dist/server/master-lock/seed.js

@@ -0,0 +1,93 @@
+/**
+ * Minting a `MASTER_LOCK_SEED` from a password nobody has to guess.
+ *
+ * ── Why this exists (2026-08-20) ────────────────────────────────────────────
+ * The lock's seed is `{kdf, verifierHash, idleMs}` — a KDF descriptor and an
+ * argon2id hash of a PBKDF2 verifier. Every one of those steps is derivable from
+ * the modules beside this one, and until now every one of them was something an
+ * operator had to reproduce by hand in a REPL to arm a new instance. That is the
+ * shape of instruction that gets written into a runbook and then gets a digit
+ * wrong; the fleet's standing answer to that is a function
+ * (`fleet/rules/automation-over-documentation.md`).
+ *
+ * The immediate caller is the ephemeral **stage** environment, whose entire
+ * purpose is to have a master-lock password an AGENT knows, so it can open
+ * `collections` and the binary-server inspector and actually look at them — two
+ * screens no agent has ever seen, because production's password is the vault's
+ * and is the owner's alone.
+ *
+ * 🔴 **A different PASSWORD, never a different SCHEME.** The derivation stays
+ * byte-identical to `apps/vault`'s (see `../../core/master-lock/kdf.ts`), because
+ * a stage that unlocks under different rules from production proves nothing about
+ * production. This function chooses the salt and the password; it changes nothing
+ * else.
+ */
+import { DEFAULT_IDLE_MS } from "cursedbelt-core/master-lock/policy";
+import { deriveMasterLockVerifier, newMasterLockKdfParams, } from "cursedbelt-core/master-lock/kdf";
+/**
+ * The idle window a freshly minted lock starts with.
+ *
+ * 🔴 It is `DEFAULT_IDLE_MS` ITSELF, not a copy that claims to match it. Until
+ * 2026-08-25 this read `15 * 60 * 1000` under a comment saying "matches the store's
+ * default", which is 5 minutes — so any app armed through `mintMasterLockSeed` would
+ * have silently got three times the window the owner asked for. Live prod was spared
+ * only by accident: both seeds omit `idleMs` entirely, so the store's own default
+ * applied. A second constant that must equal a first is a drift waiting for a reader
+ * who trusts the comment; there is now only one number.
+ */
+export const DEFAULT_SEED_IDLE_MS = DEFAULT_IDLE_MS;
+/**
+ * `password` → the record an app can be seeded with.
+ *
+ * Returns the parsed record; {@link serializeMasterLockSeed} is what turns it
+ * into the env value, because that step has its own trap (see below).
+ */
+export async function mintMasterLockSeed(password, options = {}) {
+    if (password.length < 8) {
+        // Not a policy — a floor. A seed minted from a two-character password would
+        // arm a lock that reads as protection and is not.
+        throw new Error("master-lock password must be at least 8 characters");
+    }
+    const kdf = options.kdf ?? newMasterLockKdfParams();
+    const verifier = await deriveMasterLockVerifier(password, kdf);
+    return {
+        kdf,
+        verifierHash: await Bun.password.hash(verifier, { algorithm: "argon2id" }),
+        idleMs: options.idleMs ?? DEFAULT_SEED_IDLE_MS,
+    };
+}
+/**
+ * The record as it belongs in a 0600 `.env` file.
+ *
+ * 🔴 **SINGLE-QUOTED, and this is not cosmetic.** An argon2id PHC string contains
+ * `$`, the file is sourced by a shell, and an unquoted value therefore arrives at
+ * the app with `$argon2id` expanded to nothing. `readRecord` strips exactly this
+ * quote pair — `apps/collections` shipped a *doubly*-quoted hash to prod on
+ * 2026-08-12 and spent a day being told its correct passphrase was wrong, which
+ * is why the strip is on the whole blob rather than on the field.
+ */
+export function serializeMasterLockSeed(record) {
+    return `'${JSON.stringify(record)}'`;
+}
+/**
+ * A password worth typing into a stage: unambiguous, and long enough that the
+ * hostname being on the internet behind Cloudflare Access is not the only thing
+ * protecting it.
+ *
+ * No `l`, `1`, `O` or `0` — a stage password gets read out of a terminal and
+ * typed into a browser by hand, and this is the one place where that matters.
+ */
+export function generateStagePassword(words = 4) {
+    const alphabet = "abcdefghijkmnpqrstuvwxyzACDEFGHJKLMNPQRSTUVWXYZ23456789";
+    const bytes = new Uint8Array(words * 5);
+    crypto.getRandomValues(bytes);
+    const chunks = [];
+    for (let w = 0; w < words; w += 1) {
+        let chunk = "";
+        for (let i = 0; i < 5; i += 1) {
+            chunk += alphabet[bytes[w * 5 + i] % alphabet.length];
+        }
+        chunks.push(chunk);
+    }
+    return chunks.join("-");
+}

package/dist/server/master-lock/store.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Two ways to keep the record, so no app has to invent a third.
+ *
+ * The record is one JSON blob on purpose: every app that will ever mount this already has
+ * somewhere to put a string under a key — binary-server's `settings` table, a satellite's
+ * `app_settings`, a `Map` in a test. Asking for a whole table would be asking each adopter
+ * to write a migration for three fields.
+ */
+import type { MasterLockStore } from "./masterLock";
+/** The default key, so two apps' rows look the same when somebody goes looking. */
+export declare const MASTER_LOCK_SETTING_KEY = "master_lock:record";
+/** Wrap an app's existing key/value settings surface. */
+export declare function createKvMasterLockStore(kv: {
+    get(key: string): string | null | undefined;
+    set(key: string, value: string): void;
+}, key?: string): MasterLockStore;
+/** For tests, and for a runtime with nowhere to persist — where it means the lock re-seeds
+ *  from the environment on every boot, which is the correct fallback rather than a failure. */
+export declare function createMemoryMasterLockStore(initial?: string | null): MasterLockStore;

package/dist/server/master-lock/store.js

@@ -0,0 +1,20 @@
+/** The default key, so two apps' rows look the same when somebody goes looking. */
+export const MASTER_LOCK_SETTING_KEY = "master_lock:record";
+/** Wrap an app's existing key/value settings surface. */
+export function createKvMasterLockStore(kv, key = MASTER_LOCK_SETTING_KEY) {
+    return {
+        read: () => kv.get(key) ?? null,
+        write: (json) => kv.set(key, json),
+    };
+}
+/** For tests, and for a runtime with nowhere to persist — where it means the lock re-seeds
+ *  from the environment on every boot, which is the correct fallback rather than a failure. */
+export function createMemoryMasterLockStore(initial) {
+    let value = initial ?? null;
+    return {
+        read: () => value,
+        write: (json) => {
+            value = json;
+        },
+    };
+}

package/dist/server/media-bun/image.d.ts

@@ -0,0 +1,7 @@
+import { type ImagePipelineSpec } from 'cursedbelt-core/media';
+/**
+ * Render an `ImagePipelineSpec` to an encoded image buffer. Operations are applied in
+ * order; `compress` overrides the output quality; `format-convert` is a no-op marker
+ * (the output format does the conversion). Throws on an invalid spec (before sharp).
+ */
+export declare function renderImage(spec: ImagePipelineSpec): Promise<Buffer>;

package/dist/server/media-bun/image.js

@@ -0,0 +1,96 @@
+// Image rendering via sharp. sharp is an OPTIONAL peer dep, imported LAZILY inside
+// renderImage so merely importing `cursedbelt-server` never loads the native binary
+// — only an app that actually renders an image pays for it. The transforms are driven
+// by the media-core `ImagePipelineSpec`; `remove-bg` runs the pure media-core BFS on
+// sharp's raw RGBA buffer, then re-wraps the result.
+import { assertValidImagePipelineSpec, clampQuality, floodFillBGS, } from 'cursedbelt-core/media';
+let sharpPromise = null;
+/** Lazily import sharp once; a clear error if the optional peer isn't installed. */
+async function loadSharp() {
+    if (!sharpPromise) {
+        sharpPromise = import('sharp')
+            .then((m) => m.default)
+            .catch((err) => {
+            sharpPromise = null;
+            throw new Error(`cursedbelt media: 'sharp' is required for renderImage but could not be loaded. ` +
+                `Install it in the app (it is an optional peer dependency). Cause: ${err instanceof Error ? err.message : String(err)}`);
+        });
+    }
+    return sharpPromise;
+}
+/** Run a sharp pipeline to a fresh, transparent RGBA buffer, BFS it, re-wrap it. */
+async function applyRemoveBg(sharp, img, op) {
+    const { data, info } = await img.ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+    const out = floodFillBGS(new Uint8Array(data.buffer, data.byteOffset, data.byteLength), {
+        width: info.width,
+        height: info.height,
+        channels: 4,
+        tolerance: op.tolerance,
+    });
+    return sharp(Buffer.from(out.buffer, out.byteOffset, out.byteLength), {
+        raw: { width: info.width, height: info.height, channels: 4 },
+    });
+}
+function applyResize(img, op) {
+    return img.resize({
+        width: op.width,
+        height: op.height,
+        fit: op.fit ?? 'cover',
+        withoutEnlargement: false,
+    });
+}
+/**
+ * Render an `ImagePipelineSpec` to an encoded image buffer. Operations are applied in
+ * order; `compress` overrides the output quality; `format-convert` is a no-op marker
+ * (the output format does the conversion). Throws on an invalid spec (before sharp).
+ */
+export async function renderImage(spec) {
+    assertValidImagePipelineSpec(spec);
+    const sharp = await loadSharp();
+    const source = typeof spec.input === 'string'
+        ? spec.input
+        : Buffer.from(spec.input.buffer, spec.input.byteOffset, spec.input.byteLength);
+    // `failOn: 'none'` keeps a slightly-truncated upload from hard-failing the pipeline.
+    let img = sharp(source, { failOn: 'none' });
+    let quality = spec.output.quality;
+    for (const op of spec.operations) {
+        switch (op.type) {
+            case 'resize':
+                img = applyResize(img, op);
+                break;
+            case 'crop':
+                img = img.extract({ left: op.left, top: op.top, width: op.width, height: op.height });
+                break;
+            case 'rotate':
+                // Default background transparent so a non-90° rotate doesn't fill with black.
+                img = img.rotate(op.angle, { background: { r: 0, g: 0, b: 0, alpha: 0 } });
+                break;
+            case 'flip':
+                img = op.direction === 'vertical' ? img.flip() : img.flop();
+                break;
+            case 'remove-bg':
+                img = await applyRemoveBg(sharp, img, op);
+                break;
+            case 'compress':
+                quality = op.quality;
+                break;
+            case 'format-convert':
+                break;
+        }
+    }
+    return encode(img, spec.output.format, quality);
+}
+function encode(img, format, quality) {
+    const q = clampQuality(quality);
+    switch (format) {
+        case 'jpeg':
+            return img.jpeg({ quality: q, mozjpeg: true }).toBuffer();
+        case 'png':
+            // PNG is lossless; map quality → effort/compression for a size/CPU trade-off.
+            return img.png({ compressionLevel: 9 }).toBuffer();
+        case 'webp':
+            return img.webp({ quality: q }).toBuffer();
+        case 'avif':
+            return img.avif({ quality: q }).toBuffer();
+    }
+}

package/dist/server/media-bun/index.d.ts

@@ -0,0 +1,4 @@
+export { buildProbeArgs, buildThumbnailArgs, buildTrimArgs, ffmpegTimeToSeconds, type ProbeResult, parseFfmpegProgress, parseFfprobe, type VideoCodecPlan, videoCodecPlan, } from 'cursedbelt-core/media/ffmpeg';
+export { renderImage } from './image';
+export { aacWebAudioArgs, buildFrameJpegArgs, buildSpriteVtt, buildStreamProbeArgs, canStreamCopy, EMPTY_PROBE, FASTSTART, faststartArgs, h264WebVideoArgs, hlsLadderArgs, imageThumbnailArgs, LIBRARY_CRF, LIBRARY_SCALE, parseProgressMicros, parseStreamProbe, planSprite, posterArgs, resolveLadder, type SpritePlan, spriteArgs, type VideoProbe, } from './streaming';
+export { extractFrameJpeg, extractThumbnail, isFfmpegAvailable, isFfprobeAvailable, probeMedia, probeVideoStream, runFfmpegProgress, trimVideo, } from './video';

package/dist/server/media-bun/index.js

@@ -0,0 +1,10 @@
+// src/server/media-bun — the Bun server adapter, re-exported from `cursedbelt-server`, for the media-core
+// specs: image rendering via sharp (lazy/optional), video trim + probe + thumbnail
+// via native ffmpeg/ffprobe. App handlers keep auth, FsNode lookup, quota, and
+// storeFile; this owns the actual pixel/codec work.
+export { buildProbeArgs, buildThumbnailArgs, buildTrimArgs, ffmpegTimeToSeconds, parseFfmpegProgress, parseFfprobe, videoCodecPlan, } from 'cursedbelt-core/media/ffmpeg';
+export { renderImage } from './image';
+// Streaming pipeline: faststart remux, HLS adaptive-bitrate ladder, scrub sprite + WebVTT,
+// poster, codec-aware probe — pure builders/parsers (testable without ffmpeg).
+export { aacWebAudioArgs, buildFrameJpegArgs, buildSpriteVtt, buildStreamProbeArgs, canStreamCopy, EMPTY_PROBE, FASTSTART, faststartArgs, h264WebVideoArgs, hlsLadderArgs, imageThumbnailArgs, LIBRARY_CRF, LIBRARY_SCALE, parseProgressMicros, parseStreamProbe, planSprite, posterArgs, resolveLadder, spriteArgs, } from './streaming';
+export { extractFrameJpeg, extractThumbnail, isFfmpegAvailable, isFfprobeAvailable, probeMedia, probeVideoStream, runFfmpegProgress, trimVideo, } from './video';

package/dist/server/media-bun/streaming.d.ts

@@ -0,0 +1,86 @@
+export declare const h264WebVideoArgs: (crf: string) => string[];
+export declare const aacWebAudioArgs: (bitrate: string) => string[];
+/** Move the moov atom to the front so playback can start before the full download. */
+export declare const FASTSTART: string[];
+/** Cap the long edge at ~1080p, keep aspect, force even dimensions (yuv420p needs even). */
+export declare const LIBRARY_SCALE = "scale='min(1920,iw)':'-2'";
+/** Higher quality than ephemeral Moments (28) — this output is retained. */
+export declare const LIBRARY_CRF = "23";
+export interface VideoProbe {
+    duration: number;
+    width: number;
+    height: number;
+    vcodec: string;
+    acodec: string;
+    pixfmt: string;
+    hasAudio: boolean;
+}
+export declare const EMPTY_PROBE: VideoProbe;
+/** ffprobe argv: one call for everything the pipeline decides on (codecs + dims + duration). */
+export declare const buildStreamProbeArgs: (filePath: string) => string[];
+interface StreamProbeJson {
+    format?: {
+        duration?: string;
+    };
+    streams?: Array<{
+        codec_type?: string;
+        codec_name?: string;
+        width?: number;
+        height?: number;
+        pix_fmt?: string;
+    }>;
+}
+/** Parse the `buildStreamProbeArgs` JSON into a {@link VideoProbe}. */
+export declare const parseStreamProbe: (json: StreamProbeJson) => VideoProbe;
+export declare const canStreamCopy: (p: VideoProbe, maxWidth?: number) => boolean;
+export declare const faststartArgs: (inPath: string, outPath: string, opts: {
+    copy: boolean;
+    crf?: number;
+}) => string[];
+/**
+ * Parse one ffmpeg `-progress pipe:1` line into elapsed microseconds, or null if the line
+ * carries no out_time. `runFfmpegProgress` turns a stream of these into a 0..99 percent.
+ */
+export declare const parseProgressMicros: (line: string) => number | null;
+/** Drop unknown/too-tall rungs (never upscale); always keep at least the source-or-720 rung. */
+export declare const resolveLadder: (heights: number[], sourceHeight: number) => number[];
+/**
+ * Build the HLS multi-rendition transcode. `outDir/<height>/` subdirs must already exist.
+ * Emits master.m3u8 + per-rung playlist.m3u8 + mpegts segments, variants NAMED by height
+ * so storage keys read `…/720/seg_00001.ts` rather than an opaque index.
+ */
+export declare const hlsLadderArgs: (inPath: string, outDir: string, opts: {
+    heights: number[];
+    crf: number;
+    hasAudio: boolean;
+    keyInfoFile?: string;
+}) => string[];
+/** Poster: a frame `atSeconds` in (default ~1s, to skip black intros), scaled to the library
+ *  width, as JPEG. Pass a smaller seek (or 0) for very short clips — seeking past EOF yields no
+ *  frame and the extract fails, so callers that know the duration should clamp `atSeconds`. */
+export declare const posterArgs: (inPath: string, outPath: string, atSeconds?: number) => string[];
+/** Decode a still image to a width-capped JPEG thumbnail. The fallback for formats sharp's
+ *  prebuilt binary can't decode — notably HEIC/HEVC (iPhone photos), which the licensed-out
+ *  libheif build rejects but ffmpeg's hevc decoder handles. `-update 1` writes the single frame
+ *  to a fixed filename (no image-sequence pattern); height rounds to even (`-2`) for the encoder. */
+export declare const imageThumbnailArgs: (inPath: string, outPath: string, maxWidth?: number) => string[];
+/** ffmpeg argv to grab one scaled JPEG frame at `atSeconds` on stdout (`-ss` before `-i`
+ *  fast-seeks — instant on a faststart file). The spawn runner reads pipe:1. */
+export declare const buildFrameJpegArgs: (filePath: string, atSeconds: number, maxWidth?: number) => string[];
+export interface SpritePlan {
+    effInterval: number;
+    count: number;
+    cols: number;
+    rows: number;
+    thumbW: number;
+    thumbH: number;
+}
+/** Sheet geometry: sample every `interval`s, widening it so a long video still fits one sheet. */
+export declare const planSprite: (duration: number, interval: number, srcW: number, srcH: number) => SpritePlan;
+export declare const spriteArgs: (inPath: string, outPath: string, plan: SpritePlan) => string[];
+/**
+ * WebVTT thumbnail track: one cue per tile pointing at a `#xywh` media fragment of the sheet.
+ * The sprite URL is relative (default "sprites.jpg") so it resolves against the VTT's own route.
+ */
+export declare const buildSpriteVtt: (plan: SpritePlan, spriteName?: string) => string;
+export {};