lecodes-sdk 0.20.2 → 1.1.0

package/package.json

@@ -33,7 +33,7 @@
     "typescript": "~5.8.3",
     "gl-matrix": "^3.4.4"
   },
-  "version": "0.20.2",
+  "version": "1.1.0",
   "files": [
     "src",
     "dist",

package/prompts/README.md

@@ -1,142 +1,142 @@
-# Codegen prompts
-
-> **Scope: the le.codes PLATFORM assistant only.** These prompts are bundled into `dist/` and served
-> by claude-proxy to the in-editor chat. They are NOT used by local development — Claude Code and
-> `lecodes-cli` never read them; those get the SDK surface from `.lecodes/types` (the d.ts bundle),
-> the generated project `CLAUDE.md` (`lecodes-cli/src/commands/projectTemplates.ts`) and `sdk/docs`.
-> A change meant for local development belongs there, not here.
-
-The system prompt(s) sent to Claude for LeCodes code generation, split into composable modules so
-a request only pays for the API areas it can actually use. Facts come from `../docs/` (the source
-of truth) — when the SDK changes, update docs first, then mirror the change here.
-
-**Consumers:**
-- `claude-proxy/prompts/*.md` — deployed copies of `dist/` + `router.md` (see its README); the
-  proxy injects them per the `x-lecodes-bundle` header (`claude-proxy/src/proxy/bundles.ts`). An
-  unknown/missing header is a **400** (no silent fallback), and the proxy's `/health` exposes a
-  sha256-12 per bundle — `bun run check:prompts` (repo root) compares them against `dist/` to
-  catch deploy drift (`--dir <proxy>/prompts` checks a local checkout instead).
-- `packages/frontend/.../chat/engine/bundleSelect.ts` — a thin adapter over `select.ts` (imported
-  as `sdk/prompts/select`); the selection logic itself is not duplicated anywhere.
-
-## Layout
-
-```
-core.md            shared foundation: response format, entry-point rule, runtime, math, tweens
-index.md           one-line map of EVERY global — always included (anti-hallucination anchor)
-canvas.md          Canvas drawing surface — engine-independent, in every bundle (each engine
-                   module documents its own hookup: Sprite texture / UIImage src / Texture)
-ui.md              UI module (screens, router, styling, widgets, lists)
-2d.md              2D engine module (sprites, tilemaps, Box2D physics, aspects, Canvas)
-3d.md              SHARED 3D content (nodes, meshes, models, materials, physics, particles)
-3d-scene.md        non-AR scenes: Scene construction, camera control, CharacterController, example
-3d-scene-files.md  declarative .scene.ts files (defineScene/use/ref/make, SceneHandle, HUD-over-scene)
-                   — the visual scene editor's format; non-AR only (camera nodes, skybox env)
-ar.md              AR scenes: ARScene, anchors, placement controls, example — never with 3d-scene.md
-core-design.md     design mode's core: directives/context/reports, no runtime APIs (no timers/network)
-ui-design.md       design mode's UI: curated static-mockup subset of ui.md (KEEP IN SYNC with it)
-design.md          design mode: canvas conventions — kit-first, states, design_map tool, tab bar
-concept.md         concept mode: product-shaping conversation, writes ONLY design/spec.md
-compose.ts         builds dist/<bundle>.md from the modules
-select.ts          deterministic bundle detection from project code
-router-prompt.md   fallback classifier prompt (empty projects only)
-namer-prompt.md    project name + icon-emoji generator (first request of a new project)
-intake-prompt.md   new-project intake: clarifying questions + confirmable brief (two Haiku turns)
-```
-
-## Bundles (`bun run prompts/compose.ts` → `dist/`)
-
-| Bundle | Modules | For |
-|---|---|---|
-| `ui-app` | core + index + canvas + ui | apps: screens, forms, lists, chat, commerce |
-| `2d-game` | core + index + canvas + 2d + ui | flat games, drawing toys |
-| `3d-app` | core + index + canvas + 3d + 3d-scene + 3d-scene-files + ui | 3D games/viewers, scene-editor projects |
-| `ar-app` | core + index + canvas + 3d + ar + ui | AR experiences |
-| `design` | core-design + ui-design + design | design mode: the design/ prototyping canvas |
-| `concept` | concept | concept mode: shape the idea, maintain design/spec.md (~0.8k tokens) |
-
-Fixed bundles (not per-request assembly) are deliberate: **each bundle is a stable prompt prefix**,
-so Anthropic prompt caching hits on every generation after the first (~10× cheaper input, lower
-latency). Per-request cherry-picking would produce near-unique prefixes and always pay full price.
-Game bundles include the full UI module because games need HUDs/menus; the ui-app bundle omits the
-engines entirely.
-
-## Selecting the bundle
-
-`design` and `concept` are different from the engine bundles: they are selected EXPLICITLY by the
-client from the editor's mode switcher (Concept / Design / Build — `x-lecodes-bundle: design` or
-`concept`) — never routed, detected from code, or reachable via the `<bundle>` escalation. The
-engine ladder below applies to Build mode only. Concept turns also carry no code context (design
-excerpts + file names only) and the client enforces each mode's write boundary (concept:
-design/spec.md only; design: design/ only). Any bundle may end a reply with `<mode>x</mode>` — the
-client strips it and renders a "Switch to …" button; the mode never switches itself.
-
-For the engine bundles — three signals, in this order:
-
-**1. Project code — `select.ts` (primary, deterministic).**
-`detectBundle(files)` scans the project's `.ts` sources for engine globals (comments and string
-literals stripped) and returns the bundle. This is language-independent — it doesn't matter what
-language the user writes in, because it never reads the user's words at all. It covers every
-request against an existing project, i.e. the vast majority of traffic. Priority: AR > 3D > 2D;
-sources with no engine references → `ui-app`. This mirrors the engine-kind detection the compiler
-already does for project icons — if that detection is exposed server-side, reuse it instead.
-
-**0. Intake — `intake-prompt.md` (new projects, preferred over the router).**
-The session's first request against a project with no app code runs the intake instead of building:
-one Haiku call returns 2–4 clarifying questions with tappable options (including the app kind when
-the request is ambiguous between kinds), a second call turns the answers into a short brief the
-user confirms. The confirmed kind sets the first build turn's bundle explicitly (`x-lecodes-bundle`
-sent by the client — the router below never runs), and the brief seeds `design/spec.md` as the
-project concept. Intake failure or the user's Skip degrades to the flow below — it never blocks.
-Client side: `frontend/.../chat/engine/intake.ts` + the intake card in `chatController.ts`.
-
-**2. Router model — `router-prompt.md` (fallback: intake skipped/failed on empty projects).**
-When `detectBundle` returns `null` (no code yet), classify the user's first message with one cheap
-call: `claude-haiku-4-5`, temperature 0, `max_tokens: 8`, reply is a single word `ui|2d|3d|ar`.
-The prompt is meaning-based and multilingual (EN/RU examples included). Parse defensively; any
-garbage → `ui`. Cost/latency: ~1k input tokens, a few output tokens, ~200–400 ms — negligible, and
-it runs at most once per project's life.
-
-**Stickiness.** Cache the chosen bundle per conversation and only move UP
-(`upgradeBundle(current, detected)`: ui → 2d/3d → ar), re-running `detectBundle` over files the
-assistant itself just generated. Never downgrade mid-conversation — it would invalidate the prompt
-cache and confuse in-flight context. Wrong-but-bigger is harmless; wrong-but-smaller causes
-hallucinated APIs.
-
-**3. Escalation — the `<bundle>` directive (recovery from a misroute).**
-Code-based detection can never recover from a wrong-but-smaller bundle on its own: a model that
-wasn't shown an engine never emits its globals, so the upgrade never triggers. core.md ("Missing
-engine") therefore instructs the generator to reply with ONLY `<bundle>ar</bundle>` (or `3d`/`2d`)
-when the request needs engine APIs its prompt doesn't document. The client (`parseBundleDirective`
-in `select.ts`) discards that reply, upgrades the pinned bundle, and re-sends the same request
-once — upgrade-only here too; a non-upgradable directive (e.g. a 3D project asking for the 2D
-engine) surfaces as a plain explanation instead. Relatedly, the router's classifier input must be
-ONLY the user's words: the proxy cuts everything before the frontend's `[Request]` marker, so e.g.
-a `.glb` in the project snapshot can't drag an explicit AR request toward `3d`.
-
-## Naming new projects
-
-`namer-prompt.md` is unrelated to bundle selection but lives here with the other model prompts:
-an assistant request made while the project has NO CODE yet (no non-empty `.ts` file — uploaded
-assets like a `.glb` model don't count as "started") also fires one extra Haiku call in parallel
-(`x-lecodes-bundle: namer`, `chat/engine/projectNamer.ts`) that returns bare JSON `{name, emoji}`;
-the result is saved via the normal project-update API (name + `iconEmoji`, drawn by
-`VProjectIcon`). Uncached — the prompt is far below Haiku's minimum cacheable prefix. Parsing is
-defensive: a garbled reply must never rename the project, so it's rejected rather than truncated
-into place; a rename while the call is in flight also wins over the generated name.
-
-**Why not route every request with a model?** It adds a failure mode (misroute → the generator
-confidently invents APIs it wasn't shown), latency, and cost on 100% of traffic to solve a problem
-that exists only for the ~one request per project where no code exists. Residual misroutes are
-recoverable: the index.md map means the generator always knows what exists, and the `<bundle>`
-escalation directive (above) lets it swap in the right engine module instead of guessing.
-
-## Keeping prompts honest
-
-- `index.md` must list every global exported from `sdk/src/inject.ts` — same contract as
-  `docs/check.mjs`. When a global is added, update docs, then the module, then index.md.
-- Known corrections baked into these prompts (do not regress; see `docs/AUTHORING.md`):
-  `onEndReached(thresholdPx, cb)` (threshold first), `bgSize: cover|contain|tile` (no `fill`),
-  track `deltaX/deltaY` are per-move, engine colors are hex/packed-int only, `animate` can't
-  tween strings/colors, `node.physics` (not `.body`), no `Camera2D.follow`, no
-  `UIScrollable.scrollTo`, models can't be cloned.
+# Codegen prompts
+
+> **Scope: the le.codes PLATFORM assistant only.** These prompts are bundled into `dist/` and served
+> by claude-proxy to the in-editor chat. They are NOT used by local development — Claude Code and
+> `lecodes-cli` never read them; those get the SDK surface from `.lecodes/types` (the d.ts bundle),
+> the generated project `CLAUDE.md` (`lecodes-cli/src/commands/init/templates.ts`) and `sdk/docs`.
+> A change meant for local development belongs there, not here.
+
+The system prompt(s) sent to Claude for LeCodes code generation, split into composable modules so
+a request only pays for the API areas it can actually use. Facts come from `../docs/` (the source
+of truth) — when the SDK changes, update docs first, then mirror the change here.
+
+**Consumers:**
+- `claude-proxy/prompts/*.md` — deployed copies of `dist/` + `router.md` (see its README); the
+  proxy injects them per the `x-lecodes-bundle` header (`claude-proxy/src/proxy/bundles.ts`). An
+  unknown/missing header is a **400** (no silent fallback), and the proxy's `/health` exposes a
+  sha256-12 per bundle — `bun run check:prompts` (repo root) compares them against `dist/` to
+  catch deploy drift (`--dir <proxy>/prompts` checks a local checkout instead).
+- `packages/frontend/.../chat/engine/bundleSelect.ts` — a thin adapter over `select.ts` (imported
+  as `sdk/prompts/select`); the selection logic itself is not duplicated anywhere.
+
+## Layout
+
+```
+core.md            shared foundation: response format, entry-point rule, runtime, math, tweens
+index.md           one-line map of EVERY global — always included (anti-hallucination anchor)
+canvas.md          Canvas drawing surface — engine-independent, in every bundle (each engine
+                   module documents its own hookup: Sprite texture / UIImage src / Texture)
+ui.md              UI module (screens, router, styling, widgets, lists)
+2d.md              2D engine module (sprites, tilemaps, Box2D physics, aspects, Canvas)
+3d.md              SHARED 3D content (nodes, meshes, models, materials, physics, particles)
+3d-scene.md        non-AR scenes: Scene construction, camera control, CharacterController, example
+3d-scene-files.md  declarative .scene.ts files (defineScene/use/ref/make, SceneHandle, HUD-over-scene)
+                   — the visual scene editor's format; non-AR only (camera nodes, skybox env)
+ar.md              AR scenes: ARScene, anchors, placement controls, example — never with 3d-scene.md
+core-design.md     design mode's core: directives/context/reports, no runtime APIs (no timers/network)
+ui-design.md       design mode's UI: curated static-mockup subset of ui.md (KEEP IN SYNC with it)
+design.md          design mode: canvas conventions — kit-first, states, design_map tool, tab bar
+concept.md         concept mode: product-shaping conversation, writes ONLY design/spec.md
+compose.ts         builds dist/<bundle>.md from the modules
+select.ts          deterministic bundle detection from project code
+router-prompt.md   fallback classifier prompt (empty projects only)
+namer-prompt.md    project name + icon-emoji generator (first request of a new project)
+intake-prompt.md   new-project intake: clarifying questions + confirmable brief (two Haiku turns)
+```
+
+## Bundles (`bun run prompts/compose.ts` → `dist/`)
+
+| Bundle | Modules | For |
+|---|---|---|
+| `ui-app` | core + index + canvas + ui | apps: screens, forms, lists, chat, commerce |
+| `2d-game` | core + index + canvas + 2d + ui | flat games, drawing toys |
+| `3d-app` | core + index + canvas + 3d + 3d-scene + 3d-scene-files + ui | 3D games/viewers, scene-editor projects |
+| `ar-app` | core + index + canvas + 3d + ar + ui | AR experiences |
+| `design` | core-design + ui-design + design | design mode: the design/ prototyping canvas |
+| `concept` | concept | concept mode: shape the idea, maintain design/spec.md (~0.8k tokens) |
+
+Fixed bundles (not per-request assembly) are deliberate: **each bundle is a stable prompt prefix**,
+so Anthropic prompt caching hits on every generation after the first (~10× cheaper input, lower
+latency). Per-request cherry-picking would produce near-unique prefixes and always pay full price.
+Game bundles include the full UI module because games need HUDs/menus; the ui-app bundle omits the
+engines entirely.
+
+## Selecting the bundle
+
+`design` and `concept` are different from the engine bundles: they are selected EXPLICITLY by the
+client from the editor's mode switcher (Concept / Design / Build — `x-lecodes-bundle: design` or
+`concept`) — never routed, detected from code, or reachable via the `<bundle>` escalation. The
+engine ladder below applies to Build mode only. Concept turns also carry no code context (design
+excerpts + file names only) and the client enforces each mode's write boundary (concept:
+design/spec.md only; design: design/ only). Any bundle may end a reply with `<mode>x</mode>` — the
+client strips it and renders a "Switch to …" button; the mode never switches itself.
+
+For the engine bundles — three signals, in this order:
+
+**1. Project code — `select.ts` (primary, deterministic).**
+`detectBundle(files)` scans the project's `.ts` sources for engine globals (comments and string
+literals stripped) and returns the bundle. This is language-independent — it doesn't matter what
+language the user writes in, because it never reads the user's words at all. It covers every
+request against an existing project, i.e. the vast majority of traffic. Priority: AR > 3D > 2D;
+sources with no engine references → `ui-app`. This mirrors the engine-kind detection the compiler
+already does for project icons — if that detection is exposed server-side, reuse it instead.
+
+**0. Intake — `intake-prompt.md` (new projects, preferred over the router).**
+The session's first request against a project with no app code runs the intake instead of building:
+one Haiku call returns 2–4 clarifying questions with tappable options (including the app kind when
+the request is ambiguous between kinds), a second call turns the answers into a short brief the
+user confirms. The confirmed kind sets the first build turn's bundle explicitly (`x-lecodes-bundle`
+sent by the client — the router below never runs), and the brief seeds `design/spec.md` as the
+project concept. Intake failure or the user's Skip degrades to the flow below — it never blocks.
+Client side: `frontend/.../chat/engine/intake.ts` + the intake card in `chatController.ts`.
+
+**2. Router model — `router-prompt.md` (fallback: intake skipped/failed on empty projects).**
+When `detectBundle` returns `null` (no code yet), classify the user's first message with one cheap
+call: `claude-haiku-4-5`, temperature 0, `max_tokens: 8`, reply is a single word `ui|2d|3d|ar`.
+The prompt is meaning-based and multilingual (EN/RU examples included). Parse defensively; any
+garbage → `ui`. Cost/latency: ~1k input tokens, a few output tokens, ~200–400 ms — negligible, and
+it runs at most once per project's life.
+
+**Stickiness.** Cache the chosen bundle per conversation and only move UP
+(`upgradeBundle(current, detected)`: ui → 2d/3d → ar), re-running `detectBundle` over files the
+assistant itself just generated. Never downgrade mid-conversation — it would invalidate the prompt
+cache and confuse in-flight context. Wrong-but-bigger is harmless; wrong-but-smaller causes
+hallucinated APIs.
+
+**3. Escalation — the `<bundle>` directive (recovery from a misroute).**
+Code-based detection can never recover from a wrong-but-smaller bundle on its own: a model that
+wasn't shown an engine never emits its globals, so the upgrade never triggers. core.md ("Missing
+engine") therefore instructs the generator to reply with ONLY `<bundle>ar</bundle>` (or `3d`/`2d`)
+when the request needs engine APIs its prompt doesn't document. The client (`parseBundleDirective`
+in `select.ts`) discards that reply, upgrades the pinned bundle, and re-sends the same request
+once — upgrade-only here too; a non-upgradable directive (e.g. a 3D project asking for the 2D
+engine) surfaces as a plain explanation instead. Relatedly, the router's classifier input must be
+ONLY the user's words: the proxy cuts everything before the frontend's `[Request]` marker, so e.g.
+a `.glb` in the project snapshot can't drag an explicit AR request toward `3d`.
+
+## Naming new projects
+
+`namer-prompt.md` is unrelated to bundle selection but lives here with the other model prompts:
+an assistant request made while the project has NO CODE yet (no non-empty `.ts` file — uploaded
+assets like a `.glb` model don't count as "started") also fires one extra Haiku call in parallel
+(`x-lecodes-bundle: namer`, `chat/engine/projectNamer.ts`) that returns bare JSON `{name, emoji}`;
+the result is saved via the normal project-update API (name + `iconEmoji`, drawn by
+`VProjectIcon`). Uncached — the prompt is far below Haiku's minimum cacheable prefix. Parsing is
+defensive: a garbled reply must never rename the project, so it's rejected rather than truncated
+into place; a rename while the call is in flight also wins over the generated name.
+
+**Why not route every request with a model?** It adds a failure mode (misroute → the generator
+confidently invents APIs it wasn't shown), latency, and cost on 100% of traffic to solve a problem
+that exists only for the ~one request per project where no code exists. Residual misroutes are
+recoverable: the index.md map means the generator always knows what exists, and the `<bundle>`
+escalation directive (above) lets it swap in the right engine module instead of guessing.
+
+## Keeping prompts honest
+
+- `index.md` must list every global exported from `sdk/src/inject.ts` — same contract as
+  `docs/check.mjs`. When a global is added, update docs, then the module, then index.md.
+- Known corrections baked into these prompts (do not regress; see `docs/AUTHORING.md`):
+  `onEndReached(thresholdPx, cb)` (threshold first), `bgSize: cover|contain|tile` (no `fill`),
+  track `deltaX/deltaY` are per-move, engine colors are hex/packed-int only, `animate` can't
+  tween strings/colors, `node.physics` (not `.body`), no `Camera2D.follow`, no
+  `UIScrollable.scrollTo`, models can't be cloned.

package/prompts/core-design.md

@@ -24,20 +24,33 @@ Remove a single top-level declaration:
 
 <remove file="design/shared/ui.ts" signature="const unusedCard" />
 
+Replace an exact snippet INSIDE a file — the operation for a small change to a screen (a label, a color, one element), where re-emitting the screen would repeat everything else:
+
+<replace file="design/screens/home.ts">
+<old>
+            UIText("Balance", { size: 16 }),
+</old>
+<new>
+            UIText("Group balance", { size: 18, weight: "bold" }),
+</new>
+</replace>
+
 Rules:
 - <file> replaces the whole file — write it out in full, never elide with "// ... rest unchanged"
+- <replace>: <old> is copied VERBATIM from the file as it is now (same characters, same lines — indentation is forgiven, nothing else is) and must occur exactly once — quote enough surrounding lines to make it unique; <new> is what takes its place and is never empty (to delete lines, quote the surrounding lines in <old> and repeat them without the deleted ones in <new>). One <replace> per spot; several spots in one file = several <replace> tags, each quoting the file as it was before your reply (they apply in order, so never let one <old> depend on an earlier <new>)
+- A <replace> ALWAYS holds both parts INSIDE the same tag, in this order: <old>…</old> then <new>…</new>. A <replace> without those inner tags is invalid and applies nothing — never emit the old text in one <replace> and the new text in a second one
 - <edit> and <remove> target exactly ONE top-level declaration (function / const / let in global scope). The signature is matched against the start of the existing declaration; the operation then covers that whole declaration — from its first line to its end (closing brace for functions/objects) — and nothing else: never neighboring declarations or surrounding comments
 - The signature only needs the declaration's keyword and name (`const PrimaryButton`) — anything after the name is ignored. It must name a declaration that exists in the file right now
 - <edit> must contain the complete new declaration, not a fragment. After a rename or argument change, update every call site, each via its own <edit>
 - One tag per declaration. To change or remove several declarations, emit several tags
-- Pick <edit>/<remove> for tweaking declarations in `shared/`; a screen file's default export is NOT targetable by <edit> — change a screen by re-emitting its whole <file> (screen files are small)
-- If a change doesn't fit these operations, fall back to <file> — never bend <edit> to cover multiple declarations
+- Choosing the operation, cheapest first: <replace> for a change of a few lines anywhere — this is how a screen is tweaked (its default export is NOT targetable by <edit>); <edit>/<remove> when a whole small declaration in `shared/` changes shape; <file> for new screens and real restructuring. Never bend <edit> to cover multiple declarations; if nothing else fits, fall back to <file>
+- What you write is the expensive part of a turn: never re-emit a file the request didn't change, and never rewrite a whole screen to touch a few lines
 - Only raw file content inside tags, no markdown fences (```). Backticks for template literals in the code are fine, and non-TS assets (e.g. raw SVG XML in a .svg file) are allowed
 - `design/meta.json` is the one file you NEVER write with these tags — the map is edited only through the `design_map` tool (its positions belong to the developer, and the board may have changed it while you were replying)
 
 ## Entry point & imports
 
-There is NO entry file in a design: every screen file default-exports its screen and nothing calls `.open()` — the board runs them. The UI API (`UIScreen`, `UIText`, …) is global — no imports needed. A screen's only imports are relative paths into `../shared/`. Imports of the design's own files are managed automatically: if your <edit> makes code reference another file's export, the import is added for you.
+There is NO entry file in a design: every screen file default-exports its screen and nothing calls `.open()` — the board runs them. The UI API (`UIScreen`, `UIText`, …) is global — no imports needed. A screen's only imports are relative paths into `../shared/`. Imports of the design's own files are managed automatically: if your <edit> or <replace> makes code reference another file's export, the import is added for you.
 
 Reference a design asset (image, .svg) by importing it or with the inline `asset('./path')` macro — a compile-time equivalent of the import (string LITERAL only, never a variable). External `https://…` URLs are used directly as strings.
 
@@ -47,7 +60,7 @@ Each request carries the project state: `[Assets]` lists binary files by path; `
 
 ## Automatic reports
 
-A user message starting with `[Automatic report]` is machine-generated feedback from the platform, not the user. After every reply, the platform compiles each changed screen and sends any failure back as such a report. Fix the problem directly with <file>/<edit> operations; at most one short sentence of explanation, never apologize or ask for confirmation.
+A user message starting with `[Automatic report]` is machine-generated feedback from the platform, not the user. After every reply, the platform compiles each changed screen and sends any failure back as such a report. Fix the problem directly with <replace>/<edit>/<file> operations; at most one short sentence of explanation, never apologize or ask for confirmation. A report that a <replace> or <edit> did NOT apply means the file is unchanged there: re-quote the <old> text exactly from the current file, or name an existing declaration — don't repeat the same tag.
 - A report is a checker result, not a person. Fix exactly what it lists.
 - If a report repeats an error you already tried to fix, take a DIFFERENT approach — prefer rewriting the whole file with <file>.
 - If a report says your reply was cut off and asks you to continue, re-emit the interrupted <file> block from its very beginning (a re-opened <file> replaces the whole file — never continue a file mid-line).
@@ -56,6 +69,16 @@ A user message starting with `[Automatic report]` is machine-generated feedback
 
 You may be given tools (they appear in the API request, each with its own description). `design_map` is part of the normal design workflow — use it in the same reply that creates or rewires screens. Any other tool is only worth reaching for when you genuinely can't proceed without it. Act on a tool's result and carry on; don't thank or apologise to it.
 
+## What the platform builds
+
+LeCodes builds mobile apps AND games: screen-based apps, 2D games, real-time 3D scenes with physics
+and animation, and AR — Build mode has a full engine for each. The board you work on holds SCREENS
+only: menus, HUD, inventory, profile, shop, settings. A 3D world, a game level or an AR scene is not
+a screen; it is built in Build mode, from this design. So for a game or a 3D request, design its
+screens here, describe the scene and its rules in spec.md, and say plainly that the scene itself
+comes in Build mode. Never tell the user the platform cannot do 3D or games, and never pass off a
+static illustration as the scene they asked for.
+
 ## Modes
 
 The platform runs the conversation in one of three modes the user switches between: Concept (shaping what the product is), Design — this prompt, and Build (the working app). When a request is really another mode's job — they want working logic, real data, or to "make the app actually do X" (a design is static mockups; never fake behavior), or they want to rethink what the product is before sketching more — do the part that belongs in the design (or answer briefly) and append the directive as the LAST line of your reply:

package/prompts/core.md

@@ -24,18 +24,43 @@ Remove a single top-level declaration:
 
 <remove file="home.ts" signature="let lastTime" />
 
+Replace an exact snippet INSIDE a file — the operation for a small change deep in a large declaration (a screen function, a scene setup), where <edit> would re-emit hundreds of untouched lines:
+
+<replace file="screens/group.ts">
+<old>
+            UIText("Balance", { size: 16 }),
+</old>
+<new>
+            UIText("Group balance", { size: 18, weight: "bold" }),
+</new>
+</replace>
+
 Rules:
 - <file> replaces the whole file — write it out in full, never elide with "// ... rest unchanged"
+- <replace>: <old> is copied VERBATIM from the file as it is now (same characters, same lines — indentation is forgiven, nothing else is) and must occur exactly once — quote enough surrounding lines to make it unique; <new> is what takes its place and is never empty (to delete lines, quote the surrounding lines in <old> and repeat them without the deleted ones in <new>). One <replace> per spot; several spots in one file = several <replace> tags, each quoting the file as it was before your reply (they apply in order, so never let one <old> depend on an earlier <new>)
+- A <replace> ALWAYS holds both parts INSIDE the same tag, in this order: <old>…</old> then <new>…</new>. A <replace> without those inner tags is invalid and applies nothing — never emit the old text in one <replace> and the new text in a second one
 - <edit> and <remove> target exactly ONE top-level declaration (function / const / let in global scope). The signature is matched against the start of the existing declaration; the operation then covers that whole declaration — from its first line to its end (closing brace for functions/objects) — and nothing else: never neighboring declarations or surrounding comments
 - The signature only needs the declaration's keyword and name (`function search`, `const label`) — anything after the name is ignored. It must name a declaration that exists in the file right now
 - <edit> must contain the complete new declaration, not a fragment. The new version may differ in name or arguments (renames are allowed — the signature points at the old declaration). After a rename or argument change, update every call site, each via its own <edit>
 - One tag per declaration. To change or remove several declarations, emit several tags
 - Removing a variable? Also update every declaration that references it (each via its own <edit>)
-- Pick <edit>/<remove> for tweaking a few existing declarations; <file> when adding declarations, changing imports, or restructuring
-- If a change doesn't fit these operations, fall back to <file> — never bend <edit> to cover multiple declarations
+- Choosing the operation, cheapest first: <replace> for a change of a few lines anywhere (a value, a label, one call, one branch); <edit>/<remove> when a whole small declaration changes shape; <file> for new files and real restructuring. Never bend <edit> to cover multiple declarations; if nothing else fits, fall back to <file>
+- What you write is the expensive part of a turn. Never re-emit a file the request didn't change, and never rewrite a whole file — or a whole 100-line function — to touch a few lines: that is what <replace> is for. When a large existing file needs a NEW declaration, prefer putting it in a new small file (imports between project files are managed for you) over rewriting the large one
 - File name includes the path if nested: "pages/home.ts"
 - Only raw file content inside tags, no markdown fences (```). Backticks for template literals in the code are fine, and non-TS assets (e.g. raw SVG XML in a .svg file) are allowed.
 
+// === EXAMPLE: a small change inside a big screen ===
+// screens/home.ts is a 120-line `export function homeScreen()`. Task: make the title bigger.
+
+<replace file="screens/home.ts">
+<old>
+        UIText("My cats", { size: 20, weight: "bold" }),
+</old>
+<new>
+        UIText("My cats", { size: 28, weight: "bold" }),
+</new>
+</replace>
+
 // === EXAMPLE: partial edits ===
 // Existing file has: let debugMode = true; const formatCount = (n) => `Count: ${n}`; const label = UIText(formatCount(0))
 // Task: rename formatCount → formatLabel with a prefix arg, drop unused debugMode:
@@ -58,7 +83,11 @@ directive and nothing else:
 <bundle>ar</bundle>   (or <bundle>3d</bundle> / <bundle>2d</bundle>)
 
 The platform reloads your instructions with the right engine documentation and repeats the request
-automatically. Never use this when the needed APIs are documented here — just do the work.
+automatically. This is also how a project CHANGES engine: a 2D game the user now wants in 3D, a 3D
+scene they want as a flat 2D game — ask for the engine the request needs, then rewrite what must
+change. Never tell the user the platform cannot do it, and never substitute a static picture or a
+fake for the engine they asked for. Never use this when the needed APIs are documented here — just
+do the work.
 
 ## Modes
 
@@ -81,7 +110,7 @@ Everything in this prompt is a global — no imports needed. A project's only im
 
 `main.ts` is the entry point — always name the entry file `main.ts`. A multi-file app's entry just wires things together: import the other modules, then run the launch logic (Router.init(...) / scene.open()). Every other file must be reachable from `main.ts` through imports — a side-effect module (registration code, global setup) still needs an `import './that-file'` in the entry, or it never runs. (In a project without a `main.ts`, the file nothing else imports is treated as the entry.)
 
-Imports of the project's own files are also managed automatically: if your <edit> makes code reference another file's export, the import is added for you — never fall back to a whole <file> rewrite just to change import lines. When writing a complete <file>, include imports normally.
+Imports of the project's own files are also managed automatically: if your <edit> or <replace> makes code reference another file's export, the import is added for you — never fall back to a whole <file> rewrite just to change import lines. When writing a complete <file>, include imports normally.
 
 Reference a project asset (image, font, video, .svg, .glb, …) by importing it or with the inline `asset('./path')` macro — a compile-time equivalent of the import (string LITERAL only, never a variable). External `https://…` URLs are used directly as strings.
 
@@ -91,11 +120,11 @@ Each request carries the project state: `[Assets]` lists binary files by path; `
 
 ## Automatic reports
 
-A user message starting with `[Automatic report]` is machine-generated feedback from the platform, not the user — e.g. a runtime error thrown by the running app, with a source-mapped stack. Fix the problem directly with <file>/<edit> operations. At most one short sentence of explanation; never apologize or ask for confirmation.
+A user message starting with `[Automatic report]` is machine-generated feedback from the platform, not the user — e.g. a runtime error thrown by the running app, with a source-mapped stack. Fix the problem directly with <replace>/<edit>/<file> operations. At most one short sentence of explanation; never apologize or ask for confirmation. A report that a <replace> or <edit> did NOT apply means the file is unchanged there: re-quote the <old> text exactly from the current file, or name an existing declaration — don't repeat the same tag.
 
 After every edit you make, the platform automatically verifies it — syntax, a full compile, and (for UI apps) a silent run that catches startup crashes — and sends any failure back as an `[Automatic report]`. Lesser findings (type errors, a blank first screen) are shown to the user, who can send them as a report with one tap. So:
 - A report is a checker result, not a person. Fix exactly what it lists; don't re-explain the whole change.
-- If a report repeats an error you already tried to fix, your last approach didn't work — take a DIFFERENT one. Prefer rewriting the whole file with `<file>` over another targeted `<edit>`.
+- If a report repeats an error you already tried to fix, your last approach didn't work — take a DIFFERENT one. Prefer rewriting the whole file with `<file>` over another targeted `<edit>`/`<replace>`.
 - A report may include the JSON of what actually rendered (the first screen) — read it to fix a blank or broken screen instead of guessing.
 - If a report says your reply was cut off and asks you to continue, re-emit the interrupted `<file>` block from its very beginning (a re-opened `<file>` replaces the whole file — never continue a file mid-line).
 - Prefer several small files over one very large file: a single-file re-emit then stays cheap if it ever has to be rewritten or continued.

package/prompts/select.ts

@@ -87,15 +87,30 @@ export function detectBundle(files: ProjectFile[]): Bundle | null {
 }
 
 /**
- * Sticky per-conversation upgrade: once a bundle is chosen, only ever move UP the specificity
- * ladder (ui → 2d/3d → ar) mid-conversation — never down, so the prompt-cache prefix stays
- * stable while a project grows from "empty" to "3D game with a HUD".
+ * Sticky per-conversation upgrade from CODE DETECTION: once a bundle is chosen, only ever move UP
+ * the ladder (ui → 2d → 3d → ar) mid-conversation — never down, so the prompt-cache prefix stays
+ * stable while a project grows from "empty" to "3D game with a HUD". The ladder mirrors
+ * detectBundle's priority (AR > 3D > 2D > UI): a 2D project that gains 3D code moves to the 3D
+ * bundle. (2D and 3D used to share a rank, which made 2D → 3D unreachable by any route — a project
+ * that started as a 2D game could never become a 3D one.)
  */
 export function upgradeBundle(current: Bundle, detected: Bundle): Bundle {
-  const rank: Record<Bundle, number> = { "ui-app": 0, "2d-game": 1, "3d-app": 1, "ar-app": 2 }
+  const rank: Record<Bundle, number> = { "ui-app": 0, "2d-game": 1, "3d-app": 2, "ar-app": 3 }
   return rank[detected] > rank[current] ? detected : current
 }
 
+/**
+ * Whether to honor the model's own `<bundle>` directive (parseBundleDirective). Unlike detection,
+ * an explicit request may move in ANY direction: the model is saying the APIs the request needs
+ * are not documented in its current bundle — turning a 2D game into 3D, a 3D app into AR, or a 3D
+ * scene back into a 2D game are all legitimate. The old code it rewrites is in its context; it
+ * needs no documentation to replace it. Only a no-op (asking for the bundle it already has) is
+ * refused, which also rules out a re-send loop.
+ */
+export function canSwitchBundle(current: Bundle, requested: Bundle): boolean {
+  return requested !== current
+}
+
 const DIRECTIVE_WORD: Record<string, Bundle> = { "2d": "2d-game", "3d": "3d-app", "ar": "ar-app" }
 
 /**