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

package/dist/libdef/component-decls.d.ts

@@ -0,0 +1,2 @@
+export { generateComponentDeclsForProject } from "./cpp-to-decl.js";
+export type { ComponentScanRoots } from "./component-discovery.js";

package/dist/libdef/component-decls.js

@@ -0,0 +1,6 @@
+// Public barrel for component declaration generation.
+//
+// framework-esp32 imports `generateComponentDeclsForProject` from here so its
+// dependency on cuttlefish is declared through the package exports map rather
+// than a deep relative path. Spec: 2026-07-19-framework-esp32-components-design.md
+export { generateComponentDeclsForProject } from "./cpp-to-decl.js";

package/dist/libdef/component-discovery.d.ts

@@ -0,0 +1,43 @@
+export interface ComponentScanRoots {
+    /** Subdirectory names under managed_components/ (e.g. espressif__esp_wifi). */
+    managed: string[];
+    /** Absolute paths to local component directories. */
+    local: string[];
+    /**
+     * ESP-IDF built-in component names (e.g. esp_wifi). Resolved against
+     * `idfRoot/components/<name>/include/` when idfRoot is provided; ignored
+     * otherwise (the caller is responsible for passing idfRoot when builtins
+     * are present).
+     */
+    builtin: string[];
+    /** Optional ESP-IDF install root for resolving `builtin` names. */
+    idfRoot?: string;
+}
+/**
+ * A discovered header plus the directory its generated .d.ts should land in.
+ *
+ * `outputDir` is alongside the header for managed/local components (so the
+ * .d.ts lives in the same gitignored component dir, regenerated on each run).
+ * For built-in components it's a project-local cache — NEVER write into the
+ * IDF install itself.
+ */
+export interface DiscoveredHeader {
+    /** Absolute path to the source .h file. */
+    path: string;
+    /** Absolute directory where the generated .d.ts should be written. */
+    outputDir: string;
+}
+/**
+ * Find all .h files for the declared components.
+ *
+ * - managed: scan `managed_components/<name>/include/` (falling back to the
+ *   component dir if no include/ exists). Populated by `idf.py reconfigure`.
+ * - local: scan `<path>/include/` (or `<path>/`).
+ * - builtin: scan `<idfRoot>/components/<name>/include/` (IDF ships with these).
+ *
+ * For builtins the output .d.ts goes to `<projectDir>/.cuttlefish/component-decls/<component>/`
+ * — never into `$IDF_PATH/components/`, which would pollute the IDF install.
+ *
+ * Returned entries are unsorted — the caller decides ordering.
+ */
+export declare function discoverComponentHeaders(projectDir: string, roots: ComponentScanRoots): DiscoveredHeader[];

package/dist/libdef/component-discovery.js

@@ -0,0 +1,83 @@
+import { existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/** Walk a directory recursively, returning all .h files. */
+function walkHeaders(dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    const stack = [dir];
+    while (stack.length > 0) {
+        const cur = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(cur);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            const full = join(cur, name);
+            try {
+                const st = statSync(full);
+                if (st.isDirectory()) {
+                    stack.push(full);
+                }
+                else if (name.toLowerCase().endsWith('.h')) {
+                    out.push(full);
+                }
+            }
+            catch {
+                // Stat failed (race); skip.
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Find all .h files for the declared components.
+ *
+ * - managed: scan `managed_components/<name>/include/` (falling back to the
+ *   component dir if no include/ exists). Populated by `idf.py reconfigure`.
+ * - local: scan `<path>/include/` (or `<path>/`).
+ * - builtin: scan `<idfRoot>/components/<name>/include/` (IDF ships with these).
+ *
+ * For builtins the output .d.ts goes to `<projectDir>/.cuttlefish/component-decls/<component>/`
+ * — never into `$IDF_PATH/components/`, which would pollute the IDF install.
+ *
+ * Returned entries are unsorted — the caller decides ordering.
+ */
+export function discoverComponentHeaders(projectDir, roots) {
+    const headers = [];
+    for (const name of roots.managed) {
+        const base = join(projectDir, 'managed_components', name);
+        const includeDir = join(base, 'include');
+        const dir = existsSync(includeDir) ? includeDir : base;
+        for (const h of walkHeaders(dir)) {
+            headers.push({ path: h, outputDir: dir });
+        }
+    }
+    for (const localPath of roots.local) {
+        const includeDir = join(localPath, 'include');
+        const dir = existsSync(includeDir) ? includeDir : localPath;
+        for (const h of walkHeaders(dir)) {
+            headers.push({ path: h, outputDir: dir });
+        }
+    }
+    if (roots.idfRoot) {
+        for (const name of roots.builtin) {
+            const base = join(roots.idfRoot, 'components', name);
+            const includeDir = join(base, 'include');
+            const dir = existsSync(includeDir) ? includeDir : base;
+            // Project-local cache for builtins. Mirrors the include/ layout so
+            // imports can substitute `managed_components/<name>/include/X.d.ts`
+            // patterns. Each header's .d.ts is named after the header basename.
+            const outDir = join(projectDir, '.cuttlefish', 'component-decls', name);
+            if (!existsSync(outDir))
+                mkdirSync(outDir, { recursive: true });
+            for (const h of walkHeaders(dir)) {
+                headers.push({ path: h, outputDir: outDir });
+            }
+        }
+    }
+    return headers;
+}

package/dist/libdef/cpp-to-decl.d.ts

@@ -32,3 +32,12 @@ export declare function generateDeclsForDirectory(dir: string, recursive?: boole
  * a later step for the directory-scan path.
  */
 export declare function generateDecl(filePath: string, outputPath?: string): string | null;
+import { type ComponentScanRoots } from "./component-discovery.js";
+/**
+ * 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 declare function generateComponentDeclsForProject(projectDir: string, roots: ComponentScanRoots): string[];

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

@@ -8,6 +8,7 @@ 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
  */
@@ -582,3 +583,74 @@ 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.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { listFiles, readText } from "../utils/fs.js";
+import { listFilesRecursive, readText } from "../utils/fs.js";
 import { toModuleKey, toPascalCase } from "../utils/strings.js";
 import { getLoadedFramework, hasLoadedFramework } from "../framework-registry.js";
 function toArchitectureFromFqbn(fqbn) {
@@ -21,7 +21,10 @@ function getLibraryResolver() {
 }
 export function loadLibraryDefinitions(definitionsDir) {
     const registry = new Map();
-    const files = listFiles(definitionsDir, ".libdef.json");
+    // 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).
+    const files = listFilesRecursive(definitionsDir, ".libdef.json");
     for (const filePath of files) {
         let def;
         try {

package/dist/lint-cache.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Persistent cache for the ESLint build gate.
+ *
+ * ESLint is a mandatory correctness gate: it excludes non-AOT code patterns
+ * that the transpiler cannot accept. Running it on every `cuttlefish build`
+ * costs ~3s (38% of a small-project build) and almost always finds nothing on
+ * repeat runs. Its result (zero errors) is a whole-program boolean that
+ * depends only on a small set of inputs, so it is cleanly cacheable.
+ *
+ * Soundness contract:
+ *   - The cache ONLY records a successful (zero-error) lint result.
+ *   - A failing lint never persists (the build aborts anyway).
+ *   - On ANY input change the entry is invalidated and ESLint runs for real.
+ *   - `options.force` and the `CUTTLEFISH_NO_CACHE` env var bypass entirely.
+ *
+ * This mirrors the historical `.cuttlefish-cache.json` timestamp+hash cache
+ * that used to live in this package. It is scoped to the ESLint gate (and the
+ * type-check gate) rather than the transpile-IR pass, because — unlike IR
+ * lowering — these gates' outcomes are whole-program booleans with no
+ * cross-module rehydration requirement.
+ */
+/** Resolve the eslint config the same way runEslintCheck does, to avoid drift. */
+export declare function resolveEslintConfigPath(projectRoot: string): string | undefined;
+/**
+ * Compute the inputs that the ESLint result depends on. Two builds with the
+ * same fingerprint are guaranteed to produce the same lint outcome.
+ */
+export interface LintFingerprint {
+    digest: string;
+    /** Absolute paths that were hashed into the digest (for debugging). */
+    inputs: string[];
+}
+export declare function computeLintFingerprint(projectRoot: string, srcDir: string): LintFingerprint | null;
+export interface GateCacheResult {
+    /** True when the gate can be skipped because the recorded success still holds. */
+    hit: boolean;
+    /** The fingerprint to record after a successful gate run. */
+    fingerprint: LintFingerprint | null;
+}
+/**
+ * Decide whether the ESLint gate can be skipped for this project.
+ *
+ * Returns `hit: true` only when:
+ *   - caching is not disabled, not force-bypassed,
+ *   - a fingerprint can be computed (config + eslint resolvable), and
+ *   - the on-disk cache records a success for that exact fingerprint.
+ *
+ * `force` mirrors TranspileOptions.force and bypasses the cache.
+ */
+export declare function checkLintCache(projectRoot: string, srcDir: string, opts?: {
+    force?: boolean;
+}): GateCacheResult;
+/**
+ * Record a successful ESLint run (zero errors). Never call this after a
+ * failing run — a failing build must not persist a "clean" marker.
+ */
+export declare function recordLintSuccess(projectRoot: string, fingerprint: LintFingerprint): void;
+/** Drop the lint entry (used when the gate is skipped entirely / nothing to cache). */
+export declare function invalidateLint(projectRoot: string): void;

package/dist/lint-cache.js

@@ -0,0 +1,257 @@
+/**
+ * Persistent cache for the ESLint build gate.
+ *
+ * ESLint is a mandatory correctness gate: it excludes non-AOT code patterns
+ * that the transpiler cannot accept. Running it on every `cuttlefish build`
+ * costs ~3s (38% of a small-project build) and almost always finds nothing on
+ * repeat runs. Its result (zero errors) is a whole-program boolean that
+ * depends only on a small set of inputs, so it is cleanly cacheable.
+ *
+ * Soundness contract:
+ *   - The cache ONLY records a successful (zero-error) lint result.
+ *   - A failing lint never persists (the build aborts anyway).
+ *   - On ANY input change the entry is invalidated and ESLint runs for real.
+ *   - `options.force` and the `CUTTLEFISH_NO_CACHE` env var bypass entirely.
+ *
+ * This mirrors the historical `.cuttlefish-cache.json` timestamp+hash cache
+ * that used to live in this package. It is scoped to the ESLint gate (and the
+ * type-check gate) rather than the transpile-IR pass, because — unlike IR
+ * lowering — these gates' outcomes are whole-program booleans with no
+ * cross-module rehydration requirement.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+const require = createRequire(import.meta.url);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CACHE_VERSION = 2;
+const DEFAULT_CACHE_NAME = ".cuttlefish-cache.json";
+/** Bypass the cache entirely when set (debugging / CI cold runs). */
+function isCacheDisabled() {
+    return process.env.CUTTLEFISH_NO_CACHE === "1" || process.env.CUTTLEFISH_NO_CACHE === "true";
+}
+/**
+ * Hash a file's content. Returns null if the file cannot be read (treated as
+ * "changed" by callers because the input set is no longer what we recorded).
+ */
+function hashFile(absPath) {
+    try {
+        const content = fs.readFileSync(absPath, "utf8");
+        return crypto.createHash("sha256").update(content).digest("hex").slice(0, 16);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Hash size + mtime for a file. Used for inputs (eslint config, eslint package)
+ * that we don't want to fully read on every build, and whose identity is
+ * sufficiently captured by size+mtime. Returns null if the file is missing.
+ */
+function fingerprintStat(absPath) {
+    try {
+        const stat = fs.statSync(absPath);
+        return `${stat.size}:${stat.mtimeMs}`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Transpiler-self fingerprint: invalidate every cache entry when the
+ * transpiler's own compiled sources change. Mirrors the historical
+ * computeToolchainFingerprint() in incremental-cache.ts.
+ */
+let cachedToolchainFingerprint;
+function computeToolchainFingerprint() {
+    if (cachedToolchainFingerprint !== undefined)
+        return cachedToolchainFingerprint;
+    const candidates = [
+        "transpile.js",
+        "lint-cache.js",
+        "eslint-check.js",
+        path.join("emit", "cpp-emitter.js"),
+        path.join("ir", "build-ir.js"),
+        path.join("ir", "ownership-analysis.js"),
+        path.join("ir", "validation-orchestrator.js"),
+    ];
+    const signature = candidates
+        .map((rel) => path.join(__dirname, rel))
+        .filter((p) => fs.existsSync(p))
+        .map((p) => {
+        const stat = fs.statSync(p);
+        return `${path.basename(p)}:${stat.size}:${stat.mtimeMs}`;
+    })
+        .join("|");
+    cachedToolchainFingerprint = crypto.createHash("sha256").update(signature).digest("hex").slice(0, 16);
+    return cachedToolchainFingerprint;
+}
+/** Resolve the eslint config the same way runEslintCheck does, to avoid drift. */
+export function resolveEslintConfigPath(projectRoot) {
+    const cuttlefishConfig = path.join(projectRoot, ".cuttlefish", "eslint.config.mjs");
+    if (fs.existsSync(cuttlefishConfig))
+        return cuttlefishConfig;
+    for (const name of ["eslint.config.mjs", "eslint.config.js", "eslint.config.cjs"]) {
+        const candidate = path.join(projectRoot, name);
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/** Resolve the eslint package version that runEslintCheck would load. */
+function resolveEslintIdentity(projectRoot) {
+    const resolvers = [
+        createRequire(path.join(projectRoot, "package.json")),
+        require,
+    ];
+    for (const r of resolvers) {
+        try {
+            const eslintPath = r.resolve("eslint");
+            const pkgPath = r.resolve("eslint/package.json");
+            const version = JSON.parse(fs.readFileSync(pkgPath, "utf8")).version ?? "unknown";
+            return { path: eslintPath, version };
+        }
+        catch {
+            // try next resolver
+        }
+    }
+    return null;
+}
+/** Recursively gather .ts/.tsx/.ui files under a directory (the lint input set). */
+function gatherSourceFiles(srcDir) {
+    const out = [];
+    if (!fs.existsSync(srcDir) || !fs.statSync(srcDir).isDirectory())
+        return out;
+    const stack = [srcDir];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === "node_modules" || entry.name === "out" || entry.name.startsWith("out-"))
+                    continue;
+                stack.push(full);
+            }
+            else if (entry.isFile()) {
+                const ext = entry.name.toLowerCase();
+                if (ext.endsWith(".ts") || ext.endsWith(".tsx") || ext.endsWith(".ui")) {
+                    out.push(full);
+                }
+            }
+        }
+    }
+    out.sort();
+    return out;
+}
+export function computeLintFingerprint(projectRoot, srcDir) {
+    const configPath = resolveEslintConfigPath(projectRoot);
+    if (!configPath)
+        return null; // no config => runEslintCheck returns [] without loading eslint
+    const eslint = resolveEslintIdentity(projectRoot);
+    if (!eslint)
+        return null; // eslint unresolvable => runEslintCheck returns []
+    const parts = [];
+    parts.push(["toolchain", computeToolchainFingerprint()]);
+    parts.push(["eslint", `${eslint.version}@${eslint.path}`]);
+    parts.push(["config", `${configPath}:${fingerprintStat(configPath) ?? "missing"}`]);
+    const sources = gatherSourceFiles(srcDir);
+    for (const f of sources) {
+        const h = hashFile(f);
+        parts.push(["src", `${f}:${h ?? "missing"}`]);
+    }
+    const digest = crypto
+        .createHash("sha256")
+        .update(parts.map((p) => p.join("=")).join("\n"))
+        .digest("hex")
+        .slice(0, 32);
+    return { digest, inputs: parts.map((p) => p[1]) };
+}
+function cachePathFor(projectRoot) {
+    return path.join(projectRoot, DEFAULT_CACHE_NAME);
+}
+function loadCacheFile(projectRoot) {
+    const cachePath = cachePathFor(projectRoot);
+    try {
+        if (!fs.existsSync(cachePath))
+            return null;
+        const data = JSON.parse(fs.readFileSync(cachePath, "utf8"));
+        if (data.version === CACHE_VERSION &&
+            data.toolchainFingerprint === computeToolchainFingerprint() &&
+            path.resolve(data.rootDir) === path.resolve(projectRoot)) {
+            return data;
+        }
+    }
+    catch {
+        // Corrupt or unreadable — treat as empty.
+    }
+    return null;
+}
+function saveCacheFile(projectRoot, data) {
+    data.updatedAt = Date.now();
+    try {
+        fs.writeFileSync(cachePathFor(projectRoot), JSON.stringify(data, null, 2), "utf8");
+    }
+    catch {
+        // Non-fatal: caching is best-effort. Next build just re-runs the gate.
+    }
+}
+function freshCacheFile(projectRoot) {
+    return {
+        version: CACHE_VERSION,
+        toolchainFingerprint: computeToolchainFingerprint(),
+        rootDir: path.resolve(projectRoot),
+        gates: {},
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+    };
+}
+/**
+ * Decide whether the ESLint gate can be skipped for this project.
+ *
+ * Returns `hit: true` only when:
+ *   - caching is not disabled, not force-bypassed,
+ *   - a fingerprint can be computed (config + eslint resolvable), and
+ *   - the on-disk cache records a success for that exact fingerprint.
+ *
+ * `force` mirrors TranspileOptions.force and bypasses the cache.
+ */
+export function checkLintCache(projectRoot, srcDir, opts = {}) {
+    const fingerprint = computeLintFingerprint(projectRoot, srcDir);
+    if (fingerprint === null)
+        return { hit: false, fingerprint: null };
+    if (opts.force || isCacheDisabled())
+        return { hit: false, fingerprint };
+    const data = loadCacheFile(projectRoot);
+    if (!data)
+        return { hit: false, fingerprint };
+    const entry = data.gates.lint;
+    return { hit: entry?.digest === fingerprint.digest, fingerprint };
+}
+/**
+ * Record a successful ESLint run (zero errors). Never call this after a
+ * failing run — a failing build must not persist a "clean" marker.
+ */
+export function recordLintSuccess(projectRoot, fingerprint) {
+    if (isCacheDisabled())
+        return;
+    const data = loadCacheFile(projectRoot) ?? freshCacheFile(projectRoot);
+    data.gates.lint = { digest: fingerprint.digest, recordedAt: Date.now() };
+    saveCacheFile(projectRoot, data);
+}
+/** Drop the lint entry (used when the gate is skipped entirely / nothing to cache). */
+export function invalidateLint(projectRoot) {
+    const data = loadCacheFile(projectRoot);
+    if (data && data.gates.lint) {
+        delete data.gates.lint;
+        saveCacheFile(projectRoot, data);
+    }
+}

package/dist/orchestrator/graph-builder.js

@@ -121,7 +121,7 @@ export function collectTranspileGraph(entryFile, boardPackage) {
                 }
                 if (!moduleSpecifier)
                     continue;
-                if (moduleSpecifier === "@typecad/expect" || moduleSpecifier === "@typecad/ui")
+                if (moduleSpecifier === "@typecad/expect" || moduleSpecifier === "@typecad/ui" || moduleSpecifier === "@typecad/safety")
                     continue;
                 if (moduleSpecifier.startsWith("@typecad/"))
                     continue;
@@ -159,22 +159,27 @@ export function collectTranspileGraph(entryFile, boardPackage) {
             if (moduleSpecifier === "@typecad/expect") {
                 continue;
             }
-            // Skip @typecad/ui (and the future @typecad/ui rename) — it provides
-            // compile-time authoring stubs only. ui.mount/signal/bind calls are
-            // intercepted by tryResolveUICall and lowered to IR; the package itself
-            // must NOT be emitted as a C++ module (it would synthesize a bogus
-            // _ui_t struct for the `ui` namespace value).
-            if (moduleSpecifier === "@typecad/ui" || moduleSpecifier === "@typecad/ui") {
+            // 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
+            // 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") {
                 continue;
             }
-            // Skip @typecad/board, @typecad/board-*, @typecad/mcu-*, and
-            // @typecad/framework-* — these packages ship src/ for HAL metadata
+            // Skip @typecad/board, @typecad/board-*, @typecad/mcu-*, @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
             // metadata from these files separately; emitting them as C++ produces
             // thousands of lines of stub functions (board(), gpioWrite(), etc.)
             // and pulls in unsupported types (Promise, variant, Object.freeze).
+            // Skipping @typecad/hal is especially important: its 28 source files
+            // (gpio.ts, i2c.ts, spi.ts, etc.) were all walked through full
+            // buildProgramIR, adding ~40 seconds to every transpile.
             if (moduleSpecifier === "@typecad/board"
+                || moduleSpecifier === "@typecad/hal"
                 || moduleSpecifier.startsWith("@typecad/board-")
                 || moduleSpecifier.startsWith("@typecad/mcu-")
                 || moduleSpecifier.startsWith("@typecad/framework-")) {

package/dist/platform/coop-scheduler-runtime.d.ts

@@ -0,0 +1,19 @@
+import type { ProgramIR } from "../api/index.js";
+import type { RuntimePolyfillIR } from "../api/shared/index.js";
+import type { AsyncRuntimeConfig } from "../api/shared/index.js";
+/**
+ * Build a RuntimePolyfillIR for the no-STL cooperative scheduler, when the
+ * program has async/timer work AND the strategy has opted into priority/time-
+ * budget scheduling via AsyncRuntimeConfig.
+ *
+ * The polyfill carries only the scheduler namespace + CoopSched_run() alias.
+ * Per-program work-unit registration + dispatch lines are emitted separately
+ * by each strategy's asyncLoopInjection() via buildCoopSchedInjection().
+ *
+ * Why a polyfill and not shimLines(): polyfills are dead-code-eliminated
+ * (filterPolyfillHelpers) and feature-gated centrally, matching how
+ * async_runtime / timer_methods are handled. The scheduler is STL-free, so it
+ * links on minimal-libc targets (Zephyr) where the std::function Promise
+ * runtime does not.
+ */
+export declare function buildCoopSchedulerPolyfill(_program: ProgramIR, config: AsyncRuntimeConfig, currentTimeExpr?: string): RuntimePolyfillIR | null;