tosijs-ui 1.16.24 → 1.16.26

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # Changelog
 
+## 1.16.26
+
+### Tunnel
+
+- **Global keys: one link opens every workspace, and survives restarts.** The preview host can
+  hold two machine-wide keys: `PREVIEW_EDIT_TOKEN` (new, optional) opens every workspace for
+  editing, and `PREVIEW_TOKEN` (the static previews' invite secret) opens them read-only.
+  Put them in `/etc/caddy/preview.env` on the box (re-run `tosijs-caddy-install`) and in
+  `~/local-secrets/tosijs-preview.env` on each machine running a dev server. Visit the box's
+  root once with `?t=<key>`: Caddy sets a cookie across the preview domain (24 hours for the
+  edit key), and the root page lists every workspace that is up and whether you can edit or
+  only view it. Opening one starts a session there on the first page load, and after a
+  dev-server restart a reload is all it takes. Keys must be at least 24 letters, digits, `-` or
+  `_`, because the box compares them with no rate limit; the installer refuses a short edit
+  key, and a dev server ignores one and says so. A workspace can refuse them with
+  `tunnel.globalKeys: false`, or with `'view'` let either key browse and neither edit; any other
+  value refuses both and says so. The eight-letter `--link` codes are unchanged.
+- **The view key is your preview invite.** Everyone you have given a static-preview link can,
+  by default, also read every workspace that accepts the view key while it is up, even with
+  `requireToken`. Set `tunnel.globalKeys: false` on a project that should stay yours, or rotate
+  the invite secret.
+- **Rotating a key** means editing both files, re-running the installer and restarting the dev
+  servers: a session a key already opened lasts up to 24 hours and is not re-checked against
+  the key until its server restarts.
+- **`tosijs-tunnel` refreshes the box's root page** when it registers a workspace, so a newly
+  tunnelled project appears in the list straight away. The box's root page escapes project
+  names, which it inserted into the page as they were.
+- The edit key opens a `globalKeys: 'view'` workspace read-only, as the view key does.
+
+### Security
+
+- **Source and data writes over the tunnel must come from the workspace's own origin**
+  (affected: 1.9.0 to 1.16.25). They relied on the session cookie's `SameSite=Lax`, but every
+  host under the preview domain is the same *site*, so a page on another project's preview (its
+  live examples included) could POST to your workspace with your session attached. The haltija
+  bridge's component and socket over the tunnel check the same (affected: 1.12.2 to 1.16.25).
+- **A read-only session can no longer attach the haltija agent bridge** (affected: 1.15.0 to
+  1.16.25, with `haltijaDev: 'tunnel'`). A share link's session passed the bridge's gate, which
+  asked only whether the session was valid.
+- **A redirect after redeeming a link stays on the workspace.** A link at a path starting `//`
+  redirected to another host.
+
+## 1.16.25
+
+### Dev server
+
+- **`editableData`: folders an editor on the dev page may save to** (#3365). A level or
+  scene editor running on a dev-server page can list, read and save the project's data files
+  through `/__docstore/data`, behind the same gate as source: this machine, an edit session
+  over the tunnel, or the LAN under `trustLan`. Share links stay read-only.
+  `editableData: ['static/levels']`, or `{ dirs, extensions, commit }`. Only data formats may
+  be allowed (`.json` by default; also `.jsonc` `.json5` `.ndjson` `.txt` `.csv` `.tsv`
+  `.yaml` `.yml` `.toml`), so nothing saved there runs or renders. Dot-files and symlinks are
+  never written, nor are common configuration names (`package.json`, `tsconfig.json`,
+  `firebase.json`, `*.config.*`), though the folders you name are the real boundary. A `.json`
+  save must parse, and a save replaces the file whole. A folder outside the project, the
+  project itself, one in or around `.git` or `node_modules`, or one overlapping the build
+  output stops the server at launch. `tosijs-ui/site` exports the `EditableDataOptions` type
+  and the `DATA_EXTENSIONS` list.
+- **`commit: true` makes every save a version.** Each save is its own commit
+  (`data: save <file>`, naming who saved it), and other staged work is left alone. The
+  repository's hooks run, and each git step gets 20 seconds. Nothing is committed while the
+  repository is mid-rebase, mid-merge, cherry-picking, reverting, bisecting or on a detached
+  HEAD. `?history=<file>` lists a file's latest 100 versions and `?file=<file>&at=<commit>` reads
+  one back. A save that wrote the file but did not commit answers with `commitError` instead of
+  reporting a clean save. Each committed save waits for git, so it suits an explicit Save, not
+  autosave.
+- **`tosijs-ui/doc-system/data-client`** wraps the endpoint for an editor: `listData`,
+  `readData` (text, or `{ json: true }`, or `{ at }`), `saveData` (a string as is, anything
+  else as formatted JSON) and `dataHistory`. A refusal rejects with a `DataStoreError` carrying
+  the status, and so does a page answering for the endpoint (a static host's catch-all), so
+  `listData()` tells an editor whether to offer saving.
+- **`trustLan` can name your network**, so a committed setting trusts nobody on anyone else's:
+  `trustLan: '192.168.1.0/24'` or a list, IPv4 or IPv6. Only private addresses inside it are
+  trusted. **`TOSIJS_TRUST_LAN`** sets it for one run and wins over the config either way: `1`,
+  a network, or `0` to turn a committed setting off. A network that cannot be parsed stops the
+  server at launch, and the launch warning names who is trusted and where the setting came from.
+  A refused device outside the named networks is told so in the log, and the messages readers
+  see when the LAN is refused now suggest these forms rather than `trustLan: true`.
+- **The SPA fallback shows the page the URL names.** Was: a path with no file of its own got
+  the root page, which then asked for its assets relative to that path, got 404s and never
+  hydrated; with `home` set, a reader saw the home doc. Now the dev server serves the root page
+  with its relative URLs made root-relative (in-page `#` links still stay on the page), and
+  hydration adopts a pre-rendered article only when it is the doc being shown. Generated pages
+  stamp the article with `data-doc` for that. The asset fix is the dev server's; a static host's
+  own catch-all rewrite is unchanged.
+
 ## 1.16.24
 
 `dist/iife.js` grows by about 0.2 kB gzip.

package/bin/caddy-install.ts

@@ -24,9 +24,11 @@ Three deliberate properties:
   anything else through Caddy, that is destructive — so the dry run prints a diff against
   the live file and you get to look at it before `--go`.
 
-  THE SECRET NEVER LEAVES THE BOX. Substitution happens remotely, reading
-  `/etc/caddy/preview.env`. `PREVIEW_TOKEN` is never transmitted, never appears in argv on
-  this machine, and is redacted out of the diff before it is printed.
+  THIS COMMAND NEVER CARRIES THE SECRETS. Substitution happens remotely, reading
+  `/etc/caddy/preview.env`. `PREVIEW_TOKEN` and `PREVIEW_EDIT_TOKEN` are never transmitted by
+  it, never appear in argv on this machine, and are redacted out of the diff before it is
+  printed. (Global keys are a separate choice: to use them, you copy the same values into
+  ~/local-secrets on the machines that run dev servers.)
 
   VALIDATE BEFORE SWAP. `caddy fmt` then `caddy validate` run against a scratch file; the
   live config is replaced by an atomic `mv` only once it is known to parse. A rejected
@@ -121,14 +123,28 @@ set -a; . /etc/caddy/preview.env; set +a
 : "\${ACME_EMAIL:?set ACME_EMAIL in /etc/caddy/preview.env}"
 : "\${PREVIEW_DOMAIN:?set PREVIEW_DOMAIN in /etc/caddy/preview.env}"
 
+# The global EDIT key is optional. Unset, the template still needs a value, so it gets one
+# nobody knows and the edit cookie opens nothing. Set, it is compared by Caddy with no rate
+# limit in front, so it must be long, and the cookie match needs a plain alphabet.
+if [ -z "\${PREVIEW_EDIT_TOKEN:-}" ]; then
+  PREVIEW_EDIT_TOKEN="unset-$(od -An -tx1 -N24 /dev/urandom | tr -d ' \\n')"
+elif ! printf '%s' "$PREVIEW_EDIT_TOKEN" | grep -qE '^[A-Za-z0-9_-]{24,}$'; then
+  echo "PREVIEW_EDIT_TOKEN must be at least 24 letters, digits, - or _ — refusing to install." >&2
+  exit 1
+elif [ "$PREVIEW_EDIT_TOKEN" = "$PREVIEW_TOKEN" ]; then
+  echo "PREVIEW_EDIT_TOKEN equals PREVIEW_TOKEN, so every preview link could edit — refusing to install." >&2
+  exit 1
+fi
+
 sed -e "s|__PREVIEW_TOKEN__|$PREVIEW_TOKEN|g" \\
+    -e "s|__PREVIEW_EDIT_TOKEN__|$PREVIEW_EDIT_TOKEN|g" \\
     -e "s|{{ACME_EMAIL}}|$ACME_EMAIL|g" \\
     -e "s|{{PREVIEW_DOMAIN}}|$PREVIEW_DOMAIN|g" \\
     /etc/caddy/Caddyfile.tpl > /etc/caddy/Caddyfile.new
 
-if grep -qE '\\{\\{|__PREVIEW_TOKEN__' /etc/caddy/Caddyfile.new; then
+if grep -qE '\\{\\{|__PREVIEW_(EDIT_)?TOKEN__' /etc/caddy/Caddyfile.new; then
   echo "Unsubstituted placeholders remain — refusing to install:" >&2
-  grep -nE '\\{\\{|__PREVIEW_TOKEN__' /etc/caddy/Caddyfile.new >&2
+  grep -nE '\\{\\{|__PREVIEW_(EDIT_)?TOKEN__' /etc/caddy/Caddyfile.new >&2
   rm -f /etc/caddy/Caddyfile.new
   exit 1
 fi
@@ -150,7 +166,8 @@ else
   echo "--- would change /etc/caddy/Caddyfile (token redacted) ---"
   if [ -f /etc/caddy/Caddyfile ]; then
     diff -u /etc/caddy/Caddyfile /etc/caddy/Caddyfile.new \\
-      | sed "s|$PREVIEW_TOKEN|***REDACTED***|g" || true
+      | sed -e "s|$PREVIEW_TOKEN|***REDACTED***|g" \\
+            -e "s|$PREVIEW_EDIT_TOKEN|***REDACTED***|g" || true
   else
     echo "(no existing /etc/caddy/Caddyfile — this would create it)"
   fi

package/bin/deploy-preview.ts

@@ -31,6 +31,7 @@ import { existsSync } from 'fs'
 import {
   previewRootFor,
   registerCaddyFragment,
+  refreshHostIndex,
   resolvePreviewHost,
   parseArgv,
 } from './resolve-site-config.ts'
@@ -205,51 +206,10 @@ async function registerSite(): Promise<boolean> {
   return ok
 }
 
-/** Refresh the host's index so this deploy shows up immediately. */
-async function refreshIndex(): Promise<void> {
-  const remote = `/tmp/tosi-build-index-${process.pid}.sh`
-  /*
-  Resolve the script against THIS PACKAGE, not the adopter's cwd.
-
-  `deploy/` is in `files`, so the asset ships at node_modules/tosijs-ui/deploy/ — only
-  the resolution was wrong, which meant every adopter's scp failed, the failure was
-  swallowed by a bare `return`, and the deploy still printed "✅ Deployed". Exactly the
-  #37 class of bug, one cycle later: a package asset located relative to whoever called us.
-  */
-  const script = `${import.meta.dir}/../deploy/build-index.sh`
-  const put = await $`scp -q ${script} ${`${host}:${remote}`}`.nothrow().quiet()
-  if (put.exitCode !== 0) {
-    // Loudly: the deploy itself succeeded, so this must not read as total failure —
-    // but a silently stale index is how you conclude a deploy did not land.
-    console.warn(
-      `⚠️  Could not refresh the host index (scp of ${script} failed).\n` +
-        `   The deploy landed; the listing at the root will be stale until the next one.\n` +
-        `   ${put.stderr.toString().trim().slice(0, 200)}`
-    )
-    return
-  }
-  const run = await $`ssh ${host} bash ${remote}`.nothrow().quiet()
-  await $`ssh ${host} rm -f ${remote}`.nothrow().quiet()
-  // build-index.sh is `set -euo pipefail`; a non-root user on a root-owned tree dies at
-  // mkdir. Discarding this exit code meant the deploy printed ✅ over a failed index.
-  if (run.exitCode !== 0) {
-    console.warn(
-      `⚠️  the host index was not refreshed (exit ${run.exitCode}). The deploy landed;\n` +
-        `   the listing at the root will be stale until the next successful one.\n` +
-        `   ${(run.stderr.toString() || run.stdout.toString())
-          .trim()
-          .slice(0, 200)}`
-    )
-    return
-  }
-  const out = run.stdout.toString().trim()
-  if (out) console.log(`   ${out}`)
-}
-
 let routed = true
 if (go) {
   routed = await registerSite()
-  await refreshIndex()
+  await refreshHostIndex(host!)
 }
 
 /*

package/bin/resolve-site-config.ts

@@ -19,7 +19,8 @@ silently picking up a parent directory's config would mean publishing the wrong
 and "it found something" is not the same as "it found yours".
 */
 
-import { existsSync, readFileSync } from 'fs'
+import { $ } from 'bun'
+import { existsSync } from 'fs'
 import * as path from 'path'
 
 export interface PreviewConfig {
@@ -151,47 +152,11 @@ export {
 } from '../dist/doc-system/site/site-config.js'
 
 /*
-Where the preview host comes from — ONE implementation, and a fallback that works for
-things that are not a human at an interactive prompt.
-
-`PREVIEW_HOST` lives in `~/local-secrets/tosijs-preview.env`: mode 700, a sibling of the
-repos rather than inside one, so it is structurally impossible to commit. That is a stronger
-guarantee than a rule saying "don't commit the host", which this project wrote, believed, and
-then violated in its own `tosijs-site.config.ts` for months.
-
-The fallback exists because the previous advice — "export it from your shell profile" — is
-present for a human and ABSENT for every tool: non-interactive shells inherit no interactive
-profile, so an agent or a CI step sees nothing and reports a missing credential rather than a
-missing `export`. Reading the file directly makes the resolution order true for both.
-
-Parses only `KEY=value` / `export KEY=value`, strips one layer of quotes, ignores the rest.
-Not a shell — a credentials file that needs evaluating is a credentials file that can run
-code.
+`readLocalSecret` lives in the package (`src/doc-system/site/local-secrets.ts`) because the dev
+server reads the global tunnel keys from the same file; it is re-exported here for the bins.
 */
-export function readLocalSecret(
-  name: string,
-  file = path.join(
-    process.env.HOME ?? '',
-    'local-secrets',
-    'tosijs-preview.env'
-  )
-): string | undefined {
-  if (!process.env.HOME || !existsSync(file)) return undefined
-  let text: string
-  try {
-    text = readFileSync(file, 'utf8')
-  } catch {
-    return undefined
-  }
-  for (const line of text.split('\n')) {
-    const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(
-      line
-    )
-    if (!m || m[1] !== name) continue
-    return m[2].trim().replace(/^(['"])(.*)\1$/, '$2')
-  }
-  return undefined
-}
+export { readLocalSecret } from '../dist/doc-system/site/local-secrets.js'
+import { readLocalSecret } from '../dist/doc-system/site/local-secrets.js'
 
 /**
  * `--host=` > `PREVIEW_HOST` > `PREVIEW_SSH` (legacy) > **site config** > `~/local-secrets`.
@@ -434,3 +399,47 @@ export function parseArgv(argv: string[], spec: ArgvSpec): Argv {
     rest: argv.filter((a) => !a.startsWith('--')),
   }
 }
+
+/**
+ * Refresh the host's index so a deploy, or a newly registered tunnel, shows up immediately.
+ * Shared by `tosijs-deploy` and `tosijs-tunnel`.
+ */
+export async function refreshHostIndex(host: string): Promise<void> {
+  const remote = `/tmp/tosi-build-index-${process.pid}.sh`
+  /*
+  Resolve the script against THIS PACKAGE, not the adopter's cwd.
+
+  `deploy/` is in `files`, so the asset ships at node_modules/tosijs-ui/deploy/ — only
+  the resolution was wrong, which meant every adopter's scp failed, the failure was
+  swallowed by a bare `return`, and the deploy still printed "✅ Deployed". Exactly the
+  #37 class of bug, one cycle later: a package asset located relative to whoever called us.
+  */
+  const script = `${import.meta.dir}/../deploy/build-index.sh`
+  const put = await $`scp -q ${script} ${`${host}:${remote}`}`.nothrow().quiet()
+  if (put.exitCode !== 0) {
+    // Loudly: the deploy or tunnel itself succeeded, so this must not read as total
+    // failure — but a silently stale index is how you conclude it did not land.
+    console.warn(
+      `⚠️  Could not refresh the host index (scp of ${script} failed).\n` +
+        `   The listing at the root will be stale until the next refresh.\n` +
+        `   ${put.stderr.toString().trim().slice(0, 200)}`
+    )
+    return
+  }
+  const run = await $`ssh ${host} bash ${remote}`.nothrow().quiet()
+  await $`ssh ${host} rm -f ${remote}`.nothrow().quiet()
+  // build-index.sh is `set -euo pipefail`; a non-root user on a root-owned tree dies at
+  // mkdir. Discarding this exit code meant the deploy printed ✅ over a failed index.
+  if (run.exitCode !== 0) {
+    console.warn(
+      `⚠️  the host index was not refreshed (exit ${run.exitCode}). The listing at\n` +
+        `   the root will be stale until the next successful refresh.\n` +
+        `   ${(run.stderr.toString() || run.stdout.toString())
+          .trim()
+          .slice(0, 200)}`
+    )
+    return
+  }
+  const out = run.stdout.toString().trim()
+  if (out) console.log(`   ${out}`)
+}

package/bin/tunnel.ts

@@ -34,6 +34,7 @@ import { $ } from 'bun'
 import {
   previewRootFor,
   registerCaddyFragment,
+  refreshHostIndex,
   resolveDevPort,
   resolvePreviewHost,
   resolveSiteConfig,
@@ -418,6 +419,8 @@ 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!)
   }
 }
 

package/deploy/Caddyfile

@@ -2,8 +2,10 @@
 #
 #   {{ACME_EMAIL}}      your Let's Encrypt account email
 #   {{PREVIEW_DOMAIN}}  the domain your preview hosts live under (e.g. dev.example.com)
-#   __PREVIEW_TOKEN__   the shared invite secret, substituted at install time from
-#                       /etc/caddy/preview.env — NEVER commit a real value here
+#   __PREVIEW_TOKEN__   the shared invite secret (the global VIEW key), substituted at
+#                       install time from /etc/caddy/preview.env — NEVER commit a real value
+#   __PREVIEW_EDIT_TOKEN__  the global EDIT key, from the same file; optional (unset, the
+#                       installer fills in a value nobody knows)
 #
 # Installing this file with the placeholders intact gives you a preview host whose entire
 # invite gate is a literal string published in a public repo and in every npm tarball, and
@@ -64,7 +66,28 @@
 		redir * / 302
 	}
 
-	@unauthed not header_regexp Cookie "tosi_preview=__PREVIEW_TOKEN__"
+	# 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
+	# (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
+	# opens workspaces read-only the same way. See `globalKeys` in doc-site-system.md.
+	#
+	# The cookie is the key itself: Caddy can compare a fixed value and cannot sign one. A
+	# leaked edit cookie is write access to every workspace that accepts the key until it is
+	# 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 Referrer-Policy "no-referrer"
+		header Cache-Control "no-store"
+		redir * / 302
+	}
+
+	@unauthed {
+		not header_regexp Cookie "tosi_preview=__PREVIEW_TOKEN__"
+		not header_regexp Cookie "tosi_edit=__PREVIEW_EDIT_TOKEN__"
+	}
 	handle @unauthed {
 		header Content-Type "text/html; charset=utf-8"
 		header Cache-Control "no-store"

package/deploy/build-index.sh

@@ -21,6 +21,9 @@
 set -euo pipefail
 
 ROOT=/srv/preview
+
+# Names come from config and file names; nothing reaches the page unescaped.
+html() { printf '%s' "$1" | sed -e 's/&/\&amp;/g' -e 's/</\&lt;/g' -e 's/>/\&gt;/g' -e 's/"/\&quot;/g'; }
 OUT="$ROOT/_index"
 mkdir -p "$OUT"
 
@@ -39,6 +42,7 @@ for dir in "$ROOT"/*/; do
 	gen=$(sed -n 's/.*"generator": *"\([^"]*\)".*/\1/p' "$vj" | head -1)
 	site=$(sed -n 's/.*"site": *"\([^"]*\)".*/\1/p' "$vj" | head -1)
 	[ -n "$site" ] || site="$name"
+	site=$(html "$site")
 
 	# The hostname comes from the project's OWN Caddy fragment — the same file the
 	# router reads — so this listing cannot disagree with what actually serves. An
@@ -71,6 +75,24 @@ 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.
+live=""
+for frag in "$ROOT"/_sites/*-tunnel.caddy; do
+	[ -f "$frag" ] || continue
+	name="$(html "$(basename "$frag" -tunnel.caddy)")"
+	host=$(sed -n 's/^\([A-Za-z0-9.-]*\) *{.*/\1/p' "$frag" | head -1)
+	[ -n "$host" ] || continue
+	live="$live
+	<li data-workspace=\"$host\" hidden>
+		<a href=\"https://$host/\">
+			<span class=\"name\">$name</span>
+			<span class=\"meta\"><span class=\"access\"></span><code>$host</code></span>
+		</a>
+	</li>"
+done
+
 # The REAL tosiPlatform icon, lifted verbatim from src/icons/data/tosiPlatform.ts.
 # (The first version of this file hand-drew a rough approximation — a blue box with a
 # stroke in it — which is exactly the sort of thing nobody notices in review and
@@ -108,6 +130,9 @@ cat > "$OUT/index.html" <<HTML
 	code { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; }
 	.gen { display:block; color:var(--dim); font-size:.75rem; margin-top:.3rem; }
 	.empty { color:var(--dim); }
+	h2 { font-size:1rem; margin:2rem 0 .75rem; font-weight:600; }
+	.access { font-weight:600; }
+	.access.edit { color:#2a8a3e; }
 	footer { color:var(--dim); font-size:.8rem; margin-top:2.5rem; }
 </style>
 <main>
@@ -116,6 +141,8 @@ cat > "$OUT/index.html" <<HTML
 	$(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>
@@ -133,6 +160,24 @@ cat > "$OUT/index.html" <<HTML
 		t.textContent = rel
 		t.title = d.toLocaleString()
 	}
+
+	// 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.
+	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((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
+			})
+			.catch(() => {})
+	}
 </script>
 HTML
 

package/dist/doc-browser.js

@@ -111,6 +111,7 @@ import { tosiLocalized } from './localize.js';
 import { popMenu } from './menu.js';
 import { codeEditor } from './code-editor.js';
 import { tosiDiff } from './diff.js';
+import { LAN_REFUSAL_ADVICE } from './live-example/source-access.js';
 /*
 Does this doc contain a REAL ` ```test ` block, as opposed to mentioning one?
 
@@ -954,8 +955,18 @@ export function createDocBrowser(options) {
     };
     let adoptInitialContent = contentElement !== undefined && !memoryRouting;
     const showDoc = (doc) => {
-        if (adoptInitialContent) {
-            adoptInitialContent = false; // leave the pre-rendered HTML untouched
+        /*
+        Adopt the pre-render only if it IS this doc. The dev server's SPA fallback serves the root
+        page for a path with no file of its own, so `/guide/` can arrive holding the home page's
+        article (#3346). The generator stamps `data-doc`; a page without it predates the stamp
+        and is adopted as before.
+        */
+        const prerendered = contentElement?.dataset.doc;
+        const adopt = adoptInitialContent &&
+            (prerendered === undefined || prerendered === doc.filename);
+        adoptInitialContent = false;
+        if (adopt) {
+            // leave the pre-rendered HTML untouched
         }
         else {
             // Pass the doc's build-time tjs bakes so this client-rendered page embeds the
@@ -1291,7 +1302,7 @@ export function createDocBrowser(options) {
             window.alert('This workspace needs an invite link before it can save.\n\n' +
                 'Run `tosijs-tunnel --link` on the machine hosting it, open the link once, ' +
                 'then try again. Your edit is still here.\n\n' +
-                'If you opened this over the LAN (a `.local` or local IP address), invite links will not help: set `trustLan: true` in the site config, or use its tunnel URL instead.');
+                LAN_REFUSAL_ADVICE);
         }
         else {
             // Genuinely no write endpoint (a deployed static site) — hand the file back.
@@ -1306,7 +1317,7 @@ export function createDocBrowser(options) {
             window.alert(sourceUnauthorized
                 ? 'This workspace needs an invite link before you can edit.\n\n' +
                     'Run `tosijs-tunnel --link` on the machine hosting it and open the link once.\n\n' +
-                    'If you opened this over the LAN (a `.local` or local IP address), invite links will not help: set `trustLan: true` in the site config, or use its tunnel URL instead.'
+                    LAN_REFUSAL_ADVICE
                 : `Could not load source for ${doc.path}`);
             return;
         }

package/dist/doc-system/data-client.d.ts

@@ -0,0 +1,35 @@
+export declare class DataStoreError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+/** Every editable file, project-relative, newest first. */
+export declare function listData(): Promise<{
+    files: {
+        file: string;
+        size: number;
+        modified: string;
+    }[];
+}>;
+/** A file's text, or parsed JSON with `json: true`; `at` reads it as of a commit. */
+export declare function readData(file: string, options: {
+    at?: string;
+    json: true;
+}): Promise<any>;
+export declare function readData(file: string, options?: {
+    at?: string;
+    json?: false;
+}): Promise<string>;
+/** Save a file: a string as it is, anything else as formatted JSON. */
+export declare function saveData(file: string, content: unknown): Promise<{
+    ok: true;
+    file: string;
+    commit?: string | null;
+    commitError?: string;
+}>;
+/** A file's committed versions, newest first. */
+export declare function dataHistory(file: string): Promise<{
+    commit: string;
+    date: string;
+    author: string;
+    subject: string;
+}[]>;

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

@@ -0,0 +1,105 @@
+/*{ "parent": "Documentation System", "order": 85 }*/
+/*#
+# data client
+
+For an editor running on a dev-server page (a level editor, a scene editor) to open and save
+the project's data files through `/__docstore/data`. Turn it on by naming the folders in the
+site config; [`editableData`](/doc-site-system/) in the doc-site system reference has the
+rules.
+
+```typescript
+// tosijs-site.config.ts
+editableData: { dirs: ['static/levels'], commit: true }
+```
+
+```typescript
+import { listData, readData, saveData, dataHistory } from 'tosijs-ui/doc-system/data-client'
+
+const { files } = await listData()
+const level = await readData('static/levels/ocean.json', { json: true })
+level.spawn = [0, 2, 0]
+const { commit } = await saveData('static/levels/ocean.json', level)
+const versions = await dataHistory('static/levels/ocean.json')
+if (versions.length > 1) {
+  const before = await readData('static/levels/ocean.json', { at: versions[1].commit })
+}
+```
+
+`saveData` writes an object as JSON (two-space indent, trailing newline) and a string as it
+is. With `commit: true` in the config each save is its own commit, and `commit` in the result
+is its hash (`null` when the save changed nothing). A save that wrote but could not commit
+(a failing hook, or a repository mid-rebase) resolves with `commitError` set rather than
+rejecting, because the file was saved. Each committed save runs git and the repository's
+hooks before it answers, so it suits an explicit Save, not autosave.
+
+**Dev server only.** Everything else rejects with a `DataStoreError` whose `status` says why:
+`501` when the server has no `editableData`, `403` when this page may not edit files here or
+the file is not editable, `400` for content it refuses (JSON that does not parse). A response
+that is not the endpoint's (a deployed site's catch-all answering with a page) rejects too, so
+`listData()` is the probe for whether to offer saving at all.
+
+File names may use letters, digits, `-`, `_`, `.`, `/` and spaces. `dataHistory` returns the
+latest 100 versions.
+*/
+const ENDPOINT = '/__docstore/data';
+export class DataStoreError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'DataStoreError';
+    }
+}
+async function ask(query, init) {
+    const response = await fetch(`${ENDPOINT}${query}`, {
+        credentials: 'same-origin',
+        ...init,
+    });
+    /*
+    The endpoint answers JSON or the file's text, never a page. An HTML answer is something
+    else's: a static host's catch-all serving its index for every path.
+    */
+    const type = response.headers.get('content-type') ?? '';
+    if (response.ok && type.includes('text/html')) {
+        throw new DataStoreError(`${init?.method ?? 'GET'} ${ENDPOINT}${query}: answered with a page, not the data endpoint (no dev server here?)`, response.status);
+    }
+    if (!response.ok) {
+        const text = await response.text();
+        let message = text;
+        try {
+            message = JSON.parse(text).error ?? text;
+        }
+        catch {
+            // plain text
+        }
+        throw new DataStoreError(`${init?.method ?? 'GET'} ${ENDPOINT}${query}: ${response.status} ${message}`, response.status);
+    }
+    return response;
+}
+const q = (params) => '?' + new URLSearchParams(params).toString();
+/** Every editable file, project-relative, newest first. */
+export async function listData() {
+    return (await ask('?list')).json();
+}
+export async function readData(file, options = {}) {
+    const params = { file };
+    if (options.at)
+        params.at = options.at;
+    const text = await (await ask(q(params))).text();
+    return options.json ? JSON.parse(text) : text;
+}
+/** Save a file: a string as it is, anything else as formatted JSON. */
+export async function saveData(file, content) {
+    const text = typeof content === 'string'
+        ? content
+        : JSON.stringify(content, null, 2) + '\n';
+    return (await ask('', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ file, content: text }),
+    })).json();
+}
+/** A file's committed versions, newest first. */
+export async function dataHistory(file) {
+    return (await (await ask(q({ history: file }))).json()).versions;
+}