@scalebun-release/web 2.2.2

package/dist/features/config/ConfigFeature.d.ts

@@ -0,0 +1,117 @@
+/**
+ * F-CFG — Config & Flags. Fetches GET /config (feature flags, remote config, experiments, rollouts,
+ * entitlements) with ETag/304 caching, persists it (flags available synchronously on next load), and
+ * evaluates flags/rollouts/experiments LOCALLY with deterministic fnv1a32 bucketing (the backend never
+ * assigns — see bucketing.ts; parity with RN + backend is a hard gate). Experiment exposure flows
+ * through the normal event lane: variant() emits one `experiment_exposure` event per (install, key).
+ *
+ * Zero third-party deps (web SDK core rule). Tiny + core (not lazy) — flags must resolve early/sync.
+ */
+import type { IFeature, FeatureContext } from '@scalebun/sdk-contracts';
+import { type VariationDetail } from './types.js';
+export declare class ConfigFeature implements IFeature {
+    readonly name = "config";
+    private ctx;
+    private active;
+    private payload;
+    private exposed;
+    private deviceId;
+    private clientKey;
+    private apiBaseUrl;
+    private lastFetch;
+    private onVisible?;
+    private es?;
+    private overrides;
+    private changeListeners;
+    private settled;
+    private resolveReady?;
+    private readyPromise;
+    get isActive(): boolean;
+    setup(ctx: FeatureContext): void;
+    /** F4 — subscribe to the realtime config stream. Each `change` nudge triggers an ETag-aware refresh()
+     *  (which no-ops on 304), so a kill-switch flip propagates in seconds; `ping` frames just keep-alive.
+     *  EventSource auto-reconnects on drop; SSR / no-EventSource envs simply skip it (foreground poll stays). */
+    private openStream;
+    /** F3 — coerce the loose bootstrap shape into a payload (null when absent/empty). */
+    private seedFromBootstrap;
+    private markReady;
+    private emitChange;
+    /** Re-fetch /config (ETag-aware). Keeps the cached payload on 304 / error (offline-safe). Fires
+     *  onChange listeners when a new version is applied (F3). */
+    refresh(): Promise<void>;
+    /** Resolves once the first config fetch settles (immediately when there's no network configured).
+     *  Bootstrap/cache make flags usable synchronously before this; ready() means "freshest attempted". */
+    ready(): Promise<void>;
+    /** Subscribe to config changes (a new version applied on refresh, or an override set/cleared).
+     *  Returns an unsubscribe fn. */
+    onChange(cb: () => void): () => void;
+    /** QA/dev: force a flag/experiment/rollout to a value locally (persisted). A string is matched
+     *  against a multivariate flag's variation keys; otherwise it's the served value verbatim. */
+    override(key: string, value: unknown): void;
+    clearOverride(key: string): void;
+    clearOverrides(): void;
+    private hasOverride;
+    /** F1 — the stable unit to bucket on. An explicit per-feature `bucketBy` context attribute always wins
+     *  (e.g. 'group_company' to flip a whole account together).
+     *
+     *  Otherwise the identity unit, and there are two, because they trade against each other:
+     *
+     *   - `deviceId` (stable): the same value before and after login, so a user NEVER changes variant
+     *     mid-session. This is what the RN SDK buckets on (`installationId`) and what the backend
+     *     aggregates exposures by, so it is also the only option under which web and mobile agree.
+     *   - `userId ?? deviceId` (legacy): gives a logged-in user the same assignment across devices and
+     *     across a storage clear — a genuine feature — but the identity CHANGES at login, which
+     *     re-buckets the user mid-experiment. On any experiment that spans signup that is not noise:
+     *     every converting user crosses the boundary, so the experiment measures the login, not the
+     *     treatment, and one human lands in both arms.
+     *
+     *  Correctness wins: the flip silently invalidates results, while cross-device consistency can be
+     *  recovered deliberately per experiment via `bucketBy: 'userId'`, and multi-device humans are
+     *  folded at analysis time from the backend's identity links.
+     *
+     *  Server-gated because switching re-buckets already-logged-in users once — enabled for new
+     *  experiments first, then globally. Absent ⇒ legacy behaviour, so old payloads are unchanged. */
+    private bucketingId;
+    /** Feature flag — F0: if the flag carries targeting, the first matching rule decides (serve, or a
+     *  per-rule % rollout); no rule matches → the flag's default `enabled`. No targeting → plain boolean.
+     *  F1: the % rollout buckets on the identity unit (or the flag's `bucketBy`), not the raw device.
+     *  F2: for a multivariate flag `isEnabled` is the truthiness of the served value. */
+    /** True when a read of `key` reflects real server config — i.e. the answer is a decision the user
+     *  actually experienced, and therefore an exposure worth recording. False in three cases that all
+     *  look like `false` to a caller but are NOT data:
+     *   - before bootstrap resolves (payload is EMPTY_CONFIG) — an absence of information,
+     *   - for a flag the server has never heard of,
+     *   - for a QA override — staff inspecting the system is not experiment traffic.
+     *  Without this, a first paint records a phantom `false` the user never saw, and the real value
+     *  then emits a second, contradictory exposure. */
+    knows(key: string): boolean;
+    isEnabled(key: string): boolean;
+    /** F2 — resolve a flag's served value with LD-style detail. Boolean flags (no `variations`) resolve to
+     *  their boolean; multivariate flags resolve to a variation's typed value. Precedence: a matching
+     *  targeting rule (TARGETING_MATCH / ROLLOUT) → fallthrough split (ROLLOUT) → default (DEFAULT); an
+     *  unknown flag is FLAG_NOT_FOUND (caller fallback). Never throws — safe defaults at every branch. */
+    variationDetail<T>(key: string, fallback: T): VariationDetail<T>;
+    /** F2 — the served value only (sugar over variationDetail). */
+    variation<T>(key: string, fallback: T): T;
+    /** Remote config value with type coercion + caller fallback (never throws). */
+    get<T>(key: string, fallback: T): T;
+    /** Feature rollout — deterministic percentage gate. F0: a matching targeting rule can override the
+     *  percentage for the matched audience; no match → the rollout's default percentage. */
+    isOn(key: string): boolean;
+    /** F5 — is the identified user in the global experiment holdout? Bucketed on the DEFAULT identity unit
+     *  (uniform across all experiments) so a held-out user is a clean, never-treated baseline everywhere. */
+    private inHoldout;
+    /** F5 — mutual exclusion: within a layer a user owns exactly one 0..99 slot, so only the experiment
+     *  whose `layerRange` covers that slot enrolls them (the rest of the layer excludes them). Bucketed on
+     *  the default identity unit so every experiment in the layer places the user identically. */
+    private inLayerSlot;
+    /** Experiment variant — deterministic; emits one exposure event per (install, key). F0: targeting acts
+     *  as an inclusion filter — no match ⇒ not enrolled (null); a matching rule may override the variant
+     *  set. F5: a global-holdout user, or a user whose layer slot belongs to a different experiment, is not
+     *  enrolled (null, no exposure) — keeping the holdout baseline clean and layers mutually exclusive. */
+    variant(key: string): string | null;
+    /** SDK-suppressible entitlement (fail-open: unknown → on). The bootstrap can gate features on this. */
+    entitlement(key: string): boolean;
+    teardown(): void;
+}
+//# sourceMappingURL=ConfigFeature.d.ts.map

package/dist/features/config/ConfigFeature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConfigFeature.d.ts","sourceRoot":"","sources":["../../../src/features/config/ConfigFeature.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAKxE,OAAO,EAAwD,KAAK,eAAe,EAAE,MAAM,SAAS,CAAC;AAUrG,qBAAa,aAAc,YAAW,QAAQ;IAC5C,QAAQ,CAAC,IAAI,YAAY;IACzB,OAAO,CAAC,GAAG,CAA+B;IAC1C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,QAAQ,CAAM;IACtB,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,UAAU,CAAM;IACxB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,SAAS,CAAC,CAAa;IAC/B,OAAO,CAAC,EAAE,CAAC,CAAc;IAEzB,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,eAAe,CAAyB;IAChD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAAC,CAAa;IAClC,OAAO,CAAC,YAAY,CAA8D;IAElF,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,KAAK,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI;IA4BhC;;iHAE6G;IAC7G,OAAO,CAAC,UAAU;IAmBlB,qFAAqF;IACrF,OAAO,CAAC,iBAAiB;IAezB,OAAO,CAAC,SAAS;IAOjB,OAAO,CAAC,UAAU;IAUlB;iEAC6D;IACvD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAoC9B;2GACuG;IACvG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAGtB;qCACiC;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAMpC;kGAC8F;IAC9F,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAK3C,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAOhC,cAAc,IAAI,IAAI;IAKtB,OAAO,CAAC,WAAW;IAMnB;;;;;;;;;;;;;;;;;;;sGAmBkG;IAClG,OAAO,CAAC,WAAW;IAWnB;;;yFAGqF;IACrF;;;;;;;uDAOmD;IACnD,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI3B,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAe/B;;;0GAGsG;IACtG,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC;IA8ChE,+DAA+D;IAC/D,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC;IAIzC,+EAA+E;IAC/E,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC;IAqBnC;4FACwF;IACxF,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAY1B;6GACyG;IACzG,OAAO,CAAC,SAAS;IAKjB;;kGAE8F;IAC9F,OAAO,CAAC,WAAW;IAOnB;;;2GAGuG;IACvG,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IA0CnC,uGAAuG;IACvG,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAKjC,QAAQ,IAAI,IAAI;CASjB"}

package/dist/features/config/ConfigFeature.js

@@ -0,0 +1,437 @@
+import { now, getEvalContext, patchEvalContext, getReplayCoord } from '../../core/index.js';
+import { bucketOf, pickVariant } from './bucketing.js';
+import { evaluateTargeting } from './targeting.js';
+import { loadConfig, saveConfig, loadOverrides, saveOverrides } from './configStore.js';
+import { EMPTY_CONFIG } from './types.js';
+const TTL_MS = 5 * 60 * 1000; // refresh on foreground past this age (mirror RN)
+/** A flag's bucketing salt. Rule rollouts always hashed on the flag KEY, which meant renaming a flag
+ *  silently re-bucketed its whole population. The server now sends an immutable `salt` (backfilled to
+ *  the key, so nobody moved), and only sends it once it diverges — so falling back to `key` keeps a
+ *  payload from an older server bucketing identically. */
+const saltOf = (f) => f.salt ?? f.key;
+export class ConfigFeature {
+    constructor() {
+        this.name = 'config';
+        this.ctx = null;
+        this.active = false;
+        this.payload = EMPTY_CONFIG;
+        this.exposed = new Set();
+        this.deviceId = '';
+        this.clientKey = '';
+        this.apiBaseUrl = '';
+        this.lastFetch = 0;
+        // F3 — QA overrides, change listeners, readiness.
+        this.overrides = {};
+        this.changeListeners = new Set();
+        this.settled = false;
+        this.readyPromise = new Promise((r) => (this.resolveReady = r));
+    }
+    get isActive() {
+        return this.active;
+    }
+    setup(ctx) {
+        this.ctx = ctx;
+        this.deviceId = ctx.deviceId ?? '';
+        this.clientKey = ctx.clientKey ?? '';
+        this.apiBaseUrl = ctx.apiBaseUrl ?? '';
+        patchEvalContext({ deviceId: this.deviceId }); // F0 — device attr for targeting
+        this.overrides = loadOverrides(); // F3 — dev-forced values persist across reloads
+        // F3 — bootstrap seed (SSR-authoritative for THIS render) wins the first paint; else the persisted
+        // cache; else empty. Either way flags resolve synchronously before the network responds.
+        this.payload = this.seedFromBootstrap(ctx.flagsBootstrap) ?? loadConfig() ?? EMPTY_CONFIG;
+        // F6 — exposure dedup is SESSION-scoped now (fresh Set per setup), not persisted-once-ever, to match
+        // the facade's $feature_flag_called policy. The backend dedupes exposures by install, so per-session
+        // emission doesn't change experiment stats.
+        this.exposed = new Set();
+        // Freshen from the network; mark ready once the first attempt settles (offline still resolves).
+        void this.refresh().finally(() => this.markReady());
+        if (typeof document !== 'undefined') {
+            this.onVisible = () => {
+                if (document.visibilityState === 'visible' && now() - this.lastFetch > TTL_MS)
+                    void this.refresh();
+            };
+            document.addEventListener('visibilitychange', this.onVisible);
+        }
+        if (ctx.flagsRealtime !== false)
+            this.openStream(); // F4 — default on
+        this.active = true;
+    }
+    /** F4 — subscribe to the realtime config stream. Each `change` nudge triggers an ETag-aware refresh()
+     *  (which no-ops on 304), so a kill-switch flip propagates in seconds; `ping` frames just keep-alive.
+     *  EventSource auto-reconnects on drop; SSR / no-EventSource envs simply skip it (foreground poll stays). */
+    openStream() {
+        if (typeof EventSource === 'undefined' || !this.clientKey || !this.apiBaseUrl)
+            return;
+        try {
+            this.es = new EventSource(`${this.apiBaseUrl}/config/stream?key=${encodeURIComponent(this.clientKey)}`);
+            this.es.onmessage = (ev) => {
+                // Ignore heartbeats; refresh on a change nudge (or any non-ping message, to be safe).
+                try {
+                    if (ev.data && JSON.parse(ev.data).type === 'ping')
+                        return;
+                }
+                catch {
+                    /* non-JSON — fall through to refresh */
+                }
+                void this.refresh();
+            };
+            // onerror: EventSource reconnects itself; nothing to do (offline-safe).
+        }
+        catch {
+            /* EventSource construction can throw in odd environments — degrade to the foreground poll */
+        }
+    }
+    /** F3 — coerce the loose bootstrap shape into a payload (null when absent/empty). */
+    seedFromBootstrap(b) {
+        if (!b || typeof b !== 'object')
+            return null;
+        const has = ['flags', 'remoteConfig', 'experiments', 'rollouts'].some((k) => Array.isArray(b[k]));
+        if (!has)
+            return null;
+        return {
+            version: typeof b.version === 'string' ? b.version : 'bootstrap',
+            flags: (Array.isArray(b.flags) ? b.flags : []),
+            remoteConfig: (Array.isArray(b.remoteConfig) ? b.remoteConfig : []),
+            experiments: (Array.isArray(b.experiments) ? b.experiments : []),
+            rollouts: (Array.isArray(b.rollouts) ? b.rollouts : []),
+            entitlements: b.entitlements,
+            holdout: b.holdout, // F5 — optional
+        };
+    }
+    markReady() {
+        if (!this.settled) {
+            this.settled = true;
+            this.resolveReady?.();
+        }
+    }
+    emitChange() {
+        for (const cb of this.changeListeners) {
+            try {
+                cb();
+            }
+            catch {
+                /* one bad listener must not break the others */
+            }
+        }
+    }
+    /** Re-fetch /config (ETag-aware). Keeps the cached payload on 304 / error (offline-safe). Fires
+     *  onChange listeners when a new version is applied (F3). */
+    async refresh() {
+        if (!this.clientKey || !this.apiBaseUrl || typeof fetch === 'undefined')
+            return;
+        this.lastFetch = now();
+        try {
+            const headers = { 'x-scalebun-client-key': this.clientKey };
+            if (this.payload.version)
+                headers['if-none-match'] = `"${this.payload.version}"`;
+            const res = await fetch(`${this.apiBaseUrl}/config`, { headers });
+            if (res.status === 304 || !res.ok)
+                return;
+            const data = (await res.json());
+            if (data && typeof data.version === 'string') {
+                const changed = data.version !== this.payload.version;
+                this.payload = {
+                    version: data.version,
+                    flags: data.flags ?? [],
+                    remoteConfig: data.remoteConfig ?? [],
+                    experiments: data.experiments ?? [],
+                    rollouts: data.rollouts ?? [],
+                    entitlements: data.entitlements,
+                    holdout: data.holdout, // F5 — global experiment holdout
+                    sdkFlags: data.sdkFlags, // server-controlled behaviour switches (must survive the rebuild)
+                };
+                saveConfig(this.payload);
+                if (changed) {
+                    // A variant can differ across a version change (allocation edit, salt rotation, kill-switch).
+                    // The dedupe set is keyed `key=value`, so clearing it lets the NEW value be exposed exactly
+                    // once. Without this, analytics keeps attributing the user to the arm they are no longer in.
+                    this.exposed.clear();
+                    this.emitChange();
+                }
+            }
+        }
+        catch {
+            /* offline / network error — keep the cached payload */
+        }
+    }
+    // ── F3 — QA overrides + readiness/change subscription ─────────────────────────
+    /** Resolves once the first config fetch settles (immediately when there's no network configured).
+     *  Bootstrap/cache make flags usable synchronously before this; ready() means "freshest attempted". */
+    ready() {
+        return this.readyPromise;
+    }
+    /** Subscribe to config changes (a new version applied on refresh, or an override set/cleared).
+     *  Returns an unsubscribe fn. */
+    onChange(cb) {
+        this.changeListeners.add(cb);
+        return () => {
+            this.changeListeners.delete(cb);
+        };
+    }
+    /** QA/dev: force a flag/experiment/rollout to a value locally (persisted). A string is matched
+     *  against a multivariate flag's variation keys; otherwise it's the served value verbatim. */
+    override(key, value) {
+        this.overrides[key] = value;
+        saveOverrides(this.overrides);
+        this.emitChange();
+    }
+    clearOverride(key) {
+        if (Object.prototype.hasOwnProperty.call(this.overrides, key)) {
+            delete this.overrides[key];
+            saveOverrides(this.overrides);
+            this.emitChange();
+        }
+    }
+    clearOverrides() {
+        this.overrides = {};
+        saveOverrides(this.overrides);
+        this.emitChange();
+    }
+    hasOverride(key) {
+        return Object.prototype.hasOwnProperty.call(this.overrides, key);
+    }
+    // ── Evaluation (the public surface the facade delegates to) ────────────────────
+    /** F1 — the stable unit to bucket on. An explicit per-feature `bucketBy` context attribute always wins
+     *  (e.g. 'group_company' to flip a whole account together).
+     *
+     *  Otherwise the identity unit, and there are two, because they trade against each other:
+     *
+     *   - `deviceId` (stable): the same value before and after login, so a user NEVER changes variant
+     *     mid-session. This is what the RN SDK buckets on (`installationId`) and what the backend
+     *     aggregates exposures by, so it is also the only option under which web and mobile agree.
+     *   - `userId ?? deviceId` (legacy): gives a logged-in user the same assignment across devices and
+     *     across a storage clear — a genuine feature — but the identity CHANGES at login, which
+     *     re-buckets the user mid-experiment. On any experiment that spans signup that is not noise:
+     *     every converting user crosses the boundary, so the experiment measures the login, not the
+     *     treatment, and one human lands in both arms.
+     *
+     *  Correctness wins: the flip silently invalidates results, while cross-device consistency can be
+     *  recovered deliberately per experiment via `bucketBy: 'userId'`, and multi-device humans are
+     *  folded at analysis time from the backend's identity links.
+     *
+     *  Server-gated because switching re-buckets already-logged-in users once — enabled for new
+     *  experiments first, then globally. Absent ⇒ legacy behaviour, so old payloads are unchanged. */
+    bucketingId(bucketBy) {
+        const ctx = getEvalContext();
+        if (bucketBy) {
+            const v = ctx[bucketBy];
+            if (v != null && v !== '')
+                return String(v);
+        }
+        if (this.payload.sdkFlags?.stableBucketingId)
+            return this.deviceId;
+        const userId = ctx.userId;
+        return userId != null && userId !== '' ? String(userId) : this.deviceId;
+    }
+    /** Feature flag — F0: if the flag carries targeting, the first matching rule decides (serve, or a
+     *  per-rule % rollout); no rule matches → the flag's default `enabled`. No targeting → plain boolean.
+     *  F1: the % rollout buckets on the identity unit (or the flag's `bucketBy`), not the raw device.
+     *  F2: for a multivariate flag `isEnabled` is the truthiness of the served value. */
+    /** True when a read of `key` reflects real server config — i.e. the answer is a decision the user
+     *  actually experienced, and therefore an exposure worth recording. False in three cases that all
+     *  look like `false` to a caller but are NOT data:
+     *   - before bootstrap resolves (payload is EMPTY_CONFIG) — an absence of information,
+     *   - for a flag the server has never heard of,
+     *   - for a QA override — staff inspecting the system is not experiment traffic.
+     *  Without this, a first paint records a phantom `false` the user never saw, and the real value
+     *  then emits a second, contradictory exposure. */
+    knows(key) {
+        return !this.hasOverride(key) && this.payload.flags.some((f) => f.key === key);
+    }
+    isEnabled(key) {
+        if (this.hasOverride(key))
+            return Boolean(this.overrides[key]); // F3 — QA override
+        const flag = this.payload.flags.find((f) => f.key === key);
+        if (!flag)
+            return false;
+        if (flag.variations && flag.variations.length)
+            return Boolean(this.variationDetail(key, false).value);
+        if (flag.targeting && flag.targeting.length) {
+            const rule = evaluateTargeting(flag.targeting, getEvalContext());
+            if (rule) {
+                if (typeof rule.rollout === 'number')
+                    return bucketOf(this.bucketingId(flag.bucketBy), saltOf(flag)) < rule.rollout;
+                return rule.serve ?? true;
+            }
+        }
+        return flag.enabled;
+    }
+    /** F2 — resolve a flag's served value with LD-style detail. Boolean flags (no `variations`) resolve to
+     *  their boolean; multivariate flags resolve to a variation's typed value. Precedence: a matching
+     *  targeting rule (TARGETING_MATCH / ROLLOUT) → fallthrough split (ROLLOUT) → default (DEFAULT); an
+     *  unknown flag is FLAG_NOT_FOUND (caller fallback). Never throws — safe defaults at every branch. */
+    variationDetail(key, fallback) {
+        const flag = this.payload.flags.find((f) => f.key === key);
+        if (this.hasOverride(key)) {
+            // F3 — QA override: a string matching a variation key serves that variation; else it's the value.
+            const ov = this.overrides[key];
+            if (typeof ov === 'string' && flag?.variations) {
+                const v = flag.variations.find((x) => x.key === ov);
+                if (v)
+                    return { value: v.value, variant: v.key, reason: 'DEFAULT' };
+            }
+            return { value: (ov ?? fallback), variant: typeof ov === 'string' ? ov : null, reason: 'DEFAULT' };
+        }
+        if (!flag)
+            return { value: fallback, variant: null, reason: 'FLAG_NOT_FOUND' };
+        const vars = flag.variations;
+        const id = () => this.bucketingId(flag.bucketBy);
+        // Resolve a variation key → its typed value; missing key falls to defaultVariant then defaultValue.
+        const served = (variant, reason) => {
+            const vk = variant ?? flag.defaultVariant ?? null;
+            if (vk && vars) {
+                const v = vars.find((x) => x.key === vk);
+                if (v)
+                    return { value: v.value, variant: vk, reason };
+            }
+            return { value: (flag.defaultValue ?? fallback), variant: vk, reason };
+        };
+        const fallthrough = () => {
+            if (vars && vars.some((v) => typeof v.allocationPct === 'number')) {
+                const vk = pickVariant(id(), key, vars.map((v) => ({ key: v.key, allocationPct: v.allocationPct ?? 0 })));
+                return served(vk, 'ROLLOUT');
+            }
+            if (vars)
+                return served(null, 'DEFAULT');
+            return { value: flag.enabled, variant: null, reason: 'DEFAULT' };
+        };
+        if (flag.targeting && flag.targeting.length) {
+            const rule = evaluateTargeting(flag.targeting, getEvalContext());
+            if (rule) {
+                if (typeof rule.rollout === 'number') {
+                    if (bucketOf(id(), saltOf(flag)) >= rule.rollout)
+                        return fallthrough(); // not in the rollout → default
+                    return vars ? served(rule.variation ?? null, 'ROLLOUT') : { value: true, variant: null, reason: 'ROLLOUT' };
+                }
+                if (rule.variation || vars)
+                    return served(rule.variation ?? null, 'TARGETING_MATCH');
+                return { value: (rule.serve ?? true), variant: null, reason: 'TARGETING_MATCH' };
+            }
+        }
+        return fallthrough();
+    }
+    /** F2 — the served value only (sugar over variationDetail). */
+    variation(key, fallback) {
+        return this.variationDetail(key, fallback).value;
+    }
+    /** Remote config value with type coercion + caller fallback (never throws). */
+    get(key, fallback) {
+        const rc = this.payload.remoteConfig.find((r) => r.key === key);
+        if (!rc)
+            return fallback;
+        try {
+            switch (rc.type) {
+                case 'number': {
+                    const n = Number(rc.value);
+                    return Number.isFinite(n) ? n : fallback;
+                }
+                case 'boolean':
+                    return (rc.value === 'true');
+                case 'json':
+                    return JSON.parse(rc.value);
+                default:
+                    return rc.value;
+            }
+        }
+        catch {
+            return fallback;
+        }
+    }
+    /** Feature rollout — deterministic percentage gate. F0: a matching targeting rule can override the
+     *  percentage for the matched audience; no match → the rollout's default percentage. */
+    isOn(key) {
+        if (this.hasOverride(key))
+            return Boolean(this.overrides[key]); // F3 — QA override
+        const r = this.payload.rollouts.find((x) => x.key === key);
+        if (!r)
+            return false;
+        let pct = r.percentage;
+        if (r.targeting && r.targeting.length) {
+            const rule = evaluateTargeting(r.targeting, getEvalContext());
+            if (rule && typeof rule.percentage === 'number')
+                pct = rule.percentage;
+        }
+        return bucketOf(this.bucketingId(r.bucketBy), r.salt) < pct;
+    }
+    /** F5 — is the identified user in the global experiment holdout? Bucketed on the DEFAULT identity unit
+     *  (uniform across all experiments) so a held-out user is a clean, never-treated baseline everywhere. */
+    inHoldout() {
+        const h = this.payload.holdout;
+        return !!h && h.percentage > 0 && bucketOf(this.bucketingId(), h.salt) < h.percentage;
+    }
+    /** F5 — mutual exclusion: within a layer a user owns exactly one 0..99 slot, so only the experiment
+     *  whose `layerRange` covers that slot enrolls them (the rest of the layer excludes them). Bucketed on
+     *  the default identity unit so every experiment in the layer places the user identically. */
+    inLayerSlot(exp) {
+        if (!exp.layer || !exp.layerRange)
+            return true; // not layered → no exclusion
+        const [start, end] = exp.layerRange;
+        const b = bucketOf(this.bucketingId(), `layer:${exp.layer}`);
+        return b >= start && b < end;
+    }
+    /** Experiment variant — deterministic; emits one exposure event per (install, key). F0: targeting acts
+     *  as an inclusion filter — no match ⇒ not enrolled (null); a matching rule may override the variant
+     *  set. F5: a global-holdout user, or a user whose layer slot belongs to a different experiment, is not
+     *  enrolled (null, no exposure) — keeping the holdout baseline clean and layers mutually exclusive. */
+    variant(key) {
+        if (this.hasOverride(key)) {
+            // F3 — QA override: force a variant key (no exposure — a forced variant must not skew results).
+            const ov = this.overrides[key];
+            return ov == null ? null : String(ov);
+        }
+        const exp = this.payload.experiments.find((e) => e.key === key);
+        if (!exp)
+            return null;
+        if (this.inHoldout())
+            return null; // F5 — global holdout → never treated
+        if (!this.inLayerSlot(exp))
+            return null; // F5 — another experiment owns this user's layer slot
+        let variants = exp.variants;
+        if (exp.targeting && exp.targeting.length) {
+            const rule = evaluateTargeting(exp.targeting, getEvalContext());
+            if (!rule || rule.include === false)
+                return null; // not enrolled
+            if (rule.variants && rule.variants.length)
+                variants = rule.variants;
+        }
+        const v = pickVariant(this.bucketingId(exp.bucketBy), exp.salt, variants);
+        // F6 — exposure integrity: fire once per SESSION (reconciled with the facade's $feature_flag_called,
+        // which is also once-per-session), stamped with the reason so results can segment by why the user was
+        // served. Held-out / layer-excluded / untargeted users returned null above, so no exposure fires for
+        // them (the holdout baseline stays clean). The backend dedupes by install, so per-session is safe.
+        // Dedupe on `key=variant`, NOT `key`. Keyed on `key` alone, a variant that changes mid-session
+        // (allocation edit, salt rotation, an SSE refresh) emitted NO new exposure here while the facade —
+        // which keys on key=value — did emit one: the two exposure streams disagreed, and analytics kept
+        // attributing the user to the arm they had left. Same rule on both now.
+        const dedup = `${key}=${v}`;
+        if (v && !this.exposed.has(dedup)) {
+            this.exposed.add(dedup);
+            // F7 — the correlation edge: stamp WHERE the replay was at exposure time, so the "watch the
+            // experiment" panel can deep-link a losing variant's session to the EXACT frame (not just the
+            // session). Reuses A0's replay coordinate; absent when replay isn't producing frames.
+            const replay = getReplayCoord();
+            this.ctx?.emit({
+                kind: 'event',
+                name: 'experiment_exposure',
+                props: { experiment: key, variant: v, reason: 'ENROLLED', ...(replay ? { $replay: replay } : {}) },
+                timestamp: now(),
+            });
+        }
+        return v;
+    }
+    /** SDK-suppressible entitlement (fail-open: unknown → on). The bootstrap can gate features on this. */
+    entitlement(key) {
+        const ent = this.payload.entitlements;
+        return ent?.[key] !== false;
+    }
+    teardown() {
+        if (this.onVisible && typeof document !== 'undefined') {
+            document.removeEventListener('visibilitychange', this.onVisible);
+        }
+        this.onVisible = undefined;
+        this.es?.close(); // F4 — drop the realtime stream
+        this.es = undefined;
+        this.active = false;
+    }
+}
+//# sourceMappingURL=ConfigFeature.js.map

package/dist/features/config/ConfigFeature.js.map

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

package/dist/features/config/bucketing.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Deterministic experiment/rollout bucketing — MUST stay byte-for-byte identical to the RN SDK
+ * (whatzbug-react-native-sdk/.../bucketing/fnv1a32.ts) AND the backend
+ * (wzb-dashboard-backend/src/common/bucketing/fnv1a32.ts). A shared test vector is asserted across
+ * repos; if you change the hash, update all three. Zero dependencies (web SDK core rule).
+ *
+ * Inputs are ASCII (deviceId = UUID, salt = hex) so charCodeAt === UTF-8 byte.
+ */
+export declare function fnv1a32(str: string): number;
+/** Stable 0..99 bucket for an install within an experiment/rollout (salt is immutable). */
+export declare function bucketOf(deviceId: string, salt: string): number;
+/**
+ * Pick a variant by cumulative allocation. `variants` order is significant and `allocationPct` should
+ * sum to 100; the last variant is the fallback so an install always resolves to a variant.
+ */
+export declare function pickVariant(deviceId: string, salt: string, variants: Array<{
+    key: string;
+    allocationPct: number;
+}>): string | null;
+//# sourceMappingURL=bucketing.d.ts.map

package/dist/features/config/bucketing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucketing.d.ts","sourceRoot":"","sources":["../../../src/features/config/bucketing.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO3C;AAED,2FAA2F;AAC3F,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,GACtD,MAAM,GAAG,IAAI,CASf"}

package/dist/features/config/bucketing.js

@@ -0,0 +1,37 @@
+/**
+ * Deterministic experiment/rollout bucketing — MUST stay byte-for-byte identical to the RN SDK
+ * (whatzbug-react-native-sdk/.../bucketing/fnv1a32.ts) AND the backend
+ * (wzb-dashboard-backend/src/common/bucketing/fnv1a32.ts). A shared test vector is asserted across
+ * repos; if you change the hash, update all three. Zero dependencies (web SDK core rule).
+ *
+ * Inputs are ASCII (deviceId = UUID, salt = hex) so charCodeAt === UTF-8 byte.
+ */
+export function fnv1a32(str) {
+    let h = 0x811c9dc5; // FNV offset basis (2166136261)
+    for (let i = 0; i < str.length; i++) {
+        h ^= str.charCodeAt(i);
+        h = Math.imul(h, 0x01000193); // FNV prime (16777619)
+    }
+    return h >>> 0; // unsigned 32-bit
+}
+/** Stable 0..99 bucket for an install within an experiment/rollout (salt is immutable). */
+export function bucketOf(deviceId, salt) {
+    return fnv1a32(`${deviceId}:${salt}`) % 100;
+}
+/**
+ * Pick a variant by cumulative allocation. `variants` order is significant and `allocationPct` should
+ * sum to 100; the last variant is the fallback so an install always resolves to a variant.
+ */
+export function pickVariant(deviceId, salt, variants) {
+    if (!variants.length)
+        return null;
+    const b = bucketOf(deviceId, salt);
+    let cum = 0;
+    for (const v of variants) {
+        cum += v.allocationPct;
+        if (b < cum)
+            return v.key;
+    }
+    return variants[variants.length - 1].key;
+}
+//# sourceMappingURL=bucketing.js.map