@decocms/start 0.43.0 → 1.0.0

package/.github/workflows/release.yml

@@ -23,8 +23,6 @@ jobs:
           node-version: 22
           registry-url: https://registry.npmjs.org
 
-      - run: npm install -g npm@latest
-
       - run: npm install
 
       - name: Release

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "0.43.0",
+  "version": "1.0.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",
@@ -29,6 +29,7 @@
     "./sdk/instrumentedFetch": "./src/sdk/instrumentedFetch.ts",
     "./sdk/otel": "./src/sdk/otel.ts",
     "./sdk/workerEntry": "./src/sdk/workerEntry.ts",
+    "./sdk/abTesting": "./src/sdk/abTesting.ts",
     "./sdk/redirects": "./src/sdk/redirects.ts",
     "./sdk/sitemap": "./src/sdk/sitemap.ts",
     "./sdk/useDevice": "./src/sdk/useDevice.ts",
@@ -44,11 +45,13 @@
     "./sdk/mergeCacheControl": "./src/sdk/mergeCacheControl.ts",
     "./sdk/requestContext": "./src/sdk/requestContext.ts",
     "./sdk/createInvoke": "./src/sdk/createInvoke.ts",
+    "./sdk/router": "./src/sdk/router.ts",
     "./matchers/posthog": "./src/matchers/posthog.ts",
     "./apps/autoconfig": "./src/apps/autoconfig.ts",
     "./sdk/setupApps": "./src/sdk/setupApps.ts",
     "./matchers/builtins": "./src/matchers/builtins.ts",
     "./types/widgets": "./src/types/widgets.ts",
+    "./setup": "./src/setup.ts",
     "./routes": "./src/routes/index.ts",
     "./scripts/generate-blocks": "./scripts/generate-blocks.ts",
     "./scripts/generate-schema": "./scripts/generate-schema.ts",
@@ -90,6 +93,7 @@
   "peerDependencies": {
     "@microlabs/otel-cf-workers": ">=1.0.0-rc.0",
     "@opentelemetry/api": ">=1.9.0",
+    "@tanstack/react-query": ">=5.0.0",
     "@tanstack/react-start": ">=1.0.0",
     "@tanstack/store": ">=0.7.0",
     "react": "^19.0.0",
@@ -110,6 +114,7 @@
     "@opentelemetry/api": "^1.9.1",
     "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^10.0.1",
+    "@tanstack/react-query": "^5.96.0",
     "@tanstack/store": "^0.9.1",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",

package/scripts/generate-invoke.ts

@@ -173,10 +173,10 @@ for (const prop of actionsObj.getProperties()) {
   let inputType = "any";
   let callBody = "";
 
-  // Navigate through potential type assertion (as ...)
+  // Recursively unwrap AsExpression chains (e.g. `expr as unknown as Type`)
   let createInvokeFnCall = callExpr;
-  if (callExpr.getKind() === SyntaxKind.AsExpression) {
-    createInvokeFnCall = callExpr.asKindOrThrow(SyntaxKind.AsExpression).getExpression();
+  while (createInvokeFnCall.getKind() === SyntaxKind.AsExpression) {
+    createInvokeFnCall = createInvokeFnCall.asKindOrThrow(SyntaxKind.AsExpression).getExpression();
   }
 
   // Now we have createInvokeFn(...) call
@@ -215,15 +215,18 @@ for (const prop of actionsObj.getProperties()) {
     }
   }
 
-  // Extract the return type from the "as" assertion if present
+  // Extract the return type from the outermost "as" assertion.
+  // For `expr as unknown as (ctx: ...) => Promise<T>`, the outermost
+  // AsExpression has the function type with Promise<T>.
   let returnType = "any";
   if (callExpr.getKind() === SyntaxKind.AsExpression) {
     const asExpr = callExpr.asKindOrThrow(SyntaxKind.AsExpression);
     const typeText = asExpr.getTypeNode()?.getText() || "";
-    // Extract Promise<X> from (ctx: {...}) => Promise<X>
-    const promiseMatch = typeText.match(/Promise<(.+)>$/s);
-    if (promiseMatch) {
-      returnType = promiseMatch[1].trim();
+    if (typeText !== "unknown") {
+      const promiseMatch = typeText.match(/Promise<(.+)>$/s);
+      if (promiseMatch) {
+        returnType = promiseMatch[1].trim();
+      }
     }
   }
 
@@ -277,12 +280,25 @@ for (const action of actions) {
   }
 }
 
+// Count how many actually parsed vs. stubbed
+const parsed = actions.filter((a) => a.callBody && a.importedFn).length;
+const stubbed = actions.length - parsed;
+if (stubbed > 0) {
+  console.warn(`⚠ ${stubbed} action(s) could not be parsed — generated as stubs:`);
+  for (const a of actions) {
+    if (!a.callBody || !a.importedFn) console.warn(`  - ${a.name}`);
+  }
+}
+
 // Build output
 let out = `// Auto-generated by @decocms/start/scripts/generate-invoke.ts
 // Do not edit manually. Re-run the generator to update.
 //
 // Each server function is a top-level const so TanStack Start's compiler
 // can transform createServerFn().handler() into RPC stubs on the client.
+//
+// Site-specific extensions: import { vtexActions } from this file and merge
+// with your own actions in a separate invoke.ts.
 import { createServerFn } from "@tanstack/react-start";
 `;
 
@@ -318,56 +334,65 @@ for (const action of actions) {
   const varName = `$${action.name}`;
 
   if (action.callBody && action.importedFn) {
-    // Replace "input" references with "ctx.data" in the call body
+    // Replace "input" references with "data" in the call body.
+    // The handler receives `{ data }` destructured from the validated input.
     let body = action.callBody;
-    // The callBody looks like: functionName(input.foo, input.bar)
-    // We need it to be: functionName(ctx.data.foo, ctx.data.bar)
-    body = body.replace(/\binput\./g, "ctx.data.");
-    // Handle cases like functionName(input) without dot
-    body = body.replace(/\binput\b(?!\.)/g, "ctx.data");
+    body = body.replace(/\binput\./g, "data.");
+    body = body.replace(/\binput\b(?!\.)/g, "data");
 
     if (action.unwrap) {
       out += `\nconst ${varName} = createServerFn({ method: "POST" })
-  .handler(async (ctx: { data: ${action.inputType} }) => {
+  .inputValidator((data: ${action.inputType}) => data)
+  .handler(async ({ data }): Promise<any> => {
     const result = await ${body};
     return unwrapResult(result);
   });\n`;
     } else {
       out += `\nconst ${varName} = createServerFn({ method: "POST" })
-  .handler(async (ctx: { data: ${action.inputType} }) => {
-    return await ${body};
+  .inputValidator((data: ${action.inputType}) => data)
+  .handler(async ({ data }): Promise<any> => {
+    return ${body};
   });\n`;
     }
   } else {
     // Fallback: couldn't parse — generate a stub
     out += `\n// TODO: could not auto-generate ${action.name} — add manually\nconst ${varName} = createServerFn({ method: "POST" })
-  .handler(async (ctx: { data: any }) => {
+  .handler(async () => {
     throw new Error("${action.name}: not implemented — regenerate invoke");
   });\n`;
   }
 }
 
-// Generate the invoke object
+// Generate the vtexActions object (for composability with site-specific actions)
 out += `
 // ---------------------------------------------------------------------------
-// Public invoke object — same DX as @decocms/apps/vtex/invoke
+// Typed VTEX actions map — merge with site-specific actions in your invoke.ts
 // ---------------------------------------------------------------------------
 
-export const invoke = {
-  vtex: {
-    actions: {
+export const vtexActions = {
 `;
 
 for (const action of actions) {
   const varName = `$${action.name}`;
   if (action.returnType !== "any") {
-    out += `      ${action.name}: ${varName} as unknown as (ctx: { data: ${action.inputType} }) => Promise<${action.returnType}>,\n`;
+    out += `  ${action.name}: ${varName} as unknown as (ctx: { data: ${action.inputType} }) => Promise<${action.returnType}>,\n`;
   } else {
-    out += `      ${action.name}: ${varName},\n`;
+    out += `  ${action.name}: ${varName},\n`;
   }
 }
 
-out += `    },
+out += `} as const;
+
+// Re-export OrderForm type (commonly imported from invoke by site components)
+export type { OrderForm } from "@decocms/apps/vtex/types";
+
+// ---------------------------------------------------------------------------
+// Default invoke object — import this if you don't need site extensions
+// ---------------------------------------------------------------------------
+
+export const invoke = {
+  vtex: {
+    actions: vtexActions,
   },
 } as const;
 `;

package/src/hooks/DecoRootLayout.tsx

@@ -0,0 +1,111 @@
+import { useEffect, type ReactNode } from "react";
+import { HeadContent, Scripts, ScriptOnce } from "@tanstack/react-router";
+import { LiveControls } from "./LiveControls";
+import { ANALYTICS_SCRIPT } from "../sdk/analytics";
+import { NavigationProgress } from "./NavigationProgress";
+import { StableOutlet } from "./StableOutlet";
+
+declare global {
+	interface Window {
+		__deco_ready?: boolean;
+	}
+}
+
+function buildDecoEventsBootstrap(account?: string): string {
+	const accountJson = JSON.stringify(account ?? "");
+	return `
+window.__RUNTIME__ = window.__RUNTIME__ || { account: ${accountJson} };
+window.DECO = window.DECO || {};
+window.DECO.events = window.DECO.events || {
+  _q: [],
+  _subs: [],
+  dispatch: function(e) {
+    this._q.push(e);
+    for (var i = 0; i < this._subs.length; i++) {
+      try { this._subs[i](e); } catch(err) { console.error('[DECO.events]', err); }
+    }
+  },
+  subscribe: function(fn) {
+    this._subs.push(fn);
+    for (var i = 0; i < this._q.length; i++) {
+      try { fn(this._q[i]); } catch(err) {}
+    }
+  }
+};
+window.dataLayer = window.dataLayer || [];
+`;
+}
+
+export interface DecoRootLayoutProps {
+	/** Language attribute for the <html> tag. Default: "en" */
+	lang?: string;
+	/** DaisyUI data-theme attribute. Default: "light" */
+	dataTheme?: string;
+	/** Site name for LiveControls (admin iframe communication). Required. */
+	siteName: string;
+	/** Commerce platform account name for analytics bootstrap (e.g. VTEX account). */
+	account?: string;
+	/** CSS class for <body>. Default: "bg-base-200 text-base-content" */
+	bodyClassName?: string;
+	/** Delay in ms before firing deco:ready event. Default: 500 */
+	decoReadyDelay?: number;
+	/**
+	 * Extra content rendered inside <body> after the main outlet
+	 * (e.g. Toast, custom analytics components).
+	 */
+	children?: ReactNode;
+}
+
+/**
+ * Standard Deco root layout component for use in __root.tsx.
+ *
+ * Provides:
+ * - NavigationProgress (loading bar during SPA nav)
+ * - StableOutlet (height-preserved content area)
+ * - DECO.events bootstrap (via ScriptOnce — runs before hydration, once)
+ * - LiveControls for admin
+ * - Analytics script (via ScriptOnce)
+ * - deco:ready hydration signal
+ *
+ * QueryClientProvider should be configured via createDecoRouter's `Wrap` option
+ * (per TanStack docs — non-DOM providers go on the router, not in components).
+ *
+ * Sites that need full control should compose from the individual exported
+ * pieces (NavigationProgress, StableOutlet, etc.) instead.
+ */
+export function DecoRootLayout({
+	lang = "en",
+	dataTheme = "light",
+	siteName,
+	account,
+	bodyClassName = "bg-base-200 text-base-content",
+	decoReadyDelay = 500,
+	children,
+}: DecoRootLayoutProps) {
+	useEffect(() => {
+		const id = setTimeout(() => {
+			window.__deco_ready = true;
+			document.dispatchEvent(new Event("deco:ready"));
+		}, decoReadyDelay);
+		return () => clearTimeout(id);
+	}, [decoReadyDelay]);
+
+	return (
+		<html lang={lang} data-theme={dataTheme} suppressHydrationWarning>
+			<head>
+				<HeadContent />
+			</head>
+			<body className={bodyClassName} suppressHydrationWarning>
+				<ScriptOnce children={buildDecoEventsBootstrap(account)} />
+				<NavigationProgress />
+				<main>
+					<StableOutlet />
+				</main>
+				{children}
+				<LiveControls site={siteName} />
+				<ScriptOnce children={ANALYTICS_SCRIPT} />
+				<Scripts />
+			</body>
+		</html>
+	);
+}

package/src/hooks/NavigationProgress.tsx

@@ -0,0 +1,21 @@
+import { useRouterState } from "@tanstack/react-router";
+
+const PROGRESS_CSS = `
+@keyframes progressSlide { from { transform: translateX(-100%); } to { transform: translateX(100%); } }
+.nav-progress-bar { animation: progressSlide 1s ease-in-out infinite; }
+`;
+
+/**
+ * Top-of-page loading bar that appears during SPA navigation.
+ * Uses the router's isLoading state — no extra dependencies.
+ */
+export function NavigationProgress() {
+	const isLoading = useRouterState({ select: (s) => s.isLoading });
+	if (!isLoading) return null;
+	return (
+		<div className="fixed top-0 left-0 right-0 z-[9999] h-1 bg-brand-primary-500/20 overflow-hidden">
+			<style dangerouslySetInnerHTML={{ __html: PROGRESS_CSS }} />
+			<div className="nav-progress-bar h-full w-1/3 bg-brand-primary-500 rounded-full" />
+		</div>
+	);
+}

package/src/hooks/StableOutlet.tsx

@@ -0,0 +1,30 @@
+import { useEffect, useRef } from "react";
+import { Outlet, useRouterState } from "@tanstack/react-router";
+
+/**
+ * Preserves the content area height during SPA navigation so the
+ * footer doesn't jump up while the new page is loading.
+ */
+export function StableOutlet() {
+	const isLoading = useRouterState({ select: (s) => s.isLoading });
+	const ref = useRef<HTMLDivElement>(null);
+	const savedHeight = useRef<number | undefined>(undefined);
+
+	useEffect(() => {
+		if (isLoading && ref.current) {
+			savedHeight.current = ref.current.offsetHeight;
+		}
+		if (!isLoading) {
+			savedHeight.current = undefined;
+		}
+	}, [isLoading]);
+
+	return (
+		<div
+			ref={ref}
+			style={savedHeight.current ? { minHeight: savedHeight.current } : undefined}
+		>
+			<Outlet />
+		</div>
+	);
+}

package/src/hooks/index.ts

@@ -6,3 +6,6 @@ export {
 export { isBelowFold, LazySection, type LazySectionProps } from "./LazySection";
 export { LiveControls } from "./LiveControls";
 export { SectionErrorBoundary } from "./SectionErrorFallback";
+export { NavigationProgress } from "./NavigationProgress";
+export { StableOutlet } from "./StableOutlet";
+export { DecoRootLayout, type DecoRootLayoutProps } from "./DecoRootLayout";

package/src/sdk/abTesting.ts

@@ -0,0 +1,398 @@
+/**
+ * A/B Testing wrapper for Cloudflare Worker entries.
+ *
+ * Provides KV-driven traffic splitting between the current TanStack Start
+ * worker ("worker" bucket) and a fallback origin ("fallback" bucket, e.g.
+ * legacy Deco/Fresh site). Designed for migration-period A/B testing.
+ *
+ * Features:
+ * - FNV-1a IP hashing for stable, deterministic bucket assignment
+ * - Sticky bucketing via cookie ("bucket:timestamp" format)
+ * - Query param override for QA (?_deco_bucket=worker)
+ * - Circuit breaker: worker errors auto-fallback to legacy origin
+ * - Fallback proxy with hostname rewriting (Set-Cookie, Location, body)
+ * - Configurable bypass for paths that must always use the worker
+ *   (e.g. VTEX checkout proxy paths)
+ *
+ * @example
+ * ```ts
+ * import { createDecoWorkerEntry } from "@decocms/start/sdk/workerEntry";
+ * import { withABTesting } from "@decocms/start/sdk/abTesting";
+ *
+ * const decoWorker = createDecoWorkerEntry(serverEntry, { ... });
+ *
+ * export default withABTesting(decoWorker, {
+ *   kvBinding: "SITES_KV",
+ *   shouldBypassAB: (request, url) => isVtexPath(url.pathname),
+ * });
+ * ```
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface WorkerExecutionContext {
+	waitUntil(promise: Promise<unknown>): void;
+	passThroughOnException(): void;
+}
+
+export interface WorkerHandler {
+	fetch(
+		request: Request,
+		env: Record<string, unknown>,
+		ctx: WorkerExecutionContext,
+	): Promise<Response>;
+}
+
+interface KVNamespace {
+	get<T = string>(key: string, type: "json"): Promise<T | null>;
+	get(key: string, type?: "text"): Promise<string | null>;
+}
+
+/** KV value shape — same as the original cf-gateway config. */
+export interface SiteConfig {
+	workerName: string;
+	fallbackOrigin: string;
+	abTest?: { ratio: number };
+}
+
+export type Bucket = "worker" | "fallback";
+
+export interface ABTestConfig {
+	/** KV namespace binding name. @default "SITES_KV" */
+	kvBinding?: string;
+
+	/** Cookie name for bucket persistence. @default "_deco_bucket" */
+	cookieName?: string;
+
+	/** Cookie max-age in seconds. @default 86400 (1 day) */
+	cookieMaxAge?: number;
+
+	/** Auto-fallback to legacy on worker errors. @default true */
+	circuitBreaker?: boolean;
+
+	/**
+	 * Return `true` to bypass A/B for this request — always serve from
+	 * the worker regardless of bucket assignment.
+	 *
+	 * Useful for commerce backend paths (checkout, /api/*) that must
+	 * not be proxied through the fallback origin.
+	 */
+	shouldBypassAB?: (request: Request, url: URL) => boolean;
+
+	/**
+	 * Called before the A/B logic runs. Return a `Response` to short-circuit
+	 * (e.g. for CMS redirects), or `null` to continue with A/B.
+	 */
+	preHandler?: (
+		request: Request,
+		url: URL,
+	) => Response | Promise<Response | null> | null;
+}
+
+// ---------------------------------------------------------------------------
+// FNV-1a 32-bit — fast, good distribution for short strings like IPs.
+// Same hash used by the original cf-gateway.
+// ---------------------------------------------------------------------------
+
+function fnv1a(str: string): number {
+	let hash = 0x811c9dc5;
+	for (let i = 0; i < str.length; i++) {
+		hash ^= str.charCodeAt(i);
+		hash = Math.imul(hash, 0x01000193);
+	}
+	return Math.abs(hash);
+}
+
+// ---------------------------------------------------------------------------
+// Cookie helpers
+// ---------------------------------------------------------------------------
+
+function parseCookies(header: string): Record<string, string> {
+	return Object.fromEntries(
+		header.split(";").map((c) => {
+			const [k, ...v] = c.trim().split("=");
+			return [k, v.join("=")];
+		}),
+	);
+}
+
+/**
+ * Parse the bucket cookie value.
+ *
+ * New format: "worker:1711540800" (bucket + unix timestamp).
+ * Legacy format: "worker" or "fallback" (no timestamp — old 30d cookie).
+ */
+function parseBucketCookie(
+	raw: string | undefined,
+): { bucket: Bucket; ts: number } | null {
+	if (!raw) return null;
+
+	const colonIdx = raw.indexOf(":");
+	if (colonIdx > 0) {
+		const bucket = raw.slice(0, colonIdx);
+		const ts = parseInt(raw.slice(colonIdx + 1), 10);
+		if ((bucket === "worker" || bucket === "fallback") && !isNaN(ts)) {
+			return { bucket, ts };
+		}
+	}
+
+	if (raw === "worker" || raw === "fallback") {
+		return { bucket: raw, ts: 0 };
+	}
+
+	return null;
+}
+
+// ---------------------------------------------------------------------------
+// Public helpers (exported for custom composition)
+// ---------------------------------------------------------------------------
+
+/**
+ * Deterministically assign a bucket based on:
+ * 1. Query param override (?_deco_bucket=worker)
+ * 2. Existing cookie (stickiness)
+ * 3. IP hash against ratio threshold
+ */
+export function getStableBucket(
+	request: Request,
+	ratio: number,
+	url: URL,
+	cookieName: string = "_deco_bucket",
+): Bucket {
+	const override = url.searchParams.get(cookieName);
+	if (override === "worker" || override === "fallback") return override;
+
+	const cookies = parseCookies(request.headers.get("cookie") ?? "");
+	const parsed = parseBucketCookie(cookies[cookieName]);
+	if (parsed) return parsed.bucket;
+
+	if (ratio <= 0) return "fallback";
+	if (ratio >= 1) return "worker";
+
+	const ip =
+		request.headers.get("cf-connecting-ip") ?? Math.random().toString();
+	return fnv1a(ip) % 100 < ratio * 100 ? "worker" : "fallback";
+}
+
+/**
+ * Tag a response with the bucket assignment and refresh the sticky cookie
+ * if needed (missing, changed, or stale).
+ */
+export function tagBucket(
+	response: Response,
+	bucket: Bucket,
+	hostname: string,
+	request: Request,
+	cookieName: string = "_deco_bucket",
+	maxAge: number = 86400,
+): Response {
+	const res = new Response(response.body, response);
+	res.headers.set("x-deco-bucket", bucket);
+
+	const cookies = parseCookies(request.headers.get("cookie") ?? "");
+	const parsed = parseBucketCookie(cookies[cookieName]);
+	const now = Math.floor(Date.now() / 1000);
+
+	const needsSet =
+		!parsed || parsed.bucket !== bucket || now - parsed.ts > maxAge;
+
+	if (needsSet) {
+		res.headers.append(
+			"set-cookie",
+			`${cookieName}=${bucket}:${now}; Path=/; Max-Age=${maxAge}; Domain=${hostname}; SameSite=Lax`,
+		);
+	}
+
+	return res;
+}
+
+/**
+ * Proxy a request to the fallback origin with full hostname rewriting.
+ *
+ * Rewrites:
+ * 1. URL hostname → fallback origin
+ * 2. Set-Cookie Domain → real hostname
+ * 3. Body text: fallback hostname → real hostname (for Fresh partial URLs)
+ * 4. Location header → real hostname
+ */
+export async function proxyToFallback(
+	request: Request,
+	url: URL,
+	fallbackOrigin: string,
+): Promise<Response> {
+	const target = new URL(url.toString());
+	target.hostname = fallbackOrigin;
+
+	const headers = new Headers(request.headers);
+	headers.delete("host");
+	headers.set("x-forwarded-host", url.hostname);
+
+	const init: RequestInit = {
+		method: request.method,
+		headers,
+	};
+	if (request.method !== "GET" && request.method !== "HEAD") {
+		init.body = request.body;
+		// @ts-expect-error -- needed for streaming body in Workers
+		init.duplex = "half";
+	}
+	const response = await fetch(target.toString(), init);
+
+	const ct = response.headers.get("content-type") ?? "";
+	const isText =
+		ct.includes("text/") || ct.includes("json") || ct.includes("javascript");
+
+	let body: BodyInit | null = response.body;
+	if (isText && response.body) {
+		const text = await response.text();
+		body = text.replaceAll(fallbackOrigin, url.hostname);
+	}
+
+	const rewritten = new Response(body, response);
+
+	const setCookies = response.headers.getSetCookie?.() ?? [];
+	if (setCookies.length > 0) {
+		rewritten.headers.delete("set-cookie");
+		for (const cookie of setCookies) {
+			rewritten.headers.append(
+				"set-cookie",
+				cookie.replace(
+					new RegExp(
+						`Domain=\\.?${fallbackOrigin.replace(/\./g, "\\.")}`,
+						"gi",
+					),
+					`Domain=.${url.hostname}`,
+				),
+			);
+		}
+	}
+
+	const location = response.headers.get("location");
+	if (location?.includes(fallbackOrigin)) {
+		rewritten.headers.set(
+			"location",
+			location.replaceAll(fallbackOrigin, url.hostname),
+		);
+	}
+
+	return rewritten;
+}
+
+// ---------------------------------------------------------------------------
+// Main wrapper
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap a Deco worker entry with A/B testing support.
+ *
+ * Reads config from Cloudflare KV by hostname, assigns buckets,
+ * and proxies fallback traffic to the legacy origin.
+ *
+ * When no KV binding is available or no config exists for the hostname,
+ * all traffic goes directly to the inner handler (no A/B).
+ */
+export function withABTesting(
+	handler: WorkerHandler,
+	config: ABTestConfig = {},
+): WorkerHandler {
+	const {
+		kvBinding = "SITES_KV",
+		cookieName = "_deco_bucket",
+		cookieMaxAge = 86400,
+		circuitBreaker = true,
+		shouldBypassAB,
+		preHandler,
+	} = config;
+
+	return {
+		async fetch(
+			request: Request,
+			env: Record<string, unknown>,
+			ctx: WorkerExecutionContext,
+		): Promise<Response> {
+			const url = new URL(request.url);
+
+			// Pre-handler (e.g. CMS redirects) — runs before A/B
+			if (preHandler) {
+				const pre = await preHandler(request, url);
+				if (pre) return pre;
+			}
+
+			const kv = env[kvBinding] as KVNamespace | undefined;
+			if (!kv) {
+				return handler.fetch(request, env, ctx);
+			}
+
+			const siteConfig = await kv.get<SiteConfig>(url.hostname, "json");
+			if (!siteConfig?.fallbackOrigin) {
+				return handler.fetch(request, env, ctx);
+			}
+
+			// Bypass A/B for certain paths (e.g. checkout, API)
+			if (shouldBypassAB?.(request, url)) {
+				return handler.fetch(request, env, ctx);
+			}
+
+			const ratio = siteConfig.abTest?.ratio ?? 0;
+			const bucket = getStableBucket(request, ratio, url, cookieName);
+
+			try {
+				if (bucket === "fallback") {
+					const response = await proxyToFallback(
+						request,
+						url,
+						siteConfig.fallbackOrigin,
+					);
+					return tagBucket(
+						response,
+						bucket,
+						url.hostname,
+						request,
+						cookieName,
+						cookieMaxAge,
+					);
+				}
+
+				// Worker bucket
+				try {
+					const response = await handler.fetch(request, env, ctx);
+					return tagBucket(
+						response,
+						bucket,
+						url.hostname,
+						request,
+						cookieName,
+						cookieMaxAge,
+					);
+				} catch (err) {
+					if (!circuitBreaker) throw err;
+					console.error(
+						"[A/B] Worker error, circuit breaker → fallback:",
+						err,
+					);
+					const response = await proxyToFallback(
+						request,
+						url,
+						siteConfig.fallbackOrigin,
+					);
+					return tagBucket(
+						response,
+						"fallback",
+						url.hostname,
+						request,
+						cookieName,
+						cookieMaxAge,
+					);
+				}
+			} catch (err) {
+				console.error(
+					"[A/B] Fatal proxy error, passing through to handler:",
+					err,
+				);
+				return handler.fetch(request, env, ctx);
+			}
+		},
+	};
+}

package/src/sdk/router.ts

@@ -0,0 +1,92 @@
+/**
+ * Deco-flavored TanStack Router factory.
+ *
+ * Uses standard URLSearchParams serialization instead of TanStack's default
+ * JSON-based format. Required because VTEX (and most commerce platforms) uses
+ * filter URLs like `?filter.brand=Nike&filter.brand=Adidas` which must
+ * round-trip correctly through the router's search system.
+ */
+import { createRouter as createTanStackRouter } from "@tanstack/react-router";
+import type {
+	SearchSerializer,
+	SearchParser,
+	AnyRoute,
+	TrailingSlashOption,
+} from "@tanstack/react-router";
+
+export const decoParseSearch: SearchParser = (searchStr) => {
+	const str = searchStr.startsWith("?") ? searchStr.slice(1) : searchStr;
+	if (!str) return {};
+
+	const params = new URLSearchParams(str);
+	const result: Record<string, string | string[]> = {};
+
+	for (const key of new Set(params.keys())) {
+		const values = params.getAll(key);
+		result[key] = values.length === 1 ? values[0] : values;
+	}
+	return result;
+};
+
+export const decoStringifySearch: SearchSerializer = (search) => {
+	const params = new URLSearchParams();
+	for (const [key, value] of Object.entries(search)) {
+		if (value === undefined || value === null || value === "") continue;
+		if (Array.isArray(value)) {
+			for (const v of value) params.append(key, String(v));
+		} else {
+			params.append(key, String(value));
+		}
+	}
+	const str = params.toString();
+	return str ? `?${str}` : "";
+};
+
+export interface CreateDecoRouterOptions {
+	routeTree: AnyRoute;
+	scrollRestoration?: boolean;
+	defaultPreload?: "intent" | "viewport" | "render" | false;
+	trailingSlash?: TrailingSlashOption;
+	/**
+	 * Router context — passed to all route loaders/components via routeContext.
+	 * Commonly used for { queryClient } per TanStack Query integration docs.
+	 */
+	context?: Record<string, unknown>;
+	/**
+	 * Non-DOM provider component to wrap the entire router.
+	 * Per TanStack docs, only non-DOM-rendering components (providers) should
+	 * be used — anything else causes hydration errors.
+	 *
+	 * Example: QueryClientProvider wrapping
+	 *   Wrap: ({ children }) => <QueryClientProvider client={qc}>{children}</QueryClientProvider>
+	 */
+	Wrap?: (props: { children: any }) => any;
+}
+
+/**
+ * Create a TanStack Router with Deco defaults:
+ * - URLSearchParams-based search serialization (not JSON)
+ * - Scroll restoration enabled
+ * - Preload on intent
+ */
+export function createDecoRouter(options: CreateDecoRouterOptions) {
+	const {
+		routeTree,
+		scrollRestoration = true,
+		defaultPreload = "intent",
+		trailingSlash,
+		context,
+		Wrap,
+	} = options;
+
+	return createTanStackRouter({
+		routeTree,
+		scrollRestoration,
+		defaultPreload,
+		trailingSlash,
+		context: context as any,
+		Wrap,
+		parseSearch: decoParseSearch,
+		stringifySearch: decoStringifySearch,
+	});
+}

package/src/sdk/workerEntry.ts

@@ -257,6 +257,44 @@ export interface DecoWorkerEntryOptions {
    */
   cacheVersionEnv?: string | false;
 
+  /**
+   * Security headers appended to every SSR response (HTML pages).
+   * Pass `false` to disable entirely.
+   *
+   * Default headers: X-Content-Type-Options, X-Frame-Options, Referrer-Policy,
+   * Permissions-Policy, X-XSS-Protection, HSTS, Cross-Origin-Opener-Policy.
+   *
+   * Custom entries are merged with defaults (custom values take precedence).
+   *
+   * @default DEFAULT_SECURITY_HEADERS
+   */
+  securityHeaders?: Record<string, string> | false;
+
+  /**
+   * Content Security Policy directives (report-only by default).
+   * Pass an array of directive strings which are joined with "; ".
+   * Pass `false` to omit CSP entirely.
+   *
+   * @example
+   * ```ts
+   * csp: [
+   *   "default-src 'self'",
+   *   "script-src 'self' 'unsafe-inline' https://www.googletagmanager.com",
+   *   "img-src 'self' data: https:",
+   * ]
+   * ```
+   */
+  csp?: string[] | false;
+
+  /**
+   * Automatically inject Cloudflare geo data (country, region, city)
+   * as internal cookies on every request so location matchers can read
+   * them from MatcherContext.cookies. The cookies are only visible
+   * within the Worker — they are never sent to the browser.
+   *
+   * @default true
+   */
+  autoInjectGeoCookies?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -327,6 +365,20 @@ export function injectGeoCookies(request: Request): Request {
 
 const ONE_YEAR = 31536000;
 
+/**
+ * Sensible security headers for any production storefront.
+ * CSP is intentionally not included — it's site-specific (third-party script domains).
+ */
+export const DEFAULT_SECURITY_HEADERS: Record<string, string> = {
+  "X-Content-Type-Options": "nosniff",
+  "X-Frame-Options": "SAMEORIGIN",
+  "Referrer-Policy": "strict-origin-when-cross-origin",
+  "Permissions-Policy": "camera=(), microphone=(), geolocation=()",
+  "X-XSS-Protection": "1; mode=block",
+  "Strict-Transport-Security": "max-age=63072000; includeSubDomains; preload",
+  "Cross-Origin-Opener-Policy": "same-origin-allow-popups",
+};
+
 const DEFAULT_BYPASS_PATHS = ["/_server", "/_build", "/deco/", "/live/", "/.decofile"];
 
 const FINGERPRINTED_ASSET_RE = /(?:\/_build)?\/assets\/.*-[a-zA-Z0-9_-]{8,}\.\w+$/;
@@ -366,8 +418,35 @@ export function createDecoWorkerEntry(
     stripTrackingParams: shouldStripTracking = true,
     previewShell: customPreviewShell,
     cacheVersionEnv = "BUILD_HASH",
+    securityHeaders: securityHeadersOpt,
+    csp: cspOpt,
+    autoInjectGeoCookies: geoOpt = true,
   } = options;
 
+  // Build the final security headers map (merged defaults + custom + CSP)
+  const secHeaders: Record<string, string> | null = (() => {
+    if (securityHeadersOpt === false) return null;
+    const base = { ...DEFAULT_SECURITY_HEADERS };
+    if (securityHeadersOpt) {
+      for (const [k, v] of Object.entries(securityHeadersOpt)) base[k] = v;
+    }
+    if (cspOpt && cspOpt.length > 0) {
+      base["Content-Security-Policy-Report-Only"] = cspOpt.join("; ");
+    }
+    return base;
+  })();
+
+  function applySecurityHeaders(resp: Response): Response {
+    if (!secHeaders) return resp;
+    const ct = resp.headers.get("content-type") ?? "";
+    if (!ct.includes("text/html")) return resp;
+    const out = new Response(resp.body, resp);
+    for (const [k, v] of Object.entries(secHeaders)) {
+      if (!out.headers.has(k)) out.headers.set(k, v);
+    }
+    return out;
+  }
+
   const allBypassPaths = [...(bypassPaths ?? DEFAULT_BYPASS_PATHS), ...extraBypassPaths];
 
   // -- Helpers ----------------------------------------------------------------
@@ -659,10 +738,15 @@ export function createDecoWorkerEntry(
       env: Record<string, unknown>,
       ctx: WorkerExecutionContext,
     ): Promise<Response> {
+      // Inject CF geo data as cookies for location matchers (before anything reads cookies)
+      if (geoOpt) {
+        request = injectGeoCookies(request);
+      }
+
       // Wrap the entire request in a RequestContext so that all code
       // in the call stack (loaders, invoke handlers, vtexFetchWithCookies)
       // can access the request and write response headers.
-      return RequestContext.run(request, async () => {
+      const response = await RequestContext.run(request, async () => {
       // Run app middleware (injects app state into RequestContext.bag,
       // runs registered middleware like VTEX cookie forwarding).
       const appMw = getAppMiddleware();
@@ -671,6 +755,8 @@ export function createDecoWorkerEntry(
       }
       return handleRequest(request, env, ctx);
       });
+
+      return applySecurityHeaders(response);
     },
   };
 

package/src/setup.ts

@@ -0,0 +1,192 @@
+/**
+ * One-call site bootstrap that composes framework registration functions.
+ *
+ * Sites pass their Vite-resolved globs, generated blocks, meta, CSS, fonts,
+ * and optional platform hooks. createSiteSetup wires them into the CMS engine,
+ * admin protocol, matchers, and rendering infrastructure.
+ *
+ * Everything site-specific (section loaders, cacheable sections, async rendering,
+ * layout sections, commerce loaders, sync sections) remains in the site's own
+ * setup file — createSiteSetup only handles the framework-generic wiring.
+ */
+
+import {
+	loadBlocks,
+	onBeforeResolve,
+	registerSections,
+	setBlocks,
+	setDanglingReferenceHandler,
+	setResolveErrorHandler,
+} from "./cms/index";
+import { registerBuiltinMatchers } from "./matchers/builtins";
+import { registerProductionOrigins } from "./sdk/normalizeUrls";
+import {
+	setInvokeLoaders,
+	setMetaData,
+	setPreviewWrapper,
+	setRenderShell,
+} from "./admin/index";
+
+export interface SiteSetupOptions {
+	/**
+	 * Section glob from Vite — pass `import.meta.glob("./sections/**\/*.tsx")`.
+	 * Keys are transformed from `./sections/X.tsx` → `site/sections/X.tsx`.
+	 */
+	sections: Record<string, () => Promise<any>>;
+
+	/**
+	 * Generated blocks object — import and pass directly:
+	 * `import { blocks } from "./server/cms/blocks.gen";`
+	 */
+	blocks: Record<string, unknown>;
+
+	/**
+	 * Lazy loader for admin meta schema — only fetched when admin requests it:
+	 * `() => import("./server/admin/meta.gen.json").then(m => m.default)`
+	 */
+	meta: () => Promise<any>;
+
+	/** CSS file URL from Vite `?url` import. */
+	css: string;
+
+	/** Font URLs to preload in admin preview shell. */
+	fonts?: string[];
+
+	/** Production origins for URL normalization. */
+	productionOrigins?: string[];
+
+	/**
+	 * Custom matcher registrations to run alongside builtins.
+	 * Each function is called once during setup.
+	 */
+	customMatchers?: Array<() => void>;
+
+	/** Preview wrapper component for admin preview iframe. */
+	previewWrapper?: React.ComponentType<any>;
+
+	/** Error handler for CMS resolution errors. */
+	onResolveError?: (
+		error: unknown,
+		resolveType: string,
+		context: string,
+	) => void;
+
+	/** Handler for dangling CMS references (missing __resolveType targets). */
+	onDanglingReference?: (resolveType: string) => any;
+
+	/**
+	 * Called after blocks are loaded — use for platform initialization.
+	 * Also called on every onBeforeResolve (decofile hot-reload).
+	 *
+	 * @example
+	 * ```ts
+	 * import { initVtexFromBlocks } from "@decocms/apps/vtex";
+	 * { initPlatform: (blocks) => initVtexFromBlocks(blocks) }
+	 * ```
+	 */
+	initPlatform?: (blocks: any) => void;
+
+	/**
+	 * Commerce loaders getter — passed to `setInvokeLoaders`.
+	 * Use a thunk so the full map (including site-specific loaders
+	 * defined after createSiteSetup) is captured.
+	 *
+	 * @example
+	 * ```ts
+	 * { getCommerceLoaders: () => COMMERCE_LOADERS }
+	 * ```
+	 */
+	getCommerceLoaders?: () => Record<string, (props: any) => Promise<any>>;
+}
+
+/**
+ * Bootstrap a Deco site — registers sections, matchers, blocks, meta,
+ * render shell, preview wrapper, error handlers, and platform hooks.
+ *
+ * Call once at the top of your `setup.ts`, before site-specific registrations.
+ *
+ * @example
+ * ```ts
+ * import "./cache-config";
+ * import { createSiteSetup } from "@decocms/start/setup";
+ * import { blocks } from "./server/cms/blocks.gen";
+ * import PreviewProviders from "./components/PreviewProviders";
+ * import appCss from "./styles/app.css?url";
+ * import { initVtexFromBlocks } from "@decocms/apps/vtex";
+ *
+ * createSiteSetup({
+ *   sections: import.meta.glob("./sections/**\/*.tsx"),
+ *   blocks,
+ *   meta: () => import("./server/admin/meta.gen.json").then(m => m.default),
+ *   css: appCss,
+ *   fonts: ["/fonts/Lato-Regular.woff2", "/fonts/Lato-Bold.woff2"],
+ *   productionOrigins: ["https://www.example.com"],
+ *   previewWrapper: PreviewProviders,
+ *   initPlatform: (blocks) => initVtexFromBlocks(blocks),
+ * });
+ * ```
+ */
+export function createSiteSetup(options: SiteSetupOptions): void {
+	// 1. Error handlers (set first so they catch issues during registration)
+	if (options.onResolveError) {
+		setResolveErrorHandler(options.onResolveError);
+	}
+	if (options.onDanglingReference) {
+		setDanglingReferenceHandler(options.onDanglingReference);
+	}
+
+	// 2. Section glob registration — transform Vite paths to CMS keys
+	const sections: Record<string, () => Promise<any>> = {};
+	for (const [path, loader] of Object.entries(options.sections)) {
+		sections[`site/${path.slice(2)}`] = loader;
+	}
+	registerSections(sections);
+
+	// 3. Matchers
+	registerBuiltinMatchers();
+	if (options.customMatchers) {
+		for (const register of options.customMatchers) {
+			register();
+		}
+	}
+
+	// 4. Production origins
+	if (options.productionOrigins?.length) {
+		registerProductionOrigins(options.productionOrigins);
+	}
+
+	// 5. Blocks + platform init (server-only)
+	if (typeof document === "undefined") {
+		setBlocks(options.blocks);
+		if (options.initPlatform) {
+			options.initPlatform(loadBlocks());
+		}
+	}
+
+	// 6. onBeforeResolve — re-init platform on decofile hot-reload
+	if (options.initPlatform) {
+		const init = options.initPlatform;
+		onBeforeResolve(() => {
+			init(loadBlocks());
+		});
+	}
+
+	// 7. Admin meta schema (lazy)
+	options.meta().then((data) => setMetaData(data));
+
+	// 8. Render shell
+	setRenderShell({
+		css: options.css,
+		fonts: options.fonts,
+	});
+
+	// 9. Preview wrapper
+	if (options.previewWrapper) {
+		setPreviewWrapper(options.previewWrapper);
+	}
+
+	// 10. Commerce loaders → invoke
+	if (options.getCommerceLoaders) {
+		setInvokeLoaders(options.getCommerceLoaders);
+	}
+}