@vesk/adapter 0.2.9 → 0.2.11

package/dist/client-bundle.d.ts

@@ -1,4 +1,33 @@
 import type { RouteNode, ClientBundleOptions, ClientBundleResult } from '@vesk/adapter/src/types';
+/**
+ * Pure name-collection used by `generateClientBundle`'s tree-shake request.
+ *
+ * Parses the (already compiled) client module with the compiler's AST pass and
+ * keeps only genuine top-level `import { … } from '@vesk/runtime…'` declarations.
+ * Import-shaped text inside template literals, strings, or comments — e.g. a
+ * doc code sample stored as `const md = \`import { VeskResponse } from
+ * '@vesk/runtime/server'\`` — never becomes an ImportDeclaration node, so those
+ * server-only names cannot poison the client runtime request. This is
+ * deliberately AST-only (no text scanning): text heuristics are what let
+ * server-only names leak into the client tree-shake request in the first
+ * place. If the compiled module ever fails to parse, we collect nothing rather
+ * than guess.
+ */
+export declare function extractRuntimeImportNames(code: string): string[];
+/**
+ * Builds the eval-safe HMR update snippet for one compiled file: drops
+ * imports, re-exports and the registry preamble (`const __components = …`,
+ * `const __hydrators = …`), demotes remaining value exports, and wraps the
+ * rest in a block. Component registrations (`__components["X"] = …`) still
+ * reach the live registries and stay visible to nothing else, file
+ * top-level bindings (`const navItems`, helpers, …) stay visible to the
+ * component closures that reference them, and repeated evals of the same
+ * file can no longer redeclare its top-level consts. Without the file
+ * scope, an updated component renders against missing bindings and the
+ * swap fails with a ReferenceError that surfaces nowhere the tests assert
+ * (no reload, stale DOM, zero page errors).
+ */
+export declare function buildHmrEvalSnippet(code: string): string;
 export declare function generateClientBundle(routeTree: RouteNode[], appDir: string, componentMap?: Map<string, string>, options?: ClientBundleOptions): Promise<ClientBundleResult>;
 export declare function buildRuntimeCode(runtimeDir: string): string;
 /**

package/dist/client-bundle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client-bundle.d.ts","sourceRoot":"","sources":["../src/client-bundle.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,SAAS,EAAE,mBAAmB,EAAE,kBAAkB,EAAqC,MAAM,yBAAyB,CAAC;AAoCrI,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,SAAS,EAAE,EACtB,MAAM,EAAE,MAAM,EACd,YAAY,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAClC,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,kBAAkB,CAAC,CAoT7B;AAMD,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CA+B3D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAUlE;AAID;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA+BrG"}
+{"version":3,"file":"client-bundle.d.ts","sourceRoot":"","sources":["../src/client-bundle.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,SAAS,EAAE,mBAAmB,EAAE,kBAAkB,EAAqC,MAAM,yBAAyB,CAAC;AAoCrI;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CA8BhE;AAoLD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAkBxD;AAmCD,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,SAAS,EAAE,EACtB,MAAM,EAAE,MAAM,EACd,YAAY,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAClC,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,kBAAkB,CAAC,CA0S7B;AAMD,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CA+B3D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAUlE;AAYD;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAuCrG"}

package/dist/client-bundle.js

@@ -1,8 +1,9 @@
-import { readFileSync, existsSync, writeFileSync, unlinkSync, statSync } from 'node:fs';
+import { readFileSync, existsSync, writeFileSync, unlinkSync, statSync, rmSync } from 'node:fs';
 import { resolve, join, dirname, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { build } from './esbuild-fallback.js';
 import { stripCodeTypes } from '@vesk/compiler/src/strip-ts';
+import { parse } from '@vesk/compiler/src/parser';
 import { compileClient, compileClientBoth } from '@vesk/compiler/src/client-codegen';
 import { resolveComponentName } from '@vesk/compiler/src/server-codegen';
 import { collectVskImportPaths, vskImportLines } from '@vesk/compiler/src/vsk-imports';
@@ -39,6 +40,276 @@ function findRuntimeSrc(appDir) {
     }
     throw new Error('@vesk/runtime/dist not found — run "npm run build" first');
 }
+/**
+ * Pure name-collection used by `generateClientBundle`'s tree-shake request.
+ *
+ * Parses the (already compiled) client module with the compiler's AST pass and
+ * keeps only genuine top-level `import { … } from '@vesk/runtime…'` declarations.
+ * Import-shaped text inside template literals, strings, or comments — e.g. a
+ * doc code sample stored as `const md = \`import { VeskResponse } from
+ * '@vesk/runtime/server'\`` — never becomes an ImportDeclaration node, so those
+ * server-only names cannot poison the client runtime request. This is
+ * deliberately AST-only (no text scanning): text heuristics are what let
+ * server-only names leak into the client tree-shake request in the first
+ * place. If the compiled module ever fails to parse, we collect nothing rather
+ * than guess.
+ */
+export function extractRuntimeImportNames(code) {
+    const names = [];
+    let ast;
+    try {
+        ast = parse(code);
+    }
+    catch {
+        return names;
+    }
+    const body = ast.body ?? [];
+    for (const raw of body) {
+        const node = raw;
+        if (node.type !== 'ImportDeclaration')
+            continue;
+        const src = node.source?.value;
+        if (typeof src !== 'string' || !(src === '@vesk/runtime' || src.startsWith('@vesk/runtime/')))
+            continue;
+        if (node.importKind === 'type')
+            continue;
+        for (const spec of node.specifiers ?? []) {
+            const name = spec.type === 'ImportSpecifier' ? spec.imported?.name : spec.local?.name;
+            if (name)
+                names.push(name);
+        }
+    }
+    return names;
+}
+function isRuntimeImport(node) {
+    if (node.type !== 'ImportDeclaration')
+        return false;
+    const src = node.source?.value;
+    return src === '@vesk/runtime' || (typeof src === 'string' && src.startsWith('@vesk/runtime/'));
+}
+function isVskImport(node) {
+    if (node.type !== 'ImportDeclaration')
+        return false;
+    const src = node.source?.value;
+    return typeof src === 'string' && src.endsWith('.vsk');
+}
+function isAnyImport(node) {
+    return node.type === 'ImportDeclaration';
+}
+/**
+ * Generated client-preamble nodes the bundle must not re-emit: the local
+ * `const __components = {}` registry plus the `__cleanup` / `__place` helpers —
+ * the chunk IIFEs already define their own `__components`, so a second
+ * declaration in the same scope would be a syntax error.
+ */
+function isRuntimePreamble(node) {
+    if (node.type === 'FunctionDeclaration' && (node.id?.name === '__cleanup' || node.id?.name === '__place')) {
+        return true;
+    }
+    if (node.type === 'VariableDeclaration') {
+        return node.declarations?.[0]?.id?.name === '__components';
+    }
+    return false;
+}
+/**
+ * `export default __components[<name>];` / `export const <name> = __components[<name>];`
+ * aliases emitted by codegen. The bundle registers components on `__components`
+ * directly, so these module-level re-exports must go.
+ */
+function isComponentExport(node) {
+    if (node.type === 'ExportDefaultDeclaration') {
+        const d = node.declaration;
+        return !!d && d.type === 'MemberExpression' && d.object?.type === 'Identifier' && d.object.name === '__components';
+    }
+    if (node.type === 'ExportNamedDeclaration') {
+        const init = node.declaration?.type === 'VariableDeclaration' ? node.declaration.declarations?.[0]?.init : undefined;
+        return !!init && init.type === 'MemberExpression' && init.object?.type === 'Identifier' && init.object.name === '__components';
+    }
+    return false;
+}
+/**
+ * Extracts matched top-level statements from a compiled client module using
+ * the parser's exact `start`/`end` offsets — the complement of
+ * `removeCompiledNodes`. AST-only, like everything else in this file.
+ */
+function extractCompiledNodes(code, isTarget) {
+    let ast;
+    try {
+        ast = parse(code);
+    }
+    catch {
+        return '';
+    }
+    const parts = [];
+    for (const raw of ast.body ?? []) {
+        const node = raw;
+        if (isTarget(node) && typeof node.start === 'number' && typeof node.end === 'number') {
+            let cut = node.end;
+            if (code[cut] === ';')
+                cut++;
+            parts.push(code.slice(node.start, cut));
+        }
+    }
+    return parts.join('\n');
+}
+function isModuleLevel(node) {
+    // import/export statements must stay at module top level (hoisted imports
+    // of the same module are harmless duplicates); everything else is scoped.
+    return node.type === 'ImportDeclaration'
+        || node.type === 'ExportNamedDeclaration'
+        || node.type === 'ExportDefaultDeclaration';
+}
+/**
+ * Demotes surviving value exports to plain declarations (`export const x`
+ * becomes `const x`) and drops bare re-export lists (`export { x }`,
+ * `export default …`). Code-split chunks execute as classic scripts inside
+ * an IIFE, so any `export` statement is a SyntaxError — and the chunk-local
+ * binding is all cross-file references need (components resolve through the
+ * `__components` / `__hydrators` registries). Offset-based on the parser AST.
+ */
+function demoteExports(code) {
+    let ast;
+    try {
+        ast = parse(code);
+    }
+    catch {
+        return code;
+    }
+    const body = ast.body ?? [];
+    const edits = [];
+    for (const raw of body) {
+        const node = raw;
+        if (typeof node.start !== 'number' || typeof node.end !== 'number')
+            continue;
+        if (node.type === 'ExportNamedDeclaration' && node.declaration
+            && typeof node.declaration.start === 'number' && typeof node.declaration.end === 'number') {
+            edits.push({ start: node.start, end: node.end, text: code.slice(node.declaration.start, node.declaration.end) });
+        }
+        else if (node.type === 'ExportNamedDeclaration' || node.type === 'ExportDefaultDeclaration') {
+            let cut = node.end;
+            if (code[cut] === ';')
+                cut++;
+            edits.push({ start: node.start, end: cut, text: '' });
+        }
+    }
+    edits.sort((a, b) => b.start - a.start);
+    for (const e of edits)
+        code = code.slice(0, e.start) + e.text + code.slice(e.end);
+    return code;
+}
+/**
+ * Code-split chunks execute as classic scripts, so NO import statement may
+ * survive in a contribution (runtime and `.vsk` imports are stripped
+ * earlier; npm packages and relative `.ts` values are unresolvable from a
+ * `/_vesk/static/` classic script). Strips every remaining import and
+ * demotes value exports — server-only components never execute
+ * client-side, and islands must receive data through props/serialization
+ * rather than module imports (a stripped binding referenced by an island
+ * fails loudly at that island instead of killing the whole chunk).
+ */
+function stripChunkImports(code) {
+    return demoteExports(removeCompiledNodes(code, isAnyImport));
+}
+/**
+ * Scopes one file's contribution to the shared chunk: module-level
+ * import/export statements pass through untouched, all other top-level
+ * statements (component registrations, top-level `const` helpers, …) are
+ * wrapped in a block. Without this, same-named top-level bindings from
+ * different `.vsk` files (e.g. two files declaring `const stages`) collide
+ * in the concatenated chunk scope and the whole chunk fails to parse —
+ * killing hydration for the entire page. Cross-file references always go
+ * through the `__components` / `__hydrators` registries (never bare
+ * identifiers), so hiding file locals in a block is safe; assignments like
+ * `__components["X"] = …` still reach the outer binding.
+ */
+function scopeFileContribution(code) {
+    const head = extractCompiledNodes(code, isModuleLevel);
+    const rest = removeCompiledNodes(code, isModuleLevel);
+    if (!rest.trim())
+        return head;
+    const scoped = (head ? head + '\n' : '') + '{\n' + rest + '\n}';
+    // Never trade a potential duplicate-binding error for a certain syntax
+    // error: if the scoped form does not parse, keep the original.
+    try {
+        parse(scoped);
+        return scoped;
+    }
+    catch {
+        return code;
+    }
+}
+/**
+ * Builds the eval-safe HMR update snippet for one compiled file: drops
+ * imports, re-exports and the registry preamble (`const __components = …`,
+ * `const __hydrators = …`), demotes remaining value exports, and wraps the
+ * rest in a block. Component registrations (`__components["X"] = …`) still
+ * reach the live registries and stay visible to nothing else, file
+ * top-level bindings (`const navItems`, helpers, …) stay visible to the
+ * component closures that reference them, and repeated evals of the same
+ * file can no longer redeclare its top-level consts. Without the file
+ * scope, an updated component renders against missing bindings and the
+ * swap fails with a ReferenceError that surfaces nowhere the tests assert
+ * (no reload, stale DOM, zero page errors).
+ */
+export function buildHmrEvalSnippet(code) {
+    const isSnippetDrop = (node) => {
+        if (isAnyImport(node) || isComponentExport(node) || isRuntimePreamble(node))
+            return true;
+        return node.type === 'VariableDeclaration'
+            && (node.declarations?.[0]?.id?.name === '__components'
+                || node.declarations?.[0]?.id?.name === '__hydrators');
+    };
+    const body = demoteExports(removeCompiledNodes(code, isSnippetDrop)).trim();
+    if (!body)
+        return '';
+    const scoped = `{\n${body}\n}`;
+    // Never trade a potential duplicate-binding error for a certain syntax
+    // error: if the scoped form does not parse, keep the unscoped body.
+    try {
+        parse(scoped);
+        return scoped;
+    }
+    catch {
+        return body;
+    }
+}
+/**
+ * Removes matched top-level statements from a compiled client module using the
+ * parser's exact `start`/`end` offsets — never a text scan, so a doc sample
+ * stored inside a template literal can never be mistaken for a real statement.
+ * If the module cannot be parsed it is returned untouched (the compiler's own
+ * output is always valid ESM, so that branch is unreachable in practice).
+ */
+function removeCompiledNodes(code, isTarget) {
+    let ast;
+    try {
+        ast = parse(code);
+    }
+    catch {
+        return code;
+    }
+    const ranges = [];
+    for (const raw of ast.body ?? []) {
+        const node = raw;
+        if (isTarget(node) && typeof node.start === 'number' && typeof node.end === 'number') {
+            ranges.push([node.start, node.end]);
+        }
+    }
+    if (ranges.length === 0)
+        return code;
+    ranges.sort((a, b) => b[0] - a[0]);
+    for (const [start, end] of ranges) {
+        let cut = end;
+        if (code[cut] === ';')
+            cut++;
+        if (code.startsWith('\r\n', cut))
+            cut += 2;
+        else if (code[cut] === '\n' || code[cut] === '\r')
+            cut++;
+        code = code.slice(0, start) + code.slice(cut);
+    }
+    return code;
+}
 export async function generateClientBundle(routeTree, appDir, componentMap, options) {
     const runtimeDir = findRuntimeSrc(appDir);
     const seen = new Set();
@@ -55,27 +326,22 @@ export async function generateClientBundle(routeTree, appDir, componentMap, opti
     function mustReuseWithoutStat(filePath) {
         return !!only && !only.has(filePath);
     }
+    /**
+     * Collects the runtime names a module genuinely imports from `@vesk/runtime*`
+     * (see `extractRuntimeImportNames`). Deliberately AST-only — import-shaped
+     * text inside template literals (e.g. a doc sample `const md = \`import {
+     * VeskResponse } from '@vesk/runtime/server'\``) must NOT force a client
+     * tree-shake request for a server-only name.
+     */
     function collectRuntimeImports(code) {
-        // matches bare '@vesk/runtime' and any of its subpaths
-        // ('@vesk/runtime/router', '@vesk/runtime/server', …)
-        const re = /^import\s*\{([^}]*)\}\s*from\s*['"]@vesk\/runtime(\/[a-zA-Z0-9-]+)*['"];?\s*\n?/gm;
-        for (const m of code.matchAll(re)) {
-            for (const name of m[1].split(',')) {
-                const trimmed = name.trim().replace(/^(\w+)\s+as\s+.*$/, '$1');
-                if (!trimmed || /^(type|typeof)\s/.test(trimmed))
-                    continue;
-                runtimeImportNames.add(trimmed);
-            }
-        }
+        for (const name of extractRuntimeImportNames(code))
+            runtimeImportNames.add(name);
     }
     function stripRuntimeImport(code) {
-        return code.replace(/^import\s*\{[^}]*\}\s*from\s*['"]@vesk\/runtime(\/[a-zA-Z0-9-]+)*['"];?\s*\n?/gm, '')
-            .replace(/const\s+__components\s*=\s*\{\};\s*\n?/g, '')
-            .replace(/^function __cleanup\(start, end\) \{[\s\S]*?\n\}\s*\n?/gm, '')
-            .replace(/^function __place\(start, end, nodes, fallback\) \{[\s\S]*?\n\}\s*\n?/gm, '');
+        return removeCompiledNodes(code, (node) => isRuntimeImport(node) || isRuntimePreamble(node));
     }
     function stripVskImports(code) {
-        return code.replace(/^import\s*\{[^}]*\}\s*from\s*['"][^'"]*\.vsk['"];?\s*\n?/gm, '');
+        return removeCompiledNodes(code, isVskImport);
     }
     function resolveVskImports(filePath, compile) {
         const src = readFileSync(filePath, 'utf-8');
@@ -97,9 +363,7 @@ export async function generateClientBundle(routeTree, appDir, componentMap, opti
         return resolved;
     }
     function stripExports(code) {
-        return code
-            .replace(/^export\s+default\s+__components\[.*?\];?\s*\n?/gm, '')
-            .replace(/^export\s+(const|let|var)\s+\w+\s*=\s*__components\[.*?\];?\s*\n?/gm, '');
+        return removeCompiledNodes(code, isComponentExport);
     }
     function compileFile(filePath, resolvedName, output) {
         if (seen.has(filePath))
@@ -127,10 +391,12 @@ export async function generateClientBundle(routeTree, appDir, componentMap, opti
             cachedFileHits++;
             for (const dep of cached.imports)
                 compileFile(dep, cache?.files.get(dep)?.actualName ?? '', output);
-            if (cached.compCode)
-                output.push(cached.compCode);
-            if (cached.hydCode)
-                output.push(cached.hydCode);
+            // Comp and hyd contributions of one file share its top-level bindings
+            // (e.g. `const links` used by both the component and its hydrator),
+            // so they must be scoped together in a single block.
+            const cachedFileCode = [cached.compCode, cached.hydCode].filter(Boolean).join('\n');
+            if (cachedFileCode.trim())
+                output.push(scopeFileContribution(cachedFileCode));
             for (const n of cached.runtimeNames)
                 runtimeImportNames.add(n);
             if (cached.actualName && resolvedName !== null && cached.actualName !== resolvedName) {
@@ -149,28 +415,26 @@ export async function generateClientBundle(routeTree, appDir, componentMap, opti
         // One parse/IR pass feeds both client modes AND the component-name
         // lookup — the dev hot path pays the acorn+TS parse once per edit
         // instead of three times.
-        const { comp: rawComp, hyd: rawHyd, name: actualName } = compileClientBoth(src, null);
-        const compCode = rawComp ? stripExports(stripVskImports(stripRuntimeImport(rawComp))).replace(/^\n+/, '').replace(/\n+$/, '') : '';
-        const hydCode = rawHyd ? stripExports(stripVskImports(stripRuntimeImport(rawHyd))).replace(/__components/g, '__hydrators').replace(/^\n+/, '').replace(/\n+$/, '') : '';
+        const { comp: rawComp, hyd: rawHyd, name: actualName } = compileClientBoth(src, null, filePath);
+        const compCode = rawComp ? stripChunkImports(stripExports(stripVskImports(stripRuntimeImport(rawComp)))).replace(/^\n+/, '').replace(/\n+$/, '') : '';
+        const hydCode = rawHyd ? stripChunkImports(stripExports(stripVskImports(stripRuntimeImport(rawHyd)))).replace(/__components/g, '__hydrators').replace(/^\n+/, '').replace(/\n+$/, '') : '';
         if (rawComp)
             collectRuntimeImports(rawComp);
         if (rawHyd)
             collectRuntimeImports(rawHyd);
         if (returnEdited && only.has(filePath)) {
-            // Mirrors the HMR fnSources preparation in the dev servers: drop every
-            // remaining top-level import so the snippet can be eval'd in the page
-            // context where runtime globals already exist.
-            const bare = rawComp
-                ? stripExports(stripVskImports(stripRuntimeImport(rawComp)))
-                    .replace(/^import\s*[\s\S]*?from\s*['"][^'"]+['"];?\s*\n?/gm, '')
-                : '';
-            editedSources.set(filePath, bare);
+            // Eval-safe snippet for HMR fnSources (see buildHmrEvalSnippet):
+            // full file scope so component closures keep their top-level
+            // bindings, without imports/exports or the registry preamble, and
+            // block-wrapped so repeated evals cannot redeclare them.
+            editedSources.set(filePath, rawComp ? buildHmrEvalSnippet(rawComp) : '');
             editedNames.set(filePath, actualName);
         }
-        if (compCode)
-            output.push(compCode);
-        if (hydCode)
-            output.push(hydCode);
+        // Comp and hyd contributions of one file share its top-level bindings,
+        // so they are scoped together in a single block (see replay path above).
+        const fileCode = [compCode, hydCode].filter(Boolean).join('\n');
+        if (fileCode.trim())
+            output.push(scopeFileContribution(fileCode));
         if (actualName && resolvedName !== null && actualName !== resolvedName) {
             output.push(`Object.defineProperty(__components, ${JSON.stringify(resolvedName)}, { get: () => __components[${JSON.stringify(actualName)}], configurable: true });`);
             output.push(`Object.defineProperty(__hydrators, ${JSON.stringify(resolvedName)}, { get: () => __hydrators[${JSON.stringify(actualName)}], configurable: true });`);
@@ -286,19 +550,18 @@ export async function generateClientBundle(routeTree, appDir, componentMap, opti
             seen.add(filePath);
             const src = readFileSync(filePath, 'utf-8');
             resolveVskImports(filePath, (p, n) => compileFileMono(p, n || ''));
-            const compCode = compileClient(src, null, { forceClient: true });
-            if (compCode) {
+            const compCode = compileClient(src, null, { forceClient: true, sourcePath: filePath });
+            const hydCode = compileClient(src, null, { hydrate: true, forceClient: true, includeTopLevel: false, sourcePath: filePath });
+            if (compCode)
                 collectRuntimeImports(compCode);
-                const stripped = stripExports(stripVskImports(stripRuntimeImport(compCode)));
-                componentLines.push(stripped.replace(/^\n+/, '').replace(/\n+$/, ''));
-            }
-            const hydCode = compileClient(src, null, { hydrate: true, forceClient: true, includeTopLevel: false });
-            if (hydCode) {
+            if (hydCode)
                 collectRuntimeImports(hydCode);
-                const stripped = stripExports(stripVskImports(stripRuntimeImport(hydCode)))
-                    .replace(/__components/g, '__hydrators');
-                hydratorLines.push(stripped.replace(/^\n+/, '').replace(/\n+$/, ''));
-            }
+            // Comp and hyd share the file's top-level bindings — scope together.
+            const strippedComp = compCode ? stripExports(stripVskImports(stripRuntimeImport(compCode))).replace(/^\n+/, '').replace(/\n+$/, '') : '';
+            const strippedHyd = hydCode ? stripExports(stripVskImports(stripRuntimeImport(hydCode))).replace(/__components/g, '__hydrators').replace(/^\n+/, '').replace(/\n+$/, '') : '';
+            const fileCode = [strippedComp, strippedHyd].filter(Boolean).join('\n');
+            if (fileCode.trim())
+                componentLines.push(scopeFileContribution(fileCode));
             const actualName = resolveComponentName(src);
             if (actualName && actualName !== resolvedName) {
                 aliasLines.push(`Object.defineProperty(__components, ${JSON.stringify(resolvedName)}, { get: () => __components[${JSON.stringify(actualName)}], configurable: true });`);
@@ -395,6 +658,13 @@ export function runtimeExportNames(runtimeDir) {
     return names;
 }
 let runtimeEntryId = 0;
+/**
+ * Fixed entry filename for the runtime tree-shake. A stable entry path keeps
+ * esbuild's banner comment constant, so the output is deterministic across
+ * builds (a per-call unique filename would embed a new path into the bundle
+ * every time).
+ */
+const RUNTIME_ENTRY = '.runtime-tree-entry.mjs';
 /**
  * Builds a single self-contained runtime module for the given used names.
  *
@@ -412,8 +682,12 @@ export async function buildTreeShakenRuntime(runtimeDir, usedNames) {
         console.error(`vesk: runtime names not exported — ${missing.join(', ')}; falling back to full runtime`);
         return buildRuntimeCode(runtimeDir);
     }
-    const entry = join(runtimeDir, `.runtime-tree-entry-${runtimeEntryId++}.mjs`);
+    const entry = join(runtimeDir, RUNTIME_ENTRY);
     try {
+        try {
+            rmSync(entry);
+        }
+        catch { /* not present yet */ }
         writeFileSync(entry, `export { ${unique.join(', ')} } from './index-client.js';\n`);
         const result = await build({
             entryPoints: [entry],
@@ -423,7 +697,14 @@ export async function buildTreeShakenRuntime(runtimeDir, usedNames) {
             platform: 'browser',
             target: ['es2022'],
             treeShaking: true,
-            minify: true,
+            // Do not let esbuild rename identifiers here. This bundle is one large
+            // IIFE built from many runtime modules, and the renaming pass of some
+            // esbuild versions (observed on 0.25.12) emits a free reference to an
+            // undefined minified name (ReferenceError: m is not defined) that kills
+            // client hydration for the whole app. Whitespace-only output keeps the
+            // runtime deterministic at a modest size cost; tree-shaking still prunes
+            // unreachable modules, so names coming out of the IIFE are untouched.
+            minify: false,
             write: false,
             logLevel: 'silent',
         });

package/dist/dev-api.d.ts

@@ -0,0 +1,78 @@
+import type { DevHmrState } from './dev-server';
+import type { PluginRouterChangeEvent } from './dev-server';
+export interface DiagnosticFinding {
+    severity: 'error' | 'warning' | 'info';
+    code: string;
+    file?: string | null;
+    line?: number | null;
+    column?: number | null;
+    message: string;
+    hint?: string | null;
+}
+export type CapabilityName = 'config.read' | 'config.write' | 'plugins' | 'diagnostics' | 'build' | 'file.read' | 'command';
+export type DevApiCapabilities = Record<CapabilityName, boolean>;
+/** Default DevTools capability set — `command` is gated off by default. */
+export declare const DEFAULT_CAPABILITIES: DevApiCapabilities;
+/** Gated-command allowlist (read-only/status commands only by default). */
+export declare const DEFAULT_COMMAND_ALLOWLIST: RegExp[];
+/** Server-enforced capability/permission table. */
+export declare class CapabilityTable {
+    private caps;
+    private commandAllowlist;
+    constructor(caps?: Partial<DevApiCapabilities>, commandAllowlist?: RegExp[]);
+    allows(cap: CapabilityName): boolean;
+    commandAllowed(argv: string[]): boolean;
+}
+export interface DevPanelResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+    encoding?: 'utf8' | 'base64';
+    /** When set, `body`/`encoding` are ignored and this async iterable of
+        (already-framed) strings is streamed to the client instead — used for
+        SSE agent progress. */
+    stream?: AsyncIterable<string>;
+}
+export interface RebuildResult {
+    ok: boolean;
+    error?: string;
+    ms?: number;
+}
+export interface CommandResult {
+    ok: boolean;
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export interface DevApiRouterOptions {
+    /** Directory containing app/ (parent of projectDir when config is at project root). */
+    appDir: string;
+    /** The `.vesk` state dir. */
+    veskDir: string;
+    /** Plugin names declared in config. */
+    configPluginNames: string[];
+    getHmrState?: () => DevHmrState;
+    onPluginChange?: (event: PluginRouterChangeEvent) => void | Promise<void>;
+    /** Capability overrides; `command` is off unless enabled + allowlisted. */
+    caps?: Partial<DevApiCapabilities>;
+    commandAllowlist?: RegExp[];
+    /** Dir where vesk.config.{ts,js} lives (defaults to dirname(appDir)). */
+    projectDir?: string;
+    /** Trigger a full rebuild + HMR reload (POST /__vesk/build). */
+    rebuild?: () => Promise<RebuildResult>;
+    /** Live diagnostics snapshot (GET /__vesk/diagnostics). */
+    getDiagnostics?: () => DiagnosticFinding[];
+    /** Gated command executor (POST /__vesk/command). */
+    runCommand?: (argv: string[]) => Promise<CommandResult>;
+    /** Response body cap. */
+    maxBodyBytes?: number;
+}
+export interface DevApiRouter {
+    route: (method: string, pathname: string, body?: unknown, search?: string) => Promise<DevPanelResponse | null>;
+}
+/**
+ * Build the unified DevTools API router. Exportable and dependency-injectable
+ * so the adapter + CLI dev servers can both route through it.
+ */
+export declare function createDevApiRouter(opts: DevApiRouterOptions): DevApiRouter;
+//# sourceMappingURL=dev-api.d.ts.map

package/dist/dev-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-api.d.ts","sourceRoot":"","sources":["../src/dev-api.ts"],"names":[],"mappings":"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"}