svelte-realtime 0.5.10 → 0.6.0-next.2

package/README.md

@@ -2339,6 +2339,49 @@ Without a leader configured (the default), every worker fires every job. svelte-
 
 ---
 
+## Feature flags
+
+Use `live.flag()` to declare a server-controlled value that every client reads as a readable store. A flag is a thin wrapper over `live.stream`: it declares a `merge: 'set'` topic carrying the value, and `.set(value)` pushes a new value to every subscriber.
+
+```js
+// src/live/flags.js
+import { live } from 'svelte-realtime/server';
+
+export const maintenance = live.flag('flag:maintenance', false);
+```
+
+Flip it from any handler - the `.set(value)` call publishes through the framework-owned platform, so the new value reaches every local subscriber and relays across the cluster when a bus is wired:
+
+```js
+export const toggleMaintenance = live(async (ctx, on) => {
+  maintenance.set(on);
+});
+```
+
+On the client, the flag is a readable store carrying the current value:
+
+```svelte
+<script>
+  import { maintenance } from '$live/flags';
+</script>
+
+{#if $maintenance}
+  <Banner>Down for maintenance</Banner>
+{/if}
+```
+
+`.set(value)` requires that the platform has been captured (`realtime().init`, `setCronPlatform`, or `_activateDerived` from your `hooks.ws.js` `init({ platform })` hook) - the same wiring cron and the top-level `publish()` helper need. Read the current value on the server with `.get()`.
+
+Flags are cluster-consistent by default. A single-entry shared replay buffer is enabled automatically, so a `.set()` on any replica writes the cluster-shared buffer, and a client that connects fresh - to any replica, including one that never set the flag locally - is served the cluster-latest value on connect. Already-subscribed clients stay in sync wherever they connected, because `.set()` relays the update across the cluster. Pass a custom `replay` object (for example `{ replay: { size: 5 } }`) to size the buffer, or `{ replay: false }` to opt out - a single-process app loses nothing by opting out, since the locally cached value is authoritative in one process.
+
+On every running replica an internal watcher keeps the cached value behind `.get()` fresh from boot. The watcher is installed when the registry module loads - the same moment `live.effect` watchers become active - so it does not wait for the flag module's first local import or subscribe: an inbound `set` relayed from any replica updates the cached value within a tick, and synchronous `.get()` reflects the cluster-latest value on any running instance. For a strict read on a replica that booted after the last `set` and has not yet received any inbound `set` - reading a flag the moment a replica comes up, before it has observed any traffic - use the asynchronous `getLatest()`, which reads the shared buffer directly:
+
+```js
+const on = await maintenance.getLatest();
+```
+
+---
+
 ## Derived streams
 
 Server-side computed streams that recompute when any source topic publishes.
@@ -3048,7 +3091,7 @@ With adapter 0.4.0+, the replay end marker sends `{ reqId }` (replay complete) o
 
 Once `platform.replay` is exposed (the standard install pattern is `platform.replay = createReplay(redisClient)` in your hooks), the framework auto-routes every publish to a replay-eligible topic through `platform.replay.publish` regardless of which seam the publisher sits on. `live.stream(topic, loader, { replay: true })` registers the topic at declaration time; static topics are registered up-front and dynamic topics are registered at first-subscribe time when they resolve.
 
-This applies to every framework publish surface — `ctx.publish` from RPC handlers, cron auto-publish (`live.cron('* * * * * *', topic, async (ctx) => result)` where `result !== undefined`), and `ctx.publish` from inside cron handlers — without the user wiring anything beyond `replay: true`. Pre-fix, the user was responsible for wrapping the platform with a `wrapWithReplay` proxy at every seam (the docs showed it on `createMessage` only; cron was a separate `setCronPlatform(platform)` capture, and cron-published events silently bypassed the buffer because the wrap was missing there). The auto-routing makes that asymmetry impossible by construction.
+This applies to every framework publish surface - `ctx.publish` from RPC handlers, cron auto-publish (`live.cron('* * * * * *', topic, async (ctx) => result)` where `result !== undefined`), and `ctx.publish` from inside cron handlers - without the user wiring anything beyond `replay: true`. Pre-fix, the user was responsible for wrapping the platform with a `wrapWithReplay` proxy at every seam (the docs showed it on `createMessage` only; cron was a separate `setCronPlatform(platform)` capture, and cron-published events silently bypassed the buffer because the wrap was missing there). The auto-routing makes that asymmetry impossible by construction.
 
 If you need to keep your own platform-wrapping proxy (custom topic patterns, additional intercepts), set `[WRAPPED_FOR_REPLAY] = true` on the proxy:
 
@@ -3062,7 +3105,7 @@ function wrapWithReplay(p) {
 }
 ```
 
-The framework defers entirely when this marker is present (no double-write to Redis). Without the marker, the framework's auto-routing runs alongside the user proxy's routing and will issue duplicate Redis writes — explicit opt-out is required.
+The framework defers entirely when this marker is present (no double-write to Redis). Without the marker, the framework's auto-routing runs alongside the user proxy's routing and will issue duplicate Redis writes - explicit opt-out is required.
 
 If `replay: true` is declared but `platform.replay` is never set, dev-mode logs a one-time `console.warn` per topic on the first publish, with the install pointer for the replay extension. Production runs silently (no per-publish overhead) and the local broadcast still happens.
 
@@ -3401,6 +3444,8 @@ live.publishRateWarning(false);
 
 Production builds constant-fold the activation branch to dead code - zero overhead. The sampler runs once per platform on the first ctx-helpers cache miss; per-publish cost is unchanged. Topics already in `_topicCoalesce` or `_topicVolatile` are skipped (the user has already addressed them).
 
+The client emits the same hint from the receiving side: in development it measures each stream's inbound frame rate and logs one warning per topic when it crosses the threshold, suggesting `coalesceBy` / `volatile` and linking the same guide. Streams declared with `coalesceBy` are suppressed; silence it everywhere with `configure({ publishRateHint: false })`. Production builds strip the client hint entirely (`import.meta.env`-gated), leaving zero residue on the inbound dispatch path.
+
 ### Dev-mode silent-topic warning
 
 In development, the framework arms a one-shot timer when a stream first subscribes to a topic. If no events arrive within `thresholdMs` (default `30000`), it logs a warning naming the topic and the common causes:
@@ -3677,6 +3722,7 @@ Import from `svelte-realtime/server`.
 | `live.upload(fn, options?)` | Streaming upload handler (chunked, abortable async-iterable; `maxSize` 100MB, `maxConcurrentPerSession` 4, `maxBufferedChunks` 64) |
 | `live.validated(schema, fn)` | RPC with [Standard Schema](https://standardschema.dev/) input validation (Zod, ArkType, Valibot, etc.) |
 | `live.cron(schedule, topic, fn)` | Server-side scheduled function |
+| `live.flag(topic, initialValue?, options?)` | Feature flag exposed as a readable stream with a server-side `.set(value)` |
 | `live.derived(sources, fn, options?)` | Server-side computed stream (static or dynamic sources) |
 | `live.effect(sources, fn, options?)` | Server-side reactive side effect |
 | `live.aggregate(source, reducers, options)` | Real-time incremental aggregation |

package/client.d.ts

@@ -583,6 +583,15 @@ export function configure(config: {
 	 * @default 4_194_304 (4 MB)
 	 */
 	volatileBackpressureBytes?: number;
+	/**
+	 * Enable the dev-mode publish-rate hint: a one-shot console warning logged
+	 * when an inbound stream's frame rate crosses the high-frequency threshold,
+	 * suggesting `coalesceBy` / `volatile`. Set `false` to silence it.
+	 * Production builds strip the hint entirely, so this flag only has an effect
+	 * in development.
+	 * @default true
+	 */
+	publishRateHint?: boolean;
 	/** Offline mutation queue configuration. */
 	offline?: {
 		/** Enable queuing RPCs when disconnected. */

package/client.js

@@ -121,6 +121,32 @@ const _dedupMap = new Map();
  */
 const _dedupCoalesceWarned = new Set();
 
+// - Dev-mode publish-rate hint (client half) -------------------------------
+// Mirrors the server-side sampler in `svelte-realtime/server.js`, but the
+// signal source differs. The server reads `platform.pressure.topPublishers`
+// (rates the adapter already computes); the client has no such snapshot, so
+// it measures inbound frame rate directly at the dispatch hook. A per-topic
+// fixed window counts frames; when a window closes over threshold, one warn
+// fires per topic per session with the SAME wording, threshold (200), and
+// `svti.me/highfreq` link as the server. The whole feature is gated by the
+// `import.meta.env`-folded `_IS_DEV` const so a production build strips it to
+// dead code, leaving zero residue on the inbound dispatch hot path.
+
+/** Inbound events/sec at which a topic is considered high-frequency. Matches the server sampler default. */
+const _PUBLISH_RATE_HINT_THRESHOLD = 200;
+
+/** Measurement window for the client frame-rate counter, in ms. Rate = frames-in-window / window-seconds. */
+const _PUBLISH_RATE_HINT_WINDOW_MS = 1000;
+
+/** Max distinct topics tracked in the warned dedup set. FIFO-evict on cap: dropping the oldest entry just lets that topic re-warn on its next over-threshold window. Mirrors the server `PUBLISH_RATE_WARN_DEDUP_MAX` eviction shape. */
+const _PUBLISH_RATE_HINT_DEDUP_MAX = 1_000_000;
+
+/** @type {Map<string, { start: number, count: number }>} Per-topic fixed-window frame counter. */
+const _publishRateWindows = new Map();
+
+/** @type {Set<string>} One-shot warned topics. FIFO-evicted at the dedup cap. */
+const _publishRateHintWarned = new Set();
+
 /**
  * Dev-mode check, mirrored from the `process.env.NODE_ENV` pattern
  * used elsewhere in this file. Cached once at first call so the hot
@@ -227,13 +253,37 @@ const _healthStore = writable(/** @type {'healthy' | 'degraded'} */ ('healthy'))
 /** @type {(() => void) | null} */
 let _healthUnsub = null;
 
+// Two independent inputs OR into the single health state: a server-pushed
+// degraded/recovered event on the system topic, and the connection's local
+// internal flow-control pressure (a queued/refused flow-controlled send).
+// Tracked separately so neither input clobbers the other - health is degraded
+// while EITHER is degraded, healthy only when BOTH are clear.
+let _healthServerDegraded = false;
+let _healthFlowDegraded = false;
+
+function _recomputeHealth() {
+	_healthStore.set(_healthServerDegraded || _healthFlowDegraded ? 'degraded' : 'healthy');
+}
+
 function _ensureHealthSubscription() {
 	if (_healthUnsub) return;
-	_healthUnsub = on(_HEALTH_TOPIC).subscribe((envelope) => {
+	const offTopic = on(_HEALTH_TOPIC).subscribe((envelope) => {
 		if (!envelope) return;
-		if (envelope.event === 'degraded') _healthStore.set('degraded');
-		else if (envelope.event === 'recovered') _healthStore.set('healthy');
+		if (envelope.event === 'degraded') { _healthServerDegraded = true; _recomputeHealth(); }
+		else if (envelope.event === 'recovered') { _healthServerDegraded = false; _recomputeHealth(); }
 	});
+	// Fold the connection's internal flow-control health in as a second,
+	// OR-ed input. A boolean is the only thing that crosses this accessor;
+	// no internal accounting value surfaces. Older adapter connections that
+	// predate the accessor simply do not contribute this input.
+	let offFlow = () => {};
+	try {
+		const conn = _connect();
+		if (conn && typeof conn._onLeaseDegraded === 'function') {
+			offFlow = conn._onLeaseDegraded((d) => { _healthFlowDegraded = !!d; _recomputeHealth(); });
+		}
+	} catch { /* connection not configured yet; flow health stays clear */ }
+	_healthUnsub = () => { offTopic(); offFlow(); };
 }
 
 /**
@@ -271,9 +321,18 @@ export function _resetHealth() {
 		_healthUnsub();
 		_healthUnsub = null;
 	}
+	_healthServerDegraded = false;
+	_healthFlowDegraded = false;
 	_healthStore.set('healthy');
 }
 
+// Flow control is owned end to end by the adapter connection's send gate: it
+// advertises the capability, paces its own flow-controlled sends against the
+// server's window, and reports a single degraded boolean. The realtime layer
+// consumes that boolean through conn._onLeaseDegraded in
+// _ensureHealthSubscription above and ORs it into realtime.health. There is no
+// realtime-owned mirror of the gate - a second copy would only drift.
+
 function _registerTopicErrorSetter(topic, setError) {
 	let set = _streamErrorByTopic.get(topic);
 	if (!set) { set = new Set(); _streamErrorByTopic.set(topic, set); }
@@ -494,6 +553,85 @@ function _warnCoalesceOnce(path) {
 	);
 }
 
+/**
+ * Count one inbound frame for a topic and, if its measured rate crosses the
+ * high-frequency threshold, emit a one-shot dev hint. Counterpart to the
+ * server-side sampler: same threshold (200), same `coalesceBy` / `volatile`
+ * suggestions, same `svti.me/highfreq` link. The server reads rates the
+ * adapter pre-computes; the client has none, so it counts frames over a fixed
+ * window and derives the rate locally.
+ *
+ * Suppressed when the stream was declared with `coalesceBy` - that is the user
+ * already choosing the latest-value-wins mitigation, so the hint would be
+ * noise. (There is no client-side `volatile` declaration to read; `volatile`
+ * is a per-call RPC concern, not a stream option, so only `coalesceBy`
+ * suppresses here.) Opt out entirely with `configure({ publishRateHint: false })`.
+ *
+ * The whole function is dead code in production: the only caller is gated by
+ * the `import.meta.env`-folded `_IS_DEV` const, and this body re-checks it so a
+ * direct call from a test still no-ops under a production build.
+ *
+ * @param {string} topic - the stream path (the identity available at dispatch)
+ * @param {any} options - the per-stream options object (read for `coalesceBy`)
+ */
+function _maybeHintPublishRate(topic, options) {
+	if (!_IS_DEV) return;
+	if (_clientConfig.publishRateHint === false) return;
+	if (_publishRateHintWarned.has(topic)) return;
+	// A declared-coalesced stream already picked latest-value-wins, so the hint
+	// would be noise: skip the counting work entirely, mirroring the server which
+	// marks such topics handled up front.
+	if (options && options.coalesceBy) return;
+
+	const now = Date.now();
+	let win = _publishRateWindows.get(topic);
+	if (win === undefined) {
+		_publishRateWindows.set(topic, { start: now, count: 1 });
+		return;
+	}
+	win.count++;
+	const elapsed = now - win.start;
+	if (elapsed < _PUBLISH_RATE_HINT_WINDOW_MS) return;
+
+	// Window closed: derive events/sec and reset for the next window. A short
+	// final window (e.g. the stream unsubscribed mid-window) still scales to a
+	// per-second rate, so a genuine burst is not under-counted.
+	const rate = (win.count * 1000) / elapsed;
+	win.start = now;
+	win.count = 0;
+
+	if (rate < _PUBLISH_RATE_HINT_THRESHOLD) return;
+
+	if (_publishRateHintWarned.size >= _PUBLISH_RATE_HINT_DEDUP_MAX) {
+		const oldest = _publishRateHintWarned.values().next().value;
+		if (oldest !== undefined) _publishRateHintWarned.delete(oldest);
+	}
+	_publishRateHintWarned.add(topic);
+	// The window counter is never re-read once a topic has warned (the warned
+	// set short-circuits at the top), so drop it to keep the window map bounded
+	// by live unwarned topics, mirroring the server sampler's symmetry.
+	_publishRateWindows.delete(topic);
+	console.warn(
+		`[svelte-realtime] Topic '${topic}' is receiving ` +
+		`${Math.round(rate)} events/sec.\n` +
+		`  For high-frequency streams, consider one of:\n` +
+		`    live.stream(topic, loader, { coalesceBy: (data) => data.userId })  // latest-value-wins, queued per subscriber\n` +
+		`    live.stream(topic, loader, { volatile: true })                     // drop on backpressure, best-effort\n` +
+		`  See: https://svti.me/highfreq`
+	);
+}
+
+/**
+ * Reset the dev-mode client publish-rate hint state. Tests only. Clears the
+ * one-shot warned set and the per-topic window counters so a previously seen
+ * topic can warn again.
+ * @internal
+ */
+export function _resetClientPublishRateWarning() {
+	_publishRateHintWarned.clear();
+	_publishRateWindows.clear();
+}
+
 /**
  * Build a dedup key from path and args, avoiding JSON.stringify for common cases.
  * @param {string} path
@@ -2424,6 +2562,7 @@ function _createStream(path, options, dynamicArgs, initialSchemaVersion) {
 		}
 
 		_devtoolsStreamEvent(path, envelope.event, envelope.data);
+		if (_IS_DEV) _maybeHintPublishRate(path, options);
 
 		if (_useRAF) {
 			_activeBuf.push(envelope);
@@ -3530,7 +3669,7 @@ function _checkArgs(path, args) {
  * @typedef {{ path: string, args: any[], queuedAt: number, resolve: Function, reject: Function, idempotencyKey?: string, timeout?: number }} OfflineEntry
  */
 
-/** @type {{ url?: string, auth?: boolean | string, onConnect?: () => void, onDisconnect?: () => void, timeout?: number, resumeGraceMs?: number, volatileBackpressureBytes?: number, upload?: { frameSize?: number, chunkSize?: number, highWaterMark?: number, lowWaterMark?: number }, offline?: { queue?: boolean, maxQueue?: number, maxAge?: number, replay?: 'sequential' | 'batch' | ((queue: OfflineEntry[]) => OfflineEntry[]), beforeReplay?: (call: { path: string, args: any[], queuedAt: number }) => boolean, onReplayError?: (call: { path: string, args: any[], queuedAt: number }, error: any) => void } }} */
+/** @type {{ url?: string, auth?: boolean | string, onConnect?: () => void, onDisconnect?: () => void, timeout?: number, resumeGraceMs?: number, volatileBackpressureBytes?: number, publishRateHint?: boolean, upload?: { frameSize?: number, chunkSize?: number, highWaterMark?: number, lowWaterMark?: number }, offline?: { queue?: boolean, maxQueue?: number, maxAge?: number, replay?: 'sequential' | 'batch' | ((queue: OfflineEntry[]) => OfflineEntry[]), beforeReplay?: (call: { path: string, args: any[], queuedAt: number }) => boolean, onReplayError?: (call: { path: string, args: any[], queuedAt: number }, error: any) => void } }} */
 let _clientConfig = {};
 
 /** @type {boolean} */
@@ -3561,7 +3700,12 @@ let _replayingQueue = false;
  * volatile traffic, lower it on mobile-constrained targets where the OS
  * send buffer is tighter.
  *
- * @param {{ url?: string, auth?: boolean | string, onConnect?: () => void, onDisconnect?: () => void, timeout?: number, resumeGraceMs?: number, volatileBackpressureBytes?: number, offline?: { queue?: boolean, maxQueue?: number, maxAge?: number, replay?: 'sequential' | 'batch' | ((queue: OfflineEntry[]) => OfflineEntry[]), beforeReplay?: (call: { path: string, args: any[], queuedAt: number }) => boolean, onReplayError?: (call: { path: string, args: any[], queuedAt: number }, error: any) => void } }} config
+ * `publishRateHint` (default enabled in dev) controls the one-shot console
+ * hint logged when an inbound stream's frame rate crosses the high-frequency
+ * threshold. Set `false` to silence it. Production builds strip the hint
+ * regardless, so this only matters in development.
+ *
+ * @param {{ url?: string, auth?: boolean | string, onConnect?: () => void, onDisconnect?: () => void, timeout?: number, resumeGraceMs?: number, volatileBackpressureBytes?: number, publishRateHint?: boolean, offline?: { queue?: boolean, maxQueue?: number, maxAge?: number, replay?: 'sequential' | 'batch' | ((queue: OfflineEntry[]) => OfflineEntry[]), beforeReplay?: (call: { path: string, args: any[], queuedAt: number }) => boolean, onReplayError?: (call: { path: string, args: any[], queuedAt: number }, error: any) => void } }} config
  */
 export function configure(config) {
 	_clientConfig = config;

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "svelte-realtime",
-  "version": "0.5.10",
+  "version": "0.6.0-next.2",
   "publishConfig": {
-    "tag": "latest"
+    "tag": "next"
   },
   "description": "Realtime RPC and reactive subscriptions for SvelteKit, built on svelte-adapter-uws",
   "author": "Kevin Radziszewski",

package/server.d.ts

@@ -1659,6 +1659,57 @@ export namespace live {
 		fn: T
 	): T;
 
+	/**
+	 * Declare a server-side feature flag exposed as a readable stream.
+	 *
+	 * A flag is a thin wrapper over `live.stream`: it declares a
+	 * `merge: 'set'` topic carrying the flag value, and any `.set(value)`
+	 * pushes the new value to every subscriber. On the client,
+	 * `$live/<module>` exposes the export as a readable store carrying the
+	 * current value.
+	 *
+	 * Flags are cluster-consistent by default: a single-entry shared replay
+	 * buffer is enabled, so `.set()` writes the cluster-shared buffer and a
+	 * subscriber that connects fresh - to any replica, including one that
+	 * never set the flag locally - is served the cluster-latest value.
+	 * Already-subscribed clients stay in sync across the cluster as `.set()`
+	 * relays the update. Pass a custom `replay` object to size the buffer, or
+	 * `replay: false` to opt out (single-process apps lose nothing, since the
+	 * locally cached value is authoritative in one process).
+	 *
+	 * `.set(value)` publishes through the framework-owned platform (the same
+	 * path as the top-level `publish()` helper), so the new value reaches
+	 * every local subscriber and relays across the cluster when a bus is
+	 * wired. Call it from any server context after the platform has been
+	 * captured. `.get()` reads the current value on the server synchronously;
+	 * an internal watcher - installed when the registry module loads, the same
+	 * lifecycle that activates `live.effect` watchers - keeps it fresh from boot
+	 * within a tick of any inbound `set` on a running replica, without waiting
+	 * for the flag module's first local import. `getLatest()` reads the
+	 * cluster-latest value asynchronously from the shared buffer for the strict
+	 * read on a replica that booted after the last `set` and has not yet
+	 * received any inbound `set`.
+	 *
+	 * @param topic - Topic carrying the flag value
+	 * @param initialValue - Value served to subscribers before the first `.set`
+	 * @param options - Optional `replay` to size the shared buffer, or `replay: false` to opt out
+	 *
+	 * @example
+	 * ```js
+	 * // src/live/flags.js
+	 * export const maintenance = live.flag('flag:maintenance', false);
+	 *
+	 * export const toggleMaintenance = live(async (ctx, on) => {
+	 *   maintenance.set(on);
+	 * });
+	 * ```
+	 */
+	function flag<V = any>(
+		topic: string,
+		initialValue?: V,
+		options?: { replay?: boolean | { size?: number } }
+	): Function & { set(value: V): any; get(): V; getLatest(): Promise<V> };
+
 	/**
 	 * Create a real-time incremental aggregation over a source topic.
 	 *
@@ -2495,6 +2546,15 @@ export function __registerEffect(path: string, fn: Function): void;
  */
 export function __registerAggregate(path: string, fn: Function): void;
 
+/**
+ * Install a flag's refresh watcher eagerly at registry-module load, keyed by
+ * topic, so a server-side `.get()` reflects cluster-latest sets from boot
+ * without waiting for the flag module's first local import. Called by the
+ * Vite-generated registry module.
+ * @internal
+ */
+export function __registerFlag(topic: string, initialValue?: any): void;
+
 /**
  * Register room actions lazily. Called by the Vite-generated registry module.
  * @internal

package/server.js

@@ -3720,6 +3720,139 @@ live.cron = function cron(schedule, topic, fn) {
 	return fn;
 };
 
+/**
+ * Declare a server-side feature flag exposed as a readable stream.
+ *
+ * A flag is a thin wrapper over `live.stream`: it declares a `merge: 'set'`
+ * topic carrying the flag value, and any `.set(value)` pushes the new value
+ * to every subscriber. On the client, `$live/<module>` exposes the export as
+ * a readable store carrying the current value.
+ *
+ * Flags are cluster-consistent by default: a single-entry shared replay
+ * buffer is enabled, so `.set()` writes the cluster-shared buffer and a
+ * subscriber that connects fresh - to any replica, including one that never
+ * set the flag locally - is served the cluster-latest value. Already-
+ * subscribed clients stay in sync across the cluster as `.set()` relays the
+ * update. Pass a custom `replay` object to size the buffer, or
+ * `replay: false` to opt out (single-process apps lose nothing, since the
+ * locally cached value is authoritative in one process).
+ *
+ * On every running replica an internal watcher keeps the cached value fresh
+ * from boot. The watcher is installed when the registry module loads (the
+ * same moment `live.effect` watchers become active), so it does not wait for
+ * the flag module's first local import or subscribe: an inbound `set` relayed
+ * from any replica updates the cached value within a tick, and the synchronous
+ * `.get()` reflects the cluster-latest value on any running instance. For a
+ * strict read on a replica that booted AFTER the last `set` and has not yet
+ * received any inbound `set` (the watcher only catches post-boot sets), use the
+ * asynchronous `getLatest()`, which reads the shared buffer directly.
+ *
+ * The `.set(value)` method publishes through the framework-owned platform
+ * (the same path as the top-level `publish()` helper), so the new value
+ * reaches every local subscriber and relays across the cluster when a bus
+ * is wired. Call it from any server context after the platform has been
+ * captured (RPC handler, cron tick, effect, an admin `+server.js` route).
+ *
+ * @param {string} topic - Topic carrying the flag value
+ * @param {any} [initialValue] - Value served to subscribers before the first `.set`
+ * @param {{ replay?: boolean | { size?: number } }} [options]
+ * @returns {Function & { set(value: any): any, get(): any, getLatest(): Promise<any> }}
+ *
+ * @example
+ * ```js
+ * // src/live/flags.js
+ * import { live } from 'svelte-realtime/server';
+ * export const maintenance = live.flag('flag:maintenance', false);
+ *
+ * // Flip it from any handler:
+ * export const toggleMaintenance = live(async (ctx, on) => {
+ *   maintenance.set(on);
+ * });
+ * ```
+ *
+ * ```svelte
+ * <script>
+ *   import { maintenance } from '$live/flags';
+ * </script>
+ * {#if $maintenance}<Banner />{/if}
+ * ```
+ */
+live.flag = function flag(topic, initialValue, options) {
+	if (typeof topic !== 'string' || topic.length === 0) {
+		throw new Error('[svelte-realtime] live.flag topic must be a non-empty string');
+	}
+	// The flag's value lives in a per-topic cell shared with the eager
+	// registry-load watcher (installed by `__registerFlag`). Binding to the
+	// cell instead of a private closure variable decouples the value from this
+	// module's import: a `set` that arrives before the module is first imported
+	// is captured into the cell by the eager watcher, so the first `.get()`
+	// after import reads the cluster-latest value rather than a stale init.
+	const cell = _flagCell(topic, initialValue);
+	const initFn = async function flagInit() { return cell.value; };
+	// Replay is ON by default with a single-entry buffer so the flag's
+	// topic is replay-eligible at declaration: `.set() -> publish() ->
+	// _maybeReplayPublish` writes the cluster-shared buffer, and a fresh
+	// subscriber (or a just-booted replica) is served the cluster-latest
+	// value through the seeding branch in `_executeStreamRpc`. Pass a
+	// custom `replay` object to override the buffer size, or `replay: false`
+	// to opt out (single-process apps lose nothing - the cached value is
+	// authoritative in one process).
+	const streamOpts = { merge: 'set' };
+	if (options && options.replay === false) {
+		// opt out: leave replay unset
+	} else if (options && options.replay) {
+		/** @type {any} */ (streamOpts).replay = options.replay;
+	} else {
+		/** @type {any} */ (streamOpts).replay = { size: 1 };
+	}
+	const stream = live.stream(topic, initFn, streamOpts);
+	/** @type {any} */ (stream).__isFlag = true;
+	/**
+	 * Read the flag's current value on the server (synchronous). On a running
+	 * replica this stays fresh from boot within a tick of any inbound `set` via
+	 * the per-topic watcher installed eagerly at registry load (see
+	 * `__registerFlag`). For a strict read on a replica that booted after the
+	 * last `set` and has not yet received any inbound `set`, use `getLatest()`.
+	 */
+	/** @type {any} */ (stream).get = function get() { return cell.value; };
+	/**
+	 * Read the cluster-latest flag value (asynchronous). Reads the shared
+	 * replay buffer when one is wired and non-empty; otherwise falls back to
+	 * the locally cached value. Serves the strict read-after-cold-boot
+	 * case where a replica may not yet have observed the cluster-latest set.
+	 */
+	/** @type {any} */ (stream).getLatest = async function getLatest() {
+		// Resolve the captured platform the same way `.set()` does (via the
+		// top-level `publish()` helper), so `getLatest()` reads the shared
+		// buffer whether the platform was captured by `_activateDerived` or
+		// `setCronPlatform`.
+		const platform = getPlatform();
+		const replay = platform && /** @type {any} */ (platform).replay;
+		if (replay && typeof replay.since === 'function') {
+			try {
+				const buffered = await replay.since(topic, 0);
+				if (Array.isArray(buffered) && buffered.length > 0) {
+					const last = buffered[buffered.length - 1];
+					if (last && 'data' in last) return last.data;
+				}
+			} catch {}
+		}
+		return cell.value;
+	};
+	/** Publish a new flag value to every subscriber. */
+	/** @type {any} */ (stream).set = function set(value) {
+		cell.value = value;
+		return publish(topic, 'set', value);
+	};
+	// Ensure the per-topic refresh watcher is installed. This is idempotent
+	// with the eager `__registerFlag` install the registry module emits, and
+	// covers the cases where a flag module is imported without a generated
+	// registry (the dev-mode direct-load fallback, or a flag declared inline
+	// in tests).
+	_installFlagWatcher(topic);
+	return /** @type {any} */ (stream);
+};
+
 /** @type {Map<string, { sources: string[], fn: Function, topic: string, debounce: number, timer: ReturnType<typeof setTimeout> | null }>} */
 const derivedRegistry = new Map();
 
@@ -3860,6 +3993,95 @@ export function __registerEffect(path, fn) {
 	_maybeLateActivate();
 }
 
+/**
+ * Per-topic value cells for `live.flag`. The cell holds the flag's current
+ * value and is shared between the flag export's accessors (`get`/`set`/the
+ * loader) and the eager refresh watcher installed at registry load. Keying on
+ * the topic (rather than the export path) lets the watcher install before the
+ * flag module is imported - the value the watcher captures from inbound sets is
+ * exactly the value the flag's `.get()` reads once the module is imported.
+ * @type {Map<string, { value: any }>}
+ */
+const _flagCells = new Map();
+
+/**
+ * Per-topic refresh watcher entries, so the install is idempotent across the
+ * eager registry call and the flag module's own import.
+ * @type {Map<string, { sources: string[], fn: Function, debounce: number, timer: ReturnType<typeof setTimeout> | null }>}
+ */
+const _flagWatchers = new Map();
+
+/**
+ * Get (or create) the value cell for a flag topic. A cell created by the eager
+ * watcher path may not have a meaningful seed yet; the first caller that knows
+ * the declared `initialValue` (the watcher install or the flag body, whichever
+ * runs first) seeds it. Inbound sets always overwrite the seed.
+ * @param {string} topic
+ * @param {any} [initialValue]
+ * @returns {{ value: any }}
+ */
+function _flagCell(topic, initialValue) {
+	let cell = _flagCells.get(topic);
+	if (!cell) {
+		cell = { value: initialValue };
+		_flagCells.set(topic, cell);
+	} else if (cell.value === undefined && initialValue !== undefined) {
+		// Adopt the declared initial value when the cell was created without
+		// one (e.g. the eager watcher had no static initialValue to pass).
+		cell.value = initialValue;
+	}
+	return cell;
+}
+
+/**
+ * Install the per-topic flag refresh watcher into the effect index. Idempotent:
+ * one watcher per topic, regardless of how many times this is called. The
+ * watcher updates the topic's value cell on every inbound `set`, so a sync
+ * `.get()` reflects the cluster-latest value from boot on every running replica.
+ *
+ * The bus inbound relay reaches `derivedPublishLocal -> fireWatchers(topic,
+ * event, data)`, so a `set` originating on any replica updates the cell here
+ * (the self-set echo on the origin is idempotent). `_maybeLateActivate()`
+ * installs the publish wrap even when the flag is declared before
+ * `_activateDerived`.
+ * @param {string} topic
+ */
+function _installFlagWatcher(topic) {
+	if (_flagWatchers.has(topic)) return;
+	const cell = _flagCell(topic);
+	const watcher = {
+		sources: [topic],
+		fn: function flagWatcher(event, data) { if (event === 'set') cell.value = data; },
+		debounce: 0,
+		timer: null
+	};
+	_flagWatchers.set(topic, watcher);
+	let watcherSet = _effectBySource.get(topic);
+	if (!watcherSet) { watcherSet = new Set(); _effectBySource.set(topic, watcherSet); }
+	watcherSet.add(watcher);
+	_watchedTopics.add(topic);
+	_maybeLateActivate();
+}
+
+/**
+ * Register a flag's refresh watcher eagerly. Called by the Vite-generated
+ * registry module at registry-module load (the same lifecycle that activates
+ * `live.effect` watchers), so the watcher is live from server boot on every
+ * replica WITHOUT waiting for the flag module's first local import or subscribe.
+ *
+ * Carries the static topic and (when statically analyzable) the declared
+ * `initialValue` so the cell is seeded before any inbound `set`. The flag's
+ * `__register` stream entry is emitted alongside this and remains lazy; only the
+ * watcher install is hoisted to boot.
+ * @param {string} topic
+ * @param {any} [initialValue]
+ */
+export function __registerFlag(topic, initialValue) {
+	if (typeof topic !== 'string' || topic.length === 0) return;
+	_flagCell(topic, initialValue);
+	_installFlagWatcher(topic);
+}
+
 /** @type {Map<string, { source: string, reducers: any, topic: string, state: any, snapshot: Function | null, debounce: number, timer: ReturnType<typeof setTimeout> | null }>} */
 const aggregateRegistry = new Map();
 /** @type {Map<string, any>} Topic-keyed lookup for aggregates */
@@ -6140,6 +6362,11 @@ export function _prepareHmr() {
 	_aggregateBySource.clear();
 	_aggregateByTopic.clear();
 	_watchedTopics.clear();
+	// Drop the flag watcher index so `__registerFlag` reinstalls watchers on
+	// the regenerated registry load. The value cells persist across HMR - the
+	// flag's cluster-latest value should not reset when an unrelated module is
+	// edited - and the reinstalled watcher rebinds to the surviving cell.
+	_flagWatchers.clear();
 	_streamsWithUnsubscribe.clear();
 	_hasDynamicDerived = false;
 	_hasLazyReactive = false;
@@ -7002,6 +7229,27 @@ async function _executeStreamRpc(ws, platform, fn, ctx, args, msg, subscribedRef
 		} catch {}
 	}
 
+	// Flag fresh-subscribe seeding (cluster-latest on cold connect). A
+	// fresh subscribe omits `seq`, so the seq-gated block above is skipped
+	// and the loader would otherwise return this replica's locally-cached
+	// value. For a flag backed by shared replay, read the whole buffer
+	// (size:1 => one `set` envelope) and serve it through the same
+	// `replay: true` array response the seq-gated block uses, so a fresh
+	// connect to a replica that never set the flag locally still gets the
+	// cluster-latest value. Gated strictly on `__isFlag` so non-flag replay
+	// streams (crud/latest, whose loaders intentionally hit the DB on a
+	// fresh subscribe) keep loader-only fresh-subscribe behavior. Empty
+	// buffer (no `.set()` anywhere yet) falls through to the loader.
+	if (replayOpts && platform.replay && typeof clientSeq === 'undefined' && /** @type {any} */ (fn).__isFlag) {
+		try {
+			const missed = await platform.replay.since(topic, 0);
+			if (Array.isArray(missed) && missed.length > 0) {
+				const currentSeq = await platform.replay.seq(topic);
+				return { id, ok: true, data: missed, topic, merge: streamOpts.merge, key: streamOpts.key, prepend: streamOpts.prepend, max: streamOpts.max, seq: currentSeq, replay: true };
+			}
+		} catch {}
+	}
+
 	// Seq-delta (user-provided bridge for older-than-buffer reconnects)
 	if (deltaOpts && typeof deltaOpts.fromSeq === 'function' && typeof clientSeq === 'number') {
 		try {

package/vite.js

@@ -21,6 +21,10 @@ const DYNAMIC_CHANNEL_RE = /export\s+const\s+(\w+)\s*=\s*live\.channel\s*\(\s*(?
 const RATE_LIMIT_EXPORT_RE = /export\s+const\s+(\w+)\s*=\s*live\.rateLimit\s*\(/g;
 const EFFECT_EXPORT_RE = /export\s+const\s+(\w+)\s*=\s*live\.effect\s*\(/g;
 const AGGREGATE_EXPORT_RE = /export\s+const\s+(\w+)\s*=\s*live\.aggregate\s*\(/g;
+// `live.flag(topic, initialValue)` declares a `merge: 'set'` stream carrying
+// the flag value, so the client treats it exactly like a static stream: emit
+// a `__stream(..., { merge: 'set' })` stub and register it as a plain stream.
+const FLAG_EXPORT_RE = /export\s+const\s+(\w+)\s*=\s*live\.flag\s*\(/g;
 // `live.lock(...)` and `live.idempotent(...)` wrap an inner handler. From the
 // client's perspective they're plain RPCs (the lock / idempotency runs
 // server-side inside the wrapper), so the codegen treats them identically
@@ -1272,6 +1276,18 @@ function _generateClientStubs(filePath, modulePath, dir) {
 		}
 	}
 
+	// Detect live.flag() exports (readable set-merge stream on the client)
+	FLAG_EXPORT_RE.lastIndex = 0;
+	while ((match = FLAG_EXPORT_RE.exec(source)) !== null) {
+		const name = match[1];
+		if (!/^\w+$/.test(name)) continue;
+		if (!exportedNames.has(name)) {
+			exportedNames.add(name);
+			imports.add('__stream');
+			lines.push(`export const ${name} = __stream(${safeModulePath(name)}, ${JSON.stringify({ merge: 'set' })});`);
+		}
+	}
+
 	// Dev warnings for non-live exports
 	const allExportRe = /export\s+(?:const|function|let|var|class)\s+(\w+)/g;
 	allExportRe.lastIndex = 0;
@@ -1684,6 +1700,65 @@ function _extractStreamOptions(source, name) {
 	return opts;
 }
 
+/**
+ * Extract the static declaration of a `live.flag(topic, initialValue)` export:
+ * the required topic string literal, and the second argument's source text when
+ * it is present. The topic is needed so the registry can install the flag's
+ * refresh watcher eagerly (keyed by topic, before the flag module is imported).
+ * The `initialArg` is the raw source of the second argument and is emitted only
+ * when it is a statically safe literal (a string, number, boolean, or null) so
+ * the value cell can be seeded at registry load; anything else is left for the
+ * flag body to seed on first import. Returns null when the topic is not a plain
+ * string literal (dynamic-topic flags are not supported by the codegen).
+ * @param {string} source
+ * @param {string} name
+ * @returns {{ topic: string, initialArg: string | null } | null}
+ */
+function _extractFlagDecl(source, name) {
+	const openPattern = new RegExp(
+		`export\\s+const\\s+${name}\\s*=\\s*live\\.flag\\s*\\(`
+	);
+	const openMatch = openPattern.exec(source);
+	if (!openMatch) return null;
+	let i = openMatch.index + openMatch[0].length;
+	while (i < source.length && /\s/.test(source[i])) i++;
+	if (source[i] !== '\'' && source[i] !== '"' && source[i] !== '`') return null;
+	const topicLit = _readStringLiteral(source, i);
+	if (!topicLit) return null;
+	const topic = topicLit.value;
+	i = topicLit.end + 1;
+	while (i < source.length && /\s/.test(source[i])) i++;
+	if (source[i] !== ',') return { topic, initialArg: null };
+	i++;
+	while (i < source.length && /\s/.test(source[i])) i++;
+	// Read the second argument up to the next top-level `,` or the closing `)`.
+	let depth = 0;
+	const argStart = i;
+	while (i < source.length) {
+		const skipped = _skipNonCode(source, i);
+		if (skipped >= 0) { i = skipped + 1; continue; }
+		const c = source[i];
+		if (c === '(' || c === '[' || c === '{') depth++;
+		else if (c === ')' || c === ']' || c === '}') { if (depth === 0) break; depth--; }
+		else if (c === ',' && depth === 0) break;
+		i++;
+	}
+	const rawArg = source.slice(argStart, i).trim();
+	if (rawArg === '') return { topic, initialArg: null };
+	// Only forward statically safe literals so the generated registry never
+	// evaluates user expressions. String literals are re-quoted via the parsed
+	// value; primitives pass through verbatim.
+	if (rawArg[0] === '\'' || rawArg[0] === '"' || rawArg[0] === '`') {
+		const lit = _readStringLiteral(rawArg, 0);
+		if (lit && lit.end === rawArg.length - 1) return { topic, initialArg: JSON.stringify(lit.value) };
+		return { topic, initialArg: null };
+	}
+	if (rawArg === 'true' || rawArg === 'false' || rawArg === 'null' || /^-?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i.test(rawArg)) {
+		return { topic, initialArg: rawArg };
+	}
+	return { topic, initialArg: null };
+}
+
 /**
  * Parse option properties from an object body string into an opts object.
  * Shared by stream, channel, and room option extraction.
@@ -1851,7 +1926,7 @@ function _generateRegistry(liveDir, dir, topicsRegistry) {
 
 	const files = _findLiveFiles(liveDir);
 	const lines = [
-		`import { __register, __registerGuard, __registerCron, __registerDerived, __registerEffect, __registerAggregate, __registerRoomActions } from 'svelte-realtime/server';`,
+		`import { __register, __registerGuard, __registerCron, __registerDerived, __registerEffect, __registerAggregate, __registerRoomActions, __registerFlag } from 'svelte-realtime/server';`,
 		`const __L = fn => (fn.__lazy = true, fn);\n`
 	];
 
@@ -2061,6 +2136,27 @@ function _generateRegistry(liveDir, dir, topicsRegistry) {
 			}
 		}
 
+		// Register live.flag() exports. The stream registration stays lazy (the
+		// flag module is imported on first subscribe), but the refresh watcher
+		// is installed eagerly via __registerFlag at registry-module load - the
+		// same lifecycle that activates live.effect watchers - so a server-side
+		// .get() reflects cluster-latest sets from boot without waiting for the
+		// flag module's first local import.
+		FLAG_EXPORT_RE.lastIndex = 0;
+		while ((match = FLAG_EXPORT_RE.exec(source)) !== null) {
+			const name = match[1];
+			if (!/^\w+$/.test(name)) continue;
+			if (!registered.has(name)) {
+				registered.add(name);
+				lines.push(`__register(${JSON.stringify(rel + '/' + name)}, ${_lazy(name)});`);
+				const decl = _extractFlagDecl(source, name);
+				if (decl) {
+					const initArg = decl.initialArg === null ? '' : `, ${decl.initialArg}`;
+					lines.push(`__registerFlag(${JSON.stringify(decl.topic)}${initArg});`);
+				}
+			}
+		}
+
 		// Warn about exports with non-path-safe names (pass registered to avoid
 		// double-warning for names already handled above)
 		_warnUnsafeExports(source, `${dir}/${rel}`, registered);
@@ -2318,6 +2414,17 @@ function _generateTypeDeclarations(liveDir, dir) {
 			}
 		}
 
+		// Detect live.flag() exports (readable set-merge stream)
+		FLAG_EXPORT_RE.lastIndex = 0;
+		while ((match = FLAG_EXPORT_RE.exec(source)) !== null) {
+			const name = match[1];
+			handledNames.add(name);
+			if (!exports.some(e => e.includes(`export const ${name}:`))) {
+				needsStreamStore = true;
+				exports.push(`  export const ${name}: StreamStore<any> & { load(platform: any, options?: { args?: any[]; user?: any }): Promise<any> };`);
+			}
+		}
+
 		// Detect live.binary() exports
 		BINARY_EXPORT_RE.lastIndex = 0;
 		while ((match = BINARY_EXPORT_RE.exec(source)) !== null) {