rvlib-shipkit 2.2.0 → 2.4.0

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

@@ -0,0 +1,56 @@
+// the page's theme, a node of the root (home-st.ts): his pick (dark, light or
+// auto, which follows the system) kept per browser, resolved to dark or light
+// on <html data-theme>, where hub.css swaps its token block. Applied at
+// construction, before the first render, so a reload paints in the theme.
+import { autorun, makeAutoObservable, runInAction } from 'mobx'
+
+export const THEMES = ['dark', 'light', 'auto'] as const
+export type ThemePick = (typeof THEMES)[number]
+export type Theme = 'dark' | 'light'
+
+const KEY = 'hub:theme'
+
+function loadPick(): ThemePick {
+    try {
+        const v = globalThis.localStorage?.getItem(KEY)
+        return (THEMES as readonly string[]).includes(v ?? '') ? (v as ThemePick) : 'auto'
+    } catch {
+        return 'auto'
+    }
+}
+
+export class ThemeSt {
+    pick: ThemePick = loadPick()
+    /** what the system asks for, read live */
+    system: Theme = 'dark'
+
+    constructor() {
+        makeAutoObservable(this)
+        const mq = typeof window !== 'undefined' && typeof window.matchMedia === 'function' ? window.matchMedia('(prefers-color-scheme: light)') : null
+        if (mq != null) {
+            this.system = mq.matches ? 'light' : 'dark'
+            mq.addEventListener('change', (e) => runInAction(() => (this.system = e.matches ? 'light' : 'dark')))
+        }
+        const root = typeof document !== 'undefined' ? document.documentElement : null
+        if (root != null) autorun(() => {
+            root.dataset.theme = this.resolved
+            root.style.colorScheme = this.resolved
+        })
+    }
+
+    get resolved(): Theme {
+        return this.pick === 'auto' ? this.system : this.pick
+    }
+
+    set(p: ThemePick): void {
+        this.pick = p
+        try {
+            globalThis.localStorage?.setItem(KEY, p)
+        } catch { /* private window or blocked site data: the pick lasts the tab */ }
+    }
+
+    /** the foot's button: dark, light, auto, then dark again */
+    cycle(): void {
+        this.set(THEMES[(THEMES.indexOf(this.pick) + 1) % THEMES.length]!)
+    }
+}

package/src/serve/hub-app/tree-build.ts

@@ -74,6 +74,8 @@ export const KIND_SECTION: Record<ResourceType, SectionId> = {
     post: 'media',
     wiki: 'wikis',
     process: 'processes',
+    card: 'review',
+    cut: 'trailer',
 }
 
 /** a process's colour: up reads green, crashed red, on its way orange,
@@ -392,6 +394,8 @@ export const TYPE_MARK: Record<string, TypeMark> = {
     test: { glyph: '\u2263', hue: 'k5', word: 'a test file: the check that runs it, its last runs against its budget, the command that runs it alone' },
     reflection: { glyph: '\u203b', hue: 'k2', word: 'a reflection: friction this repo logged against the wiki, waiting to be folded in' },
     process: { glyph: '\u223f', hue: 'k1', word: 'a global process this repo declares: its state, its menu, its log' },
+    card: { glyph: '\u25a3', hue: 'k2', word: 'a review card waiting for your answer: approve, fix, reject, circle a detail' },
+    cut: { glyph: '\u25b6', hue: 'k3', word: 'a trailer cut: play it with its timeline, pin a note on any frame' },
     done: { glyph: '\u2713', hue: 'k5', word: 'a done ask: answered, filed under done, out of every count above it' },
 }
 

package/src/serve/hub-app/tree-row.tsx

@@ -45,7 +45,7 @@ export const SectionRowView = observer(({ app, row }: { app: RepoSt; row: TreeRo
     const key = s == null ? null : sectionKeyLabel(id)
     const el = useInSight(t.cursor === row.key)
     return (
-        <div ref={el} className={`tsec${s?.empty === true ? ' empty' : ''}${s?.opens === false ? ' noop' : ''}${s?.on === true ? ' cur' : ''}${t.cursor === row.key ? ' on' : ''}`} aria-current={s?.on === true ? 'page' : undefined}
+        <div ref={el} className={`tsec s-${id}${s?.empty === true ? ' empty' : ''}${s?.opens === false ? ' noop' : ''}${s?.on === true ? ' cur' : ''}${t.cursor === row.key ? ' on' : ''}`} aria-current={s?.on === true ? 'page' : undefined}
             title={s == null ? row.label : `${s.title} (${key})`} onClick={() => t.click(row)}>
             <Fold app={app} row={row} />
             <Icon d={ICON[id]} />

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

@@ -144,6 +144,10 @@ export class TreeSvc {
         this.cursor = row.key
         this.activate(row)
     }
+    /** a click in the page: the arrows are the page's again until the tree is walked or clicked */
+    leave(): void {
+        this.cursor = null
+    }
     /** the chevron: fold or unfold, never open */
     fold(row: TreeRow): void {
         this.cursor = row.key

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

@@ -58,6 +58,7 @@ import { hubHandler, type CheckTap, type HubDeps, type HubHandler } from './serv
 import type { projectGutter } from './project-gutter-route.ts'
 import { defaultHubPort } from './hub-port.ts'
 import { LAYOUT } from '../core/layout.ts'
+import { storeDir, storeStamp } from '../review/store.ts'
 export { defaultHubPort }
 
 export type ServeIo = { print: (l: string) => void; printErr: (l: string) => void }
@@ -145,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
@@ -347,9 +348,10 @@ export async function resolveHubDeps(root: string, boot: RepoConfig, io: ServeIo
         graphs,
         studio,
         refresh,
-        // the config and the run record, by their stats: what the warm rows
-        // and the runs page read besides the tracked files the watch sees
-        stamp: () => `${configStamp(root)}|${record === '' ? '' : recordStamp(record)}`,
+        // the config, the run record and the review store (gitignored, its
+        // own watch counts its writes): what the warm rows and the runs page
+        // read besides the tracked files the watch sees
+        stamp: () => `${configStamp(root)}|${record === '' ? '' : recordStamp(record)}|${storeStamp(storeDir(root))}`,
         runCli,
         // the run happens IN THIS PROCESS, so every check result reaches the
         // page as it finishes. A shelled run could only ever deliver one wall

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/same-origin.ts

@@ -10,5 +10,9 @@ export function sameOrigin(req: Request): boolean {
     if (site != null && site !== 'same-origin' && site !== 'none') return false
     const origin = req.headers.get('origin')
     if (origin == null) return true
-    try { return new URL(origin).host === new URL(req.url).host } catch { return false }
+    // behind a proxy that frames the page under its own origin (pkm-multi's admin), the host the browser asked is the
+    // proxy's, which it passes on. A browser cannot forge the header: a page of another site that sets it is held at
+    // its preflight, which this server never answers
+    const host = req.headers.get('x-forwarded-host') ?? new URL(req.url).host
+    try { return new URL(origin).host === host } catch { return false }
 }

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'
@@ -32,6 +33,8 @@ import { sameOrigin } from './same-origin.ts'
 import { LAYOUT } from '../core/layout.ts'
 import { WarmCell } from './warm-cell.ts'
 import { readmeRoutes } from './readme-route.ts'
+import { reviewRoutes } from '../review/routes.ts'
+import { embedRoute } from './embed.ts'
 
 export { sameOrigin }
 
@@ -338,6 +341,12 @@ export function hubHandler(d: HubDeps, o: { base?: string; projects?: Gutter } =
             // the empty page shows the README, its images served from the repo
             const readme = await readmeRoutes(d.root, path)
             if (readme != null) return readme
+            // the review or trailer page alone, for another tool's frame (embed.ts)
+            const embed = await embedRoute(path)
+            if (embed != null) return embed
+            // the one feedback store and the trailer view (review/routes.ts)
+            const review = await reviewRoutes(d.root, req, path)
+            if (review != null) return review
             if (path === '/api/status.json') {
                 const p = join(d.root, LAYOUT.status)
                 return Response.json({ statusMd: existsSync(p) ? await Bun.file(p).text() : null })
@@ -403,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))