rvlib-shipkit 0.1.1 → 0.3.0

package/src/assets/kit-config.ts

@@ -0,0 +1,179 @@
+// defineKit — the repo-side surface: .rv-assets/kit.ts declares asset kinds,
+// generators, ship targets and metadata panels; the studio/CLI derive
+// everything else. STRUCTURE lives here (git-reviewed TS); studio-edited
+// state lives in the workspace overlays (pick.json, prompt.json, *.rect.json).
+// Kit edits need a studio restart; prompt tweaks don't (overlay).
+import { existsSync } from 'fs'
+import { join } from 'path'
+import type { alphaHeight, toPng } from './image-ops.ts'
+import type { GroundRect } from './panels/geometry-rects.ts'
+
+export type AssetSpec = {
+    id: string
+    /** FULL prompt text incl. style — the studio shows/edits exactly what generates */
+    prompt: string
+    label?: string
+    /** freeform data passed through to the ship hook */
+    ship?: unknown
+}
+
+export type ComfyGen = { backend: 'comfy'; workflow?: string; bg?: string }
+export type CanvasGen = { backend: 'canvas'; draw: (ctx: unknown, asset: AssetSpec) => void | Promise<void> }
+export type GeneratorSpec = ComfyGen | CanvasGen
+export const comfy = (p?: { workflow?: string; bg?: string }): ComfyGen => ({ backend: 'comfy', workflow: p?.workflow, bg: p?.bg })
+export const canvas = (draw: CanvasGen['draw']): CanvasGen => ({ backend: 'canvas', draw })
+
+export type GeometryPanelSpec = {
+    panel: 'geometry'
+    /** oval height = width × ratio, ratio OWNED by the repo (mirror of its game constant) */
+    ratio: number
+    /** default oval when an asset has no saved rect yet */
+    defaultOval: { x: number; y: number; w: number; size: number }
+    /** per-category default size overrides */
+    sizeByCategory?: Record<string, number>
+    legs?: boolean
+}
+export type GridPanelSpec = { panel: 'grid'; fields: ('size' | 'flip')[] }
+/** Repo-defined metadata editor: an ES module the studio serves at
+ *  GET /panel/<kindId>/<id>.js and mounts per asset —
+ *  `export function mount(el, api)` (+ optional `unmount()`), api =
+ *  { assetId, kindId, roll, imgUrl, getMeta(), saveMeta(json) } backed by
+ *  the roll's meta sidecar. Geometry/grid stay baked-in; this is the
+ *  escape hatch for ANY other metadata shape. */
+export type CustomPanelSpec = {
+    panel: 'custom'
+    /** url-safe kebab-case, unique per kind — becomes the served module name */
+    id: string
+    /** repo-root-relative ES module path (e.g. .rv-assets/panels/legs-editor.js) */
+    script: string
+}
+export type PanelSpec = GeometryPanelSpec | GridPanelSpec | CustomPanelSpec
+export const geometryPanel = (p: Omit<GeometryPanelSpec, 'panel'>): GeometryPanelSpec => ({ panel: 'geometry', ...p })
+export const gridPanel = (p: Omit<GridPanelSpec, 'panel'>): GridPanelSpec => ({ panel: 'grid', ...p })
+export const customPanel = (p: Omit<CustomPanelSpec, 'panel'>): CustomPanelSpec => ({ panel: 'custom', ...p })
+
+export type KindMeta = {
+    /** live write-through target, repo-root-relative (e.g. assets/heroes/ground-rects.json) */
+    file?: string
+    panels?: PanelSpec[]
+    /** ships to an art-normalized folder: sizes are in art-height units */
+    artNormalized?: boolean
+    /** repo-owned semantics gate, run before any metadata write-through —
+     *  return error strings to reject the write (loud, never silent) */
+    validate?: (data: unknown) => string[] | void
+}
+
+/** What a ship hook receives when a roll is picked (studio /api/pick). */
+export type ShipContext = {
+    assetId: string
+    file: string
+    asset: AssetSpec
+    kind: Kind
+    meta: unknown
+    rect: GroundRect | null
+    projectRoot: string
+    img: { toPng: typeof toPng; alphaHeight: typeof alphaHeight }
+}
+export type ShipFn = (ctx: ShipContext) => Promise<string | void>
+
+export type Kind = {
+    id: string
+    category: string
+    assets: AssetSpec[]
+    generate: GeneratorSpec
+    /** icon kinds get no geometry, thumbnails only */
+    mode?: 'sprite' | 'icon'
+    /** via = repo hook module path (default .rv-assets/ship.ts) · fn = a
+     *  built-in lib hook (e.g. identityKinds re-rendering the set) — never both */
+    ship?: { dir?: string; via?: string; fn?: ShipFn }
+    meta?: KindMeta
+}
+
+export type KitConfig = {
+    port?: number
+    /** roll workspace root, repo-root-relative; gitignored */
+    workspace?: string
+    comfy?: { host: string; workflows: string; heal?: string }
+    kinds: Kind[]
+}
+
+export type ResolvedKit = KitConfig & { port: number; workspace: string }
+
+export function validateKit(k: KitConfig): string[] {
+    const errs: string[] = []
+    if (!Array.isArray(k.kinds) || k.kinds.length === 0) errs.push('kinds must be a non-empty array')
+    const kindIds = new Set<string>()
+    const assetIds = new Set<string>()
+    for (const kind of k.kinds ?? []) {
+        if (!kind.id || !kind.category) errs.push(`kind needs id + category (got ${JSON.stringify({ id: kind.id, category: kind.category })})`)
+        if (kindIds.has(kind.id)) errs.push(`duplicate kind id '${kind.id}'`)
+        kindIds.add(kind.id)
+        if (kind.generate?.backend === 'comfy' && k.comfy == null) errs.push(`kind '${kind.id}' uses the comfy backend but the kit has no comfy config`)
+        if (kind.ship?.fn != null && kind.ship?.via != null) errs.push(`kind '${kind.id}': ship.fn and ship.via are two hooks for one pick — keep one`)
+        if (!Array.isArray(kind.assets) || kind.assets.length === 0) errs.push(`kind '${kind.id}' has no assets — a silent no-op kind is a config mistake`)
+        for (const a of kind.assets ?? []) {
+            if (!a.id || typeof a.prompt !== 'string') errs.push(`kind '${kind.id}': asset needs id + prompt (got ${JSON.stringify(a).slice(0, 80)})`)
+            if (assetIds.has(a.id)) errs.push(`duplicate asset id '${a.id}' (ids are global across kinds)`)
+            assetIds.add(a.id)
+        }
+        const panelIds = new Set<string>()
+        for (const p of kind.meta?.panels ?? []) {
+            if (p.panel !== 'custom') continue
+            if (!/^[a-z0-9][a-z0-9-]*$/.test(p.id ?? '')) errs.push(`kind '${kind.id}': custom panel id must be url-safe kebab-case (got '${p.id}')`)
+            if (panelIds.has(p.id)) errs.push(`kind '${kind.id}': duplicate custom panel id '${p.id}'`)
+            panelIds.add(p.id)
+            if (typeof p.script !== 'string' || p.script === '') errs.push(`kind '${kind.id}' panel '${p.id}': script path required (repo-root-relative ES module)`)
+            else if (p.script.startsWith('/') || p.script.split('/').includes('..'))
+                errs.push(`kind '${kind.id}' panel '${p.id}': script must be repo-root-relative without '..' (got '${p.script}')`)
+        }
+    }
+    return errs
+}
+
+/** Custom panel scripts that don't exist on disk — checked at kit load AND
+ *  studio boot so a typo'd path dies loud, never as a silent 404 in the SPA. */
+export function missingPanelScripts(kit: KitConfig, root: string): string[] {
+    const missing: string[] = []
+    for (const kind of kit.kinds) {
+        for (const p of kind.meta?.panels ?? []) {
+            if (p.panel !== 'custom') continue
+            if (!existsSync(join(root, p.script))) missing.push(`kind '${kind.id}' panel '${p.id}': ${p.script} not found under ${root}`)
+        }
+    }
+    return missing
+}
+
+export function defineKit(k: KitConfig): ResolvedKit {
+    const errs = validateKit(k)
+    if (errs.length > 0) throw new Error(`invalid kit:\n  ${errs.join('\n  ')}`)
+    return { ...k, port: k.port ?? 4800, workspace: k.workspace ?? '.rv-assets/out' }
+}
+
+export const defineKind = (k: Kind): Kind => k
+
+export async function loadKit(root: string): Promise<ResolvedKit> {
+    const path = join(root, '.rv-assets/kit.ts')
+    if (!existsSync(path)) throw new Error(`no .rv-assets/kit.ts in ${root} — create one (defineKit) or run the init snippet from the docs`)
+    const mod = (await import(path)) as { default?: ResolvedKit }
+    if (mod.default == null) throw new Error(`${path}: must default-export defineKit({...})`)
+    const missing = missingPanelScripts(mod.default, root)
+    if (missing.length > 0) throw new Error(`kit custom panel scripts missing — create them or fix the paths:\n  ${missing.join('\n  ')}`)
+    return mod.default
+}
+
+// ── lookups shared by server + CLI ──────────────────────────────────────────
+export type FoundAsset = { kind: Kind; asset: AssetSpec }
+
+export function findAsset(kit: KitConfig, assetId: string): FoundAsset | null {
+    for (const kind of kit.kinds) {
+        const asset = kind.assets.find((a) => a.id === assetId)
+        if (asset != null) return { kind, asset }
+    }
+    return null
+}
+
+export function allAssets(kit: KitConfig): FoundAsset[] {
+    return kit.kinds.flatMap((kind) => kind.assets.map((asset) => ({ kind, asset })))
+}
+
+export const categoriesOf = (kit: KitConfig): string[] => [...new Set(kit.kinds.map((k) => k.category))]

package/src/assets/kits/identity-kit.ts

@@ -0,0 +1,119 @@
+// kits/identity — favicon / logo / OG as asset kinds. One render path
+// (renderIdentityFromMark: mark png → logo master 1024², favicon 512², og
+// card), two ways to get the mark:
+// - canvas mark: deterministic, instant — `shipkit assets identity` draws it
+//   headlessly and renders the set.
+// - comfy mark: roll-and-pick in the studio; the kind carries a BUILT-IN ship
+//   hook, so picking a logo roll re-renders the whole identity set from the
+//   picked png. Headless `identity` uses the current pick — no pick yet is a
+//   loud FAIL, never a placeholder.
+// Outputs are COMMITTED: public/favicon.png (512² master), public/og.png
+// (1200×630), public/logo.png. Brand data is per-repo and never defaults
+// across repos.
+import { createCanvas, loadImage, type Image, type SKRSContext2D } from '@napi-rs/canvas'
+import { mkdirSync } from 'fs'
+import { dirname, join } from 'path'
+import sharp from 'sharp'
+import { defineKind, type CanvasGen, type ComfyGen, type Kind } from '../kit-config.ts'
+
+export type Brand = {
+    name: string
+    tagline?: string
+    /** background / accent / ink — used by the default og layout */
+    palette: { bg: string; accent: string; ink: string }
+    /** the mark: a canvas draw (deterministic) or a comfy generator (roll-and-pick) */
+    mark: CanvasGen | ComfyGen
+    /** comfy marks: the FULL generation prompt for identity-logo rolls
+     *  (style included — the studio shows/edits exactly this) */
+    markPrompt?: string
+    /** og layout hook — replaces the WHOLE default card (bg + mark left +
+     *  name/tagline right); the hook owns compositing the mark if it wants one */
+    drawOg?: (ctx: SKRSContext2D, brand: Brand, size: { w: number; h: number }) => void
+}
+
+export const FAVICON_SIZE = 512
+export const OG_W = 1200
+export const OG_H = 630
+export const LOGO_SIZE = 1024
+
+/** the one next step when a comfy mark has no picked roll yet */
+export const NO_PICK_FIX = 'roll + pick in the studio: bun run assets → #identity-logo'
+
+export function identityKinds(brand: Brand): Kind[] {
+    return [
+        defineKind({
+            id: 'identity-logo', category: 'Identity', mode: 'icon',
+            assets: [{ id: 'identity-logo', prompt: brand.markPrompt ?? `logo mark for ${brand.name}`, label: 'logo' }],
+            generate: brand.mark,
+            // built-in ship: picking a logo roll re-renders the WHOLE identity set
+            ship: { fn: async (ctx) => (await renderIdentityFromMark(brand, ctx.projectRoot, await sharp(ctx.file).png().toBuffer())).join(' + ') },
+        }),
+    ]
+}
+
+// shrink px until text fits maxW (og cards must never clip the tagline)
+const fitFont = (ctx: SKRSContext2D, text: string, px: number, maxW: number, bold = false): void => {
+    for (; px > 12; px -= 2) {
+        ctx.font = `${bold ? 'bold ' : ''}${px}px sans-serif`
+        if (ctx.measureText(text).width <= maxW) return
+    }
+}
+
+const defaultOg = (ctx: SKRSContext2D, brand: Brand, size: { w: number; h: number }, mark: Image): void => {
+    ctx.fillStyle = brand.palette.bg
+    ctx.fillRect(0, 0, size.w, size.h)
+    ctx.fillStyle = brand.palette.accent
+    ctx.fillRect(0, size.h - 14, size.w, 14)
+    const pad = 72
+    const markSize = size.h - pad * 2
+    ctx.drawImage(mark, pad, pad, markSize, markSize)
+    const textX = pad + markSize + 64
+    const maxW = size.w - textX - 48
+    ctx.fillStyle = brand.palette.ink
+    fitFont(ctx, brand.name, Math.round(size.h / 6), maxW, true)
+    ctx.textBaseline = 'middle'
+    ctx.fillText(brand.name, textX, size.h / 2 - (brand.tagline != null ? size.h / 12 : 0))
+    if (brand.tagline != null) {
+        ctx.fillStyle = brand.palette.accent
+        fitFont(ctx, brand.tagline, Math.round(size.h / 14), maxW)
+        ctx.fillText(brand.tagline, textX + 2, size.h / 2 + size.h / 9)
+    }
+}
+
+/** THE identity writer — any mark png (canvas draw or picked comfy roll) →
+ *  public/logo.png (1024² master) + public/favicon.png (512² resize) +
+ *  public/og.png (default card: bg + mark left + name/tagline right). */
+export async function renderIdentityFromMark(brand: Brand, root: string, markPng: Buffer): Promise<string[]> {
+    const out: string[] = []
+    const write = async (rel: string, buf: Buffer): Promise<void> => {
+        const path = join(root, rel)
+        mkdirSync(dirname(path), { recursive: true })
+        await Bun.write(path, buf)
+        out.push(rel)
+    }
+    const logoPng = await sharp(markPng)
+        .resize(LOGO_SIZE, LOGO_SIZE, { fit: 'contain', background: { r: 0, g: 0, b: 0, alpha: 0 } })
+        .png().toBuffer()
+    await write('public/logo.png', logoPng)
+    // favicon = logo master resized to 512² (browsers derive the rest)
+    await write('public/favicon.png', await sharp(logoPng).resize(FAVICON_SIZE, FAVICON_SIZE).png().toBuffer())
+    const og = createCanvas(OG_W, OG_H)
+    const ctx = og.getContext('2d')
+    if (brand.drawOg != null) brand.drawOg(ctx, brand, { w: OG_W, h: OG_H })
+    else defaultOg(ctx, brand, { w: OG_W, h: OG_H }, await loadImage(logoPng))
+    await write('public/og.png', og.toBuffer('image/png'))
+    return out
+}
+
+/** Headless render of the full identity set. Canvas marks draw themselves;
+ *  comfy marks need `markFile` = the PICKED roll (the caller resolves the
+ *  pick — run-assets does) and FAIL loud without one. */
+export async function renderIdentity(brand: Brand, root: string, opts?: { markFile?: string }): Promise<string[]> {
+    if (brand.mark.backend === 'canvas') {
+        const logo = createCanvas(LOGO_SIZE, LOGO_SIZE)
+        await brand.mark.draw(logo.getContext('2d'), { id: 'identity-logo', prompt: '' })
+        return renderIdentityFromMark(brand, root, logo.toBuffer('image/png'))
+    }
+    if (opts?.markFile == null) throw new Error(`brand '${brand.name}' uses a comfy mark and no roll is picked — ${NO_PICK_FIX}`)
+    return renderIdentityFromMark(brand, root, await sharp(opts.markFile).png().toBuffer())
+}

package/src/assets/native-deps.ts

@@ -0,0 +1,18 @@
+// Native-dep readiness probes for the asset generators. These MUST live in the
+// lib so the `@napi-rs/canvas` / `sharp` specifiers resolve against the lib's
+// node_modules (the same way the generators do) — a repo probing from its own
+// root would false-negative. Each not only resolves the module but exercises
+// the native binding (a present-but-ABI-broken .node passes resolution yet
+// dies at first generate — the exact A32 gap). Both return the package name;
+// both throw loud on failure.
+export async function assertCanvasReady(): Promise<string> {
+    const { createCanvas } = await import('@napi-rs/canvas')
+    createCanvas(2, 2).getContext('2d').fillRect(0, 0, 1, 1)
+    return '@napi-rs/canvas'
+}
+
+export async function assertSharpReady(): Promise<string> {
+    const sharp = (await import('sharp')).default
+    await sharp({ create: { width: 1, height: 1, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 0 } } }).png().toBuffer()
+    return 'sharp'
+}

package/src/assets/panels/geometry-rects.ts

@@ -0,0 +1,84 @@
+// Ground-geometry rect math: the session↔live formats behind the geometry
+// panel. SEMANTICS (what the oval means, size units, the ratio value) are
+// the consuming repo's; this module owns only the mechanics:
+// - session rect (per roll, <workspace>/studio/<id>/<roll>.rect.json):
+//   { x,y,w,h,size,art?,flip?,legs?[4],legColor? } — h ALWAYS re-derived
+//   = w × ratio preserving center-y, so data can never drift off-ratio.
+// - live rect (the game file): flip folds into MIRRORED coordinates and the
+//   flag is DROPPED — pixels ship mirrored, loaders must never double-flip.
+export type LegRect = { x: number; y: number; w: number; h: number }
+export type GroundRect = {
+    x: number; y: number; w: number; h: number
+    size: number
+    /** alpha-content height px (studio metadata; props normalize by it) */
+    art?: number
+    flip?: boolean
+    legs?: LegRect[]
+    legColor?: string
+}
+
+const r2 = (n: number): number => Math.round(n * 100) / 100
+const r3 = (n: number): number => Math.round(n * 1000) / 1000
+
+/** Normalize a possibly-legacy rect: fold `scale` into `size`, round
+ *  (x/y/w/h 2dp, size 3dp, legs 2dp), ratio-lock h preserving center-y. */
+export function cleanRect(raw: Record<string, unknown>, ratio: number): GroundRect {
+    const num = (k: string, dflt: number): number => (typeof raw[k] === 'number' && Number.isFinite(raw[k]) ? (raw[k] as number) : dflt)
+    const size = typeof raw.size === 'number' ? (raw.size as number) : num('scale', 1) // legacy key folds in
+    const x = num('x', 0)
+    const y = num('y', 0)
+    const w = Math.max(1, num('w', 1))
+    const oldH = num('h', w * ratio)
+    const h = w * ratio
+    const yLocked = y + (oldH - h) / 2 // keep center-y while re-locking the ratio
+    const out: GroundRect = { x: r2(x), y: r2(yLocked), w: r2(w), h: r2(h), size: r3(size) }
+    if (typeof raw.art === 'number') out.art = raw.art as number
+    if (raw.flip === true) out.flip = true
+    if (Array.isArray(raw.legs) && raw.legs.length === 4) {
+        out.legs = (raw.legs as LegRect[]).map((l) => ({ x: r2(l.x), y: r2(l.y), w: r2(l.w), h: r2(l.h) }))
+        if (typeof raw.legColor === 'string') out.legColor = raw.legColor
+    }
+    return out
+}
+
+/** Session → live: mirror x when flipped (oval AND legs), DROP the flag. */
+export function liveRect(clean: GroundRect, textureWidth = 1024): GroundRect {
+    if (clean.flip !== true) {
+        const { flip: _flip, ...rest } = clean
+        return { ...rest }
+    }
+    const { flip: _flip, ...rest } = clean
+    const out: GroundRect = { ...rest, x: r2(textureWidth - clean.x - clean.w) }
+    if (clean.legs != null) out.legs = clean.legs.map((l) => ({ ...l, x: r2(textureWidth - l.x - l.w) }))
+    return out
+}
+
+/** Default 4-leg layout derived from the oval — order [L·front, L·back,
+ *  R·back, R·front]; pair (0,1) = far side, (2,3) = near side. Each rect IS
+ *  the leg: top-center = hip, bottom-center = foot on the ground. */
+export function defaultLegs(oval: GroundRect): LegRect[] {
+    const u = oval.w
+    const cx = oval.x + oval.w / 2
+    const cy = oval.y + oval.h / 2
+    const lw = 0.09 * u
+    const lh = 0.3 * u
+    const centersDx = [0.2, -0.3, -0.22, 0.28]
+    return centersDx.map((dx, i) => {
+        const footY = cy + (i < 2 ? -0.06 : 0.06) * u
+        return { x: r2(cx + dx * u - lw / 2), y: r2(footY - lh), w: r2(lw), h: r2(lh) }
+    })
+}
+
+/** Legacy circle → oval migration (run on session read). A circle is
+ *  |h − w| ≤ 0.5. anchor: where the new oval's center-y comes from —
+ *  'bottom' (characters/scenery: feet at circle bottom) or 'center'
+ *  (buildings). artNormalized folds art-height units into oval-width units:
+ *  size *= w / art. Non-circles pass through untouched. */
+export function migrateCircle(rect: GroundRect, opts: { ratio: number; anchor: 'bottom' | 'center'; artNormalized?: boolean }): GroundRect {
+    if (Math.abs(rect.h - rect.w) > 0.5) return rect
+    const cy = opts.anchor === 'bottom' ? rect.y + rect.h : rect.y + rect.h / 2
+    let size = rect.size
+    if (opts.artNormalized === true && rect.art != null && rect.art > 0) size = size * (rect.w / rect.art)
+    const h = rect.w * opts.ratio
+    return cleanRect({ ...rect, size, h, y: cy - h / 2 } as unknown as Record<string, unknown>, opts.ratio)
+}

package/src/assets/roll-workspace.ts

@@ -0,0 +1,41 @@
+// The <workspace>/studio/<assetId>/ roll-workspace conventions — shared by
+// the studio server, the fill CLI and ship hooks. Files per asset dir:
+// v<seed>.webp|png rolls · pick.json { pick, alts[], shippedAt } ·
+// <roll>.meta.json freeform sidecars (project tooling reads/writes them) ·
+// prompt.json { prompt } overlay layered over the kind's prompt builder.
+// All writes go through the locked json-store; hand edits are legal (the
+// studio re-reads every poll).
+import { existsSync, readdirSync, statSync } from 'fs'
+import { join } from 'path'
+import { readJson, updateJson } from './json-store.ts'
+
+export type PickState = { pick: string | null; alts: string[]; shippedAt: string | null }
+export const PICK_INIT: PickState = { pick: null, alts: [], shippedAt: null }
+
+export type PromptOverlay = { prompt: string | null }
+export const PROMPT_INIT: PromptOverlay = { prompt: null }
+
+export const isRollFile = (f: string): boolean => /^v\d+\.(webp|png)$/.test(f)
+
+export const assetDir = (workspace: string, assetId: string): string => join(workspace, 'studio', assetId)
+
+export function listRolls(dir: string): string[] {
+    if (!existsSync(dir)) return []
+    return readdirSync(dir)
+        .filter(isRollFile)
+        .sort((a, b) => statSync(join(dir, b)).mtimeMs - statSync(join(dir, a)).mtimeMs) // newest first
+}
+
+export const pickPath = (dir: string): string => join(dir, 'pick.json')
+
+export const readPick = (dir: string): Promise<PickState> => readJson(pickPath(dir), PICK_INIT)
+
+export const updatePick = (dir: string, up: (s: PickState) => void): Promise<PickState> => updateJson(pickPath(dir), PICK_INIT, up)
+
+export const metaPath = (dir: string, roll: string): string => join(dir, `${roll}.meta.json`)
+
+export const promptPath = (dir: string): string => join(dir, 'prompt.json')
+
+export const readPromptOverlay = (dir: string): Promise<PromptOverlay> => readJson(promptPath(dir), PROMPT_INIT)
+
+export const updatePromptOverlay = (dir: string, up: (s: PromptOverlay) => void): Promise<PromptOverlay> => updateJson(promptPath(dir), PROMPT_INIT, up)

package/src/assets/run-assets.ts

@@ -0,0 +1,142 @@
+// shipkit assets — implementations behind cli/cmd_Assets.ts (clipanion owns
+// parsing; these plain functions own the logic, print through injected
+// sinks, and return exit codes — 0 ok · 1 fail).
+import { existsSync } from 'fs'
+import { join, relative } from 'path'
+import { randomSeed } from './gen/comfy-gen.ts'
+import { comfyResolver, generateRoll, type ComfyResolver } from './gen/generate-roll.ts'
+import { loadWorkflows } from './gen/workflow-loader.ts'
+import { allAssets, findAsset, loadKit, type ResolvedKit } from './kit-config.ts'
+import { NO_PICK_FIX, renderIdentity, type Brand } from './kits/identity-kit.ts'
+import { assetDir, listRolls, readPick, readPromptOverlay } from './roll-workspace.ts'
+import { page } from './server/studio-page.ts'
+import { serveStudio } from './server/studio-server.ts'
+
+export type Print = (line: string) => void
+export type AssetsIo = { print: Print; printErr: Print }
+
+class AssetsFail extends Error {}
+const die = (msg: string): never => { throw new AssetsFail(msg) }
+
+// Lazy comfy runtime — a canvas-only kit (no comfy: block) never loads
+// workflows or needs the box; only a real comfy roll triggers resolution.
+const comfyFor = (root: string, kit: ResolvedKit): ComfyResolver =>
+    comfyResolver(root, kit, () => die('this kit has no comfy config — add comfy: { host, workflows } to fill comfy assets'))
+
+async function rollOnce(root: string, io: AssetsIo, kit: ResolvedKit, resolveComfy: ComfyResolver, assetId: string, count: number): Promise<number> {
+    const f = findAsset(kit, assetId)
+    if (f == null) die(`unknown asset '${assetId}'`)
+    const dir = assetDir(join(root, kit.workspace), assetId)
+    const prompt = (await readPromptOverlay(dir)).prompt ?? f!.asset.prompt
+    let failed = 0
+    for (let i = 0; i < count; i++) {
+        const seed = randomSeed()
+        try {
+            await generateRoll(f!, { prompt, seed, destDir: dir }, resolveComfy)
+            io.print(`ok: ${assetId} v${seed}`)
+        } catch (e) {
+            failed++
+            io.printErr(`FAIL: ${assetId} seed ${seed}: ${(e as Error).message}`)
+        }
+    }
+    return failed
+}
+
+// wraps an implementation so kit/config errors become one FAIL line + exit 1
+async function guarded(io: AssetsIo, body: () => Promise<number>): Promise<number> {
+    try {
+        return await body()
+    } catch (e) {
+        if (e instanceof AssetsFail) { io.printErr(`FAIL: ${e.message}`); return 1 }
+        throw e
+    }
+}
+
+export const runAssetsServe = (root: string, io: AssetsIo): Promise<number> =>
+    guarded(io, async () => {
+        const kit = await loadKit(root)
+        const studio = await serveStudio({ kit, root, page })
+        io.print(`ok: studio → http://127.0.0.1:${studio.server.port}  (${allAssets(kit).length} assets)`)
+        await new Promise(() => {}) // Bun.serve owns the process — never resolve
+        return 0
+    })
+
+export const runAssetsTopUp = (root: string, io: AssetsIo, o: { mode: 'fill' | 'add'; n: number; categories: string[] }): Promise<number> =>
+    guarded(io, async () => {
+        const kit = await loadKit(root)
+        const resolveComfy = comfyFor(root, kit)
+        // canvas AND comfy kinds top up (A30 — canvas kinds draw in-process)
+        const targets = allAssets(kit)
+            .filter((f) => o.categories.length === 0 || o.categories.includes(f.kind.category))
+            .map((f) => ({ f, have: listRolls(assetDir(join(root, kit.workspace), f.asset.id)).length }))
+            .map((t) => ({ ...t, want: o.mode === 'add' ? o.n : Math.max(0, o.n - t.have) }))
+            .filter((t) => t.want > 0)
+            .sort((a, b) => a.have - b.have) // sparsest first
+        let failed = 0
+        for (const t of targets) failed += await rollOnce(root, io, kit, resolveComfy, t.f.asset.id, t.want)
+        io.print(`${o.mode}: ${targets.length} asset(s) topped up${failed > 0 ? ` — ${failed} roll(s) FAILED` : ''}`)
+        return failed > 0 ? 1 : 0
+    })
+
+export const runAssetsGen = (root: string, io: AssetsIo, o: { assetId: string; n: number }): Promise<number> =>
+    guarded(io, async () => {
+        const kit = await loadKit(root)
+        const failed = await rollOnce(root, io, kit, comfyFor(root, kit), o.assetId, o.n)
+        return failed > 0 ? 1 : 0
+    })
+
+export const runAssetsIdentity = (root: string, io: AssetsIo): Promise<number> =>
+    guarded(io, async () => {
+        const brandPath = join(root, '.rv-identity/brand.ts')
+        if (!existsSync(brandPath)) die('no .rv-identity/brand.ts — create one exporting a Brand (name, palette, mark)')
+        const mod = (await import(brandPath)) as { default?: Brand }
+        if (mod.default == null) die('.rv-identity/brand.ts must default-export the Brand')
+        const brand = mod.default!
+        let markFile: string | undefined
+        if (brand.mark.backend === 'comfy') {
+            // comfy marks render from the PICKED identity-logo roll — the kit
+            // owns the workspace where picks live
+            const kit = await loadKit(root).catch((e: Error) => die(`comfy mark needs the kit's roll workspace — ${e.message}`))
+            const dir = assetDir(join(root, kit.workspace), 'identity-logo')
+            const pick = await readPick(dir)
+            if (pick.pick == null) die(`brand '${brand.name}' uses a comfy mark and none is picked — ${NO_PICK_FIX}`)
+            markFile = join(dir, pick.pick!)
+            if (!existsSync(markFile)) die(`picked roll ${pick.pick} vanished from ${dir} — re-pick in the studio`)
+        }
+        const written = await renderIdentity(brand, root, { markFile })
+        for (const w of written) io.print(`ok: ${w}`)
+        return 0
+    })
+
+export const runAssetsCheck = (root: string, io: AssetsIo): Promise<number> =>
+    guarded(io, async () => {
+        let bad = 0
+        const kit = await loadKit(root).catch((e: Error) => { io.print(`FAIL: ${e.message}`); bad++; return null })
+        if (kit == null) return 1
+        io.print(`ok: kit loads — ${kit.kinds.length} kind(s), ${allAssets(kit).length} asset(s), workspace ${kit.workspace}`)
+        if (kit.comfy != null) {
+            try {
+                const wfs = await loadWorkflows(join(root, kit.comfy.workflows))
+                io.print(`ok: ${wfs.size} workflow pair(s) bound`)
+                // provenance: where each pair lives + that both halves validated
+                // (loadWorkflows throws on any invalid pair, so reaching here = valid).
+                // There is no global workflow store — git owns each repo's pairs; the
+                // house library (wiki/build/comfyui/references) is the copy-from source.
+                for (const wf of wfs.values()) {
+                    const rel = relative(root, wf.jsonPath).replace(/\.json$/, '')
+                    io.print(`ok: workflow '${wf.id}' → ${rel}.{json,ts} (pair valid)`)
+                }
+            } catch (e) {
+                io.print(`FAIL: ${(e as Error).message}`)
+                bad++
+            }
+            const up = await fetch(`${kit.comfy.host}/system_stats`, { signal: AbortSignal.timeout(3000) }).then((r) => r.ok).catch(() => false)
+            io.print(up ? `ok: comfy backend reachable (${kit.comfy.host})` : `WARN comfy backend unreachable (${kit.comfy.host})${kit.comfy.heal != null ? ` — ${kit.comfy.heal}` : ''}`)
+        }
+        if (existsSync(join(root, '.rv-identity/brand.ts'))) {
+            const outs = ['public/favicon.png', 'public/og.png', 'public/logo.png'].filter((p) => !existsSync(join(root, p)))
+            if (outs.length > 0) io.print(`WARN identity outputs missing: ${outs.join(', ')} — run: shipkit assets identity`)
+            else io.print('ok: identity outputs present')
+        }
+        return bad > 0 ? 1 : 0
+    })