frogoe 0.3.2 → 0.6.0

package/dist/injected-runtime.js

@@ -0,0 +1,247 @@
+/** The pixel analyzers — shared between Node (unit tests, CLI decisions)
+ *  and browser pages (raster/vision injection). This file is shipped
+ *  VERBATIM (never bundled — esbuild renames cross-references and breaks
+ *  toString() injection; see the bun-vs-esbuild divergence incident).
+ *  In the page it is injected as-is; in Node it is imported as-is. */
+
+// ── luminance / contrast (WCAG) ──────────────────────────────────────────
+const luminance = (r, g, b) => {
+  const ch = (c) => {
+    const s = c / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * ch(r) + 0.7152 * ch(g) + 0.0722 * ch(b);
+};
+
+const contrastRatio = (a, b) => (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+
+// ── composition metrics (coverage + dead rows) ───────────────────────────
+const compositionMetrics = (data, width, height, rows, palette) => {
+  const hex = (palette && palette.bg) || "#000000";
+  const pr = parseInt(hex.slice(1, 3), 16);
+  const pg = parseInt(hex.slice(3, 5), 16);
+  const pb = parseInt(hex.slice(5, 7), 16);
+  let ink = 0,
+    total = 0,
+    deadRows = 0;
+  for (let gy = 0; gy < rows; gy++) {
+    let rowInk = 0,
+      rowTotal = 0;
+    const y0 = Math.floor((gy * height) / rows);
+    const y1 = Math.floor(((gy + 1) * height) / rows);
+    for (let y = y0; y < y1; y += 2) {
+      for (let x = 0; x < width; x += 2) {
+        const at = (y * width + x) * 4;
+        const isBg =
+          Math.abs((data[at] || 0) - pr) +
+            Math.abs((data[at + 1] || 0) - pg) +
+            Math.abs((data[at + 2] || 0) - pb) <
+          60;
+        rowTotal++;
+        rowInk += isBg ? 0 : 1;
+      }
+    }
+    if (rowTotal > 0 && rowInk / rowTotal < 0.08) deadRows++;
+    ink += rowInk;
+    total += rowTotal;
+  }
+  return { coverage: total > 0 ? ink / total : 0, deadRows: deadRows, rows: rows };
+};
+
+// ── title-band analyzer (upper field, logotype-scale ink) ────────────────
+const analyzeTitleBand = (data, width, height) => {
+  const fieldHeight = Math.floor(height * 0.65);
+  const fieldBuckets = new Map();
+  for (let y = 0; y < fieldHeight; y += 2) {
+    for (let x = 0; x < width; x += 2) {
+      const at = (y * width + x) * 4;
+      const key =
+        (((data[at] || 0) >> 4) << 8) |
+        (((data[at + 1] || 0) >> 4) << 4) |
+        ((data[at + 2] || 0) >> 4);
+      fieldBuckets.set(key, (fieldBuckets.get(key) || 0) + 1);
+    }
+  }
+  let groundKey = 0,
+    groundHits = -1;
+  for (const [key, hits] of fieldBuckets) {
+    if (hits > groundHits) {
+      groundHits = hits;
+      groundKey = key;
+    }
+  }
+  const ground = [
+    ((groundKey >> 8) & 15) * 17,
+    ((groundKey >> 4) & 15) * 17,
+    (groundKey & 15) * 17,
+  ];
+  const groundLum = luminance(ground[0], ground[1], ground[2]);
+  const isInk = (x, y) => {
+    const at = (y * width + x) * 4;
+    return (
+      contrastRatio(luminance(data[at] || 0, data[at + 1] || 0, data[at + 2] || 0), groundLum) >= 3
+    );
+  };
+  const rowInkMin = Math.ceil((width / 2) * 0.15);
+  const wideRowMin = Math.ceil((width / 2) * 0.4);
+  let inkCount = 0,
+    inkTotal = 0,
+    textBottom = -1;
+  let bbox = null;
+  for (let y = 0; y < fieldHeight; y += 2) {
+    let rowInk = 0;
+    for (let x = 0; x < width; x += 2) {
+      if (isInk(x, y)) rowInk++;
+    }
+    inkTotal += Math.ceil(width / 2);
+    if (rowInk >= wideRowMin) textBottom = y;
+    if (rowInk >= rowInkMin) {
+      inkCount += Math.ceil(width / 2);
+      if (bbox === null) bbox = [width, y, 0, y];
+      bbox = [bbox[0], bbox[1], bbox[2], y];
+    }
+  }
+  if (bbox !== null) {
+    const bins = new Map();
+    for (let y = bbox[1]; y <= bbox[3]; y += 2) {
+      for (let x = 0; x < width; x += 2) {
+        if (isInk(x, y)) {
+          const bin = x >> 2;
+          bins.set(bin, (bins.get(bin) || 0) + 1);
+        }
+      }
+    }
+    const sorted = [...bins.keys()].sort((a, b) => a - b);
+    const GAP_BINS = 6;
+    let best = null,
+      runFrom = -1,
+      runTo = -1,
+      runInk = 0;
+    for (let i = 0; i <= sorted.length; i++) {
+      const bin = sorted[i] !== undefined ? sorted[i] : Number.MAX_SAFE_INTEGER;
+      const prev = sorted[i - 1] !== undefined ? sorted[i - 1] : bin;
+      const starts = i === 0 || bin - prev > GAP_BINS;
+      if (starts && runFrom !== -1) {
+        if (best === null || runInk > best[2]) best = [runFrom, runTo, runInk];
+        runFrom = -1;
+        runInk = 0;
+      }
+      if (i === sorted.length) break;
+      if (runFrom === -1) runFrom = bin;
+      runTo = bin;
+      runInk += bins.get(bin) || 0;
+    }
+    if (best !== null) bbox = [best[0] * 4, bbox[1], best[1] * 4 + 2, bbox[3]];
+    else bbox = null;
+  }
+  return {
+    bandHeight: fieldHeight,
+    ground: ground,
+    inkBBox: bbox,
+    inkCount: inkCount,
+    inkTotal: inkTotal,
+    textBottom: textBottom,
+  };
+};
+
+// ── icon corner analyzer ──────────────────────────────────────────────────
+const analyzeIconCorners = (data, width, _height) => {
+  const read = (x, y) => {
+    let r = 0,
+      g = 0,
+      b = 0,
+      a = 0;
+    for (let dy = 0; dy < 4; dy++) {
+      for (let dx = 0; dx < 4; dx++) {
+        const at = ((y + dy) * width + (x + dx)) * 4;
+        r += data[at] || 0;
+        g += data[at + 1] || 0;
+        b += data[at + 2] || 0;
+        a += data[at + 3] || 0;
+      }
+    }
+    return [Math.round(r / 16), Math.round(g / 16), Math.round(b / 16), Math.round(a / 16)];
+  };
+  const last = width - 4;
+  return { corners: [read(0, 0), read(last, 0), read(0, last), read(last, last)] };
+};
+
+// ── safe-zone collision (declared band clearance) ─────────────────────────
+const findTitleZoneCollision = (data, width, height, band) => {
+  if (band === null || band === undefined) return null;
+  const x0 = Math.max(0, Math.round(band[0]));
+  const y0 = Math.max(0, Math.round(band[1]));
+  const x1 = Math.min(width - 1, Math.round(band[2]));
+  const y1 = Math.min(height - 1, Math.round(band[3]));
+  const lumOf = (x, y) => {
+    const at = (y * width + x) * 4;
+    return luminance(data[at] || 0, data[at + 1] || 0, data[at + 2] || 0);
+  };
+  const buckets = new Map();
+  for (let y = y0; y <= y1; y += 2) {
+    for (let x = 0; x < width; x += 2) {
+      const at = (y * width + x) * 4;
+      const key =
+        (((data[at] || 0) >> 4) << 8) |
+        (((data[at + 1] || 0) >> 4) << 4) |
+        ((data[at + 2] || 0) >> 4);
+      buckets.set(key, (buckets.get(key) || 0) + 1);
+    }
+  }
+  let gk = 0,
+    gh = -1;
+  for (const [k, h] of buckets) {
+    if (h > gh) {
+      gh = h;
+      gk = k;
+    }
+  }
+  const groundLum = luminance(((gk >> 8) & 15) * 17, ((gk >> 4) & 15) * 17, (gk & 15) * 17);
+  const isLnk = (x, y) => contrastRatio(lumOf(x, y), groundLum) >= 3;
+  const ceiling = [];
+  for (let x = 0; x < width; x += 4) {
+    for (let y = 0; y < 6; y += 2) {
+      if (isLnk(x, y)) {
+        ceiling.push(x);
+        break;
+      }
+    }
+  }
+  const nearCeiling = (x) => {
+    for (const c of ceiling) {
+      if (Math.abs(x - c) <= 8) return true;
+    }
+    return false;
+  };
+  const unit = width / 540;
+  const margin = Math.round(24 * unit);
+  const blobMin = Math.round(12 * unit);
+  const countMin = Math.round(30 * (unit / 2));
+  let floaters = 0,
+    widest = 0;
+  const windowBottom = Math.min(height - 1, y1 + margin);
+  for (let y = y1 + 2; y <= windowBottom; y += 2) {
+    let run = 0;
+    for (let x = x0; x <= x1 + 2; x += 2) {
+      if (x <= x1 && isLnk(x, y) && !nearCeiling(x)) {
+        run += 2;
+        floaters++;
+      } else {
+        if (run > widest) widest = run;
+        run = 0;
+      }
+    }
+  }
+  if (floaters >= countMin && widest >= blobMin) {
+    return (
+      "bundle/art-title-collision — a free-floating blob (" +
+      widest +
+      "px wide) parks in the clearance margin under the lettering block (rows " +
+      (y1 + 2) +
+      ".." +
+      windowBottom +
+      "): free world must clear the block by ~its own radius — relocate below or compose around it (ceiling-hung world is the one legal crosser) — frogoe-creative → references/art.md"
+    );
+  }
+  return null;
+};

package/dist/templates/_shared/AGENTS.md

@@ -6,9 +6,9 @@
 
 **Doing anything with frogoe?** Read the `/frogoe` skill — it confirms the BRIEF (verb, mood, palette) up front and routes every request. The domain skills it routes to:
 
-- `/frogoe-core` — the technical contract: folder form, `defineGame` closure, four nouns, HUD bindings, external libraries. Read before writing any game code.
-- `/frogoe-creative` — house style: three dials (VARIANCE/MOTION/DENSITY), lazy defaults, typography, palettes, game feel. Read when choosing how a game looks.
-- `/frogoe-cli` — CLI dev loop: init, add, run, check, bundle, report. Finding codes split into `finding-codes.md` / `live-sandbox.md` / `bundle.md` for self-healing.
+- `/frogoe-core` — the technical contract: folder form, `defineGame` closure, four nouns, HUD bindings, external libraries, the identity-art assets (`assets/poster.js` + `assets/icon.js`). Read before writing any game code.
+- `/frogoe-creative` — house style: three dials (VARIANCE/MOTION/DENSITY), lazy defaults, typography, palettes, game feel, identity art (the poster + icon are authored, 1:1 with gameplay). Read when choosing how a game looks — including its face.
+- `/frogoe-cli` — CLI dev loop: init, add, run, vision (ASCII eyes for draw code), check, bundle, embed (the card + manifest), report. Finding codes split into `finding-codes.md` / `live-sandbox.md` / `bundle.md` / `embed.md` / `vision.md` for self-healing.
 - `/frogoe-registry` — HUD block catalog: find, evaluate, install, author new blocks.
 
 Skills live at `.claude/skills/` and `.agents/skills/` (install via `npx skills add frogoe/engine`; both mirrors stay byte-identical). Missing or stale? Re-run the install and restart the agent session. Check freshness: `frogoe skills check`.
@@ -57,7 +57,9 @@ frogoe run --tunnel         # + public URL — phone works on any network (cloud
 frogoe add <block>          # copy a HUD block into blocks/ (score, hearts, fuel, game-over, etc.)
 frogoe lint                 # fast static contract lint (stable finding codes; --json for CI)
 frogoe check                # full gate: lint + headless Chrome — FPS, playability, HUD outline, screenshots
+frogoe vision               # eyes: your draw code as ASCII maps (objects, frames, identity art)
 frogoe bundle               # one self-contained HTML (externals dissolved) — only after check passes
+frogoe embed                # the card: poster loading state + sandboxed game + manifest — after bundle
 ```
 
 > **Agents must run `frogoe check` after ANY code change** and fix all errors before
@@ -70,6 +72,7 @@ bundle`. Use `--json` for machine-readable findings that can be fixed programmat
 - `index.html` — entry shell: `<canvas id="c">` + import map + `.hud` layer (HUD blocks land here)
 - `game.js` — the whole simulation: `defineGame(({stage, input, loop, finish}) => {...})`
 - `BRIEF.md` — the game's identity: verb, mood, palette (validated by `frogoe check`)
+- `assets/poster.js` + `assets/icon.js` — REQUIRED identity art: canvas scenes importing the game's own sprites (`art/missing` gates the check; frogoe-creative → `references/art.md`)
 - `frogoe.json` — contract version pin
 - `.frogoe/` — tool-owned, gitignored (the contract runtime — never edit)
 - `blocks/` — HUD blocks copied from the registry (themed via `.hud` CSS custom properties)
@@ -86,15 +89,17 @@ frogoe check             # full gate: + browser — runtime errors, canvas paint
 
 Fix all errors before presenting the result. Common findings:
 
-| Code                     | Meaning                                                 | Fix                                                                                          |
-| ------------------------ | ------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| `brief/todo`             | BRIEF.md still has TODO markers                         | Fill in verb, mood, palette                                                                  |
-| `input/incremental-drag` | `x += p.dx` (wall-rocket bug)                           | Use `x = grabX + p.dx` or track lastX                                                        |
-| `folder/touch-select`    | Phone long-press summons text selection (iOS + Android) | Add `-webkit-user-select: none; user-select: none; -webkit-touch-callout: none` on html/body |
-| `audio/suspended-only`   | Resume gated on `=== "suspended"` (iOS silent bug)      | Resume when `state !== "running"` — see frogoe-core `references/audio.md`                    |
-| `live/hud-outline`       | HUD text missing text-shadow/stroke                     | Add `text-shadow: 0 2px 0 <dark>`                                                            |
-| `live/fps`               | Below 30fps                                             | Cache gradients, reduce shadowBlur, cut particles                                            |
-| `live/not-playable`      | Scripted taps changed nothing                           | Wire `input.on("down")` to actual game logic                                                 |
+| Code                     | Meaning                                                 | Fix                                                                                           |
+| ------------------------ | ------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `brief/todo`             | BRIEF.md still has TODO markers                         | Fill in verb, mood, palette                                                                   |
+| `art/missing`            | `assets/poster.js` / `assets/icon.js` absent            | Author both scenes — they import sprites from game.js (frogoe-creative → `references/art.md`) |
+| `art/title-band`         | poster declares no lettering-block band                 | Set `ctx.__frogoeTitleBand = [x0,y0,x1,y1]` from the layout variables (never hand-typed)      |
+| `input/incremental-drag` | `x += p.dx` (wall-rocket bug)                           | Use `x = grabX + p.dx` or track lastX                                                         |
+| `folder/touch-select`    | Phone long-press summons text selection (iOS + Android) | Add `-webkit-user-select: none; user-select: none; -webkit-touch-callout: none` on html/body  |
+| `audio/suspended-only`   | Resume gated on `=== "suspended"` (iOS silent bug)      | Resume when `state !== "running"` — see frogoe-core `references/audio.md`                     |
+| `live/hud-outline`       | HUD text missing text-shadow/stroke                     | Add `text-shadow: 0 2px 0 <dark>`                                                             |
+| `live/fps`               | Below 30fps                                             | Cache gradients, reduce shadowBlur, cut particles                                             |
+| `live/not-playable`      | Scripted taps changed nothing                           | Wire `input.on("down")` to actual game logic                                                  |
 
 ## Key rules
 
@@ -104,3 +109,4 @@ Fix all errors before presenting the result. Common findings:
 4. **Fixed furniture respects `stage.safe`** — notches cover screen edges. Score at fixed y=34 sits under the Dynamic Island on modern phones.
 5. **One page, zero runtime requests** after bundling. Author-time CDN dependencies are fine — `frogoe bundle` dissolves them (allowlist + pin + hash + inline).
 6. **`finish(score)`** ends the run. The results card is a HUD block (`game-over-card`), never something the platform draws.
+7. **Identity art is authored, never captured** — `assets/poster.js` + `assets/icon.js` draw with the game's own sprite functions (1:1 by construction; `art/*` findings gate them). Iterate with `frogoe vision` — render, LOOK at the ASCII map, fix; agents that draw blind ship blobs.

package/dist/templates/_shared/CLAUDE.md

@@ -6,9 +6,9 @@
 
 **Doing anything with frogoe?** Start at the `/frogoe` skill — it confirms the BRIEF (verb, mood, palette) up front and routes every request. The domain skills it routes to:
 
-- `/frogoe-core` — the technical contract: folder form, `defineGame` closure, four nouns, HUD bindings, external libraries. Read before writing any game code.
-- `/frogoe-creative` — house style: three dials (VARIANCE/MOTION/DENSITY), lazy defaults, typography, palettes, game feel. Read when choosing how a game looks.
-- `/frogoe-cli` — CLI dev loop: init, add, run, check, bundle, report. Finding codes split into `finding-codes.md` / `live-sandbox.md` / `bundle.md` for self-healing.
+- `/frogoe-core` — the technical contract: folder form, `defineGame` closure, four nouns, HUD bindings, external libraries, the identity-art assets (`assets/poster.js` + `assets/icon.js`). Read before writing any game code.
+- `/frogoe-creative` — house style: three dials (VARIANCE/MOTION/DENSITY), lazy defaults, typography, palettes, game feel, identity art (the poster + icon are authored, 1:1 with gameplay). Read when choosing how a game looks — including its face.
+- `/frogoe-cli` — CLI dev loop: init, add, run, vision (ASCII eyes for draw code), check, bundle, embed (the card + manifest), report. Finding codes split into `finding-codes.md` / `live-sandbox.md` / `bundle.md` / `embed.md` / `vision.md` for self-healing.
 - `/frogoe-registry` — HUD block catalog: find, evaluate, install, author new blocks.
 
 Skills live at `.claude/skills/` and `.agents/skills/` (install via `npx skills add frogoe/engine`; both mirrors stay byte-identical). Missing or stale? Re-run the install and restart the agent session. Check freshness: `frogoe skills check`.
@@ -57,7 +57,9 @@ frogoe run --tunnel         # + public URL — phone works on any network (cloud
 frogoe add <block>          # copy a HUD block into blocks/ (score, hearts, fuel, game-over, etc.)
 frogoe lint                 # fast static contract lint (stable finding codes; --json for CI)
 frogoe check                # full gate: lint + headless Chrome — FPS, playability, HUD outline, screenshots
+frogoe vision               # eyes: your draw code as ASCII maps (objects, frames, identity art)
 frogoe bundle               # one self-contained HTML (externals dissolved) — only after check passes
+frogoe embed                # the card: poster loading state + sandboxed game + manifest — after bundle
 ```
 
 > **Agents must run `frogoe check` after ANY code change** and fix all errors before
@@ -70,6 +72,7 @@ bundle`. Use `--json` for machine-readable findings that can be fixed programmat
 - `index.html` — entry shell: `<canvas id="c">` + import map + `.hud` layer (HUD blocks land here)
 - `game.js` — the whole simulation: `defineGame(({stage, input, loop, finish}) => {...})`
 - `BRIEF.md` — the game's identity: verb, mood, palette (validated by `frogoe check`)
+- `assets/poster.js` + `assets/icon.js` — REQUIRED identity art: canvas scenes importing the game's own sprites (`art/missing` gates the check; frogoe-creative → `references/art.md`)
 - `frogoe.json` — contract version pin
 - `.frogoe/` — tool-owned, gitignored (the contract runtime — never edit)
 - `blocks/` — HUD blocks copied from the registry (themed via `.hud` CSS custom properties)
@@ -86,15 +89,17 @@ frogoe check             # full gate: + browser — runtime errors, canvas paint
 
 Fix all errors before presenting the result. Common findings:
 
-| Code                     | Meaning                                                 | Fix                                                                                          |
-| ------------------------ | ------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| `brief/todo`             | BRIEF.md still has TODO markers                         | Fill in verb, mood, palette                                                                  |
-| `input/incremental-drag` | `x += p.dx` (wall-rocket bug)                           | Use `x = grabX + p.dx` or track lastX                                                        |
-| `folder/touch-select`    | Phone long-press summons text selection (iOS + Android) | Add `-webkit-user-select: none; user-select: none; -webkit-touch-callout: none` on html/body |
-| `audio/suspended-only`   | Resume gated on `=== "suspended"` (iOS silent bug)      | Resume when `state !== "running"` — see frogoe-core `references/audio.md`                    |
-| `live/hud-outline`       | HUD text missing text-shadow/stroke                     | Add `text-shadow: 0 2px 0 <dark>`                                                            |
-| `live/fps`               | Below 30fps                                             | Cache gradients, reduce shadowBlur, cut particles                                            |
-| `live/not-playable`      | Scripted taps changed nothing                           | Wire `input.on("down")` to actual game logic                                                 |
+| Code                     | Meaning                                                 | Fix                                                                                           |
+| ------------------------ | ------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `brief/todo`             | BRIEF.md still has TODO markers                         | Fill in verb, mood, palette                                                                   |
+| `art/missing`            | `assets/poster.js` / `assets/icon.js` absent            | Author both scenes — they import sprites from game.js (frogoe-creative → `references/art.md`) |
+| `art/title-band`         | poster declares no lettering-block band                 | Set `ctx.__frogoeTitleBand = [x0,y0,x1,y1]` from the layout variables (never hand-typed)      |
+| `input/incremental-drag` | `x += p.dx` (wall-rocket bug)                           | Use `x = grabX + p.dx` or track lastX                                                         |
+| `folder/touch-select`    | Phone long-press summons text selection (iOS + Android) | Add `-webkit-user-select: none; user-select: none; -webkit-touch-callout: none` on html/body  |
+| `audio/suspended-only`   | Resume gated on `=== "suspended"` (iOS silent bug)      | Resume when `state !== "running"` — see frogoe-core `references/audio.md`                     |
+| `live/hud-outline`       | HUD text missing text-shadow/stroke                     | Add `text-shadow: 0 2px 0 <dark>`                                                             |
+| `live/fps`               | Below 30fps                                             | Cache gradients, reduce shadowBlur, cut particles                                             |
+| `live/not-playable`      | Scripted taps changed nothing                           | Wire `input.on("down")` to actual game logic                                                  |
 
 ## Key rules
 
@@ -104,3 +109,4 @@ Fix all errors before presenting the result. Common findings:
 4. **Fixed furniture respects `stage.safe`** — notches cover screen edges. Score at fixed y=34 sits under the Dynamic Island on modern phones.
 5. **One page, zero runtime requests** after bundling. Author-time CDN dependencies are fine — `frogoe bundle` dissolves them (allowlist + pin + hash + inline).
 6. **`finish(score)`** ends the run. The results card is a HUD block (`game-over-card`), never something the platform draws.
+7. **Identity art is authored, never captured** — `assets/poster.js` + `assets/icon.js` draw with the game's own sprite functions (1:1 by construction; `art/*` findings gate them). Iterate with `frogoe vision` — render, LOOK at the ASCII map, fix; agents that draw blind ship blobs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frogoe",
-  "version": "0.3.2",
+  "version": "0.6.0",
   "description": "froge CLI — the agent's hands: init, add, run, check, bundle",
   "homepage": "https://github.com/frogoe/engine#readme",
   "bugs": "https://github.com/frogoe/engine/issues",