rvlib-shipkit 1.1.1 → 1.3.0

package/src/serve/hub-app/hash-route.ts

@@ -1,5 +1,5 @@
 // THE ADDRESS of what is on screen, both ways, and nothing else. Pure on
-// purpose: the page's selection rules are worth pinning, and HubSt cannot be
+// purpose: the page's selection rules are worth pinning, and RepoSt cannot be
 // instantiated without a browser.
 //
 // The media forms are older than the rest and stay byte for byte what they
@@ -20,9 +20,11 @@ export type HashSel =
     /** where the test checks' time goes: every one of them (check null), or
      *  one test check (`test`, `test:<unit>`) */
     | { t: 'tests'; check: string | null }
+    /** what administers the repo: archive, reload its hub, keep it active */
+    | { t: 'admin' }
 
 export type ParsedHash = {
-    kind: 'asset' | 'cat' | 'col' | 'item' | 'status' | 'tests' | 'none'
+    kind: 'asset' | 'cat' | 'col' | 'item' | 'status' | 'tests' | 'admin' | 'none'
     /** the collection, for an item. null for everything else */
     col: string | null
     id: string
@@ -37,6 +39,7 @@ const CAT = 'cat-'
 /** prefixed, so no asset id can shadow it */
 const STATUS = 'page:status'
 const TESTS = 'page:tests'
+const ADMIN = 'page:admin'
 
 /** what this selection puts in the url. null only for no selection at all,
  *  and then the hash is left alone rather than wiped */
@@ -49,6 +52,7 @@ export function hashFor(sel: HashSel | null): string | null {
         case 'item': return `${ITEM}${sel.col}:${sel.id}`
         case 'status': return STATUS
         case 'tests': return sel.check == null ? TESTS : `${TESTS}:${sel.check}`
+        case 'admin': return ADMIN
     }
 }
 
@@ -57,6 +61,7 @@ export function parseHash(raw: string): ParsedHash {
     if (raw === '') return none
     if (raw === STATUS) return { kind: 'status', col: null, id: '', tools: null }
     if (raw === TESTS) return { kind: 'tests', col: null, id: '', tools: null }
+    if (raw === ADMIN) return { kind: 'admin', col: null, id: '', tools: null }
     // a check id carries colons of its own (`test:rvlib-shipkit`)
     if (raw.startsWith(`${TESTS}:`)) {
         const check = raw.slice(TESTS.length + 1)
@@ -98,6 +103,7 @@ export function selOf(p: ParsedHash): HashSel | null {
         case 'item': return { t: 'item', col: p.col!, id: p.id }
         case 'status': return { t: 'status' }
         case 'tests': return { t: 'tests', check: p.id === '' ? null : p.id }
+        case 'admin': return { t: 'admin' }
     }
 }
 

package/src/serve/hub-app/header-bar.tsx

@@ -1,54 +1,65 @@
-// The header over every page, and the live strip under it. The header is the
-// repo name, one link per core page, and on the right the two runs that are
-// not one check with what is running now. The strip is the one run chart
-// (timeline-chart.tsx) over a rolling window that ends now: folded, a thin
-// bar of the last two minutes; unfolded, the full chart over ten, zoomable.
-// Each fold has ONE height whatever runs, so a run never moves the page.
+// A repo's pieces of the top bar, beside its icon and its name: what runs now
+// and the two runs that are not one check (RepoRun), then on the right its
+// processes, the hub's own trouble and modernize while it is behind
+// (RepoTools), and at the far right end the editor icons (RepoOpeners). On
+// the home they ride in the home strip (home-strip.tsx); a hub of its own
+// draws them in its own header, with its name. The repo's sections are the
+// left pane's (repo-sections.tsx). What runs, drawn, is the dock at the
+// bottom of the page (dock-view.tsx).
 import { observer } from 'mobx-react-lite'
-import { RUNS_ID } from '../../collections/collection-types.ts'
-import { Help } from './help.tsx'
-import { openWikis, WIKIS } from './wikis-view.tsx'
-import type { HubSt } from './hub-st.ts'
-import { byWords, TimelineChart } from './timeline-chart.tsx'
+import { Icon, ICON } from './icons.tsx'
+import type { RepoSt } from './repo-st.ts'
 
-export type CorePage = { id: string; label: string; on: boolean; go: () => void }
-
-/** the pages reached for most, in the order they are reached for. A page this
- *  repo does not have is not a link */
-export function corePages(app: HubSt): CorePage[] {
-    const has = (col: string): boolean => app.cols.colMeta.some((c) => c.id === col)
-    const sel = app.sel
-    const onCol = (col: string): boolean => (sel?.t === 'col' && sel.id === col) || (sel?.t === 'item' && sel.col === col)
-    const out: CorePage[] = []
-    if (has('checks')) out.push({ id: 'checks', label: 'checks', on: onCol('checks'), go: () => app.showCol('checks') })
-    // a page, never a resource: every hub keeps a run record, so it is
-    // always here
-    out.push({ id: 'runs', label: 'runs', on: onCol('runs'), go: () => app.cols.select('runs', RUNS_ID) })
-    if (has('asks')) out.push({ id: 'asks', label: 'asks', on: onCol('asks'), go: () => app.showCol('asks') })
-    const firstCat = app.media.assets[0]?.cat
-    if (firstCat != null) out.push({ id: 'media', label: 'media', on: sel?.t === 'asset' || sel?.t === 'cat', go: () => app.showCat(firstCat) })
-    if (has(WIKIS)) out.push({ id: WIKIS, label: 'wikis', on: onCol(WIKIS), go: () => openWikis(app) })
-    return out
+/** the repo's hub has not answered on the home: its reason and its fix show
+ *  instead of the page. A screen this browser kept shows meanwhile, until
+ *  the machine says the hub is not up */
+export const notUp = (app: RepoSt): boolean => {
+    const m = app.home.machine
+    if (m == null || app.started) return false
+    if (!app.cols.cached) return true
+    return m.fresh && m.worker(app.key)?.status !== 'up'
 }
 
 /** what is running, in one line: the hub's own run first, since it says the
- *  most, else the newest run the record has in flight */
-const RunState = observer(({ app }: { app: HubSt }) => {
+ *  most, else the newest run the record has in flight. Cut to its width, the
+ *  whole line on hover */
+const RunState = observer(({ app }: { app: RepoSt }) => {
     const own = app.checks.strip
     const run = app.live.view?.runs[0]
     const text = own !== '' ? own : run != null ? `${run.label} · ${run.done} of ${run.total}${run.reds > 0 ? ` · ${run.reds} red so far` : ''}` : 'idle'
     const going = app.checks.busy || run != null
     return (
         <span className={`hstate${going ? ' on' : ''}`} title={text}>
-            {going ? <span className="spin" /> : null}
+            {/* the spinner's slot is always there, so the text never moves */}
+            <span className={`spin${going ? '' : ' idle'}`} />
             <span className="htext">{text}</span>
         </span>
     )
 })
 
+export const HEALTH_TITLE = 'run the health pass: every check but the build steps, as shipkit check runs them (creds, probes, rules, contracts)'
+export const GATE_TITLE = 'run the gate: every check shipkit ci runs, the build steps included (lint, typecheck, tests)'
+
+/** the run state, then the two runs, compact: below a width their labels
+ *  give way to their icons, so the bar never wraps */
+export const RepoRun = observer(({ app }: { app: RepoSt }) => {
+    const u = app.checks
+    return (
+        <span className="hrun">
+            <RunState app={app} />
+            <button className="primary hbtn" disabled={u.busy} title={HEALTH_TITLE} aria-label="health pass" onClick={() => void u.run()}>
+                <Icon d={ICON.health} /><span className="lbl">health pass</span>
+            </button>
+            <button className="hbtn" disabled={u.busy} title={GATE_TITLE} aria-label="gate" onClick={() => void u.run(undefined, { gate: true, label: 'the gate' })}>
+                <Icon d={ICON.gate} /><span className="lbl">gate</span>
+            </button>
+        </span>
+    )
+})
+
 /** what is wrong with the hub itself, one chip per problem. Nothing when all
- *  is well: the header states trouble, never health */
-const HubStatus = observer(({ app }: { app: HubSt }) => (
+ *  is well: the bar states trouble, never health */
+const HubStatus = observer(({ app }: { app: RepoSt }) => (
     <>
         {app.cols.hubStatus.map((p) => (
             <span key={p.id} className={`hstatus ${p.severity === 'red' ? 'red' : 'warn'}`} title={p.text}>{p.text}</span>
@@ -56,73 +67,69 @@ const HubStatus = observer(({ app }: { app: HubSt }) => (
     </>
 ))
 
-export const HeaderBar = observer(({ app }: { app: HubSt }) => {
-    const u = app.checks
+/** modernize, while the repo runs an older shipkit than the home */
+const Modernize = observer(({ app }: { app: RepoSt }) => {
+    const m = app.home.machine
+    const behind = m?.data?.behind[app.key]
+    if (m == null || behind == null) return null
+    return <button className="primary hbtn" onClick={() => void m.modernize(app.key)} title={`this repo runs shipkit ${behind}, the home runs ${m.data?.version}`}>modernize {behind} → {m.data?.version}</button>
+})
+
+/** the repo in its editor and in its git client, one icon each, at the far
+ *  right end of the bar. Only on the home: the machine opens them */
+export const RepoOpeners = observer(({ app }: { app: RepoSt }) => {
+    const m = app.home.machine
+    if (m == null) return null
     return (
-        <header className="hdr">
-            <span className="hname">{app.name !== '' ? app.name : 'hub'}</span>
-            <nav className="hnav">
-                {corePages(app).map((p) => (
-                    <button key={p.id} className={p.on ? 'on' : ''} onClick={p.go}>{p.label}</button>
-                ))}
-            </nav>
-            <span className="sp" />
-            <HubStatus app={app} />
-            <RunState app={app} />
-            <button className="primary" disabled={u.busy} onClick={() => void u.run()}>run the health pass</button>
-            <button disabled={u.busy} onClick={() => void u.run(undefined, { gate: true, label: 'the gate' })}>run the gate</button>
-        </header>
+        <>
+            <button className="hicon" title="open in VS Code" aria-label={`open ${app.key} in VS Code`} onClick={() => m.openInCode(app.key)}><Icon d={ICON.vscode} /></button>
+            <button className="hicon" title="open in Fork" aria-label={`open ${app.key} in Fork`} onClick={() => void app.home.activity.openFork(app.key)}><Icon d={ICON.fork} /></button>
+        </>
     )
 })
 
-/** the key that folds and unfolds the strip, printed on its chevron */
-export const LIVE_KEY = 'l'
-
-/** the strip's own row, in px: the one height the folded strip has */
-export const LIVE_ROW_H = 30
-
-/** what the strip is, in the (?) beside its chevron */
-export const LIVE_HELP = "every check shipkit runs, whoever started it: this hub, an agent in a terminal, the daily pass, here and in the other repos. Folded, the last two minutes: a bar grows at the right while its check runs and slides left once it ends, in its verdict colour. Unfolded, the whole record, opened on the last ten minutes: the run bands, the time axis, and over the lanes how many checks ran at once, with the cap dashed and the stretches past it in orange. It follows now: the right edge is the present and the view slides with it. The wheel zooms and a drag pans; leaving the right edge stops the view where it is so a bar can be read, and ● live, the k key or panning back to the right edge follows now again. While a tooltip is open the view stands still. fit shows every run on record. A lane at the bottom is another repo with something running; a click opens its hub when it serves. The count is the checks in flight against the runner's cap"
+/** the right side of the bar for a repo, before the machine's trouble and
+ *  the openers, which close it */
+export const RepoTools = observer(({ app }: { app: RepoSt }) => (
+    <>
+        <ProcessChips app={app} />
+        <HubStatus app={app} />
+        <Modernize app={app} />
+    </>
+))
 
-const Chevron = ({ open }: { open: boolean }) => (
-    <svg className={open ? 'cvt open' : 'cvt'} viewBox="0 0 24 24" width="11" height="11" aria-hidden="true">
-        <path d="M9 5l7 7-7 7" fill="none" stroke="currentColor" strokeWidth="3.4" strokeLinecap="round" strokeLinejoin="round" />
-    </svg>
-)
+/** the bar of a hub of its own: its name, then the same pieces the home
+ *  strip carries for a repo */
+export const HeaderBar = observer(({ app }: { app: RepoSt }) => (
+    <header className="hdr">
+        <span className="hname" style={app.name === '' ? undefined : { color: app.home.projects.identityOf(app.name).colorDark }}>{app.name !== '' ? app.name : 'hub'}</span>
+        <RepoRun app={app} />
+        <span className="sp" />
+        <RepoTools app={app} />
+        <RepoOpeners app={app} />
+    </header>
+))
 
-export const LiveStrip = observer(({ app }: { app: HubSt }) => {
-    const l = app.live
-    const v = l.view
-    const run = v?.runs[0]
-    const hidden = l.chart.layout?.hidden ?? 0
-    const waits = v == null ? '' : [
-        v.queued > 0 ? `${v.queued} queued for a free slot` : '',
-        ...v.blocked.map((w) => `${w.id} waits on ${w.deps.join(', ')}`),
-    ].filter((x) => x !== '').join('\n')
-    const who = run == null ? 'nothing running' : `${run.label}`
-    const chart = (
-        <TimelineChart view={l.chart} compact={!l.open} repos={v?.repos ?? []} follow zoomable={l.open}
-            onBar={(b) => app.cols.select('checks', `check:${b.id}`)}
-            onRepo={(r) => void l.openRepo(r.repo)} />
-    )
+/** one switch per process the repo declares (serve.processes): its dot, its
+ *  id, a click starts or stops it, and a link once it serves */
+export const ProcessChips = observer(({ app }: { app: RepoSt }) => {
+    const s = app.processes
+    if (s.list.length === 0) return null
     return (
-        <div className={`live${l.open ? ' open' : ''}${run == null ? ' idle' : ''}`} style={l.open ? { height: LIVE_ROW_H + l.held.h } : undefined}>
-            <div className="lrow">
-                <button className="lfold" onClick={() => l.toggle()} title={`${l.open ? 'fold' : 'unfold'} the live timeline (${LIVE_KEY})`}>
-                    <Chevron open={l.open} /><span className="sk">{LIVE_KEY}</span>
-                </button>
-                <Help text={LIVE_HELP} />
-                <span className="lwho" title={run == null ? '' : `${run.label}, started from the ${byWords(run.by)}${v != null && v.runs.length > 1 ? `\n${v.runs.length - 1} more in flight here` : ''}`}>
-                    {who}{run == null ? null : <i>{byWords(run.by)}</i>}{v != null && v.runs.length > 1 ? <b>+{v.runs.length - 1}</b> : null}
-                </span>
-                {l.open ? <span className="sp" /> : <div className="lchart">{chart}</div>}
-                {l.note !== '' ? <span className="lnote">{l.note}</span> : null}
-                {hidden > 0 ? <span className="lmore" title="check runs that did not fit in the folded strip: unfold it to see them">+{hidden}</span> : null}
-                <span className="lbusy" title={waits === '' ? 'checks in flight in this repo, against the runner cap' : waits}>
-                    in flight <span className="dnum">{v?.busy ?? 0}</span> / cap <span className="dnum">{v?.cap ?? 0}</span>
-                </span>
-            </div>
-            {l.open ? <div className="lopen">{chart}</div> : null}
-        </div>
+        <span className="hprocs">
+            {s.list.map((p) => {
+                const on = p.status === 'up' || p.status === 'starting'
+                const title = [p.cmd, p.note, p.external ? 'started outside the hub' : null, p.tail.at(-1)].filter((x) => x != null && x !== '').join('\n')
+                return (
+                    <span key={p.id} className="hproc">
+                        <button className={`ghost ${p.status}`} title={title} disabled={p.status === 'stopping' || (on && p.external)}
+                            onClick={() => void s.act(p.id, on ? 'stop' : 'start')}>
+                            <i className={`pdot ${p.status}`} />{p.id}
+                        </button>
+                        {p.url != null && p.status === 'up' ? <a href={p.url} target="_blank" rel="noreferrer" title={p.url}>↗</a> : null}
+                    </span>
+                )
+            })}
+        </span>
     )
 })

package/src/serve/hub-app/health-svc.ts

@@ -5,14 +5,14 @@
 // every check has its own page (checks-svc.ts owns the run itself). This card
 // exists so the whole text of a run stays reachable.
 import { makeAutoObservable, runInAction } from 'mobx'
-import type { HubSt } from './hub-st.ts'
+import type { RepoSt } from './repo-st.ts'
 
 export class HealthSvc {
     statusMd: string | null = null
     /** the lines of the run in flight, newest last */
     live: string[] = []
 
-    constructor(private st: HubSt) {
+    constructor(private st: RepoSt) {
         makeAutoObservable<this, 'st'>(this, { st: false })
     }
 
@@ -25,7 +25,7 @@ export class HealthSvc {
 
     async load(): Promise<void> {
         try {
-            const s = (await (await fetch('/api/status.json')).json()) as { statusMd: string | null }
+            const s = (await (await fetch(this.st.url('/api/status.json'))).json()) as { statusMd: string | null }
             runInAction(() => { this.statusMd = s.statusMd })
         } catch (e) {
             runInAction(() => { this.statusMd = `FAIL status fetch broke: ${(e as Error).message}` })

package/src/serve/hub-app/help.tsx

@@ -1,10 +1,12 @@
 // THE help affordance, once, for every surface of the hub: a small `(?)` that
-// shows one sentence the moment it is hovered or focused. CSS does the
-// showing (.hlp in hub.css), so there is no library, no delay and no state.
+// shows one sentence when it is hovered or focused, placed by floating-ui
+// (floating.tsx) above it, or wherever it fits.
 //
 // A term lives in TERMS rather than in the component that shows it, so the
 // same word is explained the same way wherever it appears.
 
+import { Tip } from './floating.tsx'
+
 export const TERMS: Record<string, string> = {
     always: 'it runs on every gate and every health pass',
     release: 'it runs on the release path only: the full gate and the health pass run it, the quick gate does not',
@@ -23,8 +25,9 @@ export const TERMS: Record<string, string> = {
 
 /** one sentence, either given here or named by its term. `text` takes a node
  *  so a legend can ride in the same bubble as a sentence */
-export const Help = ({ text, term }: { text?: React.ReactNode; term?: string }): React.ReactElement => (
-    <span className="hlp" tabIndex={0} role="note">
-        ?<span className="hbub">{text ?? (term != null ? TERMS[term] ?? term : '')}</span>
-    </span>
-)
+export const Help = ({ text, term }: { text?: React.ReactNode; term?: string }): React.ReactElement => {
+    const c = text ?? (term != null ? TERMS[term] ?? term : '')
+    // the sentence also rides inside the glyph, out of sight, so a screen
+    // reader and a search of the page find it without a hover
+    return <Tip className="hlp" tabIndex={0} tipClass="hbub" content={c}>?<span className="vh">{c}</span></Tip>
+}

package/src/serve/hub-app/home-st.ts

@@ -0,0 +1,278 @@
+// HomeSt: THE root of the page (build/app-state-tree), exposed as window.app.
+// One tree for every page the home serves, '/', '/planned', '/activity' and
+// '/r/<repo>/': the machine, the project list, the plan, the activity, and one RepoSt per repo visited, built on
+// the first visit and kept for the life of the page (same name, same
+// instance), so a repo you come back to shows what it showed. Only the shown
+// repo polls. Every other repo whose hub is up is read ahead in the
+// background, one at a time, so its first visit has its data at once. A hub serving on its own is the same tree with no machine and
+// one repo at base ''.
+//
+// the one constraint a reader breaks first: the url and the tree move
+// together, and only `show` moves the page. A list click, a link, back,
+// forward and a hand edited address all land there.
+import { makeAutoObservable, observableShallow, reaction, type IReactionDisposer } from 'mobx'
+import { currentHash, hashFor } from './hash-route.ts'
+import { MachineSt, type MachineOpts } from './machine-st.ts'
+import { LayoutSt } from './layout-st.ts'
+import { DockSt } from './dock-st.ts'
+import { PaletteSt } from './palette-st.ts'
+import { PlannedSt } from './planned-st.ts'
+import { ActivitySt } from './activity-st.ts'
+import { ProjectsSvc } from './projects-svc.ts'
+import { parseFilter, RepoSt } from './repo-st.ts'
+
+/** the longest one repo's read ahead holds the next one back */
+export const PREFETCH_WAIT_MS = 10_000
+
+/** what the page shows: the machine overview, the plan, the activity, or one repo */
+export type Page = 'overview' | 'planned' | 'activity' | 'archived' | 'repo'
+
+/** the address of each page of the home that is no repo's */
+export const PLACE_PATH = { overview: '/', planned: '/planned', activity: '/activity', archived: '/archived' } as const
+
+/** where a repo's hub answers on the home */
+export const repoBase = (name: string): string => `/r/${encodeURIComponent(name)}`
+/** the page of a repo on the home */
+export const repoPage = (name: string): string => `${repoBase(name)}/`
+
+/** where a check's own page answers on the home */
+export const checkAddress = (repo: string, check: string): string =>
+    `${repoPage(repo)}#${hashFor({ t: 'item', col: 'checks', id: `check:${check}` })}`
+
+/** the page an address on the home names */
+export function routeOf(pathname: string): { page: Page; repo: string | null } {
+    const m = /^\/r\/([^/]+)/.exec(pathname)
+    if (m != null) return { page: 'repo', repo: decodeURIComponent(m[1]!) }
+    if (/^\/planned\/?$/.test(pathname)) return { page: 'planned', repo: null }
+    if (/^\/activity\/?$/.test(pathname)) return { page: 'activity', repo: null }
+    if (/^\/archived\/?$/.test(pathname)) return { page: 'archived', repo: null }
+    return { page: 'overview', repo: null }
+}
+
+/** a plain left click: anything else keeps the browser's own behaviour
+ *  (a new tab, a new window, a download) */
+export const plainClick = (e: { button: number; metaKey: boolean; ctrlKey: boolean; shiftKey: boolean; altKey: boolean }): boolean =>
+    e.button === 0 && !e.metaKey && !e.ctrlKey && !e.shiftKey && !e.altKey
+
+export type HomeOpts = MachineOpts & {
+    /** true on the home's web; false on a hub serving on its own */
+    home: boolean
+}
+
+export class HomeSt {
+    /** the machine, on the home; null on a hub of its own */
+    machine: MachineSt | null
+    /** the list of every repo on this disk */
+    projects: ProjectsSvc
+    /** the plan, polled while it is the page */
+    planned: PlannedSt
+    /** what every repo committed and holds, polled while it is the page */
+    activity: ActivitySt
+    /** the one picker, cmd+k */
+    palette: PaletteSt
+    /** the widths of the project list and a repo's sidebar */
+    layout: LayoutSt
+    /** the run chart docked under the whole page */
+    dock: DockSt
+    page: Page
+    /** the key of the repo picked last: its name on the home, '' for the one
+     *  repo of a hub of its own. A global page keeps it (only `shown` says
+     *  whether it is on screen); null until a repo is picked */
+    selected: string | null = null
+    /** every repo visited, by key, kept for the life of the page */
+    repos = new Map<string, RepoSt>()
+    private disposers: IReactionDisposer[] = []
+    /** a read ahead is going: one repo at a time, never two loops */
+    private prefetching = false
+    private readonly onUrl = (): void => this.fromUrl()
+
+    constructor(o: HomeOpts) {
+        this.projects = new ProjectsSvc()
+        this.planned = new PlannedSt(this)
+        this.activity = new ActivitySt(this)
+        this.palette = new PaletteSt(this)
+        this.layout = new LayoutSt()
+        this.dock = new DockSt(this)
+        this.machine = o.home ? new MachineSt(this, o) : null
+        this.page = o.home ? 'overview' : 'repo'
+        makeAutoObservable<this, 'disposers' | 'onUrl' | 'prefetching'>(this, { machine: false, projects: false, planned: false, activity: false, palette: false, layout: false, dock: false, repos: observableShallow, disposers: false, onUrl: false, prefetching: false })
+        const m = this.machine
+        if (m != null) {
+            this.projects.onSelect = (name) => this.select(name)
+            this.projects.onPlace = (p) => this.navigate(PLACE_PATH[p])
+            this.projects.onPicker = () => this.palette.toggle()
+            this.projects.pickerOpen = () => this.palette.open
+            this.projects.onArchived = () => this.navigate(PLACE_PATH.archived)
+            this.projects.dotOf = (name) => m.dotOf(name)
+            this.projects.warnOf = (name) => m.warnOf(name)
+        } else {
+            this.projects.onSelect = (name) => void this.openInHome(name)
+            const own = this.repo('')
+            own.markSeen()
+            this.selected = own.key
+        }
+    }
+
+    /** the repo on screen, or null */
+    get shown(): RepoSt | null {
+        return this.page !== 'repo' || this.selected == null ? null : this.repos.get(this.selected) ?? null
+    }
+
+    /** every repo shown once, in visit order: each keeps its own mounted
+     *  region. A repo only read ahead has no region yet */
+    get visited(): RepoSt[] {
+        return [...this.repos.values()].filter((r) => r.seen)
+    }
+
+    get title(): string {
+        if (this.page === 'overview') return 'home'
+        if (this.page === 'planned') return 'planned'
+        if (this.page === 'activity') return 'activity'
+        if (this.page === 'archived') return 'archived'
+        const r = this.shown
+        return r == null || r.name === '' ? 'hub' : `${r.name} · hub`
+    }
+
+    /** the repo of this key, built on its first visit and never again */
+    repo(key: string): RepoSt {
+        let r = this.repos.get(key)
+        if (r == null) {
+            r = new RepoSt(this, key, this.machine == null ? '' : repoBase(key))
+            this.repos.set(key, r)
+            // what this browser kept of it paints before its hub answers
+            void r.cols.restore()
+        }
+        return r
+    }
+
+    boot(): void {
+        this.machine?.boot()
+        this.dock.boot()
+        this.disposers.push(reaction(() => this.title, (t) => { document.title = t }, { fireImmediately: true }))
+        // back, forward, a pasted link and a hand edited hash all arrive
+        // here; fromUrl is idempotent, so the two events firing together
+        // for one move cost nothing
+        window.addEventListener('popstate', this.onUrl)
+        window.addEventListener('hashchange', this.onUrl)
+        this.fromUrl()
+    }
+
+    dispose(): void {
+        for (const d of this.disposers) d()
+        this.disposers = []
+        window.removeEventListener('popstate', this.onUrl)
+        window.removeEventListener('hashchange', this.onUrl)
+        this.machine?.stop()
+        this.planned.stop()
+        this.activity.stop()
+        this.dock.dispose()
+        for (const r of this.repos.values()) r.dispose()
+    }
+
+    /** a list click, a repo row: that repo, in place, as a history entry */
+    select(name: string): void {
+        this.show('repo', name, 'push')
+    }
+
+    /** a check: its own page in its repo, in place. The selection is written
+     *  before the repo is shown, so the one history entry already names it */
+    openCheck(repo: string, check: string): void {
+        this.repo(repo).cols.select('checks', `check:${check}`)
+        this.select(repo)
+    }
+
+    /** a link to a page of the home: the same page, in place */
+    navigate(path: string): void {
+        const u = new URL(path, 'http://home.invalid')
+        const r = routeOf(u.pathname)
+        if (r.page === 'planned') this.planned.query = u.searchParams.get('q') ?? ''
+        this.show(r.page, r.repo, 'push')
+    }
+
+    /** the url decides the page: the first load, back, forward and a hand
+     *  edited address all land here */
+    fromUrl(): void {
+        if (this.machine == null) {
+            this.shown?.applyHash()
+            return
+        }
+        const r = routeOf(location.pathname)
+        // an address from before repo pages had their own path (`/#<repo>`)
+        const legacy = r.page === 'overview' ? currentHash() : ''
+        if (legacy !== '') return this.show('repo', legacy, 'replace')
+        if (r.page === 'planned') this.planned.query = new URLSearchParams(location.search).get('q') ?? ''
+        if (r.page === 'repo') this.repo(r.repo!).filter = parseFilter(location.search)
+        this.show(r.page, r.repo, 'none')
+        this.shown?.applyHash()
+    }
+
+    /** the one place the page changes. A repo left behind pauses and keeps
+     *  everything; the one shown resumes once its hub answers */
+    private show(page: Page, repo: string | null, how: 'push' | 'replace' | 'none'): void {
+        const prev = this.shown
+        const next = page === 'repo' && repo != null ? this.repo(repo) : null
+        // the page already shown is never a second history entry
+        if (how === 'push' && page === this.page && next === prev && page !== 'planned') how = 'none'
+        if (prev != null && prev !== next) prev.pause()
+        next?.markSeen()
+        this.page = page
+        // a global page is no repo's: the repo picked last stays selected
+        if (next != null) this.selected = next.key
+        this.projects.selected = this.selected
+        this.projects.away = next == null
+        this.projects.place = page === 'repo' || page === 'archived' ? null : page
+        if (how !== 'none') {
+            const to = next != null ? `${repoPage(next.key)}${next.search}${next.hash}` : page === 'planned' ? this.planned.address : page === 'activity' || page === 'archived' ? PLACE_PATH[page] : '/'
+            if (how === 'push') history.pushState(null, '', to)
+            else history.replaceState(null, '', to)
+        }
+        if (page === 'planned') this.planned.start()
+        else this.planned.stop()
+        if (page === 'activity') this.activity.start()
+        else this.activity.stop()
+        if (next != null && next !== prev && this.machine?.data != null) void this.machine.hub(next.key, 'ensure')
+        this.wake()
+    }
+
+    /** the shown repo polls once its hub answers, or at once on a hub of its
+     *  own. One that started keeps going when its hub goes away, and says so */
+    wake(): void {
+        const r = this.shown
+        if (r == null) return
+        if (this.machine == null || r.started || (this.machine.fresh && this.machine.worker(r.key)?.status === 'up')) r.resume()
+    }
+
+    /** read ahead the first screen of every repo whose hub is up, in list
+     *  order, one at a time, once the repo shown has its own. A repo read
+     *  once is not read again: it polls when it shows */
+    async prefetch(): Promise<void> {
+        const m = this.machine
+        if (m?.data == null || !m.fresh || this.prefetching) return
+        const shown = this.shown
+        if (shown != null && !shown.cols.loaded) return
+        this.prefetching = true
+        try {
+            for (const p of this.projects.list) {
+                // a repo shown meanwhile has its own first screen to read:
+                // it goes first, and the next machine poll resumes this loop
+                const now = this.shown
+                if (now != null && !now.cols.loaded) return
+                if (m.worker(p.name)?.status !== 'up') continue
+                const r = this.repo(p.name)
+                if (r.started) continue
+                // a hub that hangs holds the loop back this long, never forever
+                await Promise.race([r.prefetch(), new Promise((ok) => setTimeout(ok, PREFETCH_WAIT_MS))])
+            }
+        } finally {
+            this.prefetching = false
+        }
+    }
+
+    /** a list click on a hub serving on its own: that repo's page on the
+     *  home when one serves, else the folder in VS Code */
+    async openInHome(name: string): Promise<void> {
+        const home = await fetch('/api/home-url').then((r) => r.json() as Promise<{ port: number; up: boolean }>).catch(() => null)
+        if (home?.up !== true) return this.projects.open(name)
+        window.location.href = `${window.location.protocol}//${window.location.hostname}:${home.port}${repoPage(name)}`
+    }
+}