@gjsify/rolldown-plugin-gjsify 0.51.1 → 0.52.0

package/lib/app/browser.js

@@ -1,5 +1,9 @@
 // `--app browser` Rolldown configuration factory.
 //
+// Platform-file forks resolve through `plugins/platform-resolve.ts` on the
+// BROWSER chain (ADR 0032 § 9): `./foo.web.<ext>` ahead of `./foo.<ext>`, one
+// rung, with `.gtk` / `.desktop` / `.native` refused and warned about.
+//
 // Browser builds redirect `@girs/*` and `gi://*` to an empty virtual module
 // (they appear transitively via `@gjsify/unit` and similar packages with
 // GJS-specific code paths) — unless `--gi-renderer` composes the ADR 0034
@@ -22,6 +26,7 @@ import blueprintPlugin from '@gjsify/vite-plugin-blueprint';
 import { ALIASES_NODE_FOR_BROWSER, GI_RENDERERS, getDerivedAliasesSync } from '@gjsify/resolve-npm';
 import { globToEntryPoints } from '../utils/entry-points.js';
 import { gjsImportsEmptyPlugin } from '../plugins/gjs-imports-empty.js';
+import { platformResolvePlugin, browserSuffixChain, BROWSER_REFUSED_SUFFIXES } from '../plugins/platform-resolve.js';
 import { giRendererPlugin } from '../plugins/gi-renderer.js';
 import { cssAsStringPlugin } from '../plugins/css-as-string.js';
 import { unresolvedWorkspaceImportPlugin } from '../plugins/unresolved-workspace-import.js';
@@ -98,6 +103,22 @@ export const setupForBrowser = async (input) => {
     // transform can strip the annotations out from under it (see `GjsifyConfig`).
     const prePlugins = [deepkitPlugin({ reflection: input.pluginOptions.reflection })];
     const plugins = [
+        // Platform-file forks for the browser, ADR 0032 § 9: `.web` → base. One
+        // rung, and `browserSuffixChain`'s doc comment carries why each candidate
+        // second rung is absent. FIRST in the array for the reason `app/gjs.ts`
+        // states: the plugin claims RELATIVE imports only, and a platform fork of
+        // a module that also has a Node-builtin substitution must win over the
+        // substitution, because the fork is the more specific statement. `.gtk`,
+        // `.desktop` and `.native` are deliberately not rungs here and are warned
+        // about when present; `BROWSER_REFUSED_SUFFIXES` carries the reason.
+        // `siblingIndex: true` as on the desktop chain — same population (first-
+        // party relative imports), same directory-listing filter, and without it
+        // a one-rung chain plus three refusals is four failed resolves per import.
+        platformResolvePlugin({
+            suffixes: browserSuffixChain(),
+            refusedSuffixes: BROWSER_REFUSED_SUFFIXES,
+            siblingIndex: true,
+        }),
         // ADR 0034 stage 9 — the `gi://` arm, ahead of the empty redirect so it
         // claims the specifier first, exactly as `gjsGiNodePlugin` does on the node
         // target. `emptyGirs` follows it: with the arm on, `@girs/<ns>-<ver>` must
@@ -106,6 +127,12 @@ export const setupForBrowser = async (input) => {
         ...(giRenderer ? [giRendererPlugin({ app: 'browser', ...giRenderer })] : []),
         gjsImportsEmptyPlugin({ emptyGirs: !giRenderer }),
         aliasPlugin({ entries: aliasEntries }),
+        // Blueprint has been registered here since it was registered anywhere, and until the
+        // `?shared-tree` exit existed the XML string it emitted had no reader on this target:
+        // a browser has no `Gtk.Builder`, so `import Template from './x.blp'` compiled, shipped
+        // its bytes and was never parsed by anything. It stays — a `--app browser` build of a
+        // GJS app's sources must not start failing on an import that used to resolve — and the
+        // exit a browser can actually use is now beside it.
         blueprintPlugin(),
         cssAsStringPlugin(),
         // `order: 'post'` — see app/gjs.ts. The browser target's whole job is to

package/lib/app/nativescript.js

@@ -33,8 +33,12 @@
 // PACKAGE NAME still routes per its declared slot in a single hop.
 //
 // No `cssAsStringPlugin` (NativeScript ships its own CSS pipeline as part
-// of `@nativescript/core`) and no `blueprintPlugin` (Blueprint is GTK-only).
+// of `@nativescript/core`). `blueprintPlugin` IS here: a bare `.blp` import
+// still compiles to GtkBuilder XML that nothing on this target reads, but
+// `./x.blp?shared-tree` projects the same file into the node shape
+// `@gjsify/adwaita-nativescript`'s `build` consumes.
 import { aliasPlugin } from '../plugins/alias.js';
+import blueprintPlugin from '@gjsify/vite-plugin-blueprint';
 import { deepkitPlugin } from '@gjsify/rolldown-plugin-deepkit';
 import { ALIASES_NODE_FOR_NATIVESCRIPT, GI_RENDERERS, getDerivedAliasesSync } from '@gjsify/resolve-npm';
 import { globToEntryPoints } from '../utils/entry-points.js';
@@ -146,7 +150,15 @@ export const setupForNativescript = async (input) => {
         // alias routing so a platform fork of a portable module is honored.
         platformResolvePlugin({ suffixes: nativescriptSuffixChain(platform) }),
         aliasPlugin({ entries: aliasEntries }),
-        // NO blueprintPlugin — Blueprint is a GTK-specific UI DSL
+        // Blueprint: `./x.blp?shared-tree` is how ONE authored template reaches this
+        // target. The comment this replaced read "NO blueprintPlugin — Blueprint is a
+        // GTK-specific UI DSL", and that was true of the only exit the plugin had: a
+        // GtkBuilder-XML string, which no NativeScript runtime can load. It is the
+        // NOTATION that was never GTK-specific — ADR 0053 clause 1 made `.blp` a second
+        // READER of the shared node shape, and the projection is what this target
+        // consumes. A `.blp` whose projection loses anything is refused at build time
+        // rather than rendered partially; see `SHARED_TREE_QUERY` in the plugin.
+        blueprintPlugin(),
         // NO cssAsStringPlugin — NS ships its own CSS pipeline via
         // @nativescript/core; .css imports are handled by the consuming
         // @nativescript/webpack or @nativescript/vite build

package/lib/index.d.ts

@@ -22,7 +22,7 @@ export { unresolvedWorkspaceImportPlugin, classifyImport, isWorkspaceSpecifier,
 export type { WorkspaceImportGuardOptions, WorkspaceImportGuardTarget, ImportVerdict, ClassifyImportInput, UnresolvedWorkspaceImportDetails, } from './plugins/unresolved-workspace-import.js';
 export { napiNodeAddonPlugin, resolveAddonPath, nearestPackageRoot, classifySpecifier, directNodeShim, nodeGypBuildShim, bindingsShim, napiRsShim, ADDON_FILTER_RE, isNapiRsPackageJson, isNapiRsSibling, isGjsifyNativeBridge, detectNapiRsEntry, hostNapiRsTriple, AddonNotBuiltError, } from './plugins/napi-node-addon.js';
 export type { NapiNodeAddonPluginOptions, AddonPackageJson } from './plugins/napi-node-addon.js';
-export { platformResolvePlugin, nativescriptSuffixChain, desktopSuffixChain, desktopOsSuffix, DESKTOP_OS_SUFFIXES, DESKTOP_REFUSED_SUFFIXES, PlatformVariantExternalError, detectNativescriptPlatform, nativescriptPlatformDefines, } from './plugins/platform-resolve.js';
+export { platformResolvePlugin, nativescriptSuffixChain, desktopSuffixChain, browserSuffixChain, desktopOsSuffix, DESKTOP_OS_SUFFIXES, DESKTOP_REFUSED_SUFFIXES, BROWSER_REFUSED_SUFFIXES, PlatformVariantExternalError, detectNativescriptPlatform, nativescriptPlatformDefines, } from './plugins/platform-resolve.js';
 export type { PlatformResolvePluginOptions, NativescriptPlatform } from './plugins/platform-resolve.js';
 export { rnRouteManifestPlugin, renderRouteManifest, walkRoutes, RouteManifestError, RN_ROUTES_MODULE_ID, MAX_ROUTE_DEPTH, } from './plugins/rn-route-manifest.js';
 export type { RnRouteManifestOptions, FoundRoute } from './plugins/rn-route-manifest.js';

package/lib/index.js

@@ -14,7 +14,7 @@ export { gjsImportsEmptyPlugin } from './plugins/gjs-imports-empty.js';
 export { externalsPlugin } from './plugins/externals.js';
 export { unresolvedWorkspaceImportPlugin, classifyImport, isWorkspaceSpecifier, formatUnresolvedWorkspaceImport, buildReverseAliasIndex, UnresolvedWorkspaceImportError, } from './plugins/unresolved-workspace-import.js';
 export { napiNodeAddonPlugin, resolveAddonPath, nearestPackageRoot, classifySpecifier, directNodeShim, nodeGypBuildShim, bindingsShim, napiRsShim, ADDON_FILTER_RE, isNapiRsPackageJson, isNapiRsSibling, isGjsifyNativeBridge, detectNapiRsEntry, hostNapiRsTriple, AddonNotBuiltError, } from './plugins/napi-node-addon.js';
-export { platformResolvePlugin, nativescriptSuffixChain, desktopSuffixChain, desktopOsSuffix, DESKTOP_OS_SUFFIXES, DESKTOP_REFUSED_SUFFIXES, PlatformVariantExternalError, detectNativescriptPlatform, nativescriptPlatformDefines, } from './plugins/platform-resolve.js';
+export { platformResolvePlugin, nativescriptSuffixChain, desktopSuffixChain, browserSuffixChain, desktopOsSuffix, DESKTOP_OS_SUFFIXES, DESKTOP_REFUSED_SUFFIXES, BROWSER_REFUSED_SUFFIXES, PlatformVariantExternalError, detectNativescriptPlatform, nativescriptPlatformDefines, } from './plugins/platform-resolve.js';
 export { rnRouteManifestPlugin, renderRouteManifest, walkRoutes, RouteManifestError, RN_ROUTES_MODULE_ID, MAX_ROUTE_DEPTH, } from './plugins/rn-route-manifest.js';
 export { reactNativeAliasPlugin, classifyReactNativeSpecifier, couldBeSurfaceSpecifier, loadLayer, FALLBACK_SURFACES, REACT_NATIVE_ALIAS_TARGET, REACT_NATIVE_SPECIFIER, ReactNativeDeepImportError, ReactNativeAliasTargetMissingError, SURFACE_MENTION, SURFACE_NAME_PREFIXES, } from './plugins/react-native-alias.js';
 export { reactNativeSupportGatePlugin, loadSupportTable, findSupportViolations, formatSupportViolations, formatOpaqueReference, formatUnreadableModule, SUPPORT_TABLE_SUBPATH, WATCHED_SPECIFIERS, watchedSpecifiers, ReactNativeUnsupportedImportError, SupportTableUnreadableError, } from './plugins/react-native-gate.js';

package/lib/plugins/platform-resolve.d.ts

@@ -39,6 +39,48 @@ export declare const DESKTOP_OS_SUFFIXES: Readonly<Record<string, string>>;
  * Without that, an author's fork is dead code with nothing anywhere saying so.
  */
 export declare const DESKTOP_REFUSED_SUFFIXES: readonly string[];
+/**
+ * Suffixes that must NEVER be a rung of the BROWSER chain — the mirror of
+ * {@link DESKTOP_REFUSED_SUFFIXES}, built by the same rule read from the other
+ * side: **refuse the other families' UMBRELLA rungs, not their per-target
+ * spellings.** The desktop list names `.web` (the whole browser chain) and
+ * `.native` (the phone family's umbrella) and deliberately leaves
+ * `.android`/`.ios`/`.visionos` out; from here the same rule names the GTK
+ * desktop family's two non-OS rungs plus that same phone umbrella.
+ *
+ * `.gtk` is the one a reader reaches for while chasing a missing widget, and it
+ * is the worst possible answer: `--app browser` redirects `gi://*` and `@girs/*`
+ * to an EMPTY module, so a `.gtk.tsx` reaching `Adw.ActionRow` does not fail to
+ * import — it gets `{}`, and `class X extends Adw.ActionRow` throws
+ * `Class extends value undefined` at load. That is measured, and the ADR 0034
+ * stage 9 e2e keeps exactly that row as its control.
+ *
+ * `.desktop` is named as well as `.gtk`, though only one of the two appears in
+ * this repository today: § 9 writes `.desktop` as the umbrella over `.gtk` and
+ * the three OS spellings, so refusing one and not the other is a gap, and a gap
+ * in a refusal list reads as a judgement that the omitted one is fine here.
+ *
+ * `.native` is the phone bridge — `NativeModules` exists in neither a browser
+ * nor a GTK host, which is why both lists carry it.
+ *
+ * NOT here, and each is a DECISION rather than an omission:
+ * - **the three OS spellings** (`linux`/`macos`/`windows`). They only ever
+ *   appear as rungs of the desktop chain, whose umbrella is already named — the
+ *   same reason `.android` is absent from the desktop list. Naming them would
+ *   put a warning line on every OS-forked module of a normal dual-target tree,
+ *   which is how a warning gets switched off.
+ * - **a refusal list for NativeScript at all.** That chain runs with
+ *   `siblingIndex` OFF under a byte-identical mandate, and with no listing to
+ *   filter them a refusal list costs two real `this.resolve` calls on every
+ *   relative import that has no variant — the majority, inside
+ *   `@nativescript/core` included. The desktop chain's own measurement (+14% on
+ *   a ~1400-module bundle from six failed resolves) is what says failed resolves
+ *   are not free. It is a cost with a measured-zero benefit on this tree: the
+ *   30 `.gtk.*`/`.native.*` pairs in `@gjsify/adwaita-react-native` all HIT the
+ *   NS chain at `.native`, and the refusal probe only runs when the chain found
+ *   nothing. Reopen it from a measurement of that tree with the index on.
+ */
+export declare const BROWSER_REFUSED_SUFFIXES: readonly string[];
 /**
  * The NativeScript chain: platform-specific first, then the platform-agnostic
  * `native` suffix. Without a known platform only `native` applies.
@@ -57,6 +99,37 @@ export declare function nativescriptSuffixChain(platform?: NativescriptPlatform)
  * guessing one.
  */
 export declare function desktopSuffixChain(os?: string): readonly string[];
+/**
+ * The BROWSER chain: `.web` → base. Exactly ONE rung, and the count is the
+ * decision.
+ *
+ * A desktop build knows three different things about itself and so gets three
+ * rungs: the toolkit (`.gtk`), the kernel (`.<os>`) and the target family
+ * (`.desktop`). A `--app browser` build knows ONE — it targets the DOM — and
+ * every candidate second rung was rejected for a stated reason rather than left
+ * out for tidiness:
+ *
+ * - **No engine rung** (`.firefox` / `.chromium`). The target compiles one
+ *   `esnext` bundle with no per-engine branch anywhere in it; a rung nobody can
+ *   fill is a resolution rule that can only ever surprise someone.
+ * - **No OS rung.** One browser bundle is served to every operating system, so
+ *   an OS rung would resolve against the BUILD HOST and bake it into a
+ *   platform-neutral artifact. That is the mistake `plugins/gi-runtime-paths.ts`
+ *   already documents for the GI prologue, committed here at resolution time
+ *   where the evidence is a file name and not a code path.
+ * - **No `.dom` synonym.** Two spellings for one concept is a priority order
+ *   someone has to memorise, and `.web` is what § 9 writes and what every
+ *   `.web.*` file in this repository already uses.
+ * - **No `.browser` umbrella.** `.desktop` earns its rung by sitting above four
+ *   spellings; above `.web` there is nothing for an umbrella to cover.
+ *
+ * Takes no parameter, unlike {@link desktopSuffixChain}: nothing about this
+ * chain depends on the host, which is the previous point restated from the API
+ * side. It is a function rather than a constant so that
+ * {@link PlatformResolvePluginOptions.suffixes} keeps its rule — a hand-written
+ * array is a second resolution order the tree does not state.
+ */
+export declare function browserSuffixChain(): readonly string[];
 /**
  * The desktop suffix for the BUILD HOST, or `undefined` for a host outside
  * ADR 0018's target set.
@@ -81,16 +154,19 @@ export declare function desktopOsSuffix(platform?: string): string | undefined;
 export interface PlatformResolvePluginOptions {
     /**
      * The suffix chain, most specific first. Build it with
-     * {@link nativescriptSuffixChain} or {@link desktopSuffixChain} — a
-     * hand-written array is a second resolution order the tree does not state.
+     * {@link nativescriptSuffixChain}, {@link desktopSuffixChain} or
+     * {@link browserSuffixChain} — a hand-written array is a second resolution
+     * order the tree does not state.
      */
     suffixes: readonly string[];
     /**
      * Suffixes deliberately NOT resolved, but whose presence on disk is worth
      * saying out loud: {@link DESKTOP_REFUSED_SUFFIXES} for the desktop chain,
-     * empty for NativeScript (where `.native` is a real rung). Probed only after
-     * the chain found nothing, so an empty list costs zero extra resolves and
-     * the NS path is byte-unchanged.
+     * {@link BROWSER_REFUSED_SUFFIXES} for the browser chain, empty for
+     * NativeScript — where `.native` is a real rung and the rest is a measured
+     * decision written out on `BROWSER_REFUSED_SUFFIXES`. Probed only after the
+     * chain found nothing, so an empty list costs zero extra resolves and the NS
+     * path is byte-unchanged.
      */
     refusedSuffixes?: readonly string[];
     /**
@@ -121,6 +197,20 @@ export interface PlatformResolvePluginOptions {
      * that chain is byte-identical behaviour — a filter that another plugin's
      * virtual `resolveId` could see past is not something to switch on there
      * without a measurement of that tree.
+     *
+     * ON WHEREVER THE CHAIN CARRIES A REFUSAL LIST, and that is not a preference.
+     * A refused suffix is probed on every miss, so a chain with refusals pays its
+     * probes on the MAJORITY of imports rather than the few that have a variant.
+     * Measured on `tests/e2e/vite-plugin-gjsify`'s fixture with the browser chain
+     * (one rung, three refusals) under `--max-old-space-size=4096`: index off is
+     * 1172 probes and `FATAL ERROR: Reached heap limit`; index on is 0 probes,
+     * 0.25 s and 191 MB. Under Vite each probe re-enters the whole plugin
+     * container, which is where the memory goes. Leaving the index off is
+     * therefore a choice only a chain with NO refusal list can afford.
+     *
+     * Kept fresh by {@link platformResolvePlugin}'s `watchChange` hook, so a
+     * long-lived host (a Vite dev server, `gjsify build --watch`) does not answer
+     * from a directory listing taken before the author added the variant.
      */
     siblingIndex?: boolean;
 }

package/lib/plugins/platform-resolve.js

@@ -1,16 +1,20 @@
-// Platform file resolution — ONE plugin, ONE resolution order, two chains.
+// Platform file resolution — ONE plugin, ONE resolution order, three chains.
 //
 // Lets a shared codebase fork a single module per target by file name. An
 // `import './foo'` (or `import './foo.js'`) resolves to the most specific
 // variant on disk, in the priority order the caller's chain declares:
 //
-//   NativeScript (`--app nativescript`)     GTK / desktop (`--app gjs|node`)
-//   ./foo.<android|ios|visionos>.<ext>      ./foo.gtk.<ext>
-//   ./foo.native.<ext>                      ./foo.<linux|macos|windows>.<ext>
-//   ./foo.<ext>                             ./foo.desktop.<ext>
-//                                           ./foo.<ext>
+//   NativeScript (`--app nativescript`)  GTK / desktop (`--app gjs|node`)
+//     ./foo.<android|ios|visionos>.<ext>   ./foo.gtk.<ext>
+//     ./foo.native.<ext>                   ./foo.<linux|macos|windows>.<ext>
+//     ./foo.<ext>                          ./foo.desktop.<ext>
+//                                          ./foo.<ext>
 //
-// TWO CHAINS, NOT TWO PLUGINS (ADR 0032 § 9). A second plugin would give the
+//   Browser (`--app browser`)
+//     ./foo.web.<ext>
+//     ./foo.<ext>
+//
+// THREE CHAINS, NOT THREE PLUGINS (ADR 0032 § 9). A second plugin would give the
 // tree two resolution orders that no single file states, and the order IS the
 // contract — `.gtk` before `.<os>` before `.desktop` is a decision, not an
 // implementation detail. So the chain is a PARAMETER and the builders below are
@@ -82,6 +86,48 @@ export const DESKTOP_OS_SUFFIXES = {
  * Without that, an author's fork is dead code with nothing anywhere saying so.
  */
 export const DESKTOP_REFUSED_SUFFIXES = ['native', 'web'];
+/**
+ * Suffixes that must NEVER be a rung of the BROWSER chain — the mirror of
+ * {@link DESKTOP_REFUSED_SUFFIXES}, built by the same rule read from the other
+ * side: **refuse the other families' UMBRELLA rungs, not their per-target
+ * spellings.** The desktop list names `.web` (the whole browser chain) and
+ * `.native` (the phone family's umbrella) and deliberately leaves
+ * `.android`/`.ios`/`.visionos` out; from here the same rule names the GTK
+ * desktop family's two non-OS rungs plus that same phone umbrella.
+ *
+ * `.gtk` is the one a reader reaches for while chasing a missing widget, and it
+ * is the worst possible answer: `--app browser` redirects `gi://*` and `@girs/*`
+ * to an EMPTY module, so a `.gtk.tsx` reaching `Adw.ActionRow` does not fail to
+ * import — it gets `{}`, and `class X extends Adw.ActionRow` throws
+ * `Class extends value undefined` at load. That is measured, and the ADR 0034
+ * stage 9 e2e keeps exactly that row as its control.
+ *
+ * `.desktop` is named as well as `.gtk`, though only one of the two appears in
+ * this repository today: § 9 writes `.desktop` as the umbrella over `.gtk` and
+ * the three OS spellings, so refusing one and not the other is a gap, and a gap
+ * in a refusal list reads as a judgement that the omitted one is fine here.
+ *
+ * `.native` is the phone bridge — `NativeModules` exists in neither a browser
+ * nor a GTK host, which is why both lists carry it.
+ *
+ * NOT here, and each is a DECISION rather than an omission:
+ * - **the three OS spellings** (`linux`/`macos`/`windows`). They only ever
+ *   appear as rungs of the desktop chain, whose umbrella is already named — the
+ *   same reason `.android` is absent from the desktop list. Naming them would
+ *   put a warning line on every OS-forked module of a normal dual-target tree,
+ *   which is how a warning gets switched off.
+ * - **a refusal list for NativeScript at all.** That chain runs with
+ *   `siblingIndex` OFF under a byte-identical mandate, and with no listing to
+ *   filter them a refusal list costs two real `this.resolve` calls on every
+ *   relative import that has no variant — the majority, inside
+ *   `@nativescript/core` included. The desktop chain's own measurement (+14% on
+ *   a ~1400-module bundle from six failed resolves) is what says failed resolves
+ *   are not free. It is a cost with a measured-zero benefit on this tree: the
+ *   30 `.gtk.*`/`.native.*` pairs in `@gjsify/adwaita-react-native` all HIT the
+ *   NS chain at `.native`, and the refusal probe only runs when the chain found
+ *   nothing. Reopen it from a measurement of that tree with the index on.
+ */
+export const BROWSER_REFUSED_SUFFIXES = ['gtk', 'desktop', 'native'];
 /**
  * The NativeScript chain: platform-specific first, then the platform-agnostic
  * `native` suffix. Without a known platform only `native` applies.
@@ -104,6 +150,39 @@ export function nativescriptSuffixChain(platform) {
 export function desktopSuffixChain(os) {
     return os ? ['gtk', os, 'desktop'] : ['gtk', 'desktop'];
 }
+/**
+ * The BROWSER chain: `.web` → base. Exactly ONE rung, and the count is the
+ * decision.
+ *
+ * A desktop build knows three different things about itself and so gets three
+ * rungs: the toolkit (`.gtk`), the kernel (`.<os>`) and the target family
+ * (`.desktop`). A `--app browser` build knows ONE — it targets the DOM — and
+ * every candidate second rung was rejected for a stated reason rather than left
+ * out for tidiness:
+ *
+ * - **No engine rung** (`.firefox` / `.chromium`). The target compiles one
+ *   `esnext` bundle with no per-engine branch anywhere in it; a rung nobody can
+ *   fill is a resolution rule that can only ever surprise someone.
+ * - **No OS rung.** One browser bundle is served to every operating system, so
+ *   an OS rung would resolve against the BUILD HOST and bake it into a
+ *   platform-neutral artifact. That is the mistake `plugins/gi-runtime-paths.ts`
+ *   already documents for the GI prologue, committed here at resolution time
+ *   where the evidence is a file name and not a code path.
+ * - **No `.dom` synonym.** Two spellings for one concept is a priority order
+ *   someone has to memorise, and `.web` is what § 9 writes and what every
+ *   `.web.*` file in this repository already uses.
+ * - **No `.browser` umbrella.** `.desktop` earns its rung by sitting above four
+ *   spellings; above `.web` there is nothing for an umbrella to cover.
+ *
+ * Takes no parameter, unlike {@link desktopSuffixChain}: nothing about this
+ * chain depends on the host, which is the previous point restated from the API
+ * side. It is a function rather than a constant so that
+ * {@link PlatformResolvePluginOptions.suffixes} keeps its rule — a hand-written
+ * array is a second resolution order the tree does not state.
+ */
+export function browserSuffixChain() {
+    return ['web'];
+}
 /**
  * The desktop suffix for the BUILD HOST, or `undefined` for a host outside
  * ADR 0018's target set.
@@ -155,13 +234,21 @@ export function platformResolvePlugin(options) {
         // EMPTY chain is one that was computed and came out empty — the shape a
         // mis-wired orchestrator has — and it would send every import to base
         // while looking installed.
-        throw new Error('gjsify platform resolve: the suffix chain is empty. Pass nativescriptSuffixChain(…) or ' +
-            'desktopSuffixChain(…), or omit the plugin.');
+        throw new Error('gjsify platform resolve: the suffix chain is empty. Pass nativescriptSuffixChain(…), ' +
+            'desktopSuffixChain(…) or browserSuffixChain(), or omit the plugin.');
     }
     const refused = options.refusedSuffixes ?? [];
     const useIndex = options.siblingIndex ?? false;
     // Per-directory listing cache, lowercased. `null` marks a directory that
     // could not be read, which means "no opinion" — the resolver decides.
+    //
+    // CACHED FOR THE PLUGIN INSTANCE'S LIFE, so it needs the `watchChange` hook
+    // below: in a one-shot build the process ends before a listing can go stale,
+    // but `gjsify build --watch` and a Vite dev server both keep one plugin
+    // instance across rebuilds. Without invalidation an author who ADDS
+    // `foo.web.ts` beside `foo.ts` while the watcher runs keeps being served
+    // `foo.ts` until restart — the filter would be answering from a directory
+    // that no longer exists in that shape.
     const listings = new Map();
     const listingFor = (dir) => {
         const cached = listings.get(dir);
@@ -196,6 +283,19 @@ export function platformResolvePlugin(options) {
     const warned = new Set();
     return {
         name: 'gjsify-platform-resolve',
+        // The sibling index's invalidation. Both hosts call this for every path
+        // the watcher reports (`create` / `update` / `delete`), which is exactly
+        // the event that can make a cached listing wrong — a NEW `foo.web.ts` is
+        // a `create` in the directory the filter already answered for.
+        //
+        // Only the CHANGED path's directory is dropped, not the whole map: the
+        // map is refilled lazily, so a blanket clear would re-`readdirSync` every
+        // directory the next rebuild touches for one unrelated save. `dirname`
+        // of a virtual or `\0`-prefixed id is a directory that was never cached,
+        // and deleting an absent key is a no-op — no guard needed for that.
+        watchChange(id) {
+            listings.delete(dirname(id));
+        },
         resolveId: {
             order: 'pre',
             async handler(source, importer, extraOptions) {
@@ -204,6 +304,23 @@ export function platformResolvePlugin(options) {
                     return null;
                 if (!source.startsWith('./') && !source.startsWith('../'))
                     return null;
+                // A QUERY NAMES A TRANSFORM OF ONE FILE, NOT A FILE TO FORK.
+                //
+                // `./x.blp?shared-tree`, `?raw`, `?url`: the plugin serving the query owns the
+                // resolution, and there is no second FILE for a platform chain to prefer —
+                // whatever the suffix is appended to, `./x.blp?shared-tree.native` is a
+                // specifier no convention gives a meaning to.
+                //
+                // Standing down is not merely tidier here, it is required. A probe that misses
+                // is normally free: `this.resolve('./x.native')` on a path that is not there
+                // returns null and the loop walks on. With a query in the specifier it is NOT
+                // — measured on `--app nativescript`, the missed probe surfaced as
+                // `UNLOADABLE_DEPENDENCY … No such file or directory (os error 2)` against the
+                // ORIGINAL import, and the chain never reached the plugin that would have
+                // resolved it. So the blind probe does not waste a lookup, it fails the build,
+                // and it does so pointing at a line that is correct.
+                if (source.includes('?'))
+                    return null;
                 const extMatch = KNOWN_EXT_RE.exec(source);
                 const origExt = extMatch ? extMatch[0] : '';
                 const base = origExt ? source.slice(0, -origExt.length) : source;
@@ -253,12 +370,16 @@ export function platformResolvePlugin(options) {
                     if (!probe || warned.has(probe.id))
                         continue;
                     warned.add(probe.id);
+                    // The remedy names THIS chain's own rungs. It used to end in
+                    // a hardcoded `.desktop`, which was true of the only chain
+                    // that had a refusal list and became advice to write a file
+                    // the browser chain refuses the moment a second one did.
+                    const ownVariants = suffixes.map((own) => `.${own}`).join(' / ');
                     this.warn(`gjsify platform resolve: "${base}.${suffix}" exists but is NOT a rung of this ` +
                         `target's chain (${suffixes.join(' → ')} → base), so ${importer} gets the base ` +
                         `file. ADR 0032 § 9: a .${suffix} variant is written for a runtime this build ` +
                         `is not, and reaching for it would hand this target code whose failure only ` +
-                        `shows up on screen. Move what applies here into a .${suffixes[0]} or ` +
-                        `.desktop variant.`);
+                        `shows up on screen. Move what applies here into ${ownVariants} or the base file.`);
                 }
                 return null;
             },

package/lib/utils/auto-globals.js

@@ -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
@@ -237,10 +301,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({
@@ -408,8 +478,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/runtime.js

@@ -11,7 +11,7 @@
 // Kept deliberately pure — no `gi://` / `@girs/*` imports, no side effects —
 // so it stays loadable on every host and so consumers can import it via the
 // `@gjsify/rolldown-plugin-gjsify/runtime` subpath without pulling the rest of
-// the plugin (which transitively loads blueprint-compiler, deepkit, etc.).
+// the plugin (which transitively loads the Blueprint parser, deepkit, etc.).
 /**
  * `true` when running under Bun.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/rolldown-plugin-gjsify",
-    "version": "0.51.1",
+    "version": "0.52.0",
     "description": "Rolldown / Rollup / Vite plugin orchestrator for GJS, Node, and Browser targets",
     "type": "module",
     "main": "lib/index.js",
@@ -60,11 +60,11 @@
     ],
     "license": "MIT",
     "dependencies": {
-        "@gjsify/console": "^0.51.1",
-        "@gjsify/resolve-npm": "^0.51.1",
-        "@gjsify/rolldown-plugin-deepkit": "^0.51.1",
-        "@gjsify/rolldown-plugin-pnp": "^0.51.1",
-        "@gjsify/vite-plugin-blueprint": "^0.51.1",
+        "@gjsify/console": "^0.52.0",
+        "@gjsify/resolve-npm": "^0.52.0",
+        "@gjsify/rolldown-plugin-deepkit": "^0.52.0",
+        "@gjsify/rolldown-plugin-pnp": "^0.52.0",
+        "@gjsify/vite-plugin-blueprint": "^0.52.0",
         "@rollup/pluginutils": "^5.4.0",
         "acorn": "^8.17.0",
         "acorn-typescript": "^1.4.13",
@@ -74,7 +74,7 @@
         "sass": "^1.101.0"
     },
     "peerDependencies": {
-        "@gjsify/lightningcss-native": "^0.51.1",
+        "@gjsify/lightningcss-native": "^0.52.0",
         "rolldown": "^1.1.4"
     },
     "peerDependenciesMeta": {
@@ -86,8 +86,8 @@
         }
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.51.1",
-        "@gjsify/unit": "^0.51.1",
+        "@gjsify/cli": "^0.52.0",
+        "@gjsify/unit": "^0.52.0",
         "@types/node": "^25.9.2",
         "rolldown": "^1.1.4",
         "typescript": "^6.0.3"