@typecad/framework-zephyr 1.0.0-alpha.10 → 1.0.0-alpha.11

package/dist/toolchain/env-check.js

@@ -0,0 +1,190 @@
+// ---------------------------------------------------------------------------
+// Zephyr environment check — the shared detection behind `cuttlefish doctor`.
+//
+// Mirrors @typecad/arduino-cli's checkArduinoEnv(): gather the impure
+// environment facts once (west presence + version, Zephyr version, board
+// existence), then reduce them to a structured result the doctor (and, later,
+// the build/test gates) can present uniformly. The check is side-effect-free
+// and never throws — it never installs or mutates anything.
+//
+// Two parity checks vs. framework-arduino's doctor:
+//  1. west (the Zephyr build tool) is discoverable + responsive — the direct
+//     analog of "arduino-cli is installed". discoverWest() already confirms
+//     responsiveness via `west --version`; we additionally capture the version
+//     string to report it.
+//  2. the configured board target exists in the Zephyr checkout
+//     ($ZEPHYR_BASE/boards/) — the analog of "the required core is installed".
+//
+// The existing compat-range check (compat.ts) is folded in as a third check so
+// the doctor reports everything through one entry point.
+// ---------------------------------------------------------------------------
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { discoverWest, resetWestDiscoveryCache } from './west-discover.js';
+import { westSpawn } from './west-spawn.js';
+import { detectZephyrVersion, checkZephyrCompat, resolveBoardTarget, } from './compat.js';
+// ---- west probe (impure; isolated + cached + overridable) ------------------
+let cachedProbe;
+/** Clear the west-probe cache (for tests). Also resets discovery cache. */
+export function resetWestProbeCacheForTest() {
+    cachedProbe = undefined;
+    resetWestDiscoveryCache();
+}
+/**
+ * Gather west facts: discover a usable install, then run `west --version`
+ * through it to capture the version. Memoized for the process lifetime (west
+ * installs don't move). Never throws — returns westFound:false on any failure.
+ */
+export function probeWestEnv() {
+    if (cachedProbe)
+        return cachedProbe;
+    const install = discoverWest();
+    const envBase = process.env.ZEPHYR_BASE || undefined;
+    if (!install) {
+        const data = {
+            westFound: false,
+            westVersion: undefined,
+            source: undefined,
+            zephyrBase: envBase,
+        };
+        cachedProbe = data;
+        return data;
+    }
+    // Run `west --version` through the discovered install to capture the version.
+    // discoverWest() already confirmed responsiveness, so a parse failure here is
+    // not "unresponsive" — it just means we couldn't read a version token.
+    let westVersion;
+    try {
+        const inv = westSpawn(['--version'], {
+            encoding: 'utf8',
+            timeout: 15_000,
+            windowsHide: true,
+        });
+        const r = spawnSync(inv.command, inv.args, inv.options);
+        if (r.status === 0) {
+            // inv.options is a generic SpawnSyncOptions (no encoding literal), so
+            // coerce stdout to a string before matching.
+            const out = typeof r.stdout === 'string' ? r.stdout : '';
+            const m = out.match(/v?(\d+\.\d+\.\d+)/);
+            westVersion = m ? m[1] : undefined;
+        }
+    }
+    catch {
+        // westSpawn throws only when discovery fails — but discovery already
+        // succeeded (install is non-null). Defensive: treat as no version read.
+        westVersion = undefined;
+    }
+    const data = {
+        westFound: true,
+        westVersion,
+        source: install.source,
+        zephyrBase: envBase ?? install.zephyrBase,
+    };
+    cachedProbe = data;
+    return data;
+}
+// ---- board existence (pure-ish fs probe) -----------------------------------
+/**
+ * Does `boardId` exist as a board directory in the Zephyr checkout? Checks the
+ * HWMv2 vendor layout used by Zephyr 4.x: $ZEPHYR_BASE/boards/<vendor>/<boardId>.
+ * Returns true/false when determinable; undefined when the base is unknown or
+ * the boards/ tree can't be read (so callers never fail on an inconclusive
+ * lookup — they just skip the board check).
+ */
+export function boardExistsInCheckout(boardId, zephyrBase) {
+    if (!zephyrBase)
+        return undefined;
+    const boards = join(zephyrBase, 'boards');
+    try {
+        const entries = readdirSync(boards, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory() && existsSync(join(boards, entry.name, boardId))) {
+                return true;
+            }
+        }
+        return false;
+    }
+    catch {
+        return undefined;
+    }
+}
+// ---- main entry point -------------------------------------------------------
+/**
+ * Verify the environment can build for `buildTarget`. Cheap and
+ * side-effect-free: discovers west, reads the Zephyr version, checks the compat
+ * range, and — when a target is configured — verifies the board exists in the
+ * checkout. Reports what (if anything) is wrong.
+ *
+ * - If `buildTarget` is undefined/empty, the board check is skipped (not a
+ *   failure), mirroring Arduino's no-FQBN path.
+ * - Never installs anything. Never mutates the user environment.
+ * - Never throws — always returns a result. Callers decide how to react.
+ *
+ * `options` is for-test only (injects fake probe data / board lookup).
+ */
+export function checkZephyrEnv(buildTarget, options) {
+    const probe = options?.fakeWestProbe ?? probeWestEnv();
+    const boardLookup = options?.fakeBoardExists ?? boardExistsInCheckout;
+    const zephyrVersion = detectZephyrVersion();
+    const compat = checkZephyrCompat(zephyrVersion);
+    const resolvedBoardTarget = buildTarget ? resolveBoardTarget(buildTarget, zephyrVersion) : undefined;
+    const boardId = resolvedBoardTarget ? resolvedBoardTarget.split('/')[0] : undefined;
+    const boardTargetSupported = boardId !== undefined ? boardLookup(boardId, probe.zephyrBase) : undefined;
+    const check = {
+        westFound: probe.westFound,
+        westVersion: probe.westVersion,
+        westSource: probe.source,
+        zephyrBase: probe.zephyrBase,
+        zephyrVersion,
+        compatRange: compat.range,
+        compatStatus: compat.status,
+        buildTarget,
+        resolvedBoardTarget,
+        boardTargetSupported,
+    };
+    // 1. west (the build tool) missing entirely — nothing else can run.
+    if (!probe.westFound) {
+        return {
+            ok: false,
+            reason: 'west-not-found',
+            check,
+            messages: [
+                "west (the Zephyr build tool) was not found.",
+                "  Run the typeCAD Zephyr installer, activate an existing Zephyr venv,",
+                "  set ZEPHYR_BASE to a Zephyr SDK root, or `pip install west`.",
+            ],
+            fixCommand: undefined,
+        };
+    }
+    // 2. west healthy but the Zephyr RTOS is outside the supported range.
+    if (compat.status === 'out-of-range') {
+        return {
+            ok: false,
+            reason: 'zephyr-out-of-range',
+            check,
+            messages: [
+                `Zephyr ${zephyrVersion} is outside the supported range (${compat.range}) for @typecad/framework-zephyr.`,
+                "  Set ZEPHYR_BASE to a compatible Zephyr checkout, or install one via '@typecad/zephyr-installer'.",
+            ],
+            fixCommand: undefined,
+        };
+    }
+    // 3. west + version OK — only check the board when a target is configured and
+    // the lookup was able to answer. A missing/absent target is not a board
+    // problem; an inconclusive lookup (no base) is reported as a skip, not a fail.
+    if (buildTarget && boardTargetSupported === false) {
+        return {
+            ok: false,
+            reason: 'board-not-supported',
+            check,
+            messages: [
+                `Board target '${resolvedBoardTarget}' was not found in this Zephyr checkout` +
+                    (probe.zephyrBase ? ` (${join(probe.zephyrBase, 'boards')}).` : '.'),
+                "  Check the board id, or run `west boards` to list boards in this checkout.",
+            ],
+            fixCommand: 'west boards',
+        };
+    }
+    return { ok: true, check };
+}

package/dist/toolchain/scaffold.js

@@ -85,6 +85,9 @@ export function scaffoldZephyrProject(projectRoot, debug = false, userKconfig, p
     const usage = {
         usesAdc: uses('adc_'),
         usesPwm: uses('pwm_'),
+        usesDac: uses('dac_') || uses('__tc_dac'),
+        usesFS: uses('__tc_fs'),
+        usesHwtimer: uses('counter_') || uses('__tc_hw'),
         usesI2c: uses('i2c_'),
         usesSpi: uses('spi_'),
         usesUart: uses('uart_'),

package/dist/toolchain/west-discover.d.ts

@@ -4,15 +4,21 @@
  * `pythonExecutable -m west`.
  */
 export interface WestInstall {
-    mode: 'launcher' | 'module';
+    mode: 'launcher' | 'module' | 'micromamba';
     /** Absolute path to a `west` launcher (mode 'launcher') or undefined. */
     westExecutable?: string;
     /** Absolute path to a Python interpreter with west installed (mode 'module'). */
     pythonExecutable?: string;
     /** Absolute path to the Zephyr SDK root (for $ZEPHYR_BASE), if found. */
     zephyrBase?: string;
+    /** mode 'micromamba': path to the micromamba binary (for `micromamba run -n …`). */
+    micromambaExe?: string;
+    /** mode 'micromamba': the conda env name (default 'zephyr'). */
+    envName?: string;
+    /** mode 'micromamba': MAMBA_ROOT_PREFIX, injected so micromamba finds its envs. */
+    mambaRootPrefix?: string;
     /** Which discovery strategy found this install. */
-    source: 'path' | 'zephyr-base-venv' | 'well-known' | 'system-python';
+    source: 'path' | 'zephyr-base-venv' | 'well-known' | 'system-python' | 'micromamba';
 }
 /** True if `dir` looks like a Zephyr SDK root: has CMakeLists.txt and the
  *  kernel header. */
@@ -21,6 +27,7 @@ export declare function discoverFromPath(): WestInstall | null;
 /** The canonical Zephyr workspace layout puts the venv beside the SDK:
  *  <workspace>/{.venv, zephyr}. So ${ZEPHYR_BASE}/../.venv is the venv. */
 export declare function discoverFromZephyrBase(): WestInstall | null;
+export declare function discoverFromMicromamba(envName?: string): WestInstall | null;
 /** Candidate Zephyr workspace directories. Each may contain both `.venv/`
  *  and `zephyr/` (the SDK). Exported for test injection. */
 export declare function wellKnownWorkspaces(): string[];
@@ -34,7 +41,8 @@ export declare function resetWestDiscoveryCache(): void;
  * Try each discovery strategy in order. The first usable install wins.
  * Result is memoized for the process lifetime (west installs don't move).
  *
- * Order: PATH → $ZEPHYR_BASE venv → well-known workspaces → system pythons.
+ * Order: PATH → $ZEPHYR_BASE venv → micromamba env → well-known workspaces →
+ * system pythons.
  * Returns null when no usable west install is found.
  */
 export declare function discoverWest(): WestInstall | null;

package/dist/toolchain/west-discover.js

@@ -10,14 +10,16 @@
 // Discovery cascade (first usable wins):
 //   1. `west` already on PATH (env already activated / global install).
 //   2. $ZEPHYR_BASE venv: ${ZEPHYR_BASE}/../.venv/<python> -m west.
-//   3. Well-known workspace layouts: ~/zephyrproject/.venv, /opt/zephyrproject/.
+//   3. micromamba env from @typecad/zephyr-installer (invoked via `micromamba run`,
+//      so cuttlefish builds work with NO manual activation).
+//   4. Well-known workspace layouts: ~/zephyrproject/.venv, /opt/zephyrproject/.
 //      venv, etc.
-//   4. System pythons (`python`, `python3`, `py`) via `-m west`.
+//   5. System pythons (`python`, `python3`, `py`) via `-m west`.
 //
 // Leaner than the ESP-IDF equivalent: west needs no env sourcing (no 15s
 // export.sh) — only the right interpreter + ZEPHYR_BASE.
 // ---------------------------------------------------------------------------
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
@@ -106,7 +108,77 @@ export function discoverFromZephyrBase() {
         source: 'zephyr-base-venv',
     };
 }
-// ── Strategy 3: well-known workspace layouts ───────────────────────────────
+// ── Strategy 3: micromamba env (the @typecad/zephyr-installer install) ─────
+// Locate the micromamba binary + root prefix. The installer downloads
+// micromamba to $MAMBA_ROOT_PREFIX/bin (POSIX) or Library/bin (Windows); the
+// root defaults to ~/micromamba. Returns null if the binary isn't present
+// (the installer hasn't run on this machine).
+function findMicromamba() {
+    const root = process.env.MAMBA_ROOT_PREFIX || join(homedir(), 'micromamba');
+    const exe = IS_WIN
+        ? join(root, 'Library', 'bin', 'micromamba.exe')
+        : join(root, 'bin', 'micromamba');
+    return existsSync(exe) ? { exe, rootPrefix: root } : null;
+}
+/**
+ * The micromamba env created by `@typecad/zephyr-installer`. The env's west
+ * lives at envs/<name>/bin/west (POSIX) or Scripts/west.exe (Windows). Found
+ * installs are invoked via `micromamba run -n <name> west …` (see
+ * west-spawn.ts), which sets up the env's full PATH (cmake/ninja/dtc) AND runs
+ * the activation hook (ZEPHYR_BASE / ZEPHYR_SDK_INSTALL_DIR) — so cuttlefish
+ * builds work with NO manual `micromamba activate`. This is what makes a fresh
+ * `cuttlefish build` succeed in any project without the user activating.
+ *
+ * Env name defaults to "zephyr"; override via TYPECAD_ZEPHYR_ENV. File-check
+ * based (no spawn) so it's cheap to run on every cuttlefish invocation.
+ */
+/** Read a TYPECAD_ZEPHYR_* value from the installer-written env-vars file in
+ *  a micromamba env. Handles .sh (export VAR="val"), .bat (set "VAR=val"),
+ *  and .ps1 ($env:VAR = "val"). Returns undefined if absent/unreadable. */
+function readMicromambaEnvVar(envDir, varName) {
+    const candidates = IS_WIN
+        ? [join(envDir, 'etc', 'conda', 'env-vars.ps1'), join(envDir, 'etc', 'conda', 'env-vars.bat')]
+        : [join(envDir, 'etc', 'conda', 'env-vars.sh')];
+    for (const f of candidates) {
+        if (!existsSync(f))
+            continue;
+        try {
+            const text = readFileSync(f, 'utf8');
+            // .sh/.ps1: VAR = "value" (quoted value after =).
+            let m = text.match(new RegExp(`${varName}\\s*=\\s*"([^"]+)"`));
+            if (m)
+                return m[1];
+            // .bat: set "VAR=value" (value after VAR= inside quotes).
+            m = text.match(new RegExp(`${varName}=([^"\\r\\n]+)"`));
+            if (m)
+                return m[1].trim();
+        }
+        catch { /* ignore unreadable */ }
+    }
+    return undefined;
+}
+export function discoverFromMicromamba(envName = process.env.TYPECAD_ZEPHYR_ENV || 'zephyr') {
+    const mm = findMicromamba();
+    if (!mm)
+        return null;
+    const envDir = join(mm.rootPrefix, 'envs', envName);
+    const westExe = join(envDir, IS_WIN ? 'Scripts' : 'bin', IS_WIN ? 'west.exe' : 'west');
+    if (!existsSync(envDir) || !existsSync(westExe))
+        return null;
+    // Read ZEPHYR_BASE from the installer's env-vars so the compat check (and
+    // anything else in the cuttlefish process) can detect the Zephyr version
+    // WITHOUT activation — micromamba run sets it only inside the west subprocess.
+    const zb = readMicromambaEnvVar(envDir, 'TYPECAD_ZEPHYR_BASE');
+    return {
+        mode: 'micromamba',
+        micromambaExe: mm.exe,
+        envName,
+        mambaRootPrefix: mm.rootPrefix,
+        zephyrBase: zb && isZephyrBase(zb) ? zb : undefined,
+        source: 'micromamba',
+    };
+}
+// ── Strategy 4: well-known workspace layouts ───────────────────────────────
 /** Candidate Zephyr workspace directories. Each may contain both `.venv/`
  *  and `zephyr/` (the SDK). Exported for test injection. */
 export function wellKnownWorkspaces() {
@@ -143,7 +215,7 @@ export function discoverFromWellKnown(workspaces = wellKnownWorkspaces()) {
     }
     return null;
 }
-// ── Strategy 4: system pythons via `-m west` ────────────────────────────────
+// ── Strategy 5: system pythons via `-m west` ────────────────────────────────
 /** Candidate system Python interpreters to probe with `-m west`. */
 export function systemPythons() {
     if (IS_WIN)
@@ -173,7 +245,8 @@ export function resetWestDiscoveryCache() {
  * Try each discovery strategy in order. The first usable install wins.
  * Result is memoized for the process lifetime (west installs don't move).
  *
- * Order: PATH → $ZEPHYR_BASE venv → well-known workspaces → system pythons.
+ * Order: PATH → $ZEPHYR_BASE venv → micromamba env → well-known workspaces →
+ * system pythons.
  * Returns null when no usable west install is found.
  */
 export function discoverWest() {
@@ -182,6 +255,7 @@ export function discoverWest() {
     const strategies = [
         discoverFromPath,
         discoverFromZephyrBase,
+        discoverFromMicromamba,
         discoverFromWellKnown,
         discoverFromSystemPython,
     ];

package/dist/toolchain/west-spawn.js

@@ -98,6 +98,21 @@ export function westSpawn(westArgs, baseOptions) {
     // Strip `shell` if present — we pass absolute paths / known commands, and
     // an explicit shell changes arg-quoting semantics on Windows.
     const { shell: _drop, ...optsWithoutShell } = baseOptions;
+    if (install.mode === 'micromamba' && install.micromambaExe) {
+        // `micromamba run -n <env> west …` sets up the env's full PATH
+        // (cmake/ninja/dtc) and runs the activation hook (ZEPHYR_BASE /
+        // ZEPHYR_SDK_INSTALL_DIR), so cuttlefish builds work WITHOUT the user
+        // activating the env. Inject MAMBA_ROOT_PREFIX so micromamba finds envs.
+        const mmEnv = { ...env };
+        if (install.mambaRootPrefix)
+            mmEnv.MAMBA_ROOT_PREFIX = install.mambaRootPrefix;
+        return {
+            command: install.micromambaExe,
+            args: ['run', '-n', install.envName ?? 'zephyr', 'west', ...westArgs],
+            options: { ...optsWithoutShell, env: mmEnv },
+            install,
+        };
+    }
     if (install.mode === 'launcher' && install.westExecutable) {
         return {
             command: install.westExecutable,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typecad/framework-zephyr",
-  "version": "1.0.0-alpha.10",
+  "version": "1.0.0-alpha.11",
   "description": "TypeCAD framework package for the Zephyr RTOS — west/CMake build, devicetree-driven GPIO",
   "type": "module",
   "main": "./dist/index.js",
@@ -38,11 +38,11 @@
     "test:hw:mqtt": "cd ../../tests/hardware && npm exec -- cuttlefish-test mqtt-client.test.ts"
   },
   "dependencies": {
-    "@typecad/cuttlefish": "1.0.0-alpha.10"
+    "@typecad/cuttlefish": "1.0.0-alpha.11"
   },
   "devDependencies": {
-    "@typecad/expect": "1.0.0-alpha.10",
-    "@typecad/board-xiao-nrf52840": "1.0.0-alpha.10",
+    "@typecad/expect": "1.0.0-alpha.11",
+    "@typecad/board-xiao-nrf52840": "1.0.0-alpha.11",
     "typescript": "^5.7.3"
   },
   "license": "MIT",

package/src/chips/esp32.ts

@@ -59,4 +59,16 @@ export const ESP32_DEVKITC: ZephyrChipDescriptor = {
   // the ESP32 is AMP (dual-image procpu/appcpu), not SMP, by default — so the
   // dependency is satisfied. Omitted on radioless targets.
   wifi: { supported: true },
+  // DAC: the ESP32 has two 8-bit DAC channels on GPIO25 (channel 1) and GPIO26
+  // (channel 2). The Zephyr esp32 DAC driver (drivers/dac/dac_esp32.c) exposes
+  // them via the `dac0` node; the lowering emits dac_channel_setup +
+  // dac_write_value against DEVICE_DT_GET(DT_NODELABEL(dac0)). The overlay
+  // enables the node when the program uses dac.*. ESP32-S3 has no DAC.
+  dac: {
+    device: 'dac0',
+    channels: [
+      { pin: 25, channel: 1, resolution: 8 },
+      { pin: 26, channel: 2, resolution: 8 },
+    ],
+  },
 };

package/src/chips/types.ts

@@ -101,6 +101,19 @@ export interface ZephyrAdcChannel {
   readonly channel: number;
 }
 
+/**
+ * A DAC channel: which DAC output a given HAL pin maps to. The lowering emits
+ * `dac_channel_setup` + `dac_write_value` against the DAC device node.
+ */
+export interface ZephyrDacChannel {
+  /** GPIO number (matches the HAL op `pin` field). */
+  readonly pin: number;
+  /** DAC channel index (ESP32: GPIO25 → 1, GPIO26 → 2). */
+  readonly channel: number;
+  /** DAC resolution in bits (ESP32 DAC is 8-bit). */
+  readonly resolution: number;
+}
+
 /**
  * Pure-data descriptor for a Zephyr board + its SoC's peripheral layout.
  */
@@ -151,8 +164,24 @@ export interface ZephyrChipDescriptor {
     /** ADC resolution in bits. */
     readonly resolution: number;
   };
+  /**
+   * DAC: the DAC device node label + the pin→channel map. Present only on chips
+   * with a DAC (ESP32 has 2 channels on GPIO25/26; ESP32-S3 and nRF52840 have
+   * none). Read by profileDiagnostics to flag dac.* usage on chips without it.
+   */
+  readonly dac?: {
+    readonly device: string;
+    readonly channels: readonly ZephyrDacChannel[];
+  };
   /** Watchdog node label, e.g. 'wdt0'. */
   readonly wdt?: { readonly nodeLabel: string };
+  /**
+   * Hardware timers exposed as Zephyr counter devices. `instance` (the HAL
+   * hwtimer.* op's instance index) maps to `controllers[instance].nodeLabel`.
+   * Omit on chips whose counter nodes are kernel-owned or unavailable; the
+   * lowering then lowers to a comment and profileDiagnostics flags usage.
+   */
+  readonly hwtimer?: { readonly controllers: readonly ZephyrBusController[] };
   /**
    * 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.

package/src/chips/xiao-ble.ts

@@ -61,4 +61,10 @@ export const XIAO_BLE: ZephyrChipDescriptor = {
     ],
   },
   wdt: { nodeLabel: 'wdt0' },
+  // Hardware timer: nRF RTC1 is the free counter (RTC0 is kernel-owned by the
+  // softdevice/clock driver). The hwtimer lowering drives it as a Zephyr
+  // counter device (counter_start/stop + a top-value alarm for set_frequency).
+  // Verified against the nRF52840 SoC dtsi (rtc0/rtc1 nodes). The kernel uses
+  // RTC0 for the system tick; RTC1 is available for application use.
+  hwtimer: { controllers: [{ nodeLabel: 'rtc1' }] },
 };

package/src/display/gfx.ts

@@ -86,18 +86,23 @@ function fontTableCpp(): 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.
+ * Build the display runtime C++ for a profile.
+ *
+ * Two rendering models, selected by `profile.colorFormat`:
+ *  - `'rgb565'` (TFT): a one-row line buffer (no full framebuffer — see
+ *    AGENTS.md rendering guardrails); fill_rect/draw_rect/draw_text stream
+ *    each row via display_write.
+ *  - `'mono'` (OLED, e.g. SSD1306): a full framebuffer — the standard model
+ *    for page-buffered monochrome panels (the AGENTS.md "no full framebuffer"
+ *    guardrail targets RGB SPI TFTs, not mono OLEDs). draw ops set bits;
+ *    display_flush pushes the whole framebuffer. The MONO01 packing is
+ *    horizontal, MSB-first (Zephyr convention): byte = (y*rowBytes)+(x>>3),
+ *    bit = 0x80>>(x&7).
  */
 export function buildDisplayRuntime(profile: ZephyrDisplayProfile): DisplayRuntimeResult {
   const w = profile.width;
-  const stateLines: string[] = [
-    '// 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',
-  ];
+  const h = profile.height;
+  const isMono = profile.colorFormat === 'mono';
 
   // 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
@@ -107,7 +112,127 @@ export function buildDisplayRuntime(profile: ZephyrDisplayProfile): DisplayRunti
     ? `#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 = `
+  const stateLines = isMono
+    ? [
+        '// CUTTLEFISH_DISPLAY_BEGIN',
+        `static const struct device* __tc_display = DEVICE_DT_GET(DT_NODELABEL(${profile.dtLabel}));`,
+        `// Mono framebuffer (Zephyr MONO01: horizontal, MSB-first). ${(w + 7) >> 3} bytes/row x ${h} rows.`,
+        `static uint8_t __tc_display_fb[((${w} * ${h}) + 7) / 8];`,
+        '// CUTTLEFISH_DISPLAY_END',
+      ]
+    : [
+        '// 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',
+      ];
+
+  const helpers = isMono
+    ? monoHelpers(w, h, blInit)
+    : rgb565Helpers(w, blInit);
+
+  const fontTable = fontTableCpp();
+
+  return {
+    includes: ['<zephyr/drivers/display.h>'],
+    stateLines,
+    helpers,
+    fontTable,
+  };
+}
+
+/**
+ * Mono (OLED) helpers: a full framebuffer + bit-packing. SSD1306-class panels
+ * are page-buffered, so draw ops set bits in the framebuffer and display_flush
+ * pushes the whole buffer. color != 0 ⇒ lit.
+ */
+function monoHelpers(w: number, h: number, blInit: string): string {
+  const rowBytes = (w + 7) >> 3; // bytes per row (w is byte-aligned for 128-wide panels)
+  return `
+// MONO01 pixel packing: byte = (y * ${rowBytes}) + (x >> 3), bit = 0x80 >> (x & 7).
+static inline void __tc_set_pixel(uint16_t x, uint16_t y, uint8_t on) {
+    if ((x >= ${w}U) || (y >= ${h}U)) { return; }
+    uint16_t idx = static_cast<uint16_t>((static_cast<uint32_t>(y) * ${rowBytes}U) + (x >> 3));
+    uint8_t mask = static_cast<uint8_t>(0x80U >> (x & 7U));
+    if (on != 0U) {
+        __tc_display_fb[idx] = static_cast<uint8_t>(__tc_display_fb[idx] | mask);
+    } else {
+        __tc_display_fb[idx] = static_cast<uint8_t>(__tc_display_fb[idx] & static_cast<uint8_t>(~mask));
+    }
+}
+
+static inline void display_init(void) {
+    if (!device_is_ready(__tc_display)) { for (;;) { k_msleep(1000); } }
+${blInit}
+    for (uint16_t i = 0; i < static_cast<uint16_t>(sizeof(__tc_display_fb)); i++) { __tc_display_fb[i] = 0U; }
+    display_blanking_off(__tc_display);
+}
+
+static inline void display_fill_rect(uint16_t x, uint16_t y, uint16_t rw, uint16_t rh, uint16_t color) {
+    uint8_t on = (color != 0U) ? 1U : 0U;
+    for (uint16_t row = 0; row < rh; row++) {
+        for (uint16_t i = 0; i < rw; i++) {
+            __tc_set_pixel(static_cast<uint16_t>(x + i), static_cast<uint16_t>(y + row), on);
+        }
+    }
+}
+
+static inline void display_draw_rect(uint16_t x, uint16_t y, uint16_t rw, uint16_t rh, uint16_t color) {
+    uint8_t on = (color != 0U) ? 1U : 0U;
+    for (uint16_t i = 0; i < rw; i++) {
+        __tc_set_pixel(static_cast<uint16_t>(x + i), y, on);
+        __tc_set_pixel(static_cast<uint16_t>(x + i), static_cast<uint16_t>(y + rh - 1U), on);
+    }
+    for (uint16_t row = 1U; row < rh - 1U; row++) {
+        __tc_set_pixel(x, static_cast<uint16_t>(y + row), on);
+        __tc_set_pixel(static_cast<uint16_t>(x + rw - 1U), static_cast<uint16_t>(y + row), on);
+    }
+}
+
+static inline void display_draw_text(uint16_t x, uint16_t y, const char* text, uint16_t color) {
+    uint8_t on = (color != 0U) ? 1U : 0U;
+    uint16_t cx = x;
+    for (const char* p = text; *p != 0; p++) {
+        uint8_t uc = static_cast<uint8_t>(*p);
+        if (uc >= 128U) { uc = static_cast<uint8_t>(' '); }
+        const uint8_t* glyph = &__tc_font5x7[uc][0];
+        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++) {
+                if ((bits & static_cast<uint8_t>(1U << row)) != 0U) {
+                    __tc_set_pixel(static_cast<uint16_t>(cx + col), static_cast<uint16_t>(y + row), on);
+                }
+            }
+        }
+        cx = static_cast<uint16_t>(cx + 6U);
+    }
+}
+
+static inline void display_flush(void) {
+    struct display_buffer_descriptor __desc;
+    __desc.buf_size = sizeof(__tc_display_fb);   // ${rowBytes} * ${h} bytes
+    __desc.width = ${w}U;
+    __desc.height = ${h}U;
+    __desc.pitch = ${rowBytes}U;                  // bytes per row
+    __desc.frame_incomplete = false;
+    (void)display_write(__tc_display, 0, 0, &__desc, __tc_display_fb);
+}
+`;
+}
+
+/**
+ * RGB565 (TFT) helpers: a one-row line buffer; each op streams rows via
+ * display_write. No full framebuffer (AGENTS.md rendering guardrails).
+ */
+function rgb565Helpers(w: number, blInit: string): string {
+  return `
 // 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.
@@ -178,13 +303,4 @@ 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,
-  };
 }