@typecad/simulator 0.1.0-alpha.1

package/dist/bus/spi-sim.js

@@ -0,0 +1,202 @@
+// ---------------------------------------------------------------------------
+// @typecad/simulator — SPI bus simulation
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// SimSPIBus
+// ---------------------------------------------------------------------------
+/**
+ * Simulated SPI bus for testing SPI communication.
+ *
+ * Tests register mock devices via `attachDevice()`. When sketch code performs
+ * transfers, the corresponding mock device handles the operation.
+ */
+export class SimSPIBus {
+    constructor() {
+        this.isEnabled = false;
+        this.errorPolicy = 'callback';
+        this._frequency = 4000000;
+        this._mode = 0;
+        this._bitOrder = 'msb';
+        this._devices = new Map();
+        this._inTransaction = false;
+        /** Track all operations for test assertions. */
+        this._log = [];
+    }
+    // --- ISPIBus methods ---
+    begin() {
+        this.isEnabled = true;
+    }
+    end() {
+        // In simulation, ending the bus disables it without releasing mock devices.
+        this.isEnabled = false;
+    }
+    setMode(mode) {
+        this._mode = mode;
+    }
+    setBitOrder(order) {
+        this._bitOrder = order;
+    }
+    setFrequency(hz) {
+        this._frequency = hz;
+    }
+    beginTransaction(_settings) {
+        this._inTransaction = true;
+    }
+    endTransaction() {
+        this._inTransaction = false;
+    }
+    transfer(data) {
+        const mosiData = typeof data === 'number' ? [data] : Array.from(data);
+        const timestamp = Date.now();
+        // Bus-level transfer (no CS pin) — log but no device interaction
+        this._log.push({ operation: 'transfer', data: mosiData, timestamp });
+        return new Uint8Array(mosiData.length);
+    }
+    write(data) {
+        const mosiData = typeof data === 'number' ? [data] : Array.from(data);
+        const timestamp = Date.now();
+        this._log.push({ operation: 'write', data: mosiData, timestamp });
+    }
+    write16(value) {
+        const msb = (value >> 8) & 0xFF;
+        const lsb = value & 0xFF;
+        this.write(new Uint8Array([msb, lsb]));
+    }
+    device(chipSelect) {
+        return new SimSPIDevice(this, chipSelect);
+    }
+    // --- Simulation helpers ---
+    /**
+     * Attach a mock SPI device for the given chip-select pin.
+     */
+    attachDevice(csPin, device) {
+        this._devices.set(String(csPin.number), device);
+    }
+    /**
+     * Remove a mock device.
+     */
+    detachDevice(csPin) {
+        this._devices.delete(String(csPin.number));
+    }
+    /**
+     * Get the operation log for test assertions.
+     */
+    getLog() {
+        return this._log;
+    }
+    /**
+     * Clear the operation log.
+     */
+    clearLog() {
+        this._log = [];
+    }
+    onError(_handler) {
+        // No-op in simulator
+    }
+    /**
+     * Reset all state.
+     */
+    reset() {
+        this._devices.clear();
+        this._log = [];
+        this.isEnabled = false;
+        this._inTransaction = false;
+        this._frequency = 4000000;
+        this._mode = 0;
+        this._bitOrder = 'msb';
+    }
+    // --- Internal ---
+    /** @internal */
+    _getDevice(csKey) {
+        return this._devices.get(csKey);
+    }
+    /** @internal */
+    _logOperation(op) {
+        this._log.push(op);
+    }
+}
+// ---------------------------------------------------------------------------
+// SimSPIDevice — implements ISPIDevice
+// ---------------------------------------------------------------------------
+class SimSPIDevice {
+    constructor(bus, chipSelect) {
+        this.bus = bus;
+        this._simBus = bus;
+        this.chipSelect = chipSelect;
+    }
+    transfer(data) {
+        const csKey = String(this.chipSelect.number);
+        const mosiData = typeof data === 'number' ? [data] : Array.from(data);
+        const timestamp = Date.now();
+        const device = this._simBus._getDevice(csKey);
+        if (!device) {
+            this._simBus._logOperation({ operation: 'transfer', data: mosiData, timestamp });
+            return new Uint8Array(0);
+        }
+        const misoData = device.transfer(mosiData);
+        this._simBus._logOperation({ operation: 'transfer', data: mosiData, response: misoData, timestamp });
+        return new Uint8Array(misoData);
+    }
+    write(data) {
+        const csKey = String(this.chipSelect.number);
+        const dataArray = typeof data === 'number' ? [data] : Array.from(data);
+        const timestamp = Date.now();
+        const device = this._simBus._getDevice(csKey);
+        if (!device) {
+            this._simBus._logOperation({ operation: 'write', data: dataArray, timestamp });
+            return;
+        }
+        if (device.write) {
+            // Write without register — use register 0 as placeholder
+            device.write(0, dataArray);
+        }
+        else {
+            device.transfer(dataArray);
+        }
+        this._simBus._logOperation({ operation: 'write', data: dataArray, timestamp });
+    }
+    read(count) {
+        const csKey = String(this.chipSelect.number);
+        const timestamp = Date.now();
+        const device = this._simBus._getDevice(csKey);
+        if (!device) {
+            this._simBus._logOperation({ operation: 'read', count, timestamp });
+            return new Uint8Array(0);
+        }
+        // Send dummy bytes to read
+        const misoData = device.transfer(new Array(count).fill(0));
+        this._simBus._logOperation({ operation: 'read', count, data: misoData, timestamp });
+        return new Uint8Array(misoData);
+    }
+    writeRegister(register, data) {
+        const csKey = String(this.chipSelect.number);
+        const dataArray = typeof data === 'number' ? [data] : Array.from(data);
+        const timestamp = Date.now();
+        const device = this._simBus._getDevice(csKey);
+        if (!device) {
+            this._simBus._logOperation({ operation: 'write', register, data: dataArray, timestamp });
+            return;
+        }
+        if (device.write) {
+            device.write(register, dataArray);
+        }
+        else {
+            device.transfer([register, ...dataArray]);
+        }
+        this._simBus._logOperation({ operation: 'write', register, data: dataArray, timestamp });
+    }
+    readRegister(register, count) {
+        const csKey = String(this.chipSelect.number);
+        const timestamp = Date.now();
+        const device = this._simBus._getDevice(csKey);
+        if (!device) {
+            this._simBus._logOperation({ operation: 'read', register, count, timestamp });
+            return new Uint8Array(0);
+        }
+        const data = device.readRegister
+            ? device.readRegister(register, count)
+            : device.transfer([register, ...new Array(count).fill(0)]).slice(1);
+        this._simBus._logOperation({ operation: 'read', register, count, data, timestamp });
+        return new Uint8Array(data);
+    }
+}

package/dist/contracts.d.ts

@@ -0,0 +1,223 @@
+import type { DigitalValue, AnalogValue, InterruptHandler, I2CAddress } from '@typecad/hal';
+import type { SPIMode, SPIBitOrder, SPISettings } from '@typecad/hal';
+export interface PinCapabilityFlags {
+    digitalInput: boolean;
+    digitalOutput: boolean;
+    analogInput: boolean;
+    /** DAC output */
+    analogOutput: boolean;
+    pwm: boolean;
+    interrupt: boolean;
+    pullUp: boolean;
+    pullDown: boolean;
+    touch: boolean;
+    openDrain: boolean;
+}
+export interface IToneAttachment {
+    for(duration: number): void;
+}
+export interface InterruptOptions {
+    debounce?: number;
+}
+export interface BasePin {
+    readonly number: number;
+    readonly gpio: number;
+    readonly capabilities: PinCapabilityFlags;
+    read(): DigitalValue;
+    isHigh(): boolean;
+    isLow(): boolean;
+    write(value: DigitalValue): void;
+    high(): void;
+    low(): void;
+    toggle(): void;
+    pulse(duration: number): void;
+    tone(frequency: number): IToneAttachment;
+    noTone(): void;
+    inputPullUp(): void;
+    inputPullDown?(): void;
+    outputOpenDrain(initial?: DigitalValue): void;
+    asOutput(initial?: DigitalValue): IOutputModePin;
+    asInput(): IInputModePin;
+    asInputPullUp(): IInputModePin;
+    pwm?(percent: number): void;
+    getPwmFrequency?(): number;
+    getPwmResolution?(): number;
+    readAnalog?(): AnalogValue;
+    readVoltage?(): number;
+    setAnalogReference?(voltage: number): void;
+    getAnalogResolution?(): number;
+    onRising?(handler: InterruptHandler, options?: InterruptOptions): void;
+    onFalling?(handler: InterruptHandler, options?: InterruptOptions): void;
+    onChange?(handler: InterruptHandler, options?: InterruptOptions): void;
+    offInterrupts?(): void;
+    waitForRising(timeout?: number): Promise<void>;
+    waitForFalling(timeout?: number): Promise<void>;
+}
+export interface IOutputModePin {
+    readonly number: number;
+    readonly gpio: number;
+    readonly capabilities: PinCapabilityFlags;
+    write(value: DigitalValue): void;
+    high(): void;
+    low(): void;
+    toggle(): void;
+    pulse(duration: number): void;
+    tone(frequency: number): IToneAttachment;
+    noTone(): void;
+    pwm?(percent: number): void;
+    getPwmFrequency?(): number;
+    getPwmResolution?(): number;
+    asOutput(initial?: DigitalValue): IOutputModePin;
+    asInput(): IInputModePin;
+    asInputPullUp(): IInputModePin;
+    inputPullUp(): void;
+    inputPullDown?(): void;
+    outputOpenDrain(initial?: DigitalValue): void;
+}
+export interface IInputModePin {
+    readonly number: number;
+    readonly gpio: number;
+    readonly capabilities: PinCapabilityFlags;
+    read(): DigitalValue;
+    isHigh(): boolean;
+    isLow(): boolean;
+    readAnalog?(): AnalogValue;
+    readVoltage?(): number;
+    setAnalogReference?(voltage: number): void;
+    getAnalogResolution?(): number;
+    onRising?(handler: InterruptHandler, options?: InterruptOptions): void;
+    onFalling?(handler: InterruptHandler, options?: InterruptOptions): void;
+    onChange?(handler: InterruptHandler, options?: InterruptOptions): void;
+    offInterrupts?(): void;
+    waitForRising(timeout?: number): Promise<void>;
+    waitForFalling(timeout?: number): Promise<void>;
+    asOutput(initial?: DigitalValue): IOutputModePin;
+    asInput(): IInputModePin;
+    asInputPullUp(): IInputModePin;
+    inputPullUp(): void;
+    inputPullDown?(): void;
+    outputOpenDrain(initial?: DigitalValue): void;
+}
+/** Pin with PWM output capability. */
+export type PWMPin = BasePin & {
+    pwm: NonNullable<BasePin['pwm']>;
+};
+/** Pin with analog input capability. */
+export type AnalogPin = BasePin & {
+    readAnalog: NonNullable<BasePin['readAnalog']>;
+};
+/** Pin with interrupt capability. */
+export type InterruptPin = BasePin & {
+    onRising: NonNullable<BasePin['onRising']>;
+};
+export declare function hasPWM(pin: unknown): pin is PWMPin;
+export declare function hasAnalogInput(pin: unknown): pin is AnalogPin;
+export declare function hasInterrupt(pin: unknown): pin is InterruptPin;
+export declare function assertPWM(pin: BasePin, message?: string): asserts pin is PWMPin;
+export declare function assertAnalog(pin: BasePin, message?: string): asserts pin is AnalogPin;
+export declare function assertInterrupt(pin: BasePin, message?: string): asserts pin is InterruptPin;
+export type ErrorPolicy = 'throw' | 'callback' | 'silent';
+export declare enum I2CStatus {
+    SUCCESS = 0,
+    DATA_TOO_LONG = 1,
+    NACK_ON_ADDRESS = 2,
+    NACK_ON_DATA = 3,
+    OTHER_ERROR = 4,
+    PARTIAL_READ = 5
+}
+export interface II2CDeviceAccessor {
+    readonly address: I2CAddress;
+    readByte(register: number): number;
+    readBytes(register: number, count: number): Uint8Array;
+    writeByte(register: number, value: number): void;
+    writeBytes(register: number, data: Uint8Array | number[]): void;
+}
+export interface II2CBus {
+    readonly busNumber: number;
+    readonly isEnabled: boolean;
+    begin(): void;
+    begin(address: I2CAddress): void;
+    end(): void;
+    setClock(hz: number): void;
+    device(address: I2CAddress): II2CDeviceAccessor;
+    onError(handler: (status: I2CStatus, address: I2CAddress, operation: 'read' | 'write') => void): void;
+    errorPolicy: ErrorPolicy;
+    recover(): boolean;
+}
+export declare enum SPIStatus {
+    SUCCESS = 0,
+    NOT_INITIALIZED = 1,
+    TRANSFER_FAILED = 2,
+    INVALID_CONFIG = 3,
+    TIMEOUT = 4,
+    DEVICE_ERROR = 5
+}
+export interface ISPIDevice {
+    readonly chipSelect: BasePin;
+    transfer(data: number | Uint8Array): Uint8Array;
+    write(data: number | Uint8Array): void;
+    read(count: number): Uint8Array;
+    writeRegister(register: number, data: number | Uint8Array): void;
+    readRegister(register: number, count: number): Uint8Array;
+}
+export interface ISPIBus {
+    readonly isEnabled: boolean;
+    begin(): void;
+    end(): void;
+    setMode(mode: SPIMode): void;
+    setBitOrder(order: SPIBitOrder): void;
+    setFrequency(hz: number): void;
+    beginTransaction(settings: SPISettings): void;
+    endTransaction(): void;
+    device(chipSelect: BasePin): ISPIDevice;
+    onError(handler: (status: SPIStatus, operation: 'transfer' | 'read' | 'write') => void): void;
+    errorPolicy: ErrorPolicy;
+}
+export declare enum UARTStatus {
+    SUCCESS = 0,
+    NOT_INITIALIZED = 1,
+    TIMEOUT = 2,
+    BUFFER_OVERFLOW = 3,
+    OVERRUN_ERROR = 4,
+    PARITY_ERROR = 5,
+    FRAMING_ERROR = 6,
+    BREAK_DETECTED = 7,
+    WRITE_FAILED = 8,
+    READ_FAILED = 9
+}
+export interface UARTStatusInfo {
+    available: number;
+    writeAvailable: number;
+    overrunError: boolean;
+    parityError: boolean;
+    framingError: boolean;
+    breakDetected: boolean;
+}
+export interface IUARTBus {
+    readonly uartNumber: number;
+    readonly baudRate: number;
+    readonly isEnabled: boolean;
+    begin(baud: number): void;
+    end(): void;
+    read(): number;
+    peek(): number;
+    readLine(): string;
+    readBytes(count: number): Uint8Array;
+    readString(): string;
+    available(): number;
+    write(data: number | Uint8Array | string): number;
+    flush(): void;
+    getStatus(): UARTStatusInfo;
+    clearErrors(): void;
+    onReceive(callback: (bytesAvailable: number) => void): void;
+    onTransmitComplete(callback: () => void): void;
+    onError(callback: (status: UARTStatus) => void): void;
+    errorPolicy: ErrorPolicy;
+}
+export interface ISerialPort extends IUARTBus {
+    print(...args: unknown[]): void;
+    println(...args: unknown[]): void;
+    printf(format: string, ...args: unknown[]): void;
+    isConnected(): boolean;
+    waitForConnection(timeout?: number): Promise<void>;
+}

package/dist/contracts.js

@@ -0,0 +1,87 @@
+// ---------------------------------------------------------------------------
+// @typecad/simulator — Runtime contract interfaces
+//
+// These types define the runtime contracts that @typecad/simulator's simulated
+// peripheral classes implement (SimDigitalPin, SimI2CBus, SimSPIBus,
+// SimSerialPort, ...). They were relocated here from @typecad/hal so that HAL
+// contains only its transpiler-shim surface, and the simulator owns the
+// hierarchy that matches its job (real behavioral objects, not IR emitters).
+//
+// Primitive aliases that the contracts still reference (DigitalValue,
+// AnalogValue, InterruptHandler) and the protocol-shape types (I2CAddress,
+// SPIMode, SPIBitOrder, SPISettings) remain in @typecad/hal and are imported
+// below. The dependency direction is simulator → hal (already established).
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Capability type guards and assertions
+// ---------------------------------------------------------------------------
+function isBasePin(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'number' in value &&
+        'gpio' in value);
+}
+export function hasPWM(pin) {
+    return isBasePin(pin) && 'pwm' in pin && typeof pin.pwm === 'function';
+}
+export function hasAnalogInput(pin) {
+    return isBasePin(pin) && 'readAnalog' in pin && typeof pin.readAnalog === 'function';
+}
+export function hasInterrupt(pin) {
+    return isBasePin(pin) && 'onRising' in pin && typeof pin.onRising === 'function';
+}
+export function assertPWM(pin, message) {
+    if (!hasPWM(pin)) {
+        throw new Error(message ?? 'Pin does not support PWM');
+    }
+}
+export function assertAnalog(pin, message) {
+    if (!hasAnalogInput(pin)) {
+        throw new Error(message ?? 'Pin does not support analog input');
+    }
+}
+export function assertInterrupt(pin, message) {
+    if (!hasInterrupt(pin)) {
+        throw new Error(message ?? 'Pin does not support interrupts');
+    }
+}
+// ---------------------------------------------------------------------------
+// I2C types
+// ---------------------------------------------------------------------------
+export var I2CStatus;
+(function (I2CStatus) {
+    I2CStatus[I2CStatus["SUCCESS"] = 0] = "SUCCESS";
+    I2CStatus[I2CStatus["DATA_TOO_LONG"] = 1] = "DATA_TOO_LONG";
+    I2CStatus[I2CStatus["NACK_ON_ADDRESS"] = 2] = "NACK_ON_ADDRESS";
+    I2CStatus[I2CStatus["NACK_ON_DATA"] = 3] = "NACK_ON_DATA";
+    I2CStatus[I2CStatus["OTHER_ERROR"] = 4] = "OTHER_ERROR";
+    I2CStatus[I2CStatus["PARTIAL_READ"] = 5] = "PARTIAL_READ";
+})(I2CStatus || (I2CStatus = {}));
+// ---------------------------------------------------------------------------
+// SPI types
+// ---------------------------------------------------------------------------
+export var SPIStatus;
+(function (SPIStatus) {
+    SPIStatus[SPIStatus["SUCCESS"] = 0] = "SUCCESS";
+    SPIStatus[SPIStatus["NOT_INITIALIZED"] = 1] = "NOT_INITIALIZED";
+    SPIStatus[SPIStatus["TRANSFER_FAILED"] = 2] = "TRANSFER_FAILED";
+    SPIStatus[SPIStatus["INVALID_CONFIG"] = 3] = "INVALID_CONFIG";
+    SPIStatus[SPIStatus["TIMEOUT"] = 4] = "TIMEOUT";
+    SPIStatus[SPIStatus["DEVICE_ERROR"] = 5] = "DEVICE_ERROR";
+})(SPIStatus || (SPIStatus = {}));
+// ---------------------------------------------------------------------------
+// UART types
+// ---------------------------------------------------------------------------
+export var UARTStatus;
+(function (UARTStatus) {
+    UARTStatus[UARTStatus["SUCCESS"] = 0] = "SUCCESS";
+    UARTStatus[UARTStatus["NOT_INITIALIZED"] = 1] = "NOT_INITIALIZED";
+    UARTStatus[UARTStatus["TIMEOUT"] = 2] = "TIMEOUT";
+    UARTStatus[UARTStatus["BUFFER_OVERFLOW"] = 3] = "BUFFER_OVERFLOW";
+    UARTStatus[UARTStatus["OVERRUN_ERROR"] = 4] = "OVERRUN_ERROR";
+    UARTStatus[UARTStatus["PARITY_ERROR"] = 5] = "PARITY_ERROR";
+    UARTStatus[UARTStatus["FRAMING_ERROR"] = 6] = "FRAMING_ERROR";
+    UARTStatus[UARTStatus["BREAK_DETECTED"] = 7] = "BREAK_DETECTED";
+    UARTStatus[UARTStatus["WRITE_FAILED"] = 8] = "WRITE_FAILED";
+    UARTStatus[UARTStatus["READ_FAILED"] = 9] = "READ_FAILED";
+})(UARTStatus || (UARTStatus = {}));

package/dist/gpio/analog-pin-sim.d.ts

@@ -0,0 +1,40 @@
+import type { AnalogPin } from '../contracts.js';
+import type { AnalogValue } from '@typecad/hal';
+import { SimDigitalPin } from './digital-pin-sim.js';
+/**
+ * Simulated analog input pin.
+ *
+ * Extends SimDigitalPin with analog read capabilities.
+ * Tests can inject values via `injectValue()` and verify readings.
+ *
+ * - `read()` returns a digital boolean (HIGH if above half-scale).
+ * - `readAnalog()` returns the raw ADC value.
+ */
+export declare class SimAnalogPin extends SimDigitalPin implements AnalogPin {
+    private _analogValue;
+    private _voltage;
+    private _reference;
+    private _resolution;
+    constructor(pinNum: number);
+    /** Convenience: set pin to analog input mode. */
+    analog(): void;
+    readAnalog(): AnalogValue;
+    readVoltage(): number;
+    setAnalogReference(voltage: number): void;
+    getAnalogResolution(): number;
+    /**
+     * Inject an analog value (e.g., sensor reading).
+     * Also updates the digital read state based on threshold.
+     * @param value - Raw ADC value (0 to 2^resolution - 1)
+     */
+    injectValue(value: AnalogValue): void;
+    /**
+     * Inject a voltage directly. Converts to ADC value based on resolution.
+     */
+    injectVoltage(voltage: number): void;
+    /**
+     * Set the ADC resolution in bits.
+     */
+    setResolution(bits: number): void;
+    reset(): void;
+}

package/dist/gpio/analog-pin-sim.js

@@ -0,0 +1,75 @@
+// ---------------------------------------------------------------------------
+// @typecad/simulator — Simulated analog input pin
+// ---------------------------------------------------------------------------
+import { SimDigitalPin } from './digital-pin-sim.js';
+/**
+ * Simulated analog input pin.
+ *
+ * Extends SimDigitalPin with analog read capabilities.
+ * Tests can inject values via `injectValue()` and verify readings.
+ *
+ * - `read()` returns a digital boolean (HIGH if above half-scale).
+ * - `readAnalog()` returns the raw ADC value.
+ */
+export class SimAnalogPin extends SimDigitalPin {
+    constructor(pinNum) {
+        super(pinNum, { analogInput: true });
+        this._analogValue = 0;
+        this._voltage = 0;
+        this._reference = 5.0; // Default 5V reference
+        this._resolution = 10; // Default 10-bit (0-1023)
+    }
+    // --- AnalogPin capability methods ---
+    /** Convenience: set pin to analog input mode. */
+    analog() {
+        this.asInput();
+    }
+    readAnalog() {
+        return this._analogValue;
+    }
+    readVoltage() {
+        return this._voltage;
+    }
+    setAnalogReference(voltage) {
+        this._reference = voltage;
+    }
+    getAnalogResolution() {
+        return this._resolution;
+    }
+    // --- Simulation helpers ---
+    /**
+     * Inject an analog value (e.g., sensor reading).
+     * Also updates the digital read state based on threshold.
+     * @param value - Raw ADC value (0 to 2^resolution - 1)
+     */
+    injectValue(value) {
+        this._analogValue = value;
+        // Calculate voltage from ADC value
+        const maxAdc = (1 << this._resolution) - 1;
+        this._voltage = (value / maxAdc) * this._reference;
+        // Update digital state: HIGH if above half-scale
+        super.injectValue(value > (maxAdc / 2) ? 1 : 0);
+    }
+    /**
+     * Inject a voltage directly. Converts to ADC value based on resolution.
+     */
+    injectVoltage(voltage) {
+        this._voltage = voltage;
+        const maxAdc = (1 << this._resolution) - 1;
+        this._analogValue = Math.round((voltage / this._reference) * maxAdc);
+        super.injectValue(this._analogValue > (maxAdc / 2) ? 1 : 0);
+    }
+    /**
+     * Set the ADC resolution in bits.
+     */
+    setResolution(bits) {
+        this._resolution = bits;
+    }
+    reset() {
+        super.reset();
+        this._analogValue = 0;
+        this._voltage = 0;
+        this._reference = 5.0;
+        this._resolution = 10;
+    }
+}

package/dist/gpio/digital-pin-sim.d.ts

@@ -0,0 +1,68 @@
+import type { BasePin, IToneAttachment, PinCapabilityFlags } from '../contracts.js';
+import { PinMode } from '@typecad/hal';
+import type { DigitalValue } from '@typecad/hal';
+/**
+ * Tracks the history of pin state changes for test assertions.
+ */
+export interface PinStateChange {
+    /** Timestamp (ms since simulation start) */
+    timestamp: number;
+    /** Previous value (0 or 1) */
+    from: number;
+    /** New value (0 or 1) */
+    to: number;
+}
+export declare class SimDigitalPin implements BasePin {
+    readonly number: number;
+    readonly gpio: number;
+    readonly capabilities: PinCapabilityFlags;
+    private _value;
+    private _pinMode;
+    private _history;
+    protected _startTime: number;
+    constructor(pinNum: number, caps?: Partial<PinCapabilityFlags>);
+    getMode(): PinMode;
+    setMode(mode: PinMode): void;
+    has(capability: keyof PinCapabilityFlags): boolean;
+    inputPullUp(): void;
+    inputPullDown(): void;
+    outputOpenDrain(initial?: DigitalValue): void;
+    asOutput(initial?: DigitalValue): any;
+    asInput(): any;
+    asInputPullUp(): any;
+    read(): DigitalValue;
+    isHigh(): boolean;
+    isLow(): boolean;
+    waitForRising(_timeout?: number): Promise<void>;
+    waitForFalling(_timeout?: number): Promise<void>;
+    write(value: DigitalValue): void;
+    high(): void;
+    low(): void;
+    toggle(): void;
+    pulse(_duration: number): void;
+    tone(_frequency: number): IToneAttachment;
+    noTone(): void;
+    stop(): void;
+    /**
+     * Inject a value into this pin (simulates external signal).
+     * Use this in tests to simulate button presses, sensor triggers, etc.
+     */
+    injectValue(value: number): void;
+    /**
+     * Get the history of all state changes on this pin.
+     */
+    getHistory(): readonly PinStateChange[];
+    /**
+     * Clear the state change history.
+     */
+    clearHistory(): void;
+    /**
+     * Get the current value as a plain number (0 or 1).
+     */
+    getBitValue(): number;
+    /**
+     * Reset the pin to its initial state.
+     */
+    reset(): void;
+    private _setBitValue;
+}