@typecad/cuttlefish 1.0.0-alpha.7 → 1.0.0-alpha.9

package/dist/config-loader.js

@@ -9,12 +9,6 @@
 import path from "node:path";
 import fs from "node:fs";
 import ts from "typescript";
-/** True for the framework-esp32 package or any path that resolves to it.
- *  Used to decide whether to route frameworkData → frameworkConfig so the
- *  ESP-IDF toolchain can read components, target, etc. */
-function isEspIdfFramework(framework) {
-    return framework === "@typecad/framework-esp32" || framework.endsWith("framework-esp32");
-}
 import { safeValidateConfig } from "./config-schema.js";
 /** The filename we search for when walking up directories. */
 const CONFIG_FILENAME = "cuttlefish.config.ts";
@@ -303,6 +297,9 @@ export function parseConfigFile(configPath) {
     const framework = flat.get("framework");
     if (typeof framework === "string")
         resolved.framework = framework;
+    const psram = flat.get("psram");
+    if (psram === "opi" || psram === "quad")
+        resolved.psram = psram;
     const outputFramework = flat.get("output.framework");
     if (typeof outputFramework === "string")
         resolved.outputFramework = outputFramework;
@@ -332,17 +329,16 @@ export function parseConfigFile(configPath) {
     if (nativeSection) {
         resolved.frameworkConfig = nativeSection;
     }
-    else if (resolved.framework && isEspIdfFramework(resolved.framework)) {
-        // ESP-IDF: route frameworkData through frameworkConfig so the toolchain
-        // can read components, target, and other framework-specific fields.
-        // extractFrameworkSection walks the AST and preserves nested shapes
-        // (components.managed, components.local, etc.).
-        const frameworkData = configObject
-            ? extractFrameworkSection(configObject, "frameworkData")
-            : undefined;
-        if (frameworkData) {
-            resolved.frameworkConfig = frameworkData;
-        }
+    // Parse zephyr-specific config section.
+    const zephyrKconfig = extractStringRecord(configObject, ["zephyr", "kconfig"]);
+    const zephyrCmakeArgs = extractStringArray(configObject, ["zephyr", "cmakeArgs"]);
+    const zephyrRunner = flat.get("zephyr.runner");
+    if (zephyrKconfig || zephyrCmakeArgs || typeof zephyrRunner === "string") {
+        resolved.zephyrConfig = {
+            ...(zephyrKconfig ? { kconfig: zephyrKconfig } : {}),
+            ...(zephyrCmakeArgs ? { cmakeArgs: zephyrCmakeArgs } : {}),
+            ...(typeof zephyrRunner === "string" ? { runner: zephyrRunner } : {}),
+        };
     }
     // Parse display profile config (nested object with profile name, wiring, touch)
     const displaySection = extractFrameworkSection(configObject, "display");
@@ -363,6 +359,8 @@ export function parseConfigFile(configPath) {
         structuredForValidation.entry = resolved.entry;
     if (resolved.framework)
         structuredForValidation.framework = resolved.framework;
+    if (resolved.psram)
+        structuredForValidation.psram = resolved.psram;
     if (resolved.outputFramework || resolved.outputOptimize || resolved.outputOutDir || resolved.outputExtraFlags || resolved.outputDefines) {
         structuredForValidation.output = {
             ...(resolved.outputFramework ? { framework: resolved.outputFramework } : {}),
@@ -374,6 +372,8 @@ export function parseConfigFile(configPath) {
     }
     if (resolved.console)
         structuredForValidation.console = resolved.console;
+    if (resolved.zephyrConfig)
+        structuredForValidation.zephyr = resolved.zephyrConfig;
     if (resolved.buildTarget) {
         structuredForValidation.frameworkData = { buildTarget: resolved.buildTarget };
     }
@@ -497,8 +497,9 @@ export function generateVirtualTypeDeclaration(config, platformDeclarations) {
     // `declare module` in cuttlefish-env.d.ts is treated as module augmentation
     // (because that file has `export {}`), which can't define a new module.
     //
-    // For contract-based configs, board.ts is generated by the board-codegen
-    // system, so don't overwrite it here.
+    // For contract-based configs, the narrowed board.ts is generated by the
+    // contract reader (`contract/board-generator.ts`, invoked from cli.ts before
+    // this function runs), so don't overwrite it with the generic re-export here.
     if (!config.contract && (config.board || config.mcu)) {
         const reExportSource = config.board ?? config.mcu;
         const boardTsPath = path.join(cuttlefishDir, "board.ts");

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;
     }>>;
@@ -42,18 +47,18 @@ export declare const CuttlefishConfigSchema: z.ZodEffects<z.ZodObject<{
         board: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
         board?: string | undefined;
+        include?: string[] | undefined;
         port?: string | undefined;
-        buildTarget?: string | undefined;
         baudRate?: number | undefined;
-        include?: string[] | undefined;
         timeout?: number | undefined;
+        buildTarget?: string | undefined;
     }, {
         board?: string | undefined;
+        include?: string[] | undefined;
         port?: string | undefined;
-        buildTarget?: string | undefined;
         baudRate?: number | undefined;
-        include?: string[] | 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;
-    exclude?: string[] | undefined;
-    toolchain?: {
-        type?: string | undefined;
-        frameworkOptions?: Record<string, unknown> | undefined;
-    } | 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;
-    mcu?: string | undefined;
+    frameworkData?: Record<string, unknown> | undefined;
     include?: string[] | undefined;
-    entry?: string | undefined;
-    contract?: string | undefined;
+    exclude?: string[] | undefined;
     test?: {
         board?: string | undefined;
+        include?: string[] | undefined;
         port?: string | undefined;
-        buildTarget?: string | undefined;
         baudRate?: number | undefined;
-        include?: string[] | 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;
-    exclude?: string[] | undefined;
-    toolchain?: {
-        type?: string | undefined;
-        frameworkOptions?: Record<string, unknown> | undefined;
-    } | 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;
-    mcu?: string | undefined;
+    frameworkData?: Record<string, unknown> | undefined;
     include?: string[] | undefined;
-    entry?: string | undefined;
-    contract?: string | undefined;
+    exclude?: string[] | undefined;
     test?: {
         board?: string | undefined;
+        include?: string[] | undefined;
         port?: string | undefined;
-        buildTarget?: string | undefined;
         baudRate?: number | undefined;
-        include?: string[] | 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;
-    exclude?: string[] | undefined;
-    toolchain?: {
-        type?: string | undefined;
-        frameworkOptions?: Record<string, unknown> | undefined;
-    } | 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;
-    mcu?: string | undefined;
+    frameworkData?: Record<string, unknown> | undefined;
     include?: string[] | undefined;
-    entry?: string | undefined;
-    contract?: string | undefined;
+    exclude?: string[] | undefined;
     test?: {
         board?: string | undefined;
+        include?: string[] | undefined;
         port?: string | undefined;
-        buildTarget?: string | undefined;
         baudRate?: number | undefined;
-        include?: string[] | 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;
-    exclude?: string[] | undefined;
-    toolchain?: {
-        type?: string | undefined;
-        frameworkOptions?: Record<string, unknown> | undefined;
-    } | 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;
-    mcu?: string | undefined;
+    frameworkData?: Record<string, unknown> | undefined;
     include?: string[] | undefined;
-    entry?: string | undefined;
-    contract?: string | undefined;
+    exclude?: string[] | undefined;
     test?: {
         board?: string | undefined;
+        include?: string[] | undefined;
         port?: string | undefined;
-        buildTarget?: string | undefined;
         baudRate?: number | undefined;
-        include?: string[] | 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;
+    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;
+}