@spooky-sync/core 0.0.1-canary.198 → 0.0.1-canary.199

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import * as surrealdb0 from "surrealdb";
 import { Duration, RecordId, Surreal as Surreal$1, SurrealEvents, SurrealTransaction } from "surrealdb";
 import { AccessDefinition, BackendNames, BackendRoutes, BucketNames, ColumnSchema, FinalQuery, GetTable, QueryBuilder, QueryOptions, QueryPlan, RoutePayload, SchemaStructure, TableModel, TableNames, TypeNameToTypeMap } from "@spooky-sync/query-builder";
 import { Logger } from "pino";
+import { decode, encode, isBlurhashValid } from "blurhash";
 import { LoroDoc } from "loro-crdt";
 
 //#region src/services/database/database.d.ts
@@ -2059,17 +2060,72 @@ declare class BlobCache {
   stats(): BlobCacheStats;
 }
 //#endregion
+//#region src/utils/blurhash.d.ts
+/**
+ * Blurhash generation settings. `true` enables with the defaults below, `false`
+ * disables. Resolution order for a put: per-call option > client config >
+ * default ON. See {@link Sp00kyConfig.blurhash}.
+ */
+type BlurhashSetting = boolean | BlurhashEncodeOptions;
+interface BlurhashEncodeOptions {
+  /** Horizontal detail components, 1-9. Defaults to 4. */
+  componentX?: number;
+  /** Vertical detail components, 1-9. Defaults to 3. */
+  componentY?: number;
+}
+/**
+ * Where an image's blurhash lives: a tiny sidecar object in the same bucket.
+ * Buckets have no per-object metadata channel (`put` is just `.put($content)`),
+ * so the hash for `covers/x_t.webp` is the text object `covers/x_t.webp.bh`.
+ */
+declare function blurhashSidecarPath(path: string): string;
+/** Extensions `bucket.put` treats as images worth hashing. */
+declare const BLURHASH_IMAGE_EXTENSIONS: readonly ["webp", "png", "jpg", "jpeg", "gif", "avif", "bmp"];
+declare function isImagePath(path: string): boolean;
+/**
+ * Decode `content` as an image and compute its blurhash. Browser-only: returns
+ * null (never throws) when image decoding is unavailable (node, workers without
+ * canvas), when the bytes are not a decodable image, or on any other failure —
+ * a missing hash must never break the upload that triggered it.
+ */
+declare function encodeImageToBlurhash(content: string | Uint8Array | Blob, options?: BlurhashEncodeOptions): Promise<string | null>;
+//#endregion
 //#region src/sp00ky.d.ts
 /** Coerce whatever the `.get()` RPC hands back into a Blob. */
 declare function bucketContentToBlob(content: unknown): Blob | null;
+interface BucketPutOptions {
+  /** Override the client-level {@link Sp00kyConfig.blurhash} setting for this put. */
+  blurhash?: BlurhashSetting;
+}
+interface BucketPutResult {
+  /** The computed blurhash when the content was a hashable image; else null. */
+  blurhash: string | null;
+}
+interface BucketHandleSettings {
+  blurhash?: BlurhashSetting;
+  logger?: {
+    warn: (obj: unknown, msg?: string) => void;
+  };
+}
 declare class BucketHandle {
   private bucketName;
   private remote;
   /** Absent on the raw handle the cache itself reads through. */
   private blobs?;
+  private settings?;
   constructor(bucketName: string, remote: RemoteDatabaseService, /** Absent on the raw handle the cache itself reads through. */
-  blobs?: (BlobCache | null) | undefined);
-  put(path: string, content: string | Uint8Array | Blob): Promise<void>;
+  blobs?: (BlobCache | null) | undefined, settings?: BucketHandleSettings | undefined);
+  /** Effective blurhash setting: per-call option > client config > default ON. */
+  private resolveBlurhash;
+  put(path: string, content: string | Uint8Array | Blob, options?: BucketPutOptions): Promise<BucketPutResult>;
+  /**
+   * The blurhash stored alongside an uploaded image (see
+   * {@link blurhashSidecarPath}), or null when there is none. Reads through the
+   * blob cache, so a warm client answers from OPFS without a network hop, and
+   * misses are remembered per tab so a hashless image costs at most one
+   * serialized remote read per session.
+   */
+  blurhash(path: string): Promise<string | null>;
   get(path: string): Promise<unknown>;
   /**
    * Read through the local blob cache: OPFS first, the bucket second. Unlike
@@ -2333,4 +2389,4 @@ declare function textToHtml(text: string): string;
  */
 
 //#endregion
-export { AppReleaseHandle, AppReleaseModule, type AppReleaseOptions, type AppReleaseSnapshot, AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, type BlobCacheStats, type BlobEntry, type BlobKey, type BlobReadOptions, type BlobUrlLease, BucketHandle, CURSOR_COLORS, ConnectionState, CrdtField, CrdtManager, DebounceOptions, EventSubscriptionOptions, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagOverride, type FeatureFlagSnapshot, Level, MATERIALIZATION_SAMPLE_WINDOW, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PhaseStat, PinoTransmit, PreloadOptions, PreloadRefresh, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, ReconnectConfig, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StorageHealth, StorageHealthStatus, StoreType, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, UpdateOptions, bucketContentToBlob, createAuthEventSystem, cursorColorFromName, fileToUint8Array, semverGt, textToHtml };
+export { AppReleaseHandle, AppReleaseModule, type AppReleaseOptions, type AppReleaseSnapshot, AuthEventSystem, AuthEventTypeMap, AuthEventTypes, AuthService, BLURHASH_IMAGE_EXTENSIONS, type BlobCacheStats, type BlobEntry, type BlobKey, type BlobReadOptions, type BlobUrlLease, type BlurhashEncodeOptions, type BlurhashSetting, BucketHandle, BucketPutOptions, BucketPutResult, CURSOR_COLORS, ConnectionState, CrdtField, CrdtManager, DebounceOptions, EventSubscriptionOptions, FeatureFlagHandle, FeatureFlagModule, type FeatureFlagOptions, type FeatureFlagOverride, type FeatureFlagSnapshot, Level, MATERIALIZATION_SAMPLE_WINDOW, MutationCallback, MutationEvent, MutationEventType, PersistenceClient, PhaseStat, PinoTransmit, PreloadOptions, PreloadRefresh, QueryConfig, QueryConfigRecord, QueryHash, QueryState, QueryStatus, QueryStatusCallback, QueryTimeToLive, QueryTimings, QueryUpdateCallback, ReconnectConfig, RecordVersionArray, RecordVersionDiff, RegistrationTimings, RunOptions, Sp00kyClient, Sp00kyConfig, Sp00kyQueryResult, Sp00kyQueryResultPromise, StorageHealth, StorageHealthStatus, StoreType, SyncHealth, SyncHealthConfig, SyncHealthStatus, TimingPhase, UpdateOptions, blurhashSidecarPath, bucketContentToBlob, createAuthEventSystem, cursorColorFromName, decode as decodeBlurhash, encode as encodeBlurhash, encodeImageToBlurhash, fileToUint8Array, isBlurhashValid, isImagePath, semverGt, textToHtml };

package/dist/index.js

@@ -4,6 +4,7 @@ import { QueryBuilder, RecordId as RecordId$1, cyrb53 } from "@spooky-sync/query
 import pino from "pino";
 import { applyPatch } from "fast-json-patch";
 import init, { Sp00kyProcessor } from "@spooky-sync/ssp-wasm";
+import { decode, encode, isBlurhashValid } from "blurhash";
 
 //#region src/types.ts
 /** Cap on the rolling materialization-sample window kept per query in memory. */
@@ -7092,8 +7093,8 @@ function selfAllowlistedVariant(flag, userId) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.198";
-const WASM_VERSION = "0.0.1-canary.198";
+const CORE_VERSION = "0.0.1-canary.199";
+const WASM_VERSION = "0.0.1-canary.199";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	eventsHistory = [];
@@ -11222,6 +11223,65 @@ function createBlobCache(opts) {
 	});
 }
 
+//#endregion
+//#region src/utils/blurhash.ts
+/**
+* Where an image's blurhash lives: a tiny sidecar object in the same bucket.
+* Buckets have no per-object metadata channel (`put` is just `.put($content)`),
+* so the hash for `covers/x_t.webp` is the text object `covers/x_t.webp.bh`.
+*/
+function blurhashSidecarPath(path) {
+	return `${path}.bh`;
+}
+/** Extensions `bucket.put` treats as images worth hashing. */
+const BLURHASH_IMAGE_EXTENSIONS = [
+	"webp",
+	"png",
+	"jpg",
+	"jpeg",
+	"gif",
+	"avif",
+	"bmp"
+];
+const IMAGE_EXT_RE = new RegExp(`\\.(${BLURHASH_IMAGE_EXTENSIONS.join("|")})$`, "i");
+function isImagePath(path) {
+	return IMAGE_EXT_RE.test(path);
+}
+/** Longest edge of the downscale the hash is computed from. Blurhash carries at
+*  most 9x9 DCT components, so anything past ~32px is wasted decode work. */
+const ENCODE_MAX_EDGE = 32;
+/**
+* Decode `content` as an image and compute its blurhash. Browser-only: returns
+* null (never throws) when image decoding is unavailable (node, workers without
+* canvas), when the bytes are not a decodable image, or on any other failure —
+* a missing hash must never break the upload that triggered it.
+*/
+async function encodeImageToBlurhash(content, options) {
+	if (typeof createImageBitmap !== "function") return null;
+	let bitmap = null;
+	try {
+		const blob = content instanceof Blob ? content : new Blob([content]);
+		bitmap = await createImageBitmap(blob);
+		const scale = Math.min(1, ENCODE_MAX_EDGE / Math.max(bitmap.width, bitmap.height));
+		const width = Math.max(1, Math.round(bitmap.width * scale));
+		const height = Math.max(1, Math.round(bitmap.height * scale));
+		const canvas = typeof OffscreenCanvas !== "undefined" ? new OffscreenCanvas(width, height) : typeof document !== "undefined" ? Object.assign(document.createElement("canvas"), {
+			width,
+			height
+		}) : null;
+		if (!canvas) return null;
+		const ctx = canvas.getContext("2d");
+		if (!ctx) return null;
+		ctx.drawImage(bitmap, 0, 0, width, height);
+		const { data } = ctx.getImageData(0, 0, width, height);
+		return encode(data, width, height, options?.componentX ?? 4, options?.componentY ?? 3);
+	} catch {
+		return null;
+	} finally {
+		bitmap?.close();
+	}
+}
+
 //#endregion
 //#region src/sp00ky.ts
 /** Coerce whatever the `.get()` RPC hands back into a Blob. */
@@ -11233,18 +11293,85 @@ function bucketContentToBlob(content) {
 	if (ArrayBuffer.isView(content)) return new Blob([content]);
 	return null;
 }
+/**
+* Paths known to have no blurhash sidecar, per tab. The blob cache has no
+* negative caching, so without this every mount of a hashless image would pay
+* one serialized remote read. Cleared when a put writes a sidecar or a delete
+* removes the image. Keyed `${bucket}:${path}` (the image path, not the sidecar).
+*/
+const missingBlurhash = /* @__PURE__ */ new Set();
 var BucketHandle = class {
-	constructor(bucketName, remote, blobs) {
+	constructor(bucketName, remote, blobs, settings) {
 		this.bucketName = bucketName;
 		this.remote = remote;
 		this.blobs = blobs;
+		this.settings = settings;
 	}
-	async put(path, content) {
+	/** Effective blurhash setting: per-call option > client config > default ON. */
+	resolveBlurhash(option) {
+		const setting = option ?? this.settings?.blurhash ?? true;
+		if (setting === false) return null;
+		return setting === true ? {} : setting;
+	}
+	async put(path, content, options) {
+		const encodeOptions = this.resolveBlurhash(options?.blurhash);
+		const hashPromise = encodeOptions && isImagePath(path) ? encodeImageToBlurhash(content, encodeOptions) : Promise.resolve(null);
 		await this.remote.query(`RETURN f"${this.bucketName}:/${path}".put($content);`, { content });
 		await this.blobs?.invalidate({
 			bucket: this.bucketName,
 			path
 		});
+		let hash = null;
+		try {
+			hash = await hashPromise;
+			if (hash) {
+				const sidecar = blurhashSidecarPath(path);
+				await this.remote.query(`RETURN f"${this.bucketName}:/${sidecar}".put($content);`, { content: hash });
+				await this.blobs?.invalidate({
+					bucket: this.bucketName,
+					path: sidecar
+				});
+				missingBlurhash.delete(`${this.bucketName}:${path}`);
+			}
+		} catch (error) {
+			hash = null;
+			this.settings?.logger?.warn({
+				error,
+				path
+			}, "blurhash sidecar put failed");
+		}
+		return { blurhash: hash };
+	}
+	/**
+	* The blurhash stored alongside an uploaded image (see
+	* {@link blurhashSidecarPath}), or null when there is none. Reads through the
+	* blob cache, so a warm client answers from OPFS without a network hop, and
+	* misses are remembered per tab so a hashless image costs at most one
+	* serialized remote read per session.
+	*/
+	async blurhash(path) {
+		const cacheKey = `${this.bucketName}:${path}`;
+		if (missingBlurhash.has(cacheKey)) return null;
+		try {
+			const blob = await this.read(blurhashSidecarPath(path), { persist: true });
+			if (!blob) {
+				missingBlurhash.add(cacheKey);
+				return null;
+			}
+			const hash = (await blob.text()).trim();
+			if (!isBlurhashValid(hash).result) {
+				this.settings?.logger?.warn({ path }, "blurhash sidecar holds an invalid hash");
+				missingBlurhash.add(cacheKey);
+				return null;
+			}
+			return hash;
+		} catch (error) {
+			this.settings?.logger?.warn({
+				error,
+				path
+			}, "blurhash sidecar read failed");
+			return null;
+		}
 	}
 	async get(path) {
 		const [result] = await this.remote.query(`RETURN f"${this.bucketName}:/${path}".get();`);
@@ -11307,6 +11434,17 @@ var BucketHandle = class {
 			bucket: this.bucketName,
 			path
 		});
+		if (isImagePath(path)) {
+			const sidecar = blurhashSidecarPath(path);
+			try {
+				await this.remote.query(`RETURN f"${this.bucketName}:/${sidecar}".delete();`);
+				await this.blobs?.invalidate({
+					bucket: this.bucketName,
+					path: sidecar
+				});
+			} catch {}
+			missingBlurhash.delete(`${this.bucketName}:${path}`);
+		}
 	}
 	async exists(path) {
 		const [result] = await this.remote.query(`RETURN f"${this.bucketName}:/${path}".exists();`);
@@ -11524,7 +11662,7 @@ var Sp00kyClient = class {
 		return new TabsCoordinator({
 			tabId,
 			fingerprint: computeTabsFingerprint({
-				coreVersion: "0.0.1-canary.198",
+				coreVersion: "0.0.1-canary.199",
 				schemaHash: hash53(this.config.schemaSurql),
 				endpoint: this.config.database.endpoint ?? "",
 				namespace: this.config.database.namespace,
@@ -12074,12 +12212,18 @@ var Sp00kyClient = class {
 		return this.dataModule.run(backend, path, payload, options);
 	}
 	bucket(name) {
-		return new BucketHandle(name, this.remote, this.blobs);
+		return new BucketHandle(name, this.remote, this.blobs, {
+			blurhash: this.config.blurhash,
+			logger: this.logger
+		});
 	}
 	/** Cache-free handle. The blob cache reads the remote through this, so a
 	*  cache miss can't loop back into the cache. */
 	rawBucket(name) {
-		return new BucketHandle(name, this.remote, null);
+		return new BucketHandle(name, this.remote, null, {
+			blurhash: this.config.blurhash,
+			logger: this.logger
+		});
 	}
 	/** Blob cache counters for DevTools. */
 	getBlobCacheStats() {
@@ -12118,4 +12262,4 @@ var Sp00kyClient = class {
 };
 
 //#endregion
-export { AppReleaseHandle, AppReleaseModule, AuthEventTypes, AuthService, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, FeatureFlagHandle, FeatureFlagModule, MATERIALIZATION_SAMPLE_WINDOW, Sp00kyClient, bucketContentToBlob, createAuthEventSystem, cursorColorFromName, fileToUint8Array, semverGt, textToHtml };
+export { AppReleaseHandle, AppReleaseModule, AuthEventTypes, AuthService, BLURHASH_IMAGE_EXTENSIONS, BucketHandle, CURSOR_COLORS, CrdtField, CrdtManager, FeatureFlagHandle, FeatureFlagModule, MATERIALIZATION_SAMPLE_WINDOW, Sp00kyClient, blurhashSidecarPath, bucketContentToBlob, createAuthEventSystem, cursorColorFromName, decode as decodeBlurhash, encode as encodeBlurhash, encodeImageToBlurhash, fileToUint8Array, isBlurhashValid, isImagePath, semverGt, textToHtml };

package/dist/types.d.ts

@@ -629,6 +629,22 @@ interface Sp00kyConfig<S extends SchemaStructure> {
    * (or `degradeAfterConsecutiveFailures: 0`) to never report degraded.
    */
   syncHealth?: SyncHealthConfig | false;
+  /**
+   * Automatic blurhash placeholders for bucket image uploads. On every
+   * `bucket.put` of an image path (by extension: webp/png/jpg/jpeg/gif/avif/bmp)
+   * the client computes a blurhash and stores it as a tiny sidecar object
+   * `<path>.bh` in the same bucket, best-effort. Read it back with
+   * `bucket.blurhash(path)` (or the client-solid `useBucketImage`/`BucketImage`
+   * helpers) to paint a placeholder until the image is decoded.
+   *
+   * `true` (the default) enables with 4x3 components; pass
+   * `{ componentX, componentY }` to tune detail, or `false` to disable.
+   * A per-call `put(path, content, { blurhash })` option overrides this.
+   */
+  blurhash?: boolean | {
+    componentX?: number;
+    componentY?: number;
+  };
   /**
    * Deadline (ms) for a single outgoing mutation push. Tighter than
    * {@link Sp00kyConfig.database.queryTimeoutMs} because the up-queue drains

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.198",
+  "version": "0.0.1-canary.199",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -60,10 +60,11 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.198",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.198",
+    "@spooky-sync/query-builder": "0.0.1-canary.199",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.199",
     "@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",

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/index.ts

@@ -24,3 +24,14 @@ export type {
 } from './services/blobs/index';
 export { semverGt } from './utils/semver';
 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/sp00ky.ts

@@ -62,6 +62,15 @@ import type { SqliteCacheEngine } from './services/database/sqlite-cache-engine'
 import type { BlobCache, BlobReadOptions, BlobUrlLease } from './services/blobs/index';
 import { MemoryBlobStore, createBlobCache, resolveBlobBudget } from './services/blobs/index';
 
+import {
+  blurhashSidecarPath,
+  encodeImageToBlurhash,
+  isImagePath,
+  isBlurhashValid,
+  type BlurhashSetting,
+  type BlurhashEncodeOptions,
+} from './utils/blurhash';
+
 /** Coerce whatever the `.get()` RPC hands back into a Blob. */
 export function bucketContentToBlob(content: unknown): Blob | null {
   if (content == null) return null;
@@ -74,18 +83,110 @@ export function bucketContentToBlob(content: unknown): Blob | null {
   return null;
 }
 
+export interface BucketPutOptions {
+  /** Override the client-level {@link Sp00kyConfig.blurhash} setting for this put. */
+  blurhash?: BlurhashSetting;
+}
+
+export interface BucketPutResult {
+  /** The computed blurhash when the content was a hashable image; else null. */
+  blurhash: string | null;
+}
+
+interface BucketHandleSettings {
+  blurhash?: BlurhashSetting;
+  logger?: { warn: (obj: unknown, msg?: string) => void };
+}
+
+/**
+ * Paths known to have no blurhash sidecar, per tab. The blob cache has no
+ * negative caching, so without this every mount of a hashless image would pay
+ * one serialized remote read. Cleared when a put writes a sidecar or a delete
+ * removes the image. Keyed `${bucket}:${path}` (the image path, not the sidecar).
+ */
+const missingBlurhash = new Set<string>();
+
 export class BucketHandle {
   constructor(
     private bucketName: string,
     private remote: RemoteDatabaseService,
     /** Absent on the raw handle the cache itself reads through. */
-    private blobs?: BlobCache | null
+    private blobs?: BlobCache | null,
+    private settings?: BucketHandleSettings
   ) {}
 
-  async put(path: string, content: string | Uint8Array | Blob): Promise<void> {
+  /** Effective blurhash setting: per-call option > client config > default ON. */
+  private resolveBlurhash(option?: BlurhashSetting): BlurhashEncodeOptions | null {
+    const setting = option ?? this.settings?.blurhash ?? true;
+    if (setting === false) return null;
+    return setting === true ? {} : setting;
+  }
+
+  async put(
+    path: string,
+    content: string | Uint8Array | Blob,
+    options?: BucketPutOptions
+  ): Promise<BucketPutResult> {
+    // Start hashing while the upload is in flight; both browser-side costs
+    // overlap and the sidecar put only queues once the main put resolved.
+    const encodeOptions = this.resolveBlurhash(options?.blurhash);
+    const hashPromise =
+      encodeOptions && isImagePath(path)
+        ? encodeImageToBlurhash(content, encodeOptions)
+        : Promise.resolve(null);
+
     await this.remote.query(`RETURN f"${this.bucketName}:/${path}".put($content);`, { content });
     // A path can be overwritten, so anything cached under it is now wrong.
     await this.blobs?.invalidate({ bucket: this.bucketName, path });
+
+    // The sidecar is best-effort: a hash or sidecar failure must never fail
+    // the image put that triggered it.
+    let hash: string | null = null;
+    try {
+      hash = await hashPromise;
+      if (hash) {
+        const sidecar = blurhashSidecarPath(path);
+        await this.remote.query(`RETURN f"${this.bucketName}:/${sidecar}".put($content);`, {
+          content: hash,
+        });
+        await this.blobs?.invalidate({ bucket: this.bucketName, path: sidecar });
+        missingBlurhash.delete(`${this.bucketName}:${path}`);
+      }
+    } catch (error) {
+      hash = null;
+      this.settings?.logger?.warn({ error, path }, 'blurhash sidecar put failed');
+    }
+    return { blurhash: hash };
+  }
+
+  /**
+   * The blurhash stored alongside an uploaded image (see
+   * {@link blurhashSidecarPath}), or null when there is none. Reads through the
+   * blob cache, so a warm client answers from OPFS without a network hop, and
+   * misses are remembered per tab so a hashless image costs at most one
+   * serialized remote read per session.
+   */
+  async blurhash(path: string): Promise<string | null> {
+    const cacheKey = `${this.bucketName}:${path}`;
+    if (missingBlurhash.has(cacheKey)) return null;
+    try {
+      const blob = await this.read(blurhashSidecarPath(path), { persist: true });
+      if (!blob) {
+        missingBlurhash.add(cacheKey);
+        return null;
+      }
+      const hash = (await blob.text()).trim();
+      if (!isBlurhashValid(hash).result) {
+        this.settings?.logger?.warn({ path }, 'blurhash sidecar holds an invalid hash');
+        missingBlurhash.add(cacheKey);
+        return null;
+      }
+      return hash;
+    } catch (error) {
+      // Transient failure: do NOT negative-cache, the next mount may succeed.
+      this.settings?.logger?.warn({ error, path }, 'blurhash sidecar read failed');
+      return null;
+    }
   }
 
   async get(path: string): Promise<unknown> {
@@ -137,6 +238,18 @@ export class BucketHandle {
   async delete(path: string): Promise<void> {
     await this.remote.query(`RETURN f"${this.bucketName}:/${path}".delete();`);
     await this.blobs?.invalidate({ bucket: this.bucketName, path });
+    // Symmetry with put: an image's blurhash sidecar dies with it. Best-effort,
+    // the sidecar may simply not exist.
+    if (isImagePath(path)) {
+      const sidecar = blurhashSidecarPath(path);
+      try {
+        await this.remote.query(`RETURN f"${this.bucketName}:/${sidecar}".delete();`);
+        await this.blobs?.invalidate({ bucket: this.bucketName, path: sidecar });
+      } catch {
+        // Nothing to clean up.
+      }
+      missingBlurhash.delete(`${this.bucketName}:${path}`);
+    }
   }
 
   async exists(path: string): Promise<boolean> {
@@ -1373,13 +1486,19 @@ export class Sp00kyClient<S extends SchemaStructure> {
   }
 
   bucket<B extends BucketNames<S>>(name: B): BucketHandle {
-    return new BucketHandle(name, this.remote, this.blobs);
+    return new BucketHandle(name, this.remote, this.blobs, {
+      blurhash: this.config.blurhash,
+      logger: this.logger,
+    });
   }
 
   /** Cache-free handle. The blob cache reads the remote through this, so a
    *  cache miss can't loop back into the cache. */
   private rawBucket(name: string): BucketHandle {
-    return new BucketHandle(name, this.remote, null);
+    return new BucketHandle(name, this.remote, null, {
+      blurhash: this.config.blurhash,
+      logger: this.logger,
+    });
   }
 
   /** Blob cache counters for DevTools. */

package/src/types.ts

@@ -296,6 +296,19 @@ export interface Sp00kyConfig<S extends SchemaStructure> {
    * (or `degradeAfterConsecutiveFailures: 0`) to never report degraded.
    */
   syncHealth?: SyncHealthConfig | false;
+  /**
+   * Automatic blurhash placeholders for bucket image uploads. On every
+   * `bucket.put` of an image path (by extension: webp/png/jpg/jpeg/gif/avif/bmp)
+   * the client computes a blurhash and stores it as a tiny sidecar object
+   * `<path>.bh` in the same bucket, best-effort. Read it back with
+   * `bucket.blurhash(path)` (or the client-solid `useBucketImage`/`BucketImage`
+   * helpers) to paint a placeholder until the image is decoded.
+   *
+   * `true` (the default) enables with 4x3 components; pass
+   * `{ componentX, componentY }` to tune detail, or `false` to disable.
+   * A per-call `put(path, content, { blurhash })` option overrides this.
+   */
+  blurhash?: boolean | { componentX?: number; componentY?: number };
   /**
    * Deadline (ms) for a single outgoing mutation push. Tighter than
    * {@link Sp00kyConfig.database.queryTimeoutMs} because the up-queue drains

package/src/utils/blurhash.ts

@@ -0,0 +1,90 @@
+import { encode, decode, isBlurhashValid } from 'blurhash';
+
+export { encode as encodeBlurhash, decode as decodeBlurhash, isBlurhashValid };
+
+/**
+ * Blurhash generation settings. `true` enables with the defaults below, `false`
+ * disables. Resolution order for a put: per-call option > client config >
+ * default ON. See {@link Sp00kyConfig.blurhash}.
+ */
+export type BlurhashSetting = boolean | BlurhashEncodeOptions;
+
+export interface BlurhashEncodeOptions {
+  /** Horizontal detail components, 1-9. Defaults to 4. */
+  componentX?: number;
+  /** Vertical detail components, 1-9. Defaults to 3. */
+  componentY?: number;
+}
+
+/**
+ * Where an image's blurhash lives: a tiny sidecar object in the same bucket.
+ * Buckets have no per-object metadata channel (`put` is just `.put($content)`),
+ * so the hash for `covers/x_t.webp` is the text object `covers/x_t.webp.bh`.
+ */
+export function blurhashSidecarPath(path: string): string {
+  return `${path}.bh`;
+}
+
+/** Extensions `bucket.put` treats as images worth hashing. */
+export const BLURHASH_IMAGE_EXTENSIONS = [
+  'webp',
+  'png',
+  'jpg',
+  'jpeg',
+  'gif',
+  'avif',
+  'bmp',
+] as const;
+
+const IMAGE_EXT_RE = new RegExp(`\\.(${BLURHASH_IMAGE_EXTENSIONS.join('|')})$`, 'i');
+
+export function isImagePath(path: string): boolean {
+  return IMAGE_EXT_RE.test(path);
+}
+
+/** Longest edge of the downscale the hash is computed from. Blurhash carries at
+ *  most 9x9 DCT components, so anything past ~32px is wasted decode work. */
+const ENCODE_MAX_EDGE = 32;
+
+/**
+ * Decode `content` as an image and compute its blurhash. Browser-only: returns
+ * null (never throws) when image decoding is unavailable (node, workers without
+ * canvas), when the bytes are not a decodable image, or on any other failure —
+ * a missing hash must never break the upload that triggered it.
+ */
+export async function encodeImageToBlurhash(
+  content: string | Uint8Array | Blob,
+  options?: BlurhashEncodeOptions
+): Promise<string | null> {
+  if (typeof createImageBitmap !== 'function') return null;
+  let bitmap: ImageBitmap | null = null;
+  try {
+    const blob =
+      content instanceof Blob
+        ? content
+        : new Blob([content as unknown as BlobPart]);
+    bitmap = await createImageBitmap(blob);
+    const scale = Math.min(1, ENCODE_MAX_EDGE / Math.max(bitmap.width, bitmap.height));
+    const width = Math.max(1, Math.round(bitmap.width * scale));
+    const height = Math.max(1, Math.round(bitmap.height * scale));
+    const canvas =
+      typeof OffscreenCanvas !== 'undefined'
+        ? new OffscreenCanvas(width, height)
+        : typeof document !== 'undefined'
+          ? Object.assign(document.createElement('canvas'), { width, height })
+          : null;
+    if (!canvas) return null;
+    const ctx = canvas.getContext('2d') as
+      | OffscreenCanvasRenderingContext2D
+      | CanvasRenderingContext2D
+      | null;
+    if (!ctx) return null;
+    ctx.drawImage(bitmap, 0, 0, width, height);
+    const { data } = ctx.getImageData(0, 0, width, height);
+    return encode(data, width, height, options?.componentX ?? 4, options?.componentY ?? 3);
+  } catch {
+    return null;
+  } finally {
+    bitmap?.close();
+  }
+}