@tiaforge-ui/sinter 0.1.0 → 0.2.0

package/dist/compiler/index.js

@@ -1,4 +1,5 @@
 import * as acorn from 'acorn';
+import { tsPlugin } from '@sveltejs/acorn-typescript';
 import { compileParts } from './compile.js';
 export { formatDiagnostic, docsUrl, CODES } from './diagnostics.js';
 export { DIAGNOSTIC_DOCS } from './diagnostic-docs.js';
@@ -25,6 +26,21 @@ export function pageModule(parts, options) {
         const mod = options.helpers.namespaces[ns].module;
         lines.push(`import { ${members.map((m) => `${m} as ${ns}$${m}`).join(', ')} } from ${JSON.stringify(mod)};`);
     }
+    // actions (`data-sn-call`): imported as `$a$name` / `$a$ns$member`, only those the page calls
+    const acts = options.actions;
+    if (acts?.module) {
+        const direct = parts.calls.filter((c) => !c.includes('.'));
+        if (direct.length)
+            lines.push(`import { ${direct.map((c) => `${c} as $a$${c}`).join(', ')} } from ${JSON.stringify(acts.module)};`);
+        const byNs = new Map();
+        for (const c of parts.calls.filter((x) => x.includes('.'))) {
+            const [ns, member] = c.split('.');
+            byNs.set(ns, [...(byNs.get(ns) ?? []), member]);
+        }
+        for (const [ns, members] of byNs) {
+            lines.push(`import { ${members.map((x) => `${x} as $a$${ns}$${x}`).join(', ')} } from ${JSON.stringify(acts.namespaces[ns].module)};`);
+        }
+    }
     if (options.config)
         lines.push(`import ${JSON.stringify(options.config)};`);
     lines.push('');
@@ -39,46 +55,81 @@ export function pageModule(parts, options) {
 }
 /**
  * Reads a helpers module's export names statically. `export * as m from './x.js'`
- * becomes a namespace whose members are read from `x.js` the same way.
+ * becomes a namespace whose members are read from `x.js` the same way. `export * from './y.js'`
+ * re-exports (e.g. paraglide's message index) are followed, relative paths only.
  */
 export function readHelperManifest(source, options) {
     const manifest = { module: options.module, names: [], namespaces: {} };
     const resolve = options.resolve ?? ((spec, from) => (spec.startsWith('.') ? joinPath(from, spec) : null));
-    const { names, namespaces } = exportsOf(source);
-    manifest.names = names;
-    for (const [ns, spec] of namespaces) {
-        const path = resolve(spec, options.file);
-        let members = [];
-        if (path) {
-            try {
-                members = exportsOf(options.readFile(path)).names;
-            }
-            catch {
-                members = [];
-            }
+    const read = (file) => {
+        try {
+            return exportsOf(options.readFile(file), file);
+        }
+        catch {
+            return null;
         }
+    };
+    /** the module's own value exports plus those of its `export *` re-exports, transitively */
+    const valueNames = (file, exports, seen) => {
+        const names = new Set(exports.names);
+        for (const spec of exports.reexports) {
+            const path = spec.startsWith('.') ? resolve(spec, file) : null;
+            if (!path || seen.has(path))
+                continue;
+            seen.add(path);
+            const sub = read(path);
+            if (sub)
+                for (const n of valueNames(path, sub, seen))
+                    names.add(n);
+        }
+        return [...names].sort();
+    };
+    const top = exportsOf(source, options.file);
+    manifest.names = valueNames(options.file, top, new Set([options.file]));
+    for (const [ns, spec] of top.namespaces) {
+        const path = resolve(spec, options.file);
+        const exports = path ? read(path) : null;
+        const members = path && exports ? valueNames(path, exports, new Set([path])) : [];
         const modSpec = spec.startsWith('.') ? joinPath(options.module, spec) : spec;
         manifest.namespaces[ns] = { module: modSpec, members };
     }
     return manifest;
 }
-function exportsOf(source) {
-    const ast = acorn.parse(source, { ecmaVersion: 'latest', sourceType: 'module' });
+/** acorn extended with TypeScript syntax, for `.ts` helper and namespace modules */
+let tsParser = null;
+function parseModule(source, file) {
+    const options = { ecmaVersion: 'latest', sourceType: 'module' };
+    if (!/\.[cm]?tsx?$/.test(file))
+        return acorn.parse(source, options);
+    tsParser ??= acorn.Parser.extend(tsPlugin());
+    return tsParser.parse(source, options);
+}
+/** Value exports only: type-only exports (`export type`, `export interface`, `export { type X }`) are skipped. */
+function exportsOf(source, file) {
+    const ast = parseModule(source, file);
     const names = [];
     const namespaces = [];
+    const reexports = [];
+    const typeOnly = (n) => n.exportKind === 'type';
     for (const st of ast.body) {
+        if (typeOnly(st))
+            continue;
         if (st.type === 'ExportNamedDeclaration') {
             const d = st.declaration;
             if (d?.type === 'FunctionDeclaration' && d.id)
                 names.push(d.id.name);
             else if (d?.type === 'ClassDeclaration' && d.id)
                 names.push(d.id.name);
+            else if (d?.type === 'TSEnumDeclaration')
+                names.push(d.id.name);
             else if (d?.type === 'VariableDeclaration') {
                 for (const v of d.declarations)
                     if (v.id.type === 'Identifier')
                         names.push(v.id.name);
             }
             for (const s of st.specifiers) {
+                if (typeOnly(s))
+                    continue;
                 const exported = s.exported.type === 'Identifier' ? s.exported.name : String(s.exported.value);
                 if (exported !== 'default')
                     names.push(exported);
@@ -88,8 +139,11 @@ function exportsOf(source) {
             const ns = st.exported.type === 'Identifier' ? st.exported.name : String(st.exported.value);
             namespaces.push([ns, String(st.source.value)]);
         }
+        else if (st.type === 'ExportAllDeclaration') {
+            reexports.push(String(st.source.value));
+        }
     }
-    return { names: [...new Set(names)].sort(), namespaces };
+    return { names: [...new Set(names)].sort(), namespaces, reexports };
 }
 function joinPath(from, spec) {
     const dir = from.slice(0, from.lastIndexOf('/') + 1);

package/dist/compiler/vocabulary.js

@@ -19,9 +19,10 @@ export const ATTRIBUTES = [
     { name: 'put', value: 'URL template', doc: 'PUT action' },
     { name: 'patch', value: 'URL template', doc: 'PATCH action' },
     { name: 'delete', value: 'URL template', doc: 'DELETE action' },
+    { name: 'call', value: 'action call', doc: 'local action: calls a function from the actions module, e.g. pgp.decrypt(msg)' },
     { name: 'body', value: 'value expression', doc: 'JSON request body; overrides form serialization' },
     { name: 'trigger', value: 'DOM event name', doc: 'overrides the default trigger' },
-    { name: 'debounce', value: 'milliseconds', doc: 'delays the trigger, resets on each event' },
+    { name: 'debounce', value: 'milliseconds', doc: 'delays the trigger, resets on each event; without a method, delays the element\'s data-sn-on-* handlers' },
     { name: 'concurrency', value: 'block | queue | latest', doc: 'mutations only; default block for forms, queue otherwise' },
     { name: 'optimistic', value: 'handler expression', doc: 'patch/upsert/remove calls applied before the request, rolled back on failure' },
     { name: 'then', value: 'handler expression', doc: 'runs after a 2xx response; $result = parsed body' },
@@ -31,7 +32,7 @@ export const ATTRIBUTES = [
 ];
 export const ON_DOC = { name: 'on-<event>', value: 'handler expression', doc: 'plain event handler, no request; e.g. data-sn-on-click' };
 export const ELEMENTS = [
-    { name: 'sn-resource', attrs: ['name', 'src', 'key', 'items', 'total', 'order', 'when', 'paginate', 'page-size', 'size-param', 'cursor', 'direction-param', 'page-param', 'type', 'cache'], doc: 'a named, page-wide cache of server data; `cache` (or `cache="10m"`) shows the data from the last page load at once, then revalidates' },
+    { name: 'sn-resource', attrs: ['name', 'src', 'call', 'each', 'key', 'items', 'total', 'order', 'when', 'paginate', 'page-size', 'size-param', 'cursor', 'direction-param', 'direction-values', 'page-param', 'offset-param', 'type', 'cache'], doc: 'a named, page-wide cache of server data; `cache` (or `cache="10m"`) shows the data from the last page load at once, then revalidates' },
     { name: 'sn-sync', attrs: ['src'], doc: 'one server event stream' },
     { name: 'sn-event', attrs: ['name', 'resource', 'op', 'item', 'set', 'when', 'fallback', 'type'], doc: 'maps one server event to a change message; child of <sn-sync>' },
     { name: 'sn-include', attrs: ['src'], doc: 'inlines a partial at build time' },

package/dist/each.d.ts

@@ -0,0 +1,3 @@
+import type { Feature } from './runtime/app.js';
+declare const each: Feature;
+export default each;

package/dist/each.js

@@ -0,0 +1,121 @@
+const isAbort = (e) => e instanceof DOMException && e.name == 'AbortError';
+/**
+ * Sources are keyed by their resolved URL. An item belongs to a source when it came in that
+ * source's last response, or when `src` resolves to the source's URL with the item itself in
+ * place of the list item, so an item a server event added is replaced by the next response.
+ */
+function fanOut(l, app) {
+    const { def, res: r } = l;
+    const each = def.each;
+    const sources = new Map();
+    const queued = new Set();
+    let pending = 0, again = null;
+    const urlOf = (item) => {
+        if (!item || typeof item != 'object')
+            return null;
+        try {
+            return app.url(def.src, Object.assign(Object.create(l.scope()), { [each.item]: item }));
+        }
+        catch {
+            return null;
+        }
+    };
+    /** the confirmed items minus those of source `u`, plus `items` */
+    const swap = (u, s, items) => {
+        const mine = (x) => s.keys.has(r.keyOf(x)) || urlOf(x) === u;
+        r.replace([...r.base().items.filter((x) => !mine(x)), ...items]);
+    };
+    async function load(u) {
+        const s = sources.get(u);
+        if (!s)
+            return;
+        s.c?.abort();
+        const ctl = (s.c = new AbortController()), n = ++s.seq, mark = r.startLoad();
+        let loaded = false;
+        pending++;
+        l.loading(true);
+        try {
+            const body = await l.get(u, ctl.signal);
+            if (n != s.seq || sources.get(u) != s)
+                return;
+            const items = l.items(body);
+            swap(u, s, items);
+            s.keys = new Set(items.map((x) => r.keyOf(x)));
+            s.answered = loaded = true;
+            r.meta.error = null;
+            // loadedAt: every current source has answered once
+            if ([...sources.values()].every((x) => x.answered))
+                r.meta.loadedAt = app.env.now();
+        }
+        catch (e) {
+            if (n != s.seq || isAbort(e))
+                return;
+            s.answered = true;
+            l.failed(e);
+        }
+        finally {
+            r.endLoad(mark, loaded);
+            if (n == s.seq)
+                s.c = null;
+            l.loading(--pending > 0);
+        }
+    }
+    l.changed = () => {
+        const scope = l.scope();
+        let list = [];
+        try {
+            if (def.when == null || app.fns[def.when](scope))
+                list = app.fns[each.list](scope) ?? [];
+        }
+        catch (e) {
+            app.warn(17, def.name, e.message);
+        }
+        const want = new Set();
+        for (const item of Array.isArray(list) ? list : [...list]) {
+            const u = urlOf(item);
+            if (u != null)
+                want.add(u);
+        }
+        for (const [u, s] of sources) {
+            if (want.has(u))
+                continue;
+            s.seq++;
+            s.c?.abort();
+            sources.delete(u);
+            swap(u, s, []);
+        }
+        for (const u of want) {
+            if (sources.has(u))
+                continue;
+            sources.set(u, { c: null, seq: 0, keys: new Set(), answered: false });
+            void load(u);
+        }
+        // nothing to load: loaded once the list itself is (an empty list is an answer, a pending one is not)
+        if (!sources.size && r.meta.loadedAt == null && (!each.of || app.resource(each.of).meta.loadedAt != null)) {
+            r.meta.loadedAt = app.env.now();
+            r.onDirty('meta');
+        }
+        l.loading(pending > 0);
+    };
+    l.start = () => l.changed();
+    l.load = () => Promise.all([...sources.keys()].map(load)).then(() => { });
+    // a hint (an event's payload) that resolves to one source's URL reloads only that source;
+    // several refetches in one task share one round of requests
+    l.refetch = (hint) => {
+        const u = hint ? urlOf(hint) : null;
+        queued.add(u != null && sources.has(u) ? u : '*');
+        return (again ??= Promise.resolve().then(() => {
+            again = null;
+            const urls = queued.has('*') ? [...sources.keys()] : [...queued];
+            queued.clear();
+            return Promise.all(urls.map(load)).then(() => { });
+        }));
+    };
+}
+const each = {
+    name: 'each',
+    install(app) {
+        app.ext.each = { fanOut: (loader) => fanOut(loader, app) };
+    },
+};
+export default each;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { mount, instance, type App, type Feature, type MountOptions, type StateHandle, type Transport } from './runtime/app.js';
+export { mount, instance, type App, type CallContext, type Feature, type MountOptions, type StateHandle, type Transport } from './runtime/app.js';
 export { configure, credentials, header, onUnauthorized, loginRedirect, takeReturnUrl, clearPersisted, SinterError, type Config, type Middleware, type LoginRedirectOptions, } from './runtime/config.js';
 export type { Resource, Change, Meta } from './runtime/store.js';
 export { $k } from './runtime/security.js';

package/dist/ir.d.ts

@@ -8,7 +8,11 @@ export interface Paginate {
     /** keyset/append: object literal evaluated with the boundary item as `$.$p` */
     cursor: number | null;
     directionParam: string;
+    /** keyset/append: the value sent for each direction, where it differs from the direction's name */
+    directionValues?: Partial<Record<'first' | 'prev' | 'next' | 'last', string>>;
     pageParam: string;
+    /** keyset: offset parameter that lets `page(name, n)` jump; the server skips (n - 1) * size items */
+    offsetParam?: string;
 }
 export interface ResourceDef {
     name: string;
@@ -29,6 +33,14 @@ export interface ResourceDef {
     data: number | null;
     /** `cache`: the oldest cached data to show, in ms (0: any age); absent when not cached */
     cache?: number;
+    /** `call="ns.fn(args)"`: loaded from an action function instead of `src` (then empty) */
+    call?: CallDef;
+    /** `each="a in accounts"`: one request per list item (src evaluated with `item` in scope), merged into one collection */
+    each?: {
+        item: string;
+        list: number;
+        of?: string;
+    };
 }
 export interface EventDef {
     name: string;
@@ -42,6 +54,8 @@ export interface EventDef {
 export interface SyncDef {
     src: UrlTemplate;
     events: EventDef[];
+    /** index of the node (in `roots`) whose scope `src` and the events' expressions are evaluated in, -1 (or absent) for page scope */
+    scope?: number;
 }
 export type BindingKind = 'text' | 'attr' | 'class' | 'style' | 'show' | 'model' | 'prop' | 'for' | 'if' | 'else' | 'on';
 export interface Binding {
@@ -66,6 +80,8 @@ export interface Binding {
     e?: 1;
     /** the expression reads a loop index, so it re-runs when only the row's position changed */
     i?: 1;
+    /** handler on an element without a method: `data-sn-debounce` milliseconds */
+    ms?: number;
 }
 export interface NodeDef {
     /** `data-sn` id (roots) */
@@ -80,6 +96,8 @@ export interface NodeDef {
     sid?: number;
     /** persist key for the whole state object */
     persist?: string;
+    /** the element is a `<dialog>` or inside one of its block, so its bindings wait while that dialog is closed */
+    dl?: 1;
     b: Binding[];
 }
 export interface TemplateDef {
@@ -95,9 +113,16 @@ export interface TemplateDef {
     /** for: function that finds the bound elements of one cloned row: (first content node) => elements, in `nodes` order */
     find?: number;
 }
+/** a local action call: `args` evaluates the arguments (an array), `run(args, ctx)` calls the function */
+export interface CallDef {
+    args: number;
+    run: number;
+}
 export interface ActionDef {
-    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /** `CALL`: `data-sn-call`, with `call` set and an empty `url` */
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'CALL';
     url: UrlTemplate;
+    call?: CallDef;
     body: number | null;
     trigger: string;
     debounce: number;

package/dist/lsp/typescript.js

@@ -59,7 +59,7 @@ export class TypeScriptBridge {
             this.filesChanged([support.declarations, ...support.openapi]);
         this.support = support;
         for (const [page, unit] of units) {
-            const s = shadowOf(unit, support, this.root, project.helpers);
+            const s = shadowOf(unit, support, this.root, project.helpers, project.actions);
             const prev = this.shadows.get(page);
             if (prev?.text === s.text) {
                 prev.unit = unit;

package/dist/lsp/workspace.js

@@ -48,13 +48,14 @@ export class Workspace {
         }
         const p = project(root, options);
         const inputs = new Set(VITE_CONFIGS.map((c) => join(root, c)));
-        for (const f of [p.helpersFile, p.types, ...p.openapi.map((s) => s.file)])
+        for (const f of [p.helpersFile, p.actionsFile, p.types, ...p.openapi.map((s) => s.file)])
             if (f)
                 inputs.add(f);
         for (const spec of options.openapi == null ? [] : [].concat(options.openapi))
             inputs.add(resolve(root, spec));
         for (const ext of ['.js', '.ts']) {
             inputs.add(join(root, 'src/sinter.helpers' + ext));
+            inputs.add(join(root, 'src/sinter.actions' + ext));
             inputs.add(join(root, 'src/sinter.types' + ext));
         }
         inputs.add(join(root, 'src/sinter.types.d.ts'));
@@ -166,7 +167,7 @@ export class Workspace {
             }
             try {
                 const out = compile(html, {
-                    file: page, root: state.root, dev: false, helpers: p.helpers, config: p.config, readFile, check: true, openapi: p.openapi,
+                    file: page, root: state.root, dev: false, helpers: p.helpers, actions: p.actions, config: p.config, readFile, check: true, openapi: p.openapi,
                 });
                 state.includes.set(page, out.files.map((f) => resolve(f)).filter((f) => f !== page));
                 state.diagnostics.set(page, out.diagnostics);

package/dist/paginate.js

@@ -7,14 +7,14 @@ class PagerImpl {
         this.cfg = loader.def.paginate;
         this.move = this.first();
         const m = loader.res.meta;
-        if (this.cfg.mode === 'offset')
+        if (this.cfg.mode === 'offset' || this.cfg.offsetParam)
             m.page = 1;
         Object.assign(m, { pages: null, from: null, to: null, hasPrev: false, hasNext: false });
     }
     base(dir, size = this.cfg.size) {
         const p = { [this.cfg.sizeParam]: String(size) };
         if (dir)
-            p[this.cfg.directionParam] = dir;
+            p[this.cfg.directionParam] = this.cfg.directionValues?.[dir] ?? dir;
         return p;
     }
     first() {
@@ -49,8 +49,10 @@ class PagerImpl {
             scope.$p = item;
             const c = this.loader.app.fns[this.cfg.cursor](scope);
             const out = {};
+            // like a URL template's query parameters: null and undefined fields are left out
             for (const [k, v] of Object.entries(c ?? {}))
-                out[k] = v == null ? '' : String(v);
+                if (v != null)
+                    out[k] = String(v);
             return out;
         };
         let move;
@@ -80,7 +82,16 @@ class PagerImpl {
         }
         else {
             if (typeof target === 'number') {
-                this.loader.app.warn('keyset pagination cannot jump to a page number; use paginate="offset"');
+                if (!this.cfg.offsetParam) {
+                    this.loader.app.warn('keyset pagination cannot jump to a page number; add offset-param or use paginate="offset"');
+                    return;
+                }
+                // the server skips (n - 1) pages; prev/next continue by cursor from there
+                let n = Math.max(1, Math.floor(target));
+                if (meta.pages != null)
+                    n = Math.min(n, meta.pages);
+                move = { dir: 'page', page: n, params: { [this.cfg.offsetParam]: String((n - 1) * this.cfg.size), ...this.base('first') }, from, to };
+                void this.loader.load(move);
                 return;
             }
             if (this.cfg.mode === 'append' && target !== 'next')
@@ -158,6 +169,9 @@ class PagerImpl {
                     hasPrev = full;
                 break;
         }
+        // keyset with jumps: the page that holds the last item shown (after `last`, the last page)
+        if (this.cfg.offsetParam && move.dir !== 'page')
+            meta.page = to != null ? Math.max(1, Math.ceil(to / size)) : null;
         Object.assign(meta, { pages, from, to, hasPrev, hasNext });
         this.loader.res.onDirty('meta');
     }

package/dist/project.d.ts

@@ -3,6 +3,8 @@ import type { OpenApiSpec } from './compiler/openapi.js';
 export interface ProjectOptions {
     /** helpers module, relative to the root (default `src/sinter.helpers.js`, or `.ts`) */
     helpers?: string;
+    /** actions module for `data-sn-call` and `<sn-resource call>` (default `src/sinter.actions.js`, or `.ts`) */
+    actions?: string;
     /** app configuration module imported before mount (default `src/sinter.config.js`, or `.ts`) */
     config?: string;
     /** module whose exported types `type="…"` on `<sn-resource>` may name (default `src/sinter.types.ts`, `.d.ts` or `.js`) */
@@ -15,6 +17,10 @@ export interface Project {
     helpers: HelperManifest;
     /** absolute path of the helpers module, or null */
     helpersFile: string | null;
+    /** the actions module's functions and namespaces (same shape as helpers) */
+    actions: HelperManifest;
+    /** absolute path of the actions module, or null */
+    actionsFile: string | null;
     /** root-relative URL of the config module (`/src/sinter.config.js`), or null */
     config: string | null;
     /** absolute path of the types module, or null */

package/dist/project.js

@@ -20,25 +20,28 @@ export function project(root, options = {}) {
         return readFileSync(real, 'utf8');
     };
     const url = (rel) => '/' + rel.split(sep).join('/');
-    let helpers = { module: null, names: [], namespaces: {} };
-    const helpersRel = find(options.helpers, 'src/sinter.helpers');
-    const helpersFile = helpersRel ? resolve(root, helpersRel) : null;
-    if (helpersRel && helpersFile) {
-        helpers = readHelperManifest(readFileSync(helpersFile, 'utf8'), {
-            module: url(helpersRel),
-            file: helpersFile,
-            readFile,
-            resolve: (spec, from) => {
-                if (!spec.startsWith('.'))
+    const manifest = (given, base) => {
+        const rel = find(given, base);
+        const file = rel ? resolve(root, rel) : null;
+        if (!rel || !file)
+            return [{ module: null, names: [], namespaces: {} }, null];
+        return [readHelperManifest(readFileSync(file, 'utf8'), {
+                module: url(rel),
+                file,
+                readFile,
+                resolve: (spec, from) => {
+                    if (!spec.startsWith('.'))
+                        return null;
+                    const b = resolve(dirname(from), spec);
+                    for (const q of [b, b.replace(/\.js$/, '.ts'), `${b}.js`, `${b}.ts`])
+                        if (existsSync(q))
+                            return q;
                     return null;
-                const base = resolve(dirname(from), spec);
-                for (const p of [base, base.replace(/\.js$/, '.ts'), `${base}.js`, `${base}.ts`])
-                    if (existsSync(p))
-                        return p;
-                return null;
-            },
-        });
-    }
+                },
+            }), file];
+    };
+    const [helpers, helpersFile] = manifest(options.helpers, 'src/sinter.helpers');
+    const [actions, actionsFile] = manifest(options.actions, 'src/sinter.actions');
     const configRel = find(options.config, 'src/sinter.config');
     const typesRel = find(options.types, 'src/sinter.types', ['.ts', '.d.ts', '.js']);
     const openapi = [];
@@ -70,7 +73,7 @@ export function project(root, options = {}) {
         openapi.push({ file, doc });
     }
     return {
-        root, helpers, helpersFile, readFile, openapi, diagnostics,
+        root, helpers, helpersFile, actions, actionsFile, readFile, openapi, diagnostics,
         config: configRel ? url(configRel) : null,
         types: typesRel ? resolve(root, typesRel) : null,
     };

package/dist/runtime/app.d.ts

@@ -47,13 +47,35 @@ export interface Pager {
     appends(move: unknown): boolean;
     received(items: unknown[], total: number | null, move: unknown): void;
 }
+/** The last argument of an action function (`data-sn-call`, `<sn-resource call>`). */
+export interface CallContext {
+    /** aborts when the page is hidden (pagehide) or, for a resource, when its inputs change */
+    signal: AbortSignal;
+    /** a request through the app's middleware chain (401 handling, origins, timeout) */
+    request(url: string, init?: SendInit): Promise<unknown>;
+    /** the element whose action this is; null for a resource */
+    el: Element | null;
+}
 export interface ResourceLoader {
     def: ResourceDef;
     res: Resource;
     app: App;
     pager: Pager | null;
+    /** first load (or embedded/cached data) */
+    start(): void;
+    /** `src`, `when` (or an `each` list) may have changed */
+    changed(): void;
     load(move?: unknown): Promise<void>;
-    refetch(): Promise<void>;
+    refetch(hint?: object): Promise<void>;
+    /** for feature modules: the scope `src` and `when` are evaluated in */
+    scope(): any;
+    /** for feature modules: a shared GET (concurrent loads of one URL share one request) */
+    get(url: string, signal: AbortSignal): Promise<unknown>;
+    /** for feature modules: the collection items of a response body (`items` path, checked, cleaned) */
+    items(body: unknown): any[];
+    /** for feature modules: a failed load: `$meta.error`, then the unhandled-error path */
+    failed(e: unknown): void;
+    loading(on: boolean): void;
 }
 export interface App {
     readonly ir: IR;
@@ -67,6 +89,9 @@ export interface App {
         optimistic?: {
             begin(fn: number, scope: any): () => void;
         };
+        each?: {
+            fanOut(loader: ResourceLoader): void;
+        };
         paginate?: {
             pager(loader: ResourceLoader): Pager;
             page(name: string, target: string | number): void;
@@ -108,6 +133,8 @@ export interface App {
     state<T = any>(el: Element): StateHandle<T>;
     destroy(): void;
     url(tpl: UrlTemplate, scope: any): string;
+    /** the scope of root node `i` (its state), or the page scope for -1 */
+    scopeOf(i: number): any;
     mark(path: string, scope?: any): void;
     flush(): void;
     record(change: () => void): () => void;