lecodes-cli 2.2.5 → 2.2.6

package/src/commands/thumbs.ts

@@ -1,185 +1,185 @@
-import { createRequire } from "node:module"
-import { execFileSync } from "node:child_process"
-import { existsSync, mkdtempSync, readdirSync, rmSync, statSync } from "node:fs"
-import { tmpdir } from "node:os"
-import { extname, join, relative, resolve } from "node:path"
-import { loadPeer } from "../hosts/peerInstall"
-import { projectRootOf } from "./scene"
-import { CliError, bool, c, defineCommand, endProgress, log, note, num, progress, warnErr } from "../cli"
-import { toKey } from "../project/paths"
-
-/*
- * `lecodes thumbs [path…]` — the scene editor's asset thumbnails, generated from the COMMAND LINE.
- *
- * The editor renders previews in a hidden browser host (3D assets need an engine), but image
- * thumbnails need no engine at all — and a .ktx2 has no picture until something decodes it. This
- * command fills the same cache the editor reads (`.lecodes/preview/<asset>.<hash>.png`, owned by
- * lecodes-3d-editor's server/previewCache) with no browser in the loop, so opening the editor on a
- * texture-heavy project shows a full grid immediately instead of rendering 40 thumbnails on the
- * spot.
- *
- * Incremental by construction: the cache file name carries the first 10 hex of the SOURCE file's
- * sha256, so an asset whose preview is already there is skipped after one hash — re-running over a
- * big project is nearly free. `--force` ignores that.
- *
- * Decoders, in the order tried: sharp (through the optional `lecodes-assets` peer — handles webp),
- * else jimp (bundled with this CLI: png / jpeg / bmp / gif / tiff). KTX2 goes through
- * KTX-Software's `ktx extract` first (it is a GPU-compressed format; nothing in JS reads it), and
- * the extracted PNG then takes the same resize path.
- *
- * NOT covered: models, materials and prefabs — those are RENDERED, which needs an engine. The
- * editor still does them on demand (and `lecodes render --desktop` is the browserless renderer if
- * that ever becomes a batch job).
- */
-
-const DEFAULT_SIZE = 256
-const IMAGE_EXT = /\.(png|jpe?g|webp|bmp|gif|tiff?|ktx2)$/i
-const RENDERED_EXT = /\.(glb|gltf|material\.ts|scene\.ts)$/i
-
-/** KTX-Software's `ktx` CLI (v4.3+ has `extract`), resolved like lecodes-assets resolves toktx. */
-const findKtx = (): string | null => {
-  const exe = process.platform === "win32" ? "ktx.exe" : "ktx"
-  const candidates = [
-    process.env.LECODES_KTX,
-    process.env.KTX_CLI,
-    process.env.KTX_TOKTX?.replace(/toktx(\.exe)?$/i, exe),
-    process.platform === "win32" ? join(process.env.LOCALAPPDATA ?? "", "Programs", "KTX-Software", "bin", exe) : null,
-    process.platform === "win32" ? join(process.env.ProgramFiles ?? "", "KTX-Software", "bin", exe) : null,
-    "/usr/local/bin/ktx",
-    "/opt/homebrew/bin/ktx",
-  ].filter((p): p is string => !!p)
-  for (const path of candidates) { if (existsSync(path)) return path }
-  try {
-    execFileSync(exe, [ "--version" ], { stdio: "ignore" })
-    return exe
-  } catch { return null }
-}
-
-type Resizer = (file: string, size: number) => Promise<Uint8Array>
-
-/** sharp through the `lecodes-assets` peer (it declares it optional), or null when neither is
- *  installed — jimp then covers everything but webp. */
-const sharpResizer = (): Resizer | null => {
-  try {
-    const req = createRequire(import.meta.url)
-    const sharp = createRequire(req.resolve("lecodes-assets/cli"))("sharp")
-    return async (file, size) =>
-      sharp(file).resize({ width: size, height: size, fit: "inside", withoutEnlargement: true }).png().toBuffer()
-  } catch { return null }
-}
-
-const jimpResizer = (): Resizer => async (file, size) => {
-  const { Jimp } = await import("jimp")
-  const img = await Jimp.read(file)
-  if (Math.max(img.width, img.height) > size) img.scaleToFit({ w: size, h: size })
-  return await img.getBuffer("image/png")
-}
-
-/** KTX2 → a temporary PNG (level 0, transcoded to RGBA8 when the payload is Basis-compressed). */
-const ktxToPng = (ktx: string, file: string, out: string): void => {
-  const run = (args: string[]) => execFileSync(ktx, args, { stdio: [ "ignore", "ignore", "pipe" ], encoding: "utf8" })
-  try {
-    run([ "extract", "--transcode", "rgba8", "--level", "0", file, out ])
-  } catch (e: any) {
-    // Only Basis (ETC1S/UASTC) payloads are transcodable; a plain uncompressed KTX2 extracts as-is
-    run([ "extract", "--level", "0", file, out ])
-    if (!existsSync(out)) throw e
-  }
-}
-
-/** Every previewable file under a folder — the SAME sweep the editor's asset panel lists with
- *  (node_modules + dotfiles out, nothing else): what this command doesn't cover, the browser would
- *  end up rendering itself. */
-const collect = (dir: string): string[] => {
-  const out: string[] = []
-  for (const name of readdirSync(dir)) {
-    if (name === "node_modules" || name.startsWith(".")) continue
-    const full = join(dir, name)
-    if (statSync(full).isDirectory()) out.push(...collect(full))
-    else if (IMAGE_EXT.test(name)) out.push(full)
-  }
-  return out
-}
-
-export default defineCommand({
-  name: "thumbs",
-  summary: "Asset thumbnails for the scene editor, without a browser",
-  usage: "[path…]",
-  description: "Decodes the project's images (KTX2 too, via KTX-Software's ktx tool) into the editor's preview cache. Incremental: the cached name carries the asset's content hash, so unchanged files are skipped. Models, materials and prefabs are rendered by the editor, not here.",
-  flags: {
-    force: bool("redo even the up-to-date ones"),
-    size: num("longest edge, px", { default: DEFAULT_SIZE }),
-  },
-  run: ({ args, flags }) => thumbs(args, flags.size, flags.force),
-})
-
-const thumbs = async (targets: string[], size: number, force: boolean): Promise<void> => {
-  const root = projectRootOf(process.cwd())
-
-  // The scene editor owns the preview cache — installed into ~/.lecodes/peers on first use.
-  const sceneServer = await loadPeer<typeof import("lecodes-3d-editor/server")>("lecodes-3d-editor", "server", { for: "lecodes thumbs" })
-
-  // Targets: the paths given (a file or a folder each), else the whole project.
-  let files: string[] = []
-  const rendered: string[] = []
-  if (targets.length > 0) {
-    for (const arg of targets) {
-      const abs = resolve(process.cwd(), arg)
-      if (!existsSync(abs)) throw new CliError(`No such file or folder: ${arg}`)
-      if (statSync(abs).isDirectory()) files.push(...collect(abs))
-      else if (IMAGE_EXT.test(abs)) files.push(abs)
-      else if (RENDERED_EXT.test(abs)) rendered.push(arg)
-      else throw new CliError(`Not a previewable asset: ${arg}`)
-    }
-  } else {
-    files = collect(root)
-  }
-  files = [ ...new Set(files) ]
-
-  if (files.length === 0 && rendered.length === 0) {
-    log("No images to thumbnail.")
-    return
-  }
-
-  const ktx = files.some((f) => f.toLowerCase().endsWith(".ktx2")) ? findKtx() : null
-  const sharp = sharpResizer()
-  const resize = sharp ?? jimpResizer()
-  const tmp = mkdtempSync(join(tmpdir(), "lecodes-thumbs-"))
-
-  let made = 0, fresh = 0
-  const skipped: string[] = []
-  try {
-    for (const [ i, file ] of files.entries()) {
-      const asset = "./" + toKey(relative(root, file))
-      progress(i, files.length, asset)
-      const hash = sceneServer.hashAsset(root, asset)
-      if (!hash) continue
-      if (!force && sceneServer.previewIsCurrent(root, asset, hash)) { fresh++; continue }
-
-      const ext = extname(file).toLowerCase()
-      if (ext === ".webp" && !sharp) { skipped.push(`${asset} (webp needs sharp — npm install -g lecodes-assets)`); continue }
-      try {
-        let source = file
-        if (ext === ".ktx2") {
-          if (!ktx) { skipped.push(`${asset} (KTX2 needs KTX-Software's \`ktx\` — set LECODES_KTX or put it on PATH)`); continue }
-          source = join(tmp, `${i}.png`)
-          ktxToPng(ktx, file, source)
-        }
-        sceneServer.writePreviewFile(root, asset, await resize(source, size))
-        made++
-      } catch (e: any) {
-        skipped.push(`${asset} (${(e?.message ?? String(e)).split("\n")[0]})`)
-      }
-    }
-  } finally {
-    endProgress()
-    rmSync(tmp, { recursive: true, force: true })
-  }
-
-  log(`${c.bold(String(made))} generated · ${fresh} already current${skipped.length > 0 ? ` · ${skipped.length} skipped` : ""}`)
-  for (const s of skipped) warnErr(s)
-  if (rendered.length > 0) {
-    warnErr(`Models, materials and prefabs are RENDERED, not decoded — the scene editor does those: ${rendered.join(", ")}`)
-  }
-  note(`Cache: ${join(root, ".lecodes", "preview")}  (re-runs skip everything unchanged)`)
-}
+import { createRequire } from "node:module"
+import { execFileSync } from "node:child_process"
+import { existsSync, mkdtempSync, readdirSync, rmSync, statSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { extname, join, relative, resolve } from "node:path"
+import { loadPeer } from "../hosts/peerInstall"
+import { projectRootOf } from "./scene"
+import { CliError, bool, c, defineCommand, endProgress, log, note, num, progress, warnErr } from "../cli"
+import { toKey } from "../project/paths"
+
+/*
+ * `lecodes thumbs [path…]` — the scene editor's asset thumbnails, generated from the COMMAND LINE.
+ *
+ * The editor renders previews in a hidden browser host (3D assets need an engine), but image
+ * thumbnails need no engine at all — and a .ktx2 has no picture until something decodes it. This
+ * command fills the same cache the editor reads (`.lecodes/preview/<asset>.<hash>.png`, owned by
+ * lecodes-3d-editor's server/previewCache) with no browser in the loop, so opening the editor on a
+ * texture-heavy project shows a full grid immediately instead of rendering 40 thumbnails on the
+ * spot.
+ *
+ * Incremental by construction: the cache file name carries the first 10 hex of the SOURCE file's
+ * sha256, so an asset whose preview is already there is skipped after one hash — re-running over a
+ * big project is nearly free. `--force` ignores that.
+ *
+ * Decoders, in the order tried: sharp (through the optional `lecodes-assets` peer — handles webp),
+ * else jimp (bundled with this CLI: png / jpeg / bmp / gif / tiff). KTX2 goes through
+ * KTX-Software's `ktx extract` first (it is a GPU-compressed format; nothing in JS reads it), and
+ * the extracted PNG then takes the same resize path.
+ *
+ * NOT covered: models, materials and prefabs — those are RENDERED, which needs an engine. The
+ * editor still does them on demand (and `lecodes render --desktop` is the browserless renderer if
+ * that ever becomes a batch job).
+ */
+
+const DEFAULT_SIZE = 256
+const IMAGE_EXT = /\.(png|jpe?g|webp|bmp|gif|tiff?|ktx2)$/i
+const RENDERED_EXT = /\.(glb|gltf|material\.ts|scene\.ts)$/i
+
+/** KTX-Software's `ktx` CLI (v4.3+ has `extract`), resolved like lecodes-assets resolves toktx. */
+const findKtx = (): string | null => {
+  const exe = process.platform === "win32" ? "ktx.exe" : "ktx"
+  const candidates = [
+    process.env.LECODES_KTX,
+    process.env.KTX_CLI,
+    process.env.KTX_TOKTX?.replace(/toktx(\.exe)?$/i, exe),
+    process.platform === "win32" ? join(process.env.LOCALAPPDATA ?? "", "Programs", "KTX-Software", "bin", exe) : null,
+    process.platform === "win32" ? join(process.env.ProgramFiles ?? "", "KTX-Software", "bin", exe) : null,
+    "/usr/local/bin/ktx",
+    "/opt/homebrew/bin/ktx",
+  ].filter((p): p is string => !!p)
+  for (const path of candidates) { if (existsSync(path)) return path }
+  try {
+    execFileSync(exe, [ "--version" ], { stdio: "ignore" })
+    return exe
+  } catch { return null }
+}
+
+type Resizer = (file: string, size: number) => Promise<Uint8Array>
+
+/** sharp through the `lecodes-assets` peer (it declares it optional), or null when neither is
+ *  installed — jimp then covers everything but webp. */
+const sharpResizer = (): Resizer | null => {
+  try {
+    const req = createRequire(import.meta.url)
+    const sharp = createRequire(req.resolve("lecodes-assets/cli"))("sharp")
+    return async (file, size) =>
+      sharp(file).resize({ width: size, height: size, fit: "inside", withoutEnlargement: true }).png().toBuffer()
+  } catch { return null }
+}
+
+const jimpResizer = (): Resizer => async (file, size) => {
+  const { Jimp } = await import("jimp")
+  const img = await Jimp.read(file)
+  if (Math.max(img.width, img.height) > size) img.scaleToFit({ w: size, h: size })
+  return await img.getBuffer("image/png")
+}
+
+/** KTX2 → a temporary PNG (level 0, transcoded to RGBA8 when the payload is Basis-compressed). */
+const ktxToPng = (ktx: string, file: string, out: string): void => {
+  const run = (args: string[]) => execFileSync(ktx, args, { stdio: [ "ignore", "ignore", "pipe" ], encoding: "utf8" })
+  try {
+    run([ "extract", "--transcode", "rgba8", "--level", "0", file, out ])
+  } catch (e: any) {
+    // Only Basis (ETC1S/UASTC) payloads are transcodable; a plain uncompressed KTX2 extracts as-is
+    run([ "extract", "--level", "0", file, out ])
+    if (!existsSync(out)) throw e
+  }
+}
+
+/** Every previewable file under a folder — the SAME sweep the editor's asset panel lists with
+ *  (node_modules + dotfiles out, nothing else): what this command doesn't cover, the browser would
+ *  end up rendering itself. */
+const collect = (dir: string): string[] => {
+  const out: string[] = []
+  for (const name of readdirSync(dir)) {
+    if (name === "node_modules" || name.startsWith(".")) continue
+    const full = join(dir, name)
+    if (statSync(full).isDirectory()) out.push(...collect(full))
+    else if (IMAGE_EXT.test(name)) out.push(full)
+  }
+  return out
+}
+
+export default defineCommand({
+  name: "thumbs",
+  summary: "Asset thumbnails for the scene editor, without a browser",
+  usage: "[path…]",
+  description: "Decodes the project's images (KTX2 too, via KTX-Software's ktx tool) into the editor's preview cache. Incremental: the cached name carries the asset's content hash, so unchanged files are skipped. Models, materials and prefabs are rendered by the editor, not here.",
+  flags: {
+    force: bool("redo even the up-to-date ones"),
+    size: num("longest edge, px", { default: DEFAULT_SIZE }),
+  },
+  run: ({ args, flags }) => thumbs(args, flags.size, flags.force),
+})
+
+const thumbs = async (targets: string[], size: number, force: boolean): Promise<void> => {
+  const root = projectRootOf(process.cwd())
+
+  // The scene editor owns the preview cache — installed into ~/.lecodes/peers on first use.
+  const sceneServer = await loadPeer<typeof import("lecodes-3d-editor/server")>("lecodes-3d-editor", "server", { for: "lecodes thumbs" })
+
+  // Targets: the paths given (a file or a folder each), else the whole project.
+  let files: string[] = []
+  const rendered: string[] = []
+  if (targets.length > 0) {
+    for (const arg of targets) {
+      const abs = resolve(process.cwd(), arg)
+      if (!existsSync(abs)) throw new CliError(`No such file or folder: ${arg}`)
+      if (statSync(abs).isDirectory()) files.push(...collect(abs))
+      else if (IMAGE_EXT.test(abs)) files.push(abs)
+      else if (RENDERED_EXT.test(abs)) rendered.push(arg)
+      else throw new CliError(`Not a previewable asset: ${arg}`)
+    }
+  } else {
+    files = collect(root)
+  }
+  files = [ ...new Set(files) ]
+
+  if (files.length === 0 && rendered.length === 0) {
+    log("No images to thumbnail.")
+    return
+  }
+
+  const ktx = files.some((f) => f.toLowerCase().endsWith(".ktx2")) ? findKtx() : null
+  const sharp = sharpResizer()
+  const resize = sharp ?? jimpResizer()
+  const tmp = mkdtempSync(join(tmpdir(), "lecodes-thumbs-"))
+
+  let made = 0, fresh = 0
+  const skipped: string[] = []
+  try {
+    for (const [ i, file ] of files.entries()) {
+      const asset = "./" + toKey(relative(root, file))
+      progress(i, files.length, asset)
+      const hash = sceneServer.hashAsset(root, asset)
+      if (!hash) continue
+      if (!force && sceneServer.previewIsCurrent(root, asset, hash)) { fresh++; continue }
+
+      const ext = extname(file).toLowerCase()
+      if (ext === ".webp" && !sharp) { skipped.push(`${asset} (webp needs sharp — npm install -g lecodes-assets)`); continue }
+      try {
+        let source = file
+        if (ext === ".ktx2") {
+          if (!ktx) { skipped.push(`${asset} (KTX2 needs KTX-Software's \`ktx\` — set LECODES_KTX or put it on PATH)`); continue }
+          source = join(tmp, `${i}.png`)
+          ktxToPng(ktx, file, source)
+        }
+        sceneServer.writePreviewFile(root, asset, await resize(source, size))
+        made++
+      } catch (e: any) {
+        skipped.push(`${asset} (${(e?.message ?? String(e)).split("\n")[0]})`)
+      }
+    }
+  } finally {
+    endProgress()
+    rmSync(tmp, { recursive: true, force: true })
+  }
+
+  log(`${c.bold(String(made))} generated · ${fresh} already current${skipped.length > 0 ? ` · ${skipped.length} skipped` : ""}`)
+  for (const s of skipped) warnErr(s)
+  if (rendered.length > 0) {
+    warnErr(`Models, materials and prefabs are RENDERED, not decoded — the scene editor does those: ${rendered.join(", ")}`)
+  }
+  note(`Cache: ${join(root, ".lecodes", "preview")}  (re-runs skip everything unchanged)`)
+}

package/src/compile/screenEntry.ts

@@ -1,123 +1,123 @@
-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 })
-}
+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 })
+}