rvlib-shipkit 1.4.0 → 1.6.0

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

@@ -7,6 +7,7 @@ import { testId } from '../../collections/collection-types.ts'
 import { makeAutoObservable, observableRef, runInAction } from 'mobx'
 import type { Timeline } from '../../ledger/run-timeline.ts'
 import type { RepoSt } from './repo-st.ts'
+import { ownTrouble, reach } from './reach.ts'
 
 export type { Timeline }
 
@@ -50,12 +51,12 @@ export class TimelineSvc {
     async load(fresh = false): Promise<void> {
         runInAction(() => { this.loading = true })
         try {
-            const r = await fetch(this.st.url(fresh ? '/api/timeline.json?fresh=1' : '/api/timeline.json'))
+            const r = await reach(this.st.url(fresh ? '/api/timeline.json?fresh=1' : '/api/timeline.json'))
             if (!r.ok) throw new Error(await r.text())
             const t = (await r.json()) as Timeline
             runInAction(() => { this.data = t; this.error = '' })
         } catch (e) {
-            runInAction(() => { this.error = (e as Error).message })
+            runInAction(() => { this.error = ownTrouble(e, this.st.home.machine) })
         } finally {
             runInAction(() => { this.loading = false })
         }

package/src/serve/hub-app/tree-build.ts

@@ -1,23 +1,30 @@
-// The trie, as pure functions over one flat Resource[]. No react, no mobx,
-// no dom: TreeSvc caches these as computeds and the tests drive them
-// headless. Both tabs (by path, by type) are the SAME array grouped twice,
-// never a second list.
-import { NO_CHECK, type Resource, type ResourceState, type TestFacts } from '../../collections/collection-types.ts'
+// The left pane's tree, as pure functions over one flat Resource[]. No react,
+// no mobx, no dom: TreeSvc caches these as computeds and the tests drive them
+// headless. The top rows are the repo's sections (keys.ts SectionId), and
+// every resource kind has exactly one section it lives under (KIND_SECTION),
+// so no kind can fall out of the pane. A section a repo does not draw still
+// gets its row when a resource lands in it.
+import { type Resource, type ResourceState, type ResourceType, type TestFacts } from '../../collections/collection-types.ts'
+import type { ProcessRow, RowDot } from '../../home/process-rows.ts'
 import { checkVerdictWords, plural } from '../../core/outcome-words.ts'
+import { runsWords } from '../../core/runs-matrix.ts'
 import { checkName } from './check-words.ts'
 import { durationTone, fmtMs, type DurTone } from './dur.ts'
 import type { HashSel } from './hash-route.ts'
+import { SECTION_LETTER, sectionLabel, type SectionId } from './keys.ts'
 
 export type TreeNode = {
     /** stable across reloads: the expansion set and the cursor are keys */
     key: string
     label: string
     state: ResourceState
-    /** null on a directory */
+    /** null on a group and on a section */
     res: Resource | null
-    /** a by type group: the kind it gathers, so its row wears that kind's
-     *  mark. null on a real folder and on a leaf */
+    /** a group: the kind it gathers, so its row wears that kind's mark.
+     *  null on a section and on a leaf */
     kind: string | null
+    /** a top row: the section it is. null everywhere below */
+    section: SectionId | null
     /** leaves under this node, and how many of them are red */
     total: number
     reds: number
@@ -26,8 +33,8 @@ export type TreeNode = {
     /** the archive: everything under it is already done. It stays in the
      *  tree and out of every count above it */
     archived: boolean
-    /** a folder with a page of its own: its label opens the page, its
-     *  chevron folds. null on every other folder and on a leaf */
+    /** a group with a page of its own: its label opens the page, its
+     *  chevron folds. null on every other group and on a leaf */
     page: HashSel | null
     children: TreeNode[]
 }
@@ -36,46 +43,101 @@ export type TreeRow = {
     key: string
     label: string
     depth: number
+    /** it has children, so it wears a chevron */
     dir: boolean
     state: ResourceState
     res: Resource | null
     kind: string | null
+    section: SectionId | null
     total: number
     reds: number
     checks: string[]
     page: HashSel | null
 }
 
-// a directory wears the WORST state under it, so a collapsed branch can
-// never hide a red, and OK outranks idle: a folder of passing checks read as
-// plain white because one unmeasured row in it outvoted twenty nine greens
+/** the sections, top to bottom */
+export const SECTION_ORDER = Object.keys(SECTION_LETTER) as SectionId[]
+
+/** where each resource kind lives. A Record over every kind, so a kind added
+ *  to RESOURCE_TYPES does not compile until it has a home. Runs, plan, git and
+ *  admin are pages only, so no kind lives there */
+export const KIND_SECTION: Record<ResourceType, SectionId> = {
+    check: 'repo',
+    reflection: 'reflections',
+    secret: 'secrets',
+    contract: 'contracts',
+    ask: 'asks',
+    test: 'tests',
+    asset: 'media',
+    workflow: 'media',
+    post: 'media',
+    wiki: 'wikis',
+    process: 'processes',
+}
+
+/** a process's colour: up reads green, crashed red, on its way orange,
+ *  stopped plain, and unknown (pm not answering) out of play */
+const PROCESS_STATE: Record<RowDot, ResourceState> = { up: 'ok', crashed: 'red', starting: 'warn', down: 'idle', unknown: 'quiet' }
+
+/** the repo's global processes as tree leaves. pm owns them, not the hub, so
+ *  they come from the machine and never from /api/resources.json */
+export const processResources = (rows: readonly ProcessRow[]): Resource[] =>
+    rows.map((r) => ({
+        id: `process:${r.id}`,
+        type: 'process',
+        collection: 'processes',
+        path: `processes/${r.id}`,
+        virtual: true,
+        title: r.label,
+        text: r.description ?? r.label,
+        slot: r.status,
+        state: PROCESS_STATE[r.dot],
+    }))
+
+/** a gate check lives under WHOSE it is: shipkit ships the SK checks, a
+ *  repo owns what it declared. A kind the map does not know (a newer hub)
+ *  still lands somewhere */
+export const sectionOf = (r: Resource): SectionId =>
+    r.check != null ? (r.check.from === 'shipkit' ? 'shipkit' : 'repo') : (KIND_SECTION[r.type as ResourceType] ?? 'repo')
+
+/** the severity filter, read off the COLOUR, so what `red` shows is what
+ *  reads red on the tree. An ask is proactive work, so it is in needs and
+ *  never in red (collection-types stateOf owns that rule) */
+export const passesFilter = (r: Resource, f: 'all' | 'needs' | 'red'): boolean =>
+    f === 'red' ? r.state === 'red' : f === 'needs' ? r.severity != null : true
+
+/** the filter input: a part of the title or of the path */
+export const matchesQuery = (r: Resource, q: string): boolean =>
+    q === '' || r.title.toLowerCase().includes(q) || r.path.toLowerCase().includes(q)
+
+// a group wears the WORST state under it, so a collapsed branch can never
+// hide a red, and OK outranks idle: a group of passing checks read as plain
+// white because one unmeasured row in it outvoted twenty nine greens
 const RANK: Record<ResourceState, number> = { red: 4, warn: 3, ok: 2, idle: 1, quiet: 0 }
 const worst = (a: ResourceState, b: ResourceState): ResourceState => (RANK[b] > RANK[a] ? b : a)
 
-/** an ask that is already done: it rides quiet under `done/`, filed away so
+/** an ask that is already done: it rides quiet under `done`, filed away so
  *  past answers stay consultable. Everything else a repo owns is either open
  *  or a check, so this is the one archive the tree has */
 const isDone = (r: Resource): boolean => r.type === 'ask' && r.slot === 'done'
 
-type Build = { dirs: Map<string, Build>; leaves: Resource[] }
-const emptyBuild = (): Build => ({ dirs: new Map(), leaves: [] })
-
 const byLabel = (a: TreeNode, b: TreeNode): number => {
     const ad = a.res == null
     const bd = b.res == null
-    if (ad !== bd) return ad ? -1 : 1 // directories first, then leaves
+    if (ad !== bd) return ad ? -1 : 1 // groups first, then leaves
     return a.label.localeCompare(b.label)
 }
 
 const leafNode = (r: Resource): TreeNode => ({
     // the resource id, never its path: two resources may share a file
     key: r.id,
-    // the TITLE, never the path segment: the path decides where a row sits,
-    // the title is what a reader reads
+    // the TITLE, never the path: the path is what the filter matches, the
+    // title is what a reader reads
     label: r.title,
     state: r.state,
     res: r,
     kind: null,
+    section: null,
     total: 1,
     reds: r.state === 'red' ? 1 : 0,
     checks: r.check == null ? [] : [r.check.checkId],
@@ -88,10 +150,9 @@ const rollup = (children: TreeNode[]): Pick<TreeNode, 'state' | 'total' | 'reds'
     const archived = children.length > 0 && children.every((c) => c.archived)
     return {
         state: children.reduce<ResourceState>((acc, c) => worst(acc, c.state), 'quiet'),
-        // an archive is out of the count of the folder that holds it: an
-        // asks row reading 25 when 9 of them want hands answers a question
-        // nobody asked. The archive itself still counts its own, so the row
-        // says how much is filed in there
+        // an archive is out of the count of the row that holds it: an asks
+        // row reading 25 when 9 of them want hands answers a question nobody
+        // asked. The archive itself still counts its own
         total: children.reduce((n, c) => n + (archived || !c.archived ? c.total : 0), 0),
         reds: children.reduce((n, c) => n + c.reds, 0),
         checks: children.flatMap((c) => c.checks),
@@ -99,148 +160,91 @@ const rollup = (children: TreeNode[]): Pick<TreeNode, 'state' | 'total' | 'reds'
     }
 }
 
-/** a chain of directories with one child and nothing of its own renders as
- *  ONE row (wiki/build/shipkit rather than three nested rows), and keeps the
- *  DEEPEST path as its key so an expansion survives a reload */
-const dirNode = (prefix: string, label: string, b: Build): TreeNode => {
-    if (b.leaves.length === 0 && b.dirs.size === 1) {
-        const [seg, only] = [...b.dirs.entries()][0]!
-        return dirNode(`${prefix}/${seg}`, `${label}/${seg}`, only)
-    }
-    const children = [
-        ...[...b.dirs.entries()].map(([seg, sub]) => dirNode(`${prefix}/${seg}`, seg, sub)),
-        ...b.leaves.map(leafNode),
-    ].sort(byLabel)
-    return { key: prefix, label, res: null, kind: null, ...rollup(children), page: pathPage(prefix, children), children }
-}
-
-const holdsTests = (nodes: TreeNode[]): boolean => nodes.some((n) => n.res?.test != null || holdsTests(n.children))
+/** the groups a resource sits in under its section. A check, a contract, a
+ *  secret, an ask, a test file, a wiki and an asset sit directly under their
+ *  section, one row each, a done ask under the `done` archive. Every other
+ *  kind gets one group named for it, and the group opens that collection's
+ *  page */
+type Seg = { key: string; label: string; kind: string; page: HashSel | null }
 
-/** the virtual `tests/` root of the path tab, and each `tests/<check>` under
- *  it, open the pages of the same groups on the by type tab. A real `tests/`
- *  folder that holds no test resource stays a plain folder */
-function pathPage(prefix: string, children: TreeNode[]): HashSel | null {
-    if (!holdsTests(children)) return null
-    if (prefix === 'tests') return { t: 'tests', check: null }
-    const m = prefix.match(/^tests\/([^/]+)$/)
-    return m == null || m[1] === NO_CHECK ? null : { t: 'tests', check: m[1]! }
-}
-
-/** the by type groups of test files: `tests` itself, and one group per test
- *  check. The files no check reaches have no time to show */
-function typePage(key: string, label: string): HashSel | null {
-    if (key === 'type:test') return { t: 'tests', check: null }
-    return key.startsWith('type:test:') && label !== NO_CHECK ? { t: 'tests', check: label } : null
-}
-
-export function buildPathTree(resources: Resource[]): TreeNode[] {
-    const root = emptyBuild()
-    for (const r of resources) {
-        const segs = r.path.split('/').filter((s) => s !== '')
-        let cur = root
-        for (const seg of segs.slice(0, -1)) {
-            let next = cur.dirs.get(seg)
-            if (next == null) {
-                next = emptyBuild()
-                cur.dirs.set(seg, next)
-            }
-            cur = next
-        }
-        cur.leaves.push(r)
-    }
-    return [
-        ...[...root.dirs.entries()].map(([seg, sub]) => dirNode(seg, seg, sub)),
-        ...root.leaves.map(leafNode),
-    ].sort(byLabel)
+const groupOf = (r: Resource): Seg[] => {
+    if (r.test != null) return []
+    if (r.check != null || r.type === 'contract' || r.type === 'secret') return []
+    if (r.type === 'ask') return isDone(r) ? [{ key: 'type:ask:done', label: 'done', kind: 'done', page: null }] : []
+    if (r.type === 'asset' && r.group != null) return [{ key: `cat:${r.group}`, label: r.group, kind: 'category', page: { t: 'cat', cat: r.group } }]
+    if (r.type === 'wiki' || r.type === 'asset' || r.type === 'test' || r.type === 'process' || r.type === 'reflection') return []
+    return [{ key: `type:${r.type}`, label: r.type, kind: r.type, page: { t: 'col', id: r.collection } }]
 }
 
-const groupNode = (key: string, label: string, kind: string, children: TreeNode[]): TreeNode => ({
-    key,
-    label,
-    res: null,
-    kind,
-    ...rollup(children),
-    page: typePage(key, label),
-    children: [...children].sort(byLabel),
-})
+type Group = { label: string; kind: string; page: HashSel | null; rs: Resource[]; subs: Map<string, Group> }
+const emptyGroup = (label: string, kind: string, page: HashSel | null): Group => ({ label, kind, page, rs: [], subs: new Map() })
 
-/** a gate check is filed by WHOSE it is: shipkit ships the SK checks, a repo
- *  owns everything it declared itself. There is no second axis, because what
- *  a check does and when it runs are already slots on its own row. A test
- *  file is filed under the check that runs it, since a repo holds a hundred
- *  of them. Every other resource keeps its type word. */
-type Seg = { key: string; label: string; kind: string }
+const groupChildren = (g: Group): TreeNode[] =>
+    [...[...g.subs.entries()].map(([k, sub]) => groupNode(k, sub)), ...g.rs.map(leafNode)].sort(byLabel)
 
-const groupOf = (r: Resource): Seg[] => {
-    const u = r.check
-    if (r.test != null) {
-        const by = r.test.standing === 'orphan' || r.test.checkId == null ? NO_CHECK : r.test.checkId
-        return [{ key: 'type:test', label: 'tests', kind: 'test' }, { key: `type:test:${by}`, label: by, kind: by === NO_CHECK ? 'test' : 'check' }]
-    }
-    if (u == null)
-        return isDone(r)
-            ? [{ key: `type:${r.type}`, label: r.type, kind: r.type }, { key: `type:${r.type}:done`, label: 'done', kind: 'done' }]
-            : [{ key: `type:${r.type}`, label: r.type, kind: r.type }]
-    return u.from === 'repo'
-        ? [{ key: 'type:check:repo', label: 'from this repo', kind: 'check' }]
-        : [{ key: 'type:check:shipkit', label: 'from shipkit', kind: 'check' }]
+const groupNode = (key: string, g: Group): TreeNode => {
+    const children = groupChildren(g)
+    return { key, label: g.label, res: null, kind: g.kind, section: null, ...rollup(children), page: g.page, children }
 }
 
-type Group = { label: string; kind: string; rs: Resource[]; subs: Map<string, Group> }
+/** the section node's key, stable so its fold survives a reload */
+export const sectionKey = (id: SectionId): string => `sec:${id}`
 
-const groupTree = (key: string, g: Group): TreeNode =>
-    groupNode(key, g.label, g.kind, [...[...g.subs.entries()].map(([k, sub]) => groupTree(k, sub)), ...g.rs.map(leafNode)])
-
-/** by type: one level per group, plus the `done` archive under the kind
- *  that has one, which mirrors the `asks/done/` folder the by path tab
- *  shows. Where a check RUNS is already on the row (its note slot) and
- *  counted above the tree, so a level for it costs a row to open and answers
- *  nothing again. */
-export function buildTypeTree(resources: Resource[]): TreeNode[] {
-    const top = new Map<string, Group>()
+/** the whole pane: one top row per section the repo draws, in the order
+ *  given, then any other section a resource lives in, so nothing a provider
+ *  emits is ever left without a row */
+export function buildTree(sections: readonly SectionId[], resources: Resource[]): TreeNode[] {
+    const tops = new Map<SectionId, Group>()
     for (const r of resources) {
-        let cur = top
-        let g: Group | null = null
+        const id = sectionOf(r)
+        const top = tops.get(id) ?? emptyGroup(id, id, null)
+        tops.set(id, top)
+        let g: Group = top
         for (const seg of groupOf(r)) {
-            let next = cur.get(seg.key)
-            if (next == null) {
-                next = { label: seg.label, kind: seg.kind, rs: [], subs: new Map() }
-                cur.set(seg.key, next)
-            }
+            const next: Group = g.subs.get(seg.key) ?? emptyGroup(seg.label, seg.kind, seg.page)
+            g.subs.set(seg.key, next)
             g = next
-            cur = next.subs
         }
-        g!.rs.push(r)
+        g.rs.push(r)
     }
-    return [...top.entries()].map(([key, g]) => groupTree(key, g)).sort(byLabel)
+    const order = [...sections, ...SECTION_ORDER.filter((id) => !sections.includes(id) && tops.has(id))]
+    return order.map((id) => {
+        const g = tops.get(id)
+        const children = g == null ? [] : groupChildren(g)
+        // a section is never an archive, even when all it holds is done:
+        // a search must still open it, and its count reads what is open
+        const up = rollup(children)
+        const total = children.reduce((n, c) => n + (c.archived ? 0 : c.total), 0)
+        return { key: sectionKey(id), label: sectionLabel(id), res: null, kind: null, section: id, ...up, total, archived: false, page: null, children }
+    })
 }
 
-/** the visible rows, in screen order — a directory nobody expanded stops
- *  the walk, which is the whole point of the expansion set */
+/** the visible rows, in screen order: a row nobody unfolded stops the walk,
+ *  which is the whole point of the expansion set */
 export function flattenTree(nodes: TreeNode[], expanded: Set<string>, depth = 0): TreeRow[] {
     const out: TreeRow[] = []
     for (const n of nodes) {
-        const dir = n.res == null
-        out.push({ key: n.key, label: n.label, depth, dir, state: n.state, res: n.res, kind: n.kind, total: n.total, reds: n.reds, checks: n.checks, page: n.page })
+        const dir = n.res == null && n.children.length > 0
+        out.push({ key: n.key, label: n.label, depth, dir, state: n.state, res: n.res, kind: n.kind, section: n.section, total: n.total, reds: n.reds, checks: n.checks, page: n.page })
         if (dir && expanded.has(n.key)) out.push(...flattenTree(n.children, expanded, depth + 1))
     }
     return out
 }
 
-/** the one line above the tree: how much of this repo runs on every gate,
- *  and how much does not. Counts CHECKS only, because nothing else declares a
- *  place to run */
+/** the line at the top of the checks page: how much of this repo runs on
+ *  every gate, and how much does not. Counts CHECKS only, because nothing
+ *  else declares a place to run */
 export function whenCounts(resources: Resource[]): Record<'always' | 'release' | 'health' | 'off', number> {
     const out = { always: 0, release: 0, health: 0, off: 0 }
     for (const r of resources) if (r.check != null) out[r.check.when]++
     return out
 }
 
-/** every directory key in the tree, which is what "expand all" writes.
+/** every key that can unfold, which is what "expand all" writes.
  *  `archive: false` leaves the done branches folded: a search that yields
  *  every fold must not spill what was filed away as answered */
 export function dirKeys(nodes: TreeNode[], archive = true): string[] {
-    return nodes.flatMap((n) => (n.res != null || (!archive && n.archived) ? [] : [n.key, ...dirKeys(n.children, archive)]))
+    return nodes.flatMap((n) => (n.res != null || n.children.length === 0 || (!archive && n.archived) ? [] : [n.key, ...dirKeys(n.children, archive)]))
 }
 
 /** what the label slot says: a check row carries its id as a small tag before
@@ -282,16 +286,6 @@ export type RowSlots = {
 const DIR_STATE: Record<ResourceState, SlotState> = { red: 'fail', warn: 'warn', ok: 'pass', idle: 'idle', quiet: 'off' }
 const DIR_TONE: Record<ResourceState, SlotTone> = { red: 'red', warn: 'warn', ok: 'ok', idle: 'idle', quiet: 'quiet' }
 
-/** the four values, short enough for a 48px slot. The tooltip says them in
- *  full, because these are abbreviations and nobody was born knowing them */
-const WHEN_NOTE = { always: 'ci', release: 'release', health: 'health', off: 'off' } as const
-const WHEN_HINT = {
-    always: 'runs on every gate',
-    release: 'runs on the release path only',
-    health: 'runs in the health pass only, never on a gate',
-    off: 'does not run',
-} as const
-
 export function rowSlots(row: TreeRow, running: boolean): RowSlots {
     if (row.dir)
         return {
@@ -319,7 +313,7 @@ export function rowSlots(row: TreeRow, running: boolean): RowSlots {
         }
     const verdict: [SlotState, SlotTone] = running
         ? ['running', 'run']
-        : u.when === 'off'
+        : u.when === 'off' || u.runs.off != null
             ? ['off', 'quiet']
             : u.status === 'fail'
                 ? ['fail', u.advisory ? 'adv' : 'red']
@@ -336,7 +330,9 @@ export function rowSlots(row: TreeRow, running: boolean): RowSlots {
         tone: verdict[1],
         dur: fmtMs(u.lastMs),
         durTone: durationTone(u.lastMs, u.timeoutMs, u.budgetMs),
-        note: WHEN_NOTE[u.when],
+        // where it runs has seven contexts, too many for a slot: the tooltip
+        // lists them, the check page draws them
+        note: '',
         count: null,
         hint: [
             `${u.checkId} (${u.build ? 'build step' : u.from === 'shipkit' ? 'from shipkit' : 'from this repo'}) · ${words}`,
@@ -345,7 +341,7 @@ export function rowSlots(row: TreeRow, running: boolean): RowSlots {
             u.description != null && u.description !== '' ? u.description : null,
             u.lastMs != null ? `last run ${fmtMs(u.lastMs)}` : null,
             u.samples > 0 ? `average ${fmtMs(u.avgMs)} over ${plural(u.samples, 'run')}` : null,
-            `${WHEN_HINT[u.when]}${u.whenReason != null ? `: ${u.whenReason}` : ''}`,
+            runsWords(u.runs),
         ].filter((l) => l != null).join('\n'),
     }
 }
@@ -378,15 +374,15 @@ function testSlots(r: Resource, t: TestFacts): RowSlots {
 // and on the state glyph at the right edge. Hues are tokens (k1..k6 on
 // :root), reused across kinds on purpose, because thirteen hues nobody can
 // tell apart is not thirteen answers. The glyph is what identifies, the hue
-// only groups.
+// only groups, and the word is the glyph's tooltip.
 
 export type TypeMark = { glyph: string; hue: string; word: string }
 
 export const TYPE_MARK: Record<string, TypeMark> = {
-    folder: { glyph: '\u25a3', hue: 'k5', word: 'a folder of this repo' },
     ask: { glyph: '\u25c9', hue: 'k2', word: 'an ask: something only a human can do' },
     secret: { glyph: '\u25c8', hue: 'k4', word: 'a secret this repo needs, present or missing' },
     asset: { glyph: '\u25c6', hue: 'k1', word: 'an asset of the kit, with its rolls and its pick' },
+    category: { glyph: '\u25a6', hue: 'k1', word: 'a category of the kit: its page shows every asset in it' },
     post: { glyph: '\u25a4', hue: 'k2', word: 'a post waiting in the social queue' },
     workflow: { glyph: '\u29c9', hue: 'k6', word: 'a comfy workflow module' },
     wiki: { glyph: '\u2b21', hue: 'k3', word: 'a markdown wiki, opened as its link graph' },
@@ -394,6 +390,7 @@ export const TYPE_MARK: Record<string, TypeMark> = {
     check: { glyph: '\u2299', hue: 'k6', word: 'a gate check: one question `shipkit ci` or `shipkit check` asks, whether it builds, guards a repo shape or probes the world. same page and same switch for all of them' },
     test: { glyph: '\u2263', hue: 'k5', word: 'a test file: the check that runs it, its last runs against its budget, the command that runs it alone' },
     reflection: { glyph: '\u203b', hue: 'k2', word: 'a reflection: friction this repo logged against the wiki, waiting to be folded in' },
+    process: { glyph: '\u223f', hue: 'k1', word: 'a global process this repo declares: its state, its menu, its log' },
     done: { glyph: '\u2713', hue: 'k5', word: 'a done ask: answered, filed under done, out of every count above it' },
 }
 
@@ -401,9 +398,8 @@ export const TYPE_MARK: Record<string, TypeMark> = {
  *  hole, and a new resource kind must never make the tree look broken */
 const UNKNOWN: TypeMark = { glyph: '\u25cb', hue: 'k5', word: 'a kind this page does not know yet' }
 
-/** a real folder wears the folder mark, a by type group the mark of the kind
- *  it gathers, and a leaf its own kind */
-export const markOf = (res: Resource | null | undefined, dir: boolean, kind: string | null = null): TypeMark =>
-    dir
-        ? kind == null ? TYPE_MARK.folder! : TYPE_MARK[kind] ?? UNKNOWN
-        : res == null ? UNKNOWN : isDone(res) ? TYPE_MARK.done! : TYPE_MARK[res.type] ?? UNKNOWN
+/** a group wears the mark of the kind it gathers, a leaf its own kind */
+export const markOf = (res: Resource | null | undefined, kind: string | null = null): TypeMark =>
+    res == null
+        ? kind == null ? UNKNOWN : TYPE_MARK[kind] ?? UNKNOWN
+        : isDone(res) ? TYPE_MARK.done! : TYPE_MARK[res.type] ?? UNKNOWN

package/src/serve/hub-app/tree-row.tsx

@@ -1,12 +1,26 @@
-// ONE ROW of the resource tree: a fixed grid of caret, kind, label, duration,
-// note and state glyph. The indent rides in the first column, the label eats
-// the slack, and the glyph is LAST so the wide duration column never pushes it
-// around. No row carries prose: the words are the tooltip and the page it opens.
+// ONE ROW of the left pane's tree. A section row (the top level) is drawn as
+// the project list draws its lines: caret, icon, label, count, ⌥ key, the
+// current one lit. Every row under it is a fixed grid of caret, kind, label,
+// duration clock, note and state glyph. The indent rides in the first
+// column, the label eats the slack, and the glyph is LAST, on the right edge.
+// No row carries prose: the words (the duration too) are the tooltips and
+// the page it opens. A click opens, only the chevron folds.
 import { observer } from 'mobx-react-lite'
-import type { CSSProperties } from 'react'
+import { useEffect, useRef, type CSSProperties, type RefObject } from 'react'
+import { Icon, ICON } from './icons.tsx'
+import { sectionKeyLabel } from './keys.ts'
 import type { RepoSt } from './repo-st.ts'
 import { GLYPH, markOf, rowName, rowSlots, type TreeRow } from './tree-build.ts'
 
+/** the row under the cursor stays in sight while the arrows move it */
+const useInSight = (on: boolean): RefObject<HTMLDivElement | null> => {
+    const el = useRef<HTMLDivElement | null>(null)
+    useEffect(() => {
+        if (on) el.current?.scrollIntoView({ block: 'nearest' })
+    }, [on])
+    return el
+}
+
 /** the fold marker: a chevron, right when the branch is shut and down when
  *  it is open. The 9px triangle it replaces read as a dot with an opinion */
 export const Caret = ({ open }: { open: boolean }): React.ReactElement => (
@@ -15,24 +29,53 @@ export const Caret = ({ open }: { open: boolean }): React.ReactElement => (
     </svg>
 )
 
-export const TreeRowView = observer(({ app, row }: { app: RepoSt; row: TreeRow }) => {
+/** the chevron's own hit target: it folds, and the click never reaches the row */
+const Fold = observer(({ app, row }: { app: RepoSt; row: TreeRow }) => (
+    <span className="tw" onClick={row.dir ? (e) => { e.stopPropagation(); app.tree.fold(row) } : undefined}>
+        {row.dir ? <Caret open={app.tree.isOpen(row.key)} /> : null}
+    </span>
+))
+
+/** a top row: a section of the repo. A section no page backs (a kind whose
+ *  own section this repo does not draw) still gets its row, with no key */
+export const SectionRowView = observer(({ app, row }: { app: RepoSt; row: TreeRow }) => {
+    const t = app.tree
+    const id = row.section!
+    const s = t.sections.find((x) => x.id === id)
+    const key = s == null ? null : sectionKeyLabel(id)
+    const el = useInSight(t.cursor === row.key)
+    return (
+        <div ref={el} className={`tsec${s?.empty === true ? ' empty' : ''}${s?.opens === false ? ' noop' : ''}${s?.on === true ? ' cur' : ''}${t.cursor === row.key ? ' on' : ''}`} aria-current={s?.on === true ? 'page' : undefined}
+            title={s == null ? row.label : `${s.title} (${key})`} onClick={() => t.click(row)}>
+            <Fold app={app} row={row} />
+            <Icon d={ICON[id]} />
+            <span className="rsecl">{s?.label ?? row.label}</span>
+            {s?.count == null ? null : <b className={`rsecn n${s.tone}`}>{s.count}</b>}
+            {key == null ? null : <kbd className="pjkey">{key}</kbd>}
+        </div>
+    )
+})
+
+export const TreeRowView = ({ app, row }: { app: RepoSt; row: TreeRow }): React.ReactElement =>
+    row.section != null ? <SectionRowView app={app} row={row} /> : <LeafRowView app={app} row={row} />
+
+const LeafRowView = observer(({ app, row }: { app: RepoSt; row: TreeRow }) => {
     const t = app.tree
     const u = app.checks
     const running = row.checks.some((id) => u.isRunning(id))
     const s = rowSlots(row, running)
-    const mark = markOf(row.res, row.dir, row.kind)
+    const mark = markOf(row.res, row.kind)
     const name = rowName(row)
+    const el = useInSight(t.cursor === row.key)
     return (
-        <div className={`trow${t.cursor === row.key ? ' on' : ''}`} style={{ '--d': row.depth } as CSSProperties}
+        <div ref={el} className={`trow${t.cursor === row.key ? ' on' : ''}`} style={{ '--d': row.depth } as CSSProperties}
             title={s.hint} onClick={() => t.click(row)}>
-            {/* the chevron folds, the rest of the row opens: on a folder with a
-                page of its own the two differ, everywhere else both fold */}
             <span className="tw" onClick={row.dir ? (e) => { e.stopPropagation(); t.fold(row) } : undefined}>
-                {row.dir ? <Caret open={t.expanded.has(row.key)} /> : null}
+                {row.dir ? <Caret open={t.isOpen(row.key)} /> : null}
             </span>
             <span className={`ty ${mark.hue}`} title={mark.word}>{mark.glyph}</span>
             <span className={`tl ${row.state}`}>{name.tag == null ? null : <span className="tid">{name.tag}</span>}{name.title}</span>
-            <span className={`tdur ${s.durTone ?? ''}`}>{s.dur}</span>
+            <span className={`tdur ${s.durTone ?? ''}`} title={s.dur === '' ? undefined : s.dur}>{s.dur === '' ? null : <Icon d={ICON.clock} />}</span>
             <span className="tnote">
                 {s.count == null ? s.note : <>{s.count.reds > 0 ? <b>{s.count.reds}</b> : null} {s.count.total}</>}
             </span>