videobook 0.0.0-stage → 0.2.0

package/dist/tools/create-watermark.js

@@ -0,0 +1,97 @@
+import { z } from "zod";
+import { LIGHTNING_WATERMARK_PROFILE } from "../lightning-defaults.js";
+import { WATERMARK_PLATFORMS } from "../watermark-platform.js";
+import { normalizeHandle, readWatermarkConfig, recordHandle } from "../watermark-config.js";
+import { createWatermarkAsset, DEFAULT_HANDLE_PADDING, DEFAULT_HANDLE_ROUNDING, DEFAULT_HANDLE, defaultUrl, MAX_HANDLE_PADDING, MAX_HANDLE_ROUNDING, MIN_HANDLE_PADDING, MIN_HANDLE_ROUNDING, } from "../watermark-badge.js";
+export function createWatermarkCardDef(engine) {
+    return {
+        name: "create_watermark_card",
+        description: "Make a transparent QR plus X or TikTok handle badge as an image asset, with optional platform icon, border, padding and rounding. Burn it in with apply_watermark.",
+        schema: {
+            book_id: z.string().describe("Book id"),
+            platform: z.enum(WATERMARK_PLATFORMS).optional().describe("Alias platform (default tiktok)"),
+            handle: z.string().optional().describe(`X or TikTok alias without @ (X default: ${DEFAULT_HANDLE}; TikTok default: ${LIGHTNING_WATERMARK_PROFILE.handle})`),
+            url: z.string().optional().describe("URL the QR code resolves to (default: the selected X or TikTok profile URL)"),
+            save_default: z
+                .boolean()
+                .optional()
+                .describe("Remember this handle as the default for future watermarks"),
+            include_platform_icon: z
+                .boolean()
+                .optional()
+                .describe("Show the selected platform icon before the plain alias (default true)"),
+            include_handle_border: z
+                .boolean()
+                .optional()
+                .describe("Draw a border around the handle pill (default true)"),
+            handle_padding: z
+                .number()
+                .int()
+                .min(MIN_HANDLE_PADDING)
+                .max(MAX_HANDLE_PADDING)
+                .optional()
+                .describe(`Horizontal handle padding in reference pixels (default ${DEFAULT_HANDLE_PADDING}; range ${MIN_HANDLE_PADDING}-${MAX_HANDLE_PADDING})`),
+            handle_padding_y: z
+                .number()
+                .int()
+                .min(MIN_HANDLE_PADDING)
+                .max(MAX_HANDLE_PADDING)
+                .optional()
+                .describe(`Vertical handle padding in reference pixels (default ${DEFAULT_HANDLE_PADDING}; range ${MIN_HANDLE_PADDING}-${MAX_HANDLE_PADDING})`),
+            handle_rounding: z
+                .number()
+                .int()
+                .min(MIN_HANDLE_ROUNDING)
+                .max(MAX_HANDLE_ROUNDING)
+                .optional()
+                .describe(`Handle corner rounding percent (default ${DEFAULT_HANDLE_ROUNDING}; range ${MIN_HANDLE_ROUNDING}-${MAX_HANDLE_ROUNDING})`),
+        },
+        handler: async (args) => {
+            const { handle, url, save_default, platform = "tiktok", include_platform_icon = true, include_handle_border = true, handle_padding = platform === "tiktok" ? LIGHTNING_WATERMARK_PROFILE.handlePaddingX : DEFAULT_HANDLE_PADDING, handle_padding_y = platform === "tiktok" ? LIGHTNING_WATERMARK_PROFILE.handlePaddingY : DEFAULT_HANDLE_PADDING, handle_rounding = platform === "tiktok" ? LIGHTNING_WATERMARK_PROFILE.handleRounding : DEFAULT_HANDLE_ROUNDING, } = args;
+            const config = await readWatermarkConfig(engine, platform);
+            const fallbackHandle = platform === "x"
+                ? DEFAULT_HANDLE
+                : config.savedHandle ?? config.recent[0] ?? (platform === "tiktok" ? LIGHTNING_WATERMARK_PROFILE.handle : "");
+            const resolvedHandle = normalizeHandle(handle ?? fallbackHandle);
+            if (!resolvedHandle) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: "handle must be a non-empty string" }],
+                };
+            }
+            const resolvedUrl = url ?? defaultUrl(resolvedHandle, platform);
+            const created = await createWatermarkAsset(engine, resolvedHandle, resolvedUrl, {
+                platform,
+                includePlatformIcon: include_platform_icon,
+                includeHandleBorder: include_handle_border,
+                handlePadding: handle_padding,
+                handlePaddingY: handle_padding_y,
+                handleRounding: handle_rounding,
+            });
+            if (!created.ok) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: created.error }],
+                };
+            }
+            // Remember the handle so the next watermark review defaults to it.
+            await recordHandle(resolvedHandle, { saveDefault: save_default, platform }, engine).catch(() => undefined);
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            asset_id: created.assetId,
+                            handle: resolvedHandle,
+                            url: resolvedUrl,
+                            platform,
+                            include_platform_icon,
+                            include_handle_border,
+                            handle_padding,
+                            handle_padding_y,
+                            handle_rounding,
+                        }),
+                    }],
+            };
+        },
+    };
+}

package/dist/tools/crop-asset.js

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { cropImageDef } from "./crop-image.js";
+import { cropVideoDef } from "./crop-video.js";
+export function cropAssetDef(engine) {
+    const image = cropImageDef(engine);
+    const video = cropVideoDef(engine);
+    return {
+        name: "crop_asset",
+        description: "Crop an image or video in place to a 16:9, 9:16 or 1:1 region given as 0-1 fractions (x, y, w, h), resized to 1920x1080, 1080x1920 or 1080x1080.",
+        schema: { ...image.schema, asset_id: z.string().describe("Image or video artifact id") },
+        handler: async (args) => {
+            const artifact = engine.artifacts.get(String(args.asset_id));
+            if (!artifact.ok)
+                return { isError: true, content: [{ type: "text", text: artifact.error.message }] };
+            return artifact.value.kind === "image" ? image.handler(args) : video.handler(args);
+        },
+    };
+}

package/dist/tools/crop-image.js

@@ -0,0 +1,120 @@
+import { z } from "zod";
+import { extname } from "node:path";
+import { queue } from "../queue.js";
+import { SKIP_CROP_EXTENSIONS } from "../jobs/process-image.js";
+import { cropGeometry } from "../crop-geometry.js";
+import { probeImage } from "../image.js";
+const RECT_EPSILON = 0.001;
+const IMAGE_EXTENSIONS = new Set(["jpg", "jpeg", "png", "webp"]);
+function validateRect(x, y, w, h) {
+    if (w <= 0 || h <= 0)
+        return { error: "Crop width and height must be > 0." };
+    if (x < 0 || y < 0)
+        return { error: "Crop x and y must be >= 0." };
+    if (x + w > 1 + RECT_EPSILON)
+        return { error: `Crop x + w must be <= 1 (got ${x + w}).` };
+    if (y + h > 1 + RECT_EPSILON)
+        return { error: `Crop y + h must be <= 1 (got ${y + h}).` };
+    return null;
+}
+function findOriginalImage(files) {
+    const images = files.filter((f) => {
+        const ext = (f.extension ?? extname(f.name)).replace(/^\./, "").toLowerCase();
+        return IMAGE_EXTENSIONS.has(ext);
+    });
+    // Prefer lossless/true originals when both png and jpg exist (repair cases).
+    const byName = (name) => images.find((f) => f.name === name);
+    return (byName("original.png")
+        ?? byName("original.webp")
+        ?? byName("original.jpg")
+        ?? byName("original.jpeg")
+        ?? images.find((f) => f.name.startsWith("original"))
+        ?? null);
+}
+export function cropImageDef(engine) {
+    return {
+        name: "crop_image",
+        description: "Crop an image in place to a 16:9, 9:16 or 1:1 region given as 0-1 fractions (x, y, w, h), resized to 1920x1080, 1080x1920 or 1080x1080.",
+        schema: {
+            asset_id: z.string().describe("Asset ID (e.g. img-my-photo)"),
+            book_id: z.string().describe("Book id"),
+            ratio: z.enum(["16:9", "9:16", "1:1"]).describe("Target aspect ratio"),
+            x: z.number().min(0).max(1).describe("Crop origin X as fraction of source width (0..1)"),
+            y: z.number().min(0).max(1).describe("Crop origin Y as fraction of source height (0..1)"),
+            w: z.number().min(0).max(1).describe("Crop width as fraction of source width (0..1)"),
+            h: z.number().min(0).max(1).describe("Crop height as fraction of source height (0..1)"),
+        },
+        handler: async (args) => {
+            const { asset_id, book_id, ratio, x, y, w, h } = args;
+            const rectErr = validateRect(x, y, w, h);
+            if (rectErr) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: rectErr.error }],
+                };
+            }
+            const manifestResult = await engine.files.manifest(asset_id);
+            if (!manifestResult.ok) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: manifestResult.error.message }],
+                };
+            }
+            const manifest = manifestResult.value;
+            const imageFile = findOriginalImage(manifest.files);
+            if (!imageFile) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `No original image file found in asset ${asset_id}` }],
+                };
+            }
+            const ext = (imageFile.extension ?? extname(imageFile.name)).toLowerCase();
+            const extWithDot = ext.startsWith(".") ? ext : `.${ext}`;
+            if (SKIP_CROP_EXTENSIONS.has(extWithDot)) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Cannot crop images with extension ${extWithDot}` }],
+                };
+            }
+            const assetDir = manifest.path;
+            try {
+                const original = await engine.files.read(asset_id, imageFile.name);
+                if (!original.ok)
+                    throw new Error(original.error.message);
+                const source = await probeImage(original.value);
+                cropGeometry({ x, y, w, h }, source.width, source.height, ratio, 1);
+            }
+            catch (error) {
+                return { isError: true, content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }] };
+            }
+            const jobId = `crop-${asset_id}-${Date.now()}`;
+            const jobPayload = {
+                type: "crop_image",
+                inputFilename: imageFile.name,
+                ratio,
+                rect: { x, y, w, h },
+                assetId: asset_id,
+                assetDir,
+                bookId: book_id,
+            };
+            try {
+                await queue.enqueueAndWait(jobId, jobPayload);
+            }
+            catch (err) {
+                return {
+                    isError: true,
+                    content: [{
+                            type: "text",
+                            text: `Crop failed: ${err instanceof Error ? err.message : String(err)}`,
+                        }],
+                };
+            }
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({ asset_id, job_id: jobId, ratio, status: "completed" }),
+                    }],
+            };
+        },
+    };
+}

package/dist/tools/crop-video.js

@@ -0,0 +1,97 @@
+import { z } from "zod";
+import { join } from "node:path";
+import { queue } from "../queue.js";
+import { findVideoFile } from "videobook-engine";
+import { cropGeometry } from "../crop-geometry.js";
+import { probeVideo } from "../ffmpeg.js";
+const RECT_EPSILON = 0.001;
+function validateRect(x, y, w, h) {
+    if (w <= 0 || h <= 0)
+        return { error: "Crop width and height must be > 0." };
+    if (x < 0 || y < 0)
+        return { error: "Crop x and y must be >= 0." };
+    if (x + w > 1 + RECT_EPSILON)
+        return { error: `Crop x + w must be <= 1 (got ${x + w}).` };
+    if (y + h > 1 + RECT_EPSILON)
+        return { error: `Crop y + h must be <= 1 (got ${y + h}).` };
+    return null;
+}
+export function cropVideoDef(engine) {
+    return {
+        name: "crop_video",
+        description: "Crop a video asset to a 16:9, 9:16, or 1:1 region. Coordinates are normalized fractions of the source frame (0..1). Re-renders in place to canonical dims (1920x1080 / 1080x1920 / 1080x1080) with git versioning.",
+        schema: {
+            asset_id: z.string().describe("Asset ID (e.g. vid-my-video)"),
+            book_id: z.string().describe("Book id"),
+            ratio: z.enum(["16:9", "9:16", "1:1"]).describe("Target aspect ratio"),
+            x: z.number().min(0).max(1).describe("Crop origin X as fraction of source width (0..1)"),
+            y: z.number().min(0).max(1).describe("Crop origin Y as fraction of source height (0..1)"),
+            w: z.number().min(0).max(1).describe("Crop width as fraction of source width (0..1)"),
+            h: z.number().min(0).max(1).describe("Crop height as fraction of source height (0..1)"),
+        },
+        handler: async (args) => {
+            const { asset_id, book_id, ratio, x, y, w, h } = args;
+            const rectErr = validateRect(x, y, w, h);
+            if (rectErr) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: rectErr.error }],
+                };
+            }
+            const manifestResult = await engine.files.manifest(asset_id);
+            if (!manifestResult.ok) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: manifestResult.error.message }],
+                };
+            }
+            const manifest = manifestResult.value;
+            const videoFile = findVideoFile(manifest.files);
+            if (!videoFile) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `No video file found in asset ${asset_id}` }],
+                };
+            }
+            const assetDir = manifest.path;
+            const videoPath = join(assetDir, videoFile.name);
+            try {
+                const source = await probeVideo(videoPath);
+                cropGeometry({ x, y, w, h }, source.width, source.height, ratio, 2);
+            }
+            catch (error) {
+                return { isError: true, content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }] };
+            }
+            const tempPath = join(assetDir, "original_cropped.mp4");
+            const jobId = `crop-${asset_id}-${Date.now()}`;
+            const jobPayload = {
+                type: "crop_video",
+                inputPath: videoPath,
+                outputPath: tempPath,
+                ratio,
+                rect: { x, y, w, h },
+                assetId: asset_id,
+                assetDir,
+                bookId: book_id,
+            };
+            try {
+                await queue.enqueueAndWait(jobId, jobPayload);
+            }
+            catch (err) {
+                return {
+                    isError: true,
+                    content: [{
+                            type: "text",
+                            text: `Crop failed: ${err instanceof Error ? err.message : String(err)}`,
+                        }],
+                };
+            }
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({ asset_id, job_id: jobId, ratio, status: "completed" }),
+                    }],
+            };
+        },
+    };
+}

package/dist/tools/delete-asset.js

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import { queue } from "../queue.js";
+import { readTimeline, timelineFailure, timelineInput, writeTimeline, } from "../timeline-helpers.js";
+const FORGET_TIMEOUT_MS = 5 * 60_000;
+/** Drops every primary-sequence clip and audio clip that plays the artifact. */
+export async function removeArtifactFromTimeline(engine, artifactId, options = {}) {
+    const timeline = readTimeline(engine);
+    const slots = timeline.slots.filter((slot) => slot.artifactId !== artifactId);
+    const audio = timeline.audio.filter((clip) => clip.artifactId !== artifactId);
+    if (!engine.sequences.getPrimary().clips.some((clip) => clip.source.artifactId === artifactId)) {
+        return { updated: false };
+    }
+    const result = await writeTimeline(engine, {
+        ...timelineInput(timeline),
+        slots: slots.map((slot) => ({
+            id: slot.id,
+            artifactId: slot.artifactId,
+            ...(slot.volume === undefined ? {} : { volume: slot.volume }),
+            ...(slot.audioFadeIn === undefined ? {} : { audioFadeIn: slot.audioFadeIn }),
+            ...(slot.audioFadeOut === undefined ? {} : { audioFadeOut: slot.audioFadeOut }),
+        })),
+        audio: audio.map((clip) => ({
+            id: clip.id,
+            artifactId: clip.artifactId,
+            startFrame: clip.startFrame,
+            durationFrames: clip.durationFrames,
+            ...(clip.volume === undefined ? {} : { volume: clip.volume }),
+            ...(clip.fadeIn === undefined ? {} : { fadeIn: clip.fadeIn }),
+            ...(clip.fadeOut === undefined ? {} : { fadeOut: clip.fadeOut }),
+        })),
+    }, { removeArtifactId: artifactId, ...options });
+    return result.ok ? { updated: true } : { updated: false, error: result.error.message };
+}
+function jsonResult(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value) }] };
+}
+async function deleteArtifact(engine, artifact) {
+    const assetId = artifact.artifactId;
+    const references = engine.artifacts.deletionReferences(assetId, { deleteOwnedMedia: true });
+    if (!references.ok)
+        return timelineFailure(references.error.message);
+    const removable = new Set(engine.sequences.getPrimary().clips
+        .filter((clip) => clip.source.artifactId === assetId).map((clip) => clip.clipId));
+    const blockers = references.value.filter((reference) => reference.kind !== "sequenceClip" || !removable.has(reference.id));
+    if (blockers.length > 0) {
+        return timelineFailure(`Artifact is still referenced: ${assetId} (${blockers.map((reference) => reference.kind).join(", ")}); delete it with forget and clear_references to clear them`);
+    }
+    const timeline = await removeArtifactFromTimeline(engine, assetId);
+    if (timeline.error)
+        return timelineFailure(timeline.error);
+    const result = await engine.artifacts.delete(assetId, { deleteOwnedMedia: true });
+    if (!result.ok)
+        return timelineFailure(result.error.message);
+    return jsonResult({
+        status: "deleted",
+        artifact_id: assetId,
+        ...(artifact.label ? { label: artifact.label } : {}),
+        deleted_at: new Date().toISOString(),
+        timeline,
+    });
+}
+async function forgetArtifact(bookId, artifactId, clearReferences) {
+    try {
+        const outcome = await queue.enqueueAndWait(`forget-asset-${artifactId}`, { type: "forget_asset", bookId, forgetArtifactId: artifactId, clearReferences }, FORGET_TIMEOUT_MS);
+        return jsonResult({
+            status: outcome.status,
+            artifact_id: outcome.artifactId,
+            ...(outcome.label ? { label: outcome.label } : {}),
+            references: outcome.references,
+            cleared_cells: outcome.clearedCells,
+            forgotten_objects: outcome.forgottenObjects,
+            shared_objects: outcome.sharedObjects,
+            reclaimed_bytes: outcome.reclaimedBytes,
+        });
+    }
+    catch (cause) {
+        return timelineFailure(cause instanceof Error ? cause.message : String(cause));
+    }
+}
+export function deleteAssetDef(engine) {
+    return {
+        name: "delete_asset",
+        description: "Delete an asset, dropping its sequence clips. forget also destroys its stored bytes (bytes another asset shares are kept)",
+        annotations: { destructiveHint: true, idempotentHint: false },
+        schema: {
+            asset_id: z.string(),
+            book_id: z.string().uuid(),
+            forget: z.boolean().optional().describe("Permanently destroy the stored content too"),
+            clear_references: z.boolean().optional()
+                .describe("With forget: clear notebook cells and sequence clips holding the asset first"),
+        },
+        handler: async (args) => {
+            const artifact = engine.artifacts.get(String(args.asset_id));
+            if (!artifact.ok)
+                return timelineFailure(artifact.error.message);
+            if (args.forget === true) {
+                return forgetArtifact(String(args.book_id), artifact.value.artifactId, args.clear_references === true);
+            }
+            if (args.clear_references === true)
+                return timelineFailure("clear_references applies only with forget");
+            return deleteArtifact(engine, artifact.value);
+        },
+    };
+}

package/dist/tools/describe-image.js

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import { extname } from "node:path";
+import { queue } from "../queue.js";
+const IMAGE_EXTENSIONS = new Set(["jpg", "jpeg", "png", "webp", "gif"]);
+function findImageFile(files) {
+    const images = files.filter((f) => {
+        const ext = (f.extension ?? extname(f.name)).replace(/^\./, "").toLowerCase();
+        return IMAGE_EXTENSIONS.has(ext);
+    });
+    return images.find((f) => f.name.startsWith("original")) ?? images[0] ?? null;
+}
+function error(text) {
+    return { isError: true, content: [{ type: "text", text }] };
+}
+export function describeImageDef(engine) {
+    return {
+        name: "describe_image",
+        description: "Write a reproduction-ready prompt for an image asset into a new script asset using vision (asynchronous).",
+        schema: {
+            asset_id: z.string().describe("Image artifact id"),
+            book_id: z.string().describe("Book UUID"),
+        },
+        handler: async (args) => {
+            const { asset_id, book_id } = args;
+            const sourceArtifact = engine.artifacts.get(asset_id);
+            if (!sourceArtifact.ok)
+                return error(sourceArtifact.error.message);
+            if (sourceArtifact.value.kind !== "image") {
+                return error(`describe_image only accepts image artifacts, got ${sourceArtifact.value.kind} artifact ${asset_id}`);
+            }
+            if (!process.env.OPENAI_API_KEY) {
+                return error("OPENAI_API_KEY is not set");
+            }
+            const manifestResult = await engine.files.manifest(asset_id);
+            if (!manifestResult.ok) {
+                return error(manifestResult.error.message);
+            }
+            const imageFile = findImageFile(manifestResult.value.files);
+            if (!imageFile) {
+                return error(`No image file found in artifact ${asset_id}`);
+            }
+            const scriptName = `desc ${sourceArtifact.value.label ?? asset_id}`;
+            const createResult = await engine.artifacts.create("script", scriptName);
+            if (!createResult.ok) {
+                return error(`Failed to create script asset: ${createResult.error.message}`);
+            }
+            const { artifactId: scriptAssetId } = createResult.value;
+            const jobId = `describe-image-${asset_id}-${Date.now()}`;
+            await queue.enqueue(jobId, {
+                type: "describe_image",
+                sourceAssetId: asset_id,
+                sourceImageFilename: imageFile.name,
+                assetId: scriptAssetId,
+                bookId: book_id,
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            source_asset_id: asset_id,
+                            script_asset_id: scriptAssetId,
+                            job_id: jobId,
+                            status: "enqueued",
+                        }),
+                    }],
+            };
+        },
+    };
+}

package/dist/tools/detect-scenes.js

@@ -0,0 +1,44 @@
+import { findVideoFile } from "videobook-engine";
+import { z } from "zod";
+import { queue } from "../queue.js";
+export function detectScenesDef(engine) {
+    return {
+        name: "detect_scenes",
+        description: "Find natural visual breaks in a video in a background job: shot cuts and motion-settle moments inside steady shots, each with a time and score. Read-only.",
+        schema: {
+            source_asset_id: z.string().describe("Video asset id (vid-*) inside the project"),
+            book_id: z.string().describe("Book id"),
+        },
+        handler: async (args) => {
+            const { source_asset_id, book_id } = args;
+            const sourceAssetId = source_asset_id.replace(/^@/, "");
+            const manifestResult = await engine.files.manifest(sourceAssetId);
+            if (!manifestResult.ok) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: manifestResult.error.message }],
+                };
+            }
+            const videoFile = findVideoFile(manifestResult.value.files);
+            if (!videoFile) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `No video file found in asset ${sourceAssetId}` }],
+                };
+            }
+            const jobId = `detect-scenes-${sourceAssetId}-${Date.now()}`;
+            await queue.enqueue(jobId, {
+                type: "detect_scenes",
+                assetId: sourceAssetId,
+                assetDir: manifestResult.value.path,
+                bookId: book_id,
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({ asset_id: sourceAssetId, job_id: jobId, status: "enqueued" }),
+                    }],
+            };
+        },
+    };
+}