@vibelord/lanes 1.1.1 → 1.3.0

package/payload/lanes/libexec/view.sh

@@ -4,12 +4,23 @@
 # loops forever and shows a status screen instead of dying.
 # usage: view.sh <device> <workspace> [slot]
 #   switch lane: write the lane id to $STATE/views/<device>/<workspace>.<slot>.target, then `kill -USR1` this pid.
+#   new tree (cockpit v3 U5): `kill -USR2` this pid after an update flipped ~/.local/share/lanes/current. The view
+#   re-executes itself (`exec "$0" …`: the same pid, the path it was started by — a `current` path runs the new tree) at
+#   the NEXT NATURAL EXIT of its child: an attached lane's viewer detaching or a USR1 switch, the end of a status
+#   screen's wait. USR2 itself never signals the child, so it never drops an attached tmux client.
 set -u
+# Trapped first, before this view's pid file names it: a USR2 must never find the default action (terminate).
+reexec=0
+on_reexec() { reexec=1; }
+trap on_reexec USR2
 device=${1:?device} ws=${2:?workspace} slot=${3:-main}
 mobile=0; [ "${4:-}" != --mobile ] || mobile=1
 case "$device$ws$slot" in *[!A-Za-z0-9_.-]*) echo 'invalid view name'; exit 64 ;; esac
 state=${LANES_STATE:-$HOME/.local/state/lanes}
-repo=$(cd "$(dirname "$0")/.." && pwd)
+# -P: the PHYSICAL tree. A layout names this script through the `current` link (W9 U1); resolving it once pins every
+# holder and connection.py this loop runs to the tree the view started from, so an update that flips the link never
+# mixes an old view.sh with new holders. The view moves to the new tree when it is started again.
+repo=$(cd "$(dirname "$0")/.." && pwd -P)
 dir=$state/views/$device
 mkdir -p "$dir"
 target_file=$dir/$ws.$slot.target
@@ -50,6 +61,13 @@ run() {
     # A trapped signal interrupts wait; make sure the child is really gone before moving on.
     while kill -0 "$child" 2>/dev/null; do wait "$child" 2>/dev/null || :; done
     child=
+    # A USR2 came while the child ran (or before it): it has ended by itself now, so run the tree `current` names. A
+    # failed exec ends a non-interactive shell, so a script that is gone (a pruned tree) is not exec'd: this one goes on.
+    if [ "$reexec" = 1 ]; then
+        reexec=0
+        if [ -x "$0" ] && [ "$mobile" = 1 ]; then exec "$0" "$device" "$ws" "$slot" --mobile; fi
+        if [ -x "$0" ]; then exec "$0" "$device" "$ws" "$slot"; fi
+    fi
     return "$rc"
 }
 
@@ -58,20 +76,30 @@ reset_terminal() {
     printf '\033[?1049l\033[?1000l\033[?1002l\033[?1003l\033[?1006l\033[?2004l\033[<u\033[0m\033[?25h\033[2J\033[3J\033[H'
 }
 
-# The 16-colour SGR literals of the design tokens (libexec/tokens.py --sh): sourced once, printf only, no fork.
+# The SGR literals of the design tokens (libexec/tokens.py --sh): sourced once, printf only, no fork. A plain source
+# assigns the 16-colour set; `lz_tones` re-points them to another set (assignments and a `case`, no fork either).
 # They hold `\033[…m` as text, so they go into printf's FORMAT (which turns `\033` into ESC), never into a %s argument.
 # shellcheck source=libexec/tokens.sh
 . "$repo/libexec/tokens.sh"
 
 # status_screen <title> <text> <dim line> [<lead>]: a lead, when given, is the bold headline above the title.
-# The lead glyph follows the sidebar's published glyph mode ($STATE/clients/<device>.glyphs, written by sidebar.py from
-# devices/<device>.json) and is read on EVERY call with the builtin read, no fork: this runs exactly when the host may be
-# too slow for one, and `lanes attach DEVICE --ascii` against a live session must reach the next screen without a restart.
+# The look follows the stamps the sidebar publishes for this device from its resolved modes (devices/<device>.json
+# first): $STATE/clients/<device>.glyphs, .color and .theme, read on EVERY call with the builtin read, no fork: this
+# runs exactly when the host may be too slow for one, and `lanes attach DEVICE --ascii|--color C|--theme T` against a
+# live session must reach the next screen without a restart. The lead glyph is `!` in ascii. `.color` and `.theme`
+# pick the colour set (cockpit v3 P3): truecolor or 256 of dark or light, none (NO_COLOR: bold only), and anything
+# else — no stamp, a vivid mode with no known variant yet — the 16-colour set, the user's own palette, never a guess.
+# In the vivid sets (LZ_VIVID: the colours Lanes defines) the lead takes the warning mark's tone, attention, as the
+# sidebar's banner does; 16 and none keep v1's bytes, as the sidebar's rows do.
 status_screen() {
     reset_terminal
     glyphs=unicode; { IFS= read -r glyphs < "$state/clients/$device.glyphs"; } 2>/dev/null || :
+    color=16; { IFS= read -r color < "$state/clients/$device.color"; } 2>/dev/null || :
+    theme=; { IFS= read -r theme < "$state/clients/$device.theme"; } 2>/dev/null || :
+    lz_tones "$color" "$theme"
     lead_glyph='⚠'; [ "$glyphs" != ascii ] || lead_glyph='!'
-    if [ -n "${4:-}" ]; then printf "\n  ${LZ_BOLD}%s %s${LZ_RESET}\n\n  %s\n" "$lead_glyph" "$4" "$1"
+    lead_tone=; [ -z "${LZ_VIVID:-}" ] || lead_tone=$LZ_ATTENTION
+    if [ -n "${4:-}" ]; then printf "\n  ${LZ_BOLD}${lead_tone}%s %s${LZ_RESET}\n\n  %s\n" "$lead_glyph" "$4" "$1"
     else printf "\n  ${LZ_BOLD}%s${LZ_RESET}\n" "$1"; fi
     printf "\n  %s\n\n  ${LZ_DIM}%s${LZ_RESET}\n" "$2" "$3"
 }

package/payload/lanes/systemd/lanes-docsd.service

@@ -0,0 +1,29 @@
+[Unit]
+Description=lanes docs service (login-bound docs, artifacts and uploads) on loopback 127.0.0.1:8185
+
+# Enabled and restarted by every server install (install/host-install.sh). lanes-mobile's Caddy forwards
+# https://<host>:8443/lanes-docs/* here (web/Caddyfile `handle_path /lanes-docs/*`). It reads and writes the docs store
+# ~/.local/state/lanes/docs/ and docs.log and reads members/, enrol-mode and registry.json; its publish pick-up (W4)
+# reads each workspace container's ~/.lz/state/publish/ through /proc/<pid>/root, as lanes-statusd does, and writes the
+# receipts back there; and (W5) it lands uploads in a workspace's uploads/ through the container's home volume. Hence
+# it has no ProtectHome.
+# It answers nothing until the operator pins the Serve header check (`lanes enrol mode request`, read on every
+# request). Optional settings (LANES_DOCS_DOMAINS, LANES_DOCS_PORT, and the default-off encryption at rest
+# LANES_DOCS_AGE_RECIPIENT / LANES_DOCS_AGE_IDENTITY, which `lanes upload` reads from the same drop-in) go in a drop-in,
+# `systemctl --user edit lanes-docsd.service`, which a re-install keeps (RUNBOOK "Docs service").
+# Memory: docsd holds at most two 32 MiB buffers at once (UPLOAD_SLOTS, shared by uploads and decryptions, one per
+# login), two Markdown renders and an 8 MiB render cache, and its publish pick-up reads at most 4,096 directory entries
+# of a container per cycle, so what a container plants or a member sends stays under MemoryMax (RUNBOOK "Docs service",
+# Limits; the composed peak is not measured: DEF-1917).
+[Service]
+ExecStart=/usr/bin/python3 -S -E "@REPO@/libexec/docsd.py"
+Restart=on-failure
+RestartSec=10
+NoNewPrivileges=true
+UMask=0077
+MemoryHigh=128M
+MemoryMax=192M
+Slice=lanes.slice
+
+[Install]
+WantedBy=default.target

package/payload/lanes/systemd/lanes-ensure.service

@@ -3,5 +3,8 @@ Description=lanes: recreate any missing device view session (agents are never to
 
 [Service]
 Type=oneshot
+# No After=/Conflicts= with lanes-update.service: `lanes ensure` holds the view-session lock (locks/sessions.lock,
+# DEF-1792) itself, as the update's `ensure --if-layout-changed`, `lanes rebuild` and every view create do. A tick that
+# finds it held waits 10 s, then skips (exit 0). Conflicts= would stop a running update; After= orders queued jobs only.
 ExecStart="@REPO@/bin/lanes" ensure
 Slice=lanes.slice

package/payload/lanes/systemd/lanes-gc.service

@@ -1,5 +1,5 @@
 [Unit]
-Description=lanes housekeeping (zmx logs never rotate; stale dynamic resolve files)
+Description=lanes housekeeping (zmx logs never rotate; stale dynamic resolve files; old staged trees)
 
 [Service]
 Type=oneshot

package/payload/lanes/systemd/lanes-update.service

@@ -0,0 +1,17 @@
+[Unit]
+Description=lanes: install the newest npm release when there is one (lanes update --timer)
+Documentation=https://github.com/bwllaming/bw-tools/blob/main/lanes/docs/USERGUIDE.md#update
+
+[Service]
+Type=oneshot
+# Asks the npm registry for the release @vibelord/lanes's dist-tag names (`latest`, or `lanes-stable` with channel=stable
+# in ~/.config/lanes/update.conf) and, when it is newer than the installed one, runs the npx the npm wrapper recorded at
+# install (~/.local/state/lanes/update/npx): `npx --yes @vibelord/lanes@<release> --server --update-only`. A last run
+# that ended `partial` gets its post-commit again first (once per release from here). A checkout install, an update
+# already running and an older or rolled-back release are a line in the journal and exit 0 (plan W9 U3, LNS-91).
+ExecStart="@REPO@/bin/lanes" update --timer
+# A oneshot has no start timeout by default. The update's own bounds are npx (50 min) and each post-commit step (300 s);
+# this one stops a run wedged anywhere else. A stop is SIGTERM to every process of the run: the installer records it.
+TimeoutStartSec=1h
+Nice=5
+Slice=lanes.slice

package/payload/lanes/systemd/lanes-update.timer

@@ -0,0 +1,17 @@
+[Unit]
+Description=lanes: look for a newer npm release 15 min after boot, then every 30 min (enabled by the server install)
+
+[Timer]
+# Enabled by every full server install (install/host-install.sh) with the other timers. OnBootSec= is already in the
+# past on a running host, so enabling it starts one check at once — refused while that install still holds the run lock
+# (~/.local/state/lanes/update/.lock), harmless after it (the release just installed is the newest, or the next one is).
+OnBootSec=15min
+OnUnitActiveSec=30min
+RandomizedDelaySec=5min
+# Persistent= acts only on OnCalendar= timers (systemd.timer(5)): a host that was off misses no check here because
+# OnBootSec= checks 15 min after every boot. Kept as the plan sets it; `lanes update` itself skips a check made less than
+# 20 min before (update.INTERVAL).
+Persistent=true
+
+[Install]
+WantedBy=timers.target

package/payload/lanes/web/Caddyfile

@@ -8,12 +8,35 @@
 http://:8083 {
 	bind 127.0.0.1
 	root * "{$LANES_REPO}/web"
-	header {
+	# lanes-docsd answers /lanes-docs/* with its own security headers per route (an agent's HTML or SVG artifact is a
+	# sandboxed top-level document), so the site-wide set below skips that prefix: docsd's are the only ones it sends.
+	@notdocs not path /lanes-docs/*
+	header @notdocs {
 		X-Content-Type-Options nosniff
 		X-Frame-Options DENY
 		Referrer-Policy strict-origin-when-cross-origin
 		Content-Security-Policy "default-src 'self'; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; connect-src 'self' ws: wss:; img-src 'self' data:"
 	}
+	# lanes-docsd.service (libexec/docsd.py): the docs cockpit, login-bound pages, downloads, artifacts and uploads.
+	# handle_path strips /lanes-docs. It stays the FIRST handle of the site: Caddy never reaches a block declared after
+	# a handle with a named matcher (the Zellij routes below).
+	handle_path /lanes-docs/* {
+		reverse_proxy 127.0.0.1:8185 {
+			# As on /enrol/*: keep the X-Forwarded-For Tailscale Serve sets (the client's tailnet address): docsd
+			# answers only a request that carries one, and only with Serve's identity headers. Caddy >= 2.5.
+			trusted_proxies 127.0.0.0/8
+		}
+	}
+	# The docs page's pinned Mermaid (plan W10 W6, LNS-107): install/enable-docs.sh puts holders.lock's pin into
+	# $LANES_SHARE/vendor (services.py sets LANES_SHARE in lanes-mobile.service). Immutable: a page names a VERSIONED
+	# file, so a new pin is a new URL (DEF-1870). Caddy sorts a single-path route ahead of /lanes-assets/* only past
+	# routes that also have a single path (Caddy issue #5037; DEF-1872): keep this block with the single-path routes
+	# above the named-matcher ones (/lanes-docs/* does not overlap it, so their order between themselves is free).
+	handle_path /lanes-assets/vendor/* {
+		root * "{$LANES_SHARE}/vendor"
+		header Cache-Control "public, max-age=31536000, immutable"
+		file_server
+	}
 	handle_path /lanes-assets/* {
 		header Cache-Control "no-cache"
 		file_server

package/payload/lanes/web/README.md

@@ -17,7 +17,9 @@ undoes the client's per-load single-pane start once
 (`laneFullRender`, the client's own `SetMobileRenderPreferences {single_pane: false, fit: true}`), so a desktop
 view's sidebar shows beside its lanes. `tests/web/activation.test.mjs` (`node --test`) pins the activation matrix,
 the picker model and that render preference; `tests/unit/test_web_view.py` pins the size budgets and runs that
-suite when node is installed. After an upgrade,
+suite when node is installed; `tests/web/phone.test.mjs` boots `mobile.js` as a phone against a fake page and
+client and records every frame it sends (input v2's bytes, keyboard, clipboard, dock and menu; cockpit v3 S5's filter
+Esc and prompt quick row; `test_web_view.PhoneKeys` names S5's tests and counts the file's). After an upgrade,
 check that `__zjMobileUi`, `__zjSendControl`, `__zjSoftKbdCapture` (with `sendFn` = `websockets.sendAnsiKey`),
 `__zjSyncInactiveCursorStyle` and `window.term` still exist in the served `app.js`.
 
@@ -41,16 +43,22 @@ before the control socket opens makes 0.45.1 throw `InvalidStateError` and leave
 
 `lanes-mobile.service` runs a separate, loopback-only Caddy on port 8083 with its admin API disabled.
 It does not change the system Caddy. Tailscale Serve forwards private HTTPS on 8443 to this frontend;
-the original Zellij service stays on 8082. Caddy (2.5 or later) must already be installed on the host. `/enrol/*` is
-the one route that is neither these assets nor Zellij: `handle_path` strips `/enrol` and forwards to the enrolment
-service on 127.0.0.1:8184 (`lanes-enrold.service`, [runbook](../docs/RUNBOOK.md#enrolment-service-lanes-enrold-w8-a3));
+the original Zellij service stays on 8082. Caddy (2.5 or later) must already be installed on the host. `/enrol/*` and
+`/lanes-docs/*` are the routes that are neither these assets nor Zellij: `handle_path` strips `/enrol` and forwards to
+the enrolment service on 127.0.0.1:8184 (`lanes-enrold.service`, [runbook](../docs/RUNBOOK.md#enrolment-service-lanes-enrold-w8-a3));
 it must stay before the Zellij routes, and its `trusted_proxies 127.0.0.0/8` keeps the `X-Forwarded-For` Tailscale
-Serve sets (the client's tailnet address), so the redeem rate limit counts per device.
+Serve sets (the client's tailnet address), so the redeem rate limit counts per device. `/lanes-docs/*` (prefix
+stripped) goes to the docs service on 127.0.0.1:8185 (`lanes-docsd.service`,
+[runbook](../docs/RUNBOOK.md#docs-service-lanes-docsd-w10-w3)): it is the FIRST handle of the site, keeps Serve's
+`X-Forwarded-For` the same way, and the site-wide `header` block skips it (`header @notdocs`, `@notdocs not path
+/lanes-docs/*`) so docsd's own per-route security headers are the only ones a document gets.
 Run `lanes web <device> --token` on the server (it also adds that Tailscale Serve mapping when it is missing),
 `lanes-launch web phone|laptop` from an installed client, or `sh install/enable-phone.sh --host lanes` (`--local` on
 the server).
 The [installation guide](../docs/INSTALL.md) covers Caddy, Tailscale operator permission and the selected SSH key.
-Service registration supplies `LANES_REPO` so Caddy serves the actual checkout from any installation path.
+Service registration supplies `LANES_REPO` — the `~/.local/share/lanes/current` link, which names the installed
+tree (W9 U1) — so Caddy serves that tree from any installation path, and the files an update brings as soon as
+the link moves; the routes of a new Caddyfile take a restart of `lanes-mobile` (the server installer does it).
 
 `index.html` keeps the upstream asset integrity hashes. When upgrading Zellij, compare the HTML and
 window hooks against the new version before changing the pinned binary. The mobile JS and CSS have
@@ -90,9 +98,16 @@ character of the old query after its common prefix with the new one, then the ne
 prefix; an emptied field or the Esc key sends a lone `Esc`. The text is the `TextEncoder` bytes with control bytes and
 DEL dropped, decoded back to text. There is no `setTimeout`: `send()` keeps a pause marker in its queue after a lone
 `Esc` and re-arms the one interval, whose next tick sends what follows once 60 ms have passed. The phone keeps the
-last query it sent (`laneFilterPrev`); on any tab other than a picker it forgets it, empties the field and drops a
-filter tail still waiting in the queue, without sending anything — the lane now has the focus, and an `Esc` there
-can interrupt an agent (DEF-1752; the sidebar clears its own filter when it opens a lane). Limits: the deltas assume the
+last query it sent (`laneFilterPrev`) and the picker it was typed on (`filterTab`, cockpit v3 S5); once a refresh
+finds another tab current — a lane, or another workspace's picker by the Workspaces sheet — it forgets the query,
+empties the field and drops a filter tail still waiting in the queue, without sending anything: the lane now has the
+focus, and an `Esc` there can interrupt an agent (DEF-1752 here, DEF-1817 on S5's line; the sidebar clears its own
+filter when it opens a lane), and another workspace's picker starts with an empty bar instead of the first one's
+query, whose next letter the deltas would have sent there as a bare key (DEF-1820). The lone `Esc` of an emptied
+field or of the Esc key, and the one a picker left filtered is owed, go through one debt (`owed`, picker tab names):
+`updateLaneFilterBar` sends it only while the picker it is owed to is the current tab, so a picker left filtered shows
+its whole list again on its next visit, and an Escape that arrives once the client has already moved on is held,
+never sent into the lane or another picker. Limits: the deltas assume the
 sidebar holds what the phone sent, which each new query's leading `Esc` restores — another client typing into the same
 picker pane, or a character the sidebar does not print (a no-break space, a zero-width joiner), puts them out of step
 until the field is cleared; and an `Esc` while the sidebar's upload strip is armed (`U`) returns the focus to the
@@ -155,6 +170,14 @@ on those facts (`node --test`, no jsdom).
 Attention counts come from the picker sidebar's pane title (`WS · ◆1 ◇2 ▸6`, written by the sidebar as OSC 2):
 `parseCounts` (also `window.__lanesParseCounts`) feeds the picker subtitle, `document.title`, the Lanes button's
 `data-count` and the workspace cards, inside the existing `refresh()` / `renderCards()` — no fetch, file or timer.
+The shell makes one request (W9 V3, LNS-85): once per page load, when it builds, `installFontControls()` asks
+`/enrol/site` on the same origin (the `/enrol/*` route above; the enrolment service's `GET /site` answers
+`{alias, host_name, host_key, version, request_mode, caller, source}`) and shows its `version` as the first row of
+the client's **More** menu, **Lanes v1.2.0**, above **Text size** — the same `.lanes-font-controls` row, so no CSS.
+Only a release is shown (`^\d[\w.+-]{0,31}$`, as text): `dev`, anything else, an error answer, a non-JSON 502 while
+the service is down, or no network shows nothing and throws nothing. The version is the enrolment service's tree
+(the server installer restarts it on every install). `tests/web/version.test.mjs` boots `mobile.js` against a fake
+logged-in page to pin this; `test_web_view` pins one fetch, inside `installFontControls()`, which `build()` runs once.
 Until plan Task 26 (2026-10-04) this reader was inert (DEF-1531): `bin/lanes` `mobile_workspace_tab` gave the
 picker pane a fixed `name="Lanes"`, and Zellij reports a pane's layout name instead of its OSC 2 title, so
 `pickerTitle()` read `Lanes`, `parseCounts` returned null and the shell showed no counts ("Choose a lane to continue").
@@ -163,7 +186,11 @@ phone device keeps the old picker pane until `lanes rebuild <device>` (`upgrade-
 `lanes doctor` names such a device). Whether the OSC 2 title now reaches
 `panes[].title` is still unchecked in a browser (no WebKit pass has run; fallback: the counts stay in the
 sidebar header). The quick-key row (`⏎ y n Esc ^C ↑ ↓`, `.lanes-quick`) shows on view
-tabs only; `refresh()` sets `--lanes-quick` (48 px or 0), which the terminal height subtracts. `n` and `^C` send
+tabs; on the picker tab it shows only while the sidebar asks for a key (a close, the Register confirmation or Add to
+workspace, which the sidebar announces by ending its pane title with ` · › <verb>`, ` · > <verb>` under ASCII glyphs;
+DM-LANES-SIDEBAR-TITLE), and then only `⏎ y Esc` (cockpit v3 S5) — `^C`, `n` and the arrows have no use in a prompt.
+A name field (Rename, Register as) is never announced: there `y` is a letter of the name (DEF-1819). `refresh()` sets
+`--lanes-quick` (48 px or 0), which the terminal height subtracts. `n` and `^C` send
 only when `pointerup.timeStamp − pointerdown.timeStamp ≥ 400` (no `setTimeout`); `pointercancel` and `pointerleave`
 disarm a key, and a `pointerup` without the key's own `pointerdown` sends nothing (before, a cancelled hold stayed
 armed, so a pointer released over `^C` later sent it, DEF-1739). The buttons cancel `mousedown` so a tap never moves
@@ -183,26 +210,111 @@ assigning the server theme wholesale (`SetConfig` is sent on each config-file re
 `!important` `--lanes-surface` rule for those two elements outranks it in either variant. An SRI bump of `app.js`
 re-opens this contract: re-read `startWsControl`, `installSoftKeyboardCapture`, `initWebSockets` (`sendAnsiKey`) and
 `installMenuDismissHook` before accepting it.
-`index.html` carries one `theme-color` per colour scheme. Bundle budget (spec §8, `test_web.test_bundle_growth`):
-`mobile.css` ≤ 18 982 B and `mobile.js` ≤ 24 258 B; the rules sit one per line and the explanations live here rather
+`index.html` carries one `theme-color` per colour scheme, each that variant's `surface` token, and the manifest's
+`background_color` and `theme_color` are the dark `surface`; they are hand-written, so `test_tokens.GeneratedSurfaces`
+holds them to the table (cockpit v3 P5). The icon (`icon.svg`, `icon-192.png`, a raster with anti-aliased edges) is
+the brand mark, drawn before the token table and not generated: palette v2 did not recolour it, and its bars keep
+v1's dark accent. Bundle budget (spec §8, `test_web.test_bundle_growth`):
+`mobile.css` ≤ 18 982 B and `mobile.js` ≤ 24 747 B; the rules sit one per line and the explanations live here rather
 than in the shipped files. MEASURED 2026-10-04 with `wc -c` after LNS-31 (plan Task 31) met Tasks 13/28: `mobile.js`
-21 964 B (23 268 B before its comments moved to Code notes below) and `mobile.css` 18 945 B. The JS cap was spec §8's
-22 174 B until phone shell input v2 (2026-10-07, DEF-1733): the working send path, the text keyboard, paste, Copy and
-Paste, the dock, More and hint fixes grew `mobile.js` to 23 456 B MEASURED after the dead `Write` path, the redundant
-focus/blur `is-typing` listeners and the file's header comment were removed and the new code was written compactly
-(`kbd()`, `aria()`), so the cap rose by exactly 1 282 B to that size (`mobile.css` unchanged). The independent
-review's fixes the same day (the filter's Esc-free frames and deltas, replacement ranges, no paste on a picker, only
-the paste end marker neutralised; DEF-1751..DEF-1755) grew it to 24 258 B MEASURED, and the cap rose by exactly those
-802 B again. A laptop or tablet also fetches `browser.js` (3 641 B) and `browser.css` (1 947 B); `test_web_view` pins
-that download at `LAPTOP_TABLET_JS_RATCHET` (27 899 B: 25 605 B plus the same 1 492 + 802 B of `mobile.js` growth)
-and `LAPTOP_TABLET_CSS_CAP` (DEF-1569).
+21 964 B (23 268 B before its comments moved to Code notes below) and `mobile.css` 18 945 B. A laptop or tablet also
+fetches `browser.js` and `browser.css` (1 947 B); `test_web_view` pins that download at `LAPTOP_TABLET_JS_RATCHET` and
+`LAPTOP_TABLET_CSS_CAP` (DEF-1569).
+
+The two lines that met at the cockpit v3 main sync (D2, LNS-99, 2026-10-07). On `wave/lanes-cockpit-v3`: after
+cockpit v3 S5 (the filter's Esc, the prompt quick row) `mobile.js` 22 164 B, and `browser.js` 3 334 B (3 641 B before
+its comments moved to Code notes below, to keep that download inside the ratchet, then pinned at 25 498 B); after S5
+fix cycle 1 (the Esc owed to the picker it was typed on) `mobile.js` 22 162 B and the ratchet 25 496 B. W9 V3's
+release row (+257 B of code; `mobile.js`'s line-1 pointer comment moved here first) measured 22 164 B on its own
+track; the fan-in of the two tracks measured 22 362 B, over §8's 22 174 B, and paid for it inside `mobile.js` with
+equivalent code — the four viewport properties through one setter, one `fill` style shared by the typing field's
+host and capture, the Workspaces icon's four squares drawn from their corners: 22 153 B, the download 25 487 B. On
+`bwtools/main`: the JS cap was spec §8's 22 174 B until phone shell input v2 (2026-10-07, DEF-1733): the working send
+path, the text keyboard, paste, Copy and Paste, the dock, More and hint fixes grew `mobile.js` to 23 456 B MEASURED
+after the dead `Write` path, the redundant focus/blur `is-typing` listeners and the file's header comment were
+removed and the new code was written compactly (`kbd()`, `aria()`), so the cap rose by exactly 1 282 B to that size
+(`mobile.css` unchanged); the independent review's fixes the same day (the filter's Esc-free frames and deltas,
+replacement ranges, no paste on a picker, only the paste end marker neutralised; DEF-1751..DEF-1755) grew it to
+24 258 B MEASURED, and the cap and the ratchet (27 899 B: 25 605 B plus the same 1 492 + 802 B) rose by exactly those
+802 B again. The composed file — input v2's frames, deltas, Copy/Paste and dock, plus S5's per-picker Esc debt and
+prompt quick row and W9 V3's release row, the branch's equivalent rewrites applied to the code both kept —
+MEASURED `mobile.js` 24 612 B (+354 B over input v2) and the download 24 612 + 3 334 = 27 946 B: the phone cap rose by
+those 354 B and the ratchet by 47 B (354 less the 307 B `browser.js` had already shed), each to the measured size
+(`test_web_view.JS_COCKPIT_V3`, `LAPTOP_TABLET_JS_RATCHET`), and all four cap assertions red on one byte more.
+
+The docs cockpit (plan W10 W7, LNS-108, 2026-10-08): **More** gains a **Docs** row, a link to `/lanes-docs/` (the docs
+page, `lanes-docsd` behind Caddy's `/lanes-docs/*`) in a new tab, and the desktop bar a **Docs** link beside its two
+pickers. The operator raised the phone cap by the measured amount, pinned exact: `mobile.js` MEASURED 24 747 B with
+`wc -c`, +135 B (`test_web_view.JS_DOCS`; `menuRow()` takes a tag and an extra class, and the row borrows
+`.lanes-session-link` for its 48 px touch target, so `mobile.css` stays 18 945 B). `browser.js` paid for its link
+inside its own bytes — its line-1 pointer comment moved to Code notes below and the bar's Escape listener became an
+`onkeydown` property — 3 334 -> 3 318 B MEASURED, so the laptop/tablet download is 24 747 + 3 318 = 28 065 B and the
+DEF-1569 ratchet rose by the 135 `mobile.js` bytes net of those 16, to that measured size.
+
+| File | Cap | MEASURED 2026-10-08 (`wc -c`) | Bound by |
+| --- | --- | --- | --- |
+| `mobile.js` | 24 747 B (exact) | 24 747 B | spec §8 phone row, `test_web.test_bundle_growth`, `test_web_view` `JS_DOCS` |
+| `mobile.css` | 18 982 B | 18 945 B | spec §8 phone row |
+| `browser.js` | 4 096 B | 3 318 B | `test_web_view.BROWSER_JS_CAP` |
+| `browser.css` | 2 048 B | 1 947 B | `test_web_view.BROWSER_CSS_CAP` |
+| `mobile.js` + `browser.js` | 28 065 B (exact) | 28 065 B | DEF-1569, `LAPTOP_TABLET_JS_RATCHET` |
+| `mobile.css` + `browser.css` | 20 993 B | 20 892 B | DEF-1569's CSS twin, `LAPTOP_TABLET_CSS_CAP` |
+
+## Docs page (plan W10 W6, LNS-107)
+
+The docs cockpit's pages (Markdown, Mermaid, files; served by `lanes-docsd` behind `/lanes-docs/*`, plan W3) are their
+own HTML documents with their own assets, outside the phone budget above: `docs.css` (cap 2 560 B, MEASURED 2 351 B)
+and `docs.js` (cap 1 536 B, MEASURED 1 530 B), both from `/lanes-assets/` with `no-cache` like the shell's. A page links
+`/lanes-assets/docs.css` and loads `<script src="/lanes-assets/docs.js" defer></script>`, and renders a ```` ```mermaid ````
+fence as `<pre class="mermaid">` holding the escaped source (`libexec/mdlite.py`, plan W2).
+
+- `docs.css` is phone first: a 16 px gutter (safe-area aware), a 46 rem measure, tables and code blocks that scroll
+  sideways instead of the page, `pre.mermaid` centred, system fonts only (the docs CSP allows no font source). Its
+  colours are the block between the `BEGIN`/`END lanes tokens` markers, generated by `libexec/tokens.py --docs-css`:
+  the six roles it paints (`DOCS_ROLES`) on `:root`, dark by default and light under `prefers-color-scheme` — not the
+  phone's `html.lanes-mobile` / `data-zj-theme` block. `tokens.py --check` covers it; no colour lies outside it.
+- `docs.js` is a classic script that does nothing on a page without `pre.mermaid`. With one, it appends one
+  `<script>` for `/lanes-assets/vendor/mermaid-<version>.min.js` with `integrity="sha256-…"` (base64 of the raw
+  sha256 of the pinned member, `holders.lock`) and `crossorigin="anonymous"`; on load it calls
+  `mermaid.initialize({startOnLoad: false, securityLevel: 'strict', suppressErrorRendering: true, theme})` (`dark`
+  when the system scheme is dark, else `default`) and `mermaid.run({querySelector: 'pre.mermaid'})`. Mermaid empties a
+  fence before it draws, so each fence left without an `<svg>` gets its source text back (`textContent`, never markup;
+  DEF-1873). A missing file (`install/enable-docs.sh` not run yet: 404) or an integrity mismatch fires no load, and every
+  fence stays a `<pre>` with its source. It never evaluates strings, writes markup or names the unversioned link.
+- The vendor route: `handle_path /lanes-assets/vendor/*` serves `$LANES_SHARE/vendor` (`install/services.py` puts
+  `LANES_SHARE` in `lanes-mobile.service`, as it does `LANES_REPO`) with `Cache-Control: public, max-age=31536000,
+  immutable` and no listing. Immutable is safe only because a page names the VERSIONED file: under the stable
+  `mermaid.min.js` link a browser would keep the old bytes after a pin bump and refuse them under the new integrity
+  (DEF-1870). The block sits first among the `handle` routes: Caddy sorts it ahead of `/lanes-assets/*` (longest path
+  first) only past routes that also have exactly one path (Caddy issue #5037), so after `@backend` it would never be
+  reached (DEF-1872). `test_docs_assets.VendorRoute` proves the order on a model of Caddy's sort; no Caddy runs in the
+  tests (DEF-1871).
+- CSP needs, MEASURED 2026-10-08 in headless Chromium 153 with Mermaid 11.17.2: `script-src 'self'` suffices — no
+  `'unsafe-eval'` (a flowchart and a sequence diagram rendered with no violation; a control page's `eval` was refused
+  and reported) — but the SVG Mermaid draws carries inline `<style>` and `style` attributes, so `style-src` needs
+  `'unsafe-inline'` (without it: 88 violations, unstyled diagrams). The docs page's CSP (plan W3) has both.
+- Tests: `tests/unit/test_docs_assets.py` (the pin, the enable script against a fake curl, the route model, the unit's
+  environment, both files' caps, tokens and SRI) and `tests/web/docs.test.mjs` (docs.js in a vm against a fake page and
+  a fake Mermaid that empties fences as the real one does). How to bump the pin: [runbook](../docs/RUNBOOK.md#mermaid-pin).
+- The drop area (plan W10 W5, LNS-106): the index's upload form is a plain form that works without a script — a
+  `label.docs-drop` wrapping a multi-file input, so a tap opens the picker and a drop onto the input takes the files.
+  `upload.js` (cap 2 892 B, MEASURED 2 892 B, exact) and `upload.css` (cap 1 033 B, MEASURED 1 033 B, exact) make it
+  better: a drop anywhere on the area (`input.files` = the dropped files), a size check against the form's `data-max`
+  before anything is sent, an `XMLHttpRequest` `POST up` asking for JSON with a `<progress>`, then one line per receipt
+  — a link to `d/<id>` named with `textContent`, its size, sha256 and the in-container path it `landed` at — and a
+  refusal or a network error in words. They are their own files because `docs.js` had 6 B of its cap left and
+  `docs.css` 209 B; docsd serves them like `docs.css`/`docs.js`, and only the index (the page with the form) loads them.
+  The page CSP has `connect-src 'self'` for that request. The styles use `docs.css`'s token roles only (no colour of
+  their own), 44 px touch targets, phone first. Tests: `test_docs_assets.UploadAssets` (caps, classic script, no
+  markup, roles) and `tests/web/upload.test.mjs` (upload.js in a vm against a fake page and XHR).
 
 ## Code notes
 
 `mobile.js` carries no explanations (the spec §8 budget above); each note is keyed to the code it explains, in file
 order.
 
-- The file: the Lanes browser shell (phone, tablet, desktop) over the pinned Zellij 0.45.1 client's window hooks.
+- The file: the Lanes browser shell (phone, tablet, desktop) over the pinned Zellij 0.45.1 client's window hooks. Its
+  explanations are these notes (the file's line-1 pointer to them moved here too, W9 V3).
 - `root.dataset.lanesShell = mode`: read by `browser.js` for the desktop bar and the tablet's full rendering.
 - `if (mode !== 'phone')`: appends the laptop/tablet extras (`browser.css`, `browser.js`); a phone never fetches them.
 - `if (mode === 'tablet')`: iPad Safari's user agent is a desktop one, so the shell asks for the client's mobile UI
@@ -236,12 +348,23 @@ order.
 - `hint()`: holds the subtitle for eight ticks of the one interval (DEF-1739).
 - `buildQuickRow()` (spec §6.5): `n` and `^C` send after a 400 ms hold, measured from event timestamps with no timer;
   a cancelled or left key is disarmed and a release needs the key's own press (DEF-1739); nothing takes focus.
-- `updateLaneFilterBar()`: off a picker tab, forgets the query and drops a filter tail still waiting in the queue,
-  sending nothing (the lane has the focus now, DEF-1752); the Esc key's lone `Esc` and pause leave the filter mode.
+- `clearLaneFilter()`: forgets the query and owes its picker (`filterTab`) the lone `Esc` that leaves the sidebar's
+  filter mode (`owed`, a set of picker tab names). `updateLaneFilterBar(tab, isPicker)`, on every refresh: once the
+  current tab is not the one the query was typed on, a filter tail still waiting in the queue is dropped and the query
+  cleared, sending nothing (the lane may have the focus now, DEF-1752); the lone `Esc` and its pause are sent only when
+  the current tab is an owed picker; then `filterTab` becomes the current tab if it is a picker. Escape in the bar and
+  an emptied field clear and call `refresh()`, so the `Esc` goes out at once while that picker is still current.
 - `lanesTheme()`: the shell's own terminal palette for both variants (spec §6.3, DEF-1413).
 - `refresh()`: leaves the subtitle to a live hint, hides **Panes** (and **Paste**, DEF-1754) on a picker tab so the
   dock's four columns hold its four items (DEF-1737), and flushes the `send()` queue after `updateLaneFilterBar()`, so a
-  filter tail is dropped before it could reach a lane.
+  filter tail is dropped before it could reach a lane; `quick` is `true` on a view tab (every key), `2` on the picker
+  while its title ends ` · › <verb>` (only `⏎ y Esc`), else none.
+- `menuRow()` / `installFontControls()`: a row of the client's **More** menu, prepended (Text size, then **Docs** above
+  it, then the release at the top once `/enrol/site` answers). The one `fetch` is there because `build()` runs once per
+  page load. `menuRow(label, tag, more)`: the **Docs** row is an `<a>` (plan W10 W7) to `/lanes-docs/` with
+  `target="_blank"` — a new tab, so the terminal and its socket stay where they are, and a Home Screen app, which has
+  no back button, is never navigated away — carrying `lanes-session-link` as well, the existing rule that gives it a
+  48 px touch target with no CSS of its own.
 - `connect()`: waits for server state, because an earlier resize throws `InvalidStateError` in 0.45.1. `applyTheme` is
   re-applied after every `SetConfig` (the client calls the chained `__zjSyncInactiveCursorStyle` hook) and on the theme
   toggle.
@@ -251,8 +374,22 @@ order.
   window hooks just after appending its mobile root; `hint()` and a paused `send()` re-arm it; each tick flushes the
   queue, and it clears itself once attached, with no hint up and no pause waiting.
 
+`browser.js` (laptop/tablet extras) carries none either, since cockpit v3 S5:
+
+- The file: the Lanes laptop/tablet extras (its line-1 pointer to these notes moved here in plan W10 W7, to pay for the
+  bar's Docs link).
+
+- `laneFullRender()`: the client starts a tablet in single pane on every load; once, it sends the client's own
+  switch-to-desktop preference.
+- `desktop()`: the chip toggles an overlay bar (no refit); a pick sends the phone picker's `FocusPane`. The chip
+  cancels `mousedown`, so the terminal keeps the keys. The bar ends in a **Docs** link to `/lanes-docs/` in a new tab
+  (plan W10 W7); Escape in the bar gives the terminal its keys back (`onkeydown`, one handler, as the listener was).
+- `ui()`: `window.__zjMobileUi` is set synchronously after the client appends its mobile root, which the
+  `MutationObserver` on `<body>` waits for.
+
 Validate on Safari/WebKit at 440 × 763 (iPhone 17 Pro Max with browser chrome), 440 × 956 (Home Screen),
 838 × 390 (landscape Safari), and smaller phone widths. Check login, workspace search and switching,
-lane selection, pane navigation, font controls, rotation and the visible viewport while the keyboard opens, and the
-input checklist in the [runbook](../docs/RUNBOOK.md) (text keyboard, quick keys, paste, Copy and Paste).
+lane selection, pane navigation, font controls and the release row in **More**, rotation and the visible viewport
+while the keyboard opens, and the input checklist in the [runbook](../docs/RUNBOOK.md) (text keyboard, quick keys,
+paste, Copy and Paste, the picker's filter and prompt row).
 Use disposable view sessions and revoke any temporary test token afterward.

package/payload/lanes/web/browser.js

@@ -1,4 +1,3 @@
-/* LNS-31 laptop/tablet extras; see docs/ARCHITECTURE.md (Web and phone). */
 function laneBarModel(d) {
   const panes = (d?.panes || []).filter(p => !p.is_plugin), at = d?.active_pane || {}, ws = new Map();
   const first = t => t && panes.find(p => p.tab_position === t.position);
@@ -14,7 +13,6 @@ function laneBarModel(d) {
       .map(p => item(p.title || `Pane ${p.pane_id}`, p))].filter(Boolean),
   };
 }
-// Tablet: upstream starts single pane on every load; once, send its own switch-to-desktop prefs.
 function laneFullRender(api, send) {
   let done;
   return () => {
@@ -41,14 +39,13 @@ if (typeof module === 'object') module.exports = {laneBarModel, laneFullRender};
     const full = laneFullRender(api, send);
     return () => full() && dispatchEvent(new Event('zellij:rendering-resize'));
   };
-  // Desktop: the chip toggles an overlay bar (no refit); picks send the phone picker's FocusPane.
   const desktop = api => {
     let last;
     const picks = ['Workspace', 'Lane'].map(title => make('select', {title, onchange() {
       send({type: 'FocusPane', pane_id: +this.value, is_plugin: false});
       focus();
     }}));
-    const bar = make('nav', {className: 'lanes-bar', hidden: true});
+    const bar = make('nav', {className: 'lanes-bar', hidden: true, onkeydown: ev => ev.key === 'Escape' && focus()});
     const render = () => {
       const m = !bar.hidden && laneBarModel(api.getState()?.data), sig = JSON.stringify(m);
       if (!m || sig === last) return;
@@ -61,13 +58,12 @@ if (typeof module === 'object') module.exports = {laneBarModel, laneFullRender};
       render();
       window.term?.focus();
     }});
-    chip.addEventListener('mousedown', ev => ev.preventDefault());   // the terminal keeps the keys
-    bar.addEventListener('keydown', ev => ev.key === 'Escape' && focus());
-    bar.append(...picks);
+    chip.addEventListener('mousedown', ev => ev.preventDefault());
+    bar.append(...picks, make('a', {href: '/lanes-docs/', target: '_blank', textContent: 'Docs'}));
     document.body.append(bar, chip);
     return render;
   };
-  const ui = () => window.__zjMobileUi;   // set synchronously after the client appends its mobile root
+  const ui = () => window.__zjMobileUi;
   if (ui()) return ready(ui());
   new MutationObserver((_, o) => ui() && (o.disconnect(), ready(ui()))).observe(document.body, {childList: true});
 })();

package/payload/lanes/web/docs.css

@@ -0,0 +1,52 @@
+/* Lanes docs page (plan W10 W6, LNS-107), phone first. Colours: the generated block below; system fonts only.
+   Notes: web/README.md "Docs page". */
+/* BEGIN lanes tokens (generated by libexec/tokens.py --docs-css; do not edit by hand) */
+:root {
+  --lanes-surface: #101318;
+  --lanes-surface-raised: #191e25;
+  --lanes-line: #2c333d;
+  --lanes-ink: #f2f5f8;
+  --lanes-ink-dim: #a6b1be;
+  --lanes-accent: #8fe3a6;
+  color-scheme: dark;
+}
+@media (prefers-color-scheme: light) {
+  :root {
+    --lanes-surface: #f3f5f2;
+    --lanes-surface-raised: #ffffff;
+    --lanes-line: #d5ded6;
+    --lanes-ink: #111a14;
+    --lanes-ink-dim: #4a5661;
+    --lanes-accent: #1f6f3f;
+    color-scheme: light;
+  }
+}
+/* END lanes tokens */
+*, *::before, *::after { box-sizing: border-box; }
+html { -webkit-text-size-adjust: 100%; text-size-adjust: 100%; }
+body {
+  max-width: 46rem; margin: 0 auto;
+  padding: 16px max(16px, env(safe-area-inset-right)) 32px max(16px, env(safe-area-inset-left));
+  background: var(--lanes-surface); color: var(--lanes-ink);
+  font: 16px/1.55 system-ui, -apple-system, "Segoe UI", sans-serif; overflow-wrap: break-word;
+}
+h1, h2, h3 { line-height: 1.25; margin: 1.4em 0 .5em; }
+h1 { font-size: 1.6em; margin-top: .4em; }
+h2 { font-size: 1.3em; padding-bottom: .2em; border-bottom: 1px solid var(--lanes-line); }
+a { color: var(--lanes-accent); }
+small { color: var(--lanes-ink-dim); }
+img { max-width: 100%; height: auto; }
+hr { border: 0; border-top: 1px solid var(--lanes-line); }
+blockquote { margin: 1em 0; padding-left: 12px; border-left: 3px solid var(--lanes-line); color: var(--lanes-ink-dim); }
+code, pre { font: .875em/1.45 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+code { padding: .1em .3em; border-radius: 4px; background: var(--lanes-surface-raised); }
+pre {
+  margin: 1em 0; padding: 12px; overflow-x: auto; tab-size: 4;
+  background: var(--lanes-surface-raised); border: 1px solid var(--lanes-line); border-radius: 8px;
+}
+pre code { padding: 0; font-size: 1em; background: none; }
+pre.mermaid { text-align: center; }
+pre.mermaid svg { max-width: 100%; height: auto; }
+table { display: block; max-width: 100%; overflow-x: auto; border-collapse: collapse; margin: 1em 0; }
+th, td { padding: 6px 10px; border: 1px solid var(--lanes-line); text-align: left; }
+th { background: var(--lanes-surface-raised); }

package/payload/lanes/web/docs.js

@@ -0,0 +1,36 @@
+// Lanes docs page (plan W10 W6, LNS-107): render ```mermaid fences with the pinned Mermaid, only on a page that has
+// one: its versioned file (DEF-1870), its sha256 as SRI. Without it every fence keeps its source. web/README.md.
+(function () {
+  'use strict';
+  var SRC = '/lanes-assets/vendor/mermaid-11.17.2.min.js';
+  var SRI = 'sha256-WB7X10vZBI0OOpE2OSfXLvIpQtdyJUayf3zCnjU5Drg=';
+
+  function render() {
+    var pres = document.querySelectorAll('pre.mermaid'), text = [], i;
+    for (i = 0; i < pres.length; i++) text[i] = pres[i].textContent;
+    // Mermaid empties each fence first: one left without a diagram gets its source back (DEF-1873).
+    function restore() {
+      for (i = 0; i < pres.length; i++) if (!pres[i].querySelector('svg')) pres[i].textContent = text[i];
+    }
+    try {
+      mermaid.initialize({startOnLoad: false, securityLevel: 'strict', suppressErrorRendering: true,
+        theme: matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'default'});
+      mermaid.run({querySelector: 'pre.mermaid'}).then(restore, restore);
+    } catch (e) {
+      restore();
+    }
+  }
+
+  function start() {
+    if (!document.querySelector('pre.mermaid')) return;
+    var s = document.createElement('script');
+    s.setAttribute('integrity', SRI);
+    s.setAttribute('crossorigin', 'anonymous');
+    s.setAttribute('src', SRC);
+    s.onload = render;
+    document.head.appendChild(s);
+  }
+
+  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', start);
+  else start();
+}());