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

package/dist/orchestrator/graph-builder.js

@@ -3,6 +3,8 @@ import ts from "typescript";
 import { readText } from "../utils/fs.js";
 import { detectNativeCppModule, getNpmPackageInfoForFile, isInNodeModules, resolveImport, isCuttlefishSDKPath, } from "../transpile/resolution.js";
 import { requireUIHook } from "../ui-hook.js";
+import { isSafetyImportSpecifier } from "../safety/specifiers.js";
+import { registerCuttlefishLibraryFromSpecifier } from "../library-packages.js";
 /**
  * Sort files in dependency order using Kahn's algorithm.
  * Dependencies come before dependents so that include ordering is correct
@@ -65,10 +67,10 @@ export function topologicalSortFiles(files, dependencies) {
  * Also detects native C++ modules (.d.ts + .cpp pairs).
  * Files are returned in dependency order (dependencies before dependents).
  *
- * @param boardPackage  When provided, `@typecad/board` imports resolve to this
- *                      board package (e.g. `'@typecad/board-arduino-uno'`).
+ * @param boardTarget  When provided, `@typecad/board` imports fall back to
+ *                      this package specifier (legacy; generated boards win).
  */
-export async function collectTranspileGraph(entryFile, boardPackage, imageDecodeOpts) {
+export async function collectTranspileGraph(entryFile, boardTarget, imageDecodeOpts) {
     const ordered = [];
     const pending = [path.resolve(entryFile)];
     const visited = new Set();
@@ -125,11 +127,19 @@ export async function collectTranspileGraph(entryFile, boardPackage, imageDecode
                 }
                 if (!moduleSpecifier)
                     continue;
-                if (moduleSpecifier === "@typecad/expect" || moduleSpecifier === "@typecad/ui" || moduleSpecifier === "@typecad/safety")
+                // Cuttlefish library package: an import whose package ships a
+                // cuttlefish.library.json contributes native shims + build fragments
+                // instead of transpiling — its own TypeScript types are the contract.
+                // Must precede the @typecad/* skips: scoped libraries would otherwise
+                // be dropped as "SDK packages" here (the .ui script loop skips ALL
+                // @typecad/* specifiers, unlike the selective main-loop skip list).
+                if (registerCuttlefishLibraryFromSpecifier(filePath, moduleSpecifier))
+                    continue;
+                if (moduleSpecifier === "@typecad/expect" || moduleSpecifier === "@typecad/ui" || isSafetyImportSpecifier(moduleSpecifier))
                     continue;
                 if (moduleSpecifier.startsWith("@typecad/"))
                     continue;
-                const resolved = resolveImport(filePath, moduleSpecifier, boardPackage);
+                const resolved = resolveImport(filePath, moduleSpecifier, boardTarget);
                 if (!resolved)
                     continue;
                 if (resolved.uiModule)
@@ -158,21 +168,28 @@ export async function collectTranspileGraph(entryFile, boardPackage, imageDecode
                 nativeModules.set(moduleSpecifier, nativeModule);
                 continue; // Don't try to resolve as TypeScript
             }
+            // Cuttlefish library package: an import whose package ships a
+            // cuttlefish.library.json contributes native shims + build fragments
+            // instead of transpiling — its own TypeScript types are the contract.
+            // Checked before the @typecad/* skips so scoped libraries register.
+            if (registerCuttlefishLibraryFromSpecifier(filePath, moduleSpecifier)) {
+                continue;
+            }
             // Skip @typecad/expect — it provides type-level stubs only.
             // The AST preprocessor rewrites all expect calls before transpilation.
             if (moduleSpecifier === "@typecad/expect") {
                 continue;
             }
-            // Skip @typecad/ui and @typecad/safety — they provide compile-time
-            // authoring stubs only. Their calls (ui.mount/signal/bind, safe.read)
-            // are intercepted at IR-build time and lowered to IR; the packages
-            // themselves must NOT be emitted as C++ modules (they would synthesize
+            // Skip @typecad/ui and the safety authoring surface — they provide
+            // compile-time authoring stubs only. Their calls (ui.mount/signal/bind,
+            // safe.read) are intercepted at IR-build time and lowered to IR; the
+            // modules themselves must NOT be emitted as C++ (they would synthesize
             // bogus _ui_t / _safe_t structs). All runtime definitions the user code
             // needs (enums, structs, shims) are provided by the safety polyfill.
-            if (moduleSpecifier === "@typecad/ui" || moduleSpecifier === "@typecad/safety") {
+            if (moduleSpecifier === "@typecad/ui" || isSafetyImportSpecifier(moduleSpecifier)) {
                 continue;
             }
-            // Skip @typecad/board, @typecad/board-*, @typecad/mcu-*, @typecad/hal,
+            // Skip @typecad/board (virtual), the legacy board/mcu package prefixes, @typecad/hal,
             // and @typecad/framework-* — these packages ship src/ for HAL metadata
             // introspection (hal-parser.ts, board-resolver.ts) but their source
             // must NOT be transpiled to C++. The HAL resolver loads class/method
@@ -189,7 +206,7 @@ export async function collectTranspileGraph(entryFile, boardPackage, imageDecode
                 || moduleSpecifier.startsWith("@typecad/framework-")) {
                 continue;
             }
-            const resolved = resolveImport(filePath, moduleSpecifier, boardPackage);
+            const resolved = resolveImport(filePath, moduleSpecifier, boardTarget);
             // .ui.html modules: load into the UI registry, record the path, and don't
             // push onto `pending` (they are never parsed as TypeScript).
             if (resolved?.uiModule) {

package/dist/orchestrator/type-checker.d.ts

@@ -22,11 +22,11 @@ export interface TypeCheckResult {
  * Returns early if any errors are found.
  *
  * @param files List of TypeScript files to type-check
- * @param _boardPackage Optional board package for resolving @typecad/board imports
- * @param entryFile Entrypoint sketch/main file
+ * @param _boardTarget Optional board package for resolving @typecad/board imports
+ * @param entryFile Entrypoint source/main file
  * @returns TypeCheckResult with success status and any error messages
  */
-export declare function typeCheckFiles(files: string[], _boardPackage?: string, entryFile?: string): TypeCheckResult;
+export declare function typeCheckFiles(files: string[], _boardTarget?: string, entryFile?: string): TypeCheckResult;
 /**
  * Run semantic gates against the user files of a type-checked program.
  *

package/dist/orchestrator/type-checker.js

@@ -10,11 +10,11 @@ import { requireUIHook, hasUIHook } from "../ui-hook.js";
  * Returns early if any errors are found.
  *
  * @param files List of TypeScript files to type-check
- * @param _boardPackage Optional board package for resolving @typecad/board imports
- * @param entryFile Entrypoint sketch/main file
+ * @param _boardTarget Optional board package for resolving @typecad/board imports
+ * @param entryFile Entrypoint source/main file
  * @returns TypeCheckResult with success status and any error messages
  */
-export function typeCheckFiles(files, _boardPackage, entryFile) {
+export function typeCheckFiles(files, _boardTarget, entryFile) {
     // Find the nearest tsconfig.json by walking up from the entry file (preferred)
     // or the first file in the graph. Using the entry file ensures we pick up the
     // user's tsconfig (with path mappings) rather than a dependency's tsconfig.

package/dist/platform/async-runtime.js

@@ -16,7 +16,7 @@ export function buildAsyncRuntimePolyfill(program, ctx, target, queueCapacity, s
     // instead of a millis() token the generic target never defines). When the
     // expression uses std::chrono, the polyfill must carry <chrono> itself —
     // the generic strategy's forcedIncludes are empty by design.
-    const now = strategy?.currentTimeMillis?.() ?? "millis()";
+    const now = strategy?.currentTimeMillis?.() ?? "__tc_now_ms()";
     const requiredIncludes = ["<functional>", "<vector>", "<utility>", "<string>"];
     if (now.includes("std::chrono"))
         requiredIncludes.push("<chrono>");

package/dist/platform/coop-scheduler-runtime.js

@@ -14,14 +14,14 @@ import { generateCoopScheduler } from "../api/shared/index.js";
  * links on minimal-libc targets (Zephyr) where the std::function Promise
  * runtime does not.
  */
-export function buildCoopSchedulerPolyfill(_program, config, currentTimeExpr = "millis()") {
+export function buildCoopSchedulerPolyfill(_program, config, currentTimeExpr = "__tc_now_ms()") {
     if (!config.enablePriority && !config.enableTimeBudget)
         return null;
     return {
         kind: "polyfill",
         id: "coop_scheduler",
         domain: "embedded",
-        // STL-free: only needs a 32-bit unsigned time source (millis() /
+        // STL-free: only needs a 32-bit unsigned time source (__tc_now_ms() /
         // k_uptime_get_32()) and fixed-width types, both available everywhere.
         requiredIncludes: [],
         forwardDeclarations: [],

package/dist/platform/generic-debug-codegen.d.ts

@@ -0,0 +1,36 @@
+export interface CapturedVariable {
+    name: string;
+    isFunction?: boolean;
+    /** Coarse C++ type category (inferred by the preprocessor without a checker). */
+    cppType?: 'bool' | 'int' | 'long' | 'float' | 'string' | 'unknown';
+}
+export interface LogMessagePart {
+    type: 'text' | 'variable';
+    value: string;
+}
+/**
+ * Generate the debug-mode banner. The host console needs no setup, but the
+ * printf/getchar calls below need <cstdio>: include() registers it on the
+ * program (the generic strategy's forcedIncludes is deliberately empty), and
+ * the strategy-side usesCstdio gates (e.g. native) also pick the banner up
+ * from the rawCpp text.
+ */
+export declare function generateGenericInitCode(): string[];
+/**
+ * Generate generic/native code for a breakpoint.
+ *
+ * The halt reads stdin until ENTER; any 's' typed before it marks this
+ * breakpoint skipped for the rest of the run. The flag is a C++ static local
+ * inside the emitted block (safe here — unlike TS-injected declarations, the
+ * rawCpp text bypasses the TS parser entirely), so the skip persists across
+ * loop() iterations. EOF on stdin exits the halt instead of spinning.
+ *
+ * When `breakpointId` is set the whole block is guarded by that flag; the
+ * preprocessor assigns ids to every halting breakpoint.
+ */
+export declare function generateGenericBreakpointCode(fileName: string, lineNum: number, originalLine: string, variables: CapturedVariable[], normalizedCondition: string | undefined, breakpointId?: number): string[];
+/**
+ * Generate generic/native code for a logpoint (logs a message without
+ * halting). Each part is its own printf, then a newline.
+ */
+export declare function generateGenericLogpointCode(fileName: string, lineNum: number, parts: LogMessagePart[], variables: CapturedVariable[]): string[];

package/dist/platform/generic-debug-codegen.js

@@ -0,0 +1,185 @@
+// ---------------------------------------------------------------------------
+// Generic/native debug code generator — printf-based debug output
+//
+// The debug preprocessor injects these lines into the user's TypeScript, so
+// every injected line must be TS-parseable AND lower faithfully. Raw C++ in
+// an injected line does not survive: the TS parser reads `std::cout << ...`
+// as a label plus garbage, and the emitted C++ was `std: :` noise that could
+// never compile. Every line therefore rides the rawCpp() passthrough — the
+// call lowers to __EMIT__ and its string argument is emitted as verbatim
+// C++ — so the generator can author arbitrary C++ (printf, static_cast,
+// the static skip flag) without the TS parser ever seeing it.
+//
+// printf/getchar need <cstdio>: program-analysis marks usesCstdio from
+// __EMIT__ string arguments, and the native/generic forcedIncludes gate
+// <cstdio> on that flag.
+//
+// Used by GenericStrategy's generateDebug* overrides (the debug preprocessor
+// falls back to GenericStrategy for every framework whose strategy does not
+// define its own codegen — e.g. @typecad/framework-native). The Zephyr
+// counterpart is framework-zephyr/src/debug-codegen.ts (printk + a shim-side
+// halt). Dispatched by cuttlefish/src/debug/preprocessor.ts.
+// ---------------------------------------------------------------------------
+import { escapeCppStringLiteral } from "../utils/strings.js";
+/**
+ * Wrap a C++ text fragment as an injectable TS statement. The rawCpp() call
+ * lowers to __EMIT__, whose string argument the emitter writes out verbatim
+ * (a trailing `;` is added by the emitter when the fragment lacks one).
+ * JSON.stringify produces a valid single-line TS double-quoted literal for
+ * any fragment, newlines included.
+ */
+function raw(cpp) {
+    return `rawCpp(${JSON.stringify(cpp)});`;
+}
+/** printf a string literal. */
+function printLiteral(text, indent) {
+    return raw(`${indent}printf("%s", "${escapeCppStringLiteral(text)}");`);
+}
+/**
+ * Generate the debug-mode banner. The host console needs no setup, but the
+ * printf/getchar calls below need <cstdio>: include() registers it on the
+ * program (the generic strategy's forcedIncludes is deliberately empty), and
+ * the strategy-side usesCstdio gates (e.g. native) also pick the banner up
+ * from the rawCpp text.
+ */
+export function generateGenericInitCode() {
+    return [
+        '// === DEBUG: host console (printf) ===',
+        "include('<cstdio>');",
+        raw('printf("[TypeCAD] Debug Mode Active\\n");'),
+        '// === END DEBUG INIT ===',
+        '',
+    ];
+}
+/**
+ * Generate generic/native code for a breakpoint.
+ *
+ * The halt reads stdin until ENTER; any 's' typed before it marks this
+ * breakpoint skipped for the rest of the run. The flag is a C++ static local
+ * inside the emitted block (safe here — unlike TS-injected declarations, the
+ * rawCpp text bypasses the TS parser entirely), so the skip persists across
+ * loop() iterations. EOF on stdin exits the halt instead of spinning.
+ *
+ * When `breakpointId` is set the whole block is guarded by that flag; the
+ * preprocessor assigns ids to every halting breakpoint.
+ */
+export function generateGenericBreakpointCode(fileName, lineNum, originalLine, variables, normalizedCondition, breakpointId) {
+    const lines = [];
+    const indent = '  ' + (normalizedCondition ? '  ' : '');
+    lines.push(`  // === BREAKPOINT: ${fileName}:${lineNum} ===`);
+    if (normalizedCondition) {
+        lines.push(`  if (${normalizedCondition}) {`);
+    }
+    // The whole breakpoint is one rawCpp block: a braced C++ compound
+    // statement. The emitter only appends a `;` when the fragment lacks one,
+    // so a block ending in `}` is written out verbatim.
+    const flag = breakpointId !== undefined ? `__tc_bp${breakpointId}_skipped` : undefined;
+    const b = ['{'];
+    const inner = flag ? '  ' : '';
+    if (flag) {
+        b.push(`  static bool ${flag} = false;`);
+        b.push(`  if (!${flag}) {`);
+    }
+    b.push(`${inner}printf("----------------------------------------\\n");`);
+    const headerText = normalizedCondition
+        ? `[BREAK] ${fileName}:${lineNum} (condition: ${escapeCppStringLiteral(normalizedCondition)})`
+        : `[BREAK] ${fileName}:${lineNum}`;
+    b.push(`${inner}printf("%s\\n", "${escapeCppStringLiteral(headerText)}");`);
+    b.push(`${inner}printf("  %s\\n", "${escapeCppStringLiteral(originalLine)}");`);
+    if (variables.length > 0) {
+        b.push(`${inner}printf("  Variables:\\n");`);
+        for (const v of variables) {
+            if (v.isFunction) {
+                b.push(`${inner}printf("  - %s = [function]\\n", "${escapeCppStringLiteral(v.name)}");`);
+            }
+            else {
+                const { spec, arg } = formatSpecFor(v.name, v.cppType);
+                b.push(`${inner}printf("  - %s = ${spec}\\n", "${escapeCppStringLiteral(v.name)}", ${arg});`);
+            }
+        }
+    }
+    else {
+        b.push(`${inner}printf("  (no variables in scope)\\n");`);
+    }
+    b.push(`${inner}printf("  [ENTER: continue | s: skip this breakpoint]\\n");`);
+    b.push(`${inner}int __tc_c;`);
+    if (flag) {
+        b.push(`${inner}do {`);
+        b.push(`${inner}  __tc_c = getchar();`);
+        b.push(`${inner}  if (__tc_c == 's') { ${flag} = true; }`);
+        b.push(`${inner}} while (__tc_c != '\\n' && __tc_c != EOF);`);
+    }
+    else {
+        b.push(`${inner}do {`);
+        b.push(`${inner}  __tc_c = getchar();`);
+        b.push(`${inner}} while (__tc_c != '\\n' && __tc_c != EOF);`);
+    }
+    if (flag) {
+        b.push('  }');
+    }
+    b.push('}');
+    lines.push(indent + raw(b.join('\n')));
+    if (normalizedCondition) {
+        lines.push(`  }`);
+    }
+    lines.push(`  // === END BREAKPOINT ===`);
+    return lines;
+}
+/**
+ * Generate generic/native code for a logpoint (logs a message without
+ * halting). Each part is its own printf, then a newline.
+ */
+export function generateGenericLogpointCode(fileName, lineNum, parts, variables) {
+    const lines = [];
+    lines.push(`  // === LOGPOINT: ${fileName}:${lineNum} ===`);
+    lines.push(raw(`  printf("%s", "${escapeCppStringLiteral(`[LOG ${fileName}:${lineNum}] `)}");`));
+    for (const part of parts) {
+        if (part.type === 'text') {
+            lines.push(raw(`  printf("%s", "${escapeCppStringLiteral(part.value)}");`));
+        }
+        else {
+            // Variable part: only printable if it is a non-function value in scope.
+            const match = variables.find((v) => v.name === part.value && !v.isFunction);
+            if (match) {
+                const { spec, arg } = formatSpecFor(match.name, match.cppType);
+                lines.push(raw(`  printf("${spec}", ${arg});`));
+            }
+            else {
+                lines.push(raw(`  printf("%s", "{${escapeCppStringLiteral(part.value)}}"); // variable not in scope`));
+            }
+        }
+    }
+    lines.push(raw(`  printf("\\n");`));
+    lines.push(`  // === END LOGPOINT ===`);
+    return lines;
+}
+/**
+ * Pick a printf format specifier + argument expression for a debug variable.
+ *
+ * The debug preprocessor has no TypeChecker, so `cppType` is a coarse
+ * category inferred from AST shape. Native/generic mappings:
+ *   - bool        → %d via static_cast<int>
+ *   - int/long    → %lld via static_cast<long long> (native `number` is long
+ *                   long; int32_t widens into the same cast)
+ *   - float       → %g via static_cast<double> (float literal widens)
+ *   - string      → %s via .c_str() (native strings are std::string)
+ *   - unknown     → %g via static_cast<double>, the documented fallback that
+ *                   compiles for any numeric/bool variable.
+ */
+function formatSpecFor(varName, cppType) {
+    switch (cppType) {
+        case 'bool':
+            return { spec: '%d', arg: `static_cast<int>(${varName})` };
+        case 'int':
+        case 'long':
+            return { spec: '%lld', arg: `static_cast<long long>(${varName})` };
+        case 'float':
+            return { spec: '%g', arg: `static_cast<double>(${varName})` };
+        case 'string':
+            return { spec: '%s', arg: `${varName}.c_str()` };
+        case 'unknown':
+        default:
+            // Cast to double so printf compiles regardless of the real C++ type.
+            return { spec: '%g', arg: `static_cast<double>(${varName})` };
+    }
+}

package/dist/platform/generic-strategy.d.ts

@@ -34,9 +34,6 @@ export declare class GenericStrategy implements PlatformStrategy {
     enumCastType(enumName: string): string | undefined;
     renderBoardDefinitionAccess(_chain: string[], _boardConstants?: BoardConstants): string | undefined;
     renderThrow(valueExpr: string): string;
-    isConsoleCall(callee: string): boolean;
-    transformConsoleCall(method: string, renderedArgs: string, forHeader: boolean): string;
-    transformConsoleExpression(method: string, _renderedArgs: string): string | undefined;
     objectFieldInitializer(_fieldValue: ExpressionIR, _renderExpr: (e: ExpressionIR) => string): string | undefined;
     overrideClassFieldType(_fieldName: string, _normalizedType: string): string;
     reservedNames(): ReadonlySet<string>;
@@ -50,7 +47,6 @@ export declare class GenericStrategy implements PlatformStrategy {
     needsStdFunction(): boolean;
     mathHeader(): string;
     cstringHeader(): string;
-    needsVectorOverload(): boolean;
     needsLargeEnumUnderlying(): boolean;
     renameStructField(fieldName: string): string;
     structFieldInitializer(_fieldValue: ExpressionIR, _compiletimeVarNames: Set<string>, _renderExpr: (e: ExpressionIR) => string): string | undefined;
@@ -79,8 +75,10 @@ export declare class GenericStrategy implements PlatformStrategy {
         variables: Array<{
             name: string;
             isFunction?: boolean;
+            cppType?: 'bool' | 'int' | 'long' | 'float' | 'string' | 'unknown';
         }>;
         normalizedCondition?: string;
+        breakpointId?: number;
     }): string[];
     generateDebugLogpointCode(params: {
         fileName: string;
@@ -92,6 +90,7 @@ export declare class GenericStrategy implements PlatformStrategy {
         variables: Array<{
             name: string;
             isFunction?: boolean;
+            cppType?: 'bool' | 'int' | 'long' | 'float' | 'string' | 'unknown';
         }>;
     }): string[];
     resolveDisplayOp(_op: DisplayHALOp): {

package/dist/platform/generic-strategy.js

@@ -1,7 +1,7 @@
 // ---------------------------------------------------------------------------
-// GenericStrategy — standard C++ target (std::cout, main(), <cmath> …)
+// GenericStrategy — standard C++ target (main(), <cmath> …)
 // ---------------------------------------------------------------------------
-import { escapeCppStringLiteral } from "../utils/strings.js";
+import { generateGenericInitCode, generateGenericBreakpointCode, generateGenericLogpointCode } from "./generic-debug-codegen.js";
 import { DEFAULT_STDLIB_SUPPORT } from "../api/shared/index.js";
 import { parsedIsPointer } from "../api/shared/cpp-type-ir.js";
 import { buildAsyncRuntimePolyfill } from "./async-runtime.js";
@@ -105,37 +105,6 @@ export class GenericStrategy {
     renderThrow(valueExpr) {
         return `throw ${valueExpr};`;
     }
-    isConsoleCall(callee) {
-        return callee.startsWith("console.");
-    }
-    transformConsoleCall(method, renderedArgs, forHeader) {
-        const semi = forHeader ? "" : ";";
-        switch (method) {
-            case "log":
-            case "info":
-            case "debug":
-                return `std::cout << ${renderedArgs} << std::endl${semi}`;
-            case "error":
-                return `std::cerr << "[ERROR] " << ${renderedArgs} << std::endl${semi}`;
-            case "warn":
-                return `std::cerr << "[WARN] " << ${renderedArgs} << std::endl${semi}`;
-            case "readLine":
-            case "readCharacter":
-                return this.transformConsoleExpression(method, renderedArgs) + semi;
-            default:
-                return `std::cout << ${renderedArgs} << std::endl${semi}`;
-        }
-    }
-    transformConsoleExpression(method, _renderedArgs) {
-        switch (method) {
-            case 'readLine':
-                return '([]() -> std::string { std::string s; std::getline(std::cin, s); return s; })()';
-            case 'readCharacter':
-                return '([&]() -> char { std::cout << "> " << std::flush; return std::cin.get(); })()';
-            default:
-                return undefined;
-        }
-    }
     objectFieldInitializer(_fieldValue, _renderExpr) {
         return undefined;
     }
@@ -163,7 +132,6 @@ export class GenericStrategy {
     needsStdFunction() { return true; }
     mathHeader() { return "<cmath>"; }
     cstringHeader() { return "<cstring>"; }
-    needsVectorOverload() { return true; }
     // ── Enum underlying type ────────────────────────────────────────────────
     needsLargeEnumUnderlying() { return false; }
     // ── Struct field handling ───────────────────────────────────────────────
@@ -227,56 +195,13 @@ export class GenericStrategy {
         return 'printf';
     }
     generateDebugInitCode() {
-        return [
-            '// === DEBUG: Initialize ===',
-            'std::cout << "TypeCAD Debug Mode Active" << std::endl;',
-            '// === END DEBUG INIT ===',
-            '',
-        ];
+        return generateGenericInitCode();
     }
     generateDebugBreakpointCode(params) {
-        const lines = [];
-        lines.push(`  // === BREAKPOINT: ${params.fileName}:${params.lineNum} ===`);
-        if (params.normalizedCondition) {
-            lines.push(`  if (${params.normalizedCondition}) {`);
-        }
-        lines.push(`  ${params.normalizedCondition ? '  ' : ''}std::cout << "━━━━━━━━━━━━━━━━━━━━━━━━━━━━" << std::endl;`);
-        lines.push(`  ${params.normalizedCondition ? '  ' : ''}std::cout << "BREAKPOINT: ${params.fileName}:${params.lineNum}" << std::endl;`);
-        lines.push(`  ${params.normalizedCondition ? '  ' : ''}std::cout << "  ${params.originalLine.replace(/"/g, '\\"')}" << std::endl;`);
-        if (params.variables.length > 0) {
-            lines.push(`  ${params.normalizedCondition ? '  ' : ''}std::cout << "  Variables:" << std::endl;`);
-            for (const v of params.variables) {
-                if (v.isFunction) {
-                    lines.push(`  ${params.normalizedCondition ? '  ' : ''}std::cout << "  ${v.name} = [function]" << std::endl;`);
-                }
-                else {
-                    lines.push(`  ${params.normalizedCondition ? '  ' : ''}std::cout << "  ${v.name} = " << ${v.name} << std::endl;`);
-                }
-            }
-        }
-        lines.push(`  ${params.normalizedCondition ? '  ' : ''}std::cout << "━━━━━━━━━━━━━━━━━━━━━━━━━━━━" << std::endl;`);
-        if (params.normalizedCondition) {
-            lines.push(`  }`);
-        }
-        lines.push(`  // === END BREAKPOINT ===`);
-        return lines;
+        return generateGenericBreakpointCode(params.fileName, params.lineNum, params.originalLine, params.variables, params.normalizedCondition, params.breakpointId);
     }
     generateDebugLogpointCode(params) {
-        const lines = [];
-        lines.push(`  // === LOGPOINT: ${params.fileName}:${params.lineNum} ===`);
-        const parts = [`"[LOG ${params.fileName}:${params.lineNum}] "`];
-        for (const part of params.parts) {
-            if (part.type === 'text') {
-                parts.push(`"${escapeCppStringLiteral(part.value)}"`);
-            }
-            else {
-                const varExists = params.variables.some(v => v.name === part.value && !v.isFunction);
-                parts.push(varExists ? part.value : `"${escapeCppStringLiteral(part.value)}"`);
-            }
-        }
-        lines.push(`  std::cout << ${parts.join(' << ')} << std::endl;`);
-        lines.push(`  // === END LOGPOINT ===`);
-        return lines;
+        return generateGenericLogpointCode(params.fileName, params.lineNum, params.parts, params.variables);
     }
     // ── Graphics (fallback) ────────────────────────────────────────────────
     resolveDisplayOp(_op) {

package/dist/platform/index.js

@@ -2,7 +2,7 @@
 // Platform strategy exports
 //
 // Re-exports platform strategies for use within the CLI and by consumers.
-// Framework-specific strategies (e.g. ArduinoStrategy) are provided by their
+// Framework-specific strategies (e.g. ZephyrStrategy) are provided by their
 // respective framework packages, which register via registerPlatformStrategy().
 // ---------------------------------------------------------------------------
 export { GenericStrategy } from './generic-strategy.js';

package/dist/platform/registry.d.ts

@@ -4,9 +4,9 @@ import type { PlatformStrategy } from "../api/shared/index.js";
  * their entry point to override the default strategy for a target.
  *
  * @example
- * // In @typecad/framework-arduino
+ * // In @typecad/framework-zephyr
  * import { registerPlatformStrategy } from "@typecad/cuttlefish/platform/registry";
- * registerPlatformStrategy(new ArduinoStrategy());
+ * registerPlatformStrategy(new ZephyrStrategy());
  */
 export declare function registerPlatformStrategy(strategy: PlatformStrategy): void;
 /**

package/dist/platform/registry.js

@@ -15,9 +15,9 @@ const _registry = new Map([
  * their entry point to override the default strategy for a target.
  *
  * @example
- * // In @typecad/framework-arduino
+ * // In @typecad/framework-zephyr
  * import { registerPlatformStrategy } from "@typecad/cuttlefish/platform/registry";
- * registerPlatformStrategy(new ArduinoStrategy());
+ * registerPlatformStrategy(new ZephyrStrategy());
  */
 export function registerPlatformStrategy(strategy) {
     _registry.set(strategy.id, strategy);

package/dist/preview/client.js

@@ -8,6 +8,9 @@ let pendingPointerFrame = 0;
 let debugModes = { boxes: false, clips: false, dirty: false, inspect: false };
 let debugOverlay;
 let debugCtx;
+/** Re-syncs the overlay to the app canvas whenever layout changes its box
+ *  (aspect-ratio application, max-height, container reflow). */
+let overlayResizeObserver;
 let dirtyFlashAlpha = 0;
 /** CSS px per logical display px — the overlay backing store runs at this
  *  resolution so debug strokes are 1 CSS px thin (a 1-logical-px stroke on
@@ -263,11 +266,22 @@ async function start() {
         debugOverlay.height = Math.max(1, Math.round(rect.height * dpr));
         debugScale = (rect.width * dpr) / snapshot.program.width;
     };
-    syncOverlayBox();
-    window.addEventListener("resize", syncOverlayBox);
     // Set the canvas CSS aspect-ratio to match the display (e.g. 128:64 for
-    // OLED, 320:240 for TFT) so the browser scales it proportionally.
+    // OLED, 320:240 for TFT) BEFORE syncing the overlay: the canvas is
+    // vertically centered (place-items: center), so applying the real aspect
+    // after the sync SHRANK it and moved it DOWN — the overlay stayed at the
+    // old 4/3-fallback position and every debug box sat that far above its
+    // element. A ResizeObserver re-syncs on any later layout-driven size
+    // change (max-height kicking in, container reflow), not just window
+    // resizes.
     document.documentElement.style.setProperty("--display-aspect", `${snapshot.program.width} / ${snapshot.program.height}`);
+    syncOverlayBox();
+    window.addEventListener("resize", syncOverlayBox);
+    if (typeof ResizeObserver !== "undefined") {
+        overlayResizeObserver?.disconnect();
+        overlayResizeObserver = new ResizeObserver(() => syncOverlayBox());
+        overlayResizeObserver.observe(canvas);
+    }
     const status = byId("status");
     status.textContent = `${snapshot.profileName ?? snapshot.program.display?.driver ?? "display"} ${snapshot.program.width}x${snapshot.program.height} ${snapshot.program.colorFormat}`;
     const extraDiagnostics = [];

package/dist/safety/asil-decorators.d.ts

@@ -0,0 +1,32 @@
+export {};
+/** ASIL level annotations for functions — comment-based.
+ *
+ *  ASIL levels are declared via leading comment annotations rather than
+ *  TypeScript decorators because:
+ *  - TS decorators on function declarations produce TS1206 errors in the
+ *    VS Code language server and @typescript-eslint/parser
+ *  - Comment annotations work in any editor, any toolchain, without
+ *    `experimentalDecorators` or special config
+ *
+ *  The cuttlefish IR builder extracts these from leading comments via
+ *  extractAsilFromComments() in function-builder.ts.
+ *
+ *  Part B's ISO 26262 checkers (analyzeIR) read the resulting `decorators`
+ *  field on FunctionIR to decide which rules to enforce:
+ *
+ *    // @asilD → all rules enforced (recursion, heap, loops)
+ *    // @asilC → recursion + loops enforced (heap is ASIL D only)
+ *    // @asilB → recursion enforced
+ *    // @asilA → no rules enforced (quality-managed)
+ *    (no annotation) → no rules enforced (implicit QM)
+ *
+ *  Usage:
+ *    // @asilD
+ *    function engageBrake(): void {
+ *      safe.write(brakePin, 1);
+ *    }
+ *
+ *  These are documentation-only exports — they have no runtime behavior
+ *  and are never imported by user code. They exist so the ASIL level
+ *  names appear in type hints and IDE autocomplete.
+ */