rvlib-shipkit 1.1.0 → 1.2.0

package/src/repo-config.ts

@@ -59,6 +59,27 @@ export type ServeConfig = {
      *  prints beside localhost and rides on every ping message, because a
      *  phone cannot resolve localhost */
     publicHost?: string
+    /** the long running processes this repo needs (a dev server, a watcher).
+     *  The hub supervises them: a switch each on its page, a crash restarts,
+     *  and they outlive a hub restart */
+    processes?: ProcessDecl[]
+    /** the ids of the global processes this repo needs (any house repo's
+     *  `globalProcess` unit files). The home rail marks the repo while one is off */
+    uses?: string[]
+}
+
+/** one long running process a repo needs, supervised by its hub */
+export type ProcessDecl = {
+    /** kebab-case, unique in this repo */
+    id: string
+    /** the command as a list of words, run from the repo root */
+    cmd: string[]
+    /** where it runs, repo-relative (default the repo root) */
+    cwd?: string
+    /** the url it serves, probed for up and shown as a link */
+    url?: string
+    /** starts with the hub. Default false: it starts from its switch */
+    auto?: boolean
 }
 
 export type RepoConfig = {
@@ -250,13 +271,34 @@ export type RepoConfig = {
     }
     /** the `shipkit serve` hub: port + optional graph hooks */
     serve?: ServeConfig
+    /** the repo's own colours, one #rrggbb hex each: colorLight reads on a
+     *  light background, colorDark on a dark one. Every page that shows the
+     *  repo draws its name and its rail tile in them. Rule SK024 warns when
+     *  they are missing, and its fix derives them from the repo icon */
+    identity?: {
+        /** #rrggbb that reads on a light background */
+        colorLight: string
+        /** #rrggbb that reads on a dark background: the home page draws this one */
+        colorDark: string
+    }
     /** where a gate run writes its per task logs, repo-relative (default
      *  '.shipkit/tmp/shipkit-ci'). Each run owns a subdir of it, so several agents in
      *  one checkout never overwrite each other. Keep it gitignored. */
     logDir?: string
 }
 
-const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'credsReadCommand', 'notifyCommand', 'contracts', 'gitignore', 'untrackGenerated', 'nested', 'when', 'budgets', 'ruleExempt', 'visibility', 'reviewer', 'oneWayIn', 'rules', 'release', 'units', 'notReleasable', 'hooks', 'checkDefaults', 'tui', 'serve', 'logDir', 'prose', 'smoke', 'tests'])
+const KNOWN_KEYS = new Set(['name', 'venues', 'social', 'docsBase', 'defaults', 'tasks', 'asks', 'creds', 'credsCommand', 'credsReadCommand', 'notifyCommand', 'contracts', 'gitignore', 'untrackGenerated', 'nested', 'when', 'budgets', 'ruleExempt', 'visibility', 'reviewer', 'oneWayIn', 'rules', 'release', 'units', 'notReleasable', 'hooks', 'checkDefaults', 'tui', 'serve', 'identity', 'logDir', 'prose', 'smoke', 'tests'])
+
+const KEBAB = /^[a-z0-9][a-z0-9-]*$/
+const words = (v: unknown): boolean => Array.isArray(v) && v.length > 0 && v.every((w) => typeof w === 'string')
+
+/** why a process declaration cannot run, or null */
+export function processProblem(d: ProcessDecl): string | null {
+    if (!KEBAB.test(d.id ?? '')) return `serve.processes: id '${String(d.id)}' must be kebab-case`
+    if (!words(d.cmd)) return `serve.processes['${d.id}'] needs cmd: a list of words`
+    if (d.url != null && !/^https?:\/\//.test(d.url)) return `serve.processes['${d.id}'].url must be an http url`
+    return null
+}
 
 export function defineRepo(c: RepoConfig): RepoConfig {
     if (typeof c.name !== 'string' || c.name === '') throw new Error('defineRepo: name is required')
@@ -266,11 +308,18 @@ export function defineRepo(c: RepoConfig): RepoConfig {
     // a half-declared reviewer would lint a path like `.claude/agents/.md`
     if (c.reviewer != null && (!/^[a-z0-9][a-z0-9-]*$/.test(c.reviewer.name ?? '') || (c.reviewer.brief ?? '') === ''))
         throw new Error(`defineRepo: reviewer needs { name: kebab-case, brief: path to the standing brief }`)
+    const pids = new Set<string>()
+    for (const d of c.serve?.processes ?? []) {
+        const why = processProblem(d)
+        if (why != null) throw new Error(`defineRepo: ${why}`)
+        if (pids.has(d.id)) throw new Error(`defineRepo: serve.processes declares '${d.id}' twice`)
+        pids.add(d.id)
+    }
     // unknown keys die loud — a typo'd or removed key silently changing the
     // gate is exactly the never-silence failure mode (A23)
     for (const k of Object.keys(c))
         if (!KNOWN_KEYS.has(k))
-            throw new Error(`defineRepo: unknown key '${k}'${k === 'checks' ? ` — checks:[] was removed; drop a <name>.check.ts file instead ('shipkit check' auto-discovers it)` : ''}`)
+            throw new Error(`defineRepo: unknown key '${k}'${k === 'checks' ? ` — checks:[] was removed; drop a <name>.check.ts file instead ('shipkit check' auto-discovers it)` : k === 'home' ? ` — home.resources was removed; declare each one in a <name>.shipkit.ts file as \`export default globalProcess({...})\`` : ''}`)
     // a typo'd unit key would silently drop a target and release the wrong shape
     for (const u of c.units ?? []) {
         if (typeof u.dir !== 'string' || u.dir === '') throw new Error(`defineRepo: every units[] entry needs a 'dir'`)

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

@@ -8,7 +8,7 @@ import { useEffect, useRef } from 'react'
 import { CACHED } from '../../core/outcome-words.ts'
 import { durationTone, fmtMs } from './dur.ts'
 import { Help, TERMS } from './help.tsx'
-import type { HubSt } from './hub-st.ts'
+import type { RepoSt } from './repo-st.ts'
 import type { SlowSuite, CheckFacts, RecentRun, WhenAt } from './hub-types.ts'
 import { renderMd, renderMdInline } from './md.ts'
 import { nextRun } from './next-run.ts'
@@ -89,7 +89,7 @@ export const copy = (text: string): void => {
 
 /** THE COMMAND, exactly as the gate spawns it from the repo root, or the one
  *  line saying its body is a function inside the gate */
-export const CommandLine = ({ app, u }: { app: HubSt; u: CheckFacts }) => {
+export const CommandLine = ({ app, u }: { app: RepoSt; u: CheckFacts }) => {
     const c = commandOf(u, app.root)
     if (c.kind === 'in-process')
         return (
@@ -132,7 +132,7 @@ export const CommandLine = ({ app, u }: { app: HubSt; u: CheckFacts }) => {
  *  through the managed block, and leaves the file dirty: a change of place is
  *  a change its owner reviews in a git client, never a commit made on their
  *  behalf. Choosing never asks for the reason before it writes. */
-const RunWhen = observer(({ app, u }: { app: HubSt; u: CheckFacts }) => {
+const RunWhen = observer(({ app, u }: { app: RepoSt; u: CheckFacts }) => {
     const s = app.checks
     const g = s.gate
     const shown = s.whenShown(u)
@@ -193,7 +193,7 @@ const Bars = ({ runs, ceiling, budget }: { runs: RecentRun[]; ceiling: number; b
 }
 
 /** how the last answer came: `ran 3m ago in 412ms`, or `cached 16m ago` */
-export const LastRunValue = observer(({ app, u }: { app: HubSt; u: CheckFacts }) => {
+export const LastRunValue = observer(({ app, u }: { app: RepoSt; u: CheckFacts }) => {
     const l = lastRun(u)
     if (l == null) return <span className="dim">never here</span>
     return (
@@ -245,7 +245,7 @@ const LogLines = ({ lines }: { lines: string[] }) => (
 
 /** the lines of the run in flight, then the lines of the last one. It
  *  scrolls itself while a run streams, so the newest line is on screen */
-const LastOutput = observer(({ app, lines }: { app: HubSt; lines: string[] }) => {
+const LastOutput = observer(({ app, lines }: { app: RepoSt; lines: string[] }) => {
     const live = app.checks.liveLines
     const box = useRef<HTMLPreElement>(null)
     useEffect(() => { if (box.current != null) box.current.scrollTop = box.current.scrollHeight }, [live.length])
@@ -263,7 +263,7 @@ const LastOutput = observer(({ app, lines }: { app: HubSt; lines: string[] }) =>
 /** the slow suites declared under the test step, each with the case it
  *  argued. Moving a suite between the tiers is the SAME managed block write,
  *  and it demands both answers exactly as `defineRepo` does. */
-const SlowSuites = observer(({ app }: { app: HubSt }) => {
+const SlowSuites = observer(({ app }: { app: RepoSt }) => {
     const s = app.checks
     const declared: SlowSuite[] = s.gate?.tests.slow ?? []
     return (
@@ -294,7 +294,7 @@ const SlowSuites = observer(({ app }: { app: HubSt }) => {
 
 // ── the pages ────────────────────────────────────────────────────────────
 
-export const CheckCard = observer(({ app, id }: { app: HubSt; id: string }) => {
+export const CheckCard = observer(({ app, id }: { app: RepoSt; id: string }) => {
     const i = app.cols.find('checks', id)
     if (i == null) return <div className="ph">check vanished, the inventory moved on</div>
     const u = i.check
@@ -325,8 +325,8 @@ export const CheckCard = observer(({ app, id }: { app: HubSt; id: string }) => {
                 <Remembered u={u} />
                 {/* the help never depends on the second, so it reads the wall
                     clock and the row does not repaint on every tick */}
-                <Row k="next run" help={nextRun(u, app.cols.schedule, Date.now()).help}>
-                    <TimeAhead clock={app.clock} words={(now) => nextRun(u, app.cols.schedule, now)} />
+                <Row k="next run" help={nextRun(u, app.cols.planOf(u.checkId), Date.now()).help}>
+                    <TimeAhead clock={app.clock} words={(now) => nextRun(u, app.cols.planOf(u.checkId), now)} />
                 </Row>
                 <Row k="last run" help={u.status == null
                     ? 'no run of it is on record in this checkout'

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

@@ -18,7 +18,7 @@ const list = (xs: string[]): string => (xs.length < 2 ? xs.join('') : `${xs.slic
 const CADENCE: Record<WhenAt, string> = {
     always: 'on every run',
     release: 'on every release run',
-    health: 'on every daily pass',
+    health: 'each time the plan runs it',
     off: 'nowhere, it is off',
 }
 

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

@@ -8,7 +8,7 @@
 // dropped when the run ends and the next poll brings the same facts back
 // from the one place that owns them.
 import { makeAutoObservable, runInAction } from 'mobx'
-import type { HubSt } from './hub-st.ts'
+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'
@@ -42,6 +42,10 @@ export class ChecksSvc {
      *  stay after the run: they ARE the last output until the next one */
     liveLines: string[] = []
     private clearTimer: ReturnType<typeof setTimeout> | null = null
+
+    dispose(): void {
+        if (this.clearTimer != null) clearTimeout(this.clearTimer)
+    }
     /** the managed block in repo.config.ts as the server last sent it: the
      *  hash the next write hands back, and whether the file is waiting for
      *  a commit. null until the first read */
@@ -56,7 +60,7 @@ export class ChecksSvc {
     /** the slow suite form under the test check */
     suite: SlowSuite = { file: '', catches: '', whyNotFast: '' }
 
-    constructor(private st: HubSt) {
+    constructor(private st: RepoSt) {
         makeAutoObservable<this, 'st' | 'clearTimer'>(this, { st: false, clearTimer: false })
     }
 
@@ -89,7 +93,7 @@ export class ChecksSvc {
      *  silent overwrite */
     async loadGate(): Promise<void> {
         try {
-            const r = await fetch('/api/checks/when')
+            const r = await fetch(this.st.url('/api/checks/when'))
             if (!r.ok) throw new Error(await r.text())
             const b = (await r.json()) as GateBlock
             runInAction(() => { this.gate = b })
@@ -109,14 +113,14 @@ export class ChecksSvc {
             // the hash of the file the page last read: without it a write
             // could land on top of an edit this page never saw
             if (this.gate == null) await this.loadGate()
-            const r = await fetch('/api/checks/when', { method: 'POST', body: JSON.stringify({ ...edit, expect: this.gate?.hash }) })
+            const r = await fetch(this.st.url('/api/checks/when'), { method: 'POST', body: JSON.stringify({ ...edit, expect: this.gate?.hash }) })
             if (!r.ok) throw new Error(await r.text())
             const b = (await r.json()) as GateBlock
             runInAction(() => { this.gate = b; this.gateNote = said })
             took = true
             // the rows carry `when`, so they are right only after the server
             // has read the config it just wrote
-            await this.st.cols.poll()
+            await this.st.cols.poll(true)
         } catch (e) {
             runInAction(() => { this.gateNote = `refused: ${(e as Error).message}` })
             // whatever the file really says now, so the next try is not
@@ -227,7 +231,7 @@ export class ChecksSvc {
             this.note = `running ${label}…`
         })
         try {
-            const r = await fetch('/api/check/run', { method: 'POST', body: JSON.stringify({ ...(only == null ? {} : { only }), ...(gate ? { gate } : {}) }) })
+            const r = await fetch(this.st.url('/api/check/run'), { method: 'POST', body: JSON.stringify({ ...(only == null ? {} : { only }), ...(gate ? { gate } : {}) }) })
             const rd = r.body!.getReader()
             const dec = new TextDecoder()
             let buf = ''
@@ -270,9 +274,9 @@ export class ChecksSvc {
         this.clearTimer = setTimeout(() => runInAction(() => { this.progress = idleRun() }), 5_000)
         // the numbers a run just produced live on the server, in the log it
         // wrote: one poll and the page is reading them rather than a memory
-        await this.st.cols.poll()
+        await this.st.cols.poll(true)
         void this.st.health.load()
-        void this.st.timeline.load()
+        void this.st.timeline.load(true)
         // a test page on screen reads the record the run just wrote
         const sel = this.st.sel
         if (sel?.t === 'tests') void this.st.tests.load(sel.check)

package/src/serve/hub-app/col-card.tsx

@@ -5,7 +5,7 @@
 // the file wins).
 import { runInAction } from 'mobx'
 import { observer } from 'mobx-react-lite'
-import type { HubSt } from './hub-st.ts'
+import type { RepoSt } from './repo-st.ts'
 import type { Resource } from './hub-types.ts'
 import { renderMd } from './md.ts'
 
@@ -24,7 +24,7 @@ const CredHead = ({ cred }: { cred: ReturnType<typeof credOf> }) => (
     </>
 )
 
-export const ColCard = observer(({ app, col, id }: { app: HubSt; col: string; id: string }) => {
+export const ColCard = observer(({ app, col, id }: { app: RepoSt; col: string; id: string }) => {
     const c = app.cols
     const i = c.find(col, id)
     if (i == null) return <div className="ph">item vanished — the truth file moved on</div>
@@ -103,7 +103,7 @@ export const ColCard = observer(({ app, col, id }: { app: HubSt; col: string; id
 
 // collection view — one card per visible instance, the stage-side twin of a
 // sidebar section (every section gets both views)
-export const ColGrid = observer(({ app, id }: { app: HubSt; id: string }) => {
+export const ColGrid = observer(({ app, id }: { app: RepoSt; id: string }) => {
     const c = app.cols
     const col = c.sidebarCols.find((x) => x.id === id)
     if (col == null) return <div className="stagewrap"><div className="ph">collection vanished — the truth moved on</div></div>
@@ -155,7 +155,7 @@ const wireClass = (l: string): string => {
 
 // the RAW view of a run: every check has its own page, and this is the one
 // node that keeps the whole text reachable
-export const StatusCard = observer(({ app }: { app: HubSt }) => {
+export const StatusCard = observer(({ app }: { app: RepoSt }) => {
     const h = app.health
     const body = h.live.length > 0
         ? h.live.join('\n')

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

@@ -4,20 +4,40 @@
 // file through /api/act/*; errors come back as 400 text shown verbatim on
 // the card.
 import { makeAutoObservable, runInAction } from 'mobx'
-import type { HubSt } from './hub-st.ts'
-import type { Col, ColMeta, HubProblem, Resource, Schedule } from './hub-types.ts'
+import type { RepoSt } from './repo-st.ts'
+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'
+
+/** what /api/resources.json answers */
+type Answer = { collections: ColMeta[]; resources: Resource[]; planned?: PlanRow[] | null; hub?: HubProblem[] }
 
 export class ColsSvc {
     /** exactly what the server last sent; `resources` is this plus the live
      *  results of a run in flight */
     fetched: Resource[] = []
     colMeta: ColMeta[] = []
-    /** the hub's daily health pass timer, as the last poll saw it */
-    schedule: Schedule | null = null
+    /** this repo's rows of the plan, null when no plan covers it */
+    planned: PlanRow[] | null = null
     /** what the server says is wrong with the hub itself */
     hubProblems: HubProblem[] = []
     /** the last poll failed: the page cannot reach its own server */
     fetchErr: string | null = null
+    /** a first answer arrived: until then the tree and the page links show a
+     *  spinner where they will be, never an empty repo */
+    loaded = false
+    /** what shows was kept by this browser from an earlier load, and the
+     *  hub has not answered yet (screen-cache.ts) */
+    cached = false
+    /** the first media category the kept screen had, until the media
+     *  heartbeat lists the assets */
+    cachedCat: string | null = null
+    /** when this repo's screen was last kept, 0 for never */
+    private keptAt = 0
+    /** the last answer, and the media category last kept with it */
+    private last: Answer | null = null
+    private keptCat: string | null | undefined = undefined
+    private restoring: Promise<void> | null = null
     actErr = ''
     remarkDraft = ''
     proofDraft = ''
@@ -25,30 +45,89 @@ export class ColsSvc {
     foldOverride = new Map<string, boolean>()
     private timer: ReturnType<typeof setInterval> | null = null
 
-    constructor(private st: HubSt) {
-        makeAutoObservable<this, 'st' | 'timer'>(this, { st: false, timer: false })
+    constructor(private st: RepoSt) {
+        makeAutoObservable<this, 'st' | 'timer' | 'keptAt' | 'restoring' | 'readKept' | 'last' | 'keptCat'>(this, { st: false, timer: false, keptAt: false, restoring: false, readKept: false, last: false, keptCat: false })
+    }
+
+    /** one check's row of the plan, null when no plan covers it */
+    planOf(check: string): PlanRow | null {
+        return this.planned?.find((r) => r.check === check) ?? null
+    }
+
+    /** where this repo's screen is kept: its name, or `self` on a hub of its own */
+    private get screenKey(): string {
+        return this.st.key === '' ? 'self' : this.st.key
+    }
+
+    /** paint the screen this browser kept, unless the hub answered first.
+     *  One read per repo, whoever asks */
+    restore(): Promise<void> {
+        this.restoring ??= this.readKept()
+        return this.restoring
+    }
+
+    private async readKept(): Promise<void> {
+        const s = await readScreen(this.screenKey)
+        if (s == null) return
+        runInAction(() => {
+            if (this.loaded) return
+            this.colMeta = s.collections
+            this.fetched = s.resources
+            this.planned = s.planned
+            this.hubProblems = s.hub
+            this.cachedCat = s.mediaCat
+            this.cached = true
+        })
+    }
+
+    /** keep the screen for the next load: the first answer, then at most
+     *  once a minute. The answer as parsed, never the observable copy, which
+     *  IndexedDB cannot clone */
+    private keep(j: Answer, cat: string | null = this.st.media.assets[0]?.cat ?? this.cachedCat, force = false): void {
+        this.last = j
+        const now = Date.now()
+        if (!force && now - this.keptAt < SCREEN_WRITE_MS) return
+        this.keptAt = now
+        this.keptCat = cat
+        void writeScreen(this.screenKey, { at: now, collections: j.collections, resources: j.resources, planned: j.planned ?? null, hub: j.hub ?? [], mediaCat: cat })
+    }
+
+    /** the media heartbeat listed the assets: a first category the kept
+     *  screen does not name yet is kept at once, so the header's media link
+     *  is there on the next load */
+    mediaListed(): void {
+        const cat = this.st.media.assets[0]?.cat ?? null
+        if (this.last != null && cat !== this.keptCat) this.keep(this.last, cat, true)
     }
 
     start(): void {
+        if (this.timer != null) return
         void this.poll()
         this.timer = setInterval(() => void this.poll(), 10_000)
     }
-    dispose(): void {
+    stop(): void {
         if (this.timer != null) clearInterval(this.timer)
+        this.timer = null
     }
 
-    async poll(): Promise<void> {
+    /** `fresh`: this page just changed the truth (an act, a run that ended),
+     *  so the answer waits on a walk that includes it rather than on the one
+     *  the server keeps warm */
+    async poll(fresh = false): Promise<void> {
         try {
-            const r = await fetch('/api/resources.json')
+            const r = await fetch(this.st.url(fresh ? '/api/resources.json?fresh=1' : '/api/resources.json'))
             if (!r.ok) throw new Error(await r.text())
-            const j = (await r.json()) as { collections: ColMeta[]; resources: Resource[]; schedule?: Schedule | null; hub?: HubProblem[] }
+            const j = (await r.json()) as Answer
             runInAction(() => {
                 this.colMeta = j.collections
                 this.fetched = j.resources
-                this.schedule = j.schedule ?? null
+                this.planned = j.planned ?? null
                 this.hubProblems = j.hub ?? []
                 this.fetchErr = null
+                this.loaded = true
+                this.cached = false
             })
+            this.keep(j)
         } catch (e) {
             // a dead server must SAY so, in the header, never leave a tree
             // that reads like a healthy repo. The last rows stay, dated by it
@@ -130,9 +209,9 @@ export class ColsSvc {
     private async act(path: string, body: Record<string, unknown>): Promise<boolean> {
         this.actErr = ''
         try {
-            const r = await fetch(`/api/act/${path}`, { method: 'POST', body: JSON.stringify(body) })
+            const r = await fetch(this.st.url(`/api/act/${path}`), { method: 'POST', body: JSON.stringify(body) })
             if (!r.ok) throw new Error(await r.text())
-            await this.poll()
+            await this.poll(true)
             return true
         } catch (e) {
             runInAction(() => { this.actErr = (e as Error).message })

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

@@ -4,7 +4,7 @@
 // it is something the panel SAID: the header never reports a state it guessed
 // from how the iframe looks.
 import { makeAutoObservable, runInAction } from 'mobx'
-import type { HubSt } from './hub-st.ts'
+import type { RepoSt } from './repo-st.ts'
 
 export type ComfyBox = { url: string; up: boolean; err: string | null }
 /** what the panel says, narrowed to the messages this host acts on */
@@ -37,10 +37,16 @@ export class ComfySvc {
     private mountedFor = ''
     private frame: HTMLIFrameElement | null = null
     private handshake: ReturnType<typeof setTimeout> | null = null
+    private readonly listener = (e: MessageEvent): void => this.onMessage(e)
 
-    constructor(private st: HubSt) {
-        makeAutoObservable<this, 'st' | 'frame' | 'handshake'>(this, { st: false, frame: false, handshake: false })
-        window.addEventListener('message', (e) => this.onMessage(e))
+    dispose(): void {
+        window.removeEventListener('message', this.listener)
+        if (this.handshake != null) clearTimeout(this.handshake)
+    }
+
+    constructor(private st: RepoSt) {
+        makeAutoObservable<this, 'st' | 'frame' | 'handshake' | 'listener'>(this, { st: false, frame: false, handshake: false, listener: false })
+        window.addEventListener('message', this.listener)
     }
 
     setFrame(el: HTMLIFrameElement | null): void {
@@ -78,7 +84,7 @@ export class ComfySvc {
     }
 
     async probeBox(): Promise<void> {
-        const box = await fetch('/api/comfy/box')
+        const box = await fetch(this.st.url('/api/comfy/box'))
             .then((r) => (r.ok ? (r.json() as Promise<ComfyBox>) : null))
             .catch(() => null)
         runInAction(() => {
@@ -107,7 +113,7 @@ export class ComfySvc {
         })
         void this.probeBox()
         try {
-            const r = await fetch('/api/comfy/panel', { method: 'POST', body: JSON.stringify({ restart }) })
+            const r = await fetch(this.st.url('/api/comfy/panel'), { method: 'POST', body: JSON.stringify({ restart }) })
             if (!r.ok) throw new Error(await r.text())
             const up = (await r.json()) as { url: string }
             runInAction(() => {

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

@@ -4,7 +4,7 @@
 import { observer } from 'mobx-react-lite'
 import { useEffect } from 'react'
 import type { ComfySvc } from './comfy-svc.ts'
-import type { HubSt } from './hub-st.ts'
+import type { RepoSt } from './repo-st.ts'
 
 const PANEL_CHIP: Record<ComfySvc['state'], { label: string; cls: string; title: string }> = {
     idle: { label: 'idle', cls: '', title: 'nothing started yet' },
@@ -16,7 +16,7 @@ const PANEL_CHIP: Record<ComfySvc['state'], { label: string; cls: string; title:
 
 // the same panel over an asset page. A popup, so the asset, its rolls and its
 // prompt stay on screen behind it while a value is tried
-export const ComfyOverlay = observer(({ app }: { app: HubSt }) => {
+export const ComfyOverlay = observer(({ app }: { app: RepoSt }) => {
     const c = app.comfy
     if (!c.overlay) return null
     const chip = PANEL_CHIP[c.state]
@@ -47,7 +47,7 @@ export const ComfyOverlay = observer(({ app }: { app: HubSt }) => {
     )
 })
 
-export const ComfyView = observer(({ app, id }: { app: HubSt; id: string }) => {
+export const ComfyView = observer(({ app, id }: { app: RepoSt; id: string }) => {
     const c = app.comfy
     const wf = id.replace(/^comfy:/, '')
     useEffect(() => {

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

@@ -0,0 +1,49 @@
+// THE way the page shows anything that floats over it: a tooltip, a help
+// bubble, a process log on hover, a hover card. @floating-ui/react places it
+// (flip to stay in the window, shift off its edges, an offset from the
+// trigger), a portal lifts it out of every box that clips, and hover opens
+// it after a short delay, so a pointer passing by never flickers one open.
+// Nothing here is positioned by hand.
+import { autoUpdate, flip, FloatingPortal, offset, safePolygon, shift, useDismiss, useFloating, useFocus, useHover, useInteractions, useRole, type Placement } from '@floating-ui/react'
+import { observer, useLocalObservable } from 'mobx-react-lite'
+import type { HTMLAttributes, ReactNode } from 'react'
+
+/** how long a pointer rests on a trigger before its float opens */
+export const OPEN_MS = 150
+
+/** the placement middleware every float shares; `fallbacks` are the sides
+ *  tried in order when the chosen one does not fit */
+export const middleware = (gap = 6, fallbacks?: Placement[]) => [offset(gap), flip({ padding: 8, fallbackPlacements: fallbacks }), shift({ padding: 8 })]
+
+type TipProps = Omit<HTMLAttributes<HTMLSpanElement>, 'content'> & {
+    /** what floats; nothing floats while it is null */
+    content: ReactNode
+    /** the class of the floating box */
+    tipClass?: string
+    placement?: Placement
+    /** the sides tried in order when `placement` does not fit */
+    fallbacks?: Placement[]
+    /** the pointer can move into it (a log to scroll): it stays open on the way */
+    interactive?: boolean
+}
+
+/** a trigger and what floats over it on hover or focus */
+export const Tip = observer(({ content, children, tipClass = 'ftip', placement = 'top', fallbacks, interactive = false, ...rest }: TipProps) => {
+    const st = useLocalObservable(() => ({ open: false, set(v: boolean) { this.open = v } }))
+    const f = useFloating({ open: st.open, onOpenChange: (v) => st.set(v), placement, strategy: 'fixed', middleware: middleware(6, fallbacks), whileElementsMounted: autoUpdate })
+    const hover = useHover(f.context, { delay: { open: OPEN_MS, close: interactive ? 100 : 0 }, handleClose: interactive ? safePolygon() : null })
+    const focus = useFocus(f.context)
+    const dismiss = useDismiss(f.context)
+    const role = useRole(f.context, { role: 'tooltip' })
+    const { getReferenceProps, getFloatingProps } = useInteractions([hover, focus, dismiss, role])
+    return (
+        <>
+            <span ref={f.refs.setReference} {...getReferenceProps(rest)}>{children}</span>
+            {st.open && content != null ? (
+                <FloatingPortal>
+                    <div ref={f.refs.setFloating} className={tipClass} style={f.floatingStyles} {...getFloatingProps()}>{content}</div>
+                </FloatingPortal>
+            ) : null}
+        </>
+    )
+})

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

@@ -7,7 +7,7 @@
 import { runInAction } from 'mobx'
 import { observer } from 'mobx-react-lite'
 import { useRef } from 'react'
-import type { HubSt } from './hub-st.ts'
+import type { RepoSt } from './repo-st.ts'
 import type { Leg } from './hub-types.ts'
 
 export type Box = { scale: number; x: number; y: number; w: number; h: number }
@@ -27,7 +27,7 @@ const LEG_TAGS = ['L·front', 'L·back', 'R·back', 'R·front']
 
 type DragStart = { px: number; py: number; x: number; y: number; w: number; legs: Leg[]; cy: number; mode: 'move' | 'resize' }
 
-const LegBox = observer(({ app, box, i, leg }: { app: HubSt; box: Box; i: number; leg: Leg }) => {
+const LegBox = observer(({ app, box, i, leg }: { app: RepoSt; box: Box; i: number; leg: Leg }) => {
     const m = app.media
     const start = useRef<{ px: number; py: number; legs: Leg[]; mode: 'move' | 'resize' } | null>(null)
     const px = (v: number): number => v * box.scale
@@ -80,7 +80,7 @@ const LegBox = observer(({ app, box, i, leg }: { app: HubSt; box: Box; i: number
     )
 })
 
-export const GeometryLayer = observer(({ app, box }: { app: HubSt; box: Box | null }) => {
+export const GeometryLayer = observer(({ app, box }: { app: RepoSt; box: Box | null }) => {
     const m = app.media
     const start = useRef<DragStart | null>(null)
     const rect = m.rect
@@ -137,7 +137,7 @@ export const GeometryLayer = observer(({ app, box }: { app: HubSt; box: Box | nu
     )
 })
 
-export const Rectbar = observer(({ app }: { app: HubSt }) => {
+export const Rectbar = observer(({ app }: { app: RepoSt }) => {
     const m = app.media
     const rect = m.rect
     const showSize = m.tools.has('size')

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