tosijs-ui 1.16.34 → 1.16.36

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # Changelog
 
+## 1.16.36
+
+One additive site option. Nothing changes for a site that does not set it.
+
+- **A page can be served at a second path (#3513).** `aliases: { readme: '' }` in the site
+  config also writes the root page to `/readme/`, with its stylesheet, bundle and `docs.json`
+  references worked out for that depth, and the browser opens it as the README. Before this a
+  host rewrite was the only way, and it served the page one level down with every relative
+  reference 404ing, so the page rendered but never hydrated. An alias page's canonical link
+  names the page's own path, aliases stay out of the sitemap and the nav, and relative images
+  and links in the page are rewritten to reach the same files. An alias is one lowercase path
+  segment with no dot; the build fails on one that is not, that takes a page's own path or a
+  static folder's, or that names no page.
+
+## 1.16.35
+
+Board follow-ups from 1.16.32 and 1.16.33, plus one tunnel feature. Nothing to change in an
+adopter's product. **Tunnel users:** a plain `--link` / `--share` now keeps its browser in
+across a dev-server restart for 24 hours, and the dev server writes a signing secret to
+`.tosijs-dev/` in your project (it gitignores itself). **Box operators:** re-run
+`tosijs-caddy-install --go` to tighten the access-log permissions; the dry run no longer
+prints old keys.
+
+### Tunnel
+
+- **A link survives a restart (#3416).** Redeeming a plain `--link` or `--share` link also
+  sets a signed pass (`__Host-tosi_link_pass`: kind, workspace host, expiry 24 hours after
+  redemption, HMAC-SHA256 with a per-project secret). After a restart, the next page load or
+  same-origin request trades it for a fresh session of the same kind, the way a `--global`
+  key is traded. A share link's pass stays read-only, a pass works only on the host it was
+  issued for, and a session it mints never outlives it.
+- **What that costs.** Until now nothing about a link session outlived the process, so a
+  stolen session cookie died with the server. A stolen pass now works for the rest of its 24
+  hours, across restarts. To revoke every pass at once, delete
+  `.tosijs-dev/session-secret`. The secret is created 0600 in a 0700 folder. The dev server
+  refuses to start if it sits inside the output folder; if group or others have any access to
+  it, links still open but stop surviving restarts, and the console says why. A filesystem that keeps no modes (a Windows
+  drive under WSL, FAT) cannot hold the secret: plain links there end on restart, as before.
+  Revoking a device does not end a link pass.
+- **The "dev server restarted" page** now says a link keeps its browser in for 24 hours,
+  instead of claiming sessions are never written to disk.
+
+### Preview box
+
+- **The dry run no longer prints old keys (#3502).** `tosijs-caddy-install` redacted only the
+  current keys from preview.env, but the diff's removed lines come from the live Caddyfile, so
+  after a rotation the previous `PREVIEW_TOKEN` / `PREVIEW_EDIT_TOKEN` printed in clear. Every
+  value in a key position (`tosi_preview=`, `tosi_edit=`, `query t=`) on either side is now
+  blanked wherever it appears, comments included, and so is the refusal that names leftover
+  placeholders.
+- **Access logs.** `--go` takes group and other access off the existing preview access logs
+  (`/var/log/caddy/preview*.log*`, symlinks skipped), which record short-link codes. A log
+  shipper that reads them through group membership loses access; give it root or the caddy
+  user. Caddy 2.6 has no log mode, so a log Caddy creates after the install gets Caddy's own
+  mode; doc-site-system.md says exactly what is covered.
+- **Paths with a space.** The installer found neither its template nor the gate page when the
+  package lived under a path with a space (`new URL().pathname` kept `%20`).
+- **Gate page.** The installer reads `deploy/gate-page.html` only when the template names
+  `__GATE_PAGE__`, and refuses a missing one with a message instead of a stack trace.
+- **Custom templates.** doc-site-system.md now says a custom `--template` keeps its old gate
+  page and never serves short links, and lists the lines to copy from `deploy/Caddyfile`.
+
+### Components
+
+- **`<tosi-table>` with no data.** `columns` returned a new `[]` on every read, and
+  `table.value = { ...table.value, array }` stored that `[]` as the columns, fixing the table
+  at zero columns for the data that followed. The empty list is now one per table, and handing
+  it back means "infer".
+- **`<tosi-palette>`.** An unknown `trigger` value now behaves exactly as `field` (before, it
+  showed the full field but never compacted), and warns once per value, naming it and the
+  fallback. Setting `value` from code was ignored once
+  the query field existed; it now updates the field, and searches again if the palette is
+  open.
+- **Doc browser.** Choosing a palette section result while the source editor held unsaved
+  edits, and dismissing the confirm, still rewrote the URL to the target's `#anchor` and
+  scrolled. Now nothing moves when navigation is refused.
+- **`<tosi-crud>` docs** describe `close()`, the Close button, the one-column narrow layout and
+  `TosiCrud.NARROW_WIDTH`.
+
 ## 1.16.34
 
 Spinning icons keep spinning while the page is busy, which is the only time a loader is on

package/bin/caddy-install.ts

@@ -36,6 +36,7 @@ Three deliberate properties:
 */
 
 import { existsSync, readFileSync } from 'fs'
+import { fileURLToPath } from 'url'
 import {
   embedGatePage,
   parseArgv,
@@ -82,8 +83,14 @@ The template ships inside the package, so the default is resolved relative to TH
 rather than to the cwd — an adopter runs the bin from their own project, where `deploy/` is
 their business and not ours.
 */
+/*
+`fileURLToPath`, not `new URL(...).pathname`: the latter keeps percent-encoding, so a package
+installed under a path with a space (`/Users/me/My Projects/…`) resolved to `My%20Projects` and
+the shipped template was reported missing.
+*/
 const templatePath =
-  flag('template') ?? new URL('../deploy/Caddyfile', import.meta.url).pathname
+  flag('template') ??
+  fileURLToPath(new URL('../deploy/Caddyfile', import.meta.url))
 
 if (!existsSync(templatePath)) {
   console.error(
@@ -97,15 +104,26 @@ if (!existsSync(templatePath)) {
 /*
 `__GATE_PAGE__` is the page a browser without the preview cookie sees (deploy/gate-page.html,
 with its box for a link or a code). It is not a secret, so it is embedded here rather than on the
-box. A template of your own that names it gets the shipped page.
+box. A template of your own that names it gets the shipped page; one that does not never needs
+the file, so it is read only when named.
 */
-const template = embedGatePage(
-  readFileSync(templatePath, 'utf8'),
-  readFileSync(
-    new URL('../deploy/gate-page.html', import.meta.url).pathname,
-    'utf8'
+const rawTemplate = readFileSync(templatePath, 'utf8')
+let template = rawTemplate
+if (rawTemplate.includes('__GATE_PAGE__')) {
+  const gatePagePath = fileURLToPath(
+    new URL('../deploy/gate-page.html', import.meta.url)
   )
-)
+  if (!existsSync(gatePagePath)) {
+    console.error(
+      `\nNo gate page at ${gatePagePath}\n\n` +
+        `  ${templatePath} names __GATE_PAGE__, which is filled from that file.\n` +
+        `  The package ships it at node_modules/tosijs-ui/deploy/gate-page.html;\n` +
+        `  reinstall the package, or drop __GATE_PAGE__ from your template.\n`
+    )
+    process.exit(1)
+  }
+  template = embedGatePage(rawTemplate, readFileSync(gatePagePath, 'utf8'))
+}
 
 // The template is delivered inside a quoted heredoc, so it is copied verbatim with no shell
 // expansion. A template containing the delimiter would truncate the file silently — refuse
@@ -154,6 +172,40 @@ elif [ "$PREVIEW_EDIT_TOKEN" = "$PREVIEW_TOKEN" ]; then
   exit 1
 fi
 
+# Everything this script prints from a Caddyfile goes through \`redact <files>\`. Redacting only
+# the CURRENT keys was not enough: a dry-run diff's removed lines come from the live file, which
+# after a rotation holds the PREVIOUS keys (board #3502). So the values are harvested from every
+# position the template puts a key, in the files being shown: the cookie names in matchers and
+# Set-Cookie (\`tosi_preview=\`, \`tosi_edit=\`) and the link matchers (\`query t=\`). Each value,
+# and each current key, is then blanked wherever it appears, comments included (the installer's
+# substitution reaches the comments that name the placeholders), longest first so one key cannot
+# leave part of another showing. Finally anything still in a key position is blanked by shape.
+# Here the values travel in the environment, not argv, where \`ps\` would show them. (The
+# install's own sed below still passes the keys in argv, for the moment it runs.)
+KEY_POSITION='(tosi_(preview|edit)=|query[[:space:]]+t=)'
+KEY_VALUE='[^[:space:];"()|*]+'
+key_values() {
+  { grep -ohE "$KEY_POSITION$KEY_VALUE" "$@" || [ $? -eq 1 ]; } | sed -E "s/^$KEY_POSITION//"
+  printf '%s\\n' "$PREVIEW_TOKEN" "$PREVIEW_EDIT_TOKEN"
+}
+redact() {
+  REDACT_KEYS="$(key_values "$@" | sort -u | awk 'length { print length, $0 }' | sort -rn | cut -d' ' -f2-)" \\
+    awk 'BEGIN { n = split(ENVIRON["REDACT_KEYS"], key, "\\n") }
+      {
+        line = $0
+        for (i = 1; i <= n; i++) {
+          out = ""
+          while (key[i] != "" && (at = index(line, key[i])) > 0) {
+            out = out substr(line, 1, at - 1) "***REDACTED***"
+            line = substr(line, at + length(key[i]))
+          }
+          line = out line
+        }
+        print line
+      }' \\
+    | sed -E "s/$KEY_POSITION$KEY_VALUE/\\1***REDACTED***/g"
+}
+
 sed -e "s|__PREVIEW_TOKEN__|$PREVIEW_TOKEN|g" \\
     -e "s|__PREVIEW_EDIT_TOKEN__|$PREVIEW_EDIT_TOKEN|g" \\
     -e "s|{{ACME_EMAIL}}|$ACME_EMAIL|g" \\
@@ -162,7 +214,7 @@ sed -e "s|__PREVIEW_TOKEN__|$PREVIEW_TOKEN|g" \\
 
 if grep -qE '\\{\\{|__PREVIEW_(EDIT_)?TOKEN__' /etc/caddy/Caddyfile.new; then
   echo "Unsubstituted placeholders remain — refusing to install:" >&2
-  grep -nE '\\{\\{|__PREVIEW_(EDIT_)?TOKEN__' /etc/caddy/Caddyfile.new >&2
+  grep -nE '\\{\\{|__PREVIEW_(EDIT_)?TOKEN__' /etc/caddy/Caddyfile.new | redact /etc/caddy/Caddyfile.new >&2
   rm -f /etc/caddy/Caddyfile.new
   exit 1
 fi
@@ -195,6 +247,14 @@ if [ "${go ? '1' : '0'}" = "1" ]; then
   else
     chmod 600 /etc/caddy/Caddyfile.new
   fi
+  # The access log records short-link codes as paths, unredacted (a code is spent or expired within
+  # five minutes). Caddy 2.6 has no log \`mode\`, so take group and other access off the preview logs
+  # that exist; Caddy keeps owning them. \`-type f\` skips symlinks, so a link planted in a directory
+  # Caddy can write cannot point this chmod at another file. Done before the swap, so a failure
+  # here leaves the running config untouched, like every other refusal.
+  if [ -d /var/log/caddy ]; then
+    find /var/log/caddy -maxdepth 1 -type f -name 'preview*.log*' -exec chmod go-rwx {} +
+  fi
   mv /etc/caddy/Caddyfile.new /etc/caddy/Caddyfile
   # A stopped Caddy cannot reload. Start it instead, or a box left down by the bug above could
   # never be repaired by re-running this.
@@ -222,11 +282,11 @@ if [ "${go ? '1' : '0'}" = "1" ]; then
   echo "Installed /etc/caddy/Caddyfile (caddy: $verb)."
   echo "Previous config saved as /etc/caddy/Caddyfile.bak"
 else
-  echo "--- would change /etc/caddy/Caddyfile (token redacted) ---"
+  echo "--- would change /etc/caddy/Caddyfile (keys redacted) ---"
   if [ -f /etc/caddy/Caddyfile ]; then
-    diff -u /etc/caddy/Caddyfile /etc/caddy/Caddyfile.new \\
-      | sed -e "s|$PREVIEW_TOKEN|***REDACTED***|g" \\
-            -e "s|$PREVIEW_EDIT_TOKEN|***REDACTED***|g" || true
+    # diff exits 1 when the files differ, which is the expected case; 2 is a real failure.
+    { diff -u /etc/caddy/Caddyfile /etc/caddy/Caddyfile.new || [ $? -eq 1 ]; } \\
+      | redact /etc/caddy/Caddyfile /etc/caddy/Caddyfile.new
   else
     echo "(no existing /etc/caddy/Caddyfile — this would create it)"
   fi

package/bin/tunnel-links.ts

@@ -0,0 +1,208 @@
+/*
+The links `tosijs-tunnel` prints: single-use global links (`--link --global`, and the ones
+printed at tunnel start), the device record behind each edit pass, and the short link the box
+can answer for a code.
+
+Split out of bin/tunnel.ts so it can be tested without a box (board #3416 item 2, #3506): the
+bin is a script that runs on import, so everything that reaches the network is passed in here
+(`ssh`, `fetchText`, `askForLink`) and the bin wires the real ones.
+*/
+
+import { $ } from 'bun'
+import {
+  deviceRegistryLine,
+  groupCode,
+  planGlobalLinks,
+  shortCodeScript,
+  type BoxKeys,
+} from './resolve-site-config.ts'
+import type { GlobalKeys } from '../dist/doc-system/site/dev-auth.js'
+
+export type LinkKind = 'edit' | 'view'
+
+export interface DevLinkAnswer {
+  url?: string
+  device?: string
+  error?: string
+}
+
+export interface GlobalLink {
+  kind: LinkKind
+  url: string
+  short?: string
+}
+
+export interface TunnelLinkDeps {
+  /** The preview box, as ssh names it. */
+  host: string
+  /** The preview root on the box (`/srv/preview`), where `_devices/` and `_codes/` live. */
+  root: string
+  projectName: string
+  /** The dev server's TLS port, for messages. */
+  localPort: number
+  /** `--label=`, naming the device a `--global` edit link is for. */
+  label?: string
+  /** True for `--link`; false for the links printed at tunnel start. */
+  onRequest: boolean
+  /** This machine's global keys, as `resolveGlobalKeys` read them. */
+  local: { keys: GlobalKeys; problems: string[] }
+  /** The box's domain and key fingerprints (`previewBoxKeys`). */
+  boxKeys: () => Promise<BoxKeys>
+  /** Run one command on the box; only the exit code is used. */
+  ssh: (command: string) => Promise<{ exitCode: number }>
+  /** Ask the dev server (loopback only) for a link; `query` selects the kind. */
+  askForLink: (query: string) => Promise<DevLinkAnswer>
+  /** GET a URL and return its body, or '' for anything but a 2xx. Never throws. */
+  fetchText: (url: string) => Promise<string>
+}
+
+/*
+SHORT LINKS (board #3504): record which workspace a code belongs to, so `https://<domain>/<CODE>`
+(or the code typed into the box on the gate and root pages) finds it. See shortCodeScript.
+Returns the short link, or the reason there is none (the full link still works either way).
+*/
+export async function registerShortCode(
+  deps: Pick<TunnelLinkDeps, 'host' | 'root' | 'ssh' | 'fetchText'>,
+  url: string,
+  domain: string
+): Promise<{ short?: string; problem?: string }> {
+  const code = new URL(url).searchParams.get('t') ?? ''
+  const script = shortCodeScript(deps.root, code, url)
+  if (!script) return { problem: `${url} is not a link the box can shorten` }
+  const run = await deps.ssh(script)
+  if (run.exitCode !== 0)
+    return { problem: `could not record it on ${deps.host}` }
+  // Read it back through Caddy: a box whose Caddyfile predates short links answers with its
+  // gate, and a short link printed over that would lead nowhere.
+  const served = await deps.fetchText(`https://${domain}/_codes/${code}`)
+  if (served.trim() !== url)
+    return {
+      problem: `the box's Caddyfile does not serve short links yet: run \`tosijs-caddy-install --go\``,
+    }
+  return { short: `https://${domain}/${code}` }
+}
+
+/** Append one line to the box's device registry. False if it could not be recorded. */
+export async function registerDevice(
+  deps: Pick<TunnelLinkDeps, 'root' | 'ssh'>,
+  device: { id: string; project: string; label: string },
+  issued = new Date()
+): Promise<boolean> {
+  const line = deviceRegistryLine({ ...device, issued })
+  if (!line) return false
+  const run = await deps.ssh(
+    `mkdir -p ${deps.root}/_devices && printf '%s\\n' '${line}' >> ${deps.root}/_devices/registry.tsv`
+  )
+  return run.exitCode === 0
+}
+
+/*
+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.
+*/
+export async function globalLinks(
+  deps: TunnelLinkDeps,
+  kinds: LinkKind[] = ['edit', 'view']
+): Promise<{ links: GlobalLink[]; notes: string[] }> {
+  const { local, label } = deps
+  const box: BoxKeys =
+    local.keys.edit || local.keys.view ? await deps.boxKeys() : {}
+  const plan = planGlobalLinks(local, box)
+  const links: GlobalLink[] = []
+  for (const kind of plan.kinds.filter((k) => kinds.includes(k))) {
+    const answer = await deps.askForLink(
+      `?global=${kind}&domain=${encodeURIComponent(plan.domain!)}${
+        label ? `&label=${encodeURIComponent(label)}` : ''
+      }`
+    )
+    if (answer.url && answer.device) {
+      // Recorded before the link is shown, so every pass in a browser is on the box's list.
+      const recorded = await registerDevice(deps, {
+        id: answer.device,
+        project: deps.projectName,
+        // The links printed at start are recorded too, used or not; say which they were.
+        label: label ?? (deps.onRequest ? '' : 'printed at tunnel start'),
+      })
+      if (!recorded) {
+        plan.notes.push(
+          `could not record device ${answer.device} on ${deps.host}, so no ${kind} link: it could not be listed or revoked`
+        )
+        continue
+      }
+    }
+    if (answer.url) {
+      const { short, problem } = await registerShortCode(
+        deps,
+        answer.url,
+        plan.domain!
+      )
+      if (!short)
+        plan.notes.push(`no short link (${problem}); the full link still works`)
+      links.push({ kind, url: answer.url, short })
+    } else
+      plan.notes.push(
+        answer.error ??
+          `the dev server on :${deps.localPort} did not answer, so no ${kind} link: start it (\`bun start\`), then \`tosijs-tunnel --link\``
+      )
+  }
+  return { links, notes: plan.notes }
+}
+
+/** What the tunnel prints under its public URL at start: the links, then the notes. */
+export function startLinkLines(start: {
+  links: GlobalLink[]
+  notes: string[]
+}): string[] {
+  const lines: string[] = []
+  if (start.links.length) {
+    lines.push(
+      `\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, short } of start.links) {
+      const code = new URL(url).searchParams.get('t') ?? ''
+      lines.push(
+        `   ${kind}: ${url}${kind === 'view' ? '  (read-only)' : ''}` +
+          (short ? `\n         ${short}   code ${groupCode(code)}` : '')
+      )
+    }
+  }
+  for (const note of start.notes) lines.push(`   note: ${note}`)
+  return lines
+}
+
+/** The real `askForLink`: the dev server's `/__devlink`, on loopback, over its TLS port. */
+export async function askDevServer(
+  localPort: number,
+  query: string
+): Promise<DevLinkAnswer> {
+  const res =
+    await $`curl -sk --max-time 5 https://localhost:${localPort}/__devlink${query}`
+      .nothrow()
+      .quiet()
+  try {
+    return JSON.parse(res.stdout.toString())
+  } catch {
+    return {}
+  }
+}
+
+/** The real `ssh`: never prompts or hangs, since a link is waiting on it. */
+export async function sshTo(
+  host: string,
+  command: string
+): Promise<{ exitCode: number }> {
+  return $`ssh -o BatchMode=yes -o ConnectTimeout=10 ${host} ${command}`
+    .nothrow()
+    .quiet()
+}
+
+/** The real `fetchText`. */
+export async function fetchText(url: string): Promise<string> {
+  return fetch(url, { signal: AbortSignal.timeout(5000) })
+    .then((res) => (res.ok ? res.text() : ''))
+    .catch(() => '')
+}

package/bin/tunnel.ts

@@ -32,7 +32,14 @@ always requires a session.
 
 import { $ } from 'bun'
 import {
-  planGlobalLinks,
+  askDevServer,
+  fetchText,
+  globalLinks as globalLinksFor,
+  sshTo,
+  startLinkLines,
+  type LinkKind,
+} from './tunnel-links.ts'
+import {
   previewBoxKeys,
   previewRootFor,
   readLocalSecret,
@@ -44,9 +51,7 @@ import {
   resolveSiteConfig,
   resolveTunnelLocalPort,
   parseArgv,
-  deviceRegistryLine,
   groupCode,
-  shortCodeScript,
   parseDeviceListing,
   DEVICE_LISTING_SEPARATOR,
   DEVICE_ID_PATTERN,
@@ -148,84 +153,11 @@ 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; device?: 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.
+The link logic lives in tunnel-links.ts, with everything that reaches the network passed in, so
+it can be tested without a box. These are the real ones.
 */
-async function globalLinks(
-  kinds: ('edit' | 'view')[] = ['edit', 'view']
-): Promise<{
-  links: { kind: 'edit' | 'view'; url: string; short?: 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; short?: string }[] = []
-  for (const kind of plan.kinds.filter((k) => kinds.includes(k))) {
-    const label = flag('label')
-    const answer = await askForLink(
-      `?global=${kind}&domain=${encodeURIComponent(plan.domain!)}${
-        label ? `&label=${encodeURIComponent(label)}` : ''
-      }`
-    )
-    if (answer.url && answer.device) {
-      // Recorded before the link is shown, so every pass in a browser is on the box's list.
-      const recorded = await registerDevice({
-        id: answer.device,
-        project: projectName,
-        // The links printed at start are recorded too, used or not; say which they were.
-        label: label ?? (has('link') ? '' : 'printed at tunnel start'),
-      })
-      if (!recorded) {
-        plan.notes.push(
-          `could not record device ${answer.device} on ${host}, so no ${kind} link: it could not be listed or revoked`
-        )
-        continue
-      }
-    }
-    if (answer.url) {
-      const short = await registerShortCode(answer.url, plan.domain!)
-      if (!short)
-        plan.notes.push(
-          `no short link (${
-            shortLinkProblem || `could not record it on ${host}`
-          }); the full link still works`
-        )
-      links.push({ kind, url: answer.url, short })
-    } 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
+const askForLink = (query: string) => askDevServer(localPort, query)
 
 /*
 DEVICES (board #3416). Each --global edit link is a pass for one device. The box keeps the
@@ -239,55 +171,30 @@ const devicesRoot = () =>
     preview?.caddySitesDir
   )
 
-async function registerDevice(device: {
-  id: string
-  project: string
-  label: string
-}): Promise<boolean> {
-  const line = deviceRegistryLine({ ...device, issued: new Date() })
-  if (!line) return false
-  const root = devicesRoot()
-  const run =
-    await $`ssh -o BatchMode=yes -o ConnectTimeout=10 ${host!} ${`mkdir -p ${root}/_devices && printf '%s\\n' '${line}' >> ${root}/_devices/registry.tsv`}`
-      .nothrow()
-      .quiet()
-  return run.exitCode === 0
-}
-
-/*
-SHORT LINKS (board #3504): record which workspace a code belongs to, so `https://<domain>/<CODE>`
-(or the code typed into the box on the gate and root pages) finds it. See shortCodeScript.
-Returns the short link, or undefined if it could not be recorded.
-*/
-let shortLinkProblem = ''
-async function registerShortCode(
-  url: string,
-  domain: string
-): Promise<string | undefined> {
-  const code = new URL(url).searchParams.get('t') ?? ''
-  const script = shortCodeScript(devicesRoot(), code, url)
-  if (!script) {
-    shortLinkProblem = `${url} is not a link the box can shorten`
-    return undefined
-  }
-  const run =
-    await $`ssh -o BatchMode=yes -o ConnectTimeout=10 ${host!} ${script}`
-      .nothrow()
-      .quiet()
-  if (run.exitCode !== 0) return undefined
-  // Read it back through Caddy: a box whose Caddyfile predates short links answers with its
-  // gate, and a short link printed over that would lead nowhere.
-  const served = await fetch(`https://${domain}/_codes/${code}`, {
-    signal: AbortSignal.timeout(5000),
-  })
-    .then((res) => (res.ok ? res.text() : ''))
-    .catch(() => '')
-  if (served.trim() !== url) {
-    shortLinkProblem = `the box's Caddyfile does not serve short links yet: run \`tosijs-caddy-install --go\``
-    return undefined
-  }
-  return `https://${domain}/${code}`
-}
+const globalLinks = (kinds?: LinkKind[]) =>
+  globalLinksFor(
+    {
+      host: host!,
+      root: devicesRoot(),
+      projectName,
+      localPort,
+      label: flag('label'),
+      onRequest: has('link'),
+      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'),
+      }),
+      boxKeys: () => previewBoxKeys(host!),
+      ssh: (command) => sshTo(host!, command),
+      askForLink,
+      fetchText,
+    },
+    kinds
+  )
+let startLinks: Awaited<ReturnType<typeof globalLinks>> | undefined
 
 /*
 Say where this is going, and where the address came from, BEFORE acting on it.
@@ -703,20 +610,8 @@ 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, short } of startLinks.links) {
-      const code = new URL(url).searchParams.get('t') ?? ''
-      console.log(
-        `   ${kind}: ${url}${kind === 'view' ? '  (read-only)' : ''}` +
-          (short ? `\n         ${short}   code ${groupCode(code)}` : '')
-      )
-    }
-  }
-  for (const note of startLinks?.notes ?? []) console.log(`   note: ${note}`)
+  if (startLinks)
+    for (const line of startLinkLines(startLinks)) console.log(line)
 }
 console.log(`   Ctrl-C to close.\n`)
 

package/dist/carousel.d.ts

@@ -145,6 +145,7 @@ export declare class TosiCarousel extends TosiCarousel_base {
     handleDotClick: (event: Event) => void;
     private snapTimer;
     private animationFrame;
+    private cancelAnimation;
     animateScroll(position: number, startingPosition?: number, timestamp?: number): void;
     content: () => HTMLDivElement[];
     connectedCallback(): void;