lecodes-cli 0.20.2 → 1.0.0

package/src/commands/design/index.ts

@@ -0,0 +1,391 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { CliError, bool, c, defineCommand, log, note, num, str, warnErr, type FlagValues } from "../../cli"
+import { compileDesignScreen } from "../../compile/designCompile"
+import { loadPeer } from "../../hosts/peerInstall"
+import { disableDesignShare, enableDesignShare, setDesignCommentsOpen } from "../../platform/api"
+import { openBrowser } from "../../platform/browserAuth"
+import { readMetaFrames } from "../../project/designMeta"
+import { materializeTypesLocal, writeTsconfig } from "../../project/types"
+import { session } from "../shared"
+import comments, { startCommentSync } from "./comments"
+import { DEFAULT_PORT, dirFlag, getContext, loadDesignServer, optionalPlatform, threadRef, type DesignContext } from "./context"
+import snapshot from "./snapshot"
+import { CLAUDE_MD, DESIGN_MACROS_DTS, HOME_SCREEN_TS, META_JSON, META_JSON_DESKTOP, README_HINT, SPEC_MD, TABS_TS, TOKENS_TS } from "./templates"
+
+export { flushDesignComments, type CommentFlush } from "./comments"
+
+/*
+ * `lecodes design` — the LeCodes Design canvas: prototype an app as live screens + a flow graph.
+ *
+ *   design [serve]     start the dev server + browser canvas (needs `lecodes-design`)
+ *   design init        scaffold the design folder (screens/, shared/, meta.json, spec.md, CLAUDE.md)
+ *   design snapshot    render screens headless to JSON/PNG (snapshot.ts, needs `lecodes-renderer`)
+ *   design arrange     auto-layout the flow graph (--new: only place unplaced screens)
+ *   design check       static coherence: spec.md links, flow warnings, untagged screens
+ *   design share       toggle the public share link (design must be pushed first)
+ *   design comments    the board's review comments + add / reply / resolve / pull (comments.ts)
+ *
+ * The design folder (default `design/`) holds one file per screen (screens/<id>.ts default-exports
+ * a UIScreen), shared tokens/components (shared/), and meta.json — the human-owned graph of
+ * positions, descriptions and edges. Screens compile per-file through the normal project pipeline
+ * and render via canvas-ui, live in the browser and headless for AI feedback.
+ */
+
+/** First non-empty line, for one-line echoes of a comment body. */
+const firstLine = (body: string, max = 64): string => {
+  const line = body.split("\n").find((l) => l.trim())?.trim() ?? ""
+  return line.length > max ? line.slice(0, max - 1) + "…" : line
+}
+
+// ---- serve -------------------------------------------------------------------------------------
+
+const serveFlags = {
+  ...dirFlag,
+  port: num("dev-server port", { default: DEFAULT_PORT }),
+  "no-open": bool("don't open the browser"),
+  "no-sync": bool("don't reconcile comments with the platform while serving"),
+}
+
+const serve = async (flags: FlagValues<typeof serveFlags>): Promise<void> => {
+  const ctx = getContext(flags.dir)
+  const designServer = await loadDesignServer(ctx)
+
+  // The MCP render_screen tool renders headless through lecodes-renderer, injected here so the
+  // design server keeps no dependency on it. Absent renderer → the tool returns an install hint.
+  // Opportunistic: never triggers an install from inside the MCP server (the tool reports the hint).
+  const renderer = await loadPeer<typeof import("lecodes-renderer/headless")>("lecodes-renderer", "headless", { for: "lecodes design (render_screen)", install: false })
+  const renderScreen = renderer
+    ? async (id: string, format: "json" | "png" | "both", state?: string) => {
+        const js = await compileDesignScreen({
+          root: ctx.root, manifest: ctx.manifest, name: ctx.name, designDir: ctx.designDir, designKey: ctx.designKey, screenId: id, state, assets: "disk",
+        })
+        const frames = readMetaFrames(ctx.designDir)
+        const [width, height] = frames.screens[id]?.size ?? frames.defaultSize
+        const warnings: string[] = []
+        let json: string | undefined
+        let png: Buffer | undefined
+        if (format === "json" || format === "both") {
+          const res = await renderer.renderToJson(js, { width, height, localAssets: true })
+          json = res.text
+          warnings.push(...res.warnings)
+        }
+        if (format === "png" || format === "both") {
+          const res = await renderer.renderToPng(js, { width, height, localAssets: true, scale: 2 })
+          png = res.png
+          warnings.push(...res.warnings)
+        }
+        return { json, png, warnings }
+      }
+    : undefined
+
+  const server = await designServer.startDesignServer({
+    root: ctx.root,
+    designDir: ctx.designDir,
+    name: ctx.name,
+    port: flags.port,
+    log: note,
+    // Who owns the conversation: linked, the files mirror the platform's open threads and local
+    // writes queue for `lecodes push`; standalone, these files are the record.
+    linked: !!optionalPlatform(ctx),
+    compileScreen: async (id: string, state?: string) => ({
+      js: await compileDesignScreen({
+        root: ctx.root, manifest: ctx.manifest, name: ctx.name, designDir: ctx.designDir, designKey: ctx.designKey, screenId: id, state, assets: "server",
+      }),
+      warnings: [],
+    }),
+    renderScreen,
+  })
+
+  // Reconcile comments with the platform while we run, so review feedback from the share link shows
+  // up on the board (and in comments/) without a manual pull; answers go back with `lecodes push`.
+  // `--no-sync` opts out.
+  const sync = flags["no-sync"] ? null : startCommentSync(ctx, designServer)
+
+  log(`${c.bold("LeCodes Design")} — ${ctx.name}`)
+  log(`Canvas:   ${c.bold(server.url)}`)
+  log(`MCP:      ${c.bold(server.url + "/mcp")}${renderer ? "" : c.dim("  (render_screen off — npm install -g lecodes-renderer)")}`)
+  log(`Watching: ${ctx.dirName}/  (screens hot-reload on save; Ctrl+C to stop)`)
+  if (sync) log(`Comments: ${c.dim("in sync with the platform — replies and resolves go back automatically")}`)
+  if (!flags["no-open"]) openBrowser(server.url)
+}
+
+const serveCmd = defineCommand({
+  name: "serve",
+  summary: "Start the dev server + browser canvas (what bare `lecodes design` does)",
+  flags: serveFlags,
+  examples: ["lecodes design serve --port 4480 --no-open"],
+  run: ({ flags }) => serve(flags),
+})
+
+// ---- init --------------------------------------------------------------------------------------
+
+/** Register the design server as a project-scoped MCP server so Claude Code auto-discovers it.
+ *  Merges into an existing .mcp.json (never clobbers a hand-broken one). */
+const writeMcpConfig = (ctx: DesignContext, port: number): void => {
+  const path = join(ctx.root, ".mcp.json")
+  const entry = { type: "http", url: `http://localhost:${port}/mcp` }
+  let config: { mcpServers?: Record<string, unknown> } = {}
+  if (existsSync(path)) {
+    try {
+      config = JSON.parse(readFileSync(path, "utf8"))
+    } catch {
+      warnErr(".mcp.json exists but isn't valid JSON — left it untouched. Add the lecodes-design server by hand.")
+      return
+    }
+  }
+  config.mcpServers ??= {}
+  const existing = config.mcpServers["lecodes-design"] as { url?: string } | undefined
+  if (existing?.url === entry.url) { note("kept      .mcp.json (lecodes-design MCP server)"); return }
+  config.mcpServers["lecodes-design"] = entry
+  writeFileSync(path, JSON.stringify(config, null, 2) + "\n")
+  log(`${c.green(existing ? "updated" : "created")}   .mcp.json (lecodes-design MCP → ${entry.url})`)
+}
+
+const init = defineCommand({
+  name: "init",
+  summary: "Scaffold the design folder (screens/, shared/, meta.json, spec.md, CLAUDE.md)",
+  description: "Existing files are kept. Also ignores .snapshots/ and comments/ in .lecodesignore, registers the board's MCP server in .mcp.json (so Claude Code reaches it), and writes the IDE types + a design-scoped tsconfig so screens typecheck standalone or in a project.",
+  flags: {
+    ...dirFlag,
+    port: num("dev-server port to register in .mcp.json", { default: DEFAULT_PORT }),
+    desktop: bool("desktop-frame board (meta.json defaultSize [1280, 800] instead of the phone frame)"),
+  },
+  examples: ["lecodes design init", "lecodes design init --desktop"],
+  run: async ({ flags }) => {
+    const ctx = getContext(flags.dir)
+    // --desktop: scaffold a desktop-frame board (meta.defaultSize [1280, 800]; every consumer —
+    // board tiles, arrange, snapshots, render_screen — resolves frames from it).
+    const files: [string, string][] = [
+      ["meta.json", flags.desktop ? META_JSON_DESKTOP : META_JSON],
+      ["spec.md", SPEC_MD],
+      ["README.md", README_HINT],
+      ["CLAUDE.md", CLAUDE_MD],
+      [join("shared", "tokens.ts"), TOKENS_TS],
+      [join("shared", "tabs.ts"), TABS_TS],
+      [join("screens", "home.ts"), HOME_SCREEN_TS],
+    ]
+    mkdirSync(join(ctx.designDir, "screens"), { recursive: true })
+    mkdirSync(join(ctx.designDir, "shared"), { recursive: true })
+    let created = 0
+    for (const [rel, content] of files) {
+      const abs = join(ctx.designDir, rel)
+      if (existsSync(abs)) { note(`kept      ${ctx.dirName}/${rel.replace(/\\/g, "/")}`); continue }
+      writeFileSync(abs, content)
+      log(`${c.green("created")}   ${ctx.dirName}/${rel.replace(/\\/g, "/")}`)
+      created++
+    }
+
+    // Neither of these is a project file: snapshots are local render artifacts, and comments/
+    // mirrors rows the platform already owns (pushing it back would just duplicate the database).
+    const ignorePath = join(ctx.root, ".lecodesignore")
+    const ignoreLines = [ `${ctx.dirName}/.snapshots/`, `${ctx.dirName}/comments/` ]
+    const current = existsSync(ignorePath) ? readFileSync(ignorePath, "utf8") : ""
+    const present = new Set(current.split(/\r?\n/))
+    const missing = ignoreLines.filter((line) => !present.has(line))
+    if (missing.length) {
+      appendFileSync(ignorePath, (current && !current.endsWith("\n") ? "\n" : "") + missing.join("\n") + "\n")
+      for (const line of missing) log(`${c.green("ignored")}   ${line} (in .lecodesignore)`)
+    }
+
+    // Let Claude Code reach the running board over MCP (render/check/state/activity tools).
+    writeMcpConfig(ctx, flags.port)
+
+    // IDE types: materialize the SDK's import-free type surface + a design-scoped tsconfig so screens
+    // typecheck honestly (globals like UIScreen / UINode / UINodeChild resolve), standalone or in a
+    // project. .lecodes/ and tsconfig.json are skipped by the push scanner.
+    const wroteTypes = materializeTypesLocal(ctx.designDir)
+    writeTsconfig(ctx.designDir)
+    // Design-only compiler globals (assetIcon) that aren't in the shipped SDK type surface. Written
+    // alongside the bundle so the editor resolves them; rewritten every init to pick up upgrades.
+    mkdirSync(join(ctx.designDir, ".lecodes", "types"), { recursive: true })
+    writeFileSync(join(ctx.designDir, ".lecodes", "types", "design-macros.d.ts"), DESIGN_MACROS_DTS)
+    log(`${c.green("created")}   ${ctx.dirName}/tsconfig.json${wroteTypes ? ` + ${ctx.dirName}/.lecodes/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("")
+    log(created ? "Design canvas ready." : "Design canvas already initialized.")
+    log(`  ${c.bold("lecodes design")}                start the canvas (browser)`)
+    log(`  ${c.bold("lecodes design snapshot")}       render screens headless (for AI feedback)`)
+    log(`  Point Claude Code at ${c.bold(ctx.dirName + "/CLAUDE.md")} — it documents the conventions.`)
+  },
+})
+
+// ---- arrange -----------------------------------------------------------------------------------
+
+/**
+ * Auto-layout the flow graph in meta.json. Full arrange re-lays-out every screen and always
+ * applies (the board offers Undo; the structure-aware score delta is printed); `--new` places only
+ * screens that have no explicit `pos` yet and never moves the rest — the mode Claude uses after
+ * adding screens. If the dev server is running it picks up the meta.json change and refreshes.
+ */
+const arrange = defineCommand({
+  name: "arrange",
+  summary: "Auto-layout the flow graph in meta.json",
+  description: "Re-lays-out every screen and always applies (the board offers Undo; the layout score delta is printed, lower is better). A running dev server picks the change up and refreshes.",
+  flags: { ...dirFlag, new: bool("only place screens without a pos yet; never move the rest") },
+  examples: ["lecodes design arrange", "lecodes design arrange --new"],
+  run: async ({ flags }) => {
+    const ctx = getContext(flags.dir)
+    const designServer = await loadDesignServer(ctx)
+    const onlyNew = flags.new
+    const summary = designServer.arrangeDesign(ctx.designDir, { onlyNew })
+    const score = summary.score ? ` (score ${summary.score.before.toFixed(0)} → ${summary.score.after.toFixed(0)}, lower is better)` : ""
+    if (!summary.changed) {
+      log(onlyNew ? "No unplaced screens — nothing to arrange." : `Already in its arranged shape — nothing moved${score}.`)
+      return
+    }
+    log(`${c.green("✓")} ${onlyNew ? "Placed" : "Arranged"} ${summary.moved} screen${summary.moved === 1 ? "" : "s"} in ${ctx.dirName}/meta.json${score}.`)
+  },
+})
+
+// ---- share -------------------------------------------------------------------------------------
+
+/**
+ * Toggle the project's public design share link on the platform. The design must already be pushed
+ * (`lecodes push`) — this only flips the link, it doesn't upload anything. `--off` revokes it;
+ * `--comments on|off` flips whether link visitors may WRITE comments (reading is never affected).
+ */
+const share = defineCommand({
+  name: "share",
+  summary: "Turn the public share link on (or --off); --comments on|off gates visitors' comments",
+  description: "Needs a cloned project whose design is already pushed — this only flips the link, nothing is uploaded. Anyone with the link can view the mockups; the app code stays private.",
+  flags: {
+    ...dirFlag,
+    off: bool("revoke the share link"),
+    comments: str("let link visitors leave comments (existing ones stay readable either way)", { value: "<on|off>" }),
+  },
+  examples: ["lecodes design share", "lecodes design share --comments off", "lecodes design share --off"],
+  run: async ({ flags }) => {
+    const ctx = getContext(flags.dir)
+    if (!ctx.manifest) {
+      throw new CliError("`lecodes design share` needs a cloned project. Run it inside one, and push the design first (lecodes push).")
+    }
+    const { apiUrl, token } = session()
+    const uuid = ctx.manifest.uuid
+
+    if (flags.comments !== undefined) {
+      const value = flags.comments.trim().toLowerCase()
+      if (value !== "on" && value !== "off") {
+        throw new CliError(`--comments takes "on" or "off" (got "${flags.comments}").`)
+      }
+      const { commentsOpen } = await setDesignCommentsOpen(apiUrl, token, uuid, value === "on")
+      log(`${c.green("✓")} Comments on the shared design are ${commentsOpen ? "ON" : "OFF"}.`)
+      if (!commentsOpen) note("Existing comments stay readable — this only stops new ones.")
+      return
+    }
+
+    if (flags.off) {
+      await disableDesignShare(apiUrl, token, uuid)
+      log(`${c.green("✓")} Design sharing is off.`)
+      return
+    }
+    const res = await enableDesignShare(apiUrl, token, uuid)
+    log(`${c.bold("Design shared")} — anyone with this link can view the mockups (your app code stays private):`)
+    log(`  ${c.bold(res.url ?? "")}`)
+    log(`  ${c.dim(`comments: ${res.commentsOpen === false ? "off" : "on"}`)}`)
+    note('Turn it off with:  lecodes design share --off   ·   comments:  --comments off')
+  },
+})
+
+// ---- check -------------------------------------------------------------------------------------
+
+/**
+ * Static coherence check for a design folder — the terminal/CI sibling of the `check_concept` MCP
+ * tool. Reports the flow warnings meta.json/screens/spec.md already carry (broken edges, missing
+ * screens, edges targeting an undeclared `@state`, duplicate state names, dangling `[[spec]]` links)
+ * plus concept completeness (spec.md present? screens with no role?) and discovered states. Hard
+ * warnings exit non-zero; soft hints never fail the check. No compile, no render — fast, and needs
+ * only lecodes-design (not the renderer).
+ */
+const check = defineCommand({
+  name: "check",
+  summary: "Static coherence check: flow warnings, spec.md links, states, tab bars, open comments",
+  description: "The terminal / CI sibling of the board's check_concept tool. Hard warnings (broken edges, missing screens, undeclared states, dangling [[spec]] links) exit non-zero; hints and open comments never fail it. No compile, no render — needs only lecodes-design.",
+  flags: dirFlag,
+  examples: ["lecodes design check"],
+  run: async ({ flags }) => {
+    const ctx = getContext(flags.dir)
+    const designServer = await loadDesignServer(ctx)
+    const state = designServer.readDesignState(ctx.designDir)
+    const concept = designServer.conceptReport(ctx.designDir, state.screens)
+
+    if (state.warnings.length) {
+      log(c.bold(`Warnings (${state.warnings.length})`))
+      for (const w of state.warnings) log(`  ${c.yellow("!")} ${w}`)
+      log("")
+    }
+
+    log(c.bold("Concept"))
+    log(`  spec.md:  ${concept.hasSpec ? c.green("present") : c.dim("missing (optional)")}`)
+    if (concept.screenRefs.length) {
+      const resolved = concept.screenRefs.filter((r) => r.exists).length
+      log(`  [[links]]: ${resolved}/${concept.screenRefs.length} resolve`)
+    }
+    if (concept.screensWithoutRole.length) log(`  ${c.dim("no role:")} ${concept.screensWithoutRole.join(", ")}`)
+    log("")
+
+    // States: list multi-state screens (canonical highlighted) + soft "not discoverable" hints.
+    const stateful = state.screens.filter((s) => s.states.length > 1)
+    const undiscoverable = state.screens.filter((s) => s.statesWarning)
+    if (stateful.length || undiscoverable.length) {
+      log(c.bold("States"))
+      for (const s of stateful) {
+        log(`  ${s.id}: ${s.states.map((st) => st === s.canonical ? c.green(st) : st).join(", ")}`)
+      }
+      for (const s of undiscoverable) log(`  ${c.yellow("!")} ${s.id}: ${s.statesWarning}`)
+      log("")
+    }
+
+    // Tab bars: the source-discovered hubs (defineTabs) — tabs in order + how many screens sit on
+    // each bar. Problems (missing roots, unknown tabs, bar-implied edges) surface in Warnings above.
+    if (state.hubs.length) {
+      log(c.bold("Tab bars"))
+      for (const h of state.hubs) {
+        const mounted = Object.keys(h.lanes).length
+        log(`  ${h.name} (${h.file}): ${h.tabs.join(" · ")} — ${mounted} screen${mounted === 1 ? "" : "s"} on the bar`)
+      }
+      log("")
+    }
+
+    // Review comments: open threads are outstanding work on this design, so a coherence check that
+    // stayed silent about them would report "no problems" over a board full of unanswered feedback.
+    // They never fail the check — feedback isn't an error, and the file may be a stale mirror. An
+    // older lecodes-design without the comment store simply omits the section rather than failing.
+    const commentThreads = typeof designServer.listDesignComments === "function"
+      ? designServer.listDesignComments(ctx.designDir).threads
+      : []
+    if (commentThreads.length) {
+      const open = commentThreads.filter((t) => !t.resolved)
+      log(c.bold("Comments"))
+      log(`  ${open.length} open · ${commentThreads.length} total`)
+      for (const thread of open.slice(0, 5)) {
+        const where = thread.anchor.screen ?? "(board)"
+        log(`  ${c.dim(`#${thread.number}`)} ${where}  ${c.dim(firstLine(thread.messages[0]?.body ?? ""))}`)
+      }
+      if (open.length > 5) log(`  ${c.dim(`…and ${open.length - 5} more — lecodes design comments`)}`)
+      log("")
+    }
+
+    const hard = state.warnings.length
+    if (hard === 0) {
+      const n = state.screens.length
+      log(`${c.green("✓")} No coherence problems${n ? ` across ${n} screen${n === 1 ? "" : "s"}` : ""}.`)
+      return
+    }
+    log(`${c.red("✗")} ${hard} coherence warning${hard === 1 ? "" : "s"} — see above.`)
+    process.exitCode = 1
+  },
+})
+
+// ---- the tree ----------------------------------------------------------------------------------
+
+export default defineCommand({
+  name: "design",
+  summary: "LeCodes Design — a live canvas of screens for AI-driven prototyping",
+  description: "Bare `lecodes design` starts the canvas (= `design serve`). Needs the optional lecodes-design package (installed on first use); works inside a cloned project or standalone in any folder.\n\nThe design folder (default design/) holds one file per screen (screens/<id>.ts default-exports a UIScreen), shared tokens and components (shared/), and meta.json — the human-owned graph of positions, descriptions and edges. Screens compile per file through the normal project pipeline and render live in the browser and headless for AI feedback.",
+  flags: serveFlags,
+  commands: [serveCmd, init, snapshot, arrange, check, share, comments],
+  examples: ["lecodes design init && lecodes design", "lecodes design --port 4480 --no-open", "lecodes design snapshot --png"],
+  run: ({ flags }) => serve(flags),
+})

package/src/commands/design/snapshot.ts

@@ -0,0 +1,134 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { CliError, bool, c, defineCommand, log, logErr, note, str, warnErr } from "../../cli"
+import { compileDesignScreen } from "../../compile/designCompile"
+import { loadPeer } from "../../hosts/peerInstall"
+import { readMetaFrames } from "../../project/designMeta"
+import { dirFlag, getContext, type DesignServer } from "./context"
+
+/*
+ * `lecodes design snapshot [screen…]` — render design screens headless through lecodes-renderer,
+ * the way the board's MCP render_screen tool does, for AI feedback without a browser. One requested
+ * screen prints its JSON to stdout; anything else lands as files in <dir>/.snapshots/ (or --out-dir).
+ * States: `--state <s>` renders one named state of each screen, `--all-states` every discovered
+ * one (the canonical state also written unsuffixed, so `<id>.json` always exists).
+ */
+
+/** Screen ids from <designDir>/screens/*.ts. */
+const listScreens = (designDir: string): string[] => {
+  const dir = join(designDir, "screens")
+  if (!existsSync(dir)) return []
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".ts") && !f.startsWith("."))
+    .map((f) => f.slice(0, -3))
+    .sort()
+}
+
+export default defineCommand({
+  name: "snapshot",
+  summary: "Render design screens headless to JSON / PNG (needs lecodes-renderer)",
+  usage: "[screen…]",
+  description: "One screen → its JSON on stdout; otherwise one file per screen in <dir>/.snapshots/ (<id>.json, <id>@<state>.json, PNGs with --png). --state and --all-states need lecodes-design to discover a screen's states from its source. A stuck screen (runaway loop) is killed after 120 s.",
+  flags: {
+    ...dirFlag,
+    state: str("render this state of every (state) => UIScreen screen", { value: "<name>" }),
+    "all-states": bool("render every discovered state of each screen"),
+    png: str("also rasterize PNGs at 2× (needs @napi-rs/canvas); a value is accepted and ignored", { optional: true, value: "[file]" }),
+    "out-dir": str("output folder (default <dir>/.snapshots)", { value: "<dir>" }),
+    logs: bool("forward the screens' console output (to stderr)"),
+  },
+  examples: [
+    "lecodes design snapshot",
+    "lecodes design snapshot login",
+    "lecodes design snapshot --all-states --png",
+    "lecodes design snapshot login --state error",
+  ],
+  run: async ({ args, flags }) => {
+    const ctx = getContext(flags.dir)
+    const all = listScreens(ctx.designDir)
+    if (all.length === 0) throw new CliError(`No screens in ${ctx.dirName}/screens/ — run "lecodes design init" first.`)
+    for (const id of args) {
+      if (!all.includes(id)) throw new CliError(`No screen "${id}" (have: ${all.join(", ")}).`)
+    }
+    const targets = args.length ? args : all
+
+    const stateFlag = flags.state
+    const allStates = flags["all-states"]
+    if (stateFlag !== undefined && allStates) throw new CliError("Use either --state <name> or --all-states, not both.")
+
+    const renderer = await loadPeer<typeof import("lecodes-renderer/headless")>("lecodes-renderer", "headless", { for: "lecodes design render" })
+
+    // Enumerating / validating states parses the screen source — that discovery lives in the design
+    // package. The canonical-only path (no flag) needs no discovery, so base snapshot stays lean.
+    let discover: ((source: string) => { states: string[], canonical: string }) | null = null
+    if (stateFlag !== undefined || allStates) {
+      const ds = await loadPeer<DesignServer>("lecodes-design", "server", { for: "lecodes design render --state" })
+      discover = (src) => { const d = ds.discoverScreenStates(src); return { states: d.states, canonical: d.canonical } }
+    }
+
+    // A stuck screen (runaway loop) shouldn't hang the CLI forever.
+    const killer = setTimeout(() => {
+      warnErr("Snapshot timed out after 120s.")
+      process.exit(1)
+    }, 120000)
+    killer.unref?.()
+
+    const png = flags.png !== undefined
+    const frames = readMetaFrames(ctx.designDir)
+    const outDir = flags["out-dir"] ?? join(ctx.designDir, ".snapshots")
+    const single = targets.length === 1 && args.length === 1 && !png && !allStates && !flags["out-dir"]
+    const onConsole = flags.logs
+      ? (level: string, text: string) => logErr(`${c.dim(`[${level}]`)} ${text}`)
+      : undefined
+
+    if (!single) mkdirSync(outDir, { recursive: true })
+
+    for (const id of targets) {
+      const [ width, height ] = frames.screens[id]?.size ?? frames.defaultSize
+
+      // What to render, and the file base(s) for each. `undefined` state = a bare (canonical) render.
+      // The canonical state also writes the unsuffixed `<id>` for backward compatibility.
+      let plan: { state?: string, bases: string[] }[] = [{ state: undefined, bases: [id] }]
+      if (discover) {
+        const { states, canonical } = discover(readFileSync(join(ctx.designDir, "screens", `${id}.ts`), "utf8"))
+        if (stateFlag !== undefined) {
+          if (!states.includes(stateFlag)) {
+            if (args.length === 1) throw new CliError(`No state "${stateFlag}" on ${id} (has: ${states.join(", ")}).`)
+            warnErr(`${id}: no state "${stateFlag}" (has: ${states.join(", ")}) — skipped.`)
+            continue
+          }
+          plan = [{ state: stateFlag, bases: [`${id}@${stateFlag}`] }]
+        } else {
+          plan = states.map((st) => ({ state: st, bases: st === canonical ? [`${id}@${st}`, id] : [`${id}@${st}`] }))
+        }
+      }
+
+      for (const { state, bases } of plan) {
+        const tag = state ? `${id}@${state}` : id
+        note(`Rendering ${tag}…`)
+        const js = await compileDesignScreen({
+          root: ctx.root, manifest: ctx.manifest, name: ctx.name, designDir: ctx.designDir, designKey: ctx.designKey, screenId: id, state, assets: "disk",
+        })
+        const result = await renderer.renderToJson(js, { width, height, localAssets: true, onConsole })
+        for (const w of result.warnings) warnErr(`${tag}: ${w}`)
+
+        if (single) {
+          const text = result.text.endsWith("\n") ? result.text : result.text + "\n"
+          process.stdout.write(text)
+          return
+        }
+        const pngResult = png ? await renderer.renderToPng(js, { width, height, localAssets: true, scale: 2, onConsole }) : null
+        if (pngResult) for (const w of pngResult.warnings) warnErr(`${tag}: ${w}`)
+
+        for (const base of bases) {
+          writeFileSync(join(outDir, `${base}.json`), result.text)
+          log(`${c.green("✓")} ${tag} → ${join(outDir, `${base}.json`)}`)
+          if (pngResult) {
+            writeFileSync(join(outDir, `${base}.png`), pngResult.png)
+            log(`${c.green("✓")} ${tag} → ${join(outDir, `${base}.png`)}`)
+          }
+        }
+      }
+    }
+  },
+})

package/src/commands/{designTemplates.ts → design/templates.ts}

@@ -3,9 +3,10 @@
  * platform editor's "Create design" button. Imported by a RELATIVE path through the package's
  * node_modules link (not as `lecodes-design/templates`) on purpose: the CLI build externalizes the
  * `lecodes-design` package (it's an optional runtime install for `design serve`), but `init` must
- * work without it — a relative import gets bundled into the binary like any local module. The link
- * is the `link:lecodes-design` dev dependency (see the root `bun run link`). */
+ * work without it — a relative import gets bundled into the binary like any local module. The
+ * package comes from the `lecodes-design` dev dependency (an npm range; `bun link lecodes-design`
+ * swaps in a sibling checkout). */
 
 export {
   META_JSON, META_JSON_DESKTOP, SPEC_MD, TOKENS_TS, TABS_TS, HOME_SCREEN_TS, CLAUDE_MD, DESIGN_MACROS_DTS, README_HINT,
-} from "../../node_modules/lecodes-design/src/templates"
+} from "../../../node_modules/lecodes-design/src/templates"