@warpgogol/werkstatt-shared 0.2.0

package/src/share/schemas/live-photo.ts

@@ -0,0 +1,53 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  [RFC-0202] Canonical LivePhoto config — the content contract that turns a static authored
+  image into a "living photo": a looping, muted, decorative <video> overlaid on the existing
+  <ResponsiveImage> (RFC-0152), which always remains the resting state / poster / fallback.
+  This schema configures WHETHER a photo is live and HOW it plays. It deliberately names NO
+  file: the clip is the sibling `<image-name>.webm`, resolved by convention (resolveVideo).
+</purpose>
+<non-goals>
+  <item>Do not carry a video/poster path — the clip is derived from the image token.</item>
+  <item>Do not implement playback or resolution — that is @warpgogol/werkstatt-site/ui + resolveVideo.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0202: introduced the LivePhoto content contract.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+/** How the loop starts. */
+export const livePhotoTriggerSchema = z.enum(["in-viewport", "tap", "autoplay"]);
+export type LivePhotoTrigger = z.infer<typeof livePhotoTriggerSchema>;
+
+export const livePhotoSchema = z
+  .object({
+    /** Turn the image into a living photo. Default true (presence implies intent). */
+    enabled: z.boolean().default(true),
+
+    /**
+     * When the loop starts:
+     *  - "in-viewport" (default): plays while scrolled into view, pauses when out (IntersectionObserver).
+     *  - "tap": stays a static photo until the visitor activates the play control.
+     *  - "autoplay": plays immediately on load via native attributes — no JavaScript.
+     */
+    trigger: livePhotoTriggerSchema.optional(),
+
+    /** Loop the clip continuously. Default true. false = play once, then rest on the last frame. */
+    loop: z.boolean().optional(),
+
+    /**
+     * What a tap does once the clip is running:
+     *  - "toggle" (default): tap pauses a playing clip / resumes a paused one.
+     *  - "play-only": tap can start the clip but never pauses it (the control only kick-starts).
+     */
+    tapBehavior: z.enum(["toggle", "play-only"]).optional(),
+
+    /** Media preload hint. Default "metadata" (spec-recommended baseline). */
+    preload: z.enum(["none", "metadata", "auto"]).optional(),
+  })
+  .strict();
+export type LivePhoto = z.infer<typeof livePhotoSchema>;

package/src/share/schemas/material-credit.ts

@@ -0,0 +1,292 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  RFC-0220 Material Credits contract. Defines the closed, app-agnostic schema for
+  credit/provenance sidecars that describe published materials without conflating
+  human authorship with AI tooling.
+</purpose>
+<non-goals>
+  <item>Do not discover sidecar files; validators and UI loaders own their input maps.</item>
+  <item>Do not own language catalogs, localized copy, or default rights notices.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0220: initial Material Credits schema and formatting helpers.</item>
+  <item>RFC-0223: acquireLicensePage, copyrightYear, CreditParty.version/generatedAt.</item>
+  <item>RFC-0228: target.intent "editorial"|"decorative" optional marker.</item>
+  <item>RFC-0231: optional per-asset `display` visibility override.</item>
+  <item>RFC-0488: status, usageBasis, aiUsage fields; new sourceType/role values; label mapping helpers.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+export const materialKindSchema = z.enum([
+  "image",
+  "video",
+  "audio",
+  "document",
+  "article",
+  "prose",
+  "external",
+]);
+export type MaterialKind = z.infer<typeof materialKindSchema>;
+
+export const materialSourceTypeSchema = z.enum([
+  "human-made",
+  "ai-assisted",
+  "ai-generated",
+  "composite",
+  "third-party",
+  "commissioned",
+  "licensed-third-party",
+  "customer-supplied",
+  "public-domain",
+  "screenshot",
+]);
+export type MaterialSourceType = z.infer<typeof materialSourceTypeSchema>;
+
+export const creditPartyKindSchema = z.enum([
+  "Person",
+  "Organization",
+  "AIAgent",
+  "AIModel",
+  "AIPlatform",
+  "Workflow",
+  "SourceMaterial",
+]);
+export type CreditPartyKind = z.infer<typeof creditPartyKindSchema>;
+
+export const creditRoleSchema = z.enum([
+  "creator",
+  "coCreator",
+  "commissionedBy",
+  "producer",
+  "promptAuthor",
+  "workflowAuthor",
+  "aiAgent",
+  "aiModel",
+  "aiPlatform",
+  "sourceMaterial",
+  "reviewer",
+  "approver",
+  "rightsHolder",
+  "editor",
+  "contributor",
+  "photographer",
+  "illustrator",
+]);
+export type CreditRole = z.infer<typeof creditRoleSchema>;
+
+export const materialTargetSchema = z
+  .object({
+    kind: materialKindSchema,
+    id: z.string().min(1),
+    domain: z.enum(["pages", "prose", "business", "people", "site", "surface"]).optional(),
+    lang: z.string().min(2).optional(),
+    locator: z.string().min(1).optional(),
+    /** RFC-0228: editorial requires a credit; decorative is excluded from the required-credit gate. */
+    intent: z.enum(["editorial", "decorative"]).optional(),
+  })
+  .strict();
+export type MaterialTarget = z.infer<typeof materialTargetSchema>;
+export type MaterialTargetDomain = NonNullable<MaterialTarget["domain"]>;
+
+export const creditPartySchema = z
+  .object({
+    role: creditRoleSchema,
+    name: z.string().min(1),
+    kind: creditPartyKindSchema,
+    url: z.string().url().optional(),
+    /** RFC-0223: model/platform/tool version, meaningful for AI and source parties. */
+    version: z.string().min(1).optional(),
+    /** RFC-0223: ISO date the AI/source material was generated. */
+    generatedAt: z.string().min(1).optional(),
+    note: z.string().min(1).optional(),
+  })
+  .strict();
+export type CreditParty = z.infer<typeof creditPartySchema>;
+
+export const materialLicenseSchema = z
+  .object({
+    label: z.string().min(1),
+    url: z.string().url().optional(),
+    /** RFC-0223: page where a license can be obtained (Google licensable images). */
+    acquireLicensePage: z.string().url().optional(),
+    copyrightNotice: z.string().min(1).optional(),
+    /** RFC-0223: structured copyright year. */
+    copyrightYear: z.number().int().optional(),
+    rightsStatement: z.string().min(1).optional(),
+  })
+  .strict();
+export type MaterialLicense = z.infer<typeof materialLicenseSchema>;
+
+export const materialCreditStatusSchema = z.enum([
+  "active",
+  "orphaned",
+  "needs-review",
+  "blocked",
+  "expired",
+]);
+export type MaterialCreditStatus = z.infer<typeof materialCreditStatusSchema>;
+
+export const usageBasisTypeSchema = z.enum([
+  "internal-commissioned",
+  "express-permission",
+  "license",
+  "customer-supplied",
+  "public-domain",
+  "statutory-exception",
+  "quotation-right",
+  "unverified",
+]);
+export type UsageBasisType = z.infer<typeof usageBasisTypeSchema>;
+
+export const usageBasisSchema = z
+  .object({
+    type: usageBasisTypeSchema,
+    /** Internal evidence reference (contract, license receipt, permission email). Opaque string — never shown to visitors, not validated for existence. */
+    evidenceRef: z.string().min(1).optional(),
+    /** Human-readable note about the basis, shown in the details section. */
+    note: z.string().min(1).optional(),
+  })
+  .strict();
+export type UsageBasis = z.infer<typeof usageBasisSchema>;
+
+export const aiUsageSchema = z
+  .object({
+    /** Whether the output is fully AI-generated or AI-assisted. */
+    kind: z.enum(["ai-generated", "ai-assisted"]),
+    /** Human creative contribution description. */
+    humanContribution: z.string().min(1),
+    /** Whether copyright is claimed for the output. */
+    copyrightClaimed: z.boolean(),
+    /** Internal generation record reference. Opaque string — never shown to visitors, not validated for existence. */
+    generationRecordRef: z.string().min(1).optional(),
+  })
+  .strict();
+export type AiUsage = z.infer<typeof aiUsageSchema>;
+
+export const materialCreditSchema = z
+  .object({
+    id: z.string().min(1),
+    target: materialTargetSchema,
+    sourceType: materialSourceTypeSchema,
+    /** RFC-0231: per-asset visibility override (level 1). Absent ⇒ policy decides. */
+    display: z.enum(["shown", "hidden"]).optional(),
+    /** RFC-0488: lifecycle status of the credit record. */
+    status: materialCreditStatusSchema.optional(),
+    /** RFC-0488: legal basis for using the material, distinct from the license label. */
+    usageBasis: usageBasisSchema.optional(),
+    /** RFC-0488: AI-specific provenance, required when sourceType is ai-generated or ai-assisted. */
+    aiUsage: aiUsageSchema.optional(),
+    title: z.string().min(1).optional(),
+    creditLine: z.string().min(1).optional(),
+    parties: z.array(creditPartySchema).min(1),
+    license: materialLicenseSchema,
+    createdAt: z.string().min(1).optional(),
+    reviewedAt: z.string().min(1).optional(),
+    reviewNote: z.string().min(1).optional(),
+    c2paManifestUrl: z.string().url().optional(),
+    iptcMetadataStatus: z.enum(["preserved", "stripped", "not-applicable", "unknown"]).optional(),
+  })
+  .strict();
+export type MaterialCredit = z.infer<typeof materialCreditSchema>;
+
+export const materialCreditLabelsSchema = z
+  .object({
+    summaryLabel: z.string().min(1),
+    pageTitle: z.string().min(1),
+    pageDescription: z.string().min(1),
+    emptyMessage: z.string().min(1),
+    detailsLabel: z.string().min(1),
+    createdBy: z.string().min(1),
+    createdWith: z.string().min(1),
+    promptBy: z.string().min(1),
+    reviewedBy: z.string().min(1),
+    license: z.string().min(1),
+    copyrightLabel: z.string().min(1),
+    rightsHolder: z.string().min(1),
+    sourceType: z.string().min(1),
+    /** RFC-0488: per-sourceType localized labels. */
+    sourceTypeLabels: z.record(materialSourceTypeSchema, z.string().min(1)),
+    /** RFC-0488: per-status localized labels. */
+    statusLabels: z.record(materialCreditStatusSchema, z.string().min(1)),
+    /** RFC-0488: per-usageBasis.type localized labels. */
+    usageBasisLabels: z.record(usageBasisTypeSchema, z.string().min(1)),
+    /** RFC-0488: AI-specific localized labels. */
+    aiUsageLabels: z.object({
+      aiGenerated: z.string().min(1),
+      aiAssisted: z.string().min(1),
+      humanContribution: z.string().min(1),
+      copyrightClaimed: z.string().min(1),
+      copyrightNotClaimed: z.string().min(1),
+    }),
+    /** RFC-0488: "Used on" label for usage locations list. */
+    usedOnLabel: z.string().min(1),
+    /** RFC-0488: "Verified at" label. */
+    verifiedAtLabel: z.string().min(1),
+    /** RFC-0488: placeholder text when no preview is available. */
+    noPreviewLabel: z.string().min(1),
+    /** RFC-0488: explanatory text rendered once at the bottom of the credits page. */
+    copyrightExplanation: z.string().min(1),
+  })
+  .strict();
+export type MaterialCreditLabels = z.infer<typeof materialCreditLabelsSchema>;
+
+function namesFor(credit: MaterialCredit, roles: CreditRole[]): string[] {
+  return credit.parties.filter((party) => roles.includes(party.role)).map((party) => party.name);
+}
+
+export function labelForMaterialCreditRole(role: CreditRole, labels: MaterialCreditLabels): string {
+  if (role === "creator" || role === "coCreator") return labels.createdBy;
+  if (role === "aiAgent" || role === "aiModel" || role === "aiPlatform") return labels.createdWith;
+  if (role === "promptAuthor" || role === "workflowAuthor") return labels.promptBy;
+  if (role === "reviewer" || role === "approver") return labels.reviewedBy;
+  if (role === "rightsHolder") return labels.rightsHolder;
+  return role;
+}
+
+/** RFC-0488: map a sourceType enum value to a localized human-readable label. */
+export function labelForSourceType(
+  sourceType: MaterialSourceType,
+  labels: MaterialCreditLabels,
+): string {
+  return labels.sourceTypeLabels[sourceType] ?? sourceType;
+}
+
+/** RFC-0488: map a status enum value to a localized human-readable label. */
+export function labelForStatus(status: MaterialCreditStatus, labels: MaterialCreditLabels): string {
+  return labels.statusLabels[status] ?? status;
+}
+
+/** RFC-0488: map a usageBasis.type enum value to a localized human-readable label. */
+export function labelForUsageBasis(type: UsageBasisType, labels: MaterialCreditLabels): string {
+  return labels.usageBasisLabels[type] ?? type;
+}
+
+export function formatMaterialCreditLine(
+  credit: MaterialCredit,
+  labels: MaterialCreditLabels,
+): string {
+  if (credit.creditLine) return credit.creditLine;
+
+  const parts: string[] = [];
+  const creators = namesFor(credit, ["creator", "coCreator"]);
+  const aiTools = namesFor(credit, ["aiAgent", "aiModel", "aiPlatform"]);
+  const promptAuthors = namesFor(credit, ["promptAuthor", "workflowAuthor"]);
+  const reviewers = namesFor(credit, ["reviewer", "approver"]);
+
+  if (creators.length > 0) parts.push(`${labels.createdBy}: ${creators.join(", ")}`);
+  if (aiTools.length > 0) parts.push(`${labels.createdWith}: ${aiTools.join(", ")}`);
+  if (promptAuthors.length > 0) parts.push(`${labels.promptBy}: ${promptAuthors.join(", ")}`);
+  if (reviewers.length > 0) parts.push(`${labels.reviewedBy}: ${reviewers.join(", ")}`);
+  parts.push(`${labels.license}: ${credit.license.label}`);
+  parts.push(`${labels.sourceType}: ${labelForSourceType(credit.sourceType, labels)}`);
+
+  return parts.join(" · ");
+}
+
+export function materialTargetKey(target: MaterialTarget, lang?: string): string {
+  return [target.kind, target.domain ?? "", lang ?? target.lang ?? "", target.id].join(":");
+}

package/src/share/schemas/media.ts

@@ -0,0 +1,220 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  [RFC-0210] Canonical media playback contract — the single, source-agnostic config that drives
+  every <video> on the platform through ONE primitive (<Media>) and ONE delivery policy
+  (HLS-first → progressive MP4 → optional WebM; native-only for decorative loops). The contract
+  is "not a file format" but a profile-driven policy: `feature` (content video, controls, HLS
+  ABR ladder, captions), `background` (muted loop bg), and `ambient` (living photo, RFC-0202,
+  folded in). It also defines the GENERATED video manifest shape the build-time generator emits
+  and <Media> reads synchronously (the video analogue of RFC-0204's image-variant manifest).
+</purpose>
+<non-goals>
+  <item>Do not resolve files — that is @warpgogol/werkstatt-site/content-source (resolveMedia) + the generated manifest.</item>
+  <item>Do not implement playback or transcoding — that is @warpgogol/werkstatt-site/ui + the kernel command.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0210: introduced the unified media playback contract + video manifest types.</item>
+  <item>RFC-0525: added av1 field to VideoManifestSources for AV1 progressive delivery.</item>
+  <item>RFC-0525: added opt-in av1 boolean to mediaSchema (default false) to skip slow AV1 encoding.</item>
+  <item>RFC-0591: added maxSizeMb field to mediaSchema for two-pass bitrate-capped MP4 encoding.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+import type { LivePhoto } from "./live-photo.ts";
+
+/** The three delivery profiles. Profile drives generated formats, transport, player JS, and a11y. */
+export const mediaProfileSchema = z.enum(["feature", "background", "ambient"]);
+export type MediaProfile = z.infer<typeof mediaProfileSchema>;
+
+/** When the loop starts (ambient/background) — mirrors RFC-0202 livePhotoTriggerSchema. */
+export const mediaTriggerSchema = z.enum(["in-viewport", "tap", "autoplay"]);
+export type MediaTrigger = z.infer<typeof mediaTriggerSchema>;
+
+/** Source addressing. Exactly one of `name` (explicit token) or `fromImage` (ambient convention). */
+export const mediaSourceSchema = z
+  .object({
+    /** Bare media token (RFC-0053 style). Resolved like resolveImage: <lang>/assets/<name>.<ext>. */
+    name: z.string().min(1).optional(),
+    /** Ambient only: derive the clip from a sibling image token (RFC-0202 convention). */
+    fromImage: z.string().min(1).optional(),
+  })
+  .strict();
+export type MediaSource = z.infer<typeof mediaSourceSchema>;
+
+/** One caption/subtitle track (WCAG 1.2.2). VTT resolved by convention (<token>.<lang>.vtt) or named. */
+export const mediaCaptionSchema = z
+  .object({
+    lang: z.string().min(2),
+    label: z.string().optional(),
+    /** Default true: this track is shown by default for its language. */
+    default: z.boolean().optional(),
+  })
+  .strict();
+export type MediaCaption = z.infer<typeof mediaCaptionSchema>;
+
+export const mediaSchema = z
+  .object({
+    profile: mediaProfileSchema.default("feature"),
+    source: mediaSourceSchema,
+
+    /** Poster image token. Defaults: sibling <token> raster, else generated first-frame poster. */
+    poster: z.string().optional(),
+    /**
+     * Seconds offset for the auto-generated first-frame poster (ffmpeg `-ss`). Default 1.
+     * Use to skip an intro/title card and capture a representative, fully-rendered frame.
+     */
+    posterTime: z.number().nonnegative().optional(),
+    /** Required by the validator for feature; ambient/background <video> stays aria-hidden. */
+    alt: z.string().optional(),
+
+    /** feature: ABR ladder depth. "auto" picks renditions by source height; [] = single rendition. */
+    ladder: z.union([z.literal("auto"), z.array(z.number().int().positive())]).optional(),
+
+    /**
+     * feature: opt-in AV1 progressive delivery via libsvtav1 (RFC-0525). AV1 is the slowest encoder
+     * in the pipeline; default false keeps build times fast. Set to true only for high-traffic
+     * feature videos where AV1 bandwidth savings justify the encoding cost.
+     */
+    av1: z.boolean().optional(),
+
+    /**
+     * Maximum size of the progressive MP4 file in MiB. When set, MP4 encoding switches
+     * to two-pass with a target bitrate calculated from the source duration. Default: 24
+     * (1 MiB safety margin under Cloudflare's 25 MiB per-asset limit). Set to 0 to disable
+     * two-pass and use CRF 17 (no size guarantee — may exceed the Cloudflare limit).
+     */
+    maxSizeMb: z.number().nonnegative().optional(),
+
+    /** Playback behavior (profile-clamped at render: ambient/background force muted+loop, never controls). */
+    autoplay: z.boolean().optional(),
+    loop: z.boolean().optional(),
+    muted: z.boolean().optional(),
+    controls: z.boolean().optional(),
+    preload: z.enum(["none", "metadata", "auto"]).optional(),
+
+    /** ambient/background only (RFC-0202): when the loop starts and what a tap does. */
+    trigger: mediaTriggerSchema.optional(),
+    tapBehavior: z.enum(["toggle", "play-only"]).optional(),
+
+    /** feature: prerecorded-speech accessibility. */
+    captions: z.array(mediaCaptionSchema).optional(),
+    /** contentRef to a prose transcript rendered under the video and exposed to llms/SEO. */
+    transcriptRef: z.string().optional(),
+
+    lang: z.string().optional(),
+    subPath: z.string().optional(),
+  })
+  .strict()
+  .superRefine((m, ctx) => {
+    const hasName = !!m.source.name;
+    const hasFromImage = !!m.source.fromImage;
+    if (hasName === hasFromImage) {
+      ctx.addIssue({
+        code: "custom",
+        message: "media.source needs exactly one of name | fromImage",
+      });
+    }
+    if (m.profile !== "ambient" && hasFromImage) {
+      ctx.addIssue({
+        code: "custom",
+        message: "source.fromImage is only valid for the ambient profile",
+      });
+    }
+    if (m.profile === "feature" && !m.alt) {
+      ctx.addIssue({ code: "custom", message: "feature media requires alt text" });
+    }
+  });
+export type Media = z.infer<typeof mediaSchema>;
+
+/**
+ * [RFC-0210] Project a legacy RFC-0202 LivePhoto config (paired with its host image token) onto
+ * an equivalent ambient Media config. This is the seam that lets existing `live:` authoring keep
+ * working while resolving through the single media contract — no content migration required.
+ * Returns null when the photo is not live (enabled === false).
+ */
+export function livePhotoToMedia(live: LivePhoto | undefined, imageName: string): Media | null {
+  if (!live || live.enabled === false) return null;
+  return {
+    profile: "ambient",
+    source: { fromImage: imageName },
+    trigger: live.trigger,
+    loop: live.loop,
+    tapBehavior: live.tapBehavior,
+    preload: live.preload,
+  } as Media;
+}
+
+// ─── GENERATED video manifest (RFC-0210 — written by video.variants.generate) ────────────────
+
+/** One playable caption track in the generated manifest. */
+export interface VideoCaptionTrack {
+  lang: string;
+  label?: string;
+  default?: boolean;
+  url: string;
+}
+
+/** Derived-format URLs for one source video, keyed by container/transport. */
+export interface VideoManifestSources {
+  /** HLS master playlist (feature only). */
+  hls?: string;
+  /** Progressive H.264/AAC MP4 — the universal fallback. */
+  mp4?: string;
+  /** Optional VP9 WebM enhancement. */
+  webm?: string;
+  /** AV1-in-WebM progressive (RFC-0525). Feature only. */
+  av1?: string;
+}
+
+export interface VideoManifestEntry {
+  /** Content-relative source path key, e.g. /src/content/pages/uk/assets/promo.mp4. */
+  origin: string;
+  profile: MediaProfile;
+  /** Poster URL (authored sibling raster or generated first-frame). */
+  poster?: string;
+  intrinsicWidth?: number;
+  intrinsicHeight?: number;
+  durationSec?: number;
+  hasAudio?: boolean;
+  sources: VideoManifestSources;
+  captions?: VideoCaptionTrack[];
+}
+
+export interface VideoManifest {
+  version: 1;
+  /** Primary lookup: content-relative source path → entry. */
+  byOrigin: Record<string, VideoManifestEntry>;
+  /** Secondary lookup: `<lang>/<token>` → byOrigin key (render-side token resolution). */
+  byToken: Record<string, string>;
+}
+
+/**
+ * [RFC-0234] Derived delivery set for one living-photo / ambient clip. The author ships exactly one
+ * source file (`<token>.webm` OR `<token>.mp4`, never both); the build derives the cross-device set
+ * so the clip plays everywhere. `webm` is the desktop/Android source (alpha preserved); `mp4` is the
+ * iOS-playable H.264 fallback. Since H.264 cannot carry alpha, a TRANSPARENT source is flattened
+ * over the site background colour (`mp4Bg`) so the iOS clip blends into the page instead of showing
+ * a dirty box; an opaque source is transcoded/copied as-is. `alpha` records WebM transparency so the
+ * desktop render stays transparent.
+ */
+export interface LiveVideoManifestEntry {
+  /** Content-relative source path key, e.g. /src/content/people/de/assets/maria-calderon.webm. */
+  origin: string;
+  /** Desktop/Android VP9 WebM URL (served from public/_video/live; alpha preserved). */
+  webm?: string;
+  /** iOS-playable progressive H.264 MP4 URL (transparent sources flattened over `mp4Bg`). */
+  mp4?: string;
+  /** True when the source WebM carries an alpha channel (transparent subject). */
+  alpha: boolean;
+  /** ffmpeg `0xRRGGBB` background colour the alpha source was flattened over for the iOS MP4. */
+  mp4Bg?: string;
+}
+
+export interface LiveVideoManifest {
+  version: 1;
+  /** Lookup: `<lang>/<token>` → derived entry. */
+  byToken: Record<string, LiveVideoManifestEntry>;
+}

package/src/share/schemas/navigation.ts

@@ -0,0 +1,74 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Maintains packages/share/src/schemas/navigation.ts as an authored share authored module so agents can evolve it without rediscovering local boundaries.</purpose>
+<non-goals>
+  <item>Do not handle runtime resolution or feature graph integration.</item>
+  <item>Do not contain business logic.</item>
+  <item>Do not handle backward compatibility (RFC-0046: no backward compatibility needed).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Implement RFC-0046: Move navigation schema to shared package with configurable groups.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+/**
+ * Creates a Zod enum for navigation groups from an array of allowed group names.
+ * Apps call this in their content.config.ts or navigation.ts with their specific groups.
+ *
+ * @param groups - Array of allowed navigation group names for the app
+ * @returns Zod enum schema for navigation groups
+ */
+export function createNavigationGroupEnum(groups: string[]) {
+  return z.enum(groups as [string, ...string[]]);
+}
+
+// Default groups for backward compatibility with existing apps
+export const defaultNavigationGroups = ["navigation", "legal", "contact"] as const;
+
+/**
+ * Creates a navigation target schema with configurable group validation.
+ *
+ * @param groupEnum - Zod enum schema for allowed navigation groups
+ * @returns Zod schema for a single navigation target
+ */
+export const navigationTargetSchema = (groupEnum: z.ZodEnum<Record<string, string>>) =>
+  z.object({
+    id: z.string(),
+    label: z.string(),
+    semanticTarget: z.union([
+      z.object({
+        kind: z.literal("internal"),
+        pageId: z.string(),
+        // RFC-0048: anchor may be a plain string (language-neutral) or a
+        // language-keyed record (e.g. { de: "unser-ansatz", en: "our-approach" })
+        anchor: z.union([z.string(), z.record(z.string(), z.string())]).optional(),
+      }),
+      z.object({
+        kind: z.literal("external"),
+        href: z.url(),
+      }),
+    ]),
+    routeSlug: z.string().optional(),
+    group: groupEnum.optional(),
+  });
+
+/**
+ * Creates a navigation schema with configurable group validation.
+ *
+ * @param groupEnum - Zod enum schema for allowed navigation groups
+ * @returns Zod schema for the full navigation structure
+ */
+export const navigationSchema = (groupEnum: z.ZodEnum<Record<string, string>>) =>
+  z.object({
+    targets: z.array(navigationTargetSchema(groupEnum)),
+  });
+
+/**
+ * Type helper for navigation target.
+ * The group field is loosely typed (string) here; per-app strict validation comes
+ * from the runtime Zod schema returned by navigationTargetSchema(groupEnum).
+ */
+export type NavigationTarget = z.infer<ReturnType<typeof navigationTargetSchema>>;

package/src/share/schemas/page-base.ts

@@ -0,0 +1,33 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Shared base Zod fields consumed by all page schemas across apps/*. Extracted to packages/share
+so every app re-uses the same componentOverrides contract without copy-pasting.
+Depends only on the zod peer dependency; no Astro or app-specific imports.
+</purpose>
+<non-goals>
+  <item>Do not define page-specific or app-specific fields here.</item>
+  <item>Do not import from apps/* or astro:content.</item>
+  <item>Do not perform runtime data fetching or API interactions.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial extraction from app content schemas/pages/base into packages/share.</item>
+  <item>Switched import from "astro/zod" to "zod" so the package is Astro-agnostic.</item>
+</CHANGE_SUMMARY>
+*/
+
+// [RFC-0004] Shared base fields for all page schemas.
+// Extracted to packages/share to prevent copy-paste across apps.
+// Import z from "zod" — not "astro/zod" — so this package stays framework-neutral.
+
+import { z } from "zod";
+
+// componentOverrides: a map of component paths to partial content objects.
+// Pages use this to override default component copy from frontmatter,
+// keeping .astro route files thin and copy-free.
+export const componentOverridesSchema = z
+  .record(z.string(), z.record(z.string(), z.unknown()))
+  .optional();
+
+export type ComponentOverrides = z.infer<typeof componentOverridesSchema>;