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

package/dist/add-preset.d.ts

@@ -0,0 +1,4 @@
+import type { AddCommandOptions } from "./types.js";
+export declare function listAddPresets(): string;
+/** Run `cuttlefish add <preset>`: copy the preset into the project. */
+export declare function runAddPreset(options: AddCommandOptions): void;

package/dist/add-preset.js

@@ -0,0 +1,74 @@
+// ---------------------------------------------------------------------------
+// `cuttlefish add <preset>` — scaffold copy-and-own assets into a project.
+//
+// Presets are files shipped with the package under assets/. The command COPIES
+// them into the user's project (never injected at build time): the user owns
+// the file from day one and the build only reads what they reference. This is
+// the same philosophy as shadcn/ui — components as source you keep, not a
+// runtime dependency.
+// ---------------------------------------------------------------------------
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadShadcnTheme, applyShadcnTheme } from "./theme-tokens.js";
+import chalk from "chalk";
+const ASSETS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../assets");
+const PRESETS = {
+    shadcn: {
+        source: "shadcn/shadcn.css",
+        dest: "src/styles/shadcn.css",
+        description: "shadcn-style CSS variable tokens + component class recipes (buttons, cards, badges, alerts, ...)",
+        nextSteps: [
+            `Link it from a stylesheet (sibling .ui.css file or a <style> block):`,
+            ``,
+            `    @import "./styles/shadcn.css";`,
+            ``,
+            `Then use the classes on native elements:`,
+            `    <button class="btn btn-primary">Save</button>`,
+            `    <view class="card"> ... <text class="card-title">Title</text> ... </view>`,
+            ``,
+            `Dark theme: the file defines a .dark token set — activate it with`,
+            `themeClass: 'dark' in cuttlefish.config.ts's display block.`,
+            `The file is yours: tune tokens and prune recipes freely.`,
+            ``,
+            `Themes: start from an included one with --theme <name>`,
+            `(see \`cuttlefish theme\` for the list); swap later with the same command.`,
+        ],
+    },
+};
+export function listAddPresets() {
+    return Object.entries(PRESETS).map(([id, p]) => `  ${id.padEnd(10)} ${p.description}`).join("\n");
+}
+/** Run `cuttlefish add <preset>`: copy the preset into the project. */
+export function runAddPreset(options) {
+    const preset = PRESETS[options.preset];
+    if (!preset) {
+        throw new Error(`Unknown preset "${options.preset}". Available presets:\n${listAddPresets()}`);
+    }
+    const src = path.join(ASSETS_DIR, preset.source);
+    if (!fs.existsSync(src)) {
+        throw new Error(`Preset asset missing from the cuttlefish package: ${src}`);
+    }
+    const dest = path.resolve(options.projectRoot, preset.dest);
+    if (fs.existsSync(dest) && !options.force) {
+        throw new Error(`${dest} already exists — re-run with --force to overwrite (your edits will be lost).`);
+    }
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+    // --theme <name>: merge an included shadcn theme's tokens into the copied
+    // stylesheet (shadcn preset only; no-op for future presets without themes).
+    if (options.theme) {
+        if (options.preset !== "shadcn") {
+            throw new Error(`--theme applies to the shadcn preset only (got "${options.preset}").`);
+        }
+        const theme = loadShadcnTheme(options.theme, options.projectRoot);
+        fs.writeFileSync(dest, applyShadcnTheme(fs.readFileSync(dest, "utf-8"), theme), "utf-8");
+        console.log(chalk.green(`✓`) + ` Theme ${chalk.cyan(theme.name)} tokens merged into the copied file.`);
+    }
+    console.log(chalk.green(`✓`) + ` Added preset ${chalk.cyan(options.preset)} → ${path.relative(options.projectRoot, dest)}`);
+    console.log();
+    console.log(chalk.bold(`Next steps:`));
+    for (const line of preset.nextSteps) {
+        console.log(line ? `  ${line}` : ``);
+    }
+}

package/dist/api/config.d.ts

@@ -2,8 +2,6 @@ import type { ArchitectureIdentifier } from './board-types.js';
 import type { DisplayConfig } from './shared/display-profile.js';
 /** Build-system / framework the transpiler should target. */
 type OutputFramework = string & {};
-/** Optimization strategy. */
-type OptimizationLevel = 'none' | 'size' | 'speed' | 'balanced';
 /**
  * Output section — controls how generated C++ is laid out.
  */
@@ -14,8 +12,6 @@ interface CuttlefishOutputConfig {
      * Matches the optional Zod `output.framework` in config-schema.ts.
      */
     framework?: OutputFramework;
-    /** Optimization level. */
-    optimize?: OptimizationLevel;
     /** Directory to write generated files into (relative to project root). */
     outDir?: string;
     /** Additional compiler defines (KEY = value). */

package/dist/api/shared/display-adapters/sdl.js

@@ -323,7 +323,7 @@ export const sdlAdapter = (display) => {
             `    __tc_display.put(dx, dy, pixels[i]);`,
             `  }`,
             `}`,
-            `static inline CuttlefishCanvas16* display_createCanvas(int16_t w, int16_t h) { return new SdlGfxCanvas(w, h); }`,
+            `static inline CuttlefishCanvas16* display_createCanvas(int16_t w, int16_t h) { return new (std::nothrow) SdlGfxCanvas(w, h); }`,
             `static inline CuttlefishCanvas16* display_createCanvasPsram(int16_t, int16_t) { return nullptr; }`,
             `static inline void display_deleteCanvas(CuttlefishCanvas16* c) { delete c; }`,
             `static inline int16_t display_canvasWidth(CuttlefishCanvas16* c) { return c->width(); }`,

package/dist/api/shared/display-profile.d.ts

@@ -86,6 +86,11 @@ export interface DisplayProfile {
      * is read, so a missing/unsafe readback path must not affect normal drawing.
      */
     scanlineSync?: boolean;
+    /** Tearing-effect (TE) sync, hardware variant: GPIO number of the panel's
+     *  TE output. Opt-in — few off-the-shelf display boards break the pin out.
+     *  When wired, panel updates wait for the TE frame pulse instead of the
+     *  GET_SCANLINE readback (no MISO needed; see also scanlineSync). */
+    tearingEffectPin?: number;
     touch?: TouchProfile;
     /** Enable antialiased rendering for circles, lines, rounded corners, and text
      *  unless a node opts out with font-smoothing:none.
@@ -158,6 +163,12 @@ export interface DisplayConfig {
      * default because some ST7796S modules misbehave when this command is read.
      */
     scanlineSync?: boolean;
+    /** Tearing-effect (TE) hardware sync: GPIO number of the panel's TE output
+     *  (ST7796S TE / ILI9341 TE pin). Strictly opt-in — few off-the-shelf
+     *  display boards break the pin out. When wired, panel updates arm on the
+     *  TE frame pulse (tear-free writes, no MISO readback); the Zephyr overlay
+     *  emits te-gpios on the display DT node and the adapter raises TEON. */
+    tearingEffectPin?: number;
     touch?: TouchProfile | false;
     cs?: number;
     dc?: number;

package/dist/api/shared/display-profile.js

@@ -81,6 +81,7 @@ export function resolveDisplayProfile(config, registry) {
             spiPins: config.spiPins,
             colorOrder: config.colorOrder,
             invertDisplay: config.invertDisplay,
+            tearingEffectPin: config.tearingEffectPin,
             touch: config.touch === false ? undefined : config.touch,
             displayClass: config.displayClass,
             capabilities: config.capabilities,
@@ -112,6 +113,8 @@ export function resolveDisplayProfile(config, registry) {
         base.colorOrder = config.colorOrder;
     if (config.invertDisplay !== undefined)
         base.invertDisplay = config.invertDisplay;
+    if (config.tearingEffectPin !== undefined)
+        base.tearingEffectPin = config.tearingEffectPin;
     if (config.scanlineSync !== undefined)
         base.scanlineSync = config.scanlineSync;
     if (config.touch === false)

package/dist/api/shared/hal-op-ir.d.ts

@@ -7,16 +7,35 @@ export interface GpioWriteOp {
     pin: number;
     /** 0 = LOW, 1 = HIGH, or a runtime expression string (e.g. "state", "!state") */
     value: 0 | 1 | string;
+    /**
+     * Output-pin state tracking: set at the END of the file's IR build (see
+     * markShadowUpdatingOps) when this pin has a tracked shadow read anywhere
+     * in the file — the emitted write must also assign the shadow state
+     * variable. Baked into the op at build time because emit never sees live
+     * tracker state: every file's buildProgramIR resets the tracker, and all
+     * files build before any emit runs.
+     */
+    updatesShadow?: boolean;
 }
 export interface GpioReadOp {
     operation: "gpio.read";
     port?: string;
     pin: number;
+    /**
+     * Output-pin state tracking: when set, this read is on a pin explicitly
+     * configured as OUTPUT and must NOT lower to a hardware pin read (which is
+     * not portable for direction-only outputs, e.g. Zephyr). 'high'/'low' fold
+     * to a compile-time constant; 'shadow' lowers to the tracked state
+     * variable that generated writes keep updated.
+     */
+    trackedValue?: "high" | "low" | "shadow";
 }
 export interface GpioToggleOp {
     operation: "gpio.toggle";
     port?: string;
     pin: number;
+    /** Output-pin state tracking — same contract as GpioWriteOp.updatesShadow. */
+    updatesShadow?: boolean;
 }
 export interface GpioSetModeOp {
     operation: "gpio.set_mode";

package/dist/api/shared/toolchain-types.d.ts

@@ -28,7 +28,6 @@ export interface ToolchainOptions {
     buildTarget?: string;
     port?: string;
     baud?: number;
-    optimize?: string;
     extraFlags?: string[];
     defines?: Record<string, string>;
     /** ESP32 PSRAM type ('opi' | 'quad') when the target board has PSRAM. */

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");
@@ -570,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,
@@ -671,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,
@@ -779,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;
     /**

package/dist/config-loader.js

@@ -415,9 +415,15 @@ export function parseConfigFile(configPath) {
     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;
@@ -478,10 +484,9 @@ export function parseConfigFile(configPath) {
     // 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 } : {}),

package/dist/config-schema.d.ts

@@ -18,20 +18,17 @@ 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;
         outDir?: string | undefined;
-        optimize?: "none" | "size" | "speed" | "balanced" | undefined;
         defines?: Record<string, string> | undefined;
         extraFlags?: string[] | undefined;
     }, {
         framework?: string | undefined;
         outDir?: string | undefined;
-        optimize?: "none" | "size" | "speed" | "balanced" | undefined;
         defines?: Record<string, string> | undefined;
         extraFlags?: string[] | undefined;
     }>>;
@@ -46,19 +43,19 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
         buildTarget: z.ZodOptional<z.ZodString>;
         board: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
-        port?: string | undefined;
-        include?: string[] | undefined;
         board?: string | undefined;
+        include?: string[] | undefined;
+        port?: string | undefined;
+        baudRate?: number | undefined;
         timeout?: number | undefined;
         buildTarget?: string | undefined;
-        baudRate?: number | undefined;
     }, {
-        port?: string | undefined;
-        include?: string[] | undefined;
         board?: string | undefined;
+        include?: string[] | undefined;
+        port?: string | undefined;
+        baudRate?: number | undefined;
         timeout?: number | undefined;
         buildTarget?: string | undefined;
-        baudRate?: number | undefined;
     }>>;
     toolchain: z.ZodOptional<z.ZodObject<{
         type: z.ZodOptional<z.ZodString>;
@@ -98,169 +95,165 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
         runner?: string | undefined;
     }>>;
 }, "strict", z.ZodTypeAny, {
-    console?: {
-        port?: string | undefined;
-        baudRate?: number | undefined;
-    } | undefined;
-    frameworkData?: Record<string, unknown> | undefined;
+    entry?: string | undefined;
     target?: string | undefined;
+    mcu?: string | undefined;
+    board?: string | undefined;
+    contract?: string | undefined;
+    framework?: string | undefined;
+    psram?: "opi" | "quad" | undefined;
     output?: {
         framework?: string | undefined;
         outDir?: string | undefined;
-        optimize?: "none" | "size" | "speed" | "balanced" | undefined;
         defines?: Record<string, string> | undefined;
         extraFlags?: string[] | undefined;
     } | undefined;
+    frameworkData?: Record<string, unknown> | undefined;
     include?: string[] | undefined;
-    board?: string | undefined;
-    entry?: string | undefined;
-    display?: Record<string, unknown> | undefined;
     exclude?: string[] | undefined;
+    test?: {
+        board?: string | undefined;
+        include?: string[] | undefined;
+        port?: string | undefined;
+        baudRate?: number | undefined;
+        timeout?: number | undefined;
+        buildTarget?: string | undefined;
+    } | undefined;
     toolchain?: {
         type?: string | undefined;
         frameworkOptions?: Record<string, unknown> | undefined;
     } | undefined;
+    console?: {
+        port?: string | undefined;
+        baudRate?: number | undefined;
+    } | undefined;
+    native?: Record<string, unknown> | undefined;
+    display?: Record<string, unknown> | undefined;
     zephyr?: {
         kconfig?: Record<string, string> | undefined;
         cmakeArgs?: string[] | undefined;
         runner?: string | undefined;
     } | undefined;
-    framework?: string | undefined;
-    native?: Record<string, unknown> | undefined;
+}, {
+    entry?: string | undefined;
+    target?: string | undefined;
     mcu?: string | undefined;
+    board?: string | undefined;
     contract?: string | undefined;
+    framework?: string | undefined;
     psram?: "opi" | "quad" | undefined;
-    test?: {
-        port?: string | undefined;
-        include?: string[] | undefined;
-        board?: string | undefined;
-        timeout?: number | undefined;
-        buildTarget?: string | undefined;
-        baudRate?: number | undefined;
-    } | undefined;
-}, {
-    console?: {
-        port?: string | undefined;
-        baudRate?: number | undefined;
-    } | undefined;
-    frameworkData?: Record<string, unknown> | undefined;
-    target?: string | undefined;
     output?: {
         framework?: string | undefined;
         outDir?: string | undefined;
-        optimize?: "none" | "size" | "speed" | "balanced" | undefined;
         defines?: Record<string, string> | undefined;
         extraFlags?: string[] | undefined;
     } | undefined;
+    frameworkData?: Record<string, unknown> | undefined;
     include?: string[] | undefined;
-    board?: string | undefined;
-    entry?: string | undefined;
-    display?: Record<string, unknown> | undefined;
     exclude?: string[] | undefined;
+    test?: {
+        board?: string | undefined;
+        include?: string[] | undefined;
+        port?: string | undefined;
+        baudRate?: number | undefined;
+        timeout?: number | undefined;
+        buildTarget?: string | undefined;
+    } | undefined;
     toolchain?: {
         type?: string | undefined;
         frameworkOptions?: Record<string, unknown> | undefined;
     } | undefined;
+    console?: {
+        port?: string | undefined;
+        baudRate?: number | undefined;
+    } | undefined;
+    native?: Record<string, unknown> | undefined;
+    display?: Record<string, unknown> | undefined;
     zephyr?: {
         kconfig?: Record<string, string> | undefined;
         cmakeArgs?: string[] | undefined;
         runner?: string | undefined;
     } | undefined;
-    framework?: string | undefined;
-    native?: Record<string, unknown> | undefined;
+}>, {
+    entry?: string | undefined;
+    target?: string | undefined;
     mcu?: string | undefined;
+    board?: string | undefined;
     contract?: string | undefined;
+    framework?: string | undefined;
     psram?: "opi" | "quad" | undefined;
-    test?: {
-        port?: string | undefined;
-        include?: string[] | undefined;
-        board?: string | undefined;
-        timeout?: number | undefined;
-        buildTarget?: string | undefined;
-        baudRate?: number | undefined;
-    } | undefined;
-}>, {
-    console?: {
-        port?: string | undefined;
-        baudRate?: number | undefined;
-    } | undefined;
-    frameworkData?: Record<string, unknown> | undefined;
-    target?: string | undefined;
     output?: {
         framework?: string | undefined;
         outDir?: string | undefined;
-        optimize?: "none" | "size" | "speed" | "balanced" | undefined;
         defines?: Record<string, string> | undefined;
         extraFlags?: string[] | undefined;
     } | undefined;
+    frameworkData?: Record<string, unknown> | undefined;
     include?: string[] | undefined;
-    board?: string | undefined;
-    entry?: string | undefined;
-    display?: Record<string, unknown> | undefined;
     exclude?: string[] | undefined;
+    test?: {
+        board?: string | undefined;
+        include?: string[] | undefined;
+        port?: string | undefined;
+        baudRate?: number | undefined;
+        timeout?: number | undefined;
+        buildTarget?: string | undefined;
+    } | undefined;
     toolchain?: {
         type?: string | undefined;
         frameworkOptions?: Record<string, unknown> | undefined;
     } | undefined;
+    console?: {
+        port?: string | undefined;
+        baudRate?: number | undefined;
+    } | undefined;
+    native?: Record<string, unknown> | undefined;
+    display?: Record<string, unknown> | undefined;
     zephyr?: {
         kconfig?: Record<string, string> | undefined;
         cmakeArgs?: string[] | undefined;
         runner?: string | undefined;
     } | undefined;
-    framework?: string | undefined;
-    native?: Record<string, unknown> | undefined;
+}, {
+    entry?: string | undefined;
+    target?: string | undefined;
     mcu?: string | undefined;
+    board?: string | undefined;
     contract?: string | undefined;
+    framework?: string | undefined;
     psram?: "opi" | "quad" | undefined;
-    test?: {
-        port?: string | undefined;
-        include?: string[] | undefined;
-        board?: string | undefined;
-        timeout?: number | undefined;
-        buildTarget?: string | undefined;
-        baudRate?: number | undefined;
-    } | undefined;
-}, {
-    console?: {
-        port?: string | undefined;
-        baudRate?: number | undefined;
-    } | undefined;
-    frameworkData?: Record<string, unknown> | undefined;
-    target?: string | undefined;
     output?: {
         framework?: string | undefined;
         outDir?: string | undefined;
-        optimize?: "none" | "size" | "speed" | "balanced" | undefined;
         defines?: Record<string, string> | undefined;
         extraFlags?: string[] | undefined;
     } | undefined;
+    frameworkData?: Record<string, unknown> | undefined;
     include?: string[] | undefined;
-    board?: string | undefined;
-    entry?: string | undefined;
-    display?: Record<string, unknown> | undefined;
     exclude?: string[] | undefined;
+    test?: {
+        board?: string | undefined;
+        include?: string[] | undefined;
+        port?: string | undefined;
+        baudRate?: number | undefined;
+        timeout?: number | undefined;
+        buildTarget?: string | undefined;
+    } | undefined;
     toolchain?: {
         type?: string | undefined;
         frameworkOptions?: Record<string, unknown> | undefined;
     } | undefined;
+    console?: {
+        port?: string | undefined;
+        baudRate?: number | undefined;
+    } | undefined;
+    native?: Record<string, unknown> | undefined;
+    display?: Record<string, unknown> | undefined;
     zephyr?: {
         kconfig?: Record<string, string> | undefined;
         cmakeArgs?: string[] | undefined;
         runner?: string | undefined;
     } | undefined;
-    framework?: string | undefined;
-    native?: Record<string, unknown> | undefined;
-    mcu?: string | undefined;
-    contract?: string | undefined;
-    psram?: "opi" | "quad" | undefined;
-    test?: {
-        port?: string | undefined;
-        include?: string[] | undefined;
-        board?: string | undefined;
-        timeout?: number | undefined;
-        buildTarget?: string | undefined;
-        baudRate?: number | undefined;
-    } | undefined;
 }>;
 /** Inferred TypeScript type from the Zod schema. */
 export type ValidatedCuttlefishConfig = z.infer<typeof CuttlefishConfigSchema>;

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(),

package/dist/create/debug-artifacts.d.ts

@@ -0,0 +1,20 @@
+export interface FrameworkDebugArtifactsOptions {
+    /** Framework package name (e.g. '@typecad/framework-zephyr'), if known. */
+    frameworkPackage?: string;
+    /** Absolute path to the new cuttlefish project root. */
+    workspaceRoot: string;
+    /** The framework build target (e.g. Zephyr board id), if known. */
+    buildTarget?: string;
+}
+/**
+ * Module loader for the framework package. Returns the loaded module, or
+ * undefined when it cannot be resolved. Injectable for tests.
+ */
+export type FrameworkModuleLoader = (packageName: string) => any | undefined;
+/**
+ * Generate the framework's starter debug artifacts for a new project.
+ * Returns the workspace-relative paths written (e.g. ['.vscode/launch.json']),
+ * or [] when the framework has no debug support, isn't resolvable yet, or the
+ * generator failed (warns, never throws).
+ */
+export declare function generateFrameworkDebugArtifacts(o: FrameworkDebugArtifactsOptions, loadModule?: FrameworkModuleLoader): string[];