rvlib-shipkit 1.2.0 → 1.4.0

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

@@ -0,0 +1,41 @@
+// A repo's admin page, as state: what administers the repo rather than works
+// in it. Archive asks first (the confirmation is this state, so it survives a
+// re-render and a test drives it headless), reload and keep active go to the
+// machine by the repo's key. On a hub of its own there is no machine, and no
+// admin page.
+import { makeAutoObservable } from 'mobx'
+import type { RepoSt } from './repo-st.ts'
+
+export class AdminSvc {
+    /** the archive button was pressed: its confirmation shows in its place */
+    confirming = false
+
+    constructor(private st: RepoSt) {
+        makeAutoObservable<this, 'st'>(this, { st: false })
+    }
+
+    askArchive(): void {
+        this.confirming = true
+    }
+    cancel(): void {
+        this.confirming = false
+    }
+    /** archived, the repo leaves the project list and its page shows the
+     *  archived note with its way back */
+    archive(): void {
+        this.confirming = false
+        void this.st.home.projects.setArchived(this.st.key, true)
+    }
+
+    /** its hub, stopped in the daemon and loaded again with its config read fresh */
+    reload(): Promise<boolean> {
+        return this.st.home.machine?.hub(this.st.key, 'restart') ?? Promise.resolve(false)
+    }
+
+    get active(): boolean {
+        return this.st.home.machine?.isActive(this.st.key) === true
+    }
+    setActive(on: boolean): Promise<boolean> {
+        return this.st.home.machine?.setActive(this.st.key, on) ?? Promise.resolve(false)
+    }
+}

package/src/serve/hub-app/admin-view.tsx

@@ -0,0 +1,42 @@
+// THE ADMIN PAGE of a repo (`#page:admin`): what administers the repo rather
+// than works in it, one row per control, each with the one sentence that says
+// what it does. State in admin-svc.ts. Only on the home: a hub of its own has
+// no machine to administer it.
+import { observer } from 'mobx-react-lite'
+import type { ReactNode } from 'react'
+import type { RepoSt } from './repo-st.ts'
+
+const Row = ({ title, says, children }: { title: string; says: string; children: ReactNode }) => (
+    <div className="adrow">
+        <div className="adtext">
+            <b>{title}</b>
+            <span className="dim">{says}</span>
+        </div>
+        <div className="adctl">{children}</div>
+    </div>
+)
+
+export const AdminPage = observer(({ app }: { app: RepoSt }) => {
+    const a = app.admin
+    const w = app.home.machine?.worker(app.key)
+    const name = app.name
+    return (
+        <div className="colcard checkcard">
+            <div className="chead">
+                <span className="tid">admin</span>
+                <h3 className="ctitle">{name}</h3>
+            </div>
+            <Row title="reload the hub" says={`stops ${name}'s hub in the daemon and loads it again, its repo.config.ts read fresh and its processes started again. The daemon already does it on its own when repo.config.ts changes: this is for a hub that is stuck.${w == null ? '' : ` Its hub is ${w.status} now.`}`}>
+                <button className="ghost" onClick={() => void a.reload()}>reload</button>
+            </Row>
+            <Row title="keep active" says="an active repo runs the checks the plan holds for it and gets its red pings. It is active on its own while an agent works in it or VS Code has it open: this keeps it active without either.">
+                <label className="adflag"><input type="checkbox" checked={a.active} onChange={(e) => void a.setActive(e.currentTarget.checked)} />active</label>
+            </Row>
+            <Row title="archive" says="it leaves the project list for the archived page, and nothing runs there: no hub, no watch, no plan rows, no processes, no widgets. Written to repo.config.ts as archived: true, and undone from the archived page.">
+                {a.confirming
+                    ? <span className="adconfirm"><span>archive {name}?</span><button className="primary" onClick={() => a.archive()}>archive it</button><button className="ghost" onClick={() => a.cancel()}>cancel</button></span>
+                    : <button className="ghost" onClick={() => a.askArchive()}>archive</button>}
+            </Row>
+        </div>
+    )
+})

package/src/serve/hub-app/chart-view.ts

@@ -1,12 +1,12 @@
 // The view state of THE run chart: its zoom, the width it has on screen and
 // what is under the pointer, over the geometry (timeline-geometry.ts) and the
-// drawing (timeline-chart.tsx). The live strip owns it, and nothing else in
-// the hub draws a run. What differs is the source: folded, a rolling window
-// that ends now; unfolded, the whole record opened on its last minutes.
+// drawing (timeline-chart.tsx). What differs is the source: the dock's, a
+// rolling window that ends now with one group of lanes per repo; a repo's
+// runs page's, its whole record opened on its last minutes.
 import { makeAutoObservable, observableRef } from 'mobx'
 import type { TimelineInvocation } from '../../ledger/run-timeline.ts'
 import {
-    anchorScroll, buildAxis, fitScale, fitWindow, layoutTimeline, maxZoom, PAD_PX, windowAxis, ZOOM_MIN, zoomStep, type Axis, type Layout, type Span,
+    anchorScroll, buildAxis, fitScale, fitWindow, layoutGroups, layoutTimeline, maxZoom, PAD_PX, windowAxis, ZOOM_MIN, zoomStep, type Axis, type ChartGroup, type Layout, type Span,
 } from './timeline-geometry.ts'
 
 /** what a chart draws. `windowMs` null = the whole record, with idle
@@ -23,6 +23,11 @@ export type ChartSource = {
     /** the span the view opens on: at its home zoom this much time, ending
      *  now, fills the width. Absent = home is zoom 1, the whole source */
     homeSpanMs?: number
+    /** one group of lanes per key, over a rolling window only. `invocations`
+     *  then holds every group's, and `laneCap` bounds each group */
+    groups?: ChartGroup[]
+    /** the fewest lanes a group takes, so its label fits beside them */
+    minLanes?: number
 }
 
 /** what the tooltip says, and the viewport point it is fixed at */
@@ -117,7 +122,9 @@ export class ChartView {
     get layout(): Layout | null {
         const s = this.src
         if (s == null || this.viewW === 0) return null
-        return layoutTimeline(s.invocations, this.now, this.scale, { from: this.from ?? undefined, laneCap: s.laneCap, cap: s.cap })
+        const from = this.from
+        if (s.groups != null && from != null) return layoutGroups(s.groups, this.now, this.scale, { from, laneCap: s.laneCap, minLanes: s.minLanes, cap: s.cap })
+        return layoutTimeline(s.invocations, this.now, this.scale, { from: from ?? undefined, laneCap: s.laneCap, cap: s.cap })
     }
 
     private axisAt(scale: number): Axis {

package/src/serve/hub-app/check-words.ts

@@ -35,6 +35,8 @@ export function rememberedFact(u: CachePop): RememberedFact {
         return { v: 'until a file it reads changes', inputs, help: `keyed on ${list(inputs)}: the answer is ${CACHED} until a change under ${inputs.length > 1 ? 'them' : 'it'}, then it runs again` }
     if (u.reads === true && inputs.length === 0 && (u.ttl == null || u.ttl === '') && u.never == null)
         return { v: 'until a file it read changes', inputs: [], help: `keyed on what its last run read: the answer is ${CACHED} until one of those files, existence probes or listings changes, then it runs again. \`shipkit keys --why\` names them` }
+    if (u.ttl === 'forever')
+        return { v: 'until its declaration changes', inputs: [], help: 'a decided fact (`ttl: \'forever\'`): a clean answer is kept until the value it checks is declared differently, and it runs only while no answer exists for that value' }
     if (u.ttl != null && u.ttl !== '') {
         let every = u.ttl
         try { every = spanWords(parseDuration(u.ttl)) } catch { /* an unparsable ttl is shown as written */ }

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

@@ -12,6 +12,7 @@ import type { RepoSt } from './repo-st.ts'
 import { applyRunEvent, idleRun, startRun, stripText, type RunProgress } from './run-strip.ts'
 import type { GateBlock, Resource, ResourceState, SlowSuite, CheckEvent, WhenAt } from './hub-types.ts'
 import { WHEN_OPTION } from './check-words.ts'
+import { lineText } from '../../core/wire.ts'
 
 /** the colour rule, the SAME one the server applies, because a row must not
  *  change meaning between a live result and the poll that confirms it */
@@ -199,7 +200,7 @@ export class ChecksSvc {
                 state: stateOf(e),
                 severity: e.status === 'fail' ? (e.advisory ? 'yellow' : 'red') : e.status === 'warn' ? 'yellow' : undefined,
                 check: { ...u, status: e.status, replayed: e.replayed, lastMs: e.replayed ? null : Math.round(e.ms), lastAt: Date.now(), advisory: e.advisory },
-                md: e.lines.length === 0 ? r.md : `\`\`\`\n${e.lines.map((l) => (l.kind === 'fix-fail' || l.kind === 'fix-warn' ? `      fix: ${l.text}` : l.kind === 'fail' ? `FAIL: ${l.text}` : l.kind === 'warn' ? `WARN ${l.text}` : l.kind === 'skip' ? `skip: ${l.text}` : `ok: ${l.text}`)).join('\n')}\n\`\`\``,
+                md: e.lines.length === 0 ? r.md : `\`\`\`\n${e.lines.map((l) => (l.kind === 'fix-fail' || l.kind === 'fix-warn' ? `      fix: ${lineText(l)}` : l.kind === 'fail' ? `FAIL: ${lineText(l)}` : l.kind === 'warn' ? `WARN ${lineText(l)}` : l.kind === 'skip' ? `skip: ${lineText(l)}` : `ok: ${lineText(l)}`)).join('\n')}\n\`\`\``,
             }
         })
     }

package/src/serve/hub-app/col-tables-view.tsx

@@ -0,0 +1,124 @@
+// The checks page and the asks page: one dense table each, in the activity
+// page's table style, one line per item under group headers that count their
+// lines. What needs attention comes first; the quiet groups (passing, off,
+// done) fold by default and each viewer's fold choice is kept. The filter
+// input and the severity keys narrow the lines, since both read
+// `visibleInstances`. Groups, order and words: col-tables.ts.
+import { observer } from 'mobx-react-lite'
+import type { ReactNode } from 'react'
+import { checkName } from './check-words.ts'
+import { askGroups, checkGroups, dayMs, findingLine, planWord, type TableGroup } from './col-tables.ts'
+import { durationTone, fmtMs } from './dur.ts'
+import type { Resource } from './hub-types.ts'
+import type { RepoSt } from './repo-st.ts'
+import { TimeAgo } from './time-ago.tsx'
+
+const emptyWords = (app: RepoSt): string => (app.filter === 'red' ? 'no reds here' : app.filter === 'needs' ? 'nothing here needs you' : app.query.trim() !== '' ? 'nothing matches the filter' : 'nothing here yet')
+
+/** the page frame: the collection's title and count, then the table */
+const Page = ({ title, n, cols, empty, children }: { title: string; n: number; cols: ReactNode; empty: string; children: ReactNode }) => (
+    <div className="ctpage">
+        <div className="cghead">{title}<span className="cnt">{n}</span></div>
+        {n === 0 ? <div className="ph">{empty}</div> : (
+            <table className="actable cttable">
+                <colgroup>{cols}</colgroup>
+                {children}
+            </table>
+        )}
+    </div>
+)
+
+/** one group: its header line (a click folds it), then its lines unless folded */
+const Group = observer(<K extends string>({ app, col, g, span, row }: { app: RepoSt; col: string; g: TableGroup<K>; span: number; row: (r: Resource) => ReactNode }) => {
+    const key = `${col}:${g.key}`
+    const folded = app.cols.groupFolded(key, g.foldedByDefault)
+    return (
+        <tbody className="ctgroup">
+            <tr className={`ctgrp g-${g.key}`} data-k={g.key} onClick={() => app.cols.toggleGroup(key, g.foldedByDefault)}>
+                <td colSpan={span}><span className="ctcaret">{folded ? '▸' : '▾'}</span>{g.label}</td>
+            </tr>
+            {folded ? null : g.rows.map(row)}
+        </tbody>
+    )
+})
+
+const DOT: Record<string, { tone: string; mark: string }> = {
+    fail: { tone: 't-red', mark: '●' },
+    warn: { tone: 't-warn', mark: '●' },
+    pass: { tone: 't-ok', mark: '●' },
+    skip: { tone: 'acdim', mark: '●' },
+    never: { tone: 'acdim', mark: '○' },
+    off: { tone: 'acdim', mark: '○' },
+}
+
+const CheckRow = observer(({ app, r }: { app: RepoSt; r: Resource }) => {
+    const c = r.check!
+    const name = checkName(c.checkId, r.title)
+    const dot = c.when === 'off' ? DOT.off! : c.status == null ? DOT.never! : DOT[c.status]!
+    const finding = findingLine(c)
+    const tone = durationTone(c.lastMs, c.timeoutMs, c.budgetMs)
+    return (
+        <tr className={`ctrow s-${c.status ?? 'never'}`} data-k={c.checkId} onClick={() => app.cols.select(r.collection, r.id)} title={c.description}>
+            <td className={`ctdot ${dot.tone}`}>{dot.mark}</td>
+            <td className={`ctid ${c.status === 'fail' ? 't-red' : c.status === 'warn' ? 't-warn' : ''}`}>{c.checkId}</td>
+            <td className="cttitle">{name.title === c.checkId ? '' : name.title}</td>
+            <td className="acwhen">{c.lastAt == null ? '' : <TimeAgo clock={app.clock} at={c.lastAt} />}</td>
+            <td className="ctdur">
+                {c.lastMs == null ? null : <span className={`dnum ${tone ?? ''}`}>{fmtMs(c.lastMs)}</span>}
+                <span className="ctbudget">{` / ${fmtMs(c.budgetMs)}`}</span>
+            </td>
+            <td className="ctfind" title={c.lastLines.length > 0 ? c.lastLines.join('\n') : undefined}>{finding}</td>
+            <td className="ctplan">{planWord(c)}</td>
+        </tr>
+    )
+})
+
+export const CheckTable = observer(({ app, id }: { app: RepoSt; id: string }) => {
+    const col = app.cols.sidebarCols.find((x) => x.id === id)
+    if (col == null) return <div className="stagewrap"><div className="ph">collection vanished — the truth moved on</div></div>
+    const items = app.cols.visibleInstances(col)
+    const cols = (
+        <>
+            <col className="c-dot" /><col className="c-id" /><col className="c-title" /><col className="c-age" /><col className="c-dur" /><col /><col className="c-plan" />
+        </>
+    )
+    return (
+        <Page title={col.title} n={items.length} cols={cols} empty={emptyWords(app)}>
+            {checkGroups(items).map((g) => <Group key={g.key} app={app} col={col.id} g={g} span={7} row={(r) => <CheckRow key={r.id} app={app} r={r} />} />)}
+        </Page>
+    )
+})
+
+const AskRow = observer(({ app, r }: { app: RepoSt; r: Resource }) => {
+    const a = r.ask
+    const done = r.id.startsWith('ask:done/')
+    const at = dayMs(done ? (a?.closed ?? a?.created) : a?.created)
+    const blocks = a == null || a.blocks === '-' ? '' : a.blocks
+    return (
+        <tr className={`ctrow s-${done ? 'done' : 'open'}`} data-k={r.id} onClick={() => app.cols.select(r.collection, r.id)} title={r.file}>
+            <td className={`ctkind ${done ? 'acdim' : ''}`}>{a?.kind ?? r.slot ?? ''}</td>
+            <td className={`cttitle ${done ? 'acdim' : ''}`}>{r.title}</td>
+            <td className="acwhen">{at == null ? '' : <TimeAgo clock={app.clock} at={at} />}</td>
+            <td className="ctblocks" title={blocks === '' ? undefined : blocks}>{blocks}</td>
+            {done ? <td /> : a?.probe != null
+                ? <td className="ctprobe t-ok" title={`closes itself once \`${a.probe}\` exits 0`}>auto close</td>
+                : <td className="ctprobe acdim" title="no probe: done by hand">manual</td>}
+        </tr>
+    )
+})
+
+export const AskTable = observer(({ app, id }: { app: RepoSt; id: string }) => {
+    const col = app.cols.sidebarCols.find((x) => x.id === id)
+    if (col == null) return <div className="stagewrap"><div className="ph">collection vanished — the truth moved on</div></div>
+    const items = app.cols.visibleInstances(col)
+    const cols = (
+        <>
+            <col className="c-kind" /><col /><col className="c-age" /><col className="c-blocks" /><col className="c-probe" />
+        </>
+    )
+    return (
+        <Page title={col.title} n={items.length} cols={cols} empty={emptyWords(app)}>
+            {askGroups(items).map((g) => <Group key={g.key} app={app} col={col.id} g={g} span={5} row={(r) => <AskRow key={r.id} app={app} r={r} />} />)}
+        </Page>
+    )
+})

package/src/serve/hub-app/col-tables.ts

@@ -0,0 +1,115 @@
+// The checks page and the asks page as dense tables: which group each line
+// belongs to, the order inside a group, and every word a line says. Pure, so
+// a test pins them rather than a screenshot (col-tables-view.tsx draws them).
+import { parseDuration } from '../../core/wire.ts'
+import { spanShort } from '../../plan/plan-timeline.ts'
+import type { CachePop } from './check-words.ts'
+import type { CheckFacts, Resource } from './hub-types.ts'
+
+/** one group of lines under its header. `key` is what the viewer's fold
+ *  choice is remembered under, with the collection before it */
+export type TableGroup<K extends string> = { key: K; label: string; rows: Resource[]; foldedByDefault: boolean }
+
+export type CheckGroupKey = 'fail' | 'warn' | 'never' | 'pass' | 'off'
+
+/** the groups in the order a reader wants them: what needs attention first */
+const CHECK_GROUPS: { key: CheckGroupKey; word: string; folded: boolean }[] = [
+    { key: 'fail', word: 'failing', folded: false },
+    { key: 'warn', word: 'warning', folded: false },
+    { key: 'never', word: 'never ran', folded: false },
+    { key: 'pass', word: 'passing', folded: true },
+    { key: 'off', word: 'off', folded: true },
+]
+
+/** a skipped check had nothing to look at, which is nothing to fix: it sits
+ *  with the passing ones, its dot grey */
+export function checkGroupOf(c: CheckFacts): CheckGroupKey {
+    if (c.when === 'off') return 'off'
+    if (c.status === 'fail') return 'fail'
+    if (c.status === 'warn') return 'warn'
+    if (c.status == null) return 'never'
+    return 'pass'
+}
+
+const idOf = (r: Resource): string => r.check?.checkId ?? r.id
+
+/** most recent first; a check with no result by its id */
+const byRecent = (a: Resource, b: Resource): number => (b.check?.lastAt ?? -1) - (a.check?.lastAt ?? -1) || idOf(a).localeCompare(idOf(b))
+
+export function checkGroups(rows: readonly Resource[]): TableGroup<CheckGroupKey>[] {
+    const withFacts = rows.filter((r) => r.check != null)
+    return CHECK_GROUPS.map((g) => {
+        const mine = withFacts.filter((r) => checkGroupOf(r.check!) === g.key).sort(byRecent)
+        return { key: g.key, label: `${mine.length} ${g.word}`, rows: mine, foldedByDefault: g.folded }
+    }).filter((g) => g.rows.length > 0)
+}
+
+/** a wire line as plain text: the markdown ticks it is rendered with go */
+const plain = (l: string): string => l.replace(/`/g, '').trim()
+
+const escape = (x: string): string => x.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+/** a line without what its row already shows: the verdict word (the dot
+ *  says it) and the check's own id (the id column says it) */
+export function strippedLine(line: string, id: string): string {
+    const lead = new RegExp(`^(?:(?:FAIL|WARN|✗|⚠):?\\s*|\\[${escape(id)}\\]\\s*|${escape(id)}(?:\\s+—\\s+|:\\s+|\\s+|$))`)
+    let l = line
+    for (let m = l.match(lead); m != null && m[0] !== ''; m = l.match(lead)) l = l.slice(m[0].length)
+    return l.trim()
+}
+
+/** the first line of the last run that says something: a failure or a
+ *  warning first, else any line that is not the bare `ok: <id>` header */
+export function findingLine(c: CheckFacts): string {
+    const lines = c.lastLines.map(plain).filter((l) => l !== '')
+    const loud = lines.filter((l) => /^(FAIL|WARN|✗|⚠)/.test(l))
+    const rest = lines.filter((l) => !/^(FAIL|WARN|✗|⚠|ok\b|skip\b)/.test(l))
+    for (const l of [...loud, ...rest]) {
+        const s = strippedLine(l, c.checkId)
+        if (s !== '') return s
+    }
+    return ''
+}
+
+/** how a check is planned, as one short word a column scans: what makes it
+ *  run again (a file change, a span of time, never again) or how often it
+ *  runs when it remembers nothing */
+export function planWord(u: CachePop): string {
+    if (u.when === 'off') return 'off'
+    if ((u.inputs ?? []).length > 0 || u.reads === true) return 'on change'
+    if (u.ttl === 'forever') return 'once'
+    if (u.ttl != null && u.ttl !== '') {
+        try { return `every ${spanShort(parseDuration(u.ttl))}` } catch { return `every ${u.ttl}` }
+    }
+    return u.when === 'release' ? 'every release' : u.when === 'health' ? 'health pass' : 'every run'
+}
+
+export type AskGroupKey = 'open' | 'done'
+
+/** a `YYYY-MM-DD` stamp as ms, null when the file carries none */
+export const dayMs = (d: string | null | undefined): number | null => {
+    if (d == null) return null
+    const t = Date.parse(d)
+    return Number.isNaN(t) ? null : t
+}
+
+const NOTHING = new Set(['', '-'])
+const blocksOf = (r: Resource): string => r.ask?.blocks ?? '-'
+
+/** open asks by what they block (an ask that blocks nothing last), the
+ *  oldest first inside one; done asks after, the last closed first */
+export function askGroups(rows: readonly Resource[]): TableGroup<AskGroupKey>[] {
+    const isDone = (r: Resource): boolean => r.id.startsWith('ask:done/')
+    const open = rows.filter((r) => !isDone(r)).sort((a, b) => {
+        const na = NOTHING.has(blocksOf(a)) ? 1 : 0
+        const nb = NOTHING.has(blocksOf(b)) ? 1 : 0
+        return na - nb || blocksOf(a).localeCompare(blocksOf(b)) || (dayMs(a.ask?.created) ?? 0) - (dayMs(b.ask?.created) ?? 0) || a.id.localeCompare(b.id)
+    })
+    const closedAt = (r: Resource): number => dayMs(r.ask?.closed) ?? dayMs(r.ask?.created) ?? 0
+    const done = rows.filter(isDone).sort((a, b) => closedAt(b) - closedAt(a) || a.id.localeCompare(b.id))
+    const groups: TableGroup<AskGroupKey>[] = [
+        { key: 'open', label: `${open.length} open`, rows: open, foldedByDefault: false },
+        { key: 'done', label: `${done.length} done`, rows: done, foldedByDefault: true },
+    ]
+    return groups.filter((g) => g.rows.length > 0)
+}

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

@@ -9,6 +9,20 @@ import type { Col, ColMeta, HubProblem, Resource } from './hub-types.ts'
 import type { PlanRow } from '../../plan/planner.ts'
 import { readScreen, SCREEN_WRITE_MS, writeScreen } from './screen-cache.ts'
 
+/** where a viewer's fold choices on the checks and asks tables are kept,
+ *  one per browser and not per repo: `checks:pass` open is a habit */
+export const TABLE_FOLDS_KEY = 'hub:table-folds'
+
+const readFolds = (): Map<string, boolean> => {
+    try {
+        const v = JSON.parse(globalThis.localStorage?.getItem(TABLE_FOLDS_KEY) ?? '{}') as unknown
+        if (v == null || typeof v !== 'object') return new Map()
+        return new Map(Object.entries(v).filter((e): e is [string, boolean] => typeof e[1] === 'boolean'))
+    } catch {
+        return new Map()
+    }
+}
+
 /** what /api/resources.json answers */
 type Answer = { collections: ColMeta[]; resources: Resource[]; planned?: PlanRow[] | null; hub?: HubProblem[] }
 
@@ -43,6 +57,9 @@ export class ColsSvc {
     proofDraft = ''
     /** user fold choices win; default = open when the section holds needs */
     foldOverride = new Map<string, boolean>()
+    /** the viewer's fold choices on the table groups (`checks:pass`,
+     *  `asks:done`), true = folded; a group with none folds by its default */
+    tableFolds = readFolds()
     private timer: ReturnType<typeof setInterval> | null = null
 
     constructor(private st: RepoSt) {
@@ -177,6 +194,17 @@ export class ColsSvc {
     openSection(c: Col): void {
         this.foldOverride.set(c.id, true)
     }
+    /** a table group is folded: a live search shows every match, and a group
+     *  the viewer never touched folds by its default */
+    groupFolded(key: string, byDefault: boolean): boolean {
+        if (this.st.query.trim() !== '') return false
+        return this.tableFolds.get(key) ?? byDefault
+    }
+    toggleGroup(key: string, byDefault: boolean): void {
+        if (this.st.query.trim() !== '') return
+        this.tableFolds.set(key, !this.groupFolded(key, byDefault))
+        try { globalThis.localStorage?.setItem(TABLE_FOLDS_KEY, JSON.stringify(Object.fromEntries(this.tableFolds))) } catch { /* private window: the choice lasts the tab */ }
+    }
     /** rail red dot — the section holds at least one red item */
     hasRed(c: Col): boolean {
         return c.instances.some((i) => i.severity === 'red')

package/src/serve/hub-app/controls.css

@@ -0,0 +1,32 @@
+/* small controls any page can use. Colours are hub.css tokens, spacing its
+   scale (tests/hub-css-invariants.test.ts reads this sheet too) */
+
+/* the cycling button (cycle-button.tsx): the current label, one dot per
+   option with the current one in the ink colour, then its shortcut */
+.cycle{flex:none;display:inline-flex;align-items:center;gap:var(--s1);height:18px;padding:0 var(--s1);background:var(--panel2);border:1px solid var(--line);border-radius:9px;
+ color:var(--ink);font-size:10px;line-height:1;cursor:pointer}
+.cycle:hover{border-color:var(--accent)}
+.cyclbl{min-width:26px;text-align:center}
+.cycdots{display:inline-flex;align-items:center;gap:var(--s0)}
+.cycdot{width:4px;height:4px;border-radius:2px;background:var(--dim);opacity:.5}
+.cycdot.on{background:var(--ink);opacity:1}
+.cyckey{font:9px/1 ui-monospace,Menlo,monospace;color:var(--dim);background:none;border:0;padding:0}
+
+/* a row of pills (pill-row.tsx): one row always, the rest folded into +N.
+   The probe is an invisible copy that only gives the widths */
+.pchips{position:relative;display:flex;align-items:center;gap:var(--s1);min-width:0;overflow:hidden;white-space:nowrap}
+.pchipw{flex:none;display:inline-flex}
+.pchipprobe{position:absolute;left:0;top:0;width:max-content;overflow:visible;visibility:hidden;pointer-events:none}
+.pchip{display:inline-flex;align-items:center;gap:var(--s1);height:16px;padding:0 var(--s1);border:1px solid var(--line);border-radius:8px;
+ background:var(--panel2);color:var(--dim);font-size:10px;line-height:1}
+.pchip.accent{color:var(--accent);border-color:color-mix(in srgb,var(--accent) 45%,var(--line))}
+.pchip.warn{color:var(--warn);border-color:color-mix(in srgb,var(--warn) 45%,var(--line))}
+.pchip img,.pchip .dgico{flex:none;border-radius:2px}
+.pcmark{font-weight:700}
+.pcmark.ok{color:var(--ok)}
+.pcmark.red{color:var(--red)}
+.pcmark.warn{color:var(--warn)}
+.pcmark.dim{color:var(--dim)}
+.pctext{color:var(--ink);opacity:.8}
+.pchip.accent .pctext,.pchip.warn .pctext{color:inherit;opacity:1}
+.pcage{color:var(--dim);opacity:.75}

package/src/serve/hub-app/cycle-button.tsx

@@ -0,0 +1,36 @@
+// a button that cycles through a few options: it shows only the current
+// option's label, then one dot per option (the current one lit), then its
+// shortcut. A click moves to the next option, the last one wrapping to the
+// first; the page's key handler calls the same move for the shortcut.
+
+export type CycleOption<T extends string> = { readonly value: T; readonly label: string }
+
+/** the option after `value`, the last one wrapping to the first */
+export function nextOption<T extends string>(options: readonly CycleOption<T>[], value: T): T {
+    const i = options.findIndex((o) => o.value === value)
+    return options[(i + 1) % options.length]!.value
+}
+
+export function CycleButton<T extends string>(p: {
+    options: readonly CycleOption<T>[]
+    value: T
+    onChange: (next: T) => void
+    /** the key that cycles it too, shown as a badge */
+    shortcut?: string
+    /** what the button is for, on hover */
+    title?: string
+    className?: string
+}) {
+    const cur = p.options.find((o) => o.value === p.value)
+    const next = p.options.find((o) => o.value === nextOption(p.options, p.value))
+    const hint = `${p.title == null ? '' : `${p.title}\n`}click${p.shortcut == null ? '' : ` or ${p.shortcut}`}: ${next?.label ?? ''}`
+    return (
+        <button className={`cycle${p.className == null ? '' : ` ${p.className}`}`} title={hint} onClick={() => p.onChange(nextOption(p.options, p.value))}>
+            <span className="cyclbl">{cur?.label ?? p.value}</span>
+            <span className="cycdots" aria-hidden="true">
+                {p.options.map((o) => <i key={o.value} className={`cycdot${o.value === p.value ? ' on' : ''}`} />)}
+            </span>
+            {p.shortcut == null ? null : <kbd className="cyckey">{p.shortcut}</kbd>}
+        </button>
+    )
+}

package/src/serve/hub-app/dock-anim.ts

@@ -0,0 +1,25 @@
+// the dock's size change, eased: the class on the page's vertical split
+// carries a flex-grow transition (dock.css), put on only while a size change
+// resizes the panels, so a drag, a window resize and the first paint stay
+// instant. prefers-reduced-motion drops the transition in the sheet.
+
+/** how long the dock takes to reach its new size */
+export const DOCK_ANIM_MS = 180
+/** the class that eases the split's panels */
+export const DOCK_ANIM = 'dockanim'
+
+const timers = new WeakMap<HTMLElement, ReturnType<typeof setTimeout>>()
+
+/** runs `resize` with the class on `group`, and takes it off once the
+ *  transition ended; a second call meanwhile keeps it on until its own end */
+export function animateDock(group: HTMLElement | null, resize: () => void, ms = DOCK_ANIM_MS + 40): void {
+    if (group == null) return resize()
+    const was = timers.get(group)
+    if (was != null) clearTimeout(was)
+    group.classList.add(DOCK_ANIM)
+    resize()
+    timers.set(group, setTimeout(() => {
+        timers.delete(group)
+        group.classList.remove(DOCK_ANIM)
+    }, ms))
+}