@wildo-ai/saas-website 1.1.2 → 1.1.4

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

@@ -8,33 +8,31 @@ import { z } from 'zod';
  *
  * The category is NOT a layout-shape constraint and NOT a CSS class; the
  * framework ships zero concrete sections and never inspects
- * the category at render time. The category exists for three orthogonal
+ * the category at render time. The category exists for two orthogonal
  * non-render concerns:
  *
- * 1. **Structured-data dispatch**: the
- *    SEO library reads `WebsiteSectionDefinition.category` to decide
- *    which JSON-LD vocabulary the section's `getStructuredData()` hook
- *    is allowed to emit. e.g. `PRICING` may emit `Product` /
- *    `AggregateOffer`; `FAQ` may emit `FAQPage`; `HERO` may emit
- *    `Organization` / `WebSite`. Mismatches are surfaced as build-time
- *    warnings.
- * 2. **Authoring guidance**: each value has matching application-builder
+ * 1. **Authoring guidance**: each value has matching application-builder
  *    guidance. When introducing a new category, provide its public authoring
  *    method before asking an application to use it.
- * 3. **Analytics labelling**: the runtime emits
+ * 2. **Analytics labelling**: the runtime emits
  *    `data-section-category="…"` on the `<WebsiteSection>` wrapper so
  *    analytics tooling can group section impressions
  *    without parsing className conventions.
  *
+ * **It does NOT gate structured data.** Nothing dispatches JSON-LD by category: the structured-data
+ * renderer receives only `sectionRef` and `getStructuredData`, the reconciliation contract carries
+ * no category at all, and no build-time warning compares the two. A section may return any
+ * vocabulary from `getStructuredData()` whatever its category says, so choose the category for what
+ * it does do (guidance and analytics grouping) and validate your JSON-LD yourself.
+ *
  * **Closed vocabulary on purpose**: a free-string `category` would
- * defeat the skill-mapping and SEO-dispatch contracts. Consumers who
- * need a wholly-novel section shape use the `RAW` advanced path
+ * defeat the skill mapping and would make the analytics attribute unaggregatable.
+ * Consumers who need a wholly-novel section shape use the `RAW` advanced path
  * (`website-factory-advanced` skill) which bypasses the category
  * vocabulary entirely.
  *
- * **Adding a value**: requires (a) a new entry here, (b) a matching
- * `website_section_<value>` skill stub, (c) (optionally) a
- * structured-data dispatch entry in the SEO library. Removing a value
+ * **Adding a value**: requires (a) a new entry here and (b) a matching
+ * `website_section_<value>` skill stub. Removing a value
  * is a labelled rename — every consumer's
  * `defineWebsiteSection({ category: … })` declaration breaks at compile
  * time, which is the desired loud failure.
@@ -51,11 +49,12 @@ export enum WebsiteSectionCategory {
   FOOTER_CTA = 'footer-cta',
   /**
    * Escape hatch for sections that don't fit any standard category
-   * (third-party widgets, custom one-off marketing pieces). Skips the
-   * SEO-dispatch contract — the section's `getStructuredData()` may
-   * return any vocabulary, no validation. Authors should prefer a
-   * concrete category whenever possible; using `RAW` opts the section
-   * out of the framework's structured-data safety net.
+   * (third-party widgets, custom one-off marketing pieces). Authors should
+   * prefer a concrete category whenever possible, so the section receives the
+   * matching authoring guidance and groups with its peers in analytics.
+   *
+   * It makes no difference to structured data: no category validates
+   * `getStructuredData()`, so `RAW` opts out of nothing there.
    */
   RAW = 'raw',
 }