tosijs-ui 1.13.0 → 1.14.1

package/CHANGELOG.md

@@ -1,5 +1,798 @@
 # Changelog
 
+## 1.14.1
+
+### The doc-test gate can tell a dropped page from a passing one
+
+`__docTestResults` reported `{ passed, failed, pages }`, so a consumer gate could assert that
+tests ran and that none failed — but not that **all** of them ran. A runner that silently lost
+half the corpus satisfied every check.
+
+That is not hypothetical. The false green fixed in 1.14.0 was a page-**selection** defect: a
+substring match counted 17 pages where 16 had tests, and ran a prose page's examples in a
+background iframe. Fixing the selection did not add a guard against the next one.
+
+The resolved object now carries `pagesWithTests` and `pagesTested`, and
+`tests/doc-tests.pw.ts` asserts three things where it previously asserted one: the corpus
+contains test pages at all, every such page reported, and some assertions executed. A corpus
+with genuinely no tests resolves with honest zeros, so "no tests exist" stays distinguishable
+from "tests exist and ran".
+
+Framed by tosijs-platform in #142, from a suite that reported **140 pass, 0 fail while twelve
+cases had never executed** — skip-guarded behind emulators that were not running, asserting
+`expect(true).toBe(true)`. When the emulators were finally started it found three production
+bugs in ten minutes. The tests were fine; the reporting was a lie, and a comfortable one, which
+is why it survived. **"We didn't look" and "we looked and it's fine" must not produce the same
+output** — a reported total is that same lie one level up.
+
+### New page: "Adopting the doc system"
+
+Three of the four onboarding defects this release fixes (#144, #145, #146) would have been
+prevented by a page that did not exist — a narrow path to read *before* the first build, as
+opposed to a configuration reference nobody reads until something is already wrong.
+
+It is organised around the thing that makes this system hard to adopt: **its failure mode is a
+site that serves perfectly and shows nothing.** Not a crash, not a 404 — pages return 200, the
+markup is in the HTML, the adopter's own elements register, and the page is inert. So the page
+leads with a "how to tell it actually worked" checklist (is `tosi-doc-system` defined, is the
+chrome there, read one emitted `<head>`, do the examples run) and then explains the four silent
+failures behind those checks.
+
+Includes the complete `bundleEntry` file rather than naming it, since "your entry should import
+what your pages need" was the sentence that cost #145's reporter the most — it reads as *your*
+content, not as the doc system that renders the entire site.
+
+### `<tosi-table>` filters and sorts the whole table, not the first `maxVisibleRows` (#147)
+
+The window was applied **first**, so both the filter and the sort saw only the first N rows.
+Two consequences, both reported from production at 300k rows:
+
+- **A matching row past the cap could never be found.** A newly-created company appended to a
+  12,000-row list, with the cap at 10,000, did not exist as far as search was concerned.
+- **Sorting did not sort the table.** You got the first N rows in *data* order, arranged
+  nicely — not the top N by the sort.
+
+This was known and the answer had been a warning: the comment in the render path read *"every
+count, filter and sort then ran on the truncated set, so the numbers were self-consistent and
+wrong"* (#82). A warning does not help someone whose search returns nothing, and it named row
+counts rather than the consequence — so "showing 10,000 of 12,000 rows" gave no clue why a
+search failed.
+
+The order is now **filter → force → sort → cluster → window**. `maxVisibleRows` is a *layout*
+ceiling — the browser's maximum element height — so it belongs at the end, against what will be
+drawn, rather than at the start against the data.
+
+**Cost, measured on 300k rows**, since this moves the sort from "at most `maxVisibleRows`" to
+"every match": the common case (no sort set) is **0.9ms, down from 2.9ms**; a filter narrowing
+to ~1% is 2.0ms; a broad sort over all 300k is **108ms**. That last one is the price of sorting
+the real table, and it is paid when you click a column header — but `pinColumns()`, a schema
+change and a column resize all trigger a render without changing row order, so the pipeline is
+memoized against the identities that determine it (array, filter, sort, groupId, forced ids).
+A render that changes none of them reuses the result.
+
+The truncation warning now counts against the **filtered** set — "10,000 of 300,000" is
+alarming and wrong once a filter has narrowed things to 40 — and says that the rows shown are
+the right ones, there are simply more than the browser can lay out.
+
+### `menuClass` — theme one component's menus without restyling the page (#148)
+
+Menu metrics are all theme variables, and setting them on your component **did not work**.
+The popup is built per-invocation and mounted in a body-level `<tosi-float>`, so it is not a
+descendant of whatever opened it, and custom properties have nothing to inherit from. The only
+selector that reached it was `:root` — which restyles every menu on the page, including the doc
+system's own when your component is documented on a `tosijs-ui/site` site. The reporter had not
+shipped their denser menubar for exactly that reason: a component reaching out to re-theme the
+page around it is the wrong direction.
+
+```
+popMenu({ target, menuItems, menuClass: 'my-editor-menu' })
+<tosi-menu menu-class="my-editor-menu">
+<tosi-select menu-class="my-listbox">      // its listbox mounts the same way
+```
+
+The class lands beside `xin-menu tosi-menu`, takes a space-separated list, and **propagates to
+submenus** — which are separate popups, so without that the theming would apply at the top
+level and silently revert one level down. `menuWidth` was already a per-menu attribute, so
+per-menu styling is not new here; this is the same idea for the rest of the knobs.
+
+Chosen over the two alternatives in the report: copying the trigger's computed variables onto
+the popup needs no change from adopters but is considerably more magic, and stamping a
+`data-menu-owner` back-reference solves selection without solving theming.
+
+### Adoption blockers found by tosijs-editor onboarding (#144, #145, #146)
+
+Three defects and a credential, all found by one project adopting `tosijs-ui/site` for the
+first time. Every one of them failed silently.
+
+**A Mapbox token in `dist/` blocked adopters' pushes (#145).** Two `<tosi-map>` doc examples
+carried a literal `pk.` token, which compiled into `dist/mapbox.js`, inlined into `iife.js`,
+and landed in every adopter's sourcemap. It matches Mapbox's published secret pattern, so
+**GitHub push protection blocked adopters the first time they committed their built site** — a
+wall with someone else's name on it.
+
+To be clear about what this is and is not: Mapbox `pk.` tokens are **public by design** —
+Mapbox's own docs tell you to put them in client-side JavaScript — so the scanner match is a
+false positive and there was never a secret here. The demos still use the token; it is now
+assigned programmatically and base64'd, which is **not** a security measure and would be a
+poor one. It exists solely so the literal string stops matching a regex. `atob()` protects
+nothing from anyone, which is precisely why it suits a value that needs no protection.
+
+`src/no-secrets.test.ts` fails the build on any credential-shaped string in `src/`, and says
+plainly what it cannot see: an encoded value, deliberately. It catches accident, not intent.
+
+**`bundleEntry` REPLACES the default bundle rather than extending it (#145).** An entry that
+imports only your own library produces a site where every page renders its prerendered markup
+and nothing else — no header, no nav, no menu, no live examples — with no console error, no
+build warning and no 404. `<tosi-doc-system>` sits in the HTML, inert, because nothing defined
+it, while your own elements register fine and make the bundle look healthy. The jsdoc now says
+this in the imperative with the two-line fix, and the build **scans the emitted bundle and
+warns** when `tosi-doc-system` is absent (and `tosi-example`, when the corpus has executable
+fences). Grepping is sound here for once: `customElements.define` needs the literal tag, so
+minification cannot erase it.
+
+**`baseUrl` meant two different things (#144).** `generate-site` treated it as the origin and
+added `basePath` on top; `make-llms-txt` treated it as origin-plus-path and ignored `basePath`
+entirely. On a GitHub project page no configuration satisfied both — matching the canonical
+URLs doubled the prefix in `llms.txt`, matching `llms.txt` dropped it from every canonical and
+sitemap entry. Underneath were **two copies of `withBase`** (`generate-site`, and `epub`, whose
+comment read "mirrors generate-site's withBase") plus this third consumer with none: one rule,
+three implementations, one of them empty. `withBase` now lives once in `routing.ts`, `llms.txt`
+applies it, `baseUrl` is documented as origin-only, and the build warns on the combination that
+is always wrong.
+
+**Which fence languages execute was undocumented (#146).** Six run — `js`, `ts`, `tjs`,
+`html`, `css`, `test` — and the only place the distinction appeared named a subset, so the
+mental model everyone formed was "js/ts/tjs/test run, everything else is display". A ` ```css `
+fence showing how to style the component in your app is injected as a page-wide `<style>`; a
+lone ` ```html ` fence showing the markup something compiles to renders as a broken-looking
+example. Neither fails the build. Now documented as a table with display-only alternatives
+(`xml` for markup), along with the grouping rule — adjacent fences form one example, prose
+between them starts a new one — which is why moving a `test` block under its own heading
+silently detaches it from the demo it was written against.
+
+## 1.14.0
+
+### Quote style no longer decides whether a live example runs (#141)
+
+The live-example import rewriter accepted `'single-quoted'` specifiers and rejected
+`"double-quoted"` ones — the same import, the same `{ named }` form, differing only in quotes.
+
+On its own that is a papercut. What made it serious is **Prettier**: it formats fenced code
+inside markdown and normalises quotes to double, so on any project that formats its `.md`,
+every live example was silently converted into a non-running one. The only symptom was a
+build-time warning that reads as advisory.
+
+Reported from tosijs-3d-ensemble, where the README's headline example — the one showing what a
+game imports — had never run for the life of the repo. Because it never ran, nothing noticed it
+also named a function the package has never exported. Two defects in the most-read code block
+there, both invisible for the same reason. Found by the doc-test corpus, not by reading.
+
+All three context forms (`{ named }`, `* as ns`, default) now accept either quote style, as
+does the `.elements` accessor.
+
+**And the error message named the wrong thing.** It listed the supported forms and the context
+packages — so a failing `import { x } from "pkg"`, a listed package in a listed form, was
+answered with a sentence that ruled out its own cause. The reporter spent ~40 minutes rewriting
+a multiline import that was never the problem. The message now separates the two real causes: a
+specifier the context does not carry, versus a clause shape the rewriter cannot handle.
+
+### `<tosi-code>`'s own diff overlay is readable by default (#143)
+
+`<tosi-diff>` resolves its surface as `--tosi-diff-bg || --background`. Inside `<tosi-code>`,
+`--background` is still the page's white while `--text-color` is deliberately the light code
+colour — so the diff `showDiff()` mounts rendered near-white text on white, and its unchanged
+lines were invisible. The one place the component mounts a diff itself was the one place the
+default did not work.
+
+`--background` is now redefined for that subtree to follow `--code-bg`, so the nested diff
+inherits the editor's palette. Deliberately **not** by setting `--tosi-diff-*` here: an inner
+definition beats an inherited one, so that would have overridden the very custom properties
+adopters are already using as an escape hatch — a silent break of the thing the issue was
+about. A consumer's `--tosi-diff-bg` is still checked first and still wins.
+
+### Live `ts` examples load a pinned TypeScript compiler
+
+tjs-lang's `fromTS` lazy-loads the TypeScript compiler from `DEFAULT_TYPESCRIPT_URL` —
+`https://esm.sh/typescript@5`, an **unpinned major range**. It was the one hop in the entire
+live-example chain that was neither same-origin nor pinned: everything else routes through
+`__TJS_LOCAL_BASE` or a `TJS_VERSION`-pinned CDN. Because it is fetched at runtime it appears
+in no lockfile, so `bun audit` cannot see it and "which compiler ran in a reader's browser" had
+no answer.
+
+Now pinned, via the `typescriptUrl` option tjs-lang already exposes, to the **exact version
+this repo type-checks with** — so a doc example is lowered by the same compiler that validates
+the source it was extracted from. A drift test asserts the pin against the **installed**
+compiler rather than the declared range, because `typescript` is a caret dependency here and a
+range check would call `^5.9.3` satisfied while the pin said something else.
+
+esm.sh stays as the host — tjs-lang measured it as the only CDN that reliably serves
+`typescript` as ESM. The fix is the pin, not the host; a same-origin copy is the upstream ask.
+
+Nobody was exposed: this repo's corpus contains no executable ` ```ts ` fences.
+
+### `MenuAction.action` is optional, so a drop-only menu item is expressible
+
+`acceptsDrop` + `dropAction` with no `action` — a target you can drag onto but not click — is
+a shape the runtime supports and `popDropMenu`'s docs describe, but the type required `action`.
+When the new typecheck lane compiled the tests for the first time, four literals were silenced
+with `as unknown as MenuItem` rather than the type being corrected.
+
+The casts are gone. Two tests now pin what the widened type admits: a drop-only item appears
+**disabled** in a click menu and is removed only under `hideDisabled` — the documented
+`hideDisabled` contract. (The first draft of that test asserted it was filtered out entirely,
+and failed; the finding implied a behaviour the code does not have.)
+
+### `buildSite` docs: `dist/` is reset only when the build owns it (#130)
+
+Three shipped surfaces still promised an unconditional reset — the config table and the
+gotchas list in `doc-site-system.md`, and the `prebuild` JSDoc, which reaches
+`dist/doc-system/site/site-config.d.ts` and is what an adopter reads on editor hover.
+
+`dist/` is cleared only when `emitLibrary` or `libraryTsconfig` means this build produces it.
+A `libraryBuild` function owns the directory and may deliberately emit a subset, so it is never
+cleared — **if you supply `libraryBuild`, cleaning `dist/` is yours.** The output dir is still
+always reset, which is the part `prebuild` authors actually need to know.
+
+### Security: the source editor can no longer write files the build executes (#128)
+
+`editableSources` writes were contained only to the project root — which includes
+`.git/hooks/*`, `bunfig.toml` (preload), `package.json` scripts and `bin/`, every one of which
+runs on the developer's next ordinary command. With CSRF closed (#90/#121) there was no known
+path to an unauthorised write; this removes the *consequence* of a future one.
+
+`editableSourcePaths` / `mayEditSource` build an **allow-list derived from the doc corpus**,
+not a deny-list of dangerous names: the endpoint exists to edit the source of a page you are
+looking at, so the writable set is exactly what the extractor scraped. A deny-list needs
+extending every time someone invents a new way to make a file execute and is wrong by default;
+this is right by default. It **fails closed** — an unreadable corpus permits nothing.
+
+**The first version of this was not enough, and the pre-release review caught it.** A doc
+source can itself be an executed script: `bin/make-icon-data.js` carries a `/*#` block, so it
+was a doc source, so it was writable — and `bin/dev.ts` spawns it on *every* build. The
+original tests passed because the synthetic corpus omitted `bin/`, and the live check used
+`.git/hooks/pre-commit`, which the corpus never contained. Both proved something true and
+irrelevant. There is now an `isExecutedByBuild` deny layer (all of `bin/`, the spawned `-cli`
+scripts, `generate-css`), and the tests run against the **shipped** corpus with an assertion
+that the dangerous entry is really in it — otherwise the refusal test proves nothing.
+
+The **read** half is gated by the same predicate. It was left open initially on the grounds
+that the reported issue was a drive-by write; the review was right that the argument for
+symmetry was stronger, since "view source" only ever reads a doc's own source.
+
+### The dependency audit knows where a package sits (#56)
+
+`runtimeReachable` / `classifyReach` walk the manifest graph and label an advisory's package
+**runtime** or **build-only**. Reported from an app monorepo running `buildSite`: 18
+high/critical advisories of which the runtime-reachable subset was a small fraction, so
+blocking on all of them would have bricked local dev over risk they do not carry.
+
+Conservative by construction — root `dependencies`, `optionalDependencies` **and
+`peerDependencies`** are runtime seeds (a peer ends up in the consumer's app), and an
+unresolvable package counts as reachable. A finding silently downgraded is the one outcome
+worth engineering against.
+
+`audit.blockOn: 'severity' | 'runtime'` defaults to `'severity'` — today's behaviour. Set
+`'runtime'` and a build-only finding is reported but does not block. If the manifest walk fails
+the filter is disabled entirely, because "we could not tell" must not read as "not reachable".
+
+A build that passes **only because of an active gate** now says so:
+
+```
+🟡 Build: PASSING ON A WAIVER — 1 finding(s) at or above high are suppressed
+   by an active gate. This is not a clean audit.
+```
+
+Only when the waiver is load-bearing: a gate suppressing something below the threshold would
+have passed anyway, and flagging that would train people to ignore the marker.
+
+### The doc-test runner stopped executing pages that only *mention* tests
+
+`docsWithTests` matched ` ```test ` as a **substring anywhere in the document**, so a page
+merely writing about the test tier qualified — and was rendered in a background iframe with its
+examples executed. A failure in an example on a page with *no tests* therefore surfaced through
+the doc-test tier, and only sometimes, depending on how quickly the TypeScript compiler loaded.
+
+That produced a **false green**: a standalone doc-tests run reported "62 passed" against a build
+the full suite failed on. Page selection now requires a fence at the start of a line, the same
+rule the doc extractor applies to `/*#`.
+
+The example it was hiding was ours: a ` ```ts ` fence in `doc-site-system.md` — added in the
+#93 write-up — was **executable**, so the doc-test lane ran `Bun.spawn` and `process.on` in a
+browser and threw `ReferenceError: process is not defined`. It is now ` ```typescript `, which
+is display-only. One character, and it had been red on `main` from the moment it was pushed.
+
+Related and still open (#138): an example that *compiles and then throws* is caught by nothing
+on a page without a ` ```test ` block. The build-time check catches what will not compile, not
+what compiles and fails.
+
+### An existing `firebase.json` is checked against `outputDir` (#134)
+
+`host: 'firebase'` scaffolds a config for a fresh project and keeps its hands off an existing
+one — but checked nothing, so `buildSite` could write `docs/` while `firebase deploy` published
+`.demo/`. Both commands succeed and the site serves whatever was there last. It now warns,
+handling multi-site arrays, framework-aware hosting with no `public`, and `./docs` vs `docs`
+spelling, and warns only when *every* declared target disagrees.
+
+### tjs-lang 0.13.4 → 0.13.11, and the two pins can no longer drift (#135)
+
+We were pinned to a version npm has **deprecated**, seven releases behind. The deprecation's
+threat model does not reach live-example — it is about a server transpiling submitted source —
+but sitting on a deprecated version with seven releases of fixes is its own problem.
+
+`TJS_VERSION` (what the *published site* fetches from a CDN) and the exact devDependency (what
+tests and local builds use) live in different files, so a test now asserts they agree. Drift
+there is invisible exactly where it matters: every lane stays green while the deployed site
+transpiles with a different version.
+
+### `<tosi-example>` warns when executable fences collide (#139)
+
+`js`/`tjs`/`ts` all write the same single-valued slot, so a second executable fence silently
+overwrote the first — the earlier block vanished from the page, the example ran as the later
+dialect, and nothing said so. Behaviour is unchanged (last one still wins); it now names the
+file and which dialect survived. This is the seam a dialect selector needs, which is why it is
+worth fixing before that feature rather than during it.
+
+### `getSelectText` returned the empty string on every call
+
+`<tosi-filter>` read `select.options[select.selectedIndex]`, and `selectedIndex` has never
+existed on `TosiSelect` — it selects by value. So every filter chip read ` "needle"` with two
+blanks where the field and condition belong, which looks like a styling bug. Found by adopting
+tosijs 1.10.0, whose removal of `Component`'s `[key: string]: any` index signature made the
+compiler able to see it for the first time.
+
+### Markdown is no longer formatted, and `bun format` is green again
+
+`*.md` is in `.prettierignore` by request from tosijs. `proseWrap` was already `preserve`, so
+prettier's only remaining markdown behaviours were escaping literal characters
+(`a * literal` → `a \* literal`), padding table cells, and rewriting `*` bullets — the first of
+which edits a document's *content*, and markdown is the product here.
+
+Separately, `bun format` had been exiting 1 on seven ESLint errors: CI gates `format-check`,
+which runs prettier only, so the ESLint half of the documented pre-commit command was red
+without failing anything. Among the fixes: two dead locals in the CSRF same-origin check
+(checked rather than assumed — the logic was sound, only the initialisers were dead); a dead
+`explanation` in `dev-server.ts` that was built and never used, left over from before
+`invite-page.ts` took ownership of that copy in #114; and an
+`AsyncFunction` construction failure that now rethrows with `{ cause }` so the engine's own
+error — the one naming *which* parameter it choked on — is not discarded.
+
+### `icons.*` was typed `SVGElement`, and composites are spans
+
+**This is why the release is a minor.** `SVGIconMap` declared every icon as
+`ElementCreator<SVGElement>`. A **composite** icon — any name containing `$`, the stacking
+syntax `icon-composition.md` documents and the demos use throughout — returns an
+`HTMLSpanElement`.
+
+Measured rather than reasoned about:
+
+```
+icons['tosiHat$tosi']()  → SPAN, instanceof SVGElement === false
+icons.lock()             → svg,  instanceof SVGElement === true
+```
+
+`resolveIcon` has always returned the honest `Element`; only the cast on the exported proxy
+disagreed. It is now `ElementCreator<IconElement>`, and **`IconElement` is exported from
+`icon-types.ts` for consumers holding an icon** — defined as `SVGElement | HTMLSpanElement`.
+Both members carry `.style` and `.dataset`,
+which is what callers actually reach for — widening all the way to `Element` would break
+working code to no purpose.
+
+**Why a minor rather than a patch.** Nothing about the runtime changed; a composite has always
+been a span. But code that annotated an icon as `SVGElement` compiled before and does not now,
+and "a patch never breaks you" is the contract. This breaks you out of a false belief, which is
+still breaking.
+
+**The lie was load-bearing.** Correcting it surfaced **14 sites in this repo** — `data-table`,
+`notifications`, `rich-text`, `segmented` — that stored or passed an icon as `SVGElement`. Any
+consumer doing the same has the same latent bug, which is the argument for fixing the type
+rather than the tests. If your build newly complains, that is the bug being shown to you: the
+fix is `IconElement`, or `as SVGElement` at a site you know is not a composite.
+
+### The test suite is type-checked now (#73)
+
+`tsconfig.json` excludes `*.test.ts` — right for emit, and it meant nothing ever compiled them.
+**48 errors had accumulated unseen** (the issue counted 40 when it was filed; it grows).
+`tsconfig.tests.json` plus a CI step brings it to zero and holds it there.
+
+The icons defect above is what that gate found on its first run. Two test files carried
+duplicate imports — `sessionCookie` and `nodePath` — which is invalid ESM that the runtime
+tolerated and nothing checked. The other 46 were genuine test-side noise, fixed honestly
+rather than with blanket `any`.
+
+A type-level test asserts nothing if nothing compiles it — which was already the argument for
+`typecheck-guards`, applied to everything else.
+
+### The test lane itself, honestly
+
+Three things the pre-release review found in the tests rather than in the code, recorded
+because a suite that is quietly wrong is worse than one that is loudly red.
+
+**Six tests were deleted and the suite stayed green.** Adding the #139 cases to
+`insert-examples.test.ts`, `cat >` was used instead of `cat >>`, wiping two `describe` blocks
+that covered still-shipping behaviour — grouping across a baked `<script>`, and fenced
+execution modes. Nothing complained, because fewer tests all passed. That is the exact shape of
+a coverage regression no gate catches: green is not a measurement of how much you asked. The
+blocks are restored, and the #139 cases rewritten against the same stub creator the originals
+used.
+
+**`ENOENT reading "https://esm.sh/typescript@5"` during `bun test`** came from the same
+rewrite: the real `liveExample` transpiled a `ts` fence, and the rejection leaked across test
+files, printing under an unrelated file's header. Zero occurrences now — and worth noting that
+the message named a URL while claiming `ENOENT`, which is why it read as noise for as long as
+it did.
+
+**`caddy-install.test.ts` was flaky about one run in ten.** Each of its tests cold-starts a
+real `bun` to exercise the generated remote script, so its cost is interpreter startup — ~1.2s
+each, with the file swinging 3.5s to 10.1s under load. Under bun's 5s default that put single
+tests over the line whenever the machine was busy. They now carry a 20s budget that describes
+the work; a test exceeding *that* is a real defect rather than machine load.
+
+### Every bin answers `--help`, and refuses what it does not understand (#85)
+
+`caddy-install`, `deploy-preview`, `tunnel` and `release-notes` each carried their own
+`flag()`/`has()` pair. One shared `parseArgv` replaces all four.
+
+**Refusing unknown flags is the load-bearing part.** `tosijs-caddy-install --status` — a flag it
+never had — used to read as "no flags at all", and the bin went on to ssh into the configured
+host. The same shape was still live in `tosijs-deploy`. A tool that contacts a machine must not
+read an instruction it does not understand as consent to proceed.
+
+`--help` comes with it, and is parsed **before** the site config is read, so it works from any
+directory. That matters because no lane runs a shipped bin's argument handling —
+`smoke-consumer.ts` checks shebangs and deliberately does not execute the bins that reach the
+network — so `tosijs-release-notes --help` shipped unrecognised and died on a raw `ShellError`
+outside a git repo.
+
+Also: `deploy:index` now asks for `PREVIEW_HOST` like the bins, instead of the `PREVIEW_SSH`
+they moved off.
+
+### Magic-link codes are eight letters, no digits (#132)
+
+```
+🔗 code:  JCYGCCVX   (case-insensitive)
+```
+
+The code is typed by hand into a floating keyboard on a headset. Crockford base32 was already
+chosen for typo-resistance and that was right as far as it went — but it contained **digits**,
+and on a headset the letter↔number switch is a trip to a different keyboard page. A reported XR
+session minted `A70MDCD` and `X9Q3Z53`: three digits each in seven characters, so three round
+trips for a code being gaze-and-pinched one glyph at a time.
+
+**The extra character is free; the mode switch is not.** Eight letters of a 22-letter alphabet
+is **35.7 bits against the old seven-of-32's 35.0** — slightly _stronger_, while never leaving
+the alphabetic keyboard.
+
+`I`, `L`, `O` and `U` stay excluded. `I`/`L` are indistinguishable across case, which matters
+_more_ now that there are no digits, because the code is case-insensitive so the reader cannot
+use case to tell them apart. Redemption also maps back the digits someone might type for a
+letter they misread (`5`→`S`, `2`→`Z`, `8`→`B`, `6`→`G`) — pure upside, since a digit can never
+be part of a real code — and ignores hyphens and spaces.
+
+Rate limiting is unchanged and still does the heavy lifting: redemption is serialized at ~10
+attempts/second, so 22⁸ takes ~174 years to exhaust and a five-minute window is about 1 in 18
+million.
+
+`dev-auth.ts` itself went on arguing from **32⁷** — ~111 years, 1 in 11 million — for the whole
+of the change that made the token 22⁸. The conclusion never stopped holding, which is precisely
+why nothing surfaced it: a safety argument that survives its own premises being replaced is not
+being read. The figures are corrected in place, with the superseded ones kept beside them, since
+this is the one file where the numbers *are* the argument rather than a description of it.
+
+The invite page's code box (shipped for #75) covers most of the rest of the ask: bookmark the
+host once, then each session is eight letters into a text field. The `dev.tosijs.net/<code>`
+short URL needs host-side infrastructure and is tracked in `TODO.md`.
+
+### BREAKING (narrow): the root barrel no longer re-exports the doc system (#133)
+
+`import { … } from 'tosijs-ui'` no longer gives you `code-editor`, `doc-browser`,
+`doc-system/doc-system` or `live-example`. **Import them by subpath instead** — they were
+already reachable that way, and nothing else changes:
+
+```typescript
+import { tosiCode } from 'tosijs-ui/code-editor'
+import { createDocBrowser } from 'tosijs-ui/doc-browser'
+```
+
+**Why.** `code-editor` pulls CodeMirror; `live-example` and `doc-system/doc-system` each pull
+`tjs-lang` independently. This package has no `sideEffects` field — correctly, since
+`elementCreator()` registers elements at import time and a blanket `sideEffects: false` shakes
+a bare `import 'tosijs-ui'` down to zero registrations — so a bundler must treat every
+`export *` target as side-effectful and cannot drop it. All four were therefore eager in any
+app that imported _anything_ from the barrel.
+
+Measured by snowfox-app moving a 15MB React bundle to the bun bundler, and reproduced here:
+
+|                         | size                                 |
+| ----------------------- | ------------------------------------ |
+| barrel as shipped       | 1.68 MB                              |
+| barrel without the four | 0.38 MB                              |
+| real app bundle         | 15.21 → 13.86 MB (**1.35 MB, 8.9%**) |
+
+The doc cluster was **77% of the barrel**. For contrast the 3D, map and lottie components —
+the ones you would expect to be the heavy tail — cost about 10kB, because they already
+lazy-load properly.
+
+The doc site and CDN `<script>` users are unaffected: `index-iife.ts` imports all four
+explicitly, so the weight lands on the bundle built _for_ the doc site rather than on an app
+that imports a button.
+
+### New: `tosijs-ui/codemirror` — extend `<tosi-code>.editor` without a silent no-op (#131)
+
+`<tosi-code>` exposes the raw `EditorView` and the 1.7 notes invite you to configure CodeMirror
+through it. But CodeMirror 6 keys facets, `StateField`s and gutters by **object identity**, so
+an extension built from a _second copy_ of `@codemirror/state` or `@codemirror/view` is not
+mismatched — it is **silently ignored**. No error, no warning; the gutter never renders.
+
+Reported with a real repro: a consumer's `@codemirror/view` resolved to `6.43.6` while ours
+hoisted to a nested `6.43.10`, so their `gutter()` and `GutterMarker` came from a different
+instance than the view. `@codemirror/state` happened to dedupe, which made it worse — enough
+worked that the failure looked like a bug in their gutter code.
+
+```typescript
+import { gutter, GutterMarker, StateField, StateEffect } from 'tosijs-ui/codemirror'
+```
+
+Only `@codemirror/state` and `@codemirror/view` are re-exported — the two needed to extend a
+view, exactly as the report identified.
+
+**Why not peer dependencies**, which the issue proposed and is the obvious fix: a required peer
+would make every consumer install two CodeMirror packages including the overwhelming majority
+who never render an editor (`elementCreator()` registers eagerly, so importing tosijs-ui is not
+evidence of using it), and an _optional_ peer is worse than either — the component silently
+does nothing until you discover you needed 12 packages. Re-exporting removes the failure by
+construction rather than policing it: there is no version to match and no `overrides` to write,
+because there is only ever one copy.
+
+### `buildSite` no longer wipes `dist/` — it is your package output, not a site artifact (#130)
+
+The prebuild ran `rm -rf dist/` on **every** `buildSite`, including from `devServer` and
+including for projects that configure no library build at all. For the repos this API exists to
+serve, `dist/` is the **published package output** — an input to `npm publish` — so the wipe
+destroyed build products the current run does not rebuild.
+
+Reported from tosijs with the full chain: two bundles (`module.debug.js`, `module.safe.js`,
+exposed as the `./debug` and `./safe` subpath exports) are produced only under `--build`,
+because they need a 53-file transpile too slow for the dev loop. `bun start` — or Playwright's
+`webServer`, which runs it — wiped `dist/` and rebuilt five of seven. A publish from that tree
+ships two subpaths that throw `ERR_MODULE_NOT_FOUND`, and it reached a commit once already.
+Nothing local could catch it: size and smoke gates iterate the bundles the current run _built_,
+so a bundle that was **deleted rather than skipped** is invisible to all of them.
+
+The rule is now "clean only what you wholly generate":
+
+| configuration                                                  | `dist/` cleaned? |
+| -------------------------------------------------------------- | ---------------- |
+| `emitLibrary` / `libraryTsconfig` (tsc emits the complete set) | yes              |
+| `libraryBuild` — a consumer function that may emit a subset    | **no**           |
+| none configured — nothing here owns it                         | **no**           |
+
+The doc `outputDir` wipe is unchanged and stays: that directory is wholly generated, and the
+build announces it. `dist/` is different.
+
+Incidental: `emitLibrary` runs `tsc --incremental`, whose `.tsbuildinfo` lives in `dist/`.
+Wiping it every run meant incremental compilation had never once done anything.
+
+### `bun start` serves in ~3.6s instead of ~23s, and prints 13 lines instead of 37
+
+**20.1 of those 23 seconds were the dependency audit**, running synchronously before the port
+was bound — where it hit its own 20s timeout, gave up, and **failed open**. So the stall
+bought nothing on that run: it was the cost of a check that did not happen. Measured against
+the live registry, `bun audit` takes **79.5s**.
+
+The code justified blocking on the grounds that "the audit is sub-second… a gate you wait for
+cannot be raced". The premise was false, so the conclusion was buying a twenty-second stall on
+every start. It now runs after the server is up and reports when it lands, prefixed loudly
+enough that a late advisory cannot be mistaken for part of the startup banner — non-blocking
+must not mean easy to miss. **Release builds still block**: `buildSite` audits synchronously,
+and `--test` gates there too, which is where waiting is the right trade.
+
+**Build output is 13 lines, down from 37.** Eighteen of them were `bun build` listing every
+chunk and every sourcemap — the same size information the build already summarises, only
+longer. Captured now, and replayed **in full** on failure; verified by deliberately breaking
+the bundle entry, which still prints the errors, exits 1, and restores the last good build.
+
+Spam is not free: it trains people — and agents — to stop reading build output, which is
+exactly what lets a real failure through.
+
+The ePub was the assumed culprit and is innocent: 0.34s of the 23. Measuring first is the only
+reason the actual cause was found.
+
+### `docs.json` is cache-busted, so a stale corpus stops surviving a deploy
+
+Every generated URL went through the asset stamp — the stylesheet, the hydration bundle, the
+IIFE — **except the one that matters most**. `docs.json` is the entire corpus: nav, routes and
+every page's content, and it was emitted bare.
+
+A static host sends no `Cache-Control` for it, so browsers apply **heuristic** caching — free
+to invent a freshness lifetime when you decline to state one. The site then renders a previous
+deploy's corpus against the current bundle, and nothing in the console says so. It presents as
+pages that will not update, and the fix is a hard reload nobody thinks to try. It cost a
+maintainer a long debugging session before it was traced to a Chrome cache entry.
+
+The corpus gets **its own stamp**, hashed from `docs.json`'s own bytes rather than the project
+version. The version is right for the bundles — it moves once per release, which is when they
+change. The corpus does not work that way: it changes whenever anyone edits a doc, many times
+within one version, and a preview host redeployed mid-version is the normal way this project
+reads its own site. A version-keyed corpus URL would have been stale for exactly that workflow.
+
+The dev server was already correct here — it sends `no-store, must-revalidate` on everything,
+verified. This was only ever the built static site.
+
+### `<tosi-table>` stops silently capping at 10,000 rows (#82)
+
+`maxVisibleRows` defaulted to a flat `10000` and `slice`d everything past it **without a
+word**. A 25,000-row table showed 10,000, and every count, filter and sort then ran on the
+truncated set — self-consistent, and disagreeing with the data. The property was documented
+nowhere, so the only way to find it was to lose rows and go looking.
+
+The number was wrong because it was sized as a _rendering-cost_ limit. It is a **layout**
+limit. A virtual `listBinding` renders only the visible window, so the UI cost is O(1) in row
+count — 300,000 rows scroll like 300 — and the array size is irrelevant. What binds is the
+spacer element's height against the maximum height a browser will lay out.
+
+So the cap is now derived at runtime: `maxElementHeight / rowHeight`, which at the default
+30px rows is on the order of half a million to a million rows. **Probed, not hardcoded**,
+because the ceiling is engine- _and version_-specific — two Chromium measurements in this
+project sit a factor of two apart (Chrome 151 clamps at 16777214px, the Playwright Chromium
+at 33554428px). Any constant would be wrong for somebody, in the direction that loses rows.
+
+And when a cap does bite, it now **says so in the console** with both numbers and how to
+raise it. `rowHeight: 0` stays conservative on purpose: with no fixed row height there is no
+virtualisation, every row is a real DOM node, and the cost genuinely is O(n).
+
+Set `table.maxVisibleRows = n` to override, exactly as before.
+
+### A large `rowHeight: 0` table now complains, loudly (#84)
+
+`rowHeight: 0` turns virtualisation off — every row becomes a real DOM node, and sorting,
+filtering and group toggles walk all of them on every render. It is documented for "smaller
+tables, or tables with variable row-heights", and that is the only thing it is for.
+
+Past **1,000 rows** the table now warns **on every render** until a `rowHeight` is set. That
+is deliberate, and deliberately unlike every other notice in this codebase, which fire once:
+those describe states a developer may not be able to change, whereas this is a one-line fix
+that persists until made, and a single notice scrolls out of the console and is gone.
+
+The originally suggested fix was to binary-search the scroll-anchor walk. That was declined:
+it optimises a configuration nobody should be in, and makes a misconfiguration marginally
+less bad instead of surfacing it. A table big enough for the cost to matter is big enough to
+virtualise, and virtual tables are O(1) in row count.
+
+### `<tosi-3d>` is deprecated — use `tosijs-3d`
+
+Nothing breaks: it still works, still ships, and stays until a future major. But new work
+should use **[`tosijs-3d`](https://www.npmjs.com/package/tosijs-3d)**.
+
+It is a much better library, and maintaining both is duplicated effort spent against the
+weaker one. `<tosi-3d>` is a thin Babylon wrapper that grew inside a general-purpose UI
+library; `tosijs-3d` is a project actually about 3D and XR, with the declarative component
+set and XR support that implies. Every hour spent here is an hour not spent there, and the
+result would still be the lesser of the two.
+
+`tosijs-3d` grew out of this component, so migration is mostly a rename.
+
+The deprecation appears in three places, deliberately: the doc page (what people read), the
+`@deprecated` tags on `B3d`/`b3d` (what editors surface), and a console notice printed **once
+per page on first use** — not at import, since `elementCreator()` registers eagerly and a bare
+`import 'tosijs-ui'` is not evidence anyone is using this; and not per instance, because a page
+with several scenes would spam its own console, which is how a deprecation notice teaches
+people to filter warnings rather than act on them.
+
+### The machine-health guard now reports 13GB of orphans instead of skipping them (#93)
+
+`isDevProcess` decided what was even a _candidate_ for the runaway check, and excluded
+`build` — because we spawn the bundler ourselves and a build peaking mid-run must not look
+like a runaway to its own parent. But the exemption did not say "our bundler". It said
+**every `bun build` on the machine, forever, regardless of owner or age**, so an orphan whose
+parent died a week ago was exactly as exempt as one that started 200ms ago.
+
+Reported with measurements: **69 orphaned `bun build --watch` processes holding 13.09GB**, ~55
+of them spawned inside a single 61-minute window, on a 128GB box running these very dev servers
+and sitting at 116MB free. The guard looked, and skipped every one — while resting on the
+premise that "nothing noticed the runaways because nothing ever looked".
+
+`--watch` is the distinguishing signal, and it was right there in the argv: a watcher is a
+server whoever started it. The mid-rebuild false positive the exemption existed for is already
+handled, and handled _precisely_, by parentage — the assessor filters `process.pid` plus
+`descendantsOf(process.pid)` before assessing anything. That is the exact test where a
+subcommand name was a blunt proxy for it, so this costs no false positives. `bun run` with
+`--watch` is caught too; the reported machine had four such servers up to 18 days old.
+
+**Visible is not the same as caught**, and the first pass at this shipped the difference. Every
+trigger in the assessor asks "is _one_ process too big?", and 194MB is nowhere near any of them —
+so dropping the exemption walked the guard past all 69 orphans and returned `ok` for 13GB, while
+the note above claimed they had been dealt with. The assessor now carries a rule that never
+consults RSS: **a watcher whose parent is gone (`ppid` 1) is waste at any size**, reported with
+the `kill` command. One 12MB orphan warns. It warns rather than refuses, because a build that
+will not start because of someone's stray process is a guard people switch off.
+
+"A bunch of similar names" was the other candidate signal and is deliberately _not_ used: three
+identical `bun --watch bin/dev.ts` lines are usually three sibling projects each running their
+own server. Identical argv is not duplicate work — the distinguishing fact is the cwd, which
+`ps` does not report.
+
+**And the other half, in `doc-site-system.md`:** "shell out so the OS reclaims the memory on
+exit" is only true if the child _exits_. A `dev.ts` that spawns `bun build --watch`, itself run
+under `bun --watch dev.ts`, leaks one bundler per keystroke — the previous child is never
+signalled. The doc now carries the reaping idiom (kill the previous child; reap on
+`SIGINT`/`SIGTERM`/`beforeExit`) beside the advice that produced the leak. This project's own
+builds are one-shot and were never affected.
+
+### `layout: "full-screen"` finally gets its scroll container (#119)
+
+`.doc-content`'s `overflow` is an **inline** style set by the doc-browser, so the full-screen
+layout's stylesheet `overflow: auto` was competing with an inline style and always lost. The
+`height: 100%` landed and the scroller did not — a full-screen page taller than its box was
+clipped and unscrollable. It sat one line below a `padding` that correctly went through a
+variable, with a comment explaining exactly why it had to.
+
+Both now go through `--doc-content-overflow` (default `hidden`), on the inline style **and**
+the pre-hydration rule — they have to match, or an override would take effect only after
+hydration and the page would visibly change shape.
+
+The second consequence is the one worth knowing about: `overflow: hidden` on an ancestor
+kills `position: sticky` in its subtree, so a page wanting a sticky viewport-sized window
+inside the article previously needed `.doc-content { overflow: visible !important }`. An
+`!important` in a consumer's stylesheet is this component failing to offer a seam.
+
+### A page with tests says so, even when tests are off (#113)
+
+Tests default to on for localhost and off everywhere else, and when they are off the widget is
+hidden — so **a page with failing tests looked identical to a page with no tests**. There was
+an override, `localStorage['tosijs-ui-tests-enabled']`, but you had to know the key, which
+means you had to already suspect there was something to see.
+
+That bit hardest down the path we recommend: `tosijs-tunnel` necessarily serves from a
+non-localhost hostname, so the sanctioned way to view a dev site remotely is exactly where test
+state went invisible. A maintainer read a clean tunnelled page as "the failure must be
+localhost-specific" and lost the thread.
+
+The app menu now offers a **Tests** toggle — but only on a page that has tests, where it reads
+`Tests (N not run)` while they are off. `pageTestCount()` is exported from live-example for
+this: how many examples carry tests, regardless of whether tests are enabled — the number that
+lets a UI say a runner exists here without turning it on. A published page with no tests offers nothing, so the
+default stays as quiet as it should be. The default itself was never the problem; the silence
+was.
+
+### `/version.json` stops restamping a site that did not change (#122)
+
+`docs/` is committed here and in the sibling projects, and the stamp named
+`git rev-parse HEAD` — so **every commit's `version.json` named its own parent, forever**, and
+no build→commit cycle converged:
+
+```
+build at A → version.json says A
+commit     → B contains a version.json saying A
+rebuild    → version.json says B → dirty
+commit     → C contains a version.json saying B → …
+```
+
+`build-stamp.ts` already argued against a wall-clock stamp for exactly this reason and missed
+that the argument applies one level up: `HEAD` is not a clock, but in a repo that commits its
+own output it moves on the same cadence. Small, and it cost something real — a false positive
+on `git status` at the moment you are trying to confirm a release tree is clean, so it gets
+checked, re-checked, and eventually ignored.
+
+The fix is the reporter's: if nothing else in the output changed, leave the stamp alone. A new
+`contentHash` field records what the rest of the output hashed to, so the next build can tell
+"changed" from "unchanged" without keeping a copy of the old tree — though as it happens the
+previous build is still on disk (the build moves it aside as `<outputDir>.last-good` rather
+than deleting it, and drops it only on success), so the comparison costs no extra bookkeeping.
+
+Verified end-to-end, which is the only way to check a convergence claim: build → commit →
+rebuild now leaves a **clean tree**.
+
+The stamp is also more honest for it. It now names the last build that actually changed the
+site, rather than the last one that happened to run. **Deleting `version.json` still forces a
+fresh stamp** — the escape hatch for re-identifying an unchanged build, at no extra flag.
+
+### `describeHolder(null)` says nothing is building (#123)
+
+`describeHolder(currentHolder(root))` is the natural spelling, and `currentHolder` returns
+`null` whenever nothing holds the lock — the ordinary, healthy case. It rendered the alarm
+template with the fields unfilled (`pid undefined … building in undefined`), reporting a scary
+problem that did not exist, in a reader whose whole purpose is answering "who holds this?".
+
 ## 1.13.0
 
 ### tosijs `^1.9.1` — and a console with nothing in it