rvlib-shipkit 2.3.0 → 2.4.0

package/src/serve/hub-app/wiki-st.ts

@@ -0,0 +1,190 @@
+// the wikis page's state, one per repo: the search bar over the open wiki
+// (its title and full text, graph-pages.ts on the server), the hit under the
+// arrows, and the page open in the preview panel. The graph is an iframe that
+// only draws (wiki/graph-page.ts): a click on a ball arrives as a message,
+// and opening a page answers with a focus message, so the ball and the
+// preview always show the same page.
+import { makeAutoObservable, runInAction } from 'mobx'
+import type { WikiHit, WikiPage } from '../../wiki/graph-pages.ts'
+import type { RepoSt } from './repo-st.ts'
+
+const WIDTH_KEY = 'hub:wiki-preview-width'
+const HEIGHT_KEY = 'hub:wiki-preview-height'
+const PLACE_KEY = 'hub:wiki-preview-place'
+export const PREVIEW = { min: 260, max: 1200, def: 460 }
+/** the preview below the graph: its height */
+export const PREVIEW_H = { min: 160, max: 1200, def: 360 }
+/** where the preview sits against the graph, toggled from its own head */
+export const PLACES = ['left', 'right', 'bottom'] as const
+export type PreviewPlace = (typeof PLACES)[number]
+/** the wait after a keystroke before the search asks the server */
+const SEARCH_MS = 120
+
+function loadSize(key: string, b: { min: number; max: number; def: number }): number {
+    try {
+        const n = Number(globalThis.localStorage?.getItem(key))
+        return Number.isFinite(n) && n >= b.min && n <= b.max ? n : b.def
+    } catch {
+        return b.def
+    }
+}
+
+function loadPlace(): PreviewPlace {
+    try {
+        const v = globalThis.localStorage?.getItem(PLACE_KEY) ?? ''
+        return (PLACES as readonly string[]).includes(v) ? (v as PreviewPlace) : 'left'
+    } catch {
+        return 'left'
+    }
+}
+
+function keep(key: string, v: string): void {
+    try {
+        globalThis.localStorage?.setItem(key, v)
+    } catch { /* private window: the choice lasts the tab */ }
+}
+
+export class WikiSt {
+    /** the open wiki's route, `/graph/<id>`: every read is under it */
+    href: string | null = null
+    query = ''
+    hits: WikiHit[] = []
+    /** the hit under the arrows */
+    cursor = 0
+    /** the dropdown shows */
+    listOpen = false
+    page: WikiPage | null = null
+    error = ''
+    width = loadSize(WIDTH_KEY, PREVIEW)
+    height = loadSize(HEIGHT_KEY, PREVIEW_H)
+    place: PreviewPlace = loadPlace()
+    /** the copy button said copied, for a moment */
+    copied = false
+    private frame: Window | null = null
+    private timer: ReturnType<typeof setTimeout> | null = null
+    private asked = 0
+
+    constructor(private readonly st: RepoSt) {
+        makeAutoObservable<this, 'st' | 'frame' | 'timer' | 'asked'>(this, { st: false, frame: false, timer: false, asked: false })
+    }
+
+    /** the wiki shown changed: its search starts over, and its index opens */
+    bind(href: string | null): void {
+        if (href === this.href) return
+        this.href = href
+        this.query = ''
+        this.hits = []
+        this.page = null
+        this.error = ''
+        this.listOpen = false
+        if (href != null) void this.open('')
+    }
+
+    /** the graph's iframe, to send it focus and theme */
+    setFrame(w: Window | null): void {
+        this.frame = w
+    }
+
+    send(msg: { type: 'wiki-graph:focus'; id: string } | { type: 'wiki-graph:theme'; theme: 'dark' | 'light' }): void {
+        this.frame?.postMessage(msg, '*')
+    }
+
+    setQuery(q: string): void {
+        this.query = q
+        this.cursor = 0
+        this.listOpen = q.trim() !== ''
+        if (this.timer != null) clearTimeout(this.timer)
+        if (q.trim() === '') {
+            this.hits = []
+            return
+        }
+        this.timer = setTimeout(() => void this.search(q), SEARCH_MS)
+    }
+
+    private async search(q: string): Promise<void> {
+        if (this.href == null) return
+        const n = ++this.asked
+        try {
+            const r = await fetch(this.st.url(`${this.href}/search?q=${encodeURIComponent(q)}`))
+            if (!r.ok) throw new Error(`${r.status} ${await r.text()}`)
+            const hits = (await r.json()) as WikiHit[]
+            // an answer to an older query never replaces a newer one
+            if (n === this.asked) runInAction(() => { this.hits = hits; this.error = '' })
+        } catch (e) {
+            if (n === this.asked) runInAction(() => (this.error = `search failed: ${(e as Error).message}`))
+        }
+    }
+
+    /** the search input's keys: up and down walk the hits, enter opens one, escape closes the list */
+    key(k: string): boolean {
+        if (k === 'Escape') {
+            if (!this.listOpen) return false
+            this.listOpen = false
+            return true
+        }
+        if (this.hits.length === 0) return false
+        if (k === 'ArrowDown') this.cursor = Math.min(this.hits.length - 1, this.cursor + 1)
+        else if (k === 'ArrowUp') this.cursor = Math.max(0, this.cursor - 1)
+        else if (k === 'Enter') void this.open(this.hits[this.cursor]!.id)
+        else return false
+        if (k !== 'Enter') this.listOpen = true
+        return true
+    }
+
+    /** a page opens in the preview, and its ball is focused in the graph; '' = the wiki's index */
+    async open(id: string): Promise<void> {
+        const href = this.href
+        if (href == null) return
+        this.listOpen = false
+        if (id !== '') this.send({ type: 'wiki-graph:focus', id })
+        try {
+            const r = await fetch(this.st.url(`${href}/page?node=${encodeURIComponent(id)}`))
+            if (!r.ok) throw new Error(`${r.status} ${await r.text()}`)
+            const p = (await r.json()) as WikiPage
+            // the wiki changed while the page was read: it is not this one's
+            if (href !== this.href) return
+            runInAction(() => { this.page = p; this.error = '' })
+            if (id === '') this.send({ type: 'wiki-graph:focus', id: p.id })
+        } catch (e) {
+            runInAction(() => (this.error = `${id === '' ? 'the index' : id} would not open: ${(e as Error).message}`))
+        }
+    }
+
+    setPlace(p: PreviewPlace): void {
+        this.place = p
+        keep(PLACE_KEY, p)
+    }
+
+    /** the open page's path on disk, to the clipboard */
+    async copyPath(): Promise<void> {
+        if (this.page == null) return
+        try {
+            await navigator.clipboard.writeText(this.page.file)
+            runInAction(() => (this.copied = true))
+            setTimeout(() => runInAction(() => (this.copied = false)), 1500)
+        } catch (e) {
+            runInAction(() => (this.error = `the path was not copied: ${(e as Error).message}`))
+        }
+    }
+
+    close(): void {
+        this.page = null
+    }
+
+    /** a drag of the preview's separator ended at this size: its width beside the graph, its height under it */
+    setSize(px: number): void {
+        if (this.place === 'bottom') {
+            this.height = Math.round(Math.min(PREVIEW_H.max, Math.max(PREVIEW_H.min, px)))
+            keep(HEIGHT_KEY, String(this.height))
+        } else {
+            this.width = Math.round(Math.min(PREVIEW.max, Math.max(PREVIEW.min, px)))
+            keep(WIDTH_KEY, String(this.width))
+        }
+    }
+
+    /** a message from the graph: a ball was clicked */
+    onMessage(data: unknown): void {
+        const m = data as { type?: unknown; id?: unknown } | null
+        if (m != null && m.type === 'wiki-graph:pick' && typeof m.id === 'string') void this.open(m.id)
+    }
+}

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

@@ -1,7 +1,16 @@
 // The wikis page: one tab per mounted markdown wiki, one link graph at a
 // time, embedded from its own /graph/<id> route. A tab is an item of the
 // wikis collection, so the open wiki is in the url like any other page.
+// Over the graph a search bar (title and full text, a dropdown the arrows
+// walk); a hit, or a click on a ball, opens the page in a resizable panel on
+// the right, whose refs open their page in turn and focus its ball (wiki-st.ts).
 import { observer } from 'mobx-react-lite'
+import { useEffect, useRef, type MouseEvent } from 'react'
+import { Group, Panel, Separator, type Layout } from 'react-resizable-panels'
+import { renderWikiPage } from './md.ts'
+import { editorHref } from './check-words.ts'
+import { Icon, ICON } from './icons.tsx'
+import { PLACES, PREVIEW, PREVIEW_H, type PreviewPlace, type WikiSt } from './wiki-st.ts'
 import type { RepoSt } from './repo-st.ts'
 import type { Resource } from './hub-types.ts'
 
@@ -33,8 +42,13 @@ export function openWikis(app: RepoSt): void {
     else app.showCol(WIKIS)
 }
 
+const PANEL = { overflow: 'hidden' } as const
+
 export const WikisView = observer(({ app, id }: { app: RepoSt; id: string }) => {
     const i = app.cols.find(WIKIS, id)
+    const w = app.wiki
+    const href = i?.href ?? null
+    useEffect(() => w.bind(href), [w, href])
     const tabs = (
         <span className="seg">
             {wikiTabs(app).map((t) => <button key={t.id} className={t.on ? 'on' : ''} onClick={t.go}><span className={`tl ${t.state}`}>{t.label}</span></button>)}
@@ -45,13 +59,128 @@ export const WikisView = observer(({ app, id }: { app: RepoSt; id: string }) =>
         <div className="graphview">
             <div className="gvhead">
                 {tabs}
+                {href == null ? null : <WikiSearch w={w} />}
                 <span className={`gvtext tl ${i.state}`}>{i.text}</span>
             </div>
-            {i.href == null ? <div className="ph">this wiki carries no page to embed</div> : (
-                // the spinner sits under the frame: the graph page paints its
-                // own background over it the moment it has something to show
-                <div className="gvframe"><span className="gvwait"><span className="spin" />reading the wiki…</span><iframe src={app.url(i.href)} title={i.title} /></div>
-            )}
+            {w.error !== '' ? <div className="hnote">{w.error}</div> : null}
+            {href == null ? <div className="ph">this wiki carries no page to embed</div> : <WikiBody app={app} w={w} href={href} title={i.title} />}
+        </div>
+    )
+})
+
+/** the graph and, once a page is open, its preview on the right; the preview's width is dragged and kept */
+const WikiBody = observer(({ app, w, href, title }: { app: RepoSt; w: WikiSt; href: string; title: string }) => {
+    const el = useRef<HTMLDivElement | null>(null)
+    const frame = useRef<HTMLIFrameElement | null>(null)
+    const theme = app.home.theme.resolved
+    // the theme the graph first paints in rides its url; a later change is a message, never a reload
+    const first = useRef(theme)
+    useEffect(() => w.send({ type: 'wiki-graph:theme', theme }), [w, theme])
+    useEffect(() => {
+        const on = (ev: MessageEvent): void => {
+            if (ev.source != null && ev.source === frame.current?.contentWindow) w.onMessage(ev.data)
+        }
+        addEventListener('message', on)
+        return () => removeEventListener('message', on)
+    }, [w])
+    const sep = href.includes('?') ? '&' : '?'
+    const below = w.place === 'bottom'
+    const graph = (
+        <Panel key="graph" id="wiki-graph" minSize={below ? 160 : 280} style={PANEL}>
+            {/* the spinner sits under the frame: the graph page paints its own background over it the moment it has something to show */}
+            <div className="gvframe"><span className="gvwait"><span className="spin" />reading the wiki…</span>
+                <iframe ref={(f) => { frame.current = f; w.setFrame(f?.contentWindow ?? null) }} src={`${app.url(href)}${sep}theme=${first.current}`} title={title}
+                    onLoad={() => {
+                        w.setFrame(frame.current?.contentWindow ?? null)
+                        w.send({ type: 'wiki-graph:theme', theme: app.home.theme.resolved })
+                        if (w.page != null) w.send({ type: 'wiki-graph:focus', id: w.page.id })
+                    }} />
+            </div>
+        </Panel>
+    )
+    const preview = w.page == null ? null : (
+        <Panel key="preview" id="wiki-preview" defaultSize={below ? w.height : w.width} minSize={below ? PREVIEW_H.min : PREVIEW.min} maxSize={below ? PREVIEW_H.max : PREVIEW.max}
+            groupResizeBehavior="preserve-pixel-size" style={PANEL}>
+            <WikiPreview w={w} />
+        </Panel>
+    )
+    const line = preview == null ? null : <Separator key="sep" className={below ? 'rsep hsep' : 'rsep'} />
+    return (
+        // the group is remade when the preview moves: its panels change order and axis
+        <Group key={w.place} className="gvbody" orientation={below ? 'vertical' : 'horizontal'} elementRef={el}
+            onLayoutChanged={(layout: Layout, meta) => {
+                const pct = layout['wiki-preview']
+                const r = el.current?.getBoundingClientRect()
+                const whole = below ? r?.height : r?.width
+                if (meta.isUserInteraction && pct != null && whole != null && whole > 0) w.setSize((pct / 100) * whole)
+            }}>
+            {w.place === 'left' ? [preview, line, graph] : [graph, line, preview]}
+        </Group>
+    )
+})
+
+/** the search bar: the hits drop under it, the arrows walk them, enter or a click opens one */
+const WikiSearch = observer(({ w }: { w: WikiSt }) => (
+    <span className="wsearch">
+        <input type="search" placeholder="search the wiki: a title, a word…" aria-label="search the wiki" value={w.query}
+            onChange={(e) => w.setQuery(e.currentTarget.value)}
+            onFocus={() => { if (w.hits.length > 0) w.key('ArrowUp') }}
+            onBlur={() => w.key('Escape')}
+            onKeyDown={(e) => { if (w.key(e.key)) e.preventDefault() }} />
+        {w.listOpen && w.query.trim() !== '' ? (
+            <div className="wslist" role="listbox">
+                {w.hits.length === 0 ? <div className="wsnone">no page matches</div> : w.hits.map((h, n) => (
+                    // mouse down, not click: the input's blur would close the list first
+                    <div key={h.id} role="option" aria-selected={n === w.cursor} className={`wshit${n === w.cursor ? ' on' : ''}`}
+                        onMouseDown={(e) => { e.preventDefault(); void w.open(h.id) }}>
+                        <div className="wshead"><b>{h.title}</b><span className="wspath">{h.id}</span></div>
+                        {h.snippet === '' || h.inTitle && h.snippet === '' ? null : <div className="wssnip">{h.snippet}</div>}
+                    </div>
+                ))}
+            </div>
+        ) : null}
+    </span>
+))
+
+const PLACE_ICON: Record<PreviewPlace, keyof typeof ICON> = { left: 'paneLeft', right: 'paneRight', bottom: 'paneBottom' }
+
+/** the open page: its title and path, where the panel sits, the editor and
+ *  the copy, the close; then the markdown, whose refs open their own page */
+const WikiPreview = observer(({ w }: { w: WikiSt }) => {
+    const p = w.page!
+    const editor = editorHref('', p.file)
+    const click = (e: MouseEvent<HTMLDivElement>): void => {
+        const t = e.target as HTMLElement
+        const a = t.closest('a[data-wiki]')
+        if (a != null) {
+            e.preventDefault()
+            void w.open(a.getAttribute('data-wiki')!)
+            return
+        }
+        // a ref in a code span opens its page by its text
+        const code = t.closest('code')
+        const to = code == null ? undefined : p.links[code.textContent ?? '']
+        if (to != null) void w.open(to)
+    }
+    return (
+        <div className="wprev">
+            <div className="wphead">
+                <b className="wptitle">{p.title}</b>
+                <span className="wspath" title={p.file}>{p.id}</span>
+                <span className="seg wpplace" aria-label="where the preview sits">
+                    {PLACES.map((pl) => (
+                        <button key={pl} className={w.place === pl ? 'on' : ''} aria-label={`the preview on the ${pl}`} title={`the preview on the ${pl}`} onClick={() => w.setPlace(pl)}>
+                            <Icon d={ICON[PLACE_ICON[pl]]} />
+                        </button>
+                    ))}
+                </span>
+                {editor == null ? null : (
+                    <a className="wpbtn" href={editor} title={`open ${p.file} in VS Code`}><Icon d={ICON.editor} /><span>VS Code</span></a>
+                )}
+                <button className="wpbtn" title={`copy ${p.file}`} onClick={() => void w.copyPath()}><Icon d={ICON.copy} /><span>{w.copied ? 'copied' : 'copy path'}</span></button>
+                <button className="ghost wpclose" aria-label="close the preview" title="close the preview" onClick={() => w.close()}>×</button>
+            </div>
+            <div className="wpbody md readme-body" onClick={click} dangerouslySetInnerHTML={{ __html: renderWikiPage(p.md, p.links) }} />
         </div>
     )
 })

package/src/serve/hub-runtime.ts

@@ -146,15 +146,15 @@ export async function resolveHubDeps(root: string, boot: RepoConfig, io: ServeIo
     // agent working here obeys that wiki, so a reader can open it.
     const graphs: GraphMount[] = []
     if (c.serve?.wikiGraph != null)
-        graphs.push({ id: 'wiki', label: WIKI_LABEL, title: c.serve.wikiGraph.title ?? `${c.name} wiki`, load: c.serve.wikiGraph.load, lint: c.serve.wikiGraph.lint != null ? { checks: c.serve.wikiGraph.lint } : { root } })
+        graphs.push({ id: 'wiki', label: WIKI_LABEL, title: c.serve.wikiGraph.title ?? `${c.name} wiki`, load: c.serve.wikiGraph.load, dir: c.serve.wikiGraph.dir ?? root, lint: c.serve.wikiGraph.lint != null ? { checks: c.serve.wikiGraph.lint } : { root } })
     else if (existsSync(join(root, 'wiki')))
-        graphs.push({ id: 'wiki', label: WIKI_LABEL, title: `${c.name} wiki`, load: () => scanMdGraph({ root }), lint: { root } })
+        graphs.push({ id: 'wiki', label: WIKI_LABEL, title: `${c.name} wiki`, load: () => scanMdGraph({ root }), dir: root, lint: { root } })
     const baseWiki = baseWikiRoot(root)
     if (baseWiki != null)
-        graphs.push({ id: 'base', label: wikiLabel(baseWiki), title: wikiLabel(baseWiki), load: () => scanMdGraph({ root: baseWiki }), lint: null })
+        graphs.push({ id: 'base', label: wikiLabel(baseWiki), title: wikiLabel(baseWiki), load: () => scanMdGraph({ root: baseWiki }), dir: baseWiki, lint: null })
     const agentRoot = join(root, 'agent')
     if (existsSync(agentRoot))
-        graphs.push({ id: 'agent', label: 'agent/', title: `${c.name} agent/`, load: () => scanMdGraph({ root: agentRoot, index: c.serve?.agentIndex }), lint: { root: agentRoot, index: c.serve?.agentIndex } })
+        graphs.push({ id: 'agent', label: 'agent/', title: `${c.name} agent/`, load: () => scanMdGraph({ root: agentRoot, index: c.serve?.agentIndex }), dir: agentRoot, lint: { root: agentRoot, index: c.serve?.agentIndex } })
     // ONE page for every repo: the studio ALWAYS
     // mounts — kit-less repos get an empty media section, never a second
     // page. A broken kit degrades to the same empty kit, loudly, and a repo

package/src/serve/project-gutter-route.ts

@@ -30,6 +30,8 @@ export type { Gate }
 export const POLL_MS = 5_000
 /** the app icon preview: sharp on a 2x screen at the admin page's 128px */
 const PREVIEW_PX = 256
+/** the rail's app icon, cropped to the plate: 40px at 2x, the largest rail size */
+const RAIL_PX = 96
 /** how long a release answer holds for a checkout whose `.git` is not a
  *  folder, since no stat can say when it moved */
 export const RELEASE_TTL_MS = 60_000
@@ -74,6 +76,8 @@ export type ProjectRow = {
     live: string | null
     /** the colours its repo.config.ts declares (SK024), null when it declares none */
     identity: Identity | null
+    /** its app icon cropped to the plate (core/app-icon.ts), what the folded rail draws; null with no mark */
+    appIcon: string | null
     /** epoch ms of the newest of: the last commit, the last shipkit run, the
      *  newest Claude Code transcript. null when none of them exists */
     activity: number | null
@@ -298,6 +302,15 @@ export function projectGutter(d: GutterDeps) {
     }
 
     const iconUrl = (r: WiredRepo): string | null => (r.icon == null ? null : `/api/projects/icon/${encodeURIComponent(r.name)}?v=${iconStamp(join(r.path, r.icon))}`)
+    // the url names the mark's stamp and both colours, so a new mark or a colour change is a new url, cached a day
+    const railIconUrl = (r: WiredRepo, id: Identity): string | null => {
+        const mark = appIconOf(r.path)
+        if (mark == null) return null
+        const q = new URLSearchParams({ plate: '1', light: id.colorLight, dark: id.colorDark, v: String(iconStamp(mark)) })
+        return `/api/projects/app-icon/${encodeURIComponent(r.name)}?${q}`
+    }
+    /** drawn plates, by url: a page load asks for every repo's at once */
+    const plates = new Map<string, Promise<Buffer>>()
 
     async function measure(): Promise<ProjectsAnswer> {
         const t0 = performance.now()
@@ -334,6 +347,7 @@ export function projectGutter(d: GutterDeps) {
                 release: facts[i]!.release,
                 live: liveUrlOf(config),
                 identity: identityOfText(config),
+                appIcon: railIconUrl(r, identityOfRoot(r.path)),
                 activity: lastActivity(facts[i]!.commitAt, lastRunAt(r.path), transcripts.get(r.path)),
                 commit: facts[i]!.commitAt,
             }
@@ -386,12 +400,22 @@ export function projectGutter(d: GutterDeps) {
             const r = findAny(decodeURIComponent(path.slice('/api/projects/app-icon/'.length)))
             if (r == null) return new Response('not a house repo', { status: 404 })
             const icon = appIconOf(r.path)
-            if (icon == null) return new Response('no png mark: the app wears the default icon', { status: 404 })
+            if (icon == null) return new Response('no mark: the app wears the default icon', { status: 404 })
             // the colours a picker is on right now, before they are saved; else the config's
             const q = new URL(req.url).searchParams
             const asked = { colorLight: q.get('light') ?? '', colorDark: q.get('dark') ?? '' }
             const id = identityProblem(asked) == null ? asked : identityOfRoot(r.path)
             try {
+                if (q.get('plate') === '1') {
+                    const key = `${r.path}?${q}`
+                    let png = plates.get(key)
+                    if (png == null) {
+                        png = readFile(icon).then(async (b) => (await appIconPngs(b, id, [RAIL_PX], 'plate'))[0]!)
+                        plates.set(key, png)
+                        png.catch(() => plates.delete(key))
+                    }
+                    return new Response(new Uint8Array(await png), { headers: { 'content-type': 'image/png', 'cache-control': 'max-age=86400' } })
+                }
                 const [png] = await appIconPngs(await readFile(icon), id, [PREVIEW_PX])
                 return new Response(new Uint8Array(png!), { headers: { 'content-type': 'image/png', 'cache-control': 'max-age=60' } })
             } catch (e) {

package/src/serve/project-gutter.ts

@@ -48,7 +48,7 @@ export function houseIndex(repo: string, home: string): string | null {
 
 /** a repo's own icon, first hit wins. `.shipkit/identity/icon.png` is the rail
  *  icon a repo with no public surface carries, the identity kit writes public/ */
-export const ICON_FILES = ['.shipkit/identity/icon.png', 'public/favicon.png', 'public/favicon.svg', 'public/favicon.ico', 'favicon.ico', 'public/logo.png']
+export const ICON_FILES = ['.shipkit/identity/icon.png', '.shipkit/identity/icon.svg', 'public/favicon.png', 'public/favicon.svg', 'public/favicon.ico', 'favicon.ico', 'public/logo.png']
 
 export const ICON_TYPES: Record<string, string> = { png: 'image/png', svg: 'image/svg+xml', ico: 'image/x-icon' }
 

package/src/serve/serve-hub.ts

@@ -7,6 +7,7 @@
 import { existsSync } from 'fs'
 import { join } from 'path'
 import { positionsFile } from 'rvlib-shipkit/src/wiki/graph-positions.ts'
+import { pageOf, searchWiki } from 'rvlib-shipkit/src/wiki/graph-pages.ts'
 import { graphRoutes } from 'rvlib-shipkit/src/wiki/serve-graph.ts'
 import type { StudioRoutes } from '../assets/server/studio-server.ts'
 import { comfyBoxUp, type ComfyBox, type ComfyPanelUp } from '../comfy/comfy-panel.ts'
@@ -411,6 +412,12 @@ export function hubHandler(d: HubDeps, o: { base?: string; projects?: Gutter } =
                 if (path === `/graph/${g.id}`) return page(routes.page())
                 if (path === `/graph/${g.id}/graph.json`) return Response.json(held)
                 if (path === `/graph/${g.id}/positions`) return routes.save(req)
+                // the wikis page's search bar and its preview panel: only a node of the graph is read
+                if (path === `/graph/${g.id}/search`) return g.dir == null ? new Response('this wiki names no folder to read', { status: 404 }) : Response.json(searchWiki(held, g.dir, new URL(req.url).searchParams.get('q') ?? ''))
+                if (path === `/graph/${g.id}/page`) {
+                    const p = g.dir == null ? null : pageOf(held, g.dir, new URL(req.url).searchParams.get('node') ?? '')
+                    return p == null ? new Response('not a page of this wiki', { status: 404 }) : Response.json(p)
+                }
             }
             // the media API namespace — the studio route table, ONE prefix strip
             if (d.studio != null && path.startsWith('/media/')) return d.studio.handle(req, path.slice('/media'.length))

package/src/shot/client.ts

@@ -8,7 +8,7 @@ import type { ShotDone } from './shooter.ts'
 /** the global process id pm knows the service by (shot.shipkit.ts) */
 export const SHOT_PROCESS = 'shot'
 
-export type ShotInput = { url: string; out: string; viewport?: Viewport; dpr?: number; reload?: boolean; waitMs?: number }
+export type ShotInput = { url: string; out: string; viewport?: Viewport; dpr?: number; reload?: boolean; waitMs?: number; step?: string; at?: number }
 export type ClipInput = ShotInput & { seconds: number; fps?: number; dom?: boolean }
 export type ShotResult = ShotDone & { via: 'warm' | 'started' | 'local' }
 
@@ -21,13 +21,25 @@ const shotAsk = (i: ShotInput): ShotAsk => ({
     waitMs: i.waitMs ?? DEFAULT_WAIT_MS,
 })
 
-/** a png of `url` at `out` (absolute), through the warm browser */
-export const shotUrl = (i: ShotInput, log: (l: string) => void = () => {}): Promise<ShotResult> => ask('/shot', shotAsk(i), log)
+/** a service of an older shipkit takes a stepped ask, ignores the step and shoots the page as it loads: never kept */
+function stepped(i: { step?: string }, r: ShotResult): void {
+    if (i.step && r.stepped !== true) throw new Error(`the shot service on ${shotUrlBase()} did not step the page (it says: ${r.note}); it runs an older shipkit: sk gp restart ${SHOT_PROCESS}`)
+}
+
+/** a png of `url` at `out` (absolute), through the warm browser; with `step`, the page drawn at `at` first */
+export async function shotUrl(i: ShotInput, log: (l: string) => void = () => {}): Promise<ShotResult> {
+    const r = await ask('/shot', { ...shotAsk(i), ...(i.step ? { step: i.step, at: i.at ?? 0 } : {}) }, log)
+    stepped(i, r)
+    return r
+}
 
 /** an mp4 of `seconds` of `url` at `out` (absolute): a page that is a canvas through its WebCodecs, any other page (or
  *  `dom`) as chromium paints it */
-export const clipUrl = (i: ClipInput, log: (l: string) => void = () => {}): Promise<ShotResult> =>
-    ask('/clip', { ...shotAsk(i), seconds: i.seconds, fps: i.fps ?? DEFAULT_FPS, dom: i.dom ?? false } satisfies ClipAsk, log)
+export async function clipUrl(i: ClipInput, log: (l: string) => void = () => {}): Promise<ShotResult> {
+    const r = await ask('/clip', { ...shotAsk(i), seconds: i.seconds, fps: i.fps ?? DEFAULT_FPS, dom: i.dom ?? false, ...(i.step ? { step: i.step } : {}) } satisfies ClipAsk, log)
+    stepped(i, r)
+    return r
+}
 
 /** null when nothing listens (start it), else the service's answer; a refusal throws its reason */
 async function post(route: string, a: ShotAsk): Promise<ShotDone | null> {

package/src/shot/shooter.ts

@@ -59,7 +59,7 @@ export const SHOT_NICE = 10
 /** a page that paints nothing once the screencast starts is filmed from one still taken after this */
 const FIRST_FRAME_MS = 1000
 
-export type ShotDone = { out: string; ms: number; phases: Record<string, number>; errors: string[]; note: string }
+export type ShotDone = { out: string; ms: number; phases: Record<string, number>; errors: string[]; note: string; stepped?: true }
 
 type Slot = { key: string; url: string; ctx: Context; page: Page; cdp: Cdp; errors: string[]; frozen: boolean }
 
@@ -169,6 +169,8 @@ export class Shooter {
         const phases: Record<string, number> = {}
         const t0 = performance.now()
         let move = pageMove(this.#slot == null || this.#slot.page.isClosed() ? null : { url: this.#slot.url, key: this.#slot.key }, a)
+        // a stepped still draws its moment on a fresh load, never on a page some other shot left at another time
+        if (a.step && move === 'none') move = 'reload'
         if (move === 'boot') {
             const old = this.#slot
             this.#slot = null
@@ -200,13 +202,22 @@ export class Shooter {
         let t = performance.now()
         const how = await waitReady(() => slot.page.evaluate(readMark), move === 'none' ? 0 : a.waitMs, { now: () => performance.now(), sleep: (n) => slot.page.waitForTimeout(n) })
         phases['ready'] = ms(t)
+        if (a.step) {
+            t = performance.now()
+            const { stepTo } = await import('./stepped-clip.ts')
+            if (!(await slot.page.evaluate(stepTo, [a.step, a.at ?? 0] as [string, number]))) throw new Error(`the page has no window.${a.step}(t): a stepped page draws the time it is given there`)
+            await waitReady(() => slot.page.evaluate(readMark), 0, { now: () => performance.now(), sleep: (n) => slot.page.waitForTimeout(n) })
+            // the warm page now shows that moment: the next plain shot of this url loads it again
+            slot.url = ''
+            phases['step'] = ms(t)
+        }
         t = performance.now()
         const r = await slot.cdp.send('Page.captureScreenshot', { format: 'png', optimizeForSpeed: true })
         phases['capture'] = ms(t)
         mkdirSync(dirname(a.out), { recursive: true })
         await Bun.write(a.out, Buffer.from(String(r['data']), 'base64'))
-        const note = `${move === 'none' ? 'warm page' : thawed ? 'frozen page reloaded' : move}, ${how === 'ready' ? 'ready mark' : move === 'none' ? 'no wait' : `${a.waitMs} ms after load`}`
-        return { out: a.out, ms: ms(t0), phases, errors: [...slot.errors], note }
+        const note = `${move === 'none' ? 'warm page' : thawed ? 'frozen page reloaded' : move}, ${how === 'ready' ? 'ready mark' : move === 'none' ? 'no wait' : `${a.waitMs} ms after load`}${a.step ? `, drawn at ${a.at ?? 0}s through window.${a.step}(t)` : ''}`
+        return { out: a.out, ms: ms(t0), phases, errors: [...slot.errors], note, ...(a.step ? { stepped: true as const } : {}) }
     }
 
     async #clip(a: ClipAsk): Promise<ShotDone> {
@@ -223,6 +234,11 @@ export class Shooter {
             await waitReady(() => page.evaluate(readMark), a.waitMs, { now: () => performance.now(), sleep: (n) => page.waitForTimeout(n) })
             phases['load'] = ms(t)
             t = performance.now()
+            if (a.step) {
+                const note = await (await import('./stepped-clip.ts')).stepPage(await ctx.newCDPSession(page), page, a as ClipAsk & { step: string })
+                phases['film'] = ms(t)
+                return { out: a.out, ms: ms(t0), phases, errors, note, stepped: true }
+            }
             const path: ClipPath = clipPathOf({ dom: a.dom === true, canvas: await page.evaluate(largestCanvas), viewport: a.viewport })
             const why = path === 'canvas' ? await page.evaluate(installClip, { seconds: a.seconds, fps: a.fps, quantizer: CLIP_QUANTIZER, keyEvery: KEY_EVERY } satisfies PageClipAsk) : null
             if (path === 'dom' || why != null) {

package/src/shot/shot-ask.ts

@@ -17,6 +17,9 @@ export type ShotAsk = {
     reload: boolean
     /** a page with no ready mark is shot this long after its load (a warm page at once) */
     waitMs: number
+    /** a still of a stepped page: `window[step](at)` on a fresh load, then its ready mark, then the shot */
+    step?: string
+    at?: number
 }
 
 export type ClipAsk = ShotAsk & {
@@ -24,6 +27,9 @@ export type ClipAsk = ShotAsk & {
     fps: number
     /** film the page itself even when a canvas fills it (dom-clip.ts); a page with no big canvas is filmed so anyway */
     dom?: boolean
+    /** step the page frame by frame (stepped-clip.ts): before each frame `window[step](t)`, t its time in seconds, then
+     *  its ready mark; a slow page films as smooth as a fast one */
+    step?: string
 }
 
 export const DEFAULT_SHOT_PORT = 4796
@@ -113,7 +119,9 @@ export const isClip = (a: ShotAsk | ClipAsk): a is ClipAsk => 'seconds' in a
 
 /** a request held past this (a clip: past its own seconds) fails loud and frees the turn */
 export const REQUEST_MAX_MS = 120_000
-export const capMsOf = (a: ShotAsk | ClipAsk): number => REQUEST_MAX_MS + (isClip(a) ? a.seconds * 1000 : 0)
+export const capMsOf = (a: ShotAsk | ClipAsk): number => REQUEST_MAX_MS + (isClip(a) ? (a.step ? a.seconds * a.fps * STEP_FRAME_MS : a.seconds * 1000) : 0)
+/** a stepped frame's budget in the request's cap: a page that draws a frame slower than this is no page to step */
+export const STEP_FRAME_MS = 1000
 
 // ── the ready mark ──────────────────────────────────────────────────────────
 // A page that knows when it is drawn says so: `<meta name="shot-ready"