@forkpoint/agent-lighthouse-core 0.2.4 → 0.4.0

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
 });
@@ -4006,6 +4009,175 @@ var NoBotDetectionAudit = class extends Audit {
   }
 };
 
+// src/audits/crawler-permissions/tdm-rep.ts
+var TDMREP_PATH = "/.well-known/tdmrep.json";
+async function getTdmRepFile(ctx) {
+  const cached = ctx.rootFiles[TDMREP_PATH];
+  if (cached) return cached;
+  try {
+    return await ctx.fetch({ url: `${ctx.baseUrl}${TDMREP_PATH}` });
+  } catch {
+    return null;
+  }
+}
+function describeReservation(value) {
+  return value.trim() === "1" ? "rights reserved (mining denied by default)" : "mining explicitly permitted";
+}
+var TdmRepAudit = class extends Audit {
+  static meta = {
+    id: "2.27",
+    category: "crawler-permissions",
+    title: "TDM-Rep data mining rights declared",
+    failureTitle: "TDM-Rep data mining rights declared",
+    description: 'The TDM-Rep (Text and Data Mining Reservation) protocol is the emerging machine-readable standard for declaring whether your content may be used for text and data mining, anchored in EU DSM Directive Article 4. Without an explicit declaration \u2014 either a <meta name="tdm-reservation"> tag or a /.well-known/tdmrep.json policy file \u2014 AI crawlers and licensing agents cannot tell whether you reserve your mining rights, leaving your content in a legal gray zone where well-behaved agents guess and the rest assume permission. Declaring your terms explicitly puts you in control of how AI systems may use your content.',
+    scoreDisplayMode: "ternary",
+    weight: 0.7,
+    defaultPriority: "medium",
+    guidance: {
+      impact: "Without an explicit TDM declaration, AI crawlers and content-licensing agents have no machine-readable signal about your data mining terms. Rights-respecting agents may skip your content to be safe, while others assume permission \u2014 you lose control either way, and you forfeit the EU DSM Article 4 opt-out protection that requires a machine-readable reservation.",
+      fix: 'Declare your text and data mining policy explicitly. Add <meta name="tdm-reservation" content="1"> to reserve mining rights (or "0" to permit mining) on every page, and optionally point to a full policy with <meta name="tdm-policy" content="https://yoursite.com/tdm-policy">. For a site-wide declaration, publish a JSON policy at /.well-known/tdmrep.json instead.',
+      code: '<!-- Reserve mining rights on every page -->\n<meta name="tdm-reservation" content="1" />\n<meta name="tdm-policy" content="https://yoursite.com/tdm-policy" />\n\n<!-- Or site-wide at /.well-known/tdmrep.json -->\n{\n  "tdm-reservation": 1,\n  "tdm-policy": "https://yoursite.com/tdm-policy"\n}',
+      effort: "trivial",
+      docsUrl: "https://www.w3.org/community/reports/tdmrep/CG-FINAL-tdmrep-20240510/",
+      tags: ["tdm-rep", "licensing", "crawler-permissions", "compliance"]
+    }
+  };
+  async audit(ctx) {
+    const pageUrl = ctx.pages[0]?.url;
+    for (const page of ctx.pages) {
+      const reservation = page.meta["tdm-reservation"];
+      if (reservation !== void 0) {
+        const policy = page.meta["tdm-policy"];
+        const policyNote = policy ? ` Policy URL: ${policy}.` : "";
+        return this.pass(
+          `Explicit TDM-Rep declaration found on ${page.url}: tdm-reservation="${reservation.trim()}" (${describeReservation(reservation)}).${policyNote}`,
+          "Explicit TDM reservation via meta tag or /.well-known/tdmrep.json",
+          `meta tdm-reservation="${reservation.trim()}"`,
+          page.url
+        );
+      }
+    }
+    const file = await getTdmRepFile(ctx);
+    if (file && file.status === 200) {
+      try {
+        const policy = JSON.parse(file.body);
+        const reservation = policy["tdm-reservation"];
+        const reservationNote = reservation !== void 0 ? ` tdm-reservation=${String(reservation)} (${describeReservation(String(reservation))}).` : "";
+        return this.pass(
+          `TDM-Rep policy file found at ${TDMREP_PATH}.${reservationNote}`,
+          "Explicit TDM reservation via meta tag or /.well-known/tdmrep.json",
+          `Valid JSON policy at ${TDMREP_PATH}`,
+          pageUrl
+        );
+      } catch {
+        return this.warn(
+          `A file exists at ${TDMREP_PATH} but is not valid JSON, so agents cannot parse your data mining policy.`,
+          "Valid JSON policy at /.well-known/tdmrep.json",
+          "Malformed tdmrep.json",
+          "medium",
+          pageUrl
+        );
+      }
+    }
+    const detail = file && file.status !== 200 && file.status !== 0 ? ` (${TDMREP_PATH} returned HTTP ${file.status})` : "";
+    return this.warn(
+      `No TDM-Rep declaration found. No <meta name="tdm-reservation"> tag on any page and no policy file at ${TDMREP_PATH}${detail}. Your site has not declared its text and data mining terms, so AI crawlers cannot tell whether you reserve your mining rights.`,
+      "Explicit TDM reservation via meta tag or /.well-known/tdmrep.json",
+      "No TDM-Rep declaration found",
+      "medium",
+      pageUrl
+    );
+  }
+};
+
+// src/audits/crawler-permissions/agent-governance.ts
+function explicitlyNamed(groups, bots) {
+  const agents = new Set(groups.map((g) => g.userAgent.toLowerCase()));
+  return bots.filter((bot) => {
+    const names = [bot.botName, ...bot.aliases ?? []];
+    return names.some((name) => agents.has(name.toLowerCase()));
+  });
+}
+function categoryBlocked(groups, bots) {
+  const names = new Set(
+    bots.flatMap(
+      (bot) => [bot.botName, ...bot.aliases ?? []].map((n) => n.toLowerCase())
+    )
+  );
+  const rules = groups.filter((g) => names.has(g.userAgent.toLowerCase())).flatMap((g) => g.rules);
+  return isBlanketBlocked(rules);
+}
+var AgentGovernanceAudit = class extends Audit {
+  static meta = {
+    id: "2.28",
+    category: "crawler-permissions",
+    title: "AI crawler vs conversational agent separation",
+    failureTitle: "No separation between training crawlers and live agents",
+    description: "Not all AI bots are the same. Training crawlers like GPTBot, CCBot, and Google-Extended scrape your content to build datasets, while conversational and retrieval agents like ChatGPT-User, Claude-User, and OAI-SearchBot fetch pages live to answer real user questions and can send referral traffic back to you. Many sites want to block the former while welcoming the latter \u2014 but a single catch-all User-agent: * cannot express that distinction. Granular robots.txt governance names both categories explicitly so each gets the access policy you actually intend.",
+    scoreDisplayMode: "ternary",
+    weight: 0.8,
+    defaultPriority: "medium",
+    guidance: {
+      impact: "Without separate rules for training crawlers and live conversational agents, you cannot block dataset scraping while still appearing in ChatGPT, Claude, and Perplexity answers. A blanket policy either locks you out of AI-powered discovery entirely or leaves your content open to bulk training crawls you never agreed to.",
+      fix: "Add explicit User-agent groups in robots.txt for both categories: name training crawlers (GPTBot, CCBot, Google-Extended, anthropic-ai) with the policy you want, and separately name live agents (ChatGPT-User, Claude-User, OAI-SearchBot) \u2014 typically with Allow: / so your site stays visible in AI answers.",
+      code: "# Block dataset-training crawlers\nUser-agent: GPTBot\nDisallow: /\n\nUser-agent: CCBot\nDisallow: /\n\n# Welcome live conversational agents\nUser-agent: ChatGPT-User\nAllow: /\n\nUser-agent: Claude-User\nAllow: /\n\nUser-agent: *\nAllow: /",
+      effort: "easy",
+      docsUrl: "https://platform.openai.com/docs/bots",
+      tags: ["robots-txt", "crawler-permissions", "ai-governance"]
+    }
+  };
+  audit(ctx) {
+    const robotsFile = ctx.rootFiles["/robots.txt"];
+    if (!robotsFile || robotsFile.status !== 200 || !robotsFile.body) {
+      return this.notApplicable(
+        "No robots.txt found \u2014 agentic governance cannot be evaluated.",
+        "robots.txt with explicit rules for both training crawlers and live conversational agents",
+        "No robots.txt found"
+      );
+    }
+    const groups = parseRobotsTxt(robotsFile.body);
+    const trainingNamed = explicitlyNamed(groups, TRAINING_CRAWLERS);
+    const realtimeNamed = explicitlyNamed(groups, REALTIME_CRAWLERS);
+    const hasCatchAll = groups.some((g) => g.userAgent === "*");
+    const details = {
+      trainingAgents: trainingNamed.map((b) => b.displayName),
+      realtimeAgents: realtimeNamed.map((b) => b.displayName),
+      hasCatchAll
+    };
+    const expected = "Explicit User-agent groups for both training crawlers (GPTBot, CCBot, ...) and live conversational agents (ChatGPT-User, Claude-User, ...)";
+    if (trainingNamed.length === 0 && realtimeNamed.length === 0) {
+      const result2 = this.fail(
+        hasCatchAll ? "robots.txt only defines a catch-all User-agent: * \u2014 no AI-agent-specific rules found." : "robots.txt contains no AI-agent-specific rules.",
+        expected,
+        hasCatchAll ? "Only User-agent: * present" : "No AI crawler user-agents named",
+        { priority: "medium" }
+      );
+      result2.details = details;
+      return result2;
+    }
+    const differentiated = trainingNamed.length > 0 && realtimeNamed.length > 0 && categoryBlocked(groups, trainingNamed) !== categoryBlocked(groups, realtimeNamed);
+    if (trainingNamed.length >= 2 && realtimeNamed.length >= 2 || differentiated) {
+      const result2 = this.pass(
+        `Granular agentic governance: ${trainingNamed.length} training crawler(s) and ${realtimeNamed.length} live agent(s) explicitly named${differentiated ? " with different policies" : ""}.`,
+        expected,
+        `Training: ${trainingNamed.map((b) => b.displayName).join(", ") || "none"}; Realtime: ${realtimeNamed.map((b) => b.displayName).join(", ") || "none"}`
+      );
+      result2.details = details;
+      return result2;
+    }
+    const covered = trainingNamed.length > 0 ? "training crawlers" : "live conversational agents";
+    const missing = trainingNamed.length > 0 ? "live conversational agents" : "training crawlers";
+    const result = this.warn(
+      `Only ${covered} are explicitly governed in robots.txt \u2014 no rules for ${missing}.`,
+      expected,
+      `Training: ${trainingNamed.map((b) => b.displayName).join(", ") || "none"}; Realtime: ${realtimeNamed.map((b) => b.displayName).join(", ") || "none"}`,
+      { priority: "medium" }
+    );
+    result.details = details;
+    return result;
+  }
+};
+
 // src/audits/structured-data/json-ld-present.ts
 var JsonLdPresentAudit = class extends Audit {
   static meta = {
@@ -5945,6 +6117,138 @@ var ProductReviewsAudit = class extends Audit {
   }
 };
 
+// src/audits/structured-data/product-transaction-certainty.ts
+function matchesAnyType11(schema, types) {
+  return types.some((t) => {
+    const st = schema["@type"];
+    if (typeof st === "string") return st === t;
+    if (Array.isArray(st)) return st.includes(t);
+    return false;
+  });
+}
+function asOfferList(offers) {
+  if (!offers) return [];
+  const list = Array.isArray(offers) ? offers : [offers];
+  return list.filter((o) => !!o && typeof o === "object");
+}
+var SIGNAL_LABELS = {
+  availability: "offers.availability",
+  priceValidUntil: "offers.priceValidUntil",
+  pricePair: "offers.price + offers.priceCurrency",
+  returnPolicy: "hasMerchantReturnPolicy"
+};
+var ProductTransactionCertaintyAudit = class extends Audit {
+  static meta = {
+    id: "3.24",
+    category: "structured-data",
+    title: "Product transactional certainty",
+    failureTitle: "Product transactional certainty",
+    description: "AI shopping assistants need more than a product name and price to make an authoritative recommendation: they must know whether the item is in stock, how long the quoted price is valid, and what the return policy is before they commit a user to a purchase. A Product schema that only carries name and price forces agents to guess at availability, quote potentially stale prices, and stay silent on returns \u2014 all of which erode transactional certainty in agentic commerce flows. Complete your Offer with availability, priceValidUntil, and a valid price + priceCurrency pair, and attach hasMerchantReturnPolicy to the Product or Offer.",
+    scoreDisplayMode: "ternary",
+    weight: 1,
+    applicablePageTypes: ["product"],
+    defaultPriority: "high",
+    guidance: {
+      impact: "Without availability, priceValidUntil, a valid price/currency pair, and a return policy in your Product schema, AI shopping assistants cannot make an authoritative recommendation. Agents either skip your product or answer with guessed availability, stale prices, and unknown return terms \u2014 costing you conversions in agent-driven purchases.",
+      fix: "Complete the Offer block in your Product JSON-LD with availability (a schema.org ItemAvailability value), priceValidUntil (ISO date), and a valid price + priceCurrency pair. Add hasMerchantReturnPolicy to the Product or Offer. Also ensure unique identifiers (GTIN/MPN/SKU) are present \u2014 see the Product identifiers audit \u2014 so agents can match the exact item.",
+      code: `{
+  "@context": "https://schema.org",
+  "@type": "Product",
+  "name": "Product Name",
+  "offers": {
+    "@type": "Offer",
+    "price": "99.00",
+    "priceCurrency": "USD",
+    "availability": "https://schema.org/InStock",
+    "priceValidUntil": "2026-12-31",
+    "hasMerchantReturnPolicy": {
+      "@type": "MerchantReturnPolicy",
+      "applicableCountry": "US",
+      "returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
+      "merchantReturnDays": 30
+    }
+  }
+}`,
+      effort: "moderate",
+      docsUrl: "https://schema.org/Offer",
+      tags: ["json-ld", "schema", "product", "ecommerce", "agentic-commerce"]
+    }
+  };
+  audit(ctx) {
+    const schemas = ctx.pages.flatMap((p) => flattenJsonLd(p.structuredData ?? p.jsonLd));
+    const products = schemas.filter(
+      (s) => matchesAnyType11(s, [
+        "Product",
+        "IndividualProduct",
+        "ProductModel"
+      ])
+    );
+    if (products.length === 0) {
+      return this.notApplicable(
+        "No Product schema found on any page to evaluate transactional certainty.",
+        "Product schema with offers containing availability, priceValidUntil, price + priceCurrency, and hasMerchantReturnPolicy.",
+        "None"
+      );
+    }
+    let best = null;
+    for (const product of products) {
+      const obj = product;
+      const offers = asOfferList(obj["offers"]);
+      if (offers.length === 0) continue;
+      const signals = {
+        availability: offers.some((o) => !!o["availability"]),
+        priceValidUntil: offers.some((o) => !!o["priceValidUntil"]),
+        pricePair: offers.some(
+          (o) => o["price"] !== void 0 && o["price"] !== null && o["price"] !== "" && !!o["priceCurrency"]
+        ),
+        returnPolicy: !!obj["hasMerchantReturnPolicy"] || offers.some((o) => !!o["hasMerchantReturnPolicy"])
+      };
+      const count = Object.values(signals).filter(Boolean).length;
+      if (!best || count > best.count) best = { signals, count };
+    }
+    const expected = "Product schema with offers containing availability, priceValidUntil, price + priceCurrency, and hasMerchantReturnPolicy.";
+    if (!best) {
+      return this.fail(
+        "Product schema found but no Offer block \u2014 no transactional data for agents to act on.",
+        expected,
+        "0/4 certainty signals (no offers)",
+        {
+          priority: "high",
+          description: "AI shopping assistants cannot quote a price, check stock, or state return terms without an Offer block. Add offers with price, priceCurrency, availability, priceValidUntil, and hasMerchantReturnPolicy."
+        }
+      );
+    }
+    const missing = Object.keys(best.signals).filter((k) => !best.signals[k]).map((k) => SIGNAL_LABELS[k]);
+    if (best.count === 4) {
+      return this.pass(
+        "All transactional certainty signals present: availability, priceValidUntil, price + priceCurrency, and return policy.",
+        expected,
+        "4/4 certainty signals"
+      );
+    }
+    if (best.count >= 2) {
+      return this.warn(
+        `Missing purchasing data points: ${missing.join(", ")}.`,
+        expected,
+        `${best.count}/4 certainty signals (missing: ${missing.join(", ")})`,
+        {
+          priority: "high",
+          description: `AI shopping assistants are missing ${missing.join(", ")} and cannot give an authoritative recommendation for this product. Complete the Offer block so agents can quote stock, price validity, and return terms with certainty.`
+        }
+      );
+    }
+    return this.fail(
+      `Product relies on name and price alone \u2014 missing: ${missing.join(", ")}.`,
+      expected,
+      `${best.count}/4 certainty signals (missing: ${missing.join(", ")})`,
+      {
+        priority: "high",
+        description: `AI shopping assistants are missing ${missing.join(", ")} and cannot give an authoritative recommendation for this product. Complete the Offer block so agents can quote stock, price validity, and return terms with certainty.`
+      }
+    );
+  }
+};
+
 // src/audits/meta-tags/meta-description.ts
 var MetaDescriptionAudit = class extends Audit {
   static meta = {
@@ -10494,6 +10798,368 @@ var WebmcpActionCoverageAudit = class extends Audit {
   }
 };
 
+// src/audits/agent-tools/openapi-description-quality.ts
+function tryParseJson21(body) {
+  try {
+    return JSON.parse(body);
+  } catch {
+    return void 0;
+  }
+}
+function isObject21(val) {
+  return typeof val === "object" && val !== null && !Array.isArray(val);
+}
+var HTTP_METHODS6 = ["get", "post", "put", "patch", "delete", "options", "head", "trace"];
+var MIN_DESCRIPTION_LENGTH2 = 15;
+function getOpenApiSpec8(ctx) {
+  const jsonResult = ctx.rootFiles["/openapi.json"];
+  if (jsonResult && jsonResult.status === 200 && jsonResult.body) {
+    const parsed = tryParseJson21(jsonResult.body);
+    if (isObject21(parsed)) return parsed;
+  }
+  return void 0;
+}
+function hasGoodDescription(val) {
+  return typeof val === "string" && val.trim().length > MIN_DESCRIPTION_LENGTH2;
+}
+function getCheckableItems(spec) {
+  const paths = spec["paths"];
+  if (!isObject21(paths)) return [];
+  const items = [];
+  for (const [path, pathItem] of Object.entries(paths)) {
+    if (!isObject21(pathItem)) continue;
+    for (const method of HTTP_METHODS6) {
+      const op = pathItem[method];
+      if (!isObject21(op)) continue;
+      const operation = op;
+      const opLabel = `${method.toUpperCase()} ${path}`;
+      items.push({
+        label: `${opLabel} (operation)`,
+        described: hasGoodDescription(operation["description"])
+      });
+      const parameters = operation["parameters"];
+      if (Array.isArray(parameters)) {
+        for (const param of parameters) {
+          if (!isObject21(param)) continue;
+          const name = typeof param["name"] === "string" ? param["name"] : "(unnamed)";
+          items.push({
+            label: `${opLabel} param '${name}'`,
+            described: hasGoodDescription(param["description"])
+          });
+        }
+      }
+    }
+  }
+  return items;
+}
+var OpenApiDescriptionQualityAudit = class _OpenApiDescriptionQualityAudit extends Audit {
+  static meta = {
+    id: "5.26",
+    category: "agent-tools",
+    title: "OpenAPI description quality for tool-calling",
+    failureTitle: "OpenAPI descriptions too thin for tool-calling",
+    description: 'When an AI agent converts your OpenAPI spec into callable tools, the description fields become the prompt the LLM uses to decide when and how to call each function. A one-word description like "search" tells the model nothing about what the endpoint does, what the parameter means, or what values are valid \u2014 so the agent guesses, calls the wrong tool, or fills parameters with hallucinated values. Every operation and every parameter needs a verbose description (more than 15 characters) that explains purpose, expected input, and behavior.',
+    scoreDisplayMode: "ternary",
+    weight: 0.9,
+    defaultPriority: "high",
+    guidance: {
+      impact: "LLM tool-calling treats your OpenAPI descriptions as the function-calling prompt. Missing or terse descriptions force the model to guess what each endpoint does and what each parameter accepts, producing wrong tool selection, malformed arguments, and failed API calls that erode user trust in agent-driven workflows on your site.",
+      fix: "Write a verbose description (>15 characters) for every operation and every parameter in your OpenAPI spec. Explain what the operation does, when an agent should use it, and what each parameter means including format and example values.",
+      code: `"/search": {
+  "get": {
+    "operationId": "searchProducts",
+    "description": "Search the product catalog by keyword. Returns matching products with name, price, and availability. Use this when the user asks to find or browse products.",
+    "parameters": [{
+      "name": "q",
+      "in": "query",
+      "description": "Full-text search query, e.g. 'red running shoes'. Matched against product name and description.",
+      "schema": { "type": "string" }
+    }],
+    "responses": { "200": { "description": "List of matching products" } }
+  }
+}`,
+      effort: "moderate",
+      docsUrl: "https://swagger.io/specification/#operation-object",
+      tags: ["openapi", "descriptions", "tool-calling", "llm", "api"]
+    }
+  };
+  audit(ctx) {
+    const spec = getOpenApiSpec8(ctx);
+    if (!spec) {
+      return this.notApplicable(
+        "No parseable OpenAPI JSON spec found at /openapi.json.",
+        "OpenAPI spec with verbose descriptions on all operations and parameters",
+        "No spec"
+      );
+    }
+    const items = getCheckableItems(spec);
+    if (items.length === 0) {
+      return this.notApplicable(
+        "OpenAPI spec has no operations or parameters to check.",
+        "OpenAPI spec with verbose descriptions on all operations and parameters",
+        "0 checkable items"
+      );
+    }
+    const described = items.filter((i) => i.described).length;
+    const ratio = described / items.length;
+    const missing = items.filter((i) => !i.described).map((i) => i.label);
+    const truncatedMissing = missing.slice(0, 10);
+    const missingSummary = truncatedMissing.join("; ") + (missing.length > 10 ? `; ... and ${missing.length - 10} more` : "");
+    const expected = "Every operation and parameter has a description longer than 15 characters";
+    const found = `${described}/${items.length} described (${Math.round(ratio * 100)}%)`;
+    const details = missing.length > 0 ? { missingDescriptions: truncatedMissing } : void 0;
+    if (ratio >= 0.9) {
+      return {
+        ...this.pass(
+          `${described}/${items.length} operation/parameter description(s) are verbose enough for LLM tool-calling.${missing.length > 0 ? ` Still thin: ${missingSummary}` : ""}`,
+          expected,
+          found
+        ),
+        details
+      };
+    }
+    const recommendation = {
+      priority: "high",
+      description: _OpenApiDescriptionQualityAudit.meta.description,
+      code: _OpenApiDescriptionQualityAudit.meta.guidance?.code
+    };
+    if (ratio >= 0.5) {
+      return {
+        ...this.warn(
+          `Only ${described}/${items.length} operation/parameter description(s) are verbose enough: ${missingSummary}`,
+          expected,
+          found,
+          recommendation
+        ),
+        details
+      };
+    }
+    return {
+      ...this.fail(
+        `Only ${described}/${items.length} operation/parameter description(s) are verbose enough: ${missingSummary}`,
+        expected,
+        found,
+        recommendation
+      ),
+      details
+    };
+  }
+};
+
+// src/audits/agent-tools/form-actionability.ts
+var SKIP_TYPES = ["hidden", "submit", "button", "reset", "image"];
+var IDENTITY_FIELDS = [
+  { pattern: /email/i, token: "email" },
+  { pattern: /(^|[^a-z])(tel|phone|mobile)([^a-z]|$)/i, token: "tel" },
+  { pattern: /first.?name|given.?name|fname/i, token: "given-name" },
+  { pattern: /last.?name|family.?name|surname|lname/i, token: "family-name" },
+  { pattern: /(^|[^a-z])(full.?)?name([^a-z]|$)/i, token: "name" },
+  { pattern: /street|address/i, token: "street-address" },
+  { pattern: /city|town/i, token: "address-level2" },
+  { pattern: /zip|postal|postcode/i, token: "postal-code" },
+  { pattern: /country/i, token: "country-name" }
+];
+var STANDARD_AUTOCOMPLETE_TOKENS = /* @__PURE__ */ new Set([
+  "name",
+  "honorific-prefix",
+  "given-name",
+  "additional-name",
+  "family-name",
+  "honorific-suffix",
+  "nickname",
+  "username",
+  "new-password",
+  "current-password",
+  "one-time-code",
+  "organization-title",
+  "organization",
+  "street-address",
+  "address-line1",
+  "address-line2",
+  "address-line3",
+  "address-level4",
+  "address-level3",
+  "address-level2",
+  "address-level1",
+  "country",
+  "country-name",
+  "postal-code",
+  "cc-name",
+  "cc-given-name",
+  "cc-additional-name",
+  "cc-family-name",
+  "cc-number",
+  "cc-exp",
+  "cc-exp-month",
+  "cc-exp-year",
+  "cc-csc",
+  "cc-type",
+  "transaction-currency",
+  "transaction-amount",
+  "language",
+  "bday",
+  "bday-day",
+  "bday-month",
+  "bday-year",
+  "sex",
+  "url",
+  "photo",
+  "tel",
+  "tel-country-code",
+  "tel-national",
+  "tel-area-code",
+  "tel-local",
+  "tel-local-prefix",
+  "tel-local-suffix",
+  "tel-extension",
+  "email",
+  "impp"
+]);
+var AUTOCOMPLETE_QUALIFIERS = /* @__PURE__ */ new Set(["shipping", "billing", "home", "work", "mobile", "fax", "pager"]);
+function expectedAutocompleteToken(tag, type, name, id, labelText2) {
+  if (tag === "input" && type === "email") return "email";
+  if (tag === "input" && type === "tel") return "tel";
+  const signal = `${name} ${id} ${labelText2}`;
+  for (const { pattern, token } of IDENTITY_FIELDS) {
+    if (pattern.test(signal)) return token;
+  }
+  return void 0;
+}
+function isStandardAutocomplete(value) {
+  const tokens = value.toLowerCase().split(/\s+/).filter((t) => t.length > 0 && !t.startsWith("section-") && !AUTOCOMPLETE_QUALIFIERS.has(t));
+  return tokens.length > 0 && STANDARD_AUTOCOMPLETE_TOKENS.has(tokens[tokens.length - 1]);
+}
+function labelTextFor($, formEl, id) {
+  if (!id) return "";
+  const escapedId = id.replace(/(["\\\]:])/g, "\\$1");
+  const label2 = $(formEl).find(`label[for="${escapedId}"]`).first();
+  return label2.text().trim();
+}
+var FormActionabilityAudit = class extends Audit {
+  static meta = {
+    id: "5.27",
+    category: "agent-tools",
+    title: "Form backend actionability",
+    failureTitle: "Form backend actionability",
+    description: "Autonomous agents fill forms by reading the DOM directly \u2014 they cannot see placeholders rendered visually or guess what a custom div-based widget expects. Fields without a native element, an explicit label (label[for], wrapping label, aria-label, or aria-labelledby), or a standard autocomplete attribute for identity data (email, phone, name, address) force agents to guess, producing failed or incorrect submissions. Keep every fillable field a native input/select/textarea with an explicit label and standard autocomplete tokens.",
+    scoreDisplayMode: "ternary",
+    weight: 1,
+    defaultPriority: "high",
+    guidance: {
+      impact: "AI agents do not render your page visually. Unlabeled fields, div-based fake inputs, and missing autocomplete attributes mean agents cannot tell which field is the email address or the name, so submissions fail silently or land in the wrong fields \u2014 lost leads, broken signups, and abandoned checkouts.",
+      fix: 'Use native input/select/textarea elements (never divs with role="textbox" or contenteditable), associate every field with a <label for="id">, wrapping <label>, aria-label, or aria-labelledby, and add standard autocomplete tokens (email, tel, name, street-address, postal-code, country-name) to identity fields.',
+      code: `<form action="/api/contact" method="POST">
+  <label for="full-name">Full name</label>
+  <input id="full-name" name="name" type="text" autocomplete="name" required />
+
+  <label for="email">Email</label>
+  <input id="email" name="email" type="email" autocomplete="email" required />
+
+  <label for="phone">Phone</label>
+  <input id="phone" name="phone" type="tel" autocomplete="tel" />
+
+  <button type="submit">Send</button>
+</form>`,
+      effort: "easy",
+      docsUrl: "https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill",
+      tags: ["forms", "labels", "autocomplete", "agent-fillable"]
+    }
+  };
+  audit(ctx) {
+    let totalFields = 0;
+    let actionableFields = 0;
+    const issues = [];
+    for (const page of ctx.pages) {
+      const $ = page.$;
+      $("form").each((formIndex, formEl) => {
+        $(formEl).find('[role="textbox"], [contenteditable="true"]').filter((_, el) => !["input", "select", "textarea"].includes(el.tagName?.toLowerCase() ?? "")).each((_, el) => {
+          const name = $(el).attr("name") ?? $(el).attr("id") ?? el.tagName;
+          totalFields++;
+          issues.push({
+            pageUrl: page.url,
+            formIndex,
+            field: `${el.tagName.toLowerCase()}[name="${name}"]`,
+            failedChecks: ["not a native form element (div pretending to be an input)"]
+          });
+        });
+        $(formEl).find("input, select, textarea").each((_, inputEl) => {
+          const $input = $(inputEl);
+          const tag = inputEl.tagName.toLowerCase();
+          const type = ($input.attr("type") ?? (tag === "input" ? "text" : tag)).toLowerCase();
+          if (SKIP_TYPES.includes(type)) return;
+          totalFields++;
+          const failedChecks = [];
+          const name = $input.attr("name") ?? "";
+          const id = $input.attr("id");
+          const escapedId = id ? id.replace(/(["\\\]:])/g, "\\$1") : "";
+          const hasForLabel = escapedId !== "" && $(formEl).find(`label[for="${escapedId}"]`).length > 0;
+          const hasWrappingLabel = $input.closest("label").length > 0;
+          const hasAriaLabel = ($input.attr("aria-label") ?? "").trim().length > 0;
+          const hasAriaLabelledby = ($input.attr("aria-labelledby") ?? "").trim().length > 0;
+          if (!hasForLabel && !hasWrappingLabel && !hasAriaLabel && !hasAriaLabelledby) {
+            failedChecks.push("no explicit label (missing label[for], wrapping label, aria-label, or aria-labelledby)");
+          }
+          const labelText2 = hasForLabel ? labelTextFor($, formEl, id) : $input.closest("label").text().trim();
+          const expectedToken = expectedAutocompleteToken(tag, type, name, id ?? "", labelText2);
+          const autocomplete2 = $input.attr("autocomplete");
+          if (expectedToken && (!autocomplete2 || !isStandardAutocomplete(autocomplete2))) {
+            failedChecks.push(
+              autocomplete2 ? `non-standard autocomplete="${autocomplete2}" (expected token like "${expectedToken}")` : `missing autocomplete (identity field, expected token like "${expectedToken}")`
+            );
+          }
+          if (failedChecks.length === 0) {
+            actionableFields++;
+          } else {
+            issues.push({
+              pageUrl: page.url,
+              formIndex,
+              field: `${tag}[name="${name || "(unnamed)"}" type="${type}"]`,
+              failedChecks
+            });
+          }
+        });
+      });
+    }
+    if (totalFields === 0) {
+      return this.notApplicable(
+        "No forms with fillable fields found on scanned pages \u2014 nothing to check.",
+        "Forms contain native, labeled fields with standard autocomplete attributes",
+        "0 fillable fields"
+      );
+    }
+    const ratio = actionableFields / totalFields;
+    const issueSummary = issues.slice(0, 10).map((i) => `form #${i.formIndex} ${i.field}: ${i.failedChecks.join("; ")}`).join(" | ");
+    const truncated = issues.length > 10 ? ` (and ${issues.length - 10} more)` : "";
+    const foundBase = `${actionableFields}/${totalFields} fields actionable (${Math.round(ratio * 100)}%)`;
+    const found = issues.length > 0 ? `${foundBase}. Non-actionable: ${issueSummary}${truncated}` : foundBase;
+    const firstIssueUrl = issues[0]?.pageUrl;
+    if (ratio >= 0.9) {
+      return this.pass(
+        `${actionableFields}/${totalFields} form fields are fully actionable for agents (native element, labeled, standard autocomplete).`,
+        "At least 90% of form fields are native, labeled, and use standard autocomplete",
+        found,
+        firstIssueUrl
+      );
+    }
+    if (ratio >= 0.5) {
+      return this.warn(
+        `${actionableFields}/${totalFields} form fields are fully actionable \u2014 agents will struggle with the rest.`,
+        "At least 90% of form fields are native, labeled, and use standard autocomplete",
+        found,
+        "high",
+        firstIssueUrl
+      );
+    }
+    return this.fail(
+      `Only ${actionableFields}/${totalFields} form fields are actionable \u2014 agents cannot reliably fill these forms.`,
+      "At least 90% of form fields are native, labeled, and use standard autocomplete",
+      found,
+      "high",
+      firstIssueUrl
+    );
+  }
+};
+
 // src/audits/semantic-html/single-h1.ts
 var SingleH1Audit = class extends Audit {
   static meta = {
@@ -11596,6 +12262,293 @@ var FigureFigcaptionAudit = class extends Audit {
   }
 };
 
+// src/audits/semantic-html/svg-bloat.ts
+var FLAG_THRESHOLD_BYTES = 2048;
+var SINGLE_FAIL_BYTES = 10240;
+var TOTAL_FAIL_BYTES = 20480;
+var TOTAL_WARN_BYTES = 8192;
+var MARKUP_SNIPPET_CHARS = 120;
+function formatBytes(bytes) {
+  return bytes >= 1024 ? `${(bytes / 1024).toFixed(1)}KB` : `${bytes}B`;
+}
+var SvgBloatAudit = class extends Audit {
+  static meta = {
+    id: "6.18",
+    category: "semantic-html",
+    title: "SVGs not bloating agent context",
+    failureTitle: "Large inline SVGs bloating agent context",
+    description: 'When an LLM converts your HTML to Markdown or reads raw markup, every inline SVG is inlined as thousands of path-data tokens. Decorative icon sprites, charts, and complex illustrations can silently consume tens of thousands of tokens of agent context per page \u2014 "SVG context poisoning" \u2014 crowding out the actual content the agent should read. SVGs marked aria-hidden="true" or role="presentation" are stripped by most accessibility-tree extractors and do not count. Keep visible SVGs small, move decorative ones behind aria-hidden, and prefer raster images or CSS for complex graphics.',
+    scoreDisplayMode: "ternary",
+    weight: 0.6,
+    defaultPriority: "medium",
+    guidance: {
+      impact: "Large inline SVGs are inlined verbatim as path-data tokens when an LLM converts your page to Markdown. A single 10KB icon or chart can consume thousands of tokens of agent context per page load, inflating agent cost and pushing real content out of the context window \u2014 reducing the quality of what agents extract and say about your site.",
+      fix: 'Mark decorative SVGs with aria-hidden="true" so agent pipelines strip them. For visible graphics, simplify path data with SVGO, extract complex SVGs to external files referenced via <img>, or replace them with raster images when they exceed a few kilobytes.',
+      code: '<svg aria-hidden="true" focusable="false" ...>...</svg>',
+      effort: "easy",
+      docsUrl: "https://github.com/svg/svgo",
+      tags: ["svg", "context-window", "tokens", "performance"]
+    }
+  };
+  audit(ctx) {
+    let totalCount = 0;
+    let unhiddenCount = 0;
+    let unhiddenBytes = 0;
+    const flagged = [];
+    for (const page of ctx.pages) {
+      page.$("svg").each((_, el) => {
+        totalCount++;
+        const $el = page.$(el);
+        if ($el.attr("aria-hidden") === "true" || $el.attr("role") === "presentation") {
+          return;
+        }
+        unhiddenCount++;
+        const markup = page.$.html(el) ?? "";
+        const bytes = Buffer.byteLength(markup);
+        unhiddenBytes += bytes;
+        if (bytes > FLAG_THRESHOLD_BYTES) {
+          const oneLine = markup.replace(/\s+/g, " ").trim();
+          const snippet = oneLine.length > MARKUP_SNIPPET_CHARS ? `${oneLine.slice(0, MARKUP_SNIPPET_CHARS)}...` : oneLine;
+          flagged.push({ pageUrl: page.url, bytes, snippet });
+        }
+      });
+    }
+    if (totalCount === 0) {
+      return this.notApplicable(
+        "No inline SVG elements found on any page.",
+        "No oversized unhidden inline SVGs.",
+        "No SVGs present"
+      );
+    }
+    const summary = `${totalCount} SVG(s) total, ${unhiddenCount} unhidden, ${formatBytes(unhiddenBytes)} unhidden bytes across ${ctx.pages.length} page(s).`;
+    if (flagged.length === 0 && unhiddenBytes <= TOTAL_WARN_BYTES) {
+      return this.pass(
+        `${summary} All unhidden SVGs are small enough for agent context.`,
+        "Unhidden SVGs stay under 2KB each and under 8KB total.",
+        `${formatBytes(unhiddenBytes)} of unhidden SVG markup`
+      );
+    }
+    flagged.sort((a, b) => b.bytes - a.bytes);
+    const largest = flagged[0];
+    const offenders = flagged.length ? ` Top offenders:
+${flagged.slice(0, 5).map((f) => `${formatBytes(f.bytes)} at ${f.pageUrl}: ${f.snippet}`).join("\n")}` : "";
+    const found = `${summary}${offenders}`;
+    const expected = "Unhidden SVGs stay under 2KB each and under 8KB total; nothing over 10KB per SVG or 20KB total.";
+    if (largest && largest.bytes > SINGLE_FAIL_BYTES || unhiddenBytes > TOTAL_FAIL_BYTES) {
+      const largestNote = largest ? ` \u2014 largest unhidden SVG is ${formatBytes(largest.bytes)}` : "";
+      return this.fail(
+        `${summary} Severe SVG context bloat detected${largestNote}.`,
+        expected,
+        found,
+        {
+          priority: "medium",
+          description: 'Large unhidden inline SVGs are inlined as path-data tokens when an LLM reads your page, consuming thousands of tokens of agent context. Mark decorative SVGs aria-hidden="true", simplify paths with SVGO, or move complex graphics to external files.',
+          code: '<svg aria-hidden="true" focusable="false" ...>...</svg>'
+        }
+      );
+    }
+    const warnReason = flagged.length ? `${flagged.length} unhidden SVG(s) exceed 2KB and may bloat agent context.` : `unhidden SVGs total ${formatBytes(unhiddenBytes)}, bloating agent context.`;
+    return this.warn(
+      `${summary} ${warnReason}`,
+      expected,
+      found,
+      {
+        priority: "medium",
+        description: 'Unhidden inline SVGs over 2KB add meaningful token overhead when an LLM converts your page to Markdown. Mark decorative SVGs aria-hidden="true" or optimize them with SVGO to keep agent context focused on real content.',
+        code: '<svg aria-hidden="true" focusable="false" ...>...</svg>'
+      }
+    );
+  }
+};
+
+// src/audits/semantic-html/token-ratio.ts
+var CHARS_PER_TOKEN = 4;
+var FAIL_RATIO = 0.05;
+var WARN_RATIO = 0.15;
+var TokenRatioAudit = class extends Audit {
+  static meta = {
+    id: "6.19",
+    category: "semantic-html",
+    title: "Lean token-to-content ratio",
+    failureTitle: "Lean token-to-content ratio",
+    description: 'AI agents pay for every token of raw HTML they download, but only the visible text carries meaning. This audit compares the character weight of the raw HTML against the extracted main-content text to produce a "context bloat score": the share of the page that is actual content rather than markup, scripts, and styles. The ratio is evaluated on the homepage (the first crawled page), which is the entry point agents most often fetch. A ratio under 5% means an agent parses 20 tokens of noise for every token of content; under 15% still wastes most of the context window on boilerplate. Unlike content depth (which measures text volume), this measures how efficiently that text is packaged.',
+    scoreDisplayMode: "ternary",
+    weight: 0.8,
+    defaultPriority: "high",
+    guidance: {
+      impact: "When less than 15% of your HTML is actual content, AI agents burn most of their context window and token budget on markup noise: inline scripts, CSS, SVG sprites, tracking tags, and deeply nested divs. The useful text that remains gets weaker attention from the model, and pages with extreme bloat may be truncated before the real content is even read.",
+      fix: "Move inline scripts and styles to external cached files, remove unused framework boilerplate and hidden DOM subtrees, flatten excessive wrapper divs, and serve content in semantic HTML rather than JSON blobs that need client-side hydration. Aim for at least 15% of the raw HTML weight to be visible content text.",
+      code: '<!-- Before: content buried in markup noise -->\n<div class="w1"><div class="w2"><div class="w3">\n  <script>/* 50KB of hydration data */</script>\n  <p>Buy our product</p>\n</div></div></div>\n\n<!-- After: lean, content-first markup -->\n<main>\n  <h1>Our product</h1>\n  <p>Buy our product. It solves your problem by...</p>\n</main>\n<script src="/app.js" defer></script>',
+      effort: "moderate",
+      tags: ["tokens", "performance", "content", "context-window"]
+    }
+  };
+  audit(ctx) {
+    const page = ctx.pages[0];
+    const rawHtml = page?.fetchResult.body ?? "";
+    if (!page || rawHtml.trim().length === 0) {
+      return this.notApplicable(
+        "No HTML body available to measure token-to-content ratio.",
+        "A non-empty HTML body",
+        "Empty body"
+      );
+    }
+    const cleanText = getMainContentText(page.$);
+    const rawChars = rawHtml.length;
+    const contentChars = cleanText.length;
+    const ratio = contentChars / rawChars;
+    const pct = `${(ratio * 100).toFixed(1)}%`;
+    const displayValue = `${pct} content (${Math.round(contentChars / CHARS_PER_TOKEN)} of ${Math.round(rawChars / CHARS_PER_TOKEN)} est. tokens)`;
+    const expected = `At least ${(WARN_RATIO * 100).toFixed(0)}% of the raw HTML weight is visible content text`;
+    if (ratio >= WARN_RATIO) {
+      return {
+        ...this.pass(
+          `Homepage is ${pct} content by character weight \u2014 markup overhead is within a healthy range.`,
+          expected,
+          displayValue,
+          page.url
+        ),
+        displayValue
+      };
+    }
+    if (ratio >= FAIL_RATIO) {
+      return {
+        ...this.warn(
+          `Homepage is only ${pct} content by character weight \u2014 agents spend most of their context on markup noise.`,
+          expected,
+          displayValue,
+          {
+            priority: "high",
+            description: "AI agents pay for every token of raw HTML they download, but only the visible text carries meaning. A content share under 15% means most of the context window is consumed by scripts, styles, and wrapper markup instead of your actual content. Move inline assets to external files, remove unused boilerplate, and flatten markup."
+          },
+          page.url
+        ),
+        displayValue
+      };
+    }
+    return {
+      ...this.fail(
+        `Homepage is only ${pct} content by character weight \u2014 the page is almost entirely markup noise.`,
+        expected,
+        displayValue,
+        {
+          priority: "high",
+          description: "AI agents pay for every token of raw HTML they download, but only the visible text carries meaning. A content share under 5% means an agent parses more than 20 tokens of noise for every token of content, and the page may be truncated before the real content is read. Move inline assets to external files, remove unused boilerplate, and flatten markup."
+        },
+        page.url
+      ),
+      displayValue
+    };
+  }
+};
+
+// src/audits/semantic-html/fake-headings.ts
+var FAKE_HEADING_CLASS = /(text-(xl|2xl|3xl|4xl|5xl)|font-(bold|semibold|extrabold)|heading|headline)/i;
+var MIN_FONT_SIZE_PX = 20;
+var MIN_FONT_WEIGHT = 600;
+var MAX_HEADING_TEXT_LENGTH = 120;
+var BLOCK_CHILDREN = "div, p, section, article, aside, ul, ol, dl, table, figure, blockquote, pre, form";
+var EXCLUDED_ANCESTORS = "nav, footer, button, a";
+function looksLikeHeading(el, $) {
+  const $el = $(el);
+  const tag = el.tagName?.toLowerCase() ?? "";
+  const text = $el.text().replace(/\s+/g, " ").trim();
+  if (text.length === 0 || text.length > MAX_HEADING_TEXT_LENGTH) return null;
+  if ($el.find("h1, h2, h3, h4, h5, h6").length > 0) return null;
+  if ($el.find(BLOCK_CHILDREN).length > 0) return null;
+  if ($el.parents(EXCLUDED_ANCESTORS).length > 0) return null;
+  const className = $el.attr("class") ?? "";
+  const style = $el.attr("style") ?? "";
+  const classHit = FAKE_HEADING_CLASS.test(className);
+  let styleHit = false;
+  if (style) {
+    const sizeMatch = /font-size\s*:\s*(\d+(?:\.\d+)?)px/i.exec(style);
+    if (sizeMatch && parseFloat(sizeMatch[1]) >= MIN_FONT_SIZE_PX) styleHit = true;
+    const weightMatch = /font-weight\s*:\s*(\d+|bold|bolder)/i.exec(style);
+    if (weightMatch) {
+      const w = weightMatch[1].toLowerCase();
+      if (w === "bold" || w === "bolder" || parseInt(w, 10) >= MIN_FONT_WEIGHT) styleHit = true;
+    }
+  }
+  if (!classHit && !styleHit) return null;
+  return {
+    tag,
+    className: className || void 0,
+    style: style || void 0,
+    text
+  };
+}
+var FakeHeadingsAudit = class extends Audit {
+  static meta = {
+    id: "6.20",
+    category: "semantic-html",
+    title: "No fake headings",
+    failureTitle: "Fake headings detected",
+    description: `AI agents chunk and outline page content by reading real <h1>\u2013<h6> tags. When a page styles a <div>, <span>, <p>, or <b> to look like a heading (large text, bold weight, "heading" classes) instead of using a semantic heading element, that text is invisible to the agent's document outline \u2014 sections cannot be navigated, summarized, or cited correctly. This audit is distinct from the sequential-heading check (6.2): 6.2 verifies that real headings appear in the right order, while this audit catches content that impersonates headings without using heading tags at all. Replace styled generic elements with the appropriate <h1>\u2013<h6> level.`,
+    scoreDisplayMode: "ternary",
+    weight: 0.7,
+    defaultPriority: "medium",
+    guidance: {
+      impact: "AI agents build content outlines exclusively from <h1>\u2013<h6> elements. Text that only looks like a heading is treated as ordinary body copy, so agents miss your section structure entirely \u2014 summaries flatten into a wall of text, section-level citations become impossible, and chunking for retrieval splits content at arbitrary points instead of at your intended section boundaries.",
+      fix: "Replace generic elements styled to look like headings with real heading tags. Pick the level that reflects the content's position in the outline (h2 for major sections under the h1, h3 for subsections, and so on), and move the visual styling to CSS targeting those heading elements instead of utility classes on divs and spans.",
+      code: '<!-- Before: looks like a heading, invisible to agents -->\n<div class="text-2xl font-bold">Pricing Plans</div>\n\n<!-- After: semantic and styleable -->\n<h2 class="text-2xl font-bold">Pricing Plans</h2>',
+      effort: "easy",
+      docsUrl: "https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements",
+      tags: ["headings", "semantic", "chunking", "structure"]
+    }
+  };
+  audit(ctx) {
+    const found = [];
+    for (const page of ctx.pages) {
+      const $ = page.$;
+      const flagged = /* @__PURE__ */ new Set();
+      $("div, span, p, b, strong").each((_i, el) => {
+        if ($(el).parents().toArray().some((ancestor) => flagged.has(ancestor))) {
+          return;
+        }
+        const hit = looksLikeHeading(el, $);
+        if (hit) {
+          flagged.add(el);
+          found.push({ url: page.url, heading: hit });
+        }
+      });
+    }
+    const describe = (h) => {
+      const via = h.className ? `class="${h.className}"` : `style="${h.style}"`;
+      const text = h.text.length > 60 ? `${h.text.slice(0, 57)}...` : h.text;
+      return `<${h.tag} ${via}> "${text}"`;
+    };
+    const foundSummary = found.slice(0, 5).map((f) => `${f.url}: ${describe(f.heading)}`).join("; ");
+    const expected = "All heading-like text uses semantic <h1>-<h6> elements";
+    if (found.length === 0) {
+      return this.pass(
+        "No fake headings detected \u2014 heading-like text uses semantic heading elements.",
+        expected,
+        "No styled <div>/<span>/<p>/<b> elements impersonating headings"
+      );
+    }
+    const recommendation = {
+      priority: "medium",
+      description: "AI agents chunk and outline page content by reading real <h1>\u2013<h6> tags. Elements styled to look like headings are invisible to that outline, so sections cannot be navigated, summarized, or cited correctly. Replace styled generic elements with the appropriate heading level.",
+      code: '<!-- Before -->\n<div class="text-2xl font-bold">Pricing Plans</div>\n\n<!-- After -->\n<h2 class="text-2xl font-bold">Pricing Plans</h2>'
+    };
+    if (found.length >= 5) {
+      return this.fail(
+        `Found ${found.length} fake heading(s) \u2014 generic elements styled to look like headings instead of <h1>-<h6> tags.`,
+        expected,
+        foundSummary,
+        recommendation
+      );
+    }
+    return this.warn(
+      `Found ${found.length} fake heading(s) \u2014 generic elements styled to look like headings instead of <h1>-<h6> tags.`,
+      expected,
+      foundSummary,
+      recommendation
+    );
+  }
+};
+
 // src/audits/accessibility/skip-nav.ts
 var SkipNavAudit = class extends Audit {
   static meta = {
@@ -16346,7 +17299,9 @@ var defaultConfig = {
       reg(SensitivePathsAudit),
       reg(CrawlDelayAudit),
       reg(MetaRobotsNotBlockingAudit),
-      reg(NoBotDetectionAudit)
+      reg(NoBotDetectionAudit),
+      reg(TdmRepAudit),
+      reg(AgentGovernanceAudit)
     ],
     "structured-data": [
       reg(JsonLdPresentAudit),
@@ -16367,7 +17322,8 @@ var defaultConfig = {
       reg(ActionSchemaAudit),
       reg(ProductIdentifiersAudit),
       reg(ProductDetailsAudit),
-      reg(ProductReviewsAudit)
+      reg(ProductReviewsAudit),
+      reg(ProductTransactionCertaintyAudit)
     ],
     "meta-tags": [
       reg(MetaDescriptionAudit),
@@ -16416,7 +17372,9 @@ var defaultConfig = {
       reg(WebmcpInputQualityAudit),
       reg(WebmcpToolNamingAudit),
       reg(WebmcpToolAnnotationsAudit),
-      reg(WebmcpActionCoverageAudit)
+      reg(WebmcpActionCoverageAudit),
+      reg(OpenApiDescriptionQualityAudit),
+      reg(FormActionabilityAudit)
     ],
     "semantic-html": [
       reg(SingleH1Audit),
@@ -16435,7 +17393,10 @@ var defaultConfig = {
       reg(ContentDepthAudit),
       reg(ImageAltTextAudit),
       reg(DecorativeImagesAudit),
-      reg(FigureFigcaptionAudit)
+      reg(FigureFigcaptionAudit),
+      reg(SvgBloatAudit),
+      reg(TokenRatioAudit),
+      reg(FakeHeadingsAudit)
     ],
     accessibility: [
       reg(SkipNavAudit),
@@ -16534,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,
@@ -16554,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);
@@ -16625,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");
 
@@ -22136,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;
@@ -22161,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",
@@ -22180,6 +23252,7 @@ async function runScan(url, onProgress, pageOverrides, signal) {
     "/.well-known/ai-plugin.json",
     "/.well-known/webmcp",
     "/.well-known/security.txt",
+    "/.well-known/tdmrep.json",
     "/navigation.json",
     "/privacy-policy/",
     "/privacy/",
@@ -22198,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) : [];
@@ -22219,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($);
@@ -22232,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),
@@ -22249,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 = {
@@ -22263,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) => {
@@ -22292,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
@@ -22322,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;
 }
@@ -22337,7 +23437,7 @@ function calculateReadinessVitals(checks2) {
     return Math.round(matching.reduce((sum, c) => sum + c.score, 0) / matching.length * 100);
   };
   return {
-    commerce: getScore(["3.8", "3.14", "3.21", "3.22", "3.23"]),
+    commerce: getScore(["3.8", "3.14", "3.21", "3.22", "3.23", "3.24"]),
     content: getScore([
       "1.1",
       "1.2",
@@ -22507,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,
@@ -22551,6 +23653,7 @@ function loadConfigFile(customPath) {
   logger,
   normalizeUrl,
   parseHtml,
+  planAudits,
   runAudits,
   runScan
 });