rvlib-shipkit 2.3.0 → 2.4.0

package/src/trailer/url.ts

@@ -3,7 +3,19 @@
 // it does not answer. Pure first, the io after
 import type { Film } from './grammar.ts'
 
-export type UrlFilm = Extract<Film, { kind: 'url' }>
+export type UrlFilm = Extract<Film, { kind: 'url' | 'page' }>
+
+/** a page's query words as the url's query, in the order written; a flag a key with no value */
+export function queryOf(words: readonly string[], declaredFlags: ReadonlySet<string> = new Set()): string {
+    const q = new URLSearchParams()
+    for (let i = 0; i < words.length; i++) {
+        const k = words[i]!
+        if (declaredFlags.has(k)) q.append(k, '')
+        else q.append(k, words[++i] ?? '')
+    }
+    const s = q.toString()
+    return s ? `?${s}` : ''
+}
 
 /** a global process of the repo that serves a url */
 export interface DevProcess {
@@ -98,11 +110,14 @@ export interface UrlTake {
 
 /** film the page of a `film url` line at `out`; the note says what was filmed and how */
 export async function filmUrl(f: UrlFilm, o: UrlTake): Promise<string> {
-    const url = /^https?:\/\//.test(f.route) ? f.route : urlOf(f.route, await baseUrl(o.root, o.base, o.say))
+    const page = /^https?:\/\//.test(f.route) ? f.route : urlOf(f.route, await baseUrl(o.root, o.base, o.say))
+    const url = f.kind === 'page' ? `${page}${f.query.length ? `${page.includes('?') ? '&' : ''}${queryOf(f.query, new Set(f.flags ?? [])).slice(page.includes('?') ? 1 : 0)}` : ''}` : page
     const { clipUrl, shotUrl } = await import('../shot/client.ts')
     const { viewport, dpr } = viewportOf(o.size, f.viewport)
     const wait = f.wait === undefined ? {} : { waitMs: Math.round(f.wait * 1000) }
     const log = (l: string): void => o.say(`  ${l}`)
-    const r = o.seconds === null ? await shotUrl({ url, out: o.out, viewport, dpr, ...wait }, log) : await clipUrl({ url, out: o.out, viewport, dpr, seconds: o.seconds, fps: o.fps, ...wait }, log)
+    const step = f.kind === 'page' ? { step: f.step } : {}
+    const still = f.kind === 'page' ? { step: f.step, at: f.at ?? 0 } : {}
+    const r = o.seconds === null ? await shotUrl({ url, out: o.out, viewport, dpr, ...wait, ...still }, log) : await clipUrl({ url, out: o.out, viewport, dpr, seconds: o.seconds, fps: o.fps, ...wait, ...step }, log)
     return `${url} at ${viewport.width}x${viewport.height}@${dpr}, ${r.via}, ${r.ms} ms${r.note ? `: ${r.note}` : ''}`
 }

package/src/trailer/vocab.ts

@@ -4,6 +4,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import type { FilmVerb } from './grammar.ts'
+import { type Words, wordsProblem } from './words.ts'
 
 /** the project CLI's argv from the `cli` script of package.json, null when there is none */
 export function projectCli(root: string): string[] | null {
@@ -14,11 +15,19 @@ export function projectCli(root: string): string[] | null {
     return cli.trim().split(/\s+/)
 }
 
+/** a row's declared words, checked: a declaration that is no declaration is the CLI's error, said loud */
+function wordsOf(path: string[], words: unknown): { words?: Words } {
+    if (words === undefined) return {}
+    const why = wordsProblem(words)
+    if (why !== null) throw new Error(`the film row ${path.join(' ')} declares its words wrong: ${why}`)
+    return { words: words as Words }
+}
+
 /** the film rows in a `commands --json` answer: an array of rows, or `{ commands: [...] }` */
 export function filmRows(json: unknown): FilmVerb[] {
     const rows = Array.isArray(json) ? json : Array.isArray((json as { commands?: unknown })?.commands) ? (json as { commands: unknown[] }).commands : []
     return rows.flatMap((r) => {
-        const o = r as { path?: unknown; film?: unknown; version?: unknown; length?: unknown; description?: unknown }
+        const o = r as { path?: unknown; film?: unknown; version?: unknown; length?: unknown; description?: unknown; words?: unknown; stamp?: unknown }
         if (o.film !== 'still' && o.film !== 'clip') return []
         const path = Array.isArray(o.path) ? o.path.map(String) : typeof o.path === 'string' ? o.path.trim().split(/\s+/) : []
         if (path.length === 0) return []
@@ -28,6 +37,8 @@ export function filmRows(json: unknown): FilmVerb[] {
                 film: o.film,
                 ...(typeof o.version === 'number' || typeof o.version === 'string' ? { version: o.version } : {}),
                 ...(o.length === 'own' ? { length: 'own' as const } : {}),
+                ...wordsOf(path, o.words),
+                ...(Array.isArray(o.stamp) && o.stamp.length > 0 ? { stamp: o.stamp.map(String) } : {}),
                 ...(typeof o.description === 'string' ? { description: o.description } : {}),
             },
         ]

package/src/trailer/words.ts

@@ -3,8 +3,8 @@
 // list, and hands the row its values made plain (argv stays the transport). Pure: times arrive as moments the grammar
 // resolves once the shots have landed
 
-export type WordType = 'number' | 'int' | 'enum' | 'point' | 'time' | 'cues' | 'file' | 'text' | 'word' | 'flag'
-export const WORD_TYPES: readonly WordType[] = ['number', 'int', 'enum', 'point', 'time', 'cues', 'file', 'text', 'word', 'flag']
+export type WordType = 'number' | 'int' | 'enum' | 'point' | 'time' | 'length' | 'cues' | 'file' | 'text' | 'word' | 'flag'
+export const WORD_TYPES: readonly WordType[] = ['number', 'int', 'enum', 'point', 'time', 'length', 'cues', 'file', 'text', 'word', 'flag']
 
 /** one word a row takes: its type and bounds; `arg: n` makes it the n-th positional */
 export interface WordSpec {
@@ -65,6 +65,11 @@ export function wordsProblem(words: unknown): string | null {
 
 const n4 = (x: number): string => String(+x.toFixed(4))
 
+// a cut writes plain decimals: Number() alone would take 1e2, 0x10 and Infinity
+const DECIMAL = /^-?(\d+(\.\d*)?|\.\d+)$/
+const INTEGER = /^-?\d+$/
+const decimal = (t: string): number => (DECIMAL.test(t) ? Number(t) : Number.NaN)
+
 /** one value read by its type: its plain text, a moment, or why it does not fit */
 function valueOf(key: string, spec: WordSpec, w: LineWord, time: (text: string) => Moment | null): { text: string } | { at: Moment } | { error: string } {
     const t = w.text
@@ -72,21 +77,26 @@ function valueOf(key: string, spec: WordSpec, w: LineWord, time: (text: string)
     switch (spec.type) {
         case 'number':
         case 'int': {
-            const v = w.quoted ? Number.NaN : Number(t)
-            if (!Number.isFinite(v) || (spec.type === 'int' && !Number.isInteger(v)) || (spec.min !== undefined && v < spec.min) || (spec.max !== undefined && v > spec.max)) return { error: what }
+            const v = w.quoted ? Number.NaN : decimal(t)
+            if (!Number.isFinite(v) || (spec.type === 'int' && !INTEGER.test(t)) || (spec.min !== undefined && v < spec.min) || (spec.max !== undefined && v > spec.max)) return { error: what }
             return { text: t }
         }
         case 'enum':
             return !w.quoted && spec.values!.includes(t) ? { text: t } : { error: what }
         case 'point': {
             const parts = w.quoted ? [] : t.split(',')
-            const ok = parts.length === (spec.count ?? 2) && parts.every((p) => p !== '' && Number.isFinite(Number(p)))
+            const ok = parts.length === (spec.count ?? 2) && parts.every((p) => Number.isFinite(decimal(p)))
             return ok ? { text: t } : { error: what }
         }
         case 'time': {
             const at = w.quoted ? null : time(t)
             return at === null ? { error: what } : { at }
         }
+        case 'length': {
+            // a duration: never a moment, never moved by the shot's from
+            const at = w.quoted ? null : time(t)
+            return typeof at === 'number' && (spec.min === undefined || at >= spec.min) && (spec.max === undefined || at <= spec.max) ? { text: n4(at) } : { error: what }
+        }
         case 'file':
         case 'word':
             if (w.quoted || t === '' || (spec.pattern !== undefined && !new RegExp(spec.pattern).test(t))) return { error: what }
@@ -109,6 +119,8 @@ function describe(s: WordSpec): string {
             return `${s.count ?? 2} numbers joined by commas`
         case 'time':
             return 'a time (1.5s, 400ms, 0:04, 2beats, a mark, mark+1beat)'
+        case 'length':
+            return `a length (1.5s, 400ms, 2beats)${s.min !== undefined || s.max !== undefined ? ` from ${s.min ?? 0} to ${s.max ?? '∞'} s` : ''}`
         case 'cues':
             return 'cues, name@<time> each'
         case 'file':
@@ -144,7 +156,7 @@ interface Entry {
 
 /** the entries of a run of words: a word that names a key opens it (its value words follow), any other word fills the
  *  next positional that takes it */
-function entriesOf(path: string, words: Words, ws: LineWord[], time: (text: string) => Moment | null, errors: Typed['errors']): Entry[] {
+function entriesOf(path: string, words: Words, ws: LineWord[], time: (text: string) => Moment | null, errors: Typed['errors'], keysOnly = false): Entry[] {
     const args = Object.entries(words)
         .filter(([, s]) => s.arg !== undefined)
         .sort((a, b) => a[1].arg! - b[1].arg!)
@@ -173,6 +185,13 @@ function entriesOf(path: string, words: Words, ws: LineWord[], time: (text: stri
             }
             continue
         }
+        // a section's defaults name keys: a word there that is no key of this row is a typo, never a positional
+        if (keysOnly) {
+            errors.push({ line: w.line, message: `defaults: ${w.quoted ? `"${w.text}"` : w.text} is no word film ${path} takes (${path} takes ${wordList(words)})` })
+            const v = ws[i + 1]
+            if (v && v.line === w.line && !(!v.quoted && words[v.text])) i++
+            continue
+        }
         // the next positional that takes this word; an optional one that does not is passed over
         let placed = false
         while (next < args.length) {
@@ -206,8 +225,10 @@ export function typedFilm(path: string[], words: Words, ws: LineWord[], defaults
     const errors: Typed['errors'] = []
     const own = entriesOf(path.join(' '), words, ws, time, errors)
     const given = new Set(own.map((e) => e.key))
-    const fromDefaults = defaults.length > 0 ? entriesOf(path.join(' '), words, defaults, time, errors).filter((e) => !given.has(e.key)) : []
-    const all = [...fromDefaults, ...own]
+    const fromDefaults = defaults.length > 0 ? entriesOf(path.join(' '), words, defaults, time, errors, true).filter((e) => !given.has(e.key)) : []
+    // the positionals first, in their arg order, as the row reads them by place; then the keys, the defaults' first
+    const args = own.filter((e) => e.positional).sort((a, b) => words[a.key]!.arg! - words[b.key]!.arg!)
+    const all = [...args, ...fromDefaults, ...own.filter((e) => !e.positional)]
     const seen = new Set<string>()
     const argv = [...path]
     const times: Typed['times'] = []

package/src/wiki/graph-mount.ts

@@ -12,6 +12,9 @@ export type GraphMount = {
     /** graph page title */
     title: string
     load: () => MdGraph
+    /** the folder its node ids are relative to: the wikis page searches and
+     *  previews the pages there (graph-pages.ts). Absent = no page is read */
+    dir?: 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 */

package/src/wiki/graph-page.ts

@@ -3,6 +3,10 @@
 // (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.
+// Embedded in the hub (wikis-view.tsx), it talks to its parent by message: a
+// click on a ball sends `wiki-graph:pick`, and `wiki-graph:focus` rings a ball
+// and glides it to the centre, `wiki-graph:theme` repaints it light or dark
+// (first given as ?theme=). The hub owns the search and the preview.
 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'
@@ -37,13 +41,16 @@ export function graphHtml(g: MdGraph, opts?: { title?: string; seed?: Seed; save
 </style>
 </head>
 <body>
-<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>
+<header><b>${title}</b><span>thick purple → @ co-load · thin → lazy ref · ringed = eager layer · number = hops from index, bigger = closer · colour = link neighbourhood · click = open · drag / pan / zoom · reload = regenerate</span></header>
 <canvas id="c"></canvas>
 <script>
 const DATA = ${dataJson}
 const canvas = document.getElementById('c')
 const ctx = canvas.getContext('2d')
-const dark = matchMedia('(prefers-color-scheme: dark)').matches
+// the hub's theme, else the system's
+let dark = (new URLSearchParams(location.search).get('theme') ?? (matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light')) === 'dark'
+const applyTheme = () => { document.documentElement.style.colorScheme = dark ? 'dark' : 'light' }
+applyTheme()
 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]
@@ -59,6 +66,8 @@ for (const n of N) {
     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 = DATA.alpha, hover = null, drag = null, panning = null
+// the ball the hub's preview shows, and where the view glides to bring it to the centre
+let selected = null, glide = null, down = null
 function resize() {
     const dpr = devicePixelRatio || 1
     canvas.width = innerWidth * dpr; canvas.height = innerHeight * dpr
@@ -101,10 +110,11 @@ function step() {
 function draw() {
     ctx.clearRect(0, 0, innerWidth, innerHeight)
     ctx.save(); ctx.translate(ox, oy); ctx.scale(scale, scale)
-    const focus = hover ? new Set([hover.id, ...E.flatMap(e => e.from === hover.id ? [e.to] : e.to === hover.id ? [e.from] : [])]) : null
+    const lead = hover ?? selected
+    const focus = lead ? new Set([lead.id, ...E.flatMap(e => e.from === lead.id ? [e.to] : e.to === lead.id ? [e.from] : [])]) : null
     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
+        const lit = focus == null || e.from === lead.id || e.to === lead.id
         ctx.globalAlpha = lit ? (e.eager ? 1 : 0.45) : 0.06
         ctx.strokeStyle = e.eager ? '#8b5cf6' : (dark ? '#8a8a95' : '#777')
         ctx.lineWidth = (e.eager ? 5 : 1.2) / scale
@@ -125,6 +135,7 @@ function draw() {
         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 = 3 / scale; ctx.beginPath(); ctx.arc(n.x, n.y, n.r + 3 / scale, 0, 7); ctx.stroke() }
+        if (n === selected) { ctx.globalAlpha = 1; ctx.strokeStyle = dark ? '#ffffff' : '#1c2026'; ctx.lineWidth = 2.5 / scale; ctx.beginPath(); ctx.arc(n.x, n.y, n.r + 7 / scale, 0, 7); ctx.stroke() }
         if (n.depth != null && scale * n.r > 3) {
             ctx.fillStyle = '#16161c'
             ctx.font = '600 ' + n.r * 1.1 + 'px system-ui'
@@ -132,18 +143,26 @@ function draw() {
             ctx.fillText(n.depth, n.x, n.y + n.r * 0.08)
             ctx.textBaseline = 'alphabetic'
         }
-        const showLabel = n === hover || scale > 0.8 || lit && focus != null
+        const showLabel = n === hover || n === selected || scale > 0.8 || lit && focus != null
         if (showLabel) {
-            ctx.globalAlpha = n === hover ? 1 : lit ? 0.8 : 0.1
+            ctx.globalAlpha = n === hover || n === selected ? 1 : lit ? 0.8 : 0.1
             ctx.fillStyle = dark ? '#ddd' : '#333'
-            ctx.font = (n === hover ? 13 : 11) / scale + 'px system-ui'
+            ctx.font = (n === hover || n === selected ? 13 : 11) / scale + 'px system-ui'
             ctx.textAlign = 'center'
             ctx.fillText(n.group ? n.group + '/' + n.label : n.label, n.x, n.y + n.r + 13 / scale)
         }
     }
     ctx.restore()
 }
-function loop() { step(); draw(); requestAnimationFrame(loop) }
+function loop() {
+    step()
+    if (glide != null) {
+        const tx = innerWidth / 2 - glide.x * scale, ty = innerHeight / 2 - glide.y * scale
+        ox += (tx - ox) * 0.15; oy += (ty - oy) * 0.15
+        if (Math.abs(tx - ox) < 0.5 && Math.abs(ty - oy) < 0.5) glide = null
+    }
+    draw(); requestAnimationFrame(loop)
+}
 loop()
 
 const saveOnceAfter = ${saveOnceAfter.toString()}
@@ -160,8 +179,18 @@ const nodeAt = (px, py) => {
     const [x, y] = world(px, py)
     return N.find(n => (n.x - x) ** 2 + (n.y - y) ** 2 < (n.r + 4 / scale) ** 2) ?? null
 }
+// the hub: a click on a ball opens it there, and the hub answers with focus and theme
+const embedded = parent !== window
+addEventListener('message', ev => {
+    const m = ev.data
+    if (m == null || typeof m !== 'object') return
+    if (m.type === 'wiki-graph:theme') { dark = m.theme === 'dark'; applyTheme() }
+    if (m.type === 'wiki-graph:focus') { selected = byId.get(m.id) ?? null; if (selected) glide = selected }
+})
 canvas.addEventListener('pointerdown', ev => {
     const n = nodeAt(ev.clientX, ev.clientY)
+    down = { x: ev.clientX, y: ev.clientY, n }
+    glide = null
     if (n) { drag = n; alpha = 1 } else panning = { x: ev.clientX - ox, y: ev.clientY - oy }
     canvas.setPointerCapture(ev.pointerId)
     canvas.style.cursor = 'grabbing'
@@ -171,7 +200,14 @@ canvas.addEventListener('pointermove', ev => {
     else if (panning) { ox = ev.clientX - panning.x; oy = ev.clientY - panning.y }
     else hover = nodeAt(ev.clientX, ev.clientY)
 })
-addEventListener('pointerup', () => { drag = null; panning = null; canvas.style.cursor = 'grab' })
+addEventListener('pointerup', ev => {
+    // a press that barely moved is a click: on a ball, it opens the page
+    if (down?.n != null && Math.hypot(ev.clientX - down.x, ev.clientY - down.y) < 4) {
+        selected = down.n
+        if (embedded) parent.postMessage({ type: 'wiki-graph:pick', id: down.n.id }, '*')
+    }
+    down = null; drag = null; panning = null; canvas.style.cursor = 'grab'
+})
 canvas.addEventListener('wheel', ev => {
     ev.preventDefault()
     const z = Math.exp(-ev.deltaY * 0.0015)

package/src/wiki/graph-pages.ts

@@ -0,0 +1,128 @@
+// a mounted wiki's pages, read from disk for the wikis page: the search over
+// every page of the graph (its title first, then its full text) and one page
+// with the refs it holds resolved to the graph's own nodes, so the preview can
+// open them. Only a node of the graph is ever read: a client names a node id,
+// never a path.
+import { existsSync, readFileSync, statSync } from 'fs'
+import { join } from 'path'
+import type { MdGraph, MdNode } from 'rvlib-shipkit/src/wiki/md-graph.ts'
+
+export type WikiHit = { id: string; label: string; title: string; snippet: string; inTitle: boolean }
+/** `links`: a ref token as the page writes it → the node it opens. `file`:
+ *  where it sits on disk, for the editor button and the copy */
+export type WikiPage = { id: string; title: string; md: string; links: Record<string, string>; file: string }
+
+/** the most hits a search answers */
+export const SEARCH_LIMIT = 30
+
+const cache = new Map<string, { mtime: number; text: string }>()
+
+/** the file of a node, under the folder its ids are relative to; null when
+ *  the node is not in the graph or its file is gone */
+export function nodeFile(g: MdGraph, dir: string, id: string): string | null {
+    if (!g.nodes.some((n) => n.id === id)) return null
+    for (const f of [join(dir, id), join(dir, `${id}.md`)]) if (existsSync(f) && statSync(f).isFile()) return f
+    return null
+}
+
+/** a page without its front matter: the `---` block a page opens with holds
+ *  tooling facts, never prose to read or search */
+export const bodyOf = (md: string): string => (md.startsWith('---\n') ? md.slice(4).replace(/^[\s\S]*?^---\s*$\n?/m, '') : md).replace(/^\s+/, '')
+
+function textOf(file: string): string {
+    const mtime = statSync(file).mtimeMs
+    const hit = cache.get(file)
+    if (hit != null && hit.mtime === mtime) return hit.text
+    const text = bodyOf(readFileSync(file, 'utf8'))
+    cache.set(file, { mtime, text })
+    return text
+}
+
+/** the page's first `# ` heading, else its label */
+export const titleOf = (md: string, n: Pick<MdNode, 'label'>): string => /^#\s+(.+)$/m.exec(md)?.[1]?.trim() ?? n.label
+
+/** every page whose title, path or text holds every word of the query: title
+ *  and path hits first, then by how often the words appear, a snippet around
+ *  the first one in the text */
+export function searchWiki(g: MdGraph, dir: string, q: string, limit = SEARCH_LIMIT): WikiHit[] {
+    const words = q.toLowerCase().split(/\s+/).filter((w) => w !== '')
+    if (words.length === 0) return []
+    const scored: (WikiHit & { score: number })[] = []
+    for (const n of g.nodes) {
+        const file = nodeFile(g, dir, n.id)
+        const md = file == null ? '' : textOf(file)
+        const title = titleOf(md, n)
+        const head = `${n.id} ${title}`.toLowerCase()
+        const body = md.toLowerCase()
+        if (!words.every((w) => head.includes(w) || body.includes(w))) continue
+        let score = 0
+        for (const w of words) {
+            if (head.includes(w)) score += 100
+            score += Math.min(20, body.split(w).length - 1)
+        }
+        const first = Math.min(...words.map((w) => body.indexOf(w)).filter((i) => i >= 0))
+        const snippet = Number.isFinite(first) ? snippetAt(md, first, words) : ''
+        scored.push({ id: n.id, label: n.label, title, snippet, inTitle: words.some((w) => head.includes(w)), score })
+    }
+    return scored
+        .sort((a, b) => b.score - a.score || a.id.length - b.id.length || a.id.localeCompare(b.id))
+        .slice(0, limit)
+        .map(({ score: _, ...h }) => h)
+}
+
+function snippetAt(md: string, at: number, words: string[]): string {
+    const from = Math.max(0, at - 60)
+    const to = Math.min(md.length, at + Math.max(...words.map((w) => w.length)) + 80)
+    return `${from > 0 ? '…' : ''}${md.slice(from, to).replace(/\s+/g, ' ').trim()}${to < md.length ? '…' : ''}`
+}
+
+/** the ref tokens a page writes, as the wiki scan reads them (scan-md.ts):
+ *  `@path.md`, `→ path.md`, `[text](path.md)` and `path.md` in a code span */
+export function refTokens(md: string): string[] {
+    const prose = md.replace(/^```[\s\S]*?^```\s*$/gm, '')
+    const out = new Set<string>()
+    for (const m of prose.matchAll(/(?:^|[\s(])@((?:\.{1,2}\/)*[\w][\w./-]*\.md)/gm)) out.add(m[1]!)
+    for (const m of prose.matchAll(/→\s*([\w][\w./-]*\.md)\b/g)) out.add(m[1]!)
+    for (const m of prose.matchAll(/\]\(([^)\s:]+\.md)\)/g)) out.add(m[1]!)
+    for (const m of prose.matchAll(/`([^`\n]+)`/g)) for (const p of m[1]!.matchAll(/[\w.][\w./-]*\.md/g)) out.add(p[0])
+    return [...out]
+}
+
+/** the node a token names: among the page's own link targets first, then any
+ *  node; a node whose id is the token, or one ends with the other at a folder
+ *  edge: a page names `agent/spec.md` where the agent/ graph's id is `spec.md`,
+ *  and a wiki repo's ids carry a `wiki/` the page leaves out */
+export function resolveToken(g: MdGraph, from: string, token: string): string | null {
+    const t = token.replace(/^(\.{1,2}\/)+/, '')
+    const bare = (s: string): string => s.replace(/\.md$/, '')
+    const edge = (a: string, b: string): boolean => a === b || a.endsWith(`/${b}`) || b.endsWith(`/${a}`)
+    const fits = (id: string): boolean => edge(id, t) || edge(bare(id), bare(t))
+    const targets = g.edges.filter((e) => e.from === from).map((e) => e.to)
+    const own = targets.filter(fits)
+    if (own.length > 0) return own.sort((a, b) => a.length - b.length)[0]!
+    const any = g.nodes.map((n) => n.id).filter(fits)
+    return any.length === 1 ? any[0]! : null
+}
+
+/** the page a wiki opens on: its index (the shortest `index.md`), else a
+ *  README, else a page of the eager layer, else the first */
+export function entryOf(g: MdGraph): string | null {
+    const ids = g.nodes.map((n) => n.id)
+    const named = (name: string): string | undefined => ids.filter((i) => i === name || i.endsWith(`/${name}`)).sort((a, b) => a.length - b.length)[0]
+    return named('index.md') ?? named('index') ?? named('README.md') ?? g.nodes.find((n) => n.depth === 0)?.id ?? ids[0] ?? null
+}
+
+/** a page, or the wiki's entry when no node is named */
+export function pageOf(g: MdGraph, dir: string, asked: string): WikiPage | null {
+    const id = asked === '' ? entryOf(g) : asked
+    if (id == null) return null
+    const file = nodeFile(g, dir, id)
+    if (file == null) return null
+    const md = textOf(file)
+    const links: Record<string, string> = {}
+    for (const t of refTokens(md)) {
+        const to = resolveToken(g, id, t)
+        if (to != null && to !== id) links[t] = to
+    }
+    return { id, title: titleOf(md, g.nodes.find((n) => n.id === id)!), md, links, file }
+}