@decocms/start 0.19.0

package/src/hooks/SectionErrorFallback.tsx

@@ -0,0 +1,85 @@
+import { Component, type ErrorInfo, type ReactNode } from "react";
+
+interface ErrorBoundaryProps {
+  sectionKey: string;
+  fallback?: ReactNode;
+  children: ReactNode;
+}
+
+interface ErrorBoundaryState {
+  error: Error | null;
+}
+
+/**
+ * Per-section error boundary that prevents a single broken section
+ * from crashing the entire page.
+ *
+ * In development, shows the error message + stack trace.
+ * In production, renders a silent empty placeholder.
+ */
+export class SectionErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = { error: null };
+  }
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { error };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    console.error(`[CMS] Section "${this.props.sectionKey}" crashed:`, error, info.componentStack);
+  }
+
+  render() {
+    if (this.state.error) {
+      if (this.props.fallback) return this.props.fallback;
+      return (
+        <DefaultSectionErrorFallback error={this.state.error} sectionKey={this.props.sectionKey} />
+      );
+    }
+    return this.props.children;
+  }
+}
+
+function DefaultSectionErrorFallback({ error, sectionKey }: { error: Error; sectionKey: string }) {
+  const isDev = typeof process !== "undefined" && process.env.NODE_ENV === "development";
+
+  if (!isDev) {
+    return <div data-section-error={sectionKey} className="hidden" />;
+  }
+
+  return (
+    <div
+      data-section-error={sectionKey}
+      style={{
+        padding: "16px",
+        margin: "8px 0",
+        border: "2px solid #ef4444",
+        borderRadius: "8px",
+        background: "#fef2f2",
+        fontFamily: "monospace",
+        fontSize: "13px",
+      }}
+    >
+      <div style={{ fontWeight: "bold", color: "#dc2626", marginBottom: "8px" }}>
+        Section Error: {sectionKey}
+      </div>
+      <div style={{ color: "#991b1b" }}>{error.message}</div>
+      {error.stack && (
+        <pre
+          style={{
+            marginTop: "8px",
+            fontSize: "11px",
+            color: "#6b7280",
+            whiteSpace: "pre-wrap",
+            overflow: "auto",
+            maxHeight: "200px",
+          }}
+        >
+          {error.stack}
+        </pre>
+      )}
+    </div>
+  );
+}

package/src/hooks/index.ts

@@ -0,0 +1,8 @@
+export {
+  DecoPageRenderer,
+  SectionList,
+  SectionRenderer,
+} from "./DecoPageRenderer";
+export { isBelowFold, LazySection, type LazySectionProps } from "./LazySection";
+export { LiveControls } from "./LiveControls";
+export { SectionErrorBoundary } from "./SectionErrorFallback";

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./admin/index";
+export * from "./cms/index";
+export * from "./hooks/index";
+export * from "./middleware/index";
+export * from "./types/index";

package/src/matchers/builtins.ts

@@ -0,0 +1,184 @@
+/**
+ * Built-in matchers matching deco-cx/apps website/matchers/*.
+ *
+ * These augment the matchers already handled inline in resolve.ts
+ * (always, never, device, random, utm) with the additional matchers
+ * that deco supported: cookie, cron, host, pathname, queryString.
+ *
+ * Register these at startup:
+ *
+ * @example
+ * ```ts
+ * import { registerBuiltinMatchers } from "@decocms/start/matchers/builtins";
+ * registerBuiltinMatchers();
+ * ```
+ */
+
+import type { MatcherContext } from "../cms/resolve";
+import { registerMatcher } from "../cms/resolve";
+
+// -------------------------------------------------------------------------
+// Cookie matcher
+// -------------------------------------------------------------------------
+
+function cookieMatcher(rule: Record<string, unknown>, ctx: MatcherContext): boolean {
+  const name = rule.name as string | undefined;
+  const value = rule.value as string | undefined;
+  if (!name) return false;
+
+  const cookies = ctx.cookies ?? {};
+  const cookieValue = cookies[name];
+
+  if (cookieValue === undefined) return false;
+  if (value === undefined) return true;
+  return cookieValue === value;
+}
+
+// -------------------------------------------------------------------------
+// Cron matcher
+// -------------------------------------------------------------------------
+
+function cronMatcher(rule: Record<string, unknown>, _ctx: MatcherContext): boolean {
+  const start = rule.start as string | undefined;
+  const end = rule.end as string | undefined;
+
+  if (!start && !end) return true;
+
+  const now = Date.now();
+
+  if (start) {
+    const startTime = new Date(start).getTime();
+    if (isNaN(startTime) || now < startTime) return false;
+  }
+
+  if (end) {
+    const endTime = new Date(end).getTime();
+    if (isNaN(endTime) || now > endTime) return false;
+  }
+
+  return true;
+}
+
+// -------------------------------------------------------------------------
+// Host matcher
+// -------------------------------------------------------------------------
+
+function hostMatcher(rule: Record<string, unknown>, ctx: MatcherContext): boolean {
+  const hostToMatch = rule.host as string | undefined;
+  if (!hostToMatch) return false;
+
+  const currentUrl = ctx.url;
+  if (!currentUrl) return false;
+
+  try {
+    const url = new URL(currentUrl);
+    return url.hostname === hostToMatch || url.host === hostToMatch;
+  } catch {
+    return false;
+  }
+}
+
+// -------------------------------------------------------------------------
+// Pathname matcher
+// -------------------------------------------------------------------------
+
+const MAX_PATTERN_LENGTH = 500;
+const REDOS_HEURISTIC = /(\+|\*|\{[^}]*,\})\s*(\+|\*|\{[^}]*,\})/;
+
+function isSafePattern(pattern: string): boolean {
+  if (pattern.length > MAX_PATTERN_LENGTH) return false;
+  if (REDOS_HEURISTIC.test(pattern)) return false;
+  return true;
+}
+
+function pathnameMatcher(rule: Record<string, unknown>, ctx: MatcherContext): boolean {
+  const pattern = rule.pattern as string | undefined;
+  const includes = rule.includes as string[] | undefined;
+  const excludes = rule.excludes as string[] | undefined;
+
+  const path = ctx.path ?? "";
+
+  if (pattern) {
+    if (!isSafePattern(pattern)) {
+      console.warn(
+        `[pathnameMatcher] Rejected potentially unsafe pattern: ${pattern.slice(0, 80)}`,
+      );
+      return false;
+    }
+    try {
+      const regex = new RegExp(pattern);
+      if (!regex.test(path)) return false;
+    } catch {
+      return false;
+    }
+  }
+
+  if (includes && includes.length > 0) {
+    const matches = includes.some((inc) => {
+      if (inc.includes("*")) {
+        const prefix = inc.replace(/\*+$/, "");
+        return path.startsWith(prefix);
+      }
+      return path === inc;
+    });
+    if (!matches) return false;
+  }
+
+  if (excludes && excludes.length > 0) {
+    const excluded = excludes.some((exc) => {
+      if (exc.includes("*")) {
+        const prefix = exc.replace(/\*+$/, "");
+        return path.startsWith(prefix);
+      }
+      return path === exc;
+    });
+    if (excluded) return false;
+  }
+
+  return true;
+}
+
+// -------------------------------------------------------------------------
+// Query string matcher
+// -------------------------------------------------------------------------
+
+function queryStringMatcher(rule: Record<string, unknown>, ctx: MatcherContext): boolean {
+  const key = (rule.key ?? rule.param) as string | undefined;
+  const value = rule.value as string | undefined;
+
+  if (!key) return false;
+
+  const currentUrl = ctx.url;
+  if (!currentUrl) return false;
+
+  try {
+    const url = new URL(currentUrl);
+    const paramValue = url.searchParams.get(key);
+
+    if (paramValue === null) return false;
+    if (value === undefined) return true;
+    return paramValue === value;
+  } catch {
+    return false;
+  }
+}
+
+// -------------------------------------------------------------------------
+// Registration
+// -------------------------------------------------------------------------
+
+/**
+ * Register all built-in matchers with the CMS resolver.
+ *
+ * Call once during app setup (in setup.ts or similar).
+ * These cover the matchers from deco-cx/apps that weren't
+ * handled inline in resolve.ts.
+ */
+export function registerBuiltinMatchers(): void {
+  registerMatcher("website/matchers/cookie.ts", cookieMatcher);
+  registerMatcher("website/matchers/cron.ts", cronMatcher);
+  registerMatcher("website/matchers/date.ts", cronMatcher);
+  registerMatcher("website/matchers/host.ts", hostMatcher);
+  registerMatcher("website/matchers/pathname.ts", pathnameMatcher);
+  registerMatcher("website/matchers/queryString.ts", queryStringMatcher);
+}

package/src/matchers/posthog.ts

@@ -0,0 +1,154 @@
+/**
+ * PostHog feature flag matcher bridge.
+ *
+ * Bridges deco's CMS matcher interface (`evaluateMatcher`) to PostHog's
+ * feature flag system for experiment-grade A/B testing with sticky sessions.
+ *
+ * This module is designed to be used with `registerMatcher()` from the CMS.
+ * PostHog itself is NOT a dependency of `@decocms/start` — the storefront
+ * provides the PostHog client via `configurePostHogMatcher()`.
+ *
+ * @example
+ * ```ts
+ * // In your storefront setup.ts
+ * import { registerMatcher } from "@decocms/start/cms";
+ * import { createPostHogMatcher, configurePostHogMatcher } from "@decocms/start/matchers/posthog";
+ * import posthog from "posthog-js";
+ *
+ * configurePostHogMatcher({
+ *   isFeatureEnabled: (key) => posthog.isFeatureEnabled(key) ?? false,
+ *   getFeatureFlagVariant: (key) => posthog.getFeatureFlag(key),
+ * });
+ *
+ * registerMatcher("posthog/matchers/featureFlag.ts", createPostHogMatcher());
+ * ```
+ */
+
+import type { MatcherContext } from "../cms/resolve";
+
+export interface PostHogAdapter {
+  /**
+   * Evaluate a boolean feature flag.
+   * Should return `true` if the flag is enabled for the current user.
+   */
+  isFeatureEnabled: (flagKey: string) => boolean;
+  /**
+   * Get the variant key for a multivariate feature flag.
+   * Returns the variant string or `undefined`/`false` if not matched.
+   */
+  getFeatureFlagVariant?: (flagKey: string) => string | boolean | undefined;
+}
+
+let adapter: PostHogAdapter | null = null;
+
+/**
+ * Provide the PostHog client adapter. Must be called before
+ * any PostHog matchers are evaluated.
+ */
+export function configurePostHogMatcher(ph: PostHogAdapter) {
+  adapter = ph;
+}
+
+/**
+ * Creates a matcher function compatible with `registerMatcher()`.
+ *
+ * CMS rule shape (in the decofile JSON):
+ * ```json
+ * {
+ *   "__resolveType": "posthog/matchers/featureFlag.ts",
+ *   "flagKey": "my-experiment",
+ *   "variant": "treatment"
+ * }
+ * ```
+ *
+ * - If only `flagKey` is provided, matches when the flag is enabled (boolean).
+ * - If `variant` is also provided, matches when the flag's variant equals it.
+ */
+export function createPostHogMatcher() {
+  return (rule: Record<string, unknown>, _ctx: MatcherContext): boolean => {
+    if (!adapter) {
+      console.warn(
+        "[PostHog Matcher] No adapter configured. Call configurePostHogMatcher() first.",
+      );
+      return false;
+    }
+
+    const flagKey = rule.flagKey as string | undefined;
+    if (!flagKey) {
+      console.warn("[PostHog Matcher] Missing `flagKey` in matcher rule.");
+      return false;
+    }
+
+    const expectedVariant = rule.variant as string | undefined;
+
+    if (expectedVariant && adapter.getFeatureFlagVariant) {
+      const actual = adapter.getFeatureFlagVariant(flagKey);
+      return actual === expectedVariant;
+    }
+
+    return adapter.isFeatureEnabled(flagKey);
+  };
+}
+
+/**
+ * Server-side PostHog evaluation for SSR.
+ *
+ * Uses the PostHog Node SDK to evaluate flags server-side,
+ * ensuring the first render has the correct variant without a flash.
+ *
+ * @example
+ * ```ts
+ * import { PostHog } from "posthog-node";
+ * import { configurePostHogMatcher, createServerPostHogAdapter } from "@decocms/start/matchers/posthog";
+ *
+ * const phServer = new PostHog(process.env.POSTHOG_API_KEY);
+ *
+ * // In your middleware, per-request:
+ * const adapter = createServerPostHogAdapter(phServer, distinctId);
+ * configurePostHogMatcher(adapter);
+ * ```
+ */
+export function createServerPostHogAdapter(
+  client: {
+    isFeatureEnabled: (key: string, distinctId: string) => Promise<boolean> | boolean;
+    getFeatureFlag: (
+      key: string,
+      distinctId: string,
+    ) => Promise<string | boolean | undefined> | string | boolean | undefined;
+  },
+  distinctId: string,
+): PostHogAdapter {
+  const flagCache = new Map<string, boolean>();
+  const variantCache = new Map<string, string | boolean | undefined>();
+
+  return {
+    isFeatureEnabled(key: string): boolean {
+      if (flagCache.has(key)) return flagCache.get(key)!;
+
+      // Synchronous path — pre-warm the cache in middleware before resolution
+      const result = client.isFeatureEnabled(key, distinctId);
+      if (result instanceof Promise) {
+        console.warn(
+          "[PostHog] Async flag evaluation used synchronously. Pre-warm flags in middleware.",
+        );
+        return false;
+      }
+      flagCache.set(key, result);
+      return result;
+    },
+
+    getFeatureFlagVariant(key: string): string | boolean | undefined {
+      if (variantCache.has(key)) return variantCache.get(key);
+
+      const result = client.getFeatureFlag(key, distinctId);
+      if (result instanceof Promise) {
+        console.warn(
+          "[PostHog] Async variant evaluation used synchronously. Pre-warm flags in middleware.",
+        );
+        return undefined;
+      }
+      variantCache.set(key, result);
+      return result;
+    },
+  };
+}

package/src/middleware/decoState.ts

@@ -0,0 +1,55 @@
+/**
+ * Per-request Deco state that the middleware pipeline builds up
+ * and passes through the request lifecycle.
+ */
+import { createServerTimings, type ServerTimings } from "../sdk/serverTimings";
+import type { Flag } from "../types/index";
+
+export interface DecoState {
+  /** Site name / identifier. */
+  site: string;
+  /** Per-request Server-Timing tracker. */
+  timings: ServerTimings;
+  /** Active feature flags for this request. */
+  flags: Flag[];
+  /** Whether the request is from a deco admin origin. */
+  isAdmin: boolean;
+  /** Whether debug mode is enabled (via `?__d=true` or admin). */
+  debug: boolean;
+  /** Start time of the request (ms). */
+  startedAt: number;
+}
+
+export function buildDecoState(request: Request, site?: string): DecoState {
+  const url = new URL(request.url);
+  const origin = request.headers.get("origin") || request.headers.get("referer") || "";
+
+  const ADMIN_ORIGINS = [
+    "https://admin.deco.cx",
+    "https://v0-admin.deco.cx",
+    "https://play.deco.cx",
+    "https://admin-cx.deco.page",
+    "https://deco.chat",
+    "https://admin.decocms.com",
+    "https://decocms.com",
+  ];
+
+  const isAdmin =
+    origin.includes("localhost") ||
+    origin.includes("127.0.0.1") ||
+    ADMIN_ORIGINS.some((d) => origin.startsWith(d));
+
+  const debug = url.searchParams.has("__d") || isAdmin;
+
+  return {
+    site:
+      site ||
+      (typeof globalThis.process !== "undefined" ? globalThis.process.env?.DECO_SITE : undefined) ||
+      "storefront",
+    timings: createServerTimings(),
+    flags: [],
+    isAdmin,
+    debug,
+    startedAt: performance.now(),
+  };
+}

package/src/middleware/healthMetrics.ts

@@ -0,0 +1,131 @@
+/**
+ * Health metrics collection for request tracking and diagnostics.
+ *
+ * Provides atomic counters for requests (total, inflight, errors)
+ * and a health endpoint with cache stats and uptime.
+ *
+ * @example
+ * ```ts
+ * import { trackRequest, getHealthMetrics, handleHealthCheck } from "@decocms/start/middleware/healthMetrics";
+ *
+ * // In middleware:
+ * trackRequest.start();
+ * const response = await next();
+ * trackRequest.end(response.status);
+ * ```
+ */
+
+import { getLoaderCacheStats } from "../sdk/cachedLoader";
+
+// ---------------------------------------------------------------------------
+// Counters
+// ---------------------------------------------------------------------------
+
+let totalRequests = 0;
+let inflightRequests = 0;
+let totalErrors = 0;
+const startedAt = Date.now();
+
+const statusCounts: Record<string, number> = {};
+
+export const trackRequest = {
+  start() {
+    totalRequests++;
+    inflightRequests++;
+  },
+
+  end(status: number) {
+    inflightRequests--;
+    const bucket = `${Math.floor(status / 100)}xx`;
+    statusCounts[bucket] = (statusCounts[bucket] || 0) + 1;
+    if (status >= 500) totalErrors++;
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Metrics access
+// ---------------------------------------------------------------------------
+
+export interface HealthMetrics {
+  uptime: number;
+  uptimeHuman: string;
+  requests: {
+    total: number;
+    inflight: number;
+    errors: number;
+    statusCodes: Record<string, number>;
+  };
+  cache: {
+    entries: number;
+    inflight: number;
+  };
+  memory?: {
+    rss: number;
+    heapUsed: number;
+    heapTotal: number;
+  };
+}
+
+function formatUptime(ms: number): string {
+  const seconds = Math.floor(ms / 1000);
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor((seconds % 3600) / 60);
+  const s = seconds % 60;
+  return `${h}h ${m}m ${s}s`;
+}
+
+export function getHealthMetrics(): HealthMetrics {
+  const uptime = Date.now() - startedAt;
+  const cacheStats = getLoaderCacheStats();
+
+  const metrics: HealthMetrics = {
+    uptime,
+    uptimeHuman: formatUptime(uptime),
+    requests: {
+      total: totalRequests,
+      inflight: inflightRequests,
+      errors: totalErrors,
+      statusCodes: { ...statusCounts },
+    },
+    cache: cacheStats,
+  };
+
+  // Memory info is only available in Node.js / Deno environments
+  if (typeof globalThis.process !== "undefined" && globalThis.process.memoryUsage) {
+    try {
+      const mem = globalThis.process.memoryUsage();
+      metrics.memory = {
+        rss: mem.rss,
+        heapUsed: mem.heapUsed,
+        heapTotal: mem.heapTotal,
+      };
+    } catch {
+      // not available in this runtime
+    }
+  }
+
+  return metrics;
+}
+
+// ---------------------------------------------------------------------------
+// Health check handler
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle `/deco/_health` requests with detailed metrics.
+ * Returns null for non-matching requests.
+ */
+export function handleHealthCheck(request: Request): Response | null {
+  const url = new URL(request.url);
+  if (url.pathname !== "/deco/_health") return null;
+
+  const metrics = getHealthMetrics();
+
+  return new Response(JSON.stringify(metrics, null, 2), {
+    status: 200,
+    headers: {
+      "Content-Type": "application/json",
+      "Cache-Control": "no-store",
+    },
+  });
+}

package/src/middleware/index.ts

@@ -0,0 +1,80 @@
+/**
+ * Deco middleware utilities for TanStack Start.
+ *
+ * These are NOT TanStack `createMiddleware()` instances because
+ * `@decocms/start` doesn't depend on `@tanstack/react-start`.
+ * Instead, they export composable handler functions that storefronts
+ * wire into their own `createMiddleware()` chain.
+ *
+ * @example
+ * ```ts
+ * // In your storefront's middleware.ts
+ * import { createMiddleware } from "@tanstack/react-start";
+ * import { buildDecoState, handleLiveness, applyServerTiming, applyCorsHeaders } from "@decocms/start/middleware";
+ *
+ * export const decoMiddleware = createMiddleware().server(async ({ request, next }) => {
+ *   const liveness = handleLiveness(request);
+ *   if (liveness) return { result: undefined, response: liveness };
+ *
+ *   const state = buildDecoState(request, "my-site");
+ *   const endTotal = state.timings.start("total");
+ *
+ *   const result = await next();
+ *
+ *   endTotal();
+ *   applyServerTiming(result.response, state);
+ *   if (state.isAdmin) applyCorsHeaders(result.response, request);
+ *
+ *   return result;
+ * });
+ * ```
+ */
+
+export { buildDecoState, type DecoState } from "./decoState";
+export {
+  getHealthMetrics,
+  type HealthMetrics,
+  handleHealthCheck,
+  trackRequest,
+} from "./healthMetrics";
+export { handleLiveness } from "./liveness";
+export {
+  configureMeter,
+  configureTracer,
+  getActiveSpan,
+  getMeter,
+  getTracer,
+  logRequest,
+  type MeterAdapter,
+  MetricNames,
+  recordCacheMetric,
+  recordRequestMetric,
+  type Span,
+  setSpanAttribute,
+  type TracerAdapter,
+  withTracing,
+} from "./observability";
+
+/**
+ * Appends Server-Timing header to a response from the accumulated timings.
+ */
+export function applyServerTiming(response: Response, state: { timings: { toHeader(): string } }) {
+  const header = state.timings.toHeader();
+  if (header) {
+    response.headers.append("Server-Timing", header);
+  }
+}
+
+/**
+ * Applies CORS headers for deco admin origins to a response.
+ */
+export function applyCorsHeaders(response: Response, request: Request) {
+  const origin = request.headers.get("origin") || "*";
+  response.headers.set("Access-Control-Allow-Origin", origin);
+  response.headers.set("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+  response.headers.set(
+    "Access-Control-Allow-Headers",
+    "Content-Type, Authorization, If-None-Match",
+  );
+  response.headers.set("Access-Control-Allow-Credentials", "true");
+}