tosijs-ui 1.9.0-rc.2 → 1.9.1

package/CHANGELOG.md

@@ -1,6 +1,279 @@
 # Changelog
 
-## 1.9.0-rc.2
+## 1.9.1
+
+**`tosijs-ui` did not import under Node.** Shipped `dist/` used extensionless relative
+imports (`from './site-config'`), which bun resolves and Node ESM does not — so a Node
+consumer got `Cannot find module` on entry points that had nothing to do with bun. Every
+entry point is affected, and this goes back well before 1.8.0.
+
+Everything shipped now uses explicit `.js` specifiers, which Node requires and every
+bundler accepts. **If you are on Node, upgrade; 1.9.0 and earlier will not resolve.**
+
+Two runtime requirements are unchanged, and are now documented rather than implied — they
+are honest constraints, not bugs, but the failure messages named symptoms rather than
+causes:
+
+| entry point | runtime |
+| --- | --- |
+| `tosijs-ui/site` | **bun** — it shells out, builds and spawns |
+| `tosijs-ui`, `tosijs-ui/<component>` | a **browser** or a bundler targeting one |
+| `tosijs-ui/icon-svg` | anything — deliberately DOM-free |
+
+`engines` now declares bun, and `doc-site-system.md` has a "Runtimes — what runs where"
+section.
+
+**Why four test lanes missed it:** all four run under bun. `test-consumer` packs the real
+tarball, installs it and builds from a foreign cwd — but with bun, so it proved the
+package works for people exactly like us. It now imports every entry point through **Node**
+and asserts the absence of module-resolution errors specifically, separating "packaging is
+broken" from "this needs a DOM / needs bun". Verified against the published 1.9.0: all
+three checks fail on it.
+
+## 1.9.0
+
+Consumer repairs, remote access, and **authoring: many books from one corpus**.
+
+**Anyone on 1.8.0 should upgrade, whether or not they want the new remote-editing
+feature.** 1.8.0's `tosijs-ui/site` entry point does not import at all in a clean
+install — `index.js` statically re-exports `devServer`, which imports `chokidar` at top
+level, and `chokidar` was declared only in `devDependencies` (#32). 1.8.0 also shipped
+5.2 MB / 16 files of doc-site hydrate bundle into every consumer's `dist/` (#31), and
+broke the `tosijs-make-icons` bin (#30). All three are fixed here.
+
+### Consumer repairs
+
+- **`tosijs-ui/site` imports in a clean install again** (#32). `chokidar` is now an
+  optional peer, imported lazily by the watch path only — a plain `buildSite()` never
+  reaches for it.
+- **The library package no longer carries the doc-site hydrate bundle** (#31). It built
+  into `dist/hydrate/` and shipped to everyone though nothing references it; one adopter's
+  package went from 0.62 MB / 398 files to **10.2 MB / 2888 files**. It now builds in a
+  temp dir. Caught only by reading `npm pack` output, which is why there is now a lane
+  that does exactly that (`bun run test-consumer`).
+- **`tosijs-make-icons` no longer strips `fill-rule`** (#30), which rendered holes in
+  compound `evenodd` paths solid — a keyboard drawn as one path came out filled. It was
+  stripped in **three** places, not one. `fill-rule` is fill _topology_, not colour, and
+  takes no part in the tinting the strip exists for. Ships as a bin, so it affects anyone
+  generating their own icon data.
+- **The shipped bins have shebangs** (#35, #36 — reported independently by both adopters).
+  Without one, `node_modules/.bin` shims hand TypeScript to the shell.
+- **`/version.json`'s `generator` reports tosijs-ui's version, not the consumer's** (#37).
+  It read `package.json` from the _cwd_, so the one field that answers "which tosijs-ui
+  built this?" named the wrong package entirely.
+- **A failed "save to source" says why** (#34). The server answers 501 with an actionable
+  reason and the client discarded it for a generic "Save failed.", so an unconfigured
+  server was indistinguishable from a broken one and the edit appeared to vanish.
+- **New: `iconSvg(name)` / `iconNames()`** (#33) — raw SVG markup with **no DOM
+  required**, for build scripts, ePub passes and server-rendered templates. `defineIcons()`
+  could write to the icon map but nothing could read it.
+
+### Remote access — view and edit your dev server from anywhere
+
+`preview.tunnel` exposes the dev server running on your machine at an authenticated public
+URL over an SSH reverse tunnel, so you can read and edit real source from a phone or a
+borrowed laptop. The box does no compute — it terminates TLS and routes — which is what
+lets one small VPS front many projects. Two hostnames make the posture legible:
+
+| host                             | what it is                    | gate            |
+| -------------------------------- | ----------------------------- | --------------- |
+| `<project>.dev.example.com`      | read-only snapshot, shareable | invite cookie   |
+| `<project>.edit.dev.example.com` | live workspace, yours         | session, always |
+
+`tosijs-tunnel --link` prints a single-use link; opening it once exchanges the token for a
+durable `HttpOnly; Secure; SameSite=Lax` session cookie and redirects with the token
+stripped, so it never lands in history or a `Referer`. `tosijs-deploy` publishes the static
+snapshot and self-registers a Caddy fragment, so adding a project edits no shared file.
+
+**Write authorization keys on the LISTENER, never on a peer address or a header.** Tunnel
+traffic arrives on a dedicated loopback listener, and anything arriving there needs a valid
+session — because a reverse tunnel counterfeits "local" by construction.
+
+### Security
+
+- The tunnelled workspace's **read** gate keyed on `X-Forwarded-*` rather than the
+  listener, so any forwarder that omits those headers — `ssh -R` with `GatewayPorts yes`,
+  `ngrok tcp`, `socat`, iptables DNAT, nginx `proxy_pass`, HAProxy without
+  `option forwardfor` — read the entire uncommitted working tree unauthenticated, while
+  `requireToken` promised "nothing at all, not even the page". Now keyed on the listener,
+  like every other gate.
+- `POST /report` was unauthenticated and reachable through the tunnel — a stranger could
+  fabricate `{passed:N, failed:0}` and make the test lane **exit green on a suite that
+  never ran**. Now local-only.
+- Build-error text (absolute paths from your machine) was injected into every served page
+  with no auth check. The label stays public; the detail needs a session.
+- `rsync --delete` accepted any absolute path two segments deep — including `/usr/lib` and
+  `/etc/caddy`, which it would have _mirrored_, i.e. emptied. Now an allowlist of preview
+  roots, and never the root itself: one dropped path segment would otherwise have deleted
+  every other project on a shared box, including the Caddy fragments that route them.
+- `tunnel.requireToken` defaults to **`true`**. The hostname is not a secret — Let's
+  Encrypt publishes every certificate to public CT logs — so the session gate carries the
+  weight. See the docs for what the hostname discloses and what to do about it (#38).
+
+### Fixed
+
+- **A 403 could destroy uncommitted work.** An unauthorized read fell through to GitHub
+  `main`, so you edited the _published_ file, and the save then handed you a download of
+  it — applying which silently reverts your working copy.
+- **`?t=` was intercepted on every request and method**, so any dev server answered
+  `GET /?t=12345` with "that invite link has been used" instead of the page, and 401'd
+  POSTs carrying `t`. (`t` is the classic cache-buster name.)
+- **Tunnel ports are derived, not fixed** (#39). The bin fell back to a hard-coded 8788
+  while the server used `PORT + 1`; they agreed only when `PORT` was 8787. `remotePort` is
+  now derived per project too, so two projects on one host cannot collide. One resolver
+  serves both, and `tosijs-tunnel --status` reports the ports it would use.
+- **The last-good build protection moved to where the wipe is** — it lived in the dev
+  server's watch branch, so `bun run build`, CI, adopters and `bun start`'s own initial
+  build had none of it. A red `tsc` no longer discards a freshly generated site either.
+- Two dev servers can coexist; the idle-exit timer counts requests again, not just builds;
+  "Build failed" is no longer overwritten by test results seconds later.
+
+### ⚠️ `hidden` now actually withholds
+
+**If you have been using `draft: true` or `hidden: true` for working notes or unfinished
+chapters, they were public.** `hidden` only removed a doc from the nav and the book — its
+full text was still written into `docs.json`, and it still got a pre-rendered page at its
+own URL. The code comment claimed "drafts don't ship"; a probe confirmed they did, twice
+over.
+
+`hidden: true` now means **not published at all**: absent from `docs.json`, from the
+generated pages, from every book, and from `llms.txt`. It is filtered at _extraction_,
+because the corpus is the thing that gets published and any filter applied after it is
+written is too late.
+
+It is inherited, and a child **cannot** un-hide itself from a hidden parent — accidentally
+publishing one chapter of a withheld section is the failure worth preventing.
+
+### Books
+
+A `book` value on a doc selects which volume it binds into. Volumes are discovered from
+the corpus, so a second book needs no configuration:
+
+```text
+<!--{ "book": "field-guide" }-->              → its own volume
+<!--{ "book": ["default", "field-guide"] }--> → bound into both
+<!--{ "book": "none" }-->                     → on the site, in no book
+```
+
+Like `hidden`, it is inherited down the `parent` chain — you mark a section, not every
+leaf — with the **nearest declaration winning outright**, so a chapter can divert to
+another volume, join several, or opt out. A list is what gets you shared front matter: a
+glossary or licence page bound into every volume from one source file rather than copied
+per book. `"none"` anywhere in a list wins, because a contradiction should resolve to
+withholding. `"default"` exists as a writable name for the main volume precisely so a list
+can include it — without one, an array could only ever express "not the default".
+
+`config.book` (the manifest that curates and orders docs _within_ a volume) and a doc's
+`book` metadata (_which_ volume) are different things that share a word; both are
+documented.
+
+### Release notes assemble themselves
+
+`tosijs-release-notes` builds a CHANGELOG section from `[tag]` bullets in commit bodies,
+so notes are written next to the diff rather than reconstructed from memory at the end —
+which is where three false claims in the 1.9.0 notes came from. One bullet per
+separately-interesting _thing_, layered on the conventional subject rather than replacing
+it: a `type:` prefix can only ever represent one change, and the 1.9.0 review commit did
+ten things.
+
+    tosijs-release-notes            # assemble the section
+    tosijs-release-notes --check    # gate: nothing since the last tag is unaccounted for
+
+`--check` fails when an annotation is missing from the changelog, and separately reports
+any commit whose `[fix]`/`[new]` bullets are contradicted by a **markdown-only diff** —
+the shape of the worst 1.9.0 bug, where an auth-gate fix was asserted by a commit whose
+diff never touched the file it named. Matching is deliberately loose: rewriting a bullet
+into prose is the intent, and demanding a literal match would only train people to paste.
+
+This section was assembled by the tool and then written up by hand, which is the intended
+workflow — it generates a skeleton and a coverage gate, never the prose. The gate then
+caught two things this very section had dropped, including a bug found by running the tool
+over this repo's own 2026-04/05 history: a bullet used as the commit _subject_ swallowed
+the entire body as continuation text, so one note came out as three paragraphs of
+implementation detail.
+
+### Also
+
+- `tosijs-make-icons` emits clean, stable, formatter-conformant output, and honours your
+  prettier config if prettier is resolvable. Generated icon data no longer churns against
+  a formatter (and should still be added to `.prettierignore`).
+- `resolveBook` → `resolveBooks`, returning a list. New in this release; no migration.
+
+### Late fixes (rc.3 → rc.4)
+
+Three review passes ran against this release. The last two found defects **introduced by
+the previous pass's fixes**, which is why these are listed separately rather than folded
+in silently.
+
+**⚠️ `deploy/Caddyfile` is now a TEMPLATE — action required if you installed it.** It
+shipped in every tarball carrying a real ACME email, a specific preview domain, and a
+literal `__PREVIEW_TOKEN__`, while its own header told you to `scp` it to `/etc/caddy`.
+Following that gave you a preview host whose entire invite gate was a string published in
+a public repo, issuing certificates under someone else's Let's Encrypt account. Set
+`PREVIEW_TOKEN`, `ACME_EMAIL` and `PREVIEW_DOMAIN` in `/etc/caddy/preview.env` and
+re-install with `deploy:caddy`, which now substitutes all three, **refuses to install if
+any placeholder survives**, and validates into a temp file before replacing the live
+config rather than after.
+
+- **Every ePub volume shipped an identical `dc:identifier`, `dc:title` and cover.**
+  `unique-identifier` is EPUB3's primary key, so importing two volumes into Apple Books
+  or Calibre made the second replace the first — you would silently lose a book. Volumes
+  now derive their own identity; `epub.volumeTitles` names them properly.
+- **An ePub volume matching no documents shipped as a success** — a typo'd book name
+  produced a valid ~10KB book with a cover, a nav and no chapters, at exit 0. It now fails
+  and lists the volumes that do exist. Relatedly, a corpus where _every_ doc names a
+  volume no longer errors on its empty default bucket.
+- **An invite link was unredeemable** on a proxied dev server with no `preview.tunnel`
+  block: the lock armed off a config section that did not exist while the `?t=` reader,
+  correctly gated on it, refused to look. One predicate now, exported and tested.
+- **`tosijs-tunnel` ignored `PORT` and `--port`**, targeting one port while the server
+  listened on another — the drift #39 was meant to end, reintroduced by the commit that
+  claimed to end it.
+- **The deploy and tunnel bins printed ✅ over failed remote steps.** `tosijs-deploy` now
+  distinguishes _deployed_ from _routed_ and exits non-zero when the files landed but
+  nothing serves them; `tosijs-tunnel` marks a public URL that is not routed.
+- **Preview roots other than `/srv/preview` registered successfully and routed nothing** —
+  the write side was de-hardcoded while the Caddyfile glob and index script still named
+  the default. One place decides now, and a mismatch says so. Override with
+  `preview.caddySitesDir`.
+- **`release-check` cleared an empty range** at exactly the release boundary, because
+  `git describe` returns the nearest tag including prereleases. It now baselines on the
+  last stable release _this commit descends from_, so a hotfix tagged out of order or a
+  maintenance branch cannot mislead it.
+- **Publishing now gates on `release-check`.** It was added mid-cycle, and the first thing
+  it caught was nine unrecorded annotations including a `[break]` — the `deploy/Caddyfile`
+  change above, which would otherwise have shipped with no migration note at all.
+- **The release gate hardened against itself.** `release-check` is now baselined on the
+  last stable release this commit _descends from_ (`git describe --exclude`), so a hotfix
+  tagged after a later release, or a maintenance branch, cannot mislead it — a repo-wide
+  tag scan got both wrong. Its coverage matcher also stopped crying wolf: it filtered
+  short words out of the annotation but not out of the changelog, so entries that were
+  plainly written up got reported as missing.
+- **`isLockedDown()` and `hasTunnel()` are exported** from the auth module. The predicate
+  existed in three places, one of them recomputed inside its own regression test — so
+  reverting the fix left the entire suite green. The test imports the real function now.
+- **The browser-test lane keys on haltija's `ready` signal** (haltija ≥ 1.6.1, added in
+  response to us filing it): a server that is up but has no connected tab is no longer
+  adopted, because `hj navigate` then fails with "no browser reachable". That cost three
+  lane runs in a day, each needing a manual `pkill`. The floor also named 1.5.5, a version
+  that was never published.
+- **New "Host bootstrap" docs**, because the preview host needs setting up once before
+  any project can register. Both bins write fragments that `import preview_site` /
+  `import tunnel_site` — snippets that only exist once the host has a Caddyfile — so an
+  un-bootstrapped box failed `caddy validate` forever, for every project, silently. That
+  failure now names the missing prerequisite.
+- `epub.volumeTitles` is now accepted by `defineSiteConfig` — it was documented and
+  type-rejected. `extractDocs`'s hidden-filtering gained tests at the tier that matters:
+  real files, real entry point, verified by mutation.
+
+### For maintainers of adopting projects
+
+`bun run test-consumer` packs the tarball, installs it into a scratch project, and builds
+from that project's cwd. Every other lane runs _in this repo, from this repo, with one dev
+server_ — and four regressions shipped anyway, each living outside exactly that envelope.
+More unit tests would have caught none of them; the gap was context, not depth.
+
+### 1.9.0-rc.2 (prerelease detail)
 
 Fixes everything both consumers hit within minutes of `rc.1`. Three were regressions
 introduced by rc.1 itself.
@@ -21,8 +294,8 @@ introduced by rc.1 itself.
   broken".
 - **New lane: `bun run test-consumer`** — packs the tarball, installs it into a scratch
   project, runs every bin through the `node_modules/.bin` shims, and builds a site from
-  that project's cwd. Every other lane runs *in this repo, from this repo, with one dev
-  server*, and all four rc.1-era regressions lived outside that envelope. It found a real
+  that project's cwd. Every other lane runs _in this repo, from this repo, with one dev
+  server_, and all four rc.1-era regressions lived outside that envelope. It found a real
   bug on its first run.
 - **A failed "save to source" now says why** (#34). The endpoint answers 501 with an
   actionable sentence ("editableSources is not enabled…") and the client threw it away
@@ -30,8 +303,7 @@ introduced by rc.1 itself.
   broken one and the edit appeared to vanish. The server's reason is surfaced, and every
   failure path now states that the edit is still in the editor.
 
-
-## 1.9.0-rc.1
+### 1.9.0-rc.1 (prerelease detail)
 
 Release candidate. Everything the nine-lens review and the first adopters raised is
 addressed; no features are pending. Install with `tosijs-ui@rc`.
@@ -39,10 +311,10 @@ addressed; no features are pending. Install with `tosijs-ui@rc`.
 **Edit and view are now separate hostnames**, which makes the security posture legible
 without reading config:
 
-| host | what it is | gate |
-| --- | --- | --- |
-| `<project>.dev.example.com` | read-only static preview — shareable | invite cookie |
-| `<project>.edit.dev.example.com` | live editable workspace — yours | session, always |
+| host                             | what it is                           | gate            |
+| -------------------------------- | ------------------------------------ | --------------- |
+| `<project>.dev.example.com`      | read-only static preview — shareable | invite cookie   |
+| `<project>.edit.dev.example.com` | live editable workspace — yours      | session, always |
 
 - **`tunnel.requireToken` now defaults to `true`.** The old default (read-open) was
   justified by "an expired link should degrade to a readable page when you open a second
@@ -53,10 +325,10 @@ without reading config:
   deliberately if you want a live read-only audience.
 - **An edit host with no tunnel behind it explains itself** — a 503 saying the workspace
   is offline, with a link to the static preview, instead of a bare 502. It deliberately
-  does *not* fall back to serving the snapshot: you would think you were looking at live
+  does _not_ fall back to serving the snapshot: you would think you were looking at live
   work when you were not.
 - **A spent invite link says so.** The likely culprit is a chat-app link-preview bot,
-  whose GET *is* the first use; previously you got a silent redirect and discovered it
+  whose GET _is_ the first use; previously you got a silent redirect and discovered it
   when a save failed.
 
 **Security fixes** (all found by review or adopters, none reported in the wild):
@@ -67,14 +339,14 @@ without reading config:
 - Build-error text (absolute paths from your machine) was injected into every served page
   with no auth check. The label stays public; the detail needs a session.
 - `rsync --delete` accepted any absolute path two segments deep — including `/usr/lib`
-  and `/etc/caddy`, which it would have *mirrored*, i.e. emptied. Now an allowlist of
+  and `/etc/caddy`, which it would have _mirrored_, i.e. emptied. Now an allowlist of
   preview roots, extracted and tested.
 
 **Adopter-reported fixes** (all from tosijs-3d, all consumer-facing):
 
 - **`tosijs-make-icons` stripped `fill-rule`** (#30), so a compound path using `evenodd`
   for holes — a keyboard drawn as one path — rendered the holes solid. `fill-rule` is
-  fill *topology*, not colour, and takes no part in the tinting the strip exists for.
+  fill _topology_, not colour, and takes no part in the tinting the strip exists for.
   It turned out to be stripped in **three** places, not one; the `stroked/` branch is the
   one that bit. This ships as a bin, so it affects anyone generating their own icon data.
 - **The doc-site hydrate bundle was written into the library `dist/`** (#31) and shipped
@@ -92,7 +364,7 @@ without reading config:
 **Correctness:**
 
 - **A 403 could destroy uncommitted work.** An unauthorized read fell through to GitHub
-  `main`, so you edited the *published* file, and the save then handed you a download of
+  `main`, so you edited the _published_ file, and the save then handed you a download of
   it — applying which silently reverts your working copy. 401/403 is now its own case in
   both editors.
 - **The last-good build protection moved to where the wipe is.** It lived in the dev
@@ -104,8 +376,7 @@ without reading config:
 - `?t=` is only intercepted when a tunnel is configured, and only on GET — `t` is the
   classic cache-buster name, and a 302'd POST loses its body.
 
-
-## 1.9.0-beta.3
+### 1.9.0-beta.3 (prerelease detail)
 
 Fixes three blockers found by the nine-lens review of beta.2, all in the remote-editing
 feature, plus a rebuild loop the review did not catch because nothing automated runs
@@ -113,20 +384,19 @@ feature, plus a rebuild loop the review did not catch because nothing automated
 
 - **`bun run tunnel --link` never worked.** It ran `pgrep -f 'bun bin/dev.ts'`, which does
   not match the documented start command (`bun --watch bin/dev.ts`) — so the headline flow
-  was unreachable. Worse, it *did* match `bun bin/dev.ts --build-only`, whose process exits
+  was unreachable. Worse, it _did_ match `bun bin/dev.ts --build-only`, whose process exits
   before the signal handler is registered, so the default SIGUSR2 disposition **killed
   in-flight builds**. Now it asks the dev server over a loopback-only `/__devlink` endpoint:
   no process guessing, no signals, and it cannot touch a sibling project. (`/__devlink` is
   refused over the tunnel — a read-only visitor minting a write session would be privilege
   escalation.)
-- **Write authorization failed OPEN.** It inferred "this is local" from the *absence* of
+- **Write authorization failed OPEN.** It inferred "this is local" from the _absence_ of
   `X-Forwarded-*`, so any forwarder that doesn't set them — `ssh -R` with `GatewayPorts yes`,
   `ngrok tcp`, `socat`, iptables DNAT, nginx without `forwardfor` — delivered an off-machine
   request as `{peer: 127.0.0.1, no headers}` and got an **arbitrary repo write**, which the
   watcher rebuilds and runs. The dev server now binds a **separate loopback-only port** for
   tunnel traffic; arriving there always requires a session. Which socket you connected to is
-  not something a client can forge. `bun run tunnel` also verifies the remote port is bound
-  to loopback and says so loudly if it isn't.
+  not something a client can forge.
 - **The decision guarding that RCE had no tests**, while its own comment claimed a
   regression test that did not exist. It is now `mayWriteSource()` — pure, exported, and
   covered including a named regression case for the fail-open above.
@@ -140,13 +410,13 @@ feature, plus a rebuild loop the review did not catch because nothing automated
   workspace, so silently adopting a neighbour's config would publish the wrong project.
 - **Fix: the tunnel probed the wrong port**, so forwarding to a dead listener failed
   silently with a 502 and a healthy-looking dev server (tosijs-ui#28). `ssh -R` can't
-  catch it — the *remote* bind succeeds, so `ExitOnForwardFailure` stays quiet; it's the
+  catch it — the _remote_ bind succeeds, so `ExitOnForwardFailure` stays quiet; it's the
   local end that connects to nothing. It now probes the port it actually forwards to and
   **refuses to open**, naming the likely cause (including "your tosijs-ui predates the
   tunnel listener").
 - **Tunnelled workspaces self-register too** (tosijs-ui#29). Static previews have
   self-registered since beta.1, but a tunnelled host still needed a block hand-added to
-  the *shared* Caddyfile — so the one remaining manual edit was the **riskier** one: a
+  the _shared_ Caddyfile — so the one remaining manual edit was the **riskier** one: a
   typo there breaks routing for every project on the box, which is exactly what the
   fragment design set out to abolish. `tosijs-tunnel` now writes its own fragment with
   the same validate-before-reload discipline, and the shared file names no hostnames at
@@ -162,13 +432,12 @@ feature, plus a rebuild loop the review did not catch because nothing automated
   watcher path and declared an **optional peer**, so building needs nothing extra and the
   watching dev server explains itself if it is missing.
 - **Fix: `bun start` was in a rebuild loop** (measured at 899 restarts in ~40s), which made
-  the documented dev command unusable. The build stamp imported the *generated*
+  the documented dev command unusable. The build stamp imported the _generated_
   `src/version.ts`, putting it in `bun --watch`'s module graph while prebuild rewrote it every
   build. The import is gone, and generated files are now written **only when the content
   changes**, which makes the whole class of self-write loops impossible.
 
-
-## 1.9.0-beta.2
+### 1.9.0-beta.2 (prerelease detail)
 
 > Prerelease — install with `tosijs-ui@beta`. `latest` stays on 1.8.0.
 
@@ -182,7 +451,7 @@ same watcher, same files.
   which is what lets one small VPS serve many projects. The work stays where the data is.
 - **Magic-link auth.** Two tokens on purpose: the **link** rides in a URL so it is the
   one that leaks (history, `Referer`, proxy logs, chat-app link previews) and is
-  therefore *single-use and 15 minutes*; the **session** never appears in a URL, arrives
+  therefore _single-use and 15 minutes_; the **session** never appears in a URL, arrives
   as an `HttpOnly` cookie, and is durable. A durable token pasted into a URL would be
   strictly worse than basic auth. `SameSite=Lax` gives the write endpoint free CSRF
   protection.
@@ -205,8 +474,7 @@ same watcher, same files.
   session) — Caddy serving static files has no session store — but equivalent to the
   basicauth it replaces, with no dialog.
 
-
-## 1.9.0-beta.1
+### 1.9.0-beta.1 (prerelease detail)
 
 > **Prerelease.** The preview-host system works end to end and is in daily use, but the
 > plan it belongs to (`REMOTE-ACCESS-PLAN.md`) has two more phases. Published under the
@@ -284,7 +552,7 @@ same watcher, same files.
     shown), plus an **advisories-per-package tally** — a dependency that keeps producing them
     is a code smell worth replacing rather than patching.
 - **Fix (issue #24, reported by a consumer): nav `order` now sorts numerically.** Section nav
-  and the generated `<!-- toc -->` built a zero-padded *string* key and compared it lexically,
+  and the generated `<!-- toc -->` built a zero-padded _string_ key and compared it lexically,
   so a fractional order silently sorted to the **end** of its section — `order: 1.5` landed
   after `2`, `3`, … because `"01.5" > "0002"` as text. "Insert a page at N.5" reads like a
   supported idiom and did the opposite with no warning. The same padding capped `order` at 4
@@ -299,7 +567,7 @@ same watcher, same files.
   above was effectively unfindable. The comparator needs no delimiter; the NUL is gone.
   - **Adopting the gate — budget for one upgrade, not one pin.** From the first real
     adoption (`tosijs`, which went from 12 blocking advisories to zero): if the gate flags
-    **`brace-expansion`**, note that `GHSA-mh99-v99m-4gvg` marks *every* version below
+    **`brace-expansion`**, note that `GHSA-mh99-v99m-4gvg` marks _every_ version below
     **5.0.8** affected, so the override is mandatory — and `brace-expansion@5` breaks
     **eslint 8**'s bundled `minimatch@3` with `expand is not a function`. In practice that
     means **an eslint 8 → 10 migration** (flat config + typescript-eslint 8), not a one-line
@@ -360,13 +628,13 @@ same watcher, same files.
   it never sits over the code editors in side-by-side mode). The collapsed handle carries the
   example's pass/fail color, "run tests" is a checkbox that greys when off, and the bar stays
   visible when the example is maximized.
-- **Build system is fragility-tolerant.** An *unsupported import* in a live example (a bare
+- **Build system is fragility-tolerant.** An _unsupported import_ in a live example (a bare
   specifier the runtime can't resolve) now downgrades that block to display-only with a warning
   instead of failing the whole build; genuine syntax errors still fail the build.
 - **Removed a render-skip anti-pattern** from `<tosi-segmented>`, `<tosi-color>`, and
-  `<tosi-form>`. They previously depended on `render()` being *skipped* after interaction via a
+  `<tosi-form>`. They previously depended on `render()` being _skipped_ after interaction via a
   `valueChanged` flag — fragile timing that broke under tosijs's parts changes. Renders are now
-  idempotent: they skip only *provably-redundant* writes by comparing values (colors compared
+  idempotent: they skip only _provably-redundant_ writes by comparing values (colors compared
   **parsed**, so a `#rrggbb ↔ rgba()` round-trip no longer clobbers the caret/selection in the
   field being edited).
 - **Code editor background is now a neutral off-white** (off-black in dark mode) instead of a
@@ -391,7 +659,7 @@ same watcher, same files.
   build was locked to one mount — adding a custom domain to a GitHub project page flipped the
   live site to the root while `docs/` still pointed at `/repo`, 404ing every asset into a bare,
   unstyled shell with no warning. Functional URLs are now emitted **relative to each page**, so
-  one build works at `/repo`, a custom-domain root, or a moved mount with no rebuild. *Metadata*
+  one build works at `/repo`, a custom-domain root, or a moved mount with no rebuild. _Metadata_
   URLs (`canonical`, `og:url`, `og:image`, `sitemap.xml`) stay absolute via `baseUrl`+`basePath`
   — so `basePath` now only affects metadata, never the page's assets. (The hydrated SPA's own
   nav/`pushState` and `__TJS_LOCAL_BASE` remain root-relative — tracked in #16.)
@@ -424,7 +692,7 @@ same watcher, same files.
 - **Fix: "edit page source" showed HTML instead of source in a dev server without
   `editableSources`.** The `/__docstore/source` endpoint was only routed when
   `editableSources` was on; otherwise the request fell through to the SPA `index.html`
-  fallback and returned the rendered page at status 200 — so the client loaded HTML *as* the
+  fallback and returned the rendered page at status 200 — so the client loaded HTML _as_ the
   source (and save read HTML). The endpoint is now handled unconditionally and answers a clean
   `501` when editing is disabled, so `loadSource` falls back to the GitHub raw source (read-only
   editing, matching the deployed site). Belt-and-suspenders: the client also rejects any
@@ -432,8 +700,8 @@ same watcher, same files.
   more fully in `doc-site-system.md`.
 - **Local example save now gives feedback.** "Save changes (local)" writes a per-browser
   scratchpad (not the file) — it used to do so silently, reading as a no-op. It now posts a
-  toast (`postNotification`): *"Saved to this browser only — use 'Save to source' to write the
-  file."*
+  toast (`postNotification`): _"Saved to this browser only — use 'Save to source' to write the
+  file."_
 
 - **`valueRenderer(type)` + declarative `<tosi-table>` column `type`.** A new exported helper
   turns a compact type string into a reusable, locale-aware renderer with a sensible default
@@ -449,7 +717,7 @@ same watcher, same files.
 
 - **Deprecation cleanup: `on<Event>` component callbacks → `handle<Event>`.** tosijs reserves the
   `on<Event>` prefix for elements-factory event-handler sugar and now warns when a component
-  *defines* such a property. Renamed the internal ones: `onResize` → `handleResize` (`size-break`,
+  _defines_ such a property. Renamed the internal ones: `onResize` → `handleResize` (`size-break`,
   `side-nav`, `code-editor`, `babylon-3d`, `tab-selector`) and `onScrollEnd` → `handleScrollEnd`
   (`data-table`). Verified: those pages now load with zero `on<Event>` deprecation warnings.
   (`<tosi-tabs>`'s public `onCloseTab` still uses the old name — a breaking rename deferred to a
@@ -517,7 +785,7 @@ the real transpiler + editor on demand; saving keeps the transpiled JS.
 With `importResolver` enabled, a live example can `import` any npm package — resolved through a
 same-origin service worker (tjs-lang's import-resolver). Three execution modes are flaggable on
 the fence: `inline` (default), `iframe` (DOM/CSS isolation), `ide` (recognized; iframe path for
-now). Fence grammar is order-free: `` ```ts:ide#demo `` and `` ```ts#demo:ide `` both parse.
+now). Fence grammar is order-free: ` ```ts:ide#demo ` and ` ```ts#demo:ide ` both parse.
 
 ### Doc-system & build