@wildo-ai/saas-website 1.1.5 → 1.1.6

package/src/schemas/__tests__/pricing-offer-structured-data.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from 'vitest';
+import {
+  ProductAvailability,
+  ProductPriceDisclosure,
+  PublicPricingAmountBasis,
+  PublicPricingRecurrenceUnit,
+  type PublicPricingPlan,
+  type PublicPricingPrice,
+} from '@wildo-ai/saas-models/public-runtime';
+
+import { buildWebsitePricingOfferStructuredData } from '../structured-data/pricing-offer-structured-data.shared';
+
+/**
+ * Pins for the pricing page's `AggregateOffer` (#1835). A search engine shows `price` as the price of
+ * the offer, so each refusal pinned here is a case where publishing the catalogue's number would be a
+ * false statement.
+ */
+
+const monthly = (amountMinor: string, overrides: Partial<PublicPricingPrice> = {}): PublicPricingPrice => ({
+  amountMinor,
+  decimals: 2,
+  currency: 'USD',
+  recurrence: { unit: PublicPricingRecurrenceUnit.MONTH, count: 1 },
+  amountBasis: PublicPricingAmountBasis.PER_UNIT,
+  isDefault: true,
+  ...overrides,
+});
+
+const plan = (key: string, overrides: Partial<PublicPricingPlan> = {}): PublicPricingPlan => ({
+  key,
+  sortOrder: 0,
+  targetScopes: ['organizations'],
+  isRecommended: false,
+  priceDisclosure: ProductPriceDisclosure.LISTED,
+  availability: ProductAvailability.AVAILABLE,
+  prices: [monthly('0')],
+  ...overrides,
+});
+
+const build = (plans: PublicPricingPlan[], planName?: (key: string) => string | undefined, perUnitName: string | null = 'member') =>
+  buildWebsitePricingOfferStructuredData({
+    catalog: { plans },
+    itemOfferedId: 'https://example.test/#software-application',
+    aggregateOfferIdPrefix: 'https://example.test/pricing#plans',
+    url: 'https://example.test/pricing',
+    ...(planName === undefined ? {} : { planName }),
+    ...(perUnitName === null ? {} : { perUnitName }),
+  });
+
+type AggregateLike = { '@id': string; lowPrice: string; highPrice: string; offerCount: number; offers: Array<Record<string, unknown>> };
+
+describe('buildWebsitePricingOfferStructuredData', () => {
+  it('publishes a per-unit price with what it is per — never as a whole price', () => {
+    const [aggregate] = build([plan('team', { prices: [monthly('400')] })], (key) => ({ team: 'Team' })[key]) as AggregateLike[];
+    expect(aggregate!.offers[0]).toEqual({
+      '@type': 'Offer',
+      name: 'Team',
+      price: '4',
+      priceCurrency: 'USD',
+      availability: 'https://schema.org/InStock',
+      url: 'https://example.test/pricing#plan-team',
+      priceSpecification: {
+        '@type': 'UnitPriceSpecification',
+        price: '4',
+        priceCurrency: 'USD',
+        billingDuration: 'P1M',
+        referenceQuantity: { '@type': 'QuantitativeValue', value: 1, unitText: 'member' },
+      },
+    });
+  });
+
+  it('refuses to publish a per-unit price when the page did not name the unit', () => {
+    expect(() => build([plan('team', { prices: [monthly('400')] })], undefined, null)).toThrow(/perUnitName/u);
+  });
+
+  it('never folds a flat price and a per-member price, or monthly and yearly prices, into one range', () => {
+    const aggregates = build([
+      plan('free', { prices: [monthly('0', { amountBasis: PublicPricingAmountBasis.FLAT })] }),
+      plan('team', { prices: [monthly('400')] }),
+      plan('company', { prices: [monthly('600')] }),
+      plan('annual', { prices: [monthly('4000', { amountBasis: PublicPricingAmountBasis.FLAT, recurrence: { unit: PublicPricingRecurrenceUnit.YEAR, count: 1 } })] }),
+    ]) as AggregateLike[];
+    expect(aggregates.map((aggregate) => [aggregate['@id'], aggregate.lowPrice, aggregate.highPrice, aggregate.offerCount])).toEqual([
+      ['https://example.test/pricing#plans-flat-1-month-usd', '0', '0', 1],
+      ['https://example.test/pricing#plans-per-unit-1-month-usd', '4', '6', 2],
+      ['https://example.test/pricing#plans-flat-1-year-usd', '40', '40', 1],
+    ]);
+  });
+
+  it("names an aggregate by what it aggregates, so a plan added to ANOTHER group never moves it", () => {
+    const perUnitId = (plans: PublicPricingPlan[]) =>
+      (build(plans) as AggregateLike[]).find((aggregate) => aggregate.offers.some((offer) => offer.url === 'https://example.test/pricing#plan-team'))!['@id'];
+    const team = plan('team', { prices: [monthly('400')] });
+    const free = plan('free', { prices: [monthly('0', { amountBasis: PublicPricingAmountBasis.FLAT })] });
+    expect(perUnitId([team])).toBe('https://example.test/pricing#plans-per-unit-1-month-usd');
+    expect(perUnitId([free, team])).toBe(perUnitId([team]));
+  });
+
+  it.each([
+    ['a starting price (only a floor)', plan('company', { priceDisclosure: ProductPriceDisclosure.STARTING_AT, prices: [monthly('600')] })],
+    ['an on-request plan (no price)', plan('enterprise', { priceDisclosure: ProductPriceDisclosure.ON_REQUEST, prices: [monthly('99900')] })],
+    ['an upcoming plan (cannot be bought)', plan('next', { availability: ProductAvailability.UPCOMING, prices: [monthly('900')] })],
+    ['a tiered price (the amount is indicative)', plan('volume', { prices: [monthly('100', { amountBasis: PublicPricingAmountBasis.VARIABLE })] })],
+  ])('never publishes %s as a price', (_label, excluded) => {
+    const aggregates = build([plan('team', { prices: [monthly('400')] }), excluded]) as AggregateLike[];
+    expect(aggregates.flatMap((aggregate) => aggregate.offers.map((offer) => offer.url))).toEqual(['https://example.test/pricing#plan-team']);
+  });
+
+  it('publishes nothing when nothing may be published — the true statement for an on-request-only catalogue', () => {
+    expect(build([plan('enterprise', { priceDisclosure: ProductPriceDisclosure.ON_REQUEST })])).toEqual([]);
+  });
+
+  it('never blends currencies into one aggregate', () => {
+    const aggregates = build([plan('us', { prices: [monthly('400')] }), plan('eu', { prices: [monthly('500', { currency: 'EUR' })] })]);
+    expect(aggregates.map((aggregate) => aggregate.priceCurrency)).toEqual(['USD', 'EUR']);
+  });
+
+  it('omits a one-time offer\'s billing duration rather than inventing one', () => {
+    const [aggregate] = build([plan('lifetime', { prices: [monthly('9900', { amountBasis: PublicPricingAmountBasis.FLAT, recurrence: { unit: PublicPricingRecurrenceUnit.ONE_TIME, count: 1 } })] })]) as AggregateLike[];
+    expect(aggregate!.offers[0]!.priceSpecification).toEqual({ '@type': 'UnitPriceSpecification', price: '99', priceCurrency: 'USD' });
+  });
+});

package/src/schemas/__tests__/structured-data-reconciliation.test.ts

@@ -541,3 +541,38 @@ describe('reconcileStructuredDataAgainstCatalog', () => {
     );
   });
 });
+
+describe('optional-field recommendations — the catalog entry\'s recommendOptionals, in its own channel', () => {
+  const reconcile = (recommendOptionals: boolean, payload: Record<string, unknown>) =>
+    reconcileStructuredDataAgainstCatalog({
+      catalog: [
+        createCatalogEntry({
+          '@type': 'SoftwareApplication',
+          requiredFields: ['name'],
+          optionalFields: ['offers', 'aggregateRating', 'screenshot'],
+          recommendOptionals,
+        }),
+      ],
+      pages: [{ ref: 'pricing', routePath: '/pricing', sectionRefs: ['pricing-plans'] }],
+      sections: [{ sectionRef: 'pricing-plans', getStructuredData: () => ({ '@type': 'SoftwareApplication', name: 'App', ...payload }) }],
+    });
+
+  it('recommends the optional fields a payload leaves out, when the entry opts in — and reports no finding', () => {
+    const result = reconcile(true, { offers: { '@type': 'Offer' } });
+    expect(result.findings).toEqual([]);
+    expect(result.recommendations).toHaveLength(1);
+    expect(result.recommendations[0]).toMatchObject({
+      pageRef: 'pricing',
+      sectionRef: 'pricing-plans',
+      entityType: 'SoftwareApplication',
+      missingOptionalFields: ['aggregateRating', 'screenshot'],
+    });
+    // A recommendation is not counted as a finding on the page either.
+    expect(result.pages[0]?.findingCount).toBe(0);
+  });
+
+  it('stays quiet when the entry does not opt in (the default), and when nothing is missing', () => {
+    expect(reconcile(false, {}).recommendations).toEqual([]);
+    expect(reconcile(true, { offers: {}, aggregateRating: {}, screenshot: 'x.png' }).recommendations).toEqual([]);
+  });
+});

package/src/schemas/design-tokens/website-design-tokens.shared.schemas.ts

@@ -62,8 +62,10 @@ const cssSafeValue = (fieldName: string): z.ZodString =>
  * @wildo_source:part:start saas.website.design-tokens.colors facet:layer:shared facet:family:website
  *
  * `WebsiteColorTokens` — minimal palette the marketing-site exposes as
- * CSS custom properties (`--website-color-<token>`) on the
- * `<WebsitePageLayout>` root.
+ * CSS custom properties (`--website-colors-<token>`, the key verbatim, so
+ * `surfaceForeground` → `--website-colors-surfaceForeground`) on `:root`.
+ * Reference one from code through `websiteDesignTokenCssVar('colors', …)`
+ * rather than spelling the name.
  *
  * **Why a dedicated marketing palette** (vs. reusing
  * `presets-components-models/design-tokens-config`):
@@ -92,8 +94,9 @@ const cssSafeValue = (fieldName: string): z.ZodString =>
  * `cssSafeValue` JSDoc above for the full threat model.
  *
  * **Adding a token**: append the field here using `cssSafeValue(...)`,
- * document its semantic intent in the JSDoc, and update the matching
- * CSS-emit helper in Phase 2 (`emitWebsiteColorTokensCss`).
+ * document its semantic intent in the JSDoc. `renderWebsiteDesignTokensCss`
+ * (from `@wildo-ai/saas-website/astro`) emits every key generically, so no
+ * emitter needs editing.
  */
 const _WebsiteColorTokensSchema = z.object({
   background: cssSafeValue('background color'),
@@ -118,7 +121,7 @@ export type WebsiteColorTokens = z.infer<typeof _WebsiteColorTokensSchema>;
  * @wildo_source:part:start saas.website.design-tokens.radius facet:layer:shared facet:family:website
  *
  * `WebsiteRadiusTokens` — border-radius scale exposed as
- * `--website-radius-<token>` CSS variables.
+ * `--website-radii-<token>` CSS variables.
  *
  * Marketing radii are intentionally a separate token set from the
  * SaaS app's radii: the website typically wants larger pill / hero
@@ -164,3 +167,40 @@ export const WebsiteDesignTokensSchema: typeof _WebsiteDesignTokensSchema = _Web
 
 export type WebsiteDesignTokens = z.infer<typeof _WebsiteDesignTokensSchema>;
 /** @wildo_source:part:end saas.website.design-tokens.bundle */
+
+/**
+ * The CSS custom-property NAME one design token is emitted under —
+ * `--website-<group>-<token>`, with the token key verbatim (no case
+ * conversion), so `('colors', 'surfaceForeground')` is
+ * `--website-colors-surfaceForeground`.
+ *
+ * This is the one place the naming rule lives. `renderWebsiteDesignTokensCss`
+ * emits through it, and every engine component that reads a token reads
+ * through `websiteDesignTokenCssVar`. It exists because the rule used to be
+ * spelled by hand at each reader, and one reader spelled it
+ * `surface-foreground`: the consent banner's text colour silently fell back to
+ * `#000` on every site, whatever palette the application authored.
+ */
+export function websiteDesignTokenCssProperty(group: string, token: string): string {
+  return `--website-${group}-${token}`;
+}
+
+/**
+ * A `var(...)` reference to one design token, typed against the token bundle
+ * so a misspelt group or key does not compile.
+ *
+ * @example
+ * ```ts
+ * import { websiteDesignTokenCssVar } from '@wildo-ai/saas-website';
+ * const style = { color: websiteDesignTokenCssVar('colors', 'surfaceForeground', '#000') };
+ * // → 'var(--website-colors-surfaceForeground, #000)'
+ * ```
+ */
+export function websiteDesignTokenCssVar<G extends keyof WebsiteDesignTokens>(
+  group: G,
+  token: keyof WebsiteDesignTokens[G] & string,
+  fallback?: string,
+): string {
+  const property = websiteDesignTokenCssProperty(group, token);
+  return fallback === undefined ? `var(${property})` : `var(${property}, ${fallback})`;
+}

package/src/schemas/label-keys/__tests__/scaffolded-consent-label-pack.parity.test.ts

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'node:url';
 import { describe, expect, it } from 'vitest';
 
 import { WEBSITE_CONSENT_LABEL_KEYS } from '../website-consent-label-keys.schemas';
+import { WEBSITE_PROVIDER_COMPONENT_LABEL_KEYS } from '../website-provider-component-label-keys.schemas';
 
 /**
  * The `add-website` scaffold must author EVERY framework-owned consent key.
@@ -68,4 +69,15 @@ describe('the add-website scaffold’s locale pack', () => {
     expect(entries.length).toBe(WEBSITE_CONSENT_LABEL_KEYS.length);
     for (const [, key, value] of entries) expect(value!.trim(), `${key!} is authored empty`).not.toBe('');
   });
+
+  it('authors exactly the provider-component slot keys the framework requires of every site (#1703)', () => {
+    // Same parity, same reason: the slot's consent-required and unavailable wording is framework-owned
+    // and required of every pack, so a composed site missing it would not build.
+    const template = readFileSync(join(findRepositoryRoot(), TEMPLATE_RELATIVE_PATH), 'utf8');
+    const entries = [...template.matchAll(/"(website\.chrome\.provider-component\.[^"]+)"\s*:\s*"([^"]*)"/gu)];
+    expect(entries.map(([, key]) => key!).sort()).toEqual(
+      WEBSITE_PROVIDER_COMPONENT_LABEL_KEYS.map((key) => key as unknown as string).sort(),
+    );
+    for (const [, key, value] of entries) expect(value!.trim(), `${key!} is authored empty`).not.toBe('');
+  });
 });

package/src/schemas/label-keys/website-provider-component-label-keys.schemas.ts

@@ -0,0 +1,40 @@
+import { WebsiteLabelKeySchema, type WebsiteLabelKey } from './website-label-key.schemas';
+
+/**
+ * The label keys the framework's provider-component slot reads (#1703).
+ *
+ * FRAMEWORK-OWNED, like the consent panel's keys: `WebsiteProviderComponent` renders these states,
+ * not the site's chrome, so the site does not list them in `chromeLabelKeys`.
+ * `composeEffectiveChromeLabelKeys` unions them into the label-pack validator's expected set, so a
+ * locale pack missing one fails the build rather than showing a visitor a raw key.
+ *
+ * Required of every site, including one that places no provider component today, for the reason the
+ * consent keys are: the words are cheap, and a site that adds an address lookup tomorrow must not
+ * ship it with an unlabelled refusal. The consent-required state also names each missing purpose and
+ * offers the panel, and it reuses the consent keys for both (`purpose-<purpose>`, `manage`) rather
+ * than a second wording of the same thing.
+ */
+export enum WebsiteProviderComponentLabelSlot {
+  /**
+   * Shown where a provider component would be when the visitor has not agreed to a purpose it rests
+   * on. Says the feature is off until they agree; the purposes and the way to agree follow it.
+   */
+  CONSENT_REQUIRED = 'consent-required',
+  /**
+   * Shown when the component could not be loaded (a network failure, a blocked script). Says the
+   * feature is unavailable right now, without blaming the visitor.
+   */
+  UNAVAILABLE = 'unavailable',
+}
+
+const PROVIDER_COMPONENT_LABEL_KEY_PREFIX = 'website.chrome.provider-component';
+
+/** The fully-composed key for one slot state. */
+export function websiteProviderComponentLabelKey(slot: WebsiteProviderComponentLabelSlot): WebsiteLabelKey {
+  return WebsiteLabelKeySchema.parse(`${PROVIDER_COMPONENT_LABEL_KEY_PREFIX}.${slot}`);
+}
+
+/** Every framework-owned provider-component key — what a locale pack must carry. Total over the vocabulary. */
+export const WEBSITE_PROVIDER_COMPONENT_LABEL_KEYS: readonly WebsiteLabelKey[] = Object.freeze(
+  Object.values(WebsiteProviderComponentLabelSlot).map(websiteProviderComponentLabelKey),
+);

package/src/schemas/manifests/website-root-config.shared.schemas.ts

@@ -94,9 +94,10 @@ export type WebsiteSitemapConfig = z.infer<typeof _WebsiteSitemapConfigSchema>;
  *     `'noindex'` is the deliberate exception (staging environments,
  *     beta surfaces, sites still under construction). The opt-OUT
  *     shape mirrors `WebsiteSitemapConfig.enabled` for consistency.
- *   - `'noindex'` emits a `User-agent: *\nDisallow: /` block — the
- *     standard "tell every well-behaved crawler to stay away"
- *     primitive.
+ *   - `'noindex'` is expressed by a `<meta name="robots" content="noindex">`
+ *     on every page, NOT by `Disallow: /` in `robots.txt` (#494): a crawler
+ *     barred from fetching a page never reads its noindex, so the URL can
+ *     still be indexed bare. `robots.txt` stays allow-everything for it.
  *
  * **Why `disallow[]` is a path-prefix list (not a regex)**:
  *   - The `robots.txt` spec only supports literal path prefixes
@@ -420,10 +421,10 @@ const _WebsiteRootConfigSchema = z
      *     the chrome) or above it (creating a structural surface
      *     the framework needs anyway).
      *
-     * The key MUST also be present in `chromeLabelKeys` (the
-     * label-pack validator silences "orphaned" warnings off
-     * `chromeLabelKeys`) — the framework adds it automatically via
-     * the `superRefine` pass below so consumers cannot forget.
+     * It is validated as a chrome key without being listed in
+     * `chromeLabelKeys`: the label-pack loader adds it to the effective
+     * chrome key set (`composeEffectiveChromeLabelKeys` in
+     * `astro/label-pack-loader.ts`), so consumers cannot forget it.
      */
     skipToMainContentLabelKey: WebsiteLabelKeySchema,
   })
@@ -484,8 +485,8 @@ export const WebsiteRootConfigSchema: typeof _WebsiteRootConfigSchema = _Website
  * and `navigation.footerComponent` as `unknown` (their schema field
  * type), losing the `ComponentType<unknown>` narrowing carried by the
  * hand-written `WebsitePageManifest` and `WebsiteNavigationConfig`
- * interfaces. Factories such as `defineWebsiteRootConfig` and the
- * layout primitives consume `WebsiteRootConfig` and must see those
+ * interfaces. The layout primitives and the Astro helpers consume
+ * `WebsiteRootConfig` and must see those
  * fields pre-narrowed; otherwise every consumer would need a local
  * `as ComponentType` cast at the JSX call site, defeating the type-safe
  * component contract.

package/src/schemas/sections/website-section-definition.shared.schemas.ts

@@ -14,7 +14,8 @@ import { WebsiteSectionCategorySchema } from './website-section-category.shared'
  * `core/define-website-section.tsx` module in Phase 2 because it carries
  * React types in its inputs). The shape is declared in `schemas/`
  * because it is the **observable contract** the page-manifest
- * registration, label-pack validator, and SEO dispatcher depend on.
+ * registration, the label-pack validator, `renderPageStructuredData` and the
+ * structured-data audit depend on.
  *
  * **Shape rationale** (each field carries semantic weight — see
  * `design-philosophy.mdc`):
@@ -24,7 +25,8 @@ import { WebsiteSectionCategorySchema } from './website-section-category.shared'
  *   (a section can be reused with the same `sectionRef` across pages
  *   when its label-key root is intentionally shared).
  * - `category` — see `WebsiteSectionCategory` JSDoc; tags the section
- *   for SEO-dispatch, skill-mapping, and analytics labelling.
+ *   for skill-mapping and analytics labelling. It does NOT select the
+ *   section's structured data.
  * - `expectedLabelKeys` — the **fully-composed** label keys the section
  *   commits to consuming. The plan originally proposed leaf-relative
  *   keys (`'headline'`) resolved at runtime against the
@@ -37,9 +39,13 @@ import { WebsiteSectionCategorySchema } from './website-section-category.shared'
  *        graph — `wildo website audit` can list a page's required keys
  *        without booting React.
  *     3. The leaf-relative ergonomics (`useWebsiteLabel('headline')`)
- *        survive in Phase 2 — the hook composes the leaf with the
- *        page+section context and validates the result against
- *        `expectedLabelKeys`.
+ *        survive — the hook composes the leaf with the page+section
+ *        context and looks the result up in the active pack. It does
+ *        NOT check the key against `expectedLabelKeys`: a leaf the
+ *        section never declared renders its key (with a console warning)
+ *        and is caught by nothing until a reviewer reads the page. The
+ *        build and `wildo website audit` check the pack against the
+ *        DECLARED keys, so declare every slot the component reads.
  * - `Component` — the React component that renders the section. Typed
  *   as `ComponentType<unknown>` here because schema-layer cannot lock
  *   the component's prop shape (props vary per section). The factory
@@ -49,8 +55,9 @@ import { WebsiteSectionCategorySchema } from './website-section-category.shared'
  * - `getStructuredData?` — optional pure function the SEO/AEO/GEO
  *   builder library invokes at static-build time to materialize JSON-LD
  *   for the section. The return type is intentionally `unknown` here;
- *   the SEO library narrows by `category` (e.g. `PRICING` →
- *   `Product | AggregateOffer`).
+ *   nothing narrows it by `category` — the section returns whatever
+ *   vocabulary it emits, and `wildo website audit` reconciles that
+ *   against the application's Schema.org catalog.
  *
  * **Why not `z.custom<ComponentType>(…)`**: a `z.custom` predicate
  * cannot meaningfully validate "is a React component" beyond

package/src/schemas/structured-data/pricing-offer-structured-data.shared.ts

@@ -0,0 +1,144 @@
+import {
+  ProductAvailability,
+  ProductPriceDisclosure,
+  PublicPricingAmountBasis,
+  PublicPricingRecurrenceUnit,
+  publicPricingAmountDecimal,
+  type PublicPricingCatalog,
+  type PublicPricingPlan,
+  type PublicPricingPrice,
+} from '@wildo-ai/saas-models/public-runtime';
+
+import type { WebsiteStructuredDataPayload } from './website-structured-data.shared.schemas';
+
+/**
+ * @wildo_source:part:start saas.website.pricing-offer-structured-data facet:layer:core facet:family:website facet:audience:app-developer
+ *
+ * `buildWebsitePricingOfferStructuredData` — the `AggregateOffer` a pricing page publishes, DERIVED from
+ * the application's public pricing catalogue (#1835) instead of typed by hand beside it.
+ *
+ * ## What it publishes, and what it refuses to
+ *
+ * A search engine shows an offer's `price` as the price of the offer, so an offer is published only
+ * when that is TRUE:
+ *
+ * - the plan is on sale (`availability: AVAILABLE`) — an upcoming plan cannot be bought;
+ * - its price is `LISTED` — a starting price is a floor, and an on-request plan has no price;
+ * - its published price states the whole offer for its unit: a flat or per-unit amount, never an
+ *   indicative amount of a tiered, graduated or package price.
+ *
+ * Each published offer uses the plan's DEFAULT price (the one the catalogue marks) and carries a
+ * `UnitPriceSpecification` saying what the number is FOR: its recurrence as `billingDuration` (ISO 8601
+ * `P1M` / `P1Y`) and, for a per-unit price, a `referenceQuantity` of one of the page's unit (`member`)
+ * — so "$4 per member per month" is never read as "$4".
+ *
+ * One `AggregateOffer` per (currency, amount basis, recurrence): a range is only meaningful over prices
+ * that measure the same thing, so a flat price and a per-member price, or a monthly and a yearly one, are
+ * never folded into one `lowPrice` / `highPrice`. EVERY group's `@id` is `aggregateOfferIdPrefix` suffixed with
+ * what distinguishes it (`-per-unit-1-month-usd`), so an aggregate's identity depends only on what it
+ * aggregates: adding, removing or reordering a plan in ANOTHER group never moves it. Returns `[]` when
+ * nothing may be published — a page with only on-request plans publishes no price at all, which is the
+ * true statement.
+ */
+export interface BuildWebsitePricingOfferStructuredDataInput {
+  readonly catalog: PublicPricingCatalog;
+  /** The `@id` of the entity the offers price — typically the page's `SoftwareApplication`. */
+  readonly itemOfferedId: string;
+  /**
+   * The prefix of every `AggregateOffer` `@id` (`https://…/pricing#plans`); each group appends what it
+   * aggregates, e.g. `#plans-flat-1-month-usd`.
+   */
+  readonly aggregateOfferIdPrefix: string;
+  /** The URL of the page the offers are made on; each offer's URL is this plus `#plan-<key>`. */
+  readonly url: string;
+  /**
+   * The plan's name in the page's locale. Names are text a person reads, so they come from the page's
+   * label pack; a plan the callback does not name is published without one rather than with its key.
+   */
+  readonly planName?: (planKey: string) => string | undefined;
+  /**
+   * What ONE unit of a per-unit price is, in the page's locale (`member`, `seat`) — published as the
+   * offer's `referenceQuantity.unitText`. Required when any published offer is per-unit: omitting it
+   * would state a per-member price as a whole price, so the builder refuses instead.
+   */
+  readonly perUnitName?: string;
+}
+
+export function buildWebsitePricingOfferStructuredData(input: BuildWebsitePricingOfferStructuredDataInput): readonly WebsiteStructuredDataPayload[] {
+  const published = input.catalog.plans.flatMap((plan) => {
+    const price = publishablePrice(plan);
+    return price === undefined ? [] : [{ plan, price }];
+  });
+  if (published.some(({ price }) => price.amountBasis === PublicPricingAmountBasis.PER_UNIT) && !input.perUnitName) {
+    throw new Error(
+      '[buildWebsitePricingOfferStructuredData] a published plan is priced per unit, so the page must name the unit '
+        + '(`perUnitName`, e.g. "member"); without it the offer would state a per-unit price as the whole price.',
+    );
+  }
+  const groupKeyOf = (price: PublicPricingPrice): string =>
+    `${price.currency}|${price.amountBasis}|${price.recurrence.unit}|${price.recurrence.count}`;
+  const groupKeys = [...new Set(published.map(({ price }) => groupKeyOf(price)))];
+  return groupKeys.map((groupKey) => {
+    const offers = published.filter(({ price }) => groupKeyOf(price) === groupKey);
+    const sample = offers[0]!.price;
+    const amounts = offers.map(({ price }) => publicPricingAmountDecimal(price));
+    const numeric = amounts.map(Number);
+    return {
+      '@type': 'AggregateOffer',
+      '@id': `${input.aggregateOfferIdPrefix}-${aggregateSuffix(sample)}`,
+      itemOffered: { '@id': input.itemOfferedId },
+      priceCurrency: sample.currency,
+      lowPrice: amounts[numeric.indexOf(Math.min(...numeric))],
+      highPrice: amounts[numeric.indexOf(Math.max(...numeric))],
+      offerCount: offers.length,
+      url: input.url,
+      offers: offers.map(({ plan, price }) => {
+        const name = input.planName?.(plan.key);
+        const amount = publicPricingAmountDecimal(price);
+        return {
+          '@type': 'Offer',
+          ...(name === undefined ? {} : { name }),
+          price: amount,
+          priceCurrency: price.currency,
+          availability: 'https://schema.org/InStock',
+          url: `${input.url}#plan-${plan.key}`,
+          priceSpecification: {
+            '@type': 'UnitPriceSpecification',
+            price: amount,
+            priceCurrency: price.currency,
+            ...(price.recurrence.unit === PublicPricingRecurrenceUnit.ONE_TIME ? {} : { billingDuration: isoDurationOf(price) }),
+            ...(price.amountBasis === PublicPricingAmountBasis.PER_UNIT
+              ? { referenceQuantity: { '@type': 'QuantitativeValue', value: 1, unitText: input.perUnitName } }
+              : {}),
+          },
+        };
+      }),
+    };
+  });
+}
+
+/** What distinguishes an aggregate's `@id`: its basis, its recurrence and its currency — exactly its group key. */
+function aggregateSuffix(price: PublicPricingPrice): string {
+  return `${price.amountBasis}-${price.recurrence.count}-${price.recurrence.unit}-${price.currency}`.toLowerCase().replace(/_/gu, '-');
+}
+
+/** The plan's default price, when publishing it as the offer's price would be true. */
+function publishablePrice(plan: PublicPricingPlan): PublicPricingPrice | undefined {
+  if (plan.availability !== ProductAvailability.AVAILABLE) return undefined;
+  if (plan.priceDisclosure !== ProductPriceDisclosure.LISTED) return undefined;
+  const price = plan.prices.find((candidate) => candidate.isDefault) ?? plan.prices[0];
+  if (price === undefined || price.amountBasis === PublicPricingAmountBasis.VARIABLE) return undefined;
+  return price;
+}
+
+/** Total over the recurring units: a member added to the vocabulary is a compile error here until it is mapped. */
+const ISO_DURATION_DESIGNATOR: Record<Exclude<PublicPricingRecurrenceUnit, PublicPricingRecurrenceUnit.ONE_TIME>, string> = {
+  [PublicPricingRecurrenceUnit.MONTH]: 'M',
+  [PublicPricingRecurrenceUnit.YEAR]: 'Y',
+};
+
+function isoDurationOf(price: PublicPricingPrice): string {
+  const unit = price.recurrence.unit as Exclude<PublicPricingRecurrenceUnit, PublicPricingRecurrenceUnit.ONE_TIME>;
+  return `P${price.recurrence.count}${ISO_DURATION_DESIGNATOR[unit]}`;
+}
+/** @wildo_source:part:end saas.website.pricing-offer-structured-data */

package/src/schemas/structured-data/structured-data-reconciliation.shared.ts

@@ -103,6 +103,28 @@ export type StructuredDataReconciliationFinding =
   | StructuredDataDeprecatedFieldFinding
   | StructuredDataCrossEntityReferenceDriftFinding;
 
+/**
+ * An OPTIONAL field a payload leaves out, reported because its catalog entry opted in with
+ * `recommendOptionals: true` — the entry's statement that for this type the optional fields are
+ * where the richer search and answer-engine results come from.
+ *
+ * Deliberately NOT a finding. A finding says the payload is wrong (a missing required field, an
+ * unknown type, a deprecated field) and `--strict` escalates every finding to a failure. A payload
+ * without its optional fields is valid; reporting it through the same channel would fail strict CI for
+ * following the vocabulary. So recommendations travel beside the findings, are shown as information,
+ * and never change an audit's outcome.
+ */
+export interface StructuredDataOptionalFieldRecommendation {
+  pageRef: string;
+  routePath: string;
+  sectionRef: string;
+  entityType: string;
+  entityId?: string;
+  /** The entry's optional fields this payload does not carry, in catalog order. */
+  missingOptionalFields: readonly string[];
+  message: string;
+}
+
 export interface StructuredDataReconciliationPageResult {
   pageRef: string;
   routePath: string;
@@ -112,6 +134,8 @@ export interface StructuredDataReconciliationPageResult {
 
 export interface StructuredDataReconciliationResult {
   findings: StructuredDataReconciliationFinding[];
+  /** Optional-field recommendations from entries that opted in — information, never a finding. */
+  recommendations: StructuredDataOptionalFieldRecommendation[];
   pages: StructuredDataReconciliationPageResult[];
 }
 
@@ -133,6 +157,7 @@ export function reconcileStructuredDataAgainstCatalog(
   options: ReconcileStructuredDataOptions,
 ): StructuredDataReconciliationResult {
   const findings: StructuredDataReconciliationFinding[] = [];
+  const recommendations: StructuredDataOptionalFieldRecommendation[] = [];
   const pages: StructuredDataReconciliationPageResult[] = [];
   const sectionsByRef = new Map(
     options.sections.map((section) => [section.sectionRef, section] as const),
@@ -301,7 +326,7 @@ export function reconcileStructuredDataAgainstCatalog(
 
       const routeFindingStart = findings.length;
       for (const payloadContext of payloadContexts) {
-        validatePayloadAgainstCatalog(payloadContext, catalogByType, declaredEntityIds, findings);
+        validatePayloadAgainstCatalog(payloadContext, catalogByType, declaredEntityIds, findings, recommendations);
       }
 
       pages.push({
@@ -332,6 +357,7 @@ export function reconcileStructuredDataAgainstCatalog(
 
   return {
     findings,
+    recommendations,
     pages,
   };
 }
@@ -411,6 +437,7 @@ function validatePayloadAgainstCatalog(
   catalogByType: ReadonlyMap<string, StructuredDataCatalogEntry>,
   declaredEntityIds: ReadonlySet<string>,
   findings: StructuredDataReconciliationFinding[],
+  recommendations: StructuredDataOptionalFieldRecommendation[],
 ): void {
   const { payload, pageRef, routePath, sectionRef } = payloadContext;
   const entityType = payload['@type'];
@@ -450,6 +477,24 @@ function validatePayloadAgainstCatalog(
     }
   }
 
+  if (catalogEntry.recommendOptionals === true) {
+    const missingOptionalFields = (catalogEntry.optionalFields ?? []).filter((field) => !hasPresentFieldValue(payload, field));
+    if (missingOptionalFields.length > 0) {
+      recommendations.push({
+        pageRef,
+        routePath,
+        sectionRef,
+        entityType,
+        entityId,
+        missingOptionalFields,
+        message:
+          `Structured-data payload @type="${entityType}" emitted by section "${sectionRef}" on page "${pageRef}" ` +
+          `could carry ${missingOptionalFields.map((field) => `"${field}"`).join(', ')} — optional, and the catalog ` +
+          'recommends them for richer search and answer-engine results.',
+      });
+    }
+  }
+
   for (const deprecatedField of catalogEntry.deprecatedFields ?? []) {
     if (!hasPresentFieldValue(payload, deprecatedField.field)) {
       continue;

package/src/schemas/structured-data/website-structured-data.shared.schemas.ts

@@ -16,11 +16,13 @@
  *
  * - `@type` REQUIRED — the Schema.org entity kind (`'Article'`,
  *   `'BlogPosting'`, `'FAQPage'`, …). Typed as a free-form `string`
- *   here (not a closed enum) so app-side catalog extensions
- *   (e.g. `'SoftwareApplication'`, custom Schema.org-extension
- *   `@type`s) are emittable without a saas-website release. The
- *   companion's catalog reconciliation surface validates the
- *   `@type` value against the merged engine + app catalog.
+ *   here (not a closed enum) because this package ships to the browser
+ *   and must not carry the catalog: the renderer emits whatever type a
+ *   section returns. What VALIDATES the type is the Schema.org catalog,
+ *   through `wildo website audit` and the companion's reconciliation —
+ *   and that catalog is a closed enum an application can override but
+ *   not extend, so a type outside it reports `catalog-miss` until the
+ *   framework adds it.
  * - `@id?` OPTIONAL — a stable URI identifying the entity. Used for
  *   cross-referencing on the same page (e.g. `Article.publisher`
  *   referencing the page-level `Organization` via `@id`). The