@variantlab/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 variantlab contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+# @variantlab/react
+
+React hooks and components for variantlab.
+
+> **Status:** Phase 1 — Pre-alpha. Not ready for production use.
+
+## Peer dependencies
+
+- `react` `^18.2.0 || ^19.0.0`
+
+See the [root README](../../README.md) for project overview, motivation, and roadmap.

package/dist/index.cjs

@@ -0,0 +1,180 @@
+'use strict';
+
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/components/error-boundary.tsx
+var VariantLabContext = react.createContext(null);
+function VariantLabProvider({
+  engine,
+  initialContext,
+  children
+}) {
+  const value = react.useMemo(() => engine, [engine]);
+  const appliedRef = react.useRef(null);
+  react.useLayoutEffect(() => {
+    if (initialContext === void 0) return;
+    const prev = appliedRef.current;
+    if (prev !== null && prev.engine === engine && prev.ctx === initialContext) {
+      return;
+    }
+    engine.updateContext(initialContext);
+    appliedRef.current = { engine, ctx: initialContext };
+  }, [engine, initialContext]);
+  return /* @__PURE__ */ jsxRuntime.jsx(VariantLabContext.Provider, { value, children });
+}
+
+// src/components/error-boundary.tsx
+var VariantErrorBoundary = class extends react.Component {
+  constructor() {
+    super(...arguments);
+    this.state = { error: null };
+  }
+  static getDerivedStateFromError(error) {
+    return { error };
+  }
+  componentDidCatch(error, _info) {
+    const engine = this.context;
+    if (engine !== null) {
+      try {
+        engine.reportCrash(this.props.experimentId, error);
+      } catch {
+      }
+    }
+  }
+  componentDidUpdate(prevProps) {
+    if (this.state.error !== null && prevProps.children !== this.props.children) {
+      this.setState({ error: null });
+    }
+  }
+  render() {
+    const { error } = this.state;
+    if (error !== null) {
+      const { fallback } = this.props;
+      if (typeof fallback === "function") return fallback(error);
+      return fallback ?? null;
+    }
+    return this.props.children;
+  }
+};
+VariantErrorBoundary.contextType = VariantLabContext;
+function useVariantLabEngine() {
+  const engine = react.useContext(VariantLabContext);
+  if (engine === null) {
+    throw new Error("useVariantLabEngine: no <VariantLabProvider> found above this component.");
+  }
+  return engine;
+}
+
+// src/hooks/use-variant.ts
+function useVariant(experimentId) {
+  const engine = useVariantLabEngine();
+  const subscribe = react.useCallback(
+    (onStoreChange) => {
+      return engine.subscribe((event) => {
+        if (shouldNotify(event, experimentId)) onStoreChange();
+      });
+    },
+    [engine, experimentId]
+  );
+  const getSnapshot = react.useCallback(
+    () => engine.getVariant(experimentId),
+    [engine, experimentId]
+  );
+  return react.useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+function shouldNotify(event, experimentId) {
+  switch (event.type) {
+    case "configLoaded":
+    case "contextUpdated":
+      return true;
+    case "variantChanged":
+    case "rollback":
+    case "assignment":
+      return event.experimentId === experimentId;
+    default:
+      return false;
+  }
+}
+
+// src/components/variant.tsx
+function Variant({ experimentId, children, fallback }) {
+  const active = useVariant(experimentId);
+  const node = children[active];
+  if (node !== void 0) return node;
+  return fallback ?? null;
+}
+
+// src/hooks/use-variant-value.ts
+function useVariantValue(experimentId) {
+  const engine = useVariantLabEngine();
+  useVariant(experimentId);
+  return engine.getVariantValue(experimentId);
+}
+
+// src/components/variant-value.tsx
+function VariantValue({
+  experimentId,
+  children
+}) {
+  const value = useVariantValue(experimentId);
+  return children(value);
+}
+function useExperiment(experimentId) {
+  const engine = useVariantLabEngine();
+  const variant = useVariant(experimentId);
+  const value = engine.getVariantValue(experimentId);
+  const track = react.useCallback((_eventName, _properties) => {
+  }, []);
+  return { variant, value, track };
+}
+function useRouteExperiments(route) {
+  const engine = useVariantLabEngine();
+  const cacheRef = react.useRef(null);
+  const subscribe = react.useCallback(
+    (onStoreChange) => {
+      return engine.subscribe((event) => {
+        if (event.type === "configLoaded" || event.type === "contextUpdated") {
+          cacheRef.current = null;
+          onStoreChange();
+        }
+      });
+    },
+    [engine]
+  );
+  const getSnapshot = react.useCallback(() => {
+    const cached = cacheRef.current;
+    if (cached !== null && cached.route === route) return cached.snapshot;
+    const snapshot = engine.getExperiments(route);
+    cacheRef.current = { route, snapshot };
+    return snapshot;
+  }, [engine, route]);
+  return react.useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+function useSetVariant() {
+  const engine = useVariantLabEngine();
+  return react.useCallback(
+    (experimentId, variantId) => {
+      engine.setVariant(experimentId, variantId);
+    },
+    [engine]
+  );
+}
+
+// src/index.ts
+var VERSION = "0.0.0";
+
+exports.VERSION = VERSION;
+exports.Variant = Variant;
+exports.VariantErrorBoundary = VariantErrorBoundary;
+exports.VariantLabContext = VariantLabContext;
+exports.VariantLabProvider = VariantLabProvider;
+exports.VariantValue = VariantValue;
+exports.useExperiment = useExperiment;
+exports.useRouteExperiments = useRouteExperiments;
+exports.useSetVariant = useSetVariant;
+exports.useVariant = useVariant;
+exports.useVariantLabEngine = useVariantLabEngine;
+exports.useVariantValue = useVariantValue;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/context.tsx","../src/components/error-boundary.tsx","../src/hooks/use-variant-lab-engine.ts","../src/hooks/use-variant.ts","../src/components/variant.tsx","../src/hooks/use-variant-value.ts","../src/components/variant-value.tsx","../src/hooks/use-experiment.ts","../src/hooks/use-route-experiments.ts","../src/hooks/use-set-variant.ts","../src/index.ts"],"names":["createContext","useMemo","useRef","useLayoutEffect","jsx","Component","useContext","useCallback","useSyncExternalStore"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * React context and provider for variantlab.\n *\n * The provider is a thin wrapper that hands a pre-built `VariantEngine`\n * to descendants via React context. It intentionally does NOT own the\n * engine: callers construct it via `createEngine(...)` and pass it in.\n * That keeps the adapter testable (swap in a mock engine), SSR-safe\n * (server code can build an engine before render), and free of\n * lifecycle surprises — unmounting the provider never disposes the\n * engine because the provider didn't create it.\n *\n * `initialContext`, when supplied, is applied via `useLayoutEffect`\n * before the first browser paint. We use a ref to guard against\n * repeated application on re-renders so the engine cache is only\n * busted when the caller actually swaps engines.\n */\n\nimport type { VariantContext, VariantEngine } from \"@variantlab/core\";\nimport { createContext, type ReactNode, useLayoutEffect, useMemo, useRef } from \"react\";\n\n/** The raw context value. `null` until a provider wraps the tree. */\nexport const VariantLabContext = createContext<VariantEngine | null>(null);\n\nexport interface VariantLabProviderProps {\n  /** A pre-constructed engine from `createEngine(...)`. */\n  readonly engine: VariantEngine;\n  /** Optional runtime context applied once on mount. */\n  readonly initialContext?: VariantContext;\n  readonly children?: ReactNode;\n}\n\n/**\n * Wraps descendants so the hooks in this package can locate the engine.\n *\n * The value handed to `Context.Provider` is memoized on `engine` alone\n * so that unrelated parent re-renders don't force a new reference\n * (which would cascade through every `useVariant` consumer).\n */\nexport function VariantLabProvider({\n  engine,\n  initialContext,\n  children,\n}: VariantLabProviderProps): ReactNode {\n  // Stable context value: only changes when the engine itself changes.\n  const value = useMemo(() => engine, [engine]);\n\n  // Track which (engine, initialContext) pair we've already applied so\n  // re-renders don't re-invoke updateContext (which would clear the\n  // engine cache and cause unnecessary reassignment events).\n  const appliedRef = useRef<{\n    readonly engine: VariantEngine;\n    readonly ctx: VariantContext | undefined;\n  } | null>(null);\n\n  useLayoutEffect(() => {\n    if (initialContext === undefined) return;\n    const prev = appliedRef.current;\n    if (prev !== null && prev.engine === engine && prev.ctx === initialContext) {\n      return;\n    }\n    engine.updateContext(initialContext);\n    appliedRef.current = { engine, ctx: initialContext };\n  }, [engine, initialContext]);\n\n  return <VariantLabContext.Provider value={value}>{children}</VariantLabContext.Provider>;\n}\n","/**\n * `<VariantErrorBoundary>` — crash insulation for experiment render trees.\n *\n * Wraps a variant's subtree in a class-based error boundary (the only\n * remaining legitimate use of class components in modern React). When\n * a child throws, it:\n *\n *   1. reports the crash to the engine via `engine.reportCrash(id, err)`,\n *      which feeds the rollback counter defined in `config-format.md`;\n *   2. renders `fallback` (or `null`) for the rest of the current\n *      commit cycle;\n *   3. resets itself so the next render can try again with the new\n *      variant (likely the rolled-back default after N crashes).\n *\n * The engine lookup goes through `VariantLabContext` rather than a\n * prop so the ergonomics match the hook-first API. `contextType` on\n * the class makes the context value available as `this.context` in\n * `componentDidCatch`.\n */\n\nimport type { VariantEngine } from \"@variantlab/core\";\nimport { Component, type ErrorInfo, type ReactNode } from \"react\";\nimport { VariantLabContext } from \"../context.js\";\n\nexport interface VariantErrorBoundaryProps {\n  readonly experimentId: string;\n  readonly fallback?: ReactNode | ((error: Error) => ReactNode);\n  readonly children: ReactNode;\n}\n\ninterface VariantErrorBoundaryState {\n  readonly error: Error | null;\n}\n\nexport class VariantErrorBoundary extends Component<\n  VariantErrorBoundaryProps,\n  VariantErrorBoundaryState\n> {\n  static override contextType = VariantLabContext;\n  declare context: VariantEngine | null;\n  override state: VariantErrorBoundaryState = { error: null };\n\n  static getDerivedStateFromError(error: Error): VariantErrorBoundaryState {\n    return { error };\n  }\n\n  override componentDidCatch(error: Error, _info: ErrorInfo): void {\n    const engine = this.context;\n    if (engine !== null) {\n      try {\n        engine.reportCrash(this.props.experimentId, error);\n      } catch {\n        // Swallow crash-reporting failures — we must not double-throw\n        // inside an error boundary.\n      }\n    }\n  }\n\n  override componentDidUpdate(prevProps: VariantErrorBoundaryProps): void {\n    // If the children prop changes after a recovery (e.g. the engine\n    // rolled back and a parent re-rendered with a different subtree),\n    // clear the error so we attempt to render the new tree.\n    if (this.state.error !== null && prevProps.children !== this.props.children) {\n      this.setState({ error: null });\n    }\n  }\n\n  override render(): ReactNode {\n    const { error } = this.state;\n    if (error !== null) {\n      const { fallback } = this.props;\n      if (typeof fallback === \"function\") return fallback(error);\n      return fallback ?? null;\n    }\n    return this.props.children;\n  }\n}\n","/**\n * `useVariantLabEngine` — raw engine access escape hatch.\n *\n * Most consumers should reach for `useVariant` / `useVariantValue` /\n * `useExperiment` instead. This hook is for code that needs to call\n * engine methods directly (e.g. `setVariant` from a debug panel, or\n * `reportCrash` from a custom error boundary).\n *\n * Throws synchronously when called outside a `VariantLabProvider`\n * because any other behavior (returning `null`, lazy init) would hide\n * the real bug behind mysterious fallbacks elsewhere in the tree.\n */\n\nimport type { VariantEngine } from \"@variantlab/core\";\nimport { useContext } from \"react\";\nimport { VariantLabContext } from \"../context.js\";\n\nexport function useVariantLabEngine(): VariantEngine {\n  const engine = useContext(VariantLabContext);\n  if (engine === null) {\n    throw new Error(\"useVariantLabEngine: no <VariantLabProvider> found above this component.\");\n  }\n  return engine;\n}\n","/**\n * `useVariant` — read the current variant id for an experiment.\n *\n * Subscribes to engine events via `useSyncExternalStore` so that the\n * component re-renders whenever the variant for this experiment\n * actually changes (manual override, rollback, config reload, context\n * update). Events that don't affect this experiment are filtered out\n * at the listener level — React's bail-out on identical snapshots\n * handles the rest.\n *\n * The snapshot callback is `engine.getVariant(id)` directly. The\n * engine memoizes the result in an internal cache, so repeated reads\n * in the same render pass are O(1) and side-effect free — which is\n * exactly what `useSyncExternalStore` requires.\n */\n\nimport type { EngineEvent } from \"@variantlab/core\";\nimport { useCallback, useSyncExternalStore } from \"react\";\nimport { useVariantLabEngine } from \"./use-variant-lab-engine.js\";\n\nexport function useVariant(experimentId: string): string {\n  const engine = useVariantLabEngine();\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void): (() => void) => {\n      return engine.subscribe((event: EngineEvent) => {\n        if (shouldNotify(event, experimentId)) onStoreChange();\n      });\n    },\n    [engine, experimentId],\n  );\n\n  const getSnapshot = useCallback(\n    (): string => engine.getVariant(experimentId),\n    [engine, experimentId],\n  );\n\n  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n\n/**\n * Decide whether an engine event should retrigger snapshot sampling.\n * Broad events (`configLoaded`, `contextUpdated`) always fire; targeted\n * events fire only when they name this experiment.\n */\nfunction shouldNotify(event: EngineEvent, experimentId: string): boolean {\n  switch (event.type) {\n    case \"configLoaded\":\n    case \"contextUpdated\":\n      return true;\n    case \"variantChanged\":\n    case \"rollback\":\n    case \"assignment\":\n      return event.experimentId === experimentId;\n    default:\n      return false;\n  }\n}\n","/**\n * `<Variant>` — render-prop switch for \"render\" experiments.\n *\n * Takes a plain `Record<variantId, ReactNode>` as its children. The\n * shape intentionally looks like a lookup table so grep, codegen, and\n * TypeScript exhaustiveness checks all work without any custom\n * helpers. If the active variant isn't in the table we render\n * `fallback` if provided, else `null` — silent render failures are\n * preferable to crashing the tree when a config is missing a case.\n *\n * This component is tiny on purpose: the real logic lives in\n * `useVariant`, and everything here is table lookup plus a fallback.\n */\nimport type { ReactNode } from \"react\";\nimport { useVariant } from \"../hooks/use-variant.js\";\n\nexport interface VariantProps {\n  readonly experimentId: string;\n  readonly children: Readonly<Record<string, ReactNode>>;\n  readonly fallback?: ReactNode;\n}\n\nexport function Variant({ experimentId, children, fallback }: VariantProps): ReactNode {\n  const active = useVariant(experimentId);\n  const node = children[active];\n  if (node !== undefined) return node;\n  return fallback ?? null;\n}\n","/**\n * `useVariantValue` — read a \"value\" experiment's typed payload.\n *\n * Thin wrapper around `useVariant` that looks up the matching\n * `variant.value` from the engine. Used for copy, pricing, feature\n * toggles, and any other experiment where the thing that varies is\n * data, not a React component.\n *\n * The generic `T` exists purely for type inference ergonomics. When\n * codegen is active it's filled in automatically from\n * `GeneratedExperiments[id][\"value\"]`; otherwise callers pass an\n * explicit type parameter.\n */\nimport { useVariant } from \"./use-variant.js\";\nimport { useVariantLabEngine } from \"./use-variant-lab-engine.js\";\n\nexport function useVariantValue<T = unknown>(experimentId: string): T {\n  const engine = useVariantLabEngine();\n  // Track the variant id so we re-render when it changes. The actual\n  // value is fetched via `getVariantValue` which walks the variant\n  // table; this is O(n_variants) which is fine for typical configs.\n  useVariant(experimentId);\n  return engine.getVariantValue<T>(experimentId);\n}\n","/**\n * `<VariantValue>` — function-as-child helper for \"value\" experiments.\n *\n * Lets callers declaratively render with a typed variant value without\n * having to import `useVariantValue` into a component that is\n * otherwise pure JSX. Useful inside dense markup where introducing a\n * hook would require pulling the surrounding code into a wrapper\n * component.\n */\nimport type { ReactNode } from \"react\";\nimport { useVariantValue } from \"../hooks/use-variant-value.js\";\n\nexport interface VariantValueProps<T> {\n  readonly experimentId: string;\n  readonly children: (value: T) => ReactNode;\n}\n\nexport function VariantValue<T = unknown>({\n  experimentId,\n  children,\n}: VariantValueProps<T>): ReactNode {\n  const value = useVariantValue<T>(experimentId);\n  return children(value);\n}\n","/**\n * `useExperiment` — combined read + tracker helper.\n *\n * Returns the variant id, the typed value, and a `track` function\n * bound to this experiment. `track` is a pass-through to the engine's\n * history ring buffer — it doesn't do network IO (core makes no\n * outbound calls, period) but it does give downstream telemetry\n * subscribers something to observe.\n *\n * The `track` closure is stable across re-renders via `useCallback`\n * so passing it into memoized children doesn't bust their memoization.\n */\nimport { useCallback } from \"react\";\nimport { useVariant } from \"./use-variant.js\";\nimport { useVariantLabEngine } from \"./use-variant-lab-engine.js\";\n\nexport interface UseExperimentResult<T> {\n  readonly variant: string;\n  readonly value: T;\n  readonly track: (eventName: string, properties?: Record<string, unknown>) => void;\n}\n\nexport function useExperiment<T = unknown>(experimentId: string): UseExperimentResult<T> {\n  const engine = useVariantLabEngine();\n  const variant = useVariant(experimentId);\n  const value = engine.getVariantValue<T>(experimentId);\n\n  const track = useCallback((_eventName: string, _properties?: Record<string, unknown>): void => {\n    // Telemetry forwarding is a phase-2 feature. For now `track` is\n    // a no-op sink so callers can wire up the API today without\n    // waiting for the pluggable telemetry layer.\n  }, []);\n\n  return { variant, value, track };\n}\n","/**\n * `useRouteExperiments` — list experiments active on a given route.\n *\n * Pure derivation from `engine.getExperiments(route)`. The challenge\n * is that `engine.getExperiments(route)` allocates a fresh filtered\n * array on every call, which would cause `useSyncExternalStore` to\n * flag an infinite update loop. We cache the snapshot in a ref and\n * invalidate it whenever a relevant engine event fires, so the\n * reference is stable between notifications.\n */\n\nimport type { EngineEvent, Experiment } from \"@variantlab/core\";\nimport { useCallback, useRef, useSyncExternalStore } from \"react\";\nimport { useVariantLabEngine } from \"./use-variant-lab-engine.js\";\n\ninterface Cached {\n  readonly route: string | undefined;\n  readonly snapshot: readonly Experiment[];\n}\n\nexport function useRouteExperiments(route?: string): readonly Experiment[] {\n  const engine = useVariantLabEngine();\n  const cacheRef = useRef<Cached | null>(null);\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void): (() => void) => {\n      return engine.subscribe((event: EngineEvent) => {\n        if (event.type === \"configLoaded\" || event.type === \"contextUpdated\") {\n          cacheRef.current = null;\n          onStoreChange();\n        }\n      });\n    },\n    [engine],\n  );\n\n  const getSnapshot = useCallback((): readonly Experiment[] => {\n    const cached = cacheRef.current;\n    if (cached !== null && cached.route === route) return cached.snapshot;\n    const snapshot = engine.getExperiments(route);\n    cacheRef.current = { route, snapshot };\n    return snapshot;\n  }, [engine, route]);\n\n  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n","/**\n * `useSetVariant` — dev-only imperative variant override.\n *\n * Returns a stable setter bound to the current engine. Intended for\n * debug UIs (Storybook, the overlay, dev tools) and QA scripts, not\n * for production logic. Production code should update the config or\n * targeting, not force variants from components.\n */\nimport { useCallback } from \"react\";\nimport { useVariantLabEngine } from \"./use-variant-lab-engine.js\";\n\nexport function useSetVariant(): (experimentId: string, variantId: string) => void {\n  const engine = useVariantLabEngine();\n  return useCallback(\n    (experimentId: string, variantId: string): void => {\n      engine.setVariant(experimentId, variantId);\n    },\n    [engine],\n  );\n}\n","/**\n * `@variantlab/react` — public API barrel.\n *\n * Every adapter in this package is thin: the heavy lifting is done by\n * `@variantlab/core`'s `VariantEngine`, which this adapter wires into\n * React's rendering model. Callers of `useVariant` never see the\n * engine directly unless they opt in via `useVariantLabEngine`.\n */\nexport const VERSION = \"0.0.0\";\n\nexport {\n  VariantErrorBoundary,\n  type VariantErrorBoundaryProps,\n} from \"./components/error-boundary.js\";\nexport { Variant, type VariantProps } from \"./components/variant.js\";\nexport { VariantValue, type VariantValueProps } from \"./components/variant-value.js\";\nexport {\n  VariantLabContext,\n  VariantLabProvider,\n  type VariantLabProviderProps,\n} from \"./context.js\";\nexport { type UseExperimentResult, useExperiment } from \"./hooks/use-experiment.js\";\nexport { useRouteExperiments } from \"./hooks/use-route-experiments.js\";\nexport { useSetVariant } from \"./hooks/use-set-variant.js\";\nexport { useVariant } from \"./hooks/use-variant.js\";\nexport { useVariantLabEngine } from \"./hooks/use-variant-lab-engine.js\";\nexport { useVariantValue } from \"./hooks/use-variant-value.js\";\n"]}

package/dist/index.d.cts

@@ -0,0 +1,144 @@
+import * as react from 'react';
+import { Component, ReactNode, ErrorInfo } from 'react';
+import { VariantEngine, VariantContext, Experiment } from '@variantlab/core';
+
+interface VariantErrorBoundaryProps {
+    readonly experimentId: string;
+    readonly fallback?: ReactNode | ((error: Error) => ReactNode);
+    readonly children: ReactNode;
+}
+interface VariantErrorBoundaryState {
+    readonly error: Error | null;
+}
+declare class VariantErrorBoundary extends Component<VariantErrorBoundaryProps, VariantErrorBoundaryState> {
+    static contextType: react.Context<VariantEngine | null>;
+    context: VariantEngine | null;
+    state: VariantErrorBoundaryState;
+    static getDerivedStateFromError(error: Error): VariantErrorBoundaryState;
+    componentDidCatch(error: Error, _info: ErrorInfo): void;
+    componentDidUpdate(prevProps: VariantErrorBoundaryProps): void;
+    render(): ReactNode;
+}
+
+/**
+ * `<Variant>` — render-prop switch for "render" experiments.
+ *
+ * Takes a plain `Record<variantId, ReactNode>` as its children. The
+ * shape intentionally looks like a lookup table so grep, codegen, and
+ * TypeScript exhaustiveness checks all work without any custom
+ * helpers. If the active variant isn't in the table we render
+ * `fallback` if provided, else `null` — silent render failures are
+ * preferable to crashing the tree when a config is missing a case.
+ *
+ * This component is tiny on purpose: the real logic lives in
+ * `useVariant`, and everything here is table lookup plus a fallback.
+ */
+
+interface VariantProps {
+    readonly experimentId: string;
+    readonly children: Readonly<Record<string, ReactNode>>;
+    readonly fallback?: ReactNode;
+}
+declare function Variant({ experimentId, children, fallback }: VariantProps): ReactNode;
+
+/**
+ * `<VariantValue>` — function-as-child helper for "value" experiments.
+ *
+ * Lets callers declaratively render with a typed variant value without
+ * having to import `useVariantValue` into a component that is
+ * otherwise pure JSX. Useful inside dense markup where introducing a
+ * hook would require pulling the surrounding code into a wrapper
+ * component.
+ */
+
+interface VariantValueProps<T> {
+    readonly experimentId: string;
+    readonly children: (value: T) => ReactNode;
+}
+declare function VariantValue<T = unknown>({ experimentId, children, }: VariantValueProps<T>): ReactNode;
+
+/** The raw context value. `null` until a provider wraps the tree. */
+declare const VariantLabContext: react.Context<VariantEngine | null>;
+interface VariantLabProviderProps {
+    /** A pre-constructed engine from `createEngine(...)`. */
+    readonly engine: VariantEngine;
+    /** Optional runtime context applied once on mount. */
+    readonly initialContext?: VariantContext;
+    readonly children?: ReactNode;
+}
+/**
+ * Wraps descendants so the hooks in this package can locate the engine.
+ *
+ * The value handed to `Context.Provider` is memoized on `engine` alone
+ * so that unrelated parent re-renders don't force a new reference
+ * (which would cascade through every `useVariant` consumer).
+ */
+declare function VariantLabProvider({ engine, initialContext, children, }: VariantLabProviderProps): ReactNode;
+
+interface UseExperimentResult<T> {
+    readonly variant: string;
+    readonly value: T;
+    readonly track: (eventName: string, properties?: Record<string, unknown>) => void;
+}
+declare function useExperiment<T = unknown>(experimentId: string): UseExperimentResult<T>;
+
+/**
+ * `useRouteExperiments` — list experiments active on a given route.
+ *
+ * Pure derivation from `engine.getExperiments(route)`. The challenge
+ * is that `engine.getExperiments(route)` allocates a fresh filtered
+ * array on every call, which would cause `useSyncExternalStore` to
+ * flag an infinite update loop. We cache the snapshot in a ref and
+ * invalidate it whenever a relevant engine event fires, so the
+ * reference is stable between notifications.
+ */
+
+declare function useRouteExperiments(route?: string): readonly Experiment[];
+
+declare function useSetVariant(): (experimentId: string, variantId: string) => void;
+
+/**
+ * `useVariant` — read the current variant id for an experiment.
+ *
+ * Subscribes to engine events via `useSyncExternalStore` so that the
+ * component re-renders whenever the variant for this experiment
+ * actually changes (manual override, rollback, config reload, context
+ * update). Events that don't affect this experiment are filtered out
+ * at the listener level — React's bail-out on identical snapshots
+ * handles the rest.
+ *
+ * The snapshot callback is `engine.getVariant(id)` directly. The
+ * engine memoizes the result in an internal cache, so repeated reads
+ * in the same render pass are O(1) and side-effect free — which is
+ * exactly what `useSyncExternalStore` requires.
+ */
+declare function useVariant(experimentId: string): string;
+
+/**
+ * `useVariantLabEngine` — raw engine access escape hatch.
+ *
+ * Most consumers should reach for `useVariant` / `useVariantValue` /
+ * `useExperiment` instead. This hook is for code that needs to call
+ * engine methods directly (e.g. `setVariant` from a debug panel, or
+ * `reportCrash` from a custom error boundary).
+ *
+ * Throws synchronously when called outside a `VariantLabProvider`
+ * because any other behavior (returning `null`, lazy init) would hide
+ * the real bug behind mysterious fallbacks elsewhere in the tree.
+ */
+
+declare function useVariantLabEngine(): VariantEngine;
+
+declare function useVariantValue<T = unknown>(experimentId: string): T;
+
+/**
+ * `@variantlab/react` — public API barrel.
+ *
+ * Every adapter in this package is thin: the heavy lifting is done by
+ * `@variantlab/core`'s `VariantEngine`, which this adapter wires into
+ * React's rendering model. Callers of `useVariant` never see the
+ * engine directly unless they opt in via `useVariantLabEngine`.
+ */
+declare const VERSION = "0.0.0";
+
+export { type UseExperimentResult, VERSION, Variant, VariantErrorBoundary, type VariantErrorBoundaryProps, VariantLabContext, VariantLabProvider, type VariantLabProviderProps, type VariantProps, VariantValue, type VariantValueProps, useExperiment, useRouteExperiments, useSetVariant, useVariant, useVariantLabEngine, useVariantValue };

package/dist/index.d.ts

@@ -0,0 +1,144 @@
+import * as react from 'react';
+import { Component, ReactNode, ErrorInfo } from 'react';
+import { VariantEngine, VariantContext, Experiment } from '@variantlab/core';
+
+interface VariantErrorBoundaryProps {
+    readonly experimentId: string;
+    readonly fallback?: ReactNode | ((error: Error) => ReactNode);
+    readonly children: ReactNode;
+}
+interface VariantErrorBoundaryState {
+    readonly error: Error | null;
+}
+declare class VariantErrorBoundary extends Component<VariantErrorBoundaryProps, VariantErrorBoundaryState> {
+    static contextType: react.Context<VariantEngine | null>;
+    context: VariantEngine | null;
+    state: VariantErrorBoundaryState;
+    static getDerivedStateFromError(error: Error): VariantErrorBoundaryState;
+    componentDidCatch(error: Error, _info: ErrorInfo): void;
+    componentDidUpdate(prevProps: VariantErrorBoundaryProps): void;
+    render(): ReactNode;
+}
+
+/**
+ * `<Variant>` — render-prop switch for "render" experiments.
+ *
+ * Takes a plain `Record<variantId, ReactNode>` as its children. The
+ * shape intentionally looks like a lookup table so grep, codegen, and
+ * TypeScript exhaustiveness checks all work without any custom
+ * helpers. If the active variant isn't in the table we render
+ * `fallback` if provided, else `null` — silent render failures are
+ * preferable to crashing the tree when a config is missing a case.
+ *
+ * This component is tiny on purpose: the real logic lives in
+ * `useVariant`, and everything here is table lookup plus a fallback.
+ */
+
+interface VariantProps {
+    readonly experimentId: string;
+    readonly children: Readonly<Record<string, ReactNode>>;
+    readonly fallback?: ReactNode;
+}
+declare function Variant({ experimentId, children, fallback }: VariantProps): ReactNode;
+
+/**
+ * `<VariantValue>` — function-as-child helper for "value" experiments.
+ *
+ * Lets callers declaratively render with a typed variant value without
+ * having to import `useVariantValue` into a component that is
+ * otherwise pure JSX. Useful inside dense markup where introducing a
+ * hook would require pulling the surrounding code into a wrapper
+ * component.
+ */
+
+interface VariantValueProps<T> {
+    readonly experimentId: string;
+    readonly children: (value: T) => ReactNode;
+}
+declare function VariantValue<T = unknown>({ experimentId, children, }: VariantValueProps<T>): ReactNode;
+
+/** The raw context value. `null` until a provider wraps the tree. */
+declare const VariantLabContext: react.Context<VariantEngine | null>;
+interface VariantLabProviderProps {
+    /** A pre-constructed engine from `createEngine(...)`. */
+    readonly engine: VariantEngine;
+    /** Optional runtime context applied once on mount. */
+    readonly initialContext?: VariantContext;
+    readonly children?: ReactNode;
+}
+/**
+ * Wraps descendants so the hooks in this package can locate the engine.
+ *
+ * The value handed to `Context.Provider` is memoized on `engine` alone
+ * so that unrelated parent re-renders don't force a new reference
+ * (which would cascade through every `useVariant` consumer).
+ */
+declare function VariantLabProvider({ engine, initialContext, children, }: VariantLabProviderProps): ReactNode;
+
+interface UseExperimentResult<T> {
+    readonly variant: string;
+    readonly value: T;
+    readonly track: (eventName: string, properties?: Record<string, unknown>) => void;
+}
+declare function useExperiment<T = unknown>(experimentId: string): UseExperimentResult<T>;
+
+/**
+ * `useRouteExperiments` — list experiments active on a given route.
+ *
+ * Pure derivation from `engine.getExperiments(route)`. The challenge
+ * is that `engine.getExperiments(route)` allocates a fresh filtered
+ * array on every call, which would cause `useSyncExternalStore` to
+ * flag an infinite update loop. We cache the snapshot in a ref and
+ * invalidate it whenever a relevant engine event fires, so the
+ * reference is stable between notifications.
+ */
+
+declare function useRouteExperiments(route?: string): readonly Experiment[];
+
+declare function useSetVariant(): (experimentId: string, variantId: string) => void;
+
+/**
+ * `useVariant` — read the current variant id for an experiment.
+ *
+ * Subscribes to engine events via `useSyncExternalStore` so that the
+ * component re-renders whenever the variant for this experiment
+ * actually changes (manual override, rollback, config reload, context
+ * update). Events that don't affect this experiment are filtered out
+ * at the listener level — React's bail-out on identical snapshots
+ * handles the rest.
+ *
+ * The snapshot callback is `engine.getVariant(id)` directly. The
+ * engine memoizes the result in an internal cache, so repeated reads
+ * in the same render pass are O(1) and side-effect free — which is
+ * exactly what `useSyncExternalStore` requires.
+ */
+declare function useVariant(experimentId: string): string;
+
+/**
+ * `useVariantLabEngine` — raw engine access escape hatch.
+ *
+ * Most consumers should reach for `useVariant` / `useVariantValue` /
+ * `useExperiment` instead. This hook is for code that needs to call
+ * engine methods directly (e.g. `setVariant` from a debug panel, or
+ * `reportCrash` from a custom error boundary).
+ *
+ * Throws synchronously when called outside a `VariantLabProvider`
+ * because any other behavior (returning `null`, lazy init) would hide
+ * the real bug behind mysterious fallbacks elsewhere in the tree.
+ */
+
+declare function useVariantLabEngine(): VariantEngine;
+
+declare function useVariantValue<T = unknown>(experimentId: string): T;
+
+/**
+ * `@variantlab/react` — public API barrel.
+ *
+ * Every adapter in this package is thin: the heavy lifting is done by
+ * `@variantlab/core`'s `VariantEngine`, which this adapter wires into
+ * React's rendering model. Callers of `useVariant` never see the
+ * engine directly unless they opt in via `useVariantLabEngine`.
+ */
+declare const VERSION = "0.0.0";
+
+export { type UseExperimentResult, VERSION, Variant, VariantErrorBoundary, type VariantErrorBoundaryProps, VariantLabContext, VariantLabProvider, type VariantLabProviderProps, type VariantProps, VariantValue, type VariantValueProps, useExperiment, useRouteExperiments, useSetVariant, useVariant, useVariantLabEngine, useVariantValue };

package/dist/index.js

@@ -0,0 +1,167 @@
+import { createContext, Component, useMemo, useRef, useLayoutEffect, useContext, useCallback, useSyncExternalStore } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+// src/components/error-boundary.tsx
+var VariantLabContext = createContext(null);
+function VariantLabProvider({
+  engine,
+  initialContext,
+  children
+}) {
+  const value = useMemo(() => engine, [engine]);
+  const appliedRef = useRef(null);
+  useLayoutEffect(() => {
+    if (initialContext === void 0) return;
+    const prev = appliedRef.current;
+    if (prev !== null && prev.engine === engine && prev.ctx === initialContext) {
+      return;
+    }
+    engine.updateContext(initialContext);
+    appliedRef.current = { engine, ctx: initialContext };
+  }, [engine, initialContext]);
+  return /* @__PURE__ */ jsx(VariantLabContext.Provider, { value, children });
+}
+
+// src/components/error-boundary.tsx
+var VariantErrorBoundary = class extends Component {
+  constructor() {
+    super(...arguments);
+    this.state = { error: null };
+  }
+  static getDerivedStateFromError(error) {
+    return { error };
+  }
+  componentDidCatch(error, _info) {
+    const engine = this.context;
+    if (engine !== null) {
+      try {
+        engine.reportCrash(this.props.experimentId, error);
+      } catch {
+      }
+    }
+  }
+  componentDidUpdate(prevProps) {
+    if (this.state.error !== null && prevProps.children !== this.props.children) {
+      this.setState({ error: null });
+    }
+  }
+  render() {
+    const { error } = this.state;
+    if (error !== null) {
+      const { fallback } = this.props;
+      if (typeof fallback === "function") return fallback(error);
+      return fallback ?? null;
+    }
+    return this.props.children;
+  }
+};
+VariantErrorBoundary.contextType = VariantLabContext;
+function useVariantLabEngine() {
+  const engine = useContext(VariantLabContext);
+  if (engine === null) {
+    throw new Error("useVariantLabEngine: no <VariantLabProvider> found above this component.");
+  }
+  return engine;
+}
+
+// src/hooks/use-variant.ts
+function useVariant(experimentId) {
+  const engine = useVariantLabEngine();
+  const subscribe = useCallback(
+    (onStoreChange) => {
+      return engine.subscribe((event) => {
+        if (shouldNotify(event, experimentId)) onStoreChange();
+      });
+    },
+    [engine, experimentId]
+  );
+  const getSnapshot = useCallback(
+    () => engine.getVariant(experimentId),
+    [engine, experimentId]
+  );
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+function shouldNotify(event, experimentId) {
+  switch (event.type) {
+    case "configLoaded":
+    case "contextUpdated":
+      return true;
+    case "variantChanged":
+    case "rollback":
+    case "assignment":
+      return event.experimentId === experimentId;
+    default:
+      return false;
+  }
+}
+
+// src/components/variant.tsx
+function Variant({ experimentId, children, fallback }) {
+  const active = useVariant(experimentId);
+  const node = children[active];
+  if (node !== void 0) return node;
+  return fallback ?? null;
+}
+
+// src/hooks/use-variant-value.ts
+function useVariantValue(experimentId) {
+  const engine = useVariantLabEngine();
+  useVariant(experimentId);
+  return engine.getVariantValue(experimentId);
+}
+
+// src/components/variant-value.tsx
+function VariantValue({
+  experimentId,
+  children
+}) {
+  const value = useVariantValue(experimentId);
+  return children(value);
+}
+function useExperiment(experimentId) {
+  const engine = useVariantLabEngine();
+  const variant = useVariant(experimentId);
+  const value = engine.getVariantValue(experimentId);
+  const track = useCallback((_eventName, _properties) => {
+  }, []);
+  return { variant, value, track };
+}
+function useRouteExperiments(route) {
+  const engine = useVariantLabEngine();
+  const cacheRef = useRef(null);
+  const subscribe = useCallback(
+    (onStoreChange) => {
+      return engine.subscribe((event) => {
+        if (event.type === "configLoaded" || event.type === "contextUpdated") {
+          cacheRef.current = null;
+          onStoreChange();
+        }
+      });
+    },
+    [engine]
+  );
+  const getSnapshot = useCallback(() => {
+    const cached = cacheRef.current;
+    if (cached !== null && cached.route === route) return cached.snapshot;
+    const snapshot = engine.getExperiments(route);
+    cacheRef.current = { route, snapshot };
+    return snapshot;
+  }, [engine, route]);
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+function useSetVariant() {
+  const engine = useVariantLabEngine();
+  return useCallback(
+    (experimentId, variantId) => {
+      engine.setVariant(experimentId, variantId);
+    },
+    [engine]
+  );
+}
+
+// src/index.ts
+var VERSION = "0.0.0";
+
+export { VERSION, Variant, VariantErrorBoundary, VariantLabContext, VariantLabProvider, VariantValue, useExperiment, useRouteExperiments, useSetVariant, useVariant, useVariantLabEngine, useVariantValue };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/context.tsx","../src/components/error-boundary.tsx","../src/hooks/use-variant-lab-engine.ts","../src/hooks/use-variant.ts","../src/components/variant.tsx","../src/hooks/use-variant-value.ts","../src/components/variant-value.tsx","../src/hooks/use-experiment.ts","../src/hooks/use-route-experiments.ts","../src/hooks/use-set-variant.ts","../src/index.ts"],"names":["useCallback","useRef","useSyncExternalStore"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * React context and provider for variantlab.\n *\n * The provider is a thin wrapper that hands a pre-built `VariantEngine`\n * to descendants via React context. It intentionally does NOT own the\n * engine: callers construct it via `createEngine(...)` and pass it in.\n * That keeps the adapter testable (swap in a mock engine), SSR-safe\n * (server code can build an engine before render), and free of\n * lifecycle surprises — unmounting the provider never disposes the\n * engine because the provider didn't create it.\n *\n * `initialContext`, when supplied, is applied via `useLayoutEffect`\n * before the first browser paint. We use a ref to guard against\n * repeated application on re-renders so the engine cache is only\n * busted when the caller actually swaps engines.\n */\n\nimport type { VariantContext, VariantEngine } from \"@variantlab/core\";\nimport { createContext, type ReactNode, useLayoutEffect, useMemo, useRef } from \"react\";\n\n/** The raw context value. `null` until a provider wraps the tree. */\nexport const VariantLabContext = createContext<VariantEngine | null>(null);\n\nexport interface VariantLabProviderProps {\n  /** A pre-constructed engine from `createEngine(...)`. */\n  readonly engine: VariantEngine;\n  /** Optional runtime context applied once on mount. */\n  readonly initialContext?: VariantContext;\n  readonly children?: ReactNode;\n}\n\n/**\n * Wraps descendants so the hooks in this package can locate the engine.\n *\n * The value handed to `Context.Provider` is memoized on `engine` alone\n * so that unrelated parent re-renders don't force a new reference\n * (which would cascade through every `useVariant` consumer).\n */\nexport function VariantLabProvider({\n  engine,\n  initialContext,\n  children,\n}: VariantLabProviderProps): ReactNode {\n  // Stable context value: only changes when the engine itself changes.\n  const value = useMemo(() => engine, [engine]);\n\n  // Track which (engine, initialContext) pair we've already applied so\n  // re-renders don't re-invoke updateContext (which would clear the\n  // engine cache and cause unnecessary reassignment events).\n  const appliedRef = useRef<{\n    readonly engine: VariantEngine;\n    readonly ctx: VariantContext | undefined;\n  } | null>(null);\n\n  useLayoutEffect(() => {\n    if (initialContext === undefined) return;\n    const prev = appliedRef.current;\n    if (prev !== null && prev.engine === engine && prev.ctx === initialContext) {\n      return;\n    }\n    engine.updateContext(initialContext);\n    appliedRef.current = { engine, ctx: initialContext };\n  }, [engine, initialContext]);\n\n  return <VariantLabContext.Provider value={value}>{children}</VariantLabContext.Provider>;\n}\n","/**\n * `<VariantErrorBoundary>` — crash insulation for experiment render trees.\n *\n * Wraps a variant's subtree in a class-based error boundary (the only\n * remaining legitimate use of class components in modern React). When\n * a child throws, it:\n *\n *   1. reports the crash to the engine via `engine.reportCrash(id, err)`,\n *      which feeds the rollback counter defined in `config-format.md`;\n *   2. renders `fallback` (or `null`) for the rest of the current\n *      commit cycle;\n *   3. resets itself so the next render can try again with the new\n *      variant (likely the rolled-back default after N crashes).\n *\n * The engine lookup goes through `VariantLabContext` rather than a\n * prop so the ergonomics match the hook-first API. `contextType` on\n * the class makes the context value available as `this.context` in\n * `componentDidCatch`.\n */\n\nimport type { VariantEngine } from \"@variantlab/core\";\nimport { Component, type ErrorInfo, type ReactNode } from \"react\";\nimport { VariantLabContext } from \"../context.js\";\n\nexport interface VariantErrorBoundaryProps {\n  readonly experimentId: string;\n  readonly fallback?: ReactNode | ((error: Error) => ReactNode);\n  readonly children: ReactNode;\n}\n\ninterface VariantErrorBoundaryState {\n  readonly error: Error | null;\n}\n\nexport class VariantErrorBoundary extends Component<\n  VariantErrorBoundaryProps,\n  VariantErrorBoundaryState\n> {\n  static override contextType = VariantLabContext;\n  declare context: VariantEngine | null;\n  override state: VariantErrorBoundaryState = { error: null };\n\n  static getDerivedStateFromError(error: Error): VariantErrorBoundaryState {\n    return { error };\n  }\n\n  override componentDidCatch(error: Error, _info: ErrorInfo): void {\n    const engine = this.context;\n    if (engine !== null) {\n      try {\n        engine.reportCrash(this.props.experimentId, error);\n      } catch {\n        // Swallow crash-reporting failures — we must not double-throw\n        // inside an error boundary.\n      }\n    }\n  }\n\n  override componentDidUpdate(prevProps: VariantErrorBoundaryProps): void {\n    // If the children prop changes after a recovery (e.g. the engine\n    // rolled back and a parent re-rendered with a different subtree),\n    // clear the error so we attempt to render the new tree.\n    if (this.state.error !== null && prevProps.children !== this.props.children) {\n      this.setState({ error: null });\n    }\n  }\n\n  override render(): ReactNode {\n    const { error } = this.state;\n    if (error !== null) {\n      const { fallback } = this.props;\n      if (typeof fallback === \"function\") return fallback(error);\n      return fallback ?? null;\n    }\n    return this.props.children;\n  }\n}\n","/**\n * `useVariantLabEngine` — raw engine access escape hatch.\n *\n * Most consumers should reach for `useVariant` / `useVariantValue` /\n * `useExperiment` instead. This hook is for code that needs to call\n * engine methods directly (e.g. `setVariant` from a debug panel, or\n * `reportCrash` from a custom error boundary).\n *\n * Throws synchronously when called outside a `VariantLabProvider`\n * because any other behavior (returning `null`, lazy init) would hide\n * the real bug behind mysterious fallbacks elsewhere in the tree.\n */\n\nimport type { VariantEngine } from \"@variantlab/core\";\nimport { useContext } from \"react\";\nimport { VariantLabContext } from \"../context.js\";\n\nexport function useVariantLabEngine(): VariantEngine {\n  const engine = useContext(VariantLabContext);\n  if (engine === null) {\n    throw new Error(\"useVariantLabEngine: no <VariantLabProvider> found above this component.\");\n  }\n  return engine;\n}\n","/**\n * `useVariant` — read the current variant id for an experiment.\n *\n * Subscribes to engine events via `useSyncExternalStore` so that the\n * component re-renders whenever the variant for this experiment\n * actually changes (manual override, rollback, config reload, context\n * update). Events that don't affect this experiment are filtered out\n * at the listener level — React's bail-out on identical snapshots\n * handles the rest.\n *\n * The snapshot callback is `engine.getVariant(id)` directly. The\n * engine memoizes the result in an internal cache, so repeated reads\n * in the same render pass are O(1) and side-effect free — which is\n * exactly what `useSyncExternalStore` requires.\n */\n\nimport type { EngineEvent } from \"@variantlab/core\";\nimport { useCallback, useSyncExternalStore } from \"react\";\nimport { useVariantLabEngine } from \"./use-variant-lab-engine.js\";\n\nexport function useVariant(experimentId: string): string {\n  const engine = useVariantLabEngine();\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void): (() => void) => {\n      return engine.subscribe((event: EngineEvent) => {\n        if (shouldNotify(event, experimentId)) onStoreChange();\n      });\n    },\n    [engine, experimentId],\n  );\n\n  const getSnapshot = useCallback(\n    (): string => engine.getVariant(experimentId),\n    [engine, experimentId],\n  );\n\n  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n\n/**\n * Decide whether an engine event should retrigger snapshot sampling.\n * Broad events (`configLoaded`, `contextUpdated`) always fire; targeted\n * events fire only when they name this experiment.\n */\nfunction shouldNotify(event: EngineEvent, experimentId: string): boolean {\n  switch (event.type) {\n    case \"configLoaded\":\n    case \"contextUpdated\":\n      return true;\n    case \"variantChanged\":\n    case \"rollback\":\n    case \"assignment\":\n      return event.experimentId === experimentId;\n    default:\n      return false;\n  }\n}\n","/**\n * `<Variant>` — render-prop switch for \"render\" experiments.\n *\n * Takes a plain `Record<variantId, ReactNode>` as its children. The\n * shape intentionally looks like a lookup table so grep, codegen, and\n * TypeScript exhaustiveness checks all work without any custom\n * helpers. If the active variant isn't in the table we render\n * `fallback` if provided, else `null` — silent render failures are\n * preferable to crashing the tree when a config is missing a case.\n *\n * This component is tiny on purpose: the real logic lives in\n * `useVariant`, and everything here is table lookup plus a fallback.\n */\nimport type { ReactNode } from \"react\";\nimport { useVariant } from \"../hooks/use-variant.js\";\n\nexport interface VariantProps {\n  readonly experimentId: string;\n  readonly children: Readonly<Record<string, ReactNode>>;\n  readonly fallback?: ReactNode;\n}\n\nexport function Variant({ experimentId, children, fallback }: VariantProps): ReactNode {\n  const active = useVariant(experimentId);\n  const node = children[active];\n  if (node !== undefined) return node;\n  return fallback ?? null;\n}\n","/**\n * `useVariantValue` — read a \"value\" experiment's typed payload.\n *\n * Thin wrapper around `useVariant` that looks up the matching\n * `variant.value` from the engine. Used for copy, pricing, feature\n * toggles, and any other experiment where the thing that varies is\n * data, not a React component.\n *\n * The generic `T` exists purely for type inference ergonomics. When\n * codegen is active it's filled in automatically from\n * `GeneratedExperiments[id][\"value\"]`; otherwise callers pass an\n * explicit type parameter.\n */\nimport { useVariant } from \"./use-variant.js\";\nimport { useVariantLabEngine } from \"./use-variant-lab-engine.js\";\n\nexport function useVariantValue<T = unknown>(experimentId: string): T {\n  const engine = useVariantLabEngine();\n  // Track the variant id so we re-render when it changes. The actual\n  // value is fetched via `getVariantValue` which walks the variant\n  // table; this is O(n_variants) which is fine for typical configs.\n  useVariant(experimentId);\n  return engine.getVariantValue<T>(experimentId);\n}\n","/**\n * `<VariantValue>` — function-as-child helper for \"value\" experiments.\n *\n * Lets callers declaratively render with a typed variant value without\n * having to import `useVariantValue` into a component that is\n * otherwise pure JSX. Useful inside dense markup where introducing a\n * hook would require pulling the surrounding code into a wrapper\n * component.\n */\nimport type { ReactNode } from \"react\";\nimport { useVariantValue } from \"../hooks/use-variant-value.js\";\n\nexport interface VariantValueProps<T> {\n  readonly experimentId: string;\n  readonly children: (value: T) => ReactNode;\n}\n\nexport function VariantValue<T = unknown>({\n  experimentId,\n  children,\n}: VariantValueProps<T>): ReactNode {\n  const value = useVariantValue<T>(experimentId);\n  return children(value);\n}\n","/**\n * `useExperiment` — combined read + tracker helper.\n *\n * Returns the variant id, the typed value, and a `track` function\n * bound to this experiment. `track` is a pass-through to the engine's\n * history ring buffer — it doesn't do network IO (core makes no\n * outbound calls, period) but it does give downstream telemetry\n * subscribers something to observe.\n *\n * The `track` closure is stable across re-renders via `useCallback`\n * so passing it into memoized children doesn't bust their memoization.\n */\nimport { useCallback } from \"react\";\nimport { useVariant } from \"./use-variant.js\";\nimport { useVariantLabEngine } from \"./use-variant-lab-engine.js\";\n\nexport interface UseExperimentResult<T> {\n  readonly variant: string;\n  readonly value: T;\n  readonly track: (eventName: string, properties?: Record<string, unknown>) => void;\n}\n\nexport function useExperiment<T = unknown>(experimentId: string): UseExperimentResult<T> {\n  const engine = useVariantLabEngine();\n  const variant = useVariant(experimentId);\n  const value = engine.getVariantValue<T>(experimentId);\n\n  const track = useCallback((_eventName: string, _properties?: Record<string, unknown>): void => {\n    // Telemetry forwarding is a phase-2 feature. For now `track` is\n    // a no-op sink so callers can wire up the API today without\n    // waiting for the pluggable telemetry layer.\n  }, []);\n\n  return { variant, value, track };\n}\n","/**\n * `useRouteExperiments` — list experiments active on a given route.\n *\n * Pure derivation from `engine.getExperiments(route)`. The challenge\n * is that `engine.getExperiments(route)` allocates a fresh filtered\n * array on every call, which would cause `useSyncExternalStore` to\n * flag an infinite update loop. We cache the snapshot in a ref and\n * invalidate it whenever a relevant engine event fires, so the\n * reference is stable between notifications.\n */\n\nimport type { EngineEvent, Experiment } from \"@variantlab/core\";\nimport { useCallback, useRef, useSyncExternalStore } from \"react\";\nimport { useVariantLabEngine } from \"./use-variant-lab-engine.js\";\n\ninterface Cached {\n  readonly route: string | undefined;\n  readonly snapshot: readonly Experiment[];\n}\n\nexport function useRouteExperiments(route?: string): readonly Experiment[] {\n  const engine = useVariantLabEngine();\n  const cacheRef = useRef<Cached | null>(null);\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void): (() => void) => {\n      return engine.subscribe((event: EngineEvent) => {\n        if (event.type === \"configLoaded\" || event.type === \"contextUpdated\") {\n          cacheRef.current = null;\n          onStoreChange();\n        }\n      });\n    },\n    [engine],\n  );\n\n  const getSnapshot = useCallback((): readonly Experiment[] => {\n    const cached = cacheRef.current;\n    if (cached !== null && cached.route === route) return cached.snapshot;\n    const snapshot = engine.getExperiments(route);\n    cacheRef.current = { route, snapshot };\n    return snapshot;\n  }, [engine, route]);\n\n  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n","/**\n * `useSetVariant` — dev-only imperative variant override.\n *\n * Returns a stable setter bound to the current engine. Intended for\n * debug UIs (Storybook, the overlay, dev tools) and QA scripts, not\n * for production logic. Production code should update the config or\n * targeting, not force variants from components.\n */\nimport { useCallback } from \"react\";\nimport { useVariantLabEngine } from \"./use-variant-lab-engine.js\";\n\nexport function useSetVariant(): (experimentId: string, variantId: string) => void {\n  const engine = useVariantLabEngine();\n  return useCallback(\n    (experimentId: string, variantId: string): void => {\n      engine.setVariant(experimentId, variantId);\n    },\n    [engine],\n  );\n}\n","/**\n * `@variantlab/react` — public API barrel.\n *\n * Every adapter in this package is thin: the heavy lifting is done by\n * `@variantlab/core`'s `VariantEngine`, which this adapter wires into\n * React's rendering model. Callers of `useVariant` never see the\n * engine directly unless they opt in via `useVariantLabEngine`.\n */\nexport const VERSION = \"0.0.0\";\n\nexport {\n  VariantErrorBoundary,\n  type VariantErrorBoundaryProps,\n} from \"./components/error-boundary.js\";\nexport { Variant, type VariantProps } from \"./components/variant.js\";\nexport { VariantValue, type VariantValueProps } from \"./components/variant-value.js\";\nexport {\n  VariantLabContext,\n  VariantLabProvider,\n  type VariantLabProviderProps,\n} from \"./context.js\";\nexport { type UseExperimentResult, useExperiment } from \"./hooks/use-experiment.js\";\nexport { useRouteExperiments } from \"./hooks/use-route-experiments.js\";\nexport { useSetVariant } from \"./hooks/use-set-variant.js\";\nexport { useVariant } from \"./hooks/use-variant.js\";\nexport { useVariantLabEngine } from \"./hooks/use-variant-lab-engine.js\";\nexport { useVariantValue } from \"./hooks/use-variant-value.js\";\n"]}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@variantlab/react",
+  "version": "0.1.0",
+  "description": "React hooks and components for variantlab.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "keywords": [
+    "ab-testing",
+    "experiments",
+    "feature-flags",
+    "variants",
+    "variantlab",
+    "react",
+    "hooks"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/variantlab/variantlab.git",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/variantlab/variantlab/issues"
+  },
+  "homepage": "https://github.com/variantlab/variantlab#readme",
+  "engines": {
+    "node": ">=18.17"
+  },
+  "dependencies": {
+    "@variantlab/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "jsdom": "^25.0.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "pnpm --dir ../.. exec vitest run --project react",
+    "test:coverage": "pnpm --dir ../.. exec vitest run --coverage --project react",
+    "clean": "rm -rf dist"
+  }
+}