Merge remote-tracking branch 'origin/main' into aso-plus

# Conflicts:
#	CHANGELOG.md
This commit is contained in:
CRTkafa 2026-10-12 04:09:46 +08:00
commit b65843828b
10 changed files with 561 additions and 74 deletions

View file

@ -27,6 +27,20 @@
rank trend of the best three keywords (visx, rank 1 at the top), the rank table and the next 3 actions. rank trend of the best three keywords (visx, rank 1 at the top), the rank table and the next 3 actions.
- `examples/demo-app` has listing files (`store/appstore.md`, `store/listing.md`) to try the ASO commands on. - `examples/demo-app` has listing files (`store/appstore.md`, `store/listing.md`) to try the ASO commands on.
- Faster `shots capture` (web) and `shots render` (a 22-language game took about 50 min to capture, serially, with a
new context and a full game boot per frame):
- `--concurrency N` (and `shots.capture.concurrency`): parallel browser contexts in one Chromium; defaults from the
CPU count (capture min(3, cores / 4), render min(4, cores / 2)). Output files do not depend on the order; progress
lines carry language / device / frame, n/total and an ETA. Render runs ffmpeg asynchronously and makes the contact
sheets after the images.
- Per-frame timing (goto, waitFor, eval, delay, screenshot, total) in each progress line and in
`.storebound/capture-report.json`, with time per step and the slowest frames at the end.
- `shots.capture.session: 'per-language'`: one page per language and device, booted once; shots switch with
`navigate: 'spa'` (pushState + popstate, then waitFor / eval) or `'reload'`; a failed precondition falls back to a
fresh page (`reuseTimeoutMs`).
- Input-hash cache (`.storebound/capture-cache.json`: shot entry, URL, frame size, session, copy text, app build from
`shots.capture.build` or the served HTML + scripts, fonts): unchanged frames are skipped; `--only-missing`,
`--force`. MCP `shots_capture` (`concurrency`, `mode`) and `shots_render` (`concurrency`).
- `apple listing --dry`, `play listing --dry` and `apple appinfo --dry` print a real plan (also `--json`), read-only: - `apple listing --dry`, `play listing --dry` and `apple appinfo --dry` print a real plan (also `--json`), read-only:
the version decision of `apple listing` (keep, update the editable version's string while PREPARE_FOR_SUBMISSION, the version decision of `apple listing` (keep, update the editable version's string while PREPARE_FOR_SUBMISSION,
create, or refuse: number taken, not higher than a reviewed version, another version in review / pending release), create, or refuse: number taken, not higher than a reviewed version, another version in review / pending release),

View file

@ -433,9 +433,9 @@ run in the background with a log (`storebound shots render > .storebound/render.
| command | kind | what | | command | kind | what |
|---|---|---| |---|---|---|
| `shots capture [--source web\|ios-sim\|android-emu\|folder]` | local | raw frames from your running app or game | | `shots capture [--source web\|ios-sim\|android-emu\|folder] [--concurrency N] [--only-missing \| --force]` | local | raw frames from your running app or game; web: parallel contexts, optional one boot per language (`capture.session`), skips unchanged frames, timing per step |
| `shots fonts` | network | font subsets for your copy (Noto for CJK / Arabic / Cyrillic / Devanagari ...) and the glyph coverage check per language | | `shots fonts` | network | font subsets for your copy (Noto for CJK / Arabic / Cyrillic / Devanagari ...) and the glyph coverage check per language |
| `shots render [--variant b \| --variants]` | local | every store size and language in the game or app style, feature graphic, contact sheet, overflow report | | `shots render [--variant b \| --variants] [--concurrency N]` | local | every store size and language in the game or app style, feature graphic, contact sheet, overflow report |
| `shots jpeg` | local | JPEG q92 copies of the Play renders (about 4x faster uploads) | | `shots jpeg` | local | JPEG q92 copies of the Play renders (about 4x faster uploads) |
| `shots check [--variants] [--json]` | local, read-only | store rules: sizes, alpha, format, bytes, counts, overflow, fallback / missing glyphs, videos, folder frames | | `shots check [--variants] [--json]` | local, read-only | store rules: sizes, alpha, format, bytes, counts, overflow, fallback / missing glyphs, videos, folder frames |
| `shots gallery` | local | `<renders>/index.html` review page | | `shots gallery` | local | `<renders>/index.html` review page |

View file

@ -146,6 +146,10 @@ export interface ShotSpec {
/** Web: JS run in the page before the screenshot. */ /** Web: JS run in the page before the screenshot. */
eval?: string[]; eval?: string[];
device?: 'phone' | 'tablet' | 'both'; device?: 'phone' | 'tablet' | 'both';
/** Web, capture.session "per-language": how this shot is reached in the already booted page. "spa" (default):
* history.pushState to its path + a popstate event, then waitFor / eval (switch scenes from those); "reload":
* page.goto in the same page. A failing waitFor there falls back to a fresh page. */
navigate?: 'spa' | 'reload';
/** ios-sim: extra launch arguments, e.g. ["-shotScene", "{shot}", "-seed", "1"] (read them with UserDefaults / your engine). */ /** ios-sim: extra launch arguments, e.g. ["-shotScene", "{shot}", "-seed", "1"] (read them with UserDefaults / your engine). */
args?: string[]; args?: string[];
/** android-emu: intent extras for `am start` (string / int / float / boolean), "{lang}" replaced in strings. */ /** android-emu: intent extras for `am start` (string / int / float / boolean), "{lang}" replaced in strings. */
@ -194,6 +198,18 @@ export interface ShotsCapture {
* every device, or per device class. Default: the frame's bar share of the height (phone 54 / 956 = 162 px on a 6.9" * every device, or per device class. Default: the frame's bar share of the height (phone 54 / 956 = 162 px on a 6.9"
* iPhone, 13" iPad 24 / 1376 = 48 px). */ * iPhone, 13" iPad 24 / 1376 = 48 px). */
cropTop?: number | { phone?: number; tablet?: number }; cropTop?: number | { phone?: number; tablet?: number };
/** Web: parallel browser contexts (one headless Chromium). Default min(3, CPU cores / 4): game boots are GPU-heavy.
* `--concurrency N` overrides. */
concurrency?: number;
/** Web: "per-shot" (default: new context + full boot per frame) or "per-language" (one page per language and
* device, booted once; shots switch in it, see ShotSpec.navigate). */
session?: 'per-shot' | 'per-language';
/** Web, per-language: how long a reused page may take to reach a shot's waitFor before a fresh page is used.
* Default 15000 ms. */
reuseTimeoutMs?: number;
/** Web: files or folders of the app build (e.g. "apps/game/src" or "apps/game/dist") hashed into the capture cache,
* so a code change re-captures. Default: the HTML at baseUrl and the scripts it loads. */
build?: string | string[];
shots: Record<string, ShotSpec>; shots: Record<string, ShotSpec>;
} }

View file

@ -200,13 +200,18 @@ export const TOOLS: ToolDef[] = [
args: i => ['--phased', String(i.action), ...opt('version', i.version)] }, args: i => ['--phased', String(i.action), ...opt('version', i.version)] },
{ name: 'shots_capture', title: 'Capture raw frames', command: ['shots', 'capture'], write: true, network: false, idempotent: true, { name: 'shots_capture', title: 'Capture raw frames', command: ['shots', 'capture'], write: true, network: false, idempotent: true,
description: 'Raw app or game frames per language into shots.frames from a web build (Playwright), the iOS Simulator (simctl), an Android emulator / device (adb) or a folder check. Local files only; a simulator it boots is shut down again, an emulator is never booted. dry_run lists the plan and the simctl / adb commands.', description: 'Raw app or game frames per language into shots.frames from a web build (Playwright), the iOS Simulator (simctl), an Android emulator / device (adb) or a folder check. Local files only; a simulator it boots is shut down again, an emulator is never booted. dry_run lists the plan and the simctl / adb commands.',
props: { lang, only: { type: 'string', description: 'Comma-separated shot names' }, device: { type: 'string', enum: ['phone', 'tablet'] }, source }, props: { lang, only: { type: 'string', description: 'Comma-separated shot names' }, device: { type: 'string', enum: ['phone', 'tablet'] }, source,
args: i => [...opt('lang', i.lang), ...opt('only', i.only), ...opt('device', i.device), ...opt('source', i.source)] }, concurrency: { type: 'integer', minimum: 1, maximum: 32, description: 'Web: parallel browser contexts (default from the CPU count)' },
mode: { type: 'string', enum: ['changed', 'only-missing', 'force'], default: 'changed', description: 'Web: skip frames with unchanged inputs (default), only missing ones, or capture all' } },
args: i => [...opt('lang', i.lang), ...opt('only', i.only), ...opt('device', i.device), ...opt('source', i.source),
...(i.concurrency ? ['--concurrency', String(i.concurrency)] : []), ...(i.mode === 'force' ? ['--force'] : i.mode === 'only-missing' ? ['--only-missing'] : [])] },
{ name: 'shots_render', title: 'Render store screenshots', command: ['shots', 'render'], write: true, network: false, idempotent: true, { name: 'shots_render', title: 'Render store screenshots', command: ['shots', 'render'], write: true, network: false, idempotent: true,
description: 'Store screenshots + Play feature graphic in every size and language from the frames and the copy file (local PNGs, needs Playwright + ffmpeg; slow for many languages). dry_run lists what would be rendered.', description: 'Store screenshots + Play feature graphic in every size and language from the frames and the copy file (local PNGs, needs Playwright + ffmpeg; slow for many languages). dry_run lists what would be rendered.',
props: { lang, size: { type: 'string', description: 'Comma-separated size keys: ios69, ios65, iphone-medium, ipad13, play, tab7, tab10, feature' }, props: { lang, size: { type: 'string', description: 'Comma-separated size keys: ios69, ios65, iphone-medium, ipad13, play, tab7, tab10, feature' },
scenes: { type: 'string', description: 'Comma-separated scene ids' }, variant, all_variants: { type: 'boolean', default: false, description: 'Base + every variant' } }, scenes: { type: 'string', description: 'Comma-separated scene ids' }, variant, all_variants: { type: 'boolean', default: false, description: 'Base + every variant' },
args: i => [...opt('lang', i.lang), ...opt('size', i.size), ...opt('scenes', i.scenes), ...(i.all_variants === true ? ['--variants'] : opt('variant', i.variant))] }, concurrency: { type: 'integer', minimum: 1, maximum: 32, description: 'Parallel pages (default min(4, CPU cores / 2))' } },
args: i => [...opt('lang', i.lang), ...opt('size', i.size), ...opt('scenes', i.scenes), ...(i.all_variants === true ? ['--variants'] : opt('variant', i.variant)),
...(i.concurrency ? ['--concurrency', String(i.concurrency)] : [])] },
{ name: 'shots_gallery', title: 'Review gallery', command: ['shots', 'gallery'], write: true, network: false, idempotent: true, { name: 'shots_gallery', title: 'Review gallery', command: ['shots', 'gallery'], write: true, network: false, idempotent: true,
description: 'Write <renders>/index.html: one self-contained page with every language, size, scene, variant and app preview, store check issues highlighted. Open it in a browser to review before uploading.', description: 'Write <renders>/index.html: one self-contained page with every language, size, scene, variant and app preview, store check issues highlighted. Open it in a browser to review before uploading.',
props: { lang }, args: i => opt('lang', i.lang) }, props: { lang }, args: i => opt('lang', i.lang) },

231
cli/shots/capture-web.ts Normal file
View file

@ -0,0 +1,231 @@
// Web capture (shots.capture.source "web"), parallel and incremental:
// --concurrency N browser contexts in one headless Chromium (default shots.capture.concurrency, else from the CPU
// count: a WebGL game is GPU-bound, so capture defaults lower than render). Files do not depend on
// the order: every frame has its own path.
// session shots.capture.session "per-shot" (default: a new context + page and a full boot per frame) or
// "per-language": one page per language and device, booted once; the next shots switch scenes in
// that page (navigate "spa": history.pushState + popstate to the shot's path, then waitFor / eval;
// navigate "reload": page.goto in the same page). A precondition that fails there (waitFor times out
// after reuseTimeoutMs) falls back to a fresh page.
// cache .storebound/capture-cache.json: per frame a hash of its inputs (shot entry, URL + query, frame
// size, session, the copy text of its language, the app build (shots.capture.build files, else
// the HTML and scripts at baseUrl), fonts.css). Unchanged frames that exist are skipped;
// --only-missing only captures frames that do not exist; --force captures everything.
// timing per frame: goto, waitFor, eval, delay, screenshot, total, in the progress line and in
// .storebound/capture-report.json, with the slowest frames and steps at the end.
import { createHash } from 'node:crypto';
import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
import { availableParallelism, cpus } from 'node:os';
import { join } from 'node:path';
import type { ShotSpec, ShotsCapture } from '../lib/config';
import { log, warn } from '../lib/log';
import { shotsFor } from './devices';
import type { FrameDims } from './lib';
type Device = 'phone' | 'tablet';
export const STEPS = ['goto', 'waitFor', 'eval', 'delay', 'screenshot'] as const;
export type Step = typeof STEPS[number];
export type Timing = Record<Step | 'total', number>;
/** frame = path relative to shots.frames (cache and report key), out = absolute file. */
export interface WebJob { lang: string; device: Device; name: string; spec: ShotSpec; url: string; path: string; out: string; frame: string; hash: string }
/** CPU cores (availableParallelism where Bun has it). */
export const coreCount = (): number => { try { return availableParallelism(); } catch { return cpus().length || 2; } };
/** Default parallel workers: render min(4, cores / 2); capture (GPU-heavy WebGL / game boots) min(3, cores / 4). */
export function defaultConcurrency(kind: 'render' | 'capture', cores = coreCount()): number {
return Math.max(1, kind === 'render' ? Math.min(4, Math.floor(cores / 2)) : Math.min(3, Math.floor(cores / 4)));
}
/** Runs fn over items with at most n at a time; results keep the input order. */
export async function pool<T, R>(items: T[], n: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]> {
const out = new Array<R>(items.length);
let next = 0;
const worker = async (): Promise<void> => { while (next < items.length) { const i = next++; out[i] = await fn(items[i]!, i); } };
await Promise.all(Array.from({ length: Math.max(1, Math.min(n, items.length)) }, worker));
return out;
}
const fmtS = (ms: number): string => (ms >= 60_000 ? `${Math.floor(ms / 60_000)}m${String(Math.round((ms % 60_000) / 1000)).padStart(2, '0')}s` : `${(ms / 1000).toFixed(1)}s`);
/** "n/total, ETA" progress for parallel work: ETA = remaining items x average wall time per finished item. */
export function progressLine(done: number, total: number, startedMs: number, nowMs = Date.now()): string {
const w = String(total).length;
const eta = done ? ((nowMs - startedMs) / done) * (total - done) : 0;
return `${String(done).padStart(w)}/${total}${done < total && done ? ` ETA ${fmtS(eta)}` : ''}`;
}
export const timingText = (t: Timing): string => `goto ${fmtS(t.goto)} wait ${fmtS(t.waitFor)} eval ${fmtS(t.eval)} delay ${fmtS(t.delay)} shot ${fmtS(t.screenshot)} = ${fmtS(t.total)}`;
/** Slowest frames and the time per step over all frames (for the end of the log and the report). */
export function timingSummary(frames: { frame: string; timing: Timing }[], top = 5): { slowest: { frame: string; total: number; step: Step }[]; steps: Record<Step, number>; total: number } {
const steps = Object.fromEntries(STEPS.map(s => [s, 0])) as Record<Step, number>;
for (const f of frames) for (const s of STEPS) steps[s] += f.timing[s];
const slowest = [...frames].sort((a, b) => b.timing.total - a.timing.total).slice(0, top)
.map(f => ({ frame: f.frame, total: f.timing.total, step: STEPS.reduce((m, s) => (f.timing[s] > f.timing[m] ? s : m), STEPS[0] as Step) }));
return { slowest, steps, total: frames.reduce((t, f) => t + f.timing.total, 0) };
}
const sha = (s: string | Uint8Array): string => createHash('sha256').update(s).digest('hex').slice(0, 16);
/** Content hash of build files (a file or folder; node_modules / dot folders skipped): paths, sizes and mtimes. */
export function hashPaths(paths: string[]): string {
const h = createHash('sha256');
const walk = (p: string): void => {
if (!existsSync(p)) { h.update(`missing:${p}`); return; }
const st = statSync(p);
if (st.isDirectory()) { for (const e of readdirSync(p).sort()) if (e !== 'node_modules' && !e.startsWith('.')) walk(join(p, e)); return; }
h.update(`${p}:${st.size}:${st.mtimeMs}\n`);
};
for (const p of paths) walk(p);
return h.digest('hex').slice(0, 16);
}
/** App build fingerprint from the running server: the HTML at baseUrl and the scripts it loads (dev servers too). */
export async function hashServed(baseUrl: string): Promise<string> {
try {
const html = await (await fetch(baseUrl, { signal: AbortSignal.timeout(10_000) })).text();
const h = createHash('sha256').update(html);
for (const m of html.matchAll(/<script[^>]+src=["']([^"']+)["']/g)) {
try { h.update(await (await fetch(new URL(m[1]!, baseUrl), { signal: AbortSignal.timeout(10_000) })).text()); } catch { h.update(`unreachable:${m[1]}`); }
}
return h.digest('hex').slice(0, 16);
} catch { return 'unreachable'; }
}
/** Every web frame to capture, in a fixed order (lang, device, shot), with its URL and its input hash. */
export function planWeb(cap: ShotsCapture, o: { langs: string[]; devices: Device[]; only: string[]; dims: Record<Device, FrameDims>; framesDir: string;
build: string; copyText?: (lang: string) => string; fonts?: string }): WebJob[] {
const jobs: WebJob[] = [];
for (const lang of o.langs) for (const device of o.devices) for (const [name, spec] of shotsFor(cap, device, o.only)) {
const q = (cap.query ?? '').replaceAll('{lang}', lang);
const path = (spec.path ?? '/').replaceAll('{lang}', lang) + (q ? ((spec.path ?? '/').includes('?') ? '&' : '?') + q : '');
const url = (cap.baseUrl ?? '').replace(/\/$/, '') + path;
const hash = sha(JSON.stringify({ spec, url, dims: o.dims[device], session: cap.session ?? 'per-shot', build: o.build, copy: o.copyText?.(lang) ?? '', fonts: o.fonts ?? '' }));
const frame = `${lang}/${device}/${name}.png`;
jobs.push({ lang, device, name, spec, url, path, out: join(o.framesDir, frame), frame, hash });
}
return jobs;
}
export type Cache = Record<string, string>;
export const cachePath = (root: string): string => join(root, '.storebound', 'capture-cache.json');
export function readCache(root: string): Cache { try { return JSON.parse(readFileSync(cachePath(root), 'utf8')) as Cache; } catch { return {}; } }
/** Which jobs to run: --force all; --only-missing the ones whose file is missing; else missing or changed inputs. */
export function selectJobs(jobs: WebJob[], cache: Cache, mode: 'force' | 'only-missing' | 'changed', exists: (file: string) => boolean = existsSync): { run: WebJob[]; skipped: WebJob[] } {
const run: WebJob[] = [], skipped: WebJob[] = [];
for (const j of jobs) {
const keep = mode === 'force' ? false : mode === 'only-missing' ? exists(j.out) : exists(j.out) && cache[j.frame] === j.hash;
(keep ? skipped : run).push(j);
}
return { run, skipped };
}
export interface CaptureReport {
at: string; concurrency: number; session: string; wallMs: number;
frames: { frame: string; ok: boolean; reused: boolean; timing: Timing; error?: string }[];
skipped: string[];
summary: ReturnType<typeof timingSummary>;
}
/* eslint-disable @typescript-eslint/no-explicit-any */
/** Captures the jobs in a browser: per-shot contexts, or one page per language + device in per-language sessions. */
export async function captureWeb(browser: any, cap: ShotsCapture, jobs: WebJob[], o: { concurrency: number; dims: Record<Device, FrameDims> }): Promise<CaptureReport> {
const started = Date.now();
const perLang = cap.session === 'per-language';
const report: CaptureReport['frames'] = [];
let finished = 0;
const total = jobs.length;
const newPage = async (j: WebJob): Promise<{ c: any; page: any; errs: string[] }> => {
const d = o.dims[j.device];
const c = await browser.newContext({ viewport: { width: d.w, height: d.h }, deviceScaleFactor: d.dpr, hasTouch: true, isMobile: true, serviceWorkers: 'block', locale: j.lang });
const page = await c.newPage();
const errs: string[] = [];
page.on('pageerror', (e: Error) => errs.push(e.message));
return { c, page, errs };
};
const shoot = async (s: { page: any; errs: string[] }, j: WebJob, how: 'goto' | 'spa', waitTimeout: number): Promise<Timing> => {
const t: Timing = { goto: 0, waitFor: 0, eval: 0, delay: 0, screenshot: 0, total: 0 };
let t0 = Date.now();
if (how === 'goto') await s.page.goto(j.url, { waitUntil: 'domcontentloaded', timeout: 90000 });
else await s.page.evaluate(`(p => { if (location.pathname + location.search !== p) { history.pushState(null, '', p); dispatchEvent(new PopStateEvent('popstate', { state: null })); } })(${JSON.stringify(j.path)})`);
t.goto = Date.now() - t0; t0 = Date.now();
if (j.spec.waitFor) await s.page.waitForFunction(j.spec.waitFor, null, { timeout: waitTimeout, polling: 50 });
t.waitFor = Date.now() - t0; t0 = Date.now();
for (const js of j.spec.eval ?? []) await s.page.evaluate(js);
t.eval = Date.now() - t0; t0 = Date.now();
await s.page.waitForTimeout(j.spec.delayMs ?? 1000);
t.delay = Date.now() - t0; t0 = Date.now();
mkdirSync(join(j.out, '..'), { recursive: true });
await s.page.screenshot({ path: j.out });
t.screenshot = Date.now() - t0;
t.total = t.goto + t.waitFor + t.eval + t.delay + t.screenshot;
return t;
};
const record = (j: WebJob, r: { ok: boolean; reused: boolean; timing: Timing; error?: string; errs?: string[] }): void => {
finished++;
report.push({ frame: j.frame, ok: r.ok, reused: r.reused, timing: r.timing, ...(r.error ? { error: r.error } : {}) });
const head = `${progressLine(finished, total, started)} ${j.lang}/${j.device}/${j.name}`;
if (r.ok) log('shots', `${head}.png ${r.reused ? '(reused page) ' : ''}${timingText(r.timing)}${r.errs?.length ? ' (page errors: ' + r.errs.join(' | ').slice(0, 200) + ')' : ''}`);
else warn('shots', `${head}: ${r.error}`);
};
const zero = (): Timing => ({ goto: 0, waitFor: 0, eval: 0, delay: 0, screenshot: 0, total: 0 });
if (!perLang) {
await pool(jobs, o.concurrency, async j => {
const s = await newPage(j);
try { const timing = await shoot(s, j, 'goto', 120000); record(j, { ok: true, reused: false, timing, errs: s.errs }); }
catch (e) { record(j, { ok: false, reused: false, timing: zero(), error: (e as Error).message.split('\n')[0]!.slice(0, 300) }); }
await s.c.close();
});
} else {
// one group per language + device, its shots in order on one booted page
const groups = new Map<string, WebJob[]>();
for (const j of jobs) { const k = `${j.lang}/${j.device}`; groups.set(k, [...(groups.get(k) ?? []), j]); }
await pool([...groups.values()], o.concurrency, async group => {
let s: Awaited<ReturnType<typeof newPage>> | null = null;
for (const j of group) {
const nav = j.spec.navigate ?? 'spa';
if (s) {
try {
const timing = await shoot(s, j, nav === 'reload' ? 'goto' : 'spa', cap.reuseTimeoutMs ?? 15000);
record(j, { ok: true, reused: true, timing, errs: s.errs });
continue;
} catch (e) {
warn('shots', `${j.lang}/${j.device}/${j.name}: reused page failed (${(e as Error).message.split('\n')[0]!.slice(0, 120)}), fresh page`);
await s.c.close(); s = null;
}
}
s = await newPage(j);
try { const timing = await shoot(s, j, 'goto', 120000); record(j, { ok: true, reused: false, timing, errs: s.errs }); }
catch (e) { record(j, { ok: false, reused: false, timing: zero(), error: (e as Error).message.split('\n')[0]!.slice(0, 300) }); await s.c.close(); s = null; }
}
if (s) await s.c.close();
});
}
const order = new Map(jobs.map((j, i) => [j.frame, i] as const));
report.sort((a, b) => order.get(a.frame)! - order.get(b.frame)!);
const ok = report.filter(f => f.ok);
return { at: new Date().toISOString(), concurrency: o.concurrency, session: cap.session ?? 'per-shot', wallMs: Date.now() - started, frames: report, skipped: [],
summary: timingSummary(ok.map(f => ({ frame: f.frame, timing: f.timing }))) };
}
/* eslint-enable @typescript-eslint/no-explicit-any */
/** Log lines for the end of a capture: wall time, sum of frame time, slowest frames and steps. */
export function summaryLines(r: CaptureReport): string[] {
const s = r.summary;
const lines = [`${r.frames.filter(f => f.ok).length} frames in ${fmtS(r.wallMs)} wall (${fmtS(s.total)} of frame time, ${r.concurrency} at a time, session ${r.session})`];
if (s.total) lines.push('time per step: ' + STEPS.map(st => `${st} ${fmtS(s.steps[st])} (${Math.round((100 * s.steps[st]) / s.total)} %)`).join(', '));
for (const f of s.slowest) lines.push(`slowest: ${f.frame} ${fmtS(f.total)} (mostly ${f.step})`);
return lines;
}
export function writeCaptureState(root: string, report: CaptureReport, cache: Cache, captured: WebJob[]): void {
mkdirSync(join(root, '.storebound'), { recursive: true });
const okFrames = new Set(report.frames.filter(f => f.ok).map(f => f.frame));
for (const j of captured) if (okFrames.has(j.frame)) cache[j.frame] = j.hash;
writeFileSync(cachePath(root), JSON.stringify(Object.fromEntries(Object.entries(cache).sort()), null, 1) + '\n');
writeFileSync(join(root, '.storebound', 'capture-report.json'), JSON.stringify(report, null, 1) + '\n');
}

View file

@ -1,11 +1,12 @@
// Raw frames from a running build of your app or game, from any engine. // Raw frames from a running build of your app or game, from any engine.
// storebound shots capture [--lang en,tr] [--only hero,shop] [--device phone|tablet] [--source web|ios-sim|android-emu|folder] // storebound shots capture [--lang en,tr] [--only hero,shop] [--device phone|tablet] [--source web|ios-sim|android-emu|folder]
// [--dry] [--keep-booted] // [--dry] [--keep-booted] [--concurrency N] [--only-missing | --force]
// Frames go to <shots.frames>/<lang>/<device>/<name>.png: the screen BELOW the status bar (the template draws one). // Frames go to <shots.frames>/<lang>/<device>/<name>.png: the screen BELOW the status bar (the template draws one).
// shots.capture.source (default web): // shots.capture.source (default web):
// web headless Chromium (playwright), mobile viewport + touch at phone / tablet size. Each shot: // web headless Chromium (playwright), mobile viewport + touch at phone / tablet size. Each shot:
// { path, waitFor?: JS expression that turns true, eval?: [JS], delayMs?, device? }; URL = baseUrl + path + // { path, waitFor?: JS expression that turns true, eval?: [JS], delayMs?, device? }; URL = baseUrl + path +
// query, "{lang}" replaced. // query, "{lang}" replaced. Parallel contexts, per-language page reuse, the input-hash cache and the
// per-frame timing (goto / waitFor / eval / delay / screenshot): capture-web.ts.
// ios-sim xcrun simctl: boots the simulator (ios.device / ios.devices.tablet), optional install of ios.app, status // ios-sim xcrun simctl: boots the simulator (ios.device / ios.devices.tablet), optional install of ios.app, status
// bar 9:41 / full battery / full bars, one warm-up launch after a cold boot (ios.warmupMs), then per shot: // bar 9:41 / full battery / full bars, one warm-up launch after a cold boot (ios.warmupMs), then per shot:
// launch ios.bundleId with -AppleLanguages (xx) -AppleLocale + ios.args + shot.args, open shot.url // launch ios.bundleId with -AppleLanguages (xx) -AppleLocale + ios.args + shot.args, open shot.url
@ -33,7 +34,8 @@ import { checkFrameFolder } from './check';
import { adbAppLocaleArgs, adbDemoExitArgs, adbDemoModeArgs, adbForceStopArgs, adbInstallArgs, adbScreencapArgs, adbStartArgs, adbStateArgs, adbTarget, import { adbAppLocaleArgs, adbDemoExitArgs, adbDemoModeArgs, adbForceStopArgs, adbInstallArgs, adbScreencapArgs, adbStartArgs, adbStateArgs, adbTarget,
cropArgs, cropTopFor, fill, pickSimulator, shotsFor, simBootArgs, simBootStatusArgs, simInstallArgs, simLaunchArgs, simOpenUrlArgs, cropArgs, cropTopFor, fill, pickSimulator, shotsFor, simBootArgs, simBootStatusArgs, simInstallArgs, simLaunchArgs, simOpenUrlArgs,
simScreenshotArgs, simShutdownArgs, simStatusBarArgs, simStatusBarClearArgs, simTarget, SOURCES, type Source, TOOL_HINTS, validateCapture } from './devices'; simScreenshotArgs, simShutdownArgs, simStatusBarArgs, simStatusBarClearArgs, simTarget, SOURCES, type Source, TOOL_HINTS, validateCapture } from './devices';
import { type FrameDims, frameDims } from './lib'; import { type CopyFile, copyText, type FrameDims, frameDims } from './lib';
import { captureWeb, defaultConcurrency, hashPaths, hashServed, planWeb, readCache, selectJobs, summaryLines, writeCaptureState } from './capture-web';
import { imageInfo } from './spec'; import { imageInfo } from './spec';
type Device = 'phone' | 'tablet'; type Device = 'phone' | 'tablet';
@ -120,29 +122,29 @@ export async function run(ctx: Ctx): Promise<void> {
for (const lang of langs) for (const device of devices) for (const [name, s] of shotsFor(cap, device, only)) progress(`${lang}/${device}/${name}.png <- ${cap.baseUrl}${(s.path ?? '/').replaceAll('{lang}', lang)}`); for (const lang of langs) for (const device of devices) for (const [name, s] of shotsFor(cap, device, only)) progress(`${lang}/${device}/${name}.png <- ${cap.baseUrl}${(s.path ?? '/').replaceAll('{lang}', lang)}`);
return done('shots', `capture planned (dry run): ${total} frames from web`); return done('shots', `capture planned (dry run): ${total} frames from web`);
} }
const browser = await launch(root, { headless: true, args: ['--mute-audio', '--ignore-gpu-blocklist', '--enable-webgl', '--enable-gpu'] }); need(cap.baseUrl, 'shots.capture.baseUrl');
try { const concurrency = a.num('concurrency', cap.concurrency ?? defaultConcurrency('capture'));
for (const lang of langs) for (const device of devices) for (const [name, s] of shotsFor(cap, device, only)) { const builds = cap.build ? (Array.isArray(cap.build) ? cap.build : [cap.build]).map(p => resolve(p)) : [];
const d = dims[device]; const build = builds.length ? hashPaths(builds) : await hashServed(cap.baseUrl!);
const q = (cap.query ?? '').replaceAll('{lang}', lang); let copy: CopyFile = {};
const path = (s.path ?? '/').replaceAll('{lang}', lang); try { copy = JSON.parse(readFileSync(resolve(shots.copy), 'utf8')) as CopyFile; } catch { /* no copy yet */ }
const url = need(cap.baseUrl, 'shots.capture.baseUrl').replace(/\/$/, '') + path + (q ? (path.includes('?') ? '&' : '?') + q : ''); const fontsCss = join(root, '.storebound', 'fonts', 'fonts.css');
const c = await browser.newContext({ viewport: { width: d.w, height: d.h }, deviceScaleFactor: d.dpr, hasTouch: true, isMobile: true, serviceWorkers: 'block', locale: lang }); const jobs = planWeb(cap, { langs, devices, only, dims, framesDir, build, copyText: l => copyText(l, copy[l]),
const page = await c.newPage(); fonts: existsSync(fontsCss) ? readFileSync(fontsCss, 'utf8') : '' });
const errs: string[] = []; const cache = readCache(root);
page.on('pageerror', (e: Error) => errs.push(e.message)); const { run: todo, skipped } = selectJobs(jobs, cache, a.has('force') ? 'force' : a.has('only-missing') ? 'only-missing' : 'changed');
try { if (skipped.length) log('shots', `${skipped.length} of ${jobs.length} frames unchanged, skipped (${a.has('only-missing') ? '--only-missing' : 'same inputs as last time'}; --force captures them again)`);
await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 90000 }); log('shots', `capturing ${todo.length} frames, ${Math.min(concurrency, todo.length) || 0} at a time${cap.session === 'per-language' ? ', one page per language' : ''}`);
if (s.waitFor) await page.waitForFunction(s.waitFor, null, { timeout: 120000, polling: 50 }); if (todo.length) {
for (const js of s.eval ?? []) await page.evaluate(js); const browser = await launch(root, { headless: true, args: ['--mute-audio', '--ignore-gpu-blocklist', '--enable-webgl', '--enable-gpu'] });
await page.waitForTimeout(s.delayMs ?? 1000); let report;
await page.screenshot({ path: target(lang, device, name) }); try { report = await captureWeb(browser, cap, todo, { concurrency, dims }); } finally { await browser.close(); }
n++; report.skipped = skipped.map(j => j.frame);
progress(`${lang}/${device}/${name}.png${errs.length ? ' (page errors: ' + errs.join(' | ').slice(0, 200) + ')' : ''}`); writeCaptureState(root, report, cache, todo);
} catch (e) { failed++; warn('shots', `${lang}/${device}/${name}: ${(e as Error).message.slice(0, 300)}`); } for (const l of summaryLines(report)) log('shots', l);
await c.close(); n += report.frames.filter(f => f.ok).length;
} failed += report.frames.filter(f => !f.ok).length;
} finally { await browser.close(); } }
} }
if (source === 'ios-sim') { if (source === 'ios-sim') {

View file

@ -28,10 +28,14 @@ export function validateCapture(c: ShotsCapture | undefined): string[] {
if (!c.ios?.device && !c.ios?.devices?.phone) e.push('shots.capture.ios.device: simulator name or UDID, e.g. "iPhone 17 Pro Max"'); if (!c.ios?.device && !c.ios?.devices?.phone) e.push('shots.capture.ios.device: simulator name or UDID, e.g. "iPhone 17 Pro Max"');
} }
if (c.ios?.warmupMs !== undefined && !(Number.isInteger(c.ios.warmupMs) && c.ios.warmupMs >= 0)) e.push('shots.capture.ios.warmupMs: milliseconds (integer >= 0)'); if (c.ios?.warmupMs !== undefined && !(Number.isInteger(c.ios.warmupMs) && c.ios.warmupMs >= 0)) e.push('shots.capture.ios.warmupMs: milliseconds (integer >= 0)');
if (c.concurrency !== undefined && !(Number.isInteger(c.concurrency) && c.concurrency >= 1 && c.concurrency <= 32)) e.push('shots.capture.concurrency: integer 1-32');
if (c.session !== undefined && !['per-shot', 'per-language'].includes(c.session)) e.push('shots.capture.session: per-shot | per-language');
if (c.reuseTimeoutMs !== undefined && !(Number.isInteger(c.reuseTimeoutMs) && c.reuseTimeoutMs > 0)) e.push('shots.capture.reuseTimeoutMs: milliseconds (integer > 0)');
if (src === 'android-emu' && !c.android?.package) e.push('shots.capture.android.package: application id (source android-emu)'); if (src === 'android-emu' && !c.android?.package) e.push('shots.capture.android.package: application id (source android-emu)');
if (src !== 'folder' && (!c.shots || !Object.keys(c.shots).length)) e.push('shots.capture.shots: at least one shot'); if (src !== 'folder' && (!c.shots || !Object.keys(c.shots).length)) e.push('shots.capture.shots: at least one shot');
for (const [name, s] of Object.entries(c.shots ?? {})) { for (const [name, s] of Object.entries(c.shots ?? {})) {
if (!/^[A-Za-z0-9._-]+$/.test(name)) e.push(`shots.capture.shots.${name}: name must be a file name (letters, digits, . _ -)`); if (!/^[A-Za-z0-9._-]+$/.test(name)) e.push(`shots.capture.shots.${name}: name must be a file name (letters, digits, . _ -)`);
if (s.navigate && !['spa', 'reload'].includes(s.navigate)) e.push(`shots.capture.shots.${name}.navigate: spa | reload`);
if (s.device && !['phone', 'tablet', 'both'].includes(s.device)) e.push(`shots.capture.shots.${name}.device: phone | tablet | both`); if (s.device && !['phone', 'tablet', 'both'].includes(s.device)) e.push(`shots.capture.shots.${name}.device: phone | tablet | both`);
if (src === 'web' && s.path === undefined) e.push(`shots.capture.shots.${name}.path: URL path (source web)`); if (src === 'web' && s.path === undefined) e.push(`shots.capture.shots.${name}.path: URL path (source web)`);
if ((src === 'web' || src === 'folder') && (s.args || s.extras)) e.push(`shots.capture.shots.${name}: args / extras only apply to ios-sim / android-emu`); if ((src === 'web' || src === 'folder') && (s.args || s.extras)) e.push(`shots.capture.shots.${name}: args / extras only apply to ios-sim / android-emu`);

View file

@ -1,6 +1,6 @@
// Store screenshots + Play feature graphic at exact pixel sizes, from raw app or game frames and per-language copy. // Store screenshots + Play feature graphic at exact pixel sizes, from raw app or game frames and per-language copy.
// storebound shots render [--lang en,tr] [--size ios69,play,feature] [--scenes 1,3] [--variant b | --variants] // storebound shots render [--lang en,tr] [--size ios69,play,feature] [--scenes 1,3] [--variant b | --variants]
// [--no-sheet] [--port 8792] [--dry] // [--no-sheet] [--port 8792] [--concurrency N] [--dry]
// Out: <shots.out>/<lang>/<size>/NN.png (24-bit RGB: Play rejects alpha / palette PNGs), <lang>/feature/1024x500.png, // Out: <shots.out>/<lang>/<size>/NN.png (24-bit RGB: Play rejects alpha / palette PNGs), <lang>/feature/1024x500.png,
// <lang>/sheet.png (contact sheet of every size packed into a grid, for a quick review) and <shots.out>/report.json (text overflow flags // <lang>/sheet.png (contact sheet of every size packed into a grid, for a quick review) and <shots.out>/report.json (text overflow flags
// per image, read by `shots check` and `shots gallery`). Variants go to <shots.out>/<variant>/<lang>/... // per image, read by `shots check` and `shots gallery`). Variants go to <shots.out>/<variant>/<lang>/...
@ -16,11 +16,11 @@ import { fontCodepoints } from './cmap';
import { readManifest } from './fonts'; import { readManifest } from './fonts';
import { type FontManifest, fontUsage, measureFonts, roleTexts, uncoveredChars } from './glyphs'; import { type FontManifest, fontUsage, measureFonts, roleTexts, uncoveredChars } from './glyphs';
import { join, relative } from 'node:path'; import { join, relative } from 'node:path';
import { spawnSync } from 'node:child_process';
import type { Ctx } from '../lib/ctx'; import type { Ctx } from '../lib/ctx';
import { need } from '../lib/ctx'; import { need } from '../lib/ctx';
import { done, log, warn } from '../lib/log'; import { done, log, warn } from '../lib/log';
import { launch } from './browser'; import { launch } from './browser';
import { defaultConcurrency, pool, progressLine } from './capture-web';
import { shotsStyle } from '../lib/config'; import { shotsStyle } from '../lib/config';
import { type CopyFile, SIZES, copyText, defaultSizes, frameDims, mergeCopy, palette, renderDir, scriptFont, sheetLayout, shotFonts, validateCopy, variantScenes } from './lib'; import { type CopyFile, SIZES, copyText, defaultSizes, frameDims, mergeCopy, palette, renderDir, scriptFont, sheetLayout, shotFonts, validateCopy, variantScenes } from './lib';
import { type RenderReport, mergeReport, readReport } from './report'; import { type RenderReport, mergeReport, readReport } from './report';
@ -132,14 +132,24 @@ export async function run(ctx: Ctx): Promise<void> {
}); });
const base = `http://127.0.0.1:${server.port}`; const base = `http://127.0.0.1:${server.port}`;
const browser = await launch(root, { headless: true }); const browser = await launch(root, { headless: true });
const page = await (await browser.newContext({ deviceScaleFactor: 1 })).newPage(); const concurrency = a.num('concurrency', defaultConcurrency('render'));
const errs: string[] = []; // one page per worker, each with its own error list
page.on('pageerror', (e: Error) => errs.push(e.message)); // eslint-disable-next-line @typescript-eslint/no-explicit-any
page.on('response', (r: { status(): number; url(): string }) => { if (r.status() >= 400 && !r.url().includes('/fonts/')) errs.push(`${r.status()} ${r.url()}`); }); const pages: { page: any; errs: string[] }[] = [];
let warnings = 0; const pageFor = async (k: number): Promise<{ page: any; errs: string[] }> => { // eslint-disable-line @typescript-eslint/no-explicit-any
if (pages[k]) return pages[k]!;
const page = await (await browser.newContext({ deviceScaleFactor: 1 })).newPage(); // own context: no background-tab throttling
const errs: string[] = [];
page.on('pageerror', (e: Error) => errs.push(e.message));
page.on('response', (r: { status(): number; url(): string }) => { if (r.status() >= 400 && !r.url().includes('/fonts/')) errs.push(`${r.status()} ${r.url()}`); });
return (pages[k] = { page, errs });
};
let warnings = 0, finished = 0, total = 0;
const started = Date.now();
const report: RenderReport = {}; const report: RenderReport = {};
async function shoot(url: string, w: number, h: number, out: string): Promise<void> { async function shoot(p: { page: any; errs: string[] }, url: string, w: number, h: number, out: string): Promise<void> { // eslint-disable-line @typescript-eslint/no-explicit-any
const { page, errs } = p;
errs.length = 0; errs.length = 0;
mkdirSync(join(out, '..'), { recursive: true }); mkdirSync(join(out, '..'), { recursive: true });
await page.setViewportSize({ width: w, height: h }); await page.setViewportSize({ width: w, height: h });
@ -157,47 +167,63 @@ export async function run(ctx: Ctx): Promise<void> {
} }
if (overflow.length) warn('shots', `${relative(root, out)}: ${overflow.join('; ')}`); if (overflow.length) warn('shots', `${relative(root, out)}: ${overflow.join('; ')}`);
await page.screenshot({ path: tmp, clip: { x: 0, y: 0, width: w, height: h } }); await page.screenshot({ path: tmp, clip: { x: 0, y: 0, width: w, height: h } });
const r = spawnSync('ffmpeg', ['-v', 'error', '-y', '-i', tmp, '-pix_fmt', 'rgb24', out]); const ff = Bun.spawn(['ffmpeg', '-v', 'error', '-y', '-i', tmp, '-pix_fmt', 'rgb24', out], { stderr: 'pipe' });
const code = await ff.exited;
rmSync(tmp, { force: true }); rmSync(tmp, { force: true });
if (r.status !== 0) throw new Error('ffmpeg: ' + r.stderr); if (code !== 0) throw new Error('ffmpeg: ' + await new Response(ff.stderr).text());
if (errs.length) warnings++; if (errs.length) warnings++;
log('shots', `${errs.length ? 'WARN ' : ''}${relative(root, out)}${errs.length ? ' ' + errs.join(' | ') : ''}`); finished++;
log('shots', `${progressLine(finished, total, started)} ${errs.length ? 'WARN ' : ''}${relative(root, out)}${errs.length ? ' ' + errs.join(' | ') : ''}`);
} }
try { // every image first (in parallel), then one contact sheet per language from its finished images
for (const [v, job] of jobs) for (const lang of langs) { const items: { url: string; w: number; h: number; out: string }[] = [];
const sceneIds = a.list('scenes').length ? a.list('scenes') : job.scenes.map(s => s.id); const sheets: { dir: string; rows: { size: string; files: string[] }[] }[] = [];
const vq = v ? `&v=${encodeURIComponent(v)}` : ''; for (const [v, job] of jobs) for (const lang of langs) {
const dir = renderDir(outDir, lang, v || undefined); const sceneIds = a.list('scenes').length ? a.list('scenes') : job.scenes.map(s => s.id);
const rows: { size: string; files: string[] }[] = []; const vq = v ? `&v=${encodeURIComponent(v)}` : '';
for (const size of sizes) { const dir = renderDir(outDir, lang, v || undefined);
const s = SIZES[size]!; const rows: { size: string; files: string[] }[] = [];
if (s.feature) { for (const size of sizes) {
const f = join(dir, 'feature', '1024x500.png'); const s = SIZES[size]!;
await shoot(`${base}/${style === 'app' ? 'feature-app' : 'feature'}.html?lang=${encodeURIComponent(lang)}${vq}`, s.w, s.h, f); if (s.feature) {
rows.push({ size, files: [f] }); const f = join(dir, 'feature', '1024x500.png');
continue; items.push({ url: `${base}/${style === 'app' ? 'feature-app' : 'feature'}.html?lang=${encodeURIComponent(lang)}${vq}`, w: s.w, h: s.h, out: f });
} rows.push({ size, files: [f] });
const files: string[] = []; continue;
for (const [i, id] of sceneIds.entries()) {
const f = join(dir, size, `${String(i + 1).padStart(2, '0')}.png`);
await shoot(`${base}/${style === 'app' ? 'template-app' : 'template'}.html?s=${encodeURIComponent(id)}&w=${s.w}&h=${s.h}&lang=${encodeURIComponent(lang)}${s.device ? '&device=tablet' : ''}${size === 'tab7' || size === 'tab10' ? '&style=android' : ''}${vq}`, s.w, s.h, f);
files.push(f);
}
rows.push({ size, files });
} }
if (!a.has('no-sheet') && rows.length) { const files: string[] = [];
const lay = sheetLayout(rows); for (const [i, id] of sceneIds.entries()) {
const imgs = lay.tiles.map(t => `<img src="/out/${relative(outDir, t.file)}" style="position:absolute;left:${t.x}px;top:${t.y}px;width:${t.w}px;height:${t.h}px;border-radius:14px">`).join(''); const f = join(dir, size, `${String(i + 1).padStart(2, '0')}.png`);
const W = lay.w, y = lay.h; items.push({ url: `${base}/${style === 'app' ? 'template-app' : 'template'}.html?s=${encodeURIComponent(id)}&w=${s.w}&h=${s.h}&lang=${encodeURIComponent(lang)}${s.device ? '&device=tablet' : ''}${size === 'tab7' || size === 'tab10' ? '&style=android' : ''}${vq}`, w: s.w, h: s.h, out: f });
const sheet = join(dir, '.sheet.html'); files.push(f);
await Bun.write(sheet, `<!doctype html><body style="margin:0;background:#141418;width:${W}px;height:${y}px;position:relative">${imgs}
<script>Promise.all([...document.images].map(i=>i.decode())).then(()=>document.body.dataset.ready='1')</script></body>`);
await shoot(`${base}/out/${relative(outDir, sheet)}`, W, y, join(dir, 'sheet.png'));
rmSync(sheet, { force: true });
} }
rows.push({ size, files });
} }
if (!a.has('no-sheet') && rows.length) sheets.push({ dir, rows });
}
total = items.length + sheets.length;
log('shots', `rendering ${items.length} images${sheets.length ? ` + ${sheets.length} contact sheets` : ''}, ${Math.min(concurrency, items.length)} at a time (--concurrency)`);
try {
const slot = new Map<number, number>();
let nextSlot = 0;
const withPage = async (fn: (p: { page: any; errs: string[] }) => Promise<void>): Promise<void> => { // eslint-disable-line @typescript-eslint/no-explicit-any
const free = [...Array(concurrency).keys()].find(k => !slot.has(k)) ?? nextSlot++ % concurrency;
slot.set(free, 1);
try { await fn(await pageFor(free)); } finally { slot.delete(free); }
};
await pool(items, concurrency, it => withPage(p => shoot(p, it.url, it.w, it.h, it.out)));
await pool(sheets, concurrency, async ({ dir, rows }) => {
const lay = sheetLayout(rows);
const imgs = lay.tiles.map(t => `<img src="/out/${relative(outDir, t.file)}" style="position:absolute;left:${t.x}px;top:${t.y}px;width:${t.w}px;height:${t.h}px;border-radius:14px">`).join('');
const sheet = join(dir, '.sheet.html');
await Bun.write(sheet, `<!doctype html><body style="margin:0;background:#141418;width:${lay.w}px;height:${lay.h}px;position:relative">${imgs}
<script>Promise.all([...document.images].map(i=>i.decode())).then(()=>document.body.dataset.ready='1')</script></body>`);
await withPage(p => shoot(p, `${base}/out/${relative(outDir, sheet)}`, lay.w, lay.h, join(dir, 'sheet.png')));
rmSync(sheet, { force: true });
});
} finally { } finally {
for (const p of pages) await p?.page.context().close().catch(() => {});
await browser.close(); await browser.close();
server.stop(true); server.stop(true);
if (Object.keys(report).length) await Bun.write(join(outDir, 'report.json'), JSON.stringify(mergeReport(readReport(outDir), report), null, 1) + '\n'); if (Object.keys(report).length) await Bun.write(join(outDir, 'report.json'), JSON.stringify(mergeReport(readReport(outDir), report), null, 1) + '\n');

View file

@ -52,6 +52,16 @@ in a plain Android tablet body instead of the iPad one.
`<shots.frames>/<lang>/<phone|tablet>/<shot>.png`, local, not committed. `<shots.frames>/<lang>/<phone|tablet>/<shot>.png`, local, not committed.
- `web` (default): `baseUrl`, `query` with `{lang}`, shots: `path` / `waitFor` / `eval` / `delayMs` / `device`. - `web` (default): `baseUrl`, `query` with `{lang}`, shots: `path` / `waitFor` / `eval` / `delayMs` / `device`.
Phone 440 x 902 @3x and tablet 800 x 1240 @2x by default; the template draws the status bar above. Phone 440 x 902 @3x and tablet 800 x 1240 @2x by default; the template draws the status bar above.
Speed (many languages): frames run in parallel browser contexts (`--concurrency N`, `capture.concurrency`;
default min(3, cores / 4) since game boots are GPU-heavy). `capture.session: 'per-language'` boots the app once
per language and device and switches shots in that page (per shot `navigate: 'spa'` = pushState + popstate to its
path, then `waitFor` / `eval`; `'reload'` = goto in the same page); a shot whose `waitFor` fails there within
`reuseTimeoutMs` (15000) gets a fresh page. Re-runs skip frames whose inputs did not change (shot entry, URL,
frame size, the language's copy, the build: `capture.build` files / folders, else the HTML and scripts at
`baseUrl`, fonts) via `.storebound/capture-cache.json`; `--only-missing` captures only missing files, `--force`
everything. Each progress line shows n/total, ETA and the time per step (goto, wait, eval, delay, shot); the end
lists the slowest frames and steps, and `.storebound/capture-report.json` keeps them. Put the slow step right
(a long `waitFor` = the game reaching the scene: add a URL switch that jumps there).
- `ios-sim` (Unity, Godot, Flutter, native, Capacitor: any Simulator build): `ios.device` (simulator name or UDID, - `ios-sim` (Unity, Godot, Flutter, native, Capacitor: any Simulator build): `ios.device` (simulator name or UDID,
e.g. a 6.9" iPhone), `ios.bundleId`, optional `ios.app` (.app to install), `ios.args`. Per shot: `args` (launch e.g. a 6.9" iPhone), `ios.bundleId`, optional `ios.app` (.app to install), `ios.args`. Per shot: `args` (launch
arguments, read them with UserDefaults / your engine) and / or `url` (deep link). Language goes in as arguments, read them with UserDefaults / your engine) and / or `url` (deep link). Language goes in as
@ -89,7 +99,7 @@ in a plain Android tablet body instead of the iPad one.
`{ bg, glow, ink, shadow }`), frames (one front phone + optional back phones with x / dy / scale / rotate), badge `{ bg, glow, ink, shadow }`), frames (one front phone + optional back phones with x / dy / scale / rotate), badge
slots (y, side, icon, hot, stars). Fonts default to Paytone One + Montserrat (game) or Inter (app): all cover slots (y, side, icon, hot, stars). Fonts default to Paytone One + Montserrat (game) or Inter (app): all cover
Latin Extended and Vietnamese. Latin Extended and Vietnamese.
6. **Render.** `storebound shots render --lang en` first, review `store/renders/en/sheet.png` (contact sheet, sizes 6. **Render.** (`--concurrency N`, default min(4, cores / 2) pages) `storebound shots render --lang en` first, review `store/renders/en/sheet.png` (contact sheet, sizes
packed into a grid), then packed into a grid), then
all languages in the background: `storebound shots render > .storebound/render.log 2>&1 &`. all languages in the background: `storebound shots render > .storebound/render.log 2>&1 &`.
7. **JPEG for Play.** `storebound shots jpeg` (q92, about 4x smaller than PNG; App Store stays PNG). 7. **JPEG for Play.** `storebound shots jpeg` (q92, about 4x smaller than PNG; App Store stays PNG).

179
tests/capture-web.test.ts Normal file
View file

@ -0,0 +1,179 @@
// `shots capture` (web) against a local fixture web app: parallel contexts give the same files as serial, the
// per-language session boots the app once per language, the input-hash cache skips unchanged frames and re-runs changed
// ones, and every frame has a timing breakdown. Pure helpers are tested without a browser. Skips the browser part when
// no Chromium can launch. The browser runs run in a `storebound` child process (its own Chromium), like a real run.
import { afterAll, describe, expect, test } from 'bun:test';
import { spawnSync } from 'node:child_process';
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { ShipConfig, ShotsCapture } from '../cli/lib/config';
import { type CaptureReport, defaultConcurrency, planWeb, pool, progressLine, selectJobs, timingSummary } from '../cli/shots/capture-web';
import { BASE } from './helpers/store-mock';
const CLI = join(import.meta.dir, '..', 'cli', 'index.ts');
describe('capture helpers', () => {
test('default concurrency: render min(4, cores/2), capture (GPU-heavy) min(3, cores/4), at least 1', () => {
expect(defaultConcurrency('render', 10)).toBe(4);
expect(defaultConcurrency('capture', 10)).toBe(2);
expect(defaultConcurrency('capture', 2)).toBe(1);
expect(defaultConcurrency('render', 1)).toBe(1);
});
test('pool keeps the input order and never runs more than n at once', async () => {
let now = 0, peak = 0;
const out = await pool([5, 1, 3, 2, 4], 2, async x => { now++; peak = Math.max(peak, now); await Bun.sleep(x * 3); now--; return x * 10; });
expect(out).toEqual([50, 10, 30, 20, 40]);
expect(peak).toBe(2);
});
test('progress line with an ETA', () => {
expect(progressLine(5, 20, 0, 10_000)).toBe(' 5/20 ETA 30.0s');
expect(progressLine(20, 20, 0, 10_000)).toBe('20/20');
});
test('cache selection: changed inputs and missing files run; --only-missing; --force', () => {
const cap: ShotsCapture = { source: 'web', baseUrl: 'http://x', shots: { a: { path: '/a' }, b: { path: '/b' } } };
const dims = { phone: { w: 10, h: 20, dpr: 1, bar: 0 }, tablet: { w: 10, h: 20, dpr: 1, bar: 0 } };
const jobs = planWeb(cap, { langs: ['en', 'tr'], devices: ['phone'], only: [], dims, framesDir: '/f', build: 'b1' });
expect(jobs.map(j => j.frame)).toEqual(['en/phone/a.png', 'en/phone/b.png', 'tr/phone/a.png', 'tr/phone/b.png']);
const cache = Object.fromEntries(jobs.map(j => [j.frame, j.hash]));
const all = () => true;
expect(selectJobs(jobs, cache, 'changed', all).run).toEqual([]);
const jobs2 = planWeb({ ...cap, shots: { ...cap.shots, b: { path: '/b', delayMs: 5 } } }, { langs: ['en', 'tr'], devices: ['phone'], only: [], dims, framesDir: '/f', build: 'b1' });
expect(selectJobs(jobs2, cache, 'changed', all).run.map(j => j.frame)).toEqual(['en/phone/b.png', 'tr/phone/b.png']);
const jobs3 = planWeb(cap, { langs: ['en', 'tr'], devices: ['phone'], only: [], dims, framesDir: '/f', build: 'b2' });
expect(selectJobs(jobs3, cache, 'changed', all).run.length).toBe(4);
expect(selectJobs(jobs3, cache, 'only-missing', (f: string) => !f.endsWith('tr/phone/a.png')).run.map(j => j.frame)).toEqual(['tr/phone/a.png']);
expect(selectJobs(jobs, cache, 'force', all).run.length).toBe(4);
});
test('timing summary: slowest frames with their slowest step, time per step', () => {
const t = (goto: number, waitFor: number) => ({ goto, waitFor, eval: 0, delay: 100, screenshot: 50, total: goto + waitFor + 150 });
const s = timingSummary([{ frame: 'en/phone/a.png', timing: t(1000, 200) }, { frame: 'en/phone/b.png', timing: t(100, 5000) }], 1);
expect(s.slowest).toEqual([{ frame: 'en/phone/b.png', total: 5250, step: 'waitFor' }]);
expect(s.steps).toEqual({ goto: 1100, waitFor: 5200, eval: 0, delay: 200, screenshot: 100 });
});
});
// ---- a local fixture web app: /scene/<name>?lang=xx, a SPA (popstate) that counts its boots ----
let boots = 0;
const server = Bun.serve({
port: 0, hostname: '127.0.0.1',
fetch(req) {
const u = new URL(req.url);
if (u.pathname === '/app.js') {
boots++;
return new Response(`
const COLORS = { en: '#1e66f5', de: '#40a02b', tr: '#d20f39' };
function show() {
const name = location.pathname.split('/').pop() || 'home', lang = new URLSearchParams(location.search).get('lang');
document.body.style.cssText = 'margin:0;background:' + (COLORS[lang] || '#000') + ';font:24px sans-serif;color:#fff';
document.body.innerHTML = '<div style="padding:20px">' + lang + ' ' + name + '</div><div style="margin:20px;width:' + (40 * name.length) + 'px;height:60px;background:#fff"></div>';
window.scene = null;
window.shows = (window.shows || 0) + 1;
setTimeout(() => { window.scene = name; }, 30);
}
addEventListener('popstate', show);
show();`, { headers: { 'content-type': 'text/javascript' } });
}
return new Response('<!doctype html><html><head><meta charset="utf-8"><script src="/app.js" defer></script></head><body></body></html>', { headers: { 'content-type': 'text/html' } });
},
});
afterAll(() => server.stop(true));
const canLaunch = spawnSync('bun', ['-e', `const { launch } = await import(${JSON.stringify(join(import.meta.dir, '..', 'cli', 'shots', 'browser.ts'))}); await (await launch(${JSON.stringify(join(import.meta.dir, '..'))}, { headless: true })).close();`], { timeout: 60_000 }).status === 0;
if (!canLaunch) console.warn('capture-web browser tests skipped: no Chromium could launch (bunx playwright install chromium)');
/** A temp project with this config; cli() runs `storebound shots capture <args>` in it. */
function project(cfg: ShipConfig, files: Record<string, string>): { root: string; setConfig: (c: ShipConfig) => void; cli: (args: string[]) => Promise<{ out: string; err: string; code: number }> } {
const root = mkdtempSync(join(tmpdir(), 'sb-cap-'));
for (const [p, t] of Object.entries(files)) { mkdirSync(join(root, p, '..'), { recursive: true }); writeFileSync(join(root, p), t); }
const setConfig = (c: ShipConfig) => writeFileSync(join(root, 'storebound.config.json'), JSON.stringify(c));
setConfig(cfg);
// async: the fixture server lives in this process and must keep answering while the child captures
return { root, setConfig, cli: async args => {
const r = Bun.spawn(['bun', CLI, 'shots', 'capture', ...args], { cwd: root, stdout: 'pipe', stderr: 'pipe', env: { ...process.env, NO_COLOR: '1' } });
const [out, err, code] = await Promise.all([new Response(r.stdout).text(), new Response(r.stderr).text(), r.exited]);
return { out, err, code };
} };
}
const shot = (name: string, extra: object = {}) => ({ path: `/scene/${name}`, waitFor: `window.scene === '${name}'`, delayMs: 20, ...extra });
function config(capture: Partial<ShotsCapture> = {}): ShipConfig {
return { ...BASE, shots: { copy: 'store/shots/copy.json', frames: 'store/shots/frames', out: 'store/renders', scenes: [{ id: 'hero', palette: 'fire', frames: [{ src: 'hero.png' }] }], phone: { w: 180, h: 240, dpr: 1 },
capture: { source: 'web', baseUrl: `http://127.0.0.1:${server.port}`, query: 'lang={lang}', build: 'src', shots: { hero: shot('hero'), battle: shot('battle'), king: shot('king') }, ...capture } } };
}
const files = { 'store/shots/copy.json': '{}', 'src/main.js': 'v1' };
const frames = (root: string) => ['en', 'de', 'tr'].flatMap(l => ['hero', 'battle', 'king'].map(n => join(root, 'store/shots/frames', l, 'phone', `${n}.png`)));
describe.skipIf(!canLaunch)('shots capture (web) with a fixture app', () => {
test('concurrency 3 gives the same files as serial', async () => {
const p = project(config(), files);
try {
await p.cli(['--device', 'phone', '--concurrency', '1', '--force']);
const serial = frames(p.root).map(f => readFileSync(f));
const r = await p.cli(['--device', 'phone', '--concurrency', '3', '--force']);
expect(r.out).toContain('capturing 9 frames, 3 at a time');
const parallel = frames(p.root).map(f => readFileSync(f));
expect(parallel.length).toBe(9);
for (const [i, b] of parallel.entries()) expect(Buffer.compare(b, serial[i]!)).toBe(0);
} finally { rmSync(p.root, { recursive: true, force: true }); }
}, 120_000);
test('per-language session boots the app once per language; per-shot once per frame', async () => {
const p = project(config({ session: 'per-language' }), files);
try {
boots = 0;
const r = await p.cli(['--device', 'phone', '--concurrency', '2', '--force']);
expect(boots).toBe(3);
expect(r.out).toContain('(reused page)');
const report = JSON.parse(readFileSync(join(p.root, '.storebound/capture-report.json'), 'utf8')) as CaptureReport;
expect(report.frames.filter(f => f.reused).length).toBe(6);
expect(frames(p.root).every(f => existsSync(f))).toBe(true);
// a shot whose precondition fails in the reused page (it needs a freshly booted page) falls back to a fresh page
const bad = project(config({ session: 'per-language', reuseTimeoutMs: 300, shots: { hero: shot('hero'), fresh: { path: '/scene/fresh', waitFor: "window.scene === 'fresh' && window.shows === 1", delayMs: 20 } } }), files);
try {
boots = 0;
const r2 = await bad.cli(['--device', 'phone', '--lang', 'en', '--force']);
expect(r2.err).toContain('en/phone/fresh: reused page failed');
expect(r2.out).toContain('capture done: 2 frames');
expect(boots).toBe(2);
} finally { rmSync(bad.root, { recursive: true, force: true }); }
boots = 0;
const q = project(config(), files);
await q.cli(['--device', 'phone', '--lang', 'en', '--force']);
rmSync(q.root, { recursive: true, force: true });
expect(boots).toBe(3);
} finally { rmSync(p.root, { recursive: true, force: true }); }
}, 180_000);
test('cache skips unchanged frames, re-runs changed ones; --only-missing; timing breakdown', async () => {
const p = project(config(), files);
try {
let r = await p.cli(['--device', 'phone']);
expect(r.out).toContain('capturing 9 frames');
expect(r.out).toMatch(/tr\/phone\/king\.png goto [\d.]+s wait [\d.]+s eval [\d.]+s delay [\d.]+s shot [\d.]+s = [\d.]+s/);
expect(r.out).toContain('time per step: goto');
expect(r.out).toContain('slowest: ');
const report = JSON.parse(readFileSync(join(p.root, '.storebound/capture-report.json'), 'utf8')) as CaptureReport;
expect(Object.keys(report.frames[0]!.timing).sort()).toEqual(['delay', 'eval', 'goto', 'screenshot', 'total', 'waitFor']);
expect(report.summary.slowest.length).toBe(5);
r = await p.cli(['--device', 'phone']);
expect(r.out).toContain('9 of 9 frames unchanged, skipped');
expect(r.out).toContain('capturing 0 frames');
// a changed shot entry re-runs only that shot (3 languages)
p.setConfig(config({ shots: { hero: shot('hero'), battle: shot('battle', { delayMs: 40 }), king: shot('king') } }));
r = await p.cli(['--device', 'phone']);
expect(r.out).toContain('6 of 9 frames unchanged');
expect(r.out).toContain('capturing 3 frames');
// a build change re-runs everything; --only-missing only the missing file
await Bun.write(join(p.root, 'src/main.js'), 'v2 changed');
rmSync(frames(p.root)[0]!);
r = await p.cli(['--device', 'phone', '--only-missing']);
expect(r.out).toContain('capturing 1 frames');
r = await p.cli(['--device', 'phone']);
expect(r.out).toContain('capturing 8 frames'); // the one just captured already has the new inputs
} finally { rmSync(p.root, { recursive: true, force: true }); }
}, 180_000);
});