create-sinter 0.0.0-stage → 0.15.0

package/README.md

@@ -1,3 +1,19 @@
-# Temporary Holding Version
+# create-sinter
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Scaffolds a small task board built with [sinter](https://github.com/tiaforge/sinter) (your JSON API
+bound to plain HTML) and [temper](https://github.com/tiaforge/temper) (CSS for semantic HTML).
+
+```sh
+npm create sinter my-app
+```
+
+It runs against a demo API inside Vite, so there is nothing else to start. The app shows:
+
+- server data with live updates across tabs
+- optimistic changes that roll back when the server refuses
+- a dialog without JavaScript
+- a layout both pages share, and components (one with a script that draws a canvas chart)
+- next-page data and page transitions
+- build-time checks that turn typos into build errors
+
+The template is in [`template/`](template). Its README lists what to try first.

package/index.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// `npm create sinter [directory]`: copies the template (a sinter + temper app with a demo
+// API) into a new directory. No dependencies; Node 20 or later.
+import { cpSync, existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { basename, join, relative, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+
+const DEFAULT_DIR = 'tiaforge-app';
+const args = process.argv.slice(2);
+
+if (args.includes('-h') || args.includes('--help')) {
+  console.log(`Usage: npm create sinter [directory]
+
+Creates a task board built with sinter (data) and temper (styles), with a demo API inside Vite.`);
+  process.exit(0);
+}
+
+let dir = args.find((a) => !a.startsWith('-'));
+if (!dir) {
+  if (process.stdin.isTTY) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    dir = (await rl.question(`Directory (${DEFAULT_DIR}): `)).trim() || DEFAULT_DIR;
+    rl.close();
+  } else {
+    dir = DEFAULT_DIR;
+  }
+}
+
+const target = resolve(dir);
+if (existsSync(target) && readdirSync(target).length) {
+  console.error(`${dir} is not empty. Choose a new directory.`);
+  process.exit(1);
+}
+
+cpSync(join(import.meta.dirname, 'template'), target, { recursive: true });
+// npm leaves .gitignore out of published packages, so the template carries it as _gitignore
+renameSync(join(target, '_gitignore'), join(target, '.gitignore'));
+
+const pkgPath = join(target, 'package.json');
+const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+pkg.name = basename(target).toLowerCase().replace(/[^a-z0-9._~-]+/g, '-').replace(/^[._-]+|-+$/g, '') || DEFAULT_DIR;
+writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+
+const pm = (process.env.npm_config_user_agent ?? 'npm').split('/')[0];
+const run = pm === 'npm' ? 'npm run' : pm;
+const cd = relative(process.cwd(), target) || '.';
+console.log(`
+Created ${cd}. Next:
+
+  ${cd === '.' ? '' : `cd ${cd.includes(' ') ? JSON.stringify(cd) : cd}\n  `}${pm} install
+  ${run} dev
+
+The README lists what to try first.`);

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "create-sinter",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.15.0",
+  "description": "npm create sinter: a new app with sinter (JSON API bound to HTML) and temper (CSS for semantic HTML).",
+  "license": "MIT",
+  "author": "Tia Heinrich",
+  "homepage": "https://github.com/tiaforge/sinter/tree/main/packages/create#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tiaforge/sinter.git",
+    "directory": "packages/create"
+  },
+  "bugs": {
+    "url": "https://github.com/tiaforge/sinter/issues"
+  },
+  "keywords": [
+    "create",
+    "scaffold",
+    "template",
+    "sinter",
+    "temper",
+    "vite"
+  ],
+  "type": "module",
+  "bin": {
+    "create-sinter": "index.js"
+  },
+  "files": [
+    "index.js",
+    "template"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/template/AGENTS.md

@@ -0,0 +1,16 @@
+# Notes for coding agents
+
+- Data and behavior: sinter (`data-sn-*` attributes, `<sn-*>` elements). Read
+  `node_modules/@tiaforge-ui/sinter/llms.txt` before editing pages.
+- Styling: temper (`data-variant`, `data-tone`, `data-layout`, … with fixed values; no classes for
+  looks, no margins). Read `node_modules/@tiaforge-ui/temper/llms.txt` before editing markup, and
+  `llms-full.txt` before building whole pages.
+- Shared page markup (head, header, frame, toasts) is a layout: `src/layouts/app-layout.html`. Each page is only the
+  layout's tag, `<app-layout data-sn-prop="{ title: '…' }">…</app-layout>`, and its children fill the layout's slots
+  (`slot="head"` for head elements). Change the shared parts there, not in each page.
+- Browser APIs (storage, timers, canvas, `fetch`) are not allowed in expressions: put them in a
+  component's script (`src/components/<name>.ts` beside `<name>.html`, extending the class imported
+  from `./<name>.html`; it writes state, never nodes sinter renders).
+- Types for `type="…"` go in `src/sinter.types.ts`.
+- Run `npm run check` after editing; `npm run build` runs the same checks.
+- `server/api.js` is a demo backend. Do not grow it into the real one.

package/template/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/template/README.md

@@ -0,0 +1,81 @@
+# Tasks: sinter + temper
+
+A small task board: [sinter](https://github.com/tiaforge/sinter) binds the JSON API to plain HTML,
+[temper](https://github.com/tiaforge/temper) styles the HTML. There is no router, no store and no
+hydration: the pages share a layout and two components, all expanded at build time, and the only CSS
+the app writes is the chart's.
+
+```sh
+npm install
+npm run dev
+```
+
+## Try this
+
+- **Open the page in two tabs.** Tick, add or delete a task in one; the other follows. The server
+  sends events (`<sn-sync>` in `index.html`), and sinter applies them to the list.
+- **Press "Fail next change", then tick a task.** The tick shows at once (`data-sn-optimistic`),
+  the server refuses it, and the tick is taken back. The toast comes from `onError` in
+  `src/sinter.config.ts`.
+- **Press N.** A key filter on `<body>` opens the dialog. The dialog itself needs no JavaScript:
+  `command="show-modal"` is the browser's.
+- **Click the ring.** It is a component with a script (`src/components/task-chart.html` and
+  `.ts`): sinter renders its markup, the script draws on the canvas; it gets the tasks through
+  `data-sn-prop` and sends the filter back as an event.
+- **Rest the pointer on a task, then click it.** Its data was requested while you pointed, so
+  `task.html` shows it at once, and the title morphs into the page's heading.
+- **Reload.** The list appears before the server answers (`cache`), and the filter is kept
+  (`data-sn-persist`).
+- **Change `--tm-hue` in `src/style.css`.** Every color follows, in light and dark mode.
+
+## Break it on purpose
+
+Both libraries check the markup at build time. Make these typos in `index.html` and run
+`npm run build`:
+
+| Change | Build error |
+| --- | --- |
+| `t.title` → `t.titel` | `SN208 Property 'titel' does not exist on type 'Task'. Did you mean 'title'?` |
+| `visible(tasks, q, show)` → `visible(tasks, qq, show)` | ``SN201 `qq` is not defined here. Did you mean `q`?`` |
+| `data-variant="ghost"` → `data-variant="danger"` on the delete button | `TM101 data-variant="danger" is not valid. Did you mean data-tone="danger"?` |
+
+`npm run check` runs both checkers without building. Your editor can show the same errors as you
+type: see sinter's `docs/editors.md`.
+
+## Files
+
+| File | What it is |
+| --- | --- |
+| `index.html`, `task.html` | The pages: `data-sn-*` for data, `data-*` from temper for looks. Each is one `<app-layout>` tag. |
+| `src/layouts/app-layout.html` | The layout: the head, the header and the frame both pages share; the page's content fills its slot. |
+| `src/components/app-header.html` | A component: shared markup, expanded at build time where `<app-header>` is used. |
+| `src/components/task-chart.html` | A component with a script: its markup, props and event. |
+| `src/sinter.types.ts` | The API's types. `type="Task[]"` on a resource checks every expression that reads it. |
+| `src/sinter.helpers.ts` | Functions expressions can call (`visible(…)`). |
+| `src/sinter.config.ts` | Error handling. |
+| `src/components/*.ts` | Scripts of components, for browser work: canvas, editors, storage, timers. |
+| `src/sinter.components.d.ts` | Generated: the types of the components' scripts and the layout's props, from their HTML. |
+| `src/style.css` | temper's modules and the brand color. |
+| `server/api.js` | The demo backend, running inside Vite. |
+
+## Your own API
+
+Remove `api()` from `vite.config.js`, delete `server/`, and proxy `/api` to your server in
+development:
+
+```js
+server: { proxy: { '/api': 'http://localhost:3000' } },
+```
+
+In production, serve `dist/` and your API from the same origin. For an API on another origin, list
+it in `sinter({ origins: ['https://api.example.com'] })`. With an OpenAPI spec,
+`sinter({ openapi: 'openapi.yml' })` types resources without `type="…"`, checks request bodies, and
+applies more responses to the lists by itself.
+
+Serve the event stream over HTTP/2: over HTTP/1.1 each open tab holds one of the browser's six
+connections per origin. The dev server is HTTP/1.1, so it warns in the console.
+
+## Learn more
+
+- sinter: `node_modules/@tiaforge-ui/sinter/llms.txt` (attributes, recipes and their tests)
+- temper: `node_modules/@tiaforge-ui/temper/llms-full.txt` (attributes, tokens, recipes)

package/template/_gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+.sinter/

package/template/index.html

@@ -0,0 +1,78 @@
+<!-- The page is the app layout (src/layouts/app-layout.html): its head, header and frame. Page state: the
+     search, the filter (kept across page loads by data-sn-persist) and the new task's draft.
+     N opens the new-task dialog. -->
+<app-layout data-sn-state="{ q: '', show: 'all', draft: { title: '' } }"
+            data-sn-on-keydown-n="showModal('new-task')">
+
+  <!-- The data: loaded once, kept sorted, shown at once on the next page load (`cache`), then revalidated. -->
+  <sn-resource name="tasks" src="/api/tasks" key="id" order="-createdAt" type="Task[]" cache></sn-resource>
+
+  <!-- Live updates: what another tab (or user) changes arrives as server events. -->
+  <sn-sync src="/api/events">
+    <sn-event name="task_updated" resource="tasks" op="upsert" item="task" type="TaskEvent"></sn-event>
+    <sn-event name="task_removed" resource="tasks" op="remove" type="TaskRemoved"></sn-event>
+  </sn-sync>
+
+  <div data-layout="row" data-gap="sm">
+    <h1 data-grow>Tasks</h1>
+    <button commandfor="new-task" command="show-modal" data-icon="plus">New task <kbd>N</kbd></button>
+  </div>
+
+  <!-- split: the chart beside the list, above it on a phone -->
+  <div data-layout="split" data-gap="lg" style="--tm-split: 9rem">
+    <!-- A component with a script: the tasks in through props, the filter back out through its event. -->
+    <aside>
+      <task-chart data-sn-prop="{ tasks, show }" data-sn-on-pick="show = $event.detail"></task-chart>
+    </aside>
+
+    <section data-layout="stack" data-gap="md" data-sn-let="{ shown: visible(tasks, q, show) }">
+      <div data-layout="row" data-gap="sm">
+        <input type="search" data-grow placeholder="Search" aria-label="Search tasks" data-sn-model="q">
+        <select aria-label="Show" data-sn-model="show" data-sn-persist="task-filter">
+          <option value="all">All</option>
+          <option value="open">Open</option>
+          <option value="done">Done</option>
+        </select>
+      </div>
+
+      <p data-sn-show="$meta.tasks.loading && !tasks.length" aria-busy="true">Loading…</p>
+      <p data-muted data-sn-show="$meta.tasks.loadedAt && !shown.length">No tasks here.</p>
+
+      <ul data-list data-sn-show="shown.length">
+        <template data-sn-for="t in shown">
+          <li data-layout="row" data-gap="sm" data-wrap="none">
+            <!-- Optimistic: ticks at once, rolls back if the server refuses. -->
+            <input type="checkbox" aria-label="Done"
+                   data-sn-patch="/api/tasks/{t.id}" data-sn-body="{ done: !t.done }"
+                   data-sn-optimistic="patch(t, { done: !t.done })"
+                   data-sn-attr="{ checked: t.done }">
+            <!-- The title morphs into the heading of the task's page (view transition). -->
+            <div data-grow data-layout="stack" data-gap="none">
+              <a data-truncate data-sn-attr="{ href: '/task/?id=' + t.id }"
+                 data-sn-transition="'task-' + t.id" data-sn-text="t.title"></a>
+              <small data-muted data-sn-text="relative(t.createdAt)"></small>
+            </div>
+            <button data-icon="trash-2" data-variant="ghost" data-size="sm" data-tone="danger" aria-label="Delete task"
+                    data-sn-delete="/api/tasks/{t.id}" data-sn-optimistic="remove(t)"></button>
+          </li>
+        </template>
+      </ul>
+    </section>
+  </div>
+
+  <dialog id="new-task" closedby="any">
+    <form data-layout="stack" data-gap="md" data-sn-post="/api/tasks" data-sn-body="draft"
+          data-sn-then="upsert('tasks', $result); draft = { title: '' }; close()">
+      <header>
+        <h2>New task</h2>
+        <button type="button" commandfor="new-task" command="close" aria-label="Close"></button>
+      </header>
+      <!-- `name`: a 422 with { errors: { title: … } } marks this field and shows the message after it. -->
+      <label>Title <input name="title" data-sn-model="draft.title" required autofocus></label>
+      <footer>
+        <button type="button" commandfor="new-task" command="close" data-variant="ghost">Cancel</button>
+        <button>Add task</button>
+      </footer>
+    </form>
+  </dialog>
+</app-layout>

package/template/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "tiaforge-app",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "check": "sinter check && temper check ."
+  },
+  "dependencies": {
+    "@tiaforge-ui/sinter": "^0.15.0",
+    "@tiaforge-ui/temper": "^0.1.9"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "vite": "^8.3.5"
+  }
+}

package/template/server/api.js

@@ -0,0 +1,125 @@
+// A stand-in for your backend: an in-memory task list with a JSON API and a server-sent event
+// stream, served by Vite in `npm run dev` and `npm run preview`. When your real API is up, remove
+// `api()` from vite.config.js (and proxy /api to your server there, `server.proxy`).
+//
+//   GET    /api/tasks          all tasks
+//   POST   /api/tasks          { title } → the new task
+//   GET    /api/tasks/:id      one task
+//   PATCH  /api/tasks/:id      { title?, notes?, done? } → the task
+//   DELETE /api/tasks/:id
+//   GET    /api/events         task_updated { task }, task_removed { id }
+//   POST   /api/fail-next      the next change (POST, PATCH, DELETE) fails with a 503
+
+/** Every request waits this long, so optimistic updates are visible. */
+const LATENCY_MS = 300;
+
+/** @returns {import('vite').Plugin} */
+export default function api() {
+  /** @type {Map<string, { id: string, title: string, notes: string, done: boolean, createdAt: string }>} */
+  const tasks = new Map();
+  /** @type {Set<import('node:http').ServerResponse>} */
+  const streams = new Set();
+  let failNext = false;
+  let lastId = 0;
+
+  const create = (title, done = false, minutesAgo = 0) => {
+    const id = String(++lastId);
+    const task = { id, title, notes: '', done, createdAt: new Date(Date.now() - minutesAgo * 60_000).toISOString() };
+    tasks.set(id, task);
+    return task;
+  };
+  create('Read the README', true, 90);
+  create('Open this page in a second tab, then tick a task in one of them', false, 60);
+  create('Press "Fail next change", then tick a task', false, 30);
+  create('Open a task and give it some notes', false, 10);
+
+  /** Sends one event to every open stream. */
+  const broadcast = (event, data) => {
+    for (const res of streams) res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+  };
+
+  /** @type {import('vite').Connect.NextHandleFunction} */
+  const handle = async (req, res, next) => {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    if (!url.pathname.startsWith('/api/')) return next();
+
+    const send = (status, body) => {
+      res.statusCode = status;
+      if (body === undefined) return res.end();
+      res.setHeader('content-type', 'application/json');
+      res.end(JSON.stringify(body));
+    };
+
+    if (url.pathname === '/api/events') {
+      res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-store' });
+      res.write(': connected\n\n');
+      streams.add(res);
+      req.on('close', () => streams.delete(res));
+      return;
+    }
+
+    await new Promise((r) => setTimeout(r, LATENCY_MS));
+    const body = req.method === 'GET' || req.method === 'DELETE' ? {} : await readJson(req);
+    if (body === null) return send(400, { message: 'The request body is not JSON.' });
+
+    if (req.method === 'POST' && url.pathname === '/api/fail-next') {
+      failNext = true;
+      return send(204);
+    }
+    if (req.method !== 'GET' && failNext) {
+      failNext = false;
+      return send(503, { message: 'The server refused this change, as you asked it to.' });
+    }
+
+    if (url.pathname === '/api/tasks') {
+      if (req.method === 'GET') return send(200, [...tasks.values()]);
+      if (req.method === 'POST') {
+        const title = typeof body.title === 'string' ? body.title.trim() : '';
+        if (!title) return send(422, { message: 'A task needs a title.', errors: { title: 'A task needs a title.' } });
+        const task = create(title);
+        broadcast('task_updated', { task });
+        return send(201, task);
+      }
+    }
+
+    const id = /^\/api\/tasks\/([^/]+)$/.exec(url.pathname)?.[1];
+    const task = id ? tasks.get(id) : undefined;
+    if (id && !task) return send(404, { message: 'There is no such task. Maybe someone deleted it.' });
+    if (task) {
+      if (req.method === 'GET') return send(200, task);
+      if (req.method === 'PATCH') {
+        if ('title' in body && (typeof body.title !== 'string' || !body.title.trim())) return send(422, { message: 'A task needs a title.', errors: { title: 'A task needs a title.' } });
+        const changed = { ...task };
+        if (typeof body.title === 'string') changed.title = body.title.trim();
+        if (typeof body.notes === 'string') changed.notes = body.notes;
+        if (typeof body.done === 'boolean') changed.done = body.done;
+        tasks.set(task.id, changed);
+        broadcast('task_updated', { task: changed });
+        return send(200, changed);
+      }
+      if (req.method === 'DELETE') {
+        tasks.delete(task.id);
+        broadcast('task_removed', { id: task.id });
+        return send(204);
+      }
+    }
+    send(404, { message: `No route for ${req.method} ${url.pathname}.` });
+  };
+
+  /** @param {import('vite').ViteDevServer | import('vite').PreviewServer} server */
+  const use = (server) => { server.middlewares.use(handle); };
+  return { name: 'demo-api', configureServer: use, configurePreviewServer: use };
+}
+
+/** The parsed JSON body ({} when empty), or null when it is not JSON. */
+async function readJson(req) {
+  let text = '';
+  for await (const chunk of req) text += chunk;
+  if (!text) return {};
+  try {
+    const value = JSON.parse(text);
+    return value && typeof value === 'object' ? value : null;
+  } catch {
+    return null;
+  }
+}

package/template/src/components/app-header.html

@@ -0,0 +1,16 @@
+<!-- The header of the app layout: a component, expanded at build time. It shows the layout's `armed`
+     state and emits `arm` when the next change is set to fail; the layout writes its state.
+     data-theme="dark": a dark band on a light page is one attribute. -->
+<template data-sn-component="{ armed: boolean }" data-sn-emits="{ arm: null }">
+  <header data-theme="dark" data-pad="sm">
+    <div data-layout="center" style="--tm-measure: 48rem">
+      <div data-layout="row" data-gap="sm" data-justify="between">
+        <a href="/" data-icon="circle-check"><strong>Tasks</strong></a>
+        <!-- a plain POST action; the next failed change resets `armed` (data-sn-on-sn-error on the layout's <body>) -->
+        <button data-variant="outline" data-size="sm" data-icon="triangle-alert"
+                data-sn-post="/api/fail-next" data-sn-then="emit('arm', null)"
+                data-sn-attr="{'aria-pressed': armed ? 'true' : 'false'}">Fail next change</button>
+      </div>
+    </div>
+  </header>
+</template>

package/template/src/components/task-chart.html

@@ -0,0 +1,14 @@
+<!-- A component with a script (task-chart.ts beside it): sinter renders the markup, the script draws
+     the ring on the canvas. The label is a binding, so it is in the first frame. -->
+<template data-sn-component="{ tasks: Task[]; show: string }" data-sn-emits="{ pick: 'done' | 'open' | 'all' }">
+  <figure class="chart" role="img" data-sn-attr="{ 'aria-label': tasks.filter((t) => t.done).length + ' of ' + tasks.length + ' tasks done' }">
+    <canvas data-sn-ref="canvas"></canvas>
+    <!-- resolves temper's color tokens for the canvas -->
+    <span data-sn-ref="probe" hidden></span>
+  </figure>
+</template>
+
+<style>
+  .chart { display: block; inline-size: 9rem; aspect-ratio: 1; margin: 0; cursor: pointer; }
+  canvas { display: block; }
+</style>

package/template/src/components/task-chart.ts

@@ -0,0 +1,80 @@
+// The script of <task-chart>: the browser work markup cannot do (drawing on a canvas). Its props,
+// event and refs are declared in task-chart.html, and typed through the base class generated from it
+// (src/sinter.components.d.ts). sinter runs it once per instance; it writes no node sinter renders.
+import { TaskChartComponent } from './task-chart.html';
+
+const TAU = 2 * Math.PI;
+
+export class TaskChart extends TaskChartComponent {
+  #resize = new ResizeObserver(() => this.draw());
+  #scheme = matchMedia('(prefers-color-scheme: dark)');
+  #redraw = () => this.draw();
+
+  connected() {
+    this.refs.canvas.addEventListener('click', (e) => this.click(e));
+    this.#resize.observe(this.root);
+    this.#scheme.addEventListener('change', this.#redraw);
+  }
+
+  propsChanged() { this.draw(); }
+
+  disconnected() {
+    this.#resize.disconnect();
+    this.#scheme.removeEventListener('change', this.#redraw);
+  }
+
+  counts() {
+    const done = this.props.tasks.filter((t) => t.done).length;
+    return { done, total: this.props.tasks.length };
+  }
+
+  color(token: string) {
+    this.refs.probe.style.color = `var(${token})`;
+    return getComputedStyle(this.refs.probe).color;
+  }
+
+  draw() {
+    const size = this.root.clientWidth;
+    if (!size) return;
+    const { done, total } = this.counts();
+    const dpr = devicePixelRatio || 1;
+    const c = this.refs.canvas;
+    c.width = c.height = Math.round(size * dpr);
+    c.style.width = c.style.height = `${size}px`;
+    const g = c.getContext('2d')!;
+    g.scale(dpr, dpr);
+
+    const r = size / 2, width = size * 0.14;
+    const arc = (from: number, to: number, token: string, dim: boolean) => {
+      g.globalAlpha = dim ? 0.3 : 1;
+      g.strokeStyle = this.color(token);
+      g.lineWidth = width;
+      g.beginPath();
+      g.arc(r, r, r - width / 2, from - TAU / 4, to - TAU / 4);
+      g.stroke();
+    };
+    if (!total) arc(0, TAU, '--tm-fill', false);
+    const split = total ? (done / total) * TAU : 0;
+    if (done) arc(0, split, '--tm-success', this.props.show === 'open');
+    if (done < total) arc(split, TAU, '--tm-accent', this.props.show === 'done');
+
+    g.globalAlpha = 1;
+    g.fillStyle = this.color('--tm-text');
+    g.font = `600 ${Math.round(size / 6)}px ${getComputedStyle(this.root).fontFamily}`;
+    g.textAlign = 'center';
+    g.textBaseline = 'middle';
+    g.fillText(`${done}/${total}`, r, r);
+  }
+
+  /** a click on a part picks its filter, or all when that part is already shown */
+  click(e: MouseEvent) {
+    const { done, total } = this.counts();
+    const r = this.root.clientWidth / 2, width = this.root.clientWidth * 0.14;
+    const x = e.offsetX - r, y = e.offsetY - r;
+    const distance = Math.hypot(x, y);
+    if (!total || distance < r - width || distance > r) return;
+    const angle = (Math.atan2(y, x) + TAU / 4 + TAU) % TAU;
+    const part = angle < (done / total) * TAU ? 'done' : 'open';
+    this.emit('pick', part === this.props.show ? 'all' : part);
+  }
+}

package/template/src/layouts/app-layout.html

@@ -0,0 +1,24 @@
+<!-- The document both pages share: the head, the header, the frame around the page's content and the
+     toast region. A page is this tag, with its title as a prop and its content inside.
+     `armed`: whether the next change is set to fail. The header sets it; the next failed action, on
+     any page, resets it (sn-error bubbles to <body>). -->
+<!doctype html>
+<html lang="en" data-sn-layout="{ title?: string }">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="color-scheme" content="light dark">
+  <title data-sn-text="title ? title + ' · Tasks' : 'Tasks'">Tasks</title>
+  <link rel="icon" href="data:,">
+  <link rel="stylesheet" href="../style.css">
+</head>
+<body data-sn-state="{ armed: false }" data-sn-on-sn-error="armed = false">
+  <app-header data-sn-prop="{ armed }" data-sn-on-arm="armed = true"></app-header>
+
+  <main data-layout="center" data-gap="lg" data-pad="lg" style="--tm-measure: 48rem">
+    <slot></slot>
+  </main>
+
+  <div data-toasts role="status"></div>
+</body>
+</html>

package/template/src/sinter.components.d.ts

@@ -0,0 +1,15 @@
+// Generated by sinter from src/components/*.html and src/layouts/*.html. Do not edit.
+/** every component of the app, by its tag */
+type ComponentName = "app-header" | "task-chart";
+/** every layout of the app, by its tag */
+type LayoutName = "app-layout";
+/** the props each layout declares (`data-sn-layout`) */
+interface LayoutProps {
+  "app-layout": { title?: string };
+}
+declare module '*/task-chart.html' {
+  type Task = import('./sinter.types').Task;
+  const Base: typeof import('@tiaforge-ui/sinter/components').Component;
+  /** the base of `src/components/task-chart.ts`: props, events, refs and state as `task-chart.html` declares them */
+  export class TaskChartComponent extends Base<{ tasks: Task[]; show: string }, { pick: 'done' | 'open' | 'all' }, { canvas: HTMLElementTagNameMap["canvas"]; probe: HTMLElementTagNameMap["span"] }, {}> {}
+}

package/template/src/sinter.config.ts

@@ -0,0 +1,9 @@
+// App configuration, loaded by every page before it mounts.
+import { configure } from '@tiaforge-ui/sinter';
+import { toast } from './toast';
+
+configure({
+  // A failed load or action that no data-sn-catch handled: an optimistic change has already
+  // been rolled back, so say why.
+  onError: (error) => toast(error.message, 'danger'),
+});

package/template/src/sinter.helpers.ts

@@ -0,0 +1,10 @@
+// Functions the pages' expressions can call. Keep them pure (the same arguments give the same
+// result), so they can be unit-tested without a page.
+import type { Task } from './sinter.types';
+
+/** The tasks the list shows: `show` is 'all', 'open' or 'done'; `q` matches the title. */
+export function visible(tasks: readonly Task[], q: string, show: string): Task[] {
+  const query = q.trim().toLowerCase();
+  return tasks.filter((t) =>
+    (show === 'all' || t.done === (show === 'done')) && t.title.toLowerCase().includes(query));
+}

package/template/src/sinter.types.ts

@@ -0,0 +1,22 @@
+// Types the pages name in `type="…"` on <sn-resource> and <sn-event>. `sinter check` (and every
+// `vite build`) checks each expression against them: `t.titel` fails the build.
+import type {} from '@tiaforge-ui/temper/sinter'; // temper's attribute values, for bound data-tone etc.
+
+export interface Task {
+  id: string;
+  title: string;
+  notes: string;
+  done: boolean;
+  /** ISO 8601 */
+  createdAt: string;
+}
+
+/** `task_updated` on /api/events */
+export interface TaskEvent {
+  task: Task;
+}
+
+/** `task_removed` on /api/events */
+export interface TaskRemoved {
+  id: string;
+}

package/template/src/style.css

@@ -0,0 +1,11 @@
+/* temper styles the HTML itself; this file only picks the modules and the brand. */
+@import '@tiaforge-ui/temper/core.css';
+@import '@tiaforge-ui/temper/feedback.css'; /* toasts */
+@import '@tiaforge-ui/temper/icons.css';
+
+/* Rebrand with two numbers: every color derives from them, in light and dark mode. Try 20 or 200. */
+:root {
+  --tm-hue: 290;
+  --tm-chroma: 0.16;
+}
+

package/template/src/toast.ts

@@ -0,0 +1,15 @@
+// A temper toast: appended to the page's [data-toasts] region, faded out after a few seconds.
+export function toast(text: string, tone?: 'danger' | 'success') {
+  const region = document.querySelector('[data-toasts]');
+  if (!region) return;
+  const t = document.createElement('div');
+  t.dataset.toast = '';
+  if (tone) t.dataset.tone = tone;
+  if (tone === 'danger') t.role = 'alert';
+  t.textContent = text;
+  region.append(t);
+  setTimeout(() => {
+    t.hidden = true;
+    setTimeout(() => t.remove(), 300);
+  }, 5000);
+}

package/template/task.html

@@ -0,0 +1,47 @@
+<!-- /task/?id=…: one task. Its data was requested while the pointer rested on the link,
+     so it shows at once. The tab's title is the task's, once it is there. -->
+<app-layout data-sn-prop="{ title: task ? task.title : 'Task' }">
+
+  <sn-resource name="task" src="/api/tasks/{$url.id}" type="Task"></sn-resource>
+
+  <!-- Only events about this task: an edit in another tab shows here, a delete empties the page. -->
+  <sn-sync src="/api/events">
+    <sn-event name="task_updated" resource="task" op="upsert" item="task" when="task.id === $url.id" type="TaskEvent"></sn-event>
+    <sn-event name="task_removed" resource="task" op="remove" when="id === $url.id" type="TaskRemoved"></sn-event>
+  </sn-sync>
+
+  <a href="/" data-icon="arrow-left" data-self="start">All tasks</a>
+  <!-- The same transition name as the link on the list: the title morphs into this heading. -->
+  <h1 data-sn-transition="'task-' + $url.id" data-sn-text="task ? task.title : ''"></h1>
+
+  <template data-sn-if="task">
+    <article data-layout="stack" data-gap="md">
+      <div data-layout="row" data-gap="sm" data-justify="between">
+        <span data-badge data-sn-attr="{ 'data-tone': task.done ? 'success' : 'accent' }"
+              data-sn-text="task.done ? 'Done' : 'Open'"></span>
+        <small data-muted data-sn-text="'Created ' + datetime(task.createdAt)"></small>
+      </div>
+
+      <!-- Edit a copy; saving sends it, and the response updates `task`. -->
+      <form data-layout="stack" data-gap="md" data-sn-state="{ draft: { title: task.title, notes: task.notes } }"
+            data-sn-patch="/api/tasks/{task.id}" data-sn-body="draft">
+        <label>Title <input name="title" data-sn-model="draft.title" required></label>
+        <label>Notes <textarea rows="5" data-sn-model="draft.notes"></textarea></label>
+        <footer>
+          <button type="button" data-variant="secondary"
+                  data-sn-patch="/api/tasks/{task.id}" data-sn-body="{ done: !task.done }"
+                  data-sn-optimistic="patch(task, { done: !task.done })"
+                  data-sn-text="task.done ? 'Reopen' : 'Mark done'"></button>
+          <button>Save</button>
+        </footer>
+      </form>
+    </article>
+  </template>
+
+  <template data-sn-if="!task && ($meta.task.error || $meta.task.loadedAt)">
+    <div data-callout data-tone="warning" role="status">
+      <strong>This task is gone</strong>
+      It was deleted, or the link is wrong. <a href="/">Back to all tasks</a>
+    </div>
+  </template>
+</app-layout>

package/template/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}

package/template/vite.config.js

@@ -0,0 +1,26 @@
+import { resolve } from 'node:path';
+import { defineConfig } from 'vite';
+import sinter from '@tiaforge-ui/sinter/vite';
+import temper from '@tiaforge-ui/temper/vite';
+import api from './server/api.js';
+
+export default defineConfig({
+  appType: 'mpa',
+  plugins: [
+    // Compiles the data-sn-* pages; typecheck: every expression is checked against src/sinter.types.ts in `vite build`.
+    sinter({ typecheck: true }),
+    // temper check on the markup: a wrong data-* value fails the build, the dev server warns.
+    temper(),
+    // The demo backend (server/api.js). Replace it with your API, e.g. server: { proxy: { '/api': 'http://localhost:3000' } }.
+    api(),
+  ],
+  build: {
+    // One entry per page: a sinter app is a multi-page app.
+    rollupOptions: {
+      input: {
+        index: resolve(import.meta.dirname, 'index.html'),
+        task: resolve(import.meta.dirname, 'task.html'),
+      },
+    },
+  },
+});