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

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

@@ -4,6 +4,7 @@
  * Extracted from cpp-emitter.ts
  */
 import { escapeCppStringLiteral } from "../../utils/strings.js";
+import { routeHALOp } from "../route-hal-op.js";
 /**
  * Converts a string to PascalCase.
  * Used for generating class names from function names.
@@ -53,6 +54,20 @@ export function generateAsyncTaskClass(fnName, fnStatements, strategy, knownFunc
             segments.push({ preStatements: currentPre, awaitedCallee: stmt.callee, awaitedArgs: stmt.args });
             currentPre = [];
         }
+        else if (
+        // Chained HAL calls (e.g. `await Http.get(url).send()`) resolve to a
+        // block of hal-ops whose LAST statement is the awaited wait marker.
+        // Flatten it so the split sees the marker; the leading ops (begin,
+        // setters) run as pre-statements of the same segment.
+        stmt.kind === "block" &&
+            stmt.body.length > 0 &&
+            stmt.body[stmt.body.length - 1].kind === "call" &&
+            stmt.body[stmt.body.length - 1].isAwaited) {
+            const last = stmt.body[stmt.body.length - 1];
+            currentPre.push(...stmt.body.slice(0, -1));
+            segments.push({ preStatements: currentPre, awaitedCallee: last.callee, awaitedArgs: last.args });
+            currentPre = [];
+        }
         else {
             currentPre.push(stmt);
         }
@@ -61,11 +76,23 @@ export function generateAsyncTaskClass(fnName, fnStatements, strategy, knownFunc
     segments.push({ preStatements: currentPre, awaitedArgs: [] });
     const awaitCount = segments.filter((s) => s.awaitedCallee !== undefined).length;
     const stateCount = awaitCount + 1; // STATE_0 … STATE_{awaitCount}; cyclic loops back, linear adds STATE_DONE
+    // State enum is emitted as `enum class State` (AUTOSAR A7-2-1), so all
+    // references must be scope-qualified as `State::STATE_X`. The stateEnumList
+    // (used inside `enum class State { ... }`) uses the bare names; everywhere
+    // else (assignments, case labels, comparisons) uses the qualified form.
     const stateNames = [];
-    for (let i = 0; i < stateCount; i++)
+    const qualifiedStateNames = [];
+    for (let i = 0; i < stateCount; i++) {
         stateNames.push(`STATE_${i}`);
-    if (!isCyclic)
+        qualifiedStateNames.push(`State::STATE_${i}`);
+    }
+    if (!isCyclic) {
         stateNames.push("STATE_DONE");
+        qualifiedStateNames.push("State::STATE_DONE");
+    }
+    const Q = (i) => qualifiedStateNames[i];
+    const Q_DONE = "State::STATE_DONE";
+    const Q_0 = "State::STATE_0";
     // Helper: render a non-await statement as a single C++ line
     const renderStmt = (stmt) => renderStatement(stmt, false, strategy, undefined, undefined, knownFunctionReturnTypes);
     // Collect edge-detection markers from segments
@@ -101,16 +128,74 @@ export function generateAsyncTaskClass(fnName, fnStatements, strategy, knownFunc
             tapMembers.set(member, i);
         }
     }
+    // Collect net-wait (WiFi/HTTP/HAL) markers: awaited hal-ops rewritten to
+    // __WIFI_WAIT__/__HTTP_WAIT__/__HAL_WAIT__ calls carrying the op as a
+    // hal-expr arg. The strategy lowers the op to start code + poll condition.
+    const netInfoMap = new Map();
+    for (let i = 0; i < segments.length; i++) {
+        const seg = segments[i];
+        if ((seg.awaitedCallee === "__WIFI_WAIT__" || seg.awaitedCallee === "__HTTP_WAIT__" || seg.awaitedCallee === "__BLE_WAIT__" || seg.awaitedCallee === "__HAL_WAIT__") &&
+            seg.awaitedArgs[0]?.kind === "hal-expr") {
+            const op = seg.awaitedArgs[0].operation;
+            netInfoMap.set(i, netWaitInfo(op, strategy));
+        }
+    }
+    // ── Render each state ──────────────────────────────────────────────────
+    // Decomposition: a state's ENTRY condition comes from the await that ended
+    // the PREVIOUS segment (edge / tap / net poll / timed deadline); once the
+    // condition fires, the segment body runs and the await ending THIS segment
+    // is armed (pin snapshot / tap snapshot / net start op / deadline).
+    // Lines that arm the await ending segment i and advance the state.
+    const armNextLines = (i, pad) => {
+        const seg = segments[i];
+        const lines = [];
+        if (seg.awaitedCallee === undefined) {
+            lines.push(`${pad}_state = ${isCyclic ? Q_0 : Q_DONE};`);
+            return lines;
+        }
+        const edge = edgeInfoMap.get(i);
+        const tap = tapInfoMap.get(i);
+        const net = netInfoMap.get(i);
+        if (edge) {
+            lines.push(`${pad}_edgePrev_p${edge.pin} = ${strategy.readDigitalPin?.(String(edge.pin)) ?? `digitalRead(${edge.pin})`};`);
+            if (edge.timeout !== null) {
+                lines.push(`${pad}_waitUntil = ${strategy.currentTimeMillis()} + ${edge.timeout};`);
+            }
+        }
+        else if (tap) {
+            lines.push(`${pad}_tapPrev_${i} = __ui_tap_seq;`);
+        }
+        else if (net) {
+            for (const startLine of net.startLines)
+                lines.push(`${pad}${startLine}`);
+            if (net.timeoutExpr !== null) {
+                lines.push(`${pad}_waitUntil = ${strategy.currentTimeMillis()} + ${net.timeoutExpr};`);
+            }
+        }
+        else {
+            // Plain timed wait (await delay(ms)) — arm its deadline.
+            const ms = seg.awaitedArgs[0] ? renderExpression(seg.awaitedArgs[0], strategy) : "0";
+            lines.push(`${pad}_waitUntil = ${strategy.currentTimeMillis()} + ${ms};`);
+        }
+        lines.push(`${pad}_state = ${Q(i + 1)};`);
+        return lines;
+    };
     const caseLines = [];
     for (let i = 0; i < segments.length; i++) {
         const seg = segments[i];
-        const stateName = `STATE_${i}`;
-        const isTerminal = seg.awaitedCallee === undefined;
+        const stateName = Q(i);
         const body = [];
-        const edgeSetup = edgeInfoMap.get(i);
         const edgePoll = i > 0 ? edgeInfoMap.get(i - 1) : undefined;
-        const tapSetup = tapInfoMap.get(i);
         const tapPoll = i > 0 ? tapInfoMap.get(i - 1) : undefined;
+        const netPoll = i > 0 ? netInfoMap.get(i - 1) : undefined;
+        // Segment body + arming of the next await, at the given indent.
+        const runSegment = (pad) => {
+            const lines = [];
+            for (const stmt of seg.preStatements)
+                lines.push(`${pad}${renderStmt(stmt)}`);
+            lines.push(...armNextLines(i, pad));
+            return lines;
+        };
         if (edgePoll) {
             // Poll state: check pin transition via digitalRead
             const prevVar = `_edgePrev_p${edgePoll.pin}`;
@@ -121,56 +206,15 @@ export function generateAsyncTaskClass(fnName, fnStatements, strategy, knownFunc
                 ? `(${cond}) || ${strategy.currentTimeMillis()} >= _waitUntil`
                 : cond;
             body.push(`        {`);
-            body.push(`          int _cur = digitalRead(${edgePoll.pin});`);
+            body.push(`          int _cur = ${strategy.readDigitalPin?.(String(edgePoll.pin)) ?? `digitalRead(${edgePoll.pin})`};`);
             body.push(`          if (${fullCond}) {`);
             body.push(`            ${prevVar} = _cur;`);
-            for (const stmt of seg.preStatements)
-                body.push(`            ${renderStmt(stmt)}`);
-            if (edgeSetup) {
-                // Next await is also edge detection — set up its pin tracking
-                body.push(`            _edgePrev_p${edgeSetup.pin} = digitalRead(${edgeSetup.pin});`);
-                if (edgeSetup.timeout !== null) {
-                    body.push(`            _waitUntil = ${strategy.currentTimeMillis()} + ${edgeSetup.timeout};`);
-                }
-                body.push(`            _state = STATE_${i + 1};`);
-            }
-            else if (!isTerminal) {
-                const ms = seg.awaitedArgs[0] ? renderExpression(seg.awaitedArgs[0], strategy) : "0";
-                body.push(`            _waitUntil = ${strategy.currentTimeMillis()} + ${ms};`);
-                body.push(`            _state = STATE_${i + 1};`);
-            }
-            else {
-                body.push(`            _state = ${isCyclic ? "STATE_0" : "STATE_DONE"};`);
-            }
+            body.push(...runSegment(`            `));
             body.push(`          } else {`);
             body.push(`            ${prevVar} = _cur;`);
             body.push(`          }`);
             body.push(`        }`);
         }
-        else if (edgeSetup) {
-            // Setup state: capture initial pin state before polling
-            const prevVar = `_edgePrev_p${edgeSetup.pin}`;
-            if (i === 0) {
-                for (const stmt of seg.preStatements)
-                    body.push(`        ${renderStmt(stmt)}`);
-                body.push(`        ${prevVar} = digitalRead(${edgeSetup.pin});`);
-                if (edgeSetup.timeout !== null) {
-                    body.push(`        _waitUntil = ${strategy.currentTimeMillis()} + ${edgeSetup.timeout};`);
-                }
-                body.push(`        _state = STATE_${i + 1};`);
-            }
-            else {
-                body.push(`        if (${strategy.currentTimeMillis()} >= _waitUntil) {`);
-                for (const stmt of seg.preStatements)
-                    body.push(`          ${renderStmt(stmt)}`);
-                body.push(`          ${prevVar} = digitalRead(${edgeSetup.pin});`);
-                if (edgeSetup.timeout !== null) {
-                    body.push(`          _waitUntil = ${strategy.currentTimeMillis()} + ${edgeSetup.timeout};`);
-                }
-                body.push(`          _state = STATE_${i + 1};`);
-                body.push(`        }`);
-            }
-        }
         else if (tapPoll) {
             // Tap-poll state: a previous segment ended with `await ui.onTap()`.
             // Wait until __ui_tap_seq bumps from the captured snapshot. A per-node
@@ -181,92 +225,42 @@ export function generateAsyncTaskClass(fnName, fnStatements, strategy, knownFunc
                 ? `__ui_tap_seq != ${prevVar}`
                 : `(__ui_tap_seq != ${prevVar}) && (__ui_tap_node == ${nodeFilter})`;
             body.push(`        if (${cond}) {`);
-            for (const stmt of seg.preStatements)
-                body.push(`          ${renderStmt(stmt)}`);
-            // What does the NEXT await (ending this segment) look like? Re-derive
-            // from the maps via a fresh lookup so TS doesn't narrow edgeSetup away.
-            const nextEdge = edgeInfoMap.get(i) ?? null;
-            if (tapSetup) {
-                // Next await is also a tap — capture its snapshot now.
-                body.push(`          _tapPrev_${i} = __ui_tap_seq;`);
-                body.push(`          _state = STATE_${i + 1};`);
-            }
-            else if (nextEdge) {
-                body.push(`          _edgePrev_p${nextEdge.pin} = digitalRead(${nextEdge.pin});`);
-                if (nextEdge.timeout !== null) {
-                    body.push(`          _waitUntil = ${strategy.currentTimeMillis()} + ${nextEdge.timeout};`);
-                }
-                body.push(`          _state = STATE_${i + 1};`);
-            }
-            else if (!isTerminal) {
-                // Next await is a normal timed wait (delay) — arm its deadline.
-                const ms = seg.awaitedArgs[0] ? renderExpression(seg.awaitedArgs[0], strategy) : "0";
-                body.push(`          _waitUntil = ${strategy.currentTimeMillis()} + ${ms};`);
-                body.push(`          _state = STATE_${i + 1};`);
-            }
-            else {
-                body.push(`          _state = ${isCyclic ? "STATE_0" : "STATE_DONE"};`);
-            }
+            body.push(...runSegment(`          `));
             body.push(`        }`);
         }
-        else if (tapSetup && !edgePoll) {
-            // Tap-setup state: this segment ends with `await ui.onTap()`. Capture the
-            // current tap counter so the poll state can detect the NEXT bump.
-            // (edgePoll takes precedence when the previous await was an edge.)
-            if (i === 0) {
-                for (const stmt of seg.preStatements)
-                    body.push(`        ${renderStmt(stmt)}`);
-                body.push(`        _tapPrev_${i} = __ui_tap_seq;`);
-                body.push(`        _state = STATE_${i + 1};`);
-            }
-            else {
-                body.push(`        if (${strategy.currentTimeMillis()} >= _waitUntil) {`);
-                for (const stmt of seg.preStatements)
-                    body.push(`          ${renderStmt(stmt)}`);
-                body.push(`          _tapPrev_${i} = __ui_tap_seq;`);
-                body.push(`          _state = STATE_${i + 1};`);
-                body.push(`        }`);
-            }
+        else if (netPoll) {
+            // Net-poll state: a previous segment ended with an awaited WiFi/HTTP
+            // op. Wait until its poll condition fires (or its deadline expires).
+            const deadline = `${strategy.currentTimeMillis()} >= _waitUntil`;
+            const cond = netPoll.pollCond === null
+                ? deadline
+                : netPoll.timeoutExpr !== null
+                    ? `(${netPoll.pollCond}) || ${deadline}`
+                    : netPoll.pollCond;
+            body.push(`        if (${cond}) {`);
+            body.push(...runSegment(`          `));
+            body.push(`        }`);
+        }
+        else if (i === 0) {
+            // First state runs immediately.
+            body.push(...runSegment(`        `));
         }
         else {
-            // Normal timed-wait state
-            if (i === 0) {
-                for (const stmt of seg.preStatements)
-                    body.push(`        ${renderStmt(stmt)}`);
-                if (!isTerminal) {
-                    const ms = seg.awaitedArgs[0] ? renderExpression(seg.awaitedArgs[0], strategy) : "0";
-                    body.push(`        _waitUntil = ${strategy.currentTimeMillis()} + ${ms};`);
-                    body.push(`        _state = STATE_${i + 1};`);
-                }
-                else {
-                    body.push(`        _state = ${isCyclic ? "STATE_0" : "STATE_DONE"};`);
-                }
-            }
-            else {
-                body.push(`        if (${strategy.currentTimeMillis()} >= _waitUntil) {`);
-                for (const stmt of seg.preStatements)
-                    body.push(`          ${renderStmt(stmt)}`);
-                if (!isTerminal) {
-                    const ms = seg.awaitedArgs[0] ? renderExpression(seg.awaitedArgs[0], strategy) : "0";
-                    body.push(`          _waitUntil = ${strategy.currentTimeMillis()} + ${ms};`);
-                    body.push(`          _state = STATE_${i + 1};`);
-                }
-                else {
-                    body.push(`          _state = ${isCyclic ? "STATE_0" : "STATE_DONE"};`);
-                }
-                body.push(`        }`);
-            }
+            // Previous await was a plain timed wait — poll its deadline.
+            body.push(`        if (${strategy.currentTimeMillis()} >= _waitUntil) {`);
+            body.push(...runSegment(`          `));
+            body.push(`        }`);
         }
         caseLines.push(`      case ${stateName}:`, `        {`, ...body, `        }`, `        break;`);
     }
     if (!isCyclic)
-        caseLines.push(`      case STATE_DONE:`, `        break;`);
+        caseLines.push(`      case ${Q_DONE}:`, `        break;`);
     const stateEnumList = stateNames.join(", ");
-    const isCompleteExpr = isCyclic ? "false" : "_state == STATE_DONE";
+    const isCompleteExpr = isCyclic ? "false" : `_state == ${Q_DONE}`;
     // Build constructor initializer list and edge/tap member declarations
     const edgeMemberArr = Array.from(edgeMembers);
     const tapMemberArr = Array.from(tapMembers.keys());
-    const inits = [`_state(STATE_0)`, `_waitUntil(0)`];
+    const inits = [`_state(${Q_0})`, `_waitUntil(0)`];
     for (const m of edgeMemberArr)
         inits.push(`${m}(LOW)`);
     for (const m of tapMemberArr)
@@ -281,7 +275,7 @@ export function generateAsyncTaskClass(fnName, fnStatements, strategy, knownFunc
         `// Async state machine for ${fnName}`,
         `class ${className} {`,
         `public:`,
-        `  enum State { ${stateEnumList} };`,
+        `  enum class State { ${stateEnumList} };`,
         `  ${className}() : ${ctorInitList} {}`,
         `  void run() {`,
         `    switch (_state) {`,
@@ -289,7 +283,7 @@ export function generateAsyncTaskClass(fnName, fnStatements, strategy, knownFunc
         `    }`,
         `  }`,
         `  bool isComplete() const { return ${isCompleteExpr}; }`,
-        `  void reset() { _state = STATE_0; _waitUntil = 0;${edgeResetList}${tapResetList} }`,
+        `  void reset() { _state = ${Q_0}; _waitUntil = 0;${edgeResetList}${tapResetList} }`,
         `private:`,
         `  State _state;`,
         `  unsigned long _waitUntil;`,
@@ -331,6 +325,108 @@ function renderExpression(expr, strategy) {
             return "/* complex expr */";
     }
 }
+/** Numeric-or-rendered HAL field → C++ text. */
+function ms(v) {
+    return String(v);
+}
+/** True when a timeout field is the literal 0 (wait forever, no deadline). */
+function isZeroTimeout(v) {
+    return v === undefined || v === null || String(v).trim() === "0";
+}
+/**
+ * Map an awaitable HAL op to its start statements + poll condition, lowering
+ * the start op and poll predicate through the platform strategy. Keep the set
+ * of handled ops in sync with AWAITABLE_HAL_OPS in ir/transformers/expressions.ts.
+ *
+ * Falls back to running the blocking form as the "start" with an immediate
+ * completion when the strategy can't lower the split ops.
+ */
+function netWaitInfo(op, strategy) {
+    const o = op;
+    const route = (routedOp) => routeHALOp(routedOp, strategy);
+    const expr = (operation) => route({ operation })?.expression ?? null;
+    switch (op.operation) {
+        case "timing.delay":
+            return { startLines: [], pollCond: null, timeoutExpr: ms(o.ms) };
+        case "wifi.connect": {
+            const start = route({ operation: "wifi.connect_start", ssid: o.ssid, password: o.password });
+            const poll = expr("wifi.is_connected");
+            if (start?.code && poll) {
+                return {
+                    startLines: [start.code],
+                    pollCond: poll,
+                    timeoutExpr: isZeroTimeout(o.timeoutMs) ? null : ms(o.timeoutMs),
+                };
+            }
+            break;
+        }
+        case "wifi.wait_connected": {
+            const poll = expr("wifi.is_connected");
+            if (poll) {
+                return {
+                    startLines: [],
+                    pollCond: poll,
+                    timeoutExpr: isZeroTimeout(o.timeoutMs) ? null : ms(o.timeoutMs),
+                };
+            }
+            break;
+        }
+        case "wifi.wait_disconnected": {
+            const poll = expr("wifi.is_connected");
+            if (poll) {
+                return { startLines: [], pollCond: `!${poll}`, timeoutExpr: null };
+            }
+            break;
+        }
+        case "wifi.scan": {
+            const start = route({ operation: "wifi.scan_start" });
+            const poll = expr("wifi.scan_done");
+            if (start?.code && poll) {
+                return { startLines: [start.code], pollCond: poll, timeoutExpr: null };
+            }
+            break;
+        }
+        case "http.send": {
+            const start = route({ operation: "http.send_start" });
+            const poll = expr("http.done");
+            if (start?.code && poll) {
+                return { startLines: [start.code], pollCond: poll, timeoutExpr: null };
+            }
+            break;
+        }
+        case "ble.until_connected": {
+            const start = route({ operation: "ble.until_connected_start" });
+            const poll = expr("ble.is_connected");
+            if (start?.code && poll) {
+                return {
+                    startLines: [start.code],
+                    pollCond: poll,
+                    timeoutExpr: isZeroTimeout(o.timeoutMs) ? null : ms(o.timeoutMs),
+                };
+            }
+            break;
+        }
+        case "worker.submit": {
+            // Worker offload (Phase 3). `await worker.submit(fn, arg)` rewrites to:
+            // submit the worker (start), then poll worker.done on the same handle.
+            // The submit op is emitted verbatim as the start line; the poll predicate
+            // is worker.done(handle) carrying the SAME handleId. This is a predicate-
+            // poll resume (same per-frame cost as net/timer awaits), NOT an ISR-driven
+            // resume — that defers with DMA-backed awaits.
+            const submit = routeHALOp(op, strategy);
+            // Carry the handle through to the poll so submit + done agree on the slot.
+            const poll = route({ operation: "worker.done", handleId: o.handleId })?.expression ?? null;
+            if (submit?.code && poll) {
+                return { startLines: [submit.code], pollCond: poll, timeoutExpr: null };
+            }
+            break;
+        }
+    }
+    // Fallback: run the blocking form immediately and complete on the next tick.
+    const blocking = routeHALOp(op, strategy);
+    const line = blocking?.code ?? (blocking?.expression ? `${blocking.expression};` : `/* unhandled awaited hal-op: ${op.operation} */`);
+    return { startLines: [line], pollCond: null, timeoutExpr: "0" };
+}
 function parseEdgeMarker(argText) {
     const match = argText.match(/^__EDGE_(RISING|FALLING)__([a-zA-Z0-9_]+)__T(.*)$/);
     if (!match)

package/dist/emit/utils/hal-op-cpp-type.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Best-effort C++ return type for a HAL expression op.
+ * Used by snprintf format inference and expression type inference so
+ * string-returning ops (e.g. wifi.scan_ssid → const char*) use %s, not %d.
+ */
+export declare function cppTypeForHalOp(operation: string): string | undefined;

package/dist/emit/utils/hal-op-cpp-type.js

@@ -0,0 +1,40 @@
+/**
+ * Best-effort C++ return type for a HAL expression op.
+ * Used by snprintf format inference and expression type inference so
+ * string-returning ops (e.g. wifi.scan_ssid → const char*) use %s, not %d.
+ */
+export function cppTypeForHalOp(operation) {
+    switch (operation) {
+        case "wifi.local_ip":
+        case "wifi.mac":
+        case "wifi.ap_ip":
+        case "wifi.scan_ssid":
+        case "http.body":
+        case "http.response_header":
+            return "const char*";
+        case "wifi.is_connected":
+        case "wifi.connect":
+        case "wifi.wait_connected":
+        case "wifi.scan_done":
+        case "wifi.ap_start":
+        case "wifi.connect_saved":
+        case "http.ok":
+        case "http.done":
+            return "bool";
+        case "wifi.status":
+        case "wifi.rssi":
+        case "wifi.scan":
+        case "wifi.scan_count":
+        case "wifi.scan_rssi":
+        case "wifi.scan_encryption":
+        case "wifi.scan_channel":
+        case "wifi.ap_client_count":
+        case "http.status":
+        case "http.content_length":
+            return "int";
+        case "http.send":
+            return "bool";
+        default:
+            return undefined;
+    }
+}

package/dist/framework-package.js

@@ -50,6 +50,8 @@ export function loadFrameworkPackage(packageName, fromDir = process.cwd()) {
             } : undefined,
             classNameMapBuilder: typeof mod.buildClassNameMap === "function" ? mod.buildClassNameMap : undefined,
             libDeclGenerator: typeof mod.tryGenerateLibDecl === "function" ? mod.tryGenerateLibDecl : undefined,
+            doctor: typeof mod.doctor === "function" ? mod.doctor : undefined,
+            licenses: typeof mod.licenses === "function" ? mod.licenses : undefined,
         };
         setLoadedFramework(framework);
         registerPlatformStrategy(strategy);

package/dist/framework-registry.d.ts

@@ -14,6 +14,16 @@ export interface LoadedFramework {
     classNameMapBuilder?: (imports: any[]) => Map<string, string>;
     /** Framework library .d.ts declaration generation */
     libDeclGenerator?: (modulePath: string, file: string) => string | undefined;
+    /**
+     * Optional subcommand presenters owned by the framework. Cuttlefish dispatches
+     * `cuttlefish doctor` / `cuttlefish licenses` to these when the loaded
+     * framework provides them; otherwise it prints a no-support message. Each
+     * framework decides what (if anything) these do — e.g. framework-arduino
+     * checks arduino-cli + board core (doctor) and scans Arduino library licenses
+     * (licenses).
+     */
+    doctor?: () => void;
+    licenses?: (strict: boolean, all: boolean) => void;
 }
 /**
  * Resolves framework-specific library imports (e.g., Arduino libraries).
@@ -32,6 +42,13 @@ export interface FrameworkToolchain {
     compile(options: ToolchainOptions): CompileResult;
     upload?(options: ToolchainOptions): UploadResult;
     monitor?(options: ToolchainOptions): void;
+    /**
+     * Optional: launch an interactive debugger session for the last build
+     * (e.g. `west debug`). Not invoked by the standard build/compile flow;
+     * powers an explicit debug-attach entry point. Frameworks that support
+     * source-level debugging implement this to spawn their native debugger.
+     */
+    debug?(options: ToolchainOptions): void;
 }
 export declare function setLoadedFramework(framework: LoadedFramework): void;
 export declare function getLoadedFramework(): LoadedFramework;

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;
 }

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",