@spooky-sync/client-solid 0.0.1-canary.33 → 0.0.1-canary.330

package/src/index.ts

@@ -1,14 +1,19 @@
 import type { SyncedDbConfig } from './types';
 import {
   Sp00kyClient,
-  AuthService,
-  BucketHandle,
   type Sp00kyQueryResultPromise,
-  UpdateOptions,
-  RunOptions,
+  type AuthService,
+  type BucketHandle,
+  type UpdateOptions,
+  type RunOptions,
+  type SyncHealth,
+  type StorageHealth,
+  type PreloadOptions,
+  type PreloadRefresh,
+  type WebPushModule,
 } from '@spooky-sync/core';
 
-import {
+import type {
   GetTable,
   QueryBuilder,
   SchemaStructure,
@@ -19,25 +24,89 @@ import {
   RelationshipFieldsFromSchema,
   GetRelationship,
   RelatedFieldMapEntry,
+  FinalQuery,
   InnerQuery,
   BackendNames,
   BackendRoutes,
   RoutePayload,
   BucketNames,
   BucketDefinitionSchema,
+  QueryModifier,
+  QueryModifierBuilder,
+  QueryInfo,
+  RelationshipsMetadata,
+  RelationshipDefinition,
+  InferRelatedModelFromMetadata,
+  GetCardinality,
 } from '@spooky-sync/query-builder';
 
-import { RecordId, Uuid, Surreal } from 'surrealdb';
+import { RecordId, Uuid, type Surreal } from 'surrealdb';
 export { RecordId, Uuid };
 export type { Model, GenericModel, GenericSchema, ModelPayload } from './lib/models';
 export { useQuery } from './lib/use-query';
+export { createPreload } from './lib/create-preload';
+export type { PreloadOptions, PreloadRefresh } from '@spooky-sync/core';
+export { useSyncStatus, type UseSyncStatus } from './lib/use-sync-status';
+export {
+  useImpersonation,
+  type UseImpersonation,
+  type UseImpersonationOptions,
+} from './lib/use-impersonation';
+export type {
+  SyncHealth,
+  SyncHealthStatus,
+  SyncHealthConfig,
+  ConnectionState,
+  ReconnectConfig,
+} from '@spooky-sync/core';
+export { useStorageStatus, type UseStorageStatus } from './lib/use-storage-status';
+export type { StorageHealth, StorageHealthStatus } from '@spooky-sync/core';
+export {
+  WebPushError,
+  type WebPushModule,
+  type WebPushConfig,
+  type WebPushSupport,
+  type WebPushUnsupportedReason,
+  type WebPushInfo,
+  type WebPushDevice,
+  type PushDeviceKind,
+  type WebPushSubscribeOptions,
+  type WebPushUnsubscribeOptions,
+  type WebPushSyncOptions,
+  type WebPushSyncStatus,
+  type WebPushUpdateOptions,
+  type WebPushMessageInput,
+  type WebPushMessage,
+  type WebPushErrorCode,
+  type WebPushClientMessage,
+  type PushPayload,
+  type PushNotification,
+} from '@spooky-sync/core';
+export { useCrdtField } from './lib/use-crdt-field';
+export { useFeatureFlag, type UseFeatureFlag } from './lib/use-feature-flag';
+export {
+  useAppRelease,
+  type UseAppRelease,
+  type UseAppReleaseOptions,
+} from './lib/use-app-release';
 export { useFileUpload, type FileUploadResult } from './lib/use-file-upload';
-export { useDownloadFile, type UseDownloadFileOptions, type UseDownloadFileResult } from './lib/use-download-file';
+export {
+  useDownloadFile,
+  type UseDownloadFileOptions,
+  type UseDownloadFileResult,
+} from './lib/use-download-file';
+export { useBlurhash, type UseBlurhashResult } from './lib/use-blurhash';
+export {
+  useBucketImage,
+  type UseBucketImageOptions,
+  type UseBucketImageResult,
+} from './lib/use-bucket-image';
+export { Blurhash, type BlurhashProps } from './lib/Blurhash';
+export { BucketImage, type BucketImageProps } from './lib/BucketImage';
 export { Sp00kyProvider, type Sp00kyProviderProps } from './lib/Sp00kyProvider';
 export { useDb } from './lib/context';
 
 // export { AuthEventTypes } from "@spooky-sync/core"; // TODO: Verify if AuthEventTypes exists in core
-export type {};
 
 // Re-export query builder types for convenience
 export type {
@@ -52,7 +121,7 @@ export type {
   TableModel,
   TableNames,
   QueryResult,
-} from '@spooky-sync/query-builder';
+};
 
 export type RelationshipField<
   Schema extends SchemaStructure,
@@ -121,6 +190,19 @@ export class SyncedDb<S extends SchemaStructure> {
     this._initialized = true;
   }
 
+  /**
+   * Tear down the client: leaves the tabs broker, closes the local store and
+   * remote socket, and frees the wasm circuit. Without this a remounted provider
+   * (or an HMR reload) strands a whole client, and the abandoned wasm heaps stay
+   * resident because V8 cannot see how much wasm memory a dropped wrapper holds.
+   */
+  async close(): Promise<void> {
+    const instance = this.sp00ky;
+    this.sp00ky = null;
+    this._initialized = false;
+    if (instance) await instance.close();
+  }
+
   /**
    * Create a new record in the database
    */
@@ -152,12 +234,39 @@ export class SyncedDb<S extends SchemaStructure> {
    */
   async delete<TName extends TableNames<S>>(
     tableName: TName,
-    selector: string | InnerQuery<GetTable<S, TName>, boolean>
+    selector: string | RecordId | InnerQuery<GetTable<S, TName>, boolean>
+  ): Promise<void> {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    // Accept a `"table:id"` string OR a RecordId — live-query rows carry their
+    // `id` as a RecordId, so callers can pass `db.delete('game', row.id)`
+    // directly. Build the canonical string from the raw id part (not
+    // `RecordId.toString()`, which escapes special chars) so it round-trips
+    // through the engine's `parseRecordIdString`. InnerQuery selectors are not
+    // supported yet. (cross-package RecordId instances → match by constructor name.)
+    const isRecordId =
+      selector instanceof RecordId || (selector as any)?.constructor?.name === 'RecordId';
+    let id: string;
+    if (typeof selector === 'string') {
+      id = selector;
+    } else if (isRecordId) {
+      id = `${tableName as string}:${(selector as RecordId).id}`;
+    } else {
+      throw new Error('Only string ID or RecordId selectors are supported currently with core');
+    }
+    await this.sp00ky.delete(tableName as string, id);
+  }
+
+  /**
+   * Preload/prewarm a built query into the local cache without registering a
+   * live view. Fetches once and stores the rows (+ embedded related children)
+   * locally so a later `useQuery` for the same data paints instantly. Best-effort.
+   */
+  public async preload(
+    finalQuery: FinalQuery<S, any, any, any, any, Sp00kyQueryResultPromise>,
+    options?: PreloadOptions
   ): Promise<void> {
     if (!this.sp00ky) throw new Error('SyncedDb not initialized');
-    if (typeof selector !== 'string')
-      throw new Error('Only string ID selectors are supported currently with core');
-    await this.sp00ky.delete(tableName as string, selector);
+    await this.sp00ky.preload(finalQuery, options);
   }
 
   /**
@@ -173,14 +282,11 @@ export class SyncedDb<S extends SchemaStructure> {
   /**
    * Run a backend operation
    */
-  public async run<
-    B extends BackendNames<S>,
-    R extends BackendRoutes<S, B>,
-  >(
+  public async run<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(
     backend: B,
     path: R,
     payload: RoutePayload<S, B, R>,
-    options?: RunOptions,
+    options?: RunOptions
   ): Promise<void> {
     if (!this.sp00ky) throw new Error('SyncedDb not initialized');
     await this.sp00ky.run(backend, path, payload, options);
@@ -190,7 +296,7 @@ export class SyncedDb<S extends SchemaStructure> {
    * Authenticate with the database
    */
   public async authenticate(token: string): Promise<RecordId<string>> {
-    const result = await this.sp00ky?.authenticate(token);
+    await this.sp00ky?.authenticate(token);
     // Sp00kyClient.authenticate returns whatever remote.authenticate returns (boolean or token usually?)
     // Wait, checked Sp00kyClient: return this.remote.getClient().authenticate(token);
     // SurrealDB authenticate returns void? or token?
@@ -206,6 +312,16 @@ export class SyncedDb<S extends SchemaStructure> {
     await this.signOut();
   }
 
+  /**
+   * Tell the client that this app's own impersonation banner is on screen.
+   * Only needed with `impersonationBanner: { mode: 'custom' }`; the
+   * `useImpersonation({ rendersBanner: true })` hook calls it for you.
+   */
+  public acknowledgeImpersonationBanner(): void {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    this.sp00ky.acknowledgeImpersonationBanner();
+  }
+
   /**
    * Sign out, clear session and local storage
    */
@@ -221,6 +337,23 @@ export class SyncedDb<S extends SchemaStructure> {
     if (!this.sp00ky) throw new Error('SyncedDb not initialized');
     return await this.sp00ky.useRemote(fn);
   }
+
+  /**
+   * Run one SurrealQL statement on the server and return its result array.
+   * Nothing is cached locally. Prefer this over `useRemote(s => s.query(...))`
+   * for a plain read or write: the bare SDK client that callback receives
+   * skips the connect gate, so a statement issued while the socket is being
+   * rebuilt fails with "Specify a namespace to use" instead of waiting for
+   * the session. This one is also bounded by the remote service's
+   * concurrency limit and query timeout.
+   */
+  public async remoteQuery<T extends unknown[] = unknown[]>(
+    sql: string,
+    vars?: Record<string, unknown>
+  ): Promise<T> {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return await this.sp00ky.remoteQuery<T>(sql, vars);
+  }
   /**
    * Access the remote database service directly
    */
@@ -250,11 +383,59 @@ export class SyncedDb<S extends SchemaStructure> {
     return this.sp00ky.pendingMutationCount;
   }
 
+  /** Diagnostic — see `Sp00kyClient.liveRetryCount`. */
+  get liveRetryCount(): number {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.liveRetryCount;
+  }
+
   subscribeToPendingMutations(cb: (count: number) => void): () => void {
     if (!this.sp00ky) throw new Error('SyncedDb not initialized');
     return this.sp00ky.subscribeToPendingMutations(cb);
   }
 
+  /** Current sync-health snapshot. See {@link useSyncStatus}. */
+  get syncHealth(): SyncHealth {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.syncHealth;
+  }
+
+  /**
+   * Observe sync health. Fires immediately with the current status and again
+   * on every healthy↔degraded transition. Prefer the `useSyncStatus` hook in
+   * components; this is the imperative escape hatch.
+   */
+  subscribeToSyncHealth(cb: (health: SyncHealth) => void): () => void {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.subscribeToSyncHealth(cb);
+  }
+
+  /** Current local-store durability snapshot. See {@link useStorageStatus}. */
+  get storageHealth(): StorageHealth {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.storageHealth;
+  }
+
+  /**
+   * Observe local-store durability. Fires immediately with the current snapshot
+   * and again on change. Prefer the `useStorageStatus` hook in components; this
+   * is the imperative escape hatch.
+   */
+  subscribeToStorageHealth(cb: (health: StorageHealth) => void): () => void {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.subscribeToStorageHealth(cb);
+  }
+
+  /**
+   * Web Push for this browser: `support()`, `subscribe()` (from a click),
+   * `devices()`, `notify()` / `test()` (push to yourself), `bridge()` for the
+   * service worker. See the push-notifications docs page.
+   */
+  get webPush(): WebPushModule {
+    if (!this.sp00ky) throw new Error('SyncedDb not initialized');
+    return this.sp00ky.webPush;
+  }
+
   bucket<B extends BucketNames<S>>(name: B): BucketHandle {
     if (!this.sp00ky) throw new Error('SyncedDb not initialized');
     return this.sp00ky.bucket(name);

package/src/lib/Blurhash.ts

@@ -0,0 +1,54 @@
+import { createEffect } from 'solid-js';
+import type { JSX } from 'solid-js';
+import { decodeBlurhash } from '@spooky-sync/core';
+
+export interface BlurhashProps {
+  /** The blurhash string. Nullish paints nothing (transparent canvas). */
+  hash: string | null | undefined;
+  /** Decode resolution. 32x32 is plenty: blurhash carries at most 9x9 DCT
+   *  components, the canvas is meant to be CSS-scaled to fill. */
+  width?: number;
+  height?: number;
+  /** Contrast punch, see the blurhash reference decoder. Defaults to 1. */
+  punch?: number;
+  class?: string;
+  style?: string;
+}
+
+/**
+ * A blurhash painted onto a canvas, once per hash change. Size the canvas via
+ * `class`/`style` (e.g. `absolute inset-0 w-full h-full`); the internal decode
+ * resolution stays tiny regardless of the displayed size.
+ */
+export function Blurhash(props: BlurhashProps): JSX.Element {
+  if (typeof document === 'undefined') return null;
+  const canvas = document.createElement('canvas');
+
+  createEffect(() => {
+    canvas.className = props.class ?? '';
+  });
+  createEffect(() => {
+    canvas.style.cssText = props.style ?? '';
+  });
+
+  createEffect(() => {
+    const width = props.width ?? 32;
+    const height = props.height ?? 32;
+    canvas.width = width;
+    canvas.height = height;
+    const hash = props.hash;
+    if (!hash) return;
+    try {
+      const pixels = decodeBlurhash(hash, width, height, props.punch ?? 1);
+      const ctx = canvas.getContext('2d');
+      if (!ctx) return;
+      const imageData = ctx.createImageData(width, height);
+      imageData.data.set(pixels);
+      ctx.putImageData(imageData, 0, 0);
+    } catch {
+      // An invalid hash paints nothing; the layer below stays visible.
+    }
+  });
+
+  return canvas;
+}

package/src/lib/BucketImage.ts

@@ -0,0 +1,141 @@
+import { createSignal, createEffect, onMount, onCleanup, children } from 'solid-js';
+import type { JSX } from 'solid-js';
+import type { BucketNames, SchemaStructure } from '@spooky-sync/query-builder';
+import { useBucketImage, type UseBucketImageOptions } from './use-bucket-image';
+import { Blurhash } from './Blurhash';
+
+export interface BucketImageProps {
+  /** Bucket name from the schema. */
+  bucket: string;
+  /** Path within the bucket. Nullish renders only the fallback layers. */
+  path: string | null | undefined;
+  alt?: string;
+  /** Classes for the container element (sizing/positioning). */
+  class?: string;
+  /** Classes for the inner `<img>` (the layout styles are inline). */
+  imgClass?: string;
+  /** `object-fit` for the image. Defaults to `cover`. */
+  fit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
+  /**
+   * Bottom placeholder layer (your own plate/skeleton), shown until the image
+   * settles. The blurhash layer paints on top of it once the sidecar resolves.
+   */
+  fallback?: JSX.Element;
+  /** Crossfade duration in ms. Defaults to 300. */
+  transition?: number;
+  /** Crossfade easing. Defaults to an ease-out-expo curve. */
+  easing?: string;
+  /** Resolve the blurhash sidecar. Defaults to true. */
+  blurhash?: boolean;
+  /** Download tuning, forwarded to the underlying `useDownloadFile`. */
+  options?: UseBucketImageOptions;
+}
+
+const LAYER_STYLE = 'position:absolute;inset:0;width:100%;height:100%;';
+
+/**
+ * A bucket image that never pops in: it layers (bottom to top) your `fallback`
+ * plate, the automatically stored blurhash, and the real image, which stays
+ * transparent until the bitmap is DECODED and then crossfades over the
+ * placeholders. Placeholder layers unmount once the fade settles. Respects
+ * prefers-reduced-motion (instant swap). The container is made
+ * `position: relative` unless your `class` positions it already.
+ *
+ * ```tsx
+ * <BucketImage bucket="covers" path={row.cover_key} class="absolute inset-0"
+ *              fallback={<MyPlate />} alt="" />
+ * ```
+ */
+export function BucketImage(props: BucketImageProps): JSX.Element {
+  if (typeof document === 'undefined') return null;
+
+  const image = useBucketImage(
+    props.bucket as BucketNames<SchemaStructure>,
+    () => props.path,
+    { ...props.options, blurhash: props.blurhash !== false }
+  );
+
+  const reducedMotion =
+    typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+  const root = document.createElement('div');
+  createEffect(() => {
+    root.className = props.class ?? '';
+  });
+  // Layers are absolutely positioned; give them an anchor without stomping on
+  // a caller class that already positions the container (inline would win).
+  onMount(() => {
+    if (getComputedStyle(root).position === 'static') root.style.position = 'relative';
+  });
+
+  const placeholder = document.createElement('div');
+  placeholder.style.cssText = LAYER_STYLE;
+  // Solid hands JSX props over as lazy thunks; `children` resolves them (and
+  // nested arrays/functions) to real nodes and keeps them alive reactively.
+  const fallbackHolder = document.createElement('div');
+  fallbackHolder.style.cssText = LAYER_STYLE;
+  placeholder.append(fallbackHolder);
+  const resolvedFallback = children(() => props.fallback);
+  createEffect(() => {
+    const nodes = resolvedFallback.toArray().filter((node) => node instanceof Node) as Node[];
+    fallbackHolder.replaceChildren(...nodes);
+  });
+  const hashCanvas = Blurhash({
+    get hash() {
+      return image.blurhash();
+    },
+    style: LAYER_STYLE,
+  });
+  if (hashCanvas instanceof Node) placeholder.append(hashCanvas);
+
+  const img = document.createElement('img');
+  img.decoding = 'async';
+  img.style.cssText = `${LAYER_STYLE}opacity:0;`;
+  createEffect(() => {
+    img.className = props.imgClass ?? '';
+  });
+  createEffect(() => {
+    img.style.objectFit = props.fit ?? 'cover';
+  });
+  createEffect(() => {
+    img.alt = props.alt ?? '';
+  });
+  createEffect(() => {
+    img.style.transition = reducedMotion
+      ? 'none'
+      : `opacity ${props.transition ?? 300}ms ${props.easing ?? 'cubic-bezier(0.16, 1, 0.3, 1)'}`;
+  });
+  createEffect(() => {
+    const url = image.url();
+    if (!url) {
+      img.removeAttribute('src');
+      return;
+    }
+    img.src = url;
+    image.gate(img);
+  });
+  createEffect(() => {
+    img.style.opacity = image.ready() ? '1' : '0';
+  });
+
+  // Placeholders leave the DOM once the fade is over (a shelf of covers should
+  // not composite three layers each forever) and come back when the path
+  // changes mid-life (`ready` re-arms via the hook).
+  const [settled, setSettled] = createSignal(false);
+  createEffect(() => {
+    if (!image.ready()) {
+      setSettled(false);
+      return;
+    }
+    const wait = (reducedMotion ? 0 : (props.transition ?? 300)) + 120;
+    const timer = setTimeout(() => setSettled(true), wait);
+    onCleanup(() => clearTimeout(timer));
+  });
+  createEffect(() => {
+    if (settled()) placeholder.remove();
+    else if (!placeholder.isConnected) root.insertBefore(placeholder, img);
+  });
+
+  root.append(placeholder, img);
+  return root;
+}

package/src/lib/Sp00kyProvider.ts

@@ -1,4 +1,12 @@
-import { createSignal, onMount, createComponent, createMemo, JSX, mergeProps } from 'solid-js';
+import type { JSX } from 'solid-js';
+import {
+  createSignal,
+  onMount,
+  onCleanup,
+  createComponent,
+  createMemo,
+  mergeProps,
+} from 'solid-js';
 import type { SchemaStructure } from '@spooky/query-builder';
 import type { SyncedDbConfig } from '../types';
 import { SyncedDb } from '../index';
@@ -9,6 +17,15 @@ export interface Sp00kyProviderProps<S extends SchemaStructure> {
   fallback?: JSX.Element;
   onError?: (error: Error) => void;
   onReady?: (db: SyncedDb<S>) => void;
+  /**
+   * Prewarm data into the local cache before revealing the UI. Runs after
+   * `init()`; the `fallback` stays visible until it resolves. Use awaitable
+   * `db.preload(...)` calls here to gate first-load on essential data (e.g.
+   * config). On warm loads preload returns instantly, so there's no perceptible
+   * gate after the first run. Best-effort: a rejection is caught and the UI is
+   * revealed anyway.
+   */
+  preload?: (db: SyncedDb<S>) => Promise<void>;
   children: JSX.Element;
 }
 
@@ -24,10 +41,41 @@ export function Sp00kyProvider<S extends SchemaStructure>(
 
   const [db, setDb] = createSignal<SyncedDb<S> | undefined>(undefined);
 
+  // `onMount` is async, so a dispose can land mid-init. Only that narrow race is
+  // handled here: an instance whose init finished AFTER the provider was already
+  // gone is closed, because nothing will ever reference it.
+  //
+  // A live, mounted client is deliberately NOT closed on cleanup. Doing that
+  // nulls `SyncedDb.sp00ky`, so every later `create`/`update`/`delete` throws
+  // "SyncedDb not initialized" while reads keep rendering from state that is
+  // already subscribed — i.e. mutations die silently and the app looks fine. In
+  // a host app the provider wraps the whole tree and only unmounts with the
+  // page, where the browser reclaims the worker anyway, so the leak this was
+  // meant to fix is worth far less than that risk.
+  let disposed = false;
+
+  onCleanup(() => {
+    disposed = true;
+  });
+
   onMount(async () => {
     try {
       const instance = new SyncedDb<S>(merged.config);
       await instance.init();
+      if (disposed) {
+        await instance.close();
+        return;
+      }
+      // Gate first-load UI on prewarmed data. Best-effort: never let a preload
+      // failure keep the app stuck on the fallback.
+      if (merged.preload) {
+        try {
+          await merged.preload(instance);
+        } catch (e) {
+          // oxlint-disable-next-line no-console
+          console.error('Sp00kyProvider: preload failed; revealing UI anyway', e);
+        }
+      }
       setDb(() => instance);
       merged.onReady?.(instance);
     } catch (e) {
@@ -35,6 +83,7 @@ export function Sp00kyProvider<S extends SchemaStructure>(
       if (merged.onError) {
         merged.onError(error);
       } else {
+        // oxlint-disable-next-line no-console
         console.error('Sp00kyProvider: Failed to initialize database', error);
       }
     }