@getvitops/astro 2.1.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": "2.1.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": [
@@ -19,9 +19,17 @@
     "src/components/Popover.astro",
     "src/components/Details.astro",
     "src/components/Drawer.astro",
+    "src/components/NavShell.astro",
+    "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",
@@ -30,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",
@@ -42,6 +55,10 @@
     "./components/Popover.astro": "./src/components/Popover.astro",
     "./components/Details.astro": "./src/components/Details.astro",
     "./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"
   },
@@ -49,10 +66,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@getvitops/core": "2.1.0",
-    "@getvitops/generator": "2.1.0",
-    "@getvitops/utils": "2.1.0",
-    "@getvitops/vite": "2.1.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/analytics.ts

@@ -136,7 +136,7 @@ export interface ResolvedAnalytics {
 }
 
 export interface ResolveAnalyticsContext {
-  /** Is the consent gate enabled on this site (`getvitops({ consent })`)? */
+  /** Is the consent gate enabled on this site (`vitops({ consent })`)? */
   consent?: boolean;
 }
 

package/src/components/Analytics.astro

@@ -1,7 +1,7 @@
 ---
 /**
  * <Analytics /> — the site's analytics tags, off the critical path and behind the
- * consent gate. Place in your layout's <head>; requires the getvitops()
+ * consent gate. Place in your layout's <head>; requires the vitops()
  * integration, which supplies `virtual:getvitops/head`.
  *
  * A dumb renderer over `resolveAnalytics()` (src/analytics.ts) — every decision
@@ -19,7 +19,7 @@
  * the critical-path cost the `idle` strategy exists to avoid.
  */
 import { type AnalyticsStrategy, resolveAnalytics } from '../analytics.ts';
-// @ts-ignore — virtual module provided by the getvitops() integration at build time
+// @ts-ignore — virtual module provided by the vitops() integration at build time
 import head from 'virtual:getvitops/head';
 
 interface Props {

package/src/components/CookieConsent.astro

@@ -1,7 +1,7 @@
 ---
 /**
  * <CookieConsent /> — the consent banner. Place near the end of <body>; requires
- * the getvitops() integration with `consent` enabled, which is what loads
+ * the vitops() integration with `consent` enabled, which is what loads
  * `@getvitops/core/consent` (the gate + `<wc-consent>`).
  *
  * This renders the *fallback*: a real, semantic form with real buttons. The
@@ -14,13 +14,20 @@
  * 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
  * this banner offers therefore comes from the integration, not from
  * `<Analytics />`.
  */
-// @ts-ignore — virtual module provided by the getvitops() integration at build time
+// @ts-ignore — virtual module provided by the vitops() integration at build time
 import head from 'virtual:getvitops/head';
 import type { OptionalConsentCategory } from '../analytics.ts';
 
@@ -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/Details.astro

@@ -15,7 +15,7 @@ interface Props {
   /**
    * Map a semantic name onto a fully-qualified one before rendering.
    *
-   * @deprecated The `icons` option on `getvitops()` now does this centrally, so
+   * @deprecated The `icons` option on `vitops()` now does this centrally, so
    * the site's set is configured once instead of threaded through every call
    * site. Left in place because removing it would break consumers passing one;
    * when omitted, `<Icon />` resolves through the site config.

package/src/components/Drawer.astro

@@ -19,7 +19,7 @@ interface Props {
   /**
    * Map a semantic name onto a fully-qualified one before rendering.
    *
-   * @deprecated The `icons` option on `getvitops()` now does this centrally, so
+   * @deprecated The `icons` option on `vitops()` now does this centrally, so
    * the site's set is configured once instead of threaded through every call
    * site. Left in place because removing it would break consumers passing one;
    * when omitted, `<Icon />` resolves through the site config.

package/src/components/Head.astro

@@ -1,15 +1,15 @@
 ---
 /**
  * <Head /> — the Vitops design system's <head> contributions. Place inside your
- * layout's <head>. Requires the getvitops() integration (it provides the
+ * layout's <head>. Requires the vitops() integration (it provides the
  * `virtual:getvitops/head` config + copies the assets into public/).
  *
  * Renders: favicon + PWA manifest tags, the webfont <Font /> tags for families
- * declared via getvitops({ fonts }), and the web-component runtime scripts in
+ * declared via vitops({ fonts }), and the web-component runtime scripts in
  * canonical order/priority. It does NOT emit a stylesheet <link> — the CSS is
  * imported into Astro's graph by the integration and Astro emits that link.
  */
-// @ts-ignore — virtual module provided by the getvitops() integration at build time
+// @ts-ignore — virtual module provided by the vitops() integration at build time
 import head from 'virtual:getvitops/head';
 // @ts-ignore — `Font` is provided by Astro's Fonts API (astro >= 7)
 import { Font } from 'astro:assets';
@@ -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
@@ -61,7 +88,7 @@ const THEME_SCRIPT =
 {favicons && head.themeColor && <meta name="theme-color" content={head.themeColor} />}
 
 {/*
-  Webfonts declared via getvitops({ fonts }). Astro's `fonts:` config resolves and
+  Webfonts declared via vitops({ fonts }). Astro's `fonts:` config resolves and
   optimises the files; this component is what actually puts the @font-face on the page,
   so without it the config is inert and every --font-* token falls through to its
   fallback stack.
@@ -77,15 +104,26 @@ const THEME_SCRIPT =
   <Font cssVariable={f.cssVariable} preload={f.preload} />
 ))}
 
-{/* Set by getvitops({ sitemap }); null when no sitemap was registered. */}
+{/* 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.
@@ -112,7 +150,7 @@ const THEME_SCRIPT =
 {head.consentRuntime && <script is:inline type="module" src={`${wc}/consent.js`}></script>}
 
 {/*
-  The live theme editor — a separate, opt-in bundle (getvitops({ editor: true })).
+  The live theme editor — a separate, opt-in bundle (vitops({ editor: true })).
   It is tooling, not part of the runtime, so it stays out of elements.js and off
   every page that doesn't ask for it. Loads independently of `webComponents`:
   <wc-theme-editor> registers itself and pulls in no framework element.

package/src/components/Icon.astro

@@ -67,13 +67,13 @@ if (icons.engine === 'inline' && qualified) {
   svg = await loadIconSvg(qualified, { resolveFrom: icons.root });
   if (!svg)
     console.warn(
-      `[getvitops] <Icon name="${name}"> — "${qualified}" not found. Is ` +
+      `[vitops] <Icon name="${name}"> — "${qualified}" not found. Is ` +
         `@iconify-json/${qualified.slice(0, qualified.indexOf(':'))} installed?`,
     );
 } else if (icons.engine === 'none') {
   console.warn(
-    `[getvitops] <Icon name="${name}"> rendered but icons are not configured. ` +
-      'Add `icons: true` to getvitops() in astro.config.',
+    `[vitops] <Icon name="${name}"> rendered but icons are not configured. ` +
+      'Add `icons: true` to vitops() in astro.config.',
   );
 }
 

package/src/components/NavShell.astro

@@ -0,0 +1,123 @@
+---
+/**
+ * NavShell — a navigation aside beside main content at width, collapsing to a
+ * toggle + drawer below it. Markup only: every declaration lives in the
+ * framework's `navshell` pattern (patterns/navshell.css), which is emitted in
+ * all three output formats.
+ *
+ * It nests. A docs page is typically two of these — a site nav wrapping an
+ * on-this-page nav — promoting at different breakpoints:
+ *
+ *   <NavShell id="site-nav" label="Documentation" breakpoint="md">
+ *     <Fragment slot="nav">…</Fragment>
+ *     <main>
+ *       <NavShell id="page-toc" label="On this page" breakpoint="lg" side="end">
+ *         <Fragment slot="nav">…</Fragment>
+ *         …prose…
+ *       </NavShell>
+ *     </main>
+ *   </NavShell>
+ *
+ * Nothing here may reach for a Tailwind utility: Tailwind doesn't scan
+ * node_modules, so a class only it can emit is silently never generated — and
+ * classes in the generator's TW_CLASH list are stripped from the framework's own
+ * tailwind bundle by design. `navshell*` and `drawer*` are in neither list.
+ *
+ * No runtime JS: the toggle is `<button popovertarget>` against a `[popover]`
+ * panel, so it works from the first paint and degrades to a visible panel if the
+ * Popover API is missing.
+ */
+interface Props {
+  /**
+   * The panel's id, and the `popovertarget` the toggle points at.
+   *
+   * Required, never generated. It IS the toggle↔panel contract, and a generated
+   * id would make the one real hazard of nesting — two instances colliding on
+   * the same id, so the outer toggle opens the inner panel — invisible rather
+   * than impossible. Making the author name each instance makes a collision a
+   * thing you can see in the markup.
+   */
+  id: string;
+  /** Accessible name for the `<nav>`, e.g. "Documentation" / "On this page". */
+  label: string;
+  /** Container width at which the aside appears. Default `md` (48rem). */
+  breakpoint?: 'sm' | 'md' | 'lg' | 'xl';
+  /** Which side the aside sits on at width. Default `start`. */
+  side?: 'start' | 'end';
+  /**
+   * Aside column width once promoted, e.g. `'14rem'`. Defaults to the design
+   * system's `--width-nav` token rather than a literal, so a site retunes every
+   * nav column in one place.
+   */
+  size?: string;
+  /** Accessible name for the toggle. Defaults to `Open ${label}`. */
+  toggleLabel?: string;
+  /**
+   * Where the toggle lives. `'inline'` renders a `.navshell__bar` row above the
+   * content; `'external'` renders none, for when a `<NavShellToggle>` elsewhere
+   * (typically the site header) opens this shell instead.
+   *
+   * Two NESTED shells should not both be `'inline'`: their bars are sticky at
+   * the same offset and land on top of each other. Hoist the outer one.
+   */
+  toggle?: 'inline' | 'external';
+  class?: string;
+}
+
+const {
+  id,
+  label,
+  breakpoint = 'md',
+  side = 'start',
+  // Not a literal: the default REFERENCES the design system's token, so an
+  // unsized instance still tracks `--width-nav`. A literal here would shadow it
+  // on every instance and quietly make the token unreachable through this
+  // component, which is the only way most consumers will use the pattern.
+  size = 'var(--width-nav, 16rem)',
+  toggleLabel,
+  toggle = 'inline',
+  class: className,
+} = Astro.props;
+
+// Always emitted, even when the author passes no `size`. `--navshell-size`
+// inherits (it can't be registered as non-inheriting — a registered property's
+// initial-value must be computationally independent, and this one is in rem), so
+// without this an inner instance would silently adopt an outer instance's column
+// width. Writing it on every root severs the inheritance at each boundary.
+const style = `--navshell-size: ${size}`;
+
+// The drawer slides in from the side its aside will occupy, so the motion points
+// at where the panel is going to live.
+const edge = side === 'end' ? 'drawer--right' : 'drawer--left';
+---
+
+<div
+  class:list={['navshell', `navshell--bp-${breakpoint}`, side === 'end' && 'navshell--end', className]}
+  style={style}
+>
+  {toggle === 'inline' && (
+    <div class="navshell__bar">
+      <slot name="toggle">
+        <button class="navshell__toggle" popovertarget={id} aria-label={toggleLabel ?? `Open ${label}`}>
+          <slot name="toggle-label">{label}</slot>
+        </button>
+      </slot>
+    </div>
+  )}
+
+  <div id={id} popover class:list={['navshell__panel', 'drawer', edge]}>
+    <button
+      class="navshell__close"
+      popovertarget={id}
+      popovertargetaction="hide"
+      aria-label={`Close ${label}`}>&times;</button
+    >
+    <nav class="navshell__nav" aria-label={label}>
+      <slot name="nav" />
+    </nav>
+  </div>
+
+  <div class="navshell__main">
+    <slot />
+  </div>
+</div>

package/src/components/NavShellToggle.astro

@@ -0,0 +1,45 @@
+---
+/**
+ * NavShellToggle — a `<NavShell>` toggle rendered outside its shell, so it can
+ * sit in a site header or navbar rather than in a row of its own.
+ *
+ * Two nested shells both rendering their own sticky toggle row put those rows at
+ * the same offset, on top of each other. Hoisting the outer one into the header
+ * — which is already sticky — leaves a single in-flow bar and no conflict. It is
+ * also simply where a site menu button belongs.
+ *
+ *   <header class="navbar">
+ *     <a href="/">Brand</a>
+ *     <NavShellToggle for="site-nav" label="Menu" breakpoint="md" />
+ *   </header>
+ *   …
+ *   <NavShell id="site-nav" label="Documentation" breakpoint="md" toggle="external">
+ *
+ * `breakpoint` MUST match the shell's: outside `.navshell` the toggle cannot read
+ * the shell's internal "am I wide?" flag (a style query resolves against an
+ * ancestor container, and the header is not one), so it carries its own copy.
+ * Mismatch them and you get a toggle visible next to an expanded sidebar, or no
+ * way to open the nav at all.
+ *
+ * No runtime JS: `popovertarget` is an id reference, which works from anywhere in
+ * the document.
+ */
+interface Props {
+  /** The `id` of the `<NavShell>` this opens. */
+  for: string;
+  /** Visible text (and accessible name, unless `aria-label` is given). */
+  label: string;
+  /** Must match the shell's `breakpoint`. Default `md`. */
+  breakpoint?: 'sm' | 'md' | 'lg' | 'xl';
+  class?: string;
+}
+
+const { for: target, label, breakpoint = 'md', class: className } = Astro.props;
+---
+
+<button
+  class:list={['navshell-toggle', `navshell-toggle--bp-${breakpoint}`, className]}
+  popovertarget={target}
+>
+  <slot>{label}</slot>
+</button>