@typecad/cuttlefish 0.1.0-alpha.1

package/dist/emit/utils/async-state-machine.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Async state machine generation utilities.
+ * Handles conversion of async functions to cooperative state machines.
+ * Extracted from cpp-emitter.ts
+ */
+import type { StatementIR } from "../../api/index.js";
+import type { PlatformStrategy } from "../../api/shared/index.js";
+/**
+ * Converts a string to PascalCase.
+ * Used for generating class names from function names.
+ *
+ * @param str The input string (e.g., "my_function" or "myFunction")
+ * @returns PascalCase string (e.g., "MyFunction")
+ */
+export declare function toPascalCaseLocal(str: string): string;
+/**
+ * Result of generating an async task class.
+ */
+export interface AsyncTaskClassResult {
+    /** The class definition as a string */
+    classDef: string;
+    /** The instance declaration (e.g., "blinkTask blinkTask;") */
+    instanceDecl: string;
+    /** The task variable name for use in loop() */
+    taskVarName: string;
+}
+/**
+ * Generates a cooperative state-machine class for an async function.
+ *
+ * Handles two patterns:
+ *   1. Cyclic: single `while(true)` body containing `await delay()` calls.
+ *   2. Linear: sequential statements with `await delay()` calls.
+ *
+ * Each `await delay(ms)` call becomes a timed wait state that polls `millis()`.
+ *
+ * @param fnName The original function name
+ * @param fnStatements The function body statements
+ * @param strategy The platform strategy for rendering
+ * @param knownFunctionReturnTypes Map of function names to their return types
+ * @returns The class definition, instance declaration, and task variable name
+ */
+export declare function generateAsyncTaskClass(fnName: string, fnStatements: StatementIR[], strategy: PlatformStrategy, knownFunctionReturnTypes: Map<string, string>, renderStatement: (stmt: StatementIR, forHeader: boolean, strategy: PlatformStrategy, pointerVarTypes?: Map<string, string>, calleeTransformer?: (callee: string) => string, knownFunctionReturnTypes?: Map<string, string>) => string): AsyncTaskClassResult;

package/dist/emit/utils/async-state-machine.js

@@ -0,0 +1,343 @@
+/**
+ * Async state machine generation utilities.
+ * Handles conversion of async functions to cooperative state machines.
+ * Extracted from cpp-emitter.ts
+ */
+import { escapeCppStringLiteral } from "../../utils/strings.js";
+/**
+ * Converts a string to PascalCase.
+ * Used for generating class names from function names.
+ *
+ * @param str The input string (e.g., "my_function" or "myFunction")
+ * @returns PascalCase string (e.g., "MyFunction")
+ */
+export function toPascalCaseLocal(str) {
+    return str
+        .split(/[_\s]+/)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+        .join("");
+}
+/**
+ * Generates a cooperative state-machine class for an async function.
+ *
+ * Handles two patterns:
+ *   1. Cyclic: single `while(true)` body containing `await delay()` calls.
+ *   2. Linear: sequential statements with `await delay()` calls.
+ *
+ * Each `await delay(ms)` call becomes a timed wait state that polls `millis()`.
+ *
+ * @param fnName The original function name
+ * @param fnStatements The function body statements
+ * @param strategy The platform strategy for rendering
+ * @param knownFunctionReturnTypes Map of function names to their return types
+ * @returns The class definition, instance declaration, and task variable name
+ */
+export function generateAsyncTaskClass(fnName, fnStatements, strategy, knownFunctionReturnTypes, renderStatement) {
+    const className = toPascalCaseLocal(fnName) + "Task";
+    const instanceName = `${fnName}Task`;
+    // Detect whether the body is a single while-loop (cyclic) or linear statements
+    let bodyStatements;
+    let isCyclic = false;
+    if (fnStatements.length === 1 && fnStatements[0].kind === "while") {
+        isCyclic = true;
+        bodyStatements = fnStatements[0].body;
+    }
+    else {
+        bodyStatements = fnStatements;
+    }
+    // Split body into segments at each awaited call
+    const segments = [];
+    let currentPre = [];
+    for (const stmt of bodyStatements) {
+        if (stmt.kind === "call" && stmt.isAwaited) {
+            segments.push({ preStatements: currentPre, awaitedCallee: stmt.callee, awaitedArgs: stmt.args });
+            currentPre = [];
+        }
+        else {
+            currentPre.push(stmt);
+        }
+    }
+    // Terminal segment (trailing statements after the last await, or the whole body if no awaits)
+    segments.push({ preStatements: currentPre, awaitedArgs: [] });
+    const awaitCount = segments.filter((s) => s.awaitedCallee !== undefined).length;
+    const stateCount = awaitCount + 1; // STATE_0 … STATE_{awaitCount}; cyclic loops back, linear adds STATE_DONE
+    const stateNames = [];
+    for (let i = 0; i < stateCount; i++)
+        stateNames.push(`STATE_${i}`);
+    if (!isCyclic)
+        stateNames.push("STATE_DONE");
+    // Helper: render a non-await statement as a single C++ line
+    const renderStmt = (stmt) => renderStatement(stmt, false, strategy, undefined, undefined, knownFunctionReturnTypes);
+    // Collect edge-detection markers from segments
+    const edgeInfoMap = new Map();
+    const edgeMembers = new Set();
+    for (let i = 0; i < segments.length; i++) {
+        const seg = segments[i];
+        if (seg.awaitedCallee === "__EMIT__" && seg.awaitedArgs.length > 0) {
+            const argText = seg.awaitedArgs[0].kind === "string"
+                ? seg.awaitedArgs[0].value
+                : renderExpression(seg.awaitedArgs[0], strategy);
+            const info = parseEdgeMarker(argText);
+            if (info) {
+                edgeInfoMap.set(i, info);
+                edgeMembers.add(`_edgePrev_p${info.pin}`);
+            }
+        }
+    }
+    // Collect awaitable-tap markers (await ui.onTap()). args[0] is the node
+    // filter: -1 = any tap, >=0 = a specific node index. Each tap-await needs a
+    // per-await snapshot of __ui_tap_seq to detect the NEXT bump.
+    const tapInfoMap = new Map();
+    const tapMembers = new Map(); // member name → segment index
+    for (let i = 0; i < segments.length; i++) {
+        const seg = segments[i];
+        if (seg.awaitedCallee === "__UI_TAP__" && seg.awaitedArgs.length > 0) {
+            const nodeArg = seg.awaitedArgs[0];
+            const nodeIndex = nodeArg.kind === "number"
+                ? nodeArg.value
+                : -1;
+            const member = `_tapPrev_${i}`;
+            tapInfoMap.set(i, { nodeIndex });
+            tapMembers.set(member, i);
+        }
+    }
+    const caseLines = [];
+    for (let i = 0; i < segments.length; i++) {
+        const seg = segments[i];
+        const stateName = `STATE_${i}`;
+        const isTerminal = seg.awaitedCallee === undefined;
+        const body = [];
+        const edgeSetup = edgeInfoMap.get(i);
+        const edgePoll = i > 0 ? edgeInfoMap.get(i - 1) : undefined;
+        const tapSetup = tapInfoMap.get(i);
+        const tapPoll = i > 0 ? tapInfoMap.get(i - 1) : undefined;
+        if (edgePoll) {
+            // Poll state: check pin transition via digitalRead
+            const prevVar = `_edgePrev_p${edgePoll.pin}`;
+            const cond = edgePoll.edge === "rising"
+                ? `${prevVar} == LOW && _cur == HIGH`
+                : `${prevVar} == HIGH && _cur == LOW`;
+            const fullCond = edgePoll.timeout !== null
+                ? `(${cond}) || ${strategy.currentTimeMillis()} >= _waitUntil`
+                : cond;
+            body.push(`        {`);
+            body.push(`          int _cur = digitalRead(${edgePoll.pin});`);
+            body.push(`          if (${fullCond}) {`);
+            body.push(`            ${prevVar} = _cur;`);
+            for (const stmt of seg.preStatements)
+                body.push(`            ${renderStmt(stmt)}`);
+            if (edgeSetup) {
+                // Next await is also edge detection — set up its pin tracking
+                body.push(`            _edgePrev_p${edgeSetup.pin} = digitalRead(${edgeSetup.pin});`);
+                if (edgeSetup.timeout !== null) {
+                    body.push(`            _waitUntil = ${strategy.currentTimeMillis()} + ${edgeSetup.timeout};`);
+                }
+                body.push(`            _state = STATE_${i + 1};`);
+            }
+            else if (!isTerminal) {
+                const ms = seg.awaitedArgs[0] ? renderExpression(seg.awaitedArgs[0], strategy) : "0";
+                body.push(`            _waitUntil = ${strategy.currentTimeMillis()} + ${ms};`);
+                body.push(`            _state = STATE_${i + 1};`);
+            }
+            else {
+                body.push(`            _state = ${isCyclic ? "STATE_0" : "STATE_DONE"};`);
+            }
+            body.push(`          } else {`);
+            body.push(`            ${prevVar} = _cur;`);
+            body.push(`          }`);
+            body.push(`        }`);
+        }
+        else if (edgeSetup) {
+            // Setup state: capture initial pin state before polling
+            const prevVar = `_edgePrev_p${edgeSetup.pin}`;
+            if (i === 0) {
+                for (const stmt of seg.preStatements)
+                    body.push(`        ${renderStmt(stmt)}`);
+                body.push(`        ${prevVar} = digitalRead(${edgeSetup.pin});`);
+                if (edgeSetup.timeout !== null) {
+                    body.push(`        _waitUntil = ${strategy.currentTimeMillis()} + ${edgeSetup.timeout};`);
+                }
+                body.push(`        _state = STATE_${i + 1};`);
+            }
+            else {
+                body.push(`        if (${strategy.currentTimeMillis()} >= _waitUntil) {`);
+                for (const stmt of seg.preStatements)
+                    body.push(`          ${renderStmt(stmt)}`);
+                body.push(`          ${prevVar} = digitalRead(${edgeSetup.pin});`);
+                if (edgeSetup.timeout !== null) {
+                    body.push(`          _waitUntil = ${strategy.currentTimeMillis()} + ${edgeSetup.timeout};`);
+                }
+                body.push(`          _state = STATE_${i + 1};`);
+                body.push(`        }`);
+            }
+        }
+        else if (tapPoll) {
+            // Tap-poll state: a previous segment ended with `await ui.onTap()`.
+            // Wait until __ui_tap_seq bumps from the captured snapshot. A per-node
+            // await also requires __ui_tap_node to match the awaited node index.
+            const prevVar = `_tapPrev_${i - 1}`;
+            const nodeFilter = tapPoll.nodeIndex;
+            const cond = nodeFilter < 0
+                ? `__ui_tap_seq != ${prevVar}`
+                : `(__ui_tap_seq != ${prevVar}) && (__ui_tap_node == ${nodeFilter})`;
+            body.push(`        if (${cond}) {`);
+            for (const stmt of seg.preStatements)
+                body.push(`          ${renderStmt(stmt)}`);
+            // What does the NEXT await (ending this segment) look like? Re-derive
+            // from the maps via a fresh lookup so TS doesn't narrow edgeSetup away.
+            const nextEdge = edgeInfoMap.get(i) ?? null;
+            if (tapSetup) {
+                // Next await is also a tap — capture its snapshot now.
+                body.push(`          _tapPrev_${i} = __ui_tap_seq;`);
+                body.push(`          _state = STATE_${i + 1};`);
+            }
+            else if (nextEdge) {
+                body.push(`          _edgePrev_p${nextEdge.pin} = digitalRead(${nextEdge.pin});`);
+                if (nextEdge.timeout !== null) {
+                    body.push(`          _waitUntil = ${strategy.currentTimeMillis()} + ${nextEdge.timeout};`);
+                }
+                body.push(`          _state = STATE_${i + 1};`);
+            }
+            else if (!isTerminal) {
+                // Next await is a normal timed wait (delay) — arm its deadline.
+                const ms = seg.awaitedArgs[0] ? renderExpression(seg.awaitedArgs[0], strategy) : "0";
+                body.push(`          _waitUntil = ${strategy.currentTimeMillis()} + ${ms};`);
+                body.push(`          _state = STATE_${i + 1};`);
+            }
+            else {
+                body.push(`          _state = ${isCyclic ? "STATE_0" : "STATE_DONE"};`);
+            }
+            body.push(`        }`);
+        }
+        else if (tapSetup && !edgePoll) {
+            // Tap-setup state: this segment ends with `await ui.onTap()`. Capture the
+            // current tap counter so the poll state can detect the NEXT bump.
+            // (edgePoll takes precedence when the previous await was an edge.)
+            if (i === 0) {
+                for (const stmt of seg.preStatements)
+                    body.push(`        ${renderStmt(stmt)}`);
+                body.push(`        _tapPrev_${i} = __ui_tap_seq;`);
+                body.push(`        _state = STATE_${i + 1};`);
+            }
+            else {
+                body.push(`        if (${strategy.currentTimeMillis()} >= _waitUntil) {`);
+                for (const stmt of seg.preStatements)
+                    body.push(`          ${renderStmt(stmt)}`);
+                body.push(`          _tapPrev_${i} = __ui_tap_seq;`);
+                body.push(`          _state = STATE_${i + 1};`);
+                body.push(`        }`);
+            }
+        }
+        else {
+            // Normal timed-wait state
+            if (i === 0) {
+                for (const stmt of seg.preStatements)
+                    body.push(`        ${renderStmt(stmt)}`);
+                if (!isTerminal) {
+                    const ms = seg.awaitedArgs[0] ? renderExpression(seg.awaitedArgs[0], strategy) : "0";
+                    body.push(`        _waitUntil = ${strategy.currentTimeMillis()} + ${ms};`);
+                    body.push(`        _state = STATE_${i + 1};`);
+                }
+                else {
+                    body.push(`        _state = ${isCyclic ? "STATE_0" : "STATE_DONE"};`);
+                }
+            }
+            else {
+                body.push(`        if (${strategy.currentTimeMillis()} >= _waitUntil) {`);
+                for (const stmt of seg.preStatements)
+                    body.push(`          ${renderStmt(stmt)}`);
+                if (!isTerminal) {
+                    const ms = seg.awaitedArgs[0] ? renderExpression(seg.awaitedArgs[0], strategy) : "0";
+                    body.push(`          _waitUntil = ${strategy.currentTimeMillis()} + ${ms};`);
+                    body.push(`          _state = STATE_${i + 1};`);
+                }
+                else {
+                    body.push(`          _state = ${isCyclic ? "STATE_0" : "STATE_DONE"};`);
+                }
+                body.push(`        }`);
+            }
+        }
+        caseLines.push(`      case ${stateName}:`, `        {`, ...body, `        }`, `        break;`);
+    }
+    if (!isCyclic)
+        caseLines.push(`      case STATE_DONE:`, `        break;`);
+    const stateEnumList = stateNames.join(", ");
+    const isCompleteExpr = isCyclic ? "false" : "_state == STATE_DONE";
+    // Build constructor initializer list and edge/tap member declarations
+    const edgeMemberArr = Array.from(edgeMembers);
+    const tapMemberArr = Array.from(tapMembers.keys());
+    const inits = [`_state(STATE_0)`, `_waitUntil(0)`];
+    for (const m of edgeMemberArr)
+        inits.push(`${m}(LOW)`);
+    for (const m of tapMemberArr)
+        inits.push(`${m}(0)`);
+    const ctorInitList = inits.join(", ");
+    const edgeResetList = edgeMemberArr.map(m => ` ${m} = LOW;`).join("");
+    const tapResetList = tapMemberArr.map(m => ` ${m} = 0;`).join("");
+    const edgeMemberDecls = edgeMemberArr.map(m => `  int ${m};`);
+    // __ui_tap_seq is uint32_t; the snapshot must match to detect bumps correctly.
+    const tapMemberDecls = tapMemberArr.map(m => `  uint32_t ${m};`);
+    const classDef = [
+        `// Async state machine for ${fnName}`,
+        `class ${className} {`,
+        `public:`,
+        `  enum State { ${stateEnumList} };`,
+        `  ${className}() : ${ctorInitList} {}`,
+        `  void run() {`,
+        `    switch (_state) {`,
+        ...caseLines,
+        `    }`,
+        `  }`,
+        `  bool isComplete() const { return ${isCompleteExpr}; }`,
+        `  void reset() { _state = STATE_0; _waitUntil = 0;${edgeResetList}${tapResetList} }`,
+        `private:`,
+        `  State _state;`,
+        `  unsigned long _waitUntil;`,
+        ...edgeMemberDecls,
+        ...tapMemberDecls,
+        `};`,
+    ].join("\n");
+    return { classDef, instanceDecl: `${className} ${instanceName};`, taskVarName: instanceName };
+}
+/**
+ * Renders an expression to a string (simplified version for async state machine).
+ * This is a minimal implementation - full rendering should use ExpressionRenderer.
+ */
+function renderExpression(expr, strategy) {
+    switch (expr.kind) {
+        case "number": {
+            if (expr.cppType === "float" || expr.cppType === "double" || !Number.isInteger(expr.value)) {
+                const str = `${expr.value}`;
+                return str.includes('.') || str.includes('e') || str.includes('E')
+                    ? `${str}f`
+                    : `${str}.0f`;
+            }
+            return `${expr.value}`;
+        }
+        case "string":
+            // Shared escaper — see render-expr.ts / expression-renderer.ts (demo #29
+            // Finding A family). The prior quote-only escape emitted a raw control
+            // char inside the C++ string literal for any `\n`/`\t`/`\\` value.
+            return `"${escapeCppStringLiteral(expr.value)}"`;
+        case "boolean":
+            return expr.value ? "true" : "false";
+        case "identifier":
+            return expr.value;
+        case "raw":
+            return expr.value;
+        case "hal-expr":
+            return `/* hal-expr: ${expr.operation.operation} */`;
+        default:
+            return "/* complex expr */";
+    }
+}
+function parseEdgeMarker(argText) {
+    const match = argText.match(/^__EDGE_(RISING|FALLING)__([a-zA-Z0-9_]+)__T(.*)$/);
+    if (!match)
+        return null;
+    const edge = match[1] === "RISING" ? "rising" : "falling";
+    const pin = match[2];
+    const timeoutStr = match[3];
+    const timeout = !isNaN(Number(timeoutStr)) && Number(timeoutStr) > 0 ? Number(timeoutStr) : null;
+    return { pin, edge, timeout };
+}

package/dist/emit/utils/comment-helpers.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Comment handling utilities for C++ code emission.
+ * Extracted from cpp-emitter.ts
+ */
+/**
+ * Normalizes a comment string into an array of trimmed lines.
+ * Removes empty lines and trailing whitespace.
+ *
+ * @param comment The comment string (may contain newlines)
+ * @returns Array of normalized comment lines
+ */
+export declare function normalizeComment(comment: string): string[];
+/**
+ * Emits comment lines with proper indentation.
+ *
+ * @param comments Optional array of comment strings to emit
+ * @param indent The indentation string to prepend to each line
+ * @param appendLine Function to call for each output line
+ */
+export declare function emitCommentLines(comments: string[] | undefined, indent: string, appendLine: (line: string) => void): void;

package/dist/emit/utils/comment-helpers.js

@@ -0,0 +1,31 @@
+/**
+ * Comment handling utilities for C++ code emission.
+ * Extracted from cpp-emitter.ts
+ */
+/**
+ * Normalizes a comment string into an array of trimmed lines.
+ * Removes empty lines and trailing whitespace.
+ *
+ * @param comment The comment string (may contain newlines)
+ * @returns Array of normalized comment lines
+ */
+export function normalizeComment(comment) {
+    return comment
+        .split(/\r?\n/)
+        .map((line) => line.trimEnd())
+        .filter((line) => line.length > 0);
+}
+/**
+ * Emits comment lines with proper indentation.
+ *
+ * @param comments Optional array of comment strings to emit
+ * @param indent The indentation string to prepend to each line
+ * @param appendLine Function to call for each output line
+ */
+export function emitCommentLines(comments, indent, appendLine) {
+    for (const comment of comments ?? []) {
+        for (const line of normalizeComment(comment)) {
+            appendLine(`${indent}${line}`);
+        }
+    }
+}

package/dist/emit/utils/cpp-helpers.d.ts

@@ -0,0 +1,47 @@
+export declare function accessorGetterName(prop: string): string;
+export declare function accessorSetterName(prop: string): string;
+/**
+ * Matches a C++ INTEGRAL scalar type (the enum↔integral storage boundary in
+ * SUPPORT_MATRIX §1.7). Used by the enum-storage cast sites to decide whether
+ * a value/target is on the integral side of an `enum class` boundary that
+ * needs a `static_cast`. Covers the signed/unsigned `char`/`short`/`int`/
+ * `long` spellings, the fixed-width `<cstdint>` aliases, `size_t`, and `bool`
+ * (bool participates: `Cell c = someBool` is the same boundary). Anchored so
+ * it does not match container/pointer spellings (`std::vector<...>` etc.).
+ *
+ * Single source of truth — emit sites route through this instead of each
+ * keeping their own inline regex (the prior `isNumericTarget` regex in
+ * statement-renderer was one such divergent copy). Demo #32 Finding A.
+ */
+export declare const INTEGRAL_CPP_TYPE_RE: RegExp;
+/**
+ * Resolve the actual numeric value of every member in a numeric enum, applying
+ * the TS/C++ auto-increment rule: an explicit value sets the counter, members
+ * without one get the current counter then increment. Mirrors the per-member
+ * logic the three emit sites use when emitting `= <value>`.
+ */
+export declare function resolveEnumValues(members: ReadonlyArray<{
+    value?: number | string;
+}>): number[];
+/**
+ * Compute the narrowest C++ underlying type for a numeric `enum class`, given
+ * the resolved member values. Returns the `: <type>` suffix string (or `""`
+ * for the default `int`).
+ *
+ * The transpiler knows the full, closed value range of every enum at emit
+ * time — something g++ cannot recover. Picking the narrowest type halves
+ * storage for small enums on AVR (`enum class X` defaults to `int` = 2 bytes;
+ * `enum class X : uint8_t` = 1 byte), which matters for state-machine fields,
+ * opcodes, and pin-role arrays common on small-RAM targets.
+ *
+ * Narrowing is strictly safe: the values provably fit, and `enum class`
+ * underlying-type specification is standard C++11. Widening to `: long` still
+ * applies when a value exceeds the default-int range on targets where
+ * `needsLargeEnumUnderlying` is true (AVR's 16-bit `int`).
+ *
+ * @param values The resolved numeric values of all enum members.
+ * @param needsLargeEnumUnderlying Whether the target's `int` is smaller than
+ *   32 bits (true on AVR). When true, values outside `[-32768, 32767]` widen
+ *   to `: long`. When false (32-bit int), no widening is needed.
+ */
+export declare function narrowestEnumUnderlying(values: readonly number[], needsLargeEnumUnderlying: boolean): string;

package/dist/emit/utils/cpp-helpers.js

@@ -0,0 +1,85 @@
+export function accessorGetterName(prop) {
+    return `get${prop.charAt(0).toUpperCase()}${prop.slice(1)}`;
+}
+export function accessorSetterName(prop) {
+    return `set${prop.charAt(0).toUpperCase()}${prop.slice(1)}`;
+}
+/**
+ * Matches a C++ INTEGRAL scalar type (the enum↔integral storage boundary in
+ * SUPPORT_MATRIX §1.7). Used by the enum-storage cast sites to decide whether
+ * a value/target is on the integral side of an `enum class` boundary that
+ * needs a `static_cast`. Covers the signed/unsigned `char`/`short`/`int`/
+ * `long` spellings, the fixed-width `<cstdint>` aliases, `size_t`, and `bool`
+ * (bool participates: `Cell c = someBool` is the same boundary). Anchored so
+ * it does not match container/pointer spellings (`std::vector<...>` etc.).
+ *
+ * Single source of truth — emit sites route through this instead of each
+ * keeping their own inline regex (the prior `isNumericTarget` regex in
+ * statement-renderer was one such divergent copy). Demo #32 Finding A.
+ */
+export const INTEGRAL_CPP_TYPE_RE = /^(?:unsigned\s+|signed\s+)?(?:bool|char|short|int|long(?:\s+long)?|float|double|u?int(?:8|16|32|64)_t|size_t)$/;
+/**
+ * Resolve the actual numeric value of every member in a numeric enum, applying
+ * the TS/C++ auto-increment rule: an explicit value sets the counter, members
+ * without one get the current counter then increment. Mirrors the per-member
+ * logic the three emit sites use when emitting `= <value>`.
+ */
+export function resolveEnumValues(members) {
+    const values = [];
+    let autoValue = 0;
+    for (const m of members) {
+        if (typeof m.value === "number") {
+            values.push(m.value);
+            autoValue = m.value + 1;
+        }
+        else {
+            // String-valued member (mixed enum) or auto-increment numeric.
+            values.push(autoValue);
+            autoValue++;
+        }
+    }
+    return values;
+}
+/**
+ * Compute the narrowest C++ underlying type for a numeric `enum class`, given
+ * the resolved member values. Returns the `: <type>` suffix string (or `""`
+ * for the default `int`).
+ *
+ * The transpiler knows the full, closed value range of every enum at emit
+ * time — something g++ cannot recover. Picking the narrowest type halves
+ * storage for small enums on AVR (`enum class X` defaults to `int` = 2 bytes;
+ * `enum class X : uint8_t` = 1 byte), which matters for state-machine fields,
+ * opcodes, and pin-role arrays common on small-RAM targets.
+ *
+ * Narrowing is strictly safe: the values provably fit, and `enum class`
+ * underlying-type specification is standard C++11. Widening to `: long` still
+ * applies when a value exceeds the default-int range on targets where
+ * `needsLargeEnumUnderlying` is true (AVR's 16-bit `int`).
+ *
+ * @param values The resolved numeric values of all enum members.
+ * @param needsLargeEnumUnderlying Whether the target's `int` is smaller than
+ *   32 bits (true on AVR). When true, values outside `[-32768, 32767]` widen
+ *   to `: long`. When false (32-bit int), no widening is needed.
+ */
+export function narrowestEnumUnderlying(values, needsLargeEnumUnderlying) {
+    if (values.length === 0)
+        return "";
+    let min = Infinity;
+    let max = -Infinity;
+    for (const v of values) {
+        if (v < min)
+            min = v;
+        if (v > max)
+            max = v;
+    }
+    // Widen to long first if any value overflows the target's default int range.
+    if (needsLargeEnumUnderlying && (max > 32767 || min < -32768)) {
+        return " : long";
+    }
+    // Narrow to the smallest type that fits the full [min, max] range.
+    if (min >= 0 && max <= 255)
+        return " : uint8_t";
+    if (min >= -128 && max <= 127)
+        return " : int8_t";
+    return "";
+}

package/dist/emit/utils/include-resolver.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Include resolution utilities for C++ code emission.
+ * Handles import resolution, SDK detection, and header normalization.
+ * Extracted from cpp-emitter.ts
+ */
+import type { ResolvedNpmPackage } from "../../transpile/resolution.js";
+/**
+ * Checks if a module specifier resolves to a TypeCAD SDK path.
+ * Cuttlefish SDK files (code/core/*, code/board-*, @typecad/* packages) are
+ * type-level only and should produce no C++ output or #include directives.
+ *
+ * @param moduleSpecifier The import specifier (e.g., "@typecad/hal" or "./pins")
+ * @param fromFile The file path from which the import originates
+ * @returns true if this is a TypeCAD SDK import
+ */
+export declare function isCuttlefishSDKImport(moduleSpecifier: string, fromFile: string): boolean;
+/**
+ * Normalizes an include path to proper C++ include format.
+ *
+ * @param include The include path (e.g., "Arduino.h" or "<vector>")
+ * @returns Properly formatted include (e.g., "<Arduino.h>" or "<vector>")
+ */
+export declare function normalizeInclude(include: string): string;
+/**
+ * Deduplicates an array while preserving order.
+ *
+ * @param items The array to deduplicate
+ * @returns A new array with duplicates removed
+ */
+export declare function dedupe<T>(items: T[]): T[];
+/**
+ * Result of resolving a transpiled module include.
+ */
+interface TranspiledIncludeResult {
+    /** The include path (e.g., "\"./pins.h\"") or empty string if not transpiled */
+    include: string;
+    /** Whether this import was resolved as a transpiled npm package */
+    isTranspiled: boolean;
+}
+/**
+ * Resolves an import to a local header file if it's from a transpiled npm package.
+ *
+ * @param moduleSpecifier The import specifier
+ * @param npmPackages Map of source paths to npm package info
+ * @param fromFilePath The file path from which the import originates
+ * @returns Information about the resolved include
+ */
+export declare function resolveTranspiledModuleInclude(moduleSpecifier: string, npmPackages: Map<string, ResolvedNpmPackage> | undefined, fromFilePath: string): TranspiledIncludeResult;
+/**
+ * Applies a symbol map to a callee string.
+ * Transforms root identifiers according to the mapping.
+ *
+ * @param callee The original callee (e.g., "console.log" or "myFunc")
+ * @param symbolMap Map of original names to transformed names
+ * @returns The transformed callee
+ */
+export declare function applySymbolMap(callee: string, symbolMap: Record<string, string>): string;
+export {};