tosijs-ui 1.12.4 → 1.12.6

package/CHANGELOG.md

@@ -1,5 +1,495 @@
 # Changelog
 
+## 1.12.6
+
+### `<tosi-diff resolvable>` — "do I want to accept this?"
+
+The diff viewer can now be operated, not just read. Set `resolvable` and every change gets a
+pair of buttons; `value` is the text those choices imply and `change` fires when one moves. It
+is a review surface for a **proposed** edit — an AI suggestion, a collaborator's revision, a
+file that moved under you while you were editing it.
+
+The labels are yours: `originalLabel`/`modifiedLabel`. "Mine"/"Theirs" is git's framing,
+"Current"/"Proposed" suits reviewing a suggestion, and this component's own vocabulary is
+original/modified — none of which is right for everyone, so none of it is hardcoded. Also
+`acceptAll()`, `rejectAll()`, `changeCount`, and a `resolutions` array you can read and write.
+`diffBlocks()` and `resolveDiff()` are exported too, if you want the model without the DOM.
+
+The unit of decision is a change **block**, not a line. The LCS walk can emit
+remove/add/remove/add for a single multi-line edit, and offering four independent choices there
+lets a reviewer accept half an edit — producing text neither side wrote.
+
+The read-only path is deliberately unchanged: grouping reorders interleaved edits, which is
+better to resolve and a **different rendering** for the two components already shipping this
+one. Additive means additive.
+
+Two notes on how this was tested, because **both** bugs that nearly shipped were invisible to
+the unit lane, and for the same underlying reason.
+
+The first version rendered **nothing**: `dataset: {…}` in an element creator assigns
+`el.dataset`, a read-only accessor, so `render()` threw and left an empty shadow root.
+Twenty-six green tests sat behind it, every one asserting `value` — which is computed from the
+model and is correct whether or not a single element reaches the DOM. tosijs renders on an
+animation frame and happy-dom runs none, so a unit test that merely _mounts_ an element asserts
+against an empty shadow root; appending hydrates, and `render()` must be called explicitly.
+
+The second was worse, because the render-level tests added for the first one _also_ passed. The
+buttons did nothing when clicked, in every browser. `<tosi-diff>` is a shadow-DOM component and
+tosijs delegates `on*` handlers from above the shadow boundary, so a real click is
+**retargeted**: `event.target` is the host, not the button, and `event.target.closest(…)` — the
+idiom this project documents, and which is correct for a light-DOM component — is `null` every
+time. The fix is `composedPath()`, the only one of the two that survives the boundary.
+
+The happy-dom test could not see it: it called `.click()` on a node it had already looked up and
+then asserted the value moved. Measured against a deliberately broken build, **30 unit tests
+pass and all 3 browser tests fail** — so `tests/diff-resolve.pw.ts` now clicks what a person
+clicks and reads what a host reads. The rule this leaves behind: **shadow-DOM interaction needs
+a browser test**, not a DOM-shaped unit test.
+
+### Selective revert in live examples
+
+The diff resolver is wired into `<tosi-example>`'s **View changes**, and into `<tosi-code>`
+generally via a new `diffResolvable` (plus `diffOriginalLabel`/`diffModifiedLabel`).
+
+Revert was all-or-nothing, which is the wrong shape for what actually happens: you tried four
+things and three worked. Each change in the diff now carries keep/revert buttons — labelled
+**Source** and **Yours** in an example — defaulting to _keep_, so the feature costs nothing to
+ignore and doing nothing leaves your edit exactly as it was.
+
+Choices are applied when the diff **closes**, not as you click, and a `change` event fires if
+the text moved. Writing each choice straight back into `value` would feed the new text into the
+overlay's `modified`, and `<tosi-diff>` resets its decisions when either input changes — so live
+application would wipe the choices making it and renumber the hunks under the pointer.
+
+### Fixed: `<tosi-diff>` and notifications ignored dark mode
+
+Both hardcoded a light palette — `#fff`/`#222` for the diff, `#fafafa`/`#444` for
+notifications — so on a dark page you got a white block, and in the notification's case the one
+element in the library that appears unbidden over whatever you are looking at was also the one
+that ignored your theme.
+
+Both now fall back to the theme (`--background`/`--text-color`) with the old literals as the
+final fallback, so an unthemed page is unchanged and every `--tosi-diff-*` /
+`--notification-*` override still wins exactly as before.
+
+The diff needed both halves at once: darkening the surface alone would have been **worse** than
+leaving it, because light text on a solid `#e6ffed` row is unreadable. The add/remove tints are
+now translucent (`color-mix` with `transparent`), so one value reads correctly as a wash over
+either surface.
+
+### Fixed: a consumer could not use the build lock ([#117](https://github.com/tonioloewald/tosijs-ui/issues/117), [#118](https://github.com/tonioloewald/tosijs-ui/issues/118))
+
+1.12.5 added a build lock that records `pid`, `role`, `root` and `port` per project, so a
+`stop` command can identify what is running instead of `pkill`-ing sibling checkouts. It worked
+— and none of it was reachable from outside the package. `import('tosijs-ui/site')` gave
+`currentHolder === undefined`, and the deep path is blocked by the exports map.
+
+`currentHolder`, `describeHolder`, `lockPathFor`, `lockDecision`, `isProcessAlive` and the
+`LockHolder`/`LockDecision` types are now re-exported from `tosijs-ui/site`.
+
+The reporter deliberately did **not** re-derive the lock path locally, and was right not to:
+that means copying the FNV-1a hash of the resolved root, and if the hash ever changed the
+consumer would report "nothing running" _while a server runs_. Silently-wrong is the exact
+failure this whole area exists to eliminate; duplicating the algorithm reintroduces it one
+layer out.
+
+### haltija floor raised to `^1.12.6`
+
+The floor encodes fixes, not a date. 1.12.6 is where a `--private` instance finally gained a
+**lifetime bound** (haltija#39, filed from here after one was found 12 days old at 5.7 GB and
+~150% CPU on a machine at load average 212); where **LAN and Bonjour access started working at
+all** (served scripts handed the browser `localhost:<port>`, and `localhost` in a served script
+means the _browser's_ machine, so a phone was told to connect to itself); where the widget sends
+`X-Haltija-Token`, so a `--token` server and a page that can talk back stopped being mutually
+exclusive; where results carry `paintAgeMs`, making a rAF-starved tab detectable rather than
+silently wrong; and where Electron went 40.6.1 → 43.4.1, clearing two context-isolation
+bypasses in the thing we spawn.
+
+(Internal, but worth recording: our own `CLAUDE.md` documented this pin as `^1.6.1` long after
+the code had moved to `^1.11.2` — a stale number in the one place a reader would trust for it.
+Corrected.)
+
+### Docs: our haltija gate covers the bridge, not the port
+
+The `haltijaDev: 'tunnel'` documentation read as a complete security story — session cookie,
+404-on-unauthorized, relay rather than hole — and a reader could reasonably conclude the whole
+surface was gated. It is not. Enabling `haltijaDev` at all means haltija's **own** port is
+running, and a default instance binds beyond loopback with `Access-Control-Allow-Origin: *` and
+no token, where `POST /terminal/command` reaches a shell. Set `HALTIJA_TOKEN` on a network you
+do not control; it only became genuinely usable in haltija 1.12.6, which is why older advice
+said to skip it.
+
+## 1.12.5
+
+### Fixed: 49 controls a screen reader announced as "button" and "edit text"
+
+Lighthouse scored the doc site 91 on accessibility, and the cause was entirely mechanical.
+`<tosi-table>` builds a column-options button that contains only an icon, and an editable cell
+that is an empty `<input>` — neither has any text to derive an accessible name from. On the
+data-table page alone that is 37 unnamed buttons and 12 unnamed fields. The doc-browser's search
+box made it worse in a quieter way: it had a `placeholder` and nothing else, on **every page of
+every site built with `tosijs-ui/site`**. A placeholder is not a label — it is an unreliable
+accessible name and it vanishes the moment anything is typed.
+
+The controls now carry a name: `title` on the column-options button, where the tooltip is a
+genuine win for sighted mouse users too, and `aria-label` on the cells and the search field,
+where a tooltip on every hover would just repeat the column header as noise.
+
+To be precise about what `title` buys, because its two halves land on different people: the
+**accessible name** is real and works — `title` feeds the accessible name computation, so
+VoiceOver on iOS/iPadOS announces these controls, as do NVDA and JAWS. The **visible tooltip** is
+mouse-only, and a screen-reader user was never relying on it.
+
+No visible label is added, deliberately. The vertical-more glyph is the standard overflow
+affordance and reads as one; spelling it out on every column header would be clutter that makes
+the header worse for everyone in order to restate what the icon already says. The defect was that
+the control had no name in the accessibility tree, and that is what is fixed.
+
+Localized tables get this through the existing `data-tosi-localized` directive rather than a
+`<tosi-localized>` child, because an `<input>` cannot contain a child element. Add
+**`Column Options`** to your localized strings; the editable cells reuse the column names you
+already localize, so an editable table wants those present even if you are happy with
+untranslated headers.
+
+The regression test is in `tests/a11y-names.pw.ts`, and its first version **passed with both
+fixes reverted** — it waited for `buttons.length > 2`, which the nav chrome satisfies on its own,
+and then asserted an empty list against a page that had not built the controls yet. `toEqual([])`
+is trivially true when there is nothing to check. Every assertion there now has a positive
+precondition that the things under test exist, and the mutation that removes the fixes fails it
+by name.
+
+Not fixed, and not ours: the two images without `alt` on the 3D page come from Babylon's own
+default loading screen.
+
+### Fixed: on a narrow screen, tapping a nav link left you looking at the nav
+
+A regression from 1.12.3's full-screen work, reported from a phone-width window. The sidebar
+fills the screen, you tap a link, the URL changes — and the nav stays up. The article you asked
+for never appears.
+
+Leaving full-screen had been written as the tidy mirror of entering it: `navVisible = true`. But
+that setter's show-the-nav branch writes `contentVisible = false`, and it ran on **every**
+navigation to a non-full-screen page — immediately after the nav click handler had set
+`contentVisible = true` to do precisely the thing the reader asked for. The layout code was
+overwriting a decision that belongs to the person reading.
+
+The two directions are asymmetric now, and that is the point rather than an oversight: entering
+full-screen states what it needs, and stepping out of it releases only what it claimed
+(`alwaysCompact`). Which pane is showing at a narrow width is not the layout's business.
+
+**Nothing in the test suite could have caught this.** Every layout test ran at 1400px, where
+normal mode shows the nav and the content together and `contentVisible` has no visible effect —
+the bug was invisible at every width the tests used. There are now narrow-viewport tests for
+both directions, and the mutation that restores the old line fails them.
+
+### `<tosi-sidenav>` no longer races a timer to hide its own load-time animation
+
+Its defaults are the compact arrangement — 50/50 columns, margin -100% — so the first layout pass
+moves it to wherever it actually belongs. With a transition live, that move _animates_: the
+sidebar visibly slides into place on load.
+
+The suppression was `setTimeout(…, 250)`, which is a race rather than a rule — it assumes the
+first successful layout pass lands within 250ms of the element upgrading. Measured here it lands
+~70ms after (chromium 236→297ms, webkit 213→291, firefox 229→304), leaving ~175ms spare, which
+is exactly why this never reproduced locally. But `handleResize` returns early while
+`offsetParent` is null, so on a bigger corpus or a slower device the first pass can be deferred
+past the window, and then the animation is visible.
+
+It now releases on the first pass that actually computes something, one frame later so the
+corrected values paint before transitions come back. No duration is correct for every page; a
+rule needs no number.
+
+**This does not eliminate the hydration flash, and it is worth being honest about the limit.** It
+removes one race. What remains is the interval between the element upgrading — at which point its
+shadow defaults apply — and the first layout pass correcting them: ~70ms here, invisible, but a
+real window in which the element is painted wrong rather than not painted. The principled next
+step is for the defaults to _be_ the common case, and it is written up in `TODO.md` rather than
+attempted blind, since the flash does not reproduce on this machine and changing paint defaults
+you cannot observe is how you trade a flash you cannot see for one you can.
+
+### Decided: a nav-toggle override does not survive Back
+
+Left open in 1.12.3 and now settled — **metadata wins on arrival**. A page declaring
+`layout: "full-screen"` is full-screen however you reach it: a link, Back, or a fresh load. The
+override is a transient viewing choice rather than a property of the document, and since the nav
+button is always offered on such a page, restoring it is one tap.
+
+Worth recording that the alternative was real. Browsers restore scroll position on Back, so "put
+the view back how I left it" is an established expectation, not an exotic one. It was rejected
+because the state would have to live in `history.state`, which makes the same URL behave
+differently arrived-at-by-Back than clicked — trading the current surprise for a new one — and
+adds state to a path that has none.
+
+No behaviour change; the tests that pinned it now say it is settled rather than pending.
+
+### The invite screen has a code box, so an installed PWA can let itself back in ([#75](https://github.com/tonioloewald/tosijs-ui/issues/75))
+
+The screen offered only a command to run _on the machine hosting the server_. The devices a
+tunnel exists for have no such keyboard — and an installed PWA has no address bar either, because
+iOS gives a Home Screen app its own cookie jar and its own launch URL. An unauthenticated launch
+was a black rectangle with no way out of it.
+
+It now offers the 7-character code box directly: the same affordance as the `dev.tosijs.net`
+landing page, moved to where it is actually needed. A plain GET form produces `/?t=CODE`, which is
+the path the link already takes, so this needed no new server code. The input disables
+autocapitalize, autocorrect and spellcheck, because the code is case-insensitive and a phone
+keyboard's help is noise; there is a viewport meta, because a code box you cannot hit is not much
+better than none.
+
+**What this deliberately does not attempt** is carrying a session across the install. The
+separate cookie jar is a privacy feature rather than a bug, and the issue's suggested "don't
+redirect" fix would bake a live credential into a home-screen icon — working once, then failing
+forever with no address bar to correct it. Seven characters is the better trade.
+
+### A leading metadata comment is no longer the page title ([#100](https://github.com/tonioloewald/tosijs-ui/issues/100))
+
+The title came from line one, literally. A file opening with its metadata block — the documented
+way to set `order` or `parent` — published under the title `<!--{ "order": 2 }-->`, while `order`
+itself parsed correctly. So the metadata visibly worked and the title visibly did not, which is a
+confusing pair to be handed. Hit while adding `CHANGELOG.md` and `Migration.md` to a doc site,
+which is precisely where a leading metadata comment is most natural.
+
+Leading HTML comments are skipped now, including ones that wrap across lines, and an
+unterminated comment yields no title rather than lifting text out of it — publishing something
+the author had deliberately hidden would be worse than an empty string. One rule, used by both
+call sites that previously had their own copy of the line.
+
+No URLs move: slugs derive from the filename, not the title, so an affected page gets a correct
+title at the address it already had.
+
+**The other half of that issue was already fixed**: `docPaths` entries have been in the dev
+server's watch set since #49, so editing a root `Migration.md` does trigger a rebuild.
+
+### `debugSink` — telemetry back from a page that is not on this machine ([#99](https://github.com/tonioloewald/tosijs-ui/issues/99))
+
+`haltijaDev` is localhost-gated for good reason: an injected drive-my-browser channel reachable
+from the network is RCE-adjacent. But that leaves a page served to a headset or a phone with no
+way to say **anything** — and in a WebXR session there is no console and `requestAnimationFrame`
+is suspended, so every usual readback path is gone at once. The remaining channel is a human
+reading an in-scene panel aloud.
+
+`debugSink: true` accepts `POST /__debug-sink` and appends one line per event to a JSONL file
+whose path it prints at startup, so an agent can `tail -f` it:
+
+```javascript
+navigator.sendBeacon('/__debug-sink', JSON.stringify({ t: Date.now(), tag, ...event }))
+```
+
+`sendBeacon` is the point — it needs no headers, reads no response, and survives the page going
+away.
+
+**Why this is reachable off-loopback when `/__docstore/source` is not.** It appends opaque bytes
+to a scratch file, outside the repo, that the build never reads and nothing serves back. No code
+runs; nothing is reconfigured. The source endpoint is remote code execution by design and stays
+gated. This is a log.
+
+Still **off by default**: an unauthenticated write endpoint on a LAN-reachable server should be a
+decision you made rather than one you inherited. Bounded so a looping page cannot fill a disk —
+bodies over 64 KB refused (413), the file stops at 32 MB (507). Newlines in a payload are
+escaped, because one event must be one line or `tail -f` shows a split event and the reader
+cannot tell.
+
+### The dev cert covers the machine's LAN IP ([#92](https://github.com/tonioloewald/tosijs-ui/issues/92))
+
+Every name the cert carried was useful only _on_ this machine, except `<host>.local` — which is
+precisely the one another device is most likely to fail to resolve. Reported from a Quest:
+`tosi.local` resolved to **IPv6 only**, including a link-local `fe80::…` a headset gets and
+cannot route, while the LAN IP worked. The host never sees it, because it resolves mDNS
+natively, so it fails only on the devices the name was added for.
+
+Private ranges only (10/8, 172.16/12, 192.168/16) — a public address on a dev cert would be a
+name this machine has no business claiming. A DHCP lease change moves the address and the cert
+does not follow; the script says so, and prints the URLs another device can use.
+
+Note this fixes the **name mismatch**, not the untrusted CA: mkcert's root still is not on the
+headset, so you either install it there or use the tunnel, which has a real certificate.
+
+### A dropped session says the server restarted, instead of blaming your cookies ([#114](https://github.com/tonioloewald/tosijs-ui/issues/114))
+
+Sessions live in memory and die with the process. That is the design, not an oversight: a
+credential should not outlive the thing that granted it, and nothing about a session — or the
+token exchanged for it — is ever written to disk. **That has not changed and will not.**
+
+What was wrong is that a cookie from a previous run and a cookie the server had never seen
+produced the _identical_ screen. So a reader whose dev server had restarted was told "invite
+links expire", and reasonably concluded their cookie was expiring — the one explanation the
+evidence ruled out. The reporter's own words: the misleading failure "is the part I would most
+want fixed".
+
+The cookie now carries a per-process boot id (`<bootId>.<token>`), so the next process can tell a
+cookie it _issued_ from one it has never seen. Both are still refused, identically; only the
+sentence differs:
+
+> **The dev server restarted, so your session ended with it.** Sessions are held in memory on
+> purpose — they never outlive the process that issued them, and they are never written to disk.
+> Your browser still holds the cookie; there is simply nothing on this side to match it to.
+
+The prefix is not a credential and admits nobody: a cookie with the right run id and a wrong
+token is refused exactly as before, and there is a test asserting that. An absent or malformed
+cookie is _not_ reported as a restart — claiming one we cannot evidence would be its own lie.
+
+### A bundle that references an unserved sourcemap now says so at build time ([#103](https://github.com/tonioloewald/tosijs-ui/issues/103))
+
+`--sourcemap=linked` appends a `sourceMappingURL` comment, so devtools fetches that file on every
+load. When the map is not in the served root the fetch fails — in exactly the session where
+someone is reading the console carefully for something else. It cost the reporter a wrong
+hypothesis while chasing a slow load.
+
+The uglier half was already fixed by #116 in this same release: the SPA fallback used to answer
+`.map` requests with the **HTML shell**, so devtools received a web page where a JSON map should
+be. Missing assets 404 now.
+
+The remaining half is a build-time warning naming the file and where it was expected. It checks
+what is **served**, not what was built — those differ whenever `bundleOutDir` is set, and the
+copy across is best-effort by design, so trusting the step is what let this ship. It warns rather
+than fails: a map is a debugging convenience and no site should fail to build without one.
+
+The check is a pure, tested function rather than an inline block, because the branch it lives in
+is one **this repo's own build never takes** — our bundle comes from `bin/dev.ts`, not from
+`buildSite`. That is exactly why the bug reached an adopter instead of us.
+
+### `resolveUnder` asserts path containment instead of inheriting it ([#96](https://github.com/tonioloewald/tosijs-ui/issues/96))
+
+Defence in depth: there is no live traversal, and the reporter checked the classes carefully —
+`/../../../etc/passwd`, percent-encoded and double-encoded forms all stay inside the served root
+today. But they stay inside for two reasons the static handler does not own: the WHATWG URL
+parser collapses `../` before `.pathname` is read, and `.pathname` is never the raw request line.
+Both are properties of the **caller**, so a future call with a path from a config value, a
+manifest entry or a header inherits nothing. The asserted version already lived ten lines away
+in the same file.
+
+Now an exported, tested predicate — a test that went through the server would prove nothing,
+since the URL parser makes a violation unreachable from outside.
+
+### `bun run stop` — stop THIS project's dev server, not every one on the machine ([#117](https://github.com/tonioloewald/tosijs-ui/issues/117))
+
+There was no way to stop a dev server, so what everyone reached for was
+`pkill -f 'bun bin/dev.ts'` — which matches **every** dev server on the machine, because every
+project on this pipeline runs an identical command line. A sibling checkout, a worktree or
+another agent's session died to a command that reads as "restart mine". Observed five times in
+one working day, twice while a tunnel link was in use by a remote reviewer.
+
+The record needed for this already existed: the build lock stores `pid`, `port` and `root`,
+per-project, with staleness decided by liveness rather than age. It needed a reader and a
+command. `bun run stop` (or `bun bin/dev.ts --stop`) signals that pid and nothing else, and says
+plainly when nothing is running.
+
+### The dev server can no longer die silently ([#91](https://github.com/tonioloewald/tosijs-ui/issues/91))
+
+Reported after a ~9.4h run: `pgrep` said running, `curl` got nothing, the last log line was a
+**successful** build, and there was no error, signal or exit anywhere. Every diagnostic a person
+would reach for answered "fine"; it was found the next day because a human said the site was
+down.
+
+Worth correcting the report's own diagnosis, because it does not survive the evidence: the idle
+path **announces itself** before exiting, and no such line was logged — so the idle timeout is
+not what stopped that listener. What did is still unknown, which is exactly why the fix targets
+the symptom rather than a cause.
+
+The health tick now probes the server's own listener (`GET /__alive`, a bare 204 that
+deliberately does **not** count as activity — a self-check that did would hold the idle timer
+open forever). Two consecutive failures and it exits non-zero with an explanation. A process that
+cannot serve has no value, and the one useful thing left to it is to stop claiming to be alive.
+
+### `tosijs-tunnel --link` stops printing links that cannot work ([#94](https://github.com/tonioloewald/tosijs-ui/issues/94))
+
+`--link` asks the dev server for a token, which succeeds whether or not a tunnel exists. The URL
+is well-formed and the token is real — it just answers 503, because nothing is listening
+upstream. Printed with exit 0 and no comment, that is indistinguishable from the far side being
+down.
+
+It still prints the link, since you may be about to start the tunnel, but it now says so and
+exits non-zero, so a script treating 0 as "a usable link was produced" is telling the truth.
+
+### Doc tests survive a context key with a slash in it ([#111](https://github.com/tonioloewald/tosijs-ui/issues/111), [#112](https://github.com/tonioloewald/tosijs-ui/issues/112), [#109](https://github.com/tonioloewald/tosijs-ui/issues/109))
+
+Context keys become **function parameter names** — the runner builds each block as
+`new Fn(...contextKeys, body)`. `test-harness.ts` carried its own copy of the rule that turns a
+key into an identifier, `key.replace(/-/g, '')`, which strips hyphens and leaves slashes and
+`@`. So an ordinary specifier like `'tosijs-3d/demo-utils'` became the parameter name
+`tosijs3d/demoutils`, and **every test in that file died before one of them ran** with V8's
+`Arg string terminates parameters early`. The examples on the same page rendered fine, because
+they went through the shared sanitiser — so nothing looked wrong except a red badge.
+
+One implementation now, in `code-transform.ts`, used by all five call sites. It also handles
+what the shared version had never needed to: a leading digit (`'3d-tools'`), a reserved word
+(`'class'`), and a key that reduces to nothing.
+
+**Two keys that reduce to the same identifier now throw, by name.** Quietly suffixing the second
+would leave one module bound to a name no rewritten import references — undefined at runtime with
+nothing to read. The message says which two keys and what to do:
+
+```
+example context keys "tosijs-3d" and "tosijs/3d" both reduce to the identifier "tosijs3d",
+so an import from one of them could not be told from the other. Rename one of the context keys.
+```
+
+There is also a structural test asserting **nothing outside `code-transform.ts` sanitises a
+context key**. That is the one that would have caught this: every unit test of the shared helper
+passes with the divergent copy restored, because they exercise the helper rather than the call
+site — which is exactly how the bug survived.
+
+### A missing asset 404s instead of impersonating a page ([#116](https://github.com/tonioloewald/tosijs-ui/issues/116))
+
+The dev server fell back to the SPA shell for **any** unknown path, so a missing
+`waterbump.png` answered `200 text/html`. Babylon's `Texture` fetched it, failed to decode a web
+page as an image, and substituted its checkerboard — a missing asset presented as a _styling
+choice_, and was complimented before it was diagnosed.
+
+Unknown **routes** still get the shell, because client-side routing depends on it. The
+distinguishing signal is a dot in the last path segment: an extension was asked for, so a file
+was meant. `/v1.2/guide` is still a route; `/thing.png` is not. The 404 names the path, because
+a bare "File not found" sends people to the wrong layer — the reporter went through their
+texture pipeline before suspecting the server.
+
+### `staticDirs` are watched, so a replaced asset is not served stale ([#110](https://github.com/tonioloewald/tosijs-ui/issues/110))
+
+`buildSite` copies `staticDirs` into the output on every build, but nothing watched them — so
+re-exporting a GLB over `static/model.glb` left the previous copy served indefinitely, with no
+error and no hint. Both files exist and only their contents differ, which is the hardest version
+of stale to see, and the workaround people find is touching a source file to provoke a rebuild.
+
+Same shape as #49, where `docPaths` was the omission. Verified end to end: a replaced static file
+is now picked up in about half a second.
+
+### A lone custom element is no longer wrapped in a paragraph ([#115](https://github.com/tonioloewald/tosijs-ui/issues/115))
+
+Reported by tosijs-3d: a doc page whose entire content is one custom element — the case
+`layout: "full-screen"` exists for — got an element that would not fill. marked classifies raw
+HTML by tag name and cannot know whether an unknown tag is block or inline, so
+`<my-editor></my-editor>` alone on a line came out as `<p><my-editor></my-editor></p>`. That
+paragraph is auto-height, so `height: 100%` resolved against a **33px** box inside an 842px
+content area.
+
+Measured before and after on the same page: 33px, then **842 of 842** on all three engines. The
+comment promising "a definite height, so a child asking for `height: 100%` gets one" is finally
+true rather than aspirational.
+
+The unwrap is deliberately narrow, since a heuristic here earns its own bugs: it fires only when
+a paragraph's entire content is a single element whose tag name contains a hyphen — a custom
+element, the one case marked provably cannot classify. `<p><img></p>`, `<p><em>text</em></p>`
+and `<p>see <my-thing></my-thing> here</p>` are all left exactly as they are, and mutation
+testing covers both directions — unwrapping everything fails three tests, unwrapping nothing
+fails one.
+
+### The inline doc tier runs at two widths now
+
+The same gap, one level down: the doc-test runner's iframe was hardcoded to 800x600, so **every
+inline `test` block had only ever run wide**. Its size is now overridable, and the Playwright
+doc-test spec runs the whole tier a second time at 390x844.
+
+An iframe is a real viewport, so this is not a simulation — verified that
+`matchMedia('(max-width: 600px)')` matches inside a 390px frame and not a 1200px one, and that
+the override reaches the runner (390px frame, 386 inner; 800/796 without it).
+
+**Widths only, deliberately.** Touch cannot be emulated from inside a page: an iframe inherits
+the host's input characteristics, so `(pointer: coarse)` stays false and `maxTouchPoints` stays 0
+however small the frame is. `navigator.maxTouchPoints` _can_ be redefined, and doing so would be
+worse than skipping it — the property would lie while the media queries told the truth, so a test
+could pass against a page behaving as desktop. Touch belongs to a Playwright context
+(`hasTouch`, `devices[…]`); noted in `TODO.md` as worth its own spec, since everything
+touch-shaped here is currently tested only with a mouse.
+
 ## 1.12.4
 
 ### `.tjs` source files are documented again ([#108](https://github.com/tonioloewald/tosijs-ui/issues/108))

package/bin/tunnel.ts

@@ -191,6 +191,32 @@ if (has('link')) {
     `\n🔗 Edit link:\n   ${url}\n` +
       (code ? `\n   code:  ${code}   (case-insensitive)\n` : '')
   )
+
+  /*
+  A link nobody can reach is worse than no link.
+
+  `--link` asks the dev server for a token, which succeeds whether or not a tunnel exists — the
+  URL is well-formed and the token is real, it just resolves to a 503 from the reverse proxy
+  because nothing is listening upstream. Printed with exit 0 and no comment, that is
+  indistinguishable from the far side being down, and the reporter lost a chunk of an afternoon
+  to the difference (#94).
+
+  Checked AFTER printing, deliberately: the link is still the thing you asked for, and you may
+  be about to start the tunnel. What changes is that the output says so and the exit code agrees
+  — a script that treats 0 as "a usable link was produced" is now telling the truth.
+
+  `running()` is the same predicate `--status` uses, matching this project's own forward by its
+  exact ports and host rather than by an argv substring.
+  */
+  const forwards = await running()
+  if (forwards.length === 0) {
+    console.error(
+      `⚠️  No tunnel is running, so that link will answer 503.\n` +
+        `    The token is real — nothing is listening on the far side yet.\n` +
+        `    Start one with \`tosijs-tunnel\` (or \`bun run tunnel\`), then use the link.\n`
+    )
+    process.exit(1)
+  }
   process.exit(0)
 }
 

package/dist/code-editor.d.ts

@@ -30,6 +30,9 @@ export declare class CodeEditor extends WebComponent<CodeEditorParts> {
     private diffOverlay;
     private _pendingDiff;
     get showingDiff(): boolean;
+    diffResolvable: boolean;
+    diffOriginalLabel: string;
+    diffModifiedLabel: string;
     showDiff(on: boolean): void;
     static initAttributes: {
         mode: string;

package/dist/code-editor.js

@@ -24,6 +24,8 @@ body {
 | `mode` | `javascript`, `typescript`, `tjs`, `ajs`, `css`, `html`, `markdown` |
 | `disabled` | makes the editor read-only |
 | `original` + `showDiff(on)` | diff the current `value` against a baseline, as an overlay |
+| `diffResolvable` | make that overlay **resolvable**: each change gets keep/revert buttons, and the choices are applied to `value` when the diff closes |
+| `diffOriginalLabel` / `diffModifiedLabel` | what the two buttons say (default `Original`/`Modified`) |
 | `editor` | the underlying CodeMirror [`EditorView`](https://codemirror.net/docs/ref/#view.EditorView) (`undefined` until loaded) |
 | `undo()` / `redo()` / `canUndo()` / `canRedo()` | history control |
 | `tjsAutocomplete` | runtime-value autocomplete hooks (tjs mode) — see below |
@@ -38,6 +40,29 @@ runtime values** — including proxy members no static analysis can see:
 codeEl.tjsAutocomplete = { getLiveBindings: () => ({ app, elements }) }
 ```
 
+## Selective revert
+
+`showDiff(on)` shows a read-only diff. Set `diffResolvable` first and the overlay becomes a
+review surface instead: every change carries keep/revert buttons, defaulting to **keep**, and
+whatever you leave alone survives. This is what `<tosi-example>`'s **View changes** uses — you
+tried four things and three worked, so revert the one you regret rather than all four.
+
+The choices are applied when the diff **closes**, not as you click, and a `change` event fires
+if the text moved. That is deliberate: writing each choice straight back into `value` would
+feed the new text into the overlay's `modified`, and `<tosi-diff>` resets its decisions when
+either input changes — so live application would wipe the choices making it and renumber the
+hunks under the pointer.
+
+```typescript
+codeEl.original = savedSource
+codeEl.diffResolvable = true
+codeEl.diffOriginalLabel = 'Source'
+codeEl.diffModifiedLabel = 'Yours'
+codeEl.showDiff(true)
+// …user reverts a hunk or two…
+codeEl.showDiff(false)   // codeEl.value now reflects their choices
+```
+
 ## Bundling
 
 CodeMirror is a **lazy chunk**: with a bundler (ESM), a page that never uses
@@ -154,6 +179,17 @@ export class CodeEditor extends WebComponent {
             return this._pendingDiff ?? false;
         return !this.parts.diffHost.hidden;
     }
+    /*
+    Make the diff overlay RESOLVABLE, turning it from a review into selective revert.
+  
+    Off by default, so `showDiff()` stays exactly what it was. With it on, every change gets
+    keep/revert buttons and the ones you leave alone are kept — which is the useful default when
+    the "modified" side is your own edit: you are reverting the two lines you regret, not
+    re-accepting the twenty you meant.
+    */
+    diffResolvable = false;
+    diffOriginalLabel = 'Original';
+    diffModifiedLabel = 'Modified';
     showDiff(on) {
         if (!this.hydrated) {
             this._pendingDiff = on;
@@ -165,9 +201,32 @@ export class CodeEditor extends WebComponent {
                 this.diffOverlay = tosiDiff();
                 diffHost.append(this.diffOverlay);
             }
+            this.diffOverlay.resolvable = this.diffResolvable;
+            this.diffOverlay.originalLabel = this.diffOriginalLabel;
+            this.diffOverlay.modifiedLabel = this.diffModifiedLabel;
             this.diffOverlay.original = this.original;
             this.diffOverlay.modified = this.value;
         }
+        else if (this.diffOverlay !== undefined && this.diffResolvable) {
+            /*
+            Resolutions land on the way OUT, not as you click.
+      
+            Writing each choice straight back into `value` would feed the editor's new text into the
+            overlay's `modified`, and `<tosi-diff>` resets its decisions when either input changes —
+            by design, because choice #2 of the old diff is not choice #2 of the new one. Live
+            application would therefore wipe the very choices making it, and the hunks would
+            renumber under the pointer. Applying once, when the diff closes, sidesteps that
+            completely and matches how a reviewer thinks: decide, then commit.
+      
+            The `change` event matters as much as the value: it is how a host recomputes "does this
+            still differ from the source" after a partial revert.
+            */
+            const resolved = this.diffOverlay.value;
+            if (resolved !== this.value) {
+                this.value = resolved;
+                this.dispatchEvent(new CustomEvent('change', { detail: { value: resolved } }));
+            }
+        }
         diffHost.hidden = !on;
     }
     static initAttributes = {

package/dist/data-table.d.ts

@@ -341,6 +341,7 @@ export declare class TosiTable extends WebComponent {
     sortByColumn: (columnOptions: ColumnOptions, direction?: "ascending" | "descending" | "auto") => void;
     popColumnMenu: (target: HTMLElement, options: ColumnOptions) => void;
     get captionSpan(): ElementCreator;
+    labelAttrs(key: string, attr?: string): Record<string, string>;
     get visibleRows(): any[];
     get visibleSelectedRows(): any[];
     get selectedRows(): any[];