lecodes-sdk 1.1.0 → 1.2.0

package/package.json

@@ -33,7 +33,7 @@
     "typescript": "~5.8.3",
     "gl-matrix": "^3.4.4"
   },
-  "version": "1.1.0",
+  "version": "1.2.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/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.
+# 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.