@lovek4d/kickflip 0.0.0-stage → 0.3.1

package/board/public/prototype-switcher.js

@@ -0,0 +1,226 @@
+// The floating ‹ take › pill every prototype page switches its takes with (docs/adr/0015-prototypes-come-on-request.md).
+// Load it with a relative src after claude.js, on a page whose header leads with the back arrow, then call
+//   const sw = PrototypeSwitcher.mount({ takes: { A: 'A. Name', … }, initial: 'A', render(take) {…}, above: el? })
+// render runs at mount and on each switch; sw.take is the current key. ←/→ switch unless a field has focus, and the
+// take stays in ?variant=. With ?q=<owner question id>, the pill offers the take as that question's answer: a take
+// is pickable when an option's id equals its key. Pick sends the owner-answer event questions.html sends, with the
+// note typed above the pill, then moves on through BoardUI.nextQuestion (ui-questions.js).
+// PrototypeSwitcher.current is the mounted switcher, whose go(key) shows another take in place; Waiting on you uses it
+// to switch its full-width frame without a reload (view-questions.js inPlace).
+// With ?take=<key> the page shows that take alone, with no header or pill, as questions.html frames it
+// (docs/adr/0048-a-questions-takes-show-inline.md); a page hides its own extras under html.ps-embed. There main's
+// bottom padding, kept clear for the pill, shrinks to 12px whatever the page sets, since questions.html sizes the frame
+// to the page's height.
+(function () {
+  const esc = (t) => String(t ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+
+  const takeAt = (keys, current, step) => {
+    const n = keys.length;
+    return keys[((Math.max(0, keys.indexOf(current)) + step) % n + n) % n];
+  };
+  const startTake = (keys, wanted, initial) => (keys.includes(wanted) ? wanted : keys.includes(initial) ? initial : keys[0]);
+
+  // The owner's current pick is the latest answer that chose an option; a note-only answer keeps the earlier pick.
+  const pickedChoice = (question) => [...(question?.answers || [])].reverse().find((a) => a.choice)?.choice ?? null;
+  // none: no question, or the take is not one of its options. pick: nothing picked yet. picked: this take is the
+  // owner's pick. change: another take is.
+  function pickState(question, take) {
+    if (!question) return { kind: 'none' };
+    const option = (question.options || []).find((o) => o.id === take);
+    const picked = pickedChoice(question);
+    if (!option) return { kind: 'none', picked };
+    if (!picked) return { kind: 'pick', option };
+    return { kind: picked === take ? 'picked' : 'change', option, picked };
+  }
+  // Matches ui-questions.js choiceLabel for a single-choice question.
+  const answerLabel = (option) => `${/^[A-Z][0-9]?$/i.test(option.id) ? `${option.id}. ` : ''}${option.label}`;
+  const questionUrl = (q) => (/^prototype-[\w-]+\.html(?:[?#]|$)/.test(q.url || '') ? q.url : `questions.html#${encodeURIComponent(q.id)}`);
+  // questions.html keeps each question's unsent {choice, note} under this key; a pick sent here takes its note and clears it.
+  const draftKey = (qid) => 'qdraft:' + qid;
+  const readDraft = (qid) => { try { return JSON.parse(localStorage.getItem(draftKey(qid)) || '{}'); } catch { return {}; } };
+  // In place of this page: framed in the app shell, the shell shows the URL's view in place (board/public/shell.js
+  // AppShell.open); alone, or for a URL that isn't a view, the page loads it.
+  function replaceWith(url) {
+    let app = null;
+    try { app = window.top !== window ? window.top.AppShell : null; } catch { app = null; }
+    if (!app?.open?.(String(url), { replace: true })) location.replace(url);
+  }
+
+  // Prototype pages need only claude.js and this switcher. In the shell, its BoardUI also owns the board's notice.
+  let questionsUI = null;
+  const sharedQuestions = (site) => (questionsUI ||= (async () => {
+    try { if (window.top !== window && window.top.BoardUI?.nextQuestion) return window.top.BoardUI; } catch {}
+    for (const [file, key] of [['ui.js', 'esc'], ['ui-links.js', 'linkText'], ['ui-questions.js', 'nextQuestion']]) {
+      if (globalThis.BoardUI?.[key]) continue;
+      await new Promise((resolve, reject) => {
+        const script = document.createElement('script');
+        script.src = site.url(file);
+        script.onload = resolve;
+        script.onerror = reject;
+        document.head.append(script);
+      });
+    }
+    return globalThis.BoardUI;
+  })().catch((e) => { questionsUI = null; throw e; }));
+
+  function pillHtml({ name, pick = { kind: 'none' }, busy = false }) {
+    const control = pick.kind === 'picked' ? '<span class="ps-picked">Picked</span>'
+      : pick.kind === 'pick' || pick.kind === 'change'
+        ? `<button type="button" class="ps-pick" data-ps="pick"${busy ? ' disabled' : ''}>${busy ? 'Sending…' : pick.kind === 'pick' ? 'Pick this' : 'Change pick'}</button>`
+        : '';
+    return `<button type="button" data-ps="prev" aria-label="Previous take">‹</button><span class="ps-name" title="${esc(name)}">${esc(name)}</span><button type="button" data-ps="next" aria-label="Next take">›</button>${control}`;
+  }
+
+  const CSS = `
+.ps-switch { position:fixed; left:16px; right:16px; bottom:calc(var(--app-bottom, 0px) + 14px + env(safe-area-inset-bottom)); z-index:30;
+  display:flex; flex-direction:column; align-items:center; gap:6px; pointer-events:none; }
+.ps-switch > * { pointer-events:auto; max-width:100%; min-width:0; box-sizing:border-box; }
+.ps-switch .pill, .ps-pill { display:flex; align-items:center; gap:2px; background:#000d; border:1px solid #fff3; border-radius:999px; padding:4px;
+  -webkit-backdrop-filter:blur(12px); backdrop-filter:blur(12px); font:600 13px -apple-system, system-ui, sans-serif; }
+.ps-switch .pill button, .ps-pill button { color:#fff; background:transparent; border:0; border-radius:999px; padding:7px 11px; font:inherit; white-space:nowrap; cursor:pointer; }
+.ps-pill button { flex-shrink:0; min-width:44px; min-height:44px; }
+.ps-switch .pill button.on { background:#fff; color:#000; }
+.ps-name { flex:0 1 auto; padding:7px 6px; color:#fff; white-space:nowrap; min-width:0; text-align:center; overflow:hidden; text-overflow:ellipsis; }
+.ps-pill .ps-pick { background:#fff; color:#000; margin-left:2px; }
+.ps-pill .ps-pick:disabled { opacity:.6; cursor:default; }
+.ps-switch .ps-text { width:min(420px, 100%); resize:none; border-radius:12px; border:1px solid #fff3; background:#000d; color:#fff;
+  padding:7px 10px; font:400 14px -apple-system, system-ui, sans-serif; -webkit-backdrop-filter:blur(12px); backdrop-filter:blur(12px); }
+.ps-switch .ps-text::placeholder { color:#fffa; }
+.ps-switch .ps-text[hidden] { display:none; }
+.ps-picked { margin-left:2px; padding:7px 11px; border-radius:999px; color:#fff; background:#1f9d55; white-space:nowrap; }
+.ps-note { background:#000d; color:#fff; border-radius:8px; padding:5px 10px; font:500 12px -apple-system, system-ui, sans-serif; text-align:center; }
+.ps-note[hidden] { display:none; }
+.ps-embed header.top { display:none; }
+.ps-embed main { padding-bottom:12px !important; }`;
+
+  const typing = (el) => Boolean(el?.closest?.('input, select, textarea, [contenteditable]:not([contenteditable="false"])'));
+
+  function mount({ takes, initial, render, above = null }) {
+    const keys = Object.keys(takes);
+    const params = new URLSearchParams(location.search);
+    const qid = params.get('q');
+    const site = globalThis.ClaudeSite;
+    if (!document.getElementById('ps-style')) document.head.insertAdjacentHTML('beforeend', `<style id="ps-style">${CSS}</style>`);
+    if (params.has('take')) {
+      let only = startTake(keys, params.get('take'), initial);
+      document.documentElement.classList.add('ps-embed');
+      render(only);
+      const embedded = {
+        takes: keys,
+        get take() { return only; },
+        go(next) {
+          if (!keys.includes(next) || next === only) return;
+          only = next;
+          const u = new URL(location.href); u.searchParams.set('take', only); history.replaceState(history.state, '', u);
+          render(only);
+        },
+      };
+      return (globalThis.PrototypeSwitcher.current = embedded);
+    }
+    let take = startTake(keys, params.get('variant'), initial);
+    let question = null;
+    let topics = [];
+    // A push opened this page (board/store.mjs pushUrl). Read once and dropped from the URL, so a pick made here or a
+    // reload stays on the page; only the first load sends an already-picked question on to its card's thread.
+    let fromPush = params.get('from') === 'push';
+    if (fromPush) { const u = new URL(location.href); u.searchParams.delete('from'); history.replaceState(null, '', u); }
+
+    const box = document.createElement('div');
+    box.className = 'ps-switch';
+    box.innerHTML = '<div class="ps-note" role="status" hidden></div><textarea class="ps-text" rows="2" placeholder="Note with your pick (optional)" aria-label="Note with your pick" hidden></textarea><div class="ps-pill"></div>';
+    if (above) box.prepend(above);
+    document.body.append(box);
+    const pill = box.querySelector('.ps-pill');
+    const noteEl = box.querySelector('.ps-note');
+    const text = box.querySelector('.ps-text');
+    let busy = false;
+
+    const note = (text) => { noteEl.textContent = text || ''; noteEl.hidden = !text; };
+    function paint() {
+      const state = pickState(question, take);
+      pill.innerHTML = pillHtml({ name: takes[take], pick: state, busy });
+      text.hidden = !(state.kind === 'pick' || state.kind === 'change');
+    }
+    function go(next) {
+      take = next;
+      const u = new URL(location.href); u.searchParams.set('variant', take); history.replaceState(null, '', u);
+      note('');
+      paint();
+      render(take);
+    }
+
+    async function load() {
+      if (!qid || !site) return;
+      let board = null;
+      try {
+        board = await (await fetch(site.url('api/board'), { cache: 'no-store' })).json();
+        question = (board.owner || []).find((q) => q.id === qid) || null;
+        topics = board.ownerTopics || [];
+        if (!question) note('This prototype’s question is gone, so there is nothing to pick.');
+      } catch { /* keep the last question shown */ }
+      if (fromPush && pickedChoice(question)) {
+        const card = /^item:(.+)$/.exec(question.topic || '')?.[1];
+        replaceWith(site.url(card ? `#item=${encodeURIComponent(card)}&reply` : 'questions.html'));
+        return;
+      }
+      if (question && !text.value) text.value = readDraft(qid).note || '';
+      fromPush = false;
+      paint();
+      return board;
+    }
+
+    async function pick() {
+      const state = pickState(question, take);
+      if (busy || !(state.kind === 'pick' || state.kind === 'change')) return;
+      busy = true; paint();
+      const answered = question;
+      let ui, pills, name;
+      try {
+        ui = await sharedQuestions(site);
+        pills = ui.topicRow(topics, answered.topic).pills;
+        const topic = topics.find((t) => t.id === answered.topic);
+        name = topic ? ui.topicName(topic) : '';
+        await site.send('owner-answer', { id: answered.id, question: answered.question, choice: state.option.id, label: answerLabel(state.option), note: text.value.trim() });
+      } catch { busy = false; paint(); note('Could not send. Is the host awake?'); return; }
+      try { localStorage.removeItem(draftKey(qid)); } catch { /* nothing kept */ }
+      text.value = '';
+      busy = false;
+      note('Sent. Claude replies on the card.');
+      const board = await load();
+      const next = ui.nextQuestion(board?.owner || [], pills, answered);
+      if (next) {
+        const u = new URL(site.url(questionUrl(next)), location.href);
+        if (globalThis.PageBack?.pushed) u.searchParams.set('from', 'push');
+        replaceWith(u);
+      } else {
+        const route = new URL(site.url(''), location.href).pathname.replace(/^\/+|\/+$/g, '');
+        ui.sentNotice.put(route, `Sent 1 answer${name ? ` to ${name}` : ''}.`);
+        replaceWith(site.url('./'));
+      }
+    }
+    text.addEventListener('keydown', (e) => {
+      if (e.key !== 'Enter' || !(e.metaKey || e.ctrlKey) || e.isComposing) return;
+      e.preventDefault();
+      pick();
+    });
+
+    pill.addEventListener('click', (e) => {
+      const act = e.target.closest('[data-ps]')?.dataset.ps;
+      if (act === 'prev') go(takeAt(keys, take, -1));
+      else if (act === 'next') go(takeAt(keys, take, 1));
+      else if (act === 'pick') pick();
+    });
+    document.addEventListener('keydown', (e) => {
+      if (typing(e.target) || e.metaKey || e.ctrlKey || e.altKey) return;
+      if (e.key === 'ArrowLeft') go(takeAt(keys, take, -1));
+      else if (e.key === 'ArrowRight') go(takeAt(keys, take, 1));
+    });
+    document.addEventListener('visibilitychange', () => { if (!document.hidden) load(); });
+
+    go(take);
+    load();
+    return (globalThis.PrototypeSwitcher.current = { takes: keys, get take() { return take; }, go });
+  }
+
+  globalThis.PrototypeSwitcher = { takeAt, startTake, pickedChoice, pickState, answerLabel, pillHtml, mount };
+})();

package/board/public/prototype.html

@@ -0,0 +1,55 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<title>{{prototypeTitle}}</title>
+<link rel="stylesheet" href="colors.css">
+<link rel="stylesheet" href="style.css">
+<link rel="stylesheet" href="hub.css">
+<link rel="stylesheet" href="sidebar.css">
+<style>
+  /* The one page every recorded prototype is (board/server.mjs fills the {{…}} slots; prototype-kit.js documents what a
+     take gets). main keeps room below the stage for the take pill and its note. */
+  main.proto-main { max-width: none; padding-left: 0; padding-right: 0; padding-bottom: calc(150px + var(--app-bottom, 0px) + env(safe-area-inset-bottom)); }
+  /* kit.hub() is a whole page with its own gutter and header, so it goes edge to edge. */
+  main.proto-main:has(> #stage > .kit-hub) { padding-top: 0; }
+  /* contain and the transform make the stage the containing block of everything in it, position: fixed included, and
+     clip its paint, so a take can't cover the header, the pill or the app shell around the page. */
+  #stage { position: relative; max-width: 1180px; min-width: 0; margin: 0 auto; contain: layout paint; transform: translateZ(0); isolation: isolate; overflow-x: clip; padding: 0 16px; }
+  #stage:has(> .kit-hub) { padding: 0; }
+  #stage .top { position: static; }
+  #stage .hub-view main { padding-bottom: 16px; }
+  .kit-missing { margin: 0; padding: 16px; border: 1px dashed var(--line); border-radius: 12px; color: var(--muted); overflow-wrap: anywhere; }
+  #protoToast { position: fixed; z-index: 40; left: 50%; top: calc(64px + env(safe-area-inset-top)); transform: translateX(-50%); max-width: calc(100vw - 32px); }
+  #protoToast[hidden] { display: none; }
+  @media (max-width: 899px) { #protoToast { top: max(12px, env(safe-area-inset-top)); } }
+
+  #stage .kit-sidebar.sidebar { position: relative; inset: auto; z-index: auto; transform: none; visibility: visible; transition: none;
+    width: min(320px, 100%); height: 640px; margin: 0 auto; padding: 0 8px; border: 1px solid var(--line); border-radius: 14px; }
+  #stage .kit-sidebar.sidebar:not(.kit-head) > header.top { display: none; }
+  @media (min-width: 900px) { #stage .kit-sidebar.sidebar { width: 272px; } }
+  #stage .kit-sheet-strip { padding: 32px 0 0; border-radius: 12px; background: rgba(0,0,0,.35); overflow: hidden; }
+  #stage .kit-sheet { max-width: 560px; margin: 0 auto; border: 1px solid var(--line); border-bottom: 0; border-radius: 16px 16px 0 0; background: var(--panel); color: var(--text); box-shadow: 0 -8px 30px rgba(0,0,0,.18); }
+  #stage .kit-sheet .sheet-head { padding: 10px 16px 0; }
+  #stage .kit-sheet-body { padding: 6px 16px 16px; }
+</style>
+</head>
+<body>
+{{prototypeHeader}}
+<main class="proto-main"><div id="stage"></div></main>
+<div class="toast" id="protoToast" role="status" hidden></div>
+<script id="prototypeData" type="application/json">{{prototypeData}}</script>
+<script src="claude.js"></script>
+<script src="ui.js"></script>
+<script src="ui-links.js"></script>
+<script src="ui-enums.js"></script>
+<script src="ui-cards.js"></script>
+<script src="ui-page-header.js"></script>
+<script src="ui-sidebar.js"></script>
+<script src="ui-hub.js"></script>
+<script src="prototype-switcher.js"></script>
+<script src="prototype-kit.js"></script>
+<script>PrototypeKit.start(JSON.parse(document.getElementById('prototypeData').textContent));</script>
+</body>
+</html>

package/board/public/router.js

@@ -0,0 +1,226 @@
+// The app shell's router (docs/adr/0055-one-app-for-the-whole-hub.md): every URL on the hub names a view, and a view
+// names its URL, so a push link, a reload and a shared link all land on the same view. viewOf and urlOf are pure;
+// ui.test.mjs runs them in node:vm. listen() catches clicks on links to a view the shell mounts, and back and forward.
+// A view is {kind, …}:
+//   start                       `/`, which the shell turns into the last board
+//   board {route, hash}         /<route>/, hash such as #item=<key>&reply
+//   settings {route}            /<route>/settings.html, a request to open the modal over that board
+//   questions {route, id}       /<route>/questions.html#<id>
+//   notes {route, item | wave}  /<route>/notes.html?item=<key> or ?wave=<lineup slug>, and plan.html, which the board
+//                               redirects there
+//   hub {hash, w}              /_hub/ with a settings modal named by hash; legacy /_hub/settings and
+//                               /_hub/settings/polling?w=<HH:MM> open the same modals (ADR 0075)
+//   frame {route, url}          any other page under a route, a folder or an .html file: other sites, prototypes and
+//                               every other board page, shown in a frame
+// Any other URL, such as an image or another origin, is no view (null) and loads as itself.
+// A push's from=push mark (entryOf) is no part of the view, so a push link reads as the view its page shows.
+globalThis.AppRouter = (function () {
+  // The kinds the shell mounts in place; a link to any other kind loads its page.
+  const MOUNTED = new Set(['board', 'settings', 'questions', 'notes', 'hub', 'frame']);
+  // A page's path under its route. hub/shell.mjs pageOf takes the same rule, so the hub answers a page load of every view
+  // this mounts with the shell; hub/shell.test.mjs checks the two agree.
+  const isPagePath = (rest) => rest === '' || rest.endsWith('/') || /\.html?$/.test(rest);
+
+  // href against base; boards, the set of board routes. null for another origin.
+  function viewOf(href, { boards = new Set(), base = globalThis.location?.href } = {}) {
+    let u;
+    try { u = new URL(href, base); } catch { return null; }
+    if (base && u.origin !== new URL(base).origin) return null;
+    const p = u.pathname;
+    if (p === '/') return { kind: 'start' };
+    if (['/_hub/', '/_hub/settings', '/_hub/settings/polling'].includes(p)) {
+      const hash = p === '/_hub/settings/polling' ? '#polling' : u.hash || (p === '/_hub/settings' ? '#notifications' : '');
+      return { kind: 'hub', ...(hash ? { hash } : {}), ...(hash === '#polling' && u.searchParams.get('w') ? { w: u.searchParams.get('w') } : {}) };
+    }
+    const m = /^\/([^/]+)\/(.*)$/.exec(p);
+    let route = null;
+    try { route = m && decodeURIComponent(m[1]); } catch { return null; }
+    if (!route || route === '_hub' || !isPagePath(m[2])) return null;
+    const frame = { kind: 'frame', route, url: p + u.search + u.hash };
+    if (!boards.has(route)) return frame;
+    const page = m[2];
+    if (page === '') return { kind: 'board', route, hash: u.hash };
+    if (page === 'settings.html') return { kind: 'settings', route };
+    if (page === 'questions.html') {
+      let id = null;
+      try { id = u.hash.length > 1 ? decodeURIComponent(u.hash.slice(1)) : null; } catch { id = u.hash.slice(1); }
+      return { kind: 'questions', route, id };
+    }
+    if (page === 'notes.html' || page === 'plan.html') {
+      return u.searchParams.has('wave') ? { kind: 'notes', route, wave: u.searchParams.get('wave') } : { kind: 'notes', route, item: u.searchParams.get('item') };
+    }
+    return frame;
+  }
+
+  function urlOf(view) {
+    const r = view.route !== undefined ? `/${encodeURIComponent(view.route)}/` : '';
+    switch (view.kind) {
+      case 'start': return '/';
+      case 'board': return r + (view.hash || '');
+      case 'settings': return `${r}settings.html`;
+      case 'questions': return `${r}questions.html${view.id ? `#${encodeURIComponent(view.id)}` : ''}`;
+      case 'notes': return `${r}notes.html${view.wave ? `?wave=${encodeURIComponent(view.wave)}` : view.item ? `?item=${encodeURIComponent(view.item)}` : ''}`;
+      case 'hub': return `/_hub/${view.w ? `?w=${encodeURIComponent(view.w)}` : ''}${view.hash || ''}`;
+      default: return view.url;
+    }
+  }
+
+  const mounted = (view) => Boolean(view && MOUNTED.has(view.kind));
+
+  // A push to a page other than the board carries from=push (board/store.mjs pushUrl). The router keeps that mark in
+  // the entry's history.state as pushed, which a reload keeps too, and drops it from the URL.
+  // → {href without from=push, pushed}
+  function entryOf(href) {
+    const u = new URL(href, globalThis.location?.href);
+    const pushed = u.searchParams.get('from') === 'push';
+    if (pushed) u.searchParams.delete('from');
+    return { href: u.href, pushed };
+  }
+
+  // The page tree (docs/adr/0058-back-follows-the-page-tree.md): a board, its Waiting on you, and a prototype page tied
+  // to one of its questions by ?q=, framed. levelOf → 0, 1 or 2 down the tree, or null for a view outside it.
+  function questionOf(view, boards) {
+    if (view?.kind !== 'frame' || !boards.has(view.route)) return null;
+    const u = new URL(view.url, 'http://hub');
+    return /^\/[^/]+\/prototype-[\w-]+\.html$/.test(u.pathname) ? u.searchParams.get('q') || null : null;
+  }
+  function levelOf(view, { boards = new Set() } = {}) {
+    if (view?.kind === 'board') return 0;
+    if (view?.kind === 'questions') return 1;
+    return questionOf(view, boards) ? 2 : null;
+  }
+  // → the views above view in the tree, its board first. card: the card whose thread the owner left the board from,
+  // which the board keeps open.
+  function parentsOf(view, { boards = new Set(), card = null } = {}) {
+    const q = questionOf(view, boards);
+    if (!q && view?.kind !== 'questions') return [];
+    const board = { kind: 'board', route: view.route, hash: card ? `#item=${encodeURIComponent(card)}` : '' };
+    return q ? [board, { kind: 'questions', route: view.route, id: q }] : [board];
+  }
+
+  // Each history entry carries {idx}, its distance from the shell's first entry, pushed when a push opened it, and on a
+  // view in the page tree up, how many of the entries under it are its parents. Every way into the tree writes the
+  // parents it lacks under it, so a back arrow there (up), the browser's back and a swipe all go up one level. Any other
+  // back arrow (a.back) goes one step back by idx and pushed (ui-page-header.js backStep), else follows its href.
+  // go(view, href, how, from) shows a view: how is 'push' for a link, a push tap or the start, 'pop' for back and
+  // forward; from.card is the open card a link was tapped in. It answers false, or a promise of false, when the view
+  // stays, such as when the owner keeps an unsaved edit, and a refused pop then returns to the entry it left.
+  // boards() → the board routes now.
+  // → {push(href, from), replace(href), up()}: push and replace write an entry for a view go is showing; replace answers
+  // 'up' when it went back to a parent instead, which then takes href, and go shows it on that pop.
+  function listen({ boards, go }) {
+    const b = () => ({ boards: boards() });
+    const mark = (pushed) => (pushed ? { pushed: true } : {});
+    let idx = Number.isInteger(history.state?.idx) ? history.state.idx : 0;
+    let landing = null;
+    const put = (how, href, state) => {
+      if (how === 'push') idx++;
+      history[how === 'push' ? 'pushState' : 'replaceState']({ idx, ...state }, '', href);
+    };
+    // Pushes parents, then href. up: the current entry's own up when the first parent sits on it, else -1, so a board
+    // pushed first carries none.
+    const climb = (parents, href, pushed, up) => {
+      for (const p of parents) put('push', urlOf(p), up++ >= 0 ? { up } : {});
+      put('push', href, { ...(up >= 0 ? { up: up + 1 } : {}), ...mark(pushed) });
+    };
+
+    const first = entryOf(location.href);
+    const start = viewOf(first.href, b());
+    const depth = levelOf(start, b());
+    if (depth && !(history.state?.up >= depth)) {
+      const parents = parentsOf(start, b());
+      put('replace', urlOf(parents[0]), {});
+      climb(parents.slice(1), first.href, first.pushed, 0);
+    } else history.replaceState({ ...(history.state || {}), idx, ...mark(first.pushed) }, '', first.href);
+
+    function write(how, href, { card = null } = {}) {
+      const { href: url, pushed } = entryOf(href);
+      if (how === 'push' && url === location.href) return;
+      const view = viewOf(url, b());
+      const here = viewOf(location.href, b());
+      const level = levelOf(view, b());
+      const at = here && view && here.route === view.route ? levelOf(here, b()) : null;
+      const below = history.state?.up || 0;
+      const keep = level !== null && level === at && below ? { up: below } : {};
+      if (how === 'replace') {
+        if (level !== null && at !== null && level < at && at - level <= below) {
+          landing = href;
+          history.go(level - at);
+          return 'up';
+        }
+        put('replace', url, { ...keep, ...mark(pushed) });
+        return;
+      }
+      // Another question on Waiting on you takes this one's place, so back still goes to the board.
+      if (level === 1 && at === 1) { put('replace', url, { ...keep, ...mark(pushed) }); return; }
+      const parents = parentsOf(view, { ...b(), card });
+      if (level !== null && at !== null && at < level) {
+        history.replaceState(history.state, '', urlOf(parents[at]));
+        climb(parents.slice(at + 1), url, pushed, below);
+      } else climb(parents, url, pushed, -1);
+    }
+
+    // A back arrow's tap on a view in the tree: back when its parent is the entry under it, else on to the parent.
+    // → false for a view outside the tree.
+    function up() {
+      const parents = parentsOf(viewOf(location.href, b()), b());
+      if (!parents.length) return false;
+      if (history.state?.up > 0) history.back();
+      else go(parents.at(-1), new URL(urlOf(parents.at(-1)), location.href).href, 'push');
+      return true;
+    }
+
+    // Listens after sidebar.js, so a tap the drawer took (its logo, ✕) is already defaultPrevented.
+    document.addEventListener('click', (e) => {
+      if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+      const a = e.target.closest?.('a[href]');
+      if (!a || (a.target && a.target !== '_self') || a.hasAttribute('download')) return;
+      if (a.classList.contains('back')) {
+        if (up()) { e.preventDefault(); return; }
+        if (BoardUI.backStep({ pushed: history.state?.pushed === true, href: location.href, idx: history.state?.idx }) === 'back') {
+          e.preventDefault();
+          history.back();
+          return;
+        }
+      }
+      const url = new URL(a.href, location.href);
+      const view = viewOf(url.href, { boards: boards() });
+      if (!mounted(view)) return;
+      // A link to another card on this board, or another question on Waiting on you, only moves the hash, which the
+      // view follows itself. On Waiting on you it takes this entry's place, so back still goes to the board.
+      if (url.pathname === location.pathname && url.search === location.search && url.hash && url.hash !== location.hash) {
+        if (view.kind === 'hub') { e.preventDefault(); go(view, url.href, 'push'); return; }
+        if (view.kind !== 'questions') return;
+        e.preventDefault();
+        write('replace', url.href);
+        dispatchEvent(new HashChangeEvent('hashchange'));
+        return;
+      }
+      e.preventDefault();
+      go(view, url.href, 'push', { card: a.closest?.('details.item[open][data-key]')?.dataset.key || null });
+    });
+    let restoring = false;
+    addEventListener('popstate', (e) => {
+      const was = idx;
+      if (Number.isInteger(e.state?.idx)) idx = e.state.idx;
+      if (landing) {
+        const to = entryOf(landing);
+        landing = null;
+        history.replaceState({ ...(e.state || {}), ...mark(to.pushed) }, '', to.href);
+      }
+      if (restoring) { restoring = false; return; }
+      const view = viewOf(location.href, { boards: boards() });
+      if (!mounted(view)) { location.reload(); return; }
+      Promise.resolve(go(view, location.href, 'pop')).then((shown) => {
+        if (shown !== false || was === idx) return;
+        restoring = true;
+        history.go(was - idx);
+      });
+    });
+    // A hash link adds an entry with no state of its own.
+    addEventListener('hashchange', () => { if (!Number.isInteger(history.state?.idx)) history.replaceState({ idx: ++idx }, ''); });
+    return { push: (href, from) => write('push', href, from), replace: (href) => write('replace', href), up };
+  }
+
+  return { viewOf, urlOf, mounted, entryOf, listen };
+})();

package/board/public/rules-editor.js

@@ -0,0 +1,127 @@
+// The rules editor on Board Settings and on the Hub page
+// (docs/adr/0039-rules-live-on-settings-at-hub-and-board-level.md). Edits stay on the page until Save, as the
+// reviewers list does; Save hands {rules: [{id?, text}], base: [the ids it loaded]} to the page's save(), whose
+// server merges it (hub/rules.mjs applyRules). It brings its own CSS, colours from colors.css only, and takes the page's
+// button classes. rows, payload, dirty and render are pure, for ui.test.mjs; mount touches the DOM.
+(function () {
+  const esc = (s) => String(s ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+  const one = (t) => String(t ?? '').replace(/\s+/g, ' ').trim();
+
+  // A row is a saved rule (orig is its saved text) or a new one (orig null); gone marks a staged removal.
+  const rows = (rules) => (rules || []).map((r) => ({ key: r.id, id: r.id, text: r.text, by: r.by, orig: r.text, gone: false }));
+  const payload = (list) => ({
+    rules: list.filter((r) => !r.gone).map((r) => (r.id ? { id: r.id, text: r.text } : { text: r.text })),
+    base: list.filter((r) => r.id).map((r) => r.id),
+  });
+  const dirty = (list) => list.some((r) => r.gone || r.orig === null || r.text !== r.orig);
+
+  // editing: the key of the row open for editing. buttons: the page's {primary, quiet, icon} classes; icon is ✕'s.
+  function render(list, { readOnly = false, editing = null, buttons = {}, empty = 'No rules yet.' } = {}) {
+    if (!list.length) return `<p class="muted small rule-empty">${esc(empty)}</p>`;
+    const quiet = esc(buttons.quiet || '');
+    return list.map((r) => {
+      if (!readOnly && r.key === editing) {
+        return `<div class="rule editing" data-key="${esc(r.key)}"><textarea class="rule-input" rows="3" aria-label="Rule text">${esc(r.text)}</textarea>
+          <div class="rule-edit-actions"><button type="button" class="${quiet}" data-act="cancel">Cancel</button><button type="button" class="${esc(buttons.primary || '')}" data-act="done">Done</button></div></div>`;
+      }
+      const state = r.gone ? 'gone' : r.orig === null ? 'new' : r.text !== r.orig ? 'edited' : '';
+      const meta = [r.by === 'claude' ? '<span class="rule-by">Added by Claude</span>' : '', state && !readOnly ? `<span>${state === 'gone' ? 'removed' : state}</span>` : ''].join('');
+      const actions = readOnly ? '' : `<div class="rule-actions">${r.gone ? '' : `<button type="button" class="${quiet}" data-act="edit" aria-label="Edit this rule">Edit</button>`}
+        <button type="button" class="${esc(buttons.icon ?? buttons.quiet ?? '')}" data-act="${r.gone ? 'undo' : 'remove'}" aria-label="${r.gone ? 'Keep' : 'Remove'} this rule">${r.gone ? 'Undo' : '✕'}</button></div>`;
+      return `<div class="rule${state ? ` ${state}` : ''}" data-key="${esc(r.key)}"><div class="rule-body"><div class="rule-text">${esc(r.text)}</div>${meta ? `<div class="rule-meta">${meta}</div>` : ''}</div>${actions}</div>`;
+    }).join('');
+  }
+
+  const CSS = `.rules-editor .rule { display:flex; align-items:flex-start; gap:8px; padding:9px 10px; margin:6px 0; border:1px solid var(--line); border-radius:9px; background:var(--panel); }
+.rules-editor .rule.new { border-color:var(--accent); }
+.rules-editor .rule.gone .rule-text { opacity:.5; text-decoration:line-through; }
+.rules-editor .rule.editing { flex-direction:column; align-items:stretch; }
+.rules-editor .rule-body { flex:1; min-width:0; }
+.rules-editor .rule-text { overflow-wrap:anywhere; }
+.rules-editor .rule-meta { display:flex; flex-wrap:wrap; gap:6px; margin-top:4px; font-size:12px; color:var(--muted); }
+.rules-editor .rule-by { padding:0 6px; border-radius:6px; background:var(--chip); color:var(--muted); }
+.rules-editor .rule-actions { flex:none; display:flex; gap:4px; }
+.rules-editor textarea { box-sizing:border-box; width:100%; min-width:0; resize:vertical; font:inherit; font-size:16px; color:var(--text); background:var(--panel); border:1px solid var(--line); border-radius:8px; padding:6px 8px; }
+.rules-editor .rule-add { display:flex; align-items:flex-end; gap:6px; margin-top:8px; }
+.rules-editor .rule-add textarea { flex:1; }
+.rules-editor .rule-edit-actions, .rules-editor .rule-save { display:flex; align-items:center; justify-content:flex-end; gap:8px; margin-top:8px; }
+.rules-editor .rule-save .rule-status { flex:1; min-width:0; font-size:12px; color:var(--muted); }`;
+
+  // opts: {rules, readOnly, buttons, empty, placeholder, save(payload) → Promise<{rules, message}>}. Sets data-dirty on
+  // el while anything is unsaved, so a page that reloads itself can wait.
+  function mount(el, opts) {
+    if (!document.getElementById('rules-editor-css')) document.head.insertAdjacentHTML('beforeend', `<style id="rules-editor-css">${CSS}</style>`);
+    const b = opts.buttons || {};
+    let list = rows(opts.rules);
+    let editing = null;
+    let added = 0;
+    el.classList.add('rules-editor');
+    el.innerHTML = `<div class="rule-list"></div>${opts.readOnly ? '' : `<form class="rule-add"><textarea rows="2" placeholder="${esc(opts.placeholder || 'Add a rule')}" aria-label="New rule"></textarea><button type="submit" class="${esc(b.quiet || '')}">Add</button></form>
+      <div class="rule-save"><span class="rule-status" role="status"></span><button type="button" class="${esc(b.primary || '')}" data-act="save" disabled>Save</button></div>`}`;
+    const listEl = el.querySelector('.rule-list');
+    const addBox = el.querySelector('.rule-add textarea');
+    const saveBtn = el.querySelector('[data-act="save"]');
+    const status = el.querySelector('.rule-status');
+    function mark() {
+      const unsaved = dirty(list);
+      saveBtn.disabled = !unsaved || editing !== null;
+      if (unsaved || editing !== null || addBox.value.trim()) el.dataset.dirty = ''; else delete el.dataset.dirty;
+    }
+    function draw() {
+      listEl.innerHTML = render(list, { readOnly: opts.readOnly, editing, buttons: b, empty: opts.empty });
+      if (opts.readOnly) return;
+      mark();
+      const input = listEl.querySelector('.rule-input');
+      if (input) { input.focus(); input.setSelectionRange(input.value.length, input.value.length); }
+    }
+    draw();
+    if (opts.readOnly) return { set(rules) { list = rows(rules); draw(); } };
+    listEl.addEventListener('keydown', (ev) => {
+      if (ev.key === 'Enter' && !ev.shiftKey && !ev.isComposing && ev.target.matches('.rule-input')) { ev.preventDefault(); listEl.querySelector('[data-act="done"]').click(); }
+    });
+    listEl.addEventListener('click', (ev) => {
+      const btn = ev.target.closest('button[data-act]');
+      const row = btn && list.find((r) => r.key === btn.closest('.rule').dataset.key);
+      if (!row) return;
+      const act = btn.dataset.act;
+      if (act === 'edit') editing = row.key;
+      else if (act === 'cancel') editing = null;
+      else if (act === 'done') {
+        const text = one(listEl.querySelector('.rule-input').value);
+        if (!text) return;
+        row.text = text;
+        editing = null;
+      } else if (act === 'remove') {
+        if (row.orig === null) list = list.filter((r) => r !== row); else row.gone = true;
+      } else if (act === 'undo') row.gone = false;
+      status.textContent = '';
+      draw();
+    });
+    const add = () => {
+      const text = one(addBox.value);
+      if (!text) return;
+      list.push({ key: `new-${++added}`, id: null, text, by: 'owner', orig: null, gone: false });
+      addBox.value = '';
+      status.textContent = '';
+      draw();
+    };
+    el.querySelector('.rule-add').addEventListener('submit', (ev) => { ev.preventDefault(); add(); });
+    // A rule is one line, so Enter adds it.
+    addBox.addEventListener('keydown', (ev) => { if (ev.key === 'Enter' && !ev.shiftKey && !ev.isComposing) { ev.preventDefault(); add(); } });
+    addBox.addEventListener('input', mark);
+    saveBtn.addEventListener('click', async () => {
+      saveBtn.disabled = true;
+      status.textContent = 'Saving…';
+      try {
+        const r = await opts.save(payload(list));
+        list = rows(r.rules);
+        editing = null;
+        status.textContent = r.message || 'Saved.';
+      } catch (e) { status.textContent = (e && e.message) || 'Could not save. Is the host awake?'; }
+      draw();
+    });
+    return { set(rules) { list = rows(rules); editing = null; draw(); } };
+  }
+
+  globalThis.RulesEditor = { rows, payload, dirty, render, mount, CSS };
+})();