videobook 0.0.0-stage → 0.2.0

package/dist/goal-styles.js

@@ -0,0 +1,144 @@
+export const GOAL_STYLE_IDS = ["source", "cinematic", "ig-influencer"];
+const styles = {
+    source: {
+        id: "source", label: "Match source", summary: "Keep the look, camera and lighting of the source screenshot.",
+        briefKeywords: [], defaults: { imageModel: "nano-banana-2-1", imageResolution: "2K", videoResolution: "720p" },
+        planner: "Infer the visual style, framing, lighting and camera from the scene reference. Preserve that look. Identify the scene screenshot, character references and prop references from the actual images and brief. Reference images are not necessarily people. Remove social-media interface overlays from generated pictures.",
+        fragments: {
+            frame: "Match the source scene's framing, lighting and visual style; remove interface overlays",
+            storyboard: "Keep the approved scene's visual style, people and props",
+            ending: "Keep the approved scene's visual style",
+            video: "Match the approved scene's camera and lighting; natural ambient sound",
+            revise: "Preserve the selected image's visual style",
+        },
+        banned: [], options: [],
+    },
+    cinematic: {
+        id: "cinematic", label: "Cinematic", summary: "Photographic live-action with natural proportions, textures and motion.",
+        briefKeywords: ["cinematic"], defaults: {},
+        planner: "Photographic live-action. Natural proportions, real skin and material textures, practical light. Restrained expressions and plausible motion. Comedy comes from situations and timing; avoid cartoon rendering, caricature, rubbery movement and exaggerated features.",
+        fragments: {
+            frame: "Photographic live-action, natural proportions, real textures",
+            storyboard: "Photographic live-action, natural proportions, real textures",
+            ending: "Photographic live-action, natural proportions, real textures",
+            video: "Live-action, natural motion, restrained expressions",
+            revise: "Photographic live-action, natural proportions, real textures",
+        },
+        banned: [], options: [],
+    },
+    "ig-influencer": {
+        id: "ig-influencer", label: "IG Influencer", summary: "Hyper-realistic, candid iPhone footage with natural skin and light.",
+        briefKeywords: ["ig influencer", "instagram influencer", "influencer", "insta reel", "instagram reel"],
+        defaults: { aspectRatio: "9:16", imageModel: "sunburst", imageResolution: "2K", videoResolution: "720p" },
+        planner: "Use a hyper-realistic Instagram phone-camera register: real-world activity in present tense, one location per shot, candid framing with slight imperfection, light grain, unretouched skin with visible pores and texture. Use the selected iPhone camera and lighting; natural daylight or soft indoor light by default. No HDR crunch or beautify. No captions or on-screen text inside pictures or video; storyboard notes go below pictures. Avoid cinematic, masterpiece, editorial, Portra, Cinestill and all film-stock vocabulary. Match the delivery: address the camera for selfies, be caught mid-action when filmed by a friend, hold framing steady on a tripod, or show the reflection for a mirror shot. Make the selected content format explicit in the four beats. Sound is ambient room or street sound with an optional short spoken line.",
+        fragments: {
+            frame: "hyper-realistic, skin pores, light grain",
+            storyboard: "hyper-realistic, skin pores, light grain",
+            ending: "hyper-realistic, skin pores",
+            video: "hyper-realistic skin pores, natural motion, handheld micro-shake, ambient sound",
+            revise: "hyper-realistic, skin pores",
+        },
+        banned: ["cinematic", "masterpiece", "editorial", "Portra", "Cinestill"],
+        options: [
+            {
+                key: "format", label: "Content format", default: "day-in-the-life",
+                choices: [
+                    { value: "grwm", label: "GRWM", prompt: "GRWM", briefKeywords: ["grwm", "get ready with me"], beats: "skincare, outfit, final look, mirror check" },
+                    { value: "ootd", label: "OOTD", prompt: "OOTD", briefKeywords: ["ootd", "outfit of the day"], beats: "reveal, details, walk, turn" },
+                    { value: "day-in-the-life", label: "Day in the life", prompt: "day-in-the-life", briefKeywords: ["day in the life", "vlog"], beats: "arrive, begin activity, react, finish" },
+                    { value: "travel-reel", label: "Travel reel", prompt: "travel", briefKeywords: ["travel reel"], beats: "arrive, explore, discover, farewell" },
+                    { value: "cafe", label: "Café", prompt: "café", briefKeywords: ["brunch", "cafe", "café"], beats: "order, receive drink, taste, smile" },
+                    { value: "gym", label: "Gym", prompt: "gym", briefKeywords: ["gym"], beats: "warm up, exercise, effort, recover" },
+                    { value: "skincare", label: "Skincare", prompt: "skincare", briefKeywords: ["skincare"], beats: "cleanse, apply, massage, reveal" },
+                    { value: "haul", label: "Haul", prompt: "haul", briefKeywords: ["haul"], beats: "unpack, show item, try on, react" },
+                    { value: "storytime", label: "Storytime", prompt: "storytime", briefKeywords: ["storytime"], beats: "hook, explain, react, conclude" },
+                ],
+            },
+            {
+                key: "delivery", label: "Delivery", default: "selfie-to-camera",
+                choices: [
+                    { value: "selfie-to-camera", label: "Selfie to camera", prompt: "selfie", briefKeywords: ["selfie", "front camera"] },
+                    { value: "filmed-by-friend", label: "Filmed by a friend", prompt: "friend-filmed", briefKeywords: ["filmed by"] },
+                    { value: "tripod", label: "Tripod", prompt: "tripod", briefKeywords: ["tripod"] },
+                    { value: "mirror", label: "Mirror", prompt: "mirror", briefKeywords: ["mirror"] },
+                ],
+            },
+            {
+                key: "camera", label: "Camera", default: "iphone-front",
+                choices: [
+                    { value: "iphone-front", label: "iPhone front camera", prompt: "iPhone front", briefKeywords: ["front camera", "iphone front"] },
+                    { value: "iphone-main", label: "iPhone main camera", prompt: "iPhone main", briefKeywords: ["main camera", "iphone main"] },
+                ],
+            },
+            {
+                key: "light", label: "Light", default: "soft-daylight",
+                choices: [
+                    { value: "soft-daylight", label: "Soft daylight", prompt: "soft daylight", briefKeywords: ["soft daylight", "natural daylight"] },
+                    { value: "golden-hour", label: "Golden hour", prompt: "golden hour", briefKeywords: ["golden hour"] },
+                    { value: "indoor-warm", label: "Warm indoor light", prompt: "warm indoor", briefKeywords: ["warm indoor", "indoor warm"] },
+                    { value: "night-flash", label: "Night flash", prompt: "night flash", briefKeywords: ["night out", "flash"] },
+                ],
+            },
+        ],
+    },
+};
+export function goalStyle(id) {
+    return styles[id];
+}
+export function resolveGoalStyleOptions(id, partial = {}) {
+    const style = goalStyle(id);
+    for (const key of Object.keys(partial)) {
+        if (!style.options.some(option => option.key === key))
+            throw new Error(`Unknown ${style.label} option: ${key}`);
+    }
+    const resolved = {};
+    for (const option of style.options) {
+        const fallback = option.key === "camera" && resolved.delivery !== "selfie-to-camera" ? "iphone-main" : option.default;
+        const value = partial[option.key] ?? fallback;
+        if (!option.choices.some(choice => choice.value === value)) {
+            throw new Error(`Invalid ${style.label} ${option.label}: ${value}. Choose ${option.choices.map(choice => choice.value).join(", ")}.`);
+        }
+        resolved[option.key] = value;
+    }
+    return resolved;
+}
+export function goalStyleFragment(selection, stage) {
+    const style = goalStyle(selection.id);
+    const options = resolveGoalStyleOptions(selection.id, selection.options);
+    let fragment = style.fragments[stage];
+    if (!fragment)
+        return "";
+    if (stage === "video" && options.delivery === "tripod")
+        fragment = fragment.replace("handheld micro-shake", "steady framing");
+    const pieces = style.options.map(option => option.choices.find(choice => choice.value === options[option.key]).prompt);
+    return `${pieces.length ? `${pieces.join(", ")}: ` : ""}${fragment}.`;
+}
+export function goalStyleSummary(selection) {
+    const style = goalStyle(selection.id);
+    const options = resolveGoalStyleOptions(selection.id, selection.options);
+    return [style.label, ...style.options.map(option => option.choices.find(choice => choice.value === options[option.key]).label)].join(" · ");
+}
+export function goalStylesEqual(left, right) {
+    if (left.id !== right.id)
+        return false;
+    const a = resolveGoalStyleOptions(left.id, left.options);
+    const b = resolveGoalStyleOptions(right.id, right.options);
+    return Object.keys(a).every(key => a[key] === b[key]);
+}
+function firstKeyword(brief, keywords) {
+    return Math.min(...keywords.map(keyword => {
+        const pattern = keyword.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&").replace(/[ -]+/gu, "[\\s-]+");
+        const match = new RegExp(`(^|[^\\p{L}\\p{N}_-])${pattern}(?=$|[^\\p{L}\\p{N}_-])`, "iu").exec(brief);
+        return match ? match.index + match[1].length : Infinity;
+    }));
+}
+export function goalBriefStyle(brief) {
+    const style = GOAL_STYLE_IDS.map(id => ({ style: goalStyle(id), index: firstKeyword(brief, goalStyle(id).briefKeywords) }))
+        .filter(match => Number.isFinite(match.index)).sort((left, right) => left.index - right.index)[0]?.style ?? goalStyle("source");
+    const partial = Object.fromEntries(style.options.flatMap(option => {
+        const choice = option.choices.map(candidate => ({ value: candidate.value, index: firstKeyword(brief, candidate.briefKeywords) }))
+            .filter(match => Number.isFinite(match.index)).sort((left, right) => left.index - right.index)[0];
+        return choice ? [[option.key, choice.value]] : [];
+    }));
+    return { id: style.id, options: resolveGoalStyleOptions(style.id, partial) };
+}

package/dist/goal-v3-runtime.js

@@ -0,0 +1,157 @@
+import { join } from "node:path";
+import { v7 as uuidv7 } from "uuid";
+import { findPrimaryMediaFile, nextHorizontalSlotFrom } from "videobook-engine";
+import { notebookGridTag, notebookOccupiedSlots } from "videobook-engine/notebook-grid";
+import { scanNotebookMentions } from "videobook-engine/notebook-mentions";
+import { probeVideo } from "./ffmpeg.js";
+import { closestGoalAspectRatio, compileGoalV3Steps } from "./goal-plan-v3.js";
+import { captureFrame } from "./notebook-media-ops.js";
+import { EXTRACT_FRAME_OUTPUT_ROLE } from "./notebook-cell-outputs.js";
+import { mutateNotebook } from "./notebook-mutations.js";
+import { slotRight } from "./notebook-placement.js";
+import { notebookCellFingerprint } from "./jobs/run-notebook.js";
+import { queue } from "./queue.js";
+import { resolveNotebookPromptReferences } from "./notebook-reference-resolver.js";
+import { assessToolCallEstimate } from "./jobs/cost-estimate-assessment.js";
+const GOAL_MEDIA_HELP = "Mention the reference images or videos in the brief, for example /goal @a1 @a2 as ...";
+function mediaKind(kind, cellType) {
+    if (kind === "image" || cellType === "image" || cellType === "generate_image")
+        return "image";
+    if (kind === "video" || kind === "final" || ["video", "generate_video", "concat", "splice", "split_video"].includes(cellType))
+        return "video";
+    return null;
+}
+export async function resolveGoalMediaReferences(engine, document, brief) {
+    if (scanNotebookMentions(brief).length === 0)
+        throw new Error(GOAL_MEDIA_HELP);
+    const resolved = resolveNotebookPromptReferences({ engine, document, prompt: brief, requireMedia: true });
+    if (resolved.unresolved.length > 0)
+        throw new Error(resolved.unresolved[0].message);
+    const references = [];
+    const seen = new Set();
+    for (const reference of resolved.resolved) {
+        if (seen.has(reference.artifactId))
+            continue;
+        const artifact = engine.artifacts.get(reference.artifactId);
+        const cell = document.cells.find(candidate => candidate.id === reference.cellId);
+        const kind = artifact.ok && cell ? mediaKind(artifact.value.kind, cell.type) : null;
+        if (!artifact.ok || !cell || !kind)
+            throw new Error(`${reference.mention} is not an image or video`);
+        const manifest = await engine.files.manifest(reference.artifactId);
+        const file = manifest.ok ? findPrimaryMediaFile(manifest.value.files, kind === "image" ? "image" : "video") : null;
+        if (!manifest.ok || !file)
+            throw new Error(`${reference.mention} has no readable media`);
+        seen.add(reference.artifactId);
+        references.push({
+            kind,
+            artifactId: reference.artifactId,
+            cellId: cell.id,
+            address: notebookGridTag(cell.slot),
+            label: artifact.value.label || cell.label || reference.mention,
+            objectHash: file.objectHash,
+        });
+    }
+    if (references.length === 0)
+        throw new Error(GOAL_MEDIA_HELP);
+    return references;
+}
+async function frameImageFile(engine, artifactId) {
+    const manifest = await engine.files.manifest(artifactId);
+    if (!manifest.ok)
+        throw new Error(manifest.error.message);
+    const file = findPrimaryMediaFile(manifest.value.files, "image");
+    if (!file)
+        throw new Error("The scene frame has no image file");
+    return { path: join(manifest.value.path, file.name), objectHash: file.objectHash };
+}
+async function insertSceneFrameCell(engine, notebookId, video, artifactId, atSeconds) {
+    const placed = { cell: null };
+    const runId = uuidv7();
+    const result = await mutateNotebook(engine, notebookId, "goal_scene_frame", (notebook) => {
+        const anchor = notebook.cells.find(cell => cell.id === video.cellId);
+        if (!anchor)
+            throw new Error(`${video.address} was removed`);
+        const cell = engine.notebooks.createCell({
+            type: "image",
+            label: `Frame at ${atSeconds}s`,
+            slot: nextHorizontalSlotFrom(slotRight(anchor.slot), notebookOccupiedSlots(notebook.cells)),
+            outputArtifactId: artifactId,
+            inputs: { mediaRole: EXTRACT_FRAME_OUTPUT_ROLE, frameMode: "time", timestampSeconds: atSeconds, atSeconds, sourceCellId: anchor.id, state: "completed" },
+        });
+        placed.cell = cell;
+        const completedAt = new Date().toISOString();
+        return {
+            ...notebook,
+            cells: [...notebook.cells, cell],
+            edges: [...notebook.edges, engine.notebooks.createEdge({ source: anchor.id, target: cell.id, targetInput: "segment" })],
+            execution: {
+                ...(notebook.execution ?? {}),
+                [cell.id]: { fingerprint: notebookCellFingerprint(notebook, cell), status: "completed", runId, outputArtifactId: artifactId, completedAt, updatedAt: completedAt, tool: "ffmpeg" },
+            },
+        };
+    }, { sourceCellId: video.cellId, runId }, { artifactId });
+    if (!result.ok)
+        throw new Error(result.error.message);
+    if (!placed.cell)
+        throw new Error("The scene frame could not be placed");
+    return placed.cell;
+}
+export async function captureGoalSceneFrame(engine, notebookId, references) {
+    const video = references.find(reference => reference.kind === "video");
+    if (!video)
+        return null;
+    const captured = await captureFrame(engine, video.artifactId, { role: "time", timestampSeconds: 1, title: `${video.address} · scene frame` });
+    const file = await frameImageFile(engine, captured.artifactId);
+    const probe = await probeVideo(file.path);
+    await queue.enqueue(`process-image-${captured.artifactId}`, {
+        type: "process_image", assetId: captured.artifactId, bookId: engine.book.get().bookId, extension: ".jpg",
+        provenance: { origin: "extract_frame", sourceArtifactId: video.artifactId, frameMode: "time", atSeconds: captured.atSeconds },
+    });
+    const cell = await insertSceneFrameCell(engine, notebookId, video, captured.artifactId, captured.atSeconds);
+    return {
+        reference: {
+            kind: "image", artifactId: captured.artifactId, cellId: cell.id, address: notebookGridTag(cell.slot),
+            label: cell.label ?? "Scene frame", objectHash: file.objectHash,
+        },
+        seconds: captured.atSeconds,
+        aspectRatio: closestGoalAspectRatio(probe.width, probe.height),
+    };
+}
+function estimateInput(engine, plan, step) {
+    const images = (step.id === "video" ? plan.video.imageRefs : plan.scene.imageRefs).map(reference => reference.artifactId);
+    const videos = step.id === "video" ? plan.video.videoRefs.map(reference => reference.artifactId) : [];
+    return {
+        book_id: engine.book.get().bookId,
+        ...step.params,
+        refs: { image: images, video: videos },
+        ...(step.id === "video" && images.length + videos.length > 0 ? { mode: "r2v" } : {}),
+    };
+}
+export async function estimateGoalV3(engine, plan) {
+    const [scene, video] = compileGoalV3Steps(plan);
+    const priced = await Promise.all([scene, video].map(async (step) => {
+        const estimate = await assessToolCallEstimate(engine, step.tool, estimateInput(engine, plan, step));
+        return { usd: estimate.available ? estimate.usd ?? null : null, warnings: estimate.warnings };
+    }));
+    const frame = priced[0];
+    const videos = priced[1];
+    const storyboards = { usd: 0, warnings: [] };
+    const parts = [frame, storyboards, videos];
+    return {
+        frame,
+        storyboards,
+        videos,
+        total: {
+            usd: parts.every(part => part.usd !== null) ? parts.reduce((sum, part) => sum + (part.usd ?? 0), 0) : null,
+            warnings: [...new Set(parts.flatMap(part => part.warnings))],
+        },
+    };
+}
+export function goalMediaCharacters(references) {
+    return references.filter(reference => reference.kind === "image").map(reference => ({
+        artifactId: reference.artifactId,
+        cellId: reference.cellId,
+        address: reference.address,
+        label: reference.label,
+    }));
+}

package/dist/guides/character_schema_guide.md

@@ -0,0 +1,70 @@
+# Character extraction guide
+
+You are an expert visual analyst. Look at the photograph and emit a structured **character profile** that downstream image-generation models can use to re-render this same identity across different garments, poses, and scenes.
+
+Return ONLY a JSON object matching the schema below. Do NOT wrap it in markdown fences or prose.
+
+## Subject kinds
+
+Pick exactly one `subject_kind` from this 4-way set, based on what the photograph shows:
+
+- `female` — a human female-presenting subject.
+- `male` — a human male-presenting subject.
+- `animal` — a non-human living subject (cat, dog, horse, bird, etc.).
+- `other` — anything else: an object, sculpture, doll, paper figure, mascot costume, abstract form, etc.
+
+The schema branches on this field. **Fill the human field set OR the freeform `other` field — never both.**
+
+## Field rules — `female` / `male`
+
+For human subjects, fill every required field with **concrete visual descriptors**. Image generators reproduce what they can render — anatomical structure, color, texture, geometry. They don't reproduce vibes from vague adjectives.
+
+- ✅ "hooded almond-shaped hazel eyes with thick lower lashes"
+- ❌ "kind, intelligent eyes"
+- ✅ "shoulder-length wavy chestnut hair, side-parted, slight frizz at the temples"
+- ❌ "messy brown hair"
+
+**Body measurements (`bust`, `waist`, `hips`) are the primary signal for re-rendering body shape consistently.** The `bust` field is the chest/bust geometry field: for `male` describe chest width, pectoral shape, and ribcage taper; for `female` describe bust size, cup estimate, distribution, and placement. Estimate concrete shape descriptors from the photograph — exact numeric measurements aren't usually possible, but chest width, cup size, waist taper, and hip width almost always are. Face / hair / eyes / skin remain useful but are **secondary** to body measurements.
+
+If a detail isn't visible, give the best plausible reading. Never write "unknown" — pick a concrete descriptor.
+
+## Field rules — `animal` / `other`
+
+For animal and other subjects, fill **only** the freeform `other` field — a single dense description that downstream models can use to re-render the same subject. Pack it with concrete visual detail.
+
+- For `animal`: species, breed, color, coat/fur length and texture, body proportions, distinguishing markings, eye color, ear/tail shape. Example: `"white domestic longhair cat, slender long-bodied build, fluffy medium-long silky fur, heterochromatic blue and golden eyes, pointed ears, plumed tail"`.
+- For `other`: what the subject is, materials, surface texture, color, structural form, distinguishing features. Example: `"origami paper man, folded white cardstock with sharp creases, blank flat face, articulated arms and legs, ~30cm tall"`.
+
+Do not fill the human fields (`age`, `ethnicity`, `height`, `build`, `bust`, `waist`, `hips`, `face`, `hair`, `eyes`, `skin`) for `animal` or `other`. Leave them out of the JSON.
+
+## Schema
+
+```json
+{
+  "name": "string — optional, leave blank or omit (the user fills this in)",
+  "subject_kind": "string — REQUIRED. One of: 'female', 'male', 'animal', 'other'.",
+
+  // Required ONLY when subject_kind is 'female' or 'male' — omit otherwise.
+  "age": "string — e.g. 'early 20s', 'mid-30s', '47'",
+  "ethnicity": "string — e.g. 'East Asian', 'Black / West African heritage', 'Latina', 'White / Northern European'",
+  "height": "string — height estimate, include a numeric estimate when possible (e.g. 'tall, ~6'0\" / 183cm')",
+  "build": "string — body build, e.g. 'lean athletic', 'slender', 'stocky compact'",
+  "bust": "string — chest/bust size + shape. For 'male': chest width, pectoral fullness, ribcage taper. For 'female': cup size estimate + distribution.",
+  "waist": "string — waist shape and taper",
+  "hips": "string — hip shape and width",
+  "face": "string — face structure. 1-2 sentences.",
+  "hair": "string — color, length, texture, density, hairline; describe the reference hairstyle itself. 1 sentence.",
+  "eyes": "string — color, shape, lash density, brow shape. 1 sentence.",
+  "skin": "string — skin tone and texture. 1 sentence.",
+
+  // Required ONLY when subject_kind is 'animal' or 'other' — omit for 'female'/'male'.
+  "other": "string — a single dense freeform description packed with concrete visual detail. 1-3 sentences."
+}
+```
+
+## Constraints
+
+- Each descriptive field is at most 2 short sentences (3 for `other`).
+- Total JSON must be under 2000 characters.
+- Do NOT include a `name` value — leave it empty or omit the key. The name is user-owned.
+- Do NOT speculate about profession, mood beyond the photo, or relationships.

package/dist/guides/gpt_image_2_5_prompting_guide.md

@@ -0,0 +1,21 @@
+---
+source: "https://developers.openai.com/api/docs/guides/image-generation"
+models: "GPT Image 2.5 Sunburst and Flare"
+---
+
+# GPT Image 2.5 Prompting Guide
+
+Sunburst is the default for precise image editing. Flare is available for fast everyday generation. Both support text prompts and reference images.
+
+Describe the subject, composition, setting, lighting, style, and intended use in clear language. Put essential constraints first. Quote any exact text that must appear and describe its placement and typography.
+
+For edits, state what must change and what must remain: identity, pose, framing, colors, layout, or background. Refer to multiple inputs by their order, such as image 1 and image 2, and describe the role of each. Preserve the user's reference order and requested visual details.
+
+Videobook uses Kie's GPT Image 2.5 endpoints. Supported controls come from Apicity:
+
+- Up to 16 optional reference images; no references selects text-to-image.
+- Aspect ratio: auto, 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9, 27:16, 16:27, 9:8, or 8:9.
+- Resolution: 1K, 2K, or 4K. Ratios 27:16, 16:27, 9:8, and 8:9 require 1K.
+- Background: transparent, opaque, or auto.
+
+Use only controls exposed by the selected provider. Keep aspect ratio, resolution, and background in their structured fields instead of adding API parameter names to the visual prompt. Do not add quality or NSFW-checker parameters to these Kie requests.

package/dist/guides/grok_imagine_prompting_guide.md

@@ -0,0 +1,72 @@
+---
+source: "docs.x.ai/docs/guides/image-generation, docs.x.ai/docs/guides/video-generation, grokimagineai.net/prompt-guide, genaintel.com/guides/how-to-prompt-grok-imagine"
+type: reference
+date_added: 2026-02-14
+---
+
+# Grok Imagine Prompting Guide
+
+## Summary
+
+Grok Imagine is xAI's multimodal generation system built on the Aurora model, an autoregressive mixture-of-experts network trained on interleaved text and image data. It supports text-to-image, image editing, text-to-video, image-to-video, and video editing. Aurora excels at photorealistic rendering and precise instruction following. Grok Imagine responds best to natural language scene descriptions rather than keyword lists — write prompts like scene direction, not tag stacking.
+
+## Key Takeaways
+
+- Prompts should read as natural scene descriptions, not keyword lists — the model interprets context intelligently
+- **Text-to-video formula:** Subject + Movement + Scene + Shot, Style
+- **Image-to-video formula:** Subject + Motion, Background + Motion, Camera + Motion
+- **Five-part structure for images:** Scene (what's happening) + Style (aesthetic) + Mood (emotional direction) + Lighting (time/quality) + Camera (shot type/lens/focus)
+- Place the main subject and action first — the model weights the opening of the prompt most heavily
+- Image-to-video prompts should reduce static element descriptions since the model expands from the input image
+- Negative prompts are ignored by the model — use explicit positive descriptions instead
+- Camera movement commands understood: zoom, pan, tilt, surround, aerial, follow, handheld, lens switching
+- Use "Shot Switch" to separate distinct camera angles in multi-shot sequences
+- Select "unfixed lens" when including camera movement in video generation
+- Intensity modifiers (quickly, violently, with large amplitude, powerfully, wildly) specify motion the model cannot infer from static images
+- Iterative refinement works best when adjusting one variable per iteration (lighting OR camera OR mood)
+- Batch generation supports up to 10 images per request for same-prompt variations
+
+## Style Keywords
+
+- **Realism:** photoreal detail, natural lighting, documentary feel
+- **Anime:** vibrant cel-shading, expressive linework
+- **Painterly:** oil-painting texture, impressionist glow
+- **Cinematic:** volumetric lighting, film grain, dynamic shadows
+- **Surreal:** dreamlike distortion, ethereal glow
+- **Graphic Novel:** inked outlines, bold contrasts, neon lines
+- Also supports: pencil sketch, pop art, watercolor, impressionism
+
+## Composition Control
+
+- Wide establishing shots for scale and context
+- Low-angle shots for heroic or imposing framing
+- Close-ups for emotion and texture
+- Over-the-shoulder for conversation and tension
+- Shallow depth of field for subject isolation
+
+## Emotion-Driven Language
+
+The model responds strongly to atmospheric vocabulary: nostalgic, melancholic, electric, tense, dreamlike. Emotional tone shapes the entire output more than technical descriptors alone.
+
+## Technical Parameters
+
+### Image Generation
+- **Aspect ratios:** 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 2:1, 1:2, auto
+- **Resolution:** 1K or 2K
+- **Batch size:** up to 10 images per request
+- **Pricing:** flat per-image (not token-based)
+
+### Video Generation
+- **Duration:** 1–15 seconds (generation), up to 8.7 seconds (editing)
+- **Resolution:** 480p or 720p
+- **Aspect ratios:** 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3
+- **Lens type:** fixed or unfixed (unfixed required for camera movement)
+
+## Common Mistakes
+
+- Tag stacking instead of natural language (produces generic results)
+- Weak verbs — use "surges," "unfurls," "erupts" instead of "standing," "sitting"
+- Missing time-of-day or weather cues
+- Vague aesthetic directions without specific style anchors
+- Conflicting adjective overload
+- Contradicting the input image in image-to-video prompts

package/dist/guides/image_reproduction_guide.md

@@ -0,0 +1,84 @@
+# Image Reproduction Prompt Guide
+
+Your output is fed directly into an image generator. Produce a prompt that — if given to a capable model with no other context — would reproduce the image as closely as possible in subject, framing, light, and feel.
+
+## Output shape
+
+Return a JSON object with these fields:
+
+```json
+{
+  "prompt": "single paragraph prompt, no line breaks, fed directly to an image model",
+  "shot": "shot size + camera angle in standard cinematography terms — see rules below",
+  "pose": "pure body pose of any human figure(s) — body geometry only, see rules below"
+}
+```
+
+## Rules for the `shot` field
+
+Format: `"<size>, <angle>"`. Always include both, comma-separated, lowercase.
+
+**Size** — pick exactly one (terms from standard cinematography):
+
+- `extreme close-up` (ECU/XCU) — a single feature fills the frame (eyes, mouth, hands, a detail)
+- `close-up` (CU) — head fills the frame
+- `medium close-up` (MCU) — head and shoulders, roughly chest-up
+- `medium shot` (MS) — waist up
+- `medium long shot` (MLS) — knees up (also called American shot / cowboy shot)
+- `long shot` (LS) — full figure head to toe, roughly fills frame height
+- `extreme long shot` (ELS/EWS) — figure small inside a dominant environment
+
+**Angle** — pick exactly one:
+
+- `eye-level` — camera at subject's eye height
+- `low-angle` — camera below subject, looking up
+- `high-angle` — camera above subject, looking down
+- `overhead` — straight down, bird's-eye
+- `dutch` — camera tilted, horizon askew
+
+Examples: `"medium close-up, eye-level"`, `"long shot, low-angle"`, `"extreme close-up, overhead"`.
+
+If there is no human or recognisable subject (pure landscape, abstract texture), still emit the closest size and angle for the dominant element.
+
+## Rules for the `pose` field
+
+Only emit `pose` when the image contains one or more human figures. Describe the body's geometry only:
+
+- Weight distribution and stance (e.g. weight on right leg, left foot crossed in front on the ball, contrapposto, kneeling, seated cross-legged, walking mid-stride).
+- Rotation of hips, torso, shoulders, and head relative to camera (e.g. hips three-quarters away, torso twisted back over right shoulder, head turned further than shoulders into three-quarter view).
+- Spine curvature (S-curve, arched, slumped, neutral).
+- Arm and leg positions, including elbow/knee bend and where the hands rest or what they grip.
+
+For close-ups where part of the body is out of frame, also describe the **implied posture** suggested by what's visible — what the off-frame body must be doing for the in-frame parts to make sense (e.g. "leaning forward with folded arms resting on a flat surface at chest height", "seated at a table with elbows on the surface", "lying prone with chin propped on hands"). Make this implied-posture clause one sentence at the end of the field.
+
+Do NOT mention clothing, hair, facial features, identity, expression, props, setting, or lighting in this field — those belong in `prompt`. Keep it to body geometry a pose-skeleton extractor would care about.
+
+## Rules for the `prompt` field
+
+1. **One paragraph.** No line breaks, no lists, no labels. Continuous prose.
+2. **Order matters.** Start with subject + action, then composition/framing, then lighting, then camera, then palette, then style/medium, then mood, then post-processing. A reader following the prompt top to bottom should build the image in the right order.
+3. **Be specific and visual.** "Warm golden-hour key light from camera-right at a low angle, long hard shadows raking across the wall" — not "nice lighting."
+4. **Name what you can see.** If the light is clearly a window, say window. If it's a rim light, say rim. If it's a ring-light catchlight, say so. Don't invent details you can't see, but don't be vague about what's obvious.
+5. **Estimate technical parameters** when the image signals them: lens compression (long-lens flattening vs wide-lens distortion), depth of field, shutter artifacts, film stock hints (Portra pastels, Ektachrome greens, Cinestill halation).
+6. **Match the medium.** A painting gets brush/medium vocabulary, not lens talk. A 3D render gets render-engine/material vocabulary. A photo gets camera/lens/film vocabulary.
+7. **Mood last.** End on the emotional register so the model weighs subject and craft before feel.
+8. **No filler.** Drop "a beautiful image of," "stunning," "masterpiece," etc. Describe, don't adjectivize.
+9. **Do not reference the source.** Don't say "recreate this image" or "in the style of the attached photo." The prompt stands alone.
+
+## Register: authentic photo vs editorial vs non-photo
+
+Before writing the prompt, decide what the image *actually is*. Picking the wrong register is the single biggest source of bad reproductions.
+
+- **Authentic / phone / social snapshot** — candid framing, imperfect focus, available (non-studio) light, slight clutter, non-posed subject, visible compression or upload artifacts, unretouched skin. This is the default for most user images. Use phone-capture vocabulary, drawn freely from this list as appropriate: *authentic iPhone photo, casual snapshot, handheld, mild grain, subtle facial imperfections, natural under-eye shadows, slight uneven skin tone, very subtle motion softness, no beauty filter, no skin smoothing, unedited skin, slight ISO noise, tiny chromatic aberration around highlights, mild Instagram-upload compression artifacts, slight shadow banding, very subtle sensor noise, slightly lifted blacks from auto-HDR, ordinary daylight / ordinary indoor light*. **Do not** say "editorial photograph", "35mm Portra/Cinestill", "masterpiece", "cinematic", "shot on Arri", or name pro film stocks.
+- **Editorial / studio / film** — controlled light, intentional framing, pro retouching, shallow studio bokeh, obvious film look. Only then use film-stock / lens / grade vocabulary (Portra, Cinestill, halation, teal-orange grade, etc.).
+- **Painting, illustration, 3D render** — use medium vocabulary (brushwork, ink, cel, Unreal Engine 5, PBR, octane). Never mix camera/lens/film talk into a painting.
+
+If in doubt, default to **authentic photo**. Most source images are phone captures, and "editorial/cinematic" vocabulary is what makes reproductions look staged and fake.
+
+## Example (authentic phone snapshot — for calibration, not for output)
+
+Subject: a pale pink pet pig sitting upright on the back of a small red scooter in daytime traffic, secured with a rope harness, shot from a neighboring car window.
+
+Bad: "a cinematic editorial photograph of a pig on a scooter, masterpiece, 35mm Portra, shallow depth of field"
+
+Good: "A large pale pink pig sits upright on the rear seat of a small red scooter behind a helmeted rider, held in place with a loose rope harness, rolling through mid-afternoon urban traffic; framed through the open window of a neighboring car with a sliver of the car's door visible in the lower foreground and parked white sedans and low concrete shopfronts receding into the background. Composition is centered on the pig, handheld and slightly tilted, medium telephoto compression flattening the street behind. Ordinary overhead midday daylight, soft overall with a gentle warm cast off the asphalt and no hard shadows. Shot on iPhone at roughly equivalent 50–70mm, deep focus, very slight motion softness from the moving cars. Palette of dusty pink, tomato red, warm grey asphalt, and pale sky. Authentic iPhone photo, mild grain, tiny chromatic aberration around highlights, subtle sensor noise, mild Instagram-upload compression, slightly lifted blacks, no beauty filter, no skin smoothing, unedited. Humorous and surreal but matter-of-fact."