@gjsify/rolldown-plugin-vue 0.42.0

package/README.md

@@ -0,0 +1,156 @@
+# @gjsify/rolldown-plugin-vue
+
+A Rolldown (and Rollup/Vite-compatible) plugin that compiles **Vue 3 single-file components** during gjsify builds, for a `@vue/runtime-core` custom renderer — the GTK one in [`@gjsify/gtk-host`](../../framework/gtk-host).
+
+Part of the [gjsify](https://github.com/gjsify/gjsify) project — Node.js and Web APIs for GJS (GNOME JavaScript).
+
+## Why this exists
+
+`@gjsify/gtk-host/vue` — the adapter — was complete and tested before this package. But it was tested through `h(...)` calls, which is to say through the renderer calls an SFC template compiles *to*. Nothing in the repository compiled a `.vue` file, so the compile step was unmeasured, and its failure mode is silent in the direction that matters: without `compilerOptions.isCustomElement`, **every** GTK tag compiles to `resolveComponent("gtk-box")`. Vue's resolver misses, warns once per tag — and the warning is `__DEV__`-only, which the production defines this pipeline requires strip.
+
+Measured on one template, without the predicate: 7 of 7 tags became `_resolveComponent(…)` and **zero** element vnodes were emitted. With it: 0 `resolveComponent`, 6 `createElementVNode` plus the root `createElementBlock`.
+
+`@vue/compiler-sfc` is loaded on the first `.vue` module, so a build with no SFC in it never pays for it.
+
+## Installation
+
+```bash
+gjsify install @gjsify/rolldown-plugin-vue
+```
+
+## Usage
+
+Wire it through `package.json#gjsify`, no JS-form config file needed:
+
+```json
+{
+    "gjsify": {
+        "bundler": {
+            "plugins": [{ "name": "@gjsify/rolldown-plugin-vue" }]
+        }
+    }
+}
+```
+
+Or directly in a Rolldown / Vite config:
+
+```typescript
+import { vuePlugin } from '@gjsify/rolldown-plugin-vue';
+
+export default {
+    plugins: [vuePlugin()],
+};
+```
+
+### Options
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `isCustomElement` | `isGtkHostTag` | Which tags compile to an element vnode instead of a component lookup. |
+| `include` | `/\.vue$/` | Which modules to compile. A `g`/`y` flag is stripped: both make `RegExp.test` stateful, and this plugin tests three times per module — measured with `/\.vue$/g`, `resolveId` returned `null` for *every* `.vue` import and `load` alternated between compiling and declining. |
+| `runtimeModuleName` | `@vue/runtime-core` | Module the generated code imports Vue's runtime from. `vue` — the compiler's own default — drags `@vue/runtime-dom` and the DOM renderer into a bundle with no DOM. |
+
+### The default tag rule, and where its authority is
+
+`isGtkHostTag` accepts `gtk-`/`adw-` kebab **and** `Gtk`/`Adw` + a capital. Both spellings are required: `isCustomElement` is consulted for PascalCase tags too (measured — it was asked about `GtkLabel`, `GtkBox` and `GtkGLArea` as well as the kebab forms), and one `GlobalComponents` key answers both spellings, so a kebab-only predicate leaves `<GtkBox>` type-checking and then resolving as a missing component.
+
+It is a **prefix rule** on purpose. It decides "element vnode or component lookup", never whether the widget exists. An unknown tag is refused by name twice, and neither place is here:
+
+- at render time, `@gjsify/gtk-host`'s registry throws `unknown-tag`;
+- at type-check time, `GlobalComponents` + `strictTemplates` refuses it.
+
+Encoding the widget list in this plugin would be a third copy of a generated table, and the first one to drift. The rule does cover that table exactly: all 164 GType keys in `gtk-host/src/generated/props.ts` match `^(Gtk|Adw)[A-Z]`.
+
+## What it refuses, and what it ignores
+
+**`<style>` is refused with a named error.** GTK styling is a `Gtk.CssProvider` concern — there is no element a CSS rule could attach to, and `<style scoped>` compiles to an attribute selector GTK4 CSS does not have. Compiling the rest and saying nothing would build an app that renders unstyled with nothing anywhere to read about it. Load the CSS yourself with `Gtk.CssProvider.load_from_string()` plus `Gtk.StyleContext.add_provider_for_display()`, and put the selector on the widget with `cssClasses`.
+
+**`<script lang="jsx">` / `lang="tsx">` is refused with a named error.** The module id's extension is what selects rolldown's parser, and it is chosen before anything has read the file (see below), so it cannot depend on the block's `lang`. Write JSX in a `.tsx` file and compile it with [`@gjsify/rolldown-plugin-solid`](../rolldown-plugin-solid).
+
+**A split SFC is refused with a named error.** Measured: `<template src="./tpl.html"/>` compiled to `function __sfc_render__() { return null }`, and `<script src="./s.js">` to `const __sfc__ = {}` with the external module never imported — a component that renders blank or carries none of its logic, at exit 0. (`<script setup src>` never reaches this plugin: `@vue/compiler-sfc`'s own `parse()` rejects it.) So is a `<template lang>` other than `html`: there is no template preprocessor here, and measured, `lang="pug"` compiled to a render function **returning the pug source as a text node**.
+
+**Every DOM-only template feature is refused with a named error, and this is the largest refusal set.** `compileTemplate` runs on `@vue/compiler-dom` — `@vue/compiler-sfc` ships no other template compiler — so `DOMDirectiveTransforms` and `DOMNodeTransforms` are installed and all of these *compile*. Each then fails in a way that leaves a GTK app running:
+
+| written | emitted | how it fails |
+| --- | --- | --- |
+| `v-show` | `vShow` + `withDirectives` | `vShow` is absent from `@vue/runtime-core` |
+| `v-model` on an element | `vModelText` / `vModelCheckbox` / `vModelDynamic` | all three absent |
+| `@x.stop`, `@x.enter` | `withModifiers`, `withKeys` | both absent |
+| `<Transition>`, `<TransitionGroup>` (both spellings) | `Transition`, `TransitionGroup` | both absent |
+| `v-html`, `v-text` | an `innerHTML` / `textContent` prop | no GTK widget has it |
+| `class`, `:class`, `style`, `:style` | a `class` / `style` prop | no GTK widget has it; `cssClasses` is a string **array** |
+
+The absent imports are a rolldown **MISSING_EXPORT warning at exit 0**, and the app then calls `undefined` inside a GLib callback. The dead props are refused by `@gjsify/gtk-host` as `unknown-prop` at *render* time — also inside a GLib callback, where GJS prints `JS ERROR` and the process still exits 0. Neither is a build failure without this refusal.
+
+`v-model` is refused on an **element only**: measured, on a component it compiles to `modelValue` + `onUpdate:modelValue` and imports nothing DOM-shaped, so refusing it there would break legitimate Vue. `v-if`/`v-else`/`v-for`/`v-slot`/`v-once`/`v-cloak` and a plain `@signal` are untouched.
+
+**Out of scope, and not attempted:** `<style>` including `scoped`, HMR, asset-URL rewriting (`transformAssetUrls` is off), custom blocks, SSR, `?query` suffixes on a `.vue` import, and watch-mode dependency registration. Custom blocks are the one thing that is neither compiled nor refused — they carry no runtime semantics of their own, so nothing in the bundle reads them and nothing renders differently.
+
+## How a `.vue` id gets parsed
+
+Rolldown picks a parser from the id's extension, and `.vue` is not one it knows: hand it TypeScript on a `.vue` id and the build dies with `[PARSE_ERROR] Missing initializer in const declaration` pointing into the `.vue` file. Three mechanisms were measured on the same fixture:
+
+| mechanism | node engine | GJS engine |
+| --- | --- | --- |
+| `transform` returning `moduleType: 'ts'` | exit 0 | **exit 1** — `rolldown: unsupported moduleType 'ts'` |
+| `moduleTypes: { '.vue': 'ts' }` input option | exit 0 | not reachable — the CLI has no passthrough |
+| `resolveId` renaming to `App.vue.ts` + `load` | exit 0 | exit 0 |
+
+So this plugin renames. `resolveId` resolves `./App.vue` normally (`skipSelf`) and appends `.ts` to the absolute path; `load` strips the suffix, reads the real file and compiles it. The real path stays the id's prefix, so a diagnostic still names the file.
+
+`moduleType` is not an undocumented field — rolldown 1.1.4 ships it in `SourceDescription`, and it is the *designed* mechanism. It is unavailable here because `@gjsify/rolldown-native`'s `plugin_proxy.rs::parse_module_type` accepts `js`/`ecmascript`/`json`/`text` and rejects everything else, which makes it unusable on the primary target. That gap is recorded in `status/open-todos.md`; closing it is a prebuild-cycle change and this plugin does not depend on it.
+
+One suffix and not four is why `lang="jsx"`/`"tsx"` is refused. A `<script>` with no `lang` is therefore parsed as TypeScript — harmless except for the handful of JS/TS syntactic ambiguities, and `lang="ts"` is what a project using this type surface writes anyway.
+
+## TypeScript — both halves are required
+
+The compile step above is one half. The other is `vue-tsc`, and it has a trap that produces a green check which verified nothing.
+
+```json
+{
+    "compilerOptions": { "strict": true, "module": "NodeNext", "moduleResolution": "NodeNext" },
+    "vueCompilerOptions": { "strictTemplates": true },
+    "include": ["src/**/*.ts", "src/**/*.vue"]
+}
+```
+
+- **`strictTemplates: true` is load-bearing.** Measured on `vue-tsc@3.3.11` against the `vue-host-counter` showcase: with it, an unknown prop, an unknown tag, an unknown event, a wrong value type and a bad enum nick all fail. Without it, the unknown prop and the unknown *tag* are silently accepted while wrong value types still error — so a project without it sees type errors appear and concludes the surface is working.
+- **It must be set in the BASE of the `extends` chain.** Measured, four cells, all four: the base tsconfig's value wins and the child's is ignored outright, in *both* directions — a strict base stays strict under a child that sets `false`, and a lax base stays lax under a child that sets `true`. In a monorepo the shared base config therefore decides this for every package and a per-package override does nothing. `vue-tsc --showConfig` will not tell you either: measured, it prints `compilerOptions`, `files`, `include` and `exclude` and **not** `vueCompilerOptions`. So the config that sets it has to be the one with no `extends` above it — which is what `scripts/check-vue-program.mjs` asserts. This is the load-bearing warning in [`gtk-host/src/vue-components.ts`](../../framework/gtk-host/src/vue-components.ts).
+- **`src/**/*.vue` must be in `include` explicitly, for the SFCs nothing imports.** A tsconfig whose `include` lists only `.ts` globs makes `vue-tsc` check **zero** *standalone* SFCs and exit 0. Measured, the limit of that: an SFC a root `.ts` imports is pulled into the program and fully type-checked either way, so the glob is what covers a component that is not wired up yet.
+- **`vue-tsc --noEmit` on its own is an exit code and nothing else.** `scripts/check-vue-program.mjs` is what makes it a check: it runs the package's own `vue-tsc` with `--listFiles`, requires every `.vue` on disk to be in the program, and requires the config to carry `strictTemplates` with no `extends` above it. All three are A/B-proven able to fail; a bare `vue-tsc --noEmit` stays green through each.
+- The `GlobalComponents` augmentation only applies to a program that loads it, so the project needs `import '@gjsify/gtk-host/vue-components';` somewhere — best in a `.d.ts`, since the module carries no runtime value.
+
+## The build recipe
+
+`@vue/runtime-core` is DOM-free in fact, but `--globals auto` is a static scan and injects a polyfill per identifier it sees in a dev-only branch. Four defines are required, or the bundle grows `gi://Gdk`, `GdkPixbuf`, `Pango` and `PangoCairo`:
+
+```
+--define '__VUE_OPTIONS_API__=false'
+--define '__VUE_PROD_DEVTOOLS__=false'
+--define '__VUE_PROD_HYDRATION_MISMATCH_DETAILS__=false'
+--define 'process.env.NODE_ENV="production"'
+```
+
+`showcases/gtk/vue-host-counter` asserts `globalThis.document` is `undefined` on every launch, so losing the recipe fails the showcase rather than silently growing four typelib dependencies. The full measurement, including the one import the recipe cannot save (`Suspense`), is in [`gtk-host`'s README](../../framework/gtk-host/README.md).
+
+## Determinism
+
+The plugin pins the two `@vue/compiler-sfc` options whose defaults are `__DEV__`, i.e. the *bundler's* `process.env.NODE_ENV`, which no gjsify build sets: `comments: false` (measured, the same SFC emitted 4 `createCommentVNode` calls with NODE_ENV unset and 0 with `NODE_ENV=production`) and `hoistStatic: false`, which the adapter prescribes.
+
+**`comments: false` has to be set TWICE, and pinning it only at parse time made the plugin non-deterministic within one process.** `parse()` LRU-caches the descriptor and `compileTemplate` marks the ast `transformed`, so the second compile of the same file takes `resolveTemplateAST`, which re-parses `inAST.source` using `compilerOptions` as the *parse* options. Measured on one fixture in one process: pass 1 emitted 0 `createCommentVNode` calls, pass 2 emitted 1, and the two modules differed byte-for-byte. So it is pinned in `templateParseOptions` **and** in `compilerOptions`, and a test compiles one fixture twice and asserts byte equality.
+
+`transformHoist: null` used to sit beside `hoistStatic: false` with a comment calling it load-bearing. It was dead: `@vue/compiler-dom`'s `compile()` spreads its own `transformHoist: stringifyStatic` *after* the caller's options, so the `null` never reached `baseCompile`. Measured with `hoistStatic: true`, `null` and `undefined` produced byte-identical output with 1 `createStaticVNode(` each; only `hoistStatic: false` suppresses it. The option is gone and `hoistStatic: false` keeps its two tests.
+
+One residual remains and has no option behind it: the generated code's patch-flag annotations (`8 /* PROPS */` vs `8`) and the `v-if` placeholder's debug text follow `__DEV__`. Neither changes a call or an argument that runs, and minification removes them.
+
+## Source maps
+
+`load` hands rolldown one map over the whole `.vue` file. Both halves of an SFC come with their own map and both already resolve to the *whole* file — measured, `sourcesContent[0]` is the SFC source in both, and the template map's source lines already count from the top of the file rather than from the template block — so only the generated side has to be fixed up, which is where the two halves landed in the joined module.
+
+The two maps are decoded and re-encoded rather than spliced: the generated column resets per line, but the source index, source line, source column and name index are deltas carried across the entire map, so concatenating two `mappings` strings reads the second half's first segment relative to the first half's last and puts every remaining mapping somewhere else in the file. Tests resolve a position through the merged map (line **and** column) instead of asserting the `mappings` string, which would only pin the encoder against itself.
+
+Note that gjsify's own build presets set `output.sourcemap: false` *after* spreading the caller's output options, so under `gjsify build --app <target>` the map is not written; it reaches a consumer through a plain Rolldown/Vite config.
+
+## License
+
+MIT

package/lib/index.d.ts

@@ -0,0 +1,72 @@
+import type { Plugin } from 'rolldown';
+import { type CombinedSourceMap } from './source-map.js';
+export interface VuePluginOptions {
+    /**
+     * Which tags compile to an ELEMENT vnode instead of a component lookup.
+     *
+     * Defaults to {@link isGtkHostTag}. Widen it for a project that registers
+     * widgets under another prefix; narrow it and a GTK tag silently becomes a
+     * component lookup that resolves to nothing.
+     */
+    isCustomElement?: (tag: string) => boolean;
+    /** Which modules to compile. Defaults to `.vue`. */
+    include?: RegExp;
+    /**
+     * Module the generated code imports Vue's runtime from.
+     *
+     * Defaults to `@vue/runtime-core`, which is what the gjsify adapter builds on.
+     * `vue` — the compiler's own default — pulls `@vue/runtime-dom` and the DOM
+     * renderer into a bundle that has no DOM.
+     */
+    runtimeModuleName?: string;
+}
+/**
+ * The default tag rule: `gtk-`/`adw-` kebab, or `Gtk`/`Adw` + a capital.
+ *
+ * A PREFIX RULE, deliberately, and its authority lies elsewhere — this predicate
+ * only decides "element vnode or component lookup", never whether the widget
+ * exists. An unknown tag is refused BY NAME twice: `@gjsify/gtk-host`'s registry
+ * throws `unknown-tag` at render time, and `GlobalComponents` + `strictTemplates`
+ * refuses it at type-check. Encoding the widget list here would be a third copy of
+ * a generated table, and the first one to drift.
+ *
+ * It covers that table exactly: all 164 GType keys in
+ * `gtk-host/src/generated/props.ts` match `^(Gtk|Adw)[A-Z]`, so every kebab tag
+ * derived from them matches `^(gtk|adw)-`.
+ */
+export declare const isGtkHostTag: (tag: string) => boolean;
+/** The emitted module and one map for it, over the whole `.vue` file. */
+export interface CompiledSfc {
+    code: string;
+    /** `null` only when neither half produced a map — never a stand-in for "unmapped". */
+    map: CombinedSourceMap | null;
+}
+/**
+ * Compile one SFC's source to a component module.
+ *
+ * Split out of the hooks so the whole compile is reachable without a bundler —
+ * which is what makes it testable at all.
+ */
+export declare function compileSfc(source: string, filename: string, options: {
+    isCustomElement: (tag: string) => boolean;
+    runtimeModuleName: string;
+    /**
+     * Where a NAMED-but-not-fatal finding goes — a custom block, today.
+     *
+     * A custom block carries no runtime semantics of its own, so refusing one
+     * would break a `<docs>` block that harms nothing; dropping it in silence is
+     * the other half of the same mistake. It gets said out loud instead.
+     */
+    onWarn?: (message: string) => void;
+}): Promise<CompiledSfc>;
+/**
+ * Compile Vue SFCs to a component module for a gjsify custom renderer.
+ *
+ * Wire it through `package.json#gjsify` so no JS-form config file is needed:
+ *
+ * ```json
+ * "gjsify": { "bundler": { "plugins": [{ "name": "@gjsify/rolldown-plugin-vue" }] } }
+ * ```
+ */
+export declare function vuePlugin(options?: VuePluginOptions): Plugin;
+export default vuePlugin;

package/lib/index.js

@@ -0,0 +1,540 @@
+// Vue single-file components for Rolldown — the compile step a GTK/GJS Vue app
+// needs, and the half that did not exist while the adapter did.
+//
+// `@gjsify/gtk-host/vue` is a `@vue/runtime-core` custom renderer, and it was
+// exercised through the renderer calls an SFC template compiles TO, never through
+// `@vue/compiler-sfc`. Nothing in the repository compiled a `.vue` file.
+//
+// ONE DECISION SHAPES THE WHOLE FILE, and it is not the obvious one. Rolldown picks
+// a parser from the id's EXTENSION, and `.vue` is not one it knows: hand it
+// TypeScript on a `.vue` id and the build dies with `[PARSE_ERROR] Missing
+// initializer in const declaration` pointing INTO the `.vue` file. The designed fix
+// is `moduleType` on a transform result — real, documented API in rolldown 1.1.4's
+// `SourceDescription` — and it is unusable here: `@gjsify/rolldown-native`'s
+// `plugin_proxy.rs::parse_module_type` accepts js/ecmascript/json/text and rejects
+// the rest, so `moduleType: 'ts'` builds under Node and fails under GJS, the primary
+// target. So this plugin renames the module id in `resolveId` and compiles in
+// `load`, which is the only one of the three candidates measured working on BOTH
+// engines. The table of what each did is in the README; the core gap is recorded in
+// `status/open-todos.md`.
+//
+// Everything else worth knowing is at its call site, because each one is a way this
+// compiles green and renders wrong.
+import { readFile } from 'node:fs/promises';
+import { combineSourceMaps } from './source-map.js';
+/** The component object every emitted module builds and exports. */
+const SFC_BINDING = '__sfc__';
+/** The render function, renamed out of the way of a user's own `render`. */
+const RENDER_BINDING = '__sfc_render__';
+/**
+ * Appended to the resolved `.vue` path so rolldown's extension-based parser
+ * selection reaches TypeScript. Fact 5 above.
+ *
+ * Named rather than a bare `.ts` so no real file can collide with it: a project
+ * that genuinely has an `App.vue.ts` on disk would otherwise see this plugin claim
+ * its `load` and compile `App.vue` in its place.
+ *
+ * THE `.ts` TAIL IS LOAD-BEARING FOR A SECOND REASON, and it is not rolldown's.
+ * `@gjsify/rolldown-plugin-deepkit` filters on `/\.(m|c)?tsx?$/`, so this id lands
+ * inside it and Deepkit reflects an SFC's `<script setup>` — measured: an SFC
+ * carrying `typeOf<Reflected>()` emits its `__ΩReflected` table. Rename the tail to
+ * `.js` or `.mjs` and that filter stops matching, and reflection switches off for
+ * every `.vue` file in the project with no diagnostic anywhere — `typeOf()` with no
+ * argument throws `No type given` at runtime, from a build that exited 0.
+ *
+ * Written down because the coupling is invisible at both ends: nothing in the
+ * deepkit plugin knows this suffix exists, and a rename here looks like a cosmetic
+ * choice about a name only this file uses.
+ */
+const VIRTUAL_SUFFIX = '.gjsify-vue.ts';
+const DEFAULT_INCLUDE = /\.vue$/;
+const DEFAULT_RUNTIME_MODULE_NAME = '@vue/runtime-core';
+/**
+ * The caller's `include` without the two flags that make `RegExp.test` STATEFUL.
+ *
+ * `g` and `y` both maintain `lastIndex` across calls, and this plugin tests three times
+ * per module — the specifier, the resolved id, and the filename in `load`. Measured with
+ * `vuePlugin({ include: /\.vue$/g })`: `resolveId` returned `null` for EVERY `.vue`
+ * import (the specifier matched and advanced `lastIndex`, so the resolved id then did
+ * not), and `load` alternated between compiling and declining. Stripped rather than
+ * refused: neither flag can mean anything to a `test`, so there is no intent to honour.
+ */
+function stateless(include) {
+    const flags = include.flags.replace(/[gy]/g, '');
+    return flags === include.flags ? include : new RegExp(include.source, flags);
+}
+/**
+ * The default tag rule: `gtk-`/`adw-` kebab, or `Gtk`/`Adw` + a capital.
+ *
+ * A PREFIX RULE, deliberately, and its authority lies elsewhere — this predicate
+ * only decides "element vnode or component lookup", never whether the widget
+ * exists. An unknown tag is refused BY NAME twice: `@gjsify/gtk-host`'s registry
+ * throws `unknown-tag` at render time, and `GlobalComponents` + `strictTemplates`
+ * refuses it at type-check. Encoding the widget list here would be a third copy of
+ * a generated table, and the first one to drift.
+ *
+ * It covers that table exactly: all 164 GType keys in
+ * `gtk-host/src/generated/props.ts` match `^(Gtk|Adw)[A-Z]`, so every kebab tag
+ * derived from them matches `^(gtk|adw)-`.
+ */
+export const isGtkHostTag = (tag) => /^(gtk|adw)-/.test(tag) || /^(Gtk|Adw)[A-Z]/.test(tag);
+/**
+ * Loaded on first compile, not at import.
+ *
+ * Same contract as `@gjsify/rolldown-plugin-solid` and
+ * `@gjsify/rolldown-plugin-deepkit`: a build with no `.vue` in it never pays for
+ * `@vue/compiler-sfc` (which pulls in `@babel/parser`, `postcss` and
+ * `magic-string`), and under `--app gjs` the CLI bundles this plugin for GJS before
+ * importing it, so that whole tree has to load under GJS as well.
+ */
+let cached = null;
+function load() {
+    cached ??= import('@vue/compiler-sfc');
+    return cached;
+}
+/**
+ * FNV-1a over filename + source, hex.
+ *
+ * The SFC "id" is Vue's scope id: it keys `<style scoped>` attribute selectors and
+ * `v-bind()` CSS variables. Both are out of scope here, so all this value needs is
+ * to be stable and collision-free per module — and to be computed WITHOUT
+ * `node:crypto`, because this plugin runs inside a CLI that runs on GJS.
+ */
+function scopeId(filename, source) {
+    let hash = 0x811c9dc5;
+    const input = `${filename} ${source}`;
+    for (let i = 0; i < input.length; i++) {
+        hash ^= input.charCodeAt(i);
+        // The 32-bit FNV prime, multiplied through Math.imul so it stays an int32.
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, '0');
+}
+/**
+ * Refuse a `<script lang>` this plugin cannot place behind a `.ts` id.
+ *
+ * The suffix is chosen in `resolveId`, before anything has read the file, so it
+ * cannot depend on the block's `lang` — and a JSX dialect needs a `.tsx`/`.jsx` id
+ * to parse at all. Refusing by name beats emitting code rolldown will then fail to
+ * parse with a message about the generated line rather than about the `lang`.
+ */
+function assertSupportedLang(lang, filename) {
+    if (lang === undefined || lang === 'js' || lang === 'ts')
+        return;
+    throw new Error(`@gjsify/rolldown-plugin-vue: ${filename} declares <script lang="${lang}">, which this plugin does not ` +
+        `compile. Supported: no lang, "js", "ts". A JSX dialect inside an SFC script would need the module id ` +
+        `to end in .jsx/.tsx, which is decided before the file is read; write JSX in a .tsx file and compile it ` +
+        `with @gjsify/rolldown-plugin-solid instead.`);
+}
+/**
+ * Refuse a `<style>` block by name rather than dropping it.
+ *
+ * GTK styling is a `Gtk.CssProvider` concern: there is no element a CSS rule could
+ * attach to here, and `<style scoped>` compiles to an attribute selector GTK4 CSS
+ * does not even have. Compiling the rest and saying nothing is the exact failure
+ * shape this repository keeps eliminating — the app builds, runs, looks wrong, and
+ * nothing anywhere mentions the stylesheet.
+ */
+function refuseStyleBlocks(styles, id) {
+    if (styles.length === 0)
+        return;
+    const scoped = styles.filter((style) => style.scoped === true).length;
+    throw new Error(`@gjsify/rolldown-plugin-vue: ${id} has ${styles.length} <style> block(s)` +
+        `${scoped > 0 ? ` (${scoped} scoped)` : ''}, which this plugin does not compile. GTK styling goes ` +
+        `through a Gtk.CssProvider: load the CSS yourself with Gtk.CssProvider.load_from_string() plus ` +
+        `Gtk.StyleContext.add_provider_for_display(), and put the selector on the widget with cssClasses. ` +
+        `Dropping the block silently would build an app that renders unstyled with nothing to read about it.`);
+}
+/**
+ * Refuse a `<template src>` / `<script src>` by name rather than compiling half a
+ * component.
+ *
+ * Measured: `<template src="./tpl.html"/>` beside a `<script setup>` compiles to
+ * `function __sfc_render__() { return null }`, and `<script src="./s.js">` beside a
+ * template compiles to `const __sfc__ = {}` with the external module never imported.
+ * Either way the app builds, runs, and renders a blank or logic-less component with
+ * nothing anywhere to read about it. `<script setup src>` never reaches here —
+ * `parse()` itself rejects it ("cannot use the src attribute because its syntax will be
+ * ambiguous outside of the component"), which `compileSfc` reports as an invalid SFC.
+ */
+function refuseExternalBlocks(blocks, filename) {
+    for (const [kind, block] of blocks) {
+        if (block?.src === undefined)
+            continue;
+        throw new Error(`@gjsify/rolldown-plugin-vue: ${filename} has <${kind} src="${block.src}">, which this plugin does ` +
+            `not compile: it resolves no external block, so the ${kind} would be silently EMPTY — a component ` +
+            `that renders blank or carries none of its logic, at exit 0. Inline the ${kind} into the SFC.`);
+    }
+}
+/**
+ * Refuse a `<template lang>` this plugin does not run through a preprocessor.
+ *
+ * Nothing validated it before, and the failure is silent in the worst way: measured,
+ * `<template lang="pug">` compiles to a render function that RETURNS THE PUG SOURCE AS A
+ * TEXT NODE. The app builds and shows its own template markup.
+ */
+function assertSupportedTemplateLang(lang, filename) {
+    if (lang === undefined || lang === 'html')
+        return;
+    throw new Error(`@gjsify/rolldown-plugin-vue: ${filename} declares <template lang="${lang}">, which this plugin does not ` +
+        `compile — it runs no template preprocessor, and the block would be compiled as if it were HTML: ` +
+        `measured, a pug template became a render function returning the pug source as a text node. ` +
+        `Write the template as HTML.`);
+}
+/**
+ * `NodeTypes.ELEMENT` / `NodeTypes.ATTRIBUTE` / `NodeTypes.DIRECTIVE` and
+ * `ElementTypes.ELEMENT`, from `@vue/compiler-core`'s enums.
+ *
+ * Spelled as literals because `@vue/compiler-sfc` re-exports neither enum, and taking
+ * `@vue/compiler-core` as a second direct dependency for four integers would also put it
+ * in the tree this plugin loads lazily. Each one is load-bearing for a refusal below, so
+ * a renumbering upstream turns those specs RED rather than turning the refusals off.
+ */
+const NODE_ELEMENT = 1;
+const PROP_ATTRIBUTE = 6;
+const PROP_DIRECTIVE = 7;
+const TAG_PLAIN_ELEMENT = 0;
+/** How the `@vue/runtime-dom` half of a feature would have failed on GTK. */
+const MISSING_EXPORT = 'is a @vue/runtime-dom export, which @vue/runtime-core does not have: rolldown reports the missing import ' +
+    'as a WARNING at exit 0 and the app then calls `undefined` inside a GLib callback';
+const UNKNOWN_PROP = 'compiles to a DOM prop no GTK widget has, which @gjsify/gtk-host refuses as `unknown-prop` at RENDER time ' +
+    '— inside a GLib callback, where GJS prints `JS ERROR` and the process still exits 0';
+/**
+ * `v-<name>` → why it cannot compile here, and what to write instead.
+ *
+ * `plainElementsOnly` spares the legitimate use: measured, `v-model` on a COMPONENT
+ * compiles to `modelValue` + `onUpdate:modelValue` props and imports nothing DOM-shaped,
+ * while `v-model` on an element reaches for `vModelText`/`vModelCheckbox`/`vModelDynamic`.
+ */
+const DOM_ONLY_DIRECTIVES = [
+    {
+        name: 'show',
+        plainElementsOnly: false,
+        why: `\`vShow\` ${MISSING_EXPORT}. It toggles \`style.display\`, which GTK has no equivalent for: use ` +
+            `\`v-if\`, or bind the widget's own \`visible\` property.`,
+    },
+    {
+        name: 'model',
+        plainElementsOnly: true,
+        why: `\`vModelText\`/\`vModelCheckbox\`/\`vModelDynamic\` ${MISSING_EXPORT}. Bind the widget property and ` +
+            `write it back from the widget's own signal: \`<gtk-entry :text="name" @changed="…" />\`.`,
+    },
+    {
+        name: 'html',
+        plainElementsOnly: false,
+        why: `\`v-html\` ${UNKNOWN_PROP} (\`innerHTML\`). GTK parses no HTML — put the text in the widget's own ` +
+            `\`label\` property, or use Pango markup with \`useMarkup\`.`,
+    },
+    {
+        name: 'text',
+        plainElementsOnly: false,
+        why: `\`v-text\` ${UNKNOWN_PROP} (\`textContent\`). Write the text as a child — ` +
+            `\`<gtk-label>{{ text }}</gtk-label>\` — or bind the widget's \`label\` property.`,
+    },
+];
+/**
+ * DOM props whose NAME survives compilation but which no GTK widget has.
+ *
+ * `style` reaches this list as a `v-bind`, not as an attribute: compiler-dom's
+ * `transformStyle` rewrites `style="color: red"` into a bound style OBJECT before any
+ * directive transform runs, so the static and bound spellings are indistinguishable here
+ * — and both are refused. `class` stays a plain attribute.
+ */
+const DOM_ONLY_PROPS = new Map([
+    [
+        'class',
+        `\`class\` ${UNKNOWN_PROP}. The GTK property is \`cssClasses\`, a string ARRAY: ` +
+            `\`<gtk-box :css-classes="['card']" />\`.`,
+    ],
+    [
+        'style',
+        `\`style\` ${UNKNOWN_PROP}. GTK styling is a \`Gtk.CssProvider\` concern: load the CSS with ` +
+            `\`Gtk.CssProvider.load_from_string()\` plus \`Gtk.StyleContext.add_provider_for_display()\` and put ` +
+            `the selector on the widget with \`cssClasses\`.`,
+    ],
+]);
+/**
+ * `<Transition>`/`<TransitionGroup>` in both spellings compiler-dom recognises.
+ *
+ * Measured: each emits `import { Transition } from "@vue/runtime-core"`, and both names
+ * are ABSENT there — they live in `@vue/runtime-dom`, driven by CSS transition classes.
+ * `@gjsify/gtk-host`'s README records the same fact from the runtime side.
+ */
+const DOM_ONLY_TAGS = new Map([
+    ['Transition', 'Transition'],
+    ['transition', 'Transition'],
+    ['TransitionGroup', 'TransitionGroup'],
+    ['transition-group', 'TransitionGroup'],
+]);
+/**
+ * Refuse the template features that only mean something against a DOM, BY NAME.
+ *
+ * `compileTemplate` runs on `@vue/compiler-dom` — `@vue/compiler-sfc` ships no other
+ * template compiler — so `DOMDirectiveTransforms` and `DOMNodeTransforms` are installed
+ * and every feature below COMPILES. Each then fails in one of two ways, and neither stops
+ * the app: an import `@vue/runtime-core` does not export, or a DOM prop no GTK widget
+ * has. Both are spelled out in the messages above, because the point of refusing is that
+ * someone reads why.
+ *
+ * A `nodeTransform` and not four `directiveTransforms`: two of these are not directives
+ * at all (`transformStyle` keys off an attribute, `transformTransition` off the tag), and
+ * an event MODIFIER is a property of a `v-on` this plugin must otherwise keep working.
+ * One hook sees all of them on ENTRY, before `buildProps` runs on exit.
+ */
+function refuseDomOnlyTemplateFeatures(node, filename) {
+    // The compiler hands its own AST to a `nodeTransform` and `@vue/compiler-sfc` exports
+    // no types for it, so the shape is asserted here rather than imported.
+    const element = node;
+    if (element.type !== NODE_ELEMENT)
+        return;
+    const tag = element.tag ?? '<unknown>';
+    const builtIn = DOM_ONLY_TAGS.get(tag);
+    if (builtIn !== undefined) {
+        refuse(filename, `<${tag}>`, `\`${builtIn}\` ${MISSING_EXPORT}. It animates CSS transition classes; a GTK animation is ` +
+            `\`Adw.TimedAnimation\` or a widget's own transition property (\`Gtk.Stack.transitionType\`).`);
+    }
+    for (const prop of element.props ?? []) {
+        if (prop.type === PROP_ATTRIBUTE) {
+            const why = DOM_ONLY_PROPS.get(prop.name);
+            if (why !== undefined)
+                refuse(filename, `\`${prop.name}\` on <${tag}>`, why);
+            continue;
+        }
+        if (prop.type !== PROP_DIRECTIVE)
+            continue;
+        const directive = DOM_ONLY_DIRECTIVES.find((candidate) => candidate.name === prop.name);
+        if (directive !== undefined && (!directive.plainElementsOnly || element.tagType === TAG_PLAIN_ELEMENT)) {
+            refuse(filename, `\`v-${prop.name}\` on <${tag}>`, directive.why);
+        }
+        if (prop.name === 'bind' && prop.arg?.isStatic === true) {
+            const why = DOM_ONLY_PROPS.get(String(prop.arg.content));
+            if (why !== undefined)
+                refuse(filename, `\`:${String(prop.arg.content)}\` on <${tag}>`, why);
+        }
+        const modifiers = prop.name === 'on' ? (prop.modifiers ?? []) : [];
+        if (modifiers.length > 0) {
+            const spelling = modifiers.map((modifier) => `.${String(modifier.content)}`).join('');
+            refuse(filename, `\`@${String(prop.arg?.content ?? '')}${spelling}\` on <${tag}>`, `an event modifier compiles to \`withModifiers\`/\`withKeys\`, and both ${MISSING_EXPORT}. ` +
+                `They are DOM event plumbing (\`stopPropagation\`, \`event.key\`) — a GTK signal has neither. ` +
+                `Drop the modifier and do the check inside the handler.`);
+        }
+    }
+}
+function refuse(filename, what, why) {
+    throw new Error(`@gjsify/rolldown-plugin-vue: ${filename} uses ${what}, which this plugin does not compile. ${why}`);
+}
+/**
+ * `export function render` becomes `function __sfc_render__`, so the emitted module
+ * can hold a user's own `render` binding beside it.
+ *
+ * A string rewrite, like `@vitejs/plugin-vue`'s, because `compileTemplate` has no
+ * rename option — but ASSERTED, because a silent no-op here would leave a second
+ * `render` in the module (a redeclaration at best, a shadowed user binding at worst)
+ * and the failure would surface in the app rather than in the build.
+ */
+function renameRenderExport(code, id) {
+    const renamed = code.replace(/\nexport function render\(/, `\nfunction ${RENDER_BINDING}(`);
+    if (renamed === code) {
+        throw new Error(`@gjsify/rolldown-plugin-vue: could not find the generated \`export function render(\` in the ` +
+            `template output for ${id}. @vue/compiler-sfc changed its codegen shape; this plugin renames ` +
+            `that export so it cannot collide with a user's own \`render\`.`);
+    }
+    return renamed;
+}
+/** Every message an SFC/template compile can report, flattened for one throw. */
+function messagesOf(errors) {
+    return errors.map((error) => String(error.message ?? error)).join('\n  ');
+}
+/**
+ * Compile one SFC's source to a component module.
+ *
+ * Split out of the hooks so the whole compile is reachable without a bundler —
+ * which is what makes it testable at all.
+ */
+export async function compileSfc(source, filename, options) {
+    const { parse, compileScript, compileTemplate } = await load();
+    const { isCustomElement, runtimeModuleName } = options;
+    // BOTH options LOOK like codegen options and are really PARSER options, and
+    // setting them where they look like they belong is a silent no-op — a tag's kind
+    // (element vs component) and whether a comment survives are decided at parse
+    // time. `@vitejs/plugin-vue` hands `compileTemplate` the `ast` from a plain
+    // `parse()` and relies on Vite to have configured the parser; doing that here
+    // measured 2 of 2 tags back to `_resolveComponent` while
+    // `compilerOptions.isCustomElement` sat there set and ignored.
+    //
+    // That no-op also FAKED ITS OWN A/B: `compileTemplate` re-parses an ast that has
+    // already been transformed, so a loop compiling the SAME descriptor three times
+    // showed `comments: false` "working" on the second pass. Every measurement in
+    // this package is from a fresh process.
+    //
+    // `comments` is here for a second reason: it defaults to `__DEV__`, i.e. to the
+    // BUNDLER's `process.env.NODE_ENV`, which no build here sets. Measured, the same
+    // SFC emitted 4 `createCommentVNode` calls with NODE_ENV unset and 0 with
+    // NODE_ENV=production — a different bundle for an environment variable nothing
+    // declares. It has to be set in `compilerOptions` AS WELL, and pinning it here
+    // alone made the plugin non-deterministic WITHIN one process: `parse()` LRU-caches
+    // the descriptor, `compileTemplate` marks the ast `transformed`, and the next
+    // compile of the same file therefore takes `resolveTemplateAST`, which re-parses
+    // `inAST.source` using `compilerOptions` as the PARSE options. Measured on one
+    // fixture in one process: pass 1 emitted 0 `createCommentVNode` calls, pass 2
+    // emitted 1, and the two modules differed.
+    const { descriptor, errors } = parse(source, {
+        filename,
+        templateParseOptions: { isCustomElement, comments: false },
+    });
+    if (errors.length > 0) {
+        throw new Error(`@gjsify/rolldown-plugin-vue: ${filename} is not a valid SFC:\n  ${messagesOf(errors)}`);
+    }
+    refuseStyleBlocks(descriptor.styles, filename);
+    refuseExternalBlocks([
+        ['template', descriptor.template],
+        ['script', descriptor.script],
+    ], filename);
+    assertSupportedTemplateLang(descriptor.template?.lang ?? undefined, filename);
+    for (const block of descriptor.customBlocks) {
+        options.onWarn?.(`@gjsify/rolldown-plugin-vue: ${filename} carries a <${block.type}> block, which this plugin does ` +
+            `not compile. Nothing in the bundle will read it.`);
+    }
+    const hasScript = descriptor.script !== null || descriptor.scriptSetup !== null;
+    assertSupportedLang(descriptor.scriptSetup?.lang ?? descriptor.script?.lang ?? undefined, filename);
+    const compilerOptions = {
+        isCustomElement,
+        runtimeModuleName,
+        // The adapter's contract, and it prevents a real throw rather than merely
+        // honouring a prescription. `hoistStatic` (on by default) enables
+        // compiler-dom's `stringifyStatic`, which turns a large enough static
+        // subtree into `createStaticVNode("<html…>")` — and the adapter's
+        // `insertStaticContent` THROWS, because GTK parses no HTML. It reaches GTK
+        // tags too: MEASURED, 22 `<gtk-label title="t">x</gtk-label>` children
+        // stringified exactly like 22 `<div>`s. (A first measurement with 22
+        // self-closing, text-free labels did NOT stringify, and reading that as
+        // "custom elements are exempt" is the kind of near-miss this comment exists
+        // to stop.) `cloneNode` is the same class one step further out: a GObject
+        // does not clone.
+        hoistStatic: false,
+        // Not `transformHoist: null` beside it: compiler-dom's `compile()` spreads its
+        // own `transformHoist: stringifyStatic` AFTER the caller's options, so the null
+        // never reached `baseCompile`. Measured with `hoistStatic: true`, `null` and
+        // `undefined` emitted the same 1 `createStaticVNode(` and byte-identical output;
+        // `hoistStatic: false` is what actually suppresses it.
+        comments: false,
+        // The refusals this plugin owns, reached the only way a caller can reach them:
+        // compiler-dom appends `options.nodeTransforms` after its own, so this runs on
+        // entry to every element, before `buildProps` runs on exit.
+        nodeTransforms: [(node) => refuseDomOnlyTemplateFeatures(node, filename)],
+    };
+    const id = scopeId(filename, source);
+    // `genDefaultAs` turns `export default {…}` into a binding this module can then
+    // attach `render` to, and gives a script with no default export an empty
+    // component instead of a syntax error.
+    const script = hasScript
+        ? compileScript(descriptor, {
+            id,
+            genDefaultAs: SFC_BINDING,
+            // `templateOptions` IS how `runtimeModuleName` reaches this call, and
+            // there is no other way in: `compileScript` reads it from
+            // `options.templateOptions.compilerOptions.runtimeModuleName` and
+            // otherwise emits `import { defineComponent } from 'vue'` — the full
+            // Vue package, which re-exports `@vue/runtime-dom` and its DOM
+            // renderer into a bundle that has no DOM.
+            templateOptions: { compilerOptions },
+        })
+        : null;
+    // Each piece with the map that explains it, so the module can carry ONE map over
+    // the whole `.vue` file instead of pointing every stack frame at a generated line.
+    const parts = [
+        script === null
+            ? { code: `const ${SFC_BINDING} = {};`, map: null }
+            : { code: script.content, map: script.map ?? null },
+    ];
+    if (descriptor.template !== null) {
+        const template = compileTemplate({
+            id,
+            filename,
+            source: descriptor.template.content,
+            // Safe to reuse ONLY because `parse` above got the parser options.
+            ast: descriptor.template.ast,
+            compilerOptions: { ...compilerOptions, bindingMetadata: script?.bindings },
+        });
+        if (template.errors.length > 0) {
+            throw new Error(`@gjsify/rolldown-plugin-vue: ${filename} has a template that does not compile:\n  ` +
+                messagesOf(template.errors));
+        }
+        // The rename is a same-line replacement, so it moves no mapping to another
+        // line — and the `export function render(` line the compiler emits carries no
+        // mapping of its own.
+        parts.push({ code: renameRenderExport(template.code, filename), map: template.map ?? null });
+        parts.push({ code: `${SFC_BINDING}.render = ${RENDER_BINDING};`, map: null });
+    }
+    parts.push({ code: `${SFC_BINDING}.__file = ${JSON.stringify(filename)};`, map: null });
+    parts.push({ code: `export default ${SFC_BINDING};`, map: null });
+    return {
+        code: parts.map((part) => part.code).join('\n'),
+        map: combineSourceMaps(parts.map((part) => ({ lineCount: part.code.split('\n').length, map: part.map }))),
+    };
+}
+/**
+ * Compile Vue SFCs to a component module for a gjsify custom renderer.
+ *
+ * Wire it through `package.json#gjsify` so no JS-form config file is needed:
+ *
+ * ```json
+ * "gjsify": { "bundler": { "plugins": [{ "name": "@gjsify/rolldown-plugin-vue" }] } }
+ * ```
+ */
+export function vuePlugin(options = {}) {
+    const isCustomElement = options.isCustomElement ?? isGtkHostTag;
+    const include = stateless(options.include ?? DEFAULT_INCLUDE);
+    const runtimeModuleName = options.runtimeModuleName ?? DEFAULT_RUNTIME_MODULE_NAME;
+    return {
+        name: 'gjsify-vue',
+        resolveId: {
+            // Before anything else can claim the specifier — what follows must see
+            // the renamed id, not the `.vue` one.
+            order: 'pre',
+            async handler(source, importer) {
+                if (!include.test(source))
+                    return null;
+                // `skipSelf` so the real resolution runs without re-entering here.
+                // The result carries the absolute path; the suffix is appended to
+                // THAT, so a diagnostic still names the file with the real path as
+                // its prefix.
+                const resolved = await this.resolve(source, importer, { skipSelf: true });
+                if (!resolved || !include.test(resolved.id))
+                    return null;
+                // An EXTERNAL `.vue` is not this plugin's to compile: renaming it would
+                // mint a virtual id whose `load` then `readFile`s a path that is not
+                // there (ENOENT), for a module the build was told to leave alone. Handed
+                // back verbatim instead.
+                if (resolved.external)
+                    return resolved;
+                // `moduleSideEffects` and `meta` are the rest of what the real
+                // resolution DECIDED — a plugin that answers with a bare string throws
+                // away a `sideEffects: false` and every other plugin's `meta` with it.
+                return {
+                    id: `${resolved.id}${VIRTUAL_SUFFIX}`,
+                    moduleSideEffects: resolved.moduleSideEffects,
+                    meta: resolved.meta,
+                };
+            },
+        },
+        async load(id) {
+            if (!id.endsWith(VIRTUAL_SUFFIX))
+                return null;
+            const filename = id.slice(0, -VIRTUAL_SUFFIX.length);
+            // Re-checked against `include` rather than against a literal `.vue`, so a
+            // caller-narrowed filter stays consistent across the two hooks: the pair
+            // that mints an id and the pair that reads it must agree, or the id
+            // reaches rolldown's file loader and fails on a path that does not exist.
+            if (!include.test(filename))
+                return null;
+            const source = await readFile(filename, 'utf8');
+            return compileSfc(source, filename, {
+                isCustomElement,
+                runtimeModuleName,
+                onWarn: (message) => this.warn(message),
+            });
+        },
+    };
+}
+export default vuePlugin;

package/lib/source-map.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The fields of a source map this merge READS.
+ *
+ * Deliberately not `source-map-js`'s `RawSourceMap`: that interface types `version` as
+ * `string` while every producer writes the number 3, so accepting it would force a cast
+ * at the one call site that has a real map.
+ */
+export interface SourceMapChunkMap {
+    sources: string[];
+    sourcesContent?: string[];
+    names: string[];
+    mappings: string;
+}
+/** What this module produces — assignable to rolldown's `ExistingRawSourceMap`. */
+export interface CombinedSourceMap {
+    version: 3;
+    sources: string[];
+    sourcesContent: (string | null)[];
+    names: string[];
+    mappings: string;
+}
+/** One piece of the joined module: how many lines it occupies, and its own map. */
+export interface SourceMapChunk {
+    /** Lines this piece occupies in the joined output, including its last. */
+    lineCount: number;
+    /** `null` for a piece this plugin generated, which no source position explains. */
+    map: SourceMapChunkMap | null;
+}
+/**
+ * One map for a module built by joining `chunks` with a newline between each.
+ *
+ * `null` when no chunk carried a map, so a caller can pass `map: null` — which tells a
+ * bundler "this code has no source", not "this code is its own source".
+ */
+export declare function combineSourceMaps(chunks: readonly SourceMapChunk[]): CombinedSourceMap | null;
+/**
+ * Where `generatedLine`/`generatedColumn` (both 1-based) came from, or `null`.
+ *
+ * Exported for the specs: a merged map is only checkable by resolving a position
+ * through it, and asserting the `mappings` STRING would pin the encoder's output rather
+ * than the mapping it claims to carry.
+ */
+export declare function originalPositionFor(map: CombinedSourceMap, generatedLine: number, generatedColumn: number): {
+    source: string;
+    line: number;
+    column: number;
+} | null;

package/lib/source-map.js

@@ -0,0 +1,206 @@
+// Joining the source maps `@vue/compiler-sfc` hands back, because the module this
+// plugin emits is a CONCATENATION and neither half's map describes it.
+//
+// `compileScript` maps the script half, `compileTemplate` maps the template half, and
+// both already resolve to the WHOLE `.vue` file: measured on 3.5.41, `sourcesContent[0]`
+// is the SFC source in both, and the template map's source lines already count from the
+// top of the file rather than from the template block. So the source side needs nothing;
+// only the GENERATED side does — where each half landed in the joined module.
+//
+// WHY DECODE AT ALL, rather than concatenate the two `mappings` strings with the right
+// number of `;`. The generated COLUMN resets on every line, but the source index, source
+// line, source column and name index are deltas carried across the entire map. Splice
+// two strings together and the second half's first segment is read relative to the first
+// half's last one, which puts every remaining mapping somewhere else in the file. The
+// Base64-VLQ codec below is what makes offsetting possible; it is spelled out rather than
+// taken as a dependency because `@jridgewell/sourcemap-codec` is only in this tree
+// transitively, and a direct dependency of a tier-1 package costs a lockfile change and a
+// "does it load under GJS" answer for thirty lines.
+/** Base64 digits in `sourceMappingURL` order — index IS the value. */
+const BASE64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+/** Signed Base64 VLQ: continuation in bit 5, sign in bit 0 of the first digit. */
+function decodeVlq(segment, mappings) {
+    const values = [];
+    let value = 0;
+    let scale = 1;
+    for (const char of segment) {
+        const digit = BASE64.indexOf(char);
+        if (digit === -1)
+            throw new Error(malformed(mappings, `${JSON.stringify(char)} is not a Base64 VLQ digit`));
+        // Multiplication rather than `<<`: a name index in a large map can exceed the
+        // 31 bits a shift keeps, and the overflow would be silent.
+        value += (digit & 31) * scale;
+        if ((digit & 32) !== 0) {
+            scale *= 32;
+            continue;
+        }
+        values.push(value % 2 === 1 ? -(value - 1) / 2 : value / 2);
+        value = 0;
+        scale = 1;
+    }
+    if (scale !== 1)
+        throw new Error(malformed(mappings, 'a VLQ value ends mid-continuation'));
+    return values;
+}
+function encodeVlq(value) {
+    let rest = value < 0 ? -value * 2 + 1 : value * 2;
+    let encoded = '';
+    do {
+        const digit = rest % 32;
+        rest = Math.floor(rest / 32);
+        encoded += BASE64[rest > 0 ? digit + 32 : digit];
+    } while (rest > 0);
+    return encoded;
+}
+function malformed(mappings, why) {
+    return (`@gjsify/rolldown-plugin-vue: cannot read a source map @vue/compiler-sfc produced — ${why}. ` +
+        `Mappings began ${JSON.stringify(mappings.slice(0, 40))}.`);
+}
+/** The wire form, line by line, with every position made absolute. */
+function decodeMappings(mappings) {
+    let source = 0;
+    let sourceLine = 0;
+    let sourceColumn = 0;
+    let name = 0;
+    return mappings.split(';').map((line) => {
+        let generatedColumn = 0;
+        return line
+            .split(',')
+            .filter((segment) => segment !== '')
+            .map((segment) => {
+            const fields = decodeVlq(segment, mappings);
+            generatedColumn += fields[0];
+            if (fields.length === 1)
+                return { generatedColumn };
+            // 2 and 3 are not shapes the format has. Refused rather than read as a
+            // 4-field segment with zeros, which would point at line 1 column 1.
+            if (fields.length < 4) {
+                throw new Error(malformed(mappings, `a segment carries ${fields.length} fields, not 1, 4 or 5`));
+            }
+            source += fields[1];
+            sourceLine += fields[2];
+            sourceColumn += fields[3];
+            const mapping = { generatedColumn, source, sourceLine, sourceColumn };
+            if (fields.length > 4) {
+                name += fields[4];
+                mapping.name = name;
+            }
+            return mapping;
+        });
+    });
+}
+function encodeMappings(lines) {
+    let source = 0;
+    let sourceLine = 0;
+    let sourceColumn = 0;
+    let name = 0;
+    return lines
+        .map((segments) => {
+        let generatedColumn = 0;
+        return segments
+            .map((mapping) => {
+            let encoded = encodeVlq(mapping.generatedColumn - generatedColumn);
+            generatedColumn = mapping.generatedColumn;
+            if (mapping.source === undefined)
+                return encoded;
+            encoded +=
+                encodeVlq(mapping.source - source) +
+                    encodeVlq(mapping.sourceLine - sourceLine) +
+                    encodeVlq(mapping.sourceColumn - sourceColumn);
+            source = mapping.source;
+            sourceLine = mapping.sourceLine;
+            sourceColumn = mapping.sourceColumn;
+            if (mapping.name !== undefined) {
+                encoded += encodeVlq(mapping.name - name);
+                name = mapping.name;
+            }
+            return encoded;
+        })
+            .join(',');
+    })
+        .join(';');
+}
+/**
+ * One map for a module built by joining `chunks` with a newline between each.
+ *
+ * `null` when no chunk carried a map, so a caller can pass `map: null` — which tells a
+ * bundler "this code has no source", not "this code is its own source".
+ */
+export function combineSourceMaps(chunks) {
+    if (!chunks.some((chunk) => chunk.map !== null))
+        return null;
+    const sources = [];
+    const sourcesContent = [];
+    const names = [];
+    const lines = [];
+    for (const chunk of chunks) {
+        if (chunk.map === null) {
+            lines.push(...Array.from({ length: chunk.lineCount }, () => []));
+            continue;
+        }
+        const decoded = decodeMappings(chunk.map.mappings);
+        // A map describing MORE lines than its chunk holds would shift every following
+        // chunk, and silently: the mappings still decode, they just point into the wrong
+        // half of the module. That is the whole failure this function exists to avoid.
+        if (decoded.length > chunk.lineCount) {
+            throw new Error(`@gjsify/rolldown-plugin-vue: a source map describes ${decoded.length} line(s) for a ` +
+                `${chunk.lineCount}-line chunk. Every mapping after it would name the wrong line.`);
+        }
+        // Source and name indices are per-map; the merged map has one table for all.
+        const sourceIndex = chunk.map.sources.map((source, index) => {
+            const existing = sources.indexOf(source);
+            if (existing !== -1)
+                return existing;
+            sources.push(source);
+            sourcesContent.push(chunk.map?.sourcesContent?.[index] ?? null);
+            return sources.length - 1;
+        });
+        const nameIndex = chunk.map.names.map((entry) => {
+            const existing = names.indexOf(entry);
+            if (existing !== -1)
+                return existing;
+            names.push(entry);
+            return names.length - 1;
+        });
+        for (const segments of decoded) {
+            lines.push(segments.map((mapping) => mapping.source === undefined
+                ? mapping
+                : {
+                    ...mapping,
+                    source: sourceIndex[mapping.source],
+                    ...(mapping.name === undefined ? {} : { name: nameIndex[mapping.name] }),
+                }));
+        }
+        for (let line = decoded.length; line < chunk.lineCount; line++)
+            lines.push([]);
+    }
+    return { version: 3, sources, sourcesContent, names, mappings: encodeMappings(lines) };
+}
+/**
+ * Where `generatedLine`/`generatedColumn` (both 1-based) came from, or `null`.
+ *
+ * Exported for the specs: a merged map is only checkable by resolving a position
+ * through it, and asserting the `mappings` STRING would pin the encoder's output rather
+ * than the mapping it claims to carry.
+ */
+export function originalPositionFor(map, generatedLine, generatedColumn) {
+    const segments = decodeMappings(map.mappings)[generatedLine - 1];
+    if (segments === undefined)
+        return null;
+    // The last segment at or before the column: a segment covers from its own generated
+    // column up to the next one.
+    let found;
+    for (const mapping of segments) {
+        if (mapping.generatedColumn > generatedColumn - 1)
+            break;
+        if (mapping.source !== undefined)
+            found = mapping;
+    }
+    if (found === undefined)
+        return null;
+    return {
+        source: map.sources[found.source],
+        line: found.sourceLine + 1,
+        column: found.sourceColumn + 1,
+    };
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+    "name": "@gjsify/rolldown-plugin-vue",
+    "version": "0.42.0",
+    "description": "Vue 3 single-file-component compiler plugin for Rolldown / Rollup / Vite — targeting a gjsify custom renderer",
+    "type": "module",
+    "main": "lib/index.js",
+    "module": "lib/index.js",
+    "types": "lib/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./lib/index.d.ts",
+            "default": "./lib/index.js"
+        }
+    },
+    "files": [
+        "lib"
+    ],
+    "scripts": {
+        "clear": "gjsify clear lib test.node.mjs test.gjs.mjs *.tsbuildinfo",
+        "check": "gjsify tsc --noEmit",
+        "build": "gjsify tsc -p tsconfig.build.json",
+        "build:test": "gjsify run build:test:node && gjsify run build:test:gjs",
+        "build:test:node": "gjsify build src/test.mts --app node --outfile test.node.mjs",
+        "build:test:gjs": "gjsify build src/test.mts --app gjs --outfile test.gjs.mjs",
+        "test": "gjsify run build:test && gjsify run test:node && gjsify run test:gjs",
+        "test:node": "node test.node.mjs",
+        "test:gjs": "gjsify run test.gjs.mjs"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gjsify/gjsify.git"
+    },
+    "bugs": {
+        "url": "https://github.com/gjsify/gjsify/issues"
+    },
+    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/infra/rolldown-plugin-vue#readme",
+    "keywords": [
+        "rolldown",
+        "rollup",
+        "vite",
+        "vue",
+        "sfc",
+        "gtk",
+        "gjs"
+    ],
+    "license": "MIT",
+    "dependencies": {
+        "@vue/compiler-sfc": "^3.5.41"
+    },
+    "peerDependencies": {
+        "rolldown": "^1.1.4"
+    },
+    "peerDependenciesMeta": {
+        "rolldown": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "@gjsify/cli": "^0.42.0",
+        "@gjsify/unit": "^0.42.0",
+        "@types/node": "^25.9.2",
+        "rolldown": "^1.1.4"
+    },
+    "gjsify": {
+        "tier": 1
+    }
+}