@evanion/react-feature 0.0.0 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+## 0.1.0 (2026-10-17)
+
+### 🚀 Features
+
+- **react-feature:** re-export the core types its own declarations name ([4a4fef01](https://github.com/Evanion/libraries/commit/4a4fef01))
+- **react-feature:** extract the react adapter into its own package ([af19e96a](https://github.com/Evanion/libraries/commit/af19e96a))
+
+### 🩹 Fixes
+
+- **react-feature:** hold the binding back while the core is private ([bce9e235](https://github.com/Evanion/libraries/commit/bce9e235))
+
+### 💅 Refactors
+
+- **react-feature:** call adoptDecisions from the provider ([0bd40d25](https://github.com/Evanion/libraries/commit/0bd40d25))
+
+### 🧱 Updated Dependencies
+
+- Updated @evanion/feature to 0.1.0
+
+### ❤️ Thank You
+
+- Mikael Pettersson @Evanion

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Mikael Pettersson
+
+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,152 @@
+# @evanion/react-feature
+
+**Feature decisions for your React component tree, resolved once and read anywhere.**
+
+To switch a single banner in a complex UI, you often have to prop-drill a flags object through ten layers of components. `@evanion/react-feature` solves this by publishing the decisions `@evanion/feature` has already resolved. Any component in the tree can ask "is this on, and which variant am I in?" without needing to know where the store or the evaluation context lives.
+
+## The Problem: The "Flags Prop-Drill"
+
+When a server resolves flags for a request, the component that actually needs a specific flag is often buried deep in the hierarchy. This creates two primary frictions:
+
+1. **Prop-Drilling**: Components that do not use any flags are forced to carry the flags object simply because a distant child requires it.
+2. **Two Answers Per Request**: If a component resolves a flag for itself, it reads its own clock. This means two components in a single render could land on opposite sides of a time window, causing the page to contradict itself.
+
+## The Solution: One Resolution, Published
+
+`@evanion/feature` resolves every configured feature in one call, and `features.snapshot` states that result as a `DecisionSet` containing the instant of resolution, one decision per key, and the config version wherever the store was built from a document that carries one.
+
+`FeatureProvider` publishes that set to the React tree, allowing `useFeature`, `useFeatureEnabled`, `useVariant`, and `useFeatures` to read it. Because the decisions are already made, no hook evaluates anything during the render.
+
+### Core Concept: The Server Resolves, The Tree Reads
+
+To avoid duplicating complex logic in the UI, `@evanion/react-feature` separates the act of deciding which feature to show from the act of reading that decision.
+
+Consider a game shop that splits shoppers between two different shelf-sorting methods. Instead of the UI calculating the split, the server resolves it for a specific shopper via `features.snapshot`, and `FeatureProvider` publishes that set. The `Shelf` component then simply reads its assigned variant. If Sam buckets into `popular` and Mika into `newest`, neither component has to perform the resolution logic themselves.
+
+To ensure consistency, the provider takes the shopper's targeting context alongside the set. It publishes the shipped decisions either way, and it re-resolves them against that context to check them; consequently, a provider handed no `targetingKey` reports every weighted assignment as one it cannot reproduce. The context the server resolved with is the context the provider needs.
+
+The following block runs in the package's test suite, where each `// ->` comment denotes the expression's value.
+
+<!-- #region server-render -->
+
+```tsx @import.meta.vitest
+/** @jsxRuntime classic */
+import * as React from 'react';
+// ---cut---
+import { createFeatures } from '@evanion/feature';
+import type { DecisionSet } from '@evanion/feature';
+import { FeatureProvider, useVariant } from '@evanion/react-feature';
+import { useMemo } from 'react';
+import type { ReactNode } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+
+// app/features.ts, imported by the server and by the client bundle. A store
+// carries functions, so it reaches a client module as an import and never as a
+// prop.
+const features = createFeatures([
+  {
+    key: 'shelf-sort',
+    enabled: true,
+    variants: [
+      { name: 'newest', weight: 50 },
+      { name: 'popular', weight: 50 },
+    ],
+  },
+]);
+
+type ShopDecisions = DecisionSet<{
+  'shelf-sort': { variant: 'newest' | 'popular' };
+}>;
+
+// app/shelf.tsx, a client module ('use client')
+function Shelf() {
+  const { variant } = useVariant('shelf-sort');
+
+  // A feature that resolved off carries no variant, so the shop's own order
+  // answers that case and neither arm of the split does.
+  if (variant === undefined) return <p>Shop order</p>;
+
+  return <p>{variant === 'popular' ? 'Most played first' : 'Newest first'}</p>;
+}
+
+// app/flags.tsx, a client module ('use client')
+function ShopFlags({
+  shopperId,
+  decisions,
+  children,
+}: {
+  shopperId: string;
+  decisions: ShopDecisions;
+  children: ReactNode;
+}) {
+  // The provider re-resolves the shipped set to check it, so it needs the
+  // field the server bucketed on. A provider mounted without `targetingKey`
+  // publishes the shipped variant and reports it as one it cannot reproduce.
+  // `useMemo` holds the object across renders, which the provider's own memo
+  // reads as the same context.
+  const context = useMemo(() => ({ targetingKey: shopperId }), [shopperId]);
+
+  return (
+    <FeatureProvider
+      features={features}
+      context={context}
+      decisions={decisions}
+    >
+      {children}
+    </FeatureProvider>
+  );
+}
+
+// app/page.tsx, on the server, per request
+const shelfFor = (shopperId: string) => {
+  const decisions = features.snapshot({ targetingKey: shopperId });
+
+  // The framework serialises this prop on its way into the client module.
+  // React's flight serializer and Astro's `devalue` carry the `Date` a window
+  // condition's `failed.value` can hold, and `JSON.stringify` by hand sends a
+  // string in its place.
+  return renderToStaticMarkup(
+    <ShopFlags shopperId={shopperId} decisions={decisions}>
+      <Shelf />
+    </ShopFlags>,
+  );
+};
+
+shelfFor('sam'); // -> '<p>Most played first</p>'
+shelfFor('mika'); // -> '<p>Newest first</p>'
+```
+
+<!-- #endregion server-render -->
+
+## Key Features
+
+`@evanion/react-feature` provides the following capabilities:
+
+- 🧩 **Zero Prop-Drilling**: Components name the key they care about and read the decision from the provider above them.
+- 🕓 **One Instant Per Render**: A set a render resolved states the instant it was created. The provider reads that instant as the default for anything it resolves itself, ensuring no two components in one tree straddle a time window.
+- ⚡ **Local Reads**: Hooks read decisions already held by the provider, so variant switches never wait on network requests.
+- 🛠️ **Type-Safety**: `createFeatureContext(features)` returns a provider and hooks bound to one store's schema. Misspelled keys trigger compile errors, and variants are constrained to the union declared by the store.
+- 🧬 **Divergence Reports**: When handed a shipped set, a provider compares the config version against the store. It names decisions it cannot reproduce via `onDivergence`. Where the set and the store each carry a config version and the two differ, `onVersionMismatch` decides whether the tree renders the shipped set or a local re-resolution. A store built from a bare definitions array carries no version, so a provider over one reports `unversioned` and keeps the shipped set whatever `onVersionMismatch` asks for. Build both sides from a document that carries a version to make the choice available.
+- 📦 **Lightweight Footprint**: The package is ESM only and requires Node 20 or newer. Its only peer dependency is React 18 or 19, with `@evanion/feature` pinned as a dependency.
+
+## Installation
+
+Note: This package is not on npm yet. Because `package.json` carries `private: true`, `npm install @evanion/react-feature` does not resolve until the first version is published.
+
+```bash
+npm install @evanion/react-feature @evanion/feature
+```
+
+## Documentation
+
+To master the implementation and explore worked examples, visit the full documentation site:
+
+👉 **[docs.evanion.com/react-feature](https://docs.evanion.com/react-feature/)**
+
+The `@evanion/react-feature` hooks operate by reading a shared model of features, rules, variants, and decision sets. Because this model is defined in the core package, its detailed documentation is located here:
+
+👉 **[docs.evanion.com/feature](https://docs.evanion.com/feature/)**
+
+## License
+
+MIT

package/dist/hydrate.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Whether this bundle is a production one.
+ *
+ * `process` is a Node global. This package ships as plain ESM with no bundling
+ * step and no shim, so a browser loading `@evanion/react-feature` through an
+ * import map holds no `process` and reading one raises a `ReferenceError`, and
+ * a shim that supplies `process` without `env` raises a `TypeError`. Either
+ * one raises out of the provider's `useMemo`, so the whole tree fails to
+ * mount over a question about a bundle flag.
+ *
+ * The member chain is written out whole because a bundler's `define` matches
+ * the text `process.env.NODE_ENV` and substitutes the string. A guard that
+ * read `process.env` into a local first would defeat that substitution and
+ * leave a production bundle running the development diff. `try` keeps the text
+ * a bundler replaces and still answers for a runtime that defines neither
+ * half.
+ *
+ * A runtime that answers neither half answers `true`, because this read gates
+ * work and not a message. § 4 requires the development diff to stay out of
+ * production, and the runtime that cannot be read is a plain ESM deployment,
+ * which is as often a served production page as a developer's machine. The
+ * diff costs a second `features.resolve` per mount, a second `'resolve'` event
+ * on a store built with `observe`, and a `'decision-differs'` report for every
+ * key an observer then has to triage. A developer who wants the diff in a
+ * runtime with no `process` supplies one: `globalThis.process = { env: { NODE_ENV: 'development' } }`
+ * ahead of the provider's first render answers the read.
+ *
+ * `createEmitter` takes the other side for the same read
+ * (`observe.ts:290-294`), and it gates a `console.warn` that costs a line of
+ * output.
+ */
+export declare function production(): boolean;
+//# sourceMappingURL=hydrate.d.ts.map

package/dist/hydrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydrate.d.ts","sourceRoot":"","sources":["../src/hydrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAMpC"}

package/dist/index.d.ts

@@ -0,0 +1,254 @@
+import { ReactElement, ReactNode } from 'react';
+import { Decision, Decisions, DecisionSet, DivergenceObserver, EvaluationContext, FeatureKey, Features, FrozenWhenObserved, Schema, VariantInfo, VersionMismatchPolicy } from '@evanion/feature';
+/**
+ * The document types, re-exported so a component file imports one specifier.
+ *
+ * A React application that holds a store and reloads it from a poller writes
+ * the handler beside the component, and that file names `ReloadResult` and
+ * `FeatureConfig`. Types only: `serializeConfig`, `configDigest`,
+ * `validateConfig` and `parseFeatureConfig` stay on the core entry, because a
+ * component calling one of them holds configuration in a render tree and
+ * reaches for the core.
+ */
+export type { BaseFieldType, ConfigEnvelope, ConfigIssue, ConfigIssueCode, ContextSchema, FeatureConfig, FeatureSchema, FeatureShape, FieldType, JsonValue, ReloadResult, SerializedAttributeCondition, SerializedCondition, SerializedDefinition, SerializedInstant, SerializedRule, SerializedVariantSpec, SerializedWindowCondition, ValidationResult, ValueShape, } from '@evanion/feature';
+/**
+ * The core types this package's own public declarations name, re-exported for
+ * the reason the document types above are: one specifier per component file.
+ *
+ * `FeatureProviderProps` names `Features`, `EvaluationContext` and
+ * `DecisionSet`. `BoundFeatureProviderProps` names `Features`. `BoundVariant`
+ * names `Decisions`. `FeatureContext` names `Decisions`, `FeatureKey` and
+ * `FrozenWhenObserved`. {@link AnyDecisions} names `Decision` and
+ * `FeatureKey`. `Schema` is the default `FeatureProviderProps` gives its
+ * schema parameter, and `VariantInfo` is the constraint every one of those
+ * declarations writes. A reader who annotates one prop reached two specifiers
+ * before this clause: `@evanion/react-feature` for the prop type and
+ * `@evanion/feature` for the type inside it.
+ *
+ * Types only. The core's values stay on the core entry, which
+ * `entry-surface.spec.tsx` holds this package's module namespace to.
+ */
+export type { Decision, Decisions, EvaluationContext, FeatureKey, Features, FrozenWhenObserved, Schema, VariantInfo, } from '@evanion/feature';
+/**
+ * What a provider publishes, at the erased types.
+ *
+ * Every `Decision<'cta', 'control' | 'blue', { label: string }>` assigns to
+ * `Decision<FeatureKey>` because `key`, `variant`, `value`, `blockedBy` and
+ * `cause` all sit in output position. A React context fixes its type when the
+ * context is created and cannot hold the schema a provider was given, so a
+ * provider widens to this once and the bound hooks narrow back.
+ *
+ * `Decision<FeatureKey>` and not `Decision`: the parameter defaults to `string`
+ * while its constraint admits a number, so a store keyed on a numeric enum
+ * produces a `Decision<7>` whose `key` does not assign to `Decision`'s. The
+ * widening only holds at the constraint.
+ */
+export type AnyDecisions = Readonly<Record<FeatureKey, Decision<FeatureKey>>>;
+export type { VersionMismatchPolicy } from '@evanion/feature';
+export type { DecisionOrigin, DecisionSet } from '@evanion/feature';
+export type { DivergenceObserver, DivergenceReport, DivergenceSide, } from '@evanion/feature';
+/**
+ * What {@link FeatureProvider} takes.
+ *
+ * `features` is required, because this provider holds no store of its own.
+ * {@link createFeatureContext} is the form that already holds one, and
+ * {@link BoundFeatureProviderProps} is what its provider takes.
+ *
+ * `S` is the store's schema, and it types `decisions` and `onDivergence` on
+ * the keys that store declares, so a set another store resolved is a compile
+ * error at the mount. The hooks underneath read {@link AnyDecisions} whatever
+ * `S` is, which is the erasure a React context imposes and the reason the
+ * factory exists.
+ */
+export interface FeatureProviderProps<S extends Record<keyof S, VariantInfo | never> = Schema> {
+    features: Features<S>;
+    /**
+     * The evaluation context. Resolution is memoised on this object's identity, so
+     * pass a stable reference -- an object literal written inline re-resolves on
+     * every render.
+     *
+     * Leaving `now` out means "the clock at the moment this context was first
+     * resolved". A component tree that must agree with a server render should pass
+     * `now` explicitly.
+     */
+    context?: EvaluationContext;
+    /**
+     * Decisions resolved elsewhere, as the versioned set `Features.snapshot`
+     * produces. A server render hands the client the set it resolved, and this
+     * provider publishes it.
+     *
+     * The set states the config version it was resolved under and the instant it
+     * was resolved at, so this provider can tell whether the two processes hold
+     * one configuration and can resolve the remainder at the server's instant.
+     */
+    decisions?: DecisionSet<S>;
+    /** Notified for every divergence this provider detects. Alters no decision. */
+    onDivergence?: DivergenceObserver<keyof S & FeatureKey>;
+    /**
+     * What to render when the shipped version is not the store's. Defaults to
+     * `'use-shipped'`.
+     *
+     * An application that runs no experiment and cares about revocation latency
+     * passes `'re-resolve'`.
+     */
+    onVersionMismatch?: VersionMismatchPolicy;
+    children?: ReactNode;
+}
+/**
+ * Publishes one store's decisions to every component under it.
+ *
+ * With `decisions` left out the provider resolves `features` against
+ * `context`, once per identity of the two. With a set supplied it publishes
+ * that set: the server rendered HTML from those decisions and counted an
+ * exposure for each variant it assigned, so a client answering differently
+ * makes an experiment result wrong by an amount no analysis recovers. A
+ * version mismatch renders the shipped set unless `onVersionMismatch` names
+ * `'re-resolve'`.
+ *
+ * Decides nothing itself. `@evanion/feature` resolves, and this component
+ * writes the answer into React context and renders `children`.
+ *
+ * Every hook this package exports throws outside a provider, and the message
+ * names the provider and the package. {@link useFeature},
+ * {@link useFeatureEnabled} and {@link useVariant} throw for a key the
+ * published decisions do not carry.
+ */
+export declare function FeatureProvider<S extends Record<keyof S, VariantInfo | never>>({ features, context, decisions, onDivergence, onVersionMismatch, children, }: FeatureProviderProps<S>): import('react').JSX.Element;
+/** Every resolved decision, at the erased types. */
+export declare function useFeatures(): AnyDecisions;
+/**
+ * One feature's decision, explanation included.
+ *
+ * Throws for a key that is not configured. {@link createFeatureContext} binds
+ * this hook to one store's keys, so a component under a bound provider names a
+ * key the compiler checks.
+ */
+export declare function useFeature(key: FeatureKey): Decision<FeatureKey>;
+/** One feature's decision as a boolean. */
+export declare function useFeatureEnabled(key: FeatureKey): boolean;
+/**
+ * One feature's assigned variant and its value.
+ *
+ * A reader over the decision `useFeature` already returns. Both are absent for
+ * a feature that resolved off and for a feature declaring no variants, so
+ * calling code handles off before it switches on a name.
+ *
+ * Throws for a key the provider does not carry, which `useFeature` does for the
+ * same reason: a silent `undefined` would make a typo indistinguishable from a
+ * feature nobody assigned.
+ */
+export declare function useVariant(key: FeatureKey): Pick<Decision, 'variant' | 'value'>;
+/**
+ * Props of the provider {@link createFeatureContext} returns.
+ *
+ * `features` is optional here and required on {@link FeatureProvider}: the
+ * factory already holds a store, and a mount that supplies the context alone is
+ * the common one. Pass it to resolve a different store with the same schema --
+ * a per-tenant configuration, or the copy a browser rebuilt from JSON.
+ *
+ * `Frozen` comes from the factory's own store, and a substituted store carries
+ * the same parameter. The hooks type their decisions off the factory's answer,
+ * so a store that freezes what it resolves under a factory built from a store
+ * that freezes nothing would publish frozen decisions to hooks promising the
+ * mutable form. The parameter here turns that mount into a compile error.
+ */
+export interface BoundFeatureProviderProps<S extends Record<keyof S, VariantInfo | never>, Frozen extends boolean = boolean> {
+    features?: Features<S, Frozen>;
+    context?: EvaluationContext;
+    /**
+     * Decisions resolved elsewhere, as the versioned set `Features.snapshot`
+     * produces. A server render hands the client the set it resolved, and this
+     * provider publishes it.
+     */
+    decisions?: DecisionSet<S, Frozen>;
+    /** Notified for every divergence this provider detects. Alters no decision. */
+    onDivergence?: DivergenceObserver<keyof S & FeatureKey>;
+    /**
+     * What to render when the shipped version is not the store's. Defaults to
+     * `'use-shipped'`.
+     */
+    onVersionMismatch?: VersionMismatchPolicy;
+    children?: ReactNode;
+}
+/**
+ * What {@link FeatureContext.useVariant} answers for one key.
+ *
+ * The `[S[K]] extends [never]` guard is what keeps a variant-free feature
+ * honest. `never` is a subtype of every type, so the `infer` branch alone would
+ * read `variant` off a decision that dropped the property and infer `unknown`.
+ * The tuple wrap suppresses distribution and asks the question the branch
+ * means to ask. Both fields come off `Decisions<S>[K]`, so this and the
+ * decision for the same key cannot drift apart.
+ */
+export type BoundVariant<S extends Record<keyof S, VariantInfo | never>, K extends keyof S> = [S[K]] extends [never] ? {
+    variant?: undefined;
+    value?: undefined;
+} : Decisions<S>[K] extends {
+    variant?: infer V;
+    value?: infer T;
+} ? {
+    variant?: V;
+    value?: T;
+} : never;
+/**
+ * A provider and hooks bound to one store's schema.
+ *
+ * Each hook names `keyof S`, so a misspelled key is a compile error and the
+ * variant a reader switches on is the union that store declares.
+ *
+ * `Frozen` carries the store's own answer. A store built with no observer
+ * freezes nothing and its hooks answer the mutable decisions, a store built
+ * with one answers the deeply readonly form, and a store whose observation the
+ * compiler cannot settle answers the union of the two.
+ */
+export interface FeatureContext<S extends Record<keyof S, VariantInfo | never>, Frozen extends boolean = boolean> {
+    FeatureProvider(props: BoundFeatureProviderProps<S, Frozen>): ReactElement;
+    useFeatures(): FrozenWhenObserved<Frozen, Decisions<S>>;
+    useFeature<K extends keyof S & FeatureKey>(key: K): FrozenWhenObserved<Frozen, Decisions<S>[K]>;
+    useFeatureEnabled<K extends keyof S & FeatureKey>(key: K): boolean;
+    useVariant<K extends keyof S & FeatureKey>(key: K): BoundVariant<S, K>;
+}
+/**
+ * Binds a store's schema to a provider and a set of hooks.
+ *
+ * `createFeatures([...])` returns a `Features<S>` whose keys and variant types the
+ * definitions supplied, and the store loses all of it the moment the value
+ * reaches a context: `createContext` fixes its type when the context
+ * is made, and `useContext` hands a hook that fixed type whatever the provider
+ * above it was given. A function that makes the context and the hooks together
+ * is where `S` can be held, so this is a factory and not a generic provider.
+ *
+ * `S` comes from the argument. Nothing is restated at the call site, and a
+ * store whose configuration arrived as JSON yields the wide hooks, which are
+ * the ones {@link useFeature} and its siblings already export.
+ *
+ * Each call makes its own context, so two stores nest and each set of hooks
+ * reads its own provider. The returned provider also publishes to the shared
+ * context, so a component calling the package's own {@link useFeature}
+ * underneath it reads the same decisions.
+ *
+ * A browser decides what a reader sees and gates nothing. A key that
+ * type-checks here says the store this was built from declares it, and says
+ * nothing about the decisions the provider was handed at runtime.
+ *
+ * @example
+ * ```tsx
+ * const features = createFeatures([
+ *   {
+ *     key: 'cta',
+ *     enabled: true,
+ *     variants: [
+ *       { name: 'control', weight: 50 },
+ *       { name: 'blue', weight: 50, value: { label: 'Get it' } },
+ *     ],
+ *   },
+ * ]);
+ *
+ * const { FeatureProvider, useVariant } = createFeatureContext(features);
+ *
+ * <FeatureProvider context={{ targetingKey: user.id }}>…</FeatureProvider>;
+ * useVariant('cta').variant;  // 'control' | 'blue' | undefined
+ * ```
+ */
+export declare function createFeatureContext<S extends Record<keyof S, VariantInfo | never>, Frozen extends boolean = boolean>(features: Features<S, Frozen>): FeatureContext<S, Frozen>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,118 @@
+"use client";
+import { createContext as e, useContext as t, useMemo as n, useState as r } from "react";
+import { adoptDecisions as i, reportDivergence as a } from "@evanion/feature";
+import { jsx as o } from "react/jsx-runtime";
+//#region src/hydrate.ts
+function s() {
+	try {
+		return process.env.NODE_ENV === "production";
+	} catch {
+		return !0;
+	}
+}
+//#endregion
+//#region src/index.tsx
+function c(e) {
+	return e;
+}
+var l = e(null);
+function u(e) {
+	let n = t(e);
+	if (!n) throw Error("useFeatures must be called inside a <FeatureProvider> (from @evanion/react-feature)");
+	return n;
+}
+function d(e, t) {
+	let n = Object.prototype.hasOwnProperty.call(e, t) ? e[t] : void 0;
+	if (!n) throw Error(`feature "${String(t)}" is not configured in this <FeatureProvider>`);
+	return n;
+}
+var f = Object.freeze([]), p = "use-shipped";
+function m(e, t, o, l, u) {
+	let d = l ?? p, m = u !== void 0, h = !s(), g = n(() => {
+		let n = [];
+		return {
+			value: { decisions: c(i(e, o, {
+				context: t,
+				onVersionMismatch: d,
+				onDivergence: m ? (e) => n.push(e) : void 0,
+				compare: h
+			})) },
+			reports: n
+		};
+	}, [
+		e,
+		t,
+		o,
+		d,
+		m,
+		h
+	]), [_, v] = r(f);
+	if (_ !== g.reports) {
+		v(g.reports);
+		for (let e of g.reports) a(u, e);
+	}
+	return g.value;
+}
+function h({ features: e, context: t, decisions: n, onDivergence: r, onVersionMismatch: i, children: a }) {
+	let s = m(e, t, n, i, r);
+	return /* @__PURE__ */ o(l.Provider, {
+		value: s,
+		children: a
+	});
+}
+function g() {
+	return u(l).decisions;
+}
+function _(e) {
+	return d(g(), e);
+}
+function v(e) {
+	return _(e).enabled;
+}
+function y(e) {
+	let t = _(e);
+	return {
+		variant: t.variant,
+		value: t.value
+	};
+}
+function b(e) {
+	return e;
+}
+function x(e, t) {
+	return e[t];
+}
+function S(t) {
+	let n = e(null);
+	return {
+		FeatureProvider({ features: e, context: r, decisions: i, onDivergence: a, onVersionMismatch: s, children: c }) {
+			let u = m(e ?? t, r, i, s, a);
+			return /* @__PURE__ */ o(l.Provider, {
+				value: u,
+				children: /* @__PURE__ */ o(n.Provider, {
+					value: u,
+					children: c
+				})
+			});
+		},
+		useFeatures() {
+			return b(u(n).decisions);
+		},
+		useFeature(e) {
+			let t = u(n).decisions;
+			return d(t, e), x(t, e);
+		},
+		useFeatureEnabled(e) {
+			return d(u(n).decisions, e).enabled;
+		},
+		useVariant(e) {
+			let t = d(u(n).decisions, e);
+			return {
+				variant: t.variant,
+				value: t.value
+			};
+		}
+	};
+}
+//#endregion
+export { h as FeatureProvider, S as createFeatureContext, _ as useFeature, v as useFeatureEnabled, g as useFeatures, y as useVariant };

package/package.json

@@ -1,10 +1,65 @@
 {
   "name": "@evanion/react-feature",
-  "version": "0.0.0",
-  "description": "Placeholder. Install a released version.",
-  "license": "MIT",
+  "version": "0.1.0",
+  "description": "The React binding for @evanion/feature: a provider and hooks over an already-built feature store.",
+  "keywords": [
+    "react",
+    "feature-flags",
+    "feature-toggles",
+    "rollout",
+    "variants",
+    "hooks",
+    "typescript"
+  ],
+  "homepage": "https://github.com/Evanion/libraries/tree/main/libs/react-feature#readme",
+  "bugs": {
+    "url": "https://github.com/Evanion/libraries/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Evanion/libraries.git"
+    "url": "git+https://github.com/Evanion/libraries.git",
+    "directory": "libs/react-feature"
+  },
+  "license": "MIT",
+  "author": "Mikael Pettersson",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@evanion/source": "./src/index.tsx",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.tsbuildinfo",
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*",
+    "!src/**/*.test-d.*",
+    "!src/test-setup.ts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@evanion/feature": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@evanion/doc-examples": "*"
   }
 }

package/src/hydrate.ts

@@ -0,0 +1,38 @@
+/**
+ * Whether this bundle is a production one.
+ *
+ * `process` is a Node global. This package ships as plain ESM with no bundling
+ * step and no shim, so a browser loading `@evanion/react-feature` through an
+ * import map holds no `process` and reading one raises a `ReferenceError`, and
+ * a shim that supplies `process` without `env` raises a `TypeError`. Either
+ * one raises out of the provider's `useMemo`, so the whole tree fails to
+ * mount over a question about a bundle flag.
+ *
+ * The member chain is written out whole because a bundler's `define` matches
+ * the text `process.env.NODE_ENV` and substitutes the string. A guard that
+ * read `process.env` into a local first would defeat that substitution and
+ * leave a production bundle running the development diff. `try` keeps the text
+ * a bundler replaces and still answers for a runtime that defines neither
+ * half.
+ *
+ * A runtime that answers neither half answers `true`, because this read gates
+ * work and not a message. § 4 requires the development diff to stay out of
+ * production, and the runtime that cannot be read is a plain ESM deployment,
+ * which is as often a served production page as a developer's machine. The
+ * diff costs a second `features.resolve` per mount, a second `'resolve'` event
+ * on a store built with `observe`, and a `'decision-differs'` report for every
+ * key an observer then has to triage. A developer who wants the diff in a
+ * runtime with no `process` supplies one: `globalThis.process = { env: { NODE_ENV: 'development' } }`
+ * ahead of the provider's first render answers the read.
+ *
+ * `createEmitter` takes the other side for the same read
+ * (`observe.ts:290-294`), and it gates a `console.warn` that costs a line of
+ * output.
+ */
+export function production(): boolean {
+  try {
+    return process.env.NODE_ENV === 'production';
+  } catch {
+    return true;
+  }
+}

package/src/index.tsx

@@ -0,0 +1,615 @@
+'use client';
+
+/**
+ * The React adapter: a provider and hooks over an already-built store.
+ *
+ * `'use client'` is a per-module directive, and this module carries it. The
+ * directive is why the adapter is a package of its own: `@evanion/feature`
+ * imports no framework, declares no peer and must not carry the directive,
+ * which a single module published from both sides cannot do.
+ *
+ * Evaluation itself lives in the core. Nothing here decides anything.
+ */
+
+import { createContext, useContext, useMemo, useState } from 'react';
+import type { Context, ReactElement, ReactNode } from 'react';
+import { production } from './hydrate.js';
+import { adoptDecisions, reportDivergence } from '@evanion/feature';
+import type {
+  Decision,
+  Decisions,
+  DecisionSet,
+  DeepReadonly,
+  DivergenceObserver,
+  DivergenceReport,
+  EvaluationContext,
+  FeatureKey,
+  Features,
+  FrozenWhenObserved,
+  Schema,
+  VariantInfo,
+  VersionMismatchPolicy,
+} from '@evanion/feature';
+
+/**
+ * The document types, re-exported so a component file imports one specifier.
+ *
+ * A React application that holds a store and reloads it from a poller writes
+ * the handler beside the component, and that file names `ReloadResult` and
+ * `FeatureConfig`. Types only: `serializeConfig`, `configDigest`,
+ * `validateConfig` and `parseFeatureConfig` stay on the core entry, because a
+ * component calling one of them holds configuration in a render tree and
+ * reaches for the core.
+ */
+export type {
+  BaseFieldType,
+  ConfigEnvelope,
+  ConfigIssue,
+  ConfigIssueCode,
+  ContextSchema,
+  FeatureConfig,
+  FeatureSchema,
+  FeatureShape,
+  FieldType,
+  JsonValue,
+  ReloadResult,
+  SerializedAttributeCondition,
+  SerializedCondition,
+  SerializedDefinition,
+  SerializedInstant,
+  SerializedRule,
+  SerializedVariantSpec,
+  SerializedWindowCondition,
+  ValidationResult,
+  ValueShape,
+} from '@evanion/feature';
+
+/**
+ * The core types this package's own public declarations name, re-exported for
+ * the reason the document types above are: one specifier per component file.
+ *
+ * `FeatureProviderProps` names `Features`, `EvaluationContext` and
+ * `DecisionSet`. `BoundFeatureProviderProps` names `Features`. `BoundVariant`
+ * names `Decisions`. `FeatureContext` names `Decisions`, `FeatureKey` and
+ * `FrozenWhenObserved`. {@link AnyDecisions} names `Decision` and
+ * `FeatureKey`. `Schema` is the default `FeatureProviderProps` gives its
+ * schema parameter, and `VariantInfo` is the constraint every one of those
+ * declarations writes. A reader who annotates one prop reached two specifiers
+ * before this clause: `@evanion/react-feature` for the prop type and
+ * `@evanion/feature` for the type inside it.
+ *
+ * Types only. The core's values stay on the core entry, which
+ * `entry-surface.spec.tsx` holds this package's module namespace to.
+ */
+export type {
+  Decision,
+  Decisions,
+  EvaluationContext,
+  FeatureKey,
+  Features,
+  FrozenWhenObserved,
+  Schema,
+  VariantInfo,
+} from '@evanion/feature';
+
+/**
+ * What a provider publishes, at the erased types.
+ *
+ * Every `Decision<'cta', 'control' | 'blue', { label: string }>` assigns to
+ * `Decision<FeatureKey>` because `key`, `variant`, `value`, `blockedBy` and
+ * `cause` all sit in output position. A React context fixes its type when the
+ * context is created and cannot hold the schema a provider was given, so a
+ * provider widens to this once and the bound hooks narrow back.
+ *
+ * `Decision<FeatureKey>` and not `Decision`: the parameter defaults to `string`
+ * while its constraint admits a number, so a store keyed on a numeric enum
+ * produces a `Decision<7>` whose `key` does not assign to `Decision`'s. The
+ * widening only holds at the constraint.
+ */
+export type AnyDecisions = Readonly<Record<FeatureKey, Decision<FeatureKey>>>;
+
+export type { VersionMismatchPolicy } from '@evanion/feature';
+export type { DecisionOrigin, DecisionSet } from '@evanion/feature';
+export type {
+  DivergenceObserver,
+  DivergenceReport,
+  DivergenceSide,
+} from '@evanion/feature';
+
+interface FeatureContextValue {
+  decisions: AnyDecisions;
+}
+
+/**
+ * Reads what `resolve` answered at the erased type.
+ *
+ * A store carrying an observer answers the deeply readonly form of
+ * `Decisions<S>`, and `DeepReadonly` does not reduce over a schema the compiler
+ * has not resolved, so neither form assigns to {@link AnyDecisions} on its own.
+ * Both hold one decision per key, and the context reads those decisions and
+ * writes none of them.
+ */
+function erased<S extends Record<keyof S, VariantInfo | never>>(
+  resolved: Decisions<S> | DeepReadonly<Decisions<S>>,
+): AnyDecisions {
+  return resolved as AnyDecisions;
+}
+
+const SharedContext = createContext<FeatureContextValue | null>(null);
+
+function useContextValue(
+  context: Context<FeatureContextValue | null>,
+): FeatureContextValue {
+  const value = useContext(context);
+  if (!value) {
+    throw new Error(
+      'useFeatures must be called inside a <FeatureProvider> (from @evanion/react-feature)',
+    );
+  }
+  return value;
+}
+
+/**
+ * One decision, or a throw naming the key.
+ *
+ * A bare index walks the prototype chain, so a key of `constructor` or
+ * `toString` resolves to a function off `Object.prototype` and passes the
+ * configured check below as a decision object. This asks the own-property
+ * question first.
+ *
+ * A silent `false` would make a typo indistinguishable from a feature that is
+ * off, which is the failure mode flag systems are worst at.
+ */
+function requireDecision(
+  decisions: AnyDecisions,
+  key: FeatureKey,
+): Decision<FeatureKey> {
+  const decision = Object.prototype.hasOwnProperty.call(decisions, key)
+    ? decisions[key]
+    : undefined;
+  if (!decision) {
+    throw new Error(
+      `feature "${String(key)}" is not configured in this <FeatureProvider>`,
+    );
+  }
+  return decision;
+}
+
+/**
+ * What {@link FeatureProvider} takes.
+ *
+ * `features` is required, because this provider holds no store of its own.
+ * {@link createFeatureContext} is the form that already holds one, and
+ * {@link BoundFeatureProviderProps} is what its provider takes.
+ *
+ * `S` is the store's schema, and it types `decisions` and `onDivergence` on
+ * the keys that store declares, so a set another store resolved is a compile
+ * error at the mount. The hooks underneath read {@link AnyDecisions} whatever
+ * `S` is, which is the erasure a React context imposes and the reason the
+ * factory exists.
+ */
+export interface FeatureProviderProps<
+  S extends Record<keyof S, VariantInfo | never> = Schema,
+> {
+  features: Features<S>;
+  /**
+   * The evaluation context. Resolution is memoised on this object's identity, so
+   * pass a stable reference -- an object literal written inline re-resolves on
+   * every render.
+   *
+   * Leaving `now` out means "the clock at the moment this context was first
+   * resolved". A component tree that must agree with a server render should pass
+   * `now` explicitly.
+   */
+  context?: EvaluationContext;
+  /**
+   * Decisions resolved elsewhere, as the versioned set `Features.snapshot`
+   * produces. A server render hands the client the set it resolved, and this
+   * provider publishes it.
+   *
+   * The set states the config version it was resolved under and the instant it
+   * was resolved at, so this provider can tell whether the two processes hold
+   * one configuration and can resolve the remainder at the server's instant.
+   */
+  decisions?: DecisionSet<S>;
+  /** Notified for every divergence this provider detects. Alters no decision. */
+  onDivergence?: DivergenceObserver<keyof S & FeatureKey>;
+  /**
+   * What to render when the shipped version is not the store's. Defaults to
+   * `'use-shipped'`.
+   *
+   * An application that runs no experiment and cares about revocation latency
+   * passes `'re-resolve'`.
+   */
+  onVersionMismatch?: VersionMismatchPolicy;
+  children?: ReactNode;
+}
+
+/** The pass no render has delivered, so a mount delivers its own. */
+const UNDELIVERED: readonly never[] = Object.freeze([]);
+
+/**
+ * What a provider does about a version mismatch where an application states
+ * nothing.
+ *
+ * One constant for both providers. A wrong experiment result is the failure
+ * that produces no error, no warning and no way to notice afterwards, and a
+ * stale kill switch produces a complaint within minutes (§ 3), so the two
+ * providers cannot hold different answers and a second literal is a second
+ * answer waiting to drift.
+ */
+const ON_MISMATCH: VersionMismatchPolicy = 'use-shipped';
+
+/**
+ * The value a provider publishes, with one pass of the checks per set of
+ * inputs and every report of that pass handed to the observer the current
+ * render holds.
+ *
+ * § 4 requires both checks to report before React reconciles, so
+ * `adoptDecisions` runs inside the memo body and the memo's dependency
+ * list decides how often each check runs. An observer prop written inline is a
+ * new function on every render, and a memo depending on its identity re-ran
+ * the sufficiency pass, re-resolved the store for the diff and re-sent every
+ * report for a parent re-rendering on a keystroke. § 4 budgets one pass of
+ * each per mount and § 3 reports `'unversioned'` once. The memo therefore
+ * reads the prop's presence and not its identity, and presence is what
+ * `adoptDecisions` asks about: it resolves for the diff only where
+ * something reads the result.
+ *
+ * The memo collects rather than delivers, because the observer a pass belongs
+ * to is the prop of the render that produced it and the memo body holds the
+ * prop of the render that last re-ran. A provider whose `onDivergence` turns
+ * from `undefined` into a function re-runs both checks in that render, and
+ * every report of that pass belongs to the function that just arrived. The
+ * same holds for a render that swaps one sink for another.
+ *
+ * The state update is what stops a second delivery. Every pass of the memo
+ * builds its own array, so the array identity names the pass, and a render
+ * that delivers writes it back as state. React re-renders this component with
+ * that state before it commits, the memo holds its result, and the comparison
+ * then matches. A re-render that recomputes nothing reaches the same array and
+ * delivers nothing.
+ *
+ * React invokes a render twice under `StrictMode` and discards the first,
+ * which sends every report of a pass twice. An observer counts divergences and
+ * alters nothing (§ 7), so the duplicate costs a console line.
+ */
+function usePublished<S extends Record<keyof S, VariantInfo | never>>(
+  features: Features<S>,
+  context: EvaluationContext | undefined,
+  decisions: DecisionSet<S> | undefined,
+  onVersionMismatch: VersionMismatchPolicy | undefined,
+  onDivergence: DivergenceObserver<keyof S & FeatureKey> | undefined,
+): FeatureContextValue {
+  const policy = onVersionMismatch ?? ON_MISMATCH;
+  const installed = onDivergence !== undefined;
+  const compare = !production();
+  const published = useMemo(() => {
+    const reports: DivergenceReport<keyof S & FeatureKey>[] = [];
+    const value: FeatureContextValue = {
+      decisions: erased(
+        adoptDecisions(features, decisions, {
+          context,
+          onVersionMismatch: policy,
+          onDivergence: installed
+            ? (report) => reports.push(report)
+            : undefined,
+          compare,
+        }),
+      ),
+    };
+    return { value, reports };
+  }, [features, context, decisions, policy, installed, compare]);
+
+  const [delivered, setDelivered] =
+    useState<readonly DivergenceReport<keyof S & FeatureKey>[]>(UNDELIVERED);
+  if (delivered !== published.reports) {
+    setDelivered(published.reports);
+    for (const report of published.reports) {
+      reportDivergence(onDivergence, report);
+    }
+  }
+
+  return published.value;
+}
+
+/**
+ * Publishes one store's decisions to every component under it.
+ *
+ * With `decisions` left out the provider resolves `features` against
+ * `context`, once per identity of the two. With a set supplied it publishes
+ * that set: the server rendered HTML from those decisions and counted an
+ * exposure for each variant it assigned, so a client answering differently
+ * makes an experiment result wrong by an amount no analysis recovers. A
+ * version mismatch renders the shipped set unless `onVersionMismatch` names
+ * `'re-resolve'`.
+ *
+ * Decides nothing itself. `@evanion/feature` resolves, and this component
+ * writes the answer into React context and renders `children`.
+ *
+ * Every hook this package exports throws outside a provider, and the message
+ * names the provider and the package. {@link useFeature},
+ * {@link useFeatureEnabled} and {@link useVariant} throw for a key the
+ * published decisions do not carry.
+ */
+export function FeatureProvider<
+  S extends Record<keyof S, VariantInfo | never>,
+>({
+  features,
+  context,
+  decisions,
+  onDivergence,
+  onVersionMismatch,
+  children,
+}: FeatureProviderProps<S>) {
+  const value = usePublished(
+    features,
+    context,
+    decisions,
+    onVersionMismatch,
+    onDivergence,
+  );
+
+  return (
+    <SharedContext.Provider value={value}>{children}</SharedContext.Provider>
+  );
+}
+
+/** Every resolved decision, at the erased types. */
+export function useFeatures(): AnyDecisions {
+  return useContextValue(SharedContext).decisions;
+}
+
+/**
+ * One feature's decision, explanation included.
+ *
+ * Throws for a key that is not configured. {@link createFeatureContext} binds
+ * this hook to one store's keys, so a component under a bound provider names a
+ * key the compiler checks.
+ */
+export function useFeature(key: FeatureKey): Decision<FeatureKey> {
+  return requireDecision(useFeatures(), key);
+}
+
+/** One feature's decision as a boolean. */
+export function useFeatureEnabled(key: FeatureKey): boolean {
+  return useFeature(key).enabled;
+}
+
+/**
+ * One feature's assigned variant and its value.
+ *
+ * A reader over the decision `useFeature` already returns. Both are absent for
+ * a feature that resolved off and for a feature declaring no variants, so
+ * calling code handles off before it switches on a name.
+ *
+ * Throws for a key the provider does not carry, which `useFeature` does for the
+ * same reason: a silent `undefined` would make a typo indistinguishable from a
+ * feature nobody assigned.
+ */
+export function useVariant(
+  key: FeatureKey,
+): Pick<Decision, 'variant' | 'value'> {
+  const decision = useFeature(key);
+  return { variant: decision.variant, value: decision.value };
+}
+
+/**
+ * Props of the provider {@link createFeatureContext} returns.
+ *
+ * `features` is optional here and required on {@link FeatureProvider}: the
+ * factory already holds a store, and a mount that supplies the context alone is
+ * the common one. Pass it to resolve a different store with the same schema --
+ * a per-tenant configuration, or the copy a browser rebuilt from JSON.
+ *
+ * `Frozen` comes from the factory's own store, and a substituted store carries
+ * the same parameter. The hooks type their decisions off the factory's answer,
+ * so a store that freezes what it resolves under a factory built from a store
+ * that freezes nothing would publish frozen decisions to hooks promising the
+ * mutable form. The parameter here turns that mount into a compile error.
+ */
+export interface BoundFeatureProviderProps<
+  S extends Record<keyof S, VariantInfo | never>,
+  Frozen extends boolean = boolean,
+> {
+  features?: Features<S, Frozen>;
+  context?: EvaluationContext;
+  /**
+   * Decisions resolved elsewhere, as the versioned set `Features.snapshot`
+   * produces. A server render hands the client the set it resolved, and this
+   * provider publishes it.
+   */
+  decisions?: DecisionSet<S, Frozen>;
+  /** Notified for every divergence this provider detects. Alters no decision. */
+  onDivergence?: DivergenceObserver<keyof S & FeatureKey>;
+  /**
+   * What to render when the shipped version is not the store's. Defaults to
+   * `'use-shipped'`.
+   */
+  onVersionMismatch?: VersionMismatchPolicy;
+  children?: ReactNode;
+}
+
+/**
+ * What {@link FeatureContext.useVariant} answers for one key.
+ *
+ * The `[S[K]] extends [never]` guard is what keeps a variant-free feature
+ * honest. `never` is a subtype of every type, so the `infer` branch alone would
+ * read `variant` off a decision that dropped the property and infer `unknown`.
+ * The tuple wrap suppresses distribution and asks the question the branch
+ * means to ask. Both fields come off `Decisions<S>[K]`, so this and the
+ * decision for the same key cannot drift apart.
+ */
+export type BoundVariant<
+  S extends Record<keyof S, VariantInfo | never>,
+  K extends keyof S,
+> = [S[K]] extends [never]
+  ? { variant?: undefined; value?: undefined }
+  : Decisions<S>[K] extends { variant?: infer V; value?: infer T }
+    ? { variant?: V; value?: T }
+    : never;
+
+/**
+ * A provider and hooks bound to one store's schema.
+ *
+ * Each hook names `keyof S`, so a misspelled key is a compile error and the
+ * variant a reader switches on is the union that store declares.
+ *
+ * `Frozen` carries the store's own answer. A store built with no observer
+ * freezes nothing and its hooks answer the mutable decisions, a store built
+ * with one answers the deeply readonly form, and a store whose observation the
+ * compiler cannot settle answers the union of the two.
+ */
+export interface FeatureContext<
+  S extends Record<keyof S, VariantInfo | never>,
+  Frozen extends boolean = boolean,
+> {
+  FeatureProvider(props: BoundFeatureProviderProps<S, Frozen>): ReactElement;
+  useFeatures(): FrozenWhenObserved<Frozen, Decisions<S>>;
+  useFeature<K extends keyof S & FeatureKey>(
+    key: K,
+  ): FrozenWhenObserved<Frozen, Decisions<S>[K]>;
+  useFeatureEnabled<K extends keyof S & FeatureKey>(key: K): boolean;
+  useVariant<K extends keyof S & FeatureKey>(key: K): BoundVariant<S, K>;
+}
+
+/**
+ * Reads a bound provider's decisions at the schema the factory holds.
+ *
+ * This is the one place the erased value is narrowed. It holds because a bound
+ * context is created inside a single {@link createFeatureContext} call and
+ * written by exactly one component, whose props type every entry as one of the
+ * two forms of `Decisions<S>`.
+ *
+ * The answer follows the store. A provider fed by a store carrying an observer
+ * publishes frozen decisions, and a hook promising the mutable form there would
+ * let a component write a field the runtime refuses. The compiler resolves
+ * neither branch of `FrozenWhenObserved` while `Frozen` is a parameter, so the
+ * cast states the answer the two branches share.
+ */
+function atSchema<
+  S extends Record<keyof S, VariantInfo | never>,
+  Frozen extends boolean,
+>(decisions: AnyDecisions): FrozenWhenObserved<Frozen, Decisions<S>> {
+  return decisions as unknown as FrozenWhenObserved<Frozen, Decisions<S>>;
+}
+
+/**
+ * Reads one key off a bound provider's decisions, at the schema.
+ *
+ * `DeepReadonly<Decisions<S>>` is a conditional type the compiler cannot reduce
+ * while `S` is a parameter, so nothing indexes it by `K`. Indexing first and
+ * mapping the one decision answers the same type for a settled `S`.
+ */
+function decisionAtSchema<
+  S extends Record<keyof S, VariantInfo | never>,
+  K extends keyof S & FeatureKey,
+  Frozen extends boolean,
+>(
+  decisions: AnyDecisions,
+  key: K,
+): FrozenWhenObserved<Frozen, Decisions<S>[K]> {
+  return (decisions as Decisions<S>)[key] as unknown as FrozenWhenObserved<
+    Frozen,
+    Decisions<S>[K]
+  >;
+}
+
+/**
+ * Binds a store's schema to a provider and a set of hooks.
+ *
+ * `createFeatures([...])` returns a `Features<S>` whose keys and variant types the
+ * definitions supplied, and the store loses all of it the moment the value
+ * reaches a context: `createContext` fixes its type when the context
+ * is made, and `useContext` hands a hook that fixed type whatever the provider
+ * above it was given. A function that makes the context and the hooks together
+ * is where `S` can be held, so this is a factory and not a generic provider.
+ *
+ * `S` comes from the argument. Nothing is restated at the call site, and a
+ * store whose configuration arrived as JSON yields the wide hooks, which are
+ * the ones {@link useFeature} and its siblings already export.
+ *
+ * Each call makes its own context, so two stores nest and each set of hooks
+ * reads its own provider. The returned provider also publishes to the shared
+ * context, so a component calling the package's own {@link useFeature}
+ * underneath it reads the same decisions.
+ *
+ * A browser decides what a reader sees and gates nothing. A key that
+ * type-checks here says the store this was built from declares it, and says
+ * nothing about the decisions the provider was handed at runtime.
+ *
+ * @example
+ * ```tsx
+ * const features = createFeatures([
+ *   {
+ *     key: 'cta',
+ *     enabled: true,
+ *     variants: [
+ *       { name: 'control', weight: 50 },
+ *       { name: 'blue', weight: 50, value: { label: 'Get it' } },
+ *     ],
+ *   },
+ * ]);
+ *
+ * const { FeatureProvider, useVariant } = createFeatureContext(features);
+ *
+ * <FeatureProvider context={{ targetingKey: user.id }}>…</FeatureProvider>;
+ * useVariant('cta').variant;  // 'control' | 'blue' | undefined
+ * ```
+ */
+export function createFeatureContext<
+  S extends Record<keyof S, VariantInfo | never>,
+  Frozen extends boolean = boolean,
+>(features: Features<S, Frozen>): FeatureContext<S, Frozen> {
+  const BoundContext = createContext<FeatureContextValue | null>(null);
+
+  return {
+    FeatureProvider({
+      features: given,
+      context,
+      decisions,
+      onDivergence,
+      onVersionMismatch,
+      children,
+    }) {
+      const value = usePublished(
+        given ?? features,
+        context,
+        decisions,
+        onVersionMismatch,
+        onDivergence,
+      );
+
+      return (
+        <SharedContext.Provider value={value}>
+          <BoundContext.Provider value={value}>
+            {children}
+          </BoundContext.Provider>
+        </SharedContext.Provider>
+      );
+    },
+    useFeatures() {
+      return atSchema<S, Frozen>(useContextValue(BoundContext).decisions);
+    },
+    useFeature(key) {
+      const decisions = useContextValue(BoundContext).decisions;
+      requireDecision(decisions, key);
+      return decisionAtSchema<S, typeof key, Frozen>(decisions, key);
+    },
+    useFeatureEnabled(key) {
+      return requireDecision(useContextValue(BoundContext).decisions, key)
+        .enabled;
+    },
+    useVariant(key) {
+      const decision = requireDecision(
+        useContextValue(BoundContext).decisions,
+        key,
+      );
+      // A method whose return type is conditional on an unresolved `S` has no
+      // type an implementation can write. The compiler resolves neither branch
+      // here, and the runtime answer is the two fields the decision carries
+      // either way.
+      return { variant: decision.variant, value: decision.value } as never;
+    },
+  };
+}