@typecad/cuttlefish 0.1.0-alpha.2 → 1.0.0-alpha.10

package/dist/install/framework-catalog.js

@@ -0,0 +1,107 @@
+// Framework catalog + board→framework compatibility for `cuttlefish install`.
+//
+// A "framework" is a `@typecad/framework-<id>` npm package. This module is the
+// single source of truth for which frameworks exist as installable packages and
+// which are compatible with a given board architecture. It is deliberately
+// free of side effects (no fs/process beyond lockfile/package.json reads in
+// detectPackageManager) so it unit-tests cleanly.
+import path from "node:path";
+import fs from "node:fs";
+/**
+ * The installable frameworks. Kept aligned with the packages/ directory:
+ * framework-arduino, framework-native, framework-zephyr all ship real packages.
+ * esp-idf is intentionally absent (no published package in this repo).
+ */
+export const FRAMEWORK_CATALOG = [
+    { id: "arduino", packageName: "@typecad/framework-arduino", label: "Arduino (digitalWrite, Wire, SPI)", installable: true },
+    { id: "zephyr", packageName: "@typecad/framework-zephyr", label: "Zephyr RTOS", installable: true },
+    { id: "native", packageName: "@typecad/framework-native", label: "Native (Windows/Linux executable)", installable: true },
+];
+/**
+ * Architecture → compatible framework ids. Derived from each framework
+ * package's framework.manifest.ts `profile.targets`:
+ *   - arduino: avr, esp32 family, rp2040/rp2350, samd, stm32
+ *   - zephyr:  nrf52 (xiao_ble), esp32, esp32s3
+ *   - native:  desktop only
+ * Unknown embedded architectures fall back to [arduino] (the broadest core).
+ */
+const ARCHITECTURE_FRAMEWORKS = {
+    avr: ["arduino"],
+    esp32: ["arduino", "zephyr"],
+    esp32s2: ["arduino"],
+    esp32s3: ["arduino", "zephyr"],
+    esp32c3: ["arduino"],
+    esp32c6: ["arduino"],
+    rp2040: ["arduino"],
+    rp2350: ["arduino"],
+    samd: ["arduino"],
+    stm32: ["arduino"],
+    nrf52: ["zephyr"],
+};
+const FALLBACK_FRAMEWORKS = ["arduino"];
+/** Look up a catalog entry by framework id (e.g. "arduino"). */
+export function frameworkCatalogEntry(id) {
+    return FRAMEWORK_CATALOG.find((f) => f.id === id);
+}
+/**
+ * The framework ids compatible with a board. Native boards map to ["native"];
+ * embedded boards map via ARCHITECTURE_FRAMEWORKS (falling back to arduino for
+ * unknown architectures). Order is preserved as the catalog order so the most
+ * common framework is offered first in the prompt.
+ */
+export function frameworksForTarget(target) {
+    let ids;
+    if (target.isNative) {
+        ids = ["native"];
+    }
+    else {
+        ids = ARCHITECTURE_FRAMEWORKS[target.architecture ?? ""] ?? FALLBACK_FRAMEWORKS;
+    }
+    // Re-map ids → catalog entries in catalog order (stable ordering), dropping
+    // any id that has no catalog entry (defensive — keeps the prompt clean).
+    return FRAMEWORK_CATALOG.filter((entry) => ids.includes(entry.id));
+}
+/**
+ * Detect the package manager for a directory. Priority:
+ *   1. package.json#packageManager field (the strongest signal, Corepack-style)
+ *   2. lockfile presence (pnpm-lock.yaml / yarn.lock → otherwise npm)
+ *   3. default "npm"
+ * Never throws — unreadable/missing files fall through to the next signal.
+ */
+export function detectPackageManager(cwd) {
+    try {
+        const pkgPath = path.join(cwd, "package.json");
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+        const pm = typeof pkg.packageManager === "string" ? pkg.packageManager : "";
+        if (pm.startsWith("pnpm"))
+            return "pnpm";
+        if (pm.startsWith("yarn"))
+            return "yarn";
+        if (pm.startsWith("npm"))
+            return "npm";
+    }
+    catch {
+        // no package.json or unparseable JSON — fall through to lockfile detection
+    }
+    if (fs.existsSync(path.join(cwd, "pnpm-lock.yaml")))
+        return "pnpm";
+    if (fs.existsSync(path.join(cwd, "yarn.lock")))
+        return "yarn";
+    // package-lock.json implies npm; absence also defaults to npm.
+    return "npm";
+}
+/**
+ * Build the package-manager invocation that installs `packageName` into the
+ * current project (project-local, never global — per the install command spec).
+ */
+export function buildInstallCommand(pm, packageName) {
+    switch (pm) {
+        case "pnpm":
+            return { bin: "pnpm", args: ["add", packageName] };
+        case "yarn":
+            return { bin: "yarn", args: ["add", packageName] };
+        case "npm":
+        default:
+            return { bin: "npm", args: ["install", packageName] };
+    }
+}

package/dist/install/handle-install.d.ts

@@ -0,0 +1,35 @@
+import type { InstallCommandOptions } from "../types.js";
+import { type FrameworkCatalogEntry, type PackageManager } from "./framework-catalog.js";
+interface InstallCommand {
+    bin: string;
+    args: string[];
+    cwd: string;
+}
+interface InstallRunResult {
+    /** Exit status; null when the process could not be launched (ENOENT, etc.). */
+    status: number | null;
+    /** Populated only when the binary could not be launched. */
+    launchError?: string;
+}
+type InstallRunner = (cmd: InstallCommand) => InstallRunResult;
+/**
+ * FOR TESTS ONLY. Replaces the real spawn-based installer with `runner`.
+ * Pass `undefined` to restore the real executor.
+ */
+export declare function __setInstallRunnerForTest(runner: InstallRunner | undefined): void;
+export interface InstallResult {
+    pm: PackageManager;
+    bin: string;
+    args: string[];
+}
+/**
+ * Resolve the package manager and run the install for `entry`'s package. In
+ * dry-run mode the command is printed but not executed. Throws on launch
+ * failure or non-zero exit so the CLI surfaces a clear error.
+ */
+export declare function installFrameworkPackage(entry: FrameworkCatalogEntry, opts: {
+    cwd: string;
+    dryRun?: boolean;
+}): InstallResult;
+export declare function handleInstall(options: InstallCommandOptions): Promise<void>;
+export {};

package/dist/install/handle-install.js

@@ -0,0 +1,177 @@
+// `cuttlefish install` — installs a chosen @typecad/framework-* package into the
+// current project. The flow asks which board to target first, then narrows the
+// framework choices to those compatible with that board (see framework-catalog).
+// A framework id may be passed directly (`cuttlefish install arduino`) to skip
+// the prompts entirely, which also makes the command usable in CI.
+import * as readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { spawnSync } from "node:child_process";
+import chalk from "chalk";
+import { KNOWN_TARGETS } from "../create/index.js";
+import { FRAMEWORK_CATALOG, frameworkCatalogEntry, frameworksForTarget, detectPackageManager, buildInstallCommand, } from "./framework-catalog.js";
+// ── prompts (mirror the create wizard's style for a consistent UX) ──────────
+async function promptSelect(rl, prompt, options) {
+    console.log(`${chalk.cyan("?")} ${prompt}:`);
+    for (let i = 0; i < options.length; i++) {
+        console.log(`  ${chalk.dim(`${i + 1})`)} ${options[i].label}`);
+    }
+    while (true) {
+        const answer = await rl.question(`  Enter number (1-${options.length}): `);
+        const idx = parseInt(answer.trim(), 10) - 1;
+        if (idx >= 0 && idx < options.length) {
+            return options[idx].value;
+        }
+        console.log(`  ${chalk.red("✗")} Please enter a number between 1 and ${options.length}.`);
+    }
+}
+async function selectBoardInteractively(rl) {
+    const options = KNOWN_TARGETS.map((t) => ({
+        label: t.isNative
+            ? `${t.displayName} (Windows/Linux executable)`
+            : `${t.displayName} (${t.architecture.toUpperCase()})`,
+        value: t.id,
+    }));
+    const selectedId = await promptSelect(rl, "Target board", options);
+    return KNOWN_TARGETS.find((t) => t.id === selectedId);
+}
+/**
+ * Pick a framework for `target`. When only one framework is compatible with the
+ * board it is auto-selected (mirrors the create wizard's single-option path) so
+ * the user isn't asked a question with one answer.
+ */
+async function selectFrameworkInteractively(rl, target, compatible) {
+    if (compatible.length === 1) {
+        const only = compatible[0];
+        console.log(`${chalk.cyan("?")} Framework: ${chalk.white(only.label)} ${chalk.dim(`(only option for ${target.id})`)}`);
+        return only;
+    }
+    const selectedId = await promptSelect(rl, "Framework", compatible.map((f) => ({ label: f.label, value: f.id })));
+    return compatible.find((f) => f.id === selectedId);
+}
+let testRunner;
+/**
+ * FOR TESTS ONLY. Replaces the real spawn-based installer with `runner`.
+ * Pass `undefined` to restore the real executor.
+ */
+export function __setInstallRunnerForTest(runner) {
+    testRunner = runner;
+}
+function runRealInstall(cmd) {
+    // stdio: "inherit" streams the package manager's own output to the terminal
+    // (install progress, deprecation warnings, etc.). On failure the user has
+    // already seen the details above, so we only need to report the exit code.
+    const result = spawnSync(cmd.bin, cmd.args, {
+        cwd: cmd.cwd,
+        stdio: "inherit",
+    });
+    if (result.error) {
+        const errno = result.error.code;
+        return {
+            status: null,
+            launchError: errno === "ENOENT" ? `'${cmd.bin}' not found on PATH` : String(result.error),
+        };
+    }
+    return { status: result.status };
+}
+/**
+ * Resolve the package manager and run the install for `entry`'s package. In
+ * dry-run mode the command is printed but not executed. Throws on launch
+ * failure or non-zero exit so the CLI surfaces a clear error.
+ */
+export function installFrameworkPackage(entry, opts) {
+    const pm = detectPackageManager(opts.cwd);
+    const { bin, args } = buildInstallCommand(pm, entry.packageName);
+    if (opts.dryRun) {
+        console.log(`${chalk.cyan("$")} ${bin} ${args.join(" ")}`);
+        return { pm, bin, args };
+    }
+    const cmd = { bin, args, cwd: opts.cwd };
+    const run = testRunner ?? runRealInstall;
+    const result = run(cmd);
+    if (result.launchError) {
+        throw new Error(`Failed to run '${bin}': ${result.launchError}`);
+    }
+    if (result.status !== 0) {
+        throw new Error(`'${bin} ${args.join(" ")}' exited with code ${result.status}. See the package manager output above for details.`);
+    }
+    return { pm, bin, args };
+}
+// ── command entry point ─────────────────────────────────────────────────────
+export async function handleInstall(options) {
+    const cwd = process.cwd();
+    // 1. Resolve which framework to install.
+    let entry;
+    if (options.framework) {
+        const resolved = frameworkCatalogEntry(options.framework);
+        if (!resolved) {
+            const available = FRAMEWORK_CATALOG.filter((f) => f.installable).map((f) => f.id).join(", ");
+            throw new Error(`Unknown framework '${options.framework}'. Available: ${available}`);
+        }
+        if (!resolved.installable) {
+            throw new Error(`Framework '${options.framework}' has no published package yet and cannot be installed.`);
+        }
+        entry = resolved;
+        console.log(`${chalk.cyan("?")} Framework: ${chalk.white(entry.label)}`);
+    }
+    else {
+        // Resolve the target board. --board skips the board prompt; otherwise the
+        // board is chosen interactively (which requires a TTY — handled below).
+        let target;
+        if (options.board) {
+            const found = KNOWN_TARGETS.find((t) => t.id === options.board);
+            if (!found) {
+                const available = KNOWN_TARGETS.map((t) => t.id).join(", ");
+                throw new Error(`Unknown board '${options.board}'. Available: ${available}`);
+            }
+            target = found;
+            console.log(`${chalk.cyan("?")} Board: ${chalk.white(target.displayName)} (${chalk.dim(target.id)})`);
+        }
+        // Narrow to the frameworks compatible with that board.
+        let compatible;
+        if (target) {
+            compatible = frameworksForTarget(target).filter((f) => f.installable);
+            if (compatible.length === 0) {
+                throw new Error(`No installable frameworks are compatible with board '${target.id}'.`);
+            }
+        }
+        if (compatible && compatible.length === 1) {
+            // Only one framework fits this board — auto-select it (no prompt, so this
+            // path also works under CI / non-interactive stdin).
+            entry = compatible[0];
+            console.log(`${chalk.cyan("?")} Framework: ${chalk.white(entry.label)} ${chalk.dim(`(only option for ${target.id})`)}`);
+        }
+        else {
+            // Need to prompt — for the board (if --board wasn't given) and/or for the
+            // framework (when 2+ are compatible). Refuse to hang on a readline that
+            // can't be answered (e.g. piped stdin under CI).
+            if (!process.stdin.isTTY) {
+                throw new Error("No framework specified and stdin is not interactive. " +
+                    "Pass a framework id (e.g. 'cuttlefish install arduino'), " +
+                    "or a board with a single compatible framework (e.g. '--board arduino-uno').");
+            }
+            const rl = readline.createInterface({ input, output });
+            try {
+                if (!target) {
+                    target = await selectBoardInteractively(rl);
+                    compatible = frameworksForTarget(target).filter((f) => f.installable);
+                    if (compatible.length === 0) {
+                        throw new Error(`No installable frameworks are compatible with board '${target.id}'.`);
+                    }
+                }
+                entry = await selectFrameworkInteractively(rl, target, compatible);
+            }
+            finally {
+                rl.close();
+            }
+        }
+    }
+    // 2. Install it.
+    console.log(`\n${chalk.cyan("⤳")} Installing ${chalk.white(entry.packageName)} into ${chalk.dim(cwd)}…`);
+    const result = installFrameworkPackage(entry, { cwd, dryRun: options.dryRun });
+    if (options.dryRun) {
+        console.log(chalk.dim("(dry-run — nothing was installed)"));
+        return;
+    }
+    console.log(`\n${chalk.green("✓")} Installed ${chalk.white(entry.packageName)} via ${result.pm}.`);
+    console.log(chalk.dim(`Next: run 'cuttlefish create' and pick ${entry.id}, or set framework: "${entry.packageName}" in cuttlefish.config.ts.`));
+}

package/dist/install/index.d.ts

@@ -0,0 +1,4 @@
+export { handleInstall, installFrameworkPackage, __setInstallRunnerForTest } from "./handle-install.js";
+export type { InstallResult } from "./handle-install.js";
+export { FRAMEWORK_CATALOG, frameworkCatalogEntry, frameworksForTarget, detectPackageManager, buildInstallCommand, } from "./framework-catalog.js";
+export type { FrameworkCatalogEntry, BoardLike, PackageManager, } from "./framework-catalog.js";

package/dist/install/index.js

@@ -0,0 +1,3 @@
+// `cuttlefish install` command — install a @typecad/framework-* package.
+export { handleInstall, installFrameworkPackage, __setInstallRunnerForTest } from "./handle-install.js";
+export { FRAMEWORK_CATALOG, frameworkCatalogEntry, frameworksForTarget, detectPackageManager, buildInstallCommand, } from "./framework-catalog.js";

package/dist/ir/adc-range-validation.js

@@ -4,6 +4,7 @@
 // Detects comparisons against analogRead() values that exceed the board's
 // ADC resolution (e.g., comparing to > 1023 on a 10-bit Arduino Uno).
 // ---------------------------------------------------------------------------
+import { hasLoadedFramework, getLoadedFramework } from '../framework-registry.js';
 /**
  * Get ADC configuration from board constants.
  */
@@ -41,7 +42,19 @@ function isAnalogRead(expr) {
         return op === 'adc.read' || op === 'adc.read_voltage';
     }
     if (expr.kind === 'raw') {
-        return /analogRead\s*\(/.test(expr.value);
+        const value = expr.value;
+        // Ask the loaded framework which call names produce an ADC read; fall back
+        // to the Wiring-derived analogRead when no framework is loaded.
+        const frameworkNames = hasLoadedFramework()
+            ? getLoadedFramework().strategy.analogReadCallNames?.()
+            : undefined;
+        const names = frameworkNames ?? new Set(['analogRead']);
+        for (const name of names) {
+            const re = new RegExp(`${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*\\(`);
+            if (re.test(value))
+                return true;
+        }
+        return false;
     }
     return false;
 }
@@ -59,7 +72,7 @@ function extractNumericValue(expr) {
 /**
  * Check binary comparison expressions for ADC range issues.
  */
-function checkComparisonForADCRange(left, operator, right, adcConfig, diagnostics) {
+function checkComparisonForADCRange(left, operator, right, adcConfig, filePath, diagnostics) {
     // Check if one side is an analog read and the other is a literal
     let analogReadSide = null;
     let literalValue = null;
@@ -83,6 +96,7 @@ function checkComparisonForADCRange(left, operator, right, adcConfig, diagnostic
             severity: 'info',
             message: `Comparison ${comparisonDesc} may never be true. ADC resolution is ${adcConfig.resolution}-bit (max ${adcConfig.maxValue}) on this board.`,
             code: 'adc-range-warning',
+            filePath,
             source: 'adc-range-validation',
         });
     }
@@ -90,7 +104,7 @@ function checkComparisonForADCRange(left, operator, right, adcConfig, diagnostic
 /**
  * Scan an expression for ADC range issues.
  */
-function scanExpressionForADCRange(expr, adcConfig, diagnostics) {
+function scanExpressionForADCRange(expr, adcConfig, filePath, diagnostics) {
     if (!expr || typeof expr !== 'object')
         return;
     // Check binary comparisons
@@ -98,59 +112,59 @@ function scanExpressionForADCRange(expr, adcConfig, diagnostics) {
         const bin = expr;
         const comparisonOps = ['>', '>=', '<', '<=', '===', '==', '!==', '!='];
         if (comparisonOps.includes(bin.operator)) {
-            checkComparisonForADCRange(bin.left, bin.operator, bin.right, adcConfig, diagnostics);
+            checkComparisonForADCRange(bin.left, bin.operator, bin.right, adcConfig, filePath, diagnostics);
         }
         // Recursively scan both sides
-        scanExpressionForADCRange(bin.left, adcConfig, diagnostics);
-        scanExpressionForADCRange(bin.right, adcConfig, diagnostics);
+        scanExpressionForADCRange(bin.left, adcConfig, filePath, diagnostics);
+        scanExpressionForADCRange(bin.right, adcConfig, filePath, diagnostics);
     }
     // Check ternary conditions
     if (expr.kind === 'ternary') {
         const ternary = expr;
-        scanExpressionForADCRange(ternary.condition, adcConfig, diagnostics);
-        scanExpressionForADCRange(ternary.whenTrue, adcConfig, diagnostics);
-        scanExpressionForADCRange(ternary.whenFalse, adcConfig, diagnostics);
+        scanExpressionForADCRange(ternary.condition, adcConfig, filePath, diagnostics);
+        scanExpressionForADCRange(ternary.whenTrue, adcConfig, filePath, diagnostics);
+        scanExpressionForADCRange(ternary.whenFalse, adcConfig, filePath, diagnostics);
     }
     // Check property access
     if (expr.kind === 'property-access') {
         const pa = expr;
-        scanExpressionForADCRange(pa.object, adcConfig, diagnostics);
+        scanExpressionForADCRange(pa.object, adcConfig, filePath, diagnostics);
     }
 }
 /**
  * Scan a statement for ADC range issues.
  */
-function scanStatementForADCRange(stmt, adcConfig, diagnostics) {
+function scanStatementForADCRange(stmt, adcConfig, filePath, diagnostics) {
     if (!stmt || typeof stmt !== 'object')
         return;
     switch (stmt.kind) {
         case 'var_decl': {
             const varDecl = stmt;
             if (varDecl.initializer) {
-                scanExpressionForADCRange(varDecl.initializer, adcConfig, diagnostics);
+                scanExpressionForADCRange(varDecl.initializer, adcConfig, filePath, diagnostics);
             }
             break;
         }
         case 'assign': {
             const assign = stmt;
             if (assign.value) {
-                scanExpressionForADCRange(assign.value, adcConfig, diagnostics);
+                scanExpressionForADCRange(assign.value, adcConfig, filePath, diagnostics);
             }
             break;
         }
         case 'if': {
             const ifStmt = stmt;
             if (ifStmt.condition) {
-                scanExpressionForADCRange(ifStmt.condition, adcConfig, diagnostics);
+                scanExpressionForADCRange(ifStmt.condition, adcConfig, filePath, diagnostics);
             }
             if (ifStmt.thenBranch) {
                 for (const s of ifStmt.thenBranch) {
-                    scanStatementForADCRange(s, adcConfig, diagnostics);
+                    scanStatementForADCRange(s, adcConfig, filePath, diagnostics);
                 }
             }
             if (ifStmt.elseBranch) {
                 for (const s of ifStmt.elseBranch) {
-                    scanStatementForADCRange(s, adcConfig, diagnostics);
+                    scanStatementForADCRange(s, adcConfig, filePath, diagnostics);
                 }
             }
             break;
@@ -158,11 +172,11 @@ function scanStatementForADCRange(stmt, adcConfig, diagnostics) {
         case 'while': {
             const whileStmt = stmt;
             if (whileStmt.condition) {
-                scanExpressionForADCRange(whileStmt.condition, adcConfig, diagnostics);
+                scanExpressionForADCRange(whileStmt.condition, adcConfig, filePath, diagnostics);
             }
             if (whileStmt.body) {
                 for (const s of whileStmt.body) {
-                    scanStatementForADCRange(s, adcConfig, diagnostics);
+                    scanStatementForADCRange(s, adcConfig, filePath, diagnostics);
                 }
             }
             break;
@@ -170,11 +184,11 @@ function scanStatementForADCRange(stmt, adcConfig, diagnostics) {
         case 'for': {
             const forStmt = stmt;
             if (forStmt.condition) {
-                scanExpressionForADCRange(forStmt.condition, adcConfig, diagnostics);
+                scanExpressionForADCRange(forStmt.condition, adcConfig, filePath, diagnostics);
             }
             if (forStmt.body) {
                 for (const s of forStmt.body) {
-                    scanStatementForADCRange(s, adcConfig, diagnostics);
+                    scanStatementForADCRange(s, adcConfig, filePath, diagnostics);
                 }
             }
             break;
@@ -182,7 +196,7 @@ function scanStatementForADCRange(stmt, adcConfig, diagnostics) {
         case 'return': {
             const retStmt = stmt;
             if (retStmt.value) {
-                scanExpressionForADCRange(retStmt.value, adcConfig, diagnostics);
+                scanExpressionForADCRange(retStmt.value, adcConfig, filePath, diagnostics);
             }
             break;
         }
@@ -190,7 +204,7 @@ function scanStatementForADCRange(stmt, adcConfig, diagnostics) {
             const call = stmt;
             if (call.args) {
                 for (const arg of call.args) {
-                    scanExpressionForADCRange(arg, adcConfig, diagnostics);
+                    scanExpressionForADCRange(arg, adcConfig, filePath, diagnostics);
                 }
             }
             break;
@@ -214,7 +228,7 @@ export function validateADCRange(program, boardConstants) {
     // Scan top-level statements
     if (program.topLevelStatements) {
         for (const stmt of program.topLevelStatements) {
-            scanStatementForADCRange(stmt, adcConfig, diagnostics);
+            scanStatementForADCRange(stmt, adcConfig, program.fileName, diagnostics);
         }
     }
     // Scan function bodies
@@ -222,7 +236,7 @@ export function validateADCRange(program, boardConstants) {
         for (const fn of program.functions) {
             if (fn.statements) {
                 for (const stmt of fn.statements) {
-                    scanStatementForADCRange(stmt, adcConfig, diagnostics);
+                    scanStatementForADCRange(stmt, adcConfig, program.fileName, diagnostics);
                 }
             }
         }
@@ -234,14 +248,14 @@ export function validateADCRange(program, boardConstants) {
                 for (const method of cls.methods) {
                     if (method.statements) {
                         for (const stmt of method.statements) {
-                            scanStatementForADCRange(stmt, adcConfig, diagnostics);
+                            scanStatementForADCRange(stmt, adcConfig, program.fileName, diagnostics);
                         }
                     }
                 }
             }
             if (cls.constructor?.statements) {
                 for (const stmt of cls.constructor.statements) {
-                    scanStatementForADCRange(stmt, adcConfig, diagnostics);
+                    scanStatementForADCRange(stmt, adcConfig, program.fileName, diagnostics);
                 }
             }
         }

package/dist/ir/build-ir-state.d.ts

@@ -78,6 +78,7 @@ export declare class CompilationContext {
     floatVariables: Set<string>;
     snprintfCounter: number;
     callbackPlaceholderCounter: number;
+    bleCharCounter: number;
     activeStrategy: PlatformStrategy | null;
     restParamFunctions: Map<string, string>;
     /**

package/dist/ir/build-ir-state.js

@@ -65,6 +65,12 @@ export class CompilationContext {
         this.floatVariables = new Set();
         this.snprintfCounter = 0;
         this.callbackPlaceholderCounter = 0;
+        // BLE characteristic index counter — persists across separate Ble.server()
+        // calls so a multi-characteristic server (one server() per char, the common
+        // ble-demo pattern) gets unique sequential indices instead of every char
+        // clobbering slot 0. Read by the server()/characteristic() resolver branches
+        // in hal-parser.ts. Reset per file in hal-emitter.ts with the other counters.
+        this.bleCharCounter = 0;
         this.activeStrategy = null;
         this.restParamFunctions = new Map();
         /**
@@ -246,6 +252,14 @@ export function setCurrentBoardConstants(v) {
                 pinAliasMap.set(name, num);
                 mcuPinForwardMap.set(name, num);
                 mcuPinReverseMap.set(num, name);
+                // Register an identifier-safe variant so that pins whose canonical
+                // name is not a legal JS identifier (e.g. nRF52840 "P0.28") can be
+                // imported under their underscore form (P0_28). See "Pin Naming
+                // Conventions" in the root AGENTS.md.
+                const identName = name.replace(/[.\s-]/g, "_");
+                if (identName !== name) {
+                    pinAliasMap.set(identName, num);
+                }
             }
         }
     }

package/dist/ir/build-ir.js

@@ -144,7 +144,11 @@ export function buildProgramIR(fileName, sourceText, boardPackage, prebuiltClass
     const parentStrategy = getContext().activeStrategy;
     return contextStorage.run(new CompilationContext(), () => {
         getContext().activeStrategy = parentStrategy;
-        loadHALModules(true); // Parse HAL source files (force reload to pick up changes)
+        // Ensure HAL modules are loaded. transpile.ts warms the HAL registry once
+        // per transpile run (before the per-file IR build), so this is normally a
+        // cheap no-op. The non-forced call is a safety net for direct/test callers
+        // of buildProgramIR that didn't warm the registry first.
+        loadHALModules();
         const normalizedSourceText = normalizeEntrypointSyntax(sourceText);
         const source = parseSource(fileName, normalizedSourceText);
         const diagnostics = [];
@@ -439,14 +443,14 @@ export function buildProgramIR(fileName, sourceText, boardPackage, prebuiltClass
                         }
                     }
                 }
-                // Track HAL instances imported from board packages and framework stubs
-                // so the HAL resolver can resolve them to Arduino C++ names.
+                // Track HAL instances imported from board packages and framework HAL
+                // subpaths so the HAL resolver can resolve them to framework C++ names.
                 // The `@typecad/board` virtual import resolves to the board package, so it
                 // also registers pin aliases (LED, etc.). Case-insensitive on the scope.
                 const lowerSpecifier = moduleSpecifier.toLowerCase();
                 const isHALSource = lowerSpecifier.startsWith('@typecad/board-')
-                    || lowerSpecifier === '@typecad/framework-arduino/arduino'
-                    || lowerSpecifier === '@typecad/board';
+                    || lowerSpecifier === '@typecad/board'
+                    || /^@typecad\/framework-[a-z0-9-]+\/(arduino|hal|gpio)$/.test(lowerSpecifier);
                 // UI authoring namespace: `import { ui } from "@typecad/ui"`. The `ui`
                 // value is a compile-time construct (its calls are intercepted by
                 // tryResolveUICall); it must NOT be emitted as a C++ struct/value.

package/dist/ir/call-graph.js

@@ -159,6 +159,22 @@ export function buildCallGraph(program) {
             }
         }
     }
+    // Registered callbacks from the HAL resolver (e.g. the arrow function passed
+    // to `Ble.characteristic(...).onRead(() => readTemp())`) are NOT present in
+    // top-level statements — they ride in `program.registeredCallbacks` and are
+    // later hoisted to file-scope `*_isr_*` functions by top-level-prep. The
+    // placeholder name (`__CALLBACK_N__`) is what surfaces in top-level deps,
+    // not the identifiers the callback body references (e.g. a free function
+    // like `readTemp`). Without this scan those references are invisible to the
+    // call graph: the function survives the hoist (its call sits inside the
+    // emitted ISR) but is tree-shaken as unreachable, and g++ later reports it
+    // "not declared in this scope". Attach their body identifiers to
+    // __top_level__ since the callbacks execute from the top-level entry path.
+    for (const rc of (program.registeredCallbacks ?? [])) {
+        for (const id of collectExpressionIdentifiers(rc.callbackIR)) {
+            topLevelDependencies.add(id);
+        }
+    }
     nodes.set("__top_level__", {
         name: "__top_level__",
         kind: "variable",