@typecad/ui 1.0.0-alpha.13 → 1.0.0-alpha.15

package/dist/wizard/display-catalog.js

@@ -1,8 +1,8 @@
 // ---------------------------------------------------------------------------
 // Display + touch hardware catalog for the @typecad/ui integration wizard.
 //
-// Mirrors the built-in display profiles exported by @typecad/framework-arduino
-// (src/displays/*.ts — BUILT_IN_PROFILES) and the TouchLibrary union in
+// Mirrors the built-in display profiles exported by the active framework
+// (BUILT_IN_PROFILES) and the TouchLibrary union in
 // @typecad/cuttlefish's display-profile.ts. The wizard asks questions and
 // fills defaults from these entries; the resulting object literal is written
 // into the project's cuttlefish.config.ts `display` section.
@@ -32,7 +32,6 @@ export const DISPLAY_CATALOG = [
             colorOrder: "rgb",
             antialias: true,
         },
-        arduinoLibraries: ["Adafruit GFX Library", "Adafruit ILI9341"],
         wiringNote: "Defaults assume ESP32 VSPI: SCK=18, MOSI=23, MISO=19.",
     },
     {
@@ -57,10 +56,9 @@ export const DISPLAY_CATALOG = [
             invert: false,
             antialias: true,
         },
-        arduinoLibraries: ["Adafruit GFX Library", "Adafruit ST7735 and ST7789 Library"],
         wiringNote: "Defaults assume ESP32 VSPI: SCK=18, MOSI=23, MISO=19. Adafruit_ST7796S.h comes from the" +
             " Adafruit_ST7735_and_ST7789 fork bundled in the typecode demos (demos/demo-st/lib) —" +
-            " copy it into your sketchbook libraries/ if your Library Manager copy lacks the class.",
+            " copy it into your libraries/ folder if your Library Manager copy lacks the class.",
     },
     {
         id: "ssd1309-i2c",
@@ -75,7 +73,6 @@ export const DISPLAY_CATALOG = [
             rotation: 0,
             antialias: false,
         },
-        arduinoLibraries: ["Adafruit GFX Library", "Adafruit SSD1306"],
     },
     {
         id: "sdl",
@@ -116,7 +113,6 @@ export const TOUCH_CATALOG = [
             // Typical raw-ADC range for 320×240 modules; refine per panel.
             calibration: { xMin: 375, xMax: 3950, yMin: 200, yMax: 3750 },
         },
-        arduinoLibrary: "XPT2046_Touchscreen",
     },
     {
         id: "FT6336U",
@@ -128,7 +124,6 @@ export const TOUCH_CATALOG = [
             i2cFrequency: 400_000,
         },
         // The framework's FT6336U adapter includes RAK14014_FT6336U.h.
-        arduinoLibrary: "RAK14014-FT6336U",
     },
     {
         id: "GT911",
@@ -139,7 +134,6 @@ export const TOUCH_CATALOG = [
             i2cAddress: 0x5d,
             i2cFrequency: 400_000,
         },
-        arduinoLibrary: "GT911",
     },
     {
         id: "CST816S",
@@ -150,7 +144,6 @@ export const TOUCH_CATALOG = [
             i2cAddress: 0x15,
             i2cFrequency: 400_000,
         },
-        arduinoLibrary: "CST816S",
     },
     {
         id: "Adafruit_TouchScreen",
@@ -161,7 +154,6 @@ export const TOUCH_CATALOG = [
             analogPins: { xp: 24, yp: 25, xm: 26, ym: 27, rx: 300 },
             calibration: { xMin: 100, xMax: 900, yMin: 120, yMax: 900 },
         },
-        arduinoLibrary: "Adafruit TouchScreen",
     },
     {
         id: "Adafruit_STMPE610",
@@ -172,7 +164,6 @@ export const TOUCH_CATALOG = [
             cs: 14,
             calibration: { xMin: 375, xMax: 3950, yMin: 200, yMax: 3750 },
         },
-        arduinoLibrary: "Adafruit STMPE610",
     },
     {
         id: "adapter",

package/dist/wizard/index.d.ts

@@ -2,6 +2,8 @@ export { DISPLAY_CATALOG, TOUCH_CATALOG, findPinConflicts, } from "./display-cat
 export type { DisplayCatalogEntry, TouchCatalogEntry, WizardBus, WizardTouchKind, } from "./display-catalog.js";
 export { findCuttlefishConfig, findSyntaxError, readConfigSection, readEntryPath, renderDisplayBody, renderDisplayProperty, upsertDisplaySection, } from "./config-writer.js";
 export type { ConfigRecord, RenderDisplayOptions, UpsertDisplayResult, } from "./config-writer.js";
+export { findPackageJson, previewScriptCommand, readPackageScript, upsertPackageScript, } from "./package-writer.js";
+export type { UpsertScriptResult } from "./package-writer.js";
 export { renderStarterUi } from "./starter-ui.js";
 export { runIntegrationWizard } from "./integration-wizard.js";
 export type { WizardRunResult, WizardStreams } from "./integration-wizard.js";

package/dist/wizard/index.js

@@ -6,5 +6,6 @@
 // ---------------------------------------------------------------------------
 export { DISPLAY_CATALOG, TOUCH_CATALOG, findPinConflicts, } from "./display-catalog.js";
 export { findCuttlefishConfig, findSyntaxError, readConfigSection, readEntryPath, renderDisplayBody, renderDisplayProperty, upsertDisplaySection, } from "./config-writer.js";
+export { findPackageJson, previewScriptCommand, readPackageScript, upsertPackageScript, } from "./package-writer.js";
 export { renderStarterUi } from "./starter-ui.js";
 export { runIntegrationWizard } from "./integration-wizard.js";

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

@@ -2,6 +2,9 @@ export interface WizardRunResult {
     exitCode: number;
     /** Absolute path of the config that was written, when a write happened. */
     configPath?: string;
+    /** Absolute path of the package.json holding the preview script, when the
+     *  script was added or already present. */
+    packageJsonPath?: string;
 }
 /** Optional stream overrides so tests can drive the interactive flow. */
 export interface WizardStreams {

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,31 +501,20 @@ export async function runIntegrationWizard(cwd = process.cwd(), streams = {}) {
                 }
             }
         }
-        // --- 10. Next steps ---------------------------------------------------------------
+        // --- 11. Next steps ---------------------------------------------------------------
         console.log();
         console.log(chalk.cyan("Next steps"));
         console.log();
-        const libraries = [];
-        if (displayEntry.arduinoLibraries)
-            libraries.push(...displayEntry.arduinoLibraries);
-        if (touchEntry?.arduinoLibrary && touchRecord?.library)
-            libraries.push(touchEntry.arduinoLibrary);
-        if (libraries.length > 0) {
-            console.log("  1. Install the display/touch Arduino libraries (once per machine):");
-            console.log();
-            console.log(`     ${chalk.cyan(`arduino-cli lib install ${libraries.map((lib) => `"${lib}"`).join(" ")}`)}`);
-            console.log();
-        }
-        const firstStep = libraries.length > 0 ? 2 : 1;
+        const firstStep = 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();
         console.log(`     ${chalk.cyan("npx @typecad/cuttlefish build --compile")}`);
         console.log();
-        console.log(`  ${firstStep + 2}. Flash it (set console.port in the config, or pass --port):`);
+        console.log(`  ${firstStep + 2}. Flash it (pass --port, or set CUTTLEFISH_PORT):`);
         console.log();
         console.log(`     ${chalk.cyan("npx @typecad/cuttlefish build --compile --upload")}`);
         console.log();
@@ -478,7 +523,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.13",
+  "version": "1.0.0-alpha.15",
   "description": "TypeCAD UI authoring library — HTML/CSS-driven graphics for microcontrollers",
   "type": "module",
   "main": "./dist/index.js",
@@ -44,8 +44,8 @@
     "assets"
   ],
   "dependencies": {
-    "@typecad/cuttlefish": "1.0.0-alpha.13",
-    "chalk": "^4.1.2",
+    "@typecad/cuttlefish": "1.0.0-alpha.15",
+    "chalk": "^6.0.0",
     "css-tree": "^3.2.1",
     "decode-ico": "^0.4.1",
     "linkedom": "^0.18.12",
@@ -86,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/preview/host-ui-runtime.ts

@@ -665,7 +665,6 @@ export class PreviewUIRuntime {
   }
 
   private navigate(screenIdx: number): void {
-    this.onDiagnostics?.(`NAV -> screen ${screenIdx}`);
     const next = Math.trunc(Number(screenIdx));
     if (!Number.isFinite(next) || next < 0 || next >= this.screenCount || next === this.activeScreen) return;
     this.activeScreen = next;

package/src/ui-engine/model.ts

@@ -322,9 +322,14 @@ function borderStyle(style: CSSProperty): 0 | 1 | 2 {
 }
 
 function borderWidthOf(style: CSSProperty): number {
+  // A none-style border renders nothing and must consume no space either:
+  // the draw path subtracts borderWidth*2 from the text max width, so a
+  // residual UA width on a borderless kit button wrapped its last glyph
+  // ("Primar" / "y"). Style none wins over any declared width.
+  if (borderStyle(style) === 0) return 0;
   const px = cssPx(style.borderWidth);
   if (px > 0) return Math.max(1, Math.min(8, px));
-  return borderStyle(style) === 0 ? 0 : 1;
+  return 1;
 }
 
 /** Per-side border width: the per-side field wins when set, else falls back to