@getvitops/astro 3.0.0 → 4.0.0

package/dist/routes/conversion.d.mts

@@ -0,0 +1,45 @@
+import { EmailBinding, NotifyContext, notify } from "@getvitops/utils/notify";
+
+//#region src/routes/conversion.d.ts
+/** The subset of Astro's `APIContext` this needs — typed structurally so the
+ * factory does not pin an Astro version. */
+interface ConversionRequestContext {
+  request: Request;
+  locals?: unknown;
+}
+interface ConversionRouteOptions {
+  /** Where notifications go. Build it from your site config. */
+  context: NotifyContext;
+  /**
+   * The Workers `send_email` binding for this request, e.g.
+   * `(locals) => locals.runtime.env.EMAIL`. Omit it in dev and the notification
+   * is printed instead of sent.
+   */
+  binding?: (locals: unknown) => EmailBinding | undefined;
+  /**
+   * Reject a submission before anything is sent. Return a message to refuse.
+   * This is where a consumer puts required-field checks and spam rules.
+   */
+  validate?: (body: Record<string, unknown>) => string | null;
+  /** Called with every channel outcome, delivered or not. Defaults to console. */
+  onResult?: (result: Awaited<ReturnType<typeof notify>>) => void;
+  /** Injected in tests. */
+  now?: () => number;
+}
+/**
+ * Build a POST handler for conversions.
+ *
+ * Returns 204 for a beacon and 200 with `{ success }` for a form, matching what
+ * `navigator.sendBeacon` and a fetch-submitting form each expect.
+ *
+ * **A failed notification does not fail the request.** The visitor has already
+ * submitted; refusing them because our mail did not go out turns a lost
+ * notification into a lost conversion. Failures are reported through `onResult`.
+ */
+declare function createConversionRoute(options: ConversionRouteOptions): ({
+  request,
+  locals
+}: ConversionRequestContext) => Promise<Response>;
+//#endregion
+export { ConversionRequestContext, ConversionRouteOptions, createConversionRoute };
+//# sourceMappingURL=conversion.d.mts.map

package/dist/routes/conversion.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversion.d.mts","names":[],"sources":["../../src/routes/conversion.ts"],"mappings":";;;;;UAgCiB,wBAAA;EACf,OAAA,EAAS,OAAO;EAChB,MAAA;AAAA;AAAA,UAGe,sBAAA;EAe+B;EAb9C,OAAA,EAAS,aAAA;EAeT;;AAAG;AA0BL;;EAnCE,OAAA,IAAW,MAAA,cAAoB,YAAA;EAmCc;;;;EA9B7C,QAAA,IAAY,IAAA,EAAM,MAAA;EAiC4C;EA/B9D,QAAA,IAAY,MAAA,EAAQ,OAAA,CAAQ,UAAA,QAAkB,MAAA;EA+BuB;EA7BrE,GAAA;AAAA;;;;;;;;;AA6B8E;;iBAHhE,qBAAA,CAAsB,OAAA,EAAS,sBAAA;EAG/B,OAAA;EAAA;AAAA,GAAqB,wBAAA,KAA2B,OAAA,CAAQ,QAAA"}

package/dist/routes/conversion.mjs

@@ -0,0 +1,95 @@
+import { notify } from "@getvitops/utils/notify";
+import { parseTrackingCookie } from "@getvitops/utils/tracking";
+
+//#region src/routes/conversion.ts
+/**
+* The conversion endpoint, as a factory.
+*
+* A site's contact form and its `tel:` beacon both mean the same thing — someone
+* got in touch — and both want the same treatment: read the attribution cookie
+* off the request, build the event, notify whoever the config says. That is the
+* same three lines in every project, so it ships here.
+*
+* What deliberately does **not** ship here is validation and business rules. A
+* consumer's form has its own required fields, its own spam handling and its own
+* response shape, and baking a guess at those in would make the factory something
+* to fight rather than mount. The handler takes the parsed body and an optional
+* `validate`; everything else is the caller's.
+*
+* ```ts
+* // src/pages/api/track.ts
+* export const prerender = false;
+* import { createConversionRoute } from '@getvitops/astro/routes';
+* import config from '../../site.config.json';
+*
+* export const POST = createConversionRoute({
+*   context: toNotifyContext(config),
+*   binding: (locals) => locals.runtime?.env?.EMAIL,
+* });
+* ```
+*/
+/** Fields that are never part of a submission's meaning. */
+const CONTROL_FIELDS = new Set(["event", "phone"]);
+function toFormData(body) {
+	const out = {};
+	for (const [key, value] of Object.entries(body)) {
+		if (CONTROL_FIELDS.has(key)) continue;
+		if (value === void 0 || value === null) continue;
+		out[key] = String(value);
+	}
+	return out;
+}
+/**
+* Build a POST handler for conversions.
+*
+* Returns 204 for a beacon and 200 with `{ success }` for a form, matching what
+* `navigator.sendBeacon` and a fetch-submitting form each expect.
+*
+* **A failed notification does not fail the request.** The visitor has already
+* submitted; refusing them because our mail did not go out turns a lost
+* notification into a lost conversion. Failures are reported through `onResult`.
+*/
+function createConversionRoute(options) {
+	const { context, binding, validate, onResult, now = Date.now } = options;
+	return async ({ request, locals }) => {
+		let body;
+		try {
+			const parsed = await request.json();
+			if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return Response.json({
+				success: false,
+				error: "Malformed request."
+			}, { status: 400 });
+			body = parsed;
+		} catch {
+			return Response.json({
+				success: false,
+				error: "Malformed request."
+			}, { status: 400 });
+		}
+		const isCall = body["event"] === "call";
+		if (isCall && typeof body["phone"] !== "string") return Response.json({
+			success: false,
+			error: "Missing phone."
+		}, { status: 400 });
+		const refusal = validate?.(body);
+		if (refusal) return Response.json({
+			success: false,
+			error: refusal
+		}, { status: 400 });
+		const result = await notify({
+			type: isCall ? "call" : "form",
+			...isCall ? { phone: String(body["phone"]).replace(/^tel:/, "") } : { formData: toFormData(body) },
+			tracking: parseTrackingCookie(request.headers.get("cookie")),
+			userAgent: request.headers.get("user-agent") ?? void 0,
+			ip: request.headers.get("cf-connecting-ip") ?? request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ?? void 0,
+			at: now()
+		}, context, { email: binding?.(locals) });
+		if (onResult) onResult(result);
+		else for (const r of result.results) if (!r.sent) console.warn(`[vitops] notification not sent (${r.channel}): ${r.reason}`);
+		return isCall ? new Response(null, { status: 204 }) : Response.json({ success: true });
+	};
+}
+
+//#endregion
+export { createConversionRoute };
+//# sourceMappingURL=conversion.mjs.map

package/dist/routes/conversion.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversion.mjs","names":[],"sources":["../../src/routes/conversion.ts"],"sourcesContent":["/**\n * The conversion endpoint, as a factory.\n *\n * A site's contact form and its `tel:` beacon both mean the same thing — someone\n * got in touch — and both want the same treatment: read the attribution cookie\n * off the request, build the event, notify whoever the config says. That is the\n * same three lines in every project, so it ships here.\n *\n * What deliberately does **not** ship here is validation and business rules. A\n * consumer's form has its own required fields, its own spam handling and its own\n * response shape, and baking a guess at those in would make the factory something\n * to fight rather than mount. The handler takes the parsed body and an optional\n * `validate`; everything else is the caller's.\n *\n * ```ts\n * // src/pages/api/track.ts\n * export const prerender = false;\n * import { createConversionRoute } from '@getvitops/astro/routes';\n * import config from '../../site.config.json';\n *\n * export const POST = createConversionRoute({\n *   context: toNotifyContext(config),\n *   binding: (locals) => locals.runtime?.env?.EMAIL,\n * });\n * ```\n */\nimport { type EmailBinding, notify, type NotifyContext } from '@getvitops/utils/notify';\nimport { parseTrackingCookie } from '@getvitops/utils/tracking';\nimport type { ConversionEvent } from '@getvitops/utils/tracking';\n\n/** The subset of Astro's `APIContext` this needs — typed structurally so the\n * factory does not pin an Astro version. */\nexport interface ConversionRequestContext {\n  request: Request;\n  locals?: unknown;\n}\n\nexport interface ConversionRouteOptions {\n  /** Where notifications go. Build it from your site config. */\n  context: NotifyContext;\n  /**\n   * The Workers `send_email` binding for this request, e.g.\n   * `(locals) => locals.runtime.env.EMAIL`. Omit it in dev and the notification\n   * is printed instead of sent.\n   */\n  binding?: (locals: unknown) => EmailBinding | undefined;\n  /**\n   * Reject a submission before anything is sent. Return a message to refuse.\n   * This is where a consumer puts required-field checks and spam rules.\n   */\n  validate?: (body: Record<string, unknown>) => string | null;\n  /** Called with every channel outcome, delivered or not. Defaults to console. */\n  onResult?: (result: Awaited<ReturnType<typeof notify>>) => void;\n  /** Injected in tests. */\n  now?: () => number;\n}\n\n/** Fields that are never part of a submission's meaning. */\nconst CONTROL_FIELDS = new Set(['event', 'phone']);\n\nfunction toFormData(body: Record<string, unknown>): Record<string, string> {\n  const out: Record<string, string> = {};\n  for (const [key, value] of Object.entries(body)) {\n    if (CONTROL_FIELDS.has(key)) continue;\n    if (value === undefined || value === null) continue;\n    out[key] = String(value);\n  }\n  return out;\n}\n\n/**\n * Build a POST handler for conversions.\n *\n * Returns 204 for a beacon and 200 with `{ success }` for a form, matching what\n * `navigator.sendBeacon` and a fetch-submitting form each expect.\n *\n * **A failed notification does not fail the request.** The visitor has already\n * submitted; refusing them because our mail did not go out turns a lost\n * notification into a lost conversion. Failures are reported through `onResult`.\n */\nexport function createConversionRoute(options: ConversionRouteOptions) {\n  const { context, binding, validate, onResult, now = Date.now } = options;\n\n  return async ({ request, locals }: ConversionRequestContext): Promise<Response> => {\n    let body: Record<string, unknown>;\n    try {\n      const parsed: unknown = await request.json();\n      if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {\n        return Response.json({ success: false, error: 'Malformed request.' }, { status: 400 });\n      }\n      body = parsed as Record<string, unknown>;\n    } catch {\n      return Response.json({ success: false, error: 'Malformed request.' }, { status: 400 });\n    }\n\n    const isCall = body['event'] === 'call';\n    if (isCall && typeof body['phone'] !== 'string') {\n      return Response.json({ success: false, error: 'Missing phone.' }, { status: 400 });\n    }\n\n    const refusal = validate?.(body);\n    if (refusal) return Response.json({ success: false, error: refusal }, { status: 400 });\n\n    const event: ConversionEvent = {\n      type: isCall ? 'call' : 'form',\n      ...(isCall\n        ? { phone: String(body['phone']).replace(/^tel:/, '') }\n        : { formData: toFormData(body) }),\n      tracking: parseTrackingCookie(request.headers.get('cookie')),\n      userAgent: request.headers.get('user-agent') ?? undefined,\n      // Cloudflare's own header first; `x-forwarded-for` is the portable fallback\n      // and may carry a proxy chain, whose first entry is the client.\n      ip:\n        request.headers.get('cf-connecting-ip') ??\n        request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ??\n        undefined,\n      at: now(),\n    };\n\n    const result = await notify(event, context, { email: binding?.(locals) });\n\n    if (onResult) onResult(result);\n    else\n      for (const r of result.results) {\n        if (!r.sent) console.warn(`[vitops] notification not sent (${r.channel}): ${r.reason}`);\n      }\n\n    return isCall ? new Response(null, { status: 204 }) : Response.json({ success: true });\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DA,MAAM,iBAAiB,IAAI,IAAI,CAAC,SAAS,OAAO,CAAC;AAEjD,SAAS,WAAW,MAAuD;CACzE,MAAM,MAA8B,CAAC;CACrC,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,IAAI,GAAG;EAC/C,IAAI,eAAe,IAAI,GAAG,GAAG;EAC7B,IAAI,UAAU,UAAa,UAAU,MAAM;EAC3C,IAAI,OAAO,OAAO,KAAK;CACzB;CACA,OAAO;AACT;;;;;;;;;;;AAYA,SAAgB,sBAAsB,SAAiC;CACrE,MAAM,EAAE,SAAS,SAAS,UAAU,UAAU,MAAM,KAAK,QAAQ;CAEjE,OAAO,OAAO,EAAE,SAAS,aAA0D;EACjF,IAAI;EACJ,IAAI;GACF,MAAM,SAAkB,MAAM,QAAQ,KAAK;GAC3C,IAAI,OAAO,WAAW,YAAY,WAAW,QAAQ,MAAM,QAAQ,MAAM,GACvE,OAAO,SAAS,KAAK;IAAE,SAAS;IAAO,OAAO;GAAqB,GAAG,EAAE,QAAQ,IAAI,CAAC;GAEvF,OAAO;EACT,QAAQ;GACN,OAAO,SAAS,KAAK;IAAE,SAAS;IAAO,OAAO;GAAqB,GAAG,EAAE,QAAQ,IAAI,CAAC;EACvF;EAEA,MAAM,SAAS,KAAK,aAAa;EACjC,IAAI,UAAU,OAAO,KAAK,aAAa,UACrC,OAAO,SAAS,KAAK;GAAE,SAAS;GAAO,OAAO;EAAiB,GAAG,EAAE,QAAQ,IAAI,CAAC;EAGnF,MAAM,UAAU,WAAW,IAAI;EAC/B,IAAI,SAAS,OAAO,SAAS,KAAK;GAAE,SAAS;GAAO,OAAO;EAAQ,GAAG,EAAE,QAAQ,IAAI,CAAC;EAkBrF,MAAM,SAAS,MAAM,OAAO;GAf1B,MAAM,SAAS,SAAS;GACxB,GAAI,SACA,EAAE,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,QAAQ,SAAS,EAAE,EAAE,IACpD,EAAE,UAAU,WAAW,IAAI,EAAE;GACjC,UAAU,oBAAoB,QAAQ,QAAQ,IAAI,QAAQ,CAAC;GAC3D,WAAW,QAAQ,QAAQ,IAAI,YAAY,KAAK;GAGhD,IACE,QAAQ,QAAQ,IAAI,kBAAkB,KACtC,QAAQ,QAAQ,IAAI,iBAAiB,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK,KAC5D;GACF,IAAI,IAAI;EAGsB,GAAG,SAAS,EAAE,OAAO,UAAU,MAAM,EAAE,CAAC;EAExE,IAAI,UAAU,SAAS,MAAM;OAE3B,KAAK,MAAM,KAAK,OAAO,SACrB,IAAI,CAAC,EAAE,MAAM,QAAQ,KAAK,mCAAmC,EAAE,QAAQ,KAAK,EAAE,QAAQ;EAG1F,OAAO,SAAS,IAAI,SAAS,MAAM,EAAE,QAAQ,IAAI,CAAC,IAAI,SAAS,KAAK,EAAE,SAAS,KAAK,CAAC;CACvF;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getvitops/astro",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "Astro integration for the Vitops design system — favicons/PWA, web-component scripts, and CSS, via a getvitops() integration + <Head /> component.",
   "license": "MIT",
   "files": [
@@ -23,7 +23,13 @@
     "src/components/NavShellToggle.astro",
     "src/schemas",
     "virtual.d.ts",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "src/components/Tracking.astro",
+    "src/scripts/tracking.ts",
+    "src/tracking.ts",
+    "src/components/Tree.astro",
+    "src/components/TreeNode.astro",
+    "src/components/tree.ts"
   ],
   "type": "module",
   "types": "./dist/index.d.mts",
@@ -32,10 +38,15 @@
       "types": "./dist/index.d.mts",
       "import": "./dist/index.mjs"
     },
+    "./routes": {
+      "types": "./dist/routes/conversion.d.mts",
+      "import": "./dist/routes/conversion.mjs"
+    },
     "./Head.astro": "./src/components/Head.astro",
     "./Seo.astro": "./src/components/Seo.astro",
     "./Analytics.astro": "./src/components/Analytics.astro",
     "./CookieConsent.astro": "./src/components/CookieConsent.astro",
+    "./Tracking.astro": "./src/components/Tracking.astro",
     "./components/Subgrid.astro": "./src/components/Subgrid.astro",
     "./components/Cards.astro": "./src/components/Cards.astro",
     "./components/NodeRenderer.astro": "./src/components/NodeRenderer.astro",
@@ -46,6 +57,8 @@
     "./components/Drawer.astro": "./src/components/Drawer.astro",
     "./components/NavShell.astro": "./src/components/NavShell.astro",
     "./components/NavShellToggle.astro": "./src/components/NavShellToggle.astro",
+    "./components/Tree.astro": "./src/components/Tree.astro",
+    "./components/tree.ts": "./src/components/tree.ts",
     "./schemas/*": "./src/schemas/*",
     "./package.json": "./package.json"
   },
@@ -53,10 +66,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@getvitops/core": "3.0.0",
-    "@getvitops/utils": "3.0.0",
-    "@getvitops/generator": "3.0.0",
-    "@getvitops/vite": "3.0.0"
+    "@getvitops/generator": "4.0.0",
+    "@getvitops/vite": "4.0.0",
+    "@getvitops/core": "4.0.0",
+    "@getvitops/utils": "4.0.0"
   },
   "devDependencies": {
     "@astrojs/sitemap": "^3.7.3",

package/src/components/CookieConsent.astro

@@ -14,6 +14,13 @@
  * writes one — otherwise the thing asking permission would be the thing needing
  * it.
  *
+ * **`categories` is what the banner *can* ask, not what it will.** A row here is
+ * markup, and a hidden row costs nothing, so the default is generous — every
+ * category the site could plausibly gate. `<wc-consent>` reveals only the rows
+ * something has actually demanded and the visitor hasn't answered, so being
+ * generous here buys coverage without buying interruptions. Narrow it only to
+ * refuse a category outright.
+ *
  * **Consent is not an analytics feature.** The same gate covers A/B assignment,
  * personalisation and embedded third-party content: mark any of them
  * `data-consent="<category>"` and they wait on the same choice. Which categories
@@ -50,7 +57,7 @@ const DEFAULT_LABELS: Record<OptionalConsentCategory, string> = {
 };
 
 const {
-  categories = head.consentCategories ?? ['analytics'],
+  categories = head.consentCategories ?? ['analytics', 'preferences'],
   policyUrl = head.consentPolicyUrl ?? undefined,
   policyLabel = 'Cookie notice',
   heading = 'Cookies on this site',
@@ -62,9 +69,6 @@ const {
 } = Astro.props;
 
 const wording = { ...DEFAULT_LABELS, ...labels };
-// One category is a yes/no question; checkboxes for it would be a form standing in
-// for two buttons that already say the same thing.
-const choose = categories.length > 1;
 ---
 
 <wc-consent hidden {...noReloadOnRevoke ? { 'reload-on-revoke': 'false' } : {}}>
@@ -86,20 +90,24 @@ const choose = categories.length > 1;
       {policyUrl && <a class="link" href={policyUrl}>{policyLabel}</a>}
     </div>
 
-    {choose && (
-      <div class="consent__options">
-        {categories.map((category) => (
-          <label>
-            <input type="checkbox" name={category} />
-            {wording[category]}
-          </label>
-        ))}
-      </div>
-    )}
+    {/*
+      A row per offered category, always rendered. Which of them the visitor
+      actually sees is a runtime decision — `data-consent-row` is how
+      `<wc-consent>` addresses one to reveal or hide it, and it hides the whole
+      group when a showing is about a single category.
+    */}
+    <div class="consent__options">
+      {categories.map((category) => (
+        <label data-consent-row={category}>
+          <input type="checkbox" name={category} />
+          {wording[category]}
+        </label>
+      ))}
+    </div>
 
     <div class="consent__actions">
       <button type="button" class="btn" data-consent-reject>{rejectLabel}</button>
-      {choose && <button type="button" class="btn" data-consent-save>{saveLabel}</button>}
+      <button type="button" class="btn" data-consent-save>{saveLabel}</button>
       <button type="button" class="cta" data-consent-accept>{acceptLabel}</button>
     </div>
   </form>

package/src/components/Head.astro

@@ -41,6 +41,33 @@ const THEME_SCRIPT =
   `if(s==='light'||s==='dark'){document.documentElement.dataset.theme=s;` +
   `document.documentElement.style.colorScheme=s+' only'}}catch(e){}`;
 
+/**
+ * The consent gate's build-time signal: "something on this page may need
+ * permission, and the real gate hasn't loaded yet."
+ *
+ * `consent.js` and `elements.js` are both deferred modules with no ordering
+ * guarantee between them, so `<wc-color-scheme-toggle>` can upgrade and be clicked
+ * before the gate exists. Without this, a caller probing for
+ * `window.vitopsConsent` in that window would see nothing, correctly conclude
+ * that sites without the gate should just store — and store. The stub closes the
+ * window by making the gate's *existence* known synchronously in `<head>`, which
+ * is the only place that beats every deferred bundle.
+ *
+ * It answers `false` to everything, because nothing is granted until the store
+ * has been read, and queues what it was asked so `consent/runtime.ts` can replay
+ * it on evaluation. `q` entries are `[category]` for `require()` and
+ * `[category, resolve]` for `request()`. Same shape as the `dataLayer`/`gtag`
+ * stub in `analytics.ts` and for the same reason.
+ *
+ * Emitted only when the gate is on: its absence is what tells a caller the site
+ * has no gate at all.
+ */
+const CONSENT_STUB =
+  `window.vitopsConsent=window.vitopsConsent||{q:[],` +
+  `require:function(c){this.q.push([c]);return false},` +
+  `request:function(c){var s=this;return new Promise(function(r){s.q.push([c,r])})},` +
+  `granted:function(){return false},needed:function(){return false}};`;
+
 /*
  * No `<html>` class flips here on purpose. `animation.css` used to need `no-js`
  * and `.no-scroll-timeline` set before first paint; it now asks the platform
@@ -80,12 +107,23 @@ const THEME_SCRIPT =
 {/* Set by vitops({ sitemap }); null when no sitemap was registered. */}
 {head.sitemap && <link rel="sitemap" type="application/xml" href={head.sitemap} />}
 
+{/*
+  The consent stub — synchronous, and ahead of every module script on purpose.
+  See CONSENT_STUB above: it exists so that code which loads before the gate can
+  tell "the gate isn't here yet" from "this site has no gate", and queue rather
+  than assume it may store. Keyed on `head.consent` (is the gate on?) rather than
+  `head.consentRuntime` (does anything need scheduling?) — a site whose only tag
+  is cookieless loads the runtime to schedule it but gates nothing, so there is
+  nothing for a caller to queue behind.
+*/}
+{head.consent && <script is:inline set:html={CONSENT_STUB} />}
+
 {webComponents && (
   <>
     {/*
       Apply the remembered colour scheme before first paint.
 
-      `<color-scheme-toggle>` persists the choice to localStorage, but it loads
+      `<wc-color-scheme-toggle>` persists the choice to localStorage, but it loads
       as a deferred module — so without this every navigation would paint the
       light token set and flip to dark once the element upgraded. Synchronous and
       inline on purpose: it has to run before the body renders.

package/src/components/Tracking.astro

@@ -0,0 +1,43 @@
+---
+/**
+ * <Tracking /> — ad-click attribution capture. Place in your layout's <head>;
+ * requires the vitops() integration, which supplies `virtual:getvitops/head`.
+ *
+ * A dumb renderer over `resolveTracking()` (src/tracking.ts) — the one decision,
+ * which consent category `_ac` waits on, lives there and is unit-tested.
+ *
+ * Two things it emits, and the marker is the interesting one:
+ *
+ *  - **The marker** carries `data-consent` (which category) and
+ *    `data-consent-cookies` (what to clear). It deliberately does *not* carry
+ *    `data-vitops-tag`, so the consent runtime's `scan()` never tries to activate
+ *    it — this script is ungated by design, because reading the query string is
+ *    not storage and the click ID is only in the URL on the landing page. But
+ *    `clearCookies()` queries `[data-consent="<category>"]` and reads
+ *    `data-consent-cookies` off whatever it finds, so revoking consent clears
+ *    `_ac`. That cleanup did not exist before.
+ *  - **The script**, which captures synchronously and then waits on consent for
+ *    the *write* only. See src/scripts/tracking.ts.
+ *
+ * `<meta>` rather than a `<span>` so it is valid in `<head>`, where this
+ * component belongs — the capture wants to run before the visitor can navigate.
+ */
+// @ts-ignore — virtual module provided by the vitops() integration at build time
+import head from 'virtual:getvitops/head';
+
+const { enabled, category, cookies } = head.tracking ?? { enabled: false };
+---
+
+{enabled && (
+  <>
+    <meta
+      name="vitops-tracking"
+      data-vitops-tracking
+      data-consent={category}
+      data-consent-cookies={cookies?.length ? cookies.join(',') : undefined}
+    />
+    <script>
+      import '../scripts/tracking.ts';
+    </script>
+  </>
+)}

package/src/components/Tree.astro

@@ -0,0 +1,82 @@
+---
+/**
+ * An accessible disclosure tree, progressively enhanced.
+ *
+ * Tier-3 in the framework's terms — an authoring convenience that emits the right
+ * `.tree` markup and requires **no runtime JS**. What it renders is the whole
+ * content, and it stands on its own:
+ *
+ *   - structure is real `<ul>`/`<li>` nesting, so assistive tech announces list
+ *     position and depth. A `<div>` soup looks identical and tells a screen-reader
+ *     user nothing about where they are;
+ *   - every branch is a native `<details>`/`<summary>`, so expanded state and
+ *     keyboard operation come from the platform. No `role="tree"`, no
+ *     `aria-expanded` bookkeeping — a hand-rolled ARIA tree that loses its JS is
+ *     worse than no ARIA at all;
+ *   - nodes carry ids, so any node is linkable without JS.
+ *
+ * **This component emits its own `<wc-tree>`** — do NOT wrap it in one. That is the
+ * tier-3 rule ("the wrapper emits its `<wc-*>` tag with the accessible fallback
+ * inside"), and `CookieConsent.astro` does the same with `<wc-consent>`.
+ * `<wc-tree><Tree /></wc-tree>` nests two elements binding the same tree; the
+ * element now defers to an enclosing one, so it degrades to a no-op rather than two
+ * duelling toolbars, but the single call is the intended shape.
+ *
+ * `<wc-tree>` upgrades it with filter, expand/collapse-all and deep-linking. If
+ * that never loads, only those three conveniences are missing — which is why
+ * `enhance={false}` is a supported way to get the bare fragment.
+ */
+import type { TreeItem } from './tree.ts';
+import TreeNode from './TreeNode.astro';
+
+interface Props {
+  items: TreeItem[];
+  /** Placeholder + aria-label for the filter `<wc-tree>` generates. */
+  label?: string;
+  /** Accessible name for the list itself. */
+  ariaLabel?: string;
+  /** Branches shallower than this render open. 0 = everything closed. */
+  openDepth?: number;
+  /**
+   * Emit the `<wc-tree>` wrapper (default `true`).
+   *
+   * Set false when the fragment is going somewhere the element cannot run or is
+   * unwanted — an email, a PDF, a server-rendered block on a page that doesn't load
+   * `elements.js`. The tree itself is unchanged; only the enhancement layer is
+   * omitted, so nothing is lost but filter/expand-all/deep-link.
+   */
+  enhance?: boolean;
+}
+const {
+  items,
+  label = 'Filter',
+  ariaLabel,
+  openDepth = 0,
+  enhance = true,
+  // Anything else is passed through to `<wc-tree>`, so the element can grow
+  // attributes without this component's prop surface tracking them.
+  ...rest
+} = Astro.props;
+---
+
+{/* One `<ul>`, rendered once, wrapped or not — duplicating the tree markup per
+    branch is how the two paths would drift. */}
+<Fragment>
+  {
+    enhance ? (
+      <wc-tree label={label} {...rest}>
+        <ul class="tree tree--lines" aria-label={ariaLabel}>
+          {items.map((item) => (
+            <TreeNode item={item} depth={0} openDepth={openDepth} />
+          ))}
+        </ul>
+      </wc-tree>
+    ) : (
+      <ul class="tree tree--lines" aria-label={ariaLabel}>
+        {items.map((item) => (
+          <TreeNode item={item} depth={0} openDepth={openDepth} />
+        ))}
+      </ul>
+    )
+  }
+</Fragment>

package/src/components/TreeNode.astro

@@ -0,0 +1,63 @@
+---
+/**
+ * One node of a `<Tree />`, recursing through `Astro.self`.
+ *
+ * Two shapes, and the choice is semantic rather than cosmetic:
+ *
+ *   - a **branch** wraps its label in `<details>`/`<summary>` — a native
+ *     disclosure button, so expanded state is announced and keyboard operation
+ *     is free. The child `<ul>` lives inside the `<details>`, which is what makes
+ *     it collapse with no JS.
+ *   - a **leaf** is a plain `.tree__content` row. A `<details>` with nothing to
+ *     disclose would still render a control and announce as collapsible.
+ *
+ * The item class sits on the `<li>` in both cases, so `<wc-tree>`'s filter treats
+ * leaves and branches as one kind of thing and hiding one hides its whole row.
+ */
+import type { TreeItem } from './tree.ts';
+
+interface Props {
+  item: TreeItem;
+  depth: number;
+  /** Branches at a depth below this render open. */
+  openDepth: number;
+}
+const { item, depth, openDepth } = Astro.props;
+
+const kids = item.children ?? [];
+const isBranch = kids.length > 0;
+---
+
+<li class="tree__item" id={item.id}>
+  {
+    isBranch ? (
+      <details open={depth < openDepth}>
+        <summary>
+          <span class="tree__toggle" aria-hidden="true" />
+          <span class="tree__label">
+            {item.unnamed ? <em>{item.label}</em> : <code>{item.label}</code>}
+            {item.badge && <span class="badge">{item.badge}</span>}
+            {item.flag && <span class="badge badge-danger">{item.flag}</span>}
+          </span>
+        </summary>
+        {item.descriptionHtml && <p class="tree__desc" set:html={item.descriptionHtml} />}
+        <ul class="tree">
+          {kids.map((kid) => (
+            <Astro.self item={kid} depth={depth + 1} openDepth={openDepth} />
+          ))}
+        </ul>
+      </details>
+    ) : (
+      <Fragment>
+        <span class="tree__content">
+          <span class="tree__label">
+            {item.unnamed ? <em>{item.label}</em> : <code>{item.label}</code>}
+            {item.badge && <span class="badge">{item.badge}</span>}
+            {item.flag && <span class="badge badge-danger">{item.flag}</span>}
+          </span>
+        </span>
+        {item.descriptionHtml && <p class="tree__desc" set:html={item.descriptionHtml} />}
+      </Fragment>
+    )
+  }
+</li>

package/src/components/WebComponentLoader.astro

@@ -6,7 +6,7 @@
  *
  * @example
  * <WebComponentLoader src="WCColorSchemeToggle" />
- * <color-scheme-toggle></color-scheme-toggle>
+ * <wc-color-scheme-toggle></wc-color-scheme-toggle>
  */
 interface Props {
   src: string;

package/src/components/tree.ts

@@ -0,0 +1,19 @@
+/** One node of a `<Tree />`. See `Tree.astro` for the rendering contract. */
+export interface TreeItem {
+  label: string;
+  /** Small type/meta chip after the label. */
+  badge?: string;
+  /**
+   * Rendered with `set:html`, so it MUST already be escaped. For schema text use
+   * the generator's `renderInlineMarkdown()` — one tested escaper beats each
+   * caller doing its own, which is how one of them eventually doesn't.
+   */
+  descriptionHtml?: string;
+  /** Extra chip, e.g. "required". */
+  flag?: string;
+  /** Anchor id, so the node is linkable with no JS. */
+  id?: string;
+  /** An unnamed group (a union branch) — label renders as emphasis, not code. */
+  unnamed?: boolean;
+  children?: TreeItem[];
+}