lecodes-cli 0.20.2 → 2.0.0

package/src/commands/{types.ts → update/types.ts}

@@ -1,54 +1,63 @@
 import { resolve } from "node:path"
-import { getTypes } from "../api"
-import { DEFAULT_API, loadConfig, normalizeApiUrl } from "../config"
-import { findProjectRoot, LECODES_DIR } from "../manifest"
+import { getTypes } from "../../platform/api"
+import { DEFAULT_API, loadConfig, normalizeApiUrl } from "../../platform/config"
+import { findProjectRoot, LECODES_DIR } from "../../project/manifest"
 import {
   bundleHash, readLocalTypeBundle, readProjectTypeBundle, writeTsconfig, writeTypeBundle,
   type TypeBundle,
-} from "../types"
-import { CliError, c, flagBool, flagStr, log, note, success, warn, type Args } from "../util"
+} from "../../project/types"
+import { CliError, c, log, note, success, warn } from "../../cli"
 
 /*
- * The types step of `lecodes update` (formerly `lecodes types [dir]`) — re-materialize the IDE type surface (<root>/.lecodes/types/ + tsconfig).
+ * The types step of `lecodes update` (formerly `lecodes types [dir]`) — re-materialize the IDE type
+ * surface (<root>/.lecodes/types/ + tsconfig).
  *
  * Every project gets these types once, at scaffold time: `clone`/`create`/`pull` fetch them from
  * GET /api/types (the deployed runtime's surface), while `init` and `design` — which run with no
  * server and no login — write the bundle vendored into the CLI at publish time. Neither source
- * refreshes on its own, so a local project's types age with the CLI binary that made it. This
- * command is the refresh: server by default (newest SDK the platform actually runs), `--local` for
- * the CLI's own copy, `--check` to only report drift (non-zero exit when stale).
+ * refreshes on its own, so a local project's types age with the CLI binary that made it. This step
+ * is the refresh: server by default (newest SDK the platform actually runs), `local` for the CLI's
+ * own copy, `check` to only report drift (a CliError when stale).
  *
  * IDE-only: the compiler reads the SDK sources vendored in runtime/sdk, never .lecodes/types. When
- * the two sources disagree the command says so — types promising APIs this CLI can't compile is
+ * the two sources disagree the step says so — types promising APIs this CLI can't compile is
  * exactly the confusing case worth naming out loud.
  */
 
+export type RefreshTypesOptions = {
+  /** The project folder (default: the project root above the cwd, else the cwd). */
+  dir?: string
+  /** The bundle vendored in this CLI instead of the server's. */
+  local: boolean
+  /** Only report drift — write nothing, throw when stale. */
+  check: boolean
+  /** API origin for the server bundle (default: the configured one). */
+  api?: string
+}
+
 const label = (bundle: TypeBundle) => `${Object.keys(bundle).length} file(s)`
 
-export const types = async (args: Args) => {
-  const dirArg = args._[0]
-  const root = dirArg ? resolve(dirArg) : (() => {
+export const refreshTypes = async (opts: RefreshTypesOptions): Promise<void> => {
+  const root = opts.dir ? resolve(opts.dir) : (() => {
     try { return findProjectRoot(process.cwd()) } catch { return process.cwd() }
   })()
 
-  const useLocal = flagBool(args, "local")
-  const checkOnly = flagBool(args, "check")
   const local = readLocalTypeBundle()
 
   // ---- pick the source ----
   let bundle: TypeBundle | null = null
   let source = ""
-  if (useLocal) {
+  if (opts.local) {
     if (!local) throw new CliError("This CLI ships no vendored type bundle — drop --local to fetch them from the server.")
     bundle = local
     source = "the CLI's bundled SDK"
   } else {
-    const apiUrl = normalizeApiUrl(flagStr(args, "api") ?? loadConfig().apiUrl ?? DEFAULT_API)
+    const apiUrl = normalizeApiUrl(opts.api ?? loadConfig().apiUrl ?? DEFAULT_API)
     try {
       bundle = await getTypes(apiUrl)
       source = apiUrl
     } catch (e) {
-      if (!local || checkOnly) throw e
+      if (!local || opts.check) throw e
       warn(`${(e as Error).message}`)
       bundle = local
       source = "the CLI's bundled SDK (server unreachable)"
@@ -56,10 +65,10 @@ export const types = async (args: Args) => {
   }
   log(`${c.green("source")}    ${source} — ${label(bundle)}`)
 
-  // ---- report drift, write unless --check ----
+  // ---- report drift, write unless check ----
   const onDisk = readProjectTypeBundle(root)
   const same = bundleHash(onDisk) === bundleHash(bundle)
-  if (checkOnly) {
+  if (opts.check) {
     if (Object.keys(onDisk).length === 0) throw new CliError(`No types in ${LECODES_DIR}/types/ — run \`lecodes update\`.`)
     if (!same) throw new CliError(`Types are out of date (${label(onDisk)} on disk) — run \`lecodes update\`.`)
     success(`Types are up to date (${label(onDisk)}).`)
@@ -77,11 +86,11 @@ export const types = async (args: Args) => {
 
   // The compiler uses the SDK vendored in this CLI, not these declarations — worth saying when the
   // server's surface is a different one, since that gap shows up as "autocompletes but won't build".
-  if (!useLocal && local && bundleHash(local) !== bundleHash(bundle)) {
+  if (!opts.local && local && bundleHash(local) !== bundleHash(bundle)) {
     warn("The server's SDK surface differs from the one this CLI compiles with — if something autocompletes but fails to compile, update the CLI (`npm install -g lecodes-cli@latest`) or re-run with --local.")
   }
 
   log("")
   success(stats.added + stats.updated + stats.removed > 0 ? "Types synced." : "Types already current.")
-  if (!dirArg) note("Reload the TypeScript server in your editor to pick them up.")
+  if (!opts.dir) note("Reload the TypeScript server in your editor to pick them up.")
 }

package/src/compile/collect.ts

@@ -1,10 +1,10 @@
 import { readFileSync } from "node:fs"
 import { basename } from "node:path"
-import type { Project } from "../api"
-import type { Manifest } from "../manifest"
-import { classifyKind, scanLocal } from "../localFiles"
-import { loadIgnore } from "../ignore"
-import { buildPaths } from "../project"
+import type { Project } from "../platform/api"
+import type { Manifest } from "../project/manifest"
+import { classifyKind, scanLocal } from "../project/localFiles"
+import { loadIgnore } from "../project/ignore"
+import { buildPaths } from "../project/materialize"
 import type { CompileEntry } from "./projectCompile"
 
 /*

package/src/compile/collectLocal.ts

@@ -1,8 +1,8 @@
 import { readFileSync } from "node:fs"
 import { basename } from "node:path"
-import type { Manifest } from "../manifest"
-import { classifyKind, scanLocal } from "../localFiles"
-import { loadIgnore } from "../ignore"
+import type { Manifest } from "../project/manifest"
+import { classifyKind, scanLocal } from "../project/localFiles"
+import { loadIgnore } from "../project/ignore"
 import type { CompileEntry } from "./projectCompile"
 
 /*

package/src/compile/designCompile.ts

@@ -1,8 +1,8 @@
 import { readFileSync } from "node:fs"
 import { basename } from "node:path"
-import type { Manifest } from "../manifest"
-import { classifyKind, scanLocal } from "../localFiles"
-import { loadIgnore } from "../ignore"
+import type { Manifest } from "../project/manifest"
+import { classifyKind, scanLocal } from "../project/localFiles"
+import { loadIgnore } from "../project/ignore"
 import { compileProject, type CompileEntry } from "./projectCompile"
 import { applyAssetIcons } from "./assetIcons"
 import { applyProjectFonts } from "./fonts"
@@ -18,7 +18,7 @@ import { applyProjectFonts } from "./fonts"
 
 export type DesignAssetMode = "server" | "disk"
 
-// Must match lecodes-renderer's LOCAL_ASSET_SCHEME (headless/index.ts) — same as `lecodes render`.
+// Must match lecodes-headless's LOCAL_ASSET_SCHEME (headless/index.ts) — same as `lecodes render`.
 const LOCAL_ASSET_SCHEME = "lecodesfile://"
 
 export const compileDesignScreen = async (opts: {

package/src/compile/headlessBundle.ts

@@ -1,13 +1,13 @@
-import { getProject } from "../api"
-import { loadConfig, requireApiUrl, requireToken } from "../config"
-import { findProjectRoot, readManifest, type Manifest } from "../manifest"
+import { getProject } from "../platform/api"
+import { loadConfig, requireApiUrl, requireToken } from "../platform/config"
+import { findProjectRoot, readManifest, type Manifest } from "../project/manifest"
 import { collectEntries } from "./collect"
 import { collectLocalEntries } from "./collectLocal"
 import { ambiguousEntryWarning, compileProject } from "./projectCompile"
 import { applyProjectFonts } from "./fonts"
 import { applyAppAssetIcons } from "./assetIcons"
 import type { ScreenTarget } from "./screenEntry"
-import { flagBool, flagStr, note, type Args } from "../util"
+import { note } from "../cli"
 
 /*
  * Compile the project into the iife bundle the headless renderer runs — shared by `lecodes render`
@@ -23,7 +23,7 @@ import { flagBool, flagStr, note, type Args } from "../util"
  */
 
 // URL scheme emitted for a local project's resources so the renderer reads them off disk. Must match
-// lecodes-renderer's LOCAL_ASSET_SCHEME (headless/runProject.ts).
+// lecodes-headless's LOCAL_ASSET_SCHEME (headless/runProject.ts).
 export const LOCAL_ASSET_SCHEME = "lecodesfile://"
 
 export type HeadlessBundle = {
@@ -36,8 +36,12 @@ export type HeadlessBundle = {
   useLocalAssets: boolean
 }
 
-/** Compile the local project for a headless run (honors --entry / --public-url / --remote-assets). */
-export const compileHeadlessBundle = async (args: Args, opts: { screen?: ScreenTarget } = {}): Promise<HeadlessBundle> => {
+/** What a headless compile honours: `--entry` / `--public-url` / `--remote-assets` / `--wait-network`,
+ *  and the screen module a `render <file>` named. */
+export type HeadlessOptions = { entry?: string, publicUrl?: string, remoteAssets?: boolean, waitNetwork?: boolean, screen?: ScreenTarget }
+
+/** Compile the local project for a headless run. */
+export const compileHeadlessBundle = async (opts: HeadlessOptions = {}): Promise<HeadlessBundle> => {
   let root: string
   let manifest: Manifest | null
   try {
@@ -48,9 +52,9 @@ export const compileHeadlessBundle = async (args: Args, opts: { screen?: ScreenT
     manifest = null
   }
 
-  const publicUrlFlag = flagStr(args, "public-url")
+  const publicUrlFlag = opts.publicUrl
   // A local (server-less) project has no remote asset URLs — it always reads from disk.
-  const useLocalAssets = manifest ? (!publicUrlFlag && !flagBool(args, "remote-assets")) : true
+  const useLocalAssets = manifest ? (!publicUrlFlag && !opts.remoteAssets) : true
 
   let entries
   let warnings: string[]
@@ -73,7 +77,7 @@ export const compileHeadlessBundle = async (args: Args, opts: { screen?: ScreenT
     ;({ entries, warnings } = collectLocalEntries(root, null, ""))
     name = root.split(/[\\/]/).pop() ?? "project"
     publicUrl = LOCAL_ASSET_SCHEME
-    if (flagBool(args, "remote-assets") || publicUrlFlag) {
+    if (opts.remoteAssets || publicUrlFlag) {
       warnings.push("This is a local project (no server) — assets always load from the working tree.")
     }
   }
@@ -103,7 +107,7 @@ export const compileHeadlessBundle = async (args: Args, opts: { screen?: ScreenT
   await applyAppAssetIcons(compileEntries)
 
   note("Compiling…")
-  const entryFlag = opts.screen?.entryPath ?? flagStr(args, "entry")
+  const entryFlag = opts.screen?.entryPath ?? opts.entry
   if (!entryFlag) {
     const ambiguous = ambiguousEntryWarning(compileEntries)
     if (ambiguous) warnings.push(ambiguous)
@@ -121,7 +125,7 @@ export const compileHeadlessBundle = async (args: Args, opts: { screen?: ScreenT
   }
   // With --remote-assets, 2D textures come from the network; without --wait-network they resolve empty
   // and sprites render as flat placeholders. Local assets (default) load from disk, so no hint needed.
-  if (js.includes("_creator2d") && !useLocalAssets && !flagBool(args, "wait-network")) {
+  if (js.includes("_creator2d") && !useLocalAssets && !opts.waitNetwork) {
     warnings.push("2D scene detected: sprite textures load over the network — add --wait-network to include them (else sprites render as flat placeholders).")
   }
 

package/src/compile/nativeStack.ts

@@ -1,4 +1,4 @@
-import { extractInlineSourceMap, mapNamedFileStack } from "lecodes-viewer-lite/src/sourcemapError"
+import { extractInlineSourceMap, mapNamedFileStack } from "lecodes-web-shared/src/sourcemapError"
 
 /*
  * De-minify native (QuickJS) stack traces in a desktop host's output.

package/src/compile/projectCompile.ts

@@ -1,16 +1,16 @@
 import { existsSync } from "node:fs"
 import { createRequire } from "node:module"
 import { dirname, join } from "node:path"
-import type { FileKind } from "../manifest"
-import { distRoot } from "../distRoot"
-import { compileProject as sdkCompileProject, detectEntry, scanModulesChisel, ENTRY_CONVENTION } from "lecodes-sdk/compile"
+import type { FileKind } from "../project/manifest"
+import { distRoot } from "../hosts/distRoot"
+import { compileProject as sdkCompileProject, detectEntry, scanModulesChisel, localAssetNames, ENTRY_CONVENTION } from "lecodes-sdk/compile"
 
 // Every project compiles through the SDK's one import-free compiler, which bundles with chisel (the
 // Rust method-granular bundler, @letary/chisel) — the only bundler. The SDK resolves the chisel
 // binary itself; here we just hand it an explicit path when the @letary/chisel package is present,
 // and point it at the SDK *source* tree chisel compiles from:
 //   1. the `lecodes-sdk` package when it resolves — the npm install's dependency, or in the core
-//      workspace the live packages/sdk (so an SDK edit is picked up with no re-vendoring);
+//      workspace the live sdk (so an SDK edit is picked up with no re-vendoring);
 //   2. else the copy vendored beside the standalone binary (runtime/sdk/, scripts/vendor-runtime.ts
 //      --sdk) — the binary has no node_modules.
 const resolveSdkInject = (): string | null => {
@@ -81,6 +81,9 @@ export type CompileOptions = {
   /** Editor compile: the `EDITOR` global compiles to `true` and `*.editor.ts` plugin files are
    *  bundled in (scene-editor bundles). Default false — production compiles skip them. */
   editor?: boolean
+  /** What the compile has to say that is not an error (a plugin the app uses and app.json does not
+   *  list). */
+  onWarning?: (message: string) => void
 }
 
 /** A warning when auto-detection has several import-graph roots and no main.ts to settle it —
@@ -106,4 +109,9 @@ export const compileProject = (opts: CompileOptions): Promise<string> =>
     minify: opts.minify,
     sourcemap: opts.sourcemap,
     editor: opts.editor,
+    onWarning: opts.onWarning,
   })
+
+/** Re-exported so the CALLERS that stage files next to the bundle name them the way the bundle asks
+ *  for them (see localAssetNames in the SDK compile — two packs shipping SM_Sign_01.glb). */
+export { localAssetNames }

package/src/compile/sceneCompile.ts

@@ -1,11 +1,10 @@
 import { createHash } from "node:crypto"
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { join } from "node:path"
-import type { Manifest } from "../manifest"
-import { scanLocal } from "../localFiles"
-import { loadIgnore } from "../ignore"
-import { distRoot } from "../distRoot"
-import { CliError, warnErr } from "../util"
+import type { Manifest } from "../project/manifest"
+import { scanLocal } from "../project/localFiles"
+import { loadIgnore } from "../project/ignore"
+import { warnErr } from "../cli"
 import { compileProject, type CompileEntry } from "./projectCompile"
 import { applyLocalShaders, shadersCacheDir } from "./shaders"
 
@@ -14,8 +13,9 @@ import { applyLocalShaders, shadersCacheDir } from "./shaders"
  * point (the platform backend and the standalone playground are the other two). Reads the project
  * off disk, composes the edit-mode bundle with the SDK's shared `sceneEditorEntries`, and drives it
  * through the CLI's chisel + vendored-SDK pipeline. Deliberately mirrors the playground's in-process
- * closure (scene-editor/src/server/inProcess.ts) field-for-field so every host emits the same
- * bundle — only the file source (disk vs. the folder) and the harness source differ.
+ * closure (lecodes-3d-editor's src/server/inProcess.ts) field-for-field so every host emits the same
+ * bundle — only the file source differs. The harness is the editor's: the caller hands in
+ * `sceneHarness()` of the editor package it serves the UI from, so the two are one version.
  *
  *   publicUrl ""  +  resource fileSrc "/project/<rel>"  → the scene server's /project/* mount.
  *   minify:false  — mangling erases class names the inspector matches aspect schemas by.
@@ -29,22 +29,6 @@ const TEXT_EXT = /\.(ts|js|json|svg|txt|md)$/i
 /** Strip scanLocal's leading-slash key convention ("/city.scene.ts" → "city.scene.ts"). */
 const rel = (key: string) => key.replace(/^\//, "")
 
-/**
- * Resolve the scene-editor harness sources (packages/projects/src/scene-editor):
- *   LECODES_SCENE_HARNESS_DIR env → the in-repo dir (monorepo dev), both via the SDK helper, else
- *   the JSON snapshot vendored into the CLI at publish time (runtime/scene-harness.json).
- */
-const resolveHarness = (loadSceneHarness: (dir?: string) => Record<string, string>): Record<string, string> => {
-  const inRepo = join(distRoot, "..", "projects", "src", "scene-editor")
-  try {
-    return loadSceneHarness(existsSync(inRepo) ? inRepo : undefined)
-  } catch {
-    const vendored = join(distRoot, "runtime", "scene-harness.json")
-    if (existsSync(vendored)) return JSON.parse(readFileSync(vendored, "utf8")) as Record<string, string>
-    throw new CliError("scene-editor harness sources not found — reinstall the CLI or set LECODES_SCENE_HARNESS_DIR.")
-  }
-}
-
 export const compileSceneEditor = async (opts: {
   root: string
   /** Null in standalone mode (a bare folder, no cloned project). */
@@ -53,9 +37,11 @@ export const compileSceneEditor = async (opts: {
   name: string
   /** Project path of the scene file as the editor sends it ("./city.scene.ts"). */
   scenePath: string
+  /** The editor's harness, module name → source (`sceneHarness()` of lecodes-3d-editor/server). */
+  harness: Record<string, string>
 }): Promise<{ js: string | null, error?: string }> => {
   const { root, scenePath } = opts
-  const { loadSceneHarness, sceneEditorEntries, SCENE_ENTRY_PATH } = await import("lecodes-sdk/compile")
+  const { sceneEditorEntries, sceneImportsOf, SCENE_ENTRY_PATH } = await import("lecodes-sdk/compile")
 
   const entries: CompileEntry[] = []
   const scan = scanLocal(root, { ignore: loadIgnore(root), tracked: new Set(Object.keys(opts.manifest?.files ?? {})) })
@@ -96,10 +82,12 @@ export const compileSceneEditor = async (opts: {
   }
 
   const scene = scenePath.startsWith("./") ? scenePath : "./" + rel(scenePath)
-  if (!entries.some((e) => e.path === scene && e.type === "text")) {
+  const sceneEntry = entries.find((e) => e.path === scene && e.type === "text")
+  if (!sceneEntry) {
     return { js: null, error: `Scene file not found: ${scene}` }
   }
-  entries.push(...sceneEditorEntries(scene, resolveHarness(loadSceneHarness), entries.map((e) => e.path)))
+  const paths = entries.map((e) => e.path)
+  entries.push(...sceneEditorEntries(scene, opts.harness, paths, sceneImportsOf(sceneEntry.text ?? "", scene, paths)))
 
   try {
     const js = await compileProject({

package/src/compile/screenEntry.ts

@@ -1,127 +1,123 @@
-import { existsSync, readFileSync, statSync } from "node:fs"
-import { isAbsolute, join, relative, resolve } from "node:path"
-import { screenFrame } from "../designMeta"
-import { CliError, flagStr, toKey, type Args } from "../util"
-import type { CompileEntry } from "./projectCompile"
-
-/*
- * Rendering ONE screen module instead of the whole app — `lecodes render <file>` (and
- * `--desktop`). A design screen (`design/screens/login.ts`) never boots itself: it default-exports
- * a `UIScreen`, or a `(state) => UIScreen` function for its states, and the design board / snapshot
- * supply the `.open()`. This builds the same virtual entry for the normal project pipeline, so any
- * file written that way — inside design/ or not — renders with the full `lecodes render` flag set
- * (--png/--clip/--script/--device/…) against the project's real imports and assets.
- *
- * Kept in step with compile/designCompile.ts, which does the same wrapping per screen for the board.
- */
-
-/** Extensions a screen module may carry (so `render design/screens/login` works too). */
-const SCREEN_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mjs"]
-
-/** Where the generated entry lives — the project root, so its import specifier is the screen's
- *  own project key ("./design/screens/login"). Leading dot: never a real project file. */
-const SCREEN_ENTRY_PATH = "/.screen-entry.ts"
-
-/** The design folder a bare screen id (`lecodes render login`) is looked up in. */
-const DEFAULT_DESIGN_DIR = "design"
-
-export type ScreenTarget = {
-  /** The virtual entry module — hand it to the compiler alongside the project's own entries. */
-  entry: CompileEntry
-  /** Path of that entry, for `entryOverride`. */
-  entryPath: string
-  /** The board frame from the design folder's meta.json, when this IS a design screen. */
-  frame?: [number, number]
-  /** How the screen is named in progress notes ("design/screens/login.ts", "login@empty"). */
-  label: string
-}
-
-/** `lecodes render <file|screen-id>` — the positional a screen render is asked for by. */
-const screenArg = (args: Args): string | undefined => args._[0]
-
-/** Whether the argument names a path at all (vs a bare screen id). */
-const hasSeparator = (file: string) => file.includes("/") || file.includes("\\")
-
-/** Find the screen file: a path (with or without extension), or a bare id resolved against the
- *  design folder's screens/ (`lecodes render login`, honoring --dir). */
-const findScreenFile = (root: string, file: string, dirFlag: string | undefined): string => {
-  const candidates = [resolve(process.cwd(), file)]
-  if (!hasSeparator(file)) {
-    candidates.push(join(root, (dirFlag ?? DEFAULT_DESIGN_DIR).replace(/[/\\]+$/, ""), "screens", file))
-  }
-  for (const base of candidates) {
-    if (existsSync(base) && statSync(base).isFile()) return base
-    for (const ext of SCREEN_EXTS) if (existsSync(base + ext)) return base + ext
-  }
-  throw new CliError(
-    `No screen file at "${file}".` +
-    (hasSeparator(file) ? "" : ` Pass a path, or a screen id that exists in ${dirFlag ?? DEFAULT_DESIGN_DIR}/screens/.`))
-}
-
-/** The design folder a screen file belongs to ("<root>/design" for "/design/screens/login.ts"),
- *  or null when it isn't laid out as a design screen. */
-const designDirOf = (root: string, key: string): { dir: string, id: string } | null => {
-  const m = /^\/(.*)screens\/([^/]+)\.[^./]+$/.exec(key)
-  if (!m) return null
-  const dir = join(root, m[1])
-  return existsSync(join(dir, "meta.json")) ? { dir, id: m[2] } : null
-}
-
-/**
- * Resolve `<file>` into the virtual entry that opens its default export.
- * `state` picks the branch of a `(state) => UIScreen` screen (ignored by a value export).
- */
-const resolveScreenTarget = (
-  root: string, file: string, opts: { state?: string, dir?: string } = {},
-): ScreenTarget => {
-  const abs = findScreenFile(root, file, opts.dir)
-  const rel = relative(root, abs)
-  if (rel.startsWith("..") || isAbsolute(rel)) {
-    throw new CliError(
-      `"${file}" is outside the project (${root}) — a screen renders as part of its project, so its ` +
-      `imports and asset() files resolve from the same tree.`)
-  }
-  const key = toKey(rel)
-
-  // A file with no default export compiles to an empty render; say so here instead.
-  if (!/^\s*export\s+default\b/m.test(readFileSync(abs, "utf8"))) {
-    throw new CliError(
-      `${key.slice(1)} has no default export. A screen file ends with ` +
-      `\`export default UIScreen([...])\` — or \`export default (state) => UIScreen([...])\` for screen states.`)
-  }
-
-  // Same wrapper the design board compiles (designCompile.ts): a function export is invoked with the
-  // chosen state (a bare call uses the parameter's default = the canonical state), a value is used
-  // as-is, and either way the screen is opened so the runtime has something to render.
-  const invoke = opts.state !== undefined ? `screen(${JSON.stringify(opts.state)})` : "screen()"
-  const spec = "." + key.replace(/\.[^./]+$/, "")
-  const design = designDirOf(root, key)
-  return {
-    entryPath: SCREEN_ENTRY_PATH,
-    entry: {
-      path: SCREEN_ENTRY_PATH,
-      type: "text",
-      text: `import screen from ${JSON.stringify(spec)}\n`
-        + `const __screen = typeof screen === "function" ? ${invoke} : screen\n`
-        + `__screen.open()\n`,
-    },
-    frame: design ? screenFrame(design.dir, design.id) : undefined,
-    label: (design ? design.id : key.slice(1)) + (opts.state !== undefined ? `@${opts.state}` : ""),
-  }
-}
-
-/** Read the screen target off the CLI args, or undefined when no screen was named. Rejects the
- *  flag combinations that would fight over the entrypoint. */
-export const screenTargetFromArgs = (root: string, args: Args): ScreenTarget | undefined => {
-  const file = screenArg(args)
-  if (file === undefined) {
-    if (flagStr(args, "state") !== undefined) {
-      throw new CliError("--state picks a screen's state — name the screen file too: lecodes render <file> --state <name>")
-    }
-    return undefined
-  }
-  if (flagStr(args, "entry") !== undefined) {
-    throw new CliError("Use either a screen file or --entry, not both — each names the module to compile from.")
-  }
-  return resolveScreenTarget(root, file, { state: flagStr(args, "state"), dir: flagStr(args, "dir") })
-}
+import { existsSync, readFileSync, statSync } from "node:fs"
+import { isAbsolute, join, relative, resolve } from "node:path"
+import { screenFrame } from "../project/designMeta"
+import { CliError } from "../cli"
+import { toKey } from "../project/paths"
+import type { CompileEntry } from "./projectCompile"
+
+/*
+ * Rendering ONE screen module instead of the whole app — `lecodes render <file>` (and
+ * `--desktop`). A design screen (`design/screens/login.ts`) never boots itself: it default-exports
+ * a `UIScreen`, or a `(state) => UIScreen` function for its states, and the design board / snapshot
+ * supply the `.open()`. This builds the same virtual entry for the normal project pipeline, so any
+ * file written that way — inside design/ or not — renders with the full `lecodes render` flag set
+ * (--png/--clip/--script/--device/…) against the project's real imports and assets.
+ *
+ * Kept in step with compile/designCompile.ts, which does the same wrapping per screen for the board.
+ */
+
+/** Extensions a screen module may carry (so `render design/screens/login` works too). */
+const SCREEN_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mjs"]
+
+/** Where the generated entry lives — the project root, so its import specifier is the screen's
+ *  own project key ("./design/screens/login"). Leading dot: never a real project file. */
+const SCREEN_ENTRY_PATH = "/.screen-entry.ts"
+
+/** The design folder a bare screen id (`lecodes render login`) is looked up in. */
+const DEFAULT_DESIGN_DIR = "design"
+
+export type ScreenTarget = {
+  /** The virtual entry module — hand it to the compiler alongside the project's own entries. */
+  entry: CompileEntry
+  /** Path of that entry, for `entryOverride`. */
+  entryPath: string
+  /** The board frame from the design folder's meta.json, when this IS a design screen. */
+  frame?: [number, number]
+  /** How the screen is named in progress notes ("design/screens/login.ts", "login@empty"). */
+  label: string
+}
+
+/** `lecodes render <file|screen-id>` — the positional a screen render is asked for by. */
+
+/** Whether the argument names a path at all (vs a bare screen id). */
+const hasSeparator = (file: string) => file.includes("/") || file.includes("\\")
+
+/** Find the screen file: a path (with or without extension), or a bare id resolved against the
+ *  design folder's screens/ (`lecodes render login`, honoring --dir). */
+const findScreenFile = (root: string, file: string, dirFlag: string | undefined): string => {
+  const candidates = [resolve(process.cwd(), file)]
+  if (!hasSeparator(file)) {
+    candidates.push(join(root, (dirFlag ?? DEFAULT_DESIGN_DIR).replace(/[/\\]+$/, ""), "screens", file))
+  }
+  for (const base of candidates) {
+    if (existsSync(base) && statSync(base).isFile()) return base
+    for (const ext of SCREEN_EXTS) if (existsSync(base + ext)) return base + ext
+  }
+  throw new CliError(
+    `No screen file at "${file}".` +
+    (hasSeparator(file) ? "" : ` Pass a path, or a screen id that exists in ${dirFlag ?? DEFAULT_DESIGN_DIR}/screens/.`))
+}
+
+/** The design folder a screen file belongs to ("<root>/design" for "/design/screens/login.ts"),
+ *  or null when it isn't laid out as a design screen. */
+const designDirOf = (root: string, key: string): { dir: string, id: string } | null => {
+  const m = /^\/(.*)screens\/([^/]+)\.[^./]+$/.exec(key)
+  if (!m) return null
+  const dir = join(root, m[1])
+  return existsSync(join(dir, "meta.json")) ? { dir, id: m[2] } : null
+}
+
+/**
+ * Resolve `<file>` into the virtual entry that opens its default export.
+ * `state` picks the branch of a `(state) => UIScreen` screen (ignored by a value export).
+ */
+const resolveScreenTarget = (
+  root: string, file: string, opts: { state?: string, dir?: string } = {},
+): ScreenTarget => {
+  const abs = findScreenFile(root, file, opts.dir)
+  const rel = relative(root, abs)
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    throw new CliError(
+      `"${file}" is outside the project (${root}) — a screen renders as part of its project, so its ` +
+      `imports and asset() files resolve from the same tree.`)
+  }
+  const key = toKey(rel)
+
+  // A file with no default export compiles to an empty render; say so here instead.
+  if (!/^\s*export\s+default\b/m.test(readFileSync(abs, "utf8"))) {
+    throw new CliError(
+      `${key.slice(1)} has no default export. A screen file ends with ` +
+      `\`export default UIScreen([...])\` — or \`export default (state) => UIScreen([...])\` for screen states.`)
+  }
+
+  // Same wrapper the design board compiles (designCompile.ts): a function export is invoked with the
+  // chosen state (a bare call uses the parameter's default = the canonical state), a value is used
+  // as-is, and either way the screen is opened so the runtime has something to render.
+  const invoke = opts.state !== undefined ? `screen(${JSON.stringify(opts.state)})` : "screen()"
+  const spec = "." + key.replace(/\.[^./]+$/, "")
+  const design = designDirOf(root, key)
+  return {
+    entryPath: SCREEN_ENTRY_PATH,
+    entry: {
+      path: SCREEN_ENTRY_PATH,
+      type: "text",
+      text: `import screen from ${JSON.stringify(spec)}\n`
+        + `const __screen = typeof screen === "function" ? ${invoke} : screen\n`
+        + `__screen.open()\n`,
+    },
+    frame: design ? screenFrame(design.dir, design.id) : undefined,
+    label: (design ? design.id : key.slice(1)) + (opts.state !== undefined ? `@${opts.state}` : ""),
+  }
+}
+
+/** The screen target named on the command line (`render <file>`), or undefined when no screen was
+ *  named. Rejects the flag combinations that would fight over the entrypoint. */
+export type ScreenArgs = { file?: string, state?: string, entry?: string, dir?: string }
+export const screenTargetFrom = (root: string, a: ScreenArgs): ScreenTarget | undefined => {
+  if (a.file === undefined) {
+    if (a.state !== undefined) throw new CliError("--state picks a screen's state — name the screen file too: lecodes render <file> --state <name>")
+    return undefined
+  }
+  if (a.entry !== undefined) throw new CliError("Use either a screen file or --entry, not both — each names the module to compile from.")
+  return resolveScreenTarget(root, a.file, { state: a.state, dir: a.dir })
+}