@spooky-sync/core 0.0.1-canary.81 → 0.0.1-canary.83

package/dist/index.d.ts

@@ -580,6 +580,12 @@ interface Sp00kySyncOptions {
    * {@link resolveListRefPollInterval}.
    */
   refSyncIntervalMs?: number;
+  /**
+   * Enable realtime sync for unauthenticated clients against the shared
+   * `_00_list_ref_anon` table. See {@link Sp00kyConfig.enableAnonymousLiveQueries}.
+   * Defaults to `false`.
+   */
+  anonymousLiveQueries?: boolean;
 }
 /**
  * The main synchronization engine for Sp00ky.
@@ -607,6 +613,7 @@ declare class Sp00kySync<S extends SchemaStructure> {
   events: SyncEventSystem;
   private currentUserId;
   private refMode;
+  private readonly anonLiveEnabled;
   private currentLiveQueryUuid;
   private liveQueryUnsubscribe;
   private listRefPollTimer;

package/dist/index.js

@@ -2551,6 +2551,13 @@ var SyncScheduler = class {
 //#endregion
 //#region src/modules/ref-tables.ts
 /**
+* Sentinel user id for unauthenticated clients when anonymous live queries are
+* enabled. Mirrors `ssp_protocol::ANON_AUTH_ID`. It carries no `user:` prefix
+* so it can never collide with a real user id (those arrive as `user:<id>`);
+* both sides resolve it to the shared `_00_list_ref_anon` table.
+*/
+const ANON_USER_ID = "anon";
+/**
 * Default ref-storage mode for this client build. Mirrors the SSP's
 * default (`RefMode::Dedicated`) so cross-session sync works out of the
 * box.
@@ -2582,6 +2589,7 @@ function sanitizeUserId(userId) {
 * single mode.
 */
 function listRefTableFor(mode, userId) {
+	if (userId === ANON_USER_ID) return "_00_list_ref_anon";
 	if (mode === "single") return "_00_list_ref";
 	const uid = sanitizeUserId(userId);
 	return uid ? `_00_list_ref_user_${uid}` : "_00_list_ref";
@@ -2612,6 +2620,7 @@ var Sp00kySync = class {
 	events = createSyncEventSystem();
 	currentUserId = null;
 	refMode = DEFAULT_REF_MODE;
+	anonLiveEnabled;
 	currentLiveQueryUuid = null;
 	liveQueryUnsubscribe = null;
 	listRefPollTimer = null;
@@ -2650,6 +2659,7 @@ var Sp00kySync = class {
 		this.syncEngine = new SyncEngine(this.remote, this.cache, this.schema, this.logger);
 		this.scheduler = new SyncScheduler(this.upQueue, this.downQueue, this.processUpEvent.bind(this), this.processDownEvent.bind(this), this.logger, this.handleRollback.bind(this));
 		this.refSyncIntervalMs = resolveListRefPollInterval(options?.refSyncIntervalMs);
+		this.anonLiveEnabled = options?.anonymousLiveQueries ?? false;
 	}
 	/**
 	* Initializes the synchronization system.
@@ -2663,6 +2673,15 @@ var Sp00kySync = class {
 		this.subscribeToReconnect();
 		this.scheduler.syncUp();
 		this.scheduler.syncDown();
+		if (this.anonLiveEnabled && !this.currentUserId) {
+			this.startListRefPoll();
+			this.restartRefLiveQuery().catch((err) => {
+				this.logger.debug({
+					err,
+					Category: "sp00ky-client::Sp00kySync::init"
+				}, "Anonymous ref LIVE start failed; relying on periodic poll fallback");
+			});
+		}
 	}
 	/**
 	* Push the authenticated user's record id from the parent client's
@@ -2681,6 +2700,16 @@ var Sp00kySync = class {
 		if (this.currentUserId === userId) return;
 		this.currentUserId = userId;
 		if (!userId) {
+			if (this.anonLiveEnabled) {
+				this.startListRefPoll();
+				await this.restartRefLiveQuery().catch((err) => {
+					this.logger.debug({
+						err,
+						Category: "sp00ky-client::Sp00kySync::setCurrentUserId"
+					}, "Anonymous ref LIVE restart failed; relying on periodic poll fallback");
+				});
+				return;
+			}
 			await this.killRefLiveQuery();
 			this.stopListRefPoll();
 			return;
@@ -2821,7 +2850,9 @@ var Sp00kySync = class {
 	* two points and we need the correct table name immediately.
 	*/
 	listRefTable() {
-		return listRefTableFor(this.refMode, this.dataModule.getCurrentUserId());
+		const userId = this.dataModule.getCurrentUserId();
+		if (userId == null && this.anonLiveEnabled) return listRefTableFor(this.refMode, ANON_USER_ID);
+		return listRefTableFor(this.refMode, userId);
 	}
 	async killRefLiveQuery() {
 		if (this.liveQueryUnsubscribe) {
@@ -2860,7 +2891,7 @@ var Sp00kySync = class {
 				type: "register",
 				payload: { hash }
 			});
-			if (this.currentUserId) this.restartRefLiveQuery().catch((err) => {
+			if (this.currentUserId || this.anonLiveEnabled) this.restartRefLiveQuery().catch((err) => {
 				this.logger.debug({
 					err,
 					Category: "sp00ky-client::Sp00kySync::onReconnect"
@@ -3312,8 +3343,8 @@ function parseBackendInfo(raw) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.81";
-const WASM_VERSION = "0.0.1-canary.81";
+const CORE_VERSION = "0.0.1-canary.83";
+const WASM_VERSION = "0.0.1-canary.83";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class {
 	eventsHistory = [];
@@ -5164,7 +5195,10 @@ var Sp00kyClient = class {
 		this.crdtManager = new CrdtManager(this.config.schema, this.local, this.remote, logger, config.crdtDebounceMs ?? 500);
 		this.dataModule = new DataModule(this.cache, this.local, this.config.schema, logger, this.config.streamDebounceTime);
 		this.auth = new AuthService(this.config.schema, this.remote, this.persistenceClient, logger);
-		this.sync = new Sp00kySync(this.local, this.remote, this.cache, this.dataModule, this.config.schema, this.logger, { refSyncIntervalMs: this.config.refSyncIntervalMs });
+		this.sync = new Sp00kySync(this.local, this.remote, this.cache, this.dataModule, this.config.schema, this.logger, {
+			refSyncIntervalMs: this.config.refSyncIntervalMs,
+			anonymousLiveQueries: this.config.enableAnonymousLiveQueries
+		});
 		this.featureFlags = new FeatureFlagModule({
 			dataModule: this.dataModule,
 			sync: this.sync,

package/dist/types.d.ts

@@ -291,6 +291,16 @@ interface Sp00kyConfig<S extends SchemaStructure> {
    * Defaults to `true`; set `false` to keep the old wait-for-registration path.
    */
   instantHydrate?: boolean;
+  /**
+   * Enable realtime sync while signed out. When `true`, the client starts its
+   * `_00_list_ref` poll (and a LIVE subscription) against the shared
+   * `_00_list_ref_anon` table even with no authenticated user, so a logged-out
+   * page gets live `useQuery` updates over world-readable tables. Requires the
+   * server to be deployed with `anonymousLiveQueries: true` in `sp00ky.yml`
+   * (this flag must match it). Defaults to `false`: anonymous clients can read
+   * one-shot but never sync live.
+   */
+  enableAnonymousLiveQueries?: boolean;
 }
 type QueryHash = string;
 type RecordVersionArray = Array<[string, number]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.81",
+  "version": "0.0.1-canary.83",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -59,8 +59,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.81",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.81",
+    "@spooky-sync/query-builder": "0.0.1-canary.83",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.83",
     "@surrealdb/wasm": "^3.0.3",
     "fast-json-patch": "^3.1.1",
     "loro-crdt": "^1.5.6",

package/src/modules/ref-tables.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import { RecordId } from 'surrealdb';
-import { listRefTableFor, sanitizeUserId } from './ref-tables';
+import { ANON_USER_ID, listRefTableFor, sanitizeUserId } from './ref-tables';
 
 describe('listRefTableFor', () => {
   it('returns global table in single mode regardless of user', () => {
@@ -32,6 +32,16 @@ describe('listRefTableFor', () => {
     );
     expect(listRefTableFor('dedicated', 'user:abc.dot')).toBe('_00_list_ref');
   });
+
+  it('routes the anon sentinel to the shared anon table in both modes', () => {
+    expect(listRefTableFor('dedicated', ANON_USER_ID)).toBe('_00_list_ref_anon');
+    expect(listRefTableFor('single', ANON_USER_ID)).toBe('_00_list_ref_anon');
+    // A real user whose id sanitizes to "anon" still carries the user: prefix,
+    // so it never collides with the bare sentinel.
+    expect(listRefTableFor('dedicated', 'user:anon')).toBe(
+      '_00_list_ref_user_anon'
+    );
+  });
 });
 
 describe('sanitizeUserId', () => {

package/src/modules/ref-tables.ts

@@ -12,6 +12,14 @@
 
 export type RefMode = 'single' | 'dedicated';
 
+/**
+ * Sentinel user id for unauthenticated clients when anonymous live queries are
+ * enabled. Mirrors `ssp_protocol::ANON_AUTH_ID`. It carries no `user:` prefix
+ * so it can never collide with a real user id (those arrive as `user:<id>`);
+ * both sides resolve it to the shared `_00_list_ref_anon` table.
+ */
+export const ANON_USER_ID = 'anon';
+
 /**
  * Default ref-storage mode for this client build. Mirrors the SSP's
  * default (`RefMode::Dedicated`) so cross-session sync works out of the
@@ -51,6 +59,10 @@ export function sanitizeUserId(userId: unknown): string | null {
  * single mode.
  */
 export function listRefTableFor(mode: RefMode, userId: unknown): string {
+  // Anonymous clients (flag-enabled) share one dedicated table in both modes —
+  // checked before the mode split so it never lands on the per-user or the
+  // auth-gated global table. Matches `ssp_protocol::list_ref_table_for`.
+  if (userId === ANON_USER_ID) return '_00_list_ref_anon';
   if (mode === 'single') return '_00_list_ref';
   const uid = sanitizeUserId(userId);
   return uid ? `_00_list_ref_user_${uid}` : '_00_list_ref';

package/src/modules/sync/sync.ts

@@ -21,7 +21,7 @@ import type { SchemaStructure } from '@spooky-sync/query-builder';
 import type { CacheModule } from '../cache/index';
 import type { DataModule } from '../data/index';
 import { encodeRecordId, extractIdPart, extractTablePart, surql } from '../../utils/index';
-import { DEFAULT_REF_MODE, listRefTableFor, RefMode } from '../ref-tables';
+import { ANON_USER_ID, DEFAULT_REF_MODE, listRefTableFor, RefMode } from '../ref-tables';
 
 /**
  * Tunables for `Sp00kySync` construction.
@@ -34,6 +34,12 @@ export interface Sp00kySyncOptions {
    * {@link resolveListRefPollInterval}.
    */
   refSyncIntervalMs?: number;
+  /**
+   * Enable realtime sync for unauthenticated clients against the shared
+   * `_00_list_ref_anon` table. See {@link Sp00kyConfig.enableAnonymousLiveQueries}.
+   * Defaults to `false`.
+   */
+  anonymousLiveQueries?: boolean;
 }
 
 /**
@@ -65,6 +71,11 @@ export class Sp00kySync<S extends SchemaStructure> {
 
   private refMode: RefMode = DEFAULT_REF_MODE;
 
+  // When true, an unauthenticated client still runs the `_00_list_ref` poll
+  // and LIVE subscription, routed to the shared `_00_list_ref_anon` table, so
+  // a logged-out page gets realtime `useQuery` updates. Off by default.
+  private readonly anonLiveEnabled: boolean;
+
   // Bookkeeping for the LIVE subscription on `_00_list_ref[_user_*]`.
   // SurrealDB binds the permission context at LIVE-registration time and
   // the table name in dedicated mode depends on the authenticated user,
@@ -165,6 +176,7 @@ export class Sp00kySync<S extends SchemaStructure> {
       this.handleRollback.bind(this)
     );
     this.refSyncIntervalMs = resolveListRefPollInterval(options?.refSyncIntervalMs);
+    this.anonLiveEnabled = options?.anonymousLiveQueries ?? false;
   }
 
   /**
@@ -183,6 +195,23 @@ export class Sp00kySync<S extends SchemaStructure> {
     // from the auth subscription. In dedicated mode the table name
     // depends on the authenticated user, and an unauthenticated
     // subscription wouldn't match any of the per-user tables anyway.
+    //
+    // Exception: when anonymous live queries are enabled, start realtime now
+    // against the shared `_00_list_ref_anon` table so a logged-out client
+    // syncs immediately. `setCurrentUserId` re-points LIVE to the per-user
+    // table on sign-in. Guard on `currentUserId` because the auth callback can
+    // fire (and authenticate) before `init()` runs — don't clobber that back
+    // to the anon table. `setCurrentUserId(null)` is a no-op on first load
+    // (it's already null), so this is the only place anon realtime starts.
+    if (this.anonLiveEnabled && !this.currentUserId) {
+      this.startListRefPoll();
+      this.restartRefLiveQuery().catch((err) => {
+        this.logger.debug(
+          { err, Category: 'sp00ky-client::Sp00kySync::init' },
+          'Anonymous ref LIVE start failed; relying on periodic poll fallback'
+        );
+      });
+    }
   }
 
   /**
@@ -202,6 +231,20 @@ export class Sp00kySync<S extends SchemaStructure> {
     if (this.currentUserId === userId) return;
     this.currentUserId = userId;
     if (!userId) {
+      if (this.anonLiveEnabled) {
+        // Signed out but anonymous realtime is on: keep the poll running and
+        // re-point LIVE from the (now stale) per-user table to the shared
+        // `_00_list_ref_anon`. `startListRefPoll` is idempotent; the poll
+        // re-resolves `listRefTable()` each tick so it follows automatically.
+        this.startListRefPoll();
+        await this.restartRefLiveQuery().catch((err) => {
+          this.logger.debug(
+            { err, Category: 'sp00ky-client::Sp00kySync::setCurrentUserId' },
+            'Anonymous ref LIVE restart failed; relying on periodic poll fallback'
+          );
+        });
+        return;
+      }
       await this.killRefLiveQuery();
       this.stopListRefPoll();
       return;
@@ -391,7 +434,12 @@ export class Sp00kySync<S extends SchemaStructure> {
    * two points and we need the correct table name immediately.
    */
   public listRefTable(): string {
-    return listRefTableFor(this.refMode, this.dataModule.getCurrentUserId());
+    const userId = this.dataModule.getCurrentUserId();
+    // Unauthenticated with the flag on → the shared `_00_list_ref_anon` table.
+    if (userId == null && this.anonLiveEnabled) {
+      return listRefTableFor(this.refMode, ANON_USER_ID);
+    }
+    return listRefTableFor(this.refMode, userId);
   }
 
   private async killRefLiveQuery(): Promise<void> {
@@ -443,8 +491,9 @@ export class Sp00kySync<S extends SchemaStructure> {
       // re-enqueued `register` events only re-fetch initial state, they don't
       // re-subscribe. Without this, LIVE never recovers after a reconnect and
       // the poll silently becomes the sole sync path (and never backs off).
-      // Only when authenticated: a signed-out reconnect has no per-user table.
-      if (this.currentUserId) {
+      // Authenticated → per-user table; signed-out with anon live enabled →
+      // the shared `_00_list_ref_anon`. Otherwise there's no table to re-bind.
+      if (this.currentUserId || this.anonLiveEnabled) {
         this.restartRefLiveQuery().catch((err) => {
           this.logger.debug(
             { err, Category: 'sp00ky-client::Sp00kySync::onReconnect' },

package/src/sp00ky.ts

@@ -203,7 +203,10 @@ export class Sp00kyClient<S extends SchemaStructure> {
       this.dataModule,
       this.config.schema,
       this.logger,
-      { refSyncIntervalMs: this.config.refSyncIntervalMs }
+      {
+        refSyncIntervalMs: this.config.refSyncIntervalMs,
+        anonymousLiveQueries: this.config.enableAnonymousLiveQueries,
+      }
     );
 
     // Initialize feature flags. Reuses the down-queue to register SSP plans

package/src/types.ts

@@ -143,6 +143,16 @@ export interface Sp00kyConfig<S extends SchemaStructure> {
    * Defaults to `true`; set `false` to keep the old wait-for-registration path.
    */
   instantHydrate?: boolean;
+  /**
+   * Enable realtime sync while signed out. When `true`, the client starts its
+   * `_00_list_ref` poll (and a LIVE subscription) against the shared
+   * `_00_list_ref_anon` table even with no authenticated user, so a logged-out
+   * page gets live `useQuery` updates over world-readable tables. Requires the
+   * server to be deployed with `anonymousLiveQueries: true` in `sp00ky.yml`
+   * (this flag must match it). Defaults to `false`: anonymous clients can read
+   * one-shot but never sync live.
+   */
+  enableAnonymousLiveQueries?: boolean;
 }
 
 export type QueryHash = string;