@typecad/hal 1.0.0-alpha.14 → 1.0.0-alpha.16

package/dist/emit.js

@@ -6,7 +6,7 @@
 // framework-specific C++ at code generation time.
 //
 // EMIT BOUNDARY: This file is a canonical entry point of the HAL lowering
-// surface (A) — its C++ output lands in user sketches. The emitted bytes are
+// surface (A) — its C++ output lands in user programs. The emitted bytes are
 // covered by the TypeCAD Runtime Exception (see RUNTIME_EXCEPTION.md at the
 // repository root) and are not subject to the license of this tool source.
 //
@@ -23,264 +23,190 @@ export function gpioWrite(pin, value) { }
 export function gpioRead(pin) { return 0; }
 /** Toggle a digital pin. */
 export function gpioToggle(pin) { }
-/** Set pin mode: "output" | "input" | "input_pullup" | "input_pulldown". */
-export function gpioSetMode(pin, mode) { }
+/** Thin GPIO (hal/gpio-pin.ts): configure with Zephyr flag tokens
+ *  ("GPIO.OUTPUT | GPIO.PULL_UP"). The lowering maps token names to the
+ *  GPIO_* macros; the emitted configure is guarded per pin (first use wins). */
+export function gpioConfigure(pin, flags) { }
+/** GPIO.shiftOut/shiftIn: bit-banged shift via two pins (one op each). */
+export function gpioShiftOut(dataPin, clockPin, value, msbFirst) { }
+export function gpioShiftIn(dataPin, clockPin, msbFirst) { return 0; }
+/** Thin GPIO read with FUSED guarded configure — one op, one statement-
+ *  expression: correct in any expression position (if-conditions drop a
+ *  method's leading side-effect ops, so get() must not rely on a separate
+ *  configure op). */
+export function gpioReadCfg(pin, flags) { return 0; }
 // ---------------------------------------------------------------------------
 // PWM — pulse-width modulation
 // ---------------------------------------------------------------------------
-/** Write PWM duty cycle to a pin. */
-export function pwmWrite(pin, duty) { }
-/** Positional semantic primitive. Args: pin, resolutionHz, bit0Hi, bit0Lo,
- *  bit1Hi, bit1Lo, msbFirst, queueDepth. Use rmtTxInit() from hal/rmt.ts. */
-export function rmtTxInit(pin, resolutionHz, bit0Hi, bit0Lo, bit1Hi, bit1Lo, msbFirst, queueDepth) { }
-/** Write bytes via the channel's bytes-encoder (timings fixed at init). */
-export function rmtTxWriteBytes(pin, bytes) { }
-/** Write raw RMT symbols — arbitrary [hiTicks, loTicks] pairs. */
-export function rmtTxWriteSymbols(pin, symbols) { }
-/** Block until the queued TX completes. */
-export function rmtTxWaitDone(pin, timeoutMs) { }
-/** Tear down the TX channel and release its slot. */
-export function rmtTxDeinit(pin) { }
-/** Positional semantic primitive — use rmtRxInit() from hal/rmt.ts. */
-export function rmtRxInit(pin, resolutionHz) { }
-/** Register a callback-by-name invoked when an RX burst completes. */
-export function rmtRxOnReceived(pin, handler) { }
-/** Start receiving. */
-export function rmtRxStart(pin) { }
-/** Stop receiving. */
-export function rmtRxStop(pin) { }
-/** Blocking read — returns flattened symbols [d0,l0,d1,l1,…] in ticks. */
-export function rmtRxRead(pin, maxCount) { return []; }
-/** Tear down the RX channel and release its slot. */
-export function rmtRxDeinit(pin) { }
+/** Thin PWM (hal/pwm-pin.ts): set pulse width in ns against the constructed
+ *  period. The first use also applies the construction period
+ *  (pwm_set_dt with an idle pulse), then pwm_set_pulse_dt. */
+export function pwmSetPulse(pin, periodNs, pulseNs, controller = '', channel = -1) { }
+/** Thin PWM duty sugar: pulse = duty(0.0–1.0) × periodNs — one
+ *  pwm_set_pulse_dt call, no 0–255 scaling. */
+export function pwmSetDuty(pin, periodNs, duty, controller = '', channel = -1) { }
+/** Thin PWM: change the period at runtime (pwm_set_dt; the pulse resets to
+ *  idle — Zephyr 4.4 has no period-only setter). */
+export function pwmSetPeriod(pin, periodNs, controller = '', channel = -1) { }
 // ---------------------------------------------------------------------------
 // ADC — analog-to-digital conversion
 // ---------------------------------------------------------------------------
-/** Read analog value from a pin. */
-export function adcRead(pin) { return 0; }
-/** Read analog voltage from a pin (ADC value converted to voltage). */
-export function adcReadVoltage(pin) { return 0; }
-/** Set the analog reference. */
-export function adcSetReference(ref) { }
+/** Thin ADC (hal/adc-pin.ts): raw read with construction-time gain/reference
+ *  tokens ("ADC.GAIN_1_4" / "ADC.REF_INTERNAL"); empty strings
+ *  mean "use the chip descriptor's defaults". */
+export function adcReadRaw(pin, gain, reference, channel = -1, device = '', pinctrl = '') { return 0; }
+/** Thin ADC: millivolts read (adc_raw_to_millivolts) with the same
+ *  construction-time gain/reference tokens. */
+export function adcReadMv(pin, gain, reference, channel = -1, device = '', pinctrl = '') { return 0; }
 // ---------------------------------------------------------------------------
 // Interrupts
 // ---------------------------------------------------------------------------
-/** Attach an interrupt handler to a pin. */
-export function interruptAttach(pin, handler, mode) { }
+/** Thin GPIO interrupts (hal/gpio-pin.ts onInterrupt): attach with Zephyr
+ *  INT_* tokens ("GPIO.INT_EDGE_FALLING") instead of mode strings. */
+export function interruptAttachFlags(pin, handler, intFlags) { }
 /** Detach an interrupt from a pin. */
 export function interruptDetach(pin) { }
 // ---------------------------------------------------------------------------
-// Tone / audio output
-// ---------------------------------------------------------------------------
-/** Play a tone on a pin at the given frequency, optionally for a duration. */
-export function tonePlay(pin, frequency, duration) { }
-/** Stop tone playback on a pin. */
-export function toneStop(pin) { }
-// ---------------------------------------------------------------------------
 // Timing
 // ---------------------------------------------------------------------------
-/** Delay for the given number of milliseconds. */
-export function delayMs(ms) { }
-/** Delay for the given number of microseconds. */
-export function delayMicro(us) { }
-/** Get milliseconds since boot. */
-export function getMillis() { return 0; }
-/** Get microseconds since boot. */
-export function getMicros() { return 0; }
-/** Get free heap bytes. Architecture-aware: the strategy maps this to the right
- *  symbol per target (ESP.getFreeHeap() on ESP32, __heap_start trick on AVR). */
-export function getFreeHeap() { return 0; }
+/** Time.sleep — yielding sleep in milliseconds (Zephyr: k_msleep). */
+export function timeSleep(ms) { }
+/** Time.now — milliseconds since boot as a double (Zephyr: k_uptime_get). */
+export function timeNow() { return 0; }
+/** Time.nowUs — microseconds since boot as a double, uptime-derived
+ *  (k_uptime_get() * 1000) on every board — uniform, monotonic. */
+export function timeNowUs() { return 0; }
+/** Time.busyWaitUs — spin-wait the given microseconds, no yield (Zephyr: k_busy_wait). */
+export function timeBusyWaitUs(us) { }
 // ---------------------------------------------------------------------------
 // I2C — inter-integrated circuit bus
 // ---------------------------------------------------------------------------
-/** Initialize I2C bus (master mode if no address, slave mode with address). */
-export function i2cBegin(bus, address) { }
-/** Disable I2C bus. */
-export function i2cEnd(bus) { }
-/** Set I2C bus clock speed. */
-export function i2cSetClock(bus, hz) { }
-/** Begin I2C transmission to a slave address. */
-export function i2cBeginTx(bus, address) { }
-/** Write data to I2C bus. */
-export function i2cWrite(bus, data) { }
-/** Write a byte buffer to I2C bus (expands array literals to per-byte writes). */
-export function i2cWriteBuffer(bus, data) { }
-/** End I2C transmission. Returns status. */
-export function i2cEndTx(bus, stop) { return 0; }
-/** Request bytes from I2C slave. */
-export function i2cRequestFrom(bus, address, quantity, stop) { return 0; }
-/** Check if bytes are available from I2C. */
-export function i2cAvailable(bus) { return 0; }
-/** Read a byte from I2C. */
-export function i2cRead(bus) { return 0; }
-/**
- * Drain `count` bytes requested from the I2C bus into a caller-provided buffer.
- * Semantic primitive: lowers to the `i2c.read_buffer` HAL op. The `buffer`
- * argument is emitted as a placeholder (`__HAL_READ_BUF__`) that the var-init
- * transformer rewrites to the caller's own buffer variable, so bytes land in
- * the `uint8_t data[N]` declared in user scope — NOT an internal temp that
- * decays to a pointer on return. Keeps `data.length` / `data[i]` valid.
- */
-export function i2cReadBuffer(bus, count, buffer) { }
+// Thin I2C device (hal/i2c-target.ts): Zephyr register verbs. `hz` (0 =
+// leave the bus at its current speed) applies once via a guarded
+// i2c_configure on first use.
+export function i2cRegWrite(bus, address, hz, reg, value) { }
+export function i2cRegRead(bus, address, hz, reg) { return 0; }
+export function i2cRegUpdate(bus, address, hz, reg, mask, value) { }
+export function i2cDevWrite(bus, address, hz, data) { }
 // ---------------------------------------------------------------------------
 // SPI — serial peripheral interface
 // ---------------------------------------------------------------------------
-/** Initialize SPI bus. */
-export function spiBegin(bus) { }
-/** Disable SPI bus. */
-export function spiEnd(bus) { }
-/** Transfer data on SPI bus. */
-export function spiTransfer(bus, data) { return 0; }
-/** Begin SPI transaction with settings. */
-export function spiBeginTx(bus, settings) { }
-/** End SPI transaction. */
-export function spiEndTx(bus) { }
-/** Set SPI chip-select pin LOW. */
-export function spiCsLow(pin) { }
-/** Set SPI chip-select pin HIGH. */
-export function spiCsHigh(pin) { }
-/**
- * Read `count` bytes from the SPI bus into a caller-provided buffer by clocking
- * dummy (0x00) transfers. Semantic primitive: lowers to the `spi.read_buffer`
- * HAL op (per-byte `bus.transfer(0)` read loop). The `buffer` placeholder is
- * rewritten to the caller's variable. Mirrors i2cReadBuffer. The caller is
- * responsible for asserting/de-asserting chip-select around it.
- */
-export function spiReadBuffer(bus, count, buffer) { }
-/** Set SPI data mode. */
-export function spiSetMode(bus, mode) { }
-/** Set SPI bit order. */
-export function spiSetBitOrder(bus, order) { }
-// ---------------------------------------------------------------------------
-// UART — serial communication
-// ---------------------------------------------------------------------------
-/** Initialize serial port with baud rate. */
-export function uartBegin(port, baud) { }
-/** Disable serial port. */
-export function uartEnd(port) { }
-/** Print value to serial. */
-export function uartPrint(port, value) { }
-/** Print value with newline to serial. */
-export function uartPrintln(port, value) { }
-/** printf-style formatted print to serial. */
-export function uartPrintf(port, format, args) { }
-/** Write raw data to serial. */
-export function uartWrite(port, data) { }
-/** Read a byte from serial. */
-export function uartRead(port) { return 0; }
-/** Peek at next byte from serial without consuming. */
-export function uartPeek(port) { return 0; }
-/** Check if bytes are available from serial. */
-export function uartAvailable(port) { return 0; }
-/** Flush serial output. */
-export function uartFlush(port) { }
-// ---------------------------------------------------------------------------
-// Pulse measurement
-// ---------------------------------------------------------------------------
-/** Measure pulse duration on a pin. */
-export function pulseIn_(pin, value, timeout) { return 0; }
-/** Measure long pulse using high-precision timer. */
-export function pulseInLong_(pin, value) { return 0; }
-// ---------------------------------------------------------------------------
-// Shift register
-// ---------------------------------------------------------------------------
-/** Shift a byte out to a pin. */
-export function shiftOut_(dataPin, clockPin, bitOrder, value) { }
-/** Shift a byte in from a pin. */
-export function shiftIn_(dataPin, clockPin, bitOrder) { return 0; }
+// ---------------------------------------------------------------------------
+// USB — CDC-ACM serial over the USB connector (device stack)
+// ---------------------------------------------------------------------------
+/** Enable the USB device + open the CDC serial port with a baud hint. */
+export function usbBegin(port) { }
+/** Disable the CDC serial port. */
+export function usbEnd(port) { }
+/** Print value to the USB serial port. */
+export function usbPrint(port, value) { }
+/** Print value with newline to the USB serial port. */
+export function usbPrintln(port, value) { }
+/** Read a byte from the USB serial port (-1 if none). */
+export function usbRead(port) { return 0; }
+/** Check if bytes are available from the USB serial port. */
+export function usbAvailable(port) { return 0; }
+/** True when the host has opened the port (DTR asserted). */
+export function usbConnected(port) { return false; }
+/** Thin waitLinked(): bounded DTR poll in the shim. */
+export function usbWaitReady(port, timeoutMs) { return false; }
 // ---------------------------------------------------------------------------
 // Board constant resolution
 // ---------------------------------------------------------------------------
-/** Write a value to a DAC pin. */
-export function dacWrite(pin, value) { }
+/** Thin DAC (hal/dac-pin.ts): raw dac_write_value with a construction-time
+ *  resolution (0 = the chip descriptor's channel resolution). */
+export function dacWriteValue(pin, value, resolution) { }
 // ---------------------------------------------------------------------------
 // Watchdog timer (WDT)
 // ---------------------------------------------------------------------------
-/** Enable the watchdog timer with the given timeout (string preset or number). */
-export function wdtEnable(timeout) { }
-/** Reset (kick) the watchdog timer. */
-export function wdtReset() { }
 /** Disable the watchdog timer. */
 export function wdtDisable() { }
+/** Thin Watchdog (hal/watchdog.ts): arm with the construction timeout in ms
+ *  (wdt_install_timeout + wdt_setup). */
+export function wdtSetup(timeoutMs) { }
+/** Thin Watchdog: feed (wdt_feed). */
+export function wdtFeed() { }
+/** Thin Counter (hal/counter.ts): register the alarm handler. */
+export function counterOnAlarm(instance, handler) { }
+/** Thin Counter: apply hz as the top value and start (counter_start). */
+export function counterStart(instance, hz) { }
+/** Thin Counter: stop (counter_stop). */
+export function counterStop(instance) { }
+// Thin SPI device (hal/spi-target.ts): the op carries the construction facts
+// (cs pin, hz, mode) so the shim state block and overlay child node derive
+// from op facts alone (the sensor discipline). `rx` is the caller's buffer
+// identifier ('' = write-only).
+export function spiTransceiveDt(bus, cs, hz, mode, tx, rx) { }
+export function spiWriteDt(bus, cs, hz, mode, tx) { }
+/** SPITarget.readReg sugar: one-byte register read via spi_transceive_dt
+ *  against an INTERNAL buffer — no caller array needed. */
+export function spiReadReg(bus, cs, hz, mode, reg) { return 0; }
+// Thin UART (hal/uart-port.ts): TX is poll-based with the construction baud
+// applied once (guarded uart_configure); RX is interrupt-backed into a
+// construction-sized ring (armed on first receive call). `ring` sizes the
+// shim's static buffer and rides every RX op (self-contained-op discipline).
+export function uartPollWrite(port, baud, data) { }
+export function uartRxAvailable(port, ring) { return 0; }
+export function uartRxPeek(port, ring) { return 0; }
+export function uartRxRead(port, ring) { return 0; }
+// Thin Thread (hal/thread.ts): create + schedule (k_thread_create, K_NO_WAIT).
+// The handler is the callback-registered entry function name.
+export function threadStart(index, stackBytes, priority, handler) { }
+/** Thin Thread: block until exit (k_thread_join, K_FOREVER). */
+export function threadJoin(index) { }
 /** Resolve a board definition path to a compile-time constant. */
 export function boardResolve(path) { return undefined; }
-// ---------------------------------------------------------------------------
-// Power — MCU power states and clock frequency
-// ---------------------------------------------------------------------------
-/** Enter deep sleep for the given duration (ms). Architecture-aware: the
- *  strategy emits the right call per target (esp_deep_sleep on ESP32, a
- *  not-supported comment elsewhere). */
-export function powerDeepSleep(ms) { }
-/** Enter light sleep. Architecture-aware. */
-export function powerLightSleep() { }
-/** Set the CPU frequency (MHz). */
-export function powerSetCpuFrequency(mhz) { }
-/** Enter deep sleep until `pin` reaches `level` (pin wakeup). Architecture-aware:
- *  ext0 on Xtensa (RTC pins), gpio-wakeup on RISC-V. */
-export function powerDeepSleepPin(pin, level) { }
+export function fsReadText(path) { return ""; }
+export function fsWriteText(path, content) { }
+export function fsExists(path) { return false; }
+export function fsRemove(path) { return false; }
+export function mqttConnect(brokerUri, clientId) { return false; }
+export function mqttOnMessage(handler) { }
+export function mqttSubscribe(topic) { }
+export function mqttPublish(topic, data) { }
+export function mqttConnected() { return false; }
+export function mqttDisconnect() { }
 // ---------------------------------------------------------------------------
 // Preferences (NVS-backed key/value store)
 // ---------------------------------------------------------------------------
-export function preferencesBegin(namespace, readOnly) { }
-export function preferencesEnd() { }
-export function preferencesClear() { }
-export function preferencesRemove(key) { }
-export function preferencesPutInt(key, value) { }
-export function preferencesGetInt(key, defaultValue) { return 0; }
-export function preferencesPutUInt(key, value) { }
-export function preferencesGetUInt(key, defaultValue) { return 0; }
-export function preferencesPutBool(key, value) { }
-export function preferencesGetBool(key, defaultValue) { return false; }
-export function preferencesPutFloat(key, value) { }
-export function preferencesGetFloat(key, defaultValue) { return 0; }
-export function preferencesPutString(key, value) { }
-export function preferencesGetString(key, defaultValue) { return ""; }
-export function wifiConnect(ssid, password, timeoutMs) { return false; }
+export function preferencesClear(ns) { }
+export function preferencesRemove(ns, key) { }
+export function preferencesPutInt(ns, key, value) { }
+export function preferencesGetInt(ns, key, defaultValue) { return 0; }
+export function preferencesPutBool(ns, key, value) { }
+export function preferencesGetBool(ns, key, defaultValue) { return false; }
+export function preferencesPutFloat(ns, key, value) { }
+export function preferencesGetFloat(ns, key, defaultValue) { return 0; }
+export function preferencesPutString(ns, key, value) { }
+export function preferencesGetString(ns, key, defaultValue) { return ""; }
 export function wifiConnectStart(ssid, password) { }
+/** Join with the station's construction facts (the thin WiFi.join). */
+export function wifiJoin(ssid, psk, security, channel, band, timeoutMs, ps, ipAddr, gateway, netmask) { return false; }
 export function wifiDisconnect() { }
-export function wifiStatus() { return 0; }
 export function wifiIsConnected() { return false; }
 export function wifiLocalIp() { return ""; }
 export function wifiRssi() { return 0; }
-export function wifiMac() { return ""; }
-export function wifiSetHostname(name) { }
-export function wifiSetStaticIp(ip, gateway, subnet, dns) { }
-export function wifiSetAutoReconnect(enabled) { }
-export function wifiSetPowerSave(mode) { }
-export function wifiSetTxPower(dbm) { }
+export function wifiMac() { return 0; }
 export function wifiOnEvent(event, handler) { }
 export function wifiApStart(ssid, password, channel, hidden, maxClients) { return false; }
 export function wifiApStop() { }
-export function wifiApClientCount() { return 0; }
-export function wifiApIp() { return ""; }
-export function wifiApSetChannel(channel) { }
-export function wifiApSetHidden(hidden) { }
-export function wifiApSetMaxClients(maxClients) { }
 export function wifiScan() { return 0; }
-export function wifiScanStart() { }
 export function wifiScanCount() { return 0; }
 export function wifiScanSsid(index) { return ""; }
 export function wifiScanRssi(index) { return 0; }
-export function wifiScanEncryption(index) { return 0; }
+export function wifiScanEncryption(index) { return ""; }
 export function wifiScanChannel(index) { return 0; }
-export function wifiSaveCredentials(ssid, password) { }
-export function wifiConnectSaved(timeoutMs) { return false; }
-export function wifiClearCredentials() { }
-export function wifiWaitConnected(timeoutMs) { return false; }
-export function wifiWaitDisconnected() { }
 // ---------------------------------------------------------------------------
 // HTTP client
 // ---------------------------------------------------------------------------
 export function httpBegin(method, url) { }
-export function httpReset() { }
 export function httpSetHeader(name, value) { }
 export function httpSetTimeout(ms) { }
 export function httpSetMaxBody(bytes) { }
 export function httpSetBody(data, json) { }
-export function httpSetInsecure() { }
+export function httpSetInsecure(insecure) { }
 export function httpSetCaCert(pem) { }
 export function httpSend() { return false; }
-export function httpSendStart() { }
 export function httpStatus() { return 0; }
 export function httpOk() { return false; }
 export function httpBody() { return ""; }
@@ -301,11 +227,6 @@ export function bleOnDisconnect(handler) { }
 export function bleNotify(index, value) { }
 export function bleIsConnected() { return false; }
 export function bleClientCount() { return 0; }
-export function bleSetName(name) { }
-export function bleUntilConnected(timeoutMs) { return false; }
-export function bleUntilConnectedStart() { }
-export function bleSetTxPower(dbm) { }
-export function bleStatus() { return 0; }
 // ---------------------------------------------------------------------------
 // Raw C++ escape hatch
 // ---------------------------------------------------------------------------
@@ -327,3 +248,20 @@ export function rawCpp(code) { }
 export function rawCppExpr(code) {
     return undefined;
 }
+// ---------------------------------------------------------------------------
+// Sensors — DT-bound peripheral parts (generic catalog)
+//
+// The part identity is a catalog token (SENSOR.<underscored-compatible> from
+// sensor-catalog.generated.ts); the bus/address come from the I2CTarget the
+// Sensor class was constructed with. Zephyr's uniform sensor API backs these —
+// one code shape for every part in the catalog.
+// ---------------------------------------------------------------------------
+/** Fetch a fresh sample from a DT-bound sensor part. Args: part token, bus
+ *  name, bus port (I2C address or SPI CS pin), bus kind ('i2c' | 'spi'),
+ *  SPI clock Hz, SPI mode 0-3, alert pin (-1 = none). */
+export function sensorFetch(part, bus, port, kind, spiHz, spiMode, alertPin) { }
+/** Read one channel (a SENSOR_CHAN_* suffix, see CHAN) from the fetched sample.
+ *  Returns the value as a double (Zephyr's sensor_value val1 + val2/1e6).
+ *  Carries the same construction facts as sensorFetch so either op alone
+ *  yields a complete device. */
+export function sensorGet(part, bus, port, kind, spiHz, spiMode, alertPin, chan) { return 0; }

package/dist/fs.d.ts

@@ -1,33 +1,14 @@
-/**
- * FSClass provides a high-level abstraction for filesystem operations.
- *
- * Lowered to native filesystem HAL ops (fs.*): ESP-IDF mounts an SD card via
- * esp_vfs_fat_sdmmc_mount (FAT on SDMMC/SDSPI); Arduino uses SD.h / LittleFS.
- * The per-framework runtime shim owns the open/read/write/close dance and
- * returns heap strings for readText.
- *
- * The semantic primitives (fsBegin / fsReadText / ...) are resolved to fs.*
- * HAL ops by the transpiler's hal-plugins switch; this class is the
- * ergonomic, type-checking surface.
- */
-export declare class FSClass {
-    static readonly __instance_name = "FS";
-    /** Mount the filesystem. Returns true on success. */
-    begin(): boolean;
-    /** Read a UTF-8 text file into a string. Returns "" if the file is missing
-     *  or unreadable. The returned buffer is caller-owned. */
-    readText(path: string): string;
-    /** Write a string to a file (overwrites). Silently no-ops if the file
+export declare class File {
+    private readonly _path;
+    constructor(path: string);
+    /** Read the file as UTF-8 text. "" when missing/unreadable; the buffer is
+     *  shim-owned until the next read. */
+    read(): string;
+    /** Overwrite the file with `content`. Silently no-ops when the file
      *  cannot be opened for writing. */
-    writeText(path: string, content: string): void;
-    /** True if a file exists at the path. */
-    exists(path: string): boolean;
-    /** Delete a file. Returns true if deleted. */
-    remove(path: string): boolean;
+    write(content: string): void;
+    /** True if the file exists. */
+    exists(): boolean;
+    /** Delete the file. */
+    remove(): void;
 }
-export declare const FS: FSClass;
-export declare function fsBegin(): void;
-export declare function fsReadText(path: string): string;
-export declare function fsWriteText(path: string, content: string): void;
-export declare function fsExists(path: string): boolean;
-export declare function fsRemove(path: string): boolean;

package/dist/fs.js

@@ -1,47 +1,37 @@
-/**
- * FSClass provides a high-level abstraction for filesystem operations.
- *
- * Lowered to native filesystem HAL ops (fs.*): ESP-IDF mounts an SD card via
- * esp_vfs_fat_sdmmc_mount (FAT on SDMMC/SDSPI); Arduino uses SD.h / LittleFS.
- * The per-framework runtime shim owns the open/read/write/close dance and
- * returns heap strings for readText.
- *
- * The semantic primitives (fsBegin / fsReadText / ...) are resolved to fs.*
- * HAL ops by the transpiler's hal-plugins switch; this class is the
- * ergonomic, type-checking surface.
- */
-export class FSClass {
-    /** Mount the filesystem. Returns true on success. */
-    begin() {
-        fsBegin();
-        return true;
+// ---------------------------------------------------------------------------
+// File — the thin persistent-file handle
+//
+// The path is the CONSTRUCTION fact; each verb maps 1:1 onto the Zephyr FS
+// API (littlefs on the board's storage partition, mounted lazily on first
+// use — there is no begin()/mount session):
+//
+//   read()    → the file's text ("" when missing/unreadable; the returned
+//               buffer lives in the shim until the next read)
+//   write(s)  → overwrite the file (no-op when unwritable)
+//   exists()  → the file is present
+//   remove()  → delete the file
+// ----------------------------------------------------------------------------
+import { fsReadText, fsWriteText, fsExists, fsRemove, } from './emit.js';
+export class File {
+    constructor(path) {
+        this._path = path;
     }
-    /** Read a UTF-8 text file into a string. Returns "" if the file is missing
-     *  or unreadable. The returned buffer is caller-owned. */
-    readText(path) {
-        return fsReadText(path);
+    /** Read the file as UTF-8 text. "" when missing/unreadable; the buffer is
+     *  shim-owned until the next read. */
+    read() {
+        return fsReadText(this._path);
     }
-    /** Write a string to a file (overwrites). Silently no-ops if the file
+    /** Overwrite the file with `content`. Silently no-ops when the file
      *  cannot be opened for writing. */
-    writeText(path, content) {
-        fsWriteText(path, content);
+    write(content) {
+        fsWriteText(this._path, content);
     }
-    /** True if a file exists at the path. */
-    exists(path) {
-        return fsExists(path);
+    /** True if the file exists. */
+    exists() {
+        return fsExists(this._path);
     }
-    /** Delete a file. Returns true if deleted. */
-    remove(path) {
-        return fsRemove(path);
+    /** Delete the file. */
+    remove() {
+        fsRemove(this._path);
     }
 }
-FSClass.__instance_name = "FS";
-export const FS = new FSClass();
-// ── Semantic primitives (resolved to fs.* HAL ops by the transpiler) ──
-// These are inert at runtime (tests, type-checking); the cuttlefish transpiler
-// intercepts calls by name and lowers them to typed HAL op IR.
-export function fsBegin() { }
-export function fsReadText(path) { return ""; }
-export function fsWriteText(path, content) { }
-export function fsExists(path) { return false; }
-export function fsRemove(path) { return false; }

package/dist/gpio-pin.d.ts

@@ -0,0 +1,46 @@
+import type { Pin } from './gpio.js';
+export declare class GPIO {
+    static readonly INPUT = 1;
+    static readonly OUTPUT = 2;
+    /** Configure the output buffer's initial level atomically — no
+     *  configure-then-write glitch window. */
+    static readonly OUTPUT_INIT_LOW = 4;
+    static readonly OUTPUT_INIT_HIGH = 8;
+    static readonly PULL_UP = 16;
+    static readonly PULL_DOWN = 32;
+    static readonly OPEN_DRAIN = 64;
+    static readonly OPEN_SOURCE = 128;
+    static readonly DISCONNECTED = 256;
+    static readonly INT_DISABLE = 1;
+    static readonly INT_EDGE_RISING = 2;
+    static readonly INT_EDGE_FALLING = 4;
+    static readonly INT_EDGE_BOTH = 8;
+    static readonly INT_LEVEL_LOW = 16;
+    static readonly INT_LEVEL_HIGH = 32;
+    private readonly _pin;
+    private readonly _flags;
+    /** Construct a configured pin. `flags` is a combination of the GPIO.*
+     *  statics (the transpiler carries the token text; the values are for the
+     *  editor only). The configure applies once, ahead of the first
+     *  set/get/toggle/onInterrupt call. */
+    constructor(pin: number | Pin, flags: number);
+    /** Drive the pin (gpio_pin_set_dt / set_raw). Logical level: on a pin with
+     *  a board dtSpec (LED, BUTTON), true means "active" — the DT node's
+     *  GPIO_ACTIVE_LOW is honored. */
+    set(value: boolean): void;
+    /** Read the pin (gpio_pin_get_dt / get_raw). Logical level. The guarded
+     *  configure is FUSED into the read's lowering (one statement-expression),
+     *  so the pin is correctly configured even when the call sits in a pure
+     *  expression position (if-conditions, comparisons) where a method's
+     *  leading side-effect ops would otherwise be dropped. */
+    get(): boolean;
+    /** Toggle the pin (gpio_pin_toggle_dt — the driver's atomic toggle). */
+    toggle(): void;
+    /** Attach an interrupt (gpio_pin_interrupt_configure_dt +
+     *  gpio_init_callback + gpio_add_callback). `intFlags` is one GPIO.INT_*
+     *  token — Zephyr's names verbatim, covering the level modes the legacy
+     *  onHigh/onLow strings could not express. */
+    onInterrupt(intFlags: number, handler: () => void): void;
+    /** Detach the interrupt (disable + remove callback). */
+    offInterrupt(): void;
+}