@wildo-ai/saas-website 1.1.1

package/src/astro.ts

@@ -0,0 +1,151 @@
+/**
+ * @wildo-package @wildo-ai/saas-website (astro adapter SSR/frontmatter entry)
+ *
+ * Astro **frontmatter / SSR** sub-entry. Re-exports the TypeScript
+ * helpers a consumer's per-page `.astro` files consume INSIDE
+ * frontmatter to render a marketing-site page (locale resolution,
+ * label-pack loading, `<head>` HTML rendering, design-token CSS
+ * rendering, i18n routing config, expected-label-key collection).
+ *
+ * **The `createWebsitePageBridgeIsland` factory lives in a SEPARATE
+ * subpath — `@wildo-ai/saas-website/astro-island`** — and is NOT
+ * re-exported here. The split exists because the consumer's per-page
+ * `*.bridge.tsx` module is bundled into BOTH the SSR graph (via the
+ * `.astro` page that statically imports it) AND the client graph
+ * (Astro's hydration pipeline). Re-exporting the bridge factory
+ * alongside the Node-using helpers here would force Vite to resolve
+ * `node:fs` / `node:path` for the client bundle even though
+ * tree-shaking would later drop them — resolution happens BEFORE
+ * tree-shaking, so the build hard-fails with
+ * `"resolve" is not exported by "__vite-browser-external"`. The
+ * dedicated `astro-island` subpath keeps the client import graph
+ * 100% bundle-clean.
+ *
+ * **No `.astro` shell shipped.** The Phase-5 redesign deliberately
+ * removed the previously-planned `WebsitePageBridge.astro` shell
+ * because:
+ *   1. A `.astro` file cannot be re-exported from a TS subpath barrel
+ *      and `tsc` does not copy non-TS files to `dist/`, so the shell
+ *      was unreachable from `@wildo-ai/saas-website/astro`.
+ *   2. The shell would have had to pass `pageComponent` /
+ *      `headerComponent` / `footerComponent` (`ComponentType` refs)
+ *      as React-island props — Astro's `devalue`-style island prop
+ *      serialization cannot transport function values, so hydration
+ *      would have mismatched on first interaction.
+ * Both failure modes are sidestepped by giving consumers two
+ * primitive-string-only TS helpers (`renderWebsitePageHeadHtml`,
+ * `renderWebsiteDesignTokensCss`) for the Astro-side `<head>` work
+ * and a closure-based island factory (`createWebsitePageBridgeIsland`,
+ * exported from `@wildo-ai/saas-website/astro-island`) for the
+ * React-island side. The consumer authors a thin per-page `.astro`
+ * file that statically imports the per-page bridge island — Astro's
+ * compiler then resolves the `client:*` directive against a static
+ * module export, which is the only pattern that makes Astro's
+ * hydration bundling work correctly. See `bridge-runtime.tsx`'s
+ * file-level JSDoc for the full rationale.
+ *
+ * @wildo-boundary
+ *   This entry is on the SSR / Astro-build-time side of the bundle
+ *   boundary (D12 second loosening). It MAY import:
+ *     - `node:fs`, `node:path` (label-pack-loader, runtime-helper)
+ *   It MUST NOT import:
+ *     - the bridge-runtime module — that module ships into the
+ *       client island bundle and is exposed via the
+ *       `@wildo-ai/saas-website/astro-island` subpath instead.
+ *     - the Astro runtime (`astro` package, `astro:*` virtual modules)
+ *       — those live exclusively inside `.astro` files. Adding
+ *       `astro` here would make the engine package unimportable
+ *       from any context that does not boot the Astro compiler
+ *       (Vitest tests, the `wildo website audit` CLI, companion
+ *       subprocesses).
+ *
+ *   Enforced by `engine/saas-website/src/__tests__/bundle-isolation.test.ts`
+ *   which walks `astro.ts` as one of `ENTRY_FILES` AND runs a targeted
+ *   negative test that `node:fs` / `node:path` are reachable from
+ *   `astro.ts` ONLY — never from `index.ts`, `companion-exports.ts`,
+ *   or `astro-island.ts`.
+ */
+
+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';
+/**
+ * `pick-labels-for-page` is INTENTIONALLY NOT re-exported here.
+ * It is an internal helper consumed only by `loadWebsitePageRuntime`
+ * (which IS exported via the runtime helper below). Exposing it as a
+ * public sub-entry surface would (a) invite consumers to call it
+ * directly from `.astro` frontmatter — which they should never do
+ * (the runtime helper already wires the slicing transparently), and
+ * (b) lock the engine into an extra public API the audit step would
+ * have to keep stable. Tests import the helper via its relative
+ * path, which keeps the behavior covered without leaking the surface.
+ * (Phase 6 audit fix M-B.)
+ */
+export * from './astro/website-page-runtime.helper';
+export * from './astro/website-page-head.renderer';
+export * from './astro/structured-data.renderer';
+/**
+ * Phase 7 — sibling head renderer for blog posts. Reads from a
+ * validated `BlogPostFrontmatter` instead of the page manifest's
+ * `metaLabelKeys`; emits `og:type=article` plus the
+ * `article:published_time` / `article:author` / `article:tag` lines
+ * the OG "article" vertical requires. See the renderer file's
+ * preamble for why this is a sibling rather than a flag on
+ * `renderWebsitePageHeadHtml`.
+ */
+export * from './astro/blog-post-head.renderer';
+/**
+ * Phase 8 close-out — `renderRobotsTxt(siteContext)` pure string
+ * builder for the marketing site's `robots.txt` body. Sibling of
+ * `renderWebsitePageHeadHtml` (same Astro-frontmatter consumption
+ * shape: pure TypeScript, no Astro runtime dependency, vitest-
+ * friendly). See `engine/saas-website/src/astro/robots-renderer.ts`
+ * for the field-by-field rationale and
+ * `.cursor/plans/saas-website-seo-sitemap.md` for the slice context.
+ */
+export * from './astro/robots-renderer';
+/**
+ * Phase 8 close-out — `enumerateMarketingPageSitemapUrls(siteContext)`
+ * pure helper that returns every (page-manifest × locale) absolute
+ * URL the marketing site's sitemap MUST advertise, paired with its
+ * hreflang alternates. Two consumption surfaces:
+ *
+ *   1. Vitest enforcement — a regression that drops a manifest-
+ *      registered route fails fast in unit tests, well before
+ *      `astro build` would surface it.
+ *   2. `@astrojs/sitemap` `customPages` integration — when the
+ *      consumer needs to surface routes Astro's file-based router
+ *      cannot auto-discover (data-driven landing variants, etc.),
+ *      this helper computes the canonical URL list to spread into
+ *      the plugin config.
+ *
+ * See `engine/saas-website/src/astro/sitemap-coverage.ts` and
+ * `.cursor/plans/saas-website-seo-sitemap.md` for the full
+ * rationale + scope boundary.
+ */
+export * from './astro/sitemap-coverage';
+/**
+ * AEO — `renderPageStructuredData(opts)` pure string builder that
+ * collects every section's `getStructuredData()` (when present),
+ * dedupes by `@id`, and emits one
+ * `<script type="application/ld+json">` block per surviving payload.
+ * Sibling of `renderWebsitePageHeadHtml` (same pure-TS, vitest-
+ * friendly contract). See
+ * `engine/saas-website/src/astro/structured-data.renderer.ts`
+ * for the safety + dedupe semantics and
+ * `.cursor/plans/saas-website-aeo-geo.md` for the slice context.
+ */
+export * from './astro/structured-data.renderer';
+export * from './astro/headers-renderer';
+export * from './astro/llms-txt-server';
+/**
+ * AEO — runtime payload type (`WebsiteStructuredDataPayload`) and
+ * convenience return-shape union (`WebsiteStructuredDataReturn`)
+ * the section author imports to type their `getStructuredData()`.
+ * Defined locally in `saas-website` (not in `saas-specifications`)
+ * because the runtime engine cannot depend on the spec layer; the
+ * companion catalog at `_catalogs/schema-org/` describes the same
+ * vocabulary at the COMPANION layer.
+ */
+export * from './schemas/structured-data/website-structured-data.shared.schemas';

package/src/companion-exports.ts

@@ -0,0 +1,38 @@
+/**
+ * @wildo-package @wildo-ai/saas-website (companion entry)
+ *
+ * Narrow, React-free entry point for non-React consumers:
+ *   - the `wildo-cli`'s page/sitemap/structured-data audit commands
+ *   - companion subprocesses (e.g. introspection of authored pages)
+ *   - CI scripts that validate label-pack coverage
+ *   - anything Astro-build-time that cannot pull React into the
+ *     evaluation graph
+ *
+ * Per `saas-website-slice.md` §"Note on `companion-exports.ts` scope
+ * expansion": the SEO builder library lives here too (it's pure
+ * string + JSON-LD generation, React-free by design).
+ *
+ * @wildo-boundary
+ *   This file MUST re-export ONLY from `schemas/**` and `seo/**`.
+ *   It MUST NOT import or re-export anything from:
+ *     - `core/**`         (React runtime contexts/hooks)
+ *     - `astro/**`        (Astro-only adapter)
+ *     - `mdx/**`          (MDX-only adapter)
+ *     - `integration/**`  (React-bearing integration code)
+ *   It MUST NOT import React, Astro, or `@mdx-js/*`.
+ *
+ *   Enforced by review until Phase 8 boundary lint design (see plan).
+ *
+ * Phase 1 status: schemas exposed; SEO builders land in Phase 2.5.
+ */
+
+export * from './schemas/refs/page-ref.schemas';
+export * from './schemas/refs/section-ref.schemas';
+export * from './schemas/label-keys/website-label-key.schemas';
+export * from './schemas/sections/website-section-category.shared';
+export * from './schemas/sections/website-section-definition.shared.schemas';
+export * from './schemas/design-tokens/website-design-tokens.shared.schemas';
+export * from './schemas/manifests/website-page-manifest.shared.schemas';
+export * from './schemas/manifests/website-root-config.shared.schemas';
+export * from './schemas/blog/blog-post-frontmatter.shared.schemas';
+export * from './schemas/validators/label-pack.validator';

package/src/components/low-level/WebsiteButton.tsx

@@ -0,0 +1,118 @@
+import React, { type CSSProperties, type ReactNode } from 'react';
+
+import { WebsiteLink } from './WebsiteLink';
+
+/**
+ * @wildo_source:part:start saas.website.primitives.button facet:layer:components facet:family:website
+ *
+ * `WebsiteButton` — L1 marketing-site CTA / button primitive.
+ *
+ * **Two render modes** (selected by the presence of `href`):
+ *   - `href` supplied  => renders as a `<WebsiteLink>` (anchor)
+ *     with button styling. This is the dominant marketing-site
+ *     case (CTAs link to `/signup`, `/contact`, `#pricing`).
+ *   - `href` omitted   => renders a real `<button type="…">` for
+ *     interactive sections (eg. a "Subscribe" form button on the
+ *     contact page that opens an inbound-contact dialog).
+ *
+ * **Why a single primitive** (vs. separate `<WebsiteCta>` +
+ * `<WebsiteButton>`): the visual identity is the same, and the
+ * rendered tag is a low-level concern decided per call site. A
+ * single primitive with two modes keeps the section-author API
+ * narrow (one import, one prop set) while preserving correct
+ * semantic HTML at each call site.
+ *
+ * **Variant vocabulary**: kept minimal at the placeholder level
+ * (`primary` / `secondary`). The override implementation typically
+ * extends with `tertiary`, `ghost`, `destructive`, etc. — adding
+ * variants here would lock the placeholder vocabulary against the
+ * override's richer set.
+ */
+export enum WebsiteButtonVariant {
+  PRIMARY = 'primary',
+  SECONDARY = 'secondary',
+}
+
+export enum WebsiteButtonSize {
+  SM = 'sm',
+  MD = 'md',
+  LG = 'lg',
+}
+
+interface WebsiteButtonCommonProps {
+  variant?: WebsiteButtonVariant;
+  size?: WebsiteButtonSize;
+  className?: string;
+  style?: CSSProperties;
+  id?: string;
+  ariaLabel?: string;
+  children: ReactNode;
+}
+
+interface WebsiteButtonAsLinkProps extends WebsiteButtonCommonProps {
+  href: string;
+  external?: boolean;
+  type?: never;
+  onClick?: never;
+  disabled?: never;
+}
+
+interface WebsiteButtonAsButtonProps extends WebsiteButtonCommonProps {
+  href?: never;
+  external?: never;
+  type?: 'button' | 'submit' | 'reset';
+  onClick?: () => void;
+  disabled?: boolean;
+}
+
+/**
+ * Discriminated union of "anchor-shaped" vs. "button-shaped" props.
+ * Either supply `href` (renders an anchor with link semantics) OR
+ * supply `type` / `onClick` / `disabled` (renders a real button) —
+ * mixing the two is rejected at compile time.
+ */
+export type WebsiteButtonProps = WebsiteButtonAsLinkProps | WebsiteButtonAsButtonProps;
+
+export function WebsiteButton(props: WebsiteButtonProps): ReactNode {
+  const variant = props.variant ?? WebsiteButtonVariant.PRIMARY;
+  const size = props.size ?? WebsiteButtonSize.MD;
+
+  if ('href' in props && props.href !== undefined) {
+    return (
+      <WebsiteLink
+        href={props.href}
+        external={props.external}
+        className={props.className}
+        style={props.style}
+        id={props.id}
+        ariaLabel={props.ariaLabel}
+      >
+        <span
+          data-website-primitive="button"
+          data-website-button-variant={variant}
+          data-website-button-size={size}
+          data-website-button-mode="link"
+        >
+          {props.children}
+        </span>
+      </WebsiteLink>
+    );
+  }
+
+  const attrs: Record<string, unknown> = {
+    'data-website-primitive': 'button',
+    'data-website-button-variant': variant,
+    'data-website-button-size': size,
+    'data-website-button-mode': 'button',
+    type: props.type ?? 'button',
+  };
+  if (props.className !== undefined) attrs.className = props.className;
+  if (props.style !== undefined) attrs.style = props.style;
+  if (props.id !== undefined) attrs.id = props.id;
+  if (props.ariaLabel !== undefined) attrs['aria-label'] = props.ariaLabel;
+  if (props.disabled !== undefined) attrs.disabled = props.disabled;
+  if (props.onClick !== undefined) attrs.onClick = props.onClick;
+  return <button {...attrs}>{props.children}</button>;
+}
+WebsiteButton.displayName = 'WebsiteButton';
+/** @wildo_source:part:end saas.website.primitives.button */

package/src/components/low-level/WebsiteHeading.tsx

@@ -0,0 +1,96 @@
+import React, { type CSSProperties, type ReactNode } from 'react';
+
+/**
+ * @wildo_source:part:start saas.website.primitives.heading facet:layer:components facet:family:website
+ *
+ * `WebsiteHeading` — L1 marketing-site heading primitive.
+ *
+ * **Status (Phase 2 / D18 — option D)**: minimal, self-contained
+ * placeholder. The framework defaults are intentionally bare so
+ * consumers MUST override at the L1 boundary by barrel-re-exporting
+ * a styled variant from their app's
+ * `app/website/primitives/WebsiteHeading.tsx`. The Phase 6
+ * dogfood will validate the override workflow and (deferred to
+ * Phase 6) decide whether to promote these to the
+ * `ComponentRegistryService` registry shared with `saas-frontend-lib`.
+ *
+ * **Why these primitives ship at all** (vs. asking consumers to
+ * author every primitive themselves): consistency of the section
+ * authoring surface. Section authors call `<WebsiteHeading
+ * level={1}>` from `defineWebsiteSection`'d components without
+ * having to know which app they're rendering in — the override
+ * happens at the consumer barrel level transparently.
+ *
+ * **Why `level` is a discrete prop (1–6)**: heading hierarchy is
+ * critical for SEO and accessibility, and a free-string `as` prop
+ * makes it trivial for a copy-paste section to render `<h2>`s where
+ * the page outline expects `<h1>`. Constraining `level` to a numeric
+ * union keeps the section author honest about the document outline.
+ *
+ * **Why `variant` (display vs. headline) is shipped here**:
+ * marketing-site headings need a visual scale that's distinct from
+ * the in-app heading scale (display sizes for hero, headline sizes
+ * for section titles). Even as a placeholder, the variant slot
+ * exists so section authors don't have to invent the prop ad-hoc;
+ * the override implementation can deliver the actual visual scale.
+ */
+export type WebsiteHeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+export enum WebsiteHeadingVariant {
+  /**
+   * Hero / above-the-fold sizes. Maps to the largest type scale in
+   * the consumer's design system. Use for one-per-page copy.
+   */
+  DISPLAY = 'display',
+  /**
+   * Section / sub-section titles. The default — most marketing-site
+   * headings are headline-scale, not display-scale.
+   */
+  HEADLINE = 'headline',
+  /**
+   * In-section group titles (eg. pricing tier names, FAQ question
+   * cards). Smaller than headline, structurally a heading.
+   */
+  TITLE = 'title',
+}
+
+export interface WebsiteHeadingProps {
+  /** Required heading level (1–6). Drives the rendered tag. */
+  level: WebsiteHeadingLevel;
+  /** Visual variant. Defaults to `HEADLINE` (the most common case). */
+  variant?: WebsiteHeadingVariant;
+  /** Forwarded to the heading element. */
+  className?: string;
+  /** Forwarded to the heading element for one-off inline tweaks. */
+  style?: CSSProperties;
+  /** Forwarded id (for anchor links to specific headings). */
+  id?: string;
+  children: ReactNode;
+}
+
+/**
+ * Minimal placeholder. Renders the correct semantic tag with no
+ * visual styling beyond a `data-website-primitive="heading"`
+ * attribute that the consumer's tailwind config / global CSS / the
+ * override implementation can hook into.
+ */
+export function WebsiteHeading({
+  level,
+  variant = WebsiteHeadingVariant.HEADLINE,
+  className,
+  style,
+  id,
+  children,
+}: WebsiteHeadingProps): ReactNode {
+  const Tag = `h${level}` as 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+  const attrs: Record<string, unknown> = {
+    'data-website-primitive': 'heading',
+    'data-website-heading-variant': variant,
+  };
+  if (className !== undefined) attrs.className = className;
+  if (style !== undefined) attrs.style = style;
+  if (id !== undefined) attrs.id = id;
+  return <Tag {...attrs}>{children}</Tag>;
+}
+WebsiteHeading.displayName = 'WebsiteHeading';
+/** @wildo_source:part:end saas.website.primitives.heading */

package/src/components/low-level/WebsiteImage.tsx

@@ -0,0 +1,96 @@
+import React, { type CSSProperties, type ReactNode } from 'react';
+
+/**
+ * @wildo_source:part:start saas.website.primitives.image facet:layer:components facet:family:website
+ *
+ * `WebsiteImage` — L1 marketing-site image primitive.
+ *
+ * **Status (Phase 2 / D18)**: minimal placeholder around a plain
+ * `<img>` with sensible accessibility / performance defaults
+ * (`alt` is REQUIRED, `loading` defaults to `'lazy'`, `decoding`
+ * defaults to `'async'`). Production sites override at the L1
+ * boundary to wire in Astro's `<Image>` component (or a Next/CDN
+ * variant) for automatic format / width / DPR handling.
+ *
+ * **Why `alt` is REQUIRED at the type level**: marketing imagery
+ * is a public-facing surface where missing alt text directly hurts
+ * SEO scoring AND blocks screen-reader access. Forcing the section
+ * author to author an `alt` (even an empty `''` for purely
+ * decorative images) makes the accessibility decision explicit at
+ * the call site.
+ *
+ * **Why `width` / `height` are REQUIRED**: cumulative-layout-shift
+ * is a Core Web Vital that marketing pages are routinely scored
+ * against. Without intrinsic dimensions, every image on the page
+ * triggers layout shift on load. Forcing the dimensions at the call
+ * site keeps CLS near zero by default — the override implementation
+ * can swap to Astro's `<Image>` (which encodes the same dimensions
+ * differently) without changing the section-author API.
+ *
+ * **Why no `priority` / `fetchpriority` prop here**: Astro's
+ * `<Image>` exposes its own `loading="eager"` / `priority` props
+ * with implementation-specific semantics, and a placeholder-level
+ * `priority` would be either a lie (does nothing without the Astro
+ * adapter) or a footgun (forces the override to honor a contract
+ * it can't always meet). The override implementation is the right
+ * place to expose this.
+ */
+export interface WebsiteImageProps {
+  src: string;
+  /**
+   * REQUIRED. Use `alt=""` (empty string) for purely decorative
+   * images — `null` / `undefined` is rejected at compile time so
+   * the accessibility decision is always explicit.
+   */
+  alt: string;
+  /**
+   * REQUIRED. Intrinsic image width in CSS pixels (eg. `1200`).
+   */
+  width: number;
+  /**
+   * REQUIRED. Intrinsic image height in CSS pixels (eg. `630`).
+   */
+  height: number;
+  /**
+   * `'lazy'` (default) defers loading until the image is near the
+   * viewport. Set to `'eager'` for above-the-fold hero images.
+   */
+  loading?: 'lazy' | 'eager';
+  /**
+   * `'async'` (default) lets the browser decode the image off the
+   * main thread. Set to `'sync'` only for above-the-fold hero
+   * images that need to paint immediately.
+   */
+  decoding?: 'async' | 'sync' | 'auto';
+  className?: string;
+  style?: CSSProperties;
+  id?: string;
+}
+
+export function WebsiteImage({
+  src,
+  alt,
+  width,
+  height,
+  loading = 'lazy',
+  decoding = 'async',
+  className,
+  style,
+  id,
+}: WebsiteImageProps): ReactNode {
+  const attrs: Record<string, unknown> = {
+    'data-website-primitive': 'image',
+    src,
+    alt,
+    width,
+    height,
+    loading,
+    decoding,
+  };
+  if (className !== undefined) attrs.className = className;
+  if (style !== undefined) attrs.style = style;
+  if (id !== undefined) attrs.id = id;
+  return <img {...attrs} />;
+}
+WebsiteImage.displayName = 'WebsiteImage';
+/** @wildo_source:part:end saas.website.primitives.image */

package/src/components/low-level/WebsiteInternalButton.tsx

@@ -0,0 +1,172 @@
+import React, { type CSSProperties, type ReactNode } from 'react';
+
+import { AvailableLanguage } from '@wildo-ai/saas-models/public-runtime';
+
+import { useWebsiteRuntime } from '../../core/contexts/useWebsiteRuntime';
+import { buildLocalizedRoutePath } from '../../core/routing/internal-routing.utils';
+
+import {
+  WebsiteButton,
+  type WebsiteButtonSize,
+  type WebsiteButtonVariant,
+} from './WebsiteButton';
+
+/**
+ * Pre-computed set of every known locale code; mirrors the guard in
+ * `WebsiteInternalLink` (kept duplicated rather than shared so each
+ * primitive's audit surface stays self-contained — the set is tiny).
+ */
+const ALL_LOCALE_CODES: ReadonlySet<string> = new Set(
+  Object.values(AvailableLanguage) as readonly string[],
+);
+
+function detectAccidentalLocalePrefix(routePath: string): string | null {
+  const slashIdx = routePath.indexOf('/', 1);
+  const firstSegment =
+    slashIdx === -1 ? routePath.slice(1) : routePath.slice(1, slashIdx);
+  if (firstSegment === '') return null;
+  return ALL_LOCALE_CODES.has(firstSegment) ? firstSegment : null;
+}
+
+/**
+ * @wildo_source:part:start saas.website.primitives.internal-button facet:layer:components facet:family:website
+ *
+ * `WebsiteInternalButton` — L1 marketing-site CTA primitive for
+ * INTERNAL anchor-mode buttons (CTAs that navigate to another route
+ * served by the same Astro build, e.g. "Get in touch" → `/contact`).
+ *
+ * **The architectural problem this solves** (Phase 6 fourth audit fix
+ * H-Φ): the H-β fix shipped `WebsiteInternalLink` for header/footer
+ * navigation links but `WebsiteButton` consumers in section bodies
+ * (hero / features / pricing / contact) continued to write
+ * `<WebsiteButton href="/contact">` with raw locale-neutral paths. On
+ * `/fr/…` pages those CTAs navigated to the EN-default `/contact`
+ * URL — exactly the cross-locale leak H-β was meant to kill, just on
+ * the page body instead of the chrome. Authors had to know the
+ * routing rule and call `buildLocalizedRoutePath` manually on every
+ * CTA they shipped, and the audit confirmed they did not.
+ *
+ * **Why a parallel primitive** (mirrors the H-β reasoning, NOT a
+ * `routePath` flag on `WebsiteButton`):
+ *   1. The two primitives have different authoring contracts —
+ *      `WebsiteButton`'s `href` is a fully-qualified URL the author
+ *      already commits to (or an anchor `#section`, or external);
+ *      this primitive's `routePath` is a raw locale-neutral path that
+ *      the framework prefixes. Mixing both shapes behind one prop
+ *      forces the author to think about a routing rule on every CTA
+ *      they place; mixing them without a type-system signal invites
+ *      the wrong shape on the wrong branch.
+ *   2. Internal CTAs REQUIRE the runtime context; external/anchor
+ *      CTAs do not. Forcing every external-link `WebsiteButton`
+ *      consumer to wrap in `<WebsiteRuntimeContextProvider>` is wrong.
+ *      Two primitives keep the dependency surface honest.
+ *   3. Symmetric with `WebsiteInternalLink` — section authors learn
+ *      one rule ("use the `Internal` variant for app-served paths,
+ *      the bare variant for external/scheme/anchor URLs") and apply
+ *      it identically to both link and button shapes.
+ *
+ * **Button-only render mode**: this primitive is anchor-mode-only by
+ * construction (every internal target is a route → an anchor element
+ * with appropriate href). Consumers who need a real `<button>` (no
+ * navigation, just an `onClick` handler) keep using `<WebsiteButton>`
+ * directly — there is no `routePath`-based real-button concept.
+ *
+ * **Anchor-only links** (`routePath="#features"`) and URL schemes
+ * (`mailto:`/`tel:`) are rejected at runtime: those targets do NOT
+ * benefit from locale prefixing, and surfacing them through this
+ * primitive would invite the SAME confusion that motivated splitting
+ * `WebsiteInternalLink` from `WebsiteLink` in the first place. Use
+ * `<WebsiteButton href="..." external={true}>` for those cases.
+ *
+ * **Boundary**: this component MUST stay in the React-island bundle
+ * tier (`components/low-level/`). It depends on `useWebsiteRuntime`
+ * (which throws when called outside a `<WebsiteRuntimeContextProvider>`)
+ * — the throw is the contract that prevents body CTAs from being
+ * rendered outside a bridged page accidentally.
+ *
+ * @example
+ *   ```tsx
+ *   // Hero CTA — auto-prefixes the active locale
+ *   // (`/contact` on EN pages, `/fr/contact` on FR pages):
+ *   <WebsiteInternalButton routePath="/contact" variant={WebsiteButtonVariant.PRIMARY}>
+ *     {useWebsiteLabel('cta.primary')}
+ *   </WebsiteInternalButton>
+ *   ```
+ */
+export interface WebsiteInternalButtonProps {
+  /**
+   * The locale-NEUTRAL route path. Must match a value the consumer's
+   * Astro build serves (typically a `WebsitePageManifest.routePath`).
+   * MUST start with `/` — anchor-only `#section` and URL schemes
+   * (`mailto:` / `tel:`) are rejected (use `<WebsiteButton href={...}>`
+   * for those cases).
+   */
+  routePath: string;
+  variant?: WebsiteButtonVariant;
+  size?: WebsiteButtonSize;
+  className?: string;
+  style?: CSSProperties;
+  id?: string;
+  ariaLabel?: string;
+  children: ReactNode;
+}
+
+export function WebsiteInternalButton({
+  routePath,
+  variant,
+  size,
+  className,
+  style,
+  id,
+  ariaLabel,
+  children,
+}: WebsiteInternalButtonProps): ReactNode {
+  const runtime = useWebsiteRuntime();
+
+  if (!routePath.startsWith('/')) {
+    throw new Error(
+      `[WebsiteInternalButton] routePath="${routePath}" must start with "/" ` +
+        `(framework-relative path). Anchors ("#..."), URL schemes ` +
+        `("mailto:" / "tel:"), and fully-qualified external URLs are ` +
+        `NOT supported by this primitive — use <WebsiteButton href={...} external={true}> ` +
+        `(or omit \`external\` for in-app anchors and scheme links). ` +
+        `For NAVIGATION links (not styled as a CTA), see <WebsiteInternalLink routePath={...}>.`,
+    );
+  }
+
+  const accidentalPrefix = detectAccidentalLocalePrefix(routePath);
+  if (accidentalPrefix !== null) {
+    throw new Error(
+      `[WebsiteInternalButton] routePath="${routePath}" begins with the ` +
+        `locale segment "/${accidentalPrefix}" — the framework prefixes ` +
+        `the active locale automatically, so passing a pre-prefixed path ` +
+        `would render as "/${accidentalPrefix}${routePath}" on non-default ` +
+        `locale pages (double-prefix) or silently break locale routing on ` +
+        `default-locale pages. Pass the locale-NEUTRAL path instead ` +
+        `(eg. "/pricing", not "/${accidentalPrefix}/pricing").`,
+    );
+  }
+
+  const href = buildLocalizedRoutePath({
+    locale: runtime.locale,
+    defaultLocale: runtime.defaultLocale,
+    routePath,
+  });
+
+  return (
+    <WebsiteButton
+      href={href}
+      external={false}
+      variant={variant}
+      size={size}
+      className={className}
+      style={style}
+      id={id}
+      ariaLabel={ariaLabel}
+    >
+      {children}
+    </WebsiteButton>
+  );
+}
+WebsiteInternalButton.displayName = 'WebsiteInternalButton';
+/** @wildo_source:part:end saas.website.primitives.internal-button */