lecodes-cli 0.19.0 → 0.19.2

package/src/compile/sceneCompile.ts

@@ -0,0 +1,113 @@
+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 { compileProject, type CompileEntry } from "./projectCompile"
+import { applyLocalShaders, shadersCacheDir } from "./shaders"
+
+/*
+ * The `lecodes scene` compile closure — the CLI's implementation of the scene-editor host's inject
+ * 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.
+ *
+ *   publicUrl ""  +  resource fileSrc "/project/<rel>"  → the scene server's /project/* mount.
+ *   minify:false  — mangling erases class names the inspector matches aspect schemas by.
+ *   editor:true   — the EDITOR global is `true`; `*.editor.ts` plugin files are bundled in.
+ */
+
+/** Text files handed to the compiler as source; everything else is a binary resource served from
+ *  the project folder (matches the playground's TEXT_EXT split, not the manifest's kind map). */
+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). */
+  manifest: Manifest | null
+  /** Project display name (compile metadata only, header is off). */
+  name: string
+  /** Project path of the scene file as the editor sends it ("./city.scene.ts"). */
+  scenePath: string
+}): Promise<{ js: string | null, error?: string }> => {
+  const { root, scenePath } = opts
+  const { loadSceneHarness, sceneEditorEntries, 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 ?? {})) })
+  for (const file of scan.files) {
+    const path = "./" + rel(file.path)
+    if (TEXT_EXT.test(path)) {
+      entries.push({ path, type: "text", text: readFileSync(file.absPath, "utf8") })
+    } else if (/\.mat$/i.test(path)) {
+      // custom shaders compile locally (matc + the lite JSON) into .lecodes/shaders, served through
+      // the same /project/* mount — see the fallback below when matc isn't available
+      entries.push({ path, type: "shader", text: readFileSync(file.absPath, "utf8"), absPath: file.absPath })
+    } else {
+      // Binary assets resolve to URLs the scene server serves from the project folder (/project/*).
+      entries.push({ path, type: "resource", fileSrc: "/project/" + rel(file.path) })
+    }
+  }
+
+  // Shader artifacts: the web targets only (the editor runs in a browser — lite viewport +
+  // filament preview, which loads the mobile `opengl` artifact — there is no web-specific matc
+  // build). Without matc (offline first run) the lite artifact is still built from the
+  // source alone, hashed on the text, the way the playground does — the lite viewport keeps
+  // working and only the Rendered mode lacks the shader.
+  const shaderEntries = entries.filter((e) => e.type === "shader")
+  if (shaderEntries.length > 0) {
+    const { warnings } = await applyLocalShaders(shaderEntries, { root, srcPrefix: "/project/.lecodes/shaders", platforms: [ "opengl", "webgl-lite" ] })
+    for (const w of warnings) warnErr(w)
+    const { buildLiteMaterialArtifact } = await import("lecodes-sdk/compile")
+    for (const e of shaderEntries) {
+      if (e.shaders?.length) continue
+      const hash = createHash("sha256").update(e.text ?? "").digest("hex").slice(0, 16)
+      const dir = shadersCacheDir(root)
+      mkdirSync(dir, { recursive: true })
+      const liteName = `${hash}_webgl-lite.filamat`
+      if (!existsSync(join(dir, liteName))) writeFileSync(join(dir, liteName), JSON.stringify(buildLiteMaterialArtifact(e.text ?? "")))
+      const src = `/project/.lecodes/shaders/${hash}_opengl.filamat`
+      e.shaders = [ "opengl", "webgl-lite" ].map((platform) => ({ platform, src }))
+    }
+  }
+
+  const scene = scenePath.startsWith("./") ? scenePath : "./" + rel(scenePath)
+  if (!entries.some((e) => e.path === scene && e.type === "text")) {
+    return { js: null, error: `Scene file not found: ${scene}` }
+  }
+  entries.push(...sceneEditorEntries(scene, resolveHarness(loadSceneHarness), entries.map((e) => e.path)))
+
+  try {
+    const js = await compileProject({
+      entries, name: opts.name, publicUrl: "", entryOverride: SCENE_ENTRY_PATH,
+      header: false, format: "iife", minify: false, editor: true,
+    })
+    return { js }
+  } catch (e: any) {
+    return { js: null, error: e?.message?.replace(/mem:/g, "") ?? String(e) }
+  }
+}

package/src/compile/screenEntry.ts

@@ -0,0 +1,127 @@
+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") })
+}

package/src/compile/shaders.ts

@@ -0,0 +1,245 @@
+import { execFile } from "node:child_process"
+import { createHash, randomBytes } from "node:crypto"
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { basename, join } from "node:path"
+import {
+  ALL_PLATFORM_BUILD, buildLiteMaterialArtifact, externalSamplerReg, LOCAL_ONLY_PLATFORMS,
+  matcArgs, MATC_PLATFORMS, TARGET_MATRIX_GENERATION,
+  type AnyMatcPlatform, type AnyShaderPlatform,
+} from "lecodes-sdk/compile"
+import { resolveMatcExe, resolveMatcExeCached } from "../matcTool"
+import { LECODES_DIR } from "../manifest"
+import { CliError } from "../util"
+import type { CompileEntry } from "./projectCompile"
+
+/*
+ * LOCAL shader compile — the working-tree twin of the backend's compileShaderAsset
+ * (backend/src/utils/compileShader.ts): each .mat source compiles via matc (matcTool.ts —
+ * downloaded on first use) into the same artifact family the server produces, so `lecodes dev`
+ * doesn't need a push for shaders to work. The target matrix + the webgl-lite JSON artifact
+ * builder are shared through sdk/compile (shaderTargets.ts / liteMaterial.ts) — keep the two
+ * compile paths producing the SAME set of names: the bundle derives per-backend URLs by
+ * substituting `_creator.backend` into the opengl src.
+ *
+ * Artifacts cache in <root>/.lecodes/shaders/<hash>_<platform>.filamat, keyed by a hash of the
+ * source text + the matc binary's identity (size/mtime) — a changed shader or an updated matc
+ * recompiles, an unchanged one costs a hash. The dev server serves the cache under /shaders/;
+ * `lecodes shaders` (commands/shaders.ts) lists/compiles the same cache explicitly.
+ *
+ * When matc can't be resolved (offline first run, unpublished platform), entries degrade to the
+ * old behavior — empty artifact list + the push-once warning — instead of failing the compile.
+ */
+
+const SHADERS_DIR = "shaders"
+
+export const shadersCacheDir = (root: string): string => join(root, LECODES_DIR, SHADERS_DIR)
+
+/** Served artifact names are exactly what applyLocalShaders emits — hash + a known platform. */
+export const isShaderArtifactName = (name: string): boolean =>
+  /^[0-9a-f]{16}_[a-z-]+\.filamat$/.test(name)
+
+/** The matc binary's cache-key identity — an updated (or locally rebuilt) matc recompiles. */
+export const matcIdentity = (exe: string): string => {
+  const stat = statSync(exe)
+  return `${stat.size}:${Math.trunc(stat.mtimeMs)}`
+}
+
+// TARGET_MATRIX_GENERATION is in the key so that changing the matc argv behind an EXISTING target
+// name invalidates caches that would otherwise look complete (adding/removing a name is already
+// caught by artifactFamily). Same class as matcId: a toolchain or matrix change means recompile.
+const shaderHash = (text: string, matcId: string): string =>
+  createHash("sha256").update(`${TARGET_MATRIX_GENERATION}\0${matcId}\0${text}`).digest("hex").slice(0, 16)
+
+/** The full artifact family: the server's matc targets + the CLI's local-only ones + the lite JSON.
+ *  This is what "compiled" means for `lecodes shaders` status and what a caller gets when it
+ *  doesn't ask for a narrower set. The web runtime loads the mobile `opengl` artifact (the engine
+ *  rewrites external samplers itself — sdk/compile shaderTargets.ts), so there is no web target. */
+const artifactFamily = (): AnyShaderPlatform[] => [...MATC_PLATFORMS, ...LOCAL_ONLY_PLATFORMS, "webgl-lite"]
+
+/** True when every artifact for this source is already in the cache (`lecodes shaders` status). */
+export const shaderIsCompiled = (root: string, text: string, matcId: string): boolean => {
+  const hash = shaderHash(text, matcId)
+  return artifactFamily().every((p) => existsSync(join(shadersCacheDir(root), `${hash}_${p}.filamat`)))
+}
+
+/** Which artifacts of the family are present — `lecodes shaders` status distinguishes a deliberate
+ *  subset (`lecodes shaders compile --platform …`, or a desktop build's single target) from a cache
+ *  that is simply stale. Without this, anyone using a narrower set reads a permanent "not compiled"
+ *  and re-runs a full compile to clear it, undoing the saving. */
+export const shaderCompiledPlatforms = (root: string, text: string, matcId: string): AnyShaderPlatform[] => {
+  const hash = shaderHash(text, matcId)
+  return artifactFamily().filter((p) => existsSync(join(shadersCacheDir(root), `${hash}_${p}.filamat`)))
+}
+
+/** The cached artifact FILE for a shader source + platform, when matc is installed and the
+ *  artifact was compiled (the scene editor host's `/api/shader` reads it for live material
+ *  patches). Null otherwise — the caller falls back to building the lite JSON on the fly. */
+export const localShaderArtifact = (root: string, text: string, platform: string): string | null => {
+  const matcExe = resolveMatcExeCached()
+  if (!matcExe) return null
+  const file = join(shadersCacheDir(root), `${shaderHash(text, matcIdentity(matcExe))}_${platform}.filamat`)
+  return existsSync(file) ? file : null
+}
+
+/** Every platform name the local compile knows, for validating a user-supplied `--platform` list. */
+export const allShaderPlatforms = (): AnyShaderPlatform[] =>
+  [...(Object.keys(ALL_PLATFORM_BUILD) as AnyMatcPlatform[]), "webgl-lite"]
+
+const runMatc = (exe: string, args: string[]): Promise<{ ok: boolean, stderr: string }> =>
+  new Promise((resolve) => {
+    execFile(exe, args, { windowsHide: true }, (error, _stdout, stderr) => {
+      // error covers both a nonzero exit (compile error) and a failed spawn — the message joins
+      // stderr so a missing/undownloadable binary still explains itself.
+      const text = String(stderr ?? "") || (error ? error.message : "")
+      resolve({ ok: !error, stderr: text })
+    })
+  })
+
+/** matc's stderr names the temp file — rewrite to the project path and cut the trailing noise. */
+const cleanMatcOutput = (err: string, tempName: string, realName: string): string => {
+  const output = err.replaceAll("\r", "").replaceAll(tempName, realName)
+  const cut = output.indexOf("\n\n")
+  return (cut >= 0 ? output.slice(0, cut) : output).trim()
+}
+
+/** Artifacts the local compile produced, for a caller that must SHIP them (the desktop host reads
+ *  them by name from next to the bundle — see `local` mode below). */
+export type StagedShader = { name: string, absPath: string }
+
+export type LocalShaderResult = { warnings: string[], artifacts: StagedShader[] }
+
+/** The artifacts a native host can actually load. webgl-lite is web-only, so it stays in
+ *  the cache instead of being staged into a desktop build. `_creator.backend` returns exactly one
+ *  of these: "desktop" (Windows desktop GL), "desktop-vulkan" (Windows desktop Vulkan),
+ *  "opengl" (Linux desktop, Android), "metal" (Apple).
+ *
+ *  NATIVE_PLATFORMS is the default when the caller does NOT know which host will run the bundle (a
+ *  generic `preview --local`): every native artifact ships and the runtime picks. It deliberately
+ *  omits "desktop-vulkan" — that host is opt-in, and shipping ~293 KB per shader to every unknown
+ *  target for it would be a poor trade. A caller that DOES know — every desktop path, which stages
+ *  the very exe that will run — passes `platforms` and ships exactly one, which is where
+ *  desktop-vulkan gets staged. ALL_NATIVE_PLATFORMS is the set such a request is intersected with,
+ *  i.e. "which of the requested platforms is a native host able to load at all". */
+const NATIVE_PLATFORMS: AnyMatcPlatform[] = ["opengl", "metal", "desktop"]
+const ALL_NATIVE_PLATFORMS: AnyMatcPlatform[] = ["opengl", "metal", "desktop", "desktop-vulkan"]
+
+/** The single artifact a desktop host asks for, by (target OS, renderer) — the same mapping
+ *  `js_getBackend` implements in creator-pkg. Linux desktop runs GLES and reports "opengl"; the
+ *  macOS host (the Apple repo's LeCodes Desktop.app) is Filament-on-Metal and reports "metal" —
+ *  staging "opengl" there leaves every custom material failing to load at the first scene. */
+export const desktopShaderPlatform = (
+  platform: NodeJS.Platform, renderer: "gl" | "vulkan",
+): AnyMatcPlatform =>
+  platform === "win32" ? (renderer === "vulkan" ? "desktop-vulkan" : "desktop")
+    : platform === "darwin" ? "metal"
+      : "opengl"
+
+/**
+ * Compile the project's shaders into the local cache and point each entry's `shaders` list at the
+ * results. Two modes:
+ *   - URL mode (`srcPrefix`, the dev server): srcs become `<srcPrefix>/<name>`, served over HTTP.
+ *   - `local` mode (hosts with no asset server — the desktop host): srcs become bare artifact
+ *     names, `shadersLocal` marks the entry, and the returned artifacts must be staged next to
+ *     the bundle so the host's fetchLocal finds them.
+ * Entries that already carry artifacts are skipped in URL mode (the server compiled them); in
+ * local mode they are recompiled, since a local-assets run reads the working tree by definition.
+ * Returns warnings (matc unavailable → the entry keeps whatever it had); throws CliError on an
+ * actual matc compile error (a broken .mat fails the compile like a TS error).
+ *
+ * `platforms` narrows the set compiled AND staged — pass it only when the target host is known with
+ * certainty (every desktop path: the exe is bundled or spawned by the same command). Leave it off
+ * for `lecodes dev`, which feeds a phone, a browser and the desktop host from one bundle and cannot
+ * know which will connect. Compiling is incremental per artifact, so a narrow run and a later full
+ * one add up instead of redoing each other's work.
+ */
+export const applyLocalShaders = async (
+  entries: CompileEntry[],
+  opts: { root: string, srcPrefix?: string, local?: boolean, platforms?: AnyShaderPlatform[] },
+): Promise<LocalShaderResult> => {
+  const shaderEntries = entries.filter((e) =>
+    e.type === "shader" && e.absPath && (opts.local || !e.shaders?.length))
+  if (shaderEntries.length === 0) return { warnings: [], artifacts: [] }
+
+  let matcExe: string
+  try {
+    matcExe = await resolveMatcExe()
+  } catch (e) {
+    const reason = e instanceof CliError ? e.message : String(e)
+    return { warnings: [`Local shader compile unavailable (${reason})\n  Shaders fall back to the server — push the project once for them to work.`], artifacts: [] }
+  }
+  const matcId = matcIdentity(matcExe)
+
+  const cacheDir = shadersCacheDir(opts.root)
+  mkdirSync(cacheDir, { recursive: true })
+  const artifacts: StagedShader[] = []
+
+  for (const entry of shaderEntries) {
+    const text = readFileSync(entry.absPath!, "utf8")
+    const hash = shaderHash(text, matcId)
+    const family = artifactFamily()
+    const artifact = (platform: string) => `${hash}_${platform}.filamat`
+    const has = (platform: string) => existsSync(join(cacheDir, artifact(platform)))
+
+    // What this run is responsible for: the whole family, or the caller's subset intersected with it.
+    const wanted = opts.platforms ? family.filter((p) => opts.platforms!.includes(p)) : family
+
+    // Compile only what is MISSING. Per-artifact rather than all-or-nothing so a narrow run
+    // (`--platform`, a desktop build) and a later full one add up instead of redoing each other's
+    // work. The old whole-family gate existed so a run that died midway could not serve a partial
+    // set — that property is preserved by each artifact being written-or-removed individually
+    // (the rmSync on failure below), which is what actually matters.
+    const missing = wanted.filter((p) => !has(p))
+    const matcMissing = missing.filter((p): p is AnyMatcPlatform => p !== "webgl-lite")
+    if (matcMissing.length > 0) {
+      // Temp source in tmpdir, rewritten per platform for the samplerExternal → sampler2d targets.
+      const tempName = `lecodes-matc-${randomBytes(6).toString("hex")}.mat`
+      const tempFile = join(tmpdir(), tempName)
+      try {
+        for (const platform of matcMissing) {
+          const build = ALL_PLATFORM_BUILD[platform]
+          writeFileSync(tempFile, build.replaceExternal ? text.replace(externalSamplerReg, "type:sampler2d") : text)
+          const out = join(cacheDir, artifact(platform))
+          const { ok, stderr } = await runMatc(matcExe, matcArgs(platform, out, tempFile))
+          if (!ok) {
+            rmSync(out, { force: true })
+            throw new CliError(`${entry.path}: shader compile failed [${platform}]\n${cleanMatcOutput(stderr, tempName, basename(entry.path))}`)
+          }
+        }
+      } finally {
+        rmSync(tempFile, { force: true })
+      }
+    }
+    // Web Lite artifact — JSON, not a filamat package (viewer-lite wraps the parsed fragment in
+    // its own GLSL template). buildLiteMaterialArtifact never throws — an exotic material becomes
+    // an `unsupported` artifact and the lite runtime falls back to unlit.
+    if (missing.includes("webgl-lite")) {
+      writeFileSync(join(cacheDir, artifact("webgl-lite")), JSON.stringify(buildLiteMaterialArtifact(text)))
+    }
+
+    // opengl first — its src is the template the bundle substitutes the runtime backend into.
+    if (opts.local) {
+      // Stage the native artifacts the target can ask for: the caller's set when it knows which host
+      // will run (one, for a desktop build), else every native one. `_creator.backend` picks at
+      // runtime, so shipping more than one is only ever wasted bytes — never a correctness need.
+      const staged = opts.platforms
+        ? ALL_NATIVE_PLATFORMS.filter((p) => opts.platforms!.includes(p))
+        : NATIVE_PLATFORMS
+      // opengl must lead: compileProject derives the runtime name by substituting the backend into
+      // shaders[0]'s "_opengl". A staged set without it (a Windows desktop build) still needs the
+      // template, so synthesise the entry from the opengl NAME even when that file isn't shipped.
+      entry.shaders = [
+        { platform: "opengl", src: artifact("opengl") },
+        ...staged.filter((p) => p !== "opengl").map((platform) => ({ platform, src: artifact(platform) })),
+      ]
+      entry.shadersLocal = true
+      for (const platform of staged) {
+        artifacts.push({ name: artifact(platform), absPath: join(cacheDir, artifact(platform)) })
+      }
+    } else {
+      const order = ["opengl", "metal", "desktop", "webgl-lite"]
+      entry.shaders = order.map((platform) => ({ platform, src: `${opts.srcPrefix}/${artifact(platform)}` }))
+    }
+  }
+  return { warnings: [], artifacts }
+}

package/src/config.ts

@@ -0,0 +1,42 @@
+import { homedir } from "node:os"
+import { join } from "node:path"
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { CliError } from "./util"
+
+/* Global CLI config in ~/.lecodes/config.json: the server URL + the personal access token.
+ * Env vars LECODES_API / LECODES_TOKEN override the stored values (handy for CI). */
+
+export type Config = { apiUrl?: string, token?: string }
+
+export const DEFAULT_API = "https://le.codes"
+
+const CONFIG_DIR = join(homedir(), ".lecodes")
+const CONFIG_FILE = join(CONFIG_DIR, "config.json")
+
+export const loadConfig = (): Config => {
+  let stored: Config = {}
+  try { stored = JSON.parse(readFileSync(CONFIG_FILE, "utf8")) } catch { /* none yet */ }
+  return {
+    apiUrl: process.env.LECODES_API ?? stored.apiUrl,
+    token: process.env.LECODES_TOKEN ?? stored.token,
+  }
+}
+
+export const saveConfig = (config: Config) => {
+  mkdirSync(CONFIG_DIR, { recursive: true })
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2))
+}
+
+/** Strip a trailing slash so apiUrl + "/api" / apiUrl + src compose cleanly. */
+export const normalizeApiUrl = (url: string) => url.trim().replace(/\/+$/, "")
+
+/** The token, or a friendly error telling the user to log in. */
+export const requireToken = (config: Config): string => {
+  if (!config.token) throw new CliError("Not logged in. Run `lecodes login` first.")
+  return config.token
+}
+
+export const requireApiUrl = (config: Config): string => {
+  if (!config.apiUrl) throw new CliError("No server URL configured. Run `lecodes login` first.")
+  return normalizeApiUrl(config.apiUrl)
+}

package/src/designMeta.ts

@@ -0,0 +1,35 @@
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+/* The design folder's meta.json, read WITHOUT the optional `lecodes-design` package: the CLI needs
+ * a screen's board frame in paths that must work on a bare install (`lecodes design snapshot`,
+ * `lecodes render <screen>`). Mirrors lecodes-design's `metaDefaultSize` validation — duplicated
+ * on purpose, since the design package is an optional peer. */
+
+export type ScreenMeta = { size?: [number, number] }
+export type MetaFrames = { screens: Record<string, ScreenMeta>, defaultSize: [number, number] }
+
+export const PHONE_SIZE: [number, number] = [390, 844]
+
+/** Per-screen sizes + the board default frame (meta.defaultSize — a desktop design sets
+ *  [1280, 800]). A missing/broken meta.json degrades to the phone frame. */
+export const readMetaFrames = (designDir: string): MetaFrames => {
+  try {
+    const meta = JSON.parse(readFileSync(join(designDir, "meta.json"), "utf8"))
+    const d = meta?.defaultSize
+    const valid = Array.isArray(d) && d.length === 2 &&
+      d.every((n: unknown) => typeof n === "number" && Number.isFinite(n) && n >= 64 && n <= 8192)
+    return {
+      screens: meta?.screens ?? {},
+      defaultSize: valid ? [Math.round(d[0]), Math.round(d[1])] : PHONE_SIZE,
+    }
+  } catch {
+    return { screens: {}, defaultSize: PHONE_SIZE }
+  }
+}
+
+/** The frame a screen renders at: its own `size` in meta.json, else the board default. */
+export const screenFrame = (designDir: string, screenId: string): [number, number] => {
+  const frames = readMetaFrames(designDir)
+  return frames.screens[screenId]?.size ?? frames.defaultSize
+}