@typecad/cuttlefish 1.0.0-alpha.14 → 1.0.0-alpha.16

package/dist/emit/utils/comment-helpers.js

@@ -9,7 +9,7 @@
  * @param comment The comment string (may contain newlines)
  * @returns Array of normalized comment lines
  */
-export function normalizeComment(comment) {
+function normalizeComment(comment) {
     return comment
         .split(/\r?\n/)
         .map((line) => line.trimEnd())

package/dist/emit/utils/cpp-helpers.d.ts

@@ -1,8 +1,8 @@
 export declare function accessorGetterName(prop: string): string;
 export declare function accessorSetterName(prop: string): string;
 /**
- * Matches a C++ INTEGRAL scalar type (the enum↔integral storage boundary in
- * SUPPORT_MATRIX §1.7). Used by the enum-storage cast sites to decide whether
+ * Matches a C++ INTEGRAL scalar type (the enum↔integral storage boundary).
+ * Used by the enum-storage cast sites to decide whether
  * a value/target is on the integral side of an `enum class` boundary that
  * needs a `static_cast`. Covers the signed/unsigned `char`/`short`/`int`/
  * `long` spellings, the fixed-width `<cstdint>` aliases, `size_t`, and `bool`

package/dist/emit/utils/cpp-helpers.js

@@ -5,8 +5,8 @@ export function accessorSetterName(prop) {
     return `set${prop.charAt(0).toUpperCase()}${prop.slice(1)}`;
 }
 /**
- * Matches a C++ INTEGRAL scalar type (the enum↔integral storage boundary in
- * SUPPORT_MATRIX §1.7). Used by the enum-storage cast sites to decide whether
+ * Matches a C++ INTEGRAL scalar type (the enum↔integral storage boundary).
+ * Used by the enum-storage cast sites to decide whether
  * a value/target is on the integral side of an `enum class` boundary that
  * needs a `static_cast`. Covers the signed/unsigned `char`/`short`/`int`/
  * `long` spellings, the fixed-width `<cstdint>` aliases, `size_t`, and `bool`

package/dist/emit/utils/hal-op-cpp-type.js

@@ -7,33 +7,31 @@ export function cppTypeForHalOp(operation) {
     switch (operation) {
         case "wifi.local_ip":
         case "wifi.mac":
-        case "wifi.ap_ip":
         case "wifi.scan_ssid":
         case "http.body":
         case "http.response_header":
             return "const char*";
         case "wifi.is_connected":
-        case "wifi.connect":
-        case "wifi.wait_connected":
+        case "wifi.join":
         case "wifi.scan_done":
         case "wifi.ap_start":
-        case "wifi.connect_saved":
         case "http.ok":
         case "http.done":
             return "bool";
-        case "wifi.status":
         case "wifi.rssi":
         case "wifi.scan":
         case "wifi.scan_count":
         case "wifi.scan_rssi":
         case "wifi.scan_encryption":
         case "wifi.scan_channel":
-        case "wifi.ap_client_count":
         case "http.status":
         case "http.content_length":
             return "int";
         case "http.send":
             return "bool";
+        // Zephyr's sensor channel value is a double (val1 + val2/1e6).
+        case "sensor.get":
+            return "double";
         default:
             return undefined;
     }

package/dist/emit/utils/index.d.ts

@@ -2,7 +2,7 @@
  * Emitter utilities barrel export.
  * Re-exports all utility functions for C++ code emission.
  */
-export { inferObjectFieldType, collectNestedStructDefs, hasArrayInObjectLiteral, hasThrowStatements, hasStdMathCalls, hasConsoleCalls, isConsoleCall, getConsoleMethod, isRuntimeExpression, statementRequiresRuntime, collectPointerVarTypes, collectExpressionIdentifiers, } from "./type-inference.js";
-export { toPascalCaseLocal, generateAsyncTaskClass, type AsyncTaskClassResult, } from "./async-state-machine.js";
+export { inferObjectFieldType, collectNestedStructDefs, hasArrayInObjectLiteral, hasThrowStatements, hasStdMathCalls, isRuntimeExpression, statementRequiresRuntime, collectPointerVarTypes, collectExpressionIdentifiers, } from "./type-inference.js";
+export { generateAsyncTaskClass, type AsyncTaskClassResult, } from "./async-state-machine.js";
 export { isCuttlefishSDKImport, normalizeInclude, dedupe, resolveTranspiledModuleInclude, applySymbolMap, } from "./include-resolver.js";
-export { normalizeComment, emitCommentLines, } from "./comment-helpers.js";
+export { emitCommentLines, } from "./comment-helpers.js";

package/dist/emit/utils/index.js

@@ -3,10 +3,10 @@
  * Re-exports all utility functions for C++ code emission.
  */
 // Type inference utilities
-export { inferObjectFieldType, collectNestedStructDefs, hasArrayInObjectLiteral, hasThrowStatements, hasStdMathCalls, hasConsoleCalls, isConsoleCall, getConsoleMethod, isRuntimeExpression, statementRequiresRuntime, collectPointerVarTypes, collectExpressionIdentifiers, } from "./type-inference.js";
+export { inferObjectFieldType, collectNestedStructDefs, hasArrayInObjectLiteral, hasThrowStatements, hasStdMathCalls, isRuntimeExpression, statementRequiresRuntime, collectPointerVarTypes, collectExpressionIdentifiers, } from "./type-inference.js";
 // Async state machine utilities
-export { toPascalCaseLocal, generateAsyncTaskClass, } from "./async-state-machine.js";
+export { generateAsyncTaskClass, } from "./async-state-machine.js";
 // Include resolution utilities
 export { isCuttlefishSDKImport, normalizeInclude, dedupe, resolveTranspiledModuleInclude, applySymbolMap, } from "./include-resolver.js";
 // Comment handling utilities
-export { normalizeComment, emitCommentLines, } from "./comment-helpers.js";
+export { emitCommentLines, } from "./comment-helpers.js";

package/dist/emit/utils/type-inference.d.ts

@@ -2,7 +2,7 @@
  * Type inference utilities for C++ code emission.
  * Pure functions with no side effects - extracted from cpp-emitter.ts
  */
-import type { ExpressionIR, StatementIR, PlatformStrategy } from "../../api/index.js";
+import type { ExpressionIR, StatementIR } from "../../api/index.js";
 /**
  * Infers the C++ type for an object field based on its initializer value.
  *
@@ -104,34 +104,6 @@ export declare function hasStdMathCalls(program: {
         };
     }>;
 }): boolean;
-/**
- * Checks if a program contains console.* calls (console.log, console.error, etc.)
- *
- * @param program The program IR to analyze
- * @returns true if console calls are found
- */
-export declare function hasConsoleCalls(program: {
-    topLevelStatements: StatementIR[];
-    functions: Array<{
-        statements: StatementIR[];
-    }>;
-    classes: Array<{
-        methods: Array<{
-            statements: StatementIR[];
-        }>;
-        constructor?: {
-            statements: StatementIR[];
-        };
-    }>;
-}, strategy?: PlatformStrategy): boolean;
-/**
- * Checks if a callee is a console method call (e.g., "console.log", "console.error")
- */
-export declare function isConsoleCall(callee: string, strategy?: PlatformStrategy): boolean;
-/**
- * Gets the console method name from a callee (e.g., "log" from "console.log")
- */
-export declare function getConsoleMethod(callee: string): string;
 /**
  * Checks if an expression requires runtime execution (cannot be evaluated at global scope in C++).
  * Compile-time expressions can be placed at global scope; runtime expressions must go in setup()/main().

package/dist/emit/utils/type-inference.js

@@ -330,81 +330,6 @@ export function hasStdMathCalls(program) {
     }
     return false;
 }
-/**
- * Checks if a program contains console.* calls (console.log, console.error, etc.)
- *
- * @param program The program IR to analyze
- * @returns true if console calls are found
- */
-export function hasConsoleCalls(program, strategy) {
-    const checkStatements = (statements) => {
-        for (const stmt of statements) {
-            if (stmt.kind === "call" && isConsoleCall(stmt.callee, strategy)) {
-                return true;
-            }
-            // Check nested statements in control flow
-            if ("body" in stmt && Array.isArray(stmt.body)) {
-                if (checkStatements(stmt.body))
-                    return true;
-            }
-            if ("thenBranch" in stmt && Array.isArray(stmt.thenBranch)) {
-                if (checkStatements(stmt.thenBranch))
-                    return true;
-            }
-            if ("elseBranch" in stmt && Array.isArray(stmt.elseBranch)) {
-                if (checkStatements(stmt.elseBranch))
-                    return true;
-            }
-            if ("cases" in stmt && Array.isArray(stmt.cases)) {
-                for (const c of stmt.cases) {
-                    if (checkStatements(c.body))
-                        return true;
-                }
-            }
-            if ("tryBlock" in stmt && Array.isArray(stmt.tryBlock)) {
-                if (checkStatements(stmt.tryBlock))
-                    return true;
-            }
-            if ("catchBlock" in stmt && Array.isArray(stmt.catchBlock)) {
-                if (checkStatements(stmt.catchBlock))
-                    return true;
-            }
-        }
-        return false;
-    };
-    // Check all functions
-    for (const fn of program.functions) {
-        if (checkStatements(fn.statements))
-            return true;
-    }
-    // Check top-level statements
-    if (checkStatements(program.topLevelStatements))
-        return true;
-    // Check class methods
-    for (const cls of program.classes) {
-        for (const method of cls.methods) {
-            if (checkStatements(method.statements))
-                return true;
-        }
-        if (cls.constructor && checkStatements(cls.constructor.statements))
-            return true;
-    }
-    return false;
-}
-/**
- * Checks if a callee is a console method call (e.g., "console.log", "console.error")
- */
-export function isConsoleCall(callee, strategy) {
-    if (strategy)
-        return strategy.isConsoleCall(callee);
-    return callee.startsWith("console.");
-}
-/**
- * Gets the console method name from a callee (e.g., "log" from "console.log")
- */
-export function getConsoleMethod(callee) {
-    return callee.slice("console.".length);
-}
 /**
  * Checks if an expression requires runtime execution (cannot be evaluated at global scope in C++).
  * Compile-time expressions can be placed at global scope; runtime expressions must go in setup()/main().

package/dist/framework-package.d.ts

@@ -5,6 +5,9 @@
  * Optional exports include `Toolchain`, `SYMBOL_KINDS`, library resolver,
  * class name map builder, and lib declaration generator.
  *
+ * Built-in frameworks (see BUILTIN_FRAMEWORK_MODULES) are loaded from this
+ * package directly; everything else resolves from the project directory.
+ *
  * Returns the raw module for backward compatibility.
  */
 export declare function loadFrameworkPackage(packageName: string, fromDir?: string): any;

package/dist/framework-package.js

@@ -2,7 +2,18 @@ import path from "node:path";
 import { createRequire } from "node:module";
 import { setLoadedFramework } from "./framework-registry.js";
 import { registerPlatformStrategy } from "./platform/registry.js";
+import * as nativeFramework from "./frameworks/native/index.js";
 const require = createRequire(import.meta.url);
+/**
+ * Frameworks that ship inside @typecad/cuttlefish instead of as separate
+ * @typecad/framework-* npm packages. Their config string stays the historical
+ * package name for continuity; the module is loaded directly instead of via
+ * require.resolve. (The native framework was merged in from the former
+ * @typecad/framework-native package.)
+ */
+const BUILTIN_FRAMEWORK_MODULES = {
+    "@typecad/framework-native": nativeFramework,
+};
 function resolveFrameworkPackage(packageName, fromDir = process.cwd()) {
     try {
         const resolved = require.resolve(packageName, { paths: [path.resolve(fromDir)] });
@@ -29,15 +40,21 @@ function extractToolchain(mod) {
  * Optional exports include `Toolchain`, `SYMBOL_KINDS`, library resolver,
  * class name map builder, and lib declaration generator.
  *
+ * Built-in frameworks (see BUILTIN_FRAMEWORK_MODULES) are loaded from this
+ * package directly; everything else resolves from the project directory.
+ *
  * Returns the raw module for backward compatibility.
  */
 export function loadFrameworkPackage(packageName, fromDir = process.cwd()) {
-    const packagePath = resolveFrameworkPackage(packageName, fromDir);
-    if (!packagePath) {
-        throw new Error(`Unable to resolve framework package '${packageName}' from '${fromDir}'. ` +
-            `Install it or pass a different framework package name in your TypeCAD config.`);
-    }
-    const mod = require(packagePath);
+    const builtin = BUILTIN_FRAMEWORK_MODULES[packageName];
+    const mod = builtin ?? (() => {
+        const packagePath = resolveFrameworkPackage(packageName, fromDir);
+        if (!packagePath) {
+            throw new Error(`Unable to resolve framework package '${packageName}' from '${fromDir}'. ` +
+                `Install it or pass a different framework package name in your TypeCAD config.`);
+        }
+        return require(packagePath);
+    })();
     // Populate the registry with the loaded framework components
     if (mod.FrameworkStrategy) {
         const strategy = new mod.FrameworkStrategy();

package/dist/framework-registry.d.ts

@@ -4,11 +4,11 @@ import type { CompileResult, UploadResult, ToolchainOptions } from "./api/shared
  * Components loaded from a framework package.
  */
 export interface LoadedFramework {
-    /** The platform strategy (e.g. ArduinoStrategy, NativeAVRStrategy) */
+    /** The platform strategy (e.g. ZephyrStrategy, NativeStrategy) */
     strategy: PlatformStrategy;
     /** Optional toolchain for compile/upload/monitor (framework-specific) */
     toolchain?: FrameworkToolchain;
-    /** Framework library import resolution (e.g., Arduino library detection) */
+    /** Framework library import resolution (e.g., framework library detection) */
     libraryResolver?: FrameworkLibraryResolver;
     /** Framework class name mapping for library imports */
     classNameMapBuilder?: (imports: any[]) => Map<string, string>;
@@ -18,15 +18,15 @@ export interface LoadedFramework {
      * Optional subcommand presenters owned by the framework. Cuttlefish dispatches
      * `cuttlefish doctor` / `cuttlefish licenses` to these when the loaded
      * framework provides them; otherwise it prints a no-support message. Each
-     * framework decides what (if anything) these do — e.g. framework-arduino
-     * checks arduino-cli + board core (doctor) and scans Arduino library licenses
+     * framework decides what (if anything) these do — e.g. framework-zephyr
+     * checks west + board target (doctor) and scans library licenses
      * (licenses).
      */
     doctor?: () => void;
     licenses?: (strict: boolean, all: boolean) => void;
 }
 /**
- * Resolves framework-specific library imports (e.g., Arduino libraries).
+ * Resolves framework-specific library imports.
  */
 export interface FrameworkLibraryResolver {
     isFrameworkLibraryImport(moduleSpecifier: string): boolean;

package/dist/frameworks/native/graphics/terminal-preview.d.ts

@@ -0,0 +1,5 @@
+import type { DisplayHALOp } from '../../../api/shared/index.js';
+export declare function resolveTerminalPreviewOp(op: DisplayHALOp): {
+    code?: string;
+    expression?: string;
+} | undefined;

package/dist/frameworks/native/graphics/terminal-preview.js

@@ -0,0 +1,33 @@
+// ---------------------------------------------------------------------------
+// Terminal preview — renders display ops as ANSI-colored cells to stdout
+//
+// Lets authors preview a UI on the host with no hardware. Colors map rgb565
+// back to the nearest ANSI 16-color for display only.
+// ---------------------------------------------------------------------------
+/** Map an rgb565 value to an ANSI color code (approximate). */
+function rgb565ToAnsi(c) {
+    const r5 = (c >> 11) & 0x1f;
+    const g6 = (c >> 5) & 0x3f;
+    const b5 = c & 0x1f;
+    const r = r5 >> 3, g = g6 >> 4, b = b5 >> 3; // 0/1 per channel
+    // ANSI 16-color: foreground 30+bit pattern
+    return 30 + (r ? 1 : 0) + (g ? 2 : 0) + (b ? 4 : 0);
+}
+export function resolveTerminalPreviewOp(op) {
+    switch (op.operation) {
+        case "display.init":
+            return { code: `/* native preview: ${op.driver} ${op.width}x${op.height} initialized */` };
+        case "display.fill_rect":
+            return {
+                code: `/* preview fill_rect ${op.x},${op.y} ${op.w}x${op.h} color=0x${op.color.toString(16)} ansi=${rgb565ToAnsi(op.color)} */`,
+            };
+        case "display.draw_rect":
+            return { code: `/* preview draw_rect ${op.x},${op.y} ${op.w}x${op.h} */` };
+        case "display.draw_text":
+            return { code: `/* preview draw_text ${op.x},${op.y} "${op.text}" */` };
+        case "display.flush":
+            return { code: `/* preview flush ${op.rects.length} rect(s) */` };
+        default:
+            return undefined;
+    }
+}

package/dist/frameworks/native/index.d.ts

@@ -0,0 +1,3 @@
+export { NativeStrategy, NativeStrategy as FrameworkStrategy } from './strategy.js';
+export { NativeToolchain as Toolchain } from './native-compile.js';
+export type { NativeCompileConfig } from './native-config.js';

package/dist/frameworks/native/index.js

@@ -0,0 +1,15 @@
+// ---------------------------------------------------------------------------
+// Native C++ framework — built into @typecad/cuttlefish
+//
+// Outputs standard C++ for portable Windows/Linux desktop executables.
+// Uses main(), std::string, and std::thread-based async.
+//
+// Usage:
+//   In cuttlefish.config.ts:
+//     framework: '@typecad/framework-native'
+// (The config string keeps the historical package name; the module is
+//  loaded directly by framework-package.ts, no npm package involved.)
+// ---------------------------------------------------------------------------
+export { NativeStrategy, NativeStrategy as FrameworkStrategy } from './strategy.js';
+// Native C++ toolchain (g++/clang++ compilation)
+export { NativeToolchain as Toolchain } from './native-compile.js';

package/dist/frameworks/native/native-compile.d.ts

@@ -0,0 +1,17 @@
+import type { CompileResult, ToolchainOptions } from '../../api/shared/index.js';
+/**
+ * Resolve the -l link libraries for a native build.
+ *
+ * The SDL display driver (#include <SDL2/SDL.h>) requires core SDL2 at link
+ * time on every platform; Windows/MSYS2 additionally needs -lmingw32 and
+ * -lSDL2main for the Win32 GUI entry-point glue (the SDL_MAIN_HANDLED define
+ * + SDL_SetMainReady() in display_init). Because the cuttlefish config loader
+ * is AST-only (it cannot evaluate process.platform conditionals), these libs
+ * are auto-provided here when the `sdl` display driver is active, so a single
+ * config links on both Windows and Linux without a platform-specific
+ * `native.libraries` array. User-supplied libraries are appended (deduped).
+ */
+export declare function resolveLinkLibraries(display: Record<string, unknown> | undefined, userLibs: string[]): string[];
+export declare const NativeToolchain: {
+    compile(options: ToolchainOptions): CompileResult;
+};

package/dist/frameworks/native/native-compile.js

@@ -0,0 +1,170 @@
+// ---------------------------------------------------------------------------
+// Native C++ compilation toolchain
+//
+// Compiles generated C++ into a native executable using g++ or clang++.
+// ---------------------------------------------------------------------------
+import path from "node:path";
+import fs from "node:fs";
+import { spawnSync } from "node:child_process";
+import { parseCompileErrors, collectCppFiles } from '../../api/shared/index.js';
+function findCppSource(outputDir, sourcePath) {
+    if (sourcePath.endsWith(".cpp") && fs.existsSync(sourcePath)) {
+        return sourcePath;
+    }
+    if (fs.existsSync(outputDir)) {
+        const entries = fs.readdirSync(outputDir);
+        const cppFile = entries.find((e) => e.endsWith(".cpp"));
+        if (cppFile)
+            return path.join(outputDir, cppFile);
+    }
+    throw new Error(`No .cpp source file found in ${outputDir}`);
+}
+function detectCompiler() {
+    // On Windows, also try MSYS2/MinGW paths that may not be in PATH
+    const candidates = ["g++", "clang++"];
+    if (process.platform === "win32") {
+        candidates.unshift("C:\\msys64\\ucrt64\\bin\\g++.exe", "C:\\msys64\\mingw64\\bin\\g++.exe");
+    }
+    for (const cmd of candidates) {
+        try {
+            const r = spawnSync(cmd, ["--version"], {
+                encoding: "utf8",
+                timeout: 5000,
+            });
+            if (r.status === 0) {
+                // On Windows, ensure the compiler's bin dir is first in PATH
+                // so g++ can find its internal tools (as, ld, cc1plus, etc.)
+                let env;
+                if (process.platform === "win32" && cmd.includes("\\")) {
+                    const binDir = path.dirname(cmd);
+                    const pathSep = ";";
+                    const existing = process.env.PATH ?? "";
+                    env = { ...process.env, PATH: `${binDir}${pathSep}${existing}` };
+                }
+                return { cmd, env };
+            }
+        }
+        catch { /* not found */ }
+    }
+    throw new Error("No C++ compiler found. Install g++ or clang++ and ensure it is in your PATH." +
+        (process.platform === "win32"
+            ? " On Windows, install MSYS2 (https://www.msys2.org/) and add C:\\msys64\\ucrt64\\bin to your PATH."
+            : ""));
+}
+function warningFlags(level) {
+    switch (level) {
+        case "none": return ["-w"];
+        case "all": return ["-Wall"];
+        case "extra": return ["-Wall", "-Wextra"];
+        case "error": return ["-Wall", "-Wextra", "-Werror"];
+        default: return ["-Wall"];
+    }
+}
+/**
+ * Resolve the -l link libraries for a native build.
+ *
+ * The SDL display driver (#include <SDL2/SDL.h>) requires core SDL2 at link
+ * time on every platform; Windows/MSYS2 additionally needs -lmingw32 and
+ * -lSDL2main for the Win32 GUI entry-point glue (the SDL_MAIN_HANDLED define
+ * + SDL_SetMainReady() in display_init). Because the cuttlefish config loader
+ * is AST-only (it cannot evaluate process.platform conditionals), these libs
+ * are auto-provided here when the `sdl` display driver is active, so a single
+ * config links on both Windows and Linux without a platform-specific
+ * `native.libraries` array. User-supplied libraries are appended (deduped).
+ */
+export function resolveLinkLibraries(display, userLibs) {
+    const libs = [];
+    if (display?.driver === "sdl") {
+        if (process.platform === "win32") {
+            // mingw32 (WinMain CRT glue) → SDL2main (SDL_main) → SDL2 (core).
+            libs.push("mingw32", "SDL2main", "SDL2");
+        }
+        else {
+            libs.push("SDL2");
+        }
+    }
+    for (const lib of userLibs) {
+        if (!libs.includes(lib))
+            libs.push(lib);
+    }
+    return libs;
+}
+export const NativeToolchain = {
+    compile(options) {
+        const nativeConfig = (options.frameworkConfig ?? {});
+        let cppFiles = collectCppFiles(options.outputDir);
+        if (cppFiles.length === 0) {
+            const fallback = findCppSource(options.outputDir, options.sourcePath);
+            cppFiles.push(fallback);
+        }
+        const exeExt = process.platform === "win32" ? ".exe" : ".out";
+        const exeFile = cppFiles[0].replace(/\.cpp$/, exeExt);
+        // Use configured compiler or auto-detect
+        const detected = detectCompiler();
+        const compiler = nativeConfig.compiler ?? detected.cmd;
+        const env = detected.env;
+        const flags = [];
+        // C++ standard
+        flags.push(`-std=${nativeConfig.cxxStandard ?? "c++17"}`);
+        // Optimization: always -O2. The old `output.optimize` config knob was
+        // removed from cuttlefish ("framework territory" — see config-loader's
+        // deprecation note); nothing can populate a ToolchainOptions.optimize, so
+        // these branches were dead code that never type-checked.
+        flags.push("-O2");
+        // Warning level
+        flags.push(...warningFlags(nativeConfig.warnings));
+        // Static linking (default: true on Windows, false elsewhere)
+        const staticLink = nativeConfig.staticLink ?? (process.platform === "win32");
+        if (staticLink)
+            flags.push("-static");
+        // Windows GUI subsystem: link as a windowed app, not a console app. Without
+        // -mwindows, MinGW produces a console-subsystem executable that spawns a
+        // cmd.exe window behind the SDL window on launch. This is the standard flag
+        // for any SDL/Win32 GUI program built with g++ on MSYS2/MinGW. No-op on
+        // Linux/macOS (no console-subsystem concept there).
+        if (process.platform === "win32")
+            flags.push("-mwindows");
+        // Include paths
+        if (nativeConfig.includePaths) {
+            for (const p of nativeConfig.includePaths)
+                flags.push(`-I${p}`);
+        }
+        // Library paths
+        if (nativeConfig.libraryPaths) {
+            for (const p of nativeConfig.libraryPaths)
+                flags.push(`-L${p}`);
+        }
+        // Generic extra flags and defines
+        if (options.extraFlags)
+            flags.push(...options.extraFlags);
+        if (options.defines) {
+            for (const [k, v] of Object.entries(options.defines)) {
+                flags.push(`-D${k}=${v}`);
+            }
+        }
+        // Build args: flags + source + output, then -l flags last (GCC ordering).
+        // SDL2 link libs are auto-provided when the `sdl` display driver is active
+        // (see resolveLinkLibraries) — the AST config loader can't evaluate
+        // platform conditionals, so this keeps a single config portable across
+        // Windows/Linux/macOS. User-supplied native.libraries are merged in.
+        const linkLibs = resolveLinkLibraries(options.display, nativeConfig.libraries ?? []).map((lib) => `-l${lib}`);
+        const args = [...flags, ...cppFiles, "-o", exeFile, ...linkLibs];
+        const result = spawnSync(compiler, args, {
+            encoding: "utf8",
+            timeout: 120000,
+            env: env ?? process.env,
+        });
+        let output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`.trim();
+        if (result.status === 0) {
+            output = `${compiler} -> ${exeFile}`;
+        }
+        else if (result.error) {
+            output = `Compiler error: ${result.error.message}\n${output}`.trim();
+        }
+        else if (!output) {
+            output = `Compiler exited with code ${result.status} (no output). Command: ${compiler} ${args.join(" ")}`;
+        }
+        const errors = parseCompileErrors(output, options.outputDir);
+        return { success: result.status === 0, output, errors };
+    },
+};

package/dist/frameworks/native/native-config.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Native C++ compilation configuration.
+ *
+ * @example
+ * ```ts
+ * // TypeCAD.config.ts
+ * const config: TypeCADConfig = {
+ *   framework: '@typecad/framework-native',
+ *   native: {
+ *     compiler: 'clang++',
+ *     cxxStandard: 'c++20',
+ *     warnings: 'extra',
+ *     includePaths: ['./vendor/include'],
+ *     libraries: ['curl'],
+ *   },
+ * };
+ * ```
+ */
+export interface NativeCompileConfig {
+    /** Override auto-detected compiler (e.g. 'clang++', 'g++-12'). */
+    compiler?: string;
+    /** C++ standard (e.g. 'c++17', 'c++20'). Default: 'c++17'. */
+    cxxStandard?: string;
+    /** Additional include directories (-I flags). */
+    includePaths?: string[];
+    /** Library search directories (-L flags). */
+    libraryPaths?: string[];
+    /**
+     * Libraries to link (-l flags, without the 'lib' prefix).
+     *
+     * Note: when the `sdl` display driver is active, SDL2 link libraries are
+     * auto-provided per platform by NativeToolchain (-lmingw32 -lSDL2main -lSDL2
+     * on Windows, -lSDL2 elsewhere); this field is for additional user libraries
+     * and is appended (deduped) after the auto-provided set.
+     */
+    libraries?: string[];
+    /** Warning level: 'none', 'basic', 'all', 'extra', 'error'. Default: 'basic'. */
+    warnings?: string;
+    /** Static linking toggle. Default: true on Windows, false elsewhere. */
+    staticLink?: boolean;
+}

package/dist/frameworks/native/native-config.js

@@ -0,0 +1,7 @@
+// ---------------------------------------------------------------------------
+// Native C++ compilation configuration
+//
+// Place under the `native` key in TypeCAD.config.ts to customize
+// how g++/clang++ compiles your generated C++ code.
+// ---------------------------------------------------------------------------
+export {};