@shipeasy/sdk 5.0.0 → 5.1.0

package/README.md

@@ -130,6 +130,164 @@ The loader IIFE is published to a public R2 bucket on every release and
 cached for 1y at `loader-vX.Y.Z.js` (immutable) plus a rolling 5-minute
 `loader.js`.
 
+## Testing
+
+For unit tests, build a **no-network** client with `forTesting()` and seed every
+entity with local overrides (Statsig-style). In test mode the client is already
+"initialized"/"ready", `init()`/`initOnce()`/`identify()` are no-ops (they never
+fetch), `track()` is a no-op, telemetry is disabled, and no SDK key is required —
+so your tests never touch the network.
+
+```ts
+// Server (Node / Cloudflare Worker / Deno)
+import { FlagsClient } from "@shipeasy/sdk/server";
+
+const client = FlagsClient.forTesting();
+
+client.overrideFlag("new_checkout", true);
+client.overrideConfig("upload_limits", { max_uploads: 50 });
+client.overrideExperiment("hero_cta", "treatment", { primary_label: "Buy now" });
+
+client.getFlag("new_checkout", { user_id: "u1" }); // true
+client.getConfig("upload_limits"); // { max_uploads: 50 }
+client.getExperiment("hero_cta", { user_id: "u1" }, { primary_label: "Sign up" });
+// → { inExperiment: true, group: "treatment", params: { primary_label: "Buy now" } }
+
+client.track("u1", "purchase"); // no-op — never hits the network
+client.clearOverrides(); // reset every override back to default
+```
+
+```ts
+// Browser (vanilla JS — no React required)
+import { FlagsClientBrowser } from "@shipeasy/sdk/client";
+
+const client = FlagsClientBrowser.forTesting();
+
+client.overrideFlag("new_checkout", true);
+client.overrideConfig("upload_limits", { max_uploads: 50 });
+client.overrideExperiment("hero_cta", "treatment", { primary_label: "Buy now" });
+
+client.getFlag("new_checkout"); // true
+client.getConfig("upload_limits"); // { max_uploads: 50 }
+client.getExperiment("hero_cta", { primary_label: "Sign up" });
+// → { inExperiment: true, group: "treatment", params: { primary_label: "Buy now" } }
+
+client.track("purchase"); // no-op
+client.clearOverrides();
+```
+
+The `override*` setters also work on a **normal** client (not just `forTesting()`),
+mirroring Statsig — a programmatic override always wins over the fetched values.
+In the browser the precedence is: programmatic override > URL/devtools override
+(`?se_gate_…` / `?se_config_…` / `?se_exp_…`) > the server's evaluation.
+
+**API:**
+
+```ts
+overrideFlag(name: string, value: boolean): void;
+overrideConfig(name: string, value: unknown): void;
+overrideExperiment(name: string, group: string, params: Record<string, unknown>): void;
+clearOverrides(): void;
+```
+
+## Default values
+
+`getFlag` / `getConfig` take a caller-supplied default that is returned **only
+when the value can't be evaluated** — the client isn't initialized yet, or the
+key isn't in the loaded rules. A flag that legitimately evaluates to `false`
+(disabled, rule denied, rolled out to 0%) still returns `false`, never the
+default.
+
+```ts
+// Server
+flags.get("new_checkout", { user_id: "u1" });        // false for a missing flag
+flags.get("new_checkout", { user_id: "u1" }, true);  // true only if not-ready/not-found
+flags.getConfig("limits", { defaultValue: { max: 50 } }); // default when key absent
+
+// Browser (no user arg)
+client.getFlag("new_checkout");        // false for a missing flag
+client.getFlag("new_checkout", true);  // default when not-ready/not-found
+client.getConfig("limits", { defaultValue: { max: 50 } });
+```
+
+The legacy `getConfig(name, decode)` callback signature still works unchanged;
+the options object (`{ decode?, defaultValue? }`) is the new, additive form.
+
+## Evaluation detail
+
+`getFlagDetail(name[, user])` returns `{ value, reason }` (LaunchDarkly
+`variationDetail` parity) so you can see *why* a flag resolved the way it did:
+
+```ts
+import type { FlagReason } from "@shipeasy/sdk/server"; // or /client
+
+const d = client.getFlagDetail("new_checkout", { user_id: "u1" });
+// → { value: true, reason: "RULE_MATCH" }
+```
+
+`FlagReason` is one of:
+
+| reason             | meaning                                                     |
+| ------------------ | ---------------------------------------------------------- |
+| `CLIENT_NOT_READY` | no rules loaded yet (`init()` / `identify()` pending)      |
+| `FLAG_NOT_FOUND`   | the gate name isn't in the loaded rules                    |
+| `OFF`              | the gate exists but is disabled / killed (server only)     |
+| `OVERRIDE`         | a local override (or `?se_gate_…` URL override) decided it |
+| `RULE_MATCH`       | the gate evaluated `true`                                  |
+| `DEFAULT`          | the gate evaluated `false`                                 |
+
+`getFlag` is implemented on top of `getFlagDetail` (single evaluation, single
+telemetry beacon). On the browser the server pre-evaluates the gate's
+enabled/killed state into a boolean, so `OFF` folds into `DEFAULT` there.
+
+## Change listeners
+
+The server `FlagsClient` fires registered listeners after a **background poll
+returns new data** (HTTP 200, not 304) — handy for invalidating a cache or
+re-rendering when a flag flips. Returns an unsubscribe function. Never fires in
+test/offline mode (no polling happens):
+
+```ts
+const client = new FlagsClient({ apiKey: process.env.SHIPEASY_SERVER_KEY! });
+await client.init();
+const unsubscribe = client.onChange(() => {
+  console.log("flag rules changed — re-evaluating");
+});
+// later…
+unsubscribe();
+```
+
+The browser `FlagsClientBrowser` already exposes the equivalent `subscribe()`
+(fires after each `identify()` / override change).
+
+## Offline snapshot
+
+Build a fully offline server client from a captured snapshot — zero network.
+Evaluations run the real eval against the snapshot; `init()`/`initOnce()`/
+`track()` are no-ops and overrides still apply on top. The snapshot is just the
+two SDK wire bodies:
+
+```jsonc
+// snapshot.json
+{
+  "flags":       /* body of GET /sdk/flags */,
+  "experiments": /* body of GET /sdk/experiments */
+}
+```
+
+```ts
+import { FlagsClient } from "@shipeasy/sdk/server";
+
+const client = FlagsClient.fromFile("./snapshot.json");
+// or, if you already hold the parsed object:
+const client = FlagsClient.fromSnapshot({ flags, experiments });
+
+client.getFlag("new_checkout", { user_id: "u1" });
+```
+
+`fromFile` is Node-only (it reads the file with `node:fs`); `fromSnapshot` works
+anywhere.
+
 ## Devtools overlay
 
 Press `Shift+Alt+S` on any page running the SDK (or append `?se=1` to the

package/dist/client/index.d.mts

@@ -120,6 +120,33 @@ interface ExperimentResult<P> {
     group: string;
     params: P;
 }
+/**
+ * Why a flag evaluated the way it did (LaunchDarkly variationDetail parity).
+ * Computed at the client boundary:
+ *   - CLIENT_NOT_READY — no eval result yet (identify() hasn't resolved)
+ *   - FLAG_NOT_FOUND   — the gate name isn't present in the eval result
+ *   - OFF              — folded into DEFAULT here (the server pre-evaluates the
+ *     gate's enabled/killed state into a plain boolean, so the browser can't
+ *     distinguish a disabled gate from one a rule denied)
+ *   - OVERRIDE         — a local override or a ?se_gate_/?se_ks_ URL override
+ *     decided the value
+ *   - RULE_MATCH       — the gate evaluated true
+ *   - DEFAULT          — the gate evaluated false
+ */
+declare const FLAG_REASONS: readonly ["CLIENT_NOT_READY", "FLAG_NOT_FOUND", "OFF", "OVERRIDE", "RULE_MATCH", "DEFAULT"];
+type FlagReason = (typeof FLAG_REASONS)[number];
+interface FlagDetail {
+    value: boolean;
+    reason: FlagReason;
+}
+/** Options object form of `getConfig` — keeps the legacy `decode` callback and
+ *  adds a `defaultValue` returned when the config key is absent. */
+interface GetConfigOptions<T = unknown> {
+    /** Decode the raw stored value into the typed shape callers want. */
+    decode?: (raw: unknown) => T;
+    /** Returned when the config key is absent (not overridden, not in the eval result). */
+    defaultValue?: T;
+}
 interface EvalExpResult {
     inExperiment: boolean;
     group: string;
@@ -180,6 +207,13 @@ interface FlagsClientBrowserOptions {
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
     telemetryUrl?: string;
+    /**
+     * Test mode — no network at all. identify()/init are no-ops (never call
+     * /sdk/evaluate), track() is a no-op, telemetry is forced off, and the client
+     * starts "ready" with an empty eval result. Prefer the
+     * {@link FlagsClientBrowser.forTesting} factory over passing this directly.
+     */
+    testMode?: boolean;
 }
 declare class FlagsClientBrowser {
     private readonly sdkKey;
@@ -198,8 +232,26 @@ declare class FlagsClientBrowser {
     private listeners;
     private overrideListenerInstalled;
     private identifySeq;
+    private readonly testMode;
+    private readonly flagOverrides;
+    private readonly configOverrides;
+    private readonly experimentOverrides;
     private onOverrideChange;
     constructor(opts: FlagsClientBrowserOptions);
+    /**
+     * Build a no-network, immediately-usable browser client for tests
+     * (Statsig-style). identify() is a no-op (never calls /sdk/evaluate), track()
+     * is a no-op, telemetry is disabled, and the client is already ready — seed
+     * every entity with overrideFlag/overrideConfig/overrideExperiment. No SDK
+     * key required.
+     *
+     * ```ts
+     * const client = FlagsClientBrowser.forTesting();
+     * client.overrideFlag("new_checkout", true);
+     * client.getFlag("new_checkout"); // true
+     * ```
+     */
+    static forTesting(opts?: Partial<FlagsClientBrowserOptions>): FlagsClientBrowser;
     identify(user: User): Promise<void>;
     /**
      * Report a structured error into the errors primitive. Flushes immediately
@@ -210,8 +262,35 @@ declare class FlagsClientBrowser {
     get ready(): boolean;
     private notify;
     initFromBootstrap(data: EvalResponse): void;
-    getFlag(name: string): boolean;
+    /** Force `getFlag(name)` to return `value`, ignoring URL overrides + eval. */
+    overrideFlag(name: string, value: boolean): void;
+    /** Force `getConfig(name)` to return `value`, ignoring URL overrides + eval. */
+    overrideConfig(name: string, value: unknown): void;
+    /**
+     * Force `getExperiment(name, …)` to return `{ inExperiment: true, group, params }`,
+     * ignoring URL overrides, the eval result, and exposure logging.
+     */
+    overrideExperiment(name: string, group: string, params: Record<string, unknown>): void;
+    /** Remove every programmatic override set via the override* methods. */
+    clearOverrides(): void;
+    /**
+     * Evaluate a gate and report WHY (LaunchDarkly variationDetail parity). A
+     * local override OR a ?se_gate_/?se_ks_ URL override short-circuits BEFORE
+     * telemetry; otherwise exactly one "gate" beacon is emitted. The server
+     * pre-evaluates a gate's enabled/killed state into a plain boolean, so OFF
+     * folds into DEFAULT here (the browser can't tell "disabled" from "rule
+     * denied").
+     */
+    getFlagDetail(name: string): FlagDetail;
+    /**
+     * Read a feature gate. Returns `defaultValue` ONLY when the gate cannot be
+     * evaluated (not ready or flag not found) — never for a gate that legitimately
+     * evaluates to false. Plain `getFlag(name)` keeps returning false for a
+     * missing flag.
+     */
+    getFlag(name: string, defaultValue?: boolean): boolean;
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
+    getConfig<T = unknown>(name: string, opts: GetConfigOptions<T>): T;
     getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decode?: (raw: unknown) => P, variants?: Record<string, Partial<P>>): ExperimentResult<P>;
     /**
      * Subscribe to state changes — fires after identify() completes and on
@@ -388,7 +467,9 @@ declare const flags: {
      * Everything else gates on _mountedAndReady to prevent hydration mismatches on
      * force-static pages where SSR has no flag data.
      */
-    get(name: string): boolean;
+    get(name: string, defaultValue?: boolean): boolean;
+    /** Evaluate a gate and report why (value + reason). See {@link FlagDetail}. */
+    getDetail(name: string): FlagDetail;
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
     getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decode?: (raw: unknown) => P, variants?: Record<string, Partial<P>>): ExperimentResult<P>;
     track(eventName: string, props?: Record<string, unknown>): void;
@@ -509,4 +590,4 @@ interface I18nFacade {
 }
 declare const i18n: I18nFacade;
 
-export { type AutoCollectGroups, type BootstrapPayload, type Consequence, type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };
+export { type AutoCollectGroups, type BootstrapPayload, type Consequence, type ExperimentResult, FLAG_REASONS, type FlagDetail, type FlagReason, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, type GetConfigOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };

package/dist/client/index.d.ts

@@ -120,6 +120,33 @@ interface ExperimentResult<P> {
     group: string;
     params: P;
 }
+/**
+ * Why a flag evaluated the way it did (LaunchDarkly variationDetail parity).
+ * Computed at the client boundary:
+ *   - CLIENT_NOT_READY — no eval result yet (identify() hasn't resolved)
+ *   - FLAG_NOT_FOUND   — the gate name isn't present in the eval result
+ *   - OFF              — folded into DEFAULT here (the server pre-evaluates the
+ *     gate's enabled/killed state into a plain boolean, so the browser can't
+ *     distinguish a disabled gate from one a rule denied)
+ *   - OVERRIDE         — a local override or a ?se_gate_/?se_ks_ URL override
+ *     decided the value
+ *   - RULE_MATCH       — the gate evaluated true
+ *   - DEFAULT          — the gate evaluated false
+ */
+declare const FLAG_REASONS: readonly ["CLIENT_NOT_READY", "FLAG_NOT_FOUND", "OFF", "OVERRIDE", "RULE_MATCH", "DEFAULT"];
+type FlagReason = (typeof FLAG_REASONS)[number];
+interface FlagDetail {
+    value: boolean;
+    reason: FlagReason;
+}
+/** Options object form of `getConfig` — keeps the legacy `decode` callback and
+ *  adds a `defaultValue` returned when the config key is absent. */
+interface GetConfigOptions<T = unknown> {
+    /** Decode the raw stored value into the typed shape callers want. */
+    decode?: (raw: unknown) => T;
+    /** Returned when the config key is absent (not overridden, not in the eval result). */
+    defaultValue?: T;
+}
 interface EvalExpResult {
     inExperiment: boolean;
     group: string;
@@ -180,6 +207,13 @@ interface FlagsClientBrowserOptions {
     disableTelemetry?: boolean;
     /** Override the telemetry beacon host. Defaults to {@link DEFAULT_TELEMETRY_URL}. */
     telemetryUrl?: string;
+    /**
+     * Test mode — no network at all. identify()/init are no-ops (never call
+     * /sdk/evaluate), track() is a no-op, telemetry is forced off, and the client
+     * starts "ready" with an empty eval result. Prefer the
+     * {@link FlagsClientBrowser.forTesting} factory over passing this directly.
+     */
+    testMode?: boolean;
 }
 declare class FlagsClientBrowser {
     private readonly sdkKey;
@@ -198,8 +232,26 @@ declare class FlagsClientBrowser {
     private listeners;
     private overrideListenerInstalled;
     private identifySeq;
+    private readonly testMode;
+    private readonly flagOverrides;
+    private readonly configOverrides;
+    private readonly experimentOverrides;
     private onOverrideChange;
     constructor(opts: FlagsClientBrowserOptions);
+    /**
+     * Build a no-network, immediately-usable browser client for tests
+     * (Statsig-style). identify() is a no-op (never calls /sdk/evaluate), track()
+     * is a no-op, telemetry is disabled, and the client is already ready — seed
+     * every entity with overrideFlag/overrideConfig/overrideExperiment. No SDK
+     * key required.
+     *
+     * ```ts
+     * const client = FlagsClientBrowser.forTesting();
+     * client.overrideFlag("new_checkout", true);
+     * client.getFlag("new_checkout"); // true
+     * ```
+     */
+    static forTesting(opts?: Partial<FlagsClientBrowserOptions>): FlagsClientBrowser;
     identify(user: User): Promise<void>;
     /**
      * Report a structured error into the errors primitive. Flushes immediately
@@ -210,8 +262,35 @@ declare class FlagsClientBrowser {
     get ready(): boolean;
     private notify;
     initFromBootstrap(data: EvalResponse): void;
-    getFlag(name: string): boolean;
+    /** Force `getFlag(name)` to return `value`, ignoring URL overrides + eval. */
+    overrideFlag(name: string, value: boolean): void;
+    /** Force `getConfig(name)` to return `value`, ignoring URL overrides + eval. */
+    overrideConfig(name: string, value: unknown): void;
+    /**
+     * Force `getExperiment(name, …)` to return `{ inExperiment: true, group, params }`,
+     * ignoring URL overrides, the eval result, and exposure logging.
+     */
+    overrideExperiment(name: string, group: string, params: Record<string, unknown>): void;
+    /** Remove every programmatic override set via the override* methods. */
+    clearOverrides(): void;
+    /**
+     * Evaluate a gate and report WHY (LaunchDarkly variationDetail parity). A
+     * local override OR a ?se_gate_/?se_ks_ URL override short-circuits BEFORE
+     * telemetry; otherwise exactly one "gate" beacon is emitted. The server
+     * pre-evaluates a gate's enabled/killed state into a plain boolean, so OFF
+     * folds into DEFAULT here (the browser can't tell "disabled" from "rule
+     * denied").
+     */
+    getFlagDetail(name: string): FlagDetail;
+    /**
+     * Read a feature gate. Returns `defaultValue` ONLY when the gate cannot be
+     * evaluated (not ready or flag not found) — never for a gate that legitimately
+     * evaluates to false. Plain `getFlag(name)` keeps returning false for a
+     * missing flag.
+     */
+    getFlag(name: string, defaultValue?: boolean): boolean;
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
+    getConfig<T = unknown>(name: string, opts: GetConfigOptions<T>): T;
     getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decode?: (raw: unknown) => P, variants?: Record<string, Partial<P>>): ExperimentResult<P>;
     /**
      * Subscribe to state changes — fires after identify() completes and on
@@ -388,7 +467,9 @@ declare const flags: {
      * Everything else gates on _mountedAndReady to prevent hydration mismatches on
      * force-static pages where SSR has no flag data.
      */
-    get(name: string): boolean;
+    get(name: string, defaultValue?: boolean): boolean;
+    /** Evaluate a gate and report why (value + reason). See {@link FlagDetail}. */
+    getDetail(name: string): FlagDetail;
     getConfig<T = unknown>(name: string, decode?: (raw: unknown) => T): T | undefined;
     getExperiment<P extends Record<string, unknown>>(name: string, defaultParams: P, decode?: (raw: unknown) => P, variants?: Record<string, Partial<P>>): ExperimentResult<P>;
     track(eventName: string, props?: Record<string, unknown>): void;
@@ -509,4 +590,4 @@ interface I18nFacade {
 }
 declare const i18n: I18nFacade;
 
-export { type AutoCollectGroups, type BootstrapPayload, type Consequence, type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };
+export { type AutoCollectGroups, type BootstrapPayload, type Consequence, type ExperimentResult, FLAG_REASONS, type FlagDetail, type FlagReason, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, type GetConfigOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };

package/dist/client/index.js

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/client/index.ts
 var client_exports = {};
 __export(client_exports, {
+  FLAG_REASONS: () => FLAG_REASONS,
   FlagsClientBrowser: () => FlagsClientBrowser,
   LABEL_MARKER_END: () => LABEL_MARKER_END,
   LABEL_MARKER_RE: () => LABEL_MARKER_RE,
@@ -358,6 +359,14 @@ var SeeLimiter = class {
 
 // src/client/index.ts
 var version = "4.0.0";
+var FLAG_REASONS = [
+  "CLIENT_NOT_READY",
+  "FLAG_NOT_FOUND",
+  "OFF",
+  "OVERRIDE",
+  "RULE_MATCH",
+  "DEFAULT"
+];
 var FLUSH_INTERVAL_MS = 5e3;
 var MAX_BUFFER = 100;
 var ANON_ID_KEY = "__se_anon_id";
@@ -869,7 +878,7 @@ function readExperimentOverridesFromUrl() {
   }
   return out;
 }
-var FlagsClientBrowser = class {
+var FlagsClientBrowser = class _FlagsClientBrowser {
   sdkKey;
   baseUrl;
   autoGuardrails;
@@ -888,6 +897,16 @@ var FlagsClientBrowser = class {
   // Monotonic counter so a later identify() always wins even if its /sdk/evaluate
   // response races and lands before an earlier in-flight call's response.
   identifySeq = 0;
+  // Test mode: built by `FlagsClientBrowser.forTesting()`. When set, identify()
+  // never fetches, track() is a no-op, telemetry is off, and the client is
+  // already ready with an empty eval result.
+  testMode;
+  // Programmatic overrides (Statsig-style). Set on any client via
+  // overrideFlag/overrideConfig/overrideExperiment; they win over BOTH the URL
+  // overrides and the fetched eval result. Cleared by clearOverrides().
+  flagOverrides = /* @__PURE__ */ new Map();
+  configOverrides = /* @__PURE__ */ new Map();
+  experimentOverrides = /* @__PURE__ */ new Map();
   onOverrideChange = () => {
     this.installBridge();
     this.notify();
@@ -896,6 +915,7 @@ var FlagsClientBrowser = class {
     this.sdkKey = opts.sdkKey;
     this.baseUrl = (opts.baseUrl ?? "https://edge.shipeasy.dev").replace(/\/$/, "");
     this.env = opts.env ?? "prod";
+    this.testMode = opts.testMode === true;
     this.autoGuardrails = opts.autoGuardrails !== false;
     this.autoCollectAlways = opts.autoCollectAlways === true;
     const g = opts.autoGuardrailGroups ?? {};
@@ -911,11 +931,42 @@ var FlagsClientBrowser = class {
       sdkKey: this.sdkKey,
       side: "client",
       env: this.env,
-      disabled: opts.disableTelemetry
+      // Test mode never talks to the network — telemetry off regardless of opt.
+      disabled: this.testMode || opts.disableTelemetry
+    });
+    if (this.testMode) {
+      this.evalResult = { flags: {}, configs: {}, experiments: {}, killswitches: {} };
+    } else {
+      void this.buffer.flushPendingAlias();
+    }
+  }
+  /**
+   * Build a no-network, immediately-usable browser client for tests
+   * (Statsig-style). identify() is a no-op (never calls /sdk/evaluate), track()
+   * is a no-op, telemetry is disabled, and the client is already ready — seed
+   * every entity with overrideFlag/overrideConfig/overrideExperiment. No SDK
+   * key required.
+   *
+   * ```ts
+   * const client = FlagsClientBrowser.forTesting();
+   * client.overrideFlag("new_checkout", true);
+   * client.getFlag("new_checkout"); // true
+   * ```
+   */
+  static forTesting(opts) {
+    return new _FlagsClientBrowser({
+      sdkKey: "",
+      autoGuardrails: false,
+      ...opts,
+      testMode: true
     });
-    void this.buffer.flushPendingAlias();
   }
   async identify(user) {
+    if (this.testMode) {
+      if (user.user_id !== void 0) this.userId = user.user_id;
+      this.notify();
+      return;
+    }
     const seq = ++this.identifySeq;
     const prevUserId = this.userId;
     if (user.user_id !== void 0) this.userId = user.user_id;
@@ -990,22 +1041,75 @@ var FlagsClientBrowser = class {
   initFromBootstrap(data) {
     this.evalResult = data;
   }
-  getFlag(name) {
+  // ---- Local overrides (Statsig-style) ----
+  //
+  // Precedence (highest first): programmatic override (these methods) > URL
+  // override (?se_gate_/?se_config_/?se_exp_) > fetched eval result. A
+  // programmatic override is an explicit in-code decision, so it wins over the
+  // ad-hoc URL/devtools overrides as well as the server's evaluation.
+  /** Force `getFlag(name)` to return `value`, ignoring URL overrides + eval. */
+  overrideFlag(name, value) {
+    this.flagOverrides.set(name, value);
+  }
+  /** Force `getConfig(name)` to return `value`, ignoring URL overrides + eval. */
+  overrideConfig(name, value) {
+    this.configOverrides.set(name, value);
+  }
+  /**
+   * Force `getExperiment(name, …)` to return `{ inExperiment: true, group, params }`,
+   * ignoring URL overrides, the eval result, and exposure logging.
+   */
+  overrideExperiment(name, group, params) {
+    this.experimentOverrides.set(name, { group, params });
+  }
+  /** Remove every programmatic override set via the override* methods. */
+  clearOverrides() {
+    this.flagOverrides.clear();
+    this.configOverrides.clear();
+    this.experimentOverrides.clear();
+  }
+  /**
+   * Evaluate a gate and report WHY (LaunchDarkly variationDetail parity). A
+   * local override OR a ?se_gate_/?se_ks_ URL override short-circuits BEFORE
+   * telemetry; otherwise exactly one "gate" beacon is emitted. The server
+   * pre-evaluates a gate's enabled/killed state into a plain boolean, so OFF
+   * folds into DEFAULT here (the browser can't tell "disabled" from "rule
+   * denied").
+   */
+  getFlagDetail(name) {
+    const pov = this.flagOverrides.get(name);
+    if (pov !== void 0) return { value: pov, reason: "OVERRIDE" };
+    const urlOv = readGateOverride(name);
+    if (urlOv !== null) return { value: urlOv, reason: "OVERRIDE" };
     this.telemetry.emit("gate", name);
-    if (this.evalResult === null) return false;
-    const ov = readGateOverride(name);
-    if (ov !== null) return ov;
-    return this.evalResult.flags[name] ?? false;
+    if (this.evalResult === null) return { value: false, reason: "CLIENT_NOT_READY" };
+    if (!(name in this.evalResult.flags)) return { value: false, reason: "FLAG_NOT_FOUND" };
+    const value = this.evalResult.flags[name] ?? false;
+    return { value, reason: value ? "RULE_MATCH" : "DEFAULT" };
   }
-  getConfig(name, decode) {
+  /**
+   * Read a feature gate. Returns `defaultValue` ONLY when the gate cannot be
+   * evaluated (not ready or flag not found) — never for a gate that legitimately
+   * evaluates to false. Plain `getFlag(name)` keeps returning false for a
+   * missing flag.
+   */
+  getFlag(name, defaultValue = false) {
+    const d = this.getFlagDetail(name);
+    if (d.reason === "CLIENT_NOT_READY" || d.reason === "FLAG_NOT_FOUND") return defaultValue;
+    return d.value;
+  }
+  getConfig(name, decodeOrOpts) {
     this.telemetry.emit("config", name);
-    if (this.evalResult === null) return void 0;
-    const ov = readConfigOverride(name);
-    const raw = ov !== void 0 ? ov : this.evalResult.configs?.[name];
-    if (raw === void 0) return void 0;
-    if (!decode) return raw;
+    const opts = typeof decodeOrOpts === "function" ? { decode: decodeOrOpts } : decodeOrOpts ?? {};
+    const fallback = "defaultValue" in opts ? opts.defaultValue : void 0;
+    const hasProgrammatic = this.configOverrides.has(name);
+    if (!hasProgrammatic && this.evalResult === null) return fallback;
+    const urlOv = hasProgrammatic ? void 0 : readConfigOverride(name);
+    const raw = hasProgrammatic ? this.configOverrides.get(name) : urlOv !== void 0 ? urlOv : this.evalResult?.configs?.[name];
+    if (raw === void 0) return fallback;
+    if (!opts.decode) return raw;
     try {
-      return decode(raw);
+      return opts.decode(raw);
     } catch (err) {
       console.warn(`[shipeasy] getConfig('${name}') decode failed:`, String(err));
       return void 0;
@@ -1018,6 +1122,12 @@ var FlagsClientBrowser = class {
       group: "control",
       params: defaultParams
     };
+    const pov = this.experimentOverrides.get(name);
+    if (pov) {
+      const variantParams = variants?.[pov.group];
+      const params = { ...defaultParams, ...pov.params, ...variantParams ?? {} };
+      return { inExperiment: true, group: pov.group, params };
+    }
     const ov = readExpOverride(name);
     if (ov !== null) {
       const variantParams = variants?.[ov];
@@ -1069,6 +1179,7 @@ var FlagsClientBrowser = class {
     return bridge;
   }
   track(eventName, props) {
+    if (this.testMode) return;
     this.buffer.pushMetric(eventName, this.userId, this.anonId, props);
   }
   /**
@@ -1287,12 +1398,19 @@ var flags = {
    * Everything else gates on _mountedAndReady to prevent hydration mismatches on
    * force-static pages where SSR has no flag data.
    */
-  get(name) {
+  get(name, defaultValue = false) {
     const bs = getBootstrap();
     if (bs !== null && name in bs.flags) return bs.flags[name];
-    if (!_mountedAndReady) return false;
-    if (_client) return _client.getFlag(name);
-    return readGateOverride(name) ?? false;
+    if (!_mountedAndReady) return defaultValue;
+    if (_client) return _client.getFlag(name, defaultValue);
+    return readGateOverride(name) ?? defaultValue;
+  },
+  /** Evaluate a gate and report why (value + reason). See {@link FlagDetail}. */
+  getDetail(name) {
+    if (_client) return _client.getFlagDetail(name);
+    const ov = readGateOverride(name);
+    if (ov !== null) return { value: ov, reason: "OVERRIDE" };
+    return { value: false, reason: "CLIENT_NOT_READY" };
   },
   getConfig(name, decode) {
     const bs = getBootstrap();
@@ -1624,6 +1742,7 @@ var i18n = {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  FLAG_REASONS,
   FlagsClientBrowser,
   LABEL_MARKER_END,
   LABEL_MARKER_RE,