@leftoff/cli 0.9.8-beta.2 → 0.9.8-beta.20

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) }

package/ui/update-bar.js

@@ -0,0 +1,158 @@
+// 0.9.8: "Leftoff updated · Refresh". An open board (a desktop tab, the
+// iPhone Home Screen app) keeps running the code it loaded with until it's
+// reloaded. The page knows the build it came with (index.html's
+// <meta name="leftoff-ui">, stamped by the Mac that served it, src/ui-build.js)
+// and every health check says what that Mac serves now (`ui`); when they differ
+// a bar offers a one-tap reload. Never on first load, never on its own, and a
+// failed health check changes nothing. The pure parts are unit-tested.
+
+export const POLL_MS = 60 * 1000 // a health check at least this often while the page is visible
+export const CARRY_KEY = 'leftoff.reload.carry' // drafts handed to the reloaded page
+export const CARRY_MAX_AGE_MS = 2 * 60 * 1000
+
+// The build this page loaded with: { build, machine } from the meta tag, or null.
+export function pageBuild(doc = typeof document !== 'undefined' ? document : null) {
+  const m = doc && doc.querySelector && doc.querySelector('meta[name="leftoff-ui"]')
+  const build = m && m.getAttribute('content')
+  return build ? { build, machine: m.getAttribute('data-machine') || '' } : null
+}
+
+// Should the bar show? loaded: { build, machine } (what this page runs);
+// current: a health answer ({ ui, machine }), or null when the check failed;
+// state: { showing, dismissed } (dismissed: the build whose bar was closed).
+export function shouldShow(loaded, current, state = {}) {
+  const showing = !!state.showing
+  if (!current || typeof current.ui !== 'string' || !current.ui) return showing // no answer (or an older Mac): keep what's there
+  if (!loaded || !loaded.build) return false
+  // The board moved to another Mac (yours went to sleep): its files aren't an update of this page's.
+  if (loaded.machine && current.machine && loaded.machine !== current.machine) return showing
+  if (current.ui === loaded.build) return false
+  if (state.dismissed && state.dismissed === current.ui) return false
+  return true
+}
+
+// What a reload would lose, in words; empty when nothing. Drafts (the Live
+// composer, replies) are carried over, so they aren't here.
+export function reloadRisks({ attachments = 0, uploading = 0, unsavedSettings = false, typing = false } = {}) {
+  const out = []
+  if (uploading > 0) out.push(uploading === 1 ? 'A file is still uploading' : uploading + ' files are still uploading')
+  else if (attachments > 0) out.push(attachments === 1 ? 'The attached file won’t carry over' : 'The ' + attachments + ' attached files won’t carry over')
+  if (unsavedSettings) out.push('Unsaved settings will be lost')
+  if (typing) out.push('What you’re typing will be lost')
+  return out
+}
+
+// Drafts handed over a reload: written right before it, read once right after.
+export function packCarry({ drafts = {}, focus = null, now = Date.now() } = {}) {
+  const d = {}
+  for (const [k, v] of Object.entries(drafts || {})) if (typeof v === 'string' && v.trim()) d[k] = v
+  return JSON.stringify({ at: now, drafts: d, focus: focus && d[focus.key] != null ? focus : null })
+}
+export function unpackCarry(raw, { now = Date.now(), maxAgeMs = CARRY_MAX_AGE_MS } = {}) {
+  try {
+    const j = JSON.parse(raw || '')
+    if (!j || typeof j.at !== 'number' || now - j.at > maxAgeMs || now < j.at - 5000) return null
+    const drafts = {}
+    for (const [k, v] of Object.entries(j.drafts || {})) if (typeof v === 'string') drafts[k] = v
+    const f = j.focus && typeof j.focus.key === 'string' ? { key: j.focus.key, a: Number(j.focus.a) || 0, b: Number(j.focus.b) || 0 } : null
+    return { drafts, focus: f }
+  } catch { return null }
+}
+
+// ------------------------------------------------------------ the bar (DOM)
+
+// mountUpdateBar({ health, risks, carry, icon }) -> { check(h), shown() }
+// health(): a fresh health answer (the board's refreshHealth); risks(): the
+// reloadRisks input; carry(): { drafts, focus } to hand over.
+export function mountUpdateBar({ health, risks = () => ({}), carry = () => ({}), icon = () => '', pollMs } = {}) {
+  const every = Number(pollMs || (typeof window !== 'undefined' && window.LEFTOFF_UPDATE_POLL_MS)) || POLL_MS
+  let loaded = pageBuild()
+  const st = { showing: false, dismissed: null, confirming: false, reloading: false }
+  let lastCheckAt = Date.now()
+  let el = null
+
+  function build() {
+    el = document.createElement('div')
+    el.className = 'updatebar'
+    el.id = 'updateBar'
+    el.setAttribute('role', 'status')
+    el.setAttribute('aria-live', 'polite')
+    el.hidden = true
+    el.innerHTML = '<span class="ub-icon" aria-hidden="true">' + icon('refresh-cw') + '</span><span class="ub-text">Leftoff updated</span>' +
+      '<button type="button" class="ub-go">Refresh</button><button type="button" class="ub-x" aria-label="Dismiss" title="Not now">' + icon('x') + '</button>'
+    document.body.appendChild(el)
+    // a click doesn't pull focus out of the box you're typing in
+    for (const b of el.querySelectorAll('button')) b.addEventListener('mousedown', (ev) => ev.preventDefault())
+    el.querySelector('.ub-go').addEventListener('click', onGo)
+    el.querySelector('.ub-x').addEventListener('click', onDismiss)
+  }
+  function paint() {
+    if (!el) build()
+    const was = !el.hidden
+    el.hidden = !st.showing
+    el.classList.toggle('confirm', st.confirming)
+    const text = el.querySelector('.ub-text'), go = el.querySelector('.ub-go')
+    if (st.confirming) { text.textContent = st.confirming; go.textContent = 'Refresh anyway' } else { text.textContent = 'Leftoff updated'; go.textContent = st.reloading ? 'Refreshing…' : 'Refresh' }
+    go.disabled = !!st.reloading
+    if (st.showing && !was) requestAnimationFrame(() => el && el.classList.add('in'))
+    if (!st.showing) el.classList.remove('in')
+    document.documentElement.classList.toggle('has-updatebar', st.showing)
+  }
+
+  // Every health answer the board gets comes through here (its own poll, the
+  // event stream reopening after a restart, the page coming back).
+  function check(h) {
+    lastCheckAt = Date.now()
+    if (h && !loaded && typeof h.ui === 'string' && h.ui) loaded = { build: h.ui, machine: h.machine || '' } // a page with no stamp: its first answer is its build
+    const next = shouldShow(loaded, h || null, st)
+    if (next !== st.showing) { st.showing = next; st.confirming = false; paint() }
+  }
+
+  function onDismiss() {
+    const h = lastHealth
+    st.dismissed = (h && h.ui) || st.dismissed || 'any'
+    st.showing = false; st.confirming = false
+    paint()
+  }
+  let lastHealth = null
+  function onHealth(h) { lastHealth = h; check(h) }
+
+  async function onGo() {
+    if (st.reloading) return
+    const words = reloadRisks(risks() || {})
+    if (words.length && !st.confirming) { st.confirming = words.join(' · '); paint(); return }
+    st.reloading = true; st.confirming = false; paint()
+    try { sessionStorage.setItem(CARRY_KEY, packCarry(carry() || {})) } catch {}
+    // A new service worker, if its file changed, before the page comes back.
+    try {
+      const reg = 'serviceWorker' in navigator && await navigator.serviceWorker.getRegistration()
+      if (reg) await Promise.race([reg.update(), new Promise((r) => setTimeout(r, 3000))])
+    } catch {}
+    location.reload()
+  }
+
+  // A health check at least every `every` ms while visible, and at once when
+  // the page comes back (the Home Screen app resumes, a bfcache restore).
+  const due = () => document.visibilityState !== 'hidden' && Date.now() - lastCheckAt >= every - 250
+  const tick = () => { if (due()) { lastCheckAt = Date.now(); Promise.resolve(health()).catch(() => {}) } }
+  setInterval(tick, Math.min(every, 15000))
+  const wake = (ev) => {
+    if (document.visibilityState === 'hidden') return
+    if (ev && ev.type === 'pageshow' && !ev.persisted) return
+    if (Date.now() - lastCheckAt < 3000) return
+    lastCheckAt = Date.now(); Promise.resolve(health()).catch(() => {})
+  }
+  document.addEventListener('visibilitychange', wake)
+  window.addEventListener('pageshow', wake)
+  window.addEventListener('online', wake)
+
+  return { check: onHealth, shown: () => st.showing, loaded: () => loaded }
+}
+
+// Right after a reload from the bar: the drafts it carried (once).
+export function takeCarry(storage = typeof sessionStorage !== 'undefined' ? sessionStorage : null) {
+  if (!storage) return null
+  let raw = null
+  try { raw = storage.getItem(CARRY_KEY); if (raw != null) storage.removeItem(CARRY_KEY) } catch { return null }
+  return raw ? unpackCarry(raw) : null
+}