@tiaforge-ui/sinter 0.1.0 → 0.3.0

package/README.md

@@ -2,8 +2,9 @@
 
 **Your JSON API, bound to plain HTML.** sinter loads and caches server data, keeps it current from
 server events, renders it through `<template>` bindings and runs mutations with optimistic updates,
-without components, a router or a store library. A build step compiles the HTML, so the browser runs
-no parser and no `eval`.
+without components, a router or a store library. A compiler resolves every name in every expression
+at build time, and type-checks it when you give it your TypeScript types or OpenAPI spec. A typo
+fails the build instead of the page, and the browser runs no parser and no `eval`.
 
 ```html
 <sn-resource name="contacts" src="/api/contacts" items="contacts" key="id" order="name"></sn-resource>
@@ -30,6 +31,26 @@ That page loads the contacts, keeps them sorted, applies updates other users mak
 filters as you type, and removes a contact at once when you click Delete, putting it back if the
 server refuses.
 
+## Mistakes fail the build
+
+The compiler knows every name an expression can use: the state around it, loop variables,
+resources, helpers. Misspell `q` in the filter above and the build stops:
+
+```text
+contacts.html:11:70 error SN201 unknown-identifier: `qq` is not defined here. Did you mean `q`?
+```
+
+The same pass rejects code that would break at runtime: writing to server data
+(`c.name = 'x'` is `SN205`, use `patch('contacts', c, {…})`) and browser APIs inside expressions
+(`localStorage` is `SN202`, use an island). With a `type` on the resource or your OpenAPI spec,
+`sinter check` also type-checks fields, request bodies and event payloads, so `article.titel`
+reports `Property 'titel' does not exist on type 'Article'. Did you mean 'title'?`. Your editor
+shows these errors as you type.
+
+htmx, Datastar and Alpine read their attribute strings in the browser. Nothing checks them against
+your data before they ship, so the same typo shows up only when that code runs: as a console error,
+or as an element that stays empty.
+
 ## Why sinter
 
 - **The server-state plumbing is gone.** You don't write loading flags, stale-response guards,
@@ -37,11 +58,11 @@ server refuses.
   They are attributes.
 - **Optimistic updates that stay correct**, also when requests overlap or a server event arrives
   while a request is in flight.
+- **Checked before it ships.** Every name in every expression is resolved at build time and
+  type-checked against your TypeScript types or your OpenAPI spec. Your editor shows the errors as
+  you type, with hover, completion and go to definition.
 - **Less code.** The [RealWorld](examples/realworld) app takes 735 lines in sinter. The official
-  Angular version takes 2,210. Each page downloads 12–14 KB of JS.
-- **Errors at build time.** Every expression is type-checked against your TypeScript types or your
-  OpenAPI spec. Your editor shows the errors as you type, with hover, completion and go to
-  definition.
+  Angular version takes 2,210. Each page downloads 14–16 KB of JS.
 - **Safe by construction.** Directives are compiled, not read from the live DOM. Pages run under
   `script-src 'self'` with no `unsafe-eval`, and markup injected at runtime stays inert.
 - **Plain, valid HTML.** There is one way to do each thing, and everything is visible on the element.
@@ -57,11 +78,14 @@ page load (the shared code comes from the browser cache).
 
 **htmx, Datastar.** These expect a server that renders HTML for every page and interaction. If you
 have a JSON API, you would have to build and maintain that server. sinter uses the API you already
-have, and its mutations are optimistic where htmx waits for the server's answer. If your backend
-renders HTML anyway and you want no build step, htmx is a good choice.
+have, and its mutations are optimistic where htmx waits for the server's answer. Their attributes
+are read in the browser, so a wrong name surfaces at runtime; sinter's are checked at build time.
+If your backend renders HTML anyway and you want no build step, htmx is a good choice.
 
 **Alpine, petite-vue.** These also render JSON with client-side templates, but they leave fetching,
-caching, live updates and rollback to you.
+caching, live updates and rollback to you. Their expressions are compiled in the browser with
+`new Function`, so they need `unsafe-eval` in the CSP (Alpine has a restricted CSP build), and
+nothing checks the names or fields they use until the code runs.
 
 Measurements and sources: [`docs/realworld-comparison.md`](docs/realworld-comparison.md).
 
@@ -72,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.1.
+- You need stability guarantees. sinter is at v0.3.
 
 ## Setup
 
@@ -113,6 +137,7 @@ Then write `data-sn-*` attributes in your HTML pages. Optional:
 | `@tiaforge-ui/sinter/ws` | WebSocket transport for `<sn-sync>` |
 | `@tiaforge-ui/sinter/optimistic` | optimistic layers |
 | `@tiaforge-ui/sinter/paginate` | keyset, offset, append |
+| `@tiaforge-ui/sinter/each` | fan-out resources (`each="a in accounts"`) |
 | `@tiaforge-ui/sinter/persist` | `data-sn-persist` |
 | `@tiaforge-ui/sinter/compiler` | `compile()` |
 | `@tiaforge-ui/sinter/vite` | Vite plugin |
@@ -122,11 +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 budget per module
+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/check/index.d.ts

@@ -9,6 +9,8 @@ export interface CheckOptions {
     /** from `compile(…, { check: true })`, one per page */
     units: CheckUnit[];
     helpers: HelperManifest;
+    /** the actions module (`data-sn-call`), same shape as helpers */
+    actions?: HelperManifest;
     /** absolute path of the types module, or null */
     types: string | null;
     /** the specs the pages were compiled with (`compile(…, { openapi })`) */
@@ -57,12 +59,13 @@ export declare const COMPILER_OPTIONS: {
     target: string;
     module: string;
     moduleResolution: string;
+    allowImportingTsExtensions: boolean;
     lib: string[];
     types: string[];
 };
 /** Where a page's shadow file goes. */
 export declare function shadowPath(support: Support, root: string, page: string): string;
-export declare function shadowOf(unit: CheckUnit, support: Support, root: string, helpers: HelperManifest): Shadow;
+export declare function shadowOf(unit: CheckUnit, support: Support, root: string, helpers: HelperManifest, actions?: HelperManifest): Shadow;
 /** A TypeScript error at a 1-based shadow position, as an SN208 diagnostic at the HTML position. */
 export declare function typeDiagnostic(unit: CheckUnit, regions: Region[], line: number, col: number, code: string, message: string, root: string): Diagnostic;
 export declare function check(o: CheckOptions): CheckResult;

package/dist/check/index.js

@@ -25,14 +25,14 @@ export function writeSupport(o) {
 /** The compiler options shadow files are checked with. */
 export const COMPILER_OPTIONS = {
     allowJs: true, checkJs: true, strict: true, strictNullChecks: false, noImplicitAny: false, noEmit: true, skipLibCheck: true,
-    target: 'es2022', module: 'esnext', moduleResolution: 'bundler', lib: ['es2023', 'dom', 'dom.iterable'], types: [],
+    target: 'es2022', module: 'esnext', moduleResolution: 'bundler', allowImportingTsExtensions: true, lib: ['es2023', 'dom', 'dom.iterable'], types: [],
 };
 /** Where a page's shadow file goes. */
 export function shadowPath(support, root, page) {
     return join(support.outDir, relative(root, page) + '.js');
 }
-export function shadowOf(unit, support, root, helpers) {
-    return shadow({ unit, file: shadowPath(support, root, unit.file), root, declarations: support.declarations, types: support.types, helpers, openapi: support.openapi });
+export function shadowOf(unit, support, root, helpers, actions) {
+    return shadow({ unit, file: shadowPath(support, root, unit.file), root, declarations: support.declarations, types: support.types, helpers, actions, openapi: support.openapi });
 }
 /** A TypeScript error at a 1-based shadow position, as an SN208 diagnostic at the HTML position. */
 export function typeDiagnostic(unit, regions, line, col, code, message, root) {
@@ -56,7 +56,7 @@ export function check(o) {
     const shadows = new Map();
     for (const unit of o.units) {
         const file = shadowPath(support, o.root, unit.file);
-        const s = shadowOf(unit, support, o.root, o.helpers);
+        const s = shadowOf(unit, support, o.root, o.helpers, o.actions);
         mkdirSync(dirname(file), { recursive: true });
         writeFileSync(file, s.text);
         shadows.set(resolve(file), { unit, regions: s.regions, brokenFrom: s.brokenFrom });
@@ -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 });
@@ -72,7 +73,7 @@ export function check(o) {
         throw run.error;
     const diagnostics = parseTsc(run.stdout, outDir, o.root, shadows);
     const resources = o.units.reduce((n, u) => n + u.resources.length, 0);
-    const typed = o.units.reduce((n, u) => n + u.resources.filter((r) => r.type || r.openapi).length, 0);
+    const typed = o.units.reduce((n, u) => n + u.resources.filter((r) => r.type || r.openapi || r.call).length, 0);
     const viaOpenapi = o.units.reduce((n, u) => n + u.resources.filter((r) => !r.type && r.openapi).length, 0);
     return { diagnostics, resources, typed, openapi: viaOpenapi };
 }
@@ -91,8 +92,8 @@ export function checkPage(html, o = {}) {
         const file = join(root, 'index.html');
         writeFileSync(file, html);
         const p = project(root, o);
-        const out = compile(html, { file, root, dev: false, helpers: p.helpers, readFile: p.readFile, check: true, openapi: p.openapi });
-        const r = check({ root, units: out.check ? [out.check] : [], helpers: p.helpers, types: p.types, openapi: p.openapi, tsc: findTsc(process.cwd()) });
+        const out = compile(html, { file, root, dev: false, helpers: p.helpers, actions: p.actions, readFile: p.readFile, check: true, openapi: p.openapi });
+        const r = check({ root, units: out.check ? [out.check] : [], helpers: p.helpers, actions: p.actions, types: p.types, openapi: p.openapi, tsc: findTsc(process.cwd()) });
         return [...p.diagnostics, ...out.diagnostics, ...r.diagnostics].map((d) => ({ ...d, file: relative(root, d.file) }));
     }
     finally {

package/dist/check/shadow.d.ts

@@ -14,6 +14,8 @@ export interface ShadowOptions {
         names: string[];
     } | null;
     helpers: HelperManifest;
+    /** the actions module, for `data-sn-call` arguments and results */
+    actions?: HelperManifest;
     /** absolute paths of the declarations generated per OpenAPI spec, by spec index */
     openapi?: string[];
 }
@@ -36,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;\n  pages?: number | null;\n  from?: number | null;\n  to?: number | null;\n  hasPrev?: boolean;\n  hasNext?: boolean;\n}\nexport interface Err { status: number; body: any; message: string }\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

@@ -51,7 +51,12 @@ export function shadow(o) {
         if (!taken.has(ns))
             line(`import * as ${ns} from '${moduleSpec(module)}';`);
     }
+    if (o.actions?.module && (unit.resources.some((r) => r.call) || unit.exprs.some((e) => e.returns?.kind === 'call' || e.resultType?.kind === 'call'))) {
+        line(`import * as $A from '${moduleSpec(o.actions.module)}';`);
+    }
     line('const $any = /** @type {any} */ (null);');
+    /** what a resource fed by `call` holds: the awaited result, at its `items` path */
+    const callResult = (c) => `Awaited<ReturnType<typeof $A.${c.name}>>${(c.items ? c.items.split('.') : []).map((k) => `[${JSON.stringify(k)}]`).join('')}`;
     const types = [];
     for (const r of unit.resources) {
         const t = r.type ?? 'any';
@@ -64,6 +69,11 @@ export function shadow(o) {
             line(' * }');
             line(' */');
         }
+        else if (r.call) {
+            const t = callResult(r.call);
+            types[types.length - 1] = `${JSON.stringify(r.name)}: ${t}`;
+            line(`/** @type {${t}} */`);
+        }
         else if (r.openapi) {
             const t = schemaToTs(r.openapi.schema, (n) => `$O${r.openapi.spec}.${typeName(n)}`);
             types[types.length - 1] = `${JSON.stringify(r.name)}: ${t}`;
@@ -74,6 +84,14 @@ export function shadow(o) {
             line('/** @type {any} */');
         regions.push({ start: out.length + 1, lines: 1, loc: r.nameLoc ?? r.loc, fixed: true });
         line(`const ${r.name} = $any;`);
+        // with `type`, what the action returns (at `items`) must fit it; reported on `type`
+        if (r.call && r.type) {
+            // own line: TypeScript drops a JSDoc tag that follows `{` on the same line
+            line('{');
+            regions.push({ start: out.length + 1, lines: 1, loc: r.loc, fixed: true });
+            line(`/** @type {${r.type.replace(/\s+/g, ' ')}} */ const $fits = /** @type {${callResult(r.call)}} */ ($any); void $fits;`);
+            line('}');
+        }
     }
     const names = unit.resources.map((r) => JSON.stringify(r.name)).join(' | ') || 'never';
     line(`/** @type {Record<${names}, ${decl('Meta')}>} */`);
@@ -97,9 +115,11 @@ 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.partial ? 'Partial<' : ''}${decl('Item')}<typeof ${t.resource}>${t.partial ? '>' : ''}`;
+            : t.kind === 'call'
+                ? (t.args ? `${decl('CallArgs')}<typeof $A.${t.name}>` : `Awaited<ReturnType<typeof $A.${t.name}>>`)
+                : `${t.partial ? 'Partial<' : ''}${decl('Item')}<typeof ${t.resource}>${t.partial ? '>' : ''}`;
         line(`/** @${tag} {${text}} */${after}`);
     };
     /** declarations for the frames of an expression; returns the number of blocks opened */
@@ -115,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}())`};`);
@@ -148,8 +172,19 @@ export function shadow(o) {
                 regions.push({ start: out.length + 1, lines: 1, loc: e.loc, fixed: true });
                 line(`const ${n} = $p.${n};`);
             }
+            // a state name shadows a payload field of the same name: an error when the payload type has it
+            if (e.payload.type) {
+                for (const n of e.payload.states ?? []) {
+                    const msg = `state \`${n}\` shadows the payload field \`${n}\`: rename the state`;
+                    regions.push({ start: out.length + 1, lines: 1, loc: e.loc, fixed: true });
+                    line(`/** @type {${JSON.stringify(n)} extends keyof typeof $p ? ${JSON.stringify(msg)} : true} */ const $shadows_${n} = true; void $shadows_${n};`);
+                }
+            }
         }
         if (e.mode === 'value') {
+            // action arguments and bodies are taken when the trigger fires
+            if (e.event !== null)
+                line(`/** @type {${decl(`Ev<${JSON.stringify(e.event)}>`)}} */ const $event = $any;`);
             // a value of the wrong type as a whole is reported on `return`
             regions.push({ start: out.length + 1, lines: 1, loc: e.loc, fixed: true });
             line('return (');
@@ -195,14 +230,26 @@ export interface Meta {
   loadedAt: number | null;
   pending: number;
   total: number | null;
-  page?: number;
+  page?: number | null;
   pages?: number | null;
   from?: number | null;
   to?: number | null;
   hasPrev?: boolean;
   hasNext?: boolean;
 }
-export interface Err { status: number; 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;
 export type Item<T> = NonNullable<T> extends readonly (infer U)[] ? U : NonNullable<T> extends Iterable<infer U> ? U : any;
 export type El<K extends string> = K extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[K] : HTMLElement;
 export type Ev<K extends string> = K extends keyof HTMLElementEventMap ? HTMLElementEventMap[K] : CustomEvent;
@@ -212,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/cli.js

@@ -36,12 +36,12 @@ async function main(argv) {
     const diagnostics = [...p.diagnostics];
     const units = [];
     for (const file of files) {
-        const out = compile(readFileSync(file, 'utf8'), { file, root, dev: false, helpers: p.helpers, config: p.config, readFile: p.readFile, check: true, openapi: p.openapi });
+        const out = compile(readFileSync(file, 'utf8'), { file, root, dev: false, helpers: p.helpers, actions: p.actions, config: p.config, readFile: p.readFile, check: true, openapi: p.openapi });
         diagnostics.push(...out.diagnostics);
         if (out.check)
             units.push(out.check);
     }
-    const r = check({ root, units, helpers: p.helpers, types: p.types, openapi: p.openapi });
+    const r = check({ root, units, helpers: p.helpers, actions: p.actions, types: p.types, openapi: p.openapi });
     diagnostics.push(...r.diagnostics);
     for (const d of diagnostics)
         console.log(formatDiagnostic({ ...d, file: relative(process.cwd(), d.file) || d.file }) + '\n');

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 = 
@@ -47,13 +54,24 @@ export type TypeRef =
     kind: 'item';
     resource: string;
     partial?: boolean;
+}
+/** an action (`archive`, `pgp.decrypt`): its arguments (`args`) or its awaited result */
+ | {
+    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;
@@ -70,6 +88,7 @@ export interface CheckExpr {
     payload?: {
         names: string[];
         type: TypeRef | null;
+        states?: string[];
     };
     /** the compiler reported an error in it (it may not even parse); kept for editor completion, never type-checked */
     broken?: boolean;
@@ -88,6 +107,11 @@ export interface CheckResource {
         label: string;
         schema: unknown;
     };
+    /** `call`: the action and the `items` path into its result; with `type`, the result must fit it */
+    call?: {
+        name: string;
+        items: string | null;
+    };
 }
 export interface CheckUnit {
     file: string;

package/dist/compiler/compile.d.ts

@@ -25,6 +25,8 @@ export interface CompileOptions {
     check?: boolean;
     /** parsed OpenAPI specs: resources without `type` are matched against them */
     openapi?: OpenApiSpec[];
+    /** the actions module (`data-sn-call`, `<sn-resource call>`), same shape as helpers */
+    actions?: HelperManifest;
 }
 export interface CompileResult {
     html: string;
@@ -45,6 +47,8 @@ export interface CompiledParts {
         builtin: string[];
     };
     namespaces: Record<string, string[]>;
+    /** action functions called, as written: `archive`, `pgp.decrypt` */
+    calls: string[];
     diagnostics: Diagnostic[];
     files: string[];
     /** with `check: true` */