@typecad/cuttlefish 1.0.0-alpha.6 → 1.0.0-alpha.8

package/dist/api/shared/worker-runtime.js

@@ -0,0 +1,163 @@
+// ---------------------------------------------------------------------------
+// Shared worker-offload runtime C++ code generator
+//
+// Generates the generic worker pool + the __tc_worker_submit / __tc_worker_done
+// contract that generalizes the one-off ESP32 HTTP offload pattern
+// (framework-esp32/src/lowering/http.ts: the __tc_http_send_task /
+// __tc_http_send_start / __tc_http_done trio). The pool and contract live here;
+// the per-framework spawn/signal/poll PRIMITIVES are injected via the strategy
+// hooks workerSpawnLines / workerSignalDoneExpr / workerIsDoneExpr.
+//
+// Design (the safety property, per the approved plan):
+//  - The worker runtime is request-in / poll-out: the worker function receives
+//    its inputs by value and exposes outputs only through the opaque handle.
+//  - No mutex/semaphore is added to the IR. The worker-isolation analyzer
+//    (worker-analysis.ts) makes shared mutable state a transpile-time error.
+//  - STL-free: fixed-size static slot table, function-pointer + void*. Links
+//    on minimal-libc targets (Zephyr).
+//
+// The memory-barrier contract is load-bearing on dual-core targets: the signal
+// primitive (workerSignalDoneExpr) MUST issue a full barrier so the consumer
+// observes the worker's preceding output writes once it observes completion.
+// ESP32 xTaskNotifyGive and Zephyr k_sem_give both satisfy this; bare volatile
+// does NOT across cores.
+// ---------------------------------------------------------------------------
+/**
+ * Generate the worker-offload runtime C++ for a framework that supplies a
+ * backing. Returns null if `backing` is null (unsupported on this framework).
+ *
+ * The emitted code defines, for each slot i in [0, poolSize):
+ *   - a worker trampoline __tc_worker_fn_i(void* arg) that runs the recorded
+ *     fn and then signals completion via signalDoneExpr,
+ *   - __tc_worker_submit(i, fn, arg) — records the waiter, clears done, spawns,
+ *   - __tc_worker_done(i) — poll predicate.
+ *
+ * AUTOSAR C++14: fixed-width types, static_cast, final structs, no STL, no heap.
+ */
+export function generateWorkerRuntime(backing, options = {}) {
+    if (!backing)
+        return null;
+    const poolSize = options.poolSize ?? 4;
+    const stackSize = options.stackSize ?? 8192;
+    const lines = [];
+    lines.push(`// ── Worker offload runtime (generalized request-in / poll-out) ──────────────`);
+    lines.push(`// Slot table + __tc_worker_submit/done contract. Per-framework primitives`);
+    lines.push(`// (spawn/signal/poll) are injected by the framework strategy. STL-free so`);
+    lines.push(`// this links on minimal-libc targets. See worker-runtime.ts.`);
+    lines.push(`namespace typecad_worker {`);
+    lines.push(`  using WorkerFn = void (*)(void*);`);
+    lines.push(``);
+    lines.push(`  struct WorkerSlot final {`);
+    lines.push(`    volatile bool done;`);
+    lines.push(`    void* waiter;        // framework-specific waiter handle (opaque)`);
+    lines.push(`    WorkerFn fn;`);
+    lines.push(`    void* arg;`);
+    lines.push(`  };`);
+    lines.push(``);
+    // Per-slot static instances.
+    for (let i = 0; i < poolSize; i++) {
+        lines.push(`  static WorkerSlot __slot_${i};`);
+    }
+    lines.push(``);
+    // Forward-declare the per-slot trampolines so backings that need to bind a
+    // named handler to one (e.g. Zephyr K_WORK_DEFINE(_work_i, handler_i)) can
+    // reference it before the trampoline definition appears below.
+    for (let i = 0; i < poolSize; i++) {
+        lines.push(`  static void __tc_worker_fn_${i}(void* arg);`);
+    }
+    lines.push(``);
+    // Per-slot backing declarations (e.g. Zephyr K_SEM_DEFINE + K_WORK_DEFINE +
+    // a work handler that forwards to the trampoline). Emitted BEFORE the
+    // trampoline definitions so the trampoline bodies can reference per-slot
+    // objects declared here (e.g. the completion semaphore used by the signal
+    // expression). Backings must only forward-declare, not define, the
+    // trampoline itself.
+    if (backing.slotDeclarations) {
+        for (let i = 0; i < poolSize; i++) {
+            const trampolineName = `__tc_worker_fn_${i}`;
+            for (const d of backing.slotDeclarations(i, trampolineName)) {
+                lines.push(`  ${d}`);
+            }
+        }
+        lines.push(``);
+    }
+    // Per-slot worker trampolines: run fn(arg), then signal completion.
+    for (let i = 0; i < poolSize; i++) {
+        const signal = backing.signalDoneExpr(i);
+        lines.push(`  // Worker trampoline for slot ${i}.`);
+        lines.push(`  static void __tc_worker_fn_${i}(void* arg) {`);
+        lines.push(`    // The shared runtime recorded fn/waiter before spawn; run it.`);
+        lines.push(`    if (__slot_${i}.fn != nullptr) { __slot_${i}.fn(arg); }`);
+        lines.push(`    __slot_${i}.done = true;`);
+        lines.push(`    ${signal};   // barrier: makes the fn's output writes visible`);
+        lines.push(`  }`);
+        lines.push(``);
+    }
+    // submit / done per slot.
+    for (let i = 0; i < poolSize; i++) {
+        const trampolineName = `__tc_worker_fn_${i}`;
+        const spawn = backing.spawnLines(i, trampolineName, `__slot_${i}.waiter`);
+        lines.push(`  static inline void __tc_worker_submit_${i}(WorkerFn fn, void* arg) {`);
+        lines.push(`    __slot_${i}.done = false;`);
+        lines.push(`    __slot_${i}.fn = fn;`);
+        lines.push(`    __slot_${i}.arg = arg;`);
+        lines.push(`    // waiter is set by the framework spawn primitive below.`);
+        for (const s of spawn)
+            lines.push(`    ${s}`);
+        lines.push(`  }`);
+        lines.push(``);
+        const poll = backing.isDoneExpr(i);
+        lines.push(`  static inline bool __tc_worker_done_${i}(void) {`);
+        lines.push(`    if (__slot_${i}.done) { return true; }   // fast path`);
+        lines.push(`    if (${poll}) { __slot_${i}.done = true; return true; }`);
+        lines.push(`    return false;`);
+        lines.push(`  }`);
+        lines.push(``);
+    }
+    lines.push(`}  // namespace typecad_worker`);
+    lines.push(``);
+    // Global dispatch aliases so HAL emit (worker.submit / worker.done) resolves.
+    lines.push(`// Global dispatch: select the per-slot submit/done by handle id.`);
+    lines.push(`inline void __tc_worker_submit(int32_t handle, typecad_worker::WorkerFn fn, void* arg) {`);
+    lines.push(`  switch (handle) {`);
+    for (let i = 0; i < poolSize; i++) {
+        lines.push(`    case ${i}: typecad_worker::__tc_worker_submit_${i}(fn, arg); return;`);
+    }
+    lines.push(`    default: break;   // out-of-range handle: no-op`);
+    lines.push(`  }`);
+    lines.push(`}`);
+    lines.push(`inline bool __tc_worker_done(int32_t handle) {`);
+    lines.push(`  switch (handle) {`);
+    for (let i = 0; i < poolSize; i++) {
+        lines.push(`    case ${i}: return typecad_worker::__tc_worker_done_${i}();`);
+    }
+    lines.push(`    default: return true;   // out-of-range handle: treat as already done`);
+    lines.push(`  }`);
+    lines.push(`}`);
+    return lines.join("\n");
+}
+/**
+ * Resolve a HAL worker.* op to C++ against the shared contract.
+ * Returns undefined for ops the caller did not lower (unsupported).
+ *
+ * Note: the worker function itself (fnRef) and its argument (argRef) come from
+ * the IR as flat-scalar strings (per the hal-op-ir flat-fields contract). The
+ * lowering emits a straight call into __tc_worker_submit / __tc_worker_done.
+ */
+export function lowerWorkerOp(op) {
+    const o = op;
+    switch (op.operation) {
+        case 'worker.submit': {
+            const handle = Number(o.handleId);
+            const fn = String(o.fnRef);
+            const arg = o.argRef != null ? String(o.argRef) : 'nullptr';
+            return { code: `__tc_worker_submit(static_cast<int32_t>(${handle}), ${fn}, ${arg});` };
+        }
+        case 'worker.done': {
+            const handle = Number(o.handleId);
+            return { expression: `__tc_worker_done(static_cast<int32_t>(${handle}))` };
+        }
+        default:
+            return undefined;
+    }
+}

package/dist/cli.js

@@ -5,22 +5,22 @@ import { parseCommandLine, printHelp } from "./utils/cli.js";
 import { scaffoldProject, printInitNextSteps, KNOWN_TARGETS } from "./create/index.js";
 import { runInitWizard } from "./create/index.js";
 import { generateLibraryDefinitions, transpileFile } from "./transpile.js";
-import { generateDecl, generateDeclsForDirectory } from "./libdef/cpp-to-decl.js";
+import { generateDecl, generateDeclsForDirectory, generateComponentDeclsForProject } from "./libdef/cpp-to-decl.js";
 import { mapCppLocationToTs, readSourceMap, resolveMapPath } from "./mapping/source-map.js";
 import { compileSource, uploadFirmware, monitorDevice } from "./platform/toolchain.js";
 import { resolveStrategy } from "./platform/registry.js";
 import { loadFrameworkPackage } from "./framework-package.js";
 import { getLoadedFramework, hasLoadedFramework } from "./framework-registry.js";
 import { loadCuttlefishConfig, generateVirtualTypeDeclaration } from "./config-loader.js";
+import { generateContractBoard } from "./contract/index.js";
 import { requireUIHook, hasUIHook } from "./ui-hook.js";
 import { loadUIEngine } from "./ui/ui-bridge.js";
+import { loadSafetyEngine } from "./safety/safety-bridge.js";
 import { runWatch, discoverWatchDirs } from "./watch.js";
 import { runExpectTests, assertTypeScriptInput, printDiagnostics, printMappedCompileErrors } from "./cli-utils.js";
 import { runPreviewServer } from "./preview/server.js";
 import * as ui from "./utils/ui.js";
 import chalk from "chalk";
-import { checkArduinoEnv } from "@typecad/arduino-cli";
-import { runLicensesPresenter } from "./licenses.js";
 function hasFatalDiagnostics(result) {
     return result.diagnostics.some((diagnostic) => diagnostic.severity === "error");
 }
@@ -33,6 +33,27 @@ function displayConfigForTranspile(config) {
     }
     return display;
 }
+/**
+ * Apply the PSRAM config to the Arduino build: append the `PSRAM={opi|quad}`
+ * menu option to the FQBN (so the Arduino core's psramFound()/ps_malloc work
+ * at runtime — they're gated on the board menu option, not just the define)
+ * and add `-DBOARD_HAS_PSRAM` to the defines (so the framework's PSRAM canvas
+ * allocator is compiled in). No-op when psram is unset or the target isn't an
+ * Arduino FQBN (the PSRAM= option is Arduino-core-specific).
+ */
+function applyPsramToArduinoBuild(buildTarget, defines, psram) {
+    if (!psram || !buildTarget || !buildTarget.includes(':')) {
+        return { buildTarget, defines: defines ?? {} };
+    }
+    // Arduino FQBN config options follow the board:option as `key=value` pairs.
+    // Append PSRAM= if not already present (don't clobber an explicit override).
+    const psramOpt = `PSRAM=${psram}`;
+    const adjustedTarget = buildTarget.includes('PSRAM=') ? buildTarget : `${buildTarget}:${psramOpt}`;
+    const adjustedDefines = { ...(defines ?? {}) };
+    if (!('BOARD_HAS_PSRAM' in adjustedDefines))
+        adjustedDefines.BOARD_HAS_PSRAM = '';
+    return { buildTarget: adjustedTarget, defines: adjustedDefines };
+}
 async function handleCreate(options) {
     const targetId = options.target ?? options.board;
     const hasTarget = !!targetId;
@@ -43,13 +64,16 @@ async function handleCreate(options) {
             throw new Error(`Unknown target '${targetId}'. Available targets:\n${available}`);
         }
         const framework = options.framework ?? target.framework;
-        const frameworkPackage = target.isNative
-            ? target.frameworkPackage
-            : framework === 'avr'
-                ? '@typecad/framework-avr'
-                : framework === 'arduino'
-                    ? '@typecad/framework-arduino'
-                    : `@typecad/framework-${framework}`;
+        const frameworkPackage = target.frameworkPackage
+            ?? (framework ? `@typecad/framework-${framework}` : undefined);
+        if (!frameworkPackage) {
+            throw new Error(`No framework package resolved for target '${target.id}'. ` +
+                `Pass --framework <name> or install a @typecad/framework-* package.`);
+        }
+        // Derive the short framework id from the package name (e.g.
+        // @typecad/framework-arduino → arduino) when neither the option nor the
+        // target supplied one. KNOWN_TARGETS embedded boards no longer hardcode it.
+        const frameworkId = framework ?? frameworkPackage.replace(/^@typecad\/framework-/, '');
         const projectName = options.projectName || 'my-project';
         const result = scaffoldProject({
             projectName,
@@ -59,11 +83,14 @@ async function handleCreate(options) {
             architecture: target.architecture,
             boardPackage: target.boardPackage,
             frameworkPackage,
-            framework,
+            framework: frameworkId,
             buildTarget: target.buildTarget,
             mcu: target.mcu,
             baudRate: target.isNative ? undefined : (options.baud ?? 9600),
             includeSketch: !options.noSketch,
+            ...(target.frameworkData
+                ? { frameworkData: target.frameworkData }
+                : {}),
         }, options.outDir);
         console.log(`\n${chalk.green("✓")} Created project files:`);
         for (const file of result.createdFiles) {
@@ -109,62 +136,6 @@ async function handleBoardAdd(options) {
     }
     console.log(generateFrameworkChecklist(spec));
 }
-/**
- * `cuttlefish doctor` — verify arduino-cli is installed and the board's core
- * (derived from the FQBN in cuttlefish.config.ts) is present. Exits 0 if the
- * environment is OK, non-zero otherwise. Reuses checkArduinoEnv so the
- * detection logic is shared with the build/test gates.
- */
-function runDoctor() {
-    ui.printHeader();
-    ui.printStep("Checking arduino-cli environment...");
-    const config = loadCuttlefishConfig(process.cwd());
-    const fqbn = config?.buildTarget;
-    const result = checkArduinoEnv(fqbn);
-    const check = result.check;
-    // arduino-cli presence line
-    if (check.arduinoCliInstalled) {
-        ui.printInfo(`arduino-cli .... ${check.arduinoCliVersion ?? "unknown"}  ✓`);
-    }
-    else if (!result.ok && result.reason === "arduino-cli-not-found") {
-        ui.printError(`arduino-cli .... NOT FOUND on PATH`);
-    }
-    else {
-        ui.printError(`arduino-cli .... found but unresponsive`);
-    }
-    // core presence line (only meaningful if we have an FQBN)
-    if (fqbn) {
-        if (check.requiredCore) {
-            const status = check.requiredCoreInstalled ? "installed ✓" : "NOT installed ✗";
-            const line = `${check.requiredCore} ....... ${status}`;
-            if (check.requiredCoreInstalled) {
-                ui.printInfo(line);
-            }
-            else {
-                ui.printError(line);
-                ui.printInfo(`  → run: arduino-cli core install ${check.requiredCore}`);
-            }
-        }
-    }
-    else {
-        ui.printInfo("(no buildTarget in cuttlefish.config.ts — skipping core check)");
-    }
-    // Exit code
-    if (result.ok) {
-        ui.printSuccess("Environment OK");
-        return; // exitCode stays unset => 0
-    }
-    if (!result.ok) {
-        for (const line of result.messages)
-            ui.printInfo(line);
-        process.exitCode = 1;
-    }
-}
-/**
- * `cuttlefish licenses` dispatch — the presenter lives in licenses.ts so it is
- * unit-testable without importing this binary entry module (cli.ts has a
- * shebang and runs main() at import time). See runLicensesPresenter.
- */
 async function main() {
     try {
         const options = parseCommandLine(process.argv);
@@ -212,12 +183,36 @@ async function main() {
             }
             return;
         }
-        if (options.command === "doctor") {
-            runDoctor();
-            return;
-        }
-        if (options.command === "licenses") {
-            runLicensesPresenter(options.strict ?? false, options.all ?? false);
+        if (options.command === "doctor" || options.command === "licenses") {
+            // These commands run standalone (often before a build), so the framework
+            // isn't loaded yet. Load it from the config's framework field so the
+            // framework-supplied doctor/licenses handlers are available.
+            if (!hasLoadedFramework()) {
+                const config = loadCuttlefishConfig(process.cwd());
+                if (config?.framework) {
+                    try {
+                        loadFrameworkPackage(config.framework, process.cwd());
+                    }
+                    catch {
+                        // Framework package not resolvable — fall through to the
+                        // no-support message below rather than crashing the command.
+                    }
+                }
+            }
+            const fw = hasLoadedFramework() ? getLoadedFramework() : undefined;
+            if (options.command === "doctor") {
+                if (!fw?.doctor) {
+                    ui.printInfo("This framework provides no doctor support.");
+                    return;
+                }
+                fw.doctor();
+                return;
+            }
+            if (!fw?.licenses) {
+                ui.printInfo("This framework provides no licenses support.");
+                return;
+            }
+            fw.licenses(options.strict ?? false, options.all ?? false);
             return;
         }
         // ── Handle build command — entry point comes from config ──────────
@@ -250,6 +245,37 @@ async function main() {
         // it intentionally has no inputFile (it scans scanDir instead), so the
         // generic "Missing input file path" check would otherwise block it.
         if (options.command === "gen-decls") {
+            // Check for --components flag (ESP-IDF components: managed + local).
+            // Runs before scanDir/single-file branches; components mode has no
+            // inputFile by design (it scans managed_components/ + components/).
+            const componentsDir = options.componentsDir;
+            if (componentsDir) {
+                ui.printHeader();
+                ui.printStep(`Generating component declarations for ${componentsDir}...`);
+                const config = loadCuttlefishConfig(componentsDir);
+                const frameworkConfig = (config?.frameworkConfig ?? {});
+                const componentsNode = frameworkConfig?.components ?? {};
+                const managedSpecs = Object.keys(componentsNode.managed ?? {});
+                // idf.py stores managed deps as <namespace>__<name> (slashes → __).
+                const managedNames = managedSpecs.map((spec) => spec.replace("/", "__"));
+                const localPaths = (componentsNode.local ?? []).map((p) => path.isAbsolute(p) ? p : path.resolve(componentsDir, p));
+                const builtinNames = componentsNode.builtin ?? [];
+                const created = generateComponentDeclsForProject(componentsDir, {
+                    managed: managedNames,
+                    local: localPaths,
+                    builtin: [],
+                    idfRoot: undefined,
+                });
+                if (created.length === 0) {
+                    ui.printInfo("No component declaration files created.");
+                }
+                else {
+                    ui.printSuccess(`Created ${created.length} declaration file(s):`);
+                    for (const f of created)
+                        ui.printFileCreated(f);
+                }
+                return;
+            }
             // Check for --all flag (scan directory)
             const scanDir = options.scanDir;
             if (scanDir) {
@@ -321,8 +347,56 @@ async function main() {
         // ── Load cuttlefish.config.ts (config wins over CLI flags) ──────────
         const inputDir = path.dirname(path.resolve(options.inputFile));
         const config = loadCuttlefishConfig(inputDir);
+        // ── Contract-based board narrowing ──────────────────────────────────
+        // If the config names a TypeCAD contract (*.contract.json from typecad.net),
+        // generate the narrowed `.cuttlefish/board.ts` BEFORE env.d.ts is written
+        // (it emits `export * from './board.js'` for this case) and before the
+        // board package is resolved downstream. The generated board re-exports
+        // only the pins/peripherals the PCB actually wires.
+        if (config?.contract) {
+            await generateContractBoard(config);
+        }
+        // ── Pre-transpile: generate component .d.ts stubs ───────────────────
+        // The transpile type-check needs the .d.ts imports in main.ts to resolve.
+        // For ESP-IDF builtin/managed/local components, those .d.ts files are
+        // generated by gen-decls — so we must run it BEFORE type-checking, not
+        // only as part of --compile. The cache is written under the transpile
+        // output dir (the same path --compile uses), so user imports resolve
+        // identically in both flows.
+        if (config?.frameworkConfig) {
+            const fc = config.frameworkConfig;
+            const componentsNode = fc?.components ?? {};
+            const managedSpecs = Object.keys(componentsNode.managed ?? {});
+            const localPaths = (componentsNode.local ?? []).map((p) => path.isAbsolute(p) ? p : path.resolve(inputDir, p));
+            const builtinNames = componentsNode.builtin ?? [];
+            if (managedSpecs.length > 0 || localPaths.length > 0 || builtinNames.length > 0) {
+                // Resolve the transpile output dir — the cache lives under it so the
+                // framework's compile path and this pre-transpile pass agree on location.
+                // output.outDir in config is relative to the project root (inputDir);
+                // if absent, the transpile output goes alongside the entry file.
+                const outBase = config.outputOutDir
+                    ? path.resolve(inputDir, config.outputOutDir)
+                    : inputDir;
+                try {
+                    generateComponentDeclsForProject(outBase, {
+                        managed: managedSpecs.map((s) => s.replace('/', '__')),
+                        local: localPaths,
+                        builtin: [],
+                        idfRoot: undefined,
+                    });
+                }
+                catch {
+                    // Non-fatal: if gen-decls fails (e.g. component not yet fetched),
+                    // the type-checker will surface the missing-import errors with
+                    // clearer context than crashing here.
+                }
+            }
+        }
         // Load the UI engine (if @typecad/ui is installed) before any UI work.
         await loadUIEngine();
+        // Load the safety engine (if @typecad/safety is installed) before any
+        // safety work.
+        await loadSafetyEngine();
         let effectivePlatformContext = options.platformContext;
         let effectiveTarget = options.target;
         let effectiveOutDir = options.outDir;
@@ -343,9 +417,16 @@ async function main() {
             }
             let configBuildTarget = config.buildTarget;
             if (configBuildTarget) {
+                // Reconstruct frameworkData from buildTarget so the toolchain sees the
+                // full frameworkData, not just buildTarget.
                 effectivePlatformContext = {
                     architecture: configBuildTarget.split(":")?.[1]?.toLowerCase(),
-                    frameworkData: { buildTarget: configBuildTarget },
+                    frameworkData: {
+                        buildTarget: configBuildTarget,
+                        // Thread the PSRAM type through to the framework so it can emit the
+                        // PSRAM-enabling Kconfig (Zephyr) / define + FQBN option (Arduino).
+                        ...(config.psram ? { psram: config.psram } : {}),
+                    },
                 };
             }
             if (config.outputOutDir && !options.outDir) {
@@ -424,6 +505,8 @@ async function main() {
                     diagnostics: options.diagnostics,
                     display: displayConfigForTranspile(config),
                     projectRoot: options.projectRoot,
+                    autosar: options.autosar,
+                    autosarArxml: options.autosarArxml,
                 });
                 printDiagnostics(result.diagnostics);
                 ui.printTasks(result.asyncTaskNames ?? [], result.usesTimers ?? false);
@@ -435,7 +518,8 @@ async function main() {
                     initialBuildOk = true;
                     // Initial compile + upload if flags are set
                     if (options.compile) {
-                        const buildTarget = effectivePlatformContext?.frameworkData?.buildTarget ?? options.platformContext?.frameworkData?.buildTarget;
+                        const baseBuildTarget = effectivePlatformContext?.frameworkData?.buildTarget ?? options.platformContext?.frameworkData?.buildTarget;
+                        const { buildTarget, defines: psramDefines } = applyPsramToArduinoBuild(baseBuildTarget, config?.outputDefines, config?.psram);
                         const watchOpts = {
                             outputDir: path.dirname(result.sourcePath),
                             sourcePath: result.sourcePath,
@@ -444,8 +528,12 @@ async function main() {
                             baud: options.baud ?? config?.console?.baudRate,
                             optimize: config?.outputOptimize,
                             extraFlags: config?.outputExtraFlags,
-                            defines: config?.outputDefines,
+                            defines: psramDefines,
+                            psram: config?.psram,
                             frameworkConfig: config?.frameworkConfig,
+                            zephyrConfig: config?.zephyrConfig,
+                            display: displayConfigForTranspile(config),
+                            debug: options.debug,
                         };
                         ui.printCompiling(buildTarget ?? "native");
                         const compileResult = compileSource(watchOpts);
@@ -517,6 +605,8 @@ async function main() {
                             diagnostics: options.diagnostics,
                             display: displayConfigForTranspile(config),
                             projectRoot: options.projectRoot,
+                            autosar: options.autosar,
+                            autosarArxml: options.autosarArxml,
                         });
                         printDiagnostics(rebuildResult.diagnostics);
                         ui.printTasks(rebuildResult.asyncTaskNames ?? [], rebuildResult.usesTimers ?? false);
@@ -529,7 +619,8 @@ async function main() {
                         else {
                             ui.printSuccess();
                             if (options.compile) {
-                                const buildTarget = effectivePlatformContext?.frameworkData?.buildTarget ?? options.platformContext?.frameworkData?.buildTarget;
+                                const baseBuildTarget = effectivePlatformContext?.frameworkData?.buildTarget ?? options.platformContext?.frameworkData?.buildTarget;
+                                const { buildTarget, defines: psramDefines } = applyPsramToArduinoBuild(baseBuildTarget, config?.outputDefines, config?.psram);
                                 const rebuildOpts = {
                                     outputDir: path.dirname(rebuildResult.sourcePath),
                                     sourcePath: rebuildResult.sourcePath,
@@ -538,8 +629,12 @@ async function main() {
                                     baud: options.baud ?? config?.console?.baudRate,
                                     optimize: config?.outputOptimize,
                                     extraFlags: config?.outputExtraFlags,
-                                    defines: config?.outputDefines,
+                                    defines: psramDefines,
+                                    psram: config?.psram,
                                     frameworkConfig: config?.frameworkConfig,
+                                    zephyrConfig: config?.zephyrConfig,
+                                    display: displayConfigForTranspile(config),
+                                    debug: options.debug,
                                 };
                                 ui.printCompiling(buildTarget ?? "native");
                                 const compileResult = compileSource(rebuildOpts);
@@ -604,6 +699,8 @@ async function main() {
                 diagnostics: options.diagnostics,
                 display: displayConfigForTranspile(config) ?? options.display,
                 projectRoot: options.projectRoot,
+                autosar: options.autosar,
+                autosarArxml: options.autosarArxml,
             });
             printDiagnostics(result.diagnostics);
             ui.printTasks(result.asyncTaskNames ?? [], result.usesTimers ?? false);
@@ -630,7 +727,8 @@ async function main() {
             return;
         }
         // --compile (delegates to the active framework's toolchain)
-        const buildTarget = effectivePlatformContext?.frameworkData?.buildTarget ?? options.platformContext?.frameworkData?.buildTarget;
+        const baseBuildTarget = effectivePlatformContext?.frameworkData?.buildTarget ?? options.platformContext?.frameworkData?.buildTarget;
+        const { buildTarget, defines: psramDefines } = applyPsramToArduinoBuild(baseBuildTarget, config?.outputDefines, config?.psram);
         const toolchainOpts = {
             outputDir: path.dirname(result.sourcePath),
             sourcePath: result.sourcePath,
@@ -639,8 +737,12 @@ async function main() {
             baud: options.baud ?? config?.console?.baudRate,
             optimize: config?.outputOptimize,
             extraFlags: config?.outputExtraFlags,
-            defines: config?.outputDefines,
+            defines: psramDefines,
+            psram: config?.psram,
             frameworkConfig: config?.frameworkConfig,
+            zephyrConfig: config?.zephyrConfig,
+            display: displayConfigForTranspile(config),
+            debug: options.debug,
         };
         ui.printCompiling(buildTarget ?? "native");
         let compileResult;
@@ -691,8 +793,10 @@ async function main() {
             return;
         }
         if (options.monitor) {
-            // --monitor (blocks until Ctrl+C)
-            ui.printMonitoring(port, options.baud);
+            // --monitor (blocks until Ctrl+C). Show the resolved baud (config ?? --baud)
+            // in the banner — toolchainOpts.baud is built the same way, so what the
+            // user sees is what the framework monitor opens the port at.
+            ui.printMonitoring(port, toolchainOpts.baud ?? 115200);
             monitorDevice(toolchainOpts);
             return;
         }

package/dist/config-loader.d.ts

@@ -13,7 +13,7 @@ export interface ResolvedCuttlefishConfig {
     contract?: string;
     /** Build target identifier (e.g. FQBN for Arduino CLI). */
     buildTarget?: string;
-    /** Output framework (e.g. 'arduino', 'platformio'). */
+    /** Output framework (e.g. 'arduino'). */
     outputFramework?: string;
     /** Optimization level. */
     outputOptimize?: string;
@@ -21,9 +21,12 @@ export interface ResolvedCuttlefishConfig {
     outputOutDir?: string;
     /**
      * Framework package for code generation strategy.
-     * Can be '@typecad/framework-arduino', '@typecad/framework-avr', or a custom path.
+     * Can be '@typecad/framework-arduino', '@typecad/framework-zephyr',
+     * '@typecad/framework-native', or a custom path.
      */
     framework?: string;
+    /** ESP32 PSRAM type ('opi' | 'quad') when the target board has PSRAM. */
+    psram?: 'opi' | 'quad';
     /** Entry point TypeScript file (relative to config file directory). */
     entry?: string;
     /** Path to the config file that was loaded. */
@@ -39,6 +42,8 @@ export interface ResolvedCuttlefishConfig {
     outputDefines?: Record<string, string>;
     /** Framework-specific config (e.g. `native` section). */
     frameworkConfig?: Record<string, unknown>;
+    /** Zephyr-specific config (e.g. `zephyr` section). */
+    zephyrConfig?: Record<string, unknown>;
     /** Display profile config. */
     display?: import("./api/shared/display-profile.js").DisplayConfig;
 }