@genex-ai/cli-demo 1.11.1-dev.539 → 1.11.3-dev.541

package/dist/index.js

@@ -972,6 +972,7 @@ Important note: put soul into your creations, with many details and love. Aim to
 17. Input directions match their labels: A/\u2190 moves or turns the player screen-LEFT, D/\u2192 screen-RIGHT, mouse-up looks up, and drag-pan axes share ONE convention. The cursor is either the gameplay tool (RTS, card, builder) or locked away during play \u2014 keyboard-only games included. Check it in every milestone's smoke pass.
 18. NEVER delete, empty, move, rename, or overwrite anything you did not create yourself. This folder may hold the player's own reference images, notes, sketches, or an earlier attempt \u2014 files that exist nowhere else and have no undo, no trash, no backup. A non-empty folder is normal and is NEVER something to clean up, and "start clean" is never a reason. That rules out \`rm\`/\`rm -rf\`, \`git clean\`, \`git checkout -- .\`, \`git reset --hard\` over their work, deleting to resolve a conflict or a stuck interactive prompt, and every setup tool's offer to empty a directory (\`--force\`, \`--overwrite\`, "Remove existing files") \u2014 scaffold into a fresh subfolder and copy in instead. You may add files and edit the ones you wrote. If a step genuinely cannot continue without removing something of theirs, STOP and ask, naming the exact files, and wait for a yes \u2014 "it looks like junk" is never that yes. This binds hardest during setup, where it runs fast and automatically before the player has asked for anything at all.
 19. If the game sells anything, it sells it for coin at a fixed, visible price, and NEVER sells chance. Run this test on any purchasable thing before building it: does the player pay (with coin, or with anything coin bought, directly or indirectly), is the outcome uncertain when they pay, and is there a prize they wanted \u2014 all three yes means it is paid randomness, and you build the deterministic version instead. That rules out loot boxes, gacha, mystery boxes, crates, card packs, prize wheels and raffles; wagering, staking, betting, coinflips and casino or slot mechanics denominated in coin; and donation prompts, tip jars or any player-to-player coin transfer, because coin buys goods and never just moves. Randomness the player EARNS by playing is gameplay, not commerce \u2014 an enemy dropping a random item, a chest found in the level, a procedural layout, a crit roll \u2014 and is completely fine. Every coin price renders its real-money equivalent beside it (the server sends one with every item), item prices sit on the platform's price grid so no player is left holding change they cannot spend, and nothing in a shop carries a countdown, "limited time", or a stock counter. When a request crosses one of these lines, name the mechanic, give the one-sentence reason, propose a specific compliant alternative, and build that \u2014 never the banned version "as an option", never a partial one, and never after asking the player to confirm they want it. Load \`$genex-monetization\` before building a shop.
+20. When the player names a specific thing to integrate \u2014 a library, a controller, an asset, a part of an existing game, or a tagged reference the platform placed in \`.genex/refs/<slug>/\` \u2014 integrate the real thing: read its source first and build from it, never a lighter look-alike written from scratch because it was faster. A tagged reference owns the subsystem it was tagged for, outranking the default lane and the vendored controllers for that subsystem. If you genuinely can't use it, say so in one plain line and ask how to proceed.
 ${CONTRACT_END}
 `;
 var GENEX_TOOLS_CONTRACT_BLOCK = `${CONTRACT_BEGIN}
@@ -6160,7 +6161,8 @@ async function detectSurfaceScan(cwd = process.cwd()) {
     squarePoints: [],
     depthRange: [],
     mediaElementAudio: [],
-    deferredAudioContext: []
+    deferredAudioContext: [],
+    usesThree: false
   };
   const srcDir = path17.join(cwd, "src");
   let entries;
@@ -6208,6 +6210,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 +6379,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 +7409,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 +21904,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 +22109,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 +22170,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 +22252,7 @@ function parseArgs(argv) {
     "--voice",
     "--voice-id",
     "--frame",
+    "--start-frame",
     "--first-frame",
     "--last-frame",
     "--ref",
@@ -22716,6 +22786,7 @@ function applyValueFlag(options, flag, value) {
     case "--video":
       options.video = value;
       break;
+    case "--start-frame":
     case "--first-frame":
       options.firstFrameUrl = value;
       break;
@@ -22777,7 +22848,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.3-dev.541",
   "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-game-director/SKILL.md

@@ -54,6 +54,10 @@ Use the request in front of you, not the oldest description of the project.
   invent or propose game concepts for them.
 - **Existing project** respects its renderer, physics, file conventions, and
   working systems unless the player asks to change them.
+- **A tagged reference** (source under `.genex/refs/<slug>/`) owns the
+  subsystem it was tagged for: read its `_map.md` and implementing files
+  before choosing a lane — it outranks the default lane, including the
+  vendored controllers, for that subsystem.
 
 Ask one decision at a time. Never ask the player to choose an SDK, engine,
 renderer, file layout, provider, or other implementation detail. Product

package/templates/skills/genex-game-director/references/routing-map.md

@@ -28,6 +28,9 @@ copy demo architecture.
   3D,” ask one plain question: normal generated GLB, or editable parameterized
   Three.js code? Explicit `GLB`, `procedural`, `parametric`, `code-built`, or
   `variations` language chooses directly.
+- **Tagged reference:** source under `.genex/refs/<slug>/` owns the subsystem
+  it was tagged for — read its `_map.md` and implementing files before choosing
+  a lane; it outranks the default lane, vendored controllers included.
 
 ## Route by system
 

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.