rvlib-shipkit 2.1.1 → 2.3.0

package/src/scaffold/cli-skeleton.ts

@@ -0,0 +1,149 @@
+// the project CLI a started repo gets on day one: `src/cli.ts` on the kit
+// (cli/kit/), named for the project, one example family, and the package.json
+// `cli` script plus a `bin` of the project's name. Pure text here; the scaffold
+// writes it create-only, so a repo that already has any of it keeps its own.
+import { Cli } from 'clipanion'
+import { commandRows, type Definition, newCommandsPage, renderEssentials, renderMarkdown, spliceBlock } from '../cli/cmd_Commands.ts'
+import { builtinCommands } from '../cli/kit/builtins.ts'
+import { type Verb, verbs } from '../cli/kit/verb.ts'
+
+/** the entry: the family table and nothing else. `absolute`: the repo's
+ *  tsconfig maps `src/*`, the house import form; else a relative import */
+export function cliEntry(name: string, absolute = true): string {
+    return `#!/usr/bin/env bun
+// ${name}: the project CLI, one command for every act an agent or a human does in this repo.
+// A family is src/cli/cmd_<Family>.ts exporting \`commands\`; the table names the first words
+// each family owns, so a call loads its family alone. \`${name}\` lists every command.
+import { resolve } from 'path'
+import { runProjectCli } from 'rvlib-shipkit/cli-kit'
+
+await runProjectCli({
+    name: '${name}',
+    root: resolve(import.meta.dir, '..'),
+    families: [
+        { roots: ['dev', 'shot'], load: () => import('${absolute ? 'src/cli/cmd_Dev.ts' : './cli/cmd_Dev.ts'}') },
+    ],
+})
+`
+}
+
+/** the example family's live row, as data: the source text and the day-one
+ *  pages are both made from it, so they cannot disagree */
+export function exampleRow(name: string, devScript = false): Verb {
+    return {
+        path: 'dev',
+        category: 'Run',
+        description: devScript ? 'the dev process (package.json dev)' : 'the dev process: src/index.ts, restarted on save',
+        examples: [['start it', `${name} dev`]],
+        run: devScript ? { cmd: ['bun', 'run', 'dev'] } : { cmd: ['bun', '--watch', 'src/index.ts'] },
+        essential: {},
+    }
+}
+
+const q = (s: string): string => `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`
+
+/** the example family: a row over code that exists, and the shot row a visual
+ *  project uncomments once it has a renderer */
+export function exampleFamily(name: string, devScript = false): string {
+    const v = exampleRow(name, devScript)
+    const run = 'cmd' in v.run ? `{ cmd: [${v.run.cmd.map(q).join(', ')}] }` : ''
+    return `// a command over code that exists is a row: run is { bun: <script> }, { cmd: [...] }
+// or { tool, cold } (a warm host, else the cold script). Mark an everyday row
+// \`essential: {}\`. \`sk ci\` rewrites the agent pages (cli-pages.check.shipkit.ts), or: ${pagesCommand(name)}
+import { verbs } from 'rvlib-shipkit/cli-kit'
+
+export const commands = verbs([
+    {
+        path: ${q(v.path)},
+        category: ${q(v.category)},
+        description: ${q(v.description)},
+        examples: [[${v.examples[0]!.map(q).join(', ')}]],
+        run: ${run},
+        essential: {},
+    },
+    // a visual project: any state as a png, the same command filmed by a trailer line.
+    // film: 'still' means the script takes --out <path>; 'clip' also takes --seconds <n>.
+    // {
+    //     path: 'shot',
+    //     category: 'Look',
+    //     description: 'any state of the app as a png',
+    //     examples: [['the home screen', '${name} shot home --out shot.png']],
+    //     run: { bun: 'scripts/shot.ts' },
+    //     film: 'still',
+    // },
+])
+`
+}
+
+/** where a project CLI's two agent pages live */
+export const cliPages = (name: string): { all: string; essentials: string } => ({ all: `agent/${name}.md`, essentials: `agent/${name}-essentials.md` })
+
+/** the command that writes both pages */
+export const pagesCommand = (name: string): string => `${name} commands --out ${cliPages(name).all} --essentials ${cliPages(name).essentials}`
+
+/** the day-one pages, exactly as \`<name> commands --out … --essentials …\` writes them */
+export function skeletonPages(name: string, devScript = false): { all: string; essentials: string } {
+    const cli = new Cli({ binaryName: name })
+    const builtins = builtinCommands(name)
+    const classes = [...verbs([exampleRow(name, devScript)]), ...builtins.docs, ...builtins.calls]
+    for (const c of classes) cli.register(c)
+    const defs = cli.definitions() as Definition[]
+    const rows = commandRows(defs, (cli.definitions as (o?: { detailed?: boolean }) => Definition[])({ detailed: true }), name, classes)
+    return {
+        all: spliceBlock(newCommandsPage(name, cliPages(name).all), renderMarkdown(rows, name), name)!,
+        essentials: renderEssentials(rows, name, pagesCommand(name)),
+    }
+}
+
+/** the package.json keys the project CLI needs, only where the key is free.
+ *  Returns the keys it filled */
+export function addCliKeys(pkg: { scripts?: Record<string, string>; bin?: Record<string, string> | string }, name: string): string[] {
+    const filled: string[] = []
+    pkg.scripts ??= {}
+    if (pkg.scripts.cli == null) { pkg.scripts.cli = 'bun src/cli.ts'; filled.push('scripts.cli') }
+    if (pkg.bin == null) { pkg.bin = { [name]: './src/cli.ts' }; filled.push(`bin.${name}`) }
+    return filled
+}
+
+/** what says a repo already has a CLI, its own or its product's: a `cli`
+ *  script, any `bin`, any script that runs a cli.ts or cli.js of the repo, a
+ *  src/cli.ts or a src/cli/ folder. null = the skeleton has room */
+export function existingCli(pkg: { scripts?: Record<string, string>; bin?: unknown } | null, files: { entry: boolean; cliDir: boolean }): string | null {
+    if (pkg?.scripts?.cli != null) return `package.json scripts.cli runs \`${pkg.scripts.cli}\``
+    if (pkg?.bin != null) return `package.json has a bin (${typeof pkg.bin === 'string' ? pkg.bin : Object.keys(pkg.bin as object).join(', ')})`
+    // a script running an installed tool's cli (the house `hub` runs shipkit's) is not the repo's own
+    const runner = Object.entries(pkg?.scripts ?? {}).find(([, body]) => body.split(/\s+/).some((w) => /\bcli\.(ts|js)$/.test(w) && !/node_modules\/|rvlib-shipkit/.test(w)))
+    if (runner != null) return `package.json scripts.${runner[0]} runs \`${runner[1]}\``
+    if (files.entry) return 'src/cli.ts exists'
+    if (files.cliDir) return 'src/cli/ exists'
+    return null
+}
+
+/** whether an installed rvlib-shipkit carries the kit: null = none installed */
+export function kitInstalled(installedPkg: { exports?: Record<string, unknown> } | null): boolean | null {
+    if (installedPkg == null) return null
+    return installedPkg.exports?.['./cli-kit'] != null
+}
+
+/** the check file that keeps both agent pages equal to the registry: the gate
+ *  fails a stale page and its fix pass writes it again */
+export function pagesCheckFile(name: string): string {
+    return `// agent/${name}.md and agent/${name}-essentials.md list the ${name} commands as the registry has them.
+// A stale page sends an agent at a command that does not exist; the gate's fix pass writes both again
+import { check } from 'rvlib-shipkit/src/check.ts'
+import { cliPagesCheck } from 'rvlib-shipkit/src/cli/kit/pages-check.ts'
+
+const pages = cliPagesCheck('${name}')
+
+export default check({
+    description: pages.description,
+    blocking: true,
+    runs: { onPreCommit: false, onCi: true, onFull: true, onRelease: true, onHealth: true, onSave: 'moved', onClock: false },
+    cache: { by: 'files', inputs: pages.inputs, key: null },
+    fix: 'ci',
+    applies: 'always',
+    run: pages.run,
+    repair: pages.repair,
+})
+`
+}

package/src/scaffold/files/agent-index.md

@@ -12,14 +12,14 @@ BEFORE the change it describes.
 
 **Always loaded every session:**
 
-@coding.md
+@coding.md{{CLI_INCLUDE}}
 
 Read the matching page before touching a surface:
 
 | read when touching… | page |
 |---|---|
 | any source file | `agent/coding.md` |
-| recent changes and why | `agent/changelog.md` |
+| recent changes and why | `agent/changelog.md` |{{CLI_ROW}}
 
 Grow this table: a subsystem, a service, a runbook each earn their own page,
 cross-linked from here.

package/src/scaffold/files/tsconfig.json

@@ -23,6 +23,9 @@
          "scripts/*": ["./scripts/*"]
       },
 
+      // no @types package loads unless named here: bun's globals (Bun, import.meta.dir)
+      "types": ["bun"],
+
       // every file is a module even with no import/export (standalone scripts)
       "moduleDetection": "force",
 

package/src/scaffold/files/verify-skill.md

@@ -12,7 +12,7 @@ description: Prove a change in THIS project actually works — drive the real fl
 ## The rules (house-wide)
 - Failing repro test BEFORE the fix. Green checks ≠ verification.
 - Logic → fast headless bun tests, run through `sk ci --only test` (tiny ~10-line test files reusing fixtures). While you fix one bug, `bun run test:raw <test file>` is the narrow way in, and one test by name is `bun run test:raw -- -t "<name>"`.
-- Look & feel → NEVER screenshot-self-verify; the repo owner playtests it.
+- Look & feel → your own screenshot is a check before you report, never the verdict; the repo owner playtests it.
 - Verify as the end user would: drive the real flow, observe the real signal.
 
 ## This project

package/src/scaffold/project-scaffold.ts

@@ -13,6 +13,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { dirname, join } from 'path'
 import { defaultHubPort } from '../serve/hub-port.ts'
+import { addCliKeys, cliEntry, cliPages, exampleFamily, existingCli, kitInstalled, pagesCheckFile, skeletonPages } from './cli-skeleton.ts'
 
 const FILES = join(import.meta.dir, 'files')
 
@@ -33,6 +34,8 @@ export type ScaffoldOpts = {
      *  a caller that declares a house (start seeds include lines) turns them
      *  on, and the grant is printed the one time it lands */
     claudePolicy?: boolean
+    /** false: write no project CLI (the installed rvlib-shipkit predates the kit) */
+    projectCli?: boolean
 }
 
 /** every dep the house toolchain needs for the scripts below to run. The
@@ -110,16 +113,20 @@ export function scaffoldProject(root: string, opts: ScaffoldOpts): string[] {
     // agent index advertising a port nothing listens on, so the caller that
     // knows the name it is about to wire passes the port it resolves
     const port = opts.port ?? defaultHubPort(packageName(root) ?? opts.name)
-    const vars = {
-        NAME: opts.name,
-        PORT: String(port),
-        DATE: opts.today ?? new Date().toISOString().slice(0, 10),
-    }
     const written: string[] = []
     const skipped: string[] = []
     const write = (rel: string, body: string): void => { (put(root, rel, body) ? written : skipped).push(rel) }
 
     write('src/index.ts', 'export {}\n')
+    // the project CLI on the kit, unless the dir already carries one, and its
+    // essentials page loaded by the agent index
+    const cliKeys = opts.projectCli !== false && writeCli(root, opts.name, write, p)
+    const vars = {
+        NAME: opts.name,
+        PORT: String(port),
+        DATE: opts.today ?? new Date().toISOString().slice(0, 10),
+        ...cliIndexVars(opts.name, cliKeys),
+    }
     write('tsconfig.json', template('tsconfig.json', vars))
     write('bunfig.toml', template('bunfig.toml', vars))
     // settings.json only here: it turns eslint off and keeps tsserver from
@@ -128,7 +135,7 @@ export function scaffoldProject(root: string, opts: ScaffoldOpts): string[] {
     write('.claude/skills/verify/SKILL.md', template('verify-skill.md', vars))
     writeHouseFiles(write, vars, opts.claudePolicy === true, written, p)
 
-    addScripts(root, written, p)
+    addScripts(root, written, p, cliKeys ? opts.name : null)
     addIgnoreLines(root, written)
 
     if (written.length > 0) p(`ok: scaffolded ${written.length} file(s): ${written.slice(0, 6).join(', ')}${written.length > 6 ? `, +${written.length - 6} more` : ''}`)
@@ -166,9 +173,9 @@ function writeHouseFiles(write: (rel: string, body: string) => void, vars: Recor
  *  include lines pull it into the house contract, so it gets the house half
  *  of the day-one shape and nothing that says what the repo IS. Create-only,
  *  so every file the repo already holds wins. Returns the paths it wrote */
-export function adoptHouse(root: string, opts: { name: string; today?: string; print?: (line: string) => void }): string[] {
+export function adoptHouse(root: string, opts: { name: string; today?: string; print?: (line: string) => void; cli?: boolean }): string[] {
     const p = opts.print ?? console.log
-    const vars = { NAME: opts.name, PORT: String(defaultHubPort(opts.name)), DATE: opts.today ?? new Date().toISOString().slice(0, 10) }
+    const vars = { NAME: opts.name, PORT: String(defaultHubPort(opts.name)), DATE: opts.today ?? new Date().toISOString().slice(0, 10), ...cliIndexVars(opts.name, opts.cli === true) }
     const written: string[] = []
     writeHouseFiles((rel, body) => { if (put(root, rel, body)) written.push(rel) }, vars, true, written, p)
     if (written.length > 0) p(`ok: adopted into the house, ${written.length} file(s) seeded: ${written.join(', ')}`)
@@ -193,8 +200,78 @@ What broke, which page or lib, what you expected. Gitignored on purpose,
 transient by design: it is harvested, then deleted.
 `
 
-/** the baseline scripts, added only where the key is free */
-function addScripts(root: string, written: string[], p: (line: string) => void): void {
+/** the project CLI skeleton (cli-skeleton.ts): the entry, the example family,
+ *  and whether package.json still needs its `cli` and `bin` keys. A dir that
+ *  already has a project CLI keeps it alone */
+function writeCli(root: string, name: string, write: (rel: string, body: string) => void, p: (line: string) => void): boolean {
+    const pkg = readPackage(root)
+    const found = existingCli(pkg, cliFiles(root))
+    if (found != null) { p(`skip: project CLI, ${found}`); return false }
+    writeSkeleton(root, name, pkg?.scripts?.dev != null, write)
+    return true
+}
+
+const cliFiles = (root: string): { entry: boolean; cliDir: boolean } => ({ entry: existsSync(join(root, 'src/cli.ts')), cliDir: existsSync(join(root, 'src/cli')) })
+
+/** the skeleton's five files: the entry, the example family, its two pages
+ *  and the check that keeps them current. The entry imports its families
+ *  the house way when tsconfig maps src/, relatively otherwise */
+function writeSkeleton(root: string, name: string, devScript: boolean, write: (rel: string, body: string) => void): void {
+    const pages = skeletonPages(name, devScript)
+    let absolute = true
+    try { absolute = readFileSync(join(root, 'tsconfig.json'), 'utf8').includes('"src/*"') } catch { absolute = false }
+    write('src/cli.ts', cliEntry(name, absolute))
+    write('src/cli/cmd_Dev.ts', exampleFamily(name, devScript))
+    write('src/cli/cli-pages.check.shipkit.ts', pagesCheckFile(name))
+    write(cliPages(name).all, pages.all)
+    write(cliPages(name).essentials, pages.essentials)
+}
+
+/** the installed rvlib-shipkit's manifest, null when none is installed */
+export function installedLib(root: string): { version?: string; exports?: Record<string, unknown> } | null {
+    try { return JSON.parse(readFileSync(join(root, 'node_modules/rvlib-shipkit/package.json'), 'utf8')) as { version?: string; exports?: Record<string, unknown> } }
+    catch { return null }
+}
+
+/** the agent index lines that load the essentials page and list the full one */
+const cliIndexVars = (name: string, cli: boolean): { CLI_INCLUDE: string; CLI_ROW: string } => ({
+    CLI_INCLUDE: cli ? `\n@${name}-essentials.md` : '',
+    CLI_ROW: cli ? `\n| every command of the project CLI | \`${cliPages(name).all}\` |` : '',
+})
+
+/** an ADOPTED repo asking for the project CLI (`sk start <name> --cli`): the
+ *  skeleton and its package.json keys, refused when the repo already has a
+ *  CLI of its own, because a second one splits the one door. Returns the
+ *  paths it wrote, null on a refusal */
+export function adoptCli(root: string, opts: { name: string; print?: (line: string) => void }): string[] | null {
+    const p = opts.print ?? console.log
+    const pkg = readPackage(root)
+    if (pkg == null) { p(`FAIL: no readable package.json in ${root} — the project CLI needs one`); return null }
+    const found = existingCli(pkg, cliFiles(root))
+    if (found != null) { p(`skip: ${opts.name} already has a CLI (${found}) — extend it; a project CLI beside a product's bin is wired by hand (build/cli-tool.md)`); return null }
+    const lib = installedLib(root)
+    if (kitInstalled(lib) === false) { p(`skip: the installed rvlib-shipkit ${lib?.version ?? ''} predates the CLI kit — bun add -d rvlib-shipkit@latest once a release carries it, then re-run`); return null }
+    const written: string[] = []
+    const write = (rel: string, body: string): void => { if (put(root, rel, body)) written.push(rel) }
+    writeSkeleton(root, opts.name, pkg.scripts?.dev != null, write)
+    addScripts(root, written, p, opts.name, false)
+    const index = join(root, 'agent/index.md')
+    const include = `@${opts.name}-essentials.md`
+    if (existsSync(index) && !readFileSync(index, 'utf8').split('\n').includes(include)) p(`next: in agent/index.md, load the everyday commands with the line ${include} and list \`${cliPages(opts.name).all}\` in its table`)
+    const deps = { ...(pkg as { dependencies?: object }).dependencies, ...(pkg as { devDependencies?: object }).devDependencies }
+    p(`ok: project CLI written: ${written.join(', ')} — run \`bun run cli\``)
+    if (!('rvlib-shipkit' in deps)) p('next: bun add -d rvlib-shipkit   (the CLI imports rvlib-shipkit/cli-kit)')
+    return written
+}
+
+function readPackage(root: string): { name?: string; scripts?: Record<string, string> } | null {
+    try { return JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { name?: string; scripts?: Record<string, string> } }
+    catch { return null }
+}
+
+/** the baseline scripts, added only where the key is free, plus the project
+ *  CLI's `cli` and `bin` keys when the skeleton was written */
+function addScripts(root: string, written: string[], p: (line: string) => void, cliName: string | null = null, baseline = true): void {
     const path = join(root, 'package.json')
     if (!existsSync(path)) return void p('WARN no package.json here — the typecheck script was not written')
     const raw = readFileSync(path, 'utf8')
@@ -203,11 +280,12 @@ function addScripts(root: string, written: string[], p: (line: string) => void):
     catch (e) { return void p(`WARN package.json is unparseable (${String(e).slice(0, 80)}) — the typecheck script was not written, repair it then re-run`) }
     pkg.scripts ??= {}
     let added = 0
-    for (const [k, v] of Object.entries(SCRIPTS)) if (pkg.scripts[k] == null) { pkg.scripts[k] = v; added++ }
+    if (baseline) for (const [k, v] of Object.entries(SCRIPTS)) if (pkg.scripts[k] == null) { pkg.scripts[k] = v; added++ }
+    if (cliName != null) added += addCliKeys(pkg, cliName).length
     if (added === 0) return
     const indent = raw.match(/^(\s+)"/m)?.[1] ?? '  '
     writeFileSync(path, JSON.stringify(pkg, null, indent) + '\n')
-    written.push(`package.json (${added} script(s))`)
+    written.push(`package.json (${added} key(s))`)
 }
 
 function packageName(root: string): string | null {

package/src/serve/embed.ts

@@ -0,0 +1,35 @@
+// a repo's review or trailer page alone, for another tool to frame (wiki build/shipkit/review.md, The review page):
+// `<base>/embed/?page=review` serves the same app bundled with RELATIVE asset paths, so the page and every request it
+// makes work under any prefix a proxy puts in front of the hub (pkm-multi's admin frames it under its own origin). The
+// bundle is made once a process, in memory
+import { join } from 'node:path'
+
+const INDEX = join(import.meta.dir, 'hub-app', 'index.html')
+
+let bundle: Promise<Map<string, Blob>> | null = null
+
+async function build(): Promise<Map<string, Blob>> {
+    const r = await Bun.build({ entrypoints: [INDEX], publicPath: './', target: 'browser', minify: true })
+    if (!r.success) throw new Error(r.logs.map(String).join('\n'))
+    return new Map(r.outputs.map((o) => [o.path.split('/').pop() ?? o.path, o]))
+}
+
+/** the embed page and its assets under `<base>/embed/`; null for any other path */
+export async function embedRoute(path: string): Promise<Response | null> {
+    if (path === '/embed') return new Response(null, { status: 308, headers: { location: 'embed/' } })
+    if (!path.startsWith('/embed/')) return null
+    bundle ??= build().catch((e: Error) => {
+        bundle = null
+        throw e
+    })
+    let files: Map<string, Blob>
+    try {
+        files = await bundle
+    } catch (e) {
+        return new Response(`FAIL: the embed page does not build: ${(e as Error).message}`, { status: 500 })
+    }
+    const name = path.slice('/embed/'.length) || 'index.html'
+    const f = files.get(name)
+    if (!f) return new Response(`no ${name} in the embed page`, { status: 404 })
+    return new Response(f, { headers: { 'content-type': f.type || 'application/octet-stream', 'cache-control': name === 'index.html' ? 'no-cache' : 'private, max-age=86400' } })
+}

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

@@ -32,7 +32,7 @@ const RepoName = observer(({ app, name }: { app: HomeSt; name: string }) => {
 
 /** a bar of exclusive buttons */
 const Bar = <T extends number>({ label, values, value, words, set }: { label: string; values: readonly T[]; value: number; words: (v: T) => string; set: (v: T) => void }) => (
-    <div className="acwin" role="radiogroup" aria-label={label}>
+    <div className="seg" role="radiogroup" aria-label={label}>
         {values.map((v) => (
             <button key={v} role="radio" aria-checked={value === v} className={value === v ? 'on' : ''} onClick={() => set(v)}>{words(v)}</button>
         ))}

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

@@ -4,10 +4,6 @@
    on main, orange elsewhere; a commit orange until pushed; dirt red. */
 .activity{font-size:13px;container-type:inline-size}
 .actop{display:flex;align-items:center;flex-wrap:wrap;gap:var(--s3);margin-bottom:var(--s3)}
-.acwin{display:inline-flex;border:1px solid var(--line);border-radius:4px;overflow:hidden}
-.acwin button{border:0;border-radius:0;padding:var(--s0) var(--s2);background:none;color:var(--dim);font-size:12px}
-.acwin button:hover{color:var(--ink);background:var(--panel2)}
-.acwin button.on{color:var(--accent);background:var(--sel)}
 .accap{display:inline-flex;align-items:center;gap:var(--s1);font-size:12px}
 .accap input{width:44px;height:22px;box-sizing:border-box;background:var(--bg);color:var(--ink);border:1px solid var(--line);border-radius:4px;padding:var(--s0) var(--s1);font:inherit;font-variant-numeric:tabular-nums}
 .accap input:focus{outline:none;border-color:var(--accent)}

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

@@ -4,7 +4,8 @@
 // then the status as small pills that fold into +N rather than wrap. The
 // state is dock-st.ts; the height is the page's panel (hub-app.tsx).
 import { observer } from 'mobx-react-lite'
-import { useEffect, useState } from 'react'
+import { useEffect, useState, type CSSProperties } from 'react'
+import { idVars } from './projects-svc.ts'
 import { Tip } from './floating.tsx'
 import { Icon, ICON } from './icons.tsx'
 import type { HomeSt } from './home-st.ts'
@@ -57,8 +58,8 @@ const GroupLabel = observer(({ app, g }: { app: HomeSt; g: PlacedGroup }) => {
     return (
         <button className="dgroup" onClick={() => app.dock.openRepo(g.key)}
             title={`${g.key}: open the repo${g.hidden > 0 ? `\n${g.hidden} check run(s) did not fit in its lanes` : ''}`}>
-            {p?.icon != null ? <img src={p.icon} alt="" width={12} height={12} draggable={false} /> : <i className="dgico" style={{ background: id.colorDark }} />}
-            <span style={{ color: id.colorDark }}>{g.key}</span>
+            {p?.icon != null ? <img src={p.icon} alt="" width={12} height={12} draggable={false} /> : <i className="dgico idb" style={idVars(id) as CSSProperties} />}
+            <span className="idc" style={idVars(id) as CSSProperties}>{g.key}</span>
             {/* slim folds its lanes on purpose: the count is news only open */}
             {g.hidden > 0 && app.dock.size === 'open' ? <b>+{g.hidden}</b> : null}
         </button>
@@ -72,7 +73,7 @@ const PillFace = observer(({ app, p }: { app: HomeSt; p: DockPill }) => {
         <span className={`pchip ${p.tone}`}>
             {p.repo == null ? null : pj?.icon != null
                 ? <img src={pj.icon} alt="" width={12} height={12} draggable={false} />
-                : <i className="dgico" style={{ background: app.projects.identityOf(p.repo).colorDark }} />}
+                : <i className="dgico idb" style={idVars(app.projects.identityOf(p.repo)) as CSSProperties} />}
             {p.mark == null ? null : <b className={`pcmark ${p.markTone ?? 'dim'}`}>{p.mark}</b>}
             <span className="pctext">{p.text}</span>
             {p.age == null ? null : <span className="pcage">{p.age}</span>}

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

@@ -35,18 +35,26 @@ export type HashSel =
     | { t: 'when' }
     /** 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 }
+    /** 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 }
 
 /** whose a gate check is */
 export type CheckOwner = 'shipkit' | 'repo'
 
 export type ParsedHash = {
-    kind: 'asset' | 'cat' | 'col' | 'item' | 'status' | 'tests' | 'admin' | 'readme' | 'processes' | 'plan' | 'git' | 'when' | 'checks' | 'none'
+    kind: 'asset' | 'cat' | 'col' | 'item' | 'status' | 'tests' | 'admin' | 'readme' | 'processes' | 'plan' | 'git' | 'when' | 'checks' | 'review' | 'trailer' | 'none'
     /** the collection, for an item. null for everything else */
     col: string | null
     id: string
     /** the media tool set, when the address carried one. An empty array is a
      *  choice (every tool off), null is no statement at all */
     tools: string[] | null
+    /** a trailer address only: the note open, the notes filter */
+    note?: string
+    filter?: 'open' | 'all'
 }
 
 const ITEM = 'item:'
@@ -62,6 +70,8 @@ const PLAN = 'page:plan'
 const GIT = 'page:git'
 const WHEN = 'page:when'
 const CHECKS = 'page:checks:'
+const REVIEW = 'page:review'
+const TRAILER = 'page:trailer'
 
 /** what this selection puts in the url. null only for no selection at all,
  *  and then the hash is left alone rather than wiped */
@@ -81,6 +91,12 @@ 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}`
+        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}`
+            return `${sel.trailer == null ? TRAILER : `${TRAILER}:${sel.trailer}${note}`}${sel.filter ? `?filter=${sel.filter}` : ''}`
+        }
     }
 }
 
@@ -95,6 +111,15 @@ 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 }
+    // the trailer folder rides in `col`, its cut in `id`
+    if (raw === TRAILER || raw.startsWith(`${TRAILER}:`) || raw.startsWith(`${TRAILER}?`)) {
+        const qi = raw.indexOf('?')
+        const path = qi === -1 ? raw : raw.slice(0, qi)
+        const [trailer = '', cut = '', note = ''] = path.slice(TRAILER.length + 1).split('/')
+        const f = qi === -1 ? null : new URLSearchParams(raw.slice(qi + 1)).get('filter')
+        return { kind: 'trailer', col: trailer === '' ? null : trailer, id: cut, tools: null, ...(note ? { note } : {}), ...(f === 'open' || f === 'all' ? { filter: f } : {}) }
+    }
     if (raw === `${CHECKS}shipkit` || raw === `${CHECKS}repo`) return { kind: 'checks', col: null, id: raw.slice(CHECKS.length), tools: null }
     if (raw.startsWith(`${PROCESSES}:`)) {
         const id = raw.slice(PROCESSES.length + 1)
@@ -148,6 +173,8 @@ 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 '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/header-bar.tsx

@@ -14,6 +14,8 @@ import { Icon, ICON } from './icons.tsx'
 import { Pop, Tip } from './floating.tsx'
 import { FloatCards, type Card } from './float-cards.tsx'
 import type { RepoSt } from './repo-st.ts'
+import type { CSSProperties } from 'react'
+import { idVars } from './projects-svc.ts'
 
 /** the repo's hub has not answered on the home: its reason and its fix show
  *  instead of the page. A screen this browser kept shows meanwhile, until
@@ -113,7 +115,7 @@ export const RepoTools = observer(({ app }: { app: RepoSt }) => (
 export const HeaderBar = observer(({ app }: { app: RepoSt }) => (
     <>
         <header className="hdr">
-            <span className="hname" style={app.name === '' ? undefined : { color: app.home.projects.identityOf(app.name).colorDark }}>{app.name !== '' ? app.name : 'hub'}</span>
+            <span className={app.name === '' ? 'hname' : 'hname idc'} style={app.name === '' ? undefined : (idVars(app.home.projects.identityOf(app.name)) as CSSProperties)}>{app.name !== '' ? app.name : 'hub'}</span>
             <span className="sp" />
             <RepoTools app={app} />
             <RepoRun app={app} />

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

@@ -14,6 +14,7 @@ import { makeAutoObservable, observableShallow, reaction, type IReactionDisposer
 import { currentHash, hashFor } from './hash-route.ts'
 import { MachineSt, type MachineOpts } from './machine-st.ts'
 import { LayoutSt } from './layout-st.ts'
+import { ThemeSt } from './theme-st.ts'
 import { DockSt } from './dock-st.ts'
 import { PaletteSt } from './palette-st.ts'
 import { PlannedSt } from './planned-st.ts'
@@ -60,6 +61,8 @@ export const plainClick = (e: { button: number; metaKey: boolean; ctrlKey: boole
 export type HomeOpts = MachineOpts & {
     /** true on the home's web; false on a hub serving on its own */
     home: boolean
+    /** the one repo's base, read from where the page sits: the embed page under a proxy's prefix (embed.ts) */
+    base?: string
 }
 
 export class HomeSt {
@@ -78,6 +81,8 @@ export class HomeSt {
     layout: LayoutSt
     /** the run chart docked under the whole page */
     dock: DockSt
+    /** dark, light or the system's */
+    readonly theme = new ThemeSt()
     page: Page
     /** the key of the repo picked last: its name on the home, '' for the one
      *  repo of a hub of its own. A global page keeps it (only `shown` says
@@ -90,7 +95,10 @@ export class HomeSt {
     private prefetching = false
     private readonly onUrl = (): void => this.fromUrl()
 
+    private readonly base: string | undefined
+
     constructor(o: HomeOpts) {
+        this.base = o.base
         this.projects = new ProjectsSvc()
         this.planned = new PlannedSt(this)
         this.activity = new ActivitySt(this)
@@ -100,7 +108,7 @@ export class HomeSt {
         this.dock = new DockSt(this)
         this.machine = o.home ? new MachineSt(this, o) : null
         this.page = o.home ? 'overview' : 'repo'
-        makeAutoObservable<this, 'disposers' | 'onUrl' | 'prefetching'>(this, { machine: false, projects: false, planned: false, activity: false, insights: false, palette: false, layout: false, dock: false, repos: observableShallow, disposers: false, onUrl: false, prefetching: false })
+        makeAutoObservable<this, 'disposers' | 'onUrl' | 'prefetching' | 'base'>(this, { base: false, machine: false, projects: false, planned: false, activity: false, insights: false, palette: false, layout: false, theme: false, dock: false, repos: observableShallow, disposers: false, onUrl: false, prefetching: false })
         const m = this.machine
         if (m != null) {
             this.projects.onSelect = (name) => this.select(name)
@@ -143,7 +151,7 @@ export class HomeSt {
     repo(key: string): RepoSt {
         let r = this.repos.get(key)
         if (r == null) {
-            r = new RepoSt(this, key, this.machine == null ? '' : repoBase(key))
+            r = new RepoSt(this, key, this.base ?? (this.machine == null ? '' : repoBase(key)))
             this.repos.set(key, r)
             // what this browser kept of it paints before its hub answers
             void r.cols.restore()

package/src/serve/hub-app/home-strip.tsx

@@ -15,7 +15,8 @@
 // while its hub cannot answer, with the fix. Every link of the home is a
 // page of the same app: a plain click moves it in place.
 import { observer } from 'mobx-react-lite'
-import type { ReactNode } from 'react'
+import type { CSSProperties, ReactNode } from 'react'
+import { idVars } from './projects-svc.ts'
 import type { OpenHow, ProcessIcon, ResourceView } from '../../home/resources.ts'
 import type { WorkerView } from '../../home/hubs.ts'
 import { NOT_INSTALLED } from '../../home/home-words.ts'
@@ -238,7 +239,7 @@ const ShownRepo = observer(({ app, name }: { app: HomeSt; name: string }) => {
         <span className="hrepo">
             {/* the icon's box is there before the project list is, so the name never moves */}
             {p?.icon != null ? <img src={p.icon} alt="" width={18} height={18} /> : <i className="hrico" />}
-            <b className="hrname" style={{ color: id.colorDark }}>{name}</b>
+            <b className="hrname idc" style={idVars(id) as CSSProperties}>{name}</b>
         </span>
     )
 })

package/src/serve/hub-app/home.html

@@ -14,6 +14,7 @@
   <link rel="stylesheet" href="./readme.css" />
   <link rel="stylesheet" href="./dock.css" />
   <link rel="stylesheet" href="./controls.css" />
+  <link rel="stylesheet" href="./review.css" />
 </head>
 <body data-home>
   <div id="root"></div>