tosijs-ui 1.10.0 → 1.11.0

package/CHANGELOG.md

@@ -1,5 +1,548 @@
 # 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

package/bin/caddy-install.ts

@@ -34,7 +34,7 @@ Three deliberate properties:
 */
 
 import { existsSync, readFileSync } from 'fs'
-import { resolveSiteConfig } from './resolve-site-config'
+import { resolvePreviewHost, resolveSiteConfig } from './resolve-site-config'
 
 const siteConfig = await resolveSiteConfig()
 
@@ -69,21 +69,19 @@ if (unknown.length || has('help')) {
   process.exit(bad ? 1 : 0)
 }
 
-const host =
-  flag('host') ??
-  process.env.PREVIEW_HOST ??
-  // Legacy alias. This repo's own `deploy:index` script still asks for PREVIEW_SSH,
-  // so someone who exported the only variable it ever mentioned would otherwise be
-  // told "No preview host" with nothing pointing at why.
-  process.env.PREVIEW_SSH ??
-  siteConfig.preview?.host
+const host = resolvePreviewHost(flag('host'), siteConfig.preview?.host)
 const go = has('go')
 
 if (!host) {
   console.error(
     `\nNo preview host.\n\n` +
-      `  Set one once in your site config:\n` +
-      `      preview: { host: 'user@example.com' }\n\n` +
+      `  Put it where machine-local credentials live — a 700 directory beside the\n` +
+      `  repos, so it cannot be committed:\n` +
+      `      mkdir -p ~/local-secrets && chmod 700 ~/local-secrets\n` +
+      `      echo 'PREVIEW_HOST=user@example.com' >> ~/local-secrets/tosijs-preview.env\n` +
+      `      chmod 600 ~/local-secrets/tosijs-preview.env\n` +
+      `      echo '[ -f ~/local-secrets/tosijs-preview.env ] && . ~/local-secrets/tosijs-preview.env' >> ~/.zshenv\n` +
+      `      # ~/.zshenv, not ~/.zshrc — scripts and agents get no interactive profile\n\n` +
       `  ...or pass it per-run:\n` +
       `      tosijs-caddy-install --host=user@example.com --go\n` +
       `      PREVIEW_HOST=user@example.com tosijs-caddy-install\n`

package/bin/deploy-preview.ts

@@ -28,7 +28,11 @@ Two deliberate safety properties:
 
 import { $ } from 'bun'
 import { existsSync } from 'fs'
-import { registerCaddyFragment, previewRootFor } from './resolve-site-config'
+import {
+  previewRootFor,
+  registerCaddyFragment,
+  resolvePreviewHost,
+} from './resolve-site-config'
 import {
   resolveSiteConfig,
   isSafeRemotePath,
@@ -51,14 +55,7 @@ const preview = siteConfig.preview
 // Precedence: explicit flag > env > site config. The config is the "just works"
 // default; the flag exists so you can push a one-off somewhere else without editing
 // (and committing) a config file.
-const host =
-  flag('host') ??
-  process.env.PREVIEW_HOST ??
-  // Legacy alias. This repo's own `deploy:index` script still asks for PREVIEW_SSH,
-  // so someone who exported the only variable it ever mentioned would otherwise be
-  // told "No preview host" with nothing pointing at why.
-  process.env.PREVIEW_SSH ??
-  preview?.host
+const host = resolvePreviewHost(flag('host'), preview?.host)
 const remotePath =
   flag('path') ??
   process.env.PREVIEW_PATH ??
@@ -70,8 +67,13 @@ const go = has('go')
 if (!host) {
   console.error(
     `\nNo preview host.\n\n` +
-      `  Set one once in your site config:\n` +
-      `      preview: { host: 'user@example.com' }\n\n` +
+      `  Put it where machine-local credentials live — a 700 directory beside the\n` +
+      `  repos, so it cannot be committed:\n` +
+      `      mkdir -p ~/local-secrets && chmod 700 ~/local-secrets\n` +
+      `      echo 'PREVIEW_HOST=user@example.com' >> ~/local-secrets/tosijs-preview.env\n` +
+      `      chmod 600 ~/local-secrets/tosijs-preview.env\n` +
+      `      echo '[ -f ~/local-secrets/tosijs-preview.env ] && . ~/local-secrets/tosijs-preview.env' >> ~/.zshenv\n` +
+      `      # ~/.zshenv, not ~/.zshrc — scripts and agents get no interactive profile\n\n` +
       `  ...or pass it per-run:\n` +
       `      tosijs-deploy --host=user@example.com [--path=/srv/preview/x] [--go]\n` +
       `      PREVIEW_HOST=user@example.com tosijs-deploy\n`