@tiaforge-ui/sinter 0.0.0-stage → 0.2.0

package/dist/compiler/expr.js

@@ -0,0 +1,853 @@
+// Expression analysis: parses one attribute value, resolves every identifier
+// against the lexical scope, enforces the sandbox, extracts dependency paths
+// (value expressions) and written paths (handlers), and emits a function.
+import * as acorn from 'acorn';
+import { didYouMean } from './diagnostics.js';
+const EVERYWHERE_MAGIC = ['$el', '$url', '$now', '$locale', '$meta'];
+export const ALL_MAGIC = ['$event', '$el', '$url', '$now', '$locale', '$result', '$error', '$meta'];
+export const STORE_FNS = ['refresh', 'upsert', 'patch', 'remove', 'page', 'close', 'reset', 'emit'];
+export const BUILTIN_HELPERS = ['date', 'time', 'datetime', 'relative', 'number', 'bytes'];
+export const META_FIELDS = ['loading', 'error', 'loadedAt', 'pending', 'total', 'page', 'pages', 'from', 'to', 'hasPrev', 'hasNext'];
+const PAGE_FIELDS = ['page', 'pages', 'from', 'to', 'hasPrev', 'hasNext'];
+export const GLOBALS = new Set([
+    'undefined', 'NaN', 'Infinity', 'isFinite', 'isNaN', 'parseFloat', 'parseInt',
+    'decodeURI', 'decodeURIComponent', 'encodeURI', 'encodeURIComponent',
+    'Array', 'ArrayBuffer', 'BigInt', 'BigInt64Array', 'BigUint64Array', 'Boolean', 'DataView', 'Date',
+    'Error', 'EvalError', 'AggregateError', 'Float32Array', 'Float64Array', 'Int8Array', 'Int16Array',
+    'Int32Array', 'Intl', 'Iterator', 'JSON', 'Map', 'Math', 'Number', 'Object', 'Promise', 'RangeError',
+    'ReferenceError', 'RegExp', 'Set', 'String', 'Symbol', 'SyntaxError', 'TypeError', 'URIError',
+    'Uint8Array', 'Uint8ClampedArray', 'Uint16Array', 'Uint32Array', 'WeakMap', 'WeakSet',
+    'URL', 'URLSearchParams', 'structuredClone',
+]);
+const META_TOOLS = new Set(['eval', 'Function', 'Proxy', 'Reflect', 'globalThis', 'WeakRef', 'FinalizationRegistry', 'Atomics']);
+const BROWSER = new Set([
+    'window', 'document', 'fetch', 'localStorage', 'sessionStorage', 'navigator', 'location', 'history',
+    'setTimeout', 'setInterval', 'clearTimeout', 'clearInterval', 'requestAnimationFrame', 'queueMicrotask',
+    'XMLHttpRequest', 'WebSocket', 'EventSource', 'alert', 'confirm', 'prompt', 'console', 'self', 'top',
+    'parent', 'frames', 'opener', 'indexedDB', 'crypto', 'performance', 'SharedArrayBuffer', 'importScripts',
+    'customElements', 'Worker', 'Notification', 'caches',
+]);
+const FORBIDDEN_KEYS = new Set(['constructor', '__proto__', 'prototype']);
+const READ_ONLY = new Set([
+    'includes', 'indexOf', 'lastIndexOf', 'map', 'filter', 'slice', 'find', 'findIndex', 'findLast',
+    'findLastIndex', 'some', 'every', 'reduce', 'reduceRight', 'join', 'concat', 'flat', 'flatMap', 'at',
+    'entries', 'keys', 'values', 'forEach', 'toString', 'toLocaleString', 'toSorted', 'toReversed',
+    'toSpliced', 'with', 'has', 'get', 'startsWith', 'endsWith', 'trim', 'trimStart', 'trimEnd',
+    'toLowerCase', 'toUpperCase', 'toLocaleLowerCase', 'toLocaleUpperCase', 'split', 'substring',
+    'charAt', 'charCodeAt', 'codePointAt', 'padStart', 'padEnd', 'repeat', 'replace', 'replaceAll',
+    'match', 'matchAll', 'search', 'localeCompare', 'normalize', 'toFixed', 'toPrecision', 'valueOf',
+    'getTime', 'toISOString', 'toJSON', 'getFullYear', 'getMonth', 'getDate', 'getDay', 'getHours',
+    'getMinutes', 'getSeconds', 'test', 'exec',
+]);
+const MUTATORS = new Set(['push', 'pop', 'splice', 'sort', 'reverse', 'shift', 'unshift', 'fill', 'copyWithin', 'add', 'delete', 'clear', 'set']);
+/** callbacks of these methods receive elements of the receiver as first parameter */
+const ELEMENT_CALLBACKS = new Set(['forEach', 'map', 'filter', 'find', 'findIndex', 'findLast', 'findLastIndex', 'some', 'every', 'flatMap', 'toSorted', 'sort']);
+export function analyze(src, scope, page, opts) {
+    const edits = [];
+    const deps = new Set();
+    const writes = new Set();
+    let usesEl = false;
+    let usesIndex = false;
+    let ok = true;
+    const payloadNames = new Set();
+    const payloadStates = new Set();
+    const mode = opts.mode;
+    const magicAllowed = new Set([...EVERYWHERE_MAGIC, ...(opts.magic ?? [])]);
+    const report = (code, message, offset, hint) => {
+        if (code < 'SN500')
+            ok = false;
+        opts.report(code, message, offset, hint);
+    };
+    // ---- parsing
+    let ast = null;
+    let body = [];
+    const parseOpts = { ecmaVersion: 'latest', sourceType: 'module', allowAwaitOutsideFunction: false };
+    try {
+        if (mode === 'value' || opts.object) {
+            ast = acorn.parseExpressionAt(src, 0, parseOpts);
+            // without preserveParens, `(a ? b : c)` ends inside its parentheses; find the real end
+            const end = acorn.parseExpressionAt(src, 0, { ...parseOpts, preserveParens: true }).end;
+            const rest = src.slice(end).trim();
+            if (rest) {
+                const at = src.indexOf(rest, end);
+                report('SN401', `unexpected \`${rest.slice(0, 20)}\` after the expression`, at);
+                return fail();
+            }
+            body = [ast];
+        }
+        else {
+            const prog = acorn.parse(src, parseOpts);
+            ast = prog;
+            for (const st of prog.body) {
+                if (st.type === 'EmptyStatement')
+                    continue;
+                if (st.type !== 'ExpressionStatement') {
+                    const what = st.type.endsWith('Declaration') ? 'declarations' : st.type.replace(/Statement$/, '').toLowerCase() + ' statements';
+                    report('SN203', `handlers cannot contain ${what}; use expressions separated by \`;\``, st.start);
+                    continue;
+                }
+                body.push(st.expression);
+            }
+        }
+    }
+    catch (e) {
+        const err = e;
+        report('SN401', err.message.replace(/ \(\d+:\d+\)$/, ''), err.pos ?? 0);
+        return fail();
+    }
+    function fail() {
+        return { ok: false, code: '() => undefined', deps: [], writes: [], usesEl: false, usesIndex: false, path: null, resource: null, ast: null };
+    }
+    // ---- resolution
+    function resolve(name, locals, offset, member) {
+        const local = locals.get(name);
+        if (local)
+            return { kind: 'local', info: local };
+        if (name.startsWith('$')) {
+            if (ALL_MAGIC.includes(name)) {
+                if (!magicAllowed.has(name)) {
+                    report('SN201', `\`${name}\` is not available here`, offset);
+                    return null;
+                }
+                if (name === '$el')
+                    usesEl = true;
+                if (name === '$now')
+                    page.usesNow = true;
+                return { kind: 'magic' };
+            }
+            report('SN201', `\`${name}\` is not defined.${didYouMean(name, ALL_MAGIC)}`, offset);
+            return null;
+        }
+        if (opts.payload && opts.payloadState) {
+            for (let i = scope.states.length - 1; i >= 0; i--) {
+                if (scope.states[i].names.has(name)) {
+                    payloadStates.add(name);
+                    return { kind: 'state', sid: scope.states[i].sid };
+                }
+            }
+        }
+        if (!opts.payload) {
+            for (let i = scope.loops.length - 1; i >= 0; i--) {
+                if (scope.loops[i].name === name)
+                    return { kind: 'loop', entry: scope.loops[i] };
+            }
+            for (let i = scope.states.length - 1; i >= 0; i--) {
+                if (scope.states[i].names.has(name))
+                    return { kind: 'state', sid: scope.states[i].sid };
+            }
+            const r = page.resources.get(name);
+            if (r) {
+                r.used = true;
+                return { kind: 'resource' };
+            }
+        }
+        if (STORE_FNS.includes(name) && !opts.payload)
+            return { kind: 'store' };
+        if (page.namespaces.has(name))
+            return { kind: 'ns' };
+        if (page.helpers.has(name) || BUILTIN_HELPERS.includes(name))
+            return { kind: 'helper' };
+        if (GLOBALS.has(name))
+            return { kind: 'global' };
+        if (META_TOOLS.has(name)) {
+            report('SN202', `\`${name}\` is not allowed in expressions`, offset);
+            return null;
+        }
+        if (opts.payload) {
+            payloadNames.add(name);
+            return { kind: 'payload' };
+        }
+        if (page.actions?.has(name)) {
+            report('SN203', `\`${name}\` is an action: actions run through \`data-sn-call\` or \`<sn-resource call>\`, not inside expressions`, offset);
+            return null;
+        }
+        if (BROWSER.has(name)) {
+            report('SN202', `\`${name}\` is a browser API; expressions may use JavaScript, not the browser. Use an island`, offset);
+            return null;
+        }
+        if (opts.payload) {
+            payloadNames.add(name);
+            return { kind: 'payload' };
+        }
+        const candidates = [
+            ...scope.loops.map((l) => l.name), ...scope.states.flatMap((s) => [...s.names]),
+            ...page.resources.keys(), ...page.helpers, ...page.namespaces.keys(), ...STORE_FNS, ...BUILTIN_HELPERS,
+        ];
+        report('SN201', `\`${name}\` is not defined here.${didYouMean(name, candidates)}`, offset);
+        void member;
+        return null;
+    }
+    function emitName(name, res, sid) {
+        switch (res.kind) {
+            case 'local':
+            case 'global':
+            case 'helper': return name;
+            case 'loop': return `$.${name}`;
+            case 'state': return `$.$s${sid}.${name}`;
+            case 'resource': return `$.$r.${name}`;
+            case 'magic': return `$.${name}`;
+            case 'store': return `$.$f.${name}`;
+            case 'payload': return `$.$p.${name}`;
+            case 'ns': return name;
+        }
+    }
+    function basePath(name, res) {
+        switch (res.kind) {
+            case 'state': return { segs: [`$s${res.sid}`, name], resource: null };
+            case 'resource': return { segs: ['$r', name], resource: name };
+            case 'magic':
+                return name === '$el' || name === '$event' || name === '$result' || name === '$error'
+                    ? { segs: null, resource: null } : { segs: [name], resource: null };
+            case 'loop':
+                return { segs: res.entry.alias ? [...res.entry.alias] : null, resource: res.entry.resource };
+            case 'local':
+                return { segs: res.info.alias ? [...res.info.alias] : null, resource: res.info.resource };
+            default: return { segs: null, resource: null };
+        }
+    }
+    /** Static path of an Identifier/MemberExpression chain; null if the leftmost object is not an identifier. */
+    function chainPath(n, locals) {
+        const props = [];
+        let cur = n;
+        while (cur.type === 'MemberExpression') {
+            const m = cur;
+            if (!m.computed && m.property.type === 'Identifier')
+                props.unshift(m.property.name);
+            else if (m.computed && m.property.type === 'Literal')
+                props.unshift(String(m.property.value));
+            else if (m.computed && m.property.type === 'Identifier') {
+                const pn = m.property.name;
+                const loop = !locals.has(pn) && !opts.payload ? [...scope.loops].reverse().find((l) => l.name === pn) : undefined;
+                props.unshift(loop && loop.kind === 'index' ? `{${pn}}` : '*');
+            }
+            else
+                props.unshift('*');
+            cur = m.object;
+        }
+        if (cur.type === 'ChainExpression')
+            return chainPath(cur.expression, locals);
+        if (cur.type !== 'Identifier')
+            return null;
+        const name = cur.name;
+        const res = resolveQuiet(name, locals);
+        if (!res)
+            return null;
+        const base = basePath(name, res);
+        const segs = base.segs ? [...base.segs, ...props] : null;
+        // `list[i]` where `i` indexes that same list is the row's own element: use its row placeholder,
+        // which the runtime may skip on structure changes (reconcile handles index moves)
+        segs?.forEach((seg, k) => {
+            const loop = seg[0] == '{' ? [...scope.loops].reverse().find((l) => l.kind == 'index' && `{${l.name}}` == seg) : undefined;
+            if (loop?.of && loop.of.length == k + 1 && loop.of.slice(0, k).join('.') == segs.slice(0, k).join('.'))
+                segs[k] = loop.of[k];
+        });
+        return { root: name, res, segs, resource: base.resource };
+    }
+    /** Resolution without diagnostics, for chains already resolved by the walker. */
+    function resolveQuiet(name, locals) {
+        const saved = opts.report;
+        const savedOk = ok;
+        const savedEl = usesEl;
+        opts.report = () => { };
+        try {
+            return resolve(name, locals, 0);
+        }
+        finally {
+            opts.report = saved;
+            ok = savedOk;
+            usesEl = savedEl || usesEl;
+        }
+    }
+    function addDep(segs) {
+        if (!segs)
+            return;
+        // `$meta.<name>.<field>`: validate resource and field
+        if (segs[0] === '$meta') {
+            if (segs.length < 2 || segs[1] === '*') {
+                deps.add('$meta');
+                return;
+            }
+            deps.add(segs.slice(0, 3).join('.'));
+            return;
+        }
+        deps.add(segs.join('.'));
+    }
+    function checkMeta(n, locals) {
+        const cp = chainPath(n, locals);
+        if (!cp || cp.root !== '$meta' || cp.res.kind !== 'magic' || !cp.segs)
+            return;
+        const [, rname, field] = cp.segs;
+        if (rname && rname !== '*') {
+            const r = page.resources.get(rname);
+            if (!r) {
+                report('SN301', `resource \`${rname}\` is not declared on this page.${didYouMean(rname, page.resources.keys())}`, n.start);
+                return;
+            }
+            r.used = true;
+            if (field && field !== '*') {
+                if (!META_FIELDS.includes(field)) {
+                    report('SN303', `\`$meta.${rname}.${field}\` is not a status field.${didYouMean(field, META_FIELDS)}`, n.start);
+                }
+                else if (PAGE_FIELDS.includes(field) && !r.paginate) {
+                    report('SN303', `\`$meta.${rname}.${field}\` is a pagination field, but \`${rname}\` has no \`paginate\``, n.start);
+                }
+                else if (field === 'page' && r.paginate !== 'offset' && !r.jumps) {
+                    report('SN303', `\`$meta.${rname}.page\` exists only with \`paginate="offset"\`, or \`paginate="keyset"\` with \`offset-param\``, n.start);
+                }
+            }
+        }
+    }
+    // ---- walking
+    function ident(n, locals, shorthand = false) {
+        const res = resolve(n.name, locals, n.start);
+        if (!res)
+            return;
+        if (res.kind === 'ns') {
+            report('SN206', `namespace \`${n.name}\` must be used as \`${n.name}.<member>()\``, n.start);
+            return;
+        }
+        if (res.kind === 'helper' && BUILTIN_HELPERS.includes(n.name) && !page.helpers.has(n.name))
+            page.usedHelpers.add(n.name);
+        else if (res.kind === 'helper')
+            page.usedHelpers.add(n.name);
+        let sid;
+        if (res.kind === 'state')
+            sid = res.sid;
+        if (res.kind === 'loop' && res.entry.kind === 'index')
+            usesIndex = true;
+        const text = emitName(n.name, res, sid);
+        if (text !== n.name || shorthand)
+            edits.push({ start: n.start, end: n.end, text: shorthand ? `${n.name}: ${text}` : text });
+    }
+    function declareParams(params, locals, info) {
+        const next = new Map(locals);
+        params.forEach((p, i) => {
+            const names = [];
+            collectPattern(p, names, next);
+            for (const nm of names)
+                next.set(nm, i === 0 && p.type === 'Identifier' && info ? info : { alias: null, resource: info?.resource ?? null });
+        });
+        return next;
+    }
+    function collectPattern(p, out, locals) {
+        switch (p.type) {
+            case 'Identifier':
+                out.push(p.name);
+                break;
+            case 'ObjectPattern':
+                for (const prop of p.properties) {
+                    if (prop.type === 'RestElement')
+                        collectPattern(prop.argument, out, locals);
+                    else {
+                        if (prop.computed)
+                            visit(prop.key, locals);
+                        collectPattern(prop.value, out, locals);
+                    }
+                }
+                break;
+            case 'ArrayPattern':
+                for (const el of p.elements)
+                    if (el)
+                        collectPattern(el, out, locals);
+                break;
+            case 'RestElement':
+                collectPattern(p.argument, out, locals);
+                break;
+            case 'AssignmentPattern':
+                collectPattern(p.left, out, locals);
+                visit(p.right, locals);
+                break;
+            default: report('SN401', `unsupported parameter pattern`, p.start);
+        }
+    }
+    function visitFunction(fn, locals, elementInfo) {
+        if (fn.async)
+            report('SN203', '`async` functions are not allowed in expressions', fn.start);
+        const inner = declareParams(fn.params, locals, elementInfo);
+        visit(fn.body, inner);
+    }
+    function visitChain(n, locals, isCallee) {
+        // dependency of the whole chain (minus the method name when it is called)
+        if (mode !== 'optimistic' || true) {
+            const cp = chainPath(n, locals);
+            if (cp && cp.segs) {
+                const segs = isCallee && n.type === 'MemberExpression' ? cp.segs.slice(0, -1) : cp.segs;
+                if (mode === 'value' || isCallee || true)
+                    addDep(segs.length ? segs : null);
+            }
+        }
+        visitMemberParts(n, locals);
+    }
+    function visitMemberParts(n, locals) {
+        if (n.type === 'Identifier')
+            return ident(n, locals);
+        if (n.type === 'ChainExpression')
+            return visitMemberParts(n.expression, locals);
+        if (n.type !== 'MemberExpression')
+            return visit(n, locals);
+        const m = n;
+        if (m.object.type === 'Identifier' && page.namespaces.has(m.object.name) && !locals.has(m.object.name)) {
+            nsMember(m, locals);
+            return;
+        }
+        if (m.object.type === 'Identifier' && m.object.name === '$meta')
+            checkMeta(m, locals);
+        else if (m.object.type === 'MemberExpression') {
+            const root = leftmost(m);
+            if (root?.type === 'Identifier' && root.name === '$meta')
+                checkMeta(m, locals);
+        }
+        if (m.object.type === 'MemberExpression' || m.object.type === 'Identifier' || m.object.type === 'ChainExpression')
+            visitMemberParts(m.object, locals);
+        else
+            visit(m.object, locals);
+        if (!m.computed) {
+            const pn = m.property.name;
+            if (FORBIDDEN_KEYS.has(pn))
+                report('SN207', `access to \`.${pn}\` is not allowed`, m.property.start);
+        }
+        else if (m.property.type === 'Literal') {
+            if (FORBIDDEN_KEYS.has(String(m.property.value)))
+                report('SN207', `access to \`[${m.property.raw}]\` is not allowed`, m.property.start);
+        }
+        else {
+            edits.push({ start: m.property.start, end: m.property.start, text: '$k(' });
+            edits.push({ start: m.property.end, end: m.property.end, text: ')' });
+            visit(m.property, locals);
+        }
+    }
+    function leftmost(n) {
+        let cur = n;
+        while (cur.type === 'MemberExpression' || cur.type === 'CallExpression' || cur.type === 'ChainExpression') {
+            if (cur.type === 'MemberExpression')
+                cur = cur.object;
+            else if (cur.type === 'CallExpression')
+                cur = cur.callee;
+            else
+                cur = cur.expression;
+        }
+        return cur;
+    }
+    function nsMember(m, _locals) {
+        const ns = m.object.name;
+        if (m.computed) {
+            report('SN206', `namespace members must be named literally; \`${ns}[…]\` is refused. Put a dynamic choice in a helper`, m.start);
+            return;
+        }
+        const member = m.property.name;
+        const members = page.namespaces.get(ns);
+        if (!members.has(member)) {
+            report('SN206', `\`${ns}.${member}\` is not exported by namespace \`${ns}\`.${didYouMean(member, members)}`, m.start);
+            return;
+        }
+        if (!page.usedNs.has(ns))
+            page.usedNs.set(ns, new Set());
+        page.usedNs.get(ns).add(member);
+        addDep(['$locale']);
+        edits.push({ start: m.start, end: m.end, text: `${ns}$${member}` });
+    }
+    /**
+     * A write through a callback parameter that stands for "any element" (`data.forEach(row => row.x = 1)`)
+     * records the element at runtime: the expression is wrapped in `$.$m(row, …)` and its `*` becomes `~`,
+     * so only rows holding a marked element re-evaluate.
+     */
+    function track(cp, segs, expr) {
+        const alias = cp.res.kind === 'local' ? cp.res.info.alias : null;
+        if (!alias || alias[alias.length - 1] !== '*' || segs[alias.length - 1] !== '*')
+            return segs;
+        edits.push({ start: expr.start, end: expr.start, text: `$.$m(${cp.root}, ` }, { start: expr.end, end: expr.end, text: ')' });
+        return segs.map((x, i) => (i === alias.length - 1 ? '~' : x));
+    }
+    function writePath(target, locals, at, expr) {
+        if (target.type === 'Identifier' && target.name === '$locale') {
+            writes.add('$locale');
+            return;
+        }
+        if (target.type !== 'Identifier' && target.type !== 'MemberExpression') {
+            report('SN203', 'only state variables and their properties can be assigned', at);
+            return;
+        }
+        const cp = chainPath(target, locals);
+        if (!cp) {
+            report('SN203', 'only state variables and their properties can be assigned', at);
+            return;
+        }
+        if (cp.resource) {
+            report('SN205', `\`${src.slice(target.start, target.end)}\` mutates a resource. Use \`patch('${cp.resource}', …, {…})\``, at, 'resources are read-only in expressions; copy with structuredClone() to edit');
+            return;
+        }
+        if (cp.res.kind === 'magic' && cp.root === '$url') {
+            if (!cp.segs || cp.segs.length !== 2) {
+                report('SN203', 'assign a parameter: `$url.<param> = …`', at);
+                return;
+            }
+            if (page.pathParams.has(cp.segs[1])) {
+                report('SN203', `\`$url.${cp.segs[1]}\` is a path parameter (\`data-sn-path\`) and read-only; link to the other URL instead`, at);
+                return;
+            }
+            writes.add(cp.segs.join('.'));
+            return;
+        }
+        if (cp.res.kind === 'state' || ((cp.res.kind === 'loop' || cp.res.kind === 'local') && cp.segs)) {
+            if (cp.res.kind === 'loop' && cp.segs.length === (cp.res.entry.alias?.length ?? 0)) {
+                report('SN203', `loop variable \`${cp.root}\` cannot be reassigned`, at);
+                return;
+            }
+            writes.add(track(cp, cp.segs, expr).join('.'));
+            return;
+        }
+        report('SN203', `\`${src.slice(target.start, target.end)}\` cannot be assigned; only state variables, \`$url.<param>\` and \`$locale\` can`, at);
+    }
+    function visitCall(n, locals) {
+        const callee = (n.callee.type === 'ChainExpression' ? n.callee.expression : n.callee);
+        let elementInfo = null;
+        if (callee.type === 'MemberExpression') {
+            const m = callee;
+            const method = !m.computed && m.property.type === 'Identifier' ? m.property.name : null;
+            const isNs = m.object.type === 'Identifier' && page.namespaces.has(m.object.name) && !locals.has(m.object.name);
+            if (!isNs) {
+                const recv = chainPath(m.object, locals);
+                if (method && recv) {
+                    if (ELEMENT_CALLBACKS.has(method)) {
+                        elementInfo = { alias: recv.segs ? [...recv.segs, '*'] : null, resource: recv.resource };
+                    }
+                    if (!READ_ONLY.has(method)) {
+                        if (recv.resource && MUTATORS.has(method)) {
+                            report('SN205', `\`${src.slice(m.start, m.end)}()\` mutates a resource. Use \`patch('${recv.resource}', …)\` or copy with structuredClone()`, n.start);
+                        }
+                        else if (mode === 'value' && MUTATORS.has(method) && recv.segs && recv.res.kind === 'state') {
+                            report('SN203', `value expressions cannot change state; move \`${method}()\` to \`data-sn-on-*\``, n.start);
+                        }
+                        else if (mode === 'handler' && recv.segs && recv.res.kind !== 'magic' && !recv.resource) {
+                            // a known mutator changes the list structure (`#`), not the elements; unknown methods may change anything
+                            writes.add(track(recv, recv.segs, n).join('.') + (MUTATORS.has(method) ? '.#' : ''));
+                        }
+                        else if (mode === 'handler' && recv.segs && recv.root === '$url') {
+                            writes.add(recv.segs.slice(0, 2).join('.'));
+                        }
+                    }
+                }
+                // time and randomness
+                if (mode === 'value' && m.object.type === 'Identifier' && !m.computed) {
+                    const o = m.object.name, p = m.property.name;
+                    if ((o === 'Date' && p === 'now') || (o === 'Math' && p === 'random')) {
+                        report('SN502', `\`${o}.${p}()\` in a binding never updates. Use \`$now\``, n.start);
+                    }
+                }
+            }
+            visitChain(callee, locals, true);
+        }
+        else if (callee.type === 'Identifier') {
+            const res = resolveQuiet(callee.name, locals);
+            ident(callee, locals);
+            if (res?.kind === 'store')
+                storeCall(callee.name, n);
+            else if (res?.kind === 'helper') {
+                if (BUILTIN_HELPERS.includes(callee.name))
+                    addDep(['$locale']);
+                else if (mode === 'handler') {
+                    for (const a of n.arguments) {
+                        const cp = a.type === 'Identifier' || a.type === 'MemberExpression' ? chainPath(a, locals) : null;
+                        if (cp?.segs && cp.res.kind === 'state')
+                            writes.add(cp.segs.slice(0, 2).join('.'));
+                    }
+                }
+            }
+        }
+        else {
+            visit(callee, locals);
+        }
+        for (const a of n.arguments) {
+            if (a.type === 'ArrowFunctionExpression')
+                visitFunction(a, locals, elementInfo);
+            else
+                visit(a, locals);
+        }
+    }
+    function storeCall(name, n) {
+        if (mode === 'value') {
+            report('SN203', `value expressions cannot call \`${name}()\`; move it to a handler`, n.start);
+            return;
+        }
+        const first = n.arguments[0];
+        if (['refresh', 'upsert', 'patch', 'remove', 'page'].includes(name)) {
+            if (!first || first.type !== 'Literal' || typeof first.value !== 'string') {
+                report('SN301', `\`${name}()\` takes the resource name as a string literal`, n.start);
+                return;
+            }
+            const r = page.resources.get(first.value);
+            if (!r) {
+                report('SN301', `resource \`${first.value}\` is not declared on this page.${didYouMean(first.value, page.resources.keys())}`, first.start);
+                return;
+            }
+            if (name === 'page') {
+                if (!r.paginate)
+                    report('SN303', `\`${first.value}\` has no \`paginate\`; \`page()\` needs a paginated resource`, n.start);
+                const target = n.arguments[1];
+                const named = target?.type === 'Literal' && typeof target.value === 'string' ? target.value : null;
+                if (r.paginate && r.paginate !== 'offset' && !named && !(r.paginate === 'keyset' && r.jumps)) {
+                    report('SN304', r.paginate === 'keyset'
+                        ? 'keyset pagination cannot jump to a page number. Add `offset-param` if the server also accepts an offset, or use `paginate="offset"`'
+                        : 'keyset pagination cannot jump to a page number. Use `paginate="offset"`', target?.start ?? n.start);
+                }
+                else if (r.paginate === 'append' && named && named !== 'next') {
+                    report('SN304', '`append` pagination only supports `page(…, \'next\')`', target.start);
+                }
+                else if (named && !['first', 'prev', 'next', 'last'].includes(named)) {
+                    report('SN401', `\`page()\` targets are 'first', 'prev', 'next', 'last' or a page number`, target.start);
+                }
+            }
+        }
+    }
+    function visit(n, locals) {
+        switch (n.type) {
+            case 'Identifier': {
+                const res = resolveQuiet(n.name, locals);
+                if (res) {
+                    const b = basePath(n.name, res);
+                    addDep(b.segs);
+                }
+                ident(n, locals);
+                return;
+            }
+            case 'MemberExpression':
+            case 'ChainExpression':
+                visitChain(n, locals, false);
+                return;
+            case 'CallExpression':
+                visitCall(n, locals);
+                return;
+            case 'NewExpression':
+                if (mode === 'value' && n.callee.type === 'Identifier' && n.callee.name === 'Date' && n.arguments.length === 0) {
+                    report('SN502', '`new Date()` in a binding never updates. Use `$now`', n.start);
+                }
+                visit(n.callee, locals);
+                for (const a of n.arguments)
+                    visit(a, locals);
+                return;
+            case 'ArrowFunctionExpression':
+                visitFunction(n, locals, null);
+                return;
+            case 'FunctionExpression':
+                report('SN203', 'use an arrow function instead of `function`', n.start);
+                return;
+            case 'ClassExpression':
+                report('SN203', 'classes are not allowed in expressions', n.start);
+                return;
+            case 'AssignmentExpression': {
+                if (mode !== 'handler') {
+                    report('SN203', mode === 'optimistic' ? '`data-sn-optimistic` may only call `patch`, `upsert`, `remove`' : 'value expressions cannot assign; move this to `data-sn-on-*`', n.start);
+                    return;
+                }
+                if (n.left.type === 'ObjectPattern' || n.left.type === 'ArrayPattern') {
+                    report('SN203', 'destructuring assignment is not supported in handlers', n.start);
+                    return;
+                }
+                writePath(n.left, locals, n.start, n);
+                visitMemberParts(n.left, locals);
+                visit(n.right, locals);
+                return;
+            }
+            case 'UpdateExpression':
+                if (mode !== 'handler') {
+                    report('SN203', 'value expressions cannot use `++`/`--`; move this to `data-sn-on-*`', n.start);
+                    return;
+                }
+                writePath(n.argument, locals, n.start, n);
+                visitMemberParts(n.argument, locals);
+                return;
+            case 'UnaryExpression':
+                if (n.operator === 'delete') {
+                    if (mode !== 'handler') {
+                        report('SN203', 'value expressions cannot use `delete`', n.start);
+                        return;
+                    }
+                    writePath(n.argument, locals, n.start, n);
+                    visitMemberParts(n.argument, locals);
+                    return;
+                }
+                visit(n.argument, locals);
+                return;
+            case 'AwaitExpression':
+                report('SN203', '`await` is not allowed in expressions', n.start);
+                return;
+            case 'ImportExpression':
+                report('SN203', '`import()` is not allowed in expressions', n.start);
+                return;
+            case 'YieldExpression':
+                report('SN203', '`yield` is not allowed in expressions', n.start);
+                return;
+            case 'ThisExpression':
+                report('SN202', '`this` is not available in expressions; use `$el`', n.start);
+                return;
+            case 'MetaProperty':
+                report('SN202', `\`${src.slice(n.start, n.end)}\` is not available in expressions`, n.start);
+                return;
+            case 'ObjectExpression':
+                for (const p of n.properties) {
+                    if (p.type === 'SpreadElement') {
+                        visit(p.argument, locals);
+                        continue;
+                    }
+                    if (p.computed)
+                        visit(p.key, locals);
+                    if (p.shorthand && p.value.type === 'Identifier') {
+                        const res = resolveQuiet(p.value.name, locals);
+                        if (res)
+                            addDep(basePath(p.value.name, res).segs);
+                        ident(p.value, locals, true);
+                    }
+                    else if (p.kind !== 'init' || p.method) {
+                        report('SN203', 'methods and accessors are not allowed in object literals', p.start);
+                    }
+                    else
+                        visit(p.value, locals);
+                }
+                return;
+            case 'TaggedTemplateExpression':
+                visit(n.tag, locals);
+                visit(n.quasi, locals);
+                return;
+            case 'SequenceExpression':
+                for (const e of n.expressions)
+                    visit(e, locals);
+                return;
+            default:
+                for (const key of Object.keys(n)) {
+                    if (key === 'type' || key === 'start' || key === 'end' || key === 'loc' || key === 'range')
+                        continue;
+                    const v = n[key];
+                    if (Array.isArray(v)) {
+                        for (const c of v)
+                            if (c && typeof c === 'object' && 'type' in c)
+                                visit(c, locals);
+                    }
+                    else if (v && typeof v === 'object' && 'type' in v)
+                        visit(v, locals);
+                }
+        }
+    }
+    // ---- optimistic: only patch/upsert/remove calls
+    function checkOptimistic(e) {
+        if (e.type !== 'CallExpression' || e.callee.type !== 'Identifier' || !['patch', 'upsert', 'remove'].includes(e.callee.name)) {
+            report('SN204', '`data-sn-optimistic` may only call `patch`, `upsert`, `remove`', e.start, 'local state and side effects cannot be rolled back; put them in `data-sn-then`');
+            return false;
+        }
+        return true;
+    }
+    // ---- objects
+    let entries;
+    const root = new Map();
+    if (opts.object) {
+        if (ast.type !== 'ObjectExpression') {
+            report('SN401', 'expected an object literal `{ … }`', 0);
+            return fail();
+        }
+        entries = [];
+        for (const p of ast.properties) {
+            if (p.type === 'SpreadElement') {
+                report(opts.object === 'state' ? 'SN401' : 'SN207', 'spread (`...`) is not allowed here; list each key literally', p.start);
+                continue;
+            }
+            let key;
+            if (!p.computed && p.key.type === 'Identifier')
+                key = p.key.name;
+            else if (p.key.type === 'Literal' && !p.computed)
+                key = String(p.key.value);
+            else if (opts.object === 'any-keys')
+                key = '';
+            else {
+                report(opts.object === 'state' ? 'SN401' : 'SN207', 'keys must be literal; computed keys are not allowed here', p.start);
+                continue;
+            }
+            if (p.kind !== 'init' || p.method) {
+                report('SN203', 'methods and accessors are not allowed in object literals', p.start);
+                continue;
+            }
+            const depsBefore = new Set(deps);
+            deps.clear();
+            if (p.computed)
+                visit(p.key, root);
+            if (p.shorthand && p.value.type === 'Identifier') {
+                const res = resolveQuiet(p.value.name, root);
+                if (res)
+                    addDep(basePath(p.value.name, res).segs);
+                ident(p.value, root, true);
+            }
+            else
+                visit(p.value, root);
+            const own = [...deps];
+            for (const d of depsBefore)
+                deps.add(d);
+            entries.push({ key, code: '', deps: own, offset: p.start, literal: p.value.type === 'Literal' });
+        }
+    }
+    else {
+        for (const e of body) {
+            if (mode === 'optimistic' && !checkOptimistic(e))
+                continue;
+            if (mode === 'optimistic') {
+                // arguments are read like values; only the call itself is allowed
+                const c = e;
+                ident(c.callee, root);
+                storeCall(c.callee.name, c);
+                for (const a of c.arguments)
+                    visit(a, root);
+            }
+            else
+                visit(e, root);
+        }
+    }
+    // ---- codegen
+    const out = applyEdits(src, edits);
+    let code;
+    if (mode === 'value' || opts.object)
+        code = `($) => (${out})`;
+    else
+        code = `($) => {${out}\n}`;
+    if (entries && opts.object) {
+        // per-entry code for object literals, so bindings can write key by key
+        const slice = (start, end) => applyEdits(src.slice(start, end), edits.filter((e) => e.start >= start && e.end <= end).map((e) => ({ ...e, start: e.start - start, end: e.end - start })));
+        let i = 0;
+        for (const p of ast.properties) {
+            if (p.type === 'SpreadElement')
+                continue;
+            const entry = entries[i];
+            if (!entry || entry.offset !== p.start)
+                continue;
+            let value = slice(p.value.start, p.value.end);
+            if (p.shorthand)
+                value = value.slice(value.indexOf(': ') + 2);
+            entry.code = p.computed ? `($) => [${slice(p.key.start, p.key.end)}, ${value}]` : `($) => (${value})`;
+            i++;
+        }
+    }
+    let path = null;
+    let resource = null;
+    if (body.length === 1 && !opts.object) {
+        const e = body[0];
+        if (e.type === 'Identifier' || e.type === 'MemberExpression') {
+            const cp = chainPath(e, root);
+            if (cp) {
+                path = cp.segs;
+                resource = cp.resource;
+            }
+        }
+        if (!resource) {
+            const l = leftmost(e);
+            if (l?.type === 'Identifier') {
+                const res = resolveQuiet(l.name, root);
+                if (res)
+                    resource = basePath(l.name, res).resource;
+            }
+        }
+    }
+    return { ok, code, deps: [...deps].sort(), writes: [...writes].sort(), usesEl, usesIndex, entries, path, resource, ast, ...(opts.payload ? { payloadNames: [...payloadNames].sort(), payloadStates: [...payloadStates].sort() } : {}) };
+}
+export function applyEdits(src, edits) {
+    const sorted = [...edits].sort((a, b) => b.start - a.start || (b.end - b.start) - (a.end - a.start));
+    let out = src;
+    for (const e of sorted)
+        out = out.slice(0, e.start) + e.text + out.slice(e.end);
+    return out;
+}