lecodes-sdk 0.19.0

package/prompts/3d-scene.md

@@ -0,0 +1,119 @@
+## 3D scenes (non-AR)
+
+// ===== SCENE =====
+
+new Scene(options?: {
+  ibl?: boolean                  // image-based ambient light; default TRUE — every scene has ambient
+  environmentIntensity?: number  // IBL strength; default 20000
+  bloom?: boolean                // default false
+  bloomIntensity?: number        // default 0.2 (only with bloom: true)
+  skybox?: ColorInput            // solid background / clear color
+  antialias?: boolean            // 4× MSAA; default false
+})
+// Options are constructor-only, except: scene.skybox = '#87ceeb' (setter) and scene.setAntialias(on, scale = 4).
+
+scene.open(): void                     // become THE active scene (only one renders; closes any other)
+scene.close(): void
+Scene.active                           // static: active Scene | null
+
+scene.createOverlay(options?): Scene   // second scene drawn ON TOP, sharing this camera (3D HUD layer).
+                                       // Add nodes to it; it renders with its parent — never open() it.
+await scene.warmRender()               // render once off-screen so shaders compile — do it during a
+                                       // loading screen if the first visible frame hitches
+
+// The camera is YOURS here: position it, lookAt targets, or drive it from an aspect (see FollowCam below).
+
+// ===== CHARACTER CONTROLLER =====
+// Kinematic collide-and-slide player (Jolt CharacterVirtual). Needs a Shape (capsule recommended),
+// does NOT use Physics. Has its OWN gravity, separate from the world's. Updates in the EARLY
+// phase — input set this frame is consumed by this frame's step.
+node.aspect(Shape, { capsule: { halfHeight: 0.6, radius: 0.3 } })
+    .aspect(CharacterController, {
+        speed?: 5,           // horizontal speed, units/s
+        jumpSpeed?: 7,       // take-off speed
+        gravity?: -20,       // character-only gravity
+        maxSlope?: 45,       // degrees; attach-time only
+    })
+node.controller.move(x, z)         // horizontal intent, each in [-1, 1]; STICKY — send (0, 0) to stop
+node.controller.jump()             // queued; consumed next frame if grounded
+node.controller.teleport(x, y, z)  // clears vertical velocity
+node.controller.grounded           // boolean
+node.controller.velocity           // Vec3 (fresh copy)
+// It passes through Triggers, and (v1) isn't detected by them and isn't pointer-pickable while active.
+
+## 3D example
+
+// Complete mini-game slice: physics scene, character on a ground plane, WASD + jump,
+// click crates to knock them away, trigger goal zone, transparent UIText HUD.
+
+<file name="main.ts">
+Physics.configure({ gravity: [0, -9.81, 0] })
+
+const scene = new Scene({ skybox: '#87ceeb', antialias: true })
+scene.add(Light.sun({ direction: [1, -2, -1], shadowsQuality: 2 }))
+
+// Ground: flat plane (normal up!) + static collider
+scene.add(Mesh.plane({
+    material: Material.lit({ color: '#556655' }),
+    normal: [0, 1, 0], scale: 30, receiveShadows: true,
+}).aspect(Shape, { box: [15, 0.05, 15] }).aspect(Physics, { motion: 'static' }))
+
+// Crates: dynamic bodies, clickable via their Shape
+let score = 0
+for (let i = 0; i < 5; i++) {
+    const crate = Mesh.box({
+        material: Material.lit({ color: '#b5854b' }),
+        position: [i * 2 - 4, 0.5, -3], castShadows: true,
+    }).aspect(Shape, {}).aspect(Physics, { mass: 2 })
+    crate.addEventListener('click', () => {
+        crate.physics.applyImpulse([Mathf.random(-3, 3), 8, -6])
+        scoreLabel.text = `Score: ${++score}`
+    })
+    scene.add(crate)
+}
+
+// Player: capsule character controller
+const hero = Mesh.cylinder({
+    material: Material.lit({ color: '#3878f0' }),
+    position: [0, 1, 3], scale: [0.6, 1.8, 0.6], castShadows: true,
+})
+    .aspect(Shape, { capsule: { halfHeight: 0.6, radius: 0.3 } })
+    .aspect(CharacterController, { speed: 6, jumpSpeed: 8 })
+scene.add(hero)
+
+// Goal zone: sensor that ends the round
+const goal = Mesh.box({ material: Material.unlit({ color: '#44ff88' }), position: [0, 1, -8], scale: [2, 2, 0.3] })
+    .aspect(Shape, {})
+    .aspect(Trigger)
+goal.addEventListener('enter', other => {
+    if (other === hero) scoreLabel.text = `You win! Score: ${score}`
+})
+scene.add(goal)
+
+// Camera follows the hero (LATE default phase — reads final post-physics positions)
+class FollowCam extends Aspect<'followCam', Node> {
+    update() {
+        const p = this.node.worldPosition
+        scene.camera.position = [p.x, p.y + 3, p.z + 6]
+        scene.camera.lookAt(p)
+    }
+}
+hero.aspect(FollowCam)
+
+setLoop(() => {
+    const x = (Input.key('KeyD') ? 1 : 0) - (Input.key('KeyA') ? 1 : 0)
+    const z = (Input.key('KeyS') ? 1 : 0) - (Input.key('KeyW') ? 1 : 0)
+    hero.controller.move(x, z)
+    if (Input.key('Space')) hero.controller.jump()
+})
+
+// HUD over the 3D view: a UIWidget ATTACHED to the scene. (A UIScreen would REPLACE the scene —
+// exactly one Presentable is visible at a time.)
+let scoreLabel: UIText
+const hud = UIWidget(
+    scoreLabel = UIText('Score: 0').style({ color: 'white', fontSize: 24, fontWeight: 700 }),
+).style({ top: 'max(safe-top, 16px)', right: 16 })
+
+scene.open()
+hud.attachTo(scene).show()
+</file>

package/prompts/3d.md

@@ -0,0 +1,303 @@
+## 3D engine
+
+Filament-rendered 3D content with Jolt physics. Units are world units ≈ METERS, Y is up, forward is −Z. All `eulerAngles` are DEGREES. Everything here is a global — no imports.
+
+Scene construction and lifecycle are mode-specific — see the Scene (or AR) section further below. Everything in THIS section applies to any scene:
+
+// ===== SCENE CONTENT (any scene kind) =====
+
+scene.add(...nodes: Node[]): this      // register with the draw set (≠ parenting — see hierarchy)
+scene.remove(...nodes: Node[]): this
+
+// Scene-level pointer events — fire for EVERY tap; ev.target = hit Node (needs a Shape) or null:
+scene.addEventListener('click' | 'touchstart', (ev) => { ev.target; ev.clientX; ev.clientY })
+
+// 2D HUD over a 3D view: open a UIScreen (no bgColor → transparent) AFTER the scene opens — see UI section.
+
+// ===== NODES =====
+// Node = empty transform. Mesh, Model, Light, Camera, Particles all extend it.
+// The NATIVE engine owns the transform (physics rewrites it) — getters return fresh COPIES (see math).
+
+const pivot = new Node()
+pivot.position = [0, 1, -2]        // Vec3Like (raw arrays fine); getters return Vec3 copies
+pivot.x = 3                        // scalar setters x / y / z — the way to move one axis
+pivot.quaternion = Quat.fromEuler(0, 90, 0)
+pivot.eulerAngles = [0, 90, 0]     // DEGREES
+pivot.scale = 2                    // uniform number or [sx, sy, sz]
+pivot.matrix = Mat4.compose([0, 1, 0], Quat.identity, 1)
+
+node.worldMatrix                   // get/set full world transform
+node.worldPosition / node.worldQuaternion / node.worldEulerAngles / node.worldScale   // read-only
+node.forward                       // Vec3: world-space −Z axis (read-only)
+
+node.name = 'door'                 // visible/name; traverse lookups match on name
+node.visible = false
+node.destroy()                     // frees the native entity — the ONLY teardown; node unusable after
+
+// Hierarchy (separate from scene membership — scene.add puts it in the world, node.add parents it):
+node.add(...children): this
+node.setParent(parent: Node | null, worldPositionStays = false): this
+node.parent / node.children / node.childCount / node.getChild(i)
+node.traverse(cb: (node: Node) => void)          // this node, then all descendants
+
+node.lookAt(point: Vec3Like, mode = '-z', up = [0, 1, 0]): this   // aim a local axis at a WORLD point
+
+// Node events — node.addEventListener(channel, cb) / removeEventListener:
+// 'click'                  pointer-up over the node — REQUIRES a Shape aspect (pick body)
+// 'touchstart'             pointer-down over the node (ev.track() drags) — requires Shape
+// 'enter' / 'exit'         (other: Node) physics contact / trigger overlap began/ended — Shape + Physics/Trigger
+// Without a Shape a node is INVISIBLE to taps — only scene listeners fire (ev.target === null).
+
+// ===== ASPECTS =====
+// Capabilities attach to nodes as aspects and chain; each adds a named accessor:
+node.aspect(Class, opts?)          // attach + configure; returns the node (typed with the accessor)
+node.get(Class) / node.has(Class) / node.removeAspect(Class)
+// Named accessors: node.physics, node.trigger, node.controller, node.shape, node.anim
+// Custom game logic = your own aspect with per-frame update(dt seconds):
+class Spin extends Aspect<'spin', Node> {        // <accessor name, node kind>
+    speed = 90                                   // class fields = configurable defaults (opts override)
+    update(dt: number) { this.node.eulerAngles = this.node.eulerAngles.add([0, this.speed * dt, 0]) }
+}
+mesh.aspect(Spin, { speed: 45 })                 // never `new Spin()`; init in onAttach(), clean in onDetach()
+// Phases: default = LATE (after physics — for cameras/followers reading final positions);
+// set `updateBeforePhysics = true` on aspects that WRITE velocity/kinematic transforms.
+
+// ===== MESHES & MATERIALS =====
+
+// Primitive factories — all take: { material? (default Material.unlit()), position?, eulerAngles?,
+// scale?, name?, castShadows?, receiveShadows? }. Defaults are UNIT-sized (1 m).
+Mesh.box({ size?: Vec3Like | number })                          // full edge lengths; default 1×1×1
+Mesh.sphere({ radius? })                                        // default 0.5 (unit diameter)
+Mesh.cylinder({ radius?, radiusTop?, radiusBottom?, edges? })   // height fixed 1; radiusTop: 0 = cone
+Mesh.plane({ normal?: Vec3Like })   // 1×1 quad; default normal [0,0,1] = STANDS UPRIGHT facing camera.
+                                    // A ground/floor plane NEEDS normal: [0, 1, 0].
+
+mesh.material                       // get/set slot 0; mesh.setMaterial(mat, index = 0)
+mesh.castShadows = true             // write-only render flags (or set in factory options)
+mesh.receiveShadows = true
+
+// Materials:
+Material.lit({ color?, map?: Texture })    // PBR — needs light (IBL and/or sun) or renders black
+Material.unlit({ color?, map? })           // flat, ignores all lighting
+Material.video(player.texture)             // samples a VideoPlayer's texture
+Material.shadow(color = '#000000aa')       // shadow-catcher: invisible except where shadows fall (AR staple)
+material.color = '#ff8800'                 // convenience setters on lit/unlit (no-op on custom shaders)
+material.map = tex                         // Texture | Canvas | null
+
+// Custom compiled shaders (.mat files) — load, then set uniforms by name (chainable):
+const mat = new Material(await fetch(asset('./hologram.mat'), { useOnce: true }))
+    .set('baseColor', '#ffa200')           // '#rrggbb' / '#rrggbbaa' hex STRINGS only
+    .set('roughness', 0.54)                // number → float, boolean → bool
+    .set('glowMap', tex)                   // Texture → sampler
+    .set('dir', [0, 1, 0])                 // number[] / Float32Array → vector. NOT a Vec3 — spread it: [...v]
+// material.uniforms.key = value — same thing property-style. `color`/`map` setters don't know a
+// custom shader's uniform names — always .set() the real names there.
+
+// Textures:
+const tex = await Texture.load(asset('./crate.jpg'))   // url string | FetchResponse | File
+tex.wrapS = 1; tex.wrapT = 1        // set BEFORE assigning to a material
+Texture.fromCanvas(c)               // bake a Canvas (see CANVAS section) — nameplates, generated art;
+                                    // material.map = c does the same implicitly; c.update() refreshes it
+// No dispose() — textures live until the engine tears down. Load once, reuse everywhere.
+
+// Light — Light.sun() is the ONLY light (no point/spot lights). Ambient comes from the scene's IBL.
+scene.add(Light.sun({
+    direction?: Vec3Like,          // where light TRAVELS; default a key-light angle
+    intensity?: number,            // default 100000
+    color?: ColorInput,
+    shadowsQuality?: 0 | 1 | 2 | 3 // 0 = none, 1 = default 1024 map, 2 = soft 2048, 3 = PCSS 4096
+}))
+// Creation-time only — no setters; to change the sun, destroy() it and add a new one.
+// Shadows also need castShadows on the caster + receiveShadows on the ground.
+
+// Custom geometry — tweak a primitive before wrapping (moves pivot, tiles UVs), then Mesh.from(geo):
+const geo = Geometry.cylinder({ radiusTop: 0, edges: 6 }).scale(1, 3, 1).translate(0, 1.5, 0)
+const spike = Mesh.from(geo, { material })   // finish geometry BEFORE building the mesh (buffers upload once)
+
+// ===== MODELS (GLB) =====
+
+const hero = await Model.load(asset('./hero.glb'))   // asset path | https URL | FetchResponse; rejects on error
+scene.add(hero)                    // a Model IS a Node — transform/events/aspects all apply
+hero.traverse(n => { if (n.name === 'Sword') n.visible = false })   // GLB internals are plain child Nodes
+
+// Animation — every Model has an Animator pre-attached at model.anim (clip list = the glb's clips). A layer
+// has a LOOP (what it rests on) and ONE-SHOTS played over it; any call overrides what's there over its own fade:
+hero.anim.clips / hero.anim.clip('Run') / hero.anim.clip(0)   // AnimationClip[] (file order) / by name / by index; unnamed clips = 'animation_0', …
+hero.anim.playLoop('Idle', { fade: 0.2 })                     // rest on a looping clip (crossfades from whatever plays); hero.anim.loop reads it
+const loco = hero.anim.playLoop({ Idle: 0, Walking: 2, 'Fast Run': 6 })   // a BLEND as the loop (1D; [x, y] positions = 2D)
+loco.value = speed                                            // position on the axis — members stay in phase (no foot sliding)
+const ok = await hero.anim.play('slash', { fadeIn: 0.1, fadeOut: 0.3 })   // one-shot over the loop, returns to it
+// fades default to 0 (cut): fade = both ends, fadeIn / fadeOut = one end. Unknown name warns, plays nothing.
+// The await resolves at the HAND-OVER (end − fadeOut) with true (false = cut short) — what you start right after is what
+// the clip fades into: chains crossfade: if (ok) await hero.anim.play('slash2', { fadeIn: 0.3, fadeOut: 0.3 })
+// then hero.anim.playLoop('Crouch', { fade: 0.3 }) — or nothing = back to the current loop.
+if (!hero.anim.busy) hero.anim.play('kick')    // busy = a one-shot hasn't handed over; play() always takes over otherwise
+hero.anim.stop({ fade: 0.2 })                  // everything off → rest;  hero.anim.busy;  hero.anim.speed = 0.3 (0 = pause)
+// p = play(): p.done (return THIS from async fns) / p.playing / p.progress / p.weight / p.stop({ fade }) / p.seek(t)
+// Clips from other files (Mixamo: one GLB per animation), procedural, sliced — add by name:
+const [idle, slash] = await Promise.all([AnimationClip.load(asset('./idle.glb')), AnimationClip.load(asset('./attacks.glb'), 'Slash')])
+hero.anim.addClip('slash', slash).addClip('kick', hero.anim.clip('Kick').slice(0.2, 1.1))   // slice = a sub-range, re-timed
+AnimationClip.from({ tracks: { Hips: { position: [[0, [0,0,0]], [1, [0,0.05,0]]] } } })   // curves in code, binds by node NAME
+// Clip events live on the CLIP, in SECONDS: slash.addEvent(0.4, 'hit') → hero.anim.on('hit', (clip, layer) => dealDamage())
+// Layers (legs walk, arms aim): const upper = hero.anim.addLayer({ mask: 'Spine1' }); upper.playLoop('Aim', { fade: 0.3 }); upper.stop()
+//   { additive: true } = each clip's DELTA vs its first frame on top (recoil, breathe); upper.weight = 0.5
+// Root motion (clips whose hips travel — Mixamo without 'In Place', rolls): hero.anim.rootMotion = true → the node moves
+//   (or its CharacterController, as a velocity — it collides); the bone stays put
+hero.bone('RightHand')?.add(sword)  // bones are Nodes — sockets
+// FBX assets (Mixamo exports FBX): `lecodes assets convert hero.fbx --clips Idle.fbx Run.fbx -o hero.glb` → one GLB, clips merged by bone name
+// IK — late-phase aspects ON BONES (over the Animator's pose): TwoBone on the END bone, LookAt on the bone itself
+hero.bone('LeftFoot').aspect(IK.TwoBone, { target: footPoint, pole: kneeHint }).ik.weight = grounded ? 1 : 0
+hero.bone('Head').aspect(IK.LookAt, { target: camera, limit: 70 })   // axis = bone-local forward, default [0,0,-1]
+
+// ===== PHYSICS (Jolt) =====
+
+Physics.supported                  // static boolean — without it EVERYTHING here silently no-ops
+                                   // (aspects attach fine, velocity reads [0,0,0], no events) — gate gameplay
+Physics.configure({ gravity?: [0, -9.81, 0], maxBodies?: 4096 })   // ONCE, BEFORE any body exists
+Physics.interpolation = true       // static; default on — smooths bodies between fixed 60 Hz steps
+
+// Shape — collision geometry AND pickability. MUST be attached BEFORE Physics/Trigger/CharacterController
+// (they throw "requires a Shape aspect" otherwise). Pick exactly one kind:
+node.aspect(Shape, {
+    box?: Vec3Like,                                     // HALF-extents, WORLD units, NOT scaled by the node
+    sphere?: number,                                    // radius
+    cylinder?: { halfHeight: number, radius: number },  // Y-aligned
+    capsule?: { halfHeight: number, radius: number },   // halfHeight = cylinder section only
+    mesh?: true | 'convex',                             // the node's OWN triangles (Mesh geometry or Model GLB, × world scale)
+    origin?: Vec3Like,                                  // collider centre, offset from the node's pivot (world units, node rotation, NOT scaled)
+    raycast?: boolean,                                  // default true; false = invisible to taps & raycasts
+})
+// mesh: true = exact triangle mesh → level geometry / terrain / ramps: static or kinematic Physics, Trigger,
+// pick bodies, character ground. NEVER dynamic (Physics throws). mesh: 'convex' = convex hull → dynamic props.
+// A Model collider is its bind pose (skinned parts skipped) — animated characters keep a capsule.
+node.aspect(Shape, {})             // auto: box from the mesh AABB × world scale — right for most meshes
+// origin: art modelled ABOVE its pivot (a character on its feet, a barrel on its base) needs the
+// collider lifted: { capsule: {…}, origin: [0, 0.9, 0] }. An auto shape already centres on its mesh.
+node.shape.fit(kind?)              // measure dimensions + origin from what the node RENDERS (subtree,
+// so a Model root works where {} can't) and rebuild the live collider. Fit AFTER Model.load resolves.
+// A bare Shape (no Physics) creates a STATIC pick-only body → the node gets 'click'/'touchstart'.
+// It snapshots the transform at attach time — a MOVING pickable object needs a Physics body too.
+
+// Physics — rigid body:
+node.aspect(Shape, {}).aspect(Physics, {
+    motion?: 'static' | 'dynamic' | 'kinematic',   // default 'dynamic'
+    mass?: number,                                 // kg, dynamic only; default 1
+})
+node.physics.velocity              // Vec3 world units/s — get (fresh copy) / set
+node.physics.angularVelocity       // Vec3 DEGREES/s about each world axis — get / set
+node.physics.applyImpulse(v): this // instant impulse, wakes the body
+node.position = [x, y, z]          // place / teleport — moves the node AND its body (no moveTo())
+node.eulerAngles = [0, 90, 0]      // orientation is routed to the body too (NOT for a CharacterController)
+// A teleport keeps BOTH velocities: putting an object down is velocity = 0, angularVelocity = 0, position = p
+// PHYSICS OWNS a dynamic body's transform: a position write teleports, but the sim takes over again —
+// drive motion with velocity / applyImpulse. READING node.position/worldPosition is always correct.
+// static = never moves (floors, walls); kinematic = write position each frame, pushes but isn't pushed.
+
+// Contact events — on BOTH nodes of a contact/overlap, arg = the other node:
+crate.addEventListener('enter', (other: Node) => {})
+crate.addEventListener('exit',  (other: Node) => {})
+
+// Trigger — static sensor zone (needs a Shape; no options). Overlapping bodies fire 'enter'/'exit'
+// instead of colliding; never blocks movement:
+const goal = Mesh.box({ position: [0, 1, -6] }).aspect(Shape, { box: [1, 1, 0.2] }).aspect(Trigger)
+goal.addEventListener('enter', other => win(other))
+goal.trigger.moveTo(p)
+
+// Raycast — closest PICKABLE body (any Shape with raycast: true, incl. pick-only & triggers):
+Physics.raycast(origin: Vec3Like, dir: Vec3Like, maxDist = 1000)
+// → { node: Node | null, point: Vec3, normal: Vec3, fraction: number /* 0..1 of maxDist×|dir| */ } | null
+
+// ===== PARTICLES =====
+// GPU particle emitter node — move/rotate the node to move the emitter. Every option is a live setter.
+new Particles({
+    material: Material,                      // REQUIRED — Material.unlit() is the usual choice
+    rate?: number,                           // particles/second (plain number only — a range is ignored)
+    shape?: { type: 'point', v: Vec3Like } | { type: 'box', min: Vec3Like, max: Vec3Like },
+    startVelocity?: Vec3Like | {             // fixed vector, or a direction mode:
+        dir?: Vec3Like, from?: Vec3Like, to?: Vec3Like,          // along / away-from / toward
+        speed?: number | { min, max },
+        randomizeAngle?: { min: Vec3Like, max: Vec3Like },       // jitter, degrees per axis
+    },
+    gravity?: number, drag?: number,
+    lifetime?: number | { min, max },        // seconds; range = random per particle
+    color?: string | { min, max } | DynamicColor,
+    size?: number | { min, max } | DynamicValue,
+    rotation?: number | { min, max } | DynamicValue,
+    noise?: { strength?, frequency?, speed? } | null,   // turbulence
+})
+sparks.spawn(count)                          // burst on top of rate; one-shot effect = rate: 0 + spawn(n)
+// Curves over each particle's life (t runs 0..1): flat (t, value, t, value, …) stop lists:
+sparks.size = dynamic(0.1, 'multiply', 0, 1, 1, 4)                      // grow to 4× by death
+sparks.color = dynamicColor('#ffaa33', 0.7, '#ffffff', 1, '#000000')    // multiplies base — fade to black
+sparks.destroy()                             // from Node — removes the system
+
+// ===== CAMERA / RAY / PLANE / NOISE =====
+
+scene.camera                       // a Node — never constructed; every scene owns one.
+                                   // (Who MOVES it is mode-specific — see the Scene/AR section.)
+camera.fov / .near / .far          // lens: vertical FOV degrees (60), clip 0.01 / 1000 — SETTABLE.
+camera.setProjection({ fov, near, far })   // any subset; .horizontalFov, .displaySize stay read-only
+camera.getViewDirection(screenX, screenY): Vec3   // world dir through a screen point (logical px = ev.clientX/Y)
+camera.getRay(screenX, screenY): Ray              // origin = camera.worldPosition + that direction
+
+new Ray(origin, dir)               // .origin, .dir, .getPoint(t) → origin + t·dir
+new Plane(normal, point)           // infinite math plane (NOT a physics body)
+plane.intersectRay(ray): number | null   // returns the PARAMETER t, not the point → ray.getPoint(t)
+plane.signedDistance(p) / plane.projectPoint(p)
+
+// Drag-on-ground recipe — tap/drag to a world point on the floor:
+const ground = new Plane([0, 1, 0], [0, 0, 0])
+scene.addEventListener('click', ev => {
+    const ray = scene.camera.getRay(ev.clientX, ev.clientY)
+    const t = ground.intersectRay(ray)
+    if (t !== null) marker.position = ray.getPoint(t)
+})
+// Against real bodies instead: Physics.raycast(ray.origin, ray.dir, 100)
+
+const noise = new Noise()          // native Perlin/fractal; deterministic — animate by moving the sample point
+noise.get(x, y) / noise.get3d(x, y, z)
+noise.frequency = 0.01; noise.octaves = 1    // + fractalLacunarity, fractalGain
+
+// ===== COMMON MISTAKES — DO NOT DO THESE =====
+
+// ❌ wrong accessor name
+node.body.applyImpulse(...)                    // WRONG — the accessor is node.physics
+// ✅ node.physics / node.trigger / node.controller / model.anim
+
+// ❌ writing a dynamic body's transform per frame — physics owns it and fights back
+setLoop(() => { crate.position = target })
+// ✅ drive the simulation: crate.physics.velocity = ... / applyImpulse(...); kinematic → moveTo(...)
+
+// ❌ Physics/Trigger/CharacterController before Shape — throws
+node.aspect(Physics).aspect(Shape, {})
+// ✅ Shape FIRST
+node.aspect(Shape, {}).aspect(Physics)
+
+// ❌ full extents in Shape box — collider twice the mesh
+Mesh.box().aspect(Shape, { box: [1, 1, 1] })   // 2×2×2 collider around a 1×1×1 box
+// ✅ HALF-extents, or {} to auto-fit
+Mesh.box().aspect(Shape, { box: [0.5, 0.5, 0.5] })
+
+// ❌ cloning a Model
+const copy = model.clone()                     // doesn't exist
+// ✅ pool: Promise.all(Array.from({ length: N }, () => Model.load(url))) up front, recycle
+
+// ❌ a ground plane with the default normal — it stands upright facing the camera
+Mesh.plane({ scale: 20 })
+// ✅ Mesh.plane({ scale: 20, normal: [0, 1, 0] })
+
+// ❌ Vec3/Quat as a custom-shader uniform value — lowers to NULL
+mat.set('lightDir', dir)
+// ✅ spread to a plain array: mat.set('lightDir', [...dir])
+
+// ❌ point/spot lights — they don't exist
+Light.point(...)
+// ✅ Light.sun() + scene IBL is the whole lighting model; fake glows with unlit/bloom/particles
+
+// ❌ rgba()/named colors in 3D APIs — silently black
+Material.lit({ color: 'rgba(255, 0, 0, 0.5)' })
+// ✅ hex string or packed int: '#ff0000' / '#ff000080' / 0xff0000
+
+// ❌ a fresh Material per frame (or per particle) to animate a look
+setLoop(() => { mesh.material = Material.lit({ color: next() }) })
+// ✅ mutate the one material: mesh.material.color = next()  /  mat.set('progress', t)

package/prompts/README.md

@@ -0,0 +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.