@spooky-sync/client-solid2 0.0.1-alpha.1

package/dist/index.d.ts

@@ -0,0 +1,670 @@
+import { AppReleaseOptions, AuthService, BucketHandle, BucketPutOptions, BucketPutResult, ConnectionState, ConnectionState as ConnectionState$1, CrdtField, FeatureFlagOptions, PreloadOptions, PreloadOptions as PreloadOptions$1, PreloadRefresh, ReconnectConfig, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResultPromise, StorageHealth, StorageHealth as StorageHealth$1, StorageHealthStatus, StorageHealthStatus as StorageHealthStatus$1, SyncHealth, SyncHealth as SyncHealth$1, SyncHealthConfig, SyncHealthStatus, SyncHealthStatus as SyncHealthStatus$1, UpdateOptions } from "@spooky-sync/core";
+import { RecordId, RecordId as RecordId$1, Surreal, Uuid } from "surrealdb";
+import { Accessor, Element } from "solid-js";
+import { BackendNames, BackendRoutes, BucketDefinitionSchema, BucketNames, ColumnSchema, FinalQuery, GenericModel, GenericSchema, GetCardinality, GetRelationship, GetTable, GetTable as GetTable$1, InferRelatedModelFromMetadata, InnerQuery, QueryBuilder, QueryInfo, QueryModifier, QueryModifierBuilder, QueryResult, QueryResult as QueryResult$1, RelatedFieldMapEntry, RelatedFieldsMap, RelationshipDefinition, RelationshipFieldsFromSchema, RelationshipsMetadata, RoutePayload, SchemaStructure, TableModel, TableModel as TableModel$1, TableNames, TableNames as TableNames$1 } from "@spooky-sync/query-builder";
+
+//#region src/lib/models.d.ts
+type Model<T> = T;
+type ModelPayload<T> = T & {
+  id: RecordId$1;
+};
+//# sourceMappingURL=models.d.ts.map
+//#endregion
+//#region src/types/index.d.ts
+/**
+ * Options for database provisioning
+ */
+interface ProvisionOptions {
+  /** Force re-provision even if schema already exists */
+  force?: boolean;
+}
+sideEffect();
+type CacheStrategy = 'memory' | 'indexeddb';
+/**
+ * Infer Schema type (Record<TableName, Model>) from schema const
+ */
+type InferSchemaFromConst<S extends SchemaStructure> = { [K in TableNames$1<S>]: TableModel$1<GetTable$1<S, K>> };
+/**
+ * Infer Relationships type from schema const's relationships array
+ * Converts from array format to nested object format
+ */
+type InferRelationshipsFromConst<S extends SchemaStructure, Schema extends GenericSchema> = { [TableName in TableNames$1<S>]: { [Rel in Extract<S['relationships'][number], {
+  from: TableName;
+}> as Rel['field']]: {
+  model: Rel['to'] extends keyof Schema ? Schema[Rel['to']] : any;
+  table: Rel['to'];
+  cardinality: Rel['cardinality'];
+} } };
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+type SyncedDbConfig<S extends SchemaStructure> = Prettify<Sp00kyConfig<S>>;
+//#endregion
+//#region src/lib/create-query.d.ts
+type QueryArg<S extends SchemaStructure, TableName extends TableNames$1<S>, T extends {
+  columns: Record<string, ColumnSchema>;
+}, RelatedFields extends Record<string, any>, IsOne extends boolean> = FinalQuery<S, TableName, T, RelatedFields, IsOne, Sp00kyQueryResultPromise> | (() => FinalQuery<S, TableName, T, RelatedFields, IsOne, Sp00kyQueryResultPromise> | null | undefined);
+type QueryOptions = {
+  enabled?: () => boolean;
+  /**
+   * Tear down the query (remote `_00_query` view + local WASM view) when this
+   * hook is disposed and no other subscriber remains, instead of keeping it
+   * resident for cheap re-subscription. Use for viewport-windowed lists that
+   * mount/unmount a query per scroll window and want off-screen windows
+   * cancelled. Trade-off: scrolling back to a torn-down window re-registers it.
+   */
+  deregisterOnCleanup?: boolean;
+};
+type CreateQueryResult<TData> = {
+  /**
+   * Reactive result. Never suspends and never throws: born as an empty
+   * committed value (`[]` / `null`) and reconciled in place (keyed by `id`) on
+   * every live emission — unchanged rows keep identity, and coarse readers
+   * (`<For>`) are notified on add/remove/reorder.
+   */
+  data: Accessor<TData>;
+  /**
+   * Suspending read of the same result for `<Loading>` users: throws Solid's
+   * not-ready protocol until the query has delivered its first real result
+   * (or errored, in which case it returns the empty value and `error()` is
+   * set). Read this inside a `<Loading>` boundary.
+   */
+  ready: Accessor<TData>;
+  error: Accessor<Error | undefined>;
+  /**
+   * True only on a COLD first load: nothing has painted for this identity,
+   * the server has not answered yet, and registration has not failed. A query
+   * that painted from the local cache is not loading, however long the server
+   * takes; a query the server answered with zero rows is not loading either
+   * (see `isEmpty`). Resets when the query identity changes.
+   */
+  isLoading: Accessor<boolean>;
+  /** True while a fetch cycle is in flight (registration, a sync round). */
+  isFetching: Accessor<boolean>;
+  /**
+   * True once server membership is known for this identity: a registration or
+   * poll landed, or the durable membership of a previous session was read on
+   * boot. From then on `data()` is the server's answer, not a cache guess.
+   * Latched until the identity changes (or a bucket switch resets it).
+   */
+  isAuthoritative: Accessor<boolean>;
+  /** Whether `data()` currently holds anything: rows for a list, a row for `one()`. */
+  hasData: Accessor<boolean>;
+  /**
+   * The server answered and the answer is "no rows". The signal to render an
+   * empty state on; a bare `!hasData()` cannot tell empty from not-yet-loaded.
+   */
+  isEmpty: Accessor<boolean>;
+  /**
+   * True once server membership is known AND no fetch cycle is in flight.
+   * While settled, results are authoritative: a windowed query returning fewer
+   * rows than its LIMIT really is the end of the list. Not monotonic: a later
+   * sync round re-enters `isFetching`; latch it if a verdict must stick.
+   */
+  isSettled: Accessor<boolean>;
+};
+declare function createQuery<S extends SchemaStructure, TableName extends TableNames$1<S>, T extends {
+  columns: Record<string, ColumnSchema>;
+}, RelatedFields extends Record<string, any>, IsOne extends boolean, TData = QueryResult$1<S, TableName, RelatedFields, IsOne> | null>(finalQuery: QueryArg<S, TableName, T, RelatedFields, IsOne>, options?: QueryOptions): CreateQueryResult<TData>;
+declare function createQuery<S extends SchemaStructure, TableName extends TableNames$1<S>, T extends {
+  columns: Record<string, ColumnSchema>;
+}, RelatedFields extends Record<string, any>, IsOne extends boolean, TData = QueryResult$1<S, TableName, RelatedFields, IsOne> | null>(db: SyncedDb<S>, finalQuery: QueryArg<S, TableName, T, RelatedFields, IsOne>, options?: QueryOptions): CreateQueryResult<TData>;
+/** @deprecated Renamed `createQuery` in the Solid 2 binding. */
+declare const useQuery: typeof createQuery;
+//#endregion
+//#region src/lib/create-preload.d.ts
+type PreloadArg<S extends SchemaStructure, TableName extends TableNames$1<S>, T extends {
+  columns: Record<string, ColumnSchema>;
+}, RelatedFields extends Record<string, any>, IsOne extends boolean> = FinalQuery<S, TableName, T, RelatedFields, IsOne, Sp00kyQueryResultPromise> | (() => FinalQuery<S, TableName, T, RelatedFields, IsOne, Sp00kyQueryResultPromise> | null | undefined);
+type PreloadOptions$2 = PreloadOptions$1 & {
+  /** Only preload while this returns true (defaults to always). */
+  enabled?: () => boolean;
+};
+declare function createPreload<S extends SchemaStructure, TableName extends TableNames$1<S>, T extends {
+  columns: Record<string, ColumnSchema>;
+}, RelatedFields extends Record<string, any>, IsOne extends boolean>(finalQuery: PreloadArg<S, TableName, T, RelatedFields, IsOne>, options?: PreloadOptions$2): void;
+declare function createPreload<S extends SchemaStructure, TableName extends TableNames$1<S>, T extends {
+  columns: Record<string, ColumnSchema>;
+}, RelatedFields extends Record<string, any>, IsOne extends boolean>(db: SyncedDb<S>, finalQuery: PreloadArg<S, TableName, T, RelatedFields, IsOne>, options?: PreloadOptions$2): void;
+//#endregion
+//#region src/lib/use-sync-status.d.ts
+interface UseSyncStatus {
+  /** Full health snapshot; updates reactively on every transition. */
+  health: Accessor<SyncHealth$1>;
+  /** `'healthy'` | `'degraded'`. */
+  status: Accessor<SyncHealthStatus$1>;
+  isHealthy: Accessor<boolean>;
+  /** `true` once sync has failed for a sustained run — drive a banner off this. */
+  isDegraded: Accessor<boolean>;
+  /** `true` once at least one sync round has succeeded this session. */
+  everConnected: Accessor<boolean>;
+  /**
+   * `true` only for a real lost connection: degraded AFTER a first successful
+   * sync. Stays `false` during the initial "connecting" phase (degraded but
+   * never reached the server yet), so an indicator can show nothing until the
+   * app has actually connected once.
+   */
+  isOffline: Accessor<boolean>;
+  /**
+   * Transport state of the remote WebSocket. Flips the instant the socket
+   * drops, unlike `status`, which only degrades after a sustained run of failed
+   * sync rounds — so this is what to drive a "reconnecting…" affordance off.
+   */
+  connection: Accessor<ConnectionState$1>;
+  /**
+   * `true` while the connection is being re-established. Usually still
+   * `isHealthy()`: a short reconnect is invisible to sync, and writes made
+   * during it are queued locally and pushed once the socket is back.
+   */
+  isReconnecting: Accessor<boolean>;
+}
+/**
+ * Observe sync health for a "can't reach the server" banner / indicator.
+ *
+ * Backed by `db.subscribeToSyncHealth`. Individual sync failures (a transient
+ * remote 500 on query registration, a dropped socket) are absorbed by the
+ * retry and never flip this; `isDegraded()` only goes true once failures
+ * persist for the configured number of consecutive rounds (sp00ky core config
+ * `syncHealth.degradeAfterConsecutiveFailures`, default 3), and flips back on
+ * the next successful round. Must be used within a `<Sp00kyProvider>`.
+ */
+declare function useSyncStatus(): UseSyncStatus;
+//# sourceMappingURL=use-sync-status.d.ts.map
+//#endregion
+//#region src/lib/use-sync-activity.d.ts
+interface UseSyncActivityOptions {
+  /**
+   * How long queries must be fetching before `isDownloading()` turns on.
+   * Filters the sub-frame fetches a warm cache produces, so the indicator only
+   * shows work the user could notice. Default 200 ms.
+   */
+  downloadDelayMs?: number;
+  /**
+   * `isUploading()` turns on once MORE than this many mutations are waiting in
+   * the outbox. Default 1: a single write acknowledged within a round trip is
+   * not worth an animation; a backlog is.
+   */
+  uploadThreshold?: number;
+}
+interface UseSyncActivity {
+  /** Queries inside a fetch cycle right now (core `fetchingQueryCount`). */
+  fetchingQueries: Accessor<number>;
+  /** Locally committed writes the server has not acknowledged yet. */
+  pendingMutations: Accessor<number>;
+  /** Fetching for longer than `downloadDelayMs`. Drives a "downloading" mark. */
+  isDownloading: Accessor<boolean>;
+  /** More than `uploadThreshold` writes queued. Drives an "uploading" mark. */
+  isUploading: Accessor<boolean>;
+}
+/**
+ * The two directions of sync traffic, for an indicator in the app chrome.
+ *
+ * `fetchingQueries` is one subscription on the engine's aggregate fetch count,
+ * not one per query; `pendingMutations` is the outbox depth. `isDownloading`
+ * is the fetch count debounced ON by `downloadDelayMs` (and off at once), so a
+ * local-first page that answers from cache and confirms with the server in a
+ * few milliseconds never flickers. Must be used within a `<Sp00kyProvider>`, or
+ * pass the `SyncedDb` explicitly.
+ */
+declare function useSyncActivity<S extends SchemaStructure = any>(dbOrOptions?: SyncedDb<S> | UseSyncActivityOptions, maybeOptions?: UseSyncActivityOptions): UseSyncActivity;
+//# sourceMappingURL=use-sync-activity.d.ts.map
+//#endregion
+//#region src/lib/use-storage-status.d.ts
+interface UseStorageStatus {
+  /** Full durability snapshot; updates reactively. */
+  health: Accessor<StorageHealth$1>;
+  /** `'unknown'` | `'persistent'` | `'memory'`. */
+  status: Accessor<StorageHealthStatus$1>;
+  /** `true` when the local store survives a reload. */
+  isPersistent: Accessor<boolean>;
+  /**
+   * `true` only when durable storage was requested and could NOT be opened, so
+   * the dataset is sitting in RAM and local writes die on reload. Drive a
+   * warning off this, not off `status`: a store configured as in-memory reports
+   * `'memory'` too, and that is a choice rather than a problem.
+   */
+  isMemoryFallback: Accessor<boolean>;
+}
+/**
+ * Observe how durable the LOCAL cache is, for a "no local storage" warning.
+ *
+ * Under `localEngine: 'sqlite'` with `store: 'indexeddb'` the durable store is
+ * the OPFS SAHPool VFS, and only ONE client per bucket can hold it open: a
+ * second tab of the same app cannot get it and runs in memory instead (the
+ * engine retries first, so a closing tab's lock is usually waited out). Must be
+ * used within a `<Sp00kyProvider>`.
+ */
+declare function useStorageStatus(): UseStorageStatus;
+//# sourceMappingURL=use-storage-status.d.ts.map
+//#endregion
+//#region src/lib/use-crdt-field.d.ts
+declare function useCrdtField(table: string, recordId: () => string | undefined, field: string, fallbackText?: () => string | undefined): Accessor<CrdtField | null>;
+//# sourceMappingURL=use-crdt-field.d.ts.map
+//#endregion
+//#region src/lib/use-feature-flag.d.ts
+interface UseFeatureFlag {
+  variant: Accessor<string | undefined>;
+  payload: Accessor<unknown | undefined>;
+  enabled: Accessor<boolean>;
+}
+/**
+ * Subscribe to a feature flag for the currently authenticated user.
+ *
+ * Returns three Solid accessors that update reactively whenever the
+ * server-materialized assignment in `_00_user_feature` changes. Backed by
+ * the same SSP + sync pipeline that powers `createQuery`, so toggling a flag
+ * via `spky flag enable <key>` propagates to the UI without a refresh.
+ *
+ * `enabled()` is `true` when the resolved variant exists and is not 'off'.
+ * For multi-variant flags, prefer `variant()` directly.
+ */
+declare function useFeatureFlag(key: string, options?: FeatureFlagOptions): UseFeatureFlag;
+//# sourceMappingURL=use-feature-flag.d.ts.map
+//#endregion
+//#region src/lib/use-app-release.d.ts
+interface UseAppReleaseOptions extends AppReleaseOptions {
+  /** App name from sp00ky.yml, e.g. `web`. */
+  app: string;
+  /**
+   * The running build's version (X.Y.Z), typically baked in at build time
+   * (e.g. a vite `define` from package.json). `updateAvailable()` is true when
+   * the announced release is semver-newer than this.
+   */
+  currentVersion: string;
+}
+interface UseAppRelease {
+  /** Latest announced version for the app, or undefined when no row exists. */
+  latestVersion: Accessor<string | undefined>;
+  /** Announced version is semver-newer than the running build. */
+  updateAvailable: Accessor<boolean>;
+  /** The newer release asks clients to update/reload without prompting. */
+  mandatory: Accessor<boolean>;
+  /** The newer release asks reloads to clear service-worker caches first. */
+  cacheBust: Accessor<boolean>;
+  /**
+   * Reload onto the announced release. Plain `location.reload()` normally;
+   * when the release is flagged cache-bust, CacheStorage is cleared, the
+   * service-worker registration is nudged to update, and navigation carries a
+   * `?cb=` token to punch through intermediary caches. The service worker is
+   * deliberately NOT unregistered: navigating while still controlled by a
+   * just-unregistered worker strands subresource fetches on the dead worker
+   * and the page hangs until a manual reload.
+   */
+  reload: () => Promise<void>;
+}
+/**
+ * Observe the app's announced release (`_00_app_release:<app>`, written by
+ * `spky deploy` / `spky release`) and compare it against the running build.
+ *
+ * Typical use: mount a small "new version available — Reload" notification
+ * gated on `updateAvailable()`, auto-invoking `reload()` when `mandatory()`
+ * (guard the auto path against reload loops with a per-version marker, since
+ * a client can reload while the deploy is still rolling out and land on the
+ * old bundle again).
+ */
+declare function useAppRelease(options: UseAppReleaseOptions): UseAppRelease;
+//# sourceMappingURL=use-app-release.d.ts.map
+//#endregion
+//#region src/lib/use-file-upload.d.ts
+interface FileUploadResult {
+  isUploading: () => boolean;
+  error: () => Error | null;
+  clearError: () => void;
+  upload: (path: string, file: File | Blob, options?: BucketPutOptions) => Promise<BucketPutResult | void>;
+  download: (path: string) => Promise<string | null>;
+  remove: (path: string) => Promise<void>;
+  exists: (path: string) => Promise<boolean>;
+}
+declare function useFileUpload<S extends SchemaStructure>(bucketName: BucketNames<S>): FileUploadResult;
+declare function useFileUpload<S extends SchemaStructure>(db: SyncedDb<S>, bucketName: BucketNames<S>): FileUploadResult;
+//# sourceMappingURL=use-file-upload.d.ts.map
+//#endregion
+//#region src/lib/use-download-file.d.ts
+interface UseDownloadFileOptions {
+  /**
+   * Master switch, default `true`. `false` gives every hook instance its own
+   * private object URL fetched fresh from the bucket and revoked on unmount —
+   * no sharing, no persistence, no reuse.
+   */
+  cache?: boolean;
+  /**
+   * Keep the bytes in OPFS so they survive a reload and are available offline.
+   * Default `true`. Turn off for one-shot or sensitive files; the in-tab object
+   * URL is still shared between components rendering the same path.
+   */
+  persist?: boolean;
+  /** Exempt this file from pressure eviction. Pinned bytes never expire. */
+  pin?: boolean;
+  /**
+   * `'never'` (default) treats a bucket path as immutable, which is how paths
+   * are written (`crypto.randomUUID() + ext`). `'head'` spends a remote `head()`
+   * to compare sizes before trusting the cached copy — for paths the app
+   * overwrites in place.
+   */
+  revalidate?: 'never' | 'head';
+}
+interface UseDownloadFileResult {
+  url: Accessor<string | null>;
+  isLoading: Accessor<boolean>;
+  error: Accessor<Error | null>;
+  refetch: () => void;
+}
+declare function useDownloadFile<S extends SchemaStructure>(bucketName: BucketNames<S>, path: Accessor<string | null | undefined>, options?: UseDownloadFileOptions): UseDownloadFileResult;
+declare function useDownloadFile<S extends SchemaStructure>(db: SyncedDb<S>, bucketName: BucketNames<S>, path: Accessor<string | null | undefined>, options?: UseDownloadFileOptions): UseDownloadFileResult;
+//# sourceMappingURL=use-download-file.d.ts.map
+//#endregion
+//#region src/lib/use-blurhash.d.ts
+interface UseBlurhashResult {
+  /** The stored blurhash for the path, or null while loading / when none exists. */
+  hash: Accessor<string | null>;
+  isLoading: Accessor<boolean>;
+}
+/**
+ * The blurhash sidecar for a bucket image (written automatically by
+ * `bucket.put`, see `Sp00kyConfig.blurhash`). Resolves from OPFS instantly on
+ * warm clients; a miss is remembered per tab. Use this directly when the hash
+ * belongs to a different rendition than the displayed image; otherwise
+ * `useBucketImage` / `BucketImage` bundle it with the download.
+ */
+declare function useBlurhash<S extends SchemaStructure>(bucketName: BucketNames<S>, path: Accessor<string | null | undefined>): UseBlurhashResult;
+declare function useBlurhash<S extends SchemaStructure>(db: SyncedDb<S>, bucketName: BucketNames<S>, path: Accessor<string | null | undefined>): UseBlurhashResult;
+//# sourceMappingURL=use-blurhash.d.ts.map
+//#endregion
+//#region src/lib/use-bucket-image.d.ts
+interface UseBucketImageOptions extends UseDownloadFileOptions {
+  /**
+   * Also resolve the image's blurhash sidecar (see `Sp00kyConfig.blurhash`).
+   * Default `true`; the read is registered before the image bytes so the tiny
+   * sidecar tends to land first on the serialized remote chain.
+   */
+  blurhash?: boolean;
+}
+interface UseBucketImageResult extends UseDownloadFileResult {
+  /** Blurhash for the same path, or null (off, missing, still loading). */
+  blurhash: Accessor<string | null>;
+  /** True once the current `url()` has been decoded and is safe to paint. */
+  ready: Accessor<boolean>;
+  /**
+   * Ref callback for the `<img>` rendering `url()`: flips `ready` when the
+   * bitmap is decoded (resolves on failure too, so a broken blob degrades to
+   * paint-on-load instead of hiding the image forever). Re-arms itself when
+   * the url changes.
+   */
+  gate: (img: HTMLImageElement) => void;
+}
+/**
+ * Everything needed to render a bucket image without a pop-in: the refcounted
+ * object URL, the blurhash placeholder, and a decode gate so the real bitmap
+ * is only revealed once it can paint in full. `BucketImage` wraps this into a
+ * drop-in component; use the hook for custom markup.
+ */
+declare function useBucketImage<S extends SchemaStructure>(bucketName: BucketNames<S>, path: Accessor<string | null | undefined>, options?: UseBucketImageOptions): UseBucketImageResult;
+declare function useBucketImage<S extends SchemaStructure>(db: SyncedDb<S>, bucketName: BucketNames<S>, path: Accessor<string | null | undefined>, options?: UseBucketImageOptions): UseBucketImageResult;
+//# sourceMappingURL=use-bucket-image.d.ts.map
+//#endregion
+//#region src/lib/Blurhash.d.ts
+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.
+ */
+declare function Blurhash(props: BlurhashProps): Element;
+//# sourceMappingURL=Blurhash.d.ts.map
+//#endregion
+//#region src/lib/BucketImage.d.ts
+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?: 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;
+}
+/**
+ * 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="" />
+ * ```
+ */
+declare function BucketImage(props: BucketImageProps): Element;
+//# sourceMappingURL=BucketImage.d.ts.map
+//#endregion
+//#region src/lib/Sp00kyProvider.d.ts
+interface Sp00kyProviderProps<S extends SchemaStructure> {
+  config: SyncedDbConfig<S>;
+  fallback?: 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: Element;
+}
+declare function Sp00kyProvider<S extends SchemaStructure>(props: Sp00kyProviderProps<S>): Element;
+//# sourceMappingURL=Sp00kyProvider.d.ts.map
+//#endregion
+//#region src/lib/context.d.ts
+declare function useDb<S extends SchemaStructure>(): SyncedDb<S>;
+/**
+ * Count of locally-committed mutations not yet acknowledged by the server.
+ * Drive an "unsaved changes" indicator off this.
+ */
+declare function usePendingMutations(): Accessor<number>;
+//# sourceMappingURL=context.d.ts.map
+//#endregion
+//#region src/lib/create-submission.d.ts
+interface Submission<Args extends unknown[], R> {
+  /** Run the wrapped async fn. Concurrent submits share the pending flag. */
+  submit: (...args: Args) => Promise<R | undefined>;
+  /** True while at least one submit is in flight. */
+  pending: Accessor<boolean>;
+  /** Error from the most recent settled submit, cleared on the next submit. */
+  error: Accessor<Error | undefined>;
+  /** Result of the most recent successful submit. */
+  result: Accessor<R | undefined>;
+  clearError: () => void;
+}
+/**
+ * Thin submission-state wrapper for mutations — button spinner/disable state
+ * around `db.create/update/delete/run` calls.
+ *
+ * Deliberately NOT built on Solid 2's `action()`/`createOptimisticStore`: the
+ * spooky engine is already optimistic local-first (writes commit to the local
+ * DB and re-render through live queries before sync; `run()` is an outbox
+ * CREATE), so a transaction/revert layer on top buys nothing and `action()`'s
+ * await-vs-yield transaction escape is a real footgun. Errors here mean the
+ * LOCAL commit failed — sync/push failures surface through `useSyncStatus`
+ * and `usePendingMutations` instead.
+ */
+declare function createSubmission<Args extends unknown[], R>(fn: (...args: Args) => Promise<R>): Submission<Args, R>;
+//# sourceMappingURL=create-submission.d.ts.map
+//#endregion
+//#region src/lib/conflate.d.ts
+/**
+ * Latest-wins async iterable over a subscribe-callback source.
+ *
+ * Bridges spooky's push-callback subscriptions into the AsyncIterable shape
+ * Solid 2 computations consume natively. Each spooky emission is a full result
+ * set, so intermediate values are droppable: only the newest unconsumed value
+ * is buffered, and a pending pull resolves with it immediately.
+ *
+ * Teardown contract (probed in rc-semantics.test.ts): Solid 2 does NOT
+ * terminate a superseded/disposed computation's async generator — no
+ * `return()`, no `finally`. Consumers MUST call `it.return()` themselves from
+ * an `onCleanup` registered synchronously in the compute scope. `return()`
+ * unsubscribes (awaiting the unsubscribe if the subscribe returned a promise,
+ * as `sp00ky.subscribe` does) and resolves any parked pull as done.
+ */
+declare function conflate<T>(subscribe: (cb: (v: T) => void) => (() => void) | Promise<() => void>): AsyncIterable<T>;
+//# sourceMappingURL=conflate.d.ts.map
+//#endregion
+//#region src/lib/from-subscription.d.ts
+/**
+ * Reactive view over a spooky subscribe-callback API.
+ *
+ * The memo's async generator pulls from a conflated (latest-wins) iterator;
+ * `initial` is committed as the memo's `loadingValue`, so the accessor is
+ * readable synchronously from birth and never suspends. Spooky's subscribe
+ * APIs fire immediately with the current value, so the real value lands within
+ * a tick of the first read.
+ *
+ * Teardown is manual by contract (see conflate.ts): onCleanup terminates the
+ * iterator, which unsubscribes.
+ */
+declare function fromSubscription<T>(subscribe: (cb: (v: T) => void) => (() => void) | Promise<() => void>, initial: T): Accessor<T>;
+//# sourceMappingURL=from-subscription.d.ts.map
+
+//#endregion
+//#region src/index.d.ts
+type RelationshipField<Schema extends SchemaStructure, TableName extends TableNames<Schema>, Field extends RelationshipFieldsFromSchema<Schema, TableName>> = GetRelationship<Schema, TableName, Field>;
+type RelatedFieldsTableScoped<Schema extends SchemaStructure, TableName extends TableNames<Schema>, RelatedFields extends RelationshipFieldsFromSchema<Schema, TableName> = RelationshipFieldsFromSchema<Schema, TableName>> = { [K in RelatedFields]: {
+  to: RelationshipField<Schema, TableName, K>['to'];
+  relatedFields: RelatedFieldsMap;
+  cardinality: RelationshipField<Schema, TableName, K>['cardinality'];
+} };
+type InferModel<Schema extends SchemaStructure, TableName extends TableNames<Schema>, RelatedFields extends RelatedFieldsTableScoped<Schema, TableName>> = QueryResult<Schema, TableName, RelatedFields, true>;
+type WithRelated<Field extends string, RelatedFields extends RelatedFieldsMap = {}> = { [K in Field]: Omit<RelatedFieldMapEntry, 'relatedFields'> & {
+  relatedFields: RelatedFields;
+} };
+type WithRelatedMany<Field extends string, RelatedFields extends RelatedFieldsMap = {}> = { [K in Field]: {
+  to: Field;
+  relatedFields: RelatedFields;
+  cardinality: 'many';
+} };
+declare class SyncedDb<S extends SchemaStructure> {
+  private config;
+  private sp00ky;
+  private _initialized;
+  constructor(config: SyncedDbConfig<S>);
+  getSp00ky(): Sp00kyClient<S>;
+  /**
+   * Initialize the sp00ky-ts instance
+   */
+  init(): Promise<void>;
+  /**
+   * 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.
+   */
+  close(): Promise<void>;
+  /**
+   * Create a new record in the database
+   */
+  create(id: string, payload: Record<string, unknown>): Promise<void>;
+  /**
+   * Update an existing record in the database
+   */
+  update<TName extends TableNames<S>>(tableName: TName, recordId: string, payload: Partial<TableModel<GetTable<S, TName>>>, options?: UpdateOptions): Promise<void>;
+  /**
+   * Delete an existing record in the database
+   */
+  delete<TName extends TableNames<S>>(tableName: TName, selector: string | RecordId | InnerQuery<GetTable<S, TName>, boolean>): Promise<void>;
+  /**
+   * 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 `createQuery` for the same data paints instantly. Best-effort.
+   */
+  preload(finalQuery: FinalQuery<S, any, any, any, any, Sp00kyQueryResultPromise>, options?: PreloadOptions$1): Promise<void>;
+  /**
+   * Query data from the database
+   */
+  query<TName extends TableNames<S>>(table: TName): QueryBuilder<S, TName, Sp00kyQueryResultPromise, {}, false>;
+  /**
+   * Run a backend operation
+   */
+  run<B extends BackendNames<S>, R extends BackendRoutes<S, B>>(backend: B, path: R, payload: RoutePayload<S, B, R>, options?: RunOptions): Promise<void>;
+  /**
+   * Sign out, clear session and local storage
+   */
+  signOut(): Promise<void>;
+  /**
+   * Execute a function with direct access to the remote database connection
+   */
+  useRemote<T>(fn: (db: Surreal) => T | Promise<T>): Promise<T>;
+  /**
+   * Access the remote database service directly
+   */
+  get remote(): Sp00kyClient<S>['remoteClient'];
+  /**
+   * Access the local database service directly
+   */
+  get local(): Sp00kyClient<S>['localClient'];
+  /**
+   * Access the auth service
+   */
+  get auth(): AuthService<S>;
+  get pendingMutationCount(): number;
+  /** Diagnostic — see `Sp00kyClient.liveRetryCount`. */
+  get liveRetryCount(): number;
+  subscribeToPendingMutations(cb: (count: number) => void): () => void;
+  /** Queries mid-fetch right now. See {@link useSyncActivity}. */
+  get fetchingQueryCount(): number;
+  /**
+   * Observe how many queries are fetching from the server. Fires immediately
+   * and on every change. Prefer the `useSyncActivity` hook in components.
+   */
+  subscribeToFetchActivity(cb: (fetching: number) => void): () => void;
+  /** Current sync-health snapshot. See {@link useSyncStatus}. */
+  get syncHealth(): SyncHealth$1;
+  /**
+   * 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$1) => void): () => void;
+  /** Current local-store durability snapshot. See {@link useStorageStatus}. */
+  get storageHealth(): StorageHealth$1;
+  /**
+   * 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$1) => void): () => void;
+  bucket<B extends BucketNames<S>>(name: B): BucketHandle;
+  getBucketConfig(name: string): BucketDefinitionSchema | undefined;
+}
+//#endregion
+export { Blurhash, type BlurhashProps, BucketImage, type BucketImageProps, CacheStrategy, type ConnectionState, type CreateQueryResult, type FileUploadResult, type GenericModel, type GenericSchema, type GetCardinality, type GetTable, InferModel, type InferRelatedModelFromMetadata, InferRelationshipsFromConst, InferSchemaFromConst, type Model, type ModelPayload, type PreloadOptions, type PreloadRefresh, ProvisionOptions, type QueryInfo, type QueryModifier, type QueryModifierBuilder, type QueryOptions, type QueryResult, type ReconnectConfig, RecordId, RelatedFieldsTableScoped, type RelationshipDefinition, RelationshipField, type RelationshipsMetadata, Sp00kyProvider, type Sp00kyProviderProps, type StorageHealth, type StorageHealthStatus, type Submission, type SyncHealth, type SyncHealthConfig, type SyncHealthStatus, SyncedDb, SyncedDbConfig, type TableModel, type TableNames, type UseAppRelease, type UseAppReleaseOptions, type UseBlurhashResult, type UseBucketImageOptions, type UseBucketImageResult, type UseDownloadFileOptions, type UseDownloadFileResult, type UseFeatureFlag, type UseStorageStatus, type UseSyncActivity, type UseSyncActivityOptions, type UseSyncStatus, Uuid, WithRelated, WithRelatedMany, conflate, createPreload, createQuery, createSubmission, fromSubscription, useAppRelease, useBlurhash, useBucketImage, useCrdtField, useDb, useDownloadFile, useFeatureFlag, useFileUpload, usePendingMutations, useQuery, useStorageStatus, useSyncActivity, useSyncStatus };
+//# sourceMappingURL=index.d.ts.map