rvlib-shipkit 2.2.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,26 +15,55 @@ 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; 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 []
-        return [{ path, film: o.film, ...(typeof o.description === 'string' ? { description: o.description } : {}) }]
+        return [
+            {
+                path,
+                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 } : {}),
+            },
+        ]
     })
 }
 
-/** the project CLI's film rows; null when the repo has no project CLI. A CLI that does not answer is an error */
+const asked = new Map<string, FilmVerb[]>()
+
+/** the rows asked again on the next read: a watch builds as a fresh process would */
+export const forgetVocab = (): void => asked.clear()
+
+/** the project CLI's film rows; null when the repo has no project CLI. A CLI that does not answer is an error. Asked
+ *  once per process: the prune and a watch read many cuts */
 export function readVocab(root: string, cli: readonly string[] | null): FilmVerb[] | null {
     if (cli === null) return null
+    const k = `${root}\0${cli.join(' ')}`
+    const had = asked.get(k)
+    if (had) return had
     const r = Bun.spawnSync([...cli, 'commands', '--json'], { cwd: root, stdout: 'pipe', stderr: 'pipe' })
     const text = r.stdout.toString()
     try {
         if (r.exitCode !== 0) throw new Error(`exit ${r.exitCode}`)
-        return filmRows(JSON.parse(text))
+        const rows = filmRows(JSON.parse(text))
+        asked.set(k, rows)
+        return rows
     } catch (e) {
         throw new Error(`the project CLI (${cli.join(' ')}) did not answer \`commands --json\` with its rows: ${(e as Error).message}${r.stderr.length ? `\n${r.stderr.toString().trim().split('\n').slice(-4).join('\n')}` : ''}`)
     }

package/src/trailer/words.ts

@@ -0,0 +1,275 @@
+// a film row's declared words (wiki build/trailer.md, A row's words): the row says which words it takes and their
+// types, the core reads every word of a film line at its own line against that, refuses an unknown one with the row's
+// 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' | '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 {
+    type: WordType
+    arg?: number
+    optional?: boolean
+    min?: number
+    max?: number
+    values?: string[]
+    /** a point's numbers, 2 by default */
+    count?: number
+    /** a word's shape, a regular expression */
+    pattern?: string
+    /** what it means, for the error that lists the row's words */
+    doc?: string
+}
+
+export type Words = Record<string, WordSpec>
+
+/** a word of a film line, with the line it sits on (an option line under the film line keeps its own) */
+export interface LineWord {
+    text: string
+    quoted: boolean
+    line: number
+}
+
+/** a time: seconds, or a section or mark of the cut and a time from it */
+export type Moment = number | { mark: string; offset: number }
+
+export interface Typed {
+    /** the row's path, then its words in the order written, each value plain; a time's slot is filled by `times` */
+    argv: string[]
+    /** argv slots made of moments: a time (`name` null) or cues (`name@seconds`, comma joined) */
+    times: { index: number; parts: { name: string | null; at: Moment; line: number }[] }[]
+    /** argv slots that are files, as written: the build finds them and keys their content */
+    files: number[]
+    errors: { line: number; message: string }[]
+}
+
+/** the row's words checked as a declaration: every type known, its bounds sane; null when it is one */
+export function wordsProblem(words: unknown): string | null {
+    if (typeof words !== 'object' || words === null) return 'words is a record of word → { type }'
+    for (const [k, v] of Object.entries(words as Record<string, unknown>)) {
+        const w = v as Partial<WordSpec> | null
+        if (!/^[a-z][a-z0-9-]*$/.test(k)) return `word ${k}: a word is lowercase letters, digits and -`
+        if (!w || !WORD_TYPES.includes(w.type as WordType)) return `word ${k}: type is one of ${WORD_TYPES.join(', ')}`
+        if (w.type === 'enum' && (!Array.isArray(w.values) || w.values.length === 0)) return `word ${k}: an enum names its values`
+        if (w.pattern !== undefined) {
+            try {
+                new RegExp(w.pattern)
+            } catch {
+                return `word ${k}: pattern ${w.pattern} is no regular expression`
+            }
+        }
+    }
+    return 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
+    const what = `${key} wants ${describe(spec)}, got ${w.quoted ? `"${t}"` : t}`
+    switch (spec.type) {
+        case 'number':
+        case 'int': {
+            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) => 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 }
+            return { text: t }
+        case 'text':
+            return t.trim() === '' ? { error: `${key}: the text is empty` } : { text: t }
+        default:
+            return { error: what }
+    }
+}
+
+function describe(s: WordSpec): string {
+    switch (s.type) {
+        case 'number':
+        case 'int':
+            return `${s.type === 'int' ? 'a whole number' : 'a number'}${s.min !== undefined || s.max !== undefined ? ` from ${s.min ?? '-∞'} to ${s.max ?? '∞'}` : ''}`
+        case 'enum':
+            return s.values!.join('|')
+        case 'point':
+            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':
+            return 'a file'
+        case 'word':
+            return `a word${s.pattern ? ` like ${s.pattern}` : ''}`
+        case 'text':
+            return 'a text'
+        case 'flag':
+            return 'no value'
+    }
+}
+
+/** the row's words, for an error: positionals in order, then keys */
+export const wordList = (words: Words): string =>
+    [
+        ...Object.entries(words)
+            .filter(([, s]) => s.arg !== undefined)
+            .sort((a, b) => a[1].arg! - b[1].arg!)
+            .map(([k, s]) => `<${k}>${s.optional ? '?' : ''}`),
+        ...Object.entries(words)
+            .filter(([, s]) => s.arg === undefined)
+            .map(([k]) => k),
+    ].join(' ')
+
+interface Entry {
+    key: string
+    /** a positional's words carry no key on the line */
+    positional: boolean
+    values: LineWord[]
+    line: number
+}
+
+/** 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'], keysOnly = false): Entry[] {
+    const args = Object.entries(words)
+        .filter(([, s]) => s.arg !== undefined)
+        .sort((a, b) => a[1].arg! - b[1].arg!)
+    let next = 0
+    const out: Entry[] = []
+    for (let i = 0; i < ws.length; i++) {
+        const w = ws[i]!
+        const spec = !w.quoted && words[w.text] && words[w.text]!.arg === undefined ? words[w.text]! : null
+        if (spec) {
+            if (spec.type === 'flag') out.push({ key: w.text, positional: false, values: [], line: w.line })
+            else if (spec.type === 'cues') {
+                const values: LineWord[] = []
+                while (i + 1 < ws.length && !ws[i + 1]!.quoted && /^[^@\s]+@\S+$/.test(ws[i + 1]!.text) && !words[ws[i + 1]!.text]) {
+                    const c = ws[++i]!
+                    for (const text of c.text.split(',')) values.push({ ...c, text })
+                }
+                if (values.length === 0) errors.push({ line: w.line, message: `film ${path} ${w.text} wants cues, name@<time> each` })
+                out.push({ key: w.text, positional: false, values, line: w.line })
+            } else {
+                const v = ws[i + 1]
+                if (!v || v.line !== w.line) errors.push({ line: w.line, message: `film ${path} ${w.text} wants ${describe(spec)}` })
+                else {
+                    out.push({ key: w.text, positional: false, values: [v], line: w.line })
+                    i++
+                }
+            }
+            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) {
+            const [k, s] = args[next++]!
+            if (!('error' in valueOf(k, s, w, time))) {
+                out.push({ key: k, positional: true, values: [w], line: w.line })
+                placed = true
+                break
+            }
+            if (!s.optional) {
+                errors.push({ line: w.line, message: `film ${path}: ${w.quoted ? `"${w.text}"` : w.text} fits no word here, <${k}> wants ${describe(s)} (${path} takes ${wordList(words)})` })
+                placed = true
+                break
+            }
+        }
+        if (!placed) {
+            errors.push({ line: w.line, message: `film ${path}: unknown word ${w.quoted ? `"${w.text}"` : w.text} (${path} takes ${wordList(words)})` })
+            // its value goes with it: one error a word
+            const v = ws[i + 1]
+            if (v && v.line === w.line && !(!v.quoted && words[v.text])) i++
+        }
+    }
+    return out
+}
+
+/**
+ * a film line of a row that declares its words: `ws` its words after the row's path, `defaults` its section's (a key
+ * the line gives itself wins). The plain argv, the slots that wait on a moment, the file slots, every error at its line
+ */
+export function typedFilm(path: string[], words: Words, ws: LineWord[], defaults: LineWord[], time: (text: string) => Moment | null): Typed {
+    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, 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'] = []
+    const files: number[] = []
+    for (const e of all) {
+        if (seen.has(e.key)) {
+            errors.push({ line: e.line, message: `film ${path.join(' ')}: ${e.key} given twice` })
+            continue
+        }
+        seen.add(e.key)
+        const spec = words[e.key]!
+        if (!e.positional) argv.push(e.key)
+        if (spec.type === 'flag') continue
+        if (spec.type === 'cues') {
+            const parts: Typed['times'][number]['parts'] = []
+            for (const v of e.values) {
+                const at = v.text.indexOf('@')
+                const name = v.text.slice(0, at)
+                const m = time(v.text.slice(at + 1))
+                if (m === null) errors.push({ line: v.line, message: `film ${path.join(' ')} ${e.key}: ${v.text}, the time after @ is no time (1.5s, 2beats, a mark, mark+1beat)` })
+                else parts.push({ name, at: m, line: v.line })
+            }
+            times.push({ index: argv.length, parts })
+            argv.push('')
+            continue
+        }
+        const got = valueOf(e.key, spec, e.values[0]!, time)
+        if ('error' in got) {
+            errors.push({ line: e.values[0]!.line, message: `film ${path.join(' ')}: ${got.error}` })
+            argv.push(e.values[0]!.text)
+        } else if ('at' in got) {
+            times.push({ index: argv.length, parts: [{ name: null, at: got.at, line: e.values[0]!.line }] })
+            argv.push('')
+        } else {
+            if (spec.type === 'file') files.push(argv.length)
+            argv.push(got.text)
+        }
+    }
+    for (const [k, s] of Object.entries(words)) if (s.arg !== undefined && !s.optional && !seen.has(k)) errors.push({ line: ws[0]?.line ?? defaults[0]?.line ?? 0, message: `film ${path.join(' ')}: <${k}> is missing (${path.join(' ')} takes ${wordList(words)})` })
+    return { argv, times, files, errors }
+}
+
+/** a slot's text once its moments are seconds: a time, or cues joined by commas */
+export const slotText = (parts: readonly { name: string | null; seconds: number }[]): string => parts.map((p) => (p.name === null ? n4(p.seconds) : `${p.name}@${n4(p.seconds)}`)).join(',')

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 }
+}