rvlib-shipkit 2.3.0 → 2.4.0

package/src/review/model.ts

@@ -124,6 +124,8 @@ export interface MediaView {
     clip?: ReviewClip
     audio?: ReviewAudio
     marks?: ReviewMark[]
+    /** a line on this view alone (an option's description on a choice card) */
+    note?: string
 }
 
 /** one image of a gallery view, a file of the folder (`v<n>-g<k>.<ext>`) */
@@ -168,8 +170,22 @@ export interface Item {
     light?: 'review'
     /** a draft card of a repo that shoots live: no verdict until it is ready */
     wip?: { live: string; frame: number }
+    /** a choice: every view is an option, he scores them and picks one */
+    choice?: true
 }
 
+/** a choice card: he picks one of its views */
+export const isChoice = (i: Item): boolean => i.choice === true
+
+/** a view that plays on its own: one clip or one sound, never a pair */
+export const isPlayable = (v: ReviewView | undefined): v is MediaView => v !== undefined && !isGallery(v) && !isPair(v.files) && (v.clip !== undefined || v.audio !== undefined)
+
+/** a card shown as options, one thin row a view: a choice, or two views or more that each play on their own */
+export const asOptions = (i: Item): boolean => isChoice(i) || (i.views.length >= 2 && i.views.every(isPlayable))
+
+/** the most stars a reaction gives */
+export const STARS = 5
+
 /** a view's name as the page and the CLI show it: its label, or « view n » */
 export const viewName = (v: ReviewView | undefined, i: number): string => v?.label || `view ${i + 1}`
 
@@ -219,6 +235,8 @@ export interface ReviewReaction {
     tile?: number
     status?: ReviewStatus
     comment: string
+    /** his score of the view, 1 to STARS */
+    stars?: number
 }
 
 /** a state change, or a read mark (`seen`, with the ids it read in `of`) */
@@ -238,6 +256,8 @@ export interface Message {
     rects?: Rect[]
     reactions?: ReviewReaction[]
     verdict?: ReviewStatus
+    /** the view he picked on a choice card, its index */
+    pick?: number
     /** a repo's own mark on a subject (stars, a song's mark): kept as written */
     rate?: { stars?: number; mark?: string; part?: string }
     op?: Op
@@ -313,6 +333,8 @@ export interface Verdict {
     comment: string
     rects: Rect[]
     reactions?: ReviewReaction[]
+    /** the view he picked, on a choice card */
+    pick?: number
     at: string
     seen: boolean
 }
@@ -338,6 +360,7 @@ export function verdictOf(x: ReviewItem): Verdict | null {
         comment: text ?? '',
         rects: rects ?? [],
         ...(m.reactions && m.reactions.length > 0 ? { reactions: m.reactions } : {}),
+        ...(m.pick !== undefined ? { pick: m.pick } : {}),
         at: m.at,
         seen: readBy(x, 'agent').has(m.id),
     }
@@ -677,6 +700,7 @@ export function itemProblems(v: unknown): string[] {
     for (const k of ['what', 'commit', 'supersedes', 'why', 'keeps']) if (v[k] !== undefined && typeof v[k] !== 'string') out.push(`${k}: a text`)
     if (v.light !== undefined && v.light !== 'review') out.push('light: review, or absent')
     if (v.wip !== undefined && !(obj(v.wip) && typeof v.wip.live === 'string' && v.wip.live !== '' && Number.isInteger(v.wip.frame))) out.push('wip: { live, frame }, or absent')
+    if (v.choice !== undefined && !(v.choice === true && Array.isArray(v.views) && v.views.length >= 2)) out.push('choice: true on a card of two views or more, or absent')
     return out
 }
 
@@ -690,6 +714,7 @@ export function messageProblems(v: unknown, name: string): string[] {
     if (v.op !== undefined && !OPS.includes(v.op as Op)) out.push(`op: one of ${OPS.join(', ')}`)
     if (v.verdict !== undefined && !STATUSES.includes(v.verdict as ReviewStatus)) out.push(`verdict: one of ${STATUSES.join(', ')}`)
     for (const k of ['text', 'image', 'note']) if (v[k] !== undefined && typeof v[k] !== 'string') out.push(`${k}: a text`)
+    if (v.pick !== undefined && !(Number.isInteger(v.pick) && (v.pick as number) >= 0 && v.verdict !== undefined)) out.push('pick: a view index, on a verdict')
     if (v.op === 'seen' && !(Array.isArray(v.of) && v.of.every((x) => typeof x === 'string'))) out.push('of: the ids a seen message read')
     if (v.op === undefined && v.verdict === undefined && v.rate === undefined && typeof v.text !== 'string' && !Array.isArray(v.rects))
         out.push('a message says something: text, rects, verdict, rate or op')
@@ -713,6 +738,7 @@ function galleryProblems(v: Record<string, unknown>, at: string): string[] {
 function viewProblems(v: Record<string, unknown>, at: string): string[] {
     const out: string[] = []
     if (typeof v.label !== 'string') out.push(`${at}label: a text`)
+    if (v.note !== undefined && typeof v.note !== 'string') out.push(`${at}note: a text`)
     const f = v.files
     const okImage = (n: unknown): boolean => typeof n === 'string' && FILE_RE.test(n) && !isClipFile(n) && !isAudioFile(n)
     const okClip = (n: unknown): boolean => typeof n === 'string' && FILE_RE.test(n) && isClipFile(n)
@@ -757,7 +783,7 @@ function viewProblems(v: Record<string, unknown>, at: string): string[] {
 }
 
 /** the verdict the page sends for an item, checked: every rectangle inside its view, a side exactly on a pair */
-export function verdictMessageOf(body: unknown, item: Item): { ok: true; message: Pick<Message, 'verdict' | 'text' | 'rects' | 'reactions'> } | { ok: false; errors: string[] } {
+export function verdictMessageOf(body: unknown, item: Item): { ok: true; message: Pick<Message, 'verdict' | 'text' | 'rects' | 'reactions' | 'pick'> } | { ok: false; errors: string[] } {
     if (!obj(body)) return { ok: false, errors: ['not an object'] }
     const errors: string[] = []
     if (!STATUSES.includes(body.status as ReviewStatus)) errors.push(`status: one of ${STATUSES.join(', ')}`)
@@ -800,7 +826,13 @@ export function verdictMessageOf(body: unknown, item: Item): { ok: true; message
         if (clip && typeof t === 'number') rect.t = t
         out.push(rect)
     }
-    const reactions = reactionsOf(body.reactions, views, errors)
+    const reactions = reactionsOf(body.reactions, views, errors, isChoice(item))
+    const pick = body.pick
+    if (pick !== undefined) {
+        if (!isChoice(item)) errors.push('pick: only on a choice card')
+        else if (!(typeof pick === 'number' && Number.isInteger(pick) && pick >= 0 && pick < views.length)) errors.push(`pick: the index of one of the card's ${views.length} views`)
+        else if (!isApproved(body.status as ReviewStatus)) errors.push('pick: goes with approved or approved-with-fix; rejecting every option is a plain rejected')
+    }
     if (errors.length > 0) return { ok: false, errors }
     const comment = typeof body.comment === 'string' ? body.comment : ''
     return {
@@ -810,13 +842,14 @@ export function verdictMessageOf(body: unknown, item: Item): { ok: true; message
             ...(comment ? { text: comment } : {}),
             ...(out.length > 0 ? { rects: out } : {}),
             ...(reactions.length > 0 ? { reactions } : {}),
+            ...(typeof pick === 'number' ? { pick } : {}),
         },
     }
 }
 
 /** the reactions the page sends, checked against the card's views: each on a view, a tile only on a gallery, one per view
  *  or tile; an empty one is dropped */
-function reactionsOf(v: unknown, views: readonly ReviewView[], errors: string[]): ReviewReaction[] {
+function reactionsOf(v: unknown, views: readonly ReviewView[], errors: string[], choice: boolean): ReviewReaction[] {
     if (v === undefined) return []
     if (!Array.isArray(v)) {
         errors.push('reactions: a list')
@@ -835,12 +868,21 @@ function reactionsOf(v: unknown, views: readonly ReviewView[], errors: string[])
         if (tile !== undefined && !(typeof tile === 'number' && Number.isInteger(tile) && tile >= 0 && tile < tiles)) errors.push(`reactions[${i}].tile: the index of one tile of a gallery view`)
         if (r.status !== undefined && !STATUSES.includes(r.status as ReviewStatus)) errors.push(`reactions[${i}].status: one of ${STATUSES.join(', ')}`)
         if (r.comment !== undefined && typeof r.comment !== 'string') errors.push(`reactions[${i}].comment: a text`)
+        const stars = r.stars
+        if (stars !== undefined && !(choice && typeof stars === 'number' && Number.isInteger(stars) && stars >= 1 && stars <= STARS))
+            errors.push(choice ? `reactions[${i}].stars: 1 to ${STARS}` : `reactions[${i}].stars: only on a choice card`)
         const key = `${String(r.view)}/${String(tile ?? '')}`
         if (seen.has(key)) errors.push(`reactions[${i}]: a second reaction on the same view or tile`)
         seen.add(key)
         const comment = typeof r.comment === 'string' ? r.comment.trim() : ''
-        if (r.status === undefined && comment === '') continue
-        out.push({ view: r.view as number, ...(typeof tile === 'number' ? { tile } : {}), ...(r.status !== undefined ? { status: r.status as ReviewStatus } : {}), comment })
+        if (r.status === undefined && comment === '' && stars === undefined) continue
+        out.push({
+            view: r.view as number,
+            ...(typeof tile === 'number' ? { tile } : {}),
+            ...(r.status !== undefined ? { status: r.status as ReviewStatus } : {}),
+            comment,
+            ...(typeof stars === 'number' ? { stars } : {}),
+        })
     }
     return out
 }

package/src/review/project.ts

@@ -2,12 +2,12 @@
 // walked dirs' times and its text, imported, its spec bound to the store; its sources pulled, its kinds' facts and data
 // view computed on the server, so the hub never bundles project code
 import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { isAbsolute, join, relative, resolve } from 'node:path'
 import { importFresh, repoUnitFiles } from '../core/discover-checks.ts'
 import { LAYOUT } from '../core/layout.ts'
 import type { ReviewItem } from './model.ts'
 import { bindSpec, readAll, storeDir } from './store.ts'
-import { specOfUnit, type Fact, type Link, type ReviewUnit, type ViewText } from './unit.ts'
+import { specOfUnit, type Fact, type Link, type ReviewUnit, type ViewPart, type ViewText } from './unit.ts'
 
 /** the walk's answer kept in the cache: the unit files and every dir it read, each with its time; a dir whose time moved
  *  means a file came or went, so the walk runs again */
@@ -90,7 +90,12 @@ export function factLines(unit: ReviewUnit | null, x: ReviewItem): string[] {
 }
 
 /** a kind's data view of one item, what the hub draws: its facts, links, live url and text; a function that throws says so as a fact */
-export function viewOfItem(unit: ReviewUnit | null, x: ReviewItem): { facts: Fact[]; links: Link[]; live: string | null; text: ViewText | null } {
+/** a part as the page reads it: its media a file of the item's `part-<n>` route, with its kind */
+export type PartData = Omit<ViewPart, 'media'> & { media?: 'image' | 'video' }
+
+const VIDEO = /\.(mp4|webm|mov|m4v)$/i
+
+export function viewOfItem(unit: ReviewUnit | null, x: ReviewItem): { facts: Fact[]; links: Link[]; live: string | null; text: ViewText | null; parts: PartData[] } {
     const k = unit?.kinds?.[x.item.subject.kind]
     const tryOr = <T>(what: string, f: (() => T) | undefined, none: T, errors: Fact[]): T => {
         try {
@@ -106,5 +111,16 @@ export function viewOfItem(unit: ReviewUnit | null, x: ReviewItem): { facts: Fac
     const links = tryOr('links', k?.links && (() => k.links?.(x) ?? []), [] as Link[], errors)
     const live = tryOr<string | null>('live', k?.live && (() => k.live?.(x) ?? null), null, errors)
     const text = tryOr<ViewText | null>('text', k?.text && (() => k.text?.(x) ?? null), null, errors)
-    return { facts: [...facts, ...source, ...errors], links, live, text }
+    const parts = tryOr('parts', k?.parts && (() => k.parts?.(x) ?? []), [] as ViewPart[], errors).map(({ media, ...p }): PartData => (media ? { ...p, media: VIDEO.test(media) ? 'video' : 'image' } : p))
+    return { facts: [...facts, ...source, ...errors], links, live, text, parts }
+}
+
+/** the repo file of part `n` of item `x`'s subject, inside the repo; null when the part names none or it is not there */
+export function partFile(root: string, unit: ReviewUnit | null, x: ReviewItem, n: number): string | null {
+    const media = unit?.kinds?.[x.item.subject.kind]?.parts?.(x)[n]?.media
+    if (!media) return null
+    const abs = resolve(root, media)
+    const rel = relative(root, abs)
+    if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) return null
+    return existsSync(abs) ? abs : null
 }

package/src/review/routes.ts

@@ -8,7 +8,7 @@ import { isAnimFormat, isAnimLabels, isAnimMode, pairAnimation } from './anim.ts
 import { startAuto } from './auto.ts'
 import { bad, KEEP, NO_STORE, ranged, TYPES } from './http.ts'
 import type { Rect, Subject } from './model.ts'
-import { openReview, viewOfItem } from './project.ts'
+import { openReview, partFile, viewOfItem } from './project.ts'
 import { roleOf } from './role.ts'
 import { addMessage, imageFile, markRead, raiseItem, rateSubject, readAllCached, readItem, specOf, storeDir, storeStamp, threadImage, writeVerdict } from './store.ts'
 import { trailerRoutes } from './trailer-routes.ts'
@@ -196,6 +196,17 @@ async function reviewRoute(req: Request, path: string, dir: string, unit: Review
             return bad(e)
         }
     }
+    // a part's media (a draft's clip beside its text): the file the unit names for that part, never a path the page sends
+    const part = /^part-(\d+)$/.exec(name)
+    if (part) {
+        try {
+            const x = readItem(dir, id)
+            const f = x ? partFile(join(dir, '..', '..'), unit, x, Number(part[1])) : null
+            return f ? ranged(req, f) : bad(`no media for part ${part[1]} of ${id}`, 404)
+        } catch (e) {
+            return bad(e)
+        }
+    }
     if (name === 'anim') {
         const q = new URL(req.url).searchParams
         const mode = q.get('mode') ?? 'fade'

package/src/review/store.ts

@@ -90,6 +90,8 @@ export interface ViewInput {
     after?: string
     /** a list of small images shown as a wrapping grid, each with its label; never the first view */
     gallery?: { file: string; label: string }[]
+    /** a line on this view alone: an option's description on a choice card */
+    note?: string
 }
 
 export interface AddInput {
@@ -123,6 +125,8 @@ export interface AddInput {
     light?: 'review'
     /** a draft card on a live shot: its image a live frame, no verdict until it is ready */
     wip?: { live: string }
+    /** every view is an option he picks one of */
+    choice?: boolean
     now?: Date
 }
 
@@ -228,12 +232,13 @@ function soundLength(file: string): number {
 /** the waveform a sound view shows, one size for every sound so a pair reads side by side */
 const WAVE_SIZE = { w: 1600, h: 240 }
 
-/** view `n`'s waveforms, drawn into `folder` beside their place and renamed */
+/** view `n`'s waveforms, drawn into `folder` beside their place and renamed: each column's peak on a square root scale,
+ *  so a voice's quiet syllables show; drawn white on transparent, the page fills it with its own colour (a mask) */
 async function writeWaves(v: Loaded, n: number, folder: string): Promise<void> {
     if (!v.audio) return
     const draw = async (from: string, name: string): Promise<void> => {
         const to = join(folder, `${prefix(n)}${name}.png`)
-        await ffmpeg(['-i', from, '-filter_complex', `showwavespic=s=${WAVE_SIZE.w}x${WAVE_SIZE.h}:split_channels=0:colors=0x8fb3ff`, '-frames:v', '1', '-f', 'image2', '-c:v', 'png', `${to}.tmp`])
+        await ffmpeg(['-i', from, '-filter_complex', `showwavespic=s=${WAVE_SIZE.w}x${WAVE_SIZE.h}:split_channels=0:scale=sqrt:filter=peak:colors=white`, '-frames:v', '1', '-f', 'image2', '-c:v', 'png', `${to}.tmp`])
         renameSync(`${to}.tmp`, to)
     }
     await draw(v.audio.from, 'wave')
@@ -245,10 +250,10 @@ const prefix = (n: number): string => (n > 0 ? `v${n}-` : '')
 /** the file name of tile `k` of gallery view `n` */
 const tileName = (n: number, k: number, path: string): string => `v${n}-g${k}${extname(path).toLowerCase()}`
 
-function viewOf(v: Loaded, n: number, marks: readonly ReviewMark[] = []): ReviewView {
+function viewOf(v: Loaded, n: number, marks: readonly ReviewMark[] = [], note?: string): ReviewView {
     if (v.tiles) return { label: v.label, gallery: v.tiles.map((t, k): GalleryTile => ({ file: tileName(n, k, t.path), label: t.label, size: t.size })) }
     const audio = v.audio ? { audio: { duration: v.audio.duration, wave: `${prefix(n)}wave.png`, ...(v.audio.before ? { waveBefore: `${prefix(n)}before-wave.png` } : {}) } } : {}
-    return { label: v.label, files: filesOf(v, n), size: v.size, ...clipOf(v, n), ...audio, ...(marks.length > 0 ? { marks: [...marks] } : {}) }
+    return { label: v.label, files: filesOf(v, n), size: v.size, ...clipOf(v, n), ...audio, ...(marks.length > 0 ? { marks: [...marks] } : {}), ...(note?.trim() ? { note: note.trim() } : {}) }
 }
 
 /** the file names of view `n` in the folder: `image.png` on the first, `v2-before.png` on a later one */
@@ -295,6 +300,8 @@ export async function addItem(dir: string, input: AddInput): Promise<Item> {
     if (given.length === 0) throw new Error('give --image, --video or --audio, or --before and --after, or --view "<label>" <image>')
     for (const [i, v] of given.entries()) if (i > 0 && !v.label.trim()) throw new Error('--view: every view after the first needs its label')
     if (given[0]?.gallery) throw new Error('a gallery is never the first view: give the card an --image (or a pair, or a clip) first')
+    if (input.choice && given.length < 2) throw new Error('--choice: a choice has two options or more, one --view each')
+    for (const v of given) if (v.note !== undefined && v.gallery) throw new Error(`--view "${v.label}": a note goes on an image, a clip or a sound, never a gallery`)
     const loaded = await Promise.all(given.map((v, i) => loadView(v, i === 0 ? 'the first view' : `--view "${v.label}"`)))
     if (input.supersedes !== undefined && !existsSync(join(dir, input.supersedes, 'item.json'))) throw new Error(`--supersedes ${input.supersedes}: no such card in ${dir}`)
     if (input.supersedes !== undefined && readItem(dir, input.supersedes)?.item.origin.by !== 'agent')
@@ -347,13 +354,14 @@ export async function addItem(dir: string, input: AddInput): Promise<Item> {
         what: input.what.trim(),
         ...(topic ? { topic } : {}),
         ...(input.commit ? { commit: input.commit } : {}),
-        views: loaded.map((v, n) => viewOf(v, n, input.marks?.[n])),
+        views: loaded.map((v, n) => viewOf(v, n, input.marks?.[n], given[n]?.note)),
         ...(input.supersedes ? { supersedes: input.supersedes } : {}),
         ...(answers.length > 0 ? { answers } : {}),
         ...(input.fresh && input.why ? { why: input.why.trim() } : {}),
         ...(input.supersedes && input.keeps?.trim() ? { keeps: input.keeps.trim() } : {}),
         ...(input.light ? { light: input.light } : {}),
         ...(input.wip ? { wip: { live: input.wip.live, frame: 1 } } : {}),
+        ...(input.choice ? { choice: true as const } : {}),
     }
     const problems = itemProblems(item)
     if (problems.length > 0) throw new Error(problems.join('; '))
@@ -383,6 +391,7 @@ export async function addView(dir: string, id: string, v: ViewInput, o: { marks?
     const x = readItem(dir, id)
     if (!x) throw new Error(`no card ${id}`)
     if (verdictOf(x)) throw new Error(`${id} has his answer already: a new version passes --supersedes ${id}`)
+    if (v.note !== undefined && v.gallery) throw new Error(`"${v.label}": a note goes on an image, a clip or a sound, never a gallery`)
     if (!v.label.trim()) throw new Error('add-view: the view needs its label')
     const loaded = await loadView(v, `the view "${v.label}"`)
     const n = x.item.views.length
@@ -391,7 +400,7 @@ export async function addView(dir: string, id: string, v: ViewInput, o: { marks?
     copyFiles(loaded, n, folder)
     await writePoster(loaded, n, folder)
     await writeWaves(loaded, n, folder)
-    const item: Item = { ...x.item, views: [...x.item.views, viewOf(loaded, n, o.marks)], ...(x.item.light || o.light ? { light: 'review' as const } : {}) }
+    const item: Item = { ...x.item, views: [...x.item.views, viewOf(loaded, n, o.marks, v.note)], ...(x.item.light || o.light ? { light: 'review' as const } : {}) }
     writeJson(join(folder, 'item.json'), item)
     return item
 }

package/src/review/unit.ts

@@ -11,10 +11,26 @@ export interface Fact {
     value: string
 }
 
-/** a link the hub opens */
+/** a link the hub opens. `host`: a page of the tool that frames the hub (pkm-multi's admin), its url relative to it:
+ *  in a frame it is posted to the host (`{ shipkit: 'open', url }`), alone it opens in a new tab */
 export interface Link {
     label: string
     url: string
+    host?: boolean
+}
+
+/** how a part's change reads: new, changed, gone or the same */
+export type PartTone = 'new' | 'changed' | 'gone' | 'same'
+
+/** one part of a subject the hub draws as a card of its own: a message of a post, a page of a script. `icon` an image
+ *  url (a data url carries a logo), `media` a repo relative file the hub serves beside the text, `badge` its change */
+export interface ViewPart {
+    label: string
+    detail?: string
+    icon?: string
+    badge?: { text: string; tone: PartTone }
+    media?: string
+    text: ViewText
 }
 
 /** a text the hub shows, or a change of one shown as a diff */
@@ -30,6 +46,8 @@ export interface KindDef<S extends Subject = Subject> extends SpecKind {
     /** a url the hub opens in a frame: the subject live */
     live?(x: ReviewItem): string | null
     text?(x: ReviewItem): ViewText | null
+    /** the subject in parts, each a card: a post's messages, with their logo, media and change */
+    parts?(x: ReviewItem): ViewPart[]
     /** the `sk review add` flags this kind reads, each with its help line: `--where <zone>:<x>,<y>` */
     flags?: Record<string, string>
     /** the subject (and its topic) a card of this kind gets from those flags, every flag as the list of its values;

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

@@ -16,7 +16,7 @@ export class AdminSvc {
     /** the colours the preview keeps while a picker moves, so a drag draws a
      *  few icons, not one per frame; null follows the repo's colours */
     held: Identity | null = null
-    /** the repo has no png mark, or it would not draw: the app wears the default icon */
+    /** the repo has no mark, or it would not draw: the app wears the default icon */
     noIcon = false
     private rest: ReturnType<typeof setTimeout> | null = null
 

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

@@ -27,7 +27,7 @@ const IdentityBox = observer(({ app }: { app: RepoSt }) => {
             <div className="adicon">
                 <img src={a.previewSrc} alt={`${name} app icon`} width={128} height={128} hidden={a.noIcon}
                     onLoad={() => a.previewLoaded()} onError={() => a.previewFailed()} />
-                {a.noIcon ? <span className="dim">no png mark (.shipkit/identity/icon.png, public/logo.png or public/favicon.png): its app wears the default icon</span> : null}
+                {a.noIcon ? <span className="dim">no mark (.shipkit/identity/icon.png or icon.svg, public/logo.png or public/favicon.png): its app wears the default icon</span> : null}
             </div>
             <div className="adtext">
                 <b>identity</b>

package/src/serve/hub-app/hash-route.ts

@@ -36,7 +36,7 @@ export type HashSel =
     /** the checks one owner ships: shipkit's, or the repo's own */
     | { t: 'checks'; from: CheckOwner }
     /** the review cards, `id` the open one, null for the first the list shows */
-    | { t: 'review'; id: string | null }
+    | { t: 'review'; id: string | null; q?: string }
     /** a trailer's cuts, played with their notes: a trailer folder and one of its cuts, null for the first; the note
      *  open on it, and the notes filter when it is not the page's default (all) */
     | { t: 'trailer'; trailer: string | null; cut: string | null; note?: string | null; filter?: 'open' | 'all' | null }
@@ -55,6 +55,8 @@ export type ParsedHash = {
     /** a trailer address only: the note open, the notes filter */
     note?: string
     filter?: 'open' | 'all'
+    /** a review address only: its view and list filters, as `view=1&subject=place` */
+    q?: string
 }
 
 const ITEM = 'item:'
@@ -91,7 +93,8 @@ export function hashFor(sel: HashSel | null): string | null {
         case 'git': return GIT
         case 'when': return WHEN
         case 'checks': return `${CHECKS}${sel.from}`
-        case 'review': return sel.id == null ? REVIEW : `${REVIEW}:${sel.id}`
+        // page:review:<id>?view=1&subject=place, the query only when it says something
+        case 'review': return `${sel.id == null ? REVIEW : `${REVIEW}:${sel.id}`}${sel.q ? `?${sel.q}` : ''}`
         case 'trailer': {
             // page:trailer:<trailer>/<cut>/<note>?filter=all, each part only when it says something
             const note = sel.trailer != null && sel.note ? `/${sel.cut ?? ''}/${sel.note}` : sel.cut == null ? '' : `/${sel.cut}`
@@ -111,7 +114,12 @@ export function parseHash(raw: string): ParsedHash {
     if (raw === PLAN) return { kind: 'plan', col: null, id: '', tools: null }
     if (raw === GIT) return { kind: 'git', col: null, id: '', tools: null }
     if (raw === WHEN) return { kind: 'when', col: null, id: '', tools: null }
-    if (raw === REVIEW || raw.startsWith(`${REVIEW}:`)) return { kind: 'review', col: null, id: raw.slice(REVIEW.length + 1), tools: null }
+    if (raw === REVIEW || raw.startsWith(`${REVIEW}:`) || raw.startsWith(`${REVIEW}?`)) {
+        const qi = raw.indexOf('?')
+        const path = qi === -1 ? raw : raw.slice(0, qi)
+        const q = qi === -1 ? '' : raw.slice(qi + 1)
+        return { kind: 'review', col: null, id: path.slice(REVIEW.length + 1), tools: null, ...(q ? { q } : {}) }
+    }
     // the trailer folder rides in `col`, its cut in `id`
     if (raw === TRAILER || raw.startsWith(`${TRAILER}:`) || raw.startsWith(`${TRAILER}?`)) {
         const qi = raw.indexOf('?')
@@ -173,7 +181,7 @@ export function selOf(p: ParsedHash): HashSel | null {
         case 'git': return { t: 'git' }
         case 'when': return { t: 'when' }
         case 'checks': return { t: 'checks', from: p.id as CheckOwner }
-        case 'review': return { t: 'review', id: p.id === '' ? null : p.id }
+        case 'review': return { t: 'review', id: p.id === '' ? null : p.id, ...(p.q ? { q: p.q } : {}) }
         case 'trailer': return { t: 'trailer', trailer: p.col, cut: p.id === '' ? null : p.id, ...(p.note ? { note: p.note } : {}), ...(p.filter ? { filter: p.filter } : {}) }
     }
 }

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

@@ -159,9 +159,15 @@ export class HomeSt {
         return r
     }
 
+    /** the page is the embed page: one repo's page in another tool's frame (embed.ts) */
+    get embedded(): boolean {
+        return this.base !== undefined
+    }
+
     boot(): void {
         this.machine?.boot()
-        this.dock.boot()
+        // the embed page shows one repo's page alone: no dock, so no request for the house's runs
+        if (this.base === undefined) this.dock.boot()
         this.disposers.push(reaction(() => this.title, (t) => { document.title = t }, { fireImmediately: true }))
         // back, forward, a pasted link and a hand edited hash all arrive
         // here; fromUrl is idempotent, so the two events firing together

package/src/serve/hub-app/hub.css

@@ -20,6 +20,8 @@
  --k1:#8ca8c7;--k2:#a892c9;--k3:#6fb0b8;--k4:#c792b4;--k5:#9198a1;--k6:#8f95cf;
  /* the review section's own hue: the one row of the tree meant to be seen first */
  --review:#e879d4;
+ /* a wiki page's refs (wikis-view.tsx): read on demand, loaded with the page */
+ --ref-lazy:#e8984a;--ref-eager:#6fa8f0;
  --wash:rgba(107,143,179,.15);--wash2:rgba(107,143,179,.11);--hair:rgba(107,143,179,.5);
  --errbg:#2a1a1a;--errline:#4a2c2c;--errink:#e3bebe;
  /* a running thing's wash, the green twin of errbg and errline */
@@ -39,6 +41,7 @@
  --ground:#e3ede6;--groundline:#c6d6cb;--tag:#eef2f6;
  --k1:#3f6690;--k2:#7055a3;--k3:#2b7c86;--k4:#a34e80;--k5:#5d646d;--k6:#4f56a8;
  --review:#c0279d;
+ --ref-lazy:#b8600c;--ref-eager:#1f5fc8;
  --wash:rgba(59,104,150,.12);--wash2:rgba(59,104,150,.08);--hair:rgba(59,104,150,.45);
  --errbg:#fbe9e8;--errline:#efc4c2;--errink:#8a2520;
  --okbg:#e6f3eb;--okline:#9ccdaf}
@@ -271,7 +274,8 @@ kbd{background:var(--panel2);border:1px solid var(--line);border-radius:4px;padd
  background:conic-gradient(var(--chk1) 90deg,var(--chk2) 0 180deg,var(--chk1) 0 270deg,var(--chk2) 0) 0/34px 34px}
 .stage img.roll{max-width:100%;max-height:100%;object-fit:contain;filter:drop-shadow(0 6px 20px var(--shadow));z-index:5;position:relative}
 .stage .ph,.stagewrap .ph{color:var(--dim)}
-.stagewrap{flex:1;min-height:0;overflow-y:auto;display:flex;align-items:flex-start;justify-content:center;padding:var(--s4)}
+/* every page card of a repo sits in this column, read from the left, never centred */
+.stagewrap{flex:1;min-height:0;overflow-y:auto;display:flex;align-items:flex-start;justify-content:flex-start;padding:var(--s4)}
 .stageaud{display:flex;flex-direction:column;align-items:center;gap:var(--s3);font-size:48px;padding:var(--s4)}
 .stageaud audio{width:min(480px,80vw)}
 
@@ -703,6 +707,39 @@ a.tok{color:var(--accent)}
 .gvframe{flex:1;min-height:0;position:relative;display:flex;border:1px solid var(--line);border-radius:3px;background:var(--bg)}
 .gvwait{position:absolute;inset:0;display:flex;align-items:center;justify-content:center;gap:var(--s2);font-size:12px;color:var(--dim)}
 .graphview iframe{position:relative;flex:1;min-height:0;width:100%;border:0;background:transparent}
+/* the graph and its preview panel (wikis-view.tsx) */
+.gvbody{flex:1;min-height:0}
+.gvbody .gvframe{height:100%}
+/* the wiki's search bar, its hits dropped under it over the graph */
+.wsearch{position:relative;flex:0 1 360px;min-width:160px;display:flex}
+.wsearch input{flex:1;min-width:0;height:22px;background:var(--bg);color:var(--ink);border:1px solid var(--line);border-radius:999px;padding:0 var(--s3);font:inherit;font-size:12px}
+.wsearch input:focus{outline:none;border-color:var(--accent)}
+.wslist{position:absolute;top:calc(100% + 4px);left:0;z-index:30;width:min(560px,80vw);max-height:60vh;overflow-y:auto;padding:var(--s1) 0;background:var(--panel);border:1px solid var(--line);border-radius:6px;box-shadow:0 6px 20px var(--shadow)}
+.wshit{padding:var(--s1) var(--s3);cursor:pointer}
+.wshit.on,.wshit:hover{background:var(--sel)}
+.wshead{display:flex;align-items:baseline;gap:var(--s2);min-width:0}
+.wshead b{flex:none;font-size:12.5px}
+.wspath{min-width:0;color:var(--dim);font:11px/1.4 ui-monospace,Menlo,monospace;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.wssnip{color:var(--dim);font-size:11.5px;line-height:1.4;display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden}
+.wsnone{padding:var(--s1) var(--s3);color:var(--dim);font-size:12px}
+/* the page open beside the graph */
+.wprev{height:100%;display:flex;flex-direction:column;min-width:0;background:var(--panel);border:1px solid var(--line);border-radius:3px}
+.wphead{flex:none;display:flex;align-items:center;gap:var(--s2);padding:var(--s2) var(--s3);border-bottom:1px solid var(--line);min-width:0}
+.wptitle{flex:0 1 auto;min-width:0;font-size:13px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.wphead .wspath{flex:1}
+.wpplace{flex:none}
+.wpplace button{padding:0 var(--s1)}
+.wpplace .hico{width:14px;height:14px}
+.wpbtn{flex:none;display:inline-flex;align-items:center;gap:var(--s1);height:22px;padding:0 var(--s2);border:1px solid var(--line);border-radius:999px;color:var(--dim);font-size:11.5px;text-decoration:none;background:transparent;cursor:pointer}
+.wpbtn:hover{color:var(--ink);border-color:var(--accent)}
+.wpbtn .hico{width:13px;height:13px}
+.wpclose{flex:none;padding:0 var(--s2);font-size:14px;line-height:1.2}
+/* the refs of a page: on demand (→, a link, a path) orange, loaded with it (@) blue and bold */
+.wpbody a[data-ref=lazy]{color:var(--ref-lazy)}
+.wpbody a[data-ref=lazy] code{color:var(--ref-lazy)}
+.wpbody a[data-ref=eager]{color:var(--ref-eager);font-weight:700}
+.wpbody{flex:1;min-height:0;overflow-y:auto;padding:var(--s2) var(--s4) var(--s4)}
+.wpbody a[data-wiki]{text-decoration:underline;text-decoration-style:dotted;text-underline-offset:2px;cursor:pointer}
 
 /* ── comfy item view (comfy-ts's own panel fills the stage) ── */
 .comfyview{flex:1;min-height:0;display:flex;flex-direction:column;gap:var(--s2);padding:var(--s3) var(--s4) var(--s4)}

package/src/serve/hub-app/icons.tsx

@@ -44,6 +44,12 @@ export const ICON = {
     sun: 'M10 6.5a3.5 3.5 0 1 0 .01 0M10 2v2M10 16v2M2 10h2M16 10h2M4.3 4.3l1.4 1.4M14.3 14.3l1.4 1.4M4.3 15.7l1.4-1.4M14.3 5.7l1.4-1.4',
     moon: 'M15.5 12.5A6.5 6.5 0 0 1 7.5 4.5a6.5 6.5 0 1 0 8 8z',
     auto: 'M10 3a7 7 0 1 0 .01 0M10 3v14M10 5.5h4M10 8.5h6M10 11.5h6M10 14.5h4',
+    // where the wiki preview sits: a frame with its panel's edge
+    paneLeft: 'M3 4h14v12H3zM8 4v12M4.5 7h2M4.5 9.5h2',
+    paneRight: 'M3 4h14v12H3zM12 4v12M13.5 7h2M13.5 9.5h2',
+    paneBottom: 'M3 4h14v12H3zM3 11h14M6 13.5h8',
+    copy: 'M7 7h9v10H7zM4 13V3h9',
+    editor: 'M13 3l4 3v8l-4 3-7-6 7-5zM3 7.5l3 2.5-3 2.5',
     // the project list's fold: a panel with its rail marked
     rail: 'M3 4h14v12H3zM7.5 4v12',
     // a process's own switches on the overview

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

@@ -16,10 +16,10 @@ export const LIST: Bounds = { key: 'hub:list-width', min: 140, max: 360, def: 20
 export const SIDEBAR: Bounds = { key: 'hub:sidebar-width', min: 150, max: 640, def: 330 }
 
 /** the rail's icon sizes, in px: the foot's button cycles them */
-export const RAIL_ICONS = { s: 18, m: 24, l: 32 } as const
+export const RAIL_ICONS = { s: 24, m: 32, l: 40 } as const
 export type RailIcon = keyof typeof RAIL_ICONS
 /** the rail is its icon and this much on each side */
-const RAIL_PAD = 13
+const RAIL_PAD = 6
 /** the project list folded: its icons only, a row's name in its hover card */
 export const railPx = (size: RailIcon): number => RAIL_ICONS[size] + 2 * RAIL_PAD
 const RAIL_KEY = 'hub:list-rail'

package/src/serve/hub-app/md.ts

@@ -70,3 +70,35 @@ export const renderReadme = (src: string, fileUrl: (rel: string) => string): str
         },
         exclusiveFilter: (frame) => frame.tag === 'img' && (frame.attribs.src ?? '') === '',
     })
+
+/** a wiki page in the wikis page's preview: the card allowlist, and every ref
+ *  the server resolved (`links`, token → node, graph-pages.ts) as an anchor
+ *  that opens that page in place instead of a new tab, marked by its kind so
+ *  the sheet tells them apart: `@` loads with the page (eager), `→`, a link or
+ *  a path in a code span is read on demand (lazy, written `→ path` here
+ *  whatever the page wrote) */
+export const renderWikiPage = (src: string, links: Record<string, string>): string => {
+    const to = (t: string, eager = false): string | null => (links[t] == null ? null : `#wiki${eager ? '-eager' : ''}:${encodeURIComponent(links[t]!)}`)
+    // fences stay as written: a ref in a code block is an example, not a link
+    const linked = src.split(/(^```[\s\S]*?^```\s*$)/m).map((part, i) => i % 2 === 1 ? part : part
+        .replace(/\]\(([^)\s:]+\.md)\)/g, (m, t: string) => (to(t) == null ? m : `](${to(t)})`))
+        .replace(/→(\s*)([\w][\w./-]*\.md)\b/g, (m, sp: string, t: string) => (to(t) == null ? m : `→${sp}[${t}](${to(t)})`))
+        .replace(/(^|[\s(])@((?:\.{1,2}\/)*[\w][\w./-]*\.md)/gm, (m, pre: string, t: string) => (to(t, true) == null ? m : `${pre}[@${t}](${to(t, true)})`))
+        // a code span that is exactly a page's path: a lazy ref, its arrow added unless the page wrote one
+        .replace(/(→\s*)?(?<!\[)`([\w.][\w./-]*\.md)`/g, (m, arrow: string | undefined, t: string) => (to(t) == null ? m : `${arrow ?? '→ '}[\`${t}\`](${to(t)})`)),
+    ).join('')
+    return sanitizeHtml(marked.parse(linked) as string, {
+        allowedTags: [...CARD_TAGS, 'h5', 'h6', 'del'],
+        allowedAttributes: { a: ['href', 'target', 'rel', 'data-wiki', 'data-ref'] },
+        allowedSchemes: ['http', 'https'],
+        allowProtocolRelative: false,
+        transformTags: {
+            a: (tagName, attribs): sanitizeHtml.Tag => {
+                const href = attribs.href ?? ''
+                const ref = /^#wiki(-eager)?:(.*)$/.exec(href)
+                if (ref != null) return { tagName, attribs: { href, 'data-wiki': decodeURIComponent(ref[2]!), 'data-ref': ref[1] != null ? 'eager' : 'lazy' } }
+                return { tagName, attribs: { ...attribs, target: '_blank', rel: 'noreferrer' } }
+            },
+        },
+    })
+}

package/src/serve/hub-app/project-list.css

@@ -69,8 +69,8 @@
 .pgi.h5{--c:var(--k5)}
 .pgi.h6{--c:var(--k6)}
 /* the row says three things and no more (projects-svc faceOf) */
-/* closed in VS Code: the icon and the name dim, the badge does not */
-.pjrow.dim img,.pjrow.dim .pgi,.pjrow.dim .pjname{opacity:.5}
+/* closed in VS Code: the name dims, never the icon (the icon is how a repo is found, and the rail has no name) */
+.pjrow.dim .pjname{opacity:.5}
 /* ⌘1 to ⌘9 select the first nine rows (keys.ts): the hint sits at the row's end */
 .pjkey{flex:none;font:10px/1 ui-monospace,Menlo,monospace;color:var(--dim);opacity:.6;background:none;border:0;padding:0}
 .pjrow:hover .pjkey,.pjrow.cur .pjkey,.pjpl:hover .pjkey,.pjpl.cur .pjkey{opacity:1}
@@ -128,12 +128,14 @@
 .pjlist.rail .pjname,.pjlist.rail .pjkey,.pjlist.rail .pjstep,.pjlist.rail .pgsortl,.pjlist.rail .pjarow span,.pjlist.rail .pgerr{display:none}
 .pjlist.rail .pjrow,.pjlist.rail .pjpl,.pjlist.rail .pjarow{justify-content:center;padding:0}
 /* the rail's icon size (layout-st RAIL_ICONS, the foot's S M L button): the repo icons and the row under them grow */
-.pjlist.rail .pjrow{height:calc(var(--ri,18px) + 10px)}
-.pjlist.rail .pjrow img,.pjlist.rail .pjrow .pgi{width:var(--ri,18px);height:var(--ri,18px)}
-.pjlist.rail .pjrow .pgi{font-size:calc(var(--ri,18px) * .55)}
+.pjlist.rail .pjrow{height:calc(var(--ri,24px) + 6px)}
+.pjlist.rail .pjrow img,.pjlist.rail .pjrow .pgi{width:var(--ri,24px);height:var(--ri,24px);border-radius:6px}
+.pjlist.rail .pjrow .pgi{font-size:calc(var(--ri,24px) * .5)}
+/* the app icon is a rounded plate already (core/app-icon.ts) */
+.pjlist.rail .pjrow img.pjapp{border-radius:0}
 .pjsize{font:600 10px/1 ui-monospace,Menlo,monospace}
-.pjlist.rail .pga{position:absolute;top:var(--s0);left:50%;margin-left:var(--s1);min-width:14px;height:14px;padding:0 var(--s0);border-radius:7px;font-size:9px;line-height:14px}
-.pjlist.rail .pgd,.pjlist.rail .pgw{position:absolute;bottom:var(--s1);left:50%;margin-left:var(--s1)}
+.pjlist.rail .pga{position:absolute;top:0;right:calc(50% - var(--ri,24px) / 2 - 4px);min-width:14px;height:14px;padding:0 var(--s0);border-radius:7px;font-size:9px;line-height:14px}
+.pjlist.rail .pgd,.pjlist.rail .pgw{position:absolute;bottom:var(--s0);right:calc(50% - var(--ri,24px) / 2 - 2px)}
 .pjlist.rail .pjfoot{flex-direction:column;height:auto;padding:var(--s1) 0}
 .pjlist.rail .pjfoot button{justify-content:center;width:28px;padding:0}
 .pjlist.rail .pjarbtn span{display:none}