tosijs-ui 1.9.8 → 1.11.0

package/CHANGELOG.md

@@ -1,5 +1,658 @@
 # Changelog
 
+## 1.11.0
+
+**Schema-driven editing.** Three new pieces that compose: `<tosi-schema-form>` renders a form
+from a JSON Schema, `<tosi-crud>` puts search, list and edit over a store you supply, and
+`hashState` keeps filter and selection in the URL so a filtered list with a record open is a
+link you can send.
+
+**The dev bridge is usable on a headset.** The edit-link token is now **seven characters** you
+can read off one screen and type on another, instead of twenty-two of mixed-case base64url.
+That change came from watching the feature fail in practice: people gave up and typed LAN IP
+addresses instead, and a credential too painful to use is not protecting anything.
+
+> **If you are on 1.10.0, this is a three-version jump.** 1.10.1 and 1.10.2 were tagged in git
+> but **never published to npm** — `latest` has been 1.10.0 throughout. Nothing is lost: every
+> change in those releases is in this one, and their notes are below where they always were.
+> They are simply not installable, so `npm i tosijs-ui@1.10.2` will fail.
+
+### Breaking
+
+- **`tosijs-schema` floor is `^1.8.0`** (optional peer). 1.8.0 enforces `oneOf`,
+  `exclusiveMinimum` and `exclusiveMaximum` — which is what
+  [tosijs-schema#8](https://github.com/tonioloewald/tosijs-schema/issues/8), filed from this
+  work, asked for — and exports `unenforcedKeywords`. The form now asks the **registered
+  validator** which keywords it does not check, falling back to a local list only when a
+  validator cannot answer. Against 1.7.0 a `oneOf` field carried "oneOf is not validated";
+  against 1.8.0 it carries nothing and the value is genuinely checked. Verified with
+  `bun bin/verify-schema-dep.ts --version=1.8.0` (17/17).
+
+- **Validation is supplied, not imported.** `setSchemaValidator({ validate, inferSchema, unenforcedKeywords })` —
+  one line, anywhere, before or after render. The CDN `<script>` build and any `tosijs-ui/site`
+  doc site register it themselves, so only an ESM consumer writes it.
+
+  The reason is worth knowing, because it is not a preference. A bare `import('tosijs-schema')`
+  in shipped code is either **resolved** by your bundler — which fails the build for anyone who
+  did not install it, including people using only `<tosi-table>` — or left **external**, which
+  cannot resolve in a browser and kills validation for everyone. Both were measured. There is
+  no third option, so the component asks for two functions instead of a package. The upside is
+  that they are just functions: an Ajv wrapper, a house validator or a test stub all work.
+
+- **`tjs-lang` moves to `^0.13.1`** (from `^0.12.0`), and `TJS_VERSION` in `code-transform.ts`
+  moves in lockstep. 0.12.0 is **deprecated on npm**, and the deprecation names this release's
+  own combination — _"tosijs-schema >=1.5.0 breaks the battery atoms' output validation in these
+  versions. Upgrade to 0.13.1."_ Worse for adopters, `^0.12.0` does not admit 0.13.x, so anyone
+  on current tjs-lang got a hard `ERESOLVE`. The tjs CodeMirror extension is still bundled
+  rather than externalized — the constraint that silently no-ops highlighting if it breaks.
+
+- **The edit-link token is 7 Crockford base32 characters**, and `linkTtlMinutes` defaults to
+  **5** (was 15). A link minted by an older server is not redeemable by a newer one; both are
+  in-memory and per-process, so this only matters across a restart mid-session.
+
+### New
+
+**`<tosi-schema-form>`** — a form from a JSON Schema. `value` is the state and `change` fires on
+edit, the same contract as every other component here.
+
+- Scalars, enums, `const`, and `format`-driven input types. Anything it cannot render is a
+  labelled placeholder saying so, never a silently omitted field — a field that vanishes is
+  indistinguishable from a schema that never mentioned it, which is how an editor loses data.
+- **Nested objects** become `<details>` sections to any depth, with fully-qualified leaf paths
+  (`address.geo.lat`), so value sync and error keying work at depth with no special cases.
+  `required` is scoped to the object that declares it, which is what JSON Schema means: a
+  required `city` inside an optional `address` says _if you give an address, it needs a city_.
+- **Arrays** with add, remove and reorder. Each element expands against `items`; scalar items
+  are a single field at the index (`tags.0`), object items expand to their properties
+  (`items.0.sku`).
+- **Unions** (`anyOf`/`oneOf`), each rendered as what it actually is: `[X, null]` is just an
+  optional X, an all-`const` union is a `<select>`, an all-object union is a variant picker plus
+  the matching branch's fields. Anything else names the shapes it saw ("a union of string |
+  object"). Discriminators are derived from the property every branch pins to a different
+  `const`, or declared as `x-discriminator`.
+- **Format plugins** — `registerFieldPlugin(format, plugin)` claims a schema `format`. The
+  plugin owns the control; the form keeps the label and the error slot. Plugins are dispatched
+  first and for every node kind, so `unsupported` is the fallback, not the ceiling. Register
+  whenever you like: styles are injected on registration and live forms rebuild.
+- **Validation is optional.** Without a validator the form still renders and edits and simply
+  reports no errors, which is a smaller failure than refusing to render.
+- **No schema? It infers one** from the value, via `inferSchema`. Read it back from `.schema`,
+  edit it, set it again — that round trip is the point.
+
+**`<tosi-crud>`** — search, list, edit over a `CrudStore` adapter (`list` / `save?` / `delete?`,
+promise-returning). There is **no transport in the component**: REST, a DocStore, IndexedDB, an
+array in a closure and a mock all satisfy the same three methods. Omit `save` and the form is
+read-only; omit `delete` and its button is not shown. `columnsFromSchema()` lets one description
+of the shape drive both surfaces — strictly better than the table's own inference, which reads
+`Object.keys(array[0])` and silently loses the column for a property the first row lacks. The
+search term and selected id live in the URL hash, so typing **replaces** the history entry while
+selecting a record **pushes** one: back leaves the record rather than un-typing your search a
+letter at a time.
+
+**`hashState({ namespace, mode })`** — key-value state in the page hash. Every key is namespaced
+in the URL and bare in the API, and a write never touches a key it did not put there, so two
+instances (or a hashState beside a hash router) share one URL without deleting each other. That
+is the failure that made `createDocBrowser` grow a `'memory'` routing mode, so `mode: 'memory'`
+is here from the start.
+
+**Editable `<tosi-table>`** — set `editable` and cells become inputs, per-column overridable
+either way; a column with its own `dataCell` is never made editable. A `schema` drives the
+control type and validates edits, using the same model the form uses. A `change` event carries
+`{ item, field, oldValue, newValue, error }` and commits on `change`, not `input`: an event per
+keystroke would make `3` a legitimate intermediate state of typing `35`.
+
+**Localization** — `localize(pattern, values)` fills `{name}` placeholders **after** translating,
+so the key is the whole sentence (`'Add {item}'`, never `'Add ' + item`). A concatenated
+sentence is untranslatable in principle: the translator sees a dangling fragment and cannot move
+the placeholder to where their language puts it. An unknown placeholder stays visible as
+`{name}` rather than blanked. `<tosi-schema-form>` localizes its own chrome and rebuilds on
+locale change.
+
+**The dev bridge.** `mintLinkToken()` / `normalizeLinkToken()`: Crockford base32 excludes `I`,
+`L`, `O` and `U`, so the `0`/`O` and `1`/`l` mistypes that hurt most on a floating keyboard are
+impossible rather than merely unlikely. `randomInt`, not `randomBytes % 32`. Redemption folds
+case, accepts `I`/`L` as `1` and `O` as `0`, and ignores hyphens — normalising on **redemption**
+rather than only when minting, because case-insensitivity that exists in the alphabet but not in
+the comparison is a claim rather than a behaviour, and the failure it produces is a correct human
+being told they typed it wrong. `--link` prints the code on its own line as well as in the URL.
+
+The TTL is 5 minutes because the link is a **bearer token** for its lifetime — which the
+`dev-auth` header comment now says plainly instead of describing the single-use rule it stopped
+following in 1.10.0. About 35 bits is ample for what this actually is: an online-only guess
+against a `Map` lookup, for a token redeemed seconds after minting, that mints only a write
+session `mayWriteSource` still gates.
+
+Guess-rate control: redemption runs **one at a time** and every attempt occupies at least 100ms,
+so ten attempts a second against 32⁷ is ~111 years to exhaust and about 1 in 11 million inside a
+five-minute window (measured — 20 concurrent attempts complete at 9.8/sec). After ten
+consecutive failures the slot widens to a second. Not a lockout: the door never closes on a
+human, it only gets slower to knock on. An earlier draft of this used escalating delays plus a
+lockout, and replacing it was the right call — that version had two tunable constants, a counter
+needing reset, and a lockout an attacker could trigger, which is a denial of service against the
+developer on the one credential they need in order to work.
+
+`tosijs-tunnel` prints the host **and where the address came from** before it acts —
+`tosijs-deploy` is dry-run by default and shows its target, this one is not.
+
+**Tooling.** `bin/verify-schema-dep.ts` runs the twelve requirements from tosijs-schema#6 plus
+both directions of #7 against a candidate release and exits non-zero on any failure.
+`PREVIEW_HOST` now also resolves from `~/local-secrets/tosijs-preview.env`, because the previous
+advice — export it from your shell profile — is present for a human and **absent for every
+tool**: non-interactive shells inherit no interactive profile, so an agent or CI step sees
+nothing and reports a missing credential rather than a missing `export`. `readLocalSecret` parses
+`KEY=value` only and never evaluates; a credentials file that needs a shell to read is one that
+can run code. `bin/preview-host.test.ts` includes a guard that greps the committed config for a `user@host`
+literal — and asserts the pattern would have caught the real one, so it cannot pass by being
+wrong. `bin/smoke-consumer.ts` gained four things it could not previously see: resolution of the
+new subpaths from an installed tarball, a `tsc --noEmit` over an installed consumer with
+`skipLibCheck: false` and no optional peers, a bundle entry that actually imports the library,
+and both vendored types pinned by assignability tests in both directions.
+
+- **`<tosi-table>` gained `full-width-header`.** A table whose columns add up to less than its
+  container left a strip of blank space on the right for no reason; with the attribute the
+  leftover width goes to the last **unpinned** column. Right-pinned columns are skipped —
+  they sit against the right edge by definition, so stretching one would push the space back
+  into the middle. When the columns overflow, nothing changes: every column keeps its width
+  and the table scrolls, because the row width is `max(sum, 100%)` and `1fr` then resolves to
+  exactly the width it was given. Header and body share one `grid-template-columns`, so they
+  stretch together.
+
+### Process
+
+- **`bun run release-check` must run AFTER the release commit, and it is the last thing before
+  `git tag`.** The range is `<last tag>..HEAD`, so a bullet written _in_ the release commit is
+  not in the range you checked a moment earlier — 1.11.0 shipped a commit whose body claimed
+  the gate was green while it exited 1 on the state that commit created. The range is also
+  exclusive of the since-commit, so tagging turns the gate green without the bullet ever being
+  written: the annotation escapes in both directions. Now documented in `CLAUDE.md`.
+- The `unenforced.ts` parity test is a **subset** check rather than equality. Upstream growing
+  the set of keywords it enforces is good news, and an equality assertion turned that into a
+  red build. Upstream _shrinking_ below our fallback is the dangerous direction — the fallback
+  would claim a keyword is checked when it is not — and that is still caught.
+
+### Fixed after the pre-release review
+
+The nine-lens review ran **three times** against this release. Everything in this section was
+found by it and fixed before tagging.
+
+- **Editable numeric cells silently truncated what you typed.** Typing `19.95` into a
+  `<tosi-table editable>` number cell committed **95**; `-4` committed **4** — and every
+  commit fired `change` with `error: null`, so nothing reported that a digit had gone. Two-way
+  `bindValue` wrote the model on every `input`, and `<input type=number>` sanitizes an
+  intermediate `"19."` to `""` under the HTML value-sanitization algorithm, so the binding
+  wrote `""` straight back into the focused input. The binding is one-way now and
+  `handleCellChange` is the sole model write — which also makes "commits on `change`, not on
+  `input`" true of the _model_ and not only of the event.
+
+  It was invisible to every lane because every test assigned `.value` programmatically or
+  typed with no delay, and neither ever lets a frame run between keystrokes. There are three
+  tests that genuinely **type**, with a per-character delay, across all three engines.
+
+The nine-lens review ran twice against this release. Everything below was found by it and
+fixed before tagging.
+
+- **`<tosi-crud>` destroyed unsaved edits** — one frame after any keystroke, with no user
+  action, and `save()` then posted the unedited record.
+- **`<tosi-crud>`'s table selection never followed the form**, so a `#?people.id=2` deep link
+  opened the record with nothing highlighted — the feature these notes headline, producing a
+  list that did not show where you were. **Back** also left the opened record on screen while
+  the URL said otherwise, so back-then-reload showed you two different things; and a
+  hash-driven selection change fired no `change` event. Saving a new record now writes its id
+  to the hash, which is both correct and what makes "absent id means deselect" safe.
+- **`<tosi-crud>` rebuilt the entire table on every keystroke.** Identity-guarded; measured at
+  zero table renders per keystroke afterwards.
+- **`<tosi-schema-form>` emitted duplicate `change` events** — a checkbox click produced
+  three. `<tosi-table>` fixed the identical hazard in this release; the sibling shipped
+  without it.
+- **The "not validated" note skipped containers**, so `uniqueItems` on an array and `allOf` on
+  an object — exactly the keywords a validator is most likely to skip — carried nothing.
+- **`columnsFromSchema` re-derived property types** and got `{anyOf:[{type:'boolean'},
+{type:'null'}]}` wrong, and emitted only `title` as the column name — so a title-less schema
+  gave headers reading `firstName` beside a form showing "first name".
+- **`<tosi-table>`'s column menu still concatenated localized words**, which the localize docs
+  in this same release condemn by name. All five languages checked rendered wrong:
+  `Sortieren Aufsteigend`, `숨기기 열`, `非表示 カラム`, `隐藏 列`, `Cacher Colonne`.
+  `localizePhrase(key, fragments)` asks for the whole sentence and joins the fragments only
+  when nobody has translated it — so an existing translation table keeps its behaviour exactly
+  and adding one row upgrades it. Nothing is orphaned.
+- **Six `on<Event>` members were shadowed by the element factory**, which warns about it in
+  the console. Renamed to `handle<Event>` per the framework's own guidance.
+- **The no-validator path had no coverage in any tier** — the default for every ESM adopter,
+  while every lane ran with a validator registered. It has its own test file now. Two real
+  defects were behind that gap: removing a validator left the warnings permanently
+  suppressed, and a single once-flag meant whichever component spoke first silenced the rest.
+- **A form with no schema and no validator rendered an empty box**, warning about validation
+  when the problem was that it had nothing to render. It says so on screen now, and the
+  warning names the right problem.
+- **`change.detail.oldValue` was `undefined` for every cell edit after the first.** The
+  baseline was deleted on each commit rather than rolled forward, and the delete ran _before_
+  the equality guard — so a no-op commit wiped it, and clearing a numeric cell as the second
+  edit fired no `change` at all and skipped the coercion write, leaving a schema-typed integer
+  holding a raw string.
+- **The documented `setSchemaValidator` recipe was wrong**, and only for the people it was
+  written for. `{ validate, inferSchema }` omits `unenforcedKeywords`, so the form fell back
+  to a keyword list frozen at tosijs-schema 1.7.0 and labelled every `oneOf` and
+  `exclusiveMinimum` field "not validated" while 1.8.0 was checking it. Our own doc site was
+  correct because the iife passed all three — so the failure was visible _only_ to the ESM
+  adopters the docs instruct. Pass all three.
+- **`crud.table` and `crud.form` threw before hydration** — the only two accessors on the
+  class without the guard the rest have — so the documented way to reach the composed parts
+  threw on the line the docs told you to write. They return `null` now. The snippet was also
+  in a display-only fence, so no lane ran it; it is executable and tested. And its second line
+  was wrong too: `crud.form.readOnly = true` was silently reverted on the next render.
+- **`<tosi-crud>` wrote `history.replaceState` on every search keystroke.** WebKit throws past
+  ~100 calls in 10s — a held key clearing a long term gets there — and the throw preceded the
+  debounce, so search silently stopped working with an uncaught error. The URL write moved
+  inside the debounce, where the store query already was.
+- **An empty `PREVIEW_HOST` swallowed the whole resolution chain.** `??` only skips
+  null/undefined, so `PREVIEW_HOST=''` — what a CI `env:` renders for a missing secret —
+  counted as "set" and hid both the site config and `~/local-secrets`, the exact symptom that
+  rung was added to abolish.
+- **Adding or moving an array item dropped focus.** Every row is rebuilt, so the button you
+  just clicked stopped existing: you could not press ↓ twice to move an item two places, or
+  add two rows from the keyboard. Focus is restored by role and index, skipping controls that
+  are disabled at the destination.
+- **`<tosi-schema-form>` was quadratic in the keystroke path** — one root-scoped
+  `querySelector` per field, twice, per keystroke. Measured on the built component: 800 fields
+  cost **240 ms** per keystroke before and **0.64 ms** after. An index built with the DOM
+  replaces the scans.
+- **The redemption gate had 21 tests and its wiring had none.** Reverting the dev server to a
+  bare `redeemLink()` call restored both the unbounded queue and the unthrottled guess rate
+  while leaving every lane green — a security control held in place by nothing but the diff.
+  The decision is an exported function now, like the others in that file, and is tested.
+- **Notes read `root.uniqueItems is not validated`** on a field called Tags — upstream's
+  `unenforcedKeywords` answers with paths. The leading `root.` is stripped and deeper segments
+  kept, since for a container the keyword may be several levels down.
+- **These notes themselves published the old preview-host precedence**, inverted against the
+  code and against another paragraph thirty lines earlier. Corrected, with a test asserting
+  all four places that state it agree — that sentence had been written three different ways.
+- **A duplicate mid-file import** in `dev-auth.test.ts`, found only because nothing had ever
+  type-checked the test suite. (~150 accumulated type errors remain; that is tracked, not
+  fixed here.)
+- **The two vendored-type anti-drift guards were never type-checked** — `tsconfig.json`
+  excludes `*.test.ts`, so both were inert and one was **red**: `json-schema.test.ts` asserted
+  our `JSONSchema` is assignable to theirs, which TypeScript cannot decide because both types
+  recurse through `additionalProperties`. The guard now asserts the direction it CAN decide —
+  theirs → ours, the assignment the code actually performs when storing an inferred schema —
+  and the reverse is exercised at runtime by validating an ours-typed schema through their
+  validator. `bun run typecheck-guards` (`tsconfig.guards.json`) runs in CI beside the
+  existing typecheck; mutation-verified that drifting the vendored type turns it red.
+- **`<tosi-table>`'s four column-menu captions** now use `localizePhrase`, so the docs and the
+  docs' own worked example agree.
+
+### Also fixed in the review passes
+
+- `<tosi-schema-form>` let the control's native `change` escape to consumers, so a form edit
+  fired a duplicate event — the `input`-only handler's `stopPropagation()` never saw a
+  `change`. Three events per checkbox click became one.
+- `localizePhrase` asked "did the output differ from the input?" rather than "does a row
+  exist", so a locale that deliberately maps a phrase to itself fell back to joined fragments
+  — the behaviour the row was added to replace. It also re-implemented annotation stripping
+  with a weaker regex than the module's own, which already disagreed about `tag\#42`.
+- `--tosi-spacing-50` is not a variable — the scale is `-xs/-sm/-lg/-xl` — and the `var()`
+  fallback made the mistake invisible. The three genuinely-new customization points
+  (`--tosi-error`, `--tosi-border`, `--tosi-border-radius`) are documented on the schema-form
+  page rather than left accidental.
+- `<tosi-table>`'s `fieldFor` was documented as "cached per render pass" and cached nothing,
+  while allocating a schema and running the validator's keyword walker per editable cell per
+  render.
+- `SiteConfig.tunnel.linkTtlMinutes` said "Default 15" two lines above "Defaults to 5"; the
+  summary line is what an editor tooltip shows.
+- `tosijs-tunnel --link` now prints the 7-character code as well as the URL, which the docs
+  already described and only the dev server's own banner did.
+- The "No preview host" instructions promised a `700` credentials directory and gave a command
+  that neither created nor secured it — and failed outright on a machine that did not have it.
+- `src/docs/utilities.md` was a five-line stub duplicating a section `helper-libraries.md`
+  already provides. Removed.
+- `src/docs/migrating.md` has a **1.11.0 section** — the validator seam, the `tjs-lang` floor,
+  and the edit-token change. It exists for "releases you may be upgrading past" and had no
+  entry despite this release having a Breaking section.
+
+- `<tosi-table>`'s `change` event reported `oldValue: undefined` whenever no `focus` event had
+  fired on the cell — an unfocused browser window, or any consumer who sets `.value` and
+  dispatches `change`, which is what an adopter's test does. The old value came from a
+  `WeakMap` filled on focus, which existed because two-way `bindValue` used to overwrite the
+  model as the user typed. The one-way binding shipped earlier in this release ended that, so
+  the old value is now read from the model immediately before the write — no focus event
+  required, and one mechanism instead of two. Caught by the haltija lane, which the other
+  three lanes do not substitute for.
+
+- `crud.save()` threw away the record it sent when the store returned nothing. A 204-style
+  adapter satisfies `Promise<any>` by resolving `undefined`, which is a perfectly ordinary
+  thing for a REST store to do, and the row went blank. It now keeps what it sent when the
+  store has nothing to say.
+- The `doc-system.pw.ts` nested-doc-system flake — the **fourth** instance this release of a
+  spec racing the page's own inline doc tests. The runner is now disabled for that whole
+  spec file rather than per test, because after four the fix plainly belonged at the file
+  level. 6/6 clean since.
+
+- `<tosi-doc-system>` gave up on the first failed `docs.json` fetch, so a doc site rendered
+  nothing at all when one request lost — a real-user failure, not only the test flake that
+  surfaced it. It now retries three times with full-jitter backoff (250ms base, 4s cap) and
+  honours `Retry-After`. It retries **only 429, 5xx and network errors**: a 404 or a 403 is an
+  answer, and re-asking cannot change it — which is what stops a retry turning an overloaded
+  server into a self-inflicted DoS.
+
+### Known issues
+
+- **firefox intermittently reports `no WebAssembly compiler available`** under the full
+  parallel test lane, which stops the inline-WASM example loading at all. Filed as
+  [tjs-lang#36](https://github.com/tonioloewald/tjs-lang/issues/36): a `wasm {} fallback {}`
+  block should take its fallback branch when the engine declines to compile, which is exactly
+  what that branch is for. Affects the test lane, not shipped behaviour — the example
+  degrades to not rendering rather than misreporting, and the doc-test guard against _silent_
+  fallback is unaffected.
+
+- **[#102](https://github.com/tonioloewald/tosijs-ui/issues/102)** — `<tosi-table>`'s header
+  and body columns can disagree when a programmatic `columns` assignment lands while a render
+  is already in flight. The reporting app changes column visibility on a page-size change,
+  which is what produces the timing. The host app arguably should not reassign columns
+  mid-render, but a torn header/body is ours either way. Targeted at **1.11.1**; the path
+  predates 1.11.0.
+
+### Fixed
+
+**Packaging — this one affects existing `<tosi-table>` users.** `<tosi-table>` no longer reaches
+for a schema library at all: it is the component people use _without_ one, and it must never make
+anyone install something in order to build.
+
+`tosijs-schema` was imported by
+shipped `dist/` and declared in **no dependency field**, so a consumer's build failed on a
+package they were never told they needed. It is now a declared optional peer at `^1.7.0` — which
+is what the design note said from the start — and nothing we ship imports a type from an optional
+peer any more: `import type` is erased from emitted JS but **not** from emitted `.d.ts`, and
+declaring a peer optional does not help because TypeScript has no notion of an optional peer.
+A second instance had been shipping for a while: `dist/code-editor-cm.d.ts` imported a type from
+`tjs-lang/editors/codemirror`, a declared optional peer that TS2307s anyway (reported upstream as
+tjs-lang#28). Verified from a packed tarball in a clean project: `tsc` and `vite build` both exit
+0 with the peers absent.
+
+- The `./*` subpath wildcard mapped `tosijs-ui/schema-form/fields.js` to
+  `dist/schema-form/fields.js.js`, so the extension-ful spelling — what an adopter copying this
+  repo's own ESM import style would write — did not resolve at all. A second `./*.js` wildcard
+  fixes it, strictly additively.
+
+**Localization was wrong in shipped data, and the keys were why.** `<tosi-table>`'s column-header
+menu asked for bare words, and our own translation table shows the cost: `Right` came back in the
+_correct_ sense rather than the direction in four of nine languages (sv `Rätt`, zh `正确的`, es
+`Bien`, it `Giusto`), `Column` as `柱子` (a pillar), `Sort` as `种类` / `종류` (a kind of thing),
+`Show` as `Espectáculo` / `Spettacolo` (the kind with a stage). Every one is a competent
+translation of the word it was given — which is the point. The keys now carry sense annotations
+(`Right#direction`, `Column#table`, `Sort#order`, `Show#reveal`, `Hide#conceal`, `Pin#fasten`,
+`Ascending#sort-order`), and `demo/src/localized-strings.ts` has matching rows with the
+wrong-sense entries corrected, verified in a browser across sv/es/zh. Annotating a key is
+backward compatible, so this cannot orphan an existing table.
+
+**`<tosi-crud>` destroyed unsaved edits.** Four specs now cover delete, its rejection path and
+`createNew`→`save`; mutation testing confirms that restoring the defects turns two of them red.
+
+`showSelected()` compared `form.value !== _selected`,
+and `setByPath` is immutable, so after the first keystroke that was permanently true and every
+render wrote the record as loaded back over the edit — one frame later, with no user action, and
+`save()` then posted the unedited record. The fix keeps the load guard
+(`_loaded !== _selected`) — one invariant, one place — and drops a form-change listener that set
+`_selected = form.value`, which nothing needed: `value` and `save()` read `form.value` directly,
+and `remove()` is better with the record as opened than with a half-edited copy of it. Mutation
+testing settled that: the two were independently sufficient, so neither was pinned and either
+could have been removed without a single test failing.
+
+- `<tosi-crud>`'s destructive paths ran in no lane, and the gap hid two defects: `createNew()`
+  followed by `remove()` sent `store.delete({})`, and the Delete button raised an unhandled
+  rejection on a rejecting store.
+- Grid navigation swallowed arrows, Home and End inside editable cells, so the caret could not be
+  moved and focus jumped away mid-edit; on an enum `<select>` the cell could not be changed by
+  keyboard at all. Escape and Tab stay with the grid.
+- The cell's native `change` no longer escapes the cell. It bubbles, so a listener on the table
+  received both — theirs with a `detail`, the input's with none.
+- The "this keyword is not validated" note rendered **only for unions**, so the honesty it exists
+  for covered exactly one keyword while the docs promised otherwise.
+- `validate` is called with `strict: true`. Without it the validator samples: `maxProperties` is
+  skipped entirely and a bad element deep in a long array is stepped over.
+- The optional-peer degrade was silent. It now warns once naming the package and the seam, and
+  `validationAvailable` lets a Save handler tell _"this conforms"_ from _"nobody checked"_.
+- We read `x-discriminator` first. `discriminator` is an OpenAPI keyword that tosijs-schema's own
+  `agentContract` refuses, so a schema written to pass their check spells it `x-`.
+- The schema→control layer existed twice and had drifted: a `const` property was readonly in the
+  form and a freely editable text box in the table.
+- Variant detection scores branches on how many required keys are present, rather than demanding
+  every key — a half-filled variant used to match nothing and show an empty box.
+- `readOnly` hides the add/remove/reorder controls instead of disabling them.
+- The array controls carry stable classes (`.schema-move-up`, `.schema-move-down`,
+  `.schema-remove`) alongside their localized `title`/`aria-label`: a localized tooltip cannot
+  also be a selector.
+- The hash router treats `?…` in the hash as a query, not part of the path. `#/invoices/42?q=x`
+  previously matched no route at all.
+
+The intermittent Playwright failure was chased rather than re-run until green: `hash-state.pw.ts`
+on WebKit, about one run in four, because the page's own inline doc test writes into the hash
+asynchronously and could land after the spec cleared it. A doc page under test is also a page
+running tests.
+
+**The dev bridge's own guard was a denial of service.** Serialized redemption on an
+unauthenticated path with no depth cap meant 50 junk requests delayed a legitimate link by 42
+seconds, and a trickle outgrew the drain so the denial outlasted the attack. Depth is capped;
+overflow is refused instantly with 503 and `Retry-After`. The clock is also read on **arrival**,
+so a token valid when you clicked can no longer expire while queued.
+
+**Preview host handling.** A project's own `preview.host` outranks
+`~/local-secrets/tosijs-preview.env`; the machine-global file holds one host, and when it won,
+running `tosijs-tunnel` in someone else's checkout pointed it at your box — and that bin does not
+merely print a target. One `resolvePreviewHost()` now serves all three bins. The tunnel's link
+line no longer claims "Single-use edit link (valid 15 min)", and `doc-site-system.md` no longer
+shows `host:` in its example config. `UPSTREAM.md` claimed 0.12.0 was the latest tjs-lang; stale
+by two minors.
+
+### Housekeeping: we published a preview address, and rotated it
+
+Our own `tosijs-site.config.ts` committed the preview host as an ssh target
+(`user@address`) — an **address, not a credential**. Nothing an adopter installs is
+affected, and this is not a security advisory for anyone but us. Recording it because the
+practice it produced is worth adopting.
+
+Verified rather than assumed, since "we're sure there were no keys in there" is exactly the
+sort of claim that deserves checking:
+
+- **no private key material anywhere in the repo's history** — no `BEGIN … PRIVATE KEY`
+  block in any commit on any ref, and no `.pem`, `.key`, `id_rsa` or `id_ed25519` file ever
+  added. `*.pem` is gitignored; the only tracked files under `tls/` are a README and the
+  cert-generation script.
+- access to that box always required a key that was never published, so the exposure was an
+  address someone could try to connect to — not a way in.
+
+It has been **rotated regardless**, because a value that has ever been committed to a public
+repo is public: `git log -S` finds it in seconds, and rewriting history does not un-publish
+anything.
+
+The practice that came out of it, now in `tosijs-coding-practices` → `deployment.md`:
+machine-local credentials live in `~/local-secrets/` — a `700` directory beside the repos,
+never inside one, so committing them is structurally impossible rather than merely against
+the rules. `tosijs-ui`'s bins resolve `--host=` > `PREVIEW_HOST` > `PREVIEW_SSH` > site config >
+`~/local-secrets/tosijs-preview.env` — the machine-global file is **last**, so a project that
+names its own host is never silently redirected at someone else's box — and a regression test
+now greps our own
+config for a `user@host` literal. The rule had been documented in `site-config.ts` the whole
+time and violated in the same repo — which is why the guarantee is now a directory.
+
+## 1.10.2
+
+> **Never released.** This version was tagged but never published, and the tag has since been
+> deleted. Everything below shipped in **1.11.0** instead — including the `killStrayServer`
+> fix, which is why the withdrawal is safe rather than a dropped security patch. npm went
+> straight from 1.10.0 to 1.11.0. Kept here because these changes are real and a reader
+> tracing when something landed needs to find them. ([#101](https://github.com/tonioloewald/tosijs-ui/issues/101))
+
+**The dev server no longer serves stale content after a rebuild.** This is the one that
+presented as random flakiness across several sessions: a served `/docs.json` disagreeing with
+the file on disk made the doc browser's route match fail, so live-example insertion silently
+skipped — the page rendered, hydration reported success, custom elements were defined, and
+**zero examples appeared, with no error anywhere**.
+
+The cause was a cache key of `path + lastModified`, with a comment asserting that a rebuild
+invalidates it naturally. It does not: `lastModified` is millisecond-granularity, and six
+rapid writes to one file report the same value. A rebuild that rewrote a file inside one
+millisecond kept serving the first compressed body until the process restarted — which is why
+a restart "fixed" it. The cache is now emptied on every completed rebuild, and the key carries
+the file size. (#50)
+
+**`killStrayServer` no longer shoots an unrelated process.** Reclaiming the port checked that
+the holder was a JS runtime (`bun`/`node`/`deno`) — but "a JS runtime" is not "our dev
+server", and a colleague's dev server, a language server or a test runner would all pass. It
+now requires the process to be working in **this project**, and skips with a message naming
+the directory when it is not. If the working directory cannot be read it skips too: refusing
+to start costs you ten seconds, shooting the wrong process costs you an afternoon. (#77)
+
+**`bun run release-check` now checks the version against what actually changed** — it blocks a
+patch that carries a `[break]` annotation or touches a security-relevant path, and warns on a
+`[change]`. The nine-lens review triggers on the version _letter_, so it only ever fired when
+the letter was already right; 1.9.9 was prepared, gated, tagged and pushed as a patch while
+relocating a build artifact and loosening a security default, and was caught only because a
+human asked for a review anyway. (#78, #79)
+
+**Docs:** `bundleOutDir` is in the Bundle config table it belongs in, and `checkExamples` —
+including `contextKeys`, which **extends** the default context rather than replacing it — is
+documented where adopters actually look. (#80, #81)
+
+## 1.10.1
+
+> **Never released.** This version was tagged but never published, and the tag has since been
+> deleted. Everything below shipped in **1.11.0** instead — including the `killStrayServer`
+> fix, which is why the withdrawal is safe rather than a dropped security patch. npm went
+> straight from 1.10.0 to 1.11.0. Kept here because these changes are real and a reader
+> tracing when something landed needs to find them. ([#101](https://github.com/tonioloewald/tosijs-ui/issues/101))
+
+Two fixes to 1.10.0's row grouping and scroll preservation, both reported by snowfox against
+a real wide, grouped, pinned table.
+
+**A pinned column that repeats a group value is no longer a hole.** A column that is both
+`pinned` and listed in `nonRepeatingGroupedRowCells` used `visibility: hidden` on its repeated
+cells — which suppresses _everything the cell paints_, including the opaque background
+`.col-pinned` exists to provide. On every row but the first of its group, horizontally
+scrolled cells showed through the sticky column **and were clickable there**: a visual hole
+and a hit-testing hole from one rule. Repeated cells now hide their _content_ (transparent
+text, `display: none` on element children, `user-select: none`) and keep painting their box.
+(#83)
+
+**`preserveScroll` now restores horizontal position too.** It restored `scrollTop` alone, and
+the tables that most need it are the wide ones — normally read scrolled sideways, with pinned
+columns as the identity and the interesting columns off to the right. Sorting or toggling a
+group snapped back to column 0, so the row stayed put while appearing to say something
+completely different. `scrollLeft` is captured independently of the row anchor, so it also
+survives on a table that is scrolled sideways but still at the top — which used to return
+early and lose the columns. (#86)
+
+Group ids are memoized per render in a `WeakMap`; the map is replaced each render, so a
+cached id can never outlive the values it came from.
+
+## 1.10.0
+
+Mostly a **silent-failure** release: several things that were quietly not working, or quietly
+not being checked, now say so. If you use `tosijs-ui/site`, three of these have probably cost
+you time already.
+
+### `<tosi-table>`
+
+**Scroll position survives a re-render.** Sorting, filtering, or toggling
+`visibleGroupedRowIds` no longer throws you back to the top. The table anchors on the
+**topmost visible row**, not on `scrollTop`, and restores that row to the same offset — the
+distinction matters as soon as the row count changes, because the same pixel offset then
+shows entirely different rows. Set `preserveScroll = false` for the case where a render means
+"here is a different dataset" and starting at the top is right.
+
+### The tunnel: links now work on a second device
+
+A magic link is redeemable **repeatedly for 15 minutes** instead of dying on first use. The
+old behaviour collided with the feature's own purpose: glance at a link and close the tab and
+you need a new one; open it on a laptop then reach for your phone and it is dead — in a
+workspace built for reading your uncommitted tree _on a phone_. One project had already
+replaced it with a never-expiring link of their own, which is the tell.
+
+The bound moved from _uses_ to _time_, not away. Set the level per project:
+
+```typescript
+tunnel: { linkPolicy: 'single-use', linkTtlMinutes: 2 }   // ratchet up
+```
+
+An expired link is refused under either policy — widening reuse never widens lifetime.
+
+Every user-facing string — including the line the CLI prints at the moment you share a link
+— is derived from the policy in force, rather than asserting "single-use" regardless.
+
+### Silent failures, now loud
+
+- **`docPaths` are watched.** A root-level doc was served and rendered but never watched:
+  edit, save, refresh, stale page, no rebuild, no message — indistinguishable from a browser
+  cache. (#49)
+- **Two builders on one output tree are refused,** naming the holder's pid and port. Both
+  wipe-then-repopulate `docs/`, so running a standalone build against a live dev server meant
+  each deleted what the other was writing; it killed a dev server with no error anywhere and
+  left `docs/` a fraction populated. A standalone `buildSite()` refuses; a second **dev
+  server** only warns and continues, because `bun playwright test` and `bun run test-browser`
+  each start their own and a hard failure there would break the lanes this protects. The lock
+  is stale-safe (a dead holder's lock is debris), re-entrant, released on Ctrl-C, and fails
+  open. (#51)
+- **A truncated `/*#` doc block warns, by name.** Block comments cannot nest, so a `*/`
+  inside a doc demo ends the doc there — previously surfacing as parse errors pointing at
+  _prose_, never at the delimiter responsible. (#70)
+- **Inline doc tests no longer under-report.** A page could report "done" before its examples
+  had run, so their tests were omitted rather than failed — silently, with the suite green.
+  **If you use `tosijs-ui/site` with async examples, your counts may have been wrong;** a
+  number that goes UP after upgrading is this fix.
+
+### Build output
+
+**The hydration bundle now builds into your site output, not `dist/`.** It was written into
+the library tree with only the `.js` copied out, stranding the sourcemap in a directory you
+publish and commit but never serve — 65 MiB across 216 packed blobs in one adopter, ~35% of
+that repo's packed blob store, for a file nothing could load. Set `bundleOutDir` if your
+bundle is itself a published artifact. If you have that history:
+`git rm --cached dist/iife.js dist/iife.js.map` and gitignore them. (#69)
+
+### Also in this release
+
+- **`checkExamples` accepts `{ contextKeys: [...] }`** as well as a boolean, so a library
+  that documents ITSELF — whose examples import its own package name — keeps the guard on
+  instead of disabling it. The keys are **added to** the `tosijs` / `tosijs-ui` defaults, not
+  substituted for them. (#71)
+- **`preview.tunnel.linkPolicy`** (`'window'` | `'single-use'`) and
+  **`preview.tunnel.linkTtlMinutes`** (default 15) set the link security level.
+- **`SiteConfig.preview.host` is optional.** The documented practice supplies it from
+  `PREVIEW_HOST`, so a correct config used to fail typecheck. (#72)
+- **`marked` peer is `^16.4.2 || ^17.0.0 || ^18.0.0`** — it was two majors behind `latest`, so
+  a consumer on a current marked got a peer violation on a fresh install. (#60)
+- **The live-example docs now state that `test()` bodies run concurrently** within a fence,
+  and give the rule that follows: steps that depend on each other belong in one `test()`.
+  (#43)
+- **`llms.txt` carries the browser-control affordance** when a project sets `haltijaDev`, so
+  an agent learns it can drive the running page instead of inferring behaviour from source.
+  (#18)
+- **Host bootstrap in `doc-site-system.md` now gives the actual commands** rather than
+  describing the danger and leaving the dangerous step as an exercise.
+- **`svg2DataUrl`: two real fixes, and one that is NOT done.** It wrote `strokeWidth` /
+  `strokeLinecap` / `strokeLinejoin` — names SVG ignores — on any element carrying inline
+  style, and explicit `fill` / `stroke` / `strokeWidth` arguments were clobbered by the style
+  pass. Both fixed.
+
+  **[#68](https://github.com/tonioloewald/tosijs-ui/issues/68) is NOT closed by this.** Most
+  icons carry their styling on the **root** `<svg>`, which this does not touch, so a
+  `stroked` icon — about 280 of ~287 — still serializes with no stroke at all and renders as
+  a solid black wedge. Verified after the fix: `svg2DataUrl(icons.chevronRight())` emits no
+  `stroke` and no `stroke-width`. Prefer inline `<svg>` over a data URL for stroked icons
+  until this lands.
+
+- **`acquireBuildLock` / `lockDecision`** in `build-lock.ts` — the
+  output-tree lock behind the concurrent-build refusal. **Internal**: not exported from
+  `tosijs-ui/site`, so do not build on it yet. Say so if you want it public.
+- New **`tosijs-caddy-install`** bin — installs the Caddy snippets the deploy/tunnel bins
+  need, **refuses** to install a template with placeholders left in it, keeps the outgoing
+  config as `Caddyfile.bak`, and is dry-run by default. That refusal was the reason this
+  existed as a private script; shipping the template without it was the wrong half to keep.
+- The unit lane now covers `bin/` — `bunfig.toml`'s test root was `./src`, so tests anywhere
+  else were silently never collected.
+
+> **Versioning note.** This is a patch that adds public API. Minors are for breaking changes
+> and feature rollouts; additive, non-breaking extensions ship as patches. The contract you
+> rely on is unchanged: **a patch never breaks you.**
+
 ## 1.9.8
 
 **Grouped tables can now say how much of a group is showing.** The piece missing from 1.9.7's
@@ -54,14 +707,23 @@ know anything about grouping. It is additive to the filter's own result, so a fi
 ranks as well as selects keeps its ranking.
 
 Two details worth knowing. **Clusters keep your sort**: groups appear in first-appearance
-order, so a group lands wherever its best-sorted row landed. Sorting the clusters by their
-id instead would have quietly thrown away the sort the user just clicked. And repeated
-cells are **hidden, not emptied** — `.tr:not(.table-cluster-first) .cluster-repeat
-{ visibility: hidden }`. If you write your own rule for a custom `dataCell`, use
-`visibility`, never `display: none`: every cell is an item of the row's grid, so removing
-one pulls each later cell a column left and the row renders under the wrong headers.
+order, so a group lands wherever its best-sorted row landed. Sorting the clusters by their id
+instead would have quietly thrown away the sort the user just clicked.
+
+And repeated cells are **hidden, not emptied** — transparent text plus `display: none` on
+element children, via `.tr:not(.table-cluster-first) .cluster-repeat`. Deliberately not
+`visibility: hidden`, which also stops the cell painting its **background**: a pinned
+column's background is the only thing masking the columns scrolling underneath it, so
+repeated cells there became windows onto the scrolled content. And never `display: none` on
+the cell itself — every cell is an item of the row's grid, so removing one pulls each later
+cell a column left and the row renders under the wrong headers.
 `table.isFirstInGroup(row)` answers the same question in JavaScript.
 
+Group ids are **memoized per render** in a `WeakMap` — the id is computed several times for
+one row in a single pass (clustering, parity, first-of-group, counts, then again per stamped
+row), and the inferred form does a `JSON.stringify` each time. The map is replaced on every
+render rather than kept, so a cached id can never outlive the values it came from.
+
 Ungrouped tables are unaffected — all three properties default to off.
 
 **The inline doc-test lane was under-reporting, and staying green about it.** If you use