@bitmagic/cli 0.1.64-dev.1 → 0.1.64-dev.11

package/dist/commands/generate.js

@@ -9,7 +9,8 @@ import { CliError, errnoCode } from '../errors.js';
 import { parseNumberFlag } from './number-flag.js';
 import { createOutput } from '../output.js';
 import { commandRunDeps, decoratedError } from './run-deps.js';
-import { loadProjectContext } from '../project/context.js';
+import { findProjectRootOrNull, loadProjectContext } from '../project/context.js';
+import { readArtStyleDeclaration, resolveArtStyle } from '../project/art-style.js';
 import { withJobRecord } from '../project/jobs.js';
 import { describeAppliedReference, NO_REFERENCE_FLAG, REFERENCE_FILE_FLAG, REFERENCE_IMAGE_FLAG, } from '../project/reference.js';
 import { resolveReferenceForCall } from '../project/reference-file.js';
@@ -26,8 +27,11 @@ import { downloadMusicFile } from '../generate/music.js';
 import { MUSIC_MAX_SECONDS, MUSIC_MIN_SECONDS, VIDEO_MAX_SECONDS, VIDEO_MIN_SECONDS } from '@bitmagic/asset-core';
 import { generateAndInstallAnimationFromVideo, isLocomotionState, isVideoToMotionModel, } from '../generate/animation-from-video.js';
 import { generateAndInstallVideo, IMAGE_EXTENSIONS, } from '../generate/video.js';
+import { reviewGeneratedClip } from '../generate/video-review.js';
+import { askOnStdin, isAffirmative, isInteractive } from '../prompt.js';
+import { renderInlineImage } from '../render/inline-image.js';
 import { VIDEO_EXTENSIONS } from '../assets/file-kind.js';
-import { LOCOMOTION_STATES, VIDEO_TO_MOTION_MODELS } from '@bitmagic/asset-core';
+import { LOCOMOTION_STATES, VIDEO_TO_MOTION_MODELS, MOTION_SOURCE_DEFAULT_SECONDS, MOTION_SOURCE_MIN_SECONDS, buildMotionSourcePrompt, } from '@bitmagic/asset-core';
 import { classifyAssetMaterialsQuietly } from '../assets/materials.js';
 import { DEFAULT_MAX_VOXEL_SIZE, DEFAULT_MIN_VOXEL_SIZE, SOLID_FILL_MAX_HEIGHT_M } from './assets.js';
 import { creatorPromptField, ORIGINAL_PROMPT_FLAG, withParent } from '../telemetry/creator-prompt.js';
@@ -102,6 +106,18 @@ export function buildImageBody(args) {
         referenceImageUrl: args.referenceImageUrl,
     });
 }
+/**
+ * The character default a project's art style implies: a low-poly game keeps the textured rig.
+ * Read from the cwd's project like every other generate command; outside a project the answer
+ * is "declares nothing", so the generator's own default (voxelize) stands and `loadProjectContext`
+ * reports the missing project on the very next line.
+ */
+function defaultVoxelizeForProject() {
+    const root = findProjectRootOrNull();
+    if (root === null)
+        return undefined;
+    return readArtStyleDeclaration(root).artStyle === 'low-poly' ? false : undefined;
+}
 export function buildCharacterBody(args) {
     return withoutAbsentFlags({
         name: args.name,
@@ -109,6 +125,8 @@ export function buildCharacterBody(args) {
         applyToPlayer: args.applyToPlayer,
         headScale: parseNumberFlag('head-scale', args.headScale, { min: 50, max: 300 }),
         useLibrary: args.library,
+        voxelize: args.voxelize,
+        meshModel: args.meshModel,
     });
 }
 // ── animation ───────────────────────────────────────────────────────────────
@@ -253,6 +271,44 @@ export function buildAnimationBody(args, readSpec) {
         spec,
     });
 }
+/**
+ * `--video-prompt` is `--video` with the clip generated instead of filmed, so it
+ * shares every downstream flag and refuses the same combinations. The extra
+ * refusal is the duration floor: `generate video` will happily make a 1 s clip,
+ * and Uthana will then reject it, which would bill the creator for footage that
+ * never had a chance.
+ */
+export function buildAnimationFromPromptRun(args) {
+    if (args.spec !== undefined || args.family !== undefined) {
+        throw new CliError('--video-prompt cannot be combined with --spec or --family: a captured clip is not authored from a spec.');
+    }
+    if (args.video !== undefined) {
+        throw new CliError('--video and --video-prompt cannot be combined: pass a clip you have, or describe one to generate.');
+    }
+    if (args.videoPrompt.trim() === '') {
+        throw new CliError('--video-prompt needs a description of the motion, e.g. "a person waving both arms overhead".');
+    }
+    const durationSeconds = args.videoDuration ?? MOTION_SOURCE_DEFAULT_SECONDS;
+    if (!Number.isFinite(durationSeconds)
+        || durationSeconds < MOTION_SOURCE_MIN_SECONDS || durationSeconds > VIDEO_MAX_SECONDS) {
+        throw new CliError(`--video-duration must be ${MOTION_SOURCE_MIN_SECONDS}-${VIDEO_MAX_SECONDS} seconds; `
+            + `got ${JSON.stringify(String(args.videoDuration))}. Video-to-motion needs at least `
+            + `${MOTION_SOURCE_MIN_SECONDS}s of footage to read.`);
+    }
+    // The clip half is validated by the same rules --video uses. No videoPath and
+    // no videoUrl yet: the first leg fills videoUrl in once it has produced one.
+    return { description: args.videoPrompt.trim(), durationSeconds, run: buildClipFlags(args) };
+}
+/** `--video` takes either a local file or an already-public clip URL. */
+export function isHttpUrl(value) {
+    try {
+        const { protocol } = new URL(value);
+        return protocol === 'http:' || protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * `--video` is a different generator from the authored spec: the clip comes from a person, not
  * a parameter file, so the two flag sets cannot be combined and the spec flags are refused here
@@ -262,6 +318,20 @@ export function buildAnimationVideoRun(args) {
     if (args.spec !== undefined || args.family !== undefined) {
         throw new CliError('--video cannot be combined with --spec or --family: a video clip is not authored from a spec.');
     }
+    if (args.videoPrompt !== undefined) {
+        throw new CliError('--video and --video-prompt cannot be combined: pass a clip you have, or describe one to generate.');
+    }
+    return {
+        // A URL is handed straight to the job; only a local file needs uploading.
+        ...(isHttpUrl(args.video) ? { videoUrl: args.video } : { videoPath: args.video }),
+        ...buildClipFlags(args),
+    };
+}
+/**
+ * The flags that describe the CLIP rather than where it came from, shared by
+ * `--video` and `--video-prompt` so the two lanes cannot drift apart.
+ */
+function buildClipFlags(args) {
     if (args.slot !== undefined && !isLocomotionState(args.slot)) {
         throw new CliError(`--slot must be one of ${LOCOMOTION_STATES.join(', ')}; got ${JSON.stringify(args.slot)}.`);
     }
@@ -283,7 +353,6 @@ export function buildAnimationVideoRun(args) {
         }
     }
     return {
-        videoPath: args.video,
         ...(args.name !== undefined ? { name: args.name } : {}),
         ...(args.model !== undefined ? { model: args.model } : {}),
         ...(args.loop !== undefined ? { loop: args.loop } : {}),
@@ -294,7 +363,14 @@ export function buildAnimationVideoRun(args) {
         ...(args.assetId !== undefined ? { assetId: args.assetId } : {}),
     };
 }
-const defaultDeps = (json) => commandRunDeps(json);
+const defaultDeps = (json) => ({
+    ...commandRunDeps(json),
+    interactive: isInteractive,
+    ask: askOnStdin,
+    // Same seam the cover lane uses: draws only where the terminal speaks the protocol,
+    // and the sheet's path is printed either way.
+    renderImage: (bytes) => renderInlineImage(bytes),
+});
 /** Said once every long-form generation lands, so the creator knows not to reload by hand. */
 const DEV_VIEW_RELOADS = 'A running `bitmagic dev` reloads the browser by itself to show it.';
 /**
@@ -623,6 +699,37 @@ const MATERIALS_FLAG = {
     description: 'Decide what the asset is made of after the bake, so metal shines and glass '
         + 'reflects. Pass --no-materials to leave it plain; `bitmagic assets materials` edits it later.',
 };
+/**
+ * The mesh-KEEPING pair, `generate prop|model`'s answer to `assets add --keep-glb` / `--voxelize`.
+ * Neither is needed in the common case: a low-poly project (game.json `artStyle`) keeps, a voxel
+ * project bakes. They exist for the one prop that goes the other way.
+ */
+const KEEP_GLB_FLAG = {
+    type: 'boolean',
+    description: 'Keep the generated mesh as a polygon-mesh asset instead of voxelizing it '
+        + '(the default when game.json artStyle is low-poly). Implies --mesh; no browser is needed.',
+};
+const VOXELIZE_FLAG = {
+    type: 'boolean',
+    description: 'Voxelize even in a low-poly project.',
+};
+/**
+ * Whether a generated mesh is kept: the flags when given, else the project's art style. Says so
+ * only when the style decided, so a voxel project's transcript is unchanged.
+ */
+function resolveKeepGlb(root, options, log) {
+    if (options.keepGlb === true && options.voxelize === true) {
+        throw new CliError('Pass either --keep-glb or --voxelize, not both. world.json is unchanged.');
+    }
+    if (options.keepGlb === true)
+        return true;
+    if (options.voxelize === true)
+        return false;
+    if (resolveArtStyle(root, log) !== 'low-poly')
+        return false;
+    log('Keeping the mesh: game.json artStyle is low-poly (pass --voxelize to bake it instead).');
+    return true;
+}
 /** The voxel path's `--glb-url`: a paid-for master to bake, instead of buying another. */
 const MASTER_URL_FLAG = {
     type: 'string',
@@ -646,9 +753,10 @@ function classifyGeneratedAsset(input) {
  * or an asset with no `fitBox` costs nothing.
  */
 export async function runPropGeneration(options) {
-    assertVoxelGridAllowed(options.voxelGrid, options.mesh === true);
+    assertVoxelGridAllowed(options.voxelGrid, options.mesh === true || options.keepGlb === true);
     assertOneRetrySource(options.glbUrl, options.masterUrl);
     const { output, runDeps, context, environment, token } = await resolveRun(options.json, options.deps);
+    const keepGlb = resolveKeepGlb(context.root, options, runDeps.log);
     const result = await withJobRecord({
         root: context.root,
         kind: 'prop',
@@ -670,6 +778,8 @@ export async function runPropGeneration(options) {
                 ...(options.masterUrl ? { masterUrl: options.masterUrl } : {}),
                 ...(options.mesh === true ? { mesh: true } : {}),
                 ...(options.voxelGrid !== undefined ? { voxelGrid: options.voxelGrid } : {}),
+                ...(keepGlb ? { keepGlb: true } : {}),
+                ...(runDeps.keepGlbUpload !== undefined ? { keepGlbUpload: runDeps.keepGlbUpload } : {}),
                 fetchImpl: runDeps.fetch,
                 log,
             });
@@ -680,12 +790,13 @@ export async function runPropGeneration(options) {
     });
     runDeps.log(`Upgraded "${result.assetName}" — ${result.instanceCount} placed instance`
         + `${result.instanceCount === 1 ? '' : 's'} now use the generated version.`);
-    const materials = options.materials === false
+    // Materials name what each colour group of a VOXEL asset is made of; a kept mesh has its own.
+    const materials = options.materials === false || keepGlb
         ? null
         : await classifyGeneratedAsset({ context, environment, token, assetId: result.assetId, runDeps });
     // `result` already carries glbUrl, so a retry after a later failure can find the paid-for mesh
     // in the JSON document rather than only in the error text.
-    output.result({ ok: true, kind: 'prop', ...result, ...(materials === null ? {} : { materials }) });
+    output.result({ ok: true, kind: 'prop', ...result, ...(keepGlb ? { keptMesh: true } : {}), ...(materials === null ? {} : { materials }) });
     runDeps.log(DEV_VIEW_RELOADS);
     return result;
 }
@@ -699,6 +810,14 @@ export async function runPropGeneration(options) {
  * prompt nor a preset, which is refused here before anything is spent.
  */
 export async function runVehicleGeneration(options) {
+    {
+        // A vehicle is voxel-native (its builder and finishes assume six face normals), so a low-poly
+        // project gets one anyway — said once, so the mismatch is a known choice rather than a surprise.
+        const root = findProjectRootOrNull();
+        if (root !== null && resolveArtStyle(root) === 'low-poly') {
+            process.stderr.write('note: vehicles are always voxelized; this low-poly project (game.json artStyle) will get a voxel car.\n');
+        }
+    }
     if (options.prompt === undefined && options.presetName === undefined && options.glbUrl === undefined) {
         throw new CliError('Provide --prompt to design a vehicle, or --preset to build a standard one. '
             + 'Run `bitmagic generate vehicle --preset ?` to see the preset names.');
@@ -759,9 +878,10 @@ export async function runVehicleGeneration(options) {
  * has no instances yet and scales to `--height` (or the mesh's own size) instead.
  */
 export async function runModelGeneration(options) {
-    assertVoxelGridAllowed(options.voxelGrid, options.mesh === true);
+    assertVoxelGridAllowed(options.voxelGrid, options.mesh === true || options.keepGlb === true);
     assertOneRetrySource(options.glbUrl, options.masterUrl);
     const { output, runDeps, context, environment, token } = await resolveRun(options.json, options.deps);
+    const keepGlb = resolveKeepGlb(context.root, options, runDeps.log);
     const result = await withJobRecord({
         root: context.root,
         kind: 'model',
@@ -790,6 +910,8 @@ export async function runModelGeneration(options) {
                 },
                 fetchImpl: runDeps.fetch,
                 ...(runDeps.voxelize !== undefined ? { voxelize: runDeps.voxelize } : {}),
+                ...(keepGlb ? { keepGlb: true } : {}),
+                ...(runDeps.keepGlbUpload !== undefined ? { keepGlbUpload: runDeps.keepGlbUpload } : {}),
                 log,
             });
         }
@@ -798,9 +920,11 @@ export async function runModelGeneration(options) {
         }
     });
     runDeps.log(`Added "${result.assetName}" (id ${result.assetId})`
-        + `${result.voxelCount !== undefined ? `, ${result.voxelCount} voxels` : ''}. Place it from game `
+        + `${result.voxelCount !== undefined ? `, ${result.voxelCount} voxels` : ''}`
+        + `${result.keptMesh === true ? ', kept as a polygon mesh' : ''}. Place it from game `
         + 'code, or drag it in from the dev view\'s Add-object palette.');
-    const materials = options.materials === false
+    // Materials name what each colour group of a VOXEL asset is made of; a kept mesh has its own.
+    const materials = options.materials === false || keepGlb
         ? null
         : await classifyGeneratedAsset({ context, environment, token, assetId: result.assetId, runDeps });
     // `result` carries whichever source was paid for — glbUrl or masterUrl — so a retry after a
@@ -1100,6 +1224,15 @@ const characterCommand = defineCommand({
             type: 'boolean',
             negativeDescription: 'Always make a new character; do not use a ready-made one from the library.',
         },
+        voxelize: {
+            type: 'boolean',
+            description: 'Voxelize the rigged body. Omit to follow game.json artStyle: voxel games voxelize, low-poly games keep the textured rig.',
+            negativeDescription: 'Keep the textured low-poly rig instead of voxelizing it.',
+        },
+        'mesh-model': {
+            type: 'string',
+            description: "Image-to-mesh model. Low-poly characters already default to 'runware-meshy-6' (~$0.80, ~6 min); pass 'unified-trellis' to put one back on the cheap lane. Voxel characters ignore the default and use the Forger's.",
+        },
         'original-prompt': ORIGINAL_PROMPT_FLAG,
         json: JSON_FLAG,
     },
@@ -1110,6 +1243,8 @@ const characterCommand = defineCommand({
             applyToPlayer: args['apply-to-player'],
             headScale: args['head-scale'],
             library: args.library,
+            voxelize: args.voxelize ?? defaultVoxelizeForProject(),
+            meshModel: args['mesh-model'],
         });
         await runAssetGeneration('character', 'character', withParent(body), args.json === true);
     },
@@ -1164,25 +1299,53 @@ const animationCommand = defineCommand({
         video: {
             type: 'string',
             description: `Make the clip from a video of one person instead of a spec (Uthana video-to-motion, costs sparks). `
-                + `${VIDEO_EXTENSIONS.map((e) => `.${e}`).join('/')}, 2-60 s, full body in frame. Cannot be combined with --spec/--family.`,
+                + `A local ${VIDEO_EXTENSIONS.map((e) => `.${e}`).join('/')} file, or an http(s) URL of one already uploaded. `
+                + `2-60 s, full body in frame. Cannot be combined with --spec/--family/--video-prompt.`,
+        },
+        'video-prompt': {
+            type: 'string',
+            description: 'Describe a motion and have the source clip generated instead of filmed '
+                + '(costs sparks for both the clip and the motion). The clip is framed automatically for '
+                + 'capture: one person, whole body in shot, static camera. Cannot be combined with '
+                + '--video/--spec/--family.',
+        },
+        'contact-sheet': {
+            type: 'boolean',
+            default: true,
+            description: 'Grab 8 frames of the generated source clip into a PNG under .bitmagic/videos/ '
+                + 'so it can be reviewed before the capture leg spends (the default; with --video-prompt). '
+                + 'Pass --no-contact-sheet to skip the download; needs ffmpeg.',
+        },
+        yes: {
+            type: 'boolean',
+            description: 'Skip the clip review with --video-prompt and capture motion from whatever the '
+                + 'first leg produced. The review only happens at a terminal anyway, so agents and CI are '
+                + 'unaffected either way.',
+        },
+        'video-duration': {
+            type: 'string',
+            description: `Length of the generated source clip in seconds, ${MOTION_SOURCE_MIN_SECONDS}-${VIDEO_MAX_SECONDS} `
+                + `(default ${MOTION_SOURCE_DEFAULT_SECONDS}); with --video-prompt. Billed per second. Not --duration, which is `
+                + 'the authored-spec clip length.',
         },
         model: {
             type: 'string',
-            description: `Video-to-motion model (with --video): ${VIDEO_TO_MOTION_MODELS.join(' | ')}.`,
+            description: `Video-to-motion model (with --video or --video-prompt): ${VIDEO_TO_MOTION_MODELS.join(' | ')}.`,
         },
         loop: {
             type: 'boolean',
-            description: 'Mark the clip as looping (with --video). Idle, walk and run clips should loop.',
+            description: 'Mark the clip as looping (with --video/--video-prompt). Idle, walk and run clips should loop.',
         },
         slot: {
             type: 'string',
-            description: `Pin the clip to a locomotion state for the player and every NPC (with --video): ${LOCOMOTION_STATES.join(' | ')}. `
+            description: `Pin the clip to a locomotion state for the player and every NPC (with --video/--video-prompt): ${LOCOMOTION_STATES.join(' | ')}. `
                 + 'Omit for a one-shot clip played with playCustomAnimation().',
         },
         'auto-trim': {
             type: 'boolean',
             description: 'Cut "walking to the camera" frames off both ends of the video before the motion is made (with --video). '
-                + 'Useful for clips recorded webcam-style; the dev-view recorder instead confirms an explicit window.',
+                + 'Useful for clips recorded webcam-style; the dev-view recorder instead confirms an explicit window. '
+                + 'A generated --video-prompt clip has no such frames, so it rarely needs this.',
         },
         'trim-start': {
             type: 'string',
@@ -1197,6 +1360,25 @@ const animationCommand = defineCommand({
         json: JSON_FLAG,
     },
     async run({ args }) {
+        if (args['video-prompt'] !== undefined) {
+            const run = buildAnimationFromPromptRun({
+                videoPrompt: args['video-prompt'],
+                videoDuration: args['video-duration'] !== undefined ? Number(args['video-duration']) : undefined,
+                video: args.video,
+                name: args.name,
+                model: args.model,
+                loop: args.loop === true ? true : undefined,
+                slot: args.slot,
+                autoTrim: args['auto-trim'] === true ? true : undefined,
+                trimStart: args['trim-start'] !== undefined ? Number(args['trim-start']) : undefined,
+                trimEnd: args['trim-end'] !== undefined ? Number(args['trim-end']) : undefined,
+                assetId: args['asset-id'],
+                spec: args.spec,
+                family: args.family,
+            });
+            await runAnimationFromPrompt(run, args.json === true, undefined, creatorPromptField(args).creatorPrompt, { yes: args.yes === true, contactSheet: args['contact-sheet'] !== false });
+            return;
+        }
         if (args.video !== undefined) {
             const run = buildAnimationVideoRun({
                 video: args.video,
@@ -1236,7 +1418,7 @@ const animationCommand = defineCommand({
  */
 export async function runAnimationFromVideo(run, json, deps) {
     const { output, runDeps, context, environment, token } = await resolveRun(json, deps);
-    const label = run.name ?? path.basename(run.videoPath);
+    const label = run.name ?? (run.videoPath !== undefined ? path.basename(run.videoPath) : 'Recorded motion');
     const result = await withJobRecord({
         root: context.root, kind: 'animation-video', label, log: runDeps.log,
     }, async (log) => {
@@ -1272,6 +1454,162 @@ export async function runAnimationFromVideo(run, json, deps) {
     });
     runDeps.log(DEV_VIEW_RELOADS);
 }
+/**
+ * Look at the generated clip before the capture leg spends on it.
+ *
+ * The clip costs a few sparks and the Uthana leg costs fifteen more, so the expensive half is the
+ * one worth gating. What decides "is this usable" is visible in stills — is it one person, are they
+ * whole and centred, did the model cut to a close-up halfway — so the contact sheet
+ * `generate video` already writes is enough to judge it, and the clip is a real asset by now, so a
+ * creator who wants to watch it move can do that in the dev view while this waits.
+ *
+ * Returns whether to go on. Everything except the question is best-effort: a missing ffmpeg or a
+ * failed download costs a note, never the generation that has already been paid for.
+ */
+export async function confirmSourceClip(options) {
+    const { deps } = options;
+    const review = !options.contactSheet ? null : await reviewGeneratedClip({
+        root: options.root,
+        assetId: options.assetId,
+        videoUrl: options.videoUrl,
+        durationSeconds: options.durationSeconds,
+        fetch: deps.fetch,
+    });
+    if (review !== null && review.sheetPath !== null) {
+        deps.log(`Frames: ${review.sheetPath}`);
+        // Additional, never instead of: the path is printed above whether or not the
+        // terminal can draw, exactly as the cover lane does it.
+        if (deps.renderImage !== undefined) {
+            try {
+                deps.renderImage(fs.readFileSync(review.sheetPath));
+            }
+            catch {
+                // A sheet that cannot be re-read is not worth failing a paid generation over.
+            }
+        }
+    }
+    for (const note of review?.notes ?? [])
+        deps.log(`  ${note}`);
+    deps.log(`The clip is already an asset — watch it play in the dev view (${options.assetId}).`);
+    if (options.skipPrompt)
+        return true;
+    const ask = deps.ask ?? askOnStdin;
+    return isAffirmative(await ask('Capture motion from this clip? [y/N] '));
+}
+/**
+ * The `--video-prompt` lane: text -> clip -> motion, the two existing job lanes run back to back.
+ *
+ * There is no chained endpoint behind this — asset-forger has one route that makes a video and
+ * another that reads one, and this is the seam between them. Both legs bill under their own
+ * existing key (`generate-video` per second, `generate-animation-from-video` flat), the way
+ * design-vehicle prices its chained image sub-generations rather than minting a composite.
+ *
+ * Both asset rows are kept. The clip is a real `type: 'video'` asset the creator can play back
+ * or reuse as a cutscene, and keeping it is also what makes a leg-2 failure recoverable: the
+ * footage is already paid for, so the error hands back a `--video <url>` retry instead of asking
+ * for the whole thing again.
+ */
+export async function runAnimationFromPrompt(prompt, json, deps, creatorPrompt, options = {}) {
+    const { output, runDeps, context, environment, token } = await resolveRun(json, deps);
+    const label = prompt.run.name ?? prompt.description;
+    const video = await withJobRecord({
+        root: context.root, kind: 'video', label: `${label} (motion source)`, log: runDeps.log,
+    }, async (log) => {
+        try {
+            return await generateAndInstallVideo({
+                context, environment, token,
+                run: {
+                    prompt: buildMotionSourcePrompt(prompt.description),
+                    durationSeconds: prompt.durationSeconds,
+                    name: `${label} (motion source)`,
+                    ...(creatorPrompt !== undefined ? { creatorPrompt } : {}),
+                },
+                deps: { fetch: runDeps.fetch, sleep: runDeps.sleep, log },
+            });
+        }
+        catch (error) {
+            throw decoratedError(error, (message) => message);
+        }
+    });
+    runDeps.log(`Source clip generated (${video.durationSeconds.toFixed(1)}s): ${video.videoUrl}`);
+    /*
+     * Nobody to ask means go on, rather than refuse: this lane is run by agents and by CI, and
+     * blocking there would hang on a stdin that never answers. `--json` is the declared agent
+     * signal, and its stdout carries one document, so it is not a place to hold a conversation.
+     */
+    const interactive = (runDeps.interactive ?? isInteractive)();
+    const skipPrompt = options.yes === true || json || !interactive;
+    const proceed = await confirmSourceClip({
+        root: context.root,
+        assetId: video.assetId,
+        videoUrl: video.videoUrl,
+        durationSeconds: video.durationSeconds,
+        skipPrompt,
+        contactSheet: options.contactSheet !== false,
+        deps: runDeps,
+    });
+    if (!proceed) {
+        // Declining is a decision, not a failure: the clip was made, billed and kept, so this
+        // exits clean and says what it costs to change your mind.
+        runDeps.log('Stopped before capturing motion — the video-to-motion charge was not made.');
+        runDeps.log(`The clip is kept as asset "${video.assetId}". Capture from it later with:`);
+        runDeps.log(`  bitmagic generate animation --video ${video.videoUrl} --name ${JSON.stringify(label)}`);
+        output.result({
+            ok: true,
+            kind: 'video',
+            reviewed: 'declined',
+            assetId: video.assetId,
+            videoUrl: video.videoUrl,
+            durationSeconds: video.durationSeconds,
+            sparksCharged: video.sparksCharged,
+            patchesApplied: video.patchesApplied,
+        });
+        runDeps.log(DEV_VIEW_RELOADS);
+        return;
+    }
+    const motion = await withJobRecord({
+        root: context.root, kind: 'animation-video', label, log: runDeps.log,
+    }, async (log) => {
+        try {
+            return await generateAndInstallAnimationFromVideo({
+                context, environment, token,
+                run: { ...prompt.run, videoUrl: video.videoUrl, name: label },
+                deps: { fetch: runDeps.fetch, sleep: runDeps.sleep, log },
+            });
+        }
+        catch (error) {
+            // The clip survived and is already an asset, so say what it costs to pick
+            // up from here rather than letting the creator re-buy the footage.
+            throw decoratedError(error, (message) => `${message}\n`
+                + `The source clip was kept as asset "${video.assetId}". Retry the motion without `
+                + `regenerating it:\n  bitmagic generate animation --video ${video.videoUrl} --name ${JSON.stringify(label)}`);
+        }
+    });
+    const sparksCharged = video.sparksCharged + motion.sparksCharged;
+    const patchesApplied = video.patchesApplied + motion.patchesApplied;
+    runDeps.log(`Generated animation "${label}" from a generated clip (${motion.durationSeconds.toFixed(1)}s)${describeAutoTrim(motion)}: ${motion.animationUrl}`);
+    runDeps.log(`  - motionId ${motion.motionId}${motion.locomotionState ? ` — pinned to ${motion.locomotionState}` : ''}`);
+    runDeps.log(`  - source clip asset ${video.assetId}`);
+    runDeps.log(`world.json updated (${patchesApplied} patch${patchesApplied === 1 ? '' : 'es'}).`);
+    if (!motion.locomotionState) {
+        runDeps.log(`Play it with playCustomAnimation("${motion.motionId}"), or re-run with --slot idle|walk|run to make it locomotion.`);
+    }
+    output.result({
+        ok: true,
+        kind: 'animation',
+        motionId: motion.motionId,
+        animationUrl: motion.animationUrl,
+        durationSeconds: motion.durationSeconds,
+        sourceVideoAssetId: video.assetId,
+        sourceVideoUrl: video.videoUrl,
+        ...(motion.trimmedStartSeconds !== undefined ? { trimmedStartSeconds: motion.trimmedStartSeconds } : {}),
+        ...(motion.trimmedEndSeconds !== undefined ? { trimmedEndSeconds: motion.trimmedEndSeconds } : {}),
+        ...(motion.locomotionState ? { locomotionState: motion.locomotionState } : {}),
+        sparksCharged,
+        patchesApplied,
+    });
+    runDeps.log(DEV_VIEW_RELOADS);
+}
 const videoCommand = defineCommand({
     meta: {
         name: 'video',
@@ -1304,6 +1642,12 @@ const videoCommand = defineCommand({
             type: 'string',
             description: 'Pre-minted asset_… id to store the clip under, so code already referencing it resolves.',
         },
+        'contact-sheet': {
+            type: 'boolean',
+            default: true,
+            description: 'Grab 8 frames into a PNG under .bitmagic/videos/ so the clip can be reviewed (the default). '
+                + 'Pass --no-contact-sheet to skip the download; needs ffmpeg.',
+        },
         'original-prompt': ORIGINAL_PROMPT_FLAG,
         json: JSON_FLAG,
     },
@@ -1321,15 +1665,15 @@ const videoCommand = defineCommand({
             ...(args['asset-id'] !== undefined ? { assetId: args['asset-id'] } : {}),
             ...creatorPromptField(args),
         };
-        await runVideoGeneration(run, args.json === true);
+        await runVideoGeneration(run, args.json === true, { contactSheet: args['contact-sheet'] !== false });
     },
 });
 /**
  * Job-shaped rather than streamed (see generate/video.ts), so it cannot share `runAssetGeneration`;
  * it does share the job record, so the dev view shows it beside every other generation.
  */
-export async function runVideoGeneration(run, json, deps) {
-    const { output, runDeps, context, environment, token } = await resolveRun(json, deps);
+export async function runVideoGeneration(run, json, options = {}) {
+    const { output, runDeps, context, environment, token } = await resolveRun(json, options.deps);
     const label = run.name ?? run.prompt;
     const result = await withJobRecord({
         root: context.root, kind: 'video', label, log: runDeps.log,
@@ -1349,7 +1693,32 @@ export async function runVideoGeneration(run, json, deps) {
         : '';
     runDeps.log(`Generated video "${label}" (${result.durationSeconds.toFixed(1)}s${shape}): ${result.videoUrl}`);
     runDeps.log(`world.json updated (${result.patchesApplied} patch${result.patchesApplied === 1 ? '' : 'es'}).`);
-    runDeps.log(`Play it with engine.playVideo("${result.assetId}").`);
+    const review = options.contactSheet === false
+        ? null
+        : await reviewGeneratedClip({
+            root: context.root,
+            assetId: result.assetId,
+            videoUrl: result.videoUrl,
+            durationSeconds: result.durationSeconds,
+            fetch: runDeps.fetch,
+        });
+    if (review !== null) {
+        if (review.sheetPath !== null)
+            runDeps.log(`Frames: ${review.sheetPath}`);
+        // Silence is what decides whether the cutscene needs a music bed under it, and it is
+        // invisible in the frames — so it is said in words either way, never left to be assumed.
+        if (review.hasAudioTrack === false) {
+            runDeps.log('The clip has NO audio track — play a music bed under it if the cutscene needs sound.');
+        }
+        else if (review.hasAudioTrack === true) {
+            runDeps.log('The clip carries its own audio track.');
+        }
+        for (const note of review.notes)
+            runDeps.log(`  ${note}`);
+    }
+    runDeps.log(`Play it with engine.playVideo("${result.assetId}") — from the Play click or later, `
+        + 'never before: without a prior user gesture the browser blocks autoplay and the clip silently '
+        + 'does not run. See video-cutscenes.md.');
     output.result({
         ok: true,
         kind: 'video',
@@ -1361,6 +1730,8 @@ export async function runVideoGeneration(run, json, deps) {
         ...(result.height !== undefined ? { height: result.height } : {}),
         sparksCharged: result.sparksCharged,
         patchesApplied: result.patchesApplied,
+        ...(review?.sheetPath != null ? { contactSheetPath: review.sheetPath } : {}),
+        ...(review?.hasAudioTrack != null ? { hasAudioTrack: review.hasAudioTrack } : {}),
     });
     runDeps.log(DEV_VIEW_RELOADS);
 }
@@ -1386,6 +1757,8 @@ const propCommand = defineCommand({
         },
         'master-url': MASTER_URL_FLAG,
         mesh: MESH_FLAG,
+        'keep-glb': KEEP_GLB_FLAG,
+        voxelize: VOXELIZE_FLAG,
         'direct-voxels': DIRECT_VOXELS_FLAG,
         'voxel-grid': VOXEL_GRID_FLAG,
         materials: MATERIALS_FLAG,
@@ -1399,6 +1772,8 @@ const propCommand = defineCommand({
             ...(args['glb-url'] ? { glbUrl: args['glb-url'] } : {}),
             ...(args['master-url'] ? { masterUrl: args['master-url'] } : {}),
             ...(args.mesh === true ? { mesh: true } : {}),
+            ...(args['keep-glb'] === true ? { keepGlb: true } : {}),
+            ...(args.voxelize === true ? { voxelize: true } : {}),
             ...voxelGridField(args['voxel-grid']),
             ...(args.materials === false ? { materials: false } : {}),
             json: args.json === true,
@@ -1475,7 +1850,7 @@ const modelCommand = defineCommand({
         },
         height: {
             type: 'string',
-            description: 'Scale the model to this height in metres. Omit to keep the generated mesh\'s own size.',
+            description: 'Scale the model to this height in metres. Omit to keep the generated mesh\'s own size (2 m when the mesh is kept).',
         },
         hollow: {
             type: 'boolean',
@@ -1491,6 +1866,8 @@ const modelCommand = defineCommand({
         },
         'master-url': MASTER_URL_FLAG,
         mesh: MESH_FLAG,
+        'keep-glb': KEEP_GLB_FLAG,
+        voxelize: VOXELIZE_FLAG,
         'direct-voxels': DIRECT_VOXELS_FLAG,
         'voxel-grid': VOXEL_GRID_FLAG,
         materials: MATERIALS_FLAG,
@@ -1523,6 +1900,8 @@ const modelCommand = defineCommand({
             ...(args['glb-url'] !== undefined ? { glbUrl: args['glb-url'] } : {}),
             ...(args['master-url'] !== undefined ? { masterUrl: args['master-url'] } : {}),
             ...(args.mesh === true ? { mesh: true } : {}),
+            ...(args['keep-glb'] === true ? { keepGlb: true } : {}),
+            ...(args.voxelize === true ? { voxelize: true } : {}),
             ...voxelGridField(args['voxel-grid']),
             ...(args.materials === false ? { materials: false } : {}),
             json: args.json === true,