@forkpoint/agent-lighthouse-core 0.3.0 → 0.4.0

package/dist/index.d.mts

@@ -198,8 +198,89 @@ interface ReadinessVitals {
     technical: number;
 }
 
-type ProgressCallback = (pct: number, phase: string) => void | Promise<void>;
-declare function runScan(url: string, onProgress?: ProgressCallback, pageOverrides?: PageOverride[] | null, signal?: AbortSignal): Promise<ScanReport>;
+type PhaseId = 'fetch-root' | 'fetch-pages' | 'analyze' | 'audits' | 'report';
+type ScanEvent = {
+    type: 'scan:start';
+    url: string;
+    fraction: number;
+    elapsedMs: number;
+} | {
+    type: 'phase:start';
+    phase: PhaseId;
+    totalUnits: number;
+    fraction: number;
+    elapsedMs: number;
+} | {
+    type: 'unit:done';
+    phase: PhaseId;
+    completed: number;
+    total: number;
+    label?: string;
+    fraction: number;
+    elapsedMs: number;
+} | {
+    type: 'unit:fail';
+    phase: PhaseId;
+    label: string;
+    error: string;
+    fraction: number;
+    elapsedMs: number;
+} | {
+    type: 'phase:done';
+    phase: PhaseId;
+    durationMs: number;
+    fraction: number;
+    elapsedMs: number;
+} | {
+    type: 'scan:done';
+    durationMs: number;
+    score: number;
+    fraction: number;
+    elapsedMs: number;
+};
+/**
+ * How much of the overall scan fraction each phase owns. Sums to 1 so the
+ * fraction of a finished scan is exactly 1.
+ */
+declare const PHASE_WEIGHTS: Record<PhaseId, number>;
+/**
+ * Turns scan milestones into {@link ScanEvent}s. Owns the fraction math
+ * (`Σ weights of done phases + current phase weight × completed/total`),
+ * clamps it to be monotonic non-decreasing, and stamps `fraction`/`elapsedMs`
+ * onto every event. Emission is synchronous — throttling is a consumer concern.
+ */
+declare class ProgressTracker {
+    private readonly onEvent;
+    private readonly startMs;
+    private doneWeight;
+    private phase;
+    private phaseStartMs;
+    private totalUnits;
+    private completedUnits;
+    private lastFraction;
+    constructor(onEvent: (event: ScanEvent) => void);
+    /** Fraction of the whole scan that is complete, in [0, 1]. Never decreases. */
+    get fraction(): number;
+    /** Stamp an event with the current fraction/elapsed and advance the floor. */
+    private stamp;
+    private elapsedMs;
+    scanStart(url: string): void;
+    phaseStart(phase: PhaseId, totalUnits: number): void;
+    /** Correct the current phase's unit total (e.g. discovery finds pages mid-phase). */
+    setPhaseTotal(totalUnits: number): void;
+    unitDone(label?: string): void;
+    /** A failed unit still counts as settled work so the phase can complete. */
+    unitFail(label: string, error: string): void;
+    phaseDone(): void;
+    scanDone(score: number): void;
+}
+
+interface ScanOptions {
+    onEvent?: (event: ScanEvent) => void;
+    pages?: PageOverride[] | null;
+    signal?: AbortSignal;
+}
+declare function runScan(url: string, options?: ScanOptions): Promise<ScanReport>;
 
 interface A11yNodeFinding {
     target: string;
@@ -310,12 +391,37 @@ interface AuditRunResult {
     categories: CategoryResult[];
     overallScore: number;
 }
-type ProgressFn = (completed: number, total: number) => void;
+/**
+ * Progress emitted per settled audit. The orchestrator forwards these into the
+ * ProgressTracker, which owns counting and fraction/elapsed stamping.
+ */
+type AuditProgressEvent = {
+    type: 'unit:done';
+    label: string;
+} | {
+    type: 'unit:fail';
+    label: string;
+    error: string;
+};
+interface AuditPlan {
+    runnable: Array<{
+        reg: AuditRegistration;
+        categoryId: string;
+    }>;
+    skipped: CheckResult[];
+}
+/**
+ * Split a scan config into the audits that will actually execute and the
+ * page-type-skipped `na` stubs. Exported so the orchestrator can size the
+ * audits progress phase before running it.
+ */
+declare function planAudits(ctx: CheckContext, config: ScanConfig): AuditPlan;
 /**
  * Execute all audits registered in the config against the scan context.
  * Returns check results grouped into categories with weighted scores.
+ * Pass a precomputed `plan` (from {@link planAudits}) to avoid recomputing it.
  */
-declare function runAudits(ctx: CheckContext, config: ScanConfig, onProgress?: ProgressFn): Promise<AuditRunResult>;
+declare function runAudits(ctx: CheckContext, config: ScanConfig, onEvent?: (event: AuditProgressEvent) => void, plan?: AuditPlan): Promise<AuditRunResult>;
 
 declare function parseHtml(html: string): CheerioAPI;
 declare function extractJsonLd($: CheerioAPI): object[];
@@ -711,4 +817,4 @@ declare class Logger {
 }
 declare const logger: Logger;
 
-export { type AgentLighthouseConfig, Audit, type AuditGuidance, AuditGuidanceSchema, type AuditMeta, AuditMetaSchema, type AuditRegistration, type AuditResult, AuditResultSchema, type AuditRunResult, CATEGORY_NAMES, CATEGORY_WEIGHTS, type CategoryConfig, type CategoryResult, type CheckContext, type CheckFn, type CheckPriority, CheckPrioritySchema, type CheckRecommendation, type CheckResult, CheckResultSchema, type CheckStatus, CheckStatusSchema, DEFAULT_SCAN_LIMIT, type FetchOptions, type FetchResult, type FieldStatus, type FixEffort, FixEffortSchema, MAX_CONCURRENT_REQUESTS, MAX_PAGES_PER_SCAN, MAX_RESPONSE_BODY_BYTES, PAGE_TYPE_LABELS, PRESETS, type PageContext, type PageOverride, type PageType, type PresetName, type PresetOptions, type ProductFieldVerification, READINESS_WEIGHTS, REQUEST_TIMEOUT_MS, type ReadinessVitals, SCANNER_USER_AGENT, SCAN_TIMEOUT_MS, SCORE_TIER_LABELS, type ScanConfig, type ScanReport, type ScoreDisplayMode, ScoreDisplayModeSchema, type ScoreTier, TAG_SCAN_ERROR, TAG_SKIPPED_PAGE_TYPE, type WafProtection, buildCategoryResult, calculateCategoryScore, calculateOverallScore, createFetcher, defaultConfig, defineConfig, detectPageType, detectWafProtection, extractDomain, extractForms, extractHeadLinks, extractHeadings, extractImages, extractInternalLinks, extractJsonLd, extractMarkdownLinks, extractMetaTags, extractNavLinks, extractProductFieldVerification, extractScripts, extractStylesheetUrls, flattenJsonLd, getMainContentText, getPreset, getScoreTier, getTierColor, getTierLabel, getWordCount, isPrivateIp, isSafeUrl, joinUrl, loadConfigFile, logger, normalizeUrl, parseHtml, runAudits, runScan };
+export { type AgentLighthouseConfig, Audit, type AuditGuidance, AuditGuidanceSchema, type AuditMeta, AuditMetaSchema, type AuditPlan, type AuditProgressEvent, type AuditRegistration, type AuditResult, AuditResultSchema, type AuditRunResult, CATEGORY_NAMES, CATEGORY_WEIGHTS, type CategoryConfig, type CategoryResult, type CheckContext, type CheckFn, type CheckPriority, CheckPrioritySchema, type CheckRecommendation, type CheckResult, CheckResultSchema, type CheckStatus, CheckStatusSchema, DEFAULT_SCAN_LIMIT, type FetchOptions, type FetchResult, type FieldStatus, type FixEffort, FixEffortSchema, MAX_CONCURRENT_REQUESTS, MAX_PAGES_PER_SCAN, MAX_RESPONSE_BODY_BYTES, PAGE_TYPE_LABELS, PHASE_WEIGHTS, PRESETS, type PageContext, type PageOverride, type PageType, type PhaseId, type PresetName, type PresetOptions, type ProductFieldVerification, ProgressTracker, READINESS_WEIGHTS, REQUEST_TIMEOUT_MS, type ReadinessVitals, SCANNER_USER_AGENT, SCAN_TIMEOUT_MS, SCORE_TIER_LABELS, type ScanConfig, type ScanEvent, type ScanOptions, type ScanReport, type ScoreDisplayMode, ScoreDisplayModeSchema, type ScoreTier, TAG_SCAN_ERROR, TAG_SKIPPED_PAGE_TYPE, type WafProtection, buildCategoryResult, calculateCategoryScore, calculateOverallScore, createFetcher, defaultConfig, defineConfig, detectPageType, detectWafProtection, extractDomain, extractForms, extractHeadLinks, extractHeadings, extractImages, extractInternalLinks, extractJsonLd, extractMarkdownLinks, extractMetaTags, extractNavLinks, extractProductFieldVerification, extractScripts, extractStylesheetUrls, flattenJsonLd, getMainContentText, getPreset, getScoreTier, getTierColor, getTierLabel, getWordCount, isPrivateIp, isSafeUrl, joinUrl, loadConfigFile, logger, normalizeUrl, parseHtml, planAudits, runAudits, runScan };

package/dist/index.d.ts

@@ -198,8 +198,89 @@ interface ReadinessVitals {
     technical: number;
 }
 
-type ProgressCallback = (pct: number, phase: string) => void | Promise<void>;
-declare function runScan(url: string, onProgress?: ProgressCallback, pageOverrides?: PageOverride[] | null, signal?: AbortSignal): Promise<ScanReport>;
+type PhaseId = 'fetch-root' | 'fetch-pages' | 'analyze' | 'audits' | 'report';
+type ScanEvent = {
+    type: 'scan:start';
+    url: string;
+    fraction: number;
+    elapsedMs: number;
+} | {
+    type: 'phase:start';
+    phase: PhaseId;
+    totalUnits: number;
+    fraction: number;
+    elapsedMs: number;
+} | {
+    type: 'unit:done';
+    phase: PhaseId;
+    completed: number;
+    total: number;
+    label?: string;
+    fraction: number;
+    elapsedMs: number;
+} | {
+    type: 'unit:fail';
+    phase: PhaseId;
+    label: string;
+    error: string;
+    fraction: number;
+    elapsedMs: number;
+} | {
+    type: 'phase:done';
+    phase: PhaseId;
+    durationMs: number;
+    fraction: number;
+    elapsedMs: number;
+} | {
+    type: 'scan:done';
+    durationMs: number;
+    score: number;
+    fraction: number;
+    elapsedMs: number;
+};
+/**
+ * How much of the overall scan fraction each phase owns. Sums to 1 so the
+ * fraction of a finished scan is exactly 1.
+ */
+declare const PHASE_WEIGHTS: Record<PhaseId, number>;
+/**
+ * Turns scan milestones into {@link ScanEvent}s. Owns the fraction math
+ * (`Σ weights of done phases + current phase weight × completed/total`),
+ * clamps it to be monotonic non-decreasing, and stamps `fraction`/`elapsedMs`
+ * onto every event. Emission is synchronous — throttling is a consumer concern.
+ */
+declare class ProgressTracker {
+    private readonly onEvent;
+    private readonly startMs;
+    private doneWeight;
+    private phase;
+    private phaseStartMs;
+    private totalUnits;
+    private completedUnits;
+    private lastFraction;
+    constructor(onEvent: (event: ScanEvent) => void);
+    /** Fraction of the whole scan that is complete, in [0, 1]. Never decreases. */
+    get fraction(): number;
+    /** Stamp an event with the current fraction/elapsed and advance the floor. */
+    private stamp;
+    private elapsedMs;
+    scanStart(url: string): void;
+    phaseStart(phase: PhaseId, totalUnits: number): void;
+    /** Correct the current phase's unit total (e.g. discovery finds pages mid-phase). */
+    setPhaseTotal(totalUnits: number): void;
+    unitDone(label?: string): void;
+    /** A failed unit still counts as settled work so the phase can complete. */
+    unitFail(label: string, error: string): void;
+    phaseDone(): void;
+    scanDone(score: number): void;
+}
+
+interface ScanOptions {
+    onEvent?: (event: ScanEvent) => void;
+    pages?: PageOverride[] | null;
+    signal?: AbortSignal;
+}
+declare function runScan(url: string, options?: ScanOptions): Promise<ScanReport>;
 
 interface A11yNodeFinding {
     target: string;
@@ -310,12 +391,37 @@ interface AuditRunResult {
     categories: CategoryResult[];
     overallScore: number;
 }
-type ProgressFn = (completed: number, total: number) => void;
+/**
+ * Progress emitted per settled audit. The orchestrator forwards these into the
+ * ProgressTracker, which owns counting and fraction/elapsed stamping.
+ */
+type AuditProgressEvent = {
+    type: 'unit:done';
+    label: string;
+} | {
+    type: 'unit:fail';
+    label: string;
+    error: string;
+};
+interface AuditPlan {
+    runnable: Array<{
+        reg: AuditRegistration;
+        categoryId: string;
+    }>;
+    skipped: CheckResult[];
+}
+/**
+ * Split a scan config into the audits that will actually execute and the
+ * page-type-skipped `na` stubs. Exported so the orchestrator can size the
+ * audits progress phase before running it.
+ */
+declare function planAudits(ctx: CheckContext, config: ScanConfig): AuditPlan;
 /**
  * Execute all audits registered in the config against the scan context.
  * Returns check results grouped into categories with weighted scores.
+ * Pass a precomputed `plan` (from {@link planAudits}) to avoid recomputing it.
  */
-declare function runAudits(ctx: CheckContext, config: ScanConfig, onProgress?: ProgressFn): Promise<AuditRunResult>;
+declare function runAudits(ctx: CheckContext, config: ScanConfig, onEvent?: (event: AuditProgressEvent) => void, plan?: AuditPlan): Promise<AuditRunResult>;
 
 declare function parseHtml(html: string): CheerioAPI;
 declare function extractJsonLd($: CheerioAPI): object[];
@@ -711,4 +817,4 @@ declare class Logger {
 }
 declare const logger: Logger;
 
-export { type AgentLighthouseConfig, Audit, type AuditGuidance, AuditGuidanceSchema, type AuditMeta, AuditMetaSchema, type AuditRegistration, type AuditResult, AuditResultSchema, type AuditRunResult, CATEGORY_NAMES, CATEGORY_WEIGHTS, type CategoryConfig, type CategoryResult, type CheckContext, type CheckFn, type CheckPriority, CheckPrioritySchema, type CheckRecommendation, type CheckResult, CheckResultSchema, type CheckStatus, CheckStatusSchema, DEFAULT_SCAN_LIMIT, type FetchOptions, type FetchResult, type FieldStatus, type FixEffort, FixEffortSchema, MAX_CONCURRENT_REQUESTS, MAX_PAGES_PER_SCAN, MAX_RESPONSE_BODY_BYTES, PAGE_TYPE_LABELS, PRESETS, type PageContext, type PageOverride, type PageType, type PresetName, type PresetOptions, type ProductFieldVerification, READINESS_WEIGHTS, REQUEST_TIMEOUT_MS, type ReadinessVitals, SCANNER_USER_AGENT, SCAN_TIMEOUT_MS, SCORE_TIER_LABELS, type ScanConfig, type ScanReport, type ScoreDisplayMode, ScoreDisplayModeSchema, type ScoreTier, TAG_SCAN_ERROR, TAG_SKIPPED_PAGE_TYPE, type WafProtection, buildCategoryResult, calculateCategoryScore, calculateOverallScore, createFetcher, defaultConfig, defineConfig, detectPageType, detectWafProtection, extractDomain, extractForms, extractHeadLinks, extractHeadings, extractImages, extractInternalLinks, extractJsonLd, extractMarkdownLinks, extractMetaTags, extractNavLinks, extractProductFieldVerification, extractScripts, extractStylesheetUrls, flattenJsonLd, getMainContentText, getPreset, getScoreTier, getTierColor, getTierLabel, getWordCount, isPrivateIp, isSafeUrl, joinUrl, loadConfigFile, logger, normalizeUrl, parseHtml, runAudits, runScan };
+export { type AgentLighthouseConfig, Audit, type AuditGuidance, AuditGuidanceSchema, type AuditMeta, AuditMetaSchema, type AuditPlan, type AuditProgressEvent, type AuditRegistration, type AuditResult, AuditResultSchema, type AuditRunResult, CATEGORY_NAMES, CATEGORY_WEIGHTS, type CategoryConfig, type CategoryResult, type CheckContext, type CheckFn, type CheckPriority, CheckPrioritySchema, type CheckRecommendation, type CheckResult, CheckResultSchema, type CheckStatus, CheckStatusSchema, DEFAULT_SCAN_LIMIT, type FetchOptions, type FetchResult, type FieldStatus, type FixEffort, FixEffortSchema, MAX_CONCURRENT_REQUESTS, MAX_PAGES_PER_SCAN, MAX_RESPONSE_BODY_BYTES, PAGE_TYPE_LABELS, PHASE_WEIGHTS, PRESETS, type PageContext, type PageOverride, type PageType, type PhaseId, type PresetName, type PresetOptions, type ProductFieldVerification, ProgressTracker, READINESS_WEIGHTS, REQUEST_TIMEOUT_MS, type ReadinessVitals, SCANNER_USER_AGENT, SCAN_TIMEOUT_MS, SCORE_TIER_LABELS, type ScanConfig, type ScanEvent, type ScanOptions, type ScanReport, type ScoreDisplayMode, ScoreDisplayModeSchema, type ScoreTier, TAG_SCAN_ERROR, TAG_SKIPPED_PAGE_TYPE, type WafProtection, buildCategoryResult, calculateCategoryScore, calculateOverallScore, createFetcher, defaultConfig, defineConfig, detectPageType, detectWafProtection, extractDomain, extractForms, extractHeadLinks, extractHeadings, extractImages, extractInternalLinks, extractJsonLd, extractMarkdownLinks, extractMetaTags, extractNavLinks, extractProductFieldVerification, extractScripts, extractStylesheetUrls, flattenJsonLd, getMainContentText, getPreset, getScoreTier, getTierColor, getTierLabel, getWordCount, isPrivateIp, isSafeUrl, joinUrl, loadConfigFile, logger, normalizeUrl, parseHtml, planAudits, runAudits, runScan };

package/dist/index.js

@@ -45,7 +45,9 @@ __export(index_exports, {
   MAX_PAGES_PER_SCAN: () => MAX_PAGES_PER_SCAN,
   MAX_RESPONSE_BODY_BYTES: () => MAX_RESPONSE_BODY_BYTES,
   PAGE_TYPE_LABELS: () => PAGE_TYPE_LABELS,
+  PHASE_WEIGHTS: () => PHASE_WEIGHTS,
   PRESETS: () => PRESETS,
+  ProgressTracker: () => ProgressTracker,
   READINESS_WEIGHTS: () => READINESS_WEIGHTS,
   REQUEST_TIMEOUT_MS: () => REQUEST_TIMEOUT_MS,
   SCANNER_USER_AGENT: () => SCANNER_USER_AGENT,
@@ -89,6 +91,7 @@ __export(index_exports, {
   logger: () => logger,
   normalizeUrl: () => normalizeUrl,
   parseHtml: () => parseHtml,
+  planAudits: () => planAudits,
   runAudits: () => runAudits,
   runScan: () => runScan
 });
@@ -17492,17 +17495,17 @@ function stubCheck(meta, tag, explanation) {
     tags: [tag]
   };
 }
-async function runAudits(ctx, config, onProgress) {
+function planAudits(ctx, config) {
   const scannedPageTypes = new Set(ctx.pages.map((p) => p.pageType));
-  const all = [];
-  const allChecks = [];
+  const runnable = [];
+  const skipped = [];
   for (const cat of config.categories) {
     const regs = config.audits[cat.id] ?? [];
     for (const reg2 of regs) {
       const applicable = reg2.meta.applicablePageTypes;
       if (applicable && applicable.length > 0) {
         if (!applicable.some((pt) => scannedPageTypes.has(pt))) {
-          allChecks.push(
+          skipped.push(
             stubCheck(
               reg2.meta,
               TAG_SKIPPED_PAGE_TYPE,
@@ -17512,30 +17515,35 @@ async function runAudits(ctx, config, onProgress) {
           continue;
         }
       }
-      all.push({ reg: reg2, categoryId: cat.id });
+      runnable.push({ reg: reg2, categoryId: cat.id });
     }
   }
-  const totalAudits = all.length;
-  let completed = 0;
+  return { runnable, skipped };
+}
+async function runAudits(ctx, config, onEvent, plan) {
+  const { runnable, skipped } = plan ?? planAudits(ctx, config);
+  const allChecks = [...skipped];
   const batchSize = 20;
-  for (let i = 0; i < totalAudits; i += batchSize) {
-    const batch = all.slice(i, i + batchSize);
+  for (let i = 0; i < runnable.length; i += batchSize) {
+    const batch = runnable.slice(i, i + batchSize);
     const batchResults = await Promise.all(
       batch.map(async ({ reg: reg2 }) => {
+        const label2 = `${reg2.meta.id} ${reg2.meta.title}`;
         try {
           const instance = reg2.create();
           const result = await instance.audit(ctx);
-          return instance.toCheckResult(result);
+          const check = instance.toCheckResult(result);
+          onEvent?.({ type: "unit:done", label: label2 });
+          return check;
         } catch (err) {
           logger.error({ err, auditId: reg2.meta.id }, "[scanner] Audit error");
           const message = err instanceof Error ? err.message : String(err);
+          onEvent?.({ type: "unit:fail", label: label2, error: message });
           return stubCheck(reg2.meta, TAG_SCAN_ERROR, `Audit failed to run: ${message}`);
         }
       })
     );
     allChecks.push(...batchResults);
-    completed += batchResults.length;
-    onProgress?.(completed, totalAudits);
   }
   const categories = config.categories.map((cat) => {
     const catChecks = allChecks.filter((c) => c.category === cat.id);
@@ -17583,6 +17591,110 @@ function buildWeightedCategoryResult(cat, checks2, registrations) {
   };
 }
 
+// src/progress.ts
+var PHASE_WEIGHTS = {
+  "fetch-root": 0.35,
+  "fetch-pages": 0.2,
+  analyze: 0.1,
+  audits: 0.3,
+  report: 0.05
+};
+var ProgressTracker = class {
+  onEvent;
+  startMs;
+  doneWeight = 0;
+  phase = null;
+  phaseStartMs = 0;
+  totalUnits = 0;
+  completedUnits = 0;
+  lastFraction = 0;
+  constructor(onEvent) {
+    this.onEvent = onEvent;
+    this.startMs = performance.now();
+  }
+  /** Fraction of the whole scan that is complete, in [0, 1]. Never decreases. */
+  get fraction() {
+    let f = this.doneWeight;
+    if (this.phase !== null) {
+      const ratio = this.totalUnits > 0 ? Math.min(1, this.completedUnits / this.totalUnits) : 0;
+      f += PHASE_WEIGHTS[this.phase] * ratio;
+    }
+    return Math.min(1, Math.max(f, this.lastFraction));
+  }
+  /** Stamp an event with the current fraction/elapsed and advance the floor. */
+  stamp() {
+    const fraction = this.fraction;
+    this.lastFraction = Math.max(this.lastFraction, fraction);
+    return { fraction, elapsedMs: this.elapsedMs() };
+  }
+  elapsedMs() {
+    return Math.max(0, Math.round(performance.now() - this.startMs));
+  }
+  scanStart(url) {
+    this.onEvent({ type: "scan:start", url, ...this.stamp() });
+  }
+  phaseStart(phase, totalUnits) {
+    this.phase = phase;
+    this.phaseStartMs = performance.now();
+    this.totalUnits = Math.max(0, totalUnits);
+    this.completedUnits = 0;
+    this.onEvent({
+      type: "phase:start",
+      phase,
+      totalUnits: this.totalUnits,
+      ...this.stamp()
+    });
+  }
+  /** Correct the current phase's unit total (e.g. discovery finds pages mid-phase). */
+  setPhaseTotal(totalUnits) {
+    this.totalUnits = Math.max(this.completedUnits, totalUnits);
+  }
+  unitDone(label2) {
+    const phase = this.phase;
+    if (phase === null) return;
+    this.completedUnits += 1;
+    this.onEvent({
+      type: "unit:done",
+      phase,
+      completed: this.completedUnits,
+      total: this.totalUnits,
+      label: label2,
+      ...this.stamp()
+    });
+  }
+  /** A failed unit still counts as settled work so the phase can complete. */
+  unitFail(label2, error) {
+    const phase = this.phase;
+    if (phase === null) return;
+    this.completedUnits += 1;
+    this.onEvent({
+      type: "unit:fail",
+      phase,
+      label: label2,
+      error,
+      ...this.stamp()
+    });
+  }
+  phaseDone() {
+    const phase = this.phase;
+    if (phase === null) return;
+    this.phase = null;
+    this.doneWeight += PHASE_WEIGHTS[phase];
+    const durationMs = Math.max(0, Math.round(performance.now() - this.phaseStartMs));
+    this.totalUnits = 0;
+    this.completedUnits = 0;
+    this.onEvent({
+      type: "phase:done",
+      phase,
+      durationMs,
+      ...this.stamp()
+    });
+  }
+  scanDone(score) {
+    this.onEvent({ type: "scan:done", durationMs: this.elapsedMs(), score, ...this.stamp() });
+  }
+};
+
 // src/audits/accessibility/runner.ts
 var import_jsdom = require("jsdom");
 
@@ -23094,9 +23206,11 @@ function discoverPages(homepageUrl, domain, rootFiles, homepage$, exclude, maxAd
   }
   return selected;
 }
-async function runScan(url, onProgress, pageOverrides, signal) {
-  const progress = onProgress ?? (() => {
-  });
+async function runScan(url, options) {
+  const onEvent = options?.onEvent;
+  const pageOverrides = options?.pages;
+  const signal = options?.signal;
+  const tracker = new ProgressTracker((event) => onEvent?.(event));
   const start = performance.now();
   const fetcher = createFetcher();
   const baseUrl = new URL(url).origin;
@@ -23119,7 +23233,7 @@ async function runScan(url, onProgress, pageOverrides, signal) {
   }
   logger.debug({ url, domain }, "[orchestrator] Starting runScan");
   signal?.throwIfAborted();
-  await progress(5, "Fetching root files");
+  tracker.scanStart(displayUrl);
   const rootFilePaths = [
     "/robots.txt",
     "/llms.txt",
@@ -23157,19 +23271,26 @@ async function runScan(url, onProgress, pageOverrides, signal) {
     "/our-story"
   ];
   logger.debug({ count: rootFilePaths.length }, "[orchestrator] Phase 1: Fetching root files");
+  tracker.phaseStart("fetch-root", rootFilePaths.length);
   const rootResults = await Promise.all(
-    rootFilePaths.map((path) => fetcher.fetch({ url: `${baseUrl}${path}`, signal }))
+    rootFilePaths.map(
+      (path) => fetcher.fetch({ url: `${baseUrl}${path}`, signal }).then((result) => {
+        tracker.unitDone(path);
+        return result;
+      })
+    )
   );
   const rootFiles = {};
   rootFilePaths.forEach((path, i) => {
     rootFiles[path] = rootResults[i];
   });
-  await progress(25, "Root files fetched");
+  tracker.phaseDone();
   logger.debug("[orchestrator] Phase 1 complete: Root files fetched");
   signal?.throwIfAborted();
-  await progress(30, "Fetching pages");
   logger.debug("[orchestrator] Phase 2: Fetching pages");
+  tracker.phaseStart("fetch-pages", 1);
   const homepageResult = await fetcher.fetch({ url, signal });
+  tracker.unitDone(displayUrl);
   const homepage$ = homepageResult.status === 200 && homepageResult.body ? parseHtml(homepageResult.body) : null;
   const discoverLimit = Math.max(0, MAX_PAGES_PER_SCAN - 1 - overrideUrls.length);
   const discoveredUrls = homepage$ ? discoverPages(url, domain, rootFiles, homepage$, new Set(overrideTypeByKey.keys()), discoverLimit) : [];
@@ -23178,12 +23299,22 @@ async function runScan(url, onProgress, pageOverrides, signal) {
     "[orchestrator] Page set: overrides + discovered URLs"
   );
   const extraUrls = [...overrideUrls, ...discoveredUrls];
-  await progress(40, `Analyzing ${1 + extraUrls.length} pages`);
+  tracker.setPhaseTotal(1 + extraUrls.length);
   const extraResults = await Promise.all(
-    extraUrls.map((pageUrl) => fetcher.fetch({ url: pageUrl, signal }))
+    extraUrls.map(
+      (pageUrl) => fetcher.fetch({ url: pageUrl, signal }).then((result) => {
+        tracker.unitDone(pageUrl);
+        return result;
+      })
+    )
   );
+  tracker.phaseDone();
   const allPageResults = [homepageResult, ...extraResults];
   const allPageUrls = [displayUrl, ...extraUrls];
+  tracker.phaseStart(
+    "analyze",
+    allPageResults.filter((r) => r.status === 200 && r.body).length
+  );
   const pages = allPageResults.map((r, i) => ({ result: r, url: allPageUrls[i], index: i })).filter((p) => p.result.status === 200 && p.result.body).map((p) => {
     const $ = parseHtml(p.result.body);
     const jsonLd = extractJsonLd($);
@@ -23191,6 +23322,7 @@ async function runScan(url, onProgress, pageOverrides, signal) {
     const meta = extractMetaTags($);
     const isFirstPage = p.index === 0;
     const forcedType = overrideTypeByKey.get(p.url.replace(/\/$/, ""));
+    tracker.unitDone(p.url);
     return {
       url: p.url,
       pageType: forcedType ?? detectPageType(p.url, $, structuredData, meta, isFirstPage),
@@ -23208,13 +23340,12 @@ async function runScan(url, onProgress, pageOverrides, signal) {
       p.a11yResults = await runA11yForHtml(p.fetchResult.body, p.url, A11Y_RULES);
     })
   );
-  await progress(55, "Page analysis complete");
+  tracker.phaseDone();
   logger.debug(
     { pagesAnalyzed: pages.length },
     "[orchestrator] Phase 2 complete: Page analysis complete"
   );
   signal?.throwIfAborted();
-  await progress(60, "Running audits");
   logger.debug("[orchestrator] Phase 3: Running audits");
   const wafProtection = detectWafProtection(url, homepageResult, rootFiles, pages.length);
   const ctx = {
@@ -23222,19 +23353,27 @@ async function runScan(url, onProgress, pageOverrides, signal) {
     pages,
     domain,
     baseUrl,
-    fetch: (options) => fetcher.fetch({ ...options, signal }),
+    fetch: (options2) => fetcher.fetch({ ...options2, signal }),
     wafProtection: wafProtection ?? void 0
   };
+  const auditPlan = planAudits(ctx, defaultConfig);
+  tracker.phaseStart("audits", auditPlan.runnable.length);
   const {
     checks: allChecks,
     categories,
     overallScore
-  } = await runAudits(ctx, defaultConfig, (completed, total) => {
-    const checkProgress = 60 + Math.round(completed / total * 30);
-    void progress(checkProgress, `Running audits (${completed}/${total})`);
-  });
+  } = await runAudits(
+    ctx,
+    defaultConfig,
+    (event) => {
+      if (event.type === "unit:done") tracker.unitDone(event.label);
+      else tracker.unitFail(event.label, event.error);
+    },
+    auditPlan
+  );
+  tracker.phaseDone();
   logger.debug("[orchestrator] Phase 3 complete: Audits finished");
-  await progress(97, "Building report");
+  tracker.phaseStart("report", 1);
   logger.debug("[orchestrator] Phase 4: Building final report");
   const durationMs = Math.round(performance.now() - start);
   const recommendations = allChecks.filter((c) => c.status !== "pass").slice().sort((a, b) => {
@@ -23251,7 +23390,6 @@ async function runScan(url, onProgress, pageOverrides, signal) {
   const topPasses = allChecks.filter((c) => c.status === "pass").slice().sort(
     (a, b) => (weightMap.get(b.id) ?? 1) - (weightMap.get(a.id) ?? 1)
   ).slice(0, 10);
-  await progress(100, "Complete");
   const readinessVitals = calculateReadinessVitals(allChecks);
   const readinessScore = Math.round(
     readinessVitals.commerce * READINESS_WEIGHTS.commerce + readinessVitals.content * READINESS_WEIGHTS.content + readinessVitals.botAccessibility * READINESS_WEIGHTS.botAccessibility + readinessVitals.technical * READINESS_WEIGHTS.technical
@@ -23281,6 +23419,9 @@ async function runScan(url, onProgress, pageOverrides, signal) {
     productFields: [...overrideTypeByKey.values()].includes("product") ? extractProductFieldVerification(pages) : void 0
   };
   report.summary = generateScanSummary(report);
+  tracker.unitDone();
+  tracker.phaseDone();
+  tracker.scanDone(overallScore);
   logger.debug({ durationMs, score: overallScore }, "[orchestrator] runScan complete");
   return report;
 }
@@ -23466,7 +23607,9 @@ function loadConfigFile(customPath) {
   MAX_PAGES_PER_SCAN,
   MAX_RESPONSE_BODY_BYTES,
   PAGE_TYPE_LABELS,
+  PHASE_WEIGHTS,
   PRESETS,
+  ProgressTracker,
   READINESS_WEIGHTS,
   REQUEST_TIMEOUT_MS,
   SCANNER_USER_AGENT,
@@ -23510,6 +23653,7 @@ function loadConfigFile(customPath) {
   logger,
   normalizeUrl,
   parseHtml,
+  planAudits,
   runAudits,
   runScan
 });