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

package/dist/boardgen.js

@@ -6,9 +6,10 @@
 // CONTRACT (custom PCB spec) — and emits the two artifacts a project
 // carries instead of a board package:
 //
-//   .cuttlefish/board.ts   — typed pin/bus/LED/BUTTON exports (the virtual
-//                            @typecad/board module points here)
-//   .cuttlefish/board.json — the BoardConstants flat map (pins.all.*,
+//   .typecad-hal/board.ts   — typed pin/bus/LED/BUTTON exports (the virtual
+//                            '@typecad/hal' module resolves here via the
+//                            project tsconfig — the single import surface)
+//   .typecad-hal/board.json — the BoardConstants flat map (pins.all.*,
 //                            peripherals.*, zephyr.*) the transpiler's
 //                            resolveChipFromBoard reconstructs its chip
 //                            view from
@@ -22,13 +23,14 @@
 // matrices) are absent for every board alike.
 //
 // Pure: returns the file contents; the caller (cuttlefish config-loader via
-// the strategy hook, or `cuttlefish board regen`) writes them.
+// the strategy hook, or `typecad-hal board regen`) writes them.
 // ----------------------------------------------------------------------------
 import { parseAsBuiltJson } from './as-built.js';
 import { loadBoardCatalogOverlay, GENERATOR_REV, boardRecordFingerprint, factsFingerprint, findBoardInCatalog, socBusLabelsFromTree, } from '@typecad/cuttlefish/board-catalog';
+import { getBoardGateData } from '@typecad/cuttlefish/board-gate';
 /**
  * The catalog lookups resolve against the local overlay — the user's own
- * Zephyr tree (`cuttlefish board sync`, auto-refreshed when the tree
+ * Zephyr tree (`typecad-hal board sync`, auto-refreshed when the tree
  * moves). There is no compiled-in database: a machine with no tree and no
  * overlay has no boards, and the error below says exactly that.
  */
@@ -36,7 +38,7 @@ function activeBoardData() {
     const data = loadBoardCatalogOverlay()?.data;
     if (!data) {
         throw new Error(`No board catalog on this machine. The catalog is generated from your Zephyr tree —\n` +
-            `run 'cuttlefish board sync' (or point CUTTLEFISH_BOARD_CATALOG at a catalog file).`);
+            `run 'typecad-hal board sync' (or point TYPECAD_HAL_BOARD_CATALOG at a catalog file).`);
     }
     return data;
 }
@@ -75,7 +77,7 @@ export function nrfSaadcAinPads(soc, identifier) {
  * S3/C3/C6/H2 dropped it. Sourced from the HAL's dac_periph.c
  * (`dac_channel_io_num[]`), like the nRF SAADC table is from the PS.
  */
-export function esp32DacPins(soc) {
+function esp32DacPins(soc) {
     const table = {
         esp32: [[0, 25], [1, 26]],
         esp32s2: [[0, 17], [1, 18]],
@@ -408,7 +410,7 @@ export function parsePinName(soc, name) {
     return undefined;
 }
 /** Parse + shape-validate the facts file; a clear error names the file. */
-export function parseUserFactsJson(text, source = 'cuttlefish.facts.json') {
+export function parseUserFactsJson(text, source = 'typecad-hal.facts.json') {
     let parsed;
     try {
         parsed = JSON.parse(text);
@@ -445,6 +447,9 @@ export function userFactsForTarget(file, target) {
     return hit ? file.boards[hit] : undefined;
 }
 export function buildModule(entry, userFacts, factsSuffix = '', seedWarnings = []) {
+    // The ungated surface is derived from the project's own hal copy — same
+    // resolution (project → cwd → monorepo sibling) as the engine's HAL parser.
+    const { ungated: BOARD_UNGATED_EXPORTS, ungatedTypes: BOARD_UNGATED_TYPE_EXPORTS } = getBoardGateData();
     const soc = socOfTarget(entry.identifier);
     const conv = namingConvFor(soc);
     // ── Controller table + datasheet sweep (the same for every board) ──────
@@ -609,7 +614,7 @@ export function buildModule(entry, userFacts, factsSuffix = '', seedWarnings = [
                 adcSources.push(r.source);
         }
     }
-    // User facts (cuttlefish.facts.json) — the escape hatch. User routes win
+    // User facts (typecad-hal.facts.json) — the escape hatch. User routes win
     // PER PIN over every harvested source above, and each takeover is warned.
     // Seeded with the pinctrl harvest's own lint results (name↔value
     // disagreements — routes dropped as untrustworthy upstream of here).
@@ -679,7 +684,7 @@ export function buildModule(entry, userFacts, factsSuffix = '', seedWarnings = [
         if (siliconDac.length > 0 && !dacSources.includes('dac'))
             dacSources.push('dac');
     }
-    // User facts (cuttlefish.facts.json): dac channels win per pin, and the
+    // User facts (typecad-hal.facts.json): dac channels win per pin, and the
     // declared device joins the sources (no analogDevices cross-check — the
     // user vouches for it).
     if (userFacts?.dac) {
@@ -803,7 +808,7 @@ export function buildModule(entry, userFacts, factsSuffix = '', seedWarnings = [
         ...pins.map((p) => p.ident),
         'LED',
         'BUTTON',
-        // '@typecad/hal' imports — a connector silkscreen label can literally be
+        // '@typecad/hal/core' imports — a connector silkscreen label can literally be
         // 'Pin' (phyBOARD-Atlas), and `export const Pin` merges with the import.
         'Pin',
         'I2CBus',
@@ -811,6 +816,9 @@ export function buildModule(entry, userFacts, factsSuffix = '', seedWarnings = [
         'UART',
         'USBConsole',
         'PWM',
+        // The ungated re-export block: a label colliding with any re-exported
+        // hal name would be a duplicate module export.
+        ...BOARD_UNGATED_EXPORTS,
     ]);
     buses.i2c.forEach((_, i) => reservedNames.add(`I2C${i}`));
     buses.spi.forEach((_, i) => reservedNames.add(`SPI${i}`));
@@ -826,49 +834,171 @@ export function buildModule(entry, userFacts, factsSuffix = '', seedWarnings = [
             continue;
         connectorLabelOwner.set(label, pin);
     }
+    // ── Per-pin editor annotations ──────────────────────────────────────────
+    // The same harvested facts board.json carries, stamped as JSDoc on the
+    // datasheet pin exports so plain tsserver surfaces them in hover and
+    // completion detail — board intelligence with zero editor extension. Only
+    // pins WITH a fact (silicon route, any-pad matrix membership, bus role, or
+    // an alias) get a doc line: bare pads stay bare, and the absence of an
+    // annotation says "plain GPIO" without stamping it on every line. Facts and
+    // module derive from the same route sets below, so they cannot disagree.
+    const pwmRouteByPin = new Map(siliconPwm.map((s) => [s.pin, s]));
+    const adcRouteByPin = new Map(siliconAdc.map((s) => [s.pin, s]));
+    const dacRouteByPin = new Map(siliconDac.map((s) => [s.pin, s]));
+    // Any-pad PWM matrices (ESP32 LEDC, nRF psel, RP2 slices) ride global pad
+    // numbers — same base arithmetic the manifest's matrix pins use.
+    const matrixBase = controllers.find((c) => c.nodelabel === 'gpio0')?.minPin ?? 0;
+    const matrixPwmPins = pwmMatrix
+        ? new Set(pwmMatrix.pads.map((pad) => matrixBase + pad))
+        : undefined;
+    // Aliases (connector silkscreen labels, LED/BUTTON) keyed by the aliased
+    // pin's HAL number — connectorLabelOwner's values ARE the sweep's GenPin
+    // objects, so identity holds through the LED/BUTTON facts too.
+    const aliasesByPin = new Map();
+    const noteAlias = (pin, label) => {
+        if (!pin)
+            return;
+        const list = aliasesByPin.get(pin.halPin);
+        if (list)
+            list.push(label);
+        else
+            aliasesByPin.set(pin.halPin, [label]);
+    };
+    for (const [label, pin] of connectorLabelOwner)
+        noteAlias(pin, label);
+    if (ledPinFinal)
+        noteAlias(ledPinFinal, 'LED');
+    if (buttonPin)
+        noteAlias(buttonPin, 'BUTTON');
+    extraLedPins.forEach((p, i) => noteAlias(p, `LED${i + 1}`));
+    extraButtonPins.forEach((p, i) => noteAlias(p, `BUTTON${i + 1}`));
+    // Bus roles (SDA/SCL/MOSI/…) keyed by the route's pad NAME — best-effort
+    // uppercase match; pads whose spelling the pin sweep can't place simply
+    // carry no role line. (busPads is defined further down; this walks
+    // entry.busPins directly to stay above it.)
+    const rolesByPinName = new Map();
+    for (const b of entry.busPins ?? []) {
+        const index = buses[b.bus]?.indexOf(b.nodelabel) ?? -1;
+        if (index < 0)
+            continue;
+        const instance = `${b.bus.toUpperCase()}${index}`;
+        for (const route of b.routes) {
+            if (!route.pad || !route.role)
+                continue;
+            const name = route.pad.toUpperCase();
+            const role = `${instance} ${route.role.toUpperCase()}`;
+            const list = rolesByPinName.get(name);
+            if (list) {
+                if (!list.includes(role))
+                    list.push(role);
+            }
+            else {
+                rolesByPinName.set(name, [role]);
+            }
+        }
+    }
+    const pinDoc = (p) => {
+        const parts = [];
+        const pwm = pwmRouteByPin.get(p.halPin);
+        if (pwm)
+            parts.push(`PWM ${pwm.controller} ch${pwm.channel}`);
+        else if (pwmMatrix && matrixPwmPins?.has(p.halPin)) {
+            parts.push(`PWM ${pwmMatrix.controller} ch0-${pwmMatrix.channelCount - 1} (any pad)`);
+        }
+        const adc = adcRouteByPin.get(p.halPin);
+        // Primary-unit routes (pinctrl and ESP SARADC alike) omit the controller
+        // field — fall back to the pinctrl sources, then the ESP primary unit.
+        if (adc)
+            parts.push(`ADC ${adc.controller ?? adcSources[0] ?? espAdcUnit ?? 'adc'} ch${adc.channel}`);
+        const dac = dacRouteByPin.get(p.halPin);
+        if (dac)
+            parts.push(`DAC ch${dac.channel}`);
+        parts.push(...(rolesByPinName.get(p.name.toUpperCase()) ?? []));
+        const aliases = aliasesByPin.get(p.halPin);
+        if (aliases)
+            parts.push(`aliases: ${aliases.join(', ')}`);
+        return parts.length > 0 ? parts.join(' · ') : undefined;
+    };
     const ts = [];
-    ts.push(`// GENERATED by cuttlefish boardgen from the Zephyr board catalog —`);
+    ts.push(`// GENERATED by typecad-hal boardgen from the Zephyr board catalog —`);
     ts.push(`// ${entry.identifier} (${entry.name}, ${entry.vendor}).`);
-    ts.push(`// Regenerate with: npx cuttlefish board regen`);
+    ts.push(`// Regenerate with: npx typecad-hal board regen`);
     ts.push('');
-    ts.push(`import { Pin, I2CBus, SPIBus, UART${hasUsb ? ', USBConsole' : ''}${pwmLedSpecs.length > 0 ? ', PWM' : ''} } from '@typecad/hal';`);
+    // The generated module IS the user's '@typecad/hal' (the project tsconfig
+    // maps that specifier here), so it reaches the implementation package via
+    // the './core' subpath — the one specifier the paths mapping does not
+    // capture, avoiding a circular self-reference.
+    ts.push(`import { Pin, I2CBus, SPIBus, UART${hasUsb ? ', USBConsole' : ''}${pwmLedSpecs.length > 0 ? ', PWM' : ''} } from '@typecad/hal/core';`);
     ts.push('');
     // ── Hardware-class gateway ─────────────────────────────────────────────
-    // The board module is the NARROWED surface: every hardware class re-export
-    // here exists only when this board's facts support it, so importing
-    // unavailable hardware fails at module resolution (editor + transpile)
-    // instead of at a deep diagnostic. '@typecad/hal' stays the implementation
-    // package; user code imports hardware from '@typecad/board'.
+    // This module is the NARROWED surface behind the user's '@typecad/hal'
+    // import: every hardware class gated on board facts is re-exported below
+    // only when this board's facts support it, so importing unavailable
+    // hardware fails at module resolution (editor + transpile) instead of at
+    // a deep diagnostic. Everything not gated (the lists hal ships in
+    // gate.ts) is re-exported verbatim so the full authoring surface stays
+    // importable from the same specifier ('@typecad/hal' is the one specifier —
+    // the old '@typecad/board' alias was removed with the rename).
+    ts.push('// Always-available HAL surface (not gated on board facts).');
+    ts.push(`export { ${BOARD_UNGATED_EXPORTS.join(', ')} } from '@typecad/hal/core';`);
+    ts.push(`export type { ${BOARD_UNGATED_TYPE_EXPORTS.join(', ')} } from '@typecad/hal/core';`);
+    ts.push('');
     ts.push('// Hardware this board actually has — unavailable hardware is not importable.');
-    ts.push(`export { GPIO, Thread, Time, Sensor } from '@typecad/hal';`);
     if (wdtNodeLabel)
-        ts.push(`export { Watchdog } from '@typecad/hal';`);
+        ts.push(`export { Watchdog } from '@typecad/hal/core';`);
     if (siliconPwm.length > 0 || pwmLedSpecs.length > 0 || pwmMatrix)
-        ts.push(`export { PWM } from '@typecad/hal';`);
+        ts.push(`export { PWM, Servo } from '@typecad/hal/core';`);
     if (siliconAdc.length > 0)
-        ts.push(`export { ADC } from '@typecad/hal';`);
+        ts.push(`export { ADC } from '@typecad/hal/core';`);
     if (siliconDac.length > 0)
-        ts.push(`export { DAC } from '@typecad/hal';`);
+        ts.push(`export { DAC } from '@typecad/hal/core';`);
+    // The responder rides the same wired-bus fact as I2CTarget — target-mode
+    // support is a controller-driver property discovered at registration
+    // (-ENOSYS prints loudly), never a board-name gate.
     if (buses.i2c.length > 0)
-        ts.push(`export { I2CTarget } from '@typecad/hal';`);
+        ts.push(`export { I2CTarget, I2CResponder } from '@typecad/hal/core';`);
     if (buses.spi.length > 0)
-        ts.push(`export { SPITarget } from '@typecad/hal';`);
+        ts.push(`export { SPITarget } from '@typecad/hal/core';`);
     if (buses.uart.length > 0)
-        ts.push(`export { UART } from '@typecad/hal';`);
+        ts.push(`export { UART } from '@typecad/hal/core';`);
+    if (hwtimerControllers.length > 0)
+        ts.push(`export { Counter } from '@typecad/hal/core';`);
+    // Clock rides the same free-counter facts (the zephyr,rtc-counter shim
+    // wraps the counter when the board ships no hardware rtc alias).
     if (hwtimerControllers.length > 0)
-        ts.push(`export { Counter } from '@typecad/hal';`);
+        ts.push(`export { Clock } from '@typecad/hal/core';`);
+    // CAN rides the harvested controller nodes (ESP32 TWAI, STM32 bxCAN,
+    // NXP FlexCAN…); a SoC with none exports nothing.
+    if ((entry.canNodes ?? []).length > 0)
+        ts.push(`export { CAN } from '@typecad/hal/core';`);
+    // I2S rides the harvested i2s@ controllers.
+    if ((entry.i2sNodes ?? []).length > 0)
+        ts.push(`export { I2S } from '@typecad/hal/core';`);
+    // Power rides the SoC's declared cpu-power-states (both the ESP32 family's
+    // standby + soft-off pair and STM32's suspend-to-idle count; a SoC with no
+    // declared states exports nothing).
+    if ((entry.powerStates ?? []).length > 0)
+        ts.push(`export { Power } from '@typecad/hal/core';`);
+    // KEY/MOUSE are ungated token tables — the derived always-available
+    // re-export line above already carries them on every board; only the HID
+    // device classes ride the USB gate.
     if (hasUsb)
-        ts.push(`export { USBConsole } from '@typecad/hal';`);
+        ts.push(`export { USBConsole, Keyboard, Mouse } from '@typecad/hal/core';`);
     // Store/File: a persisted backend needs a storage region — either the
     // board's own storage_partition (harvested reg) or a synthesizable one
     // (flash size known, no existing partition to collide with).
     if (entry.storageReg || (entry.flashKb && !entry.hasStoragePartition)) {
-        ts.push(`export { Store, File } from '@typecad/hal';`);
+        ts.push(`export { Store, File } from '@typecad/hal/core';`);
     }
     ts.push('');
     if (pins.length > 0) {
         ts.push(`// Datasheet-named pins (derived from the board's devicetree controllers)`);
+        ts.push(`// Pins with harvested facts carry them as JSDoc (hover shows routes/roles/aliases);`);
+        ts.push(`// a pin without a doc line is plain GPIO — no PWM/ADC/DAC route on this board.`);
         for (const p of pins) {
+            const doc = pinDoc(p);
+            if (doc)
+                ts.push(`/** ${doc} */`);
             ts.push(`export const ${p.ident} = Pin.fromPort('${p.name}');`);
         }
         ts.push('');
@@ -892,28 +1022,52 @@ export function buildModule(entry, userFacts, factsSuffix = '', seedWarnings = [
             extraPinDecls.push(p);
     }
     for (const p of extraPinDecls) {
-        ts.push(`/** ${p.name} (derived from the devicetree controller label). */`);
         ts.push(`export const ${p.ident} = Pin.fromPort('${p.name}');`);
     }
     if (ledPinFinal) {
-        ts.push(`/** On-board LED (${entry.led ? `devicetree ${entry.led.dtSpec}` : 'addressable strip — no gpio-leds node'}). */`);
+        ts.push(`/** On-board LED${entry.led ? '' : ' — addressable strip, this is its data pin'}. */`);
         ts.push(`export const LED = ${ledPinFinal.ident};`);
     }
     if (buttonPin) {
-        ts.push(`/** User button (devicetree ${entry.button?.dtSpec}). */`);
+        ts.push(`/** User button. */`);
         ts.push(`export const BUTTON = ${buttonPin.ident};`);
     }
     if (ledPinFinal || buttonPin || extraPinDecls.length > 0)
         ts.push('');
-    // Bus instance exports from the board's own DTS-wired controllers.
+    // Bus instance exports from the board's own DTS-wired controllers. When the
+    // harvest parsed a controller's pinctrl overrides, the JSDoc carries its pad
+    // routes ("SDA=PB7, SCL=PB8") — the same facts the pins.<bus> conflict-map
+    // constants hold, surfaced for hover.
+    const busPadPairs = (kind, nodelabel) => (entry.busPins ?? [])
+        .filter((b) => b.bus === kind && b.nodelabel === nodelabel)
+        .flatMap((b) => b.routes)
+        .filter((r) => r.pad && r.role)
+        .map((r) => `${r.role.toUpperCase()}=${r.pad}`);
+    const busDoc = (kind, index, nodelabel) => {
+        const label = kind === 'i2c' ? `I2C bus ${index}` : kind === 'spi' ? `SPI bus ${index}` : `UART ${index}`;
+        const pads = busPadPairs(kind, nodelabel);
+        return `Board-wired ${label}${pads.length > 0 ? ` (${pads.join(', ')})` : ''}.`;
+    };
     const busLines = [];
-    buses.i2c.forEach((_, i) => busLines.push(`export const I2C${i} = new I2CBus('I2C${i}');`));
-    buses.spi.forEach((_, i) => busLines.push(`export const SPI${i} = new SPIBus('SPI${i}');`));
-    buses.uart.forEach((_, i) => busLines.push(`export const UART${i} = new UART('UART${i}');`));
+    buses.i2c.forEach((nodelabel, i) => {
+        busLines.push(`/** ${busDoc('i2c', i, nodelabel)} */`);
+        busLines.push(`export const I2C${i} = new I2CBus('I2C${i}');`);
+    });
+    buses.spi.forEach((nodelabel, i) => {
+        busLines.push(`/** ${busDoc('spi', i, nodelabel)} */`);
+        busLines.push(`export const SPI${i} = new SPIBus('SPI${i}');`);
+    });
+    buses.uart.forEach((nodelabel, i) => {
+        busLines.push(`/** ${busDoc('uart', i, nodelabel)} */`);
+        busLines.push(`export const UART${i} = new UART('UART${i}');`);
+    });
     // USB CDC instance (the thin HAL's USBConsole): the board's DTS turns the
-    // device controller on (zephyr_udc0 status okay).
-    if (hasUsb)
+    // device controller on (zephyr_udc0 status okay). CDC has no pinctrl pad
+    // routes — the console rides the controller's silicon-fixed DP/DM pads.
+    if (hasUsb) {
+        busLines.push(`/** USB serial console — the board's USB connector (no pin to configure). */`);
         busLines.push(`export const USB0 = new USBConsole('USB0');`);
+    }
     // PWM-driven LEDs (pwm-leds): addressed by the board's own devicetree
     // alias (DT_ALIAS(pwm_led0) in the lowering) — no overlay needed. The
     // construction period comes from the DTS cell when it is a plain number
@@ -922,7 +1076,7 @@ export function buildModule(entry, userFacts, factsSuffix = '', seedWarnings = [
     pwmLedSpecs.forEach((l, i) => {
         const period = l.periodNs ?? 1_000_000;
         const name = i === 0 ? 'PWMLED' : `PWMLED${i}`;
-        busLines.push(`/** Board PWM LED (devicetree ${l.alias}${l.flags?.length ? ', ' + l.flags.join(' ') : ''}). */`);
+        busLines.push(`/** Board PWM-driven LED (already constructed — call setDuty() to dim it). */`);
         busLines.push(`export const ${name} = new PWM(${8192 + i}, { periodNs: ${period} });`);
     });
     if (busLines.length > 0) {
@@ -945,12 +1099,15 @@ export function buildModule(entry, userFacts, factsSuffix = '', seedWarnings = [
         // GPIO driver API (`gpio_pin_configure` flags + `gpio_pin_interrupt_configure`):
         // every GPIO controller implements them, so they are universally true —
         // a platform fact, not a per-pad one. Analog/PWM ride the harvested
-        // silicon routes (honest per-pad facts).
+        // silicon routes (honest per-pad facts); PWM counts both route kinds —
+        // fixed pinctrl routes AND any-pad matrices (ESP32 LEDC, nRF psel), the
+        // same set union the pin JSDoc and the PWM export gate read, so the
+        // hover annotation and the capability flag cannot disagree.
         constants[`pins.all.${i}.capabilities.digitalInput`] = true;
         constants[`pins.all.${i}.capabilities.digitalOutput`] = true;
         constants[`pins.all.${i}.capabilities.analogInput`] = siliconAdcPins.has(p.halPin);
         constants[`pins.all.${i}.capabilities.analogOutput`] = siliconDacPins.has(p.halPin);
-        constants[`pins.all.${i}.capabilities.pwm`] = siliconPwmPins.has(p.halPin);
+        constants[`pins.all.${i}.capabilities.pwm`] = siliconPwmPins.has(p.halPin) || (matrixPwmPins?.has(p.halPin) ?? false);
         constants[`pins.all.${i}.capabilities.interrupt`] = true;
         constants[`pins.all.${i}.capabilities.pullUp`] = true;
         constants[`pins.all.${i}.capabilities.pullDown`] = true;
@@ -959,6 +1116,39 @@ export function buildModule(entry, userFacts, factsSuffix = '', seedWarnings = [
         constants[`pins.all.${i}.capabilities.touch`] = false;
         constants[`pins.all.${i}.capabilities.openDrain`] = true;
     });
+    // CPU power states — the harvested PM capability facts (which levels
+    // exist, their idle timing, and whether the automatic policy may enter
+    // them; ESP32's soft-off is explicit-entry only).
+    const powerStates = entry.powerStates ?? [];
+    powerStates.forEach((ps, i) => {
+        constants[`zephyr.power.states.${i}.name`] = ps.name;
+        if (ps.minResidencyUs !== undefined)
+            constants[`zephyr.power.states.${i}.minResidencyUs`] = ps.minResidencyUs;
+        if (ps.exitLatencyUs !== undefined)
+            constants[`zephyr.power.states.${i}.exitLatencyUs`] = ps.exitLatencyUs;
+        constants[`zephyr.power.states.${i}.enabled`] = ps.enabled;
+    });
+    if (powerStates.length > 0) {
+        constants['zephyr.power.softOff'] = powerStates.some((ps) => ps.name === 'soft-off');
+    }
+    if (entry.rtcWakeTimer)
+        constants['zephyr.power.wakeTimer'] = true;
+    // CAN controllers — the harvested labeled nodes (the CAN class gate). The
+    // ESP32 TWAI pads ride along: loopback overlays route both TWAI functions
+    // onto the TX pad.
+    (entry.canNodes ?? []).forEach((c, i) => {
+        constants[`zephyr.can.controllers.${i}.nodeLabel`] = c.nodeLabel;
+        constants[`zephyr.can.controllers.${i}.compatible`] = c.compatible;
+        if (c.txPad !== undefined)
+            constants[`zephyr.can.controllers.${i}.txPad`] = c.txPad;
+        if (c.rxPad !== undefined)
+            constants[`zephyr.can.controllers.${i}.rxPad`] = c.rxPad;
+    });
+    // I2S controllers — the harvested labeled nodes (the I2S class gate).
+    (entry.i2sNodes ?? []).forEach((c, i) => {
+        constants[`zephyr.i2s.controllers.${i}.nodeLabel`] = c.nodeLabel;
+        constants[`zephyr.i2s.controllers.${i}.compatible`] = c.compatible;
+    });
     constants['peripherals.i2c.count'] = buses.i2c.length;
     constants['peripherals.spi.count'] = buses.spi.length;
     constants['peripherals.uart.count'] = buses.uart.length;
@@ -1126,16 +1316,67 @@ export function buildModule(entry, userFacts, factsSuffix = '', seedWarnings = [
     });
     // Bus controllers the board's own DTS wires up — resolveChipFromBoard
     // reconstructs the bus lists from these, and the overlays enable the
-    // nodes the program uses.
+    // nodes the program uses. Each controller also carries its board-DTS
+    // pinctrl routes when the harvest parsed them (`pinctrl` = the route
+    // names, `pads` = `role=PAD` pairs) — the diagnostics report's
+    // peripheral-usage table and the pins.<bus> conflict-map read them.
+    const busPads = (kind, nodelabel) => (entry.busPins ?? []).filter((b) => b.bus === kind && b.nodelabel === nodelabel).flatMap((b) => b.routes);
+    const busPinMap = (kind) => {
+        const parts = [];
+        buses[kind].forEach((nodelabel, i) => {
+            const pairs = busPads(kind, nodelabel)
+                .filter((r) => r.pad && r.role)
+                .map((r) => `${r.role}=${r.pad}`);
+            if (pairs.length > 0)
+                parts.push(`${i}:${pairs.join(',')}`);
+        });
+        return parts.join(';');
+    };
     buses.i2c.forEach((nodelabel, i) => {
         constants[`zephyr.i2c.controllers.${i}.nodeLabel`] = nodelabel;
+        const routes = busPads('i2c', nodelabel);
+        if (routes.length > 0) {
+            constants[`zephyr.i2c.controllers.${i}.pinctrl`] = routes.map((r) => r.name).join(',');
+            constants[`zephyr.i2c.controllers.${i}.pads`] = routes.filter((r) => r.pad).map((r) => `${r.role ?? ''}=${r.pad}`).join(',');
+        }
     });
     buses.spi.forEach((nodelabel, i) => {
         constants[`zephyr.spi.controllers.${i}.nodeLabel`] = nodelabel;
+        const routes = busPads('spi', nodelabel);
+        if (routes.length > 0) {
+            constants[`zephyr.spi.controllers.${i}.pinctrl`] = routes.map((r) => r.name).join(',');
+            constants[`zephyr.spi.controllers.${i}.pads`] = routes.filter((r) => r.pad).map((r) => `${r.role ?? ''}=${r.pad}`).join(',');
+        }
     });
     buses.uart.forEach((nodelabel, i) => {
         constants[`zephyr.uart.controllers.${i}.nodeLabel`] = nodelabel;
+        const routes = busPads('uart', nodelabel);
+        if (routes.length > 0) {
+            constants[`zephyr.uart.controllers.${i}.pinctrl`] = routes.map((r) => r.name).join(',');
+            constants[`zephyr.uart.controllers.${i}.pads`] = routes.filter((r) => r.pad).map((r) => `${r.role ?? ''}=${r.pad}`).join(',');
+        }
     });
+    // The board's console controller (chosen zephyr,console) — the
+    // diagnostics annotate the UART instance the bootloader logs on.
+    if (entry.console)
+        constants['zephyr.console'] = entry.console;
+    // Bus pad conflict maps (analyzeResources): "<inst>:<role>=<PAD>,...;..."
+    const i2cPinMap = busPinMap('i2c');
+    const spiPinMap = busPinMap('spi');
+    const uartPinMap = busPinMap('uart');
+    if (i2cPinMap)
+        constants['pins.i2c'] = i2cPinMap;
+    if (spiPinMap)
+        constants['pins.spi'] = spiPinMap;
+    if (uartPinMap)
+        constants['pins.uart'] = uartPinMap;
+    // Board silicon identity for the diagnostics metadata (the report's
+    // SRAM/flash context) — flash is a devicetree fact, sram/clock are not
+    // harvested and stay absent.
+    if (soc)
+        constants['mcu'] = soc;
+    if (entry.flashKb)
+        constants['memory.flash'] = entry.flashKb * 1024;
     // USB device (CDC-ACM): the board's DTS turned the controller on.
     if (hasUsb) {
         constants['zephyr.usb.controller'] = entry.usbController ?? 'zephyr_udc0';
@@ -1202,7 +1443,7 @@ export function buildModule(entry, userFacts, factsSuffix = '', seedWarnings = [
         constants,
         // Source fingerprint: covers the record content, the extraction
         // revision, and the tree provenance (when the record came from a
-        // catalog). `cuttlefish build` recomputes it cheaply and regenerates
+        // catalog). `typecad-hal build` recomputes it cheaply and regenerates
         // this module when it moves — a board change in the config, the catalog
         // overlay, or the Zephyr tree itself recreates the module.
         source: {
@@ -1227,8 +1468,8 @@ export function generateBoard(target, opts) {
     if (!found) {
         const hint = loadBoardCatalogOverlay()
             ? `'${target}' is not a board target in the current catalog. ` +
-                `It may be new in your Zephyr tree — run 'cuttlefish board sync' and retry.`
-            : `No board catalog on this machine. Run 'cuttlefish board sync' first.`;
+                `It may be new in your Zephyr tree — run 'typecad-hal board sync' and retry.`
+            : `No board catalog on this machine. Run 'typecad-hal board sync' first.`;
         throw new Error(hint);
     }
     // The as-built snapshot (this project's last successful build's resolved
@@ -1250,7 +1491,7 @@ export function generateBoard(target, opts) {
             asBuiltWarnings.push(`ignoring as-built snapshot: ${err.message}`);
         }
     }
-    // The project's cuttlefish.facts.json, when present: the section for THIS
+    // The project's typecad-hal.facts.json, when present: the section for THIS
     // board merges into the manifest (user routes win per pin), and the raw
     // text hashes into the module's source fingerprint so edits regenerate.
     let facts;

package/dist/chips/resolve.js

@@ -196,6 +196,23 @@ export function resolveChipFromBoard(bc) {
     // (+ optional vid/pid for the device descriptor).
     const usbController = bc.get('zephyr.usb.controller');
     const usbCdcInstances = bc.get('zephyr.usb.cdcInstances');
+    const wakeTimer = bc.get('zephyr.power.wakeTimer');
+    const i2sControllers = [];
+    for (let ii = 0; bc.get(`zephyr.i2s.controllers.${ii}.nodeLabel`) !== undefined; ii++) {
+        i2sControllers.push({
+            nodeLabel: String(bc.get(`zephyr.i2s.controllers.${ii}.nodeLabel`)),
+            compatible: String(bc.get(`zephyr.i2s.controllers.${ii}.compatible`)),
+        });
+    }
+    const canControllers = [];
+    for (let ci = 0; bc.get(`zephyr.can.controllers.${ci}.nodeLabel`) !== undefined; ci++) {
+        canControllers.push({
+            nodeLabel: String(bc.get(`zephyr.can.controllers.${ci}.nodeLabel`)),
+            compatible: String(bc.get(`zephyr.can.controllers.${ci}.compatible`)),
+            ...(bc.get(`zephyr.can.controllers.${ci}.txPad`) !== undefined ? { txPad: Number(bc.get(`zephyr.can.controllers.${ci}.txPad`)) } : {}),
+            ...(bc.get(`zephyr.can.controllers.${ci}.rxPad`) !== undefined ? { rxPad: Number(bc.get(`zephyr.can.controllers.${ci}.rxPad`)) } : {}),
+        });
+    }
     const usbVid = bc.get('zephyr.usb.vid');
     const usbPid = bc.get('zephyr.usb.pid');
     // Optional 1200-baud touch-to-reset data (BOSSA-bootloader boards).
@@ -327,6 +344,9 @@ export function resolveChipFromBoard(bc) {
         ...(storageOffset != null && storageSize != null
             ? { storage: { offset: storageOffset, size: storageSize, ...(storagePreexisting ? { preexisting: true } : {}) } }
             : {}),
+        ...(wakeTimer ? { powerWakeTimer: true } : {}),
+        ...(canControllers.length > 0 ? { can: { controllers: canControllers } } : {}),
+        ...(i2sControllers.length > 0 ? { i2s: { controllers: i2sControllers } } : {}),
         ...(usbController && usbCdcInstances && usbCdcInstances > 0
             ? {
                 usb: {

package/dist/chips/types.d.ts

@@ -219,6 +219,27 @@ export interface ZephyrDacChannel {
  * Pure-data descriptor for a Zephyr board + its SoC's peripheral layout.
  */
 export interface ZephyrChipDescriptor {
+    /** The SoC's RTC wake timer (ESP32 family rtc_timer fact) — Power.offFor
+     *  arms it (esp_sleep_enable_timer_wakeup) before soft-off. */
+    readonly powerWakeTimer?: boolean;
+    /** CAN controllers (harvested labeled can@ nodes) — the lowering
+     *  addresses the first by its DT nodelabel. */
+    readonly can?: {
+        controllers: readonly {
+            nodeLabel: string;
+            compatible: string;
+            txPad?: number;
+            rxPad?: number;
+        }[];
+    };
+    /** I2S controllers (harvested labeled i2s@ nodes) — the lowering
+     *  addresses each by its DT nodelabel. */
+    readonly i2s?: {
+        controllers: readonly {
+            nodeLabel: string;
+            compatible: string;
+        }[];
+    };
     /** Zephyr board target (the `west build -b <id>` argument), e.g. 'xiao_ble'. */
     readonly id: string;
     /** SoC family, e.g. 'nrf52840'. */
@@ -436,7 +457,7 @@ export interface ZephyrChipDescriptor {
      * verified with the board, instead of in user configs. One probe method
      * serves BOTH flashing and debugging (the same attach session); entries
      * that cannot debug (bootloaders) set `debug: false`. Users select one via
-     * `zephyr.probe` in cuttlefish.config.ts or `--probe` on the CLI;
+     * `zephyr.probe` in typecad-hal.config.ts or `--probe` on the CLI;
      * `zephyr.runner`/`runnerArgs` remain the raw escape hatch underneath.
      */
     readonly probeMethods?: readonly ZephyrProbeMethod[];

package/dist/debug-codegen.js

@@ -6,7 +6,7 @@
 // stdlibSupport.hasIostream=false), so the GenericStrategy's std::cout fallback
 // used by the debug preprocessor would NOT compile. This module routes every
 // debug line through printk("...\n") — the always-available Zephyr console,
-// with no CONFIG_CONSOLE dependency — so `cuttlefish build --debug` produces
+// with no CONFIG_CONSOLE dependency — so `typecad-hal build --debug` produces
 // compiling output.
 //
 // The halt primitive is __tc_debug_wait_for_continue() (emitted in