videobook 0.0.0-stage → 0.1.0

package/dist/ffmpeg.js

@@ -0,0 +1,425 @@
+import { execFile, spawn } from "node:child_process";
+import { promisify } from "node:util";
+import * as fsp from "node:fs/promises";
+import { logger } from "./logger.js";
+import { FFMPEG } from "./ffmpeg-binary.js";
+import { FFPROBE } from "./ffprobe-binary.js";
+export { FFMPEG, FFPROBE };
+const execFileAsync = promisify(execFile);
+const DEFAULT_FFMPEG_TIMEOUT_MS = 30 * 60_000;
+const DEFAULT_FFPROBE_TIMEOUT_MS = 2 * 60_000;
+export const H264_MEDIUM = ["-c:v", "libx264", "-preset", "medium", "-crf", "23", "-profile:v", "high", "-level:v", "4.0", "-pix_fmt", "yuv420p"];
+// `-ac 2` downmixes any source to stereo. The native `aac` encoder rejects
+// >2-channel layouts (e.g. 5.1 sources fail with "Unsupported channel layout
+// '6 channels'"), and stereo is the right delivery format for videocity's
+// web/social targets anyway.
+export const AUDIO_OPTS = ["-c:a", "aac", "-b:a", "192k", "-ac", "2"];
+function rationalValue(value) {
+    if (typeof value !== "string")
+        return null;
+    const [numerator, denominator] = value.split("/").map(Number);
+    if (!Number.isFinite(numerator) || !Number.isFinite(denominator) || denominator === 0)
+        return null;
+    return numerator / denominator;
+}
+function rationalParts(value, separator = "/") {
+    if (typeof value !== "string")
+        return null;
+    const parts = value.split(separator);
+    if (parts.length !== 2)
+        return null;
+    const numerator = Number(parts[0]);
+    const denominator = Number(parts[1]);
+    if (!Number.isSafeInteger(numerator)
+        || !Number.isSafeInteger(denominator)
+        || numerator <= 0
+        || denominator <= 0)
+        return null;
+    return { numerator, denominator };
+}
+function durationTicks(stream, timeBase, fallbackSeconds) {
+    const direct = Number(stream.duration_ts);
+    if (Number.isSafeInteger(direct) && direct > 0)
+        return direct;
+    return Math.max(1, Math.round(fallbackSeconds * timeBase.denominator / timeBase.numerator));
+}
+function rotationDegrees(stream) {
+    const sideData = Array.isArray(stream.side_data_list)
+        ? stream.side_data_list
+        : [];
+    const sideRotation = sideData
+        .map((entry) => Number(entry.rotation))
+        .find(Number.isFinite);
+    const tags = typeof stream.tags === "object" && stream.tags !== null
+        ? stream.tags
+        : {};
+    const taggedRotation = Number(tags.rotate);
+    return Math.round(sideRotation ?? (Number.isFinite(taggedRotation) ? taggedRotation : 0));
+}
+function videoProbeStream(stream, fallbackSeconds) {
+    if (!stream)
+        return null;
+    const timeBase = rationalParts(stream.time_base) ?? { numerator: 1, denominator: 1_000 };
+    const nominalFrameRate = rationalParts(stream.r_frame_rate);
+    const averageFrameRate = rationalParts(stream.avg_frame_rate);
+    return {
+        index: Number.isSafeInteger(Number(stream.index)) ? Number(stream.index) : 0,
+        timeBase,
+        durationTicks: durationTicks(stream, timeBase, fallbackSeconds),
+        codec: typeof stream.codec_name === "string" ? stream.codec_name : "unknown",
+        video: {
+            width: Math.max(1, Number(stream.width) || 1),
+            height: Math.max(1, Number(stream.height) || 1),
+            rotationDegrees: rotationDegrees(stream),
+            pixelAspect: rationalParts(stream.sample_aspect_ratio, ":")
+                ?? { numerator: 1, denominator: 1 },
+            ...(nominalFrameRate ? { nominalFrameRate } : {}),
+            ...(averageFrameRate ? { averageFrameRate } : {}),
+        },
+    };
+}
+function audioProbeStream(stream, fallbackSeconds) {
+    if (!stream)
+        return null;
+    const sampleRateHz = Math.max(1, Number(stream.sample_rate) || 48_000);
+    const timeBase = rationalParts(stream.time_base)
+        ?? { numerator: 1, denominator: sampleRateHz };
+    const channels = Math.max(1, Number(stream.channels) || 1);
+    const channelLayout = typeof stream.channel_layout === "string"
+        ? stream.channel_layout
+        : channels === 1 ? "mono" : channels === 2 ? "stereo" : `${channels} channels`;
+    return {
+        index: Number.isSafeInteger(Number(stream.index)) ? Number(stream.index) : 0,
+        timeBase,
+        durationTicks: durationTicks(stream, timeBase, fallbackSeconds),
+        codec: typeof stream.codec_name === "string" ? stream.codec_name : "unknown",
+        audio: { sampleRateHz, channels, channelLayout },
+    };
+}
+function taggedDuration(value) {
+    if (typeof value !== "string")
+        return null;
+    const match = /^(\d+):(\d+):(\d+(?:\.\d+)?)$/.exec(value);
+    if (!match)
+        return null;
+    return Number(match[1]) * 3600 + Number(match[2]) * 60 + Number(match[3]);
+}
+function streamDuration(stream, fallback) {
+    if (!stream)
+        return 0;
+    const direct = Number(stream.duration);
+    if (Number.isFinite(direct) && direct > 0)
+        return direct;
+    const durationTs = Number(stream.duration_ts);
+    const timeBase = rationalValue(stream.time_base);
+    if (Number.isFinite(durationTs) && timeBase !== null && durationTs * timeBase > 0) {
+        return durationTs * timeBase;
+    }
+    const tags = typeof stream.tags === "object" && stream.tags !== null
+        ? stream.tags
+        : undefined;
+    const tagged = taggedDuration(tags?.DURATION ?? tags?.duration);
+    return tagged !== null && tagged > 0 ? tagged : fallback;
+}
+function interruptionMessage(processName, error, options, timeoutMs) {
+    if (options.signal?.aborted) {
+        const reason = options.signal.reason;
+        const detail = reason instanceof Error ? reason.message : String(reason ?? "aborted");
+        return `${processName} cancelled: ${detail}`;
+    }
+    const processError = error;
+    if (processError.killed && processError.signal) {
+        return `${processName} timed out after ${timeoutMs}ms`;
+    }
+    return null;
+}
+export async function probeVideo(filePath, options = {}) {
+    let stdout;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_FFPROBE_TIMEOUT_MS;
+    try {
+        const result = await execFileAsync(FFPROBE, [
+            "-hide_banner",
+            "-v", "error",
+            "-print_format", "json",
+            "-show_streams",
+            "-show_format",
+            filePath,
+        ], {
+            encoding: "utf8",
+            killSignal: "SIGKILL",
+            signal: options.signal,
+            timeout: timeoutMs,
+        });
+        stdout = result.stdout;
+    }
+    catch (error) {
+        const interruption = interruptionMessage("ffprobe", error, options, timeoutMs);
+        if (interruption)
+            throw new Error(`${interruption} for ${filePath}`);
+        const e = error;
+        const stderr = typeof e.stderr === "string" ? e.stderr : e.stderr?.toString() ?? "";
+        const exit = e.code !== undefined ? String(e.code) : "?";
+        let size = "missing";
+        try {
+            const { size: bytes } = await fsp.stat(filePath);
+            size = `${bytes} bytes`;
+        }
+        catch { /* file gone */ }
+        throw new Error(`ffprobe failed for ${filePath} (exit ${exit}, ${size}): ${stderr.trim() || e.message}`);
+    }
+    const data = JSON.parse(stdout);
+    const videoStream = data.streams?.find((s) => s.codec_type === "video");
+    const width = Number(videoStream?.width ?? 0);
+    const height = Number(videoStream?.height ?? 0);
+    const duration = Number(data.format?.duration ?? 0);
+    const videoDuration = streamDuration(videoStream, duration);
+    let fps = 30;
+    const rFrameRate = videoStream?.r_frame_rate;
+    if (typeof rFrameRate === "string" && rFrameRate.includes("/")) {
+        const [num, den] = rFrameRate.split("/").map(Number);
+        if (den > 0)
+            fps = num / den;
+    }
+    const avgFps = rationalValue(videoStream?.avg_frame_rate);
+    const audioStream = data.streams?.find((s) => s.codec_type === "audio");
+    const hasAudio = audioStream !== undefined;
+    const audioDuration = audioStream ? streamDuration(audioStream, duration) : null;
+    const videoCodec = typeof videoStream?.codec_name === "string" ? videoStream.codec_name : null;
+    const audioCodec = typeof audioStream?.codec_name === "string" ? audioStream.codec_name : null;
+    return {
+        width,
+        height,
+        duration,
+        videoDuration,
+        audioDuration,
+        fps,
+        avgFps,
+        hasAudio,
+        videoCodec,
+        audioCodec,
+        videoStream: videoProbeStream(videoStream, videoDuration),
+        audioStream: audioProbeStream(audioStream, audioDuration ?? duration),
+    };
+}
+export function summarizeFfmpegStderr(stderr, maxChars = 600) {
+    const lines = stderr.split("\n").map((l) => l.trimEnd()).filter(Boolean);
+    const meaningful = lines.filter((l) => {
+        if (/^ffmpeg version /.test(l))
+            return false;
+        if (/^\s*built with /.test(l))
+            return false;
+        if (/^\s*configuration:/.test(l))
+            return false;
+        if (/^\s*lib\w+\s+\d/.test(l))
+            return false;
+        if (/^(frame|size)=/.test(l))
+            return false;
+        return true;
+    });
+    const tail = meaningful.slice(-15).join("\n");
+    if (tail.length <= maxChars)
+        return tail;
+    if (maxChars <= 0)
+        return "";
+    const truncationMarker = "\n...\n";
+    if (maxChars <= truncationMarker.length)
+        return tail.slice(0, maxChars);
+    const availableChars = maxChars - truncationMarker.length;
+    const headChars = Math.ceil(availableChars / 2);
+    const tailChars = availableChars - headChars;
+    const suffix = tailChars > 0 ? tail.slice(-tailChars) : "";
+    return `${tail.slice(0, headChars)}${truncationMarker}${suffix}`;
+}
+export function withQuietFfmpegArgs(args) {
+    const hasLoglevel = args.includes("-loglevel") || args.includes("-v");
+    const hasHideBanner = args.includes("-hide_banner");
+    const prefix = [];
+    if (!hasHideBanner)
+        prefix.push("-hide_banner");
+    if (!hasLoglevel)
+        prefix.push("-loglevel", "error");
+    return prefix.length === 0 ? args : [...prefix, ...args];
+}
+export async function runFfmpeg(args, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_FFMPEG_TIMEOUT_MS;
+    try {
+        await execFileAsync(FFMPEG, withQuietFfmpegArgs(args), {
+            encoding: "utf8",
+            killSignal: "SIGKILL",
+            signal: options.signal,
+            timeout: timeoutMs,
+        });
+    }
+    catch (error) {
+        const interruption = interruptionMessage("ffmpeg", error, options, timeoutMs);
+        if (interruption)
+            throw new Error(interruption);
+        const stderrRaw = error instanceof Error ? error.stderr : undefined;
+        const fallback = error instanceof Error ? error.message : String(error);
+        const summary = stderrRaw ? summarizeFfmpegStderr(stderrRaw) : "";
+        throw new Error(`ffmpeg failed: ${summary || fallback}`);
+    }
+}
+let _FFmpeggy = null;
+const SAMPLE_RATE = 8000;
+// Fine-grained RMS accumulators (~768 KB). We fold these in halves as audio
+// streams in, so memory stays constant regardless of clip length — see
+// extractWaveform.
+const WAVEFORM_FINE_BUCKETS = 1 << 16;
+/**
+ * Streams an asset's decoded audio and folds it into a bounded set of RMS
+ * accumulators, returning `barCount` normalised peaks (0..1).
+ *
+ * The earlier implementation buffered the entire PCM stream via execFile with a
+ * 50 MB `maxBuffer`. A video whose audio decoded to more than ~52 minutes of
+ * 8 kHz mono s16le overflowed that cap; ffmpeg was killed mid-stream, the error
+ * was swallowed, and an empty waveform came back — which never cached and so
+ * re-ran the multi-second decode on every poll. Streaming removes the cap (and
+ * the failure mode) entirely: memory is O(WAVEFORM_FINE_BUCKETS), not
+ * O(duration).
+ */
+export async function extractWaveform(videoPath, barCount, streamIndex, signal) {
+    signal?.throwIfAborted();
+    const sumSq = new Float64Array(WAVEFORM_FINE_BUCKETS);
+    const count = new Int32Array(WAVEFORM_FINE_BUCKETS);
+    let samplesPerBucket = 1;
+    let writeIdx = 0;
+    let inBucket = 0;
+    let totalSamples = 0;
+    // Halve resolution in place when the buckets fill: merge each adjacent pair,
+    // double the samples-per-bucket, and resume writing at the midpoint. This
+    // caps the accumulators at WAVEFORM_FINE_BUCKETS for any clip length.
+    const foldPairs = () => {
+        const half = WAVEFORM_FINE_BUCKETS >> 1;
+        for (let i = 0; i < half; i++) {
+            sumSq[i] = sumSq[2 * i] + sumSq[2 * i + 1];
+            count[i] = count[2 * i] + count[2 * i + 1];
+        }
+        sumSq.fill(0, half);
+        count.fill(0, half);
+        samplesPerBucket *= 2;
+        writeIdx = half;
+    };
+    const addSample = (sample) => {
+        sumSq[writeIdx] += sample * sample;
+        inBucket++;
+        totalSamples++;
+        if (inBucket === samplesPerBucket) {
+            count[writeIdx] = inBucket;
+            writeIdx++;
+            inBucket = 0;
+            if (writeIdx === WAVEFORM_FINE_BUCKETS)
+                foldPairs();
+        }
+    };
+    try {
+        await new Promise((resolve, reject) => {
+            const child = spawn(FFMPEG, withQuietFfmpegArgs([
+                "-i", videoPath, "-map", streamIndex === undefined ? "0:a:0" : `0:${streamIndex}`, "-vn", "-ac", "1", "-ar", String(SAMPLE_RATE), "-f", "s16le", "pipe:1",
+            ]), { stdio: ["ignore", "pipe", "pipe"] });
+            const abort = () => child.kill("SIGTERM");
+            signal?.addEventListener("abort", abort, { once: true });
+            if (signal?.aborted)
+                abort();
+            let carry = -1; // a single low byte left over when a chunk splits a sample
+            child.stdout.on("data", (chunk) => {
+                let offset = 0;
+                if (carry !== -1 && chunk.length > 0) {
+                    addSample((((carry | (chunk[0] << 8)) << 16) >> 16)); // sign-extend 16-bit LE
+                    offset = 1;
+                    carry = -1;
+                }
+                const usableBytes = chunk.length - offset;
+                const end = offset + usableBytes - (usableBytes & 1);
+                for (let i = offset; i < end; i += 2)
+                    addSample(chunk.readInt16LE(i));
+                carry = usableBytes & 1 ? chunk[chunk.length - 1] : -1;
+            });
+            child.stderr.resume();
+            child.on("error", reject);
+            child.on("close", (code) => {
+                signal?.removeEventListener("abort", abort);
+                // No samples means no decodable audio (no audio stream, or a decode
+                // error). Surface it once, but return empty rather than rejecting so a
+                // genuinely silent clip caches as "no waveform" instead of churning.
+                if (totalSamples === 0 && code !== 0) {
+                    logger.warn("waveform-empty", { exitCode: code });
+                }
+                resolve();
+            });
+        });
+        signal?.throwIfAborted();
+        if (totalSamples === 0)
+            return [];
+        if (inBucket > 0)
+            count[writeIdx++] = inBucket; // finalise the partial bucket
+        const usedBuckets = writeIdx;
+        // Default: 100 bars per second of audio (0.01s resolution), clamped 20..1000.
+        if (barCount === undefined) {
+            const durationSec = totalSamples / SAMPLE_RATE;
+            barCount = Math.max(20, Math.min(1000, Math.round(durationSec * 100)));
+        }
+        barCount = Math.min(barCount, usedBuckets);
+        // True RMS per bar: sum the squared energy and sample counts across the
+        // fine buckets the bar spans, then take the root-mean-square.
+        const peaks = new Array(barCount);
+        for (let b = 0; b < barCount; b++) {
+            const start = Math.floor((b * usedBuckets) / barCount);
+            const stop = Math.max(start + 1, Math.floor(((b + 1) * usedBuckets) / barCount));
+            let energy = 0;
+            let samples = 0;
+            for (let i = start; i < stop && i < usedBuckets; i++) {
+                energy += sumSq[i];
+                samples += count[i];
+            }
+            peaks[b] = samples > 0 ? Math.sqrt(energy / samples) : 0;
+        }
+        const max = Math.max(...peaks, 1);
+        return peaks.map((p) => p / max);
+    }
+    catch (err) {
+        signal?.throwIfAborted();
+        // Only reached if ffmpeg fails to spawn (e.g. binary missing). The stream
+        // never buffers, so the old maxBuffer failure mode can't recur here.
+        logger.error("waveform-failed", { error: err });
+        return [];
+    }
+}
+export async function isThumbnailBlank(imagePath) {
+    try {
+        const { stdout } = await execFileAsync(FFMPEG, withQuietFfmpegArgs([
+            "-i", imagePath,
+            "-vf", "format=gray",
+            "-f", "rawvideo",
+            "-pix_fmt", "gray",
+            "pipe:1",
+        ]), { encoding: "buffer", maxBuffer: 10 * 1024 * 1024 });
+        const buf = stdout;
+        if (buf.length === 0)
+            return true;
+        let sum = 0;
+        for (let i = 0; i < buf.length; i++)
+            sum += buf[i];
+        const mean = sum / buf.length;
+        let variance = 0;
+        for (let i = 0; i < buf.length; i++) {
+            const diff = buf[i] - mean;
+            variance += diff * diff;
+        }
+        const stddev = Math.sqrt(variance / buf.length);
+        // Near-black or uniform solid color
+        return mean < 10 || stddev < 5;
+    }
+    catch {
+        return false;
+    }
+}
+export async function getFFmpeggy() {
+    if (!_FFmpeggy) {
+        const mod = await import("ffmpeggy");
+        _FFmpeggy = mod.FFmpeggy;
+        _FFmpeggy.DefaultConfig.ffmpegBin = FFMPEG;
+        _FFmpeggy.DefaultConfig.ffprobeBin = FFPROBE;
+    }
+    return _FFmpeggy;
+}

package/dist/ffprobe-binary.js

@@ -0,0 +1,55 @@
+import { closeSync, openSync, readSync } from "node:fs";
+import { createRequire } from "node:module";
+const MACH_O_64_MAGIC_LE = 0xfeedfacf;
+const FAT_MAGIC_BE = 0xcafebabe;
+const CPU_TYPE_X86_64 = 0x01000007;
+const CPU_TYPE_ARM64 = 0x0100000c;
+/** Reads the CPU type from a Mach-O header; null when it is not Mach-O. */
+export function machOArch(header) {
+    if (header.length < 8)
+        return null;
+    const view = new DataView(header.buffer, header.byteOffset, header.byteLength);
+    if (view.getUint32(0, false) === FAT_MAGIC_BE)
+        return "universal";
+    if (view.getUint32(0, true) !== MACH_O_64_MAGIC_LE)
+        return null;
+    const cpuType = view.getUint32(4, true);
+    if (cpuType === CPU_TYPE_ARM64)
+        return "arm64";
+    if (cpuType === CPU_TYPE_X86_64)
+        return "x64";
+    return "other";
+}
+/** Whether a binary with this header can run on the host CPU. */
+export function binaryRunsOnHost(header, hostArch) {
+    const arch = machOArch(header);
+    return arch === null || arch === "universal" || arch === hostArch;
+}
+export function readBinaryHeader(path) {
+    try {
+        const fd = openSync(path, "r");
+        try {
+            const header = new Uint8Array(8);
+            return readSync(fd, header, 0, 8, 0) === 8 ? header : null;
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * ffprobe-static ships an x86_64 build under darwin/arm64, which cannot spawn
+ * on Apple Silicon without Rosetta. An explicit override wins; otherwise the
+ * bundled binary is used only when its CPU matches, else `ffprobe` on PATH.
+ */
+export function resolveFfprobePath(bundledPath, override, hostArch) {
+    if (override)
+        return override;
+    const header = readBinaryHeader(bundledPath);
+    return header && binaryRunsOnHost(header, hostArch) ? bundledPath : "ffprobe";
+}
+const require = createRequire(import.meta.url);
+export const FFPROBE = resolveFfprobePath(require("ffprobe-static").path, process.env.VIDEOBOOK_FFPROBE_PATH, process.arch);

package/dist/forget-asset.js

@@ -0,0 +1,216 @@
+import { markDescendantsStale } from "./notebook-action-catalog.js";
+import { mutateNotebook } from "./notebook-mutations.js";
+import { removeArtifactFromTimeline } from "./tools/delete-asset.js";
+const CELL_INPUT_ARTIFACT_KEYS = [
+    "firstFrameArtifactId",
+    "lastFrameArtifactId",
+    "providerArtifactId",
+];
+function isString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function inputVersionIds(inputs) {
+    return Array.isArray(inputs.outputVersionArtifactIds)
+        ? inputs.outputVersionArtifactIds.filter(isString)
+        : [];
+}
+function cellHoldsArtifact(cell, artifactId) {
+    const inputs = cell.inputs ?? {};
+    return cell.outputArtifactId === artifactId
+        || (cell.references ?? []).some((reference) => reference.targetId === artifactId)
+        || (cell.pinnedResults ?? []).some((pinned) => pinned.artifactId === artifactId)
+        || CELL_INPUT_ARTIFACT_KEYS.some((key) => inputs[key] === artifactId)
+        || inputVersionIds(inputs).includes(artifactId);
+}
+function detachedInputs(cell, artifactId) {
+    const inputs = { ...(cell.inputs ?? {}) };
+    for (const key of CELL_INPUT_ARTIFACT_KEYS) {
+        if (inputs[key] === artifactId)
+            delete inputs[key];
+    }
+    if (Array.isArray(inputs.outputVersionArtifactIds)) {
+        inputs.outputVersionArtifactIds = inputVersionIds(inputs)
+            .filter((id) => id !== artifactId);
+    }
+    if (cell.outputArtifactId === artifactId)
+        inputs.state = "ready";
+    return inputs;
+}
+function detachedCell(cell, artifactId) {
+    const references = (cell.references ?? [])
+        .filter((reference) => reference.targetId !== artifactId);
+    const pinnedResults = (cell.pinnedResults ?? [])
+        .filter((pinned) => pinned.artifactId !== artifactId);
+    return {
+        ...cell,
+        ...(cell.outputArtifactId === artifactId ? { outputArtifactId: undefined } : {}),
+        inputs: detachedInputs(cell, artifactId),
+        ...(cell.references ? { references } : {}),
+        ...(cell.pinnedResults ? { pinnedResults } : {}),
+    };
+}
+/** A cleared cell reads as never run, so a re-run refills it. */
+function detachedExecution(document, cellIds) {
+    const execution = { ...(document.execution ?? {}) };
+    for (const cellId of cellIds) {
+        const current = execution[cellId];
+        if (!current || typeof current !== "object")
+            continue;
+        execution[cellId] = {
+            ...current,
+            status: "ready",
+            stale: false,
+            outputArtifactId: undefined,
+            providerArtifactId: undefined,
+            error: undefined,
+        };
+    }
+    return execution;
+}
+function detachedDocument(document, artifactId) {
+    const cellIds = document.cells
+        .filter((cell) => cellHoldsArtifact(cell, artifactId))
+        .map((cell) => cell.id);
+    if (cellIds.length === 0)
+        return { document, cellIds };
+    const detached = {
+        ...document,
+        cells: document.cells.map((cell) => cellIds.includes(cell.id) ? detachedCell(cell, artifactId) : cell),
+        execution: detachedExecution(document, cellIds),
+    };
+    return {
+        document: cellIds.reduce((next, cellId) => markDescendantsStale(next, cellId), detached),
+        cellIds,
+    };
+}
+async function detachFromNotebooks(engine, artifactId) {
+    let cleared = 0;
+    for (const notebook of engine.notebooks.list()) {
+        if (!notebook.cells.some((cell) => cellHoldsArtifact(cell, artifactId))) {
+            continue;
+        }
+        let cellIds = [];
+        const result = await mutateNotebook(engine, notebook.id, "forget_asset", (document) => {
+            const detached = detachedDocument(document, artifactId);
+            cellIds = detached.cellIds;
+            return detached.document;
+        }, { artifactId }, { artifactId });
+        if (!result.ok)
+            throw new Error(result.error.message);
+        cleared += cellIds.length;
+    }
+    return cleared;
+}
+function referencesOf(details) {
+    const references = details?.references;
+    if (!Array.isArray(references))
+        return [];
+    return references.flatMap((entry) => {
+        if (typeof entry !== "object" || entry === null)
+            return [];
+        const row = entry;
+        return isString(row.kind) && isString(row.id)
+            ? [{ kind: row.kind, id: row.id }]
+            : [];
+    });
+}
+function remainingForgetReferences(engine, artifactId) {
+    const references = engine.artifacts.deletionReferences(artifactId, { deleteOwnedMedia: true });
+    if (!references.ok)
+        throw new Error(references.error.message);
+    const clearable = new Set(engine.sequences.getPrimary().clips
+        .filter((clip) => clip.source.artifactId === artifactId).map((clip) => `sequenceClip:${clip.clipId}`));
+    for (const notebook of engine.notebooks.list()) {
+        for (const cell of notebook.cells) {
+            const cellId = `${notebook.id}/${cell.id}`;
+            if (cell.outputArtifactId === artifactId)
+                clearable.add(`cell.outputArtifact:${cellId}`);
+            for (const reference of cell.references ?? []) {
+                if (reference.targetId === artifactId)
+                    clearable.add(`cell.reference:${cellId}/${reference.id}`);
+            }
+            for (const result of cell.pinnedResults ?? []) {
+                if (result.artifactId === artifactId)
+                    clearable.add(`pinnedSearchResult:${cellId}/${result.id}`);
+            }
+        }
+    }
+    return references.value.filter((reference) => !clearable.has(`${reference.kind}:${reference.id}`));
+}
+function inUseOutcome(artifactId, label, references, clearedCells = 0) {
+    return { status: "in_use", artifactId, label, references, clearedCells,
+        forgottenObjects: 0, sharedObjects: 0, reclaimedBytes: 0 };
+}
+/**
+ * Deletes an artifact and destroys the bytes behind it.
+ *
+ * `engine.artifacts.delete` clears the catalog rows and the workspace copy,
+ * but the content objects survive — that is what makes a duplicate import
+ * free and an old revision restorable. Forgetting finishes the job through
+ * `storage.deleteObject`, which is left unforced on purpose: an object another
+ * artifact still references is kept, so forgetting one copy of shared bytes
+ * never blanks the other.
+ */
+export async function forgetAsset(engine, input) {
+    const artifact = engine.artifacts.get(input.assetId);
+    if (!artifact.ok)
+        throw new Error(artifact.error.message);
+    const artifactId = artifact.value.artifactId;
+    const label = artifact.value.label ?? null;
+    if (input.clearReferences) {
+        const blockers = remainingForgetReferences(engine, artifactId);
+        if (blockers.length > 0)
+            return inUseOutcome(artifactId, label, blockers);
+        const timeline = await removeArtifactFromTimeline(engine, artifactId, { dryRun: true });
+        if (timeline.error)
+            throw new Error(timeline.error);
+    }
+    const manifest = await engine.files.manifest(artifactId, { includeDotfiles: true });
+    const hashes = [...new Set(manifest.ok ? manifest.value.files.map((file) => file.objectHash) : [])];
+    const clearedCells = input.clearReferences
+        ? await detachFromNotebooks(engine, artifactId)
+        : 0;
+    if (input.clearReferences) {
+        const timeline = await removeArtifactFromTimeline(engine, artifactId);
+        if (timeline.error)
+            throw new Error(timeline.error);
+    }
+    const deleted = await engine.artifacts.delete(artifactId, {
+        deleteOwnedMedia: true,
+    });
+    if (!deleted.ok) {
+        if (deleted.error.code !== "IN_USE")
+            throw new Error(deleted.error.message);
+        return inUseOutcome(artifactId, label, referencesOf(deleted.error.details), clearedCells);
+    }
+    let forgottenObjects = 0;
+    let sharedObjects = 0;
+    let reclaimedBytes = 0;
+    for (const hash of hashes) {
+        const result = await engine.storage.deleteObject(hash);
+        if (result.ok) {
+            forgottenObjects += 1;
+            if (result.value.deletedLocal)
+                reclaimedBytes += result.value.sizeBytes;
+            continue;
+        }
+        // Bytes another artifact stores, or an object row that never existed.
+        if (result.error.code === "IN_USE") {
+            sharedObjects += 1;
+            continue;
+        }
+        if (result.error.code === "NOT_FOUND")
+            continue;
+        throw new Error(result.error.message);
+    }
+    return {
+        status: "forgotten",
+        artifactId,
+        label,
+        references: [],
+        clearedCells,
+        forgottenObjects,
+        sharedObjects,
+        reclaimedBytes,
+    };
+}