@pix3/cli 1.6.3 → 2.0.0-alpha.0

package/kit/files/AGENTS.md

@@ -1,25 +1,21 @@
-<!-- Pix3 agent kit 1.6.3 — written by `pix3 kit`. You may edit it: `pix3 kit --update` never overwrites a kit file you changed. -->
+<!-- Pix3 agent kit 2.0.0-alpha.0 — written by `pix3 kit`. You may edit it: `pix3 kit --update` never overwrites a kit file you changed. -->
 # AGENTS.md — Pix3 game project
 
 This folder is a **Pix3 game**: a 2D/3D browser game. You edit it by writing files. A human
 has the same folder open in the Pix3 editor, moves things with the mouse and presses Play;
 the editor saves their edits to the same files. The files are the whole contract.
 
-If it started from a **recipe** (`design/recipe.md` exists), it is a game that already plays.
-Change it; do not rebuild it.
+A project made by `npm create pix3` starts **empty**: one entry scene (`scenes/main.pix3scene`,
+a 2D root and background, or a 3D camera and lights) and no scripts. The game is yours to build.
 
 ## Read first
 
-1. `design/recipe.md` (if present) — the map: stable node ids, tunables with ranges, extension
-   points, what must not be touched. It speaks in the in-editor agent's tool names; translate
-   them with the table in `.claude/skills/pix3-scene-format/SKILL.md` ("Recipe tool names").
-2. `README.md` — file layout of this project.
-3. The one scene or script you are about to change. Nothing else. Do not survey the repo.
+1. `README.md` — file layout of this project.
+2. The one scene or script you are about to change. Nothing else. Do not survey the repo.
    To find it, and to find your way inside it, use `pix3 tree` (every scene and prefab with
    node counts, types and components) and `pix3 tree <scene>` (one line per node: id, type,
-   position, size, layout, components, prefab instances; `--types Label2D,Button2D`,
-   `--depth 2`, `--props`) — not a read of whole scene files. Read the file itself right
-   before you edit it (rule 2).
+   position, size, layout, components, prefab instances) — not a read of whole scene files.
+   Read the file itself right before you edit it (rule 2).
 
 ## Layout
 
@@ -34,9 +30,15 @@ The layout is **whatever this project has** — do not assume folders. Three rul
   `pix3 check` scan). `export class X extends Script` → `type: user:X`.
 
 `pix3project.yaml` is the manifest (do not edit unless asked); `.pix3/` is editor + CLI
-bookkeeping (recovery journal, merge log, script types) — never edit it.
+bookkeeping (`dev.json` of the running dev server, the version journal, script types) — read
+`dev.json`, never edit anything there.
 
-Example — the layout a **recipe** project (`pix3 new`) ships; other projects differ:
+**The editor never creates, renames, moves or deletes a file, never edits `pix3project.yaml` and
+never builds — you do.** New scene, rename/move/delete with every reference, a branch turned into
+a prefab, a new flipbook, a locale added or removed, project settings, build options:
+`.claude/skills/pix3-scene-format/project-files.md`.
+
+Example — the layout `npm create pix3` sets up (`pix3 new`); other projects differ:
 
 | Path | What |
 | --- | --- |
@@ -45,7 +47,8 @@ Example — the layout a **recipe** project (`pix3 new`) ships; other projects d
 | `scenes/prefabs/*.pix3scene` | Prefabs: a scene file with exactly ONE root node (a top-level `prefabs/` works too) |
 | `scripts/*.ts` | Script components |
 | `sprites/`, `audio/`, `fonts/`, `models/` … | Assets, referenced as `res://sprites/x.png` |
-| `design/` | Recipe contract, GDD, tests. `design/tests/` is written by the editor's harness |
+| `design/` | Design notes, GDD, references |
+| `src/main.ts`, `index.html`, `vite.config.ts` | The Vite entry: `startGame('#app')` boots the entry scene; `pix3()` serves the editor at `/__pix3/` |
 
 ## The five rules
 
@@ -53,35 +56,25 @@ Example — the layout a **recipe** project (`pix3 new`) ships; other projects d
    smallest form that plays, before asking anything. Choose small things yourself (a shade, a
    speed, a count) and say so in one line. At most ONE question per turn, and only about a
    fork that changes structure ("win by score or by time?"). Never open with a question.
-2. **Re-read a scene before you edit it.** The human may have changed it in the editor a
-   minute ago. Edit the lines you mean to change (search/replace), never regenerate a whole
-   scene from memory. After writing, if `pix3 check` lists **merge-log** entries where the
-   editor KEPT the human's value instead of yours, re-read the file with `pix3 read <file>`
-   (that is your read confirmation); if your value is still intended, write it again — or ask
-   the human. Without that re-read the editor keeps restoring the human's value on every
-   write you make, even if you write the same number.
+2. **Sync, then re-read a scene before you edit it.** The human may have moved things in the
+   editor a minute ago; a successful `pix3_sync` puts their unsaved edits on disk. Edit the lines
+   you mean to change (search/replace), never regenerate a whole scene from memory. After
+   writing, `pix3_sync` again with `expect` = the sha256 of every file you wrote
+   (`.claude/skills/pix3-editor/SKILL.md`).
 3. **Leave layout, colours and fine-tuning to the human.** If asked "a bit more to the left",
    do it, then offer: "you can drag it in the editor — it saves on its own".
 4. **Run `pix3 check` after every batch of edits** and fix every error before you say "done".
    It checks YAML, node types, properties, `res://` paths, prefabs, components, and
-   type-checks your scripts (tsc). With the live channel connected (MCP, below), then run the
-   game with `game_run` (or `play_restart`), **passing `expect`** — the sha256 of every file you
-   wrote, as `pix3 check --json` prints them under `files`. An answer with
-   `disk_differs_from_agent`, or a non-empty `changedDuringRun`, is not green.
-   **No editor connected?** `pix3 check`, then `pix3 smoke <the scene you changed>` — the
-   game is `pix3 smoke scenes/main.pix3scene`; the menu never presses PLAY headless, so a
-   smoke of the menu says nothing about the game. It runs that scene in Node for 2 s
-   (`--frames N` for more) and exits 1 on any script throw, `console.error` or unhandled
-   rejection, naming script, frame and source line. With no scene it runs several, a line
-   each: the scenes your uncommitted changes reach (git), else every top-level scene, game
-   first. Green means nothing threw; it does not mean it plays (nothing was tapped or drawn)
-   — so then tell the human what to press and what they should see.
-5. **Art: placeholder → SVG → `generate_asset`, never emoji.** Placeholder = `ColorRect2D`, or
+   type-checks your scripts. Then run the game: with the editor open, `pix3_sync` with `expect`
+   and `pix3_play` / `pix3_game_run` / `pix3_errors` / a screenshot (`pix3-editor`); without it,
+   `pix3 smoke <the scene you changed>` — the game, not the menu, which never presses PLAY
+   headless (`pix3-verify`). A sync that is not `ok` is not green, and a green smoke means
+   nothing threw, not that it plays — so tell the human what to press and what they should see.
+5. **Art: placeholder → SVG → a generated image, never emoji.** Placeholder = `ColorRect2D`, or
    a near-white PNG in `sprites/` tinted with a `core:tint` effect. Better art = an SVG you
-   write into `sprites/` — it works on a `Sprite2D` when the root has `xmlns` plus px
-   `width`/`height`; `pix3 validate` checks it (`E_SVG_*`); template in `pix3-nodes` — or
-   `generate_asset` through the live channel. A label/text that is only emoji is
-   refused — emoji are not art. List every placeholder you leave.
+   write into `sprites/` (`pix3-nodes` → "An SVG you write as a sprite") — or an image the
+   human generates. A label/text that is only emoji is refused — emoji are not art. List every
+   placeholder you leave.
 
 ## YAML essentials (`.pix3scene`) — details in `pix3-scene-format`
 
@@ -108,16 +101,15 @@ root:
         properties: { visible: false }
 ```
 
-- The sample assumes a 1080×1920 portrait 2D root; yours may not have one. Read
-  `viewportBaseSize` and `projectType` in `pix3project.yaml` first; a `3d` project may have loose
-  top-level 2D nodes (HUD) with no 2D root at all. Place new HUD relative to the HUD nodes that
-  already exist (same parent, same anchoring), not to an assumed screen size.
+- The sample assumes a 1080×1920 portrait 2D root; yours may not have one — read
+  `viewportBaseSize` and `projectType` in `pix3project.yaml`, and place new HUD relative to the
+  HUD that exists (`pix3-scene-format` → "2D transform").
 - 2D space: design pixels, origin at the screen centre, **X right, Y up**. `position` is the
   node's centre. Tree order is paint order: later/deeper draws on top.
 - **Quote every colour**: `color: "#141a2e"`. Unquoted, `#` starts a YAML comment.
 - Textures: `texture: { type: 'texture', url: 'res://sprites/ph-target.png' }`.
 - `visible: false` on an overlay instance hides it **in the editor only**; play mode reads
-  `initiallyVisible` on the overlay file's root. Keep both as the recipe has them.
+  `initiallyVisible` on the overlay file's root. Set both.
 - The loader is forgiving — unknown types, unknown keys and wrong value types load silently
   as nothing. That is why rule 4 exists.
 
@@ -139,65 +131,65 @@ export class Combo extends Script {
 }
 ```
 
-- One mechanic = one new script of 70–140 lines. Extend a recipe's scripts only where
-  `design/recipe.md` names an extension point; do not restructure them.
-- Talk between scripts the way the project already does. Recipes use signals on nodes:
-  `node.emit('touch-scored', 1)` / `node.connect('touch-scored', this, fn)` — never rename the
-  recipe's signals or node ids. An existing game may use its own event bus or store instead
-  (next section).
+- One mechanic = one new script of 70–140 lines.
+- Talk between scripts the way the project already does. In a new project use signals on nodes:
+  `node.emit('touch-scored', 1)` / `node.connect('touch-scored', this, fn)`; once named, never
+  rename a signal or a node id other scripts use. An existing game may use its own event bus or
+  store instead (next section).
 - Transforms are mutated, never assigned: `node.position.set(x, y, 0)`, `node.rotation.z = rad`.
 - Types come from `@pix3/runtime`: `pix3 check` type-checks against the bundled declarations in
   `.pix3/types/` (or against your own `node_modules` when the project has its own `tsconfig.json`).
 
-## Hosting an existing (non-recipe) game
+## Hosting an existing game
 
-A game that was not made from a recipe has its own architecture; plug into it, do not add a
-second one.
+A game that was not made from `npm create pix3` has its own architecture; plug into it, do not
+add a second one — its event bus or store, its own shake/sound/tween helpers, and cleanup by
+hand of everything that is not a node signal (`pix3-scripts` → "Hosting an existing game").
 
-- **Find its event bus / state store** before writing a script:
-  `grep -rn "CustomEvent\|dispatchEvent\|addEventListener\|subscribe(\|EventTarget\|emit(" src scripts`.
-  Window `CustomEvent`s, an `EventTarget` singleton, or a store with `subscribe()` are all
-  normal; node signals are only one option. Listen to what the game already emits.
-- **Clean up by hand.** `Script.onDetach` auto-disconnects only **node signals** whose target is
-  the script (on its own node or any other). Window listeners, store subscriptions and timers
-  must be removed in `onDetach` (keep the handler in a field; call the
-  unsubscribe the store returned) — otherwise every play/stop in the editor leaves one more
-  live listener behind.
 - **Two instruction files.** The project's own `AGENTS.md` wins on **process** (planning first,
   where config and tests go, commit rules); this kit wins on **Pix3 facts** (the YAML format,
   the runtime API, `pix3 check`).
 - The project's own `package.json` means `npm install` before `pix3 check` can type-check.
-- **Use the game's own feedback mechanisms.** If its camera controller writes the camera's
-  position every frame, an engine `scene.juice.shake('camera')` / `core:Shake` on that 3D camera
-  (or on any node the game positions itself) is overwritten every frame and never shows — call
-  the game's own shake (grep `shake`) instead. The same holds for its own sound/tween helpers.
-
-## The CLI and the live channel
-
-- `pix3 check [--json]` — after every batch (rule 4). `--json` prints `files` (`{ file, sha256 }`,
-  sha256 of the raw bytes), `diagnostics`, `typecheck`, `mergeLog`, `kit`.
-- `pix3 read <file>` — print a file and confirm to the editor you read exactly these bytes.
-- `pix3 validate [paths…]` — scenes only, no type-check.
-- `pix3 smoke [scene] [--frames N] [--json]` — run a scene headless (no browser) and report
-  script throws with frame and stack, `console.error`, missing `res://` files; exit 1 on errors.
-  Name the game scene (`pix3 smoke scenes/main.pix3scene`); no scene = the scenes git changes
-  reach, else every top-level scene (`--all` forces that).
+
+## The CLI and the editor bridge
+
+A project made by `npm create pix3` has them as npm scripts: `npm run dev` (Vite: the game at
+`/`, the editor at `/__pix3/`, on the port Vite got — 5173 only if it was free; read
+`.pix3/dev.json`), `npm run editor` (`pix3 editor`), `npm run build` (`dist/`),
+`npm run preview` (serve the build), `npm run check` (`pix3 check`), `npm run smoke`
+(`pix3 smoke`; pass the scene after `--`). Elsewhere call `npx pix3 …` or read `package.json`.
+
+- `pix3 check [--json]` — after every batch (rule 4); `--json` prints `files` (`{ file, sha256 }`)
+  for `pix3_sync`'s `expect`. It flushes the open editor's unsaved edits first (`--no-sync`
+  skips that). `pix3 validate [paths…]` — scenes only, no type-check.
+- `pix3 smoke [scene] [--frames N] [--json]` — run a scene headless (no browser); exit 1 on a
+  script throw, `console.error` or unhandled rejection. Name the game scene.
 - `pix3 tree [scene] [--types A,B] [--depth N] [--props] [--json]` — scene outline, one line
   per node; no scene = project overview.
-- **Live channel (optional).** When the human runs `pix3 serve` in this folder and connects the
-  editor to it (File → Connect to Workspace…), the MCP server in `.mcp.json`
-  (`pix3 mcp --workspace`) gives you 14 tools: running and observing the game, screenshots,
-  asset/sfx generation. There is no scene-editing tool — you still edit files. Details and the
-  answer fields: `.claude/skills/pix3-verify/SKILL.md` ("Live channel").
+- `pix3 editor` — find (or start) the dev server and open the editor in a Chrome reachable only
+  through its token proxy; `pix3 agent-setup [claude|codex] [--repair]` — write the project's
+  MCP config for `chrome-devtools-mcp`, once (never commit it).
+- `pix3 gap "<what was missing>" --kind capability|tool|node|doc|other [--detail "…"] [--context "<file or task>"]`
+  — when you had to **work around** something Pix3 does not have (an engine capability, a bridge
+  tool, a node type, a doc that was missing or wrong), record it once, after the workaround: one
+  line in `.pix3/gaps.jsonl` (local, read by the Pix3 team). Sparingly — not for your own
+  mistakes, a question to the human, or a feature the game itself should implement.
+- **The editor bridge.** With the editor tab open, the `pix3-browser` MCP server (Chrome
+  DevTools) reaches it: `list_pages` → `select_page` → `list_3p_developer_tools` → the
+  `pix3_*` tools — sync the editor with the disk, play, step the game with predicates, read the
+  scene and the errors, prepare a screenshot. There is no scene-editing tool — you still edit
+  files. No `pix3-browser` server → `npx pix3 agent-setup`, then a new thread. The loop, the
+  not-ok answers and the inline fallback: `.claude/skills/pix3-editor/SKILL.md`.
 
 ## Skills (read the one you need, when you need it)
 
-- `.claude/skills/pix3-scene-format/SKILL.md` — full YAML format, prefabs, overlays, recipe tool table
+- `.claude/skills/pix3-scene-format/SKILL.md` — full YAML format, prefabs, overlays; `.pix3anim` flipbooks and `pix3 character-compile` in `pix3anim.md` beside it; file and project operations the editor does not do in `project-files.md` beside it
 - `.claude/skills/pix3-nodes/SKILL.md` — 2D node properties (Group2D, ColorRect2D, Sprite2D, Label2D, Button2D, Bar2D, CanvasLayer2D, PostProcess); every node in `reference.md` beside it
 - `.claude/skills/pix3-scripts/SKILL.md` — Script API: lifecycle, schema, scene/input/juice/tween/audio/physics, `core:` components, traps
-- `.claude/skills/pix3-verify/SKILL.md` — `pix3 check` / `validate` / `read`, merge-log, the live channel (`game_run` + `expect`)
+- `.claude/skills/pix3-editor/SKILL.md` — the editor bridge: find the tab, `pix3_sync` with `expect`, play ownership, `pix3_game_run`, screenshots, inline fallback
+- `.claude/skills/pix3-verify/SKILL.md` — `pix3 check` / `validate` / `smoke`, the diagnostic codes, how to report what was verified
 
 ## Finish every turn with
 
-What changed (files), what `pix3 check` said, whether you ran the game (and what `game_run`
+What changed (files), what `pix3 check` said, whether you ran the game (and what `pix3_game_run`
 answered) or what the human should press and see, placeholders left, and 2–3 concrete next steps.

package/kit/files/design/tests/bots/pix3-test-bot.d.ts

@@ -0,0 +1,89 @@
+// Pix3 agent kit 2.0.0-alpha.0 — `pix3 kit --update` rewrites this file; do not edit.
+//
+// Types for the test policies in this folder (global: no import needed). A policy is
+// one file exporting an object with a `tick(bot)`; the harness runs it once per logic
+// tick while the game plays, through `pix3_game_run {bot: {name: '<file name without
+// .ts>'}, …}`. Write it as
+//
+//   export default {
+//     name: 'dodge',
+//     tick(bot) { … },
+//   } satisfies BotPolicy;
+//
+// so `bot` is a Pix3TestBot and `pix3 check` type-checks the policy.
+//
+// The timing contract, which decides whether a policy works: `tick` runs AFTER the
+// game's tick, and every actuator lands on the NEXT tick. Observe frame N, act for
+// frame N+1 — the same one-frame lag a human player has.
+
+declare interface BotPoint {
+  x: number;
+  y: number;
+  z?: number;
+}
+
+/** What a policy sees of one live node. */
+declare interface BotNodeView {
+  nodeId: string;
+  name: string;
+  type: string;
+  /** The node's own flag. `false` means it is not on screen and cannot be tapped. */
+  visible: boolean;
+  position: { x: number; y: number; z: number };
+  worldPosition: { x: number; y: number; z: number };
+  /** The text the node renders, for nodes that render one. */
+  text?: string;
+}
+
+declare interface BotHit {
+  node: BotNodeView;
+  distance: number;
+  point: { x: number; y: number; z: number };
+}
+
+declare interface Pix3TestBot {
+  /** Ticks this policy has been ticked for. 1 on the first tick. */
+  readonly frame: number;
+
+  // -- sensors ---------------------------------------------------------------
+
+  /** Live nodes answering a name, an id, or a type ('Sprite2D'). */
+  nodes(query: string): BotNodeView[];
+  /** Nearest live node of `type` to `from` (default: the world origin). */
+  nearest(type: string, from?: BotPoint): BotHit | null;
+  /** First live node struck by a ray. `dir` need not be normalised. */
+  raycast(from: BotPoint, dir: BotPoint): BotHit | null;
+  /** The game's own registerGameDebug() snapshot, or null when it registered none. */
+  gameState(): unknown;
+
+  // -- actuators -------------------------------------------------------------
+
+  /** Hold a key ('Key_ArrowLeft' or 'ArrowLeft') or a named button ('Action_Primary'). */
+  press(action: string, frames?: number): void;
+  /** Let go of something press() is holding. */
+  release(action: string): void;
+  /** Tap a control by node name/id: down now, up a few ticks later. */
+  tap(target: string): void;
+  /** Steer an input axis to -1..1. On physical-input this deflects the live joystick. */
+  axis(name: string, value: number): void;
+  /** Point the pointer at a world position (aim, hover, click-to-move). */
+  moveTo(point: BotPoint): void;
+
+  // -- protocol --------------------------------------------------------------
+
+  /** One line in the run report — how the policy explains its own reasoning. */
+  log(event: string): void;
+  /** End the run with the policy's verdict and the reason, in words. First call wins. */
+  done(pass: boolean, reason: string): void;
+}
+
+declare interface BotPolicy {
+  /** Optional label for the report; the file name is used when absent. */
+  name?: string;
+  /** Runs once before the first tick. */
+  start?(bot: Pix3TestBot): void;
+  /** Runs once per logic tick until done() or the budget ends. */
+  tick(bot: Pix3TestBot): void;
+  /** Runs once after the last tick, whatever ended the run. */
+  end?(bot: Pix3TestBot): void;
+}

package/kit/kit.json

@@ -1,24 +1,27 @@
 {
   "format": 1,
-  "version": "1.6.3",
-  "inputsStamp": "8fcca842690fa33c8ede9cb18b2ea5b950b8cceea0852c114c6431bf6bc321fd",
+  "version": "2.0.0-alpha.0",
+  "inputsStamp": "2191b8f1a8e23d36c45892f3616f747dd3f429eeb427c447163b16e4586e26dc",
   "files": [
+    ".claude/skills/pix3-editor/SKILL.md",
     ".claude/skills/pix3-nodes/SKILL.md",
     ".claude/skills/pix3-nodes/reference.md",
     ".claude/skills/pix3-scene-format/SKILL.md",
+    ".claude/skills/pix3-scene-format/pix3anim.md",
+    ".claude/skills/pix3-scene-format/project-files.md",
     ".claude/skills/pix3-scene-format/reference.md",
     ".claude/skills/pix3-scripts/SKILL.md",
     ".claude/skills/pix3-scripts/reference.md",
     ".claude/skills/pix3-verify/SKILL.md",
     ".claude/skills/pix3-verify/reference.md",
     "AGENTS.md",
-    "CLAUDE.md"
+    "CLAUDE.md",
+    "design/tests/bots/pix3-test-bot.d.ts"
   ],
   "sources": [
     "docs/node-types-reference.md",
     "docs/nodes-and-systems.md",
     "docs/pix3-specification.md",
-    "packages/pix3-cli/README.md",
-    "src/services/agent/agent-skills/engine-api-map.md"
+    "packages/cli/kit-includes/engine-api-map.md"
   ]
 }

package/package.json

@@ -1,54 +1,62 @@
-{
-  "name": "@pix3/cli",
-  "version": "1.6.3",
-  "description": "Pix3 command line: create a project from a recipe, and link your own coding agent (Claude Code, Codex, ...) to an open Pix3 editor window over a loopback MCP channel.",
-  "type": "module",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/pix3dev/pix3.git",
-    "directory": "packages/pix3-cli"
-  },
-  "bin": {
-    "pix3": "dist/index.js"
-  },
-  "main": "dist/index.js",
-  "files": [
-    "dist",
-    "templates",
-    "kit",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=24.15.0 <25"
-  },
-  "scripts": {
-    "start": "node src/index.ts",
-    "build": "tsc -p tsconfig.build.json && node scripts/build-bin.mjs && node scripts/build-validate.mjs && node scripts/build-smoke.mjs",
-    "copy-templates": "node scripts/copy-templates.mjs",
-    "prepack": "npm run copy-templates && npm run build && npm run build-runtime-types && npm run build-kit",
-    "postpack": "node scripts/copy-templates.mjs --clean",
-    "type-check": "tsc --noEmit && tsc --noEmit -p tsconfig.build.json",
-    "build-kit": "node scripts/build-kit.mjs",
-    "build-runtime-types": "node scripts/build-runtime-types.mjs"
-  },
-  "keywords": [
-    "pix3",
-    "cli",
-    "mcp",
-    "game-engine",
-    "agent"
-  ],
-  "license": "Apache-2.0",
-  "optionalDependencies": {
-    "esbuild": "^0.27.3"
-  },
-  "devDependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "@types/node": "^24.5.2",
-    "@types/ws": "^8.18.1",
-    "typescript": "~5.8.3",
-    "ws": "^8.18.0",
-    "yaml": "^2.6.0"
-  }
-}
+{
+  "name": "@pix3/cli",
+  "version": "2.0.0-alpha.0",
+  "description": "Pix3 command line: create a project, check and smoke-test it, open the editor in Chrome for your coding agent (Claude Code, Codex, ...) and configure chrome-devtools-mcp for it.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pix3dev/pix3-core.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/pix3dev/pix3-core/tree/main/packages/cli#readme",
+  "bugs": {
+    "url": "https://github.com/pix3dev/pix3-core/issues"
+  },
+  "bin": {
+    "pix3": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "templates",
+    "kit",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=24.15.0 <25"
+  },
+  "scripts": {
+    "start": "node src/index.ts",
+    "build": "tsc -p tsconfig.build.json && node scripts/build-bin.mjs && node scripts/build-validate.mjs && node scripts/build-smoke.mjs",
+    "copy-templates": "node scripts/copy-templates.mjs",
+    "prepack": "npm run copy-templates && npm run build && npm run build-runtime-types && npm run build-kit",
+    "postpack": "node scripts/copy-templates.mjs --clean",
+    "type-check": "tsc --noEmit && tsc --noEmit -p tsconfig.build.json",
+    "build-kit": "node scripts/build-kit.mjs",
+    "build-runtime-types": "node scripts/build-runtime-types.mjs"
+  },
+  "keywords": [
+    "pix3",
+    "cli",
+    "mcp",
+    "game-engine",
+    "agent"
+  ],
+  "license": "Apache-2.0",
+  "optionalDependencies": {
+    "esbuild": "^0.27.3"
+  },
+  "devDependencies": {
+    "@pix3/runtime": "2.0.0-alpha.0",
+    "@types/node": "^24.5.2",
+    "@types/ws": "^8.18.1",
+    "typescript": "~5.8.3",
+    "ws": "^8.18.0",
+    "yaml": "^2.6.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  }
+}

package/templates/2d/files/scenes/main.pix3scene

@@ -0,0 +1,31 @@
+# Pix3 Scene File (YAML). The entry scene of an empty 2D project: a root that stretches over the
+# viewport (pix3project.yaml → viewportBaseSize) and a background. Add nodes under game-root.
+version: 1.0.0
+metadata:
+  description: Entry scene
+root:
+  - id: game-root
+    type: Group2D
+    name: Game Root
+    properties:
+      width: 1920
+      height: 1080
+      layout:
+        enabled: true
+        horizontalAlign: stretch
+        verticalAlign: stretch
+    children:
+      - id: background
+        type: ColorRect2D
+        name: Background
+        properties:
+          color: "#1a1a2e"
+          layout:                  # stretched over the root: the margins size it, no width/height
+            enabled: true
+            horizontalAlign: stretch
+            verticalAlign: stretch
+            left: 0
+            right: 0
+            top: 0
+            bottom: 0
+        children: []

package/templates/2d/template.yaml

@@ -0,0 +1,11 @@
+id: 2d
+title: Empty 2D
+description: An empty 2D project — one scene with a stretched 2D root and a background, nothing that plays.
+# Shared project files (package.json, vite.config.ts, index.html, src/main.ts, tsconfig.json …)
+# come from templates/base; this layer adds the 2D scene.
+extends: base
+projectType: 2d
+targetPlatform: universal
+viewport: { width: 1920, height: 1080 }
+entryScene: scenes/main.pix3scene
+order: 10

package/templates/3d/files/scenes/main.pix3scene

@@ -0,0 +1,50 @@
+# Pix3 Scene File (YAML). The entry scene of an empty 3D project: a camera, a key light and an
+# ambient fill. Add meshes under game-root; 2D HUD nodes go beside it as top-level 2D nodes.
+version: 1.0.0
+metadata:
+  description: Entry scene
+root:
+  - id: game-root
+    type: Node3D
+    name: Game Root
+    properties:
+      transform:
+        position: [0, 0, 0]
+        rotationEuler: [0, 0, 0]
+        scale: [1, 1, 1]
+    children:
+      - id: main-camera
+        type: Camera3D
+        name: Main Camera
+        properties:
+          projection: perspective
+          fov: 60
+          near: 0.1
+          far: 1000
+          transform:
+            position: [0, 2, 6]
+            rotationEuler: [-10, 0, 0]
+            scale: [1, 1, 1]
+        children: []
+      - id: key-light
+        type: DirectionalLightNode
+        name: Key Light
+        properties:
+          intensity: 1.2
+          color: "#ffffff"
+          transform:
+            position: [5, 8, 3]
+            rotationEuler: [-45, 35, 0]
+            scale: [1, 1, 1]
+        children: []
+      - id: ambient-light
+        type: AmbientLightNode
+        name: Ambient Light
+        properties:
+          intensity: 0.5
+          color: "#ffffff"
+          transform:
+            position: [0, 0, 0]
+            rotationEuler: [0, 0, 0]
+            scale: [1, 1, 1]
+        children: []

package/templates/3d/template.yaml

@@ -0,0 +1,11 @@
+id: 3d
+title: Empty 3D
+description: An empty 3D project — one scene with a camera and lights, nothing that plays.
+# Shared project files (package.json, vite.config.ts, index.html, src/main.ts, tsconfig.json …)
+# come from templates/base; this layer adds the 3D scene.
+extends: base
+projectType: 3d
+targetPlatform: universal
+viewport: { width: 1920, height: 1080 }
+entryScene: scenes/main.pix3scene
+order: 20