@tiaforge-ui/sinter 0.0.0-stage → 0.2.0

package/llms.txt

@@ -0,0 +1,632 @@
+# sinter
+
+> sinter binds JSON APIs to plain HTML: keyed resources cached from the server, kept current from server events, rendered through <template> bindings, with optimistic mutations. A build step compiles annotated HTML into a page module; the browser runs no parser and no eval.
+
+Package: @tiaforge-ui/sinter. Every directive is a `data-sn-*` attribute or an `<sn-*>` element. Anything else is a build error with a suggestion.
+
+## Attributes
+
+- `data-sn-state` (object literal): declares local reactive state for the element and its subtree
+- `data-sn-text` (value expression): sets textContent; never HTML
+- `data-sn-attr` (object literal {href: …}): literal keys; null/false removes, true sets empty; URL values are checked
+- `data-sn-class` (object literal {unread: …}): toggles each class
+- `data-sn-style` (object literal {'--color': …}): sets each property with style.setProperty
+- `data-sn-show` (value expression): toggles the hidden attribute
+- `data-sn-prop` (object literal): sets JS properties; custom elements only
+- `data-sn-model` (state path): two-way binding for form controls
+- `data-sn-for` (item in list | (item, i) in list): repeats a <template> per item
+- `data-sn-key` (value expression): row identity; defaults to the resource key or object identity
+- `data-sn-if` (value expression): renders a <template> while truthy
+- `data-sn-else`: on a <template> directly after an if template
+- `data-sn-persist` (storage key): persists the model or state in localStorage under sn:
+- `data-sn-get` (URL template): GET action; latest wins
+- `data-sn-post` (URL template): POST action
+- `data-sn-put` (URL template): PUT action
+- `data-sn-patch` (URL template): PATCH action
+- `data-sn-delete` (URL template): DELETE action
+- `data-sn-call` (action call): local action: calls a function from the actions module, e.g. pgp.decrypt(msg)
+- `data-sn-body` (value expression): JSON request body; overrides form serialization
+- `data-sn-trigger` (DOM event name): overrides the default trigger
+- `data-sn-debounce` (milliseconds): delays the trigger, resets on each event; without a method, delays the element's data-sn-on-* handlers
+- `data-sn-concurrency` (block | queue | latest): mutations only; default block for forms, queue otherwise
+- `data-sn-optimistic` (handler expression): patch/upsert/remove calls applied before the request, rolled back on failure
+- `data-sn-then` (handler expression): runs after a 2xx response; $result = parsed body
+- `data-sn-catch` (handler expression): runs after an error; $error = {status, body, message}
+- `data-sn-path` (URL patterns /a/:b …): on <html>: the path shapes this page is served for; `:name` segments appear read-only in $url
+- `data-sn-data` (resource name): on <script type="application/json"> in <head>: initial data for a resource
+- `data-sn-on-<event>` (handler expression): plain event handler, no request; e.g. data-sn-on-click
+
+## Elements
+
+- `<sn-resource>` `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`: a named, page-wide cache of server data; `cache` (or `cache="10m"`) shows the data from the last page load at once, then revalidates
+- `<sn-sync>` `src`: one server event stream
+- `<sn-event>` `name`, `resource`, `op`, `item`, `set`, `when`, `fallback`, `type`: maps one server event to a change message; child of <sn-sync>
+- `<sn-include>` `src`: inlines a partial at build time
+
+## Expressions and scope
+
+- Attribute values are JavaScript expressions, checked at build time. Value expressions (text, attr, class, show, for, if, key, body, state, URL interpolations) cannot assign, use `++`, `delete`, `await` or `import()`.
+- Handlers (`data-sn-on-*`, `then`, `catch`) are statements separated by `;`: assignments to state, `$url.<param>` and `$locale`, and calls. No declarations or loops.
+- `data-sn-optimistic` may only call `patch`, `upsert`, `remove`.
+- A name resolves innermost first: loop variables, then the nearest `data-sn-state`, then resources, then magic names, helpers and store functions, then JavaScript globals. Browser APIs (`window`, `document`, `fetch`, timers, …) are refused: use an island.
+- Resources are read-only: copy an item with `structuredClone(c)` to edit it, write with `patch()`.
+- Helpers are plain function calls, never pipes: `date()`, `time()`, `datetime()`, `relative()`, `number()`, `bytes()`. Helper namespaces: `m.inbox_title()`.
+- URL templates: `/api/x?id={c.id}`; interpolations are URL-encoded; the template must start with a literal `/path` or `https://origin`.
+- Use `$now` instead of `Date.now()` so bindings update.
+
+## Magic names
+
+`$event`, `$el`, `$url`, `$now`, `$locale`, `$result`, `$error`, `$meta`. `$event` in handlers, `$result` in `then`, `$error` (`{status, body, message}`) in `catch`; `$meta.<resource>` has `loading`, `error`, `loadedAt`, `pending`, `total`, and with `paginate`: `page` (offset), `pages`, `from`, `to`, `hasPrev`, `hasNext`.
+
+## Store functions
+
+`refresh()`, `upsert()`, `patch()`, `remove()`, `page()`, `close()`, `reset()`, `emit()`: `refresh('name')`, `upsert('name', item)`, `patch('name', item, {…})`, `remove('name', item)`, `page('name', 'next' | 'prev' | 'first' | 'last' | n)`, `close()` the nearest dialog, `reset()` the nearest form, `emit('event', detail)`.
+
+## Diagnostics
+
+`SN101 unknown-attribute`, `SN102 wrong-element`, `SN103 missing-key`, `SN104 unsupported-model`, `SN201 unknown-identifier`, `SN202 forbidden-global`, `SN203 side-effect`, `SN204 optimistic-scope`, `SN205 resource-mutation`, `SN206 unknown-namespace-member`, `SN207 unsafe-sink`, `SN208 type-error`, `SN301 unknown-resource`, `SN302 duplicate-resource`, `SN303 unknown-meta-field`, `SN304 keyset-jump`, `SN305 include-not-found`, `SN306 include-cycle`, `SN307 openapi-invalid`, `SN308 unknown-schema-field`, `SN310 unknown-action`, `SN401 parse-error`, `SN501 unused-resource`, `SN502 non-reactive-value`, `SN503 data-bound-id`, `SN504 untyped-resource`, `SN505 unknown-query-param`, `SN506 untyped-event`.
+
+## Recipes
+
+Each recipe comes with its test; copy both.
+
+### List with filter
+
+```html
+<sn-resource name="people" src="/api/people" items="people" key="id" order="name"></sn-resource>
+
+<section data-sn-state="{ q: '' }">
+  <input type="search" placeholder="Search" data-sn-model="q">
+  <p data-sn-show="$meta.people.loading" aria-busy="true">Loading…</p>
+  <ul>
+    <template data-sn-for="p in people.filter(p => p.name.toLowerCase().includes(q.toLowerCase()))">
+      <li data-sn-text="p.name"></li>
+    </template>
+  </ul>
+</section>
+```
+
+```ts
+import { expect, test } from 'vitest';
+import { render, mockRequests } from '@tiaforge-ui/sinter/testing';
+import page from './list-filter.html?raw';
+
+
+test('filters the list as you type', async () => {
+  const requests = mockRequests({ 'GET /api/people': { people: [{ id: 1, name: 'Bob' }, { id: 2, name: 'Ada' }] } });
+  const { root, flush, settle } = await render(page, { requests });
+  await settle();
+  expect([...root.querySelectorAll('li')].map((li) => li.textContent)).toEqual(['Ada', 'Bob']);
+
+  const input = root.querySelector('input')!;
+  input.value = 'ad';
+  input.dispatchEvent(new Event('input', { bubbles: true }));
+  await flush();
+  expect([...root.querySelectorAll('li')].map((li) => li.textContent)).toEqual(['Ada']);
+});
+```
+
+### Form dialog with repeatable fields
+
+```html
+<sn-resource name="people" src="/api/people" key="id" order="name"></sn-resource>
+
+<section data-sn-state="{ draft: null }">
+  <button data-sn-on-click="draft = {name: '', emails: [{value: ''}]}" commandfor="edit" command="show-modal">New</button>
+  <ul>
+    <template data-sn-for="p in people">
+      <li>
+        <span data-sn-text="p.name"></span>
+        <button data-sn-on-click="draft = structuredClone(p)" commandfor="edit" command="show-modal">Edit</button>
+      </li>
+    </template>
+  </ul>
+
+  <dialog id="edit">
+    <form data-sn-post="/api/people" data-sn-body="draft"
+          data-sn-then="upsert('people', $result); draft = null; close()"
+          data-sn-catch="emit('toast', $error.message)">
+      <input data-sn-model="draft.name" required>
+      <template data-sn-for="(e, i) in draft.emails">
+        <input type="email" data-sn-model="draft.emails[i].value">
+      </template>
+      <button type="button" data-sn-on-click="draft.emails.push({value: ''})">Add email</button>
+      <button type="submit">Save</button>
+    </form>
+  </dialog>
+</section>
+```
+
+```ts
+import { expect, test } from 'vitest';
+import { render, mockRequests } from '@tiaforge-ui/sinter/testing';
+import page from './form-dialog.html?raw';
+
+
+test('saves the draft and upserts the result', async () => {
+  const requests = mockRequests({
+    'GET /api/people': [],
+    'POST /api/people': (call) => ({ id: 1, ...(call.body as object) }),
+  });
+  const { root, flush, settle } = await render(page, { requests });
+  await settle();
+  root.querySelector('button')!.click();               // New
+  const dialog = root.querySelector('dialog')!;
+  dialog.showModal();
+  dialog.dispatchEvent(new Event('toggle'));
+  await flush();
+
+  const [name, email] = root.querySelectorAll('dialog input');
+  (name as HTMLInputElement).value = 'Ada';
+  name!.dispatchEvent(new Event('input', { bubbles: true }));
+  (email as HTMLInputElement).value = 'ada@example.com';
+  email!.dispatchEvent(new Event('input', { bubbles: true }));
+  root.querySelector('form')!.requestSubmit();
+  await settle();
+
+  expect(requests.calls.at(-1)!.body).toEqual({ name: 'Ada', emails: [{ value: 'ada@example.com' }] });
+  expect(root.querySelector('li span')!.textContent).toBe('Ada');
+  expect(dialog.open).toBe(false);
+});
+```
+
+### SSE sync
+
+```html
+<sn-resource name="people" src="/api/people" key="id" order="name"></sn-resource>
+
+<sn-sync src="/api/events">
+  <sn-event name="person_updated" resource="people" op="upsert" item="person" fallback="refetch"></sn-event>
+  <sn-event name="person_removed" resource="people" op="remove"></sn-event>
+</sn-sync>
+
+<ul>
+  <template data-sn-for="p in people"><li data-sn-text="p.name"></li></template>
+</ul>
+```
+
+```ts
+import { expect, test } from 'vitest';
+import { render, mockRequests, mockStream } from '@tiaforge-ui/sinter/testing';
+import page from './sse-sync.html?raw';
+
+
+test('applies server events to the list', async () => {
+  const requests = mockRequests({ 'GET /api/people': [{ id: 1, name: 'Bob' }] });
+  const stream = mockStream();
+  const { root, flush, settle } = await render(page, { requests, streams: { '/api/events': stream } });
+  await settle();
+
+  stream.emit('person_updated', { person: { id: 2, name: 'Ada' } });
+  stream.emit('person_removed', { id: 1 });
+  await flush();
+  expect([...root.querySelectorAll('li')].map((li) => li.textContent)).toEqual(['Ada']);
+});
+```
+
+### Optimistic toggle
+
+```html
+<sn-resource name="messages" src="/api/messages" key="id"></sn-resource>
+
+<template data-sn-for="m in messages">
+  <article>
+    <span data-sn-text="m.subject"></span>
+    <button data-sn-patch="/api/messages/{m.id}"
+            data-sn-body="{is_flagged: !m.is_flagged}"
+            data-sn-optimistic="patch('messages', m, {is_flagged: !m.is_flagged})"
+            data-sn-attr="{'aria-pressed': m.is_flagged ? 'true' : 'false'}">★</button>
+  </article>
+</template>
+```
+
+```ts
+import { expect, test } from 'vitest';
+import { render, mockRequests } from '@tiaforge-ui/sinter/testing';
+import page from './optimistic-toggle.html?raw';
+
+
+test('flags at once and rolls back when the server refuses', async () => {
+  const requests = mockRequests({
+    'GET /api/messages': [{ id: 1, subject: 'Hi', is_flagged: false }],
+    'PATCH /api/messages/1': { status: 500 },
+  });
+  const { root, flush, settle } = await render(page, { requests });
+  await settle();
+  const star = root.querySelector('button')!;
+
+  star.click();
+  await flush();
+  expect(star.getAttribute('aria-pressed')).toBe('true');   // optimistic
+
+  await settle();
+  expect(star.getAttribute('aria-pressed')).toBe('false');  // rolled back
+});
+```
+
+### Pagination
+
+```html
+<sn-resource name="messages" src="/api/messages" items="messages" total="total" key="id"
+  paginate="keyset" page-size="2" cursor="{before: id}"></sn-resource>
+
+<ul>
+  <template data-sn-for="m in messages"><li data-sn-text="m.subject"></li></template>
+</ul>
+<nav>
+  <button data-sn-on-click="page('messages', 'prev')" data-sn-attr="{disabled: !$meta.messages.hasPrev}">‹</button>
+  <span data-sn-text="`${$meta.messages.from}–${$meta.messages.to} of ${$meta.messages.total}`"></span>
+  <button data-sn-on-click="page('messages', 'next')" data-sn-attr="{disabled: !$meta.messages.hasNext}">›</button>
+</nav>
+```
+
+```ts
+import { expect, test } from 'vitest';
+import { render, mockRequests } from '@tiaforge-ui/sinter/testing';
+import page from './pagination.html?raw';
+
+const all = [5, 4, 3, 2, 1].map((id) => ({ id, subject: `m${id}` }));
+
+test('moves to the next page with a cursor', async () => {
+  const requests = mockRequests({
+    'GET /api/messages': (call) => {
+      const q = new URL(call.url, 'http://x').searchParams;
+      const before = Number(q.get('before') ?? Infinity);
+      const items = q.get('direction') === 'next' ? all.filter((m) => m.id < before) : all;
+      return { messages: items.slice(0, Number(q.get('limit'))), total: all.length };
+    },
+  });
+  const { root, settle } = await render(page, { requests });
+  await settle();
+  expect(root.querySelector('span')!.textContent).toBe('1–2 of 5');
+
+  root.querySelector<HTMLButtonElement>('nav button:last-of-type')!.click();
+  await settle();
+  expect([...root.querySelectorAll('li')].map((li) => li.textContent)).toEqual(['m3', 'm2']);
+  expect(root.querySelector('span')!.textContent).toBe('3–4 of 5');
+  expect(requests.calls.at(-1)!.url).toBe('/api/messages?before=4&limit=2&direction=next');
+});
+```
+
+### SignalR (or another transport) for <sn-sync>
+
+```html
+<!-- The page is the same as with SSE: only the configured transport differs (signalr-transport.js). -->
+<sn-resource name="people" src="/api/people" key="id" order="name"></sn-resource>
+
+<sn-sync src="/hubs/people">
+  <sn-event name="person_updated" resource="people" op="upsert" item="person"></sn-event>
+  <sn-event name="person_removed" resource="people" op="remove"></sn-event>
+</sn-sync>
+
+<ul>
+  <template data-sn-for="p in people"><li data-sn-text="p.name"></li></template>
+</ul>
+```
+
+```js
+// SignalR transport for <sn-sync>, in your app (sinter does not depend on @microsoft/signalr).
+// In src/sinter.config.js:
+//
+//   import { HubConnectionBuilder } from '@microsoft/signalr';
+//   import { configure } from '@tiaforge-ui/sinter';
+//   import { signalRTransport } from './signalr-transport.js';
+//
+//   configure({
+//     transport: (url) => url.startsWith('/hubs/')
+//       ? signalRTransport(() => new HubConnectionBuilder().withUrl(url).build())
+//       : undefined,
+//   });
+//
+// Server: `await Clients.All.SendAsync("person_updated", new { person })`; the first argument is
+// the payload. Hub method names are case-insensitive in SignalR, so keep event names distinct in
+// more than case. Do not call withAutomaticReconnect(): sinter reconnects (session probe, backoff,
+// refetch of everything the stream feeds), and two reconnect loops would race. Auth is the hub's:
+// cookies, or withUrl(url, { accessTokenFactory }); request middleware does not apply.
+
+/** @param {() => import('@microsoft/signalr').HubConnection} build a new, unstarted connection */
+export function signalRTransport(build) {
+  let hub = null;
+  let deliver = null;
+  const names = new Set();
+  const add = (name) => {
+    if (!hub || names.has(name)) return;
+    names.add(name);
+    const h = hub;
+    h.on(name, (payload) => { if (hub === h) deliver(name, payload ?? null); });
+  };
+  return {
+    connect(url, onEvent, onState, initial) {
+      const h = hub = build();
+      deliver = onEvent;
+      names.clear();
+      for (const n of initial) add(n);
+      h.onclose(() => { if (hub === h) { hub = null; onState('error'); } });
+      h.start().then(() => { if (hub === h) onState('open'); }, () => { if (hub === h) { hub = null; onState('error'); } });
+    },
+    listen: add,
+    close() {
+      const h = hub;
+      hub = null; // nothing is reported after close()
+      h?.stop().catch(() => {});
+    },
+  };
+}
+```
+
+```ts
+import { afterEach, expect, test } from 'vitest';
+import { configure } from '@tiaforge-ui/sinter';
+import { render, mockRequests } from '@tiaforge-ui/sinter/testing';
+import { signalRTransport } from './signalr-transport.js';
+import page from './signalr.html?raw';
+
+// A stand-in for HubConnection: the test calls invoke() where the server would call SendAsync().
+function fakeHub() {
+  const handlers = new Map<string, (payload: unknown) => void>();
+  let onclose = () => {};
+  return {
+    started: false,
+    on(name: string, fn: (payload: unknown) => void) { handlers.set(name, fn); },
+    onclose(fn: () => void) { onclose = fn; },
+    async start() { this.started = true; },
+    async stop() { this.started = false; },
+    invoke(name: string, payload: unknown) { handlers.get(name)?.(payload); },
+    lose() { this.started = false; onclose(); },
+  };
+}
+
+afterEach(() => configure({ transport: null }));
+
+test('applies hub messages to the list', async () => {
+  const hubs: Array<ReturnType<typeof fakeHub>> = [];
+  configure({ transport: (url) => (url.startsWith('/hubs/') ? signalRTransport(() => { hubs.push(fakeHub()); return hubs.at(-1) as never; }) : undefined) });
+  const requests = mockRequests({ 'GET /api/people': [{ id: 1, name: 'Bob' }] });
+  const { root, flush, settle, advance } = await render(page, { requests });
+  await settle();
+  expect(hubs[0]!.started).toBe(true);
+
+  hubs[0]!.invoke('person_updated', { person: { id: 2, name: 'Ada' } });
+  hubs[0]!.invoke('person_removed', { id: 1 });
+  await flush();
+  expect([...root.querySelectorAll('li')].map((li) => li.textContent)).toEqual(['Ada']);
+
+  // a lost connection: sinter reconnects with a new hub and refetches what the stream feeds
+  hubs[0]!.lose();
+  await advance(2000); // the backoff (1 s ± jitter) before reconnecting
+  await settle();
+  expect(hubs).toHaveLength(2);
+  expect(requests.calls.filter((c) => c.path === '/api/people')).toHaveLength(2);
+});
+```
+
+### Typed resources, state and events
+
+```html
+<sn-resource name="contacts" src="/api/contacts" items="contacts" key="id" type="Contact[]"></sn-resource>
+
+<sn-sync src="/api/events">
+  <sn-event name="contact_updated" resource="contacts" op="upsert" item="contact" type="ContactEvent"></sn-event>
+</sn-sync>
+
+<section data-sn-state="{ editing: /** @type {Contact|null} */ (null) }">
+  <ul>
+    <template data-sn-for="c in contacts">
+      <li>
+        <span data-sn-text="c.name"></span>
+        <small data-sn-text="c.email ?? 'no email'"></small>
+        <button data-sn-on-click="editing = structuredClone(c)">Edit</button>
+      </li>
+    </template>
+  </ul>
+  <template data-sn-if="editing">
+    <form data-sn-put="/api/contacts/{editing.id}" data-sn-body="editing"
+          data-sn-then="upsert('contacts', $result); editing = null">
+      <input data-sn-model="editing.name" required>
+      <button>Save</button>
+    </form>
+  </template>
+</section>
+```
+
+```ts
+// src/sinter.types.ts
+export interface Contact { id: number; name: string; email: string | null }
+export interface ContactEvent { contact: Contact }
+```
+
+```ts
+import { expect, test } from 'vitest';
+import { checkPage } from '@tiaforge-ui/sinter/check';
+import page from './typed.html?raw';
+import types from './typed.types.ts?raw';
+
+// In CI: `npx sinter check` (pages and options from the Vite config).
+const files = { 'src/sinter.types.ts': types };
+
+test('every expression type-checks', () => {
+  expect(checkPage(page, { files })).toEqual([]);
+});
+
+test('a typo in a field is an error at its position, with a suggestion', () => {
+  const [d] = checkPage(page.replace('c.email ??', 'c.emial ??'), { files });
+  expect(d).toMatchObject({ code: 'SN208', file: 'index.html', line: 12 });
+  expect(d!.message).toMatch(/Property 'emial' does not exist on type 'Contact'. Did you mean 'email'\?/);
+});
+
+test('an event payload that does not fit the resource is an error', () => {
+  const [d] = checkPage(page.replace('item="contact"', 'item="contact.name"'), { files });
+  expect(d!.message).toMatch(/Type 'string' is not assignable to type 'Contact'/);
+});
+```
+
+### Cached list across page loads
+
+```html
+<!-- `cache`: the next page load shows this list at once, then revalidates.
+     `$meta.inbox.loading` with data present means "updating"; `$meta.inbox.loadedAt`
+     stays null until the server has answered on this page. -->
+<sn-resource name="inbox" src="/api/messages?folder=inbox" key="id" order="-date" cache="1h"></sn-resource>
+
+<p data-sn-show="$meta.inbox.loading && inbox.length">Updating…</p>
+<ul>
+  <template data-sn-for="m in inbox">
+    <li data-sn-text="m.subject"></li>
+  </template>
+</ul>
+```
+
+```ts
+import { expect, test } from 'vitest';
+import { render, mockRequests, memoryStorage } from '@tiaforge-ui/sinter/testing';
+import page from './cached-list.html?raw';
+
+const subjects = (root: HTMLElement) => [...root.querySelectorAll('li')].map((li) => li.textContent);
+
+test('the next page load shows the cached list while it revalidates', async () => {
+  // one tab: the same sessionStorage for both page loads
+  const session = memoryStorage();
+  const first = await render(page, { session, requests: mockRequests({
+    'GET /api/messages': [{ id: 1, subject: 'Welcome', date: '2026-01-01' }],
+  }) });
+  await first.settle();
+
+  const { root, settle } = await render(page, { session, requests: mockRequests({
+    'GET /api/messages': [{ id: 2, subject: 'Lunch?', date: '2026-01-02' }, { id: 1, subject: 'Welcome', date: '2026-01-01' }],
+  }) });
+  expect(subjects(root)).toEqual(['Welcome']);                    // cached, before any response
+  expect(root.querySelector('p')!.hidden).toBe(false);            // "Updating…"
+
+  await settle();
+  expect(subjects(root)).toEqual(['Lunch?', 'Welcome']);
+  expect(root.querySelector('p')!.hidden).toBe(true);
+});
+```
+
+### Local actions: hash a file, then upload it
+
+```html
+<section data-sn-state="{ file: null, url: '', error: '' }">
+  <sn-resource name="digest" call="sha256(file)" when="file"></sn-resource>
+
+  <input type="file" data-sn-on-change="file = $el.files[0] ?? null; url = ''">
+  <p data-sn-show="$meta.digest.loading">Hashing…</p>
+  <code data-sn-text="digest"></code>
+
+  <button data-sn-call="upload(file, digest)" data-sn-attr="{disabled: !digest}"
+          data-sn-then="url = $result.url; error = ''" data-sn-catch="error = $error.message">Upload</button>
+  <a data-sn-show="url" data-sn-attr="{href: url}">Uploaded</a>
+  <p role="alert" data-sn-text="error"></p>
+</section>
+```
+
+```js
+// src/sinter.actions.js: functions pages call with data-sn-call and <sn-resource call>.
+// The last argument is sinter's context; with JSDoc types, `sinter check` checks the calls.
+/** @import { CallContext } from '@tiaforge-ui/sinter' */
+
+/**
+ * The file's SHA-256 as hex; choosing another file aborts the running hash through ctx.signal.
+ * @param {File} file
+ * @param {CallContext} ctx
+ * @returns {Promise<string>}
+ */
+export async function sha256(file, ctx) {
+  const bytes = await file.arrayBuffer();
+  ctx.signal.throwIfAborted();
+  const hash = await crypto.subtle.digest('SHA-256', bytes);
+  return [...new Uint8Array(hash)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * ctx.request goes through the app's middleware (headers, 401 handling, allowed origins).
+ * @param {File} file
+ * @param {string} digest
+ * @param {CallContext} ctx
+ * @returns {Promise<{ url: string }>}
+ */
+export async function upload(file, digest, ctx) {
+  const form = new FormData();
+  form.append('file', file);
+  form.append('sha256', digest);
+  return /** @type {Promise<{ url: string }>} */ (ctx.request('/api/uploads', { method: 'POST', body: form }));
+}
+```
+
+```ts
+import { expect, test } from 'vitest';
+import { checkPage } from '@tiaforge-ui/sinter/check';
+import { render, mockRequests } from '@tiaforge-ui/sinter/testing';
+import * as actions from './local-actions.actions.js';
+import source from './local-actions.actions.js?raw';
+import page from './local-actions.html?raw';
+
+const DIGEST = 'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad'; // sha256('abc')
+
+function choose(input: HTMLInputElement, file: File) {
+  Object.defineProperty(input, 'files', { value: [file], configurable: true });
+  input.dispatchEvent(new Event('change', { bubbles: true }));
+}
+
+test('hashes the chosen file, then uploads it with its digest', async () => {
+  const requests = mockRequests({ 'POST /api/uploads': { url: '/files/1' } });
+  const { root, settle } = await render(page, { actions, requests });
+  const button = root.querySelector('button')!;
+  expect(button.disabled).toBe(true);
+
+  choose(root.querySelector('input')!, new File(['abc'], 'abc.txt'));
+  await settle();
+  expect(root.querySelector('code')!.textContent).toBe(DIGEST);
+  expect(button.disabled).toBe(false);
+
+  button.click();
+  await settle();
+  expect((requests.calls[0]!.body as FormData).get('sha256')).toBe(DIGEST);
+  expect(root.querySelector('a')!.getAttribute('href')).toBe('/files/1');
+});
+
+test('a failed upload shows the server message', async () => {
+  const requests = mockRequests({ 'POST /api/uploads': { status: 413, body: { message: 'File too large' } } });
+  const { root, settle } = await render(page, { actions, requests });
+  choose(root.querySelector('input')!, new File(['abc'], 'abc.txt'));
+  await settle();
+  root.querySelector('button')!.click();
+  await settle();
+  expect(root.querySelector('[role=alert]')!.textContent).toBe('File too large');
+});
+
+test('sinter check: arguments are checked against the actions', () => {
+  const files = { 'src/sinter.actions.js': source };
+  expect(checkPage(page, { files })).toEqual([]);
+  const [d] = checkPage(page.replace('upload(file, digest)', 'upload(file)'), { files });
+  expect([d!.code, d!.message]).toEqual(['SN208', expect.stringContaining("is not assignable to type '[file: File, digest: string]'")]);
+});
+```
+
+## Type checking
+
+`npx sinter check` type-checks every expression with the project's TypeScript (pages and options come from the Vite config). `sinter({ typecheck: true })` runs it in `vite build`.
+
+- `<sn-resource … type="Contact[]">`: the type of what `items` selects, using names exported by `src/sinter.types.ts`. `type="any"` opts out; no `type` is warning SN504.
+- `sinter({ openapi: 'openapi.yml' })`: resources without `type` are matched to a GET operation by `src` (server prefix stripped, `{…}` matches a path parameter) and typed from its JSON response at `items`. Every build then checks `items`/`total` against the schema (SN308) and query parameter names (SN505).
+- State takes a JSDoc cast where the literal is not enough: `data-sn-state="{ editing: /** @type {Contact|null} */ (null) }"`.
+- Actions matched in the spec: `data-sn-body` is checked against the request schema, `$result` in `then` has the response type.
+- `<sn-event … type="ContactEvent">` types the payload; `item` must fit the resource's item, `set` part of it; `cursor` reads the item. No `type` on an event with payload expressions is warning SN506.
+- Errors are SN208 at the HTML position, with TypeScript's message. Null checks are off. In tests: `checkPage(html, { files, openapi })` from `@tiaforge-ui/sinter/check`.
+
+## Deploying streams
+
+Each open EventSource holds one HTTP connection, and HTTP/1.1 allows 6 per origin: with more than 5 tabs open, pages stop loading. Serve streams over HTTP/2 (any TLS reverse proxy such as nginx or Caddy) or use the WebSocket transport; dev builds warn about HTTP/1.1.
+
+## Editors
+
+`npx sinter lsp --stdio` is a language server for the project's HTML files: sinter's diagnostics as you type (partials checked through the pages that include them), and with TypeScript 7 type errors, hover, completion in expressions, go to definition and a did-you-mean quick fix. VS Code: the extension in `editors/vscode`. Setup for Neovim, Helix and Emacs: `docs/editors.md`. Every diagnostic links to its explanation in `docs/diagnostics.md`.
+
+## Testing
+
+Write a test next to the markup. `@tiaforge-ui/sinter/testing` compiles the page with the real compiler and mounts it:
+
+- `render(html, { requests, streams, url, locale, now, helpers, actions, files, storage, session })` → `{ root, app, flush, settle, advance, navigations, window }`. Pass one `memoryStorage()` as `session` to two renders to test what carries over between page loads (the `cache` attribute).
+- `mockRequests({ 'GET /api/x': json | {status, body} | (call) => … })`: records `calls`; responses are held until `settle()`; an unmatched request fails the test and lists the routes.
+- `mockStream()`: `emit(name, payload)`, `drop()`, `connected`. A stream URL with no mock uses the transport from `configure({ transport })`, so a custom transport can be tested over a fake connection (see the SignalR recipe).
+- `flush()` runs the scheduler (optimistic changes are visible), `settle()` finishes requests, queues and debounces, `advance(ms)` moves sinter's clock.