@typecad/cuttlefish 0.1.0-alpha.1 → 1.0.0-alpha.10

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-utils.d.ts

@@ -13,6 +13,7 @@ export declare function printDiagnostics(diagnostics: Array<Diagnostic | {
     line?: number;
     column?: number;
     code?: string;
+    filePath?: string;
     sourceLine?: string;
 }>): void;
 /**

package/dist/cli-utils.js

@@ -50,6 +50,7 @@ export function printDiagnostics(diagnostics) {
     for (const diagnostic of diagnostics) {
         const position = diagnostic.line && diagnostic.column ? chalk.gray(`(${diagnostic.line},${diagnostic.column})`) : "";
         const code = diagnostic.code ? chalk.gray(` [${diagnostic.code}]`) : "";
+        const file = 'filePath' in diagnostic && diagnostic.filePath ? chalk.cyan(diagnostic.filePath) : "";
         let severityLabel;
         let hintColor;
         if (diagnostic.severity === "error") {
@@ -65,7 +66,8 @@ export function printDiagnostics(diagnostics) {
             hintColor = chalk.cyan;
         }
         const location = position ? ` ${position}` : "";
-        const header = `${severityLabel}${code}${location}: ${chalk.white(diagnostic.message)}`;
+        const filePrefix = file ? `${file} ` : "";
+        const header = `${filePrefix}${severityLabel}${code}${location}: ${chalk.white(diagnostic.message)}`;
         if (diagnostic.severity === "error") {
             console.error(header);
         }

package/dist/cli.js

@@ -2,18 +2,21 @@
 import path from "node:path";
 import fs from "node:fs";
 import { parseCommandLine, printHelp } from "./utils/cli.js";
-import { scaffoldProject, printInitNextSteps, KNOWN_TARGETS } from "./create/index.js";
+import { scaffoldProject, printInitNextSteps, KNOWN_TARGETS, frameworksForTarget, frameworkCatalogEntry, FRAMEWORK_CATALOG, frameworkTargetProfile } from "./create/index.js";
 import { runInitWizard } from "./create/index.js";
+import { installProjectDependencies } from "./create/install-deps.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 { requireUIHook } from "./ui-hook.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";
@@ -31,6 +34,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;
@@ -40,15 +64,35 @@ async function handleCreate(options) {
             const available = KNOWN_TARGETS.map(t => `  - ${t.id} (${t.displayName})`).join("\n");
             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}`;
+        // Resolve the framework. --framework wins; otherwise narrow via the catalog
+        // for the chosen board and auto-pick when exactly one is compatible.
+        let frameworkId;
+        let frameworkPackage;
+        if (options.framework) {
+            const requested = frameworkCatalogEntry(options.framework);
+            if (!requested) {
+                const available = FRAMEWORK_CATALOG.filter(f => f.installable).map(f => f.id).join(", ");
+                throw new Error(`Unknown framework '${options.framework}'. Available: ${available}`);
+            }
+            frameworkId = requested.id;
+            frameworkPackage = requested.packageName;
+        }
+        else {
+            const compatible = frameworksForTarget(target).filter(f => f.installable);
+            if (compatible.length === 1) {
+                frameworkId = compatible[0].id;
+                frameworkPackage = compatible[0].packageName;
+            }
+            else {
+                const list = compatible.map(f => f.id).join(", ");
+                throw new Error(`Target '${target.id}' is compatible with multiple frameworks (${list}). ` +
+                    `Pass --framework <id> to choose one.`);
+            }
+        }
         const projectName = options.projectName || 'my-project';
+        // Framework-specific build target + toolchain (Zephyr board id + 'west' vs
+        // the Arduino FQBN + 'arduino-cli').
+        const profile = frameworkTargetProfile(target, frameworkId);
         const result = scaffoldProject({
             projectName,
             targetId: target.id,
@@ -57,18 +101,17 @@ async function handleCreate(options) {
             architecture: target.architecture,
             boardPackage: target.boardPackage,
             frameworkPackage,
-            framework,
-            buildTarget: target.buildTarget,
+            framework: frameworkId,
+            buildTarget: profile.buildTarget ?? target.buildTarget,
+            ...(profile.toolchainType ? { toolchainType: profile.toolchainType } : {}),
             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) {
-            const relative = path.relative(process.cwd(), file);
-            console.log(`  ${chalk.dim(relative || file)}`);
-        }
-        printInitNextSteps(result.options, result.outDir);
+        finalizeCreate(result, options);
     }
     else {
         const wizardResult = await runInitWizard({
@@ -83,13 +126,37 @@ async function handleCreate(options) {
             return;
         }
         const result = scaffoldProject(wizardResult, options.outDir);
-        console.log(`\n${chalk.green("✓")} Created project files:`);
-        for (const file of result.createdFiles) {
-            const relative = path.relative(process.cwd(), file);
-            console.log(`  ${chalk.dim(relative || file)}`);
+        finalizeCreate(result, options);
+    }
+}
+/**
+ * Shared tail of `cuttlefish create`: list the created files, install the new
+ * project's dependencies (so it's ready to build with no extra step — skipped
+ * via --no-install), and print the next-steps. A failed install is non-fatal:
+ * the scaffold itself is valid, so we warn and point at the manual command
+ * rather than undoing anything.
+ */
+function finalizeCreate(result, options) {
+    console.log(`\n${chalk.green("✓")} Created project files:`);
+    for (const file of result.createdFiles) {
+        const relative = path.relative(process.cwd(), file);
+        console.log(`  ${chalk.dim(relative || file)}`);
+    }
+    let installed = false;
+    if (!options.noInstall) {
+        try {
+            const { pm } = installProjectDependencies({ projectDir: result.outDir });
+            installed = true;
+            console.log(`\n${chalk.green("✓")} Installed dependencies via ${pm}.`);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const relativeDir = path.relative(process.cwd(), result.outDir) || '.';
+            console.log(`\n${chalk.yellow("!")} Could not install dependencies automatically: ${message}`);
+            console.log(chalk.dim(`  Run '${chalk.white("npm install")}' manually in ${relativeDir} when ready.`));
         }
-        printInitNextSteps(result.options, result.outDir);
     }
+    printInitNextSteps(result.options, result.outDir, { installed });
 }
 async function handleBoardAdd(options) {
     const { scaffoldBoardPackages, parseBoardSpec, generateFrameworkChecklist } = await import("./create/index.js");
@@ -154,6 +221,38 @@ async function main() {
             }
             return;
         }
+        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 ──────────
         if (options.command === "build") {
             const buildConfig = loadCuttlefishConfig(process.cwd());
@@ -184,6 +283,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) {
@@ -255,8 +385,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;
@@ -277,9 +455,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) {
@@ -321,7 +506,11 @@ async function main() {
                 // Strategy not yet loaded — env.d.ts will have generic declarations only
             }
             generateVirtualTypeDeclaration(config, platformDeclarations);
-            requireUIHook().generateProjectUITypeDeclarations(path.dirname(config.configPath));
+            // @typecad/ui is optional — skip UI type-decl generation when the engine
+            // is not loaded (no UI modules exist to declare).
+            if (hasUIHook()) {
+                requireUIHook().generateProjectUITypeDeclarations(path.dirname(config.configPath));
+            }
         }
         // Print branded header and build info
         ui.printHeader();
@@ -354,15 +543,21 @@ 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);
+                if (result.diagnosticsReportPath) {
+                    ui.printInfo(`Diagnostics report: ${result.diagnosticsReportPath}`);
+                }
                 if (result.diagnostics.length === 0) {
                     ui.printSuccess();
                     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,
@@ -371,8 +566,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);
@@ -421,7 +620,11 @@ async function main() {
                     console.log();
                     try {
                         if (config) {
-                            requireUIHook().generateProjectUITypeDeclarations(path.dirname(config.configPath));
+                            // @typecad/ui is optional — skip UI type-decl generation when the
+                            // engine is not loaded (no UI modules exist to declare).
+                            if (hasUIHook()) {
+                                requireUIHook().generateProjectUITypeDeclarations(path.dirname(config.configPath));
+                            }
                         }
                         ui.printTranspiling();
                         const rebuildResult = await transpileFile({
@@ -440,16 +643,22 @@ 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);
+                        if (rebuildResult.diagnosticsReportPath) {
+                            ui.printInfo(`Diagnostics report: ${rebuildResult.diagnosticsReportPath}`);
+                        }
                         if (rebuildResult.diagnostics.length > 0) {
                             // Errors shown via printDiagnostics — skip compile/upload
                         }
                         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,
@@ -458,8 +667,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);
@@ -524,9 +737,14 @@ 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);
+            if (result.diagnosticsReportPath) {
+                ui.printInfo(`Diagnostics report: ${result.diagnosticsReportPath}`);
+            }
         }
         if (hasFatalDiagnostics(result)) {
             ui.printError("Transpilation failed. Fix the transpiler diagnostics above before compiling.");
@@ -547,7 +765,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,
@@ -556,8 +775,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;
@@ -608,8 +831,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;
         }