@getvitops/generator 0.8.0 → 1.0.0

package/dist/index.d.mts

@@ -1,8 +1,13 @@
 import * as z from "zod/mini";
+import { ContentNode } from "@getvitops/utils";
 
 //#region src/schema.d.ts
 declare const DesignSystemSchema: z.ZodMiniObject<{
   $schema: z.ZodMiniOptional<z.ZodMiniString<string>>;
+  meta: z.ZodMiniOptional<z.ZodMiniObject<{
+    name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    description: z.ZodMiniOptional<z.ZodMiniString<string>>;
+  }, z.z.core.$strip>>;
   colors: z.ZodMiniObject<{
     palette: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniUnion<readonly [z.ZodMiniObject<{
       seed: z.ZodMiniString<string>;
@@ -10,11 +15,18 @@ declare const DesignSystemSchema: z.ZodMiniObject<{
     }, z.z.core.$strip>, z.ZodMiniObject<{
       tones: z.ZodMiniUnion<readonly [z.ZodMiniArray<z.ZodMiniString<string>>, z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>]>;
     }, z.z.core.$strip>]>>;
-    roles: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>;
+    roles: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniUnion<readonly [z.ZodMiniString<string>, z.ZodMiniObject<{
+      hue: z.ZodMiniString<string>;
+      kind: z.ZodMiniOptional<z.ZodMiniEnum<{
+        surface: "surface";
+        chromatic: "chromatic";
+      }>>;
+    }, z.z.core.$strip>]>>;
     utilities: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniEnum<{
       fill: "fill";
       bg: "bg";
       text: "text";
+      icon: "icon";
       border: "border";
       outline: "outline";
       stroke: "stroke";
@@ -93,6 +105,10 @@ declare const SCHEMA_URL = "https://unpkg.com/@getvitops/generator/schema.json";
 declare const jsonSchema: {
   "~standard": z.z.core.ZodStandardSchemaWithJSON<z.ZodMiniObject<{
     $schema: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    meta: z.ZodMiniOptional<z.ZodMiniObject<{
+      name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+      description: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.z.core.$strip>>;
     colors: z.ZodMiniObject<{
       palette: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniUnion<readonly [z.ZodMiniObject<{
         seed: z.ZodMiniString<string>;
@@ -100,11 +116,18 @@ declare const jsonSchema: {
       }, z.z.core.$strip>, z.ZodMiniObject<{
         tones: z.ZodMiniUnion<readonly [z.ZodMiniArray<z.ZodMiniString<string>>, z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>]>;
       }, z.z.core.$strip>]>>;
-      roles: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>;
+      roles: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniUnion<readonly [z.ZodMiniString<string>, z.ZodMiniObject<{
+        hue: z.ZodMiniString<string>;
+        kind: z.ZodMiniOptional<z.ZodMiniEnum<{
+          surface: "surface";
+          chromatic: "chromatic";
+        }>>;
+      }, z.z.core.$strip>]>>;
       utilities: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniEnum<{
         fill: "fill";
         bg: "bg";
         text: "text";
+        icon: "icon";
         border: "border";
         outline: "outline";
         stroke: "stroke";
@@ -254,53 +277,37 @@ type ValidationResult = {
  */
 declare function validate(input: unknown): ValidationResult;
 //#endregion
-//#region src/generate.d.ts
-type Format = 'bricks' | 'css' | 'tailwind';
-interface GenerateOptions {
-  /** Path to a design-system.json, OR an already-parsed config object. */
-  input: string | DesignSystem;
-  /** Output target. Default: 'bricks'. */
-  format?: Format;
-  /** Directory to write outputs into. Default: 'dist'. */
-  outDir?: string;
-  /** Override the framework asset root (advanced/testing). */
-  assetsDir?: string;
-}
-interface GenerateResult {
-  format: Format;
-  outDir: string;
-  written: string[];
-}
-declare function generate(options: GenerateOptions): Promise<GenerateResult>;
-//#endregion
-//#region src/docs.d.ts
-/**
- * Build the OKF docs bundle for a config. Returns a `{ relPath: content }` map;
- * the caller writes it wherever the bundle should live (e.g. `<outDir>/docs`).
- */
-declare function generateDocs(ds: DesignSystem, assetsDir: string): Record<string, string>;
-//#endregion
-//#region src/shared.d.ts
-/**
- * Data shared between the generator (`generate.ts`) and the docs bundle
- * (`docs.ts`). Lives in its own module because `generate.ts` imports `docs.ts` —
- * importing back the other way would be a cycle.
- */
-/**
- * Pattern base geometry props → per-pattern override-hook shorthand. Each hook
- * wraps the authored value (`padding: var(--p-btn, 0.4em 0.8em)`) so a
- * consumer restyles one pattern by setting one variable. The hook is named after
- * the pattern's key, not its class.
- */
-declare const BASE_HOOK: Record<string, string>;
+//#region src/site.d.ts
+declare const PostalAddressSchema: z.ZodMiniObject<{
+  streetAddress: z.ZodMiniString<string>;
+  addressLocality: z.ZodMiniString<string>;
+  addressRegion: z.ZodMiniOptional<z.ZodMiniString<string>>;
+  postalCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+  addressCountry: z.ZodMiniString<string>;
+}, z.z.core.$strip>;
+declare const ContactObjectSchema: z.ZodMiniObject<{
+  name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+  email: z.ZodMiniOptional<z.ZodMiniEmail>;
+  phone: z.ZodMiniOptional<z.ZodMiniString<string>>;
+  address: z.ZodMiniOptional<z.ZodMiniObject<{
+    streetAddress: z.ZodMiniString<string>;
+    addressLocality: z.ZodMiniString<string>;
+    addressRegion: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    postalCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    addressCountry: z.ZodMiniString<string>;
+  }, z.z.core.$strip>>;
+}, z.z.core.$strip>;
+type PostalAddress = z.infer<typeof PostalAddressSchema>;
+type ContactObject = z.infer<typeof ContactObjectSchema>;
 /**
- * Framework utility classes whose names collide with Tailwind's own defaults.
- * The `tailwind` format strips any rule targeting these — Tailwind provides
- * them, so consumers use Tailwind's utilities for these names instead.
+ * Which template set the generated legal documents are written against. This is
+ * a closed enum rather than a free string because an unrecognised value would
+ * otherwise silently fall back to the wrong body of law; `validateSite` rejects
+ * anything without a registered template. Add a member here and a matching entry
+ * in `legal/templates/index.ts` — the two are checked against each other.
  */
-declare const TW_CLASH: ReadonlySet<string>;
-//#endregion
-//#region src/site.d.ts
+declare const JURISDICTIONS: readonly ["ca"];
+type Jurisdiction = (typeof JURISDICTIONS)[number];
 declare const SiteConfigSchema: z.ZodMiniObject<{
   defaultLocale: z.ZodMiniString<string>;
   locales: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniObject<{
@@ -470,6 +477,10 @@ declare const SiteConfigSchema: z.ZodMiniObject<{
   }, z.z.core.$strip>>;
   designSystem: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniObject<{
     $schema: z.ZodMiniOptional<z.ZodMiniOptional<z.ZodMiniString<string>>>;
+    meta: z.ZodMiniOptional<z.ZodMiniOptional<z.ZodMiniObject<{
+      name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+      description: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.z.core.$strip>>>;
     shadows: z.ZodMiniOptional<z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>>>;
     fonts: z.ZodMiniOptional<z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>>>;
     typeScale: z.ZodMiniOptional<z.ZodMiniOptional<z.ZodMiniObject<{
@@ -538,11 +549,18 @@ declare const SiteConfigSchema: z.ZodMiniObject<{
       }, z.z.core.$strip>, z.ZodMiniObject<{
         tones: z.ZodMiniUnion<readonly [z.ZodMiniArray<z.ZodMiniString<string>>, z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>]>;
       }, z.z.core.$strip>]>>>;
-      roles: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>>;
+      roles: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniUnion<readonly [z.ZodMiniString<string>, z.ZodMiniObject<{
+        hue: z.ZodMiniString<string>;
+        kind: z.ZodMiniOptional<z.ZodMiniEnum<{
+          surface: "surface";
+          chromatic: "chromatic";
+        }>>;
+      }, z.z.core.$strip>]>>>;
       utilities: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniEnum<{
         fill: "fill";
         bg: "bg";
         text: "text";
+        icon: "icon";
         border: "border";
         outline: "outline";
         stroke: "stroke";
@@ -741,15 +759,38 @@ declare const SiteConfigSchema: z.ZodMiniObject<{
     }, z.z.core.$strip>>;
   }, z.z.core.$strip>>;
   legal: z.ZodMiniOptional<z.ZodMiniObject<{
+    jurisdiction: z.ZodMiniOptional<z.ZodMiniEnum<{
+      ca: "ca";
+    }>>;
     privacyPolicy: z.ZodMiniOptional<z.ZodMiniObject<{
       enabled: z.ZodMiniBoolean<boolean>;
       url: z.ZodMiniOptional<z.ZodMiniURL>;
       lastUpdated: z.ZodMiniOptional<z.ZodMiniString<string>>;
+      privacyOfficer: z.ZodMiniOptional<z.ZodMiniUnion<readonly [z.ZodMiniString<string>, z.ZodMiniObject<{
+        name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        email: z.ZodMiniOptional<z.ZodMiniEmail>;
+        phone: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        address: z.ZodMiniOptional<z.ZodMiniObject<{
+          streetAddress: z.ZodMiniString<string>;
+          addressLocality: z.ZodMiniString<string>;
+          addressRegion: z.ZodMiniOptional<z.ZodMiniString<string>>;
+          postalCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+          addressCountry: z.ZodMiniString<string>;
+        }, z.z.core.$strip>>;
+      }, z.z.core.$strip>]>>;
+      retention: z.ZodMiniOptional<z.ZodMiniString<string>>;
+      processors: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniObject<{
+        name: z.ZodMiniString<string>;
+        purpose: z.ZodMiniString<string>;
+        country: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        privacyUrl: z.ZodMiniOptional<z.ZodMiniURL>;
+      }, z.z.core.$strip>>>;
     }, z.z.core.$strip>>;
     termsOfService: z.ZodMiniOptional<z.ZodMiniObject<{
       enabled: z.ZodMiniBoolean<boolean>;
       url: z.ZodMiniOptional<z.ZodMiniURL>;
       lastUpdated: z.ZodMiniOptional<z.ZodMiniNullable<z.ZodMiniString<string>>>;
+      governingLaw: z.ZodMiniOptional<z.ZodMiniString<string>>;
     }, z.z.core.$strip>>;
     cookieConsent: z.ZodMiniOptional<z.ZodMiniObject<{
       enabled: z.ZodMiniBoolean<boolean>;
@@ -966,6 +1007,10 @@ declare const siteJsonSchema: {
     }, z.z.core.$strip>>;
     designSystem: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniObject<{
       $schema: z.ZodMiniOptional<z.ZodMiniOptional<z.ZodMiniString<string>>>;
+      meta: z.ZodMiniOptional<z.ZodMiniOptional<z.ZodMiniObject<{
+        name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        description: z.ZodMiniOptional<z.ZodMiniString<string>>;
+      }, z.z.core.$strip>>>;
       shadows: z.ZodMiniOptional<z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>>>;
       fonts: z.ZodMiniOptional<z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>>>;
       typeScale: z.ZodMiniOptional<z.ZodMiniOptional<z.ZodMiniObject<{
@@ -1034,11 +1079,18 @@ declare const siteJsonSchema: {
         }, z.z.core.$strip>, z.ZodMiniObject<{
           tones: z.ZodMiniUnion<readonly [z.ZodMiniArray<z.ZodMiniString<string>>, z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>]>;
         }, z.z.core.$strip>]>>>;
-        roles: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniString<string>>>;
+        roles: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniUnion<readonly [z.ZodMiniString<string>, z.ZodMiniObject<{
+          hue: z.ZodMiniString<string>;
+          kind: z.ZodMiniOptional<z.ZodMiniEnum<{
+            surface: "surface";
+            chromatic: "chromatic";
+          }>>;
+        }, z.z.core.$strip>]>>>;
         utilities: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniEnum<{
           fill: "fill";
           bg: "bg";
           text: "text";
+          icon: "icon";
           border: "border";
           outline: "outline";
           stroke: "stroke";
@@ -1237,15 +1289,38 @@ declare const siteJsonSchema: {
       }, z.z.core.$strip>>;
     }, z.z.core.$strip>>;
     legal: z.ZodMiniOptional<z.ZodMiniObject<{
+      jurisdiction: z.ZodMiniOptional<z.ZodMiniEnum<{
+        ca: "ca";
+      }>>;
       privacyPolicy: z.ZodMiniOptional<z.ZodMiniObject<{
         enabled: z.ZodMiniBoolean<boolean>;
         url: z.ZodMiniOptional<z.ZodMiniURL>;
         lastUpdated: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        privacyOfficer: z.ZodMiniOptional<z.ZodMiniUnion<readonly [z.ZodMiniString<string>, z.ZodMiniObject<{
+          name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+          email: z.ZodMiniOptional<z.ZodMiniEmail>;
+          phone: z.ZodMiniOptional<z.ZodMiniString<string>>;
+          address: z.ZodMiniOptional<z.ZodMiniObject<{
+            streetAddress: z.ZodMiniString<string>;
+            addressLocality: z.ZodMiniString<string>;
+            addressRegion: z.ZodMiniOptional<z.ZodMiniString<string>>;
+            postalCode: z.ZodMiniOptional<z.ZodMiniString<string>>;
+            addressCountry: z.ZodMiniString<string>;
+          }, z.z.core.$strip>>;
+        }, z.z.core.$strip>]>>;
+        retention: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        processors: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniObject<{
+          name: z.ZodMiniString<string>;
+          purpose: z.ZodMiniString<string>;
+          country: z.ZodMiniOptional<z.ZodMiniString<string>>;
+          privacyUrl: z.ZodMiniOptional<z.ZodMiniURL>;
+        }, z.z.core.$strip>>>;
       }, z.z.core.$strip>>;
       termsOfService: z.ZodMiniOptional<z.ZodMiniObject<{
         enabled: z.ZodMiniBoolean<boolean>;
         url: z.ZodMiniOptional<z.ZodMiniURL>;
         lastUpdated: z.ZodMiniOptional<z.ZodMiniNullable<z.ZodMiniString<string>>>;
+        governingLaw: z.ZodMiniOptional<z.ZodMiniString<string>>;
       }, z.z.core.$strip>>;
       cookieConsent: z.ZodMiniOptional<z.ZodMiniObject<{
         enabled: z.ZodMiniBoolean<boolean>;
@@ -1366,6 +1441,15 @@ type SiteValidationResult = {
  * These live only here — the published JSON Schema enforces shape, not integrity.
  */
 declare function validateSite(input: unknown): SiteValidationResult;
+/**
+ * Resolve who privacy requests go to: the explicit privacy officer, else the
+ * site contact, else the primary location, else the organization itself.
+ *
+ * Exported because `validateSite` and the legal-document derivation must agree
+ * on it exactly — a config that validates must be one the policy can render, and
+ * two copies of this precedence would drift into a policy with a blank address.
+ */
+declare function resolvePrivacyContact(cfg: SiteConfig): ContactObject | undefined;
 type DesignSystemEntryT = Partial<DesignSystem> & {
   displayName?: unknown;
   extends?: string;
@@ -1391,6 +1475,437 @@ declare function stripNulls(obj: unknown): unknown;
 /** Deep-merge `source` into `target` (in place). Arrays replace wholesale. */
 declare function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): void;
 //#endregion
+//#region src/tokens.d.ts
+declare const NUMERIC_STEPS: readonly ["50", "100", "200", "300", "400", "500", "600", "700", "800", "900", "950"];
+type NumStep = (typeof NUMERIC_STEPS)[number];
+interface ExpandedHue {
+  /** Numeric steps (sparse for fixed-tone kits). */
+  numeric: Partial<Record<NumStep, string>>;
+  /** True when only authored tones + endpoints exist (no interpolation). */
+  sparse?: boolean;
+  /**
+   * Steps the author pinned, and how far each sits from the ladder's lightness.
+   * A pinned colour is reproduced exactly, so a large value here is legal — but
+   * it means this hue reads heavier or lighter than its siblings at that step,
+   * which the generator surfaces as a warning.
+   */
+  deviations?: Partial<Record<NumStep, number>>;
+}
+/** Expand every palette hue into its numeric scale. */
+declare function expandPalette(raw: Record<string, unknown>): Record<string, ExpandedHue>;
+/** Which shape of token set a role gets. */
+type RoleKind = 'surface' | 'chromatic';
+/**
+ * Map a token key to its CSS custom property for a given role.
+ *
+ * `on` is the one irregular case: the foreground for a filled surface reads
+ * `--color-text-on-<role>`, with the role *after* `on`, because it names what it
+ * sits on rather than what it is.
+ *
+ * The utility class name is this minus the `--color-` prefix, which is why the
+ * emitter and the linter can both derive their vocabulary from one function.
+ */
+declare function tokenVar(role: string, key: string): string;
+/** The class name a token key produces for a role (`bg-danger-solid`, …). */
+declare const tokenClass: (role: string, key: string) => string;
+interface FunctionalRole {
+  role: string;
+  hue: string;
+  kind: RoleKind;
+  /** token key → CSS value, per appearance. */
+  light: Record<string, string>;
+  dark: Record<string, string>;
+}
+/** Resolve the token set for one role over its hue. */
+declare function functionalRole(role: string, hueName: string, hue: ExpandedHue, kind?: RoleKind): FunctionalRole;
+/**
+ * APCA targets. `TEXT` is the body-text bar; `SECONDARY` covers text on a
+ * non-primary surface and de-emphasised text. `NON_TEXT` is the icon/boundary
+ * tier — the APCA analogue of WCAG's 3:1, where a glyph may run more vivid than
+ * text because shape carries meaning alongside contrast.
+ */
+declare const CONTRAST: {
+  readonly TEXT: 75;
+  readonly SECONDARY: 60;
+  readonly NON_TEXT: 45;
+};
+//#endregion
+//#region src/generate.d.ts
+type Format = 'bricks' | 'css' | 'tailwind' | 'design';
+/**
+ * Formats that emit a stylesheet. `design` is the odd one out — it emits a
+ * single `DESIGN.md` brief and no CSS at all — so anything that expects to
+ * import the generator's output (the Vite plugin's injected stylesheet, the
+ * Astro integration) types against this narrower set.
+ */
+type StylesheetFormat = Exclude<Format, 'design'>;
+interface GenerateOptions {
+  /** Path to a design-system.json, OR an already-parsed config object. */
+  input: string | DesignSystem;
+  /** Output target. Default: 'bricks'. */
+  format?: Format;
+  /** Directory to write outputs into. Default: 'dist'. */
+  outDir?: string;
+  /** Override the framework asset root (advanced/testing). */
+  assetsDir?: string;
+  /**
+   * Optional site config (path, or already-parsed) enabling legal-document
+   * output into `<outDir>/legal/*.html`.
+   *
+   * Separate from `input` because it is a different config kind: `input` is a
+   * `design-system.json`, this is a `SiteConfig`. Nothing else in `generate`
+   * reads it, and omitting it emits no legal files.
+   */
+  site?: string | SiteConfig;
+}
+interface GenerateResult {
+  format: Format;
+  outDir: string;
+  written: string[];
+}
+interface ColorUtility {
+  /** Class name, without the leading dot. */
+  cls: string;
+  /** CSS property the class sets. */
+  prop: string;
+  /** `var(--…)` reference the class resolves to. */
+  value: string;
+}
+/**
+ * Every role colour utility, each class name emitted EXACTLY once.
+ *
+ * There is now a single axis. The target lives *inside* the token name, so
+ * `bg-danger-muted` and `text-danger-muted` are different tokens and the
+ * collision the old plane/stop precedence rule existed to arbitrate cannot
+ * arise. Both the css/bricks and tailwind paths render from this one list, which
+ * is what keeps the three formats in step; `format-parity.test.ts` holds them
+ * there.
+ *
+ * The class name IS the token name minus `--color-`, so there is no separate
+ * naming rule to drift — see `tokenClass` in tokens.ts.
+ */
+declare function roleColorUtilities(roles: readonly FunctionalRole[], utilities: readonly string[]): ColorUtility[];
+declare function generate(options: GenerateOptions): Promise<GenerateResult>;
+//#endregion
+//#region src/docs.d.ts
+/**
+ * Build the OKF docs bundle for a config. Returns a `{ relPath: content }` map;
+ * the caller writes it wherever the bundle should live (e.g. `<outDir>/docs`).
+ */
+declare function generateDocs(ds: DesignSystem, assetsDir: string): Record<string, string>;
+//#endregion
+//#region src/shared.d.ts
+/**
+ * Data shared between the generator (`generate.ts`) and the docs bundle
+ * (`docs.ts`). Lives in its own module because `generate.ts` imports `docs.ts` —
+ * importing back the other way would be a cycle.
+ */
+/**
+ * Selector the dark functional-token flip hangs off.
+ *
+ * `data-brx-theme` is Bricks' own attribute — Bricks sets it, so it's what the
+ * WordPress target needs. Nothing sets it anywhere else, which meant the dark
+ * flip was unreachable outside Bricks: the shipped `<color-scheme-toggle>` web
+ * component writes `documentElement.dataset.theme` (i.e. `data-theme`), so
+ * clicking "Dark" changed an attribute no rule matched. Matching both makes the
+ * component work on every target without changing what Bricks already does.
+ *
+ * Note this covers the explicit choice only — there is deliberately no
+ * `prefers-color-scheme` block, so the toggle's "System" position currently
+ * resolves to light. Adding one would flip every existing consumer site dark for
+ * dark-OS users, which is a product decision, not a bug fix.
+ *
+ * Shared so the docs quote the selector the generator actually emits.
+ */
+declare const DARK_SEL = ":root[data-brx-theme=\"dark\"], :root[data-theme=\"dark\"]";
+/**
+ * Roles the shipped CSS partials reference with NO fallback, so a config that
+ * omits one leaves those rules resolving to nothing — an invalid declaration,
+ * not a graceful degrade.
+ *
+ * `colors.roles` is an open record: any name works and generates a full token
+ * set, utilities and dark flip. But the framework's own component CSS is
+ * written against these six, so "roles are arbitrary" is only half true — they
+ * are *extensible*, over a required core. `validate()` warns when one is
+ * missing; `required-roles.test.ts` re-derives this list from the partials so
+ * it cannot drift as components are added.
+ *
+ * Kept as a constant rather than scanned at call time because `validate()` is
+ * a pure function — the CLI, the Vite plugin and `toJSONSchema` all import it,
+ * and none of them should touch the filesystem to answer "is this config ok?".
+ */
+declare const REQUIRED_ROLES: readonly string[];
+/**
+ * Every token key a role can resolve to, across both role kinds. Shared so the
+ * required-roles drift test greps for exactly what the generator emits.
+ *
+ * These are *keys*, not var names: the role sits in the middle of the property
+ * (`--color-bg-danger-muted`), so compose them with `tokenVar()` from `tokens.ts`
+ * rather than concatenating by hand.
+ */
+declare const ROLE_TOKEN_KEYS: readonly string[];
+/** How a role is authored in `colors.roles`: a bare hue, or a hue plus its kind. */
+type RoleSpec = string | {
+  hue: string;
+  kind?: 'surface' | 'chromatic' | undefined;
+};
+/** The palette hue a role points at, through either authoring form. */
+declare const roleHue: (spec: RoleSpec) => string;
+/**
+ * A role's kind. The bare-string shorthand means `chromatic`, because signal
+ * colours are the common case and surfaces are the two or three you name once.
+ */
+declare const roleKind: (spec: RoleSpec) => "surface" | "chromatic";
+/**
+ * Pattern base geometry props → per-pattern override-hook shorthand. Each hook
+ * wraps the authored value (`padding: var(--p-btn, 0.4em 0.8em)`) so a
+ * consumer restyles one pattern by setting one variable. The hook is named after
+ * the pattern's key, not its class.
+ */
+declare const BASE_HOOK: Record<string, string>;
+/**
+ * Framework utility classes whose names collide with Tailwind's own defaults.
+ * The `tailwind` format strips any rule targeting these — Tailwind provides
+ * them, so consumers use Tailwind's utilities for these names instead.
+ */
+declare const TW_CLASH: ReadonlySet<string>;
+//#endregion
+//#region src/legal/providers.d.ts
+interface Processor {
+  /** The provider as a reader would recognise it. */
+  name: string;
+  /** Reads after "for": "…to Stripe for payment processing". */
+  purpose: string;
+  /** Reads inside a sentence: "…including the United States". */
+  country?: string | undefined;
+  privacyUrl?: string | undefined;
+  /**
+   * Cookies this provider sets. An empty array is meaningful and not the same as
+   * `undefined`: it asserts the provider is cookieless (Plausible), which the
+   * cookie notice states positively rather than omitting.
+   */
+  cookies?: string[] | undefined;
+  /** A user-facing opt-out, when the provider offers one. */
+  optOut?: string | undefined;
+}
+/**
+ * The providers the config can imply. Keyed for testability — a test can assert
+ * a given config resolves to a given key without matching on prose.
+ */
+declare const KNOWN_PROCESSORS: {
+  googleAnalytics: {
+    name: string;
+    purpose: string;
+    country: string;
+    privacyUrl: string;
+    cookies: string[];
+    optOut: string;
+  };
+  googleTagManager: {
+    name: string;
+    purpose: string;
+    country: string;
+    privacyUrl: string;
+    cookies: never[];
+  };
+  plausible: {
+    name: string;
+    purpose: string;
+    country: string;
+    privacyUrl: string;
+    cookies: never[];
+  };
+  turnstile: {
+    name: string;
+    purpose: string;
+    country: string;
+    privacyUrl: string;
+    cookies: string[];
+  };
+  cloudflare: {
+    name: string;
+    purpose: string;
+    country: string;
+    privacyUrl: string;
+    cookies: never[];
+  };
+  vercel: {
+    name: string;
+    purpose: string;
+    country: string;
+    privacyUrl: string;
+    cookies: never[];
+  };
+  netlify: {
+    name: string;
+    purpose: string;
+    country: string;
+    privacyUrl: string;
+    cookies: never[];
+  };
+};
+type KnownProcessorKey = keyof typeof KNOWN_PROCESSORS;
+/**
+ * Which known providers this config implies, in a stable order (analytics →
+ * security → hosting) so the rendered sentence doesn't churn between builds.
+ *
+ * Returns keys rather than processors so a caller can test the detection
+ * independently of the prose attached to it.
+ */
+declare function detectProcessorKeys(site: SiteConfig): KnownProcessorKey[];
+/**
+ * Every processor this policy must disclose: the ones implied by the config,
+ * then the ones the consumer declared.
+ *
+ * Consumer entries come last and are never deduplicated against the built-ins —
+ * an explicit declaration is a statement of fact we have no grounds to drop.
+ */
+declare function resolveProcessors(site: SiteConfig): Processor[];
+//#endregion
+//#region src/legal/derive.d.ts
+/**
+ * The facts every legal template renders from.
+ *
+ * List-shaped fields are `string[]`, not pre-joined strings, because they land
+ * in bullet positions: a template that splices an empty string into a list emits
+ * a stray `-` bullet, and that is exactly the kind of silent breakage a
+ * published policy must not have.
+ */
+interface PolicyVars {
+  businessName: string;
+  url: string;
+  /** Reads after "at": "…contact our Privacy Officer at <this>." */
+  mailingAddress: string;
+  lastUpdated: string | undefined;
+  /** Extra retention sentence, when the consumer stated one. */
+  retention: string | undefined;
+  /** A consumer-supplied governing-law phrase, which wins over the two below. */
+  governingLaw: string | undefined;
+  /** Province/territory, spelled out — "Ontario", never "ON". */
+  governingProvince: string | undefined;
+  governingCountry: string;
+  /** Circumstances in which personal information is collected. */
+  collectionReasons: string[];
+  /** Categories of personal information collected. */
+  piiCollected: string[];
+  /** What the browser sends automatically. */
+  techInfo: string[];
+  /** Why that technical information is used. */
+  techInfoPurposes: string[];
+  /** What cookies track. */
+  cookieTracked: string[];
+  /** Why cookies are used. */
+  cookiePurposes: string[];
+  /** A sentence about the consent tool, or `undefined` when there is none. */
+  cookieTool: string | undefined;
+  /** How collected information is used. */
+  usePurposes: string[];
+  /** Choices a visitor has. */
+  optOutOptions: string[];
+  /** The subset of `optOutOptions` about cookies — an e-mail unsubscribe link is
+   * not a cookie choice, and listing it in a cookie notice reads as padding. */
+  cookieOptOutOptions: string[];
+  processors: Processor[];
+  /** Reads after "including": "…the United States and the European Union". */
+  countries: string | undefined;
+  consentModel: 'opt-in' | 'opt-out' | 'none';
+  cookieCategories: string[];
+}
+declare function derivePolicyVars(site: SiteConfig): PolicyVars;
+//#endregion
+//#region src/legal/templates/cookies.ca.d.ts
+declare function cookiesCa(v: PolicyVars): string;
+//#endregion
+//#region src/legal/templates/privacy.ca.d.ts
+declare function privacyCa(v: PolicyVars): string;
+//#endregion
+//#region src/legal/templates/terms.ca.d.ts
+declare function termsCa(v: PolicyVars): string;
+//#endregion
+//#region src/legal/templates/index.d.ts
+type LegalDoc = 'privacy' | 'terms' | 'cookies';
+type DocSet = Record<LegalDoc, (v: PolicyVars) => string>;
+declare const TEMPLATES: {
+  ca: {
+    privacy: typeof privacyCa;
+    terms: typeof termsCa;
+    cookies: typeof cookiesCa;
+  };
+};
+/** Stable output order, independent of which docs a given config enables. */
+declare const DOC_ORDER: LegalDoc[];
+/** Output filename stem per document — also the Bricks shortcode's allowlist. */
+declare const DOC_SLUGS: Record<LegalDoc, string>;
+//#endregion
+//#region src/legal/render.d.ts
+interface Span {
+  text: string;
+  strong?: boolean;
+  code?: boolean;
+}
+type Block = {
+  kind: 'heading';
+  level: 1 | 2 | 3;
+  spans: Span[];
+} | {
+  kind: 'paragraph';
+  spans: Span[];
+} | {
+  kind: 'list';
+  items: Span[][];
+} | {
+  kind: 'quote';
+  spans: Span[];
+};
+/** Markdown (our subset) → blocks. Throws on anything it does not model. */
+declare function parseMarkdown(md: string): Block[];
+/**
+ * Blocks → `ContentNode[]`, the framework-agnostic tree the site config already
+ * uses for `templates` of type `nodes` and `NodeRenderer.astro` already renders.
+ */
+declare function toContentNodes(blocks: Block[]): ContentNode[];
+declare function toHtmlFragment(blocks: Block[]): string;
+/**
+ * Blocks → EmDash Portable Text, matching the shape already seeded in
+ * `packages/create/templates/emdash/seed/seed.json`.
+ *
+ * Two deliberate mappings:
+ *  - the `# ` heading is **dropped** — in EmDash the page title is a field
+ *    (`data.title`), and repeating it as the first content block renders twice;
+ *  - the review blockquote becomes a `vitops.banner` with `tone: "warning"`,
+ *    which is exactly the block the hand-written placeholder pages used.
+ *
+ * `_key`s are derived from position rather than randomness, so regenerating an
+ * unchanged config produces an identical seed and a clean diff.
+ */
+declare function toPortableText(blocks: Block[], prefix: string): unknown[];
+//#endregion
+//#region src/legal/index.d.ts
+type LegalOutput = 'md' | 'html' | 'portable-text';
+interface GenerateLegalOptions {
+  /** Which documents to render. Defaults to those enabled in the config. */
+  docs?: LegalDoc[];
+  /** Output format. Default `md`. */
+  output?: LegalOutput;
+}
+/** Which documents the config asks for, in a stable order. */
+declare function enabledDocs(site: SiteConfig): LegalDoc[];
+/** Render one document to markdown. The other outputs derive from this. */
+declare function renderMarkdown(site: SiteConfig, doc: LegalDoc, vars?: PolicyVars): string;
+/**
+ * Render one document as a `ContentNode` tree — the framework-agnostic shape the
+ * site config already uses for `templates` of type `nodes`, so an Astro consumer
+ * can hand it to `NodeRenderer` instead of injecting a string of HTML.
+ */
+declare function renderNodes(site: SiteConfig, doc: LegalDoc): ContentNode[];
+/**
+ * Every enabled legal document, keyed by output path.
+ *
+ * Documents are keyed by filename (`privacy-policy.md`) rather than by document
+ * id so a caller can write the map verbatim.
+ */
+declare function generateLegal(site: SiteConfig, opts?: GenerateLegalOptions): Record<string, string>;
+//#endregion
 //#region src/index.d.ts
 /**
  * A minimal but complete starter design system, used by `vitops init`. It
@@ -1399,5 +1914,5 @@ declare function deepMerge(target: Record<string, unknown>, source: Record<strin
  */
 declare function defaultConfig(): DesignSystem;
 //#endregion
-export { BASE_HOOK, type DesignSystem, DesignSystemSchema, type Format, type GenerateOptions, type GenerateResult, SCHEMA_URL, SITE_SCHEMA_URL, type SiteConfig, SiteConfigSchema, type SiteValidationResult, TW_CLASH, type ValidationResult, deepMerge, defaultConfig, generate, generateDocs, jsonSchema, resolveSiteConfig, resolveTheme, siteJsonSchema, stripNulls, validate, validateSite };
+export { BASE_HOOK, type Block, CONTRAST, type ColorUtility, type ContactObject, DARK_SEL, DOC_ORDER, DOC_SLUGS, type DesignSystem, DesignSystemSchema, type DocSet, type ExpandedHue, type Format, type FunctionalRole, type GenerateLegalOptions, type GenerateOptions, type GenerateResult, JURISDICTIONS, type Jurisdiction, KNOWN_PROCESSORS, type KnownProcessorKey, type LegalDoc, type LegalOutput, NUMERIC_STEPS, type PolicyVars, type PostalAddress, type Processor, REQUIRED_ROLES, ROLE_TOKEN_KEYS, type RoleKind, type RoleSpec, SCHEMA_URL, SITE_SCHEMA_URL, type SiteConfig, SiteConfigSchema, type SiteValidationResult, type Span, type StylesheetFormat, TEMPLATES, TW_CLASH, type ValidationResult, deepMerge, defaultConfig, derivePolicyVars, detectProcessorKeys, enabledDocs, expandPalette, functionalRole, generate, generateDocs, generateLegal, jsonSchema, parseMarkdown, renderMarkdown, renderNodes, resolvePrivacyContact, resolveProcessors, resolveSiteConfig, resolveTheme, roleColorUtilities, roleHue, roleKind, siteJsonSchema, stripNulls, toContentNodes, toHtmlFragment, toPortableText, tokenClass, tokenVar, validate, validateSite };
 //# sourceMappingURL=index.d.mts.map