@gjsify/vite-plugin-blueprint 0.56.0 → 0.57.0

package/README.md

@@ -52,6 +52,11 @@ import windowXml from './window.blp';
 const builder = Gtk.Builder.new_from_string(windowXml, -1);
 ```
 
+`import Template from './window.blp?template'` is the exit for `registerClass` (ADR 0096 § 4): the same XML string on
+`--app gjs` / `--app node`, and under `--gi-renderer` on `--app browser` / `--app nativescript` the projected tree,
+checked against that target's renderer capability table (a refused construct fails the build naming file and line).
+It is typed as an opaque `BlueprintTemplate`. On those two targets without `--gi-renderer` it is refused, naming the flag.
+
 Add type declarations by including `"@gjsify/vite-plugin-blueprint/types"` in your `tsconfig.json` `compilerOptions.types`.
 
 ## License

package/lib/index.d.ts

@@ -10,6 +10,19 @@ export interface BlueprintPluginOptions {
      * A `.blp` under `node_modules` is never written, whatever this says — see `writeSidecar`.
      */
     sidecars?: boolean;
+    /**
+     * What `./x.blp?template` is on this build (ADR 0096 § 4). Unset, it is the module `./x.blp`
+     * is: the GtkBuilder XML, which is what `--app gjs` and `--app node` want. `renderer` makes
+     * it the projected tree checked against that renderer's capability table, as
+     * `?shared-tree&for=<renderer>` would be, so the import site names no renderer. `refusal`
+     * fails the build with that text: a target whose renderer is not composed has no value to
+     * give, and the XML string would be the one-specifier-two-meanings ADR 0070 § 1 forbids.
+     */
+    template?: {
+        renderer: string;
+    } | {
+        refusal: string;
+    };
 }
 export { BlueprintProjectionError, RendererRefusalError } from './projection-error.js';
 export type { RefusedUse } from './projection-error.js';

package/lib/index.js

@@ -72,6 +72,13 @@ const SHARED_TREE_PARAM = 'shared-tree';
  * import site for ADR 0070 § 1's reason — a target does not determine a renderer.
  */
 const RENDERER_PARAM = 'for';
+/**
+ * `./x.blp?template`: the exit a `registerClass` template comes through (ADR 0096 § 4). What it
+ * is depends on `BlueprintPluginOptions.template`, which the build target sets, because the same
+ * line has to mean "the template" on every target and not "the XML" on one and "the tree" on
+ * another.
+ */
+const TEMPLATE_PARAM = 'template';
 /** The specifier an import site writes: `./x.blp?shared-tree`. */
 export const SHARED_TREE_QUERY = `?${SHARED_TREE_PARAM}`;
 /**
@@ -92,10 +99,15 @@ function readId(id) {
     if (!file.endsWith('.blp'))
         return undefined;
     if (queryAt === -1)
-        return { file, sharedTree: false };
+        return { file, sharedTree: false, template: false };
     const params = new URLSearchParams(id.slice(queryAt + 1));
     const renderer = params.get(RENDERER_PARAM) ?? undefined;
-    return { file, sharedTree: params.has(SHARED_TREE_PARAM), ...(renderer === undefined ? {} : { renderer }) };
+    return {
+        file,
+        sharedTree: params.has(SHARED_TREE_PARAM),
+        template: params.has(TEMPLATE_PARAM),
+        ...(renderer === undefined ? {} : { renderer }),
+    };
 }
 /**
  * Write the sidecar beside its `.blp`, unless nothing would change.
@@ -177,7 +189,7 @@ async function refuseForRenderer(context, file, renderer, uses) {
         throw new RendererRefusalError(file, renderer, refused);
 }
 export default function blueprintPlugin(options = {}) {
-    const { minify = false, verbose = false, sidecars = true } = options;
+    const { minify = false, verbose = false, sidecars = true, template } = options;
     return {
         name: 'vite-plugin-blueprint',
         // The query has to be resolved by hand: the default resolver stats the specifier, and
@@ -187,7 +199,7 @@ export default function blueprintPlugin(options = {}) {
         // the XML and the tree rather than whichever was loaded first.
         async resolveId(source, importer) {
             const asked = readId(source);
-            if (asked === undefined || !asked.sharedTree)
+            if (asked === undefined || !(asked.sharedTree || asked.template))
                 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
@@ -210,9 +222,22 @@ export default function blueprintPlugin(options = {}) {
             // 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.
+            // `?template` is decided before anything is read, so a refusal names the flag and
+            // not a parse. It is then one of the two exits below, reusing their code rather than
+            // a copy: the tree with the `for=` check, or the XML module.
+            let { sharedTree, renderer } = asked;
+            if (asked.template) {
+                if (template !== undefined && 'refusal' in template) {
+                    throw new Error(`${asked.file}: \`?template\` has no value on this build. ${template.refusal}`);
+                }
+                if (template !== undefined) {
+                    sharedTree = true;
+                    renderer ??= template.renderer;
+                }
+            }
             const source = await readFile(asked.file, 'utf8');
             const ast = parseBlueprint(source, asked.file);
-            if (asked.sharedTree) {
+            if (sharedTree) {
                 // THE LOSSY EXIT REFUSES ITS LOSSES RATHER THAN SHIPPING THEM.
                 //
                 // `projectToSharedNode` declares what it dropped — ADR 0053 clause 1 calls the
@@ -229,8 +254,8 @@ export default function blueprintPlugin(options = {}) {
                 const { node, lost, uses } = projectToSharedNode(ast, { gtypeName });
                 if (lost.length > 0)
                     throw new BlueprintProjectionError(asked.file, lost);
-                if (asked.renderer !== undefined)
-                    await refuseForRenderer(this, asked.file, asked.renderer, uses);
+                if (renderer !== undefined)
+                    await refuseForRenderer(this, asked.file, renderer, uses);
                 if (verbose)
                     console.log(`Projected ${asked.file} (@gjsify/blueprint)`);
                 return `export default ${JSON.stringify(node)};`;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/vite-plugin-blueprint",
-    "version": "0.56.0",
+    "version": "0.57.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",
@@ -47,7 +47,7 @@
     ],
     "license": "MIT",
     "dependencies": {
-        "@gjsify/blueprint": "^0.56.0",
+        "@gjsify/blueprint": "^0.57.0",
         "minify-xml": "^4.5.2"
     },
     "peerDependencies": {
@@ -63,8 +63,8 @@
         }
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.56.0",
-        "@gjsify/unit": "^0.56.0",
+        "@gjsify/cli": "^0.57.0",
+        "@gjsify/unit": "^0.57.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3",
         "vite": "^8.1.3"

package/types/blueprint.d.ts

@@ -32,3 +32,16 @@ declare module '*.blp?shared-tree' {
     const tree: import('@gjsify/blueprint').SharedNode;
     export default tree;
 }
+
+/**
+ * The template a `registerClass` takes (ADR 0096 § 4): the XML string on `--app gjs`, the projected
+ * tree under `--gi-renderer`. Opaque, so application code cannot depend on which one it is.
+ */
+declare module '*.blp?template' {
+    const brand: unique symbol;
+    export interface BlueprintTemplate {
+        readonly [brand]: true;
+    }
+    const template: BlueprintTemplate;
+    export default template;
+}