tosijs-ui 1.12.0 → 1.12.2

package/CHANGELOG.md

@@ -1,5 +1,225 @@
 # Changelog
 
+## 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
+
+Local workers are pinned to **6** rather than Playwright's default (~half the cores, 9 here).
+Every engine had taken a turn producing a `page.goto` timeout or a `docs.json` load failure —
+roughly one full run in five, always passing in isolation — because 9 browsers were hitting one
+dev server. 1.11.0 fixed the client half (`fetchCorpus` retries); this reduces the contention
+instead of surviving it.
+
+Measured, not guessed: 9 workers ran the suite in 82s and 6 in 81s, so the lane is not
+CPU-bound at 9 and a third of the load is free; 4 workers costs 106s and buys nothing further.
+6/6 clean afterwards. Contributor-facing only — CI already runs at 1 worker.
+
+### `<tosi-schema-form>`: all three perf guards, and they cover different things
+
+The keystroke perf guard counts DOM lookups, and provably could not see `syncValues` — which
+runs on add/remove-item, not on keystrokes. A root-scoped per-field scan reintroduced there
+passed the existing test. There is now a sibling test on that path; mutation-testing takes it
+from 1 lookup per add to 41 → 161 as field count grows, while the keystroke test stays green
+under the same mutation.
+
+Wall-clock is back alongside them, too. It was removed in 1.11.0 for flaking; with the lane
+quiet the isolated and loaded distributions now overlap (3.20-4.57 vs 2.64-4.14 across all
+three engines, against 4.0 for linear and 16 for quadratic), so a threshold of 8 separates
+them. It earns its place by catching what counting cannot: an O(N) scan per field that uses no
+selector at all fails it at 9.63x while both count guards pass.
+
+### `<tosi-table>`: the header and body can no longer describe different columns (#102)
+
+Reported from a host app that changes column visibility when the page size changes. `set
+columns` updates the column list **synchronously** but defers the rebuild to the next frame,
+so between the assignment and that frame anything recomputing widths — a resize drag, a scroll
+handler, or the host's own page-size code — wrote a grid template for the NEW columns over the
+cells the OLD ones had built.
+
+Why that reads as _disagreement_ rather than a missing column, which is what made it confusing
+to report: with fewer tracks than cells, CSS Grid auto-places the surplus into **implicit**
+tracks, and implicit tracks size to content. Header text and body text differ, so the two rows
+resolve them to different widths and the columns visibly step apart.
+
+`setColumnWidths()` now describes the column set the DOM was actually built from, refreshed by
+`render()` on the frame that installs those cells. A column change is therefore **deferred, not
+dropped** — and because column objects are shared by reference, a resize drag still moves
+widths immediately: it is the shape that is pinned to the DOM, not the widths. All three
+properties have tests, and the fix is mutation-verified (reverting it fails with
+`tracks: 3, headerCells: 4`).
+
+The caller arguably should not reassign columns mid-render. It does not matter — a table that
+can show a header and a body describing different columns is our defect whenever the
+assignment lands.
+
 ## 1.12.0
 
 ### tosijs-ui is Apache-2.0 as of this release (MIT through 1.11.1)

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.d.ts

@@ -202,6 +202,7 @@ export declare class TosiTable extends WebComponent {
     private rowData;
     private _array;
     private _columns;
+    private _renderedCols;
     private _filter;
     private _sort?;
     private _rowGroupId;

package/dist/data-table.js

@@ -1311,6 +1311,11 @@ export class TosiTable extends WebComponent {
     };
     _array = [];
     _columns = null;
+    /*
+    The columns the CURRENT DOM was built from — see `setColumnWidths`. Not `_columns`: that one
+    changes the instant a caller assigns it, which is exactly the window this exists to cover.
+    */
+    _renderedCols = [];
     _filter = passThru;
     _sort;
     _rowGroupId = null;
@@ -2144,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
@@ -2158,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;
@@ -2611,7 +2643,30 @@ export class TosiTable extends WebComponent {
         this.addEventListener('keydown', this.handleKeyNav);
     }
     setColumnWidths() {
-        const cols = this.visibleColumns;
+        /*
+        The widths describe the columns the DOM ACTUALLY HAS, not the ones it is about to get.
+    
+        `set columns` updates `_columns` synchronously but defers the rebuild to `queueRender()`,
+        so between the assignment and the frame, `visibleColumns` already answers for a column set
+        no cell in the document belongs to. Anything that recomputes widths in that window — a
+        resize drag, a scroll handler, a host reacting to a page-size change — used to write a
+        template for the NEW columns over the OLD cells.
+    
+        That reads as the header disagreeing with the body (#102), and the reason it looks like
+        disagreement rather than simple breakage is worth knowing: with fewer tracks than cells,
+        CSS Grid auto-places the surplus into IMPLICIT tracks, which size to content. Header text
+        and body text differ, so the two rows resolve those tracks to different widths and the
+        columns visibly step apart.
+    
+        `_renderedCols` is the set the last render built the cells from; `render()` refreshes it
+        immediately before calling here, so a legitimate column change still takes effect on the
+        very frame that installs its cells. Column objects are shared by reference, so a resize
+        drag that mutates `column.width` is still reflected — it is the SHAPE that is pinned to
+        the DOM, not the widths.
+        */
+        const cols = this._renderedCols.length
+            ? this._renderedCols
+            : this.visibleColumns;
         const total = cols.reduce((w, c) => w + c.width, 0);
         /*
         `fullWidthHeader` lets ONE column absorb whatever width is left over, so a table narrower
@@ -2886,6 +2941,8 @@ export class TosiTable extends WebComponent {
         if (cols.length === 0)
             return;
         const stickyInfo = this.computeStickyInfo(cols);
+        // Before setColumnWidths, so the widths describe the cells this render is about to build.
+        this._renderedCols = cols;
         this.style.setProperty('--tosi-table-row-height', this.rowHeight > 0 ? `${this.rowHeight}px` : 'auto');
         this.setColumnWidths();
         // Build the regions. Header + optional pinned tbodies are siblings

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. See `Doc.layout` in docs.ts. */
+    layout?: 'full-width';
     testStatus?: 'passed' | 'failed' | 'pending';
     bakes?: Array<[string, {
         dialect: string;

package/dist/doc-browser.js

@@ -711,6 +711,39 @@ 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');
+            }
+        }
         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).

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

@@ -98,6 +98,16 @@ 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',
+        },
         '.darkmode': {
             ...invertLuminance(colors),
             /*

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.

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

@@ -417,6 +417,21 @@ export function mayWriteSource(opts) {
         return opts.hasValidSession;
     return isLoopbackAddressForAuth(opts.peer);
 }
+/**
+ * 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 function mayDriveWithAgent(opts) {
+    return mayWriteSource(opts);
+}
 /**
  * THE loopback test. dev-server re-exports this as `isLoopbackAddress`; it used to
  * carry its own byte-identical copy.

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

@@ -85,6 +85,28 @@ export declare function resolveLimitMb(configMb: number | undefined, envMb: stri
 export { isLoopbackAddress };
 export declare function haltijaIsDrivable(stdout: string): boolean;
 export declare function haltijaLoaderSnippet(httpsPort: number): string;
+/**
+ * The SAME-ORIGIN loader, for a page reached over the tunnel (`haltijaDev: 'tunnel'`).
+ *
+ * Over the tunnel `localhost` is the HEADSET, so every hardcoded `https://localhost:8701` in
+ * the upstream chain points at the wrong machine. This skips that chain entirely rather than
+ * asking haltija to change: `dev.js` and `inject.js` exist only to set `__haltija_config__`
+ * and load `component.js`, and both carry their own localhost gates. `component.js` has NO
+ * such gate — it reads `__haltija_config__.serverUrl` and falls back to localhost only when
+ * the config is absent — so setting the config ourselves and loading the component directly
+ * is both sufficient and the only part that can work remotely.
+ *
+ * `serverUrl` is derived from the page's own origin at runtime, not baked in, because the
+ * tunnel hostname is not known when this string is built and can differ per request.
+ *
+ * `self===top` is kept from the localhost loader: an iframe should not attach a second widget,
+ * and the doc-test runner executes pages in hidden iframes.
+ */
+export declare function haltijaTunnelLoaderSnippet(): string;
+/** Same-origin paths the tunnel bridge serves. One place, so the loader and the routes agree. */
+export declare const HALTIJA_BRIDGE_PREFIX = "/__haltija/";
+export declare const HALTIJA_BRIDGE_WS = "/__haltija/ws";
+export declare const HALTIJA_BRIDGE_COMPONENT = "/__haltija/component.js";
 /** br if the client takes it, else gzip, else nothing. */
 export declare function negotiateEncoding(accept: string | null): 'br' | 'gzip' | null;
 /** Is this worth compressing? Already-compressed formats only get bigger. */