@crvouga/atlas 0.0.0-stage → 0.2.0

package/dist/reports/src/layers-route.js

@@ -0,0 +1,259 @@
+import { Hono } from 'hono';
+import { createBundleReader } from './bundle.js';
+import { eachLimited } from './completion-order.js';
+import { createLiveEvidence } from './evidence-live.js';
+import { isFramePath, isKeySegment } from './keys.js';
+import { catalogEntries, catalogLayers } from './layer-catalog.js';
+import { layerEvidence } from './layer-merge.js';
+import { readLayer } from './layer-store.js';
+import { readBytes, readUtf8 } from './object-io.js';
+import { SPEC_RUN_ID } from './publish.js';
+import { testFrameKey, testReportKey } from './recording-keys.js';
+const TTL = 30_000;
+const LOCAL_TTL = 1_500;
+const PAGE = 40;
+const CACHED_ENTRIES = 4_096;
+export const LOCAL_BACKEND = 'local';
+export const SHARED_BACKEND = 'shared';
+/** The stores that contribute layers, in the order they answer for a recording. */
+export function reportBackends(deps) {
+    const backends = [];
+    if (deps.localStore)
+        backends.push({ id: LOCAL_BACKEND, label: 'This machine', store: deps.localStore, live: true });
+    if (deps.store && deps.store !== deps.localStore)
+        backends.push({ id: SHARED_BACKEND, label: 'Shared reports', store: deps.store, live: false });
+    for (const backend of deps.backends ?? []) {
+        if (!/^[a-z0-9-]+$/.test(backend.id) || backends.some(known => known.id === backend.id))
+            throw new Error(`Invalid report backend id: "${backend.id}"`);
+        backends.push({ ...backend, live: false });
+    }
+    return backends;
+}
+function archived(id) {
+    return /^[0-9a-f]{64}$/.test(id);
+}
+/** Bounded pages of layer origins, each layer's checks read once, and the runs still writing. */
+export function createLayersApp(deps) {
+    const backends = reportBackends(deps);
+    const listings = backends.map(() => undefined);
+    let pending = null;
+    const loaded = new Map();
+    const readers = new Map();
+    const live = createLiveEvidence({ live: deps.live, clock: deps.clock, backend: LOCAL_BACKEND });
+    function freshFor(backend) {
+        return backend.live ? LOCAL_TTL : TTL;
+    }
+    async function discover() {
+        pending ??= (async () => {
+            const now = deps.clock.now();
+            await Promise.all(backends.map(async (backend, i) => {
+                const prior = listings[i];
+                if (prior && now - prior.at < freshFor(backend))
+                    return;
+                try {
+                    listings[i] = { at: now, keys: await catalogEntries(backend.store), available: true };
+                }
+                catch {
+                    // Keep what was listed before; the next refresh after the wait tries again.
+                    listings[i] = { at: now, keys: prior?.keys ?? [], available: false };
+                }
+            }));
+            const entries = listings.flatMap((listing, backend) => (listing?.keys ?? []).map(key => ({ backend, key })));
+            // Immutable layers first, newest first: their index keys start with an inverted time.
+            return entries.sort((a, b) => Number(b.key.startsWith('layer:')) - Number(a.key.startsWith('layer:')) || (a.key < b.key ? -1 : a.key > b.key ? 1 : a.backend - b.backend));
+        })();
+        try {
+            return await pending;
+        }
+        finally {
+            pending = null;
+        }
+    }
+    /** An immutable layer is read once. A commit's mutable parts are re-read after a short wait. */
+    function entryEvidence(entry) {
+        const backend = backends[entry.backend];
+        const cacheKey = `${backend.id}|${entry.key}`;
+        const cached = loaded.get(cacheKey);
+        if (cached && (entry.key.startsWith('layer:') || deps.clock.now() - cached.at < freshFor(backend)))
+            return cached.value;
+        const value = catalogLayers(backend.store, entry.key).then(layers => layers.map(layer => layerEvidence(layer, backend.id)));
+        value.catch(() => {
+            if (loaded.get(cacheKey)?.value === value)
+                loaded.delete(cacheKey);
+        });
+        if (!cached && loaded.size >= CACHED_ENTRIES)
+            loaded.delete(loaded.keys().next().value);
+        loaded.set(cacheKey, { at: deps.clock.now(), value });
+        return value;
+    }
+    async function findEvidence(backend, id) {
+        const own = backends[backend].id === LOCAL_BACKEND ? live.find(id) : null;
+        if (own)
+            return own;
+        const sha = /^(?:source|part)-([0-9a-f]{40})-/.exec(id)?.[1];
+        const key = archived(id)
+            ? (await discover()).find(entry => entry.backend === backend && entry.key.endsWith(`-${id}.json`))?.key
+            : sha && `commit:${sha}`;
+        if (!key)
+            return null;
+        try {
+            return (await entryEvidence({ backend, key })).find(evidence => evidence.id === id) ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async function file(id, path) {
+        if (!archived(id))
+            return null;
+        let reader = readers.get(id);
+        if (!reader) {
+            for (const backend of backends) {
+                const layer = await readLayer(backend.store, id);
+                if (!layer)
+                    continue;
+                reader = createBundleReader(backend.store, layer.bundle);
+                if (readers.size >= 8)
+                    readers.delete(readers.keys().next().value);
+                readers.set(id, reader);
+                break;
+            }
+        }
+        return reader?.(path) ?? null;
+    }
+    async function activeRecords() {
+        const local = deps.localStore;
+        if (!local)
+            return [];
+        const runs = await Promise.all((await local.listKeys('active/')).map(async (key) => {
+            try {
+                const raw = await readUtf8(local, key);
+                if (raw === null)
+                    return null;
+                const run = JSON.parse(raw);
+                if (!run.packageDir || !run.bucket || typeof run.startedAtMs !== 'number')
+                    return null;
+                return { packageDir: run.packageDir, bucket: run.bucket, startedAtMs: run.startedAtMs, ...(typeof run.plannedChecks === 'number' ? { plannedChecks: run.plannedChecks } : {}) };
+            }
+            catch {
+                return null;
+            }
+        }));
+        return runs.filter(run => run !== null);
+    }
+    let outlineAt = -Infinity;
+    let outlinePending;
+    function currentOutline() {
+        if (!outlinePending || deps.clock.now() - outlineAt >= TTL) {
+            outlineAt = deps.clock.now();
+            outlinePending = deps.outline?.().catch(error => { outlinePending = undefined; throw error; });
+        }
+        return outlinePending;
+    }
+    const app = new Hono();
+    app.get('/outline', async (c) => {
+        const outline = await currentOutline();
+        if (!outline)
+            return c.json({ error: 'Current spec outline is unavailable' }, 503);
+        return c.json({ specs: outline.specs, sha: outline.sha, changedFiles: outline.changedFiles }, 200, { 'cache-control': 'no-cache' });
+    });
+    app.get('/outline/spec', async (c) => {
+        const outline = await currentOutline();
+        const path = c.req.query('path') ?? '';
+        if (!outline?.specs.some(entry => entry.path === path))
+            return c.notFound();
+        const text = await outline.readSpec(path);
+        return text === null ? c.notFound() : c.text(text);
+    });
+    app.get('/evidence', async (c) => {
+        const cursor = c.req.query('cursor') ?? '';
+        // Asking again reaches a store that was unavailable without waiting out its listing.
+        if (c.req.query('retry'))
+            for (const [i, listing] of listings.entries())
+                if (listing && !listing.available)
+                    listings[i] = { ...listing, at: -Infinity };
+        const entries = await discover();
+        const ref = (entry) => `${backends[entry.backend].id}:${entry.key}`;
+        const after = cursor ? entries.findIndex(entry => ref(entry) === cursor) + 1 : 0;
+        if (cursor && after === 0)
+            return c.json({ error: 'Layer catalog changed; refresh the report.' }, 409);
+        const selected = entries.slice(after, after + PAGE);
+        const layers = [];
+        const notices = [];
+        if (!backends.length)
+            notices.push('No report store is configured.');
+        for (const [i, listing] of listings.entries())
+            if (listing && !listing.available)
+                notices.push(`${backends[i].label} is unavailable. Layers already loaded remain usable.`);
+        await eachLimited(selected, 8, async (entry) => {
+            try {
+                for (const evidence of await entryEvidence(entry))
+                    layers.push(evidence.layer);
+            }
+            catch {
+                notices.push('A report layer could not be loaded. Its outcome is unknown.');
+            }
+        });
+        let active = [];
+        if (!cursor) {
+            const running = await live.refresh(await activeRecords(), layers);
+            layers.push(...running.layers.map(evidence => evidence.layer));
+            active = running.active;
+        }
+        layers.sort((a, b) => b.recordedAtMs - a.recordedAtMs || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+        const last = selected.at(-1);
+        const info = backends.map((backend, i) => ({ id: backend.id, label: backend.label, live: backend.live, available: listings[i]?.available ?? false }));
+        const page = { layers, notices: [...new Set(notices)], backends: info, active, cursor: after + PAGE < entries.length && last ? ref(last) : null };
+        return c.json(page, 200, { 'cache-control': 'no-cache' });
+    });
+    app.get('/evidence/rows/:backend/:id', async (c) => {
+        const backend = backends.findIndex(known => known.id === c.req.param('backend'));
+        const id = c.req.param('id');
+        const evidence = backend < 0 ? null : await findEvidence(backend, id);
+        if (!evidence)
+            return c.notFound();
+        const rows = { id: evidence.id, rows: evidence.rows, fingerprints: evidence.fingerprints };
+        return c.json(rows, 200, { 'cache-control': archived(id) ? 'public, max-age=31536000, immutable' : 'no-cache' });
+    });
+    app.get('/layers/:id/*', async (c) => {
+        const id = c.req.param('id');
+        let path;
+        try {
+            path = decodeURIComponent(new URL(c.req.url).pathname.split(`/layers/${id}/`)[1] ?? '');
+        }
+        catch {
+            return c.json({ error: 'Invalid recording path' }, 400);
+        }
+        const valid = path === 'frame.css' || /^tests\/[a-zA-Z0-9._-]+\/report\.json$/.test(path) || (path.startsWith('tests/') && isKeySegment(path.split('/')[1] ?? '') && path.split('/')[2] === 'files' && isFramePath(path.split('/').slice(3).join('/')));
+        if (!valid)
+            return c.notFound();
+        const body = await file(id, path);
+        return body ? new Response(new Uint8Array(body.bytes), { headers: { 'content-type': body.contentType, 'cache-control': 'public, max-age=31536000, immutable' } }) : c.notFound();
+    });
+    app.get('/live/:source/frame.css', async (c) => {
+        const css = live.store(c.req.param('source')) ? await deps.live?.frameCss?.() : null;
+        return css == null ? c.notFound() : c.body(css, 200, { 'content-type': 'text/css; charset=utf-8', 'cache-control': 'no-store' });
+    });
+    app.get('/live/:source/tests/:testId/*', async (c) => {
+        const source = c.req.param('source');
+        const testId = c.req.param('testId');
+        const store = isKeySegment(testId) ? live.store(source) : null;
+        if (!store)
+            return c.notFound();
+        let path;
+        try {
+            path = decodeURIComponent(new URL(c.req.url).pathname.split(`/tests/${testId}/`)[1] ?? '');
+        }
+        catch {
+            return c.json({ error: 'Invalid recording path' }, 400);
+        }
+        const frame = path.startsWith('files/') ? path.slice('files/'.length) : null;
+        if (path !== 'report.json' && !(frame && isFramePath(frame)))
+            return c.notFound();
+        const stored = await store.get(frame ? testFrameKey(SPEC_RUN_ID, testId, frame) : testReportKey(SPEC_RUN_ID, testId));
+        if (stored === null)
+            return c.notFound();
+        return new Response(new Uint8Array(await readBytes(stored.body)), { headers: { 'content-type': stored.contentType, 'cache-control': 'no-store' } });
+    });
+    return app;
+}

package/dist/reports/src/namespace-guard.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Validates a wire key before any remote object-store I/O. Every S3 command
+ * for the shared bucket must pass this gate so projects cannot clobber
+ * each other's prefixes.
+ */
+export declare function assertRemoteObjectKey(key: string, namespace: string): void;
+/**
+ * Validates a logical key before {@link ObjectStoreWithPrefix} scopes it under
+ * a namespace or feature prefix.
+ */
+export declare function assertLogicalObjectKey(key: string): void;

package/dist/reports/src/namespace-guard.js

@@ -0,0 +1,40 @@
+/**
+ * Validates a wire key before any remote object-store I/O. Every S3 command
+ * for the shared bucket must pass this gate so projects cannot clobber
+ * each other's prefixes.
+ */
+export function assertRemoteObjectKey(key, namespace) {
+    if (key.length === 0) {
+        throw new Error('Remote object key must be non-empty');
+    }
+    if (key.startsWith('/')) {
+        throw new Error(`Remote object key must not start with "/": ${key}`);
+    }
+    if (key.includes('..')) {
+        throw new Error(`Remote object key must not contain "..": ${key}`);
+    }
+    const bareNamespace = namespace.endsWith('/')
+        ? namespace.slice(0, -1)
+        : namespace;
+    if (key === namespace || key === bareNamespace) {
+        throw new Error(`Remote object key must include a path after "${namespace}": ${key}`);
+    }
+    if (!key.startsWith(namespace)) {
+        throw new Error(`Remote object key must start with "${namespace}": ${key}`);
+    }
+}
+/**
+ * Validates a logical key before {@link ObjectStoreWithPrefix} scopes it under
+ * a namespace or feature prefix.
+ */
+export function assertLogicalObjectKey(key) {
+    if (key.length === 0) {
+        throw new Error('Object store key must be non-empty');
+    }
+    if (key.startsWith('/')) {
+        throw new Error(`Object store key must not start with "/": ${key}`);
+    }
+    if (key.includes('..')) {
+        throw new Error(`Object store key must not contain "..": ${key}`);
+    }
+}

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

@@ -0,0 +1,8 @@
+/** Host navigation and keyboard events, scoped to one reports explorer. */
+export type ReportNavigation = {
+    readonly readHash: () => string;
+    readonly writeHash: (hash: string, replace: boolean) => void;
+    readonly subscribeHash: (listener: () => void) => () => void;
+    readonly subscribeKeys: (listener: (event: KeyboardEvent) => void) => () => void;
+    readonly setTitle: (title: string) => void;
+};

package/dist/reports/src/object-io.d.ts

@@ -0,0 +1,9 @@
+import type { ObjectStore } from './object-store.js';
+/** Drain a {@link ReadableStream} into a single byte array. */
+export declare function readBytes(stream: ReadableStream<Uint8Array>): Promise<Uint8Array>;
+/** Read object bytes as UTF-8 text, or `null` when the key is missing. */
+export declare function readUtf8(store: ObjectStore, key: string): Promise<string | null>;
+/** Write UTF-8 text under `key` with the given content type (default text/plain). */
+export declare function writeUtf8(store: ObjectStore, key: string, text: string, contentType?: string): Promise<void>;
+/** Read object bytes, or `null` when the key is missing. */
+export declare function readObjectBytes(store: ObjectStore, key: string): Promise<Uint8Array | null>;

package/dist/reports/src/object-io.js

@@ -0,0 +1,41 @@
+/** Drain a {@link ReadableStream} into a single byte array. */
+export async function readBytes(stream) {
+    const reader = stream.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { value, done } = await reader.read();
+        if (done)
+            break;
+        if (value !== undefined) {
+            chunks.push(value);
+            total += value.byteLength;
+        }
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+}
+/** Read object bytes as UTF-8 text, or `null` when the key is missing. */
+export async function readUtf8(store, key) {
+    const obj = await store.get(key);
+    if (obj === null)
+        return null;
+    const bytes = await readBytes(obj.body);
+    return new TextDecoder().decode(bytes);
+}
+/** Write UTF-8 text under `key` with the given content type (default text/plain). */
+export async function writeUtf8(store, key, text, contentType = 'text/plain; charset=utf-8') {
+    await store.put(key, new TextEncoder().encode(text), contentType);
+}
+/** Read object bytes, or `null` when the key is missing. */
+export async function readObjectBytes(store, key) {
+    const obj = await store.get(key);
+    if (obj === null)
+        return null;
+    return readBytes(obj.body);
+}

package/dist/reports/src/object-store.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Content-addressed binary object storage.
+ *
+ * Tiny, async, transport-agnostic surface — exactly what a "blob keyed by id"
+ * cache needs (TTS audio, exported files, derived avatars, etc.). Implementations
+ * live in sibling `impl-*.ts` files (S3/R2, in-memory, file-system).
+ *
+ * Mirrors the {@link ../sql-client/interface.ts SqlClient} shape: one interface,
+ * multiple `impl-*.ts` siblings, plus a conformance suite in `interface.test.ts`.
+ *
+ * Read semantics:
+ *   - {@link ObjectStore.get} returns `null` when the key is missing. Transport /
+ *     parse errors throw.
+ *   - {@link ObjectStore.head} returns `false` for a missing key (never throws on
+ *     "not found"). Transport errors throw.
+ *
+ * Write semantics:
+ *   - {@link ObjectStore.put} MUST be idempotent: writing the same key twice
+ *     overwrites without error. Stored `contentType` MUST round-trip through
+ *     {@link ObjectStore.get}.
+ *   - {@link ObjectStore.delete} on a missing key is a no-op (does not throw).
+ *
+ * URI semantics:
+ *   - {@link ObjectStore.getUri} returns a URL the host runtime can load
+ *     directly (`file://` on native, `blob:` on web). Stores that don't expose
+ *     direct URLs (e.g. remote R2 — bytes must be streamed through HTTP)
+ *     return `null`. Returns `null` when the key is missing.
+ *
+ * Listing:
+ *   - {@link ObjectStore.listKeys} returns keys in sorted code-unit order
+ *     (deterministic). Optional `prefix` filters to keys that start with it.
+ */
+export interface StoredObject {
+    /** Stream of stored bytes. Single-use; consume or discard before issuing more I/O on the same store. */
+    readonly body: ReadableStream<Uint8Array>;
+    readonly contentType: string;
+    readonly size: number;
+}
+export interface ObjectStore {
+    /** Returns the stored object, or `null` if no value exists for `key`. */
+    get(key: string): Promise<StoredObject | null>;
+    /** Idempotently writes `bytes` under `key` with the given `contentType`. */
+    put(key: string, bytes: Uint8Array, contentType: string): Promise<void>;
+    /** `true` iff a value exists for `key`. Never throws on "not found". */
+    head(key: string): Promise<boolean>;
+    /** Removes the value at `key` if present. No-op when missing. */
+    delete(key: string): Promise<void>;
+    /** Remove every key, idempotently. Errors (including partial failure) throw. */
+    deleteMany(keys: readonly string[]): Promise<void>;
+    /**
+     * Returns a URL that the host runtime can load directly without reading bytes
+     * through {@link ObjectStore.get} again. Returns `null` for missing keys, and
+     * `null` for stores whose backend has no addressable URL (e.g. R2).
+     */
+    getUri(key: string): Promise<string | null>;
+    /**
+     * Returns keys present in the store, sorted by code-unit order.
+     * When `prefix` is set, only keys that start with it are returned.
+     */
+    listKeys(prefix?: string): Promise<readonly string[]>;
+    /**
+     * Returns a new store scoped to `prefix`. Caller keys are relative (must not
+     * include the prefix). All I/O operates on `prefix + key`. Nested calls compose
+     * prefixes (`a/` + `b/` → `a/b/`).
+     */
+    withPrefix(prefix: string): ObjectStore;
+}

package/dist/reports/src/object-store.js

@@ -0,0 +1,32 @@
+/**
+ * Content-addressed binary object storage.
+ *
+ * Tiny, async, transport-agnostic surface — exactly what a "blob keyed by id"
+ * cache needs (TTS audio, exported files, derived avatars, etc.). Implementations
+ * live in sibling `impl-*.ts` files (S3/R2, in-memory, file-system).
+ *
+ * Mirrors the {@link ../sql-client/interface.ts SqlClient} shape: one interface,
+ * multiple `impl-*.ts` siblings, plus a conformance suite in `interface.test.ts`.
+ *
+ * Read semantics:
+ *   - {@link ObjectStore.get} returns `null` when the key is missing. Transport /
+ *     parse errors throw.
+ *   - {@link ObjectStore.head} returns `false` for a missing key (never throws on
+ *     "not found"). Transport errors throw.
+ *
+ * Write semantics:
+ *   - {@link ObjectStore.put} MUST be idempotent: writing the same key twice
+ *     overwrites without error. Stored `contentType` MUST round-trip through
+ *     {@link ObjectStore.get}.
+ *   - {@link ObjectStore.delete} on a missing key is a no-op (does not throw).
+ *
+ * URI semantics:
+ *   - {@link ObjectStore.getUri} returns a URL the host runtime can load
+ *     directly (`file://` on native, `blob:` on web). Stores that don't expose
+ *     direct URLs (e.g. remote R2 — bytes must be streamed through HTTP)
+ *     return `null`. Returns `null` when the key is missing.
+ *
+ * Listing:
+ *   - {@link ObjectStore.listKeys} returns keys in sorted code-unit order
+ *     (deterministic). Optional `prefix` filters to keys that start with it.
+ */

package/dist/reports/src/performance-part.d.ts

@@ -0,0 +1,9 @@
+import type { RunReport } from './report-types.js';
+import type { ReportPart } from './explorer-types.js';
+/** Diagnostic budgets over recorded self time; no missing measurement becomes a pass. */
+export declare function performancePart(args: {
+    readonly sha: string;
+    readonly recordedAtMs: number;
+    readonly allowanceMs: number;
+    readonly reports: readonly RunReport[];
+}): ReportPart;

package/dist/reports/src/performance-part.js

@@ -0,0 +1,42 @@
+import { performanceRows } from './performance.js';
+/** Diagnostic budgets over recorded self time; no missing measurement becomes a pass. */
+export function performancePart(args) {
+    if (!Number.isFinite(args.allowanceMs) || args.allowanceMs <= 0)
+        throw new Error('Invalid performance allowance');
+    return {
+        sha: args.sha,
+        id: 'recorded-performance',
+        kind: 'performance',
+        title: 'Recorded action performance',
+        recordedAtMs: args.recordedAtMs,
+        checks: args.reports.map((report) => {
+            const rows = performanceRows(report.steps, args.allowanceMs);
+            const measured = rows.filter((row) => row.band !== 'unmeasured');
+            const slow = rows.filter((row) => row.band === 'slow').length;
+            const maximum = measured.reduce((max, row) => Math.max(max, row.step.performance.selfMs), 0);
+            return {
+                id: report.meta.testId,
+                title: report.meta.title,
+                status: slow > 0
+                    ? 'failed'
+                    : rows.length === 0 || rows.length !== measured.length
+                        ? 'not-run'
+                        : 'passed',
+                detail: `${measured.length} measured steps; ${slow} over the diagnostic allowance. Includes waits and harness work.`,
+                ...(report.meta.sourceFile === undefined
+                    ? {}
+                    : { specPath: report.meta.sourceFile }),
+                measurements: measured.length === 0
+                    ? []
+                    : [
+                        {
+                            name: 'Longest own action',
+                            value: maximum,
+                            unit: 'ms',
+                            limit: args.allowanceMs,
+                        },
+                    ],
+            };
+        }),
+    };
+}

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

@@ -0,0 +1,13 @@
+import type { ReportStep } from './report-types.js';
+import { type FlatFrame, type FlatStep } from './frames.js';
+export type HeatBand = 'unmeasured' | 'cool' | 'warm' | 'slow';
+export type PerformanceRow = FlatStep & {
+    readonly band: HeatBand;
+};
+export declare function heatBand(ms: number | undefined, allowanceMs: number): HeatBand;
+export declare function performanceRows(steps: readonly ReportStep[], allowanceMs: number): PerformanceRow[];
+/** Self time attributes nested work once, instead of ranking every ancestor as slow. */
+export declare function performanceHotspots(rows: readonly PerformanceRow[]): PerformanceRow[];
+export declare function measuredMs(ms: number): string;
+/** Linear lookup for a large heatmap; includes a parent's first descendant frame. */
+export declare function performanceFrameIndex(rows: readonly PerformanceRow[], frames: readonly FlatFrame[]): ReadonlyMap<ReportStep, FlatFrame>;

package/dist/reports/src/performance.js

@@ -0,0 +1,45 @@
+import { flattenSteps } from './frames.js';
+export function heatBand(ms, allowanceMs) {
+    if (ms === undefined || !Number.isFinite(ms) || ms < 0)
+        return 'unmeasured';
+    if (ms > allowanceMs)
+        return 'slow';
+    return ms > allowanceMs / 4 ? 'warm' : 'cool';
+}
+export function performanceRows(steps, allowanceMs) {
+    return flattenSteps(steps).map((row) => ({
+        ...row,
+        band: heatBand(row.step.performance?.selfMs, allowanceMs),
+    }));
+}
+/** Self time attributes nested work once, instead of ranking every ancestor as slow. */
+export function performanceHotspots(rows) {
+    return rows
+        .filter((row) => row.band !== 'unmeasured')
+        .sort((a, b) => (b.step.performance?.selfMs ?? 0) - (a.step.performance?.selfMs ?? 0) ||
+        a.index - b.index);
+}
+export function measuredMs(ms) {
+    return `${ms.toFixed(2)} ms`;
+}
+/** Linear lookup for a large heatmap; includes a parent's first descendant frame. */
+export function performanceFrameIndex(rows, frames) {
+    const byStep = new Map();
+    for (const frame of frames) {
+        if (!byStep.has(frame.step))
+            byStep.set(frame.step, frame);
+    }
+    for (let i = rows.length - 1; i >= 0; i -= 1) {
+        const step = rows[i].step;
+        if (byStep.has(step))
+            continue;
+        for (const child of step.steps) {
+            const frame = byStep.get(child);
+            if (frame === undefined)
+                continue;
+            byStep.set(step, frame);
+            break;
+        }
+    }
+    return byStep;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Persist the TanStack query cache. Frame-file queries stay out of this
+ * document — those bytes live in {@link ReportCache} on their own keys.
+ */
+import { type Persister } from '@tanstack/query-persist-client-core';
+import type { QueryClient } from '@tanstack/solid-query';
+import type { ReportCache } from './fetcher.js';
+export declare function reportPersister(cache: ReportCache): Persister;
+/** Restore the cache, then keep writing it. Returns unsubscribe. */
+export declare function attachReportCache(client: QueryClient, cache: ReportCache): [() => void, Promise<void>];

package/dist/reports/src/persist.js

@@ -0,0 +1,38 @@
+/**
+ * Persist the TanStack query cache. Frame-file queries stay out of this
+ * document — those bytes live in {@link ReportCache} on their own keys.
+ */
+import { persistQueryClient, } from '@tanstack/query-persist-client-core';
+const CACHE_KEY = 'reports-query-cache';
+const WEEK = 7 * 24 * 60 * 60 * 1000;
+export function reportPersister(cache) {
+    return {
+        persistClient: (client) => cache.set(CACHE_KEY, JSON.stringify(client)),
+        restoreClient: async () => {
+            const raw = await cache.get(CACHE_KEY);
+            if (raw === null)
+                return undefined;
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                await cache.remove(CACHE_KEY);
+                return undefined;
+            }
+        },
+        removeClient: () => cache.remove(CACHE_KEY),
+    };
+}
+function keepQuery(query) {
+    return query.state.status === 'success' && query.queryKey[1] !== 'blob';
+}
+/** Restore the cache, then keep writing it. Returns unsubscribe. */
+export function attachReportCache(client, cache) {
+    return persistQueryClient({
+        queryClient: client,
+        persister: reportPersister(cache),
+        maxAge: WEEK,
+        buster: 'reports-v2',
+        dehydrateOptions: { shouldDehydrateQuery: keepQuery },
+    });
+}

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

@@ -0,0 +1,5 @@
+export declare const PHONE_W = 390;
+export declare const PHONE_H = 844;
+export declare function zoomScale(mode: string, wrapW: number, wrapH: number): number;
+/** Drop scripts and the external shell stylesheet (frameCss replaces it). */
+export declare function cleanSnapshotHtml(html: string): string;