@variantlab/core 0.1.4 → 0.1.6

package/docs/research/framework-ssr-quirks.md

@@ -0,0 +1,394 @@
+# Framework SSR quirks
+
+Notes on how each target framework handles server-side rendering, hydration, and the implications for variantlab. This document is the reference for implementing each adapter.
+
+## Table of contents
+
+- [Common concerns](#common-concerns)
+- [Next.js App Router](#nextjs-app-router)
+- [Next.js Pages Router](#nextjs-pages-router)
+- [Remix](#remix)
+- [SvelteKit](#sveltekit)
+- [SolidStart](#solidstart)
+- [Nuxt](#nuxt)
+- [Astro](#astro)
+- [React Native](#react-native)
+- [Edge runtime targets](#edge-runtime-targets)
+
+---
+
+## Common concerns
+
+Every SSR framework has the same core problem for A/B testing: the server renders one variant, the client hydrates, and if the client picks a different variant, React/Vue/Svelte throws a hydration mismatch error.
+
+### Solutions available
+
+1. **Sticky cookie**: server sets a cookie with the variant assignment; client reads the same cookie on hydration.
+2. **Streaming with suspense**: server holds rendering until it knows the variant; client streams the result.
+3. **Defer to client**: render a placeholder on server, pick the variant on client. This is the easy way but causes layout shift.
+4. **Edge middleware**: assign the variant at the edge before the request hits the renderer, then pass it via headers.
+
+variantlab supports all four, with sticky cookie as the recommended default.
+
+### Invariants variantlab must uphold
+
+- **Deterministic assignment**: given the same `(userId, experimentId, context)`, always produce the same variant.
+- **No `Math.random()` on the hot path**: non-deterministic → hydration mismatches.
+- **No `Date.now()` in pure assignment**: time-based targeting only at evaluation boundaries.
+- **Stable ordering of experiments**: iteration order must match server and client.
+- **No environment-specific branches in assignment logic**: server code must match client code byte-for-byte.
+
+---
+
+## Next.js App Router
+
+Next.js 14/15 App Router uses React Server Components (RSC). Server components can read variants freely; client components need a context.
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│  middleware.ts                                   │
+│  Reads cookies, sets sticky variant cookie       │
+└──────────────┬──────────────────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────────────────┐
+│  app/layout.tsx (Server Component)               │
+│  Reads cookies via next/headers                  │
+│  Creates initial variant map                      │
+│  Wraps children in VariantLabProvider            │
+│  (client component, re-hydrates from initial map)│
+└──────────────┬──────────────────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────────────────┐
+│  Server components: read via getVariantSSR()    │
+│  Client components: useVariant() hook            │
+└──────────────────────────────────────────────────┘
+```
+
+### Our implementation
+
+- **Middleware** sets a cookie `variantlab_v1` containing an encoded map of `(experimentId → variantId)` for eligible experiments
+- **Root layout** reads the cookie via `cookies()` from `next/headers`, decodes it, and passes it to `<VariantLabProvider initialVariants={...}>`
+- **Server components** import `getVariantSSR(experimentId, cookies())` which is a pure function
+- **Client components** use the React hooks via the provider
+
+### Pitfalls
+
+1. **Dynamic vs static rendering.** If a page reads cookies, Next.js marks it as dynamic. This affects caching. We document this clearly.
+2. **RSC boundary.** `VariantLabProvider` must be a client component. We re-export it from `@variantlab/next/client` with `"use client"` directive.
+3. **Cookie size.** Next.js cookies are limited to 4 KB. If you have many experiments, we compress the cookie (base64-encoded minified JSON, or pack variant IDs as small integers).
+4. **Parallel routes and intercepting routes.** These can render the same provider multiple times. Our provider detects this and de-duplicates.
+
+### Example
+
+```tsx
+// middleware.ts
+import { variantLabMiddleware } from "@variantlab/next/middleware";
+import config from "./experiments.json";
+
+export default variantLabMiddleware(config);
+export const config = { matcher: ["/((?!_next|api).*)"] };
+
+// app/layout.tsx
+import { cookies } from "next/headers";
+import { VariantLabProvider } from "@variantlab/next/client";
+import experiments from "./experiments.json";
+
+export default function RootLayout({ children }) {
+  const cookieStore = cookies();
+  const initialVariants = JSON.parse(
+    cookieStore.get("variantlab_v1")?.value ?? "{}"
+  );
+  return (
+    <html>
+      <body>
+        <VariantLabProvider
+          config={experiments}
+          initialVariants={initialVariants}
+        >
+          {children}
+        </VariantLabProvider>
+      </body>
+    </html>
+  );
+}
+
+// app/page.tsx (server component)
+import { getVariantSSR } from "@variantlab/next";
+import experiments from "./experiments.json";
+
+export default async function Page() {
+  const cookieStore = cookies();
+  const variant = getVariantSSR("cta-copy", cookieStore, experiments);
+  return <button>{variant === "buy-now" ? "Buy now" : "Get started"}</button>;
+}
+```
+
+---
+
+## Next.js Pages Router
+
+Older model. Simpler but less flexible.
+
+### Architecture
+
+- `getServerSideProps` reads cookies, picks variant, passes as prop
+- `_app.tsx` wraps in `<VariantLabProvider>` with initial variants
+- Client hooks work as in any React app
+
+### Example
+
+```tsx
+// pages/_app.tsx
+import { VariantLabProvider } from "@variantlab/next/client";
+import experiments from "../experiments.json";
+
+export default function MyApp({ Component, pageProps }) {
+  return (
+    <VariantLabProvider
+      config={experiments}
+      initialVariants={pageProps.variantlab ?? {}}
+    >
+      <Component {...pageProps} />
+    </VariantLabProvider>
+  );
+}
+
+// pages/index.tsx
+import { getVariantSSR } from "@variantlab/next";
+import experiments from "../experiments.json";
+
+export async function getServerSideProps({ req, res }) {
+  const variant = getVariantSSR("cta-copy", req, experiments);
+  return {
+    props: {
+      variantlab: { "cta-copy": variant },
+    },
+  };
+}
+```
+
+### Pitfalls
+
+- `getStaticProps` cannot run variant assignment (no cookies). Users must use `getServerSideProps` or client-side assignment.
+
+---
+
+## Remix
+
+Remix uses loaders for server-side data fetching. Loaders run on every request, making them ideal for variant assignment.
+
+### Architecture
+
+- A root loader reads cookies, creates an initial variant map, returns it
+- `<VariantLabProvider>` wraps the root
+- Action functions can also read variants
+
+### Example
+
+```tsx
+// app/root.tsx
+import { json } from "@remix-run/node";
+import { useLoaderData } from "@remix-run/react";
+import { VariantLabProvider } from "@variantlab/remix";
+import experiments from "./experiments.json";
+import { parseVariantCookie } from "@variantlab/remix/server";
+
+export async function loader({ request }) {
+  const cookieHeader = request.headers.get("Cookie") ?? "";
+  const initialVariants = parseVariantCookie(cookieHeader);
+  return json({ initialVariants });
+}
+
+export default function App() {
+  const { initialVariants } = useLoaderData<typeof loader>();
+  return (
+    <VariantLabProvider config={experiments} initialVariants={initialVariants}>
+      <Outlet />
+    </VariantLabProvider>
+  );
+}
+```
+
+### Pitfalls
+
+- Remix nested routes mean the provider sits at the root. Inner routes cannot create their own provider without duplicating state.
+- Action functions that redirect must re-set the variant cookie, otherwise the next loader will re-assign.
+
+---
+
+## SvelteKit
+
+SvelteKit uses `load` functions (server and client) and hooks.
+
+### Architecture
+
+- `src/hooks.server.ts` uses `handle` to read cookies and set a local variant context
+- `src/routes/+layout.server.ts` exposes the variant map via `event.locals.variantlab`
+- `src/routes/+layout.svelte` wraps children in `<VariantLabProvider>`
+
+### Example
+
+```ts
+// src/hooks.server.ts
+import type { Handle } from "@sveltejs/kit";
+import { createEngine } from "@variantlab/core";
+import experiments from "../experiments.json";
+
+export const handle: Handle = async ({ event, resolve }) => {
+  const engine = createEngine(experiments, { storage: event.cookies });
+  event.locals.variantlab = engine;
+  return resolve(event);
+};
+```
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script>
+  import { VariantLabProvider } from "@variantlab/svelte";
+  import experiments from "../experiments.json";
+  export let data;
+</script>
+
+<VariantLabProvider config={experiments} initialVariants={data.variantlab}>
+  <slot />
+</VariantLabProvider>
+```
+
+### Pitfalls
+
+- Svelte 4 vs Svelte 5 have different runes. We support both with separate entry points.
+- `$app/stores` vs `$app/state` (Svelte 5) — we abstract over both.
+
+---
+
+## SolidStart
+
+Solid is similar to React but uses fine-grained reactivity via signals.
+
+### Architecture
+
+- `createVariantLabEngine` returns a signal-based store
+- `useVariant` returns an accessor function (not a value directly)
+- `<VariantLabProvider>` is a regular component
+
+### Pitfalls
+
+- Solid's reactivity graph is different from React's. We must not use React's `useSyncExternalStore`-style pattern; instead we create signals.
+- SSR in SolidStart uses `createAsync` and `isServer` checks. We handle both.
+
+---
+
+## Nuxt
+
+Vue 3 meta-framework. Uses Nitro server routes and the Vue composition API.
+
+### Architecture
+
+- `nuxt.config.ts` installs `@variantlab/nuxt` module
+- Module auto-imports `useVariant()` composable
+- Server-side: `event.context.variantlab` via Nitro middleware
+- Client-side: `<VariantLabProvider>` via plugin
+
+### Pitfalls
+
+- Nuxt's auto-import can cause name collisions. We prefix our composables with `useVariant*` to minimize conflict.
+- Server and client must share the same engine state via `useState`-style hydration.
+
+---
+
+## Astro
+
+Astro uses "islands" — interactive components inside a mostly-static HTML page. Different framework islands can coexist on the same page.
+
+### Architecture
+
+- `astro.config.mjs` installs `@variantlab/astro` integration
+- Pages and components read variants via `Astro.locals.variantlab` at build/request time
+- Islands hydrate with initial variants passed as props
+
+### Pitfalls
+
+- Each island is its own framework instance (React island, Vue island, etc.). Each needs its own provider hydration.
+- SSG vs SSR: for static pages, variant selection happens at build time or at the edge middleware layer.
+
+---
+
+## React Native
+
+No SSR. Simpler, but has its own quirks.
+
+### Architecture
+
+- `<VariantLabProvider>` wraps the app
+- Storage uses AsyncStorage / MMKV / SecureStore
+- Debug overlay uses RN native components
+- Deep link handler integrates with Expo Linking or React Navigation
+
+### Pitfalls
+
+1. **Hermes optimization**: Some JS features that work in V8 don't optimize well in Hermes. We avoid `Proxy` in hot paths.
+2. **New Architecture (Fabric) compatibility**: We test against both Old and New architectures.
+3. **Offline**: storage reads can fail. We fall back to in-memory defaults.
+4. **AsyncStorage vs MMKV**: AsyncStorage is async, MMKV is sync. We handle both in the `Storage` interface.
+5. **Expo Go vs bare**: some APIs (SecureStore) are available only in custom dev builds. We document this clearly.
+
+---
+
+## Edge runtime targets
+
+### Cloudflare Workers
+
+- Web API subset (no Node built-ins)
+- `crypto.subtle` available — our HMAC verification works out of the box
+- KV storage for remote config caching
+- 1 MB unzipped bundle limit — our 3 KB target is well within
+
+### Vercel Edge
+
+- Similar to Cloudflare Workers
+- `NextRequest` / `NextResponse` APIs
+- Middleware runs at the edge — perfect for cookie-based assignment
+
+### Deno Deploy
+
+- Full Deno runtime
+- `crypto.subtle` available
+- Standard Web Fetch API
+
+### Bun
+
+- Mostly Node-compatible
+- Bun's fast `Bun.hash` can optionally be used for sticky assignment (gated behind a check)
+
+### AWS Lambda@Edge
+
+- Node-based but runs at CloudFront edge
+- Limited execution time (low milliseconds)
+- We fit within the constraints
+
+---
+
+## Implementation priority
+
+Based on framework popularity and user demand, we'll implement SSR support in this order:
+
+1. **Next.js App Router** (Phase 1) — largest audience
+2. **Next.js Pages Router** (Phase 1) — still widely used
+3. **React Native** (Phase 1) — primary audience for our debug overlay killer feature
+4. **Remix** (Phase 2)
+5. **SvelteKit** (Phase 3)
+6. **SolidStart** (Phase 3)
+7. **Nuxt** (Phase 3)
+8. **Astro** (Phase 3)
+
+---
+
+## See also
+
+- [`API.md`](../../API.md#variantlabnext) — the SSR API surface
+- [`docs/features/hmac-signing.md`](../features/hmac-signing.md) — Web Crypto API usage
+- [`ARCHITECTURE.md`](../../ARCHITECTURE.md#runtime-data-flow) — engine data flow

package/docs/research/naming-rationale.md

@@ -0,0 +1,238 @@
+# Naming rationale
+
+Why `variantlab`, what we considered, and what still needs validation.
+
+## Table of contents
+
+- [Current pick](#current-pick)
+- [Requirements](#requirements)
+- [Candidates considered](#candidates-considered)
+- [Why variantlab won](#why-variantlab-won)
+- [Risks](#risks)
+- [Final validation checklist](#final-validation-checklist)
+
+---
+
+## Current pick
+
+**`variantlab`** — npm scope `@variantlab/*`, domain `variantlab.dev`.
+
+The name captures three things:
+
+1. **Variant** — the unit of work. Not "flags", not "experiments", not "tests". A variant is a thing a user sees.
+2. **Lab** — a place for controlled experimentation. Evokes the scientific rigor we want to bring to UX.
+3. **Neutral** — works for feature flags, A/B tests, gradual rollouts, and UX experiments alike.
+
+---
+
+## Requirements
+
+Before deciding, we listed what the name had to support:
+
+1. **Short enough to type** — under 12 characters ideally
+2. **Available on npm** — the `@name/*` scope must be free
+3. **Available domain** — `.dev` or `.io` at minimum
+4. **Available on GitHub** — organization name free
+5. **Pronounceable** — non-native English speakers can say it
+6. **Not a trademark** — no existing company with a clashing name
+7. **Memorable** — sticks in the head
+8. **Searchable** — has unique search results, not drowned by a common word
+9. **Extensible** — `@name/core`, `@name/react`, etc. all read well
+10. **Neutral connotation** — no religion, no politics, no culture-specific meanings
+
+---
+
+## Candidates considered
+
+We went through ~30 names. Here are the serious contenders:
+
+### `variantlab`
+
+**Pros**: Captures the concept, neutral, scientific, 10 chars, `@variantlab/react` reads well.
+**Cons**: Slightly generic, may be confused with lab equipment brands.
+**npm `@variantlab` scope**: needs to be claimed.
+**variantlab.dev**: needs to be registered.
+
+### `flagkit`
+
+**Pros**: Very short (7 chars), memorable, "kit" implies bundled tools.
+**Cons**: "flag" has political/territorial connotations that could be misread. Narrows the concept to feature flags when we want to cover A/B testing, gradual rollout, and UI experiments.
+**Verdict**: Too narrow.
+
+### `shift`
+
+**Pros**: 5 chars, bold, evokes "shifting variants".
+**Cons**: Almost certainly taken on npm. Overloaded meaning (keyboard shift, shift left, etc.).
+**Verdict**: Too common.
+
+### `omniflag`
+
+**Pros**: "Omni" captures universal framework support.
+**Cons**: 8 chars + "flag" issue. Sounds like an enterprise brand.
+**Verdict**: Too corporate.
+
+### `polyvariant`
+
+**Pros**: Scientific, captures multi-variant testing, unique.
+**Cons**: 11 chars + hard to spell + "poly" sounds prefix-y.
+**Verdict**: Too academic.
+
+### `labkit`
+
+**Pros**: Short, evokes tooling.
+**Cons**: Almost certainly taken (common laboratory supply brand).
+**Verdict**: Trademark risk.
+
+### `flaglab`
+
+**Pros**: Combines "flag" and "lab".
+**Cons**: Narrow (see flag issue), and npm scope likely taken.
+**Verdict**: Ruled out.
+
+### `expt`
+
+**Pros**: 4 chars, techy.
+**Cons**: Looks like a typo. Hard to pronounce.
+**Verdict**: Too cute.
+
+### `variox`
+
+**Pros**: Unique, 6 chars, no existing trademark.
+**Cons**: Invented word, not immediately meaningful.
+**Verdict**: Backup option.
+
+### `hypothesize`
+
+**Pros**: Scientific, unique.
+**Cons**: 11 chars, hard to type repeatedly.
+**Verdict**: Too long.
+
+### `tryout`
+
+**Pros**: Short, friendly, captures "trying variants".
+**Cons**: Lacks technical gravitas, probably taken.
+**Verdict**: Too casual.
+
+### `abx`
+
+**Pros**: 3 chars, technical.
+**Cons**: Mysterious, not memorable, possibly medical connotation (antibiotic).
+**Verdict**: Too cryptic.
+
+### `testlab`
+
+**Pros**: Self-explanatory.
+**Cons**: Generic, "test" is overloaded with unit testing. Probably taken.
+**Verdict**: Too generic.
+
+### `switchboard`
+
+**Pros**: Evokes a control panel.
+**Cons**: 11 chars, dated metaphor.
+**Verdict**: Too long.
+
+### `stageset`
+
+**Pros**: Evokes staging variants.
+**Cons**: Unclear meaning, 8 chars.
+**Verdict**: Confusing.
+
+### `exposure`
+
+**Pros**: Technical term from experimentation (exposure events).
+**Cons**: 8 chars, also has negative connotations (exposure to risk, exposure of data).
+**Verdict**: Mixed signal.
+
+---
+
+## Why variantlab won
+
+Looking at the shortlist:
+
+| Name | Length | Meaningful | Neutral | Extensible | Available? |
+|---|---:|:-:|:-:|:-:|:-:|
+| variantlab | 10 | ✅ | ✅ | ✅ | TBD |
+| polyvariant | 11 | ✅ | ✅ | ✅ | Likely |
+| variox | 6 | Partial | ✅ | ✅ | Likely |
+| flagkit | 7 | Narrow | Neutral | ✅ | TBD |
+| shift | 5 | Partial | ✅ | ❌ | Unlikely |
+
+`variantlab` edges out `polyvariant` on pronounceability and `variox` on meaning. It beats `flagkit` by not pigeonholing us into feature flags.
+
+The package-family reads nicely:
+
+- `@variantlab/core`
+- `@variantlab/react`
+- `@variantlab/react-native`
+- `@variantlab/next`
+- `@variantlab/cli`
+- `@variantlab/devtools`
+
+The tagline writes itself: *"Every framework. Zero lock-in. One lab."*
+
+---
+
+## Risks
+
+### Risk 1 — npm scope taken
+
+We need to verify `@variantlab` is free on npm before committing. If it's taken but inactive, we might be able to request it via npm support. If actively used, we need a backup.
+
+**Backup plan**: If `@variantlab` is unavailable, fall back to `@variox/*` or `@lab-variant/*`.
+
+### Risk 2 — trademark conflict
+
+"Variant Lab" may exist as a company name in biotech or marketing. We need a trademark check before launching publicly.
+
+**Backup plan**: Add a distinctive suffix if needed (`variantlab.dev` domain clarifies context).
+
+### Risk 3 — SEO
+
+"variant" and "lab" are both common words. Initial Google searches may be noisy. We plan to claim the name via:
+
+- GitHub organization
+- npm scope
+- `.dev` domain
+- Twitter / Mastodon / Bluesky handles
+- Product Hunt launch
+
+### Risk 4 — Misinterpretation
+
+Some readers might assume "lab" means unstable or experimental (like Chrome flags). We mitigate by emphasizing "stable once shipped" in the tagline and README.
+
+---
+
+## Final validation checklist
+
+Before we commit to the name in code:
+
+- [ ] Verify `@variantlab` is free on npm
+- [ ] Register `variantlab.dev`
+- [ ] Create GitHub organization `variantlab`
+- [ ] Reserve handles on Twitter, Bluesky, Mastodon, LinkedIn
+- [ ] Run a trademark search in US, EU, and India
+- [ ] Socialize the name in a GitHub discussion for community feedback
+- [ ] Verify no existing OSS project uses the name actively
+
+If any of these fail, we fall back to the shortlist in order: `polyvariant` → `variox` → a new brainstorm.
+
+---
+
+## Fallback: invent a word
+
+If all pre-existing candidates fail, we invent one. Requirements for an invented name:
+
+- 5-8 characters
+- Pronounceable in English, Spanish, and Hindi
+- No existing meaning in any major language (verified via Wiktionary)
+- Clean trademark search
+- `.dev` domain available
+- Short npm scope available
+
+Candidates if we go this route: `varex`, `expio`, `experi`, `splitly`, `sprou`.
+
+---
+
+## Decision
+
+**Go with `variantlab` pending the validation checklist.** If blocked, revisit this document.