tosijs-ui 1.9.0-beta.2 → 1.9.0-rc.2

package/CHANGELOG.md

@@ -1,5 +1,173 @@
 # Changelog
 
+## 1.9.0-rc.2
+
+Fixes everything both consumers hit within minutes of `rc.1`. Three were regressions
+introduced by rc.1 itself.
+
+- **The `tosijs-tunnel` / `tosijs-deploy` bins had no shebang** (#35, #36 — reported
+  independently by both consumers), so `node_modules/.bin` shims handed them to the
+  shell, which ran TypeScript as a shell script. Added to every shipped bin.
+- **`/version.json`'s `generator` reported the CONSUMER's version** (#37). rc.1 replaced
+  an import of the generated `src/version.ts` (which caused a `bun --watch` rebuild loop)
+  with a read of `package.json` — but that resolves against the **cwd**, i.e. the
+  adopter's repo. So the one field you consult to answer "which tosijs-ui built this?"
+  answered with the wrong package entirely. Now resolved relative to the module.
+- **Two dev servers could not coexist.** The tunnel listener bound a fixed port
+  regardless of `PORT`, so a second server — or this repo's own Playwright lane beside a
+  `bun start` — died with `EADDRINUSE`. It now defaults to `PORT + 1`, and a busy tunnel
+  port warns instead of taking the whole server down: it is an optional extra, and
+  refusing to start over it turns "another instance is running" into "my dev server is
+  broken".
+- **New lane: `bun run test-consumer`** — packs the tarball, installs it into a scratch
+  project, runs every bin through the `node_modules/.bin` shims, and builds a site from
+  that project's cwd. Every other lane runs *in this repo, from this repo, with one dev
+  server*, and all four rc.1-era regressions lived outside that envelope. It found a real
+  bug on its first run.
+- **A failed "save to source" now says why** (#34). The endpoint answers 501 with an
+  actionable sentence ("editableSources is not enabled…") and the client threw it away
+  for a generic "Save failed.", so an unconfigured server was indistinguishable from a
+  broken one and the edit appeared to vanish. The server's reason is surfaced, and every
+  failure path now states that the edit is still in the editor.
+
+
+## 1.9.0-rc.1
+
+Release candidate. Everything the nine-lens review and the first adopters raised is
+addressed; no features are pending. Install with `tosijs-ui@rc`.
+
+**Edit and view are now separate hostnames**, which makes the security posture legible
+without reading config:
+
+| host | what it is | gate |
+| --- | --- | --- |
+| `<project>.dev.example.com` | read-only static preview — shareable | invite cookie |
+| `<project>.edit.dev.example.com` | live editable workspace — yours | session, always |
+
+- **`tunnel.requireToken` now defaults to `true`.** The old default (read-open) was
+  justified by "an expired link should degrade to a readable page when you open a second
+  window" — but a second window **shares the session cookie**, so a holder is never
+  walled. The wall only appears for someone genuinely unauthenticated, which is the right
+  answer for a workspace mirroring an uncommitted tree. Note the hostname is not a
+  secret: Let's Encrypt publishes every certificate to public CT logs. Set `false`
+  deliberately if you want a live read-only audience.
+- **An edit host with no tunnel behind it explains itself** — a 503 saying the workspace
+  is offline, with a link to the static preview, instead of a bare 502. It deliberately
+  does *not* fall back to serving the snapshot: you would think you were looking at live
+  work when you were not.
+- **A spent invite link says so.** The likely culprit is a chat-app link-preview bot,
+  whose GET *is* the first use; previously you got a silent redirect and discovered it
+  when a save failed.
+
+**Security fixes** (all found by review or adopters, none reported in the wild):
+
+- `POST /report` was unauthenticated and reachable through the tunnel — a stranger could
+  fabricate `{passed:N, failed:0}` and make the test lane **exit green on a suite that
+  never ran**. Now local-only.
+- Build-error text (absolute paths from your machine) was injected into every served page
+  with no auth check. The label stays public; the detail needs a session.
+- `rsync --delete` accepted any absolute path two segments deep — including `/usr/lib`
+  and `/etc/caddy`, which it would have *mirrored*, i.e. emptied. Now an allowlist of
+  preview roots, extracted and tested.
+
+**Adopter-reported fixes** (all from tosijs-3d, all consumer-facing):
+
+- **`tosijs-make-icons` stripped `fill-rule`** (#30), so a compound path using `evenodd`
+  for holes — a keyboard drawn as one path — rendered the holes solid. `fill-rule` is
+  fill *topology*, not colour, and takes no part in the tinting the strip exists for.
+  It turned out to be stripped in **three** places, not one; the `stroked/` branch is the
+  one that bit. This ships as a bin, so it affects anyone generating their own icon data.
+- **The doc-site hydrate bundle was written into the library `dist/`** (#31) and shipped
+  to every consumer, though nothing references it — one adopter's package went from
+  0.62 MB / 398 files to **10.2 MB / 2888 files**, caught only by reading `npm pack`
+  output. It now builds in a temp dir; tosijs-ui's own package drops 16 files and 5.2 MB
+  of uncompressed payload.
+- **New: `iconSvg(name)` and `iconNames()`** (#33), from `tosijs-ui/icon-svg` — raw SVG
+  markup with **no DOM required**. `defineIcons()` could write to the icon map but
+  nothing could read it, and `icons.foo()` returns an `SVGElement`, so a build script,
+  ePub pass or server-rendered template had no way to get markup except parsing the
+  package's source. Deliberately a separate module: `icons.ts` imports tosijs and throws
+  on `HTMLElement` outside a browser, which is the exact context that wanted it.
+
+**Correctness:**
+
+- **A 403 could destroy uncommitted work.** An unauthorized read fell through to GitHub
+  `main`, so you edited the *published* file, and the save then handed you a download of
+  it — applying which silently reverts your working copy. 401/403 is now its own case in
+  both editors.
+- **The last-good build protection moved to where the wipe is.** It lived in the dev
+  server's watch branch, so `bun run build`, CI, adopters, and `bun start`'s own initial
+  build had none of it. Now in `buildSite`, in a `finally` covering both a throw and a
+  `return false`, with exit codes checked (the old restore could fail while still logging
+  that it had succeeded).
+- "Build failed" is no longer overwritten by test results seconds later.
+- `?t=` is only intercepted when a tunnel is configured, and only on GET — `t` is the
+  classic cache-buster name, and a 302'd POST loses its body.
+
+
+## 1.9.0-beta.3
+
+Fixes three blockers found by the nine-lens review of beta.2, all in the remote-editing
+feature, plus a rebuild loop the review did not catch because nothing automated runs
+`bun start`.
+
+- **`bun run tunnel --link` never worked.** It ran `pgrep -f 'bun bin/dev.ts'`, which does
+  not match the documented start command (`bun --watch bin/dev.ts`) — so the headline flow
+  was unreachable. Worse, it *did* match `bun bin/dev.ts --build-only`, whose process exits
+  before the signal handler is registered, so the default SIGUSR2 disposition **killed
+  in-flight builds**. Now it asks the dev server over a loopback-only `/__devlink` endpoint:
+  no process guessing, no signals, and it cannot touch a sibling project. (`/__devlink` is
+  refused over the tunnel — a read-only visitor minting a write session would be privilege
+  escalation.)
+- **Write authorization failed OPEN.** It inferred "this is local" from the *absence* of
+  `X-Forwarded-*`, so any forwarder that doesn't set them — `ssh -R` with `GatewayPorts yes`,
+  `ngrok tcp`, `socat`, iptables DNAT, nginx without `forwardfor` — delivered an off-machine
+  request as `{peer: 127.0.0.1, no headers}` and got an **arbitrary repo write**, which the
+  watcher rebuilds and runs. The dev server now binds a **separate loopback-only port** for
+  tunnel traffic; arriving there always requires a session. Which socket you connected to is
+  not something a client can forge. `bun run tunnel` also verifies the remote port is bound
+  to loopback and says so loudly if it isn't.
+- **The decision guarding that RCE had no tests**, while its own comment claimed a
+  regression test that did not exist. It is now `mayWriteSource()` — pure, exported, and
+  covered including a named regression case for the fail-open above.
+- **The remote-access tooling now ships** as `tosijs-tunnel` and `tosijs-deploy` bins
+  (tosijs-ui#27, and independently the review's ecosystem lens). Previously `SiteConfig`
+  exposed `preview`/`tunnel` as typed public API while the ~390 lines of
+  security-sensitive glue that implement them lived only in this repo — so every adopter
+  hand-copied them and owned the drift. They resolve the consumer's site config
+  (`--config=`, `TOSIJS_SITE_CONFIG`, then `./tosijs-site.config.ts` / `./site.config.ts`)
+  and deliberately do **not** walk up the tree: these commands deploy and expose a
+  workspace, so silently adopting a neighbour's config would publish the wrong project.
+- **Fix: the tunnel probed the wrong port**, so forwarding to a dead listener failed
+  silently with a 502 and a healthy-looking dev server (tosijs-ui#28). `ssh -R` can't
+  catch it — the *remote* bind succeeds, so `ExitOnForwardFailure` stays quiet; it's the
+  local end that connects to nothing. It now probes the port it actually forwards to and
+  **refuses to open**, naming the likely cause (including "your tosijs-ui predates the
+  tunnel listener").
+- **Tunnelled workspaces self-register too** (tosijs-ui#29). Static previews have
+  self-registered since beta.1, but a tunnelled host still needed a block hand-added to
+  the *shared* Caddyfile — so the one remaining manual edit was the **riskier** one: a
+  typo there breaks routing for every project on the box, which is exactly what the
+  fragment design set out to abolish. `tosijs-tunnel` now writes its own fragment with
+  the same validate-before-reload discipline, and the shared file names no hostnames at
+  all.
+- **`tunnel.remotePort` is allocated per project** instead of defaulting to 9787 for
+  everyone (tosijs-ui#29). Two projects taking the default collided, quietly and in the
+  direction that matters. The default is now derived from the project name — stable, and
+  nobody has to allocate it — while an explicit `remotePort` still wins.
+- **Fix: `chokidar` is no longer a hard runtime dependency of the build** (tosijs-ui#32).
+  `dev-server.js` had a top-level `import { watch } from 'chokidar'`, and a consumer's
+  `bin/site.ts` loads that module even in `--build` mode — so adopters hit
+  `Cannot find package 'chokidar'` on a plain build. It is now imported lazily inside the
+  watcher path and declared an **optional peer**, so building needs nothing extra and the
+  watching dev server explains itself if it is missing.
+- **Fix: `bun start` was in a rebuild loop** (measured at 899 restarts in ~40s), which made
+  the documented dev command unusable. The build stamp imported the *generated*
+  `src/version.ts`, putting it in `bun --watch`'s module graph while prebuild rewrote it every
+  build. The import is gone, and generated files are now written **only when the content
+  changes**, which makes the whole class of self-write loops impossible.
+
+
 ## 1.9.0-beta.2
 
 > Prerelease — install with `tosijs-ui@beta`. `latest` stays on 1.8.0.

package/README.md

@@ -16,15 +16,9 @@
 
 Copyright ©2023-2025 Tonio Loewald
 
-> ## ⚠️ Breaking change in 1.7.0 — `<tosi-code>` (ACE → CodeMirror 6)
->
-> **1.7.0 is a breaking release shipping under a minor version, deliberately.** `<tosi-code>`
-> moved from ACE to CodeMirror 6. `value`, `mode`, the `change` event, `disabled`, and
-> `undo`/`redo` are unchanged; the ACE-era **`theme`** and **`options`** props are **removed** with
-> no shim. Dark mode is now automatic (`body.darkmode`) and styling comes from `--code-bg` /
-> `--text-color`. The `2.0` name is reserved for the tjs-native tosijs port, so this ships as
-> 1.7.0 — **pin `tosijs-ui@1.6` to defer.** Full detail and rationale in
-[CHANGELOG.md](./CHANGELOG.md).
+> **Upgrading from an older version?** `<tosi-code>` changed editors in 1.7.0, and
+> 1.3.0 renamed everything from `xinjs-ui`. Both are covered in
+> [Migrating from older versions](https://ui.tosijs.net/migrating/) — new projects can skip it.
 
 ## the tosijs-ui library
 
@@ -34,35 +28,6 @@ for free rather than replace it.
 
 It works beautifully with other web-component libraries, such as [shoelace.style](https://shoelace.style/).
 
-## Migrating to v1.3.0
-
-v1.3.0 completes the rename from `xinjs-ui` to `tosijs-ui`. All custom element
-tags now use the `tosi-` prefix and all exports use `Tosi*`/`tosi*` names.
-
-### Breaking changes
-
-- **Custom element tags** have changed from `<xin-*>` to `<tosi-*>`.
-  For example: `<xin-select>` is now `<tosi-select>`, `<xin-icon>` is now
-  `<tosi-icon>`, `<xin-example>` is now `<tosi-example>`, etc.
-- **CSS selectors** targeting old tag names (e.g. `xin-select { ... }`) must
-  be updated.
-- **CSS custom properties** in component `styleSpec` objects retain `--xin-*`
-  fallbacks for backward compatibility, but new code should use `--tosi-*`.
-
-### Deprecated exports still work
-
-The old `xin*` JavaScript exports (`xinSelect`, `xinTabs`, `xinTable`, etc.)
-remain available and will continue to work. Most log a runtime deprecation
-warning; a few are silent aliases marked with JSDoc `@deprecated`. They will
-be removed in a future major version.
-
-### Migration checklist
-
-1. Search your HTML for `<xin-` and replace with `<tosi-`
-2. Search your CSS for `xin-` selectors and update to `tosi-`
-3. Search your JS/TS for `xinSelect`, `xinTabs`, etc. and switch to `tosiSelect`, `tosiTabs`, etc.
-4. Search for `--xin-` CSS variable overrides and switch to `--tosi-`
-
 ## Quick Start
 
 ### Using npm and a bundler

package/bin/deploy-preview.ts

@@ -0,0 +1,247 @@
+#!/usr/bin/env bun
+/*
+Deploy the built site to a preview host.
+
+  bun bin/deploy-preview.ts                 # DRY RUN — shows what would change
+  bun bin/deploy-preview.ts --go            # actually sync
+  bun bin/deploy-preview.ts --host=me@1.2.3.4 --path=/srv/preview/tosijs-ui --go
+
+Phase 1 of REMOTE-ACCESS-PLAN.md. The whole artifact is ~9MB / ~95 files and a typical
+doc change touches 3, so this is a copy, not a deployment pipeline — rsync has done
+delta transfer since 1996 and there is no protocol to invent.
+
+Two deliberate safety properties:
+
+  DRY RUN BY DEFAULT. This runs `rsync --delete`, which removes files on the remote
+  that aren't present locally. That is correct (the remote should mirror the build)
+  and it is destructive if pointed somewhere wrong, so the destructive form must be
+  typed on purpose. `--go` is the whole ceremony.
+
+  IT WARNS WHEN THE TREE IS DIRTY. `/version.json` deliberately carries no `dirty`
+  flag: it records the last COMMIT, and a build made from a dirty tree may not match
+  that commit. Rather than bake a permanently-wrong flag into a committed file, the
+  warning lives here — at the moment a human is deciding to publish something, and can
+  act on it. This is the other half of that decision (see build-stamp.ts).
+*/
+
+import { $ } from 'bun'
+import { existsSync } from 'fs'
+import { tmpdir } from 'os'
+import {
+  resolveSiteConfig,
+  isSafeRemotePath,
+  safeRemoteRoots,
+} from './resolve-site-config'
+
+const siteConfig = await resolveSiteConfig()
+
+const args = process.argv.slice(2)
+const flag = (name: string): string | undefined => {
+  const hit = args.find((a) => a.startsWith(`--${name}=`))
+  return hit ? hit.slice(name.length + 3) : undefined
+}
+const has = (name: string): boolean => args.includes(`--${name}`)
+
+const OUT = siteConfig.outputDir ?? 'docs'
+const PROJECT = siteConfig.name ?? 'site'
+const preview = (
+  siteConfig as { preview?: { host?: string; path?: string; url?: string } }
+).preview
+
+// Precedence: explicit flag > env > site config. The config is the "just works"
+// default; the flag exists so you can push a one-off somewhere else without editing
+// (and committing) a config file.
+const host = flag('host') ?? process.env.PREVIEW_HOST ?? preview?.host
+const remotePath =
+  flag('path') ??
+  process.env.PREVIEW_PATH ??
+  preview?.path ??
+  `/srv/preview/${PROJECT}`
+const publicUrl = flag('url') ?? preview?.url
+const go = has('go')
+
+if (!host) {
+  console.error(
+    `\nNo preview host.\n\n` +
+      `  Set one once in your site config:\n` +
+      `      preview: { host: 'user@example.com' }\n\n` +
+      `  ...or pass it per-run:\n` +
+      `      bun bin/deploy-preview.ts --host=user@example.com [--path=/srv/preview/x] [--go]\n` +
+      `      PREVIEW_HOST=user@example.com bun bin/deploy-preview.ts\n`
+  )
+  process.exit(1)
+}
+
+// Never let a typo'd path become `rsync --delete` against something important.
+// An allowlist of preview roots, not a depth heuristic — "two segments deep" admits
+// /usr/lib and /etc/caddy, and mirroring a doc-site build into either would empty it.
+if (!isSafeRemotePath(remotePath)) {
+  console.error(
+    `\n🛑 Refusing to deploy to "${remotePath}".\n\n` +
+      `   This runs \`rsync --delete\`, which mirrors — anything already at the target\n` +
+      `   that isn't in the build gets removed. Targets must live under one of:\n` +
+      safeRemoteRoots()
+        .map((r) => `     ${r}/…`)
+        .join('\n') +
+      `\n`
+  )
+  process.exit(1)
+}
+
+if (!existsSync(OUT) || !existsSync(`${OUT}/index.html`)) {
+  console.error(
+    `\n🛑 No build at ./${OUT} (or it has no index.html). Run \`bun run build\` first.\n`
+  )
+  process.exit(1)
+}
+
+// What are we about to publish? /version.json is the build's identity; printing it
+// here closes the loop the stamp exists for — you see the commit BEFORE it ships,
+// not only when someone asks "what am I looking at".
+let stamp = '(no version.json — build with a current tosijs-ui)'
+try {
+  const v = JSON.parse(await Bun.file(`${OUT}/version.json`).text())
+  stamp = `${v.commit ?? '?'} — ${v.commitTime ?? '?'} (generator ${
+    v.generator
+  })`
+} catch {
+  // best effort; never block a deploy on the stamp
+}
+
+const dirty = (await $`git status --porcelain`.nothrow().quiet().text()).trim()
+
+console.log(`\n📦 ${PROJECT} → ${host}:${remotePath}`)
+console.log(`   building from: ${stamp}`)
+
+if (dirty) {
+  const n = dirty.split('\n').length
+  console.warn(
+    `\n⚠️  Working tree has ${n} uncommitted change${n === 1 ? '' : 's'}.\n` +
+      `    /version.json records the last COMMIT, so the preview will claim a commit\n` +
+      `    that does not describe what you are about to publish. Commit first if the\n` +
+      `    identity matters (it usually does when someone else is reviewing).\n`
+  )
+}
+
+// --delete so the remote mirrors the build exactly (stale pages must not linger);
+// -z compresses; --checksum is NOT used — mtime+size is enough and much faster.
+const rsyncArgs = [
+  '-az',
+  '--delete',
+  '--human-readable',
+  ...(go ? [] : ['--dry-run']),
+  '--itemize-changes',
+  `${OUT}/`,
+  `${host}:${remotePath}/`,
+]
+
+if (!go) console.log(`\n🔍 DRY RUN — nothing will change. Add --go to sync.\n`)
+
+const result = await $`rsync ${rsyncArgs}`.nothrow()
+if (result.exitCode !== 0) {
+  console.error(`\n🛑 rsync failed (exit ${result.exitCode}).`)
+  process.exit(1)
+}
+
+/*
+Self-registration.
+
+When `preview.url` is set, this project publishes its own Caddy fragment naming the
+hostname and the directory it serves. The central Caddyfile glob-imports
+/srv/preview/_sites/*.caddy, so a new project needs no edit to any shared file and no
+DNS change — deploying IS registering.
+
+The fragment is the single source of truth for hostname→directory: the index page
+reads these same files, so the listing cannot drift from the router. (It did, once:
+the index derived hostnames from directory names and linked
+tosijs-ui.dev.tosijs.net at a site actually served from ui.dev.tosijs.net.)
+
+Validate before reloading, and do not reload if invalid. One malformed fragment would
+otherwise fail the reload for EVERY project on the box — so a bad config leaves the
+previous good one serving, exactly as a failed build leaves the last good site up.
+*/
+async function registerSite(): Promise<void> {
+  if (!publicUrl) return
+  let hostname: string
+  try {
+    hostname = new URL(publicUrl).hostname
+  } catch {
+    console.warn(
+      `⚠️  preview.url is not a URL (${publicUrl}) — skipping registration.`
+    )
+    return
+  }
+
+  // Staged through a local temp file and scp'd: Bun's shell has no herestring, and
+  // building a remote `cat > file` out of an interpolated string is how you end up
+  // with a quoting bug that writes something surprising as root.
+  const local = `${tmpdir()}/${PROJECT}.caddy`
+  await Bun.write(
+    local,
+    `# Generated by \`bun run deploy\` for ${PROJECT}. Do not hand-edit.\n` +
+      `${hostname} {\n\troot * ${remotePath}\n\timport preview_site\n}\n`
+  )
+
+  const mk = await $`ssh ${host} mkdir -p /srv/preview/_sites`.nothrow().quiet()
+  const put =
+    await $`scp -q ${local} ${`${host}:/srv/preview/_sites/${PROJECT}.caddy`}`
+      .nothrow()
+      .quiet()
+  if (mk.exitCode !== 0 || put.exitCode !== 0) {
+    console.warn(
+      `⚠️  could not register ${hostname} — site deployed, routing unchanged.`
+    )
+    return
+  }
+
+  // Validate with the SAME environment systemd gives Caddy. The basicauth hash comes
+  // from an EnvironmentFile (kept out of this public repo), and a bare `caddy validate`
+  // does not load it — so {env.PREVIEW_HASH} resolves empty and validation fails with
+  // "username and password are required" on a config that is actually fine. That would
+  // fail CLOSED forever: every deploy would decline to reload and routing would freeze.
+  const check =
+    await $`ssh ${host} ${'set -a; . /etc/caddy/preview.env 2>/dev/null; set +a; caddy validate --config /etc/caddy/Caddyfile'}`
+      .nothrow()
+      .quiet()
+  if (check.exitCode !== 0) {
+    // Leave the fragment so the error is inspectable, but do NOT reload: one bad
+    // fragment would fail the reload for EVERY project on the box.
+    console.error(
+      `\n🛑 Caddy config invalid after registering ${hostname} — NOT reloading.\n` +
+        `   The previous config keeps serving. Fix or remove\n` +
+        `   /srv/preview/_sites/${PROJECT}.caddy on the host.\n` +
+        (check.stderr.toString() || check.stdout.toString())
+          .trim()
+          .split('\n')
+          .slice(-4)
+          .join('\n')
+    )
+    return
+  }
+  await $`ssh ${host} systemctl reload caddy`.nothrow().quiet()
+  console.log(`   registered ${hostname} → ${remotePath}`)
+}
+
+/** 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`
+  const put = await $`scp -q ${'deploy/build-index.sh'} ${`${host}:${remote}`}`
+    .nothrow()
+    .quiet()
+  if (put.exitCode !== 0) return
+  const run = await $`ssh ${host} bash ${remote}`.nothrow().quiet()
+  await $`ssh ${host} rm -f ${remote}`.nothrow().quiet()
+  const out = run.stdout.toString().trim()
+  if (out) console.log(`   ${out}`)
+}
+
+if (go) {
+  await registerSite()
+  await refreshIndex()
+}
+
+console.log(
+  go
+    ? `\n✅ Deployed. ${stamp}` + (publicUrl ? `\n   ${publicUrl}\n` : '\n')
+    : `\nDry run complete — re-run with --go to apply.\n`
+)

package/bin/docs.ts

@@ -1,3 +1,4 @@
+#!/usr/bin/env bun
 // Back-compat shim. The doc-extraction implementation now lives in the
 // importable doc-site system at src/doc-system/site/docs.ts (shipped as
 // `tosijs-ui/site`). This path is kept (package.json#files lists /bin/docs.ts)

package/bin/make-icon-data.js

@@ -249,16 +249,32 @@ function findIcons(dirs, ignore = []) {
         if (dir.includes('color')) {
           classes.push('color')
         } else {
-          // If not a color icon, remove fill/stroke styles
-          svgSource = svgSource.replace(/(fill|stroke)(-\w+)?:[^;]+;?/g, '')
+          /*
+          Strip fill/stroke COLOUR so a monochrome icon can be tinted — but keep
+          `fill-rule` and `clip-rule`, which are fill TOPOLOGY and take no part in
+          tinting.
+
+          Removing them reverts a compound path to `nonzero`, so an icon that punches
+          holes with `evenodd` — a keyboard drawn as one path, body with key-shaped
+          holes — renders the holes SOLID. The workaround was to move such icons into
+          `color/` with `fill:currentColor`, which keeps them themeable but opts them
+          out of the tinting path for an unrelated reason (tosijs-ui#30).
+          */
+          svgSource = svgSource.replace(
+            /(fill|stroke)(?!-rule)(-\w+)?:[^;]+;?/g,
+            ''
+          )
         }
+        // Same rule as above, and the reason it took two goes to fix: `fill-rule` was
+        // stripped in THREE places, not one. `-rule` is topology, never colour, so it
+        // survives every strip. `clip-rule` likewise.
         if (dir.includes('stroked')) {
           classes.push('stroked')
-          svgSource = svgSource.replace(/(fill)(-\w+)?:[^;]+;?/g, '')
+          svgSource = svgSource.replace(/(fill)(?!-rule)(-\w+)?:[^;]+;?/g, '')
         }
         if (dir.includes('filled')) {
           classes.push('filled')
-          svgSource = svgSource.replace(/(stroke)(-\w+)?:[^;]+;?/g, '')
+          svgSource = svgSource.replace(/(stroke)(?!-rule)(-\w+)?:[^;]+;?/g, '')
         }
         if (classes.length) {
           svgSource = svgSource.replace(

package/bin/resolve-site-config.ts

@@ -0,0 +1,126 @@
+/*
+Find and load the CONSUMER's site config.
+
+`bin/tunnel.ts` and `bin/deploy-preview.ts` ship as package bins (`tosijs-tunnel`,
+`tosijs-deploy`), so they run from an adopter's repo, not this one. They used to
+`import siteConfig from '../tosijs-site.config'` — a path that only resolves inside
+tosijs-ui, which is exactly why every adopter had to hand-copy ~390 lines of
+security-sensitive glue and then own the drift forever (tosijs-ui#27).
+
+Resolution order, first hit wins:
+  1. `--config=<path>`            explicit beats clever
+  2. `TOSIJS_SITE_CONFIG`         for CI and one-offs
+  3. ./tosijs-site.config.ts      what this repo and its siblings use
+  4. ./site.config.ts             what doc-site-system.md's quick-start suggests
+  5. ./tosijs-site.config.js / ./site.config.js
+
+Deliberately does NOT walk up the tree. These commands deploy and expose a workspace;
+silently picking up a parent directory's config would mean publishing the wrong project,
+and "it found something" is not the same as "it found yours".
+*/
+
+import { existsSync } from 'fs'
+import * as path from 'path'
+
+export interface PreviewConfig {
+  host?: string
+  path?: string
+  url?: string
+  tunnel?: {
+    remotePort?: number
+    localPort?: number
+    url?: string
+    requireToken?: boolean
+  }
+}
+
+export interface ResolvedSiteConfig {
+  name?: string
+  outputDir?: string
+  port?: number
+  preview?: PreviewConfig
+  /** absolute path of the file this came from, for error messages */
+  __configPath: string
+}
+
+const CANDIDATES = [
+  'tosijs-site.config.ts',
+  'site.config.ts',
+  'tosijs-site.config.js',
+  'site.config.js',
+]
+
+/** Where would we look? Exported so a failure message can list it. */
+export function candidatePaths(cwd = process.cwd()): string[] {
+  return CANDIDATES.map((c) => path.resolve(cwd, c))
+}
+
+export async function resolveSiteConfig(
+  argv: string[] = process.argv.slice(2),
+  cwd = process.cwd()
+): Promise<ResolvedSiteConfig> {
+  const flag = argv.find((a) => a.startsWith('--config='))?.slice(9)
+  const explicit = flag ?? process.env.TOSIJS_SITE_CONFIG
+
+  let file: string | undefined
+  if (explicit) {
+    file = path.resolve(cwd, explicit)
+    if (!existsSync(file)) {
+      console.error(`\n🛑 No site config at ${file}\n`)
+      process.exit(1)
+    }
+  } else {
+    file = candidatePaths(cwd).find((p) => existsSync(p))
+  }
+
+  if (!file) {
+    console.error(
+      `\n🛑 No site config found in ${cwd}\n\n` +
+        `   Looked for:\n` +
+        CANDIDATES.map((c) => `     ${c}`).join('\n') +
+        `\n\n   Pass one explicitly with --config=<path>, or set TOSIJS_SITE_CONFIG.\n` +
+        `   (Parent directories are deliberately NOT searched — these commands deploy\n` +
+        `   and expose a workspace, and picking up a neighbour's config silently would\n` +
+        `   publish the wrong project.)\n`
+    )
+    process.exit(1)
+  }
+
+  try {
+    const mod = await import(file)
+    const cfg = mod.default ?? mod
+    return { ...cfg, __configPath: file }
+  } catch (e) {
+    console.error(`\n🛑 Could not load ${file}:\n   ${String(e)}\n`)
+    process.exit(1)
+  }
+}
+
+/*
+Is this a safe target for `rsync --delete`?
+
+The original guard was "absolute and at least two segments deep", which happily admits
+/usr/lib, /var/www, /etc/caddy and /home/deploy — all of which would be MIRRORED to a
+doc-site build, i.e. emptied of everything else. A depth heuristic cannot express
+"somewhere set aside for previews"; an allowlist of roots can.
+
+Exported and pure so it is testable — the previous version was top-level script code
+inside the deploy, which is exactly why nothing pinned it.
+*/
+const SAFE_ROOTS = [
+  '/srv/preview',
+  '/srv/www',
+  '/var/www/preview',
+  '/opt/preview',
+]
+
+export function isSafeRemotePath(p: string): boolean {
+  if (!p.startsWith('/')) return false
+  // No traversal, no trailing weirdness that could re-root the path.
+  if (p.includes('..')) return false
+  const norm = p.replace(/\/+$/, '')
+  if (norm.split('/').filter(Boolean).length < 2) return false
+  return SAFE_ROOTS.some((root) => norm === root || norm.startsWith(root + '/'))
+}
+
+export const safeRemoteRoots = (): string[] => [...SAFE_ROOTS]