lecodes-cli 1.0.0 → 2.0.1

package/src/commands/index.ts

@@ -1,60 +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 pn from "./pn"
-import pull from "./pull"
-import push from "./push"
-import render from "./render"
-import scene from "./scene"
-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,
-  ] },
-  { title: "Editors", commands: [
-    design,
-    scene,
-    thumbs,
-  ] },
-  { title: "Content", commands: [
-    assets,
-    shaders,
-    lightmap,
-    navmesh,
-  ] },
-  { title: "Native apps", commands: [
-    app,
-    pn,
-  ] },
-  { title: "Maintenance", commands: [
-    update,
-    { ...install, hidden: !opts.install },
-  ] },
-]
+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/index.ts

@@ -25,10 +25,10 @@ const STARTER = `// Welcome to LeCodes — the whole SDK is available as globals
 
 let count = 0
 
-const counter = UIText({ color: "#9fb0d0", fontSize: 22, marginTop: 18 }, "Taps: 0")
+const counter = UIText("Taps: 0").style({ color: "#9fb0d0", fontSize: 22, marginTop: 18 })
 
-const button = UIButton(
-  {
+const button = UIButton(UIText("Tap me").style({ color: "#ffffff", fontSize: 22 }))
+  .style({
     backgroundColor: "#4f7cff",
     borderRadius: 14,
     paddingVertical: 16,
@@ -36,24 +36,20 @@ const button = UIButton(
     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)
+    $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(
-  { 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
+  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()
 `

package/src/commands/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)