@vesk/compiler 0.2.50-canary.9 → 0.2.50

package/dist/abuse-checks.d.ts

@@ -0,0 +1,7 @@
+import { type ComponentIR } from '@vesk/compiler/src/ir';
+/**
+ * Run the abuse checks for one component. Called after its body is built, so
+ * the tracked names are known.
+ */
+export declare function validateAbuse(comp: ComponentIR, file?: string, source?: string): void;
+//# sourceMappingURL=abuse-checks.d.ts.map

package/dist/abuse-checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abuse-checks.d.ts","sourceRoot":"","sources":["../src/abuse-checks.ts"],"names":[],"mappings":"AA6BA,OAAO,EAQL,KAAK,WAAW,EACjB,MAAM,uBAAuB,CAAC;AAsS/B;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAMrF"}

package/dist/abuse-checks.js

@@ -0,0 +1,315 @@
+import { walk } from 'zimmerframe';
+import { ClientBlock, DynamicBinding, OpaqueDynamicRegion, RuntimeStatement, ServerBlock, TrackDecl, StaticNode, } from '@vesk/compiler/src/ir';
+import { VeskError, codeFrame } from '@vesk/compiler/src/errors';
+/** Offset -> 1-based line/column, for a code frame in a diagnostic. */
+function offsetToLineCol(source, offset) {
+    let line = 1;
+    let lineStart = 0;
+    for (let i = 0; i < offset && i < source.length; i++) {
+        if (source[i] === '\n') {
+            line++;
+            lineStart = i + 1;
+        }
+    }
+    return { line, column: offset - lineStart + 1 };
+}
+/**
+ * Browser-only globals, with what to reach for instead. `navigator` and
+ * `location` are the dangerous ones: they do not throw on the server, they
+ * return undefined and the page renders wrong.
+ */
+/**
+ * READS only. A bare read of one of these at statement level is unambiguous:
+ * it executes during SSR, either throwing (`window`) or silently returning the
+ * wrong thing (`navigator` exists in modern Node, so `navigator.onLine` renders
+ * as offline). Calls are NOT in this list: `setInterval`/`addEventListener`
+ * inside an effect or a hoisted statement are indistinguishable from a body
+ * statement at this point in the walk, and a diagnostic that fires on correct
+ * code is worse than none. Timer/listener misuse is a documented follow-up.
+ */
+const SSR_UNSAFE = {
+    window: 'the DOM',
+    document: 'the DOM',
+    localStorage: 'storage',
+    sessionStorage: 'storage',
+    navigator: 'the Network Information API (see getNetworkState)',
+    location: 'routing (see usePathname)',
+    history: 'routing (see useNavigate)',
+    matchMedia: 'a CSS media query',
+};
+function at(node, ctx) {
+    const opts = { inComponent: ctx.compName };
+    if (ctx.file)
+        opts.file = ctx.file;
+    if (ctx.source && typeof node.start === 'number') {
+        const { line, column } = offsetToLineCol(ctx.source, node.start);
+        opts.line = line;
+        opts.column = column;
+        opts.frame = codeFrame(ctx.source, line, column);
+    }
+    return opts;
+}
+/** Walk an expression, reporting SSR-unsafe globals and cell misuse. */
+/** Calls whose bodies are emitted on the client only, so the DOM is legal there. */
+const CLIENT_ONLY_CALLS = new Set(['on_destroy', 'effect', 'pre_effect', 'user_effect']);
+/**
+ * The global named by a `typeof x !== 'undefined'` / `=== 'undefined'` test, or
+ * null. `&&` / `||` short-circuit, so the other side of the expression only runs
+ * when the global exists.
+ */
+function typeofGlobalIn(node) {
+    const isTypeofOf = (n) => n && n.type === 'UnaryExpression' && n.operator === 'typeof' && n.argument?.type === 'Identifier'
+        ? String(n.argument.name)
+        : null;
+    if (!node)
+        return null;
+    const pair = (a, b) => {
+        const fromA = isTypeofOf(a);
+        if (fromA && b?.type === 'BinaryExpression' && b.operator === '!==')
+            return fromA;
+        const fromB = isTypeofOf(b);
+        if (fromB && a?.type === 'BinaryExpression' && a.operator === '!==')
+            return fromB;
+        return null;
+    };
+    if (node.type === 'LogicalExpression')
+        return pair(node.left, node.right);
+    if (node.type === 'ConditionalExpression') {
+        return pair(node.test, node.consequent) ?? pair(node.test, node.alternate);
+    }
+    return null;
+}
+/**
+ * The global a subexpression tests for existence with `typeof`, whether the test
+ * stands alone (`typeof x !== 'undefined'`), guards an `&&` chain, or selects a
+ * conditional branch. Anything evaluated only when that test passed may read the
+ * global safely.
+ */
+function guardNameOf(node) {
+    if (!node)
+        return null;
+    const direct = typeofGlobalIn(node);
+    if (direct)
+        return direct;
+    if (node.type === 'LogicalExpression')
+        return guardNameOf(node.left);
+    return null;
+}
+/**
+ * Does this statement set up a client-only lifecycle call anywhere?
+ *
+ * `effect(() => { const h = setInterval(…); on_destroy(() => clearInterval(h)) })`
+ * can arrive as ONE hoisted statement, so a statement that mentions a
+ * client-only call is treated as client-only. That errs toward silence rather
+ * than a false positive, which is the right direction for a new diagnostic.
+ */
+function mentionsClientOnlyCall(ast) {
+    if (!ast)
+        return false;
+    let found = false;
+    try {
+        walk(ast, null, {
+            CallExpression(node) {
+                const callee = node.callee;
+                if (callee && callee.type === 'Identifier' && CLIENT_ONLY_CALLS.has(String(callee.name))) {
+                    found = true;
+                    return;
+                }
+                return;
+            },
+        });
+    }
+    catch {
+        return false;
+    }
+    return found;
+}
+function checkExpression(ast, ctx, insideHandler) {
+    if (!ast)
+        return;
+    walk(ast, null, {
+        ConditionalExpression(node, context) {
+            // `test ? a : typeof x !== 'undefined' && x.use()` — the chosen branch is
+            // guarded, so a read of that global there is safe.
+            const guarded = guardNameOf(node.alternate) ?? guardNameOf(node.consequent);
+            if (!guarded)
+                return context.next();
+            ctx.guardedGlobals = new Set([...(ctx.guardedGlobals || []), guarded]);
+            return context.next();
+        },
+        LogicalExpression(node, context) {
+            // `typeof document !== 'undefined' && !!document.querySelector(…)` is the
+            // standard client-only guard, and the right side never evaluates on the
+            // server. Honour the short-circuit instead of flagging correct code (the
+            // docs app's error boundary uses exactly this shape).
+            const guarded = guardNameOf(node.left);
+            if (guarded) {
+                ctx.guardedGlobals = new Set([...(ctx.guardedGlobals || []), guarded]);
+                return context.next();
+            }
+            return context.next();
+        },
+        UnaryExpression(node, context) {
+            // `typeof window !== 'undefined'` is the CORRECT guard for a client-only
+            // value — the test-app's own broken-component fixture uses it. A `typeof`
+            // test never reads the value, so it must not be flagged.
+            if (node.operator === 'typeof')
+                return;
+            return context.next();
+        },
+        ArrowFunctionExpression(node, context) {
+            // A function body runs when it is CALLED, not when the render creates it.
+            // `const probe = () => document.querySelector(…)` called from a handler is
+            // correct code, so the walk stops here.
+            return;
+        },
+        FunctionExpression(node, context) {
+            return;
+        },
+        Identifier(node, context) {
+            if ((ctx.clientOnlyDepth || 0) > 0)
+                return context.next();
+            const parent = context.path.at(-1);
+            // A member's PROPERTY is a name, not a global: `foo.window` is fine.
+            if (parent && parent.type === 'MemberExpression' && parent.property === node && !parent.computed)
+                return context.next();
+            if (parent && parent.type === 'Property' && parent.key === node && !parent.computed && !parent.shorthand)
+                return context.next();
+            const name = String(node.name);
+            if (insideHandler)
+                return context.next();
+            if (ctx.guardedGlobals?.has(name))
+                return context.next();
+            if (name in SSR_UNSAFE) {
+                throw VeskError.ssrUnsafeGlobal(name, at(node, ctx));
+            }
+            return context.next();
+        },
+        CallExpression(node, context) {
+            const callee = node.callee;
+            // Depth is carried on the context object, not a module global: a global is
+            // never decremented, so one on_destroy call would silently disable every
+            // later check in the file.
+            const insideClientOnly = (ctx.clientOnlyDepth || 0) > 0;
+            if (callee && callee.type === 'Identifier') {
+                const name = String(callee.name);
+                if (insideHandler || insideClientOnly)
+                    return context.next();
+                // on_destroy/effect bodies are emitted on the client only, so anything
+                // they touch is legal — and `context.skip()` keeps the walk out.
+                if (CLIENT_ONLY_CALLS.has(name)) {
+                    ctx.clientOnlyDepth = (ctx.clientOnlyDepth || 0) + 1;
+                    context.next();
+                    ctx.clientOnlyDepth -= 1;
+                    return;
+                }
+                if (name in SSR_UNSAFE)
+                    throw VeskError.ssrUnsafeGlobal(name, at(callee, ctx));
+            }
+            // Anything else (a nested arrow, a call argument) is still evaluated on
+            // the server when it runs in the body — unless we are inside a
+            // client-only call.
+            if (!insideHandler && !insideClientOnly)
+                checkExpression(callee ?? null, ctx, false);
+            return context.next();
+        },
+    });
+}
+/** The nodes whose expressions the server evaluates. */
+function checkNode(node, ctx, insideHandler = false) {
+    if (!node || typeof node !== 'object')
+        return;
+    // Guarded globals are scoped to one top-level statement.
+    if (insideHandler === false && node instanceof RuntimeStatement)
+        ctx.guardedGlobals = new Set();
+    // `{#client}` never runs on the server; `{#server}` DOES (that is its whole
+    // purpose), so it is checked like any other body position.
+    if (node instanceof ClientBlock)
+        return;
+    if (node instanceof ServerBlock) {
+        for (const child of (node.children
+            || node.body
+            || [])) {
+            checkNode(child, ctx);
+        }
+        return;
+    }
+    if (node instanceof RuntimeStatement) {
+        if (!insideHandler && !mentionsClientOnlyCall(node.ast))
+            checkExpression(node.ast, ctx, false);
+        return;
+    }
+    if (node instanceof TrackDecl) {
+        // `track(...)` is safe in the body; a track() inside a nested function is not,
+        // but that is a different failure (a raw syntax error) and the parser owns it.
+        return;
+    }
+    if (node instanceof DynamicBinding) {
+        if (insideHandler)
+            return;
+        // An event handler is client-only by definition: it is dispatched by the
+        // browser, so `document.title = …` there is correct, not a bug.
+        const binding = node;
+        const target = String(binding.target || '');
+        if (target.startsWith('on') || binding.kind === 'event')
+            return;
+        checkExpression(node.expression?.ast ?? null, ctx, false);
+        return;
+    }
+    if (node instanceof OpaqueDynamicRegion) {
+        checkExpression(node.condition?.ast ?? null, ctx, false);
+        for (const child of (node.consequentNodes || []))
+            checkNode(child, ctx);
+        for (const child of (node.alternateNodes || []))
+            checkNode(child, ctx);
+        return;
+    }
+    if (node instanceof StaticNode) {
+        for (const attr of node.attributes || [])
+            void attr;
+        for (const child of node.children || [])
+            checkNode(child, ctx);
+        return;
+    }
+    // ComponentCall / MapRegion / prop slots / anything else: recurse over children
+    // and check their expressions, still in body position.
+    const record = node;
+    if (record.expression && typeof record.expression === 'object') {
+        checkExpression(record.expression.ast ?? null, ctx, false);
+    }
+    for (const key of Object.keys(record)) {
+        const value = record[key];
+        if (Array.isArray(value))
+            for (const item of value)
+                checkNode(item, ctx);
+        else if (value && typeof value === 'object' && value.constructor?.name?.endsWith('Node')) {
+            checkNode(value, ctx);
+        }
+    }
+}
+/** The cell/value halves of every `track()` declaration in a component. */
+function collectCells(comp) {
+    const cells = new Map();
+    const values = new Map();
+    for (const node of comp.body) {
+        if (!(node instanceof TrackDecl))
+            continue;
+        const cellName = node.rawName || node.name;
+        if (node.rawName)
+            cells.set(node.rawName, { value: node.name });
+        values.set(node.name, { cell: cellName });
+    }
+    return { cells, values };
+}
+/**
+ * Run the abuse checks for one component. Called after its body is built, so
+ * the tracked names are known.
+ */
+export function validateAbuse(comp, file, source) {
+    // A `client` island renders on the server too — SSR runs the same body — so
+    // the same rules apply. What differs is `{#server}`/`{#client}`.
+    const { cells, values } = collectCells(comp);
+    const ctx = { compName: comp.name, file, source, cells, values };
+    for (const node of comp.body)
+        checkNode(node, ctx);
+}

package/dist/errors.d.ts

@@ -9,6 +9,8 @@ export interface VeskErrorOptions {
     nextSteps?: string[];
     tip?: string;
     code?: string;
+    /** Rendered code frame (see `codeFrame`). Never a V-code. */
+    frame?: string;
     [key: string]: unknown;
 }
 export declare class VeskError extends Error {
@@ -19,7 +21,10 @@ export declare class VeskError extends Error {
     suggestions: string[];
     nextSteps: string[];
     tip: string;
+    /** The V-diagnostic code, e.g. `V0501`. */
     code?: string;
+    /** The rendered code frame. Used to be written into `code`, which silently replaced the V-code. */
+    frame?: string;
     constructor(message: string, opts?: VeskErrorOptions);
     static notFound(name: string, candidates?: string[], context?: VeskErrorOptions): VeskError;
     /**
@@ -37,6 +42,40 @@ export declare class VeskError extends Error {
         form?: 'nested' | 'value';
     }): VeskError;
     static classDecl(context?: VeskErrorOptions): VeskError;
+    /**
+     * A browser-only global used in code the SERVER evaluates.
+     *
+     * On the server these are either absent (`window is not defined`) or, worse,
+     * silently present-but-wrong (`navigator` exists in modern Node, so
+     * `navigator.onLine` is `undefined` and a page renders as if it were offline).
+     * A raw `ReferenceError` at request time is the worst possible report: it
+     * names neither the component nor the fix. This points at the line.
+     */
+    static ssrUnsafeGlobal(name: string, context?: Partial<VeskErrorOptions> & {
+        inComponent?: string;
+    }): VeskError;
+    /**
+     * The second name from `track()` called as a function.
+     *
+     * `const &[count, setCount] = track(0)` returns a CELL, not a setter function, so
+     * `setCount(1)` throws `setCount is not a function` from generated code with
+     * no line of user code in the message. The cell is the writer: `.set(v)`.
+     */
+    static cellCalledAsFunction(name: string, context?: Partial<VeskErrorOptions> & {
+        value?: string;
+        cell?: string;
+    }): VeskError;
+    /**
+     * `set(value, …)` used outside a rewritten expression.
+     *
+     * The compiler rewrites `set(count, v)` to `countCell.set(v)` inside JSX and
+     * event handlers — but a bare statement in the component body is NOT
+     * rewritten, so the runtime `set` receives the value and throws
+     * "Cannot read properties of undefined". Pass the CELL, not the value.
+     */
+    static setWithValueName(name: string, context?: Partial<VeskErrorOptions> & {
+        cell?: string;
+    }): VeskError;
     static serverBlockInClient(compName: string, context?: VeskErrorOptions): VeskError;
     static clientBlockInServer(compName: string, context?: VeskErrorOptions): VeskError;
     static componentNotFound(name: string, available?: string[], context?: VeskErrorOptions): VeskError;

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAoBxD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,WAAW,GAAE,MAAU,GAAG,MAAM,GAAG,IAAI,CAWrG;AAqCD,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,SAAI,EAAE,KAAK,SAAI,GAAG,MAAM,CAkBrG;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAgBD,qBAAa,SAAU,SAAQ,KAAK;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;gBAEF,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,gBAAqB;IAYxD,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,GAAE,MAAM,EAAO,EAAE,OAAO,GAAE,gBAAqB,GAAG,SAAS;IA8BnG;;;;;;;;;;OAUG;IACH,MAAM,CAAC,kBAAkB,CAAC,OAAO,GAAE,gBAAgB,GAAG;QAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAA;KAAO,GAAG,SAAS;IA6BpG,MAAM,CAAC,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,SAAS;IAoB3D,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,SAAS;IAmBvF,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,SAAS;IAmBvF,MAAM,CAAC,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,MAAM,EAAO,EAAE,OAAO,GAAE,gBAAqB,GAAG,SAAS;IAO3G,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,GAAE,MAAM,EAAO,EAAE,OAAO,GAAE,gBAAqB,GAAG,SAAS;IAYvG,MAAM,CAAC,sBAAsB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,SAAS;IAmB/G,MAAM,CAAC,cAAc,CAAC,OAAO,GAAE,gBAAgB,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,SAAS;IAmBpF,QAAQ,IAAI,MAAM;IA0BlB,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAclC"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAoBxD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,WAAW,GAAE,MAAU,GAAG,MAAM,GAAG,IAAI,CAWrG;AAqCD,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,SAAI,EAAE,KAAK,SAAI,GAAG,MAAM,CAkBrG;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAgBD,qBAAa,SAAU,SAAQ,KAAK;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mGAAmG;IACnG,KAAK,CAAC,EAAE,MAAM,CAAC;gBAEH,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,gBAAqB;IAgBxD,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,GAAE,MAAM,EAAO,EAAE,OAAO,GAAE,gBAAqB,GAAG,SAAS;IA8BnG;;;;;;;;;;OAUG;IACH,MAAM,CAAC,kBAAkB,CAAC,OAAO,GAAE,gBAAgB,GAAG;QAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAA;KAAO,GAAG,SAAS;IA6BpG,MAAM,CAAC,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,SAAS;IAoB3D;;;;;;;;OAQG;IACH,MAAM,CAAC,eAAe,CACpB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAO,GACjE,SAAS;IAqBZ;;;;;;OAMG;IACH,MAAM,CAAC,oBAAoB,CACzB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO,GAC1E,SAAS;IAmBZ;;;;;;;OAOG;IACH,MAAM,CAAC,gBAAgB,CACrB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO,GAC1D,SAAS;IAkBZ,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,SAAS;IAmBvF,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,SAAS;IAmBvF,MAAM,CAAC,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,MAAM,EAAO,EAAE,OAAO,GAAE,gBAAqB,GAAG,SAAS;IAO3G,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,GAAE,MAAM,EAAO,EAAE,OAAO,GAAE,gBAAqB,GAAG,SAAS;IAYvG,MAAM,CAAC,sBAAsB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,SAAS;IAmB/G,MAAM,CAAC,cAAc,CAAC,OAAO,GAAE,gBAAgB,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,SAAS;IAmBpF,QAAQ,IAAI,MAAM;IA0BlB,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAclC"}

package/dist/errors.js

@@ -107,7 +107,10 @@ export class VeskError extends Error {
     suggestions;
     nextSteps;
     tip;
+    /** The V-diagnostic code, e.g. `V0501`. */
     code;
+    /** The rendered code frame. Used to be written into `code`, which silently replaced the V-code. */
+    frame;
     constructor(message, opts = {}) {
         super(message);
         this.name = 'VeskError';
@@ -117,8 +120,13 @@ export class VeskError extends Error {
         this.suggestions = opts.suggestions || [];
         this.nextSteps = opts.nextSteps || [];
         this.tip = opts.tip || '';
-        if (opts.code !== undefined)
+        // The diagnostic code owns `code`. The code frame used to be written there
+        // too, which silently replaced `V0501` with a wall of source text — the
+        // report lost the one thing that identifies it.
+        if (opts.code !== undefined && !opts.code.includes('\n'))
             this.code = opts.code;
+        if (opts.frame !== undefined)
+            this.frame = opts.frame;
     }
     static notFound(name, candidates = [], context = {}) {
         const allCandidates = [...new Set([...candidates, ...VESK_BUILTINS])];
@@ -202,6 +210,75 @@ export class VeskError extends Error {
             tip: 'Use plain objects for data and factory functions for constructors inside .vsk files.',
         });
     }
+    /**
+     * A browser-only global used in code the SERVER evaluates.
+     *
+     * On the server these are either absent (`window is not defined`) or, worse,
+     * silently present-but-wrong (`navigator` exists in modern Node, so
+     * `navigator.onLine` is `undefined` and a page renders as if it were offline).
+     * A raw `ReferenceError` at request time is the worst possible report: it
+     * names neither the component nor the fix. This points at the line.
+     */
+    static ssrUnsafeGlobal(name, context = {}) {
+        return new VeskError(`\`${name}\` is browser-only, and this component body runs during SSR.`, {
+            ...context,
+            code: context.code || 'V0501',
+            suggestions: [
+                `Wrap the part that needs the DOM in a {#client} block.`,
+                `Move the code into an event handler — handlers never run on the server.`,
+                `Do the setup in on_destroy(), which the compiler only emits on the client.`,
+            ],
+            nextSteps: [
+                `component ${context.inComponent ?? 'this component'}: wrap the \`${name}\` access in {#client}...{/client}.`,
+                `Or guard it: if (typeof ${name} !== 'undefined') { ... }`,
+            ],
+            tip: 'SSR renders this component before the client exists. Reading a browser global here either throws during the request or (for `navigator`) silently returns undefined.',
+        });
+    }
+    /**
+     * The second name from `track()` called as a function.
+     *
+     * `const &[count, setCount] = track(0)` returns a CELL, not a setter function, so
+     * `setCount(1)` throws `setCount is not a function` from generated code with
+     * no line of user code in the message. The cell is the writer: `.set(v)`.
+     */
+    static cellCalledAsFunction(name, context = {}) {
+        return new VeskError(`\`${name}\` is a cell, not a function — cells are written with \`.set()\`.`, {
+            ...context,
+            code: context.code || 'V0502',
+            suggestions: [
+                `Use \`${name}.set(...)\` instead of \`${name}(...)\`.`,
+                `Or use the tracked spelling inside an event handler: set(${context.value ?? 'value'}, ...)`,
+            ],
+            nextSteps: [
+                `const &[${context.value ?? 'value'}, ${name}] = track(0) → \`${name}.set(v)\``,
+                'The value read in markup is the first name; the second is the cell object.',
+            ],
+            tip: `\`track()\` returns [value, cell]. \`${name}\` is the cell half.`,
+        });
+    }
+    /**
+     * `set(value, …)` used outside a rewritten expression.
+     *
+     * The compiler rewrites `set(count, v)` to `countCell.set(v)` inside JSX and
+     * event handlers — but a bare statement in the component body is NOT
+     * rewritten, so the runtime `set` receives the value and throws
+     * "Cannot read properties of undefined". Pass the CELL, not the value.
+     */
+    static setWithValueName(name, context = {}) {
+        return new VeskError(`\`set(${name}, …)\` needs the CELL, and \`${name}\` is the value half of track().`, {
+            ...context,
+            code: context.code || 'V0503',
+            suggestions: [
+                `Use \`set(${context.cell ?? 'cell'}, …)\` or \`${context.cell ?? 'cell'}.set(…)\`.`,
+                `Or move the set() into an event handler, where the compiler rewrites it for you.`,
+            ],
+            nextSteps: [
+                `const &[${name}, ${context.cell ?? 'cell'}] = track(0) → \`${context.cell ?? 'cell'}.set(v)\``,
+            ],
+            tip: 'set(cell, value) is only rewritten inside JSX and handlers; in a body statement it reaches the runtime untouched.',
+        });
+    }
     static serverBlockInClient(compName, context = {}) {
         return new VeskError(`{#server} block found in client island "${compName}". Client islands render on both server and client, so {#server} blocks have no effect.`, {
             ...context,

package/dist/ir-generator.js

@@ -1524,7 +1524,7 @@ function validateBlocks(compName, isClient, body, file, source) {
                     const { line, column } = offsetToLineCol(source, pos);
                     opts.line = line;
                     opts.column = column;
-                    opts.code = codeFrame(source, line, column);
+                    opts.frame = codeFrame(source, line, column);
                 }
                 throw VeskError.serverBlockInClient(compName, opts);
             }
@@ -1537,7 +1537,7 @@ function validateBlocks(compName, isClient, body, file, source) {
                     const { line, column } = offsetToLineCol(source, pos);
                     opts.line = line;
                     opts.column = column;
-                    opts.code = codeFrame(source, line, column);
+                    opts.frame = codeFrame(source, line, column);
                 }
                 throw VeskError.clientBlockInServer(compName, opts);
             }

package/dist/scan.d.ts

@@ -93,6 +93,21 @@ export declare function hasTopLevelComma(text: string): boolean;
  * and `for (... in ...)` headers apart from classic `for` loops.
  */
 export declare function containsForOfIn(text: string): boolean;
+/**
+ * Reports whether `ident` appears in `text` as a CALLED identifier — i.e.
+ * followed by an optional TS generic clause and then `(`.
+ *
+ * This is a character-loop tokenizer, not a text match: it steps over
+ * whitespace, `//` and block comments, and quoted / template strings, so
+ * `track(` appearing inside a string, a comment or a property access
+ * (`obj.track(...)`) never counts. Template literals are skipped whole —
+ * including their `${...}` holes — because a `track(` in an interpolation is
+ * not a reliable enough signal to inject a runtime binding for.
+ *
+ * Used to decide which runtime helpers a raw statement needs without
+ * requiring the caller to have been lowered into a TrackDecl first.
+ */
+export declare function callsIdentifier(text: string, ident: string): boolean;
 /**
  * Extracts the argument text of a `track<...>(...)` call from an init
  * expression. Handles nested generics (`track<Map<string, number>>(...)`)

package/dist/scan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../src/scan.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAItD;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAOzE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWrD;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAS5D;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAG9D;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAc9D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAsB1D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAY3D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAmDlD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAkBvE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CA2BjE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAgBtD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAkBrD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAYpD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOtD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAcnE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAqB9D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAY3D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAexD"}
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../src/scan.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAItD;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAOzE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWrD;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAS5D;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAG9D;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAc9D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAsB1D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAY3D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAmDlD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAkBvE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CA2BjE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAgBtD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAkBrD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAwDpE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAYpD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOtD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAcnE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAqB9D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAY3D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAexD"}

package/dist/scan.js

@@ -408,6 +408,70 @@ export function containsForOfIn(text) {
     }
     return false;
 }
+/**
+ * Reports whether `ident` appears in `text` as a CALLED identifier — i.e.
+ * followed by an optional TS generic clause and then `(`.
+ *
+ * This is a character-loop tokenizer, not a text match: it steps over
+ * whitespace, `//` and block comments, and quoted / template strings, so
+ * `track(` appearing inside a string, a comment or a property access
+ * (`obj.track(...)`) never counts. Template literals are skipped whole —
+ * including their `${...}` holes — because a `track(` in an interpolation is
+ * not a reliable enough signal to inject a runtime binding for.
+ *
+ * Used to decide which runtime helpers a raw statement needs without
+ * requiring the caller to have been lowered into a TrackDecl first.
+ */
+export function callsIdentifier(text, ident) {
+    let i = 0;
+    const len = text.length;
+    // True when the previous significant character means the next identifier
+    // is a member access (`obj.track`) rather than a free call.
+    let afterDot = false;
+    while (i < len) {
+        const ch = text[i];
+        if (isWhitespaceChar(ch)) {
+            i++;
+            continue;
+        }
+        const commentEnd = skipComment(text, i);
+        if (commentEnd !== i) {
+            i = commentEnd;
+            continue;
+        }
+        if (ch === '"' || ch === "'" || ch === '`') {
+            i = skipString(text, i);
+            afterDot = false;
+            continue;
+        }
+        if (ch === '.' || (ch === '?' && text[i + 1] === '.')) {
+            afterDot = true;
+            i += ch === '.' ? 1 : 2;
+            continue;
+        }
+        if (isIdentStartCode(ch.charCodeAt(0))) {
+            let j = i + 1;
+            while (j < len && isIdentCharCode(text.charCodeAt(j)))
+                j++;
+            const name = text.slice(i, j);
+            let k = skipWhitespace(text, j);
+            // A `name<T,>(...)` generic call — skip the balanced `<...>`.
+            if (text[k] === '<') {
+                k = skipTrackGeneric(text, k);
+                k = skipWhitespace(text, k);
+            }
+            if (name === ident && text[k] === '(' && !afterDot) {
+                return true;
+            }
+            afterDot = false;
+            i = j;
+            continue;
+        }
+        afterDot = false;
+        i++;
+    }
+    return false;
+}
 /**
  * Extracts the argument text of a `track<...>(...)` call from an init
  * expression. Handles nested generics (`track<Map<string, number>>(...)`)

package/dist/server-jsgen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-jsgen.d.ts","sourceRoot":"","sources":["../src/server-jsgen.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAOzE,OAAO,EAAkG,KAAK,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAoDrK,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,EAAE,OAAO,GAAE,OAAe,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,MAAM,CAgEjJ;AA4XD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,EAAE,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,CAqD1F;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAkCzE;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAYhG"}
+{"version":3,"file":"server-jsgen.d.ts","sourceRoot":"","sources":["../src/server-jsgen.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAOzE,OAAO,EAAkG,KAAK,WAAW,EAAE,MAAM,mCAAmC,CAAC;AA4DrK,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,EAAE,OAAO,GAAE,OAAe,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,MAAM,CA4EjJ;AAyZD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,EAAE,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,CAwD1F;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB;AAuFD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAkCzE;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAYhG"}

package/dist/server-jsgen.js

@@ -1,8 +1,15 @@
-import { StaticNode, TextNode, DynamicBinding, OpaqueDynamicRegion, MapRegion, WhileLoop, SwitchBlock, TryCatch, ForLoop, TrackDecl, RuntimeStatement, ComponentRef, ComponentCall, ServerBlock, ClientBlock, HeadBlock, SlotNode, PropSlot, PropSlotRender, } from '@vesk/compiler/src/ir';
+import { Expression, StaticNode, TextNode, DynamicBinding, OpaqueDynamicRegion, MapRegion, WhileLoop, SwitchBlock, TryCatch, ForLoop, TrackDecl, RuntimeStatement, ComponentRef, ComponentCall, ServerBlock, ClientBlock, HeadBlock, SlotNode, PropSlot, PropSlotRender, } from '@vesk/compiler/src/ir';
 import { isStaticIR, collectTrackedNames, transformTracked, transformTrackedInit, semicolonizeStatement } from '@vesk/compiler/src/client-codegen';
-import { unwrapTrackCall, stripTrackGeneric, hasTopLevelComma, skipWhitespace, findBalancedEnd, startsWithIdentifier } from '@vesk/compiler/src/scan';
+import { unwrapTrackCall, stripTrackGeneric, hasTopLevelComma, skipWhitespace, findBalancedEnd, startsWithIdentifier, callsIdentifier } from '@vesk/compiler/src/scan';
 import { escapeHtml, indent, exprJS, extractTopLevelNames, extractRuntimeNames, buildParamInit, __vskHydrate, __vskMarkerless, __vskImportedNames, setVskImportedNames, setVskForceClaim, takeVskForceClaim, nextVskId, } from '@vesk/compiler/src/server-utils';
 import { localValueImportNames } from '@vesk/compiler/src/module-imports';
+import { lowerJsxInExpression } from '@vesk/compiler/src/server-jsx-lowering';
+import { print } from 'esrap';
+import tsPrinter from 'esrap/languages/ts';
+/** Print an already-lowered AST with the plain TS printer (no JSX remains). */
+function printLoweredTs(ast) {
+    return print(ast, tsPrinter()).code;
+}
 import { vskImportValueNames } from '@vesk/compiler/src/vsk-imports';
 // Hydrate-mode component-boundary wrapper. Each server-rendered component call
 // is preceded by a `<!--vsk-->` marker and a single container element: the
@@ -107,8 +114,17 @@ export function irNodeToJS(node, importedNames, isAsync = false, tracked) {
             `})();`,
         ].join('\n');
     }
-    if (node instanceof RuntimeStatement)
+    if (node instanceof RuntimeStatement) {
+        const stmt = node;
+        const lowered = stmt.ast ? lowerJsxInExpression(stmt.ast) : null;
+        if (lowered && lowered !== stmt.ast && (tracked?.size ?? 0) === 0) {
+            return semicolonizeStatement(printLoweredTs(lowered));
+        }
+        if (lowered && lowered !== stmt.ast) {
+            return semicolonizeStatement(transformTracked({ ...node, ast: lowered }, tracked || new Map()));
+        }
         return semicolonizeStatement(transformTracked(node, tracked || new Map()));
+    }
     if (node instanceof SlotNode) {
         // Markerless mode drops the slot boundary comments: SSR output is plain
         // HTML and slot claims scope structurally (createLayoutSlot subject to the
@@ -133,7 +149,21 @@ function isEvent(target) {
     return !!target && target.startsWith('on') && target.length > 2;
 }
 function exprJSX(node, tracked) {
-    return exprJS(transformTracked(node, tracked || new Map()));
+    // A function-valued child — `<For each={items}>{(item) => <li/>}</For>` —
+    // carries JSX inside an EXPRESSION, and the server has no IR node for it, so
+    // it used to be printed verbatim and the render threw "Unexpected token '<'".
+    // Lower it to the string the body emitter would have produced. Client output
+    // is untouched (a chunk goes through esbuild's tsx loader, so JSX is legal
+    // there).
+    const lowered = node.ast ? lowerJsxInExpression(node.ast) : null;
+    const didLower = lowered !== node.ast;
+    if (didLower && (tracked?.size ?? 0) === 0) {
+        // `transformTracked` returns the RAW source when there is nothing to
+        // rewrite, which would throw the lowering away. With no tracked names there
+        // are no rewrites to lose.
+        return exprJS(printLoweredTs(lowered));
+    }
+    return exprJS(transformTracked({ ...node, ast: lowered }, tracked || new Map()));
 }
 function staticNodeToJS(node, isAsync = false, tracked) {
     const lines = [];
@@ -461,19 +491,35 @@ function componentCallToJS(node, importedNames, isAsync = false, tracked) {
         }
     }
     if (regularChildren.length > 0) {
-        const childLines = [];
-        for (const child of regularChildren) {
-            const code = irNodeToJS(child, importedNames, isAsync, tracked);
-            if (code)
-                childLines.push(code);
+        // A single function-valued child (`<For each={items}>{(item) => …}</For>`,
+        // or a reference to one) must stay a FUNCTION: `For` calls it per item.
+        // Wrapping it in the `(() => { const __out = []; … })()` text emitter made it
+        // return undefined, so For rendered an empty list.
+        const fnType = regularChildren.length === 1 && regularChildren[0] instanceof DynamicBinding && regularChildren[0].kind === 'text'
+            ? regularChildren[0].expression.ast?.type
+            : null;
+        const isFnChild = fnType === 'ArrowFunctionExpression'
+            || fnType === 'FunctionExpression'
+            || fnType === 'Identifier'
+            || fnType === 'MemberExpression';
+        if (isFnChild) {
+            propsEntries.push(`children: ${exprJSX(regularChildren[0].expression, tracked)}`);
         }
-        if (childLines.length > 0) {
-            const childrenVar = `__ch${nextVskId()}`;
-            propsEntries.push(`children: ${childrenVar}`);
-            lines.push(`const ${childrenVar} = ${isAsync ? 'await (async ' : '('}() => {`);
-            lines.push(`const __out = [];`);
-            lines.push(indent(childLines.join('\n')));
-            lines.push(`return __out.join(''); })();`);
+        else {
+            const childLines = [];
+            for (const child of regularChildren) {
+                const code = irNodeToJS(child, importedNames, isAsync, tracked);
+                if (code)
+                    childLines.push(code);
+            }
+            if (childLines.length > 0) {
+                const childrenVar = `__ch${nextVskId()}`;
+                propsEntries.push(`children: ${childrenVar}`);
+                lines.push(`const ${childrenVar} = ${isAsync ? 'await (async ' : '('}() => {`);
+                lines.push(`const __out = [];`);
+                lines.push(indent(childLines.join('\n')));
+                lines.push(`return __out.join(''); })();`);
+            }
         }
     }
     const propsObj = `{ ${propsEntries.join(', ')} }`;
@@ -503,10 +549,10 @@ function componentCallToJS(node, importedNames, isAsync = false, tracked) {
     }
     const callExpr = `${awaitKw}${calleeVar}(${propsObj}, __registry, (${calleeVar}.__veskScope || __vesk))`;
     if (__vskHydrate && !__vskMarkerless) {
-        lines.push(`__out.push(${JSON.stringify(componentMarker(compName))} + (${callExpr} || ''));`);
+        lines.push(`__out.push(${JSON.stringify(componentMarker(compName))} + __flat(${callExpr}));`);
     }
     else {
-        lines.push(`__out.push(${callExpr} || '');`);
+        lines.push(`__out.push(__flat(${callExpr}));`);
     }
     return lines.join('\n');
 }
@@ -524,6 +570,9 @@ export function generateFunctionBody(comp, importedNames) {
     lines.push(`const __styleText = (v) => { if (typeof v === 'string') return v; if (v && typeof v === 'object') { let s = ''; for (const k in v) { const x = v[k]; if (x == null || x === false) continue; s += k.replace(/[A-Z]/g, (m) => '-' + m.toLowerCase()) + ':' + x + ';'; } return s; } return String(v); };`);
     lines.push(`const __attr = (n, v) => (v == null || v === false) ? '' : ' ' + n + '="' + __escape(n === 'style' ? __styleText(v) : String(v)) + '"';`);
     lines.push(`const raw = (s) => s == null ? '' : String(s);`);
+    // A component may return an ARRAY of strings (`<For>` maps its children), and
+    // `Array#toString` joins the rows with commas — `<li>a</li>,<li>b</li>`.
+    lines.push(`const __flat = (v) => Array.isArray(v) ? v.join('') : (v == null ? '' : String(v));`);
     lines.push(`const __tk = globalThis.__vsk_ssr_token || '';`);
     if (asyncMode) {
         lines.push(`const __pk = __tk ? '__vsk_ssr_promises_' + __tk : '__vsk_ssr_promises';`);
@@ -563,6 +612,105 @@ export function generateFunctionBody(comp, importedNames) {
     __currentCompName = '';
     return lines.join('\n');
 }
+/**
+ * Whether a component body needs `track` / `get` / `set` destructured into its
+ * `__vesk` scope.
+ *
+ * A `TrackDecl` (`const &[n] = track(0)`) always needs them. A PLAIN
+ * `const n = track(0)` does not lower to a TrackDecl — it stays a raw
+ * `RuntimeStatement` whose source still calls `track` — and used to reach the
+ * server renderer unbound, taking the whole page down with
+ * "track is not defined". The client codegen imports these names
+ * unconditionally, so the server has to recognise the plain form too or the
+ * two halves of a file disagree about what is in scope.
+ */
+function bodyNeedsRuntimeCells(nodes) {
+    for (const node of nodes) {
+        if (node instanceof TrackDecl)
+            return true;
+        // Raw statement / expression text: the only place a plain `track(...)`
+        // call can appear outside a lowered node.
+        if (node instanceof RuntimeStatement && callsIdentifier(node.raw, 'track'))
+            return true;
+        if (node instanceof Expression && callsIdentifier(node.raw, 'track'))
+            return true;
+        if (node instanceof ForLoop) {
+            if (callsIdentifier(node.init, 'track'))
+                return true;
+            if (callsIdentifier(node.update, 'track'))
+                return true;
+            if (callsIdentifier(node.condition.raw, 'track'))
+                return true;
+            if (bodyNeedsRuntimeCells(node.bodyTemplate))
+                return true;
+        }
+        if (node instanceof StaticNode) {
+            for (const attr of node.attributes) {
+                if (callsIdentifier(attr.value, 'track'))
+                    return true;
+            }
+            if (bodyNeedsRuntimeCells(node.children))
+                return true;
+        }
+        if (node instanceof ComponentCall) {
+            for (const prop of node.props) {
+                if (callsIdentifier(prop.value.raw, 'track'))
+                    return true;
+            }
+            for (const spread of node.spreadProps) {
+                if (callsIdentifier(spread.raw, 'track'))
+                    return true;
+            }
+            if (bodyNeedsRuntimeCells(node.children))
+                return true;
+        }
+        if (node instanceof ServerBlock || node instanceof ClientBlock || node instanceof HeadBlock) {
+            if (bodyNeedsRuntimeCells(node.children))
+                return true;
+        }
+        if (node instanceof PropSlot && bodyNeedsRuntimeCells(node.body))
+            return true;
+        if (node instanceof MapRegion) {
+            if (callsIdentifier(node.expression.raw, 'track'))
+                return true;
+            if (bodyNeedsRuntimeCells(node.bodyTemplate))
+                return true;
+            if (bodyNeedsRuntimeCells(node.alternateNodes))
+                return true;
+        }
+        if (node instanceof OpaqueDynamicRegion) {
+            if (callsIdentifier(node.condition.raw, 'track'))
+                return true;
+            if (bodyNeedsRuntimeCells(node.consequentNodes))
+                return true;
+            if (bodyNeedsRuntimeCells(node.alternateNodes))
+                return true;
+        }
+        if (node instanceof WhileLoop) {
+            if (callsIdentifier(node.condition.raw, 'track'))
+                return true;
+            if (bodyNeedsRuntimeCells(node.bodyTemplate))
+                return true;
+        }
+        if (node instanceof SwitchBlock) {
+            if (callsIdentifier(node.discriminant.raw, 'track'))
+                return true;
+            for (const c of node.cases) {
+                if (c.test && callsIdentifier(c.test.raw, 'track'))
+                    return true;
+                if (bodyNeedsRuntimeCells(c.body))
+                    return true;
+            }
+        }
+        if (node instanceof TryCatch) {
+            if (bodyNeedsRuntimeCells(node.bodyTemplate))
+                return true;
+            if (bodyNeedsRuntimeCells(node.catchBody))
+                return true;
+        }
+    }
+    return false;
+}
 /**
  * Builds the compiled body source for every component in an IR root. Used by
  * both `buildComponentMap` (live functions) and `precompile.ts` (AOT SSR plans
@@ -579,7 +727,7 @@ export function buildComponentEntries(irRoot) {
     const componentNames = new Set(irRoot.components.map((c) => c.name));
     const topValueNames = topNames.filter((n) => !componentNames.has(n));
     const importedNames = new Set([...runtimeNames, ...localValueNames, ...topValueNames]);
-    const hasTracked = irRoot.components.some((c) => c.body.some((n) => n instanceof TrackDecl));
+    const hasTracked = irRoot.components.some((c) => bodyNeedsRuntimeCells(c.body));
     const extraNames = hasTracked ? ['get', 'set', 'track'] : [];
     // Values exported by a `.vsk` module (`export const MAX = 10`) are hoisted
     // into this file's `__vesk` and must be destructured into component scope.

package/dist/server-jsx-lowering.d.ts

@@ -0,0 +1,16 @@
+/** True when `node` contains JSX anywhere. */
+export declare function containsJsx(node: unknown, depth?: number): boolean;
+declare const RAW = "__raw";
+/**
+ * JSX text semantics, matching what the compiler emits for StaticNode text:
+ * lines are trimmed, blank lines vanish, and interior newlines collapse to a
+ * single space. Getting this wrong is visible as stray whitespace in SSR HTML.
+ */
+export declare function normalizeJsxText(value: string): string;
+/**
+ * Rewrite every JSX node inside `ast` into the string it would have rendered.
+ * Returns the original node when there is no JSX, so the common path is free.
+ */
+export declare function lowerJsxInExpression(ast: unknown): unknown;
+export { RAW as RAW_HELPER };
+//# sourceMappingURL=server-jsx-lowering.d.ts.map

package/dist/server-jsx-lowering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-jsx-lowering.d.ts","sourceRoot":"","sources":["../src/server-jsx-lowering.ts"],"names":[],"mappings":"AAwBA,8CAA8C;AAC9C,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,SAAI,GAAG,OAAO,CAa7D;AAKD,QAAA,MAAM,GAAG,UAAU,CAAC;AAEpB;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAiBtD;AAiLD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAG1D;AAED,OAAO,EAAE,GAAG,IAAI,UAAU,EAAE,CAAC"}

package/dist/server-jsx-lowering.js

@@ -0,0 +1,226 @@
+/** True when `node` contains JSX anywhere. */
+export function containsJsx(node, depth = 0) {
+    if (!node || typeof node !== 'object' || depth > 40)
+        return false;
+    if (Array.isArray(node)) {
+        for (const item of node)
+            if (containsJsx(item, depth + 1))
+                return true;
+        return false;
+    }
+    const type = node.type;
+    if (type === 'JSXElement' || type === 'JSXFragment')
+        return true;
+    for (const key of Object.keys(node)) {
+        const value = node[key];
+        if (value && typeof value === 'object' && containsJsx(value, depth + 1))
+            return true;
+    }
+    return false;
+}
+/** The helper names the generated server body already defines. */
+const ESCAPE = '__escape';
+const ATTR = '__attr';
+const RAW = '__raw';
+/**
+ * JSX text semantics, matching what the compiler emits for StaticNode text:
+ * lines are trimmed, blank lines vanish, and interior newlines collapse to a
+ * single space. Getting this wrong is visible as stray whitespace in SSR HTML.
+ */
+export function normalizeJsxText(value) {
+    const lines = value.split(/\r\n|\n|\r/);
+    let lastNonEmpty = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (/[^ \t]/.test(lines[i]))
+            lastNonEmpty = i;
+    }
+    let out = '';
+    for (let i = 0; i < lines.length; i++) {
+        let line = lines[i].replace(/\t/g, ' ');
+        if (i !== 0)
+            line = line.replace(/^ +/, '');
+        if (i !== lines.length - 1)
+            line = line.replace(/ +$/, '');
+        if (line) {
+            if (i !== lastNonEmpty)
+                line += ' ';
+            out += line;
+        }
+    }
+    return out;
+}
+function lower(node, ctx) {
+    if (Array.isArray(node))
+        return node.map((n) => lower(n, ctx));
+    if (!node || typeof node !== 'object')
+        return node;
+    const n = node;
+    if (n.type === 'JSXElement') {
+        const opening = n.openingElement;
+        const name = jsxTagName(opening.name);
+        const attrs = lowerAttributes(opening.attributes, ctx);
+        const children = lowerChildren(n.children, ctx);
+        // statics[0] opens the tag, attributes interleave, then '>', then children,
+        // then the closing tag. Getting the '>' placement wrong silently produced
+        // `<lia</li>` — a tag that never closes and swallows the next element.
+        const statics = [`<${name}`, ...attrs.statics.slice(1)];
+        statics[statics.length - 1] += '>';
+        const quasis = [...statics, `</${name}>`];
+        const expressions = [...attrs.exprs, ...children];
+        return template(quasis, expressions);
+    }
+    if (n.type === 'JSXFragment') {
+        return template(['', ''], lowerChildren(n.children, ctx));
+    }
+    // Any other node: rebuild it with lowered children.
+    const out = {};
+    for (const key of Object.keys(n)) {
+        if (key === 'type' || key === 'start' || key === 'end' || key === 'loc' || key === 'range') {
+            out[key] = n[key];
+            continue;
+        }
+        const value = n[key];
+        out[key] = value && typeof value === 'object' ? lower(value, ctx) : value;
+    }
+    return out;
+}
+function jsxTagName(nameNode) {
+    const n = nameNode;
+    if (!n)
+        return 'div';
+    if (n.type === 'JSXIdentifier')
+        return String(n.name);
+    if (n.type === 'JSXMemberExpression') {
+        const object = jsxTagName(n.object);
+        const property = n.property;
+        return `${object}.${String(property?.name)}`;
+    }
+    if (n.type === 'JSXNamespacedName') {
+        const ns = n.namespace;
+        const name = n.name;
+        return `${String(ns?.name)}:${String(name?.name)}`;
+    }
+    return 'div';
+}
+function lowerAttributes(attrs, ctx) {
+    const statics = [''];
+    const exprs = [];
+    const push = (text, expr) => {
+        if (expr === undefined) {
+            statics[statics.length - 1] += text;
+            return;
+        }
+        statics[statics.length - 1] += text;
+        statics.push('');
+        exprs.push(expr);
+    };
+    for (const attr of attrs || []) {
+        const a = attr;
+        if (a.type === 'JSXSpreadAttribute') {
+            // A spread inside a function-valued child is not lowered; dropping it
+            // would be silently wrong, so it is reported instead.
+            console.error('[vesk] a spread attribute in a JSX expression is not supported yet (dropped):', String(a.argument ?? '').slice(0, 60));
+            continue;
+        }
+        const name = jsxAttrName(a.name);
+        const value = a.value;
+        if (value === null || value === undefined) {
+            push(` ${name}`);
+            continue;
+        }
+        if (value.type === 'StringLiteral') {
+            push(` ${name}="${escapeAttrText(String(value.value))}"`);
+            continue;
+        }
+        if (value.type === 'JSXExpressionContainer') {
+            const inner = value.expression;
+            if (!inner || inner.type === 'JSXEmptyExpression') {
+                push(` ${name}="true"`);
+                continue;
+            }
+            push(` ${name}="`, callNode(ATTR, [literal(name), coerceString(lower(inner, ctx))]));
+            push('"');
+            continue;
+        }
+        push(` ${name}="`, callNode(ATTR, [literal(name), coerceString(lower(value, ctx))]));
+        push('"');
+    }
+    return { statics, exprs };
+}
+function jsxAttrName(nameNode) {
+    const n = nameNode;
+    if (!n)
+        return 'data';
+    if (n.type === 'JSXIdentifier')
+        return String(n.name);
+    return jsxTagName(n);
+}
+function lowerChildren(children, ctx) {
+    const out = [];
+    for (const child of children || []) {
+        const c = child;
+        if (c.type === 'JSXText') {
+            const text = normalizeJsxText(String(c.value ?? ''));
+            if (text)
+                out.push(literal(text));
+            continue;
+        }
+        if (c.type === 'JSXExpressionContainer') {
+            const inner = c.expression;
+            if (!inner || inner.type === 'JSXEmptyExpression')
+                continue;
+            const lowered = lower(inner, ctx);
+            out.push(coerceString(lowered));
+            continue;
+        }
+        const lowered = lower(c, ctx);
+        out.push(coerceString(lowered));
+    }
+    return out;
+}
+/** `{v}` in HTML output must be escaped, exactly as the body emitter does. */
+function coerceString(node) {
+    if (!node || typeof node !== 'object')
+        return callNode(ESCAPE, [literal(String(node))]);
+    const n = node;
+    // Already a template literal we built: its parts are static text, but any
+    // expression inside came from a nested container that escaped itself.
+    if (n.type === 'TemplateLiteral')
+        return n;
+    if (n.type === 'Literal' || n.type === 'StringLiteral')
+        return callNode(ESCAPE, [node]);
+    return callNode(ESCAPE, [callNode('String', [node])]);
+}
+/** Assemble a template literal: `statics.length === expressions.length + 1`. */
+function template(statics, expressions) {
+    const quasis = statics.map((raw, i) => ({
+        type: 'TemplateElement',
+        value: { raw },
+        tail: i === statics.length - 1,
+    }));
+    return { type: 'TemplateLiteral', quasis, expressions };
+}
+function literal(value) {
+    return { type: 'Literal', value };
+}
+function callNode(callee, args) {
+    return {
+        type: 'CallExpression',
+        callee: { type: 'Identifier', name: callee },
+        arguments: args,
+        optional: false,
+    };
+}
+function escapeAttrText(value) {
+    return value.split('&').join('&amp;').split('<').join('&lt;').split('>').join('&gt;').split('"').join('&quot;');
+}
+/**
+ * Rewrite every JSX node inside `ast` into the string it would have rendered.
+ * Returns the original node when there is no JSX, so the common path is free.
+ */
+export function lowerJsxInExpression(ast) {
+    if (!containsJsx(ast))
+        return ast;
+    return lower(ast, { track: false });
+}
+export { RAW as RAW_HELPER };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vesk/compiler",
-  "version": "0.2.50-canary.9",
+  "version": "0.2.50",
   "type": "module",
   "description": "Vesk compiler — lexer, parser, semantic analysis, IR, codegen",
   "main": "./dist/index.js",
@@ -20,7 +20,7 @@
   },
   "dependencies": {
     "@sveltejs/acorn-typescript": "^1.0.0",
-    "@vesk/types": "^0.2.50-canary.9",
+    "@vesk/types": "^0.2.50",
     "acorn": "^8.15.0",
     "esrap": "^2.3.0",
     "is-reference": "^3.0.0",