lecodes-cli 0.13.1 → 0.14.0

package/dist/index.js

@@ -1826,7 +1826,7 @@ var ICON_ID, isIdentStart2 = (c2) => c2 >= "A" && c2 <= "Z" || c2 >= "a" && c2 <
       return new Error(`assetIcon: unknown icon pack "${pack}" (in "${pack}:${name}"). Available packs: ${packs.join(", ")}.`);
     } catch {}
   }
-  return new Error(`assetIcon: can't reach the icon registry${registry ? ` (${registry})` : ""} to resolve "${pack}:${name}". ` + `Check your connection, or set LECODES_ICON_REGISTRY.`);
+  return Object.assign(new Error(`assetIcon: can't reach the icon registry${registry ? ` (${registry})` : ""} to resolve "${pack}:${name}". ` + `Check your connection, or set LECODES_ICON_REGISTRY.`), { transient: true });
 }, VENDORED_ICON_PATH, collectVendoredIcons = (entries) => {
   const map = new Map;
   for (const e of entries) {
@@ -43098,6 +43098,13 @@ var SPEC_MD, META_JSON = `{
   },
   "edges": []
 }
+`, META_JSON_DESKTOP = `{
+  "defaultSize": [1280, 800],
+  "screens": {
+    "home": { "pos": [0, 0], "desc": "Example screen — replace me", "role": "list" }
+  },
+  "edges": []
+}
 `, TOKENS_TS = `// Design tokens shared by every screen. Colors are hex strings (the engine parses hex only).
 // App font: one theme() call here sets the default text font everywhere. font("id") installs a
 // registry family (vendored at compile time) and returns its name — no loading code needed.
@@ -43114,56 +43121,30 @@ export const colors = {
 export const spacing = { xs: 4, sm: 8, md: 16, lg: 24 }
 
 export const radius = { sm: 8, md: 12, lg: 20 }
-`, TABS_TS = `// The app's tab bar, declared ONCE — the design canvas discovers it from this file.
+`, TABS_TS = `// The app's tab bar — declare it here ONCE; the design canvas discovers it from this file:
 //
 //   export const mainTabs = defineTabs({
 //     home: { label: "Home", icon: assetIcon("lucide:house") },
 //     news: { label: "News", icon: assetIcon("lucide:newspaper") },
 //   })
 //
-// The KEYS are screen ids — each tab's root screen (screens/<key>.ts), in tab order, literals only.
+// \`defineTabs\` is an SDK global — the standard themed bar, the same look the built app's UITabs
+// renders. The KEYS are screen ids — each tab's root screen (screens/<key>.ts), in tab order,
+// literals only. Icons are always \`assetIcon("pack:name")\` calls — never hand-written
+// \`{ svg }\` objects (those silently render blank).
+//
 // Every screen that shows the bar mounts it with a literal tab id — tab roots AND pushed details
 // that keep the bar:
 //
 //   export default () => mainTabs.screen("news", [ ...content ])
 //
-// A screen that doesn't mount it is a full-screen push (bar hidden). Never draw meta.json edges
-// between tab screens — the bar already navigates; the board renders it as a rail + lanes.
-// Restyle the bar below freely: only the defineTabs({ keys }) declaration and the
-// .screen("<tab>", …) / .bar("<tab>") call shapes are parsed.
-
-type TabDef = { label: string, icon?: { svg: string, tintColor: string | null } }
-
-// Theme-variable driven — theme({ primaryColor, mutedColor, tabbarBg, screenBg }) anywhere
-// restyles every screen's bar at once; the fallbacks keep an untouched scaffold looking right.
-const ACTIVE = "var(--primaryColor, #5b8cff)"
-const INACTIVE = "var(--mutedColor, #8a919e)"
-const BAR_BG = "var(--tabbarBg, #15171c)"
-const SCREEN_BG = "var(--screenBg, #101114)"
-
-export const defineTabs = <T extends Record<string, TabDef>>(tabs: T) => {
-  const ids = Object.keys(tabs) as (keyof T & string)[]
-
-  /** The bar alone — mount it yourself when the screen owns its whole layout. */
-  const bar = (active: keyof T & string) =>
-    UIRow(ids.map((id) => {
-      const color = id === active ? ACTIVE : INACTIVE
-      return UIButton([
-        ...(tabs[id].icon ? [UIImage(tabs[id].icon!).style({ width: 22, height: 22, tintColor: color })] : []),
-        UIText(tabs[id].label).style({ fontSize: 10, color }),
-      ]).style({ name: \`tab-\${id}\`, flexDirection: "column", gap: 3, flexGrow: 1, flexBasis: 0, pt: 8, pb: 6 })
-    })).style({ bgColor: BAR_BG, pb: "safe-bottom" })
-
-  /** A screen that sits ON the bar (the common case): [ content, bar ] — the same column the real
-   *  app composes as [ UIPager, bar ]. */
-  const screen = (active: keyof T & string, children: UINodeChild[]) =>
-    UIScreen([
-      UIColumn(children).style({ flexGrow: 1, p: 16, pt: "safe-top" }),
-      bar(active),
-    ]).style({ bgColor: SCREEN_BG })
-
-  return { ids, bar, screen }
-}
+// …or \`mainTabs.bar("news")\` when the screen owns its whole layout. A screen that doesn't mount
+// it is a full-screen push (bar hidden). Never draw meta.json edges between tab screens — the bar
+// already navigates; the board renders it as a rail + lanes.
+//
+// Restyle via the theme: theme({ primaryColor, mutedColor, tabbarBg, screenBg }) in shared/tokens.ts
+// recolors every screen's bar (and the built app's UITabs) at once. Keep the defineTabs({...})
+// declaration and the .screen("<tab>", …) / .bar("<tab>") call shapes intact — the canvas parses them.
 `, HOME_SCREEN_TS = `import { colors, spacing, radius } from "../shared/tokens"
 
 // Mock data: the domain shown on realistic values. Inline, per screen.
@@ -43217,13 +43198,13 @@ This is an intent-capture stage — screens run on inline mock data, before any
 ## Read this first, then meta.json
 
 \`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. 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.
+(navigation intent). **Read it before opening any screen file.** When you create a screen, add its
+meta entry **without a \`pos\`** and add edges — the board places it from its structure (its tab
+lane, its group region, its flow neighbours) and **persists that position itself**; you never
+hand-pick coordinates (you can't see the board). To tidy after a batch of changes, call the
+\`arrange_screens\` MCP tool (or \`lecodes design arrange\`) — the layout engine knows tab rails,
+group regions and flow direction. Never reposition or rewrite existing \`pos\` values or
+human-authored descriptions — positions the developer dragged are theirs.
 
 \`\`\`json
 {
@@ -43247,11 +43228,15 @@ positions or descriptions.
 - **An edge from a screen to itself** (\`"from": "home", "to": "home@empty"\`) is a *state link*: the
   board draws it as a chip on the activator element (clicking it switches the tile's state), never
   as an arrow. Use it to record "tapping X puts this screen into state Y".
-- **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.
+- **Group only what the tab bar doesn't already section.** Screens on a tab bar are sectioned by
+  their lanes — never set a \`group\` on a tab root or any screen that mounts the bar (a group that
+  duplicates a lane draws nothing and gets flagged for deletion). Group the screens *outside* the
+  bar by user-facing area — \`"group": "Onboarding"\` — 2–6 screens per group (Onboarding,
+  Recovery, Pickers…; on an app with no tab bar that means every screen). 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
@@ -43322,9 +43307,11 @@ keep in the chat.
 
 Most apps have one — declare it ONCE, in source, and never draw edges for it:
 
-- \`shared/tabs.ts\` ships a \`defineTabs\` helper. Declare the bar there:
+- \`defineTabs\` is an SDK global (the standard themed bar — the same look the built app's
+  \`UITabs\` renders). Declare the bar in \`shared/tabs.ts\`:
   \`export const mainTabs = defineTabs({ home: { label: "Home", icon: assetIcon("lucide:house") }, … })\`
-  — the **keys are screen ids** (each tab's root screen, in tab order), literals only.
+  — the **keys are screen ids** (each tab's root screen, in tab order), literals only, and icons
+  are always \`assetIcon(…)\` calls.
 - Every screen that shows the bar mounts it with a **literal** tab id:
   \`export default () => mainTabs.screen("news", [ …content ])\` — tab roots AND pushed detail
   screens that keep the bar (the news lane's article screen mounts \`"news"\` too). A screen that
@@ -43332,10 +43319,13 @@ Most apps have one — declare it ONCE, in source, and never draw edges for it:
 - The canvas discovers all of this from the source (like screen states) and draws the bar as a
   **rail + lane bands** — tab switching needs NO edges, and \`design_state\` serves the discovered
   \`hubs\`. In the live prototype, tapping a tab button jumps the board to that tab's root screen.
+- The lane bands replace groups for bar screens: don't \`group\` anything that mounts the bar
+  (see the meta.json section) — groups are for the flows *outside* the bar.
 - Style through theme variables: the bar reads \`var(--primaryColor)\`, \`var(--mutedColor)\`,
   \`var(--tabbarBg)\`, \`var(--screenBg)\` (with fallbacks) — one \`theme({ primaryColor: … })\` call
-  restyles it app-wide. You may restyle \`shared/tabs.ts\` itself; keep the \`defineTabs({ … })\`
-  declaration and \`.screen("<tab>", …)\` call shapes intact (the canvas parses them).
+  in \`shared/tokens.ts\` restyles it app-wide (and the built app's bar with it). Keep the
+  \`defineTabs({ … })\` declaration and \`.screen("<tab>", …)\` call shapes intact (the canvas
+  parses them).
 
 ## Screen states (variants)
 
@@ -43497,8 +43487,8 @@ JSON by hand (a message missing its \`pending\` flag is never delivered, and not
 1. \`board_activity\` (if the server is up), then \`design_comments\` for anything open, 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.)
+   the board places them from their lane/group/flow structure and persists the result. After a
+   larger batch, \`arrange_screens\` (MCP) or \`lecodes design arrange\` re-tidies the whole board.
 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.
@@ -43600,12 +43590,17 @@ var DEFAULT_DIR = "design", DEFAULT_PORT = 4477, getContext = (args) => {
   if (!existsSync19(dir))
     return [];
   return readdirSync10(dir).filter((f3) => f3.endsWith(".ts") && !f3.startsWith(".")).map((f3) => f3.slice(0, -3)).sort();
-}, readMetaSizes = (designDir) => {
+}, PHONE_SIZE, readMetaFrames = (designDir) => {
   try {
     const meta = JSON.parse(readFileSync18(join19(designDir, "meta.json"), "utf8"));
-    return meta?.screens ?? {};
+    const d = meta?.defaultSize;
+    const valid = Array.isArray(d) && d.length === 2 && d.every((n2) => typeof n2 === "number" && Number.isFinite(n2) && n2 >= 64 && n2 <= 8192);
+    return {
+      screens: meta?.screens ?? {},
+      defaultSize: valid ? [Math.round(d[0]), Math.round(d[1])] : PHONE_SIZE
+    };
   } catch {
-    return {};
+    return { screens: {}, defaultSize: PHONE_SIZE };
   }
 }, writeMcpConfig = (ctx, port) => {
   const path2 = join19(ctx.root, ".mcp.json");
@@ -43631,7 +43626,7 @@ var DEFAULT_DIR = "design", DEFAULT_PORT = 4477, getContext = (args) => {
   log(`${c.green(existing ? "updated" : "created")}   .mcp.json (lecodes-design MCP → ${entry.url})`);
 }, init = async (ctx, args) => {
   const files = [
-    ["meta.json", META_JSON],
+    ["meta.json", flagBool(args, "desktop") ? META_JSON_DESKTOP : META_JSON],
     ["spec.md", SPEC_MD],
     ["README.md", README_HINT],
     ["CLAUDE.md", CLAUDE_MD],
@@ -43717,14 +43712,14 @@ var DEFAULT_DIR = "design", DEFAULT_PORT = 4477, getContext = (args) => {
   }, 120000);
   killer.unref?.();
   const png2 = flagBool(args, "png") || flagStr(args, "png") !== undefined;
-  const sizes = readMetaSizes(ctx.designDir);
+  const frames = readMetaFrames(ctx.designDir);
   const outDir = flagStr(args, "out-dir") ?? join19(ctx.designDir, ".snapshots");
   const single = targets.length === 1 && requested.length === 1 && !png2 && !allStates && !flagStr(args, "out-dir");
   const onConsole = flagBool(args, "logs") ? (level, text) => logErr(`${c.dim(`[${level}]`)} ${text}`) : undefined;
   if (!single)
     mkdirSync14(outDir, { recursive: true });
   for (const id of targets) {
-    const [width, height] = sizes[id]?.size ?? [390, 844];
+    const [width, height] = frames.screens[id]?.size ?? frames.defaultSize;
     let plan = [{ state: undefined, bases: [id] }];
     if (discover) {
       const { states, canonical } = discover(readFileSync18(join19(ctx.designDir, "screens", `${id}.ts`), "utf8"));
@@ -43798,7 +43793,8 @@ var DEFAULT_DIR = "design", DEFAULT_PORT = 4477, getContext = (args) => {
       state,
       assets: "disk"
     });
-    const [width, height] = readMetaSizes(ctx.designDir)[id]?.size ?? [390, 844];
+    const frames = readMetaFrames(ctx.designDir);
+    const [width, height] = frames.screens[id]?.size ?? frames.defaultSize;
     const warnings = [];
     let json;
     let png2;
@@ -43849,11 +43845,12 @@ var DEFAULT_DIR = "design", DEFAULT_PORT = 4477, getContext = (args) => {
   const designServer = await loadDesignServer(ctx);
   const onlyNew = flagBool(args, "new");
   const summary = designServer.arrangeDesign(ctx.designDir, { onlyNew });
+  const score = summary.score ? ` (score ${summary.score.before.toFixed(0)} → ${summary.score.after.toFixed(0)}, lower is better)` : "";
   if (!summary.changed) {
-    log(onlyNew ? "No unplaced screens — nothing to arrange." : "Already tidy — the current layout wins, nothing moved.");
+    log(onlyNew ? "No unplaced screens — nothing to arrange." : `Already in its arranged shape — nothing moved${score}.`);
     return;
   }
-  log(`${c.green("✓")} ${onlyNew ? "Placed" : "Arranged"} ${summary.moved} screen${summary.moved === 1 ? "" : "s"} in ${ctx.dirName}/meta.json.`);
+  log(`${c.green("✓")} ${onlyNew ? "Placed" : "Arranged"} ${summary.moved} screen${summary.moved === 1 ? "" : "s"} in ${ctx.dirName}/meta.json${score}.`);
 }, 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).");
@@ -44192,6 +44189,7 @@ var init_design = __esm(() => {
   init_config();
   init_api();
   init_types4();
+  PHONE_SIZE = [390, 844];
 });
 
 // ../../node_modules/.bun/qrcode-terminal@0.12.0/node_modules/qrcode-terminal/vendor/QRCode/QRMode.js
@@ -45213,7 +45211,7 @@ var require_main = __commonJS((exports, module) => {
 // package.json
 var package_default = {
   name: "lecodes-cli",
-  version: "0.13.1",
+  version: "0.14.0",
   dependencies: {
     "@letary/chisel": "^0.6.0",
     jimp: "^1.6.1"
@@ -45226,8 +45224,8 @@ var package_default = {
     sdk: "workspace:*"
   },
   peerDependencies: {
-    "lecodes-design": "^0.5.0",
-    "lecodes-renderer": "^0.8.0",
+    "lecodes-design": "^0.6.1",
+    "lecodes-renderer": "^0.8.2",
     "lecodes-3d-editor": "^0.2.0"
   },
   bin: {
@@ -46346,6 +46344,17 @@ var FIRST_PARTY_PLUGINS = {
   geolocation: "letary/lecodes-plugins",
   push: "letary/lecodes-plugins"
 };
+var readAppConfigAt = (root) => readJson(join12(root, "app.json"));
+var DESKTOP_DEFAULT_WINDOW = { width: 1280, height: 720 };
+var desktopDefaultViewport = (root) => {
+  const cfg = readAppConfigAt(root);
+  if (!cfg?.desktop || cfg.ios || cfg.android)
+    return null;
+  return {
+    width: cfg.desktop.window?.width ?? DESKTOP_DEFAULT_WINDOW.width,
+    height: cfg.desktop.window?.height ?? DESKTOP_DEFAULT_WINDOW.height
+  };
+};
 var readJson = (path) => {
   if (!existsSync10(path))
     return null;
@@ -48907,6 +48916,7 @@ var create = async (args) => {
 
 // src/commands/desktop.ts
 init_util();
+init_manifest();
 
 // src/desktopRenderer.ts
 init_util();
@@ -49057,6 +49067,20 @@ var updateDesktop = async () => {
   else
     note(`Desktop renderer set to ${latest} (was ${before}).`);
 };
+var windowEnv = (opts) => {
+  const env = {};
+  const width = opts.width ?? (opts.height !== undefined ? 1280 : undefined);
+  const height = opts.height ?? (opts.width !== undefined ? 720 : undefined);
+  if (width && height)
+    env.CREATOR_WINDOW_SIZE = `${width}x${height}`;
+  if (opts.minWidth && opts.minHeight)
+    env.CREATOR_MIN_WINDOW_SIZE = `${opts.minWidth}x${opts.minHeight}`;
+  if (opts.title)
+    env.CREATOR_WINDOW_TITLE = opts.title;
+  if (opts.resizable === false)
+    env.CREATOR_WINDOW_FIXED = "1";
+  return env;
+};
 var stageBundle = (js, resources) => {
   const runDir = mkdtempSync(join18(tmpdir(), "lecodes-render-"));
   writeFileSync14(join18(runDir, "app.js"), js);
@@ -49071,9 +49095,7 @@ var runDesktopApp = async (js, resources, opts = {}) => {
   const exe = await resolveDesktopExe();
   const runDir = stageBundle(js, resources);
   try {
-    const env = { ...process.env };
-    if (opts.width && opts.height)
-      env.CREATOR_WINDOW_SIZE = `${opts.width}x${opts.height}`;
+    const env = { ...process.env, ...windowEnv(opts) };
     await new Promise((done, fail) => {
       const child = spawn2(exe, [join18(runDir, "app.js")], { cwd: runDir, env, stdio: ["ignore", "inherit", "inherit"] });
       child.on("error", (e2) => fail(new CliError(`Can't run the desktop host: ${e2.message}`)));
@@ -49088,6 +49110,15 @@ var runDesktopApp = async (js, resources, opts = {}) => {
     rmSync4(runDir, { recursive: true, force: true });
   }
 };
+var runDesktopDev = async (url, opts = {}) => {
+  const exe = await resolveDesktopExe();
+  const env = { ...process.env, ...windowEnv(opts) };
+  await new Promise((done, fail) => {
+    const child = spawn2(exe, [url], { env, stdio: ["ignore", "ignore", "inherit"] });
+    child.on("error", (e2) => fail(new CliError(`Can't run the desktop host: ${e2.message}`)));
+    child.on("exit", () => done());
+  });
+};
 var runDesktopRender = async (js, resources, opts) => {
   const exe = await resolveDesktopExe();
   const runDir = stageBundle(js, resources);
@@ -49141,11 +49172,24 @@ ${tail.join("").trimEnd()}` : "";
 
 // src/commands/desktop.ts
 var run = async (args) => {
+  let root;
+  try {
+    root = findProjectRoot(process.cwd());
+  } catch {
+    root = process.cwd();
+  }
+  const appCfg = readAppConfigAt(root);
+  const win = appCfg?.desktop?.window;
   const { js, resources } = await buildBundle(args);
-  const width = Number(flagStr(args, "width")) || undefined;
-  const height = Number(flagStr(args, "height")) || undefined;
   note("Launching LeCodes Desktop… (close the window to return)");
-  await runDesktopApp(js, resources, { width, height });
+  await runDesktopApp(js, resources, {
+    width: Number(flagStr(args, "width")) || win?.width,
+    height: Number(flagStr(args, "height")) || win?.height,
+    minWidth: win?.minWidth,
+    minHeight: win?.minHeight,
+    resizable: win?.resizable,
+    title: flagStr(args, "title") ?? win?.title ?? appCfg?.name
+  });
 };
 var status = async () => {
   const selected = selectedDesktopVersion();
@@ -49787,6 +49831,19 @@ ${result.error}`);
     note(`Token stored in ${LECODES_DIR}/dev.json (delete it to rotate the URL).`);
   log("");
   log(`Watching ${root} — save a file to hot-reload. Ctrl+C to stop.`);
+  if (flagBool(args, "desktop")) {
+    const appCfg = readAppConfigAt(root);
+    const win = appCfg?.desktop?.window;
+    note("Opening LeCodes Desktop against the dev server…");
+    runDesktopDev(server.url, {
+      width: win?.width,
+      height: win?.height,
+      minWidth: win?.minWidth,
+      minHeight: win?.minHeight,
+      resizable: win?.resizable,
+      title: win?.title ?? appCfg?.name ?? name
+    }).then(() => note("Desktop window closed — the dev server keeps running (Ctrl+C to stop)."), (e2) => warnErr(`Desktop host: ${e2 instanceof Error ? e2.message : String(e2)}`));
+  }
 };
 
 // src/commands/diff.ts
@@ -50030,6 +50087,13 @@ const screen = UIScreen(
 
 screen.open()
 `;
+var appJsonDesktop = (name) => JSON.stringify({
+  name,
+  desktop: {
+    window: { width: 1280, height: 800, minWidth: 640, minHeight: 480 }
+  }
+}, null, 2) + `
+`;
 var readmeTemplate = (name) => `# ${name}
 
 A LeCodes app. The whole SDK is available as globals (\`UIScreen\`, \`UIText\`, \`Scene2D\`, …) —
@@ -50104,8 +50168,11 @@ var init2 = async (args) => {
     log(`${c.green("created")}   ${rel}`);
     created++;
   };
+  const forDesktop = flagBool(args, "desktop");
   write("main.ts", STARTER2);
   write("README.md", readmeTemplate(name));
+  if (forDesktop)
+    write("app.json", appJsonDesktop(name));
   write("CLAUDE.md", appClaudeMd(name));
   write("tests/counter.flow.json", STARTER_FLOW);
   write(".lecodesignore", DEFAULT_IGNORE_FILE);
@@ -50118,9 +50185,15 @@ var init2 = async (args) => {
   log("");
   success(created ? `Local project ${c.bold(name)} ready${dirArg === "." ? "" : ` in ${c.bold(dirArg)}/`}.` : `Project ${c.bold(name)} already initialized.`);
   const cd = dirArg === "." ? "" : `cd ${dirArg} && `;
-  log(`  ${c.bold(cd + "lecodes dev")}                run it on a device with hot reload`);
-  log(`  ${c.bold(cd + "lecodes test")}               run the flow tests headless (no device)`);
-  log(`  ${c.bold(cd + "lecodes compile -o app.js")}  bundle it for LeCodes Desktop`);
+  if (forDesktop) {
+    log(`  ${c.bold(cd + "lecodes dev --desktop")}      run it in a desktop window with hot reload`);
+    log(`  ${c.bold(cd + "lecodes test")}               run the flow tests headless (desktop-sized)`);
+    log(`  ${c.bold(cd + "lecodes desktop run")}        open the compiled app in the desktop host`);
+  } else {
+    log(`  ${c.bold(cd + "lecodes dev")}                run it on a device with hot reload`);
+    log(`  ${c.bold(cd + "lecodes test")}               run the flow tests headless (no device)`);
+    log(`  ${c.bold(cd + "lecodes compile -o app.js")}  bundle it for LeCodes Desktop`);
+  }
 };
 
 // src/commands/link.ts
@@ -50470,6 +50543,7 @@ var compileHeadlessBundle = async (args) => {
 };
 
 // src/commands/render.ts
+init_manifest();
 init_util();
 var DEVICE_SAFE_AREA = {
   none: { insets: [0, 0, 0, 0], bars: [] },
@@ -50539,8 +50613,15 @@ var readScenarioFile = (path2) => {
   return file;
 };
 var renderDesktop = async (args) => {
-  const width = Number(flagStr(args, "width")) || 390;
-  const height = Number(flagStr(args, "height")) || 844;
+  let root;
+  try {
+    root = findProjectRoot(process.cwd());
+  } catch {
+    root = process.cwd();
+  }
+  const win = readAppConfigAt(root)?.desktop?.window;
+  const width = Number(flagStr(args, "width")) || win?.width || 390;
+  const height = Number(flagStr(args, "height")) || win?.height || 844;
   const frames = Number(flagStr(args, "frames")) || 60;
   const timeoutMs = Number(flagStr(args, "timeout")) || 60000;
   const pngFlag = flagStr(args, "png") ?? "screenshot.png";
@@ -50568,10 +50649,11 @@ var render = async (args) => {
     process.exit(1);
   }, timeoutMs);
   killer.unref?.();
-  const { js, warnings, useLocalAssets } = await compileHeadlessBundle(args);
+  const { js, warnings, useLocalAssets, root } = await compileHeadlessBundle(args);
   const renderer = await requireRenderer();
-  const width = Number(flagStr(args, "width")) || scenario?.width || 390;
-  const height = Number(flagStr(args, "height")) || scenario?.height || 844;
+  const projectViewport = desktopDefaultViewport(root);
+  const width = Number(flagStr(args, "width")) || scenario?.width || projectViewport?.width || 390;
+  const height = Number(flagStr(args, "height")) || scenario?.height || projectViewport?.height || 844;
   const settleStr = flagStr(args, "settle") ?? (scenario?.settle !== undefined ? String(scenario.settle) : undefined);
   const timeStr = flagStr(args, "time");
   const onConsole = flagBool(args, "logs") ? (level, text2) => logErr(`${c.dim(`[${level}]`)} ${text2}`) : undefined;
@@ -51286,6 +51368,7 @@ var readFlowFile = (abs, displayName) => {
 var test = async (args) => {
   const { js, warnings, useLocalAssets, root } = await compileHeadlessBundle(args);
   const renderer = await requireRenderer();
+  const projectViewport = desktopDefaultViewport(root);
   const testsDir = resolve12(root, flagStr(args, "dir") ?? "tests");
   const designMetaPath = resolve12(root, flagStr(args, "design-dir") ?? "design", "meta.json");
   const asJson = flagBool(args, "json");
@@ -51356,8 +51439,8 @@ var test = async (args) => {
     try {
       const steps = renderer.parseScenarioSteps(kase.steps);
       const session = await renderer.createSession(js, {
-        width: Number(flagStr(args, "width")) || kase.width || 390,
-        height: Number(flagStr(args, "height")) || kase.height || 844,
+        width: Number(flagStr(args, "width")) || kase.width || projectViewport?.width || 390,
+        height: Number(flagStr(args, "height")) || kase.height || projectViewport?.height || 844,
         settleMs: flagSettle !== undefined ? Number(flagSettle) : kase.settle,
         waitNetwork: flagBool(args, "wait-network"),
         localAssets: useLocalAssets,
@@ -51709,7 +51792,11 @@ ${c.bold("Commands:")}
   init [dir]                    Scaffold a new LOCAL project (no login/server): a starter
                                   main.ts, a CLAUDE.md + passing flow test (the headless
                                   render/test loop), IDE types + tsconfig, a .lecodesignore.
-                                  Run it with 'lecodes dev' or 'lecodes compile'.${INSTALL_HELP}
+                                  Run it with 'lecodes dev' or 'lecodes compile'.
+                                  --desktop       also write an app.json declaring the desktop
+                                                    target (window size; 'dev --desktop',
+                                                    'desktop run' and headless render/test
+                                                    pick it up)${INSTALL_HELP}
   login                         Authorize in the browser and store an access token
                                   --token <pat>   store a token from the web UI instead
                                   --api <url>     API origin (default https://le.codes)
@@ -51752,6 +51839,9 @@ ${c.bold("Commands:")}
                                   --host <ip>     LAN address to advertise (default: auto-detect)
                                   --entry <path>  override the entrypoint
                                   --no-qr         don't render the QR code
+                                  --desktop       also open the app in the native desktop host
+                                                    (same hot reload; window from app.json's
+                                                    desktop block; closing it keeps the server)
   compile                       Compile the local project to JS (prints to stdout)
                                   (was 'lecodes preview' — the old name still works)
                                   -o, --out <file>   write to a file instead of stdout
@@ -51817,6 +51907,8 @@ ${c.bold("Commands:")}
                                   --dir <folder>     design folder (default design/)
                                   --no-open          don't open the browser
   design init                   Scaffold the design folder (screens/, shared/, meta.json, CLAUDE.md)
+                                  --desktop          desktop-frame board (meta.json defaultSize
+                                                       [1280, 800] instead of the phone frame)
   design snapshot [screen…]     Render design screens headless (needs 'lecodes-renderer')
                                   one screen → JSON to stdout; else files in design/.snapshots/
                                   --png              also rasterize PNGs (needs @napi-rs/canvas)
@@ -51831,8 +51923,9 @@ ${c.bold("Commands:")}
                                   no args shows the version status (selected / downloaded /
                                   newest published)
                                   run     compile the current project and open it in a real
-                                          desktop window (--width/--height set the window size;
-                                          --entry overrides the entrypoint)
+                                          desktop window (size/min-size/title default from
+                                          app.json's desktop block; --width/--height/--title
+                                          override; --entry overrides the entrypoint)
                                   update  move to the newest published release
                                           (cached in ~/.lecodes/renderer)
   scene [path]                  LeCodes Scene Editor — visually edit a .scene.ts (tree, inspector,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lecodes-cli",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "dependencies": {
     "@letary/chisel": "^0.6.0",
     "jimp": "^1.6.1"
@@ -13,8 +13,8 @@
     "sdk": "workspace:*"
   },
   "peerDependencies": {
-    "lecodes-design": "^0.5.0",
-    "lecodes-renderer": "^0.8.0",
+    "lecodes-design": "^0.6.1",
+    "lecodes-renderer": "^0.8.2",
     "lecodes-3d-editor": "^0.2.0"
   },
   "bin": {

package/runtime/sdk/compile/assetIconMacro.ts

@@ -16,9 +16,9 @@
  *
  * WHERE the SVG bodies come from is the caller's business, passed in as a resolver:
  *   - CLI design compile: vendored into the design folder from the icon registry (lock + notices);
- *   - backend design board: the already-pushed `design/assets/icons/**` text assets, no registry;
  *   - CLI app compiles: the user-level cache (~/.lecodes/cache/icons) + registry on miss;
- *   - backend app compile: a server-side cache + registry on miss.
+ *   - backend app compile + design board: vendored `assets/icons/**` text assets first, then a
+ *     server-side cache + registry on miss.
  * App compiles never write icons into the project — attribution for platform-deployed apps rides
  * the `// icons:` bundle header (buildIconsHeaderValue) and the platform, not an in-repo notice.
  */
@@ -358,10 +358,12 @@ export const iconNotFoundError = async (
       return new Error(`assetIcon: unknown icon pack "${pack}" (in "${pack}:${name}"). Available packs: ${packs.join(", ")}.`)
     } catch { /* corrupt licenses → fall through to the connectivity error */ }
   }
-  return new Error(
+  // `transient` lets callers that cache compile results skip caching this one: unlike a missing
+  // icon, an unreachable registry is not a property of the source being compiled.
+  return Object.assign(new Error(
     `assetIcon: can't reach the icon registry${registry ? ` (${registry})` : ""} to resolve "${pack}:${name}". `
     + `Check your connection, or set LECODES_ICON_REGISTRY.`,
-  )
+  ), { transient: true })
 }
 
 /** `…assets/icons/<pack>/<name>.svg` — an icon the design flow vendored into the project tree. */

package/runtime/sdk/inject.ts

@@ -81,6 +81,7 @@ export {
   UIScrollable, type UIScrollableStyle,
   UIPager, type UIPagerStyle,
   UITabs, type UITabDef,
+  defineTabs, type TabDef, type TabsHandle,
   UIWidget, type UIWidgetStyle,
   UIModal, type UIModalStyle,
   UIBottomSheet, type UIBottomSheetStyle,

package/runtime/sdk/ui/UI.ts

@@ -17,7 +17,7 @@ export { UIPopover, type UIPopoverStyle, type UIPopoverAnchor } from './UIPopove
 export { UIRow, UIColumn, UIBox, type UIContainerStyle } from './UIContainer'
 export { UIScrollable, type UIScrollableStyle } from './UIScrollable'
 export { UIPager, type UIPagerStyle } from './UIPager'
-export { UITabs, type UITabDef } from './UITabs'
+export { UITabs, type UITabDef, defineTabs, type TabDef, type TabsHandle } from './UITabs'
 
 export { UIVirtualizedList } from './UIVirtualizedList'