@leftoff/cli 0.9.8-beta.14 → 0.9.8-beta.16

package/mod/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "leftoff",
-  "version": "0.9.8-beta.14",
+  "version": "0.9.8-beta.16",
   "description": "Leftoff (formerly Checkpoints): WTF was I working on? Tracks every Claude Code session on this machine, writes a 3-line checkpoint when one goes quiet, and adds /cp (checkpoint now), /cp-name and a /leftoff pane. Talks to the local Leftoff daemon on 127.0.0.1:7429 and falls back to writing markdown in ~/checkpoints.",
   "author": {
     "name": "Joel"

package/mod/hooks/register.js

@@ -28,7 +28,7 @@ const END_TIMEOUT_MS = 1000
 const MODEL_TIMEOUT_MS = 20000
 
 // Module state. $.state is not used: the pane redraws with $.ui.invalidate.
-const MOD_VERSION = '0.9.8-beta.14' // keep in step with .claude-plugin/plugin.json
+const MOD_VERSION = '0.9.8-beta.16' // keep in step with .claude-plugin/plugin.json
 
 const st = {
   internal: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leftoff/cli",
-  "version": "0.9.8-beta.14",
+  "version": "0.9.8-beta.16",
   "description": "Leftoff: WTF was I working on? Tracks every Claude Code session, writes a 3-line checkpoint when one goes quiet, and gives you a daily digest and a board, on your Mac and (optionally) your phone.",
   "keywords": [
     "claude",

package/ui/app.css

@@ -2610,3 +2610,8 @@ html.pv-open, html.pv-open body { overflow: hidden; }
 .updatebar .ub-go:focus-visible, .updatebar .ub-x:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
 @media (min-width: 700px) { .updatebar { left: calc(50% + var(--rail-w, 0px) / 2); } }
 @media (prefers-reduced-motion: reduce) { .updatebar { transition: none; } }
+
+/* 0.9.8: a non-Live session's Live box offers the Live resume command */
+.live-box.off .live-resume-row { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; margin-top: 6px; }
+.live-box.off .live-resume-row code { flex: 1 1 220px; min-width: 0; overflow-wrap: anywhere; font-size: 12.5px; padding: 8px 10px; border-radius: 8px; background: var(--card2); border: 1px solid var(--line); }
+.live-box.off .live-resume-row .btn { min-height: 44px; gap: 7px; }

package/ui/app.js

@@ -5,6 +5,7 @@ import { icon } from './icons.js'
 import { selectHtml, comboHtml, closeMenu, openActionMenu, closeActionMenu, actionMenuKey, openNameSheet } from './picker.js'
 import { SETTINGS, settingsKeyFor } from './settings-nav.js'
 import { mountWizard, shouldAutoOpen } from './wizard.js'
+import { shouldAutoTour, startTour } from './tour.js' // 0.9.8 the product tour
 import { changedKeys } from './settings-dirty.js'
 import { looksMd, stripMd, plainCp } from './cp-text.js'
 import { beginWriting, settleWriting, reconcileWriting, dismissWriting, isWriting, writingText, WRITING_SYNC_MS, FRESH_MS } from './writing.js'
@@ -1483,7 +1484,8 @@ function liveBoxHtml(s, v) {
     const how = state.liveHow
     return '<section class="live-box off" aria-label="Live link"><div class="live-head"><h2>Live <span class="pill soon">Beta</span></h2></div>' +
       '<p class="faint">To send this session messages from here or your phone, and answer its permission prompts, start it with <code>leftoff live</code>' +
-      (how && how.line ? ' (or <code>' + esc(how.line) + '</code>)' : '') + '. Claude Code asks once to load the channel; channels are a research preview.</p></section>'
+      (how && how.line ? ' (or <code>' + esc(how.line) + '</code>)' : '') + '. Claude Code asks once to load the channel; channels are a research preview.</p>' +
+      (s.liveResumeCommand ? '<p class="faint">Already running? Exit it in its terminal, then paste this to bring it back Live:</p><div class="live-resume-row"><code class="mono">' + esc(s.liveResumeCommand) + '</code><button type="button" class="btn" data-action="copy-cmd" data-cmd="' + esc(s.liveResumeCommand) + '">' + icon('copy') + 'Copy Live resume</button></div>' : '') + '</section>'
   }
   const msgs = (v && v.messages) || []
   const may = state.mayAnswer !== false
@@ -3176,7 +3178,7 @@ async function viewSettings() {
     updates: '<div class="section">About</div>' +
       '<label>Version</label><div class="aboutline"><span class="chip mono">v' + esc(h.version || '') + '</span><a href="#/whats-new">What’s new</a><a href="' + NPM_URL + '" target="_blank" rel="noopener">npm ↗</a></div>' +
       '<div class="hint">' + updateLine() + ' <button type="button" class="linkish" data-action="check-updates">Check now</button></div>' +
-      '<label>Setup</label><div class="aboutline"><a href="#/setup">Run setup again</a></div>' +
+      '<label>Setup</label><div class="aboutline"><a href="#/setup">Run setup again</a> · <a href="#/tour">Take the tour</a></div>' +
       advanced('updates', '<label for="f-updates">Check daily</label><label class="check"><input id="f-updates" type="checkbox"' + (!(c.updates && c.updates.check === false) ? ' checked' : '') + '><span>Look for a new version daily. Nothing installs on its own.</span></label>' +
         '<label>Machine</label><div><span class="chip machine">⌂ ' + esc(c.machineResolved) + '</span></div>' +
         '<label>Folder</label><div><a class="chip mono" href="file://' + esc(c.folder) + '">' + esc(c.folder) + '</a></div>'),
@@ -3875,7 +3877,7 @@ function paintListsCount(lists) {
 // The session page's Lists section: saved lists, the hint, and "Find lists in this session".
 function sessionListsSection(s) {
   const f = listUi.found[s.id]
-  let h = '<h2>Lists <span class="count">' + ((s.lists || []).length) + '</span><button type="button" class="helpq" data-action="list-help-go" title="How lists work">?</button></h2>'
+  let h = '<h2>Lists <span class="count">' + ((s.lists || []).length) + '</span><button type="button" class="helpq" data-action="list-help-inline" aria-expanded="' + (listUi.sHelp ? 'true' : 'false') + '" aria-controls="sListsHelp" title="How lists work">?</button></h2>' + (listUi.sHelp ? listsHelp().replace('id="listsHelp"', 'id="sListsHelp"') : '')
   if (s.lists && s.lists.length) h += '<div class="lists">' + s.lists.map((x) => (state.listFull && state.listFull[x.ref] ? listCard(state.listFull[x.ref], { session: false }) : '')).join('') + '</div>'
   if (s.listHint) h += '<div class="lfound hint"><div><strong>Claude wrote a ' + esc(s.listHint.count) + '-step list</strong>: ' + esc(s.listHint.name) + '</div><div class="row"><button type="button" class="btn primary" data-action="list-save-hint" data-id="' + esc(s.id) + '">Save</button><button type="button" class="btn" data-action="list-dismiss" data-id="' + esc(s.id) + '">Dismiss</button></div></div>'
   h += '<div class="lfind"><button type="button" class="btn" data-action="list-find" data-id="' + esc(s.id) + '"' + (listUi.finding[s.id] ? ' disabled' : '') + '>' + icon('list-checks') + (listUi.finding[s.id] ? 'Reading the transcript…' : 'Find lists in this session') + '</button>' +
@@ -3920,6 +3922,7 @@ async function render() {
     else if (r.name === 'docs' && r.arg) await viewDocPage(r.arg)
     else if (r.name === 'search') await viewSearch(r.q || '')
     else if (r.name === 'setup') await viewSetup()
+    else if (r.name === 'tour') { location.replace('#/'); startTour({ api }); return }
     else await viewBoard()
     tabsAfterRender()
   } catch (e) {
@@ -3932,12 +3935,20 @@ async function render() {
 // it keeps its own step and fetches its own state.
 async function viewSetup() {
   if ($app.querySelector('.wz')) return
-  await mountWizard($app, { api, esc, onDone: () => { location.hash = '#/' } })
+  await mountWizard($app, { api, esc, onDone: () => { location.hash = '#/'; autoTour() } })
 }
 // Opens #/setup by itself once, on a Mac's own board, when the board opens plain (no deep link).
+// Otherwise the product tour gets its turn.
 async function firstRunSetup() {
-  if (location.hash.replace(/^#\/?/, '')) return
-  try { const s = await api('GET', '/v1/setup'); if (shouldAutoOpen(s, (state.route || {}).name) && !location.hash.replace(/^#\/?/, '')) location.replace('#/setup') } catch {}
+  if (!location.hash.replace(/^#\/?/, '')) {
+    try { const s = await api('GET', '/v1/setup'); if (shouldAutoOpen(s, (state.route || {}).name) && !location.hash.replace(/^#\/?/, '')) return location.replace('#/setup') } catch {}
+  }
+  autoTour()
+}
+// The product tour (0.9.8, ui/tour.js): by itself once per Mac, after setup, on
+// the board; #/tour (Settings → Updates & about, the palette) replays it.
+async function autoTour() {
+  try { const t = await api('GET', '/v1/tour'); if (shouldAutoTour(t, parseRoute().name)) startTour({ api, auto: true }) } catch {}
 }
 
 // A remote browser (Tailscale) that hasn't signed in yet: the iPhone
@@ -4631,6 +4642,7 @@ function paletteActions() {
   }
   if (projectsUi.mayEdit) out.push({ action: 'project-new', title: 'New project…', sub: 'a named group of repos', icon: 'plus' })
   out.push({ action: 'gen-digest-go', title: 'Today’s digest', sub: 'open it', icon: 'newspaper', href: '#/digest' })
+  out.push({ action: 'tour', title: 'Take the tour', sub: 'a quick look around the board', icon: 'sparkles', href: '#/tour' })
   return out
 }
 function searchGroups(q, r) {
@@ -4950,6 +4962,7 @@ document.addEventListener('click', async (ev) => {
     if (action === 'list-showall') { listUi.showAll = !listUi.showAll; return render() }
     if (action === 'list-help') { listUi.help = !listUi.help; return render() }
     if (action === 'list-help-go') { listUi.help = true; location.hash = '#/lists'; return }
+    if (action === 'list-help-inline') { listUi.sHelp = !listUi.sHelp; render(); return }
     if (action === 'remote-link' || action === 'remote-code') {
       const l = await api('POST', '/v1/remote/link', action === 'remote-link' ? { full: true } : undefined)
       if (l.needed === false) { toast('No sign-in needed (remoteRequireToken is off)'); return }

package/ui/tour.css

@@ -0,0 +1,63 @@
+/* The product tour (0.9.8, ui/tour.js). Loaded only when the tour starts. */
+.tour { position: fixed; inset: 0; z-index: 900; pointer-events: auto; touch-action: none; }
+.tour-dim { position: absolute; inset: 0; background: rgba(3, 5, 10, .7); animation: tour-in .18s ease-out; }
+.tour-dim[hidden], .tour-hole[hidden] { display: none; }
+/* The spotlight: a clear box whose huge shadow dims everything around it. */
+.tour-hole { position: fixed; border-radius: 12px; box-shadow: 0 0 0 2px var(--accent), 0 0 0 200vmax rgba(3, 5, 10, .7); pointer-events: none;
+  transition: left .25s ease, top .25s ease, width .25s ease, height .25s ease; }
+[data-theme="light"] .tour-dim { background: rgba(15, 18, 28, .6); }
+[data-theme="light"] .tour-hole { box-shadow: 0 0 0 2px var(--accent), 0 0 0 200vmax rgba(15, 18, 28, .6); }
+.tour-card { position: fixed; left: 0; top: 0; width: 340px; max-width: calc(100vw - 16px - env(safe-area-inset-left) - env(safe-area-inset-right)); box-sizing: border-box;
+  background: var(--card2); color: var(--text); border: 1px solid var(--line-strong); border-radius: 16px; padding: 16px 16px 10px;
+  box-shadow: 0 18px 50px rgba(0, 0, 0, .45); transition: left .25s ease, top .25s ease; outline: none; }
+[data-theme="light"] .tour-card { background: var(--card); box-shadow: 0 18px 50px rgba(22, 26, 36, .28); }
+.tour-count { font-size: 12px; font-weight: 600; color: var(--muted); letter-spacing: .2px; }
+.tour-card .tour-title { font-size: 17px; font-weight: 650; margin: 2px 0 6px; line-height: 1.25; color: var(--text); text-transform: none; letter-spacing: normal; }
+.tour-body { font-size: 14px; line-height: 1.45; color: var(--text2); margin: 0 0 10px; }
+.tour-nav { display: flex; align-items: center; gap: 8px; }
+.tour-grow { flex: 1; }
+.tour-nav .btn { min-height: 44px; box-sizing: border-box; text-decoration: none; min-width: 44px; padding: 6px 14px; font-size: 14px; justify-content: center; }
+.tour-nav .tour-skip { color: var(--muted); padding: 6px 4px; background: none; border: 0; box-shadow: none; }
+.tour-nav .tour-skip:hover { color: var(--text); background: none; }
+.tour-still .tour-hole, .tour-still .tour-card, .tour-still .tour-dim { transition: none; animation: none; }
+@media (prefers-reduced-motion: reduce) { .tour-hole, .tour-card, .tour-dim { transition: none; animation: none; } }
+@keyframes tour-in { from { opacity: 0; } to { opacity: 1; } }
+/* Read by tour.js for the safe areas. */
+.tour-safe { position: fixed; inset: 0; visibility: hidden; pointer-events: none; padding: env(safe-area-inset-top) env(safe-area-inset-right) env(safe-area-inset-bottom) env(safe-area-inset-left); }
+@media (max-width: 699.98px) { .tour-card { width: 100vw; } }
+
+/* Small drawings for a part that isn't on screen. */
+.tour-illus { background: var(--bg); border: 1px solid var(--line); border-radius: 12px; padding: 12px; margin: 0 0 12px; font-size: 12.5px; color: var(--text2); display: grid; gap: 8px; }
+.tour-illus .ti-row { display: flex; align-items: center; gap: 6px; flex-wrap: wrap; }
+.tour-illus .ti-faint { color: var(--muted); }
+.tour-illus .ti-pill { border-radius: 999px; padding: 1px 8px; font-size: 11px; font-weight: 600; background: var(--tint-cyan); color: var(--cyan); margin-left: auto; }
+.tour-illus .ti-pill.ti-needs { background: var(--tint-yellow); color: var(--yellow); margin-left: 0; }
+.tour-illus .ti-btn { border: 1px solid var(--btn-line); background: var(--btn-bg); border-radius: 7px; padding: 3px 9px; font-size: 12px; }
+.tour-illus .ti-btn.ti-primary { background: var(--accent); border-color: var(--accent); color: var(--on-accent); font-weight: 600; }
+.tour-illus .ti-dot { width: 8px; height: 8px; border-radius: 50%; background: var(--green); flex: none; }
+.tour-illus .ti-card, .tour-illus .ti-need { background: var(--card); border: 1px solid var(--line); border-radius: 10px; padding: 10px; display: grid; gap: 6px; }
+.tour-illus .ti-need { border-color: var(--yellow); }
+.tour-illus .ti-need.ti-mini { padding: 8px; }
+.tour-illus .ti-cp { display: grid; gap: 2px; border-left: 2px solid var(--line-strong); padding-left: 8px; }
+.tour-illus .ti-cp i { font-style: normal; color: var(--muted); }
+.tour-illus .ti-live { display: grid; gap: 6px; }
+.tour-illus .ti-msg { max-width: 80%; border-radius: 12px; padding: 5px 10px; }
+.tour-illus .ti-you { justify-self: end; background: var(--tint-accent); color: var(--text); }
+.tour-illus .ti-claude { justify-self: start; background: var(--card); border: 1px solid var(--line); }
+.tour-illus .ti-composer { display: flex; align-items: center; gap: 8px; border: 1px solid var(--line-strong); border-radius: 18px; padding: 4px 4px 4px 10px; background: var(--field); }
+.tour-illus .ti-clip { display: inline-flex; width: 16px; height: 16px; color: var(--muted); }
+.tour-illus .ti-clip svg { width: 16px; height: 16px; }
+.tour-illus .ti-input { flex: 1; color: var(--faint); }
+.tour-illus .ti-send { width: 24px; height: 24px; border-radius: 50%; background: var(--accent); color: var(--on-accent); display: inline-flex; align-items: center; justify-content: center; font-weight: 700; }
+.tour-illus .ti-tabs { display: flex; gap: 4px; border-bottom: 1px solid var(--line); }
+.tour-illus .ti-tab { padding: 5px 10px; border: 1px solid var(--line); border-bottom: 0; border-radius: 8px 8px 0 0; background: var(--card); color: var(--muted); white-space: nowrap; }
+.tour-illus .ti-tab.ti-on { color: var(--text); background: var(--card2); font-weight: 600; }
+.tour-illus .ti-phone { width: 150px; margin: 0 auto; border: 2px solid var(--line-strong); border-radius: 22px; padding: 10px 8px 14px; display: grid; gap: 8px; background: var(--card); }
+.tour-illus .ti-url { font-size: 10.5px; text-align: center; background: var(--bg2); border-radius: 8px; padding: 3px 6px; color: var(--text2); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.tour-illus .ti-note { display: grid; gap: 1px; background: var(--card2); border: 1px solid var(--line); border-radius: 10px; padding: 6px 8px; font-size: 11px; box-shadow: 0 4px 12px rgba(0, 0, 0, .18); }
+.tour-illus .ti-note span { color: var(--muted); }
+.tour-illus .ti-lines { display: grid; gap: 5px; }
+.tour-illus .ti-lines span { height: 7px; border-radius: 4px; background: var(--line); }
+.tour-illus .ti-lines span:nth-child(2) { width: 70%; }
+.tour-illus .ti-lines span:nth-child(3) { width: 45%; }
+@media (max-height: 700px) { .tour-illus { padding: 8px; gap: 6px; } .tour-illus .ti-phone { width: 130px; } }

package/ui/tour.js

@@ -0,0 +1,364 @@
+// The product tour (0.9.8): six quick spotlight steps over the real board,
+// separate from the setup wizard (ui/wizard.js). It dims the page, cuts a hole
+// around the part it talks about and puts a small card beside it. A part that
+// isn't on screen (no session yet, tabs on a phone, Live outside a session)
+// gets the card in the middle with a small drawing instead: never a spotlight
+// on nothing, and nothing is written into your sessions for it.
+//
+// It runs by itself once per Mac (the record sits beside the wizard's,
+// GET /v1/tour, POST /v1/tour/seen), after setup has been seen, on a plain
+// board open. Settings → Updates & about → "Take the tour" and the command
+// palette replay it (#/tour). The pure parts below are shared with the unit
+// tests; startTour() is the DOM side.
+
+export const TOUR_KEYS = ['needs', 'card', 'live', 'tabs', 'catchup', 'phone']
+
+// Does the board start it by itself? state: GET /v1/tour. routeName: the
+// route the board is on. Not over the setup wizard: on this Mac's own board
+// it waits until setup has been seen (another device never gets the wizard).
+export function shouldAutoTour(state, routeName) {
+  return !!state && state.auto === true && state.seen === false && (state.setupSeen === true || state.local === false) && (!routeName || routeName === 'board')
+}
+
+// The six steps for what's on screen. found: { needs: 'strip' | 'nav' | null,
+// card: bool, live: bool, tabs: 'strip' | 'row' | null, catchup: bool }.
+// ctx: { narrow: phone width, standalone: the Home Screen app, host: the
+// leftoff.dev name or null }. Each step: { key, title, body, target, illus }:
+// target names what to spotlight (null: the card sits in the middle with
+// illus, a small drawing).
+export function tourSteps(found = {}, ctx = {}) {
+  const f = found || {}
+  const host = ctx.host || 'yourname.leftoff.dev'
+  const steps = []
+  steps.push(f.needs === 'strip'
+    ? { key: 'needs', title: 'Needs you', body: 'Sessions waiting on you come first: a permission prompt or a question from Claude. Answer right here, or Go to the terminal.', target: 'needs-strip', illus: null }
+    : { key: 'needs', title: 'Needs you', body: 'When a session stops for a permission prompt or a question, it lands here, longest wait first. Answer from the board, or Go to the terminal.', target: f.needs === 'nav' ? 'needs-nav' : null, illus: f.needs === 'nav' ? null : 'needs' })
+  steps.push({ key: 'card', title: 'A session', body: 'One card per Claude Code session: its status and its latest checkpoint (what it was doing, where it stopped, what’s next). Go jumps to its terminal, Resume reopens a closed one, and Checkpoint now is in the ⋯ menu.', target: f.card ? 'card' : null, illus: f.card ? null : 'card' })
+  steps.push({ key: 'live', title: 'Live', body: 'Start a session with leftoff live and talk to it from its page: Claude reads your message as its next prompt. Attach photos or files with the paperclip, and answer permission prompts here or on your phone.', target: f.live ? 'live' : null, illus: f.live ? null : 'live' })
+  steps.push(ctx.narrow
+    ? { key: 'tabs', title: 'Open sessions', body: 'Sessions you open stay in an Open row on the board. On a session, swipe or tap ‹ › to move between them.', target: f.tabs === 'row' ? 'tabs-row' : null, illus: f.tabs === 'row' ? null : 'tabs' }
+    : { key: 'tabs', title: 'Tabs', body: 'Sessions open in tabs up here, next to the board. A click opens a preview tab; it stays once you type in it or double-click it.', target: f.tabs === 'strip' ? 'tabs-strip' : null, illus: f.tabs === 'strip' ? null : 'tabs' })
+  steps.push({ key: 'catchup', title: 'Catch up', body: 'Back after a while? Catch me up tells you what got done and what’s waiting. The digest sums up each day.', target: f.catchup ? 'catchup' : null, illus: f.catchup ? null : 'catchup' })
+  steps.push(ctx.narrow && ctx.standalone
+    ? { key: 'phone', title: 'Your phone', body: 'You’re in the Home Screen app. Tap Turn on notifications under More, and your phone buzzes when a session needs you.', target: null, illus: 'phone', host }
+    : { key: 'phone', title: 'Your phone', body: 'Open ' + host + ' on your iPhone and add it to your Home Screen. It works like an app, with a notification when a session needs you.', target: null, illus: 'phone', host, link: { href: '#/settings/phone', label: 'Phone settings' } })
+  return steps
+}
+
+// Next index for a move: dir -1 | 1, clamped to the steps there are.
+export function moveIndex(i, n, dir) {
+  const k = Math.max(0, Math.min(Number(n) - 1, (Number(i) || 0) + (dir < 0 ? -1 : 1)))
+  return Number.isFinite(k) ? k : 0
+}
+
+// Where the card goes. target: { top, left, width, height } (the spotlight)
+// or null (the middle). card: { width, height }. vp: { width, height }.
+// insets: { top, right, bottom, left } kept clear (safe areas, the phone's
+// bottom bar). Below, else above, else beside, else over the bottom of the
+// target; always inside vp minus insets (and a margin) when it fits there.
+export function placeCard(target, card, vp, insets = {}, { gap = 12, margin = 8 } = {}) {
+  const ins = { top: 0, right: 0, bottom: 0, left: 0, ...insets }
+  const x0 = ins.left + margin, x1 = vp.width - ins.right - margin
+  const y0 = ins.top + margin, y1 = vp.height - ins.bottom - margin
+  const cw = Math.min(card.width, x1 - x0), ch = card.height
+  const clampX = (x) => Math.max(x0, Math.min(x1 - cw, x))
+  const clampY = (y) => Math.max(y0, Math.min(y1 - ch, y))
+  const out = (left, top, side) => ({ left: Math.round(left), top: Math.round(top), side })
+  if (!target) return out(clampX((x0 + x1 - cw) / 2), clampY((y0 + y1 - ch) / 2), 'center')
+  const t = { top: target.top, left: target.left, bottom: target.top + target.height, right: target.left + target.width }
+  const midX = clampX(t.left + (t.right - t.left) / 2 - cw / 2)
+  if (y1 - (t.bottom + gap) >= ch) return out(midX, Math.max(y0, t.bottom + gap), 'below')
+  if (t.top - gap - y0 >= ch) return out(midX, Math.min(y1 - ch, t.top - gap - ch), 'above')
+  const midY = clampY(t.top)
+  if (x1 - (t.right + gap) >= cw) return out(t.right + gap, midY, 'right')
+  if (t.left - gap - x0 >= cw) return out(t.left - gap - cw, midY, 'left')
+  return out(midX, clampY(y1 - ch), 'over')
+}
+
+// The spotlight for an element's rect: a little room around it, kept on screen.
+export function holeFor(rect, vp, pad = 6) {
+  const left = Math.max(2, rect.left - pad), top = Math.max(2, rect.top - pad)
+  const right = Math.min(vp.width - 2, rect.left + rect.width + pad), bottom = Math.min(vp.height - 2, rect.top + rect.height + pad)
+  if (right - left < 4 || bottom - top < 4) return null
+  return { left, top, width: right - left, height: bottom - top }
+}
+
+// ------------------------------------------------------------- drawings
+
+const CLIP = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m21.4 11.1-8.9 8.9a5.5 5.5 0 0 1-7.8-7.8l8.9-8.9a3.7 3.7 0 0 1 5.2 5.2l-8.9 8.9a1.8 1.8 0 0 1-2.6-2.6l8.2-8.2"/></svg>'
+const ESC = (s) => String(s == null ? '' : s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]))
+
+// Small static drawings for a step whose part isn't on screen. Demo names only.
+export function illusHtml(name, step = {}) {
+  const box = (inner) => '<div class="tour-illus tour-illus-' + name + '" aria-hidden="true">' + inner + '</div>'
+  if (name === 'needs') return box('<div class="ti-need"><span class="ti-pill ti-needs">needs you</span><b>api</b><span class="ti-faint">Bash: pnpm test</span><div class="ti-row"><span class="ti-btn ti-primary">Allow</span><span class="ti-btn">Deny</span></div></div>')
+  if (name === 'card') return box('<div class="ti-card"><div class="ti-row"><span class="ti-dot"></span><b>Fix the login redirect</b><span class="ti-pill">waiting</span></div><div class="ti-faint">acme/web · studio · 2 min</div>' +
+    '<div class="ti-cp"><div><i>Doing</i> moving the redirect into middleware</div><div><i>Stopped at</i> tests for the expired-session case</div><div><i>Next</i> run the e2e suite</div></div>' +
+    '<div class="ti-row"><span class="ti-btn ti-primary">Go</span><span class="ti-btn">⋯</span></div></div>')
+  if (name === 'live') return box('<div class="ti-live"><div class="ti-msg ti-you">Can you run the tests?</div><div class="ti-msg ti-claude">Running them now.</div>' +
+    '<div class="ti-need ti-mini"><span class="ti-faint">Allow Bash: pnpm test?</span><div class="ti-row"><span class="ti-btn ti-primary">Allow</span><span class="ti-btn">Deny</span></div></div>' +
+    '<div class="ti-composer"><span class="ti-clip">' + CLIP + '</span><span class="ti-input">Message Claude</span><span class="ti-send">↑</span></div></div>')
+  if (name === 'tabs') return box('<div class="ti-tabs"><span class="ti-tab ti-on">Board</span><span class="ti-tab"><i>acme/web</i></span><span class="ti-tab">api ×</span></div>')
+  if (name === 'catchup') return box('<div class="ti-row"><span class="ti-btn ti-primary">Catch me up</span><span class="ti-btn">Today’s digest →</span></div>')
+  if (name === 'phone') return box('<div class="ti-phone"><div class="ti-url">' + ESC(step.host || 'yourname.leftoff.dev') + '</div><div class="ti-note"><b>Leftoff</b><span>api needs you: Allow Bash?</span></div><div class="ti-lines"><span></span><span></span><span></span></div></div>')
+  return ''
+}
+
+// The card's inside for step i of n.
+export function cardHtml(step, i, n) {
+  const last = i === n - 1
+  return (step.illus ? illusHtml(step.illus, step) : '') +
+    '<div class="tour-count">' + (i + 1) + ' of ' + n + '</div>' +
+    '<h2 class="tour-title" id="tourTitle">' + ESC(step.title) + '</h2>' +
+    '<p class="tour-body" id="tourBody">' + ESC(step.body) + '</p>' +
+    '<div class="tour-nav">' + (last ? (step.link ? '<a class="btn tour-link" href="' + ESC(step.link.href) + '" data-tour="link">' + ESC(step.link.label) + '</a>' : '') + '<span class="tour-grow"></span>' : '<button type="button" class="btn linkish tour-skip" data-tour="skip">Skip tour</button><span class="tour-grow"></span>') +
+      (i > 0 ? '<button type="button" class="btn" data-tour="back">Back</button>' : '') +
+      '<button type="button" class="btn primary" data-tour="' + (last ? 'done' : 'next') + '">' + (last ? 'Done' : 'Next') + '</button></div>'
+}
+
+// ------------------------------------------------------------- the DOM side
+
+const SEL = {
+  'needs-strip': '#app .needs-strip',
+  'needs-nav': '#needsTab',
+  card: '#app article.card:not(.agentcard):not(.closed-card)',
+  live: '#app #live',
+  'tabs-strip': '#tabStrip',
+  'tabs-row': '#openRow',
+  catchup: '#app .pagehead .actions',
+}
+function shown(el) {
+  if (!el || el.hidden || el.closest('[hidden]')) return false
+  const r = el.getBoundingClientRect()
+  if (r.width < 4 || r.height < 4) return false
+  const cs = getComputedStyle(el)
+  return cs.visibility !== 'hidden' && cs.display !== 'none'
+}
+// The room a target gets on screen: under the top bars, above the phone's bottom bar.
+function room() {
+  const ins = insets()
+  let top = ins.top
+  for (const el of document.querySelectorAll('.top, #tabStrip')) {
+    if (!shown(el)) continue
+    const r = el.getBoundingClientRect(), pos = getComputedStyle(el).position
+    if ((pos === 'fixed' || pos === 'sticky') && r.top < 10 && r.bottom < window.innerHeight / 3) top = Math.max(top, r.bottom)
+  }
+  return { top, bottom: window.innerHeight - ins.bottom, ins }
+}
+function findEl(target, cardH = 260) {
+  if (!target) return null
+  const all = [...document.querySelectorAll(SEL[target] || '#none')].filter(shown)
+  if (target === 'card') {
+    // a session card short enough to sit beside the tour's card, else the shortest of the first few
+    const cards = all.filter((el) => !el.closest('.needs-strip')).slice(0, 8)
+    const r = room(), fits = (el) => el.getBoundingClientRect().height + cardH + 40 <= r.bottom - r.top
+    return cards.find((el) => fits(el) && el.querySelector('.actions-row')) || cards.sort((a, b) => a.offsetHeight - b.offsetHeight)[0] || null
+  }
+  return all[0] || null
+}
+// What gets the spotlight: the element, or for the Needs you strip its head and first ask.
+function rectOf(target, el) {
+  if (target === 'needs-strip') {
+    const parts = [el.querySelector('.needs-head'), el.querySelector('.needs-list > *')].filter(Boolean).map((x) => x.getBoundingClientRect())
+    if (parts.length) {
+      const l = Math.min(...parts.map((r) => r.left)), t = Math.min(...parts.map((r) => r.top)), rr = Math.max(...parts.map((r) => r.right)), b = Math.max(...parts.map((r) => r.bottom))
+      return { left: l, top: t, width: rr - l, height: b - t }
+    }
+  }
+  return el.getBoundingClientRect()
+}
+// What's on screen right now, for tourSteps().
+export function probe() {
+  const has = (t) => !!findEl(t)
+  return {
+    needs: has('needs-strip') ? 'strip' : has('needs-nav') ? 'nav' : null,
+    card: has('card'), live: has('live'),
+    tabs: has('tabs-strip') ? 'strip' : has('tabs-row') ? 'row' : null,
+    catchup: has('catchup'),
+  }
+}
+
+let current = null // one tour at a time
+export function tourOpen() { return !!current }
+
+function loadCss() {
+  if (document.querySelector('link[data-tour-css]')) return Promise.resolve()
+  return new Promise((resolve) => {
+    const l = document.createElement('link')
+    l.rel = 'stylesheet'; l.href = 'tour.css'; l.dataset.tourCss = '1'
+    const t = setTimeout(resolve, 2000)
+    l.onload = l.onerror = () => { clearTimeout(t); resolve() }
+    document.head.appendChild(l)
+  })
+}
+const waitFor = (pred, ms = 4000) => new Promise((resolve) => {
+  const t0 = Date.now()
+  const tick = () => { if (pred()) return resolve(true); if (Date.now() - t0 > ms) return resolve(false); setTimeout(tick, 60) }
+  tick()
+})
+const narrowQ = () => window.matchMedia('(max-width: 699.98px)').matches
+const reduced = () => window.matchMedia('(prefers-reduced-motion: reduce)').matches
+const isStandalone = () => !!(window.navigator.standalone || (window.matchMedia && window.matchMedia('(display-mode: standalone)').matches))
+
+// Safe areas, read from a probe the stylesheet pads with env(), plus the
+// phone's bottom bar while it shows.
+function insets() {
+  const p = document.createElement('div')
+  p.className = 'tour-safe'
+  document.body.appendChild(p)
+  const cs = getComputedStyle(p)
+  const ins = { top: parseFloat(cs.paddingTop) || 0, right: parseFloat(cs.paddingRight) || 0, bottom: parseFloat(cs.paddingBottom) || 0, left: parseFloat(cs.paddingLeft) || 0 }
+  p.remove()
+  const bar = document.querySelector('.top .tabs')
+  if (bar && narrowQ() && !document.body.classList.contains('nav-hidden')) {
+    const r = bar.getBoundingClientRect()
+    if (r.height && r.top > window.innerHeight / 2) ins.bottom = Math.max(ins.bottom, window.innerHeight - r.top)
+  }
+  return ins
+}
+
+// Start it. deps: { api, auto: started by itself, onEnd(how) }. Goes to the
+// board first when it's somewhere else.
+export async function startTour({ api, auto = false, onEnd = () => {} } = {}) {
+  if (current) return current
+  const me = (current = { closed: false })
+  const back = document.activeElement && document.activeElement !== document.body ? document.activeElement : null
+  if (!/^#\/?(\?|$)/.test(location.hash || '#/')) location.hash = '#/'
+  // the board, drawn (its head links to the digest; no other page's does)
+  await Promise.all([loadCss(), waitFor(() => /^#\/?(\?|$)/.test(location.hash || '#/') && !!document.querySelector('#app .pagehead .actions a[href="#/digest"]'))])
+  if (me.closed) return
+  if (document.querySelector('.wz')) { current = null; return } // the setup wizard is up: not over it
+  let host = /\.leftoff\.dev$/.test(location.hostname) ? location.hostname : null
+  if (!host && api) { try { const r = await api('GET', '/v1/relay', undefined, { timeoutMs: 1500 }); if (r && r.host) host = r.host } catch {} }
+
+  const root = document.createElement('div')
+  root.className = 'tour' + (reduced() ? ' tour-still' : '')
+  root.innerHTML = '<div class="tour-dim"></div><div class="tour-hole" hidden></div>' +
+    '<div class="tour-card" role="dialog" aria-modal="true" aria-labelledby="tourTitle" aria-describedby="tourBody" tabindex="-1"></div>'
+  document.body.appendChild(root)
+  document.body.classList.add('tour-on')
+  const dim = root.querySelector('.tour-dim'), hole = root.querySelector('.tour-hole'), card = root.querySelector('.tour-card')
+  let i = 0, steps = [], raf = 0, timer = 0, pinned = null, marked = null
+
+  const ctx = () => ({ narrow: narrowQ(), standalone: isStandalone(), host })
+  const place = () => {
+    raf = 0
+    if (me.closed) return
+    const step = steps[i]
+    const el = step && (pinned && pinned.isConnected ? pinned : findEl(step.target, card.offsetHeight))
+    const vp = { width: window.innerWidth, height: window.innerHeight }
+    let h = el ? holeFor(rectOf(step.target, el), vp) : null
+    // A target too tall to sit beside the card: the spotlight keeps its top part.
+    if (h && step.target !== 'needs-nav' && step.target !== 'tabs-strip') {
+      const rm = room(), spare = rm.bottom - 12 - card.offsetHeight - 12 - h.top
+      if (h.top + h.height > rm.bottom - card.offsetHeight - 24 && h.top - rm.top < card.offsetHeight + 24 && spare >= 80) h = { ...h, height: Math.min(h.height, spare) }
+    }
+    // the spotlit element carries data-tour-on (the browser check reads it)
+    const lit = h ? el : null
+    if (marked !== lit) { if (marked) marked.removeAttribute('data-tour-on'); if (lit) lit.setAttribute('data-tour-on', step.target); marked = lit }
+    root.dataset.step = step ? step.key : ''
+    root.dataset.mode = h ? 'spot' : 'center'
+    if (h) {
+      hole.hidden = false; dim.hidden = true
+      Object.assign(hole.style, { left: h.left + 'px', top: h.top + 'px', width: h.width + 'px', height: h.height + 'px' })
+    } else { hole.hidden = true; dim.hidden = false }
+    const at = placeCard(h, { width: card.offsetWidth, height: card.offsetHeight }, vp, insets())
+    Object.assign(card.style, { left: at.left + 'px', top: at.top + 'px' })
+    card.dataset.side = at.side
+  }
+  const soon = () => { if (!raf) raf = requestAnimationFrame(place) }
+
+  const show = (k, focus = true) => {
+    i = k
+    steps = tourSteps(probe(), ctx())
+    let step = steps[i]
+    // The target a step names: brought on screen under the top bars (the bars
+    // held, so the phone's bottom bar doesn't slide away under it).
+    if (window.leftoffNav) window.leftoffNav.show()
+    card.innerHTML = cardHtml(step, i, steps.length) // measured below
+    const el = findEl(step.target, card.offsetHeight)
+    pinned = el
+    if (el && step.target !== 'needs-nav' && step.target !== 'tabs-strip') {
+      const r = rectOf(step.target, el), rm = room()
+      const fitsWithCard = r.height + card.offsetHeight + 24 <= rm.bottom - rm.top
+      if (fitsWithCard ? (r.top < rm.top + 8 || r.top + r.height + card.offsetHeight + 24 > rm.bottom) : (r.top < rm.top + 8 || r.top > rm.top + 24)) window.scrollBy(0, r.top - rm.top - 12)
+    }
+    if (!el && step.target) { steps[i] = step = { ...step, target: null, illus: step.illus || step.key } }
+    card.innerHTML = cardHtml(step, i, steps.length)
+    card.dataset.key = step.key
+    place()
+    clearTimeout(timer); timer = setTimeout(place, 260) // after the bars and the scroll settle
+    if (focus) { const b = card.querySelector('[data-tour="next"], [data-tour="done"]'); if (b) b.focus({ preventScroll: true }) }
+  }
+
+  const end = (how) => {
+    if (me.closed) return
+    me.closed = true; current = null
+    cancelAnimationFrame(raf); clearTimeout(timer)
+    mo.disconnect()
+    window.removeEventListener('resize', soon); window.removeEventListener('scroll', soon, true)
+    document.removeEventListener('keydown', onKey, true)
+    root.remove(); document.body.classList.remove('tour-on')
+    if (api) api('POST', '/v1/tour/seen', { how }).catch(() => {})
+    document.removeEventListener('focusin', onFocus)
+    window.removeEventListener('hashchange', onHash)
+    if (marked) marked.removeAttribute('data-tour-on')
+    // focus goes back where it was; if that's gone (Settings → Take the tour), to the page's heading
+    const to = back && back.isConnected ? back : document.querySelector('#app .pagehead h1')
+    if (to && to !== back) to.tabIndex = -1
+    if (to && to.focus) { try { to.focus({ preventScroll: true }) } catch {} }
+    onEnd(how)
+  }
+  me.end = end
+
+  const go = (dir) => { const k = moveIndex(i, steps.length, dir); if (k !== i) show(k) }
+  root.addEventListener('click', (e) => {
+    const b = e.target.closest('[data-tour]')
+    if (!b) return
+    const a = b.dataset.tour
+    if (a === 'next') go(1)
+    else if (a === 'back') go(-1)
+    else if (a === 'done') end('done')
+    else if (a === 'skip') end('skipped')
+    else if (a === 'link') { e.preventDefault(); const to = b.getAttribute('href'); end('done'); location.hash = to }
+  })
+  // Nothing under the dim scrolls or takes a tap while it's up.
+  const still = (e) => { if (!card.contains(e.target)) e.preventDefault() }
+  root.addEventListener('wheel', still, { passive: false })
+  root.addEventListener('touchmove', still, { passive: false })
+  function onKey(e) {
+    if (me.closed) return
+    const k = e.key
+    if (k === 'Escape') { e.preventDefault(); end('skipped') }
+    else if (k === 'ArrowRight' || k === 'PageDown') { e.preventDefault(); go(1) }
+    else if (k === 'ArrowLeft' || k === 'PageUp') { e.preventDefault(); go(-1) }
+    else if (k === 'Enter' && !(e.target.closest && e.target.closest('button, a') && card.contains(e.target))) { e.preventDefault(); if (i === steps.length - 1) end('done'); else go(1) }
+    else if (k === 'Tab') {
+      // focus stays in the card
+      const f = [...card.querySelectorAll('button, a[href]')].filter((x) => !x.disabled)
+      if (!f.length) return
+      const at = f.indexOf(document.activeElement)
+      e.preventDefault()
+      const n = e.shiftKey ? (at <= 0 ? f.length - 1 : at - 1) : (at < 0 || at === f.length - 1 ? 0 : at + 1)
+      f[n].focus()
+    } else if (!card.contains(e.target)) e.preventDefault()
+    e.stopPropagation() // the board's own shortcuts wait
+  }
+  document.addEventListener('keydown', onKey, true)
+  function onFocus(e) { if (!me.closed && !root.contains(e.target)) { const b = card.querySelector('[data-tour="next"], [data-tour="done"]'); if (b) b.focus({ preventScroll: true }) } }
+  document.addEventListener('focusin', onFocus)
+  // The board redraws under it (live updates): the spotlight follows.
+  const mo = new MutationObserver(() => { if (pinned && !pinned.isConnected) pinned = null; soon() })
+  const app = document.getElementById('app')
+  if (app) mo.observe(app, { childList: true, subtree: true })
+  window.addEventListener('resize', soon)
+  window.addEventListener('scroll', soon, true)
+  // Leaving the board (a link, the back button) ends it.
+  function onHash() { if (!me.closed && !/^#\/?(\?|$)/.test(location.hash || '#/')) end('skipped') }
+  window.addEventListener('hashchange', onHash)
+  show(0)
+  return me
+}
+
+// Close a running tour (the board calls this before it opens something else).
+export function endTour(how = 'skipped') { if (current && current.end) current.end(how) }