@variantlab/core 0.1.4 → 0.1.6

package/docs/phases/phase-2-expansion.md

@@ -0,0 +1,307 @@
+# Phase 2 — Expansion (v0.2)
+
+**Status**: Not started
+**Goal**: Broaden framework coverage and add power-user features that didn't make the MVP cut.
+**Target version**: `0.2.0`
+
+## Table of contents
+
+- [Exit criteria](#exit-criteria)
+- [Scope](#scope)
+- [New packages](#new-packages)
+- [Core improvements](#core-improvements)
+- [CLI improvements](#cli-improvements)
+- [Documentation](#documentation)
+- [Milestones](#milestones)
+
+---
+
+## Exit criteria
+
+Phase 2 is done when:
+
+1. `@variantlab/remix` is published and tested in a production-style example
+2. `@variantlab/vue` is published with a composition API that matches the hooks API
+3. `@variantlab/vanilla` (framework-free) is published
+4. Devtools browser extension scaffolding exists (beta)
+5. Telemetry interface is finalized and at least one reference adapter is shipped
+6. `variantlab distribution` simulation command works
+7. Core supports server-sent events (SSE) for live config push (optional)
+8. All framework examples still pass CI
+9. Migration from v0.1 → v0.2 is documented
+
+---
+
+## Scope
+
+### Remix adapter (`@variantlab/remix`)
+
+- [ ] Server helpers: `getVariantLoader`, `variantLabMiddleware`
+- [ ] `<VariantLabProvider>` with loader data hydration
+- [ ] Cookie-based sticky assignment (reuses Next.js adapter logic)
+- [ ] Works on Remix SPA mode and SSR mode
+- [ ] Example app in `examples/remix-app`
+
+### Vue adapter (`@variantlab/vue`)
+
+- [ ] `<VariantLabProvider>` component
+- [ ] `useVariant(id)` composable
+- [ ] `useVariantValue(id)` composable
+- [ ] `useExperiment(id)` composable
+- [ ] `useRouteExperiments()` composable
+- [ ] `<Variant>` component with slots
+- [ ] Reactivity via Vue's `ref`/`computed` bridged to engine `subscribe`
+- [ ] Nuxt module in a separate package (phase 3)
+
+### Vanilla adapter (`@variantlab/vanilla`)
+
+- [ ] No framework dependency
+- [ ] Imperative API: `getVariant`, `getVariantValue`, `setVariant`
+- [ ] DOM helpers: `bindElement(id, ...)` for vanilla-JS sites
+- [ ] Storage adapter for localStorage / sessionStorage
+- [ ] Route watcher for `popstate` + `hashchange`
+- [ ] Example in `examples/vanilla-app` (a static HTML file)
+
+---
+
+## New packages
+
+| Package | Size | Notes |
+|---|---|---|
+| `@variantlab/remix` | ~3 KB | Extends core with Remix-specific loaders |
+| `@variantlab/vue` | ~2 KB | Composition API; hooks with same names as React |
+| `@variantlab/vanilla` | ~1 KB | Framework-free |
+| `@variantlab/telemetry-console` | ~0.5 KB | Reference telemetry adapter that logs to console |
+| `@variantlab/devtools` | Deferred | Chrome/Firefox extension — beta only |
+
+---
+
+## Core improvements
+
+### Targeting enhancements
+
+- [ ] Wildcard prefix matching for locale (`"en*"`)
+- [ ] `appVersion` prerelease support (`>=2.0.0-beta.1`)
+- [ ] `attributes` key globs (`"plan*"`)
+
+These are backward-compatible additions; existing configs still work.
+
+### Config improvements
+
+- [ ] Support `include` field to split configs across files (`experiments/*.json` merged into one)
+- [ ] Support `$ref` for variant value reuse
+- [ ] Per-experiment `startDate`/`endDate` fractional support (interpolate rollout over time)
+
+### Assignment
+
+- [ ] New strategy: `sticky-session` — same variant for the entire session, re-assigned on new session
+- [ ] New strategy: `sticky-device` — per-device stickiness using a generated device ID
+- [ ] Configurable bucket resolution (100 buckets → 10000 buckets for fine-grained splits)
+
+### Telemetry
+
+- [ ] Finalize `Telemetry` interface
+- [ ] Ship reference implementations:
+  - `@variantlab/telemetry-console` — logs to console
+  - `@variantlab/telemetry-posthog` — for PostHog (user hosts their own PostHog)
+- [ ] Document how to integrate with Mixpanel, Amplitude, Segment, custom webhooks
+
+### Live config push
+
+- [ ] SSE-based `createEventSourceFetcher` for push updates
+- [ ] WebSocket-based `createWebSocketFetcher` (optional)
+- [ ] Config change events surface in debug overlay
+
+This is optional — most users can poll every 60s.
+
+---
+
+## CLI improvements
+
+### `variantlab distribution`
+
+Simulate variant distribution for a config:
+
+```bash
+variantlab distribution experiments.json \
+  --experiment cta-copy \
+  --users 10000
+```
+
+Output: table of variant IDs with actual/expected percentages. Useful for verifying splits.
+
+### `variantlab eval`
+
+Add filtering and batch mode:
+
+```bash
+variantlab eval experiments.json \
+  --experiments cta-copy,card-layout \
+  --context-file ./test-contexts.json
+```
+
+### `variantlab diff`
+
+Compare two configs:
+
+```bash
+variantlab diff old.json new.json
+```
+
+Shows added/removed/changed experiments.
+
+### `variantlab migrate`
+
+Upgrade configs across major versions (placeholder for future):
+
+```bash
+variantlab migrate --from 1 --to 2 experiments.json
+```
+
+---
+
+## Documentation
+
+### Migration guides
+
+- `docs/migrations/v0.1-to-v0.2.md` — what changed, what to update
+- `docs/migrations/from-firebase.md` — migrating from Firebase Remote Config
+- `docs/migrations/from-growthbook.md` — migrating from GrowthBook
+- `docs/migrations/from-launchdarkly.md` — migrating from LaunchDarkly
+
+### Adapter cookbooks
+
+- `docs/adapters/remix.md`
+- `docs/adapters/vue.md`
+- `docs/adapters/vanilla.md`
+
+Each cookbook shows:
+
+- Install
+- Provider setup
+- Using hooks/composables
+- SSR pattern
+- Debug overlay integration
+- Common pitfalls
+
+### Tutorial
+
+- `docs/tutorial/first-experiment.md` — a 10-minute walkthrough for new users
+- `docs/tutorial/multivariate-layout.md` — building a Drishtikon-style layout test
+- `docs/tutorial/feature-flags.md` — using variantlab as feature flags
+
+---
+
+## Milestones
+
+### M1: Remix adapter
+
+- Package scaffolding
+- Loader-based SSR
+- Cookie handling
+- Example app
+- Tests
+
+Gate: example deployed to Remix's deploy target, no hydration issues.
+
+### M2: Vue adapter
+
+- Package scaffolding
+- Composition API composables
+- Component shims
+- Example SFC app (Vite + Vue)
+- Tests
+
+Gate: composables reactive, debug overlay renders in Vue.
+
+### M3: Vanilla adapter
+
+- Framework-free core wrapper
+- DOM bindings
+- Example static HTML
+- Tests
+
+Gate: static example works in all evergreen browsers.
+
+### M4: CLI distribution + diff + migrate
+
+- `distribution` command with statistical output
+- `diff` command with readable delta
+- `migrate` command stub (no actual migrations yet)
+- Tests
+
+Gate: CLI commands exit with correct codes on all expected inputs.
+
+### M5: Telemetry interface + reference adapters
+
+- Finalize `Telemetry` interface (no breaking changes in phase 3+)
+- Ship console adapter
+- Ship posthog adapter
+- Integration tests
+
+Gate: end-to-end telemetry flow from hook call → posthog event.
+
+### M6: Live config push (optional)
+
+- SSE fetcher
+- Event subscription in debug overlay
+- Example with a small SSE server
+
+Gate: a config change on the server appears in the app within 1 second. This is optional; if it adds > 500 bytes to core, defer to phase 3.
+
+### M7: v0.2.0 release
+
+- Changeset + changelog
+- Migration guides
+- Publish to npm
+
+Gate: all new packages pass size checks, tests, and publint.
+
+---
+
+## Non-goals
+
+Explicitly **not** in phase 2:
+
+- ❌ Svelte / SvelteKit (phase 3)
+- ❌ Solid / SolidStart (phase 3)
+- ❌ Astro (phase 3)
+- ❌ Nuxt module (phase 3)
+- ❌ HMAC signing (phase 4)
+- ❌ Crash rollback persistence (phase 4)
+- ❌ Time travel replay (phase 4)
+- ❌ Devtools full implementation (phase 3)
+- ❌ Hosted dashboard (never)
+
+---
+
+## Risks
+
+### Risk: Vue reactivity doesn't map cleanly to `subscribe`
+
+Mitigation: study how Pinia and VueUse bridge external state. If hooks feel wrong in Vue, we adjust the composable shapes without touching core.
+
+### Risk: Remix loader + client variant mismatch
+
+Mitigation: strict cookie-based stickiness. The loader sets the cookie, the client reads it. No client-side randomness.
+
+### Risk: Telemetry interface is wrong and we can't change it
+
+Mitigation: finalize only after shipping 2 reference adapters that use it. If both work, the interface is probably right.
+
+### Risk: Scope creep
+
+Mitigation: strict "phase 2 is only these items" discipline. New ideas go to phase 3 or later.
+
+---
+
+## Transition to phase 3
+
+Phase 2 exits when:
+
+- All exit criteria met
+- v0.2.0 is tagged and published
+- Migration guides written
+- No regressions in phase 1 packages
+
+Phase 3 starts with: the remaining framework ecosystem (Svelte, Solid, Astro, Nuxt) and full devtools. See [`phase-3-ecosystem.md`](./phase-3-ecosystem.md).

package/docs/phases/phase-3-ecosystem.md

@@ -0,0 +1,289 @@
+# Phase 3 — Ecosystem (v0.3)
+
+**Status**: Not started
+**Goal**: Reach every major frontend framework and ship the devtools extension.
+**Target version**: `0.3.0`
+
+## Table of contents
+
+- [Exit criteria](#exit-criteria)
+- [Framework adapters](#framework-adapters)
+- [Devtools extension](#devtools-extension)
+- [Meta-framework integrations](#meta-framework-integrations)
+- [Quality of life](#quality-of-life)
+- [Milestones](#milestones)
+
+---
+
+## Exit criteria
+
+Phase 3 is done when:
+
+1. `@variantlab/svelte` is published
+2. `@variantlab/sveltekit` is published
+3. `@variantlab/solid` is published
+4. `@variantlab/solid-start` is published
+5. `@variantlab/astro` is published
+6. `@variantlab/nuxt` is published
+7. `@variantlab/devtools` Chrome/Firefox extension is in beta
+8. At least one community contribution has been merged
+9. Adapter sizes meet budgets
+10. Each adapter has a working example app
+11. Documentation covers all adapters uniformly
+
+---
+
+## Framework adapters
+
+### Svelte (`@variantlab/svelte`)
+
+- [ ] `<VariantLabProvider>` component (Svelte 5 runes-ready)
+- [ ] `useVariant(id)` as a Svelte store + `$` auto-subscribe
+- [ ] `useVariantValue(id)` store
+- [ ] `<Variant>` with named slots for each variant
+- [ ] Store reactivity via engine `subscribe`
+- [ ] Works on Svelte 4 and Svelte 5
+- [ ] Example in `examples/svelte-app`
+
+### SvelteKit (`@variantlab/sveltekit`)
+
+- [ ] Server hooks (`handle`) for context extraction
+- [ ] Load function helpers for SSR
+- [ ] Cookie-based sticky assignment
+- [ ] Edge adapter compatibility
+- [ ] Example in `examples/sveltekit-app`
+
+### Solid (`@variantlab/solid`)
+
+- [ ] `<VariantLabProvider>` component
+- [ ] `useVariant(id)` as a Solid accessor
+- [ ] `useVariantValue(id)` accessor
+- [ ] `<Variant>` with children-as-function signal
+- [ ] Reactivity via `createSignal` bridged to engine `subscribe`
+- [ ] Example in `examples/solid-app`
+
+### SolidStart (`@variantlab/solid-start`)
+
+- [ ] Server-side variant resolution
+- [ ] `createServerAction$` integration
+- [ ] Cookie-based stickiness
+- [ ] Example in `examples/solid-start-app`
+
+### Astro (`@variantlab/astro`)
+
+- [ ] Astro integration plugin
+- [ ] Server-side rendering helpers
+- [ ] Client-island hydration
+- [ ] Works with any framework island (React, Vue, Svelte, Solid)
+- [ ] View transitions integration
+- [ ] Example in `examples/astro-app`
+
+### Nuxt (`@variantlab/nuxt`)
+
+- [ ] Nuxt module (`addPlugin`, `addImportsDir`)
+- [ ] Auto-imported composables
+- [ ] Server-side rendering via `nuxt/server`
+- [ ] Config pushed via runtime config
+- [ ] Example in `examples/nuxt-app`
+
+---
+
+## Devtools extension
+
+### Chrome / Firefox / Edge extension
+
+- [ ] Manifest V3
+- [ ] Attaches to pages with `@variantlab/react` (or other adapters) loaded
+- [ ] Panel in DevTools showing:
+  - [ ] Active experiments on the current page
+  - [ ] Current variant of each
+  - [ ] Override controls
+  - [ ] History timeline
+  - [ ] Config viewer
+  - [ ] Context inspector
+- [ ] No network calls — all local
+- [ ] No data collection
+- [ ] Open source in the same monorepo
+- [ ] Published to Chrome Web Store + Firefox Add-ons
+
+### Implementation sketch
+
+The devtools extension uses the existing engine's `subscribe` + `getHistory` + `getExperiments` API. It talks to the page via `window.postMessage` and reads engine state from `window.__VARIANTLAB__` (exposed in dev builds only).
+
+Security:
+
+- The extension only activates on pages that explicitly expose the devtools hook
+- No data leaves the browser
+- Read-only by default; writes require confirmation
+
+---
+
+## Meta-framework integrations
+
+### TanStack Router
+
+- [ ] Reference integration that syncs route context with TanStack Router's navigation state
+- [ ] Not a separate package — documented in `docs/adapters/tanstack-router.md`
+
+### React Router v7
+
+- [ ] Reference integration with `useLocation`
+- [ ] Documented in `docs/adapters/react-router.md`
+
+### Expo Router v3+
+
+- [ ] Already covered by `@variantlab/react-native`, but document edge cases
+- [ ] `docs/adapters/expo-router.md`
+
+### Ionic + Capacitor
+
+- [ ] Reference integration — mostly just React
+- [ ] Native plugin wrapper for deep links
+- [ ] `docs/adapters/ionic.md`
+
+### Tauri
+
+- [ ] Reference integration for Tauri apps
+- [ ] Custom fetcher that reads from Tauri's filesystem API
+- [ ] `docs/adapters/tauri.md`
+
+### Electron
+
+- [ ] Reference integration
+- [ ] Main process + renderer process separation
+- [ ] `docs/adapters/electron.md`
+
+---
+
+## Quality of life
+
+### Storybook addon (`@variantlab/storybook`)
+
+- [ ] Addon that lets stories select variants via toolbar
+- [ ] Each story can declare its experiment dependencies
+- [ ] Integrates with the existing debug overlay
+- [ ] Example storybook in `examples/storybook`
+
+### Playwright fixtures (`@variantlab/playwright`)
+
+- [ ] Fixture for setting variants in Playwright tests
+- [ ] Helper for asserting which variant is active
+- [ ] Example in `examples/playwright-tests`
+
+### Vitest matchers (`@variantlab/vitest`)
+
+- [ ] `expect(engine).toHaveVariant("foo", "bar")`
+- [ ] `expect(engine).toHaveExposed("foo")`
+- [ ] Mock engine helper
+- [ ] Documented in `docs/tooling/testing.md`
+
+### MSW handlers (`@variantlab/msw`)
+
+- [ ] Mock Service Worker handlers for remote config fetching
+- [ ] Lets tests control what configs get served
+- [ ] Example in `examples/msw-tests`
+
+### `create-variantlab` scaffolder
+
+- [ ] `npm create variantlab@latest`
+- [ ] Prompts for framework, prefers sensible defaults
+- [ ] Generates a working project with example experiment
+
+---
+
+## Milestones
+
+### M1: Svelte + SvelteKit
+
+- Svelte 5 runes support
+- SvelteKit SSR
+- Example apps
+- Tests
+
+### M2: Solid + SolidStart
+
+- Signal-based hooks
+- SSR
+- Example apps
+- Tests
+
+### M3: Astro
+
+- Integration plugin
+- Island hydration
+- Example app
+
+### M4: Nuxt
+
+- Nuxt module
+- Auto-imports
+- Example app
+
+### M5: Devtools extension beta
+
+- Manifest V3 scaffolding
+- Panel UI
+- Read-only support
+- Chrome Web Store submission (beta channel)
+
+### M6: QoL tools
+
+- Storybook addon
+- Playwright fixtures
+- Vitest matchers
+- MSW handlers
+- create-variantlab
+
+### M7: v0.3.0 release
+
+- All adapters published
+- Devtools in beta
+- Changelog + migration notes
+
+---
+
+## Community targets
+
+By the end of phase 3, we want:
+
+- [ ] 10+ external contributors
+- [ ] 5+ example apps in `examples/`
+- [ ] 100+ GitHub stars
+- [ ] 1000+ weekly downloads on npm
+- [ ] 1+ blog post from a user
+- [ ] 1+ conference talk (any size)
+
+These are "hope so" targets, not gates.
+
+---
+
+## Risks
+
+### Risk: framework coverage becomes a maintenance burden
+
+Mitigation: each adapter is < 200 LOC and shares 95% of its code via `@variantlab/core`. Core changes ripple to all adapters. Adapter-specific bugs stay in adapters.
+
+### Risk: devtools extension is harder than expected
+
+Mitigation: ship a minimal panel first (read-only). Interactive features come later if the read-only version is useful.
+
+### Risk: Astro's island model doesn't fit our API
+
+Mitigation: Astro users primarily use React/Vue/Svelte inside islands. The Astro adapter is thin — it provides the Provider at the island boundary, and the framework adapter does the rest.
+
+### Risk: Nuxt auto-imports collide with user code
+
+Mitigation: namespace all composables under a `vl` prefix option. Users can opt out of auto-imports.
+
+---
+
+## Transition to phase 4
+
+Phase 3 exits when:
+
+- All framework adapters published
+- Devtools extension in beta
+- All milestones hit
+- v0.3.0 published
+
+Phase 4 adds advanced features: HMAC signing, crash rollback persistence, time travel replay, statistical features. See [`phase-4-advanced.md`](./phase-4-advanced.md).