@typecad/cuttlefish 1.0.0-alpha.11 → 1.0.0-alpha.13

package/dist/cli.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import fs from "node:fs";
 import { parseCommandLine, printHelp } from "./utils/cli.js";
 import { scaffoldProject, printInitNextSteps, KNOWN_TARGETS, frameworksForTarget, frameworkCatalogEntry, FRAMEWORK_CATALOG, frameworkTargetProfile } from "./create/index.js";
+import { generateFrameworkDebugArtifacts } from "./create/debug-artifacts.js";
 import { runInitWizard } from "./create/index.js";
 import { installProjectDependencies } from "./create/install-deps.js";
 import { generateLibraryDefinitions, transpileFile } from "./transpile.js";
@@ -156,7 +157,20 @@ function finalizeCreate(result, options) {
             console.log(chalk.dim(`  Run '${chalk.white("npm install")}' manually in ${relativeDir} when ready.`));
         }
     }
-    printInitNextSteps(result.options, result.outDir, { installed });
+    // Framework starter debug profile (e.g. Zephyr esp32s3): write .vscode/
+    // launch.json + tasks.json so F5 in VS Code works before the first build.
+    // Runs after the install step so the framework package resolves from the
+    // new project's node_modules; best-effort — the first --debug build writes
+    // the artifacts anyway.
+    const debugArtifacts = generateFrameworkDebugArtifacts({
+        frameworkPackage: result.options.frameworkPackage || undefined,
+        workspaceRoot: result.outDir,
+        buildTarget: result.options.buildTarget,
+    });
+    if (debugArtifacts.length > 0) {
+        console.log(`\n${chalk.green("✓")} Debug profile: ${debugArtifacts.map((f) => chalk.white(f)).join(", ")}`);
+    }
+    printInitNextSteps(result.options, result.outDir, { installed, debugProfile: debugArtifacts.length > 0 });
 }
 async function handleBoardAdd(options) {
     const { scaffoldBoardPackages, parseBoardSpec, generateFrameworkChecklist } = await import("./create/index.js");
@@ -442,6 +456,12 @@ async function main() {
         let effectiveFrameworkPackage = options.frameworkPackage;
         let effectiveMcuPackage;
         let effectivePort = options.port;
+        // CUTTLEFISH_PORT env var sits between the CLI flag and the config file
+        // (flag > env > config), so cross-platform uploads don't need a
+        // Windows-specific COM port baked into package.json scripts.
+        if (!effectivePort && process.env.CUTTLEFISH_PORT) {
+            effectivePort = process.env.CUTTLEFISH_PORT;
+        }
         if (config) {
             if (config.mcu) {
                 effectiveMcuPackage = config.mcu;
@@ -564,7 +584,6 @@ async function main() {
                             buildTarget,
                             port: effectivePort,
                             baud: options.baud ?? config?.console?.baudRate,
-                            optimize: config?.outputOptimize,
                             extraFlags: config?.outputExtraFlags,
                             defines: psramDefines,
                             psram: config?.psram,
@@ -665,7 +684,6 @@ async function main() {
                                     buildTarget,
                                     port: effectivePort,
                                     baud: options.baud ?? config?.console?.baudRate,
-                                    optimize: config?.outputOptimize,
                                     extraFlags: config?.outputExtraFlags,
                                     defines: psramDefines,
                                     psram: config?.psram,
@@ -773,7 +791,6 @@ async function main() {
             buildTarget,
             port: effectivePort,
             baud: options.baud ?? config?.console?.baudRate,
-            optimize: config?.outputOptimize,
             extraFlags: config?.outputExtraFlags,
             defines: psramDefines,
             psram: config?.psram,

package/dist/config-loader.d.ts

@@ -15,8 +15,6 @@ export interface ResolvedCuttlefishConfig {
     buildTarget?: string;
     /** Output framework (e.g. 'arduino'). */
     outputFramework?: string;
-    /** Optimization level. */
-    outputOptimize?: string;
     /** Output directory. */
     outputOutDir?: string;
     /**
@@ -52,6 +50,14 @@ export interface ResolvedCuttlefishConfig {
  * Returns the absolute path on success, `undefined` if none is found.
  */
 export declare function findConfigFile(startDir: string): string | undefined;
+/**
+ * Warn about config values the AST-only parser cannot evaluate. The loader
+ * deliberately never runs user code (no ts-node / dynamic import), so only
+ * inline literals survive extraction; without these warnings a value like
+ * `libraries: sdlLibraries` (an identifier) used to vanish silently and
+ * surface later as an opaque link error.
+ */
+export type ConfigDropWarning = (message: string) => void;
 /**
  *
  * The file must have a default export whose initializer is an object literal.

package/dist/config-loader.js

@@ -12,6 +12,13 @@ import ts from "typescript";
 import { safeValidateConfig } from "./config-schema.js";
 /** The filename we search for when walking up directories. */
 const CONFIG_FILENAME = "cuttlefish.config.ts";
+/** Top-level keys recognized by CuttlefishConfigSchema — used to warn about
+ *  misspelled keys that the AST extraction would otherwise drop silently. */
+const KNOWN_TOP_LEVEL_KEYS = new Set([
+    "entry", "target", "mcu", "board", "contract", "framework", "psram",
+    "output", "frameworkData", "include", "exclude", "test", "toolchain",
+    "console", "native", "zephyr", "display",
+]);
 /**
  * Search upward from `startDir` for a file named `cuttlefish.config.ts`.
  * Returns the absolute path on success, `undefined` if none is found.
@@ -30,15 +37,21 @@ export function findConfigFile(startDir) {
     }
     return undefined;
 }
-// ---------------------------------------------------------------------------
-// AST helpers — extract scalar values from a TS object literal
-// ---------------------------------------------------------------------------
 function unwrapTypeCast(node) {
     let curr = node;
-    while (ts.isAsExpression(curr) || ts.isTypeAssertionExpression(curr)) {
-        curr = curr.expression;
+    for (;;) {
+        if (ts.isAsExpression(curr) || ts.isTypeAssertionExpression(curr) || ts.isParenthesizedExpression(curr)) {
+            curr = curr.expression;
+            continue;
+        }
+        // satisfies is TS ≥4.9 — guard for older typings, then cast for .expression.
+        const isSatisfies = ts.isSatisfiesExpression;
+        if (typeof isSatisfies === "function" && isSatisfies(curr)) {
+            curr = curr.expression;
+            continue;
+        }
+        return curr;
     }
-    return curr;
 }
 function getStringLiteral(node) {
     const unwrapped = unwrapTypeCast(node);
@@ -55,20 +68,51 @@ function getScalarValue(node) {
     if (ts.isNumericLiteral(unwrapped)) {
         return Number(unwrapped.text);
     }
+    // Negative (and explicitly positive) number literals parse as
+    // PrefixUnaryExpression — `reset: -1` used to be silently dropped.
+    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;
 }
+/** True for `null` / `undefined` literals — inline literals, but not values
+ *  the config shape supports; callers warn with an accurate message instead
+ *  of the "variables/ternaries" text. */
+function isNullishLiteral(node) {
+    const kind = unwrapTypeCast(node).kind;
+    return kind === ts.SyntaxKind.NullKeyword || kind === ts.SyntaxKind.UndefinedKeyword;
+}
 /**
  * Walk an object literal and collect all scalar (string / number / boolean)
  * property values into a flat dot-path map — exactly like board-resolver.ts.
  */
-function walkObjectLiteral(obj, prefix, out) {
+/** Property key text for Identifier/StringLiteral names, else undefined
+ *  (SpreadAssignment has no name; computed keys are not static text). */
+function propertyKeyName(prop) {
+    const name = prop.name;
+    if (!name)
+        return undefined;
+    return ts.isIdentifier(name) || ts.isStringLiteral(name) ? name.text : undefined;
+}
+function describePropertyKey(prop) {
+    return propertyKeyName(prop) ?? "<unnamed>";
+}
+function walkObjectLiteral(obj, prefix, out, warn) {
     for (const prop of obj.properties) {
-        if (!ts.isPropertyAssignment(prop))
+        if (!ts.isPropertyAssignment(prop)) {
+            if (warn) {
+                const label = prefix ? `${prefix}.${describePropertyKey(prop)}` : describePropertyKey(prop);
+                warn(`'${label}' uses ${ts.SyntaxKind[prop.kind]} syntax (shorthand/spread/method) — only property assignments are supported, ignored.`);
+            }
             continue;
+        }
         const key = ts.isIdentifier(prop.name)
             ? prop.name.text
             : ts.isStringLiteral(prop.name)
@@ -78,13 +122,26 @@ function walkObjectLiteral(obj, prefix, out) {
             continue;
         const fullKey = prefix ? `${prefix}.${key}` : key;
         if (ts.isObjectLiteralExpression(prop.initializer)) {
-            walkObjectLiteral(prop.initializer, fullKey, out);
+            walkObjectLiteral(prop.initializer, fullKey, out, warn);
+        }
+        else if (ts.isArrayLiteralExpression(prop.initializer)) {
+            // Arrays are extracted by the dedicated array extractors
+            // (output.extraFlags, zephyr.cmakeArgs, native.libraries, …), not the
+            // flat scalar walk — skip here without warning.
         }
         else {
             const value = getScalarValue(prop.initializer);
             if (value !== undefined) {
                 out.set(fullKey, value);
             }
+            else if (warn) {
+                // Message text must stay byte-identical to extractObjectAsRecord's —
+                // sections walked by both (native, display) rely on the warn-site
+                // dedup to print one warning per dropped value, not two.
+                warn(isNullishLiteral(prop.initializer)
+                    ? `'${fullKey}' is a null/undefined literal — not a supported config value, ignored.`
+                    : `'${fullKey}' is not an inline literal (variables, ternaries, and template substitutions are not evaluated) — ignored.`);
+            }
         }
     }
 }
@@ -124,20 +181,18 @@ function navigateToObjectProperty(obj, path) {
     }
     return undefined;
 }
-function extractStringArray(obj, path) {
+function extractStringArray(obj, path, warn) {
+    const label = path.join(".");
     const leaf = navigateToObjectProperty(obj, path);
-    if (!leaf || !ts.isArrayLiteralExpression(leaf))
+    if (!leaf || !ts.isArrayLiteralExpression(leaf)) {
+        if (leaf && warn)
+            warn(`'${label}' is not an inline array literal — ignored.`);
         return undefined;
-    const result = [];
-    for (const elem of leaf.elements) {
-        const s = getStringLiteral(elem);
-        if (s === undefined)
-            return undefined;
-        result.push(s);
     }
-    return result;
+    return extractStringArrayFromArrayLiteral(leaf, warn, label);
 }
-function extractStringRecord(obj, path) {
+function extractStringRecord(obj, path, warn) {
+    const label = path.join(".");
     const leaf = navigateToObjectProperty(obj, path);
     if (!leaf || !ts.isObjectLiteralExpression(leaf))
         return undefined;
@@ -153,8 +208,11 @@ function extractStringRecord(obj, path) {
         if (!key)
             continue;
         const value = getStringLiteral(prop.initializer);
-        if (value === undefined)
+        if (value === undefined) {
+            if (warn)
+                warn(`'${label}.${key}' is not a string literal — the whole record is ignored.`);
             return undefined;
+        }
         result[key] = value;
     }
     if (Object.keys(result).length === 0)
@@ -165,11 +223,18 @@ function extractStringRecord(obj, path) {
  * Recursively extract an object literal as Record<string, unknown>.
  * Handles strings, numbers, booleans, string arrays, and nested objects.
  */
-function extractObjectAsRecord(obj) {
+function extractObjectAsRecord(obj, warn, prefix = "") {
     const result = {};
     for (const prop of obj.properties) {
-        if (!ts.isPropertyAssignment(prop))
+        if (!ts.isPropertyAssignment(prop)) {
+            if (warn) {
+                // Byte-identical to walkObjectLiteral's message for the same property
+                // so the warn-site dedup collapses the double walk into one warning.
+                const label = prefix ? `${prefix}.${describePropertyKey(prop)}` : describePropertyKey(prop);
+                warn(`'${label}' uses ${ts.SyntaxKind[prop.kind]} syntax (shorthand/spread/method) — only property assignments are supported, ignored.`);
+            }
             continue;
+        }
         const key = ts.isIdentifier(prop.name)
             ? prop.name.text
             : ts.isStringLiteral(prop.name)
@@ -177,29 +242,40 @@ function extractObjectAsRecord(obj) {
                 : undefined;
         if (!key)
             continue;
+        const fullKey = prefix ? `${prefix}.${key}` : key;
         const init = prop.initializer;
         if (ts.isObjectLiteralExpression(init)) {
-            result[key] = extractObjectAsRecord(init);
+            result[key] = extractObjectAsRecord(init, warn, fullKey);
         }
         else if (ts.isArrayLiteralExpression(init)) {
-            const arr = extractStringArrayFromArrayLiteral(init);
+            const arr = extractStringArrayFromArrayLiteral(init, warn, fullKey);
             if (arr)
                 result[key] = arr;
         }
         else {
             const scalar = getScalarValue(init);
-            if (scalar !== undefined)
+            if (scalar !== undefined) {
                 result[key] = scalar;
+            }
+            else if (warn) {
+                // Keep byte-identical to walkObjectLiteral's message (see above).
+                warn(isNullishLiteral(init)
+                    ? `'${fullKey}' is a null/undefined literal — not a supported config value, ignored.`
+                    : `'${fullKey}' is not an inline literal (variables, ternaries, and template substitutions are not evaluated) — ignored.`);
+            }
         }
     }
     return result;
 }
-function extractStringArrayFromArrayLiteral(node) {
+function extractStringArrayFromArrayLiteral(node, warn, label = "array") {
     const result = [];
     for (const elem of node.elements) {
         const s = getStringLiteral(elem);
-        if (s === undefined)
+        if (s === undefined) {
+            if (warn)
+                warn(`'${label}' has a non-string-literal element — the whole array is ignored.`);
             return undefined;
+        }
         result.push(s);
     }
     return result;
@@ -207,7 +283,7 @@ function extractStringArrayFromArrayLiteral(node) {
 /**
  * Extract a top-level config section as a generic Record<string, unknown>.
  */
-function extractFrameworkSection(obj, sectionName) {
+function extractFrameworkSection(obj, sectionName, warn) {
     for (const prop of obj.properties) {
         if (!ts.isPropertyAssignment(prop))
             continue;
@@ -218,9 +294,12 @@ function extractFrameworkSection(obj, sectionName) {
                 : undefined;
         if (key !== sectionName)
             continue;
-        if (!ts.isObjectLiteralExpression(prop.initializer))
+        if (!ts.isObjectLiteralExpression(prop.initializer)) {
+            if (warn)
+                warn(`'${sectionName}' section is not an inline object literal — ignored.`);
             return undefined;
-        return extractObjectAsRecord(prop.initializer);
+        }
+        return extractObjectAsRecord(prop.initializer, warn, sectionName);
     }
     return undefined;
 }
@@ -251,11 +330,14 @@ export function parseConfigFile(configPath) {
         }
         // export default config;  (ExportAssignment with an identifier)
         if (ts.isExportAssignment(stmt) && !stmt.isExportEquals) {
-            if (ts.isIdentifier(stmt.expression)) {
-                defaultExportName = stmt.expression.text;
+            // Unwrap `export default { ... } satisfies CuttlefishConfig` /
+            // `as const` / parenthesized forms down to the underlying expression.
+            const expr = unwrapTypeCast(stmt.expression);
+            if (ts.isIdentifier(expr)) {
+                defaultExportName = expr.text;
             }
-            else if (ts.isObjectLiteralExpression(stmt.expression)) {
-                inlineDefaultObject = stmt.expression;
+            else if (ts.isObjectLiteralExpression(expr)) {
+                inlineDefaultObject = expr;
             }
         }
     }
@@ -263,16 +345,43 @@ export function parseConfigFile(configPath) {
     let configObject = inlineDefaultObject;
     if (!configObject && defaultExportName) {
         const decl = variableDecls.get(defaultExportName);
-        if (decl?.initializer && ts.isObjectLiteralExpression(decl.initializer)) {
-            configObject = decl.initializer;
+        if (decl?.initializer) {
+            // `const config = { ... } satisfies CuttlefishConfig` parses the
+            // initializer as a SatisfiesExpression — unwrap to the object literal
+            // so the whole config isn't silently ignored.
+            const init = unwrapTypeCast(decl.initializer);
+            if (ts.isObjectLiteralExpression(init)) {
+                configObject = init;
+            }
         }
     }
     if (!configObject) {
         return undefined;
     }
+    // Collect drop warnings (values the AST-only parser can't evaluate) and
+    // print them once after parsing — silent drops here used to surface much
+    // later as missing -l flags / reverted defaults with no diagnostic.
+    const dropWarnings = [];
+    const seenWarnings = new Set();
+    const warn = (message) => {
+        const line = `${path.basename(configPath)}: ${message}`;
+        if (!seenWarnings.has(line)) {
+            seenWarnings.add(line);
+            dropWarnings.push(line);
+        }
+    };
+    // Typos in top-level keys (e.g. `output.optmize`) were dropped before
+    // schema validation, so the strict schema never saw them — check the raw
+    // source keys against the known set directly.
+    for (const prop of configObject.properties) {
+        const key = propertyKeyName(prop);
+        if (key && !KNOWN_TOP_LEVEL_KEYS.has(key)) {
+            warn(`unknown top-level key '${key}' — misspelled or unsupported.`);
+        }
+    }
     // Walk the object literal into a flat map.
     const flat = new Map();
-    walkObjectLiteral(configObject, "", flat);
+    walkObjectLiteral(configObject, "", flat, warn);
     // Map flat keys to the resolved config shape.
     const resolved = { configPath };
     const entry = flat.get("entry");
@@ -298,14 +407,23 @@ export function parseConfigFile(configPath) {
     if (typeof framework === "string")
         resolved.framework = framework;
     const psram = flat.get("psram");
-    if (psram === "opi" || psram === "quad")
+    if (typeof psram === "string") {
+        // Assign any string (including "") so the schema's PsramType enum rejects
+        // typos ('octal') with a validation error instead of silently dropping it.
         resolved.psram = psram;
+    }
     const outputFramework = flat.get("output.framework");
     if (typeof outputFramework === "string")
         resolved.outputFramework = outputFramework;
-    const outputOptimize = flat.get("output.optimize");
-    if (typeof outputOptimize === "string")
-        resolved.outputOptimize = outputOptimize;
+    // `output.optimize` is removed: no framework ever consumed it (the only
+    // consumer, framework-esp32, is deleted). Warn-and-drop instead of failing
+    // strict validation, so existing configs keep building while telling the
+    // user to delete the key. Optimization is framework territory — e.g.
+    // `zephyr.kconfig` CONFIG_*_OPTIMIZATIONS symbols.
+    if (flat.has("output.optimize")) {
+        warn("'output.optimize' has no effect and is deprecated — remove it. " +
+            "Control optimization via the framework (e.g. zephyr.kconfig CONFIG_SIZE_OPTIMIZATIONS / CONFIG_SPEED_OPTIMIZATIONS).");
+    }
     const outputOutDir = flat.get("output.outDir");
     if (typeof outputOutDir === "string")
         resolved.outputOutDir = outputOutDir;
@@ -319,19 +437,19 @@ export function parseConfigFile(configPath) {
         };
     }
     // Extract structured fields that the flat walker cannot handle.
-    const outputExtraFlags = extractStringArray(configObject, ["output", "extraFlags"]);
+    const outputExtraFlags = extractStringArray(configObject, ["output", "extraFlags"], warn);
     if (outputExtraFlags)
         resolved.outputExtraFlags = outputExtraFlags;
-    const outputDefines = extractStringRecord(configObject, ["output", "defines"]);
+    const outputDefines = extractStringRecord(configObject, ["output", "defines"], warn);
     if (outputDefines)
         resolved.outputDefines = outputDefines;
-    const nativeSection = extractFrameworkSection(configObject, "native");
+    const nativeSection = extractFrameworkSection(configObject, "native", warn);
     if (nativeSection) {
         resolved.frameworkConfig = nativeSection;
     }
     // Parse zephyr-specific config section.
-    const zephyrKconfig = extractStringRecord(configObject, ["zephyr", "kconfig"]);
-    const zephyrCmakeArgs = extractStringArray(configObject, ["zephyr", "cmakeArgs"]);
+    const zephyrKconfig = extractStringRecord(configObject, ["zephyr", "kconfig"], warn);
+    const zephyrCmakeArgs = extractStringArray(configObject, ["zephyr", "cmakeArgs"], warn);
     const zephyrRunner = flat.get("zephyr.runner");
     if (zephyrKconfig || zephyrCmakeArgs || typeof zephyrRunner === "string") {
         resolved.zephyrConfig = {
@@ -341,7 +459,10 @@ export function parseConfigFile(configPath) {
         };
     }
     // Parse display profile config (nested object with profile name, wiring, touch)
-    const displaySection = extractFrameworkSection(configObject, "display");
+    const displaySection = extractFrameworkSection(configObject, "display", warn);
+    // extractObjectAsRecord walks literals into a loose record; the shape is
+    // checked downstream (schema passthrough + display-profile resolution), so
+    // bridge it to the declared DisplayConfig type at this single boundary.
     if (displaySection)
         resolved.display = displaySection;
     // Validate the parsed config against the Zod schema.
@@ -359,12 +480,13 @@ export function parseConfigFile(configPath) {
         structuredForValidation.entry = resolved.entry;
     if (resolved.framework)
         structuredForValidation.framework = resolved.framework;
-    if (resolved.psram)
+    // `!== undefined` (not truthiness) so an empty-string psram reaches the
+    // PsramType enum and fails validation instead of vanishing.
+    if (resolved.psram !== undefined)
         structuredForValidation.psram = resolved.psram;
-    if (resolved.outputFramework || resolved.outputOptimize || resolved.outputOutDir || resolved.outputExtraFlags || resolved.outputDefines) {
+    if (resolved.outputFramework || resolved.outputOutDir || resolved.outputExtraFlags || resolved.outputDefines) {
         structuredForValidation.output = {
             ...(resolved.outputFramework ? { framework: resolved.outputFramework } : {}),
-            ...(resolved.outputOptimize ? { optimize: resolved.outputOptimize } : {}),
             ...(resolved.outputOutDir ? { outDir: resolved.outputOutDir } : {}),
             ...(resolved.outputExtraFlags ? { extraFlags: resolved.outputExtraFlags } : {}),
             ...(resolved.outputDefines ? { defines: resolved.outputDefines } : {}),
@@ -374,6 +496,10 @@ export function parseConfigFile(configPath) {
         structuredForValidation.console = resolved.console;
     if (resolved.zephyrConfig)
         structuredForValidation.zephyr = resolved.zephyrConfig;
+    if (resolved.frameworkConfig)
+        structuredForValidation.native = resolved.frameworkConfig;
+    if (resolved.display)
+        structuredForValidation.display = resolved.display;
     if (resolved.buildTarget) {
         structuredForValidation.frameworkData = { buildTarget: resolved.buildTarget };
     }
@@ -382,6 +508,12 @@ export function parseConfigFile(configPath) {
         const errorMsg = validation.errors.map(e => `  - ${e}`).join("\n");
         throw new Error(`Configuration validation failed for ${configPath}:\n${errorMsg}`);
     }
+    if (dropWarnings.length > 0) {
+        console.warn(`⚠ ${configPath}: some values were ignored (the parser only evaluates inline literals):`);
+        for (const w of dropWarnings) {
+            console.warn(`  ${w}`);
+        }
+    }
     return resolved;
 }
 /**
@@ -440,6 +572,23 @@ export function generateVirtualTypeDeclaration(config, platformDeclarations) {
         "  type Shared<T = unknown> = T;",
         "  type Mutable<T = unknown> = T;",
         "",
+        "  // SafeVariable: SEU-resistant storage. The transpiler lowers SafeVariable<number>",
+        "  // to a C++ template with inverted-redundancy storage. Declared as an interface",
+        "  // (not a type alias) so the TS type checker recognizes method calls.",
+        "  // Arithmetic T only (integral or floating-point); string is rejected by a",
+        "  // static_assert in the emitted C++ template.",
+        "  interface SafeVariable<T = number> { set(value: T): void; get(): T; valid(): boolean; hasFault(): boolean; }",
+        "  // SafeInt: chainable bounds-checked signed-integer arithmetic. The transpiler",
+        "  // lowers SafeInt<number> to SafeInt<int32_t> (a C++ template with sticky-fault",
+        "  // overflow detection). Signed integer T only — unsigned/bool/float/string are",
+        "  // rejected by a static_assert in the emitted C++ template.",
+        "  interface SafeInt<T = number> {",
+        "    add(delta: T): SafeInt<T>; sub(delta: T): SafeInt<T>;",
+        "    mul(factor: T): SafeInt<T>; divide(d: T): SafeInt<T>; mod(d: T): SafeInt<T>;",
+        "    negate(): SafeInt<T>; absValue(): SafeInt<T>;",
+        "    get(): T; hasFault(): boolean; valid(): boolean; reset(newValue: T): void;",
+        "  }",
+        "",
         "  // C-style explicit number types recognized by the transpiler",
         "  type uint8_t = number;",
         "  type int8_t = number;",
@@ -480,9 +629,9 @@ export function generateVirtualTypeDeclaration(config, platformDeclarations) {
         "",
         "declare module '@typecad/board' {",
         `  ${boardExport}`,
-        "  export type Owned<T = any> = T;",
-        "  export type Shared<T = any> = T;",
-        "  export type Mutable<T = any> = T;",
+        "  export type Owned<T = unknown> = T;",
+        "  export type Shared<T = unknown> = T;",
+        "  export type Mutable<T = unknown> = T;",
         "}",
         "",
         "export {};",

package/dist/config-schema.d.ts

@@ -18,19 +18,16 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
     psram: z.ZodOptional<z.ZodEnum<["opi", "quad"]>>;
     output: z.ZodOptional<z.ZodObject<{
         framework: z.ZodOptional<z.ZodString>;
-        optimize: z.ZodOptional<z.ZodEnum<["none", "size", "speed", "balanced"]>>;
         outDir: z.ZodOptional<z.ZodString>;
         defines: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         extraFlags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strict", z.ZodTypeAny, {
         framework?: string | undefined;
-        optimize?: "none" | "size" | "speed" | "balanced" | undefined;
         outDir?: string | undefined;
         defines?: Record<string, string> | undefined;
         extraFlags?: string[] | undefined;
     }, {
         framework?: string | undefined;
-        optimize?: "none" | "size" | "speed" | "balanced" | undefined;
         outDir?: string | undefined;
         defines?: Record<string, string> | undefined;
         extraFlags?: string[] | undefined;
@@ -81,6 +78,9 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
         baudRate?: number | undefined;
     }>>;
     native: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /** Display profile config (driver, wiring, touch) — loosely typed here so
+     *  the loader's presence/shape extraction round-trips through validation. */
+    display: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     zephyr: z.ZodOptional<z.ZodObject<{
         kconfig: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         cmakeArgs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -104,7 +104,6 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
     psram?: "opi" | "quad" | undefined;
     output?: {
         framework?: string | undefined;
-        optimize?: "none" | "size" | "speed" | "balanced" | undefined;
         outDir?: string | undefined;
         defines?: Record<string, string> | undefined;
         extraFlags?: string[] | undefined;
@@ -129,6 +128,7 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
         baudRate?: number | undefined;
     } | undefined;
     native?: Record<string, unknown> | undefined;
+    display?: Record<string, unknown> | undefined;
     zephyr?: {
         kconfig?: Record<string, string> | undefined;
         cmakeArgs?: string[] | undefined;
@@ -144,7 +144,6 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
     psram?: "opi" | "quad" | undefined;
     output?: {
         framework?: string | undefined;
-        optimize?: "none" | "size" | "speed" | "balanced" | undefined;
         outDir?: string | undefined;
         defines?: Record<string, string> | undefined;
         extraFlags?: string[] | undefined;
@@ -169,6 +168,7 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
         baudRate?: number | undefined;
     } | undefined;
     native?: Record<string, unknown> | undefined;
+    display?: Record<string, unknown> | undefined;
     zephyr?: {
         kconfig?: Record<string, string> | undefined;
         cmakeArgs?: string[] | undefined;
@@ -184,7 +184,6 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
     psram?: "opi" | "quad" | undefined;
     output?: {
         framework?: string | undefined;
-        optimize?: "none" | "size" | "speed" | "balanced" | undefined;
         outDir?: string | undefined;
         defines?: Record<string, string> | undefined;
         extraFlags?: string[] | undefined;
@@ -209,6 +208,7 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
         baudRate?: number | undefined;
     } | undefined;
     native?: Record<string, unknown> | undefined;
+    display?: Record<string, unknown> | undefined;
     zephyr?: {
         kconfig?: Record<string, string> | undefined;
         cmakeArgs?: string[] | undefined;
@@ -224,7 +224,6 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
     psram?: "opi" | "quad" | undefined;
     output?: {
         framework?: string | undefined;
-        optimize?: "none" | "size" | "speed" | "balanced" | undefined;
         outDir?: string | undefined;
         defines?: Record<string, string> | undefined;
         extraFlags?: string[] | undefined;
@@ -249,6 +248,7 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
         baudRate?: number | undefined;
     } | undefined;
     native?: Record<string, unknown> | undefined;
+    display?: Record<string, unknown> | undefined;
     zephyr?: {
         kconfig?: Record<string, string> | undefined;
         cmakeArgs?: string[] | undefined;

package/dist/config-schema.js

@@ -6,14 +6,11 @@
 // enum constraints before the config is used by the transpiler.
 // ---------------------------------------------------------------------------
 import { z } from 'zod';
-/** Optimization levels accepted by the output.optimize field. */
-const OptimizationLevel = z.enum(['none', 'size', 'speed', 'balanced']);
 /** PSRAM types accepted by the top-level `psram` field (ESP32 PSRAM variants). */
 const PsramType = z.enum(['opi', 'quad']);
 /** Schema for the `output` section. */
 const OutputConfig = z.object({
     framework: z.string().min(1).optional(),
-    optimize: OptimizationLevel.optional(),
     outDir: z.string().optional(),
     defines: z.record(z.string(), z.string()).optional(),
     extraFlags: z.array(z.string()).optional(),
@@ -68,6 +65,9 @@ export const CuttlefishConfigSchema = z.object({
     toolchain: ToolchainConfig.optional(),
     console: ConsoleConfig.optional(),
     native: z.record(z.string(), z.unknown()).optional(),
+    /** Display profile config (driver, wiring, touch) — loosely typed here so
+     *  the loader's presence/shape extraction round-trips through validation. */
+    display: z.record(z.string(), z.unknown()).optional(),
     zephyr: ZephyrConfig.optional(),
 }).strict().refine(data => !(data.board && data.contract), {
     message: "Specifying both 'board' and 'contract' is not allowed. Choose one.",