rvlib-shipkit 2.2.0 → 2.4.0

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

@@ -80,16 +80,17 @@ export const InsightsView = observer(({ app }: { app: HomeSt }) => {
     return (
         <div className="hall activity insights">
             <div className="actop">
-                <div className="acwin" role="radiogroup" aria-label="which repos">
+                <div className="seg" role="radiogroup" aria-label="which repos">
                     {(Object.keys(SCOPE_WORDS) as Scope[]).map((s) => (
                         <button key={s} role="radio" aria-checked={st.scope === s} className={st.scope === s ? 'on' : ''} title={SCOPE_WORDS[s].title} onClick={() => st.setScope(s)}>{SCOPE_WORDS[s].label}</button>
                     ))}
                 </div>
-                <div className="acwin" role="radiogroup" aria-label="which boxes">
+                <div className="seg" role="radiogroup" aria-label="which boxes">
                     <button role="radio" aria-checked={st.tag == null} className={st.tag == null ? 'on' : ''} onClick={() => st.setTag(null)}>all</button>
                     {st.tags.map((t) => <button key={t} role="radio" aria-checked={st.tag === t} className={st.tag === t ? 'on' : ''} onClick={() => st.setTag(t)}>{t}</button>)}
                 </div>
-                <input className="inquery" type="search" placeholder="filter: a package, a script…" aria-label="filter every box" value={st.query} onChange={(e) => st.setQuery(e.currentTarget.value)} />
+                {/* focused as the page opens (⌘; then type a package name) */}
+                <input className="inquery" type="search" autoFocus placeholder="filter: a package, a script…" aria-label="filter every box" value={st.query} onChange={(e) => st.setQuery(e.currentTarget.value)} />
                 <button type="button" className="acpill" disabled={st.loading} onClick={() => st.refresh()} title="read every package.json again now · an answer is kept 5 minutes">
                     <span className={`acring${st.loading ? ' on' : ''}`}>↻</span>
                 </button>

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

@@ -1,12 +1,13 @@
 // the page's command keys, read the same on every layout: ⌘1 to ⌘9 select the
 // nth repo of the project list, ⌘↑ and ⌘↓ the repo above or below, then the home row under the right hand: ⌘J
-// the picker, ⌘K the overview, ⌘L the activity, ⌘' the plan. ⌘B cycles the
-// dock at the bottom of the page (dock-st.ts): the line, slim, open.
-// A digit and the quote are read from the physical key (`code`), so an
+// the picker, ⌘K the overview, ⌘L the activity, ⌘; the insights, ⌘' the plan.
+// ⌘B folds the project list to its icon rail and back (layout-st.ts), ⌘⇧B
+// cycles the dock at the bottom of the page (dock-st.ts): the line, slim, open.
+// A digit, the semicolon and the quote are read from the physical key (`code`), so an
 // AZERTY keyboard, where the key under 1 types `&`, selects the same repo. Ctrl stands in for
 // ⌘ off a Mac. The macOS app binds none of these to a menu item, so they
 // reach the page (tests/home-strip.test.tsx reads ShipkitGui.swift).
-export type PageKey = { t: 'repo'; n: number } | { t: 'step'; by: -1 | 1 } | { t: 'home' } | { t: 'planned' } | { t: 'activity' } | { t: 'picker' } | { t: 'dock' }
+export type PageKey = { t: 'repo'; n: number } | { t: 'step'; by: -1 | 1 } | { t: 'home' } | { t: 'planned' } | { t: 'activity' } | { t: 'insights' } | { t: 'picker' } | { t: 'dock' } | { t: 'rail' }
 
 type KeyLike = { key: string; code: string; metaKey: boolean; ctrlKey: boolean; shiftKey: boolean; altKey: boolean }
 
@@ -14,26 +15,29 @@ export function pageKey(e: KeyLike): PageKey | null {
     if (!(e.metaKey || e.ctrlKey) || e.altKey) return null
     const digit = /^Digit([1-9])$/.exec(e.code)
     if (digit != null) return { t: 'repo', n: Number(digit[1]) }
-    if (e.shiftKey) return null
+    if (e.shiftKey) return e.code === 'KeyB' || e.key.toLowerCase() === 'b' ? { t: 'dock' } : null
     if (e.key === 'ArrowUp') return { t: 'step', by: -1 }
     if (e.key === 'ArrowDown') return { t: 'step', by: 1 }
     if (e.code === 'Quote' || e.key === "'") return { t: 'planned' }
+    if (e.code === 'Semicolon' || e.key === ';') return { t: 'insights' }
     const k = e.key.toLowerCase()
     if (k === 'j') return { t: 'picker' }
     if (k === 'k') return { t: 'home' }
     if (k === 'l') return { t: 'activity' }
-    if (k === 'b') return { t: 'dock' }
+    if (k === 'b') return { t: 'rail' }
     return null
 }
 
 /** the shortcut each place of the home carries on its button */
-export const PLACE_KEY: Record<'overview' | 'planned' | 'activity', string> & Partial<Record<string, string>> = { overview: '⌘K', planned: "⌘'", activity: '⌘L' }
+export const PLACE_KEY: Record<'overview' | 'planned' | 'activity' | 'insights', string> & Partial<Record<string, string>> = { overview: '⌘K', planned: "⌘'", activity: '⌘L', insights: '⌘;' }
 /** the picker's shortcut, on the first button, before home */
 export const PICKER_KEY = '⌘J'
 /** the repo above and below, hinted at the project list's foot */
 export const STEP_KEYS = ['⌘↑', '⌘↓'] as const
 /** the dock's shortcut, on the dock's own header */
-export const DOCK_KEY = '⌘B'
+export const DOCK_KEY = '⌘⇧B'
+/** the project list between its full width and its icon rail */
+export const RAIL_KEY = '⌘B'
 
 /** the tree's filter, on a repo page: a plain `/` focuses it, and its
  *  badge at the input's right prints this */
@@ -54,8 +58,8 @@ export function isSearchKey(e: Pick<KeyLike, 'key' | 'metaKey' | 'ctrlKey' | 'al
  *  plus a letter only types a character inside a text field, where the page
  *  leaves the key alone. Read from the physical key (`code`): on a Mac ⌥C
  *  types ç, and AZERTY moves the letters */
-export type SectionId = 'readme' | 'contracts' | 'shipkit' | 'repo' | 'secrets' | 'when' | 'runs' | 'plan' | 'processes' | 'git' | 'asks' | 'reflections' | 'tests' | 'media' | 'wikis' | 'admin'
-export const SECTION_LETTER: Record<SectionId, string> = { readme: 'E', contracts: 'K', shipkit: 'S', repo: 'C', secrets: 'X', when: 'O', runs: 'R', plan: 'N', processes: 'P', git: 'G', asks: 'A', reflections: 'F', tests: 'T', media: 'M', wikis: 'W', admin: 'D' }
+export type SectionId = 'readme' | 'contracts' | 'shipkit' | 'repo' | 'secrets' | 'when' | 'runs' | 'plan' | 'processes' | 'git' | 'asks' | 'review' | 'reflections' | 'tests' | 'media' | 'trailer' | 'wikis' | 'admin'
+export const SECTION_LETTER: Record<SectionId, string> = { readme: 'E', review: 'V', trailer: 'L', contracts: 'K', shipkit: 'S', repo: 'C', secrets: 'X', when: 'O', runs: 'R', plan: 'N', processes: 'P', git: 'G', asks: 'A', reflections: 'F', tests: 'T', media: 'M', wikis: 'W', admin: 'D' }
 /** a section's words on its row, where the id alone would not say it */
 export const SECTION_LABEL: Partial<Record<SectionId, string>> = { shipkit: 'shipkit checks', repo: 'repo checks' }
 export const sectionLabel = (id: SectionId): string => SECTION_LABEL[id] ?? id

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

@@ -3,7 +3,9 @@
 // its separator (react-resizable-panels) and kept per browser in px, so the
 // next load renders at that width from its first paint. A stored value that
 // is not a number, or is out of bounds, reads as the default: no runtime
-// value can hand the page a list wider than LIST.max.
+// value can hand the page a list wider than LIST.max. The list also folds to
+// its icon rail: a drag below its min or ⌘B, kept per browser too, its icons
+// small, medium or large (RAIL_ICONS), the rail as wide as they need.
 import { makeAutoObservable } from 'mobx'
 
 export type Bounds = { key: string; min: number; max: number; def: number }
@@ -11,7 +13,26 @@ export type Bounds = { key: string; min: number; max: number; def: number }
 /** the project list: icon and name on one line */
 export const LIST: Bounds = { key: 'hub:list-width', min: 140, max: 360, def: 200 }
 /** a repo's sidebar: the resource tree */
-export const SIDEBAR: Bounds = { key: 'hub:sidebar-width', min: 220, max: 640, def: 330 }
+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: 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 = 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'
+const RAIL_ICON_KEY = 'hub:rail-icon'
+
+function loadRailIcon(): RailIcon {
+    try {
+        const v = globalThis.localStorage?.getItem(RAIL_ICON_KEY) ?? ''
+        return v in RAIL_ICONS ? (v as RailIcon) : 'm'
+    } catch {
+        return 'm'
+    }
+}
 
 /** a width in its bounds, or the default for anything else */
 export const clampWidth = (v: unknown, b: Bounds): number => {
@@ -33,8 +54,20 @@ function saveWidth(b: Bounds, px: number): void {
     } catch { /* private window or blocked site data: the width lasts the tab */ }
 }
 
+function loadRail(): boolean {
+    try {
+        return globalThis.localStorage?.getItem(RAIL_KEY) === '1'
+    } catch {
+        return false
+    }
+}
+
 export class LayoutSt {
     listWidth = loadWidth(LIST)
+    /** the list shows its icons only */
+    listRail = loadRail()
+    /** the rail's icon size */
+    railIcon: RailIcon = loadRailIcon()
     sidebarWidth = loadWidth(SIDEBAR)
 
     constructor() {
@@ -47,6 +80,34 @@ export class LayoutSt {
         saveWidth(LIST, this.listWidth)
     }
 
+    /** the list folded to its icons, or back at its kept width */
+    setRail(on: boolean): void {
+        if (this.listRail === on) return
+        this.listRail = on
+        try {
+            globalThis.localStorage?.setItem(RAIL_KEY, on ? '1' : '0')
+        } catch { /* private window or blocked site data: the rail lasts the tab */ }
+    }
+
+    /** the rail's width, its icon and its margins */
+    get railPx(): number {
+        return railPx(this.railIcon)
+    }
+
+    /** the rail's size button: small, medium, large, then small again */
+    cycleRailIcon(): void {
+        const all = Object.keys(RAIL_ICONS) as RailIcon[]
+        this.railIcon = all[(all.indexOf(this.railIcon) + 1) % all.length]!
+        try {
+            globalThis.localStorage?.setItem(RAIL_ICON_KEY, this.railIcon)
+        } catch { /* private window or blocked site data: the size lasts the tab */ }
+    }
+
+    /** ⌘B */
+    toggleRail(): void {
+        this.setRail(!this.listRail)
+    }
+
     /** a drag of the sidebar's separator ended at this width */
     setSidebarWidth(px: number): void {
         this.sidebarWidth = clampWidth(Math.round(px), SIDEBAR)

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/planned-view.tsx

@@ -8,6 +8,7 @@
 // place, the check opens its own page in that repo.
 import { observer } from 'mobx-react-lite'
 import type { CSSProperties, MouseEvent, ReactNode } from 'react'
+import { idVars } from './projects-svc.ts'
 import type { PlanRow } from '../../plan/planner.ts'
 import { Tip } from './floating.tsx'
 import type { HomeSt } from './home-st.ts'
@@ -62,14 +63,14 @@ const Card = observer(({ app, r, now }: { app: HomeSt; r: PlanRow; now: number }
 const Row = observer(({ app, r, now }: { app: HomeSt; r: PlanRow; now: number }) => {
     const st = app.planned
     const m = markOf(r)
-    const colour = { '--pc': app.projects.identityOf(r.repo).colorDark } as CSSProperties
+    const colour = idVars(app.projects.identityOf(r.repo)) as CSSProperties
     return (
         <Tip className={`plr m-${m.mark}`} content={<Card app={app} r={r} now={now} />} tipClass="plcard" placement="right-start" fallbacks={['bottom-end', 'top-end']} interactive>
             <span className="plwhen">{whenWords(r, now)}</span>
             <span className="plwhat">
                 <InPlace className="plrepo" href={repoPage(r.repo)} go={() => st.openRepo(r.repo)}>
                     <Face app={app} repo={r.repo} />
-                    <span style={colour}>{r.repo}</span>
+                    <span className="idc" style={colour}>{r.repo}</span>
                 </InPlace>
                 <span className="pldim"> · </span>
                 <InPlace className="plcheck" href={checkAddress(r.repo, r.check)} go={() => st.openCheck(r.repo, r.check)}>{r.check}</InPlace>

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

@@ -15,7 +15,6 @@
 .m-running .plwhen{color:var(--accent)}
 .plwhat{min-width:0;overflow:hidden;text-overflow:ellipsis}
 .plrepo,.plcheck{color:inherit;text-decoration:none}
-.plrepo span{color:var(--pc)}
 .plrepo:hover span,.plcheck:hover{text-decoration:underline}
 .plface{width:14px;height:14px;margin-right:var(--s1);vertical-align:-2px;border-radius:3px;object-fit:contain}
 .pldim{color:var(--dim)}

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

@@ -22,16 +22,16 @@
 .pjaini{flex:none;width:14px;height:14px;border-radius:3px;background:var(--panel2)}
 /* the foot: sort (its title names the order), the step keys hint, archived
    carries its count and stays lit while its rows show */
-.pgsort,.pjarbtn{flex:none;display:inline-flex;align-items:center;gap:var(--s1);height:22px;padding:0 var(--s1);background:transparent;border:1px solid var(--line);border-radius:3px;
+.pgsort,.pjarbtn,.pjfold{flex:none;display:inline-flex;align-items:center;gap:var(--s1);height:22px;padding:0 var(--s1);background:transparent;border:1px solid var(--line);border-radius:3px;
  color:var(--dim);font-size:11px;cursor:pointer}
 .pgsort{flex:0 1 auto;min-width:0}
 /* the step keys, a hint: the repo above or below */
 .pjstep{flex:none;display:inline-flex;gap:var(--s0);margin-left:auto;color:var(--dim);font-size:11px}
 .pjstep kbd{padding:0 var(--s1);border:1px solid var(--line);border-radius:3px;font:inherit}
 .pgsortl{min-width:0;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
-.pgsort .hico,.pjarbtn .hico{flex:none;width:14px;height:14px}
-.pgsort:hover,.pjarbtn:hover{color:var(--ink);border-color:var(--accent)}
-.pjarbtn.on{color:var(--ink);background:var(--sel);border-color:var(--accent)}
+.pgsort .hico,.pjarbtn .hico,.pjfold .hico{flex:none;width:14px;height:14px}
+.pgsort:hover,.pjarbtn:hover,.pjfold:hover{color:var(--ink);border-color:var(--accent)}
+.pjarbtn.on,.pjfold[aria-pressed=true]{color:var(--ink);background:var(--sel);border-color:var(--accent)}
 .pjarbtn span{font-variant-numeric:tabular-nums}
 /* the sort menu: over the foot, placed by floating-ui (floating.tsx) */
 .pgmenu{z-index:30;min-width:180px;padding:var(--s1) 0;background:var(--panel);border:1px solid var(--line);border-radius:4px;box-shadow:0 6px 20px var(--shadow);font-size:12px}
@@ -50,6 +50,9 @@
 .pjrow:hover,.pjpl:hover{background:var(--panel2);color:var(--ink)}
 /* the shown repo: its row lit, marked on the left in its identity colour
    (a global page's line: in the accent) */
+/* the repo's colour for the theme: colorDark, or colorLight on a light page (projects-svc idVars) */
+.pjrow{--pjc:var(--idd)}
+:root[data-theme=light] .pjrow{--pjc:var(--idl)}
 .pjrow.cur,.pjpl.cur{background:var(--sel);color:var(--pjc,var(--ink));box-shadow:inset 3px 0 0 var(--pjc,var(--accent));font-weight:600}
 .pjpl .hico{flex:none;width:18px;height:18px;color:inherit}
 /* the selected repo while a global page is up: still marked, dimmer */
@@ -66,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}
@@ -119,3 +122,20 @@
 .rsep{position:relative;flex:none;width:1px;background:var(--line)}
 .rsep::before{content:'';position:absolute;top:0;bottom:0;left:-6px;right:-6px;cursor:col-resize;background:transparent;z-index:6}
 .rsep:hover,.rsep[data-separator="hover"],.rsep[data-separator="active"]{background:var(--accent)}
+/* the rail: the list folded to its icons (layout-st RAIL_PX). The names, the
+   ⌘ hints and the step hint hide, every icon centres, the badge and the dots
+   ride the icon's corner, the foot stacks its buttons */
+.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,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: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}

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

@@ -3,7 +3,7 @@
 // the shown repo's row marked in its identity colour. Its width is the
 // panel the page gives it (hub-app.tsx, react-resizable-panels). A row says
 // three things and no more (faceOf): the open asks as its one badge, a dim
-// icon while VS Code does not have the folder open, a thin edge breathing
+// name (never the icon) while VS Code does not have the folder open, a thin edge breathing
 // while Claude sessions run in it; on the home, a dot while its hub starts
 // or crashed and a mark while a global process it uses is off. Everything
 // else is the hover card, placed by floating-ui beside the row. A click
@@ -13,7 +13,10 @@
 // labeled sorts (a pick sorts once, the button names the order the list is
 // in), archived shows or hides the archived repos just above the foot
 // (names only, no ⌘ number, a row opens the archived page, nothing loads),
-// the foot never moving. On the home a section of four lines on top, in the
+// the foot never moving. ⌘B (or the foot's fold button, or a drag of the
+// separator below the list's min) folds the list to its icon rail: the
+// names, the ⌘ hints and the step hint hide, the badge rides the icon's
+// corner, the hover card still names the row. On the home a section of four lines on top, in the
 // repo rows' style, opens the picker, the overview, the activity and the
 // plan, each with its shortcut at the line's end, the page shown lit. It
 // renders from the first paint with the list this browser kept, so a load
@@ -24,14 +27,17 @@ import { useEffect, type CSSProperties } from 'react'
 import { middleware, OPEN_MS } from './floating.tsx'
 import { Icon, ICON } from './icons.tsx'
 import { plainClick } from './home-st.ts'
-import { PICKER_KEY, PLACE_KEY, STEP_KEYS } from './keys.ts'
-import { cardModel, faceOf, hueOf, SORTS, type Place, type Project, type ProjectsSvc } from './projects-svc.ts'
+import { PICKER_KEY, PLACE_KEY, RAIL_KEY, STEP_KEYS } from './keys.ts'
+import { cardModel, faceOf, hueOf, idVars, SORTS, type Place, type Project, type ProjectsSvc } from './projects-svc.ts'
+import { THEMES, type ThemePick } from './theme-st.ts'
+import { RAIL_ICONS, type RailIcon } from './layout-st.ts'
 
-/** what the list needs of its page: the hub and the home both carry one */
-export type ListHost = { projects: ProjectsSvc }
+/** what the list needs of its page: the hub and the home both carry one;
+ *  the layout, when the page can fold the list to its rail */
+export type ListHost = { projects: ProjectsSvc; layout?: { listRail: boolean; toggleRail(): void; railIcon: RailIcon; cycleRailIcon(): void }; theme?: { pick: ThemePick; cycle(): void } }
 
 /** the lines on top of the list, in their order: the picker, the overview,
- *  then the places, their shortcuts ⌘J ⌘K ⌘L ⌘' top to bottom */
+ *  then the places, each with its shortcut (keys.ts) */
 const PLACES: { id: Place | 'picker'; label: string; title: string }[] = [
     { id: 'picker', label: 'jump to…', title: 'jump to a page, a repo or one of its resources' },
     { id: 'overview', label: 'overview', title: 'the overview: shipkit, every global process and every repo on this machine' },
@@ -65,7 +71,8 @@ export const Row = observer(({ app, p, i }: { app: ListHost; p: Project; i: numb
     const dot = s.dotOf(p.name)
     const warn = s.warnOf(p.name)
     // the shown repo's row is marked in its own colour
-    const mark = cur ? ({ '--pjc': s.identityOf(p.name).colorDark } as CSSProperties) : undefined
+    const mark = cur ? (idVars(s.identityOf(p.name)) as CSSProperties) : undefined
+    // folded, the rail wears the repo's app icon: its mark on its identity plate
     return (
         <>
             <button ref={f.refs.setReference} className={cls} aria-label={p.name} style={mark} draggable
@@ -89,7 +96,9 @@ export const Row = observer(({ app, p, i }: { app: ListHost; p: Project; i: numb
                     },
                     onDragEnd: () => s.dragEnd(),
                 })}>
-                <Face p={p} px={ROW_ICON} />
+                {app.layout?.listRail === true && p.appIcon != null
+                    ? <img className="pjapp" src={p.appIcon} alt="" width={ROW_ICON} height={ROW_ICON} draggable={false} />
+                    : <Face p={p} px={ROW_ICON} />}
                 <span className="pjname">{p.name}</span>
                 {face.badge != null ? <b className="pga">{face.badge}</b> : null}
                 {face.busy ? <i className="pgs" /> : null}
@@ -155,8 +164,10 @@ export const Card = ({ p, now }: { p: Project; now: number }) => {
 export const ProjectList = observer(({ app }: { app: ListHost }) => {
     useEffect(() => app.projects.start(), [app])
     const s = app.projects
+    const lay = app.layout
+    const rail = lay?.listRail === true
     return (
-        <nav className="pjlist" aria-label="projects">
+        <nav className={`pjlist${rail ? ' rail' : ''}`} aria-label="projects" style={rail ? ({ '--ri': `${RAIL_ICONS[lay!.railIcon]}px` } as CSSProperties) : undefined}>
             {s.onPlace == null && s.onPicker == null && s.error === '' ? null : (
                 <div className="pjhead">
                     {PLACES.map((pl) => {
@@ -195,6 +206,17 @@ export const ProjectList = observer(({ app }: { app: ListHost }) => {
                 </div>
             ) : null}
             <div className="pjfoot">
+                {lay == null ? null : (
+                    <button className="pjfold" aria-pressed={rail} title={`${rail ? 'show the names' : 'fold the list to its icons'} (${RAIL_KEY})`} onClick={() => lay.toggleRail()}>
+                        <Icon d={ICON.rail} />
+                    </button>
+                )}
+                {lay == null || !rail ? null : (
+                    <button className="pjfold pjsize" aria-label={`icon size: ${lay.railIcon}`} title={`the icons: ${SIZE_WORDS[lay.railIcon]}; click for the next size`} onClick={() => lay.cycleRailIcon()}>
+                        {lay.railIcon.toUpperCase()}
+                    </button>
+                )}
+                {app.theme == null ? null : <ThemeButton t={app.theme} />}
                 <SortButton s={s} />
                 <span className="pjstep" title={`${STEP_KEYS[0]} and ${STEP_KEYS[1]} open the repo above or below, from any page`}>
                     {STEP_KEYS.map((k) => <kbd key={k}>{k}</kbd>)}
@@ -211,6 +233,20 @@ export const ProjectList = observer(({ app }: { app: ListHost }) => {
     )
 })
 
+const SIZE_WORDS: Record<RailIcon, string> = { s: 'small', m: 'medium', l: 'large' }
+
+const THEME_ICON: Record<ThemePick, keyof typeof ICON> = { dark: 'moon', light: 'sun', auto: 'auto' }
+
+/** the theme: dark, light or auto (the system's), one click to the next */
+const ThemeButton = observer(({ t }: { t: { pick: ThemePick; cycle(): void } }) => {
+    const next = THEMES[(THEMES.indexOf(t.pick) + 1) % THEMES.length]
+    return (
+        <button className="pjfold" aria-label={`theme: ${t.pick}`} title={`theme: ${t.pick}${t.pick === 'auto' ? ' (follows the system)' : ''}; click for ${next}`} onClick={() => t.cycle()}>
+            <Icon d={ICON[THEME_ICON[t.pick]]} />
+        </button>
+    )
+})
+
 /** the words for the order the list is in */
 const orderWords = (s: ProjectsSvc): string => {
     const m = s.sortMode

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

@@ -7,6 +7,10 @@ import type { ArchivedRow, ProjectRow as Project, Release } from '../project-gut
 import { identityOfName, type Identity } from '../../core/identity-color.ts'
 import { ownTrouble, reach } from './reach.ts'
 
+/** a repo's two colours as the vars a `.idc` element or a list row reads,
+ *  hub.css picking the one for the page's theme */
+export const idVars = (id: Pick<Identity, 'colorDark' | 'colorLight'>): Record<'--idd' | '--idl', string> => ({ '--idd': id.colorDark, '--idl': id.colorLight })
+
 /** the list never says the page's server is gone, even where no machine
  *  card is (a hub on its own): that hub's trouble card says it */
 const SAID_ELSEWHERE = true
@@ -130,8 +134,9 @@ export function sortNames(list: Project[], mode: SortMode): string[] {
 export type HubDot = 'starting' | 'crashed' | null
 
 /** what the icon face shows, and nothing more: at most ONE badge (the open
- *  asks, the only fact that needs a human's hands), dim while VS Code does
- *  not have the folder open, and a pulsing edge while Claude sessions run */
+ *  asks, the only fact that needs a human's hands), a dim name while VS Code
+ *  does not have the folder open (the icon stays whole), and a pulsing edge
+ *  while Claude sessions run */
 export type Face = { badge: number | null; dim: boolean; busy: boolean }
 export const faceOf = (p: Project): Face => ({
     badge: p.asks > 0 ? p.asks : null,

package/src/serve/hub-app/repo-sections.ts

@@ -8,7 +8,7 @@
 // own has none of the three. The counts read the severity filter, like everything under them,
 // and come from what the page already holds (the kept screen on a reload), so
 // none arrives late and moves the tree.
-import { RUNS_ID } from '../../collections/collection-types.ts'
+import { REVIEW_COL, RUNS_ID, TRAILER_COL } from '../../collections/collection-types.ts'
 import type { CheckOwner, HashSel } from './hash-route.ts'
 import { sectionLabel, type SectionId } from './keys.ts'
 import type { RepoSt } from './repo-st.ts'
@@ -45,6 +45,8 @@ export function sectionOfSel(sel: HashSel | null, ownerOf: (checkItemId: string)
         case 'when': return 'when'
         case 'checks': return sel.from
         case 'admin': return 'admin'
+        case 'review': return 'review'
+        case 'trailer': return 'trailer'
         case 'tests': return 'tests'
         case 'asset': case 'cat': return 'media'
         case 'status': return null
@@ -54,6 +56,8 @@ export function sectionOfSel(sel: HashSel | null, ownerOf: (checkItemId: string)
             if (col === WIKIS) return 'wikis'
             if (col === 'contracts') return 'contracts'
             if (col === 'creds') return 'secrets'
+            if (col === REVIEW_COL) return 'review'
+            if (col === TRAILER_COL) return 'trailer'
             if (col === 'checks') return sel.t === 'item' ? ownerOf(sel.id) : null
             return col === 'asks' || col === 'tests' || col === 'reflections' ? col : null
         }
@@ -87,11 +91,14 @@ export function openSection(app: RepoSt, id: SectionId): void {
         }
         case 'wikis': return openWikis(app)
         case 'admin': return app.showAdmin()
+        case 'review': return app.showReview(app.review.selectedId)
+        case 'trailer': return app.showTrailer(app.trailer.trailerId, app.trailer.cutId)
     }
 }
 
-/** the sections whose page says it is empty, so an empty row still opens it */
-const EMPTY_PAGES = new Set<SectionId>(['processes'])
+/** the sections whose page says it is empty, so an empty row still opens it: the review and trailer pages say how a
+ *  first card or a first cut comes */
+const EMPTY_PAGES = new Set<SectionId>(['processes', 'review', 'trailer'])
 
 export function repoSections(app: RepoSt): RepoSection[] {
     const has = (col: string): boolean => app.cols.colMeta.some((c) => c.id === col)
@@ -106,6 +113,11 @@ export function repoSections(app: RepoSt): RepoSection[] {
     const out: RepoSection[] = [line('readme', 'the README, what the repo is', none)]
     const ownReds = (from: CheckOwner): number => res.filter((r) => r.check?.from === from && r.state === 'red').length
     const unless = (on: boolean, why: string): string | null => (on ? null : why)
+    // review and trailer sit right under the readme: the pages he answers
+    out.push(line('review', 'the review cards agents send you: approve, fix, reject, circle a detail', counted(res.filter((r) => r.type === 'card').length, 'warn'),
+        unless(has(REVIEW_COL), 'no review card yet: an agent sends one with sk review add')))
+    out.push(line('trailer', 'the trailer cuts: play one with its timeline, pin a note on any frame', none,
+        unless(has(TRAILER_COL), 'no trailer: write trailer/<name>/main.trailer, then sk trailer')))
     out.push(line('contracts', 'what a release venue asks of this repo, and what it still lacks', counted(reds('contracts'), 'red'), unless(has('contracts'), 'no contract: no release venue applies to this repo')))
     const noChecks = unless(has('checks'), 'no checks yet: its hub has not answered')
     out.push(line('shipkit', 'the checks shipkit ships to every repo, one page each', counted(ownReds('shipkit'), 'red'), noChecks))