@wildo-ai/saas-website 1.1.1

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

@@ -0,0 +1,133 @@
+import React from 'react';
+import { describe, expect, it, vi, afterEach } from 'vitest';
+import { render, renderHook } from '@testing-library/react';
+import '@testing-library/jest-dom';
+
+import {
+  WebsiteRuntimeContextProvider,
+  type WebsiteRuntimeContextValue,
+} from '../contexts/WebsiteRuntimeContext';
+import { useWebsiteRuntime } from '../contexts/useWebsiteRuntime';
+import { WebsitePageContextProvider } from '../contexts/WebsitePageContext';
+import { useWebsitePage } from '../contexts/useWebsitePage';
+import { WebsiteSectionContextProvider } from '../contexts/WebsiteSectionContext';
+import { useWebsiteSection } from '../contexts/useWebsiteSection';
+import { WebsiteSectionCategory } from '../../schemas/sections/website-section-category.shared';
+import { WebsitePageRefSchema } from '../../schemas/refs/page-ref.schemas';
+import { WebsiteSectionRefSchema } from '../../schemas/refs/section-ref.schemas';
+import { WebsiteLabelKeySchema } from '../../schemas/label-keys/website-label-key.schemas';
+import { AvailableLanguage } from '@wildo-ai/saas-models/public-runtime';
+
+const NoopHeader = () => <span data-testid="header" />;
+const NoopFooter = () => <span data-testid="footer" />;
+
+const RUNTIME_FIXTURE: WebsiteRuntimeContextValue = {
+  locale: AvailableLanguage.EN,
+  defaultLocale: AvailableLanguage.EN,
+  labelPack: { 'website.landing.hero.headline': 'Hello' },
+  skipToMainContentLabelKey: WebsiteLabelKeySchema.parse('website.chrome.layout.skip-to-main-content'),
+  designTokens: {
+    colors: {
+      background: '#fff',
+      foreground: '#000',
+      primary: '#000',
+      primaryForeground: '#fff',
+      accent: '#000',
+      accentForeground: '#fff',
+      surface: '#fff',
+      surfaceForeground: '#000',
+      border: '#ccc',
+      muted: '#eee',
+      mutedForeground: '#666',
+    },
+    radii: { none: '0', sm: '2px', md: '4px', lg: '8px', xl: '12px', full: '9999px' },
+  },
+  navigation: {
+    headerComponent: NoopHeader,
+    footerComponent: NoopFooter,
+  },
+};
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('WebsiteRuntimeContext', () => {
+  it('provides the runtime value through the provider component', () => {
+    const { result } = renderHook(() => useWebsiteRuntime(), {
+      wrapper: ({ children }) => (
+        <WebsiteRuntimeContextProvider value={RUNTIME_FIXTURE}>
+          {children}
+        </WebsiteRuntimeContextProvider>
+      ),
+    });
+    expect(result.current).toBe(RUNTIME_FIXTURE);
+  });
+
+  it('throws with a clear message when used outside the provider', () => {
+    /**
+     * Suppress the React error-boundary logging — the throw is the
+     * test's expected outcome.
+     */
+    vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    expect(() => renderHook(() => useWebsiteRuntime())).toThrowError(
+      /must be called inside <WebsiteRuntimeContextProvider>/,
+    );
+  });
+});
+
+describe('WebsitePageContext', () => {
+  it('provides the page ref through the provider component', () => {
+    const pageRef = WebsitePageRefSchema.parse('landing');
+    const { result } = renderHook(() => useWebsitePage(), {
+      wrapper: ({ children }) => (
+        <WebsitePageContextProvider value={{ pageRef }}>
+          {children}
+        </WebsitePageContextProvider>
+      ),
+    });
+    expect(result.current.pageRef).toBe(pageRef);
+  });
+
+  it('throws when used outside <WebsitePageLayout>', () => {
+    vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    expect(() => renderHook(() => useWebsitePage())).toThrowError(
+      /must be called inside <WebsitePageLayout>/,
+    );
+  });
+});
+
+describe('WebsiteSectionContext', () => {
+  it('provides the section ref + category through the provider component', () => {
+    const sectionRef = WebsiteSectionRefSchema.parse('hero');
+    const { result } = renderHook(() => useWebsiteSection(), {
+      wrapper: ({ children }) => (
+        <WebsiteSectionContextProvider
+          value={{ sectionRef, category: WebsiteSectionCategory.HERO }}
+        >
+          {children}
+        </WebsiteSectionContextProvider>
+      ),
+    });
+    expect(result.current.sectionRef).toBe(sectionRef);
+    expect(result.current.category).toBe(WebsiteSectionCategory.HERO);
+  });
+
+  it('throws when used outside <WebsiteSection>', () => {
+    vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    expect(() => renderHook(() => useWebsiteSection())).toThrowError(
+      /must be called inside <WebsiteSection>/,
+    );
+  });
+});
+
+describe('Provider component renders children', () => {
+  it('WebsiteRuntimeContextProvider passes children through', () => {
+    const { getByTestId } = render(
+      <WebsiteRuntimeContextProvider value={RUNTIME_FIXTURE}>
+        <div data-testid="child" />
+      </WebsiteRuntimeContextProvider>,
+    );
+    expect(getByTestId('child')).toBeInTheDocument();
+  });
+});

package/src/core/__tests__/core-boundary.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest';
+import { readFileSync, readdirSync, statSync } from 'fs';
+import { join, resolve } from 'path';
+
+/**
+ * Boundary test for the `core/` and `components/` directories.
+ *
+ * Per `engine/saas-website/src/index.ts` `@wildo-boundary` block:
+ *   - `core/`       : MAY use React; MUST NOT import `~wildo-frontend-lib/**`
+ *                     or `@wildo-ai/saas-frontend-lib`
+ *   - `components/` : same rules as `core/` (D18 — L1 primitives are
+ *                     self-contained placeholders, not re-exports of
+ *                     `saas-frontend-lib`)
+ *
+ * The constraint exists because `saas-website` does NOT depend on
+ * `saas-frontend-lib` (per `package.json`) — the marketing-site engine
+ * is a parallel surface to the SaaS app frontend. Phase 6 dogfood will
+ * decide whether to promote the L1 primitives to a shared
+ * `ComponentRegistryService` registry; until then this boundary is
+ * load-bearing.
+ *
+ * **Implementation**: AST parsing would be ideal but is overkill for a
+ * static-import grep. We scan source files (excluding `__tests__`) and
+ * fail the test if any forbidden import path appears.
+ */
+
+const ROOT = resolve(__dirname, '../..');
+const SCAN_DIRS = ['core', 'components'];
+const FORBIDDEN_PATTERNS: readonly RegExp[] = [
+  /from\s+['"]~wildo-frontend-lib(?:\/[^'"]*)?['"]/,
+  /from\s+['"]@wildo-ai\/saas-frontend-lib(?:\/[^'"]*)?['"]/,
+  /import\s*\(\s*['"]~wildo-frontend-lib(?:\/[^'"]*)?['"]\s*\)/,
+  /import\s*\(\s*['"]@wildo-ai\/saas-frontend-lib(?:\/[^'"]*)?['"]\s*\)/,
+];
+
+function* walk(dir: string): Generator<string> {
+  for (const entry of readdirSync(dir)) {
+    if (entry === '__tests__') continue;
+    const full = join(dir, entry);
+    const s = statSync(full);
+    if (s.isDirectory()) {
+      yield* walk(full);
+    } else if (entry.endsWith('.ts') || entry.endsWith('.tsx')) {
+      yield full;
+    }
+  }
+}
+
+function findViolations(): { file: string; pattern: string; line: string }[] {
+  const violations: { file: string; pattern: string; line: string }[] = [];
+  for (const dirName of SCAN_DIRS) {
+    const dir = join(ROOT, dirName);
+    for (const file of walk(dir)) {
+      const content = readFileSync(file, 'utf8');
+      const lines = content.split('\n');
+      for (const [lineIdx, line] of lines.entries()) {
+        for (const pattern of FORBIDDEN_PATTERNS) {
+          if (pattern.test(line)) {
+            violations.push({
+              file: file.replace(ROOT + '/', ''),
+              pattern: pattern.source,
+              line: `${lineIdx + 1}: ${line.trim()}`,
+            });
+          }
+        }
+      }
+    }
+  }
+  return violations;
+}
+
+describe('core/ + components/ boundary (D18)', () => {
+  it('does not import from ~wildo-frontend-lib or @wildo-ai/saas-frontend-lib', () => {
+    const violations = findViolations();
+    if (violations.length > 0) {
+      const report = violations
+        .map((v) => `  ${v.file} (matched /${v.pattern}/)\n    ${v.line}`)
+        .join('\n');
+      throw new Error(
+        `Boundary violations detected — saas-website MUST NOT depend on saas-frontend-lib (D18):\n${report}`,
+      );
+    }
+    expect(violations).toEqual([]);
+  });
+});

package/src/core/__tests__/define-website-page-manifest.test.tsx

@@ -0,0 +1,111 @@
+import React from 'react';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import { defineWebsitePageManifest } from '../factories/define-website-page-manifest';
+import { WebsiteLabelKeySchema } from '../../schemas/label-keys/website-label-key.schemas';
+import { WebsitePageHydrationStrategy } from '../../schemas/manifests/website-page-manifest.shared.schemas';
+
+interface BlogPostPageProps {
+  slug: string;
+}
+
+function BlogPostPage({ slug }: BlogPostPageProps): React.ReactElement {
+  return <div data-testid="blog">{slug}</div>;
+}
+
+const TITLE_KEY = WebsiteLabelKeySchema.parse('website.landing.meta.title');
+const DESCRIPTION_KEY = WebsiteLabelKeySchema.parse('website.landing.meta.description');
+
+describe('defineWebsitePageManifest', () => {
+  it('produces a manifest that round-trips through the schema', () => {
+    const manifest = defineWebsitePageManifest({
+      ref: 'landing',
+      routePath: '/',
+      pageComponent: () => null,
+      sectionRefs: ['hero', 'cta'],
+      metaLabelKeys: { titleKey: TITLE_KEY, descriptionKey: DESCRIPTION_KEY },
+    });
+
+    expect(manifest.ref as unknown as string).toBe('landing');
+    expect(manifest.routePath as unknown as string).toBe('/');
+    expect(manifest.sectionRefs.map((r) => r as unknown as string)).toEqual(['hero', 'cta']);
+    expect(manifest.metaLabelKeys.titleKey).toBe(TITLE_KEY);
+  });
+
+  it('preserves the precise pageComponent prop type via the generic', () => {
+    const manifest = defineWebsitePageManifest<BlogPostPageProps>({
+      ref: 'blog-post',
+      routePath: '/blog/[slug]',
+      pageComponent: BlogPostPage,
+      sectionRefs: ['post-body'],
+      metaLabelKeys: {
+        titleKey: WebsiteLabelKeySchema.parse('website.blog-post.meta.title'),
+        descriptionKey: WebsiteLabelKeySchema.parse('website.blog-post.meta.description'),
+      },
+    });
+
+    expectTypeOf(manifest.pageComponent).toEqualTypeOf<
+      React.ComponentType<BlogPostPageProps>
+    >();
+  });
+
+  it('rejects duplicate sectionRefs (schema superRefine)', () => {
+    expect(() =>
+      defineWebsitePageManifest({
+        ref: 'landing',
+        routePath: '/',
+        pageComponent: () => null,
+        sectionRefs: ['hero', 'hero'],
+        metaLabelKeys: { titleKey: TITLE_KEY, descriptionKey: DESCRIPTION_KEY },
+      }),
+    ).toThrowError(/Duplicate sectionRef/);
+  });
+
+  it('rejects metaLabelKeys not rooted under the page ref', () => {
+    expect(() =>
+      defineWebsitePageManifest({
+        ref: 'pricing',
+        routePath: '/pricing',
+        pageComponent: () => null,
+        sectionRefs: ['tiers'],
+        /**
+         * `landing` keys under a `pricing` page — the schema's
+         * `superRefine` enforces the page-prefix discipline.
+         */
+        metaLabelKeys: { titleKey: TITLE_KEY, descriptionKey: DESCRIPTION_KEY },
+      }),
+    ).toThrowError(/must be rooted under the page ref/);
+  });
+
+  it('preserves the optional hydration field', () => {
+    const manifest = defineWebsitePageManifest({
+      ref: 'contact',
+      routePath: '/contact',
+      pageComponent: () => null,
+      sectionRefs: ['form'],
+      metaLabelKeys: {
+        titleKey: WebsiteLabelKeySchema.parse('website.contact.meta.title'),
+        descriptionKey: WebsiteLabelKeySchema.parse('website.contact.meta.description'),
+      },
+      hydration: WebsitePageHydrationStrategy.EAGER,
+    });
+    expect(manifest.hydration).toBe(WebsitePageHydrationStrategy.EAGER);
+  });
+
+  it('preserves the optional seo field', () => {
+    const manifest = defineWebsitePageManifest({
+      ref: 'pricing',
+      routePath: '/pricing',
+      pageComponent: () => null,
+      sectionRefs: ['tiers'],
+      metaLabelKeys: {
+        titleKey: WebsiteLabelKeySchema.parse('website.pricing.meta.title'),
+        descriptionKey: WebsiteLabelKeySchema.parse('website.pricing.meta.description'),
+      },
+      seo: {
+        noaiOptOut: true,
+      },
+    });
+    expect(manifest.seo?.noaiOptOut).toBe(true);
+  });
+});

package/src/core/__tests__/define-website-section.test.tsx

@@ -0,0 +1,89 @@
+import React from 'react';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import {
+  defineWebsiteSection,
+  type TypedWebsiteSectionDefinition,
+} from '../factories/define-website-section';
+import { WebsiteSectionCategory } from '../../schemas/sections/website-section-category.shared';
+
+interface HeroProps {
+  headlineKey: string;
+  subheadlineKey: string;
+}
+
+function HeroSection({ headlineKey }: HeroProps): React.ReactElement {
+  return <h1 data-testid="hero">{headlineKey}</h1>;
+}
+
+describe('defineWebsiteSection', () => {
+  it('produces a definition that round-trips through the schema', () => {
+    const def = defineWebsiteSection<HeroProps>({
+      sectionRef: 'hero',
+      category: WebsiteSectionCategory.HERO,
+      expectedLabelKeys: [
+        'website.landing.hero.headline',
+        'website.landing.hero.subheadline',
+      ],
+      Component: HeroSection,
+    });
+
+    expect(def.sectionRef as unknown as string).toBe('hero');
+    expect(def.category).toBe(WebsiteSectionCategory.HERO);
+    expect(def.expectedLabelKeys).toHaveLength(2);
+    expect(def.Component).toBe(HeroSection);
+  });
+
+  it('preserves the precise component prop type via the generic', () => {
+    const def = defineWebsiteSection<HeroProps>({
+      sectionRef: 'hero',
+      category: WebsiteSectionCategory.HERO,
+      expectedLabelKeys: ['website.landing.hero.headline'],
+      Component: HeroSection,
+    });
+
+    /**
+     * Compile-time check: the returned `Component` must accept HeroProps,
+     * not the lowest-common-denominator `ComponentType<unknown>` that the
+     * schema-inferred type carries.
+     */
+    expectTypeOf(def.Component).toEqualTypeOf<React.ComponentType<HeroProps>>();
+    expectTypeOf<TypedWebsiteSectionDefinition<HeroProps>['Component']>().toEqualTypeOf<
+      React.ComponentType<HeroProps>
+    >();
+  });
+
+  it('validates malformed sectionRef at module-load time (parse-time fail-loud)', () => {
+    expect(() =>
+      defineWebsiteSection<Record<string, never>>({
+        sectionRef: 'INVALID UPPERCASE WITH SPACES',
+        category: WebsiteSectionCategory.HERO,
+        expectedLabelKeys: [],
+        Component: () => null,
+      }),
+    ).toThrowError(/WebsiteSectionRef/);
+  });
+
+  it('validates malformed expected label keys', () => {
+    expect(() =>
+      defineWebsiteSection<Record<string, never>>({
+        sectionRef: 'hero',
+        category: WebsiteSectionCategory.HERO,
+        expectedLabelKeys: ['not-a-valid-website-label-key'],
+        Component: () => null,
+      }),
+    ).toThrowError(/WebsiteLabelKey/);
+  });
+
+  it('preserves an optional getStructuredData hook', () => {
+    const getStructuredData = () => ({ '@type': 'Organization' });
+    const def = defineWebsiteSection<Record<string, never>>({
+      sectionRef: 'hero',
+      category: WebsiteSectionCategory.HERO,
+      expectedLabelKeys: ['website.landing.hero.headline'],
+      Component: () => null,
+      getStructuredData,
+    });
+    expect(def.getStructuredData).toBe(getStructuredData);
+  });
+});

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

@@ -0,0 +1,41 @@
+import React from 'react';
+import { describe, expect, it } from 'vitest';
+import { renderHook } from '@testing-library/react';
+
+import {
+  WebsiteRuntimeContextProvider,
+  type WebsiteRuntimeContextValue,
+} from '../contexts/WebsiteRuntimeContext';
+import { useWebsiteDesignTokens } from '../hooks/useWebsiteDesignTokens';
+import { WebsiteLabelKeySchema } from '../../schemas/label-keys/website-label-key.schemas';
+import { AvailableLanguage } from '@wildo-ai/saas-models/public-runtime';
+
+const TOKENS = {
+  colors: {
+    background: '#fff', foreground: '#000', primary: '#000',
+    primaryForeground: '#fff', accent: '#000', accentForeground: '#fff',
+    surface: '#fff', surfaceForeground: '#000', border: '#ccc',
+    muted: '#eee', mutedForeground: '#666',
+  },
+  radii: { none: '0', sm: '2px', md: '4px', lg: '8px', xl: '12px', full: '9999px' },
+};
+
+const RUNTIME: WebsiteRuntimeContextValue = {
+  locale: AvailableLanguage.EN,
+  defaultLocale: AvailableLanguage.EN,
+  labelPack: {},
+  designTokens: TOKENS,
+  navigation: { headerComponent: () => null, footerComponent: () => null },
+  skipToMainContentLabelKey: WebsiteLabelKeySchema.parse('website.chrome.layout.skip-to-main-content'),
+};
+
+describe('useWebsiteDesignTokens', () => {
+  it('returns the runtime context design tokens by reference', () => {
+    const { result } = renderHook(() => useWebsiteDesignTokens(), {
+      wrapper: ({ children }) => (
+        <WebsiteRuntimeContextProvider value={RUNTIME}>{children}</WebsiteRuntimeContextProvider>
+      ),
+    });
+    expect(result.current).toBe(TOKENS);
+  });
+});

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

@@ -0,0 +1,117 @@
+import React from 'react';
+import { describe, expect, it, vi, afterEach } from 'vitest';
+import { renderHook } from '@testing-library/react';
+
+import {
+  WebsiteRuntimeContextProvider,
+  type WebsiteRuntimeContextValue,
+} from '../contexts/WebsiteRuntimeContext';
+import { WebsitePageContextProvider } from '../contexts/WebsitePageContext';
+import { WebsiteSectionContextProvider } from '../contexts/WebsiteSectionContext';
+import { useWebsiteLabel, useWebsiteLabelByKey } from '../hooks/useWebsiteLabel';
+import { WebsitePageRefSchema } from '../../schemas/refs/page-ref.schemas';
+import { WebsiteSectionRefSchema } from '../../schemas/refs/section-ref.schemas';
+import { WebsiteSectionCategory } from '../../schemas/sections/website-section-category.shared';
+import { WebsiteLabelKeySchema } from '../../schemas/label-keys/website-label-key.schemas';
+import { AvailableLanguage } from '@wildo-ai/saas-models/public-runtime';
+
+const RUNTIME: WebsiteRuntimeContextValue = {
+  locale: AvailableLanguage.EN,
+  defaultLocale: AvailableLanguage.EN,
+  labelPack: {
+    'website.landing.hero.headline': 'Welcome to Wonder Todos',
+    'website.landing.hero.cta.primary': 'Get started',
+  },
+  designTokens: {
+    colors: {
+      background: '#fff', foreground: '#000', primary: '#000',
+      primaryForeground: '#fff', accent: '#000', accentForeground: '#fff',
+      surface: '#fff', surfaceForeground: '#000', border: '#ccc',
+      muted: '#eee', mutedForeground: '#666',
+    },
+    radii: { none: '0', sm: '2px', md: '4px', lg: '8px', xl: '12px', full: '9999px' },
+  },
+  navigation: {
+    headerComponent: () => null,
+    footerComponent: () => null,
+  },
+  skipToMainContentLabelKey: WebsiteLabelKeySchema.parse('website.chrome.layout.skip-to-main-content'),
+};
+
+const wrap =
+  (pageRef: string, sectionRef: string) =>
+  ({ children }: { children: React.ReactNode }) => (
+    <WebsiteRuntimeContextProvider value={RUNTIME}>
+      <WebsitePageContextProvider value={{ pageRef: WebsitePageRefSchema.parse(pageRef) }}>
+        <WebsiteSectionContextProvider
+          value={{
+            sectionRef: WebsiteSectionRefSchema.parse(sectionRef),
+            category: WebsiteSectionCategory.HERO,
+          }}
+        >
+          {children}
+        </WebsiteSectionContextProvider>
+      </WebsitePageContextProvider>
+    </WebsiteRuntimeContextProvider>
+  );
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('useWebsiteLabel', () => {
+  it('composes leaf with page+section context and resolves the label', () => {
+    const { result } = renderHook(() => useWebsiteLabel('headline'), {
+      wrapper: wrap('landing', 'hero'),
+    });
+    expect(result.current).toBe('Welcome to Wonder Todos');
+  });
+
+  it('composes nested leaf paths (dot notation)', () => {
+    const { result } = renderHook(() => useWebsiteLabel('cta.primary'), {
+      wrapper: wrap('landing', 'hero'),
+    });
+    expect(result.current).toBe('Get started');
+  });
+
+  it('returns the composed key + warns when the pack lacks the entry', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    const { result } = renderHook(() => useWebsiteLabel('missing-leaf'), {
+      wrapper: wrap('landing', 'hero'),
+    });
+    expect(result.current).toBe('website.landing.hero.missing-leaf');
+    expect(warn).toHaveBeenCalledOnce();
+    expect(warn.mock.calls[0]?.[0]).toMatch(/Missing label for key "website\.landing\.hero\.missing-leaf"/);
+  });
+
+  it('throws when invoked outside any of the three required contexts', () => {
+    vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    expect(() => renderHook(() => useWebsiteLabel('headline'))).toThrowError(
+      /must be called inside <WebsiteRuntimeContextProvider>/,
+    );
+  });
+});
+
+describe('useWebsiteLabelByKey', () => {
+  it('looks up a fully-composed key', () => {
+    const key = WebsiteLabelKeySchema.parse('website.landing.hero.headline');
+    const { result } = renderHook(() => useWebsiteLabelByKey(key), {
+      wrapper: ({ children }) => (
+        <WebsiteRuntimeContextProvider value={RUNTIME}>{children}</WebsiteRuntimeContextProvider>
+      ),
+    });
+    expect(result.current).toBe('Welcome to Wonder Todos');
+  });
+
+  it('returns the key + warns on miss', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    const key = WebsiteLabelKeySchema.parse('website.landing.hero.missing');
+    const { result } = renderHook(() => useWebsiteLabelByKey(key), {
+      wrapper: ({ children }) => (
+        <WebsiteRuntimeContextProvider value={RUNTIME}>{children}</WebsiteRuntimeContextProvider>
+      ),
+    });
+    expect(result.current).toBe('website.landing.hero.missing');
+    expect(warn).toHaveBeenCalledOnce();
+  });
+});