@genex-ai/cli-demo 0.48.0-dev.78 → 0.48.0-dev.80

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.48.0-dev.78",
+  "version": "0.48.0-dev.80",
   "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

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

@@ -28,6 +28,34 @@ ring) that no hand-written CSS can fake.
   the CSS placeholder, finished to `$genex-threejs-game-ui`'s Tier-1 floor,
   ships as the HUD.
 
+## Three layers — plates are DOM, chrome is sprites, data is DOM
+
+- **Plate (DOM).** The backing surface behind a widget is built in CSS — in
+  whatever register the brief and concept frame call for: smoked glass
+  (`background: rgba(<darkest hue>, 0.35–0.6)` + `backdrop-filter: blur(6–12px)`
+  and its `-webkit-` twin) when the style wants translucency, a solid painted
+  plate, a subtle gradient — or no plate at all for an outline-led look.
+  **Glass is a technique, not a default** — do not reach for translucency
+  because this skill mentions it; reach for it when THIS game's brief does.
+  What is fixed is WHERE plates are built — the DOM — because
+  semi-transparency physically cannot survive sprite extraction: a composited
+  panel's pixels are a blend of panel and background, and no cutout can
+  un-blend them. Plates are NEVER baked into sprites.
+- **Chrome (sprites — what THIS pipeline generates).** Opaque frames, corner
+  brackets, ornaments, emblems, icons, medallions — hard-alpha art laid over
+  the glass. The Stage-2 sheet contains ONLY chrome; never a panel with its
+  fill or glass surface baked in.
+- **Data (DOM).** Numbers, labels, and bar fills are DOM text and masked
+  fills (the fillBox pattern below) — always over the glass, never
+  rasterized into art.
+- **Micro-elements are designed, not defaulted.** The sheet excludes
+  primitive-only shapes (plain crosshair ticks, dots, pips) because CSS
+  renders them crisper — but CSS never means default: the reticle and every
+  cue, toast, and counter still get the brief's treatment (stroke weight,
+  glow, state changes — hit, low-ammo, empowered). An ornamented,
+  identity-bearing reticle (engraved ring, sculpted brackets) is chrome —
+  put it on the sheet like any other asset.
+
 ## Framing rules — internalize before prompting
 
 The HUD overlays a **live 3D scene**. The pixels between widgets show the game.
@@ -36,6 +64,11 @@ The HUD overlays a **live 3D scene**. The pixels between widgets show the game.
   fabric, wood board) as part of the HUD. Material aesthetics belong on the
   widget FRAMES — the HP bar frame is parchment, the minimap ring is leather —
   never on a screen-filling sprite.
+- **No plates in sprites.** Panel plates in the mockup — translucent or
+  solid — are welcome as the LOOK, but the Stage-2 asset list requests only
+  their opaque chrome (frame, brackets, ornament); the plate itself is
+  rebuilt at runtime in CSS matching the mockup's tint (see the three layers
+  above).
 - **4–7 widgets.** Fewer doesn't read as a HUD; more clutters the screen and
   burns generations.
 - **Every widget needs internal contrast** — a panel fill, outline stroke, or
@@ -92,7 +125,10 @@ and [references/stage2-prompt-template.md](references/stage2-prompt-template.md)
 **Order of work: kick Stage 1 off as your FIRST action after the UI plan
 gate**, then write the widget layout and wiring code (placement, masked-fill
 scaffolding, plain-CSS placeholder bars) while it renders — the CSS HUD keeps
-the game playable until the sprites land. Generate 2 mockup candidates in one
+the game playable until the sprites land. When the gate produced a concept
+frame, anchor Stage 1 to it — `--edit <concept-url>` holds the game's
+register far better than a text-only prompt; single-sprite regenerations
+anchor the same way. Generate 2 mockup candidates in one
 call (`--candidates 2`) and pick the better one: a re-roll costs the whole
 serial chain, a second candidate costs nothing extra in wall-clock.
 

package/templates/skills/genex-ai-hud/references/stage2-prompt-template.md

@@ -15,6 +15,10 @@ Fill `[ASSET_LIST]`, then pass the whole text as the prompt to
   identity labels);
 - **states what to REMOVE** (`runtime_static` labels and `runtime_dynamic`
   values, fills, items);
+- **requests chrome only** — never a panel's plate/backing surface,
+  translucent or solid: plates are rebuilt at runtime in CSS (rgba,
+  backdrop-filter, or a solid fill — whatever matches the mockup), so ask
+  for the panel's frame/brackets/ornament, not the panel surface itself;
 - **requests the annotated duplicate** for every bar/meter frame (the
   template's progress block below covers the mechanics — your item just says
   "output the clean frame + annotated duplicate pair").
@@ -61,7 +65,7 @@ DO NOT include in the output sheet:
 - Simple dot indicators, status pips, blip markers
 - Fills inside bars, items inside slots, map terrain inside minimap rings (these are added at runtime by CSS / game code)
 
-Those excluded elements will be recreated by runtime code (CSS shapes and DOM text) — much crisper than a downsampled PNG.
+Those excluded elements will be recreated by runtime code (CSS shapes and DOM text) — much crisper than a downsampled PNG. Recreated does NOT mean default-styled: reticles, pips, and cues still follow the style brief (stroke weight, glow, state colors). An ornamented, identity-bearing reticle — an engraved ring, sculpted brackets — is NOT a simple primitive; include it in the asset list like any other chrome.
 
 Pure white #ffffff background everywhere except where the actual UI assets sit.
 ```

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

@@ -48,6 +48,14 @@ might suggest. Two hard rules for the frame prompt:
   perches", "fog drifts left then back right", "candle flames flicker".
   Bad: "camera dollies forward into the gate" (one-way motion fights the
   identical endpoints and produces a visible hitch).
+  **The seam is YOUR job, not the model's:** in practice the clip lands
+  *near* frame 0, not exactly on it, and a bare `video.loop = true` shows a
+  visible hitch every cycle. Always wire the video with the DOM crossfade
+  below, and watch one full cycle before calling the menu done. (Do not
+  reach for `--loop` here: it routes to a different model with a first-class
+  loop param but NO frame conditioning — the video won't match your key art —
+  and server-side `--frame` overrides `--loop` anyway, so passing both does
+  nothing.)
 - **Two-frame** (`--first-frame` + `--last-frame`) only when the menu
   genuinely needs a state change (rain starts and persists, a figure walks in
   and stays). The loop will have a visible seam where the last frame snaps
@@ -71,6 +79,44 @@ npx genex wait <gen-id>
 # -> https://assets.genex.technology/generations/<gen-id>/video-mp4
 ```
 
+## Seamless in the DOM — the loop crossfade (mandatory wiring)
+
+Never wire the clip as a bare `<video loop>` — the residual seam shows every
+cycle. Two stacked `<video>` elements with the same src crossfade at the
+cycle end; any seam disappears deterministically, no regeneration lottery:
+
+```ts
+/** Deterministic seamless loop: two stacked <video>s crossfade at cycle end. */
+export function seamlessLoop(holder: HTMLElement, url: string, fade = 0.6): void {
+  const mk = (): HTMLVideoElement => {
+    const v = document.createElement("video");
+    v.src = url; v.muted = true; v.playsInline = true; v.preload = "auto";
+    holder.appendChild(v);
+    return v;
+  };
+  let front = mk(), back = mk();
+  front.style.opacity = "1";
+  void front.play();
+  const tick = (): void => {
+    if (front.duration > 0 && front.currentTime >= front.duration - fade && back.paused) {
+      back.currentTime = 0;
+      void back.play();
+      front.style.transition = back.style.transition = `opacity ${fade}s linear`;
+      back.style.opacity = "1";
+      front.style.opacity = "0";
+      const old = front; front = back; back = old;
+      window.setTimeout(() => back.pause(), fade * 1000 + 50);
+    }
+    requestAnimationFrame(tick);
+  };
+  requestAnimationFrame(tick);
+}
+```
+
+Pause both videos when the menu phase hides (they're decode work), and
+resume the front one when it returns. Watch ONE full cycle in the browser
+before calling the menu done — that's the seam check.
+
 **Work async — the menu must never block the game.** Generate the frame right
 after the UI plan gate, enqueue the video with `--no-wait`, ship the CSS menu
 (buttons + title over the frame IMAGE as a static backdrop), and swap the
@@ -89,9 +135,8 @@ copy-pasteable example:
 ```html
 <div id="ui">
   <div id="screen-menu" class="screen" data-phase="menu">
-    <video class="menu-bg"
-      src="https://assets.genex.technology/generations/<id>/video-mp4"
-      autoplay muted loop playsinline></video>
+    <!-- seamlessLoop() (above) injects two crossfading <video>s here -->
+    <div class="menu-bg" id="menu-bg"></div>
     <div class="menu-title stagger" style="--i: 0">EMBERFALL</div>
     <button class="menu-btn stagger" id="menu-play"    style="--i: 1; left: 38%; top: 52%; width: 24%; height: 8%;">PLAY</button>
     <button class="menu-btn stagger" id="menu-options" style="--i: 2; left: 38%; top: 63%; width: 24%; height: 8%;">OPTIONS</button>
@@ -104,7 +149,9 @@ copy-pasteable example:
 
 ```css
 #screen-menu { position: absolute; inset: 0; overflow: hidden; background: #000; }
-.menu-bg { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; }
+.menu-bg { position: absolute; inset: 0; }
+.menu-bg video { position: absolute; inset: 0; width: 100%; height: 100%;
+                 object-fit: cover; opacity: 0; }
 .menu-title {
   position: absolute; left: 0; right: 0; top: 14%; text-align: center;
   font-family: "Cinzel", serif; font-size: 9vh; color: #f4e3b8;

package/templates/skills/genex-threejs-game-ui/SKILL.md

@@ -39,6 +39,15 @@ backdrop), not an afterthought `<div>`. When the menu decision is a reasoned
 "no", every "menu backdrop" row above (pause, fail, win, lobby) grades over
 the loader's key art instead.
 
+The table lists screens; **elements are inventoried separately**. Walk the
+whole loop in your head — loader → menu → spawn → action → pickup → damage →
+death → retry → win — and write down EVERY on-screen element the player will
+ever see: the reticle and each of its states, aim/interact cues, toasts,
+damage numbers, kill feeds, timers, countdowns, pickup popups… Each element
+gets a treatment from the brief. **Nothing ships looking like default
+browser CSS** — an element styled like a bare `<div>` or a system button is
+a bug wherever it appears, listed or not.
+
 **2. One shared style brief — for the WHOLE game, not just the UI.** Write it
 once — 4–5 named hues, materials, one display + one body font, mood — and
 store it as a comment block near the UI code. `$genex-ai-menu`,
@@ -58,6 +67,13 @@ AAA games of the genre, and state in one line which structural conventions
 you're borrowing. The bar is what those games ship, not "good enough for a
 demo". Conventions only — never logos, exact layouts, or trade dress. The
 same 2–3 names carry into the router's visual-direction gate for the scene.
+Then turn references + brief into ONE **concept frame** — a single generated
+image of what THIS game should look like mid-play (scene, mood, lighting;
+a UI impression is welcome but optional):
+`npx genex image "<one-sentence game look from the brief>" --aspect 16:9 --quality high --no-wait`,
+enqueued FIRST of all art. Its URL goes into the style-brief comment as the
+game's north star: every later 2D generation that accepts `--edit` anchors
+to it, and the scene's lighting/grading is judged against it.
 
 **4. Ask only when genuinely ambiguous.** If the concept pins the mood (a
 "gothic horror dungeon crawler" pins it), decide and state the plan in one
@@ -70,12 +86,21 @@ it derives from the game type.
 are examples, not defaults. Do not default to neon/cyberpunk/synthwave — or
 any other single register — unless the concept calls for it.
 
-**6. Close the gate out loud — plan + queued generations.** The gate's output
-is one short visible message in chat: the screen list with tiers, the style
-brief (hues + font pair), the named references, and the generation IDs of the
-Tier-2 jobs just enqueued — the `$genex-ai-hud` Stage-1 mockup (every game)
-and the `$genex-ai-menu` video (when the menu decision is yes). No visible
-plan or no queued IDs means the gate did not run — go back and run it.
+**6. Close the gate out loud — a fixed-format plan message.** Post this
+message in chat, translated to the user's language, filling every line —
+this exact structure, not a paraphrase (the scaffold's keep-it-short talk
+rule explicitly does not apply to this one message):
+
+```
+UI plan
+• Screens: <list with tiers — loader / menu / pause (Esc) / win/lose / …>
+• Style: <4–5 named hues> · fonts <display> / <body>
+• References: <2–3 AAA games — one line on what's borrowed>
+• Concept frame: <generation id>
+• Queued: HUD chrome <id> · menu video <id or "no menu: reason">
+```
+
+A message missing any line means the gate did not run — go back and run it.
 
 ## The tier ladder
 
@@ -268,6 +293,8 @@ architecture and consume the shared style brief.
 - No pause screen, or a pause that isn't bound to Escape.
 - A style brief whose fonts were never actually loaded (a system-stack display
   font at runtime).
+- A micro-element (reticle, cue, toast, damage number) left as default CSS
+  while the panels got the art treatment.
 - A generic stat dashboard (rows of labels + numbers) instead of a designed
   HUD — pick the 2–3 numbers that matter and style them by hierarchy.
 - Hard-cut phase swaps, a menu whose elements just appear, numbers that

package/templates/skills/genex-threejs-skill-router/SKILL.md

@@ -71,7 +71,9 @@ stack this game ships (bloom/AO/grade — at least ONE built render-pass effect
 for EVERY game, justified by the shared style brief; the UI vignette div or a
 CSS filter on the canvas does not count, and a plan that "deliberately skips
 everything" is the stock default, not a look; `$genex-threejs-image-pipeline`
-owns ordering when 2+ compose), and the lighting/atmosphere mood from that
+owns ordering when 2+ compose), one named **ambient-motion loop** that keeps
+the scene alive at rest (emissive pulse, shimmer, drifting dust — shader
+work, zero generations), and the lighting/atmosphere mood from that
 same brief. Planning is not building — effects still land last in the
 execution order.
 
@@ -150,8 +152,10 @@ concept-driven — a richer first build beats a grey-box one.
   floors from the routing-map's acceptance gate: the generated sprite HUD wired in
   (not the CSS placeholder), pause on Escape, the branded loader with its key-art
   background, the brief's fonts actually loaded, the renderer baseline + at least one
-  built render-pass effect, and every placed 2D/media piece screenshot-verified in
-  situ. These floors gate `npx genex publish` and the final handoff of a session the
+  built render-pass effect, every placed 2D/media piece screenshot-verified in
+  situ, no UI element left as default browser CSS, and no placeholder primitive
+  left where a generated asset was planned. These floors gate `npx genex publish`
+  and the final handoff of a session the
   same way — they do not wait for the word "done" to be said.
 - Entering an **existing or remixed project**: read before writing — learn the
   current renderer choice, physics setup, and file conventions first, then

package/templates/skills/genex-threejs-skill-router/references/routing-map.md

@@ -24,10 +24,12 @@ Three.js release or branch, and do not blindly copy demo architecture.
    one shared style brief, a tier per screen — stated visibly in chat, never
    decided silently. Enqueue the Tier-2 UI generations now with `--no-wait`
    (pick them up later with `npx genex wait <id>`) — they render server-side
-   while you build the game. The `$genex-ai-hud` Stage-1 mockup is enqueued
-   here for EVERY game; the `$genex-ai-menu` video whenever the menu decision
-   is yes (the default for every game — "it's only a draft" is not a reason
-   to decide no). Skipping this enqueue is
+   while you build the game. FIRST of all art: the gate's **concept frame** —
+   the single image of the finished game's look that every later `--edit`-able
+   generation anchors to. Then the `$genex-ai-hud` Stage-1 mockup, enqueued
+   here for EVERY game; and the `$genex-ai-menu` video whenever the menu
+   decision is yes (the default for every game — "it's only a draft" is not a
+   reason to decide no). Skipping this enqueue is
    the #1 way a finished game ships an ugly HUD — by step 12 there is nothing
    to swap in.
 4. Lock the visual direction — the same plan-first logic as the UI gate, in
@@ -47,7 +49,14 @@ Three.js release or branch, and do not blindly copy demo architecture.
      owns the pass ordering;
    - **references**: name 2–3 AAA games whose look this game borrows
      (conventions, lighting mood, palette, post — never trade dress); the
-     same 2–3 the UI gate named, extended from the interface to the scene;
+     same 2–3 the UI gate named, extended from the interface to the scene,
+     and embodied in the gate's concept frame — the image the scene is
+     judged against;
+   - **ambient motion**: name ONE subtle environmental motion loop that keeps
+     the scene alive at rest — an emissive pulse along edges, heat shimmer,
+     drifting dust, a slowly flowing texture. Shader/procedural, zero
+     generations, built with the scene — a world that is perfectly still
+     reads as a screenshot, not a place;
    - **lighting/atmosphere mood** from the SAME shared style brief the UI gate
      wrote — one art direction across scene and UI.
    Planning is not building: effects still land LAST (steps 10–11); this step
@@ -61,15 +70,16 @@ Three.js release or branch, and do not blindly copy demo architecture.
    architecture, planets, water, precipitation, clouds, or VFX. Show the
    planned loader from the very first asset load — a player must never stare
    at a black screen; the rest of the UI states come at step 12.
-   Then dress the world with 2D/media art: walk the scene for image/video
-   insertion points — posters, signs, graffiti, decals, banners, in-world
-   screens and billboards (`$genex-ai-image`; `$genex-ai-video` for anything
-   that should move). The visual-direction block names the 2–4 pieces this
-   world gets (or states in one line why it has none — that waiver is valid
-   only for a world with no authored surfaces at all, pure-abstract geometry
-   or empty open water/space; a world with buildings, walls, rooms, vehicles,
-   or props names its pieces); enqueue them with
-   `--no-wait` alongside the other assets. Every placed piece is
+   Then make the world-dressing DECISION — a judgment call, not a quota:
+   does THIS world's fiction support 2D art (posters, signs, graffiti,
+   decals, banners, in-world screens — `$genex-ai-image`; `$genex-ai-video`
+   for anything that should move)? Say the decision in one line in the
+   visual-direction block. Name only the pieces that genuinely belong — a
+   garage wants grease posters and warning decals; a pristine void wants
+   none — and anchor their prompts to the concept frame. **Zero is a valid
+   answer with a stated reason; art placed just to satisfy this step is the
+   failure mode, not skipping it.** Enqueue what you named with `--no-wait`
+   alongside the other assets. Every placed piece is
    screenshot-checked in situ — right scale, not stretched, unlit material
    where it must glow, readable at gameplay distance
    (`$genex-threejs-visual-validation` owns the capture discipline).
@@ -89,7 +99,10 @@ Three.js release or branch, and do not blindly copy demo architecture.
     `$genex-threejs-game-ui` (HUD, pause on Escape, fail/retry, win, and the
     full loading state grown from the step-6 loader), then `npx genex wait`
     the step-3 UI generations and wire them in — the sprite HUD replaces the
-    placeholder CSS, the menu video replaces the still frame. This swap is a
+    placeholder CSS, the menu video replaces the still frame (wired with the
+    menu skill's loop crossfade), and the scene's planned generated models
+    replace their placeholder primitives — a shipped wave of enemies may not
+    be untextured boxes. This swap is a
     completion gate, not an option: a game still on the placeholder CSS HUD,
     or without a working Escape pause, is not done. Then run a feel pass via
     `$genex-threejs-game-feel` (input response, camera, impact feedback,
@@ -97,6 +110,33 @@ Three.js release or branch, and do not blindly copy demo architecture.
 13. Validate in a real browser with fixed seeds, captures, interaction checks,
     and performance evidence.
 
+## Parallelize with subagents (when the environment has them)
+
+Generations already render server-side in parallel — the wall-clock savings
+live in the ATTENDED chains. When the coding agent supports background
+subagents (e.g. Claude Code's Agent tool), split these off; in environments
+without them (Cursor), the same order simply runs sequentially and the
+`--no-wait` pattern still hides most generation latency.
+
+- **HUD chain worker.** The moment the Stage-1 mockup lands, hand the whole
+  `$genex-ai-hud` chain to one subagent: pick the better candidate → Stage-2
+  sheet → clean → extract → masks → write the sprite wiring. Its prompt must
+  be self-contained — the style brief, concept-frame and mockup URLs, the
+  output dir, and exactly which files it owns.
+- **Asset shepherd.** One subagent runs `npx genex wait` on every queued ID
+  and wires each asset in as it lands (skybox, models, menu video, dressing),
+  swapping placeholders out and reporting each swap.
+- **Verification runner.** Browser evidence — screenshots, control presses,
+  the menu loop-seam watch, in-situ checks of placed art — can run in a
+  subagent while the main agent keeps building.
+
+Hard rules: **one writer per file** — each subagent owns a disjoint file set
+(the HUD worker owns the hud modules and `public/assets/hud/`, the shepherd
+owns asset-wiring modules), and the main agent stays the only writer of
+gameplay/netcode. Merge points are explicit: a subagent reports what it
+changed, the main agent reconciles. Never put two writers on the same
+module — a corrupted entry point costs more than the minutes saved.
+
 ## Acceptance gate
 
 **Game fast path:** for a game task that loaded no procedural/visual-system skill,
@@ -107,7 +147,9 @@ sprite HUD wired in — not the CSS placeholder — pause on Escape, the branded
 loader with its key-art background, the brief's font pair actually loaded)
 and the look floor (the step-4 renderer baseline + named post stack actually
 built; every placed 2D/media piece — decals, posters, in-world screens —
-screenshot-verified in situ)**. These floors gate `npx genex publish` and the
+screenshot-verified in situ; no UI element left as default browser CSS; no
+placeholder primitive left where a generated asset was
+planned)**. These floors gate `npx genex publish` and the
 final handoff of a session the same way — "I never said it was done" is not
 an exemption. The list below applies to routed *visual-system* scenes, and each
 system-specific item (debug views, seed manifests, tier knobs) applies only when