tosijs-ui 1.12.7 → 1.13.0

package/CHANGELOG.md

@@ -1,5 +1,318 @@
 # Changelog
 
+## 1.13.0
+
+### tosijs `^1.9.1` — and a console with nothing in it
+
+The peer floor moves to `^1.9.1`. **The binding reason is a type-surface change, not the console
+cleanup** — our emitted declarations now reference `TosiProps` and `TosiStyleSheet` (renamed
+upstream from `XinProps`/`XinStyleSheet`), so `dist/*.d.ts` _hard-requires_ a tosijs that exports
+them. An adopter on an older tosijs gets type errors, not warnings. The floor also carries
+tosijs's **agent-surface security fix**, and the deprecation cleanup below.
+
+**Migration note if you are on tosijs 1.7.x:** this floor takes you through **tosijs 1.8.0**,
+which its own notes describe as deviating from semver — it removed `data-ref` and `<xin-slot>`.
+Read tosijs's 1.8.0 entry before upgrading; that step is not automatic.
+
+Before 1.9.1, every page of every doc site logged warnings a consumer could not act on:
+
+- `xinValue, tosiValue, xinPath…` — tosijs reading its own deprecated proxy property
+  ([tosijs#31](https://github.com/tonioloewald/tosijs/issues/31)). Nothing in any consumer's
+  code caused it.
+- `bindText` / `bindList` — deprecated in 1.8, then **withdrawn as a category error**
+  ([tosijs#33](https://github.com/tonioloewald/tosijs/issues/33)). They are a pair: `bindList`
+  supplies the per-item template and `bindText` fills it, and `{ textContent: proxy }` was
+  never a replacement for the path form (measured: `textContent: '^.name'` inside a template
+  renders the literal string, `bindText: '^.name'` binds). `bindText`'s runtime warning
+  outlived its typings by one release and is gone in 1.9.1.
+
+Verified on a from-scratch build rather than assumed: **the three deprecation warnings above are
+gone.** An earlier draft of these notes claimed _zero console warnings_, and that was false — one warning remains and it is ours, not tosijs's. Instantiating `<tosi-tabs>` still logs an
+on-event collision from our deprecated `onCloseTab` alias, which the elements factory reads as
+event-handler sugar.
+`onCloseTab` is a deprecated alias we keep for compatibility, so removing it is a breaking change
+and waits for the next major. Stating it rather than claiming a clean console we do not have.
+
+### Live examples: pick a side by clicking, and see what actually changed
+
+Both diff views — the resolvable one and the read-only one behind `<tosi-code>`'s review
+overlay — now let you **click a coloured line** to take that side, and mark **the words that
+actually differ** more strongly than the line containing them. Dragging to select text does not
+change anything; those lines are also what you copy from.
+
+`<tosi-example>`'s widget bar used to stay **open after every action** — you clicked "maximize"
+and it sat there covering the corner of the thing you had just maximised, until you remembered
+to click the handle again. It now closes once you have actually done something, its controls are ordered by reach (maximize nearest the handle), and the handle is the
+tosi owl on a status-coloured badge — orange running, green passed, red failed.
+
+**Tapping that handle on a touch device no longer flashes the menu open and shut.** A touch
+device has no hover, but the browser still fires `pointerenter`/`pointerleave` around a tap, so
+the hover _peek_ opened the bar and then undid itself before the click pinned it — you tapped
+again believing it had failed, and that second tap closed it for real.
+
+### Source moved into the app menu
+
+The floating `<> Source` chip that sat over the content is gone; Source is a submenu of the app
+menu beside Language and Color Theme, and it disappears entirely on a page with no source file.
+
+### Security: cross-site requests can no longer reach the dev server's write endpoints
+
+`POST /__docstore/source` and `POST /__build` were gated on the **peer address alone** — no
+credential — and the handlers parse JSON regardless of `Content-Type`. That made a cross-site
+`fetch(…, {mode:'no-cors'})` a _simple_ request: no preflight, peer is `127.0.0.1`, gate passes.
+Any page you happened to visit while `bun start` was running could write any file under the repo
+root, `.git/hooks/*` included — code execution at your next git operation
+([#90](https://github.com/tonioloewald/tosijs-ui/issues/90)).
+
+All three state-changing endpoints — `/__docstore/source`, `/__build` and `/report` — now
+require the request to be same-origin, via one shared predicate rather than a term repeated per
+call site. It checks **both** `Sec-Fetch-Site` **and** `Origin`: the first is unforgeable but
+absent on Safari < 16.4, Firefox < 90 and older WKWebViews, and those browsers send the second.
+An earlier pass checked only the first and left exactly that population unprotected. Applied
+**on the non-tunnel path only** — the tunnel is legitimately cross-site and
+is gated by a session cookie instead. Non-browser callers (the CLI, `curl`) send no fetch
+metadata and are unaffected; the attack this closes is specifically a _browser_ being induced to
+make the request, and a browser always tells us.
+
+The prose in `dev-auth.ts` had claimed `SameSite=Lax` gave "free CSRF protection". That was true
+only of the tunnel path, which needs a cookie — the default loopback path needed nothing, so the
+stated defence never covered its own primary case.
+
+### New dev-server endpoint: `POST /__build` (loopback only)
+
+Called out under its own heading because it is a new HTTP surface on a tool people run all day.
+
+It exists so `bun run build` can ask a running dev server to build instead of refusing (below).
+It is gated exactly like `/__devlink`: **loopback and NOT via the tunnel**. Verified against a
+real server rather than reasoned about — an anonymous tunnel request gets `401` from the session
+gate, and an **authenticated** one gets `404` from this gate, which is the case that matters. A
+remote visitor triggering builds would be a denial of service at best, and runs the project's own
+build code at worst. `GET` does nothing.
+
+Nothing else about the build lock changed: two builders racing `rm -rf` on one output tree is
+still refused, and a stale lock still gets the old message.
+
+### ePub dates, and an `epub.modified` option
+
+`dcterms:modified` is the only date an ePub reader can surface, and it is baked into a
+committed, redistributed file — so it has to be deterministic _and_ coherent. The
+version-derived encoding introduced in this release **wrapped** — twice. First `1.13.24` and
+`1.14.0` produced the same instant; the repack then made `1.13.1-beta.1` byte-identical to
+`1.13.0`, collided `1.0.1000` with `1.1.0`, and sent a CalVer `2026.9.3` to the year 5872. Each
+attempt shipped a docblock asserting the ordering that execution disproved.
+
+So the promise is narrowed to what is actually needed and can actually be held: **the same
+version always yields the same instant, and different versions yield different ones.** It is no
+longer ordered, because nothing reads these dates as a sequence — a reader sees one date on one
+book — and a claim nobody needs, made three times and false three times, is worse than no claim.
+The test sweep is generated rather than hand-picked, which is what would have caught the
+adjacent-version collision.
+
+New: **`epub.modified`** in the site config. The derived date is synthetic — it looks like a
+date without being one — and until now an adopter had no way to publish the real one.
+
+That option shipped broken for a few hours and is worth recording: `modified` was written
+**above** a `...epubOpts` spread, and `epubOpts` _is_ `config.epub` — so the adopter's raw value
+overwrote the sanitised one. `'2026-09-03'` reached the OPF unnormalised and `'not a date'`
+reached it verbatim, and EPUB 3 requires exactly `CCYY-MM-DDThh:mm:ssZ`, so the obvious spelling
+of the new option produced a file EPUBCheck rejects. The option assembly is now an exported
+**`epubOptionsFor()`** with tests that drive **the call site**, not just the date function beside it
+— the third time in this release that a green test asserted a pure function whose only consumer
+threw the result away.
+
+### The book this project ships carries a real date again
+
+`docs/tosijs-ui.epub` is redistributed, and its OPF has no `dc:date` — so `dcterms:modified` is
+the only date a reader ever sees. The version-derived scheme hashed 1.13.0 to **2012**, fourteen
+years adrift, where v1.12.8's book carried a correct contemporary date. This repo now sets
+`epub.modified` explicitly, which is exactly what that new option is for; adopters who care
+about the date should do the same, and adopters who don't still get a deterministic one.
+
+A related tidy: a docblock asserting the monotonicity this function does not have had survived
+three rewrites by sitting forty lines above it in a different file, and was shipping in `dist/`.
+The behaviour is described in one place now.
+
+### One place decides the ePub date
+
+`buildEpub` — the public export, and what `bun book` calls — now defaults and validates
+`dcterms:modified` itself. It previously used `new Date()` with no validation, so the
+determinism fix and the `epub.modified` handling lived at a single `buildSite` call site that
+`bun book` never executed: that path still stamped a wall clock, re-dirtying the committed ePub,
+and still passed a date-only string into an OPF that EPUBCheck rejects.
+
+That is the fourth instance in this release of one shape: **a green test asserting a function
+whose only consumer discards the result.** The date function was correct and tested; the
+assembly threw its return value away. The predicate was correct and tested; two of three
+endpoints used it. The touch guard was correct; the test retyped it. And the fix for the
+_first_ three introduced the fourth, by testing a helper that one of two shipped paths called.
+
+The answer is not another helper — it is a single choke point every path already goes through,
+tested from the public entry point by asserting the OPF text.
+
+### Tests that can actually fail
+
+Two "regression tests" added earlier in this release were **tautologies**: each re-declared the
+production predicate inside the test file and asserted on the copy, so both passed forever and
+stayed green when the real code was broken. A mutation test in the pre-release review killed
+zero of them. They now mount the real `<tosi-pocket-bar>` and import the exported delegation
+predicate, and were re-mutated to confirm the opposite — deleting the touch guards and the
+pin-clear turns two tests red.
+
+A re-review then found the same shape one layer down: the delegated-build queue —
+`buildNow`/`buildWaiters` — had **zero** coverage, and an unconditional infinite loop passed the
+whole green suite. The loop is fixed (it started a build on every pass instead of once, spinning
+the dev server into ~30 builds and a `process.exit(1)` that blamed the user's watcher config),
+and the decision is now a pure exported function, `nextBuildStep()`, with tests for the
+contended orderings. `POST /report` was also found never to have received the CSRF gate — the
+term had been spliced into two call sites by hand and the third missed, which is why all three
+now share one named predicate.
+
+Recorded here rather than buried because it is the same failure this project's notes already
+describe from 1.9.0: work asserted in prose that the code did not do. A test that retypes the
+condition it is testing is that failure wearing a lab coat.
+
+### What delegation guarantees (and what it refuses)
+
+The delegation path above was hardened after a pre-release review found several ways it could
+report a success nobody got. Worth stating, because "my build tool said it built" is a claim you
+rely on:
+
+- **It proves the build was yours.** `holder.port` is validated before it reaches a URL, the
+  request carries `?root=`, and the reply carries `pid`/`root`/`outputDir` which must match the
+  lock and the tree you asked for. A planted lock plus any listener answering `{"ok":true}`
+  previously printed "rebuilt this tree" and exited 0 over an untouched tree — stale locks from
+  other projects are ordinary on a dev machine, one of them usually on the shared default port.
+- **It waits for the tree to settle**, not for whichever build finishes next — starting one
+  build and then parking, with a cap so a watcher that keeps firing degrades to a message
+  instead of a build storm. (The first attempt called `rebuild()` on **every pass**, and
+  `rebuild()` sets `pending` when a build is in flight — so the settled check could never pass
+  under contention and it re-armed forever, spinning the dev server into ~30 builds and a
+  `process.exit(1)` blaming the user's watcher config. It was correct when idle, which is why
+  it looked fine. A re-review caught it; the decision is now a pure function with tests for
+  the contended orderings, which had no coverage at all.) A reply used to be
+  released by an already-running build one line before a queued rebuild began wiping the output
+  directory — success reported while the tree was being emptied, right before the documented
+  `git add`.
+- **It does not believe a reply it does not recognise.** A dev server predating this endpoint
+  answers the POST with the SPA shell; that now reports "restart your dev server" instead of
+  accusing your build of failing. Dev servers here live for days running the code they loaded,
+  so that is the normal upgrade path.
+- **Its timeout is the server's real one.** The client promised ten minutes while `Bun.serve`
+  idles connections at 120s, so a _successful_ long build was reported as a failure. "Did not
+  answer in time — the build may still be running" is now distinguished from "unreachable".
+
+`<tosi-pocket-bar>` also gained a public `close()`. The live-example bar was setting `open =
+false` directly, which left the component's internal pin set — so it re-opened on hover, stuck
+open over the content, and the next handle tap did nothing. On touch, where this release removes
+the hover path, there was no way back at all.
+
+### Builds stopped fighting the dev server
+
+`bun run build` with a dev server running now **asks it to build** instead of refusing, and
+`bun run test-browser` uses its **own port (8798)** instead of reclaiming 8787 by killing
+whatever holds it. Both produced the same workflow — kill the server, build, forget to restart
+it — and the second twice took a live tunnel offline, where the symptom is a page reporting
+"offline" with no hint which half died.
+
+The generated ePub is **reproducible** now. It differed on every build, so it landed in every
+diff and made a clean tree impossible after building — two independent causes:
+`dcterms:modified` defaulted to `new Date()`, and the zip stored each file's mtime, and those
+files had just been written. Entry mtimes are normalised to a constant before zipping (zip has
+no flag for it; normalising the inputs is the standard fix), and the date is anchored to the
+last commit that touched `package.json` rather than to a clock or to HEAD. After
+commit-then-rebuild the tree carries one changed file (`docs/version.json`, which records the
+commit by design) where it used to carry 68 plus a binary.
+
+### Icons
+
+`shift` (⇧) — the standard shift-key outline, asked for by tosijs-3d and general enough to live
+here rather than in one consumer. `tab` (⇥) — an arrow pointing at a vertical bar, built on
+`arrowRight`'s proportions. And `fatArrowUp`/`fatArrowRight`/`fatArrowDown`/`fatArrowLeft`: one
+drawing and four rotations via the same redirect mechanism the arrow and chevron families use.
+
+The shift glyph is centred on 12,12 (apex y=4, base y=20; it was 3..20, half a pixel high) —
+invisible head-on, and what makes each rotation land square instead of drifting off-centre.
+
+With `delete`, `cornerDownLeft` and `command` already present, an on-screen keyboard now has
+everything except caps-lock.
+
+### Smaller things
+
+- **`<tosi-pocket-bar>` handles are brandable**: `--tosi-pocket-handle-bg`,
+  `--tosi-pocket-handle-radius` and `--tosi-pocket-handle-size`, all defaulting to exactly their
+  previous values, so nothing changes for an existing consumer. A circle needs all three —
+  `border-radius: 50%` on a content-sized flex button is an ellipse.
+- The live-example handle uses them for the owl badge, and its **controls were reordered** so
+  maximize sits nearest the handle and tests furthest.
+- The dead `.view-source` CSS went with the button it styled, rather than leaving rules for an
+  element nothing creates.
+- **`bindText` in `<tosi-table>` briefly moved to `textContent`, then reverted back to
+  `bindText`.** `data-table.ts:2179` holds a proxy, which is the only shape the replacement
+  accepts — but with the deprecation withdrawn upstream, keeping it would have left the file
+  using two idioms for the same job with nothing gained. Net change: zero lines.
+
+## 1.12.8
+
+### Diffs: pick a side by clicking it, and see what actually changed
+
+Two things, and they apply to **both** diff views — the resolvable one and the read-only one
+used by `<tosi-code>`'s review overlay and the doc-browser's before-save screen.
+
+**Clicking a coloured line picks that side**, equivalent to its button. The line is what a
+reader is already looking at and pointing at; reaching for a small button to say "this one"
+when the thing is under the cursor was friction with nothing behind it. Dragging to select
+text does **not** change anything — those lines are also what you copy from, and without that
+guard, selecting a line to copy it would silently flip the resolution and rewrite the value.
+
+**Within a changed line, the words that actually differ are marked** more strongly than the
+line around them. A whole-line wash says "something here changed", which for a one-word edit
+throws away most of the signal — so the line colour tells you which side you are on, and the
+run tells you what moved. `diffTokens(before, after)` and `tokenRunsForLines(lines)` are
+exported if you want that data without the DOM.
+
+Word runs, not characters: a character diff of `sat` → `sprawled` marks the shared `s` and
+produces confetti. Whitespace and punctuation are tokens so the runs **reassemble each input
+exactly** — a diff viewer that silently drops a space misrepresents the text it exists to show
+— and whitespace between two changed words is absorbed into the change, or `sat on` renders as
+two boxes with a hole punched between them. Lines over 400 tokens fall back to whole-line
+marking rather than locking a tab on a minified bundle pasted into a diff.
+
+The read-only view keeps its line order exactly. Pairing is computed per run of consecutive
+changed lines, so an interleaved edit is marked correctly without the reordering that the
+resolvable view's block grouping does.
+
+`tokenRunsForLines` returns a **dense** array — one entry per input line, `undefined` where a
+line has no runs. Worth stating because the obvious implementation (`new Array(n)`) is sparse,
+and `map`/`forEach` silently skip holes: fine for the indexed read it was written for, a trap
+for anyone iterating it.
+
+### Generated asset URLs are build-stamped
+
+`/doc-system.css` and the hydration bundle are now emitted with a `?v=` stamp taken from the
+same build identity that writes `/version.json`, so a page cannot claim one build while
+loading another's cached bundle. Stale filenames going stale is not hypothetical — it happened
+on this project's own doc site and cost a round of "is this a layout regression?" before
+turning out to be a cached bundle, with a hard reload as the fix nobody thinks to try.
+
+A query rather than content-hashed filenames, deliberately: `docs/` is committed in this repo
+and its siblings, so hashing would add and delete a file on every build and put churn in every
+diff.
+
+**The stamp is the project's own version**, so it moves once per release — the granularity at
+which a published site actually changes — and a rebuild between releases is byte-identical. The
+first attempt derived it from the commit, which was precise and unusable: it re-stamped all 68
+generated pages on every commit, and because the test lanes build too, it did not terminate
+(commit → build → 68 dirty → commit → build). The honest tradeoff of the version, stated rather
+than left to be discovered: two builds of the same version with different code share a stamp, so
+a mid-version redeploy can still serve a cached bundle. That is exactly the previous state — no
+worse — and it closes the case that actually bit, a cached bundle surviving _across_ releases.
+
+Cross-origin URLs are left alone — `scriptUrl` may point at a CDN, and busting someone else's
+cache was never the point — as are URLs that already carry a query or fragment.
+
+Consumers of `tosijs-ui/site` get this automatically; `generateSite` also takes an explicit
+`assetStamp` if you are driving it directly. Leave it unset and the output is unchanged.
+
 ## 1.12.7
 
 ### Live-example and doc-test failures now tell you where

package/bin/make-icon-data.js

@@ -334,6 +334,17 @@ const manualRedirects = {
   arrowDownRight: 'arrowUpRight90r',
   arrowDownLeft: 'arrowUpRight180r',
   arrowUpLeft: 'arrowUpRight270r',
+
+  // `shift` is the ⇧ key glyph and points UP, which is the wrong base for the
+  // `up-down-right-left/` folder convention (that expects a RIGHT-pointing base).
+  // Rather than redraw it sideways and make the keyboard glyph a rotation of an
+  // arrow nobody asked for, the four directions are declared here — the escape
+  // hatch this block exists for. The drawing is centred on 12,12 so each rotation
+  // lands square.
+  fatArrowUp: 'shift',
+  fatArrowRight: 'shift90r',
+  fatArrowDown: 'shift180r',
+  fatArrowLeft: 'shift270r',
 }
 Object.assign(iconRedirects, manualRedirects)
 

package/dist/diff.d.ts

@@ -39,6 +39,32 @@ export declare function resolveDiff(blocks: DiffBlock[], choices: DiffResolution
  * in `after`), in display order.
  */
 export declare function diffLines(before: string, after: string): DiffLine[];
+/** A run of text within a changed line, flagged if it is part of what actually differs. */
+export interface TokenRun {
+    text: string;
+    changed: boolean;
+}
+/**
+ * Word-level diff of two lines, as runs that reassemble each input exactly.
+ *
+ * Returns everything flagged `changed` when the lines are too long to diff cheaply, or when
+ * they share nothing — in both cases the containing line highlight already says it.
+ */
+export declare function diffTokens(before: string, after: string): {
+    removed: TokenRun[];
+    added: TokenRun[];
+};
+/**
+ * Token runs for each line of a FLAT line diff, pairing within each run of changed lines
+ * without reordering anything.
+ *
+ * The resolvable view groups changes into blocks, which reorders an interleaved edit
+ * (`-a +A -b +B` becomes `-a -b +A +B`) — better to resolve, but a changed rendering. The
+ * read-only view must keep its order exactly, and it turns out it does not have to give
+ * anything up for that: pairing is computed per run of consecutive non-context lines, and the
+ * lines are still emitted where they already were. Same marking, same order.
+ */
+export declare function tokenRunsForLines(lines: DiffLine[]): Array<TokenRun[] | undefined>;
 interface DiffParts extends PartsMap {
     body: HTMLElement;
 }
@@ -68,6 +94,11 @@ export declare class TosiDiff extends Component<DiffParts> {
             whiteSpace: string;
             wordBreak: string;
         };
+        '.diff-line .line-text': {
+            minWidth: string;
+            whiteSpace: string;
+            wordBreak: string;
+        };
         '.diff-line .marker': {
             textAlign: string;
             userSelect: string;
@@ -111,6 +142,22 @@ export declare class TosiDiff extends Component<DiffParts> {
             background: string;
             color: string;
         };
+        '.diff-line .text.changed': {
+            borderRadius: string;
+            padding: string;
+        };
+        '.diff-add .text.changed': {
+            background: string;
+        };
+        '.diff-remove .text.changed': {
+            background: string;
+        };
+        '.diff-line[data-choice]': {
+            cursor: string;
+        };
+        '.diff-line[data-choice]:hover': {
+            filter: string;
+        };
         '.diff-line.not-chosen': {
             opacity: string;
             textDecoration: string;