lecodes-cli 0.20.2 → 2.0.0

package/src/commands/index.ts

@@ -0,0 +1,64 @@
+import type { Group } from "../cli"
+import app from "./app"
+import assets from "./assets"
+import clone from "./clone"
+import compile from "./compile"
+import create from "./create"
+import design from "./design"
+import desktop from "./desktop"
+import dev from "./dev"
+import diff from "./diff"
+import init from "./init"
+import install from "./install"
+import lightmap from "./lightmap"
+import link from "./link"
+import login from "./login"
+import navmesh from "./navmesh"
+import plugin from "./plugin"
+import pn from "./pn"
+import pull from "./pull"
+import push from "./push"
+import render from "./render"
+import scene from "./scene"
+import serve from "./serve"
+import shaders from "./shaders"
+import status from "./status"
+import test from "./test"
+import thumbs from "./thumbs"
+import update from "./update"
+
+/*
+ * THE command list. Adding a command = one file with a `defineCommand` default export + one line
+ * here, in the group it belongs to (CONTRIBUTING.md). Order within a group is the help's order.
+ */
+export const commandGroups = (opts: { install: boolean }): Group[] => [
+  { title: "Project", commands: [init, create, clone, link, status, diff, pull, push, login] },
+  { title: "Run & test", commands: [
+    dev,
+    compile,
+    render,
+    test,
+    desktop,
+    serve,
+  ] },
+  { title: "Editors", commands: [
+    design,
+    scene,
+    thumbs,
+  ] },
+  { title: "Content", commands: [
+    assets,
+    shaders,
+    lightmap,
+    navmesh,
+  ] },
+  { title: "Native apps", commands: [
+    app,
+    plugin,
+    pn,
+  ] },
+  { title: "Maintenance", commands: [
+    update,
+    { ...install, hidden: !opts.install },
+  ] },
+]

package/src/commands/{init.ts → init/index.ts}

@@ -1,191 +1,195 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs"
-import { basename, dirname, join, resolve } from "node:path"
-import { LECODES_DIR } from "../manifest"
-import { materializeTypesLocal, writeTsconfig } from "../types"
-import { DEFAULT_IGNORE_FILE, ensureGitignore } from "../ignore"
-import { appClaudeMd, CLAUDE_SETTINGS, STARTER_FLOW } from "./projectTemplates"
-import { c, flagBool, log, note, success, warnErr, type Args } from "../util"
-
-/*
- * `lecodes init [dir]` — scaffold a brand-new LOCAL project: no account, no login, no server.
- *
- * Writes a starter entry, a CLAUDE.md (the headless render/test workflow for AI assistants) with
- * a passing starter flow test, the SDK's import-free type surface + a tsconfig (so VS Code gives
- * full IntelliSense offline), and a `.lecodesignore`. The result runs immediately with `lecodes dev`
- * (hot reload on a device) and compiles with `lecodes compile -o app.js` (a self-contained bundle
- * for LeCodes Desktop). It's the offline counterpart to `lecodes create`, which makes a project on
- * the server; a local project needs no manifest — `dev`/`compile` compile straight from the tree.
- *
- * Idempotent: existing files are kept (never clobbered), so it's safe to re-run or run in a folder
- * that already has content. Only the generated tsconfig + `.lecodes/types/` are rewritten each run.
- */
-
-const STARTER = `// Welcome to LeCodes — the whole SDK is available as globals, no imports needed.
-// Run it live on a device with \`lecodes dev\`, or bundle it with \`lecodes compile -o app.js\`.
-
-let count = 0
-
-const counter = UIText({ color: "#9fb0d0", fontSize: 22, marginTop: 18 }, "Taps: 0")
-
-const button = UIButton(
-  {
-    backgroundColor: "#4f7cff",
-    borderRadius: 14,
-    paddingVertical: 16,
-    paddingHorizontal: 40,
-    marginTop: 24,
-    alignItems: "center",
-    justifyContent: "center",
-  },
-  [UIText({ color: "#ffffff", fontSize: 22 }, "Tap me")],
-)
-  .style({ name: "tap" }) // names make elements targetable in tests/*.flow.json (see CLAUDE.md)
-  .onClick(() => {
-    count++
-    counter.text = "Taps: " + count
-  })
-
-const screen = UIScreen(
-  { backgroundColor: "#1e2230", alignItems: "center", justifyContent: "center", padding: 40 },
-  [
-    UIColumn(
-      { backgroundColor: "#2b3550", borderRadius: 24, padding: 40, alignItems: "center" },
-      [UIText({ color: "#ffffff", fontSize: 32 }, "Hello, LeCodes"), button, counter],
-    ),
-  ],
-).style({ name: "home" }) // the screen root's name is what tests' \`expect: { screen: … }\` reads
-
-screen.open()
-`
-
-/** `--desktop`: declare the desktop target up front. Window sizes are logical units (the host
- *  scales for HiDPI); `dev --desktop` / `desktop run` / `render --desktop` all read this, and a
- *  desktop-only app.json makes headless render/test default to the window size too. */
-const appJsonDesktop = (name: string) => JSON.stringify({
-  name,
-  desktop: {
-    window: { width: 1280, height: 800, minWidth: 640, minHeight: 480 },
-  },
-}, null, 2) + "\n"
-
-const readmeTemplate = (name: string) => `# ${name}
-
-A LeCodes app. The whole SDK is available as globals (\`UIScreen\`, \`UIText\`, \`Scene2D\`, …) —
-no imports needed. \`main.ts\` is the entry point.
-
-## Run it
-
-\`\`\`
-lecodes dev                  # live on your phone: scan the QR with the LeCodes app, hot reload
-lecodes compile -o app.js    # bundle to a single self-contained JS file
-\`\`\`
-
-## Test it (no device needed)
-
-\`\`\`
-lecodes render --png shot.png    # headless screenshot of the running app
-lecodes test                     # run tests/*.flow.json — the starter ships with a passing one
-\`\`\`
-
-Scenario format + conventions: see [CLAUDE.md](./CLAUDE.md) (written for AI assistants, useful
-for humans too).
-
-## Put it on the platform
-
-This project is local-only. To give it a home on le.codes (web editor, sharing, OTA updates):
-
-\`\`\`
-lecodes login                    # once per machine
-lecodes link                     # create a project from this folder and connect it
-lecodes push -m "initial"        # upload it as the first checkpoint (--publish to go live)
-\`\`\`
-
-Already made the project in the web editor? \`lecodes link --project <uuid>\` adopts it — it
-shows what your next push would change there before connecting anything.
-
-## Go native
-
-\`\`\`
-lecodes app init ios         # generate a native Xcode shell in ios/
-lecodes app sync             # embed the compiled bundle + plugins into it
-lecodes app open             # open it in Xcode, build & run
-\`\`\`
-
-## Layout
-
-- \`main.ts\` — the app's entry point. Add more .ts files freely and import them from
-  \`main.ts\`; a file named \`main.ts\` is always the entry.
-- \`tests/\` — headless flow tests (\`lecodes test\`); failing steps dump the frame to
-  \`tests/.artifacts/\`
-- \`CLAUDE.md\` — guidance for AI assistants (the headless feedback loop + testability conventions)
-- \`assets/\` — images/fonts the app references (created on demand)
-- \`tsconfig.json\` + \`.lecodes/types/\` — generated IDE types (rewritten by the CLI; don't edit).
-  They come from the SDK bundled in the CLI; \`lecodes update\` refreshes them from the platform.
-- \`.lecodes/\` is gitignored — per-checkout state (those types + \`manifest.json\`, this machine's
-  sync cursor once linked). After a fresh git clone: \`lecodes update\`, then
-  \`lecodes link --project <uuid>\` to re-attach.
-- \`.lecodesignore\` — files a future \`lecodes push\` would skip
-
-Full command list: \`lecodes --help\`.
-`
-
-export const init = async (args: Args) => {
-  const dirArg = (args._[0] ?? ".").replace(/[/\\]+$/, "") || "."
-  const root = resolve(dirArg)
-  const name = basename(root)
-
-  mkdirSync(root, { recursive: true })
-
-  let created = 0
-  const write = (rel: string, content: string) => {
-    const abs = join(root, rel)
-    if (existsSync(abs)) { note(`kept      ${rel}`); return }
-    mkdirSync(dirname(abs), { recursive: true })
-    writeFileSync(abs, content)
-    log(`${c.green("created")}   ${rel}`)
-    created++
-  }
-
-  const forDesktop = flagBool(args, "desktop")
-
-  // Starter entry — a root file named main.ts is always the detected entrypoint.
-  write("main.ts", STARTER)
-  write("README.md", readmeTemplate(name))
-  // --desktop: an app.json declaring the desktop target (window config in logical units).
-  if (forDesktop) write("app.json", appJsonDesktop(name))
-  // AI-assistant guidance + a passing flow test: the headless loop is discoverable from day one.
-  write("CLAUDE.md", appClaudeMd(name))
-  write(".claude/settings.json", CLAUDE_SETTINGS)
-  write("tests/counter.flow.json", STARTER_FLOW)
-  // Keep local render/preview outputs (screenshot.png, shots/) out of any future push.
-  write(".lecodesignore", DEFAULT_IGNORE_FILE)
-  // .lecodes/ is per-checkout state (generated types + the push cursor) — keep it out of git.
-  const gi = ensureGitignore(root)
-  if (gi === "created") { log(`${c.green("created")}   .gitignore`); created++ }
-  else if (gi === "updated") log(`${c.green("updated")}   .gitignore  ${c.dim("(+ .lecodes/)")}`)
-  else note("kept      .gitignore")
-
-  // IDE types: the SDK's import-free global surface + a tsconfig, so VS Code resolves UIScreen,
-  // Scene2D, setLoop, … with no server. Regenerated every run to pick up CLI upgrades.
-  const wroteTypes = materializeTypesLocal(root)
-  writeTsconfig(root)
-  log(`${c.green("written")}   tsconfig.json${wroteTypes ? ` + ${LECODES_DIR}/types/` : ""}  (IDE types)`)
-  if (!wroteTypes) {
-    warnErr("Bundled SDK types not found — tsconfig written, but globals may show unresolved until the CLI is rebuilt with vendored types.")
-  }
-
-  log("")
-  success(created
-    ? `Local project ${c.bold(name)} ready${dirArg === "." ? "" : ` in ${c.bold(dirArg)}/`}.`
-    : `Project ${c.bold(name)} already initialized.`)
-  const cd = dirArg === "." ? "" : `cd ${dirArg} && `
-  if (forDesktop) {
-    log(`  ${c.bold(cd + "lecodes dev --desktop")}      run it in a desktop window with hot reload`)
-    log(`  ${c.bold(cd + "lecodes test")}               run the flow tests headless (desktop-sized)`)
-    log(`  ${c.bold(cd + "lecodes desktop run")}        open the compiled app in the desktop host`)
-  } else {
-    log(`  ${c.bold(cd + "lecodes dev")}                run it on a device with hot reload`)
-    log(`  ${c.bold(cd + "lecodes test")}               run the flow tests headless (no device)`)
-    log(`  ${c.bold(cd + "lecodes compile -o app.js")}  bundle it for LeCodes Desktop`)
-  }
-}
+import { existsSync, mkdirSync, writeFileSync } from "node:fs"
+import { basename, dirname, join, resolve } from "node:path"
+import { LECODES_DIR } from "../../project/manifest"
+import { materializeTypesLocal, writeTsconfig } from "../../project/types"
+import { DEFAULT_IGNORE_FILE, ensureGitignore } from "../../project/ignore"
+import { appClaudeMd, CLAUDE_SETTINGS, STARTER_FLOW } from "./templates"
+import { bool, c, defineCommand, log, note, success, warnErr } from "../../cli"
+
+/*
+ * `lecodes init [dir]` — scaffold a brand-new LOCAL project: no account, no login, no server.
+ *
+ * Writes a starter entry, a CLAUDE.md (the headless render/test workflow for AI assistants) with
+ * a passing starter flow test, the SDK's import-free type surface + a tsconfig (so VS Code gives
+ * full IntelliSense offline), and a `.lecodesignore`. The result runs immediately with `lecodes dev`
+ * (hot reload on a device) and compiles with `lecodes compile -o app.js` (a self-contained bundle
+ * for LeCodes Desktop). It's the offline counterpart to `lecodes create`, which makes a project on
+ * the server; a local project needs no manifest — `dev`/`compile` compile straight from the tree.
+ *
+ * Idempotent: existing files are kept (never clobbered), so it's safe to re-run or run in a folder
+ * that already has content. Only the generated tsconfig + `.lecodes/types/` are rewritten each run.
+ */
+
+const STARTER = `// Welcome to LeCodes — the whole SDK is available as globals, no imports needed.
+// Run it live on a device with \`lecodes dev\`, or bundle it with \`lecodes compile -o app.js\`.
+
+let count = 0
+
+const counter = UIText("Taps: 0").style({ color: "#9fb0d0", fontSize: 22, marginTop: 18 })
+
+const button = UIButton(UIText("Tap me").style({ color: "#ffffff", fontSize: 22 }))
+  .style({
+    backgroundColor: "#4f7cff",
+    borderRadius: 14,
+    paddingVertical: 16,
+    paddingHorizontal: 40,
+    marginTop: 24,
+    alignItems: "center",
+    justifyContent: "center",
+    $hovered: { backgroundColor: "#6b91ff" }, // the mouse over it (desktop); $pressed is the press
+  })
+  .named("tap") // names make elements targetable in tests/*.flow.json (see CLAUDE.md)
+  .onClick(() => {
+    count++
+    counter.text = "Taps: " + count
+  })
+
+const screen = UIScreen(
+  UIColumn(UIText("Hello, LeCodes").style({ color: "#ffffff", fontSize: 32 }), button, counter)
+    .style({ backgroundColor: "#2b3550", borderRadius: 24, padding: 40, alignItems: "center" }),
+)
+  .style({ backgroundColor: "#1e2230", alignItems: "center", justifyContent: "center", padding: 40 })
+  .named("home") // the screen root's name is what tests' \`expect: { screen: … }\` reads
+
+screen.open()
+`
+
+/** `--desktop`: declare the desktop target up front. Window sizes are logical units (the host
+ *  scales for HiDPI); `dev --desktop` / `desktop run` / `render --desktop` all read this, and a
+ *  desktop-only app.json makes headless render/test default to the window size too. */
+const appJsonDesktop = (name: string) => JSON.stringify({
+  name,
+  desktop: {
+    window: { width: 1280, height: 800, minWidth: 640, minHeight: 480 },
+  },
+}, null, 2) + "\n"
+
+const readmeTemplate = (name: string) => `# ${name}
+
+A LeCodes app. The whole SDK is available as globals (\`UIScreen\`, \`UIText\`, \`Scene2D\`, …) —
+no imports needed. \`main.ts\` is the entry point.
+
+## Run it
+
+\`\`\`
+lecodes dev                  # live on your phone: scan the QR with the LeCodes app, hot reload
+lecodes compile -o app.js    # bundle to a single self-contained JS file
+\`\`\`
+
+## Test it (no device needed)
+
+\`\`\`
+lecodes render --png shot.png    # headless screenshot of the running app
+lecodes test                     # run tests/*.flow.json — the starter ships with a passing one
+\`\`\`
+
+Scenario format + conventions: see [CLAUDE.md](./CLAUDE.md) (written for AI assistants, useful
+for humans too).
+
+## Put it on the platform
+
+This project is local-only. To give it a home on le.codes (web editor, sharing, OTA updates):
+
+\`\`\`
+lecodes login                    # once per machine
+lecodes link                     # create a project from this folder and connect it
+lecodes push -m "initial"        # upload it as the first checkpoint (--publish to go live)
+\`\`\`
+
+Already made the project in the web editor? \`lecodes link --project <uuid>\` adopts it — it
+shows what your next push would change there before connecting anything.
+
+## Go native
+
+\`\`\`
+lecodes app init ios         # generate a native Xcode shell in ios/
+lecodes app sync             # embed the compiled bundle + plugins into it
+lecodes app open             # open it in Xcode, build & run
+\`\`\`
+
+## Layout
+
+- \`main.ts\` — the app's entry point. Add more .ts files freely and import them from
+  \`main.ts\`; a file named \`main.ts\` is always the entry.
+- \`tests/\` — headless flow tests (\`lecodes test\`); failing steps dump the frame to
+  \`tests/.artifacts/\`
+- \`CLAUDE.md\` — guidance for AI assistants (the headless feedback loop + testability conventions)
+- \`assets/\` — images/fonts the app references (created on demand)
+- \`tsconfig.json\` + \`.lecodes/types/\` — generated IDE types (rewritten by the CLI; don't edit).
+  They come from the SDK bundled in the CLI; \`lecodes update\` refreshes them from the platform.
+- \`.lecodes/\` is gitignored — per-checkout state (those types + \`manifest.json\`, this machine's
+  sync cursor once linked). After a fresh git clone: \`lecodes update\`, then
+  \`lecodes link --project <uuid>\` to re-attach.
+- \`.lecodesignore\` — files a future \`lecodes push\` would skip
+
+Full command list: \`lecodes --help\`.
+`
+
+export default defineCommand({
+  name: "init",
+  summary: "Scaffold a new LOCAL project (no login, no server)",
+  usage: "[dir]",
+  description: "Writes a starter main.ts, a CLAUDE.md + a passing flow test (the headless render / test loop), the IDE types + tsconfig, and a .lecodesignore. Run it with `lecodes dev` or `lecodes compile`. Idempotent: existing files are kept.",
+  flags: { desktop: bool("also write an app.json declaring the desktop target (window size; `dev --desktop`, `desktop run` and headless render / test pick it up)") },
+  examples: ["lecodes init myapp", "lecodes init --desktop"],
+  run: ({ args, flags }) => init(args[0], flags.desktop),
+})
+
+const init = (dir: string | undefined, forDesktop: boolean): void => {
+  const dirArg = (dir ?? ".").replace(/[/\\]+$/, "") || "."
+  const root = resolve(dirArg)
+  const name = basename(root)
+
+  mkdirSync(root, { recursive: true })
+
+  let created = 0
+  const write = (rel: string, content: string) => {
+    const abs = join(root, rel)
+    if (existsSync(abs)) { note(`kept      ${rel}`); return }
+    mkdirSync(dirname(abs), { recursive: true })
+    writeFileSync(abs, content)
+    log(`${c.green("created")}   ${rel}`)
+    created++
+  }
+
+  // Starter entry — a root file named main.ts is always the detected entrypoint.
+  write("main.ts", STARTER)
+  write("README.md", readmeTemplate(name))
+  // --desktop: an app.json declaring the desktop target (window config in logical units).
+  if (forDesktop) write("app.json", appJsonDesktop(name))
+  // AI-assistant guidance + a passing flow test: the headless loop is discoverable from day one.
+  write("CLAUDE.md", appClaudeMd(name))
+  write(".claude/settings.json", CLAUDE_SETTINGS)
+  write("tests/counter.flow.json", STARTER_FLOW)
+  // Keep local render/preview outputs (screenshot.png, shots/) out of any future push.
+  write(".lecodesignore", DEFAULT_IGNORE_FILE)
+  // .lecodes/ is per-checkout state (generated types + the push cursor) — keep it out of git.
+  const gi = ensureGitignore(root)
+  if (gi === "created") { log(`${c.green("created")}   .gitignore`); created++ }
+  else if (gi === "updated") log(`${c.green("updated")}   .gitignore  ${c.dim("(+ .lecodes/)")}`)
+  else note("kept      .gitignore")
+
+  // IDE types: the SDK's import-free global surface + a tsconfig, so VS Code resolves UIScreen,
+  // Scene2D, setLoop, … with no server. Regenerated every run to pick up CLI upgrades.
+  const wroteTypes = materializeTypesLocal(root)
+  writeTsconfig(root)
+  log(`${c.green("written")}   tsconfig.json${wroteTypes ? ` + ${LECODES_DIR}/types/` : ""}  (IDE types)`)
+  if (!wroteTypes) {
+    warnErr("Bundled SDK types not found — tsconfig written, but globals may show unresolved until the CLI is rebuilt with vendored types.")
+  }
+
+  log("")
+  success(created
+    ? `Local project ${c.bold(name)} ready${dirArg === "." ? "" : ` in ${c.bold(dirArg)}/`}.`
+    : `Project ${c.bold(name)} already initialized.`)
+  const cd = dirArg === "." ? "" : `cd ${dirArg} && `
+  if (forDesktop) {
+    log(`  ${c.bold(cd + "lecodes dev --desktop")}      run it in a desktop window with hot reload`)
+    log(`  ${c.bold(cd + "lecodes test")}               run the flow tests headless (desktop-sized)`)
+    log(`  ${c.bold(cd + "lecodes desktop run")}        open the compiled app in the desktop host`)
+  } else {
+    log(`  ${c.bold(cd + "lecodes dev")}                run it on a device with hot reload`)
+    log(`  ${c.bold(cd + "lecodes test")}               run the flow tests headless (no device)`)
+    log(`  ${c.bold(cd + "lecodes compile -o app.js")}  bundle it for LeCodes Desktop`)
+  }
+}

package/src/commands/{projectTemplates.ts → init/templates.ts}

@@ -2,7 +2,7 @@
  * has its own set — designTemplates.ts). CLAUDE.md is the AI-assistant counterpart of README.md:
  * it teaches the headless feedback loop (render / --script / test) and the conventions that make
  * an app testable, so an assistant opening the project drives the real app instead of guessing.
- * Facts here mirror lecodes-renderer's scenario engine — update both when the format changes. */
+ * Facts here mirror lecodes-headless's scenario engine — update both when the format changes. */
 
 export const appClaudeMd = (name: string) => `# ${name} — LeCodes app
 
@@ -30,17 +30,22 @@ lecodes render --desktop --view iso --png iso.png   # 3D: inspection camera fitt
                                   # scene (iso|top|front|side|back [--fov N]) — or --camera x,y,z
                                   # --look-at x,y,z; the app's camera is untouched. In scripts:
                                   # { "view": "iso", "screenshot": "iso.png" } then { "view": "off" }
-lecodes render --desktop --script <file>  # the same scenario on the NATIVE host (3D/Jolt, real
-                                  # GPU): coordinates only ({ x, y }), expect.log checked,
-                                  # text/node/screen expects skipped; deterministic 16 ms frames
+lecodes render --desktop --script <file>  # the same scenario on the NATIVE host (real GPU, the
+                                  # real hit-test): the same steps, targets and expects as
+                                  # headless (only expect.audio / the json output are headless-only)
+lecodes render --sim --script <file>      # the WINDOWLESS native host (lecodes-server): the real
+                                  # engines, no GPU, no pixels, no UI hit-test — expect.log /
+                                  # expect.paint only; runs on CI and beside an open desktop window
 lecodes test                      # all tests/*.flow.json + design-derived flows; run before "done"
-lecodes test --desktop            # the file flows on the NATIVE host (3D/Jolt/real GPU; coordinate
-                                  # flows only — design flows stay headless)
+lecodes test --desktop            # the file flows on the NATIVE host (design flows stay headless)
+lecodes test --sim                # the windowless twin: coordinates + expect.log / expect.paint only
 lecodes dev --android --time 12 --png phone.png   # the REAL phone over adb (USB): launches the app on
                                   # the dev url via adb reverse, streams device logs as [device:log],
                                   # screenshots after 12 s, force-stops, exit 1 on a crash. --serial
                                   # <id> with several devices, --apk <file> to install a build first.
                                   # Without --time it runs until Ctrl+C (which stops the app).
+lecodes dev --ios --time 12 --png sim.png   # the same on a booted iOS simulator or a plugged-in iPhone
+                                  # (Mac + Xcode): --udid <id|name>, --app <LeCodesApp.app> to install.
 \`\`\`
 
 Iterate with \`--script\` scenarios and keep the useful ones as \`tests/<name>.flow.json\` — they
@@ -49,7 +54,8 @@ are the regression suite. A failing step dumps the failing frame (JSON + PNG) un
 
 ## Scenario format (tests/*.flow.json and --script files)
 
-One action per step (\`tap\`, \`type\`+\`text\`, \`fill\`, \`scroll\` [+\`by\`], \`wait\`, and for
+One action per step (\`tap\`, \`type\`+\`text\`, \`fill\`, \`scroll\` [+\`by\`], \`wait\`, \`hover\` (the
+mouse over a node: \`$hovered\` + \`onMouseEnter\`; hovering elsewhere ends it), and for
 games: \`frames\` (advance N fixed 1/60 steps, no sleeping), \`drag\`+\`to\` [+\`ms\`], \`hold\`+\`ms\`,
 \`key\`+\`ms\` / \`keyDown\` / \`keyUp\` (KeyboardEvent.code: "ArrowRight", "KeyW", "Space" — mouse
 buttons are keys too: "MouseLeft"/"MouseRight"), \`look: [dx, dy]\` [+\`ms\`] (mouse motion for
@@ -57,12 +63,29 @@ buttons are keys too: "MouseLeft"/"MouseRight"), \`look: [dx, dy]\` [+\`ms\`] (m
 \`stick: { left: [x, y], right: [x, y], triggers: [l, r] }\` (values persist; \`index\` = pad),
 \`gamepad: "connect" | "disconnect"\`, pad buttons as keys: \`keyDown: "GamepadSouth"\`), then an
 optional \`expect\` (\`screen\`, \`node\`/\`notNode\`, \`text\`/\`notText\`,
-\`value: { target, equals }\`, \`log\` — a \`console.log\` line contains it), then outputs
-(\`screenshot\` [+\`clip\`: a node name or \`{ x, y, width, height }\`], \`json\`). Targets resolve by
-\`name\` → exact visible text → substring → input placeholder; a tap/drag on empty space reaches
+\`value: { target, equals }\`, \`log\` — a \`console.log\` line contains it,
+\`paint: { "<name>": { color: "#rrggbbaa", fontSize: 18, present: [...], absent: [...] } }\` — the
+resolved style of a named node, \`audio: { played, playing }\`), then outputs
+(\`screenshot\` [+\`clip\`: a node name or \`{ x, y, width, height }\`], \`json\`, \`dump\` — the
+runtime's tree with every node's box + resolved paint, identical on every host). Targets resolve
+by \`name\` → exact visible text → substring → input placeholder; a tap/drag on empty space reaches
 the 2D scene (sprite \`click\`/\`touchstart\`, \`ev.track()\`). Envelope keys: \`name\`,
 \`width\`/\`height\`, \`settle\`, \`fixtures\`, \`steps\`.
 
+Three hosts run the same file, at a fixed 16 ms clock on all of them:
+
+| host | flag | what it is | targets | expects |
+|---|---|---|---|---|
+| headless | (none) | Bun: the runtime + UI renderer + a recording 3D core (no GPU) | names or \`{ x, y }\` | all |
+| sim | \`--sim\` | the windowless native server: real engines, no pixels, no UI | \`{ x, y }\`, straight to the scene | \`log\`, \`paint\` |
+| desktop | \`--desktop\` | the hidden desktop window: pixels, GL materials, the real hit-test | names or \`{ x, y }\` | all but \`audio\` |
+
+One flow file, the same verdict on headless and desktop: names resolve the same way (\`name\` →
+exact text → substring → placeholder), every step runs (\`hover\`, \`type\`, \`fill\`, \`scroll\`,
+\`clip\` included) and the semantic expects read the same tree. Only \`expect.audio\` and the
+\`json\` output are the headless renderer's. On the desktop \`type\` taps the input and types into
+it (appends); the sim has no UI, so it takes coordinates and \`expect.log\` / \`expect.paint\` only.
+
 \`\`\`json
 { "steps": [
   { "expect": { "screen": "home", "text": "Taps: 0" } },
@@ -72,19 +95,21 @@ the 2D scene (sprite \`click\`/\`touchstart\`, \`ev.track()\`). Envelope keys: \
 ] }
 \`\`\`
 
-Game time is deterministic headless: \`setLoop\`, 2D physics/animation and aspect \`update(dt)\`
-advance in fixed 1/60 steps driven by \`wait\`/\`frames\`/\`drag\`/\`key\` — never by a wall clock —
-so a flow that passes once passes every time. \`Input.key(code)\` reads the keys a flow holds and
-\`Input.on('keydown' | 'keyup', e => e.code)\` fires for each \`key\`/\`keyDown\`/\`keyUp\` step
-(events land before the next loop tick); \`stick\` values are what \`Input.gamepad(0).axis()\` reads.
-Headless draws UI + the 2D scene (sprites, tilemaps, Box2D); 3D is captured as JSON with REAL Jolt
-physics (bodies fall, characters collide, triggers fire, ragdolls drop — a character with no ground
-under it falls, like on device) — use \`--desktop\` for 3D pixels. \`console.log\` + \`expect.log\` is the assertion
-channel for game state that has no UI.
+Game time is deterministic on every host: the Aspect / System phases (\`updateBefore\` / \`update\`),
+2D physics and animation advance in fixed 1/60 steps driven by \`wait\`/\`frames\`/\`drag\`/\`key\` —
+never by a wall clock — so a flow that passes once passes every time. \`Input.key(code)\` reads the
+keys a flow holds and \`Input.on('keydown' | 'keyup', e => e.code)\` fires for each
+\`key\`/\`keyDown\`/\`keyUp\` step (events land before the next loop tick); \`stick\` values are what
+\`Input.gamepad(0).axis()\` reads. Headless draws UI + the 2D scene (sprites, tilemaps, Box2D); 3D is
+captured as JSON with REAL Jolt physics (bodies fall, characters collide, triggers fire, ragdolls
+drop — a character with no ground under it falls, like on device) — use \`--desktop\` for 3D pixels,
+\`--sim\` for engine behaviour on a box without a GPU. \`console.log\` + \`expect.log\` is the
+assertion channel for game state that has no UI.
 
 ## Make the app testable
 
-- Give interactive elements a \`name\`: \`UIButton(...).style({ name: "login" })\`.
+- Give interactive elements a \`name\`: \`UIButton(...).named("login")\` (or \`el.name = "login"\`;
+  it is not a style key).
 - Name every screen's ROOT node with the screen's id — \`expect.screen\` reads it.
 - If the project has a \`design/\` folder, keep the design's screen ids and activator \`name\`s
   in the app code: \`lecodes test\` then checks the built app against the designed navigation
@@ -94,6 +119,16 @@ channel for game state that has no UI.
   match wins). \`lecodes test\` auto-loads it for design-derived flows; a scenario file opts in
   with \`"fixtures": "fixtures.json"\` in its envelope.
 - \`fill\` fills every empty input — use it before tapping a disabled-until-filled submit.
+- Visual state is a \`$class\` in the style (\`$pressed\`, \`$hovered\`, \`$focused\`, your own
+  \`$selected\` set with \`el.class.selected = true\` or bound with \`.class({ selected: () => … })\`);
+  the interaction states read back as \`button.isPressed\` / \`button.isHovered\`.
+  A flow asserts the EFFECT through \`expect.paint\` on a named node (the resolved \`color\` /
+  \`backgroundColor\` from the dump), never the class name — that works headless and native alike.
+- Hover is the mouse's: \`{ "hover": "login" }\`, a \`frames\` step, then \`expect.paint\` on the node's
+  resolved colour (\`$hovered\`) and \`expect.log\` from \`onMouseEnter\`; hover somewhere else to see
+  it end. Works headless and on \`--desktop\`; \`mouseTo: [x, y]\` is the same cursor by coordinates.
+  \`$focused\` is the desktop renderer's; a keyboard-driven highlight (your own \`$focus\` class moved
+  by arrow keys) is assertable everywhere: \`key\` steps, then \`expect.paint\` on the highlighted node.
 
 ## 3D scenes
 
@@ -108,7 +143,15 @@ channel for game state that has no UI.
 \`lecodes update\` if it's missing, never commit \`.lecodes/\`). For semantics and examples,
 fetch the docs — they are served as raw markdown for AI tools:
 
-- https://le.codes/llms.txt — the docs map; fetch it first to find the right page
+- https://le.codes/llms.txt — the docs map; fetch it first to find the right page. It opens with the
+  CLI: every \`lecodes\` command with what it is for, the agent page (running without a terminal,
+  \`--entry\`, login) and the editors that expose MCP tools — \`lecodes design\` (the screen board)
+  and \`lecodes scene\` (the 3D scene editor for \`.scene.ts\` files). \`lecodes <command> --help\`
+  is the authority on flags.
+  **Building a whole thing — a game, enemies, a crowd of characters, a native plugin? llms.txt opens
+  with a COOKBOOK: read the matching recipe BEFORE you design the structure.** It has the file
+  layout, a skeleton per part, how to verify, and the traps already paid for (start with
+  "Project architecture for a game" for any game bigger than one file).
 - https://le.codes/en/docs/api/<area>/<page>.md — one reference page as raw markdown
   (e.g. \`ui/styling.md\`, \`2d/scene2d.md\`, \`3d/scene.md\`, \`runtime/storage.md\`)
 - https://le.codes/en/docs/guide/<page>.md — guide pages (project anatomy, CLI, tracks)