@pylonsync/react 0.22.59 → 0.22.61

package/dist/appUpdate.d.ts

@@ -8,6 +8,29 @@ 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;
+/** What `moveToLatestBuild()` did. */
+export type BuildMove = 
+/** The page is loading the server's build. */
+"moving"
+/** The server runs this page's build. */
+ | "current"
+/** The server did not answer. */
+ | "offline"
+/** Writes wait to be sent, and the caller asked not to wait for them. */
+ | "pending-writes"
+/** The page reloaded from this build moments ago and still runs it. */
+ | "blocked"
+/** No build to compare: `pylon dev`, SSR, or an app without `offline`. */
+ | "inert";
+export interface MoveOptions {
+    /** Load this URL in the new build. Default: reload the current URL. */
+    url?: string;
+    /** Ask the server for its build first, because a file failed to load.
+     *  Default: use what the last check found. */
+    recheck?: boolean;
+    /** Return `"pending-writes"` instead of waiting for pending writes. */
+    skipIfPendingWrites?: boolean;
+}
 /** One build of the app. */
 export interface AppBuild {
     /** The service worker version: a hash of the build. */
@@ -83,7 +106,8 @@ export interface AppUpdateEnv {
     setTimeout(fn: () => void, ms: number): unknown;
     clearTimeout(handle: unknown): void;
     now(): number;
-    reload(): void;
+    /** Reload the page, or load `url` when given. */
+    reload(url?: string): void;
     sessionStorage: StorageLike | null;
     localStorage: StorageLike | null;
     /** The page runs as an iOS home-screen app (`navigator.standalone`). */
@@ -131,6 +155,15 @@ export declare class AppUpdater {
      * own cannot reload in a loop).
      */
     apply: () => Promise<void>;
+    /**
+     * Move to the server's build when it is not this page's: `apply()`, then
+     * load `url` (or reload). Resolves with what it did; on `"moving"` the
+     * page is about to unload. Never moves while the server cannot be reached,
+     * so an offline page keeps its screen.
+     */
+    moveToLatestBuild: (options?: MoveOptions) => Promise<BuildMove>;
+    /** Run `apply()` once at a time; resolves with whether the page reloads. */
+    private startApply;
     private activeEnv;
     private start;
     private stop;
@@ -156,6 +189,13 @@ export declare const appUpdate: AppUpdater;
  * `registerOfflineWorker({ build })`; apps do not call it.
  */
 export declare function configureAppUpdate(build: AppBuild | null, production: boolean): void;
+/**
+ * Move this page to the server's build when it runs another one. The SSR
+ * client runtime calls it on navigation and when a route entry fails to
+ * load; `dynamic()` calls it when a chunk fails to load. See
+ * `AppUpdater.moveToLatestBuild`.
+ */
+export declare function moveToLatestBuild(options?: MoveOptions): Promise<BuildMove>;
 /** An updater with its own environment, for tests and for apps that
  *  render outside the SSR client runtime. */
 export declare function createAppUpdate(options: {

package/dist/index.d.ts

@@ -45,8 +45,8 @@ 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 { createAppUpdate, AppUpdater, moveToLatestBuild } from "./appUpdate";
+export type { AppBuild, AppUpdateState, AppUpdateEnv, BuildMove, MoveOptions, } from "./appUpdate";
 export { db, init, getSync, setSessionToken } from "./db";
 export { createTypedDb } from "./typed";
 export type { TypedDb, AgentDBSchema } from "./typed";

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.22.59",
+  "version": "0.22.61",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",
@@ -14,15 +14,15 @@
     "prepack": "bun run build"
   },
   "dependencies": {
-    "@pylonsync/realtime": "0.22.59",
-    "@pylonsync/sdk": "0.22.59",
-    "@pylonsync/sync": "0.22.59"
+    "@pylonsync/realtime": "0.22.61",
+    "@pylonsync/sdk": "0.22.61",
+    "@pylonsync/sync": "0.22.61"
   },
   "peerDependencies": {
     "react": ">=19.0.0"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.10.0",
+    "@happy-dom/global-registrator": "^21.0.4",
     "@testing-library/react": "^16.3.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",

package/src/appUpdate.test.ts

@@ -99,6 +99,7 @@ function makeEnv(opts: {
   const fetches: string[] = [];
   const warnings: string[] = [];
   let reloads = 0;
+  const reloadUrls: Array<string | undefined> = [];
   const doc = {
     visibilityState: "visible",
     addEventListener: (_t: string, l: () => void) => docListeners.add(l),
@@ -138,8 +139,9 @@ function makeEnv(opts: {
       if (i >= 0) timers.splice(i, 1);
     },
     now: () => now,
-    reload: () => {
+    reload: (url) => {
       reloads++;
+      reloadUrls.push(url);
     },
     sessionStorage: opts.session ?? new MemoryStorage(),
     localStorage: opts.local ?? new MemoryStorage(),
@@ -163,6 +165,7 @@ function makeEnv(opts: {
     warnings,
     intervals,
     reloads: () => reloads,
+    reloadUrls,
     setLatest: (l: typeof latest) => {
       latest = l;
     },
@@ -459,3 +462,111 @@ test("the first check does not record a newer build's install identity", async (
   expect(local.map.size).toBe(0);
   expect(u.getSnapshot().reinstallRecommended).toBe(false);
 });
+
+// ---------------------------------------------------------------------------
+// moveToLatestBuild: the client runtime moves an open page to a new deploy.
+// Veritas, after a deploy: the new worker waited for every tab to close, and
+// each click in an open tab became a full page load of the old build.
+// ---------------------------------------------------------------------------
+
+test("after a deploy, a click moves the page once: the waiting worker takes over and the link loads", async () => {
+  const reg = new FakeRegistration();
+  reg.waiting = new FakeWorker("v2");
+  const f = makeEnv({ latest: { version: "v2" }, registration: reg, pending: 0 });
+  const u = createAppUpdate({ build: BUILD, production: true, env: f.env });
+  await u.check();
+
+  const move = u.moveToLatestBuild({ url: "/leads", skipIfPendingWrites: true });
+  await settle();
+  expect(reg.waiting!.messages).toEqual([{ type: "pylon:skip-waiting" }]);
+  f.fireControllerChange();
+  expect(await move).toBe("moving");
+  expect(f.reloadUrls).toEqual(["/leads"]);
+
+  // More clicks before the page unloads: no second load.
+  expect(await u.moveToLatestBuild({ url: "/map" })).toBe("moving");
+  expect(f.reloads()).toBe(1);
+});
+
+test("a page that a move left on the old build does not move again", async () => {
+  const session = new MemoryStorage();
+  const first = makeEnv({ latest: { version: "v2" }, registration: null, session });
+  const u1 = createAppUpdate({ build: BUILD, production: true, env: first.env });
+  expect(await u1.moveToLatestBuild({ url: "/leads", recheck: true })).toBe("moving");
+
+  // The load came back on v1 (the server answered with the old build). The
+  // next click must not load again: that is the reload per click.
+  const second = makeEnv({ latest: { version: "v2" }, registration: null, session });
+  const u2 = createAppUpdate({ build: BUILD, production: true, env: second.env });
+  expect(await u2.moveToLatestBuild({ url: "/map", recheck: true })).toBe("blocked");
+  expect(await u2.moveToLatestBuild({ url: "/map", recheck: true })).toBe("blocked");
+  expect(second.reloads()).toBe(0);
+});
+
+test("a click with unsent writes does not wait for them; a failed file load does", async () => {
+  const reg = new FakeRegistration();
+  reg.waiting = new FakeWorker("v2");
+  const f = makeEnv({ latest: { version: "v2" }, registration: reg, pending: 1 });
+  const u = createAppUpdate({ build: BUILD, production: true, env: f.env });
+  await u.check();
+
+  expect(await u.moveToLatestBuild({ url: "/leads", skipIfPendingWrites: true })).toBe(
+    "pending-writes",
+  );
+  expect(reg.waiting!.messages).toEqual([]);
+
+  // The old build cannot show the next screen: wait for the writes, then move.
+  const move = u.moveToLatestBuild({ url: "/map", recheck: true });
+  await settle();
+  expect(u.getSnapshot().waitingForSync).toBe(true);
+  expect(reg.waiting!.messages).toEqual([]);
+  f.setPending(0);
+  await settle();
+  expect(reg.waiting!.messages).toEqual([{ type: "pylon:skip-waiting" }]);
+  f.fireControllerChange();
+  expect(await move).toBe("moving");
+  expect(f.reloadUrls).toEqual(["/map"]);
+});
+
+test("a failed file load while offline keeps the page", async () => {
+  const reg = new FakeRegistration();
+  const f = makeEnv({ latest: { version: "v2" }, registration: reg });
+  const u = createAppUpdate({ build: BUILD, production: true, env: f.env });
+  await u.check();
+  f.setLatest("offline");
+  expect(await u.moveToLatestBuild({ recheck: true })).toBe("offline");
+  expect(f.reloads()).toBe(0);
+});
+
+test("a page of the new build under the old worker lets its own worker take over", async () => {
+  // The tab loaded build v2 from the network, but the v1 worker still
+  // controls it and answers the build manifest from its cache.
+  const reg = new FakeRegistration();
+  reg.waiting = new FakeWorker("v2");
+  const f = makeEnv({ latest: { version: "v2" }, registration: reg });
+  const u = createAppUpdate({
+    build: { version: "v2", builtAt: null },
+    production: true,
+    env: f.env,
+  });
+  const move = u.moveToLatestBuild({ url: "/leads", recheck: true });
+  await settle();
+  expect(reg.waiting!.messages).toEqual([{ type: "pylon:skip-waiting" }]);
+  f.fireControllerChange();
+  expect(await move).toBe("moving");
+  expect(f.reloadUrls).toEqual(["/leads"]);
+});
+
+test("a failed file load with the server on this build does not move", async () => {
+  const f = makeEnv({ latest: { version: "v1" }, registration: new FakeRegistration() });
+  const u = createAppUpdate({ build: BUILD, production: true, env: f.env });
+  expect(await u.moveToLatestBuild({ recheck: true })).toBe("current");
+  expect(f.reloads()).toBe(0);
+});
+
+test("an app without offline does not move", async () => {
+  const f = makeEnv({ latest: { version: "v2" }, registration: null });
+  const u = createAppUpdate({ build: BUILD, production: false, env: f.env });
+  expect(await u.moveToLatestBuild({ recheck: true })).toBe("inert");
+  expect(f.fetches).toHaveLength(0);
+});

package/src/appUpdate.ts

@@ -19,6 +19,11 @@
 //   - `apply()` waits until the outbox has no pending writes, tells the
 //     waiting worker to take over (`pylon:skip-waiting`), and reloads once
 //     when it does.
+//   - `moveToLatestBuild()` is the same move, started by the client runtime
+//     instead of the app: on a navigation when the server already runs a
+//     newer build, and when a file of this page's build failed to load (a
+//     route entry or a `dynamic()` chunk the deploy removed). It loads the
+//     link's URL in the new build. A failure while offline does not move.
 //   - On an iOS home-screen app, a change to the manifest's name, icons,
 //     display mode or start URL sets `reinstallRecommended`: iOS reads those
 //     only when the app is added.
@@ -52,6 +57,31 @@ const RELOAD_KEY = "pylon:app-update:reload";
 /** localStorage: the install identity the home-screen app was added with. */
 const INSTALL_KEY = "pylon:app-update:install";
 
+/** What `moveToLatestBuild()` did. */
+export type BuildMove =
+  /** The page is loading the server's build. */
+  | "moving"
+  /** The server runs this page's build. */
+  | "current"
+  /** The server did not answer. */
+  | "offline"
+  /** Writes wait to be sent, and the caller asked not to wait for them. */
+  | "pending-writes"
+  /** The page reloaded from this build moments ago and still runs it. */
+  | "blocked"
+  /** No build to compare: `pylon dev`, SSR, or an app without `offline`. */
+  | "inert";
+
+export interface MoveOptions {
+  /** Load this URL in the new build. Default: reload the current URL. */
+  url?: string;
+  /** Ask the server for its build first, because a file failed to load.
+   *  Default: use what the last check found. */
+  recheck?: boolean;
+  /** Return `"pending-writes"` instead of waiting for pending writes. */
+  skipIfPendingWrites?: boolean;
+}
+
 /** One build of the app. */
 export interface AppBuild {
   /** The service worker version: a hash of the build. */
@@ -131,7 +161,8 @@ export interface AppUpdateEnv {
   setTimeout(fn: () => void, ms: number): unknown;
   clearTimeout(handle: unknown): void;
   now(): number;
-  reload(): void;
+  /** Reload the page, or load `url` when given. */
+  reload(url?: string): void;
   sessionStorage: StorageLike | null;
   localStorage: StorageLike | null;
   /** The page runs as an iOS home-screen app (`navigator.standalone`). */
@@ -200,7 +231,7 @@ export class AppUpdater {
   private running = false;
   private interval: unknown = null;
   private checking: Promise<void> | null = null;
-  private applyRun: Promise<void> | null = null;
+  private applyRun: Promise<boolean> | null = null;
   private reloading = false;
 
   constructor(envFactory: () => AppUpdateEnv | null) {
@@ -246,13 +277,44 @@ export class AppUpdater {
    * that did not change the build (so a page that calls `apply()` on its
    * own cannot reload in a loop).
    */
-  apply = (): Promise<void> => {
+  apply = (): Promise<void> => this.startApply().then(() => {});
+
+  /**
+   * Move to the server's build when it is not this page's: `apply()`, then
+   * load `url` (or reload). Resolves with what it did; on `"moving"` the
+   * page is about to unload. Never moves while the server cannot be reached,
+   * so an offline page keeps its screen.
+   */
+  moveToLatestBuild = async (options: MoveOptions = {}): Promise<BuildMove> => {
     const env = this.activeEnv();
-    if (!env) return Promise.resolve();
+    if (!env) return "inert";
+    if (this.reloading) return "moving";
+    if (options.recheck) {
+      this.latest = null;
+      await this.check();
+    }
+    const latest = this.latest?.version ?? null;
+    if (latest === null) return "offline";
+    // The server runs this page's build, but its worker still waits behind
+    // an older one, which answers with the older build's cached files (the
+    // build manifest among them, from a worker of an earlier Pylon). Let it take
+    // over.
+    const ownWorkerWaits = this.waitingVersion === this.build!.version;
+    if (latest === this.build!.version && !ownWorkerWaits) return "current";
+    if (options.skipIfPendingWrites && (env.pendingWrites()?.count() ?? 0) > 0) {
+      return "pending-writes";
+    }
+    return (await this.startApply(options.url)) ? "moving" : "blocked";
+  };
+
+  /** Run `apply()` once at a time; resolves with whether the page reloads. */
+  private startApply(url?: string): Promise<boolean> {
+    const env = this.activeEnv();
+    if (!env) return Promise.resolve(false);
     if (!this.applyRun) {
       this.applying = true;
       this.emit();
-      this.applyRun = this.runApply(env).finally(() => {
+      this.applyRun = this.runApply(env, url).finally(() => {
         this.applyRun = null;
         this.applying = false;
         this.waitingForSync = false;
@@ -415,7 +477,7 @@ export class AppUpdater {
     this.reinstall = stored.install !== latest.install;
   }
 
-  private async runApply(env: AppUpdateEnv): Promise<void> {
+  private async runApply(env: AppUpdateEnv, url?: string): Promise<boolean> {
     const from = this.build!.version;
     const last = readJson(env.sessionStorage, RELOAD_KEY);
     if (
@@ -428,7 +490,7 @@ export class AppUpdater {
         `[pylon] apply() reloaded ${Math.round((env.now() - last.at) / 1000)}s ago ` +
           `and the page still runs build ${from}. Not reloading again.`,
       );
-      return;
+      return false;
     }
 
     await this.drainOutbox(env);
@@ -468,13 +530,14 @@ export class AppUpdater {
     } else if (waiting) {
       waiting.postMessage({ type: "pylon:skip-waiting" });
     }
-    this.reload(env);
+    this.reload(env, url);
+    return true;
   }
 
-  private reload(env: AppUpdateEnv): void {
+  private reload(env: AppUpdateEnv, url?: string): void {
     if (this.reloading) return;
     this.reloading = true;
-    env.reload();
+    env.reload(url);
   }
 
   private drainOutbox(env: AppUpdateEnv): Promise<void> {
@@ -545,7 +608,7 @@ export function browserEnv(): AppUpdateEnv | null {
     setTimeout: (fn, ms) => setTimeout(fn, ms),
     clearTimeout: (h) => clearTimeout(h as any),
     now: () => Date.now(),
-    reload: () => window.location.reload(),
+    reload: (url) => (url ? window.location.assign(url) : window.location.reload()),
     sessionStorage: safeStorage(() => window.sessionStorage),
     localStorage: safeStorage(() => window.localStorage),
     iosStandalone: nav.standalone === true,
@@ -589,6 +652,16 @@ export function configureAppUpdate(build: AppBuild | null, production: boolean):
   appUpdate.configure(build, production);
 }
 
+/**
+ * Move this page to the server's build when it runs another one. The SSR
+ * client runtime calls it on navigation and when a route entry fails to
+ * load; `dynamic()` calls it when a chunk fails to load. See
+ * `AppUpdater.moveToLatestBuild`.
+ */
+export function moveToLatestBuild(options?: MoveOptions): Promise<BuildMove> {
+  return appUpdate.moveToLatestBuild(options);
+}
+
 /** An updater with its own environment, for tests and for apps that
  *  render outside the SSR client runtime. */
 export function createAppUpdate(options: {

package/src/dynamic.test.tsx

@@ -15,6 +15,25 @@ const { renderToStaticMarkup } = require("react-dom/server") as {
 };
 import React from "react";
 import { dynamic } from "./dynamic";
+import { appUpdate, type BuildMove, type MoveOptions } from "./appUpdate";
+
+/** Answer the page's build check with `result`; records each call. */
+function stubMove(result: BuildMove) {
+  const calls: MoveOptions[] = [];
+  const original = appUpdate.moveToLatestBuild;
+  appUpdate.moveToLatestBuild = async (options: MoveOptions = {}) => {
+    calls.push(options);
+    return result;
+  };
+  return { calls, restore: () => (appUpdate.moveToLatestBuild = original) };
+}
+
+function quietErrors() {
+  const orig = console.error;
+  const seen: unknown[][] = [];
+  console.error = (...args: unknown[]) => seen.push(args);
+  return { seen, restore: () => (console.error = orig) };
+}
 
 // @testing-library auto-registers cleanup when it finds a global afterEach;
 // bun:test doesn't provide one, so mounted trees would accumulate across tests
@@ -96,6 +115,66 @@ describe("dynamic() with ssr:false", () => {
   });
 });
 
+describe("dynamic() after a deploy", () => {
+  // Veritas: the map's chunk 404'd after a deploy, and the page went blank.
+  test("a chunk the deploy removed moves the page to the new build", async () => {
+    const move = stubMove("moving");
+    const errors = quietErrors();
+    try {
+      const D = dynamic(async () => {
+        throw new TypeError("Failed to fetch dynamically imported module: /_pylon/build/chunks/map-loader-jk6q22q6.js");
+      }, { loading: Skeleton });
+      render(<D />);
+      await waitFor(() => expect(move.calls).toEqual([{ recheck: true }]));
+      expect(screen.getByTestId("skeleton")).toBeDefined();
+      // The page is loading the new build: nothing to report.
+      expect(errors.seen).toEqual([]);
+    } finally {
+      move.restore();
+      errors.restore();
+    }
+  });
+
+  test("offline, the fallback stays and the next mount tries again", async () => {
+    const move = stubMove("offline");
+    const errors = quietErrors();
+    try {
+      let online = false;
+      const D = dynamic(async () => {
+        if (!online) throw new TypeError("Failed to fetch");
+        return { default: Heavy };
+      }, { loading: Skeleton });
+      const first = render(<D />);
+      await waitFor(() => expect(errors.seen).toHaveLength(1));
+      expect(screen.getByTestId("skeleton")).toBeDefined();
+      first.unmount();
+      online = true;
+      render(<D />);
+      await waitFor(() => expect(screen.getByTestId("heavy")).toBeDefined());
+    } finally {
+      move.restore();
+      errors.restore();
+    }
+  });
+
+  test("with ssr:true, a removed chunk moves the page instead of throwing", async () => {
+    const move = stubMove("moving");
+    const errors = quietErrors();
+    try {
+      const D = dynamic(async () => {
+        throw new TypeError("Failed to fetch dynamically imported module");
+      }, { ssr: true, loading: Skeleton });
+      render(<D />);
+      await waitFor(() => expect(move.calls).toHaveLength(1));
+      await new Promise((r) => setTimeout(r, 20));
+      expect(screen.getByTestId("skeleton")).toBeDefined();
+    } finally {
+      move.restore();
+      errors.restore();
+    }
+  });
+});
+
 describe("dynamic() with ssr:true", () => {
   test("server-renders the real component", async () => {
     const D = dynamic(async () => ({ default: Heavy }), {

package/src/dynamic.tsx

@@ -26,6 +26,7 @@ import React, {
   useState,
   type ComponentType,
 } from "react";
+import { appUpdate } from "./appUpdate";
 
 export interface DynamicOptions {
   /** Rendered while the chunk loads (and, when `ssr` is false, on the server). */
@@ -47,6 +48,21 @@ export interface DynamicOptions {
 type Loader<P> = () => Promise<{ default: ComponentType<P> } | ComponentType<P>>;
 
 /** A module namespace or the component itself — accept both, like Next. */
+/**
+ * A chunk failed to load. After a deploy the server no longer has this
+ * build's chunks: move the page to the new build (an app with `offline`
+ * only; see `moveToLatestBuild`). Resolves true when the page is about to
+ * load the new build. Offline, or with the server on this build, the page
+ * stays as it is.
+ */
+async function movedAfterChunkError(): Promise<boolean> {
+  try {
+    return (await appUpdate.moveToLatestBuild({ recheck: true })) === "moving";
+  } catch {
+    return false;
+  }
+}
+
 function resolveComponent<P>(
   mod: { default: ComponentType<P> } | ComponentType<P>,
 ): ComponentType<P> {
@@ -78,7 +94,15 @@ export function dynamic<P extends object>(
     // saving — the component is in the tree the server rendered — so this is
     // for splitting code, not weight.
     const Lazy = lazy(async () => {
-      const mod = await loader();
+      let mod: Awaited<ReturnType<Loader<P>>>;
+      try {
+        mod = await loader();
+      } catch (err) {
+        // The page is loading the new build: keep the fallback up until it
+        // unloads, rather than handing the error to an error boundary.
+        if (await movedAfterChunkError()) return new Promise<never>(() => {});
+        throw err;
+      }
       return { default: resolveComponent<P>(mod) as ComponentType<any> };
     });
     const WithSuspense = (props: P) => (
@@ -95,9 +119,17 @@ export function dynamic<P extends object>(
   // real component swaps in from an effect, which never runs during SSR.
   //
   // The promise is cached on first use so remounts don't refetch, and so two
-  // instances of the same dynamic component share one request.
+  // instances of the same dynamic component share one request. A failed load
+  // is not kept: the next mount tries again (offline, then back online).
   let cached: Promise<ComponentType<P>> | null = null;
-  const load = () => (cached ??= Promise.resolve(loader()).then(resolveComponent<P>));
+  const load = () =>
+    (cached ??= Promise.resolve()
+      .then(loader)
+      .then(resolveComponent<P>)
+      .catch((err) => {
+        cached = null;
+        throw err;
+      }));
 
   const ClientOnly = (props: P) => {
     const [Loaded, setLoaded] = useState<ComponentType<P> | null>(null);
@@ -110,9 +142,12 @@ export function dynamic<P extends object>(
           if (alive) setLoaded(() => C);
         },
         (err) => {
-          // A chunk that fails to load (deploy mid-session, offline) leaves
-          // the fallback up rather than blanking the subtree.
-          console.error("[pylon] dynamic() failed to load a component:", err);
+          // A chunk that fails to load leaves the fallback up rather than
+          // blanking the subtree. After a deploy the page moves to the new
+          // build; offline it keeps the fallback.
+          void movedAfterChunkError().then((moving) => {
+            if (!moving) console.error("[pylon] dynamic() failed to load a component:", err);
+          });
         },
       );
       return () => {

package/src/index.ts

@@ -212,8 +212,14 @@ 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 { createAppUpdate, AppUpdater, moveToLatestBuild } from "./appUpdate";
+export type {
+  AppBuild,
+  AppUpdateState,
+  AppUpdateEnv,
+  BuildMove,
+  MoveOptions,
+} from "./appUpdate";
 
 // One-liner API
 export { db, init, getSync, setSessionToken } from "./db";