@typecad/cuttlefish 0.1.0-alpha.2 → 1.0.0-alpha.11

package/dist/config-schema.d.ts

@@ -11,6 +11,11 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
     board: z.ZodOptional<z.ZodString>;
     contract: z.ZodOptional<z.ZodString>;
     framework: z.ZodOptional<z.ZodString>;
+    /** ESP32 PSRAM type. When set, the framework emits the PSRAM-enabling
+     *  Kconfig/define so canvas allocations prefer external RAM (large scroll
+     *  viewports/lists stop failing on PSRAM targets). No effect on boards
+     *  without PSRAM (the runtime falls back to SRAM then the band renderer). */
+    psram: z.ZodOptional<z.ZodEnum<["opi", "quad"]>>;
     output: z.ZodOptional<z.ZodObject<{
         framework: z.ZodOptional<z.ZodString>;
         optimize: z.ZodOptional<z.ZodEnum<["none", "size", "speed", "balanced"]>>;
@@ -19,14 +24,14 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
         extraFlags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strict", z.ZodTypeAny, {
         framework?: string | undefined;
+        optimize?: "none" | "size" | "speed" | "balanced" | undefined;
         outDir?: string | undefined;
-        optimize?: "size" | "none" | "speed" | "balanced" | undefined;
         defines?: Record<string, string> | undefined;
         extraFlags?: string[] | undefined;
     }, {
         framework?: string | undefined;
+        optimize?: "none" | "size" | "speed" | "balanced" | undefined;
         outDir?: string | undefined;
-        optimize?: "size" | "none" | "speed" | "balanced" | undefined;
         defines?: Record<string, string> | undefined;
         extraFlags?: string[] | undefined;
     }>>;
@@ -41,19 +46,19 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
         buildTarget: z.ZodOptional<z.ZodString>;
         board: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
-        buildTarget?: string | undefined;
-        port?: string | undefined;
         board?: string | undefined;
-        baudRate?: number | undefined;
         include?: string[] | undefined;
+        port?: string | undefined;
+        baudRate?: number | undefined;
         timeout?: number | undefined;
-    }, {
         buildTarget?: string | undefined;
-        port?: string | undefined;
+    }, {
         board?: string | undefined;
-        baudRate?: number | undefined;
         include?: string[] | undefined;
+        port?: string | undefined;
+        baudRate?: number | undefined;
         timeout?: number | undefined;
+        buildTarget?: string | undefined;
     }>>;
     toolchain: z.ZodOptional<z.ZodObject<{
         type: z.ZodOptional<z.ZodString>;
@@ -76,141 +81,178 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
         baudRate?: number | undefined;
     }>>;
     native: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    zephyr: z.ZodOptional<z.ZodObject<{
+        kconfig: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        cmakeArgs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        runner: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        kconfig?: Record<string, string> | undefined;
+        cmakeArgs?: string[] | undefined;
+        runner?: string | undefined;
+    }, {
+        kconfig?: Record<string, string> | undefined;
+        cmakeArgs?: string[] | undefined;
+        runner?: string | undefined;
+    }>>;
 }, "strict", z.ZodTypeAny, {
-    console?: {
-        port?: string | undefined;
-        baudRate?: number | undefined;
-    } | undefined;
-    frameworkData?: Record<string, unknown> | undefined;
+    entry?: string | undefined;
     target?: string | undefined;
+    mcu?: string | undefined;
+    board?: string | undefined;
+    contract?: string | undefined;
     framework?: string | undefined;
-    native?: Record<string, unknown> | undefined;
+    psram?: "opi" | "quad" | undefined;
     output?: {
         framework?: string | undefined;
+        optimize?: "none" | "size" | "speed" | "balanced" | undefined;
         outDir?: string | undefined;
-        optimize?: "size" | "none" | "speed" | "balanced" | undefined;
         defines?: Record<string, string> | undefined;
         extraFlags?: string[] | undefined;
     } | undefined;
-    board?: string | undefined;
-    mcu?: string | undefined;
+    frameworkData?: Record<string, unknown> | undefined;
     include?: string[] | undefined;
-    entry?: string | undefined;
-    toolchain?: {
-        type?: string | undefined;
-        frameworkOptions?: Record<string, unknown> | undefined;
-    } | undefined;
-    contract?: string | undefined;
     exclude?: string[] | undefined;
     test?: {
-        buildTarget?: string | undefined;
-        port?: string | undefined;
         board?: string | undefined;
-        baudRate?: number | undefined;
         include?: string[] | undefined;
+        port?: string | undefined;
+        baudRate?: number | undefined;
         timeout?: number | undefined;
+        buildTarget?: string | undefined;
+    } | undefined;
+    toolchain?: {
+        type?: string | undefined;
+        frameworkOptions?: Record<string, unknown> | undefined;
     } | undefined;
-}, {
     console?: {
         port?: string | undefined;
         baudRate?: number | undefined;
     } | undefined;
-    frameworkData?: Record<string, unknown> | undefined;
+    native?: Record<string, unknown> | undefined;
+    zephyr?: {
+        kconfig?: Record<string, string> | undefined;
+        cmakeArgs?: string[] | undefined;
+        runner?: string | undefined;
+    } | undefined;
+}, {
+    entry?: string | undefined;
     target?: string | undefined;
+    mcu?: string | undefined;
+    board?: string | undefined;
+    contract?: string | undefined;
     framework?: string | undefined;
-    native?: Record<string, unknown> | undefined;
+    psram?: "opi" | "quad" | undefined;
     output?: {
         framework?: string | undefined;
+        optimize?: "none" | "size" | "speed" | "balanced" | undefined;
         outDir?: string | undefined;
-        optimize?: "size" | "none" | "speed" | "balanced" | undefined;
         defines?: Record<string, string> | undefined;
         extraFlags?: string[] | undefined;
     } | undefined;
-    board?: string | undefined;
-    mcu?: string | undefined;
+    frameworkData?: Record<string, unknown> | undefined;
     include?: string[] | undefined;
-    entry?: string | undefined;
-    toolchain?: {
-        type?: string | undefined;
-        frameworkOptions?: Record<string, unknown> | undefined;
-    } | undefined;
-    contract?: string | undefined;
     exclude?: string[] | undefined;
     test?: {
-        buildTarget?: string | undefined;
-        port?: string | undefined;
         board?: string | undefined;
-        baudRate?: number | undefined;
         include?: string[] | undefined;
+        port?: string | undefined;
+        baudRate?: number | undefined;
         timeout?: number | undefined;
+        buildTarget?: string | undefined;
+    } | undefined;
+    toolchain?: {
+        type?: string | undefined;
+        frameworkOptions?: Record<string, unknown> | undefined;
     } | undefined;
-}>, {
     console?: {
         port?: string | undefined;
         baudRate?: number | undefined;
     } | undefined;
-    frameworkData?: Record<string, unknown> | undefined;
+    native?: Record<string, unknown> | undefined;
+    zephyr?: {
+        kconfig?: Record<string, string> | undefined;
+        cmakeArgs?: string[] | undefined;
+        runner?: string | undefined;
+    } | undefined;
+}>, {
+    entry?: string | undefined;
     target?: string | undefined;
+    mcu?: string | undefined;
+    board?: string | undefined;
+    contract?: string | undefined;
     framework?: string | undefined;
-    native?: Record<string, unknown> | undefined;
+    psram?: "opi" | "quad" | undefined;
     output?: {
         framework?: string | undefined;
+        optimize?: "none" | "size" | "speed" | "balanced" | undefined;
         outDir?: string | undefined;
-        optimize?: "size" | "none" | "speed" | "balanced" | undefined;
         defines?: Record<string, string> | undefined;
         extraFlags?: string[] | undefined;
     } | undefined;
-    board?: string | undefined;
-    mcu?: string | undefined;
+    frameworkData?: Record<string, unknown> | undefined;
     include?: string[] | undefined;
-    entry?: string | undefined;
-    toolchain?: {
-        type?: string | undefined;
-        frameworkOptions?: Record<string, unknown> | undefined;
-    } | undefined;
-    contract?: string | undefined;
     exclude?: string[] | undefined;
     test?: {
-        buildTarget?: string | undefined;
-        port?: string | undefined;
         board?: string | undefined;
-        baudRate?: number | undefined;
         include?: string[] | undefined;
+        port?: string | undefined;
+        baudRate?: number | undefined;
         timeout?: number | undefined;
+        buildTarget?: string | undefined;
+    } | undefined;
+    toolchain?: {
+        type?: string | undefined;
+        frameworkOptions?: Record<string, unknown> | undefined;
     } | undefined;
-}, {
     console?: {
         port?: string | undefined;
         baudRate?: number | undefined;
     } | undefined;
-    frameworkData?: Record<string, unknown> | undefined;
+    native?: Record<string, unknown> | undefined;
+    zephyr?: {
+        kconfig?: Record<string, string> | undefined;
+        cmakeArgs?: string[] | undefined;
+        runner?: string | undefined;
+    } | undefined;
+}, {
+    entry?: string | undefined;
     target?: string | undefined;
+    mcu?: string | undefined;
+    board?: string | undefined;
+    contract?: string | undefined;
     framework?: string | undefined;
-    native?: Record<string, unknown> | undefined;
+    psram?: "opi" | "quad" | undefined;
     output?: {
         framework?: string | undefined;
+        optimize?: "none" | "size" | "speed" | "balanced" | undefined;
         outDir?: string | undefined;
-        optimize?: "size" | "none" | "speed" | "balanced" | undefined;
         defines?: Record<string, string> | undefined;
         extraFlags?: string[] | undefined;
     } | undefined;
-    board?: string | undefined;
-    mcu?: string | undefined;
+    frameworkData?: Record<string, unknown> | undefined;
     include?: string[] | undefined;
-    entry?: string | undefined;
+    exclude?: string[] | undefined;
+    test?: {
+        board?: string | undefined;
+        include?: string[] | undefined;
+        port?: string | undefined;
+        baudRate?: number | undefined;
+        timeout?: number | undefined;
+        buildTarget?: string | undefined;
+    } | undefined;
     toolchain?: {
         type?: string | undefined;
         frameworkOptions?: Record<string, unknown> | undefined;
     } | undefined;
-    contract?: string | undefined;
-    exclude?: string[] | undefined;
-    test?: {
-        buildTarget?: string | undefined;
+    console?: {
         port?: string | undefined;
-        board?: string | undefined;
         baudRate?: number | undefined;
-        include?: string[] | undefined;
-        timeout?: number | undefined;
+    } | undefined;
+    native?: Record<string, unknown> | undefined;
+    zephyr?: {
+        kconfig?: Record<string, string> | undefined;
+        cmakeArgs?: string[] | undefined;
+        runner?: string | undefined;
     } | undefined;
 }>;
 /** Inferred TypeScript type from the Zod schema. */

package/dist/config-schema.js

@@ -8,6 +8,8 @@
 import { z } from 'zod';
 /** Optimization levels accepted by the output.optimize field. */
 const OptimizationLevel = z.enum(['none', 'size', 'speed', 'balanced']);
+/** PSRAM types accepted by the top-level `psram` field (ESP32 PSRAM variants). */
+const PsramType = z.enum(['opi', 'quad']);
 /** Schema for the `output` section. */
 const OutputConfig = z.object({
     framework: z.string().min(1).optional(),
@@ -35,6 +37,12 @@ const ToolchainConfig = z.object({
     type: z.string().optional(),
     frameworkOptions: z.record(z.string(), z.unknown()).optional(),
 }).strict();
+/** Schema for the `zephyr` section. */
+const ZephyrConfig = z.object({
+    kconfig: z.record(z.string(), z.string()).optional(),
+    cmakeArgs: z.array(z.string()).optional(),
+    runner: z.string().optional(),
+}).strict();
 /**
  * Schema for the full CuttlefishConfig shape.
  *
@@ -47,6 +55,11 @@ export const CuttlefishConfigSchema = z.object({
     board: z.string().optional(),
     contract: z.string().optional(),
     framework: z.string().optional(),
+    /** ESP32 PSRAM type. When set, the framework emits the PSRAM-enabling
+     *  Kconfig/define so canvas allocations prefer external RAM (large scroll
+     *  viewports/lists stop failing on PSRAM targets). No effect on boards
+     *  without PSRAM (the runtime falls back to SRAM then the band renderer). */
+    psram: PsramType.optional(),
     output: OutputConfig.optional(),
     frameworkData: z.record(z.string(), z.unknown()).optional(),
     include: z.array(z.string()).optional(),
@@ -55,6 +68,7 @@ export const CuttlefishConfigSchema = z.object({
     toolchain: ToolchainConfig.optional(),
     console: ConsoleConfig.optional(),
     native: z.record(z.string(), z.unknown()).optional(),
+    zephyr: ZephyrConfig.optional(),
 }).strict().refine(data => !(data.board && data.contract), {
     message: "Specifying both 'board' and 'contract' is not allowed. Choose one.",
     path: ['board'],

package/dist/contract/board-generator.d.ts

@@ -0,0 +1,17 @@
+/** The directory (relative to the project root) where board.ts is generated. */
+export declare const CUTTLEFISH_DIR = ".cuttlefish";
+export interface GenerateBoardOptions {
+    /** Absolute project root dir (where .cuttlefish/ lives). */
+    projectDir: string;
+    /** MCU package specifier, e.g. '@typecad/mcu-atmega328p'. */
+    mcuPackage: string;
+    /** Matched MCU pin names to re-export (e.g. ['PB5','PC4']). */
+    connectedPins: string[];
+    /** Selected peripheral instance names to re-export (e.g. ['I2C0']). */
+    peripherals: string[];
+}
+/**
+ * Writes the narrowed `.cuttlefish/board.ts`.
+ * @returns the absolute path to the generated file.
+ */
+export declare function generateBoardFile(opts: GenerateBoardOptions): string;

package/dist/contract/board-generator.js

@@ -0,0 +1,57 @@
+// ---------------------------------------------------------------------------
+// Board generator — emits the narrowed `.cuttlefish/board.ts` for a contract
+//
+// Given the MCU package name plus the matched pin and peripheral names, writes
+// a board.ts that:
+//   - re-exports the full HAL surface from @typecad/hal (constants, functions,
+//     timing, math, GPIO/Pin helpers, buses) so firmware has the complete
+//     runtime vocabulary; and
+//   - re-exports ONLY the connected pins and selected peripherals from the MCU
+//     package, so any pin the PCB did not wire is absent from `@typecad/board`
+//     and using it becomes a compile error.
+//
+// The emitted file is consumed via cuttlefish-env.d.ts, which emits
+// `declare module '@typecad/board' { export * from './board.js'; ... }`
+// for contract-based configs (see config-loader.ts). The './board.js' relative
+// specifier resolves to this file in the same `.cuttlefish/` directory.
+// ---------------------------------------------------------------------------
+import fs from 'node:fs';
+import path from 'node:path';
+/** The directory (relative to the project root) where board.ts is generated. */
+export const CUTTLEFISH_DIR = '.cuttlefish';
+/**
+ * Writes the narrowed `.cuttlefish/board.ts`.
+ * @returns the absolute path to the generated file.
+ */
+export function generateBoardFile(opts) {
+    const { projectDir, mcuPackage, connectedPins, peripherals } = opts;
+    const cuttlefishDir = path.join(projectDir, CUTTLEFISH_DIR);
+    if (!fs.existsSync(cuttlefishDir)) {
+        fs.mkdirSync(cuttlefishDir, { recursive: true });
+    }
+    const lines = [
+        '// Auto-generated by the cuttlefish transpiler from a TypeCAD contract.',
+        '// Do not edit manually — regenerate by re-running cuttlefish.',
+        '//',
+        '// This board exposes only the pins and peripherals that the source contract',
+        `// (${mcuPackage}) declares as connected on the PCB. Pins the board did not wire`,
+        '// are intentionally absent: using one is a compile error.',
+        '',
+        '// Full HAL runtime surface (constants, timing, math, GPIO/bus helpers).',
+        "export * from '@typecad/hal';",
+        '',
+        '// Narrowed pin set — only pins the contract declares connected.',
+    ];
+    if (connectedPins.length > 0) {
+        lines.push(`export { ${connectedPins.join(', ')} } from '${mcuPackage}';`);
+    }
+    if (peripherals.length > 0) {
+        lines.push('');
+        lines.push('// Narrowed peripheral set — only buses whose pins are wired on the PCB.');
+        lines.push(`export { ${peripherals.join(', ')} } from '${mcuPackage}';`);
+    }
+    lines.push(''); // trailing newline
+    const outPath = path.join(cuttlefishDir, 'board.ts');
+    fs.writeFileSync(outPath, lines.join('\n'), 'utf-8');
+    return outPath;
+}

package/dist/contract/contract-parser.d.ts

@@ -0,0 +1,217 @@
+import { z } from 'zod';
+/** Contract schema version. Only 1 is currently defined. */
+export declare const CONTRACT_VERSION: 1;
+/**
+ * An external component on the same net as an MCU pin. Validated LENIENTLY:
+ * cuttlefish does not act on component metadata, so we only require the fields
+ * the firmware toolchain reads (reference + dnp) and accept unknown extras
+ * (voltage, wattage, tolerance, ...) without rejecting the contract. This
+ * keeps cuttlefish forward-compatible with typecad.net adding component fields.
+ */
+declare const ContractComponentSchema: z.ZodObject<{
+    reference: z.ZodString;
+    dnp: z.ZodBoolean;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    reference: z.ZodString;
+    dnp: z.ZodBoolean;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    reference: z.ZodString;
+    dnp: z.ZodBoolean;
+}, z.ZodTypeAny, "passthrough">>;
+/**
+ * Info about a single connected MCU pin. The fields cuttlefish consumes
+ * (pinName, pinType, net) are required; boardName is optional (present only
+ * when typecad.net's Component.typehal map was set).
+ */
+declare const ContractPinSchema: z.ZodObject<{
+    pinName: z.ZodString;
+    pinType: z.ZodString;
+    boardName: z.ZodOptional<z.ZodString>;
+    net: z.ZodString;
+    externalComponents: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        reference: z.ZodString;
+        dnp: z.ZodBoolean;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        reference: z.ZodString;
+        dnp: z.ZodBoolean;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        reference: z.ZodString;
+        dnp: z.ZodBoolean;
+    }, z.ZodTypeAny, "passthrough">>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    pinName: string;
+    pinType: string;
+    net: string;
+    externalComponents: z.objectOutputType<{
+        reference: z.ZodString;
+        dnp: z.ZodBoolean;
+    }, z.ZodTypeAny, "passthrough">[];
+    boardName?: string | undefined;
+}, {
+    pinName: string;
+    pinType: string;
+    net: string;
+    boardName?: string | undefined;
+    externalComponents?: z.objectInputType<{
+        reference: z.ZodString;
+        dnp: z.ZodBoolean;
+    }, z.ZodTypeAny, "passthrough">[] | undefined;
+}>;
+/** Which peripheral buses have all their required pins wired. */
+declare const AvailablePeripheralsSchema: z.ZodObject<{
+    i2c: z.ZodBoolean;
+    spi: z.ZodBoolean;
+    uart: z.ZodBoolean;
+}, "strict", z.ZodTypeAny, {
+    i2c: boolean;
+    spi: boolean;
+    uart: boolean;
+}, {
+    i2c: boolean;
+    spi: boolean;
+    uart: boolean;
+}>;
+/**
+ * The top-level contract object. `.strict()` so a future v2 contract with new
+ * top-level keys is rejected clearly (complementing the version check) rather
+ * than silently accepted with the new fields dropped.
+ */
+export declare const HwContractSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    mcu: z.ZodObject<{
+        symbol: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        symbol: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        symbol: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>;
+    connectedPins: z.ZodRecord<z.ZodString, z.ZodObject<{
+        pinName: z.ZodString;
+        pinType: z.ZodString;
+        boardName: z.ZodOptional<z.ZodString>;
+        net: z.ZodString;
+        externalComponents: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            reference: z.ZodString;
+            dnp: z.ZodBoolean;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            reference: z.ZodString;
+            dnp: z.ZodBoolean;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            reference: z.ZodString;
+            dnp: z.ZodBoolean;
+        }, z.ZodTypeAny, "passthrough">>, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        pinName: string;
+        pinType: string;
+        net: string;
+        externalComponents: z.objectOutputType<{
+            reference: z.ZodString;
+            dnp: z.ZodBoolean;
+        }, z.ZodTypeAny, "passthrough">[];
+        boardName?: string | undefined;
+    }, {
+        pinName: string;
+        pinType: string;
+        net: string;
+        boardName?: string | undefined;
+        externalComponents?: z.objectInputType<{
+            reference: z.ZodString;
+            dnp: z.ZodBoolean;
+        }, z.ZodTypeAny, "passthrough">[] | undefined;
+    }>>;
+    availablePeripherals: z.ZodObject<{
+        i2c: z.ZodBoolean;
+        spi: z.ZodBoolean;
+        uart: z.ZodBoolean;
+    }, "strict", z.ZodTypeAny, {
+        i2c: boolean;
+        spi: boolean;
+        uart: boolean;
+    }, {
+        i2c: boolean;
+        spi: boolean;
+        uart: boolean;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    mcu: {
+        symbol: string;
+    } & {
+        [k: string]: unknown;
+    };
+    version: 1;
+    connectedPins: Record<string, {
+        pinName: string;
+        pinType: string;
+        net: string;
+        externalComponents: z.objectOutputType<{
+            reference: z.ZodString;
+            dnp: z.ZodBoolean;
+        }, z.ZodTypeAny, "passthrough">[];
+        boardName?: string | undefined;
+    }>;
+    availablePeripherals: {
+        i2c: boolean;
+        spi: boolean;
+        uart: boolean;
+    };
+}, {
+    mcu: {
+        symbol: string;
+    } & {
+        [k: string]: unknown;
+    };
+    version: 1;
+    connectedPins: Record<string, {
+        pinName: string;
+        pinType: string;
+        net: string;
+        boardName?: string | undefined;
+        externalComponents?: z.objectInputType<{
+            reference: z.ZodString;
+            dnp: z.ZodBoolean;
+        }, z.ZodTypeAny, "passthrough">[] | undefined;
+    }>;
+    availablePeripherals: {
+        i2c: boolean;
+        spi: boolean;
+        uart: boolean;
+    };
+}>;
+export type ContractComponent = z.infer<typeof ContractComponentSchema>;
+export type ContractPin = z.infer<typeof ContractPinSchema>;
+export type AvailablePeripherals = z.infer<typeof AvailablePeripheralsSchema>;
+export type HwContract = z.infer<typeof HwContractSchema>;
+/**
+ * Parses a TypeCAD contract file.
+ *
+ * The version is checked first as a fast path so a v2 (or later) contract
+ * fails with "unsupported version, update cuttlefish" rather than a cascade
+ * of field-mismatch errors. After the version check, the full schema is
+ * applied for precise per-field validation.
+ *
+ * @throws on an unreadable file, invalid JSON, unsupported version, or
+ *   schema-validation failure (with a path-annotated message).
+ */
+export declare function parseContractFile(contractPath: string): HwContract;
+/**
+ * Matches contract pins to canonical MCU pin names (e.g. 'PB5', 'PC4').
+ *
+ * Strategy (boardName-first, substring fallback):
+ *   1. If the contract pin carries a `boardName` (populated by typecad.net when
+ *      Component.typehal was set) and that name appears in mcuPinNames, use it
+ *      directly — it is the user-validated mapping.
+ *   2. Otherwise, substring-match the KiCAD `pinName` against mcuPinNames
+ *      (e.g. "XTAL1/PB6" contains "PB6"). This covers contracts emitted without
+ *      a typehal map.
+ *
+ * Power/ground pins are excluded. The result is de-duplicated.
+ */
+export declare function matchConnectedPins(contract: HwContract, mcuPinNames: readonly string[]): string[];
+/**
+ * Selects which MCU peripheral instance names to re-export based on the
+ * contract's availablePeripherals. If the contract says SPI isn't wired,
+ * SPI0 (and friends) is dropped from the narrowed board — so `SPI0.begin()`
+ * becomes a compile error on a board whose PCB doesn't route SPI.
+ */
+export declare function selectPeripherals(contract: HwContract, mcuPeripheralNames: readonly string[]): string[];
+export {};