@getvitops/generator 3.0.0 → 4.1.0

package/dist/index.d.mts

@@ -354,7 +354,7 @@ declare const SiteFontSchema: z.ZodMiniObject<{
   }, z.z.core.$strip>>]>>;
 }, z.z.core.$strip>;
 /**
- * What `vitops notify` needs to tell search engines a deploy happened.
+ * What `vitops search notify` needs to tell search engines a deploy happened.
  *
  * Scoped by what search engines actually accept, which is narrower than it looks:
  * Google exposes **no** "request indexing" API (the Search Console button is not in
@@ -389,6 +389,41 @@ declare const IndexingSchema: z.ZodMiniObject<{
   }, z.z.core.$strip>>;
   priorityUrls: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniURL>>;
 }, z.z.core.$strip>;
+/**
+ * The ad platforms `vitops ads` can link a site to.
+ *
+ * A closed enum, mirroring `AD_PROVIDER_KEYS` in `@getvitops/utils/ads` — that
+ * module owns what each platform *can do* (whether it verifies a domain, what its
+ * tag is, which click ID it stamps), this owns what a config may *say*. Mirrored
+ * rather than derived because a `z.enum` needs literals to reach the published JSON
+ * Schema; `config.test.ts` asserts the two lists are the same set, so a provider
+ * added to one and not the other fails the build rather than silently getting no
+ * verification step and no tag.
+ */
+declare const AD_PROVIDERS: readonly ["google", "meta", "linkedin", "reddit", "tiktok", "microsoft", "pinterest", "snapchat"];
+type AdProvider = (typeof AD_PROVIDERS)[number];
+/**
+ * One ad property this site is linked to.
+ *
+ * Facts, not prose — the same rule the legal block follows. This records *which*
+ * account and *which* tag id, and the platform capability table decides what can be
+ * done about them. It is also what finally lets the rest of the toolchain see an ad
+ * pixel: the generated cookie notice discloses its cookies, `vitops ads lint`
+ * checks its click ID is captured, and the consent gate is handed the cookie names
+ * to clear on revoke. A pixel pasted into a template is invisible to all three.
+ */
+declare const AdPropertySchema: z.ZodMiniObject<{
+  accountId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+  pixelId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+  conversionLabel: z.ZodMiniOptional<z.ZodMiniString<string>>;
+  domain: z.ZodMiniOptional<z.ZodMiniString<string>>;
+  domainVerification: z.ZodMiniOptional<z.ZodMiniString<string>>;
+  category: z.ZodMiniOptional<z.ZodMiniEnum<{
+    analytics: "analytics";
+    marketing: "marketing";
+  }>>;
+  enabled: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+}, z.z.core.$strip>;
 /**
  * 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
@@ -398,6 +433,22 @@ declare const IndexingSchema: z.ZodMiniObject<{
  */
 declare const JURISDICTIONS: readonly ["ca"];
 type Jurisdiction = (typeof JURISDICTIONS)[number];
+/**
+ * The country each template set frames cross-border transfers as *leaving*.
+ *
+ * A jurisdiction's own country is not a transfer, so this is what filters the
+ * disclosure lists — without it, `country: "Canada"` renders the incoherent
+ * "outside of Canada, including Canada".
+ *
+ * It belongs to the **jurisdiction**, not to `organization.address`: a `ca` policy
+ * says "outside of Canada" even for a business incorporated elsewhere. (The
+ * address drives a different sentence — the terms' governing-law clause, via
+ * `governingCountry`.) `satisfies` makes a new jurisdiction unable to forget it,
+ * the same guard style as `TEMPLATES`.
+ */
+declare const JURISDICTION_COUNTRIES: {
+  ca: string;
+};
 declare const SiteSectionSchema: z.ZodMiniObject<{
   defaultLocale: z.ZodMiniString<string>;
   locales: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniObject<{
@@ -437,10 +488,15 @@ declare const SiteSectionSchema: z.ZodMiniObject<{
     }, z.z.core.$strip>>>;
   }, z.z.core.$strip>>>;
   cloudflare: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniUnknown>>;
+  searchConsole: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniObject<{
+    delegatedOwners: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniEmail>>;
+    fullUserGroup: z.ZodMiniOptional<z.ZodMiniEmail>;
+  }, z.z.core.$strip>>>;
   environments: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniObject<{
     url: z.ZodMiniURL;
     api: z.ZodMiniOptional<z.ZodMiniURL>;
     analytics: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+    ads: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
     robots: z.ZodMiniOptional<z.ZodMiniString<string>>;
     variant: z.ZodMiniOptional<z.ZodMiniString<string>>;
   }, z.z.core.$strip>>;
@@ -646,12 +702,44 @@ declare const SiteSectionSchema: z.ZodMiniObject<{
     }, z.z.core.$strip>>;
   }, z.z.core.$strip>>;
   notifications: z.ZodMiniOptional<z.ZodMiniObject<{
-    email: z.ZodMiniOptional<z.ZodMiniEmail>;
+    email: z.ZodMiniOptional<z.ZodMiniUnion<readonly [z.ZodMiniEmail, z.ZodMiniObject<{
+      provider: z.ZodMiniLiteral<"cloudflare">;
+      to: z.ZodMiniOptional<z.ZodMiniEmail>;
+      from: z.ZodMiniOptional<z.ZodMiniEmail>;
+      fromName: z.ZodMiniOptional<z.ZodMiniString<string>>;
+      replyTo: z.ZodMiniOptional<z.ZodMiniEmail>;
+      binding: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    }, z.z.core.$strip>]>>;
   }, z.z.core.$strip>>;
   tracking: z.ZodMiniOptional<z.ZodMiniObject<{
     enabled: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+    category: z.ZodMiniOptional<z.ZodMiniEnum<{
+      analytics: "analytics";
+      marketing: "marketing";
+    }>>;
     platforms: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniString<string>>>;
   }, z.z.core.$strip>>;
+  ads: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniEnum<{
+    google: "google";
+    meta: "meta";
+    linkedin: "linkedin";
+    reddit: "reddit";
+    tiktok: "tiktok";
+    microsoft: "microsoft";
+    pinterest: "pinterest";
+    snapchat: "snapchat";
+  }> & z.z.core.$partial, z.ZodMiniObject<{
+    accountId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    pixelId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    conversionLabel: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    domain: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    domainVerification: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    category: z.ZodMiniOptional<z.ZodMiniEnum<{
+      analytics: "analytics";
+      marketing: "marketing";
+    }>>;
+    enabled: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+  }, z.z.core.$strip>>>;
   security: z.ZodMiniOptional<z.ZodMiniObject<{
     turnstile: z.ZodMiniOptional<z.ZodMiniObject<{
       siteKey: z.ZodMiniOptional<z.ZodMiniString<string>>;
@@ -682,6 +770,11 @@ declare const SiteSectionSchema: z.ZodMiniObject<{
         name: z.ZodMiniString<string>;
         purpose: z.ZodMiniString<string>;
         country: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        storage: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniObject<{
+          country: z.ZodMiniString<string>;
+          scope: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        }, z.z.core.$strip>>>;
+        operatorCountry: z.ZodMiniOptional<z.ZodMiniString<string>>;
         privacyUrl: z.ZodMiniOptional<z.ZodMiniURL>;
       }, z.z.core.$strip>>>;
     }, z.z.core.$strip>>;
@@ -1098,10 +1191,15 @@ declare const ConfigSchema: z.ZodMiniObject<{
       }, z.z.core.$strip>>>;
     }, z.z.core.$strip>>>;
     cloudflare: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniUnknown>>;
+    searchConsole: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniObject<{
+      delegatedOwners: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniEmail>>;
+      fullUserGroup: z.ZodMiniOptional<z.ZodMiniEmail>;
+    }, z.z.core.$strip>>>;
     environments: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniObject<{
       url: z.ZodMiniURL;
       api: z.ZodMiniOptional<z.ZodMiniURL>;
       analytics: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+      ads: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
       robots: z.ZodMiniOptional<z.ZodMiniString<string>>;
       variant: z.ZodMiniOptional<z.ZodMiniString<string>>;
     }, z.z.core.$strip>>;
@@ -1307,12 +1405,44 @@ declare const ConfigSchema: z.ZodMiniObject<{
       }, z.z.core.$strip>>;
     }, z.z.core.$strip>>;
     notifications: z.ZodMiniOptional<z.ZodMiniObject<{
-      email: z.ZodMiniOptional<z.ZodMiniEmail>;
+      email: z.ZodMiniOptional<z.ZodMiniUnion<readonly [z.ZodMiniEmail, z.ZodMiniObject<{
+        provider: z.ZodMiniLiteral<"cloudflare">;
+        to: z.ZodMiniOptional<z.ZodMiniEmail>;
+        from: z.ZodMiniOptional<z.ZodMiniEmail>;
+        fromName: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        replyTo: z.ZodMiniOptional<z.ZodMiniEmail>;
+        binding: z.ZodMiniOptional<z.ZodMiniString<string>>;
+      }, z.z.core.$strip>]>>;
     }, z.z.core.$strip>>;
     tracking: z.ZodMiniOptional<z.ZodMiniObject<{
       enabled: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+      category: z.ZodMiniOptional<z.ZodMiniEnum<{
+        analytics: "analytics";
+        marketing: "marketing";
+      }>>;
       platforms: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniString<string>>>;
     }, z.z.core.$strip>>;
+    ads: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniEnum<{
+      google: "google";
+      meta: "meta";
+      linkedin: "linkedin";
+      reddit: "reddit";
+      tiktok: "tiktok";
+      microsoft: "microsoft";
+      pinterest: "pinterest";
+      snapchat: "snapchat";
+    }> & z.z.core.$partial, z.ZodMiniObject<{
+      accountId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+      pixelId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+      conversionLabel: z.ZodMiniOptional<z.ZodMiniString<string>>;
+      domain: z.ZodMiniOptional<z.ZodMiniString<string>>;
+      domainVerification: z.ZodMiniOptional<z.ZodMiniString<string>>;
+      category: z.ZodMiniOptional<z.ZodMiniEnum<{
+        analytics: "analytics";
+        marketing: "marketing";
+      }>>;
+      enabled: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+    }, z.z.core.$strip>>>;
     security: z.ZodMiniOptional<z.ZodMiniObject<{
       turnstile: z.ZodMiniOptional<z.ZodMiniObject<{
         siteKey: z.ZodMiniOptional<z.ZodMiniString<string>>;
@@ -1343,6 +1473,11 @@ declare const ConfigSchema: z.ZodMiniObject<{
           name: z.ZodMiniString<string>;
           purpose: z.ZodMiniString<string>;
           country: z.ZodMiniOptional<z.ZodMiniString<string>>;
+          storage: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniObject<{
+            country: z.ZodMiniString<string>;
+            scope: z.ZodMiniOptional<z.ZodMiniString<string>>;
+          }, z.z.core.$strip>>>;
+          operatorCountry: z.ZodMiniOptional<z.ZodMiniString<string>>;
           privacyUrl: z.ZodMiniOptional<z.ZodMiniURL>;
         }, z.z.core.$strip>>>;
       }, z.z.core.$strip>>;
@@ -1405,12 +1540,14 @@ type OrganizationConfig = z.infer<typeof OrganizationSectionSchema>;
 type SiteSection = z.infer<typeof SiteSectionSchema>;
 /** One `fonts[]` entry — a serialisable projection of an Astro Fonts API family. */
 type SiteFont = z.infer<typeof SiteFontSchema>;
-/** The `seo.indexing` block — what `vitops notify` reads. */
+/** The `seo.indexing` block — what `vitops search notify` reads. */
 type SiteIndexing = z.infer<typeof IndexingSchema>;
 /** IndexNow submission settings. The `key` is public by design. */
 type SiteIndexNow = z.infer<typeof IndexNowSchema>;
 /** Google Search Console property settings. The credential is never in the config. */
 type SiteSearchConsole = z.infer<typeof SearchConsoleSchema>;
+/** One `site.ads` entry — an ad property to link via `vitops ads setup`. */
+type SiteAdProperty = z.infer<typeof AdPropertySchema>;
 declare const CONFIG_SCHEMA_URL = "https://unpkg.com/@getvitops/generator/config.schema.json";
 /** The published JSON Schema (draft-2020-12), derived from the zod schema. */
 declare const configJsonSchema: {
@@ -1666,10 +1803,15 @@ declare const configJsonSchema: {
         }, z.z.core.$strip>>>;
       }, z.z.core.$strip>>>;
       cloudflare: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniUnknown>>;
+      searchConsole: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniObject<{
+        delegatedOwners: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniEmail>>;
+        fullUserGroup: z.ZodMiniOptional<z.ZodMiniEmail>;
+      }, z.z.core.$strip>>>;
       environments: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniObject<{
         url: z.ZodMiniURL;
         api: z.ZodMiniOptional<z.ZodMiniURL>;
         analytics: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+        ads: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
         robots: z.ZodMiniOptional<z.ZodMiniString<string>>;
         variant: z.ZodMiniOptional<z.ZodMiniString<string>>;
       }, z.z.core.$strip>>;
@@ -1875,12 +2017,44 @@ declare const configJsonSchema: {
         }, z.z.core.$strip>>;
       }, z.z.core.$strip>>;
       notifications: z.ZodMiniOptional<z.ZodMiniObject<{
-        email: z.ZodMiniOptional<z.ZodMiniEmail>;
+        email: z.ZodMiniOptional<z.ZodMiniUnion<readonly [z.ZodMiniEmail, z.ZodMiniObject<{
+          provider: z.ZodMiniLiteral<"cloudflare">;
+          to: z.ZodMiniOptional<z.ZodMiniEmail>;
+          from: z.ZodMiniOptional<z.ZodMiniEmail>;
+          fromName: z.ZodMiniOptional<z.ZodMiniString<string>>;
+          replyTo: z.ZodMiniOptional<z.ZodMiniEmail>;
+          binding: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        }, z.z.core.$strip>]>>;
       }, z.z.core.$strip>>;
       tracking: z.ZodMiniOptional<z.ZodMiniObject<{
         enabled: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+        category: z.ZodMiniOptional<z.ZodMiniEnum<{
+          analytics: "analytics";
+          marketing: "marketing";
+        }>>;
         platforms: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniString<string>>>;
       }, z.z.core.$strip>>;
+      ads: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniEnum<{
+        google: "google";
+        meta: "meta";
+        linkedin: "linkedin";
+        reddit: "reddit";
+        tiktok: "tiktok";
+        microsoft: "microsoft";
+        pinterest: "pinterest";
+        snapchat: "snapchat";
+      }> & z.z.core.$partial, z.ZodMiniObject<{
+        accountId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        pixelId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        conversionLabel: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        domain: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        domainVerification: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        category: z.ZodMiniOptional<z.ZodMiniEnum<{
+          analytics: "analytics";
+          marketing: "marketing";
+        }>>;
+        enabled: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+      }, z.z.core.$strip>>>;
       security: z.ZodMiniOptional<z.ZodMiniObject<{
         turnstile: z.ZodMiniOptional<z.ZodMiniObject<{
           siteKey: z.ZodMiniOptional<z.ZodMiniString<string>>;
@@ -1911,6 +2085,11 @@ declare const configJsonSchema: {
             name: z.ZodMiniString<string>;
             purpose: z.ZodMiniString<string>;
             country: z.ZodMiniOptional<z.ZodMiniString<string>>;
+            storage: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniObject<{
+              country: z.ZodMiniString<string>;
+              scope: z.ZodMiniOptional<z.ZodMiniString<string>>;
+            }, z.z.core.$strip>>>;
+            operatorCountry: z.ZodMiniOptional<z.ZodMiniString<string>>;
             privacyUrl: z.ZodMiniOptional<z.ZodMiniURL>;
           }, z.z.core.$strip>>>;
         }, z.z.core.$strip>>;
@@ -2284,12 +2463,216 @@ declare function roleColorUtilities(roles: readonly FunctionalRole[], utilities:
 declare function generate(options: GenerateOptions): Promise<GenerateResult>;
 //#endregion
 //#region src/docs.d.ts
+interface JsonSchemaNode {
+  type?: string;
+  description?: string;
+  properties?: Record<string, JsonSchemaNode>;
+  required?: string[];
+  additionalProperties?: JsonSchemaNode | boolean;
+  anyOf?: JsonSchemaNode[];
+  items?: JsonSchemaNode;
+  enum?: unknown[];
+}
+/**
+ * The inline markdown the schema's `desc()` text actually uses, as HTML. Closed
+ * on purpose, exactly like the legal renderer's subset: these strings are
+ * authored in `schema.ts`, so the set is knowable rather than guessed at.
+ *
+ * Escaping happens before any markup is emitted, so a description containing `<`
+ * cannot inject tags — several do (`<canonical>/<key>.txt`). Exported because the
+ * only safe place for this is one tested function; a caller doing its own escaping
+ * is how one of them eventually doesn't.
+ *
+ * **Code spans are lifted out FIRST, and that is load-bearing rather than tidy.**
+ * `colors.utilities` describes the target families as `` `bg-*` ``, `` `text-*` ``,
+ * `` `border-*` `` — literal asterisk WILDCARDS. Run emphasis over the raw string
+ * and the `*` closing `bg-*` pairs with the one closing `text-*`, wrapping the
+ * text between two unrelated utilities in `<em>` and eating both asterisks. The
+ * prose then silently describes families that don't exist. Lifting code spans
+ * first makes emphasis structurally unable to see inside them.
+ */
+declare const renderInlineMarkdown: (s: string) => string;
+interface SchemaTreeOptions {
+  /** Dotted id prefix, so two trees on one page can't collide. */
+  idPrefix?: string;
+  /** Nesting cap. Unlike the markdown walk there is no reason to truncate. */
+  maxDepth?: number;
+  /**
+   * Dotted paths to render but not descend into.
+   *
+   * Exists for one real case: the project config declares `designSystem.themes`
+   * as a looser shape than `DesignSystemSchema`, because the full one is applied
+   * separately by `resolveTheme`. Its embedded copy is therefore an
+   * APPROXIMATION — measurably so, missing the descriptions for `colors`,
+   * `colors.palette`, `colors.roles` and `colors.utilities`. Rendering it as the
+   * token reference would quietly document the colour system less well than the
+   * design-system schema does, so a caller prunes it here and renders
+   * `jsonSchema` alongside instead.
+   */
+  prune?: readonly string[];
+}
+interface SchemaTreeNode {
+  /** Field name, or `<name>` / `[items]` for a map value or array item. */
+  label: string;
+  /** Human type label — `object`, `map`, `string | number`, `one of`. */
+  type: string;
+  required: boolean;
+  /** Raw schema description (the closed inline-markdown subset), if any. */
+  description?: string;
+  /**
+   * Dotted config path (`site.analytics.clarityId`). Absent when the node is not
+   * addressable: a pseudo-label, or a path already claimed by an earlier node.
+   */
+  id?: string;
+  /** True for an `anyOf` branch, which has no name of its own. */
+  variant?: boolean;
+  children: SchemaTreeNode[];
+}
+/**
+ * Walk a JSON Schema into tree DATA.
+ *
+ * The same walk that produces the `authoring.md` / `config.md` bullet lists,
+ * returned as a node model instead of a string. Returning data rather than markup
+ * is deliberate and follows `roleColorUtilities()`: the *shape* of the tree is one
+ * decision, and each medium renders it — markdown for agents, an accessible
+ * `<details>` tree for the docs site. An HTML-emitting version here would be a
+ * second source of the markup contract for `<wc-tree>` to drift from.
+ *
+ * Ids are dotted paths so a field can be linked to directly. Map-value and
+ * array-item pseudo-labels are skipped in the path: `site.dns.records` reads
+ * better than `site.dns.<domain>.records`, and neither `<domain>` nor `[items]`
+ * is a real key.
+ */
+declare function schemaTreeNodes(schema: JsonSchemaNode, opts?: SchemaTreeOptions): SchemaTreeNode[];
 /**
  * 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/tiers.d.ts
+/**
+ * Which tiers provide each pattern, and which call to make.
+ *
+ * The toolkit ships four tiers that COMPOSE — CSS framework classes, Lit web
+ * components, Astro components, Bricks elements — and the composition is what a
+ * consumer actually needs. For a tree: `.tree` styles it, `<Tree />` generates the
+ * markup, `<wc-tree>` enhances it. This file is the single source for that, and
+ * `tiers.test.ts` holds it to the files on disk.
+ *
+ * **Authored, not derived, and that is deliberate.** Name convention carries most
+ * of it (`patterns/<name>.css` ↔ `WC<Name>.ts` → `wc-<name>` ↔
+ * `bricks/elements/<name>.php`) but breaks where it matters:
+ *
+ *   - `splitter.css` hosts TWO components (`wc-split-panel`, `wc-image-compare`);
+ *   - `anchor-link.css` provides `.link`, whose config pattern is `link`;
+ *   - `tag.css` carries parts for THREE config patterns (`badge`, `tag`, `status`);
+ *   - `layout.css` (a root partial, not under `patterns/`) provides `.split` and
+ *     `.centered`, both of which have Bricks elements;
+ *   - `forms.css`, `nav.css`, `navbar.css`, `navshell.css` each serve several tiers.
+ *
+ * A derivation would need an exceptions table longer than the rule, and a rename
+ * would silently drop a link instead of failing. So it is authored, and the guards
+ * make omission a build failure rather than a missing docs row.
+ *
+ * **The composition rule this encodes** (see `AGENTS.md`, tier 3): an Astro
+ * component emits the `<wc-*>` tag with the accessible fallback INSIDE it. So
+ * `<Tree />` is the whole call — wrapping it in your own `<wc-tree>` nests two
+ * elements on one tree. `astro.wraps` records which case each component is, because
+ * it varies: `Tree` and `CookieConsent` wrap a web component, while `Details`,
+ * `Drawer`, `Popover`, `NavShell` and `Subgrid` emit tier-1 markup with no web
+ * component at all. That cannot be inferred from the taxonomy.
+ */
+/** A pattern's CSS. `generated` means `design-system.json`'s `patterns.items`. */
+interface TierCss {
+  /**
+   * Hand-written partial, relative to `packages/core/css/` — usually
+   * `patterns/<name>.css`, occasionally a root partial such as `layout.css`.
+   * Absent when the pattern is generated CSS only.
+   */
+  partial?: string;
+  /** Representative classes. Not exhaustive — the class reference enumerates. */
+  classes: string[];
+  /**
+   * True when the pattern is **config-authored** — its CSS comes from
+   * `patterns.items.<name>`, so it gets the token cascade, `states`, role variants
+   * and `BASE_HOOK` override vars. False means a purely structural partial with
+   * none of those.
+   *
+   * Note `patterns.items` is CONSUMER-authored: `defaultConfig()` ships only
+   * `btn`/`cta`/`card`, and a consumer declares whatever else they need. So this
+   * flag records which patterns are *of that kind* — the reference set is this
+   * repo's own `src/design-system.json`, which is what the docs render from — not a
+   * promise about any particular consumer's config.
+   */
+  generated: boolean;
+}
+interface TierWc {
+  tag: string;
+  /** In `elements.js`. False = its own bundle, or not shipped at all. */
+  registered: boolean;
+  /** What JS adds over the fallback. The reason the tier exists for this pattern. */
+  adds: string;
+  /** Set when the element ships somewhere other than `elements.js`. */
+  bundle?: string;
+}
+interface TierAstro {
+  /** Import specifier, e.g. `@getvitops/astro/components/Tree.astro`. */
+  component: string;
+  /**
+   * `wc` — emits the `<wc-*>` tag with the fallback inside, so this one call is the
+   * whole composition. `css` — emits tier-1 markup; there is no web component.
+   */
+  wraps: 'wc' | 'css';
+}
+interface TierEntry {
+  css: TierCss;
+  wc?: TierWc;
+  /**
+   * Astro components for this pattern. An array because a pattern can ship more
+   * than one — `navshell` has both `NavShell` and `NavShellToggle`, since the
+   * toggle must be placeable outside the shell.
+   */
+  astro?: TierAstro[];
+  /** Bricks element `$name`, e.g. `vitops-carousel`. */
+  bricks?: string;
+  /** The one line an agent needs: what to actually write. */
+  use: string;
+}
+declare const TIERS: Record<string, TierEntry>;
+/** Pattern names, sorted — a stable order for docs and tests. */
+declare const TIER_NAMES: readonly string[];
+/** Every `wc-*` tag the manifest knows, whether shipped in `elements.js` or not. */
+declare function tierTags(): {
+  tag: string;
+  registered: boolean;
+  pattern: string;
+}[];
+/** The four tiers, as a projection axis. */
+type Tier = 'css' | 'wc' | 'astro' | 'bricks';
+/** A pattern paired with its entry — what one tier's projection iterates. */
+interface TierProjection {
+  name: string;
+  entry: TierEntry;
+}
+/**
+ * The patterns one tier provides, in `TIER_NAMES` order.
+ *
+ * Every renderer goes through this rather than filtering `TIERS` itself: the docs
+ * bundle projects all four tiers into one table for agents, the docsite projects
+ * each tier as its own page for humans, and they must agree about which patterns
+ * are in a tier. Five copies of `.filter(e => e.wc)` would agree until one of them
+ * didn't.
+ *
+ * `css` needs a predicate rather than a presence check, which is the non-obvious
+ * part. `TierEntry.css` is required, so *every* entry has one — including the
+ * editor-v2 track, whose entries carry `c([])`: no partial, no classes, not
+ * generated. Treating the field's presence as membership would list four patterns
+ * on the CSS page with nothing to show for them, and `color-wheel` genuinely has
+ * no CSS. The other three tiers are optional fields, so presence is the test.
+ */
+declare function tierPatterns(tier: Tier): TierProjection[];
+//#endregion
 //#region ../../node_modules/.pnpm/@iconify+types@2.0.0/node_modules/@iconify/types/types.d.ts
 /**
  * Icon dimensions.
@@ -2537,7 +2920,7 @@ declare function loadIconSvg(qualified: string, opts?: {
  *
  * `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
+ * flip was unreachable outside Bricks: the shipped `<wc-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.
@@ -2602,13 +2985,48 @@ declare const BASE_HOOK: Record<string, string>;
 declare const TW_CLASH: ReadonlySet<string>;
 //#endregion
 //#region src/legal/providers.d.ts
+/** One place a provider holds information, and which information if not all of it. */
+interface ProcessorStorage {
+  /** Reads inside a sentence: "…including the United States". */
+  country: string;
+  /**
+   * Reads after "in the case of". Present means this location holds only SOME of
+   * what the provider receives, which is a narrower claim than an unscoped entry —
+   * so the template gives it its own sentence rather than folding it into the list,
+   * where a reader would take it to cover everything.
+   */
+  scope?: string | undefined;
+}
 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". */
+  /**
+   * Shorthand asserting BOTH `storage` and `operatorCountry` are this one country.
+   *
+   * Kept for the common case (and because it is public API), but note it is the
+   * field whose *meaning* was never defined — its old doc comment described how it
+   * READ, not what it asserted, which is how one string came to stand for two
+   * different facts. Prefer the explicit pair when they differ.
+   */
   country?: string | undefined;
+  /**
+   * Where the information actually rests. Feeds the "stored or processed outside
+   * of <jurisdiction>" disclosure and nothing else.
+   */
+  storage?: ProcessorStorage[] | undefined;
+  /**
+   * The jurisdiction that can compel this provider to produce the information —
+   * where it is established, or from which it is controlled. Reads after "the laws
+   * of".
+   *
+   * A separate fact from `storage`, and the one privacy law actually turns on: the
+   * OPC's concern is foreign *access*, not foreign storage. Azure in a Canadian
+   * region is `storage: [{ country: 'Canada' }]`, `operatorCountry: 'the United
+   * States'` — the bytes never move and US law still reaches them.
+   */
+  operatorCountry?: string | undefined;
   privacyUrl?: string | undefined;
   /**
    * Cookies this provider sets. An empty array is meaningful and not the same as
@@ -2669,28 +3087,28 @@ declare const KNOWN_PROCESSORS: {
   turnstile: {
     name: string;
     purpose: string;
-    country: string;
+    operatorCountry: string;
     privacyUrl: string;
     cookies: string[];
   };
   cloudflare: {
     name: string;
     purpose: string;
-    country: string;
+    operatorCountry: string;
     privacyUrl: string;
     cookies: never[];
   };
   vercel: {
     name: string;
     purpose: string;
-    country: string;
+    operatorCountry: string;
     privacyUrl: string;
     cookies: never[];
   };
   netlify: {
     name: string;
     purpose: string;
-    country: string;
+    operatorCountry: string;
     privacyUrl: string;
     cookies: never[];
   };
@@ -2712,6 +3130,19 @@ declare function detectProcessorKeys(cfg: Config): KnownProcessorKey[];
  * an explicit declaration is a statement of fact we have no grounds to drop.
  */
 declare function resolveProcessors(cfg: Config): Processor[];
+/**
+ * Processors the config discloses but places nowhere.
+ *
+ * Such a processor cannot appear in the transfer disclosure — there is nothing true
+ * to say about it — and today it vanishes from that section in silence, which is the
+ * tidy-looking failure. Names only, and deliberately NOT on `PolicyVars`: that type
+ * is the facts a template renders from, and a document must not editorialise about
+ * its own gaps. The CLI reports these on stderr instead.
+ *
+ * Not a `validateConfig` error either: a bare `{ name, purpose }` validates today,
+ * so rejecting it would make this a breaking change.
+ */
+declare function processorsMissingLocation(cfg: Config): string[];
 //#endregion
 //#region src/legal/derive.d.ts
 /**
@@ -2757,7 +3188,54 @@ interface PolicyVars {
    * 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". */
+  /**
+   * Cookies the site sets itself.
+   *
+   * Separate from `processors`, which are third parties — no provider table would
+   * ever name a first-party cookie, so without this the notice can say "we do not
+   * set cookies" while `_ac` sits in the visitor's browser.
+   */
+  firstPartyCookies: {
+    name: string;
+    purpose: string;
+    retention: string;
+  }[];
+  /**
+   * The country this document frames transfers as *leaving*, from the jurisdiction
+   * rather than the org's address — a `ca` policy says "outside of Canada" even for
+   * a business incorporated elsewhere. (`governingCountry` is the address, and
+   * drives a different sentence: the terms' governing-law clause.)
+   */
+  jurisdictionCountry: string;
+  /**
+   * Reads after "including": foreign countries where information rests, with no
+   * category attached — the broad claim.
+   */
+  storageCountries: string | undefined;
+  /**
+   * Foreign storage locations holding only SOME categories. Structured rather than
+   * pre-joined, because the connective ("in the case of") is the template's word,
+   * not a fact. Disjoint from `storageCountries`: a country already claimed
+   * unscoped is never repeated here, since the unscoped claim is the broader one.
+   */
+  scopedStorage: {
+    country: string;
+    scope: string;
+  }[];
+  /**
+   * Reads after "the laws of": foreign jurisdictions that can compel a provider to
+   * produce information, EXCLUDING any already named in `storageCountries` —
+   * saying US law reaches information already disclosed as stored in the US adds a
+   * sentence and no fact.
+   */
+  operatorCountries: string | undefined;
+  /**
+   * Reads after "including": "…the United States and the European Union".
+   *
+   * @deprecated Split into `storageCountries` and `operatorCountries`, which keep
+   * residency and legal reach apart. Retained, and still every country the field
+   * ever named, so a consumer's own template renders what it always rendered.
+   */
   countries: string | undefined;
   consentModel: 'opt-in' | 'opt-out' | 'none';
   cookieCategories: string[];
@@ -2865,5 +3343,5 @@ declare function generateLegal(cfg: Config, opts?: GenerateLegalOptions): Record
  */
 declare function defaultConfig(): DesignSystem;
 //#endregion
-export { BASE_HOOK, type Block, CONFIG_SCHEMA_URL, CONTRAST, type ColorUtility, type Config, ConfigSchema, type ConfigValidationResult, 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, type IconSpriteOptions, type IconSpriteResult, JURISDICTIONS, type Jurisdiction, KNOWN_PROCESSORS, type KnownProcessorKey, type LegalDoc, type LegalOutput, NUMERIC_STEPS, type OrganizationConfig, type PolicyVars, type PostalAddress, type Processor, REQUIRED_ROLES, ROLE_TOKEN_KEYS, type ResolvedInput, type RoleKind, type RoleSpec, SCHEMA_URL, type SiteFont, SiteFontSchema, type SiteIndexNow, type SiteIndexing, type SiteSearchConsole, type SiteSection, type Span, type StylesheetFormat, TEMPLATES, TW_CLASH, type ValidationResult, buildIconSprite, configJsonSchema, deepMerge, defaultConfig, derivePolicyVars, detectProcessorKeys, enabledDocs, expandPalette, functionalRole, generate, generateDocs, generateLegal, isConfig, jsonSchema, loadIconSvg, parseMarkdown, renderMarkdown, renderNodes, resolveConfig, resolveInput, resolvePrivacyContact, resolveProcessors, resolveTheme, roleColorUtilities, roleHue, roleKind, spriteId, stripNulls, toContentNodes, toHtmlFragment, toPortableText, tokenClass, tokenVar, validate, validateConfig };
+export { AD_PROVIDERS, type AdProvider, BASE_HOOK, type Block, CONFIG_SCHEMA_URL, CONTRAST, type ColorUtility, type Config, ConfigSchema, type ConfigValidationResult, 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, type IconSpriteOptions, type IconSpriteResult, JURISDICTIONS, JURISDICTION_COUNTRIES, type JsonSchemaNode, type Jurisdiction, KNOWN_PROCESSORS, type KnownProcessorKey, type LegalDoc, type LegalOutput, NUMERIC_STEPS, type OrganizationConfig, type PolicyVars, type PostalAddress, type Processor, type ProcessorStorage, REQUIRED_ROLES, ROLE_TOKEN_KEYS, type ResolvedInput, type RoleKind, type RoleSpec, SCHEMA_URL, type SchemaTreeNode, type SchemaTreeOptions, type SiteAdProperty, type SiteFont, SiteFontSchema, type SiteIndexNow, type SiteIndexing, type SiteSearchConsole, type SiteSection, type Span, type StylesheetFormat, TEMPLATES, TIERS, TIER_NAMES, TW_CLASH, type Tier, type TierAstro, type TierCss, type TierEntry, type TierProjection, type TierWc, type ValidationResult, buildIconSprite, configJsonSchema, deepMerge, defaultConfig, derivePolicyVars, detectProcessorKeys, enabledDocs, expandPalette, functionalRole, generate, generateDocs, generateLegal, isConfig, jsonSchema, loadIconSvg, parseMarkdown, processorsMissingLocation, renderInlineMarkdown, renderMarkdown, renderNodes, resolveConfig, resolveInput, resolvePrivacyContact, resolveProcessors, resolveTheme, roleColorUtilities, roleHue, roleKind, schemaTreeNodes, spriteId, stripNulls, tierPatterns, tierTags, toContentNodes, toHtmlFragment, toPortableText, tokenClass, tokenVar, validate, validateConfig };
 //# sourceMappingURL=index.d.mts.map