@typecad/ui 1.0.0-alpha.12 → 1.0.0-alpha.14

package/dist/wizard/integration-wizard.js

@@ -5,8 +5,10 @@
 // into their project's cuttlefish.config.ts: pick a display, answer bus/pin/
 // speed questions with hardware-aware defaults, then splice the resulting
 // `display` section into the config without touching any other section.
-// Offers to create a starter .ui entry file when none exists and prints the
-// next build/flash/library steps at the end.
+// Also adds a `preview` npm script to package.json so the desktop preview
+// renderer starts via `npm run preview`. Offers to create a starter .ui entry
+// file when none exists and prints the next build/flash/library steps at the
+// end.
 // ---------------------------------------------------------------------------
 import fs from "node:fs";
 import path from "node:path";
@@ -14,6 +16,7 @@ import chalk from "chalk";
 import { createPromptInterface, promptConfirm, promptInt, promptSelect, promptText, } from "./prompts.js";
 import { DISPLAY_CATALOG, TOUCH_CATALOG, findPinConflicts, } from "./display-catalog.js";
 import { findCuttlefishConfig, findSyntaxError, readConfigSection, readEntryPath, renderDisplayProperty, upsertDisplaySection, } from "./config-writer.js";
+import { findPackageJson, previewScriptCommand, readPackageScript, upsertPackageScript, } from "./package-writer.js";
 import { renderStarterUi } from "./starter-ui.js";
 /** Keys the wizard manages — anything else found in an existing display
  *  section is carried over untouched instead of being silently dropped. */
@@ -405,7 +408,35 @@ export async function runIntegrationWizard(cwd = process.cwd(), streams = {}) {
                 return { exitCode: 1 };
             }
         }
-        // --- 8. Summary + write -------------------------------------------------------
+        // --- 8. package.json preview script ------------------------------------------
+        // `npm run preview` should start the desktop preview renderer, pointing at
+        // the config the wizard just verified. An existing identical script is
+        // left untouched; a differing one is only replaced with consent.
+        let packageJsonPath;
+        let packageJsonText;
+        let previewCommand;
+        let existingPreview;
+        let replacePreview = false;
+        const foundPackageJson = findPackageJson(path.dirname(configPath));
+        if (foundPackageJson) {
+            try {
+                packageJsonText = fs.readFileSync(foundPackageJson, "utf-8");
+                existingPreview = readPackageScript(packageJsonText, "preview");
+                packageJsonPath = foundPackageJson;
+                previewCommand = previewScriptCommand(foundPackageJson, configPath);
+            }
+            catch (err) {
+                console.log(`  ${chalk.yellow("!")} ${err instanceof Error ? err.message : String(err)} — skipping the npm preview script.`);
+            }
+            if (previewCommand && existingPreview !== undefined && existingPreview !== previewCommand) {
+                console.log(`  ${chalk.yellow("!")} package.json already has a preview script: ${chalk.white(existingPreview)}`);
+                replacePreview = await promptConfirm(rl, "Replace it with the wizard's preview command?", true);
+            }
+        }
+        else {
+            console.log(`${chalk.yellow("!")} No package.json found next to ${path.relative(cwd, configPath)} — skipping the npm preview script.`);
+        }
+        // --- 9. Summary + write -------------------------------------------------------
         console.log();
         console.log(chalk.dim("  The following display section will be written to"));
         console.log(chalk.dim(`  ${path.relative(cwd, configPath)}:`));
@@ -421,6 +452,17 @@ export async function runIntegrationWizard(cwd = process.cwd(), streams = {}) {
         if (carried.length > 0) {
             console.log(`  ${chalk.dim(`Kept existing display settings the wizard does not manage: ${carried.join(", ")}`)}`);
         }
+        if (previewCommand && packageJsonPath) {
+            if (existingPreview === previewCommand) {
+                console.log(`  ${chalk.dim(`npm script already configured: preview — "${previewCommand}"`)}`);
+            }
+            else if (existingPreview === undefined || replacePreview) {
+                console.log(`  ${chalk.dim("Also writes npm script:")} ${chalk.white("preview")}${chalk.dim(` — "${previewCommand}"`)}`);
+            }
+            else {
+                console.log(`  ${chalk.dim(`Kept existing preview script: "${existingPreview}"`)}`);
+            }
+        }
         console.log();
         if (!(await promptConfirm(rl, "Write this configuration?", true))) {
             console.log(chalk.dim("  Aborted — nothing was written."));
@@ -434,7 +476,21 @@ export async function runIntegrationWizard(cwd = process.cwd(), streams = {}) {
         }
         fs.writeFileSync(configPath, updated.text, "utf-8");
         console.log(`${chalk.green("✓")} ${updated.mode === "replaced" ? "Updated" : "Added"} the display section in ${chalk.white(path.relative(cwd, configPath))}`);
-        // --- 9. Starter entry file ------------------------------------------------------
+        // The preview script rides along with the confirmed write: added when
+        // missing, confirmed verbatim when already the wizard's command, and only
+        // replaced when the user consented above.
+        if (packageJsonPath && packageJsonText !== undefined && previewCommand
+            && (existingPreview === undefined || existingPreview === previewCommand || replacePreview)) {
+            const scriptUpsert = upsertPackageScript(packageJsonText, "preview", previewCommand);
+            if (scriptUpsert.changed) {
+                fs.writeFileSync(packageJsonPath, scriptUpsert.text, "utf-8");
+                console.log(`${chalk.green("✓")} ${scriptUpsert.previous !== undefined ? "Updated" : "Added"} npm script ${chalk.white("preview")} in ${chalk.white(path.relative(cwd, packageJsonPath))}`);
+            }
+            else {
+                console.log(`${chalk.green("✓")} npm script ${chalk.white("preview")} already configured in ${chalk.white(path.relative(cwd, packageJsonPath))}`);
+            }
+        }
+        // --- 10. Starter entry file ------------------------------------------------------
         if (entryPath) {
             const entryAbs = path.resolve(path.dirname(configPath), entryPath);
             if (!fs.existsSync(entryAbs) && entryAbs.endsWith(".ui")) {
@@ -445,7 +501,7 @@ export async function runIntegrationWizard(cwd = process.cwd(), streams = {}) {
                 }
             }
         }
-        // --- 10. Next steps ---------------------------------------------------------------
+        // --- 11. Next steps ---------------------------------------------------------------
         console.log();
         console.log(chalk.cyan("Next steps"));
         console.log();
@@ -463,7 +519,7 @@ export async function runIntegrationWizard(cwd = process.cwd(), streams = {}) {
         const firstStep = libraries.length > 0 ? 2 : 1;
         console.log(`  ${firstStep}. Preview your UI on the desktop:`);
         console.log();
-        console.log(`     ${chalk.cyan("npx @typecad/cuttlefish preview")}`);
+        console.log(`     ${chalk.cyan(previewCommand ? "npm run preview" : "npx @typecad/cuttlefish preview")}`);
         console.log();
         console.log(`  ${firstStep + 1}. Compile for your board:`);
         console.log();
@@ -478,7 +534,11 @@ export async function runIntegrationWizard(cwd = process.cwd(), streams = {}) {
             console.log(chalk.dim("  off-target, calibrate your panel and update display.touch.calibration."));
             console.log();
         }
-        return { exitCode: 0, configPath };
+        return {
+            exitCode: 0,
+            configPath,
+            ...(packageJsonPath && previewCommand ? { packageJsonPath } : {}),
+        };
     }
     finally {
         rl.close();

package/dist/wizard/package-writer.d.ts

@@ -0,0 +1,20 @@
+/** Walk up from `startDir` looking for package.json. */
+export declare function findPackageJson(startDir: string): string | undefined;
+/** Read a single npm script; undefined when missing. Throws on invalid JSON. */
+export declare function readPackageScript(sourceText: string, name: string): string | undefined;
+export interface UpsertScriptResult {
+    text: string;
+    /** false — the script already had this exact command; text is unchanged. */
+    changed: boolean;
+    /** The command that was replaced, when a different script existed. */
+    previous?: string;
+}
+/** Insert or update one npm script, preserving every other key and their order. */
+export declare function upsertPackageScript(sourceText: string, name: string, command: string): UpsertScriptResult;
+/**
+ * The `cuttlefish preview` command the wizard writes as the `preview` npm
+ * script. The --config path is made relative to the package.json directory
+ * (npm scripts run there), posix-separated, and explicitly ./-prefixed so
+ * sibling configs render as `./cuttlefish.config.ts`.
+ */
+export declare function previewScriptCommand(packageJsonPath: string, configPath: string): string;

package/dist/wizard/package-writer.js

@@ -0,0 +1,79 @@
+// ---------------------------------------------------------------------------
+// package.json script writer for the @typecad/ui integration wizard.
+//
+// package.json is plain JSON (no comments, no expressions), so unlike
+// cuttlefish.config.ts (see config-writer.ts) this needs no AST surgery —
+// parse, compare, set, and re-serialize with the 2-space formatting npm and
+// `cuttlefish create` both write. An unchanged script is a no-op: the
+// original text is returned verbatim so a re-run never reformats the file.
+// ---------------------------------------------------------------------------
+import fs from "node:fs";
+import path from "node:path";
+const PACKAGE_FILENAME = "package.json";
+/** Walk up from `startDir` looking for package.json. */
+export function findPackageJson(startDir) {
+    let dir = path.resolve(startDir);
+    for (;;) {
+        const candidate = path.join(dir, PACKAGE_FILENAME);
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+            return candidate;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+function parsePackageJson(sourceText) {
+    try {
+        return JSON.parse(sourceText);
+    }
+    catch (err) {
+        throw new Error(`package.json is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function scriptsOf(pkg) {
+    const scripts = pkg.scripts;
+    return typeof scripts === "object" && scripts !== null && !Array.isArray(scripts)
+        ? scripts
+        : undefined;
+}
+/** Read a single npm script; undefined when missing. Throws on invalid JSON. */
+export function readPackageScript(sourceText, name) {
+    const scripts = scriptsOf(parsePackageJson(sourceText));
+    const value = scripts?.[name];
+    return typeof value === "string" ? value : undefined;
+}
+/** Insert or update one npm script, preserving every other key and their order. */
+export function upsertPackageScript(sourceText, name, command) {
+    const pkg = parsePackageJson(sourceText);
+    const scripts = scriptsOf(pkg);
+    const previous = scripts?.[name];
+    if (previous === command) {
+        return { text: sourceText, changed: false };
+    }
+    if (!scripts) {
+        pkg.scripts = {};
+    }
+    pkg.scripts[name] = command;
+    // Keep the file's trailing-newline convention (npm writes LF; a missing
+    // final newline stays missing so the diff is one line, not two).
+    const eol = sourceText.endsWith("\r\n") ? "\r\n" : sourceText.endsWith("\n") ? "\n" : "";
+    return {
+        text: `${JSON.stringify(pkg, null, 2)}${eol}`,
+        changed: true,
+        ...(previous !== undefined ? { previous } : {}),
+    };
+}
+/**
+ * The `cuttlefish preview` command the wizard writes as the `preview` npm
+ * script. The --config path is made relative to the package.json directory
+ * (npm scripts run there), posix-separated, and explicitly ./-prefixed so
+ * sibling configs render as `./cuttlefish.config.ts`.
+ */
+export function previewScriptCommand(packageJsonPath, configPath) {
+    let rel = path.relative(path.dirname(packageJsonPath), configPath).split(path.sep).join("/");
+    if (!rel.startsWith("."))
+        rel = `./${rel}`;
+    return `cuttlefish preview --config ${rel}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typecad/ui",
-  "version": "1.0.0-alpha.12",
+  "version": "1.0.0-alpha.14",
   "description": "TypeCAD UI authoring library — HTML/CSS-driven graphics for microcontrollers",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,6 +25,9 @@
       "types": "./dist/ui-engine/*.d.ts",
       "default": "./dist/ui-engine/*.js"
     },
+    "./themes/*": {
+      "default": "./themes/*"
+    },
     "./preview/*": {
       "types": "./dist/preview/*.d.ts",
       "default": "./dist/preview/*.js"
@@ -37,14 +40,17 @@
   "sideEffects": false,
   "files": [
     "dist",
-    "src"
+    "src",
+    "assets"
   ],
   "dependencies": {
-    "@typecad/cuttlefish": "1.0.0-alpha.12",
-    "chalk": "^4.1.2",
+    "@typecad/cuttlefish": "1.0.0-alpha.14",
+    "chalk": "^6.0.0",
     "css-tree": "^3.2.1",
+    "decode-ico": "^0.4.1",
     "linkedom": "^0.18.12",
     "opentype.js": "^2.0.0",
+    "sharp": "^0.35.3",
     "typescript": "^5.7.3",
     "yoga-layout": "^3.2.1"
   },
@@ -80,7 +86,7 @@
     "firmware"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22.11.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.7",

package/src/cli.ts

@@ -1,87 +1,90 @@
-#!/usr/bin/env node
-// ---------------------------------------------------------------------------
-// @typecad/ui CLI — display integration wizard.
-//
-//   npx @typecad/ui --config    Run the interactive integration wizard
-//   npx @typecad/ui --help      Show usage
-//   npx @typecad/ui --version   Show the installed version
-// ---------------------------------------------------------------------------
-
-import { runIntegrationWizard } from "./wizard/integration-wizard.js";
-
-const USAGE = `
-@typecad/ui — HTML/CSS-driven graphics for microcontrollers
-
-Usage:
-  npx @typecad/ui --config        Configure a display (+ touch) for your
-                                  cuttlefish project interactively. Writes the
-                                  \`display\` section of cuttlefish.config.ts.
-
-Options:
-  --config            Run the integration wizard
-  --help, -h          Show this help
-  --version, -v       Print the installed @typecad/ui version
-
-The wizard asks which display module you are using (ILI9341 / ST7796S SPI TFT,
-SSD1309 I2C OLED, desktop simulator, or custom), then walks through bus pins,
-SPI/I2C speed, rotation, and touch controller wiring with hardware-aware
-defaults. It never touches the rest of your cuttlefish.config.ts.
-
-Docs: https://github.com/justind000/typecode/tree/main/packages/ui
-`.trim();
-
-function printUsage(): void {
-  console.log(USAGE);
-}
-
-async function main(argv: string[]): Promise<number> {
-  const args = argv.slice(2);
-
-  if (args.includes("--help") || args.includes("-h")) {
-    printUsage();
-    return 0;
-  }
-
-  if (args.includes("--version") || args.includes("-v")) {
-    // Lazily read the version so importing this module stays side-effect free.
-    const { readFile } = await import("node:fs/promises");
-    const { fileURLToPath } = await import("node:url");
-    const { dirname, join } = await import("node:path");
-    try {
-      const packageJson = JSON.parse(
-        await readFile(join(dirname(dirname(fileURLToPath(import.meta.url))), "package.json"), "utf-8"),
-      ) as { version?: string };
-      console.log(packageJson.version ?? "unknown");
-      return 0;
-    } catch {
-      console.log("unknown");
-      return 0;
-    }
-  }
-
-  if (args.length === 0 || (args.length === 1 && (args[0] === "--config" || args[0] === "config"))) {
-    if (!process.stdin.isTTY) {
-      console.error("The integration wizard is interactive and needs a terminal.");
-      console.error("Run `npx @typecad/ui --config` from your project directory, or configure");
-      console.error("the `display` section of cuttlefish.config.ts manually:");
-      console.error("https://github.com/justind000/typecode/tree/main/packages/ui#display-configuration");
-      return 1;
-    }
-    const result = await runIntegrationWizard(process.cwd());
-    return result.exitCode;
-  }
-
-  console.error(`Unknown option${args.length > 1 ? "s" : ""}: ${args.join(" ")}\n`);
-  printUsage();
-  return 2;
-}
-
-main(process.argv).then(
-  (code) => {
-    process.exitCode = code;
-  },
-  (error) => {
-    console.error(error instanceof Error ? error.message : error);
-    process.exitCode = 1;
-  },
-);
+#!/usr/bin/env node
+// ---------------------------------------------------------------------------
+// @typecad/ui CLI — display integration wizard.
+//
+//   npx @typecad/ui --config    Run the interactive integration wizard
+//   npx @typecad/ui --help      Show usage
+//   npx @typecad/ui --version   Show the installed version
+// ---------------------------------------------------------------------------
+
+import { runIntegrationWizard } from "./wizard/integration-wizard.js";
+
+const USAGE = `
+@typecad/ui — HTML/CSS-driven graphics for microcontrollers
+
+Usage:
+  npx @typecad/ui --config        Configure a display (+ touch) for your
+                                  cuttlefish project interactively. Writes the
+                                  \`display\` section of cuttlefish.config.ts
+                                  and a \`preview\` npm script.
+
+Options:
+  --config            Run the integration wizard
+  --help, -h          Show this help
+  --version, -v       Print the installed @typecad/ui version
+
+The wizard asks which display module you are using (ILI9341 / ST7796S SPI TFT,
+SSD1309 I2C OLED, desktop simulator, or custom), then walks through bus pins,
+SPI/I2C speed, rotation, and touch controller wiring with hardware-aware
+defaults. It never touches the rest of your cuttlefish.config.ts, and adds a
+\`preview\` script to package.json so the desktop preview renderer starts with
+\`npm run preview\`.
+
+Docs: https://github.com/justind000/typecode/tree/main/packages/ui
+`.trim();
+
+function printUsage(): void {
+  console.log(USAGE);
+}
+
+async function main(argv: string[]): Promise<number> {
+  const args = argv.slice(2);
+
+  if (args.includes("--help") || args.includes("-h")) {
+    printUsage();
+    return 0;
+  }
+
+  if (args.includes("--version") || args.includes("-v")) {
+    // Lazily read the version so importing this module stays side-effect free.
+    const { readFile } = await import("node:fs/promises");
+    const { fileURLToPath } = await import("node:url");
+    const { dirname, join } = await import("node:path");
+    try {
+      const packageJson = JSON.parse(
+        await readFile(join(dirname(dirname(fileURLToPath(import.meta.url))), "package.json"), "utf-8"),
+      ) as { version?: string };
+      console.log(packageJson.version ?? "unknown");
+      return 0;
+    } catch {
+      console.log("unknown");
+      return 0;
+    }
+  }
+
+  if (args.length === 0 || (args.length === 1 && (args[0] === "--config" || args[0] === "config"))) {
+    if (!process.stdin.isTTY) {
+      console.error("The integration wizard is interactive and needs a terminal.");
+      console.error("Run `npx @typecad/ui --config` from your project directory, or configure");
+      console.error("the `display` section of cuttlefish.config.ts manually:");
+      console.error("https://github.com/justind000/typecode/tree/main/packages/ui#display-configuration");
+      return 1;
+    }
+    const result = await runIntegrationWizard(process.cwd());
+    return result.exitCode;
+  }
+
+  console.error(`Unknown option${args.length > 1 ? "s" : ""}: ${args.join(" ")}\n`);
+  printUsage();
+  return 2;
+}
+
+main(process.argv).then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+  },
+);

package/src/engine-index.ts

@@ -1,51 +1,53 @@
-// ---------------------------------------------------------------------------
-// Engine entry point for @typecad/ui.
-//
-// Cuttlefish dynamically imports this module when UI usage is detected:
-//   const engine = await import("@typecad/ui/engine");
-//   const hook = await engine.registerTranspilerUI();
-//
-// registerTranspilerUI() returns an object implementing the TranspilerUIHook
-// interface defined in @typecad/cuttlefish. This is the single runtime
-// contract between the two packages.
-// ---------------------------------------------------------------------------
-
-import type { TranspilerUIHook } from "@typecad/cuttlefish/ui-hook";
-import {
-  resetUIRegistry, loadUIModule, loadUIModuleFromText, getUIModule,
-  hasUIModule, allUIModules, allLoweredUIModules,
-  markEntryHasUI, entryHasUI, clearEntryHasUI, lowerOnMount,
-  generateProjectUITypeDeclarations,
-} from "./ui-engine/ui-registry.js";
-import { resolveColor, resolveColorInternal } from "./ui-engine/color.js";
-import { emitRuntimeHeader } from "./ui-engine/runtime-header.js";
-import { emitCuttlefishGfx } from "./ui-engine/runtime-header/cuttlefish-gfx.js";
-import { splitUiFile } from "./ui-engine/ui-file-splitter.js";
-
-export type { TranspilerUIHook };
-
-/**
- * Build and return the TranspilerUIHook — the object cuttlefish core uses
- * to access all UI capabilities (parsing, layout, lowering, emission).
- */
-export function registerTranspilerUI(): TranspilerUIHook {
-  return {
-    resetUIRegistry,
-    loadUIModule,
-    loadUIModuleFromText,
-    getUIModule,
-    hasUIModule,
-    allUIModules,
-    allLoweredUIModules,
-    markEntryHasUI,
-    entryHasUI,
-    clearEntryHasUI,
-    lowerOnMount,
-    resolveColor,
-    resolveColorInternal,
-    emitRuntimeHeader,
-    emitCuttlefishGfx,
-    splitUiFile,
-    generateProjectUITypeDeclarations,
-  };
-}
+// ---------------------------------------------------------------------------
+// Engine entry point for @typecad/ui.
+//
+// Cuttlefish dynamically imports this module when UI usage is detected:
+//   const engine = await import("@typecad/ui/engine");
+//   const hook = await engine.registerTranspilerUI();
+//
+// registerTranspilerUI() returns an object implementing the TranspilerUIHook
+// interface defined in @typecad/cuttlefish. This is the single runtime
+// contract between the two packages.
+// ---------------------------------------------------------------------------
+
+import type { TranspilerUIHook } from "@typecad/cuttlefish/ui-hook";
+import {
+  resetUIRegistry, loadUIModule, loadUIModuleFromText, getUIModule,
+  hasUIModule, allUIModules, allLoweredUIModules,
+  markEntryHasUI, entryHasUI, clearEntryHasUI, lowerOnMount,
+  generateProjectUITypeDeclarations,
+} from "./ui-engine/ui-registry.js";
+import { resolveColor, resolveColorInternal } from "./ui-engine/color.js";
+import { emitRuntimeHeader } from "./ui-engine/runtime-header.js";
+import { emitCuttlefishGfx } from "./ui-engine/runtime-header/cuttlefish-gfx.js";
+import { splitUiFile } from "./ui-engine/ui-file-splitter.js";
+import { warmUpImageDecoding } from "./ui-engine/image-decode.js";
+
+export type { TranspilerUIHook };
+
+/**
+ * Build and return the TranspilerUIHook — the object cuttlefish core uses
+ * to access all UI capabilities (parsing, layout, lowering, emission).
+ */
+export function registerTranspilerUI(): TranspilerUIHook {
+  return {
+    resetUIRegistry,
+    loadUIModule,
+    loadUIModuleFromText,
+    getUIModule,
+    hasUIModule,
+    allUIModules,
+    allLoweredUIModules,
+    markEntryHasUI,
+    entryHasUI,
+    clearEntryHasUI,
+    lowerOnMount,
+    resolveColor,
+    resolveColorInternal,
+    emitRuntimeHeader,
+    emitCuttlefishGfx,
+    splitUiFile,
+    warmUpImageDecoding,
+    generateProjectUITypeDeclarations,
+  };
+}