@crvouga/atlas 0.0.0-stage → 0.2.0

package/dist/playwright/src/media.js

@@ -0,0 +1,283 @@
+import { spawn } from 'node:child_process';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { locate } from './signals.js';
+const isLocator = (target) => 'waitFor' in target;
+export const SHOWCASE_PACING = {
+    moveMs: 600,
+    pauseBeforeTapMs: 300,
+    typeDelayMs: 60,
+    holdAfterMs: 1000,
+    holdBeforeMs: 500
+};
+export const FAST_PACING = {
+    moveMs: 0,
+    pauseBeforeTapMs: 0,
+    typeDelayMs: 0,
+    holdAfterMs: 0,
+    holdBeforeMs: 0
+};
+export const PHONE = {
+    viewport: { width: 390, height: 844 },
+    deviceScaleFactor: 3,
+    isMobile: true,
+    hasTouch: true
+};
+/**
+ * A soft touch indicator for videos: a dot that glides to each tap target, a pressed state, and a
+ * ripple. It lives in its own fixed layer and is hidden for screenshots.
+ */
+const TOUCH_OVERLAY = `(() => {
+  if (window.__specTouch) return;
+  const install = () => {
+    const layer = document.createElement('div');
+    layer.setAttribute('data-spec-touch', '');
+    layer.style.cssText = 'position:fixed;inset:0;pointer-events:none;z-index:2147483647;';
+    const dot = document.createElement('div');
+    dot.style.cssText = 'position:absolute;width:34px;height:34px;margin:-17px 0 0 -17px;border-radius:50%;background:rgba(124,58,237,.28);border:2px solid rgba(124,58,237,.75);box-shadow:0 2px 10px rgba(76,29,149,.25);opacity:0;transition:opacity .2s, transform .12s;left:50%;top:70%;';
+    layer.appendChild(dot);
+    document.documentElement.appendChild(layer);
+    let x = window.innerWidth / 2, y = window.innerHeight * 0.7;
+    window.__specTouch = {
+      move(tx, ty, ms) {
+        dot.style.opacity = '1';
+        return new Promise((resolve) => {
+          const sx = x, sy = y, start = performance.now();
+          const step = (now) => {
+            const t = ms <= 0 ? 1 : Math.min(1, (now - start) / ms);
+            const e = t < .5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2;
+            x = sx + (tx - sx) * e; y = sy + (ty - sy) * e;
+            dot.style.left = x + 'px'; dot.style.top = y + 'px';
+            if (t < 1) requestAnimationFrame(step); else resolve();
+          };
+          requestAnimationFrame(step);
+        });
+      },
+      press(down) { dot.style.transform = down ? 'scale(.78)' : 'scale(1)'; dot.style.background = down ? 'rgba(124,58,237,.5)' : 'rgba(124,58,237,.28)'; },
+      ripple() {
+        const r = document.createElement('div');
+        r.style.cssText = 'position:absolute;width:34px;height:34px;margin:-17px 0 0 -17px;border-radius:50%;border:2px solid rgba(124,58,237,.6);left:' + x + 'px;top:' + y + 'px;transition:transform .5s ease-out, opacity .5s ease-out;';
+        layer.appendChild(r);
+        requestAnimationFrame(() => { r.style.transform = 'scale(2.6)'; r.style.opacity = '0'; });
+        setTimeout(() => r.remove(), 600);
+      },
+      visible(on) { layer.style.display = on ? 'block' : 'none'; }
+    };
+  };
+  if (document.documentElement) install(); else document.addEventListener('DOMContentLoaded', install);
+})();`;
+/** Taps and typing a person would do, paced for showcase videos and logged to the step timeline. */
+export class UserActions {
+    page;
+    pacing;
+    timeline;
+    showTouches;
+    constructor(page, pacing, timeline, showTouches) {
+        this.page = page;
+        this.pacing = pacing;
+        this.timeline = timeline;
+        this.showTouches = showTouches;
+    }
+    static async install(page) {
+        await page.addInitScript(TOUCH_OVERLAY);
+    }
+    async overlay(fn, ...args) {
+        if (!this.showTouches)
+            return undefined;
+        return this.page
+            .evaluate(({ fn, args }) => {
+            const touch = window.__specTouch;
+            return touch?.[fn]?.(...args);
+        }, { fn, args })
+            .catch(() => undefined);
+    }
+    /** Tap a locator or a signal (resolved with `locate`). */
+    async tap(target, label) {
+        const locator = isLocator(target) ? target : locate(this.page, target);
+        await locator.waitFor({ state: 'visible', timeout: 15_000 });
+        await locator.scrollIntoViewIfNeeded().catch(() => undefined);
+        const box = await locator.boundingBox();
+        if (!box)
+            throw new Error(`"${label}" has no position on screen`);
+        const x = Math.round(box.x + box.width / 2);
+        const y = Math.round(box.y + box.height / 2);
+        if (this.showTouches) {
+            await this.overlay('move', x, y, this.pacing.moveMs);
+            await this.page.waitForTimeout(this.pacing.pauseBeforeTapMs);
+            await this.overlay('press', true);
+        }
+        this.timeline.add({ kind: 'tap', label, x, y });
+        await locator.click({ timeout: 10_000 });
+        if (this.showTouches) {
+            await this.overlay('ripple');
+            await this.overlay('press', false);
+        }
+    }
+    async type(target, text, label) {
+        const locator = isLocator(target) ? target : locate(this.page, target);
+        await this.tap(locator, label);
+        this.timeline.add({ kind: 'type', label, text });
+        await locator.fill('');
+        await locator.pressSequentially(text, { delay: this.pacing.typeDelayMs });
+    }
+    async hold(ms) {
+        if (ms > 0)
+            await this.page.waitForTimeout(ms);
+    }
+    async hideTouches() {
+        await this.overlay('visible', false);
+    }
+    async showTouchLayer() {
+        await this.overlay('visible', true);
+    }
+}
+/** A settled, deterministic capture at device resolution, with the touch layer hidden. */
+export async function captureScreen(page, driver, file, mask = []) {
+    mkdirSync(path.dirname(file), { recursive: true });
+    await page.waitForLoadState('networkidle', { timeout: 5_000 }).catch(() => undefined);
+    await page.evaluate(() => document.fonts.ready.then(() => undefined)).catch(() => undefined);
+    await driver.hideTouches();
+    await page.screenshot({
+        path: file,
+        animations: 'disabled',
+        caret: 'hide',
+        scale: 'device',
+        mask
+    });
+    await driver.showTouchLayer();
+    const webp = file.replace(/\.png$/, '.webp');
+    await ffmpeg([
+        '-y',
+        '-loglevel',
+        'error',
+        '-i',
+        file,
+        '-vf',
+        'scale=400:-2',
+        '-quality',
+        '82',
+        webp
+    ]);
+    return { png: file, webp };
+}
+export function ffmpeg(args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('ffmpeg', args, { stdio: ['ignore', 'ignore', 'pipe'] });
+        let stderr = '';
+        child.stderr.on('data', (chunk) => (stderr += chunk.toString()));
+        child.on('error', reject);
+        child.on('close', (code) => code === 0 ? resolve() : reject(new Error(`ffmpeg ${code}: ${stderr}`)));
+    });
+}
+/**
+ * Records a clip at the phone's physical resolution (1170×2532). Chrome's screencast, and
+ * Playwright's built-in video that rides on it, only deliver CSS-pixel frames (390×844) and
+ * upscale them, so text goes soft. Instead this loops device-scale JPEG captures (about 20 fps
+ * here), keeps each frame's own timestamp, and encodes H.264 at 30 fps, holding each frame for as
+ * long as it was on screen. The first frame becomes the poster.
+ */
+export class ScreencastRecorder {
+    page;
+    scale;
+    session = null;
+    frames = [];
+    directory = '';
+    stoppedAt = 0;
+    running = false;
+    loop = null;
+    constructor(page, scale = PHONE.deviceScaleFactor) {
+        this.page = page;
+        this.scale = scale;
+    }
+    async start(workDirectory) {
+        this.directory = workDirectory;
+        rmSync(workDirectory, { recursive: true, force: true });
+        mkdirSync(workDirectory, { recursive: true });
+        this.frames = [];
+        this.session = await this.page.context().newCDPSession(this.page);
+        const { width, height } = this.page.viewportSize() ?? PHONE.viewport;
+        const clip = { x: 0, y: 0, width, height, scale: this.scale };
+        this.running = true;
+        const session = this.session;
+        this.loop = (async () => {
+            while (this.running) {
+                const at = Date.now();
+                const shot = await session
+                    .send('Page.captureScreenshot', {
+                    format: 'jpeg',
+                    quality: 90,
+                    clip,
+                    optimizeForSpeed: true
+                })
+                    .catch(() => null);
+                if (!shot) {
+                    await new Promise((r) => setTimeout(r, 30));
+                    continue;
+                }
+                const file = path.join(this.directory, `f${String(this.frames.length).padStart(5, '0')}.jpg`);
+                writeFileSync(file, Buffer.from(shot.data, 'base64'));
+                this.frames.push({ file, at });
+            }
+        })();
+    }
+    async stop(output) {
+        this.stoppedAt = Date.now();
+        this.running = false;
+        await this.loop;
+        if (this.session) {
+            await this.session.detach().catch(() => undefined);
+            this.session = null;
+        }
+        if (this.frames.length === 0)
+            return null;
+        const list = this.frames
+            .map((frame, i) => {
+            const next = this.frames[i + 1]?.at ?? this.stoppedAt;
+            const seconds = Math.max(1 / 30, (next - frame.at) / 1000);
+            return `file '${frame.file}'\nduration ${seconds.toFixed(3)}`;
+        })
+            .join('\n');
+        const last = this.frames.at(-1).file;
+        const concat = path.join(this.directory, 'frames.txt');
+        writeFileSync(concat, `${list}\nfile '${last}'\n`);
+        mkdirSync(path.dirname(output), { recursive: true });
+        await ffmpeg([
+            '-y',
+            '-loglevel',
+            'error',
+            '-f',
+            'concat',
+            '-safe',
+            '0',
+            '-i',
+            concat,
+            '-vf',
+            'fps=30,scale=trunc(iw/2)*2:trunc(ih/2)*2,format=yuv420p',
+            '-c:v',
+            'libx264',
+            '-preset',
+            'slow',
+            '-crf',
+            '18',
+            '-movflags',
+            '+faststart',
+            output
+        ]);
+        const poster = output.replace(/\.mp4$/, '.poster.webp');
+        await ffmpeg([
+            '-y',
+            '-loglevel',
+            'error',
+            '-i',
+            this.frames[0].file,
+            '-vf',
+            'scale=600:-2',
+            '-quality',
+            '82',
+            poster
+        ]);
+        const durationMs = this.stoppedAt - this.frames[0].at;
+        rmSync(this.directory, { recursive: true, force: true });
+        return { video: output, poster, durationMs };
+    }
+}

package/dist/playwright/src/signals.d.ts

@@ -0,0 +1,34 @@
+import type { CheckResult, RecognizerResult, StateImplementation } from '../../core/src/index.js';
+import type { Signal } from '../../core/src/signals.js';
+import type { Locator, Page } from 'playwright';
+export { css, describeSignal, label, role, testId, text, type Signal } from '../../core/src/signals.js';
+/** A signal as a Playwright locator: the first visible match, with Playwright's own role and text rules. */
+export declare function locate(page: Page, signal: Signal): Locator;
+export type SignatureSpec = {
+    all?: Signal[];
+    any?: Signal[];
+    none?: Signal[];
+};
+/** Recognise a state from its UI signature: every `all` visible, one `any` visible, no `none`. */
+export declare function recognize(page: Page, spec: SignatureSpec): Promise<RecognizerResult>;
+/** Checks that a quoted piece of the spec is on screen; records expected and actual on failure. */
+export declare function checkSignals(page: Page, checks: {
+    check: string;
+    signal: Signal;
+}[]): Promise<CheckResult[]>;
+/**
+ * A state implementation from a UI signature, for a context that exposes `page`. Extra fields
+ * (`lookIn`, `settle`, `transient`, `sameAs`, `checks`) pass through.
+ */
+export declare function screen<C extends {
+    page: Page;
+}>(spec: SignatureSpec & {
+    checks?: {
+        check: string;
+        signal: Signal;
+    }[];
+    transient?: boolean;
+    sameAs?: string;
+    lookIn?: (ctx: C) => Promise<void>;
+    settle?: (ctx: C) => Promise<void>;
+}): StateImplementation<C>;

package/dist/playwright/src/signals.js

@@ -0,0 +1,56 @@
+import { describeSignal } from '../../core/src/signals.js';
+export { css, describeSignal, label, role, testId, text } from '../../core/src/signals.js';
+/** A signal as a Playwright locator: the first visible match, with Playwright's own role and text rules. */
+export function locate(page, signal) {
+    if ('testId' in signal)
+        return page.getByTestId(signal.testId).filter({ visible: true }).first();
+    if ('role' in signal) {
+        const options = { ...(signal.name ? { name: signal.name } : {}), ...(signal.exact ? { exact: true } : {}) };
+        return page.getByRole(signal.role, options).filter({ visible: true }).first();
+    }
+    if ('label' in signal)
+        return page.getByLabel(signal.label).filter({ visible: true }).first();
+    if ('css' in signal)
+        return page.locator(signal.css).filter({ visible: true }).first();
+    return page.getByText(signal.text, signal.exact ? { exact: true } : {}).filter({ visible: true }).first();
+}
+const isVisible = (page, signal) => locate(page, signal).isVisible().catch(() => false);
+/** Recognise a state from its UI signature: every `all` visible, one `any` visible, no `none`. */
+export async function recognize(page, spec) {
+    const signals = [];
+    for (const s of spec.all ?? [])
+        signals.push({ signal: describeSignal(s), expected: 'visible', visible: await isVisible(page, s) });
+    if (spec.any?.length) {
+        let seen = false;
+        for (const s of spec.any)
+            if (await isVisible(page, s))
+                seen = true;
+        signals.push({ signal: `one of: ${spec.any.map(describeSignal).join(' | ')}`, expected: 'visible', visible: seen });
+    }
+    for (const s of spec.none ?? [])
+        signals.push({ signal: describeSignal(s), expected: 'hidden', visible: await isVisible(page, s) });
+    return { matched: signals.every((x) => (x.expected === 'visible' ? x.visible : !x.visible)), signals };
+}
+/** Checks that a quoted piece of the spec is on screen; records expected and actual on failure. */
+export async function checkSignals(page, checks) {
+    const results = [];
+    for (const { check, signal } of checks) {
+        const visible = await isVisible(page, signal);
+        results.push({ check, passed: visible, expected: `${describeSignal(signal)} visible`, actual: visible ? 'visible' : 'not on screen' });
+    }
+    return results;
+}
+/**
+ * A state implementation from a UI signature, for a context that exposes `page`. Extra fields
+ * (`lookIn`, `settle`, `transient`, `sameAs`, `checks`) pass through.
+ */
+export function screen(spec) {
+    return {
+        recognize: (ctx) => recognize(ctx.page, spec),
+        ...(spec.checks ? { checks: (ctx) => checkSignals(ctx.page, spec.checks) } : {}),
+        ...(spec.transient ? { transient: true } : {}),
+        ...(spec.sameAs ? { sameAs: spec.sameAs } : {}),
+        ...(spec.lookIn ? { lookIn: spec.lookIn } : {}),
+        ...(spec.settle ? { settle: spec.settle } : {})
+    };
+}

package/dist/reports/src/browser-navigation.d.ts

@@ -0,0 +1,2 @@
+import type { ReportNavigation } from './navigation.js';
+export declare function browserReportNavigation(): ReportNavigation;

package/dist/reports/src/browser-navigation.js

@@ -0,0 +1,28 @@
+export function browserReportNavigation() {
+    return {
+        readHash: () => window.location.hash,
+        writeHash: (hash, replace) => {
+            if (window.location.hash === hash)
+                return;
+            if (replace)
+                window.history.replaceState(null, '', hash);
+            else
+                window.history.pushState(null, '', hash);
+        },
+        subscribeHash: (listener) => {
+            window.addEventListener('hashchange', listener);
+            window.addEventListener('popstate', listener);
+            return () => {
+                window.removeEventListener('hashchange', listener);
+                window.removeEventListener('popstate', listener);
+            };
+        },
+        subscribeKeys: (listener) => {
+            window.addEventListener('keydown', listener);
+            return () => window.removeEventListener('keydown', listener);
+        },
+        setTitle: (title) => {
+            document.title = title;
+        },
+    };
+}

package/dist/reports/src/bundle.d.ts

@@ -0,0 +1,24 @@
+import type { ObjectStore } from './object-store.js';
+export declare const BUNDLE_BYTES: number;
+type Location = {
+    blob: string;
+    offset: number;
+    size: number;
+};
+export type BundleIndex = Record<string, {
+    contentType: string;
+    parts: Location[];
+}>;
+export type BundleEntry = {
+    key: string;
+    bytes: Uint8Array;
+    contentType: string;
+};
+export declare function bundleIndexKey(sha: string, source: string): string;
+/** Four bounded compressed chunks in flight, with one small index published last. */
+export declare function publishBundle(store: ObjectStore, key: string, entries: AsyncIterable<BundleEntry>): Promise<void>;
+export declare function writeBundle(store: ObjectStore, entries: AsyncIterable<BundleEntry>, prefix: string): Promise<BundleIndex>;
+/** Cache only immutable blobs; mutable indexes are read for each request. */
+export declare function createBundleReader(store: ObjectStore, index: BundleIndex): (key: string) => Promise<BundleEntry | null>;
+export declare function readBundleIndex(store: ObjectStore, key: string): Promise<BundleIndex>;
+export {};

package/dist/reports/src/bundle.js

@@ -0,0 +1,114 @@
+import { readObjectBytes, readUtf8, writeUtf8, } from './object-io.js';
+import { eachLimitedStream } from './completion-order.js';
+export const BUNDLE_BYTES = 4 * 1024 * 1024;
+export function bundleIndexKey(sha, source) {
+    return `commits/${sha}/bundles/${source}.json`;
+}
+async function transform(bytes, decompress) {
+    const buffer = new Uint8Array(bytes).buffer;
+    const stream = new Blob([buffer]).stream();
+    const output = decompress
+        ? stream.pipeThrough(new DecompressionStream('gzip'))
+        : stream.pipeThrough(new CompressionStream('gzip'));
+    return new Uint8Array(await new Response(output).arrayBuffer());
+}
+async function flush(store, entries, index, writes) {
+    const bytes = new Uint8Array(entries.reduce((size, entry) => size + entry.bytes.length, 0));
+    const locations = [];
+    let offset = 0;
+    for (const entry of entries) {
+        bytes.set(entry.bytes, offset);
+        const location = { blob: '', offset, size: entry.bytes.length };
+        (index[entry.key] ??= {
+            contentType: entry.contentType,
+            parts: [],
+        }).parts.push(location);
+        locations.push(location);
+        offset += entry.bytes.length;
+    }
+    const compressed = await transform(bytes, false);
+    // Some runtimes put wall time in gzip's MTIME header. Canonicalize it;
+    // content identity depends only on the uncompressed bytes.
+    compressed.fill(0, 4, 8);
+    const digest = await crypto.subtle.digest('SHA-256', bytes.buffer);
+    const hash = Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('');
+    const blob = `${writes.prefix}${hash}.gz`;
+    for (const location of locations)
+        location.blob = blob;
+    // Identical chunks and reruns reuse the same bytes: HEAD is Class B;
+    // writing the same content again would still incur a Class A operation.
+    let upload = writes.pending.get(blob);
+    if (upload === undefined) {
+        upload = uploadBlob(store, blob, compressed);
+        writes.pending.set(blob, upload);
+    }
+    await upload;
+}
+async function uploadBlob(store, blob, bytes) {
+    if (!(await store.head(blob)))
+        await store.put(blob, bytes, 'application/gzip');
+}
+async function* chunks(entries) {
+    let pending = [];
+    let size = 0;
+    for await (const entry of entries) {
+        for (let offset = 0; offset < Math.max(1, entry.bytes.length);) {
+            const bytes = entry.bytes.slice(offset, offset + BUNDLE_BYTES - size);
+            pending.push({ ...entry, bytes });
+            size += bytes.length;
+            offset += Math.max(1, bytes.length);
+            if (size === BUNDLE_BYTES) {
+                yield pending;
+                pending = [];
+                size = 0;
+            }
+        }
+    }
+    if (pending.length > 0)
+        yield pending;
+}
+/** Four bounded compressed chunks in flight, with one small index published last. */
+export async function publishBundle(store, key, entries) {
+    const index = await writeBundle(store, entries, `${key.slice(0, key.indexOf('/bundles/'))}/blobs/`);
+    await writeUtf8(store, key, JSON.stringify(index), 'application/json');
+}
+export async function writeBundle(store, entries, prefix) {
+    const index = {};
+    const writes = { prefix, pending: new Map() };
+    await eachLimitedStream(chunks(entries), 4, chunk => flush(store, chunk, index, writes));
+    return index;
+}
+/** Cache only immutable blobs; mutable indexes are read for each request. */
+export function createBundleReader(store, index) {
+    const cache = new Map();
+    return async (key) => {
+        const location = index[key];
+        if (location === undefined)
+            return null;
+        const chunks = [];
+        for (const part of location.parts) {
+            let pending = cache.get(part.blob);
+            if (pending === undefined) {
+                if (cache.size >= 4)
+                    cache.delete(cache.keys().next().value ?? '');
+                pending = readObjectBytes(store, part.blob).then((bytes) => bytes === null ? null : transform(bytes, true));
+                cache.set(part.blob, pending);
+            }
+            const bytes = await pending;
+            if (bytes === null)
+                return null;
+            chunks.push(bytes.slice(part.offset, part.offset + part.size));
+        }
+        const bytes = new Uint8Array(chunks.reduce((size, chunk) => size + chunk.length, 0));
+        let offset = 0;
+        for (const chunk of chunks) {
+            bytes.set(chunk, offset);
+            offset += chunk.length;
+        }
+        return { key, bytes, contentType: location.contentType };
+    };
+}
+export async function readBundleIndex(store, key) {
+    const text = await readUtf8(store, key);
+    return text === null ? {} : JSON.parse(text);
+}

package/dist/reports/src/catalog.d.ts

@@ -0,0 +1,37 @@
+/** Shared search, filter, group and sort for reports and the tests inside one. */
+export type CatalogStatus = 'all' | 'passed' | 'failed' | 'skipped' | 'running';
+export type CatalogGroup = 'none' | 'file' | 'status' | 'package' | 'runtime';
+export type CatalogSort = 'recent' | 'name' | 'duration' | 'status';
+export type CatalogLayout = 'list' | 'grid';
+export type CatalogQuery = {
+    readonly q: string;
+    readonly status: CatalogStatus;
+    readonly group: CatalogGroup;
+    readonly sort: CatalogSort;
+    readonly layout: CatalogLayout;
+};
+export type CatalogEntity = {
+    readonly id: string;
+    readonly title: string;
+    readonly status: string;
+    readonly durationMs: number | null;
+    /** Group label for `file` (a source file, or a branch). */
+    readonly file: string;
+    readonly packageName: string;
+    readonly runtime: string;
+    /** One muted line under the title: a failure, or a date. */
+    readonly detail: string;
+    readonly search: string;
+    readonly href: string | null;
+};
+export type CatalogGroupView = {
+    readonly name: string;
+    readonly durationMs: number;
+    readonly failed: number;
+    readonly entities: readonly CatalogEntity[];
+};
+export declare function catalogCounts(entities: readonly CatalogEntity[]): Record<CatalogStatus, number>;
+/** The list's search params, dropped when a test route carries frame and zoom. */
+export declare function catalogParams(params: Readonly<Record<string, string>>): Record<string, string>;
+/** Filter, sort, then one group per chosen key. `recent` keeps input order. */
+export declare function arrangeCatalog(entities: readonly CatalogEntity[], query: CatalogQuery): readonly CatalogGroupView[];