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

package/dist/lowering/preferences.js

@@ -29,6 +29,9 @@
 // Runtime Exception (RUNTIME_EXCEPTION.md at the repo root).
 // ---------------------------------------------------------------------------
 /** Render a HAL field: pass through (already rendered by the resolver). */
+function unq(v) {
+    return String(v).replace(/^"|"$/g, '');
+}
 function s(v) {
     return String(v);
 }
@@ -73,10 +76,7 @@ export function preferencesInitLines() {
         `    bool used;`,
         `};`,
         ``,
-        `// Active namespace prefix ("tc/<ns>/"). begin() overwrites it; end() clears.`,
-        `// prefs_ns is deliberately sized to hold "tc/" + a 16-char ns + "/" + NUL.`,
         `static struct {`,
-        `    char ns[24];`,
         `    bool loaded;`,
         `    __tc_prefs_slot slots[__TC_PREFS_SLOT_COUNT];`,
         `} __tc_prefs;`,
@@ -96,15 +96,18 @@ export function preferencesInitLines() {
         `            __tc_prefs.slots[i].len = static_cast<uint8_t>(got);`,
         `            // Type is encoded as the first byte of the stored value (see put_*).`,
         `            __tc_prefs.slots[i].type = __tc_prefs.slots[i].val[0];`,
-        `            (void)snprintf(__tc_prefs.slots[i].key, __TC_PREFS_KEY_LEN, "%s", name);`,
+        `            // h_set hands us the name RELATIVE to the handler's "tc"`,
+        `            // subtree ("rig/marker") — the cache keys full names, so`,
+        `            // re-attach the prefix or loaded entries never match a lookup.`,
+        `            (void)snprintf(__tc_prefs.slots[i].key, __TC_PREFS_KEY_LEN, "tc/%s", name);`,
         `            __tc_prefs.slots[i].used = true;`,
         `            return 0;`,
         `        }`,
         `    }`,
         `    return 0;  // cache full — silently drop (matches ESP32 NVS-full behavior)`,
         `}`,
-        `static int __tc_prefs_h_get(const char* key, char* val, int val_len_max) {`,
-        `    (void)key; (void)val; (void)val_len_max;`,
+        `static int __tc_prefs_h_get(const char* full, char* val, int val_len_max) {`,
+        `    (void)full; (void)val; (void)val_len_max;`,
         `    return -ENOENT;`,
         `}`,
         `static int __tc_prefs_h_commit(void) { return 0; }`,
@@ -122,12 +125,6 @@ export function preferencesInitLines() {
         `    }`,
         `}`,
         ``,
-        `// Build the full settings name "tc/<ns>/<key>" into out. ns is the active`,
-        `// prefix set by begin(); the slot's key[] stores this full path so remove()`,
-        `// and clear() can settings_delete the exact stored name.`,
-        `static void __tc_prefs_full(char* out, size_t outsz, const char* key) {`,
-        `    (void)snprintf(out, outsz, "%s%s", __tc_prefs.ns, key);`,
-        `}`,
         ``,
         `// Slot lookup by full settings name. Returns nullptr when absent (the get_*`,
         `// helpers then fall back to the caller's default value, matching the ESP32`,
@@ -159,9 +156,8 @@ export function preferencesInitLines() {
         `// as val[0] so h_set can recover it on the next boot without a separate`,
         `// name→type map.`,
         `template <typename T>`,
-        `static inline void __tc_prefs_put(const char* key, uint8_t tag, const T& value) {`,
-        `    char full[__TC_PREFS_KEY_LEN];`,
-        `    __tc_prefs_full(full, sizeof(full), key);`,
+        `static inline void __tc_prefs_put(const char* full, uint8_t tag, const T& value) {`,
+        `    __tc_prefs_ensure_loaded();   // begin() is gone — mount lazily here`,
         `    uint8_t buf[1U + sizeof(T)];`,
         `    buf[0] = tag;`,
         `    (void)memcpy(&buf[1], &value, sizeof(T));`,
@@ -177,9 +173,8 @@ export function preferencesInitLines() {
         `}`,
         ``,
         `template <typename T>`,
-        `static inline T __tc_prefs_get(const char* key, uint8_t tag, T def) {`,
-        `    char full[__TC_PREFS_KEY_LEN];`,
-        `    __tc_prefs_full(full, sizeof(full), key);`,
+        `static inline T __tc_prefs_get(const char* full, uint8_t tag, T def) {`,
+        `    __tc_prefs_ensure_loaded();`,
         `    __tc_prefs_slot* slot = __tc_prefs_find(full);`,
         `    if (slot == nullptr || slot->type != tag || slot->len < (1U + sizeof(T))) {`,
         `        return def;`,
@@ -192,23 +187,12 @@ export function preferencesInitLines() {
         `// ── Lifecycle (session model on top of the flat key-space) ──────────────`,
         `// begin records "tc/<ns>/" as the prefix every subsequent key is built under.`,
         `// end clears the prefix (NOT the cache). Both are cheap on Zephyr: the real`,
-        `// work is in settings_load() at boot. They exist for portability with the`,
-        `// ESP32 NVS session model and so a future session-needing backend has a hook.`,
-        `static inline void __tc_prefs_begin(const char* ns, bool readOnly) {`,
-        `    (void)readOnly;`,
-        `    __tc_prefs_ensure_loaded();`,
-        `    (void)snprintf(__tc_prefs.ns, sizeof(__tc_prefs.ns), "tc/%s/", ns);`,
-        `}`,
-        `static inline void __tc_prefs_end(void) {`,
-        `    __tc_prefs.ns[0] = '\\0';`,
-        `}`,
         ``,
         `// remove: drop one key from flash and the cache. Falls back to no-op if the`,
         `// slot isn't cached (settings_delete on a missing key returns -ENOENT, which`,
         `// we swallow).`,
-        `static inline void __tc_prefs_remove(const char* key) {`,
-        `    char full[__TC_PREFS_KEY_LEN];`,
-        `    __tc_prefs_full(full, sizeof(full), key);`,
+        `static inline void __tc_prefs_remove(const char* full) {`,
+        `    __tc_prefs_ensure_loaded();`,
         `    (void)settings_delete(full);`,
         `    __tc_prefs_slot* slot = __tc_prefs_find(full);`,
         `    if (slot != nullptr) { slot->used = false; }`,
@@ -218,11 +202,12 @@ export function preferencesInitLines() {
         `// authoritative list of keys we have written) and settings_delete each whose`,
         `// full name starts with the active ns prefix, then mark the slot free. Only`,
         `// the active namespace is cleared — keys under other namespaces survive.`,
-        `static inline void __tc_prefs_clear(void) {`,
-        `    const size_t plen = strlen(__tc_prefs.ns);`,
+        `static inline void __tc_prefs_clear(const char* prefix) {`,
+        `    __tc_prefs_ensure_loaded();`,
+        `    const size_t plen = strlen(prefix);`,
         `    for (int i = 0; i < __TC_PREFS_SLOT_COUNT; i++) {`,
         `        if (__tc_prefs.slots[i].used &&`,
-        `            strncmp(__tc_prefs.slots[i].key, __tc_prefs.ns, plen) == 0) {`,
+        `            strncmp(__tc_prefs.slots[i].key, prefix, plen) == 0) {`,
         `            (void)settings_delete(__tc_prefs.slots[i].key);`,
         `            __tc_prefs.slots[i].used = false;`,
         `        }`,
@@ -232,39 +217,38 @@ export function preferencesInitLines() {
         `// ── Typed accessors ─────────────────────────────────────────────────────`,
         `// Each put_* stamps its tag byte and persists; each get_* reads the cache and`,
         `// returns the default on miss/type-mismatch (mirrors ESP32 Preferences).`,
-        `static inline void __tc_prefs_put_int(const char* key, int32_t v) {`,
-        `    __tc_prefs_put<int32_t>(key, ${TAG.INT}, v);`,
+        `static inline void __tc_prefs_put_int(const char* full, int32_t v) {`,
+        `    __tc_prefs_put<int32_t>(full, ${TAG.INT}, v);`,
         `}`,
-        `static inline int32_t __tc_prefs_get_int(const char* key, int32_t def) {`,
-        `    return __tc_prefs_get<int32_t>(key, ${TAG.INT}, def);`,
+        `static inline int32_t __tc_prefs_get_int(const char* full, int32_t def) {`,
+        `    return __tc_prefs_get<int32_t>(full, ${TAG.INT}, def);`,
         `}`,
-        `static inline void __tc_prefs_put_uint(const char* key, uint32_t v) {`,
-        `    __tc_prefs_put<uint32_t>(key, ${TAG.UINT}, v);`,
+        `static inline void __tc_prefs_put_uint(const char* full, uint32_t v) {`,
+        `    __tc_prefs_put<uint32_t>(full, ${TAG.UINT}, v);`,
         `}`,
-        `static inline uint32_t __tc_prefs_get_uint(const char* key, uint32_t def) {`,
-        `    return __tc_prefs_get<uint32_t>(key, ${TAG.UINT}, def);`,
+        `static inline uint32_t __tc_prefs_get_uint(const char* full, uint32_t def) {`,
+        `    return __tc_prefs_get<uint32_t>(full, ${TAG.UINT}, def);`,
         `}`,
-        `static inline void __tc_prefs_put_bool(const char* key, bool v) {`,
+        `static inline void __tc_prefs_put_bool(const char* full, bool v) {`,
         `    uint8_t b = v ? 1U : 0U;`,
-        `    __tc_prefs_put<uint8_t>(key, ${TAG.BOOL}, b);`,
+        `    __tc_prefs_put<uint8_t>(full, ${TAG.BOOL}, b);`,
         `}`,
-        `static inline bool __tc_prefs_get_bool(const char* key, bool def) {`,
-        `    uint8_t b = __tc_prefs_get<uint8_t>(key, ${TAG.BOOL}, def ? 1U : 0U);`,
+        `static inline bool __tc_prefs_get_bool(const char* full, bool def) {`,
+        `    uint8_t b = __tc_prefs_get<uint8_t>(full, ${TAG.BOOL}, def ? 1U : 0U);`,
         `    return b != 0U;`,
         `}`,
-        `static inline void __tc_prefs_put_float(const char* key, float v) {`,
-        `    __tc_prefs_put<float>(key, ${TAG.FLOAT}, v);`,
+        `static inline void __tc_prefs_put_float(const char* full, float v) {`,
+        `    __tc_prefs_put<float>(full, ${TAG.FLOAT}, v);`,
         `}`,
-        `static inline float __tc_prefs_get_float(const char* key, float def) {`,
-        `    return __tc_prefs_get<float>(key, ${TAG.FLOAT}, def);`,
+        `static inline float __tc_prefs_get_float(const char* full, float def) {`,
+        `    return __tc_prefs_get<float>(full, ${TAG.FLOAT}, def);`,
         `}`,
         ``,
         `// Strings are length-prefixed into the value buffer (capped at STR_LEN so the`,
         `// whole slot still fits in __TC_PREFS_VAL_LEN). get copies out with a NUL and`,
         `// returns def when the slot is absent or the wrong type.`,
-        `static inline void __tc_prefs_put_string(const char* key, const char* v) {`,
-        `    char full[__TC_PREFS_KEY_LEN];`,
-        `    __tc_prefs_full(full, sizeof(full), key);`,
+        `static inline void __tc_prefs_put_string(const char* full, const char* v) {`,
+        `    __tc_prefs_ensure_loaded();`,
         `    uint8_t buf[1U + __TC_PREFS_STR_LEN];`,
         `    buf[0] = ${TAG.STRING};`,
         `    size_t n = strlen(v);`,
@@ -280,10 +264,9 @@ export function preferencesInitLines() {
         `        slot->used = true;`,
         `    }`,
         `}`,
-        `static inline const char* __tc_prefs_get_string(const char* key, const char* def) {`,
+        `static inline const char* __tc_prefs_get_string(const char* full, const char* def) {`,
+        `    __tc_prefs_ensure_loaded();`,
         `    static char out[__TC_PREFS_STR_LEN + 1U];`,
-        `    char full[__TC_PREFS_KEY_LEN];`,
-        `    __tc_prefs_full(full, sizeof(full), key);`,
         `    __tc_prefs_slot* slot = __tc_prefs_find(full);`,
         `    if (slot == nullptr || slot->type != ${TAG.STRING} || slot->len < 1U) {`,
         `        return def;`,
@@ -307,37 +290,26 @@ export function preferencesInitLines() {
 export function lowerPreferences(op) {
     const o = op;
     switch (op.operation) {
-        case 'preferences.begin':
-            // readOnly is honored as a no-op: Zephyr settings has no read-only mount,
-            // and silently ignoring it matches the ESP32 Preferences behavior when
-            // an RO handle is written (the put returns an error the app doesn't see).
-            return { code: `__tc_prefs_begin(${s(o.namespace)}, ${o.readOnly ? 'true' : 'false'});` };
-        case 'preferences.end':
-            return { code: `__tc_prefs_end();` };
         case 'preferences.clear':
-            return { code: `__tc_prefs_clear();` };
+            return { code: `__tc_prefs_clear("tc/${unq(o.ns)}/");` };
         case 'preferences.remove':
-            return { code: `__tc_prefs_remove(${s(o.key)});` };
+            return { code: `__tc_prefs_remove("tc/${unq(o.ns)}/${unq(o.key)}");` };
         case 'preferences.put_int':
-            return { code: `__tc_prefs_put_int(${s(o.key)}, ${s(o.value)});` };
+            return { code: `__tc_prefs_put_int("tc/${unq(o.ns)}/${unq(o.key)}", ${s(o.value)});` };
         case 'preferences.get_int':
-            return { expression: `__tc_prefs_get_int(${s(o.key)}, ${s(o.defaultValue)})` };
-        case 'preferences.put_uint':
-            return { code: `__tc_prefs_put_uint(${s(o.key)}, ${s(o.value)});` };
-        case 'preferences.get_uint':
-            return { expression: `__tc_prefs_get_uint(${s(o.key)}, ${s(o.defaultValue)})` };
+            return { expression: `__tc_prefs_get_int("tc/${unq(o.ns)}/${unq(o.key)}", ${s(o.defaultValue)})` };
         case 'preferences.put_bool':
-            return { code: `__tc_prefs_put_bool(${s(o.key)}, ${o.value ? 'true' : 'false'});` };
+            return { code: `__tc_prefs_put_bool("tc/${unq(o.ns)}/${unq(o.key)}", ${o.value ? 'true' : 'false'});` };
         case 'preferences.get_bool':
-            return { expression: `__tc_prefs_get_bool(${s(o.key)}, ${o.defaultValue ? 'true' : 'false'})` };
+            return { expression: `__tc_prefs_get_bool("tc/${unq(o.ns)}/${unq(o.key)}", ${o.defaultValue ? 'true' : 'false'})` };
         case 'preferences.put_float':
-            return { code: `__tc_prefs_put_float(${s(o.key)}, ${s(o.value)});` };
+            return { code: `__tc_prefs_put_float("tc/${unq(o.ns)}/${unq(o.key)}", ${s(o.value)});` };
         case 'preferences.get_float':
-            return { expression: `__tc_prefs_get_float(${s(o.key)}, ${s(o.defaultValue)})` };
+            return { expression: `__tc_prefs_get_float("tc/${unq(o.ns)}/${unq(o.key)}", ${s(o.defaultValue)})` };
         case 'preferences.put_string':
-            return { code: `__tc_prefs_put_string(${s(o.key)}, ${s(o.value)});` };
+            return { code: `__tc_prefs_put_string("tc/${unq(o.ns)}/${unq(o.key)}", ${s(o.value)});` };
         case 'preferences.get_string':
-            return { expression: `__tc_prefs_get_string(${s(o.key)}, ${s(o.defaultValue)})` };
+            return { expression: `__tc_prefs_get_string("tc/${unq(o.ns)}/${unq(o.key)}", ${s(o.defaultValue)})` };
         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/pulse.js

@@ -44,37 +44,6 @@ export function lowerPulseOrShift(op, chip) {
                 expression: `({ int64_t __max = static_cast<int64_t>(${timeout} / 1000); int64_t __t0 = k_uptime_get(); bool __ok = true; while (gpio_pin_get_raw(${dev}, ${pin}) != ${want}) { if ((k_uptime_get() - __t0) > __max) { __ok = false; break; } } int32_t __ret = 0; if (__ok) { int64_t __start = k_uptime_get(); while (gpio_pin_get_raw(${dev}, ${pin}) == ${want}) { } __ret = static_cast<int32_t>((k_uptime_get() - __start) * 1000); } __ret; })`,
             };
         }
-        case 'shift.out': {
-            // Bit-bang `value` (MSB or LSB first) via dataPin + clockPin. The two
-            // pins may sit on different GPIO controllers on multi-controller SoCs
-            // (ESP32-S3), so each is resolved to its own owning controller.
-            const dataPin = o.dataPin;
-            const clockPin = o.clockPin;
-            const dataDev = devForPin(chip, dataPin);
-            const clockDev = devForPin(chip, clockPin);
-            const msbFirst = o.bitOrder === 'msb';
-            const init = msbFirst ? '7' : '0';
-            const test = msbFirst ? '(__i >= 0)' : '(__i < 8)';
-            const step = msbFirst ? '__i--' : '__i++';
-            return {
-                code: `for (int __i = ${init}; ${test}; ${step}) { gpio_pin_set_raw(${dataDev}, ${controllerRawPinForPin(chip, dataPin)}, (${o.value} >> __i) & 1); gpio_pin_set_raw(${clockDev}, ${controllerRawPinForPin(chip, clockPin)}, 1); k_busy_wait(1); gpio_pin_set_raw(${clockDev}, ${controllerRawPinForPin(chip, clockPin)}, 0); }`,
-            };
-        }
-        case 'shift.in': {
-            // Read 8 bits (MSB or LSB first) from dataPin, clocking on clockPin.
-            const dataPin = o.dataPin;
-            const clockPin = o.clockPin;
-            const dataDev = devForPin(chip, dataPin);
-            const clockDev = devForPin(chip, clockPin);
-            const msbFirst = o.bitOrder === 'msb';
-            const init = msbFirst ? '7' : '0';
-            const test = msbFirst ? '(__i >= 0)' : '(__i < 8)';
-            const step = msbFirst ? '__i--' : '__i++';
-            const accum = msbFirst ? '__v = (__v << 1)' : '__v |= (bit << __i)';
-            return {
-                expression: `({ uint8_t __v = 0; for (int __i = ${init}; ${test}; ${step}) { gpio_pin_set_raw(${clockDev}, ${controllerRawPinForPin(chip, clockPin)}, 1); k_busy_wait(1); int bit = gpio_pin_get_raw(${dataDev}, ${controllerRawPinForPin(chip, dataPin)}); gpio_pin_set_raw(${clockDev}, ${controllerRawPinForPin(chip, clockPin)}, 0); ${accum}; } __v; })`,
-            };
-        }
         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.d.ts

@@ -14,6 +14,13 @@ export declare function pwmDtAlias(spec: ZephyrPwmSpec): string;
  * expression and fails to compile (caught by the blackpill E2E west build).
  */
 export declare function pwmDtAliasToken(spec: ZephyrPwmSpec): string;
+/**
+ * Look up a PWM spec by HAL pin number. Matrix pins (ESP32 LEDC) synthesize
+ * a spec on the fly: the channel is inert here — the emitted C++ addresses
+ * the pin only via its `tc-pwm<pin>` alias (the DT pwms cell carries the
+ * real channel, assigned by the overlay generator over the driven pins).
+ */
+export declare function findPwmSpec(chip: ZephyrChipDescriptor, pin: number): ZephyrPwmSpec | undefined;
 /**
  * Emit the per-channel PWM spec declarations. One per spec in the chip
  * descriptor that the PROGRAM ACTUALLY DRIVES (`usedPins`) — a spec for an
@@ -22,7 +29,11 @@ export declare function pwmDtAliasToken(spec: ZephyrPwmSpec): string;
  * program), every spec is emitted. Called from shimLines when the program
  * uses PWM.
  */
-export declare function pwmInitLines(chip: ZephyrChipDescriptor, usedPins?: ReadonlySet<number>): string[];
+export declare function pwmInitLines(chip: ZephyrChipDescriptor, usedPins?: ReadonlySet<number>, userSpecs?: readonly {
+    pin: number;
+    controller: string;
+    channel: number;
+}[]): string[];
 /**
  * Resolve a HAL pwm.* op to Zephyr C++.
  * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.

package/dist/lowering/pwm.js

@@ -24,9 +24,20 @@ export function pwmDtAlias(spec) {
 export function pwmDtAliasToken(spec) {
     return pwmDtAlias(spec).replace(/-/g, '_');
 }
-/** Look up a PWM spec by HAL pin number. */
-function findPwmSpec(chip, pin) {
-    return chip.pwm?.specs.find((s) => s.pin === pin);
+/**
+ * Look up a PWM spec by HAL pin number. Matrix pins (ESP32 LEDC) synthesize
+ * a spec on the fly: the channel is inert here — the emitted C++ addresses
+ * the pin only via its `tc-pwm<pin>` alias (the DT pwms cell carries the
+ * real channel, assigned by the overlay generator over the driven pins).
+ */
+export function findPwmSpec(chip, pin) {
+    const spec = chip.pwm?.specs.find((s) => s.pin === pin);
+    if (spec)
+        return spec;
+    const m = chip.pwm?.matrix;
+    if (m && m.pins.includes(pin))
+        return { pin, controller: m.controller, channel: 0 };
+    return undefined;
 }
 /** The C variable name emitted for a PWM channel's spec. */
 function pwmVarName(spec) {
@@ -40,13 +51,37 @@ function pwmVarName(spec) {
  * program), every spec is emitted. Called from shimLines when the program
  * uses PWM.
  */
-export function pwmInitLines(chip, usedPins) {
+export function pwmInitLines(chip, usedPins, userSpecs) {
     const lines = ['// CUTTLEFISH_PWM_BEGIN'];
     for (const spec of chip.pwm?.specs ?? []) {
         if (usedPins && !usedPins.has(spec.pin))
             continue;
         lines.push(`static const struct pwm_dt_spec ${pwmVarName(spec)} = PWM_DT_SPEC_GET(DT_ALIAS(${pwmDtAliasToken(spec)}));`);
     }
+    // Inline-override pins (the escape hatch): the construction opts vouch for
+    // controller+channel on a pin the manifest does not map — the alias var
+    // the lowered calls reference (the DT node itself comes from the overlay
+    // regen's marker merge).
+    for (const spec of userSpecs ?? []) {
+        if (chip.pwm?.specs.some((s) => s.pin === spec.pin))
+            continue;
+        if (usedPins && !usedPins.has(spec.pin))
+            continue;
+        lines.push(`static const struct pwm_dt_spec ${pwmVarName(spec)} = PWM_DT_SPEC_GET(DT_ALIAS(${pwmDtAliasToken(spec)}));`);
+    }
+    // Matrix pins (ESP32 LEDC): one alias per driven pin, ascending — the same
+    // order the overlay generator assigns channels in, though the C++ never
+    // needs the channel (the DT pwms cell carries it). An omitted usage set
+    // (probe paths) emits every matrix pin, mirroring the static behavior.
+    const m = chip.pwm?.matrix;
+    if (m) {
+        const pins = (usedPins ? [...usedPins].filter((p) => m.pins.includes(p)) : [...m.pins])
+            .sort((a, b) => a - b);
+        for (const pin of pins) {
+            const spec = { pin, controller: m.controller, channel: 0 };
+            lines.push(`static const struct pwm_dt_spec ${pwmVarName(spec)} = PWM_DT_SPEC_GET(DT_ALIAS(${pwmDtAliasToken(spec)}));`);
+        }
+    }
     lines.push('// CUTTLEFISH_PWM_END');
     return lines;
 }
@@ -56,7 +91,20 @@ export function pwmInitLines(chip, usedPins) {
  */
 export function lowerPwm(op, chip) {
     const o = op;
-    const spec = findPwmSpec(chip, o.pin);
+    // Construction-time controller/channel overrides (hal/pwm-pin.ts opts):
+    // the user vouches for the routing. The spec synthesizes from the
+    // override (addressing rides the tc-pwm<pin> alias like a matrix pin) and
+    // a marker comment carries controller+channel to the overlay regen, which
+    // synthesizes the DT node — the transpiler cannot.
+    const hasOverride = (typeof o.controllerOverride === 'string' && o.controllerOverride !== '')
+        || (typeof o.channelOverride === 'number' && o.channelOverride >= 0);
+    const spec = hasOverride
+        ? {
+            pin: o.pin,
+            controller: o.controllerOverride ?? 'pwm0',
+            channel: o.channelOverride ?? 0,
+        }
+        : findPwmSpec(chip, o.pin);
     if (!spec) {
         // Probe / unlisted pin: return a comment so the resolver reports non-
         // undefined (the manifest validator's probe sends pin:0 with no spec).
@@ -64,18 +112,34 @@ export function lowerPwm(op, chip) {
         return { code: `/* pwm on pin ${o.pin}: no PWM spec in chip descriptor */` };
     }
     const v = pwmVarName(spec);
+    // The overlay regen (toolchain) parses this into a synthesized pwm-leds
+    // spec: pin → controller/channel. Comment placement inside the block
+    // braces is legal C.
+    const marker = hasOverride
+        ? `/* cuttlefish-user-facts: pwm pin=${spec.pin} controller=${spec.controller} channel=${spec.channel} */ `
+        : '';
     switch (op.operation) {
-        case 'pwm.write': {
-            // Duty is 0–255 (Arduino analogWrite). Scale to ns against the period.
-            return { code: `pwm_set_pulse_dt(&${v}, (static_cast<uint32_t>(${o.duty}) * ${v}.period) / 255);` };
+        // ── Thin PWM (hal/pwm-pin.ts) — ns-true verbs ──────────────────────────
+        // Zephyr 4.4 has pwm_set_dt (period + pulse) and pwm_set_pulse_dt (pulse
+        // only) — no period-only setter. The construction period is established
+        // once via pwm_set_dt(period, pulse 0 = line idle), then every set is one
+        // pwm_set_pulse_dt. No 0–255 scaling anywhere.
+        case 'pwm.set_pulse': {
+            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}, ${o.pulseNs}); }`,
+            };
+        }
+        case 'pwm.set_duty': {
+            // duty is 0.0–1.0; pulse = duty × the construction period.
+            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}, static_cast<uint32_t>(static_cast<double>(${o.duty}) * static_cast<double>(${o.periodNs}))); }`,
+            };
         }
-        case 'pwm.get_frequency': {
-            // period is in ns; frequency = 1e9 / period (Hz).
-            return { expression: `(${v}.period ? (1000000000ULL / ${v}.period) : 0)` };
+        case 'pwm.set_period': {
+            // No period-only API: pwm_set_dt applies the new period and resets the
+            // pulse to idle — follow with setPulse/setDuty to drive the line.
+            return { code: `${marker}(void)pwm_set_dt(&${v}, ${o.periodNs}, 0);` };
         }
-        case 'pwm.get_resolution':
-            // Arduino-compatible 8-bit duty range.
-            return { expression: '8' };
         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/random.js

@@ -5,7 +5,7 @@
 // the configured entropy source (the nRF52840 hardware RNG when
 // CONFIG_HARDWARE_DEVICE_RANDOM_GENERATOR is selected, or the default test/
 // xoroshiro generator otherwise). It is seeded automatically at boot from the
-// entropy driver, so unlike Arduino there is no implicit seeding step.
+// entropy driver, so there is no implicit seeding step.
 //
 // The HAL random surface is the Arduino-core model:
 //   random.int()    → a non-negative 31-bit integer [0, 2^31 - 1]
@@ -70,7 +70,7 @@ export function randomInitLines() {
         `}`,
         ``,
         `// Re-seed the PRNG. After this call the sequence is deterministic from`,
-        `// \`seed\`, matching Arduino randomSeed. A literal zero seed is accepted and`,
+        `// \`seed\`, matching the platform's randomSeed. A literal zero seed is accepted and`,
         `// remapped to the same odd constant (xorshift32 cannot start from 0).`,
         `static inline void __tc_rand_seed(uint32_t seed) {`,
         `    __tc_rand_state = (seed == 0U) ? 0x9E3779B9U : seed;`,
@@ -84,7 +84,7 @@ export function randomInitLines() {
         `}`,
         ``,
         `// Half-open range [min, max-1]. Implements the HAL contract directly rather`,
-        `// than calling Arduino random(min, max): the modulus rejection-free form`,
+        `// than calling the platform random(min, max): the modulus rejection-free form`,
         `// avoids the modulo bias a naive (rand % (max-min)) introduces. max > min`,
         `// is assumed (the HAL validates this at the source level).`,
         `static inline int32_t __tc_rand_range(int32_t min, int32_t max) {`,

package/dist/lowering/sensor.d.ts

@@ -0,0 +1,37 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+/** Strip the 'SENSOR.' property-access prefix from a part token arg. */
+export declare function sensorPartKey(part: string): string;
+/** Strip the 'CHAN.' property-access prefix from a channel arg. */
+export declare function sensorChanName(chan: string): string;
+/** All names a constructed sensor is known by, derived from the op facts. */
+export interface SensorNames {
+    /** DT nodelabel of the child node the overlay emits
+     *  (tc_<part>_i2c<N>_0x<addr> / tc_<part>_spi<N>_cs<pin>). */
+    dtLabel: string;
+    /** C device-handle variable (__tc_sensor_<stem>_dev). */
+    devVar: string;
+    /** C sensor_value scratch variable (__tc_sensor_<stem>_val). */
+    valVar: string;
+    /** The controller index the bus string carries. */
+    busIndex: number;
+    /** The bus port: I2C address or SPI CS pin. */
+    port: number;
+    /** 'i2c' | 'spi'. */
+    busKind: 'i2c' | 'spi';
+}
+/** 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. */
+export declare function sensorNames(part: string, bus: string, port: number | string, busKind?: string): SensorNames;
+/**
+ * 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[];
+/**
+ * Resolve a HAL sensor.* op to Zephyr C++.
+ * Returns `{ code }` for fetch (statement), `{ expression }` for get (value).
+ */
+export declare function lowerSensor(op: HALOpIR): {
+    code?: string;
+    expression?: string;
+};

package/dist/lowering/sensor.js

@@ -0,0 +1,119 @@
+// ---------------------------------------------------------------------------
+// Sensor lowering — Zephyr's uniform sensor API over the generated catalog
+//
+// One code shape for every part in @typecad/hal's sensor catalog: the op's
+// part token resolves to the DT compatible, the bus string to the controller
+// index, and the address to the I2C reg. The names are derived identically
+// here (device handles), in strategy.ts state blocks, and in the overlay
+// scanner (dt-config/overlay.ts + toolchain/index.ts) — the tc-pwm<pin>
+// discipline: both sides derive from the same facts, so they cannot drift.
+//
+// Kconfig: nothing per-part. The in-tree driver Kconfigs are `default y` on
+// DT_HAS_<COMPAT>_ENABLED, so the overlay's child node IS the enable switch;
+// CONFIG_SENSOR (the umbrella under `if SENSOR`) is usage-gated in
+// dt-config/kconfig.ts off the lowered `sensor_` tokens.
+// ---------------------------------------------------------------------------
+import { SENSOR_PART_INFO } from '@typecad/hal';
+import { parseControllerIndex } from './util.js';
+/** Strip the 'SENSOR.' property-access prefix from a part token arg. */
+export function sensorPartKey(part) {
+    return part.replace(/^SENSOR\./, '');
+}
+/** Strip the 'CHAN.' property-access prefix from a channel arg. */
+export function sensorChanName(chan) {
+    return chan.replace(/^CHAN\./, '');
+}
+/** 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. */
+export function sensorNames(part, bus, port, busKind = 'i2c') {
+    const partKey = sensorPartKey(String(part));
+    const busIndex = parseControllerIndex(typeof bus === 'string' ? bus : String(bus));
+    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)}`;
+    return {
+        dtLabel: `tc_${stem}`,
+        devVar: `__tc_sensor_${stem}_dev`,
+        valVar: `__tc_sensor_${stem}_val`,
+        busIndex,
+        port: portNum,
+        busKind: busKind === 'spi' ? 'spi' : 'i2c',
+    };
+}
+/**
+ * Resolve the part token against the generated catalog, validating the bus
+ * kind and (when the driver scan knows them) the channel. Throws a build-time
+ * error with the Zephyr-facing name — the same words the user would meet in
+ * Zephyr docs, checked before west ever runs.
+ */
+/** @internal */
+function requirePartInfo(partKey) {
+    const info = SENSOR_PART_INFO[partKey];
+    if (!info) {
+        throw new Error(`Sensor part '${partKey}' is not in the Zephyr sensor catalog (SENSOR in @typecad/hal). ` +
+            `Check the token against the catalog — it is the compatible with , and - replaced by _.`);
+    }
+    return info;
+}
+/** Validate the op's bus kind against the part's bindings. */
+function requireBusKind(partKey, info, busKind) {
+    if (!info.buses.includes(busKind)) {
+        throw new Error(`Sensor part '${partKey}' (${info.compatible}) does not bind on ${busKind.toUpperCase()} — ` +
+            `its bindings are ${info.buses.join('/').toUpperCase()}.`);
+    }
+}
+/**
+ * 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) {
+    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)}`;
+    return [
+        '// CUTTLEFISH_SENSOR_BEGIN',
+        `static const struct device* ${n.devVar} = DEVICE_DT_GET(DT_NODELABEL(${n.dtLabel}));`,
+        `static struct sensor_value ${n.valVar};`,
+        cfg,
+        '// CUTTLEFISH_SENSOR_END',
+    ];
+}
+/**
+ * Resolve a HAL sensor.* op to Zephyr C++.
+ * Returns `{ code }` for fetch (statement), `{ expression }` for get (value).
+ */
+export function lowerSensor(op) {
+    const o = op;
+    const partKey = sensorPartKey(String(o.part));
+    const info = requirePartInfo(partKey);
+    requireBusKind(partKey, info, String(o.busKind ?? 'i2c'));
+    const n = sensorNames(o.part, o.bus, o.port ?? o.address, String(o.busKind ?? 'i2c'));
+    switch (op.operation) {
+        case 'sensor.fetch':
+            // sensor_sample_fetch. The leading (void) keeps the value scratch
+            // referenced under Zephyr's -Werror when the program fetches but never
+            // reads a channel (the state block is emitted per referenced sensor).
+            return {
+                code: `(void)${n.valVar}; sensor_sample_fetch(${n.devVar});`,
+            };
+        case 'sensor.get': {
+            const chan = sensorChanName(String(o.chan));
+            if (info.channels.length > 0 && !info.channels.includes(chan)) {
+                throw new Error(`Sensor part '${partKey}' (${info.compatible}) does not serve channel '${chan}' — ` +
+                    `its driver serves: ${info.channels.join(', ')}.`);
+            }
+            // sensor_value is val1 + val2 * 1e-6; evaluate once per read.
+            return {
+                expression: `(sensor_channel_get(${n.devVar}, SENSOR_CHAN_${chan}, &${n.valVar}), ` +
+                    `static_cast<double>(${n.valVar}.val1) + static_cast<double>(${n.valVar}.val2) / 1000000.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.`);
+    }
+}

package/dist/lowering/spi.d.ts

@@ -1,5 +1,17 @@
 import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
 import type { ZephyrChipDescriptor } from '../chips/types.js';
+export interface SpiTargetNames {
+    dtLabel: string;
+    varName: string;
+    busIndex: number;
+    cs: number;
+}
+/** Derive a thin SPI target's names from the op facts. */
+export declare function spiTargetNames(bus: string, cs: number | string): SpiTargetNames;
+/** The per-target state block: one spi_dt_spec against the DT child node the
+ *  overlay emits, plus the tc-spit-cfg comment the overlay scanner reads (the
+ *  tc-sensor-cfg channel). Called from shimLines for each distinct target. */
+export declare function spiTargetStateLines(bus: string, cs: number | string, hz?: number | string, mode?: number | string): string[];
 /**
  * Emit the per-controller SPI state. The bus device resolves at compile time;
  * a static spi_config holds the base operation flags, and mutable runtime fields