@vesk/compiler 0.2.50-canary.11 → 0.2.50-canary.12

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":"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"}

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vesk/compiler",
-  "version": "0.2.50-canary.11",
+  "version": "0.2.50-canary.12",
   "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.11",
+    "@vesk/types": "^0.2.50-canary.12",
     "acorn": "^8.15.0",
     "esrap": "^2.3.0",
     "is-reference": "^3.0.0",