@tiaforge-ui/sinter 0.2.0 → 0.3.1

package/README.md

@@ -96,7 +96,7 @@ Measurements and sources: [`docs/realworld-comparison.md`](docs/realworld-compar
   islands, which are plain custom elements.
 - You can't have a build step.
 - Your backend renders HTML, not JSON.
-- You need stability guarantees. sinter is at v0.2.
+- You need stability guarantees. sinter is at v0.3.
 
 ## Setup
 
@@ -147,12 +147,13 @@ Then write `data-sn-*` attributes in your HTML pages. Optional:
 ## Development
 
 ```sh
-npm test          # vitest (happy-dom)
+npm test          # vitest (happy-dom); CI runs typecheck, build and tests on every push (Node 22/24/26)
 npm run typecheck
 npm run build     # dist/
 npm run size      # size per page and module, with budgets
 npm run bench     # store and flush benchmarks (docs/benchmark.md)
 npm run docs      # regenerate llms.txt, html-custom-data.json (also the VS Code extension's) and docs/diagnostics.md
+npm run release -- 0.3.0   # bump versions, date the changelog, commit "Release 0.3.0", tag v0.3.0 (not pushed)
 ```
 
 License: MIT. Contributions are accepted under the Developer Certificate of Origin

package/dist/cache.js

@@ -68,22 +68,29 @@ const cache = {
             loaded(def, r, url, items, total, appended) {
                 let t = tracked.get(def.name);
                 if (!t) {
-                    const entry = (t = { def, r, url, dirty: false, appended });
+                    const entry = (t = { def, r, url, dirty: false, appended, off: false });
                     // confirmed changes after the load (server events, action results); layers never fire this
                     r.subscribe(() => { entry.dirty = true; });
                     tracked.set(def.name, t);
                 }
                 t.url = url;
                 t.appended = appended;
+                t.off = false;
                 // `append` caches only its first page: later pages would be shown as if they were it
                 if (!appended)
                     write(def, url, items, total);
                 t.dirty = false;
             },
+            // the emptied resource must not replace the entry of its last URL
+            cleared(def) {
+                const t = tracked.get(def.name);
+                if (t)
+                    t.off = true;
+            },
         };
         app.addCleanup(app.env.listen('pagehide', () => {
             for (const t of tracked.values()) {
-                if (!t.dirty || t.appended || t.def.paginate?.mode == 'append')
+                if (!t.dirty || t.off || t.appended || t.def.paginate?.mode == 'append')
                     continue;
                 const b = t.r.base();
                 write(t.def, t.url, b.items, b.total);

package/dist/check/index.js

@@ -64,7 +64,8 @@ export function check(o) {
     const tsconfig = join(outDir, 'tsconfig.json');
     writeFileSync(tsconfig, JSON.stringify({
         compilerOptions: COMPILER_OPTIONS,
-        files: ['sinter.d.ts', ...support.openapi.map((f) => relative(outDir, f)), ...[...shadows.keys()].map((f) => relative(outDir, f).split('\\').join('/'))],
+        // the types module always, so augmentations in it (declare global, a library's import type {}) apply
+        files: ['sinter.d.ts', ...(support.types ? [relative(outDir, support.types.file).split('\\').join('/')] : []), ...support.openapi.map((f) => relative(outDir, f)), ...[...shadows.keys()].map((f) => relative(outDir, f).split('\\').join('/'))],
     }, null, 2) + '\n');
     const tsc = o.tsc ?? findTsc(o.root);
     const run = spawnSync(process.execPath, [tsc, '-p', tsconfig, '--pretty', 'false'], { encoding: 'utf8', cwd: outDir });

package/dist/check/shadow.d.ts

@@ -38,7 +38,7 @@ export declare function shadow(o: ShadowOptions): Shadow;
 /** Maps a 1-based shadow position to the HTML, or null for generated lines. */
 export declare function mapPosition(regions: Region[], line: number, col: number): CheckLoc | null;
 /** `sinter.d.ts`: the types the shadow files refer to. */
-export declare const DECLARATIONS = "// Generated by `sinter check`. Do not edit.\nexport interface Meta {\n  loading: boolean;\n  error: Err | null;\n  loadedAt: number | null;\n  pending: number;\n  total: number | null;\n  page?: number | null;\n  pages?: number | null;\n  from?: number | null;\n  to?: number | null;\n  hasPrev?: boolean;\n  hasNext?: boolean;\n}\nexport interface Err { status: number | null; body: any; message: string }\nexport interface CallContext { signal: AbortSignal; request(url: string, init?: { method?: string; body?: unknown; headers?: Record<string, string>; signal?: AbortSignal }): Promise<any>; el: Element | null }\n/** an action's parameters without its trailing context */\nexport type CallArgs<F> = F extends (...a: infer P) => any ? (P extends [...infer A, infer L] ? ([L] extends [CallContext] ? A : P) : P) : never;\nexport type Item<T> = NonNullable<T> extends readonly (infer U)[] ? U : NonNullable<T> extends Iterable<infer U> ? U : any;\nexport type El<K extends string> = K extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[K] : HTMLElement;\nexport type Ev<K extends string> = K extends keyof HTMLElementEventMap ? HTMLElementEventMap[K] : CustomEvent;\nexport interface Store<R> {\n  refresh(name: keyof R & string): void;\n  upsert<K extends keyof R & string>(name: K, item: Item<R[K]>): void;\n  patch<K extends keyof R & string>(name: K, item: Partial<Item<R[K]>>, set: Partial<Item<R[K]>>): void;\n  remove<K extends keyof R & string>(name: K, item: Partial<Item<R[K]>>): void;\n  page(name: keyof R & string, to: 'next' | 'prev' | 'first' | 'last' | number): void;\n  close(): void;\n  reset(): void;\n  emit(event: string, detail?: unknown): void;\n}\ntype Style = 'short' | 'medium' | 'long' | 'full';\nexport function date(v: unknown, style?: Style): string;\nexport function time(v: unknown, style?: Style): string;\nexport function datetime(v: unknown, style?: Style): string;\nexport function relative(v: unknown, now?: unknown): string;\nexport function number(v: unknown, opts?: Intl.NumberFormatOptions): string;\nexport function bytes(v: unknown): string;\n";
+export declare const DECLARATIONS = "// Generated by `sinter check`. Do not edit.\nexport interface Meta {\n  loading: boolean;\n  error: Err | null;\n  loadedAt: number | null;\n  pending: number;\n  total: number | null;\n  page?: number | null;\n  pages?: number | null;\n  from?: number | null;\n  to?: number | null;\n  hasPrev?: boolean;\n  hasNext?: boolean;\n}\nexport interface Err { status: number | null; body: any; message: string; detail: string | null }\ndeclare global {\n  /**\n   * Value types for attributes bound with data-sn-attr. Empty here; a library extends it to type its own\n   * attributes, e.g. tinystyle (import type {} from '@tiaforge-ui/tinystyle/sinter' in the types module).\n   */\n  interface SinterAttributes {}\n}\n/** what data-sn-attr accepts: the keys SinterAttributes types, anything else as before */\nexport type Attrs = { [K in keyof SinterAttributes]?: SinterAttributes[K] } & Record<string, unknown>;\nexport interface CallContext { signal: AbortSignal; request(url: string, init?: { method?: string; body?: unknown; headers?: Record<string, string>; signal?: AbortSignal }): Promise<any>; el: Element | null }\n/** an action's parameters without its trailing context */\nexport type CallArgs<F> = F extends (...a: infer P) => any ? (P extends [...infer A, infer L] ? ([L] extends [CallContext] ? A : P) : P) : never;\nexport type Item<T> = NonNullable<T> extends readonly (infer U)[] ? U : NonNullable<T> extends Iterable<infer U> ? U : any;\nexport type El<K extends string> = K extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[K] : HTMLElement;\nexport type Ev<K extends string> = K extends keyof HTMLElementEventMap ? HTMLElementEventMap[K] : CustomEvent;\nexport interface Store<R> {\n  refresh(name: keyof R & string): void;\n  upsert<K extends keyof R & string>(name: K, item: Item<R[K]>): void;\n  patch<K extends keyof R & string>(name: K, item: Partial<Item<R[K]>>, set: Partial<Item<R[K]>>): void;\n  remove<K extends keyof R & string>(name: K, item: Partial<Item<R[K]>>): void;\n  page(name: keyof R & string, to: 'next' | 'prev' | 'first' | 'last' | number): void;\n  showModal(id: string): void;\n  close(id?: string): void;\n  reset(): void;\n  emit(event: string, detail?: unknown): void;\n}\ntype Style = 'short' | 'medium' | 'long' | 'full';\nexport function date(v: unknown, style?: Style): string;\nexport function time(v: unknown, style?: Style): string;\nexport function datetime(v: unknown, style?: Style): string;\nexport function relative(v: unknown, now?: unknown): string;\nexport function number(v: unknown, opts?: Intl.NumberFormatOptions): string;\nexport function bytes(v: unknown): string;\n";
 /**
  * Maps a 1-based position in an HTML file to the shadow, or null when it is not inside an
  * expression. `lines` are the shadow's lines.

package/dist/check/shadow.js

@@ -103,7 +103,7 @@ export function shadow(o) {
     line('/** @type {string} */');
     line('let $locale = $any;');
     line(`/** @type {${decl('Store')}<{ ${types.join('; ')} }>} */`);
-    line(`const { ${STORE_FNS.join(', ')} } = $any;`);
+    line(`const { ${STORE_FNS.filter((f) => !unit.resources.some((r) => r.name === f)).join(', ')} } = $any;`);
     line(`/** @template T @param {T} list @returns {${decl('Item')}<T>} */`);
     line('function $item(list) { return $any; }');
     /** a JSDoc tag with a type; a type the app wrote maps its errors to where it was written */
@@ -115,7 +115,7 @@ export function shadow(o) {
             line(`} */${after}`);
             return;
         }
-        const text = t.kind === 'openapi'
+        const text = t.kind === 'decl' ? decl(t.name) : t.kind === 'openapi'
             ? schemaToTs(t.schema, (n) => `$O${t.spec}.${typeName(n)}`)
             : t.kind === 'call'
                 ? (t.args ? `${decl('CallArgs')}<typeof $A.${t.name}>` : `Awaited<ReturnType<typeof $A.${t.name}>>`)
@@ -135,6 +135,10 @@ export function shadow(o) {
                 f.names.forEach((n, k) => { at(f.locs?.[k]); line(`${n},`); });
                 line(`} = ${f.init === null ? '$any' : `$e${f.init}()`};`);
             }
+            else if (f.kind === 'let') {
+                at(f.loc);
+                line(`const ${f.name} = ${f.init === null ? '$any' : `$e${f.init}()`};`);
+            }
             else {
                 at(f.loc);
                 line(`const ${f.item} = ${f.init === null ? '$any' : `$item($e${f.init}())`};`);
@@ -233,7 +237,16 @@ export interface Meta {
   hasPrev?: boolean;
   hasNext?: boolean;
 }
-export interface Err { status: number | null; body: any; message: string }
+export interface Err { status: number | null; body: any; message: string; detail: string | null }
+declare global {
+  /**
+   * Value types for attributes bound with data-sn-attr. Empty here; a library extends it to type its own
+   * attributes, e.g. tinystyle (import type {} from '@tiaforge-ui/tinystyle/sinter' in the types module).
+   */
+  interface SinterAttributes {}
+}
+/** what data-sn-attr accepts: the keys SinterAttributes types, anything else as before */
+export type Attrs = { [K in keyof SinterAttributes]?: SinterAttributes[K] } & Record<string, unknown>;
 export interface CallContext { signal: AbortSignal; request(url: string, init?: { method?: string; body?: unknown; headers?: Record<string, string>; signal?: AbortSignal }): Promise<any>; el: Element | null }
 /** an action's parameters without its trailing context */
 export type CallArgs<F> = F extends (...a: infer P) => any ? (P extends [...infer A, infer L] ? ([L] extends [CallContext] ? A : P) : P) : never;
@@ -246,7 +259,8 @@ export interface Store<R> {
   patch<K extends keyof R & string>(name: K, item: Partial<Item<R[K]>>, set: Partial<Item<R[K]>>): void;
   remove<K extends keyof R & string>(name: K, item: Partial<Item<R[K]>>): void;
   page(name: keyof R & string, to: 'next' | 'prev' | 'first' | 'last' | number): void;
-  close(): void;
+  showModal(id: string): void;
+  close(id?: string): void;
   reset(): void;
   emit(event: string, detail?: unknown): void;
 }

package/dist/compiler/check-unit.d.ts

@@ -7,7 +7,7 @@ export interface CheckLoc {
     chain: string[];
 }
 /**
- * A scope frame: a `data-sn-state` object or a `data-sn-for` loop. `init` is the
+ * A scope frame: a `data-sn-state` object, a `data-sn-for` loop or a `data-sn-let` name. `init` is the
  * expression that creates it (the state literal, the list), or null when that
  * expression did not compile.
  */
@@ -27,6 +27,13 @@ export type CheckFrame =
     init: number | null;
     loc?: CheckLoc;
     indexLoc?: CheckLoc;
+}
+/** a `data-sn-let` name; `loc`: where the name is written */
+ | {
+    kind: 'let';
+    name: string;
+    init: number | null;
+    loc?: CheckLoc;
 };
 /** A type the checker writes for something other than a resource. */
 export type TypeRef = 
@@ -53,13 +60,18 @@ export type TypeRef =
     kind: 'call';
     name: string;
     args?: boolean;
+}
+/** a type sinter declares itself (\`Attrs\` for \`data-sn-attr\`) */
+ | {
+    kind: 'decl';
+    name: string;
 };
 export interface CheckExpr {
     src: string;
     /** `value` returns the expression; `handler` runs it as statements */
     mode: 'value' | 'handler';
     loc: CheckLoc;
-    /** frames visible here, in the order sinter resolves them last: states outer to inner, then loops outer to inner */
+    /** frames visible here, in the order sinter resolves them last: states, then loops, then lets, each outer to inner */
     frames: number[];
     /** tag of the element the expression sits on, for `$el` */
     tag: string;

package/dist/compiler/compile.js

@@ -3,12 +3,12 @@
 import * as parse5 from 'parse5';
 import { parseExpressionAt } from 'acorn';
 import { didYouMean, severityOf } from './diagnostics.js';
-import { analyze } from './expr.js';
+import { analyze, STORE_FNS } from './expr.js';
 import { ATTRIBUTES, ELEMENTS } from './vocabulary.js';
 import { matchOperation, matchResource, queryNames, walk } from './openapi.js';
 const ATTRS = ATTRIBUTES.map((a) => a.name);
 const METHODS = ['get', 'post', 'put', 'patch', 'delete'];
-const ACTION_ONLY = ['body', 'trigger', 'debounce', 'concurrency', 'optimistic', 'then', 'catch'];
+const ACTION_ONLY = ['body', 'trigger', 'debounce', 'concurrency', 'optimistic', 'then', 'catch', 'confirm', 'encoding'];
 const UNSAFE_ELEMENTS = new Set(['script', 'style', 'iframe', 'object', 'embed', 'base', 'meta', 'link', 'animate', 'set', 'animatemotion', 'animatetransform']);
 const FORM_CONTROLS = new Set(['input', 'select', 'textarea']);
 const RESOURCE_ATTRS = ELEMENTS.find((e) => e.name === 'sn-resource').attrs;
@@ -55,7 +55,7 @@ class Compiler {
         this.page = {
             resources: new Map(), helpers: new Set(opts.helpers.names), namespaces: ns,
             actions: new Set([...(opts.actions?.names ?? []), ...Object.keys(opts.actions?.namespaces ?? {})]),
-            usedHelpers: new Set(), usedNs: new Map(), usesNow: false, pathParams: new Set(),
+            usedHelpers: new Set(), usedNs: new Map(), usesNow: false, pathParams: new Set(), dialogs: new Set(),
         };
     }
     run(html) {
@@ -100,7 +100,7 @@ class Compiler {
         return {
             html: parse5.serialize(doc),
             ir, fns: this.fns,
-            features: [...(this.opts.dev ? ['dev'] : []), ...['sse', 'optimistic', 'paginate', 'persist', 'cache', 'each'].filter((f) => this.features.has(f))],
+            features: [...(this.opts.dev ? ['dev'] : []), ...['sse', 'optimistic', 'paginate', 'persist', 'cache', 'each', 'listbox'].filter((f) => this.features.has(f))],
             helpers: { user, builtin }, namespaces, calls: [...this.calls].sort(),
             diagnostics: this.diagnostics, files: [...this.files].sort(),
             ...(this.check ? { check: this.check } : {}),
@@ -321,7 +321,7 @@ class Compiler {
         // the browser merges adjacent text when it parses the output; merge now so node paths agree
         mergeText(parent);
     }
-    // ---- declarations (first pass: names only, so expressions can see every resource)
+    // ---- declarations (first pass: names only, so expressions can see every resource and dialog)
     declare(parent, inTemplate = false) {
         for (const child of parent.childNodes) {
             if (!isElement(child))
@@ -340,6 +340,10 @@ class Compiler {
                     this.report(child, 'name', 'SN302', `resource \`${name}\` is declared twice`, 0);
                     continue;
                 }
+                if (STORE_FNS.includes(name)) {
+                    this.report(child, 'name', 'SN209', `\`${name}\` is a store function (\`${name}()\`); a resource cannot take its name`, 0);
+                    continue;
+                }
                 const key = attr(child, 'key');
                 const paginate = attr(child, 'paginate');
                 const info = { name, key: key ? key.split(',').map((s) => s.trim()).filter(Boolean) : null, paginate: paginate ?? null, used: false };
@@ -349,6 +353,11 @@ class Compiler {
                 this.resourceEls.set(name, child);
                 continue;
             }
+            if (child.tagName === 'dialog') {
+                const id = attr(child, 'id');
+                if (id)
+                    this.page.dialogs.add(id);
+            }
             this.declare(child, inTemplate);
             if (child.tagName === 'template')
                 this.declare(child.content, true);
@@ -412,7 +421,7 @@ class Compiler {
         // unknown attributes
         const known = new Set(ATTRS.map((a) => `data-sn-${a}`));
         for (const a of sn) {
-            if (known.has(a.name) || a.name.startsWith('data-sn-on-'))
+            if (known.has(a.name) || a.name.startsWith('data-sn-on-') || a.name.startsWith('data-sn-debounce-'))
                 continue;
             this.report(el, a.name, 'SN101', `\`${a.name}\` is not a sinter attribute.${didYouMean(a.name, [...known, 'data-sn-on-click'])}`, 0);
         }
@@ -466,13 +475,32 @@ class Compiler {
                     const locs = first.map((e) => this.locOf(el, 'data-sn-state', e.offset));
                     this.check.frames.push({ kind: 'state', names: [...entry.names], init: this.lastExpr, locs });
                 }
-                scope = { loops: scope.loops, states: [...scope.states, entry] };
+                this.checkNames(el, 'data-sn-state', scope, [...entry.names]);
+                scope = { ...scope, states: [...scope.states, entry] };
                 if (has('persist') && !has('model')) {
                     node.persist = get('persist');
                     this.features.add('persist');
                 }
             }
         }
+        // derived names: the element and its subtree read them like state
+        if (has('let'))
+            scope = this.lets(el, scope);
+        // a text field with suggestions: the listbox feature handles the keys (see src/listbox.ts)
+        if (has('listbox')) {
+            const list = get('listbox');
+            if (!['input', 'textarea'].includes(el.tagName))
+                this.report(el, 'data-sn-listbox', 'SN102', '`data-sn-listbox` belongs on a text `<input>` or `<textarea>`', 0);
+            else if (list && !/^[A-Za-z][\w-]*$/.test(list))
+                this.report(el, 'data-sn-listbox', 'SN401', '`data-sn-listbox` takes the literal `id` of the suggestion list, or nothing for the nearest `[role="listbox"]` around the input', 0);
+            else {
+                setAttr(el, 'role', 'combobox');
+                if (list)
+                    setAttr(el, 'aria-controls', list);
+                setAttr(el, 'aria-autocomplete', 'list');
+                this.features.add('listbox');
+            }
+        }
         const isTemplate = el.tagName === 'template';
         const valueB = (k, name) => {
             const r = this.expr(el, name, scope, { mode: 'value' });
@@ -516,6 +544,16 @@ class Compiler {
             if (!sn.some((a) => a.name.startsWith('data-sn-on-')))
                 this.report(el, 'data-sn-debounce', 'SN102', '`data-sn-debounce` needs a method attribute (`data-sn-get`, `-post`, …) or a `data-sn-on-*` handler on the same element', 0);
         }
+        // `data-sn-debounce-<event>`: only that event's handler waits
+        for (const a of sn) {
+            if (!a.name.startsWith('data-sn-debounce-'))
+                continue;
+            const event = a.name.slice('data-sn-debounce-'.length), ms = Number(a.value);
+            if (!Number.isFinite(ms) || ms < 0 || a.value.trim() === '')
+                this.report(el, a.name, 'SN401', `\`${a.name}\` takes milliseconds`, 0);
+            if (!has(`on-${event}`))
+                this.report(el, a.name, 'SN102', `\`${a.name}\` needs a \`data-sn-on-${event}\` handler on the same element`, 0);
+        }
         for (const a of sn) {
             if (!a.name.startsWith('data-sn-on-'))
                 continue;
@@ -525,8 +563,9 @@ class Compiler {
                 continue;
             }
             const r = this.expr(el, a.name, scope, { mode: 'handler', magic: ['$event'] });
+            const own = get(`debounce-${event}`), ms = own !== undefined ? Number(own) || 0 : handlerDebounce;
             if (r.ok)
-                node.b.push(binding({ k: 'on', n: event, f: this.fn(r.code), w: r.writes, ...(handlerDebounce > 0 ? { ms: handlerDebounce } : {}) }));
+                node.b.push(binding({ k: 'on', n: event, f: this.fn(r.code), w: r.writes, ...(ms > 0 ? { ms } : {}) }));
         }
         if (methods.length > 1)
             this.report(el, `data-sn-${methods[1]}`, 'SN102', 'an element can have only one method attribute', 0);
@@ -627,6 +666,61 @@ class Compiler {
         }
         return r;
     }
+    // ---- derived names
+    /**
+     * `data-sn-let="{ s: suggestions(q), n: s.length }"`: each name is a value expression, inlined
+     * where it is read; later names may use earlier ones.
+     */
+    lets(el, scope) {
+        const src = attr(el, 'data-sn-let') ?? '';
+        let obj;
+        try {
+            obj = parseExpressionAt(src, 0, { ecmaVersion: 'latest' });
+        }
+        catch (e) {
+            this.report(el, 'data-sn-let', 'SN401', e.message.replace(/ \(\d+:\d+\)$/, ''), e.pos ?? 0);
+            return scope;
+        }
+        if (obj.type !== 'ObjectExpression') {
+            this.report(el, 'data-sn-let', 'SN401', '`data-sn-let` takes an object literal: `{ name: expression, … }`', 0);
+            return scope;
+        }
+        for (const p of obj.properties) {
+            if (p.type !== 'Property' || p.computed || p.shorthand || p.key.type !== 'Identifier' || p.kind !== 'init' || p.method) {
+                this.report(el, 'data-sn-let', 'SN401', '`data-sn-let` entries are `name: expression`', p.start);
+                continue;
+            }
+            const name = p.key.name;
+            if (name.startsWith('$')) {
+                this.report(el, 'data-sn-let', 'SN401', 'names starting with `$` are reserved', p.key.start);
+                continue;
+            }
+            if (!this.checkNames(el, 'data-sn-let', scope, [name], p.key.start))
+                continue;
+            const v = p.value;
+            const r = this.expr(el, 'data-sn-let', scope, { mode: 'value' }, src.slice(v.start, v.end), v.start);
+            const entry = { name, code: r.inner, deps: r.deps, usesEl: r.usesEl, usesIndex: r.usesIndex, resource: r.resource };
+            if (this.check) {
+                this.frameOf.set(entry, this.check.frames.length);
+                this.check.frames.push({ kind: 'let', name, init: r.ok ? this.lastExpr : null, loc: this.locOf(el, 'data-sn-let', p.key.start) });
+            }
+            scope = { ...scope, lets: [...(scope.lets ?? []), entry] };
+        }
+        return scope;
+    }
+    /** A name declared here must not hide a let, or be hidden by one (SN209); false on a conflict. */
+    checkNames(el, attrName, scope, names, offset = 0) {
+        let ok = true;
+        for (const n of names) {
+            const isLet = (scope.lets ?? []).some((l) => l.name === n);
+            const other = attrName === 'data-sn-let' && (scope.loops.some((l) => l.name === n) || scope.states.some((s) => s.names.has(n)));
+            if (isLet || other) {
+                this.report(el, attrName, 'SN209', `\`${n}\` is already defined here${isLet ? ' by `data-sn-let`' : ''}; use another name`, offset);
+                ok = false;
+            }
+        }
+        return ok;
+    }
     // ---- check unit
     /** Adds type information to the expression `expr()` recorded last. */
     typeLast(info) {
@@ -647,7 +741,7 @@ class Compiler {
     }
     recordExpr(el, attrName, scope, o, src, shift, r) {
         const frames = [];
-        for (const f of [...scope.states, ...scope.loops]) {
+        for (const f of [...scope.states, ...scope.loops, ...(scope.lets ?? [])]) {
             const i = this.frameOf.get(f);
             if (i !== undefined && !frames.includes(i))
                 frames.push(i);
@@ -670,6 +764,8 @@ class Compiler {
     // ---- bindings
     attrBinding(el, node, scope) {
         const r = this.expr(el, 'data-sn-attr', scope, { mode: 'value', object: 'literal-keys' });
+        if (this.check)
+            this.typeLast({ returns: { kind: 'decl', name: 'Attrs' } });
         if (!r.entries)
             return;
         for (const e of r.entries) {
@@ -801,10 +897,18 @@ class Compiler {
         const then = fnOf('then', { mode: 'handler', magic: ['$event', '$result'] }, typed?.body != null ? { resultType: { kind: 'openapi', spec: typed.spec, schema: typed.body } }
             : call ? { resultType: { kind: 'call', name: call.name } } : undefined);
         const catch_ = fnOf('catch', { mode: 'handler', magic: ['$event', '$error'] });
+        const confirm = fnOf('confirm', { mode: 'value', magic: ['$event'] });
+        const encoding = get('encoding');
+        if (encoding !== undefined && encoding !== 'form' && encoding !== 'json')
+            this.report(el, 'data-sn-encoding', 'SN401', '`data-sn-encoding` is `json` (the default) or `form`', 0);
+        if (encoding !== undefined && method === 'call')
+            this.report(el, 'data-sn-encoding', 'SN102', '`data-sn-encoding` belongs to a method attribute; a call sends its own requests', 0);
         const def = {
             method: method.toUpperCase(), url, body: body.f, trigger, debounce, concurrency,
             optimistic: optimistic.f, then: then.f, catch: catch_.f, w: [...new Set([...then.w, ...catch_.w])].sort(), form: isForm,
             ...(call ? { call: { args: call.args, run: call.run } } : {}),
+            ...(confirm.f !== null ? { confirm: confirm.f } : {}),
+            ...(encoding === 'form' ? { enc: 'form' } : {}),
         };
         this.actions.push(def);
         node.b.push(binding({ k: 'on', n: trigger, x: this.actions.length - 1 }));
@@ -839,7 +943,8 @@ class Compiler {
                 frame.indexLoc = this.locOf(el, 'data-sn-for', value.indexOf(index, itemAt + item.length));
             this.check.frames.push(frame);
         }
-        const inner = { loops, states: scope.states };
+        this.checkNames(el, 'data-sn-for', scope, index ? [item, index] : [item]);
+        const inner = { ...scope, loops };
         t.key = null;
         t.keyFields = null;
         if (keySrc !== undefined) {
@@ -905,8 +1010,10 @@ class Compiler {
         if (lit)
             parts.push(lit);
         const first = parts[0];
-        if (typeof first !== 'string' || !(/^\/[^/\\]/.test(first) || first === '/' || /^https?:\/\/[^/{}]+(\/|$)/i.test(first))) {
-            this.report(el, attrName, 'SN207', 'a URL template must start with a literal same-origin path (`/api/…`) or a literal `https://` origin', 0, 'a leading interpolation or `//` lets a value choose the host');
+        // a literal origin followed by a value needs its `/`: `https://api.example.com{x}` lets `x` extend the host
+        const origin = parts.length > 1 ? /^https?:\/\/[^/{}]+\//i : /^https?:\/\/[^/{}]+(\/|$)/i;
+        if (typeof first !== 'string' || !(/^\/[^/\\]/.test(first) || first === '/' || origin.test(first))) {
+            this.report(el, attrName, 'SN207', 'a URL template must start with a literal same-origin path (`/api/…`) or a literal `https://` origin (with a `/` after the host when a value follows)', 0, 'a leading interpolation or `//` lets a value choose the host');
         }
         return parts;
     }
@@ -953,7 +1060,7 @@ class Compiler {
                     this.frameOf.set(loop, this.check.frames.length);
                     this.check.frames.push({ kind: 'loop', item: m[1], index: null, init: listExpr, loc: this.locOf(el, 'each', eachAttr.indexOf(m[1])) });
                 }
-                srcScope = { loops: [...ctx.scope.loops, loop], states: ctx.scope.states };
+                srcScope = { ...ctx.scope, loops: [...ctx.scope.loops, loop] };
                 if (list.ok)
                     each = { item: m[1], list: this.fn(list.code), ...(list.resource ? { of: list.resource } : {}) };
                 this.features.add('each');

package/dist/compiler/diagnostic-docs.js

@@ -41,7 +41,7 @@ export const DIAGNOSTIC_DOCS = {
     },
     SN205: {
         example: '`m.is_read = true` mutates a resource. Use `patch(\'messages\', m, {is_read: true})`',
-        means: 'Resource data is read-only in expressions: it mirrors the server, and a direct write would be lost on the next refresh or event.',
+        means: 'Resource data is read-only in expressions: it mirrors the server, and a direct write (an assignment, a mutating method such as `push()`, or `Object.assign()` on an item) would be lost on the next refresh or event.',
         fix: 'Use the `patch()` call from the message, or copy the item with `structuredClone(c)` to edit it in state.',
     },
     SN206: {
@@ -51,14 +51,19 @@ export const DIAGNOSTIC_DOCS = {
     },
     SN207: {
         example: '`onclick` cannot be bound with `data-sn-attr`; use `data-sn-on-click`',
-        means: 'The binding could run script or inject markup from data: event-handler attributes, `style`, `srcdoc`, `innerHTML`, bindings on `<script>` and similar elements, URL templates that do not start with a literal path, or persisted password fields.',
-        fix: 'Use the safe equivalent the message names: `data-sn-on-*` for events, `data-sn-style` for styles, a literal `/path` at the start of a URL template.',
+        means: 'The binding could run script or inject markup from data: event-handler attributes, `style`, `srcdoc`, `innerHTML`, bindings on `<script>` and similar elements, URL templates that do not start with a literal path (or with a literal origin that lacks its `/` before a value), persisted password fields, or `constructor`, `__proto__` and `prototype` named in an expression.',
+        fix: 'Use the safe equivalent the message names: `data-sn-on-*` for events, `data-sn-style` for styles, a literal `/path` (or `https://host/`) at the start of a URL template.',
     },
     SN208: {
         example: 'Property \'nmae\' does not exist on type \'Contact\'. (TS2339)',
         means: 'TypeScript found a type error in an expression. Reported by `sinter check`, `sinter({ typecheck: true })` and the editor integration.',
         fix: 'Fix the expression, or the type: `type` on `<sn-resource>`, the OpenAPI spec, or a JSDoc cast in `data-sn-state`.',
     },
+    SN209: {
+        example: '`s` is already defined here by `data-sn-let`; use another name',
+        means: 'A `data-sn-let` name is inlined wherever it is read, so it cannot share a name with a state variable or loop variable in its scope, or be redeclared inside it. A resource cannot take the name of a store function (`refresh`, `upsert`, `patch`, `remove`, `page`, `showModal`, `close`, `reset`, `emit`).',
+        fix: 'Rename the let, the state or loop variable, or the resource.',
+    },
     SN301: {
         example: 'resource `mesages` is not declared on this page',
         means: 'A store call, `$meta` or embedded data (`data-sn-data`) names a resource that no `<sn-resource>` on the page or its partials declares.',
@@ -99,6 +104,11 @@ export const DIAGNOSTIC_DOCS = {
         means: 'The resource matched an operation in the OpenAPI spec, but its `items` or `total` path is not in the response schema.',
         fix: 'Fix the path in `items` or `total`, or the spec if the API changed.',
     },
+    SN309: {
+        example: 'no `<dialog id="compose-dialg">` on this page. Did you mean `compose-dialog`?',
+        means: '`showModal(id)` and `close(id)` name a `<dialog>` by its literal `id`, which must be on the page or one of its partials.',
+        fix: 'Fix the id, or add `id` to the `<dialog>`. `close()` without an argument closes the dialog around the element.',
+    },
     SN310: {
         example: '`pgp.decrpyt` is not exported by the actions module. Did you mean `pgp.decrypt`?',
         means: '`data-sn-call` and `<sn-resource call>` name a function the actions module (`src/sinter.actions.js` or `.ts`) exports, directly or through `export * as ns`.',

package/dist/compiler/diagnostics.d.ts

@@ -28,6 +28,7 @@ export declare const CODES: {
     readonly SN206: 'unknown-namespace-member';
     readonly SN207: 'unsafe-sink';
     readonly SN208: 'type-error';
+    readonly SN209: 'name-conflict';
     readonly SN301: 'unknown-resource';
     readonly SN302: 'duplicate-resource';
     readonly SN303: 'unknown-meta-field';
@@ -36,6 +37,7 @@ export declare const CODES: {
     readonly SN306: 'include-cycle';
     readonly SN307: 'openapi-invalid';
     readonly SN308: 'unknown-schema-field';
+    readonly SN309: 'unknown-dialog';
     readonly SN310: 'unknown-action';
     readonly SN401: 'parse-error';
     readonly SN501: 'unused-resource';

package/dist/compiler/diagnostics.js

@@ -11,6 +11,7 @@ export const CODES = {
     SN206: 'unknown-namespace-member',
     SN207: 'unsafe-sink',
     SN208: 'type-error',
+    SN209: 'name-conflict',
     SN301: 'unknown-resource',
     SN302: 'duplicate-resource',
     SN303: 'unknown-meta-field',
@@ -19,6 +20,7 @@ export const CODES = {
     SN306: 'include-cycle',
     SN307: 'openapi-invalid',
     SN308: 'unknown-schema-field',
+    SN309: 'unknown-dialog',
     SN310: 'unknown-action',
     SN401: 'parse-error',
     SN501: 'unused-resource',

package/dist/compiler/expr.d.ts

@@ -19,6 +19,16 @@ export interface StateEntry {
     sid: number;
     names: Set<string>;
 }
+/** A `data-sn-let` name: a value expression inlined wherever the name is read. */
+export interface LetEntry {
+    name: string;
+    /** the compiled expression (without the `($) =>` wrapper) */
+    code: string;
+    deps: string[];
+    usesEl: boolean;
+    usesIndex: boolean;
+    resource: string | null;
+}
 export interface ResourceInfo {
     name: string;
     key: string[] | null;
@@ -30,6 +40,8 @@ export interface ResourceInfo {
 export interface Scope {
     loops: LoopEntry[];
     states: StateEntry[];
+    /** `data-sn-let` names, outer to inner */
+    lets?: LetEntry[];
 }
 export interface PageInfo {
     resources: Map<string, ResourceInfo>;
@@ -43,6 +55,8 @@ export interface PageInfo {
     usesNow: boolean;
     /** `:name` segments of the page's `data-sn-path` patterns */
     pathParams: Set<string>;
+    /** literal `id`s of the page's `<dialog>` elements, for `showModal()` and `close()` */
+    dialogs: Set<string>;
 }
 export interface ExprOptions {
     mode: Mode;
@@ -66,6 +80,8 @@ export interface ObjectEntry {
 export interface ExprResult {
     ok: boolean;
     code: string;
+    /** `code` without its `($) =>` wrapper (value expressions) */
+    inner: string;
     deps: string[];
     writes: string[];
     usesEl: boolean;