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

package/README.md

@@ -13,6 +13,26 @@ npm install --save-dev @typecad/cuttlefish
 
 `@typecad/ui` is compile-time only — none of its code is shipped to the device. The transpiler intercepts `ui.mount` / `ui.signal` / `ui.bind` / ... calls and lowers them to device variables and binding-table entries, so the package can be safely kept in `dependencies`.
 
+### Integration wizard
+
+Integrating a display is the one step with real hardware decisions — which panel, which bus, which pins, whether there's touch and how it connects. Run the wizard from your project directory:
+
+```bash
+npx @typecad/ui --config
+```
+
+It asks:
+
+1. **Display** — a built-in profile (ILI9341 320×240 SPI TFT, ST7796S 320×480 SPI TFT, SSD1309 128×64 I2C OLED), the desktop SDL simulator, or a fully custom driver.
+2. **Bus wiring** — SPI pins (CS/DC/RST/backlight, frequency in MHz, optional SCK/MOSI/MISO override) or the I2C address. Defaults match the framework profiles and the repo's demo wiring (ESP32 VSPI), and any existing `display` section in your config pre-fills the answers.
+3. **Orientation & rendering** — rotation and antialiasing, with advanced color-order/inversion options behind a confirm.
+4. **Touch** — none, resistive (XPT2046, STMPE610, 4-wire analog), capacitive (FT6336U, GT911, CST816S), or a custom adapter file — each with its pins, address, and a sensible default calibration.
+5. **Theme** — optional `themeCss` / `themeClass`.
+
+After a summary preview and confirmation, the wizard splices only the `display` section into `cuttlefish.config.ts` — every other section (and its comments) is preserved byte-for-byte, unmanaged display keys like `scroll` are carried over, and the result is syntax-checked before anything is written. If your config's `entry` points at a `.ui` file that doesn't exist yet, it offers to generate a starter screen, and it prints the exact `arduino-cli lib install ...`, preview, compile, and flash commands as next steps.
+
+If there is no `cuttlefish.config.ts` yet, create the project first with `npx @typecad/cuttlefish init`, then re-run the wizard.
+
 ## Project layout
 
 A TypeCAD UI project has one **entry** — the file you point `cuttlefish.config.ts` at. The entry can be either a `.ui` single-file component or a plain `.ts` module. Both intermix freely with regular cuttlefish TypeScript (HAL pin reads, `setInterval`, `console.log`, your own `.ts` modules) — the `<script>` block of a `.ui` file and a standalone `.ts` file are lowered by the same pipeline.
@@ -217,7 +237,7 @@ The fastest path is a single `.ui` file with markup, styling, and behavior toget
 </screen>
 ```
 
-Display hardware and wiring live in `cuttlefish.config.ts` under `display`, so the UI source stays focused on UI behavior.
+Display hardware and wiring live in `cuttlefish.config.ts` under `display`, so the UI source stays focused on UI behavior. Run `npx @typecad/ui --config` to generate that section interactively (see [Integration wizard](#integration-wizard)) — the result looks like the `display` line below.
 
 ### 2. Point the entry at the `.ui` file
 

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,74 @@
+#!/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() {
+    console.log(USAGE);
+}
+async function main(argv) {
+    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"));
+            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/dist/ui-engine/model.js

@@ -449,7 +449,7 @@ function parseBoxShadow(style, format) {
         // Split into a numbers zone (offset/blur) and a color zone. The color
         // zone starts at the first # hex, rgb(, rgba(, or color name. css-tree
         // may strip spaces between values, so we can't rely on whitespace split.
-        const colorStart = part.search(/#|rgba?\(|\b(?:black|white|red|green|blue|gray|grey|yellow|orange|purple|pink|cyan|magenta|silver|gold|brown|tan|navy|teal|maroon|lime|olive|aqua|fuchsia|transparent)\b/i);
+        const colorStart = part.search(/#|rgba?\(|hsla?\(|\b(?:black|white|red|green|blue|gray|grey|yellow|orange|purple|pink|cyan|magenta|silver|gold|brown|tan|navy|teal|maroon|lime|olive|aqua|fuchsia|transparent)\b/i);
         const numZone = colorStart >= 0 ? part.slice(0, colorStart) : part;
         const colorZone = colorStart >= 0 ? part.slice(colorStart) : "";
         // Extract numbers from the numeric zone only (safe — no hex digits here).

package/dist/ui-engine/runtime-header/canvas-helpers.js

@@ -29,9 +29,9 @@ static inline CuttlefishCanvas16* ui_create_canvas_best(int16_t w, int16_t h) {
       if (!psram_logged) {
         psram_logged = 1;
 #if defined(ESP32) && defined(ARDUINO)
-        Serial.printf("[psram] canvas %dx%d allocated in PSRAM (free=%u)\n", w, h, ESP.getFreePsram());
+        Serial.printf("[psram] canvas %dx%d allocated in PSRAM (free=%u)\\n", w, h, ESP.getFreePsram());
 #else
-        printf("[psram] canvas %dx%d allocated in PSRAM\n", w, h);
+        printf("[psram] canvas %dx%d allocated in PSRAM\\n", w, h);
 #endif
       }
       return c;

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

@@ -47,7 +47,16 @@ struct UINodeDrawCtx {
 // Returns 1 when the node fully handled its own canvas push, decoration,
 // coordinate restore, and dirty-clear (NODE_LIST). Returns 0 otherwise, in
 // which case the caller is responsible for the post-switch epilogue.
-static inline uint8_t ui_draw_node_body(int16_t i, const UINodeDrawCtx* ctx) {
+//
+// The ctx parameter is typed const void* (cast back to UINodeDrawCtx* below):
+// the Arduino .ino preprocessor auto-inserts a forward declaration of every
+// function near the top of the sketch, BEFORE this struct is defined, so a
+// struct-typed parameter makes that generated prototype fail to compile
+// ("'UINodeDrawCtx' does not name a type"). Primitive-only parameters keep
+// the auto-generated prototype valid; call sites still pass &ctx, which
+// converts implicitly to const void*.
+static inline uint8_t ui_draw_node_body(int16_t i, const void* rawCtx) {
+  const UINodeDrawCtx* ctx = static_cast<const UINodeDrawCtx*>(rawCtx);
   int16_t drawY = ctx->drawY;
   UI_COLOR_T bColor = ctx->bColor;
   UI_COLOR_T fillBg = ctx->fillBg;

package/dist/ui-engine/runtime-header/touch-keyboard-fwd.js

@@ -3,6 +3,7 @@
 // See docs/superpowers/specs/2026-07-12-split-runtime-header-design.md.
 export function emitTouchKeyboardFwd() {
     return `
+#include <cstdlib>  // abs() for drag-distance thresholds (self-sufficient slice)
 // ── Touch hit-testing + click dispatch ─────────────────────────────────────
 // Radio groups for mutual exclusion
 struct UIRadioGroup {

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

@@ -0,0 +1,49 @@
+/** Walk up from `startDir` looking for cuttlefish.config.ts. */
+export declare function findCuttlefishConfig(startDir: string): string | undefined;
+/** A plain record as extracted from a config object literal. */
+export type ConfigRecord = Record<string, unknown>;
+/**
+ * Read a top-level section of the config (e.g. `display`) as a plain record.
+ * Returns undefined when the section is missing or not an object literal.
+ */
+export declare function readConfigSection(sourceText: string, section: string): ConfigRecord | undefined;
+/** Read the top-level `entry` scalar (the .ui/.ts entry path). */
+export declare function readEntryPath(sourceText: string): string | undefined;
+export interface RenderDisplayOptions {
+    /** Indentation of the property lines inside the braces (default 2 spaces). */
+    indent?: string;
+    /** Indentation of the closing brace (default: none). */
+    closingIndent?: string;
+    /** Line ending used in the rendered block (default "\n"). */
+    eol?: string;
+    /** Optional `// comment` lines rendered above the matching key. */
+    comments?: Record<string, string>;
+}
+/**
+ * Render the display section as an object-literal body (braces included).
+ * Key order follows insertion order of the record, matching the demos
+ * (profile/wiring first, touch last). Nested objects render inline.
+ */
+export declare function renderDisplayBody(display: ConfigRecord, options?: RenderDisplayOptions): string;
+/** Render the complete `display: { ... }` property text for a property that
+ *  starts at `options.indent`. The returned text's first line is NOT indented
+ *  — the caller positions the property start; body lines and the closing
+ *  brace are indented relative to `options.indent`. */
+export declare function renderDisplayProperty(display: ConfigRecord, options?: RenderDisplayOptions): string;
+export interface UpsertDisplayResult {
+    text: string;
+    /** "replaced" — an existing display section was rewritten; "inserted" — none existed. */
+    mode: "replaced" | "inserted";
+}
+/**
+ * Insert or replace the `display` section in a cuttlefish.config.ts source
+ * string, preserving every other section and comment. Throws when the config
+ * has no recognizable default-export object literal.
+ */
+export declare function upsertDisplaySection(sourceText: string, display: ConfigRecord, options?: RenderDisplayOptions): UpsertDisplayResult;
+/**
+ * Syntactic sanity check for wizard output: returns the first error message
+ * when the text no longer parses as TypeScript, or null when it is clean.
+ * (Semantic checking is the build's job — this only guards the splice.)
+ */
+export declare function findSyntaxError(text: string): string | null;

package/dist/wizard/config-writer.js

@@ -0,0 +1,366 @@
+// ---------------------------------------------------------------------------
+// cuttlefish.config.ts reader/writer for the @typecad/ui integration wizard.
+//
+// The build's config loader (packages/cuttlefish/src/config-loader.ts) is
+// AST-based and deliberately never evaluates user code — only inline literals
+// survive extraction. The writer here plays by the same rules: the wizard
+// emits plain object literals and splices them into the config's default
+// export object via the TypeScript AST, so every other section (and its
+// comments) survives an update byte-for-byte.
+// ---------------------------------------------------------------------------
+import fs from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+const CONFIG_FILENAME = "cuttlefish.config.ts";
+/** Walk up from `startDir` looking for cuttlefish.config.ts. */
+export function findCuttlefishConfig(startDir) {
+    let dir = path.resolve(startDir);
+    for (;;) {
+        const candidate = path.join(dir, CONFIG_FILENAME);
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+            return candidate;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+// ---------------------------------------------------------------------------
+// AST helpers (kept aligned with the config loader's extraction rules)
+// ---------------------------------------------------------------------------
+function unwrapTypeCast(node) {
+    let curr = node;
+    for (;;) {
+        if (ts.isAsExpression(curr) || ts.isTypeAssertionExpression(curr) || ts.isParenthesizedExpression(curr)) {
+            curr = curr.expression;
+            continue;
+        }
+        const isSatisfies = ts.isSatisfiesExpression;
+        if (typeof isSatisfies === "function" && isSatisfies(curr)) {
+            curr = curr.expression;
+            continue;
+        }
+        return curr;
+    }
+}
+function propertyKeyName(prop) {
+    const name = prop.name;
+    if (!name)
+        return undefined;
+    return ts.isIdentifier(name) || ts.isStringLiteral(name) ? name.text : undefined;
+}
+function getScalarValue(node) {
+    const unwrapped = unwrapTypeCast(node);
+    if (ts.isStringLiteral(unwrapped) || ts.isNoSubstitutionTemplateLiteral(unwrapped)) {
+        return unwrapped.text;
+    }
+    if (ts.isNumericLiteral(unwrapped)) {
+        return Number(unwrapped.text);
+    }
+    if (ts.isPrefixUnaryExpression(unwrapped)
+        && (unwrapped.operator === ts.SyntaxKind.MinusToken || unwrapped.operator === ts.SyntaxKind.PlusToken)
+        && ts.isNumericLiteral(unwrapped.operand)) {
+        const magnitude = Number(unwrapped.operand.text);
+        return unwrapped.operator === ts.SyntaxKind.MinusToken ? -magnitude : magnitude;
+    }
+    if (unwrapped.kind === ts.SyntaxKind.TrueKeyword)
+        return true;
+    if (unwrapped.kind === ts.SyntaxKind.FalseKeyword)
+        return false;
+    return undefined;
+}
+function getStringLiteral(node) {
+    const unwrapped = unwrapTypeCast(node);
+    if (ts.isStringLiteral(unwrapped) || ts.isNoSubstitutionTemplateLiteral(unwrapped)) {
+        return unwrapped.text;
+    }
+    return undefined;
+}
+/**
+ * Find the config's default-export object literal. Accepts the same shapes as
+ * the build's loader:
+ *   1. `export default { ... }`
+ *   2. `const config: CuttlefishConfig = { ... }; export default config;`
+ * with `as` / `satisfies` / parenthesized wrappers unwrapped.
+ */
+function findConfigObjectLiteral(sourceFile) {
+    const variableDecls = new Map();
+    let defaultExportName;
+    let inlineDefaultObject;
+    for (const stmt of sourceFile.statements) {
+        if (ts.isVariableStatement(stmt)) {
+            for (const decl of stmt.declarationList.declarations) {
+                if (ts.isIdentifier(decl.name)) {
+                    variableDecls.set(decl.name.text, decl);
+                }
+            }
+        }
+        if (ts.isExportAssignment(stmt) && !stmt.isExportEquals) {
+            const expr = unwrapTypeCast(stmt.expression);
+            if (ts.isIdentifier(expr)) {
+                defaultExportName = expr.text;
+            }
+            else if (ts.isObjectLiteralExpression(expr)) {
+                inlineDefaultObject = expr;
+            }
+        }
+    }
+    if (inlineDefaultObject)
+        return inlineDefaultObject;
+    if (defaultExportName) {
+        const decl = variableDecls.get(defaultExportName);
+        if (decl?.initializer) {
+            const init = unwrapTypeCast(decl.initializer);
+            if (ts.isObjectLiteralExpression(init))
+                return init;
+        }
+    }
+    return undefined;
+}
+function parseSource(sourceText) {
+    return ts.createSourceFile(CONFIG_FILENAME, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+}
+function objectLiteralToRecord(obj) {
+    const result = {};
+    for (const prop of obj.properties) {
+        if (!ts.isPropertyAssignment(prop))
+            continue;
+        const key = propertyKeyName(prop);
+        if (!key)
+            continue;
+        const init = unwrapTypeCast(prop.initializer);
+        if (ts.isObjectLiteralExpression(init)) {
+            result[key] = objectLiteralToRecord(init);
+        }
+        else if (ts.isArrayLiteralExpression(init)) {
+            const items = [];
+            for (const elem of init.elements) {
+                const s = getStringLiteral(elem);
+                if (s === undefined)
+                    break;
+                items.push(s);
+            }
+            if (items.length === init.elements.length && items.length > 0)
+                result[key] = items;
+        }
+        else {
+            const scalar = getScalarValue(init);
+            if (scalar !== undefined)
+                result[key] = scalar;
+        }
+    }
+    return result;
+}
+/**
+ * Read a top-level section of the config (e.g. `display`) as a plain record.
+ * Returns undefined when the section is missing or not an object literal.
+ */
+export function readConfigSection(sourceText, section) {
+    const obj = findConfigObjectLiteral(parseSource(sourceText));
+    if (!obj)
+        return undefined;
+    for (const prop of obj.properties) {
+        if (!ts.isPropertyAssignment(prop))
+            continue;
+        if (propertyKeyName(prop) !== section)
+            continue;
+        const init = unwrapTypeCast(prop.initializer);
+        if (!ts.isObjectLiteralExpression(init))
+            return undefined;
+        return objectLiteralToRecord(init);
+    }
+    return undefined;
+}
+/** Read the top-level `entry` scalar (the .ui/.ts entry path). */
+export function readEntryPath(sourceText) {
+    const obj = findConfigObjectLiteral(parseSource(sourceText));
+    if (!obj)
+        return undefined;
+    for (const prop of obj.properties) {
+        if (!ts.isPropertyAssignment(prop))
+            continue;
+        if (propertyKeyName(prop) !== "entry")
+            continue;
+        const value = getStringLiteral(unwrapTypeCast(prop.initializer));
+        return value;
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Rendering — build the `display` object-literal text
+// ---------------------------------------------------------------------------
+/** Keys whose numeric values read best in hex (I2C addresses). */
+const HEX_KEYS = new Set(["address", "i2cAddress"]);
+function escapeString(value) {
+    return value.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+}
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function renderValue(key, value) {
+    if (typeof value === "number") {
+        if (HEX_KEYS.has(key) && Number.isInteger(value) && value >= 0) {
+            return `0x${value.toString(16)}`;
+        }
+        return String(value);
+    }
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "string")
+        return `'${escapeString(value)}'`;
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => renderValue(key, item)).join(", ")}]`;
+    }
+    if (isPlainRecord(value)) {
+        const inner = Object.entries(value)
+            .map(([nestedKey, nestedValue]) => `${nestedKey}: ${renderValue(nestedKey, nestedValue)}`)
+            .join(", ");
+        return `{ ${inner} }`;
+    }
+    throw new Error(`Cannot render display config value for key "${key}" (${typeof value}).`);
+}
+/**
+ * Render the display section as an object-literal body (braces included).
+ * Key order follows insertion order of the record, matching the demos
+ * (profile/wiring first, touch last). Nested objects render inline.
+ */
+export function renderDisplayBody(display, options = {}) {
+    const indent = options.indent ?? "  ";
+    const closingIndent = options.closingIndent ?? "";
+    const eol = options.eol ?? "\n";
+    const lines = [];
+    for (const [key, value] of Object.entries(display)) {
+        const comment = options.comments?.[key];
+        if (comment) {
+            lines.push(`${indent}// ${comment}`);
+        }
+        lines.push(`${indent}${key}: ${renderValue(key, value)},`);
+    }
+    return `{${eol}${lines.join(eol)}${eol}${closingIndent}}`;
+}
+/** Render the complete `display: { ... }` property text for a property that
+ *  starts at `options.indent`. The returned text's first line is NOT indented
+ *  — the caller positions the property start; body lines and the closing
+ *  brace are indented relative to `options.indent`. */
+export function renderDisplayProperty(display, options = {}) {
+    const indent = options.indent ?? "";
+    return `display: ${renderDisplayBody(display, {
+        ...options,
+        indent: `${indent}  `,
+        closingIndent: indent,
+    })}`;
+}
+// ---------------------------------------------------------------------------
+// Splicing — insert or replace the display section inside the config
+// ---------------------------------------------------------------------------
+/** Leading whitespace of the line containing `pos` ("" when mid-line). */
+function lineIndentAt(text, pos) {
+    const lineStart = text.lastIndexOf("\n", pos - 1) + 1;
+    const before = text.slice(lineStart, pos);
+    return /^[ \t]*$/.test(before) ? before : "";
+}
+function detectLineEnding(text) {
+    return text.includes("\r\n") ? "\r\n" : "\n";
+}
+/** Skip whitespace and comments from `pos`; true when the next char is ','. */
+function spanStartsWithComma(text, pos, end) {
+    let i = pos;
+    while (i < end) {
+        const ch = text[i];
+        if (ch === " " || ch === "\t" || ch === "\r" || ch === "\n") {
+            i++;
+            continue;
+        }
+        if (ch === "/" && text[i + 1] === "/") {
+            const newline = text.indexOf("\n", i);
+            if (newline === -1 || newline >= end)
+                return false;
+            i = newline + 1;
+            continue;
+        }
+        if (ch === "/" && text[i + 1] === "*") {
+            const close = text.indexOf("*/", i);
+            if (close === -1 || close + 2 > end)
+                return false;
+            i = close + 2;
+            continue;
+        }
+        return ch === ",";
+    }
+    return false;
+}
+/**
+ * Insert or replace the `display` section in a cuttlefish.config.ts source
+ * string, preserving every other section and comment. Throws when the config
+ * has no recognizable default-export object literal.
+ */
+export function upsertDisplaySection(sourceText, display, options = {}) {
+    const sourceFile = parseSource(sourceText);
+    const obj = findConfigObjectLiteral(sourceFile);
+    if (!obj) {
+        throw new Error("cuttlefish.config.ts has no recognizable config object — expected `export default { ... }` or `const config = { ... }; export default config;`.");
+    }
+    const eol = options.eol ?? detectLineEnding(sourceText);
+    const existing = obj.properties.find((prop) => ts.isPropertyAssignment(prop) && propertyKeyName(prop) === "display");
+    if (existing) {
+        const indent = lineIndentAt(sourceText, existing.getStart());
+        const body = renderDisplayBody(display, { ...options, indent: `${indent}  `, closingIndent: indent, eol });
+        const init = unwrapTypeCast(existing.initializer);
+        if (ts.isObjectLiteralExpression(init)) {
+            // Replace just the initializer — `display:` name and its comments stay.
+            return {
+                text: sourceText.slice(0, init.getStart()) + body + sourceText.slice(init.getEnd()),
+                mode: "replaced",
+            };
+        }
+        // `display: someExpression` — replace the whole property.
+        return {
+            text: sourceText.slice(0, existing.getStart()) + `display: ${body}` + sourceText.slice(existing.getEnd()),
+            mode: "replaced",
+        };
+    }
+    // No display section — insert before the object literal's closing brace.
+    const closeBrace = obj.getEnd() - 1;
+    const lastProp = obj.properties[obj.properties.length - 1];
+    const indent = lastProp
+        ? lineIndentAt(sourceText, lastProp.getStart())
+        : lineIndentAt(sourceText, obj.getStart()) + "  ";
+    const body = renderDisplayBody(display, { ...options, indent: `${indent}  `, closingIndent: indent, eol });
+    const closingIndent = lineIndentAt(sourceText, closeBrace);
+    let prefix = sourceText;
+    if (lastProp && !spanStartsWithComma(sourceText, lastProp.getEnd(), closeBrace)) {
+        prefix = sourceText.slice(0, lastProp.getEnd()) + "," + sourceText.slice(lastProp.getEnd());
+    }
+    // Recompute the brace position if a comma was inserted before it.
+    const insertedComma = prefix !== sourceText;
+    const closeBraceFinal = closeBrace + (insertedComma ? 1 : 0);
+    return {
+        text: prefix.slice(0, closeBraceFinal)
+            // Trailing comma keeps the multi-property style of the demos.
+            + `${indent}display: ${body},${eol}${closingIndent}`
+            + prefix.slice(closeBraceFinal),
+        mode: "inserted",
+    };
+}
+/**
+ * Syntactic sanity check for wizard output: returns the first error message
+ * when the text no longer parses as TypeScript, or null when it is clean.
+ * (Semantic checking is the build's job — this only guards the splice.)
+ */
+export function findSyntaxError(text) {
+    const output = ts.transpileModule(text, {
+        reportDiagnostics: true,
+        compilerOptions: { target: ts.ScriptTarget.ESNext, module: ts.ModuleKind.ESNext },
+    });
+    const errors = (output.diagnostics ?? []).filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error);
+    if (errors.length === 0)
+        return null;
+    const first = errors[0];
+    const message = ts.flattenDiagnosticMessageText(first.messageText, "\n");
+    if (typeof first.start === "number") {
+        const line = text.slice(0, first.start).split("\n").length;
+        return `line ${line}: ${message}`;
+    }
+    return message;
+}

package/dist/wizard/display-catalog.d.ts

@@ -0,0 +1,75 @@
+export type WizardBus = "spi" | "i2c" | "none";
+export type WizardTouchKind = "none" | "spi" | "i2c" | "analog" | "adapter" | "sdl";
+export interface DisplayCatalogEntry {
+    /** Catalog id — also the `display.profile` value for built-ins. */
+    id: string;
+    label: string;
+    hint: string;
+    /** Built-in profile name written to config (omitted for custom/sdl). */
+    profile?: string;
+    /** Driver name written when no built-in profile applies. */
+    driver?: string;
+    bus: WizardBus;
+    /** Wizard question defaults. */
+    defaults: {
+        cs?: number;
+        dc?: number;
+        rst?: number;
+        /** Backlight GPIO; undefined = don't ask, null = ask but default blank. */
+        backlight?: number | null;
+        /** Backlight pin the built-in profile drives when `backlight` is omitted. */
+        backlightProfileDefault?: number;
+        spiFrequency?: number;
+        address?: number;
+        width?: number;
+        height?: number;
+        /** Native panel size before rotation (used for capacitive touch calibration). */
+        nativeWidth?: number;
+        nativeHeight?: number;
+        rotation?: number;
+        colorOrder?: "rgb" | "bgr";
+        invert?: boolean;
+        antialias?: boolean;
+    };
+    /** Arduino libraries the driver needs (for the printed next steps). */
+    arduinoLibraries?: string[];
+    /** A wiring note printed with the summary. */
+    wiringNote?: string;
+}
+export declare const DISPLAY_CATALOG: readonly DisplayCatalogEntry[];
+export interface TouchCatalogEntry {
+    /** `touch.library` value written to config (built-in libraries only). */
+    id: string;
+    label: string;
+    hint: string;
+    kind: WizardTouchKind;
+    defaults: {
+        cs?: number;
+        irq?: number;
+        i2cAddress?: number;
+        i2cFrequency?: number;
+        resetPin?: number;
+        /** Resistive raw-ADC calibration (capacitive uses panel pixel space). */
+        calibration?: {
+            xMin: number;
+            xMax: number;
+            yMin: number;
+            yMax: number;
+        };
+        analogPins?: {
+            xp: number;
+            yp: number;
+            xm: number;
+            ym: number;
+            rx: number;
+        };
+    };
+    arduinoLibrary?: string;
+}
+export declare const TOUCH_CATALOG: readonly TouchCatalogEntry[];
+/**
+ * Collect GPIO collisions between the display wiring and the touch wiring so
+ * the wizard can warn before writing the config (a shared pin is almost
+ * always a mis-entered default rather than real hardware).
+ */
+export declare function findPinConflicts(displayPins: Record<string, number | undefined>, touchPins: Record<string, number | undefined>): string[];