@tiaforge-ui/sinter 0.0.0-stage → 0.2.0

package/dist/lsp/server.js

@@ -0,0 +1,281 @@
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { CODES, docsUrl } from '../compiler/index.js';
+import { check, findTsc } from '../check/index.js';
+import { Connection } from './rpc.js';
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { didYouMeanEdit } from './quickfix.js';
+import { TypeScriptBridge, typescriptMajor } from './typescript.js';
+import { Workspace } from './workspace.js';
+/** How long typing must pause before TypeScript checks the pages. */
+export const TYPECHECK_DELAY = 300;
+/** The range a diagnostic underlines: the name or word at its position, else one character. */
+export function rangeOf(text, line, col) {
+    const lines = text.split('\n');
+    const l = Math.max(0, Math.min(line - 1, lines.length - 1));
+    const s = lines[l] ?? '';
+    const c = Math.max(0, Math.min(col - 1, s.length));
+    const m = /^[\w$-]+/.exec(s.slice(c));
+    const end = m ? c + m[0].length : Math.min(c + 1, s.length);
+    return { start: { line: l, character: c }, end: { line: l, character: end > c ? end : c } };
+}
+export function toLsp(d, text) {
+    const name = CODES[d.code];
+    return {
+        range: d.span
+            ? { start: { line: d.span.line - 1, character: d.span.col - 1 }, end: { line: d.span.endLine - 1, character: d.span.endCol - 1 } }
+            : rangeOf(text, d.line, d.col),
+        severity: d.severity === 'error' ? 1 : 2,
+        code: name ? `${d.code} ${name}` : d.code,
+        codeDescription: { href: docsUrl(d.code) },
+        source: 'sinter',
+        message: d.message + (d.hint ? `\nhint: ${d.hint}` : ''),
+    };
+}
+const uriToPath = (uri) => fileURLToPath(uri);
+const pathToUri = (path) => pathToFileURL(path).href;
+export function startServer(input, output, o = {}) {
+    const conn = new Connection(input, output);
+    const last = new Map();
+    /** per project root: the TypeScript bridge, 'cli' for TypeScript before 7 (checked on save), or 'none' */
+    const typescript = new Map();
+    const timers = new Map();
+    const delay = o.typecheckDelay ?? TYPECHECK_DELAY;
+    let disposed = false;
+    const modeOf = (root) => {
+        let m = typescript.get(root);
+        if (m)
+            return m;
+        try {
+            const tsc = o.tsc ?? findTsc(root);
+            m = typescriptMajor(tsc) >= 7 ? new TypeScriptBridge(root, tsc) : 'cli';
+        }
+        catch {
+            m = 'none';
+        }
+        typescript.set(root, m);
+        return m;
+    };
+    const typecheck = async (state) => {
+        const mode = modeOf(state.root);
+        if (mode === 'none')
+            return;
+        if (mode === 'cli') {
+            const p = state.project;
+            const r = check({ root: state.root, units: [...state.units.values()], helpers: p.helpers, types: p.types, openapi: p.openapi, tsc: o.tsc ?? findTsc(state.root) });
+            await workspace.setTypes(state, '*', r.diagnostics);
+            return;
+        }
+        await mode.update(state.project, state.units);
+        for (const page of state.units.keys())
+            await workspace.setTypes(state, page, await mode.diagnostics(page));
+    };
+    const schedule = (state, wait) => {
+        clearTimeout(timers.get(state.root));
+        timers.set(state.root, setTimeout(() => {
+            timers.delete(state.root);
+            typecheck(state).catch((e) => disposed || process.stderr.write(`sinter lsp: type check failed: ${e instanceof Error ? e.stack : String(e)}\n`));
+        }, wait));
+    };
+    const workspace = new Workspace({
+        compiled(state) {
+            // before TypeScript 7 the check runs `tsc` once per save instead
+            if (modeOf(state.root) !== 'cli')
+                schedule(state, delay);
+        },
+        publish(file, diagnostics) {
+            let text = '';
+            try {
+                text = workspace.read(file);
+            }
+            catch { /* deleted: ranges fall back to line starts */ }
+            const params = { uri: pathToUri(file), diagnostics: diagnostics.map((d) => toLsp(d, text)) };
+            const json = JSON.stringify(params.diagnostics);
+            if (last.get(file) === json)
+                return;
+            last.set(file, json);
+            conn.notify('textDocument/publishDiagnostics', params);
+        },
+    });
+    let watchDynamic = false;
+    let shutdown = false;
+    conn.onRequest('initialize', (params) => {
+        watchDynamic = !!params?.capabilities?.workspace?.didChangeWatchedFiles?.dynamicRegistration;
+        const folders = (params?.workspaceFolders ?? []).map((f) => uriToPath(f.uri));
+        if (!folders.length && params?.rootUri)
+            folders.push(uriToPath(params.rootUri));
+        // load the projects of the open folders early, so the first open file is quick
+        for (const f of folders)
+            void workspace.projectFor(f + '/index.html').catch(() => { });
+        return {
+            capabilities: {
+                // full text on every change
+                textDocumentSync: { openClose: true, change: 1, save: { includeText: false } },
+                hoverProvider: true,
+                completionProvider: { triggerCharacters: ['.'], resolveProvider: true },
+                definitionProvider: true,
+                codeActionProvider: { codeActionKinds: ['quickfix'] },
+            },
+            serverInfo: { name: 'sinter' },
+        };
+    });
+    conn.onNotification('initialized', () => {
+        if (!watchDynamic)
+            return;
+        void conn.request('client/registerCapability', {
+            registrations: [{
+                    id: 'sinter-watch',
+                    method: 'workspace/didChangeWatchedFiles',
+                    registerOptions: {
+                        watchers: [
+                            { globPattern: '**/*.html' },
+                            { globPattern: '**/vite.config.{js,ts,mjs,mts,cjs,cts}' },
+                            { globPattern: '**/src/sinter.{helpers,types,config}.{js,ts}' },
+                            { globPattern: '**/src/sinter.types.d.ts' },
+                            { globPattern: '**/*.{yml,yaml,json}' },
+                            { globPattern: '**/src/**/*.{js,ts}' },
+                        ],
+                    },
+                }],
+        }).catch(() => { });
+    });
+    const local = (uri) => uri.startsWith('file:');
+    conn.onNotification('textDocument/didOpen', (p) => {
+        if (local(p.textDocument.uri))
+            return workspace.open(uriToPath(p.textDocument.uri), p.textDocument.text);
+    });
+    conn.onNotification('textDocument/didChange', (p) => {
+        const text = p.contentChanges[p.contentChanges.length - 1]?.text;
+        if (local(p.textDocument.uri) && typeof text === 'string')
+            return workspace.change(uriToPath(p.textDocument.uri), text);
+    });
+    conn.onNotification('textDocument/didClose', (p) => {
+        if (local(p.textDocument.uri))
+            return workspace.close(uriToPath(p.textDocument.uri));
+    });
+    conn.onNotification('textDocument/didSave', async (p) => {
+        if (!local(p.textDocument.uri))
+            return;
+        const file = uriToPath(p.textDocument.uri);
+        await workspace.fileChanged(file);
+        const state = await workspace.projectFor(file);
+        if (modeOf(state.root) === 'cli')
+            schedule(state, 0);
+    });
+    conn.onNotification('workspace/didChangeWatchedFiles', async (p) => {
+        const files = (p.changes ?? []).filter((c) => local(c.uri)).map((c) => uriToPath(c.uri));
+        for (const m of typescript.values())
+            if (m instanceof TypeScriptBridge)
+                m.filesChanged(files.filter((f) => !f.endsWith('.html')));
+        for (const f of files)
+            await workspace.fileChanged(f);
+    });
+    conn.onRequest('textDocument/hover', async (p) => {
+        if (!local(p.textDocument.uri))
+            return null;
+        const file = uriToPath(p.textDocument.uri);
+        const state = await workspace.projectFor(file);
+        const mode = modeOf(state.root);
+        if (!(mode instanceof TypeScriptBridge))
+            return null;
+        // the shadows must reflect the latest edit
+        await mode.update(state.project, state.units);
+        return mode.hover(file, p.position.line + 1, p.position.character + 1);
+    });
+    /** the bridge for a file's project, with its shadows brought up to date */
+    const bridgeFor = async (file) => {
+        const state = await workspace.projectFor(file);
+        const mode = modeOf(state.root);
+        if (!(mode instanceof TypeScriptBridge))
+            return null;
+        await mode.update(state.project, state.units);
+        return { bridge: mode, state };
+    };
+    conn.onRequest('textDocument/completion', async (p) => {
+        if (!local(p.textDocument.uri))
+            return null;
+        const file = uriToPath(p.textDocument.uri);
+        const b = await bridgeFor(file);
+        return b ? b.bridge.completion(file, p.position.line + 1, p.position.character + 1, p.context) : null;
+    });
+    conn.onRequest('completionItem/resolve', async (item) => {
+        const m = item?.data?.sinter ? typescript.get(item.data.sinter) : null;
+        return m instanceof TypeScriptBridge ? m.resolve(item) : item;
+    });
+    const location = (t) => {
+        let text = '';
+        try {
+            text = workspace.read(t.file);
+        }
+        catch { /* the target's range falls back to its start */ }
+        const range = t.endLine !== undefined && t.endCol !== undefined
+            ? { start: { line: t.line - 1, character: t.col - 1 }, end: { line: t.endLine - 1, character: t.endCol - 1 } }
+            : rangeOf(text, t.line, t.col);
+        return { uri: pathToUri(t.file), range };
+    };
+    conn.onRequest('textDocument/definition', async (p) => {
+        if (!local(p.textDocument.uri))
+            return null;
+        const file = uriToPath(p.textDocument.uri);
+        const partial = includeAt(workspace.read(file), p.position.line, p.position.character);
+        if (partial !== null) {
+            const target = resolve(dirname(file), partial);
+            return existsSync(target) ? [{ uri: pathToUri(target), range: { start: { line: 0, character: 0 }, end: { line: 0, character: 0 } } }] : null;
+        }
+        const b = await bridgeFor(file);
+        if (!b)
+            return null;
+        const targets = await b.bridge.definition(file, p.position.line + 1, p.position.character + 1, b.state.project);
+        return targets.map(location);
+    });
+    conn.onRequest('textDocument/codeAction', (p) => {
+        if (!local(p.textDocument.uri))
+            return [];
+        let text;
+        try {
+            text = workspace.read(uriToPath(p.textDocument.uri));
+        }
+        catch {
+            return [];
+        }
+        const actions = [];
+        for (const d of p.context?.diagnostics ?? []) {
+            if (d.source !== 'sinter')
+                continue;
+            const edit = didYouMeanEdit(text, d.range, d.message);
+            if (!edit)
+                continue;
+            actions.push({
+                title: `Change to '${edit.newText}'`, kind: 'quickfix', isPreferred: true, diagnostics: [d],
+                edit: { changes: { [p.textDocument.uri]: [edit] } },
+            });
+        }
+        return actions;
+    });
+    const dispose = () => {
+        disposed = true;
+        for (const t of timers.values())
+            clearTimeout(t);
+        timers.clear();
+        for (const m of typescript.values())
+            if (m instanceof TypeScriptBridge)
+                m.dispose();
+        typescript.clear();
+    };
+    conn.onRequest('shutdown', () => { shutdown = true; dispose(); return null; });
+    const closed = conn.onClose;
+    conn.onClose = () => { dispose(); closed?.(); };
+    conn.onNotification('exit', () => { conn.close(); o.exit?.(shutdown ? 0 : 1); });
+    conn.onUnhandled = () => { };
+    return conn;
+}
+/** The `src` of an `<sn-include>` when the 0-based position is inside its value, else null. */
+export function includeAt(text, line, character) {
+    const t = text.split('\n')[line] ?? '';
+    for (const m of t.matchAll(/<sn-include\b[^>]*?\bsrc\s*=\s*(["'])([^"']*)\1/g)) {
+        const start = m.index + m[0].length - 1 - m[2].length;
+        if (character >= start && character <= start + m[2].length)
+            return m[2];
+    }
+    return null;
+}

package/dist/lsp/spec-location.d.ts

@@ -0,0 +1,9 @@
+export interface SpecLocation {
+    line: number;
+    col: number;
+}
+/**
+ * The position of `components.schemas.<schema>` in `file`, or of its `properties.<prop>` when
+ * given and present. `schema` is the TypeScript name; the spec's own name is looked up.
+ */
+export declare function specLocation(file: string, schema: string, prop?: string): SpecLocation | null;

package/dist/lsp/spec-location.js

@@ -0,0 +1,42 @@
+// Where a named schema (or one of its properties) is written in an OpenAPI spec
+// file, for go to definition on types generated from it. YAML and JSON alike: the
+// `yaml` parser reads both and keeps source ranges.
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { typeName } from '../check/openapi-types.js';
+/** The key named `name` in a YAML map node. */
+function pair(map, name) {
+    return map?.items?.find((p) => p.key?.value === name);
+}
+function lineCol(text, offset) {
+    let line = 1;
+    let start = 0;
+    for (let i = 0; i < offset && i < text.length; i++)
+        if (text[i] === '\n') {
+            line++;
+            start = i + 1;
+        }
+    return { line, col: offset - start + 1 };
+}
+/**
+ * The position of `components.schemas.<schema>` in `file`, or of its `properties.<prop>` when
+ * given and present. `schema` is the TypeScript name; the spec's own name is looked up.
+ */
+export function specLocation(file, schema, prop) {
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const yaml = createRequire(import.meta.url)('yaml');
+    const doc = yaml.parseDocument(text);
+    const schemas = pair(pair(doc.contents, 'components')?.value, 'schemas')?.value;
+    const entry = schemas?.items?.find((p) => typeof p.key?.value === 'string' && typeName(p.key.value) === schema);
+    if (!entry?.key?.range)
+        return null;
+    const property = prop ? pair(pair(entry.value, 'properties')?.value, prop) : undefined;
+    const at = property?.key?.range ?? entry.key.range;
+    return lineCol(text, at[0]);
+}

package/dist/lsp/typescript.d.ts

@@ -0,0 +1,77 @@
+import { type Region } from '../check/shadow.js';
+import type { CheckUnit } from '../compiler/check-unit.js';
+import type { Diagnostic } from '../compiler/index.js';
+import type { Project } from '../project.js';
+/** The major version of the project's TypeScript, from the package next to its `tsc`. */
+export declare function typescriptMajor(tsc: string): number;
+interface OpenShadow {
+    unit: CheckUnit;
+    path: string;
+    uri: string;
+    text: string;
+    lines: string[];
+    regions: Region[];
+    brokenFrom: number | null;
+    version: number;
+}
+/** A place in a file, 1-based; `end` when known. */
+export interface Target {
+    file: string;
+    line: number;
+    col: number;
+    endLine?: number;
+    endCol?: number;
+}
+interface LspRange {
+    start: {
+        line: number;
+        character: number;
+    };
+    end: {
+        line: number;
+        character: number;
+    };
+}
+export declare class TypeScriptBridge {
+    readonly root: string;
+    private conn;
+    private child;
+    private ready;
+    private shadows;
+    private support;
+    readonly outDir: string;
+    constructor(root: string, tsc: string);
+    /** Brings the shadows in line with the pages' latest check units. */
+    update(project: Project, units: Map<string, CheckUnit>): Promise<void>;
+    /** TypeScript's errors in a page's expressions, at their HTML positions. */
+    diagnostics(page: string): Promise<Diagnostic[]>;
+    /** The page shadow and shadow position for a 1-based HTML position, if it is in an expression. */
+    locate(file: string, line: number, col: number): {
+        shadow: OpenShadow;
+        line: number;
+        col: number;
+    } | null;
+    /** Maps a shadow range back to the HTML; null when it is not inside one expression. */
+    private toHtml;
+    hover(file: string, line: number, col: number): Promise<{
+        contents: unknown;
+        range?: LspRange;
+    } | null>;
+    /** Completions at a 1-based HTML position inside an expression, with edits mapped to the HTML. */
+    completion(file: string, line: number, col: number, context: unknown): Promise<{
+        isIncomplete: boolean;
+        items: any[];
+    } | null>;
+    /** Details for a completion item this bridge returned (documentation, signature). */
+    resolve(item: any): Promise<any>;
+    /**
+     * Definitions of the name at a 1-based HTML position: where the HTML declares it (resources,
+     * state, loop variables), the spec for types generated from OpenAPI, else TypeScript's own
+     * answer (helpers, the types module).
+     */
+    definition(file: string, line: number, col: number, project: Project): Promise<Target[]>;
+    /** Tells TypeScript that files it may have read changed on disk. */
+    filesChanged(files: string[]): void;
+    dispose(): void;
+}
+export {};

package/dist/lsp/typescript.js

@@ -0,0 +1,242 @@
+// The bridge to TypeScript 7's own language server (`tsc --lsp --stdio`). It keeps
+// one shadow file per page open there, pulls type errors for them and answers hovers,
+// mapping positions between the HTML and the shadows.
+import { spawn } from 'node:child_process';
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { COMPILER_OPTIONS, shadowOf, shadowPath, typeDiagnostic, writeSupport } from '../check/index.js';
+import { mapPosition, shadowPosition } from '../check/shadow.js';
+import { Connection } from './rpc.js';
+import { specLocation } from './spec-location.js';
+/** The major version of the project's TypeScript, from the package next to its `tsc`. */
+export function typescriptMajor(tsc) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(dirname(tsc), '..', 'package.json'), 'utf8'));
+        return Number(/^(\d+)/.exec(pkg.version ?? '')?.[1] ?? 0);
+    }
+    catch {
+        return 0;
+    }
+}
+/** Names the shadow declares for itself, never offered as completions. */
+const INTERNAL = /^(\$any|\$item|\$p|\$e\d+)$/;
+export class TypeScriptBridge {
+    root;
+    conn;
+    child;
+    ready;
+    shadows = new Map();
+    support = null;
+    outDir;
+    constructor(root, tsc) {
+        this.root = root;
+        this.outDir = join(root, '.sinter', 'lsp');
+        mkdirSync(this.outDir, { recursive: true });
+        writeFileSync(join(this.outDir, 'tsconfig.json'), JSON.stringify({ compilerOptions: COMPILER_OPTIONS, include: ['**/*.js', '*.d.ts'] }, null, 2) + '\n');
+        this.child = spawn(process.execPath, [tsc, '--lsp', '--stdio'], { cwd: this.outDir, stdio: ['pipe', 'pipe', 'ignore'] });
+        this.conn = new Connection(this.child.stdout, this.child.stdin);
+        // workspace/configuration, client/registerCapability, progress: nothing to say
+        this.conn.requestFallback = (method, params) => (method === 'workspace/configuration' ? (params?.items ?? []).map(() => null) : null);
+        this.conn.onUnhandled = () => { };
+        this.child.on('error', () => this.conn.close());
+        this.child.stdin.on('error', () => this.conn.close());
+        this.ready = this.conn.request('initialize', {
+            processId: process.pid,
+            rootUri: pathToFileURL(this.outDir).href,
+            capabilities: {
+                textDocument: { diagnostic: {}, hover: { contentFormat: ['markdown', 'plaintext'] }, synchronization: {} },
+                workspace: { configuration: true, didChangeWatchedFiles: { dynamicRegistration: true } },
+            },
+        }).then(() => this.conn.notify('initialized', {}), () => { });
+    }
+    /** Brings the shadows in line with the pages' latest check units. */
+    async update(project, units) {
+        await this.ready;
+        const support = writeSupport({ root: this.root, outDir: this.outDir, types: project.types, openapi: project.openapi });
+        // a reloaded project may have new type names or spec declarations
+        if (this.support && JSON.stringify(support) !== JSON.stringify(this.support))
+            this.filesChanged([support.declarations, ...support.openapi]);
+        this.support = support;
+        for (const [page, unit] of units) {
+            const s = shadowOf(unit, support, this.root, project.helpers, project.actions);
+            const prev = this.shadows.get(page);
+            if (prev?.text === s.text) {
+                prev.unit = unit;
+                prev.regions = s.regions;
+                prev.brokenFrom = s.brokenFrom;
+                continue;
+            }
+            const path = shadowPath(support, this.root, page);
+            const uri = pathToFileURL(path).href;
+            const next = { unit, path, uri, text: s.text, lines: s.text.split('\n'), regions: s.regions, brokenFrom: s.brokenFrom, version: (prev?.version ?? 0) + 1 };
+            this.shadows.set(page, next);
+            if (prev) {
+                this.conn.notify('textDocument/didChange', { textDocument: { uri, version: next.version }, contentChanges: [{ text: s.text }] });
+            }
+            else {
+                // on disk too, so the tsconfig's `include` puts it in the project
+                mkdirSync(dirname(path), { recursive: true });
+                writeFileSync(path, s.text);
+                this.conn.notify('textDocument/didOpen', { textDocument: { uri, languageId: 'javascript', version: next.version, text: s.text } });
+            }
+        }
+        for (const [page, s] of this.shadows) {
+            if (units.has(page))
+                continue;
+            this.conn.notify('textDocument/didClose', { textDocument: { uri: s.uri } });
+            rmSync(s.path, { force: true });
+            this.shadows.delete(page);
+        }
+    }
+    /** TypeScript's errors in a page's expressions, at their HTML positions. */
+    async diagnostics(page) {
+        const s = this.shadows.get(page);
+        if (!s)
+            return [];
+        const report = await this.conn.request('textDocument/diagnostic', { textDocument: { uri: s.uri } });
+        const out = [];
+        for (const item of report?.items ?? []) {
+            // hints and suggestions (unused imports of the shadow itself) are not the page's business
+            if (item.severity !== 1)
+                continue;
+            const { start, end } = item.range;
+            // broken expressions are the compiler's to report
+            if (s.brokenFrom !== null && start.line + 1 >= s.brokenFrom)
+                continue;
+            const d = typeDiagnostic(s.unit, s.regions, start.line + 1, start.character + 1, `TS${item.code}`, item.message, this.root);
+            const a = mapPosition(s.regions, start.line + 1, start.character + 1);
+            const b = mapPosition(s.regions, end.line + 1, end.character + 1);
+            if (a && b && a.file === b.file && (b.line > a.line || (b.line === a.line && b.col > a.col))) {
+                d.span = { line: a.line, col: a.col, endLine: b.line, endCol: b.col };
+            }
+            out.push(d);
+        }
+        return out;
+    }
+    /** The page shadow and shadow position for a 1-based HTML position, if it is in an expression. */
+    locate(file, line, col) {
+        // the page itself first, then pages that include `file`
+        const order = [...this.shadows].sort(([a], [b]) => Number(b === file) - Number(a === file));
+        for (const [, s] of order) {
+            const p = shadowPosition(s.regions, s.lines, file, line, col);
+            if (p)
+                return { shadow: s, ...p };
+        }
+        return null;
+    }
+    /** Maps a shadow range back to the HTML; null when it is not inside one expression. */
+    toHtml(s, r, file) {
+        const a = mapPosition(s.regions, r.start.line + 1, r.start.character + 1);
+        const b = mapPosition(s.regions, r.end.line + 1, r.end.character + 1);
+        if (!a || !b || a.file !== file || b.file !== file)
+            return null;
+        return { start: { line: a.line - 1, character: a.col - 1 }, end: { line: b.line - 1, character: b.col - 1 } };
+    }
+    async hover(file, line, col) {
+        await this.ready;
+        const at = this.locate(file, line, col);
+        if (!at)
+            return null;
+        const h = await this.conn.request('textDocument/hover', {
+            textDocument: { uri: at.shadow.uri }, position: { line: at.line - 1, character: at.col - 1 },
+        });
+        if (!h)
+            return null;
+        const range = h.range ? this.toHtml(at.shadow, h.range, file) : null;
+        return range ? { contents: h.contents, range } : { contents: h.contents };
+    }
+    /** Completions at a 1-based HTML position inside an expression, with edits mapped to the HTML. */
+    async completion(file, line, col, context) {
+        await this.ready;
+        const at = this.locate(file, line, col);
+        if (!at)
+            return null;
+        const r = await this.conn.request('textDocument/completion', {
+            textDocument: { uri: at.shadow.uri }, position: { line: at.line - 1, character: at.col - 1 }, context,
+        });
+        if (!r)
+            return null;
+        const list = Array.isArray(r) ? r : r.items ?? [];
+        const items = [];
+        for (const item of list) {
+            // the shadow's own names, and auto-imports that would edit the shadow's header
+            if (INTERNAL.test(item.label) || item.additionalTextEdits?.length)
+                continue;
+            const edit = item.textEdit;
+            if (edit) {
+                const range = edit.range ?? edit.replace;
+                const mapped = range && this.toHtml(at.shadow, range, file);
+                if (mapped)
+                    item.textEdit = { range: mapped, newText: edit.newText };
+                else
+                    delete item.textEdit;
+            }
+            item.data = { sinter: this.root, ts: item.data ?? null, uri: at.shadow.uri };
+            items.push(item);
+        }
+        return { isIncomplete: Array.isArray(r) ? false : !!r.isIncomplete, items };
+    }
+    /** Details for a completion item this bridge returned (documentation, signature). */
+    async resolve(item) {
+        const ours = item.data;
+        const r = await this.conn.request('completionItem/resolve', { ...item, data: ours.ts, textEdit: undefined });
+        return { ...item, documentation: r?.documentation ?? item.documentation, detail: r?.detail ?? item.detail };
+    }
+    /**
+     * Definitions of the name at a 1-based HTML position: where the HTML declares it (resources,
+     * state, loop variables), the spec for types generated from OpenAPI, else TypeScript's own
+     * answer (helpers, the types module).
+     */
+    async definition(file, line, col, project) {
+        await this.ready;
+        const at = this.locate(file, line, col);
+        if (!at)
+            return [];
+        const r = await this.conn.request('textDocument/definition', {
+            textDocument: { uri: at.shadow.uri }, position: { line: at.line - 1, character: at.col - 1 },
+        });
+        const list = !r ? [] : Array.isArray(r) ? r : [r];
+        const out = [];
+        for (const d of list) {
+            const uri = d.targetUri ?? d.uri;
+            const range = d.targetSelectionRange ?? d.range;
+            if (!uri?.startsWith('file:') || !range)
+                continue;
+            const path = fileURLToPath(uri);
+            const shadow = [...this.shadows.values()].find((s) => s.path === path);
+            if (shadow) {
+                const loc = mapPosition(shadow.regions, range.start.line + 1, range.start.character + 1);
+                if (loc)
+                    out.push({ file: loc.file, line: loc.line, col: loc.col });
+                continue;
+            }
+            const spec = this.support?.openapi.indexOf(path) ?? -1;
+            if (spec >= 0) {
+                const text = readFileSync(path, 'utf8').split('\n')[range.start.line] ?? '';
+                const name = /^export (?:interface|type) ([\w$]+)/.exec(text)?.[1];
+                const ident = text.slice(range.start.character, range.end.character);
+                const specFile = project.openapi[spec]?.file;
+                const loc = name && specFile ? specLocation(specFile, name, ident !== name ? ident : undefined) : null;
+                if (loc && specFile)
+                    out.push({ file: specFile, ...loc });
+                continue;
+            }
+            // sinter's own declarations say nothing useful about the app
+            if (path === this.support?.declarations)
+                continue;
+            out.push({ file: path, line: range.start.line + 1, col: range.start.character + 1, endLine: range.end.line + 1, endCol: range.end.character + 1 });
+        }
+        return out;
+    }
+    /** Tells TypeScript that files it may have read changed on disk. */
+    filesChanged(files) {
+        if (!files.length)
+            return;
+        this.conn.notify('workspace/didChangeWatchedFiles', { changes: files.map((f) => ({ uri: pathToFileURL(f).href, type: 2 })) });
+    }
+    dispose() {
+        this.conn.close();
+        this.child.kill();
+    }
+}