lecodes-cli 0.5.3 → 0.6.0

package/dist/index.js

@@ -3,12 +3,12 @@ import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/index.ts
-import { readFileSync as readFileSync11 } from "node:fs";
-import { dirname as dirname7, join as join12 } from "node:path";
-import { fileURLToPath as fileURLToPath3 } from "node:url";
+import { readFileSync as readFileSync13 } from "node:fs";
+import { dirname as dirname8, join as join13 } from "node:path";
+import { fileURLToPath as fileURLToPath4 } from "node:url";
 
 // src/commands/clone.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync5, readdirSync } from "node:fs";
+import { existsSync as existsSync4, mkdirSync as mkdirSync5, readdirSync } from "node:fs";
 import { resolve } from "node:path";
 
 // src/util.ts
@@ -286,7 +286,8 @@ var materializeAssets = async (root, project, apiUrl, token, onProgress) => {
 
 // src/types.ts
 import { dirname as dirname3, join as join4 } from "node:path";
-import { mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { existsSync as existsSync2, mkdirSync as mkdirSync4, readFileSync as readFileSync3, writeFileSync as writeFileSync4 } from "node:fs";
 var TSCONFIG = {
   compilerOptions: {
     target: "ES2020",
@@ -303,8 +304,7 @@ var TSCONFIG = {
   include: [`${LECODES_DIR}/types/**/*.d.ts`, "**/*.ts", "**/*.js"],
   exclude: ["node_modules"]
 };
-var materializeTypes = async (root, apiUrl) => {
-  const bundle = await getTypes(apiUrl);
+var writeTypeBundle = (root, bundle) => {
   const typesDir = join4(root, LECODES_DIR, "types");
   for (const [path, text] of Object.entries(bundle)) {
     const dest = join4(typesDir, path);
@@ -312,12 +312,37 @@ var materializeTypes = async (root, apiUrl) => {
     writeFileSync4(dest, text);
   }
 };
+var materializeTypes = async (root, apiUrl) => {
+  writeTypeBundle(root, await getTypes(apiUrl));
+};
+var readLocalTypeBundle = () => {
+  const here = dirname3(fileURLToPath(import.meta.url));
+  const candidates = [
+    join4(here, "..", "runtime", "sdk-types.json"),
+    join4(here, "..", "..", "sdk", "dist", "types.json")
+  ];
+  for (const path of candidates) {
+    if (existsSync2(path)) {
+      try {
+        return JSON.parse(readFileSync3(path, "utf8"));
+      } catch {}
+    }
+  }
+  return null;
+};
+var materializeTypesLocal = (root) => {
+  const bundle = readLocalTypeBundle();
+  if (!bundle)
+    return false;
+  writeTypeBundle(root, bundle);
+  return true;
+};
 var writeTsconfig = (root) => {
   writeFileSync4(join4(root, "tsconfig.json"), JSON.stringify(TSCONFIG, null, 2));
 };
 
 // src/ignore.ts
-import { existsSync as existsSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync5 } from "node:fs";
+import { existsSync as existsSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync5 } from "node:fs";
 import { join as join5 } from "node:path";
 var BUILTIN_PATTERNS = ["node_modules/", ".git/", "_*", "*.log", ".DS_Store"];
 var DEFAULT_IGNORE_FILE = `# Files matched here are NOT pushed to LeCodes.
@@ -395,9 +420,9 @@ var buildMatcher = (rules) => (key, isDir) => {
 var loadIgnore = (root) => {
   const lines = [...BUILTIN_PATTERNS];
   const file = join5(root, ".lecodesignore");
-  if (existsSync2(file)) {
+  if (existsSync3(file)) {
     try {
-      lines.push(...readFileSync3(file, "utf8").split(/\r?\n/));
+      lines.push(...readFileSync4(file, "utf8").split(/\r?\n/));
     } catch {}
   }
   const rules = lines.map(compile).filter((r) => r !== null);
@@ -405,7 +430,7 @@ var loadIgnore = (root) => {
 };
 var writeDefaultIgnore = (root) => {
   const file = join5(root, ".lecodesignore");
-  if (!existsSync2(file))
+  if (!existsSync3(file))
     writeFileSync5(file, DEFAULT_IGNORE_FILE);
 };
 
@@ -428,7 +453,7 @@ var clone = async (args) => {
   const project = await getProject(apiUrl, token, uuid);
   const dir = args._[1] ?? slug(project.name);
   const root = resolve(dir);
-  if (existsSync3(root) && readdirSync(root).length > 0) {
+  if (existsSync4(root) && readdirSync(root).length > 0) {
     throw new CliError(`Directory "${dir}" already exists and is not empty.`);
   }
   mkdirSync5(root, { recursive: true });
@@ -448,7 +473,7 @@ var clone = async (args) => {
 };
 
 // src/commands/create.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync6, readdirSync as readdirSync2, writeFileSync as writeFileSync6 } from "node:fs";
+import { existsSync as existsSync5, mkdirSync as mkdirSync6, readdirSync as readdirSync2, writeFileSync as writeFileSync6 } from "node:fs";
 import { join as join6, resolve as resolve2 } from "node:path";
 var slug2 = (name) => name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "project";
 var STARTER = `// Welcome to le.codes — no imports needed, the whole SDK is available as globals.
@@ -468,7 +493,7 @@ var create = async (args) => {
     throw new CliError("Usage: lecodes create <name> [directory]");
   const dir = args._[1] ?? slug2(name);
   const root = resolve2(dir);
-  if (existsSync4(root) && readdirSync2(root).length > 0) {
+  if (existsSync5(root) && readdirSync2(root).length > 0) {
     throw new CliError(`Directory "${dir}" already exists and is not empty.`);
   }
   mkdirSync6(root, { recursive: true });
@@ -486,15 +511,15 @@ var create = async (args) => {
 };
 
 // src/commands/design.ts
-import { existsSync as existsSync7, mkdirSync as mkdirSync7, readFileSync as readFileSync7, readdirSync as readdirSync5, writeFileSync as writeFileSync7, appendFileSync } from "node:fs";
-import { basename as basename2, join as join10 } from "node:path";
+import { existsSync as existsSync9, mkdirSync as mkdirSync8, readFileSync as readFileSync9, readdirSync as readdirSync5, writeFileSync as writeFileSync8, appendFileSync } from "node:fs";
+import { basename as basename2, join as join11 } from "node:path";
 
 // src/compile/designCompile.ts
-import { readFileSync as readFileSync6 } from "node:fs";
+import { readFileSync as readFileSync8 } from "node:fs";
 import { basename } from "node:path";
 
 // src/localFiles.ts
-import { readdirSync as readdirSync3, readFileSync as readFileSync4 } from "node:fs";
+import { readdirSync as readdirSync3, readFileSync as readFileSync5 } from "node:fs";
 import { join as join7, relative } from "node:path";
 var SKIP_DIRS = new Set([".lecodes", ".git", "node_modules"]);
 var SKIP_FILES = new Set(["tsconfig.json", "jsconfig.json", ".gitignore", ".lecodesignore", ".DS_Store"]);
@@ -569,7 +594,7 @@ var scanLocal = (root, opts = {}) => {
           ignored.push(key);
           continue;
         }
-        files.push({ path: key, absPath: abs, sha: sha256(readFileSync4(abs)) });
+        files.push({ path: key, absPath: abs, sha: sha256(readFileSync5(abs)) });
       }
     }
   };
@@ -603,16 +628,16 @@ var diffLocal = (manifest, scan) => {
 var hasChanges = (diff) => diff.added.length + diff.modified.length + diff.deleted.length > 0;
 
 // src/compile/projectCompile.ts
-import { existsSync as existsSync6 } from "node:fs";
+import { existsSync as existsSync7 } from "node:fs";
 import { createRequire as createRequire3 } from "node:module";
 import { dirname as dirname5, join as join9 } from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
 // ../sdk/src/compile/bundler.ts
-import { existsSync as existsSync5, readdirSync as readdirSync4, readFileSync as readFileSync5, statSync } from "node:fs";
+import { existsSync as existsSync6, readdirSync as readdirSync4, readFileSync as readFileSync6, statSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { createRequire as createRequire2 } from "node:module";
 import { dirname as dirname4, join as join8, relative as relative2 } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // ../sdk/src/compile/assetMacro.ts
 var ASSET_RE = /\basset\(\s*(["'])((?:[^"'\\]|\\.)*)\1\s*\)/g;
@@ -672,11 +697,11 @@ var classBodyDeclaresAspect = (src, from) => {
 // ../sdk/src/compile/bundler.ts
 var resolveInject = () => {
   const override = process.env.LECODES_SDK_INJECT;
-  if (override && existsSync5(override))
+  if (override && existsSync6(override))
     return override;
-  const here = dirname4(fileURLToPath(import.meta.url));
+  const here = dirname4(fileURLToPath2(import.meta.url));
   const src = join8(here, "..", "inject.ts");
-  if (existsSync5(src))
+  if (existsSync6(src))
     return src;
   throw new Error("sdk: could not locate the inject source (LECODES_SDK_INJECT / src/inject.ts)");
 };
@@ -714,7 +739,7 @@ var collectSdkFiles = (sdkSrc) => {
       if (statSync(p).isDirectory())
         walk(p);
       else if (isSdkSource(p))
-        out["/__sdk/" + relative2(sdkSrc, p).split("\\").join("/")] = readFileSync5(p, "utf8");
+        out["/__sdk/" + relative2(sdkSrc, p).split("\\").join("/")] = readFileSync6(p, "utf8");
     }
   };
   walk(sdkSrc);
@@ -724,13 +749,13 @@ var collectSdkFiles = (sdkSrc) => {
 var resolveChiselBin = () => {
   const override = process.env.LECODES_CHISEL_BIN;
   if (override) {
-    if (existsSync5(override))
+    if (existsSync6(override))
       return override;
     throw new Error(`LECODES_CHISEL_BIN points at a missing file: ${override}`);
   }
   try {
     const bin = createRequire2(import.meta.url)("@letary/chisel").binaryPath();
-    if (bin && existsSync5(bin))
+    if (bin && existsSync6(bin))
       return bin;
   } catch {}
   throw new Error("chisel binary not found. Install @letary/chisel, or set LECODES_CHISEL_BIN.");
@@ -890,9 +915,9 @@ ${inlineSourceMapComment(map)}` : code;
 ${inlineSourceMapComment(offsetSourceMap(map, headerLines))}`;
 };
 // src/compile/projectCompile.ts
-var here = dirname5(fileURLToPath2(import.meta.url));
+var here = dirname5(fileURLToPath3(import.meta.url));
 var vendoredInject = join9(here, "..", "runtime", "sdk", "inject.ts");
-if (existsSync6(vendoredInject))
+if (existsSync7(vendoredInject))
   process.env.LECODES_SDK_INJECT = vendoredInject;
 var resolveChiselBin2 = () => {
   if (process.env.LECODES_CHISEL_BIN)
@@ -916,10 +941,379 @@ var compileProject2 = (opts) => compileProject({
   localAssets: opts.localAssets
 });
 
+// src/compile/assetIcons.ts
+import { createHash as createHash2 } from "node:crypto";
+import { existsSync as existsSync8, mkdirSync as mkdirSync7, readFileSync as readFileSync7, writeFileSync as writeFileSync7 } from "node:fs";
+import { dirname as dirname6, join as join10 } from "node:path";
+var DEFAULT_REGISTRY = process.env.LECODES_ICON_REGISTRY?.trim() || "https://icon-registry.jt3.ru/v1";
+var ICON_ID = /^([a-z0-9]+(?:-[a-z0-9]+)*):([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+var isIdentStart = (c2) => c2 >= "A" && c2 <= "Z" || c2 >= "a" && c2 <= "z" || c2 === "_" || c2 === "$";
+var isIdentPart = (c2) => isIdentStart(c2) || c2 >= "0" && c2 <= "9";
+var skipString = (src, start) => {
+  const quote = src[start];
+  const n = src.length;
+  let i = start + 1;
+  while (i < n) {
+    const c2 = src[i];
+    if (c2 === "\\") {
+      i += 2;
+      continue;
+    }
+    if (quote === "`" && c2 === "$" && src[i + 1] === "{") {
+      i = skipBraces(src, i + 1);
+      continue;
+    }
+    if (c2 === quote)
+      return i + 1;
+    i++;
+  }
+  return n;
+};
+var skipBraces = (src, open) => {
+  const n = src.length;
+  let depth = 0;
+  let i = open;
+  while (i < n) {
+    const c2 = src[i];
+    if (c2 === '"' || c2 === "'" || c2 === "`") {
+      i = skipString(src, i);
+      continue;
+    }
+    if (c2 === "{")
+      depth++;
+    else if (c2 === "}") {
+      depth--;
+      if (depth === 0)
+        return i + 1;
+    }
+    i++;
+  }
+  return n;
+};
+var matchParen = (src, open) => {
+  const n = src.length;
+  let depth = 0;
+  let i = open;
+  while (i < n) {
+    const c2 = src[i];
+    if (c2 === '"' || c2 === "'" || c2 === "`") {
+      i = skipString(src, i);
+      continue;
+    }
+    if (c2 === "/" && src[i + 1] === "/") {
+      i += 2;
+      while (i < n && src[i] !== `
+`)
+        i++;
+      continue;
+    }
+    if (c2 === "/" && src[i + 1] === "*") {
+      i += 2;
+      while (i < n && !(src[i] === "*" && src[i + 1] === "/"))
+        i++;
+      i += 2;
+      continue;
+    }
+    if (c2 === "(")
+      depth++;
+    else if (c2 === ")") {
+      depth--;
+      if (depth === 0)
+        return i;
+    }
+    i++;
+  }
+  return -1;
+};
+var splitTopLevel = (text, delim) => {
+  const parts = [];
+  const n = text.length;
+  let depth = 0;
+  let last = 0;
+  let i = 0;
+  while (i < n) {
+    const c2 = text[i];
+    if (c2 === '"' || c2 === "'" || c2 === "`") {
+      i = skipString(text, i);
+      continue;
+    }
+    if (c2 === "(" || c2 === "[" || c2 === "{")
+      depth++;
+    else if (c2 === ")" || c2 === "]" || c2 === "}")
+      depth = Math.max(0, depth - 1);
+    else if (depth === 0 && c2 === delim) {
+      parts.push(text.slice(last, i));
+      last = i + 1;
+    }
+    i++;
+  }
+  parts.push(text.slice(last));
+  return parts;
+};
+var stringLiteralValue = (text) => {
+  const t = text.trim();
+  if (t.length < 2)
+    return null;
+  const q = t[0];
+  if (q !== '"' && q !== "'" && q !== "`" || t[t.length - 1] !== q)
+    return null;
+  const inner = t.slice(1, -1);
+  if (q === "`" && inner.includes("${"))
+    return null;
+  if (inner.includes(q) && !inner.includes("\\" + q))
+    return null;
+  return inner.replace(/\\(.)/g, "$1");
+};
+var scanAssetIconCalls = (source) => {
+  const calls = [];
+  const n = source.length;
+  let i = 0;
+  while (i < n) {
+    const c2 = source[i];
+    if (c2 === '"' || c2 === "'" || c2 === "`") {
+      i = skipString(source, i);
+      continue;
+    }
+    if (c2 === "/" && source[i + 1] === "/") {
+      i += 2;
+      while (i < n && source[i] !== `
+`)
+        i++;
+      continue;
+    }
+    if (c2 === "/" && source[i + 1] === "*") {
+      i += 2;
+      while (i < n && !(source[i] === "*" && source[i + 1] === "/"))
+        i++;
+      i += 2;
+      continue;
+    }
+    if (isIdentStart(c2)) {
+      let j = i + 1;
+      while (j < n && isIdentPart(source[j]))
+        j++;
+      if (source.slice(i, j) === "assetIcon" && prevNonSpace(source, i) !== ".") {
+        const call = parseCall(source, i, j);
+        if (call) {
+          calls.push(call);
+          i = call.end;
+          continue;
+        }
+      }
+      i = j;
+      continue;
+    }
+    i++;
+  }
+  return calls;
+};
+var prevNonSpace = (src, i) => {
+  let k = i - 1;
+  while (k >= 0 && /\s/.test(src[k]))
+    k--;
+  return k >= 0 ? src[k] : "";
+};
+var parseCall = (src, start, identEnd) => {
+  const n = src.length;
+  let i = identEnd;
+  while (i < n && /\s/.test(src[i]))
+    i++;
+  if (src[i] !== "(")
+    return null;
+  const close = matchParen(src, i);
+  if (close === -1)
+    return null;
+  const call = { start, end: close + 1, id: "", pack: "", name: "" };
+  const args = splitTopLevel(src.slice(i + 1, close), ",");
+  const id = stringLiteralValue(args[0] ?? "");
+  if (id === null) {
+    call.error = `assetIcon(...) needs a string-literal id like "lucide:bell" (got \`${(args[0] ?? "").trim() || "()"}\`).`;
+    return call;
+  }
+  const m = ICON_ID.exec(id);
+  if (!m) {
+    call.error = `assetIcon("${id}"): id must be "pack:name", lowercase [a-z0-9-] (e.g. "lucide:bell").`;
+    return call;
+  }
+  call.id = id;
+  call.pack = m[1];
+  call.name = m[2];
+  const optsText = args[1]?.trim();
+  if (optsText) {
+    const color = extractColor(optsText);
+    if (color.error) {
+      call.error = color.error;
+      return call;
+    }
+    if (color.bake !== undefined)
+      call.bake = color.bake;
+    else if (color.tint !== undefined)
+      call.tint = color.tint;
+  }
+  return call;
+};
+var extractColor = (optsText) => {
+  if (!optsText.startsWith("{") || !optsText.endsWith("}")) {
+    return { error: `assetIcon(id, opts): opts must be an object literal like { color: "#5b8cff" }.` };
+  }
+  for (const prop of splitTopLevel(optsText.slice(1, -1), ",")) {
+    const kv = splitTopLevel(prop, ":");
+    if (kv.length < 2)
+      continue;
+    const key = kv[0].trim().replace(/^["'`]|["'`]$/g, "");
+    if (key !== "color")
+      continue;
+    const raw = kv.slice(1).join(":").trim();
+    if (!raw)
+      continue;
+    const literal = stringLiteralValue(raw);
+    return literal !== null ? { bake: literal } : { tint: raw };
+  }
+  return {};
+};
+var rewriteAssetIcons = (source, calls, svgById) => {
+  let out = source;
+  for (const call of [...calls].sort((a, b) => b.start - a.start)) {
+    const svg = svgById.get(call.id);
+    if (svg === undefined)
+      continue;
+    out = out.slice(0, call.start) + iconExpr(svg, call) + out.slice(call.end);
+  }
+  return out;
+};
+var iconExpr = (svg, call) => {
+  const body = call.bake ? svg.split("currentColor").join(call.bake) : svg;
+  const src = `SvgSource(\`${escapeTemplate(body)}\`)`;
+  return call.tint ? `Object.assign(${src}, { tintColor: (${call.tint}) })` : src;
+};
+var escapeTemplate = (s) => s.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
+var isHttp = (s) => /^https?:/i.test(s);
+var sha12 = (s) => createHash2("sha256").update(s).digest("hex").slice(0, 12);
+var registryHome = (registry) => registry.replace(/\/v\d+$/, "");
+var readText = async (registry, rel) => {
+  if (isHttp(registry)) {
+    const res = await fetch(`${registry}/${rel}`);
+    return res.ok ? await res.text() : null;
+  }
+  try {
+    return readFileSync7(join10(registry, rel), "utf8");
+  } catch {
+    return null;
+  }
+};
+var readLock = (path) => {
+  try {
+    const lock = JSON.parse(readFileSync7(path, "utf8"));
+    if (lock && typeof lock === "object" && lock.icons && lock.packs)
+      return lock;
+  } catch {}
+  return null;
+};
+var serializeLock = (lock) => {
+  const sortKeys = (rec) => 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) + `
+`;
+};
+var renderNotices = (lock) => {
+  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 note2 = `- **${p}** — ${l.spdx}${l.url ? ` — ${l.url}` : ""}`;
+    if (l.attribution)
+      note2 += `
+  - **Attribution required:** ${l.attribution}`;
+    if (l.modifiedNotice)
+      note2 += `
+  - ${l.spdx}: state any modifications if you alter the glyphs.`;
+    lines.push(note2);
+  }
+  lines.push("");
+  return lines.join(`
+`);
+};
+var writeIfChanged = (path, text) => {
+  const current = existsSync8(path) ? safeRead(path) : null;
+  if (current === text)
+    return false;
+  writeFileSync7(path, text);
+  return true;
+};
+var safeRead = (path) => {
+  try {
+    return readFileSync7(path, "utf8");
+  } catch {
+    return null;
+  }
+};
+var vendorIcons = async (designDir, ids, opts = {}) => {
+  const registry = (opts.registry ?? DEFAULT_REGISTRY).replace(/\/+$/, "");
+  const lockPath = join10(designDir, "icons.lock.json");
+  const lock = readLock(lockPath) ?? { registry, icons: {}, packs: {} };
+  const svgById = new Map;
+  const missing = [];
+  for (const id of ids) {
+    const li = lock.icons[id];
+    const cached = li && safeRead(join10(designDir, li.path));
+    if (cached)
+      svgById.set(id, cached);
+    else
+      missing.push(id);
+  }
+  if (missing.length) {
+    const licRaw = await readText(registry, "licenses.json");
+    if (!licRaw)
+      throw new Error(`assetIcon: can't reach the icon registry (${registry}). Check your connection, or set LECODES_ICON_REGISTRY.`);
+    const licenses = JSON.parse(licRaw);
+    for (const id of missing) {
+      const m = ICON_ID.exec(id);
+      const [, pack, name] = m;
+      const lic = licenses[pack];
+      if (!lic)
+        throw new Error(`assetIcon: unknown icon pack "${pack}" (in "${id}"). Browse packs at ${registryHome(registry)}.`);
+      const svg = await readText(registry, `${pack}/${name}.svg`);
+      if (svg === null)
+        throw new Error(`assetIcon: icon "${id}" not found in the registry. Check the name at ${registryHome(registry)}.`);
+      const rel = `assets/icons/${pack}/${name}.svg`;
+      const abs = join10(designDir, rel);
+      mkdirSync7(dirname6(abs), { recursive: true });
+      writeFileSync7(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));
+  }
+  if (Object.keys(lock.icons).length)
+    writeIfChanged(join10(designDir, "ICON-NOTICES.md"), renderNotices(lock));
+  return svgById;
+};
+var applyAssetIcons = async (entries, designDir, opts = {}) => {
+  const scanned = entries.filter((e) => e.type === "text" && typeof e.text === "string" && e.text.includes("assetIcon")).map((e) => ({ entry: e, calls: scanAssetIconCalls(e.text) })).filter((s) => s.calls.length > 0);
+  if (scanned.length === 0)
+    return;
+  const errors = scanned.flatMap((s) => s.calls.filter((c2) => c2.error).map((c2) => c2.error));
+  if (errors.length)
+    throw new Error([...new Set(errors)].join(`
+`));
+  const ids = [...new Set(scanned.flatMap((s) => s.calls.map((c2) => c2.id)))];
+  const svgById = await vendorIcons(designDir, ids, opts);
+  for (const { entry, calls } of scanned)
+    entry.text = rewriteAssetIcons(entry.text, calls, svgById);
+};
+
 // src/compile/designCompile.ts
 var LOCAL_ASSET_SCHEME = "lecodesfile://";
 var compileDesignScreen = async (opts) => {
-  const { root, manifest, designKey, screenId } = opts;
+  const { root, manifest, designDir, designKey, screenId, state } = opts;
   const entries = [];
   const scan = scanLocal(root, { ignore: loadIgnore(root), tracked: new Set(Object.keys(manifest?.files ?? {})) });
   for (const file of scan.files) {
@@ -934,17 +1328,20 @@ var compileDesignScreen = async (opts) => {
     } else if (type === "shader") {
       entries.push({ path: file.path, type, shaders: [] });
     } else {
-      entries.push({ path: file.path, type, text: readFileSync6(file.absPath, "utf8") });
+      entries.push({ path: file.path, type, text: readFileSync8(file.absPath, "utf8") });
     }
   }
+  const invoke = state !== undefined ? `screen(${JSON.stringify(state)})` : "screen()";
   const entryPath = `${designKey}/.screen-entry.ts`;
   entries.push({
     path: entryPath,
     type: "text",
     text: `import screen from "./screens/${screenId}"
-screen.open()
+` + `const __screen = typeof screen === "function" ? ${invoke} : screen
+` + `__screen.open()
 `
   });
+  await applyAssetIcons(entries, designDir);
   return compileProject2({
     entries,
     name: opts.name,
@@ -1036,11 +1433,45 @@ var browserLogin = async (webBase, timeoutMs = 5 * 60 * 1000, open = openBrowser
 // src/commands/designTemplates.ts
 var META_JSON = `{
   "screens": {
-    "home": { "pos": [0, 0], "desc": "Example screen — replace me" }
+    "home": { "pos": [0, 0], "desc": "Example screen — replace me", "role": "list" }
   },
   "edges": []
 }
 `;
+var SPEC_MD = `# Concept
+
+The narrative half of this design. \`meta.json\` + the canvas hold the *visual/flow* half (screens,
+positions, edges); this file holds what never renders as a screen — the data model, the actors, and
+the rules & decisions behind them. Prose, not schema. **Half-filled is fine** — fill it in as the
+design firms up. This is where the concept you'd otherwise keep in chat lives.
+
+Link a screen with \`[[screen-id]]\` (its file name). \`lecodes design check\` warns when a link names
+a screen that doesn't exist.
+
+## Data model
+
+The entities the app is about, and their fields. The mock data at the top of each screen file is the
+first draft of this — promote the entities that stabilize here (one table each).
+
+<!--
+### Task
+| field | type | notes |
+|-------|------|-------|
+| id    | string  |                 |
+| title | string  |                 |
+| done  | boolean | defaults to false |
+-->
+
+## Actors
+
+Who uses the app, and what each is allowed to do. (Different from a screen's \`role\` in meta.json,
+which is the screen's *kind* — list, detail, form…)
+
+## Rules & decisions
+
+Behaviour that isn't visible in a single screen — validation, permissions, notifications, edge
+cases — and the decisions you've made and why, so they aren't re-litigated later.
+`;
 var TOKENS_TS = `// Design tokens shared by every screen. Colors are hex strings (the engine parses hex only).
 export const colors = {
   bg: "#101114",
@@ -1110,24 +1541,60 @@ This is an intent-capture stage — screens run on inline mock data, before any
 
 \`meta.json\` is the app map: every screen (position, description) and the edges between them
 (navigation intent). **Read it before opening any screen file.** It is the human's file — the
-canvas and the developer own positions and descriptions. You MAY add entries for new screens you
-create (pick a free position: screens are 390×844, leave ~160px gaps) and add edges when the flow
-is clear, but never reposition or rewrite existing human-authored descriptions.
+canvas and the developer own positions and descriptions. When you create a screen, add its meta
+entry **without a \`pos\`** and add edges — the board **auto-places it next to its flow neighbours**,
+so you never hand-pick coordinates (you can't see the board, and positions are the human's to own).
+\`lecodes design arrange --new\` optionally writes those auto-placements into meta.json; the developer's
+⇥ Arrange button re-tidies the whole board. Never reposition or rewrite existing human-authored
+positions or descriptions.
 
 \`\`\`json
 {
-  "screens": { "login": { "pos": [0, 0], "desc": "Phone login" } },
-  "edges": [ { "from": "login", "to": "code", "label": "after phone entry", "activator": "submit" } ]
+  "screens": {
+    "login": { "desc": "Phone login", "group": "Onboarding", "role": "auth" },
+    "code": { "group": "Onboarding", "role": "auth" }
+  },
+  "groups": { "Onboarding": { "desc": "First-run flow" } },
+  "edges": [
+    { "from": "login", "to": "code", "label": "after phone entry", "activator": "submit" },
+    { "from": "code", "to": "home@empty", "label": "first sign-in" }
+  ]
 }
 \`\`\`
 
 - An edge's optional \`activator\` names the element (its \`name\` style option) that triggers the
   transition. Give a \`name\` to interactive elements an edge refers to — nothing else needs names.
+- **Group each screen** you create by its user-facing area — \`"group": "Onboarding"\` — 2–6 screens
+  per group (Onboarding, Checkout, Settings…). Groups render as labeled regions and \`arrange\` lays
+  each out as its own sub-flow, so grouping keeps big boards legible. Semantic clustering is your
+  job (you're good at it); coordinates are \`arrange\`'s (it can see the board, you can't). Don't
+  regroup existing screens unless asked — groups are part of the human's map.
+- **Tag a screen's \`role\`** in its meta entry — its *kind* (\`list\`, \`detail\`, \`form\`, \`auth\`,
+  \`modal\`…). Optional, renders on the board, captures concept the screen source can't;
+  \`lecodes design check\` lists screens still untagged (never blocking). *(A screen's **states** are
+  a separate thing — declared in the source, not meta; see "Screen states" below.)*
+
+## The concept — spec.md
+
+\`meta.json\` + the canvas are the *visual/flow* half of the design; \`spec.md\` is the *narrative*
+half — what never renders as a screen and doesn't fit meta.json: the **data model** (entities +
+fields), the **actors** (who uses the app + their permissions), and the **rules & decisions**
+(validation, edge cases, and the choices behind them). Write down here what you'd otherwise only
+keep in the chat.
+
+- It's prose (markdown), co-owned by you and the developer — edit it with your normal Read/Edit
+  (there's no board writer for it). Half-filled is fine.
+- The **mock data at the top of each screen is the first draft of the data model** — promote the
+  entities that stabilize into spec.md's tables.
+- Link a screen with \`[[screen-id]]\`. \`lecodes design check\` (and the \`check_concept\` MCP tool)
+  warn when a link names a screen that doesn't exist, and list screens with no \`role\` yet —
+  coherence, never a blocker.
 
 ## Screen rules
 
-- **One file = one screen.** \`screens/<id>.ts\` default-exports an already-computed screen:
-  \`export default UIScreen([ … ]).style({ … })\`. The filename is the screen's identity.
+- **One file = one screen.** \`screens/<id>.ts\` default-exports a screen — either a value
+  (\`export default UIScreen([ … ]).style({ … })\`) or a **function of state** for multi-state
+  screens (see "Screen states" below). The filename is the screen's identity.
 - **Styles go through the chained \`.style({ … })\` method** — e.g.
   \`UIText("Today").style({ fontSize: 28, fontWeight: 700 })\`. Passing a style object as the
   first argument is a legacy form.
@@ -1139,28 +1606,111 @@ is clear, but never reposition or rewrite existing human-authored descriptions.
   every screen. Promoting a repeated pattern into \`shared/\` is an explicit, deliberate step.
 - The LeCodes UI API (\`UIScreen\`, \`UIColumn\`, \`UIRow\`, \`UIBox\`, \`UIText\`, \`UIImage\`,
   \`UIButton\`, \`UIInput\`, \`UISpacer\`, \`UIScrollable\`, …) is **global** — no imports needed.
-  Colors must be hex strings.
+  Colors must be hex strings. This folder ships a \`tsconfig.json\` + bundled SDK types
+  (\`.lecodes/types/\`), so the editor resolves those globals — and \`UINode\` / \`UINodeChild\` for
+  typing a component's return value or a container's children — with no imports. Trust the types;
+  don't fall back to \`any\`.
+
+## Screen states (variants)
+
+A screen often has more than one look — a list vs. its empty state, a form vs. its error state.
+Instead of a second file per variant, make the default export a **function of a state string whose
+type is a string-literal union** — the union IS the state list (no separate schema):
+
+\`\`\`ts
+export default (state: "default" | "empty" = "default") => UIScreen([
+  Header(child),
+  state === "empty" ? EmptyState("Nothing here yet") : UIScrollable(items.map(Card)),
+  TabBar(tabs, "home"),
+])
+\`\`\`
+
+- The **union members are the states**, in written order. It may be written inline (as above) or as
+  a named alias in the same file (\`type State = "default" | "empty"; export default (s: State) => …\`).
+  Give the parameter a **default** (\`= "default"\`) — that's the *canonical* state (what a bare
+  render, snapshot, and the board's initial view show). No default → the first member is canonical.
+- When the data differs per state, derive it from \`state\` at the top of the function — then it's
+  just layout: \`const items = state === "empty" ? [] : MOCK\`.
+- State ids are lowercase \`[a-z0-9-]\` (filename-safe, no \`@\`). A value export — or a function whose
+  parameter isn't a literal union — is a single state named \`default\` (fully backward compatible).
+- **Check a state:** \`render_screen\` takes a \`state\`; the board shows a switcher on multi-state
+  screens; \`lecodes design snapshot <id> --state <name>\` / \`--all-states\` write \`<id>@<state>.png\`.
+- **Edges can target a state:** an edge's \`to\` (or \`from\`) may be \`"<id>@<state>"\` (e.g.
+  \`"home@empty"\`) — still one node per screen. \`lecodes design check\` errors on an edge pointing at
+  a state the screen doesn't declare.
+
+## Icons
+
+Use real icons instead of emoji. \`assetIcon("pack:name")\` is a **compile-time macro**: it vendors
+one SVG from the icon registry at build time and returns an image source (like \`SvgSource(...)\`), so
+screens render offline and deterministically in headless snapshots — no network at render time.
+
+\`\`\`ts
+UIImage(assetIcon("lucide:bell", { color: colors.accent })).style({ width: 24, height: 24 })
+UIImage(assetIcon("lucide:check")).style({ width: 20, height: 20, tintColor: colors.muted })
+\`\`\`
+
+- Pass the result straight to \`UIImage(...)\`. Recolor it with the \`{ color }\` option — a hex **literal**
+  is baked into the SVG at compile time, a **token/expression** (\`{ color: colors.accent }\`) is applied
+  as a tint — or with the \`tintColor\` **style** prop (\`.style({ tintColor: … })\`; there is no
+  \`.tintColor()\` method). All of these render colored in headless snapshots. The \`"pack:name"\` id must
+  be a **string literal** (it's resolved at compile time).
+- Browse packs and names at **https://icon-registry.jt3.ru**. Common packs: \`lucide\`, \`tabler\`,
+  \`heroicons\`, \`feather\`, \`bi\`, \`carbon\`.
+- Vendored SVGs land in \`assets/icons/\`, tracked by \`icons.lock.json\` + \`ICON-NOTICES.md\`
+  (attribution) — **commit these**; they make rebuilds offline. An unknown \`pack:name\` is a clear
+  compile error.
 
 ## See what you built
 
 The developer watches the canvas live (screens hot-reload on save). To see a screen yourself:
 
+**When the design server is running (it usually is), prefer the MCP tools** — they use the
+server's warm compile cache and return images inline, no files on disk:
+
+- \`render_screen\` (id, format: json | png | both, state?) — what a screen actually looks like
+  (pass \`state\` to render a specific state; default is canonical).
+- \`check_screens\` (ids?) — fast compile check after an edit batch; no render.
+- \`check_concept\` — spec.md ↔ screens coherence + which screens still lack a \`role\`.
+- \`design_state\` — the live screens + edges (fresher than re-reading meta.json).
+- \`board_activity\` (since?) — what the developer just did on the canvas + which screen is
+  selected; call it at the start of a turn.
+
+Fall back to the CLI when the tools report the server is down:
+
 \`\`\`sh
-lecodes design snapshot <id>          # semantic JSON of the laid-out screen → stdout
-lecodes design snapshot <id> --png    # + PNG screenshot → design/.snapshots/<id>.png
-lecodes design snapshot               # all screens → design/.snapshots/
+lecodes design snapshot <id>              # semantic JSON of the laid-out screen → stdout
+lecodes design snapshot <id> --png        # + PNG screenshot → design/.snapshots/<id>.png
+lecodes design snapshot <id> --state empty  # one state → design/.snapshots/<id>@empty.png|.json
+lecodes design snapshot <id> --all-states   # every state → design/.snapshots/<id>@<state>.png|.json
+lecodes design snapshot                   # all screens → design/.snapshots/
+lecodes design check                      # concept + flow coherence (spec.md links, states, untagged)
 \`\`\`
 
-Snapshot after every screen you create or change, and fix what looks wrong (overflow, overlap,
-unreadable contrast, off-screen content) before reporting back.
+Either way: after every screen you create or change, look at it and fix what's wrong (overflow,
+overlap, unreadable contrast, off-screen content) before reporting back.
 
 ## Workflow
 
-1. Read \`meta.json\`, then the \`shared/\` signatures, then only the screens you need.
-2. Create/edit screen files; register new screens (and clear edges) in \`meta.json\`.
-3. Snapshot → verify → fix.
-4. When the developer edits a description or the flow on the canvas, treat meta.json as the
-   updated spec.
+1. \`board_activity\` (if the server is up), then read \`meta.json\`, the \`shared/\` signatures, and
+   only the screens you need.
+2. Create/edit screen files; register new screens in \`meta.json\` **without \`pos\`** and add edges —
+   they auto-place next to their neighbours on the board. (\`lecodes design arrange --new\` commits
+   those positions to meta.json if you want them written.)
+3. \`check_screens\` → \`render_screen\` (or \`lecodes design snapshot\`) → verify → fix.
+4. When the developer edits a description, text, or the flow on the canvas — visible in
+   \`board_activity\` and in \`meta.json\`/the screen source — treat it as the updated spec.
+`;
+var DESIGN_MACROS_DTS = `// Generated by \`lecodes design init\`. Globals the design compiler resolves — not shipped SDK runtime.
+
+/**
+ * Vendor one icon from the icon registry at build time and return an image source (the same shape
+ * SvgSource(...) returns). \`id\` is "pack:name" (e.g. "lucide:bell"); pass the result to UIImage(...).
+ * Recolor with the { color } option — a hex literal is baked into the SVG, a token
+ * (\`{ color: colors.accent }\`) is applied as a tint — or the \`tintColor\` style prop. The id must be a
+ * string literal (resolved, and the SVG vendored, at compile time).
+ */
+declare function assetIcon(id: string, opts?: { color?: string }): { readonly svg: string, tintColor: string | null }
 `;
 var README_HINT = `# design/
 
@@ -1187,48 +1737,72 @@ var getContext = (args) => {
     manifest,
     name: manifest?.name ?? basename2(root),
     dirName,
-    designDir: join10(root, dirName),
+    designDir: join11(root, dirName),
     designKey: "/" + dirName.replace(/\\/g, "/")
   };
 };
 var listScreens = (designDir) => {
-  const dir = join10(designDir, "screens");
-  if (!existsSync7(dir))
+  const dir = join11(designDir, "screens");
+  if (!existsSync9(dir))
     return [];
   return readdirSync5(dir).filter((f) => f.endsWith(".ts") && !f.startsWith(".")).map((f) => f.slice(0, -3)).sort();
 };
 var readMetaSizes = (designDir) => {
   try {
-    const meta = JSON.parse(readFileSync7(join10(designDir, "meta.json"), "utf8"));
+    const meta = JSON.parse(readFileSync9(join11(designDir, "meta.json"), "utf8"));
     return meta?.screens ?? {};
   } catch {
     return {};
   }
 };
-var init = async (ctx) => {
+var writeMcpConfig = (ctx, port) => {
+  const path = join11(ctx.root, ".mcp.json");
+  const entry = { type: "http", url: `http://localhost:${port}/mcp` };
+  let config = {};
+  if (existsSync9(path)) {
+    try {
+      config = JSON.parse(readFileSync9(path, "utf8"));
+    } catch {
+      warnErr(".mcp.json exists but isn't valid JSON — left it untouched. Add the lecodes-design server by hand.");
+      return;
+    }
+  }
+  config.mcpServers ??= {};
+  const existing = config.mcpServers["lecodes-design"];
+  if (existing?.url === entry.url) {
+    note("kept      .mcp.json (lecodes-design MCP server)");
+    return;
+  }
+  config.mcpServers["lecodes-design"] = entry;
+  writeFileSync8(path, JSON.stringify(config, null, 2) + `
+`);
+  log(`${c.green(existing ? "updated" : "created")}   .mcp.json (lecodes-design MCP → ${entry.url})`);
+};
+var init = async (ctx, args) => {
   const files = [
     ["meta.json", META_JSON],
+    ["spec.md", SPEC_MD],
     ["README.md", README_HINT],
     ["CLAUDE.md", CLAUDE_MD],
-    [join10("shared", "tokens.ts"), TOKENS_TS],
-    [join10("screens", "home.ts"), HOME_SCREEN_TS]
+    [join11("shared", "tokens.ts"), TOKENS_TS],
+    [join11("screens", "home.ts"), HOME_SCREEN_TS]
   ];
-  mkdirSync7(join10(ctx.designDir, "screens"), { recursive: true });
-  mkdirSync7(join10(ctx.designDir, "shared"), { recursive: true });
+  mkdirSync8(join11(ctx.designDir, "screens"), { recursive: true });
+  mkdirSync8(join11(ctx.designDir, "shared"), { recursive: true });
   let created = 0;
   for (const [rel, content] of files) {
-    const abs = join10(ctx.designDir, rel);
-    if (existsSync7(abs)) {
+    const abs = join11(ctx.designDir, rel);
+    if (existsSync9(abs)) {
       note(`kept      ${ctx.dirName}/${rel.replace(/\\/g, "/")}`);
       continue;
     }
-    writeFileSync7(abs, content);
+    writeFileSync8(abs, content);
     log(`${c.green("created")}   ${ctx.dirName}/${rel.replace(/\\/g, "/")}`);
     created++;
   }
-  const ignorePath = join10(ctx.root, ".lecodesignore");
+  const ignorePath = join11(ctx.root, ".lecodesignore");
   const ignoreLine = `${ctx.dirName}/.snapshots/`;
-  const current = existsSync7(ignorePath) ? readFileSync7(ignorePath, "utf8") : "";
+  const current = existsSync9(ignorePath) ? readFileSync9(ignorePath, "utf8") : "";
   if (!current.split(/\r?\n/).includes(ignoreLine)) {
     appendFileSync(ignorePath, (current && !current.endsWith(`
 `) ? `
@@ -1236,6 +1810,14 @@ var init = async (ctx) => {
 `);
     log(`${c.green("ignored")}   ${ignoreLine} (in .lecodesignore)`);
   }
+  writeMcpConfig(ctx, Number(flagStr(args, "port")) || DEFAULT_PORT);
+  const wroteTypes = materializeTypesLocal(ctx.designDir);
+  writeTsconfig(ctx.designDir);
+  mkdirSync8(join11(ctx.designDir, ".lecodes", "types"), { recursive: true });
+  writeFileSync8(join11(ctx.designDir, ".lecodes", "types", "design-macros.d.ts"), DESIGN_MACROS_DTS);
+  log(`${c.green("created")}   ${ctx.dirName}/tsconfig.json${wroteTypes ? ` + ${ctx.dirName}/.lecodes/types/` : ""}  (IDE types)`);
+  if (!wroteTypes)
+    warnErr("Bundled SDK types not found — tsconfig written, but globals may show unresolved until the CLI is rebuilt with vendored types.");
   log("");
   log(created ? "Design canvas ready." : "Design canvas already initialized.");
   log(`  ${c.bold("lecodes design")}                start the canvas (browser)`);
@@ -1252,12 +1834,28 @@ var snapshot = async (ctx, args) => {
       throw new CliError(`No screen "${id}" (have: ${all.join(", ")}).`);
   }
   const targets = requested.length ? requested : all;
+  const stateFlag = flagStr(args, "state");
+  const allStates = flagBool(args, "all-states");
+  if (stateFlag !== undefined && allStates)
+    throw new CliError("Use either --state <name> or --all-states, not both.");
   let renderer;
   try {
     renderer = await import("lecodes-renderer/headless");
   } catch {
     throw new CliError("The renderer isn't installed. Run:  npm i -D lecodes-renderer");
   }
+  let discover = null;
+  if (stateFlag !== undefined || allStates) {
+    try {
+      const ds = await import("lecodes-design/server");
+      discover = (src) => {
+        const d = ds.discoverScreenStates(src);
+        return { states: d.states, canonical: d.canonical };
+      };
+    } catch {
+      throw new CliError("Rendering specific states needs the design canvas. Run:  npm i -D lecodes-design");
+    }
+  }
   const killer = setTimeout(() => {
     warnErr("Snapshot timed out after 120s.");
     process.exit(1);
@@ -1265,45 +1863,68 @@ var snapshot = async (ctx, args) => {
   killer.unref?.();
   const png = flagBool(args, "png") || flagStr(args, "png") !== undefined;
   const sizes = readMetaSizes(ctx.designDir);
-  const outDir = flagStr(args, "out-dir") ?? join10(ctx.designDir, ".snapshots");
-  const single = targets.length === 1 && requested.length === 1 && !png && !flagStr(args, "out-dir");
+  const outDir = flagStr(args, "out-dir") ?? join11(ctx.designDir, ".snapshots");
+  const single = targets.length === 1 && requested.length === 1 && !png && !allStates && !flagStr(args, "out-dir");
   const onConsole = flagBool(args, "logs") ? (level, text) => logErr(`${c.dim(`[${level}]`)} ${text}`) : undefined;
   if (!single)
-    mkdirSync7(outDir, { recursive: true });
+    mkdirSync8(outDir, { recursive: true });
   for (const id of targets) {
-    note(`Rendering ${id}…`);
-    const js = await compileDesignScreen({
-      root: ctx.root,
-      manifest: ctx.manifest,
-      name: ctx.name,
-      designKey: ctx.designKey,
-      screenId: id,
-      assets: "disk"
-    });
     const [width, height] = sizes[id]?.size ?? [390, 844];
-    const result = await renderer.renderToJson(js, { width, height, localAssets: true, onConsole });
-    for (const w of result.warnings)
-      warnErr(`${id}: ${w}`);
-    if (single) {
-      const text = result.text.endsWith(`
+    let plan = [{ state: undefined, bases: [id] }];
+    if (discover) {
+      const { states, canonical } = discover(readFileSync9(join11(ctx.designDir, "screens", `${id}.ts`), "utf8"));
+      if (stateFlag !== undefined) {
+        if (!states.includes(stateFlag)) {
+          if (requested.length === 1)
+            throw new CliError(`No state "${stateFlag}" on ${id} (has: ${states.join(", ")}).`);
+          warnErr(`${id}: no state "${stateFlag}" (has: ${states.join(", ")}) — skipped.`);
+          continue;
+        }
+        plan = [{ state: stateFlag, bases: [`${id}@${stateFlag}`] }];
+      } else {
+        plan = states.map((st) => ({ state: st, bases: st === canonical ? [`${id}@${st}`, id] : [`${id}@${st}`] }));
+      }
+    }
+    for (const { state, bases } of plan) {
+      const tag = state ? `${id}@${state}` : id;
+      note(`Rendering ${tag}…`);
+      const js = await compileDesignScreen({
+        root: ctx.root,
+        manifest: ctx.manifest,
+        name: ctx.name,
+        designDir: ctx.designDir,
+        designKey: ctx.designKey,
+        screenId: id,
+        state,
+        assets: "disk"
+      });
+      const result = await renderer.renderToJson(js, { width, height, localAssets: true, onConsole });
+      for (const w of result.warnings)
+        warnErr(`${tag}: ${w}`);
+      if (single) {
+        const text = result.text.endsWith(`
 `) ? result.text : result.text + `
 `;
-      process.stdout.write(text);
-      return;
-    }
-    writeFileSync7(join10(outDir, `${id}.json`), result.text);
-    log(`${c.green("✓")} ${id} → ${join10(outDir, `${id}.json`)}`);
-    if (png) {
-      const pngResult = await renderer.renderToPng(js, { width, height, localAssets: true, scale: 2, onConsole });
-      for (const w of pngResult.warnings)
-        warnErr(`${id}: ${w}`);
-      writeFileSync7(join10(outDir, `${id}.png`), pngResult.png);
-      log(`${c.green("✓")} ${id} → ${join10(outDir, `${id}.png`)}`);
+        process.stdout.write(text);
+        return;
+      }
+      const pngResult = png ? await renderer.renderToPng(js, { width, height, localAssets: true, scale: 2, onConsole }) : null;
+      if (pngResult)
+        for (const w of pngResult.warnings)
+          warnErr(`${tag}: ${w}`);
+      for (const base of bases) {
+        writeFileSync8(join11(outDir, `${base}.json`), result.text);
+        log(`${c.green("✓")} ${tag} → ${join11(outDir, `${base}.json`)}`);
+        if (pngResult) {
+          writeFileSync8(join11(outDir, `${base}.png`), pngResult.png);
+          log(`${c.green("✓")} ${tag} → ${join11(outDir, `${base}.png`)}`);
+        }
+      }
     }
   }
 };
 var serve = async (ctx, args) => {
-  if (!existsSync7(ctx.designDir)) {
+  if (!existsSync9(ctx.designDir)) {
     throw new CliError(`No ${ctx.dirName}/ folder here. Run "lecodes design init" to scaffold it.`);
   }
   let designServer;
@@ -1313,30 +1934,86 @@ var serve = async (ctx, args) => {
     throw new CliError("The design canvas isn't installed. Run:  npm i -D lecodes-design");
   }
   const port = Number(flagStr(args, "port")) || DEFAULT_PORT;
+  let renderer = null;
+  try {
+    renderer = await import("lecodes-renderer/headless");
+  } catch {
+    renderer = null;
+  }
+  const renderScreen = renderer ? async (id, format, state) => {
+    const r = renderer;
+    const js = await compileDesignScreen({
+      root: ctx.root,
+      manifest: ctx.manifest,
+      name: ctx.name,
+      designDir: ctx.designDir,
+      designKey: ctx.designKey,
+      screenId: id,
+      state,
+      assets: "disk"
+    });
+    const [width, height] = readMetaSizes(ctx.designDir)[id]?.size ?? [390, 844];
+    const warnings = [];
+    let json;
+    let png;
+    if (format === "json" || format === "both") {
+      const res = await r.renderToJson(js, { width, height, localAssets: true });
+      json = res.text;
+      warnings.push(...res.warnings);
+    }
+    if (format === "png" || format === "both") {
+      const res = await r.renderToPng(js, { width, height, localAssets: true, scale: 2 });
+      png = res.png;
+      warnings.push(...res.warnings);
+    }
+    return { json, png, warnings };
+  } : undefined;
   const server = await designServer.startDesignServer({
     root: ctx.root,
     designDir: ctx.designDir,
     name: ctx.name,
     port,
     log: note,
-    compileScreen: async (id) => ({
+    compileScreen: async (id, state) => ({
       js: await compileDesignScreen({
         root: ctx.root,
         manifest: ctx.manifest,
         name: ctx.name,
+        designDir: ctx.designDir,
         designKey: ctx.designKey,
         screenId: id,
+        state,
         assets: "server"
       }),
       warnings: []
-    })
+    }),
+    renderScreen
   });
   log(`${c.bold("LeCodes Design")} — ${ctx.name}`);
   log(`Canvas:   ${c.bold(server.url)}`);
+  log(`MCP:      ${c.bold(server.url + "/mcp")}${renderer ? "" : c.dim("  (render_screen off — npm i -D lecodes-renderer)")}`);
   log(`Watching: ${ctx.dirName}/  (screens hot-reload on save; Ctrl+C to stop)`);
   if (!flagBool(args, "no-open"))
     openBrowser(server.url);
 };
+var arrange = async (ctx, args) => {
+  if (!existsSync9(ctx.designDir)) {
+    throw new CliError(`No ${ctx.dirName}/ folder here. Run "lecodes design init" to scaffold it.`);
+  }
+  let designServer;
+  try {
+    designServer = await import("lecodes-design/server");
+  } catch {
+    throw new CliError("The design canvas isn't installed. Run:  npm i -D lecodes-design");
+  }
+  const onlyNew = flagBool(args, "new");
+  const summary = designServer.arrangeDesign(ctx.designDir, { onlyNew });
+  if (!summary.changed) {
+    log(onlyNew ? "No unplaced screens — nothing to arrange." : "Already tidy — the current layout wins, nothing moved.");
+    return;
+  }
+  log(`${c.green("✓")} ${onlyNew ? "Placed" : "Arranged"} ${summary.moved} screen${summary.moved === 1 ? "" : "s"} in ${ctx.dirName}/meta.json.`);
+};
 var share = async (ctx, args) => {
   if (!ctx.manifest) {
     throw new CliError("`lecodes design share` needs a cloned project. Run it inside one, and push the design first (lecodes push).");
@@ -1355,22 +2032,73 @@ var share = async (ctx, args) => {
   log(`  ${c.bold(res.url ?? "")}`);
   note("Turn it off with:  lecodes design share --off");
 };
+var check = async (ctx, args) => {
+  if (!existsSync9(ctx.designDir)) {
+    throw new CliError(`No ${ctx.dirName}/ folder here. Run "lecodes design init" to scaffold it.`);
+  }
+  let designServer;
+  try {
+    designServer = await import("lecodes-design/server");
+  } catch {
+    throw new CliError("The design canvas isn't installed. Run:  npm i -D lecodes-design");
+  }
+  const state = designServer.readDesignState(ctx.designDir);
+  const concept = designServer.conceptReport(ctx.designDir, state.screens);
+  if (state.warnings.length) {
+    log(c.bold(`Warnings (${state.warnings.length})`));
+    for (const w of state.warnings)
+      log(`  ${c.yellow("!")} ${w}`);
+    log("");
+  }
+  log(c.bold("Concept"));
+  log(`  spec.md:  ${concept.hasSpec ? c.green("present") : c.dim("missing (optional)")}`);
+  if (concept.screenRefs.length) {
+    const resolved = concept.screenRefs.filter((r) => r.exists).length;
+    log(`  [[links]]: ${resolved}/${concept.screenRefs.length} resolve`);
+  }
+  if (concept.screensWithoutRole.length)
+    log(`  ${c.dim("no role:")} ${concept.screensWithoutRole.join(", ")}`);
+  log("");
+  const stateful = state.screens.filter((s) => s.states.length > 1);
+  const undiscoverable = state.screens.filter((s) => s.statesWarning);
+  if (stateful.length || undiscoverable.length) {
+    log(c.bold("States"));
+    for (const s of stateful) {
+      log(`  ${s.id}: ${s.states.map((st) => st === s.canonical ? c.green(st) : st).join(", ")}`);
+    }
+    for (const s of undiscoverable)
+      log(`  ${c.yellow("!")} ${s.id}: ${s.statesWarning}`);
+    log("");
+  }
+  const hard = state.warnings.length;
+  if (hard === 0) {
+    const n = state.screens.length;
+    log(`${c.green("✓")} No coherence problems${n ? ` across ${n} screen${n === 1 ? "" : "s"}` : ""}.`);
+    return;
+  }
+  log(`${c.red("✗")} ${hard} coherence warning${hard === 1 ? "" : "s"} — see above.`);
+  process.exitCode = 1;
+};
 var design = async (args) => {
   const sub = args._[0] ?? "serve";
   const ctx = getContext(args);
   if (sub === "serve")
     return serve(ctx, args);
   if (sub === "init")
-    return init(ctx);
+    return init(ctx, args);
   if (sub === "snapshot")
     return snapshot(ctx, args);
+  if (sub === "arrange")
+    return arrange(ctx, args);
+  if (sub === "check")
+    return check(ctx, args);
   if (sub === "share")
     return share(ctx, args);
-  throw new CliError(`Unknown design subcommand "${sub}" (serve | init | snapshot | share).`);
+  throw new CliError(`Unknown design subcommand "${sub}" (serve | init | snapshot | arrange | check | share).`);
 };
 
 // src/serverDiff.ts
-import { readFileSync as readFileSync8 } from "node:fs";
+import { readFileSync as readFileSync10 } from "node:fs";
 import { basename as basename3 } from "node:path";
 var isTextAsset = (t) => t === "text" || t === "shader" || t === "scene";
 var computeServerDiff = (project, scan) => {
@@ -1389,7 +2117,7 @@ var computeServerDiff = (project, scan) => {
     const local = localByPath.get(path);
     if (local && !server) {
       const text = isTextKind(classifyKind(basename3(path)));
-      entries.push({ path, status: "added", binary: !text, serverText: "", localText: text ? readFileSync8(local.absPath, "utf8") : undefined });
+      entries.push({ path, status: "added", binary: !text, serverText: "", localText: text ? readFileSync10(local.absPath, "utf8") : undefined });
       continue;
     }
     if (server && !local) {
@@ -1400,12 +2128,12 @@ var computeServerDiff = (project, scan) => {
     if (server && local) {
       if (isTextAsset(server.type)) {
         const serverText = server.text ?? "";
-        const localText = readFileSync8(local.absPath, "utf8");
+        const localText = readFileSync10(local.absPath, "utf8");
         if (serverText !== localText)
           entries.push({ path, status: "modified", binary: false, serverText, localText });
       } else {
         const serverSize = server.file?.size;
-        const localSize = Buffer.byteLength(readFileSync8(local.absPath));
+        const localSize = Buffer.byteLength(readFileSync10(local.absPath));
         if (serverSize !== undefined && serverSize !== localSize) {
           entries.push({ path, status: "modified", binary: true });
         }
@@ -1569,11 +2297,11 @@ var login = async (args) => {
 };
 
 // src/commands/preview.ts
-import { writeFileSync as writeFileSync8 } from "node:fs";
+import { writeFileSync as writeFileSync9 } from "node:fs";
 import { resolve as resolve3 } from "node:path";
 
 // src/compile/collect.ts
-import { readFileSync as readFileSync9 } from "node:fs";
+import { readFileSync as readFileSync11 } from "node:fs";
 import { basename as basename4 } from "node:path";
 var collectEntries = (root, manifest, project) => {
   const pathById = buildPaths(project.assets);
@@ -1598,7 +2326,7 @@ var collectEntries = (root, manifest, project) => {
         warnings.push(`No compiled shader for ${file.path} — push it to compile the shader.`);
       entries.push({ path: file.path, type, shaders });
     } else {
-      entries.push({ path: file.path, type, text: readFileSync9(file.absPath, "utf8") });
+      entries.push({ path: file.path, type, text: readFileSync11(file.absPath, "utf8") });
     }
   }
   return { entries, warnings };
@@ -1628,7 +2356,7 @@ var preview = async (args) => {
   if (out && isNullSink(out)) {
     note(`Discarded output (${out})`);
   } else if (out) {
-    writeFileSync8(resolve3(out), js);
+    writeFileSync9(resolve3(out), js);
     note(`Wrote ${out} (${js.length} bytes)`);
   } else {
     process.stdout.write(js);
@@ -1640,7 +2368,7 @@ var preview = async (args) => {
 };
 
 // src/commands/render.ts
-import { writeFileSync as writeFileSync9 } from "node:fs";
+import { writeFileSync as writeFileSync10 } from "node:fs";
 import { resolve as resolve4 } from "node:path";
 var LOCAL_ASSET_SCHEME2 = "lecodesfile://";
 var DEVICE_SAFE_AREA = {
@@ -1737,7 +2465,7 @@ var render = async (args) => {
     if (isNullSink(pngFlag)) {
       note(`Discarded PNG (${pngFlag})`);
     } else {
-      writeFileSync9(resolve4(pngFlag), png);
+      writeFileSync10(resolve4(pngFlag), png);
       note(`Wrote ${pngFlag} (${png.length} bytes, ${width}x${height})`);
     }
     return done((cb) => cb());
@@ -1752,7 +2480,7 @@ var render = async (args) => {
     return done((cb) => cb());
   }
   if (out) {
-    writeFileSync9(resolve4(out), result.text);
+    writeFileSync10(resolve4(out), result.text);
     note(`Wrote ${out} (${result.text.length} bytes)`);
     return done((cb) => cb());
   }
@@ -1763,8 +2491,8 @@ var render = async (args) => {
 };
 
 // src/commands/pull.ts
-import { existsSync as existsSync8, mkdirSync as mkdirSync8, rmSync, writeFileSync as writeFileSync10 } from "node:fs";
-import { dirname as dirname6, join as join11 } from "node:path";
+import { existsSync as existsSync10, mkdirSync as mkdirSync9, rmSync, writeFileSync as writeFileSync11 } from "node:fs";
+import { dirname as dirname7, join as join12 } from "node:path";
 var pull = async (args) => {
   const root = findProjectRoot(process.cwd());
   const manifest = readManifest(root);
@@ -1784,8 +2512,8 @@ var pull = async (args) => {
   const remotePaths = new Set([...buildPaths(project.assets).entries()].filter(([id]) => project.assets.find((a) => a.id === id)?.type !== "folder").map(([, path]) => path));
   for (const path of Object.keys(manifest.files)) {
     if (!remotePaths.has(path)) {
-      const abs = join11(root, ...path.replace(/^\//, "").split("/"));
-      if (existsSync8(abs))
+      const abs = join12(root, ...path.replace(/^\//, "").split("/"));
+      if (existsSync10(abs))
         rmSync(abs);
     }
   }
@@ -1823,18 +2551,18 @@ var pullPaths = async (root, manifest, project, paths, apiUrl, token) => {
   const files = { ...manifest.files };
   for (const asset of targets) {
     const key = pathById.get(asset.id);
-    const abs = join11(root, ...key.replace(/^\//, "").split("/"));
-    mkdirSync8(dirname6(abs), { recursive: true });
+    const abs = join12(root, ...key.replace(/^\//, "").split("/"));
+    mkdirSync9(dirname7(abs), { recursive: true });
     let sha;
     if (asset.type === "file") {
       if (!asset.file?.src)
         continue;
       const bytes = await downloadBlob(apiUrl, asset.file.src);
-      writeFileSync10(abs, bytes);
+      writeFileSync11(abs, bytes);
       sha = sha256(bytes);
     } else {
       const text = asset.text ?? "";
-      writeFileSync10(abs, text);
+      writeFileSync11(abs, text);
       sha = sha256(text);
     }
     files[key] = { id: asset.id, type: kindOf2(asset.type), sha };
@@ -1847,7 +2575,7 @@ var pullPaths = async (root, manifest, project, paths, apiUrl, token) => {
 
 // src/commands/push.ts
 import { basename as basename5 } from "node:path";
-import { readFileSync as readFileSync10 } from "node:fs";
+import { readFileSync as readFileSync12 } from "node:fs";
 var push = async (args) => {
   const root = findProjectRoot(process.cwd());
   const manifest = readManifest(root);
@@ -1906,9 +2634,9 @@ var push = async (args) => {
     if (source)
       entry.assetId = source.id;
     if (isTextKind(kind)) {
-      entry.text = readFileSync10(file.absPath, "utf8");
+      entry.text = readFileSync12(file.absPath, "utf8");
     } else if (!source || source.sha !== file.sha) {
-      const blob = await uploadBlob(apiUrl, token, manifest.uuid, basename5(file.path), readFileSync10(file.absPath));
+      const blob = await uploadBlob(apiUrl, token, manifest.uuid, basename5(file.path), readFileSync12(file.absPath));
       entry.blobFileId = blob.id;
       uploaded++;
     }
@@ -2049,8 +2777,8 @@ Config lives in ~/.lecodes/config.json (override with LECODES_API / LECODES_TOKE
 var commands = { login, create, clone, status, diff, pull, push, preview, render, design };
 var readVersion = () => {
   try {
-    const here2 = dirname7(fileURLToPath3(import.meta.url));
-    return JSON.parse(readFileSync11(join12(here2, "..", "package.json"), "utf8")).version ?? "unknown";
+    const here2 = dirname8(fileURLToPath4(import.meta.url));
+    return JSON.parse(readFileSync13(join13(here2, "..", "package.json"), "utf8")).version ?? "unknown";
   } catch {
     return "unknown";
   }