@genex-ai/cli-demo 1.11.1-dev.539 → 1.11.2-dev.540

package/dist/index.js

@@ -6160,7 +6160,8 @@ async function detectSurfaceScan(cwd = process.cwd()) {
     squarePoints: [],
     depthRange: [],
     mediaElementAudio: [],
-    deferredAudioContext: []
+    deferredAudioContext: [],
+    usesThree: false
   };
   const srcDir = path17.join(cwd, "src");
   let entries;
@@ -6208,6 +6209,7 @@ async function detectSurfaceScan(cwd = process.cwd()) {
         ratio
       });
     }
+    if (/\bfrom\s*["']three(?:\/[^"']*)?["']/.test(content)) found.usesThree = true;
     const threeAudioImport = /import\s+(?:type\s+)?\{[^}]*\bAudio\b[^}]*\}\s+from\s*["']three["']/.test(
       content
     );
@@ -6376,8 +6378,9 @@ function surfaceNudges(log, s) {
   }
   if (s.mediaElementAudio.length) {
     const list = s.mediaElementAudio.map((d) => `${d.where} \u2014 ${d.detail}`).join("; ");
+    const fix = s.usesThree ? `THREE.Audio/PositionalAudio on one AudioListener have none of this \u2014 genex-ai-sfx ships the pooled one-shot, the live-value loop, and the decode-during-the-menu preload.` : `Plain WebAudio has none of this \u2014 one AudioContext (created inside the first user gesture), fetch + decodeAudioData during the menu, an AudioBufferSourceNode per one-shot, and a GainNode per live value. A music bed that only plays/pauses MAY stay an <audio> element; anything whose volume or rate tracks gameplay must not.`;
     log.warn(
-      `HTML <audio> elements are carrying this game's sound: ${list}. On iPhone an <audio> element is a handle on the operating system's media pipeline in ANOTHER PROCESS: every write to .volume or .playbackRate is a cross-process call, and play() is slow and asynchronous. A sound driven from a live value \u2014 wheels from speed, engine from RPM \u2014 writes 60-120 of those a second and stutters the whole game, while one-shots arrive late. It disguises itself as a graphics problem perfectly: only while moving, identical at every quality setting, desktop fine. THREE.Audio/PositionalAudio on one AudioListener have none of this \u2014 genex-ai-sfx ships the pooled one-shot, the live-value loop, and the decode-during-the-menu preload.`
+      `HTML <audio> elements are carrying this game's sound: ${list}. On iPhone an <audio> element is a handle on the operating system's media pipeline in ANOTHER PROCESS: every write to .volume or .playbackRate is a cross-process call, and play() is slow and asynchronous. A sound driven from a live value \u2014 wheels from speed, engine from RPM \u2014 writes 60-120 of those a second and stutters the whole game, while one-shots arrive late. It disguises itself as a graphics problem perfectly: only while moving, identical at every quality setting, desktop fine. ${fix}`
     );
   }
   if (s.deferredAudioContext.length) {
@@ -7405,6 +7408,20 @@ async function runGenerate(kind, opts) {
     }
     opts = { ...opts, frameUrl: inlined.dataUri };
   }
+  for (const [field, flag] of [
+    ["firstFrameUrl", "--start-frame/--first-frame"],
+    ["lastFrameUrl", "--last-frame"]
+  ]) {
+    const ref = opts[field];
+    if (kind !== "video" || !ref || isRemoteRef(ref)) continue;
+    const inlined = await inlineLocalImage(ref, flag);
+    if (!inlined.ok) {
+      log.error(inlined.error);
+      process.exitCode = 1;
+      return;
+    }
+    opts = { ...opts, [field]: inlined.dataUri };
+  }
   if (kind === "video" && opts.refs?.length) {
     const refs = [];
     for (const ref of opts.refs) {
@@ -21886,8 +21903,13 @@ ${c.bold("Options for the generators (`model` `sfx` `music` `voice` `texture` `i
                        it, model default).
   --frame <url|file>   (video) animate from THIS frame back to itself (seamless
                        loop) \u2014 an asset URL or a local image file (\u22644 MB).
-  --first-frame <url>  (video) start frame for a two-frame motion \u2026
-  --last-frame <url>   (video) \u2026 and its end frame.
+  --start-frame <url|file>  (video) continue from this exact frame, no end
+                       anchor \u2014 the clip-chaining primitive: extract the last
+                       frame of the previous clip (ffmpeg) and pass it here.
+                       Anchors are compositional guidance, not pixel-pinning;
+                       chain from REAL extracted frames so drift can't stack.
+  --first-frame <url|file>  (video) start frame; alone it means --start-frame \u2026
+  --last-frame <url|file>   (video) \u2026 add this to also anchor the end frame.
   --ref <url|file>     (video, repeatable \xD79) subject/style reference images \u2014
                        cite them in the prompt as "Image 1"\u2026"Image N"; keeps
                        the same character/style across many clips. Cannot be
@@ -22086,7 +22108,8 @@ ${c.bold("Generate")}                                                        typ
       --transparent                  \u2026with a real alpha channel (sprites, icons, logos).
       --edit <path|url>              \u2026edit an existing image with the prompt.
       --remove-bg / --bg-mode <m>    \u2026cut the background (sprite|glyph|sheet|matte).
-  genex video "<prompt>"             A video (mp4). --loop, --frame <img>. ${cr("video")}
+  genex video "<prompt>"             A video (mp4). --loop, --frame <img>, ${cr("video")}
+                                     --start-frame <img> (continue a clip).
   genex texture "<prompt>"           A tiling PBR texture set. --terrain.  ${cr("texture")}
   genex sfx "<prompt>"               A sound effect (mp3). --duration.     ${cr("sfx")}
   genex music "<prompt>"             A looping instrumental track (mp3).   ${cr("music")}
@@ -22146,6 +22169,51 @@ ${c.bold("Examples")}
 Hosting, publishing, multiplayer, remixing and custom domains are the Genex
 platform \u2014 build a game there from one prompt: ${c.cyan("https://genex.games")}
 `;
+var COMMAND_HELP = {
+  video: `${c.bold("genex video")} \u2014 generate a video clip (mp4, MiniMax H3 Max \u2014 the flagship; plain H3 for seamless loops and 2k/4k; native stereo audio on every non-loop clip).
+
+${c.bold("Modes")}
+  genex video "<prompt>"                          text-to-video (16:9).
+  genex video "<prompt>" --start-frame <img>      continue from this frame \u2014 the
+                                                  clip-chaining primitive.
+  genex video "<prompt>" --frame <img>            animate from the frame back to
+                                                  itself (seamless loop; menus).
+  genex video "<prompt>" --first-frame <img> --last-frame <img>
+                                                  two-frame motion (both anchored).
+  genex video "<prompt>" --ref <img> [--ref \u2026\xD79]  same subject/style across many
+                                                  clips ("Image 1"\u2026"Image N").
+  genex video "<prompt>" --loop                   prompt-only seamless loop (no
+                                                  conditioning frame; Luma Ray-2).
+
+${c.bold("Flags")}
+  --start-frame <url|file>   continue-from anchor; local files inline (\u22644 MB).
+  --frame / --first-frame / --last-frame <url|file>   ditto.
+  --ref <url|file>           repeatable \xD79; not combinable with frames/--loop.
+  --duration <s>             5-15 (integer seconds; H3's own band). Default 5,
+                             loops/pairs 8. Longer scenes: chain clips.
+  --resolution <r>           480p | 768p (default, top native) | 2k | 4k.
+  --no-wait                  enqueue only; attach later with genex wait <id>.
+
+  Aspect: text/ref clips are 16:9. Frame-conditioned clips FOLLOW THE SOURCE
+  IMAGE \u2014 a square image (genex image --aspect square) yields a square video.
+
+${c.bold("Chaining clips (playable films, cutscene sequences)")}
+  Frame anchors are COMPOSITIONAL GUIDANCE, not pixel-pinning \u2014 the model
+  repaints the frame (measured ~21 dB vs the supplied image; identical would be
+  ~35-40 dB). Chains still hold if every clip starts from the PREVIOUS CLIP'S
+  REAL last frame, because drift never accumulates:
+    ffmpeg -sseof -0.2 -i prev.mp4 -update 1 -q:v 1 last.png
+    genex video "<what changes next>" --start-frame last.png
+  Cut clip-to-clip (or crossfade ~200 ms to hide the residual repaint). Keep
+  in-game <video> muted by default \u2014 every H3 clip carries audio.
+
+${c.bold("Content filter")}
+  The provider rejects anatomy-invasion phrasing (cables/wires/needles entering
+  a body) as body horror \u2014 describe the object or machine instead: "a
+  statue-like figure threaded into the wall" passes where "cables entering her
+  spine" fails. Rejections are never retryable; reword and re-run.
+`
+};
 function parseArgs(argv) {
   const parsed = {
     command: void 0,
@@ -22183,6 +22251,7 @@ function parseArgs(argv) {
     "--voice",
     "--voice-id",
     "--frame",
+    "--start-frame",
     "--first-frame",
     "--last-frame",
     "--ref",
@@ -22716,6 +22785,7 @@ function applyValueFlag(options, flag, value) {
     case "--video":
       options.video = value;
       break;
+    case "--start-frame":
     case "--first-frame":
       options.firstFrameUrl = value;
       break;
@@ -22777,7 +22847,8 @@ async function main() {
   const mode = await workspaceMode();
   setWorkspaceHeader(mode === "tools" ? "tools" : null);
   if (parsed.help || parsed.command === void 0) {
-    log.plain(mode === "tools" ? HELP_TOOLS : HELP);
+    const perCommand = parsed.command === void 0 ? void 0 : COMMAND_HELP[parsed.command];
+    log.plain(perCommand ?? (mode === "tools" ? HELP_TOOLS : HELP));
     return;
   }
   const isBlenderMcp = parsed.command === "blender" && parsed.options.name === "mcp";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "1.11.1-dev.539",
+  "version": "1.11.2-dev.540",
   "description": "Set up your project's agent workspace (.claude/.codex/.cursor in the game folder), authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

package/templates/skills/genex-ai-video/SKILL.md

@@ -146,8 +146,19 @@ See `$genex-threejs-multiplayer` for the `shared` channel rules and the room API
 - `--frame <url|file>` — one generated image (or a local file ≤4 MB) as BOTH
   first and last frame — the seamless-loop mode (motion must return to its
   start; the seam is mathematically exact).
-- `--first-frame <url>` / `--last-frame <url>` — two-frame motion between two
-  stills (a genuine state change — a door opens, day turns to night).
+- `--start-frame <url|file>` — continue from this frame, no end anchor — the
+  clip-chaining primitive (see below). Local files inline like `--frame`.
+- `--first-frame <url|file>` / `--last-frame <url|file>` — two-frame motion
+  between two stills (a genuine state change — a door opens, day turns to
+  night). `--first-frame` alone means `--start-frame`.
+
+**Frame anchors are compositional guidance, not pixel-pinning.** The model
+repaints every anchor — the clip's first frame lands near the supplied image
+(same scene, same composition) but not ON it, and regenerating doesn't change
+that; it is how the mode works. Plan for it: chains stay coherent when each
+clip starts from the previous clip's REAL frame (below), and a supplied
+`--last-frame` steers where motion ends rather than guaranteeing the exact
+pixels.
 - `--ref <url|file>` — repeatable, up to 9 subject/style reference images.
   Cite each in the prompt by its order: "Image 1 is the hero — she walks into
   frame…". This is how the SAME character or art style holds across many clips
@@ -168,8 +179,21 @@ evidence detective game, a video-book. The pattern that makes it hold together:
 - **Branching scenes**: generate one clip per story node at build time, ship
   the mp4 URLs in a scene-graph JSON, play them full-screen with DOM choice
   buttons; preload the clips reachable from the current node while it plays.
-- **Visual continuity**: chain scenes with `--frame`/`--first-frame` so each
-  clip opens where the last one ended.
+- **Visual continuity — chain from REAL frames**: extract the previous clip's
+  actual last frame and seed the next clip with it:
+
+  ```bash
+  ffmpeg -sseof -0.2 -i prev.mp4 -update 1 -q:v 1 last.png
+  npx genex video "she turns and walks toward the far door" --start-frame last.png
+  ```
+
+  Never chain from the image you WISHED the clip ended on — anchors are
+  repainted (above), so the wish and the clip disagree and every join jumps.
+  Chaining from the real frame keeps drift from accumulating; the residual
+  repaint at each cut is small, and a ~200 ms crossfade between the two
+  `<video>` elements hides it entirely. Write chained prompts as CHANGE ONLY
+  ("she turns…", "the light flickers out") — the start frame already says
+  everything else.
 - **Cast consistency**: give every scene the same `--ref` images of your
   protagonist and key locations — the single biggest quality lever for any
   multi-clip story.
@@ -181,6 +205,12 @@ evidence detective game, a video-book. The pattern that makes it hold together:
 - **"Not authorized"** — run `npx @genex-ai/cli-demo@dev init` first (it writes your `GENEX_TOKEN`).
 - **"Prompt rejected"** — the provider's content-safety filter blocked the prompt.
   This is non-retryable; retrying the same wording fails again. Rewrite the prompt.
+  The measured false-positive class is anatomy being pierced or entered
+  (cables/wires/needles into a body — biomech and cyberpunk vocabulary trips
+  it). Describe the object or machine instead of the anatomy: "a statue-like
+  figure threaded into the wall" passes where "cables entering her spine"
+  fails. Word it that way on the FIRST try — each rejection still ends a
+  billed-then-refunded round trip.
 - **Nothing plays / black surface** — the first `video.play()` must run inside a user
   gesture (click/keydown); confirm it's called and its promise rejection is logged.
 - **Tainted-source / security error** — set `video.crossOrigin = "anonymous"` before

package/templates/skills/genex-tool-video/SKILL.md

@@ -33,7 +33,22 @@ npx genex video "camera drifts slowly forward, banners stirring" --frame ./asset
 ```
 
 - `--frame <path|url>` — animate FROM this frame back to itself, i.e. a seamless loop. Local file (≤ 4 MB) or a previous generation's URL.
-- `--first-frame <url>` / `--last-frame <url>` — a two-frame motion between them.
+- `--start-frame <path|url>` — continue from this frame, no end anchor — the clip-chaining primitive.
+- `--first-frame <path|url>` / `--last-frame <path|url>` — a two-frame motion between them. All frame anchors take local files.
+
+Frame anchors are **compositional guidance, not pixel-pinning** — the model
+repaints the frame (same scene and composition, not the same pixels), and
+regenerating doesn't change that. Chained clips (a cutscene sequence, a
+branching video story) stay coherent when each clip starts from the previous
+clip's REAL last frame, so drift never accumulates:
+
+```bash
+ffmpeg -sseof -0.2 -i ./assets/prev.mp4 -update 1 -q:v 1 last.png
+npx genex video "she turns and walks toward the far door" --start-frame last.png
+```
+
+Write chained prompts as CHANGE ONLY — the start frame already says everything
+else. Cut clip-to-clip, or crossfade ~200 ms to hide the residual repaint.
 
 ## Options
 
@@ -61,5 +76,6 @@ command bills a NEW clip** — it is never a way to check on one already running
 ## Troubleshooting
 
 - **It failed** — video fails server-side more often than any other lane, and every attempt is minutes. The CLI counts failures in this folder and tells you when to stop: after the second, use a still image instead and say so in one plain line. A third attempt bills the same and returns the same.
+- **"Prompt rejected"** — the content-safety filter; never retryable with the same wording. The measured false-positive class is anatomy being pierced or entered (cables/wires/needles into a body — biomech vocabulary trips it). Describe the object or machine instead: "a statue-like figure threaded into the wall" passes where "cables entering her spine" fails.
 - **Out of credits** — the error prints balance, price and refill date. Relay it; don't retry.
 - **Anything else** — `npx genex doctor` reports sign-in, credits, and whether the video lane is live.