@pix3/cli 1.6.0 → 1.6.2

package/templates/minigame-2d/files/scripts/SettingsWindow.ts

@@ -1,198 +1,198 @@
-/**
- * SettingsWindow — behavior for the settings-window prefab.
- *
- * Attach to the prefab root. The Music / SFX checkboxes mute or restore the
- * engine audio buses (`scene.audio.setBusVolume`), CLOSE hides the window.
- * Node lookups are relative to the prefab subtree so multiple instances work.
- *
- * Handlers are **intent-first**: each behaviour lives in a named public method
- * marked `Intent:`, and the signal handlers below do nothing but call one. The
- * two switches are also registered as commands — `settings.toggle-music` /
- * `settings.toggle-sfx`, namespaced so this prefab's intents never collide with
- * the menu's `open-settings` / `close-settings` — so a test flips sound without
- * hunting for a checkbox on screen.
- *
- * Note on the checkboxes: they are event-driven, not polled. `Checkbox2D` splits
- * its signals the way Godot does — `click` is the POINTER signal ("the box was
- * clicked"), `toggled` is the STATE signal ("the box is now checked/unchecked"),
- * emitted after the flip with the new value as its payload. Anything that
- * applies the state connects to `toggled`, so the handler can simply read
- * `checked` (or take the payload) and get the value the user just chose.
- */
-import { Script, Checkbox2D, type NodeBase, type PropertySchema } from '@pix3/runtime';
-
-/** One live signal connection, kept so `onDetach` can take it back down. */
-interface SignalBinding {
-  node: NodeBase;
-  signal: string;
-  handler: () => void;
-}
-
-export class SettingsWindow extends Script {
-  private musicToggle: Checkbox2D | null = null;
-  private sfxToggle: Checkbox2D | null = null;
-  private readonly bindings: SignalBinding[] = [];
-  private disposeCommands: (() => void)[] = [];
-
-  constructor(id: string, type: string) {
-    super(id, type);
-    this.config = {
-      musicToggle: 'music-toggle',
-      sfxToggle: 'sfx-toggle',
-      closeButton: 'close-button',
-    };
-  }
-
-  static getPropertySchema(): PropertySchema {
-    return {
-      nodeType: 'SettingsWindow',
-      properties: [
-        {
-          name: 'musicToggle',
-          type: 'string',
-          ui: { label: 'Music Checkbox', group: 'Settings' },
-          getValue: s => (s as SettingsWindow).config.musicToggle,
-          setValue: (s, v) => {
-            (s as SettingsWindow).config.musicToggle = typeof v === 'string' ? v : '';
-          },
-        },
-        {
-          name: 'sfxToggle',
-          type: 'string',
-          ui: { label: 'SFX Checkbox', group: 'Settings' },
-          getValue: s => (s as SettingsWindow).config.sfxToggle,
-          setValue: (s, v) => {
-            (s as SettingsWindow).config.sfxToggle = typeof v === 'string' ? v : '';
-          },
-        },
-        {
-          name: 'closeButton',
-          type: 'string',
-          ui: { label: 'Close Button', group: 'Settings' },
-          getValue: s => (s as SettingsWindow).config.closeButton,
-          setValue: (s, v) => {
-            (s as SettingsWindow).config.closeButton = typeof v === 'string' ? v : '';
-          },
-        },
-      ],
-      groups: { Settings: { label: 'Settings Window', expanded: true } },
-    };
-  }
-
-  onStart(): void {
-    this.musicToggle = this.findInSubtree(String(this.config.musicToggle ?? ''));
-    this.sfxToggle = this.findInSubtree(String(this.config.sfxToggle ?? ''));
-
-    // Match the buses to the boxes as authored, before anyone clicks anything:
-    // without the old per-frame read, nothing else would ever apply the initial state.
-    if (this.musicToggle) {
-      this.setMusicEnabled(this.musicToggle.checked);
-    }
-    if (this.sfxToggle) {
-      this.setSfxEnabled(this.sfxToggle.checked);
-    }
-
-    this.connectToggle(this.musicToggle, enabled => this.setMusicEnabled(enabled));
-    this.connectToggle(this.sfxToggle, enabled => this.setSfxEnabled(enabled));
-
-    // The commands flip the BOX, not the bus: `toggled` then applies the bus, so
-    // a dispatched intent leaves exactly the state a tap would (checkmark, bus,
-    // snapshot). Applying the bus here instead would drift the two apart, and
-    // dispatching from the `toggled` handler would make the command dispatch
-    // itself — the registry caps that recursion, but the loop is the bug.
-    const commands = this.scene?.commands;
-    this.disposeCommands = [
-      commands?.register('settings.toggle-music', () => this.musicToggle?.toggle(), {
-        description: 'Flip the music checkbox, muting or restoring the music bus.',
-      }),
-      commands?.register('settings.toggle-sfx', () => this.sfxToggle?.toggle(), {
-        description: 'Flip the SFX checkbox, muting or restoring the sound-effects bus.',
-      }),
-    ].filter((dispose): dispose is () => void => dispose !== undefined);
-
-    const closeButton = this.findInSubtree<NodeBase>(String(this.config.closeButton ?? ''));
-    if (closeButton) {
-      this.bind(closeButton, 'pressed', () => this.closeWindow());
-    } else {
-      console.warn('[SettingsWindow] Close button not found.');
-    }
-  }
-
-  onDetach(): void {
-    for (const binding of this.bindings) {
-      binding.node.disconnect(binding.signal, this, binding.handler);
-    }
-    this.bindings.length = 0;
-    // A settings window can be freed while its scene keeps running, and a
-    // command pointing at a detached prefab is exactly the dead intent the
-    // registry's scene-scoped lifetime is meant to prevent.
-    for (const dispose of this.disposeCommands) {
-      dispose();
-    }
-    this.disposeCommands = [];
-    this.musicToggle = null;
-    this.sfxToggle = null;
-  }
-
-  /** Intent: hide the settings window. */
-  closeWindow(): void {
-    if (this.node) {
-      this.node.visible = false;
-    }
-  }
-
-  /** Intent: mute or restore the music bus. */
-  setMusicEnabled(enabled: boolean): void {
-    if (!this.scene) {
-      return; // No audio yet — the next click applies it.
-    }
-    this.scene.audio.setBusVolume('music', enabled ? 1 : 0);
-  }
-
-  /** Intent: mute or restore the sound-effects bus. */
-  setSfxEnabled(enabled: boolean): void {
-    if (!this.scene) {
-      return;
-    }
-    this.scene.audio.setBusVolume('sfx', enabled ? 1 : 0);
-  }
-
-  /**
-   * Call `apply` with the checkbox's new state. `toggled` fires once the flip is
-   * applied, so `checked` is the value the user just chose.
-   */
-  private connectToggle(toggle: Checkbox2D | null, apply: (enabled: boolean) => void): void {
-    if (!toggle) {
-      return;
-    }
-    this.bind(toggle, 'toggled', () => apply(toggle.checked));
-  }
-
-  /** Connect a signal and remember it, so `onDetach` leaves no listener behind. */
-  private bind(node: NodeBase, signal: string, handler: () => void): void {
-    node.connect(signal, this, handler);
-    this.bindings.push({ node, signal, handler });
-  }
-
-  /** Search this prefab's subtree by node id or name (instance-safe). */
-  private findInSubtree<T extends NodeBase = NodeBase>(query: string): T | null {
-    if (!query || !this.node) {
-      return null;
-    }
-    const visit = (node: NodeBase): NodeBase | null => {
-      if (node.nodeId === query || node.name === query) {
-        return node;
-      }
-      for (const child of node.children) {
-        if (child instanceof Object && 'nodeId' in child) {
-          const found = visit(child as NodeBase);
-          if (found) {
-            return found;
-          }
-        }
-      }
-      return null;
-    };
-    return visit(this.node) as T | null;
-  }
-}
+/**
+ * SettingsWindow — behavior for the settings-window prefab.
+ *
+ * Attach to the prefab root. The Music / SFX checkboxes mute or restore the
+ * engine audio buses (`scene.audio.setBusVolume`), CLOSE hides the window.
+ * Node lookups are relative to the prefab subtree so multiple instances work.
+ *
+ * Handlers are **intent-first**: each behaviour lives in a named public method
+ * marked `Intent:`, and the signal handlers below do nothing but call one. The
+ * two switches are also registered as commands — `settings.toggle-music` /
+ * `settings.toggle-sfx`, namespaced so this prefab's intents never collide with
+ * the menu's `open-settings` / `close-settings` — so a test flips sound without
+ * hunting for a checkbox on screen.
+ *
+ * Note on the checkboxes: they are event-driven, not polled. `Checkbox2D` splits
+ * its signals the way Godot does — `click` is the POINTER signal ("the box was
+ * clicked"), `toggled` is the STATE signal ("the box is now checked/unchecked"),
+ * emitted after the flip with the new value as its payload. Anything that
+ * applies the state connects to `toggled`, so the handler can simply read
+ * `checked` (or take the payload) and get the value the user just chose.
+ */
+import { Script, Checkbox2D, type NodeBase, type PropertySchema } from '@pix3/runtime';
+
+/** One live signal connection, kept so `onDetach` can take it back down. */
+interface SignalBinding {
+  node: NodeBase;
+  signal: string;
+  handler: () => void;
+}
+
+export class SettingsWindow extends Script {
+  private musicToggle: Checkbox2D | null = null;
+  private sfxToggle: Checkbox2D | null = null;
+  private readonly bindings: SignalBinding[] = [];
+  private disposeCommands: (() => void)[] = [];
+
+  constructor(id: string, type: string) {
+    super(id, type);
+    this.config = {
+      musicToggle: 'music-toggle',
+      sfxToggle: 'sfx-toggle',
+      closeButton: 'close-button',
+    };
+  }
+
+  static getPropertySchema(): PropertySchema {
+    return {
+      nodeType: 'SettingsWindow',
+      properties: [
+        {
+          name: 'musicToggle',
+          type: 'string',
+          ui: { label: 'Music Checkbox', group: 'Settings' },
+          getValue: s => (s as SettingsWindow).config.musicToggle,
+          setValue: (s, v) => {
+            (s as SettingsWindow).config.musicToggle = typeof v === 'string' ? v : '';
+          },
+        },
+        {
+          name: 'sfxToggle',
+          type: 'string',
+          ui: { label: 'SFX Checkbox', group: 'Settings' },
+          getValue: s => (s as SettingsWindow).config.sfxToggle,
+          setValue: (s, v) => {
+            (s as SettingsWindow).config.sfxToggle = typeof v === 'string' ? v : '';
+          },
+        },
+        {
+          name: 'closeButton',
+          type: 'string',
+          ui: { label: 'Close Button', group: 'Settings' },
+          getValue: s => (s as SettingsWindow).config.closeButton,
+          setValue: (s, v) => {
+            (s as SettingsWindow).config.closeButton = typeof v === 'string' ? v : '';
+          },
+        },
+      ],
+      groups: { Settings: { label: 'Settings Window', expanded: true } },
+    };
+  }
+
+  onStart(): void {
+    this.musicToggle = this.findInSubtree(String(this.config.musicToggle ?? ''));
+    this.sfxToggle = this.findInSubtree(String(this.config.sfxToggle ?? ''));
+
+    // Match the buses to the boxes as authored, before anyone clicks anything:
+    // without the old per-frame read, nothing else would ever apply the initial state.
+    if (this.musicToggle) {
+      this.setMusicEnabled(this.musicToggle.checked);
+    }
+    if (this.sfxToggle) {
+      this.setSfxEnabled(this.sfxToggle.checked);
+    }
+
+    this.connectToggle(this.musicToggle, enabled => this.setMusicEnabled(enabled));
+    this.connectToggle(this.sfxToggle, enabled => this.setSfxEnabled(enabled));
+
+    // The commands flip the BOX, not the bus: `toggled` then applies the bus, so
+    // a dispatched intent leaves exactly the state a tap would (checkmark, bus,
+    // snapshot). Applying the bus here instead would drift the two apart, and
+    // dispatching from the `toggled` handler would make the command dispatch
+    // itself — the registry caps that recursion, but the loop is the bug.
+    const commands = this.scene?.commands;
+    this.disposeCommands = [
+      commands?.register('settings.toggle-music', () => this.musicToggle?.toggle(), {
+        description: 'Flip the music checkbox, muting or restoring the music bus.',
+      }),
+      commands?.register('settings.toggle-sfx', () => this.sfxToggle?.toggle(), {
+        description: 'Flip the SFX checkbox, muting or restoring the sound-effects bus.',
+      }),
+    ].filter((dispose): dispose is () => void => dispose !== undefined);
+
+    const closeButton = this.findInSubtree<NodeBase>(String(this.config.closeButton ?? ''));
+    if (closeButton) {
+      this.bind(closeButton, 'pressed', () => this.closeWindow());
+    } else {
+      console.warn('[SettingsWindow] Close button not found.');
+    }
+  }
+
+  onDetach(): void {
+    for (const binding of this.bindings) {
+      binding.node.disconnect(binding.signal, this, binding.handler);
+    }
+    this.bindings.length = 0;
+    // A settings window can be freed while its scene keeps running, and a
+    // command pointing at a detached prefab is exactly the dead intent the
+    // registry's scene-scoped lifetime is meant to prevent.
+    for (const dispose of this.disposeCommands) {
+      dispose();
+    }
+    this.disposeCommands = [];
+    this.musicToggle = null;
+    this.sfxToggle = null;
+  }
+
+  /** Intent: hide the settings window. */
+  closeWindow(): void {
+    if (this.node) {
+      this.node.visible = false;
+    }
+  }
+
+  /** Intent: mute or restore the music bus. */
+  setMusicEnabled(enabled: boolean): void {
+    if (!this.scene) {
+      return; // No audio yet — the next click applies it.
+    }
+    this.scene.audio.setBusVolume('music', enabled ? 1 : 0);
+  }
+
+  /** Intent: mute or restore the sound-effects bus. */
+  setSfxEnabled(enabled: boolean): void {
+    if (!this.scene) {
+      return;
+    }
+    this.scene.audio.setBusVolume('sfx', enabled ? 1 : 0);
+  }
+
+  /**
+   * Call `apply` with the checkbox's new state. `toggled` fires once the flip is
+   * applied, so `checked` is the value the user just chose.
+   */
+  private connectToggle(toggle: Checkbox2D | null, apply: (enabled: boolean) => void): void {
+    if (!toggle) {
+      return;
+    }
+    this.bind(toggle, 'toggled', () => apply(toggle.checked));
+  }
+
+  /** Connect a signal and remember it, so `onDetach` leaves no listener behind. */
+  private bind(node: NodeBase, signal: string, handler: () => void): void {
+    node.connect(signal, this, handler);
+    this.bindings.push({ node, signal, handler });
+  }
+
+  /** Search this prefab's subtree by node id or name (instance-safe). */
+  private findInSubtree<T extends NodeBase = NodeBase>(query: string): T | null {
+    if (!query || !this.node) {
+      return null;
+    }
+    const visit = (node: NodeBase): NodeBase | null => {
+      if (node.nodeId === query || node.name === query) {
+        return node;
+      }
+      for (const child of node.children) {
+        if (child instanceof Object && 'nodeId' in child) {
+          const found = visit(child as NodeBase);
+          if (found) {
+            return found;
+          }
+        }
+      }
+      return null;
+    };
+    return visit(this.node) as T | null;
+  }
+}

package/templates/minigame-2d/template.yaml

@@ -1,10 +1,10 @@
-id: minigame-2d
-title: Minigame 2D
-description: Separate menu + game scenes with a scene transition, and a reusable settings-window prefab (music/SFX toggles wired to audio buses).
-projectType: 2d
-targetPlatform: universal
-viewport: { width: 1920, height: 1080 }
-# The build/full-run entry scene (Project Settings → Default Export Scene Path).
-# The menu boots first; PLAY transitions to main.pix3scene (the game).
-entryScene: scenes/menu.pix3scene
-order: 50
+id: minigame-2d
+title: Minigame 2D
+description: Separate menu + game scenes with a scene transition, and a reusable settings-window prefab (music/SFX toggles wired to audio buses).
+projectType: 2d
+targetPlatform: universal
+viewport: { width: 1920, height: 1080 }
+# The build/full-run entry scene (Project Settings → Default Export Scene Path).
+# The menu boots first; PLAY transitions to main.pix3scene (the game).
+entryScene: scenes/menu.pix3scene
+order: 50

package/templates/playable-2d/files/README.md

@@ -1,30 +1,30 @@
-# {{PROJECT_NAME}}
-
-A Pix3 project created from the **Playable 2D** template — a portrait playable-ad blank.
-
-## What's included
-
-- **Tap-to-start intro** (`intro-overlay`, `scenes/ui/intro.pix3scene`) — the first tap unlocks browser audio and starts the game (`scripts/GameFlow.ts`).
-- **Gameplay placeholder** — replace the animated logo sprite in `main.pix3scene` with your game.
-- **End screen with CTA** (`end-screen`, `scenes/ui/end-screen.pix3scene`) — the PLAY NOW button reports game end (`playable.gameEnd()`) and logs the click. It opens nothing: the ad network decides the store target at delivery time (`mraid.open` / `dapi.openStoreUrl`), so wire its SDK in `CtaButton.ctaClick()` when you package the ad.
-- `GameFlow` shows the end screen automatically after `autoWinAfterSec` seconds — replace that with your real win/lose condition.
-- **Readable state** — `GameFlow` publishes a `registerGameDebug` snapshot (phase, timer, overlay visibility, session end), so tooling reads the run's state instead of judging it from a screenshot. Add your own fields as you add state.
-- **Intent-first handlers** — every reaction to the player is a named method (`GameFlow.start/finish/restart`, `CtaButton.ctaClick`) that the event handler merely calls; keep that shape and the game stays drivable by intent.
-
-## Project structure
-
-- `design/` — game design document and reference images
-- `design/tests/` — agent-testing material: `routines/*.json` (named step +
-  assertion scripts, written on the highest channel the game offers) and
-  `reachability.json` (controls proven reachable on a live run). The harness
-  that runs them is still in development; format and location are fixed now.
-- `scenes/` — scene files; `main.pix3scene` is the startup scene
-- `scenes/ui/` — the full-screen overlays (`intro.pix3scene`, `end-screen.pix3scene`),
-  instanced into `main.pix3scene` with `visible: false` so the editor opens on the
-  game. That flag is editor-only; `initiallyVisible` on each overlay's root is what
-  play mode reads. Edit an overlay in its own tab, or tick the eye on its instance
-  node to preview it composited — just don't save that tick.
-- `sprites/` — images and textures
-- `scripts/` — game scripts (`export class X extends Script`, used as `user:X`)
-- `audio/` — music and sound effects
-- `AGENTS.md` — rules and pointers for AI agents working on this project
+# {{PROJECT_NAME}}
+
+A Pix3 project created from the **Playable 2D** template — a portrait playable-ad blank.
+
+## What's included
+
+- **Tap-to-start intro** (`intro-overlay`, `scenes/ui/intro.pix3scene`) — the first tap unlocks browser audio and starts the game (`scripts/GameFlow.ts`).
+- **Gameplay placeholder** — replace the animated logo sprite in `main.pix3scene` with your game.
+- **End screen with CTA** (`end-screen`, `scenes/ui/end-screen.pix3scene`) — the PLAY NOW button reports game end (`playable.gameEnd()`) and logs the click. It opens nothing: the ad network decides the store target at delivery time (`mraid.open` / `dapi.openStoreUrl`), so wire its SDK in `CtaButton.ctaClick()` when you package the ad.
+- `GameFlow` shows the end screen automatically after `autoWinAfterSec` seconds — replace that with your real win/lose condition.
+- **Readable state** — `GameFlow` publishes a `registerGameDebug` snapshot (phase, timer, overlay visibility, session end), so tooling reads the run's state instead of judging it from a screenshot. Add your own fields as you add state.
+- **Intent-first handlers** — every reaction to the player is a named method (`GameFlow.start/finish/restart`, `CtaButton.ctaClick`) that the event handler merely calls; keep that shape and the game stays drivable by intent.
+
+## Project structure
+
+- `design/` — game design document and reference images
+- `design/tests/` — agent-testing material: `routines/*.json` (named step +
+  assertion scripts, written on the highest channel the game offers) and
+  `reachability.json` (controls proven reachable on a live run). The harness
+  that runs them is still in development; format and location are fixed now.
+- `scenes/` — scene files; `main.pix3scene` is the startup scene
+- `scenes/ui/` — the full-screen overlays (`intro.pix3scene`, `end-screen.pix3scene`),
+  instanced into `main.pix3scene` with `visible: false` so the editor opens on the
+  game. That flag is editor-only; `initiallyVisible` on each overlay's root is what
+  play mode reads. Edit an overlay in its own tab, or tick the eye on its instance
+  node to preview it composited — just don't save that tick.
+- `sprites/` — images and textures
+- `scripts/` — game scripts (`export class X extends Script`, used as `user:X`)
+- `audio/` — music and sound effects
+- `AGENTS.md` — rules and pointers for AI agents working on this project

package/templates/playable-2d/files/design/recipe.md

@@ -1,83 +1,83 @@
-# Recipe: recipe-playable-ad
-
-## What this is
-
-The playable-ad shape: a portrait scene with a tap-to-start gate, a short piece
-of gameplay, and an end screen whose CTA button reports game end through the
-engine Playable SDK and logs the click. It opens no store page — the ad network
-picks that target at delivery time, so hook its SDK into `CtaButton.ctaClick()`
-when you package the ad. One scene, no menu — an ad has no menu.
-
-The gameplay itself is deliberately a placeholder (`hero-sprite` bobbing on a
-`core:Sine`) plus an auto-win timer. Replace both: keep the gate and the CTA,
-build the middle. If the brief needs real mechanics, start from `recipe-arena-2d`,
-`recipe-bouncer-2d` or `recipe-tapper-2d` and port this gate/CTA structure over.
-
-## Node map
-
-| id | what |
-| --- | --- |
-| `game-root` | scene root; hosts `GameFlow` (the phase driver: intro → playing → ended) |
-| `background` | full-screen `ColorRect2D` (palette background) |
-| `hero-sprite` | placeholder gameplay object, bobbing on a `core:Sine` |
-| `hud-label` | in-game text line |
-| `intro-overlay` → `intro-dim`, `intro-label` | the tap gate (`scenes/ui/intro.pix3scene`, instanced into main); the first tap hides it, starts the game, and unlocks browser audio |
-| `end-screen` → `end-dim`, `end-label`, `cta-button` | end screen (`scenes/ui/end-screen.pix3scene`, instanced into main), `initiallyVisible: false` |
-| `cta-button` | hosts `CtaButton` — `playable.gameEnd()` + a `[CtaButton] CTA clicked` log; the store call belongs to the ad network SDK, not to the template |
-
-`GameFlow.finish()` reveals the end screen; call it from your gameplay code for
-a real win/lose instead of the placeholder timer.
-
-## Placeholders
-
-| role | file | node |
-| --- | --- | --- |
-| hero | `sprites/pix3-logo.png` | `hero-sprite` |
-
-## Tunables
-
-```yaml
-tunables:
-  autoWinAfterSec: { node: game-root, component: "user:GameFlow", property: autoWinAfterSec, min: 0, max: 120, default: 15 }
-  introNode: { node: game-root, component: "user:GameFlow", property: introNode, default: intro-overlay }
-  endNode: { node: game-root, component: "user:GameFlow", property: endNode, default: end-screen }
-  skipIntro: { node: game-root, component: "user:GameFlow", property: skipIntro, default: false }
-  bgColor: { node: background, property: color, default: "#16213e" }
-```
-
-`component` present → `set_component_property`; absent → `set_property`.
-
-`skipIntro: true` starts the run already playing, with the tap gate hidden — a
-prototyping vent so iterating does not cost a tap per reload. Turn it back off
-before shipping: in an ad container that first tap is what unlocks browser audio.
-
-## Extension points
-
-- **Real gameplay.** Replace `hero-sprite` and set `autoWinAfterSec: 0`, then
-  call `finish()` on the `GameFlow` component from your own script when the
-  player wins or loses. Everything else (gate, end screen, CTA) stays.
-- **Fail state.** Add a `lose-label` inside `end-screen` and pick the text in
-  your `finish()` caller — a playable that can only be won reads as a demo.
-- **Second CTA.** Any `Button2D` with a `user:CtaButton` component works, so an
-  early "install now" banner is one node.
-- **Network requirements.** Keep everything self-contained: an ad bundle is a
-  single HTML file, so no external fetches, and prefer few, small textures.
-
-## Do not touch
-
-- The node ids above (rename `name`, never `id`).
-- `intro-overlay` must exist and be visible at start (`initiallyVisible: true` in
-  `scenes/ui/intro.pix3scene`): the first tap is what unlocks browser audio, so a
-  playable without a gate ships silent.
-- `end-screen` must keep `initiallyVisible: false` (in `scenes/ui/end-screen.pix3scene`).
-- The `visible: false` on both `instance:` nodes in `main.pix3scene` is an
-  editor-only hide so the scene opens on the game — keep it, and author
-  `initiallyVisible` in the overlay file, never as an instance override.
-- Do not import rapier — it would put a ~2 MB wasm payload in an ad bundle.
-
-## Verify
-
-1. `play_start` on `scenes/main.pix3scene`; `intro-overlay` is visible.
-2. `game_input` a tap → `intro-overlay` hides and `hero-sprite` starts bobbing.
-3. Wait `autoWinAfterSec` → `end-screen` becomes visible with `cta-button`.
-4. Press `cta-button` → the SDK reports game end and `[CtaButton] CTA clicked` appears in the console (nothing navigates away).
+# Recipe: recipe-playable-ad
+
+## What this is
+
+The playable-ad shape: a portrait scene with a tap-to-start gate, a short piece
+of gameplay, and an end screen whose CTA button reports game end through the
+engine Playable SDK and logs the click. It opens no store page — the ad network
+picks that target at delivery time, so hook its SDK into `CtaButton.ctaClick()`
+when you package the ad. One scene, no menu — an ad has no menu.
+
+The gameplay itself is deliberately a placeholder (`hero-sprite` bobbing on a
+`core:Sine`) plus an auto-win timer. Replace both: keep the gate and the CTA,
+build the middle. If the brief needs real mechanics, start from `recipe-arena-2d`,
+`recipe-bouncer-2d` or `recipe-tapper-2d` and port this gate/CTA structure over.
+
+## Node map
+
+| id | what |
+| --- | --- |
+| `game-root` | scene root; hosts `GameFlow` (the phase driver: intro → playing → ended) |
+| `background` | full-screen `ColorRect2D` (palette background) |
+| `hero-sprite` | placeholder gameplay object, bobbing on a `core:Sine` |
+| `hud-label` | in-game text line |
+| `intro-overlay` → `intro-dim`, `intro-label` | the tap gate (`scenes/ui/intro.pix3scene`, instanced into main); the first tap hides it, starts the game, and unlocks browser audio |
+| `end-screen` → `end-dim`, `end-label`, `cta-button` | end screen (`scenes/ui/end-screen.pix3scene`, instanced into main), `initiallyVisible: false` |
+| `cta-button` | hosts `CtaButton` — `playable.gameEnd()` + a `[CtaButton] CTA clicked` log; the store call belongs to the ad network SDK, not to the template |
+
+`GameFlow.finish()` reveals the end screen; call it from your gameplay code for
+a real win/lose instead of the placeholder timer.
+
+## Placeholders
+
+| role | file | node |
+| --- | --- | --- |
+| hero | `sprites/pix3-logo.png` | `hero-sprite` |
+
+## Tunables
+
+```yaml
+tunables:
+  autoWinAfterSec: { node: game-root, component: "user:GameFlow", property: autoWinAfterSec, min: 0, max: 120, default: 15 }
+  introNode: { node: game-root, component: "user:GameFlow", property: introNode, default: intro-overlay }
+  endNode: { node: game-root, component: "user:GameFlow", property: endNode, default: end-screen }
+  skipIntro: { node: game-root, component: "user:GameFlow", property: skipIntro, default: false }
+  bgColor: { node: background, property: color, default: "#16213e" }
+```
+
+`component` present → `set_component_property`; absent → `set_property`.
+
+`skipIntro: true` starts the run already playing, with the tap gate hidden — a
+prototyping vent so iterating does not cost a tap per reload. Turn it back off
+before shipping: in an ad container that first tap is what unlocks browser audio.
+
+## Extension points
+
+- **Real gameplay.** Replace `hero-sprite` and set `autoWinAfterSec: 0`, then
+  call `finish()` on the `GameFlow` component from your own script when the
+  player wins or loses. Everything else (gate, end screen, CTA) stays.
+- **Fail state.** Add a `lose-label` inside `end-screen` and pick the text in
+  your `finish()` caller — a playable that can only be won reads as a demo.
+- **Second CTA.** Any `Button2D` with a `user:CtaButton` component works, so an
+  early "install now" banner is one node.
+- **Network requirements.** Keep everything self-contained: an ad bundle is a
+  single HTML file, so no external fetches, and prefer few, small textures.
+
+## Do not touch
+
+- The node ids above (rename `name`, never `id`).
+- `intro-overlay` must exist and be visible at start (`initiallyVisible: true` in
+  `scenes/ui/intro.pix3scene`): the first tap is what unlocks browser audio, so a
+  playable without a gate ships silent.
+- `end-screen` must keep `initiallyVisible: false` (in `scenes/ui/end-screen.pix3scene`).
+- The `visible: false` on both `instance:` nodes in `main.pix3scene` is an
+  editor-only hide so the scene opens on the game — keep it, and author
+  `initiallyVisible` in the overlay file, never as an instance override.
+- Do not import rapier — it would put a ~2 MB wasm payload in an ad bundle.
+
+## Verify
+
+1. `play_start` on `scenes/main.pix3scene`; `intro-overlay` is visible.
+2. `game_input` a tap → `intro-overlay` hides and `hero-sprite` starts bobbing.
+3. Wait `autoWinAfterSec` → `end-screen` becomes visible with `cta-button`.
+4. Press `cta-button` → the SDK reports game end and `[CtaButton] CTA clicked` appears in the console (nothing navigates away).