@pylonsync/react 0.22.47 → 0.22.50

package/dist/db.d.ts

@@ -1,4 +1,5 @@
 import { SyncEngine, type Row, type SyncEngineConfig } from "@pylonsync/sync";
+import { type QueuedUploadHandle, type QueueUploadOptions } from "./offlineUploads";
 import { type QueryOptions, type UseQueryReturn, type UseQueryOneReturn, type UseReactiveQueryReturn, type UseMutationReturn, type UseInfiniteQueryReturn, type AggregateSpec, type UseAggregateReturn, type SearchSpec, type UseSearchReturn } from "./hooks";
 import { type UploadedFile, type UploadFileOptions } from "./index";
 /**
@@ -174,6 +175,9 @@ export declare const db: {
     streamFn(name: string, args?: Record<string, unknown>): AsyncGenerator<string, unknown, unknown>;
     /** Upload a file through /api/files/init, a PUT, and /api/files/confirm. */
     uploadFile(input: File | Blob | ArrayBuffer | Uint8Array, options?: UploadFileOptions): Promise<UploadedFile>;
+    /** Keep a file on the device and upload it when there is a network,
+     *  then set it on its record. See `queueUpload`. */
+    queueUpload(file: Blob, options: QueueUploadOptions): Promise<QueuedUploadHandle>;
     /** @deprecated Use `uploadFile`; extra fields were never stored. */
     uploadFileMultipart(file: File | Blob, fields?: Record<string, string>): Promise<UploadedFile>;
 };

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export type { ImageResponseOptions, ImageResponseFont, } from "./image-response"
 export type { PageProps, PageAuth, ServerData, SsrResponse, SsrCookieOptions, Metadata, GenerateMetadata, Sitemap, SitemapEntry, Robots, RobotsRule, LlmsTxt, LlmsSection, LlmsLink, RouteSegmentConfig, ErrorBoundaryProps, NotFoundProps, FormFields, FormDb, FormRequest, RouteHandler, RawRouteHandler, RawResponse, } from "./ssr";
 export { useRouter, useSearchParams, usePathname, useParams, useRouteSeed, useRouteData, redirect, notFound, NotFoundError, } from "./useRouter";
 export type { PylonRouter } from "./useRouter";
-import { type Storage as PylonStorage, type TransportConfig } from "@pylonsync/sync";
+import { type Storage as PylonStorage, type TransportConfig, type FileVisibility, type UploadBytesOptions, type UploadedFile } from "@pylonsync/sync";
 export { useQuery, useQueryOne, useReactiveQuery, useMutation, useInfiniteQuery, usePaginatedQuery, useEntityMutation, useAction, useQueryRaw, useQueryOneRaw, useLiveList, useLiveRow, useInsert, useUpdate, useDelete, useFn, useAggregate, useSearch, } from "./hooks";
 export type { QueryOptions, QueryFilter, IncludeSpec, UseQueryReturn, UseQueryOneReturn, UseReactiveQueryReturn, UseMutationReturn, UseInfiniteQueryReturn, UsePaginatedQueryReturn, PaginatedQueryStatus, UseFnReturn, AggregateSpec, UseAggregateReturn, SearchSpec, UseSearchReturn, } from "./hooks";
 export { useAgentRun } from "./useAgentRun";
@@ -32,6 +32,13 @@ export { useSession } from "./useSession";
 export type { UseSessionReturn, ResolvedSession } from "./useSession";
 export { useSyncStatus } from "./useSyncStatus";
 export type { SyncConnectionStatus } from "./useSyncStatus";
+export { useOutbox } from "./useOutbox";
+export type { UseOutboxReturn, Outbox, OutboxItem } from "./useOutbox";
+export { queueUpload, useFileUrl } from "./offlineUploads";
+export type { QueueUploadOptions, QueuedUploadHandle, UploadAttachTarget } from "./offlineUploads";
+export { UploadQueueFullError, UploadRejectedError } from "@pylonsync/sync";
+export { registerOfflineWorker } from "./offlineWorker";
+export type { OfflineWorkerOptions } from "./offlineWorker";
 export { db, init, getSync, setSessionToken } from "./db";
 export { createTypedDb } from "./typed";
 export type { TypedDb, AgentDBSchema } from "./typed";
@@ -254,27 +261,9 @@ export declare function listFns(): Promise<{
     name: string;
     fn_type: "query" | "mutation" | "action";
 }[]>;
-export interface UploadedFile {
-    id: string;
-    /** Where to read the file. Store this on your row. */
-    url: string;
-    size: number;
-}
-/**
- * Who can read an uploaded file through `url`.
- *   - "private" (default): only the uploader.
- *   - "public": anyone, signed in or not. Use it for content every visitor
- *     sees, such as feed photos or listing images.
- * Writes and deletes stay with the uploader either way. On a CDN-backed
- * store (Stack0, a public bucket) every file is served by its URL, so the
- * setting only changes reads that go through `/api/files/<id>`.
- */
-export type FileVisibility = "private" | "public";
-export interface UploadFileOptions {
-    filename?: string;
-    contentType?: string;
+export type { UploadedFile, FileVisibility } from "@pylonsync/sync";
+export interface UploadFileOptions extends UploadBytesOptions {
     token?: string;
-    visibility?: FileVisibility;
 }
 /**
  * Upload a file (File, Blob, or raw bytes) in three steps:
@@ -287,6 +276,9 @@ export interface UploadFileOptions {
  * signature is the credential. The session is never sent to a presigned
  * URL on another origin.
  *
+ * All three steps need the network. For a file taken where there may be
+ * none (a photo in the field), use `queueUpload`.
+ *
  * @example
  * ```ts
  * const photo = await uploadFile(fileFromInput, { visibility: "public" });

package/dist/offlineUploads.d.ts

@@ -0,0 +1,45 @@
+import { type FileVisibility, type QueuedUploadHandle, type SyncEngine, type UploadAttachTarget } from "@pylonsync/sync";
+export type { QueuedUploadHandle, UploadAttachTarget };
+export interface QueueUploadOptions {
+    /** The record the file belongs to, and the field that gets its id
+     *  (and `urlField`, its URL). */
+    attach: UploadAttachTarget;
+    filename?: string;
+    contentType?: string;
+    visibility?: FileVisibility;
+    /** Defaults to the engine `init()` set up. */
+    engine?: SyncEngine;
+}
+/**
+ * Keep a file on the device and upload it when there is a network, then
+ * set it on its record. Returns at once, also with no network.
+ *
+ * At once the record's `attach.field` (and `attach.urlField`) holds
+ * `local:<localId>`; read it with `useFileUrl` to show the photo from the
+ * device. When the upload finishes, the field gets the file id and
+ * `urlField` the file URL. Both changes are ordinary queued writes.
+ *
+ * ```ts
+ * const photoId = await db.insert("Photo", { leadId, fileId: null, url: null });
+ * await queueUpload(file, {
+ *   attach: { entity: "Photo", id: photoId, field: "fileId", urlField: "url" },
+ * });
+ * ```
+ *
+ * Pending and failed uploads are in `useOutbox()` with kind `"upload"`.
+ * Throws `UploadQueueFullError` when the queue already holds
+ * `maxQueuedUploadBytes` (200 MB by default).
+ */
+export declare function queueUpload(file: Blob, options: QueueUploadOptions): Promise<QueuedUploadHandle>;
+/**
+ * The URL to show for a file field: the value itself, or, for a
+ * `local:<localId>` value from `queueUpload`, an object URL of the copy on
+ * this device. Null for an empty value, and for a `local:` value this
+ * device does not hold (another device queued it, or it was dismissed).
+ *
+ * ```tsx
+ * const src = useFileUrl(photo.url);
+ * return src ? <img src={src} /> : <Placeholder />;
+ * ```
+ */
+export declare function useFileUrl(value: string | null | undefined, engine?: SyncEngine): string | null;

package/dist/offlineWorker.d.ts

@@ -0,0 +1,50 @@
+export interface OfflineWorkerOptions {
+    /** The app set `buildManifest({ offline })`. */
+    optedIn: boolean;
+    /** Not `pylon dev`. */
+    production: boolean;
+    /** Whether a user is signed in on this page. The worker refetches the
+     *  pages it keeps when this changes, because each one carries the
+     *  signed-in bit. */
+    signedIn?: boolean;
+    /** Defaults to the global `navigator`. */
+    navigator?: {
+        serviceWorker?: ServiceWorkerContainerLike;
+    };
+    /** Resolves when the page has loaded, so the worker's downloads do not
+     *  compete with the page's own. Defaults to the window `load` event. */
+    whenLoaded?: () => Promise<void>;
+}
+/** The parts of `ServiceWorkerContainer` this module uses. */
+export interface ServiceWorkerContainerLike {
+    register(url: string, options?: {
+        scope?: string;
+    }): Promise<unknown>;
+    getRegistrations?(): Promise<ReadonlyArray<RegistrationLike>>;
+    ready?: Promise<{
+        active?: {
+            postMessage(message: unknown): void;
+        } | null;
+    }>;
+}
+interface RegistrationLike {
+    active?: {
+        scriptURL: string;
+    } | null;
+    waiting?: {
+        scriptURL: string;
+    } | null;
+    installing?: {
+        scriptURL: string;
+    } | null;
+    unregister(): Promise<boolean>;
+}
+/**
+ * Register the worker when the app opted in and this is a production page.
+ * Otherwise remove a Pylon worker an earlier build left on this origin (an
+ * app that turned offline off, or `pylon dev` after `pylon start`). Workers
+ * the app registered itself are left alone. Never throws: an app works
+ * online without its worker.
+ */
+export declare function registerOfflineWorker(opts: OfflineWorkerOptions): Promise<unknown | null>;
+export {};

package/dist/useOutbox.d.ts

@@ -0,0 +1,45 @@
+import { type Outbox, type OutboxItem, type Row, type SyncEngine } from "@pylonsync/sync";
+export type { Outbox, OutboxItem };
+export interface UseOutboxReturn {
+    /** Writes the server has not applied yet: made offline, or waiting
+     *  for a sign-in. Oldest first. */
+    pending: OutboxItem[];
+    /** Writes the server rejected, with `error` and `errorCode`. Oldest
+     *  first. Each stays until it is retried or dismissed. */
+    failed: OutboxItem[];
+    /** Send a failed write again, with `data` merged over its fields.
+     *  Resolves once the server applies it or it is queued offline;
+     *  rejects with a `MutationRejectedError` when the server rejects it
+     *  again or another user is signed in. */
+    retry: (id: string, data?: Row) => Promise<string>;
+    /** Drop a failed write. */
+    dismiss: (id: string) => boolean;
+}
+/**
+ * The writes on this device that are not on the server: pending writes
+ * (offline, or waiting for a sign-in) and failed writes (the server
+ * rejected them). Re-renders when a write is queued, applied, rejected,
+ * retried or dismissed.
+ *
+ * ```tsx
+ * function Outbox() {
+ *   const { pending, failed, retry, dismiss } = useOutbox();
+ *   return (
+ *     <>
+ *       {pending.length > 0 && <p>{pending.length} not synced</p>}
+ *       {failed.map((w) => (
+ *         <div key={w.id}>
+ *           {w.entity}: {w.error}
+ *           <button onClick={() => retry(w.id)}>Retry</button>
+ *           <button onClick={() => dismiss(w.id)}>Dismiss</button>
+ *         </div>
+ *       ))}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * Pass an explicit `engine` if your app uses a non-default sync
+ * instance; otherwise the hook reads the singleton wired up by `init()`.
+ */
+export declare function useOutbox(engine?: SyncEngine): UseOutboxReturn;

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.22.47",
+  "version": "0.22.50",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",
@@ -14,9 +14,9 @@
     "prepack": "bun run build"
   },
   "dependencies": {
-    "@pylonsync/realtime": "0.22.47",
-    "@pylonsync/sdk": "0.22.47",
-    "@pylonsync/sync": "0.22.47"
+    "@pylonsync/realtime": "0.22.50",
+    "@pylonsync/sdk": "0.22.50",
+    "@pylonsync/sync": "0.22.50"
   },
   "peerDependencies": {
     "react": ">=19.0.0"

package/src/db.ts

@@ -2,6 +2,11 @@
 
 import { SyncEngine, createSyncEngine, type Row, type SyncEngineConfig } from "@pylonsync/sync";
 import { setActiveEngine } from "./engine-registry";
+import {
+  queueUpload,
+  type QueuedUploadHandle,
+  type QueueUploadOptions,
+} from "./offlineUploads";
 import {
   useQuery as useQueryHook,
   useQueryOne as useQueryOneHook,
@@ -340,6 +345,12 @@ export const db = {
     return uploadFile(input, options);
   },
 
+  /** Keep a file on the device and upload it when there is a network,
+   *  then set it on its record. See `queueUpload`. */
+  queueUpload(file: Blob, options: QueueUploadOptions): Promise<QueuedUploadHandle> {
+    return queueUpload(file, options);
+  },
+
   /** @deprecated Use `uploadFile`; extra fields were never stored. */
   uploadFileMultipart(
     file: File | Blob,

package/src/index.ts

@@ -75,8 +75,12 @@ import {
   pylonFetch,
   pylonFetchRaw,
   PylonHttpError,
+  uploadBytes,
   type Storage as PylonStorage,
   type TransportConfig,
+  type FileVisibility,
+  type UploadBytesOptions,
+  type UploadedFile,
 } from "@pylonsync/sync";
 import { peekActiveEngine } from "./engine-registry";
 
@@ -187,6 +191,20 @@ export type { UseSessionReturn, ResolvedSession } from "./useSession";
 export { useSyncStatus } from "./useSyncStatus";
 export type { SyncConnectionStatus } from "./useSyncStatus";
 
+// Writes not yet on the server, and writes the server rejected.
+export { useOutbox } from "./useOutbox";
+export type { UseOutboxReturn, Outbox, OutboxItem } from "./useOutbox";
+
+// Files kept on the device and uploaded when there is a network.
+export { queueUpload, useFileUrl } from "./offlineUploads";
+export type { QueueUploadOptions, QueuedUploadHandle, UploadAttachTarget } from "./offlineUploads";
+export { UploadQueueFullError, UploadRejectedError } from "@pylonsync/sync";
+
+// Offline service worker registration. The SSR client runtime calls it on
+// every page load; apps opt in with `buildManifest({ offline })`.
+export { registerOfflineWorker } from "./offlineWorker";
+export type { OfflineWorkerOptions } from "./offlineWorker";
+
 // One-liner API
 export { db, init, getSync, setSessionToken } from "./db";
 
@@ -952,29 +970,10 @@ export async function listFns(): Promise<
 // File upload
 // ---------------------------------------------------------------------------
 
-export interface UploadedFile {
-  id: string;
-  /** Where to read the file. Store this on your row. */
-  url: string;
-  size: number;
-}
-
-/**
- * Who can read an uploaded file through `url`.
- *   - "private" (default): only the uploader.
- *   - "public": anyone, signed in or not. Use it for content every visitor
- *     sees, such as feed photos or listing images.
- * Writes and deletes stay with the uploader either way. On a CDN-backed
- * store (Stack0, a public bucket) every file is served by its URL, so the
- * setting only changes reads that go through `/api/files/<id>`.
- */
-export type FileVisibility = "private" | "public";
+export type { UploadedFile, FileVisibility } from "@pylonsync/sync";
 
-export interface UploadFileOptions {
-  filename?: string;
-  contentType?: string;
+export interface UploadFileOptions extends UploadBytesOptions {
   token?: string;
-  visibility?: FileVisibility;
 }
 
 /**
@@ -988,6 +987,9 @@ export interface UploadFileOptions {
  * signature is the credential. The session is never sent to a presigned
  * URL on another origin.
  *
+ * All three steps need the network. For a file taken where there may be
+ * none (a photo in the field), use `queueUpload`.
+ *
  * @example
  * ```ts
  * const photo = await uploadFile(fileFromInput, { visibility: "public" });
@@ -998,87 +1000,8 @@ export async function uploadFile(
   input: File | Blob | ArrayBuffer | Uint8Array,
   options: UploadFileOptions = {}
 ): Promise<UploadedFile> {
-  let body: BodyInit;
-  let size: number;
-  let filename = options.filename;
-  let contentType = options.contentType;
-
-  if (typeof File !== "undefined" && input instanceof File) {
-    body = input;
-    size = input.size;
-    filename ??= input.name;
-    contentType ??= input.type || "application/octet-stream";
-  } else if (typeof Blob !== "undefined" && input instanceof Blob) {
-    body = input;
-    size = input.size;
-    contentType ??= input.type || "application/octet-stream";
-  } else if (input instanceof ArrayBuffer) {
-    body = input;
-    size = input.byteLength;
-  } else {
-    // Newer TS lib types refuse `Uint8Array<ArrayBufferLike>` as BodyInit
-    // directly even though every runtime accepts it. Hand fetch the
-    // underlying ArrayBuffer slice to sidestep the type narrowing.
-    const u8 = input as Uint8Array;
-    body = u8.buffer.slice(u8.byteOffset, u8.byteOffset + u8.byteLength) as ArrayBuffer;
-    size = u8.byteLength;
-  }
-
-  filename ??= "upload";
-  contentType ??= "application/octet-stream";
-
-  const transport = clientTransport(options.token);
-
-  const slot = await pylonFetch<{ uploadUrl: string; assetId: string }>(
-    transport,
-    "/api/files/init",
-    {
-      method: "POST",
-      json: {
-        filename,
-        mimeType: contentType,
-        size,
-        visibility: options.visibility ?? "private",
-      },
-    },
-  );
-
-  const base = new URL(getBaseUrl() || "http://localhost");
-  const target = new URL(slot.uploadUrl, base);
-  const put =
-    target.origin === base.origin
-      ? await pylonFetchRaw(transport, `${target.pathname}${target.search}`, {
-          method: "PUT",
-          body,
-          headers: { "Content-Type": contentType },
-        })
-      : await fetch(target.toString(), {
-          method: "PUT",
-          body,
-          headers: { "Content-Type": contentType },
-        });
-  // Read the response body to the end, even an empty 204. Chrome cancels a
-  // fetch whose body is never read once the Response is dropped, and
-  // DevTools then lists the upload as failed (net::ERR_ABORTED) although
-  // the server stored the bytes.
-  const putBody = await put.text().catch(() => "");
-  if (!put.ok) {
-    let message = `Upload of ${filename} failed: ${put.status}`;
-    let code: string | undefined;
-    try {
-      const err = JSON.parse(putBody) as { error?: { code?: string; message?: string } };
-      if (err.error?.message) message = err.error.message;
-      code = err.error?.code;
-    } catch {
-      // Not JSON (storage provider XML, proxy page): keep the status text.
-    }
-    throw new PylonHttpError(message, put.status, code);
-  }
-
-  return pylonFetch<UploadedFile>(transport, "/api/files/confirm", {
-    method: "POST",
-    json: { assetId: slot.assetId },
-  });
+  const { token, ...rest } = options;
+  return uploadBytes(clientTransport(token), input, rest);
 }
 
 /**

package/src/offlineUploads.test.tsx

@@ -0,0 +1,66 @@
+// A queued photo shows on its record at once, from the device, and the
+// record shows the uploaded file's URL after the upload runs.
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { act, cleanup, render, screen, waitFor } from "@testing-library/react";
+import type { SyncEngine } from "@pylonsync/sync";
+import { createTestEnv, type TestEnv } from "@pylonsync/sync/src/test-harness";
+
+import { useQueryOne } from "./hooks";
+import { queueUpload, useFileUrl } from "./offlineUploads";
+
+const asEngine = (e: TestEnv["engine"]): SyncEngine => e as unknown as SyncEngine;
+
+let env: TestEnv | null = null;
+afterEach(async () => {
+  cleanup();
+  if (env) {
+    await env.dispose();
+    env = null;
+  }
+});
+
+function PhotoCard({ engine }: { engine: SyncEngine }) {
+  const { data } = useQueryOne<{ id: string; url: string | null }>(engine, "Photo", "p1");
+  const src = useFileUrl(data?.url, engine);
+  return <span data-testid="src">{src ?? "none"}</span>;
+}
+
+describe("queueUpload + useFileUrl", () => {
+  test("the record shows the local photo at once and the real URL after the upload", async () => {
+    env = createTestEnv({ transport: "poll" });
+    env.signIn({ userId: "rep1" });
+    env.server.seed("Photo", [{ id: "p1", url: null, fileId: null }]);
+    await env.start();
+    const engine = asEngine(env.engine);
+    render(<PhotoCard engine={engine} />);
+    expect(screen.getByTestId("src").textContent).toBe("none");
+
+    // Hold the upload so the local stage is observable.
+    env.server.files.dropNextPut();
+    let queued!: Awaited<ReturnType<typeof queueUpload>>;
+    await act(async () => {
+      queued = await queueUpload(new File([new Uint8Array(64)], "door.jpg", { type: "image/jpeg" }), {
+        attach: { entity: "Photo", id: "p1", field: "fileId", urlField: "url" },
+        engine,
+      });
+    });
+    expect(queued.localUrl).toMatch(/^blob:/);
+    expect(screen.getByTestId("src").textContent).toBe(queued.localUrl!);
+
+    await act(async () => {
+      await env!.engine.uploads.process();
+      await queued.done;
+    });
+    await waitFor(() => expect(screen.getByTestId("src").textContent).toBe("/api/files/f_2"));
+  });
+
+  test("a local reference this device does not hold resolves to null", async () => {
+    env = createTestEnv({ transport: "poll" });
+    env.signIn({ userId: "rep1" });
+    env.server.seed("Photo", [{ id: "p1", url: "local:upl_from_another_phone", fileId: null }]);
+    await env.start();
+    render(<PhotoCard engine={asEngine(env.engine)} />);
+    await waitFor(() => expect(screen.getByTestId("src").textContent).toBe("none"));
+  });
+});

package/src/offlineUploads.ts

@@ -0,0 +1,77 @@
+"use client";
+
+import {
+	localUploadId,
+	OUTBOX_CHANNEL,
+	type FileVisibility,
+	type QueuedUploadHandle,
+	type SyncEngine,
+	type UploadAttachTarget,
+} from "@pylonsync/sync";
+import { useSyncExternalStore } from "react";
+import { db } from "./db";
+
+export type { QueuedUploadHandle, UploadAttachTarget };
+
+export interface QueueUploadOptions {
+	/** The record the file belongs to, and the field that gets its id
+	 *  (and `urlField`, its URL). */
+	attach: UploadAttachTarget;
+	filename?: string;
+	contentType?: string;
+	visibility?: FileVisibility;
+	/** Defaults to the engine `init()` set up. */
+	engine?: SyncEngine;
+}
+
+/**
+ * Keep a file on the device and upload it when there is a network, then
+ * set it on its record. Returns at once, also with no network.
+ *
+ * At once the record's `attach.field` (and `attach.urlField`) holds
+ * `local:<localId>`; read it with `useFileUrl` to show the photo from the
+ * device. When the upload finishes, the field gets the file id and
+ * `urlField` the file URL. Both changes are ordinary queued writes.
+ *
+ * ```ts
+ * const photoId = await db.insert("Photo", { leadId, fileId: null, url: null });
+ * await queueUpload(file, {
+ *   attach: { entity: "Photo", id: photoId, field: "fileId", urlField: "url" },
+ * });
+ * ```
+ *
+ * Pending and failed uploads are in `useOutbox()` with kind `"upload"`.
+ * Throws `UploadQueueFullError` when the queue already holds
+ * `maxQueuedUploadBytes` (200 MB by default).
+ */
+export function queueUpload(
+	file: Blob,
+	options: QueueUploadOptions,
+): Promise<QueuedUploadHandle> {
+	const { engine, ...rest } = options;
+	return (engine ?? db.sync).queueUpload(file, rest);
+}
+
+/**
+ * The URL to show for a file field: the value itself, or, for a
+ * `local:<localId>` value from `queueUpload`, an object URL of the copy on
+ * this device. Null for an empty value, and for a `local:` value this
+ * device does not hold (another device queued it, or it was dismissed).
+ *
+ * ```tsx
+ * const src = useFileUrl(photo.url);
+ * return src ? <img src={src} /> : <Placeholder />;
+ * ```
+ */
+export function useFileUrl(
+	value: string | null | undefined,
+	engine?: SyncEngine,
+): string | null {
+	const sync = engine ?? db.sync;
+	const localId = localUploadId(value);
+	return useSyncExternalStore(
+		(cb) => sync.store.subscribe(cb, OUTBOX_CHANNEL),
+		() => (localId ? sync.uploadLocalUrl(localId) : (value ?? null)),
+		() => (localId ? null : (value ?? null)),
+	);
+}

package/src/offlineWorker.test.ts

@@ -0,0 +1,87 @@
+// The SSR client runtime calls registerOfflineWorker on every page load. It
+// must register `/pylon-sw.js` only for a production page of an app that
+// opted in, and otherwise remove a Pylon worker an earlier build left behind
+// without touching the app's own workers.
+
+import { expect, test } from "bun:test";
+import { registerOfflineWorker } from "./offlineWorker";
+
+function fakeContainer(scripts: string[] = []) {
+  const registered: Array<{ url: string; scope?: string }> = [];
+  const unregistered: string[] = [];
+  const messages: unknown[] = [];
+  const container = {
+    register: async (url: string, options?: { scope?: string }) => {
+      registered.push({ url, scope: options?.scope });
+      return { scope: "/" };
+    },
+    getRegistrations: async () =>
+      scripts.map((scriptURL) => ({
+        active: { scriptURL },
+        unregister: async () => {
+          unregistered.push(scriptURL);
+          return true;
+        },
+      })),
+    ready: Promise.resolve({ active: { postMessage: (m: unknown) => messages.push(m) } }),
+  };
+  return { container, registered, unregistered, messages };
+}
+
+const loaded = () => Promise.resolve();
+
+test("registers the worker in production when the app opted in", async () => {
+  const f = fakeContainer();
+  const reg = await registerOfflineWorker({
+    optedIn: true,
+    production: true,
+    signedIn: true,
+    navigator: { serviceWorker: f.container },
+    whenLoaded: loaded,
+  });
+  expect(reg).not.toBeNull();
+  expect(f.registered).toEqual([{ url: "/pylon-sw.js", scope: "/" }]);
+  expect(f.messages).toEqual([{ type: "pylon:session", signedIn: true }]);
+});
+
+test("does not register under pylon dev", async () => {
+  const f = fakeContainer();
+  await registerOfflineWorker({
+    optedIn: true,
+    production: false,
+    navigator: { serviceWorker: f.container },
+    whenLoaded: loaded,
+  });
+  expect(f.registered).toEqual([]);
+});
+
+test("does not register when the app did not opt in", async () => {
+  const f = fakeContainer();
+  await registerOfflineWorker({
+    optedIn: false,
+    production: true,
+    navigator: { serviceWorker: f.container },
+    whenLoaded: loaded,
+  });
+  expect(f.registered).toEqual([]);
+});
+
+test("removes a leftover Pylon worker but not the app's own", async () => {
+  const f = fakeContainer([
+    "https://app.example/pylon-sw.js",
+    "https://app.example/push-worker.js",
+  ]);
+  await registerOfflineWorker({
+    optedIn: false,
+    production: true,
+    navigator: { serviceWorker: f.container },
+    whenLoaded: loaded,
+  });
+  expect(f.unregistered).toEqual(["https://app.example/pylon-sw.js"]);
+});
+
+test("a browser without service workers is a no-op", async () => {
+  expect(
+    await registerOfflineWorker({ optedIn: true, production: true, navigator: {} }),
+  ).toBeNull();
+});

package/src/offlineWorker.ts

@@ -0,0 +1,95 @@
+// Registers the offline service worker (`/pylon-sw.js`) for apps that set
+// `buildManifest({ offline })`. The SSR client runtime calls this once per
+// page load; apps do not call it themselves.
+//
+// The worker is served by the Pylon runtime and generated per build (see
+// packages/functions/src/offline-sw.ts). It is never registered under
+// `pylon dev`: a worker serves cached build files first, which would hide
+// every edit until the next install.
+
+const WORKER_URL = "/pylon-sw.js";
+
+export interface OfflineWorkerOptions {
+  /** The app set `buildManifest({ offline })`. */
+  optedIn: boolean;
+  /** Not `pylon dev`. */
+  production: boolean;
+  /** Whether a user is signed in on this page. The worker refetches the
+   *  pages it keeps when this changes, because each one carries the
+   *  signed-in bit. */
+  signedIn?: boolean;
+  /** Defaults to the global `navigator`. */
+  navigator?: { serviceWorker?: ServiceWorkerContainerLike };
+  /** Resolves when the page has loaded, so the worker's downloads do not
+   *  compete with the page's own. Defaults to the window `load` event. */
+  whenLoaded?: () => Promise<void>;
+}
+
+/** The parts of `ServiceWorkerContainer` this module uses. */
+export interface ServiceWorkerContainerLike {
+  register(url: string, options?: { scope?: string }): Promise<unknown>;
+  getRegistrations?(): Promise<ReadonlyArray<RegistrationLike>>;
+  ready?: Promise<{ active?: { postMessage(message: unknown): void } | null }>;
+}
+
+interface RegistrationLike {
+  active?: { scriptURL: string } | null;
+  waiting?: { scriptURL: string } | null;
+  installing?: { scriptURL: string } | null;
+  unregister(): Promise<boolean>;
+}
+
+function defaultWhenLoaded(): Promise<void> {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return Promise.resolve();
+  }
+  if (document.readyState === "complete") return Promise.resolve();
+  return new Promise((resolve) =>
+    window.addEventListener("load", () => resolve(), { once: true }),
+  );
+}
+
+function isPylonWorker(reg: RegistrationLike): boolean {
+  const worker = reg.active ?? reg.waiting ?? reg.installing;
+  if (!worker) return false;
+  try {
+    return new URL(worker.scriptURL).pathname === WORKER_URL;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Register the worker when the app opted in and this is a production page.
+ * Otherwise remove a Pylon worker an earlier build left on this origin (an
+ * app that turned offline off, or `pylon dev` after `pylon start`). Workers
+ * the app registered itself are left alone. Never throws: an app works
+ * online without its worker.
+ */
+export async function registerOfflineWorker(
+  opts: OfflineWorkerOptions,
+): Promise<unknown | null> {
+  const nav =
+    opts.navigator ??
+    (typeof navigator !== "undefined" ? (navigator as any) : undefined);
+  const container = nav?.serviceWorker as ServiceWorkerContainerLike | undefined;
+  if (!container) return null;
+  try {
+    if (!opts.optedIn || !opts.production) {
+      const regs = (await container.getRegistrations?.()) ?? [];
+      await Promise.all(regs.filter(isPylonWorker).map((r) => r.unregister()));
+      return null;
+    }
+    await (opts.whenLoaded ?? defaultWhenLoaded)();
+    const registration = await container.register(WORKER_URL, { scope: "/" });
+    if (typeof opts.signedIn === "boolean" && container.ready) {
+      const ready = await container.ready;
+      ready.active?.postMessage({ type: "pylon:session", signedIn: opts.signedIn });
+    }
+    return registration;
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn("[pylon offline] service worker registration failed:", err);
+    return null;
+  }
+}

package/src/useOutbox.test.tsx

@@ -0,0 +1,82 @@
+// `useOutbox` re-renders as writes go pending, reach the server, or fail, and
+// its retry/dismiss act on the failed list.
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { act, cleanup, render, screen, waitFor } from "@testing-library/react";
+import type { SyncEngine } from "@pylonsync/sync";
+import { createTestEnv, type TestEnv } from "@pylonsync/sync/src/test-harness";
+
+import { useOutbox } from "./useOutbox";
+
+const asEngine = (e: TestEnv["engine"]): SyncEngine => e as unknown as SyncEngine;
+
+let env: TestEnv | null = null;
+afterEach(async () => {
+  cleanup();
+  if (env) {
+    await env.dispose();
+    env = null;
+  }
+});
+
+let latest: ReturnType<typeof useOutbox> | null = null;
+function Probe({ engine }: { engine: SyncEngine }) {
+  const outbox = useOutbox(engine);
+  latest = outbox;
+  return (
+    <span data-testid="outbox">
+      {`${outbox.pending.length} not synced, ${outbox.failed.length} failed` +
+        (outbox.failed[0] ? `: ${outbox.failed[0].error}` : "")}
+    </span>
+  );
+}
+
+const text = () => screen.getByTestId("outbox").textContent;
+
+describe("useOutbox", () => {
+  test("re-renders when a write goes pending, then reaches the server", async () => {
+    env = createTestEnv({ transport: "poll" });
+    env.signIn({ userId: "u1" });
+    await env.start();
+    render(<Probe engine={asEngine(env.engine)} />);
+    expect(text()).toBe("0 not synced, 0 failed");
+
+    env.server.primeNextPushOutcome({ kind: "network" });
+    await act(async () => {
+      await env!.engine.insert("Knock", { door: "1" });
+    });
+    expect(text()).toBe("1 not synced, 0 failed");
+
+    await act(async () => {
+      await env!.engine.push();
+    });
+    await waitFor(() => expect(text()).toBe("0 not synced, 0 failed"));
+  });
+
+  test("re-renders when a write fails; retry and dismiss work from the hook", async () => {
+    env = createTestEnv({ transport: "poll" });
+    env.signIn({ userId: "u1" });
+    await env.start();
+    env.server.rejectWritesWhere("Knock", (d) => d.door === "", "VALIDATION_FAILED", "door number is required");
+    render(<Probe engine={asEngine(env.engine)} />);
+
+    await act(async () => {
+      await env!.engine.insert("Knock", { door: "" }).catch(() => {});
+    });
+    expect(text()).toBe("0 not synced, 1 failed: door number is required");
+
+    await act(async () => {
+      await latest!.retry(latest!.failed[0]!.id, { door: "7" });
+    });
+    await waitFor(() => expect(text()).toBe("0 not synced, 0 failed"));
+
+    await act(async () => {
+      await env!.engine.insert("Knock", { door: "" }).catch(() => {});
+    });
+    expect(text()).toBe("0 not synced, 1 failed: door number is required");
+    act(() => {
+      expect(latest!.dismiss(latest!.failed[0]!.id)).toBe(true);
+    });
+    expect(text()).toBe("0 not synced, 0 failed");
+  });
+});

package/src/useOutbox.ts

@@ -0,0 +1,74 @@
+"use client";
+
+import {
+	OUTBOX_CHANNEL,
+	type Outbox,
+	type OutboxItem,
+	type Row,
+	type SyncEngine,
+} from "@pylonsync/sync";
+import { useCallback, useSyncExternalStore } from "react";
+import { db } from "./db";
+
+export type { Outbox, OutboxItem };
+
+export interface UseOutboxReturn {
+	/** Writes the server has not applied yet: made offline, or waiting
+	 *  for a sign-in. Oldest first. */
+	pending: OutboxItem[];
+	/** Writes the server rejected, with `error` and `errorCode`. Oldest
+	 *  first. Each stays until it is retried or dismissed. */
+	failed: OutboxItem[];
+	/** Send a failed write again, with `data` merged over its fields.
+	 *  Resolves once the server applies it or it is queued offline;
+	 *  rejects with a `MutationRejectedError` when the server rejects it
+	 *  again or another user is signed in. */
+	retry: (id: string, data?: Row) => Promise<string>;
+	/** Drop a failed write. */
+	dismiss: (id: string) => boolean;
+}
+
+const EMPTY: Outbox = { pending: [], failed: [] };
+
+/**
+ * The writes on this device that are not on the server: pending writes
+ * (offline, or waiting for a sign-in) and failed writes (the server
+ * rejected them). Re-renders when a write is queued, applied, rejected,
+ * retried or dismissed.
+ *
+ * ```tsx
+ * function Outbox() {
+ *   const { pending, failed, retry, dismiss } = useOutbox();
+ *   return (
+ *     <>
+ *       {pending.length > 0 && <p>{pending.length} not synced</p>}
+ *       {failed.map((w) => (
+ *         <div key={w.id}>
+ *           {w.entity}: {w.error}
+ *           <button onClick={() => retry(w.id)}>Retry</button>
+ *           <button onClick={() => dismiss(w.id)}>Dismiss</button>
+ *         </div>
+ *       ))}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * Pass an explicit `engine` if your app uses a non-default sync
+ * instance; otherwise the hook reads the singleton wired up by `init()`.
+ */
+export function useOutbox(engine?: SyncEngine): UseOutboxReturn {
+	const sync = engine ?? db.sync;
+	const outbox = useSyncExternalStore(
+		(cb) => sync.store.subscribe(cb, OUTBOX_CHANNEL),
+		() => sync.outbox(),
+		// The server has no queue.
+		() => EMPTY,
+	);
+	const retry = useCallback(
+		(id: string, data?: Row) => sync.retryWrite(id, data),
+		[sync],
+	);
+	const dismiss = useCallback((id: string) => sync.dismissWrite(id), [sync]);
+	return { pending: outbox.pending, failed: outbox.failed, retry, dismiss };
+}