@typecad/framework-zephyr 1.0.0-alpha.18 → 1.0.0-alpha.20

package/dist/lowering/matrix.js

@@ -0,0 +1,63 @@
+// ---------------------------------------------------------------------------
+// Matrix lowering — gpio-kbd-matrix node + input-event trampoline
+//
+// The gpio-kbd-matrix driver (Zephyr input subsystem) scans the grid and
+// reports each key as ABS_X (column) + ABS_Y (row) + BTN_TOUCH (press).
+// The shim decodes the triple and calls the user's lowered callback as
+// (row, col, pressed). The overlay generator synthesizes the DT node with
+// row-gpios/col-gpios phandle arrays from the construction pad lists —
+// the lowering's comment marker carries rows/cols to the toolchain scan
+// (the pwm user-facts marker precedent).
+// ----------------------------------------------------------------------------
+/**
+ * Emit the matrix trampoline state. Called from shimLines when the program
+ * uses matrix.* — the listener targets the synthesized tc_matrix node, the
+ * handler pointer is assigned by the on_key lowering.
+ */
+export function matrixInitLines() {
+    return [
+        '// CUTTLEFISH_MATRIX_BEGIN',
+        'static void (*__tc_matrix_on_key)(double, double, bool) = NULL;',
+        'static int32_t __tc_matrix_row = -1;',
+        'static int32_t __tc_matrix_col = -1;',
+        'static void __tc_matrix_cb(struct input_event* evt, void* user_data) {',
+        '    (void)user_data;',
+        '    switch (evt->code) {',
+        '    case INPUT_ABS_X:',
+        '        __tc_matrix_col = evt->value;',
+        '        break;',
+        '    case INPUT_ABS_Y:',
+        '        __tc_matrix_row = evt->value;',
+        '        break;',
+        '    case INPUT_BTN_TOUCH:',
+        '        if (__tc_matrix_on_key != NULL && __tc_matrix_row >= 0 && __tc_matrix_col >= 0) {',
+        '            __tc_matrix_on_key(static_cast<double>(__tc_matrix_row), static_cast<double>(__tc_matrix_col), evt->value != 0);',
+        '        }',
+        '        break;',
+        '    default:',
+        '        break;',
+        '    }',
+        '}',
+        'INPUT_CALLBACK_DEFINE(DEVICE_DT_GET(DT_NODELABEL(tc_matrix)), __tc_matrix_cb, NULL);',
+        '// CUTTLEFISH_MATRIX_END',
+    ];
+}
+/**
+ * Resolve a HAL matrix.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops.
+ */
+export function lowerMatrix(op) {
+    const o = op;
+    switch (op.operation) {
+        case 'matrix.on_key': {
+            // The comment marker carries the construction pad lists to the
+            // toolchain's overlay scan (the pwm user-facts precedent).
+            return {
+                code: `/* cuttlefish-matrix: rows=${o.rows} cols=${o.cols} */ __tc_matrix_on_key = ${o.handler};`,
+            };
+        }
+        default:
+            throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+                `Open an issue or use rawCpp() to emit it manually.`);
+    }
+}

package/dist/lowering/power.d.ts

@@ -0,0 +1,10 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+/**
+ * Resolve a HAL power.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops.
+ */
+export declare function lowerPower(op: HALOpIR, chip?: ZephyrChipDescriptor): {
+    code?: string;
+    expression?: string;
+};

package/dist/lowering/power.js

@@ -0,0 +1,35 @@
+// ---------------------------------------------------------------------------
+// Power lowering — sys_poweroff() for explicit soft-off entry
+//
+// Both SoC families implement the kernel's sys_poweroff(): ESP32 parks the
+// RTC domain and calls esp_deep_sleep_start(); STM32 enters standby-class
+// deep sleep. The call never returns — wake is a reset or a wake source
+// (board-specific: the Black Pill's WKUP pin is PA0; ESP32 GPIOs armed as
+// wake triggers). Statement emission continues after the call site, but
+// nothing there runs — the transpiler treats it as any other void call.
+// ----------------------------------------------------------------------------
+/**
+ * Resolve a HAL power.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops.
+ */
+export function lowerPower(op, chip) {
+    const o = op;
+    switch (op.operation) {
+        case 'power.off':
+            return { code: 'sys_poweroff();' };
+        case 'power.off_for': {
+            // DAC discipline: without the RTC wake-timer fact, a timed off would
+            // sleep with no wake source — lower to a comment naming it.
+            if (!chip?.powerWakeTimer) {
+                return { code: `/* Power.offFor(${o.ms} ms): this board's SoC declares no RTC wake timer — soft-off here has no armed wake; use Power.off() */` };
+            }
+            // Arm the RTC timer (µs), then enter soft-off; wake is a reboot.
+            return {
+                code: `{ esp_sleep_enable_timer_wakeup(static_cast<uint64_t>(${o.ms}) * 1000ULL); sys_poweroff(); }`,
+            };
+        }
+        default:
+            throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+                `Open an issue or use rawCpp() to emit it manually.`);
+    }
+}

package/dist/lowering/pwm.js

@@ -140,6 +140,31 @@ export function lowerPwm(op, chip) {
             // pulse to idle — follow with setPulse/setDuty to drive the line.
             return { code: `${marker}(void)pwm_set_dt(&${v}, ${o.periodNs}, 0);` };
         }
+        // ── Servo (hal/servo.ts) — calibrated 50 Hz sugar on the same channel ──
+        // The commanded value is runtime text; the calibrated range and travel
+        // are construction literals carried on the op. Clamping and the angle→
+        // pulse mapping run in the emitted C++ — they cannot fold at transpile
+        // time. Pulse widths convert µs→ns here (×1000).
+        case 'pwm.servo_us': {
+            const minNs = Math.round(Number(o.minUs ?? 1000) * 1000);
+            const maxNs = Math.round(Number(o.maxUs ?? 2000) * 1000);
+            return {
+                code: `{ ${marker}static bool __tc_pwm_p${o.pin}_prd = false; if (!__tc_pwm_p${o.pin}_prd) { (void)pwm_set_dt(&${v}, ${o.periodNs}, 0); __tc_pwm_p${o.pin}_prd = true; } uint32_t __tc_sv_p${o.pin} = static_cast<uint32_t>(${o.us}) * 1000U; if (__tc_sv_p${o.pin} < ${minNs}U) { __tc_sv_p${o.pin} = ${minNs}U; } if (__tc_sv_p${o.pin} > ${maxNs}U) { __tc_sv_p${o.pin} = ${maxNs}U; } (void)pwm_set_pulse_dt(&${v}, __tc_sv_p${o.pin}); }`,
+            };
+        }
+        case 'pwm.servo_angle': {
+            const minNs = Math.round(Number(o.minUs ?? 1000) * 1000);
+            const maxNs = Math.round(Number(o.maxUs ?? 2000) * 1000);
+            const maxAngle = Number(o.maxAngle ?? 180) || 180;
+            return {
+                code: `{ ${marker}static bool __tc_pwm_p${o.pin}_prd = false; if (!__tc_pwm_p${o.pin}_prd) { (void)pwm_set_dt(&${v}, ${o.periodNs}, 0); __tc_pwm_p${o.pin}_prd = true; } double __tc_sv_a${o.pin} = static_cast<double>(${o.angle}); if (__tc_sv_a${o.pin} < 0.0) { __tc_sv_a${o.pin} = 0.0; } if (__tc_sv_a${o.pin} > ${maxAngle}.0) { __tc_sv_a${o.pin} = ${maxAngle}.0; } (void)pwm_set_pulse_dt(&${v}, static_cast<uint32_t>(static_cast<double>(${minNs}) + (__tc_sv_a${o.pin} * ((static_cast<double>(${maxNs}) - static_cast<double>(${minNs})) / static_cast<double>(${maxAngle}.0))))); }`,
+            };
+        }
+        case 'pwm.servo_idle': {
+            return {
+                code: `{ ${marker}static bool __tc_pwm_p${o.pin}_prd = false; if (!__tc_pwm_p${o.pin}_prd) { (void)pwm_set_dt(&${v}, ${o.periodNs}, 0); __tc_pwm_p${o.pin}_prd = true; } (void)pwm_set_pulse_dt(&${v}, 0U); }`,
+            };
+        }
         default:
             throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
                 `Open an issue or use rawCpp() to emit it manually.`);

package/dist/lowering/sensor.d.ts

@@ -17,7 +17,7 @@ export interface SensorNames {
     /** The bus port: I2C address or SPI CS pin. */
     port: number;
     /** 'i2c' | 'spi'. */
-    busKind: 'i2c' | 'spi';
+    busKind: 'i2c' | 'spi' | 'w1';
 }
 /** Derive a sensor's DT/C++ names. The scanner regexes the emitted __tc_
  *  prefix form, so the part group must stay [a-z0-9_]+ and greedy. */
@@ -26,7 +26,7 @@ export declare function sensorNames(part: string, bus: string, port: number | st
  * Emit the per-sensor state block (device handle + sensor_value scratch).
  * Called from shimLines for each distinct sensor the program's ops reference.
  */
-export declare function sensorStateLines(part: string, bus: string, port: number | string, busKind?: string, spiHz?: number | string, spiMode?: number | string, alertPin?: number | string): string[];
+export declare function sensorStateLines(part: string, bus: string, port: number | string, busKind?: string, spiHz?: number | string, spiMode?: number | string, alertPin?: number | string, resolution?: number | string): string[];
 /**
  * Resolve a HAL sensor.* op to Zephyr C++.
  * Returns `{ code }` for fetch (statement), `{ expression }` for get (value).

package/dist/lowering/sensor.js

@@ -31,14 +31,16 @@ export function sensorNames(part, bus, port, busKind = 'i2c') {
     const portNum = typeof port === 'number' ? port : parseInt(String(port));
     const stem = busKind === 'spi'
         ? `${partKey}_spi${busIndex}_cs${portNum}`
-        : `${partKey}_i2c${busIndex}_0x${portNum.toString(16)}`;
+        : busKind === 'w1'
+            ? `${partKey}_w1_p${portNum}`
+            : `${partKey}_i2c${busIndex}_0x${portNum.toString(16)}`;
     return {
         dtLabel: `tc_${stem}`,
         devVar: `__tc_sensor_${stem}_dev`,
         valVar: `__tc_sensor_${stem}_val`,
         busIndex,
         port: portNum,
-        busKind: busKind === 'spi' ? 'spi' : 'i2c',
+        busKind: busKind === 'spi' ? 'spi' : busKind === 'w1' ? 'w1' : 'i2c',
     };
 }
 /**
@@ -67,13 +69,15 @@ function requireBusKind(partKey, info, busKind) {
  * Emit the per-sensor state block (device handle + sensor_value scratch).
  * Called from shimLines for each distinct sensor the program's ops reference.
  */
-export function sensorStateLines(part, bus, port, busKind = 'i2c', spiHz = 0, spiMode = 0, alertPin = -1) {
+export function sensorStateLines(part, bus, port, busKind = 'i2c', spiHz = 0, spiMode = 0, alertPin = -1, resolution = 12) {
     const partKey = sensorPartKey(String(part));
     requireBusKind(partKey, requirePartInfo(partKey), busKind);
     const n = sensorNames(part, bus, port, busKind);
     // The config comment carries construction facts (SPI clock, mode, alert
     // GPIO) to the overlay scanner — they shape the DT node, not the C++.
-    const cfg = `// tc-sensor-cfg: ${n.dtLabel} hz=${Number(spiHz)} mode=${Number(spiMode)} alert=${Number(alertPin)}`;
+    const cfg = busKind === 'w1'
+        ? `// tc-sensor-cfg: ${n.dtLabel} res=${Number(resolution)}`
+        : `// tc-sensor-cfg: ${n.dtLabel} hz=${Number(spiHz)} mode=${Number(spiMode)} alert=${Number(alertPin)}`;
     return [
         '// CUTTLEFISH_SENSOR_BEGIN',
         `static const struct device* ${n.devVar} = DEVICE_DT_GET(DT_NODELABEL(${n.dtLabel}));`,

package/dist/lowering/strip.d.ts

@@ -0,0 +1,16 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+/**
+ * Emit the per-strip state. Called from shimLines for each SPI controller
+ * the program drives a strip on: one `struct led_rgb` buffer sized by the
+ * construction chain length + the DT device handle.
+ */
+export declare function stripInitLines(chip: ZephyrChipDescriptor, busIndex: number, count: number): string[];
+/**
+ * Resolve a HAL strip.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops.
+ */
+export declare function lowerStrip(op: HALOpIR, chip: ZephyrChipDescriptor): {
+    code?: string;
+    expression?: string;
+};

package/dist/lowering/strip.js

@@ -0,0 +1,70 @@
+// ---------------------------------------------------------------------------
+// Strip lowering — ws2812-spi child node + led_strip_update_rgb
+//
+// The strip is an spi-device child of one of the board's wired SPI
+// controllers (Zephyr's ws2812-spi driver synthesizes the WS2812 waveform
+// on the bus's MOSI line — the board-equal form: the strip uses whatever
+// pads the board's devicetree routes that SPI to). The shim block declares
+// the pixel buffer + device handle; the overlay generator synthesizes the
+// DT child node (chain length + tuned frames — see dt-config/overlay.ts).
+// set/fill edit the buffer; show() is one led_strip_update_rgb.
+// ----------------------------------------------------------------------------
+import { parseControllerIndex } from './util.js';
+/** The C variable names for a strip on controller index `idx`. */
+function stripVars(idx) {
+    return { buf: `__tc_strip${idx}_buf`, dev: `__tc_strip${idx}_dev` };
+}
+/**
+ * Emit the per-strip state. Called from shimLines for each SPI controller
+ * the program drives a strip on: one `struct led_rgb` buffer sized by the
+ * construction chain length + the DT device handle.
+ */
+export function stripInitLines(chip, busIndex, count) {
+    const ctrl = chip.spi?.controllers[busIndex];
+    if (!ctrl)
+        return [];
+    const { buf, dev } = stripVars(busIndex);
+    return [
+        '// CUTTLEFISH_STRIP_BEGIN',
+        `static struct led_rgb ${buf}[${count}];`,
+        `static const struct device* ${dev} = DEVICE_DT_GET(DT_NODELABEL(tc_strip${busIndex}));`,
+        '// CUTTLEFISH_STRIP_END',
+    ];
+}
+/**
+ * Resolve a HAL strip.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops.
+ */
+export function lowerStrip(op, chip) {
+    const o = op;
+    // DAC discipline: a board with no wired SPI (or an out-of-range bus)
+    // lowers to a comment naming the constraint — the honest per-board answer
+    // (the manifest probe runs boardless; profileDiagnostics flags the usage).
+    const idx = parseControllerIndex(typeof o.bus === 'string' ? o.bus : String(o.bus));
+    if (!chip.spi || idx >= chip.spi.controllers.length) {
+        const wired = chip.spi ? `this board wires ${chip.spi.controllers.length} SPI controller(s)` : 'this board wires no SPI controller';
+        return { code: `/* strip on bus ${o.bus}: no such SPI controller — ${wired}; a Strip rides one of the board's SPI buses */` };
+    }
+    const { buf, dev } = stripVars(idx);
+    const count = Number(o.count ?? 1) || 1;
+    switch (op.operation) {
+        case 'strip.set_pixel': {
+            // Buffer assignment — runtime index and channel values splice as C++.
+            // The driver applies the strip's color order (GRB mapping) at show.
+            return {
+                code: `{ uint32_t __tc_strip_i = static_cast<uint32_t>(${o.index}); if (__tc_strip_i < ${count}U) { ${buf}[__tc_strip_i].r = static_cast<uint8_t>(${o.r}); ${buf}[__tc_strip_i].g = static_cast<uint8_t>(${o.g}); ${buf}[__tc_strip_i].b = static_cast<uint8_t>(${o.b}); } }`,
+            };
+        }
+        case 'strip.fill': {
+            return {
+                code: `{ for (uint32_t __tc_strip_j = 0U; __tc_strip_j < ${count}U; ++__tc_strip_j) { ${buf}[__tc_strip_j].r = static_cast<uint8_t>(${o.r}); ${buf}[__tc_strip_j].g = static_cast<uint8_t>(${o.g}); ${buf}[__tc_strip_j].b = static_cast<uint8_t>(${o.b}); } }`,
+            };
+        }
+        case 'strip.show': {
+            return { code: `(void)led_strip_update_rgb(${dev}, ${buf}, ${count}U);` };
+        }
+        default:
+            throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+                `Open an issue or use rawCpp() to emit it manually.`);
+    }
+}

package/dist/lowering/thread.js

@@ -42,8 +42,12 @@ export function lowerThread(op) {
         case 'thread.start': {
             // Store the entry, create + schedule immediately. The stack size comes
             // from the state block (the construction fact), via K_THREAD_STACK_SIZEOF.
+            // The thread gets a name so trace heartbeats report it as something
+            // other than "unnamed" — k_thread_name_set returns -ENOSYS without
+            // CONFIG_THREAD_NAME (which the scaffold turns on for traced builds),
+            // so the call is emitted unconditionally.
             return {
-                code: `${p}_fn = (${o.handler}); (void)k_thread_create(&${p}_thread, ${p}_stack, K_THREAD_STACK_SIZEOF(${p}_stack), ${p}_tramp, NULL, NULL, NULL, ${o.priority ?? 5}, 0, K_NO_WAIT);`,
+                code: `${p}_fn = (${o.handler}); (void)k_thread_create(&${p}_thread, ${p}_stack, K_THREAD_STACK_SIZEOF(${p}_stack), ${p}_tramp, NULL, NULL, NULL, ${o.priority ?? 5}, 0, K_NO_WAIT); (void)k_thread_name_set(&${p}_thread, "tc_thread_${instance}");`,
             };
         }
         case 'thread.join':

package/dist/lowering/trace.d.ts

@@ -0,0 +1,44 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+/**
+ * Resolve a HAL trace.* op to Zephyr C++. The device helpers
+ * (__tc_trace_mark / __tc_trace_event) are emitted unconditionally by
+ * shimLines — they are two printf calls, and a Trace.mark() call site must
+ * never fail to link because tracing was disabled (the lines simply have no
+ * capture listening).
+ */
+export declare function lowerTrace(op: HALOpIR): {
+    code?: string;
+    expression?: string;
+};
+/** Default heartbeat interval (ms) when zephyr.trace.intervalMs is absent. */
+export declare const TRACE_HB_DEFAULT_INTERVAL_MS = 1000;
+/** Clamp for zephyr.trace.intervalMs — faster than 50 ms floods the console
+ *  and skews the measured CPU load; slower than a minute adds nothing. */
+export declare function clampTraceIntervalMs(intervalMs: number | undefined): number;
+/**
+ * UI frame-time trace block — emitted UNCONDITIONALLY for UI-mounted
+ * programs (the call site the emitter stamps after ui_tick must never fail
+ * to link), but every body compiles away unless the heartbeat block defined
+ * CUTTLEFISH_TRACE_UI (zephyr.trace enabled). Wall-time stats only: frame
+ * count / total / max ms per heartbeat interval — the per-phase breakdown
+ * inside ui_tick stays a ui-engine change for a later stage.
+ */
+/**
+ * On-device alarm thresholds (zephyr.trace.alarms) — the sampler prints
+ * [TR:ALARM:<seq>:<code>:<detail>] the moment one is breached, so an
+ * untethered device still DETECTS the degradation; reading it only needs a
+ * capture (or a serial console) after the fact.
+ */
+export interface TraceAlarmThresholds {
+    /** Alarm when a thread's unused stack falls below this (bytes). */
+    stackMinBytes?: number;
+    /** Alarm when an interval's worst UI frame exceeds this (ms). */
+    frameMaxMs?: number;
+}
+export declare function uiFrameTraceLines(frameAlarmMs?: number): string[];
+/**
+ * The heartbeat shim lines (definitions + SYS_INIT self-start). Emitted by
+ * shimLines when the platform context carries zephyr.trace.enabled.
+ * `withUi` adds the [TR:UI: frame-stats line (UI-mounted programs).
+ */
+export declare function traceHeartbeatLines(intervalMs: number, withUi: boolean, alarms?: TraceAlarmThresholds): string[];

package/dist/lowering/trace.js

@@ -0,0 +1,239 @@
+// ---------------------------------------------------------------------------
+// Trace heartbeat — the runtime-stats sampler behind `typecad-hal trace`
+//
+// Emits a self-starting sampler into the ENTRY translation unit only (the
+// block compiles under CUTTLEFISH_ENTRY_TU, which the emitter defines once
+// per program — a copy in a split-file TU would register the SYS_INIT hook
+// twice and double every heartbeat). A k_work_delayable on the system work
+// queue samples, every intervalMs:
+//
+//   - per-thread execution cycles   (CONFIG_THREAD_RUNTIME_STATS)
+//   - per-thread stack unused/size  (CONFIG_INIT_STACKS / THREAD_STACK_INFO)
+//   - the system-wide cycle counter  (k_thread_runtime_stats_all_get — the
+//     CPU-time denominator; per-thread CPU% is computed HOST-side as
+//     delta_thread_exec / delta_sys_exec, so no cycle/Hz units leak onto
+//     the wire and idle shows up as its own thread)
+//
+// and prints `[TR:` lines on the console (printf → STDOUT_CONSOLE, the same
+// channel the test-runner protocol uses). Sampling, not event tracing: the
+// device cost is O(live threads) arithmetic per interval — no context-switch
+// hook, no ring buffer, no per-frame work — so the probe effect on the
+// measured system is one short work-queue visit per interval.
+//
+// Heap usage is deliberately NOT sampled: engine-emitted C++ is no-malloc by
+// construction (AUTOSAR rule set), so a heap series would be a constant line.
+//
+// The whole block also gates on CONFIG_THREAD_MONITOR + CONFIG_THREAD_RUNTIME
+// _STATS: the scaffold enables both when zephyr.trace.enabled is set, but a
+// user override in zephyr.kconfig compiles the sampler out instead of
+// failing the link (k_thread_foreach lives in kernel/thread_monitor.c and
+// only builds under THREAD_MONITOR).
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a HAL trace.* op to Zephyr C++. The device helpers
+ * (__tc_trace_mark / __tc_trace_event) are emitted unconditionally by
+ * shimLines — they are two printf calls, and a Trace.mark() call site must
+ * never fail to link because tracing was disabled (the lines simply have no
+ * capture listening).
+ */
+export function lowerTrace(op) {
+    const o = op;
+    switch (op.operation) {
+        case 'trace.mark':
+            return { code: `__tc_trace_mark(${o.name ?? '""'});` };
+        case 'trace.event':
+            // The value may be a runtime expression (variable, ternary) — the
+            // plugin resolved it as text; interpolate inside static_cast so any
+            // numeric C++ expression is valid here.
+            return { code: `__tc_trace_event(${o.name ?? '""'}, static_cast<double>(${o.value ?? 0}));` };
+        default:
+            throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+                `Open an issue or use rawCpp() to emit it manually.`);
+    }
+}
+/** Default heartbeat interval (ms) when zephyr.trace.intervalMs is absent. */
+export const TRACE_HB_DEFAULT_INTERVAL_MS = 1000;
+/** Clamp for zephyr.trace.intervalMs — faster than 50 ms floods the console
+ *  and skews the measured CPU load; slower than a minute adds nothing. */
+export function clampTraceIntervalMs(intervalMs) {
+    if (typeof intervalMs !== 'number' || !Number.isFinite(intervalMs)) {
+        return TRACE_HB_DEFAULT_INTERVAL_MS;
+    }
+    return Math.min(60_000, Math.max(50, Math.round(intervalMs)));
+}
+export function uiFrameTraceLines(frameAlarmMs) {
+    const alarmDefine = frameAlarmMs !== undefined ? [`#define __TC_TRACE_ALARM_FRAME ${frameAlarmMs}U`] : [];
+    const frameAlarm = frameAlarmMs !== undefined
+        ? [
+            '        // Continual monitoring: the worst frame breaching the ceiling is an',
+            '        // alarm, not a statistic — printed the moment it happens.',
+            '        if (__tc_trace_ui_max_ms > __TC_TRACE_ALARM_FRAME) {',
+            '            printf("[TR:ALARM:%u:frame:%u\\n", static_cast<unsigned int>(seq),',
+            '                   static_cast<unsigned int>(__tc_trace_ui_max_ms));',
+            '        }',
+        ]
+        : [];
+    return [
+        '// CUTTLEFISH_TRACE_UI_BEGIN',
+        '#if defined(CUTTLEFISH_TRACE_UI)',
+        ...alarmDefine,
+        'static uint32_t __tc_trace_ui_frames = 0U;',
+        'static uint32_t __tc_trace_ui_total_ms = 0U;',
+        'static uint32_t __tc_trace_ui_max_ms = 0U;',
+        'static uint64_t __tc_trace_ui_phase[5];',
+        '#endif',
+        'static inline void __tc_trace_ui_frame(uint32_t frame_delta_ms) {',
+        '#if defined(CUTTLEFISH_TRACE_UI)',
+        '    __tc_trace_ui_frames += 1U;',
+        '    __tc_trace_ui_total_ms += frame_delta_ms;',
+        '    if (frame_delta_ms > __tc_trace_ui_max_ms) { __tc_trace_ui_max_ms = frame_delta_ms; }',
+        '#else',
+        '    (void)frame_delta_ms;',
+        '#endif',
+        '}',
+        // Called from the seams the ui-engine's emitTick interleaves between its
+        // five phase slices (bindings / transitions / draw / scroll / flush).
+        // Cycles are accumulated raw; the report converts to µs once per
+        // heartbeat via sys_clock_hw_cycles_per_sec().
+        'static inline void __tc_trace_ui_phase_add(uint8_t idx, uint64_t cycles) {',
+        '#if defined(CUTTLEFISH_TRACE_UI)',
+        '    if (idx < 5U) { __tc_trace_ui_phase[idx] += cycles; }',
+        '#else',
+        '    (void)idx; (void)cycles;',
+        '#endif',
+        '}',
+        'static inline void __tc_trace_ui_report(uint32_t seq) {',
+        '#if defined(CUTTLEFISH_TRACE_UI)',
+        '    if (__tc_trace_ui_frames > 0U) {',
+        '        const uint32_t avg_x10 = (__tc_trace_ui_total_ms * 10U) / __tc_trace_ui_frames;',
+        '        printf("[TR:UI:%u:%u:%u:%u\\n", static_cast<unsigned int>(seq),',
+        '               static_cast<unsigned int>(__tc_trace_ui_frames),',
+        '               static_cast<unsigned int>(avg_x10),',
+        '               static_cast<unsigned int>(__tc_trace_ui_max_ms));',
+        '        printf("[TR:UP:%u:%llu:%llu:%llu:%llu:%llu\\n", static_cast<unsigned int>(seq),',
+        '               static_cast<unsigned long long>((__tc_trace_ui_phase[0] * 1000000ULL) / sys_clock_hw_cycles_per_sec()),',
+        '               static_cast<unsigned long long>((__tc_trace_ui_phase[1] * 1000000ULL) / sys_clock_hw_cycles_per_sec()),',
+        '               static_cast<unsigned long long>((__tc_trace_ui_phase[2] * 1000000ULL) / sys_clock_hw_cycles_per_sec()),',
+        '               static_cast<unsigned long long>((__tc_trace_ui_phase[3] * 1000000ULL) / sys_clock_hw_cycles_per_sec()),',
+        '               static_cast<unsigned long long>((__tc_trace_ui_phase[4] * 1000000ULL) / sys_clock_hw_cycles_per_sec()));',
+        ...frameAlarm,
+        '    }',
+        '#else',
+        '    (void)seq;',
+        '#endif',
+        '}',
+        'static inline void __tc_trace_ui_reset(void) {',
+        '#if defined(CUTTLEFISH_TRACE_UI)',
+        '    __tc_trace_ui_frames = 0U;',
+        '    __tc_trace_ui_total_ms = 0U;',
+        '    __tc_trace_ui_max_ms = 0U;',
+        '    for (uint8_t i = 0U; i < 5U; i++) { __tc_trace_ui_phase[i] = 0ULL; }',
+        '#endif',
+        '}',
+        '// CUTTLEFISH_TRACE_UI_END',
+    ];
+}
+/**
+ * The heartbeat shim lines (definitions + SYS_INIT self-start). Emitted by
+ * shimLines when the platform context carries zephyr.trace.enabled.
+ * `withUi` adds the [TR:UI: frame-stats line (UI-mounted programs).
+ */
+export function traceHeartbeatLines(intervalMs, withUi, alarms) {
+    const ms = clampTraceIntervalMs(intervalMs);
+    const stackAlarmDefine = alarms?.stackMinBytes !== undefined
+        ? [`#define __TC_TRACE_ALARM_STACK ${alarms.stackMinBytes}U`]
+        : [];
+    const stackAlarm = alarms?.stackMinBytes !== undefined
+        ? [
+            '    // Continual monitoring: headroom under the floor is an alarm, printed',
+            '    // the moment the sampler sees it (once per interval while held).',
+            '#ifdef __TC_TRACE_ALARM_STACK',
+            '    if (stack_ok && unused < __TC_TRACE_ALARM_STACK) {',
+            '        printf("[TR:ALARM:%u:stack:%s:%u\\n", static_cast<unsigned int>(seq), name,',
+            '               static_cast<unsigned int>(unused));',
+            '    }',
+            '#endif',
+        ]
+        : [];
+    return [
+        '// CUTTLEFISH_TRACE_BEGIN',
+        '#if defined(CUTTLEFISH_ENTRY_TU) && defined(CONFIG_THREAD_MONITOR) && defined(CONFIG_THREAD_RUNTIME_STATS)',
+        `#define __TC_TRACE_HB_MS ${ms}U`,
+        ...stackAlarmDefine,
+        'static uint32_t __tc_trace_seq = 0U;',
+        // One [TR:TH:<seq>:<name>:<exec>:<unused>:<size>] line per live thread.
+        // Stack fields print -1 when the platform cannot inspect that thread
+        // (ARC-style NO_UNUSED_STACK_INSPECTION faults) — the host reads the
+        // sentinel as "unknown", not zero.
+        'static void __tc_trace_thread_line(const struct k_thread* cthread, void* user_data) {',
+        '    (void)user_data;',
+        '    // The foreach callback hands out a const thread; the stats/name',
+        '    // syscalls take k_tid_t (non-const) — the same const_cast Zephyr\'s',
+        '    // own thread_analyzer performs at this exact boundary.',
+        '    struct k_thread* thread = const_cast<struct k_thread*>(cthread);',
+        '    const uint32_t seq = __tc_trace_seq;',
+        '    k_thread_runtime_stats_t stats;',
+        '    uint64_t exec = 0U;',
+        '    if (k_thread_runtime_stats_get(thread, &stats) == 0) {',
+        '        exec = stats.execution_cycles;',
+        '    }',
+        '    size_t unused = 0U;',
+        '    const bool stack_ok = k_thread_stack_space_get(thread, &unused) == 0;',
+        '#ifdef CONFIG_THREAD_STACK_INFO',
+        '    const size_t size = thread->stack_info.size;',
+        '#else',
+        '    const size_t size = 0U;',
+        '#endif',
+        '    char name[24];',
+        '    const char* thread_name = k_thread_name_get(thread);',
+        '    uint32_t n = 0U;',
+        '    if (thread_name != nullptr) {',
+        '        for (; thread_name[n] != \'\\0\' && n < (sizeof(name) - 1U); n++) {',
+        '            const char c = thread_name[n];',
+        '            const bool plain = (c >= \'a\' && c <= \'z\') || (c >= \'A\' && c <= \'Z\')',
+        '                || (c >= \'0\' && c <= \'9\') || c == \'_\' || c == \'-\' || c == \'.\';',
+        '            name[n] = plain ? c : \'_\';',
+        '        }',
+        '    }',
+        '    name[n] = \'\\0\';',
+        '    if (n == 0U) { name[0] = \'u\'; name[1] = \'n\'; name[2] = \'\\0\'; }',
+        '    printf("[TR:TH:%u:%s:%llu:%lld:%u\\n",',
+        '           static_cast<unsigned int>(seq), name,',
+        '           static_cast<unsigned long long>(exec),',
+        '           stack_ok ? static_cast<long long>(unused) : -1LL,',
+        '           static_cast<unsigned int>(size));',
+        ...stackAlarm,
+        '}',
+        'static void __tc_trace_hb_work(struct k_work* work);',
+        'static K_WORK_DELAYABLE_DEFINE(__tc_trace_hb_dwork, __tc_trace_hb_work);',
+        'static void __tc_trace_hb_work(struct k_work* work) {',
+        '    (void)work;',
+        '    k_thread_runtime_stats_t all;',
+        '    uint64_t sys_exec = 0U;',
+        '    if (k_thread_runtime_stats_all_get(&all) == 0) {',
+        '        sys_exec = all.execution_cycles;',
+        '    }',
+        '    __tc_trace_seq += 1U;',
+        '    printf("[TR:HB:%u:%u:%llu\\n",',
+        '           static_cast<unsigned int>(__tc_trace_seq),',
+        '           static_cast<unsigned int>(k_uptime_get_32()),',
+        '           static_cast<unsigned long long>(sys_exec));',
+        ...(withUi
+            ? [
+                '    __tc_trace_ui_report(__tc_trace_seq);',
+                '    __tc_trace_ui_reset();',
+            ]
+            : []),
+        '    k_thread_foreach(__tc_trace_thread_line, nullptr);',
+        '    k_work_reschedule(&__tc_trace_hb_dwork, K_MSEC(__TC_TRACE_HB_MS));',
+        '}',
+        'static int __tc_trace_hb_boot(void) {',
+        `    printf("[TR:CFG:1:${ms}]\\n");`,
+        '    k_work_schedule(&__tc_trace_hb_dwork, K_MSEC(__TC_TRACE_HB_MS));',
+        '    return 0;',
+        '}',
+        'SYS_INIT(__tc_trace_hb_boot, APPLICATION, CONFIG_APPLICATION_INIT_PRIORITY);',
+        '#endif // CUTTLEFISH_ENTRY_TU && THREAD_MONITOR && THREAD_RUNTIME_STATS',
+        '// CUTTLEFISH_TRACE_END',
+    ];
+}

package/dist/lowering/uart.js

@@ -26,7 +26,12 @@ export function uartInitLines(chip, controllerIndex) {
         '// CUTTLEFISH_UART_BEGIN',
         `static const struct device* ${p}_dev = DEVICE_DT_GET(DT_NODELABEL(${ctrl.nodeLabel}));`,
         `static void ${p}_init(uint32_t baud) {`,
-        `    const struct uart_config cfg = { .baudrate = (baud ? baud : 115200), .parity = UART_CFG_PARITY_NONE, .stop_bits = UART_CFG_STOP_BITS_1, .data_bits = UART_CFG_DATA_BITS_8, .flow_ctrl = UART_CFG_FLOW_CTRL_NONE };`,
+        // 115200 8N1 is the console default — reconfiguring an already-matching
+        // port RESETS the ESP32 UART's TX path and silently eats the FIRST write
+        // that follows (poll_out completes into a reconfiguring FIFO). Only a
+        // genuinely different rate reconfigures.
+        `    if (baud == 0U || baud == 115200U) { return; }`,
+        `    const struct uart_config cfg = { .baudrate = baud, .parity = UART_CFG_PARITY_NONE, .stop_bits = UART_CFG_STOP_BITS_1, .data_bits = UART_CFG_DATA_BITS_8, .flow_ctrl = UART_CFG_FLOW_CTRL_NONE };`,
         `    uart_configure(${p}_dev, &cfg);`,
         `}`,
         '// CUTTLEFISH_UART_END',

package/dist/lowering/usb.d.ts

@@ -16,7 +16,9 @@ import type { ZephyrChipDescriptor } from '../chips/types.js';
  * subsys/usb/device_next/Kconfig, include/zephyr/usb/usbd.h, and
  * samples/subsys/usb/common/sample_usbd_init.c.
  */
-export declare function usbdDeviceLines(chip: ZephyrChipDescriptor): string[];
+export declare function usbdDeviceLines(chip: ZephyrChipDescriptor, opts?: {
+    hid?: boolean;
+}): string[];
 /**
  * Emit the per-instance CDC device + init helper. Called from shimLines when
  * the program uses USB and the chip declares `usb`; must be paired with one

package/dist/lowering/usb.js

@@ -44,11 +44,11 @@ function nodeLabel(idx) {
  * subsys/usb/device_next/Kconfig, include/zephyr/usb/usbd.h, and
  * samples/subsys/usb/common/sample_usbd_init.c.
  */
-export function usbdDeviceLines(chip) {
+export function usbdDeviceLines(chip, opts) {
     if (!chip.usb)
         return [];
     const vid = chip.usb.vid ?? '0x2fe3';
-    const pid = chip.usb.pid ?? '0x0001';
+    const pid = chip.usb.pid ?? (opts?.hid ? '0x0008' : '0x0001');
     // 1200-baud touch-to-reset (BOSSA-bootloader boards): a usbd message
     // callback that reboots into the bootloader when the host sets the CDC
     // baud rate to 1200. Zephyr's CDC-ACM class publishes
@@ -126,7 +126,10 @@ export function usbdDeviceLines(chip) {
         // for boards without detection (STM32 OTG_FS).
         '    err = usbd_enable(&__tc_usbd);',
         '    if (err != 0) { printk("typecad-hal usb: enable failed: %d\\n", err); return; }',
-        '    printk("typecad-hal usb: device enabled\\n");',
+        // No success printk: the message interleaves with the hardware-test
+        // protocol on the shared uart console (a [TC:EXPECT] line corrupted
+        // mid-suite when the HID tests first brought the device up). Failures
+        // still print — a broken USB is worth the noise.
         '}',
         '// CUTTLEFISH_USBD_END',
     ];