lecodes-sdk 2.2.11 → 2.2.13

package/prompts/3d.md

@@ -1,299 +0,0 @@
-## 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')           // color STRINGS only (any CSS color); a number is a float
-    .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
-
-// ❌ 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

@@ -1,142 +0,0 @@
-# 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|fill|tile`,
-  track `deltaX/deltaY` are per-move, colors are CSS strings / 0xRRGGBB / [r,g,b(,a)] everywhere, `animate` can't
-  tween strings/colors, `node.physics` (not `.body`), no `Camera2D.follow`, no
-  `UIScrollable.scrollTo`, models can't be cloned.

package/prompts/ar.md

@@ -1,142 +0,0 @@
-## AR
-
-ARScene = a scene over the device camera with world tracking, from the "ar" plugin — the app lists it
-in app.json: `"plugins": { "ar": "*" }` (without it `ARScene.isSupported` is false and open() rejects).
-Everything from the 3D-engine section applies (nodes, meshes, models, materials, physics, events);
-THIS section is how an AR scene is created and driven. The session moves scene.camera every frame and
-draws the camera image behind everything (no skybox shows); lit materials still need the default IBL
-and/or a Light.sun.
-
-// ===== ARSCENE =====
-
-new ARScene(options?: {
-    ibl?: boolean                  // image-based ambient light; default TRUE
-    environmentIntensity?: number  // IBL strength; default 20000
-    mode?: 'world' | 'images'      // 'world' (default): planes, hitTest, anchors, images.
-                                   // 'images': image targets only — no planes, no hitTest, no root
-})
-ARScene.isSupported              // static: the host has the plugin — check before an AR button
-
-await scene.open(options?: {     // ASYNC: camera permission → warm render → session → on screen.
-    planes?: 'horizontal' | 'vertical' | 'both' | 'none'   // default 'horizontal'
-    lightEstimation?: boolean    // 'light' events
-    followLight?: boolean        // the scene's ambient follows the estimated light
-    transition?: Transition
-})                               // REJECTS: camera denied, 'unavailable' (no ARKit/ARCore), superseded —
-                                 // always await and handle failure (fall back / show a message).
-scene.close()                    // stops the session (the camera is let go)
-
-// ===== TRACKING =====
-scene.trackingState              // 'notAvailable' | 'limited' | 'normal'
-scene.trackingReason             // with 'limited': 'initializing' | 'excessiveMotion' | 'insufficientFeatures' | 'relocalizing'
-scene.addEventListener('tracking', (state, reason) => {})
-scene.addEventListener('error', ({ code, message }) => {})   // the session failed and is over
-
-// ===== ANCHORS =====
-// An Anchor is a Node the session moves — parent content under one (it joins the scene with it).
-
-scene.root                       // Anchor: pinned on the FIRST HORIZONTAL PLANE found ('track' fires then);
-                                 // until then at the world's origin. Not in 'images' mode.
-scene.anchor(pose)               // Anchor at a pose ({ position, rotation }, e.g. a hitTest result's)
-scene.createAnchor(source: FetchResponse, physicalWidth = 0.2): ImageAnchor
-// Image target: `source` = the marker image (fetch it), `physicalWidth` = its printed width in
-// METERS. Hidden until the image is seen. A RIGID pose in meters (no scale): its centre, Y out of
-// the image, the image in XZ (Z toward its bottom). Its size: anchor.extent = [width, height] m
-// (refined while tracked; [physicalWidth, 0] before the first 'track'). A plane on it:
-//   const s = Mesh.plane({ material, eulerAngles: [-90, 0, 0] }); anchor.add(s)
-//   anchor.addEventListener('track', () => s.scale = [anchor.extent[0], anchor.extent[1], 1])
-anchor.tracked                   // the session holds it now
-anchor.addEventListener('track', () => {})
-anchor.addEventListener('untrack', () => {})
-anchor.remove()                  // let it go; it leaves the scene
-
-// ===== PLANES & HIT TEST =====
-scene.planes                     // ARPlane[]: plane.type ('horizontal' | 'vertical'), plane.extent [w, d] m,
-                                 // plane.polygon (x,z pairs in the plane's space), plane.center (Vec3)
-scene.addEventListener('plane', ({ plane, change, mergedInto }) => {})   // change: 'added' | 'updated' | 'removed'
-scene.showPlanes = true          // a grid drawn on every plane
-const hits = await scene.hitTest(ev.clientX, ev.clientY, 'planes')   // a scene touch's point → [{ pose, type, plane, distance }], nearest first; [] = nothing
-
-// ===== LIGHT & CAPTURE =====
-scene.lightEstimate              // { intensity (1000 = neutral), temperature (K) } | null
-const photo = await scene.captureFrame()   // the camera image alone: a JPEG File
-const shot = await scene.capture()         // what the scene shows (camera + 3D): a PNG File
-
-// ===== PLACEMENT CONTROLS =====
-const controls = scene.addControls(target: Node, options?: {
-    minScale?: number,   // pinch clamp; default 0.08
-    maxScale?: number,   // default 2
-    pan?: boolean,       // one finger: over the plane under the finger; default true
-    pinch?: boolean,     // two-finger uniform scale; default true
-    twist?: boolean,     // two-finger rotate around Y; default true
-})
-controls.remove()        // detach the gesture listeners
-
-// ===== ON THE WEB =====
-// The camera under the scene, the camera turned by the phone's sensors, its position fixed: tracking
-// is 'normal' at once, NO planes, NO images, hitTest resolves [], root never fires 'track' (it stays
-// at the origin) — don't gate content on root's 'track' if the app must work in a browser.
-
-// ===== AR RULES & MISTAKES =====
-
-// The camera is the session's — READ it (position, getRay), NEVER place it.
-// ❌ moving the camera to frame content — the session overwrites it every frame
-arScene.camera.position = [0, 2, 4]
-// ✅ move the WORLD: parent content under scene.root (or an anchor) and place THAT
-scene.root.add(model); model.position = [0, 0, -1]
-
-// ❌ forgetting the plugin: ARScene without "ar" in app.json "plugins" is unsupported everywhere
-// ✅ app.json: { "plugins": { "ar": "*" } }
-
-// ❌ treating open() like Scene.open()
-arScene.open(); spawnStuff()           // runs before the session started; rejection unhandled
-// ✅ await it and handle failure
-try { await arScene.open() } catch { toast('AR is not available on this device') }
-
-// ❌ placing on a tap at a guessed distance
-// ✅ hitTest the tap and anchor there
-scene.addEventListener('click', async (ev) => {
-    const [hit] = await scene.hitTest(ev.clientX, ev.clientY, 'planes')
-    if (hit) scene.anchor(hit.pose).add(lamp.clone())
-})
-
-// Shadows on the real floor: a Mesh.plane({ normal: [0, 1, 0], material: Material.shadow() })
-// under the object — invisible except where shadows fall.
-
-## AR example
-
-// Object-placement app: a GLB on the floor once it is found, drag/pinch/twist to position it,
-// tap it to play its animation, shadow on the real floor, a HUD hint over the scene.
-// app.json lists the plugin: { "plugins": { "ar": "*" } }
-
-<file name="main.ts">
-const scene = new ARScene()
-
-const hint = UIText('Move your phone to find the floor').style({ color: 'white', fontSize: 16 })
-scene.widgets(UIWidget(hint).style({ position: 'absolute', left: 0, right: 0, bottom: 48, alignItems: 'center' }))
-
-async function main() {
-    const chair = await Model.load(asset('./chair.glb'))
-    chair.aspect(Shape, {})                        // pick body → tappable
-    chair.addEventListener('click', () => chair.anim.play(0, { loop: false }))
-
-    // Shadow catcher on the real floor, parented with the model so it follows placement
-    const shadow = Mesh.plane({ normal: [0, 1, 0], material: Material.shadow(), scale: 2 })
-    chair.add(shadow)
-
-    // Content lives under the floor anchor (it joins the scene with it)
-    scene.root.add(chair)
-    scene.add(Light.sun({ shadowsQuality: 2 }))
-    scene.root.addEventListener('track', () => { hint.text = 'Drag to move · pinch to scale · tap to animate' })
-
-    scene.addControls(chair)                       // drag / pinch-scale / twist gestures
-
-    try {
-        await scene.open()                         // camera permission → session
-    } catch {
-        toast('AR is not available on this device')
-    }
-}
-
-main()
-</file>

package/prompts/canvas.md

@@ -1,28 +0,0 @@
-// ===== CANVAS — retained drawing baked to a texture (engine-independent) =====
-// The way to get custom TEXT and vector graphics anywhere: charts, generated images, labels,
-// paint surfaces. Mirrors the browser 2D context, but RECORDS commands and rasterizes on bake.
-// A baked Canvas is accepted wherever an image/texture source is — the exact hookups are listed
-// in the UI / engine sections of this prompt.
-
-const c = new Canvas(width, height, { pixelRatio: device.pixelRatio })
-// width/height are LOGICAL units — author all drawing logical; pixelRatio only multiplies baked
-// resolution (crispness), never the on-screen size.
-
-c.fillStyle = '#ff8800'   // any CSS color string, as everywhere in the SDK;
-c.lineCap = 'round'       // also strokeStyle, lineWidth, lineJoin, miterLimit, globalAlpha, letterSpacing,
-c.setLineDash([4, 2])     // dashes; a gradient: c.fillStyle = c.createLinearGradient(x0,y0,x1,y1).addColorStop(0,'#fff').addColorStop(1,'transparent')
-c.font = 'bold 16px sans-serif'   // textAlign ('left'|'center'|'right'), textBaseline
-                                  // custom fonts: draw only AFTER await registerFont(...)
-c.fillRect(x, y, w, h) / c.strokeRect / c.clearRect
-c.beginPath().moveTo(x,y).lineTo(x,y).arc(x,y,r,a0,a1).arcTo(x1,y1,x2,y2,r).ellipse(x,y,rx,ry,rot,a0,a1).rect(x,y,w,h).roundRect(x,y,w,h,r).closePath()  // all chain
-c.fill('evenodd'?) / c.stroke() / c.clip() / c.fillText(text, x, y) / c.strokeText(text, x, y)
-c.measureText(text): { width, ascent, descent }   // in the CURRENT font and letterSpacing, logical px
-c.drawImage(bmp: Bitmap, dx, dy [, dw, dh])   // blits a Bitmap only (c.toBitmap(), await c.loadImage(SvgSource(svg) | fetchResponse))
-
-c.update(): this    // after redrawing, push new pixels to EVERY texture/image this canvas produced
-c.reset(): this     // discard the recorded drawing to start over
-c.resize(w, h): this   // new logical size (takes effect next bake; measure-then-resize works pre-bake)
-c.toBitmap(): Bitmap   // rasterized snapshot, usable with drawImage
-// GOTCHA: reset() clears the recorded STATE too — font/fillStyle/textAlign fall back to defaults
-// (the getters report the defaults again). Re-set font & friends after every reset().
-// Ever-growing drawings: flatten — const snap = c.toBitmap(); c.reset(); c.drawImage(snap, 0, 0)