videobook 0.0.0-stage → 0.2.0

package/dist/jobs/render-timeline.js

@@ -0,0 +1,283 @@
+import { join } from "node:path";
+import { mkdir, mkdtemp, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { logger } from "../logger.js";
+import { registerJobHandler } from "../queue.js";
+import { runFfmpeg, probeVideo, AUDIO_OPTS, H264_MEDIUM } from "../ffmpeg.js";
+import { withLockedLocalLease } from "./_lease.js";
+import { ingestWorkspaceOutputs } from "./_persist-output.js";
+const LOCK_DURATION_MS = 1_800_000;
+const LANDSCAPE_RENDER = "landscape.mp4";
+const PORTRAIT_RENDER = "portrait.mp4";
+const SQUARE_RENDER = "square.mp4";
+const LANDSCAPE_OUTPUT = "timeline_landscape.mp4";
+const PORTRAIT_OUTPUT = "timeline_portrait.mp4";
+const SQUARE_OUTPUT = "timeline_square.mp4";
+export function buildAudioFilter(index, slot, duration, hasAudio = true) {
+    const filters = ["aresample=48000", "aformat=sample_fmts=fltp:channel_layouts=stereo"];
+    const vol = slot.volume / 100;
+    if (vol !== 1) {
+        filters.push(`volume=${vol}`);
+    }
+    const fadeInSec = slot.fadeIn / 1000;
+    if (fadeInSec > 0) {
+        filters.push(`afade=t=in:d=${fadeInSec}`);
+    }
+    const fadeOutSec = slot.fadeOut / 1000;
+    if (fadeOutSec > 0) {
+        const startTime = Math.max(0, duration - fadeOutSec);
+        filters.push(`afade=t=out:st=${startTime}:d=${fadeOutSec}`);
+    }
+    if (hasAudio) {
+        return `[${index}:a:0]${filters.join(",")}[a${index}]`;
+    }
+    return `anullsrc=channel_layout=stereo:sample_rate=48000,atrim=0:${duration},asetpts=PTS-STARTPTS,${filters.join(",")}[a${index}]`;
+}
+// A CFR file's measured average rate matches its nominal rate almost exactly;
+// anything beyond this gap means uneven frame timestamps (VFR).
+const VFR_TOLERANCE_FPS = 0.1;
+const FALLBACK_FPS = 30;
+/**
+ * Decide whether the timeline concat can stream-copy video. Stream-copying
+ * splices packets without touching timestamps, so it is only safe when every
+ * input is h264 at the same resolution and the same constant frame rate.
+ * Anything else (mixed fps across slots, a VFR input, a stray codec) must be
+ * re-encoded to one constant frame rate — otherwise the concatenated output
+ * carries uneven timestamps that turn into visible skipping once platforms
+ * like X transcode it assuming CFR.
+ */
+export function planTimelineVideo(probes) {
+    const first = probes[0];
+    const uniformFps = probes.every((p) => Math.round(p.fps) === Math.round(first.fps));
+    const reasons = [];
+    if (probes.some((p) => p.videoCodec !== "h264"))
+        reasons.push("non-h264 input");
+    if (!uniformFps)
+        reasons.push("mixed frame rates");
+    if (probes.some((p) => p.width !== first.width || p.height !== first.height)) {
+        reasons.push("mixed resolutions");
+    }
+    if (probes.some((p) => p.avgFps !== null && Math.abs(p.avgFps - p.fps) > VFR_TOLERANCE_FPS)) {
+        reasons.push("variable frame rate input");
+    }
+    if (reasons.length === 0)
+        return { mode: "copy" };
+    return {
+        mode: "reencode",
+        targetFps: uniformFps ? Math.round(first.fps) || FALLBACK_FPS : FALLBACK_FPS,
+        width: first.width,
+        height: first.height,
+        reasons,
+    };
+}
+function buildReencodeVideoFilter(index, plan) {
+    const { targetFps, width, height } = plan;
+    return (`[${index}:v:0]fps=${targetFps},` +
+        `scale=${width}:${height}:force_original_aspect_ratio=decrease,` +
+        `pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2,setsar=1,format=yuv420p[v${index}]`);
+}
+/**
+ * ffmpeg args for the re-encode path: each slot is its own input, video is
+ * normalized to one CFR rate/resolution and concatenated via the concat
+ * filter alongside the per-slot audio chains.
+ */
+export function buildReencodeArgs(opts) {
+    const { inputPaths, resolvedSlots, durations, hasAudioFlags, resolvedAudio, plan, outputPath } = opts;
+    const n = inputPaths.length;
+    const hasOverlays = resolvedAudio.length > 0;
+    const args = [];
+    for (const p of inputPaths)
+        args.push("-i", p);
+    for (const overlay of resolvedAudio)
+        args.push("-i", overlay.audioPath);
+    const filterParts = [];
+    for (let i = 0; i < n; i++) {
+        filterParts.push(buildReencodeVideoFilter(i, plan));
+        filterParts.push(buildAudioFilter(i, resolvedSlots[i], durations[i], hasAudioFlags[i]));
+    }
+    const concatInputs = Array.from({ length: n }, (_, i) => `[v${i}][a${i}]`).join("");
+    const concatAudioLabel = hasOverlays ? "[concatA]" : "[outa]";
+    filterParts.push(`${concatInputs}concat=n=${n}:v=1:a=1[outv]${concatAudioLabel}`);
+    if (hasOverlays) {
+        const overlayLabels = [];
+        resolvedAudio.forEach((overlay, k) => {
+            const label = `ov${k}`;
+            overlayLabels.push(`[${label}]`);
+            filterParts.push(buildOverlayAudioFilter(n + k, overlay, label));
+        });
+        const mixCount = 1 + overlayLabels.length;
+        filterParts.push(`[concatA]${overlayLabels.join("")}amix=inputs=${mixCount}:duration=first:dropout_transition=0:normalize=0,aresample=48000,aformat=sample_fmts=fltp:channel_layouts=stereo[outa]`);
+    }
+    args.push("-filter_complex", filterParts.join(";"), "-map", "[outv]", ...H264_MEDIUM, "-pix_fmt", "yuv420p", "-map", "[outa]", ...AUDIO_OPTS, "-movflags", "+faststart", "-y", outputPath);
+    return args;
+}
+function buildOverlayAudioFilter(inputIndex, overlay, label) {
+    const filters = ["aresample=48000", "aformat=sample_fmts=fltp:channel_layouts=stereo"];
+    const durationSec = overlay.durationMs / 1000;
+    if (durationSec > 0) {
+        filters.push(`atrim=0:${durationSec}`);
+    }
+    if (overlay.startMs > 0) {
+        filters.push(`adelay=${overlay.startMs}|${overlay.startMs}`);
+    }
+    if (overlay.volume !== 1) {
+        filters.push(`volume=${overlay.volume}`);
+    }
+    const fadeInSec = overlay.fadeInMs / 1000;
+    if (fadeInSec > 0) {
+        filters.push(`afade=t=in:st=${overlay.startMs / 1000}:d=${fadeInSec}`);
+    }
+    const fadeOutSec = overlay.fadeOutMs / 1000;
+    if (fadeOutSec > 0) {
+        const fadeOutStart = Math.max(0, (overlay.startMs + overlay.durationMs) / 1000 - fadeOutSec);
+        filters.push(`afade=t=out:st=${fadeOutStart}:d=${fadeOutSec}`);
+    }
+    return `[${inputIndex}:a:0]${filters.join(",")}[${label}]`;
+}
+/**
+ * Fast path: video stream-copied via the concat demuxer. Only valid when
+ * planTimelineVideo() returned "copy" (uniform CFR h264 inputs). Audio is
+ * stream-copied too unless a slot deviates from default volume/fades or
+ * overlay clips must be mixed in.
+ */
+async function runCopyConcat(opts) {
+    const { inputPaths, resolvedSlots, durations, hasAudioFlags, resolvedAudio, outputPath, signal } = opts;
+    const n = resolvedSlots.length;
+    const needsSlotAudioFilter = resolvedSlots.some((s) => s.volume !== 100 || s.fadeIn > 0 || s.fadeOut > 0);
+    const hasOverlays = resolvedAudio.length > 0;
+    const needsAudioFilter = needsSlotAudioFilter || hasOverlays;
+    const concatListDir = await mkdtemp(join(tmpdir(), "videocity-concat-"));
+    const concatListPath = join(concatListDir, "list.txt");
+    try {
+        // concat demuxer list: one `file '<path>'` per line, single-quotes
+        // escaped by `'\''`.
+        const listBody = inputPaths
+            .map((p) => `file '${p.replace(/'/g, "'\\''")}'`)
+            .join("\n");
+        await writeFile(concatListPath, listBody + "\n", "utf8");
+        const ffmpegArgs = ["-f", "concat", "-safe", "0", "-i", concatListPath];
+        if (needsAudioFilter) {
+            // Re-open each slot as its own input so we can apply per-slot audio
+            // filters, then concat the audio streams. Video comes from input 0
+            // (the concat demuxer) and is stream-copied.
+            for (const p of inputPaths) {
+                ffmpegArgs.push("-i", p);
+            }
+            for (const overlay of resolvedAudio) {
+                ffmpegArgs.push("-i", overlay.audioPath);
+            }
+            const filterParts = [];
+            for (let i = 0; i < n; i++) {
+                // Input indices for the per-slot reopens start at 1.
+                filterParts.push(buildAudioFilter(i + 1, resolvedSlots[i], durations[i], hasAudioFlags[i]));
+            }
+            const concatInputs = Array.from({ length: n }, (_, i) => `[a${i + 1}]`).join("");
+            const concatLabel = hasOverlays ? "[concatA]" : "[outa]";
+            filterParts.push(`${concatInputs}concat=n=${n}:v=0:a=1${concatLabel}`);
+            if (hasOverlays) {
+                const overlayBaseIndex = 1 + n;
+                const overlayLabels = [];
+                resolvedAudio.forEach((overlay, k) => {
+                    const label = `ov${k}`;
+                    overlayLabels.push(`[${label}]`);
+                    filterParts.push(buildOverlayAudioFilter(overlayBaseIndex + k, overlay, label));
+                });
+                const mixInputs = `[concatA]${overlayLabels.join("")}`;
+                const mixCount = 1 + overlayLabels.length;
+                filterParts.push(`${mixInputs}amix=inputs=${mixCount}:duration=first:dropout_transition=0:normalize=0,aresample=48000,aformat=sample_fmts=fltp:channel_layouts=stereo[outa]`);
+            }
+            ffmpegArgs.push("-filter_complex", filterParts.join(";"), "-map", "0:v:0", "-c:v", "copy", "-map", "[outa]", ...AUDIO_OPTS);
+        }
+        else {
+            // No audio adjustments: stream-copy both tracks.
+            ffmpegArgs.push("-map", "0:v:0", "-map", "0:a:0?", "-c", "copy");
+        }
+        ffmpegArgs.push("-movflags", "+faststart", "-y", outputPath);
+        await runFfmpeg(ffmpegArgs, { signal });
+    }
+    finally {
+        await rm(concatListDir, { recursive: true, force: true });
+    }
+}
+export function registerRenderTimelineJob(engine) {
+    registerJobHandler("render_timeline", async (payload, ctx) => {
+        ctx.signal.throwIfAborted();
+        const { bookId, orientation, resolvedSlots, resolvedAudio = [], } = payload;
+        const existingFinal = engine.artifacts.list().find((artifact) => artifact.kind === "final" && artifact.label === "final");
+        const finalResult = existingFinal !== undefined
+            ? { ok: true, value: existingFinal }
+            : await engine.artifacts.create({ kind: "final", label: "final" });
+        if (!finalResult.ok)
+            throw new Error(finalResult.error.message);
+        const finalId = finalResult.value.artifactId;
+        const finalDir = finalResult.value.path;
+        await mkdir(finalDir, { recursive: true });
+        return withLockedLocalLease(engine, finalId, finalDir, ctx, "final", { durationMs: LOCK_DURATION_MS }, async () => {
+            const renderFilename = orientation === "portrait" ? PORTRAIT_RENDER : orientation === "square" ? SQUARE_RENDER : LANDSCAPE_RENDER;
+            const outputFilename = orientation === "portrait" ? PORTRAIT_OUTPUT : orientation === "square" ? SQUARE_OUTPUT : LANDSCAPE_OUTPUT;
+            const outputPath = join(finalDir, outputFilename);
+            const inputPaths = [];
+            const durations = [];
+            const hasAudioFlags = [];
+            const videoProbes = [];
+            for (const slot of resolvedSlots) {
+                ctx.signal.throwIfAborted();
+                const inputPath = join(slot.assetDir, renderFilename);
+                inputPaths.push(inputPath);
+                const probe = await probeVideo(inputPath, { signal: ctx.signal });
+                durations.push(probe.duration);
+                hasAudioFlags.push(probe.hasAudio);
+                videoProbes.push({
+                    fps: probe.fps,
+                    avgFps: probe.avgFps,
+                    width: probe.width,
+                    height: probe.height,
+                    videoCodec: probe.videoCodec,
+                });
+            }
+            const n = resolvedSlots.length;
+            // Slot renders normally share codec/resolution/fps (same Remotion
+            // pipeline), in which case video is stream-copied via the concat
+            // demuxer. But /render keeps each source clip's native frame rate, so
+            // a timeline mixing e.g. 24fps generated clips with 30fps footage —
+            // or containing any VFR input — must be re-encoded to one constant
+            // frame rate, or the spliced timestamps stutter after platforms
+            // (X, etc.) transcode the upload assuming CFR.
+            const plan = planTimelineVideo(videoProbes);
+            if (plan.mode === "reencode") {
+                logger.warn("timeline-reencode", { bookId, targetFps: plan.targetFps, count: plan.reasons.length });
+                await runFfmpeg(buildReencodeArgs({
+                    inputPaths,
+                    resolvedSlots,
+                    durations,
+                    hasAudioFlags,
+                    resolvedAudio,
+                    plan,
+                    outputPath,
+                }), { signal: ctx.signal });
+            }
+            else {
+                await runCopyConcat({
+                    inputPaths,
+                    resolvedSlots,
+                    durations,
+                    hasAudioFlags,
+                    resolvedAudio,
+                    outputPath,
+                    signal: ctx.signal,
+                });
+            }
+            const thumbPath = join(finalDir, "original.jpg");
+            await runFfmpeg(["-y", "-i", outputPath, "-frames:v", "1", "-q:v", "2", thumbPath], { signal: ctx.signal });
+            await ingestWorkspaceOutputs(engine, finalId, [outputFilename, "original.jpg"], "render_timeline", { orientation, slotCount: n });
+            const renderMeta = {
+                slotCount: n,
+                slots: resolvedSlots.map((s) => s.artifactId),
+                output: outputFilename,
+                renderedAt: new Date().toISOString(),
+            };
+            await engine.metadata.artifacts.write(finalId, `${orientation}.render`, renderMeta);
+            return { success: true, output: outputFilename };
+        }, { durationMs: LOCK_DURATION_MS });
+    });
+}

package/dist/jobs/repair-search-indexes.js

@@ -0,0 +1,42 @@
+import { buildAssetList } from "../tools/reconcile-project-work.js";
+import { missingVisualIndexes } from "../search-index-coverage.js";
+import { registerLocalClipSearchProvider } from "../local-search-models.js";
+import { registerJobHandler } from "../queue.js";
+import { runSemanticIndex } from "./semantic-index.js";
+export function registerRepairSearchIndexesJob(engine) {
+    registerJobHandler("repair_search_indexes", (payload, context) => repairSearchIndexes(engine, Array.isArray(payload.kinds) ? payload.kinds : ["image", "video"], context));
+}
+export function repairSearchIndexes(engine, requestedKinds, context) {
+    return engine.withLocalMedia(async () => {
+        context.signal.throwIfAborted();
+        const kinds = new Set(requestedKinds);
+        const assets = (await buildAssetList(engine, engine.book.get().bookId, "newest"))
+            .filter((asset) => kinds.has(asset.type === "final" ? "video" : asset.type));
+        const missing = missingVisualIndexes(engine, assets);
+        const result = { indexed: 0, failed: 0, failures: [] };
+        if (missing.length === 0)
+            return result;
+        await registerLocalClipSearchProvider(engine).prepare({ signal: context.signal });
+        for (const asset of missing) {
+            context.signal.throwIfAborted();
+            try {
+                const indexed = await runSemanticIndex(engine, {
+                    type: "semantic_index", assetId: asset.artifact_id, bookId: engine.book.get().bookId, prepareVisualMedia: true, visualOnly: true,
+                }, context);
+                if (indexed.semanticVisual !== "ready" || missingVisualIndexes(engine, [asset]).length > 0) {
+                    throw new Error("Visual indexing is incomplete. Check the source media and prepare the local search models before retrying.");
+                }
+                result.indexed += 1;
+            }
+            catch (error) {
+                context.signal.throwIfAborted();
+                result.failed += 1;
+                if (result.failures.length < 10)
+                    result.failures.push({
+                        artifactId: asset.artifact_id, message: error instanceof Error ? error.message : String(error),
+                    });
+            }
+        }
+        return result;
+    });
+}

package/dist/jobs/replace-video-audio.js

@@ -0,0 +1,64 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, basename } from "node:path";
+import { registerJobHandler, queue } from "../queue.js";
+import { AUDIO_OPTS, probeVideo, runFfmpeg } from "../ffmpeg.js";
+import { withLockedLocalLease } from "./_lease.js";
+import { replaceArtifactFileFromPath } from "./_persist-output.js";
+const LOCK_DURATION_MS = 300_000;
+const STALE_ANALYSIS_FILES = [
+    ".original.analysis.json",
+    ".analysis.gpt4otrans.json",
+    "elevenlabs.json",
+];
+export function registerReplaceVideoAudioJob(engine) {
+    registerJobHandler("replace_video_audio", async (payload, ctx) => {
+        const { inputPath, audioPath, assetId, assetDir, audioAssetId, bookId, extraProvenance, } = payload;
+        const result = await withLockedLocalLease(engine, assetId, assetDir, ctx, "replace_audio", { durationMs: LOCK_DURATION_MS, data: { state: "replacing-audio" } }, async () => {
+            const inputFilename = basename(inputPath);
+            const source = await probeVideo(inputPath, { signal: ctx.signal });
+            if (!source.videoStream || source.videoDuration <= 0)
+                throw new Error("Video source has no playable video stream");
+            const workspace = await mkdtemp(join(tmpdir(), "videobook-replace-audio-"));
+            const outputPath = join(workspace, "output.mp4");
+            try {
+                await runFfmpeg([
+                    "-y", "-i", inputPath, "-i", audioPath,
+                    "-map", "0:v:0", "-map", "1:a:0", "-c:v", "copy",
+                    "-af", `apad,atrim=duration=${source.videoDuration},asetpts=PTS-STARTPTS`,
+                    ...AUDIO_OPTS, "-movflags", "+faststart", outputPath,
+                ], { signal: ctx.signal });
+                const output = await probeVideo(outputPath, { signal: ctx.signal });
+                const tolerance = Math.max(1 / (source.fps || 30), 0.05);
+                if (!output.hasAudio || Math.abs(output.videoDuration - source.videoDuration) > tolerance
+                    || Math.abs((output.audioDuration ?? output.duration) - source.videoDuration) > tolerance) {
+                    throw new Error("Replacement audio output does not preserve the video duration");
+                }
+                await replaceArtifactFileFromPath(engine, assetId, inputFilename, outputPath);
+            }
+            finally {
+                await rm(workspace, { recursive: true, force: true });
+            }
+            for (const stale of STALE_ANALYSIS_FILES) {
+                await engine.files.delete(assetId, stale);
+            }
+            const videoPath = join(assetDir, inputFilename);
+            return { videoPath };
+        }, { durationMs: LOCK_DURATION_MS, waitForActiveMs: 30_000 });
+        await queue.enqueue(`process-video-${assetId}-${Date.now()}`, {
+            type: "process_video",
+            videoPath: result.videoPath,
+            assetId,
+            assetDir,
+            bookId,
+            provenance: {
+                ...(extraProvenance ?? {}),
+                origin: "replace_audio",
+                source_audio: audioAssetId,
+                replaced_at: new Date().toISOString(),
+            },
+            force: true,
+        });
+        return { success: true };
+    });
+}

package/dist/jobs/restore-archive-clip.js

@@ -0,0 +1,53 @@
+import { join } from "node:path";
+import { getArchiveStore } from "../archive-store.js";
+import { queue, registerJobHandler } from "../queue.js";
+import { withLockedLocalLease } from "./_lease.js";
+const LOCK_DURATION_MS = 10 * 60_000;
+function provenance(payload) {
+    return {
+        origin: "archive",
+        archive_id: payload.archiveId,
+        title: payload.title ?? "",
+        topics: payload.topics ?? [],
+        people: payload.people ?? [],
+        restored_at: new Date().toISOString(),
+    };
+}
+export function registerRestoreArchiveClipJob(engine) {
+    registerJobHandler("restore_archive_clip", async (payload, ctx) => {
+        const p = payload;
+        return withLockedLocalLease(engine, p.assetId, p.assetDir, ctx, "download", { durationMs: LOCK_DURATION_MS, data: { state: "downloading" } }, async () => {
+            const store = getArchiveStore();
+            const body = await store.getBytes(p.mediaKey);
+            if (!body)
+                throw new Error(`Archive media not found: ${p.mediaKey}`);
+            const write = await engine.files.write(p.assetId, p.filename, Buffer.from(body));
+            if (!write.ok)
+                throw new Error(write.error.message);
+            const meta = provenance(p);
+            if (p.mediaKind === "video") {
+                const processJobId = `process-video-${p.assetId}-${Date.now()}`;
+                await queue.enqueue(processJobId, {
+                    type: "process_video",
+                    videoPath: join(p.assetDir, p.filename),
+                    assetId: p.assetId,
+                    assetDir: p.assetDir,
+                    bookId: p.bookId,
+                    provenance: meta,
+                });
+                return { success: true, archive_id: p.archiveId, asset_id: p.assetId, job_id: processJobId };
+            }
+            const processJobId = `process-audio-${p.assetId}-${Date.now()}`;
+            await queue.enqueue(processJobId, {
+                type: "process_audio",
+                audioPath: join(p.assetDir, p.filename),
+                sourceFilename: p.filename,
+                assetId: p.assetId,
+                assetDir: p.assetDir,
+                bookId: p.bookId,
+                provenance: { ...meta, content_type: p.contentType },
+            });
+            return { success: true, archive_id: p.archiveId, asset_id: p.assetId, job_id: processJobId };
+        }, { durationMs: LOCK_DURATION_MS });
+    });
+}

package/dist/jobs/reverse-video.js

@@ -0,0 +1,53 @@
+import { basename, join } from "node:path";
+import { registerJobHandler, queue } from "../queue.js";
+import { getFFmpeggy, H264_MEDIUM, AUDIO_OPTS } from "../ffmpeg.js";
+import { withLockedLocalLease } from "./_lease.js";
+import { replaceArtifactFileFromPath } from "./_persist-output.js";
+const LOCK_DURATION_MS = 300_000;
+function buildReverseOutputOptions(hasAudio) {
+    const opts = ["-vf", "reverse"];
+    if (hasAudio) {
+        opts.push("-af", "areverse");
+    }
+    else {
+        opts.push("-an");
+    }
+    opts.push(...H264_MEDIUM, ...AUDIO_OPTS);
+    return opts;
+}
+export function registerReverseVideoJob(engine) {
+    registerJobHandler("reverse_video", async (payload, ctx) => {
+        const { inputPath, outputPath, hasAudio, assetId, assetDir, bookId, } = payload;
+        const result = await withLockedLocalLease(engine, assetId, assetDir, ctx, "reverse", { durationMs: LOCK_DURATION_MS, data: { state: "reversing" } }, async () => {
+            const outputOptions = buildReverseOutputOptions(hasAudio);
+            const FFmpeggy = await getFFmpeggy();
+            const ff = new FFmpeggy({
+                input: inputPath,
+                output: outputPath,
+                outputOptions,
+                overwriteExisting: true,
+            });
+            await ff.run();
+            await ff.done();
+            const inputFilename = basename(inputPath);
+            await replaceArtifactFileFromPath(engine, assetId, inputFilename, outputPath);
+            const videoPath = join(assetDir, inputFilename);
+            return { videoPath };
+        }, { durationMs: LOCK_DURATION_MS, waitForActiveMs: 30_000 });
+        await queue.enqueue(`process-video-${assetId}-${Date.now()}`, {
+            type: "process_video",
+            videoPath: result.videoPath,
+            assetId,
+            assetDir,
+            bookId,
+            provenance: {
+                origin: "reverse",
+                source_asset_id: assetId,
+                reversed_at: new Date().toISOString(),
+            },
+            force: true,
+            skipDownstreamJobs: true,
+        });
+        return { success: true };
+    });
+}

package/dist/jobs/rewrite-script.js

@@ -0,0 +1,173 @@
+import { registerJobHandler } from "../queue.js";
+import { requireApiKey } from "../api-key.js";
+import { INTELLIGENCE_MODEL, buildIntelligenceResponses, firstResponseText, intelligenceRequest, } from "../openai-intelligence.js";
+import { withLocalLease } from "./_lease.js";
+import { formatMarkdown, PROMPT_CHAR_LIMIT, SCRIPT_FILENAME, } from "./describe-image.js";
+import { platformGuidance } from "../platform-guidance.js";
+const FIELD_LABEL_TO_KEY = {
+    Shot: "shot",
+    Pose: "pose",
+};
+const FULL_REWRITE_JSON_SCHEMA = {
+    type: "object",
+    required: ["prompt", "shot", "pose"],
+    additionalProperties: false,
+    properties: {
+        prompt: { type: "string" },
+        shot: { anyOf: [{ type: "string" }, { type: "null" }] },
+        pose: { anyOf: [{ type: "string" }, { type: "null" }] },
+    },
+};
+const TLDR_REWRITE_JSON_SCHEMA = {
+    type: "object",
+    required: ["prompt"],
+    additionalProperties: false,
+    properties: {
+        prompt: { type: "string" },
+    },
+};
+function parseMarkdownToResult(md) {
+    const lines = md.split("\n");
+    const promptLines = [];
+    let i = 0;
+    while (i < lines.length && lines[i].trim() !== "") {
+        promptLines.push(lines[i]);
+        i++;
+    }
+    const result = { prompt: promptLines.join("\n").trim() };
+    while (i < lines.length && lines[i].trim() === "")
+        i++;
+    for (; i < lines.length; i++) {
+        const line = lines[i];
+        const match = line.match(/^([A-Z][a-z]+):\s*(.+)$/);
+        if (!match)
+            continue;
+        const key = FIELD_LABEL_TO_KEY[match[1]];
+        if (key)
+            result[key] = match[2].trim();
+    }
+    return result;
+}
+function buildFullSystemPrompt(platform) {
+    const platformBlock = platform ? `\n\n--- PLATFORM ---\n${platformGuidance(platform)}\n--- END PLATFORM ---` : "";
+    return ("You rewrite image-reproduction prompt documents. The input describes one scene, split into a prose " +
+        "prompt paragraph and two labeled breakdown fields (Shot, Pose). You apply a user transformation and " +
+        "emit a rewritten document in the same JSON shape.\n\n" +
+        "Return ONLY a JSON object with keys: prompt (string, REQUIRED), shot (string or null), pose (string or " +
+        "null). Use null when an optional field is absent from the input. The shot field is shot size + camera " +
+        "angle in standard cinematography terms (e.g. 'medium close-up, eye-level'). The pose field describes " +
+        "body geometry only (weight, stance, rotation, limb positions); for close-ups, also describe implied " +
+        "off-frame posture in one trailing sentence. The pose field must not mention clothing, hair, face, or " +
+        "setting. No prose outside the JSON. No markdown fences.\n\n" +
+        `HARD LIMIT: the "prompt" field MUST be ${PROMPT_CHAR_LIMIT} characters or fewer.\n\n` +
+        "When a transformation instruction is provided, apply it rigorously: any subject being replaced must " +
+        "be ABSENT from every field of the output. Rewrite every field end-to-end so it describes the scene " +
+        "AFTER the transformation. Adapt subject, setting, and mood naturally to the new content; do NOT " +
+        "simply string-replace nouns.\n\n" +
+        "Preserve from the original: framing/angle/shot type, camera distance, lighting direction and time of " +
+        "day, overall capture register (authentic phone snapshot vs editorial), and aspect ratio cues." +
+        platformBlock);
+}
+function buildTldrSystemPrompt(platform) {
+    const platformBlock = platform ? `\n\n--- PLATFORM ---\n${platformGuidance(platform)}\n--- END PLATFORM ---` : "";
+    return ("You rewrite image-reproduction prompt documents into a 1–2 sentence TLDR. The input may be a full " +
+        "document (prose paragraph + labeled fields) or a TLDR already. You emit a tight 1–2 sentence prompt " +
+        "(roughly 40–70 words) capturing subject, setting, framing, light, and mood.\n\n" +
+        "Match the input's register: if it reads as a casual phone/social photo, include authentic-capture cues " +
+        "(mild grain, subtle sensor noise, tiny chromatic aberration, no beauty filter, unedited skin) and AVOID " +
+        "words like 'editorial', 'cinematic', 'masterpiece', or named film stocks (Portra, Cinestill, etc.). " +
+        "Only use film-stock / cinematic vocabulary if the input clearly references a pro editorial or film " +
+        "still. Never apply camera vocabulary to a painting or render.\n\n" +
+        "Return ONLY a JSON object: { \"prompt\": string }. No breakdown fields. No prose outside the JSON. " +
+        "No markdown fences.\n\n" +
+        "When a transformation instruction is provided, apply it rigorously: any subject being replaced must " +
+        "NOT appear in the output. Describe only the scene AFTER the transformation." +
+        platformBlock);
+}
+function buildUserMessage(current, customPrompt) {
+    const parts = [
+        "CURRENT DOCUMENT (JSON):",
+        JSON.stringify(current, null, 2),
+    ];
+    if (customPrompt && customPrompt.trim().length > 0) {
+        parts.push("", "TRANSFORMATION INSTRUCTION (apply this; any subject being replaced must vanish from every field):", customPrompt.trim());
+    }
+    else {
+        parts.push("", "No transformation instruction. Rewrite the document to match any new platform/variant guidance above while preserving the scene content.");
+    }
+    return parts.join("\n");
+}
+async function rewriteText(responses, current, opts, signal) {
+    const system = opts.tldr ? buildTldrSystemPrompt(opts.platform) : buildFullSystemPrompt(opts.platform);
+    const user = buildUserMessage(current, opts.customPrompt);
+    const response = await responses(intelligenceRequest({
+        instructions: system,
+        input: [{ role: "user", content: user }],
+        text: {
+            format: {
+                type: "json_schema",
+                name: opts.tldr ? "rewrite_script_tldr" : "rewrite_script_full",
+                schema: opts.tldr ? TLDR_REWRITE_JSON_SCHEMA : FULL_REWRITE_JSON_SCHEMA,
+                strict: true,
+            },
+        },
+        max_output_tokens: 2048,
+    }), signal);
+    const content = firstResponseText(response);
+    if (!content) {
+        throw new Error(`Rewrite provider returned no content (status=${response.status})`);
+    }
+    const raw = JSON.parse(content);
+    if (!raw.prompt || typeof raw.prompt !== "string") {
+        throw new Error(`Rewrite model returned no prompt field. Got keys: ${Object.keys(raw).join(",")}`);
+    }
+    const parsed = {
+        prompt: raw.prompt,
+        ...(typeof raw.shot === "string" ? { shot: raw.shot } : {}),
+        ...(typeof raw.pose === "string" ? { pose: raw.pose } : {}),
+    };
+    if (parsed.prompt.length > PROMPT_CHAR_LIMIT) {
+        parsed.prompt = parsed.prompt.slice(0, PROMPT_CHAR_LIMIT).trimEnd();
+    }
+    return parsed;
+}
+function formatTldrMarkdown(r) {
+    return `${r.prompt.trim()}\n`;
+}
+export function registerRewriteScriptJob(engine) {
+    registerJobHandler("rewrite_script", async (payload, ctx) => {
+        const { assetId: scriptAssetId, sourceAssetId, tldr, platform, customPrompt, } = payload;
+        return withLocalLease(engine, scriptAssetId, ctx, "rewrite_script", async () => {
+            const responses = buildIntelligenceResponses(requireApiKey("OPENAI_API_KEY"));
+            const readResult = await engine.files.read(scriptAssetId, SCRIPT_FILENAME);
+            if (!readResult.ok) {
+                throw new Error(`Failed to read ${SCRIPT_FILENAME} from ${scriptAssetId}: ${readResult.error.message}`);
+            }
+            const currentMarkdown = Buffer.from(readResult.value).toString("utf-8");
+            const current = parseMarkdownToResult(currentMarkdown);
+            if (!current.prompt) {
+                throw new Error(`Script ${scriptAssetId} has no parseable prompt in ${SCRIPT_FILENAME}`);
+            }
+            const rewritten = await rewriteText(responses, current, {
+                tldr: tldr === true,
+                platform: platform ?? null,
+                customPrompt: customPrompt ?? null,
+            }, ctx.signal);
+            const markdown = tldr ? formatTldrMarkdown(rewritten) : formatMarkdown(rewritten);
+            const writeResult = await engine.files.write(scriptAssetId, SCRIPT_FILENAME, markdown);
+            if (!writeResult.ok) {
+                throw new Error(`Failed to write ${SCRIPT_FILENAME} to ${scriptAssetId}: ${writeResult.error.message}`);
+            }
+            await engine.metadata.artifacts.write(scriptAssetId, "original", {
+                origin: "describe_image",
+                sourceAssetId,
+                model: INTELLIGENCE_MODEL,
+                processed_at: new Date().toISOString(),
+                variant: tldr ? "tldr" : "full",
+                ...(platform ? { platform } : {}),
+                ...(customPrompt ? { customPrompt } : {}),
+            });
+            return { success: true, scriptAssetId, prompt: rewritten.prompt };
+        });
+    });
+}