@syncular/client 0.0.6-96 → 0.1.0

package/README.md

@@ -1,23 +1,725 @@
 # @syncular/client
 
-Client-side sync engine for Syncular with offline-first support: local outbox, incremental push/pull, conflict detection, subscriptions/scopes, and optional blobs/plugins.
+Rust-owned SQLite browser client for Syncular.
 
-## Install
+This package is the TypeScript host binding over the Rust client. The browser
+runtime is a dedicated Worker that owns the Rust WASM module and SQLite handle.
+TypeScript keeps Kysely as the type-safe query builder; generated app code
+supplies the DB type, schema installer, mutation helpers, subscriptions, and
+runtime assertions.
+
+## Generated App Entry
+
+Configure Rust codegen to emit your browser helper into your app package:
+
+```json
+{
+  "typescriptOutputPath": "src/generated/syncular.browser.ts",
+  "typescriptRuntimeImportPath": "@syncular/client",
+  "tables": {
+    "profiles": {
+      "serverVersionColumn": "server_version",
+      "blobColumns": ["avatar"]
+    }
+  }
+}
+```
+
+App code imports the generated helper, not a table-specific API from this
+package:
+
+```ts
+import { createSyncularAppDatabase } from './generated/syncular.browser';
+
+const syncular = await createSyncularAppDatabase({
+  config: {
+    baseUrl: '/sync',
+    actorId: 'user-1',
+    clientId: 'client-1',
+    projectId: 'project-1',
+    fileName: 'app.sqlite',
+  },
+  requestTimeoutMs: 30_000,
+  getHeaders: async () => ({
+    authorization: `Bearer ${await auth.currentAccessToken()}`,
+  }),
+  authLifecycle: {
+    refreshToken: () => auth.refreshAccessToken(),
+  },
+});
+
+const rows = await syncular.db
+  .selectFrom('tasks')
+  .select(['id', 'title'])
+  .where('project_id', '=', 'project-1')
+  .execute();
+
+await syncular.mutations.tasks.insert({
+  title: 'Typed Rust-owned write',
+  completed: 0,
+  user_id: 'user-1',
+  project_id: 'project-1',
+});
+
+await syncular.client.issueAuthLease({
+  schemaVersion: 1,
+  scopes: [
+    {
+      subscriptionId: 'tasks:user-1',
+      table: 'tasks',
+      values: { user_id: 'user-1' },
+      operations: ['upsert'],
+    },
+  ],
+});
+
+await syncular.leasedMutations.tasks.update('task-1', {
+  title: 'Queued while offline',
+});
+
+// Local mutations sync automatically by default. To opt out, pass:
+// sync: { autoSyncAfterMutation: false }
+
+const live = await syncular.live(
+  syncular.db
+    .selectFrom('tasks')
+    .select(['id', 'title'])
+    .where('project_id', '=', 'project-1'),
+  {
+    onChange(rows) {
+      console.log(rows);
+    },
+  }
+);
+
+live.unsubscribe();
+await syncular.close();
+```
+
+Generated helpers intentionally do not emit table constants, column constants,
+or canned queries. Reads stay plain Kysely. Sync-aware writes go through
+`syncular.mutations` or generated operation helpers.
+
+Use `bootstrapPhases` when the app should become usable before every
+subscription has finished its first snapshot. Keys can be generated table names
+or subscription ids. Phase `0` is critical by default, phase `1` is
+interactive by default, and higher phases continue in the background:
+
+```ts
+const syncular = await createSyncularAppDatabase({
+  config: {
+    baseUrl: '/sync',
+    actorId: 'user-1',
+    clientId: 'client-1',
+    pull: {
+      criticalBootstrapPhase: 0,
+      interactiveBootstrapPhase: 1,
+    },
+  },
+  bootstrapPhases: {
+    projects: 0,
+    tasks: 1,
+    comments: 2,
+  },
+});
+
+const result = await syncular.client.syncOnce();
+
+if (result.bootstrap.criticalReady) {
+  renderShell();
+}
+
+const unsubscribeBootstrap = syncular.client.addEventListener(
+  'bootstrapChanged',
+  (bootstrap) => {
+    if (bootstrap.interactiveReady) enableMainViews();
+    if (bootstrap.complete) enableFullDataViews();
+  }
+);
+```
+
+Do not treat missing scopes as empty data while `bootstrap.complete` is false.
+Use `bootstrap.pendingSubscriptionIds`, `bootstrap.phases`, or generated
+subscription ids to decide which views can render complete results.
+
+The database owns the sync lifecycle. `createSyncularDatabase` registers
+subscriptions, runs the initial sync, starts realtime, schedules reconnect
+catchup, and coordinates shutdown through `close()`:
+
+```ts
+import { createSyncularDatabase } from '@syncular/client';
+
+const syncular = await createSyncularDatabase<AppDb>({
+  config: {
+    baseUrl: '/sync',
+    actorId: 'user-1',
+    clientId: 'client-1',
+  },
+  subscriptions: [
+    {
+      id: 'tasks:user-1',
+      table: 'tasks',
+      scopes: { user_id: 'user-1' },
+    },
+  ],
+});
+
+const unsubscribe = syncular.on('rowsChanged', (event) => {
+  console.log(event.changedTables);
+});
+
+const status = syncular.getStatus();
+if (status.hasPendingMutations) showSavingIndicator();
+
+await syncular.resumeFromBackground();
+await syncular.close();
+```
+
+The database starts realtime by default. Pass `realtime: false` only for a
+host policy that cannot hold a websocket, and `lifecycle: { autoStart: false }`
+to open without starting sync at all. Interval polling is still off by
+default: websocket reconnects trigger HTTP catchup sync, and failed
+websocket binary sync-pack applies recover through HTTP pull. Use
+`pollIntervalMs` only for environments that explicitly need polling.
+
+## React
+
+React apps can import the `@syncular/client/react` subpath.
+The adapter owns the Rust browser client lifecycle when passed `options`, or
+can wrap an already-created managed client:
+
+```ts
+import { createSyncularReact } from '@syncular/client/react';
+
+const {
+  SyncProvider,
+  useSyncQuery,
+  useMutations,
+  useLeasedMutations,
+  useMutation,
+  useOutboxStats,
+  usePresenceWithJoin,
+  useSyncConnection,
+} = createSyncularReact<AppDb>();
+
+function AppShell({ children }: { children: React.ReactNode }) {
+  return (
+    <SyncProvider
+      options={{
+        config: {
+          baseUrl: '/sync',
+          actorId: 'user-1',
+          clientId: 'client-1',
+        },
+        subscriptions: [
+          {
+            id: 'tasks:user-1',
+            table: 'tasks',
+            scopes: { user_id: 'user-1' },
+          },
+        ],
+        realtime: true,
+      }}
+    >
+      {children}
+    </SyncProvider>
+  );
+}
+
+function TaskList() {
+  const { data: tasks } = useSyncQuery(
+    ({ selectFrom }) =>
+      selectFrom('tasks')
+        .select(['id', 'title'])
+        .where('user_id', '=', 'user-1'),
+    {
+      tables: ['tasks'],
+      deps: ['user-1'],
+    }
+  );
+
+  const presence = usePresenceWithJoin('user:user-1', {
+    metadata: { view: 'tasks' },
+  });
+
+  const m = useMutations();
+  const leased = useLeasedMutations();
+  const createTask = (title: string) =>
+    m.tasks.insert({
+      title,
+      completed: 0,
+      user_id: 'user-1',
+    });
+
+  const completeTask = useMutation({ table: 'tasks' });
+  const markDone = (id: string) =>
+    completeTask.mutate.update(id, { completed: 1 });
+
+  const renameOffline = (id: string, title: string) =>
+    leased.tasks.update(id, { title });
+
+  const connection = useSyncConnection();
+  const outbox = useOutboxStats();
+}
+```
+
+The React entrypoint is intentionally ergonomic and Rust-backed: reads use typed
+Kysely selectors through `useSyncQuery`, writes use generated mutations through
+`useMutations` / `useLeasedMutations` or table-scoped
+`useMutation` / `useLeasedMutation`, and presence stays scoped to server scope
+keys. When the query is a Kysely builder, `useSyncQuery` uses the runtime
+live-query observer; promise-only queries fall back to conservative row-change
+refresh. `SyncProvider` does not recreate an owned client just because an inline
+`options` object changed identity; pass `optionsKey` when the app intentionally
+needs to tear down and reopen the Rust client for a new identity or database.
+
+Generated apps also get typed row-delta helpers for realtime/UI routing. The
+runtime event stays generic, while app code can branch on real table columns:
+
+```ts
+import { syncularChangedRows } from './generated/syncular.browser';
+
+const unsubscribe = syncular.on('rowsChanged', (event) => {
+  for (const task of syncularChangedRows.tasks(event)) {
+    if (task.isDelete) {
+      removeTaskFromList(task.rowId);
+      continue;
+    }
+    if (task.changed.title || task.changed.completed) {
+      refreshTaskRow(task.rowId);
+    }
+    if (task.crdt.title_yjs_state) {
+      refreshActiveEditorState(task.rowId);
+    }
+  }
+});
+```
+
+The returned `syncular.db` is a read/query-builder surface. Public SQL execution
+rejects app-table and internal-table writes, including Kysely `insertInto`,
+`updateTable`, `deleteFrom`, schema DDL, and raw mutating SQL. This prevents
+local rows from bypassing Syncular's outbox, conflict, encryption, blob, and
+realtime semantics. Generated app setup uses an internal schema-write path
+before the database handle is returned; application writes should use
+`syncular.mutations`.
+
+Mutations schedule `client.syncOnce()` automatically after a successful local
+commit. The scheduler coalesces repeated writes with a short debounce and queues
+one follow-up sync if another mutation lands while sync is already running:
+
+```ts
+const syncular = await createSyncularAppDatabase({
+  config: {
+    baseUrl: '/sync',
+    actorId: 'user-1',
+    clientId: 'client-1',
+  },
+  sync: {
+    autoSyncAfterMutation: true, // default
+    mutationSyncDebounceMs: 25,
+    rowsChangedDebounceMs: 16,
+    autoProcessBlobUploadsAfterStore: false, // default
+    blobUploadDebounceMs: 25,
+  },
+});
+```
+
+Set `autoSyncAfterMutation: false` when an app wants to batch its own sync
+cycles explicitly. Set `autoProcessBlobUploadsAfterStore: true` when the
+browser should process queued blob uploads after `blobs.store()` with the same
+debounce/backpressure model. It is disabled by default so mobile/background
+hosts can choose when network blob work is allowed.
+
+## Blobs
+
+Blobs are a sidecar API on the same Rust-owned SQLite client. App data still
+uses typed Kysely queries; binary payloads are content-addressed and staged in
+Syncular internal blob tables:
+
+```ts
+const avatar = await syncular.blobs.store(file, {
+  mimeType: file.type,
+});
+
+await syncular.mutations.profiles.upsert(userId, {
+  avatar,
+});
+
+await syncular.blobs.processUploadQueue();
+
+const bytes = await syncular.blobs.retrieve(avatar);
+```
+
+`store()` hashes and caches bytes in Rust/WASM SQLite, then queues upload unless
+`immediate: true` is passed. Upload/download requests use the same auth header
+lifecycle as sync and talk to the server blob routes under `${baseUrl}/blobs`.
+Apps can call `processUploadQueue()` manually or opt into
+`sync.autoProcessBlobUploadsAfterStore`.
+Columns listed in `blobColumns` are typed as `BlobRef` in generated Kysely
+types and use generated codecs so SQLite stores JSON text while app code reads
+and writes structured blob refs.
+
+## Auth
+
+App code owns authentication. Pass `getHeaders` to the generated app database
+factory when sync requests need bearer tokens, session headers, or tenant
+headers:
+
+```ts
+const syncular = await createSyncularAppDatabase({
+  config: {
+    baseUrl: '/sync',
+    actorId: 'user-1',
+    clientId: 'client-1',
+  },
+  getHeaders: async () => ({
+    authorization: `Bearer ${await auth.currentAccessToken()}`,
+  }),
+});
+```
+
+The Worker refreshes those headers after opening and before `syncPull`,
+`syncPush`, and `syncOnce`, then forwards them into Rust. The `actorId` config
+is used for sync identity and generated default scopes; it is not sent as an
+implicit auth credential.
+If Rust reports HTTP 401/403 during sync, `authLifecycle` can refresh
+credentials and the Worker retries that sync operation once with fresh headers.
+
+Offline auth leases are explicit. They capture bounded local intent and audit
+provenance, but the server still rechecks current authorization when queued
+commits replay:
+
+```ts
+await syncular.client.issueAuthLease({
+  schemaVersion: 1,
+  scopes: [
+    {
+      subscriptionId: 'tasks:user-1',
+      table: 'tasks',
+      values: { user_id: 'user-1' },
+      operations: ['upsert', 'delete'],
+    },
+  ],
+});
+
+const active = await syncular.client.activeAuthLeases('user-1');
+await syncular.leasedMutations.tasks.update('task-1', {
+  title: 'Offline edit',
+});
+```
+
+Use normal `syncular.mutations` unless the app intentionally needs lease-backed
+offline writes.
+
+## Platform Bridges
+
+`@syncular/client/tauri` and `@syncular/client/react-native` expose TypeScript
+host bindings over a native Rust runtime. They are bridge adapters, not separate
+JavaScript sync clients:
+
+```ts
+import { createSyncularTauriClient } from '@syncular/client/tauri';
+
+const client = await createSyncularTauriClient<AppDb>({
+  invoke,
+  listen,
+});
+
+const rows = await client.db.selectFrom('tasks').selectAll().execute();
+await client.leasedMutations.tasks.update('task-1', { title: 'Offline edit' });
+await client.resumeFromBackground();
+```
+
+Bridge subpaths preserve row/field metadata on `rowsChanged` events and expose
+the same leased mutation, auth lease, lifecycle, presence, conflict, and blob
+client shape where the native module provides those commands. They do not
+pretend to support live-query registration by rerunning table-level events; app
+bridges can either use row/field metadata directly or wait for a native
+observed-query stream. Command history remains generated-client owned, not a
+generic bridge-level JavaScript undo stack.
+
+## Diagnostics
+
+Pass `diagnostics` to observe structured client, worker, auth, realtime,
+storage, sync, and blob events. Header values and websocket URLs are not emitted.
+
+```ts
+const syncular = await createSyncularAppDatabase({
+  config: {
+    baseUrl: '/sync',
+    actorId: 'user-1',
+    clientId: 'client-1',
+  },
+  diagnostics(event) {
+    logger.debug(event.code, event);
+  },
+});
+```
+
+`requestTimeoutMs` is enforced in the Worker. For long sync/blob requests the
+Worker also aborts the Rust-owned browser fetches, including snapshot chunk
+downloads, before dropping the timed-out response.
+
+UI code can poll `syncular.client.connectionState()` for a cheap snapshot of the
+Worker state: closed flag, pending request count, realtime connection state,
+storage fallback, and the latest diagnostic/error.
+
+## Realtime
+
+Realtime is optional and runs inside the same dedicated Worker as Rust-owned
+SQLite. Enable it with `realtime`:
+
+```ts
+const syncular = await createSyncularAppDatabase({
+  config: {
+    baseUrl: '/sync',
+    actorId: 'user-1',
+    clientId: 'client-1',
+  },
+  realtime: true,
+});
+```
+
+The Worker connects to `${baseUrl}/realtime`, listens for server `sync`
+wakeups, runs `syncPull()` in Rust, then emits affected live-query snapshots to
+JS listeners. Browser WebSockets cannot send custom headers; use same-origin
+cookie auth when possible, or pass non-sensitive server-supported params:
+
+```ts
+await createSyncularAppDatabase({
+  config: {
+    baseUrl: '/sync',
+    actorId: 'user-1',
+    clientId: 'client-1',
+  },
+  realtime: {
+    wsUrl: 'wss://api.example.com/sync/realtime',
+    getParams: async () => ({ token: await auth.realtimeToken() }),
+  },
+});
+```
+
+Realtime also carries presence. Scope keys match the sync scope keys exposed by
+the server, for example `user:user-1` for a `user:{user_id}` handler scope:
+
+```ts
+const unsubscribePresence = syncular.client.addPresenceListener((event) => {
+  renderCollaborators(event.scopeKey, event.presence);
+});
+
+syncular.client.joinPresence('user:user-1', {
+  editingTaskId: 'task-1',
+});
+
+syncular.client.updatePresenceMetadata('user:user-1', {
+  editingTaskId: 'task-2',
+});
+
+const currentPresence = syncular.client.getPresence('user:user-1');
+renderCollaborators('user:user-1', currentPresence);
+
+syncular.client.leavePresence('user:user-1');
+unsubscribePresence();
+```
+
+`getPresence(scopeKey)` returns the latest in-memory snapshot for that scope.
+The server authorizes presence against the websocket connection's current
+subscriptions, so call `syncular.client.setSubscriptions()` and complete an
+initial sync before joining presence.
+
+Operational events are available on the same client surface:
+
+```ts
+syncular.client.addEventListener('outboxChanged', (stats) => {
+  updateSyncBadge(stats.pending + stats.sending);
+});
+
+syncular.client.addEventListener('conflictsChanged', (stats) => {
+  showConflictCount(stats.unresolved);
+});
+
+syncular.client.addEventListener('blobUploadFailed', ({ hash, error }) => {
+  reportBlobUploadFailure(hash, error);
+});
+```
+
+Browser event names intentionally use the Rust-native vocabulary shared with
+native event payloads: `rowsChanged`, `outboxChanged`, `conflictsChanged`,
+`presenceChanged`, `blobUploadCompleted`, and `blobUploadFailed`.
+
+## Runtime Contract
+
+The default API always uses a Worker. `createSyncularAppDatabase()` validates
+the runtime before returning:
+
+- package name/version must match `@syncular/client`
+- Worker protocol version must match the generated helper
+- generated app schema version must match the local SQLite schema state
+- Rust runtime must include the generated schema's required feature list
+
+`client.runtimeInfo()` exposes the package identity, Worker protocol, resolved
+storage mode, fallback details, Worker/WASM asset URLs, Rust crate version,
+generated schema version, and Rust feature list.
+
+Generated clients emit `syncularGeneratedRequiredRuntimeFeatures` from schema
+metadata. A basic app only needs `web-owned-sqlite-core`; apps using blob
+columns, CRDT/Yjs, or field encryption add `blobs`, `crdt-yjs`, and/or `e2ee`.
+`createSyncularAppDatabase()` passes those requirements into the Worker open
+path automatically.
+
+## Storage
+
+Omitting `config.storage` defaults to `opfsSahPool`. If that default OPFS open
+fails because the browser cannot create the sync access handle, the Worker
+client retries with `indexedDb` and reports the fallback via
+`runtimeInfo().storageFallback`.
+
+Explicit storage is never silently changed:
+
+```ts
+await createSyncularAppDatabase({
+  config: {
+    baseUrl: '/sync',
+    actorId: 'user-1',
+    clientId: 'client-1',
+    storage: 'indexedDb',
+  },
+});
+```
+
+`client.compactStorage()` performs bounded local cleanup in Rust-owned SQLite:
+acked outbox commits and resolved conflicts by age, optional failed blob upload
+rows and inactive subscription state by age, blob cache pruning by byte budget,
+and tombstones only when the caller supplies `maxTombstoneServerVersion`.
+
+```ts
+await syncular.client.compactStorage({
+  olderThanMs: 7 * 24 * 60 * 60 * 1000,
+  maxBlobCacheBytes: 256 * 1024 * 1024,
+  pruneFailedBlobUploads: true,
+  maxTombstoneServerVersion: lastServerVersionKnownSafeToDrop,
+});
+```
+
+Tombstone cleanup is intentionally not enabled by age alone; deleting
+soft-deleted app rows before the server/version contract says they are safe can
+break later sync repair.
+
+## CRDT Document Fields
+
+Generated app clients expose schema-derived CRDT field helpers, and the
+low-level client exposes generic `openCrdtField`, `applyCrdtFieldYjsUpdate`,
+`materializeCrdtField`, `snapshotCrdtFieldStateVector`, and `compactCrdtField`
+methods. Keep editor-specific code above this package: TipTap schemas,
+ProseMirror transforms, Excalidraw save policy, selection, undo, and WebView
+messages belong in app code or optional app adapters.
+
+Use `@syncular/client/crdt-yjs` for app-layer editor glue above this
+package. It connects Yjs binary update streams to Syncular's durable CRDT field
+API, preserves pending updates across failed writes, exposes backpressure,
+prefers queued native host writes when available, and refreshes app view models
+from materialized Syncular state after changed-row events.
+
+For rich editors, keep Yjs as the canonical field state. ProseMirror JSON,
+title, preview, outline, search text, and similar values are projections that
+apps should rebuild after a CRDT changed-row event, remote apply, or compaction.
+The Rust-owned client persists a compact binary Yjs state and state vector per
+document field, plus an append-only binary Yjs update log with `pending`,
+`flushed`, and `acked` status. Use `crdtDocumentSnapshot` to inspect the
+current compacted state/vector and queue counts, `crdtUpdateLog` for adapter
+diagnostics, and `compactStorage({ olderThanMs, pruneCrdtUpdateLog: true })` to
+prune old acked log entries without touching the canonical compact state.
+
+## Assets
+
+The `@syncular/client` package writes the full Rust WASM artifact to
+`dist/wasm`:
+
+- `syncular.js`
+- `syncular_bg.wasm`
+- `syncular-runtime-artifact.json`
+
+It also writes the core artifact to `dist/wasm-core` and the ordered catalog to
+`dist/syncular-runtime-artifacts.json`.
+
+The default Worker resolves those assets relative to the package runtime.
+Generated app code can select from that catalog without changing the public
+query/mutation API:
+
+```ts
+import { resolveSyncularRuntimeArtifactCatalog } from '@syncular/client';
+
+const catalogUrl = '/syncular/syncular-runtime-artifacts.json';
+const catalog = await fetch(catalogUrl).then((response) => response.json());
+
+await createSyncularAppDatabase({
+  config,
+  runtimeArtifacts: resolveSyncularRuntimeArtifactCatalog(catalog, {
+    baseUrl: catalogUrl,
+  }),
+});
+```
+
+The first artifact containing every generated required feature is used. Custom
+asset serving can still pass a custom `worker`; the lower-level direct Rust
+client accepts advanced `runtime`, `module`, `wasmGlueUrl`, and `wasmUrl`
+options. Normal generated app code should not need those lower-level paths.
+
+Release WASM builds run a size budget check after `wasm-opt -Oz` and custom
+section stripping. The current checked budgets are `3.25 MiB` raw and
+`1.35 MiB` gzip. Override them only for an intentional release-size decision:
 
 ```bash
-npm install @syncular/client
+SYNCULAR_WASM_RAW_BUDGET_BYTES=3407872 \
+SYNCULAR_WASM_GZIP_BUDGET_BYTES=1415578 \
+  bun --cwd packages/client run size:wasm:check
 ```
 
-## Documentation
+The check writes an attribution report to
+`.context/wasm-size/syncular-wasm-size.txt` when run through
+`packages/client` `build:wasm` or `size:wasm:check`. Release builds
+also write a non-shipping optimized profile WASM to
+`.context/wasm-size/syncular_bg.profile.wasm` before final custom section
+stripping so attribution can keep symbol names when available.
+
+The current browser client is the canonical Rust-owned SQLite runtime wrapper
+for generated clients. The no-CRDT/no-E2EE core binding artifact has measured
+byte savings; the current core artifact also omits blob upload/cache helpers.
+The client package `build` runs `build:wasm:variants`, which writes both
+artifacts plus the catalog, and generated loading can select the smallest
+matching artifact when an app serves the catalog. Publishing separate wrapper
+packages around the same WASM would not remove bytes.
+
+For local measurement or app experiments:
+
+```bash
+bun --cwd packages/client run build:wasm:core
+bun --cwd packages/client run build:wasm:variants
+bun --cwd packages/client run catalog:wasm
+bun --cwd packages/client run size:wasm:core
+```
 
-- Client setup: https://syncular.dev/docs/build/client-setup
-- Subscriptions (partial sync): https://syncular.dev/docs/introduction/subscriptions
-- Commits & conflicts: https://syncular.dev/docs/introduction/commits
+`build:wasm:core` writes `dist/wasm-core/syncular.js` and
+`dist/wasm-core/syncular_bg.wasm` with `web-owned-sqlite-core` only. That
+artifact does not include blob, CRDT/Yjs, or E2EE support. `catalog:wasm`
+combines `dist/wasm-core/syncular-runtime-artifact.json` and
+`dist/wasm/syncular-runtime-artifact.json` into the top-level
+`dist/syncular-runtime-artifacts.json` catalog.
 
-## Links
+## Package Scripts
 
-- GitHub: https://github.com/syncular/syncular
-- Issues: https://github.com/syncular/syncular/issues
+```bash
+bun run build
+bun run test
+bun run test:wasm:auth
+bun run test:wasm:hono
+bun run test:wasm:variants
+```
 
-> Status: Alpha. APIs and storage layouts may change between releases.
+`test:wasm:hono` builds the dev WASM artifact and runs the Hono-backed browser
+smokes for auth retry, sync protocol edge cases, realtime wakeups, and blob
+transport behavior.
 
+`packages/client` `build:wasm`, `size:wasm:check`, and the conformance
+gates are the current browser runtime validation path. The old JS/wa-sqlite
+comparison benchmark was removed with the legacy TypeScript client runtime.