@warpgogol/werkstatt-shared 0.2.0

package/src/share/schemas/participant.ts

@@ -0,0 +1,247 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0508: canonical Participant schema — a unified entity model for humans, AI agents,
+organization units, external specialists, partner organizations, and service accounts.
+Extends the People collection (RFC-0200) with type-specific responsibility/authority/evidence
+fields, lifecycle statuses, consent records for humans, and public/private visibility.
+</purpose>
+<non-goals>
+  <item>Do not define route generation or page rendering logic — that lives in @warpgogol/werkstatt-site/share/astro.</item>
+  <item>Do not define validation rules — that lives in @warpgogol/werkstatt-site/checks/src/participant.ts.</item>
+  <item>Do not remove PERSON_AFFILIATIONS from person.ts — it is retained for human governance JSON-LD.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0508: initial creation — Participant schema with six types, statuses, relationships, consent, and type-specific fields.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+import { PERSON_AFFILIATIONS } from "./person.ts";
+
+export const PARTICIPANT_TYPES = [
+  "human",
+  "ai-agent",
+  "organization-unit",
+  "external-specialist",
+  "partner-organization",
+  "service-account",
+] as const;
+export type ParticipantType = (typeof PARTICIPANT_TYPES)[number];
+
+export const PARTICIPANT_RELATIONSHIPS = [
+  "founder",
+  "board",
+  "team",
+  "patron",
+  "author",
+  "advisor",
+  "contractor",
+  "partner",
+  "service",
+] as const;
+export type ParticipantRelationship = (typeof PARTICIPANT_RELATIONSHIPS)[number];
+
+export const PARTICIPANT_STATUSES = [
+  "active",
+  "temporarily-unavailable",
+  "on-leave",
+  "former",
+  "retired",
+  "suspended",
+  "draft",
+] as const;
+export type ParticipantStatus = (typeof PARTICIPANT_STATUSES)[number];
+
+export const CONSENT_APPROVED_FIELDS = [
+  "lifespan.born",
+  "lifespan.died",
+  "location",
+  "bio",
+  "photo",
+  "sameAs",
+] as const;
+export type ConsentApprovedField = (typeof CONSENT_APPROVED_FIELDS)[number];
+
+const consentSchema = z
+  .object({
+    consentRecordId: z.string().min(1),
+    approvedFields: z.array(z.enum(CONSENT_APPROVED_FIELDS)).default([]),
+    approvedMedia: z.array(z.string()).default([]),
+    consentDate: z.string().min(1),
+    withdrawalRoute: z.string().min(1).optional(),
+    profileReviewer: z.string().min(1),
+  })
+  .strict();
+
+const responsibilitySchema = z
+  .object({
+    summary: z.string(),
+    scope: z.string().optional(),
+    pbpReferences: z.array(z.string()).default([]),
+  })
+  .strict();
+
+const authoritySchema = z
+  .object({
+    canSignFor: z.array(z.string()).default([]),
+    canCommitTo: z.array(z.string()).default([]),
+    escalationRoute: z.string().optional(),
+  })
+  .strict();
+
+const evidenceSchema = z
+  .object({
+    claims: z
+      .array(
+        z
+          .object({
+            claimId: z.string(),
+            sourceRef: z.string(),
+            verifiedAt: z.string(),
+          })
+          .strict(),
+      )
+      .default([]),
+    disclosures: z
+      .array(
+        z
+          .object({
+            type: z.string(),
+            text: z.string(),
+            url: z.string().optional(),
+          })
+          .strict(),
+      )
+      .default([]),
+  })
+  .strict();
+
+const contactSchema = z
+  .object({
+    primaryRoute: z.string().optional(),
+    pgpFingerprint: z.string().optional(),
+    responseTime: z.string().optional(),
+  })
+  .strict();
+
+const lifespanSchema = z
+  .object({
+    born: z.union([z.string(), z.number()]).optional(),
+    died: z.union([z.string(), z.number()]).optional(),
+  })
+  .strict();
+
+const aiAgentFieldsSchema = z
+  .object({
+    modelId: z.string(),
+    provider: z.string(),
+    technicalStand: z
+      .object({
+        agentId: z.string(),
+        toolsetVersion: z.string(),
+        lastEvaluatedAt: z.string(),
+        capabilities: z.array(z.string()).default([]),
+      })
+      .strict(),
+    rightsMatrix: z
+      .object({
+        canPublish: z.boolean().default(false),
+        canEditContent: z.boolean().default(false),
+        canManageUsers: z.boolean().default(false),
+        canAccessFinancials: z.boolean().default(false),
+      })
+      .strict(),
+    accountableHumanId: z.string().min(1),
+  })
+  .strict();
+
+const organizationUnitFieldsSchema = z
+  .object({
+    unitName: z.string(),
+    parentUnit: z.string().optional(),
+    leadParticipantId: z.string().optional(),
+  })
+  .strict();
+
+const externalSpecialistFieldsSchema = z
+  .object({
+    specialty: z.string(),
+    organization: z.string().optional(),
+    engagementType: z.string().optional(),
+    contractRef: z.string().optional(),
+  })
+  .strict();
+
+const partnerOrganizationFieldsSchema = z
+  .object({
+    organizationName: z.string(),
+    partnershipType: z.string().optional(),
+    contactRoute: z.string().optional(),
+  })
+  .strict();
+
+const serviceAccountFieldsSchema = z
+  .object({
+    serviceName: z.string(),
+    provider: z.string(),
+    scopeDescription: z.string(),
+    credentialsRef: z.string(),
+  })
+  .strict();
+
+export const participantSchema = z
+  .object({
+    participantId: z.string().min(1),
+    participantType: z.enum(PARTICIPANT_TYPES),
+    publicName: z.string().min(1),
+    slug: z.string().min(1),
+    status: z.enum(PARTICIPANT_STATUSES),
+    relationshipType: z.enum(PARTICIPANT_RELATIONSHIPS),
+
+    responsibility: responsibilitySchema.optional(),
+    authority: authoritySchema.optional(),
+    evidence: evidenceSchema.optional(),
+    contact: contactSchema.optional(),
+
+    visibility: z.enum(["public", "private"]).default("private"),
+    profileOwner: z.string().optional(),
+    retentionClass: z.enum(["permanent", "standard", "short-term"]).default("standard"),
+
+    name: z.string().optional(),
+    role: z.string().optional(),
+    photo: z.string().optional(),
+    bio: z.string().optional(),
+    affiliations: z.array(z.enum(PERSON_AFFILIATIONS)).default([]),
+    order: z.number().int().nonnegative().optional(),
+    lifespan: lifespanSchema.optional(),
+    statement: z.string().optional(),
+    stats: z.array(z.object({ label: z.string(), value: z.string() }).strict()).optional(),
+    cta: z.object({ label: z.string(), target: z.string() }).strict().optional(),
+    sameAs: z.array(z.string().url()).optional(),
+    page: z
+      .object({ enabled: z.boolean().default(false) })
+      .strict()
+      .optional(),
+    location: z.string().optional(),
+    live: z
+      .object({
+        src: z.string(),
+        poster: z.string().optional(),
+        alt: z.string().optional(),
+      })
+      .strict()
+      .optional(),
+
+    consent: consentSchema.optional(),
+
+    aiAgent: aiAgentFieldsSchema.optional(),
+    organizationUnit: organizationUnitFieldsSchema.optional(),
+    externalSpecialist: externalSpecialistFieldsSchema.optional(),
+    partnerOrganization: partnerOrganizationFieldsSchema.optional(),
+    serviceAccount: serviceAccountFieldsSchema.optional(),
+  })
+  .strict();
+
+export type ParticipantData = z.infer<typeof participantSchema>;

package/src/share/schemas/person.ts

@@ -0,0 +1,24 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0200: closed affiliation vocabulary for Person records. Used by the People
+section check in @warpgogol/site-kernel-checks to validate person affiliations.
+This is a closed vocabulary used by check infrastructure, not PBP entity code.
+</purpose>
+<non-goals>
+  <item>Do not export the full personSchema — person records now live in a standalone `people` content collection (RFC-0471).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0470: moved PERSON_AFFILIATIONS from @warpgogol/business/schemas/person.ts to @warpgogol/werkstatt-shared/share/schemas/person.ts.</item>
+  <item>RFC-0471: @warpgogol/business package deleted. Person records now live in a standalone `people` content collection.</item>
+</CHANGE_SUMMARY>
+*/
+
+/**
+ * Closed affiliation vocabulary. `founder` → Organization.founder, `board` →
+ * Organization.member (governance), `team`/`patron`/`author` are presentational
+ * roles shown in the People section but not governance JSON-LD.
+ */
+export const PERSON_AFFILIATIONS = ["founder", "board", "team", "patron", "author"] as const;
+export type PersonAffiliation = (typeof PERSON_AFFILIATIONS)[number];

package/src/share/schemas/print.ts

@@ -0,0 +1,93 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0257: TypeScript contracts for the print-ready visitor-page system.
+Defines page-level print config, site-level print labels, and the PDF generator
+result shape. Consumed by @warpgogol/werkstatt-shared/ontology schemas, @warpgogol/werkstatt-site/ui layout, and
+@warpgogol/site-kernel-checks validators.
+</purpose>
+<non-goals>
+  <item>Do not implement Zod schemas here — @warpgogol/werkstatt-shared/ontology owns the Zod validation schemas.</item>
+  <item>Do not import from Astro or app-specific modules.</item>
+  <item>Do not define runtime print detection logic — that lives in @warpgogol/werkstatt-site/ui.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0257: Initial creation — print content contracts for page frontmatter, site labels, and PDF generator result.</item>
+</CHANGE_SUMMARY>
+*/
+
+// ---------------------------------------------------------------------------
+// Closed enums
+// ---------------------------------------------------------------------------
+
+export const PRINT_ORIENTATIONS = ["portrait", "landscape", "auto"] as const;
+export type PrintOrientation = (typeof PRINT_ORIENTATIONS)[number];
+
+export const PRINT_PAGE_SIZES = ["a4", "letter", "legal"] as const;
+export type PrintPageSize = (typeof PRINT_PAGE_SIZES)[number];
+
+export const PRINT_MARGINS = ["normal", "narrow", "none"] as const;
+export type PrintMargins = (typeof PRINT_MARGINS)[number];
+
+export const PRINT_BACKGROUND_MODES = ["preserve", "flatten"] as const;
+export type PrintBackgroundMode = (typeof PRINT_BACKGROUND_MODES)[number];
+
+export const PRINT_REGIONS = [
+  "navigation",
+  "breadcrumbs",
+  "cta",
+  "footer-links",
+  "header-logo",
+  "site-background",
+  "hero-animation",
+] as const;
+export type PrintRegion = (typeof PRINT_REGIONS)[number];
+
+// ---------------------------------------------------------------------------
+// Page-level print config (frontmatter `print:` block)
+// ---------------------------------------------------------------------------
+
+export interface PagePrintConfig {
+  /** When false, no PDF is generated and the browser print shows a disabled notice. Default: true. */
+  enabled?: boolean;
+  /** Print orientation. Default: auto (generator picks best fit). */
+  orientation?: PrintOrientation;
+  /** Page size passed to Playwright. Default: a4. */
+  pageSize?: PrintPageSize;
+  /** Margin preset. Default: normal. */
+  margins?: PrintMargins;
+  /** When true, expand all <details> before PDF capture. Default: true. */
+  expandDetails?: boolean;
+  /** Screen regions to suppress in print. Default: []. */
+  hide?: PrintRegion[];
+  /** Background handling: preserve keeps images/colors, flatten replaces with neutral surface. Default: preserve. */
+  background?: PrintBackgroundMode;
+}
+
+// ---------------------------------------------------------------------------
+// Site-level print labels (site/{lang}/labels.md `print:` block)
+// ---------------------------------------------------------------------------
+
+export interface SitePrintLabels {
+  headerLogo?: string;
+  headerBrandLabel?: string;
+  headerTagline?: string;
+  footerLegalNotice?: string;
+  footerShowUrl?: boolean;
+  footerShowDate?: boolean;
+  footerPageNumberLabel?: string;
+  printDisabledNotice?: string;
+}
+
+// ---------------------------------------------------------------------------
+// PDF generator result (print.pdf.generate command output)
+// ---------------------------------------------------------------------------
+
+export interface PrintPdfGenerateResult {
+  generated: number;
+  skipped: number;
+  disabled: number;
+  errors: Array<{ route: string; error: string }>;
+  outputDir: string;
+}

package/src/share/schemas/section-background.ts

@@ -0,0 +1,106 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+[RFC-0101] Canonical SectionBackground discriminated union. Replaces flat
+visual-modifier props (texture / transparent / opacity / verticalFade /
+noTopFade / noBottomFade / topVerticalFadeOpacity / bottomVerticalFadeOpacity)
+across every shared section in packages/ui. Section background is strictly
+independent from the global SiteBackground shell block (RFC-0105).
+</purpose>
+<non-goals>
+  <item>Do not include glass effect here (lives in ./glass.ts).</item>
+  <item>Do not absorb the full-viewport SiteBackground shell layer (RFC-0105).</item>
+  <item>Do not parse image assets; <SectionShell> + <SectionImage> own that.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0133: backfilled MODULE_MAP and CHANGE_SUMMARY markers for compass.validate compliance.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+const cssValueOrToken = z.string().min(1);
+
+/** RFC-0101 — kind: "color". Solid colour background using a CSS token or value. */
+const sectionBackgroundColorSchema = z
+  .object({
+    kind: z.literal("color"),
+    /** Defaults to var(--ds-color-bg) when omitted. */
+    color: cssValueOrToken.optional(),
+  })
+  .strict();
+
+/** RFC-0101 — kind: "image". Image background with fit + quality + optional tint overlay. */
+const sectionBackgroundImageSchema = z
+  .object({
+    kind: z.literal("image"),
+    /** Bare image name (RFC-0053); resolved by <SectionShell> via shared image utils. */
+    imageName: z.string().min(1),
+    fit: z.enum(["cover", "tile", "stretch-width", "stretch-height"]).optional(),
+    quality: z.enum(["low", "mid", "high", "max"]).optional(),
+    /** 0..1; tint overlay opacity using --ds-color-bg above the image. */
+    tintOpacity: z.number().min(0).max(1).optional(),
+  })
+  .strict();
+
+/** RFC-0101 — kind: "texture". Repeating texture pattern (e.g. noise) layered over color. */
+const sectionBackgroundTextureSchema = z
+  .object({
+    kind: z.literal("texture"),
+    /** Texture id — "noise" is the only built-in for now. */
+    texture: z.string().min(1),
+  })
+  .strict();
+
+/** RFC-0101 — kind: "transparent". Lets the SiteBackground (RFC-0105) show through. */
+const sectionBackgroundTransparentSchema = z
+  .object({
+    kind: z.literal("transparent"),
+    /** Optional tint opacity (0 = fully transparent, 1 = fully opaque --ds-color-bg). */
+    opacity: z.number().min(0).max(1).optional(),
+  })
+  .strict();
+
+/**
+ * RFC-0101 — kind: "fade". Linear gradient along one axis. Replaces the
+ * legacy verticalFade / noTopFade / noBottomFade / topVerticalFadeOpacity /
+ * bottomVerticalFadeOpacity permutation matrix with a single parameterised
+ * gradient. Per the accepted RFC, direction is restricted to vertical |
+ * horizontal (no diagonal / radial).
+ */
+const sectionBackgroundFadeSchema = z
+  .object({
+    kind: z.literal("fade"),
+    direction: z.enum(["vertical", "horizontal"]),
+    /** Start colour token / value. Defaults to var(--ds-color-bg). */
+    from: cssValueOrToken.optional(),
+    /** End colour token / value. Defaults to var(--ds-color-bg). */
+    to: cssValueOrToken.optional(),
+    /** 0..1; opacity of the gradient at the start edge. Default 1. */
+    startOpacity: z.number().min(0).max(1).optional(),
+    /** 0..1; opacity of the gradient at the end edge. Default 1. */
+    endOpacity: z.number().min(0).max(1).optional(),
+    /** 0..0.5; plateau width fraction. Default 0.2. */
+    inset: z.number().min(0).max(0.5).optional(),
+    /** Suppress fade at the start edge. */
+    noStartFade: z.boolean().optional(),
+    /** Suppress fade at the end edge. */
+    noEndFade: z.boolean().optional(),
+  })
+  .strict();
+
+export const sectionBackgroundSchema = z.discriminatedUnion("kind", [
+  sectionBackgroundColorSchema,
+  sectionBackgroundImageSchema,
+  sectionBackgroundTextureSchema,
+  sectionBackgroundTransparentSchema,
+  sectionBackgroundFadeSchema,
+]);
+
+export type SectionBackgroundColor = z.infer<typeof sectionBackgroundColorSchema>;
+export type SectionBackgroundImage = z.infer<typeof sectionBackgroundImageSchema>;
+export type SectionBackgroundTexture = z.infer<typeof sectionBackgroundTextureSchema>;
+export type SectionBackgroundTransparent = z.infer<typeof sectionBackgroundTransparentSchema>;
+export type SectionBackgroundFade = z.infer<typeof sectionBackgroundFadeSchema>;
+export type SectionBackground = z.infer<typeof sectionBackgroundSchema>;

package/src/share/schemas/section-body.ts

@@ -0,0 +1,138 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+[RFC-0103 + RFC-0134] Canonical SectionBodyContent discriminated union. One shape covers
+every non-composite body kind: list / split-list / stats / cards / paragraphs /
+comparison / rich. Body-level visual effects are authored through composable
+`effects[]` assignments rather than legacy surface-specific props.
+</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0133: backfilled MODULE_MAP and CHANGE_SUMMARY markers for compass.validate compliance.</item>
+  <item>RFC-0134 replaces legacy surface config with composable effects assignments on supported body kinds.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+import { effectsSchema } from "./effects.ts";
+import { horizontalAlignSchema } from "./horizontal-align.ts";
+import { iconColorSchema } from "./icon-color.ts";
+import { standardListItemSchema } from "./standard-list-item.ts";
+import { standardCardSchema } from "./section-cards.ts";
+import { statItemSchema } from "./section-stats.ts";
+
+export const sectionBodyKindSchema = z.enum([
+  "list",
+  "split-list",
+  "stats",
+  "cards",
+  "paragraphs",
+  "comparison",
+  "rich",
+  "composite",
+]);
+export type SectionBodyKind = z.infer<typeof sectionBodyKindSchema>;
+
+const listBodySchema = z
+  .object({
+    kind: z.literal("list"),
+    items: z.array(standardListItemSchema).min(1),
+    note: z.string().optional(),
+    iconColor: iconColorSchema.optional(),
+    align: horizontalAlignSchema.optional(),
+    itemAlign: horizontalAlignSchema.optional(),
+    hideMarkers: z.boolean().optional(),
+    effects: effectsSchema.optional(),
+  })
+  .strict();
+
+const splitListBodySchema = z
+  .object({
+    kind: z.literal("split-list"),
+    primaryItems: z.array(standardListItemSchema).min(1),
+    secondaryItems: z.array(standardListItemSchema).optional(),
+    labels: z
+      .object({
+        primary: z.string().min(1),
+        secondary: z.string().min(1),
+      })
+      .optional(),
+    iconColors: z
+      .object({
+        primary: iconColorSchema.optional(),
+        secondary: iconColorSchema.optional(),
+      })
+      .optional(),
+    align: horizontalAlignSchema.optional(),
+    effects: effectsSchema.optional(),
+  })
+  .strict();
+
+const statsBodySchema = z
+  .object({
+    kind: z.literal("stats"),
+    stats: z.array(statItemSchema).min(1),
+    animated: z.boolean().optional(),
+    align: horizontalAlignSchema.optional(),
+  })
+  .strict();
+
+const cardsBodySchema = z
+  .object({
+    kind: z.literal("cards"),
+    cards: z.array(standardCardSchema).min(1),
+    layout: z.enum(["grid", "list"]).optional(),
+    columns: z.union([z.literal(2), z.literal(3), z.literal(4)]).optional(),
+    align: horizontalAlignSchema.optional(),
+    effects: effectsSchema.optional(),
+  })
+  .strict();
+
+const paragraphsBodySchema = z
+  .object({
+    kind: z.literal("paragraphs"),
+    paragraphs: z.array(z.string().min(1)).min(1),
+    align: horizontalAlignSchema.optional(),
+  })
+  .strict();
+
+const comparisonBodySchema = z
+  .object({
+    kind: z.literal("comparison"),
+    rows: z.array(z.object({ left: z.string().min(1), right: z.string().min(1) }).strict()).min(1),
+    labels: z.object({ left: z.string().min(1), right: z.string().min(1) }).optional(),
+    align: horizontalAlignSchema.optional(),
+    effects: effectsSchema.optional(),
+  })
+  .strict();
+
+const richBodySchema = z
+  .object({
+    kind: z.literal("rich"),
+    contentRef: z.string().min(1),
+    animateNumbers: z.boolean().optional(),
+    align: horizontalAlignSchema.optional(),
+  })
+  .strict();
+
+export const sectionBodyContentSchema = z.discriminatedUnion("kind", [
+  listBodySchema,
+  splitListBodySchema,
+  statsBodySchema,
+  cardsBodySchema,
+  paragraphsBodySchema,
+  comparisonBodySchema,
+  richBodySchema,
+]);
+
+export type SectionListBody = z.infer<typeof listBodySchema>;
+export type SectionSplitListBody = z.infer<typeof splitListBodySchema>;
+export type SectionStatsBody = z.infer<typeof statsBodySchema>;
+export type SectionCardsBody = z.infer<typeof cardsBodySchema>;
+export type SectionParagraphsBody = z.infer<typeof paragraphsBodySchema>;
+export type SectionComparisonBody = z.infer<typeof comparisonBodySchema>;
+export type SectionRichBody = z.infer<typeof richBodySchema>;
+export type SectionBodyContent = z.infer<typeof sectionBodyContentSchema>;

package/src/share/schemas/section-cards.ts

@@ -0,0 +1,37 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+[RFC-0103] Canonical StandardCard schema consumed by <SectionCardGrid>. Unifies
+the four ad-hoc card shapes that used to live in `approach`, `audience-cards`,
+`donation-use`, `team` (PersonProfile keeps a richer shape because it owns
+animation hooks).
+</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0133: backfilled MODULE_MAP and CHANGE_SUMMARY markers for compass.validate compliance.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+import { vendorIconConfigSchema } from "./standard-list-item.ts";
+
+export const standardCardSchema = z
+  .object({
+    title: z.string(),
+    description: z.string().optional(),
+    /** Bare image name (RFC-0053); resolved by <SectionImage> at render. */
+    image: z.string().optional(),
+    imageAlt: z.string().optional(),
+    icon: vendorIconConfigSchema.optional(),
+    /** Optional internal pageId or anchor target — turns the card into a link. */
+    href: z.string().optional(),
+    badge: z.string().optional(),
+    /** Optional number display for the card (e.g., "01", "02") */
+    number: z.string().optional(),
+  })
+  .strict();
+
+export type StandardCard = z.infer<typeof standardCardSchema>;