@spooky-sync/core 0.0.1-canary.21 → 0.0.1-canary.211

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.21",
+  "version": "0.0.1-canary.211",
   "type": "module",
+  "sideEffects": false,
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -17,12 +18,12 @@
   "scripts": {
     "dev": "tsdown --watch",
     "dev:example": "pnpm dev",
-    "build": "tsdown",
+    "build": "tsdown && node scripts/check-broker-bundle.mjs",
     "test": "vitest"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/mono424/spooky.git",
+    "url": "https://github.com/mono424/sp00ky.git",
     "directory": "packages/core"
   },
   "keywords": [
@@ -59,12 +60,15 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "workspace:*",
-    "@spooky-sync/ssp-wasm": "workspace:*",
-    "@surrealdb/wasm": "^3.0.0",
+    "@spooky-sync/query-builder": "0.0.1-canary.211",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.211",
+    "@sqlite.org/sqlite-wasm": "3.53.0-build1",
+    "@surrealdb/wasm": "^3.0.3",
+    "blurhash": "^2.0.5",
     "fast-json-patch": "^3.1.1",
+    "loro-crdt": "^1.5.6",
     "pino": "^10.1.0",
-    "surrealdb": "2.0.0"
+    "surrealdb": "2.0.3"
   },
   "devDependencies": {
     "@types/node": "^22.5.2",

package/scripts/check-broker-bundle.mjs

@@ -0,0 +1,33 @@
+// Build gate: dist/tabs-broker-worker.js must be self-contained ESM.
+// Bundlers cannot trace `new SharedWorker(url)` module graphs, so any
+// import statement surviving into the emitted broker file would 404 at
+// runtime in consumers (the file is fetched as a bare URL, its relative
+// chunk siblings are not copied along). Run after `tsdown` in the build.
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const dist = resolve(dirname(fileURLToPath(import.meta.url)), '../dist/tabs-broker-worker.js');
+
+let code;
+try {
+  code = readFileSync(dist, 'utf8');
+} catch {
+  console.error(`check-broker-bundle: ${dist} missing; did tsdown run?`);
+  process.exit(1);
+}
+
+const problems = [];
+// Static or dynamic imports of sibling chunks.
+const importRe = /(?:^|\n)\s*import[\s(]/;
+if (importRe.test(code)) problems.push('contains an import statement');
+if (!code.includes('onconnect')) problems.push('missing onconnect handler');
+
+if (problems.length > 0) {
+  console.error(`check-broker-bundle: dist/tabs-broker-worker.js ${problems.join('; ')}.`);
+  console.error(
+    'The broker worker must stay free of runtime imports (type-only imports are fine in source).'
+  );
+  process.exit(1);
+}
+console.log('check-broker-bundle: ok');

package/skills/{spooky-core → sp00ky-core}/SKILL.md

@@ -1,27 +1,27 @@
 ---
-name: spooky-core
+name: sp00ky-core
 description: >-
-  Core client for the Spooky reactive local-first SurrealDB framework. Use when
-  initializing SpookyClient, registering queries and subscriptions, performing
+  Core client for the Sp00ky reactive local-first SurrealDB framework. Use when
+  initializing Sp00kyClient, registering queries and subscriptions, performing
   mutations (create/update/delete), handling auth (signUp/signIn/signOut),
   working with file buckets, or using backend runs (HTTP outbox pattern).
 metadata:
-  author: spooky-sync
+  author: sp00ky-sync
   version: "0.0.1"
 ---
 
-# Spooky Core
+# Sp00ky Core
 
-`@spooky-sync/core` provides `SpookyClient`, the main entry point for the Spooky framework. It handles local-first data sync with SurrealDB, reactive queries, optimistic mutations, authentication, file storage, and backend runs.
+`@spooky-sync/core` provides `Sp00kyClient`, the main entry point for the Sp00ky framework. It handles local-first data sync with SurrealDB, reactive queries, optimistic mutations, authentication, file storage, and backend runs.
 
 ## Initialization
 
 ```typescript
-import { SpookyClient } from '@spooky-sync/core';
+import { Sp00kyClient } from '@spooky-sync/core';
 import { schema } from './generated/schema'; // Generated by `spooky generate`
 import schemaSurql from './generated/schema.surql?raw';
 
-const client = new SpookyClient({
+const client = new Sp00kyClient({
   database: {
     endpoint: 'ws://localhost:8000',
     namespace: 'my_ns',
@@ -40,7 +40,7 @@ await client.init();
 await client.close();
 ```
 
-### SpookyConfig Options
+### Sp00kyConfig Options
 
 See [references/config.md](references/config.md) for all configuration options.
 
@@ -159,13 +159,13 @@ Buckets must be defined in the schema under the `buckets` array.
 
 ## Backend Runs (HTTP Outbox)
 
-Backend runs let you trigger server-side HTTP operations via an **outbox pattern**. When you call `db.run()`, it creates a job record in a local outbox table. That record syncs to remote SurrealDB, where the Spooky Sync Platform (SSP) picks it up and calls your backend HTTP API. The result status is written back to the job record and syncs to the client reactively.
+Backend runs let you trigger server-side HTTP operations via an **outbox pattern**. When you call `db.run()`, it creates a job record in a local outbox table. That record syncs to remote SurrealDB, where the Sp00ky Sync Platform (SSP) picks it up and calls your backend HTTP API. The result status is written back to the job record and syncs to the client reactively.
 
 ### `db.run()` Signature
 
 ```typescript
 db.run<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(
-  backend: B,        // Backend name from spooky.yml (e.g., 'api')
+  backend: B,        // Backend name from sp00ky.yml (e.g., 'api')
   route: R,          // Route path from OpenAPI spec (e.g., '/spookify')
   payload: RoutePayload<S, B, R>,  // Typed args for the route
   options?: RunOptions
@@ -192,7 +192,7 @@ The `assignedTo` option is how you link a job to an entity. Passing a record ID:
 
 ### Full Example
 
-**1. Configure the backend in `spooky.yml`:**
+**1. Configure the backend in `sp00ky.yml`:**
 
 ```yaml
 backends:

package/skills/{spooky-core → sp00ky-core}/references/auth.md

@@ -2,7 +2,7 @@
 
 ## AuthService API
 
-The `AuthService` is available on `SpookyClient` as `client.auth`.
+The `AuthService` is available on `Sp00kyClient` as `client.auth`.
 
 ### Properties
 

package/skills/{spooky-core → sp00ky-core}/references/config.md

@@ -1,7 +1,7 @@
-# SpookyConfig Reference
+# Sp00kyConfig Reference
 
 ```typescript
-interface SpookyConfig<S extends SchemaStructure> {
+interface Sp00kyConfig<S extends SchemaStructure> {
   database: {
     /** SurrealDB WebSocket endpoint URL */
     endpoint?: string;

package/src/bucket-blurhash.test.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { BucketHandle } from './sp00ky';
+import type { RemoteDatabaseService } from './services/database/index';
+import {
+  blurhashSidecarPath,
+  isImagePath,
+  encodeImageToBlurhash,
+  encodeBlurhash,
+} from './utils/blurhash';
+
+// A real 1x1 hash so isBlurhashValid passes in the read-path tests.
+const VALID_HASH = encodeBlurhash(new Uint8ClampedArray([12, 34, 56, 255]), 1, 1, 1, 1);
+
+function makeRemote(queries: string[]) {
+  return {
+    query: vi.fn(async (surql: string) => {
+      queries.push(surql);
+      return [null];
+    }),
+  } as unknown as RemoteDatabaseService;
+}
+
+describe('blurhash path helpers', () => {
+  it('appends .bh for the sidecar', () => {
+    expect(blurhashSidecarPath('a/b_t.webp')).toBe('a/b_t.webp.bh');
+  });
+
+  it('recognizes image extensions case-insensitively', () => {
+    expect(isImagePath('x/y.webp')).toBe(true);
+    expect(isImagePath('x/y.PNG')).toBe(true);
+    expect(isImagePath('x/y.webp.bh')).toBe(false);
+    expect(isImagePath('x/notes.txt')).toBe(false);
+  });
+});
+
+describe('encodeImageToBlurhash outside a browser', () => {
+  it('returns null instead of throwing (no createImageBitmap in node)', async () => {
+    await expect(encodeImageToBlurhash(new Uint8Array([1, 2, 3]))).resolves.toBeNull();
+  });
+});
+
+describe('BucketHandle.put', () => {
+  let queries: string[];
+
+  beforeEach(() => {
+    queries = [];
+  });
+
+  it('image put succeeds with blurhash null when encoding is unavailable', async () => {
+    const handle = new BucketHandle('covers', makeRemote(queries), null);
+    const result = await handle.put('a/b_t.webp', new Uint8Array([1]));
+    expect(result).toEqual({ blurhash: null });
+    // Only the image put went out; no sidecar for a failed/unavailable encode.
+    expect(queries).toHaveLength(1);
+    expect(queries[0]).toContain('covers:/a/b_t.webp".put');
+  });
+
+  it('skips hashing entirely for non-image paths and when disabled', async () => {
+    const handle = new BucketHandle('covers', makeRemote(queries), null, { blurhash: false });
+    await handle.put('a/b_t.webp', new Uint8Array([1]));
+    await handle.put('a/readme.txt', 'hello');
+    expect(queries).toHaveLength(2);
+    expect(queries.some((q) => q.includes('.bh'))).toBe(false);
+  });
+
+  it('writes the sidecar when a hash is produced', async () => {
+    // Simulate a browser: a createImageBitmap whose bitmap a canvas can read.
+    const pixels = { width: 2, height: 2 };
+    vi.stubGlobal(
+      'createImageBitmap',
+      vi.fn(async () => ({ ...pixels, close: vi.fn() }))
+    );
+    vi.stubGlobal(
+      'OffscreenCanvas',
+      class {
+        width: number;
+        height: number;
+        constructor(w: number, h: number) {
+          this.width = w;
+          this.height = h;
+        }
+        getContext() {
+          return {
+            drawImage: () => {},
+            getImageData: (_x: number, _y: number, w: number, h: number) => ({
+              data: new Uint8ClampedArray(w * h * 4).fill(128),
+            }),
+          };
+        }
+      }
+    );
+    try {
+      const handle = new BucketHandle('covers', makeRemote(queries), null);
+      const result = await handle.put('a/b_t.webp', new Uint8Array([1]));
+      expect(result.blurhash).toBeTruthy();
+      expect(queries).toHaveLength(2);
+      expect(queries[1]).toContain('covers:/a/b_t.webp.bh".put');
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+});
+
+describe('BucketHandle.blurhash', () => {
+  it('returns a valid stored hash and negative-caches misses per path', async () => {
+    const reads: string[] = [];
+    let payload: unknown = VALID_HASH;
+    const remote = {
+      query: vi.fn(async (surql: string) => {
+        reads.push(surql);
+        return [payload];
+      }),
+    } as unknown as RemoteDatabaseService;
+    const handle = new BucketHandle('covers', remote, null);
+
+    await expect(handle.blurhash('hit/x.webp')).resolves.toBe(VALID_HASH);
+
+    payload = null;
+    await expect(handle.blurhash('miss/x.webp')).resolves.toBeNull();
+    const readsAfterMiss = reads.length;
+    // The miss is remembered: no second remote read for the same path.
+    await expect(handle.blurhash('miss/x.webp')).resolves.toBeNull();
+    expect(reads).toHaveLength(readsAfterMiss);
+  });
+
+  it('treats invalid sidecar content as missing', async () => {
+    const remote = {
+      query: vi.fn(async () => ['not a blurhash \\ at all']),
+    } as unknown as RemoteDatabaseService;
+    const handle = new BucketHandle('covers', remote, null);
+    await expect(handle.blurhash('bad/x.webp')).resolves.toBeNull();
+  });
+});
+
+describe('BucketHandle.delete', () => {
+  it('also deletes the sidecar for image paths, best-effort', async () => {
+    const queries: string[] = [];
+    const handle = new BucketHandle('covers', makeRemote(queries), null);
+    await handle.delete('a/b_t.webp');
+    expect(queries).toHaveLength(2);
+    expect(queries[0]).toContain('covers:/a/b_t.webp".delete');
+    expect(queries[1]).toContain('covers:/a/b_t.webp.bh".delete');
+
+    queries.length = 0;
+    await handle.delete('a/notes.txt');
+    expect(queries).toHaveLength(1);
+  });
+});

package/src/build-globals.d.ts

@@ -0,0 +1,12 @@
+// Build-time string constants injected by tsdown's `define` (see
+// tsdown.config.ts). They carry the real bundled frontend package versions so
+// the DevTools can surface frontend/backend version drift.
+//
+// Typed as `string | undefined` on purpose: the substitution only happens when
+// `@spooky-sync/core` is built with our tsdown plugin. A downstream app that
+// bundles core from source never runs that plugin, so these identifiers must be
+// guarded with `typeof` (see modules/devtools/index.ts) to avoid a runtime
+// ReferenceError that would break DB initialization.
+declare const __SP00KY_CORE_VERSION__: string | undefined;
+declare const __SP00KY_WASM_VERSION__: string | undefined;
+declare const __SP00KY_SURREAL_VERSION__: string | undefined;

package/src/events/events.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { EventSystem, EventDefinition } from './index';
+import type { EventDefinition } from './index';
+import { EventSystem } from './index';
 
 // Define test event types
 type TestEvents = {

package/src/events/index.ts

@@ -172,6 +172,9 @@ export class EventSystem<E extends EventTypeMap> {
    * @param payload The data associated with the event.
    */
   emit<T extends EventType<E>, P extends EventPayload<E, T>>(type: T, payload: P): void {
+    // `{ type, payload }` structurally matches `Event<E, T>` (= the indexed
+    // access `E[T]`), but TS can't verify assignability to an indexed-access
+    // type over the generic `E`/`T`, so the constructed event is asserted.
     const event = {
       type,
       payload,

package/src/index.ts

@@ -1,4 +1,38 @@
 export * from './types';
-export * from './spooky';
+export * from './sp00ky';
 export * from './modules/auth/index';
-export { fileToUint8Array } from './utils/index';
+export { CrdtField, CrdtManager, cursorColorFromName, CURSOR_COLORS } from './modules/crdt/index';
+export {
+  FeatureFlagModule,
+  FeatureFlagHandle,
+  type FeatureFlagOptions,
+  type FeatureFlagOverride,
+  type FeatureFlagSnapshot,
+} from './modules/feature-flag/index';
+export {
+  AppReleaseModule,
+  AppReleaseHandle,
+  type AppReleaseOptions,
+  type AppReleaseSnapshot,
+} from './modules/app-release/index';
+export type {
+  BlobCacheStats,
+  BlobEntry,
+  BlobKey,
+  BlobReadOptions,
+  BlobUrlLease,
+} from './services/blobs/index';
+export { semverGt } from './utils/semver';
+export { LocalOpTimeoutError, DEFAULT_LOCAL_OP_TIMEOUT_MS } from './services/database/errors';
+export { fileToUint8Array, textToHtml } from './utils/index';
+export {
+  blurhashSidecarPath,
+  encodeImageToBlurhash,
+  encodeBlurhash,
+  decodeBlurhash,
+  isBlurhashValid,
+  isImagePath,
+  BLURHASH_IMAGE_EXTENSIONS,
+  type BlurhashSetting,
+  type BlurhashEncodeOptions,
+} from './utils/blurhash';

package/src/modules/app-release/index.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { AppReleaseModule } from './index';
+
+// Mirrors the FeatureFlagModule test rig: the DataModule mock captures the
+// single subscribe callback so tests can push live results, and counts
+// query() calls to assert the query is SHARED across apps.
+function makeDeps() {
+  let subCb: ((records: unknown[]) => void) | null = null;
+  const calls: Array<{ sql: string; params: unknown }> = [];
+  let authCb: ((userId: string | null) => void) | null = null;
+
+  const dataModule = {
+    query: async (_table: string, sql: string, params: unknown) => {
+      calls.push({ sql, params });
+      return `hash:${calls.length}`;
+    },
+    subscribe: (_hash: string, cb: (records: unknown[]) => void) => {
+      subCb = cb;
+      return () => {
+        subCb = null;
+      };
+    },
+  };
+  const sync = { enqueueDownEvent: () => {} };
+  const auth = {
+    subscribe: (cb: (userId: string | null) => void) => {
+      authCb = cb;
+      return () => {
+        authCb = null;
+      };
+    },
+  };
+  const logger = { child: () => ({ warn: () => {} }) };
+
+  const deps = { dataModule, sync, auth, logger } as any;
+  return {
+    deps,
+    calls,
+    push: (records: unknown[]) => subCb?.(records),
+    setUser: (id: string | null) => authCb?.(id),
+    hasSub: () => subCb !== null,
+  };
+}
+
+const tick = () => new Promise((r) => setTimeout(r, 0));
+
+describe('AppReleaseModule', () => {
+  let env: ReturnType<typeof makeDeps>;
+  let mod: AppReleaseModule<any>;
+
+  beforeEach(() => {
+    env = makeDeps();
+    mod = new AppReleaseModule(env.deps);
+  });
+
+  it('registers ONE shared, unfiltered query for many apps', async () => {
+    mod.release('web');
+    mod.release('admin');
+    await tick();
+
+    expect(env.calls.length).toBe(1);
+    expect(env.calls[0].sql).not.toContain('WHERE');
+    expect(env.calls[0].sql).toContain('FROM _00_app_release');
+  });
+
+  it('fans the shared result out to each handle by app', async () => {
+    const web = mod.release('web');
+    const missing = mod.release('missing');
+    await tick();
+
+    env.push([{ app: 'web', version: '1.2.0', cache_bust: true, mandatory: null }]);
+
+    expect(web.version()).toBe('1.2.0');
+    expect(web.snapshot().cacheBust).toBe(true);
+    expect(web.snapshot().mandatory).toBe(false);
+    expect(missing.version()).toBeUndefined();
+    expect(missing.updateAvailable('1.0.0')).toBe(false);
+  });
+
+  it('updateAvailable compares semver against the running build', async () => {
+    const web = mod.release('web');
+    await tick();
+
+    env.push([{ app: 'web', version: '1.2.0' }]);
+    expect(web.updateAvailable('1.1.9')).toBe(true);
+    expect(web.updateAvailable('1.2.0')).toBe(false);
+    expect(web.updateAvailable('1.3.0')).toBe(false);
+    expect(web.updateAvailable('garbage')).toBe(false);
+  });
+
+  it('observes row updates live without re-registering', async () => {
+    const web = mod.release('web');
+    await tick();
+
+    env.push([{ app: 'web', version: '1.0.0' }]);
+    expect(web.updateAvailable('1.0.0')).toBe(false);
+
+    env.push([{ app: 'web', version: '1.0.1', mandatory: true }]);
+    expect(web.updateAvailable('1.0.0')).toBe(true);
+    expect(web.snapshot().mandatory).toBe(true);
+
+    expect(env.calls.length).toBe(1);
+  });
+
+  it('seeds a late-created handle from the already-loaded snapshot', async () => {
+    mod.release('web');
+    await tick();
+    env.push([{ app: 'web', version: '2.0.0' }]);
+
+    const late = mod.release('web');
+    expect(late.version()).toBe('2.0.0');
+  });
+
+  it('re-registers on user change', async () => {
+    mod.init();
+    const web = mod.release('web');
+    await tick();
+    env.push([{ app: 'web', version: '1.0.0' }]);
+    expect(web.version()).toBe('1.0.0');
+
+    env.setUser('user:other');
+    await tick();
+    expect(env.hasSub()).toBe(true); // re-registered under the new session
+  });
+});