@tiaforge-ui/sinter 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tia Heinrich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+# 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.
+**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`.
+
+```html
+<sn-resource name="contacts" src="/api/contacts" items="contacts" key="id" order="name"></sn-resource>
+
+<sn-sync src="/api/events">
+  <sn-event name="contact_updated" resource="contacts" op="upsert" item="contact"></sn-event>
+  <sn-event name="contact_removed" resource="contacts" op="remove"></sn-event>
+</sn-sync>
+
+<section data-sn-state="{ q: '' }">
+  <input type="search" data-sn-model="q">
+  <ul>
+    <template data-sn-for="c in contacts.filter(c => c.name.includes(q))">
+      <li>
+        <span data-sn-text="c.name"></span>
+        <button data-sn-delete="/api/contacts/{c.id}" data-sn-optimistic="remove('contacts', c)">Delete</button>
+      </li>
+    </template>
+  </ul>
+</section>
+```
+
+That page loads the contacts, keeps them sorted, applies updates other users make as they arrive,
+filters as you type, and removes a contact at once when you click Delete, putting it back if the
+server refuses.
+
+## Why sinter
+
+- **The server-state plumbing is gone.** You don't write loading flags, stale-response guards,
+  refetch on reconnect, list upserts from SSE or WebSocket events, or rollback of failed updates.
+  They are attributes.
+- **Optimistic updates that stay correct**, also when requests overlap or a server event arrives
+  while a request is in flight.
+- **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.
+- **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.
+  This makes the pages easy to read and easy for an LLM to write correctly (`llms.txt` ships with the
+  package).
+
+## Compared with
+
+**Angular, React, Vue.** If your app mostly shows and edits API data, a SPA framework makes you build
+components, services, a store and a router to get there. sinter keeps the page as HTML and moves the
+data handling into attributes. The tradeoff is that sinter apps are multi-page: each navigation is a
+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.
+
+**Alpine, petite-vue.** These also render JSON with client-side templates, but they leave fetching,
+caching, live updates and rollback to you.
+
+Measurements and sources: [`docs/realworld-comparison.md`](docs/realworld-comparison.md).
+
+## When not to use sinter
+
+- You want a SPA: client-side routing, transitions, a component system.
+- The UI is mostly client-side interaction (editors, canvas, drag and drop). sinter leaves that to
+  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.
+
+## Setup
+
+```sh
+npm install @tiaforge-ui/sinter
+```
+
+```js
+// vite.config.js
+import sinter from '@tiaforge-ui/sinter/vite';
+export default { plugins: [sinter()] };
+```
+
+Then write `data-sn-*` attributes in your HTML pages. Optional:
+
+- `src/sinter.config.js`: `configure({ request, sessionProbe, onError, locale, origins, urlSchemes, transport })`. Auth headers, error handling, WebSocket (`@tiaforge-ui/sinter/ws`) or SignalR transports.
+- `src/sinter.helpers.js`: functions and namespaces your expressions can call (`export * as m from './paraglide/messages.js'`).
+- `src/sinter.types.ts`: types named by `<sn-resource type="Contact[]">`. Or use `sinter({ openapi: 'openapi.yml' })` to type resources from your API spec.
+- `npx sinter check` type-checks every expression. `sinter({ typecheck: true })` runs it in `vite build`.
+- `<sn-resource … cache>` shows the last page load's data at once, then revalidates. Call `clearPersisted()` on logout.
+- Serve `<sn-sync>` streams over HTTP/2. Over HTTP/1.1, each tab's stream takes one of six connections per origin.
+- Editors: `npx sinter lsp --stdio`. There is a VS Code extension in [`editors/vscode`](editors/vscode). For Neovim, Helix and Emacs, see [`docs/editors.md`](docs/editors.md).
+
+## Docs
+
+- [`llms.txt`](llms.txt): attribute reference, scope rules and recipes (each with tests).
+- [`docs/spec.md`](docs/spec.md): the v0.1 specification.
+- [`docs/diagnostics.md`](docs/diagnostics.md): every `SN` error code and how to fix it.
+- [`examples/realworld`](examples/realworld): a complete multi-page app.
+- [`docs/progress.md`](docs/progress.md): implementation status and decisions.
+
+## Packages
+
+| Import | Contents |
+| --- | --- |
+| `@tiaforge-ui/sinter` | `mount`, store, renderer, actions, request layer, instance API, `configure` |
+| `@tiaforge-ui/sinter/sse` | `<sn-sync>`, SSE transport |
+| `@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/persist` | `data-sn-persist` |
+| `@tiaforge-ui/sinter/compiler` | `compile()` |
+| `@tiaforge-ui/sinter/vite` | Vite plugin |
+| `@tiaforge-ui/sinter/check` | `check()` (used by `sinter check`), `checkPage()` for tests |
+| `@tiaforge-ui/sinter/testing` | `render`, `mockRequests`, `mockStream` |
+
+## Development
+
+```sh
+npm test          # vitest (happy-dom)
+npm run typecheck
+npm run build     # dist/
+npm run size      # size budget per module
+npm run docs      # regenerate llms.txt, html-custom-data.json (also the VS Code extension's) and docs/diagnostics.md
+```
+
+License: MIT. Contributions are accepted under the Developer Certificate of Origin
+(`Signed-off-by` in each commit, `git commit -s`); no CLA.

package/dist/cache.d.ts

@@ -0,0 +1,5 @@
+import type { Feature } from './runtime/app.js';
+/** entries larger than this (serialized) are not written */
+export declare const MAX_ENTRY: number;
+declare const cache: Feature;
+export default cache;

package/dist/cache.js

@@ -0,0 +1,95 @@
+import { CACHE_PREFIX } from './runtime/config.js';
+/** entries larger than this (serialized) are not written */
+export const MAX_ENTRY = 256 * 1024;
+const cache = {
+    name: 'cache',
+    install(app) {
+        const tracked = new Map();
+        const keyOf = (def, url) => CACHE_PREFIX + JSON.stringify([url, def.items, def.total]);
+        /** drops the older half of the cache entries; false when there was nothing to drop */
+        const evict = (s, keep) => {
+            const entries = [];
+            for (let i = 0; i < s.length; i++) {
+                const k = s.key(i);
+                if (!k || !k.startsWith(CACHE_PREFIX) || k == keep)
+                    continue;
+                let t = 0;
+                try {
+                    t = JSON.parse(s.getItem(k)).t;
+                }
+                catch { /* unreadable: oldest */ }
+                entries.push([k, t]);
+            }
+            if (!entries.length)
+                return false;
+            entries.sort((a, b) => a[1] - b[1]);
+            for (const [k] of entries.slice(0, Math.ceil(entries.length / 2)))
+                s.removeItem(k);
+            return true;
+        };
+        const write = (def, url, items, total) => {
+            const s = app.env.session();
+            if (!s)
+                return;
+            let text;
+            try {
+                text = JSON.stringify({ t: app.env.now(), items, total });
+            }
+            catch {
+                return;
+            }
+            if (text.length > MAX_ENTRY)
+                return app.warn(19, def.name, Math.round(text.length / 1024));
+            const key = keyOf(def, url);
+            for (let tries = 0; tries < 2; tries++) {
+                try {
+                    s.setItem(key, text);
+                    return;
+                }
+                catch {
+                    if (!evict(s, key))
+                        return;
+                }
+            }
+        };
+        app.ext.cache = {
+            read(def, url) {
+                try {
+                    const v = app.env.session()?.getItem(keyOf(def, url));
+                    if (!v)
+                        return null;
+                    const e = JSON.parse(v);
+                    return def.cache && app.env.now() - e.t > def.cache ? null : e;
+                }
+                catch {
+                    return null;
+                }
+            },
+            loaded(def, r, url, items, total, appended) {
+                let t = tracked.get(def.name);
+                if (!t) {
+                    const entry = (t = { def, r, url, dirty: false, appended });
+                    // confirmed changes after the load (server events, action results); layers never fire this
+                    r.subscribe(() => { entry.dirty = true; });
+                    tracked.set(def.name, t);
+                }
+                t.url = url;
+                t.appended = appended;
+                // `append` caches only its first page: later pages would be shown as if they were it
+                if (!appended)
+                    write(def, url, items, total);
+                t.dirty = false;
+            },
+        };
+        app.addCleanup(app.env.listen('pagehide', () => {
+            for (const t of tracked.values()) {
+                if (!t.dirty || t.appended || t.def.paginate?.mode == 'append')
+                    continue;
+                const b = t.r.base();
+                write(t.def, t.url, b.items, b.total);
+                t.dirty = false;
+            }
+        }));
+    },
+};
+export default cache;

package/dist/check/index.d.ts

@@ -0,0 +1,82 @@
+import type { CheckUnit } from '../compiler/check-unit.js';
+import type { HelperManifest } from '../compiler/compile.js';
+import type { Diagnostic } from '../compiler/diagnostics.js';
+import { type ProjectOptions } from '../project.js';
+import type { OpenApiSpec } from '../compiler/openapi.js';
+import { type Region, type Shadow } from './shadow.js';
+export interface CheckOptions {
+    root: string;
+    /** from `compile(…, { check: true })`, one per page */
+    units: CheckUnit[];
+    helpers: HelperManifest;
+    /** absolute path of the types module, or null */
+    types: string | null;
+    /** the specs the pages were compiled with (`compile(…, { openapi })`) */
+    openapi?: OpenApiSpec[];
+    /** where the shadow files go (default `<root>/.sinter/check`) */
+    outDir?: string;
+    /** path of TypeScript's `tsc` script (default: resolved from the project) */
+    tsc?: string;
+}
+export interface CheckResult {
+    diagnostics: Diagnostic[];
+    resources: number;
+    /** resources with `type` or an OpenAPI match */
+    typed: number;
+    /** of those, typed from OpenAPI */
+    openapi: number;
+}
+/** What every shadow file of a project refers to, written once per run. */
+export interface Support {
+    outDir: string;
+    /** absolute path of `sinter.d.ts` */
+    declarations: string;
+    types: {
+        file: string;
+        names: string[];
+    } | null;
+    /** generated declarations per OpenAPI spec, by spec index */
+    openapi: string[];
+}
+/** Writes `sinter.d.ts` and the spec declarations into `outDir`. */
+export declare function writeSupport(o: {
+    root: string;
+    outDir: string;
+    types: string | null;
+    openapi?: OpenApiSpec[];
+}): Support;
+/** The compiler options shadow files are checked with. */
+export declare const COMPILER_OPTIONS: {
+    allowJs: boolean;
+    checkJs: boolean;
+    strict: boolean;
+    strictNullChecks: boolean;
+    noImplicitAny: boolean;
+    noEmit: boolean;
+    skipLibCheck: boolean;
+    target: string;
+    module: string;
+    moduleResolution: string;
+    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;
+/** 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;
+/**
+ * Type-checks one page in a temporary project, for tests: `files` are written next to it
+ * (`{ 'src/sinter.types.ts': … }`), options name them as in the Vite config. Returns the
+ * compiler's and TypeScript's diagnostics; TypeScript is resolved from the current directory.
+ */
+export declare function checkPage(html: string, o?: ProjectOptions & {
+    files?: Record<string, string>;
+}): Diagnostic[];
+/** TypeScript's `tsc` script, resolved from the project like its own imports. */
+export declare function findTsc(root: string): string;
+/** Names a types module exports: TS declarations, `export { … }` lists and JSDoc typedefs. */
+export declare function typeExports(source: string): string[];
+/** Shortens absolute module paths in TypeScript's messages to project-relative ones. */
+export declare function clean(message: string, root: string): string;

package/dist/check/index.js

@@ -0,0 +1,156 @@
+// `sinter check`: type-checks every expression of the compiled pages with the
+// project's own TypeScript (`tsc` on generated, checked JavaScript files).
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { dirname, join, relative, resolve } from 'node:path';
+import { compile } from '../compiler/index.js';
+import { project } from '../project.js';
+import { specDeclarations } from './openapi-types.js';
+import { DECLARATIONS, mapPosition, shadow } from './shadow.js';
+/** Writes `sinter.d.ts` and the spec declarations into `outDir`. */
+export function writeSupport(o) {
+    const declarations = join(o.outDir, 'sinter.d.ts');
+    mkdirSync(o.outDir, { recursive: true });
+    writeIfChanged(declarations, DECLARATIONS);
+    const openapi = (o.openapi ?? []).map((s, i) => {
+        const file = join(o.outDir, `openapi-${i}.d.ts`);
+        writeIfChanged(file, specDeclarations(s.doc, relative(o.root, s.file).split('\\').join('/')));
+        return file;
+    });
+    const types = o.types ? { file: o.types, names: typeExports(readFileSync(o.types, 'utf8')) } : null;
+    return { outDir: o.outDir, declarations, types, openapi };
+}
+/** 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: [],
+};
+/** 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 });
+}
+/** 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) {
+    const text = `${clean(message, root)} (${code})`;
+    const loc = mapPosition(regions, line, col);
+    return loc
+        ? { severity: 'error', code: 'SN208', message: text + (loc.chain.length ? ` (included from ${loc.chain.join(' ← ')})` : ''), file: loc.file, line: loc.line, col: loc.col }
+        : { severity: 'error', code: 'SN208', message: `in code sinter generated (please report): ${text}`, file: unit.file, line: 1, col: 1 };
+}
+function writeIfChanged(file, text) {
+    try {
+        if (readFileSync(file, 'utf8') === text)
+            return;
+    }
+    catch { /* missing */ }
+    writeFileSync(file, text);
+}
+export function check(o) {
+    const outDir = o.outDir ?? join(o.root, '.sinter', 'check');
+    const support = writeSupport({ root: o.root, outDir, types: o.types, openapi: o.openapi });
+    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);
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, s.text);
+        shadows.set(resolve(file), { unit, regions: s.regions, brokenFrom: s.brokenFrom });
+    }
+    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('/'))],
+    }, null, 2) + '\n');
+    const tsc = o.tsc ?? findTsc(o.root);
+    const run = spawnSync(process.execPath, [tsc, '-p', tsconfig, '--pretty', 'false'], { encoding: 'utf8', cwd: outDir });
+    if (run.error)
+        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 viaOpenapi = o.units.reduce((n, u) => n + u.resources.filter((r) => !r.type && r.openapi).length, 0);
+    return { diagnostics, resources, typed, openapi: viaOpenapi };
+}
+/**
+ * Type-checks one page in a temporary project, for tests: `files` are written next to it
+ * (`{ 'src/sinter.types.ts': … }`), options name them as in the Vite config. Returns the
+ * compiler's and TypeScript's diagnostics; TypeScript is resolved from the current directory.
+ */
+export function checkPage(html, o = {}) {
+    const root = mkdtempSync(join(tmpdir(), 'sinter-check-page-'));
+    try {
+        for (const [rel, text] of Object.entries(o.files ?? {})) {
+            mkdirSync(dirname(join(root, rel)), { recursive: true });
+            writeFileSync(join(root, rel), text);
+        }
+        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()) });
+        return [...p.diagnostics, ...out.diagnostics, ...r.diagnostics].map((d) => ({ ...d, file: relative(root, d.file) }));
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+/** TypeScript's `tsc` script, resolved from the project like its own imports. */
+export function findTsc(root) {
+    const req = createRequire(join(root, 'package.json'));
+    let pkg;
+    try {
+        pkg = req.resolve('typescript/package.json');
+    }
+    catch {
+        throw new Error('sinter check needs TypeScript: npm install -D typescript');
+    }
+    const bin = JSON.parse(readFileSync(pkg, 'utf8')).bin?.tsc ?? 'bin/tsc';
+    return join(dirname(pkg), bin);
+}
+/** Names a types module exports: TS declarations, `export { … }` lists and JSDoc typedefs. */
+export function typeExports(source) {
+    const names = new Set();
+    for (const m of source.matchAll(/export\s+(?:declare\s+)?(?:abstract\s+)?(?:interface|type|class|enum)\s+([A-Za-z_$][\w$]*)/g))
+        names.add(m[1]);
+    for (const m of source.matchAll(/export\s+(?:type\s+)?\{([^}]*)\}/g)) {
+        for (const part of m[1].split(',')) {
+            const name = part.trim().replace(/^type\s+/, '').split(/\s+as\s+/).pop().trim();
+            if (/^[A-Za-z_$][\w$]*$/.test(name) && name !== 'default')
+                names.add(name);
+        }
+    }
+    for (const m of source.matchAll(/@typedef\s+(?:\{.*?\}\s+)?([A-Za-z_$][\w$]*)/g))
+        names.add(m[1]);
+    return [...names].sort();
+}
+/** `file(line,col): error TS1234: message`, with indented continuation lines. */
+function parseTsc(stdout, outDir, root, shadows) {
+    const out = [];
+    let last = null;
+    for (const raw of stdout.split(/\r?\n/)) {
+        const m = /^(.+?)\((\d+),(\d+)\): error (TS\d+): (.*)$/.exec(raw);
+        if (!m) {
+            if (last && /^\s+\S/.test(raw))
+                last.message += '\n  ' + raw.trim();
+            continue;
+        }
+        last = null;
+        const s = shadows.get(resolve(outDir, m[1]));
+        // errors in the app's own modules are its own tsc's business; broken expressions are the compiler's
+        if (!s || (s.brokenFrom !== null && Number(m[2]) >= s.brokenFrom))
+            continue;
+        const d = typeDiagnostic(s.unit, s.regions, Number(m[2]), Number(m[3]), m[4], m[5], root);
+        out.push(d);
+        last = d;
+    }
+    return out;
+}
+/** Shortens absolute module paths in TypeScript's messages to project-relative ones. */
+export function clean(message, root) {
+    return message.replace(/import\("([^"]+)"\)/g, (_, p) => `import("${p.startsWith(root) ? relative(root, p).split('\\').join('/') : p}")`);
+}

package/dist/check/openapi-types.d.ts

@@ -0,0 +1,6 @@
+/** A schema name as a TypeScript identifier. */
+export declare function typeName(name: string): string;
+/** TypeScript for a schema; `ref` turns a named schema into a type reference. */
+export declare function schemaToTs(schema: unknown, ref: (name: string) => string, depth?: number): string;
+/** Declarations for every named schema of a spec: interfaces for objects, aliases otherwise. */
+export declare function specDeclarations(doc: unknown, file: string): string;

package/dist/check/openapi-types.js

@@ -0,0 +1,84 @@
+// JSON Schema (OpenAPI 3.0 and 3.1) to TypeScript, for `sinter check`. Named
+// schemas (`components.schemas`) become named declarations, so messages say
+// `type 'Article'`. Precision where checking expressions needs it (properties,
+// arrays, unions, enums); `any` where it does not (formats, patterns, limits).
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const SCHEMA_REF = '#/components/schemas/';
+/** A schema name as a TypeScript identifier. */
+export function typeName(name) {
+    const id = name.replace(/[^\w$]/g, '_');
+    return /^\d/.test(id) ? '_' + id : id;
+}
+const key = (k) => (/^[A-Za-z_$][\w$]*$/.test(k) ? k : JSON.stringify(k));
+/** TypeScript for a schema; `ref` turns a named schema into a type reference. */
+export function schemaToTs(schema, ref, depth = 0) {
+    if (schema === true || schema === undefined)
+        return 'any';
+    if (schema === false)
+        return 'never';
+    if (!isObj(schema) || depth > 24)
+        return 'any';
+    const s = schema;
+    if (typeof s.$ref === 'string') {
+        return s.$ref.startsWith(SCHEMA_REF) ? ref(s.$ref.slice(SCHEMA_REF.length).replace(/~1/g, '/').replace(/~0/g, '~')) : 'any';
+    }
+    const sub = (v) => schemaToTs(v, ref, depth + 1);
+    let t;
+    if ('const' in s)
+        t = JSON.stringify(s.const);
+    else if (Array.isArray(s.enum))
+        t = s.enum.map((v) => JSON.stringify(v)).join(' | ') || 'never';
+    else if (Array.isArray(s.allOf))
+        t = s.allOf.map((x) => paren(sub(x))).join(' & ');
+    else if (Array.isArray(s.oneOf) || Array.isArray(s.anyOf))
+        t = (s.oneOf ?? s.anyOf).map(sub).join(' | ');
+    else {
+        const types = Array.isArray(s.type) ? s.type.map(String) : typeof s.type === 'string' ? [s.type] : [];
+        if (!types.length && (isObj(s.properties) || 'additionalProperties' in s))
+            types.push('object');
+        if (!types.length && 'items' in s)
+            types.push('array');
+        t = types.length ? types.map((ty) => single(ty, s, sub)).join(' | ') : 'any';
+    }
+    if (s.nullable === true && t !== 'any')
+        t = `${paren(t)} | null`;
+    return t;
+}
+function single(type, s, sub) {
+    switch (type) {
+        case 'string': return 'string';
+        case 'number':
+        case 'integer': return 'number';
+        case 'boolean': return 'boolean';
+        case 'null': return 'null';
+        case 'array': return `${paren(sub(s.items))}[]`;
+        case 'object': {
+            const props = isObj(s.properties) ? s.properties : {};
+            const required = new Set(Array.isArray(s.required) ? s.required.map(String) : []);
+            const parts = Object.entries(props).map(([k, v]) => `${key(k)}${required.has(k) ? '' : '?'}: ${sub(v)}`);
+            const extra = s.additionalProperties;
+            if (extra === true || isObj(extra))
+                parts.push(`[key: string]: ${extra === true ? 'any' : sub(extra)}`);
+            else if (!parts.length && extra === undefined)
+                parts.push('[key: string]: any');
+            return `{ ${parts.join('; ')} }`;
+        }
+        default: return 'any';
+    }
+}
+const paren = (t) => (/[|&]/.test(t) && !/^\{.*\}$/.test(t) ? `(${t})` : t);
+/** Declarations for every named schema of a spec: interfaces for objects, aliases otherwise. */
+export function specDeclarations(doc, file) {
+    const out = [`// Generated by \`sinter check\` from ${file}. Do not edit.`, 'export {};'];
+    const schemas = isObj(doc) && isObj(doc.components) && isObj(doc.components.schemas) ? doc.components.schemas : {};
+    const ref = (n) => typeName(n);
+    for (const [name, schema] of Object.entries(schemas)) {
+        const t = schemaToTs(schema, ref);
+        // a plain object type becomes an interface, which keeps its name in messages
+        if (/^\{ .* \}$/s.test(t) && !/\} [|&] \{/.test(t))
+            out.push(`export interface ${typeName(name)} ${t}`);
+        else
+            out.push(`export type ${typeName(name)} = ${t};`);
+    }
+    return out.join('\n') + '\n';
+}

package/dist/check/shadow.d.ts

@@ -0,0 +1,47 @@
+import type { CheckLoc, CheckUnit } from '../compiler/check-unit.js';
+import type { HelperManifest } from '../compiler/compile.js';
+export interface ShadowOptions {
+    unit: CheckUnit;
+    /** absolute path the shadow file is written to */
+    file: string;
+    /** project root; root-relative module specifiers (`/src/x.js`) resolve against it */
+    root: string;
+    /** absolute path of the declarations sinter writes next to the shadow files (`sinter.d.ts`) */
+    declarations: string;
+    /** the types module and the names it exports */
+    types: {
+        file: string;
+        names: string[];
+    } | null;
+    helpers: HelperManifest;
+    /** absolute paths of the declarations generated per OpenAPI spec, by spec index */
+    openapi?: string[];
+}
+/** A run of shadow lines that came from the HTML. */
+export interface Region {
+    /** first shadow line, 1-based */
+    start: number;
+    lines: number;
+    loc: CheckLoc;
+    /** every line maps to `loc` itself (a `type` attribute in a JSDoc comment) */
+    fixed?: boolean;
+}
+export interface Shadow {
+    text: string;
+    regions: Region[];
+    /** first line of the broken expressions (written last); nothing from there on is reported */
+    brokenFrom: number | null;
+}
+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";
+/**
+ * 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.
+ */
+export declare function shadowPosition(regions: Region[], lines: string[], file: string, line: number, col: number): {
+    line: number;
+    col: number;
+} | null;