@typecad/cuttlefish 1.0.0-alpha.3 → 1.0.0-alpha.6

package/README.md

@@ -12,15 +12,15 @@ C++, and can chain compile, upload, and serial-monitor steps.
 From a project root containing `cuttlefish.config.ts`:
 
 ```bash
-npx cuttlefish build
-npx cuttlefish build --compile --upload --port COM4
-npx cuttlefish build --compile --upload --monitor --port COM4 --baud 115200
+npx @typecad/cuttlefish build
+npx @typecad/cuttlefish build --compile --upload --port COM4
+npx @typecad/cuttlefish build --compile --upload --monitor --port COM4 --baud 115200
 ```
 
 Scaffold a starter project with the built-in wizard:
 
 ```bash
-npx cuttlefish create --board arduino:avr:uno --framework arduino
+npx @typecad/cuttlefish create --board arduino:avr:uno --framework arduino
 ```
 
 ## Commands

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

@@ -267,6 +267,15 @@ export interface SpiCsHighOp {
     port?: string;
     pin: number;
 }
+export interface SpiReadBufferOp {
+    operation: "spi.read_buffer";
+    bus: string;
+    /** Number of bytes — numeric or runtime expression string */
+    count: number | string;
+    /** Buffer variable name, "__HAL_READ_BUF__" placeholder (rewritten to the
+     *  caller's variable by the variable-init transformer), or "__DISCARD__" */
+    buffer: string;
+}
 export interface UartBeginOp {
     operation: "uart.begin";
     port: string;
@@ -385,7 +394,7 @@ export interface RawCppOp {
  * operations. Each node carries a semantic `operation` tag and typed
  * arguments. Framework strategies translate these into concrete C++.
  */
-export type HALOpIR = GpioWriteOp | GpioReadOp | GpioToggleOp | GpioSetModeOp | PwmWriteOp | PwmGetFrequencyOp | PwmGetResolutionOp | AdcReadOp | AdcGetResolutionOp | AdcSetReferenceOp | AdcGetReferenceOp | AdcReadVoltageOp | DacWriteOp | InterruptAttachOp | InterruptDetachOp | TonePlayOp | ToneStopOp | TimingDelayOp | TimingDelayMicrosecondsOp | TimingMillisOp | TimingMicrosOp | TimingFreeHeapOp | TimingSetIntervalOp | TimingSetTimeoutOp | TimingClearIntervalOp | TimingClearTimeoutOp | PowerDeepSleepOp | PowerLightSleepOp | PowerSetCpuFrequencyOp | I2cBeginOp | I2cEndOp | I2cSetClockOp | I2cBeginTransmissionOp | I2cWriteOp | I2cWriteBytesOp | I2cWriteBufferOp | I2cReadBufferOp | I2cEndTransmissionOp | I2cRequestFromOp | I2cAvailableOp | I2cReadOp | I2cRecoverOp | SpiBeginOp | SpiEndOp | SpiTransferOp | SpibeginTransactionOp | SpiEndTransactionOp | SpiSetModeOp | SpiSetBitOrderOp | SpiCsLowOp | SpiCsHighOp | UartBeginOp | UartEndOp | UartPrintOp | UartPrintlnOp | UartPrintfOp | UartWriteOp | UartReadOp | UartPeekOp | UartAvailableOp | UartFlushOp | PulseInOp | PulseInLongOp | ShiftOutOp | ShiftInOp | BoardResolveOp | WdtEnableOp | WdtResetOp | WdtDisableOp | SnprintfEmitOp | RawCppOp | DisplayHALOp;
+export type HALOpIR = GpioWriteOp | GpioReadOp | GpioToggleOp | GpioSetModeOp | PwmWriteOp | PwmGetFrequencyOp | PwmGetResolutionOp | AdcReadOp | AdcGetResolutionOp | AdcSetReferenceOp | AdcGetReferenceOp | AdcReadVoltageOp | DacWriteOp | InterruptAttachOp | InterruptDetachOp | TonePlayOp | ToneStopOp | TimingDelayOp | TimingDelayMicrosecondsOp | TimingMillisOp | TimingMicrosOp | TimingFreeHeapOp | TimingSetIntervalOp | TimingSetTimeoutOp | TimingClearIntervalOp | TimingClearTimeoutOp | PowerDeepSleepOp | PowerLightSleepOp | PowerSetCpuFrequencyOp | I2cBeginOp | I2cEndOp | I2cSetClockOp | I2cBeginTransmissionOp | I2cWriteOp | I2cWriteBytesOp | I2cWriteBufferOp | I2cReadBufferOp | I2cEndTransmissionOp | I2cRequestFromOp | I2cAvailableOp | I2cReadOp | I2cRecoverOp | SpiBeginOp | SpiEndOp | SpiTransferOp | SpibeginTransactionOp | SpiEndTransactionOp | SpiSetModeOp | SpiSetBitOrderOp | SpiCsLowOp | SpiCsHighOp | SpiReadBufferOp | UartBeginOp | UartEndOp | UartPrintOp | UartPrintlnOp | UartPrintfOp | UartWriteOp | UartReadOp | UartPeekOp | UartAvailableOp | UartFlushOp | PulseInOp | PulseInLongOp | ShiftOutOp | ShiftInOp | BoardResolveOp | WdtEnableOp | WdtResetOp | WdtDisableOp | SnprintfEmitOp | RawCppOp | DisplayHALOp;
 /**
  * Helper type: extracts the operation string from a HALOpIR variant.
  * Useful for type-safe switch statements in framework strategies.

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

@@ -26,6 +26,14 @@ export interface Diagnostic {
     column?: number;
     code?: string;
     source?: string;
+    /**
+     * Path (or basename) of the source file the diagnostic refers to. When set,
+     * it is rendered in the diagnostic header so the location is not just
+     * `(line,col)` but `path/to/file.ts (line,col)`. Emitters should prefer the
+     * real file path from the originating node's sourceSpan, falling back to a
+     * basename when the full path is unavailable.
+     */
+    filePath?: string;
     /** Text of the source line for display context. */
     sourceLine?: string;
 }

package/dist/cli-utils.d.ts

@@ -13,6 +13,7 @@ export declare function printDiagnostics(diagnostics: Array<Diagnostic | {
     line?: number;
     column?: number;
     code?: string;
+    filePath?: string;
     sourceLine?: string;
 }>): void;
 /**

package/dist/cli-utils.js

@@ -50,6 +50,7 @@ export function printDiagnostics(diagnostics) {
     for (const diagnostic of diagnostics) {
         const position = diagnostic.line && diagnostic.column ? chalk.gray(`(${diagnostic.line},${diagnostic.column})`) : "";
         const code = diagnostic.code ? chalk.gray(` [${diagnostic.code}]`) : "";
+        const file = 'filePath' in diagnostic && diagnostic.filePath ? chalk.cyan(diagnostic.filePath) : "";
         let severityLabel;
         let hintColor;
         if (diagnostic.severity === "error") {
@@ -65,7 +66,8 @@ export function printDiagnostics(diagnostics) {
             hintColor = chalk.cyan;
         }
         const location = position ? ` ${position}` : "";
-        const header = `${severityLabel}${code}${location}: ${chalk.white(diagnostic.message)}`;
+        const filePrefix = file ? `${file} ` : "";
+        const header = `${filePrefix}${severityLabel}${code}${location}: ${chalk.white(diagnostic.message)}`;
         if (diagnostic.severity === "error") {
             console.error(header);
         }

package/dist/cli.js

@@ -19,6 +19,8 @@ import { runExpectTests, assertTypeScriptInput, printDiagnostics, printMappedCom
 import { runPreviewServer } from "./preview/server.js";
 import * as ui from "./utils/ui.js";
 import chalk from "chalk";
+import { checkArduinoEnv } from "@typecad/arduino-cli";
+import { runLicensesPresenter } from "./licenses.js";
 function hasFatalDiagnostics(result) {
     return result.diagnostics.some((diagnostic) => diagnostic.severity === "error");
 }
@@ -107,6 +109,62 @@ async function handleBoardAdd(options) {
     }
     console.log(generateFrameworkChecklist(spec));
 }
+/**
+ * `cuttlefish doctor` — verify arduino-cli is installed and the board's core
+ * (derived from the FQBN in cuttlefish.config.ts) is present. Exits 0 if the
+ * environment is OK, non-zero otherwise. Reuses checkArduinoEnv so the
+ * detection logic is shared with the build/test gates.
+ */
+function runDoctor() {
+    ui.printHeader();
+    ui.printStep("Checking arduino-cli environment...");
+    const config = loadCuttlefishConfig(process.cwd());
+    const fqbn = config?.buildTarget;
+    const result = checkArduinoEnv(fqbn);
+    const check = result.check;
+    // arduino-cli presence line
+    if (check.arduinoCliInstalled) {
+        ui.printInfo(`arduino-cli .... ${check.arduinoCliVersion ?? "unknown"}  ✓`);
+    }
+    else if (!result.ok && result.reason === "arduino-cli-not-found") {
+        ui.printError(`arduino-cli .... NOT FOUND on PATH`);
+    }
+    else {
+        ui.printError(`arduino-cli .... found but unresponsive`);
+    }
+    // core presence line (only meaningful if we have an FQBN)
+    if (fqbn) {
+        if (check.requiredCore) {
+            const status = check.requiredCoreInstalled ? "installed ✓" : "NOT installed ✗";
+            const line = `${check.requiredCore} ....... ${status}`;
+            if (check.requiredCoreInstalled) {
+                ui.printInfo(line);
+            }
+            else {
+                ui.printError(line);
+                ui.printInfo(`  → run: arduino-cli core install ${check.requiredCore}`);
+            }
+        }
+    }
+    else {
+        ui.printInfo("(no buildTarget in cuttlefish.config.ts — skipping core check)");
+    }
+    // Exit code
+    if (result.ok) {
+        ui.printSuccess("Environment OK");
+        return; // exitCode stays unset => 0
+    }
+    if (!result.ok) {
+        for (const line of result.messages)
+            ui.printInfo(line);
+        process.exitCode = 1;
+    }
+}
+/**
+ * `cuttlefish licenses` dispatch — the presenter lives in licenses.ts so it is
+ * unit-testable without importing this binary entry module (cli.ts has a
+ * shebang and runs main() at import time). See runLicensesPresenter.
+ */
 async function main() {
     try {
         const options = parseCommandLine(process.argv);
@@ -154,6 +212,14 @@ async function main() {
             }
             return;
         }
+        if (options.command === "doctor") {
+            runDoctor();
+            return;
+        }
+        if (options.command === "licenses") {
+            runLicensesPresenter(options.strict ?? false, options.all ?? false);
+            return;
+        }
         // ── Handle build command — entry point comes from config ──────────
         if (options.command === "build") {
             const buildConfig = loadCuttlefishConfig(process.cwd());

package/dist/create/index.d.ts

@@ -1,6 +1,6 @@
 export { scaffoldProject, normalizeProjectName, KNOWN_TARGETS, KNOWN_BOARDS, registerKnownTarget, printInitNextSteps } from './init-scaffold.js';
 export type { KnownTarget, KnownBoard, ScaffoldProjectResult } from './init-scaffold.js';
-export { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateGitignore, generateEslintConfig, } from './init-templates.js';
+export { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateStarterTest, generateStarterSim, generateGitignore, generateEslintConfig, } from './init-templates.js';
 export type { InitProjectOptions } from './init-templates.js';
 export { runInitWizard } from './init-wizard.js';
 export { scaffoldBoardPackages } from './board-codegen.js';

package/dist/create/index.js

@@ -1,5 +1,5 @@
 export { scaffoldProject, normalizeProjectName, KNOWN_TARGETS, KNOWN_BOARDS, registerKnownTarget, printInitNextSteps } from './init-scaffold.js';
-export { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateGitignore, generateEslintConfig, } from './init-templates.js';
+export { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateStarterTest, generateStarterSim, generateGitignore, generateEslintConfig, } from './init-templates.js';
 export { runInitWizard } from './init-wizard.js';
 // Board codegen tool (`cuttlefish board add`)
 export { scaffoldBoardPackages } from './board-codegen.js';

package/dist/create/init-scaffold.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import fs from "node:fs";
 import chalk from "chalk";
-import { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateGitignore, generateBoardForwardingFile, generateEslintConfig, } from "./init-templates.js";
+import { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateStarterTest, generateStarterSim, generateGitignore, generateBoardForwardingFile, generateEslintConfig, } from "./init-templates.js";
 import { generateEslintRules } from "./eslint-rules-template.js";
 const _knownTargets = [
     {
@@ -150,6 +150,24 @@ export function scaffoldProject(options, outDir) {
         fs.writeFileSync(sketchPath, generateStarterSketch(options), 'utf-8');
         createdFiles.push(sketchPath);
     }
+    // Embedded projects get a starter hardware test (@typecad/expect / cuttlefish-test).
+    // Native projects have no serial/board path, so they get no test setup.
+    if (!options.isNative) {
+        const testsDir = path.join(resolvedOutDir, 'tests');
+        fs.mkdirSync(testsDir, { recursive: true });
+        const testPath = path.join(testsDir, '01-basics.test.ts');
+        fs.writeFileSync(testPath, generateStarterTest(options), 'utf-8');
+        createdFiles.push(testPath);
+        // Host-side simulation (@typecad/simulator + vitest). sim/ is kept separate
+        // from tests/ so `vitest run sim/` never loads the @typecad/expect no-op
+        // stubs, and `cuttlefish-test` (which globs tests/) never tries to flash a
+        // simulator file as firmware.
+        const simDir = path.join(resolvedOutDir, 'sim');
+        fs.mkdirSync(simDir, { recursive: true });
+        const simPath = path.join(simDir, 'main.test.ts');
+        fs.writeFileSync(simPath, generateStarterSim(options), 'utf-8');
+        createdFiles.push(simPath);
+    }
     return { createdFiles, outDir: resolvedOutDir, options };
 }
 export function printInitNextSteps(options, outDir) {
@@ -164,9 +182,15 @@ export function printInitNextSteps(options, outDir) {
     if (!options.isNative) {
         const portHint = process.platform === 'win32' ? 'COM4' : '/dev/ttyACM0';
         console.log();
+        console.log(chalk.bold.white("To simulate without hardware:"));
+        console.log(`  ${chalk.cyan("npm run simulate")}`);
+        console.log();
         console.log(chalk.bold.white("To upload to your board:"));
         console.log(`  ${chalk.cyan("npm run upload")}`);
         console.log();
-        console.log(chalk.dim(`Edit ${chalk.white("package.json")} to change the serial port from ${chalk.white(portHint)} to your port.`));
+        console.log(chalk.bold.white("To run hardware tests:"));
+        console.log(`  ${chalk.cyan("npm run test:hw")}`);
+        console.log();
+        console.log(chalk.dim(`Edit ${chalk.white("cuttlefish.config.ts")} to change the serial port from ${chalk.white(portHint)} to your port.`));
     }
 }

package/dist/create/init-templates.d.ts

@@ -19,6 +19,8 @@ export declare function generateProjectTsconfig(options: InitProjectOptions): st
 export declare function generateProjectConfig(options: InitProjectOptions): string;
 export declare function generateProjectEnvDts(options: InitProjectOptions): string;
 export declare function generateStarterSketch(options: InitProjectOptions): string;
+export declare function generateStarterTest(_options: InitProjectOptions): string;
+export declare function generateStarterSim(options: InitProjectOptions): string;
 export declare function generateBoardForwardingFile(boardPackage: string): string;
 export declare function generateGitignore(_options: InitProjectOptions): string;
 export declare function generateEslintConfig(_options: InitProjectOptions): string;

package/dist/create/init-templates.js

@@ -2,11 +2,11 @@ import { LINT_RULES } from '../ir/feature-registry.js';
 export function generateProjectPackageJson(options) {
     const { projectName, frameworkPackage, boardPackage } = options;
     const deps = {
-        "@typecad/cuttlefish": "^0.1.0-alpha.1",
-        [frameworkPackage]: "^0.1.0-alpha.1",
+        "@typecad/cuttlefish": "^1.0.0-alpha.3",
+        [frameworkPackage]: "^1.0.0-alpha.3",
     };
     if (boardPackage) {
-        deps[boardPackage] = "^0.1.0-alpha.1";
+        deps[boardPackage] = "^1.0.0-alpha.3";
     }
     const depsJson = Object.entries(deps)
         .map(([k, v]) => `    "${k}": "${v}"`)
@@ -15,12 +15,27 @@ export function generateProjectPackageJson(options) {
     // eslint-transpiler-rules plugin (which is plain JS, no dep). Without these
     // devDependencies `npm run lint` fails to resolve the parser/plugin in a
     // freshly created project. Versions mirror the repo demo's package.json.
-    const devDepsJson = [
+    const baseDevDeps = [
         '    "eslint": "^10.4.1"',
         '    "@typescript-eslint/parser": "^8.61.0"',
         '    "@typescript-eslint/eslint-plugin": "^8.61.0"',
-    ].join(',\n');
+    ];
+    // Developer-utility scripts shared by every target (native + embedded).
+    // None require hardware or extra dependencies:
+    //   dev        — auto-retranspile on save (transpile-only; append --compile
+    //                to also compile on each change). The fast "does it
+    //                typecheck" feedback loop.
+    //   gen-decls  — generate TypeScript .d.ts from C++ headers. File-argument:
+    //                `npm run gen-decls -- lib/foo.h` or `-- --all lib/`.
+    //   gen-libdefs — generate library-definition stubs from a TS file's imports.
+    //                File-argument: `npm run gen-libdefs -- src/main.ts`.
+    const devScripts = [
+        '"dev": "cuttlefish build --watch"',
+        '"gen-decls": "cuttlefish gen-decls"',
+        '"gen-libdefs": "cuttlefish gen-libdefs"',
+    ];
     if (options.isNative) {
+        const devDepsJson = baseDevDeps.join(',\n');
         return `{
   "name": "${projectName}",
   "version": "1.0.0",
@@ -28,7 +43,8 @@ export function generateProjectPackageJson(options) {
   "scripts": {
     "build": "cuttlefish build",
     "compile": "cuttlefish build --compile",
-    "lint": "eslint --config .cuttlefish/eslint.config.mjs src/"
+    "lint": "eslint --config .cuttlefish/eslint.config.mjs src/",
+    ${devScripts.join(',\n    ')}
   },
   "dependencies": {
 ${depsJson}
@@ -39,6 +55,19 @@ ${devDepsJson}
 }
 `;
     }
+    // Embedded projects get two host-side testing tiers:
+    //  - @typecad/expect: hardware tests run on the board via cuttlefish-test
+    //    (`npm run test:hw`), scoped to tests/**/*.test.ts.
+    //  - @typecad/simulator + vitest: simulate the board in Node (`npm run
+    //    simulate`), scoped to sim/**/*.test.ts so vitest never collides with the
+    //    @typecad/expect no-op stubs under tests/.
+    // Versions mirror the workspace's published releases / root devDeps.
+    const devDepsJson = [
+        ...baseDevDeps,
+        '    "@typecad/expect": "^1.0.0-alpha.3"',
+        '    "@typecad/simulator": "^1.0.0-alpha.3"',
+        '    "vitest": "^4.0.18"',
+    ].join(',\n');
     return `{
   "name": "${projectName}",
   "version": "1.0.0",
@@ -48,7 +77,10 @@ ${devDepsJson}
     "compile": "cuttlefish build --compile",
     "upload": "cuttlefish build --compile --upload",
     "monitor": "cuttlefish build --compile --upload --monitor",
-    "lint": "eslint --config .cuttlefish/eslint.config.mjs src/"
+    "test:hw": "npm exec -- cuttlefish-test",
+    "simulate": "vitest run sim/",
+    "lint": "eslint --config .cuttlefish/eslint.config.mjs src/",
+    ${devScripts.join(',\n    ')}
   },
   "dependencies": {
 ${depsJson}
@@ -85,9 +117,10 @@ export function generateProjectTsconfig(options) {
     "noEmit": true,
     "resolveJsonModule": true,
     "allowArbitraryExtensions": true,
+    "allowImportingTsExtensions": true,
     "rootDirs": ["src", "types"]${paths}
   },
-  "include": ["src/**/*.ts", "types/**/*.ts", "cuttlefish.config.ts"${options.boardPackage ? ', ".cuttlefish/cuttlefish-env.d.ts"' : ''}]
+  "include": ["src/**/*.ts", "types/**/*.ts", "cuttlefish.config.ts"${options.boardPackage ? ', ".cuttlefish/cuttlefish-env.d.ts"' : ''}${options.isNative ? '' : ', "sim/**/*.ts"'}]
 }
 `;
 }
@@ -127,6 +160,11 @@ export default config;
         : '';
     const portHint = process.platform === 'win32' ? 'COM4' : '/dev/ttyACM0';
     const baudLine = options.baudRate ? `\n\n  // Console polyfill configuration\n  console: {\n    baudRate: ${options.baudRate},\n    // Serial port for upload/monitor. Override with --port on the CLI.\n    port: '${portHint}',\n  },` : '';
+    // Hardware test runner configuration — used by \`npm run test:hw\` (cuttlefish-test,
+    // provided by @typecad/expect). It transpiles each tests/**/*.test.ts file,
+    // flashes it to the board, and evaluates the assertions over serial.
+    const resolvedBaud = options.baudRate ?? 115200;
+    const testLine = `\n\n  // Hardware test runner (@typecad/expect / \`npm run test:hw\`)\n  test: {\n    // Serial port for the test board. Override with --port on the CLI or the\n    // CUTTLEFISH_PORT env var (e.g. CUTTLEFISH_PORT=/dev/ttyUSB0 npm run test:hw).\n    port: '${portHint}',\n    baudRate: ${resolvedBaud},\n    timeout: 30000,\n    include: ['tests/**/*.test.ts'],\n  },`;
     return `// ---------------------------------------------------------------------------
 // cuttlefish.config.ts — Project configuration
 //
@@ -155,7 +193,7 @@ const config: CuttlefishConfig = {
   // Toolchain configuration
   toolchain: {
     type: '${resolvedToolchain}',
-  },${baudLine}
+  },${baudLine}${testLine}
 };
 
 export default config;
@@ -286,6 +324,148 @@ while (true) {
 }
 `;
 }
+export function generateStarterTest(_options) {
+    return `// ---------------------------------------------------------------------------
+// Hardware test — Basics
+//
+// Runs on the board via \`npm run test:hw\` (cuttlefish-test). Each test file is
+// transpiled, flashed to the board, and its assertions are evaluated on the host
+// over serial. Change the serial port in cuttlefish.config.ts (the \`test.port\`
+// field) or override it with the CUTTLEFISH_PORT env var.
+//
+// API: describe(...).it(...).expect(value).<matcher>() chains. Import pin
+// objects from '@typecad/board' to assert on real hardware I/O. Every file ends
+// with done().
+// ---------------------------------------------------------------------------
+
+import { describe, done } from '@typecad/expect';
+
+describe("Basics")
+  .it("adds two numbers")
+  .expect(
+    (() => {
+      const a = 1;
+      let b = 2;
+      return a + b;
+    })
+  ).toBe(3)
+  .it("multiplies two numbers")
+  .expect(
+    (() => {
+      let a = 3;
+      let b = 4;
+      return a * b;
+    })
+  ).toBe(12)
+  .it("reads an array element")
+  .expect(
+    (() => {
+      const data = new Uint8Array([0xAA, 0x10, 0x20]);
+      return data[1];
+    })
+  ).toBe(0x10)
+  .it("clamps a value to a range")
+  .expect(
+    (() => {
+      const value = 2000;
+      return Math.max(0, Math.min(1023, value));
+    })
+  ).toBe(1023);
+
+done();
+`;
+}
+export function generateStarterSim(options) {
+    const boardType = options.targetId;
+    return `// ---------------------------------------------------------------------------
+// Hardware simulation — Button + LED
+//
+// Runs entirely on your computer with \`npm run simulate\` (vitest + the
+// @typecad/simulator package). No board, serial port, or arduino-cli required.
+// The simulator mirrors the pins/peripherals of your ${options.targetDisplayName}
+// (${boardType}); you inject fake inputs and assert on the outputs in Node.
+//
+// This is the fast tier — iterate on logic here, then confirm on real hardware
+// with \`npm run test:hw\` (which flashes tests/ to the board).
+// ---------------------------------------------------------------------------
+
+import { describe, it, expect, beforeEach } from "vitest";
+import {
+  createSimBoard,
+  type SimBoard,
+  type SimDigitalPin,
+} from "@typecad/simulator";
+
+// ===========================================================================
+// FIRMWARE LOGIC
+// ---------------------------------------------------------------------------
+// Factor your firmware into a function that takes the simulated pins as
+// arguments. In a real project this same logic runs on the board against real
+// pins — here it runs against the sim board so you can test it without hardware.
+// ===========================================================================
+
+/**
+ * Reads a button and reflects its state on an LED.
+ *
+ * To use your own logic: replace the body of this function with whatever your
+ * firmware does (read a sensor, drive a motor, print to serial, ...). As long
+ * as it only touches pins you pass in, the simulator can exercise it.
+ */
+function reflectButtonOnLed(button: SimDigitalPin, led: SimDigitalPin): void {
+  // The button pin is pulled HIGH (1) at rest and reads LOW (0) when pressed.
+  if (button.isLow()) {
+    led.high();
+  } else {
+    led.low();
+  }
+}
+
+// ===========================================================================
+// TEST BENCH
+// ---------------------------------------------------------------------------
+// \`createSimBoard\` builds an in-memory version of your board. The pin numbers
+// below match the physical pinout. Add the pins/peripherals your firmware uses:
+// board.digital(n), board.analog(n), board.pwm(n), board.serial(n),
+// board.i2c(n), board.spi(n), board.interrupt(n).
+// ===========================================================================
+
+function setupSim(): { board: SimBoard; button: SimDigitalPin; led: SimDigitalPin } {
+  // boardType mirrors the target chosen with \`cuttlefish create\`.
+  const board = createSimBoard({ boardType: "${boardType}" });
+
+  const button = board.digital(2).asInputPullUp();  // button on pin 2 (INPUT_PULLUP)
+  const led = board.digital(13).asOutput(false);    // LED on pin 13
+
+  return { board, button, led };
+}
+
+describe("Button + LED (simulator)", () => {
+  beforeEach(() => {
+    // A fresh board per test keeps state isolated. For a long-running sim you
+    // can call board.reset() between cycles instead.
+  });
+
+  it("keeps the LED off while the button is released", () => {
+    const { button, led } = setupSim();
+
+    // Button at rest: INPUT_PULLUP reads HIGH.
+    reflectButtonOnLed(button, led);
+
+    expect(led.getBitValue()).toBe(0);
+  });
+
+  it("turns the LED on while the button is pressed", () => {
+    const { button, led } = setupSim();
+
+    // Simulate a press: drive the button pin LOW.
+    button.injectValue(0);
+    reflectButtonOnLed(button, led);
+
+    expect(led.getBitValue()).toBe(1);
+  });
+});
+`;
+}
 export function generateBoardForwardingFile(boardPackage) {
     return `// ---------------------------------------------------------------------------
 // .cuttlefish/board.ts — Dynamically generated forwarding board package

package/dist/emit/emitters/setup.js

@@ -31,6 +31,80 @@ function filterShimBlock(lines, startMarker, endMarker) {
     }
     return filtered;
 }
+/**
+ * Detect whether a program uses the watchdog timer. The HAL resolver lowers
+ * `WDT.enable/reset/disable` calls to structured `wdt.*` hal-ops, which the
+ * setup emitter then renders as bare `wdt_enable/wdt_reset/wdt_disable` calls
+ * (or constant-folded `wdt_enable(WDTO_*)` macros). All of those require
+ * `<avr/wdt.h>`, so the include is gated on this check instead of being forced
+ * into every AVR program.
+ *
+ * `programAnalysis.usesWDT` is NOT used here: it scans `WDT.`-prefixed
+ * callees and raw-code hal-ops, but the structured `wdt.*` ops carry a typed
+ * operation name with no raw code, so the analysis misses them.
+ *
+ * The recursion mirrors `collectStatementIdentifiers` (identifier-collector.ts)
+ * — the canonical IR walker — so every compound statement shape is covered.
+ */
+function programUsesWdt(program) {
+    const visitStatement = (stmt) => {
+        if (stmt.kind === "hal-op") {
+            const opName = stmt.operation?.operation;
+            if (typeof opName === "string" && opName.startsWith("wdt."))
+                return true;
+        }
+        switch (stmt.kind) {
+            case "block":
+            case "labeled":
+                return visit(stmt.body);
+            case "if":
+                return visit(stmt.thenBranch) || visit(stmt.elseBranch ?? []);
+            case "for":
+                return visit(stmt.body)
+                    || (stmt.initializer ? visitStatement(stmt.initializer) : false);
+            case "while":
+            case "do_while":
+            case "for_of":
+            case "for_in":
+                return visit(stmt.body);
+            case "switch":
+                return stmt.cases.some((c) => visit(c.body ?? []));
+            case "try":
+                return visit(stmt.tryBlock) || visit(stmt.catchBlock ?? []) || visit(stmt.finallyBlock ?? []);
+            default:
+                return false;
+        }
+    };
+    const visit = (statements) => {
+        if (!statements)
+            return false;
+        for (const stmt of statements) {
+            if (visitStatement(stmt))
+                return true;
+        }
+        return false;
+    };
+    if (visit(program.topLevelStatements))
+        return true;
+    for (const fn of program.functions) {
+        if (visit(fn.statements))
+            return true;
+    }
+    for (const cls of program.classes) {
+        for (const m of cls.methods)
+            if (visit(m.statements))
+                return true;
+        for (const g of cls.getters)
+            if (visit(g.statements))
+                return true;
+        for (const s of cls.setters)
+            if (visit(s.statements))
+                return true;
+        if (cls.constructor && visit(cls.constructor.statements))
+            return true;
+    }
+    return false;
+}
 /**
  * Extract a `#ifndef MACRO ... #endif` include-guard block from a shim line
  * list. Used to emit just the macro definition (e.g. CUTTLEFISH_UNDEFINED) in
@@ -118,6 +192,14 @@ export function buildEmitterContext(program, options) {
     })();
     const programAnalysis = analyzeProgram(program, strategy);
     if (options.platformContext) {
+        // The UI runtime's per-frame tick calls millis() (injected by the emitter,
+        // not present in user source), so a mounted UI needs the native millis ISR
+        // even when usesNativeTiming is false. OR entryHasUI() into the flag the
+        // AVR strategy reads when gating native_millis, so framework-avr doesn't
+        // drop the Timer0 ISR from a UI program.
+        if (!programAnalysis.usesNativeTiming && entryHasUI()) {
+            programAnalysis.usesNativeTiming = true;
+        }
         options.platformContext.analysis = programAnalysis;
         if (!options.platformContext.architecture && program.boardConstants) {
             options.platformContext.architecture = program.boardConstants.get("architecture");
@@ -223,6 +305,28 @@ export function buildEmitterContext(program, options) {
         if (!programAnalysis.usesStrPtr) {
             shimLines = filterShimBlock(shimLines, '#ifndef CUTTLEFISH_STR_BUF_SIZE', 'inline size_t (strlen)(const __tc_str_ptr& s) { return ::strlen(s.buf); }');
         }
+        // framework-avr native peripheral driver shims. Each block carries a
+        // CUTTLEFISH_*_BEGIN/END marker pair; strip the ones the program doesn't
+        // use. framework-arduino's shimLines contain none of these markers, so
+        // these filters are no-ops there. The strategies also self-gate on the
+        // same flags; this is the defensive backstop (mirrors how usesWDT/etc.
+        // backstop the strategy-side gating above).
+        if (!programAnalysis.usesUart) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_UART_BEGIN', '// CUTTLEFISH_UART_END');
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_UART_EXT_BEGIN', '// CUTTLEFISH_UART_EXT_END');
+        }
+        if (!programAnalysis.usesSPI) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_SPI_BEGIN', '// CUTTLEFISH_SPI_END');
+        }
+        if (!programAnalysis.usesI2C) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_TWI_BEGIN', '// CUTTLEFISH_TWI_END');
+        }
+        if (!programAnalysis.usesEEPROM) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_EEPROM_BEGIN', '// CUTTLEFISH_EEPROM_END');
+        }
+        if (!programAnalysis.usesTone) {
+            shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_TONE_BEGIN', '// CUTTLEFISH_TONE_END');
+        }
         profileDiagnostics = [...strategy.profileDiagnostics(program, options.platformContext)];
     }
     for (const imported of program.imports) {
@@ -745,6 +849,17 @@ export function buildEmitterContext(program, options) {
     if (stringEnumNames.size > 0) {
         includes.push(strategy.cstringHeader());
     }
+    // `<avr/wdt.h>` is only needed when the program actually uses the watchdog.
+    // The HAL resolver lowers WDT.enable/reset/disable to bare wdt_*() calls
+    // (or constant-folded wdt_enable(WDTO_*) macros), all of which require the
+    // header. Detect the structured `wdt.*` hal-ops directly here rather than
+    // relying on programAnalysis.usesWDT (which misses these ops — they carry
+    // a typed operation name, not raw code the analysis scans) or on a forced
+    // include in the AVR profile (which leaked the header into every AVR
+    // program, even ones that never touch the watchdog like `led.toggle()`).
+    if (programUsesWdt(program)) {
+        includes.push("<avr/wdt.h>");
+    }
     // Placeholder defaults for fields that are computed later by other phases
     const noopFixPointer = (c) => c;
     // Demo #18 Finding B: collect the names of non-exported free functions that