@loic001/experiments 0.1.0

package/PRINCIPLES.md

@@ -0,0 +1,59 @@
+# experiments — laws
+
+An experiment shows different people different things and asks which worked.
+Everything below exists because one of these is easy to break by accident.
+
+## 1. An arm is stable, or it is not an experiment
+
+The same subject sees the same arm on every load, every page, every day, with
+no server round-trip and no flash. The arm is a pure function of
+`(subject id × experiment key)` — a hash, not a coin toss. A subject who
+changes arm mid-test pollutes both.
+
+## 2. Assigning is not exposing
+
+Computing someone's arm costs nothing and means nothing. The denominator is
+the people who **saw** the thing. A visitor who never reached the tested
+component must never enter the count — including them dilutes the very
+difference you are trying to measure. So assignment is pure and silent;
+only `expose()` records.
+
+## 3. The registry serves; the data judges
+
+The registry lives with the app that **serves** variants. A reader —
+dashboard, warehouse, notebook — discovers the arms from what was actually
+served, and never needs a mirrored copy. Two registries to keep in sync is a
+bug waiting for a Friday: one of them drifts, and the numbers quietly describe
+an experiment nobody is running.
+
+## 4. A variant is what someone SAW, never what they became
+
+The arm is a **dimension** of the subject, alongside channel or country — not
+a fact, not a step, not an outcome. It rides with the subject into whatever
+funnel or ledger the host already has. This package computes no funnels: it
+hands over a string.
+
+## 5. Widening a rollout never moves anyone
+
+Entering the test and choosing an arm are two independent draws. Going from
+10% to 50% lets new subjects in; it does not reshuffle the ones already there,
+so the data collected before the widening stays usable.
+
+## 6. Stopping is one line, and history keeps its arms
+
+`enabled: false` → everyone sees the control, nothing new is recorded. What
+was already served keeps its arm forever: a past experiment is history, not a
+mistake to erase. Variant ids are append-only — renaming one rewrites the
+meaning of rows already written.
+
+## 7. No verdict without enough people
+
+A p-value on twelve subjects is decoration. A verdict requires **both** a
+minimum arm size and a significance threshold, and when either is missing the
+honest output is "not yet", never a number that will flip next week. Fixing
+the goal before starting is the host's job; refusing to speak early is ours.
+
+## 8. Analytics never breaks the page
+
+Every sink is best-effort and wrapped. A blocked pixel, a full quota, a
+private window: the experiment still serves an arm and the page still renders.

package/README.md

@@ -0,0 +1,80 @@
+# experiments
+
+A stable arm per subject, exposure as the denominator, and a verdict that
+refuses to speak too early. No server round-trip, no flash, no vendor.
+
+Laws: [PRINCIPLES.md](./PRINCIPLES.md).
+
+```ts
+import { createExperiments, posthogSink } from '@loic001/experiments/browser';
+
+export const experiments = createExperiments({
+  experiments: [
+    {
+      key: 'apply_landing',
+      enabled: true,
+      rollout: 0.5,                  // half the traffic enters the test
+      control: 'control',
+      variants: [{ id: 'control' }, { id: 'v2' }],
+    },
+  ],
+  sinks: [posthogSink()],
+});
+```
+
+Serve it — React, or anything:
+
+```tsx
+import { useExperiment } from '@loic001/experiments/react';
+
+const arm = useExperiment(experiments, 'apply_landing');
+if (arm === 'v2') return <Variant />;
+```
+
+Carry it — the arm rides with whatever you already send:
+
+```ts
+payload.exp = experiments.wire();     // "apply_landing:v2", or undefined
+```
+
+Judge it — registry-free, from whatever your warehouse counted:
+
+```ts
+import { compareArms } from '@loic001/experiments';
+
+compareArms([
+  { id: 'control', n: 4_012, converted: 402 },
+  { id: 'v2', n: 3_988, converted: 518 },
+]);
+// { verdict: 'winner', winner: 'v2',
+//   arms: [ …, { id: 'v2', ratePct: 13, deltaPts: 3, liftPct: 29.9, pValue: 0, significant: true } ] }
+```
+
+## Three entries
+
+| Import | Contains | Needs |
+|---|---|---|
+| `@loic001/experiments` | assignment, wire format, verdict — **pure** | nothing |
+| `@loic001/experiments/browser` | storage, URL overrides, exposure sinks | a browser (or injected fakes) |
+| `@loic001/experiments/react` | the hook | React ≥ 18 |
+
+The pure entry runs in a browser, a worker, a Node job or a SQL-fed dashboard
+alike. Everything in `/browser` is injectable (`storage`, `search`, `now`,
+`sinks`), so the whole adapter is testable without a DOM.
+
+## What it does not do
+
+- **No funnels.** The arm is a dimension on your subject; your funnel tool
+  slices on it. Pairs naturally with [`@loic001/funnels`](https://github.com/loic001/funnels).
+- **No identity.** The subject id is a local random, 30 days, never sent
+  anywhere. Only `"key:variant"` travels.
+- **No registry on the reading side.** A dashboard discovers arms from the
+  data. Two registries to keep in sync is a bug waiting for a Friday.
+- **No sequential testing.** `compareArms` is a two-proportion z test at a
+  fixed horizon. Peeking daily and stopping at the first green inflates false
+  positives — fix the sample size before you start.
+
+## Overrides
+
+`?exp=apply_landing:v2` forces an arm for QA and previews, and only accepts a
+variant that actually exists. Change the parameter with `overrideParam`.

package/dist/browser/index.d.ts

@@ -0,0 +1,50 @@
+import { E as Experiment, A as Assignments } from '../types-BWOV7ULO.js';
+
+type StorageLike = {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+};
+type Exposure = {
+    key: string;
+    variant: string;
+    subject: string;
+};
+/** Where exposures go. Every sink is best-effort — it never breaks the page (law 8). */
+type Sink = {
+    onExposure(e: Exposure): void;
+};
+type CreateOptions = {
+    experiments: readonly Experiment[];
+    /** Default: `localStorage`, or an in-memory map when unavailable (SSR, private mode). */
+    storage?: StorageLike;
+    /** Query string used for overrides. Default: `location.search`. */
+    search?: () => string;
+    now?: () => number;
+    /** How long an assignment and a subject id live. Default 30 days. */
+    ttlMs?: number;
+    /** Storage key prefix. Default `exp`. */
+    namespace?: string;
+    /** URL parameter that forces arms — `?exp=key:variant`. Default `exp`. */
+    overrideParam?: string;
+    sinks?: readonly Sink[];
+};
+type Experiments = {
+    /** Stable anonymous id for this browser. Not an identity; never leaves the device. */
+    subjectId(): string;
+    /** The arm this subject WOULD see. Pure: records nothing, fires nothing (law 2). */
+    variantOf(key: string): string;
+    /** Declare the subject saw it: records the arm, fires the sinks once, returns it. */
+    expose(key: string): string;
+    /** Arms actually shown (from storage) — the only ones that may travel (law 2). */
+    shown(): Assignments;
+    /** `shown()` serialized — drop it in your lead/event payload. */
+    wire(): string | undefined;
+    /** Test seam: forget assignments and fired exposures. */
+    reset(): void;
+};
+/** PostHog sink: a persistent `exp_<key>` property plus one `experiment_exposure` event. */
+declare function posthogSink(): Sink;
+declare function createExperiments(opts: CreateOptions): Experiments;
+
+export { type CreateOptions, type Experiments, type Exposure, type Sink, type StorageLike, createExperiments, posthogSink };

package/dist/browser/index.js

@@ -0,0 +1,153 @@
+import {
+  assignVariant,
+  parseAssignments,
+  serializeAssignments
+} from "../chunk-WBS3SDIK.js";
+
+// browser/index.ts
+var DAY = 864e5;
+function memoryStorage() {
+  const m = /* @__PURE__ */ new Map();
+  return {
+    getItem: (k) => m.get(k) ?? null,
+    setItem: (k, v) => void m.set(k, v),
+    removeItem: (k) => void m.delete(k)
+  };
+}
+function safeStorage(given) {
+  if (given) return given;
+  try {
+    const ls = globalThis.localStorage;
+    if (ls) {
+      const probe = "__exp_probe__";
+      ls.setItem(probe, "1");
+      ls.removeItem(probe);
+      return ls;
+    }
+  } catch {
+  }
+  return memoryStorage();
+}
+function posthogSink() {
+  return {
+    onExposure({ key, variant }) {
+      const ph = globalThis.posthog;
+      ph?.register?.({ [`exp_${key}`]: variant });
+      ph?.capture?.("experiment_exposure", { exp_key: key, exp_variant: variant });
+    }
+  };
+}
+function createExperiments(opts) {
+  const store = safeStorage(opts.storage);
+  const now = opts.now ?? (() => Date.now());
+  const ttl = opts.ttlMs ?? 30 * DAY;
+  const ns = opts.namespace ?? "exp";
+  const param = opts.overrideParam ?? "exp";
+  const sinks = opts.sinks ?? [];
+  const subjectKey = `${ns}:subject`;
+  const assignKey = `${ns}:assigned`;
+  const fired = /* @__PURE__ */ new Set();
+  const find = (key) => opts.experiments.find((e) => e.key === key);
+  const readEnvelope = (k) => {
+    try {
+      const raw = store.getItem(k);
+      if (!raw) return {};
+      const parsed = JSON.parse(raw);
+      if (!parsed || typeof parsed.savedAt !== "number" || typeof parsed.data !== "object" || parsed.data == null) {
+        return {};
+      }
+      if (now() - parsed.savedAt > ttl) {
+        store.removeItem(k);
+        return {};
+      }
+      return parsed.data;
+    } catch {
+      return {};
+    }
+  };
+  const writeEnvelope = (k, data) => {
+    try {
+      store.setItem(k, JSON.stringify({ savedAt: now(), data }));
+    } catch {
+    }
+  };
+  const overrides = () => {
+    let raw = null;
+    try {
+      const search = opts.search ? opts.search() : globalThis.location?.search;
+      if (search) raw = new URLSearchParams(search).get(param);
+    } catch {
+      return {};
+    }
+    const parsed = parseAssignments(raw);
+    const out = {};
+    for (const [k, v] of Object.entries(parsed)) {
+      if (find(k)?.variants.some((x) => x.id === v)) out[k] = v;
+    }
+    return out;
+  };
+  const subjectId = () => {
+    const stored = readEnvelope(subjectKey).id;
+    if (stored) return stored;
+    let id;
+    try {
+      id = globalThis.crypto?.randomUUID?.();
+    } catch {
+      id = void 0;
+    }
+    id ??= `s_${Math.random().toString(16).slice(2)}${now().toString(16)}`;
+    writeEnvelope(subjectKey, { id });
+    return id;
+  };
+  const variantOf = (key) => {
+    const exp = find(key);
+    if (!exp) return "control";
+    if (!exp.enabled) return exp.control;
+    return overrides()[key] ?? readEnvelope(assignKey)[key] ?? assignVariant(exp, subjectId());
+  };
+  const expose = (key) => {
+    const exp = find(key);
+    if (!exp) return "control";
+    const variant = variantOf(key);
+    if (!exp.enabled) return variant;
+    const stored = readEnvelope(assignKey);
+    if (stored[key] !== variant) writeEnvelope(assignKey, { ...stored, [key]: variant });
+    const token = `${key}:${variant}`;
+    if (!fired.has(token)) {
+      fired.add(token);
+      const e = { key, variant, subject: subjectId() };
+      for (const s of sinks) {
+        try {
+          s.onExposure(e);
+        } catch {
+        }
+      }
+    }
+    return variant;
+  };
+  const shown = () => {
+    const stored = readEnvelope(assignKey);
+    const out = {};
+    for (const e of opts.experiments) if (e.enabled && stored[e.key]) out[e.key] = stored[e.key];
+    return out;
+  };
+  return {
+    subjectId,
+    variantOf,
+    expose,
+    shown,
+    wire: () => serializeAssignments(shown()),
+    reset: () => {
+      fired.clear();
+      try {
+        store.removeItem(assignKey);
+      } catch {
+      }
+    }
+  };
+}
+export {
+  createExperiments,
+  posthogSink
+};
+//# sourceMappingURL=index.js.map

package/dist/browser/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../browser/index.ts"],"sourcesContent":["/**\n * Browser plumbing — the only part that touches storage, the URL and pixels.\n *\n * Everything here is injectable, so the whole adapter is testable in Node\n * without a DOM: pass your own `storage`, `search`, `now` and sinks.\n *\n *   const exp = createExperiments({ experiments: MY_EXPERIMENTS, sinks: [posthogSink()] });\n *   const arm = exp.expose('apply_landing');   // assigns, records, fires sinks\n *   exp.wire();                                // \"apply_landing:v2\" → your lead payload\n */\nimport { assignVariant } from '../src/assign.js';\nimport type { Assignments, Experiment } from '../src/types.js';\nimport { parseAssignments, serializeAssignments } from '../src/wire.js';\n\nexport type StorageLike = {\n  getItem(key: string): string | null;\n  setItem(key: string, value: string): void;\n  removeItem(key: string): void;\n};\n\nexport type Exposure = { key: string; variant: string; subject: string };\n\n/** Where exposures go. Every sink is best-effort — it never breaks the page (law 8). */\nexport type Sink = { onExposure(e: Exposure): void };\n\nexport type CreateOptions = {\n  experiments: readonly Experiment[];\n  /** Default: `localStorage`, or an in-memory map when unavailable (SSR, private mode). */\n  storage?: StorageLike;\n  /** Query string used for overrides. Default: `location.search`. */\n  search?: () => string;\n  now?: () => number;\n  /** How long an assignment and a subject id live. Default 30 days. */\n  ttlMs?: number;\n  /** Storage key prefix. Default `exp`. */\n  namespace?: string;\n  /** URL parameter that forces arms — `?exp=key:variant`. Default `exp`. */\n  overrideParam?: string;\n  sinks?: readonly Sink[];\n};\n\nexport type Experiments = {\n  /** Stable anonymous id for this browser. Not an identity; never leaves the device. */\n  subjectId(): string;\n  /** The arm this subject WOULD see. Pure: records nothing, fires nothing (law 2). */\n  variantOf(key: string): string;\n  /** Declare the subject saw it: records the arm, fires the sinks once, returns it. */\n  expose(key: string): string;\n  /** Arms actually shown (from storage) — the only ones that may travel (law 2). */\n  shown(): Assignments;\n  /** `shown()` serialized — drop it in your lead/event payload. */\n  wire(): string | undefined;\n  /** Test seam: forget assignments and fired exposures. */\n  reset(): void;\n};\n\nconst DAY = 86_400_000;\n\nfunction memoryStorage(): StorageLike {\n  const m = new Map<string, string>();\n  return {\n    getItem: (k) => m.get(k) ?? null,\n    setItem: (k, v) => void m.set(k, v),\n    removeItem: (k) => void m.delete(k),\n  };\n}\n\n/** localStorage, but never throwing: private mode and quota are normal, not exceptional. */\nfunction safeStorage(given?: StorageLike): StorageLike {\n  if (given) return given;\n  try {\n    const ls = (globalThis as { localStorage?: StorageLike }).localStorage;\n    if (ls) {\n      const probe = '__exp_probe__';\n      ls.setItem(probe, '1');\n      ls.removeItem(probe);\n      return ls;\n    }\n  } catch {\n    /* falls through to memory */\n  }\n  return memoryStorage();\n}\n\ntype Envelope = { savedAt: number; data: Record<string, string> };\n\n/** PostHog sink: a persistent `exp_<key>` property plus one `experiment_exposure` event. */\nexport function posthogSink(): Sink {\n  return {\n    onExposure({ key, variant }) {\n      const ph = (globalThis as { posthog?: { register?(p: Record<string, unknown>): void; capture?(e: string, p?: Record<string, unknown>): void } }).posthog;\n      ph?.register?.({ [`exp_${key}`]: variant });\n      ph?.capture?.('experiment_exposure', { exp_key: key, exp_variant: variant });\n    },\n  };\n}\n\nexport function createExperiments(opts: CreateOptions): Experiments {\n  const store = safeStorage(opts.storage);\n  const now = opts.now ?? (() => Date.now());\n  const ttl = opts.ttlMs ?? 30 * DAY;\n  const ns = opts.namespace ?? 'exp';\n  const param = opts.overrideParam ?? 'exp';\n  const sinks = opts.sinks ?? [];\n  const subjectKey = `${ns}:subject`;\n  const assignKey = `${ns}:assigned`;\n  const fired = new Set<string>();\n\n  const find = (key: string): Experiment | undefined => opts.experiments.find((e) => e.key === key);\n\n  const readEnvelope = (k: string): Record<string, string> => {\n    try {\n      const raw = store.getItem(k);\n      if (!raw) return {};\n      const parsed = JSON.parse(raw) as Envelope;\n      if (!parsed || typeof parsed.savedAt !== 'number' || typeof parsed.data !== 'object' || parsed.data == null) {\n        return {};\n      }\n      if (now() - parsed.savedAt > ttl) {\n        store.removeItem(k);\n        return {};\n      }\n      return parsed.data;\n    } catch {\n      return {};\n    }\n  };\n\n  const writeEnvelope = (k: string, data: Record<string, string>): void => {\n    try {\n      store.setItem(k, JSON.stringify({ savedAt: now(), data } satisfies Envelope));\n    } catch {\n      /* best-effort (law 8) */\n    }\n  };\n\n  const overrides = (): Record<string, string> => {\n    let raw: string | null = null;\n    try {\n      const search = opts.search ? opts.search() : (globalThis as { location?: { search?: string } }).location?.search;\n      if (search) raw = new URLSearchParams(search).get(param);\n    } catch {\n      return {};\n    }\n    const parsed = parseAssignments(raw);\n    // A forced arm must be a REAL arm, or a dashboard would grow a column for\n    // an experiment nobody is running.\n    const out: Record<string, string> = {};\n    for (const [k, v] of Object.entries(parsed)) {\n      if (find(k)?.variants.some((x) => x.id === v)) out[k] = v;\n    }\n    return out;\n  };\n\n  const subjectId = (): string => {\n    const stored = readEnvelope(subjectKey).id;\n    if (stored) return stored;\n    let id: string | undefined;\n    try {\n      // Locked-down browsers expose `crypto` but throw on use — a random id is\n      // always better than a broken page (law 8).\n      id = (globalThis as { crypto?: { randomUUID?(): string } }).crypto?.randomUUID?.();\n    } catch {\n      id = undefined;\n    }\n    id ??= `s_${Math.random().toString(16).slice(2)}${now().toString(16)}`;\n    writeEnvelope(subjectKey, { id });\n    return id;\n  };\n\n  const variantOf = (key: string): string => {\n    const exp = find(key);\n    if (!exp) return 'control';\n    if (!exp.enabled) return exp.control;\n    return overrides()[key] ?? readEnvelope(assignKey)[key] ?? assignVariant(exp, subjectId());\n  };\n\n  const expose = (key: string): string => {\n    const exp = find(key);\n    if (!exp) return 'control';\n    const variant = variantOf(key);\n    if (!exp.enabled) return variant;\n\n    // Exposure is the ONLY writer: what is stored is what was shown, and that\n    // is exactly what may travel with the subject (law 2).\n    const stored = readEnvelope(assignKey);\n    if (stored[key] !== variant) writeEnvelope(assignKey, { ...stored, [key]: variant });\n\n    const token = `${key}:${variant}`;\n    if (!fired.has(token)) {\n      fired.add(token);\n      const e: Exposure = { key, variant, subject: subjectId() };\n      for (const s of sinks) {\n        try {\n          s.onExposure(e);\n        } catch {\n          /* law 8 */\n        }\n      }\n    }\n    return variant;\n  };\n\n  const shown = (): Assignments => {\n    const stored = readEnvelope(assignKey);\n    const out: Record<string, string> = {};\n    // A stopped experiment stops travelling, even if the browser still remembers it (law 6).\n    for (const e of opts.experiments) if (e.enabled && stored[e.key]) out[e.key] = stored[e.key];\n    return out;\n  };\n\n  return {\n    subjectId,\n    variantOf,\n    expose,\n    shown,\n    wire: () => serializeAssignments(shown()),\n    reset: () => {\n      fired.clear();\n      try {\n        store.removeItem(assignKey);\n      } catch {\n        /* law 8 */\n      }\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-WBS3SDIK.js

@@ -0,0 +1,64 @@
+// src/hash.ts
+function hash32(input) {
+  let h = 2166136261;
+  for (let i = 0; i < input.length; i += 1) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+var bucketOf = (subject, salt) => hash32(`${subject}:${salt}`) / 4294967296;
+
+// src/assign.ts
+function assignVariant(exp, subject) {
+  if (!exp.enabled || !subject) return exp.control;
+  const rollout = exp.rollout ?? 1;
+  if (rollout < 1 && bucketOf(subject, `${exp.key}:rollout`) >= rollout) return exp.control;
+  const total = exp.variants.reduce((s, v) => s + (v.weight ?? 1), 0);
+  if (total <= 0) return exp.control;
+  const target = bucketOf(subject, exp.key) * total;
+  let acc = 0;
+  let chosen = exp.control;
+  for (const v of exp.variants) {
+    acc += v.weight ?? 1;
+    if (target < acc) {
+      chosen = v.id;
+      break;
+    }
+  }
+  return chosen;
+}
+
+// src/wire.ts
+var KEY_RE = /^[a-z0-9_]{1,40}$/;
+var VARIANT_RE = /^[a-z0-9_-]{1,40}$/;
+var WIRE_MAX = 200;
+function parseAssignments(raw) {
+  const out = {};
+  if (!raw) return out;
+  for (const part of String(raw).split(",")) {
+    const [k, v] = part.split(":").map((s) => s.trim().toLowerCase());
+    if (k && v && KEY_RE.test(k) && VARIANT_RE.test(v)) out[k] = v;
+  }
+  return out;
+}
+function serializeAssignments(a) {
+  const parts = Object.entries(a).filter(([k, v]) => k && v).sort(([x], [y]) => x.localeCompare(y)).map(([k, v]) => `${k}:${v}`);
+  if (parts.length === 0) return void 0;
+  const joined = parts.join(",");
+  return joined.length <= WIRE_MAX ? joined : joined.slice(0, joined.lastIndexOf(",", WIRE_MAX));
+}
+var dimIdOf = (key) => `exp_${key}`;
+var NOT_EXPOSED = "none";
+
+export {
+  hash32,
+  bucketOf,
+  assignVariant,
+  WIRE_MAX,
+  parseAssignments,
+  serializeAssignments,
+  dimIdOf,
+  NOT_EXPOSED
+};
+//# sourceMappingURL=chunk-WBS3SDIK.js.map

package/dist/chunk-WBS3SDIK.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hash.ts","../src/assign.ts","../src/wire.ts"],"sourcesContent":["/**\n * FNV-1a, 32 bits. Small, dependency-free, and well-spread enough to split\n * traffic: the point is a stable bucket per subject, not cryptography.\n */\nexport function hash32(input: string): number {\n  let h = 0x811c9dc5;\n  for (let i = 0; i < input.length; i += 1) {\n    h ^= input.charCodeAt(i);\n    h = Math.imul(h, 0x01000193);\n  }\n  return h >>> 0;\n}\n\n/**\n * A stable float in [0,1) for a `(subject, salt)` pair. Different salts give\n * independent draws from the same subject — which is what lets a rollout widen\n * without reshuffling anyone (law 5).\n */\nexport const bucketOf = (subject: string, salt: string): number =>\n  hash32(`${subject}:${salt}`) / 0x100000000;\n","import { bucketOf } from './hash.js';\nimport type { Experiment } from './types.js';\n\n/**\n * The arm a subject gets — PURE, silent, no I/O (law 2). Two independent\n * draws: one decides whether the subject enters the test at all (`rollout`),\n * the other which arm they see. Separating them is what makes widening a\n * rollout safe (law 5).\n *\n * An empty subject id, a disabled experiment, or weights that sum to zero all\n * fall back to the control — serving something is always better than throwing\n * on a page.\n */\nexport function assignVariant(exp: Experiment, subject: string): string {\n  if (!exp.enabled || !subject) return exp.control;\n\n  const rollout = exp.rollout ?? 1;\n  if (rollout < 1 && bucketOf(subject, `${exp.key}:rollout`) >= rollout) return exp.control;\n\n  const total = exp.variants.reduce((s, v) => s + (v.weight ?? 1), 0);\n  if (total <= 0) return exp.control;\n\n  // Une seule sortie : le point tombe dans le premier intervalle cumulé qui le\n  // dépasse. `bucketOf` est strictement < 1, donc il tombe toujours.\n  const target = bucketOf(subject, exp.key) * total;\n  let acc = 0;\n  let chosen = exp.control;\n  for (const v of exp.variants) {\n    acc += v.weight ?? 1;\n    if (target < acc) {\n      chosen = v.id;\n      break;\n    }\n  }\n  return chosen;\n}\n","import type { Assignments } from './types.js';\n\nconst KEY_RE = /^[a-z0-9_]{1,40}$/;\nconst VARIANT_RE = /^[a-z0-9_-]{1,40}$/;\n\n/** Longest wire string we ever emit — it rides inside other people's columns. */\nexport const WIRE_MAX = 200;\n\n/**\n * `\"apply_landing:v2,hero:b\"` → `{ apply_landing: 'v2', hero: 'b' }`.\n * Tolerant by design: this string crosses domains, query strings and third\n * party columns, so it parses what it recognises and silently drops the rest.\n * Never throws.\n */\nexport function parseAssignments(raw: string | null | undefined): Record<string, string> {\n  const out: Record<string, string> = {};\n  if (!raw) return out;\n  for (const part of String(raw).split(',')) {\n    const [k, v] = part.split(':').map((s) => s.trim().toLowerCase());\n    if (k && v && KEY_RE.test(k) && VARIANT_RE.test(v)) out[k] = v;\n  }\n  return out;\n}\n\n/**\n * `{ apply_landing: 'v2' }` → `\"apply_landing:v2\"`. Sorted, so the same\n * assignments always produce the same string (it ends up in dedupe keys and\n * cache keys). `undefined` when there is nothing to say.\n */\nexport function serializeAssignments(a: Assignments): string | undefined {\n  const parts = Object.entries(a)\n    .filter(([k, v]) => k && v)\n    .sort(([x], [y]) => x.localeCompare(y))\n    .map(([k, v]) => `${k}:${v}`);\n  if (parts.length === 0) return undefined;\n  const joined = parts.join(',');\n  return joined.length <= WIRE_MAX ? joined : joined.slice(0, joined.lastIndexOf(',', WIRE_MAX));\n}\n\n/** Dimension id for a key — the name the funnel/warehouse sees. */\nexport const dimIdOf = (key: string): string => `exp_${key}`;\n\n/** Value used for subjects who were never exposed. Never an empty string: absence must be countable. */\nexport const NOT_EXPOSED = 'none';\n"],"mappings":";AAIO,SAAS,OAAO,OAAuB;AAC5C,MAAI,IAAI;AACR,WAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK,GAAG;AACxC,SAAK,MAAM,WAAW,CAAC;AACvB,QAAI,KAAK,KAAK,GAAG,QAAU;AAAA,EAC7B;AACA,SAAO,MAAM;AACf;AAOO,IAAM,WAAW,CAAC,SAAiB,SACxC,OAAO,GAAG,OAAO,IAAI,IAAI,EAAE,IAAI;;;ACN1B,SAAS,cAAc,KAAiB,SAAyB;AACtE,MAAI,CAAC,IAAI,WAAW,CAAC,QAAS,QAAO,IAAI;AAEzC,QAAM,UAAU,IAAI,WAAW;AAC/B,MAAI,UAAU,KAAK,SAAS,SAAS,GAAG,IAAI,GAAG,UAAU,KAAK,QAAS,QAAO,IAAI;AAElF,QAAM,QAAQ,IAAI,SAAS,OAAO,CAAC,GAAG,MAAM,KAAK,EAAE,UAAU,IAAI,CAAC;AAClE,MAAI,SAAS,EAAG,QAAO,IAAI;AAI3B,QAAM,SAAS,SAAS,SAAS,IAAI,GAAG,IAAI;AAC5C,MAAI,MAAM;AACV,MAAI,SAAS,IAAI;AACjB,aAAW,KAAK,IAAI,UAAU;AAC5B,WAAO,EAAE,UAAU;AACnB,QAAI,SAAS,KAAK;AAChB,eAAS,EAAE;AACX;AAAA,IACF;AAAA,EACF;AACA,SAAO;AACT;;;ACjCA,IAAM,SAAS;AACf,IAAM,aAAa;AAGZ,IAAM,WAAW;AAQjB,SAAS,iBAAiB,KAAwD;AACvF,QAAM,MAA8B,CAAC;AACrC,MAAI,CAAC,IAAK,QAAO;AACjB,aAAW,QAAQ,OAAO,GAAG,EAAE,MAAM,GAAG,GAAG;AACzC,UAAM,CAAC,GAAG,CAAC,IAAI,KAAK,MAAM,GAAG,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC;AAChE,QAAI,KAAK,KAAK,OAAO,KAAK,CAAC,KAAK,WAAW,KAAK,CAAC,EAAG,KAAI,CAAC,IAAI;AAAA,EAC/D;AACA,SAAO;AACT;AAOO,SAAS,qBAAqB,GAAoC;AACvE,QAAM,QAAQ,OAAO,QAAQ,CAAC,EAC3B,OAAO,CAAC,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,EACzB,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,EACrC,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,EAAE;AAC9B,MAAI,MAAM,WAAW,EAAG,QAAO;AAC/B,QAAM,SAAS,MAAM,KAAK,GAAG;AAC7B,SAAO,OAAO,UAAU,WAAW,SAAS,OAAO,MAAM,GAAG,OAAO,YAAY,KAAK,QAAQ,CAAC;AAC/F;AAGO,IAAM,UAAU,CAAC,QAAwB,OAAO,GAAG;AAGnD,IAAM,cAAc;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,117 @@
+import { E as Experiment, A as Assignments } from './types-BWOV7ULO.js';
+export { V as Variant } from './types-BWOV7ULO.js';
+
+/**
+ * The arm a subject gets — PURE, silent, no I/O (law 2). Two independent
+ * draws: one decides whether the subject enters the test at all (`rollout`),
+ * the other which arm they see. Separating them is what makes widening a
+ * rollout safe (law 5).
+ *
+ * An empty subject id, a disabled experiment, or weights that sum to zero all
+ * fall back to the control — serving something is always better than throwing
+ * on a page.
+ */
+declare function assignVariant(exp: Experiment, subject: string): string;
+
+/**
+ * FNV-1a, 32 bits. Small, dependency-free, and well-spread enough to split
+ * traffic: the point is a stable bucket per subject, not cryptography.
+ */
+declare function hash32(input: string): number;
+/**
+ * A stable float in [0,1) for a `(subject, salt)` pair. Different salts give
+ * independent draws from the same subject — which is what lets a rollout widen
+ * without reshuffling anyone (law 5).
+ */
+declare const bucketOf: (subject: string, salt: string) => number;
+
+/**
+ * The verdict — generic over arms, registry-free (law 3). Give it what each
+ * arm was shown and how many converted; it says whether the difference is
+ * real, or refuses to say (law 7).
+ */
+/** What a reader knows about one arm, whatever its source. */
+type Arm = {
+    id: string;
+    label?: string;
+    /** Subjects EXPOSED to this arm — the denominator (law 2). */
+    n: number;
+    /** Of those, how many reached the goal. */
+    converted: number;
+};
+type CompareOptions = {
+    /** Arm every other one is measured against. Default: the first. */
+    control?: string;
+    /** Minimum exposed per arm before any verdict is allowed. Default 30. */
+    minArmN?: number;
+    /** Two-sided significance threshold. Default 0.05. */
+    alpha?: number;
+};
+type ArmResult = {
+    id: string;
+    label: string;
+    n: number;
+    converted: number;
+    /** Conversion, in percent. null when nobody was exposed. */
+    ratePct: number | null;
+    /** Difference with the control, in percentage points. null for the control itself. */
+    deltaPts: number | null;
+    /** Relative lift vs the control, in percent. null when the control converts nobody. */
+    liftPct: number | null;
+    z: number | null;
+    pValue: number | null;
+    /** Both conditions met: p < alpha AND both arms above `minArmN`. */
+    significant: boolean;
+    /** This arm alone has enough people. */
+    enough: boolean;
+    isControl: boolean;
+};
+type Comparison = {
+    control: string;
+    arms: ArmResult[];
+    /** Total exposed across arms. */
+    exposed: number;
+    /**
+     * What a human should read. `not_enough` while any arm is below the floor,
+     * `no_difference` when nothing is significant, else the winning arm id.
+     */
+    verdict: 'not_enough' | 'no_difference' | 'winner' | 'loser';
+    winner: string | null;
+};
+declare const DEFAULT_MIN_ARM_N = 30;
+declare const DEFAULT_ALPHA = 0.05;
+/**
+ * Abramowitz & Stegun 7.1.26 — |error| < 1.5e-7. A p-value is displayed to
+ * three decimals; a series is honest here and keeps the package dependency-free.
+ */
+declare function erf(x: number): number;
+type ProportionTest = {
+    z: number;
+    pValue: number;
+};
+/** Two-proportion z test (pooled), two-sided. null when either arm is empty. */
+declare function twoProportionTest(kA: number, nA: number, kB: number, nB: number): ProportionTest | null;
+/** Compare arms against the control. Order in = order out, control first. */
+declare function compareArms(arms: readonly Arm[], opts?: CompareOptions): Comparison;
+
+/** Longest wire string we ever emit — it rides inside other people's columns. */
+declare const WIRE_MAX = 200;
+/**
+ * `"apply_landing:v2,hero:b"` → `{ apply_landing: 'v2', hero: 'b' }`.
+ * Tolerant by design: this string crosses domains, query strings and third
+ * party columns, so it parses what it recognises and silently drops the rest.
+ * Never throws.
+ */
+declare function parseAssignments(raw: string | null | undefined): Record<string, string>;
+/**
+ * `{ apply_landing: 'v2' }` → `"apply_landing:v2"`. Sorted, so the same
+ * assignments always produce the same string (it ends up in dedupe keys and
+ * cache keys). `undefined` when there is nothing to say.
+ */
+declare function serializeAssignments(a: Assignments): string | undefined;
+/** Dimension id for a key — the name the funnel/warehouse sees. */
+declare const dimIdOf: (key: string) => string;
+/** Value used for subjects who were never exposed. Never an empty string: absence must be countable. */
+declare const NOT_EXPOSED = "none";
+
+export { type Arm, type ArmResult, Assignments, type CompareOptions, type Comparison, DEFAULT_ALPHA, DEFAULT_MIN_ARM_N, Experiment, NOT_EXPOSED, type ProportionTest, WIRE_MAX, assignVariant, bucketOf, compareArms, dimIdOf, erf, hash32, parseAssignments, serializeAssignments, twoProportionTest };

package/dist/index.js

@@ -0,0 +1,84 @@
+import {
+  NOT_EXPOSED,
+  WIRE_MAX,
+  assignVariant,
+  bucketOf,
+  dimIdOf,
+  hash32,
+  parseAssignments,
+  serializeAssignments
+} from "./chunk-WBS3SDIK.js";
+
+// src/analyze.ts
+var DEFAULT_MIN_ARM_N = 30;
+var DEFAULT_ALPHA = 0.05;
+function erf(x) {
+  const sign = x < 0 ? -1 : 1;
+  const ax = Math.abs(x);
+  const t = 1 / (1 + 0.3275911 * ax);
+  const y = 1 - ((((1.061405429 * t - 1.453152027) * t + 1.421413741) * t - 0.284496736) * t + 0.254829592) * t * Math.exp(-ax * ax);
+  return sign * y;
+}
+var normalCdf = (z) => 0.5 * (1 + erf(z / Math.SQRT2));
+function twoProportionTest(kA, nA, kB, nB) {
+  if (nA <= 0 || nB <= 0) return null;
+  const p = (kA + kB) / (nA + nB);
+  const se = Math.sqrt(p * (1 - p) * (1 / nA + 1 / nB));
+  const z = se === 0 ? 0 : (kB / nB - kA / nA) / se;
+  return { z: Math.round(z * 100) / 100, pValue: Math.round(2 * (1 - normalCdf(Math.abs(z))) * 1e3) / 1e3 };
+}
+var round1 = (v) => Math.round(v * 10) / 10;
+function compareArms(arms, opts = {}) {
+  const minArmN = opts.minArmN ?? DEFAULT_MIN_ARM_N;
+  const alpha = opts.alpha ?? DEFAULT_ALPHA;
+  const controlId = opts.control ?? arms[0]?.id ?? "";
+  const control = arms.find((a) => a.id === controlId);
+  const controlN = control?.n ?? 0;
+  const results = arms.map((a) => {
+    const isControl = a.id === controlId;
+    const test = isControl || !control ? null : twoProportionTest(control.converted, control.n, a.converted, a.n);
+    const rate = a.n > 0 ? 100 * a.converted / a.n : null;
+    const controlRate = control && control.n > 0 ? 100 * control.converted / control.n : null;
+    return {
+      id: a.id,
+      label: a.label ?? a.id,
+      n: a.n,
+      converted: a.converted,
+      ratePct: rate == null ? null : round1(rate),
+      deltaPts: rate == null || controlRate == null || isControl ? null : round1(rate - controlRate),
+      liftPct: rate == null || controlRate == null || controlRate === 0 || isControl ? null : round1((rate - controlRate) / controlRate * 100),
+      z: test?.z ?? null,
+      pValue: test?.pValue ?? null,
+      significant: test != null && test.pValue < alpha && a.n >= minArmN && controlN >= minArmN,
+      enough: a.n >= minArmN,
+      isControl
+    };
+  });
+  const ordered = [...results].sort((a, b) => Number(b.isControl) - Number(a.isControl));
+  const decided = ordered.filter((r) => r.significant && r.deltaPts != null);
+  const best = decided.reduce((acc, r) => acc == null || r.deltaPts > acc.deltaPts ? r : acc, null);
+  const verdict = ordered.some((r) => !r.enough) ? "not_enough" : best == null ? "no_difference" : best.deltaPts > 0 ? "winner" : "loser";
+  return {
+    control: controlId,
+    arms: ordered,
+    exposed: arms.reduce((s, a) => s + a.n, 0),
+    verdict,
+    winner: verdict === "winner" && best ? best.id : null
+  };
+}
+export {
+  DEFAULT_ALPHA,
+  DEFAULT_MIN_ARM_N,
+  NOT_EXPOSED,
+  WIRE_MAX,
+  assignVariant,
+  bucketOf,
+  compareArms,
+  dimIdOf,
+  erf,
+  hash32,
+  parseAssignments,
+  serializeAssignments,
+  twoProportionTest
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/analyze.ts"],"sourcesContent":["/**\n * The verdict — generic over arms, registry-free (law 3). Give it what each\n * arm was shown and how many converted; it says whether the difference is\n * real, or refuses to say (law 7).\n */\n\n/** What a reader knows about one arm, whatever its source. */\nexport type Arm = {\n  id: string;\n  label?: string;\n  /** Subjects EXPOSED to this arm — the denominator (law 2). */\n  n: number;\n  /** Of those, how many reached the goal. */\n  converted: number;\n};\n\nexport type CompareOptions = {\n  /** Arm every other one is measured against. Default: the first. */\n  control?: string;\n  /** Minimum exposed per arm before any verdict is allowed. Default 30. */\n  minArmN?: number;\n  /** Two-sided significance threshold. Default 0.05. */\n  alpha?: number;\n};\n\nexport type ArmResult = {\n  id: string;\n  label: string;\n  n: number;\n  converted: number;\n  /** Conversion, in percent. null when nobody was exposed. */\n  ratePct: number | null;\n  /** Difference with the control, in percentage points. null for the control itself. */\n  deltaPts: number | null;\n  /** Relative lift vs the control, in percent. null when the control converts nobody. */\n  liftPct: number | null;\n  z: number | null;\n  pValue: number | null;\n  /** Both conditions met: p < alpha AND both arms above `minArmN`. */\n  significant: boolean;\n  /** This arm alone has enough people. */\n  enough: boolean;\n  isControl: boolean;\n};\n\nexport type Comparison = {\n  control: string;\n  arms: ArmResult[];\n  /** Total exposed across arms. */\n  exposed: number;\n  /**\n   * What a human should read. `not_enough` while any arm is below the floor,\n   * `no_difference` when nothing is significant, else the winning arm id.\n   */\n  verdict: 'not_enough' | 'no_difference' | 'winner' | 'loser';\n  winner: string | null;\n};\n\nexport const DEFAULT_MIN_ARM_N = 30;\nexport const DEFAULT_ALPHA = 0.05;\n\n/**\n * Abramowitz & Stegun 7.1.26 — |error| < 1.5e-7. A p-value is displayed to\n * three decimals; a series is honest here and keeps the package dependency-free.\n */\nexport function erf(x: number): number {\n  const sign = x < 0 ? -1 : 1;\n  const ax = Math.abs(x);\n  const t = 1 / (1 + 0.3275911 * ax);\n  const y =\n    1 -\n    ((((1.061405429 * t - 1.453152027) * t + 1.421413741) * t - 0.284496736) * t + 0.254829592) *\n      t *\n      Math.exp(-ax * ax);\n  return sign * y;\n}\n\nconst normalCdf = (z: number): number => 0.5 * (1 + erf(z / Math.SQRT2));\n\nexport type ProportionTest = { z: number; pValue: number };\n\n/** Two-proportion z test (pooled), two-sided. null when either arm is empty. */\nexport function twoProportionTest(\n  kA: number,\n  nA: number,\n  kB: number,\n  nB: number,\n): ProportionTest | null {\n  if (nA <= 0 || nB <= 0) return null;\n  const p = (kA + kB) / (nA + nB);\n  const se = Math.sqrt(p * (1 - p) * (1 / nA + 1 / nB));\n  const z = se === 0 ? 0 : (kB / nB - kA / nA) / se;\n  return { z: Math.round(z * 100) / 100, pValue: Math.round(2 * (1 - normalCdf(Math.abs(z))) * 1000) / 1000 };\n}\n\nconst round1 = (v: number): number => Math.round(v * 10) / 10;\n\n/** Compare arms against the control. Order in = order out, control first. */\nexport function compareArms(arms: readonly Arm[], opts: CompareOptions = {}): Comparison {\n  const minArmN = opts.minArmN ?? DEFAULT_MIN_ARM_N;\n  const alpha = opts.alpha ?? DEFAULT_ALPHA;\n  const controlId = opts.control ?? arms[0]?.id ?? '';\n  const control = arms.find((a) => a.id === controlId);\n\n  const controlN = control?.n ?? 0;\n\n  const results: ArmResult[] = arms.map((a) => {\n    const isControl = a.id === controlId;\n    const test = isControl || !control ? null : twoProportionTest(control.converted, control.n, a.converted, a.n);\n    const rate = a.n > 0 ? (100 * a.converted) / a.n : null;\n    const controlRate = control && control.n > 0 ? (100 * control.converted) / control.n : null;\n    return {\n      id: a.id,\n      label: a.label ?? a.id,\n      n: a.n,\n      converted: a.converted,\n      ratePct: rate == null ? null : round1(rate),\n      deltaPts: rate == null || controlRate == null || isControl ? null : round1(rate - controlRate),\n      liftPct:\n        rate == null || controlRate == null || controlRate === 0 || isControl\n          ? null\n          : round1(((rate - controlRate) / controlRate) * 100),\n      z: test?.z ?? null,\n      pValue: test?.pValue ?? null,\n      significant: test != null && test.pValue < alpha && a.n >= minArmN && controlN >= minArmN,\n      enough: a.n >= minArmN,\n      isControl,\n    };\n  });\n\n  const ordered = [...results].sort((a, b) => Number(b.isControl) - Number(a.isControl));\n  // Le contrôle n'est jamais « significatif » (il n'est comparé à rien), donc\n  // tout ce qui reste ici porte un `deltaPts` chiffré.\n  type Decided = ArmResult & { deltaPts: number };\n  const decided = ordered.filter((r): r is Decided => r.significant && r.deltaPts != null);\n  const best = decided.reduce<Decided | null>((acc, r) => (acc == null || r.deltaPts > acc.deltaPts ? r : acc), null);\n\n  const verdict: Comparison['verdict'] = ordered.some((r) => !r.enough)\n    ? 'not_enough'\n    : best == null\n      ? 'no_difference'\n      : best.deltaPts > 0\n        ? 'winner'\n        : 'loser';\n\n  return {\n    control: controlId,\n    arms: ordered,\n    exposed: arms.reduce((s, a) => s + a.n, 0),\n    verdict,\n    winner: verdict === 'winner' && best ? best.id : null,\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/react/index.d.ts

@@ -0,0 +1,6 @@
+import { Experiments } from '../browser/index.js';
+import '../types-BWOV7ULO.js';
+
+declare function useExperiment(experiments: Experiments, key: string, control?: string): string;
+
+export { useExperiment };

package/dist/react/index.js

@@ -0,0 +1,15 @@
+"use client";
+
+// react/index.ts
+import { useEffect, useState } from "react";
+function useExperiment(experiments, key, control = "control") {
+  const [variant, setVariant] = useState(control);
+  useEffect(() => {
+    setVariant(experiments.expose(key));
+  }, [experiments, key]);
+  return variant;
+}
+export {
+  useExperiment
+};
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../react/index.ts"],"sourcesContent":["'use client';\n\n/**\n * The React seam — one hook, no context, no provider.\n *\n *   const arm = useExperiment(exp, 'apply_landing');\n *   if (arm === 'v2') return <Variant />;\n *\n * The first render (server, and hydration) always returns the CONTROL: the arm\n * lives in storage, which does not exist on the server, and diverging would\n * be a hydration error. The real arm arrives on mount, and THAT is when the\n * exposure is declared — so the denominator never counts someone who saw\n * nothing (law 2). For an above-the-fold change this costs one frame; it is\n * the honest price of no server round-trip and no blocking screen.\n */\nimport { useEffect, useState } from 'react';\nimport type { Experiments } from '../browser/index.js';\n\nexport function useExperiment(experiments: Experiments, key: string, control = 'control'): string {\n  const [variant, setVariant] = useState<string>(control);\n  useEffect(() => {\n    setVariant(experiments.expose(key));\n  }, [experiments, key]);\n  return variant;\n}\n"],"mappings":";;;AAeA,SAAS,WAAW,gBAAgB;AAG7B,SAAS,cAAc,aAA0B,KAAa,UAAU,WAAmB;AAChG,QAAM,CAAC,SAAS,UAAU,IAAI,SAAiB,OAAO;AACtD,YAAU,MAAM;AACd,eAAW,YAAY,OAAO,GAAG,CAAC;AAAA,EACpC,GAAG,CAAC,aAAa,GAAG,CAAC;AACrB,SAAO;AACT;","names":[]}

package/dist/types-BWOV7ULO.d.ts

@@ -0,0 +1,29 @@
+/** One arm. `weight` is relative to its siblings (default 1). */
+type Variant = {
+    id: string;
+    label?: string;
+    weight?: number;
+};
+/**
+ * One experiment, as declared by the app that SERVES it (law 3). Readers do
+ * not need this — they discover arms from the data.
+ */
+type Experiment = {
+    /** Stable key. Becomes the dimension id downstream (`exp_<key>`). */
+    key: string;
+    label?: string;
+    /** false → everyone gets the control and nothing is recorded (law 6). */
+    enabled: boolean;
+    /** Share of subjects allowed INTO the test, 0..1 (default 1). */
+    rollout?: number;
+    /** Arm served to everyone outside the test. Must be one of `variants`. */
+    control: string;
+    variants: readonly Variant[];
+    description?: string;
+    /** ISO date the experiment started serving — the marker on a funnel's timeline. */
+    since?: string;
+};
+/** `{ [key]: variantId }` — what a subject was shown. */
+type Assignments = Readonly<Record<string, string>>;
+
+export type { Assignments as A, Experiment as E, Variant as V };

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@loic001/experiments",
+  "version": "0.1.0",
+  "description": "Experiment kernel: a stable arm per subject, exposure as the denominator, and a verdict that refuses to speak too early. The registry serves; the data judges.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser/index.d.ts",
+      "default": "./dist/browser/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "PRINCIPLES.md"
+  ],
+  "sideEffects": false,
+  "license": "MIT",
+  "author": "loic001",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "experiment",
+    "ab-test",
+    "feature-flag",
+    "funnel",
+    "tracking"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/loic001/experiments.git"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "build": "tsup",
+    "prepublishOnly": "npm run typecheck && npm run coverage && npm run build"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "react": "^19.2.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.5.0",
+    "vitest": "^3.2.4"
+  }
+}