@gjsify/rolldown-plugin-gjsify 0.51.1 → 0.53.0

package/lib/plugins/rewrite-node-modules-paths.js

@@ -26,7 +26,9 @@
 // until 2026-08-22 — see `shouldInline` for the incident that measured the cost.
 import { createRequire } from 'node:module';
 import { dirname, join, relative, resolve } from 'node:path';
-import { inlineStaticReads } from '../utils/inline-static-reads.js';
+import { inlineStaticReads, parseSource } from '../utils/inline-static-reads.js';
+import { declareBuildInput } from '../utils/declare-build-input.js';
+import { hasZipSegment } from '../utils/zip-path.js';
 export const REWRITE_FILTER = /\.(m?js|cjs|[cm]?tsx?)$/;
 const DIRNAME_DECL_RE = /(?:var|let|const)\s+__dirname\b|export\s+(?:var|let|const)\s+__dirname\b/;
 const FILENAME_DECL_RE = /(?:var|let|const)\s+__filename\b|export\s+(?:var|let|const)\s+__filename\b/;
@@ -162,6 +164,132 @@ function needsDirnameDecl(src, flags) {
 function needsFilenameDecl(src, flags) {
     return flags.hasFilename && !FILENAME_DECL_RE.test(src);
 }
+// The local name the file-URL → path conversion is imported under. Prefixed so it
+// cannot collide with a `fileURLToPath` the dep declares itself.
+const URL_TO_PATH = '__gjsifyFileURLToPath';
+/**
+ * A path expression for the file URL `url`, with `fileURLToPath` semantics.
+ *
+ * It used to be `new URL(…).pathname`, which is a URL PATH, not a filesystem path, and
+ * the two part ways twice: percent-escapes stay encoded (`/my%20app/x.js` on any OS),
+ * and on win32 the drive comes out as `/C:/…`, which no Windows API accepts. Every
+ * target has a `fileURLToPath` behind `node:url` (Node's own; `@gjsify/url` on GJS and
+ * in the browser), and the case-1 shim already relies on it.
+ *
+ * `dir` strips the trailing separator the directory URL leaves behind — either one,
+ * since win32 answers `\`.
+ */
+function urlToPathExpr(url, dir = false) {
+    const path = `${URL_TO_PATH}(${url})`;
+    return dir ? `${path}.replace(/[\\\\/]$/, "")` : path;
+}
+/**
+ * The import the {@link urlToPathExpr} expressions need, when any of them survive.
+ *
+ * A non-empty `preamble` is NOT the condition. When a file declares its OWN `__dirname`,
+ * {@link routeMetaPaths} declines the declaration and hands back the raw expression, so
+ * `import.meta.dirname` is still rewritten to a `__gjsifyFileURLToPath(…)` call while the
+ * preamble stays EMPTY — and a header keyed on `preamble.length` leaves that call bound to
+ * nothing. Measured: a node_modules dep with `var __dirname = "MINE"` beside
+ * `import.meta.dirname` emitted a bare `__gjsifyFileURLToPath(…)` and died on the
+ * ReferenceError at first use. `substitutes` is the same `import.meta` test the callers
+ * already branch on, so the header tracks what the output actually references.
+ */
+function urlToPathHeader(preamble, substitutes) {
+    return preamble.length > 0 || substitutes
+        ? `import { fileURLToPath as ${URL_TO_PATH} } from "node:url";`
+        : undefined;
+}
+/**
+ * Route `import.meta.dirname`/`filename` the way the caller routes a bare
+ * `__dirname`/`__filename`: ONE `var` in the preamble, every occurrence referencing it.
+ * Answering them at all is the point — a bundled dep's location tokens must never
+ * resolve to the BUNDLE: @signalapp/libsignal-client's
+ * `node-gyp-build(import.meta.dirname + '/..')` looked beside the bundle and threw
+ * "No native build was found". (The addon package itself stays external now; a
+ * NON-addon dep spelling `import.meta.dirname` still lands here.) Case 1 answers inline
+ * through the runtime shim instead, and a file that declares its OWN `__dirname` keeps
+ * the inline expression, so a generated declaration can never collide with it.
+ */
+function routeMetaPaths(src, flags, decl) {
+    const declareDirname = (flags.hasDirname || /\bimport\.meta\.dirname\b/.test(src)) && !DIRNAME_DECL_RE.test(src);
+    const declareFilename = (flags.hasFilename || /\bimport\.meta\.filename\b/.test(src)) && !FILENAME_DECL_RE.test(src);
+    return {
+        preamble: [
+            ...(declareDirname ? [`var __dirname = ${decl.dirname};`] : []),
+            ...(declareFilename ? [`var __filename = ${decl.filename};`] : []),
+        ],
+        dirname: declareDirname ? '__dirname' : decl.dirname,
+        filename: declareFilename ? '__filename' : decl.filename,
+    };
+}
+const IMPORT_META_PROPS = ['url', 'dirname', 'filename'];
+const IMPORT_META_RE = /\bimport\.meta\.(url|dirname|filename)\b/g;
+/** Every `import.meta.<url|dirname|filename>` EXPRESSION in `src`, or null when it does not parse. */
+function importMetaRanges(src, path) {
+    let ast;
+    try {
+        ast = parseSource(src, path);
+    }
+    catch {
+        // acorn trails the bundler on new syntax; the caller keeps the token rewrite.
+        return null;
+    }
+    const ranges = [];
+    const stack = [ast];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (node === null || typeof node !== 'object')
+            continue;
+        if (Array.isArray(node)) {
+            stack.push(...node);
+            continue;
+        }
+        const object = node.object;
+        const property = node.property;
+        if (node.type === 'MemberExpression' &&
+            !node.computed &&
+            object?.type === 'MetaProperty' &&
+            object.meta?.name === 'import' &&
+            object.property?.name === 'meta' &&
+            property?.type === 'Identifier' &&
+            IMPORT_META_PROPS.includes(property.name ?? '')) {
+            ranges.push({
+                start: node.start,
+                end: node.end,
+                prop: property.name,
+            });
+            continue;
+        }
+        for (const value of Object.values(node))
+            if (value !== null && typeof value === 'object')
+                stack.push(value);
+    }
+    return ranges;
+}
+/**
+ * Replace every `import.meta.url` / `.dirname` / `.filename` expression in `src`.
+ *
+ * On the AST, not the text: the token also occurs inside STRINGS, and a text rewrite
+ * put a quoted replacement inside a quoted key — vite's `define: { "import.meta.url":
+ * … }` became `"__gjsifyModuleUrl("vite/…")"`, a PARSE_ERROR ("Expected `:` but found
+ * `Identifier`") that failed every `--app gjs` build reaching vite or wxt. A source
+ * acorn cannot parse keeps the token rewrite it always had.
+ *
+ * `dirname` and `filename` (Node ≥ 20.11) are answered too: GJS defines neither, so
+ * unplugin's `path.resolve(import.meta.dirname, …)` threw `The "path" argument must be
+ * of type string. Received type undefined` at load — where wxt's rebuild stopped next.
+ */
+export function replaceImportMeta(src, path, replacements) {
+    const ranges = importMetaRanges(src, path);
+    if (ranges === null)
+        return src.replace(IMPORT_META_RE, (_m, prop) => replacements[prop]);
+    let out = src;
+    for (const { start, end, prop } of ranges.sort((a, b) => b.start - a.start)) {
+        out = out.slice(0, start) + replacements[prop] + out.slice(end);
+    }
+    return out;
+}
 /** Prepend preamble + (optional) shim import to the source. */
 function withPreamble(src, lines, importHeader) {
     const parts = importHeader ? [importHeader, ...lines, src] : [...lines, src];
@@ -185,7 +313,15 @@ function rewriteOnDiskEsm(src, path, flags) {
         preamble.push(`var __filename = __gjsifyModuleFile(${spec});`);
         used.push('__gjsifyModuleFile');
     }
-    const code = src.replace(/\bimport\.meta\.url\b/g, `__gjsifyModuleUrl(${spec})`);
+    if (src.includes('import.meta.dirname') && !used.includes('__gjsifyModuleDir'))
+        used.push('__gjsifyModuleDir');
+    if (src.includes('import.meta.filename') && !used.includes('__gjsifyModuleFile'))
+        used.push('__gjsifyModuleFile');
+    const code = replaceImportMeta(src, path, {
+        url: `__gjsifyModuleUrl(${spec})`,
+        dirname: `__gjsifyModuleDir(${spec})`,
+        filename: `__gjsifyModuleFile(${spec})`,
+    });
     const header = `import { ${used.join(', ')} } from ${JSON.stringify(MODULE_RESOLVE_SHIM)};`;
     return { code: withPreamble(code, preamble, header), moduleType: moduleTypeForPath(path) };
 }
@@ -197,29 +333,40 @@ function rewriteOnDiskEsm(src, path, flags) {
 function rewriteOnDiskEsmLegacy(src, path, bundleDir, flags) {
     const relPath = relative(bundleDir, path);
     const relDirWithSlash = (relative(bundleDir, dirname(path)) || '.') + '/';
-    const preamble = [];
-    if (needsDirnameDecl(src, flags)) {
-        preamble.push(`var __dirname = new URL(${JSON.stringify(relDirWithSlash)}, import.meta.url).pathname.replace(/\\/$/, "");`);
-    }
-    if (needsFilenameDecl(src, flags)) {
-        preamble.push(`var __filename = new URL(${JSON.stringify(relPath)}, import.meta.url).pathname;`);
-    }
-    const code = src.replace(/\bimport\.meta\.url\b/g, `new URL(${JSON.stringify(relPath)}, import.meta.url).href`);
-    return { code: withPreamble(code, preamble), moduleType: moduleTypeForPath(path) };
+    const route = routeMetaPaths(src, flags, {
+        dirname: urlToPathExpr(`new URL(${JSON.stringify(relDirWithSlash)}, import.meta.url)`, true),
+        filename: urlToPathExpr(`new URL(${JSON.stringify(relPath)}, import.meta.url)`),
+    });
+    const code = replaceImportMeta(src, path, {
+        url: `new URL(${JSON.stringify(relPath)}, import.meta.url).href`,
+        dirname: route.dirname,
+        filename: route.filename,
+    });
+    const substitutes = /\bimport\.meta\.(?:dirname|filename)\b/.test(src);
+    return {
+        code: withPreamble(code, route.preamble, urlToPathHeader(route.preamble, substitutes)),
+        moduleType: moduleTypeForPath(path),
+    };
 }
 /**
  * Case 3 — PnP zip-resident. Keep `import.meta.url` as the bundle's own URL and
  * derive `__dirname`/`__filename` from it.
  */
 function rewriteZipResident(src, path, flags) {
-    const preamble = [];
-    if (needsDirnameDecl(src, flags)) {
-        preamble.push(`var __dirname = new URL(".", import.meta.url).pathname.replace(/\\/$/, "");`);
-    }
-    if (needsFilenameDecl(src, flags)) {
-        preamble.push(`var __filename = new URL(import.meta.url).pathname;`);
-    }
-    return { code: withPreamble(src, preamble), moduleType: moduleTypeForPath(path) };
+    const route = routeMetaPaths(src, flags, {
+        dirname: urlToPathExpr('new URL(".", import.meta.url)', true),
+        filename: urlToPathExpr('import.meta.url'),
+    });
+    // `import.meta.url` keeps case 3's rule (the bundle's own URL); only the two
+    // members GJS does not define are routed through the declarations.
+    const substitutes = /\bimport\.meta\.(?:dirname|filename)\b/.test(src);
+    const code = substitutes
+        ? replaceImportMeta(src, path, { url: 'import.meta.url', dirname: route.dirname, filename: route.filename })
+        : src;
+    return {
+        code: withPreamble(code, route.preamble, urlToPathHeader(route.preamble, substitutes)),
+        moduleType: moduleTypeForPath(path),
+    };
 }
 /**
  * Case 4a — CJS, runtime-resolve. `__dirname`/`__filename` come from the module-resolve
@@ -269,13 +416,16 @@ function rewriteCjsAbsolute(src, path, flags) {
  * Pure rewriter: the rewritten code plus the module type to re-parse it with, or `null`
  * when the file references none of the tokens.
  */
-export function rewriteContents(args, srcInput, bundleDir, runtimeResolve) {
+export function rewriteContents(args, srcInput, bundleDir, runtimeResolve, declare) {
     if (!shouldRewrite(args.path))
         return null;
-    const inlined = inlineStaticReads(srcInput, args.path);
+    const inlined = inlineStaticReads(srcInput, args.path, declare);
     const src = inlined.contents;
     const flags = {
-        hasMetaUrl: src.includes('import.meta.url'),
+        // A file that spelled ANY `import.meta.*` location is ESM, so it keeps the ESM
+        // strategies even when `import.meta.url` itself never appeared. The strategies
+        // answer all three on the AST (see `replaceImportMeta`), never as text.
+        hasMetaUrl: /\bimport\.meta\.(?:url|dirname|filename)\b/.test(src),
         hasDirname: src.includes('__dirname'),
         hasFilename: src.includes('__filename'),
     };
@@ -285,7 +435,7 @@ export function rewriteContents(args, srcInput, bundleDir, runtimeResolve) {
     }
     // Step 2: dispatch by case (see file header).
     if (flags.hasMetaUrl) {
-        if (relative(bundleDir, args.path).includes('.zip/')) {
+        if (hasZipSegment(relative(bundleDir, args.path))) {
             return rewriteZipResident(src, args.path, flags);
         }
         return runtimeResolve
@@ -319,8 +469,14 @@ export function nodeModulesPathRewritePlugin(options) {
             order: 'post',
             filter: { id: REWRITE_FILTER },
             handler(code, id) {
+                // What the inliner FOLDS into the bundle is an input of the
+                // output and no module graph names it, so it is declared through
+                // the standard contract — the same one `css-as-string` uses.
+                // Feature-detected, and the reason is measured: see
+                // `utils/declare-build-input.ts`.
+                const declare = (abs) => declareBuildInput(this, abs);
                 if (id.includes('node_modules')) {
-                    const result = rewriteContents({ path: id }, code, options.bundleDir, runtimeResolve);
+                    const result = rewriteContents({ path: id }, code, options.bundleDir, runtimeResolve, declare);
                     if (!result)
                         return null;
                     return { code: result.code, map: null };
@@ -330,7 +486,7 @@ export function nodeModulesPathRewritePlugin(options) {
                 // is the node_modules question this plugin was written for.
                 if (!shouldInline(id))
                     return null;
-                const inlined = inlineStaticReads(code, id);
+                const inlined = inlineStaticReads(code, id, declare);
                 return inlined.inlined > 0 ? { code: inlined.contents, map: null } : null;
             },
         },

package/lib/plugins/unresolved-workspace-import.js

@@ -20,6 +20,8 @@
 // on the old fall-through instead of promoting a user's own mapping mistake to a
 // fatal error in a plugin they did not ask for.
 import { dirname } from 'node:path';
+/** Marks this plugin's own `this.resolve` probes (`custom` resolve option). */
+const OWN_PROBE = 'gjsify-unresolved-workspace-import/probe';
 /** Bare `@gjsify/*` package specifier — the workspace edge this guard protects. */
 const WORKSPACE_SCOPE = '@gjsify/';
 /**
@@ -169,10 +171,8 @@ function describeResolverFailure(err) {
  */
 export function unresolvedWorkspaceImportPlugin(options) {
     const { target, aliases, isExternal, toolchainAnchor } = options;
-    // Re-entrancy belt: `skipSelf: true` should keep our own `this.resolve` out of
-    // this hook, but a hang is a far worse failure than a missed check. Keyed by
-    // `candidate\0importer` — the same package legitimately resolves from many.
-    const inFlight = new Set();
+    // Resolutions in flight, by the cache key — concurrent askers await the same one.
+    const pending = new Map();
     // Read only on the failure path, to recover the `node:fs` behind a failed
     // `@gjsify/fs`.
     const reverseAliases = buildReverseAliasIndex(aliases);
@@ -200,6 +200,12 @@ export function unresolvedWorkspaceImportPlugin(options) {
                 const importer = typeof rawImporter === 'string' ? rawImporter : undefined;
                 if (extraOptions?.isEntry)
                     return null;
+                // Re-entrancy belt: `skipSelf: true` should keep our own probes out of
+                // this hook, but one that got back in would now await ITSELF below — a
+                // hang, far worse than a missed check. The probes carry a marker, so the
+                // belt tells re-entrancy from a concurrent ask instead of guessing.
+                if (extraOptions?.custom?.[OWN_PROBE])
+                    return null;
                 // The toolchain fallback below re-enters this hook with the anchor as
                 // the importer. Declining there keeps the probe from rescuing itself:
                 // the anchor cannot answer for the anchor, and the recursion has no
@@ -216,75 +222,90 @@ export function unresolvedWorkspaceImportPlugin(options) {
                 const cached = resolvedCache.get(key);
                 if (cached)
                     return cached;
-                if (inFlight.has(key))
-                    return null;
-                inFlight.add(key);
-                let resolved = null;
-                // KEPT DELIBERATELY, and NOT as a miss. `this.resolve` re-runs the whole
-                // `pre`-order chain, so it can fail two very different ways. "Nothing is
-                // there" is `null` on both engines — npm `rolldown` always answered that,
-                // and `@gjsify/rolldown-native` now does too (`isResolveMiss`, which is
-                // where the engine mismatch that hid this plugin's diagnostic under GJS
-                // is fixed). What reaches this catch is the OTHER kind: a hook in that
-                // chain throwing on purpose (`napi-node-addon`'s `resolveAddonPath`), an
-                // EACCES, a corrupt `package.json`, a bridge fault. Letting it escape
-                // surfaces it as a bare "plugin `gjsify-alias` threw an error" naming
-                // neither specifier nor importer; swallowing it would report a real fault
-                // as the user's missing dependency. So it is caught, kept, and thrown
-                // BELOW with this plugin's context around it and the original as `cause`.
-                let resolverFailure;
+                // A CONCURRENT ask for the same key shares the one in flight. The belt
+                // used to answer it with `null`, as if it were re-entrancy, and Rolldown
+                // externalised the specifier: two modules of one directory, or two
+                // `import … from 'node:path'` statements of one module, resolving at the
+                // same moment. Measured twice — web-ext's `lib/cmd/*.js` (loaded in
+                // parallel through dynamic imports) lost the module-resolve shim, and
+                // vite's `chunks/node.js` kept a bare `node:path` — each only when the
+                // scheduler interleaved them, so the same build could pass or fail.
+                const shared = pending.get(key);
+                if (shared)
+                    return shared;
+                const work = resolveCandidate.call(this, source, importer, verdict, extraOptions?.kind, key);
+                pending.set(key, work);
                 try {
-                    resolved = await this.resolve(verdict.candidate, importer, {
-                        skipSelf: true,
-                        kind: extraOptions?.kind,
-                    });
-                }
-                catch (err) {
-                    resolverFailure = err;
+                    return await work;
                 }
                 finally {
-                    inFlight.delete(key);
+                    pending.delete(key);
                 }
-                if (resolved) {
-                    resolvedCache.set(key, resolved);
-                    return resolved;
-                }
-                // Toolchain fallback — see `toolchainAnchor`. Only after a real `null`:
-                // a resolver that ERRORED has not established that the project lacks the
-                // package, and rescuing there would turn "project first, always" into
-                // "project first unless the project errors".
-                if (resolverFailure === undefined && toolchainAnchor !== undefined) {
-                    const fromToolchain = await this.resolve(verdict.candidate, toolchainAnchor, {
-                        skipSelf: true,
-                        kind: extraOptions?.kind,
-                    });
-                    if (fromToolchain) {
-                        // The one visible trace that this artifact is MIXED — some of its
-                        // `@gjsify/*` from the project, this one from the CLI's own
-                        // install, possibly a different major. Without it a rescued build
-                        // and a healthy one have byte-identical logs, and a wrong answer
-                        // that leaves no trace is the expensive kind. Deduplicated by
-                        // `resolvedCache`: one line per (candidate, importer dir, kind).
-                        this.warn(`gjsify: \`${verdict.candidate}\` did not resolve from the project ` +
-                            `(imported by ${importer ?? '<entry>'}) — using the copy installed beside the ` +
-                            `running CLI (${toolchainAnchor}). Build the workspace package to use the ` +
-                            `project's own copy.`);
-                        resolvedCache.set(key, fromToolchain);
-                        return fromToolchain;
-                    }
-                }
-                throw new UnresolvedWorkspaceImportError({
-                    target,
-                    source,
-                    candidate: verdict.candidate,
-                    aliasTarget: verdict.aliasTarget,
-                    aliasedFrom: reverseAliases.get(verdict.candidate)?.filter((s) => s !== source),
-                    importer: importer ?? '<entry>',
-                    ...(resolverFailure === undefined
-                        ? {}
-                        : { resolverFailure: describeResolverFailure(resolverFailure) }),
-                }, resolverFailure);
             },
         },
     };
+    async function resolveCandidate(source, importer, verdict, kind, key) {
+        let resolved = null;
+        // KEPT DELIBERATELY, and NOT as a miss. `this.resolve` re-runs the whole
+        // `pre`-order chain, so it can fail two very different ways. "Nothing is
+        // there" is `null` on both engines — npm `rolldown` always answered that,
+        // and `@gjsify/rolldown-native` now does too (`isResolveMiss`, which is
+        // where the engine mismatch that hid this plugin's diagnostic under GJS
+        // is fixed). What reaches this catch is the OTHER kind: a hook in that
+        // chain throwing on purpose (`napi-node-addon`'s `resolveAddonPath`), an
+        // EACCES, a corrupt `package.json`, a bridge fault. Letting it escape
+        // surfaces it as a bare "plugin `gjsify-alias` threw an error" naming
+        // neither specifier nor importer; swallowing it would report a real fault
+        // as the user's missing dependency. So it is caught, kept, and thrown
+        // BELOW with this plugin's context around it and the original as `cause`.
+        let resolverFailure;
+        try {
+            resolved = await this.resolve(verdict.candidate, importer, {
+                skipSelf: true,
+                kind,
+                custom: { [OWN_PROBE]: true },
+            });
+        }
+        catch (err) {
+            resolverFailure = err;
+        }
+        if (resolved) {
+            resolvedCache.set(key, resolved);
+            return resolved;
+        }
+        // Toolchain fallback — see `toolchainAnchor`. Only after a real `null`:
+        // a resolver that ERRORED has not established that the project lacks the
+        // package, and rescuing there would turn "project first, always" into
+        // "project first unless the project errors".
+        if (resolverFailure === undefined && toolchainAnchor !== undefined) {
+            const fromToolchain = await this.resolve(verdict.candidate, toolchainAnchor, {
+                skipSelf: true,
+                kind,
+                custom: { [OWN_PROBE]: true },
+            });
+            if (fromToolchain) {
+                // The one visible trace that this artifact is MIXED — some of its
+                // `@gjsify/*` from the project, this one from the CLI's own
+                // install, possibly a different major. Without it a rescued build
+                // and a healthy one have byte-identical logs, and a wrong answer
+                // that leaves no trace is the expensive kind. Deduplicated by
+                // `resolvedCache`: one line per (candidate, importer dir, kind).
+                this.warn(`gjsify: \`${verdict.candidate}\` did not resolve from the project ` +
+                    `(imported by ${importer ?? '<entry>'}) — using the copy installed beside the ` +
+                    `running CLI (${toolchainAnchor}). Build the workspace package to use the ` +
+                    `project's own copy.`);
+                resolvedCache.set(key, fromToolchain);
+                return fromToolchain;
+            }
+        }
+        throw new UnresolvedWorkspaceImportError({
+            target,
+            source,
+            candidate: verdict.candidate,
+            aliasTarget: verdict.aliasTarget,
+            aliasedFrom: reverseAliases.get(verdict.candidate)?.filter((s) => s !== source),
+            importer: importer ?? '<entry>',
+            ...(resolverFailure === undefined ? {} : { resolverFailure: describeResolverFailure(resolverFailure) }),
+        }, resolverFailure);
+    }
 }

package/lib/shims/addon-resolve.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 declare function __gjsifyAddonResolve(targets: Record<string, string>): string;