tosijs-ui 1.12.8 → 1.13.0

package/CHANGELOG.md

@@ -1,5 +1,256 @@
 # 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

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/doc-browser.js

@@ -190,8 +190,6 @@ const testTextColor = {
 };
 // Test indicator styles - widget inherits button styles from base stylesheet
 const testIndicatorStyleSpec = {
-    '.view-source': { opacity: '0.9' },
-    '.view-source:hover': { opacity: '1' },
     '@keyframes test-pulse': {
         '0%, 100%': { opacity: '1' },
         '50%': { opacity: '0.7' },
@@ -1116,10 +1114,18 @@ export function createDocBrowser(options) {
         editUI = { editor, doc, view: 'edit', original: content };
         setSourceView('edit');
     };
-    const openSourceMenu = (target) => {
+    /*
+    The Source items, separated from the popup that used to be their only home.
+  
+    They now hang off the app menu as a submenu, so this returns the ITEMS and lets the
+    caller decide where they appear — an empty array when the current doc has no source
+    file, which is how the host knows to omit the submenu entirely rather than showing an
+    empty one.
+    */
+    const sourceMenuItems = () => {
         const doc = docs.find((d) => String(d.filename) === String(app.currentDoc.filename));
-        if (!doc)
-            return;
+        if (!doc || !doc.path)
+            return [];
         const fileName = (path) => path.split('/').pop() || path;
         // While editing, the Source menu becomes the editor's controls (no separate
         // toolbar). Otherwise it offers entry points: edit, view on GitHub, download.
@@ -1189,13 +1195,7 @@ export function createDocBrowser(options) {
                     }),
                 },
             ];
-        popMenu({
-            target,
-            // The trigger is position:fixed at the top-right; `auto` placement opens
-            // upward into zero space and collapses the menu, so open below-left.
-            position: 'sw',
-            menuItems,
-        });
+        return menuItems;
     };
     // ── Hierarchical nav (path routing) ───────────────────────────────────────
     // Build nested <details> from the doc tree; current-highlight, test status,
@@ -1365,47 +1365,7 @@ export function createDocBrowser(options) {
             overflowY: 'scroll',
             height: '100%',
         },
-    }, button({
-        class: 'view-source',
-        style: {
-            display: 'flex',
-            alignItems: 'center',
-            gap: '6px',
-            position: 'fixed',
-            top: 'calc(var(--xin-header-height, 60px) + 5px)',
-            right: '5px',
-            // Above the code editor (which fills the content area); below the
-            // popped menu (z 1002).
-            zIndex: '100',
-            fontSize: '0.875em',
-            color: 'var(--brand-color, inherit)',
-            // Solid, theme-aware chip so it stays legible over the editor.
-            background: 'var(--background, white)',
-            border: 'none',
-            borderRadius: '4px',
-            padding: '3px 8px',
-            boxShadow: '0 1px 4px #0003',
-            cursor: 'pointer',
-            transition: 'opacity 0.2s ease',
-        },
-        // Opacity + :hover live in CSS (.view-source) — a JS hover handler
-        // here would fade the delegation root (the whole page), not the button.
-        onClick(event) {
-            // tosijs delegates clicks, so event.currentTarget is the delegation
-            // root, not the button — resolve the real trigger for menu anchoring.
-            const btn = event.target.closest('.view-source');
-            if (btn)
-                openSourceMenu(btn);
-        },
-        bind: {
-            value: app.currentDoc,
-            binding(element, doc) {
-                // Show when there's a source file to edit/view (any doc with a
-                // path); the menu handles dev-vs-GitHub availability per item.
-                element.style.display = doc.path ? 'flex' : 'none';
-            },
-        },
-    }, icons.code({ style: { _xinIconSize: 16 } }), 'Source'), docContent)));
+    }, docContent)));
     // Render the landing doc (adopts pre-rendered HTML when hydrating).
     showDoc(currentDoc);
     // Inject test indicator styles
@@ -1813,6 +1773,19 @@ export function createDocBrowser(options) {
         startBackgroundTests();
         testManager.enabled.observe(startBackgroundTests);
     }
+    /*
+    The host assembles the Source submenu from these.
+  
+    It used to be a floating `<> Source` chip pinned over the content — a second, separate
+    affordance for something the app menu was already the home of. Handing the ITEMS to the
+    host instead means one menu, and the host decides placement; an empty array (a doc with
+    no source file) tells it to omit the submenu rather than show an empty one.
+  
+    Same seam `navigate` uses below: a property on the returned element, because the host is
+    a different component that already holds this reference.
+    */
+    ;
+    container.sourceMenuItems = sourceMenuItems;
     // Memory routing: let the host drive navigation programmatically (by slug) and
     // read the current slug back, so the browser can live in a floating panel etc.
     if (memoryRouting) {

package/dist/doc-system/doc-system.js

@@ -337,6 +337,23 @@ export class TosiDocSystem extends Component {
                         })),
                     });
                 }
+                /*
+                The Source submenu, contributed by the doc browser.
+      
+                It replaces a floating `<> Source` chip that sat over the content — a second
+                affordance for something this menu was already the natural home of. The browser
+                returns an empty array when the current doc has no source file, and an empty
+                submenu is worse than none, so this omits it entirely in that case.
+                */
+                const sourceItems = this.browser?.sourceMenuItems?.() ?? [];
+                if (sourceItems.length > 0) {
+                    menuItems.push({
+                        caption: 'Source',
+                        icon: 'code',
+                        menuItems: sourceItems,
+                    });
+                    menuItems.push(null);
+                }
                 menuItems.push({
                     caption: 'Color Theme',
                     icon: 'rgb',

package/dist/doc-system/site/dev-auth.d.ts

@@ -221,6 +221,12 @@ export declare function sessionCookie(token: string, maxAgeMs?: number): string;
  * defeat the entire design.
  */
 export declare function urlWithoutToken(rawUrl: string, param: string): string;
+export declare function isSameOriginRequest(request: {
+    url?: string;
+    headers: {
+        get(name: string): string | null;
+    };
+}): boolean;
 export declare function mayWriteSource(opts: {
     /** did this arrive on the loopback listener dedicated to the tunnel? */
     viaTunnel: boolean;

package/dist/doc-system/site/dev-auth.js

@@ -479,6 +479,88 @@ anything arriving there is treated as remote no matter what it claims.
                because "local" is exactly what a tunnel counterfeits.
   direct     → a loopback peer is sufficient; you are at this keyboard.
 */
+/*
+CSRF: a loopback peer is not a same-origin caller (#90).
+
+`mayWriteSource`'s direct path is peer-address-only — no credential — and the handlers parse
+JSON regardless of `Content-Type`. That makes a cross-site `fetch(…, {mode:'no-cors'})` with a
+CORS-safelisted type a SIMPLE request: no preflight, peer is 127.0.0.1, gate passes. Any page
+the developer happens to visit could therefore write any file under the repo root — including
+`.git/hooks/*`, i.e. code execution at the next git operation. `POST /__build` then turns that
+into "and run it now".
+
+The file already claimed CSRF protection from `SameSite=Lax`, and that is true only of the
+TUNNEL path, which needs a cookie. The default loopback path needs nothing, so the stated
+defence never covered the primary case.
+
+Fetch metadata is the fix, and it is cheap: browsers send `Sec-Fetch-Site` on every request and
+scripts cannot forge it. A same-origin page sends `same-origin`; a page on evil.example sends
+`cross-site`. Non-browser callers (our own CLI, curl) send neither header — so the rule must
+accept ABSENCE, or it breaks every legitimate tool. That is not a hole: the attack this closes
+is specifically "a browser the developer is using is induced to make the request", and a
+browser always tells us.
+
+Applied ONLY on the non-tunnel branch. UPSTREAM.md records that rejecting cross-site outright
+breaks the tunnel case, where the widget legitimately calls :8700 from a page on :3000 — that
+path is gated by a session cookie instead.
+*/
+export function isSameOriginRequest(request) {
+    /*
+    TWO signals, because neither alone covers the population.
+  
+    `Sec-Fetch-Site` is the strong one — unforgeable by script, sent on every request by any
+    engine that has it. But Safari < 16.4, Firefox < 90 and older WKWebViews send NO fetch
+    metadata, and an earlier version of this function allowed absence outright with a comment
+    claiming "a browser always sends it". That was false for exactly the browsers a developer
+    might have open, leaving them in the pre-fix position: a forged simple request writing
+    `.git/hooks/pre-commit`.
+  
+    `Origin` closes that gap, because those same browsers DO send it on cross-origin POSTs. So:
+    refuse a cross-site `Sec-Fetch-Site`, and independently refuse an `Origin` that is not ours.
+  
+    Absence of BOTH is still allowed, and that is deliberate rather than an oversight: our own
+    CLI and `curl` send neither, and the threat model here is a browser being induced to make
+    the request. A request carrying no browser fingerprint at all is not that.
+    */
+    const site = request.headers.get('sec-fetch-site');
+    if (site !== null && site !== 'same-origin' && site !== 'none')
+        return false;
+    const origin = request.headers.get('origin');
+    /*
+    NOTE there is no `origin !== 'null'` exemption, deliberately.
+  
+    An earlier version had one, and it was the single worst value to allow: `Origin: null` is
+    exactly what a sandboxed iframe, `srcdoc`, a `data:` document and a cross-origin-redirected
+    POST send — i.e. the one Origin an attacker can choose. Modern engines stayed protected only
+    because they ALSO send `Sec-Fetch-Site: cross-site`; the unprotected set was precisely the
+    old-browser population this Origin check exists for. Nothing we ship requests from an opaque
+    origin, so the exemption bought nothing. It now falls through to the unparseable-origin
+    refusal below.
+    */
+    if (origin !== null) {
+        // Compare against the origin the request was actually addressed to, which is what the
+        // browser would have had to match. `Host` is what the client dialled.
+        const host = request.headers.get('host');
+        let ours = null;
+        try {
+            ours = request.url !== undefined ? new URL(request.url).host : null;
+        }
+        catch {
+            ours = null;
+        }
+        const expected = ours ?? host;
+        let originHost = null;
+        try {
+            originHost = new URL(origin).host;
+        }
+        catch {
+            return false; // an Origin we cannot parse is not one we can accept
+        }
+        if (expected === null || originHost !== expected)
+            return false;
+    }
+    return true;
+}
 export function mayWriteSource(opts) {
     if (opts.viaTunnel)
         return opts.hasValidSession;

package/dist/doc-system/site/dev-server.d.ts

@@ -40,6 +40,19 @@ export declare function resolveWatchPaths(config: {
 declare global {
     var Bun: any;
 }
+/**
+ * What a delegated build should do next, given the queue's state.
+ *
+ * Extracted and exported because the loop that used to be inline shipped an unbounded rebuild
+ * storm — `rebuild()` on every iteration re-queued the very build being waited on — and no test
+ * could reach it. This is the whole decision, and it is pure.
+ */
+export declare function nextBuildStep(state: {
+    attempt: number;
+    building: boolean;
+    pending: boolean;
+    maxAttempts: number;
+}): 'start' | 'wait' | 'settled' | 'gave-up';
 export declare function resolveHaltijaChannel(cwd?: string, env?: Record<string, string | undefined>): {
     argv: string[];
     describe: string;