@gjsify/rolldown-plugin-gjsify 0.51.1 → 0.53.0

package/lib/shims/addon-resolve.js

@@ -0,0 +1,193 @@
+// Runtime resolver for a GJS bundle's Node-API addon, ADR 0084.
+//
+// The build enumerates every `.node` an addon package ships, keyed by
+// platform (`linux-x64`, `linux-x64-musl`, `darwin-arm64`, …), and bakes the
+// table into the bundle. At RUN time the bundle picks the entry for the host
+// it finds itself on and resolves the addon's package root through the same
+// `__gjsifyBundleUrl` banner + `createRequire` anchor the module-resolve shim
+// uses. The addon is never copied and never leaves its package, so a `.node`
+// that `dlopen`s a sibling `.so` or reads a data file beside itself keeps
+// working.
+//
+// Three correctness constraints shape the implementation:
+//
+//  1. *Location anchor.* The resolver anchors at the BUNDLE's URL, not its
+//     own. When a consumer bundles this shim it lives under
+//     `node_modules/@gjsify/rolldown-plugin-gjsify/...`, so the path rewriter
+//     would rewrite this file's own `import.meta.url` too. We therefore take
+//     no `import.meta.url` here and read the anchor from `globalThis.
+//     __gjsifyBundleUrl`, captured by a one-line banner at byte 0 of the
+//     bundle — the single point where `import.meta.url` is unambiguously the
+//     bundle's URL.
+//
+//  2. *exports-map safety.* `createRequire(...).resolve("<pkg>/<deep/path>")`
+//     is rejected by strict `"exports"` maps under Node's native
+//     `createRequire` (the `--app node` target), and `@gjsify/module` is
+//     exports-aware too. So we never resolve the deep path directly: we
+//     resolve the PACKAGE ROOT and join the subpath literally, which no
+//     `exports` map can block.
+//
+//  3. *libc is a variable, not a probe.* It is read from `process.env.LIBC`,
+//     never sniffed off the filesystem. On a musl host with an unset `LIBC`
+//     the lookup falls through to the libc-agnostic entry, which is what
+//     node-gyp-build's own untagged prebuilds assume; a package shipping a
+//     glibc-only and a musl prebuild under one tuple is served the glibc one,
+//     which `LIBC=musl` fixes. (The one `package.json` read in this file is on
+//     the `exports`-blocked root fallback, not on the libc decision.)
+//
+// The `addons/` layout the resolver names when the package is not installed is
+// the declared destination a packaging step would fill. `gjsify ship` does not
+// fill it yet — see ADR 0084 § Consequences for the measurement.
+//
+// @ts-ignore — `node:{module,url,path,fs}` are resolved by the consumer's
+// `gjsify build` run (aliased to `@gjsify/{module,url,path,fs}`), not by tsc here.
+import { createRequire } from 'node:module';
+// @ts-ignore — see above.
+import { fileURLToPath } from 'node:url';
+// @ts-ignore — see above.
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+// @ts-ignore — see above. Read on the `exports`-blocked fallback only; see
+// `declaresPackage`. The no-filesystem rule above is about libc, not this.
+import { readFileSync } from 'node:fs';
+import { hostAddonKeys, selectAddonTarget } from '../utils/addon-platform.js';
+/** The bundle's own URL (set by the byte-0 banner). Throws only if the banner didn't run. */
+function bundleAnchorUrl() {
+    const anchor = globalThis.__gjsifyBundleUrl;
+    if (!anchor) {
+        throw new Error('gjsify: __gjsifyBundleUrl is not set — the bundle-URL banner did not run. ' +
+            'The addon-resolve shim is only valid in single-file app builds (gjsify build --app gjs).');
+    }
+    return anchor;
+}
+/**
+ * Split a bundled-file spec into its package name and the path within the
+ * package. Handles scoped names:
+ *   "typedoc/dist/lib/app.js"   → { pkg: "typedoc",        subpath: "dist/lib/app.js" }
+ *   "@scope/name/sub/file.js"   → { pkg: "@scope/name",    subpath: "sub/file.js" }
+ *   "typedoc"                   → { pkg: "typedoc",        subpath: "" }
+ */
+function splitPackageSpec(spec) {
+    const parts = spec.split('/');
+    const segments = spec.startsWith('@') ? 2 : 1;
+    return {
+        pkg: parts.slice(0, segments).join('/'),
+        subpath: parts.slice(segments).join('/'),
+    };
+}
+/**
+ * Find the on-disk root directory of `pkg`, exports-map-agnostic.
+ *
+ * `package.json` is resolvable for nearly every package and points straight at
+ * the root. When a strict `exports` map blocks it, fall back to the package's
+ * main entry (always an export) and derive the root from the
+ * `node_modules/<pkg>` boundary in its path.
+ *
+ * A WORKSPACE-LINKED package resolves to its real path, which carries no
+ * `node_modules/<pkg>/` segment, and answering `dirname(main)` there named the
+ * directory the entry sits in — `packages/typedoc/dist` — so the subpath was
+ * joined onto `dist/` and the addon was reported missing at a path that never
+ * existed. The boundary is therefore only a shortcut; the fallback walks up to
+ * the nearest ancestor whose own `package.json` declares `pkg`, which is the
+ * root by definition. Returns null when `pkg` is not installed.
+ */
+function resolvePackageRoot(pkg) {
+    try {
+        const require = createRequire(bundleAnchorUrl());
+        return dirname(require.resolve(`${pkg}/package.json`));
+    }
+    catch {
+        /* strict `exports`: fall through to the entry point */
+    }
+    let main;
+    try {
+        main = createRequire(bundleAnchorUrl()).resolve(pkg);
+    }
+    catch {
+        return null;
+    }
+    const marker = `/node_modules/${pkg}/`;
+    const idx = main.lastIndexOf(marker);
+    if (idx >= 0)
+        return main.slice(0, idx + marker.length - 1);
+    for (let dir = dirname(main), i = 0; i < 64; i++) {
+        if (declaresPackage(dir, pkg))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/** Does the `package.json` in `dir` declare `name: pkg`? The root test, read not inferred. */
+function declaresPackage(dir, pkg) {
+    try {
+        const manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+        return manifest.name === pkg;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the addon's `.node` for the RUNNING host from the build-time table.
+ *
+ * `targets` maps platform keys (`linux-x64`, `linux-x64-musl`, …) to
+ * `<package>/<subpath>` specs. The host keys are tried most-specific first
+ * (exact, then libc-agnostic, then `*`). The package root is resolved at run
+ * time through the bundle-URL anchor, which is what makes the bundle relocatable
+ * (ADR 0084).
+ *
+ * Throws when no entry matches the running host, when the table is empty, and
+ * when the addon package is not installed next to the bundle. The last one is
+ * a LIMIT, not an oversight: identity-based resolution needs the package to be
+ * somewhere on disk, so a bundle shipped with no `node_modules` around it cannot
+ * load a third-party addon. It throws rather than returning
+ * `<bundle dir>/addons/…` because that directory is a declared layout nothing
+ * fills yet, and a path that cannot exist reaches `loadAddon` as a bare ENOENT
+ * that names neither the package nor the remedy. Both facts are in the message.
+ */
+export function __gjsifyAddonResolve(targets) {
+    const keys = hostAddonKeys(process.platform, process.arch, process.env.LIBC);
+    const spec = selectAddonTarget(targets, keys);
+    if (spec === null) {
+        const known = Object.keys(targets).join(', ') || '(empty)';
+        throw new Error(`gjsify-napi-addon: no .node for host '${process.platform}-${process.arch}' ` +
+            `(libc: ${process.env.LIBC ?? 'unset'}). Addon table knows: ${known}. ` +
+            `Install the platform package or build the addon for this host.`);
+    }
+    // A `.node` outside every `node_modules` has no package IDENTITY to resolve
+    // by, and `packageSpecFor` recorded the path itself. Splitting it as a
+    // specifier made the first segment the package name and the rest the subpath,
+    // so a direct import of a locally built addon resolved a package named ``
+    // and threw naming neither the file nor the remedy. There is nothing to
+    // resolve — the build's path is the only answer — so it is returned, and the
+    // build warns once that this entry does not travel with the bundle.
+    if (isAbsolute(spec))
+        return spec;
+    const { pkg, subpath } = splitPackageSpec(spec);
+    const root = resolvePackageRoot(pkg);
+    if (root !== null) {
+        if (subpath === '')
+            return root;
+        // The subpath is the build's own `relative()` today, so this cannot
+        // reject a table this plugin wrote. It is here because this is the
+        // function that decides which file gets dlopen'd: a table naming `..`
+        // would otherwise walk out of the package it claims to belong to.
+        const target = resolve(root, subpath);
+        if (target !== root && !target.startsWith(root + sep)) {
+            throw new Error(`gjsify-napi-addon: the addon table names '${subpath}', which leaves the package ` +
+                `root '${root}'. A package cannot provide a file outside itself.`);
+        }
+        return target;
+    }
+    // The package is not installed where this bundle can see it. `<bundle
+    // dir>/addons/<package>/` is the declared layout a packaging step would
+    // fill — `gjsify ship` does not yet — so name it and the two remedies.
+    const staged = join(dirname(fileURLToPath(bundleAnchorUrl())), 'addons', pkg, subpath);
+    throw new Error(`gjsify-napi-addon: cannot find the addon package '${pkg}' from this bundle. ` +
+        `A GJS bundle finds its addon by package identity, so '${pkg}' must be installed in a ` +
+        `node_modules reachable from the bundle's own location, or staged at ` +
+        `'${staged}' (a layout no gjsify step fills yet). Run the bundle next to its ` +
+        "project's node_modules, or rebuild where the package is installed.");
+}

package/lib/utils/addon-platform.d.ts

@@ -0,0 +1,23 @@
+/** The one spelling: `linux-x64`, `linux-x64-musl`, `darwin-arm64`, `win32-x64`. */
+export declare function addonPlatformKey(platform: string, arch: string, libc?: string): string;
+/**
+ * A napi-rs triple as an {@link addonPlatformKey}. The ABI token napi-rs appends is
+ * either implied by the platform (`gnu` on linux, `msvc` on win32, the arm eabi
+ * flavours) or a real axis (`musl`) — only the latter survives into the key.
+ */
+export declare function normalizeNapiRsTriple(triple: string): string;
+/**
+ * The keys to try for a host, most specific first.
+ *
+ * A musl host also accepts the UNTAGGED key, because that is what node-gyp-build's own
+ * untagged prebuilds mean — "no libc claim" — and a musl-only tree would otherwise find
+ * nothing. A glibc host does NOT accept the musl key: loading a musl binary against
+ * glibc is the failure this selection exists to avoid, and a missing entry with a clear
+ * message beats a `dlopen` crash.
+ *
+ * `*` is last and is not host-specific: it is the entry a DIRECTLY imported `.node`
+ * writes, where the source named one file and there is no selection to make.
+ */
+export declare function hostAddonKeys(platform: string, arch: string, libc?: string): string[];
+/** The first key of `keys` present in `targets`, or null. */
+export declare function selectAddonTarget(targets: Record<string, string>, keys: string[]): string | null;

package/lib/utils/addon-platform.js

@@ -0,0 +1,50 @@
+// The platform VOCABULARY shared by the two halves of ADR 0084: the build enumerates
+// every `.node` an addon package ships, keyed by platform; the bundle picks one at run
+// time from the host it finds itself on. Both halves must spell a platform the same way
+// or the lookup silently misses, so the spelling lives here — a pure module with no
+// `node:` imports, because the runtime half (`shims/addon-resolve.ts`) is bundled into
+// user output and must not drag the filesystem in.
+//
+// The key is node-gyp-build's tuple (`<platform>-<arch>`) plus a `-musl` suffix, NOT
+// napi-rs' triple: napi-rs spells the same platform `linux-x64-gnu` / `win32-x64-msvc`
+// while prebuildify spells it `linux-x64`, and one bundle can carry addons of both
+// conventions. {@link normalizeNapiRsTriple} folds the second spelling into the first.
+/** The one spelling: `linux-x64`, `linux-x64-musl`, `darwin-arm64`, `win32-x64`. */
+export function addonPlatformKey(platform, arch, libc) {
+    return libc === 'musl' ? `${platform}-${arch}-musl` : `${platform}-${arch}`;
+}
+/**
+ * A napi-rs triple as an {@link addonPlatformKey}. The ABI token napi-rs appends is
+ * either implied by the platform (`gnu` on linux, `msvc` on win32, the arm eabi
+ * flavours) or a real axis (`musl`) — only the latter survives into the key.
+ */
+export function normalizeNapiRsTriple(triple) {
+    if (triple.endsWith('-musl'))
+        return triple;
+    return triple.replace(/-(?:gnu|msvc|eabi|eabihf|gnueabihf|androideabi)$/, '');
+}
+/**
+ * The keys to try for a host, most specific first.
+ *
+ * A musl host also accepts the UNTAGGED key, because that is what node-gyp-build's own
+ * untagged prebuilds mean — "no libc claim" — and a musl-only tree would otherwise find
+ * nothing. A glibc host does NOT accept the musl key: loading a musl binary against
+ * glibc is the failure this selection exists to avoid, and a missing entry with a clear
+ * message beats a `dlopen` crash.
+ *
+ * `*` is last and is not host-specific: it is the entry a DIRECTLY imported `.node`
+ * writes, where the source named one file and there is no selection to make.
+ */
+export function hostAddonKeys(platform, arch, libc) {
+    const base = addonPlatformKey(platform, arch);
+    return libc === 'musl' ? [`${base}-musl`, base, '*'] : [base, '*'];
+}
+/** The first key of `keys` present in `targets`, or null. */
+export function selectAddonTarget(targets, keys) {
+    for (const key of keys) {
+        const hit = targets[key];
+        if (typeof hit === 'string' && hit.length > 0)
+            return hit;
+    }
+    return null;
+}

package/lib/utils/auto-globals.d.ts

@@ -55,6 +55,12 @@ export interface DetectAutoGlobalsOptions {
      * `process.cwd()`.
      */
     cwd?: string;
+    /**
+     * A second root for that gate: the running CLI's directory when the build was given
+     * a `toolchainAnchor`, whose resolver takes a `@gjsify/*` the project lacks from
+     * beside the CLI. Only consulted together with `cwd`.
+     */
+    toolchainDir?: string;
 }
 /**
  * Build options for the analyser: the same input options the caller would use for the

package/lib/utils/auto-globals.js

@@ -81,7 +81,7 @@ function isSubset(a, b) {
             return false;
     return true;
 }
-async function applyExcludeGlobals(detected, currentInject, extraRegisterPaths, excludeGlobals, cwd) {
+async function applyExcludeGlobals(detected, currentInject, extraRegisterPaths, excludeGlobals, cwd, searchDirs = cwd) {
     if (excludeGlobals?.length) {
         for (const id of excludeGlobals)
             detected.delete(id);
@@ -91,12 +91,12 @@ async function applyExcludeGlobals(detected, currentInject, extraRegisterPaths,
     const finalPaths = detectedToRegisterPaths(detected);
     for (const p of extraRegisterPaths)
         finalPaths.add(p);
-    emitGiBackedDiagnostic(finalPaths, detected, cwd);
+    emitGiBackedDiagnostic(finalPaths, detected, searchDirs);
     // No exclude: `currentInject` already reflects `finalPaths`, so reuse it —
     // re-running filterResolvableRegisterPaths would repeat its skip warnings.
     if (!excludeGlobals?.length)
         return { detected, injectPath: currentInject };
-    const filtered = cwd ? filterResolvableRegisterPaths(finalPaths, cwd) : finalPaths;
+    const filtered = searchDirs ? filterResolvableRegisterPaths(finalPaths, searchDirs) : finalPaths;
     const injectPath = filtered.size > 0 ? ((await writeRegisterInjectFile(filtered, cwd)) ?? undefined) : undefined;
     return { detected, injectPath };
 }
@@ -169,14 +169,14 @@ let giNoteEmitted = false;
  * register, via `isRegisterPathResolvable` rather than
  * `filterResolvableRegisterPaths` to avoid duplicating that one's skip warnings.
  */
-function emitGiBackedDiagnostic(registerPaths, detected, cwd) {
+function emitGiBackedDiagnostic(registerPaths, detected, searchDirs) {
     if (giNoteEmitted)
         return;
     const candidates = new Set();
     for (const path of registerPaths) {
         if (!giNamespacesForRegister(path))
             continue;
-        if (cwd && !isRegisterPathResolvable(path, cwd))
+        if (searchDirs && !isRegisterPathResolvable(path, searchDirs))
             continue;
         candidates.add(path);
     }
@@ -189,6 +189,70 @@ function emitGiBackedDiagnostic(registerPaths, detected, cwd) {
 function isFullConfig(v) {
     return v !== null && typeof v === 'object' && !Array.isArray(v) && 'plugins' in v && 'options' in v;
 }
+/**
+ * Merge the orchestrator's `transform` with the analysis side's, PER KEY — the
+ * analysis side wins for the keys it actually sets.
+ *
+ * `analysisOptions.transform ?? orchestratorOptions?.transform` was wrong for a
+ * MEASURED reason, not a stylistic one: the CLI's config merge does
+ * `bundler.transform ??= {}` (`@gjsify/cli` `src/config.ts`), so the analysis side is
+ * ALWAYS a non-nullish object and `??` therefore always took it — dropping the
+ * orchestrator's `target`, `define` and `inject` from every single analysis pass. The
+ * detector then reads a bundle transformed differently from the one that ships, which
+ * is exactly what the "analyse the bundled output AFTER tree-shaking" invariant exists
+ * to prevent.
+ *
+ * What that cost, measured on `--app gjs`, whose orchestrator defines
+ * `process.env.READABLE_STREAM` to `"disable"`. Entry:
+ *
+ *     if (process.env.READABLE_STREAM !== 'disable') document.getElementById('app');
+ *
+ * The define makes that branch dead, so the emitted bundle carries no `document`
+ * reference at all — and the build injected `document` + `HTMLCanvasElement` + `Path2D`
+ * anyway: 24 globals and 276_726 bytes where the same entry now yields 21 and 176_487.
+ * 100 KB of DOM/canvas register code, one of it a GI-backed register that makes the
+ * artifact hard-require a GTK runtime at load. Silently, at exit 0.
+ *
+ * Note what does NOT discriminate here, so the next reproduction does not start with
+ * it: `process` is detected on every `--app gjs` build regardless, because the process
+ * stub the target prepends in `renderChunk` writes `globalThis.process` and the
+ * detector reads its own banner back.
+ *
+ * `define` and `inject` are string maps and merge per key; every other transform key is
+ * a scalar (`target`, `lang`, `sourceType`) or a coherent option bag (`typescript`,
+ * `decorator`, `assumptions`, `tsconfig`) that is replaced whole. This is deliberately
+ * the same shape as `mergeBundlerOptions` in `@gjsify/cli`, which merges the FINAL
+ * build's options: the two must agree, or the analysis is measuring a different bundle
+ * again one key further down.
+ */
+function mergeTransformOptions(orchestrator, analysis) {
+    if (!orchestrator)
+        return analysis;
+    if (!analysis)
+        return orchestrator;
+    const merged = { ...orchestrator, ...analysis };
+    if (orchestrator.define || analysis.define) {
+        merged.define = { ...orchestrator.define, ...analysis.define };
+    }
+    if (orchestrator.inject || analysis.inject) {
+        merged.inject = { ...orchestrator.inject, ...analysis.inject };
+    }
+    return merged;
+}
+/**
+ * Same per-key rule for `resolve`. No caller sets `analysisOptions.resolve` today, so
+ * this is inert right now — it is here because `resolve` is the third plain-object
+ * field on the same code path and a whole-object `??` on it would silently drop the
+ * orchestrator's `conditionNames`/`mainFields`, which is the divergence the class
+ * comment above describes.
+ */
+function mergeResolveOptions(orchestrator, analysis) {
+    if (!orchestrator)
+        return analysis;
+    if (!analysis)
+        return orchestrator;
+    return { ...orchestrator, ...analysis };
+}
 /**
  * Run the iterative in-memory build with acorn-based global detection, each pass
  * seeded by the previous pass's globals, until the detected set is stable. Returns the
@@ -201,10 +265,13 @@ export async function detectAutoGlobals(analysisOptions, pluginOptions, gjsifyPl
         : new Set();
     const excludeSet = new Set(options.excludeGlobals ?? []);
     const cwd = options.cwd;
+    const searchDirs = cwd && options.toolchainDir ? [cwd, options.toolchainDir] : cwd;
     let detected = new Set();
     let currentInject = undefined;
     if (extraRegisterPaths.size > 0) {
-        const resolvableExtra = cwd ? filterResolvableRegisterPaths(extraRegisterPaths, cwd) : extraRegisterPaths;
+        const resolvableExtra = searchDirs
+            ? filterResolvableRegisterPaths(extraRegisterPaths, searchDirs)
+            : extraRegisterPaths;
         currentInject = (await writeRegisterInjectFile(resolvableExtra, cwd)) ?? undefined;
     }
     // Caller plugins (e.g. the PnP relay) survive every pass; the gjsify plugin is
@@ -237,10 +304,16 @@ export async function detectAutoGlobals(analysisOptions, pluginOptions, gjsifyPl
             : analysisOptions.input;
         // Take resolve/external/transform from the orchestrator so the analysis bundle
         // goes through the same module resolution as the final build; explicit
-        // analysis-side overrides win.
-        const mergedResolve = analysisOptions.resolve ?? orchestratorOptions?.resolve;
+        // analysis-side overrides win PER KEY (see `mergeTransformOptions`).
+        //
+        // `external` stays a whole-value choice on purpose: it is not a plain object
+        // (string | RegExp | array | predicate), the orchestrator's array has already
+        // folded the caller's own entries in, and the shape rules an array cannot
+        // express live in `externalsPlugin` — which is part of `gjsifyPluginsArray`
+        // below, so it applies to the analysis bundle whichever array wins here.
+        const mergedResolve = mergeResolveOptions(orchestratorOptions?.resolve, analysisOptions.resolve);
         const mergedExternal = analysisOptions.external ?? orchestratorOptions?.external;
-        const mergedTransform = analysisOptions.transform ?? orchestratorOptions?.transform;
+        const mergedTransform = mergeTransformOptions(orchestratorOptions?.transform, analysisOptions.transform);
         const orchTreeshake = orchestratorOptions?.treeshake;
         const gjsifyPluginsArray = Array.isArray(gjsifyInstance) ? gjsifyInstance : [gjsifyInstance];
         const chunkCodes = await bundler({
@@ -311,7 +384,7 @@ export async function detectAutoGlobals(analysisOptions, pluginOptions, gjsifyPl
                 const extras = extraRegisterPaths.size > 0 ? ` (+ ${extraRegisterPaths.size} extra register module(s))` : '';
                 console.debug(`[gjsify] --globals auto: converged after ${iteration - 1} iteration(s), ${detected.size} global(s)${sorted.length ? ': ' + sorted.join(', ') : ''}${extras}`);
             }
-            return applyExcludeGlobals(detected, currentInject, extraRegisterPaths, options.excludeGlobals, cwd);
+            return applyExcludeGlobals(detected, currentInject, extraRegisterPaths, options.excludeGlobals, cwd, searchDirs);
         }
         // Seed the next pass with the precomputed closure. Unioning with the
         // previously-injected set keeps growth monotonic — an over-approximated superset
@@ -335,8 +408,8 @@ export async function detectAutoGlobals(analysisOptions, pluginOptions, gjsifyPl
         // Drop register paths whose polyfill package is not installed: an unresolvable
         // import is a HARD Rolldown error, strictly worse than skipping with a warning.
         // The caller adds the dep or acknowledges the gap via --exclude-globals.
-        if (cwd)
-            registerPaths = filterResolvableRegisterPaths(registerPaths, cwd);
+        if (searchDirs)
+            registerPaths = filterResolvableRegisterPaths(registerPaths, searchDirs);
         if (registerPaths.size === 0) {
             return { detected, injectPath: undefined };
         }
@@ -349,7 +422,7 @@ export async function detectAutoGlobals(analysisOptions, pluginOptions, gjsifyPl
     if (verbose) {
         console.debug(`[gjsify] --globals auto: hit max iterations (${MAX_ITERATIONS}), using last detected set`);
     }
-    return applyExcludeGlobals(detected, currentInject, extraRegisterPaths, options.excludeGlobals, cwd);
+    return applyExcludeGlobals(detected, currentInject, extraRegisterPaths, options.excludeGlobals, cwd, searchDirs);
 }
 /**
  * `--app node` genuine-GJS-source detection (the reverse of `--globals auto`).
@@ -408,8 +481,12 @@ export async function detectNodeGiGlobals(analysisOptions, pluginOptions, gjsify
                 ...baseOptions,
                 input: analysisOptions.input,
                 external: analysisOptions.external ?? baseOptions.external,
-                resolve: analysisOptions.resolve ?? baseOptions.resolve,
-                transform: analysisOptions.transform ?? baseOptions.transform,
+                // Per key, for the reason spelled out on `mergeTransformOptions`: the
+                // CLI always hands an object here, so a whole-object `??` dropped this
+                // target's `target: 'node24'` and `define: { global, window }` from
+                // every reverse-bridge analysis pass.
+                resolve: mergeResolveOptions(baseOptions.resolve, analysisOptions.resolve),
+                transform: mergeTransformOptions(baseOptions.transform, analysisOptions.transform),
                 plugins: [...callerPlugins, ...gjsifyPluginsArray],
                 logLevel: 'silent',
             },

package/lib/utils/declare-build-input.d.ts

@@ -0,0 +1,13 @@
+/** One file the output depends on. */
+export type DeclareBuildInput = (abs: string) => void;
+/** A plugin context that MAY carry `addWatchFile` — an older engine does not. */
+export interface WatchFileCapableContext {
+    addWatchFile?: (id: string) => void;
+}
+/**
+ * `this.addWatchFile(abs)`, or one line saying it was missing.
+ *
+ * The context is passed in rather than bound, so each caller keeps its own `this`
+ * and this stays usable from any hook shape.
+ */
+export declare function declareBuildInput(ctx: WatchFileCapableContext, abs: string): void;

package/lib/utils/declare-build-input.js

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: MIT
+// "This file is an input of the output" — `this.addWatchFile`, one layer down.
+//
+// Two of this package's plugins read a file the BUNDLER never sees: a
+// stylesheet's `@import` chain (`css-as-string`) and a package's own
+// `readFileSync(new URL(..., import.meta.url))` (the static-read inliner, which
+// folds the bytes into the bundle). Neither file is a module, so no graph names
+// it and a `gjsify test` bundle that depends on one reads as fresh after it
+// changes. `this.addWatchFile` is the standard contract for exactly that, and
+// this is the one place it is issued from.
+//
+// FEATURE-DETECTED, and that is measured, not defensive: the engine the GJS CLI
+// loads is resolved through several anchors, and one of them answered with a
+// build whose plugin context had no such method — a direct call then fails the
+// build with `this.addWatchFile is not a function`. A build must not fail over
+// bookkeeping, so a miss degrades to a single line naming the consequence and the
+// fix. The other half is in the CLI: a bundle whose build reported NO watch list
+// can never be called fresh (`utils/bundle-inputs.ts`).
+let _warned = false;
+/**
+ * `this.addWatchFile(abs)`, or one line saying it was missing.
+ *
+ * The context is passed in rather than bound, so each caller keeps its own `this`
+ * and this stays usable from any hook shape.
+ */
+export function declareBuildInput(ctx, abs) {
+    if (typeof ctx.addWatchFile === 'function') {
+        ctx.addWatchFile.call(ctx, abs);
+        return;
+    }
+    if (_warned)
+        return;
+    _warned = true;
+    console.warn('[gjsify] this Rolldown engine has no `addWatchFile`, so a file a plugin read itself is ' +
+        'not declared as a build input — editing one may leave a `gjsify test` bundle looking ' +
+        'fresh. Upgrade `@gjsify/rolldown-native` (the GJS engine) to declare it.');
+}

package/lib/utils/detect-free-globals.d.ts

@@ -1,3 +1,6 @@
+import * as acorn from 'acorn';
+/** Every name bound by a binding pattern. */
+export declare function extractBindingNames(node: acorn.AnyNode): string[];
 /**
  * Free identifiers in bundled output that match the known web/Node globals in
  * `GJS_GLOBALS_MAP` — drives `--app gjs --globals auto`. Rules: `scanFreeGlobals`.

package/lib/utils/detect-free-globals.js

@@ -69,7 +69,7 @@ function wbgJsNameFor(fnName) {
     return match?.[1] ?? null;
 }
 /** Every name bound by a binding pattern. */
-function extractBindingNames(node) {
+export function extractBindingNames(node) {
     if (!node)
         return [];
     switch (node.type) {

package/lib/utils/entry-wrapper.js

@@ -25,7 +25,12 @@ export function wrapInputWithSideEffects(input, sideEffects, opts = {}) {
     const userEntries = new Map(); // virtualId → realPath
     const PREFIX = `${GJSIFY_VIRTUAL_PREFIX}entry:`;
     function wrap(realPath) {
-        const id = PREFIX + realPath;
+        // The wrapper is ESM whatever the entry is, and Rolldown reads a module's
+        // format off its id's EXTENSION: `\0gjsify-entry:…/prettier.cjs` was parsed as
+        // CommonJS and every `import` in the wrapper failed with `PARSE_ERROR: Cannot
+        // use import statement outside a module`. A CJS entry therefore gets `.mjs`
+        // appended; the others keep the id they always had.
+        const id = PREFIX + realPath + (/\.c[jt]sx?$/i.test(realPath) ? '.mjs' : '');
         userEntries.set(id, realPath);
         return id;
     }

package/lib/utils/index.d.ts

@@ -9,3 +9,4 @@ export { inlineStaticReads, isAbsoluteFsPath, isWithin, resourceRootFor } from '
 export { GJSIFY_VIRTUAL_PREFIX, isGjsifyVirtualModuleId } from './virtual-module-id.js';
 export { locateSurvivingJsx, classifyJsxParseFailure, formatSurvivingJsx } from './jsx-survival.js';
 export type { SurvivingJsx } from './jsx-survival.js';
+export { wrapInputWithSideEffects } from './entry-wrapper.js';

package/lib/utils/index.js

@@ -8,3 +8,4 @@ export { resolveGlobalsList, writeRegisterInjectFile } from './scan-globals.js';
 export { inlineStaticReads, isAbsoluteFsPath, isWithin, resourceRootFor } from './inline-static-reads.js';
 export { GJSIFY_VIRTUAL_PREFIX, isGjsifyVirtualModuleId } from './virtual-module-id.js';
 export { locateSurvivingJsx, classifyJsxParseFailure, formatSurvivingJsx } from './jsx-survival.js';
+export { wrapInputWithSideEffects } from './entry-wrapper.js';

package/lib/utils/inline-static-reads.d.ts

@@ -1,4 +1,18 @@
-export declare function inlineStaticReads(src: string, sourceFilePath: string): {
+import * as acorn from 'acorn';
+/**
+ * Parse a source with the parser its extension calls for.
+ *
+ * The TypeScript half is why first-party sources were invisible to this inliner
+ * for as long as it was scoped to `node_modules`: an installed package ships JS,
+ * so plain acorn could always parse it, and nothing ever asked what happens to a
+ * `.ts`. The answer was that `acorn.parse` threw and the `catch` returned
+ * "nothing to inline" — a result indistinguishable from a file that genuinely has
+ * no static reads. Measured on `packages/infra/cli/src/utils/app-metadata.ts`:
+ * `inlined: 0`, while the identical expression in a `.js` file returned
+ * `inlined: 1`.
+ */
+export declare function parseSource(src: string, sourceFilePath: string): acorn.Program;
+export declare function inlineStaticReads(src: string, sourceFilePath: string, declare?: (abs: string) => void): {
     contents: string;
     inlined: number;
 };