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

package/dist/cli.js

@@ -7,25 +7,28 @@
 //   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
+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() {
     console.log(USAGE);

package/dist/preview/host-ui-runtime.js

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

package/dist/ui-engine/model.js

@@ -78,10 +78,16 @@ function borderStyle(style) {
     return 0;
 }
 function borderWidthOf(style) {
+    // 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
  *  the uniform borderWidth. Used for border-left/top/right/bottom support. */

package/dist/ui-engine/runtime-header/node-draw-body.js

@@ -1237,10 +1237,16 @@ static inline uint8_t ui_render_screen_bands(int16_t rx, int16_t ry, int16_t rw,
       int16_t origBoxH = __ui_nodes[c].box.h;
       __ui_nodes[c].box.x = static_cast<int16_t>(origBoxX - rx);
       __ui_nodes[c].box.y = static_cast<int16_t>(origBoxY - ry - bandTop);
-      // Clamp the face to the scroll viewport (band-local coords). The
-      // shifted box/draw geometry stays within the candidate's clip bounds;
-      // text wrapping and layout metrics shrink with the box. Fully clipped
-      // faces drop out here.
+      // Clamp the face to the scroll viewport (band-local DRAW coords). The
+      // clamp must operate on the node's DRAW position — box.y is
+      // content-local and the ancestor scroll is subtracted later, inside
+      // ui_draw_y_for_node, so comparing box.y against display-space clip
+      // bounds passed scrolled content whose CONTENT coordinate numerically
+      // fell inside the viewport: a button scrolled up past the viewport top
+      // painted over the header, and the smearing stuck (nothing repaints
+      // the header afterwards). Clamp the draw position and shift the box by
+      // the delta; text wrapping and layout metrics shrink with the box.
+      // Fully clipped faces drop out here.
       {
         // int32 math: the unclipped sentinels are ±32767 and the band-local
         // conversion subtracts region/band offsets — int16 arithmetic wraps
@@ -1251,29 +1257,25 @@ static inline uint8_t ui_render_screen_bands(int16_t rx, int16_t ry, int16_t rw,
         int32_t clipBotL = static_cast<int32_t>(__ui_scroll_candidates[ci].clipBottom) - ry - bandTop;
         int32_t clipLeftL = static_cast<int32_t>(__ui_scroll_candidates[ci].clipLeft) - rx;
         int32_t clipRightL = static_cast<int32_t>(__ui_scroll_candidates[ci].clipRight) - rx;
-        int16_t boxY0 = __ui_nodes[c].box.y;
-        if (boxY0 < clipTopL) {
-          __ui_nodes[c].box.y = static_cast<int16_t>(clipTopL);
-          __ui_nodes[c].box.h = static_cast<int16_t>(__ui_nodes[c].box.h - (clipTopL - boxY0));
-        }
-        if (static_cast<int32_t>(__ui_nodes[c].box.y) + __ui_nodes[c].box.h > clipBotL) {
-          __ui_nodes[c].box.h = static_cast<int16_t>(clipBotL - __ui_nodes[c].box.y);
-        }
-        int16_t boxX0 = __ui_nodes[c].box.x;
-        if (boxX0 < clipLeftL) {
-          __ui_nodes[c].box.x = static_cast<int16_t>(clipLeftL);
-          __ui_nodes[c].box.w = static_cast<int16_t>(__ui_nodes[c].box.w - (clipLeftL - boxX0));
-        }
-        if (static_cast<int32_t>(__ui_nodes[c].box.x) + __ui_nodes[c].box.w > clipRightL) {
-          __ui_nodes[c].box.w = static_cast<int16_t>(clipRightL - __ui_nodes[c].box.x);
-        }
-        if (__ui_nodes[c].box.w <= 0 || __ui_nodes[c].box.h <= 0) {
+        int16_t dispY0 = ui_draw_y_for_node(c);
+        int16_t dispX0 = ui_draw_x_for_node(c);
+        int32_t y0 = dispY0 < clipTopL ? clipTopL : dispY0;
+        int32_t y1 = static_cast<int32_t>(dispY0) + __ui_nodes[c].box.h > clipBotL ? clipBotL : static_cast<int32_t>(dispY0) + __ui_nodes[c].box.h;
+        int32_t x0 = dispX0 < clipLeftL ? clipLeftL : dispX0;
+        int32_t x1 = static_cast<int32_t>(dispX0) + __ui_nodes[c].box.w > clipRightL ? clipRightL : static_cast<int32_t>(dispX0) + __ui_nodes[c].box.w;
+        if (x1 - x0 <= 0 || y1 - y0 <= 0) {
           __ui_nodes[c].box.x = origBoxX;
           __ui_nodes[c].box.y = origBoxY;
           __ui_nodes[c].box.w = origBoxW;
           __ui_nodes[c].box.h = origBoxH;
           continue;
         }
+        // box.y/box.x already carry the band shift; add the clamp delta on
+        // top (y0 - dispY0 is 0 when unclipped, preserving the shift).
+        __ui_nodes[c].box.y = static_cast<int16_t>(__ui_nodes[c].box.y + (y0 - dispY0));
+        __ui_nodes[c].box.h = static_cast<int16_t>(y1 - y0);
+        __ui_nodes[c].box.x = static_cast<int16_t>(__ui_nodes[c].box.x + (x0 - dispX0));
+        __ui_nodes[c].box.w = static_cast<int16_t>(x1 - x0);
       }
       int16_t baseDrawX = ui_base_draw_x_for_node(c);
       int16_t baseDrawY = ui_base_draw_y_for_node(c);

package/dist/ui-engine/shadcn-kit.d.ts

@@ -1 +1 @@
-export declare const SHADCN_KIT_CSS = "/* ---------------------------------------------------------------------------\n * shadcn-style component kit \u2014 BUILT IN and always included.\n *\n * These tokens + class recipes are prepended to every build and preview\n * automatically, BEFORE your stylesheets, so anything you write overrides\n * them by normal cascade order. No scaffolding, no imports needed: put the\n * classes on native elements and they work.\n *\n * THEMES: a theme is any CSS file. Pre-packaged ones ship with @typecad/ui \u2014\n * import by bare specifier from a <style> block (or the sidecar .ui.css):\n *\n *   @import \"@typecad/ui/themes/blue.css\";   (zinc slate stone gray neutral\n *                                             blue green red)\n *\n * Your own: save a ui.shadcn.com / tweakcn export into the project and\n * @import it by path \u2014 its :root/.dark token blocks override the kit\n * defaults (later definitions win). Both dialects parse \u2014 classic HSL channel triplets and\n * Tailwind-v4 oklch(); alpha in colors is ignored (no blending on bare\n * metal). Dark mode activates with themeClass: 'dark' in the config's\n * display block.\n *\n * Overriding recipes: redefine any class in your own stylesheet; your\n * definition wins.\n *\n * Components (classes over native elements):\n *   Button      <button class=\"btn btn-primary\">Save</button>\n *               variants: -secondary -outline -ghost -destructive\n *               sizes: .btn-sm .btn-lg   full width: .btn-block\n *   Badge       <text class=\"badge badge-secondary\">new</text>\n *               variants: -default(omit) -destructive -outline\n *   Card        <view class=\"card\">\n *                 <view class=\"card-header\">\n *                   <text class=\"card-title\">Title</text>\n *                   <text class=\"card-description\">Subtitle</text>\n *                 </view>\n *                 <view class=\"card-content\">...</view>\n *                 <view class=\"card-footer\">...buttons...</view>\n *               </view>\n *   Input       <input class=\"input\" placeholder=\"...\"/>\n *   Label       <label class=\"form-label\">Name</label>\n *   Row (kit)   <view class=\"row\"> ... </view>   (flex row + gap, for composing)\n *   Validation  .input-error (destructive border) + .field-error hint;\n *               runtime-driven: bind borderColor/visible to a signal\n *   Separator   <hr class=\"separator\"/> (horizontal) or\n *               <hr class=\"vseparator\"/> (vertical; stretches to the row height)\n *   Alert       <view class=\"alert alert-destructive\">\n *                 <text class=\"alert-title\">...</text>\n *                 <text class=\"alert-description\">...</text>\n *               </view>\n *   Skeleton    <view class=\"skeleton\"/>            (pulse while loading)\n *   Spinner     <view class=\"spinner\"><view class=\"spinner-dot\"/></view>\n *               (indeterminate loading: a dot orbiting a ring via pure\n *                transform keyframes \u2014 translate lerps smoothly, unlike\n *                rotate which only renders exact quarter turns)\n *   Dialog      <dialog id=\"d\"><view class=\"dialog-scrim\" on:click={...}/>\n *               <view class=\"dialog-card\"> ... <view class=\"dialog-footer\">\n *               </view></dialog>\n *               (centered modal: programmatic ui.dialog.open(id), scrim tap\n *                closes; same slot machinery as the drawer)\n *   Toast       <toast id=\"t\" side=\"bottom\" duration=\"2500\" class=\"toast\">\n *               ...</toast>  (ui.toast(id) shows it; auto-closes after the\n *               duration; stacks as authored siblings)\n *   Progress    <progress class=\"progress\" value=\"40\"/>\n *   Avatar      <img class=\"avatar\" src=\"face.bmp\"/>\n *   Switch      <check class=\"switch\"/>             (pill container; the\n *               16px indicator is runtime-drawn at the top-left \u2014 best-effort)\n *   Tabs        <view class=\"tabs-list\"><button class=\"tabs-trigger\">..</button>..\n *               <view class=\"tabs-content-area\"><view class=\"tabs-content\">..\n *               (panes toggle via ui.bind(x, 'visible', ...) on a signal)\n *   Accordion   <view class=\"accordion\"><view class=\"accordion-item\">..\n *               (content toggles via ui.bind visible; chevron via text bind)\n *   Table       <table> ... </table>                (UA styles apply; see the\n *               html-table-approximation build note)\n * ------------------------------------------------------------------------- */\n\n:root {\n  --background: #ffffff;\n  --foreground: #09090b;\n  --card: #ffffff;\n  --card-foreground: #09090b;\n  --primary: #18181b;\n  --primary-foreground: #fafafa;\n  --secondary: #f4f4f5;\n  --secondary-foreground: #18181b;\n  --muted: #f4f4f5;\n  --muted-foreground: #71717a;\n  --accent: #f4f4f5;\n  --accent-foreground: #18181b;\n  --destructive: #dc2626;\n  --destructive-foreground: #fafafa;\n  --destructive-background: #fee2e2;\n  --border: #e4e4e7;\n  --input: #e4e4e7;\n  --radius: 8px;\n  --shadow-sm: 0 1px 3px rgb(0 0 0 / 0.1);\n  /* Solid scrim for dialogs \u2014 alpha blending needs a canvas underneath, so\n     the kit uses an opaque near-black that reads as a dimmed backdrop. */\n  --scrim: #101014;\n}\n\n.dark {\n  --background: #09090b;\n  --foreground: #fafafa;\n  --card: #18181b;\n  --card-foreground: #fafafa;\n  --primary: #fafafa;\n  --primary-foreground: #18181b;\n  --secondary: #27272a;\n  --secondary-foreground: #fafafa;\n  --muted: #27272a;\n  --muted-foreground: #a1a1aa;\n  --accent: #27272a;\n  --accent-foreground: #fafafa;\n  --destructive: #ef4444;\n  --destructive-foreground: #09090b;\n  --destructive-background: #451a1a;\n  --border: #27272a;\n  --input: #3f3f46;\n  --radius: 8px;\n}\n\n/* ---- Button ---------------------------------------------------------------- */\n\n.btn {\n  border-radius: var(--radius);\n  padding: 10px 16px;\n  font-weight: bold;\n  transition: background 80ms;\n}\n.btn:pressed { transform: translateY(1px); }\n.btn-primary { background: var(--primary); color: var(--primary-foreground); }\n.btn-secondary { background: var(--secondary); color: var(--secondary-foreground); }\n.btn-outline { background: var(--background); color: var(--foreground); border: 1px solid var(--border); }\n.btn-ghost { color: var(--foreground); }\n.btn-destructive { background: var(--destructive); color: var(--destructive-foreground); }\n.btn-sm { padding: 6px 10px; min-height: 32px; font-size: 12px; }\n.btn-lg { padding: 14px 22px; min-height: 52px; font-size: 18px; }\n.btn-block { align-self: stretch; }\n\n/* ---- Badge ------------------------------------------------------------------ */\n\n.badge {\n  background: var(--primary);\n  color: var(--primary-foreground);\n  padding: 2px 8px;\n  border-radius: 999px;\n  font-size: 12px;\n  text-align: center;\n}\n.badge-secondary { background: var(--secondary); color: var(--secondary-foreground); }\n.badge-destructive { background: var(--destructive); color: var(--destructive-foreground); }\n.badge-outline { background: var(--background); color: var(--foreground); border: 1px solid var(--border); }\n\n/* ---- Layout utility -------------------------------------------------------------\n   Not a shadcn component \u2014 a kit convenience for composing recipes. */\n\n.row { flex-direction: row; align-items: center; gap: 8px; }\n\n/* ---- Card ------------------------------------------------------------------- */\n\n.card {\n  background: var(--card);\n  color: var(--card-foreground);\n  border: 1px solid var(--border);\n  border-radius: var(--radius);\n  box-shadow: var(--shadow-sm);\n  padding: 16px;\n  gap: 8px;\n  align-self: stretch;\n}\n.card-header { gap: 4px; }\n.card-title { font-size: 18px; font-weight: bold; }\n.card-description { font-size: 14px; color: var(--muted-foreground); }\n.card-content { gap: 8px; }\n.card-footer { flex-direction: row; gap: 8px; }\n\n/* ---- Tabs ---------------------------------------------------------------- */\n\n/* Segmented trigger row (shadcn TabsList). Active-trigger styling is driven\n   at runtime by ui.bind background/color bindings in author code \u2014 runtime\n   color swaps are literal hex (compile-time tokens), so pin them to the\n   active theme the way native_demo accents do. */\n.tabs-list {\n  flex-direction: row;\n  gap: 4px;\n  align-self: stretch;\n  background: var(--muted);\n  border-radius: var(--radius);\n  padding: 4px;\n}\n.tabs-trigger {\n  flex-grow: 1;\n  border-radius: calc(var(--radius) - 2px);\n  padding: 6px 10px;\n  min-height: 32px;\n  font-size: 13px;\n  text-align: center;\n}\n/* Fixed-height content region: panes are absolutely stacked inside it and\n   toggled via ui.bind(x, 'visible', ...) \u2014 layout keeps every pane's box,\n   so switching never re-flows. */\n.tabs-content-area {\n  position: relative;\n  align-self: stretch;\n  height: 150px;\n}\n.tabs-content {\n  position: absolute;\n  left: 0;\n  top: 0;\n  right: 0;\n  bottom: 0;\n  gap: 8px;\n}\n\n/* ---- Accordion (single-open) --------------------------------------------- */\n\n/* Stacked collapsible sections. The trigger is a button + chevron row; the\n   content pane toggles via ui.bind(x, 'visible', () => signal === i) \u2014 the\n   same signal pattern as Tabs. The chevron swaps v/^ via a text binding. */\n.accordion {\n  gap: 8px;\n  align-self: stretch;\n}\n.accordion-item {\n  background: var(--card);\n  border: 1px solid var(--border);\n  border-radius: var(--radius);\n}\n.accordion-trigger-row {\n  flex-direction: row;\n  align-items: center;\n  gap: 8px;\n  padding: 10px 12px;\n}\n.accordion-trigger {\n  flex-grow: 1;\n  text-align: left;\n  font-weight: bold;\n  padding: 0;\n  min-height: 20px;\n  /* The UA sheet gives every button a 1px border (border: 1px solid, colored\n     by the foreground token). A trigger is a plain text row on the card \u2014\n     cancel it or each one renders with a bright outline. */\n  border: none;\n}\n.accordion-chevron {\n  color: var(--muted-foreground);\n  font-size: 14px;\n  /* Wide enough for the '^' glyph (advance 12px at 14px size) \u2014 a single\n     char wider than the box wraps to nothing. */\n  width: 16px;\n  text-align: center;\n}\n.accordion-content {\n  padding: 0 12px 10px 12px;\n  gap: 8px;\n}\n\n/* ---- Form controls ----------------------------------------------------------- */\n\n.input {\n  background: var(--background);\n  color: var(--foreground);\n  border: 1px solid var(--input);\n  border-radius: var(--radius);\n}\n.form-label { color: var(--foreground); font-size: 14px; }\n\n/* Switch: pill container. The runtime draws a 16px circular knob that\n   slides with state \u2014 hollow at the left when off, solid at the right when\n   on (a static jump, no travel animation). min-height overrides the UA\n   touch target so the pill stays 26px tall. */\n.switch {\n  width: 44px;\n  height: 26px;\n  /* Override the UA's touch-target min-height (42px on small panels) \u2014 the\n     pill must stay 26px tall to read as a switch, not a checkbox. */\n  min-height: 26px;\n  border-radius: 999px;\n  border: 1px solid var(--border);\n  /* --card, not --muted: on a bare (near-black) page background a --muted\n     track reads as a stray gray box; --card keeps the pill affordance while\n     staying quiet. Swap back to var(--muted) inside lighter containers. */\n  background: var(--card);\n}\n\n/* ---- Checked-state pairs (shadcn data-[state=checked]) ------------------------\n   The ON control carries the primary pair: the switch's TRACK turns primary\n   with a primary-foreground knob, the checkbox face and the radio's selected\n   ring do the same. The select's pair themes the OPTION LIST's selected row\n   with the accent pair (shadcn's SelectItem selected state). These bake at\n   build time from :checked rules (a separate style bucket, like :pressed);\n   the device runtime swaps the pair onto the indicator when the value flips,\n   and the preview draws through the same fields. */\n.switch:checked {\n  background: var(--primary);\n  border-color: var(--primary);\n  color: var(--primary-foreground);\n}\ncheck:checked {\n  background: var(--primary);\n  color: var(--primary-foreground);\n}\nradio:checked {\n  background: var(--primary);\n  color: var(--primary-foreground);\n}\n.select:checked {\n  background: var(--accent);\n  color: var(--accent-foreground);\n}\n\n/* ---- Form validation states -------------------------------------------------- */\n\n/* Static hook: always-invalid styling for hardcoded markup. Runtime-driven\n   validation (recommended) binds the input's borderColor + a .field-error\n   hint's visible/text to a signal \u2014 see the demo's Forms screen. */\n.input-error {\n  border-color: var(--destructive);\n}\n.field-error {\n  color: var(--destructive);\n  font-size: 12px;\n}\n.field-success {\n  color: var(--muted-foreground);\n  font-size: 12px;\n}\n\n/* ---- Separator ---------------------------------------------------------------- */\n\n.separator {\n  height: 1px;\n  background: var(--border);\n  margin: 8px 0;\n}\n/* Vertical: 1px wide, stretches to the row's cross height (shadcn's\n   <Separator orientation=\"vertical\" /> \u2014 flex column + align-self: stretch). */\n.vseparator {\n  width: 1px;\n  height: 100%;\n  align-self: stretch;\n  background: var(--border);\n  margin: 0 8px;\n}\n\n/* ---- Alert -------------------------------------------------------------------- */\n\n.alert {\n  background: var(--background);\n  color: var(--foreground);\n  border: 1px solid var(--border);\n  border-radius: var(--radius);\n  padding: 12px;\n  gap: 4px;\n  align-self: stretch;\n}\n.alert-destructive {\n  background: var(--destructive-background);\n  border: 1px solid var(--destructive);\n  color: var(--destructive);\n}\n.alert-title { font-weight: bold; }\n.alert-description { font-size: 14px; color: var(--muted-foreground); }\n\n/* ---- Skeleton (loading placeholder) --------------------------------------------- */\n\n/* Opacity pulse. If the target display's keyframe support skips opacity,\n   the block still renders as a static muted placeholder. */\n.skeleton {\n  background: var(--muted);\n  border-radius: var(--radius);\n  height: 16px;\n  align-self: stretch;\n  animation: ui-skeleton-pulse 1.2s ease-in-out infinite;\n}\n@keyframes ui-skeleton-pulse {\n  0% { opacity: 1; }\n  50% { opacity: 0.55; }\n  100% { opacity: 1; }\n}\n\n/* ---- Spinner ---------------------------------------------------------------- */\n\n/* Indeterminate loading indicator: a dot orbiting inside a ring, pure\n   transform keyframes. translate() lerps CONTINUOUSLY between stops (unlike\n   rotate(), which only renders exact quarter turns), so the orbit is smooth.\n   The dot is absolute + out of flow; the ring is a fixed square so border\n   clipping stays symmetric. Sizes: change .spinner's width/height and keep\n   the dot inset consistent (orbit travel = inner - dot). */\n.spinner {\n  position: relative;\n  width: 22px;\n  height: 22px;\n  border: 2px solid var(--muted);\n  border-radius: 999px;\n}\n.spinner-dot {\n  position: absolute;\n  /* The dot's BASE position is the orbit's TOP-LEFT corner, not the ring\n     center: the keyframes translate 0..8px from here, and the path only\n     centers when base + travel/2 == ring center (with the 2px border,\n     top/left 2px + border lands the 6px dot at 4,4; its center travels\n     7..15 around the 22px ring's center at 11,11). */\n  top: 2px;\n  left: 2px;\n  width: 6px;\n  height: 6px;\n  background: var(--primary);\n  border-radius: 999px;\n  animation: ui-spinner-orbit 1000ms linear infinite;\n}\n@keyframes ui-spinner-orbit {\n  0%   { transform: translate(0px, 0px); }\n  25%  { transform: translate(8px, 0px); }\n  50%  { transform: translate(8px, 8px); }\n  75%  { transform: translate(0px, 8px); }\n  100% { transform: translate(0px, 0px); }\n}\n/* ---- Dialog ---------------------------------------------------------------- */\n\n/* Centered modal: <dialog> is a centered drawer (side-free) \u2014 programmatic\n   open/close via ui.dialog.open(id)/close(id?), hidden while closed by the\n   runtime (visibility gate for centered panels; offsets can't hide them).\n   The scrim is part of the markup: an absolute full-area view whose tap\n   closes the dialog; the card sits above it. z-index keeps both over page\n   content. */\n.dialog-scrim {\n  position: absolute;\n  left: 0;\n  right: 0;\n  top: 0;\n  bottom: 0;\n  background: var(--scrim);\n  z-index: 30;\n}\n.dialog-card {\n  position: absolute;\n  left: 24px;\n  right: 24px;\n  top: 64px;\n  background: var(--card);\n  color: var(--card-foreground);\n  border: 1px solid var(--border);\n  border-radius: var(--radius);\n  box-shadow: var(--shadow-lg);\n  padding: 16px;\n  gap: 8px;\n  z-index: 31;\n}\n.dialog-footer {\n  flex-direction: row;\n  justify-content: flex-end;\n  gap: 8px;\n}\n\n/* ---- Toast ----------------------------------------------------------------- */\n\n/* Transient notification: <toast side=\"bottom\" duration=\"2500\"> slides from\n   the bottom edge (author-positioned, flush to the edge so the slide fully\n   hides it) and auto-closes after duration ms. Show with ui.toast(id).\n   Sibling toasts stack by author layout; each closes on its own timer. */\n.toast {\n  position: absolute;\n  left: 12px;\n  right: 12px;\n  bottom: 0;\n  background: var(--foreground);\n  color: var(--background);\n  border-radius: var(--radius);\n  padding: 12px;\n  gap: 4px;\n  z-index: 40;\n}\n.toast-title { font-weight: bold; font-size: 14px; }\n.toast-description { font-size: 12px; color: var(--muted-foreground); }\n\n\n\n/* ---- Progress / Avatar ----------------------------------------------------------- */\n\n.progress {\n  height: 12px;\n  border-radius: 999px;\n  background: var(--secondary);\n  border: 1px solid var(--border);\n  color: var(--primary);\n}\n/* Avatar: plain image element. The runtime draws images rectangular \u2014 no\n   rounded clipping \u2014 so no border/radius here (a border would just draw\n   over the image). Wrap in a sized view if you want a frame. */\n";
+export declare const SHADCN_KIT_CSS = "/* ---------------------------------------------------------------------------\n * shadcn-style component kit \u2014 BUILT IN and always included.\n *\n * These tokens + class recipes are prepended to every build and preview\n * automatically, BEFORE your stylesheets, so anything you write overrides\n * them by normal cascade order. No scaffolding, no imports needed: put the\n * classes on native elements and they work.\n *\n * THEMES: a theme is any CSS file. Pre-packaged ones ship with @typecad/ui \u2014\n * import by bare specifier from a <style> block (or the sidecar .ui.css):\n *\n *   @import \"@typecad/ui/themes/blue.css\";   (zinc slate stone gray neutral\n *                                             blue green red)\n *\n * Your own: save a ui.shadcn.com / tweakcn export into the project and\n * @import it by path \u2014 its :root/.dark token blocks override the kit\n * defaults (later definitions win). Both dialects parse \u2014 classic HSL channel triplets and\n * Tailwind-v4 oklch(); alpha in colors is ignored (no blending on bare\n * metal). Dark mode activates with themeClass: 'dark' in the config's\n * display block.\n *\n * Overriding recipes: redefine any class in your own stylesheet; your\n * definition wins.\n *\n * Components (classes over native elements):\n *   Button      <button class=\"btn btn-primary\">Save</button>\n *               variants: -secondary -outline -ghost -destructive\n *               sizes: .btn-sm .btn-lg   full width: .btn-block\n *   Badge       <text class=\"badge badge-secondary\">new</text>\n *               variants: -default(omit) -destructive -outline\n *   Card        <view class=\"card\">\n *                 <view class=\"card-header\">\n *                   <text class=\"card-title\">Title</text>\n *                   <text class=\"card-description\">Subtitle</text>\n *                 </view>\n *                 <view class=\"card-content\">...</view>\n *                 <view class=\"card-footer\">...buttons...</view>\n *               </view>\n *   Input       <input class=\"input\" placeholder=\"...\"/>\n *   Label       <label class=\"form-label\">Name</label>\n *   Row (kit)   <view class=\"row\"> ... </view>   (flex row + gap, for composing)\n *   Validation  .input-error (destructive border) + .field-error hint;\n *               runtime-driven: bind borderColor/visible to a signal\n *   Separator   <hr class=\"separator\"/> (horizontal) or\n *               <hr class=\"vseparator\"/> (vertical; stretches to the row height)\n *   Alert       <view class=\"alert alert-destructive\">\n *                 <text class=\"alert-title\">...</text>\n *                 <text class=\"alert-description\">...</text>\n *               </view>\n *   Skeleton    <view class=\"skeleton\"/>            (pulse while loading)\n *   Spinner     <view class=\"spinner\"><view class=\"spinner-dot\"/></view>\n *               (indeterminate loading: a dot orbiting a ring via pure\n *                transform keyframes \u2014 translate lerps smoothly, unlike\n *                rotate which only renders exact quarter turns)\n *   Dialog      <dialog id=\"d\"><view class=\"dialog-scrim\" on:click={...}/>\n *               <view class=\"dialog-card\"> ... <view class=\"dialog-footer\">\n *               </view></dialog>\n *               (centered modal: programmatic ui.dialog.open(id), scrim tap\n *                closes; same slot machinery as the drawer)\n *   Toast       <toast id=\"t\" side=\"bottom\" duration=\"2500\" class=\"toast\">\n *               ...</toast>  (ui.toast(id) shows it; auto-closes after the\n *               duration; stacks as authored siblings)\n *   Progress    <progress class=\"progress\" value=\"40\"/>\n *   Avatar      <img class=\"avatar\" src=\"face.bmp\"/>\n *   Switch      <check class=\"switch\"/>             (pill container; the\n *               16px indicator is runtime-drawn at the top-left \u2014 best-effort)\n *   Tabs        <view class=\"tabs-list\"><button class=\"tabs-trigger\">..</button>..\n *               <view class=\"tabs-content-area\"><view class=\"tabs-content\">..\n *               (panes toggle via ui.bind(x, 'visible', ...) on a signal)\n *   Accordion   <view class=\"accordion\"><view class=\"accordion-item\">..\n *               (content toggles via ui.bind visible; chevron via text bind)\n *   Table       <table> ... </table>                (UA styles apply; see the\n *               html-table-approximation build note)\n * ------------------------------------------------------------------------- */\n\n:root {\n  --background: #ffffff;\n  --foreground: #09090b;\n  --card: #ffffff;\n  --card-foreground: #09090b;\n  --primary: #18181b;\n  --primary-foreground: #fafafa;\n  --secondary: #f4f4f5;\n  --secondary-foreground: #18181b;\n  --muted: #f4f4f5;\n  --muted-foreground: #71717a;\n  --accent: #f4f4f5;\n  --accent-foreground: #18181b;\n  --destructive: #dc2626;\n  --destructive-foreground: #fafafa;\n  --destructive-background: #fee2e2;\n  --border: #e4e4e7;\n  --input: #e4e4e7;\n  --radius: 8px;\n  --shadow-sm: 0 1px 3px rgb(0 0 0 / 0.1);\n  /* Solid scrim for dialogs \u2014 alpha blending needs a canvas underneath, so\n     the kit uses an opaque near-black that reads as a dimmed backdrop. */\n  --scrim: #101014;\n}\n\n.dark {\n  --background: #09090b;\n  --foreground: #fafafa;\n  --card: #18181b;\n  --card-foreground: #fafafa;\n  --primary: #fafafa;\n  --primary-foreground: #18181b;\n  --secondary: #27272a;\n  --secondary-foreground: #fafafa;\n  --muted: #27272a;\n  --muted-foreground: #a1a1aa;\n  --accent: #27272a;\n  --accent-foreground: #fafafa;\n  --destructive: #ef4444;\n  --destructive-foreground: #09090b;\n  --destructive-background: #451a1a;\n  --border: #27272a;\n  --input: #3f3f46;\n  --radius: 8px;\n}\n\n/* ---- Button ---------------------------------------------------------------- */\n\n.btn {\n  border-radius: var(--radius);\n  padding: 10px 16px;\n  font-weight: bold;\n  transition: background 80ms;\n  /* Reset the UA's browser-default button border (shadcn's button reset):\n     ghost must be truly borderless \u2014 variants that want one (outline)\n     re-declare it themselves. */\n  border: none;\n}\n.btn:pressed { transform: translateY(1px); }\n.btn-primary { background: var(--primary); color: var(--primary-foreground); }\n.btn-secondary { background: var(--secondary); color: var(--secondary-foreground); }\n.btn-outline { background: var(--background); color: var(--foreground); border: 1px solid var(--border); }\n.btn-ghost { color: var(--foreground); }\n.btn-destructive { background: var(--destructive); color: var(--destructive-foreground); }\n.btn-sm { padding: 6px 10px; min-height: 32px; font-size: 12px; }\n.btn-lg { padding: 14px 22px; min-height: 52px; font-size: 18px; }\n.btn-block { align-self: stretch; }\n\n/* ---- Badge ------------------------------------------------------------------ */\n\n.badge {\n  background: var(--primary);\n  color: var(--primary-foreground);\n  padding: 2px 8px;\n  border-radius: 999px;\n  font-size: 12px;\n  text-align: center;\n}\n.badge-secondary { background: var(--secondary); color: var(--secondary-foreground); }\n.badge-destructive { background: var(--destructive); color: var(--destructive-foreground); }\n.badge-outline { background: var(--background); color: var(--foreground); border: 1px solid var(--border); }\n\n/* ---- Layout utility -------------------------------------------------------------\n   Not a shadcn component \u2014 a kit convenience for composing recipes. */\n\n.row { flex-direction: row; align-items: center; gap: 8px; }\n\n/* ---- Card ------------------------------------------------------------------- */\n\n.card {\n  background: var(--card);\n  color: var(--card-foreground);\n  border: 1px solid var(--border);\n  border-radius: var(--radius);\n  box-shadow: var(--shadow-sm);\n  padding: 16px;\n  gap: 8px;\n  align-self: stretch;\n}\n.card-header { gap: 4px; }\n.card-title { font-size: 18px; font-weight: bold; }\n.card-description { font-size: 14px; color: var(--muted-foreground); }\n.card-content { gap: 8px; }\n.card-footer { flex-direction: row; gap: 8px; }\n\n/* ---- Tabs ---------------------------------------------------------------- */\n\n/* Segmented trigger row (shadcn TabsList). Active-trigger styling is driven\n   at runtime by ui.bind background/color bindings in author code \u2014 runtime\n   color swaps are literal hex (compile-time tokens), so pin them to the\n   active theme the way native_demo accents do. */\n.tabs-list {\n  flex-direction: row;\n  gap: 4px;\n  align-self: stretch;\n  background: var(--muted);\n  border-radius: var(--radius);\n  padding: 4px;\n}\n.tabs-trigger {\n  flex-grow: 1;\n  border-radius: calc(var(--radius) - 2px);\n  padding: 6px 10px;\n  min-height: 32px;\n  font-size: 13px;\n  text-align: center;\n}\n/* Fixed-height content region: panes are absolutely stacked inside it and\n   toggled via ui.bind(x, 'visible', ...) \u2014 layout keeps every pane's box,\n   so switching never re-flows. */\n.tabs-content-area {\n  position: relative;\n  align-self: stretch;\n  height: 150px;\n}\n.tabs-content {\n  position: absolute;\n  left: 0;\n  top: 0;\n  right: 0;\n  bottom: 0;\n  gap: 8px;\n}\n\n/* ---- Accordion (single-open) --------------------------------------------- */\n\n/* Stacked collapsible sections. The trigger is a button + chevron row; the\n   content pane toggles via ui.bind(x, 'visible', () => signal === i) \u2014 the\n   same signal pattern as Tabs. The chevron swaps v/^ via a text binding. */\n.accordion {\n  gap: 8px;\n  align-self: stretch;\n}\n.accordion-item {\n  background: var(--card);\n  border: 1px solid var(--border);\n  border-radius: var(--radius);\n}\n.accordion-trigger-row {\n  flex-direction: row;\n  align-items: center;\n  gap: 8px;\n  padding: 10px 12px;\n}\n.accordion-trigger {\n  flex-grow: 1;\n  text-align: left;\n  font-weight: bold;\n  padding: 0;\n  min-height: 20px;\n  /* The UA sheet gives every button a 1px border (border: 1px solid, colored\n     by the foreground token). A trigger is a plain text row on the card \u2014\n     cancel it or each one renders with a bright outline. */\n  border: none;\n}\n.accordion-chevron {\n  color: var(--muted-foreground);\n  font-size: 14px;\n  /* Wide enough for the '^' glyph (advance 12px at 14px size) \u2014 a single\n     char wider than the box wraps to nothing. */\n  width: 16px;\n  text-align: center;\n}\n.accordion-content {\n  padding: 0 12px 10px 12px;\n  gap: 8px;\n}\n\n/* ---- Form controls ----------------------------------------------------------- */\n\n.input {\n  background: var(--background);\n  color: var(--foreground);\n  border: 1px solid var(--input);\n  border-radius: var(--radius);\n}\n.form-label { color: var(--foreground); font-size: 14px; }\n\n/* Switch: pill container. The runtime draws a 16px circular knob that\n   slides with state \u2014 hollow at the left when off, solid at the right when\n   on (a static jump, no travel animation). min-height overrides the UA\n   touch target so the pill stays 26px tall. */\n.switch {\n  width: 44px;\n  height: 26px;\n  /* Override the UA's touch-target min-height (42px on small panels) \u2014 the\n     pill must stay 26px tall to read as a switch, not a checkbox. */\n  min-height: 26px;\n  border-radius: 999px;\n  border: 1px solid var(--border);\n  /* --card, not --muted: on a bare (near-black) page background a --muted\n     track reads as a stray gray box; --card keeps the pill affordance while\n     staying quiet. Swap back to var(--muted) inside lighter containers. */\n  background: var(--card);\n}\n\n/* ---- Checked-state pairs (shadcn data-[state=checked]) ------------------------\n   The ON control carries the primary pair: the switch's TRACK turns primary\n   with a primary-foreground knob, the checkbox face and the radio's selected\n   ring do the same. The select's pair themes the OPTION LIST's selected row\n   with the accent pair (shadcn's SelectItem selected state). These bake at\n   build time from :checked rules (a separate style bucket, like :pressed);\n   the device runtime swaps the pair onto the indicator when the value flips,\n   and the preview draws through the same fields. */\n.switch:checked {\n  background: var(--primary);\n  border-color: var(--primary);\n  color: var(--primary-foreground);\n}\ncheck:checked {\n  background: var(--primary);\n  color: var(--primary-foreground);\n}\nradio:checked {\n  background: var(--primary);\n  color: var(--primary-foreground);\n}\n.select:checked {\n  background: var(--accent);\n  color: var(--accent-foreground);\n}\n\n/* ---- Form validation states -------------------------------------------------- */\n\n/* Static hook: always-invalid styling for hardcoded markup. Runtime-driven\n   validation (recommended) binds the input's borderColor + a .field-error\n   hint's visible/text to a signal \u2014 see the demo's Forms screen. */\n.input-error {\n  border-color: var(--destructive);\n}\n.field-error {\n  color: var(--destructive);\n  font-size: 12px;\n}\n.field-success {\n  color: var(--muted-foreground);\n  font-size: 12px;\n}\n\n/* ---- Separator ---------------------------------------------------------------- */\n\n.separator {\n  height: 1px;\n  background: var(--border);\n  margin: 8px 0;\n}\n/* Vertical: 1px wide, stretches to the row's cross height (shadcn's\n   <Separator orientation=\"vertical\" /> \u2014 flex column + align-self: stretch). */\n.vseparator {\n  width: 1px;\n  height: 100%;\n  align-self: stretch;\n  background: var(--border);\n  margin: 0 8px;\n}\n\n/* ---- Alert -------------------------------------------------------------------- */\n\n.alert {\n  background: var(--background);\n  color: var(--foreground);\n  border: 1px solid var(--border);\n  border-radius: var(--radius);\n  padding: 12px;\n  gap: 4px;\n  align-self: stretch;\n}\n.alert-destructive {\n  background: var(--destructive-background);\n  border: 1px solid var(--destructive);\n  color: var(--destructive);\n}\n.alert-title { font-weight: bold; }\n.alert-description { font-size: 14px; color: var(--muted-foreground); }\n\n/* ---- Skeleton (loading placeholder) --------------------------------------------- */\n\n/* Opacity pulse. If the target display's keyframe support skips opacity,\n   the block still renders as a static muted placeholder. */\n.skeleton {\n  background: var(--muted);\n  border-radius: var(--radius);\n  height: 16px;\n  align-self: stretch;\n  animation: ui-skeleton-pulse 1.2s ease-in-out infinite;\n}\n@keyframes ui-skeleton-pulse {\n  0% { opacity: 1; }\n  50% { opacity: 0.55; }\n  100% { opacity: 1; }\n}\n\n/* ---- Spinner ---------------------------------------------------------------- */\n\n/* Indeterminate loading indicator: a dot orbiting inside a ring, pure\n   transform keyframes. translate() lerps CONTINUOUSLY between stops (unlike\n   rotate(), which only renders exact quarter turns), so the orbit is smooth.\n   The dot is absolute + out of flow; the ring is a fixed square so border\n   clipping stays symmetric. Sizes: change .spinner's width/height and keep\n   the dot inset consistent (orbit travel = inner - dot). */\n.spinner {\n  position: relative;\n  width: 22px;\n  height: 22px;\n  border: 2px solid var(--muted);\n  border-radius: 999px;\n}\n.spinner-dot {\n  position: absolute;\n  /* The dot's BASE position is the orbit's TOP-LEFT corner, not the ring\n     center: the keyframes translate 0..8px from here, and the path only\n     centers when base + travel/2 == ring center (with the 2px border,\n     top/left 2px + border lands the 6px dot at 4,4; its center travels\n     7..15 around the 22px ring's center at 11,11). */\n  top: 2px;\n  left: 2px;\n  width: 6px;\n  height: 6px;\n  background: var(--primary);\n  border-radius: 999px;\n  animation: ui-spinner-orbit 1000ms linear infinite;\n}\n@keyframes ui-spinner-orbit {\n  0%   { transform: translate(0px, 0px); }\n  25%  { transform: translate(8px, 0px); }\n  50%  { transform: translate(8px, 8px); }\n  75%  { transform: translate(0px, 8px); }\n  100% { transform: translate(0px, 0px); }\n}\n/* ---- Dialog ---------------------------------------------------------------- */\n\n/* Centered modal: <dialog> is a centered drawer (side-free) \u2014 programmatic\n   open/close via ui.dialog.open(id)/close(id?), hidden while closed by the\n   runtime (visibility gate for centered panels; offsets can't hide them).\n   The scrim is part of the markup: an absolute full-area view whose tap\n   closes the dialog; the card sits above it. z-index keeps both over page\n   content. */\n.dialog-scrim {\n  position: absolute;\n  left: 0;\n  right: 0;\n  top: 0;\n  bottom: 0;\n  background: var(--scrim);\n  z-index: 30;\n}\n.dialog-card {\n  position: absolute;\n  left: 24px;\n  right: 24px;\n  top: 64px;\n  background: var(--card);\n  color: var(--card-foreground);\n  border: 1px solid var(--border);\n  border-radius: var(--radius);\n  box-shadow: var(--shadow-lg);\n  padding: 16px;\n  gap: 8px;\n  z-index: 31;\n}\n.dialog-footer {\n  flex-direction: row;\n  justify-content: flex-end;\n  gap: 8px;\n}\n\n/* ---- Toast ----------------------------------------------------------------- */\n\n/* Transient notification: <toast side=\"bottom\" duration=\"2500\"> slides from\n   the bottom edge (author-positioned, flush to the edge so the slide fully\n   hides it) and auto-closes after duration ms. Show with ui.toast(id).\n   Sibling toasts stack by author layout; each closes on its own timer. */\n.toast {\n  position: absolute;\n  left: 12px;\n  right: 12px;\n  bottom: 0;\n  background: var(--foreground);\n  color: var(--background);\n  border-radius: var(--radius);\n  padding: 12px;\n  gap: 4px;\n  z-index: 40;\n}\n.toast-title { font-weight: bold; font-size: 14px; }\n.toast-description { font-size: 12px; color: var(--muted-foreground); }\n\n\n\n/* ---- Progress / Avatar ----------------------------------------------------------- */\n\n.progress {\n  height: 12px;\n  border-radius: 999px;\n  background: var(--secondary);\n  border: 1px solid var(--border);\n  color: var(--primary);\n}\n/* Avatar: plain image element. The runtime draws images rectangular \u2014 no\n   rounded clipping \u2014 so no border/radius here (a border would just draw\n   over the image). Wrap in a sized view if you want a frame. */\n";

package/dist/ui-engine/shadcn-kit.js

@@ -135,6 +135,10 @@ export const SHADCN_KIT_CSS = `/* ----------------------------------------------
   padding: 10px 16px;
   font-weight: bold;
   transition: background 80ms;
+  /* Reset the UA's browser-default button border (shadcn's button reset):
+     ghost must be truly borderless — variants that want one (outline)
+     re-declare it themselves. */
+  border: none;
 }
 .btn:pressed { transform: translateY(1px); }
 .btn-primary { background: var(--primary); color: var(--primary-foreground); }

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,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.13",
+  "version": "1.0.0-alpha.14",
   "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.14",
+    "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",