tosijs-ui 1.16.27 → 1.16.29

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # Changelog
 
+## 1.16.29
+
+### Doc system
+
+- **A wikilink can name a page by its title.** `[[The feature registry]]` now reaches the page
+  at `/registry/`. Before, a target was only ever slugified, so it went to
+  `/the-feature-registry/` and 404'd. The slug (file name) still wins when a page has one, so
+  no link that worked changes target. A title two pages share reaches neither.
+  Reported by tosijs-3d-ensemble (#234).
+- **The build reports a wikilink that reaches no doc page**, naming the file and the target,
+  and fails under `strict`. One site had nine of these, live 404s from as far back as its 0.3,
+  and no build had said a word. **If you build with `strict: true`:** a wikilink to something
+  that is not a doc page, such as a hand-written page in your static folder, now fails the
+  build even though the link works. Write it as an ordinary `[label](/path/)`.
+- **The test-status widget sits in the header bar.** It was fixed at the bottom left over the
+  page, so a full-page component's last list row lost clicks to it (#233). A page with
+  `{"header": false}` still floats it there, having nowhere else to put it.
+
+### Tunnel
+
+- **The "needs an invite link" page offers the lasting link too.** When the dev server takes
+  the preview box's global keys, it now names `tosijs-tunnel --link --global` beside the
+  per-visit `--link`. That link keeps the browser in for 30 days across restarts (#232).
+
+## 1.16.28
+
+### Tunnel
+
+- **`tosijs-tunnel` prints a single-use link that keeps you signed in.** Once the route is
+  registered, it prints one link per global key, such as
+  `https://ui.edit.dev.tosijs.net/?t=KFMRPWQT`. The link carries a one-use code, never the key.
+  Opening it starts a session in that workspace and gives the browser the box's key as a
+  cookie across the preview domain for 30 days. From then on that browser opens every
+  workspace holding the key, and the box's root list, without another link, across dev-server
+  restarts. The edit link expires after the usual link window (5 minutes,
+  `tunnel.linkTtlMinutes`); the view link is read-only and lasts a day (`--share-ttl`).
+  `--link --global` and `--link --global --share` print fresh ones. Plain `--link` and
+  `--link --share` are unchanged.
+- **It only offers a link that means what it says.** It reads the box's `PREVIEW_DOMAIN` and a
+  sha256 of each key over ssh (the keys stay on the box). It prints no link for a key this
+  workspace refuses or the box does not share, and says why instead.
+- **The box's root page lists every workspace** and says what your key opens in each: `edit`,
+  `view`, or nothing. A workspace that is offline, or whose dev server is on a tosijs-ui before
+  1.16.26, shows as not answering. In 1.16.26 those rows were hidden, so a workspace on an
+  older tosijs-ui vanished from the page meant for picking one. Workspaces are now listed above
+  the deployed builds.
+- **`?t=<key>` on any preview host takes `&to=<label>`** and sends you on to
+  `<label>.<preview domain>`, and the edit key's cookie lasts 30 days there too, as the view
+  key's always has.
+
+### Security
+
+- **The box's access log recorded every link credential** (affected: 1.9.0 to 1.16.27). Caddy
+  logs the request URI, so each `?t=<key>` visit wrote that key, and each link redemption its
+  code, to `/var/log/caddy/preview.log`. The template now redacts `t` and `token` there.
+  **Re-run `tosijs-caddy-install`, then scrub the old logs** (`/var/log/caddy/preview*.log*`) **or
+  rotate your keys.** Caddy already kept cookies out of the log.
+- **The `to` redirect stays under the preview domain.** `to` must be DNS labels (lowercase
+  letters, digits, `-`, separated by `.`); anything else, including a path, a second `to` or
+  encoded line breaks, falls back to `/`. Checked against Caddy 2.6.2 and 2.11.7.
+
 ## 1.16.27
 
 ### Deploy

package/bin/resolve-site-config.ts

@@ -34,6 +34,8 @@ export interface PreviewConfig {
     localPort?: number
     url?: string
     requireToken?: boolean
+    /** see `tunnel.globalKeys` in site-config.ts */
+    globalKeys?: boolean | 'view'
   }
 }
 
@@ -156,6 +158,8 @@ export {
 server reads the global tunnel keys from the same file; it is re-exported here for the bins.
 */
 export { readLocalSecret } from '../dist/doc-system/site/local-secrets.js'
+export { resolveGlobalKeys } from '../dist/doc-system/site/dev-auth.js'
+import type { GlobalKeys } from '../dist/doc-system/site/dev-auth.js'
 import { readLocalSecret } from '../dist/doc-system/site/local-secrets.js'
 
 /**
@@ -443,3 +447,100 @@ export async function refreshHostIndex(host: string): Promise<void> {
   const out = run.stdout.toString().trim()
   if (out) console.log(`   ${out}`)
 }
+
+/** What the box says about its global keys: its domain, and a fingerprint of each key. */
+export interface BoxKeys {
+  domain?: string
+  /** sha256 hex of the box's PREVIEW_EDIT_TOKEN / PREVIEW_TOKEN, '' when it has none */
+  editSha?: string
+  viewSha?: string
+  problem?: string
+}
+
+/**
+ * Read the box's preview domain, and fingerprints of its two keys, in one ssh call.
+ *
+ * The file is SOURCED, as the installer and Caddy's own install read it, so all three agree on
+ * quoting, `export` and comments. The keys never leave the box: only their sha256 does, which is
+ * enough to say "this machine's key is not the box's", the one mismatch that makes a link
+ * open this workspace and nothing else.
+ */
+export async function previewBoxKeys(host: string): Promise<BoxKeys> {
+  const script =
+    // Checked first: bash as a login shell carries on past a failed `.`, which read as "sets
+    // no PREVIEW_DOMAIN" when the file was missing or unreadable.
+    '[ -r /etc/caddy/preview.env ] || { echo "/etc/caddy/preview.env is missing or unreadable" >&2; exit 1; }; ' +
+    'set -a; . /etc/caddy/preview.env; set +a; ' +
+    'printf "%s\\n" "${PREVIEW_DOMAIN:-}"; ' +
+    'for k in "${PREVIEW_EDIT_TOKEN:-}" "${PREVIEW_TOKEN:-}"; do ' +
+    'if [ -n "$k" ]; then printf %s "$k" | { sha256sum 2>/dev/null || shasum -a 256; } | cut -d" " -f1; else echo; fi; done'
+  // Never prompt or hang: `--link --global` waits on this.
+  const read =
+    await $`ssh -o BatchMode=yes -o ConnectTimeout=10 ${host} ${script}`
+      .nothrow()
+      .quiet()
+  if (read.exitCode !== 0) {
+    return {
+      problem: `could not read /etc/caddy/preview.env on ${host}: ${read.stderr
+        .toString()
+        .trim()
+        .slice(0, 160)}`,
+    }
+  }
+  const [domain = '', editSha = '', viewSha = ''] = read.stdout
+    .toString()
+    .split('\n')
+    .map((line) => line.trim())
+  if (!/^[a-z0-9.-]+$/i.test(domain)) {
+    return {
+      problem: `/etc/caddy/preview.env on ${host} sets no PREVIEW_DOMAIN`,
+    }
+  }
+  return { domain, editSha, viewSha }
+}
+
+const sha256 = (text: string) =>
+  new Bun.CryptoHasher('sha256').update(text).digest('hex')
+
+/**
+ * Which single-use links `tosijs-tunnel` can honestly offer, and why not the rest.
+ *
+ * A link hands the browser this machine's key as a cookie across the box's domain, so it is
+ * only worth printing when this workspace accepts the key AND the box holds the same one; with a
+ * different key on the box, the cookie would open this workspace and not the box's root or any
+ * other workspace, which is not what the link says.
+ */
+export function planGlobalLinks(
+  local: { keys: GlobalKeys; problems: string[] },
+  box: BoxKeys
+): { kinds: ('edit' | 'view')[]; domain?: string; notes: string[] } {
+  const notes = [...local.problems]
+  const { keys } = local
+  const wanted: ('edit' | 'view')[] = []
+  if (keys.edit && (keys.editGrants ?? 'edit') === 'edit') wanted.push('edit')
+  if (keys.view) wanted.push('view')
+  if (wanted.length === 0) {
+    if (notes.length === 0)
+      notes.push(
+        'no global key on this machine (PREVIEW_EDIT_TOKEN / PREVIEW_TOKEN in ~/local-secrets/tosijs-preview.env), or tunnel.globalKeys turns them off'
+      )
+    return { kinds: [], notes }
+  }
+  if (!box.domain) {
+    notes.push(box.problem ?? 'the box did not say what its preview domain is')
+    return { kinds: [], notes }
+  }
+  const kinds = wanted.filter((kind) => {
+    const mine = kind === 'edit' ? keys.edit! : keys.view!
+    const theirs = kind === 'edit' ? box.editSha : box.viewSha
+    if (theirs === sha256(mine)) return true
+    const name = kind === 'edit' ? 'PREVIEW_EDIT_TOKEN' : 'PREVIEW_TOKEN'
+    notes.push(
+      theirs
+        ? `${name} here is not the box's, so no ${kind} link: put the same value in both files`
+        : `the box has no ${name}, so no ${kind} link: add it to /etc/caddy/preview.env and re-run tosijs-caddy-install`
+    )
+    return false
+  })
+  return { kinds, domain: box.domain, notes }
+}

package/bin/tunnel.ts

@@ -32,9 +32,13 @@ always requires a session.
 
 import { $ } from 'bun'
 import {
+  planGlobalLinks,
+  previewBoxKeys,
   previewRootFor,
+  readLocalSecret,
   registerCaddyFragment,
   refreshHostIndex,
+  resolveGlobalKeys,
   resolveDevPort,
   resolvePreviewHost,
   resolveSiteConfig,
@@ -45,7 +49,7 @@ import {
 const { has, flag } = parseArgv(process.argv.slice(2), {
   bin: 'tosijs-tunnel',
   summary: 'expose the local dev server through the preview host',
-  flags: ['close', 'link', 'status', 'share'],
+  flags: ['close', 'link', 'status', 'share', 'global'],
   values: ['host', 'port', 'local-port', 'remote-port', 'url', 'share-ttl'],
   usage:
     `  tosijs-tunnel                        open the tunnel (foreground)\n` +
@@ -53,6 +57,8 @@ const { has, flag } = parseArgv(process.argv.slice(2), {
     `  --close                              close a running tunnel\n` +
     `  --link                               print a magic edit link\n` +
     `  --link --share                       print a READ-ONLY link to send to a person\n` +
+    `  --link --global [--share]            a SINGLE-USE link that also gives that browser the\n` +
+    `                                       box's key for 30 days (every workspace, the root list)\n` +
     `  --share-ttl=<minutes>                how long that share link lives (default 1440)\n` +
     `  --host=user@box                      override the configured preview host\n` +
     `  --port= --local-port= --remote-port= override the resolved ports`,
@@ -113,6 +119,60 @@ const publicUrl = flag('url') ?? preview?.tunnel?.url
 // Set by the registration step below; no public URL means there is no route to fail.
 let routed = true
 
+/** Ask the dev server (loopback only) for a link; `query` selects the kind. */
+async function askForLink(
+  query: string
+): Promise<{ url?: string; error?: string }> {
+  const res =
+    await $`curl -sk --max-time 5 https://localhost:${localPort}/__devlink${query}`
+      .nothrow()
+      .quiet()
+  try {
+    return JSON.parse(res.stdout.toString())
+  } catch {
+    return {}
+  }
+}
+
+/*
+Single-use links that also give the browser the box's global key (see GlobalGrant in
+dev-auth.ts): one click opens this workspace, and from then on that browser opens every
+workspace holding the key, and the box's root list, for 30 days, across restarts. The link
+carries a one-use code, never the key. Offered only for keys this workspace accepts and the box
+holds too; `notes` says why any other is missing.
+*/
+async function globalLinks(
+  kinds: ('edit' | 'view')[] = ['edit', 'view'],
+  extraQuery = ''
+): Promise<{
+  links: { kind: 'edit' | 'view'; url: string }[]
+  notes: string[]
+}> {
+  const local = resolveGlobalKeys(preview?.tunnel?.globalKeys, {
+    PREVIEW_TOKEN:
+      process.env.PREVIEW_TOKEN ?? readLocalSecret('PREVIEW_TOKEN'),
+    PREVIEW_EDIT_TOKEN:
+      process.env.PREVIEW_EDIT_TOKEN ?? readLocalSecret('PREVIEW_EDIT_TOKEN'),
+  })
+  const box =
+    local.keys.edit || local.keys.view ? await previewBoxKeys(host!) : {}
+  const plan = planGlobalLinks(local, box)
+  const links: { kind: 'edit' | 'view'; url: string }[] = []
+  for (const kind of plan.kinds.filter((k) => kinds.includes(k))) {
+    const answer = await askForLink(
+      `?global=${kind}&domain=${encodeURIComponent(plan.domain!)}${extraQuery}`
+    )
+    if (answer.url) links.push({ kind, url: answer.url })
+    else
+      plan.notes.push(
+        answer.error ??
+          `the dev server on :${localPort} did not answer, so no ${kind} link: start it (\`bun start\`), then \`tosijs-tunnel --link\``
+      )
+  }
+  return { links, notes: plan.notes }
+}
+let startLinks: Awaited<ReturnType<typeof globalLinks>> | undefined
+
 /*
 Say where this is going, and where the address came from, BEFORE acting on it.
 
@@ -176,18 +236,25 @@ if (has('link')) {
   */
   const share = has('share')
   const shareTtl = flag('share-ttl')
-  const query = share
-    ? `?share=1${shareTtl ? `&ttl=${encodeURIComponent(shareTtl)}` : ''}`
-    : ''
-  const res =
-    await $`curl -sk --max-time 5 https://localhost:${localPort}/__devlink${query}`
-      .nothrow()
-      .quiet()
-  let url = ''
-  try {
-    url = JSON.parse(res.stdout.toString()).url
-  } catch {
-    /* fall through to the error below */
+  const ttl = shareTtl ? `&ttl=${encodeURIComponent(shareTtl)}` : ''
+  /*
+  `--global` asks for a link that also hands over the box's key (see globalLinks): single-use,
+  and the browser keeps every workspace for 30 days. Opt-in, because it is a different promise
+  from the two links above, which are reusable for their window and open this workspace only.
+  A share link spent by a chat app's link preview, or one that opens every workspace, would
+  break the promise `--share` makes to the person you send it to.
+  */
+  let url: string
+  if (has('global')) {
+    const global = await globalLinks([share ? 'view' : 'edit'], ttl)
+    for (const note of global.notes) console.log(`note: ${note}`)
+    url = global.links[0]?.url ?? ''
+    if (!url) {
+      console.error('\nNo single-use global link (see the note above).\n')
+      process.exit(1)
+    }
+  } else {
+    url = (await askForLink(share ? `?share=1${ttl}` : '')).url ?? ''
   }
   if (!url) {
     console.error(
@@ -210,7 +277,15 @@ if (has('link')) {
   */
   const code = new URL(url).searchParams.get('t')
   console.log(
-    `\n🔗 ${share ? 'Share link (READ ONLY)' : 'Edit link'}:\n   ${url}\n` +
+    `\n🔗 ${
+      has('global')
+        ? `Single-use ${
+            share ? 'READ-ONLY ' : ''
+          }link (that browser keeps every workspace for 30 days)`
+        : share
+        ? 'Share link (READ ONLY)'
+        : 'Edit link'
+    }:\n   ${url}\n` +
       (code ? `\n   code:  ${code}   (case-insensitive)\n` : '')
   )
 
@@ -419,8 +494,11 @@ if (publicUrl) {
       describe: `${hostname} → this workspace`,
       body: fragment,
     })
-    // The root's list of live workspaces is read from these fragments.
-    if (routed) await refreshHostIndex(host!)
+    if (routed) {
+      // The root's list of live workspaces is read from these fragments.
+      await refreshHostIndex(host!)
+      startLinks = await globalLinks()
+    }
   }
 }
 
@@ -438,6 +516,15 @@ if (publicUrl) {
       ? `   ${publicUrl}`
       : `   ${publicUrl}  ⚠️  NOT routed — registration failed above; this URL will not reach here`
   )
+  if (startLinks?.links.length) {
+    console.log(
+      `\n   Single-use links: each opens this workspace, then keeps that browser in every` +
+        `\n   workspace on the box (and its root list) for 30 days:`
+    )
+    for (const { kind, url } of startLinks.links)
+      console.log(`   ${kind}: ${url}${kind === 'view' ? '  (read-only)' : ''}`)
+  }
+  for (const note of startLinks?.notes ?? []) console.log(`   note: ${note}`)
 }
 console.log(`   Ctrl-C to close.\n`)
 

package/deploy/Caddyfile

@@ -36,6 +36,15 @@
 # `root` is the only thing that varies, keeping it in the caller costs one line per
 # project and makes this file work on any Caddy 2.x.
 (preview_site) {
+	# Where a key link lands: `&to=<label>` sends it to `<label>.{{PREVIEW_DOMAIN}}` (so
+	# `tosijs-tunnel` can hand out ONE link that sets the cookie here and opens its workspace),
+	# anything else to this host's root. Only DNS labels match, and the target is always under
+	# the preview domain, so this cannot redirect off-site.
+	map {query.to} {tosi_link_target} {
+		~^([a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*)$ "https://${1}.{{PREVIEW_DOMAIN}}/"
+		default "/"
+	}
+
 	# THE PREVIEW HOST IS PRIVATE — but gated by a LINK, not a password dialog.
 	#
 	# basicauth used to guard these hosts, and it worked, but it makes the browser throw
@@ -63,11 +72,13 @@
 		header Set-Cookie "tosi_preview=__PREVIEW_TOKEN__; Domain=.{{PREVIEW_DOMAIN}}; Path=/; Max-Age=2592000; HttpOnly; Secure; SameSite=Lax"
 		header Referrer-Policy "no-referrer"
 		header Cache-Control "no-store"
-		redir * / 302
+		redir * {tosi_link_target} 302
 	}
 
 	# THE GLOBAL EDIT KEY: `?t=<edit key>` on any preview host sets `tosi_edit` across the
-	# whole preview domain for 24 hours. Every tunnelled workspace that holds the same key
+	# whole preview domain for 30 days, the same cookie a workspace's single-use link from
+	# `tosijs-tunnel` sets (that link is the usual way in: it never puts the key in a URL).
+	# Every tunnelled workspace that holds the same key
 	# (PREVIEW_EDIT_TOKEN in ~/local-secrets/tosijs-preview.env on the machine running it)
 	# trades it for an editing session on the first page load, so the root's list opens them
 	# all, across dev-server restarts. It also opens these static previews. The view key above
@@ -78,10 +89,10 @@
 	# rotated (edit preview.env here and on each machine, re-run the installer).
 	@editlink query t=__PREVIEW_EDIT_TOKEN__
 	handle @editlink {
-		header Set-Cookie "tosi_edit=__PREVIEW_EDIT_TOKEN__; Domain=.{{PREVIEW_DOMAIN}}; Path=/; Max-Age=86400; HttpOnly; Secure; SameSite=Lax"
+		header Set-Cookie "tosi_edit=__PREVIEW_EDIT_TOKEN__; Domain=.{{PREVIEW_DOMAIN}}; Path=/; Max-Age=2592000; HttpOnly; Secure; SameSite=Lax"
 		header Referrer-Policy "no-referrer"
 		header Cache-Control "no-store"
-		redir * / 302
+		redir * {tosi_link_target} 302
 	}
 
 	# Anchored at both ends: unanchored, `tosi_edit=<key>x` matched too. That needed the key
@@ -151,6 +162,17 @@
 			roll_size 10MiB
 			roll_keep 3
 		}
+		# Links carry credentials in the query: `t` (a global key, or a single-use code) and
+		# `token`. Caddy already keeps cookies out of this log; this keeps those out too.
+		format filter {
+			wrap json
+			fields {
+				request>uri query {
+					replace t REDACTED
+					replace token REDACTED
+				}
+			}
+		}
 	}
 }
 
@@ -198,6 +220,17 @@
 			roll_size 10MiB
 			roll_keep 3
 		}
+		# Links carry credentials in the query: `t` (a global key, or a single-use code) and
+		# `token`. Caddy already keeps cookies out of this log; this keeps those out too.
+		format filter {
+			wrap json
+			fields {
+				request>uri query {
+					replace t REDACTED
+					replace token REDACTED
+				}
+			}
+		}
 	}
 }
 

package/deploy/build-index.sh

@@ -75,9 +75,10 @@ for dir in "$ROOT"/*/; do
 	</li>"
 done
 
-# Tunnelled workspaces: every registered `-tunnel` fragment. Whether one is UP, and what
-# the reader may do there, changes by the minute, so the page asks each one when it loads
-# (see the script below); this only lists where to ask.
+# Tunnelled workspaces: every registered `-tunnel` fragment, ALWAYS listed, so this page is
+# where you pick one. Whether it is up, and what the reader may do there, changes by the
+# minute, so the page asks each one when it loads (see the script below). Hiding the rows
+# that did not answer made a workspace on an older tosijs-ui simply vanish.
 live=""
 for frag in "$ROOT"/_sites/*-tunnel.caddy; do
 	[ -f "$frag" ] || continue
@@ -85,10 +86,10 @@ for frag in "$ROOT"/_sites/*-tunnel.caddy; do
 	host=$(sed -n 's/^\([A-Za-z0-9.-]*\) *{.*/\1/p' "$frag" | head -1)
 	[ -n "$host" ] || continue
 	live="$live
-	<li data-workspace=\"$host\" hidden>
+	<li data-workspace=\"$host\">
 		<a href=\"https://$host/\">
 			<span class=\"name\">$name</span>
-			<span class=\"meta\"><span class=\"access\"></span><code>$host</code></span>
+			<span class=\"meta\"><span class=\"access\">checking…</span><code>$host</code></span>
 		</a>
 	</li>"
 done
@@ -133,16 +134,18 @@ cat > "$OUT/index.html" <<HTML
 	h2 { font-size:1rem; margin:2rem 0 .75rem; font-weight:600; }
 	.access { font-weight:600; }
 	.access.edit { color:#2a8a3e; }
+	.access.none { font-weight:400; }
 	footer { color:var(--dim); font-size:.8rem; margin-top:2.5rem; }
 </style>
 <main>
 	<header>$ICON<h1>tosijs previews</h1></header>
-	<p class="sub">Deployed builds. Each shows the commit it was built from.</p>
+	<p class="sub">Live workspaces, and the builds deployed here.</p>
+	$(if [ -n "$live" ]; then echo "<section id=\"live\"><h2>Live workspaces</h2><ul>$live
+	</ul></section>"; fi)
+	<h2>Deployed builds</h2>
 	$(if [ "$count" -eq 0 ]; then echo '<p class="empty">Nothing deployed yet.</p>'; else echo "<ul>$rows
 	</ul>"; fi)
 	$(if [ -n "$unlinked" ]; then echo "<p class=\"empty\">Deployed but not routed:$unlinked</p>"; fi)
-	$(if [ -n "$live" ]; then echo "<section id=\"live\" hidden><h2>Live workspaces</h2><ul>$live
-	</ul></section>"; fi)
 	<footer>Previews only — not production. Each entry updates when that project deploys (<code>bun run deploy --go</code>), not when it builds.</footer>
 </main>
 <script>
@@ -162,21 +165,26 @@ cat > "$OUT/index.html" <<HTML
 	}
 
 	// Ask each tunnelled workspace whether it is up and what this reader may do there. Only
-	// this origin may read the answer, and it reflects the key cookie this page set; a
-	// workspace that is down (or older than this probe) shows nothing. Opening one trades the
-	// key for a session there, so these are plain links.
+	// this origin may read the answer, and it reflects the key cookie this page set. Opening
+	// one trades the key for a session there, so these are plain links. A workspace that is
+	// down and one whose dev server predates this probe (tosijs-ui 1.16.26) look the same
+	// from here: neither gives an answer this page may read.
+	const silent = 'not answering (offline, or tosijs-ui before 1.16.26)'
+	const say = (li, text, kind) => {
+		const label = li.querySelector('.access')
+		label.textContent = text
+		label.className = 'access ' + kind
+	}
 	for (const li of document.querySelectorAll('[data-workspace]')) {
 		fetch('https://' + li.dataset.workspace + '/__alive', { credentials: 'include' })
-			.then((r) => (r.ok && r.status === 200 ? r.json() : null))
+			.then((r) => (r.status === 200 ? r.json() : null))
 			.then((info) => {
-				if (!info || !info.access) return
-				const label = li.querySelector('.access')
-				label.textContent = info.access === 'edit' ? 'edit' : 'view'
-				label.classList.add(info.access)
-				li.hidden = false
-				document.getElementById('live').hidden = false
+				if (!info) say(li, silent, 'none')
+				else if (info.access === 'edit') say(li, 'edit', 'edit')
+				else if (info.access === 'view') say(li, 'view', 'view')
+				else say(li, 'up, but your key does not open it', 'none')
 			})
-			.catch(() => {})
+			.catch(() => say(li, silent, 'none'))
 	}
 </script>
 HTML

package/dist/doc-browser.js

@@ -95,7 +95,7 @@ history, for a browser embedded in another page: drive it with `initialRoute`,
 */
 /*{ "parent": "Documentation System", "order": 50 }*/
 import { elements, vars, varDefault, bindings, touch, getListItem, debounce, tosi, StyleSheet, } from 'tosijs';
-import { buildSlugMap, pathForSlug, filenameForPath, homeDoc, } from './doc-system/routing.js';
+import { buildSlugMap, pathForSlug, filenameForPath, homeDoc, wikilinkTargets, } from './doc-system/routing.js';
 import { buildNavTree } from './doc-system/nav-tree.js';
 import { renderDocMarkdown } from './doc-system/render.js';
 import { pageTitle } from './doc-system/doc-title.js';
@@ -202,21 +202,28 @@ const testIndicatorStyleSpec = {
         background: testColor.fail,
         animation: 'test-pulse 2s ease-in-out infinite',
     },
-    // Floating widget - position and colors only, inherits button structure.
-    // Bottom-LEFT: bottom-right is where the injected haltija dev widget sits, and it
-    // was overlaying this.
+    /*
+    The widget sits in the header bar, not over the page (GitHub #233).
+  
+    It used to be `position: fixed` at the bottom left, on top of whatever the page drew there:
+    a full-page component's list ran under it and a click on its last row landed on the widget
+    instead. Only a page with no header (`{"header": false}`) still floats it, because there is
+    nowhere else to put it. Bottom-LEFT, because the haltija dev widget takes bottom-right.
+    */
     '.test-widget': {
         _testBg: testColor.running,
         _testFg: testTextColor.running,
-        position: 'fixed',
-        bottom: vars.spacing,
-        left: vars.spacing,
-        zIndex: '1000',
         background: vars.testBg,
         // Paired with the background, not fixed to white — see testTextColor above.
         color: vars.testFg,
         gap: vars.spacing50,
     },
+    '.test-widget.-floating': {
+        position: 'fixed',
+        bottom: vars.spacing,
+        left: vars.spacing,
+        zIndex: '1000',
+    },
     '.test-widget[hidden]': { display: 'none' },
     '.test-widget.-running': {
         _testBg: testColor.running,
@@ -368,6 +375,7 @@ export function createDocBrowser(options) {
     // while letting <tosi-doc-system> drive clean `/slug/` URLs off the same docs.
     // Both path and memory routing key off slugs; only legacy query routing doesn't.
     const slugMap = routing === 'query' ? {} : buildSlugMap(docs);
+    const wikilinks = wikilinkTargets(docs);
     const slugFor = (filename) => slugMap[filename] ?? filename;
     const filenameForSlug = (slug) => {
         for (const d of docs)
@@ -974,6 +982,7 @@ export function createDocBrowser(options) {
             // without loading the tjs transpiler. See self-contained-examples-plan.md.
             docContent.innerHTML = renderDocMarkdown(doc.text, {
                 bakes: doc.bakes ? new Map(doc.bakes) : undefined,
+                wikilinks,
             });
         }
         /*
@@ -1029,6 +1038,7 @@ export function createDocBrowser(options) {
             // to follow the doc, so this does not ride on that path succeeding.
             refreshNavToggle();
         }
+        placeTestWidget(doc);
         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).
@@ -1262,7 +1272,7 @@ export function createDocBrowser(options) {
             return;
         editUI.view = view;
         if (view === 'preview') {
-            docContent.innerHTML = renderDocMarkdown(docMarkdownFromSource(editUI.editor.value, editUI.doc.path));
+            docContent.innerHTML = renderDocMarkdown(docMarkdownFromSource(editUI.editor.value, editUI.doc.path), { wikilinks });
             rewriteContentLinks();
             LiveExample.insertExamples(docContent, context, editUI.doc.path || undefined);
         }
@@ -1615,6 +1625,21 @@ export function createDocBrowser(options) {
             height: '100%',
         },
     }, docContent)));
+    // Test status widget
+    const testWidget = button({
+        class: 'test-widget',
+        hidden: true,
+        onClick: showTestMenu,
+    }, span({ part: 'label' }, 'Tests'), span({ class: 'count', part: 'count' }, '0'));
+    const headerBar = container.querySelector('header');
+    // In the header unless this doc hides the header; see `.test-widget` in the styles.
+    const placeTestWidget = (doc) => {
+        const floating = doc.header === false;
+        testWidget.classList.toggle('-floating', floating);
+        const home = floating ? container : headerBar;
+        if (testWidget.parentElement !== home)
+            home.appendChild(testWidget);
+    };
     // Render the landing doc (adopts pre-rendered HTML when hydrating).
     showDoc(currentDoc);
     // Inject test indicator styles
@@ -1622,13 +1647,6 @@ export function createDocBrowser(options) {
     // Header brand-mark sizing (icon / <img> / inline-<svg>), one CSS var each.
     StyleSheet('doc-logo-mark', logoMarkStyleSpec);
     StyleSheet('doc-nav-search', navSearchStyleSpec);
-    // Floating widget for test status
-    const testWidget = button({
-        class: 'test-widget',
-        hidden: true,
-        onClick: showTestMenu,
-    }, span({ part: 'label' }, 'Tests'), span({ class: 'count', part: 'count' }, '0'));
-    container.appendChild(testWidget);
     /*
     The far end has something to tell you.
   

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

@@ -7,7 +7,7 @@ Node-only APIs — so it bundles into the iife. Live examples are pretty-printed
 force-wrapped code listings, not executed.
 */
 import { renderDocMarkdown } from './render.js';
-import { buildSlugMap } from './routing.js';
+import { buildSlugMap, wikilinkTargets } from './routing.js';
 import { buildNavTree } from './nav-tree.js';
 import { bookTextOf } from './book-target.js';
 // Clean book typography; force-wraps code so listings never overflow a page.
@@ -149,10 +149,13 @@ function tocHtml(nodes) {
 export function buildBookHtml(docs, opts) {
     const visible = docs.filter((d) => !d.hidden);
     const slugMap = buildSlugMap(visible);
+    const wikilinks = wikilinkTargets(visible);
     const roots = buildNavTree(visible, slugMap);
     const css = opts.css ?? `${DEFAULT_BOOK_CSS}\n${PRINT_CSS}`;
     const chapters = flatten(roots)
-        .map((node) => `<section class="chapter" id="${slugify(node.doc.filename)}">\n${renderDocMarkdown(stripDocMeta(bookTextOf(node.doc)))}\n</section>`)
+        .map((node) => `<section class="chapter" id="${slugify(node.doc.filename)}">\n${renderDocMarkdown(stripDocMeta(bookTextOf(node.doc)), {
+        wikilinks,
+    })}\n</section>`)
         .join('\n');
     return `<!DOCTYPE html>
 <html lang="${opts.lang ?? 'en'}">