crossbind 0.0.1 → 2.0.0-beta.50

package/src/state/loadConfig.js

@@ -0,0 +1,215 @@
+import os from 'node:os';
+import fs from 'node:fs';
+import systemKeys from '../utils/systemKeys.js';
+import loadJs from '../utils/loadJs.js';
+import {
+    resolveDependencyOverride, resolveDependencyReplace, restampIdentity, resolveExcludedNames, getOverrideKey,
+} from '../utils/overrideDependency.js';
+import loadJson from '../utils/loadJson.js';
+import getParentPath from '../utils/getParentPath.js';
+import getAbsolutePath from '../utils/getAbsolutePath.js';
+import fixPackageName from '../utils/fixPackageName.js';
+import getCMakeListsFilePath from '../utils/getCMakeListsFilePath.js';
+import calculateDependencyParameters from './calculateDependencyParameters.js';
+import logger from '../utils/logger.js';
+// import getCmakeParameters from './getCmakeParameters.js';
+
+export default async function loadConfig(configDir = process.cwd(), configName = 'crossbind.config') {
+    const config = await loadJs(configDir, configName) || {};
+    if (config.excludedDependencies?.length) {
+        logger.info('crossbind: `excludedDependencies` in crossbind.config.js is no longer read — declare exclusions in crossbind.overrides.js as { <name>: false }.');
+    }
+    const overrides = await loadJs(configDir, 'crossbind.overrides');
+    const exclude = resolveExcludedNames(overrides);
+    const seen = new Set();
+    const output = getFilledConfig(config, { isDepend: false, exclude, seen, replaces: overrides });
+    output.excludedDependencies = exclude;
+
+    const build = await loadJs(configDir, 'crossbind.build');
+
+    if (build) {
+        build.withBuildConfig = true;
+    }
+    output.build = { ...build, ...output.build };
+
+    if (overrides) {
+        Object.entries(overrides).forEach(([key, value]) => {
+            if (!value || typeof value !== 'object') {
+                logger.info(`crossbind: crossbind.overrides["${key}"] must be an object — { rebuild: true } / { exclude: true } / { replace: ... }.`);
+            }
+        });
+        output.allDependencies.forEach((d) => {
+            const resolved = resolveDependencyOverride(overrides, d);
+            if (resolved) {
+                d.overrideBuild = resolved.override;
+                d.rebuild = true;
+            }
+        });
+        const unmatched = Object.keys(overrides).filter((k) => !seen.has(k));
+        if (unmatched.length) {
+            logger.info(`crossbind: crossbind.overrides entries not matched to any dependency: ${unmatched.join(', ')}. Available: ${[...seen].sort().join(', ')}`);
+        }
+    }
+
+    // Consume any dependency already rebuilt from source (buildDependencies writes the marker) so the
+    // fresh artifacts win across processes — e.g. Android rebuilds at the Gradle config phase and is
+    // consumed when the CMake phase reloads the config.
+    output.allDependencies.forEach((d) => {
+        const depsDir = `${output.paths.cache}/deps/${d.general.name}`;
+        const meta = loadJson(`${depsDir}/.crossbind-rebuild.json`);
+        if (!meta || meta.key !== getOverrideKey(d)) return;
+        if (!fs.existsSync(`${depsDir}/dist/prebuilt/CMakeLists.txt`)) {
+            logger.info(`crossbind: rebuilt cache for "${d.general.name}" is incomplete (missing dist/prebuilt/CMakeLists.txt) — using prebuilt. Rebuild, or reset with \`crossbind clean-deps\`.`);
+            return;
+        }
+        d.paths.output = `${depsDir}/dist`;
+        if (d.export.libName.some((n) => fs.existsSync(`${depsDir}/${n}.xcframework`))) {
+            d.paths.project = depsDir;
+        }
+    });
+
+    output.paths.systemConfig = `${os.homedir()}/.crossbind.json`;
+    output.system = loadJson(output.paths.systemConfig) || {};
+
+    Object.entries(systemKeys).forEach(([key, value]) => {
+        if (!(key in output.system)) {
+            output.system[key] = value.default;
+        }
+    });
+
+    return output;
+}
+
+export function getFilledConfig(config, options = { isDepend: false }) {
+    const exclude = options.exclude || [];
+    const { seen, replaces } = options;
+
+    const dependencies = (config.dependencies || [])
+        .map((d) => {
+            const filled = getFilledConfig(d, { isDepend: true, exclude, seen, replaces });
+            const replacement = resolveDependencyReplace(replaces, filled);
+            if (!replacement) return filled;
+            return restampIdentity(getFilledConfig(replacement, { isDepend: true, exclude, seen, replaces }), filled);
+        })
+        .filter((fd) => {
+            const names = [fd.general.name, fd.package?.name, fd.general.alias?.package].filter(Boolean);
+            names.forEach((n) => seen?.add(n));
+            return !names.some((n) => exclude.includes(n));
+        });
+
+    const newConfig = {
+        general: config.general || {},
+        dependencies,
+        cargoDependencies: config.cargoDependencies || {},
+        // 'sync' types the direct surface; 'promise' wraps every generated method return
+        // for useWorker-style runtimes (constructors stay sync-typed: await new X()).
+        dts: config.dts || 'sync',
+        // Opt-in package type publishing: emit <output>/types/index.d.ts over the public
+        // headers and wire package.json types/typesVersions (see actions/buildTypes.js).
+        types: config.types || false,
+        // Cloned: raw crossbind.config modules are import singletons; later path mutations
+        // (e.g. rebuild-marker consumption) must not leak into them across loadConfig calls.
+        paths: { ...(config.paths || {}) },
+        ext: config.ext || {},
+        export: config.export || {},
+        targetSpecs: config.targetSpecs || [],
+        build: config.build || {},
+        target: config.target || {},
+        extensions: config.extensions || [],
+        package: null,
+        functions: config.functions || {},
+    };
+
+    if (!['sync', 'promise'].includes(newConfig.dts)) {
+        throw new Error(`crossbind: "dts" must be 'sync' or 'promise' (got '${newConfig.dts}').`);
+    }
+    if (typeof newConfig.types !== 'boolean') {
+        throw new Error(`crossbind: "types" must be true or false (got '${newConfig.types}').`);
+    }
+
+    if (newConfig.paths.config && !newConfig.paths.project) {
+        newConfig.paths.project = getParentPath(newConfig.paths.config);
+    }
+
+    if (!newConfig.paths.project) {
+        newConfig.paths.project = process.cwd();
+    } else {
+        newConfig.paths.project = getAbsolutePath(null, newConfig.paths.project);
+    }
+
+    newConfig.package = loadJson(`${newConfig.paths.project}/package.json`);
+
+    if (!newConfig?.general?.name) {
+        if (!newConfig.package) {
+            throw new Error(`crossbind: no package.json found in ${newConfig.paths.project}. Run crossbind from your project root, or scaffold a project with \`npm create crossbind\`.`);
+        }
+        newConfig.general.name = fixPackageName(newConfig.package.name) || 'crossbindsample';
+    }
+
+    const getPath = getAbsolutePath.bind(null, newConfig.paths.project);
+
+    newConfig.paths.base = getPath(newConfig.paths.base) || newConfig.paths.project;
+    newConfig.paths.cache = getPath(newConfig.paths.cache) || getPath('.crossbind');
+    newConfig.paths.build = getPath(newConfig.paths.build) || getPath(`${newConfig.paths.cache}/build`);
+    newConfig.paths.native = (newConfig.paths.native || ['src/native']).map((p) => getPath(p));
+    newConfig.paths.module = (newConfig.paths.module || newConfig.paths.native).map((p) => getPath(p));
+    newConfig.paths.header = (newConfig.paths.header || newConfig.paths.native).map((p) => getPath(p));
+    newConfig.paths.bridge = (newConfig.paths.bridge || [...newConfig.paths.native, newConfig.paths.build])
+        .map((p) => getPath(p));
+    newConfig.paths.output = getPath(newConfig.paths.output) || newConfig.paths.build;
+    newConfig.paths.cmake = options.isDepend ? getPath(getCMakeListsFilePath(newConfig.paths.output)) : (
+        getPath(newConfig.paths.cmake || getCMakeListsFilePath(newConfig.paths.project))
+    );
+    newConfig.paths.cmakeDir = getParentPath(newConfig.paths.cmake);
+    newConfig.paths.cli = getParentPath(getParentPath(import.meta.url));
+    newConfig.paths.cliCMakeListsTxt = `${newConfig.paths.cli}/assets/cmake/CMakeLists.txt`;
+
+    newConfig.ext.header = newConfig.ext.header || ['h', 'hpp', 'hxx', 'hh'];
+    newConfig.ext.source = newConfig.ext.source || ['c', 'cpp', 'cxx', 'cc'];
+    newConfig.ext.module = newConfig.ext.module || ['i'];
+
+    newConfig.export.type = newConfig.export.type || 'cmake';
+    newConfig.export.header = newConfig.export.header || 'include';
+    newConfig.export.libPath = getPath(newConfig.export.libPath || 'lib');
+    newConfig.export.libName = newConfig.export.libName || [newConfig.general.name];
+    newConfig.export.binHeaders = newConfig.export.binHeaders || [];
+    newConfig.export.bundle = newConfig.export.bundle ?? true;
+
+    newConfig.allDependencies = (() => {
+        const output = {};
+        [...newConfig.dependencies, ...newConfig.dependencies.map((d) => d.allDependencies).flat()].forEach((d) => {
+            output[d.paths.project] = d;
+        });
+        return Object.values(output);
+    })();
+
+    newConfig.extensions?.forEach(e => {
+        e?.loadConfig?.after(newConfig);
+    });
+
+    if (newConfig.target.runtime !== 'mt' && newConfig.allDependencies.some((d) => d?.target?.runtime === 'mt')) {
+        newConfig.target.runtime = 'mt';
+    }
+
+    newConfig.functions.isEnabled = newConfig.functions.isEnabled || ((target) => {
+        // Source-cmake packages ship no prebuilt at all: their own CMakeLists (at the
+        // package root, not a generated dist/prebuilt one) is compiled into the consuming
+        // build via add_subdirectory, so they serve every target.
+        const isSourceCmakePackage = newConfig.export?.type === 'cmake'
+            && newConfig.paths.cmake !== newConfig.paths.cliCMakeListsTxt
+            && !newConfig.paths.cmakeDir.endsWith('/prebuilt')
+            && fs.existsSync(newConfig.paths.cmake);
+
+        return (
+            isSourceCmakePackage
+            || fs.existsSync(`${newConfig.paths.cmakeDir}/${target.path}`)
+            || fs.existsSync(`${newConfig.paths.cmakeDir}/${target.releasePath}`)
+            || (target.platform === 'ios' && fs.existsSync(`${newConfig.paths.cmakeDir}/../../${newConfig.general.name}-${target.runtime}.xcframework`))
+        );
+    });
+
+    newConfig.dependencyParameters = calculateDependencyParameters(newConfig);
+    // newConfig.cmakeParameters = getCmakeParameters(newConfig);
+
+    return newConfig;
+}

package/src/utils/appRustCrates.js

@@ -0,0 +1,106 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { cargoTripleFor } from './cargoTarget.js';
+import { isMtWasm, assertMtRustToolchain, cargoTargetDirFor, cargoBuildInvocation } from './rustMt.js';
+import runCargo from './runCargo.js';
+import { sysrootFor } from './rustSysroot.js';
+import { relPath } from './rustBridgeGen.js';
+import writeIfChanged from './writeIfChanged.js';
+
+const SUPER = '_app_super';
+
+// App-local Rust surfaces (imported .rs files) live as rlib bridge crates under
+// <project>/.crossbind/rust-bridges/ (written by the bundler transformer on import). They are
+// bundled into ONE super staticlib here - a single libstd, so the consumer may safely
+// force_load/whole-archive exactly this archive next to keep-symbol-linked Rust packages.
+export default function buildAppRustCrates(target, cacheDir, cargoDependencies = null, log = console.log) {
+    const root = `${cacheDir}/rust-bridges`;
+    if (!fs.existsSync(root)) return [];
+    let crates = fs.readdirSync(root, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && e.name !== SUPER && fs.existsSync(`${root}/${e.name}/Cargo.toml`))
+        .map((e) => e.name);
+
+    // Prune bridges whose source of truth is gone. An app-local surface whose .rs was deleted
+    // breaks cargo on the missing #[path] target; a crate_ bridge whose cargoDependencies entry
+    // was removed silently keeps dead registrations in every later binary. crate_ pruning only
+    // runs when the caller passes the current cargoDependencies - null means "don't judge".
+    crates = crates.filter((name) => {
+        const dir = `${root}/${name}`;
+        const libRs = `${dir}/src/lib.rs`;
+        const src = fs.existsSync(libRs) ? fs.readFileSync(libRs, 'utf8') : '';
+        const pathMod = src.match(/#\[path = "(.+?)"\]\s*\r?\nmod user;/);
+        let stale = false;
+        if (pathMod) {
+            // #[path] is written relative to the file that carries it, so it has to be resolved
+            // against that directory - resolving it against cwd finds nothing and prunes a
+            // perfectly live bridge.
+            stale = !fs.existsSync(path.resolve(path.dirname(libRs), pathMod[1]));
+        } else if (cargoDependencies && name.startsWith('crate_')) {
+            stale = !Object.keys(cargoDependencies)
+                .some((c) => `crate_${c.replace(/[^a-zA-Z0-9_]/g, '_').toLowerCase()}` === name);
+        }
+        if (stale) {
+            fs.rmSync(dir, { recursive: true, force: true });
+            log(`crossbind: pruned stale rust bridge '${name}' - its source is gone`);
+        }
+        return !stale;
+    });
+    if (crates.length === 0) return [];
+
+    const isMt = isMtWasm(target);
+    // true in the image, a downloaded artifact path on a host that has one, false where mt must
+    // still rebuild std - and only that last case needs a nightly toolchain here.
+    const sysroot = sysrootFor(target);
+    if (isMt && !sysroot) assertMtRustToolchain();
+
+    const superDir = `${root}/${SUPER}`;
+    const manifest = [
+        '# Generated by crossbind - do not edit. Bundles every app-local Rust surface.',
+        '[package]',
+        'name = "crossbind-app-super"',
+        'version = "0.0.0"',
+        'edition = "2021"',
+        '',
+        '[lib]',
+        'name = "crossbind_app_super"',
+        'crate-type = ["staticlib"]',
+        '',
+        '[dependencies]',
+        ...crates.map((c) => `${c.replaceAll('_', '-')}-crossbind-app = { path = "${relPath(superDir, `${root}/${c}`)}" }`),
+        '',
+        '[profile.release]',
+        'panic = "abort"',
+        '',
+        '[workspace]',
+        '',
+    ].join('\n');
+    const lib = [
+        '// Generated by crossbind - do not edit. The underscore uses bundle each bridge rlib (and',
+        '// its init-array registrations) into this single staticlib.',
+        ...crates.map((c) => `use ${c}_crossbind_app as _;`),
+        '',
+    ].join('\n');
+    writeIfChanged(`${superDir}/Cargo.toml`, manifest);
+    writeIfChanged(`${superDir}/src/lib.rs`, lib);
+
+    const triple = cargoTripleFor(target);
+    if (!triple) throw new Error(`crossbind: app rust crates do not support platform '${target.platform}/${target.arch}'.`);
+
+    const targetDir = cargoTargetDirFor(superDir, target);
+    const { args, rustflags, panic, allowUnstable } = cargoBuildInvocation({
+        target,
+        triple,
+        targetDir,
+        manifestPath: `${superDir}/Cargo.toml`,
+        sysroot,
+    });
+    const build = runCargo(args, {
+        rustflags, panic, allowUnstable, target,
+    });
+    if (build.status !== 0) {
+        throw new Error(`crossbind: cargo build failed for the app rust super-crate (${triple}${isMt && !sysroot ? ', mt/build-std' : ''}${sysroot ? `, ${isMt ? 'mt' : 'st'} sysroot` : ''})`);
+    }
+    const libFile = `${targetDir}/${triple}/release/libcrossbind_app_super.a`;
+    if (!fs.existsSync(libFile)) throw new Error(`crossbind: expected cargo output ${libFile} not found`);
+    return [libFile];
+}

package/src/utils/binTools.js

@@ -0,0 +1,76 @@
+// Pure helpers for -bin packages (contract C): the recipe's `bin` block is the single
+// source for the tool map; everything else (json, npmignore, dispatcher) derives from it.
+
+export function validateBinConfig(bin) {
+    const tools = bin?.tools ?? {};
+    const names = Object.keys(tools);
+    if (names.length === 0) throw new Error('crossbind: bin.tools is empty');
+    const binaries = names.filter((name) => tools[name].kind === 'binary');
+    const multicall = names.filter((name) => tools[name].kind === 'multicall-entry');
+    if (multicall.length > 0 && binaries.length !== 1) {
+        throw new Error('crossbind: multicall-entry tools need exactly one kind:"binary" host tool');
+    }
+    return { tools, names, binaries, multicall };
+}
+
+export function renderBinJson(bin) {
+    return `${JSON.stringify({ tools: bin.tools }, null, 2)}\n`;
+}
+
+export function renderBinNpmignore(bin) {
+    const published = Object.entries(bin.tools ?? {})
+        .filter(([, tool]) => tool.publish)
+        .map(([name]) => name);
+    return `${[
+        '# GENERATED by crossbind from the recipe bin map (crossbind.build.js) - do not edit.',
+        '*.xcframework.zip',
+        '*.tgz',
+        '.crossbind',
+        '*.dylib',
+        '# bin package: ship only the tools the bin map declares publish:true, plus share/ data.',
+        'dist/prebuilt/**/bin/*',
+        ...published.map((name) => `!dist/prebuilt/**/bin/${name}`),
+        'dist/prebuilt/**/lib',
+        'dist/prebuilt/**/include',
+        'dist/prebuilt/**/share/man',
+        'dist/prebuilt/**/share/doc',
+        'dist/prebuilt/**/share/bash-completion',
+    ].join('\n')}\n`;
+}
+
+// npm command surface: one `<tool>-wasi` shim per shipped tool, all sharing the copied runner.
+export function renderBinCommands(bin) {
+    if (bin.commands === false) return {};
+    return Object.fromEntries(
+        Object.entries(bin.tools ?? {})
+            .filter(([, tool]) => tool.publish)
+            .map(([name]) => [`${name}-wasi`, `bin/${name}-wasi.mjs`]),
+    );
+}
+
+export function renderCommandStub(tool) {
+    return [
+        '#!/usr/bin/env node',
+        '// GENERATED by crossbind from the recipe bin map (crossbind.build.js) - do not edit.',
+        "import { run } from 'crossbind/src/runtime/wasiRun.mjs';",
+        '',
+        `await run(import.meta.url, '${tool}');`,
+        '',
+    ].join('\n');
+}
+
+export function renderDispatcher(bin) {
+    const { binaries, multicall } = validateBinConfig(bin);
+    const host = binaries[0];
+    const symbolOf = (tool) => `${tool}_multicall_main`;
+    return [
+        '#include <cstring>',
+        ...[host, ...multicall].map((tool) => `int ${symbolOf(tool)}(int, char**);`),
+        'int main(int argc, char** argv) {',
+        '    const char* tool = argc > 1 ? argv[1] : "";',
+        ...multicall.map((tool) => `    if (!std::strcmp(tool, "${tool}")) return ${symbolOf(tool)}(argc - 1, argv + 1);`),
+        `    return ${symbolOf(host)}(argc, argv);`,
+        '}',
+        '',
+    ].join('\n');
+}

package/src/utils/bridgeAsyncGuard.js

@@ -0,0 +1,37 @@
+// SWIG registers _JSPI-suffixed methods with emscripten::async(). Registering
+// such a binding in a build WITHOUT -sJSPI aborts emsdk 6 DEBUG builds at
+// embind registration time ("Async bindings are only supported with JSPI"),
+// killing the whole module before anything runs. One bridge .cpp is shared by
+// every target of a package, so the guard has to be a compile-time condition:
+// wrap each async registration in #ifdef CROSSBIND_JSPI, and let createLib define
+// CROSSBIND_JSPI only for targets whose emccFlags carry -sJSPI.
+export default function guardAsyncBindings(bridgeText) {
+    if (!bridgeText.includes('emscripten::async()')) {
+        return bridgeText;
+    }
+
+    const lines = bridgeText.split('\n');
+    const out = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        const alreadyGuarded = i > 0 && lines[i - 1].trim() === '#ifdef CROSSBIND_JSPI';
+        if (!line.includes('emscripten::async()') || alreadyGuarded) {
+            out.push(line);
+            continue;
+        }
+        // Registrations are one chained call per line, optionally closing the
+        // statement. Keep any trailing `;` OUTSIDE the guard so the chain (or
+        // an empty statement) stays valid when CROSSBIND_JSPI is undefined.
+        const match = /^(\s*)(.*?);?\s*$/.exec(line);
+        const indent = match[1];
+        const call = match[2];
+        const endsStatement = /;\s*$/.test(line);
+        out.push('#ifdef CROSSBIND_JSPI');
+        out.push(indent + call);
+        out.push('#endif');
+        if (endsStatement) {
+            out.push(`${indent};`);
+        }
+    }
+    return out.join('\n');
+}

package/src/utils/cargoTarget.js

@@ -0,0 +1,15 @@
+// Maps a crossbind build target to the cargo target triple. Rust is built on the host (the rust
+// toolchain is host-installed), so the host must have the matching linker/SDK: Xcode for apple,
+// a sourced emsdk for wasm, an NDK for android.
+export function cargoTripleFor(target) {
+    switch (target.platform) {
+        case 'wasm':
+            return 'wasm32-unknown-emscripten';
+        case 'ios':
+            return target.arch === 'iphonesimulator' ? 'aarch64-apple-ios-sim' : 'aarch64-apple-ios';
+        case 'android':
+            return target.arch === 'x86_64' ? 'x86_64-linux-android' : 'aarch64-linux-android';
+        default:
+            return null; // wasi (no rust wasip3 target yet) and anything else: unsupported
+    }
+}

package/src/utils/cppDts.js

@@ -0,0 +1,201 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import writeIfChanged from './writeIfChanged.js';
+
+// Best-effort .d.ts for `.h` imports, the C++ analog of the Rust emitDts: parse the
+// binding-rules surface (classes, public methods, primitives/string/shared_ptr), skip
+// anything else WITH a log line, and fall back to `any` for exported symbols the parser
+// did not understand - the export list itself always comes from the bridge (exports.json).
+
+const NUMBER_TYPES = new Set([
+    'int', 'long', 'short', 'float', 'double', 'size_t', 'unsigned',
+    'unsigned char', 'signed char',
+    'int8_t', 'int16_t', 'int32_t', 'int64_t', 'uint8_t', 'uint16_t', 'uint32_t', 'uint64_t',
+    'long long', 'unsigned int', 'unsigned long', 'unsigned short', 'unsigned long long',
+]);
+
+function tsType(raw, classNames, { nullableSharedPtr = false } = {}) {
+    let t = raw.trim().replace(/\bconst\b/g, '').replace(/&/g, '').trim().replace(/\s+/g, ' ');
+    if (t.includes('*')) return null;
+    const vector = t.match(/^std::vector<([\s\S]+)>$/);
+    if (vector) {
+        const inner = tsType(vector[1], classNames);
+        return inner === null || inner === 'void' ? null : `CppVector<${inner}>`;
+    }
+    const shared = t.match(/^std::shared_ptr<\s*(\w+)\s*>$/);
+    if (shared) {
+        if (!classNames.has(shared[1])) return null;
+        // Embind shared_ptr returns can resolve to null; parameters take the plain object.
+        return nullableSharedPtr ? `${shared[1]} | null` : shared[1];
+    }
+    if (t === 'void') return 'void';
+    if (t === 'bool') return 'boolean';
+    if (NUMBER_TYPES.has(t)) return 'number';
+    if (t === 'std::string') return 'string';
+    if (classNames.has(t)) return t;
+    return null;
+}
+
+function parseArgs(rawArgs, classNames) {
+    const trimmed = rawArgs.trim();
+    if (trimmed === '' || trimmed === 'void') return [];
+    const parts = [];
+    let depth = 0;
+    let current = '';
+    for (const ch of trimmed) {
+        if (ch === '<' || ch === '(') depth += 1;
+        if (ch === '>' || ch === ')') depth -= 1;
+        if (ch === ',' && depth === 0) { parts.push(current); current = ''; } else current += ch;
+    }
+    parts.push(current);
+    return parts.map((part, i) => {
+        const noDefault = part.split('=')[0].trim();
+        // Declaration-style unnamed parameter: the whole token is a type.
+        const unnamed = tsType(noDefault, classNames);
+        if (unnamed !== null && unnamed !== 'void') return { name: `arg${i}`, type: unnamed };
+        const m = noDefault.match(/^(.*?)([A-Za-z_]\w*)$/s);
+        if (!m) return null;
+        const type = tsType(m[1], classNames);
+        if (type === null || type === 'void') return null;
+        return { name: m[2] || `arg${i}`, type };
+    });
+}
+
+// Statements are collected at brace depth 0 of the class body; inline bodies and
+// member-initialiser lists after the argument list are skipped.
+function bodyStatements(body) {
+    const statements = [];
+    let current = '';
+    let depth = 0;
+    for (let i = 0; i < body.length; i += 1) {
+        const ch = body[i];
+        if (ch === '{') { depth += 1; continue; }
+        if (ch === '}') { depth -= 1; if (depth === 0) { statements.push(current); current = ''; } continue; }
+        if (depth > 0) continue;
+        if (ch === ';') { statements.push(current); current = ''; continue; }
+        current += ch;
+    }
+    statements.push(current);
+    return statements.map((s) => s.trim()).filter(Boolean);
+}
+
+export function parseCppSurface(source, log = console.log) {
+    const clean = source
+        .replace(/\/\*[\s\S]*?\*\//g, ' ')
+        .replace(/\/\/[^\n]*/g, ' ')
+        .replace(/^[ \t]*#[^\n]*$/gm, ' ');
+
+    const classes = [];
+    const classNames = new Set();
+    const classRe = /\b(class|struct)\s+([A-Za-z_]\w*)\s*(?::[^{]*)?\{/g;
+    const found = [];
+    let m = classRe.exec(clean);
+    while (m) {
+        let depth = 1;
+        let i = classRe.lastIndex;
+        while (i < clean.length && depth > 0) {
+            if (clean[i] === '{') depth += 1;
+            if (clean[i] === '}') depth -= 1;
+            i += 1;
+        }
+        found.push({ kind: m[1], name: m[2], body: clean.slice(classRe.lastIndex, i - 1) });
+        classNames.add(m[2]);
+        m = classRe.exec(clean);
+    }
+
+    // Value-semantics fields only: these are the types embind's .property can expose
+    // without ownership questions (and the worker clone can carry).
+    const FIELD_TYPES = new Set(['number', 'boolean', 'string']);
+
+    for (const cls of found) {
+        let access = cls.kind === 'struct' ? 'public' : 'private';
+        let ctor = null;
+        const methods = [];
+        const fields = [];
+        for (let statement of bodyStatements(cls.body)) {
+            const sections = statement.match(/\b(public|private|protected)\s*:\s*([\s\S]*)$/);
+            if (sections) { access = sections[1]; statement = sections[2].trim(); }
+            if (!statement || access !== 'public') continue;
+            statement = statement.replace(/\)\s*:\s*[\s\S]*$/, ')').replace(/\)\s*const$/, ')').trim();
+
+            const sig = statement.match(/^(static\s+)?(?:explicit\s+)?([\w:<>,\s*&]*?)\s*\b([A-Za-z_]\w*)\s*\(([\s\S]*)\)$/);
+            if (!sig) {
+                const decl = statement.split('=')[0].trim();
+                const field = !statement.includes('(') && !/^(static|using|typedef|friend|enum)\b/.test(decl)
+                    ? decl.match(/^(.*?)\b([A-Za-z_]\w*)$/s)
+                    : null;
+                if (field) {
+                    const type = tsType(field[1], classNames);
+                    if (type !== null && FIELD_TYPES.has(type)) fields.push({ name: field[2], type });
+                }
+                continue;
+            }
+            const [, staticKw, retRaw, name, argsRaw] = sig;
+            const args = parseArgs(argsRaw, classNames);
+            if (args.includes(null)) { log(`crossbind: dts: skipped ${cls.name}::${name} (unsupported parameter type)`); continue; }
+            if (name === cls.name && retRaw.trim() === '') { ctor = { args }; continue; }
+            if (name.startsWith('~')) continue;
+            const ret = tsType(retRaw, classNames, { nullableSharedPtr: true });
+            if (ret === null) { log(`crossbind: dts: skipped ${cls.name}::${name} (unsupported return type '${retRaw.trim()}')`); continue; }
+            methods.push({ name, isStatic: Boolean(staticKw), args, ret });
+        }
+        classes.push({ name: cls.name, ctor, methods, fields });
+    }
+    return { classes };
+}
+
+export function emitCppDts(model, exportNames, mode = 'sync') {
+    const wrap = (t) => (mode === 'promise' ? `Promise<${t}>` : t);
+    const out = ['// Generated by crossbind - do not edit. Values are usable after init().', ''];
+    const usesVector = model.classes.some((cls) => (cls.ctor?.args ?? []).concat(cls.methods.flatMap((m) => [...m.args, { type: m.ret }]))
+        .some((a) => a.type?.includes('CppVector<')));
+    if (usesVector) {
+        out.push('/** An embind std::vector proxy. Convert with Module.toArray / Module.toVector. */');
+        out.push('export interface CppVector<T> {');
+        out.push(`    size(): ${wrap('number')};`);
+        out.push(`    get(index: number): ${wrap('T')};`);
+        out.push(`    push_back(value: T): ${wrap('void')};`);
+        out.push(`    delete(): ${wrap('void')};`);
+        out.push('}');
+    }
+    const emitted = new Set();
+    for (const cls of model.classes) {
+        if (!exportNames.includes(cls.name)) continue;
+        emitted.add(cls.name);
+        out.push(`export declare class ${cls.name} {`);
+        if (cls.ctor) out.push(`    constructor(${cls.ctor.args.map((a) => `${a.name}: ${a.type}`).join(', ')});`);
+        else out.push('    private constructor();');
+        for (const field of cls.fields ?? []) {
+            out.push(`    ${field.name}: ${field.type};`);
+        }
+        for (const method of cls.methods) {
+            out.push(`    ${method.isStatic ? 'static ' : ''}${method.name}(${method.args.map((a) => `${a.name}: ${a.type}`).join(', ')}): ${wrap(method.ret)};`);
+        }
+        out.push('}');
+    }
+    for (const name of exportNames) {
+        if (!emitted.has(name)) out.push(`export declare const ${name}: any;`);
+    }
+    out.push('export declare let AllSymbols: Record<string, unknown>;');
+    out.push('export declare function initNative(config?: Record<string, unknown>): Promise<unknown>;');
+    out.push('');
+    return out.join('\n');
+}
+
+// Mirror the declaration under <cache>/types/<project-relative>.d.ts - never next to the
+// user's header. Package headers are skipped: their types ship with the package itself.
+export function writeHeaderDts({ headerFile, exportsFile, projectPath, cacheDir, dtsMode = 'sync', log = () => {} }) {
+    if (!fs.existsSync(exportsFile)) return;
+    const relative = path.relative(projectPath, headerFile);
+    if (relative.startsWith('..')) return;
+    let exportNames;
+    try {
+        exportNames = JSON.parse(fs.readFileSync(exportsFile, 'utf8'));
+    } catch (e) {
+        log(`crossbind: dts: unreadable exports file ${exportsFile} (${e.message})`);
+        return;
+    }
+    if (!Array.isArray(exportNames)) return;
+    const model = headerFile.endsWith('.i') ? { classes: [] } : parseCppSurface(fs.readFileSync(headerFile, 'utf8'), log);
+    writeIfChanged(`${cacheDir}/types/${relative}.d.ts`, emitCppDts(model, exportNames, dtsMode));
+}