@wildo-ai/saas-website 1.1.4 → 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

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+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.
+ *
+ * ## The failure this exists to stop, measured 2026-09-20
+ *
+ * `WEBSITE_CONSENT_LABEL_KEYS` is what a locale pack must carry, and a pack missing one fails the
+ * site's build rather than showing a visitor a raw key — that refusal is deliberate, and its own
+ * declaration says why: *"a site that adds analytics tomorrow must not ship it with an unlabelled —
+ * or absent — way to refuse."*
+ *
+ * The key set then GREW by four (the always-active row, and one explanation per purpose). The
+ * dogfood site's packs were updated by hand and the SCAFFOLD was not, so every newly composed
+ * website would have shipped four keys short — a scaffold that cannot build, produced by a change
+ * two packages away, with nothing between the two but somebody remembering.
+ *
+ * ## Why a parity test rather than a shared constant
+ *
+ * The template is Handlebars, so no TypeScript can import it and no type can relate the two. That
+ * leaves the same choice this repository has made before for exactly this shape
+ * (`scaffolded-resource-operations.parity.test.ts`): a COPY of a fact, with a test holding the copy
+ * equal to its source. What makes it worth having is the direction of the failure — a missing key is
+ * invisible until somebody composes a site, and the person who composes it is not the person who
+ * added the key.
+ *
+ * It asserts EQUALITY, not containment, in both directions: a key the template authors and the
+ * framework no longer asks for is a label nobody renders, which is the defect `#54` started from.
+ */
+const TEMPLATE_RELATIVE_PATH = 'templates/saas/scenarios/add-website/files/website/src/i18n/en.json.hbs';
+
+function findRepositoryRoot(): string {
+  let directory = dirname(fileURLToPath(import.meta.url));
+  while (!existsSync(join(directory, TEMPLATE_RELATIVE_PATH))) {
+    const parent = dirname(directory);
+    if (parent === directory) throw new Error(`Could not locate ${TEMPLATE_RELATIVE_PATH} above ${fileURLToPath(import.meta.url)}.`);
+    directory = parent;
+  }
+  return directory;
+}
+
+describe('the add-website scaffold’s locale pack', () => {
+  it('authors exactly the consent keys the framework requires of every site', () => {
+    const template = readFileSync(join(findRepositoryRoot(), TEMPLATE_RELATIVE_PATH), 'utf8');
+    const authored = [...template.matchAll(/"(website\.chrome\.consent\.[^"]+)"\s*:/gu)].map((match) => match[1]!);
+
+    /*
+     * Guards the guard: a regex that matched nothing would report perfect agreement with an empty
+     * template, which is the shape `--self-test` exists for everywhere else in this repository.
+     */
+    expect(authored.length, 'the template no longer authors consent keys this test can read').toBeGreaterThan(0);
+
+    const required = WEBSITE_CONSENT_LABEL_KEYS.map((key) => key as unknown as string);
+    expect([...authored].sort()).toEqual([...required].sort());
+  });
+
+  it('gives every authored consent key a non-empty value', () => {
+    // A key present with an empty string satisfies a pack validator and shows a visitor nothing —
+    // the same outcome as the missing key, arrived at through the check rather than around it.
+    const template = readFileSync(join(findRepositoryRoot(), TEMPLATE_RELATIVE_PATH), 'utf8');
+    const entries = [...template.matchAll(/"(website\.chrome\.consent\.[^"]+)"\s*:\s*"([^"]*)"/gu)];
+    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-consent-label-keys.schemas.ts

@@ -0,0 +1,78 @@
+import { ConsentPurpose, CONSENT_PURPOSES } from '@wildo-ai/saas-models/public-runtime';
+
+import { WebsiteLabelKeySchema, type WebsiteLabelKey } from './website-label-key.schemas';
+
+/**
+ * The label keys the framework's visitor consent surface reads (#534).
+ *
+ * FRAMEWORK-OWNED, like the skip link's key: the consent banner is rendered by `WebsitePageLayout`, not by
+ * the site's chrome, so the site does not list these 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.
+ *
+ * They are required of every site, including one that runs no consent-based provider today: the words are
+ * cheap, and a site that adds analytics tomorrow must not ship it with an unlabelled — or absent — way to
+ * refuse.
+ *
+ * Purpose names are keyed by the `ConsentPurpose` VALUE and derived from the vocabulary, so a purpose added
+ * to it is a missing label in every site's pack at the next build, not a purpose the banner cannot name.
+ */
+export enum WebsiteConsentLabelSlot {
+  /** Heading of the consent panel. */
+  TITLE = 'title',
+  /** What the panel is for: optional purposes are off until agreed, each chosen separately, changeable later. */
+  DESCRIPTION = 'description',
+  /** Agree to every purpose listed. */
+  ACCEPT_ALL = 'accept-all',
+  /** Agree to none of them — recorded as a choice, so the panel does not return. */
+  DECLINE_ALL = 'decline-all',
+  /** Save exactly the purposes ticked. */
+  SAVE = 'save',
+  /** Re-open the panel to change a choice already made. */
+  MANAGE = 'manage',
+  /**
+   * Name of the row covering what runs whatever the visitor chooses.
+   *
+   * NOT a `ConsentPurpose`, and it must never become one: that vocabulary is what a visitor DECIDES,
+   * and this is the thing they are not being asked about. It is shown because a panel listing only
+   * the optional purposes cannot answer the question a visitor opened it to answer — what is
+   * happening on this site — which is why every specialized consent platform states it.
+   */
+  ESSENTIAL_TITLE = 'essential-title',
+  /** What the always-active row covers, and why its control is checked and cannot be changed. */
+  ESSENTIAL_DESCRIPTION = 'essential-description',
+}
+
+const CONSENT_LABEL_KEY_PREFIX = 'website.chrome.consent';
+
+/** The fully-composed key for one panel slot. */
+export function websiteConsentLabelKey(slot: WebsiteConsentLabelSlot): WebsiteLabelKey {
+  return WebsiteLabelKeySchema.parse(`${CONSENT_LABEL_KEY_PREFIX}.${slot}`);
+}
+
+/** The fully-composed key naming one consent purpose. */
+export function websiteConsentPurposeLabelKey(purpose: ConsentPurpose): WebsiteLabelKey {
+  return WebsiteLabelKeySchema.parse(`${CONSENT_LABEL_KEY_PREFIX}.purpose-${purpose}`);
+}
+
+/**
+ * The key EXPLAINING one consent purpose — what agreeing to it means for this visitor.
+ *
+ * The name above answers *what is it called*; this answers *what will happen to me*, and a choice
+ * made without the second is not an informed one. "Analytics" beside a tick box is a category, not
+ * something a visitor can weigh.
+ *
+ * Derived from the vocabulary exactly as the name is, so a purpose added to `ConsentPurpose` is a
+ * missing label in every site's pack at the next build rather than a row that renders a name with no
+ * explanation beneath it.
+ */
+export function websiteConsentPurposeDescriptionLabelKey(purpose: ConsentPurpose): WebsiteLabelKey {
+  return WebsiteLabelKeySchema.parse(`${CONSENT_LABEL_KEY_PREFIX}.purpose-${purpose}-description`);
+}
+
+/** Every framework-owned consent key — what a locale pack must carry. Total over both vocabularies. */
+export const WEBSITE_CONSENT_LABEL_KEYS: readonly WebsiteLabelKey[] = Object.freeze([
+  ...Object.values(WebsiteConsentLabelSlot).map(websiteConsentLabelKey),
+  ...CONSENT_PURPOSES.map(websiteConsentPurposeLabelKey),
+  ...CONSENT_PURPOSES.map(websiteConsentPurposeDescriptionLabelKey),
+]);

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