tosijs-ui 1.14.3 → 1.15.0

package/CHANGELOG.md

@@ -1,5 +1,711 @@
 # Changelog
 
+## 1.15.0
+
+### `save-to-source` wrote edits into the wrong fence, silently
+
+Found by this release's own pre-release review, and it is caused by a feature this release
+introduces — so it could not have shipped ahead of `:static`, and `:static` must not ship
+ahead of it.
+
+`example-policy.ts` was added this cycle as **the one rule** for "does this fence become a
+live example", and `insert-examples` was converted to it. Its structural twin was not:
+`save-to-source` kept a flat six-language set *and* its own fence-info regex that captured the
+language as `[\w-]*` — which stops at the colon, so `js:static` read as plain `js` and the
+mode was invisible there while being load-bearing everywhere else.
+
+Example ordinals are a **shared coordinate system** between those two modules. They agree only
+if both ask the same question, and after `:static` they did not: every ordinal following a
+display-only fence pointed one group too far, so editing an example saved over a *different*
+block. Silently — the "couldn't locate this example" guard only fires on an out-of-range
+ordinal, and here a group existed at that index, just the wrong one. Under `liveExamples:
+'opt-in'`, which is the prose and book setting, every ordinal on the page shifts.
+
+Fixed at the class rather than the instance: `parseFenceInfo` now joins `isLiveFence` in
+`example-policy.ts`, `render.ts` uses it instead of its own inline copy, and `save-to-source`
+groups with `isLiveFence` and takes the policy from the caller. There is one parser and one
+predicate; a third divergence has nowhere to live.
+
+Mutation-verified — restoring either half of the old behaviour turns the regression tests red.
+
+### `<tosi-table>` was silently capped at 10,000 rows in Firefox
+
+Found by the release gate, and pre-existing — it fails identically at v1.14.3, verified in a
+worktree rather than assumed.
+
+`probeMaxElementHeight` asks for a 1e9-pixel element and measures what the engine gives back,
+on the stated reasoning that *"every engine tried clamps it"*. Firefox does not: above its
+ceiling it returns **0**, which is indistinguishable here from "no layout to probe". So
+`derivedMaxVisibleRows` fell back to the flat 10,000 that #82 exists to replace — on every
+Firefox page, silently, while the feature reported working everywhere else. Measured:
+
+```
+1e9 → 0      1e8 → 0      1e7 → 10000000      1e6 → 1000000
+```
+
+The probe now halves until the element lays out, which converges on the real ceiling within a
+factor of two on any engine, clamping or not, in at most a dozen forced layouts — once per
+page and cached. Result:
+
+| engine | before | after |
+| --- | ---: | ---: |
+| Firefox | 10,000 rows | **520,833** |
+| Chromium | 1,118,480 | 1,118,480 |
+| WebKit | 1,118,480 | 1,118,480 |
+
+The test had reimplemented the probe inline — the same single ask, carrying the same wrong
+assumption — so it was testing a copy rather than the component. It now calls the shipped
+function, which is why it caught this at all once the real one was fixed.
+
+**Why it hid for so long:** CI runs Chromium only, and the fallback is graceful. Nothing was
+broken, just quietly 52× smaller.
+
+### Guards that could not fail, and a scope that was never stated
+
+- **`theme.codeBg` was unguarded.** The WCAG contrast test hardcoded `#fdfdfd`, so it could
+  not see the public knob at all — with `codeBg: '#1e1e1e'` the worst light-mode token measures
+  **1.71:1** against AA's 4.5, all eleven light rules fail and all eleven dark ones too, and
+  the test stayed green throughout. It now reads the background out of the spec, so it asserts
+  against what ships. The limit is also stated rather than implied: the palette is eleven fixed,
+  contrast-checked literals and **does not track `codeBg`** — override it and you own the
+  contrast (retheme the tokens via the `--token-*` variables). There is now a test asserting
+  that limit, so a change in scope has to be a deliberate edit rather than a silent one.
+- **The `checkExamples` process boundary had no test.** The example policy crosses it through
+  `TOSI_LIVE_EXAMPLES`, and every build we run sends `'auto'` — so `'opt-in'` had never crossed
+  a process boundary anywhere, which is precisely where the earlier M2 defect lived. Now covered
+  by an integration test that spawns the CLI: the env key, the clean-JSON stdout contract, and
+  the default. Mutation-verified against a child that ignores the env value.
+- **The Print path changed twice in one cycle with no test at any tier.** Extracted as
+  `printWhenReady` and covered: an already-`complete` window prints without waiting for a `load`
+  that will never fire again, a loading one waits, a failing highlight still prints (plain code
+  beats a dialog that never opens), and highlighting happens *before* print rather than racing
+  it.
+
+### The cache-busting stamp no longer skips an asset in silence
+
+`?v=` is computed by hashing the assets it guards, and the loop `continue`d past a missing
+input without a word. That is how `doc-system.css` came to be **named in the inputs and never
+hashed** for the life of the feature: the stylesheet was generated ~80 lines later in a
+~1270-line function. Measured at the time — the `?v=` on every page equalled
+sha256(hydrate.js + iife.js) exactly. A `theme`-only change, which reaches the CSS generator as
+argv and never enters a bundle, therefore deployed new CSS under an **unchanged URL** and
+returning visitors kept the old stylesheet.
+
+The previous fix was to move one statement earlier, with nothing asserting the ordering — so
+the same reorder could undo it and every lane would stay green. `computeAssetStamp` is now its
+own module: a named-but-missing input is reported with the file and the consequence, and the
+properties are unit-tested (changing any input moves the stamp; an unchanged rebuild does not;
+the fallback is used only when nothing exists). Verified end to end — the `?v=` in the built
+site equals sha256 of all three assets.
+
+### One `language-*` pattern, not five
+
+The class pattern was written `[A-Za-z0-9_+#-]+` four times in `highlight.ts` and `[\w-]+` once
+in `epub.ts`, so a `c++` or `c#` fence was a language to one pass over a document and plain `c`
+to another. Hoisted into `langOfClass`, with `+` and `#` in the character class deliberately —
+they are real language names. Mutation-verified against the narrower spelling.
+
+### Corrections to the `registerGrammar` surface, before anyone builds on it
+
+tjs-lang is writing a TJS Prism grammar against this API (#155), so the companion pieces
+mattered more than their severity suggested.
+
+- **`grammarFor` contradicted `highlight()` on registered languages.** It consulted the alias
+  table only, so after `registerGrammar('tjs', …)` — the one thing a language author does — it
+  still answered `javascript` while `highlight()` correctly used the supplied grammar. It is
+  now registration-aware, and documented as returning a grammar *name*.
+- **A false guarantee about print.** The docs said a registered grammar reaches "the
+  pre-rendered page, the ePub **and print**". The first two are true; print is not. The
+  registry is module state in the *build* process and only `__TOSI_EXAMPLE_POLICY` is stamped
+  into the page — so a hard-loaded page is correct (the tokens are already in the HTML) while
+  client-side navigation and the in-app Print path re-highlight with an empty registry and fall
+  back to `javascript`. Now stated plainly, with the workaround (an ESM consumer can register
+  in their `bundleEntry` too) and the remaining gap (a CDN `<script>` consumer cannot).
+- **Two exported types named `ExamplePolicy`** with different value sets — `'auto' | 'opt-in'`
+  and `'auto' | 'opt-in' | 'none'` — both reachable through the `./*` wildcard, so which one
+  you got depended on the import path. One type now, with `SiteExamplePolicy` expressing the
+  site-valid subset as `Exclude<ExamplePolicy, 'none'>` rather than as a second declaration
+  that can drift.
+
+### The doc-system registration guard reported green on an inert bundle (#159)
+
+`bundleRegistrations` tested `bundleSource.includes('tosi-doc-system')` and its own
+documentation called that *"the one case where grepping a bundle is sound"*. It is not. The tag
+being present is **necessary and not sufficient**, and our own documented API supplies the
+counter-example: the context-map loop `document.querySelectorAll('tosi-doc-system')` puts the
+string into a bundle that registers nothing. The reporter's build reported healthy with exactly
+one `customElements.define` in it, none of it the doc system — and the caller then fell through
+to warn about a *different* component, pointing them away from the defect.
+
+The obvious repair is wrong in the other direction, and is worth recording because it looks
+right: matching `define(` beside the quoted tag **false-negatives on our own bundle**.
+`elementCreator()` registers with a variable, so the minified output reads
+`customElements.define(i,this,r)` while the literal sits in a `closest()` call and some CSS
+selectors, nowhere near a `define`.
+
+It now looks for evidence of a registration by either route — `preferredTagName="<tag>"` (the
+tosijs path, verified to survive minification in both `dist/iife.js` and a built `hydrate.js`)
+or `define("<tag>"` (a direct call). Checked in both directions against real bundles and
+against the #159 reproduction. The false soundness claim is gone from the shipped `.d.ts`; what
+replaces it says plainly that this is a heuristic which now fails closed on the reported shape,
+rather than claiming to be sound.
+
+### tosijs-ui no longer steals a `Prism` the page already owns
+
+Prism is a free-global library — its grammar files register against `window.Prism` at load
+time — so load order decides who owns it and neither side is told. We were importing our copy
+over the top of a host's. Reproduced rather than reasoned about, with a host Prism carrying one
+custom language and one plugin:
+
+```
+ensureGrammar(rust)           = true
+globalThis.Prism is host?     = false
+host custom lang reachable?   = false
+host plugins reachable?       = false
+host object itself intact?    = true     ← their captured reference points at an orphan
+we leaked manual onto global? = true
+```
+
+Nothing errored. Their languages and plugins were simply unreachable, and anything they had
+captured addressed an orphan. The `manual` leak is the worse half: Prism reads that flag at
+load, so a host Prism core loading *after* us computed `manual === true` and **silently never
+ran `highlightAll()`** — us breaking their page, not merely losing a global.
+
+Now: we **adopt** a host instance when one exists, never write `manual` onto an instance we did
+not create, and restore the prior global if our own import fails. Every line of that
+reproduction flips. Mutation-verified — deleting the adopt branch or leaking `manual` each
+turns the tests red.
+
+This is the #131 hazard class (`@codemirror/state` identity) in a worse container. That one got
+a real remedy — `tosijs-ui/codemirror`, a re-export so only one copy exists — and this one still
+has no equivalent: `registerGrammar` supplies grammars, not instance access. The harm is fixed;
+the asymmetry is recorded in `UPSTREAM.md` and `TODO.md`.
+
+The adopter reference states that a page which brought no Prism of its own ends up with ours,
+and that loading your own afterwards wins and stops our highlighting — that is Prism's model,
+not something we can fix from here. Load yours first, or use `registerGrammar` to add a
+language to ours instead of bringing a second copy.
+
+### Published-surface corrections
+
+- **`bundleEntry` lost its documentation in the emitted `.d.ts`.** `liveExamples` was added
+  between that field's JSDoc and the field itself, and TypeScript attaches a doc comment to
+  whatever declaration follows it — so `bundleEntry?: string;` shipped with no comment at all,
+  taking the #145 warning with it (the one explaining why omitting the doc-system import gives
+  you a site that serves 200s and shows nothing). Reordered, and guarded by a test that reads
+  the **emitted** `.d.ts` rather than the source, because the source looked fine throughout.
+- **`<tosi-table>`'s selection docs described pre-1.15 behaviour**, calling `selectRow` /
+  `selectRows` internals "documented because they may as well be". They are now a supported
+  surface that enforces cardinality and fires `selectionChanged` — and the published page said
+  neither. It now also carries the feedback-loop guard `<tosi-crud>` needed, since any consumer
+  that both drives and observes selection will hit the same thing.
+- **The README understated the iife by 21%** — "~385KB gzip" against a measured 468KB — and
+  named CodeMirror as the only contributor. Prism and its 27 grammars (+31.8KB) are the second,
+  with the same cause and the same remedy.
+
+### `<tosi-highlight>` renders in colour anywhere, not only inside a doc site
+
+The component shipped without the palette it needs. This package contains **no CSS files at
+all** — every style is a `StyleSheet()` call — and the `.token.*` rules lived inside the
+doc-system stylesheet. So a `<tosi-highlight>` on an ordinary page produced perfectly correct
+`<span class="token …">` markup and rendered it in flat black: 17 token spans, every one
+computing to `rgb(0,0,0)`. That is the single thing the component exists to do.
+
+The doc block compounded it by telling you to "import the doc-system CSS" — naming an import
+that did not exist.
+
+The palette now lives in `doc-system/highlight-styles.ts` as an exported `highlightStyleSpec`,
+the doc-system spreads that one copy rather than holding its own, and the element **injects it
+on first use** — so the standalone case needs no import and no configuration. Every colour is
+still a `varDefault`, so `:root { --token-keyword: rebeccapurple }` retunes one token type
+without touching the rest.
+
+> Writing the test for this found a second defect before it shipped: `StyleSheet()` does not
+> dedupe by id on its own, and `render()` runs many times per element, so the first version
+> injected a `<style>` per render — nine in a single test file. It now carries the same
+> module-level guard as `ensureTooltipStyles`.
+
+### Every "Run this example live" link in an `opt-in` book was dead
+
+The ePub generator carried a **third** verbatim copy of the six-language set and
+re-implemented example grouping without consulting `isLiveFence` or `config.liveExamples`.
+
+The consequence landed hardest on exactly the people who build ePubs. Under
+`liveExamples: 'opt-in'` — the setting the config docs recommend for book and prose sites —
+the page produces no live examples at all, while the book went on injecting "▶ Run this example
+live ↗" links to every one of them. Every link in the shipped book pointed at an anchor that
+does not exist. With a single `:static` fence the ordinals also slid, so `#example-3` addressed
+a block the page never anchored.
+
+A book is the medium where a broken link cannot be corrected after publication, which is what
+moved this from a note to a fix.
+
+The ePub now uses the same predicate and the site's own policy, and reads the `:mode` off the
+`<pre>` exactly where `insertExamples` reads it. Its language-class pattern also matched
+`[\w-]+` while the highlighter matched `[A-Za-z0-9_+#-]+`, so a `c++` or `c#` fence was read
+differently by the two; both now use the wider one.
+
+The existing test asserted only that the link class was present. It now builds a chapter with a
+`:static` fence ahead of a live one and asserts there is exactly **one** link and no
+`#example-2`. Mutation-verified.
+
+### A gitignored file shipped to npm, and no repo-reading check could have seen it
+
+1.14.2's tarball contained `dist/.metadata_never_index` — a zero-byte macOS Spotlight marker
+that is gitignored and untracked. Harmless in itself. The mechanism is not.
+
+`files` includes `/dist` wholesale, and **when `files` is present npm consults neither
+`.gitignore` nor `.npmignore`** for the paths it selects. So anything sitting in `dist/` ships,
+and being gitignored makes it *less* visible rather than more: every guard that reads the repo
+is blind to it by construction. A stray debug dump or a scratch `.env` would ship exactly as
+readily.
+
+Verified the hard way — an `.npmignore` naming the file was added first and changed nothing,
+so there is no declarative fix and the config line was removed again. `bin/smoke-consumer.ts`
+now asserts on the **packed listing**, the only place the truth exists, and fails on
+`.DS_Store`, Spotlight markers, `.env*` and debug logs.
+
+Found by diffing the published tarball against the tag — the post-publish check that reads the
+artifact instead of the repo. All 871 built files were byte-identical; this was the only delta.
+
+Also removed: **`bin/dist/`**, 1.6MB of tracked build output last rebuilt in August, not in
+`files`, and referenced by nothing. `reviews-1.11-pass2.md` flagged it — and the identical
+Spotlight marker inside it — two releases ago and left the box unticked. Every clone was paying
+for it, and anyone grepping for `iife.js` found a stale copy.
+
+### tjs-lang 0.13.13 (#135) — **already shipped in 1.14.3**
+
+Carried here so a 1.13.x upgrader gets it too. Full notes under 1.14.3 below: on tjs-lang
+<=0.13.11 a `test '…' { … }` inside a quoted string executed at transpile time, in the host
+page, outside the iframe sandbox. If you are on 1.14.3 you already have this.
+
+### Share a link with a PERSON: `tosijs-tunnel --link --share`
+
+The magic link was tuned for **device** handoff — you read a seven-character code off one
+screen and type it into the headset in your hands, seconds later, and you want to edit. Five
+minutes is right for that, and the short window is exactly what pays for a token short enough
+to type.
+
+**Human** handoff is a different shape and had nothing. You text a URL to a colleague, she
+opens it after her next meeting, and she gets a dead link — which reads as *your feature is
+broken*, not *your link expired*. The alternative, in one real case, was building a Tauri app
+and shipping her an installer so she could look at something.
+
+```bash
+tosijs-tunnel --link --share                 # read-only, 24 hours
+tosijs-tunnel --link --share --share-ttl=120 # …or two
+```
+
+A share link is **read-only** — it browses and cannot save source — and that capability is
+what makes the long life safe. It is deliberately **one flag rather than `--ttl` plus
+`--read-only`**: two orthogonal knobs would let you construct a week-long *write-capable*
+token sitting in a chat log, and nothing would stop you. For the same reason, raising
+`linkTtlMinutes` is not the answer; that produces a long link that can still write.
+
+The session it mints is narrowed to match and expires after **7 days** instead of the usual 30
+— it belongs to someone else, so its horizon should be the demo rather than your dev server's
+uptime. `--share-ttl` is capped there, because past it the link would outlive the credential it
+can hand over. Share links also ignore `linkPolicy: 'single-use'`: a texted link gets opened
+when the recipient gets to it, sometimes twice, sometimes after being forwarded — and spending
+it on first redemption is the friction that led an adopter to replace the mechanism with a
+permanent token of their own.
+
+**New in the security surface, since this is a dev-tooling path people audit.** Read-only
+sessions are the mechanism: `AuthState` gains a `readOnly` set marking a token, `redeemLink`
+carries the capability from link to session, and `sessionMayWrite` / `cookieMayWrite` answer
+it. `mayWriteSource` gains an optional `sessionMayWrite` — **optional, defaulting to
+permissive**, so every existing three-field caller behaves exactly as before; a narrowing that
+defaulted the other way would have silently disabled editing for everyone. Also exported:
+`resolveShareTtlMs`, `READONLY_SESSION_TTL_MS`, `SHARE_LINK_TTL_MS`. The loopback-listener rule
+that decides what counts as remote is untouched.
+
+Configurable as `tunnel.shareTtlMinutes` (default 1440). Nothing about the existing edit link
+changes: still 5 minutes, still write-capable, and `mayWriteSource` treats an omitted
+capability as permissive so no existing caller behaves differently.
+
+It still fronts the running dev server, so it needs your machine on. For a demo that has to
+survive your laptop sleeping, use the static preview.
+
+### `import 'tosijs-ui/doc-browser'` defines `<tosi-doc-system>` (#158, #159) — **already shipped in 1.14.2**
+
+Carried here so a 1.13.x upgrader gets it too. Full notes under 1.14.2 below. If you are on
+1.14.2 or later you already have this.
+
+### Client-side navigation lost syntax highlighting on an `opt-in` site
+
+The doc-browser called `highlightBlocks` without a policy, so the new `isLiveFence` filter
+defaulted to `'auto'` and skipped all six executable languages — leaving them for a live
+example that an `opt-in` site never creates. Measured on client-side navigation: **531
+highlighted tokens down to 23.**
+
+The symptom lands on exactly the audience `liveExamples: 'opt-in'` exists for — prose and book
+sites, where nearly every fence is illustration. It now passes `examplePolicy()`, the same
+global `insertExamples` reads, so the two cannot disagree.
+
+### Print waited on a fixed timer instead of `load`
+
+`autoPrint: true` used to inject a `load` wait; switching it off so the page could be
+highlighted first dropped the wait with it, and printing raced the render. Restored.
+
+### `<tosi-schema-form>`: non-conforming data is documented, not silently absorbed (#162)
+
+The form is an editor, not a gate — a value that violates the schema is rendered, validated on
+load and marked, never coerced, stripped or refused. That is deliberate, and it is now written
+down, along with why there is no built-in save gate: with no validator registered `validate()`
+returns `true`, so a gate here would open silently for every consumer who never installed one,
+which reads as enforcement while enforcing nothing.
+
+Three known limitations are documented with it, because the value is preserved but **cannot be
+seen**: a value the typed control cannot hold renders empty (`age: "abc"` in a `number` input),
+a union value matching no branch renders no fields at all, and an error whose path has no
+rendered field is invisible while `validate()` returns `false`. Tracked as #162; the fix is a
+panel listing what could not be displayed.
+
+### `bun format` was red on two lint errors no gate ever ran
+
+CI runs `format-check`, which is **prettier only** — so the ESLint half of `bun format`, the
+command the docs tell you to run before committing, had gone red without failing anything.
+Two errors in `audit-guard.ts` (a dead initializer and a `require()`), both fixed. Worth
+knowing the shape: a documented command and the gate that checks it were not the same command.
+
+The annotation gate had the mirror-image problem, and it is worth recording for anyone using
+`tosijs-release-notes`: the commit that wrote up the last batch left `release-check` missing
+three more, because a write-up is itself an annotation. Two were real user-visible fixes,
+written up above. The third was internal and should have carried `[note]` — which is exactly
+what CLAUDE.md means by "the last commit before `git tag` must carry only `[note]` bullets, or
+the loop does not terminate."
+
+### ePub NCX `playOrder` was duplicated and non-monotonic
+
+`playOrder` is the NCX's **linear reading position**, and the spec requires it unique and
+increasing — readers use it for "next chapter" and progress. It was read inside a template
+literal *after* the recursive child call had already advanced the shared counter, so every
+parent inherited its deepest descendant's number.
+
+Our own ePub shipped **4 duplicate values across 72 navPoints**, with a sequence that went
+backwards. A four-level section collapsed all four onto one value.
+
+`id` was always correct, because it captured `++counter.n` into a const. `playOrder` now does
+the same, which is the whole fix.
+
+Found by checking whether the nav system supports a parent with a parent — it does, at every
+level (model, static HTML, hydrated nav, EPUB3 `nav.xhtml`, NCX, and the CSS indentation),
+and refreshing a deeply nested page discloses every ancestor correctly. A flat corpus cannot
+reproduce this defect, which is why it shipped.
+
+### `<tosi-table>`'s selection API agrees with clicking, and notifies (#157)
+
+`selectRow`/`selectRows` stamped the selection key with no reference to the table's mode,
+while the click path enforces it three separate ways. So `selectRows([a, b, c], true)` on a
+single-select table left **three rows selected** — a state no amount of clicking can produce —
+and neither method fired `selectionChanged`, so a consumer keeping its own UI in step silently
+missed every programmatic selection. Including "restore selection after a data refresh", which
+is what these methods are documented for.
+
+Both now enforce cardinality and notify exactly once. Selecting in single-select mode
+**replaces**, exactly as a plain click does, and warns if handed more than one row rather than
+silently dropping the rest.
+
+**Narrower than the issue proposed, and deliberately.** `multiple` is a data-model invariant
+and is enforced; `select` is not, because it governs what the *user* may do rather than what
+the *program* may do. Gating on it broke legitimate headless use — including this component's
+own pinned-row example, which selects a totals row on a table that never enables clicking.
+Cardinality is the invariant the report is really about, and `multiple` covers it alone.
+
+Deselection is never gated: it can only reduce a selection, and refusing it would strand rows
+selected before the mode changed with no way to clear them.
+
+The click path keeps notifying once per interaction by composing a private non-notifying
+primitive — a plain click deselects everything and then selects one, so a notifying public API
+called from inside would fire several times per click.
+
+**`<tosi-crud>` needed a guard for the new notification**, and the shape is worth knowing if
+you drive a table programmatically: it both drives and observes the selection, so its own
+`deSelect()`/`selectRow()` sync now called back into its handler — the deselect half reporting
+an empty selection, which cleared the current record mid-edit. A component that writes and
+watches the same state has to be able to tell its own writes from the user's.
+
+### `registerGrammar` — a language can supply its own Prism definition (#155)
+
+Our alias table maps fence names onto Prism's built-in grammars, which is the wrong seam for a
+language that ships its own. tjs-lang is generating a TJS definition from the same source that
+already emits their TextMate grammars; hardcoding it here would put their grammar behind our
+release cadence.
+
+```js
+import { registerGrammar } from 'tosijs-ui/site'
+import { tjsGrammar } from 'tjs-lang/prism'
+registerGrammar('tjs', tjsGrammar)
+```
+
+Registered grammars win over the alias table, install under the **fence** name (so the class
+stays `language-tjs` for a theme to target), and are used by the **build-time** pass — so they
+reach the pre-rendered page, the ePub and print, not just a hydrated browser tab.
+
+That last part is the whole point, and it is their argument rather than mine: a wrong token
+colour is cosmetic on the web and permanent in a printed book. TJS's colon examples
+(`greet(name: 'Alice')`) are *values*; rendered with TypeScript's type colour, the page
+visually asserts the exact misreading the document exists to correct.
+
+### `popstate` no longer re-renders on a hash-only change (#152)
+
+Setting `location.hash` is a fragment navigation, and per spec it fires `popstate` before
+`hashchange` — so any component keeping state in the hash re-mounted the entire article on
+every write, destroying and re-creating every live example on the page. An editor lost focus
+and its buffer mid-keystroke. The handler now compares the resolved filename and only scrolls
+when the document is unchanged.
+
+### No rule redefines a global palette token (#150)
+
+`button, select, .clickable` and `pre, code` each set
+`--text-color: var(--brand-color)` — redefining the token the whole palette derives from
+(`--tosi-text: var(--text-color)`) on an *element* selector. From any button downward it
+stopped meaning "the theme's text colour".
+
+That reaches into anything embedded: an editor deriving its chrome from the page resolved
+correctly in the document and to the brand colour on its own slotted toolbar buttons — oklab
+L≈0.27 against an L 0.16 bar in dark mode, unreadable, with correct body text beside it. The
+`pre, code` instance also put every syntax-highlighting token span in a poisoned palette.
+
+Both now set `color`. A test encodes the distinction rather than an allowlist: a rule may
+redefine the token **only if it owns a background** — `header` is brand-coloured, so its
+contents genuinely need the matching text colour and should inherit it. A rule that only wants
+to colour itself sets `color`.
+
+### Packaging and API corrections
+
+**`tosijs-ui/highlight-block` resolves under every condition.** It shipped as the only named
+subpath without a `default` export condition — its ten siblings all had one. An exact key beats
+the `./*` wildcard and *errors* (`ERR_PACKAGE_PATH_NOT_EXPORTED`) rather than falling through,
+so a resolver under `['require','default']` — Jest's default, a CJS-targeting webpack/rollup
+build, Vite SSR externalisation — hard-failed on that one subpath while `tosijs-ui/diff` beside
+it resolved. `bun run test-consumer` now asserts **structurally** that every named subpath
+carries `types` + `import` + `default`.
+
+**`prismjs` is a real dependency, not an optional peer.** It first shipped declared *only* as
+a devDependency while `dist/doc-system/highlight.js` imported it, so an adopter's build
+resolved it by hoisting luck — and without it their doc site, ePub and print output had no
+syntax highlighting at all, silently. Making it an optional peer then broke the build outright:
+the grammar loaders are static imports a bundler must resolve, so an adopter without the
+package could not build. This
+is the fork already recorded for `tosijs-schema`: a literal import fails a consumer's build
+when the package is absent, and a variable specifier cannot resolve in a browser. It costs one
+lockfile entry and one audit surface; it costs **no bytes** unless something highlights, since
+`<tosi-highlight>` is excluded from the root barrel and the grammars are lazy chunks. The iife
+is the exception and pays **+31.8kb gzip** — see below.
+
+**`ExamplePolicy` gained `'none'`** — "nothing here is live" — for targets that cannot run an
+example at all. The ePub and the Print path pass it.
+
+**`transformAvailable(dialect)`** is exported: the question a diagnostic must ask before it
+accuses a document. `checkExamples` uses it to **skip** dialects whose transpiler could not be
+resolved and report them as *unchecked*, instead of parsing them as JavaScript and blaming the
+author (#154). `ExampleCheck.skipped` now survives the child-process boundary, so that field is
+true on the path the build actually uses rather than always reading "nothing was skipped".
+
+**The "writes outside `outputDir`" warning fires under `bun start`.** It was gated on
+`!opts.skipAudit`, which means *interactive* — so it never appeared in the dev server, the
+exact workflow the report came from.
+
+### The iife is +31.8kb gzip — and that is above our own gate
+
+`dist/iife.js` went **435.7kb → 467.5kb gzip (+7.3%)** between 1.14.1 and 1.15.0. An iife
+cannot code-split, so it inlines Prism core and all 27 grammar modules. This lands on every CDN
+`<script>` user and every `tosijs-ui/site` adopter without `bundleEntry`, on every page load,
+and it compounds #120 where CodeMirror is already most of that bundle.
+
+`CLAUDE.md` sets the gate for a new runtime dependency as the printed gzip delta, and this
+exceeds it. It ships anyway because the alternative was a highlighter that did not work in a
+browser — but the number is stated here rather than left in a commit body, and the unexplored
+remedy (capping the grammar map, or marking prism external for the iife specifically) is
+tracked in `TODO.md` so tagging cannot evaporate it.
+
+**The ESM path is unaffected**: an app importing a button ships no prism at all.
+
+### Need more icons?
+
+The icons page now points at [lucide](https://lucide.dev) — a maintained fork of Feather in the
+same style with far more options, ISC licensed. It emits the same geometry Feather does
+(`24×24`, `fill="none"`, `stroke="currentColor"`, width 2, round caps), so a downloaded SVG
+drops into `defineIcons()` and inherits colour and sizing like a built-in.
+
+### Smaller corrections from the pre-release review
+
+- **`checkExamples` no longer hard-fails on a fence that will never run.** It reduced
+  ` ```js:static ` to `js`, so a block marked illustrative — or any block under
+  `liveExamples: 'opt-in'` that never asked to run — failed the build over its syntax, advising
+  the author to retag it `typescript`: exactly the mislabelling this release abolishes. It now
+  keeps the fence mode and gates on the same predicate the highlighter and `insertExamples` use.
+- **`highlightBlocks` asks that predicate too**, rather than relying on `insertExamples` having
+  already wrapped live blocks. That held only by ordering, which nothing enforced, and
+  tokenizing live-example source is what cost seven doc tests mid-cycle.
+- **`ensureGrammar` distinguishes "no such grammar" from "failed to load".** The first is a
+  plain code block; the second is a real problem and now says so. Conflating them is why a
+  browser-side failure shipped silently.
+- **The `docPaths` escape from the default `reviews/` exclusion actually works** — the basename
+  test ran on the roots too, so naming the directory produced nothing while three shipped
+  places said otherwise.
+- **The `-test-only` class** lets a stylesheet present a test-only example's results as its
+  body rather than as an annotation under an empty preview.
+- **The barrel guard checks two properties**: a plain component build ships zero prism, and
+  every grammar import lives inside a thunk.
+
+### A test-only example shows its results instead of an empty box
+
+A ` ```test ` fence with no `js`/`html`/`css` beside it has nothing to render. The preview came
+up empty and the results panel stayed hidden unless a test **failed** — so a passing suite
+looked like a broken example, and hid the one thing the block existed to show.
+
+Now the results are the example's body: always visible, in flow, with the empty preview taking
+no space. Ordinary examples are unchanged — their results stay a floating panel, shown on the
+test tab or on failure.
+
+Useful for documenting a pure function, an invariant, or any behaviour with no visual output.
+There is a worked example in the `example` docs, which is also what the Playwright test asserts
+against — the corpus had none when this was written.
+
+### Four adoption defects from tjs-lang (#151, #153, #154, #156)
+
+All four are silent — the build succeeds and something is quietly wrong, which is #61's thesis
+in four more instances.
+
+**`SiteConfig` gained `ignoreDocPaths`, and `reviews/` is excluded by default (#153).** A
+`docPaths: ['docs']` takes the directory wholesale, and one adopter's first successful build
+**published 13 internal pre-release review reports as public pages** — including BLOCK
+verdicts naming an adopter. `extractDocs` already had `ignore`; it simply was not reachable
+from the config. The practices doc that tells you to write review reports is the same one
+warning that publishing them is the bad outcome, so the safe thing is now the default rather
+than the informed choice. An explicit `docPaths` entry still wins — naming a directory skips the basename exclusion,
+which applies only to directories found while walking. And when a default exclusion withholds
+files it now prints the directory, the count and how to publish them, rather than dropping
+pages with no receipt.
+
+> **If you built a site on 1.14.1 or earlier, upgrading is not enough.** The default only
+> protects the *next* build. Scraped review pages carry no `noindex` and are listed in
+> `sitemap.xml` and `llms.txt`, so anything already deployed stays public and indexable until
+> you replace it. Check your **deployed** output — not your working tree — for pages derived
+> from a `reviews/` directory, then rebuild on 1.15.0 and redeploy. If they were indexed, the
+> rebuild removes the pages but you may also want a removal request.
+
+**The build says which files outside `outputDir` it will overwrite (#154).** `outputDir` reads
+as a box the build stays inside and is not one: `docsJson` defaults to `demo/docs.json` and
+`llms.txt` is written at the project root. An adopter who set `outputDir` to a scratch
+directory *specifically to evaluate without touching their repo* lost both — including the
+`docs.json` their playground reads at runtime. Warned only when `outputDir` has been moved off
+its default, which is the "I am containing this build" gesture; a project on the default has an
+ordinary setup where these writes are the point.
+
+**`checkExamples` no longer blames the document for a transpiler it could not load (#154).**
+`loadTransform` degrades to identity when tjs-lang is unresolvable — right at runtime, wrong
+for a build-time check, because the block is then parsed as raw JavaScript. The reporter got
+~30 syntax errors in **valid TJS**, each advising them to fix correct code, with the one line
+explaining the degradation printed far away. Unparseable dialects are now **skipped and
+reported as unchecked** — "we did not look" and "we looked and it is fine" must not produce the
+same output, and neither may masquerade as "your document is broken".
+
+**Dev rebuilds bust the browser cache (#151).** Assets were stamped with the package version,
+which does not change while you work — so `hydrate.js?v=0.2.0` was byte-identical across every
+rebuild and the browser kept executing the bundle it cached hours ago, through edits and
+reloads. It looks exactly like "my change had no effect": the reporter spent a long session
+editing CSS that was already correct and already being served. Dev builds now stamp with a
+**content hash** of the bundle, the iife and the stylesheet, so it moves when the output moves
+and *only* then. **Every** build does — there is no separate release mode.
+
+Two defects in the first cut, both caught by the 1.15.0 review. `doc-system.css` was named in
+the hash inputs but generated ~80 lines after the stamp was consumed, and the hash loop skips a
+missing file silently — so a `theme`-only change deployed new CSS under an unchanged URL, a
+regression against the version stamp it replaced. And the "release builds keep the version"
+branch keyed on `opts.lock`, which no shipped caller passes and which means *acquire the build
+lock*: it never ran, and an adopter using `lock` for its documented purpose would have silently
+changed stamping mode. The stylesheet is now generated before the stamp, and the branch is
+gone.
+
+**A doc that documents the metadata format is no longer classified by its own example
+(#156).** `<!--{…}-->` matched anywhere in the file, so a page teaching the convention was
+published with the illustration's `title` and `order`. Fenced code is now stripped before
+scanning and the block must start a line — the same rule `/*#` doc comments already follow.
+
+### Static code is syntax-highlighted — on the page, in the ePub, and in print
+
+Display-only code was highlighted **nowhere**. The pre-rendered page emitted a bare
+`<pre><code class="language-ts">`, the client never touched it, and the ePub stripped the
+language class entirely — so a doc system that publishes books had no highlighting in the
+books.
+
+Highlighting now happens at **build time**, which is the only thing that reaches an ePub
+(readers may run no JavaScript), print, a no-JS reader, or a crawler. Token markup is in the
+HTML; all it needs is CSS.
+
+- **Site**: **two palettes**, light (the default) and dark under `.darkmode`, each
+  contrast-checked against the `--code-bg` it sits on — worst case 5.32:1 light, 6.01:1 dark,
+  against WCAG AA's 4.5:1. Every colour is a `varDefault`, so a single token type can be
+  overridden in one mode without replacing the set.
+- **Book and print**: a separate LIGHT palette, contrast-checked against the `#f6f8fa` code
+  background (the weakest is ~4.6:1, above WCAG AA).
+- Both the ePub and the **Print** path pass a `'none'` example policy, because neither can run
+  a live example — so an executable fence is highlighted there rather than skipped. Without it
+  the ePub left **237 of 284 code blocks plain** (every `js`, `html`, `css` and `test` block,
+  which is most of the corpus) while this entry claimed otherwise, and the print path never
+  highlighted at all, so the book stylesheet's token rules matched nothing.
+- **Client**: the same pass runs after client-side navigation, and skips anything already
+  highlighted, which is what keeps the pre-rendered page and its hydrated self identical.
+
+**Executable fences are never highlighted** — they are live-example *source*, and tokenizing
+them hands the example markup where it expected code. The build and the client now ask that
+question through one shared predicate (`doc-system/example-policy.ts`), because for one build
+they disagreed and seven doc tests failed as "Expected 0 to be 4": an example that rendered
+nothing, reported as a broken component rather than a broken pipeline.
+
+### New: `<tosi-highlight>` — by subpath, not from the root barrel
+
+**Import it as `tosijs-ui/highlight-block`.** It is deliberately *not* re-exported from the
+root barrel, for the same reason the doc-system cluster is not (#133): its import chain
+reaches the static Prism grammar map, and a bundler emitted **15 grammar chunks / 357kb** for
+an app that imported a rating and a select. Measured before and after — 30 chunks / 373kb → 1
+chunk / 287kb.
+
+The iife pulls it explicitly, so CDN `<script>` and doc-site users are unaffected. Bundling
+grammars is right there and wrong in the barrel: an iife cannot code-split, and its consumers
+want highlighting.
+
+A tree-shakeable component for a fetched snippet, a generated example, an API response — the
+cases the build cannot know about. Renders readable plain text synchronously and upgrades when
+the grammar arrives, so a reader never sees an empty box and a missing grammar degrades to
+plain code rather than failing.
+
+Prism is a **lazy chunk**: an app that imports a button ships none of it. `src/index.test.ts`
+asserts that against a real split bundle, since the property is easy to lose to a stray static
+import.
+
+Prism rather than reusing the CodeMirror we already ship, because #120 is an open issue about
+CodeMirror being in every IIFE at 94% of the bundle — and routing static highlighting through
+it would deepen exactly the dependency that issue wants to escape. It also covers the languages
+a prose corpus uses and the editor never bundled: shell, python, rust, yaml, diff.
+
+### Live examples can be opt-in, and a single fence can opt out (#140, #146)
+
+Six fence languages execute — `js`, `ts`, `tjs`, `html`, `css`, `test` — and until now a
+**static sample in one of them was impossible.** The only workaround was to mislabel the fence
+(`xml` for HTML, `scss` for CSS), which changes the syntax highlighting to a language it isn't.
+
+Two escapes. **The default does not move**, so no existing corpus changes:
+
+```
+```js:static          one fence, opted out — works under either policy
+liveExamples: 'opt-in'   nothing runs unless its fence asks (`:inline` / `:iframe` / `:ide`)
+```
+
+`'opt-in'` is the setting for a **prose or book site**, where code is overwhelmingly
+illustration. `html` and `css` are the ones that bite, because neither looks like something
+you are asking to run: a fence showing how to style the component *in your app* is injected as
+a page-wide stylesheet — a white slab in dark mode — and a fence showing the markup something
+compiles to renders as an unstyled demo. Neither fails a build, so a site can ship both and
+nobody finds out.
+
+The policy reaches the client the same way `__TJS_LOCAL_BASE` does, and is **only emitted when
+it differs from the default**, so an `auto` site's HTML is byte-identical to before.
+
+`:static` is honoured under both policies, so one corpus can be written to work either way.
 ## 1.14.3
 
 A single-fix patch cut from `v1.14.2`. Carries no 1.15.0 work.