@gjsify/vite-plugin-blueprint 0.51.0 → 0.52.0

package/README.md

@@ -1,6 +1,6 @@
 # @gjsify/vite-plugin-blueprint
 
-Vite/Rollup/Rolldown plugin that compiles GNOME Blueprint (`.blp`) UI files to GTK XML strings via `blueprint-compiler`. Import a `.blp` file and receive its compiled XML as a JavaScript string, ready for `Gtk.Builder`.
+Vite/Rollup/Rolldown plugin that compiles GNOME Blueprint (`.blp`) UI files to GtkBuilder XML strings. Import a `.blp` file and receive its compiled XML as a JavaScript string, ready for `Gtk.Builder`.
 
 Part of the [gjsify](https://github.com/gjsify/gjsify) project — Node.js and Web APIs for GJS (GNOME JavaScript).
 
@@ -14,10 +14,24 @@ npm install @gjsify/vite-plugin-blueprint
 yarn add @gjsify/vite-plugin-blueprint
 ```
 
-Requires `blueprint-compiler` on the system (e.g. `sudo dnf install blueprint-compiler`). It is found on
-`PATH`, and on Windows also in an MSYS2 install that is not on `PATH`; set `BLUEPRINT_COMPILER` to point at
-one the plugin does not find. When there is none, the build error names the install command for the host it
-ran on rather than leaving you to guess — so this README does not repeat one per platform.
+**No `blueprint-compiler` needed, and none is spawned.** The plugin parses and emits in process through
+[`@gjsify/blueprint`](https://github.com/gjsify/gjsify/tree/main/packages/infra/blueprint), which reads the
+introspection it needs out of pinned `@girs` packages rather than an installed typelib — so a build works
+on macOS and Windows, and in a cold bootstrap, where the GNOME tool is not installable in one line. See
+[ADR 0053](https://github.com/gjsify/gjsify/blob/main/docs/adr/0053-blueprint-parsed-in-repo.md).
+
+**What it does NOT accept.** The parser holds a documented subset of the language, and anything outside it
+is a build error naming the construct, the file and the line — never a silent pass-through, because output
+that is plausible and wrong is discovered in a shipped program. Today that means an `[internal-child]`
+bracket, a file-level `translation-domain`, an inline `menu` as a property value, a response flag, a
+multi-step lookup chain with no cast (`bind a.b.c`), a closure with no `as <Type>`, and a type from a
+namespace `@girs` publishes no vocabulary for (`Gio`, `Gdk` and `GObject` today) — for that last one the
+extern form is the way through: `Gio.ListStore` is refused and `$GListStore` is not, because it writes the
+GType name out and needs no vocabulary. Every refusal names the construct, the file, the line and one thing
+to do next, and says that `blueprint-compiler` is not involved, so a file it accepts can still stop here.
+The two error classes are `BlueprintSyntaxError` and `BlueprintEmitError` from `@gjsify/blueprint`, and both
+carry `file` and `line` as fields, so a tool wrapping this plugin does not have to read them out of a
+sentence. The package ships `corpus/refused/`, one named fixture per refused construct.
 
 ## Usage
 

package/lib/index.d.ts

@@ -3,5 +3,7 @@ export interface BlueprintPluginOptions {
     minify?: boolean;
     verbose?: boolean;
 }
-export { BlueprintCompileError, BlueprintCompilerNotFoundError, type BlueprintHost, currentBlueprintHost, formatMissingBlueprintCompiler, type ResolvedBlueprintCompiler, resolveBlueprintCompiler, } from './resolve-compiler.js';
+export { BlueprintProjectionError } from './projection-error.js';
+/** The specifier an import site writes: `./x.blp?shared-tree`. */
+export declare const SHARED_TREE_QUERY = "?shared-tree";
 export default function blueprintPlugin(options?: BlueprintPluginOptions): Plugin;

package/lib/index.js

@@ -1,49 +1,159 @@
-import { execa } from 'execa';
+import { readFile } from 'node:fs/promises';
+import { accessibilityElement, accessibilityValue, emitGtkBuilderXml, enumOrFlagsTypeOf, gtypeName, parseBlueprint, projectToSharedNode, resolveIdent, } from '@gjsify/blueprint';
 import minifyXML from 'minify-xml';
-import { BlueprintCompileError, BlueprintCompilerNotFoundError, resolveBlueprintCompiler, } from './resolve-compiler.js';
-export { BlueprintCompileError, BlueprintCompilerNotFoundError, currentBlueprintHost, formatMissingBlueprintCompiler, resolveBlueprintCompiler, } from './resolve-compiler.js';
+// Blueprint's OWN two error types are not re-exported here, and that is the shape rather than
+// an omission. What a parse or an emit throws is `@gjsify/blueprint`'s `BlueprintSyntaxError` /
+// `BlueprintEmitError`, raised by the package that DEFINES them and that every consumer of this
+// plugin already has as a declared dependency — `plugin.spec.ts` catches them from there. A
+// re-export would give the same two classes a second import path whose only job is to stay in
+// step with the first.
+//
+// `BlueprintProjectionError` below is the opposite case and belongs here for the same reason
+// those belong there: the refusal it carries is not a fact about the LANGUAGE. The parser reads
+// the file fine and the projection hands back a tree plus the list of what it cost; deciding
+// that such a tree may not reach a renderer is this plugin's decision, taken at the seam where
+// a build target is known. So it is declared where it is thrown.
+export { BlueprintProjectionError } from './projection-error.js';
+import { BlueprintProjectionError } from './projection-error.js';
+/**
+ * The five seams `@gjsify/blueprint`'s emitter reaches introspection through, answered by that
+ * same package out of the `@girs` vocabulary.
+ *
+ * ALL FIVE, and that is not tidiness. Every one is optional and every one NARROWS the output:
+ * without `resolveIdent` an enum property emits `vertical` where GtkBuilder is given `1`, without
+ * `gtypeName` a `Gio.ListStore` emits `GioListStore`, a class GtkBuilder resolves to nothing.
+ * `emitGtkBuilderXml` documents a fallback for each, so a dropped seam does not throw — it builds,
+ * and the widget is wrong at run time. That is the silent-wrong-output ADR 0053 clause 3 exists to
+ * refuse, and no corpus run can catch it: `check-blueprint-corpus.mjs` hands in its own five, so
+ * it would stay green over every tracked `.blp` while this file passed four.
+ *
+ * `Required<EmitOptions>` is what holds it, and it is a TYPE rather than a test because a test
+ * would need a `.blp` whose bytes move for each seam and there is no such file. Drop a key and
+ * `gjsify run check` fails on this line; change a seam's signature upstream and it fails here too.
+ */
+const SEAMS = Object.freeze({
+    accessibilityElement,
+    accessibilityValue,
+    enumOrFlagsTypeOf,
+    gtypeName,
+    resolveIdent,
+});
+/**
+ * The query that asks for ADR 0051's authored-tree node instead of GtkBuilder XML.
+ *
+ * WHY A SPECIFIER AND NOT A BUILD-TARGET MODE. The obvious wiring is an option — `emit: 'tree'`
+ * on the non-GTK app targets — and it is the wrong one, for a reason the whole point of sharing a
+ * template rests on: it would make `import Template from './x.blp'` a string on `--app gjs` and
+ * an object on `--app browser`. One source, two meanings, chosen by a build flag the file cannot
+ * see. A consumer would have no spelling for "give me the XML here" on a target whose default had
+ * been flipped, and the ambient `*.blp` declaration — which has exactly one shape per module
+ * pattern — could not describe either honestly. The knowledge of WHICH exit a module wants sits
+ * at the import site, so that is where it is written.
+ *
+ * Three properties fall out, and each is worth more than the shorter spelling:
+ *
+ *   · The GTK path cannot change. A bare `.blp` never reaches `projectToSharedNode` at all, so
+ *     "the XML exit did not move" is a statement about reachable code and not about a default
+ *     value someone could flip. ADR 0066 § The XML exit does not move made that a property to
+ *     keep checkable rather than assert; this keeps it checkable one layer out.
+ *   · The refusal below cannot break a build that did not ask. A `.blp` with losses keeps
+ *     compiling to XML exactly as it does today; only asking for its TREE fails.
+ *   · Every app target registers one plugin with no options. There is no target→mode table to
+ *     keep in step with the list of targets, which is the drift `app/nativescript.ts`'s
+ *     "NO blueprintPlugin" comment was one half of.
+ */
+const SHARED_TREE_PARAM = 'shared-tree';
+/** The specifier an import site writes: `./x.blp?shared-tree`. */
+export const SHARED_TREE_QUERY = `?${SHARED_TREE_PARAM}`;
+/**
+ * The `.blp` path a module id names, with the exit it asked for.
+ *
+ * A PARAMETER, not a suffix, and that distinction is the whole correctness of this plugin
+ * under Vite. This package is published as a *vite* plugin, and Vite appends its own segments
+ * to a module id on the way through: `?shared-tree&import` from import analysis, `&v=<hash>`
+ * from the dep optimizer, `&used` from the SSR transform. An `endsWith('?shared-tree')` test
+ * matches none of those — and then the `.blp` fallback below misses too, because the id no
+ * longer ends in `.blp` either. The plugin would DECLINE the module, silently, and raw
+ * Blueprint source would reach whatever loader runs next. Rolldown, which is what this repo
+ * builds with, appends nothing, so the repo's own builds never show it.
+ */
+function readId(id) {
+    const queryAt = id.indexOf('?');
+    const file = queryAt === -1 ? id : id.slice(0, queryAt);
+    if (!file.endsWith('.blp'))
+        return undefined;
+    if (queryAt === -1)
+        return { file, sharedTree: false };
+    return { file, sharedTree: new URLSearchParams(id.slice(queryAt + 1)).has(SHARED_TREE_PARAM) };
+}
 export default function blueprintPlugin(options = {}) {
     const { minify = false, verbose = false } = options;
-    // Cached only on SUCCESS, so the PATH walk costs one probe per plugin
-    // instance instead of one per `.blp`. A MISS is deliberately re-probed:
-    // installing the compiler and saving the file is how a watch session is
-    // meant to recover, and caching "absent" would make that need a restart.
-    let compiler = null;
     return {
         name: 'vite-plugin-blueprint',
+        // The query has to be resolved by hand: the default resolver stats the specifier, and
+        // no file is named `main-window.blp?shared-tree`. Resolving the path WITHOUT the query
+        // and putting it back is also what keeps the two exits separate modules — same file,
+        // two ids, two module records — so importing a template both ways in one bundle gets
+        // the XML and the tree rather than whichever was loaded first.
+        async resolveId(source, importer) {
+            const asked = readId(source);
+            if (asked === undefined || !asked.sharedTree)
+                return null;
+            const resolved = await this.resolve(asked.file, importer, { skipSelf: true });
+            // The WHOLE query goes back on, not just ours: anything the host added to the
+            // specifier is the host's, and dropping it here would resolve to a different
+            // module than the one it asked for.
+            return resolved === null ? null : `${resolved.id}${source.slice(source.indexOf('?'))}`;
+        },
         async load(id) {
-            if (id.endsWith('.blp')) {
-                compiler ??= resolveBlueprintCompiler();
-                if (!compiler) {
-                    // Names the `.blp` that wanted it, so the diagnostic points at
-                    // a file the reader recognises rather than at the plugin.
-                    throw new BlueprintCompilerNotFoundError(id);
-                }
-                const resolved = compiler;
-                try {
-                    // Compile .blp file and get XML output directly
-                    const { stdout } = await execa(resolved.file, [...resolved.prefixArgs, 'compile', id], {
-                        // Only ever an overlay (an MSYS2 PATH prepend); undefined
-                        // inherits the environment unchanged.
-                        env: resolved.env,
-                    });
-                    if (verbose)
-                        console.log(`Compiled ${id} (blueprint-compiler via ${resolved.source})`);
-                    let xmlContent = stdout;
-                    // Minify XML if option is enabled
-                    if (minify) {
-                        xmlContent = minifyXML(xmlContent);
-                        if (verbose)
-                            console.log(`Minified XML for ${id}`);
-                    }
-                    // Return the XML content as a string
-                    return `export default ${JSON.stringify(xmlContent)};`;
-                }
-                catch (error) {
-                    const detail = error instanceof Error ? error.stderr || error.message : String(error);
-                    throw new BlueprintCompileError(id, resolved.file, detail);
-                }
+            const asked = readId(id);
+            if (asked === undefined)
+                return;
+            // ADR 0053 clause 5: the in-repo parser is authoritative for the build and
+            // `blueprint-compiler` is the oracle it is measured against. There is deliberately
+            // NO fallback to the binary. A silent one would put back the dependency clause 7
+            // exists to remove, and it would hide any disagreement behind whichever of the two
+            // happened to be installed — the build's output would depend on the host.
+            //
+            // The subset is a real limit while it lasts. A `.blp` reaching a construct the
+            // parser does not hold fails the build rather than compiling, and the error names
+            // the construct, the file and the line: `BlueprintSyntaxError` before an AST
+            // exists, `BlueprintEmitError` after. That is clause 3's declared trade against
+            // output that looks plausible and means something else.
+            const source = await readFile(asked.file, 'utf8');
+            const ast = parseBlueprint(source, asked.file);
+            if (asked.sharedTree) {
+                // THE LOSSY EXIT REFUSES ITS LOSSES RATHER THAN SHIPPING THEM.
+                //
+                // `projectToSharedNode` declares what it dropped — ADR 0053 clause 1 calls the
+                // losses "named at the seam rather than discovered downstream" — and this is the
+                // seam that has to act on the naming. A renderer handed a tree with losses builds
+                // a SMALLER UI than the `.blp` describes and cannot tell: a `bind` that never
+                // updates, an `Adw.Breakpoint` whose setters never fire. The template would then
+                // be complete on GTK and quietly partial everywhere else, which is worse than not
+                // sharing it at all, because the GTK build keeps saying it works.
+                //
+                // So the build stops here, with the file, the line and the kind of every loss —
+                // a porting task a reader can open, not a warning scrolled past. `minify` does
+                // not apply: it is an XML setting and this exit emits none.
+                const { node, lost } = projectToSharedNode(ast, { gtypeName });
+                if (lost.length > 0)
+                    throw new BlueprintProjectionError(asked.file, lost);
+                if (verbose)
+                    console.log(`Projected ${asked.file} (@gjsify/blueprint)`);
+                return `export default ${JSON.stringify(node)};`;
+            }
+            let xmlContent = emitGtkBuilderXml(ast, SEAMS);
+            if (verbose)
+                console.log(`Compiled ${asked.file} (@gjsify/blueprint)`);
+            // Minify XML if option is enabled
+            if (minify) {
+                xmlContent = minifyXML(xmlContent);
+                if (verbose)
+                    console.log(`Minified XML for ${asked.file}`);
             }
+            // Return the XML content as a string
+            return `export default ${JSON.stringify(xmlContent)};`;
         },
     };
 }

package/lib/projection-error.d.ts

@@ -0,0 +1,23 @@
+import type { ProjectedLoss } from '@gjsify/blueprint';
+/**
+ * A `.blp` asked for as a shared tree whose projection would have dropped something.
+ *
+ * WHY THIS IS A REFUSAL AND NOT A WARNING. The projection is lossy by construction (ADR 0053
+ * clause 1) and it says what it dropped. A build that emitted the tree anyway would hand a
+ * renderer a smaller UI than the source describes, with nothing downstream able to tell: the
+ * GTK build of the same file stays complete, so the template reads as shared and working while
+ * one surface silently renders less. That failure is expensive exactly because it is invisible,
+ * and a warning in a build log is invisible in the same way.
+ *
+ * WHY IT CARRIES THE LOSSES AND NOT JUST A SENTENCE. `lost` is the porting task: each entry is
+ * a construct and the line it sits on, so a consumer — a vite config, a CI step, a codemod —
+ * can group or count them without re-parsing the file. The message spells the same thing for a
+ * human, one loss per line, because a build failure is read before it is caught.
+ */
+export declare class BlueprintProjectionError extends Error {
+    /** The `.blp` that was asked for, with no query attached. */
+    readonly file: string;
+    /** Every loss the projection declared, in the order it declared them. */
+    readonly lost: readonly ProjectedLoss[];
+    constructor(file: string, lost: readonly ProjectedLoss[]);
+}

package/lib/projection-error.js

@@ -0,0 +1,34 @@
+/**
+ * A `.blp` asked for as a shared tree whose projection would have dropped something.
+ *
+ * WHY THIS IS A REFUSAL AND NOT A WARNING. The projection is lossy by construction (ADR 0053
+ * clause 1) and it says what it dropped. A build that emitted the tree anyway would hand a
+ * renderer a smaller UI than the source describes, with nothing downstream able to tell: the
+ * GTK build of the same file stays complete, so the template reads as shared and working while
+ * one surface silently renders less. That failure is expensive exactly because it is invisible,
+ * and a warning in a build log is invisible in the same way.
+ *
+ * WHY IT CARRIES THE LOSSES AND NOT JUST A SENTENCE. `lost` is the porting task: each entry is
+ * a construct and the line it sits on, so a consumer — a vite config, a CI step, a codemod —
+ * can group or count them without re-parsing the file. The message spells the same thing for a
+ * human, one loss per line, because a build failure is read before it is caught.
+ */
+export class BlueprintProjectionError extends Error {
+    /** The `.blp` that was asked for, with no query attached. */
+    file;
+    /** Every loss the projection declared, in the order it declared them. */
+    lost;
+    constructor(file, lost) {
+        // One loss per line and the kind named before the place, because the kind decides
+        // whether this file can be shared at all and the line only says where to start.
+        const listed = lost.map((loss) => `  ${loss.kind} at ${file}:${loss.line}`).join('\n');
+        super(`${file} cannot be used as a shared tree: its projection drops ` +
+            `${lost.length} construct(s) the node shape has no spelling for.\n${listed}\n` +
+            'The GtkBuilder-XML exit of the same file is unaffected — import it without ' +
+            '`?shared-tree` to build it for GTK. To share it, replace the constructs above ' +
+            'with ones the shared node carries, or render this surface from its own tree.');
+        this.name = 'BlueprintProjectionError';
+        this.file = file;
+        this.lost = lost;
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@gjsify/vite-plugin-blueprint",
-    "version": "0.51.0",
-    "description": "Compile GNOME Blueprint .blp templates to XML strings via blueprint-compiler. Vite / Rollup / Rolldown compatible.",
+    "version": "0.52.0",
+    "description": "Compile GNOME Blueprint .blp templates to GtkBuilder-XML strings with the in-repo @gjsify/blueprint parser: no blueprint-compiler, no spawn. Vite / Rollup / Rolldown compatible.",
     "type": "module",
     "main": "lib/index.js",
     "module": "lib/index.js",
@@ -11,10 +11,6 @@
             "types": "./lib/index.d.ts",
             "default": "./lib/index.js"
         },
-        "./resolve": {
-            "types": "./lib/resolve-compiler.d.ts",
-            "default": "./lib/resolve-compiler.js"
-        },
         "./types": {
             "types": "./types/blueprint.d.ts"
         }
@@ -51,7 +47,7 @@
     ],
     "license": "MIT",
     "dependencies": {
-        "execa": "^9.6.1",
+        "@gjsify/blueprint": "^0.52.0",
         "minify-xml": "^4.5.2"
     },
     "peerDependencies": {
@@ -67,8 +63,8 @@
         }
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.51.0",
-        "@gjsify/unit": "^0.51.0",
+        "@gjsify/cli": "^0.52.0",
+        "@gjsify/unit": "^0.52.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3",
         "vite": "^8.1.3"

package/types/blueprint.d.ts

@@ -2,3 +2,20 @@ declare module '*.blp' {
     const content: string;
     export default content;
 }
+
+/**
+ * The same file asked for as ADR 0051's authored-tree node — what `adwaita-web`'s
+ * `mountSharedTree` and the NativeScript port's `build` consume.
+ *
+ * A SECOND MODULE PATTERN AND NOT A WIDER `*.blp`, because the two exits are two shapes and a
+ * module has one: declaring `.blp` as `string | SharedNode` would make every existing consumer
+ * narrow past a value it cannot receive. `@gjsify/vite-plugin-blueprint` § SHARED_TREE_QUERY
+ * says why the exit is chosen by the specifier rather than by the build target.
+ *
+ * `SharedNode` is assignable to `@gjsify/adwaita-core`'s `SharedTreeNode` — the renderers'
+ * parameter — which is the property that makes this import mountable without a cast.
+ */
+declare module '*.blp?shared-tree' {
+    const tree: import('@gjsify/blueprint').SharedNode;
+    export default tree;
+}

package/lib/resolve-compiler.d.ts

@@ -1,84 +0,0 @@
-/** A spawnable blueprint-compiler, plus how it was found (for `verbose`). */
-export interface ResolvedBlueprintCompiler {
-    /** The executable to spawn. */
-    file: string;
-    /** Arguments that must precede blueprint-compiler's own (e.g. the script path). */
-    prefixArgs: string[];
-    /** Environment overlay to spawn with, or undefined to inherit unchanged. */
-    env?: Record<string, string>;
-    source: 'env' | 'path' | 'msys2';
-}
-/**
- * The host facts this module decides on, taken as a PARAMETER rather than read
- * from ambient `process.*`.
- *
- * Every unit-test leg in this repo runs on Linux, so an ambient
- * `process.platform` puts the darwin and win32 branches — which are most of this
- * module and the only ones anybody gets wrong — out of reach of any test. This
- * is the purity `packages/infra/cli/src/utils/platform-check.ts` documents,
- * applied to the module whose entire job is a per-OS answer.
- */
-export interface BlueprintHost {
-    /** `process.platform` of the host being answered for. */
-    platform: NodeJS.Platform;
-    /** That host's environment. */
-    env: Record<string, string | undefined>;
-    /** Does this path exist? `existsSync` in production, a map in a test. */
-    exists: (path: string) => boolean;
-}
-/** The running process as a {@link BlueprintHost}. */
-export declare function currentBlueprintHost(): BlueprintHost;
-/**
- * Locate a usable blueprint-compiler, or null when there is none.
- *
- * Order: `BLUEPRINT_COMPILER` (an explicit answer always wins, and is the escape
- * hatch for an install none of the probes below know about) → `PATH` → an MSYS2
- * install on win32.
- *
- * A set-but-unusable override resolves to null rather than falling through to
- * the probes. Handing back a path that is not there sent its `ENOENT` into the
- * "the compiler EXISTS and refused the file" branch, which then blamed the
- * `.blp` for a typo in an environment variable; and quietly ignoring an explicit
- * instruction to run a second guess is not better. Null is what lets
- * {@link formatMissingBlueprintCompiler} say which of the two actually happened.
- */
-export declare function resolveBlueprintCompiler(host?: BlueprintHost): ResolvedBlueprintCompiler | null;
-/**
- * What to tell someone who has no blueprint-compiler.
- *
- * Names the install command for THIS platform rather than listing every one:
- * the reader is on one host and the other two lines are noise they have to
- * filter. The Linux arm is the exception that proves it — every Linux row of
- * `PM_PACKAGES` in `@gjsify/cli`'s `check-system-deps.ts` spells the package
- * identically, so splitting it per distro would be four lines carrying one word.
- *
- * `BLUEPRINT_COMPILER` is mentioned everywhere because it is the answer for any
- * install the probes miss — except when it is itself the problem, which gets its
- * own sentence: repeating "or set BLUEPRINT_COMPILER" at someone who just set it
- * is how a diagnostic loses their trust.
- */
-export declare function formatMissingBlueprintCompiler(host?: BlueprintHost): string;
-/**
- * No usable compiler on this host.
- *
- * Carries the whole user-facing sentence so the wording has exactly one home and
- * the plugin composes nothing: what this replaces was an `ExecaError` naming the
- * COMMAND, in the guest's own language, from inside a rolldown plugin stack
- * (#1098).
- */
-export declare class BlueprintCompilerNotFoundError extends Error {
-    readonly blueprintPath: string;
-    readonly name = "BlueprintCompilerNotFoundError";
-    constructor(blueprintPath: string, host?: BlueprintHost);
-}
-/**
- * The compiler exists and refused the file, so this is a blueprint syntax or
- * type error and its own stderr is the useful part — never an install hint the
- * reader has already satisfied.
- */
-export declare class BlueprintCompileError extends Error {
-    readonly blueprintPath: string;
-    readonly compilerFile: string;
-    readonly name = "BlueprintCompileError";
-    constructor(blueprintPath: string, compilerFile: string, detail: string);
-}

package/lib/resolve-compiler.js

@@ -1,219 +0,0 @@
-// Where is `blueprint-compiler`, and what do we say when it is nowhere?
-//
-// Split out of the plugin so it is answerable in a test without a compiler
-// installed, and because the answer is genuinely platform-shaped on Windows.
-//
-// The failure this replaces: the plugin called `execa('blueprint-compiler', …)`
-// and rethrew whatever came back, so a host without it got an ExecaError stack
-// naming the COMMAND THAT FAILED and nothing about what to install. Measured on
-// the win11-gjsify VM, that error was read as "blueprint-compiler is a GNOME
-// Python tool, so it is unavailable on Windows" — a conclusion that reached a
-// docs file and stopped anyone building a `.blp` showcase there for a day. It is
-// available; nothing said how to get it.
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-/**
- * `existsSync` throws rather than answering `false` when the argument is not a
- * usable path at all (an embedded NUL, for one) — and an unreadable or malformed
- * PATH entry is not an answer about the command we are looking for. Same catch,
- * and same reason, as `isOnPath()` in `@gjsify/cli`'s `check-system-deps.ts`.
- */
-function existsSafe(path) {
-    try {
-        return existsSync(path);
-    }
-    catch {
-        return false;
-    }
-}
-/** The running process as a {@link BlueprintHost}. */
-export function currentBlueprintHost() {
-    return { platform: process.platform, env: process.env, exists: existsSafe };
-}
-/**
- * MSYS2 install roots to probe on win32, in order.
- *
- * MSYS2 is the ONLY way to get blueprint-compiler onto Windows today, and not
- * for the reason the tool's Python-ness suggests: it is pure Python (PyPI ships
- * a `py3-none-any` wheel), but `blueprintcompiler/gir.py` reads TYPELIBS through
- * `GIRepository`, so it needs PyGObject — which publishes no Windows wheel, so
- * `pip install blueprint-compiler` dies building it from source. MSYS2 is where
- * Python, PyGObject and the typelibs arrive already fitted together.
- *
- * `C:\msys64` is the installer default; the `$USERPROFILE` entries cover the
- * extracted-archive install, which is what a host without admin rights gets;
- * `C:\tools\msys64` is Chocolatey's.
- */
-function msys2Roots(env) {
-    return [
-        env.MSYS2_ROOT,
-        'C:\\msys64',
-        env.USERPROFILE && join(env.USERPROFILE, 'msys64'),
-        env.USERPROFILE && join(env.USERPROFILE, 'Tools', 'msys64'),
-        'C:\\tools\\msys64',
-    ].filter((root) => typeof root === 'string' && root.length > 0);
-}
-/**
- * MSYS2 environments, most-preferred first. `ucrt64` is MSYS2's own default for
- * new installs and links the modern Universal CRT; the others are probed so an
- * existing install is not rejected for being older.
- */
-const MSYS2_ENVS = ['ucrt64', 'mingw64', 'clang64'];
-/** Executable suffixes to try for a bare command name. Windows needs them; POSIX does not. */
-function exeSuffixes(platform) {
-    return platform === 'win32' ? ['.exe', '.cmd', '.bat', ''] : [''];
-}
-/** First existing `<dir>/<cmd><suffix>`, or null. */
-function findOnPath(cmd, host) {
-    const pathVar = host.env.PATH;
-    if (!pathVar)
-        return null;
-    const sep = host.platform === 'win32' ? ';' : ':';
-    for (const dir of pathVar.split(sep)) {
-        if (!dir)
-            continue;
-        for (const suffix of exeSuffixes(host.platform)) {
-            const candidate = join(dir, cmd + suffix);
-            if (host.exists(candidate))
-                return candidate;
-        }
-    }
-    return null;
-}
-/**
- * Find an MSYS2-provided blueprint-compiler.
- *
- * MSYS2 installs it as a SHEBANG SCRIPT with no `.exe` beside it, which Windows
- * cannot execute — so this returns MSYS2's own `python.exe` with the script as
- * its first argument, rather than the script alone. `<env>/bin` is prepended to
- * PATH because the script imports PyGObject, which loads MSYS2's libglib and its
- * typelibs from there.
- *
- * Deliberately does NOT set `GI_TYPELIB_PATH` at the gjsify GTK runtime bundle:
- * those typelibs are gvsbuild's and name `glib-2.0-0.dll` in their
- * `shared_library` field while MSYS2 ships `libglib-2.0-0.dll`. Measured — it
- * fails with "Failed to load shared library", and the obvious repair (put both
- * on PATH) would load two GLib builds into one process, which is a worse problem
- * than the one it solves.
- */
-function findInMsys2(host) {
-    if (host.platform !== 'win32')
-        return null;
-    for (const root of msys2Roots(host.env)) {
-        for (const env of MSYS2_ENVS) {
-            const bin = join(root, env, 'bin');
-            const script = join(bin, 'blueprint-compiler');
-            const python = join(bin, 'python.exe');
-            if (!host.exists(script) || !host.exists(python))
-                continue;
-            return {
-                file: python,
-                prefixArgs: [script],
-                // `;` is a win32 fact, not a host fact — this branch only runs there.
-                env: { PATH: `${bin};${host.env.PATH ?? ''}` },
-                source: 'msys2',
-            };
-        }
-    }
-    return null;
-}
-/** Does this override name a location, as opposed to a bare command to look up? */
-function looksLikePath(override) {
-    return override.includes('/') || override.includes('\\');
-}
-/**
- * Locate a usable blueprint-compiler, or null when there is none.
- *
- * Order: `BLUEPRINT_COMPILER` (an explicit answer always wins, and is the escape
- * hatch for an install none of the probes below know about) → `PATH` → an MSYS2
- * install on win32.
- *
- * A set-but-unusable override resolves to null rather than falling through to
- * the probes. Handing back a path that is not there sent its `ENOENT` into the
- * "the compiler EXISTS and refused the file" branch, which then blamed the
- * `.blp` for a typo in an environment variable; and quietly ignoring an explicit
- * instruction to run a second guess is not better. Null is what lets
- * {@link formatMissingBlueprintCompiler} say which of the two actually happened.
- */
-export function resolveBlueprintCompiler(host = currentBlueprintHost()) {
-    const override = host.env.BLUEPRINT_COMPILER;
-    if (override) {
-        if (looksLikePath(override)) {
-            return host.exists(override) ? { file: override, prefixArgs: [], source: 'env' } : null;
-        }
-        // A bare command name is a legitimate override, and must still reach the
-        // child through the same PATH walk any other command name gets.
-        const onPath = findOnPath(override, host);
-        return onPath ? { file: onPath, prefixArgs: [], source: 'env' } : null;
-    }
-    const onPath = findOnPath('blueprint-compiler', host);
-    if (onPath) {
-        return { file: onPath, prefixArgs: [], source: 'path' };
-    }
-    return findInMsys2(host);
-}
-/**
- * What to tell someone who has no blueprint-compiler.
- *
- * Names the install command for THIS platform rather than listing every one:
- * the reader is on one host and the other two lines are noise they have to
- * filter. The Linux arm is the exception that proves it — every Linux row of
- * `PM_PACKAGES` in `@gjsify/cli`'s `check-system-deps.ts` spells the package
- * identically, so splitting it per distro would be four lines carrying one word.
- *
- * `BLUEPRINT_COMPILER` is mentioned everywhere because it is the answer for any
- * install the probes miss — except when it is itself the problem, which gets its
- * own sentence: repeating "or set BLUEPRINT_COMPILER" at someone who just set it
- * is how a diagnostic loses their trust.
- */
-export function formatMissingBlueprintCompiler(host = currentBlueprintHost()) {
-    const override = host.env.BLUEPRINT_COMPILER;
-    if (override) {
-        return (`BLUEPRINT_COMPILER is set to "${override}", which is not ${looksLikePath(override) ? 'a file that exists' : 'on PATH'}.\n` +
-            '  Point it at a blueprint-compiler executable, or unset it to search PATH\n' +
-            '  (and, on Windows, the usual MSYS2 install locations).');
-    }
-    const install = host.platform === 'win32'
-        ? 'MSYS2 packages it prebuilt (it needs PyGObject, which has no Windows wheel, so pip cannot):\n' +
-            '    pacman -S mingw-w64-ucrt-x86_64-blueprint-compiler mingw-w64-ucrt-x86_64-gtk4 mingw-w64-ucrt-x86_64-libadwaita\n' +
-            '  An MSYS2 install under C:\\msys64, %USERPROFILE%\\msys64, %USERPROFILE%\\Tools\\msys64 or\n' +
-            '  C:\\tools\\msys64 is found automatically — it does NOT need to be on PATH.'
-        : host.platform === 'darwin'
-            ? 'brew install blueprint-compiler'
-            : 'sudo dnf install blueprint-compiler   (apt, pacman, zypper and apk package it under the same name)';
-    return ('blueprint-compiler was not found — @gjsify/vite-plugin-blueprint needs it to\n' +
-        '  compile .blp templates to GtkBuilder XML.\n' +
-        `  ${install}\n` +
-        '  Or set BLUEPRINT_COMPILER to its full path.');
-}
-/**
- * No usable compiler on this host.
- *
- * Carries the whole user-facing sentence so the wording has exactly one home and
- * the plugin composes nothing: what this replaces was an `ExecaError` naming the
- * COMMAND, in the guest's own language, from inside a rolldown plugin stack
- * (#1098).
- */
-export class BlueprintCompilerNotFoundError extends Error {
-    blueprintPath;
-    name = 'BlueprintCompilerNotFoundError';
-    constructor(blueprintPath, host = currentBlueprintHost()) {
-        super(`${blueprintPath}: ${formatMissingBlueprintCompiler(host)}`);
-        this.blueprintPath = blueprintPath;
-    }
-}
-/**
- * The compiler exists and refused the file, so this is a blueprint syntax or
- * type error and its own stderr is the useful part — never an install hint the
- * reader has already satisfied.
- */
-export class BlueprintCompileError extends Error {
-    blueprintPath;
-    compilerFile;
-    name = 'BlueprintCompileError';
-    constructor(blueprintPath, compilerFile, detail) {
-        super(`${blueprintPath}: blueprint-compiler failed (${compilerFile})\n${detail}`);
-        this.blueprintPath = blueprintPath;
-        this.compilerFile = compilerFile;
-    }
-}