lecodes-cli 0.19.0 → 0.20.0

package/src/commands/thumbs.ts

@@ -0,0 +1,178 @@
+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 { projectRootOf } from "./scene"
+import { CliError, c, endProgress, flagBool, flagStr, log, note, progress, toKey, warnErr, type Args } from "../util"
+
+/*
+ * `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 const thumbs = async (args: Args) => {
+  const root = projectRootOf(process.cwd())
+
+  let sceneServer: typeof import("lecodes-3d-editor/server")
+  try {
+    sceneServer = await import("lecodes-3d-editor/server")
+  } catch {
+    throw new CliError("The scene editor isn't installed (it owns the preview cache). Run:  npm install -g lecodes-3d-editor")
+  }
+
+  const size = Number(flagStr(args, "size")) || DEFAULT_SIZE
+  const force = flagBool(args, "force")
+
+  // Targets: the paths given (a file or a folder each), else the whole project.
+  let files: string[] = []
+  const rendered: string[] = []
+  if (args._.length > 0) {
+    for (const arg of args._) {
+      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/commands/types.ts

@@ -0,0 +1,87 @@
+import { resolve } from "node:path"
+import { getTypes } from "../api"
+import { DEFAULT_API, loadConfig, normalizeApiUrl } from "../config"
+import { findProjectRoot, LECODES_DIR } from "../manifest"
+import {
+  bundleHash, readLocalTypeBundle, readProjectTypeBundle, writeTsconfig, writeTypeBundle,
+  type TypeBundle,
+} from "../types"
+import { CliError, c, flagBool, flagStr, log, note, success, warn, type Args } from "../util"
+
+/*
+ * 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).
+ *
+ * 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
+ * exactly the confusing case worth naming out loud.
+ */
+
+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) : (() => {
+    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 (!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)
+    try {
+      bundle = await getTypes(apiUrl)
+      source = apiUrl
+    } catch (e) {
+      if (!local || checkOnly) throw e
+      warn(`${(e as Error).message}`)
+      bundle = local
+      source = "the CLI's bundled SDK (server unreachable)"
+    }
+  }
+  log(`${c.green("source")}    ${source} — ${label(bundle)}`)
+
+  // ---- report drift, write unless --check ----
+  const onDisk = readProjectTypeBundle(root)
+  const same = bundleHash(onDisk) === bundleHash(bundle)
+  if (checkOnly) {
+    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)}).`)
+    return
+  }
+
+  const stats = writeTypeBundle(root, bundle)
+  writeTsconfig(root)
+  const changes = [
+    stats.added ? `${stats.added} added` : null,
+    stats.updated ? `${stats.updated} updated` : null,
+    stats.removed ? `${stats.removed} removed` : null,
+  ].filter(Boolean)
+  log(`${c.green("written")}   ${LECODES_DIR}/types/ + tsconfig.json  ${c.dim(changes.length ? `(${changes.join(", ")})` : "(already current)")}`)
+
+  // 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)) {
+    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.")
+}

package/src/commands/update.ts

@@ -0,0 +1,190 @@
+import { spawnSync } from "node:child_process"
+import { existsSync, readdirSync } from "node:fs"
+import { homedir } from "node:os"
+import { dirname, join, resolve } from "node:path"
+import pkg from "../../package.json"
+import { CliError, c, flagBool, log, note, type Args } from "../util"
+import { OPTIONAL_PEERS, peerVersion } from "../peers"
+import { updateDesktop } from "../desktopRenderer"
+import { updateMatc } from "../matcTool"
+import { types } from "./types"
+import { shaders } from "./shaders"
+import { app } from "./app"
+
+/*
+ * `lecodes update` — one command that moves EVERYTHING a project depends on to its newest published
+ * state, in the order the pieces depend on each other:
+ *
+ *   1. desktop   the LeCodes Desktop host `desktop run` / `render --desktop` use   (= `desktop update`)
+ *   2. matc      Filament's material compiler for local shader compiles              (= `shaders update`)
+ *   3. shaders   recompile the project's .mat files with that matc                   (= `shaders compile`)
+ *   4. types     the IDE types (.lecodes/types + tsconfig) from the server            (= `types`)
+ *   5. shells    ios/ + android/ pins → newest SDK release + plugin tags, re-sync     (= `app update`)
+ *   6. cli       the GLOBAL npm installs — every installed optional peer (lecodes-renderer,
+ *                lecodes-design, lecodes-3d-editor, lecodes-assets) and the CLI itself that is behind
+ *                npm's latest: `npm install -g …@latest` (peers first, the CLI last; the standalone
+ *                binary can't come from npm — it says so and does the peers only)
+ *
+ * Every step is the existing subcommand, so nothing here can drift from what the individual
+ * commands do; this only sequences them and keeps going when one fails (the summary says which).
+ * Steps that the environment pins are SKIPPED, not overridden: LECODES_DESKTOP_EXE means a local
+ * host build (engine work — the cache is irrelevant), LECODES_MATC a local matc; the project steps
+ * need a project (a dir with app.json / .lecodes above the cwd) and the shell step a shell folder.
+ *
+ * Flags: --local (types from the SDK bundled in this CLI instead of the server), --no-shells (leave
+ * ios/android pins alone — `app update` re-syncs, which compiles the bundle and, for server projects,
+ * needs a login), --check (the npm step only REPORTS what is behind and prints the install line),
+ * --no-cli (skip the npm step — offline / air-gapped machines).
+ *
+ * `lecodes types` used to be its own command; the types step here replaced it (2026-09-04).
+ */
+
+/** The nearest project at or above `start`: a dir with app.json, or a .lecodes/ that holds a project's
+ *  manifest or types. NOT the bare `.lecodes/` marker projectEnv uses — the CLI's own config lives in
+ *  ~/.lecodes, so that rule would turn any folder under the home dir into a "project" and the types
+ *  step would scaffold .lecodes/types + tsconfig.json into it. */
+const findProjectDir = (start: string): string | null => {
+  const home = resolve(homedir())
+  let dir = resolve(start)
+  while (true) {
+    if (dir !== home && (existsSync(join(dir, "app.json")) || existsSync(join(dir, ".lecodes", "manifest.json")) || existsSync(join(dir, ".lecodes", "types")))) return dir
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+type Outcome = "updated" | "ok" | "skipped" | "failed"
+type Step = { name: string, outcome: Outcome, detail?: string }
+
+const NPM = "https://registry.npmjs.org"
+
+/** `latest` dist-tag of an npm package, or null when npm is unreachable / the package is unknown. */
+const npmLatest = async (name: string): Promise<string | null> => {
+  try {
+    const res = await fetch(`${NPM}/${name}/latest`, { signal: AbortSignal.timeout(4000) })
+    if (!res.ok) return null
+    const json = await res.json() as { version?: string }
+    return json.version ?? null
+  } catch {
+    return null
+  }
+}
+
+const semverNewer = (a: string, b: string): number => {
+  const pa = a.split(/[.-]/).map(Number), pb = b.split(/[.-]/).map(Number)
+  for (let i = 0; i < 3; i++) { const d = (pa[i] ?? 0) - (pb[i] ?? 0); if (d) return d }
+  return 0
+}
+
+/** Running straight from the repo checkout (src/commands/update.ts), not a built dist/binary. */
+const FROM_SOURCE = /[\\/]src[\\/]commands[\\/]/.test(import.meta.url)
+/** The standalone release build: the bundle + chisel sit next to the executable (same test as index.ts). */
+const STANDALONE = existsSync(join(dirname(process.execPath), "runtime")) &&
+  existsSync(join(dirname(process.execPath), process.platform === "win32" ? "chisel.exe" : "chisel"))
+
+export const update = async (args: Args) => {
+  const steps: Step[] = []
+  const heading = (name: string, what: string) => log(`\n${c.bold(name)}  ${c.dim(what)}`)
+  const run = async (name: string, what: string, fn: () => Promise<Outcome | [Outcome, string]>) => {
+    heading(name, what)
+    try {
+      const r = await fn()
+      const [outcome, detail] = Array.isArray(r) ? r : [r, undefined]
+      steps.push({ name, outcome, detail })
+      if (outcome === "skipped" && detail) note(`skipped — ${detail}`)
+    } catch (e) {
+      const msg = e instanceof CliError ? e.message : e instanceof Error ? e.message : String(e)
+      log(c.red("✗ ") + msg)
+      steps.push({ name, outcome: "failed", detail: msg })
+    }
+  }
+
+  const root = findProjectDir(process.cwd())
+
+  // 1. desktop host
+  await run("desktop", "LeCodes Desktop host (desktop run / render --desktop)", async () => {
+    if (process.env.LECODES_DESKTOP_EXE) return ["skipped", `LECODES_DESKTOP_EXE=${process.env.LECODES_DESKTOP_EXE} (a local build; \`lecodes desktop update\` refreshes the cache anyway)`]
+    await updateDesktop()
+    return "ok"
+  })
+
+  // 2. matc
+  await run("matc", "Filament material compiler for local shader compiles", async () => {
+    if (process.env.LECODES_MATC) return ["skipped", `LECODES_MATC=${process.env.LECODES_MATC} (a local matc)`]
+    await updateMatc()
+    return "ok"
+  })
+
+  // 3. shaders (project)
+  await run("shaders", "recompile the project's .mat shaders with the current matc", async () => {
+    if (!root) return ["skipped", "not inside a project"]
+    await shaders({ _: ["compile"], flags: {} })
+    return "ok"
+  })
+
+  // 4. types (project)
+  await run("types", flagBool(args, "local") ? "IDE types from the SDK bundled in this CLI" : "IDE types from the server", async () => {
+    if (!root) return ["skipped", "not inside a project"]
+    await types({ _: [], flags: flagBool(args, "local") ? { local: true } : {} })
+    return "ok"
+  })
+
+  // 5. native shells (project)
+  await run("shells", "ios/ + android/ pins → newest SDK release + plugin tags, then re-sync", async () => {
+    if (!root) return ["skipped", "not inside a project"]
+    if (flagBool(args, "no-shells")) return ["skipped", "--no-shells"]
+    const present = ["ios", "android"].filter((d) => existsSync(join(root!, d)) && readdirSync(join(root!, d)).length > 0)
+    if (present.length === 0) return ["skipped", "no ios/ or android/ shell in this project (`lecodes app init ios|android`)"]
+    await app({ _: ["update"], flags: {} })
+    return "ok"
+  })
+
+  // 6. this CLI + its optional peers — the GLOBAL npm installs (`npm install -g`, how the CLI and its
+  // peers are installed): every installed one that is behind npm's latest moves forward. The peers go
+  // first, the CLI itself last — replacing the running CLI's files is fine (this process already
+  // holds its code), but its new version is what the next invocation runs, so nothing after it here.
+  // Peers that are NOT installed stay that way: they're optional, installing one is a choice.
+  await run("cli", "lecodes-cli + its optional peers (global npm installs)", async () => {
+    if (flagBool(args, "no-cli")) return ["skipped", "--no-cli"]
+    if (FROM_SOURCE) return ["skipped", "running from the repo checkout — the CLI and its peers are the repo's own"]
+    const rows: { name: string, installed: string | null, latest: string | null }[] = []
+    for (const [name, probe] of OPTIONAL_PEERS) {
+      const installed = peerVersion(name, probe)
+      rows.push({ name, installed, latest: installed ? await npmLatest(name) : null })
+    }
+    rows.push({ name: "lecodes-cli", installed: pkg.version, latest: await npmLatest("lecodes-cli") })
+    if (rows.every((r) => r.latest === null)) return ["skipped", "npm unreachable"]
+    const behind = rows.filter((r) => r.installed && r.latest && semverNewer(r.latest, r.installed) > 0)
+    for (const r of rows) {
+      const state = !r.installed ? c.dim("not installed (optional — npm install -g " + r.name + ")")
+        : !r.latest ? c.dim("(npm: unknown)")
+        : behind.includes(r) ? c.yellow("→ " + r.latest)
+        : c.dim("(up to date)")
+      log("  " + r.name.padEnd(18) + " " + (r.installed ?? "").padEnd(8) + " " + state)
+    }
+    if (behind.length === 0) return "ok"
+    const specs = behind.map((r) => r.name + "@latest")
+    if (flagBool(args, "check")) return ["updated", behind.length + " behind — run: npm install -g " + specs.join(" ")]
+    if (STANDALONE && behind.some((r) => r.name === "lecodes-cli")) {
+      note("this is the standalone build — the CLI updates by re-installing the release archive, not through npm; peers still go through npm")
+    }
+    const toInstall = STANDALONE ? specs.filter((s) => !s.startsWith("lecodes-cli@")) : specs
+    if (toInstall.length === 0) return ["skipped", "only the standalone CLI itself is behind — download the release"]
+    log("  " + c.dim("$") + " npm install -g " + toInstall.join(" "))
+    const r = spawnSync("npm", ["install", "-g", ...toInstall], { stdio: "inherit", shell: true })
+    if (r.status !== 0) throw new CliError("npm install -g exited with " + (r.status ?? "a signal"))
+    const names = toInstall.map((s) => s.replace("@latest", "")).join(", ")
+    const cliToo = toInstall.some((s) => s.startsWith("lecodes-cli@"))
+    return ["updated", names + " → latest" + (cliToo ? " (the new CLI runs from your next command)" : "")]
+  })
+
+  // Summary — one line per step so a scrolled-away failure can't hide.
+  log(`\n${c.bold("Summary")}`)
+  const width = Math.max(...steps.map((s) => s.name.length))
+  for (const s of steps) {
+    const mark = s.outcome === "failed" ? c.red("✗") : s.outcome === "skipped" ? c.dim("–") : c.green("✓")
+    log(`  ${mark} ${s.name.padEnd(width)}  ${s.outcome === "failed" ? c.red(s.detail ?? "failed") : s.outcome === "skipped" ? c.dim(s.detail ?? "skipped") : s.detail ?? s.outcome}`)
+  }
+  if (steps.some((s) => s.outcome === "failed")) process.exitCode = 1
+}

package/src/compile/assetIcons.ts

@@ -0,0 +1,214 @@
+import { createHash } from "node:crypto"
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { dirname, join } from "node:path"
+import { applyAssetIconMacro, buildIconsHeaderValue, collectVendoredIcons, iconNotFoundError, ICON_ID, type AssetIconEntry } from "lecodes-sdk/compile"
+
+/*
+ * The CLI side of the `assetIcon('pack:name')` compile macro. The scan/rewrite core lives in the
+ * SDK (sdk/compile assetIconMacro — shared with the backend); this wrapper decides where the SVG
+ * bodies come from per compile mode:
+ *
+ *   design — `lecodes design` screens: icons vendor INTO the design folder
+ *            (assets/icons/<pack>/<name>.svg + icons.lock.json + ICON-NOTICES.md), so the pushed
+ *            design renders offline (the platform board resolves vendored svgs first, its own
+ *            cache/registry for the rest) and attribution ships in the user's repo.
+ *   app    — `lecodes compile` / `dev` / `render` / `test`: icons resolve from the user-level cache
+ *            (~/.lecodes/cache/icons/<pack>/<name>.svg), fetching misses from the registry. Nothing
+ *            is written into the project — the project tree stays exactly what the user wrote.
+ *            No lock: registry `/v1` ids are immutable (a redesigned glyph is a new name or a /v2),
+ *            so a cached SVG is valid forever. Attribution rides the bundle's `// icons:` header
+ *            (packs inlined) + the platform's attribution surface, not an in-repo notice.
+ */
+
+/** Default registry base — per-icon SVGs at `<base>/<pack>/<name>.svg`, licenses at `<base>/licenses.json`.
+ *  A local directory (with the same layout) works too, for tests. Override with LECODES_ICON_REGISTRY. */
+const DEFAULT_REGISTRY = process.env.LECODES_ICON_REGISTRY?.trim() || "https://icon-registry.jt3.ru/v1"
+
+// ---- registry access ----------------------------------------------------------------------------
+
+type LicenseEntry = { spdx: string, title: string, url: string, attribution: string | null, modifiedNotice: boolean }
+
+const isHttp = (s: string) => /^https?:/i.test(s)
+const sha12 = (s: string) => createHash("sha256").update(s).digest("hex").slice(0, 12)
+
+const readText = async (registry: string, rel: string): Promise<string | null> => {
+  if (isHttp(registry)) {
+    // Network failure reads as absent — callers turn a fully-unreachable registry into a clear error.
+    try {
+      const res = await fetch(`${registry}/${rel}`)
+      return res.ok ? await res.text() : null
+    } catch { return null }
+  }
+  try { return readFileSync(join(registry, rel), "utf8") } catch { return null }
+}
+
+const safeRead = (path: string): string | null => { try { return readFileSync(path, "utf8") } catch { return null } }
+
+const writeIfChanged = (path: string, text: string): boolean => {
+  const current = existsSync(path) ? safeRead(path) : null
+  if (current === text) return false
+  writeFileSync(path, text)
+  return true
+}
+
+/** Fetch one icon's SVG; a miss throws the legible SDK-built error ("did you mean …" from the
+ *  pack's meta.json, or the available-pack list when the pack itself is unknown). */
+const fetchIcon = async (registry: string, pack: string, name: string): Promise<string> => {
+  const svg = await readText(registry, `${pack}/${name}.svg`)
+  if (svg !== null) return svg
+  throw await iconNotFoundError(pack, name, (rel) => readText(registry, rel), registry)
+}
+
+const loadLicenses = async (registry: string): Promise<Record<string, LicenseEntry>> => {
+  const raw = await readText(registry, "licenses.json")
+  if (!raw) throw new Error(`assetIcon: can't reach the icon registry (${registry}). Check your connection, or set LECODES_ICON_REGISTRY.`)
+  return JSON.parse(raw) as Record<string, LicenseEntry>
+}
+
+// ---- design mode: vendoring (registry → design/assets/icons + lock + notices) --------------------
+
+type LockIcon = { pack: string, name: string, hash: string, spdx: string, path: string }
+type Lock = { registry: string, icons: Record<string, LockIcon>, packs: Record<string, LicenseEntry> }
+
+const readLock = (path: string): Lock | null => {
+  try {
+    const lock = JSON.parse(readFileSync(path, "utf8")) as Lock
+    if (lock && typeof lock === "object" && lock.icons && lock.packs) return lock
+  } catch { /* absent or corrupt → start fresh */ }
+  return null
+}
+
+/** A stable serialization: keys sorted, no timestamp — same inputs produce byte-identical output. */
+const serializeLock = (lock: Lock): string => {
+  const sortKeys = <T>(rec: Record<string, T>): Record<string, T> =>
+    Object.fromEntries(Object.keys(rec).sort().map((k) => [k, rec[k]]))
+  return JSON.stringify({ registry: lock.registry, icons: sortKeys(lock.icons), packs: sortKeys(lock.packs) }, null, 2) + "\n"
+}
+
+const renderNotices = (lock: Lock): string => {
+  const packs = [...new Set(Object.values(lock.icons).map((i) => i.pack))].sort()
+  const lines = [
+    "# Icon attribution & notices",
+    "",
+    "Icons vendored from the icon-registry via `assetIcon(...)`. Keep this file in your repo / product.",
+    "",
+  ]
+  for (const p of packs) {
+    const l = lock.packs[p]
+    if (!l) continue
+    let note = `- **${p}** — ${l.spdx}${l.url ? ` — ${l.url}` : ""}`
+    if (l.attribution) note += `\n  - **Attribution required:** ${l.attribution}`
+    if (l.modifiedNotice) note += `\n  - ${l.spdx}: state any modifications if you alter the glyphs.`
+    lines.push(note)
+  }
+  lines.push("")
+  return lines.join("\n")
+}
+
+/** Resolve `ids` to their SVG bodies, vendoring any not already on disk. Reads cached icons off disk
+ *  (no network) and only fetches the misses; then keeps icons.lock.json + ICON-NOTICES.md in sync.
+ *  Returns id → svg. Throws a clear compile error on an unknown pack / missing icon. */
+export const vendorIcons = async (
+  designDir: string,
+  ids: string[],
+  opts: { registry?: string } = {},
+): Promise<Map<string, string>> => {
+  const registry = (opts.registry ?? DEFAULT_REGISTRY).replace(/\/+$/, "")
+  const lockPath = join(designDir, "icons.lock.json")
+  const lock: Lock = readLock(lockPath) ?? { registry, icons: {}, packs: {} }
+  const svgById = new Map<string, string>()
+
+  // Serve from the on-disk vendor cache where we can; collect the rest.
+  const missing: string[] = []
+  for (const id of ids) {
+    const li = lock.icons[id]
+    const cached = li && safeRead(join(designDir, li.path))
+    if (cached) svgById.set(id, cached)
+    else missing.push(id)
+  }
+
+  if (missing.length) {
+    const licenses = await loadLicenses(registry)
+
+    for (const id of missing) {
+      const m = ICON_ID.exec(id)! // scanner validated the shape already
+      const [, pack, name] = m
+      const lic = licenses[pack]
+      if (!lic) throw new Error(`assetIcon: unknown icon pack "${pack}" (in "${id}"). Available packs: ${Object.keys(licenses).sort().join(", ")}.`)
+      const svg = await fetchIcon(registry, pack, name)
+
+      const rel = `assets/icons/${pack}/${name}.svg`
+      const abs = join(designDir, rel)
+      mkdirSync(dirname(abs), { recursive: true })
+      writeFileSync(abs, svg)
+      lock.icons[id] = { pack, name, hash: sha12(svg), spdx: lic.spdx, path: rel }
+      lock.packs[pack] = { spdx: lic.spdx, title: lic.title, url: lic.url, attribution: lic.attribution, modifiedNotice: lic.modifiedNotice }
+      svgById.set(id, svg)
+    }
+    lock.registry = registry
+    writeIfChanged(lockPath, serializeLock(lock))
+  }
+
+  // Attribution is fail-closed: notices always reflect the vendored packs (write throws → build fails).
+  if (Object.keys(lock.icons).length) writeIfChanged(join(designDir, "ICON-NOTICES.md"), renderNotices(lock))
+
+  return svgById
+}
+
+/** The design-screen compile pass: resolve + vendor every `assetIcon(...)` into the design folder
+ *  and rewrite the calls inline (mutates `entries[].text`). A no-op when nothing uses `assetIcon`. */
+export const applyAssetIcons = async (
+  entries: AssetIconEntry[],
+  designDir: string,
+  opts: { registry?: string } = {},
+): Promise<void> => {
+  await applyAssetIconMacro(entries, (ids) => vendorIcons(designDir, ids, opts))
+}
+
+// ---- app mode: the user-level icon cache ----------------------------------------------------------
+
+/** `~/.lecodes/cache/icons` — shared by every project on the machine (icons are project-independent
+ *  and immutable per id, so one fetch ever). Sits next to the CLI's other user-level state (config.ts). */
+const defaultCacheDir = () => join(homedir(), ".lecodes", "cache", "icons")
+
+/** Resolve `ids` via the user-level cache, fetching misses from the registry. No lock, no notices,
+ *  no project writes (see the header comment). Returns id → svg. */
+export const cacheIcons = async (
+  ids: string[],
+  opts: { registry?: string, cacheDir?: string } = {},
+): Promise<Map<string, string>> => {
+  const registry = (opts.registry ?? DEFAULT_REGISTRY).replace(/\/+$/, "")
+  const cacheDir = opts.cacheDir ?? defaultCacheDir()
+  const svgById = new Map<string, string>()
+
+  for (const id of ids) {
+    const [, pack, name] = ICON_ID.exec(id)! // scanner validated the shape already
+    const cachePath = join(cacheDir, pack, `${name}.svg`)
+    const cached = safeRead(cachePath)
+    if (cached) { svgById.set(id, cached); continue }
+
+    const svg = await fetchIcon(registry, pack, name)
+    mkdirSync(dirname(cachePath), { recursive: true })
+    writeFileSync(cachePath, svg)
+    svgById.set(id, svg)
+  }
+  return svgById
+}
+
+/** The app-compile pass (`compile`/`dev`/`render`/`test`): resolve every `assetIcon(...)` — icons
+ *  the design flow already vendored into the tree (`…assets/icons/**`) first, then the user-level
+ *  cache — and rewrite the calls inline (mutates `entries[].text`). Returns the `// icons:` header
+ *  payload (distinct packs), or undefined when the project uses no icons. */
+export const applyAppAssetIcons = async (
+  entries: AssetIconEntry[],
+  opts: { registry?: string, cacheDir?: string } = {},
+): Promise<string | undefined> => {
+  const ids = await applyAssetIconMacro(entries, async (wanted) => {
+    const vendored = collectVendoredIcons(entries)
+    const misses = wanted.filter((id) => !vendored.has(id))
+    const fetched = misses.length ? await cacheIcons(misses, opts) : new Map<string, string>()
+    return new Map(wanted.map((id) => [id, vendored.get(id) ?? fetched.get(id)!]))
+  })
+  return ids.length ? buildIconsHeaderValue(ids) : undefined
+}