playwright-checkpoint 0.3.0 → 0.4.0

package/dist/cli/index.cjs

@@ -37,11 +37,11 @@ __export(cli_exports, {
   runCli: () => runCli
 });
 module.exports = __toCommonJS(cli_exports);
-var import_node_path5 = __toESM(require("path"), 1);
+var import_node_path18 = __toESM(require("path"), 1);
 
 // src/report/index.ts
-var import_promises4 = __toESM(require("fs/promises"), 1);
-var import_node_path4 = __toESM(require("path"), 1);
+var import_promises16 = __toESM(require("fs/promises"), 1);
+var import_node_path17 = __toESM(require("path"), 1);
 
 // src/report/html-reporter.ts
 var import_promises = __toESM(require("fs/promises"), 1);
@@ -668,8 +668,1231 @@ var htmlReporter = {
 };
 
 // src/report/markdown-reporter.ts
+var import_promises14 = __toESM(require("fs/promises"), 1);
+var import_node_path15 = __toESM(require("path"), 1);
+
+// src/core.ts
+var import_promises13 = __toESM(require("fs/promises"), 1);
+var import_node_path14 = __toESM(require("path"), 1);
+
+// src/collectors/aria-snapshot.ts
 var import_promises2 = __toESM(require("fs/promises"), 1);
 var import_node_path2 = __toESM(require("path"), 1);
+function countSnapshotNodes(value) {
+  if (value == null) {
+    return 0;
+  }
+  if (Array.isArray(value)) {
+    return value.reduce((total, item) => total + countSnapshotNodes(item), 0);
+  }
+  if (typeof value !== "object") {
+    return 1;
+  }
+  const node = value;
+  const children = Array.isArray(node.children) ? node.children : [];
+  return 1 + children.reduce((total, child) => total + countSnapshotNodes(child), 0);
+}
+async function captureAriaSnapshot(page) {
+  try {
+    const root = page.locator(":root");
+    if (typeof root.ariaSnapshot === "function") {
+      const snapshot = await root.ariaSnapshot();
+      return snapshot ?? null;
+    }
+  } catch {
+  }
+  if (typeof page.accessibility?.snapshot === "function") {
+    try {
+      const snapshot = await page.accessibility.snapshot({ interestingOnly: false });
+      return snapshot ?? null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+var ariaSnapshotCollector = {
+  name: "aria-snapshot",
+  defaultEnabled: false,
+  async collect(ctx) {
+    const snapshot = await captureAriaSnapshot(ctx.page);
+    const nodeCount = countSnapshotNodes(snapshot);
+    const outputPath = import_node_path2.default.join(ctx.checkpointDir, "aria-snapshot.json");
+    const data = {
+      snapshot,
+      nodeCount
+    };
+    await import_promises2.default.writeFile(outputPath, `${JSON.stringify(data, null, 2)}
+`, "utf8");
+    return {
+      data,
+      artifacts: [
+        {
+          name: "aria-snapshot",
+          path: outputPath,
+          contentType: "application/json"
+        }
+      ],
+      summary: {
+        nodeCount
+      }
+    };
+  }
+};
+
+// src/collectors/axe.ts
+var import_promises3 = __toESM(require("fs/promises"), 1);
+var import_node_path3 = __toESM(require("path"), 1);
+
+// src/page-utils.ts
+async function settlePage(page) {
+  await page.waitForLoadState("domcontentloaded").catch(() => void 0);
+  await page.waitForLoadState("load", { timeout: 3e3 }).catch(() => void 0);
+}
+
+// src/collectors/axe.ts
+var axeLoader = () => import("@axe-core/playwright");
+var warnedAboutMissingAxe = false;
+function warnOnce(message, error) {
+  if (warnedAboutMissingAxe) {
+    return;
+  }
+  warnedAboutMissingAxe = true;
+  if (error instanceof Error) {
+    console.warn(`[playwright-checkpoint] ${message}`, error);
+    return;
+  }
+  if (error !== void 0) {
+    console.warn(`[playwright-checkpoint] ${message}`, String(error));
+    return;
+  }
+  console.warn(`[playwright-checkpoint] ${message}`);
+}
+function resolveAxeBuilder(module2) {
+  return module2.default ?? module2.AxeBuilder ?? null;
+}
+async function analyzeAccessibility(page, AxeBuilder) {
+  try {
+    await settlePage(page);
+    return await new AxeBuilder({ page }).analyze();
+  } catch {
+    await page.waitForTimeout(500);
+    await settlePage(page);
+    return await new AxeBuilder({ page }).analyze();
+  }
+}
+function skippedAxeResult(reason) {
+  return {
+    data: {
+      skipped: true,
+      reason,
+      violations: 0,
+      results: null
+    },
+    artifacts: [],
+    summary: {
+      violations: 0
+    }
+  };
+}
+var axeCollector = {
+  name: "axe",
+  defaultEnabled: true,
+  async collect(ctx) {
+    const timeoutBudgetMs = typeof ctx.config.timeoutMs === "number" ? ctx.config.timeoutMs : 5e3;
+    if (timeoutBudgetMs > 0) {
+      if (typeof ctx.adjustTimeout === "function") {
+        ctx.adjustTimeout(timeoutBudgetMs);
+      } else if (ctx.testInfo && typeof ctx.testInfo.setTimeout === "function") {
+        ctx.testInfo.setTimeout(ctx.testInfo.timeout + timeoutBudgetMs);
+      }
+    }
+    let module2;
+    try {
+      module2 = await axeLoader();
+    } catch (error) {
+      warnOnce("Skipping axe collector because @axe-core/playwright is unavailable.", error);
+      return skippedAxeResult("@axe-core/playwright is unavailable");
+    }
+    const AxeBuilder = resolveAxeBuilder(module2);
+    if (!AxeBuilder) {
+      warnOnce("Skipping axe collector because @axe-core/playwright did not expose an AxeBuilder export.");
+      return skippedAxeResult("@axe-core/playwright did not expose AxeBuilder");
+    }
+    const results = await analyzeAccessibility(ctx.page, AxeBuilder);
+    const violations = results && typeof results === "object" && Array.isArray(results.violations) ? results.violations.length : 0;
+    const axePath = import_node_path3.default.join(ctx.checkpointDir, "axe.json");
+    await import_promises3.default.writeFile(axePath, `${JSON.stringify(results, null, 2)}
+`, "utf8");
+    return {
+      data: {
+        skipped: false,
+        reason: null,
+        violations,
+        results
+      },
+      artifacts: [
+        {
+          name: "axe",
+          path: axePath,
+          contentType: "application/json"
+        }
+      ],
+      summary: {
+        violations
+      }
+    };
+  }
+};
+
+// src/collectors/console.ts
+var import_promises4 = __toESM(require("fs/promises"), 1);
+var import_node_path4 = __toESM(require("path"), 1);
+var consoleStates = /* @__PURE__ */ new WeakMap();
+function getLocation(message) {
+  const location2 = message.location();
+  if (!location2.url && location2.lineNumber == null && location2.columnNumber == null) {
+    return null;
+  }
+  return {
+    ...location2.url ? { url: location2.url } : {},
+    ...location2.lineNumber == null ? {} : { lineNumber: location2.lineNumber },
+    ...location2.columnNumber == null ? {} : { columnNumber: location2.columnNumber }
+  };
+}
+var consoleCollector = {
+  name: "console",
+  defaultEnabled: true,
+  async setup({ page }) {
+    if (consoleStates.has(page)) {
+      return;
+    }
+    const entries = [];
+    const recordConsoleMessage = (message) => {
+      if (message.type() !== "error") {
+        return;
+      }
+      entries.push({
+        type: message.type(),
+        text: message.text(),
+        location: getLocation(message),
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    };
+    const recordPageError = (error) => {
+      entries.push({
+        type: "pageerror",
+        text: error.message,
+        location: null,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    };
+    page.on("console", recordConsoleMessage);
+    page.on("pageerror", recordPageError);
+    consoleStates.set(page, {
+      entries,
+      offset: 0,
+      recordConsoleMessage,
+      recordPageError
+    });
+  },
+  async collect(ctx) {
+    const state = consoleStates.get(ctx.page);
+    const checkpointEntries = state ? state.entries.slice(state.offset) : [];
+    if (state) {
+      state.offset = state.entries.length;
+    }
+    const outputPath = import_node_path4.default.join(ctx.checkpointDir, "console-errors.json");
+    await import_promises4.default.writeFile(outputPath, `${JSON.stringify(checkpointEntries, null, 2)}
+`, "utf8");
+    return {
+      data: checkpointEntries,
+      artifacts: [
+        {
+          name: "console-errors",
+          path: outputPath,
+          contentType: "application/json"
+        }
+      ],
+      summary: {
+        consoleErrorCount: checkpointEntries.length
+      }
+    };
+  },
+  async teardown({ page }) {
+    const state = consoleStates.get(page);
+    if (!state) {
+      return;
+    }
+    page.off("console", state.recordConsoleMessage);
+    page.off("pageerror", state.recordPageError);
+    consoleStates.delete(page);
+  }
+};
+
+// src/collectors/dom-stats.ts
+var import_promises5 = __toESM(require("fs/promises"), 1);
+var import_node_path5 = __toESM(require("path"), 1);
+var domStatsCollector = {
+  name: "dom-stats",
+  defaultEnabled: false,
+  async collect(ctx) {
+    const stats = await ctx.page.evaluate(() => {
+      const allNodes = document.querySelectorAll("*");
+      const maxDepthFrom = (root) => {
+        if (!root) {
+          return 0;
+        }
+        let maxDepth = 1;
+        const queue = [{ node: root, depth: 1 }];
+        while (queue.length > 0) {
+          const current = queue.shift();
+          if (!current) {
+            continue;
+          }
+          maxDepth = Math.max(maxDepth, current.depth);
+          for (const child of Array.from(current.node.children)) {
+            queue.push({ node: child, depth: current.depth + 1 });
+          }
+        }
+        return maxDepth;
+      };
+      const maybeGetEventListeners = globalThis.getEventListeners;
+      let eventListenerCount = null;
+      if (typeof maybeGetEventListeners === "function") {
+        eventListenerCount = 0;
+        const targets = [window, document, ...Array.from(allNodes)];
+        for (const target of targets) {
+          try {
+            const listeners = maybeGetEventListeners(target) ?? {};
+            for (const entries of Object.values(listeners)) {
+              eventListenerCount += Array.isArray(entries) ? entries.length : 0;
+            }
+          } catch {
+          }
+        }
+      }
+      return {
+        nodeCount: allNodes.length,
+        maxDepth: maxDepthFrom(document.documentElement),
+        formCount: document.querySelectorAll("form").length,
+        imageCount: document.querySelectorAll("img").length,
+        scriptCount: document.querySelectorAll("script").length,
+        stylesheetCount: document.styleSheets.length,
+        eventListenerCount
+      };
+    });
+    const data = {
+      nodeCount: stats.nodeCount,
+      maxDepth: stats.maxDepth,
+      formCount: stats.formCount,
+      imageCount: stats.imageCount,
+      scriptCount: stats.scriptCount,
+      stylesheetCount: stats.stylesheetCount,
+      eventListenerCount: stats.eventListenerCount
+    };
+    const outputPath = import_node_path5.default.join(ctx.checkpointDir, "dom-stats.json");
+    await import_promises5.default.writeFile(outputPath, `${JSON.stringify(data, null, 2)}
+`, "utf8");
+    return {
+      data,
+      artifacts: [
+        {
+          name: "dom-stats",
+          path: outputPath,
+          contentType: "application/json"
+        }
+      ],
+      summary: {
+        nodeCount: data.nodeCount,
+        maxDepth: data.maxDepth,
+        formCount: data.formCount,
+        imageCount: data.imageCount
+      }
+    };
+  }
+};
+
+// src/collectors/forms.ts
+var import_promises6 = __toESM(require("fs/promises"), 1);
+var import_node_path6 = __toESM(require("path"), 1);
+var REDACTED = "[REDACTED]";
+var DEFAULT_REDACT_PATTERNS = ["password", "token", "secret", "api[_-]?key", "authorization", "bearer"];
+var EMAIL_LIKE_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+function toRegex(pattern) {
+  const trimmed = pattern.trim();
+  if (!trimmed) {
+    return null;
+  }
+  try {
+    return new RegExp(trimmed, "i");
+  } catch {
+    return null;
+  }
+}
+function redactionRegexes(ctx) {
+  const fromConfig = Array.isArray(ctx.config.redact) ? ctx.config.redact.filter((entry) => typeof entry === "string") : [];
+  return [...DEFAULT_REDACT_PATTERNS, ...ctx.redact, ...fromConfig].map((pattern) => toRegex(pattern)).filter((value) => value instanceof RegExp);
+}
+function shouldRedactText(value, regexes) {
+  if (EMAIL_LIKE_REGEX.test(value.trim())) {
+    return true;
+  }
+  return regexes.some((regex) => regex.test(value));
+}
+function fieldIdentifier(field) {
+  return [field.type, field.name, field.id, field.label, field.placeholder].filter((value) => !!value).join(" ");
+}
+function redactValue(value) {
+  if (value == null) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(() => REDACTED);
+  }
+  return REDACTED;
+}
+function fieldNeedsRedaction(field, regexes) {
+  if (shouldRedactText(fieldIdentifier(field), regexes)) {
+    return true;
+  }
+  if (field.value == null) {
+    return false;
+  }
+  if (Array.isArray(field.value)) {
+    return field.value.some((entry) => shouldRedactText(entry, regexes));
+  }
+  return shouldRedactText(field.value, regexes);
+}
+var formsCollector = {
+  name: "forms",
+  defaultEnabled: false,
+  async collect(ctx) {
+    const rawFields = await ctx.page.evaluate(() => {
+      const elements = Array.from(document.querySelectorAll("input, select, textarea"));
+      const isVisible = (element) => {
+        if (!(element instanceof HTMLElement)) {
+          return false;
+        }
+        const inputType = element instanceof HTMLInputElement ? element.type.toLowerCase() : null;
+        if (inputType === "hidden") {
+          return false;
+        }
+        if (element.hasAttribute("hidden") || element.getAttribute("aria-hidden") === "true") {
+          return false;
+        }
+        const style = window.getComputedStyle(element);
+        if (style.display === "none" || style.visibility === "hidden" || Number(style.opacity) === 0) {
+          return false;
+        }
+        const rect = element.getBoundingClientRect();
+        return rect.width > 0 && rect.height > 0;
+      };
+      const readLabel = (element) => {
+        if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement) {
+          const fromLabels = element.labels && element.labels.length > 0 ? element.labels[0]?.textContent?.trim() : null;
+          if (fromLabels) {
+            return fromLabels;
+          }
+        }
+        return element.getAttribute("aria-label")?.trim() ?? null;
+      };
+      const readValue = (element) => {
+        if (element instanceof HTMLSelectElement) {
+          if (element.multiple) {
+            return {
+              value: Array.from(element.selectedOptions).map((option) => option.value),
+              checked: null,
+              type: "select-multiple"
+            };
+          }
+          return {
+            value: element.value,
+            checked: null,
+            type: "select-one"
+          };
+        }
+        if (element instanceof HTMLTextAreaElement) {
+          return {
+            value: element.value,
+            checked: null,
+            type: "textarea"
+          };
+        }
+        if (element instanceof HTMLInputElement) {
+          const inputType = element.type.toLowerCase();
+          if (inputType === "checkbox" || inputType === "radio") {
+            return {
+              value: element.checked ? element.value || "on" : null,
+              checked: element.checked,
+              type: inputType
+            };
+          }
+          if (inputType === "file") {
+            return {
+              value: element.files ? Array.from(element.files).map((file) => file.name) : [],
+              checked: null,
+              type: inputType
+            };
+          }
+          return {
+            value: element.value,
+            checked: null,
+            type: inputType || null
+          };
+        }
+        return {
+          value: null,
+          checked: null,
+          type: null
+        };
+      };
+      return elements.filter((element) => isVisible(element)).map((element) => {
+        const { value, checked, type } = readValue(element);
+        return {
+          tagName: element.tagName.toLowerCase(),
+          type,
+          name: element.getAttribute("name"),
+          id: element.getAttribute("id"),
+          label: readLabel(element),
+          placeholder: element.getAttribute("placeholder"),
+          value,
+          checked,
+          disabled: element.disabled,
+          required: element.required
+        };
+      });
+    });
+    const regexes = redactionRegexes({ redact: ctx.redact, config: ctx.config });
+    let redactedCount = 0;
+    const fields = rawFields.map((field) => {
+      const redacted = fieldNeedsRedaction(field, regexes);
+      if (redacted) {
+        redactedCount += 1;
+      }
+      return {
+        ...field,
+        redacted,
+        value: redacted ? redactValue(field.value) : field.value
+      };
+    });
+    const data = {
+      fieldCount: fields.length,
+      redactedCount,
+      fields
+    };
+    const outputPath = import_node_path6.default.join(ctx.checkpointDir, "form-state.json");
+    await import_promises6.default.writeFile(outputPath, `${JSON.stringify(data, null, 2)}
+`, "utf8");
+    return {
+      data,
+      artifacts: [
+        {
+          name: "form-state",
+          path: outputPath,
+          contentType: "application/json"
+        }
+      ],
+      summary: {
+        fieldCount: data.fieldCount,
+        redactedCount: data.redactedCount
+      }
+    };
+  }
+};
+
+// src/collectors/html.ts
+var import_promises7 = __toESM(require("fs/promises"), 1);
+var import_node_path7 = __toESM(require("path"), 1);
+async function readPageContent(page) {
+  try {
+    await settlePage(page);
+    return await page.content();
+  } catch {
+    await page.waitForTimeout(500);
+    await settlePage(page);
+    return await page.content();
+  }
+}
+var htmlCollector = {
+  name: "html",
+  defaultEnabled: true,
+  async collect(ctx) {
+    const htmlPath = import_node_path7.default.join(ctx.checkpointDir, "page.html");
+    const html = await readPageContent(ctx.page);
+    await import_promises7.default.writeFile(htmlPath, html, "utf8");
+    return {
+      data: {
+        contentLength: html.length
+      },
+      artifacts: [
+        {
+          name: "html",
+          path: htmlPath,
+          contentType: "text/html"
+        }
+      ],
+      summary: {
+        htmlPath: "page.html"
+      }
+    };
+  }
+};
+
+// src/collectors/metadata.ts
+var import_promises8 = __toESM(require("fs/promises"), 1);
+var import_node_path8 = __toESM(require("path"), 1);
+function normalizeStructuredData(scriptContents) {
+  const values = [];
+  for (const content of scriptContents) {
+    const value = content?.trim();
+    if (!value) {
+      continue;
+    }
+    try {
+      values.push(JSON.parse(value));
+    } catch {
+      values.push({
+        parseError: "Invalid JSON-LD",
+        raw: value
+      });
+    }
+  }
+  return values;
+}
+var metadataCollector = {
+  name: "metadata",
+  defaultEnabled: true,
+  async collect(ctx) {
+    const metadata = await ctx.page.evaluate(() => {
+      const meta = (selector) => document.querySelector(selector)?.getAttribute("content") ?? null;
+      const canonicalLink = document.querySelector('link[rel="canonical"]');
+      const html = document.documentElement;
+      const structuredDataScripts = Array.from(document.querySelectorAll('script[type="application/ld+json"]')).map((script) => script.textContent ?? null);
+      return {
+        url: location.href,
+        title: document.title,
+        description: meta('meta[name="description"]'),
+        openGraph: {
+          title: meta('meta[property="og:title"]'),
+          description: meta('meta[property="og:description"]'),
+          image: meta('meta[property="og:image"]')
+        },
+        canonicalUrl: canonicalLink?.getAttribute("href") ?? null,
+        lang: html.getAttribute("lang"),
+        viewport: meta('meta[name="viewport"]'),
+        structuredDataScripts
+      };
+    });
+    const normalizedMetadata = {
+      url: metadata.url,
+      title: metadata.title,
+      description: metadata.description,
+      openGraph: metadata.openGraph,
+      canonicalUrl: metadata.canonicalUrl,
+      lang: metadata.lang,
+      viewport: metadata.viewport,
+      structuredData: normalizeStructuredData(metadata.structuredDataScripts)
+    };
+    const outputPath = import_node_path8.default.join(ctx.checkpointDir, "metadata.json");
+    await import_promises8.default.writeFile(outputPath, `${JSON.stringify(normalizedMetadata, null, 2)}
+`, "utf8");
+    return {
+      data: normalizedMetadata,
+      artifacts: [
+        {
+          name: "metadata",
+          path: outputPath,
+          contentType: "application/json"
+        }
+      ],
+      summary: {
+        url: normalizedMetadata.url,
+        title: normalizedMetadata.title,
+        lang: normalizedMetadata.lang
+      }
+    };
+  }
+};
+
+// src/collectors/network.ts
+var import_promises9 = __toESM(require("fs/promises"), 1);
+var import_node_path9 = __toESM(require("path"), 1);
+var networkStates = /* @__PURE__ */ new WeakMap();
+var networkCollector = {
+  name: "network",
+  defaultEnabled: true,
+  async setup({ page }) {
+    if (networkStates.has(page)) {
+      return;
+    }
+    const entries = [];
+    const recordRequestFailure = (request) => {
+      entries.push({
+        kind: "requestfailed",
+        url: request.url(),
+        method: request.method(),
+        status: null,
+        statusText: null,
+        failureText: request.failure()?.errorText ?? null,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    };
+    const recordHttpError = (response) => {
+      if (response.status() < 400) {
+        return;
+      }
+      entries.push({
+        kind: "http-error",
+        url: response.url(),
+        method: response.request().method(),
+        status: response.status(),
+        statusText: response.statusText(),
+        failureText: null,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    };
+    page.on("requestfailed", recordRequestFailure);
+    page.on("response", recordHttpError);
+    networkStates.set(page, {
+      entries,
+      offset: 0,
+      recordRequestFailure,
+      recordHttpError
+    });
+  },
+  async collect(ctx) {
+    const state = networkStates.get(ctx.page);
+    const checkpointEntries = state ? state.entries.slice(state.offset) : [];
+    if (state) {
+      state.offset = state.entries.length;
+    }
+    const outputPath = import_node_path9.default.join(ctx.checkpointDir, "failed-requests.json");
+    await import_promises9.default.writeFile(outputPath, `${JSON.stringify(checkpointEntries, null, 2)}
+`, "utf8");
+    return {
+      data: checkpointEntries,
+      artifacts: [
+        {
+          name: "failed-requests",
+          path: outputPath,
+          contentType: "application/json"
+        }
+      ],
+      summary: {
+        failedRequestCount: checkpointEntries.length
+      }
+    };
+  },
+  async teardown({ page }) {
+    const state = networkStates.get(page);
+    if (!state) {
+      return;
+    }
+    page.off("requestfailed", state.recordRequestFailure);
+    page.off("response", state.recordHttpError);
+    networkStates.delete(page);
+  }
+};
+
+// src/collectors/network-timing.ts
+var import_promises10 = __toESM(require("fs/promises"), 1);
+var import_node_path10 = __toESM(require("path"), 1);
+var timingStates = /* @__PURE__ */ new WeakMap();
+function maybeDuration(start, end) {
+  if (start <= 0 || end <= 0 || end < start) {
+    return null;
+  }
+  return end - start;
+}
+function toNetworkRecord(response, timing) {
+  return {
+    url: response.url,
+    status: response.status,
+    statusText: response.statusText,
+    resourceType: response.resourceType,
+    timestamp: response.timestamp,
+    durationMs: timing ? timing.duration : null,
+    transferSize: timing ? timing.transferSize : null,
+    encodedBodySize: timing ? timing.encodedBodySize : null,
+    decodedBodySize: timing ? timing.decodedBodySize : null,
+    nextHopProtocol: timing ? timing.nextHopProtocol || null : null,
+    timing: {
+      startTimeMs: timing ? timing.startTime : null,
+      redirectMs: timing ? maybeDuration(timing.redirectStart, timing.redirectEnd) : null,
+      dnsMs: timing ? maybeDuration(timing.domainLookupStart, timing.domainLookupEnd) : null,
+      connectMs: timing ? maybeDuration(timing.connectStart, timing.connectEnd) : null,
+      tlsMs: timing ? maybeDuration(timing.secureConnectionStart, timing.connectEnd) : null,
+      requestMs: timing ? maybeDuration(timing.requestStart, timing.responseStart) : null,
+      responseMs: timing ? maybeDuration(timing.responseStart, timing.responseEnd) : null
+    }
+  };
+}
+var networkTimingCollector = {
+  name: "network-timing",
+  defaultEnabled: false,
+  async setup({ page }) {
+    if (timingStates.has(page)) {
+      return;
+    }
+    const responses = [];
+    const recordResponse = (response) => {
+      responses.push({
+        url: response.url(),
+        status: response.status(),
+        statusText: response.statusText(),
+        resourceType: response.request().resourceType(),
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    };
+    page.on("response", recordResponse);
+    timingStates.set(page, {
+      responses,
+      responseOffset: 0,
+      resourceOffsetByUrl: /* @__PURE__ */ new Map(),
+      recordResponse
+    });
+  },
+  async collect(ctx) {
+    const state = timingStates.get(ctx.page);
+    const recentResponses = state ? state.responses.slice(state.responseOffset) : [];
+    if (state) {
+      state.responseOffset = state.responses.length;
+    }
+    const resourceTimings = await ctx.page.evaluate(() => {
+      const entries = performance.getEntriesByType("resource");
+      return entries.map((entry) => ({
+        name: entry.name,
+        duration: entry.duration,
+        transferSize: entry.transferSize,
+        encodedBodySize: entry.encodedBodySize,
+        decodedBodySize: entry.decodedBodySize,
+        nextHopProtocol: entry.nextHopProtocol,
+        startTime: entry.startTime,
+        redirectStart: entry.redirectStart,
+        redirectEnd: entry.redirectEnd,
+        domainLookupStart: entry.domainLookupStart,
+        domainLookupEnd: entry.domainLookupEnd,
+        connectStart: entry.connectStart,
+        connectEnd: entry.connectEnd,
+        secureConnectionStart: entry.secureConnectionStart,
+        requestStart: entry.requestStart,
+        responseStart: entry.responseStart,
+        responseEnd: entry.responseEnd
+      }));
+    });
+    const timingsByUrl = /* @__PURE__ */ new Map();
+    for (const timing of resourceTimings) {
+      const list = timingsByUrl.get(timing.name);
+      if (list) {
+        list.push(timing);
+      } else {
+        timingsByUrl.set(timing.name, [timing]);
+      }
+    }
+    const requests = recentResponses.map((response) => {
+      if (!state) {
+        return toNetworkRecord(response, null);
+      }
+      const list = timingsByUrl.get(response.url) ?? [];
+      const currentOffset = state.resourceOffsetByUrl.get(response.url) ?? 0;
+      const match = list[currentOffset] ?? null;
+      if (match) {
+        state.resourceOffsetByUrl.set(response.url, currentOffset + 1);
+      }
+      return toNetworkRecord(response, match);
+    });
+    const totalBytes = requests.reduce((total, request) => {
+      if (typeof request.transferSize !== "number" || request.transferSize < 0) {
+        return total;
+      }
+      return total + request.transferSize;
+    }, 0);
+    const slowestRequestMs = requests.reduce((slowest, request) => {
+      if (typeof request.durationMs !== "number") {
+        return slowest;
+      }
+      return Math.max(slowest, request.durationMs);
+    }, 0);
+    const data = {
+      requestCount: requests.length,
+      totalBytes,
+      slowestRequestMs,
+      requests
+    };
+    const outputPath = import_node_path10.default.join(ctx.checkpointDir, "network-timing.json");
+    await import_promises10.default.writeFile(outputPath, `${JSON.stringify(data, null, 2)}
+`, "utf8");
+    return {
+      data,
+      artifacts: [
+        {
+          name: "network-timing",
+          path: outputPath,
+          contentType: "application/json"
+        }
+      ],
+      summary: {
+        requestCount: data.requestCount,
+        totalBytes: data.totalBytes,
+        slowestRequestMs: data.slowestRequestMs
+      }
+    };
+  },
+  async teardown({ page }) {
+    const state = timingStates.get(page);
+    if (!state) {
+      return;
+    }
+    page.off("response", state.recordResponse);
+    timingStates.delete(page);
+  }
+};
+
+// src/collectors/screenshot.ts
+var import_node_path11 = __toESM(require("path"), 1);
+var PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+function readPngSize(buffer) {
+  if (buffer.length < 24 || !buffer.subarray(0, 8).equals(PNG_SIGNATURE)) {
+    return null;
+  }
+  if (buffer.toString("ascii", 12, 16) !== "IHDR") {
+    return null;
+  }
+  return {
+    width: buffer.readUInt32BE(16),
+    height: buffer.readUInt32BE(20)
+  };
+}
+var screenshotCollector = {
+  name: "screenshot",
+  defaultEnabled: true,
+  async collect(ctx) {
+    const fullPage = ctx.options.fullPage ?? true;
+    const screenshotPath = import_node_path11.default.join(ctx.checkpointDir, "page.png");
+    const screenshotBuffer = await ctx.page.screenshot({ path: screenshotPath, fullPage });
+    let highlightBounds = null;
+    if (ctx.options.highlightSelector) {
+      highlightBounds = await ctx.page.locator(ctx.options.highlightSelector).boundingBox().catch(() => null);
+    }
+    return {
+      data: {
+        fullPage,
+        highlightBounds,
+        highlightSelector: ctx.options.highlightSelector ?? null,
+        imageSize: Buffer.isBuffer(screenshotBuffer) ? readPngSize(screenshotBuffer) : null
+      },
+      artifacts: [
+        {
+          name: "screenshot",
+          path: screenshotPath,
+          contentType: "image/png"
+        }
+      ],
+      summary: {
+        screenshotPath: "page.png"
+      }
+    };
+  }
+};
+
+// src/collectors/storage.ts
+var import_promises11 = __toESM(require("fs/promises"), 1);
+var import_node_path12 = __toESM(require("path"), 1);
+var REDACTED2 = "[REDACTED]";
+var DEFAULT_REDACT_PATTERNS2 = ["password", "token", "secret", "api[_-]?key", "authorization", "session", "email"];
+var EMAIL_LIKE_REGEX2 = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+function toRegex2(pattern) {
+  const trimmed = pattern.trim();
+  if (!trimmed) {
+    return null;
+  }
+  try {
+    return new RegExp(trimmed, "i");
+  } catch {
+    return null;
+  }
+}
+function buildRedactionRegexes(ctx) {
+  const fromConfig = Array.isArray(ctx.config.redact) ? ctx.config.redact.filter((entry) => typeof entry === "string") : [];
+  return [...DEFAULT_REDACT_PATTERNS2, ...ctx.redact, ...fromConfig].map((pattern) => toRegex2(pattern)).filter((value) => value instanceof RegExp);
+}
+function shouldRedact(identifier, value, regexes) {
+  if (regexes.some((regex) => regex.test(identifier))) {
+    return true;
+  }
+  if (!value) {
+    return false;
+  }
+  if (EMAIL_LIKE_REGEX2.test(value.trim())) {
+    return true;
+  }
+  return regexes.some((regex) => regex.test(value));
+}
+var storageCollector = {
+  name: "storage",
+  defaultEnabled: false,
+  async collect(ctx) {
+    const includeCookieValues = ctx.config.includeCookieValues === true;
+    const includeLocalStorageValues = ctx.config.includeLocalStorageValues === true;
+    const redactValues = ctx.config.redactValues !== false;
+    const regexes = buildRedactionRegexes({ redact: ctx.redact, config: ctx.config });
+    const cookies = await ctx.page.context().cookies();
+    const localStorageEntries = await ctx.page.evaluate(
+      () => Object.keys(localStorage).map((key) => ({
+        key,
+        value: localStorage.getItem(key) ?? ""
+      }))
+    );
+    const normalizedCookies = cookies.map((cookie) => {
+      const rawValue = includeCookieValues ? cookie.value : null;
+      const redacted = redactValues && shouldRedact(cookie.name, rawValue, regexes);
+      return {
+        name: cookie.name,
+        domain: cookie.domain,
+        path: cookie.path,
+        value: rawValue == null ? null : redacted ? REDACTED2 : rawValue,
+        redacted,
+        expires: cookie.expires,
+        httpOnly: cookie.httpOnly,
+        secure: cookie.secure,
+        sameSite: cookie.sameSite
+      };
+    });
+    const normalizedLocalStorage = localStorageEntries.map((entry) => {
+      const rawValue = includeLocalStorageValues ? entry.value : null;
+      const redacted = redactValues && shouldRedact(entry.key, rawValue, regexes);
+      return {
+        key: entry.key,
+        value: rawValue == null ? null : redacted ? REDACTED2 : rawValue,
+        redacted
+      };
+    });
+    const data = {
+      cookieCount: normalizedCookies.length,
+      localStorageKeyCount: normalizedLocalStorage.length,
+      cookies: normalizedCookies,
+      localStorage: normalizedLocalStorage
+    };
+    const outputPath = import_node_path12.default.join(ctx.checkpointDir, "storage-state.json");
+    await import_promises11.default.writeFile(outputPath, `${JSON.stringify(data, null, 2)}
+`, "utf8");
+    return {
+      data,
+      artifacts: [
+        {
+          name: "storage-state",
+          path: outputPath,
+          contentType: "application/json"
+        }
+      ],
+      summary: {
+        cookieCount: data.cookieCount,
+        localStorageKeyCount: data.localStorageKeyCount
+      }
+    };
+  }
+};
+
+// src/collectors/web-vitals.ts
+var import_promises12 = __toESM(require("fs/promises"), 1);
+var import_node_path13 = __toESM(require("path"), 1);
+var initializedPages = /* @__PURE__ */ new WeakSet();
+function rateMetric(value, thresholds) {
+  if (value == null || Number.isNaN(value)) {
+    return "unknown";
+  }
+  if (value <= thresholds.good) {
+    return "good";
+  }
+  if (value <= thresholds.needsImprovement) {
+    return "needs-improvement";
+  }
+  return "poor";
+}
+function metric(value, thresholds) {
+  return {
+    value,
+    rating: rateMetric(value, thresholds)
+  };
+}
+async function captureWebVitals(page) {
+  const raw = await page.evaluate(() => {
+    const globalState = globalThis;
+    const state = globalState.__e2eWebVitals ?? {
+      cls: 0,
+      fcp: null,
+      lcp: null,
+      inp: null
+    };
+    const navigation = performance.getEntriesByType("navigation")[0];
+    return {
+      cls: state.cls,
+      fcp: state.fcp,
+      lcp: state.lcp,
+      inp: state.inp,
+      ttfb: navigation ? navigation.responseStart : null,
+      domContentLoaded: navigation ? navigation.domContentLoadedEventEnd : null,
+      loadEvent: navigation ? navigation.loadEventEnd : null,
+      url: location.href
+    };
+  });
+  return {
+    url: raw.url,
+    capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    cls: metric(raw.cls, { good: 0.1, needsImprovement: 0.25 }),
+    fcpMs: metric(raw.fcp, { good: 1800, needsImprovement: 3e3 }),
+    lcpMs: metric(raw.lcp, { good: 2500, needsImprovement: 4e3 }),
+    inpMs: metric(raw.inp, { good: 200, needsImprovement: 500 }),
+    ttfbMs: metric(raw.ttfb, { good: 800, needsImprovement: 1800 }),
+    domContentLoadedMs: raw.domContentLoaded,
+    loadEventMs: raw.loadEvent
+  };
+}
+var webVitalsCollector = {
+  name: "web-vitals",
+  defaultEnabled: true,
+  async setup({ page }) {
+    if (initializedPages.has(page)) {
+      return;
+    }
+    initializedPages.add(page);
+    await page.addInitScript(() => {
+      const globalState = globalThis;
+      if (!globalState.__e2eWebVitals) {
+        globalState.__e2eWebVitals = {
+          cls: 0,
+          fcp: null,
+          lcp: null,
+          inp: null
+        };
+      }
+      const state = globalState.__e2eWebVitals;
+      try {
+        const paintObserver = new PerformanceObserver((entryList) => {
+          for (const entry of entryList.getEntries()) {
+            if (entry.name === "first-contentful-paint") {
+              state.fcp = entry.startTime;
+            }
+          }
+        });
+        paintObserver.observe({ type: "paint", buffered: true });
+      } catch {
+      }
+      try {
+        const lcpObserver = new PerformanceObserver((entryList) => {
+          const entries = entryList.getEntries();
+          const lastEntry = entries[entries.length - 1];
+          if (lastEntry) {
+            state.lcp = lastEntry.startTime;
+          }
+        });
+        lcpObserver.observe({ type: "largest-contentful-paint", buffered: true });
+        addEventListener("pagehide", () => lcpObserver.disconnect(), { once: true });
+      } catch {
+      }
+      try {
+        const clsObserver = new PerformanceObserver((entryList) => {
+          for (const entry of entryList.getEntries()) {
+            if (!entry.hadRecentInput) {
+              state.cls += entry.value ?? 0;
+            }
+          }
+        });
+        clsObserver.observe({ type: "layout-shift", buffered: true });
+        addEventListener("pagehide", () => clsObserver.disconnect(), { once: true });
+      } catch {
+      }
+      try {
+        const inpObserver = new PerformanceObserver((entryList) => {
+          for (const entry of entryList.getEntries()) {
+            const duration = entry.duration ?? 0;
+            if (state.inp == null || duration > state.inp) {
+              state.inp = duration;
+            }
+          }
+        });
+        inpObserver.observe({ type: "event", buffered: true, durationThreshold: 40 });
+        addEventListener("pagehide", () => inpObserver.disconnect(), { once: true });
+      } catch {
+      }
+    });
+  },
+  async collect(ctx) {
+    const snapshot = await captureWebVitals(ctx.page);
+    const outputPath = import_node_path13.default.join(ctx.checkpointDir, "web-vitals.json");
+    await import_promises12.default.writeFile(outputPath, `${JSON.stringify(snapshot, null, 2)}
+`, "utf8");
+    return {
+      data: snapshot,
+      artifacts: [
+        {
+          name: "web-vitals",
+          path: outputPath,
+          contentType: "application/json"
+        }
+      ],
+      summary: {
+        cls: snapshot.cls,
+        fcp: snapshot.fcpMs,
+        lcp: snapshot.lcpMs,
+        inp: snapshot.inpMs,
+        ttfb: snapshot.ttfbMs
+      }
+    };
+  },
+  async teardown({ page }) {
+    initializedPages.delete(page);
+  }
+};
+
+// src/collectors/builtin-collectors.ts
+var builtinCollectors = [
+  screenshotCollector,
+  htmlCollector,
+  axeCollector,
+  webVitalsCollector,
+  consoleCollector,
+  networkCollector,
+  metadataCollector,
+  ariaSnapshotCollector,
+  domStatsCollector,
+  formsCollector,
+  storageCollector,
+  networkTimingCollector
+];
+
+// src/collectors/registry.ts
+var builtinCollectors2 = /* @__PURE__ */ new Map();
+var builtinsRegistered = false;
+function registerBuiltinCollector(collector) {
+  builtinCollectors2.set(collector.name, collector);
+}
+function registerBuiltinCollectors(collectors) {
+  if (builtinsRegistered) {
+    return;
+  }
+  for (const collector of collectors) {
+    registerBuiltinCollector(collector);
+  }
+  builtinsRegistered = true;
+}
+
+// src/core.ts
+registerBuiltinCollectors(builtinCollectors);
+function warn(message, error) {
+  if (error instanceof Error) {
+    console.warn(`[playwright-checkpoint] ${message}`, error);
+    return;
+  }
+  if (error !== void 0) {
+    console.warn(`[playwright-checkpoint] ${message}`, String(error));
+    return;
+  }
+  console.warn(`[playwright-checkpoint] ${message}`);
+}
+
+// src/report/markdown-reporter.ts
 function slugify2(value) {
   return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "story";
 }
@@ -677,6 +1900,28 @@ function stripTags(value) {
   const stripped = value.replace(/\s+@[a-z0-9-]+/gi, " ").replace(/\s+/g, " ").trim();
   return stripped || value.trim() || "Untitled story";
 }
+function articleTitle(run) {
+  const override = run.article?.title?.trim();
+  return override || stripTags(run.title);
+}
+function articleDescription(run) {
+  const description = run.article?.description?.trim();
+  return description ? description : null;
+}
+function articleSlug(run) {
+  const override = run.article?.slug?.trim();
+  return slugify2(override || stripTags(run.title));
+}
+function uniqueArticleSlug(baseSlug, usedSlugs) {
+  if (!usedSlugs.has(baseSlug)) {
+    return baseSlug;
+  }
+  let index = 1;
+  while (usedSlugs.has(`${baseSlug}-${index}`)) {
+    index += 1;
+  }
+  return `${baseSlug}-${index}`;
+}
 function normalizeConfig(config) {
   return {
     storiesDir: typeof config.storiesDir === "string" ? config.storiesDir : ".",
@@ -687,7 +1932,8 @@ function normalizeConfig(config) {
     footer: typeof config.footer === "string" ? config.footer : void 0,
     frontmatter: config.frontmatter === true || config.frontmatter === false || config.frontmatter != null && typeof config.frontmatter === "object" && !Array.isArray(config.frontmatter) ? config.frontmatter : false,
     imagePathPrefix: typeof config.imagePathPrefix === "string" ? config.imagePathPrefix : void 0,
-    copyScreenshots: typeof config.copyScreenshots === "boolean" ? config.copyScreenshots : true
+    copyScreenshots: typeof config.copyScreenshots === "boolean" ? config.copyScreenshots : true,
+    requireExplicitStep: typeof config.requireExplicitStep === "boolean" ? config.requireExplicitStep : false
   };
 }
 function normalizeTags(tags) {
@@ -699,6 +1945,9 @@ function shouldIncludeRun(run, config) {
     const runTags = new Set(normalizeTags(run.tags));
     return includeTags.some((tag) => runTags.has(tag));
   }
+  if (run.articles) {
+    return true;
+  }
   return run.checkpoints.some((checkpoint) => {
     const hasDescription = typeof checkpoint.description === "string" && checkpoint.description.trim().length > 0;
     return hasDescription || typeof checkpoint.step === "number";
@@ -723,7 +1972,7 @@ function choosePrimaryRun(runs, preferredProject) {
   })[0] ?? null;
 }
 function resolveArtifactPath2(run, artifactPath) {
-  return import_node_path2.default.isAbsolute(artifactPath) ? artifactPath : import_node_path2.default.resolve(import_node_path2.default.dirname(run.sourceManifestPath), artifactPath);
+  return import_node_path15.default.isAbsolute(artifactPath) ? artifactPath : import_node_path15.default.resolve(import_node_path15.default.dirname(run.sourceManifestPath), artifactPath);
 }
 function screenshotSourcePath(run, checkpoint) {
   const artifacts = checkpoint.collectors.screenshot?.artifacts ?? [];
@@ -767,21 +2016,21 @@ function breadcrumbLabel(url) {
 }
 function autoDescription(checkpoint) {
   const pageTitle = checkpoint.title.trim();
-  const location = urlLabel(checkpoint.url);
+  const location2 = urlLabel(checkpoint.url);
   if (pageTitle) {
-    return `This step captures **${pageTitle}** at \`${location}\`.`;
+    return `This step captures **${pageTitle}** at \`${location2}\`.`;
   }
-  return `This step captures **${checkpoint.name}** at \`${location}\`.`;
+  return `This step captures **${checkpoint.name}** at \`${location2}\`.`;
 }
 function markdownRelativePath(fromFile, toFile) {
-  const relativePath = import_node_path2.default.relative(import_node_path2.default.dirname(fromFile), toFile).split(import_node_path2.default.sep).join("/");
+  const relativePath = import_node_path15.default.relative(import_node_path15.default.dirname(fromFile), toFile).split(import_node_path15.default.sep).join("/");
   if (relativePath.startsWith(".")) {
     return relativePath;
   }
   return `./${relativePath}`;
 }
 function rewriteImagePath(markdownFile, imageFile, outputDir, prefix) {
-  const relativePath = import_node_path2.default.relative(outputDir, imageFile).split(import_node_path2.default.sep).join("/");
+  const relativePath = import_node_path15.default.relative(outputDir, imageFile).split(import_node_path15.default.sep).join("/");
   if (prefix) {
     return `${prefix.replace(/\/+$/g, "")}/${relativePath.replace(/^\/+/, "")}`;
   }
@@ -817,17 +2066,22 @@ async function materializeScreenshot(args) {
   if (!sourcePath) {
     return null;
   }
-  const extension = import_node_path2.default.extname(sourcePath) || ".png";
-  const targetPath = import_node_path2.default.join(
+  const cachedTargetPath = args.screenshotCopies?.get(sourcePath);
+  if (cachedTargetPath) {
+    return rewriteImagePath(args.markdownFile, cachedTargetPath, args.outputDir, args.config.imagePathPrefix);
+  }
+  const extension = import_node_path15.default.extname(sourcePath) || ".png";
+  const targetPath = import_node_path15.default.join(
     args.outputDir,
     args.config.screenshotsDir ?? "screenshots",
-    args.storySlug,
-    `${String(args.stepOrder).padStart(2, "0")}-${slugify2(args.checkpoint.name)}${extension}`
+    args.screenshotDirSlug,
+    `${args.screenshotFileSlug}${extension}`
   );
   try {
     if (args.config.copyScreenshots !== false) {
-      await import_promises2.default.mkdir(import_node_path2.default.dirname(targetPath), { recursive: true });
-      await import_promises2.default.copyFile(sourcePath, targetPath);
+      await import_promises14.default.mkdir(import_node_path15.default.dirname(targetPath), { recursive: true });
+      await import_promises14.default.copyFile(sourcePath, targetPath);
+      args.screenshotCopies?.set(sourcePath, targetPath);
       args.writtenFiles.add(targetPath);
       return rewriteImagePath(args.markdownFile, targetPath, args.outputDir, args.config.imagePathPrefix);
     }
@@ -847,10 +2101,31 @@ function orderedCheckpoints(checkpoints) {
   });
 }
 async function buildSteps(args) {
-  const checkpoints = orderedCheckpoints(args.run.checkpoints);
+  let checkpoints;
+  if (args.stepNames && args.stepNames.length > 0) {
+    const byName = /* @__PURE__ */ new Map();
+    for (const checkpoint of args.run.checkpoints) {
+      if (byName.has(checkpoint.name)) {
+        warn(`Duplicate checkpoint name "${checkpoint.name}" in "${args.run.title}". Using the latest capture for article generation.`);
+      }
+      byName.set(checkpoint.name, checkpoint);
+    }
+    checkpoints = args.stepNames.map((stepName) => {
+      const checkpoint = byName.get(stepName);
+      if (!checkpoint) {
+        warn(`Markdown article step "${stepName}" was not captured in "${args.run.title}". Skipping step.`);
+        return null;
+      }
+      return checkpoint;
+    }).filter((checkpoint) => checkpoint !== null);
+  } else {
+    checkpoints = orderedCheckpoints(args.run.checkpoints).filter(
+      (checkpoint) => !args.config.requireExplicitStep || typeof checkpoint.step === "number"
+    );
+  }
   const steps = [];
   for (const [index, checkpoint] of checkpoints.entries()) {
-    const order = typeof checkpoint.step === "number" ? checkpoint.step : index + 1;
+    const order = args.stepNames ? index + 1 : typeof checkpoint.step === "number" ? checkpoint.step : index + 1;
     steps.push({
       checkpoint,
       order,
@@ -859,12 +2134,13 @@ async function buildSteps(args) {
       imagePath: await materializeScreenshot({
         run: args.run,
         checkpoint,
-        storySlug: args.storySlug,
-        stepOrder: order,
+        screenshotDirSlug: args.screenshotDirSlug,
+        screenshotFileSlug: args.stepNames ? checkpoint.slug : `${String(order).padStart(2, "0")}-${slugify2(checkpoint.name)}`,
         outputDir: args.outputDir,
         markdownFile: args.markdownFile,
         config: args.config,
-        writtenFiles: args.writtenFiles
+        writtenFiles: args.writtenFiles,
+        screenshotCopies: args.screenshotCopies
       }),
       urlLabel: urlLabel(checkpoint.url),
       breadcrumbLabel: breadcrumbLabel(checkpoint.url),
@@ -875,13 +2151,14 @@ async function buildSteps(args) {
 }
 function renderMarkdown(args) {
   const frontmatterFields = args.config.frontmatter === true || typeof args.config.frontmatter === "object" ? {
-    title: args.title,
     project: args.run.project,
-    testId: args.run.testId,
     tags: args.run.tags,
+    ...args.config.frontmatter && typeof args.config.frontmatter === "object" ? args.config.frontmatter : {},
+    ...args.article?.frontmatter ?? {},
+    testId: args.run.testId,
     startedAt: args.run.startedAt,
     generatedAt: args.generatedAt,
-    ...args.config.frontmatter && typeof args.config.frontmatter === "object" ? args.config.frontmatter : {}
+    title: args.title
   } : null;
   const sections = args.steps.map((step) => {
     const lines = [`## Step ${step.order}: ${step.heading}`, ""];
@@ -901,6 +2178,7 @@ function renderMarkdown(args) {
   const parts = [
     frontmatterFields ? serializeFrontmatter(frontmatterFields) : "",
     `# ${args.title}`,
+    args.description?.trim() ?? "",
     args.config.header ? args.config.header.trim() : "",
     sections,
     args.config.footer ? args.config.footer.trim() : ""
@@ -908,6 +2186,42 @@ function renderMarkdown(args) {
   return `${parts.join("\n\n")}
 `;
 }
+function resolveArticles(run) {
+  const multiArticles = (run.articles ?? []).filter((article) => Array.isArray(article.steps));
+  if (run.articles && multiArticles.length === 0) {
+    warn(`Markdown reporter received an empty articles array for "${run.title}". Falling back to the default single-article output.`);
+  }
+  if (multiArticles.length === 0) {
+    return [
+      {
+        title: articleTitle(run),
+        description: articleDescription(run),
+        slug: articleSlug(run),
+        metadata: run.article,
+        screenshotDirSlug: articleSlug(run)
+      }
+    ];
+  }
+  const usedSlugs = /* @__PURE__ */ new Set();
+  const screenshotDirSlug = slugify2(stripTags(run.title));
+  return multiArticles.map((article, index) => {
+    const fallbackSlug = `${screenshotDirSlug}-${index + 1}`;
+    const baseSlug = slugify2(article.slug?.trim() || fallbackSlug);
+    const uniqueSlug = uniqueArticleSlug(baseSlug, usedSlugs);
+    if (uniqueSlug !== baseSlug) {
+      warn(`Markdown article slug collision for "${article.title ?? run.title}" resolved as "${uniqueSlug}".`);
+    }
+    usedSlugs.add(uniqueSlug);
+    return {
+      title: article.title?.trim() || stripTags(run.title),
+      description: article.description?.trim() || null,
+      slug: uniqueSlug,
+      metadata: article,
+      stepNames: [...article.steps],
+      screenshotDirSlug
+    };
+  });
+}
 var markdownReporter = {
   name: "markdown",
   description: "Generates one Markdown help article per captured story.",
@@ -919,37 +2233,56 @@ var markdownReporter = {
     const stories = groupByStory(context.runs);
     const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
     const writtenFiles = /* @__PURE__ */ new Set();
+    const usedStorySlugs = /* @__PURE__ */ new Set();
+    const screenshotCopies = /* @__PURE__ */ new Map();
     let articleCount = 0;
     for (const [storyTitle, runs] of stories) {
       const primaryRun = choosePrimaryRun(runs, config.preferredProject);
       if (!primaryRun || !shouldIncludeRun(primaryRun, config)) {
         continue;
       }
-      const title = stripTags(storyTitle);
-      const storySlug = slugify2(title);
-      const markdownFile = import_node_path2.default.join(context.outputDir, config.storiesDir ?? ".", `${storySlug}.md`);
-      const steps = await buildSteps({
-        run: primaryRun,
-        storySlug,
-        outputDir: context.outputDir,
-        markdownFile,
-        config,
-        writtenFiles
-      });
-      await import_promises2.default.mkdir(import_node_path2.default.dirname(markdownFile), { recursive: true });
-      await import_promises2.default.writeFile(
-        markdownFile,
-        renderMarkdown({
-          title,
-          steps,
+      for (const article of resolveArticles(primaryRun)) {
+        let storySlug = article.slug;
+        if (usedStorySlugs.has(storySlug)) {
+          let index = 2;
+          while (usedStorySlugs.has(`${article.slug}-${index}`)) {
+            index += 1;
+          }
+          storySlug = `${article.slug}-${index}`;
+          warn(`Markdown article slug collision for "${article.title || storyTitle}" resolved as "${storySlug}".`);
+        }
+        usedStorySlugs.add(storySlug);
+        const markdownFile = import_node_path15.default.join(context.outputDir, config.storiesDir ?? ".", `${storySlug}.md`);
+        const steps = await buildSteps({
           run: primaryRun,
+          stepNames: article.stepNames,
+          screenshotDirSlug: article.screenshotDirSlug,
+          outputDir: context.outputDir,
+          markdownFile,
           config,
-          generatedAt
-        }),
-        "utf8"
-      );
-      writtenFiles.add(markdownFile);
-      articleCount += 1;
+          writtenFiles,
+          screenshotCopies
+        });
+        if (steps.length === 0) {
+          continue;
+        }
+        await import_promises14.default.mkdir(import_node_path15.default.dirname(markdownFile), { recursive: true });
+        await import_promises14.default.writeFile(
+          markdownFile,
+          renderMarkdown({
+            title: article.title,
+            description: article.description,
+            steps,
+            run: primaryRun,
+            article: article.metadata,
+            config,
+            generatedAt
+          }),
+          "utf8"
+        );
+        writtenFiles.add(markdownFile);
+        articleCount += 1;
+      }
     }
     return {
       files: [...writtenFiles],
@@ -959,8 +2292,8 @@ var markdownReporter = {
 };
 
 // src/report/mdx-reporter.ts
-var import_promises3 = __toESM(require("fs/promises"), 1);
-var import_node_path3 = __toESM(require("path"), 1);
+var import_promises15 = __toESM(require("fs/promises"), 1);
+var import_node_path16 = __toESM(require("path"), 1);
 var DEFAULT_PROJECT_ORDER2 = ["desktop-light", "desktop-dark", "mobile-light", "mobile-dark"];
 function slugify3(value) {
   return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "story";
@@ -1026,7 +2359,7 @@ function orderedCheckpoints2(checkpoints) {
   });
 }
 function resolveArtifactPath3(run, artifactPath) {
-  return import_node_path3.default.isAbsolute(artifactPath) ? artifactPath : import_node_path3.default.resolve(import_node_path3.default.dirname(run.sourceManifestPath), artifactPath);
+  return import_node_path16.default.isAbsolute(artifactPath) ? artifactPath : import_node_path16.default.resolve(import_node_path16.default.dirname(run.sourceManifestPath), artifactPath);
 }
 function screenshotSourcePath2(run, checkpoint) {
   const artifacts = checkpoint.collectors.screenshot?.artifacts ?? [];
@@ -1060,21 +2393,21 @@ function urlLabel2(url) {
 }
 function autoDescription2(checkpoint) {
   const pageTitle = checkpoint.title.trim();
-  const location = urlLabel2(checkpoint.url);
+  const location2 = urlLabel2(checkpoint.url);
   if (pageTitle) {
-    return `This step captures **${pageTitle}** at \`${location}\`.`;
+    return `This step captures **${pageTitle}** at \`${location2}\`.`;
   }
-  return `This step captures **${checkpoint.name}** at \`${location}\`.`;
+  return `This step captures **${checkpoint.name}** at \`${location2}\`.`;
 }
 function markdownRelativePath2(fromFile, toFile) {
-  const relativePath = import_node_path3.default.relative(import_node_path3.default.dirname(fromFile), toFile).split(import_node_path3.default.sep).join("/");
+  const relativePath = import_node_path16.default.relative(import_node_path16.default.dirname(fromFile), toFile).split(import_node_path16.default.sep).join("/");
   if (relativePath.startsWith(".")) {
     return relativePath;
   }
   return `./${relativePath}`;
 }
 function rewriteImagePath2(mdxFile, imageFile, outputDir, prefix) {
-  const relativePath = import_node_path3.default.relative(outputDir, imageFile).split(import_node_path3.default.sep).join("/");
+  const relativePath = import_node_path16.default.relative(outputDir, imageFile).split(import_node_path16.default.sep).join("/");
   if (prefix) {
     return `${prefix.replace(/\/+$/g, "")}/${relativePath.replace(/^\/+/, "")}`;
   }
@@ -1149,8 +2482,8 @@ async function materializeScreenshot2(args) {
   if (!sourcePath) {
     return null;
   }
-  const extension = import_node_path3.default.extname(sourcePath) || ".png";
-  const targetPath = import_node_path3.default.join(
+  const extension = import_node_path16.default.extname(sourcePath) || ".png";
+  const targetPath = import_node_path16.default.join(
     args.outputDir,
     args.config.screenshotsDir ?? "screenshots",
     args.storySlug,
@@ -1158,8 +2491,8 @@ async function materializeScreenshot2(args) {
   );
   try {
     if (args.config.copyScreenshots !== false) {
-      await import_promises3.default.mkdir(import_node_path3.default.dirname(targetPath), { recursive: true });
-      await import_promises3.default.copyFile(sourcePath, targetPath);
+      await import_promises15.default.mkdir(import_node_path16.default.dirname(targetPath), { recursive: true });
+      await import_promises15.default.copyFile(sourcePath, targetPath);
       args.writtenFiles.add(targetPath);
       return rewriteImagePath2(args.mdxFile, targetPath, args.outputDir, args.config.imagePathPrefix);
     }
@@ -1289,7 +2622,7 @@ var mdxReporter = {
       }
       const title = stripTags2(storyTitle);
       const storySlug = slugify3(title);
-      const mdxFile = import_node_path3.default.join(context.outputDir, config.storiesDir ?? ".", `${storySlug}.mdx`);
+      const mdxFile = import_node_path16.default.join(context.outputDir, config.storiesDir ?? ".", `${storySlug}.mdx`);
       const steps = await buildSteps2({
         runs,
         primaryRun,
@@ -1299,8 +2632,8 @@ var mdxReporter = {
         config,
         writtenFiles
       });
-      await import_promises3.default.mkdir(import_node_path3.default.dirname(mdxFile), { recursive: true });
-      await import_promises3.default.writeFile(
+      await import_promises15.default.mkdir(import_node_path16.default.dirname(mdxFile), { recursive: true });
+      await import_promises15.default.writeFile(
         mdxFile,
         renderMdx({
           title,
@@ -1329,10 +2662,10 @@ var builtinReporterDefaults = {
   mdx: false
 };
 async function walkFiles(directory) {
-  const dirents = await import_promises4.default.readdir(directory, { withFileTypes: true });
+  const dirents = await import_promises16.default.readdir(directory, { withFileTypes: true });
   const files = [];
   for (const dirent of dirents) {
-    const absolutePath = import_node_path4.default.join(directory, dirent.name);
+    const absolutePath = import_node_path17.default.join(directory, dirent.name);
     if (dirent.isDirectory()) {
       files.push(...await walkFiles(absolutePath));
       continue;
@@ -1344,7 +2677,7 @@ async function walkFiles(directory) {
   return files;
 }
 function isCheckpointManifestFile(filePath) {
-  const fileName = import_node_path4.default.basename(filePath);
+  const fileName = import_node_path17.default.basename(filePath);
   return fileName === "checkpoint-manifest.json" || fileName.startsWith("checkpoint-manifest-") && fileName.endsWith(".json");
 }
 function isCheckpointManifest(value) {
@@ -1362,6 +2695,8 @@ function toRunRecord(manifest, sourceManifestPath) {
     project: manifest.project,
     testId: manifest.testId,
     title: manifest.title,
+    ...manifest.article ? { article: manifest.article } : {},
+    ...manifest.articles ? { articles: manifest.articles } : {},
     tags: manifest.tags,
     startedAt: manifest.startedAt,
     checkpoints: manifest.checkpoints
@@ -1373,6 +2708,8 @@ function toManifest(run) {
     project: run.project,
     testId: run.testId,
     title: run.title,
+    ...run.article ? { article: run.article } : {},
+    ...run.articles ? { articles: run.articles } : {},
     tags: run.tags,
     startedAt: run.startedAt,
     checkpoints: run.checkpoints
@@ -1417,7 +2754,7 @@ async function loadRuns(testResultsDir) {
   for (const manifestPath of manifestFiles) {
     let rawManifest;
     try {
-      rawManifest = JSON.parse(await import_promises4.default.readFile(manifestPath, "utf8"));
+      rawManifest = JSON.parse(await import_promises16.default.readFile(manifestPath, "utf8"));
     } catch {
       continue;
     }
@@ -1638,8 +2975,8 @@ async function runCli(argv = process.argv.slice(2), deps = {}) {
     printHelp(log);
     return 0;
   }
-  const resultsDir = import_node_path5.default.resolve(cwd(), parsed.resultsDir);
-  const outputDir = import_node_path5.default.resolve(cwd(), parsed.outputDir);
+  const resultsDir = import_node_path18.default.resolve(cwd(), parsed.resultsDir);
+  const outputDir = import_node_path18.default.resolve(cwd(), parsed.outputDir);
   try {
     const config = parsed.command === "docs" ? docsConfig(parsed.format, parsed.filterTags) : reporterConfig(parsed.reporters);
     const results = await runReportersImpl(config, resultsDir, outputDir);