rvlib-shipkit 2.1.0 → 2.2.0

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/shipkit-files.ts

@@ -6,13 +6,17 @@
 //                         supervises it, the home page switches it
 //   widget({...})         html the daemon renders every few seconds, mounted
 //                         on the home page
+//   trailer({...})        what `sk trailer` cannot read from a file: the
+//                         sounds the repo resolves by id (trailer/adapter.ts)
 //
 // the one constraint a reader breaks first: every kind is IMPORTED by the
 // process that reads it (discovery, pm's config child, the daemon), so a file
 // keeps its top level cheap and puts heavy work inside a function.
 import { check, type CheckDef } from './check.ts'
+import { trailer, type TrailerDef, type TrailerUnit } from './trailer/adapter.ts'
 
-export { check }
+export { check, trailer }
+export type { TrailerDef, TrailerUnit }
 
 /** one button beside a global process: a command, or a function of the file */
 export type ProcessAction = {
@@ -69,7 +73,7 @@ export type WidgetDef = {
 export type GlobalProcessUnit = GlobalProcessDef & { kind: 'globalProcess' }
 export type WidgetUnit = WidgetDef & { kind: 'widget' }
 
-export const UNIT_KINDS = ['globalProcess', 'widget'] as const
+export const UNIT_KINDS = ['globalProcess', 'widget', 'trailer'] as const
 
 const KEBAB = /^[a-z0-9][a-z0-9-]*$/
 const words = (v: unknown): boolean => Array.isArray(v) && v.length > 0 && v.every((w) => typeof w === 'string')
@@ -123,9 +127,9 @@ export function widget(d: WidgetDef): WidgetUnit {
 }
 
 /** the kind a default export says it is: a unit, else a check */
-export function unitKind(d: unknown): 'globalProcess' | 'widget' | 'check' {
+export function unitKind(d: unknown): 'globalProcess' | 'widget' | 'trailer' | 'check' {
     const k = (d as { kind?: unknown } | null)?.kind
-    return k === 'globalProcess' || k === 'widget' ? k : 'check'
+    return k === 'globalProcess' || k === 'widget' || k === 'trailer' ? k : 'check'
 }
 
 export type { CheckDef }

package/src/shot/client.ts

@@ -0,0 +1,67 @@
+// the one way code asks for a shot or a clip: `shotUrl` and `clipUrl` post to
+// the warm shot service (serve-shot.ts), start it through pm when it is down,
+// and shoot in process only when the machine has no pm (CI, SHIPKIT_NO_HOME).
+// `sk shot` and the trailer's `url` film both call these.
+import { DEFAULT_FPS, DEFAULT_VIEWPORT, DEFAULT_WAIT_MS, type ClipAsk, type ShotAsk, shotUrlBase, type Viewport } from './shot-ask.ts'
+import type { ShotDone } from './shooter.ts'
+
+/** the global process id pm knows the service by (shot.shipkit.ts) */
+export const SHOT_PROCESS = 'shot'
+
+export type ShotInput = { url: string; out: string; viewport?: Viewport; dpr?: number; reload?: boolean; waitMs?: number }
+export type ClipInput = ShotInput & { seconds: number; fps?: number; dom?: boolean }
+export type ShotResult = ShotDone & { via: 'warm' | 'started' | 'local' }
+
+const shotAsk = (i: ShotInput): ShotAsk => ({
+    url: i.url,
+    out: i.out,
+    viewport: i.viewport ?? DEFAULT_VIEWPORT,
+    dpr: i.dpr ?? 1,
+    reload: i.reload ?? false,
+    waitMs: i.waitMs ?? DEFAULT_WAIT_MS,
+})
+
+/** a png of `url` at `out` (absolute), through the warm browser */
+export const shotUrl = (i: ShotInput, log: (l: string) => void = () => {}): Promise<ShotResult> => ask('/shot', shotAsk(i), log)
+
+/** an mp4 of `seconds` of `url` at `out` (absolute): a page that is a canvas through its WebCodecs, any other page (or
+ *  `dom`) as chromium paints it */
+export const clipUrl = (i: ClipInput, log: (l: string) => void = () => {}): Promise<ShotResult> =>
+    ask('/clip', { ...shotAsk(i), seconds: i.seconds, fps: i.fps ?? DEFAULT_FPS, dom: i.dom ?? false } satisfies ClipAsk, log)
+
+/** null when nothing listens (start it), else the service's answer; a refusal throws its reason */
+async function post(route: string, a: ShotAsk): Promise<ShotDone | null> {
+    let r: Response
+    try {
+        r = await fetch(`${shotUrlBase()}${route}`, { method: 'POST', body: JSON.stringify(a), headers: { 'content-type': 'application/json' } })
+    } catch {
+        return null
+    }
+    if (!r.ok) throw new Error(await r.text())
+    return (await r.json()) as ShotDone
+}
+
+async function ask(route: '/shot' | '/clip', a: ShotAsk | ClipAsk, log: (l: string) => void): Promise<ShotResult> {
+    const warm = await post(route, a)
+    if (warm != null) return { ...warm, via: 'warm' }
+    const { pmUp, pmUrl } = await import('../home/home-paths.ts')
+    if (process.env['CI'] == null && process.env['SHIPKIT_NO_HOME'] == null && (await pmUp())) {
+        log(`shot: starting the shot service (sk gp start ${SHOT_PROCESS})`)
+        const { pmSwitchDeps, switchProcess } = await import('../cli/cmd_GlobalProcesses.ts')
+        const code = await switchProcess(SHOT_PROCESS, 'start', pmSwitchDeps(log, pmUrl()), 60_000)
+        if (code !== 0) throw new Error(`the shot service did not start through pm: sk gp shows where it stands`)
+        const started = await post(route, a)
+        if (started == null) throw new Error(`pm says the shot service is up and nothing answers on ${shotUrlBase()}`)
+        return { ...started, via: 'started' }
+    }
+    log('shot: no pm on this machine, shooting in process (a cold browser)')
+    const { Shooter } = await import('./shooter.ts')
+    const { dirname } = await import('path')
+    const s = new Shooter([process.cwd(), dirname(import.meta.dir)])
+    try {
+        const done = route === '/clip' ? await s.clip(a as ClipAsk) : await s.shot(a)
+        return { ...done, via: 'local' }
+    } finally {
+        await s.close()
+    }
+}

package/src/shot/clip-encoder.ts

@@ -0,0 +1,146 @@
+// a clip filmed by the page itself: each frame of its largest canvas goes to
+// the page's WebCodecs encoder (H.264, the media engine) on the page's own
+// animation frames, in real time, and the stream comes back in takes of at
+// most TAKE bytes, never whole (one answer of a long clip's base64 can close
+// the browser). ffmpeg then muxes it into an mp4 with no second encode.
+//
+// the constraint a reader breaks first: `installClip`, `takeClip` and
+// `CLIP_INIT` run IN the page, so they import nothing and read only their
+// argument and the document. A WebGL canvas keeps no drawing buffer after it
+// presents, so the clip's page is opened with CLIP_INIT, which asks every
+// WebGL context for `preserveDrawingBuffer`.
+
+/** what the page films: seconds of its largest canvas at fps, H.264 at a fixed quantizer */
+export type PageClipAsk = { seconds: number; fps: number; quantizer: number; keyEvery: number }
+
+/** what the page says once the film ran */
+export type PageClipDone = { frames: number; repeated: number; width: number; height: number; canvasOfViewport: string }
+
+/** IN THE PAGE, as an init script: every WebGL context keeps its drawing buffer, so a frame reads back after it presents */
+export const CLIP_INIT = `(() => {
+    const get = HTMLCanvasElement.prototype.getContext
+    HTMLCanvasElement.prototype.getContext = function (type, attrs) {
+        if (type === 'webgl' || type === 'webgl2' || type === 'experimental-webgl') attrs = Object.assign({}, attrs, { preserveDrawingBuffer: true })
+        return get.call(this, type, attrs)
+    }
+})()`
+
+type ClipState = {
+    chunks: Uint8Array[]
+    next: number
+    failed: string | null
+    done: Promise<PageClipDone>
+}
+
+/** IN THE PAGE: starts filming the largest visible canvas; null once it films, else why it cannot */
+export async function installClip(a: PageClipAsk): Promise<string | null> {
+    const w = window as unknown as { __skClip?: ClipState }
+    if (typeof VideoEncoder === 'undefined') return 'this page has no WebCodecs (VideoEncoder)'
+    const canvases = [...document.querySelectorAll('canvas')].filter((c) => c.width > 0 && c.height > 0 && c.getBoundingClientRect().width > 0)
+    const canvas = canvases.sort((x, y) => y.width * y.height - x.width * x.height)[0]
+    if (canvas == null) return 'the page draws no visible <canvas>: a clip films the page\'s canvas through WebCodecs'
+    const even = (v: number): number => Math.max(2, 2 * Math.floor(v / 2))
+    const width = even(canvas.width)
+    const height = even(canvas.height)
+    const blocks = Math.ceil(width / 16) * Math.ceil(height / 16)
+    const level = blocks <= 8192 ? '28' : blocks <= 36864 ? '33' : '34'
+    const config: VideoEncoderConfig = {
+        codec: `avc1.6400${level}`,
+        width,
+        height,
+        framerate: a.fps,
+        latencyMode: 'quality',
+        bitrateMode: 'quantizer',
+        hardwareAcceleration: 'prefer-hardware',
+        avc: { format: 'annexb' },
+    }
+    if (!(await VideoEncoder.isConfigSupported(config)).supported) return `the page's H.264 encoder takes no ${width}x${height} at a fixed quantizer`
+    const box = canvas.getBoundingClientRect()
+    const canvasOfViewport = `${Math.round(box.width)}x${Math.round(box.height)} css px of ${innerWidth}x${innerHeight}`
+    const st: ClipState = { chunks: [], next: 0, failed: null, done: Promise.resolve({ frames: 0, repeated: 0, width, height, canvasOfViewport }) }
+    const enc = new VideoEncoder({
+        output: (chunk) => {
+            const b = new Uint8Array(chunk.byteLength)
+            chunk.copyTo(b)
+            st.chunks.push(b)
+        },
+        error: (e) => (st.failed = `the page's encoder failed: ${e.message}`),
+    })
+    enc.configure(config)
+    const total = Math.round(a.seconds * a.fps)
+    const step = 1000 / a.fps
+    const rect = { x: 0, y: 0, width, height }
+    st.done = new Promise<PageClipDone>((ok, fail) => {
+        let n = 0
+        let repeated = 0
+        let t0 = -1
+        const tick = (t: number): void => {
+            try {
+                if (st.failed) throw new Error(st.failed)
+                if (t0 < 0) t0 = t
+                // a frame for every step of real time passed: a slow page repeats its last drawing, so the clip keeps its length
+                let made = 0
+                while (n < total && n * step <= t - t0) {
+                    const frame = new VideoFrame(canvas, { timestamp: Math.round(n * step * 1000), duration: Math.round(step * 1000), visibleRect: rect })
+                    enc.encode(frame, { keyFrame: n % a.keyEvery === 0, avc: { quantizer: a.quantizer } } as VideoEncoderEncodeOptions)
+                    frame.close()
+                    if (made++ > 0) repeated++
+                    n++
+                }
+                if (n < total) requestAnimationFrame(tick)
+                else
+                    void enc
+                        .flush()
+                        .then(() => {
+                            enc.close()
+                            if (st.failed) throw new Error(st.failed)
+                            ok({ frames: n, repeated, width, height, canvasOfViewport })
+                        })
+                        .catch(fail)
+            } catch (e) {
+                if (enc.state !== 'closed') enc.close()
+                fail(e)
+            }
+        }
+        requestAnimationFrame(tick)
+    })
+    // a rejection is read by `clipDone`, never left unhandled in the page
+    st.done.catch(() => undefined)
+    w.__skClip = st
+    return null
+}
+
+/** IN THE PAGE: the stream made since the last take, at most `max` bytes (whole chunks, one at least), base64; '' when
+ *  none waits */
+export async function takeClip(max: number): Promise<string> {
+    const st = (window as unknown as { __skClip: ClipState }).__skClip
+    if (st.failed) throw new Error(st.failed)
+    const from = st.next
+    let bytes = 0
+    while (st.next < st.chunks.length && (st.next === from || bytes + st.chunks[st.next]!.byteLength <= max)) bytes += st.chunks[st.next++]!.byteLength
+    if (st.next === from) return ''
+    const part = st.chunks.slice(from, st.next)
+    for (let i = from; i < st.next; i++) st.chunks[i] = new Uint8Array(0)
+    const url = await new Promise<string>((ok, fail) => {
+        const r = new FileReader()
+        r.onload = () => ok(String(r.result))
+        r.onerror = () => fail(new Error('the stream did not read back'))
+        r.readAsDataURL(new Blob(part as BlobPart[]))
+    })
+    return url.slice(url.indexOf(',') + 1)
+}
+
+/** IN THE PAGE: resolves once the film ran and the encoder flushed */
+export const clipDone = (): Promise<PageClipDone> => (window as unknown as { __skClip: ClipState }).__skClip.done
+
+/** the most stream one take carries, bytes: its base64 is a third more */
+export const TAKE = 8 << 20
+
+/** H.264's quantizer, 0 to 51, lower is better: 24 films a UI or a 3D scene sharp at a few MB a minute */
+export const CLIP_QUANTIZER = 24
+
+/** a key frame a second at 30 fps: a cut into the footage seeks no further back than that */
+export const KEY_EVERY = 30
+
+/** ffmpeg's arguments to mux a raw H.264 stream (stdin) into an mp4, no second encode */
+export const muxArgs = (fps: number, out: string): string[] => ['-hide_banner', '-nostdin', '-y', '-loglevel', 'error', '-fflags', '+genpts', '-r', String(fps), '-f', 'h264', '-i', 'pipe:0', '-c:v', 'copy', '-movflags', '+faststart', out]

package/src/shot/dom-clip.ts

@@ -0,0 +1,124 @@
+// a clip of the page itself, for a page the canvas path cannot film: chromium
+// sends each painted frame of the page (CDP `Page.startScreencast`, jpeg),
+// `FrameTimeline` lays them on the clip's fixed frame grid (a frame holds
+// until the next one paints, so a still page still fills its seconds), and
+// ffmpeg encodes the grid to H.264 as the frames arrive.
+//
+// measured against Playwright's `recordVideo` on a 3 s animated page: 60
+// painted frames a second and 90 of 90 distinct frames in the mp4, against
+// 65 of 89 for recordVideo (25 fps vp8, then a second encode to trim it).
+//
+// the constraint a reader breaks first: the screencast must take EVERY frame
+// (`everyNthFrame: 1`). Every second frame drops 6 to 21 distinct frames of
+// 90, because its arrival jitter beats against the clip's grid.
+import type { Viewport } from './shot-ask.ts'
+
+export type ClipPath = 'canvas' | 'dom'
+
+/** css box of the page's largest visible canvas, the one the canvas path would film */
+export type CanvasBox = { width: number; height: number }
+
+/** a canvas this share of the viewport or more is the page: the canvas path films it. Under it, the page is DOM with
+ *  a canvas in it (a chart, a sparkline), and filming the canvas alone would drop the page */
+export const CANVAS_SHARE = 0.5
+
+export function clipPathOf(o: { dom: boolean; canvas: CanvasBox | null; viewport: Viewport }): ClipPath {
+    if (o.dom || o.canvas == null) return 'dom'
+    return o.canvas.width * o.canvas.height >= CANVAS_SHARE * o.viewport.width * o.viewport.height ? 'canvas' : 'dom'
+}
+
+/** IN THE PAGE: the css box of the largest visible canvas by drawing buffer (installClip's pick), null when none */
+export const largestCanvas = (): CanvasBox | null => {
+    const c = [...document.querySelectorAll('canvas')].filter((x) => x.width > 0 && x.height > 0 && x.getBoundingClientRect().width > 0).sort((x, y) => y.width * y.height - x.width * x.height)[0]
+    if (c == null) return null
+    const r = c.getBoundingClientRect()
+    return { width: r.width, height: r.height }
+}
+
+/** the screencast request: every frame, jpeg. Its frames are css pixels whatever the device pixel ratio */
+export const screencastParams = (viewport: Viewport): Record<string, unknown> => ({
+    format: 'jpeg',
+    quality: 90,
+    maxWidth: viewport.width,
+    maxHeight: viewport.height,
+    everyNthFrame: 1,
+})
+
+/** the painted frames on the clip's fixed grid of `fps` × `seconds` slots. Slot i shows the last frame painted at or
+ *  before i / fps, timed from the first frame */
+export class FrameTimeline {
+    readonly total: number
+    #filled = 0
+    #t0: number | null = null
+    #shown = 0
+
+    constructor(
+        readonly fps: number,
+        readonly seconds: number,
+    ) {
+        this.total = Math.round(seconds * fps)
+    }
+
+    /** a frame painted at `t` seconds (any clock, the same for every frame): how many slots the PREVIOUS frame fills,
+     *  and whether this frame lands past the clip's end (it is then dropped) */
+    arrive(t: number): { previous: number; past: boolean } {
+        this.#t0 ??= t
+        const rel = t - this.#t0
+        const upTo = Math.min(this.total, Math.ceil(rel * this.fps))
+        const previous = this.#shown === 0 ? 0 : Math.max(0, upTo - this.#filled)
+        this.#filled += previous
+        const past = rel >= this.seconds
+        if (!past) this.#shown++
+        return { previous, past }
+    }
+
+    /** the slots the last frame fills once filming stops, so the clip is exactly `seconds` long */
+    end(): number {
+        if (this.#shown === 0) return 0
+        const rest = this.total - this.#filled
+        this.#filled = this.total
+        return rest
+    }
+
+    /** distinct frames the page painted inside the clip */
+    get shown(): number {
+        return this.#shown
+    }
+
+    /** the page's own frame rate over the clip */
+    get realFps(): number {
+        return this.#shown / this.seconds
+    }
+}
+
+/** ffmpeg's arguments: a stream of jpegs (stdin) at `fps` into an H.264 mp4 of exactly `frames` frames */
+export const domEncodeArgs = (fps: number, frames: number, out: string): string[] => [
+    '-hide_banner',
+    '-nostdin',
+    '-y',
+    '-loglevel',
+    'error',
+    '-f',
+    'image2pipe',
+    '-framerate',
+    String(fps),
+    '-c:v',
+    'mjpeg',
+    '-i',
+    'pipe:0',
+    '-vf',
+    'scale=trunc(iw/2)*2:trunc(ih/2)*2',
+    '-frames:v',
+    String(frames),
+    '-c:v',
+    'libx264',
+    '-preset',
+    'veryfast',
+    '-crf',
+    '20',
+    '-pix_fmt',
+    'yuv420p',
+    '-movflags',
+    '+faststart',
+    out,
+]

package/src/shot/serve-shot.ts

@@ -0,0 +1,54 @@
+// the warm shot service, the `shot` global process pm keeps up: an http
+// door on 127.0.0.1 over one Shooter. `sk shot` and `shotUrl` post an ask
+// and get back where the file landed. The browser launches on the first
+// ask and closes after BROWSER_IDLE_MS; this process itself stays, idle.
+import { dirname } from 'path'
+import { LIB_VERSION } from '../core/lib-version.ts'
+import { type ClipAsk, isClip, type ShotAsk, shotPort } from './shot-ask.ts'
+import { Shooter } from './shooter.ts'
+
+export const SHOT_SERVICE = 'shipkit-shot'
+
+export function serveShots(port = shotPort(), roots = [process.cwd(), dirname(import.meta.dir)]): { stop(): Promise<void> } {
+    const shooter = new Shooter(roots)
+    const server = Bun.serve({
+        hostname: '127.0.0.1',
+        port,
+        idleTimeout: 0,
+        async fetch(req) {
+            const path = new URL(req.url).pathname
+            if (req.method === 'GET' && path === '/health') return Response.json({ service: SHOT_SERVICE, version: LIB_VERSION, pid: process.pid, ...shooter.warm })
+            if (req.method === 'POST' && (path === '/shot' || path === '/clip')) {
+                let a: ShotAsk | ClipAsk
+                try {
+                    a = (await req.json()) as ShotAsk | ClipAsk
+                } catch {
+                    return new Response('the ask is not json', { status: 400 })
+                }
+                if (typeof a?.url !== 'string' || typeof a.out !== 'string' || !a.out.startsWith('/')) return new Response('an ask needs url and an absolute out', { status: 400 })
+                try {
+                    const done = path === '/clip' ? (isClip(a) ? await shooter.clip(a) : null) : await shooter.shot(a)
+                    if (done == null) return new Response('a clip ask needs seconds and fps', { status: 400 })
+                    return Response.json(done)
+                } catch (e) {
+                    return new Response((e as Error).message ?? String(e), { status: 500 })
+                }
+            }
+            return new Response('not found: GET /health, POST /shot, POST /clip', { status: 404 })
+        },
+    })
+    return {
+        async stop() {
+            await shooter.close()
+            void server.stop(true)
+        },
+    }
+}
+
+if (import.meta.main) {
+    const s = serveShots()
+    console.log(`ok shots on 127.0.0.1:${shotPort()}`)
+    const bye = (): void => void s.stop().finally(() => process.exit(0))
+    process.on('SIGTERM', bye)
+    process.on('SIGINT', bye)
+}