@typecad/framework-zephyr 1.0.0-alpha.8

package/dist/chips/types.d.ts

@@ -0,0 +1,154 @@
+/**
+ * A GPIO pin described as a devicetree spec.
+ *
+ * Zephyr addresses GPIO via `struct gpio_dt_spec` resolved from devicetree
+ * aliases/labels (e.g. DT_ALIAS(led0)). The dtSpec form is preferred because
+ * `gpio_pin_set_dt()` honors the node's polarity flags — so an active-low LED
+ * (logical 1 = LED on) is handled by the DT `GPIO_ACTIVE_LOW` flag, not by the
+ * generated C++.
+ */
+export interface ZephyrGpioDtSpec {
+    /** GPIO number — matches the HAL op `pin` field (P0.X → X, P1.X → 32+X). */
+    readonly pin: number;
+    /**
+     * Devicetree alias/nodelabel macro, e.g. `led0`, `sw0`, `led1`.
+     * Emitted as `GPIO_DT_SPEC_GET(DT_ALIAS(<dtSpec>), gpios)`.
+     */
+    readonly dtSpec: string;
+}
+/**
+ * A GPIO controller devicetree node, and the HAL pin-number range it owns.
+ *
+ * Most SoCs expose a single GPIO controller (nRF52840: `gpio0` owns every
+ * pin). SoCs that split GPIO across multiple devicetree nodes — e.g. the
+ * ESP32-S3 (`gpio0`: pins 0–31, `gpio1`: pins 32–48) — list one entry per
+ * controller so the lowering can route a HAL pin to the owning controller at
+ * runtime. Pin numbers match the HAL op `pin` field.
+ */
+export interface ZephyrGpioController {
+    /** Devicetree nodelabel, e.g. 'gpio0', 'gpio1'. */
+    readonly nodelabel: string;
+    /** First HAL pin number owned by this controller (inclusive). */
+    readonly minPin: number;
+    /** Last HAL pin number owned by this controller (inclusive). */
+    readonly maxPin: number;
+}
+/**
+ * A bus controller (I2C / SPI / UART) described by its devicetree nodelabel.
+ *
+ * Zephyr resolves the `const struct device*` at compile time via
+ * `DEVICE_DT_GET(DT_NODELABEL(<nodeLabel>))`, so unlike ESP-IDF there is no
+ * lazy handle resolution — the lowering emits the macro directly.
+ */
+export interface ZephyrBusController {
+    /** Devicetree nodelabel, e.g. 'i2c1', 'spi2', 'uart0'. */
+    readonly nodeLabel: string;
+}
+/**
+ * A PWM channel described as a devicetree spec.
+ *
+ * Emitted as `struct pwm_dt_spec __tc_pwm<N> = PWM_DT_SPEC_GET(DT_ALIAS(<dtSpec>))`.
+ * `pwm_set_pulse_dt(&__tc_pwm<N>, pulse_ns)` honors the spec's period/polarity.
+ */
+export interface ZephyrPwmSpec {
+    /** GPIO number (matches the HAL op `pin` field). */
+    readonly pin: number;
+    /** Devicetree alias, e.g. 'pwm-led0'. */
+    readonly dtSpec: string;
+}
+/**
+ * A GPIO pin usable as an interrupt source.
+ *
+ * Emitted as `struct gpio_dt_spec __tc_int<N> = GPIO_DT_SPEC_GET(DT_ALIAS(<dtSpec>), gpios)`
+ * + a `struct gpio_callback` registered via `gpio_add_callback`.
+ */
+export interface ZephyrInterruptPin {
+    /** GPIO number (matches the HAL op `pin` field). */
+    readonly pin: number;
+    /** Devicetree alias, e.g. 'sw0', or a nodelabel. */
+    readonly dtSpec: string;
+}
+/**
+ * An ADC channel: which SAADC input a given HAL pin maps to.
+ *
+ * The XIAO nRF52840 has no pre-declared ADC channel nodes in devicetree, so the
+ * lowering emits `adc_channel_setup` against `DEVICE_DT_GET(DT_NODELABEL(adc))`
+ * using the `channel` index here (SAADC AIN0–AIN7).
+ */
+export interface ZephyrAdcChannel {
+    /** GPIO number (matches the HAL op `pin` field). */
+    readonly pin: number;
+    /** SAADC channel index (AIN0–AIN7). */
+    readonly channel: number;
+}
+/**
+ * Pure-data descriptor for a Zephyr board + its SoC's peripheral layout.
+ */
+export interface ZephyrChipDescriptor {
+    /** Zephyr board target (the `west build -b <id>` argument), e.g. 'xiao_ble'. */
+    readonly id: string;
+    /** SoC family, e.g. 'nrf52840'. */
+    readonly soc: string;
+    /**
+     * Default GPIO controller nodelabel for the raw-pin fallback. Pins not in
+     * `gpio.dtSpecs` are addressed via
+     * `DEVICE_DT_GET(DT_NODELABEL(<gpioController>))` + gpio_pin_*_raw().
+     *
+     * For SoCs that split GPIO across multiple devicetree nodes, `gpioControllers`
+     * overrides this per pin range; this field is then only the out-of-range
+     * fallback (so a single-controller board is unaffected by it).
+     */
+    readonly gpioController: string;
+    /**
+     * Per-range GPIO controllers for SoCs that split GPIO across multiple
+     * devicetree nodes (ESP32-S3: `gpio0` 0–31, `gpio1` 32–48). When present, the
+     * lowering routes a HAL pin to its owning controller at runtime via the
+     * emitted `__tc_gpio_dev(pin)` dispatcher; `gpioController` is the fallback.
+     * Omit on single-controller SoCs (nRF52840, RP2040, …) — every pin is on the
+     * one controller described by `gpioController`.
+     */
+    readonly gpioControllers?: readonly ZephyrGpioController[];
+    /** GPIO pins with devicetree specs (LEDs, buttons, board-defined pins). */
+    readonly gpio: {
+        readonly dtSpecs: readonly ZephyrGpioDtSpec[];
+        /** Interrupt-capable pins with DT specs (buttons etc.). */
+        readonly interruptPins?: readonly ZephyrInterruptPin[];
+    };
+    /** I2C controllers (board-wired). Index 0 = the primary bus. */
+    readonly i2c?: {
+        readonly controllers: readonly ZephyrBusController[];
+    };
+    /** SPI controllers (board-wired). Index 0 = the primary bus. */
+    readonly spi?: {
+        readonly controllers: readonly ZephyrBusController[];
+    };
+    /** UART controllers (board-wired). Index 0 = the primary port. */
+    readonly uart?: {
+        readonly controllers: readonly ZephyrBusController[];
+    };
+    /** PWM channels with DT specs. */
+    readonly pwm?: {
+        readonly specs: readonly ZephyrPwmSpec[];
+    };
+    /** ADC: the SAADC node label + the pin→channel map. */
+    readonly adc?: {
+        readonly nodeLabel: string;
+        readonly channels: readonly ZephyrAdcChannel[];
+        /** Reference voltage in millivolts (nRF internal = 3000 for VDD/4 + gain 1/4… use 3000). */
+        readonly vrefMv: number;
+        /** ADC resolution in bits. */
+        readonly resolution: number;
+    };
+    /** Watchdog node label, e.g. 'wdt0'. */
+    readonly wdt?: {
+        readonly nodeLabel: string;
+    };
+    /**
+     * WiFi capability marker. Present only on chips with a WiFi radio (ESP32-S3).
+     * Read by profileDiagnostics to flag wifi.* usage on chips without a radio.
+     * Omit on radioless chips (nRF52840) — its absence is the "no WiFi" signal.
+     */
+    readonly wifi?: {
+        readonly supported: true;
+    };
+}

package/dist/chips/types.js

@@ -0,0 +1,14 @@
+// ---------------------------------------------------------------------------
+// Zephyr chip descriptor — pure-data model
+//
+// Mirrors the per-framework chip-descriptor pattern established by
+// framework-esp32 (Esp32ChipDescriptor) and framework-avr (AVRChipDescriptor):
+// the framework owns its own device-tree-derived descriptor, keyed off the
+// Zephyr board target string in frameworkData.buildTarget. The board/MCU
+// packages are deliberately NOT read at emit time (see the framework-package
+// data-flow split); this descriptor is the source the lowering reads.
+//
+// No behavior — the lowering code in src/lowering/*.ts reads getActiveChip()
+// to resolve pins to devicetree specs and raw-controller fallbacks.
+// ---------------------------------------------------------------------------
+export {};

package/dist/chips/xiao-ble.d.ts

@@ -0,0 +1,2 @@
+import type { ZephyrChipDescriptor } from './types.js';
+export declare const XIAO_BLE: ZephyrChipDescriptor;

package/dist/chips/xiao-ble.js

@@ -0,0 +1,61 @@
+// ---------------------------------------------------------------------------
+// Seeed Studio XIAO nRF52840 — Zephyr board descriptor
+//
+// Board target: `xiao_ble` (mainline Zephyr, boards/seeed/xiao_ble).
+// The onboard user LED is active-low and exposed as the DT alias `led0`.
+// ---------------------------------------------------------------------------
+export const XIAO_BLE = {
+    id: 'xiao_ble',
+    soc: 'nrf52840',
+    gpioController: 'gpio0',
+    gpio: {
+        dtSpecs: [
+            // Onboard RGB LEDs — active-low (GPIO_ACTIVE_LOW in xiao_ble_common.dtsi).
+            // Verified against the board's `aliases { led0 = &led0; led1 = &led1; led2 = &led2; }`.
+            { pin: 26, dtSpec: 'led0' }, // Red   (P0.26)
+            { pin: 30, dtSpec: 'led1' }, // Green (P0.30)
+            { pin: 6, dtSpec: 'led2' }, // Blue  (P0.06)
+        ],
+        // The XIAO nRF52840 has a user button on P0.04, but mainline Zephyr's
+        // xiao_ble board (verified against Zephyr 4.3.99) does NOT expose it as a
+        // DT `sw0` alias — there is no gpio-keys node in xiao_ble.dts. Emitting
+        // GPIO_DT_SPEC_GET(DT_ALIAS(sw0), gpios) therefore fails to compile
+        // ('DT_N_ALIAS_sw0_... was not declared'). Until a button node + alias is
+        // added (via an overlay or an upstream board update), interruptPins stays
+        // empty: attachInterrupt on this board lowers to the no-DT-spec comment
+        // fallback rather than a hard compile error.
+        interruptPins: [],
+    },
+    // The XIAO connector wiring (from seeed_xiao_connector.dtsi + xiao_ble-pinctrl.dtsi):
+    //   xiao_i2c     → i2c1  (SDA P0.04/D4, SCL P0.05/D5)
+    //   xiao_spi     → spi2  (SCK P1.13/D8, MOSI P1.15/D10, MISO P1.14/D9)
+    //   xiao_serial  → uart0 (TX P1.11/D6, RX P1.12/D7)
+    // The board DTS leaves i2c0/spi0/spi1 disabled (shared instances).
+    i2c: {
+        controllers: [{ nodeLabel: 'i2c1' }],
+    },
+    spi: {
+        controllers: [{ nodeLabel: 'spi2' }],
+    },
+    uart: {
+        controllers: [{ nodeLabel: 'uart0' }],
+    },
+    pwm: {
+        // pwm-led0 drives the board PWM LED (PWM_OUT0 on P0.17, inverted).
+        specs: [{ pin: 17, dtSpec: 'pwm-led0' }],
+    },
+    adc: {
+        // SAADC node is `adc`; no pre-declared channels. XIAO D0–D3 = AIN0–AIN3
+        // (P0.02/P0.03/P0.28/P0.29). Internal VREF ~0.6V with VDD/4 gain ⇒ 3000mV.
+        nodeLabel: 'adc',
+        resolution: 12,
+        vrefMv: 3000,
+        channels: [
+            { pin: 2, channel: 0 }, // P0.02 / D0 / AIN0
+            { pin: 3, channel: 1 }, // P0.03 / D1 / AIN1
+            { pin: 28, channel: 2 }, // P0.28 / D2 / AIN2
+            { pin: 29, channel: 3 }, // P0.29 / D3 / AIN3
+        ],
+    },
+    wdt: { nodeLabel: 'wdt0' },
+};

package/dist/debug-codegen.d.ts

@@ -0,0 +1,33 @@
+export interface CapturedVariable {
+    name: string;
+    isFunction?: boolean;
+    /** Coarse C++ type category (inferred by the preprocessor without a checker). */
+    cppType?: 'bool' | 'int' | 'long' | 'float' | 'string' | 'unknown';
+}
+export interface LogMessagePart {
+    type: 'text' | 'variable';
+    value: string;
+}
+/**
+ * Generate the debug-mode banner. printk is always wired (Zephyr console), so
+ * there is no init to perform — just confirm debug instrumentation is live.
+ */
+export declare function generateZephyrInitCode(): string[];
+/**
+ * Generate Zephyr code for a breakpoint.
+ *
+ * The halt is __tc_debug_wait_for_continue() (emitted in ZephyrStrategy.shimLines
+ * under --debug): blocks until a byte arrives on the console, yielding to the
+ * scheduler between polls. The user must have a console attached (`west serial`
+ * or a terminal on the USB-CDC port); ENTER continues, 's' skips this breakpoint
+ * for the rest of the run.
+ *
+ * When `breakpointId` is set, the whole halt block is wrapped in
+ * `if (!__tc_bp_disabled_<id>)`, so a skipped breakpoint becomes a no-op until
+ * reboot. The flag is `static` so it persists across loop() iterations.
+ */
+export declare function generateZephyrBreakpointCode(fileName: string, lineNum: number, originalLine: string, variables: CapturedVariable[], normalizedCondition: string | undefined, breakpointId?: number): string[];
+/**
+ * Generate Zephyr code for a logpoint (logs a message without halting).
+ */
+export declare function generateZephyrLogpointCode(fileName: string, lineNum: number, parts: LogMessagePart[], variables: CapturedVariable[]): string[];

package/dist/debug-codegen.js

@@ -0,0 +1,162 @@
+// ---------------------------------------------------------------------------
+// Zephyr debug code generator — printk-based debug output
+//
+// The Zephyr counterpart to framework-esp32/src/debug-codegen.ts. Zephyr's
+// minimal C++ config has no <iostream> (manifest: needsIostream=false,
+// stdlibSupport.hasIostream=false), so the GenericStrategy's std::cout fallback
+// used by the debug preprocessor would NOT compile. This module routes every
+// debug line through printk("...\n") — the always-available Zephyr console,
+// with no CONFIG_CONSOLE dependency — so `cuttlefish build --debug` produces
+// compiling output.
+//
+// The halt primitive is __tc_debug_wait_for_continue() (emitted in
+// ZephyrStrategy.shimLines when --debug is active): a k_console-input / busy
+// poll that yields to the scheduler so an unattended breakpoint does not trip
+// any watchdog. ENTER continues; 's' disables this breakpoint for the run.
+//
+// Used by ZephyrStrategy's generateDebug* overrides, dispatched by the
+// cuttlefish debug preprocessor (cuttlefish/src/debug/preprocessor.ts).
+// ---------------------------------------------------------------------------
+/**
+ * Generate the debug-mode banner. printk is always wired (Zephyr console), so
+ * there is no init to perform — just confirm debug instrumentation is live.
+ */
+export function generateZephyrInitCode() {
+    return [
+        `// === DEBUG: Zephyr console (printk) ===`,
+        `printk("[TypeCAD] Debug Mode Active\\n");`,
+        `// === END DEBUG INIT ===`,
+        ``,
+    ];
+}
+/**
+ * Generate Zephyr code for a breakpoint.
+ *
+ * The halt is __tc_debug_wait_for_continue() (emitted in ZephyrStrategy.shimLines
+ * under --debug): blocks until a byte arrives on the console, yielding to the
+ * scheduler between polls. The user must have a console attached (`west serial`
+ * or a terminal on the USB-CDC port); ENTER continues, 's' skips this breakpoint
+ * for the rest of the run.
+ *
+ * When `breakpointId` is set, the whole halt block is wrapped in
+ * `if (!__tc_bp_disabled_<id>)`, so a skipped breakpoint becomes a no-op until
+ * reboot. The flag is `static` so it persists across loop() iterations.
+ */
+export function generateZephyrBreakpointCode(fileName, lineNum, originalLine, variables, normalizedCondition, breakpointId) {
+    const lines = [];
+    const hasDisableGuard = breakpointId !== undefined;
+    // Each wrap level adds two spaces of indent: the disable guard (outermost)
+    // then the condition (if any).
+    const indent = '  ' + (hasDisableGuard ? '  ' : '') + (normalizedCondition ? '  ' : '');
+    lines.push(`  // === BREAKPOINT: ${fileName}:${lineNum} ===`);
+    // Disable guard: a skipped breakpoint becomes a no-op until reboot. The
+    // disable state lives in the framework's debug shim (a static registry keyed
+    // by breakpointId) — NOT as a per-breakpoint declaration here, because the
+    // transpiler mangles `static bool` declarations injected into the source.
+    if (hasDisableGuard) {
+        lines.push(`  if (!__tc_bp_is_disabled(${breakpointId})) {`);
+    }
+    if (normalizedCondition) {
+        lines.push(`  ${hasDisableGuard ? '  ' : ''}if (${normalizedCondition}) {`);
+    }
+    lines.push(`${indent}printk("----------------------------------------\\n");`);
+    const headerText = normalizedCondition
+        ? `[BREAK] ${fileName}:${lineNum} (condition: ${escapeString(normalizedCondition)})`
+        : `[BREAK] ${fileName}:${lineNum}`;
+    lines.push(`${indent}printk("%s\\n", "${headerText}");`);
+    lines.push(`${indent}printk("  %s\\n", "${escapeString(originalLine)}");`);
+    if (variables.length > 0) {
+        lines.push(`${indent}printk("  Variables:\\n");`);
+        for (const v of variables) {
+            if (v.isFunction) {
+                lines.push(`${indent}printk("  - %s = [function]\\n", "${v.name}");`);
+            }
+            else {
+                const { spec, arg } = formatSpecFor(v.name, v.cppType);
+                lines.push(`${indent}printk("  - %s = ${spec}\\n", "${v.name}", ${arg});`);
+            }
+        }
+    }
+    else {
+        lines.push(`${indent}printk("  (no variables in scope)\\n");`);
+    }
+    lines.push(`${indent}printk("  [ENTER: continue | s: skip this breakpoint]\\n");`);
+    lines.push(`${indent}printk("----------------------------------------\\n");`);
+    // Halt — block on console input, scheduler-yielding. 's' records this id as
+    // disabled in the shim's registry. Pass -1 when no id (never disable).
+    lines.push(`${indent}__tc_debug_wait_for_continue(${hasDisableGuard ? breakpointId : -1});`);
+    if (normalizedCondition) {
+        lines.push(`  ${hasDisableGuard ? '  ' : ''}}`);
+    }
+    if (hasDisableGuard) {
+        lines.push(`  }`);
+    }
+    lines.push(`  // === END BREAKPOINT ===`);
+    return lines;
+}
+/**
+ * Generate Zephyr code for a logpoint (logs a message without halting).
+ */
+export function generateZephyrLogpointCode(fileName, lineNum, parts, variables) {
+    const lines = [];
+    lines.push(`  // === LOGPOINT: ${fileName}:${lineNum} ===`);
+    lines.push(`  printk("[LOG ${fileName}:${lineNum}] ");`);
+    for (const part of parts) {
+        if (part.type === 'text') {
+            lines.push(`  printk("${escapeString(part.value)}");`);
+        }
+        else {
+            // variable part: only printable if it is a non-function value in scope.
+            const match = variables.find((v) => v.name === part.value && !v.isFunction);
+            if (match) {
+                const { spec, arg } = formatSpecFor(match.name, match.cppType);
+                lines.push(`  printk("${spec}", ${arg});`);
+            }
+            else {
+                lines.push(`  printk("{${escapeString(part.value)}}"); // variable not in scope`);
+            }
+        }
+    }
+    lines.push(`  printk("\\n");`);
+    lines.push(`  // === END LOGPOINT ===`);
+    return lines;
+}
+/**
+ * Escape a string for use inside printk("..."). Same rules as the ESP-IDF
+ * generator: backslash, double-quote, newline, carriage return.
+ */
+function escapeString(s) {
+    return s
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r');
+}
+/**
+ * Pick a printk format specifier + argument expression for a debug variable.
+ *
+ * The debug preprocessor has no TypeChecker, so `cppType` is a coarse category
+ * inferred from AST shape. For `unknown` we cast to `double` and use `%g` so
+ * the generated printk always compiles for any numeric/bool variable. printk
+ * supports the standard printf format specifiers.
+ *
+ * Returns `{ spec, arg }` where `spec` is the `%`-specifier substring to embed
+ * in the format string and `arg` is the C++ argument expression.
+ */
+function formatSpecFor(varName, cppType) {
+    switch (cppType) {
+        case 'bool':
+        case 'int':
+            return { spec: '%d', arg: varName };
+        case 'long':
+            return { spec: '%ld', arg: varName };
+        case 'float':
+            return { spec: '%g', arg: varName };
+        case 'string':
+            return { spec: '%s', arg: varName };
+        case 'unknown':
+        default:
+            // Cast to double so printk compiles regardless of the real C++ type.
+            return { spec: '%g', arg: `static_cast<double>(${varName})` };
+    }
+}

package/dist/display/gfx.d.ts

@@ -0,0 +1,17 @@
+import type { ZephyrDisplayProfile } from './profiles.js';
+export interface DisplayRuntimeResult {
+    /** #include lines to force when the display is used. */
+    readonly includes: string[];
+    /** File-scope C++ declarations (device handle + line buffer). */
+    readonly stateLines: string[];
+    /** The C++ helper functions (display_init/fill_rect/draw_rect/draw_text/flush). */
+    readonly helpers: string;
+    /** The C++ font-table source (exposed for testing). */
+    readonly fontTable: string;
+}
+/**
+ * Build the display runtime C++ for a profile. The line buffer is one row
+ * (width pixels × 2 bytes rgb565); fill_rect/draw_rect/draw_text compute into
+ * it row-by-row and display_write each row. No full framebuffer.
+ */
+export declare function buildDisplayRuntime(profile: ZephyrDisplayProfile): DisplayRuntimeResult;

package/dist/display/gfx.js

@@ -0,0 +1,171 @@
+// ---------------------------------------------------------------------------
+// Zephyr display GFX runtime — generic display_write + ported GFX primitives
+//
+// Emits C++ that resolves a DT-bound display device, keeps a one-row line
+// buffer (no full framebuffer — see AGENTS.md rendering guardrails), and
+// implements fill_rect / draw_rect / draw_text / flush on top of display_write.
+// Text uses a minimal 5x7 bitmap font covering digits 0-9 and uppercase A-Z
+// only; unknown characters render as a space.
+//
+// EMIT BOUNDARY: emitted bytes land in user firmware. Covered by the TypeCAD
+// Runtime Exception (RUNTIME_EXCEPTION.md at the repo root).
+// ---------------------------------------------------------------------------
+// 5x7 bitmap glyphs for 0-9 and A-Z. Each glyph is 5 bytes (columns), MSB=top.
+// Unknown characters fall back to the space (all-zero columns).
+// (Compact hand-authored bitmaps; the test asserts presence of '0'..'9','A'..'Z'.)
+function fontTableCpp() {
+    // A flat map: char -> 5 bytes. Built so the test sees '0'..'9' and 'A'..'Z'.
+    const glyphs = {
+        '0': [0x3e, 0x51, 0x49, 0x45, 0x3e],
+        '1': [0x00, 0x42, 0x7f, 0x40, 0x00],
+        '2': [0x42, 0x61, 0x51, 0x49, 0x46],
+        '3': [0x21, 0x41, 0x45, 0x4b, 0x31],
+        '4': [0x18, 0x14, 0x12, 0x7f, 0x10],
+        '5': [0x27, 0x45, 0x45, 0x45, 0x39],
+        '6': [0x3c, 0x4a, 0x49, 0x49, 0x30],
+        '7': [0x01, 0x71, 0x09, 0x05, 0x03],
+        '8': [0x36, 0x49, 0x49, 0x49, 0x36],
+        '9': [0x06, 0x49, 0x49, 0x29, 0x1e],
+        'A': [0x7e, 0x11, 0x11, 0x11, 0x7e],
+        'B': [0x7f, 0x49, 0x49, 0x49, 0x36],
+        'C': [0x3e, 0x41, 0x41, 0x41, 0x22],
+        'D': [0x7f, 0x41, 0x41, 0x22, 0x1c],
+        'E': [0x7f, 0x49, 0x49, 0x49, 0x41],
+        'F': [0x7f, 0x09, 0x09, 0x09, 0x01],
+        'G': [0x3e, 0x41, 0x49, 0x49, 0x7a],
+        'H': [0x7f, 0x08, 0x08, 0x08, 0x7f],
+        'I': [0x00, 0x41, 0x7f, 0x41, 0x00],
+        'J': [0x20, 0x40, 0x41, 0x3f, 0x01],
+        'K': [0x7f, 0x08, 0x14, 0x22, 0x41],
+        'L': [0x7f, 0x40, 0x40, 0x40, 0x40],
+        'M': [0x7f, 0x02, 0x0c, 0x02, 0x7f],
+        'N': [0x7f, 0x04, 0x08, 0x10, 0x7f],
+        'O': [0x3e, 0x41, 0x41, 0x41, 0x3e],
+        'P': [0x7f, 0x09, 0x09, 0x09, 0x06],
+        'Q': [0x3e, 0x41, 0x51, 0x21, 0x5e],
+        'R': [0x7f, 0x09, 0x19, 0x29, 0x46],
+        'S': [0x46, 0x49, 0x49, 0x49, 0x31],
+        'T': [0x01, 0x01, 0x7f, 0x01, 0x01],
+        'U': [0x3f, 0x40, 0x40, 0x40, 0x3f],
+        'V': [0x1f, 0x20, 0x40, 0x20, 0x1f],
+        'W': [0x3f, 0x40, 0x38, 0x40, 0x3f],
+        'X': [0x63, 0x14, 0x08, 0x14, 0x63],
+        'Y': [0x07, 0x08, 0x70, 0x08, 0x07],
+        'Z': [0x61, 0x51, 0x49, 0x45, 0x43],
+    };
+    const lines = [
+        '// Minimal 5x7 font: digits 0-9 and uppercase A-Z. Unknown chars → space.',
+        '// (Rows for other codes are all-zero — the table is indexed by char code.)',
+        'static const uint8_t __tc_font5x7[128][5] = {',
+    ];
+    for (let c = 0; c < 128; c++) {
+        const ch = String.fromCharCode(c);
+        const known = Object.prototype.hasOwnProperty.call(glyphs, ch);
+        const g = glyphs[ch] ?? [0x00, 0x00, 0x00, 0x00, 0x00];
+        // Annotate known glyphs (0-9, A-Z) with their char literal; other rows use
+        // only the code point so the table carries no stray char literals.
+        const label = known ? ` '${ch}'` : ` ${c}`;
+        lines.push(`    {0x${g[0].toString(16).padStart(2, '0')}, 0x${g[1].toString(16).padStart(2, '0')}, 0x${g[2].toString(16).padStart(2, '0')}, 0x${g[3].toString(16).padStart(2, '0')}, 0x${g[4].toString(16).padStart(2, '0')}}, //${label}`);
+    }
+    lines.push('};');
+    return lines.join('\n');
+}
+/**
+ * Build the display runtime C++ for a profile. The line buffer is one row
+ * (width pixels × 2 bytes rgb565); fill_rect/draw_rect/draw_text compute into
+ * it row-by-row and display_write each row. No full framebuffer.
+ */
+export function buildDisplayRuntime(profile) {
+    const w = profile.width;
+    const stateLines = [
+        '// CUTTLEFISH_DISPLAY_BEGIN',
+        `static const struct device* __tc_display = DEVICE_DT_GET(DT_NODELABEL(${profile.dtLabel}));`,
+        `static uint16_t __tc_display_line[${w}];  // one-row line buffer (rgb565)`,
+        '// CUTTLEFISH_DISPLAY_END',
+    ];
+    // Backlight is optional: the overlay emits the DT alias only when a backlight
+    // GPIO is configured. Guard with DT_HAS_ALIAS so this compiles whether or not
+    // the alias exists (DT_NODE_HAS_STATUS(DT_ALIAS(...)) is version-dependent
+    // when the alias is missing).
+    const blInit = profile.backlight
+        ? `#if DT_HAS_ALIAS(${profile.backlight})\n    const struct device* __bl = DEVICE_DT_GET(DT_ALIAS(${profile.backlight}));\n    gpio_pin_configure(__bl, 0, GPIO_OUTPUT); gpio_pin_set(__bl, 0, 1);\n#endif`
+        : '';
+    const helpers = `
+// Write a single row of \`rw\` rgb565 pixels at (x,y). Builds the
+// display_buffer_descriptor the Zephyr display_write API requires (rgb565 =
+// 2 bytes/pixel) and pushes the one-row line buffer.
+static inline void __tc_display_write_row(uint16_t x, uint16_t y, uint16_t rw) {
+    struct display_buffer_descriptor __desc;
+    __desc.buf_size = static_cast<uint32_t>(rw) * 2U;   // 2 bytes per rgb565 pixel
+    __desc.width = rw;
+    __desc.height = 1U;
+    __desc.pitch = rw;
+    __desc.frame_incomplete = false;
+    (void)display_write(__tc_display, x, y, &__desc, __tc_display_line);
+}
+
+static inline void display_init(void) {
+    if (!device_is_ready(__tc_display)) { for (;;) { k_msleep(1000); } }
+${blInit}
+    display_blanking_off(__tc_display);
+}
+
+static inline void display_fill_rect(uint16_t x, uint16_t y, uint16_t rw, uint16_t h, uint16_t color) {
+    for (uint16_t row = 0; row < h; row++) {
+        for (uint16_t i = 0; i < rw; i++) { __tc_display_line[i] = color; }
+        __tc_display_write_row(x, static_cast<uint16_t>(y + row), rw);
+    }
+}
+
+static inline void display_draw_rect(uint16_t x, uint16_t y, uint16_t rw, uint16_t h, uint16_t color) {
+    // Top + bottom edges.
+    for (uint16_t i = 0; i < rw; i++) { __tc_display_line[i] = color; }
+    __tc_display_write_row(x, y, rw);
+    __tc_display_write_row(x, static_cast<uint16_t>(y + h - 1U), rw);
+    // Left + right edges.
+    for (uint16_t row = 1U; row < h - 1U; row++) {
+        __tc_display_line[0] = color;
+        if (rw > 1U) { __tc_display_line[rw - 1U] = color; }
+        __tc_display_write_row(x, static_cast<uint16_t>(y + row), rw);
+    }
+}
+
+static inline void display_draw_text(uint16_t x, uint16_t y, const char* text, uint16_t color) {
+    uint16_t cx = x;
+    for (const char* p = text; *p != 0; p++) {
+        // Read the byte UNSIGNED so bytes >= 0x80 don't index the 128-entry
+        // font table negatively (signed char would make 0x80 == -128).
+        uint8_t uc = static_cast<uint8_t>(*p);
+        if (uc >= 128U) { uc = static_cast<uint8_t>(' '); }     // unknown → space
+        const uint8_t* glyph = &__tc_font5x7[uc][0];
+        // Lowercase → uppercase; anything outside 0-9/A-Z → space glyph.
+        if (uc >= static_cast<uint8_t>('a') && uc <= static_cast<uint8_t>('z')) {
+            glyph = &__tc_font5x7[uc - 32U][0];
+        } else if (uc < static_cast<uint8_t>('0')
+                   || (uc > static_cast<uint8_t>('9') && uc < static_cast<uint8_t>('A'))
+                   || uc > static_cast<uint8_t>('Z')) {
+            glyph = &__tc_font5x7[static_cast<uint8_t>(' ')][0];
+        }
+        for (uint16_t col = 0; col < 5U; col++) {
+            uint8_t bits = glyph[col];
+            for (uint16_t row = 0; row < 7U; row++) {
+                __tc_display_line[0] = ((bits & static_cast<uint8_t>(1U << row)) != 0U) ? color : 0U;
+                __tc_display_write_row(static_cast<uint16_t>(cx + col), static_cast<uint16_t>(y + row), 1U);
+            }
+        }
+        cx = static_cast<uint16_t>(cx + 6U);  // 5 cols + 1 space
+    }
+}
+
+static inline void display_flush(void) {
+    // No-op: writes are immediate via display_write; there is no framebuffer to push.
+}
+`;
+    const fontTable = fontTableCpp();
+    return {
+        includes: ['<zephyr/drivers/display.h>'],
+        stateLines,
+        helpers,
+        fontTable,
+    };
+}

package/dist/display/index.d.ts

@@ -0,0 +1,20 @@
+import type { DisplayHALOp } from '@typecad/cuttlefish/api/shared';
+import { type ZephyrDisplayProfile } from './profiles.js';
+export { zephyrUiDisplayAdapter, zephyrDisplayAdapterGenerator } from './ui-adapter.js';
+export { zephyrTouchAdapter } from './touch-adapter.js';
+export { ZEPHYR_DISPLAY_PROFILES, DEFAULT_ZEPHYR_DISPLAY_PROFILE } from './profiles.js';
+export type { ZephyrDisplayProfile } from './profiles.js';
+export interface DisplayState {
+    initialized: boolean;
+    profile: ZephyrDisplayProfile;
+}
+/** Fresh display state (used by the strategy per-build). */
+export declare function newDisplayState(): DisplayState;
+/**
+ * Resolve a display.* op. Returns { code } for statement ops, undefined when
+ * the op is not recognized.
+ */
+export declare function resolveZephyrDisplayOp(op: DisplayHALOp, state: DisplayState): {
+    code?: string;
+    expression?: string;
+} | undefined;