@typecad/framework-zephyr 1.0.0-alpha.16 → 1.0.0-alpha.19

package/dist/strategy.js

@@ -25,6 +25,22 @@ import { syncBoardCatalog, ensureFreshBoardCatalog, } from './sdk/board-catalog-
 import { setActiveChip, NO_BOARD_CHIP } from './chips/index.js';
 import { resolveChipFromBoard } from './chips/resolve.js';
 import { emitGpioDevDispatcher } from './chips/controllers.js';
+/**
+ * Visit the program's transpile-resolved HAL ops with the same `visit` the IR
+ * walk uses. A HAL call inlined into another HAL call's template literal
+ * (`USB0.writeLine(\`n: ${gps.available()}\`)`) is lowered to C++ text while
+ * the IR is built — it never becomes a hal-op/hal-expr IR node, so the walk
+ * alone cannot see it. Such ops ride on ProgramIR.resolvedHalOps; wrapped as
+ * `{ operation: op }` they match the hal-op node shape every collector below
+ * tests for. Without this fold, shims keyed on these scans (UART RX rings,
+ * sensor device handles, per-controller bus state, ADC channels/overrides,
+ * dt specs) go undeclared while the baked text still references them — the
+ * `'__tc_dt_led0' was not declared` failure class.
+ */
+function visitResolvedHalOps(program, visit) {
+    for (const op of program?.resolvedHalOps ?? [])
+        visit({ operation: op });
+}
 /**
  * Deep-walk the program IR and collect the HAL pin numbers the program
  * actually touches for a peripheral family ('adc' | 'pwm') — the same walk
@@ -64,6 +80,7 @@ function collectUsedPins(program, kind, chip) {
         }
     };
     visit(program);
+    visitResolvedHalOps(program, visit);
     return pins;
 }
 /**
@@ -99,6 +116,7 @@ function collectAdcOverrideDevices(program) {
         }
     };
     visit(program);
+    visitResolvedHalOps(program, visit);
     return devices;
 }
 /**
@@ -136,6 +154,7 @@ function collectPwmOverrideSpecs(program) {
         }
     };
     visit(program);
+    visitResolvedHalOps(program, visit);
     return specs;
 }
 /**
@@ -149,6 +168,66 @@ function collectPwmOverrideSpecs(program) {
  * -Wunused-variable (Zephyr builds with warnings-as-errors), the same
  * hygiene collectUsedPins enforces for per-channel ADC/PWM state.
  */
+/**
+ * Strips the program drives, keyed by SPI controller index → the
+ * construction chain length (the buffer size). Collected from strip.* ops.
+ */
+/** Which HID protocol the program drives — 'mixed' when verbs from BOTH
+ *  classes appear (one interface per program is the v1 ceiling; the caller
+ *  turns mixed into a #error so the build names it clearly). */
+function collectHidProtocol(program) {
+    if (!program)
+        return undefined;
+    let kb = false;
+    let mouse = false;
+    const visit = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        const n = node;
+        const op = n.operation;
+        if (op && typeof op === 'object') {
+            const name = op.operation;
+            if (typeof name === 'string') {
+                if (name.startsWith('hid.kb_'))
+                    kb = true;
+                if (name.startsWith('hid.mouse_'))
+                    mouse = true;
+            }
+        }
+        for (const v of Object.values(n))
+            if (v && typeof v === 'object')
+                visit(v);
+    };
+    visit(program);
+    if (kb && mouse)
+        return 'mixed';
+    return kb ? 'keyboard' : mouse ? 'mouse' : undefined;
+}
+function collectStrips(program) {
+    if (!program)
+        return undefined;
+    const strips = new Map();
+    const visit = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        const n = node;
+        const op = n.operation;
+        if (op && typeof op === 'object') {
+            const o = op;
+            if (o.operation === 'strip.set_pixel' || o.operation === 'strip.fill' || o.operation === 'strip.show') {
+                const m = String(o.bus ?? '').match(/(\d+)$/);
+                const idx = m ? parseInt(m[1], 10) : 0;
+                const count = Number(o.count ?? 1) || 1;
+                strips.set(idx, Math.max(strips.get(idx) ?? 0, count));
+            }
+        }
+        for (const v of Object.values(n))
+            if (v && typeof v === 'object')
+                visit(v);
+    };
+    visit(program);
+    return strips;
+}
 function collectUsedBusIndices(program) {
     if (!program)
         return undefined;
@@ -185,6 +264,7 @@ function collectUsedBusIndices(program) {
         }
     };
     visit(program);
+    visitResolvedHalOps(program, visit);
     return indices;
 }
 /**
@@ -213,9 +293,13 @@ export function collectSensors(program) {
                 const spiHz = o.spiHz ?? 0;
                 const spiMode = o.spiMode ?? 0;
                 const alertPin = o.alertPin ?? -1;
+                const resolution = o.resolution ?? 12;
                 const key = `${part}|${bus}|${port}|${busKind}`;
-                if (!sensors.has(key))
-                    sensors.set(key, { part, bus, port, busKind, spiHz, spiMode, alertPin });
+                const existing = sensors.get(key);
+                if (!existing)
+                    sensors.set(key, { part, bus, port, busKind, spiHz, spiMode, alertPin, resolution });
+                else if (o.resolution !== undefined)
+                    existing.resolution = resolution;
             }
         }
         for (const v of Object.values(n)) {
@@ -228,8 +312,176 @@ export function collectSensors(program) {
         }
     };
     visit(program);
+    visitResolvedHalOps(program, visit);
     return sensors;
 }
+/**
+ * The I2S construction facts the program's ops carry (the shim's slab and
+ * init helpers size from these) — first-seen wins, keyed by instance.
+ */
+export function collectI2s(program) {
+    if (!program)
+        return undefined;
+    const out = new Map();
+    const visit = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        const n = node;
+        const op = n.operation;
+        if (op && typeof op === 'object') {
+            const o = op;
+            const name = o.operation;
+            if (name === 'i2s.write' || name === 'i2s.read') {
+                // Raw instance (no clamp): the strategy loop folds usage through
+                // lowerI2s's clamp, so the facts must stay keyed by what the ops
+                // actually carry.
+                const inst = Number(o.instance ?? 0);
+                if (!out.has(inst)) {
+                    out.set(inst, {
+                        hz: Number(o.hz ?? 16000),
+                        channels: Number(o.channels ?? 2),
+                        bits: Number(o.bits ?? 16),
+                        blockFrames: Number(o.blockFrames ?? 64),
+                    });
+                }
+            }
+        }
+        for (const v of Object.values(n)) {
+            if (Array.isArray(v)) {
+                for (const item of v)
+                    visit(item);
+            }
+            else if (v && typeof v === 'object')
+                visit(v);
+        }
+    };
+    visit(program);
+    visitResolvedHalOps(program, visit);
+    return out;
+}
+/**
+ * Which can / i2s / clock verbs the program's ops actually use — the init
+ * blocks emit only the state those verbs reference (Zephyr's -Werror turns
+ * an unreferenced static function/variable into a build failure: a
+ * send-only CAN program must not carry the rx trampoline, a now()-only
+ * Clock program must not carry the set() conversion helper). Returns
+ * undefined when there is no program to scan (probe flows) — callers then
+ * fall back to emitting every controller with the full state set.
+ */
+export function collectVerbUsage(program) {
+    if (!program)
+        return undefined;
+    const out = {
+        can: new Map(),
+        i2s: new Map(),
+        clock: { set: false, now: false },
+    };
+    const canFlags = (inst) => {
+        let f = out.can.get(inst);
+        if (!f) {
+            f = { begin: false, send: false, onReceive: false };
+            out.can.set(inst, f);
+        }
+        return f;
+    };
+    const i2sFlags = (inst) => {
+        let f = out.i2s.get(inst);
+        if (!f) {
+            f = { write: false, read: false, readAt: false };
+            out.i2s.set(inst, f);
+        }
+        return f;
+    };
+    const visit = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        const n = node;
+        const op = n.operation;
+        if (op && typeof op === 'object') {
+            const o = op;
+            const name = o.operation;
+            const inst = Number(o.instance ?? 0);
+            switch (name) {
+                case 'can.begin':
+                    canFlags(inst).begin = true;
+                    break;
+                case 'can.send':
+                    canFlags(inst).send = true;
+                    break;
+                case 'can.on_receive':
+                    canFlags(inst).onReceive = true;
+                    break;
+                case 'i2s.write':
+                    i2sFlags(inst).write = true;
+                    break;
+                case 'i2s.read':
+                    i2sFlags(inst).read = true;
+                    break;
+                case 'i2s.read_at':
+                    i2sFlags(inst).readAt = true;
+                    break;
+                case 'clock.set':
+                    out.clock.set = true;
+                    break;
+                case 'clock.now':
+                    out.clock.now = true;
+                    break;
+                default: break;
+            }
+        }
+        for (const v of Object.values(n)) {
+            if (Array.isArray(v)) {
+                for (const item of v)
+                    visit(item);
+            }
+            else if (v && typeof v === 'object')
+                visit(v);
+        }
+    };
+    visit(program);
+    visitResolvedHalOps(program, visit);
+    return out;
+}
+/**
+ * Collect the distinct I2C responders the program's ops reference
+ * (i2c.resp_*), keyed `${bus}|${address}` — one target-mode address per
+ * constructed responder. Mirrors collectSpiTargets: the construction facts
+ * (rx/tx sizes) ride every op, so the first seen wins and the state block
+ * cannot drift from the call sites.
+ */
+export function collectI2cResponders(program) {
+    if (!program)
+        return undefined;
+    const responders = new Map();
+    const visit = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        const n = node;
+        const op = n.operation;
+        if (op && typeof op === 'object') {
+            const o = op;
+            if (String(o.operation).startsWith('i2c.resp_')) {
+                const bus = String(o.bus ?? '');
+                const address = Number(o.address ?? 0);
+                const key = `${bus}|${address}`;
+                if (!responders.has(key)) {
+                    responders.set(key, { bus, address, rx: Number(o.rx ?? 64), tx: Number(o.tx ?? 32) });
+                }
+            }
+        }
+        for (const v of Object.values(n)) {
+            if (Array.isArray(v)) {
+                for (const item of v)
+                    visit(item);
+            }
+            else if (v && typeof v === 'object')
+                visit(v);
+        }
+    };
+    visit(program);
+    visitResolvedHalOps(program, visit);
+    return responders;
+}
 /**
  * Collect the distinct thin SPI targets the program's ops reference
  * (spi.transceive / spi.dev_write), keyed `${bus}|${cs}`. Mirrors
@@ -266,6 +518,7 @@ export function collectSpiTargets(program) {
         }
     };
     visit(program);
+    visitResolvedHalOps(program, visit);
     return targets;
 }
 /**
@@ -305,6 +558,7 @@ export function collectUartRings(program) {
         }
     };
     visit(program);
+    visitResolvedHalOps(program, visit);
     return rings;
 }
 /**
@@ -339,6 +593,7 @@ export function collectThreads(program) {
         }
     };
     visit(program);
+    visitResolvedHalOps(program, visit);
     return threads;
 }
 import { lowerHalOp } from './lowering/index.js';
@@ -347,10 +602,18 @@ import { pwmInitLines } from './lowering/pwm.js';
 import { dacInitLines } from './lowering/dac.js';
 import { fsInitLines } from './lowering/fs.js';
 import { hwtimerInitLines } from './lowering/hwtimer.js';
-import { i2cInitLines } from './lowering/i2c.js';
+import { i2cInitLines, i2cResponderStateLines } from './lowering/i2c.js';
+import { parseControllerIndex } from './lowering/util.js';
+import { stripInitLines } from './lowering/strip.js';
+import { hidInitLines } from './lowering/hid.js';
+import { matrixInitLines } from './lowering/matrix.js';
+import { clockInitLines } from './lowering/clock.js';
+import { canInitLines } from './lowering/can.js';
+import { i2sInitLines } from './lowering/i2s.js';
 import { sensorStateLines } from './lowering/sensor.js';
 import { spiTargetStateLines } from './lowering/spi.js';
 import { threadStateLines } from './lowering/thread.js';
+import { traceHeartbeatLines, uiFrameTraceLines, clampTraceIntervalMs } from './lowering/trace.js';
 import { uartRingStateLines } from './lowering/uart.js';
 import { spiInitLines } from './lowering/spi.js';
 import { uartInitLines } from './lowering/uart.js';
@@ -385,13 +648,16 @@ import { httpInitLines } from './lowering/http.js';
 import { mqttInitLines } from './lowering/mqtt.js';
 import { preferencesInitLines } from './lowering/preferences.js';
 import { randomInitLines } from './lowering/random.js';
-import { generateZephyrInitCode, generateZephyrBreakpointCode, generateZephyrLogpointCode } from './debug-codegen.js';
 import { generateStaticAsyncRuntime } from '@typecad/cuttlefish/api/shared';
 import { resolveZephyrDisplayOp, newDisplayState } from './display/index.js';
 import { buildDisplayRuntime } from './display/gfx.js';
-import { ZEPHYR_DISPLAY_PROFILES, BUILT_IN_PROFILES } from './display/profiles.js';
+import { ZEPHYR_DISPLAY_PROFILES, BUILT_IN_PROFILES, isDtCompatible, isMonoDisplay, isGrayDisplay, isEinkDisplay } from './display/profiles.js';
+import { listBoundDisplayCompatibles } from './display/bindings.js';
 import { zephyrDisplayAdapterGenerator } from './display/ui-adapter.js';
 import { zephyrTouchAdapter } from './display/touch-adapter.js';
+/** debugMode() memo — the boardgen facts lookup is not free and the method is
+ *  called several times per build (transpile gate + artifact writers). */
+const debugModeMemo = new Map();
 export class ZephyrStrategy {
     constructor() {
         this.id = 'zephyr';
@@ -437,22 +703,7 @@ export class ZephyrStrategy {
         setActiveChip(fromBoard ?? NO_BOARD_CHIP);
         return fromBoard ?? NO_BOARD_CHIP;
     }
-    /**
-     * Resolve the debug mode for the active target from the platform context.
-     * Mirrors resolveChip's target extraction so shimLines/forcedIncludes can
-     * gate the printf halt shim + console UART include to printf builds only
-     * (gdb builds use VS Code native breakpoints + #line markers, so the
-     * __tc_debug_wait_for_continue shim and its <zephyr/drivers/uart.h> include
-     * are dead code there).
-     */
-    resolveDebugMode(ctx) {
-        const fd = ctx?.frameworkData;
-        const target = fd?.target ??
-            fd?.buildTarget;
-        return this.debugMode(target);
-    }
     forcedIncludes(_program, ctx) {
-        const isPrintf = this.resolveDebugMode(ctx) === 'printf';
         // <zephyr/kernel.h> for k_msleep / k_uptime_get_32 / k_busy_wait / printk.
         // <zephyr/drivers/gpio.h> for the gpio_pin_*_dt / gpio_dt_spec API.
         // <cstdint> because DIRECT_CPP_TYPE_MAP passes int32_t/uint8_t through
@@ -473,7 +724,7 @@ export class ZephyrStrategy {
         // passes int32_t/uint8_t through verbatim.
         const inc = ['<zephyr/kernel.h>', '<zephyr/drivers/gpio.h>', '<cstdint>'];
         // <cstdio> backs the printf family only: __tc_print/__tc_println (emitted
-        // solely when @typecad/expect's preprocessor injected them — tracked via
+        // solely when the test-runner preprocessor injected them — tracked via
         // usedPolyfillHelpers), raw printf/snprintf in user code (usesCstdio), and
         // the fs/preferences/uart shims (their lowerings snprintf into buffers).
         // A program touching none of those needs no <cstdio>.
@@ -489,14 +740,30 @@ export class ZephyrStrategy {
             inc.push('<zephyr/drivers/sensor.h>');
         if (uses('usesSPI'))
             inc.push('<zephyr/drivers/spi.h>');
+        if (uses('usesStrip'))
+            inc.push('<zephyr/drivers/led_strip.h>');
+        if (uses('usesHid')) {
+            inc.push('<zephyr/usb/class/hid.h>');
+            inc.push('<zephyr/usb/class/usbd_hid.h>');
+            inc.push('<zephyr/usb/usbd.h>');
+            inc.push('<zephyr/drivers/usb/usb_buf.h>');
+        }
+        if (uses('usesMatrix'))
+            inc.push('<zephyr/input/input.h>');
+        if (uses('usesPower'))
+            inc.push('<zephyr/sys/poweroff.h>');
+        // esp_sleep.h exists only on the espressif HAL — gate on the harvested
+        // RTC wake-timer fact (the includes' uses() reads op flags, not src).
+        if (uses('usesPower') && chip.powerWakeTimer)
+            inc.push('<esp_sleep.h>');
+        if (uses('usesClock'))
+            inc.push('<zephyr/drivers/rtc.h>');
+        if (uses('usesCan'))
+            inc.push('<zephyr/drivers/can.h>');
+        if (uses('usesI2s'))
+            inc.push('<zephyr/drivers/i2s.h>');
         if (uses('usesUart'))
             inc.push('<zephyr/drivers/uart.h>');
-        // uart.h is also needed by the printf-mode debug halt shim
-        // (__tc_debug_wait_for_continue polls the console UART) even when the
-        // program itself does not use the UART HAL. In gdb mode the shim is not
-        // emitted, so skip the include there to avoid pulling in an unused header.
-        if (isPrintf && !inc.includes('<zephyr/drivers/uart.h>'))
-            inc.push('<zephyr/drivers/uart.h>');
         // USB CDC serial: the class instance is a UART device (uart.h); the
         // device context macros + usbd_* API live in the next-stack header.
         if (uses('usesUsb')) {
@@ -550,10 +817,11 @@ export class ZephyrStrategy {
         // HTTP/S client: Zephyr's http_client_req runs over a pre-connected socket,
         // so the shim pulls in the BSD socket + POSIX DNS surfaces alongside the
         // http client/parser headers. TLS sec tags need tls_credentials; <cstring>
-        // /<cstdlib> back the shim's memcpy/strlen/new-nothrow usage (the core
-        // shim only includes <cstdio>/<cstdint>).
+        // /<cstdlib>/<new> back the shim's memcpy/strlen/new-nothrow usage (the
+        // core shim only includes <cstdio>/<cstdint> — std::nothrow is not
+        // guaranteed to arrive transitively).
         if (uses('usesHttp'))
-            inc.push('<zephyr/net/socket.h>', '<zephyr/net/http/client.h>', '<zephyr/net/http/parser.h>', '<zephyr/net/tls_credentials.h>', '<zephyr/posix/sys/socket.h>', '<cstring>', '<cstdlib>');
+            inc.push('<zephyr/net/socket.h>', '<zephyr/net/http/client.h>', '<zephyr/net/http/parser.h>', '<zephyr/net/tls_credentials.h>', '<zephyr/posix/sys/socket.h>', '<cstring>', '<cstdlib>', '<new>');
         // MQTT client: <zephyr/net/mqtt.h> for mqtt_connect/publish/subscribe, plus
         // <zephyr/net/socket.h> for the zsock_* poll/getaddrinfo API the shim's poll
         // thread uses, and <zephyr/net/tls_credentials.h> for the mqtts:// path
@@ -608,6 +876,10 @@ export class ZephyrStrategy {
                 return;
             }
             for (const v of Object.values(node)) {
+                if (typeof v === 'string' && v.includes(TOKEN)) {
+                    found = true;
+                    return;
+                }
                 if (Array.isArray(v)) {
                     for (const item of v)
                         visit(item);
@@ -620,9 +892,17 @@ export class ZephyrStrategy {
         return found;
     }
     /** Pins referenced by gpio.* hal-ops in the program IR. lowerGpio routes a
-     *  pin to its devicetree spec by pin NUMBER, so the structured hal-op pins
-     *  are the authoritative signal for which __tc_dt_* specs are needed —
-     *  regardless of when the final call text is rendered. */
+     * pin to its devicetree spec by pin NUMBER, so the structured hal-op pins
+     * are the authoritative signal for which __tc_dt_* specs are needed —
+     * regardless of when the final call text is rendered.
+     *
+     * A gpio op interpolated into another HAL call's template literal
+     * (`USB0.writeLine(\`led: ${led.get()}\`)`) never becomes an IR node —
+     * resolveHALExprToText lowers it to C++ text while building the IR and bakes
+     * it into an __EMIT__ snprintf prelude, so the walk cannot see its pin. The
+     * spec NAME it references is still in that text; collectRawMatches finds it
+     * there, or the spec goes undeclared and the build fails on `__tc_dt_led0
+     * was not declared in this scope`. */
     collectGpioPinUsage(program) {
         const pins = new Set();
         if (!program)
@@ -646,13 +926,18 @@ export class ZephyrStrategy {
             }
         };
         visit(program);
+        visitResolvedHalOps(program, visit);
         return pins;
     }
     /** Run `re` (global) against every raw string in the IR — raw expression
-     *  values plus raw hal-op codes — returning capture group 1 of each match
-     *  (the full match when the regex has no group). This is how references the
-     *  text scanners must see but that never appear as IR call nodes (e.g. a
-     *  rawCpp() escape hatch naming `__tc_dt_sw0` directly) are discovered. */
+     * values plus raw hal-op codes — returning capture group 1 of each match
+     * (the full match when the regex has no group). This is how references the
+     * text scanners must see but that never appear as IR call nodes are
+     * discovered: a rawCpp() escape hatch naming `__tc_dt_sw0` directly, and —
+     * the reason every string LEAF is scanned, not just raw nodes — the
+     * pre-lowered C++ text of a HAL call inlined into another HAL call's
+     * template literal, which the IR builder bakes into plain `string` payloads
+     * (__EMIT__ snprintf preludes, op data fields) rather than raw nodes. */
     collectRawMatches(program, re) {
         const found = new Set();
         if (!program)
@@ -664,14 +949,10 @@ export class ZephyrStrategy {
         const visit = (node) => {
             if (!node || typeof node !== 'object')
                 return;
-            if (node.kind === 'raw' && typeof node.value === 'string')
-                scan(node.value);
-            if (node.operation && typeof node.operation === 'object'
-                && node.operation.operation === 'raw' && typeof node.operation.code === 'string') {
-                scan(node.operation.code);
-            }
             for (const v of Object.values(node)) {
-                if (Array.isArray(v)) {
+                if (typeof v === 'string')
+                    scan(v);
+                else if (Array.isArray(v)) {
                     for (const item of v)
                         visit(item);
                 }
@@ -700,7 +981,6 @@ export class ZephyrStrategy {
     }
     shimLines(program, ctx) {
         const chip = this.resolveChip(ctx, program);
-        const isPrintf = this.resolveDebugMode(ctx) === 'printf';
         const a = ctx?.analysis;
         const uses = (f) => (a ? !!a[f] : true);
         const helpers = a?.usedPolyfillHelpers;
@@ -764,7 +1044,7 @@ export class ZephyrStrategy {
         if (entryHasUI()) {
             guardBody.push('#ifndef PROGMEM', '#define PROGMEM', '#endif');
         }
-        // Test-runner console helpers: @typecad/expect's Zephyr shim calls these
+        // Test-runner console helpers: the test-runner's Zephyr shim calls these
         // for protocol output. Overloaded for string (const char*) and numeric
         // (double) so the same call site works for markers and test values.
         // The fs lowering bakes __tc_println into its error paths too, so the
@@ -782,21 +1062,29 @@ export class ZephyrStrategy {
                 'static inline char* __tc_fmt_num_buf(double v, char* out, size_t cap) {',
                 '    if (v != v) { snprintf(out, cap, "nan"); return out; }',
                 '    double a = v < 0 ? -v : v;',
-                '    long long ip = (long long)a;',
-                '    long long fr = (long long)((a - (double)ip) * 1000000.0 + 0.5);',
+                '    long long ip = static_cast<long long>(a);',
+                '    long long fr = static_cast<long long>((a - static_cast<double>(ip)) * 1000000.0 + 0.5);',
                 '    if (fr >= 1000000LL) { ip += 1LL; fr = 0LL; }',
                 '    int used = 0;',
                 '    if (v < 0 && (ip != 0LL || fr != 0LL)) { out[used++] = \'-\'; out[used] = \'\\0\'; }',
-                '    if (fr == 0LL) { snprintf(out + used, cap - (size_t)used, "%lld", ip); return out; }',
+                '    if (fr == 0LL) { snprintf(out + used, cap - static_cast<size_t>(used), "%lld", ip); return out; }',
                 '    char fbuf[8];',
                 '    int len = snprintf(fbuf, sizeof(fbuf), "%06lld", fr);',
                 '    while (len > 0 && fbuf[len - 1] == \'0\') { fbuf[--len] = \'\\0\'; }',
-                '    snprintf(out + used, cap - (size_t)used, "%lld.%s", ip, fbuf);',
+                '    snprintf(out + used, cap - static_cast<size_t>(used), "%lld.%s", ip, fbuf);',
                 '    return out;',
                 '}',
                 'static void __tc_fmt_num(double v) { char __b[32]; printf("%s", __tc_fmt_num_buf(v, __b, sizeof(__b))); }',
             ].join('\n'), 'inline void __tc_print(double v) { __tc_fmt_num(v); }', 'inline void __tc_println(const char* s) { printf("%s\\n", s); }', 'inline void __tc_println(double v) { __tc_fmt_num(v); printf("\\n"); }');
         }
+        // Trace user-event helpers (Trace.mark / Trace.event → trace.mark /
+        // trace.event ops): one [TR:EV:<uptime_ms>:<name>[:<value>] console line
+        // per call, captured host-side as timeline events. Emitted
+        // UNCONDITIONALLY like __tc_print — a Trace.mark() call site must never
+        // fail to link because zephyr.trace was disabled; with no capture
+        // listening the lines are ordinary console output. Value formatting
+        // reuses __tc_fmt_num_buf (integer-only, the picolibc %g trap).
+        guardBody.push('inline void __tc_trace_mark(const char* name) {', '    printf("[TR:EV:%u:%s\\n", static_cast<unsigned int>(k_uptime_get_32()), name);', '}', 'inline void __tc_trace_event(const char* name, double v) {', '    char __b[32];', '    printf("[TR:EV:%u:%s:%s\\n", static_cast<unsigned int>(k_uptime_get_32()), name, __tc_fmt_num_buf(v, __b, sizeof(__b)));', '}');
         // Serial-port write helper: writes a scalar to a UART/CDC device a byte at
         // a time. Overloaded on const char* (strings, snprintf buffers) and double
         // (numbers/booleans) so a single __tc_dev_put(dev, value) call site formats
@@ -812,12 +1100,29 @@ export class ZephyrStrategy {
         // declared controller's __tc_<bus>N_dev trips -Wunused-variable under
         // Zephyr's -Werror (collectUsedBusIndices; probes with no program emit all).
         const usedBuses = collectUsedBusIndices(program);
+        // Verb-level usage for the can.*/i2s.*/clock.* init blocks (see
+        // collectVerbUsage) — undefined when there is no program (probe flows
+        // emit the full state set).
+        const verbUsage = collectVerbUsage(program);
         if (uses('usesI2C') && chip.i2c) {
             for (let i = 0; i < chip.i2c.controllers.length; i++) {
                 if (usedBuses && !usedBuses.i2c.has(i))
                     continue;
                 guardBody.push(...i2cInitLines(chip, i));
             }
+            // I2C responders — one target-mode state block per constructed
+            // responder (bus|address), against the controller handles above
+            // (collectI2cResponders; the ops mark the bus used, so the handle
+            // the registration references is always present).
+            const responders = collectI2cResponders(program);
+            if (responders) {
+                for (const r of responders.values()) {
+                    const idx = parseControllerIndex(r.bus);
+                    if (idx >= chip.i2c.controllers.length)
+                        continue;
+                    guardBody.push(...i2cResponderStateLines(chip, idx, r.address, r.rx, r.tx));
+                }
+            }
         }
         if (uses('usesSPI') && chip.spi) {
             for (let i = 0; i < chip.spi.controllers.length; i++) {
@@ -826,6 +1131,79 @@ export class ZephyrStrategy {
                 guardBody.push(...spiInitLines(chip, i));
             }
         }
+        // LED strips — one buffer + device handle per driven SPI controller
+        // (chain length from the construction facts).
+        {
+            const strips = collectStrips(program);
+            if (uses('usesStrip') && strips) {
+                for (const [idx, count] of strips) {
+                    guardBody.push(...stripInitLines(chip, idx, count));
+                }
+            }
+        }
+        // Key matrix — the input-subsystem trampoline (the DT node comes from
+        // the overlay generator, driven by the toolchain's matrix scan).
+        if (uses('usesMatrix')) {
+            guardBody.push(...matrixInitLines());
+        }
+        // Wall-clock shim — the epoch<->civil helpers + the rtc alias handle
+        // (the DT node comes from the overlay generator's shim synthesis).
+        if (uses('usesClock')) {
+            const clockUsage = verbUsage?.clock ?? { set: true, now: true };
+            guardBody.push(...clockInitLines(clockUsage));
+        }
+        // CAN — per-controller device handle + the rx trampoline (the DT node
+        // is the board's own can@ node, enabled by the overlay). Only the
+        // controllers the program addresses, and only the state its verbs
+        // reference (collectVerbUsage; probes with no program emit all). Usage
+        // folds through the same clamp lowerCan applies to out-of-range
+        // instances, so the state block for the clamped controller emits.
+        if (uses('usesCan') && chip.can) {
+            const nCtrl = chip.can.controllers.length;
+            const canUsage = verbUsage?.can;
+            const folded = Array.from({ length: nCtrl }, () => ({ begin: false, send: false, onReceive: false }));
+            if (canUsage) {
+                for (const [inst, flags] of canUsage) {
+                    const f = folded[Math.max(0, Math.min(inst, nCtrl - 1))];
+                    f.begin = f.begin || flags.begin;
+                    f.send = f.send || flags.send;
+                    f.onReceive = f.onReceive || flags.onReceive;
+                }
+            }
+            for (let i = 0; i < nCtrl; i++) {
+                const f = folded[i];
+                if (canUsage && !f.begin && !f.send && !f.onReceive)
+                    continue;
+                guardBody.push(...canInitLines(chip, i, canUsage ? f : { begin: true, send: true, onReceive: true }));
+            }
+        }
+        // I2S — per-controller slab + block buffers + lazy direction inits,
+        // sized from the construction facts the ops carry. Same used-instance
+        // and clamp-fold discipline as CAN.
+        if (uses('usesI2s') && chip.i2s) {
+            const i2sFacts = collectI2s(program);
+            const nCtrl = chip.i2s.controllers.length;
+            const i2sUsage = verbUsage?.i2s;
+            const folded = Array.from({ length: nCtrl }, () => ({ write: false, read: false, readAt: false }));
+            if (i2sUsage) {
+                for (const [inst, flags] of i2sUsage) {
+                    const f = folded[Math.max(0, Math.min(inst, nCtrl - 1))];
+                    f.write = f.write || flags.write;
+                    f.read = f.read || flags.read;
+                    f.readAt = f.readAt || flags.readAt;
+                }
+            }
+            for (let i = 0; i < nCtrl; i++) {
+                const f = folded[i];
+                if (i2sUsage && !f.write && !f.read && !f.readAt)
+                    continue;
+                const facts = i2sFacts?.get(i);
+                const channels = facts?.channels ?? 2;
+                const bits = facts?.bits ?? 16;
+                const blockFrames = facts?.blockFrames ?? 64;
+                guardBody.push(...i2sInitLines(chip, i, blockFrames * channels * (bits / 8), i2sUsage ? f : { write: true, read: true, readAt: true }));
+            }
+        }
         if (uses('usesUart') && chip.uart) {
             for (let i = 0; i < chip.uart.controllers.length; i++) {
                 if (usedBuses && !usedBuses.uart.has(i))
@@ -848,7 +1226,7 @@ export class ZephyrStrategy {
             const sensors = collectSensors(program);
             if (sensors) {
                 for (const s of sensors.values()) {
-                    guardBody.push(...sensorStateLines(s.part, s.bus, s.port, s.busKind, s.spiHz, s.spiMode, s.alertPin));
+                    guardBody.push(...sensorStateLines(s.part, s.bus, s.port, s.busKind, s.spiHz, s.spiMode, s.alertPin, s.resolution));
                 }
             }
         }
@@ -874,10 +1252,52 @@ export class ZephyrStrategy {
                 }
             }
         }
-        if (uses('usesUsb') && chip.usb) {
-            guardBody.push(...usbdDeviceLines(chip));
-            for (let i = 0; i < chip.usb.cdcInstances; i++)
-                guardBody.push(...usbInitLines(chip, i));
+        // Trace heartbeat — the runtime-stats sampler behind `typecad-hal trace
+        // capture`. Opt-in via zephyr.trace.enabled in typecad-hal.config.ts (the
+        // config loader threads the zephyr record through platformContext). The
+        // block compiles under CUTTLEFISH_ENTRY_TU, so split-file TUs carry no
+        // second copy (a duplicate SYS_INIT would double every heartbeat).
+        // UI-mounted programs additionally get the frame-stats block (always
+        // defined, active only under CUTTLEFISH_TRACE_UI) so the ui_tick call
+        // site's instrumentation never depends on the trace config.
+        {
+            const traceCfg = ctx
+                ?.zephyr?.trace;
+            const traceEnabled = traceCfg?.enabled === true;
+            if (traceEnabled && entryHasUI()) {
+                guardBody.push('#if defined(CUTTLEFISH_ENTRY_TU)', '#define CUTTLEFISH_TRACE_UI 1', '#endif');
+            }
+            if (entryHasUI()) {
+                guardBody.push(...uiFrameTraceLines(traceCfg?.alarms?.frameMaxMs));
+            }
+            if (traceEnabled) {
+                guardBody.push(...traceHeartbeatLines(clampTraceIntervalMs(traceCfg?.intervalMs), entryHasUI(), traceCfg?.alarms));
+            }
+        }
+        // The usbd context is shared by CDC and HID; the CDC per-instance
+        // state only emits when the program actually uses usb.* (an HID-only
+        // program would otherwise carry an unused __tc_usb0_dev).
+        if ((uses('usesUsb') || uses('usesHid')) && chip.usb) {
+            guardBody.push(...usbdDeviceLines(chip, { hid: uses('usesHid') }));
+            if (uses('usesUsb')) {
+                for (let i = 0; i < chip.usb.cdcInstances; i++)
+                    guardBody.push(...usbInitLines(chip, i));
+            }
+        }
+        // USB HID — one interface per program; the protocol comes from which
+        // class's verbs the program used (keyboard vs mouse). Requires the USB
+        // device context (the same one CDC rides — the register helper calls
+        // __tc_usbd_start).
+        if (uses('usesHid') && chip.usb) {
+            const protocol = collectHidProtocol(program) ?? 'keyboard';
+            if (protocol === 'mixed') {
+                // One zephyr,hid-device interface per program (the v1 ceiling) —
+                // name it at compile time instead of an undefined-symbol error.
+                guardBody.push('#error "typecad-hal: one HID interface per program (v1) — Keyboard and Mouse cannot be mixed in one app"');
+            }
+            else {
+                guardBody.push(...hidInitLines(protocol));
+            }
         }
         // PWM init also fires (with alias vars for the override pins) when a
         // program drives ONLY inline-override channels on a chip with no pwm
@@ -953,13 +1373,15 @@ export class ZephyrStrategy {
             lines.push('// cuttlefish runtime shim. Wrapped in a single include guard so the', '// block is safe to emit into multiple headers and .cpp files within', '// one translation unit (a .cpp may #include several headers that each', '// carry the shim). The guard ensures the definitions are seen exactly', '// once per TU.', '#ifndef CUTTLEFISH_SHIM_DEFINED', '#define CUTTLEFISH_SHIM_DEFINED', ...guardBody, '#endif // CUTTLEFISH_SHIM_DEFINED');
         }
         // Devicetree specs — one per board-defined GPIO pin, but ONLY for pins the
-        // program actually addresses (lowerGpio routes by pin number, and the
-        // structured gpio.* hal-op pins are visible here) plus aliases named
-        // verbatim in raw code (rawCpp escape hatches). Emitted OUTSIDE the single
-        // CUTTLEFISH_SHIM_DEFINED guard with a per-symbol guard: per-file pin sets
-        // differ, and in a multi-header TU the first header's TU-wide guard would
-        // otherwise hide the second header's specs. Without a program (capability
-        // query), emit them all.
+        // program actually addresses (lowerGpio routes by pin number; the
+        // structured gpio.* hal-op pins plus the spec names appearing in any IR
+        // string — including the pre-lowered text of a HAL call inlined into
+        // another HAL call's template literal — are visible here) and aliases
+        // named verbatim in raw code (rawCpp escape hatches). Emitted OUTSIDE the
+        // single CUTTLEFISH_SHIM_DEFINED guard with a per-symbol guard: per-file
+        // pin sets differ, and in a multi-header TU the first header's TU-wide
+        // guard would otherwise hide the second header's specs. Without a program
+        // (capability query), emit them all.
         const usedPins = this.collectGpioPinUsage(program);
         const dtTextRefs = this.collectRawMatches(program, /__tc_dt_([A-Za-z0-9_]+)/g);
         for (const spec of chip.gpio.dtSpecs) {
@@ -968,32 +1390,6 @@ export class ZephyrStrategy {
             const guard = `__TC_DT_${spec.dtSpec.replace(/[^A-Za-z0-9_]/g, '_').toUpperCase()}_SPEC`;
             lines.push(`#ifndef ${guard}`, `#define ${guard}`, `static const struct gpio_dt_spec __tc_dt_${spec.dtSpec} = GPIO_DT_SPEC_GET(DT_ALIAS(${spec.dtSpec}), gpios);`, `#endif // ${guard}`);
         }
-        // --- Debug-mode halt + per-breakpoint disable registry ---
-        //
-        // Printf mode only. In gdb mode the cuttlefish debug preprocessor is
-        // skipped (core emits #line markers + VS Code native breakpoints instead),
-        // so __tc_debug_wait_for_continue is never called — skip the shim and its
-        // <zephyr/drivers/uart.h> dependency entirely (forcedIncludes mirrors this).
-        //
-        // The cuttlefish debug preprocessor injects __tc_debug_wait_for_continue(id)
-        // calls at each breakpoint; without these definitions the emitted code
-        // would not link.
-        //
-        // Zephyr's minimal libc has no getchar()/EOF, so the halt polls the console
-        // UART directly via uart_poll_in on the system console device, yielding to
-        // the scheduler with k_msleep between polls so an unattended breakpoint
-        // does not starve the system. ENTER (or any non-'s' byte) = continue;
-        // 's'/'S' = skip this breakpoint for the rest of the run (records the id).
-        if (isPrintf) {
-            lines.push('#ifndef __TC_BP_DISABLED_DEFINED', '#define __TC_BP_DISABLED_DEFINED', 'static bool __tc_bp_disabled[256] = {0};', 'static inline bool __tc_bp_is_disabled(int id) { return id >= 0 && id < 256 && __tc_bp_disabled[id]; }', 
-            // Console input: poll the UART console device. DEVICE_DT_GET(DT_CHOSEN(zephyr_console))
-            // resolves to the board's console (UART0 USB-CDC on the XIAO nRF52840).
-            // Not every board DTS declares a zephyr,console chosen (STM32MP1 M-side,
-            // display/carrier boards): there is nothing to print a prompt on and
-            // nothing to read a key from, so breakpoints auto-continue instead of
-            // hanging an unattended run.
-            '#if DT_HAS_CHOSEN(zephyr_console)', 'static inline char __tc_debug_wait_for_continue(int id) {', '    const struct device* __con = DEVICE_DT_GET(DT_CHOSEN(zephyr_console));', '    unsigned char __c = 0;', "    while (uart_poll_in(__con, &__c) != 0) {", '        k_msleep(10);', '    }', "    // Drain the rest of the typed line so the next breakpoint waits fresh.", "    unsigned char __peek = 0;", "    while (uart_poll_in(__con, &__peek) == 0 && __peek != '\\n') { (void)0; }", "    if ((__c == 's') || (__c == 'S')) { if (id >= 0 && id < 256) __tc_bp_disabled[id] = true; }", '    return static_cast<char>(__c);', '}', '#else', 'static inline char __tc_debug_wait_for_continue(int id) { (void)id; return static_cast<char>(0); }', '#endif // DT_HAS_CHOSEN(zephyr_console)', '#endif // __TC_BP_DISABLED_DEFINED', '');
-        }
         // --- Zephyr entrypoint ---------------------------------------------------
         // No bridge here: the synthesizer emits main() itself (it keys off
         // entrypointFunctionName()="main" and requiresLoopFunction()=false), with
@@ -1023,7 +1419,11 @@ export class ZephyrStrategy {
         // precede the wiring-ambient shims and the PinGroup factory there; the
         // __tc_gpio_read body below is what still needs emitting here.)
         if (this.needsGpioReadShim(program, ctx)) {
-            lines.push('inline int __tc_gpio_read(int pin) { return gpio_pin_get_raw(__tc_gpio_dev(static_cast<uint32_t>(pin)), __tc_gpio_pin(static_cast<uint32_t>(pin))); }');
+            lines.push('inline int __tc_gpio_read(int pin) { return gpio_pin_get_raw(__tc_gpio_dev(static_cast<uint32_t>(pin)), __tc_gpio_pin(static_cast<uint32_t>(pin))); }', 
+            // Runtime input configuration for ui.watchPin / ui.press setup
+            // (the strategy's setPinMode lowers here). Idempotent — setup calls
+            // it once per watched pin before the poll loop reads it.
+            'inline void __tc_gpio_configure_input(uint32_t pin) { gpio_pin_configure(__tc_gpio_dev(pin), __tc_gpio_pin(pin), GPIO_INPUT | GPIO_PULL_UP); }');
         }
         // __tc_gpio_write / __tc_delay_us are only referenced via @typecad/safety
         // lowering, so they stay gated on it.
@@ -1556,10 +1956,13 @@ export class ZephyrStrategy {
     // ── Interrupt safety ─────────────────────────────────────────────────────
     // Zephyr ISRs run above thread context: anything that sleeps (k_msleep),
     // pends, or takes a driver lock is illegal there (asserted by the kernel in
-    // debug builds; corrupts scheduler state otherwise). The names below are the
-    // IR-level callees cuttlefish's interrupt-analysis pass matches (the same
-    // keys ArduinoStrategy uses; timing.delay/delay_microseconds hal-ops are
-    // mapped back to the bare names by the analyzer itself).
+    // debug builds; corrupts scheduler state otherwise). The keys below are
+    // matched by cuttlefish's interrupt-analysis pass in two shapes: bare/qualified
+    // callee names (call statements) and resolved hal-op payloads — the analyzer
+    // maps timing.delay/delay_microseconds/sleep/busy_wait_us ops back to the
+    // bare timing keys, and matches the op payload's port/bus field (UART0,
+    // I2C0, SPI0, …) against these keys directly. The same keys ArduinoStrategy
+    // uses.
     isrUnsafeOperations() {
         return new Map([
             ['delay', {
@@ -1698,14 +2101,14 @@ export class ZephyrStrategy {
         catch (err) {
             // A malformed facts/as-built file is the USER's error — surface it
             // verbatim instead of the generic "cannot generate" below.
-            if (err instanceof Error && (err.message.includes('cuttlefish.facts.json') || err.message.includes('as-built.json')))
+            if (err instanceof Error && (err.message.includes('typecad-hal.facts.json') || err.message.includes('as-built.json')))
                 throw err;
             return undefined;
         }
     }
     /**
      * Regenerate the board catalog overlay from the user's own Zephyr tree —
-     * `cuttlefish board sync`. After a `west update`, this is how new/changed/
+     * `typecad-hal board sync`. After a `west update`, this is how new/changed/
      * removed boards reach projects without a cuttlefish release. See
      * src/sdk/board-catalog-sync.ts.
      */
@@ -1714,7 +2117,7 @@ export class ZephyrStrategy {
     }
     /**
      * Refresh the overlay only when it is stale (provenance no longer matches
-     * the tree) — the pre-step `cuttlefish board regen` runs so a regen after
+     * the tree) — the pre-step `typecad-hal board regen` runs so a regen after
      * `west update` picks up the tree's boards automatically. Tree walk only
      * happens when there is actual refreshing to do.
      */
@@ -1774,6 +2177,17 @@ export class ZephyrStrategy {
             postIteration: 'k_msleep(1);',
         };
     }
+    /**
+     * Per-frame wall-time feed for the trace heartbeat's UI stats. The helper
+     * is emitted unconditionally for UI programs (compiles to a no-op unless
+     * zephyr.trace defined CUTTLEFISH_TRACE_UI), so this call is safe with
+     * tracing on or off.
+     */
+    uiFrameTimingLines(deltaMsExpr) {
+        if (!entryHasUI())
+            return null;
+        return [`__tc_trace_ui_frame(static_cast<uint32_t>(${deltaMsExpr}));`];
+    }
     // ── Type aliases ────────────────────────────────────────────────────────
     shouldSkipTypeAlias() {
         return false;
@@ -1899,23 +2313,23 @@ export class ZephyrStrategy {
                 requiredIncludes: ['<cstring>'],
                 forwardDeclarations: [],
                 helperStructs: [],
-                helperFunctions: [`
-// TypeCAD string method polyfills (Zephyr, minimal-libc).
-#ifndef CUTTLEFISH_STR_BUF_SIZE
-#define CUTTLEFISH_STR_BUF_SIZE 64
-#endif
-bool __tc_endsWith(const char* s, const char* suffix) { int sl = strlen(s), tl = strlen(suffix); return sl >= tl && strcmp(s + sl - tl, suffix) == 0; }
-const char* __tc_toUpperCase(const char* s) { static char buf[2][CUTTLEFISH_STR_BUF_SIZE]; static uint8_t slot = 0; slot ^= 1; char* b = buf[slot]; strncpy(b, s, CUTTLEFISH_STR_BUF_SIZE - 1); b[CUTTLEFISH_STR_BUF_SIZE - 1] = '\\0'; for (char* p = b; *p; p++) { if (*p >= 'a' && *p <= 'z') { *p = static_cast<char>(*p - 32); } } return b; }
-const char* __tc_toLowerCase(const char* s) { static char buf[2][CUTTLEFISH_STR_BUF_SIZE]; static uint8_t slot = 0; slot ^= 1; char* b = buf[slot]; strncpy(b, s, CUTTLEFISH_STR_BUF_SIZE - 1); b[CUTTLEFISH_STR_BUF_SIZE - 1] = '\\0'; for (char* p = b; *p; p++) { if (*p >= 'A' && *p <= 'Z') { *p = static_cast<char>(*p + 32); } } return b; }
-const char* __tc_trim(const char* s) { static char buf[2][CUTTLEFISH_STR_BUF_SIZE]; static uint8_t slot = 0; slot ^= 1; char* b = buf[slot]; while (*s == ' ' || *s == '\\t' || *s == '\\n' || *s == '\\r') s++; int len = strlen(s); while (len > 0 && (s[len-1] == ' ' || s[len-1] == '\\t' || s[len-1] == '\\n' || s[len-1] == '\\r')) len--; int cplen = len < CUTTLEFISH_STR_BUF_SIZE - 1 ? len : CUTTLEFISH_STR_BUF_SIZE - 1; strncpy(b, s, cplen); b[cplen] = '\\0'; return b; }
-const char* __tc_substring2(const char* s, int start, int end) { static char buf[2][CUTTLEFISH_STR_BUF_SIZE]; static uint8_t slot = 0; slot ^= 1; char* b = buf[slot]; int slen = strlen(s); if (start < 0) start = 0; if (end > slen) end = slen; if (end < start) end = start; int len = end - start; if (len >= CUTTLEFISH_STR_BUF_SIZE) len = CUTTLEFISH_STR_BUF_SIZE - 1; strncpy(b, s + start, len); b[len] = '\\0'; return b; }
-const char* __tc_substring1(const char* s, int start) { return __tc_substring2(s, start, strlen(s)); }
-const char* __tc_slice2(const char* s, int start, int end) { return __tc_substring2(s, start, end); }
-const char* __tc_slice1(const char* s, int start) { return __tc_substring2(s, start, strlen(s)); }
-const char* __tc_replace(const char* s, const char* old, const char* repl) { static char buf[2][CUTTLEFISH_STR_BUF_SIZE]; static uint8_t slot = 0; slot ^= 1; char* b = buf[slot]; const char* pos = strstr(s, old); if (!pos) { strncpy(b, s, CUTTLEFISH_STR_BUF_SIZE - 1); b[CUTTLEFISH_STR_BUF_SIZE - 1] = '\\0'; return b; } int beforeLen = static_cast<int>(pos - s); int oldLen = static_cast<int>(strlen(old)); int replLen = static_cast<int>(strlen(repl)); if (beforeLen + replLen + static_cast<int>(strlen(pos + oldLen)) >= CUTTLEFISH_STR_BUF_SIZE) { strncpy(b, s, CUTTLEFISH_STR_BUF_SIZE - 1); b[CUTTLEFISH_STR_BUF_SIZE - 1] = '\\0'; return b; } memcpy(b, s, beforeLen); memcpy(b + beforeLen, repl, replLen); strcpy(b + beforeLen + replLen, pos + oldLen); return b; }
-const char* __tc_charAt(const char* s, int idx) { static char buf[2][2]; static uint8_t slot = 0; slot ^= 1; buf[slot][0] = s[idx]; buf[slot][1] = '\\0'; return buf[slot]; }
-int __tc_charCodeAt(const char* s, int idx) { return static_cast<int>(static_cast<unsigned char>(s[idx])); }
-int __tc_indexOf(const char* s, const char* needle) { const char* p = strstr(s, needle); return p ? static_cast<int>(p - s) : -1; }
+                helperFunctions: [`
+// TypeCAD string method polyfills (Zephyr, minimal-libc).
+#ifndef CUTTLEFISH_STR_BUF_SIZE
+#define CUTTLEFISH_STR_BUF_SIZE 64
+#endif
+bool __tc_endsWith(const char* s, const char* suffix) { int sl = strlen(s), tl = strlen(suffix); return sl >= tl && strcmp(s + sl - tl, suffix) == 0; }
+const char* __tc_toUpperCase(const char* s) { static char buf[2][CUTTLEFISH_STR_BUF_SIZE]; static uint8_t slot = 0; slot ^= 1; char* b = buf[slot]; strncpy(b, s, CUTTLEFISH_STR_BUF_SIZE - 1); b[CUTTLEFISH_STR_BUF_SIZE - 1] = '\\0'; for (char* p = b; *p; p++) { if (*p >= 'a' && *p <= 'z') { *p = static_cast<char>(*p - 32); } } return b; }
+const char* __tc_toLowerCase(const char* s) { static char buf[2][CUTTLEFISH_STR_BUF_SIZE]; static uint8_t slot = 0; slot ^= 1; char* b = buf[slot]; strncpy(b, s, CUTTLEFISH_STR_BUF_SIZE - 1); b[CUTTLEFISH_STR_BUF_SIZE - 1] = '\\0'; for (char* p = b; *p; p++) { if (*p >= 'A' && *p <= 'Z') { *p = static_cast<char>(*p + 32); } } return b; }
+const char* __tc_trim(const char* s) { static char buf[2][CUTTLEFISH_STR_BUF_SIZE]; static uint8_t slot = 0; slot ^= 1; char* b = buf[slot]; while (*s == ' ' || *s == '\\t' || *s == '\\n' || *s == '\\r') s++; int len = strlen(s); while (len > 0 && (s[len-1] == ' ' || s[len-1] == '\\t' || s[len-1] == '\\n' || s[len-1] == '\\r')) len--; int cplen = len < CUTTLEFISH_STR_BUF_SIZE - 1 ? len : CUTTLEFISH_STR_BUF_SIZE - 1; strncpy(b, s, cplen); b[cplen] = '\\0'; return b; }
+const char* __tc_substring2(const char* s, int start, int end) { static char buf[2][CUTTLEFISH_STR_BUF_SIZE]; static uint8_t slot = 0; slot ^= 1; char* b = buf[slot]; int slen = strlen(s); if (start < 0) start = 0; if (end > slen) end = slen; if (end < start) end = start; int len = end - start; if (len >= CUTTLEFISH_STR_BUF_SIZE) len = CUTTLEFISH_STR_BUF_SIZE - 1; strncpy(b, s + start, len); b[len] = '\\0'; return b; }
+const char* __tc_substring1(const char* s, int start) { return __tc_substring2(s, start, strlen(s)); }
+const char* __tc_slice2(const char* s, int start, int end) { return __tc_substring2(s, start, end); }
+const char* __tc_slice1(const char* s, int start) { return __tc_substring2(s, start, strlen(s)); }
+const char* __tc_replace(const char* s, const char* old, const char* repl) { static char buf[2][CUTTLEFISH_STR_BUF_SIZE]; static uint8_t slot = 0; slot ^= 1; char* b = buf[slot]; const char* pos = strstr(s, old); if (!pos) { strncpy(b, s, CUTTLEFISH_STR_BUF_SIZE - 1); b[CUTTLEFISH_STR_BUF_SIZE - 1] = '\\0'; return b; } int beforeLen = static_cast<int>(pos - s); int oldLen = static_cast<int>(strlen(old)); int replLen = static_cast<int>(strlen(repl)); if (beforeLen + replLen + static_cast<int>(strlen(pos + oldLen)) >= CUTTLEFISH_STR_BUF_SIZE) { strncpy(b, s, CUTTLEFISH_STR_BUF_SIZE - 1); b[CUTTLEFISH_STR_BUF_SIZE - 1] = '\\0'; return b; } memcpy(b, s, beforeLen); memcpy(b + beforeLen, repl, replLen); strcpy(b + beforeLen + replLen, pos + oldLen); return b; }
+const char* __tc_charAt(const char* s, int idx) { static char buf[2][2]; static uint8_t slot = 0; slot ^= 1; buf[slot][0] = s[idx]; buf[slot][1] = '\\0'; return buf[slot]; }
+int __tc_charCodeAt(const char* s, int idx) { return static_cast<int>(static_cast<unsigned char>(s[idx])); }
+int __tc_indexOf(const char* s, const char* needle) { const char* p = strstr(s, needle); return p ? static_cast<int>(p - s) : -1; }
 `],
                 shimMacros: [],
                 dependencies: [],
@@ -1931,27 +2345,27 @@ int __tc_indexOf(const char* s, const char* needle) { const char* p = strstr(s,
                 requiredIncludes: [],
                 forwardDeclarations: [],
                 helperStructs: [],
-                helperFunctions: [`
-#ifndef __TC_STATIC_ARRAY_DEFINED
-#define __TC_STATIC_ARRAY_DEFINED
-template<typename T, int N>
-struct __tc_StaticArray {
-    T data[N];
-    int _size;
-    __tc_StaticArray() : _size(0) {}
-    int length() const { return _size; }
-    int size() const { return _size; }
-    void push(T val) { if (_size < N) data[_size++] = val; }
-    T pop() { return (_size > 0) ? data[--_size] : T(); }
-    int indexOf(T val) const { for (int i = 0; i < _size; i++) if (data[i] == val) return i; return -1; }
-    T& operator[](int i) { return data[i]; }
-    const T& operator[](int i) const { return data[i]; }
-    T* begin() { return &data[0]; }
-    T* end() { return &data[_size]; }
-    const T* begin() const { return &data[0]; }
-    const T* end() const { return &data[_size]; }
-};
-#endif
+                helperFunctions: [`
+#ifndef __TC_STATIC_ARRAY_DEFINED
+#define __TC_STATIC_ARRAY_DEFINED
+template<typename T, int N>
+struct __tc_StaticArray {
+    T data[N];
+    int _size;
+    __tc_StaticArray() : _size(0) {}
+    int length() const { return _size; }
+    int size() const { return _size; }
+    void push(T val) { if (_size < N) data[_size++] = val; }
+    T pop() { return (_size > 0) ? data[--_size] : T(); }
+    int indexOf(T val) const { for (int i = 0; i < _size; i++) if (data[i] == val) return i; return -1; }
+    T& operator[](int i) { return data[i]; }
+    const T& operator[](int i) const { return data[i]; }
+    T* begin() { return &data[0]; }
+    T* end() { return &data[_size]; }
+    const T* begin() const { return &data[0]; }
+    const T* end() const { return &data[_size]; }
+};
+#endif
 `],
                 shimMacros: [],
                 dependencies: [],
@@ -2008,9 +2422,14 @@ struct __tc_StaticArray {
     writeDigitalPin(pin, val) {
         return `__tc_gpio_write(${pin}, ${val})`;
     }
-    setPinMode(_pin, _mode) {
-        // Zephyr configures pin direction via devicetree, not a runtime pinMode.
-        return `/* pin mode configured via devicetree */`;
+    setPinMode(pin, _mode) {
+        // Runtime input configuration: Zephyr has no pinMode — the GPIO API
+        // configures direction/pull explicitly. The mode argument is ignored:
+        // every watchPin/press consumer wants an input with pull-up (buttons are
+        // active-low), and __tc_gpio_configure_input hardcodes exactly that.
+        // The helper's definition rides the GPIO read shim (same gate — UI builds
+        // with pin watchers always carry the read surface too).
+        return `__tc_gpio_configure_input(static_cast<uint32_t>(${pin}));`;
     }
     delayMs(ms) {
         return `k_msleep(${ms})`;
@@ -2046,16 +2465,31 @@ struct __tc_StaticArray {
         return resolveZephyrDisplayOp(op, this._displayState);
     }
     supportedDisplayDrivers() {
-        return new Set(Object.keys(ZEPHYR_DISPLAY_PROFILES));
+        // Registry profiles plus every panel compatible with a display binding in
+        // the user's Zephyr tree — the drop-in path (display.driver = compatible)
+        // validates at mount like any curated profile. No tree discoverable →
+        // registry only.
+        const drivers = new Set(Object.keys(ZEPHYR_DISPLAY_PROFILES));
+        try {
+            for (const compatible of listBoundDisplayCompatibles())
+                drivers.add(compatible);
+        }
+        catch {
+            // Tree unreadable — the registry set stands.
+        }
+        return drivers;
     }
     // ── Strategy-owned display/touch adapter seam ────────────────────────────
     // Zephyr owns its display + touch adapters: the UI display adapter bridges
-    // the in-tree CuttlefishGFX class to the panel (per-controller init + wire
-    // format, see src/display/ui-adapter.ts), and the touch adapters drive the
-    // FT6336U (I2C capacitive) and XPT2046 (SPI resistive) controllers via
-    // Zephyr's bus APIs (src/display/touch-adapter.ts). Both live in this
-    // package so cuttlefish carries no Zephyr/Wiring-specific display or touch
-    // knowledge. Mirrors ArduinoStrategy's provides*/resolve* pattern.
+    // the in-tree CuttlefishGFX class to the panel via one of two transports
+    // (per profile — 'direct-spi': per-controller init + wire format over
+    // spi_write, see src/display/ui-adapter.ts; 'zephyr-display': Zephyr's
+    // display API with in-tree panel drivers, see src/display/ui-adapter-native.ts),
+    // and the touch adapters drive the FT6336U (I2C capacitive) and XPT2046
+    // (SPI resistive) controllers via Zephyr's bus APIs (src/display/touch-adapter.ts).
+    // Both live in this package so cuttlefish carries no Zephyr/Wiring-specific
+    // display or touch knowledge. Mirrors ArduinoStrategy's provides*/resolve*
+    // pattern.
     providesDisplayAdapter() { return true; }
     resolveDisplayAdapter(display) {
         const code = zephyrDisplayAdapterGenerator(display);
@@ -2074,7 +2508,30 @@ struct __tc_StaticArray {
         return new Map(Object.entries(BUILT_IN_PROFILES));
     }
     colorFormat() {
-        return 'rgb565';
+        // The seeded display state is the truth after display.init (drop-in mono
+        // panels synthesize 'mono'); the default profile keeps the pre-init
+        // rgb565 answer byte-identical with history.
+        return this._displayState.profile.colorFormat;
+    }
+    colorFormatForDriver(driver) {
+        // Drop-in panel class from the compatible table (DATA): the 1bpp OLED
+        // family lowers mono engine-side and the 16-gray family lowers gray8,
+        // so colors flatten at build time instead of rgb565-lowering into an
+        // adapter that cannot show them. Registry profiles carry their own
+        // colorFormat; non-compatible driver ids keep the default.
+        if (isDtCompatible(driver) && isMonoDisplay({ driver }))
+            return 'mono';
+        if (isDtCompatible(driver) && isEinkDisplay({ driver }))
+            return 'mono';
+        if (isDtCompatible(driver) && isGrayDisplay({ driver }))
+            return 'gray8';
+        return undefined;
+    }
+    displayClassForDriver(driver) {
+        // The compatible table decides (DATA) — ssd16xx/uc81xx are e-ink.
+        if (isDtCompatible(driver) && isEinkDisplay({ driver }))
+            return 'eink';
+        return undefined;
     }
     graphicsCapacity() {
         return {
@@ -2085,43 +2542,43 @@ struct __tc_StaticArray {
         };
     }
     // ── Debug ─────────────────────────────────────────────────────────────────
-    // Zephyr's minimal C++ config has no <iostream>, so the GenericStrategy
-    // std::cout fallback the debug preprocessor uses by default would NOT
-    // compile. Override the debug surface to route through printk (always
-    // available, no CONFIG_CONSOLE dependency) and the __tc_debug_wait_for_continue
-    // halt emitted in shimLines. See src/debug-codegen.ts.
-    //
-    // Target-selective: targets with a debug probe get native GDB source-level
-    // debugging (core emits #line markers + skips printf instrumentation); the
-    // rest fall back to the printk instrumentation path. The ESP32-S3 has a
-    // built-in USB-JTAG (single-cable GDB via OpenOCD) so it selects 'gdb'.
-    // The XIAO nRF52840 needs its J-Link wired up; its GDB path is a follow-on,
-    // so it stays on printf for now.
+    // Source-level debugging is the GDB flow only (the west-owned gdb server
+    // serves F5 via cortex-debug's external-server mode — see
+    // toolchain/debug-config.ts). The printf/Serial breakpoint instrumentation
+    // pipeline was removed from the product.
     debugMode(target) {
-        // `target` is the Zephyr board id (optionally with a /qualifier suffix,
-        // e.g. 'esp32s3_devkitc/esp32s3/procpu'). Match on the bare board id.
-        const boardId = (target ?? '').split('/')[0];
-        if (boardId === 'esp32s3_devkitc' || boardId.startsWith('esp32s3')) {
-            return 'gdb';
-        }
-        // The STM32 Black Pill ships a verified ST-Link probe method in its board
-        // package (openocd runner over SWD, with the reset_config quirk for the
-        // unwired SRST line), so F5 attaches natively out of the box.
-        if (boardId.startsWith('blackpill_')) {
-            return 'gdb';
-        }
-        // The plain ESP32 (esp32_devkitc) intentionally stays on 'printf': unlike
-        // the S3 it has NO built-in USB-JTAG, so gdb needs an external ESP-PROG
-        // probe + a different OpenOCD cfg/toolchain dir (deferred). Falls through.
-        return 'printf';
-    }
-    generateDebugInitCode() {
-        return generateZephyrInitCode();
-    }
-    generateDebugBreakpointCode(params) {
-        return generateZephyrBreakpointCode(params.fileName, params.lineNum, params.originalLine, params.variables, params.normalizedCondition, params.breakpointId);
-    }
-    generateDebugLogpointCode(params) {
-        return generateZephyrLogpointCode(params.fileName, params.lineNum, params.parts, params.variables);
+        // `target` is the Zephyr board id (optionally with a /qualifier suffix).
+        // gdb capability is a FACT of the board: its probe-method table carries a
+        // debug-capable entry (bootloaders mark debug:false; SWD/JTAG probes and
+        // built-in USB-JTAG carry debug:true) — the same table west's runner
+        // selection uses. Boards without a table (or unresolvable targets, e.g.
+        // generated custom boards) report 'none', and --debug fails with an
+        // explicit diagnostic (transpile.ts) rather than building silently.
+        const t = (target ?? '').trim();
+        if (!t)
+            return 'none';
+        const memo = debugModeMemo.get(t);
+        if (memo)
+            return memo;
+        let mode = 'none';
+        try {
+            const g = generateBoard(t);
+            const constants = JSON.parse(g.boardJson).constants;
+            for (let i = 0;; i++) {
+                const id = constants[`zephyr.probeMethods.${i}.id`];
+                if (typeof id !== 'string')
+                    break;
+                if (constants[`zephyr.probeMethods.${i}.debug`] !== false) {
+                    mode = 'gdb';
+                    break;
+                }
+            }
+        }
+        catch {
+            // Board not resolvable from facts — 'none' (never crash codegen over
+            // the debug-capability gate).
+        }
+        debugModeMemo.set(t, mode);
+        return mode;
     }
 }