@typecad/framework-zephyr 1.0.0-alpha.8

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

@@ -0,0 +1,40 @@
+/**
+ * A discovered, usable west installation. `mode` tells the caller how to
+ * invoke it: 'launcher' = call `westExecutable` directly; 'module' = call
+ * `pythonExecutable -m west`.
+ */
+export interface WestInstall {
+    mode: 'launcher' | 'module';
+    /** 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;
+    /** Which discovery strategy found this install. */
+    source: 'path' | 'zephyr-base-venv' | 'well-known' | 'system-python';
+}
+/** True if `dir` looks like a Zephyr SDK root: has CMakeLists.txt and the
+ *  kernel header. */
+export declare function isZephyrBase(dir: string): boolean;
+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;
+/** Candidate Zephyr workspace directories. Each may contain both `.venv/`
+ *  and `zephyr/` (the SDK). Exported for test injection. */
+export declare function wellKnownWorkspaces(): string[];
+export declare function discoverFromWellKnown(workspaces?: string[]): WestInstall | null;
+/** Candidate system Python interpreters to probe with `-m west`. */
+export declare function systemPythons(): string[];
+export declare function discoverFromSystemPython(pythons?: string[]): WestInstall | null;
+/** Clear the process-local discovery cache (for tests). */
+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.
+ * Returns null when no usable west install is found.
+ */
+export declare function discoverWest(): WestInstall | null;

package/dist/toolchain/west-discover.js

@@ -0,0 +1,203 @@
+// ---------------------------------------------------------------------------
+// west discovery — find a usable `west` (and the Zephyr SDK / ZEPHYR_BASE)
+//
+// west installs into a Python venv that must be activated before `west` is on
+// PATH. We resolve a working invocation WITHOUT requiring the user to have
+// activated the venv, by preferring the robust `<python> -m west` form: it
+// sidesteps shebang-launcher fragility on Windows and works with any venv
+// once we know which Python interpreter has west installed.
+//
+// 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/.
+//      venv, etc.
+//   4. 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 { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { spawnSync } from 'node:child_process';
+const IS_WIN = process.platform === 'win32';
+/** The Python executable name inside a venv's bin/ (POSIX) or Scripts/ (Win). */
+function venvPython(venvDir) {
+    return join(venvDir, IS_WIN ? 'Scripts' : 'bin', IS_WIN ? 'python.exe' : 'python');
+}
+/** True if `exe` runs `python -m west --version` successfully. */
+function pythonRunsWest(exe) {
+    try {
+        const r = spawnSync(exe, ['-m', 'west', '--version'], {
+            encoding: 'utf8',
+            timeout: 15_000,
+            windowsHide: true,
+        });
+        return r.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** True if `cmd` runs `west --version` successfully. */
+function westOnPath(cmd) {
+    try {
+        const r = spawnSync(cmd, ['--version'], {
+            encoding: 'utf8',
+            timeout: 15_000,
+            shell: IS_WIN,
+            windowsHide: true,
+        });
+        return r.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** True if `dir` looks like a Zephyr SDK root: has CMakeLists.txt and the
+ *  kernel header. */
+export function isZephyrBase(dir) {
+    if (!dir)
+        return false;
+    return (existsSync(join(dir, 'CMakeLists.txt')) &&
+        existsSync(join(dir, 'include', 'zephyr', 'kernel.h')));
+}
+// ── Strategy 1: `west` on PATH ──────────────────────────────────────────────
+export function discoverFromPath() {
+    const which = spawnSync(IS_WIN ? 'where' : 'which', ['west'], {
+        encoding: 'utf8',
+        shell: true,
+        windowsHide: true,
+    });
+    if (which.status !== 0)
+        return null;
+    const lines = (which.stdout ?? '').split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+    for (const line of lines) {
+        if (!existsSync(line))
+            continue;
+        if (!westOnPath(line))
+            continue;
+        return {
+            mode: 'launcher',
+            westExecutable: line,
+            zephyrBase: process.env.ZEPHYR_BASE || undefined,
+            source: 'path',
+        };
+    }
+    return null;
+}
+// ── Strategy 2: $ZEPHYR_BASE sibling venv ───────────────────────────────────
+/** The canonical Zephyr workspace layout puts the venv beside the SDK:
+ *  <workspace>/{.venv, zephyr}. So ${ZEPHYR_BASE}/../.venv is the venv. */
+export function discoverFromZephyrBase() {
+    const zb = process.env.ZEPHYR_BASE;
+    if (!zb || !isZephyrBase(zb))
+        return null;
+    const workspaceDir = dirname(zb);
+    const venvDir = join(workspaceDir, '.venv');
+    const py = venvPython(venvDir);
+    if (!existsSync(py) || !pythonRunsWest(py))
+        return null;
+    return {
+        mode: 'module',
+        pythonExecutable: py,
+        zephyrBase: zb,
+        source: 'zephyr-base-venv',
+    };
+}
+// ── Strategy 3: well-known workspace layouts ───────────────────────────────
+/** Candidate Zephyr workspace directories. Each may contain both `.venv/`
+ *  and `zephyr/` (the SDK). Exported for test injection. */
+export function wellKnownWorkspaces() {
+    const home = homedir();
+    if (IS_WIN) {
+        return [
+            join(home, 'zephyrproject'),
+            join(home, 'zephyr'),
+            'C:\\zephyrproject',
+            'C:\\zephyr',
+        ];
+    }
+    return [
+        join(home, 'zephyrproject'),
+        join(home, 'zephyr'),
+        '/opt/zephyrproject',
+        '/opt/zephyr',
+    ];
+}
+export function discoverFromWellKnown(workspaces = wellKnownWorkspaces()) {
+    for (const ws of workspaces) {
+        const venvDir = join(ws, '.venv');
+        const py = venvPython(venvDir);
+        if (!existsSync(py) || !pythonRunsWest(py))
+            continue;
+        // Resolve ZEPHYR_BASE if the SDK sits beside the venv.
+        const zb = join(ws, 'zephyr');
+        return {
+            mode: 'module',
+            pythonExecutable: py,
+            zephyrBase: isZephyrBase(zb) ? zb : undefined,
+            source: 'well-known',
+        };
+    }
+    return null;
+}
+// ── Strategy 4: system pythons via `-m west` ────────────────────────────────
+/** Candidate system Python interpreters to probe with `-m west`. */
+export function systemPythons() {
+    if (IS_WIN)
+        return ['py', 'python', 'python3'];
+    return ['python3', 'python'];
+}
+export function discoverFromSystemPython(pythons = systemPythons()) {
+    for (const py of pythons) {
+        if (!pythonRunsWest(py))
+            continue;
+        return {
+            mode: 'module',
+            pythonExecutable: py,
+            zephyrBase: process.env.ZEPHYR_BASE || undefined,
+            source: 'system-python',
+        };
+    }
+    return null;
+}
+// ── Top-level cascade ────────────────────────────────────────────────────────
+let cachedDiscover;
+/** Clear the process-local discovery cache (for tests). */
+export function resetWestDiscoveryCache() {
+    cachedDiscover = undefined;
+}
+/**
+ * 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.
+ * Returns null when no usable west install is found.
+ */
+export function discoverWest() {
+    if (cachedDiscover !== undefined)
+        return cachedDiscover;
+    const strategies = [
+        discoverFromPath,
+        discoverFromZephyrBase,
+        discoverFromWellKnown,
+        discoverFromSystemPython,
+    ];
+    for (const strat of strategies) {
+        let install = null;
+        try {
+            install = strat();
+        }
+        catch {
+            install = null;
+        }
+        if (install) {
+            cachedDiscover = install;
+            return install;
+        }
+    }
+    cachedDiscover = null;
+    return null;
+}

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

@@ -0,0 +1,39 @@
+import type { SpawnSyncOptions } from 'node:child_process';
+import { type WestInstall } from './west-discover.js';
+export interface WestInvocation {
+    /** The command to spawnSync: a `west` launcher or a Python interpreter. */
+    command: string;
+    /** Args for the command (includes `-m west` when in module mode). */
+    args: string[];
+    /** Base spawn options with cwd/timeout/encoding/stdio, plus the env carrying
+     *  ZEPHYR_BASE when discovered. */
+    options: SpawnSyncOptions;
+    /** The install the invocation was built from, for surfacing to the user. */
+    install: WestInstall;
+}
+/**
+ * The env to pass to the west spawn: the process env, with ZEPHYR_BASE injected
+ * when a SDK root was discovered, AND the venv's bin/Scripts dir prepended to
+ * PATH when west was found via a venv Python.
+ *
+ * The PATH prepend matters: `west flash` shells out to bare runner tools
+ * (`esptool`, `openocd`, `nrfjprog`, …) via check_call, so they resolve from
+ * PATH. Without the prepend, the user's PATH may surface a *different* tool
+ * ahead of the venv's — e.g. an older esptool whose argument spelling is
+ * incompatible with the runner. Putting the venv's bin first makes west's
+ * delegated subprocesses resolve to the same versions west itself runs under.
+ */
+export declare function buildEnv(install: WestInstall): NodeJS.ProcessEnv;
+/**
+ * Build a spawn invocation that runs `west <westArgs>`.
+ *
+ * `baseOptions` carries the cwd/timeout/stdio settings the caller wants;
+ * westSpawn preserves them and injects the discovery env. The returned object
+ * destructures directly into spawnSync:
+ *
+ *   const inv = westSpawn(['build', '-b', 'xiao_ble', projectRoot], { cwd, timeout });
+ *   spawnSync(inv.command, inv.args, inv.options);
+ *
+ * Throws a clear, actionable error when no usable west install is discovered.
+ */
+export declare function westSpawn(westArgs: string[], baseOptions: SpawnSyncOptions): WestInvocation;

package/dist/toolchain/west-spawn.js

@@ -0,0 +1,117 @@
+// ---------------------------------------------------------------------------
+// west spawn helper — build a spawnSync invocation for `west <args>`
+//
+// Mirrors framework-esp32's idfSpawn(): given the discovered WestInstall,
+// produce {command, args, env} that the toolchain destructures into spawnSync.
+//
+// Two modes:
+//   - 'launcher': spawn the `west` launcher directly (mode 'launcher').
+//   - 'module'  : spawn `<python> -m west ...` (mode 'module'). This is the
+//                 robust cross-platform form — it activates the venv's
+//                 interpreter for the one process without sourcing anything.
+//
+// ZEPHYR_BASE is injected into the spawn env when a SDK root was discovered
+// (find_package(Zephyr) needs it). west's prj.conf/CMakeLists are found via
+// the project dir regardless.
+// ---------------------------------------------------------------------------
+import { dirname } from 'node:path';
+import { discoverWest } from './west-discover.js';
+/**
+ * The Scripts/ (Windows) or bin/ (POSIX) directory of the venv the discovered
+ * west runs under. `pythonExecutable` lives in that directory, so it is its
+ * dirname. Returns undefined for launcher-mode installs where no venv is known.
+ */
+function venvBinDir(install) {
+    return install.pythonExecutable ? dirname(install.pythonExecutable) : undefined;
+}
+/**
+ * The env to pass to the west spawn: the process env, with ZEPHYR_BASE injected
+ * when a SDK root was discovered, AND the venv's bin/Scripts dir prepended to
+ * PATH when west was found via a venv Python.
+ *
+ * The PATH prepend matters: `west flash` shells out to bare runner tools
+ * (`esptool`, `openocd`, `nrfjprog`, …) via check_call, so they resolve from
+ * PATH. Without the prepend, the user's PATH may surface a *different* tool
+ * ahead of the venv's — e.g. an older esptool whose argument spelling is
+ * incompatible with the runner. Putting the venv's bin first makes west's
+ * delegated subprocesses resolve to the same versions west itself runs under.
+ */
+export function buildEnv(install) {
+    const env = { ...process.env };
+    if (install.zephyrBase && !env.ZEPHYR_BASE) {
+        env.ZEPHYR_BASE = install.zephyrBase;
+    }
+    const bin = venvBinDir(install);
+    if (bin) {
+        const sep = process.platform === 'win32' ? ';' : ':';
+        // On Windows the PATH environment variable may be cased as `Path` (the
+        // registry-native form, the only one populated when node is launched from
+        // PowerShell/cmd) or `PATH` (POSIX form, set by Git Bash). Writing only one
+        // casing can leave the other stale/empty, which under PowerShell would drop
+        // the user's real PATH (cmake, ninja, …) — breaking `west` configure. Read
+        // whichever casing is populated and write that same casing back, preserving
+        // the full existing value with the venv dir prepended.
+        const existing = env.Path ?? env.PATH ?? '';
+        const updated = bin + sep + existing;
+        if (env.Path !== undefined || (env.PATH === undefined && process.platform === 'win32')) {
+            env.Path = updated;
+        }
+        else {
+            env.PATH = updated;
+        }
+    }
+    return env;
+}
+/**
+ * Build a spawn invocation that runs `west <westArgs>`.
+ *
+ * `baseOptions` carries the cwd/timeout/stdio settings the caller wants;
+ * westSpawn preserves them and injects the discovery env. The returned object
+ * destructures directly into spawnSync:
+ *
+ *   const inv = westSpawn(['build', '-b', 'xiao_ble', projectRoot], { cwd, timeout });
+ *   spawnSync(inv.command, inv.args, inv.options);
+ *
+ * Throws a clear, actionable error when no usable west install is discovered.
+ */
+export function westSpawn(westArgs, baseOptions) {
+    const install = discoverWest();
+    if (!install) {
+        throw new Error([
+            'west (the Zephyr build tool) was not found.',
+            '',
+            'cuttlefish looked for it on PATH, in $ZEPHYR_BASE/.venv, in common',
+            'Zephyr workspace dirs (~/zephyrproject/.venv), and as a system',
+            "Python module (`python -m west`). To fix:",
+            '',
+            '  • Run the typeCAD Zephyr installer (one command, any OS — needs Node ≥18):',
+            '      node packages/zephyr-installer/install.mjs',
+            '    then `micromamba activate zephyr` and retry.',
+            '  • Or activate an existing Zephyr venv in this shell, or',
+            '  • Or set ZEPHYR_BASE to your Zephyr SDK root (the venv at $ZEPHYR_BASE/../.venv is then used), or',
+            '  • Or install west into a discoverable Python: pip install west',
+            '',
+            'See https://docs.zephyrproject.org/latest/develop/getting_started/index.html',
+        ].join('\n'));
+    }
+    const env = buildEnv(install);
+    // 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 === 'launcher' && install.westExecutable) {
+        return {
+            command: install.westExecutable,
+            args: westArgs,
+            options: { ...optsWithoutShell, env },
+            install,
+        };
+    }
+    // module mode: <python> -m west <args>
+    const py = install.pythonExecutable;
+    return {
+        command: py,
+        args: ['-m', 'west', ...westArgs],
+        options: { ...optsWithoutShell, env },
+        install,
+    };
+}

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@typecad/framework-zephyr",
+  "version": "1.0.0-alpha.8",
+  "description": "TypeCAD framework package for the Zephyr RTOS — west/CMake build, devicetree-driven GPIO",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./display": {
+      "types": "./dist/display/index.d.ts",
+      "default": "./dist/display/index.js"
+    },
+    "./framework.manifest": {
+      "types": "./dist/framework.manifest.d.ts",
+      "default": "./dist/framework.manifest.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run --root ../.. tests/packages/framework-zephyr/manifest.test.ts",
+    "test:coverage": "npm test && tsx ../../scripts/render-framework-coverage.ts",
+    "test:hw": "npm exec -- cuttlefish-test",
+    "test:hw:basics": "npm exec -- cuttlefish-test tests/01-basics.test.ts",
+    "test:hw:gpio": "npm exec -- cuttlefish-test tests/40-gpio.test.ts",
+    "test:hw:timers": "npm exec -- cuttlefish-test tests/42-timers.test.ts",
+    "test:http": "tsx ../../tests/hardware/start-server.ts",
+    "test:hw:http": "cd ../../tests/hardware && npm exec -- cuttlefish-test http-client.test.ts",
+    "test:mqtt": "tsx ../../tests/hardware/start-server.ts",
+    "test:hw:mqtt": "cd ../../tests/hardware && npm exec -- cuttlefish-test mqtt-client.test.ts"
+  },
+  "dependencies": {
+    "@typecad/cuttlefish": "1.0.0-alpha.8"
+  },
+  "devDependencies": {
+    "@typecad/expect": "1.0.0-alpha.8",
+    "@typecad/board-xiao-nrf52840": "1.0.0-alpha.8",
+    "typescript": "^5.7.3"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/justind000/typecode.git",
+    "directory": "packages/framework-zephyr"
+  },
+  "homepage": "https://github.com/justind000/typecode/tree/main/packages/framework-zephyr",
+  "bugs": {
+    "url": "https://github.com/justind000/typecode/issues"
+  },
+  "keywords": [
+    "ble",
+    "cpp",
+    "cuttlefish",
+    "embedded",
+    "firmware",
+    "framework",
+    "gpio",
+    "microcontroller",
+    "nordic",
+    "nrf52840",
+    "rtos",
+    "typecad",
+    "typescript",
+    "zephyr"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "typecad0",
+  "sideEffects": false
+}

package/src/async/timer-polyfill.ts

@@ -0,0 +1,107 @@
+// ---------------------------------------------------------------------------
+// Timer methods polyfill — Zephyr k_timer + k_work (heap-free)
+//
+// setInterval / setTimeout / clearInterval / clearTimeout backed by a fixed
+// pool of k_timer + k_work pairs. The timer's expiry function (ISR context)
+// submits a k_work item to the system workqueue; the work handler runs the
+// user callback in thread context. This split keeps the ISR cheap and lets the
+// callback run on a real thread (so it can do real work — but must not block,
+// since the system workqueue is shared).
+//
+// EMIT BOUNDARY: emitted bytes land in user firmware. Covered by the TypeCAD
+// Runtime Exception (RUNTIME_EXCEPTION.md at the repo root).
+// ---------------------------------------------------------------------------
+
+import type { RuntimePolyfillIR } from '@typecad/cuttlefish/api/shared';
+
+const MIN_TIMERS = 1;
+const MAX_TIMERS_CAP = 16;
+
+export interface TimerPolyfillIR extends RuntimePolyfillIR {
+  /** The clamped pool size the C++ was generated with. */
+  maxTimers: number;
+}
+
+/**
+ * Build the timer_methods polyfill IR. `requestedTimers` is sized from
+ * ctx.analysis.timerCallCount; it is clamped to [1, 16].
+ */
+export function buildTimerPolyfill(requestedTimers: number): TimerPolyfillIR {
+  const maxTimers = Math.min(MAX_TIMERS_CAP, Math.max(MIN_TIMERS, requestedTimers));
+
+  const helperStructs = [`
+// cuttlefish timer runtime — k_timer + k_work pool (heap-free).
+struct __tc_TimerSlot {
+    struct k_timer timer;
+    struct k_work work;
+    void (*callback)(void);
+    bool active;
+};
+
+static struct __tc_TimerSlot __tc_timer_slots[${maxTimers}];
+
+static void __tc_timer_work_handler(struct k_work* w) {
+    // Runs on the system workqueue thread (NOT ISR). Find the owning slot by
+    // address and invoke the callback. Must not block.
+    for (int32_t i = 0; i < ${maxTimers}; i++) {
+        if (&__tc_timer_slots[i].work == w) {
+            if (__tc_timer_slots[i].callback != nullptr) { __tc_timer_slots[i].callback(); }
+            return;
+        }
+    }
+}
+
+static void __tc_timer_expiry_fn(struct k_timer* t) {
+    // ISR context: submit the work item, do NOT run the callback here.
+    for (int32_t i = 0; i < ${maxTimers}; i++) {
+        if (&__tc_timer_slots[i].timer == t) {
+            (void)k_work_submit(&__tc_timer_slots[i].work);
+            return;
+        }
+    }
+}
+
+static int32_t __tc_timer_add(void (*cb)(void), int32_t ms, bool repeat) {
+    for (int32_t i = 0; i < ${maxTimers}; i++) {
+        if (!__tc_timer_slots[i].active) {
+            __tc_timer_slots[i].callback = cb;
+            __tc_timer_slots[i].active = true;
+            k_timer_init(&__tc_timer_slots[i].timer, __tc_timer_expiry_fn, nullptr);
+            k_work_init(&__tc_timer_slots[i].work, __tc_timer_work_handler);
+            k_timer_start(&__tc_timer_slots[i].timer, K_MSEC(ms), repeat ? K_MSEC(ms) : K_FOREVER);
+            return i + 1;  // 1-based id (Arduino parity)
+        }
+    }
+    return 0;  // pool full
+}
+
+static void __tc_timer_clear(int32_t id) {
+    if (id > 0 && id <= ${maxTimers}) {
+        int32_t i = id - 1;
+        k_timer_stop(&__tc_timer_slots[i].timer);
+        __tc_timer_slots[i].active = false;
+        __tc_timer_slots[i].callback = nullptr;
+    }
+}
+`];
+
+  const helperFunctions = [`
+int32_t __tc_setInterval(void (*cb)(), int32_t ms) { return __tc_timer_add(cb, ms, true); }
+int32_t __tc_setTimeout(void (*cb)(), int32_t ms) { return __tc_timer_add(cb, ms, false); }
+void __tc_clearInterval(int32_t id) { __tc_timer_clear(id); }
+void __tc_clearTimeout(int32_t id) { __tc_timer_clear(id); }
+`];
+
+  return {
+    kind: 'polyfill',
+    id: 'timer_methods',
+    domain: 'embedded',
+    requiredIncludes: [],
+    forwardDeclarations: [],
+    helperStructs,
+    helperFunctions,
+    shimMacros: [],
+    dependencies: [],
+    maxTimers,
+  };
+}

package/src/chips/controllers.ts

@@ -0,0 +1,74 @@
+// ---------------------------------------------------------------------------
+// GPIO controller resolution — pin → devicetree nodelabel
+//
+// Most SoCs expose a single GPIO controller, so a HAL pin maps to
+// `chip.gpioController` unconditionally. SoCs that split GPIO across multiple
+// devicetree nodes (ESP32-S3: `gpio0` 0–31, `gpio1` 32–48) list a range per
+// controller in `chip.gpioControllers`. These helpers route a HAL pin to the
+// owning controller.
+//
+// Two forms:
+//   - controllerNodelabelForPin(): used by the compile-time lowering paths
+//     (gpio/pulse/spi raw writes), where the pin number is a literal known at
+//     transpile time. Resolves to a single nodelabel so the emitted
+//     `DT_NODELABEL(<nodelabel>)` macro is statically valid.
+//   - emitGpioDevDispatcher(): used by paths that take a RUNTIME pin (the
+//     @typecad/safety __tc_gpio_read/__tc_gpio_write shims). Emits a tiny
+//     `__tc_gpio_dev(uint32_t pin)` that returns the owning `const struct
+//     device*`, so a single shim body handles any pin. Single-controller SoCs
+//     collapse to a one-liner.
+// ---------------------------------------------------------------------------
+
+import type { ZephyrChipDescriptor } from './types.js';
+
+/**
+ * Resolve the devicetree nodelabel of the GPIO controller that owns `pin`.
+ *
+ * For single-controller SoCs (no `gpioControllers`) this is always
+ * `chip.gpioController`. For multi-controller SoCs it finds the entry whose
+ * [minPin, maxPin] range contains `pin`, falling back to `chip.gpioController`
+ * for out-of-range pins (e.g. the manifest probe's synthetic pin 0).
+ */
+export function controllerNodelabelForPin(chip: ZephyrChipDescriptor, pin: number): string {
+  const ranges = chip.gpioControllers;
+  if (ranges && ranges.length > 0) {
+    const hit = ranges.find((r) => pin >= r.minPin && pin <= r.maxPin);
+    if (hit) return hit.nodelabel;
+  }
+  return chip.gpioController;
+}
+
+/**
+ * Emit the C++ source for a runtime pin → GPIO-device dispatcher.
+ *
+ * Returns lines defining `static inline const struct device* __tc_gpio_dev(uint32_t pin)`.
+ * Each branch resolves its controller via `DEVICE_DT_GET(DT_NODELABEL(...))` at
+ * compile time (the macro is evaluated per branch, so it is always statically
+ * valid); only `pin` is runtime. For a single-controller SoC this collapses to
+ * a one-liner returning that controller, so the existing XIAO nRF52840 behavior
+ * is byte-for-byte unchanged.
+ */
+export function emitGpioDevDispatcher(chip: ZephyrChipDescriptor): string[] {
+  const ranges = chip.gpioControllers;
+  if (!ranges || ranges.length === 0) {
+    return [
+      'static inline const struct device* __tc_gpio_dev(uint32_t pin) {',
+      `    (void)pin;`,
+      `    return DEVICE_DT_GET(DT_NODELABEL(${chip.gpioController}));`,
+      '}',
+    ];
+  }
+  const lines: string[] = [
+    'static inline const struct device* __tc_gpio_dev(uint32_t pin) {',
+  ];
+  for (const r of ranges) {
+    lines.push(
+      `    if (pin >= ${r.minPin} && pin <= ${r.maxPin}) { return DEVICE_DT_GET(DT_NODELABEL(${r.nodelabel})); }`,
+    );
+  }
+  lines.push(
+    `    return DEVICE_DT_GET(DT_NODELABEL(${chip.gpioController}));`,
+    '}',
+  );
+  return lines;
+}