@warpgogol/werkstatt-shared 0.2.0

package/src/ontology/shared-section-props/visual-header.ts

@@ -0,0 +1,163 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Section visual and header JSON Schema fragments for RFC-0101/RFC-0102: visual sub-schemas and header sub-schemas applied at section root.</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-0303 Phase 3: extracted from shared-section-props/index.ts as part of the domain split.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { EFFECT_STACK_ITEM_SCHEMA, ALIGN_ENUM, type JsonSchemaFragment } from "./common.ts";
+
+/** RFC-0101 — section visual contract (background / effects / density / tone / containerVariant / motion). */
+export const SECTION_VISUAL_FRAGMENT: JsonSchemaFragment = {
+  properties: {
+    background: {
+      oneOf: [
+        {
+          type: "object",
+          additionalProperties: false,
+          required: ["kind"],
+          properties: {
+            kind: { const: "color" },
+            color: { type: "string", minLength: 1 },
+          },
+        },
+        {
+          type: "object",
+          additionalProperties: false,
+          required: ["kind", "imageName"],
+          properties: {
+            kind: { const: "image" },
+            imageName: { type: "string", minLength: 1 },
+            fit: { enum: ["cover", "tile", "stretch-width", "stretch-height"] },
+            quality: { enum: ["low", "mid", "high", "max"] },
+            tintOpacity: { type: "number", minimum: 0, maximum: 1 },
+          },
+        },
+        {
+          type: "object",
+          additionalProperties: false,
+          required: ["kind", "texture"],
+          properties: {
+            kind: { const: "texture" },
+            texture: { type: "string", minLength: 1 },
+          },
+        },
+        {
+          type: "object",
+          additionalProperties: false,
+          required: ["kind"],
+          properties: { kind: { const: "transparent" } },
+        },
+        {
+          type: "object",
+          additionalProperties: false,
+          required: ["kind", "direction"],
+          properties: {
+            kind: { const: "fade" },
+            direction: { enum: ["vertical", "horizontal"] },
+            from: { type: "string", minLength: 1 },
+            to: { type: "string", minLength: 1 },
+            startOpacity: { type: "number", minimum: 0, maximum: 1 },
+            endOpacity: { type: "number", minimum: 0, maximum: 1 },
+            inset: { type: "number", minimum: 0, maximum: 0.5 },
+            noStartFade: { type: "boolean" },
+            noEndFade: { type: "boolean" },
+          },
+        },
+      ],
+    },
+    effects: {
+      type: "array",
+      minItems: 1,
+      items: {
+        type: "object",
+        additionalProperties: false,
+        required: ["target", "stack"],
+        properties: {
+          target: { type: "string", minLength: 1 },
+          stack: {
+            type: "array",
+            minItems: 1,
+            items: EFFECT_STACK_ITEM_SCHEMA,
+          },
+        },
+      },
+    },
+    density: { enum: ["compact", "normal", "spacious"] },
+    tone: { enum: ["default", "warning", "success", "muted"] },
+    containerVariant: { enum: ["default", "narrow", "full"] },
+    motion: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        reveal: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            variant: { enum: ["fade", "fade-up", "fade-up-stagger"] },
+            once: { type: "boolean" },
+            threshold: { type: "number", minimum: 0, maximum: 1 },
+          },
+        },
+        parallax: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            variant: { enum: ["subtle", "balanced", "dramatic"] },
+            speed: { type: "number", minimum: 0, maximum: 2 },
+          },
+        },
+        stagger: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            delay: { type: "number", minimum: 0, maximum: 2 },
+            childSelector: { type: "string" },
+          },
+        },
+        off: { type: "boolean" },
+      },
+    },
+  },
+};
+
+/** RFC-0102 — section header (tone-segmented heading + optional subheading + alignment + level). */
+export const SECTION_HEADER_FRAGMENT: JsonSchemaFragment = {
+  properties: {
+    header: {
+      type: "object",
+      additionalProperties: false,
+      required: ["heading"],
+      properties: {
+        heading: {
+          oneOf: [
+            { type: "string", minLength: 1 },
+            {
+              type: "array",
+              minItems: 1,
+              items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["text"],
+                properties: {
+                  text: { type: "string", minLength: 1 },
+                  tone: { enum: ["default", "primary", "accent", "muted", "inverse"] },
+                },
+              },
+            },
+          ],
+        },
+        eyebrow: { type: "string", minLength: 1 },
+        subheading: { type: "string", minLength: 1 },
+        align: ALIGN_ENUM,
+        level: { enum: [1, 2] },
+        hideSectionNumber: { type: "boolean" },
+      },
+    },
+  },
+};

package/src/ontology/site-families/charity-donation-trust/cultural-rules.yaml

@@ -0,0 +1,6 @@
+family: charity-donation-trust
+version: 1.0.0
+rules:
+  - Respect beneficiary dignity; avoid savior framing.
+  - Prefer concrete local context over abstract global heroics.
+  - Do not imply moral failure if the visitor does not donate.

package/src/ontology/site-families/charity-donation-trust/family.yaml

@@ -0,0 +1,44 @@
+id: charity-donation-trust
+displayName: Charity · Donation trust
+version: 1.0.0
+description: |
+  Donation-first trust system for mission-driven nonprofits. Emphasizes mission clarity,
+  impact proof, transparent fund allocation, and a single primary ask.
+
+detection:
+  signals:
+    archetypePrimary: donation-funnel
+    audienceAny: [donors, supporters, volunteers]
+    conversionPrimary: donation-intent
+    materialMentionsAny: [donation, transparency, recurring-support]
+  threshold: 0.7
+
+recipe:
+  candidateBiomes:
+    - nonprofit-trust
+  candidateConstellations:
+    - nonprofit-donation-funnel
+  requiredSectionArchetypes:
+    # Remapped 2026-05-29 from placeholder names to the existing archetype YAMLs
+    # under packages/ontology/archetypes/sections/ (see RFC-0131).
+    - hero
+    - impact
+    - donation-use
+    - final-cta
+  conversionGoals:
+    primary:
+      id: donation-confirmation
+      eventName: donation-confirmed
+    secondary:
+      - id: donation-intent
+        eventName: donation-intent
+      - id: contact-submitted
+        eventName: contact-submit
+  auditThresholds:
+    transparencyVisible: required
+    impactProofVisible: required
+    singlePrimaryAsk: required
+    testimonialPresent: warn
+  agentReadinessBaseline:
+    maxBytesToCta: 4096
+    requireStructuredData: [Organization, FAQPage]

package/src/ontology/site-families/charity-donation-trust/linguistic-rules.yaml

@@ -0,0 +1,6 @@
+family: charity-donation-trust
+version: 1.0.0
+rules:
+  - Use plain-language fundraising copy.
+  - Prefer short declarative sentences near CTAs.
+  - Ban unverifiable absolutes such as "guaranteed impact".

package/src/ontology/site-families/check-quality-operator/cultural-rules.yaml

@@ -0,0 +1,6 @@
+family: check-quality-operator
+version: 1.0.0
+rules:
+  - "URL-first framing: the visitor brings a URL, not a business problem."
+  - Show what the check covers before asking for action.
+  - "Reports must be concrete and actionable, not vanity scores."

package/src/ontology/site-families/check-quality-operator/family.yaml

@@ -0,0 +1,40 @@
+id: check-quality-operator
+displayName: Check · Quality-operator
+version: 1.0.0
+description: |
+  Trust system for URL-first website-quality operators. The visitor arrives
+  with a URL, understands what the check covers, and runs or requests a
+  concrete quality audit with an actionable report. No Handwerk conversion
+  funnel, no donation ask — the primary action is "run the check".
+
+detection:
+  signals:
+    archetypePrimary: quality-audit-tool
+    audienceAny: [webmasters, operators, agencies]
+    conversionPrimary: check-initiated
+    materialMentionsAny: [url-check, quality-report, action-pack, audit]
+  threshold: 0.7
+
+recipe:
+  candidateBiomes:
+    - check-concrete-blueprint
+  candidateConstellations:
+    - check-quality-landing
+  requiredSectionArchetypes:
+    - hero
+  conversionGoals:
+    primary:
+      id: check-initiated
+      eventName: check-started
+    secondary:
+      - id: report-downloaded
+        eventName: report-downloaded
+      - id: faq-engagement
+        eventName: faq-question-opened
+  auditThresholds:
+    urlFirstFraming: required
+    actionPackVisible: required
+    testimonialPresent: forbidden
+  agentReadinessBaseline:
+    maxBytesToCta: 4096
+    requireStructuredData: [Organization, FAQPage]

package/src/ontology/site-families/check-quality-operator/linguistic-rules.yaml

@@ -0,0 +1,6 @@
+family: check-quality-operator
+version: 1.0.0
+rules:
+  - Prefer precise technical German over marketing language.
+  - Ban vague quality claims without evidence.
+  - Use direct, operational phrasing near CTAs.

package/src/ontology/site-families/handwerk-trust-engineering/cultural-rules.yaml

@@ -0,0 +1,6 @@
+family: handwerk-trust-engineering
+version: 1.0.0
+rules:
+  - Respect German Handwerk norms: practical proof beats visionary abstraction.
+  - Do not use startup-style disruption language.
+  - Make ownership, exit terms, and responsibilities explicit.

package/src/ontology/site-families/handwerk-trust-engineering/family.yaml

@@ -0,0 +1,53 @@
+id: handwerk-trust-engineering
+displayName: Handwerk · Trust-engineering
+version: 1.0.0
+description: |
+  B2B trust system for small German Handwerk businesses. Founder-led,
+  written-conditions-first, vendor-lock-in-averse. Conversion is a written
+  inquiry; lead-count and ROI promises are forbidden.
+
+detection:
+  signals:
+    archetypePrimary: b2b-trust-system
+    audienceAny: [handwerker, maler-lackierer, kleinunternehmen]
+    conversionPrimary: qualified-project-inquiry
+    materialMentionsAny: [notausgang, vendor-lock-in, controlled-responsibility]
+  threshold: 0.7
+
+recipe:
+  candidateBiomes:
+    - handwerk-material-warm
+  candidateConstellations:
+    - handwerk-trust-funnel
+  requiredSectionArchetypes:
+    - hero-decision-card
+    - video-section
+    - trust-strip
+    - comparison-cards
+    - audience-cards
+    - ownership-block
+    - notausgang-block
+    - controlled-responsibility-block
+    - price-card
+    - people
+    - faq-list
+    - final-cta
+  conversionGoals:
+    primary:
+      id: qualified-inquiry
+      eventName: inquiry-submitted
+    secondary:
+      - id: faq-engagement
+        eventName: faq-question-opened
+      - id: price-page-read
+        eventName: scroll-depth-80
+  auditThresholds:
+    forbiddenROIPromise: error
+    forbiddenLeadCountGuarantee: error
+    notausgangVisible: required
+    priceVisible: required
+    founderIdentified: required
+    testimonialPresent: forbidden
+  agentReadinessBaseline:
+    maxBytesToCta: 4096
+    requireStructuredData: [Organization, FAQPage, Service]

package/src/ontology/site-families/handwerk-trust-engineering/linguistic-rules.yaml

@@ -0,0 +1,6 @@
+family: handwerk-trust-engineering
+version: 1.0.0
+rules:
+  - Prefer concrete business German over slogan language.
+  - Ban ROI guarantees and lead-count promises.
+  - Use direct, written-condition phrasing near CTAs and pricing.

package/src/ontology/tests/catalogs.pbt.test.ts

@@ -0,0 +1,89 @@
+import { test, expect } from "vitest";
+import fc from "fast-check";
+import { StarCatalog, starNameSchema } from "../cosmic/star-catalog.ts";
+import { PlanetCatalog, planetNameSchema } from "../cosmic/planet-catalog.ts";
+import { MoonCatalog, moonNameSchema } from "../cosmic/moon-catalog.ts";
+import { cosmicNameSchema } from "../cosmic/index.ts";
+import {
+  LayerValues,
+  layerSchema,
+  ComponentRoleValues,
+  componentRoleSchema,
+  IndustryValues,
+  industrySchema,
+} from "../enums.ts";
+
+test("PBT: any star from the catalog passes starNameSchema", () => {
+  fc.assert(
+    fc.property(fc.constantFrom(...StarCatalog), (star) => {
+      expect(starNameSchema.safeParse(star).success).toBe(true);
+    }),
+  );
+});
+
+test("PBT: any planet from the catalog passes planetNameSchema", () => {
+  fc.assert(
+    fc.property(fc.constantFrom(...PlanetCatalog), (planet) => {
+      expect(planetNameSchema.safeParse(planet).success).toBe(true);
+    }),
+  );
+});
+
+test("PBT: any moon from the catalog passes moonNameSchema", () => {
+  fc.assert(
+    fc.property(fc.constantFrom(...MoonCatalog), (moon) => {
+      expect(moonNameSchema.safeParse(moon).success).toBe(true);
+    }),
+  );
+});
+
+test("PBT: any cosmic name passes cosmicNameSchema", () => {
+  const allCosmic = [...StarCatalog, ...PlanetCatalog, ...MoonCatalog];
+  fc.assert(
+    fc.property(fc.constantFrom(...allCosmic), (name) => {
+      expect(cosmicNameSchema.safeParse(name).success).toBe(true);
+    }),
+  );
+});
+
+test("PBT: any Layer value passes layerSchema", () => {
+  fc.assert(
+    fc.property(fc.constantFrom(...LayerValues), (v) => {
+      expect(layerSchema.safeParse(v).success).toBe(true);
+    }),
+  );
+});
+
+test("PBT: any ComponentRole value passes componentRoleSchema", () => {
+  fc.assert(
+    fc.property(fc.constantFrom(...ComponentRoleValues), (v) => {
+      expect(componentRoleSchema.safeParse(v).success).toBe(true);
+    }),
+  );
+});
+
+test("PBT: any Industry value passes industrySchema", () => {
+  fc.assert(
+    fc.property(fc.constantFrom(...IndustryValues), (v) => {
+      expect(industrySchema.safeParse(v).success).toBe(true);
+    }),
+  );
+});
+
+test("PBT: random non-cosmic strings fail cosmicNameSchema", () => {
+  fc.assert(
+    fc.property(
+      fc
+        .string({ minLength: 1 })
+        .filter(
+          (s) =>
+            !StarCatalog.includes(s as never) &&
+            !PlanetCatalog.includes(s as never) &&
+            !MoonCatalog.includes(s as never),
+        ),
+      (s) => {
+        expect(cosmicNameSchema.safeParse(s).success).toBe(false);
+      },
+    ),
+  );
+});

package/src/ontology/tests/enums.test.ts

@@ -0,0 +1,203 @@
+import { test, expect, describe } from "vitest";
+import {
+  LayerValues,
+  layerSchema,
+  ComponentRoleValues,
+  componentRoleSchema,
+  IndustryValues,
+  industrySchema,
+  IndustryLabels,
+} from "../enums.ts";
+import { StarCatalog, starNameSchema } from "../cosmic/star-catalog.ts";
+import { PlanetCatalog, planetNameSchema } from "../cosmic/planet-catalog.ts";
+import { MoonCatalog, moonNameSchema } from "../cosmic/moon-catalog.ts";
+import { cosmicNameSchema } from "../cosmic/index.ts";
+
+describe("Layer enum", () => {
+  test("has exactly 3 values", () => {
+    expect(LayerValues).toHaveLength(3);
+  });
+
+  test("contains page, section, component", () => {
+    expect([...LayerValues].sort()).toEqual(["component", "page", "section"]);
+  });
+
+  test("schema accepts valid values", () => {
+    expect(layerSchema.safeParse("page").success).toBe(true);
+    expect(layerSchema.safeParse("section").success).toBe(true);
+    expect(layerSchema.safeParse("component").success).toBe(true);
+  });
+
+  test("schema rejects invalid values", () => {
+    expect(layerSchema.safeParse("layout").success).toBe(false);
+    expect(layerSchema.safeParse("").success).toBe(false);
+  });
+});
+
+describe("ComponentRole enum", () => {
+  test("contains section framework primitives", () => {
+    expect(ComponentRoleValues).toContain("section-shell");
+    expect(ComponentRoleValues).toContain("section-header");
+    expect(ComponentRoleValues).toContain("section-body");
+    expect(ComponentRoleValues).toContain("section-cta");
+    expect(ComponentRoleValues).toContain("section-image");
+    expect(ComponentRoleValues).toContain("site-background");
+  });
+
+  test("schema accepts valid values", () => {
+    expect(componentRoleSchema.safeParse("header").success).toBe(true);
+    expect(componentRoleSchema.safeParse("section-shell").success).toBe(true);
+  });
+
+  test("schema rejects invalid values", () => {
+    expect(componentRoleSchema.safeParse("unknown-role").success).toBe(false);
+  });
+
+  test("has no duplicate values", () => {
+    const seen = new Set<string>();
+    for (const v of ComponentRoleValues) {
+      expect(seen.has(v)).toBe(false);
+      seen.add(v);
+    }
+  });
+});
+
+describe("Industry enum", () => {
+  test("has exactly 6 values", () => {
+    expect(IndustryValues).toHaveLength(6);
+  });
+
+  test("schema accepts valid values", () => {
+    expect(industrySchema.safeParse("trades-and-construction").success).toBe(true);
+    expect(industrySchema.safeParse("non-profit").success).toBe(true);
+  });
+
+  test("schema rejects invalid values", () => {
+    expect(industrySchema.safeParse("technology").success).toBe(false);
+  });
+
+  test("IndustryLabels covers all Industry values", () => {
+    for (const v of IndustryValues) {
+      expect(IndustryLabels[v]).toBeDefined();
+      expect(IndustryLabels[v].length).toBeGreaterThan(0);
+    }
+  });
+});
+
+describe("StarCatalog", () => {
+  test("is non-empty", () => {
+    expect(StarCatalog.length).toBeGreaterThan(100);
+  });
+
+  test("contains known stars", () => {
+    expect(StarCatalog).toContain("Vega");
+    expect(StarCatalog).toContain("Sirius");
+    expect(StarCatalog).toContain("Polaris");
+  });
+
+  test("has no duplicate entries", () => {
+    const seen = new Set<string>();
+    for (const s of StarCatalog) {
+      expect(seen.has(s)).toBe(false);
+      seen.add(s);
+    }
+  });
+
+  test("schema accepts valid star names", () => {
+    expect(starNameSchema.safeParse("Vega").success).toBe(true);
+  });
+
+  test("schema rejects invalid star names", () => {
+    expect(starNameSchema.safeParse("NotAStar").success).toBe(false);
+  });
+});
+
+describe("PlanetCatalog", () => {
+  test("contains known planets", () => {
+    expect(PlanetCatalog).toContain("Europa");
+    expect(PlanetCatalog).toContain("Io");
+    expect(PlanetCatalog).toContain("Titan");
+    expect(PlanetCatalog).toContain("Ceres");
+  });
+
+  test("has no duplicate entries", () => {
+    const seen = new Set<string>();
+    for (const p of PlanetCatalog) {
+      expect(seen.has(p)).toBe(false);
+      seen.add(p);
+    }
+  });
+
+  test("schema accepts valid planet names", () => {
+    expect(planetNameSchema.safeParse("Europa").success).toBe(true);
+  });
+
+  test("schema rejects invalid planet names", () => {
+    expect(planetNameSchema.safeParse("Earth").success).toBe(false);
+  });
+});
+
+describe("MoonCatalog", () => {
+  test("contains known moons", () => {
+    expect(MoonCatalog).toContain("Oberon");
+    expect(MoonCatalog).toContain("Triton");
+    expect(MoonCatalog).toContain("Charon");
+  });
+
+  test("contains passport-reserved moons", () => {
+    const reserved = ["Methone", "Despina", "Klarissa", "Bianca", "Adrastea"];
+    for (const r of reserved) {
+      expect(MoonCatalog).toContain(r);
+    }
+  });
+
+  test("has no duplicate entries", () => {
+    const seen = new Set<string>();
+    for (const m of MoonCatalog) {
+      expect(seen.has(m)).toBe(false);
+      seen.add(m);
+    }
+  });
+
+  test("schema accepts valid moon names", () => {
+    expect(moonNameSchema.safeParse("Oberon").success).toBe(true);
+  });
+
+  test("schema rejects invalid moon names", () => {
+    expect(moonNameSchema.safeParse("Luna").success).toBe(false);
+  });
+});
+
+describe("Cross-catalog identity", () => {
+  test("Planet and Moon catalogs are mutually disjoint", () => {
+    const planetSet = new Set<string>(PlanetCatalog);
+    for (const m of MoonCatalog) {
+      expect(planetSet.has(m)).toBe(false);
+    }
+  });
+
+  test("Star and Moon catalogs are mutually disjoint", () => {
+    const starSet = new Set<string>(StarCatalog);
+    for (const m of MoonCatalog) {
+      expect(starSet.has(m)).toBe(false);
+    }
+  });
+});
+
+describe("cosmicNameSchema", () => {
+  test("accepts star names", () => {
+    expect(cosmicNameSchema.safeParse("Vega").success).toBe(true);
+  });
+
+  test("accepts planet names", () => {
+    expect(cosmicNameSchema.safeParse("Europa").success).toBe(true);
+  });
+
+  test("accepts moon names", () => {
+    expect(cosmicNameSchema.safeParse("Oberon").success).toBe(true);
+  });
+
+  test("rejects non-cosmic strings", () => {
+    expect(cosmicNameSchema.safeParse("NotInAnyCatalog").success).toBe(false);
+  });
+});