tosijs-ui 1.12.1 → 1.12.3

package/CHANGELOG.md

@@ -1,5 +1,262 @@
 # Changelog
 
+## 1.12.3
+
+### Back now has layout coverage, because a reader noticed before the tests did
+
+Reported from the keyboard as "sometimes the full-screen page and the full-screen page with the
+nav open look like different history entries". Measured, it is neither history nor
+inconsistent: the nav toggle creates **no** history entry (`history.length` unchanged across
+repeated toggles, URL unchanged). What happens is that **Back re-asserts the page's declared
+layout** and discards the override — so leaving a page with the nav open and returning finds it
+closed.
+
+That is defensible and it is what ships: a full-screen page is full-screen whenever you arrive
+at it. Whether Back should instead restore what you left is now an open decision in `TODO.md`,
+with the measurements attached, rather than whatever fell out of the implementation.
+
+The gap the report exposed was in the tests, not the feature: `doc-system.pw.ts` already covered
+Back for URL, title and content, but nothing checked its effect on **layout**, and every layout
+test reached its pages by clicking links. Both directions are covered now — and labelled by what
+they actually do, since one is a genuine regression test (dropping `removeAttribute('data-layout')`
+on navigation fails it) and the other is a contract tripwire that survives every mutation tried
+against it. A test that cannot fail is usually decoration; that one is deliberate, and saying so
+is the difference.
+
+### The dev server sends `Cache-Control: no-store` on everything
+
+It previously sent no `Cache-Control` at all, and that is not neutral: a browser may invent a
+freshness lifetime when you decline to state one, and Safari is the most willing to. So the dev
+server would rebuild correctly while the browser kept serving the previous build — which
+presents as "my fix did not work", and is only escaped by emptying the cache by hand. It cost
+exactly that here: a bug was reported against code that had already been fixed.
+
+All three of the file-server's exits are covered — injected HTML, compressed assets, and
+binaries that stream untouched — because they are separate responses and adding the header to
+the obvious one is precisely how the other two get missed. Each is independently
+mutation-verified.
+
+**Dev server only.** The built site in `docs/` is unaffected; it is a static site for a real
+host, and telling a CDN never to store it would be actively wrong.
+
+### `layout: "full-screen"` — and `<tosi-sidenav alwaysCompact>` underneath it
+
+`full-width` shipped in 1.12.2 and `full-screen` did not, because it needed something from the
+sidenav that did not exist. It exists now, and it is one line rather than a new layout.
+
+**`<tosi-sidenav>` gained `navVisible`** — the one control a "show me the navigation" button
+needs. Read it, flip it:
+
+```js
+sidenav.navVisible = !sidenav.navVisible
+```
+
+It resolves what hiding the nav _means_ at the current width — forcing compact on a wide screen,
+simply showing the content on a narrow one — so no caller has to know, and a narrow-screen
+request does not outstay itself when the window is widened. `layout: "full-screen"` uses the
+same property, so the feature is general rather than something the doc-browser knows a trick
+about.
+
+**And `alwaysCompact` underneath it.** Compact mode already shows the nav _or_ the content
+and takes turns between them — which is precisely what a full-screen page wants — so this just
+removes the width test rather than adding a second way to lay out. It is a named state and not a
+`minSize` no viewport can reach, because the second one works and reads as a bug to the next
+person.
+
+**`layout: "full-screen"`** then means: no reading measure, no nav, no gutter, and a content area
+with a real height — so a demo, a canvas or an embedded app can ask for `height: 100%` and get
+it. There is a [demo page](/full-screen-demo/), and the navigation button works there: it
+returns you to the normal layout rather than replacing the content with a full-screen nav, and
+it **stays offered** so you can go back. Riding `compact` directly, as it used to, meant the
+button vanished on its own click and stranded you in the normal layout.
+
+Two inline styles were quietly breaking the promise. `.doc-content` receives both its
+`max-width` and its `padding` inline from the doc-browser, so no stylesheet could override
+either — a full-screen page rendered inset by 32px, in a box that collapsed to its content
+height instead of filling. `padding` now routes through `--doc-content-padding`, the way the
+measure already did.
+
+Navigating away restores the nav, and a reader's override lasts until they navigate rather than
+beyond it — **including Back**, so a full-screen page is full-screen whenever you arrive at it.
+That is predictable, but it does mean leaving a page with the nav open and returning finds it
+closed; whether Back should instead restore what you left is noted in `TODO.md` as a decision
+rather than left to whatever fell out of the implementation. Both directions are mutation-verified, which caught a test that _looked_ like it
+covered the second one and did not: it routed through a prose page, which reset the state as a
+side effect.
+
+Before hydration there is no sidenav at all, just static markup, so a stylesheet rule covers the
+first paint. Those rules select `.doc-nav.doc-nav` — the class deliberately repeated — because
+the pre-hydration layout further down the same sheet has identical specificity, and winning on
+source order works right up until someone reorders the spec.
+
+## 1.12.2
+
+### `haltijaDev: 'tunnel'` — let an agent drive a page running in a headset (#104)
+
+`haltijaDev: true` is localhost-gated, and that gate is exactly what stopped the feature
+working where it is worth the most. Debugging in a VR headset is close to blind: no readable
+console, no devtools, no way to inspect the DOM without taking it off — and taking it off is
+the thing you cannot do, because the bug is usually _about_ being in it.
+
+Set `haltijaDev: 'tunnel'` and the channel is also served **same-origin over the tunnel**.
+Redeem an edit link on the device, load the page, and it shows up in `hj windows` like any
+other — `hj eval`, `hj navigate`, `hj tree` all work against it, and `hj` never learns the
+page is remote.
+
+**Why it works at all, and why it needed no change from haltija.** The page **dials out**:
+`component.js` reads `window.__haltija_config__.serverUrl` and falls back to localhost only
+when that config is absent. So nothing has to reach _into_ a headset — the dev server sets
+the config itself, serves the component from the page's own origin, and relays the WebSocket
+to the local channel. The upstream `dev.js`/`inject.js` chain is skipped entirely; both files
+carry their own localhost gates and all three of their hardcoded `https://localhost:8701`
+URLs would resolve on the **headset** rather than on your machine.
+
+**A separate opt-in, deliberately.** `true` means "an agent may drive the page on this
+machine". Upgrading must never silently turn that into "wherever it is reachable", so
+`'tunnel'` is its own value — and `HALTIJA_DEV=1` does **not** enable it, because that
+variable is a convenience toggle and this is not a convenience.
+
+**What authorizes it:** a live dev session cookie — the same credential that gates source
+writes, via the same predicate (`mayDriveWithAgent` delegates to `mayWriteSource`, and a test
+asserts they agree on every input). Driving a page with an agent is at least as powerful as
+writing source, so it gets no weaker a gate. What authorizes is the **listener**, never the
+peer address: a reverse tunnel counterfeits "local" by construction. Unauthorized requests
+get **404**, not 403 — whether a project enabled the bridge is nobody's business but the
+session holder's.
+
+Verified end to end rather than by inspection: a real browser on the tunnel origin stores the
+session, receives the loader, resolves `serverUrl` to its own origin (not `localhost:8701`),
+attaches the widget, opens the relayed socket, appears in `hj windows`, and answers `hj eval`
+and `hj navigate`.
+
+### Dragging works on Firefox now — every draggable, not just table columns ([#107](https://github.com/tonioloewald/tosijs-ui/issues/107))
+
+**The first drag on a freshly-loaded page did not work in Firefox.** The thing you grabbed
+stayed put and random text highlighted instead; it only started behaving once you had clicked
+somewhere — anywhere — to settle Firefox's selection state. Land on a page and drag a column
+edge, which is an entirely ordinary thing to do, and the first attempt failed.
+
+This affected **every** `trackDrag` consumer — `<tosi-sizer>`, `<tosi-float>`,
+`<tosi-editable-rect>` and `<tosi-table>` column resizing — and had done since the drag tracker
+landed in **v0.5.1**. Measured with no prior click: `<tosi-sizer>` did not move at all, a table
+column applied one 12px step and froze. All three engines now behave identically (150 → 210 →
+270 on the same gesture, and nothing selected).
+
+Two parts, because either alone does nothing. `trackDrag` calls `preventDefault()` on the
+initiating mousedown, which is narrow rather than blunt — it only ever runs once a component has
+already decided a drag is starting, so ordinary clicks, focus and selection are untouched. And
+`<tosi-sizer>`, `<tosi-float>` and `<tosi-editable-rect>` had to stop registering their
+**mousedown** listeners as `passive`, because a passive listener makes `preventDefault` a silent
+no-op — which is exactly why the table (whose listener was never passive) improved first while
+the others stayed dead. Nothing is lost: `passive`'s practical value is silencing the console
+warning about handlers that delay scrolling, and that warning only ever applied to touch and
+wheel. `touchstart` stays passive.
+
+It is Firefox behaving badly, and that is a diagnosis rather than an excuse — the workaround is
+cheap and users do not care whose bug it is.
+
+### Page metadata: `layout: full-width`, so a route can leave the reading column ([#105](https://github.com/tonioloewald/tosijs-ui/issues/105))
+
+Prose wants a measure — 44em is roughly what people read comfortably, and it stays the default.
+But a demo, a dashboard, a wide table or a canvas is _worse_ squeezed into a column, and having
+to pick one habit for the whole site is what makes people build a second site. Now a page can
+opt out, the same way it sets `pin` or `order`:
+
+```markdown
+<!--{ "layout": "full-width" }-->
+```
+
+or `layout: full-width` in YAML frontmatter. **This project's own README uses it.**
+
+Stamped into the served HTML rather than applied on load, so the first paint is already right —
+a layout applied by script would show the reading column and snap wide, the flicker
+pre-rendering exists to prevent. Client-side navigation keeps it in step **in both directions**;
+that second direction is the one a naive implementation forgets, and it has its own test
+(mutation-verified: dropping the clear-on-navigate fails it, dropping the static stamp fails
+three more including first paint).
+
+**`layout: "full-screen"` is not implemented and is rejected with a message rather than
+half-honoured.** It needs a collapsed state on `<tosi-side-nav>`: after hydration the nav
+carries an inline `display`, and side-nav sets its width as an inline property, so a stylesheet
+cannot override either without `!important` — and hiding side-nav itself hides the content too,
+since it wraps both. A value that dropped the measure while leaving the chrome exactly where it
+was would be reported as a bug, correctly. Tracked in `TODO.md`.
+
+### `<tosi-table>`: a column drag no longer dies when `columns` is reassigned under it
+
+The other half of the reporting app's "resize funkiness", and a different defect from #102's
+torn grid — this one is not a mismatch at all. `resizeColumn` captured the `ColumnOptions`
+object and mutated it for the whole drag, and that object stops being the table's the instant a
+caller assigns a new `columns` array. Which the app does on a page-size change, and a page-size
+change is a very likely thing to happen while someone is dragging a column edge. From then on
+the drag wrote widths into an orphan: pointer moving, column not moving, nothing reported.
+
+The drag now re-resolves the column by `prop` each step — ending cleanly if it is gone, and
+rebasing on the new width if the object was merely replaced. Confirmed pre-existing rather than
+introduced by 1.12.1: reverting that fix leaves the drag equally dead.
+
+### Known: column resize does not work on Firefox at all ([#107](https://github.com/tonioloewald/tosijs-ui/issues/107))
+
+Found while investigating the above, and it is the bigger problem. On Firefox a **plain** column
+drag — no reassignment anywhere near it — applies one step and freezes: +60px reaches 162 and
++120px still reads 162, against 210 then 270 on chromium and webkit. A document-level capture
+listener shows Firefox stops delivering `mousemove` to the page entirely after the first event,
+so no callback can run.
+
+The cause looks to be `trackDrag` listening on a full-screen overlay while Firefox keeps
+implicit mouse capture on the element that received the `mousedown`. The fix is Pointer Events
+with explicit capture, and `trackDrag` is shared by every draggable affordance — so it wants
+doing deliberately, with the others re-tested on Firefox at the same time, rather than as a
+footnote to this release. Ruled out first: it is not the DOM being rebuilt under the drag
+(deferring renders changes nothing) and not #102 (reverting that changes nothing).
+
+### `tosijs-release-notes`: the bump gate stops blocking on dev tooling
+
+Two fixes, both hit while cutting this release — which is the only way anyone finds them.
+
+**A dev-tooling path with a security surface now WARNS instead of blocking a patch.** Every
+path on that list is development tooling — a dev server, a tunnel, a deploy script — and none
+of it runs in an end user's browser as part of an adopter's app. Halting a release over it
+spends the maintainer's attention on the release with the least at stake, and a guard that
+cries wolf gets overridden or deleted, taking the case it was _right_ about with it (#79, a
+loosened dev-server default shipped as a patch). The warning keeps that signal and stops
+charging for it. A gate that genuinely should block would have to key on code an adopter
+**ships**, which none of these are.
+
+**The blocking branch offered advice it could not honour.** It said "explain in the notes why
+this does not reach anyone" — but `bumpConcerns` never sees the notes, so nothing you wrote
+could satisfy it, and the only way forward was to work that out by reading the tool's own
+source. Same defect this project already fixed in the tunnel's 401 page. It now says "cut a
+minor", which is the only thing that ever worked.
+
+### Security-relevant paths that changed, and why this is still a patch
+
+`dev-auth.ts` — the module that decides who may do privileged things — changed in this
+release, and a patch touching it deserves a heading rather than a footnote.
+
+**The change is purely additive, and that is checkable rather than asserted.** The diff against
+1.12.1 removes **zero lines**, and `mayWriteSource` is **byte-identical** to 1.12.1. What was
+added is one new exported function, `mayDriveWithAgent`, whose entire body delegates to
+`mayWriteSource` — with a test asserting the two agree on every combination of `viaTunnel`,
+`hasValidSession` and peer address, so they cannot drift apart later without that test going
+red.
+
+**Nothing reaches an existing adopter.** The new predicate is consulted only by the
+`/__haltija/` routes, which exist only when `haltijaDev: 'tunnel'` is set. Every existing
+authorization decision — source writes, link minting, session validation — is executed by the
+same bytes as in 1.12.1. If you have not opted in, the reachable behaviour of this release is
+identical to 1.12.1.
+
+**What it would mean if you do opt in:** a live dev session cookie becomes sufficient to let an
+agent drive your page over the tunnel, in addition to editing source. That is a real widening
+of what a session can do, which is why it is a distinct config value and not implied by
+`haltijaDev: true`.
+
+**A patch, not a minor**, despite reading like a feature: it is a new optional _value_ on an
+existing config field, plus routes that exist only under it. `haltijaDev: true` behaves exactly
+as before and nothing is removed or renamed, so the contract a patch carries — it does not
+break you — holds.
+
 ## 1.12.1
 
 ### The Playwright lane no longer fights itself

package/README.md

@@ -1,6 +1,6 @@
 # tosijs-ui
 
-<!--{ "pin": "top", "headTitle": "tosijs-ui — robust, standards-based web components", "description": "A small, fast library of standards-based web components (data tables, dialogs, forms, rich text, carousels, and more) built on tosijs — smaller and faster than a React app, with no virtual DOM.", "keywords": "web components, custom elements, tosijs, data table, dialog, form, rich text, no virtual dom" }-->
+<!--{ "pin": "top", "layout": "full-width", "headTitle": "tosijs-ui — robust, standards-based web components", "description": "A small, fast library of standards-based web components (data tables, dialogs, forms, rich text, carousels, and more) built on tosijs — smaller and faster than a React app, with no virtual DOM.", "keywords": "web components, custom elements, tosijs, data table, dialog, form, rich text, no virtual dom" }-->
 
 [ui.tosijs.net live demo](https://ui.tosijs.net) | [tosijs](https://tosijs.net) | [discord](https://discord.gg/ramJ9rgky5) | [github](https://github.com/tonioloewald/tosijs-ui#readme) | [npm](https://www.npmjs.com/package/tosijs-ui)
 

package/bin/release-notes.ts

@@ -159,9 +159,16 @@ if (has('check')) {
     )
     for (const e of c.evidence) console.error(`   ${e}`)
     console.error(
+      /*
+      Advice you can actually follow. The blocking branch used to offer "explain in the notes
+      why this does not reach anyone" — which `bumpConcerns` cannot honour, because it never
+      sees the notes. A gate whose stated remedy is unrunnable leaves you re-reading your own
+      tool to find out what it wants, which is the same defect this repo fixed in the tunnel's
+      401 page.
+      */
       blocking
-        ? `\n   Cut a minor, or explain in the notes why this does not reach anyone.\n`
-        : `\n   Check it is genuinely additive.\n`
+        ? `\n   Cut a minor — this is not something the notes can talk you out of.\n`
+        : `\n   Check it is genuinely additive, and say what moved in the notes.\n`
     )
   }
 

package/dist/data-table.js

@@ -2149,9 +2149,29 @@ export class TosiTable extends WebComponent {
         this.style.cursor = column !== undefined ? 'col-resize' : '';
     };
     resizeColumn = (event) => {
-        const column = this.getColumn(event);
-        if (column !== undefined) {
-            const origWidth = Number(column.width);
+        const grabbed = this.getColumn(event);
+        if (grabbed !== undefined) {
+            /*
+            The drag follows the column BY PROP, not by holding the object it started on.
+      
+            A drag used to capture the `ColumnOptions` object and mutate it for its whole life. That
+            object stops being the table's the moment a caller assigns a new `columns` array — which
+            the reporting app does on a page-size change, and a page-size change is a very likely
+            thing to happen while someone is dragging a column edge. From then on the drag wrote
+            widths into an orphan: pointer moving, column not moving, nothing reported anywhere.
+      
+            Each step re-resolves from the current set instead. If the column is gone the drag ends
+            (its premise went with it); if the object was replaced but the prop survives, the drag
+            continues, rebased on the new width — `origWidth + dx` against a width the caller has
+            since changed would make the column jump by the difference.
+      
+            (Firefox needed a separate fix before any of this was observable there — it turned the
+            first drag on a fresh page into a text selection. See track-drag.ts, and #107.)
+            */
+            const prop = grabbed.prop;
+            let anchor = grabbed;
+            let anchorWidth = Number(grabbed.width);
+            let anchorDx = 0;
             const isTouchEvent = event.touches !== undefined;
             const touchIdentifier = isTouchEvent
                 ? event.touches[0].identifier
@@ -2163,9 +2183,16 @@ export class TosiTable extends WebComponent {
                 if (touch === undefined) {
                     return true;
                 }
-                const width = origWidth + dx;
-                column.width =
-                    width > this.minColumnWidth ? width : this.minColumnWidth;
+                const live = this.columns.find((c) => c.prop === prop);
+                if (!live)
+                    return true;
+                if (live !== anchor) {
+                    anchor = live;
+                    anchorWidth = Number(live.width);
+                    anchorDx = dx;
+                }
+                const width = anchorWidth + (dx - anchorDx);
+                live.width = width > this.minColumnWidth ? width : this.minColumnWidth;
                 this.setColumnWidths();
                 if (event.type === 'mouseup') {
                     return true;

package/dist/doc-browser.d.ts

@@ -22,6 +22,8 @@ export interface Doc {
     path: string;
     pin?: string;
     hidden?: boolean;
+    /** `'full-width'` drops the reading measure; `'full-screen'` also puts the nav away. */
+    layout?: 'full-width' | 'full-screen';
     testStatus?: 'passed' | 'failed' | 'pending';
     bakes?: Array<[string, {
         dialect: string;

package/dist/doc-browser.js

@@ -422,6 +422,16 @@ export function createDocBrowser(options) {
             docs,
             currentDoc,
             compact: false,
+            /*
+            Whether to OFFER the navigation button — deliberately not the same thing as `compact`.
+      
+            The button used to ride `compact` directly, which is right for a responsive page: wide
+            enough to show the nav beside the content, and there is nothing to toggle. But opening the
+            nav on a full-screen page leaves compact mode by design, and the button would vanish with
+            it — stranding the reader in the normal layout with no way back to full screen. So it is
+            offered whenever the layout is compact OR the page asked to be full-screen.
+            */
+            navToggle: false,
         },
     });
     const app = state[stateKey];
@@ -576,13 +586,58 @@ export function createDocBrowser(options) {
     // sidenav')`, which returns the FIRST sidenav in the document (an OUTER instance
     // when this one is an embedded, memory-routed browser).
     let sidenav = null;
+    /*
+    `full-screen` uses the sidenav's OWN compact behaviour rather than a new state.
+  
+    `<tosi-sidenav>` already does exactly what full-screen wants: compact mode shows the nav OR the
+    content, with `contentVisible` picking which. `alwaysCompact` keeps it in that mode at any
+    width, and `contentVisible` gives the page the whole box.
+  
+    Remembered rather than applied directly, because the sidenav is not there yet when the first
+    doc renders — `sidenav` is captured from its own change event, which fires on a state CHANGE
+    and so may never fire at all on a normal-width page.
+    */
+    let wantsFullScreen = false;
+    /*
+    What we last PUSHED onto the sidenav, so the user's own toggle is not overwritten.
+  
+    The first version applied the layout on every call, and `applyFullScreen` is called from the
+    sidenav's change handler — so clicking "navigation" flipped `contentVisible`, the sidenav
+    changed state, the handler fired, and the layout was re-applied on top. The nav button looked
+    live and did nothing. Applying only on TRANSITION means a full-screen page sets itself up once
+    and then leaves the reader alone.
+    */
+    let appliedFullScreen = null;
+    /** Offer the button when there is something to toggle: a compact layout, or a full-screen page. */
+    const refreshNavToggle = () => {
+        app.navToggle = (Boolean(sidenav?.compact) || wantsFullScreen);
+    };
+    const applyFullScreen = () => {
+        /*
+        Resolved from THIS browser's own container when the change event has not introduced it yet.
+        Scoped rather than `document.querySelector('tosi-sidenav')`, which returns the first in the
+        document — for a nested doc-browser, the HOST's.
+        */
+        if (!sidenav && typeof container !== 'undefined' && container) {
+            sidenav = container.querySelector(TosiSidenav.tagName);
+        }
+        if (!sidenav)
+            return;
+        if (appliedFullScreen === wantsFullScreen)
+            return;
+        // The same one control the nav button uses — the layout is just asking for the nav to be
+        // away, and the sidenav decides how that is achieved.
+        sidenav.navVisible = !wantsFullScreen;
+        appliedFullScreen = wantsFullScreen;
+        refreshNavToggle();
+    };
     const headerContent = [
         button({
             class: 'iconic',
             style: { color: vars.linkColor },
             title: 'navigation',
             bind: {
-                value: app.compact,
+                value: app.navToggle,
                 binding: {
                     toDOM(element, compact) {
                         element.style.display = compact ? '' : 'none';
@@ -593,8 +648,10 @@ export function createDocBrowser(options) {
                 },
             },
             onClick() {
+                // Read it, flip it. `<tosi-sidenav>` resolves what that means at this width; a
+                // button should not have to know, and this one used to.
                 if (sidenav)
-                    sidenav.contentVisible = !sidenav.contentVisible;
+                    sidenav.navVisible = !sidenav.navVisible;
             },
         }, icons.menu()),
         span({ style: { flex: '0 0 10px' } }),
@@ -651,7 +708,13 @@ export function createDocBrowser(options) {
         // doc-browser (no doc-system stylesheet) working.
         maxWidth: 'var(--doc-content-max-width, 44em)',
         margin: 'auto',
-        padding: '0 1em',
+        /*
+        Through a variable, for the same reason `maxWidth` is: this is an INLINE style, so a
+        stylesheet cannot override it, and `layout: "full-screen"` needs to. A full-screen page that
+        keeps a 1em gutter is not full screen — it is a demo inset by 32px, which is exactly what it
+        looked like.
+        */
+        padding: 'var(--doc-content-padding, 0 1em)',
         overflow: 'hidden',
     });
     // Adoption is zero-flash hydration of a statically pre-rendered page: it only
@@ -711,6 +774,58 @@ export function createDocBrowser(options) {
                 bakes: doc.bakes ? new Map(doc.bakes) : undefined,
             });
         }
+        /*
+        Keep the page's layout in step with the doc on SPA navigation.
+    
+        The static generator stamps `data-layout` so the first paint is already right without JS;
+        this is the other half — navigating from a full-width page to a prose one must put the
+        reading column back, and vice versa. Written on every showDoc rather than only on change,
+        because the adopted first page also arrives here and the attribute it was served with must
+        survive rather than be assumed.
+        */
+        /*
+        On the SAME element the static generator stamps — `<tosi-doc-system>` — not on
+        `docContent.parentElement`.
+    
+        Those are not the same node, which cost a debugging round: hydration wraps the adopted
+        `<article class="doc-content">` in a div, so the parent is that div while the generator's
+        attribute sits on the custom element above it. Writing to the div left the real host still
+        reading `full-width`, so navigating from the wide page to a prose one silently stayed wide —
+        and the test that only checked the wide direction would have passed.
+    
+        A memory-routed browser is EXCLUDED deliberately. That mode exists so an embedded or nested
+        browser cannot reach out and change the page hosting it, and `closest()` from inside one
+        finds the OUTER doc-system — the host's, not its own. Same reasoning as its history/location
+        ban; a nested doc-browser rewriting its host's layout is the same bug wearing a hat.
+        */
+        if (!memoryRouting) {
+            const layoutHost = docContent.closest('tosi-doc-system');
+            if (layoutHost) {
+                if (doc.layout)
+                    layoutHost.setAttribute('data-layout', doc.layout);
+                else
+                    layoutHost.removeAttribute('data-layout');
+            }
+            /*
+            `full-screen` also collapses the nav, and that has to go through the COMPONENT rather than
+            CSS: `<tosi-sidenav>` writes its column widths as inline properties, so a stylesheet has
+            nothing to override. The pre-hydration rule in doc-system-styles.ts handles the static
+            markup, which has a plain `<nav>` and no sidenav yet; this handles the hydrated page. Two
+            rules for two genuinely different DOMs, not two fixes for one bug.
+            */
+            wantsFullScreen = doc.layout === 'full-screen';
+            /*
+            Forced on every navigation. Without this, opening the nav on one full-screen page (which
+            turns `alwaysCompact` off) would leave the NEXT full-screen page not full-screen, because
+            the wish had not changed and the transition check would skip it. A reader's override is
+            meant to last until they navigate, not beyond it.
+            */
+            appliedFullScreen = null;
+            applyFullScreen();
+            // applyFullScreen returns early when there is no sidenav yet; the button state still has
+            // to follow the doc, so this does not ride on that path succeeding.
+            refreshNavToggle();
+        }
         rewriteContentLinks();
         // Stamp each example with its source file (for the source↔doc map). doc.path
         // is the extracted file (.md, or a source file with doc comments).
@@ -1216,6 +1331,9 @@ export function createDocBrowser(options) {
             sidenav = event.target.closest(TosiSidenav.tagName);
             if (sidenav)
                 app.compact = sidenav.compact;
+            refreshNavToggle();
+            // The sidenav has just introduced itself; give it the layout the doc asked for.
+            applyFullScreen();
         },
     }, searchField, navContent, div({
         style: {

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

@@ -98,6 +98,61 @@ export function docSystemStyleSpec(theme = {}) {
             // below — if these two ever disagree, the page jumps on hydration.
             _docContentMaxWidth: '44em',
         },
+        /*
+        Per-page layout, driven by `layout:` in a doc's metadata (see `Doc.layout`).
+    
+        Both are variable overrides rather than new layout rules, which is what keeps them cheap
+        and non-invasive: the measure is already `--doc-content-max-width`, so a page opts out by
+        changing one value. Nothing here runs for a corpus that never sets `layout`.
+        */
+        'tosi-doc-system[data-layout="full-width"]': {
+            _docContentMaxWidth: 'none',
+        },
+        /*
+        `full-screen` — no measure, and no chrome.
+    
+        These rules are for the PRE-HYDRATION page, whose markup is a plain `<nav class="doc-nav">`
+        with no inline styles, so hiding it here works and works on first paint. Once the bundle
+        loads, the nav becomes a slotted node inside `<tosi-sidenav>` carrying its own inline
+        `display`, and CSS can no longer touch it — the doc-browser sets `sidenav.navHidden`
+        instead. Different DOM before and after hydration, so genuinely two rules rather than a
+        belt-and-braces duplicate.
+        */
+        'tosi-doc-system[data-layout="full-screen"]': {
+            _docContentMaxWidth: 'none',
+        },
+        'tosi-doc-system[data-layout="full-screen"] .doc-content': {
+            padding: '0',
+            /*
+            A definite height, so a child asking for `height: 100%` gets one.
+      
+            "The content is the viewport" is the promise this layout makes, and a demo, a canvas or an
+            embedded app is the reason to use it — all of which want to FILL, not to sit in a tall
+            box. Without a height here `100%` on a child resolves against `auto` and collapses to its
+            content.
+            */
+            height: '100%',
+            overflow: 'auto',
+            /*
+            The gutter goes too. `.doc-content`'s padding is an INLINE style set by the doc-browser,
+            so this is set through the variable it reads rather than declared here, where it would
+            simply lose.
+            */
+            _docContentPadding: '0',
+        },
+        /*
+        `.doc-nav.doc-nav` — the class twice, on purpose.
+    
+        `tosi-doc-system:not(:defined) .doc-nav` (the pre-hydration layout, further down this same
+        sheet) has IDENTICAL specificity to the single-class form, so which one wins is decided by
+        source order, and it sits later. Winning on position works until someone reorders the spec,
+        at which point the nav quietly comes back on full-screen pages with nothing to point at.
+        Repeating the class costs one selector token and settles it on specificity, wherever these
+        rules end up living.
+        */
+        'tosi-doc-system[data-layout="full-screen"] > .doc-nav.doc-nav, tosi-doc-system[data-layout="full-screen"] > .doc-navbar.doc-navbar': {
+            display: 'none',
+        },
         '.darkmode': {
             ...invertLuminance(colors),
             /*
@@ -180,7 +235,7 @@ export function docSystemStyleSpec(theme = {}) {
             display: 'block',
             maxWidth: vars.docContentMaxWidth,
             margin: 'auto',
-            padding: '0 1em',
+            padding: 'var(--doc-content-padding, 0 1em)',
             // Must match doc-browser's inline style EXACTLY, `overflow` included: it
             // establishes a block formatting context, which stops the <h1>'s top margin
             // collapsing out of the box. Without it the static content sits 10px lower

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

@@ -221,6 +221,21 @@ Deliberately a small, named list rather than a clever heuristic: it has to be ob
 release was flagged, and obvious how to add to it. Matched as substrings of repo-relative
 paths.
 */
+/*
+Paths where a change is worth a second look before it ships as a patch.
+
+These are all DEVELOPMENT tooling — a dev server, a tunnel, a deploy script. None of it runs in
+an end user's browser as part of an adopter's app, which is why touching them WARNS rather than
+blocks. The distinction is the point: a security-relevant change to code an adopter ships to
+their users deserves a gate that stops the release, and a change to a tool a developer chooses
+to run on their own machine deserves a sentence in the notes.
+
+It blocked, briefly, and that was wrong in a way worth recording. A gate that halts a release
+over dev-only tooling spends the maintainer's attention on the release with the least at stake,
+and the reliable outcome of a guard that cries wolf is that it gets overridden or deleted —
+taking the case it was RIGHT about (#79, a loosened dev-server default shipped as a patch) with
+it. Warning keeps that signal and stops charging for it.
+*/
 export const SENSITIVE_PATHS = [
     'dev-auth',
     'build-lock',
@@ -264,8 +279,8 @@ export function bumpConcerns(opts) {
     const sensitive = changedPaths.filter((p) => SENSITIVE_PATHS.some((s) => p.includes(s)));
     if (sensitive.length) {
         out.push({
-            level: 'block',
-            reason: 'a security-relevant path changed in a PATCH — say what moved, under its own heading, in a release people will read',
+            level: 'warn',
+            reason: 'a dev-tooling path with a security surface changed in a PATCH — say what moved, under its own heading, in a release people will read',
             evidence: sensitive.slice(0, 8),
         });
     }

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

@@ -184,6 +184,23 @@ export declare function mayWriteSource(opts: {
     /** does the request carry a live session cookie? */
     hasValidSession: boolean;
 }): boolean;
+/**
+ * Who may attach the haltija dev channel — i.e. let an agent DRIVE this page.
+ *
+ * Deliberately the same rule as `mayWriteSource`, delegating rather than restating it, because
+ * driving a page with an agent is at least as powerful as writing source: an agent that can
+ * evaluate script in the page can read whatever the page can read and act as the logged-in
+ * user. A weaker gate here would quietly become the weakest link, and a *parallel* copy of the
+ * rule would be a second thing to keep in step — which is how the two drift.
+ *
+ * It is a separate NAME because the capability is separate: if the policies ever need to
+ * diverge, this is the one place to change, and every caller already says which it means.
+ */
+export declare function mayDriveWithAgent(opts: {
+    viaTunnel: boolean;
+    peer?: string | null;
+    hasValidSession: boolean;
+}): boolean;
 /**
  * THE loopback test. dev-server re-exports this as `isLoopbackAddress`; it used to
  * carry its own byte-identical copy.