@cockernutx/language-plugin-brace 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vue-brace contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# @cockernutx/language-plugin-brace
+
+Volar / Vue language tools plugin for `lang="brace"` templates.
+
+Without it, Volar hands the brace source to the HTML parser: template expressions are never
+*checked*, so `@if (…)` / `@for (…)` conditions are seen as plain text and the whole block
+produces spurious errors and no hover.
+
+## Build before you use it
+
+```sh
+deno task build:plugin     # from the repo root
+```
+
+**Volar loads a language plugin by resolving it and calling `require()` on the result**, in
+`vue-tsc` and in the editor's language server — both Node processes. Serving
+`src/index.ts` works only under Deno, which can `require()` TypeScript directly. In Node it
+is a `SyntaxError`; Volar catches it and carries on **without the plugin**, so every brace
+template loses hover, completions and diagnostics, and the only trace is a warning in the
+Vue Language Server output channel:
+
+```
+[Vue] Resolve plugin path failed: @cockernutx/language-plugin-brace SyntaxError: …
+```
+
+This is the failure mode this package was written in, and it is worth knowing because it
+looks like "the plugin does nothing" rather than "the plugin did not load". `index.cjs`
+therefore loads `dist/index.js`, and `deno task test` rebuilds it; a test fails if `dist` is
+missing or older than the source it came from.
+
+**How to tell it loaded:** open a brace template and hover a variable in a `@try` block. With
+the plugin loaded you get a type; without it, `any` (or nothing) — and Volar will be reporting
+errors on lines of brace syntax that are perfectly valid. **Reload the window** after building:
+the language server only loads plugins at startup.
+
+## Setup
+
+```jsonc
+// tsconfig.app.json
+{
+  "vueCompilerOptions": {
+    "plugins": ["@cockernutx/language-plugin-brace"]
+  }
+}
+```
+
+## How it works
+
+Volar reaches a custom template language through three hooks. The plugin implements all
+three:
+
+1. **`getEmbeddedCodes` / `resolveEmbeddedCode`** — publish the raw brace block as an
+   embedded document with `lang: 'brace'`. Volar's built-in `vue-sfc-template` plugin only
+   does this for `lang === 'html'`, so without these hooks a brace template has no virtual
+   file at all: no highlighting and no in-template features.
+2. **`compileSFCTemplate`** — compiles the generated template with language-core's
+   `compileTemplate` and supplies the AST that template type checking works from.
+3. **Offset remapping** — every location in that AST is rewritten back into brace-source
+   coordinates.
+
+Step 3 is why `compileBrace` returns a map. Because the transform emits one line per input
+line, a generated line belongs to exactly one source line, and within it every copied
+fragment is recorded as a `{ gen, src, length }` segment. A generated position inside one of
+those segments maps to the exact source character; anything else is synthesised markup
+(`<template v-if="…">`) and falls back to the end of the nearest copied run, or to the end of
+the source line when it has none.
+
+Per-fragment mapping matters more than it sounds. One `@for` line becomes
+`<template v-for="item in items" :key="item.id">`, so `item`, `items` and `item.id` all sit
+at different offsets from their generated counterparts; a single shift per line gets only
+the first of them right, and the rest — the ones outside an `@if` line, which is most of a
+template — point at the wrong token, which is what makes hover and go-to-definition fail.
+
+The embedded content pushed in step 1 is the *raw brace source*, which is the same
+coordinate space the remapped AST uses. Keeping those two in step is the whole trick, and
+it is why the two hooks cannot be implemented independently.
+
+A malformed block is reported through `onError` rather than thrown, so a bad template
+produces a diagnostic instead of a dead language server.
+
+### Why the AST must stay in brace coordinates
+
+Volar does not only read offsets out of this AST — it also slices text:
+
+- `options.template` (the brace source) is sliced using AST offsets, so offsets have to be
+  brace coordinates for expressions, props and children to map anywhere sensible.
+- `parseVForNode` slices `node.loc.source` — the *generated* text — using offsets relative to
+  the node. That is the one place where the two coordinate spaces collide, and it is what used
+  to make `@for` with `index` / `key` report two TypeScript syntax errors; the alignment pass
+  described under Caveats is what reconciles them. Everything else is consistent because both
+  the offsets and the document they describe end up in brace coordinates.
+
+## Highlighting
+
+The `lang: 'brace'` embedded document needs a grammar to be useful, which VS Code can only
+get from an extension. `packages/vscode-vue-brace` registers that language id and a TextMate
+grammar — install it as described in its README. Without it, brace templates render as
+plain text.
+
+## Entry point
+
+Volar resolves plugin names with `require()` and then calls the resolved module *itself* as
+the factory (no `.default` unwrapping), so the entry has to be a callable CommonJS module
+that **Node** can load. `index.cjs` re-exports the default from `dist/index.js`, which
+`deno task build:plugin` produces. Pointing it at `src/index.ts` instead is the trap
+described at the top of this file: Deno loads it happily and the editor never does.
+
+## Caveats
+
+- The plugin API version is pinned to `2.2`. language-core's `validVersions` is
+  `[2, 2.1, 2.2]`; anything else makes it drop the plugin with only a console warning.
+- **`@for` with `index` or `key` needs the element aligned to the author's column.** Volar
+  rebuilds the
+  `v-for` binding by slicing the generated `<template v-for="(item, i) in …">` text with
+  offsets *relative to the element*, so those deltas have to come out as the generated ones.
+  `collectVForPatterns` reads the binding names with generated deltas *before* the remap;
+  `alignVForPatterns` then anchors the element on the `@for` column the author wrote and
+  rebuilds `loc.source` as a padded pattern occupying the author's own columns. Before that,
+  the slice produced garbage: the errors above, plus garbage binding names whose semantic
+  tokens landed across the template. (An earlier attempt moved the element's start onto the
+  generated geometry instead. That repairs the slice and corrupts every other consumer of that
+  offset, which reads it as a *source* position — do not reintroduce it.)
+- **`vue-tsc` needs a Node runtime.** It cannot run under Deno — Volar registers `.vue`
+  support by rewriting `tsc.js` through an `fs.readFileSync` hook that Deno bypasses — so a
+  Node binary has to be present to type-check templates. That is how the loader bug above was
+  found: `node …/vue-tsc.js --noEmit` reported `Resolve plugin path failed`, and
+  `--listFiles` showed no `.vue` files in the program at all.
+

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import type { VueLanguagePlugin } from '@vue/language-core';
+/**
+ * Volar plugin for `lang="brace"`.
+ *
+ * Volar only reaches a custom template language through `compileSFCTemplate`; without it
+ * the brace source is handed to the HTML parser, so template expressions are never
+ * type-checked. Wire it up with:
+ *
+ * ```jsonc
+ * // tsconfig.json
+ * { "vueCompilerOptions": { "plugins": ["@cockernutx/language-plugin-brace"] } }
+ * ```
+ */
+declare const plugin: VueLanguagePlugin;
+export default plugin;

package/dist/index.js

@@ -0,0 +1,242 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const compile_1 = require("@cockernutx/brace-template/compile");
+const mapper_1 = require("@cockernutx/brace-template/mapper");
+const preprocessor_1 = require("@cockernutx/brace-template/preprocessor");
+/**
+ * Apply `visit` to every object in the tree, once.
+ *
+ * Every *object*, not every AST node: `remapOffsets` has to reach the `{ start, end }`
+ * locations nested inside `loc`, which carry no `type` of their own, so the filter has to be
+ * the callback's business.
+ */
+function walk(value, visit, seen = new Set()) {
+    if (!value || typeof value !== 'object' || seen.has(value))
+        return;
+    seen.add(value);
+    const record = value;
+    visit(record);
+    for (const key in record)
+        walk(record[key], visit, seen);
+}
+/**
+ * Rewrite `offset` on every node of the tree, in place.
+ *
+ * The compiler's AST carries offsets on expression nodes and locations; Volar derives lines
+ * and columns from them, so every one of them has to move into brace-source coordinates.
+ */
+function remapOffsets(value, toSourceOffset) {
+    walk(value, (node) => {
+        if (typeof node.offset === 'number')
+            node.offset = toSourceOffset(node.offset);
+    });
+}
+/**
+ * Point each element's `loc.start` at its tag name rather than at the `<`.
+ *
+ * Volar's component-name tokens (`vue-component-semantic-tokens` in the language server) compute
+ * the range like this:
+ *
+ * ```js
+ * let start = element.loc.start.offset
+ * if (template.lang === 'html') start += 1          // skip the `<`
+ * push({ start, length: element.tag.length })
+ * ```
+ *
+ * So for `lang === 'html'` the AST is assumed to start an element at the `<` and the provider
+ * compensates; for any other lang it takes `loc.start` to be the *name*. Our brace AST follows
+ * the html convention, so the token came out covering `<FragileChil` — one character wide of the
+ * name, leaving the last character to the grammar's colour. Volar's own mappings were exact
+ * throughout, which is what made this look like a mapping bug on our side; it is a convention
+ * mismatch in a branch keyed on the template's `lang`.
+ *
+ * Shifting by one keeps every other consumer working: `getElementTagOffsets` searches with
+ * `indexOf(node.tag, node.loc.start.offset)`, and the name starts exactly at that position, so
+ * the offset it returns is unchanged.
+ */
+function alignElementStartsToTagNames(ast) {
+    walk(ast, (node) => {
+        if (node.type !== 1 || typeof node.tag !== 'string' || !node.loc?.start)
+            return;
+        node.loc.start.offset += 1;
+    });
+}
+/**
+ * A `v-for`'s binding pattern, as Volar reads it.
+ *
+ * `codegen/template/vFor.js` (`parseVForNode`) rebuilds the pattern by slicing the element's
+ * own text between two offsets, relative to the element:
+ *
+ * ```js
+ * node.loc.source.slice(value.loc.start.offset - node.loc.start.offset,
+ *                       (index ?? key ?? value).loc.end.offset - node.loc.start.offset)
+ * ```
+ *
+ * It then emits `for (const [<slice>] of …)` and maps the slice 1:1 onto the source range
+ * `[value.loc.start, (index ?? key ?? value).loc.end)`. Two coordinate spaces meet here:
+ *
+ * - `loc.source` is the element's text as parsed from the *generated* markup, so it has to be
+ *   read with **generated** offsets;
+ * - the offsets themselves are remapped to **source** coordinates, because the same `loc` drives
+ *   hover and navigation for the author's file.
+ *
+ * Reading the names with remapped offsets silently returned `"(it` instead of `item`. And
+ * because the emitted pattern is only as long as the slice, the range it maps onto has to be
+ * the author's clause — otherwise the two bindings land on the wrong columns (`index` used to
+ * be mapped onto `of`, and the whole range was scaled down to seven characters).
+ */
+function collectVForPatterns(ast) {
+    const found = [];
+    walk(ast, (node) => {
+        const parseResult = node.parseResult;
+        const { value, index, key } = parseResult ?? {};
+        if (!value?.loc || !node.loc)
+            return;
+        const last = index ?? key ?? value;
+        const pattern = node.loc.source;
+        if (typeof pattern !== 'string')
+            return;
+        const relative = (offset) => offset - node.loc.start.offset;
+        const names = [value, last].filter((name, i, all) => all.indexOf(name) === i);
+        found.push({
+            node,
+            value,
+            names: names.map((name) => [
+                name,
+                pattern.slice(relative(name.loc.start.offset), relative(name.loc.end.offset)),
+            ]),
+        });
+    });
+    return found;
+}
+/**
+ * Give the element a source position, and build the pattern text Volar will slice out of it.
+ *
+ * The element is synthesised (`@for (…) {` becomes `<template v-for="(item, i) in …">`), so it
+ * is anchored to the directive the author wrote. The names are then placed at the columns they
+ * occupy in the author's clause, and the pattern is padded to the clause's length: the slice is
+ * a valid binding pattern, and because it is exactly as long as the source range it maps onto,
+ * each binding lands on the name that was typed. The padding is whitespace inside `[…]`, which
+ * is legal and inert.
+ */
+function alignVForPatterns(patterns, template) {
+    for (const { node, value, names } of patterns) {
+        const sourceLineStart = template.lastIndexOf('\n', node.loc.end.offset) + 1;
+        const indent = /^[ \t]*/.exec(template.slice(sourceLineStart))?.[0].length ?? 0;
+        node.loc.start.offset = sourceLineStart + indent;
+        const end = names.at(-1)[0].loc.end.offset - node.loc.start.offset;
+        if (end <= 0)
+            continue;
+        const chars = Array.from({ length: end }, () => ' ');
+        for (const [name, text] of names) {
+            const at = name.loc.start.offset - node.loc.start.offset;
+            if (at < 0)
+                continue;
+            for (let i = 0; i < text.length && at + i < end; i += 1)
+                chars[at + i] = text[i];
+        }
+        // Separate the names, so the slice parses as a two-element binding pattern.
+        if (names.length > 1) {
+            chars[value.loc.end.offset - node.loc.start.offset] = ',';
+        }
+        node.loc.source = chars.join('');
+    }
+}
+/**
+ * Volar plugin for `lang="brace"`.
+ *
+ * Volar only reaches a custom template language through `compileSFCTemplate`; without it
+ * the brace source is handed to the HTML parser, so template expressions are never
+ * type-checked. Wire it up with:
+ *
+ * ```jsonc
+ * // tsconfig.json
+ * { "vueCompilerOptions": { "plugins": ["@cockernutx/language-plugin-brace"] } }
+ * ```
+ */
+const plugin = ({ modules }) => {
+    const { codeFeatures, compileTemplate } = modules['@vue/language-core'];
+    return {
+        name: '@cockernutx/language-plugin-brace',
+        // `validVersions` is [2, 2.1, 2.2]; anything else makes language-core drop the plugin
+        // with only a console warning.
+        version: 2.2,
+        /**
+         * language-core's built-in `vue-sfc-template` plugin only produces an embedded document
+         * when `lang === 'html'`, so without this a brace template has no virtual file in the
+         * editor at all: no highlighting, and no completions, hover, navigation or diagnostics
+         * inside it.
+         *
+         * The content pushed in `resolveEmbeddedCode` is the *raw brace source*, which is
+         * exactly the coordinate space the remapped AST uses — the two have to agree for any of
+         * this to line up, and keeping them in step is why `compileBraceWithMap` exists.
+         */
+        getEmbeddedCodes(_fileName, ir) {
+            const template = ir.template;
+            if (!template || template.lang !== preprocessor_1.BRACE_LANG)
+                return [];
+            return [{ id: 'template', lang: preprocessor_1.BRACE_LANG }];
+        },
+        resolveEmbeddedCode(_fileName, ir, embeddedFile) {
+            const template = ir.template;
+            if (embeddedFile.id !== 'template' || !template || template.lang !== preprocessor_1.BRACE_LANG)
+                return;
+            embeddedFile.content.push([
+                template.content,
+                template.name,
+                0,
+                codeFeatures.full,
+            ]);
+        },
+        compileSFCTemplate(lang, template, options) {
+            if (lang !== preprocessor_1.BRACE_LANG)
+                return;
+            let compiled;
+            try {
+                compiled = (0, compile_1.compileBraceWithMap)(template);
+            }
+            catch (error) {
+                // A malformed block must surface as a diagnostic, never as a dead language server. The
+                // cast names the error type of *this* options object rather than one imported from
+                // `@vue/compiler-dom`, for the reason explained at `TemplateAst`.
+                options.onError?.({
+                    name: 'BraceCompileError',
+                    message: error instanceof Error ? error.message : String(error),
+                    code: 0,
+                });
+                return { ast: compileTemplate('', options), code: '', preamble: '' };
+            }
+            const toSourceOffset = (0, mapper_1.createOffsetMapper)(template, compiled.code, compiled.lines);
+            /**
+             * Move a diagnostic's location into brace coordinates.
+             *
+             * Generic on purpose: the identity of Volar's warning and error types is Volar's business,
+             * not ours, and a signature naming them would reintroduce the coupling this file avoids.
+             */
+            const remap = (diagnostic) => {
+                if (diagnostic.loc) {
+                    diagnostic.loc.start.offset = toSourceOffset(diagnostic.loc.start.offset);
+                    diagnostic.loc.end.offset = toSourceOffset(diagnostic.loc.end.offset);
+                }
+                return diagnostic;
+            };
+            const ast = compileTemplate(compiled.code, {
+                ...options,
+                onWarn: (warning) => options.onWarn?.(remap(warning)),
+                onError: (error) => options.onError?.(remap(error)),
+            });
+            // The `v-for` pattern needs both coordinate spaces: the names are read from the generated
+            // markup *before* the remap, and placed into the author's columns *after* it.
+            const vForPatterns = collectVForPatterns(ast);
+            remapOffsets(ast, toSourceOffset);
+            // Volar's component-token provider reads an element's `loc.start` as its tag *name* for
+            // any template whose lang is not `html` (see `alignElementStartsToTagNames`), so that has
+            // to be true of the offsets we hand over — and after the remap, so the shift applies to a
+            // source offset.
+            alignElementStartsToTagNames(ast);
+            alignVForPatterns(vForPatterns, template);
+            return { ast, code: '', preamble: '' };
+        },
+    };
+};
+exports.default = plugin;

package/dist/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/index.cjs

@@ -0,0 +1,11 @@
+// Volar loads language plugins by resolving a specifier and calling `require()` on the
+// result, with no `.default` unwrapping — see how `@vue/language-plugin-pug` ships as
+// CommonJS.
+//
+// This file used to require `./src/index.ts`, which only works because Deno can `require()`
+// TypeScript. The editor's language server and `vue-tsc` are Node processes, where that is a
+// `SyntaxError`: Volar catches it and carries on without the plugin, so every brace template
+// silently loses brace syntax, hover and diagnostics, and the only trace is a warning in the
+// language server's output channel. `deno task build:plugin` compiles the plugin to `dist/`,
+// which is what Node loads.
+module.exports = require('./dist/index.js').default

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@cockernutx/language-plugin-brace",
+  "version": "0.1.0",
+  "description": "Volar / Vue language tools plugin for lang=\"brace\" SFC templates",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "index.cjs", "README.md", "LICENSE"],
+  "scripts": {
+    "prepack": "deno task --cwd=../.. build:plugin",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": ["vue", "volar", "language-server", "plugin", "template"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/strawberyy-coconut/vue-brace.git",
+    "directory": "packages/language-plugin-brace"
+  },
+  "homepage": "https://github.com/strawberyy-coconut/vue-brace#readme",
+  "bugs": "https://github.com/strawberyy-coconut/vue-brace/issues",
+  "dependencies": {
+    "@cockernutx/brace-template": "^0.1.0",
+    "@vue/language-core": "^3.3.11"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.0 || >=3.6.0-0"
+  },
+  "devDependencies": {
+    "@vue/compiler-dom": "catalog:",
+    "vitest": "^5.0.2",
+    "vue": "catalog:"
+  }
+}