audit0 0.1.0

package/dist/engine/report.d.mts

@@ -0,0 +1 @@
+export declare function writeReport(audit: any, outputDirectory: any): Promise<string>;

package/dist/engine/report.mjs

@@ -0,0 +1,577 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { thresholds, gradeTiming, imageFinding, navigationMetricTypes, navigationFindings, pageFindings, } from "./findings.mjs";
+const NAVIGATION_METRICS = [
+    ["clickToFeedbackMs", "Click to first visible feedback"],
+    ["clickToUrlMs", "Click to URL (context only)"],
+    ["clickToShellMs", "Click to shell"],
+    ["clickToUsefulMs", "Click to useful content"],
+    ["clickToCompleteMs", "Click to complete (configured markers)"],
+].map(([key, label]) => [key, label, navigationMetricTypes[key]]);
+const UNSAFE_PATH = /[\u0000-\u001f\u007f\\:%?#]/;
+const IMAGE_EXTENSION = /\.(?:png|jpe?g|webp|gif|avif)$/i;
+const BLOCKING_EVIDENCE_GAP = /^(?:renderBlockingStatus unavailable|PerformanceObserver resource is unsupported|Browser (?:resources|elements|fonts|fontStyleSheets|fontCssRules) collection was truncated|CDP request collection capped|Browser snapshot unavailable|No browser observations available)/;
+function reportTitle(origin) {
+    try {
+        return `Performance audit · ${new URL(origin).hostname}`;
+    }
+    catch {
+        return "Performance audit";
+    }
+}
+function escapeHtml(text) {
+    return String(text ?? "Unavailable").replace(/[&<>"']/g, (character) => ({
+        "&": "&amp;",
+        "<": "&lt;",
+        ">": "&gt;",
+        '"': "&quot;",
+        "'": "&#39;",
+    })[character]);
+}
+function localPath(path) {
+    if (typeof path !== "string" || !path || UNSAFE_PATH.test(path))
+        return null;
+    const segments = path.split("/");
+    if (segments.some((segment) => !segment || segment === "." || segment === ".."))
+        return null;
+    return `./${segments.map((segment) => encodeURIComponent(segment)).join("/")}`;
+}
+function imageLink(path, label, thumbnail = false) {
+    const href = localPath(path);
+    if (!href || !IMAGE_EXTENSION.test(path))
+        return '<span class="muted">No safe image link</span>';
+    return `<a href="${escapeHtml(href)}">${thumbnail
+        ? `<img src="${escapeHtml(href)}" alt="${escapeHtml(label)}" loading="lazy" decoding="async">`
+        : escapeHtml(label)}</a>`;
+}
+function validTiming(timing) {
+    return typeof timing === "number" && Number.isFinite(timing) && timing >= 0;
+}
+function milliseconds(timing) {
+    return validTiming(timing) ? `${timing.toFixed(1)} ms` : "Unmeasured";
+}
+function gradeBadge(grade) {
+    const label = ["good", "ok", "bad"].includes(grade) ? grade : "unmeasured";
+    return `<span class="grade grade-${label}">${label}</span>`;
+}
+function timingCell(timing, metric) {
+    if (metric === null && validTiming(timing))
+        return `${milliseconds(timing)} <span class="muted">context only; not graded</span>`;
+    return `${milliseconds(timing)} ${gradeBadge(gradeTiming(timing, metric))}`;
+}
+function gradeCounts(grades) {
+    return `<small class="grade-counts">Samples: good: ${grades.filter((grade) => grade === "good").length}; ok: ${grades.filter((grade) => grade === "ok").length}; bad: ${grades.filter((grade) => grade === "bad").length}; unmeasured: ${grades.filter((grade) => grade === null).length}</small>`;
+}
+function distribution(timings, metric) {
+    const sorted = timings.filter(validTiming).sort((a, b) => a - b);
+    const count = sorted.length;
+    const counts = metric === null
+        ? `<small>Context samples: measured: ${count}; unmeasured: ${timings.length - count}</small>`
+        : gradeCounts(timings.map((timing) => gradeTiming(timing, metric)));
+    if (!count)
+        return `<span class="muted">Unmeasured (n=0)</span> ${gradeBadge(null)}${counts}`;
+    const middle = Math.floor(count / 2);
+    const median = count % 2 ? sorted[middle] : sorted[middle - 1] / 2 + sorted[middle] / 2;
+    return `${timingCell(median, metric)} <span class="muted">(n=${count})</span>${count >= 10
+        ? `<small>p90 ${timingCell(sorted[Math.ceil(count * 0.9) - 1], metric)}</small>`
+        : ""}${counts}`;
+}
+function table(headers, rows, empty = "No observations recorded.") {
+    if (!rows.length)
+        return `<p class="muted">${escapeHtml(empty)}</p>`;
+    return `<div class="table-scroll" tabindex="0" role="region" aria-label="${escapeHtml(headers.join(", "))}"><table><thead><tr>${headers.map((header) => `<th scope="col">${escapeHtml(header)}</th>`).join("")}</tr></thead><tbody>${rows.map((cells) => `<tr>${cells.map((cell) => `<td>${cell}</td>`).join("")}</tr>`).join("")}</tbody></table></div>`;
+}
+function rawDetails(label, payload) {
+    return `<details><summary>${escapeHtml(label)}</summary><pre>${escapeHtml(JSON.stringify(payload, null, 2))}</pre></details>`;
+}
+function notesList(notes) {
+    return notes?.length
+        ? `<ul>${notes.map((note) => `<li>${escapeHtml(typeof note === "string" ? note : JSON.stringify(note))}</li>`).join("")}</ul>`
+        : "";
+}
+function statusCounts(records) {
+    const collected = records.filter((record) => record.status === "ok" && !record.error).length;
+    return `${records.length} attempts; ${collected} collected; ${records.length - collected} incomplete`;
+}
+function statusCell(record, kind) {
+    if (record.status === "ok" && !record.error)
+        return '<span class="muted">collected</span>';
+    const findings = kind === "page" ? { TTFB: pageFindings(record).ttfb } : navigationFindings(record);
+    const unmeasured = Object.entries(findings)
+        .filter(([, finding]) => !validTiming(finding.ms))
+        .map(([metric]) => metric);
+    return `<span class="muted">incomplete</span><p class="error">${gradeBadge("bad")} collection finding: ${escapeHtml(record.error || "No error message recorded.")}</p>
+    <p>Unmeasured metrics: ${unmeasured.length ? escapeHtml(unmeasured.join(", ")) : "none among the timing metrics"}. Missing measurements are not bad performance; valid partial timings retain their own grades.</p>`;
+}
+function groups(records, fields) {
+    const grouped = new Map();
+    for (const record of records) {
+        const key = JSON.stringify(fields.map((field) => record[field] ?? null));
+        if (!grouped.has(key))
+            grouped.set(key, []);
+        grouped.get(key).push(record);
+    }
+    return [...grouped.values()];
+}
+function pageSummary(pages) {
+    return table(["Page", "Mode", "Collection counts", "Request-response TTFB median / sample grades"], groups(pages, ["path", "mode"]).map((records) => [
+        escapeHtml(records[0].path),
+        escapeHtml(records[0].mode),
+        statusCounts(records),
+        distribution(records.map((record) => pageFindings(record).ttfb.ms), "ttfb"),
+    ]));
+}
+function navigationSummary(navigations) {
+    return table([
+        "Route",
+        "Mode",
+        "Collection counts",
+        ...NAVIGATION_METRICS.map(([, label, metric]) => `${label} median / ${metric === null ? "sample counts" : "sample grades"}`),
+    ], groups(navigations, ["from", "to", "mode"]).map((records) => [
+        `${escapeHtml(records[0].from)} &rarr; ${escapeHtml(records[0].to)}`,
+        escapeHtml(records[0].mode),
+        statusCounts(records),
+        ...NAVIGATION_METRICS.map(([key, , metric]) => distribution(records.map((record) => navigationFindings(record)[key].ms), metric)),
+    ]));
+}
+function pageEvidenceTable(pages) {
+    return table([
+        "Page / attempt",
+        "Mode",
+        "Collection",
+        "TTFB / grade",
+        "TTFB source",
+        "Navigation to first byte",
+        "Response end",
+        "FCP",
+        "Preliminary LCP",
+        "Evidence",
+    ], pages.map((page, index) => [
+        `${escapeHtml(page.path)}<small>${escapeHtml(page.id)} / attempt ${escapeHtml(page.attempt)}</small>`,
+        escapeHtml(page.mode),
+        statusCell(page, "page"),
+        timingCell(pageFindings(page).ttfb.ms, "ttfb"),
+        escapeHtml(page.diagnostics?.navigation?.ttfbSource),
+        milliseconds(page.diagnostics?.navigation?.navigationToFirstByteMs),
+        milliseconds(page.diagnostics?.navigation?.responseEndMs),
+        milliseconds(page.diagnostics?.paints?.fcpMs),
+        milliseconds(page.diagnostics?.paints?.lcp?.startTime),
+        `${imageLink(page.screenshot, "Screenshot")}<small><a href="#page-${index}">Diagnostics and raw sample</a></small>`,
+    ]));
+}
+function navigationEvidenceTable(navigations, allNavigations) {
+    return table([
+        "Route / attempt",
+        "Mode / type",
+        "Collection",
+        ...NAVIGATION_METRICS.map(([, label, metric]) => metric === null ? label : `${label} / grade`),
+        "Evidence",
+    ], navigations.map((navigation) => [
+        `${escapeHtml(navigation.from)} &rarr; ${escapeHtml(navigation.to)}<small>${escapeHtml(navigation.id)} / attempt ${escapeHtml(navigation.attempt)}</small>`,
+        `${escapeHtml(navigation.mode)}<small>${escapeHtml(navigation.measurement?.type)}</small>`,
+        statusCell(navigation, "navigation"),
+        ...NAVIGATION_METRICS.map(([key, , metric]) => timingCell(navigationFindings(navigation)[key].ms, metric)),
+        `${imageLink(navigation.screenshot, "Screenshot")}<small><a href="#navigation-${allNavigations.indexOf(navigation)}">Checkpoints, frames and raw sample</a></small>`,
+    ]));
+}
+function imageDiagnostics(images) {
+    if (!images)
+        return `<p>${gradeBadge(null)} Image observations unmeasured.</p>`;
+    return (`<h4>Preload declarations</h4><p>Declarations are distinct from matched request evidence. High priority alone never proves a preload. An empty evidence list means not confirmed, not proof of absence.</p>
+    ${Array.isArray(images.preloads) ? rawDetails("Recorded image preload declarations (not proof of use)", images.preloads) : '<p class="muted">Preload declarations unmeasured in this report.</p>'}` +
+        ["early", "final"]
+            .map((snapshot) => {
+            const candidates = [
+                ...(images[snapshot] ?? []).map((image) => ({ ...image, kind: "img" })),
+                ...(images.backgrounds?.[snapshot] ?? []).map((image) => ({
+                    ...image,
+                    kind: "CSS background",
+                })),
+            ].filter((image) => image.visible && image.intersectsViewport);
+            const initiallyHigh = candidates.filter((image) => ["High", "VeryHigh"].includes(image.initialPriority)).length;
+            const finallyHigh = candidates.filter((image) => ["High", "VeryHigh"].includes(image.finalPriority)).length;
+            return `<h4>${snapshot === "early" ? "Early" : "Final"} above-fold candidates</h4>
+      <p>Snapshot observed at ${milliseconds(images[`${snapshot}ObservedMs`])} after time origin. ${candidates.length} recorded candidates; initial CDP High/VeryHigh: ${initiallyHigh}; final CDP High/VeryHigh: ${finallyHigh}. Counts are per snapshot, not unique requests.</p>
+      ${table([
+                "Image / source",
+                "Viewport geometry",
+                "Kind",
+                "LCP match",
+                "Fetch discovery (time origin)",
+                "Discovery after TTFB (signed)",
+                "Request rank",
+                "Preload evidence",
+                "Initiator",
+                "HTML fetchPriority hint",
+                "CDP initial",
+                "CDP final at cutoff",
+                "Priority status / request",
+                "Grade / reason",
+            ], candidates.map((image) => [
+                `${escapeHtml(image.alt || image.sourceUrl || image.url)}<small>${escapeHtml(image.url)}</small><small>${escapeHtml(image.networkId)}</small>`,
+                [image.width, image.height, image.x, image.y].every(Number.isFinite)
+                    ? escapeHtml(`${Math.round(image.width)}x${Math.round(image.height)} at (${Math.round(image.x)}, ${Math.round(image.y)})`)
+                    : "Unmeasured geometry",
+                escapeHtml(image.kind),
+                image.isLcpCandidate === true
+                    ? "Matched candidate LCP (preliminary)"
+                    : image.isLcpCandidate === false
+                        ? "Above-fold non-LCP candidate"
+                        : "LCP match unmeasured",
+                Number.isFinite(image.fetchStartMs)
+                    ? `${image.fetchStartMs.toFixed(1)} ms`
+                    : "Unmeasured",
+                Number.isFinite(image.fetchStartAfterTtfbMs)
+                    ? `${image.fetchStartAfterTtfbMs > 0 ? "+" : ""}${image.fetchStartAfterTtfbMs.toFixed(1)} ms`
+                    : "Unmeasured",
+                Number.isFinite(image.requestOrder) ? escapeHtml(image.requestOrder) : "Unmeasured",
+                Array.isArray(image.preloadEvidence)
+                    ? image.preloadEvidence.length
+                        ? `Observed: ${escapeHtml(image.preloadEvidence.join(", "))}`
+                        : "Not confirmed (no recorded evidence)"
+                    : "Unmeasured (legacy or missing evidence)",
+                escapeHtml(image.initiatorType ?? "Unmeasured"),
+                escapeHtml(image.fetchPriority),
+                escapeHtml(image.initialPriority),
+                escapeHtml(image.finalPriority),
+                `${escapeHtml(image.finalPriorityStatus)} / ${escapeHtml(image.requestStatus)}`,
+                `${gradeBadge(imageFinding(image).grade)} ${escapeHtml(imageFinding(image).reason)}`,
+            ]), "No visible, viewport-intersecting candidates recorded in this snapshot.")}`;
+        })
+            .join(""));
+}
+function blockingFinding(diagnostics, kind, incomplete) {
+    if (!diagnostics ||
+        (kind === "fonts" ? !diagnostics.fonts : !Array.isArray(diagnostics.renderBlockingScripts))) {
+        return {
+            grade: null,
+            reason: `${kind === "fonts" ? "Font" : "Script"} blocking observations unmeasured.`,
+        };
+    }
+    const fonts = diagnostics.fonts;
+    const observed = kind === "fonts"
+        ? fonts.resources?.some((font) => font.performanceTimings?.some((timing) => timing.renderBlockingStatus === "blocking"))
+        : diagnostics.renderBlockingScripts.some((script) => script.renderBlockingStatus === "blocking");
+    if (observed)
+        return {
+            grade: "bad",
+            reason: "Browser-reported render-blocking resources observed; this does not quantify visible delay.",
+        };
+    const partial = incomplete ||
+        (diagnostics.measurementNotes ?? []).some((note) => BLOCKING_EVIDENCE_GAP.test(String(note).slice(0, 2000)));
+    const risk = kind === "fonts"
+        ? !Array.isArray(fonts.faces) ||
+            !Array.isArray(fonts.resources) ||
+            fonts.faces.some((face) => face.sourceType !== "local-only" &&
+                (["auto", "block"].includes(face.display) ||
+                    !["network", "mixed"].includes(face.sourceType) ||
+                    !face.display)) ||
+            fonts.resources.some((font) => !font.performanceTimings?.length ||
+                font.performanceTimings.some((timing) => !["blocking", "non-blocking"].includes(timing.renderBlockingStatus)))
+        : !Array.isArray(diagnostics.resources) ||
+            !Array.isArray(diagnostics.explicitInlineRenderBlockers) ||
+            diagnostics.explicitInlineRenderBlockers.length > 0 ||
+            diagnostics.renderBlockingScripts.length > 0 ||
+            diagnostics.resources.some((resource) => !["blocking", "non-blocking"].includes(resource.renderBlockingStatus));
+    return partial || risk
+        ? { grade: "ok", reason: "Risk or partial/unsupported evidence; blocking is not proven." }
+        : {
+            grade: "good",
+            reason: "No evidenced blockers in the recorded observations; not proof that blocking is impossible.",
+        };
+}
+function fontDiagnostics(diagnostics, incomplete) {
+    const fonts = diagnostics?.fonts;
+    const finding = blockingFinding(diagnostics, "fonts", incomplete);
+    const summary = `<p>${gradeBadge(finding.grade)} ${escapeHtml(finding.reason)}</p>`;
+    if (!fonts)
+        return summary;
+    const proven = (fonts.resources ?? []).filter((font) => font.performanceTimings?.some((timing) => timing.renderBlockingStatus === "blocking"));
+    return `${summary}<p>Browser-reported blocking font resources: <strong>${Array.isArray(fonts.resources) ? proven.length : "Unmeasured"}</strong>. Font set at FCP: ${escapeHtml(fonts.statusAtFcp)} (sampled at ${milliseconds(fonts.atFcpObservedMs)}); at finish: ${escapeHtml(fonts.statusAtFinish)}.</p>
+    ${table(["Font face", "font-display", "Status", "Potential invisible text risk", "CSS source type"], (fonts.faces ?? []).map((face) => [
+        escapeHtml(face.family),
+        escapeHtml(face.display),
+        escapeHtml(face.status),
+        face.sourceType === "local-only"
+            ? "No font download: local-only source"
+            : ["auto", "block"].includes(face.display)
+                ? "Potential risk only, not proof"
+                : "Not indicated by display mode",
+        escapeHtml(face.sourceType || "unknown"),
+    ]))}
+    ${table(["Font resource", "Status", "Resource Timing renderBlockingStatus", "Request-response TTFB"], (fonts.resources ?? []).map((font) => [
+        escapeHtml(font.url),
+        escapeHtml(font.status),
+        escapeHtml(font.performanceTimings?.length
+            ? font.performanceTimings
+                .map((timing) => timing.renderBlockingStatus ?? "Unavailable")
+                .join(", ")
+            : null),
+        timingCell(font.ttfbMs, "ttfb"),
+    ]))}`;
+}
+function pageDetails(page, index) {
+    const diagnostics = page.diagnostics;
+    const incomplete = page.status !== "ok" || Boolean(page.error);
+    const scripts = blockingFinding(diagnostics, "scripts", incomplete);
+    return `<details class="sample" id="page-${index}"><summary>${escapeHtml(page.path)} / ${escapeHtml(page.mode)} / attempt ${escapeHtml(page.attempt)}</summary>
+    ${statusCell(page, "page")}
+    ${imageLink(page.screenshot, `Page screenshot: ${page.path}`, true)}
+    ${diagnostics
+        ? `
+      <p>Observation cutoff: ${milliseconds(diagnostics.finishedMs)} after document time origin. FCP: ${milliseconds(diagnostics.paints?.fcpMs)}. Preliminary observation-window LCP: ${milliseconds(diagnostics.paints?.lcp?.startTime)}; not finalized.</p>
+      <h3>Images</h3>${imageDiagnostics(diagnostics.images)}
+      <h3>Fonts</h3>${fontDiagnostics(diagnostics, incomplete)}
+      <h3>Scripts</h3>
+      <p>${gradeBadge(scripts.grade)} ${escapeHtml(scripts.reason)}</p>
+      <p>Proven render-blocking script resources recorded: <strong>${diagnostics.renderBlockingScripts?.filter((script) => script.renderBlockingStatus === "blocking").length ?? "Unmeasured"}</strong>. Explicit inline blocking=render declarations: <strong>${diagnostics.explicitInlineRenderBlockers?.length ?? "Unmeasured"}</strong> snapshot observations, not unique or proven blockers.</p>
+      ${table([
+            "Script URL from blocking-resource observations",
+            "Browser blocking status",
+            "TTFB",
+            "HTML hints",
+        ], (diagnostics.renderBlockingScripts ?? []).map((script) => [
+            escapeHtml(script.url),
+            escapeHtml(script.renderBlockingStatus),
+            timingCell(script.ttfbMs, "ttfb"),
+            escapeHtml(JSON.stringify(script.hints)),
+        ]), "No proven render-blocking scripts recorded.")}
+      ${rawDetails("Explicit inline declarations (separate, not proof)", diagnostics.explicitInlineRenderBlockers)}
+      <h3>Collection notes</h3>${notesList(diagnostics.measurementNotes)}
+    `
+        : `<p class="muted">Page diagnostics unavailable. Images, fonts and scripts are unmeasured. See the recorded collection finding.</p>`}
+    ${rawDetails("Final content state and document timings", { finalState: page.finalState, navigation: diagnostics?.navigation })}
+    <p>Complete resource and priority timelines are in <a href="./audit.json">audit.json</a>, under pages / ${escapeHtml(page.id)} / attempt ${escapeHtml(page.attempt)} / ${escapeHtml(page.mode)}.</p>
+  </details>`;
+}
+function checkpoints(measurement) {
+    const requested = [
+        ...new Set([
+            100,
+            500,
+            1000,
+            ...(measurement.checkpoints ?? []).map((checkpoint) => checkpoint.requestedMs),
+        ]),
+    ]
+        .filter(validTiming)
+        .sort((a, b) => a - b);
+    return table([
+        "Requested checkpoint",
+        "Last observed state",
+        "Observed timestamp",
+        "Observation bracket [last, next]",
+        "Marker counts",
+    ], requested.map((requestedMs) => {
+        const checkpoint = measurement.checkpoints?.find((checkpoint) => checkpoint.requestedMs === requestedMs);
+        return [
+            milliseconds(requestedMs),
+            escapeHtml(checkpoint?.state ?? "not-observed"),
+            milliseconds(checkpoint?.lastObservedMs),
+            `[${milliseconds(checkpoint?.lastObservedMs)}, ${milliseconds(checkpoint?.nextObservedMs)}]`,
+            escapeHtml(checkpoint ? JSON.stringify(checkpoint.counts) : null),
+        ];
+    }));
+}
+function filmstrip(navigation) {
+    const frames = [...(navigation.measurement?.frames ?? [])].sort((a, b) => (Number.isFinite(a.atMs) ? a.atMs : Infinity) - (Number.isFinite(b.atMs) ? b.atMs : Infinity));
+    if (!frames.length)
+        return '<p class="muted">No filmstrip frames recorded.</p>';
+    return `<div class="filmstrip">${frames
+        .map((frame) => {
+        const at = Number.isFinite(frame.atMs) ? `${frame.atMs.toFixed(1)} ms` : "Unavailable";
+        const path = localPath(navigation.directory) && localPath(frame.file)
+            ? `${navigation.directory}/${frame.file}`
+            : null;
+        return `<figure>${imageLink(path, `Frame at ${at} relative to click`, true)}<figcaption>${escapeHtml(at)} relative to click<small>${escapeHtml(frame.file)}</small></figcaption></figure>`;
+    })
+        .join("")}</div>`;
+}
+function routeMilestones(navigation) {
+    const milestones = (navigation.criteria?.milestones ?? []).map((milestone) => {
+        const atMs = navigation.measurement?.milestoneTimings?.[milestone.id];
+        return [
+            `<strong>${escapeHtml(milestone.label)}</strong><small>${escapeHtml(milestone.description)}</small>`,
+            validTiming(atMs) ? milliseconds(atMs) : "Not shown",
+            validTiming(atMs) ? escapeHtml(milestone.gradeMetric ?? "not graded") : "not graded",
+        ];
+    });
+    return table(["Route milestone", "First observed", "Grading profile"], milestones, "No route-specific milestones were configured for this sample.");
+}
+function navigationDetails(navigation, index) {
+    const measurement = navigation.measurement;
+    return `<details class="sample" id="navigation-${index}"><summary>${escapeHtml(navigation.from)} &rarr; ${escapeHtml(navigation.to)} / ${escapeHtml(navigation.mode)} / attempt ${escapeHtml(navigation.attempt)}</summary>
+    ${statusCell(navigation, "navigation")}
+    ${imageLink(navigation.screenshot, `Navigation screenshot: ${navigation.to}`, true)}
+    ${navigation.mode === "client-ready-first-visit" ? '<p class="notice">Conditional client-ready retry: this fresh-context sample ran only because the original first visit used a full document navigation. It is excluded from aggregate timing distributions.</p>' : ""}
+    ${measurement
+        ? `
+      ${NAVIGATION_METRICS.map(([key, label, metric]) => `<p><strong>${label}:</strong> ${timingCell(measurement[key], metric)}</p>`).join("")}
+      <h3>Route milestones</h3>${routeMilestones(navigation)}
+      <h3>First visible feedback evidence</h3>
+      ${measurement.firstFeedbackReasons?.length ? notesList(measurement.firstFeedbackReasons) : '<p class="muted">First feedback reasons unmeasured or not recorded. Missing feedback timings are not inferred from URL or shell timings.</p>'}
+      <p>Pre-click hover: ${milliseconds(measurement.preClickHoverMs)} (recorded duration). The target is scrolled into view, then hovered before the click. Hover is excluded from click-relative clocks and is not feedback; network capture starts before hover.</p>
+      <h3>Checkpoint observations</h3>
+      <p>The state is the last sample at or before the requested time, not an exact-time screenshot. The bracket exposes the next sample, gaps and missing observations. Times are relative to the click.</p>
+      ${checkpoints(measurement)}
+      <h3>Chronological filmstrip</h3>${filmstrip(navigation)}
+      ${measurement.notes?.length ? `<h3>Measurement notes</h3>${notesList(measurement.notes)}` : ""}
+    `
+        : '<p class="muted">Navigation measurement unavailable. See the recorded status and error.</p>'}
+    ${rawDetails("Destination criteria", navigation.criteria)}
+    ${rawDetails("Raw navigation sample and state timeline", navigation)}
+  </details>`;
+}
+const STYLES = `
+  :root { color-scheme: light; font-family: system-ui, -apple-system, sans-serif; color: #24313b; background: #f5f6f8; line-height: 1.6; }
+  * { box-sizing: border-box; }
+  body { margin: 0; }
+  main { max-width: 1440px; margin: auto; padding: 40px 28px 72px; }
+  header { border-top: 4px solid #28576b; padding: 24px 0; }
+  h1, h2, h3, h4 { line-height: 1.25; color: #172d3a; }
+  h1 { font-size: clamp(2rem, 5vw, 3rem); letter-spacing: -.04em; margin: 8px 0 16px; }
+  h2 { margin-top: 0; font-size: 1.45rem; }
+  h3 { margin-top: 28px; }
+  h4 { margin-bottom: 8px; }
+  p { max-width: 110ch; }
+  section { margin: 24px 0; padding: 24px; background: white; border: 1px solid #dce2e7; border-radius: 8px; }
+  a { color: #185e80; text-underline-offset: 3px; overflow-wrap: anywhere; }
+  a:hover { color: #103b50; }
+  a:focus-visible, summary:focus-visible, .table-scroll:focus-visible { outline: 3px solid #b26b0a; outline-offset: 3px; }
+  .eyebrow { text-transform: uppercase; letter-spacing: .12em; font-size: .8rem; }
+  .muted, small { color: #57636e; }
+  small { display: block; font-size: .82rem; }
+  .cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 12px; }
+  .card { padding: 16px; background: #edf3f6; border-radius: 6px; }
+  .card strong { display: block; font-size: 1.1rem; }
+  .notice { border-left: 3px solid #ad752a; background: #fcf7ed; padding: 12px 16px; }
+  .table-scroll { overflow-x: auto; margin: 16px 0; }
+  table { border-collapse: collapse; width: 100%; font-size: .88rem; font-variant-numeric: tabular-nums; }
+  th, td { padding: 12px; text-align: left; vertical-align: top; border-bottom: 1px solid #e1e6ea; min-width: 120px; overflow-wrap: anywhere; }
+  th { background: #edf2f5; font-weight: 600; }
+  td { max-width: 420px; }
+  .success { color: #226442; }
+  .failure, .error { color: #9a3030; }
+  .grade { display: inline-block; padding: 1px 7px; border-radius: 4px; font-size: .8rem; font-weight: 700; }
+  .grade-good { color: #185536; background: #e0f2e7; }
+  .grade-ok { color: #76500d; background: #fff0c9; }
+  .grade-bad { color: #8a2424; background: #fbe5e5; }
+  .grade-unmeasured { color: #495660; background: #e9edf0; }
+  .error { white-space: pre-wrap; overflow-wrap: anywhere; }
+  details { margin: 12px 0; }
+  details.sample { border-top: 1px solid #dce2e7; padding: 16px 0; scroll-margin-top: 16px; }
+  summary { cursor: pointer; font-weight: 600; overflow-wrap: anywhere; }
+  pre { white-space: pre-wrap; overflow-wrap: anywhere; max-height: 600px; overflow: auto; background: #f2f4f6; padding: 16px; font-size: .8rem; }
+  img { display: block; max-width: 100%; width: 280px; height: auto; border: 1px solid #dce2e7; border-radius: 4px; margin-top: 12px; }
+  .filmstrip { display: flex; gap: 16px; overflow-x: auto; padding-bottom: 16px; }
+  figure { flex: 0 0 240px; margin: 0; }
+  figcaption { font-size: .85rem; margin-top: 8px; overflow-wrap: anywhere; }
+  li { margin: 8px 0; }
+  @media (max-width: 640px) { main { padding: 16px 12px 40px; } section { padding: 16px 12px; } th, td { padding: 10px; } }
+  @media print { body { background: white; } main { padding: 0; } section, .card { break-inside: avoid; } .table-scroll, .filmstrip { overflow: visible; } }
+`;
+export async function writeReport(audit, outputDirectory) {
+    if (!audit ||
+        audit.schemaVersion !== 1 ||
+        !Array.isArray(audit.pages) ||
+        !Array.isArray(audit.navigations)) {
+        throw new TypeError("Expected a schemaVersion: 1 audit with pages and navigations arrays");
+    }
+    const { pages, navigations } = audit;
+    const timingPages = pages;
+    const timingNavigations = navigations.filter((navigation) => ["first-visit", "revisit"].includes(navigation.mode));
+    const clientReadyNavigations = navigations.filter((navigation) => navigation.mode === "client-ready-first-visit");
+    const otherNavigations = navigations.filter((navigation) => !["first-visit", "revisit", "client-ready-first-visit"].includes(navigation.mode));
+    const html = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; img-src 'self'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'">
+<title>${escapeHtml(reportTitle(audit.environment?.origin))}</title><style>${STYLES}</style></head><body><main>
+  <header><div class="eyebrow">Local browser observations</div><h1>Performance audit</h1>
+    <p>${escapeHtml(audit.environment?.origin)}<br><span class="muted">${escapeHtml(audit.startedAt)} to ${escapeHtml(audit.finishedAt)}</span></p>
+    <p>This report describes this audit's environment and observation windows only. It does not establish production-wide performance or claim that performance has been fixed.</p>
+  </header>
+  <section aria-labelledby="summary"><h2 id="summary">Summary</h2><div class="cards">
+    <div class="card"><strong>Page TTFB median</strong>${distribution(timingPages.map((page) => pageFindings(page).ttfb.ms), "ttfb")}</div>
+    ${NAVIGATION_METRICS.map(([key, label, metric]) => `<div class="card"><strong>${label} median</strong>${distribution(timingNavigations.map((navigation) => navigationFindings(navigation)[key].ms), metric)}</div>`).join("")}
+    <div class="card"><strong>Final above-fold image grades</strong>${gradeCounts(timingPages.flatMap((page) => pageFindings(page).images.map((image) => image.grade)))}<small>${timingPages.filter((page) => !Array.isArray(page.diagnostics?.images?.final)).length} page attempts with unmeasured final image snapshots. Per-snapshot candidates, not unique requests. Missing image observations are not counted as good.</small></div>
+    </div><p>These overview medians combine timing modes and routes. Use the grouped medians and individual sample grades below to locate outliers; a good median does not erase bad samples.</p>
+    <h3>Collection coverage</h3><div class="cards">
+    <div class="card"><strong>Page diagnostics</strong>${statusCounts(pages)}</div>
+    <div class="card"><strong>Navigation timing runs</strong>${statusCounts(timingNavigations)}</div>
+    <div class="card"><strong>Conditional client-ready retries</strong>${statusCounts(clientReadyNavigations)}</div>
+    ${otherNavigations.length ? `<div class="card"><strong>Unrecognized modes, excluded</strong>${statusCounts(otherNavigations)}</div>` : ""}
+    </div>
+    <h3>Environment and recorded settings (not grading thresholds)</h3>
+    ${table(["Setting", "Recorded value"], Object.entries({ ...audit.environment, ...audit.settings }).map(([key, setting]) => [
+        escapeHtml(key),
+        escapeHtml(typeof setting === "object" ? JSON.stringify(setting) : setting),
+    ]))}
+    <h3>Current findings</h3><p>Grades above and below are recomputed from raw measurements using the current thresholds, not persisted grading prose.</p>
+    ${audit.observations?.length ? `<details><summary>Legacy observations (historical text, not authoritative grading)</summary><p>These saved observations may use obsolete thresholds. Use the recomputed grades and threshold table instead.</p>${notesList(audit.observations)}</details>` : ""}
+    <p>Page response time and navigation usefulness are different measurements. Response end is relative to navigation start and exposes streamed-document completion after early headers. A fast TTFB alone does not imply a usable page.</p>
+  </section>
+  <section aria-labelledby="method"><h2 id="method">Reading the measurements</h2>
+    ${table(["Metric", "good", "ok", "bad", "Boundary interpretation"], [
+        [
+            "Request-response TTFB",
+            `&lt; ${thresholds.ttfb.goodBelowMs} ms`,
+            `${thresholds.ttfb.goodBelowMs} to &lt; ${thresholds.ttfb.okBelowMs} ms`,
+            `&ge; ${thresholds.ttfb.okBelowMs} ms`,
+            `Exactly ${thresholds.ttfb.goodBelowMs} ms is ok; exactly ${thresholds.ttfb.okBelowMs} ms is bad.`,
+        ],
+        [
+            "Immediate visible feedback / shell",
+            `&lt; ${thresholds.feedback.goodBelowMs} ms`,
+            `${thresholds.feedback.goodBelowMs} to &lt; ${thresholds.feedback.okBelowMs} ms`,
+            `&ge; ${thresholds.feedback.okBelowMs} ms`,
+            `Exactly ${thresholds.feedback.goodBelowMs} ms is ok; exactly ${thresholds.feedback.okBelowMs} ms is bad.`,
+        ],
+        [
+            "Useful or complete configured content",
+            `&lt; ${thresholds.content.goodBelowMs} ms`,
+            `${thresholds.content.goodBelowMs} to ${thresholds.content.badAboveMs} ms`,
+            `&gt; ${thresholds.content.badAboveMs} ms`,
+            `Exactly ${thresholds.content.badAboveMs} ms is ok; values above it are bad.`,
+        ],
+        [
+            "Above-fold image heuristic",
+            "Early fetch with initial CDP High/VeryHigh, not pending",
+            "Early but pending or high initial priority not observed",
+            "Late fetch or observed request/decode error",
+            `Early means signed fetch discovery minus document first byte &le; ${thresholds.images.earlyAfterTtfbMs} ms (inclusive, including negative delays). Missing delay is unmeasured unless a request/decode error was observed. Preload evidence is separate; final priority upgrades do not change initial priority.`,
+        ],
+    ])}
+    <ul>
+      <li>Medians include every finite, non-negative measurement, including partial measurements from incomplete collections. Missing or invalid timings are unmeasured, never zero. Each graded metric has its own valid sample count and per-sample good/ok/bad/unmeasured counts so medians cannot hide outliers. Context-only timings have measured/unmeasured counts, not performance grades.</li>
+      <li>Grades are findings, never audit pass/fail gates. Timeouts and collection errors are bad collection findings, not fabricated bad performance. They do not stop the runner from attempting the remaining cases. Local tests still enforce harness correctness, including invalid report input.</li>
+      <li>Collection labels are collected or incomplete, independent of performance grades. Status values are collection metadata, not performance verdicts.</li>
+      <li>90th percentiles appear only with at least 10 valid samples per metric, using nearest rank. Small runs do not support tail-performance or production-wide conclusions.</li>
+      <li>Page groups separate fresh-context and warm-reload modes. A first visit and its revisit share one browser context: the revisit uses browser Back to return to the source before clicking the destination again. A conditional client-ready first visit uses a separate fresh context only when the original first visit was full-document; conditional retries never enter timing distributions.</li>
+      <li>Request-response TTFB is diagnostics.navigation.ttfbMs, using the recorded CDP source (normally receiveHeadersStart minus sendEnd). It includes RTT, cache and upstream work, not pure server compute. Browser request-to-first-byte and navigation-to-first-byte are distinct raw measurements; unavailable CDP timings are not replaced with them.</li>
+      <li>Navigation milestones are sampled DOM states relative to the click, not exact pixel presentation. Useful and complete refer to the configured viewport marker criteria, not proof all interactions are ready. Source dwell, observation length, prefetching and prior visits affect results. FCP, LCP, response end and other contextual timings have no grade threshold in this audit.</li>
+      <li>First visible feedback is the observed new destination fallback, shell/content, or movement of an explicitly configured navigation indicator. Click to URL is context only, not evidence of visible feedback and never a pass grade. Legacy artifacts without clickToFeedbackMs remain unmeasured; feedback is not inferred from URL or shell timings. Useful and complete content are graded separately from immediate feedback.</li>
+      <li>The target is scrolled into view, then hovered for the configured pre-click duration (default 150 ms). Hover is not feedback and is excluded from click-relative clocks. Network capture starts before hover, so hover-triggered prefetch can be observed; earlier prefetch may be absent.</li>
+      <li>LCP is preliminary, observation-window only, not finalized. Long tasks and all downloaded JavaScript must not be counted as render-blocking scripts: only diagnostics.renderBlockingScripts is counted. Explicit inline blockers are reported separately as declarations.</li>
+      <li>Image fetchPriority is an HTML hint; initial and final priorities are actual CDP observations, with final meaning the collection cutoff. Above-fold candidates reflect sampled visibility and geometry, not proof of importance or lack of occlusion. Prioritize selectively after inspecting evidence, not every logo or above-fold image.</li>
+      <li>Image request rank is the 1-based chronological order of observed main-frame subresource requests, not a priority rank. Signed image delay is relative to document first byte, not the request-response TTFB duration. A matched candidate LCP is a preliminary URL match, not finalized LCP or proof of element identity.</li>
+      <li>Font-display auto/block signals potential invisible text risk, not proven blocking. Swap is not a render blocker by virtue of its display mode. Browser-reported blocking font resources require performanceTimings.renderBlockingStatus = blocking; request duration and font display alone do not prove text was blocked.</li>
+    </ul>
+  </section>
+  <section aria-labelledby="pages"><h2 id="pages">Page TTFB by mode</h2>${pageSummary(timingPages)}</section>
+  <section aria-labelledby="navigation"><h2 id="navigation">Navigation timings by mode</h2>${navigationSummary(timingNavigations)}</section>
+  <section aria-labelledby="page-evidence"><h2 id="page-evidence">Page samples and evidence</h2>${pageEvidenceTable(pages)}${pages.map(pageDetails).join("")}</section>
+  <section aria-labelledby="timing-evidence"><h2 id="timing-evidence">Navigation timing samples</h2>${navigationEvidenceTable(timingNavigations, navigations)}</section>
+  <section aria-labelledby="conditional-retries"><h2 id="conditional-retries">Conditional client-ready retries</h2><p class="notice">These fresh-context retries run only after a full-document first visit and are shown for diagnosis, not combined with timing-run distributions.</p>${navigationEvidenceTable(clientReadyNavigations, navigations)}</section>
+  ${otherNavigations.length ? `<section><h2>Unrecognized navigation modes</h2>${navigationEvidenceTable(otherNavigations, navigations)}</section>` : ""}
+  <section aria-labelledby="navigation-details"><h2 id="navigation-details">Navigation checkpoints and details</h2>${navigations.length ? navigations.map(navigationDetails).join("") : '<p class="muted">No navigation observations recorded.</p>'}</section>
+  <section aria-labelledby="privacy"><h2 id="privacy">Privacy and scope</h2>
+    <p>Keep these artifacts local and review before sharing. Anonymous browsing can still capture public chat, usernames and other public content in screenshots. URLs and paths may contain identifiers, and error messages or supplied raw data may contain sensitive text.</p>
+    <p>This report writer does not collect HARs, cookies, authorization headers or secrets. It renders the supplied audit, including any allowlisted cache headers already in diagnostics; HTML escaping is not secret redaction. Evidence links are restricted to local relative image paths. No scripts, external resources or web fonts are used.</p>
+  </section>
+</main></body></html>
+`;
+    const directory = resolve(outputDirectory);
+    await mkdir(directory, { recursive: true });
+    const reportPath = resolve(directory, "report.html");
+    await writeFile(reportPath, html, "utf8");
+    return reportPath;
+}

package/dist/engine/settings.d.mts

@@ -0,0 +1,11 @@
+export declare const defaultSettings: {
+    repeats: number;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    sourceDwellMs: number;
+    preClickHoverMs: number;
+    pageObservationMs: number;
+    navigationObservationMs: number;
+};

package/dist/engine/settings.mjs

@@ -0,0 +1,8 @@
+export const defaultSettings = {
+    repeats: 3,
+    viewport: { width: 1440, height: 1000 },
+    sourceDwellMs: 4000,
+    preClickHoverMs: 150,
+    pageObservationMs: 5000,
+    navigationObservationMs: 30000,
+};

package/dist/findings.d.ts

@@ -0,0 +1 @@
+export { gradeTiming, imageFinding, navigationFindings, navigationMetricTypes, pageFindings, thresholds, } from "./engine/findings.mjs";

package/dist/findings.js

@@ -0,0 +1 @@
+export { gradeTiming, imageFinding, navigationFindings, navigationMetricTypes, pageFindings, thresholds, } from "./engine/findings.mjs";

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { defineAudit } from "./config/define.ts";
+export { defaultSettings } from "./config/defaults.ts";
+export { AuditConfigError } from "./config/errors.ts";
+export { marker } from "./config/marker.ts";
+export { runAudit } from "./run.ts";
+export type { AuditDocument, AuditResult, RunOptions } from "./run.ts";
+export type { AuditConfigErrorCode } from "./config/errors.ts";
+export type { MarkerInput, MarkerOptions, MarkerPattern, MarkerRule } from "./config/types.ts";
+export type { AuditConfig, AuditConfigInput, AuditSettings, AuditSettingsInput, JourneyInput, JourneySpec, MilestoneInput, MilestoneSpec, PageInput, PageSpec, Viewport, } from "./config/types.ts";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { defineAudit } from "./config/define.js";
+export { defaultSettings } from "./config/defaults.js";
+export { AuditConfigError } from "./config/errors.js";
+export { marker } from "./config/marker.js";
+export { runAudit } from "./run.js";

package/dist/infra.d.ts

@@ -0,0 +1,2 @@
+export { buildArtifactManifest } from "./engine/artifacts.mjs";
+export { validateAuditDocument, readAuditBundle } from "./engine/audit-archive.mjs";