@wildo-ai/saas-website 1.1.7 → 1.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wildo-ai/saas-website",
-  "version": "1.1.7",
+  "version": "1.1.9",
   "description": "SaaS marketing/landing website engine — schemas, helpers, layout/primitive placeholders, Astro/MDX adapters, and SEO/AEO/GEO builder library. Consumers author all business sections themselves via the defineWebsiteSection factory.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Wildo AI",
@@ -65,10 +65,10 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@wildo-ai/external-connectors-public": "1.1.7",
-    "@wildo-ai/platform-config-lib": "1.1.7",
-    "@wildo-ai/presets-components-models": "1.1.7",
-    "@wildo-ai/saas-models": "1.1.7",
+    "@wildo-ai/external-connectors-public": "1.1.9",
+    "@wildo-ai/platform-config-lib": "1.1.9",
+    "@wildo-ai/presets-components-models": "1.1.9",
+    "@wildo-ai/saas-models": "1.1.9",
     "yaml": "^2.3.4"
   },
   "devDependencies": {

package/src/astro/__tests__/assert-website-pages-have-sections.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from 'vitest';
+
+import { AvailableLanguage } from '@wildo-ai/saas-models/public-runtime';
+
+import { WildoMarketingWebsiteConfigSchema } from '../../config/wildo-website-config.schemas';
+import { WebsiteLabelKeySchema } from '../../schemas/label-keys/website-label-key.schemas';
+import { WebsitePageManifestSchema } from '../../schemas/manifests/website-page-manifest.shared.schemas';
+import { WebsiteRootConfigSchema, type WebsiteRootConfig } from '../../schemas/manifests/website-root-config.shared.schemas';
+import { assertWebsitePagesHaveSections, listWebsitePagesWithoutSections } from '../assert-website-pages-have-sections';
+import { assertLabelPacksValid } from '../label-pack-loader';
+import { composeWebsiteSiteContext } from '../website-site-context';
+
+/**
+ * #2205: an empty page is a valid manifest so `astro dev` can serve it, and BUILDING one is refused.
+ * The refusal used to sit in the manifest schema, where it crashed the dev server at module load
+ * until every page of the site had a section.
+ */
+const NoopComponent = () => null;
+
+const manifest = (ref: string, sectionRefs: readonly string[]) =>
+  WebsitePageManifestSchema.parse({
+    ref,
+    routePath: ref === 'home' ? '/' : `/${ref}`,
+    pageComponent: NoopComponent,
+    sectionRefs,
+    metaLabelKeys: {
+      titleKey: WebsiteLabelKeySchema.parse(`website.${ref}.meta.title`),
+      descriptionKey: WebsiteLabelKeySchema.parse(`website.${ref}.meta.description`),
+    },
+  });
+
+const rootConfig = (pageManifests: readonly ReturnType<typeof manifest>[]): WebsiteRootConfig =>
+  WebsiteRootConfigSchema.parse({
+    pageManifests,
+    designTokens: {
+      colors: {
+        background: '#fff', foreground: '#111', primary: '#0070f3', primaryForeground: '#fff', accent: '#ff5e5b',
+        accentForeground: '#fff', surface: '#fafafa', surfaceForeground: '#111', border: '#e5e5e5', muted: '#f5f5f5', mutedForeground: '#737373',
+      },
+      radii: { none: '0', sm: '0.125rem', md: '0.375rem', lg: '0.75rem', xl: '1.5rem', full: '9999px' },
+    },
+    navigation: { headerComponent: NoopComponent, footerComponent: NoopComponent },
+    seo: { siteName: 'Example' },
+    skipToMainContentLabelKey: WebsiteLabelKeySchema.parse('website.chrome.layout.skip-to-main-content'),
+  }) as WebsiteRootConfig;
+
+describe('assertWebsitePagesHaveSections', () => {
+  it('passes a site whose every page has a section', () => {
+    expect(() => assertWebsitePagesHaveSections(rootConfig([manifest('home', ['home-hero'])]))).not.toThrow();
+  });
+
+  it('refuses a site with an empty page, and names EVERY empty page in one error', () => {
+    const config = rootConfig([manifest('home', []), manifest('pricing', ['pricing-hero']), manifest('contact', [])]);
+    expect(() => assertWebsitePagesHaveSections(config)).toThrow(/2 page\(s\) declare no section and cannot be built: "home", "contact"/);
+  });
+
+  it('lists the empty pages without throwing, for a report that must answer what the build would refuse', () => {
+    const config = rootConfig([manifest('home', []), manifest('pricing', ['pricing-hero'])]);
+    expect(listWebsitePagesWithoutSections(config)).toEqual(['home']);
+  });
+
+  it('is armed by assertLabelPacksValid, the build-start hook every website already wires', () => {
+    const siteContext = composeWebsiteSiteContext({
+      rootConfig: rootConfig([manifest('home', [])]),
+      websiteConfig: WildoMarketingWebsiteConfigSchema.parse({
+        publicOrigin: 'https://example.com',
+        appOrigin: 'https://app.example.com',
+        defaultLocale: AvailableLanguage.EN,
+        locales: [{ locale: AvailableLanguage.EN, path: 'en' }],
+      }),
+    });
+    // The packs directory does not exist: the empty-page refusal runs first, so it is what surfaces.
+    expect(() => assertLabelPacksValid('/nonexistent/website-packs', siteContext, new Map())).toThrow(/declare no section and cannot be built: "home"/);
+  });
+});

package/src/astro/assert-website-pages-have-sections.ts

@@ -0,0 +1,41 @@
+import type { WebsiteRootConfig } from '../schemas/manifests/website-root-config.shared.schemas';
+
+/**
+ * The refs of every page that declares no section, in manifest order — the population
+ * {@link assertWebsitePagesHaveSections} refuses to build. Exported on its own so a report
+ * (`wildo website audit`) answers from the same predicate the build applies, without throwing.
+ */
+export function listWebsitePagesWithoutSections(rootConfig: Pick<WebsiteRootConfig, 'pageManifests'>): readonly string[] {
+  return rootConfig.pageManifests
+    .filter((manifest) => manifest.sectionRefs.length === 0)
+    .map((manifest) => String(manifest.ref));
+}
+
+/**
+ * Refuse to BUILD a website while any page has no section (#2205).
+ *
+ * A page manifest may declare an empty `sectionRefs` list: that is a page whose sections are still
+ * being authored, and the application-creation build lane creates exactly that state (the page task
+ * writes the empty list, then each section task appends itself). A dev server must be able to serve
+ * it, so the manifest schema accepts it.
+ *
+ * Building is where the consequence is. A built site is what a real reader receives, and a page
+ * with nothing between its header and footer is not unfinished there, it is wrong. So the refusal
+ * that used to sit in the manifest schema, where it crashed `astro dev` at module load, sits here.
+ *
+ * It runs from `assertLabelPacksValid`, the `astro:build:start` hook every website already wires,
+ * so no application has to edit its Astro config for the gate to arm. It is exported on its own for
+ * any other build entry (an audit command, a custom integration).
+ *
+ * Every empty page is named in ONE error rather than the first only, for the reason the label
+ * validator aggregates its locales: one build run should surface everything that blocks it.
+ */
+export function assertWebsitePagesHaveSections(rootConfig: Pick<WebsiteRootConfig, 'pageManifests'>): void {
+  const emptyPageRefs = listWebsitePagesWithoutSections(rootConfig);
+  if (emptyPageRefs.length === 0) return;
+  throw new Error(
+    `[website-build] ${emptyPageRefs.length} page(s) declare no section and cannot be built: ${emptyPageRefs.map((ref) => `"${ref}"`).join(', ')}. `
+      + 'A page with no section is a valid state while it is being authored (a dev server serves it), never one to publish. '
+      + 'Add at least one section to each page\'s sections list, or remove the page from the root config\'s page manifests.',
+  );
+}

package/src/astro/label-pack-loader.ts

@@ -16,6 +16,7 @@ import {
 } from '../schemas/validators/label-pack.validator';
 
 import type { WebsiteSiteContext } from './website-site-context';
+import { assertWebsitePagesHaveSections } from './assert-website-pages-have-sections';
 
 /**
  * @wildo_source:part:start saas.website.astro.label-loader facet:layer:astro facet:family:website
@@ -241,6 +242,12 @@ function composeEffectiveChromeLabelKeys(
  * `loadAndValidateAllLabelPacks` is what `wildo website audit` calls
  * when it wants programmatic access to the per-locale results.
  *
+ * **Empty pages**: it first refuses a page whose `sectionRefs` is empty
+ * (`assertWebsitePagesHaveSections`, #2205). That refusal used to live in
+ * the manifest schema, where it crashed `astro dev` too; this hook runs
+ * only at `astro:build:start`, which is where a page with nothing on it
+ * stops being unfinished and starts being wrong.
+ *
  * **Key-origin annotation**: every `missing` key is tagged with the
  * page (and, if section-scoped, the section) that declared it, so the
  * author can grep + open the right `defineWebsiteSection` /
@@ -252,6 +259,9 @@ export function assertLabelPacksValid(
   expectedKeysBySectionRef: ExpectedLabelKeysBySectionRef,
 ): void {
   const { rootConfig } = siteContext;
+  // The build-start hook every website wires, so the empty-page refusal arms with no config edit
+  // (#2205). First, because a page with no section has no label commitments to validate.
+  assertWebsitePagesHaveSections(rootConfig);
   const validations = loadAndValidateAllLabelPacks(
     packsDir,
     siteContext,

package/src/astro.ts

@@ -70,6 +70,7 @@ export * from './astro/website-site-context';
 export * from './astro/i18n-routing.helper';
 export * from './astro/collect-expected-label-keys';
 export * from './astro/label-pack-loader';
+export * from './astro/assert-website-pages-have-sections';
 /**
  * `pick-labels-for-page` is INTENTIONALLY NOT re-exported here.
  * It is an internal helper consumed only by `loadWebsitePageRuntime`

package/src/core/__tests__/WebsitePageSections.test.tsx

@@ -0,0 +1,57 @@
+import React from 'react';
+import { describe, expect, it } from 'vitest';
+import { render } from '@testing-library/react';
+import '@testing-library/jest-dom';
+
+import { WebsitePageSections } from '../layouts/WebsitePageSections';
+import { defineWebsiteSection } from '../factories/define-website-section';
+import { WebsiteSectionCategory } from '../../schemas/sections/website-section-category.shared';
+import { WebsiteLabelKeySchema } from '../../schemas/label-keys/website-label-key.schemas';
+
+const HERO = defineWebsiteSection<Record<string, never>>({
+  sectionRef: 'home-hero',
+  category: WebsiteSectionCategory.HERO,
+  expectedLabelKeys: [WebsiteLabelKeySchema.parse('website.home.home-hero.headline')],
+  Component: () => <p>hero body</p>,
+});
+
+describe('WebsitePageSections', () => {
+  it('renders each section inside its WebsiteSection wrapper, in order', () => {
+    const { container, getByText } = render(<WebsitePageSections pageRef="home" sections={[HERO]} />);
+    expect(container.querySelector('section[data-section-ref="home-hero"]')).not.toBeNull();
+    expect(getByText('hero body')).toBeInTheDocument();
+    expect(container.querySelector('[data-website-pending-page]')).toBeNull();
+  });
+
+  it('gives a section its declared anchorId as the DOM id, so an in-page link has a target', () => {
+    const tiers = defineWebsiteSection<Record<string, never>>({
+      sectionRef: 'pricing-tiers',
+      category: WebsiteSectionCategory.PRICING,
+      expectedLabelKeys: [WebsiteLabelKeySchema.parse('website.pricing.pricing-tiers.heading')],
+      anchorId: 'tiers',
+      Component: () => <p>tiers</p>,
+    });
+    const { container } = render(<WebsitePageSections pageRef="pricing" sections={[tiers, HERO]} />);
+    expect(container.querySelector('section#tiers')?.getAttribute('data-section-ref')).toBe('pricing-tiers');
+    expect(container.querySelector('section[data-section-ref="home-hero"]')?.hasAttribute('id')).toBe(false);
+  });
+
+  it('refuses an anchorId that is not a fragment-safe HTML id', () => {
+    expect(() => defineWebsiteSection<Record<string, never>>({
+      sectionRef: 'pricing-tiers',
+      category: WebsiteSectionCategory.PRICING,
+      expectedLabelKeys: [],
+      anchorId: 'two words',
+      Component: () => null,
+    })).toThrow(/anchorId must start with a letter/);
+  });
+
+  it('renders a VISIBLE pending marker for a page whose sections are not authored yet (#2205)', () => {
+    // Mapped by hand, an empty list renders nothing, which looks exactly like a page that failed.
+    const { container } = render(<WebsitePageSections pageRef="home" sections={[]} />);
+    const marker = container.querySelector('[data-website-pending-page="home"]');
+    expect(marker).not.toBeNull();
+    expect(marker).toHaveAttribute('aria-busy', 'true');
+    expect(marker).toHaveTextContent('home: sections = []');
+  });
+});

package/src/core/factories/define-website-section.ts

@@ -27,6 +27,8 @@ export interface DefineWebsiteSectionInput<TProps> {
   sectionRef: WebsiteSectionRef | string;
   category: WebsiteSectionCategory;
   expectedLabelKeys: readonly (WebsiteLabelKey | string)[];
+  /** The section's DOM id, so a link can target it (`<a href="#tiers">`). See `WebsiteSectionDefinition.anchorId`. */
+  anchorId?: string;
   Component: ComponentType<TProps>;
   /**
    * See `WebsiteSectionDefinition.getStructuredData?` JSDoc for the
@@ -109,6 +111,7 @@ export function defineWebsiteSection<TProps>(
     sectionRef: input.sectionRef,
     category: input.category,
     expectedLabelKeys: input.expectedLabelKeys,
+    anchorId: input.anchorId,
     Component: input.Component,
     getStructuredData: input.getStructuredData,
   });
@@ -121,6 +124,7 @@ export function defineWebsiteSection<TProps>(
     sectionRef: parsed.sectionRef,
     category: parsed.category,
     expectedLabelKeys: parsed.expectedLabelKeys,
+    ...(parsed.anchorId !== undefined ? { anchorId: parsed.anchorId } : {}),
     Component: input.Component,
     ...(input.getStructuredData ? { getStructuredData: input.getStructuredData } : {}),
   };

package/src/core/layouts/WebsitePageSections.tsx

@@ -0,0 +1,68 @@
+import React, { type ReactNode } from 'react';
+
+import type { WebsiteSectionDefinition } from '../../schemas/sections/website-section-definition.shared.schemas';
+import { WebsiteSection } from './WebsiteSection';
+
+/**
+ * @wildo_source:part:start saas.website.page-sections.component facet:layer:core facet:family:website
+ *
+ * `WebsitePageSections` — renders a page's ordered sections list, each inside its `WebsiteSection`
+ * wrapper, and a visible PENDING marker while the list is still empty.
+ *
+ * A page component should render its sections through this rather than mapping the list by hand:
+ *
+ * ```tsx
+ * export function PricingPage(): ReactNode {
+ *   return <WebsitePageSections pageRef="pricing" sections={PRICING_SECTIONS} />;
+ * }
+ * ```
+ *
+ * **Why the empty state is the point.** A page's sections list starts EMPTY when its page
+ * is authored before its sections — the application-creation build lane does exactly that, one task
+ * per page and one per section. An empty page is a valid manifest and a dev server serves it; the
+ * production build refuses it (`assertWebsitePagesHaveSections`). Mapped by hand, an empty list
+ * renders nothing at all, which is indistinguishable from a page that failed. This renders a
+ * marked block instead, so the page visibly says its sections are still to come.
+ *
+ * A section's `anchorId`, declared on its definition, becomes the wrapper's DOM `id`, so in-page links
+ * still have a target when no page places its sections by hand.
+ *
+ * **The marker carries identifiers, not prose.** It shows the page ref and the empty list as code,
+ * deliberately: words a person reads come from the label packs, and a label for a state no built
+ * page can ever reach (the build refuses an empty page) would be a key every locale must carry for
+ * nothing. A missing section must LOOK missing, which a raw identifier does.
+ */
+export interface WebsitePageSectionsProps {
+  /** The page's ref, as its manifest declares it. Shown in the pending marker. */
+  pageRef: string;
+  /** The page's ordered sections list — the same array its manifest's `sectionRefs` derive from. */
+  sections: readonly WebsiteSectionDefinition[];
+}
+
+export function WebsitePageSections({ pageRef, sections }: WebsitePageSectionsProps): ReactNode {
+  if (sections.length === 0) {
+    return (
+      <section
+        data-website-pending-page={pageRef}
+        aria-busy="true"
+        style={{ margin: '2rem auto', maxWidth: '48rem', padding: '2rem', border: '2px dashed currentColor', opacity: 0.6, textAlign: 'center' }}
+      >
+        <code>{`${pageRef}: sections = []`}</code>
+      </section>
+    );
+  }
+  return (
+    <>
+      {sections.map((section) => {
+        const SectionComponent = section.Component as React.ComponentType;
+        return (
+          <WebsiteSection key={String(section.sectionRef)} sectionRef={section.sectionRef} category={section.category} id={section.anchorId}>
+            <SectionComponent />
+          </WebsiteSection>
+        );
+      })}
+    </>
+  );
+}
+WebsitePageSections.displayName = 'WebsitePageSections';
+/** @wildo_source:part:end saas.website.page-sections.component */

package/src/index.ts

@@ -78,6 +78,7 @@ export * from './core/factories/define-website-section';
 export * from './core/factories/define-website-page-manifest';
 export * from './core/layouts/WebsitePageLayout';
 export * from './core/layouts/WebsiteSection';
+export * from './core/layouts/WebsitePageSections';
 
 export * from './core/consent/website-consent-storage';
 export * from './core/consent/WebsiteConsentContext';

package/src/schemas/__tests__/page-manifest.test.ts

@@ -55,12 +55,9 @@ describe('WebsitePageManifestSchema', () => {
     ).toThrow(/must be rooted under the page ref/);
   });
 
-  it('rejects empty section ref lists', () => {
-    expect(() =>
-      WebsitePageManifestSchema.parse({
-        ...VALID_MANIFEST_INPUT,
-        sectionRefs: [],
-      }),
-    ).toThrow();
+  it('accepts an EMPTY section ref list: a page whose sections are not authored yet (#2205)', () => {
+    // The build lane writes the empty list before any section task runs. Refusing it here crashed
+    // `astro dev` at module load; the refusal now belongs to the build (assertWebsitePagesHaveSections).
+    expect(WebsitePageManifestSchema.parse({ ...VALID_MANIFEST_INPUT, sectionRefs: [] }).sectionRefs).toEqual([]);
   });
 });

package/src/schemas/manifests/website-page-manifest.shared.schemas.ts

@@ -141,6 +141,8 @@ export type WebsitePageRoutePath = z.infer<typeof _WebsitePageRoutePathSchema>;
  *   not match the directive in its `.astro` file.
  *
  * **Refinements**:
+ *   - `sectionRefs` MAY be empty — a page whose sections are still being authored. It may be
+ *     served by a dev server and may not be built: see `assertWebsitePagesHaveSections`.
  *   - `sectionRefs` MUST contain unique values. Duplicates indicate
  *     either a copy-paste bug (two sections pointing at the same
  *     label-key root) or an intent to share a label-key root that
@@ -203,9 +205,16 @@ const _WebsitePageManifestSchema = z
     ref: WebsitePageRefSchema,
     routePath: _WebsitePageRoutePathSchema,
     pageComponent: z.unknown(),
-    sectionRefs: z.array(WebsiteSectionRefSchema).min(1, {
-      error: 'A page manifest must declare at least one sectionRef',
-    }),
+    /*
+     * EMPTY is a valid manifest (#2205): a page whose sections are not authored YET. The build lane
+     * creates that state on purpose (the page task writes the empty list, then each section task
+     * appends itself), and refusing it here made `astro dev` crash at module load until every page
+     * of the site had a section. An empty page is unfinished, not false, so it is representable and
+     * a dev server renders it (`WebsitePageSections` shows the pending state). What is refused is
+     * BUILDING one: `assertWebsitePagesHaveSections`, run from the build-start hook, because a
+     * published page with nothing on it is a statement to a real reader.
+     */
+    sectionRefs: z.array(WebsiteSectionRefSchema),
     metaLabelKeys: _WebsitePageMetaLabelKeysSchema,
     hydration: WebsitePageHydrationStrategySchema.optional(),
     seo: _WebsitePageSeoConfigSchema.optional(),

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

@@ -46,6 +46,14 @@ import { WebsiteSectionCategorySchema } from './website-section-category.shared'
  *        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.
+ * - `anchorId?` — the section's DOM id, so a link (`<a href="#tiers">`)
+ *   can target it. Belongs to the DEFINITION because a page renders its
+ *   sections list through `WebsitePageSections`, which places every
+ *   section itself: an anchor a page author would otherwise write on a
+ *   hand-placed `<WebsiteSection id=…>` has nowhere else to live. A
+ *   valid HTML id that is also URL-fragment-safe: a letter, then
+ *   letters, digits, `-` or `_`. Uniqueness on a page is the author's
+ *   to keep, like the id attribute it becomes.
  * - `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
@@ -72,6 +80,9 @@ const _WebsiteSectionDefinitionSchema = z.object({
   sectionRef: WebsiteSectionRefSchema,
   category: WebsiteSectionCategorySchema,
   expectedLabelKeys: z.array(WebsiteLabelKeySchema).readonly(),
+  anchorId: z.string().regex(/^[A-Za-z][A-Za-z0-9_-]*$/, {
+    error: 'A section anchorId must start with a letter and contain only letters, digits, "-" or "_"',
+  }).optional(),
   Component: z.unknown(),
   getStructuredData: z.unknown().optional(),
 });