@burdenoff/website-sdk 2026.1026.1 → 2026.1028.1

package/README.md

@@ -159,7 +159,9 @@ function Header() {
 |---|---|---|
 | `seo` | – | Renders `PageHead` with these overrides. Omit to manage `<head>` yourself. |
 | `productSlug` | – | The site this page is on. A soft hint to the assistant, not a hard filter. |
-| `examplePrompts` | – | Prompt chips used only when the backend catalog supplies none. |
+| `examplePrompts` | – | Prompt chips used only when the backend catalog supplies none. With `scope="product"` they are the only prompts shown, whatever the catalog has. |
+| `scope` | `'portfolio'` | `'product'` (with `productSlug`) makes the assistant one product's own. See [One product's own assistant](#one-products-own-assistant). |
+| `productName` | catalog name | The product's display name in the `product` scope. Default: the catalog's name for `productSlug`. |
 | `className` | – | Extra classes on the page root. |
 | `heightMode` | `'viewport'` | `viewport` pins the chat to the screen with an internally scrolling transcript, and is the only mode in which the component manages the host page's scroll position; `auto` lets the page grow and never touches its host's scrolling (for embedding). |
 | `viewportOffset` | `0` | Chrome to subtract in `viewport` mode, **before the first measurement only**. A number is pixels; a string is any CSS length (`'4rem'`). Once mounted the pane measures its own top and this value stops being used — so an approximate header height is fine, and the on-screen keyboard is handled for you. |
@@ -167,6 +169,80 @@ function Header() {
 | `onSend` | – | Fired with the message text each time a send is accepted (analytics). |
 | `welcomeTitle` / `welcomeBody` | catalog values | Override the welcome copy. `welcomeTitle` **is** the page `<h1>`. |
 
+#### One product's own assistant
+
+By default the assistant speaks for the whole portfolio: a "Focus on a product"
+picker lists every product, concept cards come from every product, and the
+catalog's copy invites comparing products. A product site that wants its
+assistant to be about that product alone passes `scope="product"` with its
+`productSlug`, on `ExplorePage`, on the site-wide `ExplorePanel`, or on both.
+`ExplorePanel` takes the same `scope`, `productName` and `examplePrompts` props
+and passes them to its chat.
+
+```tsx
+<ExplorePanel
+  open={open}
+  onOpenChange={setOpen}
+  productSlug="healthybowl"
+  scope="product"
+  productName="Healthy Bowl" // the panel is titled "Healthy Bowl assistant"
+  examplePrompts={[
+    "Our herd's health records are spread across three notebooks.",
+    'We only find out a field needs water once the crop is stressed.',
+  ]}
+/>
+```
+
+In that scope:
+
+- The panel's title is "{product} assistant", in the visitor's language and its
+  word order, named from `productName`, else from the catalog. Where a phone
+  leaves it too little room beside the tabs, it wraps to two lines, and the
+  header keeps its height. In English and most locales two lines hold the whole
+  title at 320px and wider; a narrower title box, such as Tamil's at 320px (its
+  tabs are wider), can still end the second line with an ellipsis.
+- There is no product picker. Every question is asked about this product, also
+  in a conversation that was stored, reopened or shared with another focus; the
+  request carries `productSlug` as it always has.
+- Only this product's concept cards show, and none at all when it has none.
+- The example prompts are your `examplePrompts` and nothing else (each once,
+  blank ones dropped), whatever the catalog has. Only when you pass none does it
+  fall back to the catalog's, without any that name another product and without
+  the built-in "Which of your products fits a problem like mine?". Pass your
+  own: the catalog's are written for every site at once, and even the ones that
+  name no product describe other sites' problems. Pass them to the
+  product-scoped view itself (`ExplorePanel` or `ExplorePage`): an
+  `ExploreChatProvider`'s own `examplePrompts` only stand in until the catalog
+  loads.
+- Unless you pass `welcomeBody`, the welcome invites the visitor to describe a
+  problem or ask what the product does, instead of the catalog's invitation to
+  compare products. A catalog title that names another product is replaced by
+  the built-in one. The welcome's "Compare across the ecosystem" tile is left
+  out.
+- The composer is the published one, unchanged: the same layout, the same size
+  and the same fit to its draft. Only its placeholder's text is shorter, "Ask
+  about {product}…" instead of "Describe a problem, or ask about {product}…",
+  because on a phone the field stays one line tall and cuts off a placeholder
+  that wraps. The English one fits that line at 320px and wider. Some longer
+  locales, such as Spanish and Tamil, may still wrap at 320px and narrower; that
+  is left for a follow-up, and HealthyBowl, the site this was made for, is
+  English-only.
+- The page's meta description (and its `og:` and `twitter:` copies) is the
+  product's own, "Answers about {product}, drawn from {product}'s
+  documentation…", never "and every other product we build". The title and
+  `og:site_name` name the product already.
+- A question that needs more searches than one answer can make (`TOOL_BUDGET`)
+  is asked to be narrowed to one part of it, in the visitor's language, instead
+  of to "two or three specific products".
+
+Answers still come from the backend unchanged: when a visitor asks about
+another product, the answer and its sources can mention it. Each view applies
+its own scope, so under an `ExploreChatProvider` a portfolio `/explore` page and
+a product-scoped panel still share one conversation. Without a `productSlug`,
+`scope="product"` has no product to pin to and behaves like the default (a
+development build logs a warning). The default, `scope="portfolio"`, renders
+exactly what it always has.
+
 **`ExploreCta` props**: `variant` (`'header' \| 'mobile' \| 'floating'`, required),
 `href` (default `/explore`), `label` (default `Ask AI`), `className`,
 `onNavigate`, `onClick`, `currentPath`. The `floating` variant hides itself on
@@ -429,6 +505,33 @@ import { cn } from '@burdenoff/website-sdk/utils'
 const className = cn('px-4 py-2', isActive && 'bg-blue-500', 'rounded-lg')
 ```
 
+## Case studies need a customer sign-off
+
+`CaseStudiesListPage` and `CaseStudyPage` render a story only when its CMS page
+(tag `case-study`) carries a `customerSignOff`: the customer's written approval
+of the story and its numbers. global-tenant-svc refuses to serve an unapproved
+case study on the public queries, and the SDK filters again with
+`hasCustomerSignOff`, so no product website can show one. Set the sign-off with
+`updateContentPage(id, { customerSignOff: { signedBy, signedAt, documentRef } })`
+as a super-admin; `null` withdraws it. Public visitors only ever see the
+approval date. Never invent a sign-off or publish a composite story.
+
+## Comparison (/vs) page sources and freshness
+
+`@burdenoff/website-sdk/comparison` gives every website with a /vs page the same
+contract for claims about other vendors:
+
+- `Sourced` / `NonEmptySources`: each claim carries at least one
+  `{ url, verifiedAt }` (ISO date), enforced by the type.
+- `checkComparisonFreshness(claims, { maxAgeDays })` returns an issue for a
+  claim without a source, a non-http(s) URL, a malformed or future date, or a
+  newest verification older than 180 days (default).
+- `formatFreshnessReport(issues)` prints them for CI.
+
+Run it as a PR Check step (see fluidgrids-website `scripts/check-vs-freshness.ts`)
+so a stale comparison blocks the next change until someone re-reads the
+vendor's current page.
+
 ## API Integration
 
 All components that require API integration expect the following endpoints:

package/dist/comparison/index.d.mts

@@ -0,0 +1,83 @@
+/**
+ * @burdenoff/website-sdk - Comparison page sources and freshness (BOFF-9971)
+ *
+ * Every product website with a /vs (competitor comparison) page makes claims
+ * about other vendors. Those claims age fast: a vendor ships the feature we
+ * said it lacked, or changes its prices. This module gives every site the same
+ * contract and the same check:
+ *
+ * - each claim carries at least one source `{ url, verifiedAt }` (enforced by
+ *   the `Sourced` type at compile time), and
+ * - `checkComparisonFreshness` fails when a claim has no source, a source is
+ *   not an http(s) URL, a date is malformed or in the future, or the newest
+ *   verification is older than `maxAgeDays` (180 by default).
+ *
+ * Sites run the check in their PR Check workflow, so a stale or unsourced
+ * comparison blocks the next change until someone re-reads the vendor's page.
+ *
+ * @example
+ * ```ts
+ * import { checkComparisonFreshness, formatFreshnessReport } from '@burdenoff/website-sdk/comparison'
+ *
+ * const issues = checkComparisonFreshness(collectClaims(COMPETITORS))
+ * if (issues.length) {
+ *   console.error(formatFreshnessReport(issues))
+ *   process.exit(1)
+ * }
+ * ```
+ */
+/** Where a comparison claim was checked, and when (ISO date, YYYY-MM-DD). */
+interface ComparisonSource {
+    /** The vendor page (or docs page) the claim was checked against. */
+    url: string;
+    /** The day a person last read that page and confirmed the claim. */
+    verifiedAt: string;
+    /** Optional short label shown with the link, e.g. "Pricing". */
+    label?: string;
+}
+/** A non-empty list: a sourced claim always has at least one source. */
+type NonEmptySources = readonly [
+    ComparisonSource,
+    ...ComparisonSource[]
+];
+/** Mix-in for any comparison claim (table row, profile, pricing row). */
+interface Sourced {
+    sources: NonEmptySources;
+}
+/** One claim to check, located by a human-readable path for the report. */
+interface ComparisonClaim {
+    /** Where the claim lives, e.g. "zapier.featureRows[Workflow versioning]". */
+    path: string;
+    /** Its sources; missing or empty fails the check. */
+    sources?: readonly ComparisonSource[] | null;
+}
+type FreshnessProblem = "missing-source" | "invalid-url" | "invalid-date" | "future-date" | "stale";
+interface FreshnessIssue {
+    path: string;
+    problem: FreshnessProblem;
+    detail: string;
+}
+interface FreshnessOptions {
+    /** Oldest acceptable verification, in days. Default 180. */
+    maxAgeDays?: number;
+    /** The clock to check against. Default: now. */
+    now?: Date;
+}
+/** Default staleness threshold for comparison claims. */
+declare const DEFAULT_COMPARISON_MAX_AGE_DAYS = 180;
+/** Parse a strict YYYY-MM-DD date as UTC midnight, or null when invalid. */
+declare function parseVerifiedAt(value: string): Date | null;
+/**
+ * Check every claim and return the problems found (empty when all is well).
+ * A claim passes on its newest valid source, so adding a fresh source to an
+ * old claim is enough to clear a "stale" issue.
+ */
+declare function checkComparisonFreshness(claims: readonly ComparisonClaim[], options?: FreshnessOptions): FreshnessIssue[];
+/** Newest valid verification date across all claims, or null. */
+declare function latestVerification(claims: readonly ComparisonClaim[]): string | null;
+/** Oldest valid verification date across all claims, or null. */
+declare function oldestVerification(claims: readonly ComparisonClaim[]): string | null;
+/** A plain-text report for CI logs, one line per issue. */
+declare function formatFreshnessReport(issues: readonly FreshnessIssue[]): string;
+
+export { type ComparisonClaim, type ComparisonSource, DEFAULT_COMPARISON_MAX_AGE_DAYS, type FreshnessIssue, type FreshnessOptions, type FreshnessProblem, type NonEmptySources, type Sourced, checkComparisonFreshness, formatFreshnessReport, latestVerification, oldestVerification, parseVerifiedAt };

package/dist/comparison/index.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @burdenoff/website-sdk - Comparison page sources and freshness (BOFF-9971)
+ *
+ * Every product website with a /vs (competitor comparison) page makes claims
+ * about other vendors. Those claims age fast: a vendor ships the feature we
+ * said it lacked, or changes its prices. This module gives every site the same
+ * contract and the same check:
+ *
+ * - each claim carries at least one source `{ url, verifiedAt }` (enforced by
+ *   the `Sourced` type at compile time), and
+ * - `checkComparisonFreshness` fails when a claim has no source, a source is
+ *   not an http(s) URL, a date is malformed or in the future, or the newest
+ *   verification is older than `maxAgeDays` (180 by default).
+ *
+ * Sites run the check in their PR Check workflow, so a stale or unsourced
+ * comparison blocks the next change until someone re-reads the vendor's page.
+ *
+ * @example
+ * ```ts
+ * import { checkComparisonFreshness, formatFreshnessReport } from '@burdenoff/website-sdk/comparison'
+ *
+ * const issues = checkComparisonFreshness(collectClaims(COMPETITORS))
+ * if (issues.length) {
+ *   console.error(formatFreshnessReport(issues))
+ *   process.exit(1)
+ * }
+ * ```
+ */
+/** Where a comparison claim was checked, and when (ISO date, YYYY-MM-DD). */
+interface ComparisonSource {
+    /** The vendor page (or docs page) the claim was checked against. */
+    url: string;
+    /** The day a person last read that page and confirmed the claim. */
+    verifiedAt: string;
+    /** Optional short label shown with the link, e.g. "Pricing". */
+    label?: string;
+}
+/** A non-empty list: a sourced claim always has at least one source. */
+type NonEmptySources = readonly [
+    ComparisonSource,
+    ...ComparisonSource[]
+];
+/** Mix-in for any comparison claim (table row, profile, pricing row). */
+interface Sourced {
+    sources: NonEmptySources;
+}
+/** One claim to check, located by a human-readable path for the report. */
+interface ComparisonClaim {
+    /** Where the claim lives, e.g. "zapier.featureRows[Workflow versioning]". */
+    path: string;
+    /** Its sources; missing or empty fails the check. */
+    sources?: readonly ComparisonSource[] | null;
+}
+type FreshnessProblem = "missing-source" | "invalid-url" | "invalid-date" | "future-date" | "stale";
+interface FreshnessIssue {
+    path: string;
+    problem: FreshnessProblem;
+    detail: string;
+}
+interface FreshnessOptions {
+    /** Oldest acceptable verification, in days. Default 180. */
+    maxAgeDays?: number;
+    /** The clock to check against. Default: now. */
+    now?: Date;
+}
+/** Default staleness threshold for comparison claims. */
+declare const DEFAULT_COMPARISON_MAX_AGE_DAYS = 180;
+/** Parse a strict YYYY-MM-DD date as UTC midnight, or null when invalid. */
+declare function parseVerifiedAt(value: string): Date | null;
+/**
+ * Check every claim and return the problems found (empty when all is well).
+ * A claim passes on its newest valid source, so adding a fresh source to an
+ * old claim is enough to clear a "stale" issue.
+ */
+declare function checkComparisonFreshness(claims: readonly ComparisonClaim[], options?: FreshnessOptions): FreshnessIssue[];
+/** Newest valid verification date across all claims, or null. */
+declare function latestVerification(claims: readonly ComparisonClaim[]): string | null;
+/** Oldest valid verification date across all claims, or null. */
+declare function oldestVerification(claims: readonly ComparisonClaim[]): string | null;
+/** A plain-text report for CI logs, one line per issue. */
+declare function formatFreshnessReport(issues: readonly FreshnessIssue[]): string;
+
+export { type ComparisonClaim, type ComparisonSource, DEFAULT_COMPARISON_MAX_AGE_DAYS, type FreshnessIssue, type FreshnessOptions, type FreshnessProblem, type NonEmptySources, type Sourced, checkComparisonFreshness, formatFreshnessReport, latestVerification, oldestVerification, parseVerifiedAt };

package/dist/comparison/index.js

@@ -0,0 +1,116 @@
+'use strict';
+
+// src/comparison/index.ts
+var DEFAULT_COMPARISON_MAX_AGE_DAYS = 180;
+var DAY_MS = 24 * 60 * 60 * 1e3;
+var ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+function parseVerifiedAt(value) {
+  if (typeof value !== "string" || !ISO_DATE.test(value)) return null;
+  const date = /* @__PURE__ */ new Date(`${value}T00:00:00.000Z`);
+  if (Number.isNaN(date.getTime())) return null;
+  return date.toISOString().slice(0, 10) === value ? date : null;
+}
+function isHttpUrl(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" || url.protocol === "http:";
+  } catch {
+    return false;
+  }
+}
+function checkComparisonFreshness(claims, options = {}) {
+  const maxAgeDays = options.maxAgeDays ?? DEFAULT_COMPARISON_MAX_AGE_DAYS;
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const issues = [];
+  for (const claim of claims) {
+    const sources = claim.sources ?? [];
+    if (sources.length === 0) {
+      issues.push({
+        path: claim.path,
+        problem: "missing-source",
+        detail: "no source: add { url, verifiedAt } for the vendor page this claim was checked against"
+      });
+      continue;
+    }
+    let newest = null;
+    for (const source of sources) {
+      if (!isHttpUrl(source.url)) {
+        issues.push({
+          path: claim.path,
+          problem: "invalid-url",
+          detail: `source URL is not an http(s) URL: ${JSON.stringify(source.url)}`
+        });
+      }
+      const verified = parseVerifiedAt(source.verifiedAt);
+      if (!verified) {
+        issues.push({
+          path: claim.path,
+          problem: "invalid-date",
+          detail: `verifiedAt must be YYYY-MM-DD, got ${JSON.stringify(source.verifiedAt)}`
+        });
+        continue;
+      }
+      if (verified.getTime() > now.getTime() + DAY_MS) {
+        issues.push({
+          path: claim.path,
+          problem: "future-date",
+          detail: `verifiedAt ${source.verifiedAt} is in the future`
+        });
+        continue;
+      }
+      if (!newest || verified.getTime() > newest.getTime()) newest = verified;
+    }
+    if (newest) {
+      const ageDays = Math.floor((now.getTime() - newest.getTime()) / DAY_MS);
+      if (ageDays > maxAgeDays) {
+        issues.push({
+          path: claim.path,
+          problem: "stale",
+          detail: `last verified ${newest.toISOString().slice(0, 10)} (${ageDays} days ago, limit ${maxAgeDays}): re-read the vendor page and update verifiedAt or the claim`
+        });
+      }
+    }
+  }
+  return issues;
+}
+function latestVerification(claims) {
+  let latest = null;
+  for (const claim of claims) {
+    for (const source of claim.sources ?? []) {
+      if (parseVerifiedAt(source.verifiedAt) && (!latest || source.verifiedAt > latest)) {
+        latest = source.verifiedAt;
+      }
+    }
+  }
+  return latest;
+}
+function oldestVerification(claims) {
+  let oldest = null;
+  for (const claim of claims) {
+    for (const source of claim.sources ?? []) {
+      if (parseVerifiedAt(source.verifiedAt) && (!oldest || source.verifiedAt < oldest)) {
+        oldest = source.verifiedAt;
+      }
+    }
+  }
+  return oldest;
+}
+function formatFreshnessReport(issues) {
+  if (issues.length === 0)
+    return "Comparison sources: all claims sourced and fresh.";
+  const lines = issues.map((i) => `  - [${i.problem}] ${i.path}: ${i.detail}`);
+  return [
+    `Comparison sources: ${issues.length} problem(s) found.`,
+    ...lines,
+    "Re-check each claim against the vendor's current page, then update the claim and its verifiedAt."
+  ].join("\n");
+}
+
+exports.DEFAULT_COMPARISON_MAX_AGE_DAYS = DEFAULT_COMPARISON_MAX_AGE_DAYS;
+exports.checkComparisonFreshness = checkComparisonFreshness;
+exports.formatFreshnessReport = formatFreshnessReport;
+exports.latestVerification = latestVerification;
+exports.oldestVerification = oldestVerification;
+exports.parseVerifiedAt = parseVerifiedAt;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/comparison/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/comparison/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @burdenoff/website-sdk - Comparison page sources and freshness (BOFF-9971)\n *\n * Every product website with a /vs (competitor comparison) page makes claims\n * about other vendors. Those claims age fast: a vendor ships the feature we\n * said it lacked, or changes its prices. This module gives every site the same\n * contract and the same check:\n *\n * - each claim carries at least one source `{ url, verifiedAt }` (enforced by\n *   the `Sourced` type at compile time), and\n * - `checkComparisonFreshness` fails when a claim has no source, a source is\n *   not an http(s) URL, a date is malformed or in the future, or the newest\n *   verification is older than `maxAgeDays` (180 by default).\n *\n * Sites run the check in their PR Check workflow, so a stale or unsourced\n * comparison blocks the next change until someone re-reads the vendor's page.\n *\n * @example\n * ```ts\n * import { checkComparisonFreshness, formatFreshnessReport } from '@burdenoff/website-sdk/comparison'\n *\n * const issues = checkComparisonFreshness(collectClaims(COMPETITORS))\n * if (issues.length) {\n *   console.error(formatFreshnessReport(issues))\n *   process.exit(1)\n * }\n * ```\n */\n\n/** Where a comparison claim was checked, and when (ISO date, YYYY-MM-DD). */\nexport interface ComparisonSource {\n  /** The vendor page (or docs page) the claim was checked against. */\n  url: string;\n  /** The day a person last read that page and confirmed the claim. */\n  verifiedAt: string;\n  /** Optional short label shown with the link, e.g. \"Pricing\". */\n  label?: string;\n}\n\n/** A non-empty list: a sourced claim always has at least one source. */\nexport type NonEmptySources = readonly [\n  ComparisonSource,\n  ...ComparisonSource[],\n];\n\n/** Mix-in for any comparison claim (table row, profile, pricing row). */\nexport interface Sourced {\n  sources: NonEmptySources;\n}\n\n/** One claim to check, located by a human-readable path for the report. */\nexport interface ComparisonClaim {\n  /** Where the claim lives, e.g. \"zapier.featureRows[Workflow versioning]\". */\n  path: string;\n  /** Its sources; missing or empty fails the check. */\n  sources?: readonly ComparisonSource[] | null;\n}\n\nexport type FreshnessProblem =\n  \"missing-source\" | \"invalid-url\" | \"invalid-date\" | \"future-date\" | \"stale\";\n\nexport interface FreshnessIssue {\n  path: string;\n  problem: FreshnessProblem;\n  detail: string;\n}\n\nexport interface FreshnessOptions {\n  /** Oldest acceptable verification, in days. Default 180. */\n  maxAgeDays?: number;\n  /** The clock to check against. Default: now. */\n  now?: Date;\n}\n\n/** Default staleness threshold for comparison claims. */\nexport const DEFAULT_COMPARISON_MAX_AGE_DAYS = 180;\n\nconst DAY_MS = 24 * 60 * 60 * 1000;\nconst ISO_DATE = /^\\d{4}-\\d{2}-\\d{2}$/;\n\n/** Parse a strict YYYY-MM-DD date as UTC midnight, or null when invalid. */\nexport function parseVerifiedAt(value: string): Date | null {\n  if (typeof value !== \"string\" || !ISO_DATE.test(value)) return null;\n  const date = new Date(`${value}T00:00:00.000Z`);\n  if (Number.isNaN(date.getTime())) return null;\n  // Reject rollovers such as 2026-02-31 → 2026-03-03.\n  return date.toISOString().slice(0, 10) === value ? date : null;\n}\n\nfunction isHttpUrl(value: string): boolean {\n  try {\n    const url = new URL(value);\n    return url.protocol === \"https:\" || url.protocol === \"http:\";\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Check every claim and return the problems found (empty when all is well).\n * A claim passes on its newest valid source, so adding a fresh source to an\n * old claim is enough to clear a \"stale\" issue.\n */\nexport function checkComparisonFreshness(\n  claims: readonly ComparisonClaim[],\n  options: FreshnessOptions = {},\n): FreshnessIssue[] {\n  const maxAgeDays = options.maxAgeDays ?? DEFAULT_COMPARISON_MAX_AGE_DAYS;\n  const now = options.now ?? new Date();\n  const issues: FreshnessIssue[] = [];\n\n  for (const claim of claims) {\n    const sources = claim.sources ?? [];\n    if (sources.length === 0) {\n      issues.push({\n        path: claim.path,\n        problem: \"missing-source\",\n        detail:\n          \"no source: add { url, verifiedAt } for the vendor page this claim was checked against\",\n      });\n      continue;\n    }\n\n    let newest: Date | null = null;\n    for (const source of sources) {\n      if (!isHttpUrl(source.url)) {\n        issues.push({\n          path: claim.path,\n          problem: \"invalid-url\",\n          detail: `source URL is not an http(s) URL: ${JSON.stringify(source.url)}`,\n        });\n      }\n      const verified = parseVerifiedAt(source.verifiedAt);\n      if (!verified) {\n        issues.push({\n          path: claim.path,\n          problem: \"invalid-date\",\n          detail: `verifiedAt must be YYYY-MM-DD, got ${JSON.stringify(source.verifiedAt)}`,\n        });\n        continue;\n      }\n      if (verified.getTime() > now.getTime() + DAY_MS) {\n        issues.push({\n          path: claim.path,\n          problem: \"future-date\",\n          detail: `verifiedAt ${source.verifiedAt} is in the future`,\n        });\n        continue;\n      }\n      if (!newest || verified.getTime() > newest.getTime()) newest = verified;\n    }\n\n    if (newest) {\n      const ageDays = Math.floor((now.getTime() - newest.getTime()) / DAY_MS);\n      if (ageDays > maxAgeDays) {\n        issues.push({\n          path: claim.path,\n          problem: \"stale\",\n          detail: `last verified ${newest.toISOString().slice(0, 10)} (${ageDays} days ago, limit ${maxAgeDays}): re-read the vendor page and update verifiedAt or the claim`,\n        });\n      }\n    }\n  }\n\n  return issues;\n}\n\n/** Newest valid verification date across all claims, or null. */\nexport function latestVerification(\n  claims: readonly ComparisonClaim[],\n): string | null {\n  let latest: string | null = null;\n  for (const claim of claims) {\n    for (const source of claim.sources ?? []) {\n      if (\n        parseVerifiedAt(source.verifiedAt) &&\n        (!latest || source.verifiedAt > latest)\n      ) {\n        latest = source.verifiedAt;\n      }\n    }\n  }\n  return latest;\n}\n\n/** Oldest valid verification date across all claims, or null. */\nexport function oldestVerification(\n  claims: readonly ComparisonClaim[],\n): string | null {\n  let oldest: string | null = null;\n  for (const claim of claims) {\n    for (const source of claim.sources ?? []) {\n      if (\n        parseVerifiedAt(source.verifiedAt) &&\n        (!oldest || source.verifiedAt < oldest)\n      ) {\n        oldest = source.verifiedAt;\n      }\n    }\n  }\n  return oldest;\n}\n\n/** A plain-text report for CI logs, one line per issue. */\nexport function formatFreshnessReport(\n  issues: readonly FreshnessIssue[],\n): string {\n  if (issues.length === 0)\n    return \"Comparison sources: all claims sourced and fresh.\";\n  const lines = issues.map((i) => `  - [${i.problem}] ${i.path}: ${i.detail}`);\n  return [\n    `Comparison sources: ${issues.length} problem(s) found.`,\n    ...lines,\n    \"Re-check each claim against the vendor's current page, then update the claim and its verifiedAt.\",\n  ].join(\"\\n\");\n}\n"]}

package/dist/comparison/index.mjs

@@ -0,0 +1,109 @@
+// src/comparison/index.ts
+var DEFAULT_COMPARISON_MAX_AGE_DAYS = 180;
+var DAY_MS = 24 * 60 * 60 * 1e3;
+var ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+function parseVerifiedAt(value) {
+  if (typeof value !== "string" || !ISO_DATE.test(value)) return null;
+  const date = /* @__PURE__ */ new Date(`${value}T00:00:00.000Z`);
+  if (Number.isNaN(date.getTime())) return null;
+  return date.toISOString().slice(0, 10) === value ? date : null;
+}
+function isHttpUrl(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" || url.protocol === "http:";
+  } catch {
+    return false;
+  }
+}
+function checkComparisonFreshness(claims, options = {}) {
+  const maxAgeDays = options.maxAgeDays ?? DEFAULT_COMPARISON_MAX_AGE_DAYS;
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const issues = [];
+  for (const claim of claims) {
+    const sources = claim.sources ?? [];
+    if (sources.length === 0) {
+      issues.push({
+        path: claim.path,
+        problem: "missing-source",
+        detail: "no source: add { url, verifiedAt } for the vendor page this claim was checked against"
+      });
+      continue;
+    }
+    let newest = null;
+    for (const source of sources) {
+      if (!isHttpUrl(source.url)) {
+        issues.push({
+          path: claim.path,
+          problem: "invalid-url",
+          detail: `source URL is not an http(s) URL: ${JSON.stringify(source.url)}`
+        });
+      }
+      const verified = parseVerifiedAt(source.verifiedAt);
+      if (!verified) {
+        issues.push({
+          path: claim.path,
+          problem: "invalid-date",
+          detail: `verifiedAt must be YYYY-MM-DD, got ${JSON.stringify(source.verifiedAt)}`
+        });
+        continue;
+      }
+      if (verified.getTime() > now.getTime() + DAY_MS) {
+        issues.push({
+          path: claim.path,
+          problem: "future-date",
+          detail: `verifiedAt ${source.verifiedAt} is in the future`
+        });
+        continue;
+      }
+      if (!newest || verified.getTime() > newest.getTime()) newest = verified;
+    }
+    if (newest) {
+      const ageDays = Math.floor((now.getTime() - newest.getTime()) / DAY_MS);
+      if (ageDays > maxAgeDays) {
+        issues.push({
+          path: claim.path,
+          problem: "stale",
+          detail: `last verified ${newest.toISOString().slice(0, 10)} (${ageDays} days ago, limit ${maxAgeDays}): re-read the vendor page and update verifiedAt or the claim`
+        });
+      }
+    }
+  }
+  return issues;
+}
+function latestVerification(claims) {
+  let latest = null;
+  for (const claim of claims) {
+    for (const source of claim.sources ?? []) {
+      if (parseVerifiedAt(source.verifiedAt) && (!latest || source.verifiedAt > latest)) {
+        latest = source.verifiedAt;
+      }
+    }
+  }
+  return latest;
+}
+function oldestVerification(claims) {
+  let oldest = null;
+  for (const claim of claims) {
+    for (const source of claim.sources ?? []) {
+      if (parseVerifiedAt(source.verifiedAt) && (!oldest || source.verifiedAt < oldest)) {
+        oldest = source.verifiedAt;
+      }
+    }
+  }
+  return oldest;
+}
+function formatFreshnessReport(issues) {
+  if (issues.length === 0)
+    return "Comparison sources: all claims sourced and fresh.";
+  const lines = issues.map((i) => `  - [${i.problem}] ${i.path}: ${i.detail}`);
+  return [
+    `Comparison sources: ${issues.length} problem(s) found.`,
+    ...lines,
+    "Re-check each claim against the vendor's current page, then update the claim and its verifiedAt."
+  ].join("\n");
+}
+
+export { DEFAULT_COMPARISON_MAX_AGE_DAYS, checkComparisonFreshness, formatFreshnessReport, latestVerification, oldestVerification, parseVerifiedAt };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/comparison/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/comparison/index.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * @burdenoff/website-sdk - Comparison page sources and freshness (BOFF-9971)\n *\n * Every product website with a /vs (competitor comparison) page makes claims\n * about other vendors. Those claims age fast: a vendor ships the feature we\n * said it lacked, or changes its prices. This module gives every site the same\n * contract and the same check:\n *\n * - each claim carries at least one source `{ url, verifiedAt }` (enforced by\n *   the `Sourced` type at compile time), and\n * - `checkComparisonFreshness` fails when a claim has no source, a source is\n *   not an http(s) URL, a date is malformed or in the future, or the newest\n *   verification is older than `maxAgeDays` (180 by default).\n *\n * Sites run the check in their PR Check workflow, so a stale or unsourced\n * comparison blocks the next change until someone re-reads the vendor's page.\n *\n * @example\n * ```ts\n * import { checkComparisonFreshness, formatFreshnessReport } from '@burdenoff/website-sdk/comparison'\n *\n * const issues = checkComparisonFreshness(collectClaims(COMPETITORS))\n * if (issues.length) {\n *   console.error(formatFreshnessReport(issues))\n *   process.exit(1)\n * }\n * ```\n */\n\n/** Where a comparison claim was checked, and when (ISO date, YYYY-MM-DD). */\nexport interface ComparisonSource {\n  /** The vendor page (or docs page) the claim was checked against. */\n  url: string;\n  /** The day a person last read that page and confirmed the claim. */\n  verifiedAt: string;\n  /** Optional short label shown with the link, e.g. \"Pricing\". */\n  label?: string;\n}\n\n/** A non-empty list: a sourced claim always has at least one source. */\nexport type NonEmptySources = readonly [\n  ComparisonSource,\n  ...ComparisonSource[],\n];\n\n/** Mix-in for any comparison claim (table row, profile, pricing row). */\nexport interface Sourced {\n  sources: NonEmptySources;\n}\n\n/** One claim to check, located by a human-readable path for the report. */\nexport interface ComparisonClaim {\n  /** Where the claim lives, e.g. \"zapier.featureRows[Workflow versioning]\". */\n  path: string;\n  /** Its sources; missing or empty fails the check. */\n  sources?: readonly ComparisonSource[] | null;\n}\n\nexport type FreshnessProblem =\n  \"missing-source\" | \"invalid-url\" | \"invalid-date\" | \"future-date\" | \"stale\";\n\nexport interface FreshnessIssue {\n  path: string;\n  problem: FreshnessProblem;\n  detail: string;\n}\n\nexport interface FreshnessOptions {\n  /** Oldest acceptable verification, in days. Default 180. */\n  maxAgeDays?: number;\n  /** The clock to check against. Default: now. */\n  now?: Date;\n}\n\n/** Default staleness threshold for comparison claims. */\nexport const DEFAULT_COMPARISON_MAX_AGE_DAYS = 180;\n\nconst DAY_MS = 24 * 60 * 60 * 1000;\nconst ISO_DATE = /^\\d{4}-\\d{2}-\\d{2}$/;\n\n/** Parse a strict YYYY-MM-DD date as UTC midnight, or null when invalid. */\nexport function parseVerifiedAt(value: string): Date | null {\n  if (typeof value !== \"string\" || !ISO_DATE.test(value)) return null;\n  const date = new Date(`${value}T00:00:00.000Z`);\n  if (Number.isNaN(date.getTime())) return null;\n  // Reject rollovers such as 2026-02-31 → 2026-03-03.\n  return date.toISOString().slice(0, 10) === value ? date : null;\n}\n\nfunction isHttpUrl(value: string): boolean {\n  try {\n    const url = new URL(value);\n    return url.protocol === \"https:\" || url.protocol === \"http:\";\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Check every claim and return the problems found (empty when all is well).\n * A claim passes on its newest valid source, so adding a fresh source to an\n * old claim is enough to clear a \"stale\" issue.\n */\nexport function checkComparisonFreshness(\n  claims: readonly ComparisonClaim[],\n  options: FreshnessOptions = {},\n): FreshnessIssue[] {\n  const maxAgeDays = options.maxAgeDays ?? DEFAULT_COMPARISON_MAX_AGE_DAYS;\n  const now = options.now ?? new Date();\n  const issues: FreshnessIssue[] = [];\n\n  for (const claim of claims) {\n    const sources = claim.sources ?? [];\n    if (sources.length === 0) {\n      issues.push({\n        path: claim.path,\n        problem: \"missing-source\",\n        detail:\n          \"no source: add { url, verifiedAt } for the vendor page this claim was checked against\",\n      });\n      continue;\n    }\n\n    let newest: Date | null = null;\n    for (const source of sources) {\n      if (!isHttpUrl(source.url)) {\n        issues.push({\n          path: claim.path,\n          problem: \"invalid-url\",\n          detail: `source URL is not an http(s) URL: ${JSON.stringify(source.url)}`,\n        });\n      }\n      const verified = parseVerifiedAt(source.verifiedAt);\n      if (!verified) {\n        issues.push({\n          path: claim.path,\n          problem: \"invalid-date\",\n          detail: `verifiedAt must be YYYY-MM-DD, got ${JSON.stringify(source.verifiedAt)}`,\n        });\n        continue;\n      }\n      if (verified.getTime() > now.getTime() + DAY_MS) {\n        issues.push({\n          path: claim.path,\n          problem: \"future-date\",\n          detail: `verifiedAt ${source.verifiedAt} is in the future`,\n        });\n        continue;\n      }\n      if (!newest || verified.getTime() > newest.getTime()) newest = verified;\n    }\n\n    if (newest) {\n      const ageDays = Math.floor((now.getTime() - newest.getTime()) / DAY_MS);\n      if (ageDays > maxAgeDays) {\n        issues.push({\n          path: claim.path,\n          problem: \"stale\",\n          detail: `last verified ${newest.toISOString().slice(0, 10)} (${ageDays} days ago, limit ${maxAgeDays}): re-read the vendor page and update verifiedAt or the claim`,\n        });\n      }\n    }\n  }\n\n  return issues;\n}\n\n/** Newest valid verification date across all claims, or null. */\nexport function latestVerification(\n  claims: readonly ComparisonClaim[],\n): string | null {\n  let latest: string | null = null;\n  for (const claim of claims) {\n    for (const source of claim.sources ?? []) {\n      if (\n        parseVerifiedAt(source.verifiedAt) &&\n        (!latest || source.verifiedAt > latest)\n      ) {\n        latest = source.verifiedAt;\n      }\n    }\n  }\n  return latest;\n}\n\n/** Oldest valid verification date across all claims, or null. */\nexport function oldestVerification(\n  claims: readonly ComparisonClaim[],\n): string | null {\n  let oldest: string | null = null;\n  for (const claim of claims) {\n    for (const source of claim.sources ?? []) {\n      if (\n        parseVerifiedAt(source.verifiedAt) &&\n        (!oldest || source.verifiedAt < oldest)\n      ) {\n        oldest = source.verifiedAt;\n      }\n    }\n  }\n  return oldest;\n}\n\n/** A plain-text report for CI logs, one line per issue. */\nexport function formatFreshnessReport(\n  issues: readonly FreshnessIssue[],\n): string {\n  if (issues.length === 0)\n    return \"Comparison sources: all claims sourced and fresh.\";\n  const lines = issues.map((i) => `  - [${i.problem}] ${i.path}: ${i.detail}`);\n  return [\n    `Comparison sources: ${issues.length} problem(s) found.`,\n    ...lines,\n    \"Re-check each claim against the vendor's current page, then update the claim and its verifiedAt.\",\n  ].join(\"\\n\");\n}\n"]}

package/dist/components/explore.d.mts

@@ -1,4 +1,4 @@
 import 'react';
-export { E as EXPLORE_PREFILL_MAX_LENGTH, d as ExplorePage, e as ExplorePageProps, l as ExploreProvenance, m as ExploreReferenceKind, f as answerPlainText, g as answerSpeechText, h as exploreQuestionHref, i as inlineImageOrigins, j as isInlineImageAllowed, k as isInlineVideoAllowed, n as logoUrlOf, o as productNamesByOrigin, r as referenceKindOf, s as summariseReferences } from '../explore-BRfKFfvI.mjs';
+export { a as EXPLORE_PREFILL_MAX_LENGTH, e as ExplorePage, f as ExplorePageProps, m as ExploreProvenance, n as ExploreReferenceKind, g as answerPlainText, h as answerSpeechText, i as exploreQuestionHref, j as inlineImageOrigins, k as isInlineImageAllowed, l as isInlineVideoAllowed, o as logoUrlOf, q as productNamesByOrigin, r as referenceKindOf, s as summariseReferences } from '../explore-BEgq1_0O.mjs';
 import '../explore-types-_9UJu6EA.mjs';
 import 'react-markdown';

package/dist/components/explore.d.ts

@@ -1,4 +1,4 @@
 import 'react';
-export { E as EXPLORE_PREFILL_MAX_LENGTH, d as ExplorePage, e as ExplorePageProps, l as ExploreProvenance, m as ExploreReferenceKind, f as answerPlainText, g as answerSpeechText, h as exploreQuestionHref, i as inlineImageOrigins, j as isInlineImageAllowed, k as isInlineVideoAllowed, n as logoUrlOf, o as productNamesByOrigin, r as referenceKindOf, s as summariseReferences } from '../explore-DkfcKgp6.js';
+export { a as EXPLORE_PREFILL_MAX_LENGTH, e as ExplorePage, f as ExplorePageProps, m as ExploreProvenance, n as ExploreReferenceKind, g as answerPlainText, h as answerSpeechText, i as exploreQuestionHref, j as inlineImageOrigins, k as isInlineImageAllowed, l as isInlineVideoAllowed, o as logoUrlOf, q as productNamesByOrigin, r as referenceKindOf, s as summariseReferences } from '../explore-CHiP9u-4.js';
 import '../explore-types-_9UJu6EA.js';
 import 'react-markdown';