rvlib-shipkit 2.1.1 → 2.3.0

package/src/shot/shooter.ts

@@ -0,0 +1,343 @@
+// the browser half of the shots: ONE headless chromium, ONE booted page kept
+// warm, one request at a time on it (`Turns`). A still reuses the page when
+// it already shows the url (its own HMR keeps it current), so a warm shot is
+// a ready check plus chromium's fast capture. A clip films on a page of its
+// own in the same browser, so it never disturbs the warm page: a page that IS
+// a canvas through the page's WebCodecs (clip-encoder.ts), any other page
+// through chromium's screencast and ffmpeg (dom-clip.ts).
+//
+// it never slows the machine's other work: the browser runs niced, the page
+// stays live only LIVE_MS after a request and is then frozen (no frame, no
+// timer, no cpu), a frozen page is loaded again before its next still (an
+// edit it missed while frozen never reaches a shot), and the browser closes
+// after BROWSER_IDLE_MS.
+//
+// the constraint a reader breaks first: Playwright is NOT a dependency of the
+// lib (a toolkit every repo installs carries no browser). It is resolved from
+// the repo that runs this, through the one resolver `loadPlaywright`.
+import { mkdirSync } from 'fs'
+import { setPriority } from 'os'
+import { dirname } from 'path'
+import { loadPlaywright } from '../smoke/run-smoke.ts'
+import { CLIP_INIT, CLIP_QUANTIZER, clipDone, installClip, KEY_EVERY, muxArgs, type PageClipAsk, type PageClipDone, TAKE, takeClip } from './clip-encoder.ts'
+import { type ClipPath, clipPathOf, domEncodeArgs, FrameTimeline, largestCanvas, screencastParams } from './dom-clip.ts'
+import { capMsOf, type ClipAsk, pageMove, readMark, type ShotAsk, slotKey, Turns, waitReady } from './shot-ask.ts'
+
+/** the slice of playwright the shots touch, so the lib types nothing it does not ship */
+type Cdp = {
+    send(method: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>
+    on(event: string, cb: (e: Record<string, unknown>) => void): unknown
+    off(event: string, cb: (e: Record<string, unknown>) => void): unknown
+}
+type Page = {
+    goto(url: string, o?: { waitUntil?: string; timeout?: number }): Promise<unknown>
+    reload(o?: { waitUntil?: string; timeout?: number }): Promise<unknown>
+    evaluate<R, A>(fn: (a: A) => R | Promise<R>, arg?: A): Promise<R>
+    waitForTimeout(ms: number): Promise<void>
+    on(event: string, cb: (x: { message?: string; text?(): string; type?(): string }) => void): void
+    close(): Promise<void>
+    isClosed(): boolean
+}
+type Context = { newPage(): Promise<Page>; newCDPSession(p: Page): Promise<Cdp>; addInitScript(s: { content: string }): Promise<void>; close(): Promise<void> }
+type Browser = {
+    newContext(o: { viewport: { width: number; height: number }; deviceScaleFactor: number; locale?: string }): Promise<Context>
+    close(): Promise<void>
+    isConnected(): boolean
+    on(event: 'disconnected', cb: () => void): void
+}
+type Playwright = { chromium: { launch(o: { headless: boolean; args: string[] }): Promise<Browser> } }
+
+/** WebGL on the GPU over metal on a mac: in software a 3D page crawls. Audio plays with no gesture */
+export const BROWSER_ARGS = [...(process.platform === 'darwin' ? ['--use-angle=metal', '--enable-gpu', '--ignore-gpu-blocklist'] : []), '--autoplay-policy=no-user-gesture-required']
+
+/** the page keeps running this long after a request (an agent's burst of shots), then it is frozen */
+export const LIVE_MS = 10_000
+/** the browser closes after this long with no request; the next shot pays its launch again (about 1 s) */
+export const BROWSER_IDLE_MS = 60_000
+/** the niceness of the process that launches the browser: chromium inherits it */
+export const SHOT_NICE = 10
+/** a page that paints nothing once the screencast starts is filmed from one still taken after this */
+const FIRST_FRAME_MS = 1000
+
+export type ShotDone = { out: string; ms: number; phases: Record<string, number>; errors: string[]; note: string }
+
+type Slot = { key: string; url: string; ctx: Context; page: Page; cdp: Cdp; errors: string[]; frozen: boolean }
+
+/** the roots tried for playwright, in order: the repo that runs the shots, then wherever this lib sits */
+export async function resolvePlaywright(roots: string[]): Promise<Playwright> {
+    let last: unknown = null
+    for (const r of roots) {
+        try {
+            return await loadPlaywright<Playwright>(r)
+        } catch (e) {
+            last = e
+        }
+    }
+    throw last instanceof Error ? last : new Error(String(last))
+}
+
+const ms = (t0: number): number => Math.round(performance.now() - t0)
+
+const withCap = <T>(what: string, capMs: number, p: Promise<T>): Promise<T> =>
+    Promise.race([p, new Promise<T>((_, fail) => setTimeout(() => fail(new Error(`${what} took past ${capMs / 1000} s`)), capMs).unref?.())])
+
+export class Shooter {
+    readonly #roots: string[]
+    readonly #turns = new Turns()
+    #browser: Browser | null = null
+    #launching: Promise<Browser> | null = null
+    #slot: Slot | null = null
+    #idle: ReturnType<typeof setTimeout> | null = null
+    #live: ReturnType<typeof setTimeout> | null = null
+
+    constructor(roots: string[]) {
+        this.#roots = roots
+    }
+
+    get warm(): { browser: boolean; url: string | null; waiting: number } {
+        return { browser: this.#browser?.isConnected() === true, url: this.#slot?.url ?? null, waiting: this.#turns.waiting }
+    }
+
+    /** a png of the url, written at `a.out` */
+    shot(a: ShotAsk): Promise<ShotDone> {
+        return this.#turns.run(() => withCap(`the shot of ${a.url}`, capMsOf(a), this.#shot(a)).finally(() => this.#touch()))
+    }
+
+    /** an mp4 of `a.seconds` of the url, written at `a.out`: its canvas when the canvas is the page, else the page */
+    clip(a: ClipAsk): Promise<ShotDone> {
+        return this.#turns.run(() => withCap(`the clip of ${a.url}`, capMsOf(a), this.#clip(a)).finally(() => this.#touch()))
+    }
+
+    async close(): Promise<void> {
+        if (this.#idle) clearTimeout(this.#idle)
+        if (this.#live) clearTimeout(this.#live)
+        this.#slot = null
+        const b = this.#browser
+        this.#browser = null
+        await b?.close().catch(() => undefined)
+    }
+
+    #touch(): void {
+        if (this.#idle) clearTimeout(this.#idle)
+        this.#idle = setTimeout(() => void this.close(), BROWSER_IDLE_MS)
+        this.#idle.unref?.()
+        if (this.#live) clearTimeout(this.#live)
+        this.#live = setTimeout(() => void this.#turns.run(() => this.#freeze()), LIVE_MS)
+        this.#live.unref?.()
+    }
+
+    async #freeze(): Promise<void> {
+        const s = this.#slot
+        if (s == null || s.frozen || s.page.isClosed()) return
+        await s.cdp.send('Page.setWebLifecycleState', { state: 'frozen' }).catch(() => undefined)
+        s.frozen = true
+    }
+
+    #ensureBrowser(): Promise<Browser> {
+        if (this.#browser?.isConnected()) return Promise.resolve(this.#browser)
+        this.#launching ??= (async () => {
+            const pw = await resolvePlaywright(this.#roots)
+            try {
+                setPriority(SHOT_NICE)
+            } catch {}
+            const b = await pw.chromium.launch({ headless: true, args: BROWSER_ARGS })
+            b.on('disconnected', () => {
+                if (this.#browser === b) {
+                    this.#browser = null
+                    this.#slot = null
+                }
+            })
+            this.#browser = b
+            return b
+        })().finally(() => (this.#launching = null))
+        return this.#launching
+    }
+
+    async #context(a: ShotAsk): Promise<Context> {
+        const b = await this.#ensureBrowser()
+        return b.newContext({ viewport: a.viewport, deviceScaleFactor: a.dpr, locale: 'en-US' })
+    }
+
+    static #listen(page: Page, errors: string[]): void {
+        page.on('pageerror', (e) => errors.push(`pageerror: ${e.message ?? ''}`))
+        page.on('console', (m) => {
+            if (m.type?.() === 'error') errors.push(`console: ${m.text?.() ?? ''}`)
+        })
+    }
+
+    async #shot(a: ShotAsk): Promise<ShotDone> {
+        const phases: Record<string, number> = {}
+        const t0 = performance.now()
+        let move = pageMove(this.#slot == null || this.#slot.page.isClosed() ? null : { url: this.#slot.url, key: this.#slot.key }, a)
+        if (move === 'boot') {
+            const old = this.#slot
+            this.#slot = null
+            await old?.ctx.close().catch(() => undefined)
+            const t = performance.now()
+            const ctx = await this.#context(a)
+            const page = await ctx.newPage()
+            const errors: string[] = []
+            Shooter.#listen(page, errors)
+            this.#slot = { key: slotKey(a), url: a.url, ctx, page, cdp: await ctx.newCDPSession(page), errors, frozen: false }
+            phases['browser'] = ms(t)
+        }
+        const slot = this.#slot!
+        slot.errors.length = 0
+        const thawed = slot.frozen
+        if (slot.frozen) {
+            await slot.cdp.send('Page.setWebLifecycleState', { state: 'active' })
+            slot.frozen = false
+        }
+        // a frozen page may have missed an edit: it loads again
+        if (move === 'none' && thawed) move = 'reload'
+        if (move !== 'none') {
+            const t = performance.now()
+            slot.url = a.url
+            if (move === 'reload') await slot.page.reload({ waitUntil: 'load', timeout: 60_000 })
+            else await slot.page.goto(a.url, { waitUntil: 'load', timeout: 60_000 })
+            phases['load'] = ms(t)
+        }
+        let t = performance.now()
+        const how = await waitReady(() => slot.page.evaluate(readMark), move === 'none' ? 0 : a.waitMs, { now: () => performance.now(), sleep: (n) => slot.page.waitForTimeout(n) })
+        phases['ready'] = ms(t)
+        t = performance.now()
+        const r = await slot.cdp.send('Page.captureScreenshot', { format: 'png', optimizeForSpeed: true })
+        phases['capture'] = ms(t)
+        mkdirSync(dirname(a.out), { recursive: true })
+        await Bun.write(a.out, Buffer.from(String(r['data']), 'base64'))
+        const note = `${move === 'none' ? 'warm page' : thawed ? 'frozen page reloaded' : move}, ${how === 'ready' ? 'ready mark' : move === 'none' ? 'no wait' : `${a.waitMs} ms after load`}`
+        return { out: a.out, ms: ms(t0), phases, errors: [...slot.errors], note }
+    }
+
+    async #clip(a: ClipAsk): Promise<ShotDone> {
+        const phases: Record<string, number> = {}
+        const t0 = performance.now()
+        const ctx = await this.#context(a)
+        const errors: string[] = []
+        try {
+            await ctx.addInitScript({ content: CLIP_INIT })
+            const page = await ctx.newPage()
+            Shooter.#listen(page, errors)
+            let t = performance.now()
+            await page.goto(a.url, { waitUntil: 'load', timeout: 60_000 })
+            await waitReady(() => page.evaluate(readMark), a.waitMs, { now: () => performance.now(), sleep: (n) => page.waitForTimeout(n) })
+            phases['load'] = ms(t)
+            t = performance.now()
+            const path: ClipPath = clipPathOf({ dom: a.dom === true, canvas: await page.evaluate(largestCanvas), viewport: a.viewport })
+            const why = path === 'canvas' ? await page.evaluate(installClip, { seconds: a.seconds, fps: a.fps, quantizer: CLIP_QUANTIZER, keyEvery: KEY_EVERY } satisfies PageClipAsk) : null
+            if (path === 'dom' || why != null) {
+                const note = await filmPage(await ctx.newCDPSession(page), page, a)
+                phases['film'] = ms(t)
+                return { out: a.out, ms: ms(t0), phases, errors, note: why == null ? note : `${note}; the canvas path refused: ${why}` }
+            }
+            const parts: Buffer[] = []
+            let done: PageClipDone | null = null
+            let failed: unknown = null
+            void page.evaluate(clipDone).then(
+                (d) => (done = d),
+                (e) => (failed = e),
+            )
+            const drain = async (): Promise<void> => {
+                for (;;) {
+                    const data = await page.evaluate(takeClip, TAKE)
+                    if (data === '') return
+                    parts.push(Buffer.from(data, 'base64'))
+                }
+            }
+            while (done == null && failed == null) {
+                await Bun.sleep(250)
+                await drain()
+            }
+            if (failed != null) throw failed instanceof Error ? failed : new Error(String(failed))
+            await drain()
+            phases['film'] = ms(t)
+            t = performance.now()
+            const stream = Buffer.concat(parts)
+            await mux(stream, a.fps, a.out)
+            phases['mux'] = ms(t)
+            const d = done as unknown as PageClipDone
+            const mb = (stream.length / 2 ** 20).toFixed(1)
+            const note = `${d.frames} frames ${d.width}x${d.height} at ${a.fps} fps (${d.repeated} repeated for a slow page), canvas ${d.canvasOfViewport}, ${mb} MB H.264 from the page's WebCodecs, muxed`
+            return { out: a.out, ms: ms(t0), phases, errors, note }
+        } finally {
+            await ctx.close().catch(() => undefined)
+        }
+    }
+}
+
+const ffmpegBin = (): string => {
+    const ffmpeg = Bun.which('ffmpeg') ?? (process.platform === 'darwin' ? '/opt/homebrew/bin/ffmpeg' : null)
+    if (ffmpeg == null) throw new Error('ffmpeg is not installed: brew install ffmpeg')
+    return ffmpeg
+}
+
+const ffmpegFailed = (what: string, err: string, code: number | null): Error => new Error(`ffmpeg ${what}: ${err.trim().split('\n').slice(-6).join('\n') || `exit ${code}`}`)
+
+/** the page's H.264 stream into an mp4 by ffmpeg, no second encode; loud with ffmpeg's own words */
+export async function mux(stream: Buffer, fps: number, out: string): Promise<void> {
+    const ffmpeg = ffmpegBin()
+    mkdirSync(dirname(out), { recursive: true })
+    const p = Bun.spawn([ffmpeg, ...muxArgs(fps, out)], { stdin: new Blob([new Uint8Array(stream)]), stdout: 'ignore', stderr: 'pipe' })
+    const err = await new Response(p.stderr).text()
+    if ((await p.exited) !== 0) throw ffmpegFailed(`mux → ${out}`, err, p.exitCode)
+}
+
+/** `a.seconds` of the page as chromium paints it, encoded by ffmpeg as the frames arrive; the note says what it filmed */
+async function filmPage(cdp: Cdp, page: Page, a: ClipAsk): Promise<string> {
+    const ffmpeg = ffmpegBin()
+    mkdirSync(dirname(a.out), { recursive: true })
+    const tl = new FrameTimeline(a.fps, a.seconds)
+    const p = Bun.spawn([ffmpeg, ...domEncodeArgs(a.fps, tl.total, a.out)], { stdin: 'pipe', stdout: 'ignore', stderr: 'pipe' })
+    const stderr = new Response(p.stderr).text()
+    let last: Uint8Array | null = null
+    let writing: Promise<unknown> = Promise.resolve()
+    const put = (copies: number, frame: Uint8Array | null): void => {
+        if (copies <= 0 || frame == null) return
+        writing = writing.then(() => {
+            for (let i = 0; i < copies; i++) p.stdin.write(frame)
+            return p.stdin.flush()
+        })
+    }
+    let stop!: () => void
+    const stopped = new Promise<void>((ok) => (stop = ok))
+    let timer: ReturnType<typeof setTimeout> | null = null
+    const frame = (t: number, data: Uint8Array): void => {
+        timer ??= setTimeout(stop, a.seconds * 1000)
+        const { previous, past } = tl.arrive(t)
+        put(previous, last)
+        if (past) stop()
+        else last = data
+    }
+    let px = `${a.viewport.width}x${a.viewport.height}`
+    const onFrame = (e: Record<string, unknown>): void => {
+        void cdp.send('Page.screencastFrameAck', { sessionId: e['sessionId'] }).catch(() => undefined)
+        const m = e['metadata'] as { timestamp?: number; deviceWidth?: number; deviceHeight?: number } | undefined
+        if (timer == null && m?.deviceWidth != null && m.deviceHeight != null) px = `${Math.round(m.deviceWidth)}x${Math.round(m.deviceHeight)}`
+        frame(m?.timestamp ?? Date.now() / 1000, Buffer.from(String(e['data']), 'base64'))
+    }
+    cdp.on('Page.screencastFrame', onFrame)
+    try {
+        await cdp.send('Page.startScreencast', screencastParams(a.viewport))
+        await page.waitForTimeout(FIRST_FRAME_MS)
+        if (timer == null) {
+            const still = await cdp.send('Page.captureScreenshot', { format: 'jpeg', quality: 90 })
+            if (timer == null) frame(Date.now() / 1000, Buffer.from(String(still['data']), 'base64'))
+        }
+        await stopped
+    } finally {
+        cdp.off('Page.screencastFrame', onFrame)
+        if (timer != null) clearTimeout(timer)
+        await cdp.send('Page.stopScreencast').catch(() => undefined)
+    }
+    put(tl.end(), last)
+    const broke = await writing.then(
+        () => null,
+        (e: unknown) => e,
+    )
+    await Promise.resolve(p.stdin.end()).catch(() => undefined)
+    const err = await stderr
+    if ((await p.exited) !== 0) throw ffmpegFailed(`encode → ${a.out}`, err, p.exitCode)
+    if (broke != null) throw broke instanceof Error ? broke : new Error(String(broke))
+    const dpr = a.dpr === 1 ? '' : ` (css pixels: the screencast ignores --dpr ${a.dpr})`
+    return `${tl.total} frames ${px}${dpr} at ${a.fps} fps from ${tl.shown} the page painted (${tl.realFps.toFixed(1)} fps), filmed by chromium's screencast, H.264 by ffmpeg`
+}

package/src/shot/shot-ask.ts

@@ -0,0 +1,189 @@
+// what a shot or a clip asks the warm shot service, and every pure rule about
+// it: the flags mapped to an ask, the ready mark read, the default file. No
+// browser, no disk, no process here: the suite tests all of it.
+import { join, resolve } from 'path'
+import { LAYOUT } from '../core/layout.ts'
+
+export type Viewport = { width: number; height: number }
+
+export type ShotAsk = {
+    url: string
+    viewport: Viewport
+    /** device pixel ratio: a png holds viewport × dpr pixels */
+    dpr: number
+    /** absolute: the service writes the file here */
+    out: string
+    /** load the page again even when the warm page already shows this url */
+    reload: boolean
+    /** a page with no ready mark is shot this long after its load (a warm page at once) */
+    waitMs: number
+}
+
+export type ClipAsk = ShotAsk & {
+    seconds: number
+    fps: number
+    /** film the page itself even when a canvas fills it (dom-clip.ts); a page with no big canvas is filmed so anyway */
+    dom?: boolean
+}
+
+export const DEFAULT_SHOT_PORT = 4796
+
+export const shotPort = (): number => {
+    const env = Number(process.env.SHIPKIT_SHOT_PORT)
+    return Number.isInteger(env) && env > 0 ? env : DEFAULT_SHOT_PORT
+}
+
+export const shotUrlBase = (port = shotPort()): string => `http://127.0.0.1:${port}`
+
+export const DEFAULT_VIEWPORT: Viewport = { width: 1280, height: 720 }
+export const DEFAULT_WAIT_MS = 300
+export const DEFAULT_FPS = 30
+/** a clip past this length needs `--long`: a long clip is a long wait and a big file */
+export const MAX_CLIP_SECONDS = 30
+
+/** `1280,720` or `1280x720` */
+export function parseViewport(s: string): Viewport {
+    const m = /^\s*(\d+)\s*[,x]\s*(\d+)\s*$/.exec(s)
+    const width = Number(m?.[1])
+    const height = Number(m?.[2])
+    if (!m || width < 16 || height < 16 || width > 7680 || height > 4320) throw new Error(`--viewport '${s}' is not w,h in pixels (16 to 7680 by 4320), like 1280,720`)
+    return { width, height }
+}
+
+/** a bare `localhost:5173/x` or `/x` against nothing reads as http */
+export function normalizeUrl(s: string): string {
+    const t = s.trim()
+    if (/^https?:\/\//.test(t)) return t
+    if (/^(localhost|127\.0\.0\.1|\[::1\]|[\w.-]+\.\w+)(:\d+)?(\/|$)/.test(t)) return `http://${t}`
+    if (/^:\d+(\/|$)/.test(t)) return `http://localhost${t}`
+    throw new Error(`'${s}' is not a url: give http://host:port/path, localhost:5173/path or :5173/path`)
+}
+
+/** the file a shot lands in when no `--out` is given: under the repo's local scratch, named after the url */
+export function defaultOut(url: string, ext: 'png' | 'mp4'): string {
+    const u = new URL(url)
+    const slug = `${u.hostname}-${u.port || (u.protocol === 'https:' ? '443' : '80')}${u.pathname}${u.search}${u.hash}`
+        .replace(/[^\w.-]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 80)
+    return join(LAYOUT.tmp, 'shots', `${slug}.${ext}`)
+}
+
+export type ShotFlags = {
+    url: string
+    viewport?: string
+    dpr?: string
+    out?: string
+    reload?: boolean
+    wait?: string
+    video?: string
+    fps?: string
+    long?: boolean
+    dom?: boolean
+}
+
+const positive = (flag: string, s: string, max: number): number => {
+    const n = Number(s)
+    if (!Number.isFinite(n) || n <= 0 || n > max) throw new Error(`${flag} '${s}' must be a number above 0 and at most ${max}`)
+    return n
+}
+
+/** the command line mapped to the ask the service runs: every default here, every refusal loud */
+export function askOf(f: ShotFlags, cwd: string): ShotAsk | ClipAsk {
+    const url = normalizeUrl(f.url)
+    const seconds = f.video == null ? null : positive('--video', f.video, 600)
+    if (seconds != null && seconds > MAX_CLIP_SECONDS && f.long !== true) throw new Error(`--video ${seconds}: a clip past ${MAX_CLIP_SECONDS} s needs --long (a long clip is a long wait and a big file)`)
+    if (seconds == null && f.fps != null) throw new Error('--fps only applies to a clip: add --video <seconds>')
+    if (seconds == null && f.dom === true) throw new Error('--dom only applies to a clip: add --video <seconds>')
+    const base: ShotAsk = {
+        url,
+        viewport: f.viewport == null ? DEFAULT_VIEWPORT : parseViewport(f.viewport),
+        dpr: f.dpr == null ? 1 : positive('--dpr', f.dpr, 4),
+        out: resolve(cwd, f.out ?? defaultOut(url, seconds == null ? 'png' : 'mp4')),
+        reload: f.reload === true,
+        waitMs: f.wait == null ? DEFAULT_WAIT_MS : f.wait === '0' ? 0 : positive('--wait', f.wait, 60_000),
+    }
+    if (seconds == null) return base
+    if (!base.out.endsWith('.mp4')) throw new Error(`--out '${f.out}': a clip is an mp4 (H.264)`)
+    return { ...base, seconds, fps: f.fps == null ? DEFAULT_FPS : positive('--fps', f.fps, 60), dom: f.dom === true }
+}
+
+export const isClip = (a: ShotAsk | ClipAsk): a is ClipAsk => 'seconds' in a
+
+/** a request held past this (a clip: past its own seconds) fails loud and frees the turn */
+export const REQUEST_MAX_MS = 120_000
+export const capMsOf = (a: ShotAsk | ClipAsk): number => REQUEST_MAX_MS + (isClip(a) ? a.seconds * 1000 : 0)
+
+// ── the ready mark ──────────────────────────────────────────────────────────
+// A page that knows when it is drawn says so: `<meta name="shot-ready"
+// content="wait">` in its head while it settles, `content="ready"` once it is
+// drawn. A page with the meta is shot the moment it says ready, and fails
+// loud at the cap when it never does. A page without it is shot `waitMs`
+// after its load.
+
+export type ReadyState = 'ready' | 'pending' | 'silent'
+
+/** what the page's meta says: null content means the page has no meta */
+export const readyOf = (content: string | null): ReadyState => (content == null ? 'silent' : content.trim().toLowerCase() === 'ready' ? 'ready' : 'pending')
+
+/** run IN the page: its source goes to the browser, so it reads nothing but the document */
+export const readMark = (): string | null => document.querySelector('meta[name="shot-ready"]')?.getAttribute('content') ?? (document.querySelector('meta[name="shot-ready"]') ? '' : null)
+
+export const READY_CAP_MS = 30_000
+const POLL_MS = 16
+
+export interface Clock {
+    now(): number
+    sleep(ms: number): Promise<void>
+}
+
+/** polls the page until it is ready to shoot: 'ready' once its mark says so, 'fallback' once a page with no mark had
+ *  its wait. A page whose mark never says ready fails loud at the cap */
+export async function waitReady(probe: () => Promise<string | null>, fallbackMs: number, clock: Clock, capMs = READY_CAP_MS): Promise<'ready' | 'fallback'> {
+    const t0 = clock.now()
+    for (;;) {
+        const s = readyOf(await probe())
+        if (s === 'ready') return 'ready'
+        const spent = clock.now() - t0
+        if (s === 'silent' && spent >= fallbackMs) return 'fallback'
+        if (s === 'pending' && spent >= capMs) throw new Error(`the page has <meta name="shot-ready"> and never set content="ready" in ${capMs / 1000} s`)
+        await clock.sleep(Math.min(POLL_MS, Math.max(1, (s === 'silent' ? fallbackMs : capMs) - spent)))
+    }
+}
+
+// ── the turn ────────────────────────────────────────────────────────────────
+
+/** one request at a time on the one warm page: a job runs once every job asked before it settled, and a job that
+ *  throws frees the turn like one that returns */
+export class Turns {
+    #tail: Promise<unknown> = Promise.resolve()
+    #waiting = 0
+
+    get waiting(): number {
+        return this.#waiting
+    }
+
+    run<T>(job: () => Promise<T>): Promise<T> {
+        this.#waiting++
+        const mine = this.#tail.then(
+            () => job(),
+            () => job(),
+        )
+        this.#tail = mine.then(
+            () => (this.#waiting--, undefined),
+            () => (this.#waiting--, undefined),
+        )
+        return mine
+    }
+}
+
+/** what the slot of the one warm page is keyed by: a request of another screen boots its own page */
+export const slotKey = (a: Pick<ShotAsk, 'viewport' | 'dpr'>): string => `${a.viewport.width}x${a.viewport.height}@${a.dpr}`
+
+/** what the warm page must do before a still: nothing, navigate, or reload */
+export function pageMove(current: { url: string; key: string } | null, a: ShotAsk): 'boot' | 'goto' | 'reload' | 'none' {
+    if (current == null || current.key !== slotKey(a)) return 'boot'
+    if (current.url !== a.url) return 'goto'
+    return a.reload ? 'reload' : 'none'
+}

package/src/shot/shot.shipkit.ts

@@ -0,0 +1,14 @@
+// the warm shot service as a machine process: pm keeps it up, and `sk shot`
+// starts it when it is down. One browser for every repo of the machine.
+import { join } from 'path'
+import { globalProcess } from '../shipkit-files.ts'
+import { shotUrlBase } from './shot-ask.ts'
+
+export default globalProcess({
+    id: 'shot',
+    label: 'shots',
+    description: 'warm headless browser: sk shot <url> gives a png, --video a clip, for every repo',
+    cmd: ['bun', join(import.meta.dir, 'serve-shot.ts')],
+    probe: `${shotUrlBase()}/health`,
+    icon: '📸',
+})

package/src/smoke/run-smoke.ts

@@ -262,14 +262,14 @@ export const PLAYWRIGHT_HINT = 'FAIL playwright is not installed in this repo
 
 /** resolved from the REPO, never from this package: the browser is the
  *  consumer's dependency, and the message names the two commands that fix it */
-export async function loadPlaywright(root: string): Promise<Playwright> {
+export async function loadPlaywright<T = Playwright>(root: string): Promise<T> {
     let resolved: string
     try {
         resolved = Bun.resolveSync('playwright', root)
     } catch {
         throw new Error(PLAYWRIGHT_HINT)
     }
-    return (await import(resolved)) as Playwright
+    return (await import(resolved)) as T
 }
 
 const isSelector = (spec: string): boolean => /^[#.[]/.test(spec) || /^[a-z][\w-]*(\[|:|$)/.test(spec) || spec.includes(' > ')

package/src/start-repo.ts

@@ -13,7 +13,8 @@ import { join } from 'path'
 import { ensureGitRepo, ensureIgnoreBaseline, firstGhLine, isScratch, publishRepo, runner, type Run } from './git-bootstrap.ts'
 import { initRepo } from './init-repo.ts'
 import { AGENT_LINE } from './checks/SK003-claude-md-shape.check.ts'
-import { adoptHouse, scaffoldProject, TOOLCHAIN } from './scaffold/project-scaffold.ts'
+import { adoptCli, adoptHouse, installedLib, scaffoldProject, TOOLCHAIN } from './scaffold/project-scaffold.ts'
+import { kitInstalled } from './scaffold/cli-skeleton.ts'
 import { defaultHubPort } from './serve/hub-port.ts'
 
 /** the one template: `shipkit start <name>` is the only thing anyone types,
@@ -53,6 +54,8 @@ export type StartOpts = {
     github?: boolean
     /** how `gh` runs — injected by tests, which never touch a real account */
     gh?: Run | null
+    /** a repo with history gets the project CLI skeleton too (a started repo always does) */
+    cli?: boolean
     /** how `bun` runs for the dep install — injected by tests, which never
      *  touch the network. An explicit null means no bun on this machine */
     bun?: Run | null
@@ -121,18 +124,6 @@ export async function startRepo(name: string, opts: StartOpts = {}): Promise<num
             // all (a downloaded template, one stray line) otherwise skipped
             // the baseline and refused the first commit over 7000 dep files
             ensureIgnoreBaseline(dir)
-            // the day-one shape: tsconfig, vscode tasks, the agent wiki, the
-            // verify skill. Create-only, so a dir that already holds any of
-            // them keeps its own. The .claude/ policy files ride on the
-            // include lines: a caller that declares a house gets the house
-            // defaults, a bare `shipkit start` never has its agent
-            // permissions widened by a scaffold
-            // the port comes from the name being WIRED, which is the one on the
-            // command line: init takes the caller's name over the manifest's,
-            // and a dir found holding a forked package.json carries a name
-            // nothing will listen on
-            try { scaffoldProject(dir, { name, port: defaultHubPort(name), print, claudePolicy: house.length > 0 }) }
-            catch (e) { console.error(`WARN scaffold incomplete in ${dir}: ${e instanceof Error ? e.message : String(e)} — the dir is still yours`) }
             // the wired scripts call node_modules binaries, so a scaffold
             // whose scripts exit 127 is not a started repo. Skips mirror the
             // github half's guards: an injected runner wins, the env switch
@@ -150,12 +141,36 @@ export async function startRepo(name: string, opts: StartOpts = {}): Promise<num
                 if (r.code === 0) console.error(`ok: installed ${deps.join(', ')}`)
                 else console.error(`WARN dependency install failed: ${firstGhLine(r.out)}`)
             }
+            // the day-one shape: tsconfig, vscode tasks, the agent wiki, the
+            // verify skill. Create-only, so a dir that already holds any of
+            // them keeps its own. The .claude/ policy files ride on the
+            // include lines: a caller that declares a house gets the house
+            // defaults, a bare `shipkit start` never has its agent
+            // permissions widened by a scaffold
+            // the port comes from the name being WIRED, which is the one on the
+            // command line: init takes the caller's name over the manifest's,
+            // and a dir found holding a forked package.json carries a name
+            // nothing will listen on
+            // The install runs first, so the project CLI is written only when the
+            // installed lib carries the kit its entry imports
+            const kit = kitInstalled(installedLib(dir))
+            if (kit === false) console.error(`skip: project CLI — the installed rvlib-shipkit ${installedLib(dir)?.version ?? ''} predates the CLI kit: \`sk start ${name} --cli\` once a release carries it`)
+            try { scaffoldProject(dir, { name, port: defaultHubPort(name), print, claudePolicy: house.length > 0, projectCli: kit !== false }) }
+            catch (e) { console.error(`WARN scaffold incomplete in ${dir}: ${e instanceof Error ? e.message : String(e)} — the dir is still yours`) }
         }
         // a repo with history that a house adopts: its own files win, and the
         // house half of the day-one shape lands beside them, so the include
         // lines below route at an agent wiki that exists
+        // the project CLI on an adopted repo is asked for, never implied: its
+        // src/cli.ts may be the product's own bin, or its CLI may live
+        // elsewhere. Before the house files, so a fresh agent index loads it
+        let cliWritten = false
+        if (wired && !startable && opts.cli === true) {
+            try { cliWritten = adoptCli(dir, { name, print }) != null }
+            catch (e) { console.error(`WARN could not write the project CLI in ${dir}: ${e instanceof Error ? e.message : String(e)} — the dir is still yours`) }
+        }
         if (wired && !startable && house.length > 0) {
-            try { adoptHouse(dir, { name, print }) }
+            try { adoptHouse(dir, { name, print, cli: cliWritten }) }
             catch (e) { console.error(`WARN could not seed the house files in ${dir}: ${e instanceof Error ? e.message : String(e)} — the dir is still yours`) }
         }
         let unscaffolded = false