@genex-ai/cli-demo 0.47.0-dev.70 → 0.47.0-dev.74

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.47.0-dev.70",
+  "version": "0.47.0-dev.74",
   "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {
@@ -36,12 +36,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@sentry/node": "^10.63.0"
+    "@sentry/node": "^10.63.0",
+    "pngjs": "^7.0.0"
   },
   "devDependencies": {
     "@dimforge/rapier3d-compat": "^0.19.3",
     "@genex-ai/multiplayer": "workspace:*",
     "@pixiv/three-vrm": "^3.5.4",
+    "@types/pngjs": "^6.0.5",
     "@types/three": "^0.185.0",
     "three": "^0.185.1",
     "tsup": "^8.0.0",

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

@@ -0,0 +1,381 @@
+---
+name: genex-ai-hud
+description: Generate a production HUD sprite set — matched frames, masks, and icons in one coherent art style — via the mockup-then-deconstruct pipeline (`npx genex image` + `npx genex ui`), then wire it as a DOM overlay with channel-accurate masked fills. Use when the game wants a cohesive art-directed HUD (fantasy brass, sci-fi glass, racing carbon) rather than a clean minimal CSS HUD.
+---
+
+# Genex AI · HUD
+
+Generate every sprite of a game HUD in ONE art style — a full-HUD mockup, then
+a deconstruction into individual assets — and wire them as a plain-DOM overlay
+with masked fills that track the art's real channels. The result is an
+art-directed HUD (etched steel ammo strip, parchment HP bar, chrome minimap
+ring) that no hand-written CSS can fake.
+
+## When to use this vs. a hand-coded CSS HUD
+
+- **Use `$genex-threejs-game-ui` alone** (clean CSS bars, text, plates) for
+  most games — it's faster, crisper, and always readable. That skill also owns
+  the overlay architecture this one plugs into.
+- **Use this skill** when the game's identity wants a *materially* art-directed
+  HUD — gothic filigree frames, rusted post-apocalyptic panels, carbon-fiber
+  racing telemetry, hand-painted storybook plates — where the frames themselves
+  are illustrations. You'll spend ~10 image generations and real wiring effort;
+  make sure the game deserves it.
+
+## Framing rules — internalize before prompting
+
+The HUD overlays a **live 3D scene**. The pixels between widgets show the game.
+
+- **NEVER generate a fullscreen ambient background** (parchment sheet, paper,
+  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.
+- **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
+  semi-opaque backdrop — because the scene behind it might be a snowfield or a
+  torchlit dungeon. Pure-outline widgets over arbitrary scenes fail.
+- **The mockup must be flat and head-on** — a 2D screen-space overlay, never
+  tilted, isometric, or in perspective. Angled panels have no clean silhouette
+  and deconstruct into skewed slices. If the mockup comes back tilted,
+  regenerate it before going further.
+
+## Style brief
+
+Start from the game's ONE shared style brief (`$genex-threejs-game-ui`'s "Plan
+the UI first" gate) — the HUD, menu, and loader consume the same brief; a HUD
+styled in a second world is a bug. Expand it here with what sprites need:
+materials, an explicit palette of **4–5 named hues**, weathering, line
+treatment, atmosphere. Keep outline stroke width
+consistent across widgets — per-widget stroke changes read as amateur fastest.
+For **per-sprite prompts** (single-sprite regeneration, below) the brief must
+end EXACTLY with:
+
+> Sharp edge silhouette on a flat plain background for clean cutout. No drop shadows. No vignette. Subject centered.
+
+That sentence is what gives clean cutouts; skip it and the sprites come back
+with halos. (The Stage-1 mockup and Stage-2 sheet prompts do NOT use it — they
+are full frames, not cutouts; the templates below handle that.)
+
+## Text ownership — classify every word before Stage 2
+
+Walk every visible word, digit, suffix, and glyph in the mockup into three
+buckets. The Stage-2 prompt KEEPS or REMOVES accordingly:
+
+- **`baked_static`** — identity text fused into the art (a "SPECIAL" label
+  painted into a meter frame, carved scale numerals, engraved panel titles).
+  Stage 2 **keeps** it in the asset.
+- **`runtime_static`** — fixed but editable/localizable labels ("AMMO"
+  captions, objective headers not fused with the frame). Stage 2 **removes**
+  it; you render it as DOM text.
+- **`runtime_dynamic`** — anything driven by game state: values, timers, bar
+  fills, item icons, map content. Stage 2 **removes** it; the DOM renders it.
+
+The test: "is this fixed identity artwork, or should runtime code own it?"
+Baking a runtime value into a sprite is a failure; stripping a carved identity
+label flattens the art.
+
+## The pipeline
+
+Each step is one command; every `<...-url>` is the R2 URL the previous command
+printed. Fill the two prompt templates —
+[references/stage1-prompt-template.md](references/stage1-prompt-template.md)
+and [references/stage2-prompt-template.md](references/stage2-prompt-template.md)
+— before Stages 1 and 2.
+
+**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
+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.
+
+```bash
+# Stage 1 — full-HUD mockup over a placeholder scene (the LAYOUT REFERENCE).
+# Two candidates in one call; pick the better, save its URL:
+npx genex image "<filled stage-1 prompt>" --size 2560x1440 --quality high --candidates 2
+
+# Stage 2 — deconstruct the mockup into an asset sheet on white:
+npx genex image "<filled stage-2 prompt>" --edit <mockup-url> --quality high
+
+# Stage 2b — ML-clean the sheet background (preserves anti-aliased edges and
+# interior whites that a naive white-key would eat; the prompt is recorded, unused):
+npx genex image "clean sheet" --clean <sheet-url>
+
+# Stage 3 — extract individual transparent PNGs locally (free, no generation).
+# Names in READING ORDER: top-to-bottom, then left-to-right within a band:
+npx genex ui extract --in <cleaned-url> --out-dir public/assets/hud --names hp-frame,ammo-frame,minimap-ring,weapon-icon
+
+# Progress masks — for every bar/meter with a generated frame. The Stage-2
+# sheet holds a clean frame cell PLUS a same-size annotated duplicate with the
+# fill zones painted pure green #00ff00; this converts the green into an alpha
+# mask + the fillBox (FB) the DOM fill reads:
+npx genex ui masks --in <cleaned-url> --out-dir public/assets/hud --pairs "hp:cx,cy,w,h:ax,ay,w,h:1"
+#   pairs = name : clean-cell crop (px) : annotated-cell crop (px) : expected green components
+
+# Text colors — sample the mockup instead of free-picking from the palette:
+npx genex ui text-color --in <mockup-url> --box x,y,w,h
+```
+
+Why mockup-then-deconstruct instead of N per-sprite generations: one
+generation produces a **matched set** (no style drift between widgets) and the
+model composes the layout for you — the mockup is the ground-truth reference
+you verify the final HUD against.
+
+### Sprite iteration
+
+To fix ONE sprite, don't re-run the pipeline:
+
+- **Regenerate it** in the house style:
+  `npx genex image "<style brief + sprite subject>" --quality medium --remove-bg`
+  — add `--bg-mode glyph` for digits and closed shapes (an `8` or `$` otherwise
+  comes back with its loops hollowed out). Use the mandatory cutout sentence.
+- **Or region-edit the sheet**: `npx genex image "<targeted change>" --edit <sheet-url>`
+  then re-run `genex ui extract` — surgical, preserves everything else.
+- `npx genex ui trim --in public/assets/hud/<sprite>.png` crops a sprite to
+  its alpha content and reports its real pixel dims — the source of truth for
+  the box↔art aspect rule below.
+
+## Composition rules (each one is a documented failure class)
+
+- **Continuous fills = masked reveal.** HP, mana, fuel, XP, stamina, charge —
+  NEVER generate `*-fill.png` sprites, and NEVER use a naive `width`/`height`
+  percentage of the widget box (it drifts ~12% off the art's real channel:
+  empty at 25%, full by 75%). The frame stays a sprite; the fill is the
+  masked-fill DOM pattern below.
+- **Minimap/radar interiors are an empty CSS disc** (`border-radius: 50%`,
+  dark background). Only the decorative ring frame is a sprite, prompted with
+  an explicitly **transparent center — no map, no terrain inside**. Gameplay
+  code paints blips into the disc at runtime; the model otherwise invents
+  garbled fake streets.
+- **Dial needles = ONE up-pointing sprite + a computed rotation.** Never one
+  sprite per angle. `transform: rotate(<deg>)` with `transform-origin: 50% 100%`
+  (pivot at the needle base), sweeping `-135deg..135deg` for a classic dial:
+  `rotate(${-135 + 270 * clamp(v / max, 0, 1)}deg)`.
+- **Segmented bars = 3 stacked divs**: (1) a full-width dark track, (2) the
+  solid scaling fill, (3) a fixed full-width notch overlay
+  (`repeating-linear-gradient(to right, transparent 0 9%, #1c1c24 9% 10%)`)
+  painted ON TOP. Never put the gradient on the scaling fill itself — its `%`
+  stops anchor to the fill's own width and the segments visibly compress as
+  the value drops.
+- **Every numeric readout gets a backing plate** — a
+  `background: rgba(10, 8, 6, 0.6)` rounded div behind the text by default, an
+  extracted plate sprite when the art has one, or a deliberate skip documented
+  in a comment (`/* no plate — reads against <reason> */`). Bare digits look
+  fine over the dev background and vanish over a bright scene.
+
+## The masked-fill DOM pattern (the crown jewel)
+
+Full annotated version with all direction variants and a worked HP-bar
+example: [references/masked-fill.md](references/masked-fill.md). The compact
+form:
+
+```html
+<div class="widget" id="hud-hp">          <!-- root: overflow VISIBLE (glows may bleed) -->
+  <div class="hp-mask">                   <!-- outer: the silhouette mask -->
+    <div class="hp-fill" data-fill data-fill-mask="hp-mask.png"
+         data-fill-box="0.0784,0.3469,0.9216,0.3605"
+         data-fill-from="left" data-fill-ratio="0.72"></div>
+  </div>
+  <img class="hp-frame" src="/assets/hud/hp-frame.png" alt="">
+</div>
+```
+
+```css
+.widget  { position: absolute; overflow: visible; }
+.hp-mask { position: absolute; inset: 0; overflow: hidden;
+           -webkit-mask-image: url(/assets/hud/hp-mask.png);
+           mask-image: url(/assets/hud/hp-mask.png);
+           -webkit-mask-size: 100% 100%; mask-size: 100% 100%;
+           mask-repeat: no-repeat; }
+.hp-fill { position: absolute; inset: 0;   /* FULL-BOX gradient; the clip places the edge */
+           background: linear-gradient(180deg, #ef5b5b, #7a1d18); }
+.hp-frame { position: absolute; inset: 0; width: 100%; height: 100%;
+            object-fit: fill; }            /* frame paints on top */
+```
+
+```ts
+// FB = the mask's fillBox from the `genex ui masks` JSON — the TRUE channel.
+const FB = { x: 0.0784, y: 0.3469, w: 0.9216, h: 0.3605 };
+const fill = document.querySelector<HTMLElement>("#hud-hp .hp-fill")!;
+
+function setHp(hp: number, maxHp: number): void {
+  const ratio = Math.max(0, Math.min(1, hp / maxHp));
+  const cx = (FB.x + ratio * FB.w) * 100;               // left-fill: edge at the CHANNEL level
+  fill.style.clipPath = `polygon(0% 0%, ${cx}% 0%, ${cx}% 100%, 0% 100%)`;
+  fill.dataset.fillRatio = String(ratio);               // keeps the fill auditable
+  const low = hp / maxHp < 0.25;                        // the reactive element (see below)
+  fill.style.filter = low ? "drop-shadow(0 0 12px #ff2a36)" : "none";
+}
+```
+
+The structure, in one breath: the OUTER div carries the alpha mask
+(`mask-image` + `mask-size: 100% 100%`, `overflow: hidden`) so the fill can
+only exist inside the art's silhouette; the INNER div is a FULL-BOX gradient
+whose `clip-path` places the leading edge at the **channel-relative** level
+using `FB` — for a left fill the right edge sits at `(FB.x + ratio * FB.w) * 100%`,
+for a bottom fill the top edge at `(FB.y + (1 - ratio) * FB.h) * 100%`. Stamp
+`data-fill`, `data-fill-mask`, `data-fill-box`, `data-fill-from`, and
+`data-fill-ratio` on the inner div — they make every fill auditable against
+the mask JSON. The frame `<img>` sits on top with `object-fit: fill`, and the
+widget root keeps `overflow: visible` so glow effects bleed past the art
+instead of clipping to a hard square.
+
+## Reactivity — the juice floor
+
+A live HUD moves; a static one is a mockup screenshot. The floor for THIS
+skill (each is a few lines of plain JS + CSS):
+
+- **Numbers tween, never snap.** Score/coins/ammo tick to the new value over
+  ~300 ms (`requestAnimationFrame` lerp on the displayed number).
+- **Damage-chip bar**: behind the instant red fill, a white/pale "chip" layer
+  eases down ~600 ms later — the player reads exactly how much that hit cost.
+  (Two stacked fills in the same mask; the chip's `clip-path` lags the real
+  one via a delayed transition.)
+- **A damage flash**: a screen-edge vignette pulse on hit (one full-screen
+  div, `opacity` keyframe), not a number cloud.
+- **At least one threshold state** — a change of VISUAL, not just of fill:
+
+```ts
+const low = hp / maxHp < 0.25;
+el.style.color = low ? "#ff6b6b" : "#f4e3b8";
+el.classList.toggle("pulse", low);   // @keyframes pulse in your CSS + a transition
+```
+
+- **Pickup pop**: the touched counter scales 1 → 1.15 → 1 (~150 ms) when it
+  gains.
+
+Impact feedback beyond the HUD (hitstop, camera shake, difficulty ramp) is
+`$genex-threejs-game-feel` — run its pass before calling the game done; the
+HUD's reactive layer and that skill's feedback layer are designed together.
+
+## Placement
+
+Position widgets by **anchor + reference-1920×1080 pixels**, scaled by
+`viewportH / 1080` so the HUD holds its physical position on any aspect ratio:
+
+```ts
+function layoutHud(): void {
+  const s = innerHeight / 1080;
+  const hp = document.getElementById("hud-hp")!;
+  hp.style.left = `${40 * s}px`;
+  hp.style.bottom = `${40 * s}px`;
+  hp.style.width = `${560 * s}px`;
+  // h derived from the frame art's REAL aspect (trim/extract sidecar dims), never eyeballed:
+  hp.style.height = `${Math.round(560 * (102 / 760)) * s}px`;  // hp-frame.png is 760x102
+}
+layoutHud();
+window.addEventListener("resize", layoutHud);
+```
+
+Genre defaults (tweak per game): **hp** bottom-left `(40, -40)`; **ammo**
+bottom-center; **crosshair** dead center, ~48px, aspect locked; **score**
+top-center; **minimap** top-right, ~220px square.
+
+Two hard rules:
+
+- **The box aspect must match the frame PNG's aspect** (use the dims from the
+  `genex ui trim` output or the extract `.bbox.json` sidecar): pick ONE
+  dimension by design and COMPUTE the other. `object-fit: fill` on a
+  mismatched box squashes the art.
+- **≥ 20px gaps** (reference pixels) between widgets sharing an anchor —
+  tighter visibly overlaps once sprite padding is counted.
+
+## Verify before calling it done
+
+- **Open every extracted PNG and eyeball it** — right subject, right name.
+  The reading-order sort can mismap when rows are uneven; re-run `extract`
+  with corrected name order rather than regenerating anything.
+- **Fills grow monotonically** — drive each fill through 0 → 50 → 100 and
+  confirm the reveal grows and stays inside the art's channel (never bulging
+  past the frame's track).
+- **No text clips** — for every text node, `scrollWidth <= clientWidth`.
+  Display fonts run 25–50% wider than a naive estimate; widen the box or drop
+  the weight, don't shrink the font.
+- **No widget overlaps** at the reference viewport, and none off-screen.
+- **Screenshot-check over real gameplay** — bright AND dark scenes — with
+  `$genex-threejs-visual-validation`'s capture discipline. Judge the pixels,
+  not your intent.
+
+## Cost & latency honesty
+
+A full HUD is **~10 image generations** (mockup + deconstruct + clean + a few
+sprite re-rolls), a couple of minutes each at high quality — budget an hour
+end to end, not five minutes. That fits comfortably inside the image rate
+limit; local `genex ui` steps are free and instant. Two rules keep the clock
+honest: the sprite pipeline runs WHILE you build (kick Stage 1 first, code
+against CSS placeholders, swap sprites in as stages land — never make the
+player-facing v0 wait on it), and candidates beat re-rolls (`--candidates 2`
+on the mockup: choosing between two costs zero extra wall-clock; regenerating
+after a bad single costs the whole chain).
+
+## Publish checklist
+
+- **Extracted sprites and masks are LOCAL files in `public/assets/hud/`** —
+  unlike other generated assets, they ship with the build and belong in the
+  repo. Reference them by relative path (`/assets/hud/hp-frame.png`), which
+  resolves at the domain root in dev and published alike.
+- Keep the mockup and cleaned-sheet **R2 URLs in a comment** near the HUD
+  code — sheet region-edits and re-extraction need them, and they're permanent.
+- Every fill uses the masked reveal with a real `FB` from the masks JSON — no
+  naive percentage fills hiding anywhere (`data-fill-*` stamps make this
+  greppable).
+
+## Options
+
+- `npx genex image` — `--size <WxH>` exact pixels (multiples of 16, each side
+  ≤ 3840, aspect at most 3:1); `--quality <low|medium|high>` (high for the
+  mockup/sheet, medium for single sprites); `--candidates <2|3|4>` several
+  variants in ONE call (use 2 for the mockup — pick the better, skip the
+  re-roll); `--edit <url>` image-to-image edit of an R2 URL; `--clean <url>`
+  background removal only; `--remove-bg` chains removal after a
+  generation/edit; `--bg-mode <sprite|glyph|sheet>` picks the removal model
+  (`glyph` for digits/closed shapes; `--clean` defaults to `sheet`);
+  `--no-wait` enqueue and continue — `npx genex wait <id>` picks the result
+  up later (safe to re-run; never creates a new generation).
+- `npx genex ui extract --in <png|url> --out-dir <dir> --names a,b,c` — also
+  writes a `.bbox.json` sidecar per sprite; `--min-pixels <n>` lowers the
+  component threshold when a small sprite is missed.
+- `npx genex ui masks --in <png|url> --out-dir <dir> --pairs "name:cx,cy,w,h:ax,ay,w,h:n"` —
+  emits `<name>-frame.png`, `<name>-mask.png`, an overlay, and the JSON with
+  `fillBox` (`FB`).
+- `npx genex ui text-color --in <png|url> --box x,y,w,h` — deterministic
+  eyedropper: background/plate color + dark/light/chromatic ink candidates.
+  Use the returned hex verbatim for the DOM text over that region.
+- `npx genex ui trim --in <png>` — crop to alpha content + report real dims.
+
+## Troubleshooting
+
+- **"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. Non-retryable; rewrite the wording.
+- **Generation takes minutes** — normal at high quality; let the command wait
+  and print the URL (the next pipeline step needs it, and re-running creates —
+  and bills — a new generation).
+- **A sprite got the wrong name** — extraction sorts by reading order
+  (top-to-bottom bands, left-to-right within a band); uneven rows can shift
+  the mapping. Re-run `extract` with the names reordered — no generation
+  needed.
+- **A small element is missing from extraction** — it fell under the component
+  threshold; re-run with `--min-pixels 500`.
+- **The fill drifts off the art's channel** — a naive `width`/`height` % crept
+  in, or `FB` doesn't match the mask. Use the clipPath formula with the
+  `fillBox` from the masks JSON, verbatim.
+- **The fill never shows, at any ratio** — the frame PNG's channel interior is
+  opaque track art occluding the fill beneath it. Raise the mask div above the
+  frame (`z-index`); the mask keeps the fill inside the channel, so the rim
+  and baked labels are unaffected (see the z-order note in
+  [references/masked-fill.md](references/masked-fill.md)).
+- **`genex ui masks` fails registration/coverage checks** — the annotated
+  duplicate drifted from the clean cell (different scale/position) or the
+  green isn't flat `#00ff00`. Region-edit the sheet (`--edit <sheet-url>`)
+  asking for a same-size duplicate with flat green fill zones, then re-run.
+- **Digits or `$`/`%` come back hollow after `--remove-bg`** — closed loops
+  read as background to the default cutter. Regenerate with `--bg-mode glyph`.
+- **A widget looks squashed** — the placement box aspect doesn't match the
+  frame PNG (`object-fit: fill` stretches). Get the real dims from
+  `genex ui trim` and compute the box from them.
+- **The mockup came back tilted / in perspective** — it won't deconstruct
+  cleanly. Keep the flat-framing paragraph in the Stage-1 prompt and
+  regenerate before Stage 2.

package/templates/skills/genex-ai-hud/references/masked-fill.md

@@ -0,0 +1,145 @@
+# The masked-fill DOM pattern
+
+Every continuous fill (bar, meter, orb, gauge) inside a generated frame is a
+**masked directional reveal**: two nested divs plus the frame image. The mask
+confines the fill to the art's exact silhouette; a `clip-path` on a full-box
+inner div places the leading edge at the channel-relative level.
+
+## Why not `width: ratio * 100%`?
+
+The art's fillable channel does not span the widget box — the frame's
+ornament eats the ends. Scaling the fill's own width/height against the FULL
+box drifts up to ~12% off the real channel (measured: reads empty at 25%,
+full by 75%). The reveal edge must be placed at `ratio` along the **true
+channel** — the `fillBox` (`FB`) that `npx genex ui masks` measures from the
+mask's opaque pixels and prints in its JSON.
+
+## Structure
+
+```
+widget root            position:absolute; overflow: VISIBLE   ← glows may bleed past the art
+├─ outer mask div      inset:0; overflow:hidden; mask-image:url(<mask.png>); mask-size:100% 100%
+│  └─ inner fill div   inset:0; FULL-BOX gradient; clip-path places the edge; data-fill-* stamps
+└─ frame <img>         inset:0; width/height:100%; object-fit:fill   ← painted on top
+```
+
+Confinement is the outer div's job (`overflow: hidden` + the mask). The
+widget **root stays `overflow: visible`** — otherwise any glow/halo that
+blooms past the silhouette gets sliced to a hard square.
+
+**Z-order depends on the frame art's channel.** "Frame on top" assumes the
+frame PNG's fill channel is transparent or translucent glass. This pipeline's
+deconstructed frames usually keep an **opaque** dark track texture inside the
+channel — a fill underneath is completely occluded (the bar looks stuck at
+empty no matter the ratio). In that case raise the mask div above the frame
+(`z-index` on the outer mask div): the mask confines the fill to the channel
+pixels, so the rim and any baked labels stay untouched. Check one extracted
+frame's channel pixels before wiring; if you can't see the fill move, this
+z-order is the first suspect.
+
+## The reveal formulas
+
+`ratio = clamp(value / max, 0, 1)`. `FB = { x, y, w, h }` in 0..1 fractions
+of the widget box (from the masks JSON). The edge coordinate is a percent of
+the FULL box:
+
+| `from` | leading edge | clipPath |
+| --- | --- | --- |
+| **left** | `cx = (FB.x + ratio * FB.w) * 100` | `polygon(0% 0%, cx% 0%, cx% 100%, 0% 100%)` |
+| **right** | `cx = (FB.x + (1 - ratio) * FB.w) * 100` | `polygon(cx% 0%, 100% 0%, 100% 100%, cx% 100%)` |
+| **bottom** | `cy = (FB.y + (1 - ratio) * FB.h) * 100` | `polygon(0% cy%, 100% cy%, 100% 100%, 0% 100%)` |
+| **top** | `cy = (FB.y + ratio * FB.h) * 100` | `polygon(0% 0%, 100% 0%, 100% cy%, 0% cy%)` |
+
+Left/right suit horizontal bars; bottom suits orbs and vertical gauges (the
+liquid rises). For an orb whose empty top would show the scene through the
+glass, add a dark cavity div (a circle at the `FB` box) BEHIND the fill so
+the empty portion reads as deep glass rather than a hole.
+
+## The `data-fill-*` contract
+
+Stamp these on the inner fill div, derived from the SAME variables that
+drive the clip — they make every fill auditable against the masks JSON
+(and greppable, so no naive percentage fill hides in the codebase):
+
+| Attribute | Value |
+| --- | --- |
+| `data-fill` | present on every fill element |
+| `data-fill-mask` | the mask PNG basename, e.g. `hp-mask.png` |
+| `data-fill-box` | `` `${FB.x},${FB.y},${FB.w},${FB.h}` `` |
+| `data-fill-from` | `left` \| `right` \| `top` \| `bottom` |
+| `data-fill-ratio` | the current `ratio`, updated with the clip |
+
+## Worked example — an HP bar (left fill)
+
+`genex ui masks --out-dir public/assets/hud` wrote `hp-frame.png` +
+`hp-mask.png` and, beside them, `hp.annotated-progress.json` (one object per
+pair; the run's index `annotated-progress.json` nests the same objects in a
+`pairs` array). `fillBox` sits at the object's top level:
+
+```json
+{
+  "input": "<cleaned-sheet-url>",
+  "pairs": [
+    {
+      "name": "hp",
+      "fillBox": { "x": 0.0784, "y": 0.3469, "w": 0.9216, "h": 0.3605 },
+      "mask": { "path": "public/assets/hud/hp-mask.png", "...": "..." },
+      "...": "..."
+    }
+  ]
+}
+```
+
+```html
+<div class="widget" id="hud-hp">
+  <div class="fill-mask" style="-webkit-mask-image: url(/assets/hud/hp-mask.png); mask-image: url(/assets/hud/hp-mask.png);">
+    <div class="fill" data-fill data-fill-mask="hp-mask.png"
+         data-fill-box="0.0784,0.3469,0.9216,0.3605"
+         data-fill-from="left" data-fill-ratio="0.72"></div>
+  </div>
+  <img class="frame" src="/assets/hud/hp-frame.png" alt="">
+</div>
+```
+
+```css
+.widget { position: absolute; overflow: visible; }
+.fill-mask {
+  position: absolute; inset: 0; overflow: hidden;
+  -webkit-mask-repeat: no-repeat; mask-repeat: no-repeat;
+  -webkit-mask-position: center; mask-position: center;
+  -webkit-mask-size: 100% 100%; mask-size: 100% 100%;
+}
+.fill {
+  position: absolute; inset: 0;                      /* FULL box — the clip does the work */
+  background: linear-gradient(180deg, #ef5b5b 0%, #c84134 60%, #7a1d18 100%);
+  transition: clip-path 0.2s ease-out;               /* smooth damage ticks */
+}
+.fill.low { filter: drop-shadow(0 0 12px #ff2a36); animation: hud-pulse 1s ease-in-out infinite; }
+.frame { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: fill; }
+@keyframes hud-pulse { 50% { opacity: 0.75; } }
+```
+
+```ts
+// FB comes from the masks JSON — never eyeball it, never re-measure by hand.
+const FB = { x: 0.0784, y: 0.3469, w: 0.9216, h: 0.3605 };
+const fill = document.querySelector<HTMLElement>("#hud-hp .fill")!;
+
+export function setHp(hp: number, maxHp: number): void {
+  const ratio = Math.max(0, Math.min(1, hp / maxHp));
+  const cx = (FB.x + ratio * FB.w) * 100;
+  fill.style.clipPath = `polygon(0% 0%, ${cx}% 0%, ${cx}% 100%, 0% 100%)`;
+  fill.dataset.fillRatio = String(ratio);
+  fill.classList.toggle("low", ratio < 0.25);          // the reactive branch
+}
+```
+
+Cosmetics (glow, pulse, transition) live alongside the clip but must never
+fight it — no `transform`, `width`, or `height` on the fill element; the
+computed `clip-path` is the single source of the reveal.
+
+## Verification
+
+Drive each fill through 0 → 50 → 100: it must read empty at 0, grow
+monotonically, read full at 100, and never bulge past the frame's visible
+track. If the edge lands off the channel, the `FB` in code doesn't match the
+masks JSON — or a naive percentage fill crept back in.

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

@@ -0,0 +1,44 @@
+# Stage 1 prompt template — full-HUD mockup
+
+Fill the four placeholders, then pass the whole text as the prompt to
+`npx genex image "<filled prompt>" --size 2560x1440 --quality high`.
+
+Placeholders:
+
+- `[GENRE_BRIEF]` — one-line genre description, anchored in a recognizable
+  register ("a dark gothic action RPG", "a sun-bleached rally racing game",
+  "a hand-painted storybook platformer").
+- `[GAME_SCENE]` — what's behind the HUD ("a dark medieval cathedral interior
+  with candlelight"). Only the scene may show 3D depth — never the HUD.
+- `[STYLE_BRIEF]` — your full 3–5 sentence style brief with the named 4–5 hue
+  palette. Do NOT append the per-sprite cutout sentence here — this is a full
+  frame, not a cutout.
+- `[ELEMENT_LIST]` — a bullet list of your 4–7 chosen widgets with one-line
+  descriptions. List only asset-backed widgets; pure-geometry elements
+  (crosshairs, tick rails, plain shapes) are built in code and stay off the
+  list.
+
+## The template
+
+```
+A screenshot of a complete game HUD for [GENRE_BRIEF]. The HUD is composited over a [GAME_SCENE] visible behind it.
+
+Visual style: [STYLE_BRIEF]
+
+The HUD includes these elements, arranged naturally as a real game would lay them out (you decide the layout — do not force a grid, place each element where it makes the HUD readable and combat-ready):
+
+[ELEMENT_LIST]
+
+This is a real in-game screenshot. Sharp detail on every UI element. No motion blur on the HUD. The HUD is clear and combat-readable. No watermarks. No external annotations.
+
+CRITICAL — flat HUD framing: draw every HUD element flat and head-on, parallel to the screen plane, like a 2D overlay painted directly onto the display (orthographic / screen-space UI). The HUD must NOT be tilted, angled, skewed, rotated in 3D, shown in perspective, or made to recede into depth — no isometric interface, no vanishing point on the panels, no 3D-extruded or floating-at-an-angle widgets, no curved/wrapped screen. ONLY the game scene behind the HUD may show 3D depth and perspective; the HUD layer itself is a flat 2D plane with square-on, axis-aligned edges, so each widget can be cleanly cut out as a flat sprite.
+```
+
+Never delete the flat-framing paragraph — a tilted or perspective mockup does
+not deconstruct cleanly (angled panel edges have no clean silhouette, so
+Stage 2 produces sliced, skewed cutouts). If the mockup comes back tilted,
+regenerate it before proceeding; do not try to salvage it downstream.
+
+The mockup is the **layout reference**: save its URL, compare the finished
+HUD against it, and sample runtime text colors from it with
+`npx genex ui text-color`.