@spooky-sync/core 0.0.1-canary.167 → 0.0.1-canary.169

package/dist/index.d.ts

@@ -1636,6 +1636,15 @@ interface FeatureFlagOptions {
   fallback?: string;
   ttl?: QueryTimeToLive;
 }
+/**
+ * A locally forced variant. Applies to THIS browser only and is never sent to
+ * the server — the assignment in `_00_user_feature` is untouched, so clearing
+ * the override restores whatever the server says.
+ */
+interface FeatureFlagOverride {
+  variant: string;
+  payload?: unknown;
+}
 declare class FeatureFlagHandle {
   readonly key: string;
   readonly fallback: string | undefined;
@@ -1672,6 +1681,7 @@ declare class FeatureFlagModule<S extends SchemaStructure> {
   private ttl;
   private snapshots;
   private loaded;
+  private overrides;
   constructor(deps: FeatureFlagModuleDeps<S>);
   init(): void;
   feature(key: string, options?: FeatureFlagOptions): FeatureFlagHandle;
@@ -1683,6 +1693,21 @@ declare class FeatureFlagModule<S extends SchemaStructure> {
   private ensureStarted;
   /** Live query result → per-key snapshots → push to every active handle. */
   private applyRecords;
+  /**
+   * Force `key` to `variant` in THIS browser. Pass `null` to clear.
+   *
+   * Nothing is written to the server: the `_00_user_feature` assignment is
+   * untouched, so clearing restores whatever the server says. Persisted to
+   * localStorage on the page origin, so it survives a reload.
+   */
+  setLocalOverride(key: string, variant: string | null, payload?: unknown): void;
+  clearLocalOverrides(): void;
+  getLocalOverrides(): Record<string, FeatureFlagOverride>;
+  /** The assignment for `key`, with any local override taking precedence. */
+  private resolve;
+  private pushAll;
+  private loadOverrides;
+  private persistOverrides;
 }
 //#endregion
 //#region src/modules/app-release/index.d.ts
@@ -2126,6 +2151,22 @@ declare class Sp00kyClient<S extends SchemaStructure> {
    * its own row, and cannot create or modify assignments.
    */
   feature(key: string, options?: FeatureFlagOptions): FeatureFlagHandle;
+  /**
+   * Force a feature flag to `variant` in THIS browser only; `null` clears it.
+   *
+   * Nothing is sent to the server — the `_00_user_feature` assignment is
+   * untouched, so clearing restores whatever the server says. Persisted to
+   * localStorage, survives reloads, and applies while signed out. Backs the
+   * DevTools Flags tab, and is a convenient hook for tests.
+   *
+   * To change a flag for OTHER users you need admin rights (`spky admin add`)
+   * and the DevTools Flags tab, or `spky flag`.
+   */
+  setFeatureOverride(key: string, variant: string | null, payload?: unknown): void;
+  /** Drop every local feature flag override set via `setFeatureOverride`. */
+  clearFeatureOverrides(): void;
+  /** The local feature flag overrides currently in effect, keyed by flag. */
+  getFeatureOverrides(): Record<string, FeatureFlagOverride>;
   /**
    * Observe the announced release of an app (`_00_app_release:<app>`, written
    * by `spky deploy` / `spky release`). The handle's `snapshot()` carries the
@@ -2248,4 +2289,4 @@ declare function textToHtml(text: string): string;
  */
 
 //#endregion
-export { AppReleaseHandle, AppReleaseModule, type AppReleaseOptions, type AppReleaseSnapshot, AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, type BlobCacheStats, type BlobEntry, type BlobKey, type BlobReadOptions, type BlobUrlLease, BucketHandle, CURSOR_COLORS, ConnectionState, CrdtField, CrdtManager, DebounceOptions, EventSubscriptionOptions, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagSnapshot, Level, MATERIALIZATION_SAMPLE_WINDOW, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PhaseStat, PinoTransmit, PreloadOptions, PreloadRefresh, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, ReconnectConfig, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StorageHealth, StorageHealthStatus, StoreType, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, UpdateOptions, bucketContentToBlob, createAuthEventSystem, cursorColorFromName, fileToUint8Array, semverGt, textToHtml };
+export { AppReleaseHandle, AppReleaseModule, type AppReleaseOptions, type AppReleaseSnapshot, AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, type BlobCacheStats, type BlobEntry, type BlobKey, type BlobReadOptions, type BlobUrlLease, BucketHandle, CURSOR_COLORS, ConnectionState, CrdtField, CrdtManager, DebounceOptions, EventSubscriptionOptions, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagOverride, type FeatureFlagSnapshot, Level, MATERIALIZATION_SAMPLE_WINDOW, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PhaseStat, PinoTransmit, PreloadOptions, PreloadRefresh, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, ReconnectConfig, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StorageHealth, StorageHealthStatus, StoreType, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, UpdateOptions, bucketContentToBlob, createAuthEventSystem, cursorColorFromName, fileToUint8Array, semverGt, textToHtml };

package/dist/index.js

@@ -6541,10 +6541,196 @@ async function walkOpfs(maxEntries = 2e3, maxDepth = 8) {
 	}
 }
 
+//#endregion
+//#region src/modules/devtools/flags.ts
+/**
+* SurrealDB's SDK returns one entry per statement; each entry is the rows for
+* that statement, but older/local shapes wrap them as `{ status, result }`.
+* `getTableData` in `index.ts` unwraps the same three shapes inline — this is
+* that logic, reusable.
+*/
+function statementRows(result, index = 0) {
+	if (!Array.isArray(result)) return [];
+	const entry = result[index];
+	if (Array.isArray(entry)) return entry;
+	if (entry && typeof entry === "object" && "result" in entry) {
+		const inner = entry.result;
+		return Array.isArray(inner) ? inner : inner === void 0 || inner === null ? [] : [inner];
+	}
+	return entry === void 0 || entry === null ? [] : [entry];
+}
+function message(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+/** Row shape guards. `key` is the only field the panel truly can't do without. */
+function hasStringKey(row) {
+	return !!row && typeof row === "object" && typeof row.key === "string";
+}
+function isAssignment(row) {
+	return hasStringKey(row);
+}
+function isFlagRow(row) {
+	return hasStringKey(row);
+}
+var FlagsAdminService = class {
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/**
+	* Everything the Flags tab renders, in one round trip per source.
+	*
+	* Each section fails independently: a remote read that throws downgrades to
+	* `isAdmin: false` plus an `error`, while local assignments and overrides
+	* still render. Signing out must not blank the whole tab.
+	*/
+	async getFlags() {
+		const userId = this.deps.currentUserId();
+		const snapshot = {
+			at: Date.now(),
+			userId,
+			isAdmin: false,
+			flags: [],
+			assignments: [],
+			overrides: this.deps.overrides()?.getLocalOverrides() ?? {}
+		};
+		try {
+			snapshot.assignments = statementRows(await this.deps.local.query("SELECT key, variant, payload FROM _00_user_feature")).filter(isAssignment).map((r) => ({
+				key: r.key,
+				variant: r.variant,
+				payload: r.payload
+			}));
+		} catch (err) {
+			this.deps.logger.debug({
+				err,
+				Category: "sp00ky-client::FlagsAdminService::getFlags"
+			}, "Local feature assignments unavailable");
+		}
+		if (!userId) return snapshot;
+		try {
+			snapshot.isAdmin = statementRows(await this.deps.remote.query("SELECT VALUE id FROM _00_admin WHERE user = $auth.id LIMIT 1")).length > 0;
+		} catch (err) {
+			snapshot.error = `Could not check admin status: ${message(err)}. If this deployment predates the Flags tab, run \`spky migrate\` (or redeploy) to apply the internal schema.`;
+			return snapshot;
+		}
+		if (!snapshot.isAdmin) return snapshot;
+		try {
+			snapshot.flags = statementRows(await this.deps.remote.query("SELECT key, description, variants, default_variant, enabled, payloads, rules, updated_at FROM _00_feature_flag ORDER BY key ASC")).filter(isFlagRow).map((flag) => ({
+				...flag,
+				rules: Array.isArray(flag.rules) ? flag.rules : [],
+				variants: Array.isArray(flag.variants) ? flag.variants : [],
+				selfAllowlistedVariant: selfAllowlistedVariant(flag, userId)
+			}));
+		} catch (err) {
+			snapshot.error = `Could not read feature flags: ${message(err)}`;
+		}
+		return snapshot;
+	}
+	/**
+	* Flip a flag's global `enabled` bit for EVERY user, then re-materialize.
+	*
+	* Both statements are one request so they share a transaction: if the
+	* materialize fails, the `enabled` change rolls back rather than leaving the
+	* definition and the assignments disagreeing.
+	*/
+	async setFlagEnabled(key, enabled) {
+		return this.mutate("UPDATE _00_feature_flag SET enabled = $enabled WHERE key = $key; RETURN fn::feature::materialize($key);", {
+			key,
+			enabled
+		}, 1);
+	}
+	/**
+	* Add or remove a user from `$key`'s allowlist for `$variant`, then
+	* re-materialize. Defaults to the signed-in user, so the common case
+	* ("turn this on for me, for real") needs no user picker.
+	*/
+	async setFlagUserVariant(key, variant, remove, userId) {
+		const target = userId ?? this.deps.currentUserId();
+		if (!target) return {
+			success: false,
+			error: "Not signed in"
+		};
+		let user;
+		try {
+			user = parseRecordIdString(target);
+		} catch (err) {
+			return {
+				success: false,
+				error: `Invalid user id '${target}': ${message(err)}`
+			};
+		}
+		return remove ? this.mutate("RETURN fn::feature::disallow($key, $user);", {
+			key,
+			user
+		}, 0) : this.mutate("RETURN fn::feature::allow($key, $variant, $user);", {
+			key,
+			variant,
+			user
+		}, 0);
+	}
+	setLocalFlagOverride(key, variant, payload) {
+		const store = this.deps.overrides();
+		store?.setLocalOverride(key, variant, payload);
+		return { overrides: store?.getLocalOverrides() ?? {} };
+	}
+	clearLocalFlagOverrides() {
+		const store = this.deps.overrides();
+		store?.clearLocalOverrides();
+		return { overrides: store?.getLocalOverrides() ?? {} };
+	}
+	/**
+	* Run a remote mutation, reporting the materialize count from `$index`.
+	*
+	* Retries on a transaction conflict. `fn::feature::allow` / `disallow` are
+	* read-modify-write over `_00_feature_flag.rules`, so two admins acting on
+	* the same flag at once collide. SurrealDB detects this and fails the loser
+	* with "Transaction conflict ... can be retried" rather than losing the
+	* write — verified against 3.1 — so nothing is silently dropped. Retrying
+	* turns that into the outcome the user expected instead of a raw engine
+	* error they can do nothing with.
+	*/
+	async mutate(sql, vars, index) {
+		let lastError;
+		for (let attempt = 0; attempt < MUTATE_ATTEMPTS; attempt++) try {
+			return {
+				success: true,
+				users: statementRows(await this.deps.remote.query(sql, vars), index)[0]?.users
+			};
+		} catch (err) {
+			lastError = err;
+			if (!isRetryableConflict(err) || attempt === MUTATE_ATTEMPTS - 1) break;
+			await sleep(40 * (attempt + 1) + Math.random() * 40);
+		}
+		this.deps.logger.warn({
+			err: lastError,
+			sql,
+			Category: "sp00ky-client::FlagsAdminService::mutate"
+		}, "Feature flag mutation failed");
+		return {
+			success: false,
+			error: message(lastError)
+		};
+	}
+};
+const MUTATE_ATTEMPTS = 3;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function isRetryableConflict(err) {
+	return /transaction (write )?conflict/i.test(message(err));
+}
+/**
+* Which variant, if any, this user is explicitly allowlisted into.
+*
+* `rules[].users` holds record-id strings (`flag.rs` serialises them as JSON),
+* so compare as strings. Lets the panel show "you're on the list" without
+* making the user reason about a raw rules blob.
+*/
+function selfAllowlistedVariant(flag, userId) {
+	return (Array.isArray(flag.rules) ? flag.rules : []).find((rule) => rule?.kind === "allowlist" && Array.isArray(rule.users) && rule.users.some((u) => String(u) === userId))?.variant;
+}
+
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.167";
-const WASM_VERSION = "0.0.1-canary.167";
+const CORE_VERSION = "0.0.1-canary.169";
+const WASM_VERSION = "0.0.1-canary.169";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	eventsHistory = [];
@@ -6569,6 +6755,8 @@ var DevToolsService = class DevToolsService {
 	localTables = [];
 	localTablesFetching = false;
 	localTablesAt = 0;
+	featureOverrides = null;
+	flagsAdmin;
 	constructor(databaseService, remoteDatabaseService, logger, schema, authService, dataManager) {
 		this.databaseService = databaseService;
 		this.remoteDatabaseService = remoteDatabaseService;
@@ -6576,6 +6764,17 @@ var DevToolsService = class DevToolsService {
 		this.schema = schema;
 		this.authService = authService;
 		this.dataManager = dataManager;
+		this.flagsAdmin = new FlagsAdminService({
+			remote: this.remoteDatabaseService,
+			local: this.databaseService,
+			logger: this.logger,
+			currentUserId: () => {
+				const id = this.authService.currentUser?.id;
+				if (!id) return null;
+				return id instanceof RecordId ? encodeRecordId(id) : String(id);
+			},
+			overrides: () => this.featureOverrides
+		});
 		this.exposeToWindow();
 		if (typeof window !== "undefined") window.addEventListener("message", (e) => {
 			if (e.source !== window) return;
@@ -6888,11 +7087,24 @@ var DevToolsService = class DevToolsService {
 		}
 		return data;
 	}
+	/**
+	* Hand the FeatureFlagModule to the Flags tab so it can read and write local
+	* overrides. Called from `Sp00kyClient` once both are constructed; until then
+	* the override methods are no-ops that report an empty map.
+	*/
+	setFeatureFlagOverrides(store) {
+		this.featureOverrides = store;
+	}
 	exposeToWindow() {
 		if (typeof window !== "undefined") {
 			window.__00__ = {
 				version: this.version,
 				getState: () => this.getState(),
+				getFlags: () => this.flagsAdmin.getFlags(),
+				setFlagEnabled: (key, enabled) => this.flagsAdmin.setFlagEnabled(key, enabled),
+				setFlagUserVariant: (key, variant, remove, userId) => this.flagsAdmin.setFlagUserVariant(key, variant, remove, userId),
+				setLocalFlagOverride: (key, variant, payload) => this.flagsAdmin.setLocalFlagOverride(key, variant, payload),
+				clearLocalFlagOverrides: () => this.flagsAdmin.clearLocalFlagOverrides(),
 				clearHistory: () => {
 					this.eventsHistory = [];
 					this.notifyDevTools();
@@ -8504,6 +8716,7 @@ var CrdtManager = class {
 //#endregion
 //#region src/modules/feature-flag/index.ts
 const FEATURE_QUERY = "SELECT key, variant, payload FROM _00_user_feature";
+const OVERRIDE_STORAGE_KEY = "sp00ky:feature-overrides";
 var FeatureFlagHandle = class {
 	latest = {
 		variant: void 0,
@@ -8571,9 +8784,11 @@ var FeatureFlagModule = class {
 	ttl = "10m";
 	snapshots = /* @__PURE__ */ new Map();
 	loaded = false;
+	overrides = /* @__PURE__ */ new Map();
 	constructor(deps) {
 		this.deps = deps;
 		this.logger = deps.logger.child({ service: "FeatureFlagModule" });
+		this.loadOverrides();
 	}
 	init() {
 		if (this.authUnsubscribe) return;
@@ -8588,10 +8803,7 @@ var FeatureFlagModule = class {
 		this.handles.add(handle);
 		handle.onClose(() => this.handles.delete(handle));
 		if (options.ttl) this.ttl = options.ttl;
-		if (this.loaded) handle.set(this.snapshots.get(key) ?? {
-			variant: void 0,
-			payload: void 0
-		});
+		if (this.loaded || this.overrides.has(key)) handle.set(this.resolve(key));
 		this.ensureStarted();
 		return handle;
 	}
@@ -8606,10 +8818,7 @@ var FeatureFlagModule = class {
 		this.teardownQuery();
 		this.loaded = false;
 		this.snapshots.clear();
-		for (const handle of this.handles) handle.set({
-			variant: void 0,
-			payload: void 0
-		});
+		for (const handle of this.handles) handle.set(this.resolve(handle.key));
 		await this.ensureStarted();
 	}
 	teardownQuery() {
@@ -8644,10 +8853,73 @@ var FeatureFlagModule = class {
 			payload: row.payload
 		});
 		this.loaded = true;
-		for (const handle of this.handles) handle.set(this.snapshots.get(handle.key) ?? {
+		this.pushAll();
+	}
+	/**
+	* Force `key` to `variant` in THIS browser. Pass `null` to clear.
+	*
+	* Nothing is written to the server: the `_00_user_feature` assignment is
+	* untouched, so clearing restores whatever the server says. Persisted to
+	* localStorage on the page origin, so it survives a reload.
+	*/
+	setLocalOverride(key, variant, payload) {
+		if (variant === null) this.overrides.delete(key);
+		else this.overrides.set(key, {
+			variant,
+			payload
+		});
+		this.persistOverrides();
+		this.pushAll();
+	}
+	clearLocalOverrides() {
+		this.overrides.clear();
+		this.persistOverrides();
+		this.pushAll();
+	}
+	getLocalOverrides() {
+		return Object.fromEntries(this.overrides);
+	}
+	/** The assignment for `key`, with any local override taking precedence. */
+	resolve(key) {
+		const override = this.overrides.get(key);
+		if (override) return {
+			variant: override.variant,
+			payload: override.payload
+		};
+		return this.snapshots.get(key) ?? {
 			variant: void 0,
 			payload: void 0
-		});
+		};
+	}
+	pushAll() {
+		for (const handle of this.handles) handle.set(this.resolve(handle.key));
+	}
+	loadOverrides() {
+		try {
+			const raw = globalThis.localStorage?.getItem(OVERRIDE_STORAGE_KEY);
+			if (!raw) return;
+			const parsed = JSON.parse(raw);
+			for (const [key, value] of Object.entries(parsed ?? {})) if (value && typeof value.variant === "string") this.overrides.set(key, value);
+		} catch (err) {
+			this.logger.warn({
+				err,
+				Category: "sp00ky-client::FeatureFlagModule::loadOverrides"
+			}, "Failed to read local feature flag overrides");
+		}
+	}
+	persistOverrides() {
+		try {
+			if (this.overrides.size === 0) {
+				globalThis.localStorage?.removeItem(OVERRIDE_STORAGE_KEY);
+				return;
+			}
+			globalThis.localStorage?.setItem(OVERRIDE_STORAGE_KEY, JSON.stringify(this.getLocalOverrides()));
+		} catch (err) {
+			this.logger.warn({
+				err,
+				Category: "sp00ky-client::FeatureFlagModule::persistOverrides"
+			}, "Failed to persist local feature flag overrides");
+		}
 	}
 };
 
@@ -10849,6 +11121,7 @@ var Sp00kyClient = class {
 			logger
 		});
 		this.devTools = new DevToolsService(this.local, this.remote, logger, this.config.schema, this.auth, this.dataModule);
+		this.devTools.setFeatureFlagOverrides(this.featureFlags);
 		this.streamProcessor.addReceiver(this.devTools);
 		this.setupCallbacks();
 		if (tabsSupport.supported) this.tabsCoordinator = this.buildTabsCoordinator();
@@ -10887,7 +11160,7 @@ var Sp00kyClient = class {
 		return new TabsCoordinator({
 			tabId,
 			fingerprint: computeTabsFingerprint({
-				coreVersion: "0.0.1-canary.167",
+				coreVersion: "0.0.1-canary.169",
 				schemaHash: hash53(this.config.schemaSurql),
 				endpoint: this.config.database.endpoint ?? "",
 				namespace: this.config.database.namespace,
@@ -11228,6 +11501,28 @@ var Sp00kyClient = class {
 		return this.featureFlags.feature(key, options);
 	}
 	/**
+	* Force a feature flag to `variant` in THIS browser only; `null` clears it.
+	*
+	* Nothing is sent to the server — the `_00_user_feature` assignment is
+	* untouched, so clearing restores whatever the server says. Persisted to
+	* localStorage, survives reloads, and applies while signed out. Backs the
+	* DevTools Flags tab, and is a convenient hook for tests.
+	*
+	* To change a flag for OTHER users you need admin rights (`spky admin add`)
+	* and the DevTools Flags tab, or `spky flag`.
+	*/
+	setFeatureOverride(key, variant, payload) {
+		this.featureFlags.setLocalOverride(key, variant, payload);
+	}
+	/** Drop every local feature flag override set via `setFeatureOverride`. */
+	clearFeatureOverrides() {
+		this.featureFlags.clearLocalOverrides();
+	}
+	/** The local feature flag overrides currently in effect, keyed by flag. */
+	getFeatureOverrides() {
+		return this.featureFlags.getLocalOverrides();
+	}
+	/**
 	* Observe the announced release of an app (`_00_app_release:<app>`, written
 	* by `spky deploy` / `spky release`). The handle's `snapshot()` carries the
 	* announced version plus the cache-bust/mandatory flags, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.167",
+  "version": "0.0.1-canary.169",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -60,8 +60,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.167",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.167",
+    "@spooky-sync/query-builder": "0.0.1-canary.169",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.169",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.0.3",
     "fast-json-patch": "^3.1.1",

package/src/index.ts

@@ -6,6 +6,7 @@ export {
   FeatureFlagModule,
   FeatureFlagHandle,
   type FeatureFlagOptions,
+  type FeatureFlagOverride,
   type FeatureFlagSnapshot,
 } from './modules/feature-flag/index';
 export {

package/src/modules/devtools/flags.ts

@@ -0,0 +1,349 @@
+/**
+ * Feature flag administration for the DevTools panel.
+ *
+ * Two independent capabilities, deliberately kept apart:
+ *
+ * - **Local overrides** force a variant in THIS browser. No auth, no network,
+ *   works signed out and offline. Delegated straight to `FeatureFlagModule`.
+ * - **Remote changes** flip a flag for EVERY user. These require the caller to
+ *   be listed in `_00_admin` (`spky admin add <user>`); SurrealDB enforces
+ *   that, not this file. A non-admin's SELECT returns `[]` rather than an
+ *   error, and the `fn::feature::*` calls are hard-denied.
+ *
+ * Everything remote goes through `RemoteDatabaseService` with BOUND params.
+ * The panel's generic `runQuery` bridge is not usable here: it interpolates
+ * the SurrealQL into an `inspectedWindow.eval` string (so a DB-sourced flag
+ * key or record id would be concatenated into code) and it rejects after 10s,
+ * which a materialize over a real user table will exceed.
+ *
+ * Definitions live in `_00_feature_flag`, which is NOT synced to clients, so
+ * flags must be read remotely. Per-user assignments live in `_00_user_feature`,
+ * which IS live-synced, so those come from the local store for free.
+ */
+
+import type { Logger } from '../../services/logger/index';
+import { parseRecordIdString } from '../../utils/index';
+
+/**
+ * The only thing this service needs from a database. Structural rather than
+ * `AbstractDatabaseService`, because the local side is a `LocalStore` (which
+ * wraps a database rather than extending it) and both must satisfy it.
+ */
+export interface FlagQueryable {
+  query<T extends unknown[]>(query: string, vars?: Record<string, unknown>): Promise<T>;
+}
+
+/** A targeting rule as written by `spky flag` / `fn::feature::allow`. */
+export interface DevToolsFlagRule {
+  kind: 'allowlist' | 'rollout' | string;
+  variant: string;
+  /** Allowlist only. Stored as record-id STRINGS, not records. */
+  users?: string[];
+  /** Rollout only, 0..100. */
+  percent?: number;
+  priority: number;
+}
+
+export interface DevToolsFlagRow {
+  key: string;
+  description?: string;
+  variants: string[];
+  default_variant: string;
+  enabled: boolean;
+  payloads?: Record<string, unknown>;
+  rules: DevToolsFlagRule[];
+  updated_at?: string;
+  /** Derived: the variant the signed-in user is allowlisted into, if any. */
+  selfAllowlistedVariant?: string;
+}
+
+export interface DevToolsFlagAssignment {
+  key: string;
+  variant: string;
+  payload?: unknown;
+}
+
+export interface DevToolsFlagOverride {
+  variant: string;
+  payload?: unknown;
+}
+
+export interface DevToolsFlagsSnapshot {
+  at: number;
+  /** Null when signed out. */
+  userId: string | null;
+  /** True when `_00_admin` has a row for the signed-in user. */
+  isAdmin: boolean;
+  /** Empty for non-admins — SurrealDB filters the rows, it does not error. */
+  flags: DevToolsFlagRow[];
+  /** From the LOCAL `_00_user_feature`: what this browser actually resolves. */
+  assignments: DevToolsFlagAssignment[];
+  /** Local-only forced variants, page-origin localStorage. */
+  overrides: Record<string, DevToolsFlagOverride>;
+  /**
+   * Set when the internal schema predates this feature (no `_00_admin` table),
+   * or the remote read failed. The panel shows it instead of a bare empty
+   * state, so "not migrated" doesn't look like "you're not an admin".
+   */
+  error?: string;
+}
+
+export interface DevToolsFlagResult {
+  success: boolean;
+  error?: string;
+  /** Users re-evaluated by `fn::feature::materialize`. */
+  users?: number;
+}
+
+/** The slice of `FeatureFlagModule` this service needs. */
+export interface LocalOverrideStore {
+  setLocalOverride(key: string, variant: string | null, payload?: unknown): void;
+  clearLocalOverrides(): void;
+  getLocalOverrides(): Record<string, DevToolsFlagOverride>;
+}
+
+export interface FlagsAdminDeps {
+  remote: FlagQueryable;
+  local: FlagQueryable;
+  logger: Logger;
+  /** Resolves the signed-in user's record id, or null. */
+  currentUserId: () => string | null;
+  /** Set once the client has built its FeatureFlagModule. */
+  overrides: () => LocalOverrideStore | null;
+}
+
+/**
+ * SurrealDB's SDK returns one entry per statement; each entry is the rows for
+ * that statement, but older/local shapes wrap them as `{ status, result }`.
+ * `getTableData` in `index.ts` unwraps the same three shapes inline — this is
+ * that logic, reusable.
+ */
+function statementRows(result: unknown, index = 0): unknown[] {
+  if (!Array.isArray(result)) return [];
+  const entry = result[index];
+  if (Array.isArray(entry)) return entry;
+  if (entry && typeof entry === 'object' && 'result' in entry) {
+    const inner = (entry as { result?: unknown }).result;
+    return Array.isArray(inner) ? inner : inner === undefined || inner === null ? [] : [inner];
+  }
+  return entry === undefined || entry === null ? [] : [entry];
+}
+
+function message(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/** Row shape guards. `key` is the only field the panel truly can't do without. */
+function hasStringKey(row: unknown): row is { key: string } {
+  return !!row && typeof row === 'object' && typeof (row as { key?: unknown }).key === 'string';
+}
+
+function isAssignment(row: unknown): row is DevToolsFlagAssignment {
+  return hasStringKey(row);
+}
+
+function isFlagRow(row: unknown): row is DevToolsFlagRow {
+  return hasStringKey(row);
+}
+
+export class FlagsAdminService {
+  constructor(private deps: FlagsAdminDeps) {}
+
+  /**
+   * Everything the Flags tab renders, in one round trip per source.
+   *
+   * Each section fails independently: a remote read that throws downgrades to
+   * `isAdmin: false` plus an `error`, while local assignments and overrides
+   * still render. Signing out must not blank the whole tab.
+   */
+  async getFlags(): Promise<DevToolsFlagsSnapshot> {
+    const userId = this.deps.currentUserId();
+    const snapshot: DevToolsFlagsSnapshot = {
+      at: Date.now(),
+      userId,
+      isAdmin: false,
+      flags: [],
+      assignments: [],
+      overrides: this.deps.overrides()?.getLocalOverrides() ?? {},
+    };
+
+    // Local assignments: available signed out and offline.
+    try {
+      const rows = statementRows(
+        await this.deps.local.query('SELECT key, variant, payload FROM _00_user_feature')
+      );
+      snapshot.assignments = rows.filter(isAssignment).map((r) => ({
+        key: r.key,
+        variant: r.variant,
+        payload: r.payload,
+      }));
+    } catch (err) {
+      this.deps.logger.debug(
+        { err, Category: 'sp00ky-client::FlagsAdminService::getFlags' },
+        'Local feature assignments unavailable'
+      );
+    }
+
+    if (!userId) return snapshot;
+
+    try {
+      // Self-scoped by `_00_admin`'s own select rule: an admin sees exactly
+      // their own row, a non-admin sees nothing. The roster never leaks.
+      const admin = statementRows(
+        await this.deps.remote.query('SELECT VALUE id FROM _00_admin WHERE user = $auth.id LIMIT 1')
+      );
+      snapshot.isAdmin = admin.length > 0;
+    } catch (err) {
+      // A missing `_00_admin` table means the deployment hasn't applied the
+      // internal schema yet. Say so — otherwise it reads as "not an admin".
+      snapshot.error = `Could not check admin status: ${message(err)}. If this deployment predates the Flags tab, run \`spky migrate\` (or redeploy) to apply the internal schema.`;
+      return snapshot;
+    }
+
+    if (!snapshot.isAdmin) return snapshot;
+
+    try {
+      const rows = statementRows(
+        await this.deps.remote.query(
+          'SELECT key, description, variants, default_variant, enabled, payloads, rules, updated_at ' +
+            'FROM _00_feature_flag ORDER BY key ASC'
+        )
+      );
+      snapshot.flags = rows
+        .filter(isFlagRow)
+        .map((flag) => ({
+          ...flag,
+          rules: Array.isArray(flag.rules) ? flag.rules : [],
+          variants: Array.isArray(flag.variants) ? flag.variants : [],
+          selfAllowlistedVariant: selfAllowlistedVariant(flag, userId),
+        }));
+    } catch (err) {
+      snapshot.error = `Could not read feature flags: ${message(err)}`;
+    }
+
+    return snapshot;
+  }
+
+  /**
+   * Flip a flag's global `enabled` bit for EVERY user, then re-materialize.
+   *
+   * Both statements are one request so they share a transaction: if the
+   * materialize fails, the `enabled` change rolls back rather than leaving the
+   * definition and the assignments disagreeing.
+   */
+  async setFlagEnabled(key: string, enabled: boolean): Promise<DevToolsFlagResult> {
+    return this.mutate(
+      'UPDATE _00_feature_flag SET enabled = $enabled WHERE key = $key; ' +
+        'RETURN fn::feature::materialize($key);',
+      { key, enabled },
+      1
+    );
+  }
+
+  /**
+   * Add or remove a user from `$key`'s allowlist for `$variant`, then
+   * re-materialize. Defaults to the signed-in user, so the common case
+   * ("turn this on for me, for real") needs no user picker.
+   */
+  async setFlagUserVariant(
+    key: string,
+    variant: string,
+    remove: boolean,
+    userId?: string
+  ): Promise<DevToolsFlagResult> {
+    const target = userId ?? this.deps.currentUserId();
+    if (!target) return { success: false, error: 'Not signed in' };
+
+    // `fn::feature::allow/disallow` declare `$user: record`. A string binding
+    // is rejected by the type check, so parse it into a real RecordId.
+    let user;
+    try {
+      user = parseRecordIdString(target);
+    } catch (err) {
+      return { success: false, error: `Invalid user id '${target}': ${message(err)}` };
+    }
+
+    return remove
+      ? this.mutate('RETURN fn::feature::disallow($key, $user);', { key, user }, 0)
+      : this.mutate('RETURN fn::feature::allow($key, $variant, $user);', { key, variant, user }, 0);
+  }
+
+  setLocalFlagOverride(
+    key: string,
+    variant: string | null,
+    payload?: unknown
+  ): { overrides: Record<string, DevToolsFlagOverride> } {
+    const store = this.deps.overrides();
+    store?.setLocalOverride(key, variant, payload);
+    return { overrides: store?.getLocalOverrides() ?? {} };
+  }
+
+  clearLocalFlagOverrides(): { overrides: Record<string, DevToolsFlagOverride> } {
+    const store = this.deps.overrides();
+    store?.clearLocalOverrides();
+    return { overrides: store?.getLocalOverrides() ?? {} };
+  }
+
+  /**
+   * Run a remote mutation, reporting the materialize count from `$index`.
+   *
+   * Retries on a transaction conflict. `fn::feature::allow` / `disallow` are
+   * read-modify-write over `_00_feature_flag.rules`, so two admins acting on
+   * the same flag at once collide. SurrealDB detects this and fails the loser
+   * with "Transaction conflict ... can be retried" rather than losing the
+   * write — verified against 3.1 — so nothing is silently dropped. Retrying
+   * turns that into the outcome the user expected instead of a raw engine
+   * error they can do nothing with.
+   */
+  private async mutate(
+    sql: string,
+    vars: Record<string, unknown>,
+    index: number
+  ): Promise<DevToolsFlagResult> {
+    let lastError: unknown;
+    for (let attempt = 0; attempt < MUTATE_ATTEMPTS; attempt++) {
+      try {
+        const result = await this.deps.remote.query(sql, vars);
+        const materialized = statementRows(result, index)[0] as { users?: number } | undefined;
+        return { success: true, users: materialized?.users };
+      } catch (err) {
+        lastError = err;
+        if (!isRetryableConflict(err) || attempt === MUTATE_ATTEMPTS - 1) break;
+        // Staggered so two collided clients don't line up again on the retry.
+        await sleep(40 * (attempt + 1) + Math.random() * 40);
+      }
+    }
+
+    this.deps.logger.warn(
+      { err: lastError, sql, Category: 'sp00ky-client::FlagsAdminService::mutate' },
+      'Feature flag mutation failed'
+    );
+    return { success: false, error: message(lastError) };
+  }
+}
+
+const MUTATE_ATTEMPTS = 3;
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function isRetryableConflict(err: unknown): boolean {
+  return /transaction (write )?conflict/i.test(message(err));
+}
+
+/**
+ * Which variant, if any, this user is explicitly allowlisted into.
+ *
+ * `rules[].users` holds record-id strings (`flag.rs` serialises them as JSON),
+ * so compare as strings. Lets the panel show "you're on the list" without
+ * making the user reason about a raw rules blob.
+ */
+function selfAllowlistedVariant(flag: DevToolsFlagRow, userId: string): string | undefined {
+  const rules = Array.isArray(flag.rules) ? flag.rules : [];
+  const hit = rules.find(
+    (rule) =>
+      rule?.kind === 'allowlist' &&
+      Array.isArray(rule.users) &&
+      rule.users.some((u) => String(u) === userId)
+  );
+  return hit?.variant;
+}

package/src/modules/devtools/index.ts

@@ -23,6 +23,7 @@ import {
   UNAVAILABLE,
 } from './versions';
 import { walkOpfs, type BlobCacheInfo, type SharedTabsInfo, type StorageInfo } from './storage-info';
+import { FlagsAdminService, type LocalOverrideStore } from './flags';
 
 // Real bundled frontend versions, injected at build time by tsdown's
 // version-define plugin (see tsdown.config.ts). The `typeof` guard keeps these
@@ -85,6 +86,12 @@ export class DevToolsService implements StreamUpdateReceiver {
   private localTablesFetching = false;
   private localTablesAt = 0;
 
+  // Feature flag admin, backing the panel's Flags tab. The local-override
+  // store is injected later (`setFeatureFlagOverrides`) because the
+  // FeatureFlagModule is built after this service.
+  private featureOverrides: LocalOverrideStore | null = null;
+  private readonly flagsAdmin: FlagsAdminService;
+
   constructor(
     private databaseService: LocalStore,
     private remoteDatabaseService: RemoteDatabaseService,
@@ -93,6 +100,18 @@ export class DevToolsService implements StreamUpdateReceiver {
     private authService: AuthService<SchemaStructure>,
     private dataManager?: DataModule<SchemaStructure>
   ) {
+    this.flagsAdmin = new FlagsAdminService({
+      remote: this.remoteDatabaseService,
+      local: this.databaseService,
+      logger: this.logger,
+      currentUserId: () => {
+        const id = this.authService.currentUser?.id;
+        if (!id) return null;
+        return id instanceof RecordId ? encodeRecordId(id) : String(id);
+      },
+      overrides: () => this.featureOverrides,
+    });
+
     this.exposeToWindow();
 
     // Stay dormant until a devtools consumer announces itself. The extension's
@@ -525,11 +544,33 @@ export class DevToolsService implements StreamUpdateReceiver {
     return data;
   }
 
+  /**
+   * Hand the FeatureFlagModule to the Flags tab so it can read and write local
+   * overrides. Called from `Sp00kyClient` once both are constructed; until then
+   * the override methods are no-ops that report an empty map.
+   */
+  public setFeatureFlagOverrides(store: LocalOverrideStore): void {
+    this.featureOverrides = store;
+  }
+
   private exposeToWindow() {
     if (typeof window !== 'undefined') {
       (window as any).__00__ = {
         version: this.version,
         getState: () => this.getState(),
+        // ---- Feature flags (Flags tab) --------------------------------
+        // Remote reads/writes are admin-gated by SurrealDB, not here: a
+        // non-admin gets an empty flag list, and the `fn::feature::*` calls
+        // are denied outright. The override methods are purely local and
+        // work signed out.
+        getFlags: () => this.flagsAdmin.getFlags(),
+        setFlagEnabled: (key: string, enabled: boolean) =>
+          this.flagsAdmin.setFlagEnabled(key, enabled),
+        setFlagUserVariant: (key: string, variant: string, remove: boolean, userId?: string) =>
+          this.flagsAdmin.setFlagUserVariant(key, variant, remove, userId),
+        setLocalFlagOverride: (key: string, variant: string | null, payload?: unknown) =>
+          this.flagsAdmin.setLocalFlagOverride(key, variant, payload),
+        clearLocalFlagOverrides: () => this.flagsAdmin.clearLocalFlagOverrides(),
         clearHistory: () => {
           this.eventsHistory = [];
           this.notifyDevTools();

package/src/modules/feature-flag/index.test.ts

@@ -1,6 +1,20 @@
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { FeatureFlagModule } from './index';
 
+// vitest runs in the `node` environment here, so there is no localStorage.
+// The module guards every access with `globalThis.localStorage?.`, which keeps
+// overrides in-memory-only — this shim lets the persistence path be tested.
+function installLocalStorage() {
+  const store = new Map<string, string>();
+  const shim = {
+    getItem: (k: string) => store.get(k) ?? null,
+    setItem: (k: string, v: string) => void store.set(k, v),
+    removeItem: (k: string) => void store.delete(k),
+  };
+  (globalThis as any).localStorage = shim;
+  return { store, uninstall: () => delete (globalThis as any).localStorage };
+}
+
 // Minimal mocks for the three deps the module touches. The DataModule mock
 // captures the single subscribe callback so a test can push live results, and
 // counts query() calls to assert the query is SHARED (one registration for all
@@ -118,3 +132,120 @@ describe('FeatureFlagModule', () => {
     expect(env.hasSub()).toBe(true); // re-registered for the new user
   });
 });
+
+// Local overrides force a variant in THIS browser only. They must win over the
+// server assignment on every read path — `variant()`, `payload()`, `enabled()`
+// and `subscribe()` all funnel through the same resolver, so a gap in any one
+// of them is a gap in all of them.
+describe('FeatureFlagModule local overrides', () => {
+  let env: ReturnType<typeof makeDeps>;
+  let mod: FeatureFlagModule<any>;
+  let ls: ReturnType<typeof installLocalStorage>;
+
+  beforeEach(() => {
+    ls = installLocalStorage();
+    env = makeDeps();
+    mod = new FeatureFlagModule(env.deps);
+  });
+
+  afterEach(() => ls.uninstall());
+
+  it('wins over the server assignment', async () => {
+    const flag = mod.feature('alpha', { fallback: 'off' });
+    await tick();
+    env.push([{ key: 'alpha', variant: 'off' }]);
+    expect(flag.enabled()).toBe(false);
+
+    mod.setLocalOverride('alpha', 'on');
+    expect(flag.variant()).toBe('on');
+    expect(flag.enabled()).toBe(true);
+  });
+
+  it('survives a later live result for the same key', async () => {
+    const flag = mod.feature('alpha', { fallback: 'off' });
+    await tick();
+    mod.setLocalOverride('alpha', 'on');
+
+    env.push([{ key: 'alpha', variant: 'off' }]); // server disagrees
+    expect(flag.variant()).toBe('on');
+  });
+
+  it('applies before the first result, without a fallback flash', () => {
+    mod.setLocalOverride('alpha', 'on');
+    const flag = mod.feature('alpha', { fallback: 'off' });
+    expect(flag.variant()).toBe('on'); // seeded even though nothing loaded yet
+  });
+
+  it('carries its own payload', async () => {
+    const flag = mod.feature('alpha', { fallback: 'off' });
+    await tick();
+    env.push([{ key: 'alpha', variant: 'off', payload: { copy: 'server' } }]);
+
+    mod.setLocalOverride('alpha', 'on', { copy: 'local' });
+    expect(flag.payload()).toEqual({ copy: 'local' });
+  });
+
+  it('notifies subscribers when set and cleared', async () => {
+    const flag = mod.feature('alpha', { fallback: 'off' });
+    await tick();
+    env.push([{ key: 'alpha', variant: 'off' }]);
+
+    const seen: (string | undefined)[] = [];
+    flag.subscribe((s) => seen.push(s.variant));
+    expect(seen).toEqual(['off']); // immediate call
+
+    mod.setLocalOverride('alpha', 'on');
+    mod.setLocalOverride('alpha', null);
+    expect(seen).toEqual(['off', 'on', 'off']);
+  });
+
+  it('restores the server assignment when cleared', async () => {
+    const flag = mod.feature('alpha', { fallback: 'off' });
+    await tick();
+    env.push([{ key: 'alpha', variant: 'treatment', payload: { copy: 'server' } }]);
+
+    mod.setLocalOverride('alpha', 'off');
+    expect(flag.variant()).toBe('off');
+
+    mod.clearLocalOverrides();
+    expect(flag.variant()).toBe('treatment');
+    expect(flag.payload()).toEqual({ copy: 'server' });
+  });
+
+  it('survives a user change — it is a browser setting, not a session one', async () => {
+    mod.init();
+    const flag = mod.feature('alpha', { fallback: 'off' });
+    await tick();
+    mod.setLocalOverride('alpha', 'on');
+
+    env.setUser('user:other');
+    await tick();
+    expect(flag.variant()).toBe('on');
+  });
+
+  it('persists to localStorage and reloads into a fresh module', () => {
+    mod.setLocalOverride('alpha', 'on', { copy: 'local' });
+    expect(mod.getLocalOverrides()).toEqual({ alpha: { variant: 'on', payload: { copy: 'local' } } });
+
+    // A new module reads the same page-origin store, as after a reload.
+    const reloaded = new FeatureFlagModule(makeDeps().deps);
+    expect(reloaded.getLocalOverrides()).toEqual({
+      alpha: { variant: 'on', payload: { copy: 'local' } },
+    });
+    expect(reloaded.feature('alpha', { fallback: 'off' }).variant()).toBe('on');
+  });
+
+  it('drops the storage key entirely once the last override is cleared', () => {
+    mod.setLocalOverride('alpha', 'on');
+    expect(ls.store.size).toBe(1);
+
+    mod.setLocalOverride('alpha', null);
+    expect(ls.store.size).toBe(0);
+    expect(new FeatureFlagModule(makeDeps().deps).getLocalOverrides()).toEqual({});
+  });
+
+  it('ignores a corrupt store rather than failing to construct', () => {
+    ls.store.set('sp00ky:feature-overrides', '{not json');
+    expect(() => new FeatureFlagModule(makeDeps().deps)).not.toThrow();
+  });
+});

package/src/modules/feature-flag/index.ts

@@ -13,6 +13,12 @@ import type { QueryTimeToLive } from '../../types';
 // fallback. Avoids one-registration-per-flag and the param-filtered live query.
 const FEATURE_QUERY = 'SELECT key, variant, payload FROM _00_user_feature';
 
+// Local overrides live on the PAGE origin, so they survive reloads and are
+// shared across tabs of the app. Deliberately not the DevTools panel's own
+// storage — the panel runs on a different origin and would get a separate
+// bucket.
+const OVERRIDE_STORAGE_KEY = 'sp00ky:feature-overrides';
+
 interface FeatureRow {
   key?: string;
   variant?: string;
@@ -29,6 +35,16 @@ export interface FeatureFlagOptions {
   ttl?: QueryTimeToLive;
 }
 
+/**
+ * A locally forced variant. Applies to THIS browser only and is never sent to
+ * the server — the assignment in `_00_user_feature` is untouched, so clearing
+ * the override restores whatever the server says.
+ */
+export interface FeatureFlagOverride {
+  variant: string;
+  payload?: unknown;
+}
+
 export class FeatureFlagHandle {
   private latest: FeatureFlagSnapshot = { variant: undefined, payload: undefined };
   private listeners = new Set<(s: FeatureFlagSnapshot) => void>();
@@ -114,9 +130,15 @@ export class FeatureFlagModule<S extends SchemaStructure> {
   // back). `snapshots` only holds ASSIGNED keys; an absent key → fallback.
   private snapshots = new Map<string, FeatureFlagSnapshot>();
   private loaded = false;
+  // Developer-forced variants, this browser only. Take precedence over the
+  // server assignment for every read path.
+  private overrides = new Map<string, FeatureFlagOverride>();
 
   constructor(private deps: FeatureFlagModuleDeps<S>) {
     this.logger = deps.logger.child({ service: 'FeatureFlagModule' });
+    // Loaded in the constructor rather than `init()` so an override applies
+    // even when `client.feature()` is called before auth resolves.
+    this.loadOverrides();
   }
 
   init(): void {
@@ -135,8 +157,10 @@ export class FeatureFlagModule<S extends SchemaStructure> {
     if (options.ttl) this.ttl = options.ttl;
     // If the shared query already resolved, seed this handle immediately so a
     // late `feature()` call doesn't flash the fallback for an assigned key.
-    if (this.loaded) {
-      handle.set(this.snapshots.get(key) ?? { variant: undefined, payload: undefined });
+    // An override seeds it too, even before the first result: forcing a
+    // variant should take effect instantly, not one round trip later.
+    if (this.loaded || this.overrides.has(key)) {
+      handle.set(this.resolve(key));
     }
     void this.ensureStarted();
     return handle;
@@ -155,8 +179,10 @@ export class FeatureFlagModule<S extends SchemaStructure> {
     this.loaded = false;
     this.snapshots.clear();
     // Clear handles immediately so a sign-out hides flag-gated UI without lag.
+    // `resolve` keeps any local override in place across the switch — it is a
+    // developer setting for this browser, not part of the session.
     for (const handle of this.handles) {
-      handle.set({ variant: undefined, payload: undefined });
+      handle.set(this.resolve(handle.key));
     }
     await this.ensureStarted();
   }
@@ -202,8 +228,81 @@ export class FeatureFlagModule<S extends SchemaStructure> {
       }
     }
     this.loaded = true;
-    for (const handle of this.handles) {
-      handle.set(this.snapshots.get(handle.key) ?? { variant: undefined, payload: undefined });
+    this.pushAll();
+  }
+
+  // ===========================================================
+  // Local overrides (this browser only)
+  // ===========================================================
+
+  /**
+   * Force `key` to `variant` in THIS browser. Pass `null` to clear.
+   *
+   * Nothing is written to the server: the `_00_user_feature` assignment is
+   * untouched, so clearing restores whatever the server says. Persisted to
+   * localStorage on the page origin, so it survives a reload.
+   */
+  setLocalOverride(key: string, variant: string | null, payload?: unknown): void {
+    if (variant === null) this.overrides.delete(key);
+    else this.overrides.set(key, { variant, payload });
+    this.persistOverrides();
+    this.pushAll();
+  }
+
+  clearLocalOverrides(): void {
+    this.overrides.clear();
+    this.persistOverrides();
+    this.pushAll();
+  }
+
+  getLocalOverrides(): Record<string, FeatureFlagOverride> {
+    return Object.fromEntries(this.overrides);
+  }
+
+  /** The assignment for `key`, with any local override taking precedence. */
+  private resolve(key: string): FeatureFlagSnapshot {
+    const override = this.overrides.get(key);
+    if (override) return { variant: override.variant, payload: override.payload };
+    return this.snapshots.get(key) ?? { variant: undefined, payload: undefined };
+  }
+
+  private pushAll(): void {
+    for (const handle of this.handles) handle.set(this.resolve(handle.key));
+  }
+
+  private loadOverrides(): void {
+    try {
+      const raw = globalThis.localStorage?.getItem(OVERRIDE_STORAGE_KEY);
+      if (!raw) return;
+      const parsed = JSON.parse(raw) as Record<string, FeatureFlagOverride>;
+      for (const [key, value] of Object.entries(parsed ?? {})) {
+        if (value && typeof value.variant === 'string') this.overrides.set(key, value);
+      }
+    } catch (err) {
+      // Best-effort: a corrupt or unavailable store must never stop the
+      // client from booting. Same posture as the DevTools prefs helper.
+      this.logger.warn(
+        { err, Category: 'sp00ky-client::FeatureFlagModule::loadOverrides' },
+        'Failed to read local feature flag overrides',
+      );
+    }
+  }
+
+  private persistOverrides(): void {
+    try {
+      if (this.overrides.size === 0) {
+        globalThis.localStorage?.removeItem(OVERRIDE_STORAGE_KEY);
+        return;
+      }
+      globalThis.localStorage?.setItem(
+        OVERRIDE_STORAGE_KEY,
+        JSON.stringify(this.getLocalOverrides()),
+      );
+    } catch (err) {
+      this.logger.warn(
+        { err, Category: 'sp00ky-client::FeatureFlagModule::persistOverrides' },
+        'Failed to persist local feature flag overrides',
+      );
     }
   }
 }

package/src/sp00ky.ts

@@ -47,7 +47,7 @@ import type { RecordWithId } from './modules/cache/index';
 import { CrdtManager, CrdtField } from './modules/crdt/index';
 import { preloadLoro } from './modules/crdt/loro-loader';
 import { FeatureFlagModule, FeatureFlagHandle } from './modules/feature-flag/index';
-import type { FeatureFlagOptions } from './modules/feature-flag/index';
+import type { FeatureFlagOptions, FeatureFlagOverride } from './modules/feature-flag/index';
 import { AppReleaseModule, AppReleaseHandle } from './modules/app-release/index';
 import type { AppReleaseOptions } from './modules/app-release/index';
 import { LocalStoragePersistenceClient } from './services/persistence/localstorage';
@@ -465,6 +465,11 @@ export class Sp00kyClient<S extends SchemaStructure> {
       this.dataModule
     );
 
+    // Let the DevTools Flags tab read and write local flag overrides. Done
+    // here rather than via the constructor because FeatureFlagModule is built
+    // above and DevToolsService takes its deps positionally.
+    this.devTools.setFeatureFlagOverrides(this.featureFlags);
+
     // Register DevTools as a receiver for stream updates
     this.streamProcessor.addReceiver(this.devTools);
 
@@ -1054,6 +1059,31 @@ export class Sp00kyClient<S extends SchemaStructure> {
     return this.featureFlags.feature(key, options);
   }
 
+  /**
+   * Force a feature flag to `variant` in THIS browser only; `null` clears it.
+   *
+   * Nothing is sent to the server — the `_00_user_feature` assignment is
+   * untouched, so clearing restores whatever the server says. Persisted to
+   * localStorage, survives reloads, and applies while signed out. Backs the
+   * DevTools Flags tab, and is a convenient hook for tests.
+   *
+   * To change a flag for OTHER users you need admin rights (`spky admin add`)
+   * and the DevTools Flags tab, or `spky flag`.
+   */
+  setFeatureOverride(key: string, variant: string | null, payload?: unknown): void {
+    this.featureFlags.setLocalOverride(key, variant, payload);
+  }
+
+  /** Drop every local feature flag override set via `setFeatureOverride`. */
+  clearFeatureOverrides(): void {
+    this.featureFlags.clearLocalOverrides();
+  }
+
+  /** The local feature flag overrides currently in effect, keyed by flag. */
+  getFeatureOverrides(): Record<string, FeatureFlagOverride> {
+    return this.featureFlags.getLocalOverrides();
+  }
+
   /**
    * Observe the announced release of an app (`_00_app_release:<app>`, written
    * by `spky deploy` / `spky release`). The handle's `snapshot()` carries the