rvlib-shipkit 0.38.0 → 1.0.0

package/src/ts/tsconfig-resolve.ts

@@ -0,0 +1,108 @@
+// which tsconfig files a typecheck must actually visit.
+//
+// `tsc --noEmit -p <solution>` on a solution-style config (`files: []` plus
+// `references`) compiles ZERO files and exits 0. The gate then prints
+// `ok: typecheck` while a type error sits in src, which is the single worst
+// output this repo can produce: an unmeasured green nobody can tell from a
+// measured one. tsc will not warn about it, so the caller has to resolve the
+// leaves itself and refuse when there are none.
+//
+// No disk access of its own: every read goes through the reader it is handed,
+// plain fs outside a check (ts/tsconfig-projects.ts), the check context
+// inside one, so a check that asks how typecheck resolves is keyed on the
+// configs it read.
+import { dirname, isAbsolute, join, relative, resolve } from 'path'
+import type { UnitReader } from '../release/unit-resolve.ts'
+import { parseJsonc } from './jsonc.ts'
+
+export type TypecheckProjects = {
+    /** absolute paths, in declaration order, of the configs that compile files */
+    projects: string[]
+    /** nothing would be compiled: the check would pass without checking */
+    vacuous: boolean
+    /** references pointing at a path that does not exist, verbatim as declared */
+    missing: string[]
+}
+
+type RawConfig = {
+    files?: unknown
+    include?: unknown
+    references?: { path?: unknown }[]
+}
+
+/** the reader, over absolute paths: it answers by the path relative to `root` */
+type At = { text: (abs: string) => string | null; exists: (abs: string, kind?: 'file' | 'dir') => boolean }
+
+/** a reference may name a directory, a config file, or a dir with no config */
+function configPathFor(at: At, base: string, declared: string): string | null {
+    const p = isAbsolute(declared) ? declared : resolve(base, declared)
+    if (at.exists(p, 'dir')) return at.exists(join(p, 'tsconfig.json')) ? join(p, 'tsconfig.json') : null
+    return at.exists(p) ? p : null
+}
+
+/**
+ * whether tsc would compile anything for THIS config, ignoring its references.
+ *
+ * tsc's rule, and every branch here is a shape found in the field:
+ * - `files` non-empty, or `include` non-empty: compiles those
+ * - neither key present: the default `include` is `**\/*`, so it compiles the
+ *   whole directory tree, which is why a bare `{ references: [...] }` is NOT
+ *   a solution config
+ * - `files: []` with no `include`: the solution-style marker, compiles nothing
+ * - `include: []`: compiles nothing whatever `files` says, unless `files` lists
+ *   something
+ */
+function compilesOwnFiles(cfg: RawConfig): boolean {
+    const files = Array.isArray(cfg.files) ? cfg.files : null
+    const include = Array.isArray(cfg.include) ? cfg.include : null
+    if (files != null && files.length > 0) return true
+    if (include != null) return include.length > 0
+    return files == null
+}
+
+function read(at: At, path: string): RawConfig {
+    const text = at.text(path)
+    if (text == null) throw new Error(`tsconfig unreadable at ${path}: no file there`)
+    try { return (parseJsonc(text) ?? {}) as RawConfig }
+    catch (e) { throw new Error(`tsconfig unparseable at ${path}: ${String(e).slice(0, 120)}`) }
+}
+
+/**
+ * Walk `references` to the leaves. A leaf that declares `files: []` with no
+ * `include` compiles nothing and is dropped, so a solution whose every leaf is
+ * empty comes back `vacuous` rather than as a command that passes for free.
+ */
+export function resolveTypecheckProjects(tsconfigPath: string, io: UnitReader, root: string): TypecheckProjects {
+    const rel = (abs: string): string => relative(root, abs).replace(/\\/g, '/')
+    const at: At = { text: (abs) => io.text(rel(abs)), exists: (abs, kind) => io.exists(rel(abs), kind) }
+    const start = resolve(root, tsconfigPath)
+    const projects: string[] = []
+    const missing: string[] = []
+    // a reference loop is legal to WRITE and would otherwise recurse forever
+    const seen = new Set<string>()
+
+    const visit = (path: string): void => {
+        if (seen.has(path)) return
+        seen.add(path)
+        const cfg = read(at, path)
+        // references are checked FIRST so the list reads dependencies before
+        // dependents, the order `tsc -b` would build in
+        for (const r of Array.isArray(cfg.references) ? cfg.references : []) {
+            const declared = typeof r?.path === 'string' ? r.path : null
+            if (declared == null) continue
+            const next = configPathFor(at, dirname(path), declared)
+            if (next == null) missing.push(declared)
+            else visit(next)
+        }
+        // `references` does NOT suppress a config's own inputs: only an empty
+        // `files` with no `include` does, and that is what makes a config
+        // solution-style. Skipping a referencing config outright is how the
+        // first version of this file reintroduced the false green it exists to
+        // kill, on `{ include: ['src'], references: [...] }`, which is the
+        // ordinary monorepo package shape
+        if (compilesOwnFiles(cfg)) projects.push(path)
+    }
+
+    visit(start)
+    return { projects, vacuous: projects.length === 0, missing }
+}

package/src/tui/build-steps-panel.ts

@@ -0,0 +1,61 @@
+// built-in panel: the gate's BUILD STEPS through runCi, results streaming in
+// via the onCheck tap. A build step is what `shipkit ci` runs and the health
+// pass leaves out, which is the ONE axis that splits this panel from the one
+// beside it. Every other check is skipped here on purpose: the checks panel
+// runs and renders them, and running them twice per refresh proves the same
+// thing twice.
+// no panel writes STATUS.md: a dashboard refresh runs the build steps alone,
+// so stamping a verdict from it would overwrite what a real gate proved with
+// a narrower claim, just by looking at the repo.
+import type { RepoConfig } from '../repo-config.ts'
+import { allTasks } from '../ledger/gate-checks.ts'
+import { runCi } from '../core/run-ci.ts'
+import { formatLine } from '../core/wire.ts'
+import type { CheckEvent } from '../core/check-runner.ts'
+import type { TuiPanelDef, TuiRow } from './tui-panel.ts'
+
+const checkRow = (e: CheckEvent): TuiRow => ({
+    key: e.id,
+    label: e.id,
+    status: e.status === 'pass' ? 'pass' : e.status === 'fail' ? 'fail' : e.status === 'warn' ? 'warn' : 'skip',
+    hint: `${(e.ms / 1000).toFixed(1)}s`,
+    detail: [
+        ...e.lines.map((l) => formatLine(l, false)),
+        ...(e.note != null && e.note !== '' ? [`skip: ${e.note}`] : []),
+        ...(e.logPath != null ? [`full log: ${e.logPath}`] : []),
+    ],
+})
+
+export function buildStepsPanel(root: string, config: RepoConfig): TuiPanelDef {
+    let rows: TuiRow[] = []
+    return {
+        id: 'build',
+        title: 'build steps',
+        rows: () => rows,
+        refresh: async (update) => {
+            const { tasks, disabled, unfilled } = await allTasks(config, root)
+            rows = [
+                ...tasks.map((t): TuiRow => ({ key: t.id, label: t.id, status: 'pending', detail: [] })),
+                ...disabled.map((id): TuiRow => ({ key: id, label: id, status: 'skip', detail: ['skip: disabled by repo.config defaults'] })),
+                ...unfilled.map((u): TuiRow => ({ key: u.id, label: u.id, status: 'skip', detail: [`skip: ${u.reason}`] })),
+            ]
+            const byKey = new Map(rows.map((r, i) => [r.key, i]))
+            update()
+            await runCi(root, {
+                config,
+                buildOnly: true,
+                status: false,
+                print: () => {}, // rows carry everything the wire lines would
+                onCheck: (e) => {
+                    const i = byKey.get(e.id)
+                    if (i == null) return
+                    rows[i] = checkRow(e)
+                    update()
+                },
+            })
+            // bail/interrupt leftovers never got a finish tap — visible, never a fake pass
+            rows = rows.map((r) => (r.status === 'pending' ? { ...r, status: 'skip', detail: ['skip: never ran (bailed or interrupted)'] } : r))
+            update()
+        },
+    }
+}

package/src/tui/checks-panel.ts

@@ -1,35 +1,43 @@
-// built-in panel: contracts + every discovered *.check.ts through runCheck
-// (both TTL cache layers intact) — per-check results stream in via the
-// onResult tap. status:false: no TUI panel writes STATUS.md (tasks-panel.ts).
-import { discoverChecks } from '../core/discover-checks.ts'
+// built-in panel: every check the health pass asks for, through runCheck,
+// results streaming in via the onCheck tap. The rows are drawn from the same
+// inventory every other surface reads, so a check cannot exist for the gate
+// and not for the dashboard. status:false: no TUI panel writes STATUS.md
+// (build-steps-panel.ts).
+import { gateInventory } from '../ledger/gate-checks.ts'
+import { loadRepoConfig, type RepoConfig } from '../repo-config.ts'
 import { runCheck } from '../core/run-check.ts'
 import { formatLine } from '../core/wire.ts'
 import type { TuiPanelDef, TuiRow } from './tui-panel.ts'
+import { CACHED } from '../core/outcome-words.ts'
 
-export function checksPanel(root: string): TuiPanelDef {
+export function checksPanel(root: string, config?: RepoConfig): TuiPanelDef {
     let rows: TuiRow[] = []
     return {
         id: 'checks',
-        title: 'Checks',
+        title: 'checks',
         rows: () => rows,
         refresh: async (update) => {
-            rows = ['contracts', ...discoverChecks(root).map((d) => d.name)]
-                .map((n): TuiRow => ({ key: n, label: n, status: 'pending', detail: [] }))
+            const c = config ?? (await loadRepoConfig(root))
+            // the checks the HEALTH pass asks for: everything that is not a
+            // build step, which is the panel beside this one
+            rows = (await gateInventory(root, c))
+                .filter((r) => !r.build)
+                .map((r): TuiRow => ({ key: r.decl.id, label: r.decl.id, status: 'pending', detail: [r.description] }))
             const byKey = new Map(rows.map((r, i) => [r.key, i]))
             update()
             await runCheck(root, {
                 status: false,
                 print: () => {},
-                onResult: (name, r) => {
+                onCheck: (e) => {
                     const row: TuiRow = {
-                        key: name,
-                        label: name,
-                        status: r.status,
-                        ...(r.cached ? { hint: 'cached' } : {}),
-                        detail: r.lines.map((l) => formatLine(l, false)),
+                        key: e.name,
+                        label: e.name,
+                        status: e.status,
+                        ...(e.replayed ? { hint: CACHED } : {}),
+                        detail: e.lines.map((l) => formatLine(l, false)),
                     }
-                    const i = byKey.get(name)
-                    if (i == null) { byKey.set(name, rows.length); rows.push(row) } // suite-side names (secret checks) still land
+                    const i = byKey.get(e.name)
+                    if (i == null) { byKey.set(e.name, rows.length); rows.push(row) }
                     else rows[i] = row
                     update()
                 },

package/src/tui/run-tui.ts

@@ -6,7 +6,7 @@ import { render } from 'ink'
 import { configure } from 'mobx'
 import { loadRepoConfig } from '../repo-config.ts'
 import { checksPanel } from './checks-panel.ts'
-import { tasksPanel } from './tasks-panel.ts'
+import { buildStepsPanel } from './build-steps-panel.ts'
 import { TuiApp } from './tui-app.tsx'
 import { TuiStore } from './tui-store.ts'
 
@@ -16,7 +16,7 @@ export async function runTui(root: string): Promise<number> {
     // only signal. Read-warning flags stay off: useInput handler reads are
     // legitimately untracked and would false-positive.
     configure({ enforceActions: 'always' })
-    const store = new TuiStore(c.name, [tasksPanel(root, c), checksPanel(root), ...(c.tui?.panels ?? [])])
+    const store = new TuiStore(c.name, [buildStepsPanel(root, c), checksPanel(root, c), ...(c.tui?.panels ?? [])])
     store.refresh() // instant static paint; results stream in
     const app = render(React.createElement(TuiApp, { store }))
     await app.waitUntilExit()

package/src/tui/tui-panel.ts

@@ -1,7 +1,7 @@
 // TUI panel contract — render-free and mobx-free on purpose: a panel is
 // DATA (rows + wire-format detail lines), the generic view (tui-app.tsx)
-// owns all ink. Built-ins: tasks-panel.ts (the ci gate) + checks-panel.ts
-// (contracts + discovered *.check.ts); a repo injects extras via
+// owns all ink. Built-ins: build-steps-panel.ts (the ci gate) + checks-panel.ts
+// (the gate's build steps, then every other check); a repo injects extras via
 // repo.config `tui: { panels: [...] }`.
 
 export type TuiRowStatus = 'pass' | 'fail' | 'warn' | 'skip' | 'pending' | 'info'
@@ -21,14 +21,15 @@ export type TuiRow = {
 }
 
 export type TuiPanelDef = {
+    /** stable panel id, used for the tab order and the key binding */
     id: string
     /** tab label */
     title: string
-    /** shown green when rows() is empty after refresh (e.g. "no open asks …") */
+    /** shown green when rows() is empty after refresh, as in "no open asks" */
     emptyText?: string
     /** current rows — the store re-reads after every update() */
     rows: () => TuiRow[]
-    /** (re)load data; call update() after each mutation so the view repaints.
+    /** (re)load data. Call update() after each mutation so the view repaints.
      *  The spinner runs until every panel's returned promise settled. */
     refresh: (update: () => void) => void | Promise<void>
 }

package/src/wiki/graph-colors.ts

@@ -0,0 +1,68 @@
+// one hue per node, so linked pages share a colour family and distant ones
+// differ. a spectral layout on the colour wheel: the two smoothest eigenvectors
+// of the normalized link graph (hub weight damped, so an index linking
+// everything cannot pull every node to one colour) place each node on a plane,
+// its angle is its hue. then hues are rank equalized: the order around the
+// wheel survives, the whole wheel is used. starts are hashed from ids, so a
+// reload keeps every colour.
+import type { MdGraph } from './md-graph.ts'
+
+const ROUNDS = 300
+/** an @ edge binds two pages harder than a lazy ref */
+const EAGER_WEIGHT = 3
+
+/** fnv-1a, 32 bit: a stable pseudo random start per id */
+export function hashUnit(s: string): number {
+    let h = 0x811c9dc5
+    for (let i = 0; i < s.length; i++) h = Math.imul(h ^ s.charCodeAt(i), 0x01000193)
+    return (h >>> 0) / 2 ** 32
+}
+
+/** hue in degrees [0, 360) per node id */
+export function nodeHues(g: MdGraph): Record<string, number> {
+    const ids = g.nodes.map((n) => n.id)
+    const index = new Map(ids.map((id, i) => [id, i]))
+    const deg = new Array<number>(ids.length).fill(0)
+    const links: { a: number; b: number; w: number }[] = []
+    for (const e of g.edges) {
+        const a = index.get(e.from), b = index.get(e.to)
+        if (a == null || b == null || a === b) continue
+        const w = e.eager ? EAGER_WEIGHT : 1
+        links.push({ a, b, w })
+        deg[a]! += w
+        deg[b]! += w
+    }
+    // power iteration on (I + D^-1/2 W D^-1/2) / 2, deflated against its top
+    // eigenvector sqrt(deg): what survives are the two smoothest directions
+    const top = deg.map((d) => Math.sqrt(d))
+    const topNorm = Math.hypot(...top) || 1
+    const mul = (v: number[]): number[] => {
+        const out = v.map((x) => x / 2)
+        for (const { a, b, w } of links) {
+            const k = w / Math.sqrt(deg[a]! * deg[b]!) / 2
+            out[a]! += v[b]! * k
+            out[b]! += v[a]! * k
+        }
+        return out
+    }
+    const dot = (u: number[], v: number[]) => u.reduce((s, x, i) => s + x * v[i]!, 0)
+    const orth = (v: number[], against: number[][]) => {
+        for (const u of against) { const k = dot(v, u); v = v.map((x, i) => x - k * u[i]!) }
+        const len = Math.hypot(...v) || 1
+        return v.map((x) => x / len)
+    }
+    const unitTop = top.map((x) => x / topNorm)
+    let u = ids.map((id) => hashUnit(id) - 0.5)
+    let v = ids.map((id) => hashUnit(`${id}#`) - 0.5)
+    for (let r = 0; r < ROUNDS; r++) {
+        u = orth(mul(u), [unitTop])
+        v = orth(mul(v), [unitTop, u])
+    }
+    // a node with no link sits at the origin, its hashed start gives its angle
+    const angle = ids.map((id, i) =>
+        deg[i] === 0 ? hashUnit(id) * 2 * Math.PI : Math.atan2(v[i]! / Math.sqrt(deg[i]!), u[i]! / Math.sqrt(deg[i]!)))
+    const order = ids.map((_, i) => i).sort((i, j) => angle[i]! - angle[j]!)
+    const out: Record<string, number> = {}
+    order.forEach((i, rank) => { out[ids[i]!] = (rank * 360) / ids.length })
+    return out
+}

package/src/wiki/graph-mount.ts

@@ -1,21 +1,19 @@
-// one MOUNTED md graph, as the hub serves it and as the graphs section shows
+// one MOUNTED md wiki graph, as the hub serves it and as the wikis page shows
 // it. ONE list per repo (serve/run-serve builds it): the route, the card and
 // the lint verdict all read the same entries, so a card can never link at a
 // route that is not served.
 import type { MdGraph } from 'rvlib-shipkit/src/wiki/md-graph.ts'
 
 export type GraphMount = {
-    /** route + card id: /graph/<id>, instance graph:<id> */
+    /** route + card id: /graph/<id>, instance wiki:<id> */
     id: string
-    /** card text and tool label, e.g. `wiki graph`, `<repo> wiki` */
+    /** its tab on the wikis page and its tool label, e.g. `this repo's wiki`, `<repo> wiki`, `agent/` */
     label: string
     /** graph page title */
     title: string
     load: () => MdGraph
-    /** null = someone else owns this graph's lint (a repo-owned provider, or a
-     *  wiki living in another repo): the card links, it never judges */
-    lint: { root: string; index?: string } | null
-    /** parenthesized on the CARD only, never in the terminal banner: why this
-     *  graph carries no verdict here */
-    note?: string
+    /** what judges this graph: the built-in md lint over a dir, the repo's own
+     *  checks by id (their last verdicts), or null for a wiki living in another
+     *  repo, which the card links and never judges */
+    lint: { root: string; index?: string } | { checks: string[] } | null
 }

package/src/wiki/graph-page.ts

@@ -1,19 +1,23 @@
 // Self-contained HTML: a force-directed canvas graph (no deps, no CDN).
-// Small balls (group-colored, eager layer highlighted), directed edges with
-// arrowheads — solid = eager auto-include, dashed = lazy ref. Drag balls,
-// drag background to pan, wheel to zoom, hover to focus a node's links.
+// Balls sized by hops from the index and coloured by link neighbourhood
+// (graph-colors.ts), eager layer ringed. Directed solid edges with arrowheads,
+// a thick purple one = eager auto-include, a thin grey one = lazy ref. Drag
+// balls, drag background to pan, wheel to zoom, hover to focus a node's links.
+import { nodeHues } from 'rvlib-shipkit/src/wiki/graph-colors.ts'
+import { SAVE_AFTER_MS, saveOnceAfter, type Seed } from 'rvlib-shipkit/src/wiki/graph-positions.ts'
 import type { MdGraph } from 'rvlib-shipkit/src/wiki/md-graph.ts'
 
-const PALETTE = ['#e05252', '#e0a552', '#c6d34f', '#5ec95e', '#52c9b0', '#529fe0', '#8f6fe8', '#d46fd4', '#9a8a72']
-
-export function graphHtml(g: MdGraph, opts?: { title?: string }): string {
+/** `seed` = where nodes start (graph-positions.ts). `saveUrl` = where the page
+ *  POSTs its node positions once per display; absent = it never does */
+export function graphHtml(g: MdGraph, opts?: { title?: string; seed?: Seed; saveUrl?: string }): string {
     // arbitrary wikis can hold hostile-looking titles/labels — keep the page unbreakable
     const title = (opts?.title ?? 'wiki graph').replace(/&/g, '&amp;').replace(/</g, '&lt;')
-    const groups = [...new Set(g.nodes.map((n) => n.group ?? ''))].sort()
-    const color = (grp: string | null) => PALETTE[groups.indexOf(grp ?? '') % PALETTE.length]!
+    const hues = nodeHues(g)
     const data = {
-        nodes: g.nodes.map((n) => ({ ...n, color: n.eager ? '#8b5cf6' : color(n.group) })),
+        nodes: g.nodes.map((n) => ({ ...n, color: `oklch(0.74 0.15 ${Math.round(hues[n.id]!)})`, ...opts?.seed?.start[n.id] })),
         edges: g.edges,
+        alpha: opts?.seed?.alpha ?? 1,
+        saveUrl: opts?.saveUrl ?? null,
     }
     const dataJson = JSON.stringify(data).replaceAll('<', '\\u003c')
     return `<!doctype html>
@@ -33,7 +37,7 @@ export function graphHtml(g: MdGraph, opts?: { title?: string }): string {
 </style>
 </head>
 <body>
-<header><b>${title}</b><span>solid → @ co-load · dashed → lazy ref · purple = eager layer · number = hops from index · drag / pan / zoom · reload = regenerate</span></header>
+<header><b>${title}</b><span>thick purple → @ co-load · thin → lazy ref · ringed = eager layer · number = hops from index, bigger = closer · colour = link neighbourhood · drag / pan / zoom · reload = regenerate</span></header>
 <canvas id="c"></canvas>
 <script>
 const DATA = ${dataJson}
@@ -42,14 +46,19 @@ const ctx = canvas.getContext('2d')
 const dark = matchMedia('(prefers-color-scheme: dark)').matches
 const N = DATA.nodes, byId = new Map(N.map(n => [n.id, n]))
 const E = DATA.edges.filter(e => byId.has(e.from) && byId.has(e.to))
+const SIZE_BY_DEPTH = [3, 2, 1.5]
 const deg = new Map()
 for (const e of E) { deg.set(e.from, (deg.get(e.from) ?? 0) + 1); deg.set(e.to, (deg.get(e.to) ?? 0) + 1) }
 for (const n of N) {
-    const a = Math.random() * Math.PI * 2, d = 120 + Math.random() * 240
-    n.x = Math.cos(a) * d; n.y = Math.sin(a) * d; n.vx = 0; n.vy = 0
-    n.r = 4 + Math.min(6, Math.sqrt(deg.get(n.id) ?? 0) * 1.6)
+    if (n.x == null || n.y == null) {
+        const a = Math.random() * Math.PI * 2, d = 120 + Math.random() * 240
+        n.x = Math.cos(a) * d; n.y = Math.sin(a) * d
+    }
+    n.vx = 0; n.vy = 0
+    // hops from the index set the size: 0 → x3, 1 → x2, 2 → x1.5, deeper or unreachable → x1
+    n.r = 6 * (SIZE_BY_DEPTH[n.depth] ?? 1) + Math.min(4, Math.sqrt(deg.get(n.id) ?? 0))
 }
-let scale = 1, ox = 0, oy = 0, alpha = 1, hover = null, drag = null, panning = null
+let scale = 1, ox = 0, oy = 0, alpha = DATA.alpha, hover = null, drag = null, panning = null
 function resize() {
     const dpr = devicePixelRatio || 1
     canvas.width = innerWidth * dpr; canvas.height = innerHeight * dpr
@@ -66,8 +75,9 @@ function step() {
         const a = N[i], b = N[j]
         let dx = a.x - b.x, dy = a.y - b.y
         let d2 = dx * dx + dy * dy; if (d2 < 1) { dx = Math.random() - .5; dy = Math.random() - .5; d2 = 1 }
-        const f = 1200 / d2
         const d = Math.sqrt(d2)
+        // plus a hard push while two balls overlap, big balls need room
+        const f = 4000 / d2 + Math.max(0, a.r + b.r + 24 - d) * 0.3
         dx /= d; dy /= d
         a.vx += dx * f; a.vy += dy * f; b.vx -= dx * f; b.vy -= dy * f
     }
@@ -75,12 +85,12 @@ function step() {
         const a = byId.get(e.from), b = byId.get(e.to)
         const dx = b.x - a.x, dy = b.y - a.y
         const d = Math.sqrt(dx * dx + dy * dy) || 1
-        const rest = e.eager ? 60 : 110
+        const rest = (e.eager ? 90 : 180) + a.r + b.r
         const f = (d - rest) * (e.eager ? 0.02 : 0.008)
         a.vx += dx / d * f; a.vy += dy / d * f; b.vx -= dx / d * f; b.vy -= dy / d * f
     }
     for (const n of N) {
-        n.vx -= n.x * 0.0015; n.vy -= n.y * 0.0015
+        n.vx -= n.x * 0.0008; n.vy -= n.y * 0.0008
         if (n === drag) { n.vx = 0; n.vy = 0; continue }
         n.x += n.vx * alpha; n.y += n.vy * alpha
         n.vx *= 0.85; n.vy *= 0.85
@@ -95,15 +105,13 @@ function draw() {
     for (const e of E) {
         const a = byId.get(e.from), b = byId.get(e.to)
         const lit = focus == null || e.from === hover.id || e.to === hover.id
-        ctx.globalAlpha = lit ? (e.eager ? 1 : 0.55) : 0.08
+        ctx.globalAlpha = lit ? (e.eager ? 1 : 0.45) : 0.06
         ctx.strokeStyle = e.eager ? '#8b5cf6' : (dark ? '#8a8a95' : '#777')
-        ctx.lineWidth = (e.eager ? 3.5 : 1) / scale
-        ctx.setLineDash(e.eager ? [] : [4 / scale, 4 / scale])
+        ctx.lineWidth = (e.eager ? 5 : 1.2) / scale
         const dx = b.x - a.x, dy = b.y - a.y, d = Math.sqrt(dx * dx + dy * dy) || 1
-        const tx = b.x - dx / d * (b.r + 3), ty = b.y - dy / d * (b.r + 3)
+        const gap = b.r + (b.eager ? 6 : 3) / scale, tx = b.x - dx / d * gap, ty = b.y - dy / d * gap
         ctx.beginPath(); ctx.moveTo(a.x + dx / d * a.r, a.y + dy / d * a.r); ctx.lineTo(tx, ty); ctx.stroke()
-        ctx.setLineDash([])
-        const ah = 5 / scale
+        const ah = (e.eager ? 7 : 4.5) / scale
         ctx.fillStyle = ctx.strokeStyle
         ctx.beginPath()
         ctx.moveTo(tx, ty)
@@ -116,9 +124,9 @@ function draw() {
         ctx.globalAlpha = lit ? 1 : 0.15
         ctx.fillStyle = n.color
         ctx.beginPath(); ctx.arc(n.x, n.y, n.r, 0, 7); ctx.fill()
-        if (n.eager) { ctx.strokeStyle = '#8b5cf6'; ctx.lineWidth = 2 / scale; ctx.beginPath(); ctx.arc(n.x, n.y, n.r + 2.5 / scale, 0, 7); ctx.stroke() }
+        if (n.eager) { ctx.strokeStyle = '#8b5cf6'; ctx.lineWidth = 3 / scale; ctx.beginPath(); ctx.arc(n.x, n.y, n.r + 3 / scale, 0, 7); ctx.stroke() }
         if (n.depth != null && scale * n.r > 3) {
-            ctx.fillStyle = '#fff'
+            ctx.fillStyle = '#16161c'
             ctx.font = '600 ' + n.r * 1.1 + 'px system-ui'
             ctx.textAlign = 'center'; ctx.textBaseline = 'middle'
             ctx.fillText(n.depth, n.x, n.y + n.r * 0.08)
@@ -138,6 +146,15 @@ function draw() {
 function loop() { step(); draw(); requestAnimationFrame(loop) }
 loop()
 
+const saveOnceAfter = ${saveOnceAfter.toString()}
+if (DATA.saveUrl != null) saveOnceAfter(${SAVE_AFTER_MS}, setTimeout, () => {
+    const pos = {}
+    for (const n of N) pos[n.id] = [Math.round(n.x), Math.round(n.y)]
+    fetch(DATA.saveUrl, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(pos) })
+        .then(r => { if (!r.ok) console.warn('graph positions not saved: ' + r.status) })
+        .catch(e => console.warn('graph positions not saved: ' + e.message))
+})()
+
 const world = (px, py) => [(px - ox) / scale, (py - oy) / scale]
 const nodeAt = (px, py) => {
     const [x, y] = world(px, py)

package/src/wiki/graph-positions.ts

@@ -0,0 +1,105 @@
+// where a graph's nodes sat last time, so the next display starts close to it.
+// one json file per graph per checkout, `<git-common-dir>/shipkit/graph-positions/<id>.json`,
+// never tracked. a start, never a pin: the layout still runs from there.
+import { mkdirSync, readFileSync } from 'fs'
+import { dirname, join } from 'path'
+import { atomicWrite } from '../core/locked-write.ts'
+import { shipkitRoot } from '../ledger/store.ts'
+import type { MdGraph } from './md-graph.ts'
+
+export type Positions = Record<string, [number, number]>
+
+/** how long a display lays out before the page sends its positions, once */
+export const SAVE_AFTER_MS = 3000
+/** a POST body past this is refused: a few thousand nodes fit well under it */
+export const MAX_POSITIONS_BYTES = 512 * 1024
+/** from this share of seeded nodes on, the layout starts calm */
+const CALM_FROM_SHARE = 0.5
+const CALM_ALPHA = 0.25
+const JITTER = 12
+
+const safeId = (id: string): string => id.replace(/[^a-zA-Z0-9._-]/g, '_')
+
+export const positionsFile = (root: string, graphId: string): string => join(shipkitRoot(root), 'graph-positions', `${safeId(graphId)}.json`)
+
+const isPoint = (p: unknown): p is [number, number] =>
+    Array.isArray(p) && p.length === 2 && Number.isFinite(p[0]) && Number.isFinite(p[1])
+
+/** keeps the well formed points of the ids in `keep`, rounded. anything else
+ *  (a vanished node, a malformed entry) is dropped, never an error */
+export function cleanPositions(raw: unknown, keep: ReadonlySet<string>): Positions {
+    const out: Positions = {}
+    if (raw == null || typeof raw !== 'object' || Array.isArray(raw)) return out
+    for (const [id, p] of Object.entries(raw as Record<string, unknown>)) {
+        if (keep.has(id) && isPoint(p)) out[id] = [Math.round(p[0]), Math.round(p[1])]
+    }
+    return out
+}
+
+/** a missing or unreadable file is no memory, and the graph lays out as new */
+export function readPositions(file: string): Positions {
+    try {
+        const doc = JSON.parse(readFileSync(file, 'utf8')) as { positions?: unknown }
+        const raw = doc.positions
+        if (raw == null || typeof raw !== 'object') return {}
+        return cleanPositions(raw, new Set(Object.keys(raw)))
+    } catch {
+        return {}
+    }
+}
+
+export function writePositions(file: string, positions: Positions): void {
+    mkdirSync(dirname(file), { recursive: true })
+    atomicWrite(file, `${JSON.stringify({ v: 1, positions }, null, 1)}\n`)
+}
+
+export type Seed = { start: Record<string, { x: number; y: number }>; alpha: number }
+
+/** the starting point of every node that has one: its saved position, else
+ *  the mean of its saved neighbours (links either way) plus a small jitter.
+ *  a node with neither is absent, and the page places it as a new node */
+export function seedPositions(g: MdGraph, saved: Positions, rand: () => number = Math.random): Seed {
+    const start: Seed['start'] = {}
+    for (const n of g.nodes) {
+        const p = saved[n.id]
+        if (p != null) start[n.id] = { x: p[0], y: p[1] }
+    }
+    for (const n of g.nodes) {
+        if (start[n.id] != null) continue
+        let sx = 0, sy = 0, k = 0
+        for (const e of g.edges) {
+            const other = e.from === n.id ? e.to : e.to === n.id ? e.from : null
+            const p = other == null ? undefined : saved[other]
+            if (p != null) { sx += p[0]; sy += p[1]; k++ }
+        }
+        if (k > 0) start[n.id] = { x: sx / k + (rand() - 0.5) * 2 * JITTER, y: sy / k + (rand() - 0.5) * 2 * JITTER }
+    }
+    const seeded = g.nodes.filter((n) => saved[n.id] != null).length
+    return { start, alpha: g.nodes.length > 0 && seeded / g.nodes.length >= CALM_FROM_SHARE ? CALM_ALPHA : 1 }
+}
+
+/** arms ONE delayed save per display: every later call is a no op. inlined
+ *  into the graph page by its source text, so it must stay self contained */
+export function saveOnceAfter(ms: number, later: (fn: () => void, ms: number) => unknown, save: () => void): () => void {
+    let armed = false
+    return () => {
+        if (armed) return
+        armed = true
+        later(save, ms)
+    }
+}
+
+/** the POST handler both servers mount: bounded body, ids checked against the
+ *  graph as it is now, so a vanished node leaves the file on this save */
+export async function acceptPositions(req: Request, file: string, g: () => MdGraph): Promise<Response> {
+    if (req.method !== 'POST') return new Response('POST only', { status: 405 })
+    const len = Number(req.headers.get('content-length') ?? 0)
+    if (len > MAX_POSITIONS_BYTES) return new Response('too large', { status: 413 })
+    const text = await req.text()
+    if (text.length > MAX_POSITIONS_BYTES) return new Response('too large', { status: 413 })
+    let body: unknown
+    try { body = JSON.parse(text) } catch { return new Response('not json', { status: 400 }) }
+    const positions = cleanPositions(body, new Set(g().nodes.map((n) => n.id)))
+    writePositions(file, positions)
+    return new Response(null, { status: 204 })
+}

package/src/wiki/run-wiki.ts

@@ -28,7 +28,7 @@ export async function runWikiServe(o: WikiScanOpts & { port: number; title?: str
     const rel = relative(process.cwd(), cfg.root)
     const title = o.title ?? (rel === '' ? basename(cfg.root) : `${basename(process.cwd())} ${rel}`)
     try {
-        serveMdGraph({ port: o.port, title, load: () => scanMdGraph(cfg) })
+        serveMdGraph({ port: o.port, title, root: cfg.root, load: () => scanMdGraph(cfg) })
         say(`wiki graph → http://localhost:${o.port} (open in browser, or VSCode "Simple Browser: Show")`)
         // keep the server alive — the command must not resolve
         await new Promise(() => {})