@typecad/cuttlefish 1.0.0-alpha.14 → 1.0.0-alpha.16

package/dist/libdef/cpp-to-decl.js

@@ -8,7 +8,6 @@ import fs from "node:fs";
 import path from "node:path";
 import { parseHeader } from "./header-parser.js";
 import { buildClassIndex, BaseClassResolver } from "./base-class-resolver.js";
-import { writeText } from "../utils/fs.js";
 /**
  * Maps C++ types to TypeScript types
  */
@@ -583,74 +582,3 @@ function generateDeclWithResolver(filePath, resolver) {
     }
     return outPath;
 }
-// ─── ESP-IDF component dispatch ───────────────────────────────────────────
-//
-// Picks the C or C++ emitter per header based on whether it declares classes.
-// ESP-IDF components are mostly C (free functions + typedefs); Arduino-style
-// libraries are C++ classes. Spec:
-// docs/superpowers/specs/2026-07-19-framework-esp32-components-design.md
-import { generateCDecl } from "./c-to-decl.js";
-import { discoverComponentHeaders } from "./component-discovery.js";
-/** Heuristic: does this header declare any C++ classes? */
-function hasClasses(headerPath) {
-    try {
-        const content = fs.readFileSync(headerPath, "utf8");
-        return parseHeader(content).length > 0;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Generate .d.ts declarations for every declared component's headers,
- * picking the C or C++ emitter per header based on whether it declares classes.
- *
- * Returns the list of created/updated .d.ts paths (headers that produced no
- * declarations are skipped).
- */
-export function generateComponentDeclsForProject(projectDir, roots) {
-    const headers = discoverComponentHeaders(projectDir, roots);
-    const created = [];
-    for (const discovered of headers) {
-        // Output path: <outputDir>/<basename>.d.ts. For managed/local this is
-        // alongside the header; for builtins it's the project-local cache dir.
-        const baseName = path.basename(discovered.path).replace(/\.h$/i, '');
-        const outputPath = path.join(discovered.outputDir, baseName + '.d.ts');
-        const out = hasClasses(discovered.path)
-            ? generateDecl(discovered.path, outputPath)
-            : generateCDecl(discovered.path, outputPath);
-        if (out) {
-            created.push(out);
-            // Write a sibling .libdef.json so the import → #include resolver picks
-            // up the real (case-preserving) header name. Without this, the resolver
-            // falls back to toPascalCase(moduleKey) + ".h" — fine for Arduino libs
-            // (Adafruit_GFX → Adafruit_GFX.h, resolved separately) but wrong for
-            // ESP-IDF component headers (esp_wifi → <EspWifi.h>, not <esp_wifi.h>).
-            // The libdef declares the actual header basename ("esp_wifi.h"), which
-            // is the ground truth — the generator just read the file.
-            writeComponentLibdef(discovered.path, outputPath);
-        }
-    }
-    return created;
-}
-/**
- * Write `<d.ts-basename>.libdef.json` next to a generated component `.d.ts`,
- * pointing the import → #include resolver at the actual source header.
- *
- * The libdef `module` field is the lowercased basename (matches what
- * `toModuleKey()` produces from an import specifier), and `include` is the
- * case-preserving `<basename>.h` — quote-wrapped because component headers
- * are project-local (resolved via the include path), not system angle-bracket
- * includes. Matches the local-header convention in `resolveLocalModuleHeader`.
- */
-function writeComponentLibdef(sourceHeaderPath, dtsOutputPath) {
-    const headerBaseName = path.basename(sourceHeaderPath); // e.g. "esp_wifi.h"
-    const dtsBaseName = path.basename(dtsOutputPath, '.d.ts'); // e.g. "esp_wifi"
-    const libdefPath = path.join(path.dirname(dtsOutputPath), `${dtsBaseName}.libdef.json`);
-    const libdef = {
-        module: dtsBaseName.toLowerCase(),
-        include: `"${headerBaseName}"`,
-        source: sourceHeaderPath,
-    };
-    writeText(libdefPath, JSON.stringify(libdef, null, 2) + '\n');
-}

package/dist/libdef/registry.d.ts

@@ -6,5 +6,4 @@ interface ResolvedImport {
 }
 export declare function loadLibraryDefinitions(definitionsDir: string): Map<string, LibraryDefinition>;
 export declare function resolveImport(importNode: ImportIR, definitions: Map<string, LibraryDefinition>, target: TargetProfile, platformContext?: PlatformContext, importerFilePath?: string): ResolvedImport;
-export declare function generateLibdefStubs(inputFile: string, imports: ImportIR[], outDir: string): string[];
 export {};

package/dist/libdef/registry.js

@@ -22,8 +22,7 @@ function getLibraryResolver() {
 export function loadLibraryDefinitions(definitionsDir) {
     const registry = new Map();
     // Recursive scan: libdefs may live at the entry dir (single-level convention)
-    // or nested under cache trees like `.cuttlefish/component-decls/<component>/`
-    // (per-component overrides generated alongside .d.ts stubs).
+    // or nested in project subdirectories (per-module overrides).
     const files = listFilesRecursive(definitionsDir, ".libdef.json");
     for (const filePath of files) {
         let def;
@@ -121,25 +120,3 @@ export function resolveImport(importNode, definitions, target, platformContext,
         },
     };
 }
-export function generateLibdefStubs(inputFile, imports, outDir) {
-    const created = [];
-    if (!fs.existsSync(outDir)) {
-        fs.mkdirSync(outDir, { recursive: true });
-    }
-    for (const item of imports) {
-        const moduleKey = toModuleKey(item.moduleSpecifier);
-        const libdefPath = path.join(outDir, `${moduleKey}.libdef.json`);
-        if (!fs.existsSync(libdefPath)) {
-            const include = `<${toPascalCase(moduleKey)}.h>`;
-            const libdefContent = {
-                module: moduleKey,
-                include,
-                symbols: Object.fromEntries(item.namedImports.map((symbol) => [symbol, symbol])),
-                source: inputFile,
-            };
-            fs.writeFileSync(libdefPath, JSON.stringify(libdefContent, null, 2) + "\n", "utf8");
-            created.push(libdefPath);
-        }
-    }
-    return created;
-}

package/dist/library/init.d.ts

@@ -1,7 +1,7 @@
 export interface LibraryInitOptions {
     /** Full package name (e.g. '@acme/esp32-led-ring' or 'my-lib'). */
     name?: string;
-    /** Framework id from FRAMEWORK_CATALOG ('zephyr', 'arduino', ...). */
+    /** Framework id from FRAMEWORK_CATALOG ('zephyr', 'native', ...). */
     framework?: string;
     /** Category id from LIBRARY_CATEGORIES. */
     category?: string;

package/dist/library/init.js

@@ -124,38 +124,38 @@ function renderTsconfig() {
     }, null, 2) + "\n";
 }
 function renderApi(m) {
-    return `// ---------------------------------------------------------------------------
-// ${m.packageName} — cuttlefish library package (${m.category.label.toLowerCase()}).
-//
-// This file is the typed API contract: it is never executed. The cuttlefish
-// transpiler lowers the import to the shim header (shims/__tc_${m.tokenBase}.h),
-// and calls on the exported instance render verbatim into the generated C++.
-// Two rules keep that contract intact:
-//
-//   1. Method names are load-bearing. The C++ class in the shim must define
-//      exactly these names — 'rgbLed'-style call sites appear in the C++ as-is.
-//   2. Export a singleton instance, not a constructor. A bare 'new' in user
-//      code renders as a C++ heap allocation, which the AUTOSAR C++14 rules
-//      the shims follow forbid.
-// ---------------------------------------------------------------------------
-
-/**
- * ${m.category.description} (${m.category.examples}).
- */
-export class ${m.className} {
-  /**
-   * Prepare the hardware. Call once from setup(). The stub in the shim is a
-   * no-op — replace it with your initialization code.
-   */
-  begin(): this {
-    return this;
-  }
-
-  // Add your API here. Every method needs a matching member on the C++ class.
-}
-
-/** The instance to use — a preconstructed singleton (see rule 2 above). */
-export const ${m.instanceName}: ${m.className} = new ${m.className}();
+    return `// ---------------------------------------------------------------------------
+// ${m.packageName} — cuttlefish library package (${m.category.label.toLowerCase()}).
+//
+// This file is the typed API contract: it is never executed. The cuttlefish
+// transpiler lowers the import to the shim header (shims/__tc_${m.tokenBase}.h),
+// and calls on the exported instance render verbatim into the generated C++.
+// Two rules keep that contract intact:
+//
+//   1. Method names are load-bearing. The C++ class in the shim must define
+//      exactly these names — 'rgbLed'-style call sites appear in the C++ as-is.
+//   2. Export a singleton instance, not a constructor. A bare 'new' in user
+//      code renders as a C++ heap allocation, which the AUTOSAR C++14 rules
+//      the shims follow forbid.
+// ---------------------------------------------------------------------------
+
+/**
+ * ${m.category.description} (${m.category.examples}).
+ */
+export class ${m.className} {
+  /**
+   * Prepare the hardware. Call once from setup(). The stub in the shim is a
+   * no-op — replace it with your initialization code.
+   */
+  begin(): this {
+    return this;
+  }
+
+  // Add your API here. Every method needs a matching member on the C++ class.
+}
+
+/** The instance to use — a preconstructed singleton (see rule 2 above). */
+export const ${m.instanceName}: ${m.className} = new ${m.className}();
 `;
 }
 function renderManifest(m) {
@@ -180,123 +180,123 @@ function renderManifest(m) {
     return JSON.stringify(manifest, null, 2) + "\n";
 }
 function renderShimHeader(m) {
-    return `// ---------------------------------------------------------------------------
-// __tc_${m.tokenBase}.h — ${m.packageName} shim.
-//
-// The implementation behind the TypeScript API in src/index.ts. Calls on the
-// exported instance render verbatim, so the class name, the instance name,
-// and the method names must match src/index.ts exactly.
-//
-// AUTOSAR C++14 by construction: fixed-width integers, static_cast only (no
-// C-style casts), no heap, 'final' on the leaf class. The generated
-// application's compliance check runs over these bytes.
-// ---------------------------------------------------------------------------
-
-#ifndef TC_${m.tokenBase.toUpperCase()}_H_
-#define TC_${m.tokenBase.toUpperCase()}_H_
-
-#include <cstdint>
-${m.isZephyr ? "#include <zephyr/kernel.h>\n" : ""}class ${m.className} final
-{
-public:
-  ${m.className}& begin();
-
-private:
-  bool initialized_ = false;
-};
-
-extern ${m.className} ${m.instanceName};
-
-#endif  // TC_${m.tokenBase.toUpperCase()}_H_
+    return `// ---------------------------------------------------------------------------
+// __tc_${m.tokenBase}.h — ${m.packageName} shim.
+//
+// The implementation behind the TypeScript API in src/index.ts. Calls on the
+// exported instance render verbatim, so the class name, the instance name,
+// and the method names must match src/index.ts exactly.
+//
+// AUTOSAR C++14 by construction: fixed-width integers, static_cast only (no
+// C-style casts), no heap, 'final' on the leaf class. The generated
+// application's compliance check runs over these bytes.
+// ---------------------------------------------------------------------------
+
+#ifndef TC_${m.tokenBase.toUpperCase()}_H_
+#define TC_${m.tokenBase.toUpperCase()}_H_
+
+#include <cstdint>
+${m.isZephyr ? "#include <zephyr/kernel.h>\n" : ""}class ${m.className} final
+{
+public:
+  ${m.className}& begin();
+
+private:
+  bool initialized_ = false;
+};
+
+extern ${m.className} ${m.instanceName};
+
+#endif  // TC_${m.tokenBase.toUpperCase()}_H_
 `;
 }
 function renderShimSource(m) {
-    return `// ---------------------------------------------------------------------------
-// __tc_${m.tokenBase}.cpp — ${m.packageName} shim implementation.
-// See __tc_${m.tokenBase}.h for the contract. AUTOSAR C++14 compliant.
-// ---------------------------------------------------------------------------
-
-#include "__tc_${m.tokenBase}.h"
-
-${m.className}& ${m.className}::begin()
-{
-  initialized_ = true;
-  return *this;
-}
-
-${m.className} ${m.instanceName};
+    return `// ---------------------------------------------------------------------------
+// __tc_${m.tokenBase}.cpp — ${m.packageName} shim implementation.
+// See __tc_${m.tokenBase}.h for the contract. AUTOSAR C++14 compliant.
+// ---------------------------------------------------------------------------
+
+#include "__tc_${m.tokenBase}.h"
+
+${m.className}& ${m.className}::begin()
+{
+  initialized_ = true;
+  return *this;
+}
+
+${m.className} ${m.instanceName};
 `;
 }
 function renderOverlay(m) {
-    return `/*
- * ${m.id} — devicetree overlay fragment (${m.category.label.toLowerCase()}).
- *
- * Appended to the generated boards/<board>.overlay when this library's import
- * is used. Describe the hardware here: controllers, pins, binding properties.
- * When upstream Zephyr ships a sample overlay for your part, adapt it and
- * credit it in a comment.
- */
-
-/ {
-\t/* aliases { your-alias = &your_node; }; */
-};
+    return `/*
+ * ${m.id} — devicetree overlay fragment (${m.category.label.toLowerCase()}).
+ *
+ * Appended to the generated boards/<board>.overlay when this library's import
+ * is used. Describe the hardware here: controllers, pins, binding properties.
+ * When upstream Zephyr ships a sample overlay for your part, adapt it and
+ * credit it in a comment.
+ */
+
+/ {
+\t/* aliases { your-alias = &your_node; }; */
+};
 `;
 }
 function renderReadme(m) {
-    return `# ${m.packageName}
-
-A cuttlefish library package — ${m.category.label.toLowerCase()} (${m.category.description}),
-for the **${m.framework}** framework${m.targets.length > 0 ? ` (targets: ${m.targets.join(", ")})` : ""}.
-
-## Use it
-
-\`\`\`ts
-import { ${m.instanceName} } from '${m.packageName}';
-
-${m.instanceName}.begin();
-\`\`\`
-
-## Carry the hardware facts
-
-This library owns the facts so projects don't have to. Document, in this
-README, everything a user would otherwise hunt through datasheets for:
-
-- which board revisions and targets are supported (and which pins they use),
-- which peripherals the library borrows (say so — a user may want them),
-- wiring requirements (I2C address straps, level shifting, pull-ups).
-
-## Authoring checklist
-
-- Method names in src/index.ts match the C++ shim names exactly; calls render verbatim.
-- Export a singleton instance, not a constructor.
-- Shims pass \`cuttlefish library validate\` (AUTOSAR C++14, strict).
-- \`cuttlefish.library.json\` declares framework${m.isZephyr ? ", kconfig, overlay" : ""} and the shim files.
-- package.json keywords include the marker (\`cuttlefish-library\`) and category (\`cuttlefish-${m.category.id}\`) keywords.
-
-Validate with \`cuttlefish library validate .\` from this directory.
+    return `# ${m.packageName}
+
+A cuttlefish library package — ${m.category.label.toLowerCase()} (${m.category.description}),
+for the **${m.framework}** framework${m.targets.length > 0 ? ` (targets: ${m.targets.join(", ")})` : ""}.
+
+## Use it
+
+\`\`\`ts
+import { ${m.instanceName} } from '${m.packageName}';
+
+${m.instanceName}.begin();
+\`\`\`
+
+## Carry the hardware facts
+
+This library owns the facts so projects don't have to. Document, in this
+README, everything a user would otherwise hunt through datasheets for:
+
+- which board revisions and targets are supported (and which pins they use),
+- which peripherals the library borrows (say so — a user may want them),
+- wiring requirements (I2C address straps, level shifting, pull-ups).
+
+## Authoring checklist
+
+- Method names in src/index.ts match the C++ shim names exactly; calls render verbatim.
+- Export a singleton instance, not a constructor.
+- Shims pass \`cuttlefish library validate\` (AUTOSAR C++14, strict).
+- \`cuttlefish.library.json\` declares framework${m.isZephyr ? ", kconfig, overlay" : ""} and the shim files.
+- package.json keywords include the marker (\`cuttlefish-library\`) and category (\`cuttlefish-${m.category.id}\`) keywords.
+
+Validate with \`cuttlefish library validate .\` from this directory.
 `;
 }
 function renderStarterTest(m) {
-    return `import { describe, it, expect } from "vitest";
-import { readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import { ComplianceContext, runSelfCheck } from "@typecad/cuttlefish/compliance";
-
-// The shipped shim bytes must pass --autosar=strict, exactly like framework
-// shims — the generated application's compliance check runs over them.
-
-const here = dirname(fileURLToPath(import.meta.url));
-
-describe("${m.packageName} shims under --autosar=strict", () => {
-  it("__tc_${m.tokenBase}.h/.cpp produce no unrecorded AUTOSAR violations", () => {
-    const header = readFileSync(join(here, "..", "shims", "__tc_${m.tokenBase}.h"), "utf8").split("\\n");
-    const source = readFileSync(join(here, "..", "shims", "__tc_${m.tokenBase}.cpp"), "utf8").split("\\n");
-    const ctx = new ComplianceContext("strict");
-    const findings = runSelfCheck(ctx, source, header);
-    expect(findings).toEqual([]);
-  });
-});
+    return `import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ComplianceContext, runSelfCheck } from "@typecad/cuttlefish/compliance";
+
+// The shipped shim bytes must pass --autosar=strict, exactly like framework
+// shims — the generated application's compliance check runs over them.
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+describe("${m.packageName} shims under --autosar=strict", () => {
+  it("__tc_${m.tokenBase}.h/.cpp produce no unrecorded AUTOSAR violations", () => {
+    const header = readFileSync(join(here, "..", "shims", "__tc_${m.tokenBase}.h"), "utf8").split("\\n");
+    const source = readFileSync(join(here, "..", "shims", "__tc_${m.tokenBase}.cpp"), "utf8").split("\\n");
+    const ctx = new ComplianceContext("strict");
+    const findings = runSelfCheck(ctx, source, header);
+    expect(findings).toEqual([]);
+  });
+});
 `;
 }
 // ── Scaffolding ─────────────────────────────────────────────────────────────

package/dist/library-packages.d.ts

@@ -79,7 +79,7 @@ export declare function validateCuttlefishLibraries(frameworkId: string, buildTa
  *
  *   1. scan the emitted sources for each library's gate token;
  *   2. write (write-if-changed) the shims of every gated library into the
- *      emitted source directory — the framework scaffold's CMake/sketch
+ *      emitted source directory — the framework scaffold's CMake/program
  *      regen picks the sources up automatically;
  *   3. delete shim files recorded in the previous sidecar that are no longer
  *      used, so removing an import removes its native code;

package/dist/library-packages.js

@@ -212,7 +212,7 @@ function readSidecar(sidecarPath) {
  *
  *   1. scan the emitted sources for each library's gate token;
  *   2. write (write-if-changed) the shims of every gated library into the
- *      emitted source directory — the framework scaffold's CMake/sketch
+ *      emitted source directory — the framework scaffold's CMake/program
  *      regen picks the sources up automatically;
  *   3. delete shim files recorded in the previous sidecar that are no longer
  *      used, so removing an import removes its native code;

package/dist/mapping/peripheral-names.js

@@ -20,14 +20,19 @@ export function mapPeripheralName(name, strategy) {
         if (mapped)
             return mapped;
     }
-    // Default fallbacks if strategy doesn't provide a mapping
+    // Default fallbacks if strategy doesn't provide a mapping: the canonical
+    // TypeCAD controller names. (The Arduino object names — Serial/Wire/SPI —
+    // went with framework-arduino; every live consumer only parses the
+    // trailing controller digit, which the canonical names carry too.)
     const canonical = name.toUpperCase();
     if (canonical === "UART0")
-        return "Serial";
+        return "UART0";
     if (canonical === "I2C0")
-        return "Wire";
+        return "I2C0";
     if (canonical === "SPI0")
-        return "SPI";
+        return "SPI0";
+    if (canonical === "USB0")
+        return "USB0";
     return undefined;
 }
 // ---------------------------------------------------------------------------

package/dist/mapping/source-map.d.ts

@@ -3,12 +3,11 @@ export declare function writeSourceMap(map: GeneratedSourceMap): string;
 export declare function readSourceMap(mapPath: string): GeneratedSourceMap;
 export declare function makeGeneratedMap(generatedFilePath: string, sourceFilePath: string, entries: SourceMapEntry[]): GeneratedSourceMap;
 export declare function mapCppLocationToTs(map: GeneratedSourceMap, cppLine: number, cppColumn: number, message?: string, cppFilePath?: string): MappedDiagnostic;
-export declare function resolveMapPath(mapFileOrGeneratedFile: string): string;
 /**
- * Resolve source map path for a flattened Arduino sketch
- * When a sketch is flattened, the source map needs to account for merged files
+ * Resolve source map path for a generated program
+ * When a program is flattened, the source map needs to account for merged files
  */
-export declare function resolveSourceMapForSketch(sketchPath: string, originalSourceMapPath?: string): string | undefined;
+export declare function resolveSourceMapForProgram(programPath: string, originalSourceMapPath?: string): string | undefined;
 /**
  * Index of every per-file source map in a build directory, keyed by the
  * normalized generated file path (the .cpp/.h each map covers).

package/dist/mapping/source-map.js

@@ -80,42 +80,36 @@ export function mapCppLocationToTs(map, cppLine, cppColumn, message, cppFilePath
         symbolName: best?.symbolName,
     };
 }
-export function resolveMapPath(mapFileOrGeneratedFile) {
-    if (mapFileOrGeneratedFile.endsWith(".thcppmap.json")) {
-        return path.resolve(process.cwd(), mapFileOrGeneratedFile);
-    }
-    return toSourceMapPath(path.resolve(process.cwd(), mapFileOrGeneratedFile));
-}
 /**
- * Resolve source map path for a flattened Arduino sketch
- * When a sketch is flattened, the source map needs to account for merged files
+ * Resolve source map path for a generated program
+ * When a program is flattened, the source map needs to account for merged files
  */
-export function resolveSourceMapForSketch(sketchPath, originalSourceMapPath) {
-    const sketchDir = path.dirname(sketchPath);
-    const sketchName = path.basename(sketchPath, path.extname(sketchPath));
+export function resolveSourceMapForProgram(programPath, originalSourceMapPath) {
+    const programDir = path.dirname(programPath);
+    const programName = path.basename(programPath, path.extname(programPath));
     // First try the original source map path
     if (originalSourceMapPath && fs.existsSync(originalSourceMapPath)) {
         return originalSourceMapPath;
     }
-    // Try to find source maps for the sketch directory
+    // Try to find source maps for the program directory
     const possibleMaps = [
-        path.join(sketchDir, `${sketchName}.thcppmap.json`),
-        path.join(sketchDir, `${sketchName}.ino.thcppmap.json`),
-        path.join(sketchDir, "example.thcppmap.json"), // Common case for example sketches
+        path.join(programDir, `${programName}.thcppmap.json`),
+        path.join(programDir, `${programName}.cpp.thcppmap.json`),
+        path.join(programDir, "example.thcppmap.json"), // Common case for example programs
     ];
     for (const mapPath of possibleMaps) {
         if (fs.existsSync(mapPath)) {
             return mapPath;
         }
     }
-    // Look for any .thcppmap.json files in the sketch directory
+    // Look for any .thcppmap.json files in the program directory
     try {
-        const files = fs.readdirSync(sketchDir);
+        const files = fs.readdirSync(programDir);
         const mapFiles = files.filter(f => f.endsWith('.thcppmap.json'));
         if (mapFiles.length > 0) {
             // Return the most recent one
             const latest = mapFiles.sort().pop();
-            return path.join(sketchDir, latest);
+            return path.join(programDir, latest);
         }
     }
     catch {

package/dist/orchestrator/graph-builder.d.ts

@@ -12,10 +12,10 @@ export declare function topologicalSortFiles(files: string[], dependencies: Map<
  * 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 declare function collectTranspileGraph(entryFile: string, boardPackage?: string, imageDecodeOpts?: {
+export declare function collectTranspileGraph(entryFile: string, boardTarget?: string, imageDecodeOpts?: {
     maxW?: number;
     maxH?: number;
 }): Promise<TranspileGraphResult>;

package/dist/orchestrator/graph-builder.js

@@ -3,6 +3,7 @@ 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.
@@ -66,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();
@@ -134,11 +135,11 @@ export async function collectTranspileGraph(entryFile, boardPackage, imageDecode
                 // @typecad/* specifiers, unlike the selective main-loop skip list).
                 if (registerCuttlefishLibraryFromSpecifier(filePath, moduleSpecifier))
                     continue;
-                if (moduleSpecifier === "@typecad/expect" || moduleSpecifier === "@typecad/ui" || moduleSpecifier === "@typecad/safety")
+                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)
@@ -179,16 +180,16 @@ export async function collectTranspileGraph(entryFile, boardPackage, imageDecode
             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
@@ -205,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) {