rvlib-shipkit 0.38.0 → 1.0.0

package/src/serve/hub-app/index.html

@@ -5,6 +5,8 @@
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>hub</title>
   <link rel="stylesheet" href="./hub.css" />
+  <link rel="stylesheet" href="./project-gutter.css" />
+  <link rel="stylesheet" href="./prose-hits.css" />
 </head>
 <body>
   <div id="root"></div>

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

@@ -0,0 +1,174 @@
+// The live strip under the header, as the page holds it: `/api/live.json`
+// read every second (the runs of the last ten minutes, the ones in flight,
+// here and in the other house repos), whether the strip is folded, and the
+// chart it draws. Folded, the chart is the thin rolling window of the last
+// two minutes; unfolded, the whole record (the recent runs of /api/live.json
+// over the older ones of /api/timeline.json), opened on its last ten minutes
+// and fit to all of it on demand. It is the hub's one run chart
+// (chart-view.ts, timeline-chart.tsx).
+import { makeAutoObservable, observableRef, runInAction } from 'mobx'
+import type { LiveView } from '../../ledger/live-timeline.ts'
+import type { TimelineInvocation } from '../../ledger/run-timeline.ts'
+import { ChartView, type ChartSource } from './chart-view.ts'
+import type { HubSt } from './hub-st.ts'
+import { chartHeight } from './timeline-geometry.ts'
+
+/** how often the page asks. A strip a second behind the runner is still live */
+export const LIVE_POLL_MS = 1_000
+/** the folded strip's window, and the span the unfolded one opens on */
+export const FOLDED_WINDOW_MS = 120_000
+export const OPEN_WINDOW_MS = 600_000
+/** the most the unfolded chart grows to: past it the lanes scroll inside it */
+export const OPEN_MAX_H = 320
+/** how long the unfolded chart keeps a height its lanes no longer fill,
+ *  so it grows at once and never shrinks under the eye every second */
+export const HEIGHT_HOLD_MS = 10_000
+
+/** the height the unfolded chart shows: up at once, down only once the
+ *  lanes have wanted less for HEIGHT_HOLD_MS */
+export type HeldHeight = { h: number; lowSince: number | null }
+export function settleHeight(prev: HeldHeight, wanted: number, now: number, holdMs = HEIGHT_HOLD_MS): HeldHeight {
+    if (wanted >= prev.h) return { h: wanted, lowSince: null }
+    if (prev.lowSince == null) return { h: prev.h, lowSince: now }
+    return now - prev.lowSince >= holdMs ? { h: wanted, lowSince: null } : prev
+}
+
+/** the whole record the unfolded chart draws: every run of the live view,
+ *  then the older runs of the record it does not carry, newest first */
+export function mergeRuns(recent: TimelineInvocation[], record: TimelineInvocation[]): TimelineInvocation[] {
+    const seen = new Set(recent.map((i) => i.runId))
+    return [...recent, ...record.filter((i) => !seen.has(i.runId))].sort((a, b) => b.started - a.started)
+}
+/** the lanes the folded strip has room for */
+export const FOLDED_LANES = 5
+
+/** where the fold is remembered. localStorage is per origin and every
+ *  repo's hub has its own port, so this is per repo already */
+export const OPEN_KEY = 'hub:liveOpen'
+
+const readOpen = (): boolean => {
+    try { return globalThis.localStorage?.getItem(OPEN_KEY) === '1' } catch { return false }
+}
+
+/** the server clock now: the view's stamp plus what the page clock has
+ *  counted since it arrived, since the page may be another machine */
+export const serverNow = (view: LiveView, receivedAt: number, clientNow: number): number => view.now + Math.max(0, clientNow - receivedAt)
+
+/** what the chart draws: folded, the rolling two minutes; open, the whole
+ *  record, opening on its last ten */
+export function liveSource(view: LiveView | null, now: number, open: boolean, record: TimelineInvocation[] = []): ChartSource | null {
+    if (view == null) return null
+    if (!open) return { invocations: view.invocations, now, windowMs: FOLDED_WINDOW_MS, laneCap: Math.max(1, FOLDED_LANES - view.repos.length), zoomable: false, cap: view.cap }
+    return { invocations: mergeRuns(view.invocations, record), now, windowMs: null, zoomable: true, cap: view.cap, homeSpanMs: OPEN_WINDOW_MS }
+}
+
+export class LiveSvc {
+    view: LiveView | null = null
+    /** the page clock when `view` arrived */
+    receivedAt = 0
+    error = ''
+    /** a short answer to a click (a repo whose hub is not serving) */
+    note = ''
+    open = readOpen()
+    /** the unfolded chart's height, held so it does not jump every second */
+    held: HeldHeight = { h: 0, lowSince: null }
+    chart: ChartView
+    private timer: ReturnType<typeof setInterval> | null = null
+    private inFlight = false
+
+    constructor(private st: HubSt) {
+        this.chart = new ChartView(null, () => liveSource(this.view, this.now, this.open, this.st.timeline.data?.invocations ?? []))
+        makeAutoObservable<this, 'st' | 'timer' | 'inFlight'>(this, { st: false, timer: false, inFlight: false, view: observableRef, chart: false })
+    }
+
+    /** the server clock, as of the page clock's last tick */
+    get now(): number {
+        return this.view == null ? this.st.clock.now : serverNow(this.view, this.receivedAt, this.st.clock.now)
+    }
+
+    toggle(): void {
+        this.open = !this.open
+        try { globalThis.localStorage?.setItem(OPEN_KEY, this.open ? '1' : '0') } catch { /* private window: the fold lasts the tab */ }
+        // either fold starts live: the folded strip is a trail, nothing else
+        this.chart.attach()
+        this.opened()
+    }
+
+    /** unfolded: back to the last ten minutes, the older record fetched, and
+     *  a height from the lanes as they are */
+    private opened(): void {
+        if (!this.open) return
+        this.chart.home()
+        this.chart.attach()
+        this.held = { h: 0, lowSince: null }
+        this.settle(this.st.clock.now)
+        if (this.st.timeline.data == null) void this.st.timeline.load()
+    }
+
+    /** the height the lanes want now, as the held rule lets it show */
+    settle(now: number): void {
+        const l = this.chart.layout
+        const lanes = (l?.lanes ?? 0) + (this.view?.repos.length ?? 0)
+        this.held = settleHeight(this.held, Math.min(OPEN_MAX_H, chartHeight(lanes)), now)
+    }
+
+    start(): void {
+        if (this.timer != null) return
+        this.opened()
+        void this.poll()
+        this.timer = setInterval(() => void this.poll(), LIVE_POLL_MS)
+    }
+    dispose(): void {
+        if (this.timer != null) clearInterval(this.timer)
+        this.timer = null
+    }
+
+    async poll(): Promise<void> {
+        // a slow answer must not stack a second request behind it
+        if (this.inFlight) return
+        this.inFlight = true
+        try {
+            const r = await fetch('/api/live.json')
+            if (!r.ok) throw new Error(await r.text())
+            const v = (await r.json()) as LiveView
+            const ended = this.running && v.runs.length === 0
+            runInAction(() => {
+                this.view = v
+                this.receivedAt = Date.now()
+                this.error = ''
+                if (this.open) this.settle(Date.now())
+            })
+            // a run that ended, from a terminal as much as from a button,
+            // wrote new numbers: the rows and the timeline read them now
+            // rather than on the next ten second poll
+            if (ended) {
+                void this.st.cols.poll()
+                if (this.st.timeline.data != null) void this.st.timeline.load()
+            }
+        } catch (e) {
+            runInAction(() => { this.error = `the live runs could not be read: ${(e as Error).message}` })
+        } finally {
+            this.inFlight = false
+        }
+    }
+
+    get running(): boolean {
+        return (this.view?.runs.length ?? 0) > 0
+    }
+
+    /** a repo lane was clicked: its hub, when it serves */
+    async openRepo(repo: string): Promise<void> {
+        try {
+            const r = (await (await fetch(`/api/repo-hub?repo=${encodeURIComponent(repo)}`)).json()) as { url: string | null }
+            if (r.url != null) window.open(r.url, '_blank')
+            else this.say(`${repo} has no hub serving`)
+        } catch (e) {
+            this.say(`${repo}: ${(e as Error).message}`)
+        }
+    }
+
+    private say(text: string): void {
+        runInAction(() => { this.note = text })
+        setTimeout(() => runInAction(() => { if (this.note === text) this.note = '' }), 4_000)
+    }
+}

package/src/serve/hub-app/md.ts

@@ -22,3 +22,18 @@ export const renderMd = (src: string): string =>
             a: (tagName, attribs) => ({ tagName, attribs: { ...attribs, target: '_blank', rel: 'noreferrer' } }),
         },
     })
+
+/** ONE LINE of markdown, for text that already carries a line structure of
+ *  its own. A wire line keeps its prefix and its place in the log, and the
+ *  backtick spans and urls inside it still render: no block tag survives the
+ *  allowlist, so nothing here can break the line it was given. */
+export const renderMdInline = (src: string): string =>
+    sanitizeHtml(marked.parseInline(src) as string, {
+        allowedTags: ['code', 'strong', 'em', 'b', 'i', 'a'],
+        allowedAttributes: { a: ['href', 'target', 'rel'] },
+        allowedSchemes: ['http', 'https'],
+        allowProtocolRelative: false,
+        transformTags: {
+            a: (tagName, attribs) => ({ tagName, attribs: { ...attribs, target: '_blank', rel: 'noreferrer' } }),
+        },
+    })

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

@@ -552,7 +552,10 @@ export class MediaSvc {
         if (k === 'ArrowRight' && i < rolls.length - 1) this.setActive(rolls[i + 1]!.name)
         else if (k === 'ArrowLeft' && i > 0) this.setActive(rolls[i - 1]!.name)
         else if (k === 'Enter' && this.active != null) void this.pick(this.active)
-        else if ((k === 'a' || k === 'A') && this.active != null) void this.alt(this.active)
+        // SHIFT+A only, the binding the help line prints: a bare `a` belongs
+        // to the page (the all/needs/red filter), and a letter bound in both
+        // places is bound in neither
+        else if (k === 'A' && this.active != null) void this.alt(this.active)
         else if ((k === 'x' || k === 'X') && this.active != null) void this.discard(this.active)
         else return false
         return true

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

@@ -144,6 +144,10 @@ export const ToolsBar = observer(({ app }: { app: HubSt }) => {
     const label = (id: string): string =>
         id === 'json' ? 'asset json' : id === 'meta' ? 'roll meta' : id.startsWith('c:') ? id.slice(2) : id
     const cur = [...m.tools].sort().join(',')
+    // one draft per KIND, never per asset: tuning the loras for the road rat is
+    // tuning them for all 107 creatures, which is the point of a shared draft
+    const wfId = d.info?.workflow?.id ?? null
+    const kindId = d.info?.kindId ?? 'default'
     return (
         <div className="toolsbar">
             {/* tabs = tool presets (kit-declared first) — switching swaps the
@@ -157,6 +161,12 @@ export const ToolsBar = observer(({ app }: { app: HubSt }) => {
             {m.validTools(d).map((id) => (
                 <button key={id} className={`chip${m.tools.has(id) ? ' on' : ''}`} onClick={() => m.toggleTool(id)}>{label(id)}</button>
             ))}
+            {/* the workflow behind this asset, tuned where the asset already is.
+                Only on an asset a comfy workflow actually draws */}
+            {wfId != null ? (
+                <button className="chip" title={`tune ${wfId} for every ${kindId} asset`}
+                    onClick={() => void app.comfy.tune(wfId, kindId)}>tune workflow</button>
+            ) : null}
             <span className="sp" />
             <button className="ghost" onClick={() => m.toggleVariants()}>
                 {m.variantsOpen ? 'variants ▸' : `variants (${d.rolls.length}) ◂`}
@@ -263,6 +273,11 @@ export const CatGrid = observer(({ app }: { app: HubSt }) => {
                 <label>size for ALL {cat} <input type="number" step={0.1} min={0.1} value={m.allSize}
                     onChange={(e) => runInAction(() => { m.allSize = e.target.value })} /></label>
                 <button className="ghost" onClick={() => void m.applyAllSize()}>apply</button>
+                {/* rolls for the whole category, the one control the tree
+                    has no row to carry */}
+                {m.catRows.every((r) => m.assets.find((a) => a.id === r.id)?.manual === true) ? null : (
+                    <span className="catgen">{[1, 2, 3].map((n) => <button key={n} className="ghost" onClick={() => void m.genCat(cat, n)}>+{n}</button>)}</span>
+                )}
                 <span className="jmsg">{m.allMsg}</span>
             </div>
             <div className="cards">

package/src/serve/hub-app/next-run.ts

@@ -0,0 +1,68 @@
+// WHEN A CHECK RUNS NEXT, as a true statement. Nothing runs a check on a clock
+// except the hub's daily health pass (serve/health-schedule.ts), so the answer
+// is read off where the check runs (`when`), what it remembers, and that one
+// timer. Pure, so every case is pinned by a test rather than a screenshot.
+import type { Schedule, CheckFacts } from './hub-types.ts'
+
+export type NextRun = {
+    /** the value the page shows */
+    words: string
+    /** the exact moment, when there is one: the tooltip's stamp */
+    at: number | null
+    /** the sentence behind the value, for the row's help */
+    help: string
+}
+
+const MIN = 60_000
+const HOUR = 60 * MIN
+const DAY = 24 * HOUR
+
+/** a span ahead, in the two largest units: `~14h`, `~3d11h`, `~25m` */
+export function aheadWords(ms: number): string {
+    if (ms < MIN) return '<1m'
+    if (ms < HOUR) return `~${Math.round(ms / MIN)}m`
+    if (ms < DAY) return `~${Math.round(ms / HOUR)}h`
+    let d = Math.floor(ms / DAY)
+    let h = Math.round((ms - d * DAY) / HOUR)
+    if (h === 24) { d++; h = 0 }
+    return `~${d}d${h > 0 ? `${h}h` : ''}`
+}
+
+/** a span as a rhythm: `24h`, `3d`, `90m`. Whole days read as days from two
+ *  days up, because `every ~72h` makes a reader do the division */
+export function spanWords(ms: number): string {
+    if (ms >= 2 * DAY && ms % DAY === 0) return `${ms / DAY}d`
+    if (ms >= HOUR) return `${Math.round((ms / HOUR) * 10) / 10}h`
+    if (ms >= MIN) return `${Math.round(ms / MIN)}m`
+    return `${Math.round(ms / 1000)}s`
+}
+
+export type NextRunFacts = Pick<CheckFacts, 'when' | 'whenReason'> & { keepsUntil?: number | null }
+
+export function nextRun(u: NextRunFacts, s: Schedule | null, now: number): NextRun {
+    if (u.when === 'always')
+        return { words: 'next shipkit ci', at: null, help: 'it runs on every `shipkit ci` and in every health pass. A cached answer is used when nothing it depends on moved' }
+    if (u.when === 'release')
+        return { words: 'before a release', at: null, help: '`shipkit ci --full` and the release path run it, and so does the health pass. The quick gate you run while working does not' }
+    if (u.when === 'off')
+        return { words: u.whenReason != null && u.whenReason !== '' ? `never: ${u.whenReason}` : 'never', at: null, help: 'it is off: nothing runs it until the switch below puts it somewhere' }
+    if (s == null)
+        return { words: 'next health pass', at: null, help: 'this hub runs no daily timer, so it runs when `shipkit check` runs or when you press run the health pass' }
+    if (s.running) return { words: 'running now', at: now, help: 'the daily health pass is running right now' }
+    const pass = Math.max(now, s.nextAt)
+    const keeps = u.keepsUntil ?? null
+    if (keeps != null && keeps > pass) {
+        const k = Math.ceil((keeps - pass) / s.everyMs)
+        const at = pass + k * s.everyMs
+        return {
+            words: `in ${aheadWords(at - now)}`,
+            at,
+            help: `the health pass runs every ${spanWords(s.everyMs)}, and uses this check's cached answer until it runs out. The first pass after that runs it again`,
+        }
+    }
+    return {
+        words: pass <= now ? 'due now' : `in ${aheadWords(pass - now)}`,
+        at: pass,
+        help: `the next health pass: the hub runs it every ${spanWords(s.everyMs)} while it serves, and at startup when the last one is older than that`,
+    }
+}

package/src/serve/hub-app/project-gutter.css

@@ -0,0 +1,65 @@
+/* the project gutter. It is FIXED to the left edge, so it takes no cell of
+   the .app grid, and the page makes room for it by padding, whatever the
+   grid holds. Colours are hub.css tokens only, spacing is its scale:
+   tests/hub-css-invariants.test.ts reads this sheet too. */
+.app:has(> .pgut){--gut:44px;padding-left:var(--gut)}
+.pgut{position:fixed;left:0;top:0;bottom:0;width:var(--gut,44px);z-index:5;display:flex;flex-direction:column;align-items:center;
+ gap:var(--s1);padding:var(--s2) 0;background:var(--bg);border-right:1px solid var(--line);overflow-y:auto;scrollbar-width:none}
+.pgt{position:relative;flex:none;width:32px;height:32px;display:flex;align-items:center;justify-content:center;padding:0;
+ background:transparent;border:0;border-radius:6px;cursor:pointer}
+.pgt:hover{background:var(--panel2)}
+.pgt.cur{background:var(--sel)}
+.pgt img{width:24px;height:24px;border-radius:5px;object-fit:cover;pointer-events:none}
+/* the initial on a hue hashed from the name (projects-svc hueOf) */
+.pgi{width:24px;height:24px;border-radius:5px;display:flex;align-items:center;justify-content:center;
+ font-size:12px;font-weight:600;user-select:none;color:var(--c);background:color-mix(in srgb,var(--c) 22%,var(--panel2))}
+.pgi.h1{--c:var(--k1)}
+.pgi.h2{--c:var(--k2)}
+.pgi.h3{--c:var(--k3)}
+.pgi.h4{--c:var(--k4)}
+.pgi.h5{--c:var(--k5)}
+.pgi.h6{--c:var(--k6)}
+/* the face says three things and no more (projects-svc faceOf) */
+/* closed in VS Code: the icon dims, the badge does not */
+.pgt.dim img,.pgt.dim .pgi{opacity:.45}
+/* the one badge: open asks, top right */
+.pga{position:absolute;top:0;right:0;min-width:14px;height:14px;padding:0 var(--s0);border-radius:7px;
+ font-size:9px;font-weight:700;line-height:14px;text-align:center;color:var(--bg);background:var(--warn)}
+/* Claude sessions running: a thin edge on the left that breathes */
+.pgs{position:absolute;left:0;top:6px;bottom:6px;width:2px;border-radius:1px;background:var(--accent);pointer-events:none;animation:pgpulse 2.4s ease-in-out infinite}
+@keyframes pgpulse{0%,100%{opacity:1}50%{opacity:.25}}
+@media (prefers-reduced-motion:reduce){.pgs{animation:none}}
+/* the hover card: right of the rail, one at a time, never interactive.
+   Header, then what needs a human, then the label and value rows of the
+   check page (.wfact .wk .wv from hub.css) */
+.pgcard{position:fixed;left:calc(var(--gut,44px) + var(--s2));z-index:20;width:300px;padding:var(--s3);pointer-events:none;
+ background:var(--panel);border:1px solid var(--line);border-radius:4px;box-shadow:0 6px 20px var(--shadow);font-size:12px;line-height:1.45;color:var(--ink)}
+.pgch{display:flex;align-items:center;gap:var(--s2);min-width:0}
+.pgcface{flex:none;display:flex}
+.pgcface img,.pgcface .pgi{width:20px;height:20px;border-radius:4px;font-size:11px}
+.pgcname{flex:1;min-width:0;font-size:13px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.pgcthis{font-weight:400;font-size:11px;color:var(--dim)}
+.pgcver{flex:none;color:var(--dim);font-size:11px;font-variant-numeric:tabular-nums}
+.pgcline{margin-top:var(--s1);color:var(--dim);font-size:11px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.pgcdesc{margin-top:var(--s1);color:var(--dim);font-size:11px;display:-webkit-box;-webkit-box-orient:vertical;-webkit-line-clamp:2;overflow:hidden}
+/* NEEDS YOU: a warn toned bullet, set apart from the facts */
+.pgcneeds{margin-top:var(--s2);padding:var(--s1) var(--s2);border-left:2px solid var(--warn);background:var(--panel2);border-radius:0 3px 3px 0}
+.pgcneed{display:flex;gap:var(--s1);min-width:0;color:var(--warn)}
+.pgcneed.red{color:var(--red);white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.pgcask{flex:1;min-width:0;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.pgcmore{flex:none}
+.pgcfacts{margin-top:var(--s2)}
+.pgcfacts .wk{flex-basis:64px;white-space:nowrap}
+.pgcfacts .wv{text-align:right;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;word-break:normal}
+.pgcfacts .wv.warn{color:var(--warn)}
+.pgerr{font-size:12px;font-weight:700;color:var(--red);cursor:help}
+/* the one time sort by last activity, above the icons */
+.pgsort{flex:none;width:32px;height:20px;padding:0;background:transparent;border:1px solid var(--line);border-radius:3px;
+ color:var(--dim);font-size:12px;line-height:18px;cursor:pointer}
+.pgsort:hover{color:var(--ink);border-color:var(--accent)}
+/* a drag: the tile being moved fades, and the gap it would land in is a line
+   drawn on a tile edge, centred in the gap between two tiles */
+.pgt.dragging{opacity:.4}
+.pgt.dropb::before,.pgt.dropa::after{content:'';position:absolute;left:2px;right:2px;height:2px;border-radius:1px;background:var(--accent);pointer-events:none}
+.pgt.dropb::before{top:-3px}
+.pgt.dropa::after{bottom:-3px}

package/src/serve/hub-app/project-gutter.tsx

@@ -0,0 +1,128 @@
+// the project gutter: one icon per repo that shares this hub's house wiki,
+// down the far left of the page. The face stays quiet (faceOf): at most one
+// badge, the open asks; the icon dims while VS Code does not have the folder
+// open; a thin edge pulses while Claude sessions run in it; the selected
+// background marks this hub's own repo. Everything else is the hover card,
+// shown at once to the right of the icon. A click opens the folder in VS
+// Code, a drag reorders the rail, and the button on top sorts it once by
+// last activity. Fixed position, so it takes no cell of the page grid
+// (project-gutter.css).
+import { observer } from 'mobx-react-lite'
+import { useEffect, useLayoutEffect, useRef } from 'react'
+import type { HubSt } from './hub-st.ts'
+import { cardModel, faceOf, hueOf, type Project } from './projects-svc.ts'
+
+export const Tile = observer(({ app, p, i }: { app: HubSt; p: Project; i: number }) => {
+    const s = app.projects
+    const gap = s.shownGap
+    const face = faceOf(p)
+    // the drop line rides on a tile edge, so showing it moves nothing
+    const edge = gap === i ? ' dropb' : gap === i + 1 && i === s.list.length - 1 ? ' dropa' : ''
+    const cls = `pgt${p.current ? ' cur' : ''}${face.dim ? ' dim' : ''}${s.drag === p.name ? ' dragging' : ''}${edge}`
+    return (
+    <button className={cls} aria-label={p.name}
+        draggable onClick={() => void s.open(p.name)}
+        onMouseEnter={(e) => {
+            const r = e.currentTarget.getBoundingClientRect()
+            s.hoverIn(p.name, r.top + r.height / 2)
+        }}
+        onMouseLeave={() => s.hoverOut(p.name)}
+        onDragStart={(e) => {
+            e.dataTransfer.effectAllowed = 'move'
+            e.dataTransfer.setData('text/plain', p.name)
+            s.dragStart(p.name)
+        }}
+        onDragOver={(e) => {
+            if (s.drag == null) return
+            e.preventDefault()
+            const r = e.currentTarget.getBoundingClientRect()
+            s.dragOver(i, e.clientY - r.top, r.height)
+        }}
+        onDrop={(e) => {
+            e.preventDefault()
+            s.drop()
+        }}
+        onDragEnd={() => s.dragEnd()}>
+        <Face p={p} />
+        {face.badge != null ? <b className="pga">{face.badge}</b> : null}
+        {face.busy ? <i className="pgs" /> : null}
+    </button>
+    )
+})
+
+const Face = ({ p }: { p: Project }) => (p.icon != null
+    ? <img src={p.icon} alt="" draggable={false} />
+    : <span className={`pgi h${hueOf(p.name)}`}>{(p.name.match(/[a-zA-Z]/)?.[0] ?? p.name.charAt(0)).toUpperCase()}</span>)
+
+/** the card for one repo: header, what needs a human, then the fact rows,
+ *  in the label and value shape the check page's WHAT widget uses */
+export const Card = ({ p, now }: { p: Project; now: number }) => {
+    const m = cardModel(p, now)
+    return (
+        <>
+            <div className="pgch">
+                <span className="pgcface"><Face p={p} /></span>
+                <b className="pgcname">{m.head.name}{m.head.current ? <span className="pgcthis"> this hub</span> : null}</b>
+                {m.head.version == null ? null : <span className="pgcver">v{m.head.version.replace(/^v/, '')}</span>}
+            </div>
+            {m.head.branch == null ? null : <div className="pgcline">{m.head.branch}</div>}
+            {m.head.description == null ? null : <div className="pgcdesc">{m.head.description}</div>}
+            {m.needs == null ? null : (
+                <div className="pgcneeds">
+                    {m.needs.asks == null ? null : (
+                        <div className="pgcneed">
+                            <span className="pgcask">{m.needs.asks.count} ask{m.needs.asks.count === 1 ? '' : 's'}: {m.needs.asks.titles.join(' · ')}</span>
+                            {m.needs.asks.more > 0 ? <span className="pgcmore">+{m.needs.asks.more}</span> : null}
+                        </div>
+                    )}
+                    {m.needs.gate == null ? null : <div className="pgcneed red">{m.needs.gate}</div>}
+                </div>
+            )}
+            {m.facts.length === 0 ? null : (
+                <div className="pgcfacts">
+                    {m.facts.map((f) => (
+                        <div key={f.k} className="wfact">
+                            <span className="wk">{f.k}</span>
+                            <span className={`wv${f.tone == null ? '' : ` ${f.tone}`}`}>{f.v}</span>
+                        </div>
+                    ))}
+                </div>
+            )}
+        </>
+    )
+}
+
+/** the one hover card: right of the rail, centred on the icon's row, then
+ *  clamped into the viewport once its own height is known */
+export const HoverCard = observer(({ app }: { app: HubSt }) => {
+    const s = app.projects
+    const p = s.hovered
+    const y = s.hover?.y ?? 0
+    const ref = useRef<HTMLDivElement>(null)
+    useLayoutEffect(() => {
+        const el = ref.current
+        if (el == null) return
+        const h = el.offsetHeight
+        el.style.top = `${Math.max(8, Math.min(y - h / 2, window.innerHeight - h - 8))}px`
+    })
+    if (p == null) return null
+    return (
+        <div ref={ref} className="pgcard" role="tooltip">
+            <Card p={p} now={Date.now()} />
+        </div>
+    )
+})
+
+export const ProjectGutter = observer(({ app }: { app: HubSt }) => {
+    useEffect(() => app.projects.start(), [app])
+    const s = app.projects
+    if (s.list.length === 0 && s.error === '') return null
+    return (
+        <nav className="pgut" aria-label="projects">
+            <button className="pgsort" title="sort by last activity, once: the result is the new manual order" onClick={() => s.sortByActivity()}>⇅</button>
+            {s.list.map((p, i) => <Tile key={p.name} app={app} p={p} i={i} />)}
+            {s.error !== '' ? <span className="pgerr" title={s.error}>!</span> : null}
+            <HoverCard app={app} />
+        </nav>
+    )
+})