@pylonsync/react 0.22.47 → 0.22.58

package/dist/AppUpdateBar.d.ts

@@ -0,0 +1,21 @@
+import type { ReactNode } from "react";
+import type { AppUpdater } from "./appUpdate";
+export interface AppUpdateBarProps {
+    className?: string;
+    /** Text when a new build is ready. */
+    message?: ReactNode;
+    /** The button label. */
+    actionLabel?: ReactNode;
+    /** The button label while pending writes are sent before the reload. */
+    savingLabel?: ReactNode;
+    /** Text on an iOS home-screen app whose name or icon changed. */
+    reinstallMessage?: ReactNode;
+    updater?: AppUpdater;
+}
+/**
+ * A minimal, unstyled notice for `useAppUpdate`. Renders nothing until a
+ * new build is ready or the home-screen app must be added again. Style it
+ * with `className` and the `data-pylon-app-update` attribute, or build your
+ * own notice with the hook.
+ */
+export declare function AppUpdateBar({ className, message, actionLabel, savingLabel, reinstallMessage, updater, }: AppUpdateBarProps): import("react").JSX.Element | null;

package/dist/appUpdate.d.ts

@@ -0,0 +1,166 @@
+/** The path the runtime serves the latest build's version at. */
+export declare const VERSION_URL = "/_pylon/version";
+/** How often a visible page checks for a new build. */
+export declare const CHECK_INTERVAL_MS: number;
+/** How long `apply()` waits for a new worker to install or take over
+ *  before it reloads anyway. */
+export declare const WORKER_WAIT_MS: number;
+/** A reload that lands on the same build within this window does not
+ *  reload again. */
+export declare const RELOAD_GUARD_MS: number;
+/** One build of the app. */
+export interface AppBuild {
+    /** The service worker version: a hash of the build. */
+    version: string;
+    /** When the build was made (ISO 8601), or null when unknown. */
+    builtAt: string | null;
+}
+export interface AppUpdateState {
+    /** The build this page runs. Null during SSR and in an app without
+     *  `buildManifest({ offline })`. */
+    version: string | null;
+    builtAt: string | null;
+    /** The latest build the server reported. Null until the first check
+     *  succeeds. */
+    latestVersion: string | null;
+    latestBuiltAt: string | null;
+    /** A newer build exists. `apply()` loads it. */
+    updateReady: boolean;
+    /** The app is on the iOS home screen, and its name, icons, display mode
+     *  or start URL changed since it was added. The user must remove the app
+     *  and add it again to see the change. */
+    reinstallRecommended: boolean;
+    /** `apply()` is running. */
+    applying: boolean;
+    /** `apply()` is waiting for pending writes to reach the server. */
+    waitingForSync: boolean;
+}
+/** The parts of `ServiceWorker` this module uses. */
+export interface WorkerLike {
+    state?: string;
+    postMessage(message: unknown, transfer?: unknown[]): void;
+    addEventListener?(type: "statechange", listener: () => void): void;
+}
+/** The parts of `ServiceWorkerRegistration` this module uses. */
+export interface UpdateRegistrationLike {
+    waiting?: WorkerLike | null;
+    installing?: WorkerLike | null;
+    update?(): Promise<unknown>;
+    addEventListener?(type: "updatefound", listener: () => void): void;
+    removeEventListener?(type: "updatefound", listener: () => void): void;
+}
+/** The parts of `ServiceWorkerContainer` this module uses. */
+export interface UpdateContainerLike {
+    controller?: unknown;
+    getRegistration?(scope?: string): Promise<UpdateRegistrationLike | undefined>;
+    addEventListener?(type: "controllerchange", listener: () => void): void;
+    removeEventListener?(type: "controllerchange", listener: () => void): void;
+}
+interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+/** The pending writes `apply()` waits for. */
+export interface PendingWrites {
+    count(): number;
+    subscribe(listener: () => void): () => void;
+}
+/** Everything the updater touches outside itself. Tests pass their own;
+ *  the browser defaults come from `browserEnv`. */
+export interface AppUpdateEnv {
+    serviceWorker: UpdateContainerLike | null;
+    fetch(url: string, init: RequestInit): Promise<{
+        ok: boolean;
+        json(): Promise<unknown>;
+    }>;
+    document: {
+        visibilityState: string;
+        addEventListener(type: "visibilitychange", listener: () => void): void;
+        removeEventListener(type: "visibilitychange", listener: () => void): void;
+    } | null;
+    setInterval(fn: () => void, ms: number): unknown;
+    clearInterval(handle: unknown): void;
+    setTimeout(fn: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+    now(): number;
+    reload(): void;
+    sessionStorage: StorageLike | null;
+    localStorage: StorageLike | null;
+    /** The page runs as an iOS home-screen app (`navigator.standalone`). */
+    iosStandalone: boolean;
+    /** The sync engine's pending writes, or null when the app has none. */
+    pendingWrites(): PendingWrites | null;
+    /** Asks a waiting worker for its version. Null when it does not answer. */
+    askVersion(worker: WorkerLike): Promise<string | null>;
+    warn(message: string): void;
+}
+/** The state during SSR and before the client runtime configured a build. */
+export declare const INERT_APP_UPDATE_STATE: AppUpdateState;
+/** Checks for new builds and loads them. One per page; see `appUpdate`. */
+export declare class AppUpdater {
+    private build;
+    private production;
+    private envFactory;
+    private env;
+    private listeners;
+    private snapshot;
+    private latest;
+    private waitingVersion;
+    private reinstall;
+    private applying;
+    private waitingForSync;
+    private registration;
+    private running;
+    private interval;
+    private checking;
+    private applyRun;
+    private reloading;
+    constructor(envFactory: () => AppUpdateEnv | null);
+    /** Set the build this page runs. `production` is false under `pylon
+     *  dev`, which leaves the updater inert. */
+    configure(build: AppBuild | null, production: boolean): void;
+    getSnapshot: () => AppUpdateState;
+    subscribe: (listener: () => void) => (() => void);
+    /** Ask the server for the latest build now. */
+    check: () => Promise<void>;
+    /**
+     * Load the newest build: wait until the outbox has no pending writes,
+     * let the waiting service worker take over, and reload the page once.
+     * Does nothing under `pylon dev`, during SSR, or right after a reload
+     * that did not change the build (so a page that calls `apply()` on its
+     * own cannot reload in a loop).
+     */
+    apply: () => Promise<void>;
+    private activeEnv;
+    private start;
+    private stop;
+    private onVisibility;
+    private emit;
+    private runCheck;
+    /** The Pylon worker's registration, with an `updatefound` listener that
+     *  records a new worker once it is installed. */
+    private watchRegistration;
+    private readWaiting;
+    private readInstall;
+    private runApply;
+    private reload;
+    private drainOutbox;
+    private waitForInstalled;
+}
+/** The browser environment, or null outside a browser. */
+export declare function browserEnv(): AppUpdateEnv | null;
+/** The page's updater. `useAppUpdate()` reads it. */
+export declare const appUpdate: AppUpdater;
+/**
+ * Set the build this page runs. The SSR client runtime calls it through
+ * `registerOfflineWorker({ build })`; apps do not call it.
+ */
+export declare function configureAppUpdate(build: AppBuild | null, production: boolean): void;
+/** An updater with its own environment, for tests and for apps that
+ *  render outside the SSR client runtime. */
+export declare function createAppUpdate(options: {
+    build: AppBuild | null;
+    production: boolean;
+    env: AppUpdateEnv | null;
+}): AppUpdater;
+export {};

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,21 @@ export { useSession } from "./useSession";
 export type { UseSessionReturn, ResolvedSession } from "./useSession";
 export { useSyncStatus } from "./useSyncStatus";
 export type { SyncConnectionStatus } from "./useSyncStatus";
+export { useSyncProgress } from "./useSyncProgress";
+export type { SyncProgress } from "./useSyncProgress";
+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 { useAppUpdate } from "./useAppUpdate";
+export type { UseAppUpdateReturn } from "./useAppUpdate";
+export { AppUpdateBar } from "./AppUpdateBar";
+export type { AppUpdateBarProps } from "./AppUpdateBar";
+export { createAppUpdate, AppUpdater } from "./appUpdate";
+export type { AppBuild, AppUpdateState, AppUpdateEnv } from "./appUpdate";
 export { db, init, getSync, setSessionToken } from "./db";
 export { createTypedDb } from "./typed";
 export type { TypedDb, AgentDBSchema } from "./typed";
@@ -254,27 +269,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 +284,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,54 @@
+import { type AppBuild } from "./appUpdate";
+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 build this page runs, from `__PYLON_DATA__`. `useAppUpdate`
+     *  compares it with the latest build. */
+    build?: AppBuild;
+}
+/** 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/queryFilter.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Order two values the way the server's SQL does: negative, zero or
+ * positive; `null` when they cannot be compared (different types, or an
+ * object). Null and undefined are not handled here.
+ */
+export declare function compareValues(a: unknown, b: unknown): number | null;
+type Row = Record<string, unknown>;
+/** A predicate for `where` (keys other than `$order` and `$limit`). */
+export declare function compileWhere(where: Record<string, unknown>): (row: Row) => boolean;
+/** Sort comparator for `$order` / `orderBy`: nulls last ascending, the
+ *  server's value order otherwise. */
+export declare function compareForOrder(a: unknown, b: unknown, dir: "asc" | "desc"): number;
+export {};

package/dist/useAppUpdate.d.ts

@@ -0,0 +1,34 @@
+import { type AppUpdater, type AppUpdateState } from "./appUpdate";
+export interface UseAppUpdateReturn extends AppUpdateState {
+    /** Wait until the outbox has no pending writes, then load the newest
+     *  build (the page reloads). */
+    apply: () => Promise<void>;
+    /** Ask the server for the latest build now. The hook also checks when
+     *  the page becomes visible and every five minutes. */
+    check: () => Promise<void>;
+}
+/**
+ * Whether a newer build of the app is deployed, and a way to load it.
+ * Works in apps that set `buildManifest({ offline })`; elsewhere, under
+ * `pylon dev` and during SSR, `updateReady` stays false and `apply()` does
+ * nothing.
+ *
+ * ```tsx
+ * function UpdateNotice() {
+ *   const { updateReady, applying, waitingForSync, apply } = useAppUpdate();
+ *   if (!updateReady) return null;
+ *   return (
+ *     <div role="status">
+ *       A new version of the app is available.
+ *       <button onClick={apply} disabled={applying}>
+ *         {waitingForSync ? "Saving changes" : "Update"}
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * Pass an explicit `updater` (from `createAppUpdate`) to use one other than
+ * the page's.
+ */
+export declare function useAppUpdate(updater?: AppUpdater): UseAppUpdateReturn;

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/dist/useSyncProgress.d.ts

@@ -0,0 +1,21 @@
+import { type SyncEngine, type SyncProgress } from "@pylonsync/sync";
+export type { SyncProgress };
+/**
+ * How far the sync engine's current pull has got: `pulling`, `snapshot`
+ * (a first sync or a far-behind catch-up), `rows` and `pages` received,
+ * and `synced` (a pull completed since the last replica reset).
+ *
+ * The session resolves as soon as `/api/auth/me` answers, before the
+ * replica has filled. Render the signed-in screen from `useSession()` and
+ * use this for a progress line while the data arrives. `useSyncStatus()`
+ * reports the connection instead.
+ *
+ * ```tsx
+ * function SyncLine() {
+ *   const { pulling, snapshot, rows } = useSyncProgress();
+ *   if (!pulling || !snapshot) return null;
+ *   return <p>Loading data: {rows} records</p>;
+ * }
+ * ```
+ */
+export declare function useSyncProgress(engine?: SyncEngine): SyncProgress;

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.22.47",
+  "version": "0.22.58",
   "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.58",
+    "@pylonsync/sdk": "0.22.58",
+    "@pylonsync/sync": "0.22.58"
   },
   "peerDependencies": {
     "react": ">=19.0.0"

package/src/AppUpdateBar.tsx

@@ -0,0 +1,54 @@
+"use client";
+
+import type { ReactNode } from "react";
+import type { AppUpdater } from "./appUpdate";
+import { useAppUpdate } from "./useAppUpdate";
+
+export interface AppUpdateBarProps {
+  className?: string;
+  /** Text when a new build is ready. */
+  message?: ReactNode;
+  /** The button label. */
+  actionLabel?: ReactNode;
+  /** The button label while pending writes are sent before the reload. */
+  savingLabel?: ReactNode;
+  /** Text on an iOS home-screen app whose name or icon changed. */
+  reinstallMessage?: ReactNode;
+  updater?: AppUpdater;
+}
+
+/**
+ * A minimal, unstyled notice for `useAppUpdate`. Renders nothing until a
+ * new build is ready or the home-screen app must be added again. Style it
+ * with `className` and the `data-pylon-app-update` attribute, or build your
+ * own notice with the hook.
+ */
+export function AppUpdateBar({
+  className,
+  message = "A new version of the app is available.",
+  actionLabel = "Update",
+  savingLabel = "Saving changes",
+  reinstallMessage = "The app name or icon changed. Remove the app from the home screen and add it again.",
+  updater,
+}: AppUpdateBarProps) {
+  const { updateReady, reinstallRecommended, applying, waitingForSync, apply } =
+    useAppUpdate(updater);
+  if (updateReady) {
+    return (
+      <div role="status" className={className} data-pylon-app-update="ready">
+        <span>{message}</span>{" "}
+        <button type="button" onClick={() => void apply()} disabled={applying}>
+          {waitingForSync ? savingLabel : actionLabel}
+        </button>
+      </div>
+    );
+  }
+  if (reinstallRecommended) {
+    return (
+      <div role="status" className={className} data-pylon-app-update="reinstall">
+        {reinstallMessage}
+      </div>
+    );
+  }
+  return null;
+}

package/src/Link.tsx

@@ -9,9 +9,16 @@
 //     that match across the two routes survive reconciliation, so
 //     their state persists.
 //   - Prefetches in two stages, because the two halves cost very
-//     different things. On viewport entry (IntersectionObserver) the
-//     runtime modulepreloads the destination's client chunks — static,
-//     immutable, cacheable. On hover, touch, or focus it also fetches
+//     different things. For every rendered link, the runtime
+//     modulepreloads the destination's client chunks — static, immutable,
+//     cacheable — once the page has painted and the browser is idle
+//     (requestIdleCallback), and not at all under Save-Data or on 2G. That
+//     covers links off screen, such as a tab bar, so the first tap is warm
+//     too, without counting against this page's first paint. For a route
+//     that navigates with no page fetch (`navigation = "client"` or an
+//     offline route), the runtime also loads its entry then. On hover,
+//     touch, pointerdown, or focus it fetches the chunks at once and also
+//     fetches
 //     the page itself, which costs a server render, so that waits for a
 //     real signal of intent rather than firing for a screenful of links.
 //     Focus is included so a keyboard user tabbing to a link gets the
@@ -138,6 +145,12 @@ export function Link({
       window.__pylon?.prefetch(href, { document: true });
     };
 
+    // Every rendered link, not only those in view, once the browser is idle.
+    const idle =
+      typeof window.requestIdleCallback === "function"
+        ? window.requestIdleCallback(warmChunks, { timeout: 2000 })
+        : window.setTimeout(warmChunks, 200);
+
     let io: IntersectionObserver | null = null;
     if (typeof IntersectionObserver !== "undefined") {
       io = new IntersectionObserver(
@@ -156,6 +169,8 @@ export function Link({
 
     el.addEventListener("mouseenter", warmPage);
     el.addEventListener("touchstart", warmPage, { passive: true });
+    // A press starts ~100 ms before the click: enough to start the fetch.
+    el.addEventListener("pointerdown", warmPage);
     // Focus is the keyboard's version of hover, and a stronger signal: a
     // cursor slides across links it isn't aiming at, but nobody tabs onto one
     // idly. Without it, tabbing to a link and pressing Enter took the cold
@@ -163,9 +178,12 @@ export function Link({
     el.addEventListener("focus", warmPage);
 
     return () => {
+      if (typeof window.cancelIdleCallback === "function") window.cancelIdleCallback(idle);
+      else window.clearTimeout(idle);
       io?.disconnect();
       el.removeEventListener("mouseenter", warmPage);
       el.removeEventListener("touchstart", warmPage);
+      el.removeEventListener("pointerdown", warmPage);
       el.removeEventListener("focus", warmPage);
     };
   }, [href, prefetch]);