@typecad/hal 1.0.0-alpha.13 → 1.0.0-alpha.15

package/src/sensor.ts

@@ -0,0 +1,80 @@
+// ---------------------------------------------------------------------------
+// Sensor — generic DT-bound sensor part (Zephyr's uniform sensor API)
+//
+// `new Sensor(SENSOR.sensirion_sht3xd, I2C1.device(0x44))` covers every part
+// in the generated catalog: the constructor's facts (part token + bus +
+// address) become a devicetree child node in the generated overlay, and the
+// methods lower to Zephyr's one-shape sensor API (sensor_sample_fetch /
+// sensor_channel_get). No per-part code exists anywhere — the catalog
+// (sensor-catalog.generated.ts) is data, generated from Zephyr's own binding
+// YAMLs and driver channel tables.
+//
+// The channel names are Zephyr verbiage minus the SENSOR_CHAN_ prefix
+// (CHAN.AMBIENT_TEMP ↔ SENSOR_CHAN_AMBIENT_TEMP), so any Zephyr sample or
+// binding doc greps straight into user code.
+// ---------------------------------------------------------------------------
+
+import { sensorFetch, sensorGet } from './emit.js';
+import { include } from './include.js';
+import type { I2CTarget } from './i2c-target.js';
+import type { SPITarget } from './spi-target.js';
+import type { SensorChannelOf, SensorBusOf } from './sensor-catalog.generated.js';
+
+/** Part ids the catalog knows (the Sensor<P> narrowing keys). */
+type SensorPartId = keyof SensorChannelOf;
+
+/** The bus-device argument a part accepts, from its generated bus map:
+ *  SPI-only parts take SPITarget, I2C-only take I2CTarget, dual-bus either. */
+type BusDeviceFor<B extends string> = B extends 'spi' ? SPITarget : B extends 'i2c' ? I2CTarget : I2CTarget | SPITarget;
+export type SensorBusDevice<P extends SensorPartId = SensorPartId> = BusDeviceFor<SensorBusOf[P]>;
+
+/** Construction options. */
+export interface SensorOptions {
+  /** SPI clock in Hz, SPI parts only. Default 1 MHz (safe for every
+   *  catalog part); raise to the breakout's datasheet maximum. */
+  spiHz?: number;
+  /** SPI mode (CPOL/CPHA bits), 0-3. Default 0. */
+  mode?: 0 | 1 | 2 | 3;
+  /** Alert GPIO, for parts whose binding declares alert-gpios. */
+  alert?: number;
+}
+
+export class Sensor<P extends SensorPartId = SensorPartId> {
+  private readonly _part: string;
+  private readonly _bus: string = '';
+  private readonly _port: number = 0;
+  private readonly _kind: string = 'i2c';
+  private readonly _spiHz: number = 1000000;
+  private readonly _mode: number = 0;
+  private readonly _alert: number = -1;
+
+  /** Construct a sensor handle. `part` is a `SENSOR.<name>` token;
+   *  `dev` is the bus device (e.g. `I2C1.device(0x44)`) carrying the bus
+   *  and address. The transpiler resolves the bus instance and address from
+   *  `dev` — the class fields are the IR carrier, not runtime state.
+   *  The `P` parameter is editor-only: it narrows `get()` to this part's
+   *  channels (from the generated SensorChannelOf map); the transpiler
+   *  re-validates at build time with the driver's full channel list. */
+  constructor(part: P, dev: SensorBusDevice<P>, opts?: SensorOptions) {
+    this._part = part;
+    void dev;
+    void opts;
+  }
+
+  /** Fetch a fresh sample (sensor_sample_fetch). Reads reflect the last
+   *  fetch — Zephyr's own fetch/get split, kept verbatim. */
+  fetch(): void {
+    include('<zephyr/drivers/sensor.h>');
+    sensorFetch(this._part, this._bus, this._port, this._kind, this._spiHz, this._mode, this._alert);
+  }
+
+  /** Read one channel from the fetched sample (sensor_channel_get).
+   *  Returns the value as a double (val1 + val2/1e6). The parameter is
+   *  narrowed to this part's channels when constructed from a literal
+   *  SENSOR token — `sht3x.get(` completes AMBIENT_TEMP | HUMIDITY and
+   *  rejects the rest in the editor. */
+  get(chan: SensorChannelOf[P]): number {
+    include('<zephyr/drivers/sensor.h>');
+    return sensorGet(this._part, this._bus, this._port, this._kind, this._spiHz, this._mode, this._alert, chan);
+  }
+}

package/src/shift-pin.ts

@@ -0,0 +1,16 @@
+// ---------------------------------------------------------------------------
+// shiftOut / shiftIn — the thin bit-bang shift (the legacy shiftOut/shiftIn
+// shape, Zephyr-lowered): clock idles low; each bit sets data then pulses the
+// clock. For real SPI, use SPITarget. Pin arguments accept board pin aliases
+// (resolved to their numbers by the transpiler).
+// ---------------------------------------------------------------------------
+
+import { gpioShiftOut, gpioShiftIn } from './emit.js';
+
+export function shiftOut(dataPin: number, clockPin: number, value: number, msbFirst: boolean = true): void {
+  gpioShiftOut(dataPin, clockPin, value, msbFirst);
+}
+
+export function shiftIn(dataPin: number, clockPin: number, msbFirst: boolean = true): number {
+  return gpioShiftIn(dataPin, clockPin, msbFirst);
+}

package/src/spi-target.ts

@@ -0,0 +1,53 @@
+// ---------------------------------------------------------------------------
+// SPITarget — the thin Zephyr-shaped SPI device
+//
+// A chip-select peer on an SPI bus, addressed the Zephyr way: construction
+// emits a devicetree child node (cs-gpios index + spi-max-frequency + mode
+// bits — the same machinery sensors ride), and the verbs lower to
+// spi_transceive_dt / spi_write_dt against a static spi_dt_spec. Hardware
+// CS, no manual GPIO toggling, no runtime spi_config rebuilding.
+//
+// `bus` is the board's bus instance export (SPI0/SPI1), `cs` the chip-select
+// pin, and the options are the wire facts: `hz` (spi-max-frequency) and
+// `mode` (CPOL/CPHA bits 0–3 → spi-cpol/spi-cpha).
+// ----------------------------------------------------------------------------
+
+import { spiTransceiveDt, spiWriteDt, spiReadReg } from './emit.js';
+import type { Pin } from './gpio.js';
+
+export class SPITarget {
+  private readonly _bus: string;
+  private readonly _cs: number;
+  private readonly _hz: number;
+  private readonly _mode: number;
+
+  /** Construct a device handle. `bus` is the bus instance (SPI0, …); `cs`
+   *  is the chip-select pin; `hz` the bus clock (spi-max-frequency, default
+   *  1 MHz conservative); `mode` the SPI mode 0–3. */
+  constructor(bus: string, cs: number | Pin, opts?: { hz?: number; mode?: 0 | 1 | 2 | 3 }) {
+    this._bus = bus;
+    this._cs = typeof cs === 'number' ? cs : cs.number;
+    this._hz = opts?.hz ?? 1000000;
+    this._mode = opts?.mode ?? 0;
+  }
+
+  /** Full-duplex transfer (spi_transceive_dt): `tx` bytes out while `rx`
+   *  captures — the buffer you pass is the buffer filled, so declare it and
+   *  read it directly (rx.length decides the capture length). Omit `rx`
+   *  for a write-only transfer. */
+  transceive(tx: number[] | Uint8Array, rx?: Uint8Array): void {
+    spiTransceiveDt(this._bus, this._cs, this._hz, this._mode, tx, rx ?? new Uint8Array(0));
+  }
+
+  /** Write bytes (spi_write_dt) — no capture. */
+  write(tx: number[] | Uint8Array): void {
+    spiWriteDt(this._bus, this._cs, this._hz, this._mode, tx);
+  }
+
+  /** Register read sugar: sends `reg`, returns the one captured byte
+   *  (spi_transceive_dt against an internal buffer — e.g. a BME280's ID
+   *  register 0xD0 reads 0x60). */
+  readReg(reg: number): number {
+    return spiReadReg(this._bus, this._cs, this._hz, this._mode, reg);
+  }
+}

package/src/spi.ts

@@ -1,121 +1,27 @@
-import { spiBegin, spiEnd, spiTransfer, spiBeginTx, spiEndTx, spiCsLow, spiCsHigh, spiSetMode, spiSetBitOrder, spiReadBuffer, rawCpp } from './emit.js';
-import { include } from './include.js';
-import type { Pin } from './gpio.js';
-import type { SPIMode, SPISettings } from './types.js';
-
-export class SPIDevice {
-  private _bus: string;
-  private _cs: number;
-
-  constructor(bus: string, chipSelect: number) {
-    this._bus = bus;
-    this._cs = chipSelect;
-  }
-
-  transfer(data: number | Uint8Array): number {
-    include("<SPI.h>");
-    spiCsLow(this._cs);
-    rawCpp(`auto __res = ${this._bus}.transfer(${data});`);
-    spiCsHigh(this._cs);
-    rawCpp(`return __res;`);
-    return 0;
-  }
-
-  write(data: number | Uint8Array): void {
-    include("<SPI.h>");
-    spiCsLow(this._cs);
-    spiTransfer(this._bus, data);
-    spiCsHigh(this._cs);
-  }
-
-  readRegister(register: number, count: number): Uint8Array {
-    include("<SPI.h>");
-    spiCsLow(this._cs);
-    spiTransfer(this._bus, register);
-    // Clock `count` dummy bytes and drain them into the caller's buffer
-    // (declared by the Uint8Array return marker as `uint8_t data[count]`).
-    // Using the semantic primitive — NOT rawCpp — keeps the buffer in user
-    // scope so it survives the return (no decayed pointer) and `data.length`
-    // / `data[i]` work, mirroring I2CDevice.readBytes.
-    spiReadBuffer(this._bus, count, new Uint8Array(count));
-    spiCsHigh(this._cs);
-    return new Uint8Array(count);
-  }
-
-  writeRegister(register: number, value: number): void {
-    include("<SPI.h>");
-    spiCsLow(this._cs);
-    spiTransfer(this._bus, register);
-    spiTransfer(this._bus, value);
-    spiCsHigh(this._cs);
-  }
-}
-
-export class SPIBus {
-  static readonly __includes = ["<SPI.h>"];
-  private _bus: string;
-
-  constructor(bus: string) {
-    this._bus = bus;
-  }
-
-  device(chipSelect: Pin): SPIDevice {
-    return new SPIDevice(this._bus, chipSelect.number);
-  }
-
-  begin(): this {
-    include("<SPI.h>");
-    spiBegin(this._bus);
-    return this;
-  }
-
-  end(): void {
-    spiEnd(this._bus);
-  }
-
-  take(): this | null {
-    return this;
-  }
-
-  release(): void {
-    // No-op for standard Arduino.
-  }
-
-
-  transfer(value: number | Uint8Array): number {
-    return spiTransfer(this._bus, value);
-  }
-
-  setFrequency(hz: number): void {
-    spiBeginTx(this._bus, `SPISettings(${hz}, MSBFIRST, SPI_MODE0)`);
-  }
-
-  beginTransaction(settings: SPISettings): void {
-    spiBeginTx(this._bus, settings);
-  }
-
-  endTransaction(): void {
-    spiEndTx(this._bus);
-  }
-
-  setMode(mode: SPIMode): void {
-    spiSetMode(this._bus, mode);
-  }
-
-  setBitOrder(order: 'lsb' | 'msb'): void {
-    spiSetBitOrder(this._bus, order);
-  }
-
-  write(value: number): void {
-    spiTransfer(this._bus, value);
-  }
-
-  write16(value: number): void {
-    rawCpp(`${this._bus}.transfer16(${value});`);
-  }
-}
-
-/** Map TypeCAD SPI instance number to Arduino C++ object name. SPI0→SPI, SPI1→SPI1 */
-export function spiName(instance: number): string {
-  return instance === 0 ? "SPI" : `SPI${instance}`;
-}
+// ---------------------------------------------------------------------------
+// SPI — controller selector (legacy SPI API removed)
+//
+// The bus singletons (SPI0/SPI1…) are CONTROLLER SELECTORS; device(cs, opts?)
+// hands back the FUNCTIONAL SPITarget directly — transceive/write/regRead
+// verbs callable with no further construction. Equivalent to
+// `new SPITarget(this, cs, opts)`. The standalone SPIDevice fact-carrier was
+// absorbed by SPITarget.
+// ----------------------------------------------------------------------------
+
+import { SPITarget } from './spi-target.js';
+import type { Pin } from './gpio.js';
+
+export class SPIBus {
+  private _bus: string;
+
+  constructor(bus: string) {
+    this._bus = bus;
+  }
+
+  /** The functional device target behind `chipSelect` on this controller —
+   *  transceive/write/regRead verbs callable directly, and the fact-carrier
+   *  `new Sensor(...)` accepts. */
+  device(chipSelect: Pin, opts?: { hz?: number; mode?: 0 | 1 | 2 | 3 }): SPITarget {
+    return new SPITarget(this._bus, chipSelect, opts);
+  }
+}

package/src/thread.ts

@@ -0,0 +1,44 @@
+// ---------------------------------------------------------------------------
+// Thread — the thin Zephyr-shaped thread
+//
+// k_thread_create / k_thread_join with Zephyr's own model: construction
+// carries the thread's facts (stack size, priority); start(fn) creates and
+// schedules it (K_NO_WAIT — running immediately); join() blocks until it
+// exits (K_FOREVER). The entry function is a no-argument closure, trampolined
+// through Zephyr's (void*, void*, void*) entry signature — the same
+// callback machinery interrupts use.
+//
+// The `index` is the thread's identity (0, 1, 2, …) — the slot its stack and
+// k_thread state occupy, like Counter's instance. Priorities: Zephyr's scale
+// — 5 (the default) is preemptive, below main; negative would be cooperative.
+// ----------------------------------------------------------------------------
+
+import { threadStart, threadJoin } from './emit.js';
+import { callback } from './callback.js';
+
+export class Thread {
+  private readonly _index: number;
+  private readonly _stackBytes: number;
+  private readonly _priority: number;
+
+  /** Construct a thread handle. `stackKb` defaults to 2 (generous for
+   *  generated code); `priority` defaults to 5 — preemptive, below main. */
+  constructor(index: number, opts?: { stackKb?: number; priority?: number }) {
+    this._index = index;
+    this._stackBytes = (opts?.stackKb ?? 2) * 1024;
+    this._priority = opts?.priority ?? 5;
+  }
+
+  /** Create the thread and schedule it immediately (k_thread_create with
+   *  K_NO_WAIT). The entry function runs concurrently with main from here. */
+  start(fn: () => void): void {
+    threadStart(this._index, this._stackBytes, this._priority, callback(fn));
+  }
+
+  /** Block until the thread exits (k_thread_join with K_FOREVER). Requires
+   *  a prior start() on the same index — an unstarted slot is a build
+   *  error naming the slot's symbol. */
+  join(): void {
+    threadJoin(this._index);
+  }
+}

package/src/time.ts

@@ -0,0 +1,50 @@
+// ---------------------------------------------------------------------------
+// Time — the TS-flavored timing surface
+//
+// The Arduino-named forms (delay/millis/micros/delayMicroseconds, module
+// functions and the Timing class) are deprecated for new code but keep
+// lowering — framework-arduino is frozen on them. Time is the replacement:
+// plain-number milliseconds like the rest of the JS ecosystem (Date.now() is
+// ms), microseconds explicit in the name, and the honest Zephyr verbs —
+// k_msleep (yielding sleep), k_uptime_get (ms clock), k_busy_wait (spin).
+// ---------------------------------------------------------------------------
+
+import { timeSleep, timeNow, timeNowUs, timeBusyWaitUs } from './emit.js';
+
+export class TimeClass {
+  static readonly __instance_name = 'Time';
+
+  /** Yielding sleep in milliseconds (k_msleep). On the generated
+   *  single-threaded main this blocks the caller — the same semantics
+   *  delay() had, JS-spelled. Inside an async function, `await`-ed it
+   *  becomes cooperative: the async state machine arms a deadline and
+   *  yields (other tasks and timers run) until it passes — the same
+   *  machinery `await delay()` rides. */
+  sleep(ms: number): Promise<void> {
+    timeSleep(ms);
+    return Promise.resolve();
+  }
+
+  /** Milliseconds since boot as a double (k_uptime_get) — Date.now()-shaped:
+   *  milliseconds, monotonic, no uint32 wrap. */
+  now(): number {
+    return timeNow();
+  }
+
+  /** Microseconds since boot as a double — uptime-derived
+   *  (k_uptime_get() * 1000) on every board: the cycle-counter form reads a
+   *  constant on SoCs without a free-running 64-bit counter, so the one
+   *  uniform, monotonic expression wins. Resolution is the uptime tick
+   *  (millisecond); for sub-ms determinism use Counter (hardware timer). */
+  nowUs(): number {
+    return timeNowUs();
+  }
+
+  /** Spin-wait the given microseconds (k_busy_wait) — no yield; for sub-ms
+   *  protocol timing where a schedule point would break the waveform. */
+  busyWaitUs(us: number): void {
+    timeBusyWaitUs(us);
+  }
+}
+
+export const Time = new TimeClass();

package/src/types.ts

@@ -1,12 +1,13 @@
 // ---------------------------------------------------------------------------
 // @typecad/hal — Public type definitions
 //
-// Transpiler-shim type surface: enums, type aliases, and the pin-group API
-// consumed by the HAL's transpiler-shim classes (Pin/OutputPin/InputPin,
-// I2CBus/SPIBus/SerialPort) and re-exported for downstream type-checking.
+// Transpiler-shim type surface: value aliases and the enums consumed by the
+// HAL's transpiler-shim classes (Pin, GPIO, I2CBus/SPIBus) and re-exported
+// for downstream type-checking.
 //
 // Runtime-contract interfaces (BasePin, II2CBus, ISPIBus, ISerialPort, the
-// status enums, capability guards, etc.) have been relocated to
+// status enums, capability guards, and the legacy Wire/SPI protocol-shape
+// types I2CAddress/SPIMode/SPIBitOrder/SPISettings) have been relocated to
 // @typecad/simulator/src/contracts.ts — they describe the runtime objects the
 // simulator implements, not the transpiler shims that live here.
 // ---------------------------------------------------------------------------
@@ -21,6 +22,15 @@ export type DigitalValue = boolean;
 /** An analog value is a plain number (resolution-dependent). */
 export type AnalogValue = number;
 
+// ---------------------------------------------------------------------------
+// Serial write value
+// ---------------------------------------------------------------------------
+
+/** A value a serial port (UART / USB console) can write: text, a number, or
+ *  a boolean. Numbers format as decimal (integer + trimmed fractional);
+ *  booleans print as 1/0. */
+export type SerialValue = string | number | boolean;
+
 // ---------------------------------------------------------------------------
 // Pin mode enum
 // ---------------------------------------------------------------------------
@@ -34,83 +44,12 @@ export enum PinMode {
   ANALOG            = 'ANALOG',
 }
 
-// ---------------------------------------------------------------------------
-// Interrupt mode enum
-// ---------------------------------------------------------------------------
-
-export enum InterruptMode {
-  RISING  = 'RISING',
-  FALLING = 'FALLING',
-  CHANGE  = 'CHANGE',
-  LOW     = 'LOW',
-  HIGH    = 'HIGH',
-}
-
 // ---------------------------------------------------------------------------
 // Interrupt handler type
 // ---------------------------------------------------------------------------
 
 export type InterruptHandler = () => void;
 
-// ---------------------------------------------------------------------------
-// Pin groups
-// ---------------------------------------------------------------------------
-
-export interface PinGroupMember {
-  readonly number: number;
-  readonly gpio: number;
-  write(value: DigitalValue): void;
-  high(): void;
-  low(): void;
-  toggle(): void;
-  read(): DigitalValue;
-  isHigh(): boolean;
-  isLow(): boolean;
-}
-
-export interface IPinGroup<T extends PinGroupMember = PinGroupMember> {
-  readonly name: string;
-  readonly pins: ReadonlyArray<T>;
-  writePattern(pattern: number): void;
-  readPattern(): number;
-  fill(value: DigitalValue): void;
-}
-
-export function createPinGroup<T extends PinGroupMember>(
-  pins: T[]
-): IPinGroup<T> {
-  return {
-    name: 'PinGroup',
-    pins: Object.freeze(pins) as ReadonlyArray<T>,
-    writePattern(pattern: number): void {
-      for (let i = 0; i < this.pins.length; i++) {
-        const bit = (pattern >> i) & 1;
-        const pin = this.pins[i];
-        if ('write' in pin && typeof pin.write === 'function') {
-          pin.write(bit === 1);
-        }
-      }
-    },
-    readPattern(): number {
-      let value = 0;
-      for (let i = 0; i < this.pins.length; i++) {
-        const pin = this.pins[i];
-        if ('isHigh' in pin && typeof pin.isHigh === 'function' && pin.isHigh()) {
-          value |= (1 << i);
-        }
-      }
-      return value;
-    },
-    fill(value: DigitalValue): void {
-      for (const pin of this.pins) {
-        if ('write' in pin && typeof pin.write === 'function') {
-          pin.write(value);
-        }
-      }
-    },
-  };
-}
-
 // ---------------------------------------------------------------------------
 // Architecture identifier
 // ---------------------------------------------------------------------------
@@ -129,17 +68,3 @@ export type ArchitectureIdentifier =
   | 'nrf52'
   | (string & {});
 
-// ---------------------------------------------------------------------------
-// Protocol-shape types (re-exported by @typecad/framework-arduino)
-// ---------------------------------------------------------------------------
-
-export type I2CAddress = number;
-
-export type SPIBitOrder = 'msb' | 'lsb';
-export type SPIMode = 0 | 1 | 2 | 3;
-
-export interface SPISettings {
-  frequency: number;
-  mode: SPIMode;
-  bitOrder: SPIBitOrder;
-}

package/src/uart-port.ts

@@ -0,0 +1,64 @@
+// ---------------------------------------------------------------------------
+// UART — the thin Zephyr-shaped serial port
+//
+// TX is poll-based (uart_poll_out — synchronous, fine for writes); RX is
+// INTERRUPT-backed: the first receive call arms the driver's IRQ callback,
+// which drains the FIFO into a construction-sized ring buffer. That makes
+// the honest versions of the calls the poll API couldn't support:
+//   available() — bytes waiting in the ring (the poll driver cannot report
+//                 this without draining the byte you want next)
+//   peek()      — the oldest byte WITHOUT consuming it
+//   read()      — pop the oldest byte, or -1 when the ring is empty
+//
+// Construction: `new UART('UART0', { baud: 9600, rxBufferBytes: 128 })` —
+// the ring size (default 64) is a construction fact that sizes the shim's
+// static buffer; bytes arriving with a full ring are dropped (the embedded
+// honest answer — no unbounded buffering).
+// ----------------------------------------------------------------------------
+
+import { uartPollWrite, uartRxAvailable, uartRxPeek, uartRxRead } from './emit.js';
+import type { SerialValue } from './types.js';
+
+export class UART {
+  private readonly _port: string;
+  private readonly _baud: number;
+  private readonly _rxBufferBytes: number;
+
+  /** Construct a port handle. `port` is the UART instance (UART0, UART1, …);
+   *  `baud` applies once at first use (default 115200, 8N1);
+   *  `rxBufferBytes` sizes the receive ring (default 64). */
+  constructor(port: string, opts?: { baud?: number; rxBufferBytes?: number }) {
+    this._port = port;
+    this._baud = opts?.baud ?? 115200;
+    this._rxBufferBytes = opts?.rxBufferBytes ?? 64;
+  }
+
+  /** Write text, a number, or a boolean (uart_poll_out per byte). No newline
+   *  appended. Numbers format as decimal; booleans print as 1/0. */
+  write(data: SerialValue): void {
+    uartPollWrite(this._port, this._baud, data);
+  }
+
+  /** Write a value followed by a newline. */
+  writeLine(data: SerialValue): void {
+    uartPollWrite(this._port, this._baud, data);
+    uartPollWrite(this._port, this._baud, "\n");
+  }
+
+  /** Bytes waiting in the receive ring. Arms the RX interrupt on first
+   *  use (uart_irq_callback_user_data_set + uart_irq_rx_enable — the
+   *  callback drains the FIFO into the ring). */
+  available(): number {
+    return uartRxAvailable(this._port, this._rxBufferBytes);
+  }
+
+  /** The oldest received byte WITHOUT consuming it; -1 when empty. */
+  peek(): number {
+    return uartRxPeek(this._port, this._rxBufferBytes);
+  }
+
+  /** Pop the oldest received byte; -1 when the ring is empty. */
+  read(): number {
+    return uartRxRead(this._port, this._rxBufferBytes);
+  }
+}

package/src/usb.ts

@@ -0,0 +1,82 @@
+// ---------------------------------------------------------------------------
+// USBConsole — the thin CDC-ACM console
+//
+// A serial pipe over the board's USB connector (Communication Device Class,
+// Abstract Control Model). The construction fact is the port identity
+// ('USB0' — the CDC instance index the devicetree overlay composes); the
+// verbs map 1:1 onto Zephyr's CDC device stack:
+//
+//   open()            → start the USB device stack (idempotent; CDC has no
+//                       wire baud — line coding is the host's business)
+//   close()           → observable no-op (tearing down the shared device
+//                       stack would drop every other CDC instance)
+//   write(v)          → one typed write (text | number | boolean — the
+//   writeLine(v)        __tc_print contract, not print(any))
+//   linked()          → the host has the port open (DTR asserted); output
+//                       written before this is silently dropped by hosts
+//   waitLinked(ms)    → ONE op: bounded DTR poll in the shim (k_msleep
+//                       slices), boolean, no user-code busy loop. 0 = forever.
+//   read()/available()→ poll RX (the byte or -1 / a ready count)
+//
+// Unlike a hardware UART, output before the host opens the port is lost —
+// gate on linked()/waitLinked() when early output matters.
+// ----------------------------------------------------------------------------
+
+import {
+  usbBegin, usbEnd, usbPrint, usbPrintln,
+  usbRead, usbAvailable, usbConnected, usbWaitReady,
+} from './emit.js';
+import type { SerialValue } from './types.js';
+
+export class USBConsole {
+  private readonly _port: string;
+
+  /** Construct the console for a CDC instance ('USB0' = instance 0). */
+  constructor(port: string = 'USB0') {
+    this._port = port;
+  }
+
+  /** Start the USB device stack and bring the CDC port up. Idempotent. */
+  open(): void {
+    usbBegin(this._port);
+  }
+
+  /** Stop using the port. Observable no-op on Zephyr — the device stack is
+   *  shared by every CDC instance and is not torn down per-port. */
+  close(): void {
+    usbEnd(this._port);
+  }
+
+  /** Write text, a number, or a boolean. Numbers format as decimal;
+   *  booleans print as 1/0. */
+  write(value: SerialValue): void {
+    usbPrint(this._port, value);
+  }
+
+  /** Write a value followed by a newline. */
+  writeLine(value: SerialValue): void {
+    usbPrintln(this._port, value);
+  }
+
+  /** True when the host has the port open (DTR asserted). Output written
+   *  before this is true is silently dropped by most hosts. */
+  linked(): boolean {
+    return usbConnected(this._port);
+  }
+
+  /** Block until the host opens the port, polling in the shim (no user-code
+   *  busy loop). `timeoutMs` 0 = wait forever. Returns true once linked. */
+  waitLinked(timeoutMs: number = 0): boolean {
+    return usbWaitReady(this._port, timeoutMs);
+  }
+
+  /** Read one byte, or -1 when no byte is ready (non-blocking). */
+  read(): number {
+    return usbRead(this._port);
+  }
+
+  /** Bytes ready to read (the CDC poll path reports 0/1 — see the lowering). */
+  available(): number {
+    return usbAvailable(this._port);
+  }
+}