react-native-gtkx 0.1.0-alpha.4 → 0.2.0-alpha.2

package/dist/sea/assemble.js

@@ -0,0 +1,129 @@
+// Turns a Metro-built app into ONE executable file: bundle everything into
+// a CJS entry (./bundle.ts), generate a SEA blob from it, then inject that
+// blob into a copy of the `node` binary. This is the whole of what "SEA"
+// means — Node's Single Executable Application format is literally a copy
+// of the node binary with a V8 code-cache blob appended, which is why the
+// result necessarily carries Node's own weight (~117 MB on linux-arm64,
+// against <7 MB for the app code and its native addon).
+//
+// Follows gtkx's own tutorial (gtkx-org/gtkx examples/tutorial/scripts/
+// build-sea.sh) for these mechanics; ./bundle.ts's header documents where
+// the bundling half deliberately diverges.
+//
+// Kept out of ../runner/index.ts and reached through a dynamic import so
+// the bundler is only loaded when a SEA is actually asked for; the
+// ordinary `build-linux` path never touches it.
+import { spawnSync } from "node:child_process";
+import { chmodSync, copyFileSync, mkdirSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { bundleMetroSea } from "./bundle.js";
+/** The fuse postject looks for inside the node binary to place the blob. */
+const SENTINEL_FUSE = "NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2";
+/** Pinned: postject has no stable release, and the SEA docs name this one. */
+const POSTJECT = "postject@1.0.0-alpha.6";
+const run = (command, args) => {
+    const result = spawnSync(command, args, { stdio: "inherit" });
+    if (result.error) {
+        throw result.error;
+    }
+    if (result.status !== 0) {
+        throw new Error(`${command} ${args.join(" ")} exited with ${result.status}`);
+    }
+};
+/**
+ * Drops the debug symbols from the copied Node binary. Worth a step of its
+ * own because the saving is not marginal: the `node` binary distributed by
+ * NodeSource for Ubuntu ships `with debug_info, not stripped` — measured at
+ * 117 MB, and 98 MB after `strip --strip-all`. Nothing in a SEA needs those
+ * symbols; the only cost is that a crash inside Node's own C++ produces an
+ * unsymbolicated backtrace.
+ *
+ * Runs BEFORE postject, never after: `--strip-all` removes non-allocated
+ * sections, which is exactly what the injected NODE_SEA_BLOB is.
+ *
+ * Best-effort — a build machine without binutils still produces a working
+ * (larger) executable rather than failing, so this cannot become a new
+ * install requirement for a build that worked yesterday.
+ */
+const stripSymbols = (file) => {
+    const before = statSync(file).size;
+    const result = spawnSync("strip", ["--strip-all", file], {
+        stdio: ["ignore", "ignore", "pipe"],
+    });
+    if (result.error || result.status !== 0) {
+        console.warn("[react-native-gtkx] skipped stripping symbols (no usable `strip`) — " +
+            "the executable will be tens of MB larger than it needs to be");
+        return;
+    }
+    const saved = (before - statSync(file).size) / 1024 / 1024;
+    console.warn(`[react-native-gtkx] stripped debug symbols (-${saved.toFixed(0)} MB)`);
+};
+/**
+ * Produces the middle artifact: one self-contained CJS file with the app,
+ * its whole node_modules closure and the native addon inlined, run by a
+ * system `node`. Everything the SEA is except the embedded Node runtime —
+ * so ~120 MB smaller, at the cost of a `nodejs` dependency to declare.
+ * Returns its size in bytes.
+ */
+export const bundleStandalone = async (options) => {
+    const { appRoot, jsbundlePath, outFile } = options;
+    mkdirSync(dirname(outFile), { recursive: true });
+    console.warn("[react-native-gtkx] bundling a standalone script…");
+    await bundleMetroSea({
+        appRoot,
+        jsbundlePath,
+        outFile,
+        nativeAddonSource: "inline",
+    });
+    return statSync(outFile).size;
+};
+/**
+ * Produces a single executable at {@link AssembleSeaOptions.outFile} and
+ * returns its size in bytes. Requires network access on first run unless
+ * postject is already in the npx cache.
+ */
+export const assembleSea = async (options) => {
+    const { appRoot, jsbundlePath, outFile } = options;
+    const workDir = options.workDir ?? dirname(jsbundlePath);
+    mkdirSync(workDir, { recursive: true });
+    mkdirSync(dirname(outFile), { recursive: true });
+    console.warn("[react-native-gtkx] bundling for a single executable…");
+    const bundlePath = join(workDir, "sea-bundle.cjs");
+    const nativeAddon = await bundleMetroSea({
+        appRoot,
+        jsbundlePath,
+        outFile: bundlePath,
+    });
+    console.warn(`[react-native-gtkx]   native addon: ${nativeAddon.path}`);
+    const configPath = join(workDir, "sea-config.json");
+    writeFileSync(configPath, `${JSON.stringify({
+        main: bundlePath,
+        output: join(workDir, "sea-prep.blob"),
+        disableExperimentalSEAWarning: true,
+        assets: { [nativeAddon.key]: nativeAddon.path },
+    }, null, 2)}\n`);
+    console.warn("[react-native-gtkx] generating the SEA blob…");
+    run(process.execPath, ["--experimental-sea-config", configPath]);
+    console.warn("[react-native-gtkx] copying the node binary…");
+    copyFileSync(process.execPath, outFile);
+    if (process.platform === "darwin") {
+        // The copy inherits a signature that no longer matches once the blob
+        // is injected; macOS refuses to exec it until the signature is gone.
+        run("codesign", ["--remove-signature", outFile]);
+    }
+    stripSymbols(outFile);
+    console.warn("[react-native-gtkx] injecting the SEA blob…");
+    run("npx", [
+        "--yes",
+        "--ignore-scripts",
+        POSTJECT,
+        outFile,
+        "NODE_SEA_BLOB",
+        join(workDir, "sea-prep.blob"),
+        "--sentinel-fuse",
+        SENTINEL_FUSE,
+    ]);
+    chmodSync(outFile, 0o755);
+    return statSync(outFile).size;
+};
+//# sourceMappingURL=assemble.js.map

package/dist/sea/assemble.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assemble.js","sourceRoot":"","sources":["../../src/sea/assemble.ts"],"names":[],"mappings":"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","sourcesContent":["// Turns a Metro-built app into ONE executable file: bundle everything into\n// a CJS entry (./bundle.ts), generate a SEA blob from it, then inject that\n// blob into a copy of the `node` binary. This is the whole of what \"SEA\"\n// means — Node's Single Executable Application format is literally a copy\n// of the node binary with a V8 code-cache blob appended, which is why the\n// result necessarily carries Node's own weight (~117 MB on linux-arm64,\n// against <7 MB for the app code and its native addon).\n//\n// Follows gtkx's own tutorial (gtkx-org/gtkx examples/tutorial/scripts/\n// build-sea.sh) for these mechanics; ./bundle.ts's header documents where\n// the bundling half deliberately diverges.\n//\n// Kept out of ../runner/index.ts and reached through a dynamic import so\n// the bundler is only loaded when a SEA is actually asked for; the\n// ordinary `build-linux` path never touches it.\nimport { spawnSync } from \"node:child_process\"\nimport {\n  chmodSync,\n  copyFileSync,\n  mkdirSync,\n  statSync,\n  writeFileSync,\n} from \"node:fs\"\nimport { dirname, join } from \"node:path\"\nimport { bundleMetroSea } from \"./bundle.js\"\n\n/** The fuse postject looks for inside the node binary to place the blob. */\nconst SENTINEL_FUSE = \"NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2\"\n\n/** Pinned: postject has no stable release, and the SEA docs name this one. */\nconst POSTJECT = \"postject@1.0.0-alpha.6\"\n\nexport type AssembleSeaOptions = {\n  /** The app root — where gtkx.config.ts and package.json live. */\n  appRoot: string\n  /** The release jsbundle `build-linux` just wrote. */\n  jsbundlePath: string\n  /** Where the finished executable is written. */\n  outFile: string\n  /** Scratch directory for the intermediate CJS bundle, the SEA config and\n   * the prep blob (default: alongside the jsbundle). */\n  workDir?: string\n}\n\nconst run = (command: string, args: string[]): void => {\n  const result = spawnSync(command, args, { stdio: \"inherit\" })\n  if (result.error) {\n    throw result.error\n  }\n  if (result.status !== 0) {\n    throw new Error(`${command} ${args.join(\" \")} exited with ${result.status}`)\n  }\n}\n\n/**\n * Drops the debug symbols from the copied Node binary. Worth a step of its\n * own because the saving is not marginal: the `node` binary distributed by\n * NodeSource for Ubuntu ships `with debug_info, not stripped` — measured at\n * 117 MB, and 98 MB after `strip --strip-all`. Nothing in a SEA needs those\n * symbols; the only cost is that a crash inside Node's own C++ produces an\n * unsymbolicated backtrace.\n *\n * Runs BEFORE postject, never after: `--strip-all` removes non-allocated\n * sections, which is exactly what the injected NODE_SEA_BLOB is.\n *\n * Best-effort — a build machine without binutils still produces a working\n * (larger) executable rather than failing, so this cannot become a new\n * install requirement for a build that worked yesterday.\n */\nconst stripSymbols = (file: string): void => {\n  const before = statSync(file).size\n  const result = spawnSync(\"strip\", [\"--strip-all\", file], {\n    stdio: [\"ignore\", \"ignore\", \"pipe\"],\n  })\n  if (result.error || result.status !== 0) {\n    console.warn(\n      \"[react-native-gtkx] skipped stripping symbols (no usable `strip`) — \" +\n        \"the executable will be tens of MB larger than it needs to be\",\n    )\n    return\n  }\n  const saved = (before - statSync(file).size) / 1024 / 1024\n  console.warn(\n    `[react-native-gtkx] stripped debug symbols (-${saved.toFixed(0)} MB)`,\n  )\n}\n\n/**\n * Produces the middle artifact: one self-contained CJS file with the app,\n * its whole node_modules closure and the native addon inlined, run by a\n * system `node`. Everything the SEA is except the embedded Node runtime —\n * so ~120 MB smaller, at the cost of a `nodejs` dependency to declare.\n * Returns its size in bytes.\n */\nexport const bundleStandalone = async (options: {\n  appRoot: string\n  jsbundlePath: string\n  outFile: string\n}): Promise<number> => {\n  const { appRoot, jsbundlePath, outFile } = options\n  mkdirSync(dirname(outFile), { recursive: true })\n  console.warn(\"[react-native-gtkx] bundling a standalone script…\")\n  await bundleMetroSea({\n    appRoot,\n    jsbundlePath,\n    outFile,\n    nativeAddonSource: \"inline\",\n  })\n  return statSync(outFile).size\n}\n\n/**\n * Produces a single executable at {@link AssembleSeaOptions.outFile} and\n * returns its size in bytes. Requires network access on first run unless\n * postject is already in the npx cache.\n */\nexport const assembleSea = async (\n  options: AssembleSeaOptions,\n): Promise<number> => {\n  const { appRoot, jsbundlePath, outFile } = options\n  const workDir = options.workDir ?? dirname(jsbundlePath)\n  mkdirSync(workDir, { recursive: true })\n  mkdirSync(dirname(outFile), { recursive: true })\n\n  console.warn(\"[react-native-gtkx] bundling for a single executable…\")\n  const bundlePath = join(workDir, \"sea-bundle.cjs\")\n  const nativeAddon = await bundleMetroSea({\n    appRoot,\n    jsbundlePath,\n    outFile: bundlePath,\n  })\n  console.warn(`[react-native-gtkx]   native addon: ${nativeAddon.path}`)\n\n  const configPath = join(workDir, \"sea-config.json\")\n  writeFileSync(\n    configPath,\n    `${JSON.stringify(\n      {\n        main: bundlePath,\n        output: join(workDir, \"sea-prep.blob\"),\n        disableExperimentalSEAWarning: true,\n        assets: { [nativeAddon.key]: nativeAddon.path },\n      },\n      null,\n      2,\n    )}\\n`,\n  )\n\n  console.warn(\"[react-native-gtkx] generating the SEA blob…\")\n  run(process.execPath, [\"--experimental-sea-config\", configPath])\n\n  console.warn(\"[react-native-gtkx] copying the node binary…\")\n  copyFileSync(process.execPath, outFile)\n  if (process.platform === \"darwin\") {\n    // The copy inherits a signature that no longer matches once the blob\n    // is injected; macOS refuses to exec it until the signature is gone.\n    run(\"codesign\", [\"--remove-signature\", outFile])\n  }\n  stripSymbols(outFile)\n\n  console.warn(\"[react-native-gtkx] injecting the SEA blob…\")\n  run(\"npx\", [\n    \"--yes\",\n    \"--ignore-scripts\",\n    POSTJECT,\n    outFile,\n    \"NODE_SEA_BLOB\",\n    join(workDir, \"sea-prep.blob\"),\n    \"--sentinel-fuse\",\n    SENTINEL_FUSE,\n  ])\n\n  chmodSync(outFile, 0o755)\n  return statSync(outFile).size\n}\n"]}

package/dist/sea/bundle.d.ts

@@ -0,0 +1,61 @@
+import { type NativeAddonSource } from "./native-shim.js";
+export type MetroSeaBundleOptions = {
+    /** The app root — where gtkx.config.ts lives and package.json resolves
+     * HOST_MODULE_EXTERNALS' bare specifiers (react, @gtkx/*, ...) from. */
+    appRoot: string;
+    /** Path to the release jsbundle produced by `build-linux`. */
+    jsbundlePath: string;
+    /** Where to write the bundled CJS entry (e.g. dist/bundle.cjs). */
+    outFile: string;
+    /** Where the native addon's bytes come from at runtime — "sea-asset"
+     * for a real single executable, "inline" for a self-contained .cjs run
+     * by a system Node (default: "sea-asset"). */
+    nativeAddonSource?: NativeAddonSource;
+};
+export type NativeAddonAsset = {
+    /** Absolute path to the platform's @gtkx/native-<platform>-<libc>.node
+     * that npm installed for this machine. */
+    path: string;
+    /** The SEA asset key it must be embedded under. */
+    key: string;
+};
+/**
+ * Locates the ONE native addon file npm installed for this machine.
+ * @gtkx/native picks exactly one optionalDependency per platform/libc at
+ * install time (see @gtkx/native/index.js's NAPI-RS-generated loader) —
+ * failing loudly on anything other than exactly one match matters here:
+ * silently picking the wrong one would embed an addon for the wrong
+ * architecture with no error until the app actually launches.
+ */
+export declare const resolveNativeAddon: (appRoot: string) => NativeAddonAsset;
+/**
+ * Builds the synthetic SEA entry source: every HOST_MODULE_EXTERNALS name
+ * loaded through a dynamic `import()` (mirroring runner/host.ts's own
+ * `load()`, which does the same against a real node_modules at runtime),
+ * assembled into globalThis.__hostModules, then the jsbundle text executed
+ * the same way host.ts does.
+ *
+ * Dynamic import, not static, throughout: a Node SEA's main script is
+ * CommonJS only — confirmed empirically, Node 24 executes the embedded
+ * main as CJS regardless of a "type": "module" field in sea-config.json
+ * or an .mjs extension — and top-level await is a hard error under a "cjs"
+ * output format REGARDLESS of whether the module is reached via a static
+ * or dynamic import (the restriction is format-wide, not per-module —
+ * verified: switching yoga-layout's static import to a dynamic one alone
+ * did not clear the error). yoga-layout's own entry point has exactly this
+ * top-level await (it loads its WASM binary asynchronously — see
+ * node_modules/yoga-layout/dist/src/index.js: `const Yoga =
+ * wrapAssembly(await loadYoga())` at module scope). The actual fix: import
+ * "yoga-layout/load" instead, which exports the same `await`, just inside
+ * an async FUNCTION (`export async function loadYoga()`), not at the
+ * file's top level — bundleable, and awaited here like everything else.
+ */
+export declare const buildEntrySource: (jsbundlePath: string) => string;
+/**
+ * Produces `outFile`, a single CJS file with the jsbundle, its
+ * HOST_MODULE_EXTERNALS and gtkx.config.ts's resolved values all inlined,
+ * and the native addon import redirected to the SEA-asset extraction
+ * shim. Returns the native addon that must be embedded as a SEA asset
+ * under {@link NativeAddonAsset.key} for the result to run.
+ */
+export declare const bundleMetroSea: (options: MetroSeaBundleOptions) => Promise<NativeAddonAsset>;

package/dist/sea/bundle.js

@@ -0,0 +1,202 @@
+// Bundles a Metro-built react-native-gtkx app (main.jsbundle) into a
+// single CJS file suitable for Node's --experimental-sea-config, undoing
+// exactly the externalization HOST_MODULE_EXTERNALS performs at Metro
+// build time.
+//
+// Design, and where this follows/diverges from gtkx's own tutorial
+// (gtkx-org/gtkx examples/tutorial/scripts/bundle.ts and
+// bundle-postject.ts — read before any of this was written):
+//
+// - Bundling mechanics (bundle → single minified CJS file) and the
+//   SEA/postject pipeline itself (./assemble.ts) follow the tutorial
+//   closely. The bundler is rolldown rather than the tutorial's esbuild —
+//   NOT a preference: rolldown is vite's own engine (vite 8 depends on it
+//   outright, esbuild is only an optional peer there), and vite is a hard
+//   dependency of @gtkx/cli, which is a hard dependency of this package.
+//   So rolldown is already installed for every consumer, and esbuild would
+//   have been the one genuinely new bundler in the tree.
+// - Native addon: the tutorial's shim assumes the addon file sits BESIDE
+//   the built executable (require resolved from
+//   dirname(process.execPath)). That is two files, not one — the actual
+//   central design decision this epic exists to make — so this diverges:
+//   the addon is embedded IN the artifact (as a SEA asset, or as a base64
+//   literal for the --standalone .cjs) and extracted to a per-user cache
+//   directory on first run. See ./native-shim.ts's header for the full
+//   reasoning.
+// - Metro's externals: the tutorial has no equivalent problem, its source
+//   is already a single vite/rollup bundle. Metro deliberately
+//   externalizes @gtkx/*, react and yoga-layout (../metro/index.ts,
+//   HOST_MODULE_EXTERNALS) so main.jsbundle expects
+//   globalThis.__hostModules/__hostRequire to exist before it runs (see
+//   ../runner/host.ts). This module is a third host implementation
+//   (host.ts and host-dev.ts are the other two — see host-dev.ts's header
+//   for why they don't share code) that builds those globals from real,
+//   STATICALLY imported modules — every name in HOST_MODULE_EXTERNALS
+//   becomes a literal `import * as` statement in the generated entry — so
+//   the bundler can inline them instead of the app needing a runtime
+//   node_modules to dynamically load them from. gtkx.config.ts is also
+//   resolved once here, at bundle time (see ./gtkx-config-module.ts).
+//
+// Not attempted here: the vite path. Investigated, not a drop-in of this
+// same technique — see docs/getting-started.md's "Shipping an app"
+// section for the concrete blocker found empirically while building this:
+// the vite bundle loads the native addon through a DYNAMICALLY obtained
+// require (`createRequire(import.meta.url)("./gtkx.node")`), which a
+// bundler does not intercept the way it intercepts a static import
+// (verified: the resolve hook never fires for it), and which is unlikely
+// to resolve at all once running from inside a real SEA blob, where
+// import.meta.url no longer points at a file with real siblings on disk.
+import { mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { rolldown } from "rolldown";
+import { HOST_MODULE_EXTERNALS } from "../metro/index.js";
+import { buildGtkxConfigModule, virtualConfigModulePlugin, } from "./gtkx-config-module.js";
+import { NATIVE_ASSET_KEY, nativeAddonShimPlugin, } from "./native-shim.js";
+import { reactAnchorPlugin } from "./react-anchor-plugin.js";
+/**
+ * Locates the ONE native addon file npm installed for this machine.
+ * @gtkx/native picks exactly one optionalDependency per platform/libc at
+ * install time (see @gtkx/native/index.js's NAPI-RS-generated loader) —
+ * failing loudly on anything other than exactly one match matters here:
+ * silently picking the wrong one would embed an addon for the wrong
+ * architecture with no error until the app actually launches.
+ */
+export const resolveNativeAddon = (appRoot) => {
+    const appRequire = createRequire(join(appRoot, "package.json"));
+    const nativePackageJson = appRequire.resolve("@gtkx/native/package.json");
+    // .../node_modules/@gtkx/native/package.json -> .../node_modules/@gtkx
+    const scopeDir = dirname(dirname(nativePackageJson));
+    const candidates = readdirSync(scopeDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && entry.name.startsWith("native-"))
+        .flatMap((entry) => {
+        const dir = join(scopeDir, entry.name);
+        return readdirSync(dir)
+            .filter((file) => file.endsWith(".node"))
+            .map((file) => join(dir, file));
+    });
+    const [first, ...rest] = candidates;
+    if (!first || rest.length > 0) {
+        throw new Error(`expected exactly one @gtkx/native-*/*.node under ${scopeDir}, found ` +
+            `${candidates.length} (${candidates.join(", ") || "none"}) — ` +
+            "reinstall targeting a single platform.");
+    }
+    return { path: first, key: NATIVE_ASSET_KEY };
+};
+/**
+ * Builds the synthetic SEA entry source: every HOST_MODULE_EXTERNALS name
+ * loaded through a dynamic `import()` (mirroring runner/host.ts's own
+ * `load()`, which does the same against a real node_modules at runtime),
+ * assembled into globalThis.__hostModules, then the jsbundle text executed
+ * the same way host.ts does.
+ *
+ * Dynamic import, not static, throughout: a Node SEA's main script is
+ * CommonJS only — confirmed empirically, Node 24 executes the embedded
+ * main as CJS regardless of a "type": "module" field in sea-config.json
+ * or an .mjs extension — and top-level await is a hard error under a "cjs"
+ * output format REGARDLESS of whether the module is reached via a static
+ * or dynamic import (the restriction is format-wide, not per-module —
+ * verified: switching yoga-layout's static import to a dynamic one alone
+ * did not clear the error). yoga-layout's own entry point has exactly this
+ * top-level await (it loads its WASM binary asynchronously — see
+ * node_modules/yoga-layout/dist/src/index.js: `const Yoga =
+ * wrapAssembly(await loadYoga())` at module scope). The actual fix: import
+ * "yoga-layout/load" instead, which exports the same `await`, just inside
+ * an async FUNCTION (`export async function loadYoga()`), not at the
+ * file's top level — bundleable, and awaited here like everything else.
+ */
+export const buildEntrySource = (jsbundlePath) => {
+    const jsbundleSource = readFileSync(jsbundlePath, "utf8");
+    const loadLines = HOST_MODULE_EXTERNALS.map((name) => {
+        if (name === "yoga-layout") {
+            return [
+                `  {`,
+                `    const { loadYoga, ...rest } = await import("yoga-layout/load");`,
+                `    hostModules["yoga-layout"] = __interopHostModule({ ...rest, default: await loadYoga() });`,
+                `  }`,
+            ].join("\n");
+        }
+        return `  hostModules[${JSON.stringify(name)}] = __interopHostModule(await import(${JSON.stringify(name)}));`;
+    });
+    return [
+        `async function __gtkxSeaMain() {`,
+        // Mirrors runner/host.ts's `load()` interop: import() handles both ESM
+        // and CJS, merge a `default` for Babel's default-import interop when
+        // the module has none of its own.
+        `  const __interopHostModule = (ns) => {`,
+        `    const merged = Object.assign({ __esModule: true }, ns);`,
+        `    if (!("default" in ns)) merged.default = ns;`,
+        `    return merged;`,
+        `  };`,
+        `  const hostModules = {};`,
+        ...loadLines,
+        `  globalThis.__hostModules = hostModules;`,
+        // Node builtin proxies resolve lazily through the host's own require —
+        // real here, no createRequire indirection needed (see host.ts for why
+        // it needs one: this file's import.meta.url is never used for
+        // anything relative, only require() of bare/builtin specifiers).
+        `  globalThis.__hostRequire = require;`,
+        `  require("node:vm").runInThisContext(${JSON.stringify(jsbundleSource)}, { filename: ${JSON.stringify(jsbundlePath)} });`,
+        `}`,
+        `__gtkxSeaMain().catch((error) => { console.error(error); process.exitCode = 1; });`,
+    ].join("\n");
+};
+/**
+ * Produces `outFile`, a single CJS file with the jsbundle, its
+ * HOST_MODULE_EXTERNALS and gtkx.config.ts's resolved values all inlined,
+ * and the native addon import redirected to the SEA-asset extraction
+ * shim. Returns the native addon that must be embedded as a SEA asset
+ * under {@link NativeAddonAsset.key} for the result to run.
+ */
+export const bundleMetroSea = async (options) => {
+    const { appRoot, jsbundlePath, outFile } = options;
+    const nativeAddonSource = options.nativeAddonSource ?? "sea-asset";
+    const configModuleSource = await buildGtkxConfigModule(appRoot);
+    const nativeAddon = resolveNativeAddon(appRoot);
+    const entrySource = buildEntrySource(jsbundlePath);
+    mkdirSync(dirname(outFile), { recursive: true });
+    // The entry is given a path inside appRoot that does not exist on disk,
+    // rather than a `\0`-prefixed virtual id: every bare specifier it
+    // imports (react, @gtkx/*, yoga-layout) must resolve from the app's own
+    // node_modules, and a real directory is what makes that happen.
+    const entryId = join(appRoot, "__gtkx-sea-entry.js");
+    const bundle = await rolldown({
+        input: entryId,
+        cwd: appRoot,
+        platform: "node",
+        plugins: [
+            {
+                name: "gtkx-sea-entry",
+                resolveId: (source) => (source === entryId ? entryId : null),
+                load: (id) => (id === entryId ? entrySource : null),
+            },
+            reactAnchorPlugin(appRoot),
+            nativeAddonShimPlugin({
+                specifier: "@gtkx/native",
+                appRoot,
+                source: nativeAddonSource,
+                assetKey: nativeAddon.key,
+                addonBytes: nativeAddonSource === "inline"
+                    ? readFileSync(nativeAddon.path)
+                    : undefined,
+            }),
+            virtualConfigModulePlugin(configModuleSource, appRoot),
+        ],
+    });
+    try {
+        await bundle.write({
+            file: outFile,
+            format: "cjs",
+            minify: true,
+            // Every HOST_MODULE_EXTERNALS name is reached through a dynamic
+            // import; without this each one becomes its own chunk and the
+            // "single file" the whole build exists to produce is a directory.
+            codeSplitting: false,
+        });
+    }
+    finally {
+        await bundle.close();
+    }
+    return nativeAddon;
+};
+//# sourceMappingURL=bundle.js.map

package/dist/sea/bundle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.js","sourceRoot":"","sources":["../../src/sea/bundle.ts"],"names":[],"mappings":"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","sourcesContent":["// Bundles a Metro-built react-native-gtkx app (main.jsbundle) into a\n// single CJS file suitable for Node's --experimental-sea-config, undoing\n// exactly the externalization HOST_MODULE_EXTERNALS performs at Metro\n// build time.\n//\n// Design, and where this follows/diverges from gtkx's own tutorial\n// (gtkx-org/gtkx examples/tutorial/scripts/bundle.ts and\n// bundle-postject.ts — read before any of this was written):\n//\n// - Bundling mechanics (bundle → single minified CJS file) and the\n//   SEA/postject pipeline itself (./assemble.ts) follow the tutorial\n//   closely. The bundler is rolldown rather than the tutorial's esbuild —\n//   NOT a preference: rolldown is vite's own engine (vite 8 depends on it\n//   outright, esbuild is only an optional peer there), and vite is a hard\n//   dependency of @gtkx/cli, which is a hard dependency of this package.\n//   So rolldown is already installed for every consumer, and esbuild would\n//   have been the one genuinely new bundler in the tree.\n// - Native addon: the tutorial's shim assumes the addon file sits BESIDE\n//   the built executable (require resolved from\n//   dirname(process.execPath)). That is two files, not one — the actual\n//   central design decision this epic exists to make — so this diverges:\n//   the addon is embedded IN the artifact (as a SEA asset, or as a base64\n//   literal for the --standalone .cjs) and extracted to a per-user cache\n//   directory on first run. See ./native-shim.ts's header for the full\n//   reasoning.\n// - Metro's externals: the tutorial has no equivalent problem, its source\n//   is already a single vite/rollup bundle. Metro deliberately\n//   externalizes @gtkx/*, react and yoga-layout (../metro/index.ts,\n//   HOST_MODULE_EXTERNALS) so main.jsbundle expects\n//   globalThis.__hostModules/__hostRequire to exist before it runs (see\n//   ../runner/host.ts). This module is a third host implementation\n//   (host.ts and host-dev.ts are the other two — see host-dev.ts's header\n//   for why they don't share code) that builds those globals from real,\n//   STATICALLY imported modules — every name in HOST_MODULE_EXTERNALS\n//   becomes a literal `import * as` statement in the generated entry — so\n//   the bundler can inline them instead of the app needing a runtime\n//   node_modules to dynamically load them from. gtkx.config.ts is also\n//   resolved once here, at bundle time (see ./gtkx-config-module.ts).\n//\n// Not attempted here: the vite path. Investigated, not a drop-in of this\n// same technique — see docs/getting-started.md's \"Shipping an app\"\n// section for the concrete blocker found empirically while building this:\n// the vite bundle loads the native addon through a DYNAMICALLY obtained\n// require (`createRequire(import.meta.url)(\"./gtkx.node\")`), which a\n// bundler does not intercept the way it intercepts a static import\n// (verified: the resolve hook never fires for it), and which is unlikely\n// to resolve at all once running from inside a real SEA blob, where\n// import.meta.url no longer points at a file with real siblings on disk.\nimport { mkdirSync, readdirSync, readFileSync } from \"node:fs\"\nimport { createRequire } from \"node:module\"\nimport { dirname, join } from \"node:path\"\nimport { rolldown } from \"rolldown\"\nimport { HOST_MODULE_EXTERNALS } from \"../metro/index.js\"\nimport {\n  buildGtkxConfigModule,\n  virtualConfigModulePlugin,\n} from \"./gtkx-config-module.js\"\nimport {\n  NATIVE_ASSET_KEY,\n  nativeAddonShimPlugin,\n  type NativeAddonSource,\n} from \"./native-shim.js\"\nimport { reactAnchorPlugin } from \"./react-anchor-plugin.js\"\n\nexport type MetroSeaBundleOptions = {\n  /** The app root — where gtkx.config.ts lives and package.json resolves\n   * HOST_MODULE_EXTERNALS' bare specifiers (react, @gtkx/*, ...) from. */\n  appRoot: string\n  /** Path to the release jsbundle produced by `build-linux`. */\n  jsbundlePath: string\n  /** Where to write the bundled CJS entry (e.g. dist/bundle.cjs). */\n  outFile: string\n  /** Where the native addon's bytes come from at runtime — \"sea-asset\"\n   * for a real single executable, \"inline\" for a self-contained .cjs run\n   * by a system Node (default: \"sea-asset\"). */\n  nativeAddonSource?: NativeAddonSource\n}\n\nexport type NativeAddonAsset = {\n  /** Absolute path to the platform's @gtkx/native-<platform>-<libc>.node\n   * that npm installed for this machine. */\n  path: string\n  /** The SEA asset key it must be embedded under. */\n  key: string\n}\n\n/**\n * Locates the ONE native addon file npm installed for this machine.\n * @gtkx/native picks exactly one optionalDependency per platform/libc at\n * install time (see @gtkx/native/index.js's NAPI-RS-generated loader) —\n * failing loudly on anything other than exactly one match matters here:\n * silently picking the wrong one would embed an addon for the wrong\n * architecture with no error until the app actually launches.\n */\nexport const resolveNativeAddon = (appRoot: string): NativeAddonAsset => {\n  const appRequire = createRequire(join(appRoot, \"package.json\"))\n  const nativePackageJson = appRequire.resolve(\"@gtkx/native/package.json\")\n  // .../node_modules/@gtkx/native/package.json -> .../node_modules/@gtkx\n  const scopeDir = dirname(dirname(nativePackageJson))\n  const candidates = readdirSync(scopeDir, { withFileTypes: true })\n    .filter((entry) => entry.isDirectory() && entry.name.startsWith(\"native-\"))\n    .flatMap((entry) => {\n      const dir = join(scopeDir, entry.name)\n      return readdirSync(dir)\n        .filter((file) => file.endsWith(\".node\"))\n        .map((file) => join(dir, file))\n    })\n  const [first, ...rest] = candidates\n  if (!first || rest.length > 0) {\n    throw new Error(\n      `expected exactly one @gtkx/native-*/*.node under ${scopeDir}, found ` +\n        `${candidates.length} (${candidates.join(\", \") || \"none\"}) — ` +\n        \"reinstall targeting a single platform.\",\n    )\n  }\n  return { path: first, key: NATIVE_ASSET_KEY }\n}\n\n/**\n * Builds the synthetic SEA entry source: every HOST_MODULE_EXTERNALS name\n * loaded through a dynamic `import()` (mirroring runner/host.ts's own\n * `load()`, which does the same against a real node_modules at runtime),\n * assembled into globalThis.__hostModules, then the jsbundle text executed\n * the same way host.ts does.\n *\n * Dynamic import, not static, throughout: a Node SEA's main script is\n * CommonJS only — confirmed empirically, Node 24 executes the embedded\n * main as CJS regardless of a \"type\": \"module\" field in sea-config.json\n * or an .mjs extension — and top-level await is a hard error under a \"cjs\"\n * output format REGARDLESS of whether the module is reached via a static\n * or dynamic import (the restriction is format-wide, not per-module —\n * verified: switching yoga-layout's static import to a dynamic one alone\n * did not clear the error). yoga-layout's own entry point has exactly this\n * top-level await (it loads its WASM binary asynchronously — see\n * node_modules/yoga-layout/dist/src/index.js: `const Yoga =\n * wrapAssembly(await loadYoga())` at module scope). The actual fix: import\n * \"yoga-layout/load\" instead, which exports the same `await`, just inside\n * an async FUNCTION (`export async function loadYoga()`), not at the\n * file's top level — bundleable, and awaited here like everything else.\n */\nexport const buildEntrySource = (jsbundlePath: string): string => {\n  const jsbundleSource = readFileSync(jsbundlePath, \"utf8\")\n  const loadLines = HOST_MODULE_EXTERNALS.map((name) => {\n    if (name === \"yoga-layout\") {\n      return [\n        `  {`,\n        `    const { loadYoga, ...rest } = await import(\"yoga-layout/load\");`,\n        `    hostModules[\"yoga-layout\"] = __interopHostModule({ ...rest, default: await loadYoga() });`,\n        `  }`,\n      ].join(\"\\n\")\n    }\n    return `  hostModules[${JSON.stringify(name)}] = __interopHostModule(await import(${JSON.stringify(name)}));`\n  })\n  return [\n    `async function __gtkxSeaMain() {`,\n    // Mirrors runner/host.ts's `load()` interop: import() handles both ESM\n    // and CJS, merge a `default` for Babel's default-import interop when\n    // the module has none of its own.\n    `  const __interopHostModule = (ns) => {`,\n    `    const merged = Object.assign({ __esModule: true }, ns);`,\n    `    if (!(\"default\" in ns)) merged.default = ns;`,\n    `    return merged;`,\n    `  };`,\n    `  const hostModules = {};`,\n    ...loadLines,\n    `  globalThis.__hostModules = hostModules;`,\n    // Node builtin proxies resolve lazily through the host's own require —\n    // real here, no createRequire indirection needed (see host.ts for why\n    // it needs one: this file's import.meta.url is never used for\n    // anything relative, only require() of bare/builtin specifiers).\n    `  globalThis.__hostRequire = require;`,\n    `  require(\"node:vm\").runInThisContext(${JSON.stringify(jsbundleSource)}, { filename: ${JSON.stringify(jsbundlePath)} });`,\n    `}`,\n    `__gtkxSeaMain().catch((error) => { console.error(error); process.exitCode = 1; });`,\n  ].join(\"\\n\")\n}\n\n/**\n * Produces `outFile`, a single CJS file with the jsbundle, its\n * HOST_MODULE_EXTERNALS and gtkx.config.ts's resolved values all inlined,\n * and the native addon import redirected to the SEA-asset extraction\n * shim. Returns the native addon that must be embedded as a SEA asset\n * under {@link NativeAddonAsset.key} for the result to run.\n */\nexport const bundleMetroSea = async (\n  options: MetroSeaBundleOptions,\n): Promise<NativeAddonAsset> => {\n  const { appRoot, jsbundlePath, outFile } = options\n  const nativeAddonSource = options.nativeAddonSource ?? \"sea-asset\"\n  const configModuleSource = await buildGtkxConfigModule(appRoot)\n  const nativeAddon = resolveNativeAddon(appRoot)\n  const entrySource = buildEntrySource(jsbundlePath)\n\n  mkdirSync(dirname(outFile), { recursive: true })\n\n  // The entry is given a path inside appRoot that does not exist on disk,\n  // rather than a `\\0`-prefixed virtual id: every bare specifier it\n  // imports (react, @gtkx/*, yoga-layout) must resolve from the app's own\n  // node_modules, and a real directory is what makes that happen.\n  const entryId = join(appRoot, \"__gtkx-sea-entry.js\")\n\n  const bundle = await rolldown({\n    input: entryId,\n    cwd: appRoot,\n    platform: \"node\",\n    plugins: [\n      {\n        name: \"gtkx-sea-entry\",\n        resolveId: (source) => (source === entryId ? entryId : null),\n        load: (id) => (id === entryId ? entrySource : null),\n      },\n      reactAnchorPlugin(appRoot),\n      nativeAddonShimPlugin({\n        specifier: \"@gtkx/native\",\n        appRoot,\n        source: nativeAddonSource,\n        assetKey: nativeAddon.key,\n        addonBytes:\n          nativeAddonSource === \"inline\"\n            ? readFileSync(nativeAddon.path)\n            : undefined,\n      }),\n      virtualConfigModulePlugin(configModuleSource, appRoot),\n    ],\n  })\n  try {\n    await bundle.write({\n      file: outFile,\n      format: \"cjs\",\n      minify: true,\n      // Every HOST_MODULE_EXTERNALS name is reached through a dynamic\n      // import; without this each one becomes its own chunk and the\n      // \"single file\" the whole build exists to produce is a directory.\n      codeSplitting: false,\n    })\n  } finally {\n    await bundle.close()\n  }\n\n  return nativeAddon\n}\n"]}

package/dist/sea/gtkx-config-module.d.ts

@@ -0,0 +1,18 @@
+import type { Plugin } from "rolldown";
+export declare const CONFIG_REQUIRED: string;
+/**
+ * Loads and validates the app's gtkx.config.ts, returning the source of a
+ * virtual:gtkx-config module with the resolved values baked in as literals.
+ */
+export declare const buildGtkxConfigModule: (appRoot: string) => Promise<string>;
+/**
+ * Resolves the bare "virtual:gtkx-config" specifier @gtkx/react imports to
+ * the module source built by {@link buildGtkxConfigModule}, so the bundler
+ * can inline it like any other static import — no runtime loader hook
+ * needed.
+ *
+ * The module is given an id inside `appRoot` rather than a `\0`-prefixed
+ * virtual one because it re-exports "@gtkx/jsx/metadata": that bare
+ * specifier needs a real directory to resolve from.
+ */
+export declare const virtualConfigModulePlugin: (moduleSource: string, appRoot: string) => Plugin;

package/dist/sea/gtkx-config-module.js

@@ -0,0 +1,67 @@
+// @gtkx/react imports the bare specifier "virtual:gtkx-config" for JSX
+// metadata plus the app's applicationId/userEventSignals/lazy elements.
+// runner/host.ts resolves it at every process start through a loader hook
+// (registerHooks), reading gtkx.config.ts from the current working
+// directory. A SEA has no "app root" to read a config file from at
+// runtime — there is no cwd convention once the app is a single file
+// copied anywhere — so this bakes the same values in at BUILD time
+// instead, the same way the vite path already does (its CLI plugin serves
+// virtual:gtkx-config from the build-time config, never a runtime read).
+//
+// Deliberately duplicated validation logic rather than shared with
+// host.ts: see host-dev.ts's header comment for why the hosts in this
+// package are self-contained twins rather than sharing relative imports —
+// this is a third twin, for the same reason (host.ts must keep resolving
+// its config at runtime for ordinary `run-linux`/installed-app use; this
+// one resolves it once, at bundle time, for the SEA artifact only).
+import { join } from "node:path";
+import { createConfigLoader } from "@gtkx/config/internal";
+export const CONFIG_REQUIRED = "gtkx.config.ts with an applicationId is required in the app root " +
+    '(export default defineConfig({ applicationId: "...", libraries: [...] })).';
+/**
+ * Loads and validates the app's gtkx.config.ts, returning the source of a
+ * virtual:gtkx-config module with the resolved values baked in as literals.
+ */
+export const buildGtkxConfigModule = async (appRoot) => {
+    const loader = createConfigLoader();
+    const config = await loader.resolve(appRoot).catch((error) => {
+        throw new Error(`${CONFIG_REQUIRED}\n${String(error)}`);
+    });
+    if (!config.applicationId) {
+        throw new Error(CONFIG_REQUIRED);
+    }
+    // A behaviors module would have to be bundled and merged through
+    // @gtkx/react/config; the react-native surface owns element behaviors,
+    // so no app declares one — refuse rather than silently drop it (mirrors
+    // host.ts's runtime check).
+    if (config.elements !== null) {
+        throw new Error("gtkx.config.ts `elements.behaviors` is not supported on the linux " +
+            "platform — react-native-gtkx owns element behaviors.");
+    }
+    const lazyElements = Object.fromEntries(config.lazyElements.map((type) => [type, { lazy: true }]));
+    return [
+        `export * from "@gtkx/jsx/metadata";`,
+        `export const applicationId = ${JSON.stringify(config.applicationId)};`,
+        `export const userEventSignals = ${JSON.stringify(config.userEventSignals)};`,
+        `export const elements = ${JSON.stringify(lazyElements)};`,
+    ].join("\n");
+};
+/**
+ * Resolves the bare "virtual:gtkx-config" specifier @gtkx/react imports to
+ * the module source built by {@link buildGtkxConfigModule}, so the bundler
+ * can inline it like any other static import — no runtime loader hook
+ * needed.
+ *
+ * The module is given an id inside `appRoot` rather than a `\0`-prefixed
+ * virtual one because it re-exports "@gtkx/jsx/metadata": that bare
+ * specifier needs a real directory to resolve from.
+ */
+export const virtualConfigModulePlugin = (moduleSource, appRoot) => {
+    const configId = join(appRoot, "__gtkx-sea-config.js");
+    return {
+        name: "gtkx-virtual-config",
+        resolveId: (source) => (source === "virtual:gtkx-config" ? configId : null),
+        load: (id) => (id === configId ? moduleSource : null),
+    };
+};
+//# sourceMappingURL=gtkx-config-module.js.map

package/dist/sea/gtkx-config-module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gtkx-config-module.js","sourceRoot":"","sources":["../../src/sea/gtkx-config-module.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,wEAAwE;AACxE,0EAA0E;AAC1E,mEAAmE;AACnE,mEAAmE;AACnE,qEAAqE;AACrE,mEAAmE;AACnE,0EAA0E;AAC1E,yEAAyE;AACzE,EAAE;AACF,mEAAmE;AACnE,sEAAsE;AACtE,0EAA0E;AAC1E,yEAAyE;AACzE,yEAAyE;AACzE,oEAAoE;AACpE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAG1D,MAAM,CAAC,MAAM,eAAe,GAC1B,mEAAmE;IACnE,4EAA4E,CAAA;AAE9E;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,EACxC,OAAe,EACE,EAAE;IACnB,MAAM,MAAM,GAAG,kBAAkB,EAAE,CAAA;IACnC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QACpE,MAAM,IAAI,KAAK,CAAC,GAAG,eAAe,KAAK,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IACzD,CAAC,CAAC,CAAA;IACF,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,eAAe,CAAC,CAAA;IAClC,CAAC;IACD,iEAAiE;IACjE,uEAAuE;IACvE,wEAAwE;IACxE,4BAA4B;IAC5B,IAAI,MAAM,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,oEAAoE;YAClE,sDAAsD,CACzD,CAAA;IACH,CAAC;IACD,MAAM,YAAY,GAAG,MAAM,CAAC,WAAW,CACrC,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAC1D,CAAA;IACD,OAAO;QACL,qCAAqC;QACrC,gCAAgC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,aAAa,CAAC,GAAG;QACvE,mCAAmC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,gBAAgB,CAAC,GAAG;QAC7E,2BAA2B,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,GAAG;KAC3D,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACd,CAAC,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CACvC,YAAoB,EACpB,OAAe,EACP,EAAE;IACV,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,sBAAsB,CAAC,CAAA;IACtD,OAAO;QACL,IAAI,EAAE,qBAAqB;QAC3B,SAAS,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,KAAK,qBAAqB,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;QAC3E,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC;KACtD,CAAA;AACH,CAAC,CAAA","sourcesContent":["// @gtkx/react imports the bare specifier \"virtual:gtkx-config\" for JSX\n// metadata plus the app's applicationId/userEventSignals/lazy elements.\n// runner/host.ts resolves it at every process start through a loader hook\n// (registerHooks), reading gtkx.config.ts from the current working\n// directory. A SEA has no \"app root\" to read a config file from at\n// runtime — there is no cwd convention once the app is a single file\n// copied anywhere — so this bakes the same values in at BUILD time\n// instead, the same way the vite path already does (its CLI plugin serves\n// virtual:gtkx-config from the build-time config, never a runtime read).\n//\n// Deliberately duplicated validation logic rather than shared with\n// host.ts: see host-dev.ts's header comment for why the hosts in this\n// package are self-contained twins rather than sharing relative imports —\n// this is a third twin, for the same reason (host.ts must keep resolving\n// its config at runtime for ordinary `run-linux`/installed-app use; this\n// one resolves it once, at bundle time, for the SEA artifact only).\nimport { join } from \"node:path\"\nimport { createConfigLoader } from \"@gtkx/config/internal\"\nimport type { Plugin } from \"rolldown\"\n\nexport const CONFIG_REQUIRED =\n  \"gtkx.config.ts with an applicationId is required in the app root \" +\n  '(export default defineConfig({ applicationId: \"...\", libraries: [...] })).'\n\n/**\n * Loads and validates the app's gtkx.config.ts, returning the source of a\n * virtual:gtkx-config module with the resolved values baked in as literals.\n */\nexport const buildGtkxConfigModule = async (\n  appRoot: string,\n): Promise<string> => {\n  const loader = createConfigLoader()\n  const config = await loader.resolve(appRoot).catch((error: unknown) => {\n    throw new Error(`${CONFIG_REQUIRED}\\n${String(error)}`)\n  })\n  if (!config.applicationId) {\n    throw new Error(CONFIG_REQUIRED)\n  }\n  // A behaviors module would have to be bundled and merged through\n  // @gtkx/react/config; the react-native surface owns element behaviors,\n  // so no app declares one — refuse rather than silently drop it (mirrors\n  // host.ts's runtime check).\n  if (config.elements !== null) {\n    throw new Error(\n      \"gtkx.config.ts `elements.behaviors` is not supported on the linux \" +\n        \"platform — react-native-gtkx owns element behaviors.\",\n    )\n  }\n  const lazyElements = Object.fromEntries(\n    config.lazyElements.map((type) => [type, { lazy: true }]),\n  )\n  return [\n    `export * from \"@gtkx/jsx/metadata\";`,\n    `export const applicationId = ${JSON.stringify(config.applicationId)};`,\n    `export const userEventSignals = ${JSON.stringify(config.userEventSignals)};`,\n    `export const elements = ${JSON.stringify(lazyElements)};`,\n  ].join(\"\\n\")\n}\n\n/**\n * Resolves the bare \"virtual:gtkx-config\" specifier @gtkx/react imports to\n * the module source built by {@link buildGtkxConfigModule}, so the bundler\n * can inline it like any other static import — no runtime loader hook\n * needed.\n *\n * The module is given an id inside `appRoot` rather than a `\\0`-prefixed\n * virtual one because it re-exports \"@gtkx/jsx/metadata\": that bare\n * specifier needs a real directory to resolve from.\n */\nexport const virtualConfigModulePlugin = (\n  moduleSource: string,\n  appRoot: string,\n): Plugin => {\n  const configId = join(appRoot, \"__gtkx-sea-config.js\")\n  return {\n    name: \"gtkx-virtual-config\",\n    resolveId: (source) => (source === \"virtual:gtkx-config\" ? configId : null),\n    load: (id) => (id === configId ? moduleSource : null),\n  }\n}\n"]}

package/dist/sea/native-shim.d.ts

@@ -0,0 +1,40 @@
+import type { Plugin } from "rolldown";
+export declare const NATIVE_ASSET_KEY = "gtkx-native.node";
+/**
+ * Where the shim gets the addon's bytes from — the only difference between
+ * the two single-file artifacts:
+ *
+ * - `"sea-asset"`: from the SEA blob, via node:sea. Only works inside a
+ *   real single executable.
+ * - `"inline"`: from a base64 literal in the bundle itself, so the CJS
+ *   file is self-contained under a plain `node app.cjs` — the same
+ *   artifact minus the embedded Node runtime. Costs ~4/3 of the addon's
+ *   size in source text (the addon is ~1.6 MB) and is parsed once at
+ *   startup; the extraction and dlopen below are shared.
+ */
+export type NativeAddonSource = "sea-asset" | "inline";
+export type NativeAddonShimOptions = {
+    /** The bare specifier to replace, in practice "@gtkx/native". */
+    specifier: string;
+    /** The app root — the shim's id lives here, see above. */
+    appRoot: string;
+    /** Where the addon's bytes come from at runtime. */
+    source: NativeAddonSource;
+    /** SEA asset key; unused when `source` is "inline". */
+    assetKey?: string;
+    /** The addon's bytes; required when `source` is "inline". */
+    addonBytes?: Buffer;
+};
+/**
+ * Intercepts every import/require of `specifier` (an exact bare module
+ * specifier, e.g. "@gtkx/native") and replaces it with the extraction shim
+ * above. The real module never reaches the bundle graph — only its
+ * re-exported surface, loaded from the extracted file at runtime.
+ *
+ * The shim is given an id inside `appRoot` with a `.cjs` extension rather
+ * than a `\0`-prefixed virtual one: the shim IS CommonJS (it assigns
+ * `module.exports` so consumers' NAMED imports of the addon still resolve
+ * through the bundler's interop), and a real directory is what lets any
+ * specifier inside it resolve normally.
+ */
+export declare const nativeAddonShimPlugin: (options: NativeAddonShimOptions) => Plugin;