@carlonicora/nextjs-jsonapi 6.19.0 → 6.20.1

package/src/features/analytics/contexts/__tests__/AnalyticsAdminContext.spec.tsx

@@ -1,6 +1,7 @@
 import { act, fireEvent, render, screen, waitFor } from "@testing-library/react";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { useSharedContext } from "../../../../contexts/SharedContext";
+import { formatLocalDate } from "../../../../core";
 import { AnalyticsAdminService } from "../../data/AnalyticsAdminService";
 import { AnalyticsAdminProvider, useAnalyticsAdmin } from "../AnalyticsAdminContext";
 
@@ -10,6 +11,7 @@ vi.mock("../../data/AnalyticsAdminService", () => ({
     getTimeline: vi.fn(async () => []),
     getBreakdown: vi.fn(async () => []),
     getSessions: vi.fn(async () => []),
+    getDailyUniques: vi.fn(async () => []),
     next: vi.fn(async () => []),
   },
 }));
@@ -31,6 +33,8 @@ function Probe() {
       <span data-testid="sessions">{ctx.sessions.map((s) => s.id).join(",")}</span>
       <span data-testid="has-more">{String(ctx.hasMoreSessions)}</span>
       <span data-testid="section">{ctx.filters.section}</span>
+      <span data-testid="daily-uniques">{ctx.dailyUniques.map((d) => d.id).join(",")}</span>
+      <span data-testid="error">{ctx.error ?? ""}</span>
       <button type="button" onClick={() => ctx.setFilters({ section: "app" })}>
         app
       </button>
@@ -86,6 +90,40 @@ describe("AnalyticsAdminContext", () => {
     expect(breakdowns).toHaveLength(6);
   });
 
+  it("requests the daily uniques once with the local calendar dates of the range and exposes them", async () => {
+    vi.mocked(AnalyticsAdminService.getDailyUniques).mockResolvedValueOnce([
+      { id: "2026-11-03" },
+      { id: "2026-11-04" },
+    ] as any);
+
+    render(
+      <AnalyticsAdminProvider>
+        <Probe />
+      </AnalyticsAdminProvider>,
+    );
+
+    await waitFor(() => expect(screen.getByTestId("daily-uniques")).toHaveTextContent("2026-11-03,2026-11-04"));
+
+    expect(AnalyticsAdminService.getDailyUniques).toHaveBeenCalledTimes(1);
+    const { from, to } = vi.mocked(AnalyticsAdminService.getSummary).mock.calls[0][0];
+    expect(AnalyticsAdminService.getDailyUniques).toHaveBeenCalledWith({
+      fromDate: formatLocalDate(new Date(from)),
+      toDate: formatLocalDate(new Date(to)),
+    });
+  });
+
+  it("sets the page error when the daily uniques request fails", async () => {
+    vi.mocked(AnalyticsAdminService.getDailyUniques).mockRejectedValueOnce(new Error("daily uniques failed"));
+
+    render(
+      <AnalyticsAdminProvider>
+        <Probe />
+      </AnalyticsAdminProvider>,
+    );
+
+    await waitFor(() => expect(screen.getByTestId("error")).toHaveTextContent("daily uniques failed"));
+  });
+
   it("defaults to the last 30 days", async () => {
     render(
       <AnalyticsAdminProvider>

package/src/features/analytics/data/AnalyticsAdminService.ts

@@ -1,5 +1,6 @@
 import { AbstractService, EndpointCreator, HttpMethod, Modules, NextRef } from "../../../core";
 import { AnalyticsBreakdownInterface } from "./analytics-breakdown.interface";
+import { AnalyticsDailyUniqueTimelineInterface } from "./analytics-daily-unique-timeline.interface";
 import { AnalyticsPageViewInterface } from "./analytics-page-view.interface";
 import { AnalyticsSessionInterface } from "./analytics-session.interface";
 import { AnalyticsSummaryInterface } from "./analytics-summary.interface";
@@ -38,6 +39,25 @@ export class AnalyticsAdminService extends AbstractService {
     });
   }
 
+  /**
+   * One row per calendar day from fromDate to toDate (YYYY-MM-DD, local dates).
+   * Always daily and never filtered by section, so it skips withFilters.
+   */
+  static async getDailyUniques(params: {
+    fromDate: string;
+    toDate: string;
+  }): Promise<AnalyticsDailyUniqueTimelineInterface[]> {
+    const endpoint = new EndpointCreator({ endpoint: Modules.AnalyticsDailyUniqueTimeline });
+    endpoint.addAdditionalParam("fromDate", params.fromDate);
+    endpoint.addAdditionalParam("toDate", params.toDate);
+
+    return this.callApi<AnalyticsDailyUniqueTimelineInterface[]>({
+      type: Modules.AnalyticsDailyUniqueTimeline,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+    });
+  }
+
   static async getBreakdown(
     params: AnalyticsFilters & { dimension: AnalyticsDimension; limit?: number },
   ): Promise<AnalyticsBreakdownInterface[]> {

package/src/features/analytics/data/__tests__/AnalyticsAdminService.spec.ts

@@ -114,4 +114,19 @@ describe("AnalyticsAdminService", () => {
     expect(call.method).toBe("GET");
     expect(call.endpoint).toBe("analytics/administration/sessions/s1/pageviews");
   });
+  it("getDailyUniques sends only fromDate and toDate to the daily-uniques endpoint, never the section filters", async () => {
+    const spy = callApi();
+
+    await AnalyticsAdminService.getDailyUniques({ fromDate: "2026-10-05", toDate: "2026-11-04" });
+
+    const call = firstCall(spy);
+    expect(call.type).toBe(ModuleRegistry.get("AnalyticsDailyUniqueTimeline" as any));
+    expect(call.method).toBe("GET");
+    expect(call.endpoint).toContain("analytics/administration/daily-uniques");
+    expect(call.endpoint).toContain("fromDate=2026-10-05");
+    expect(call.endpoint).toContain("toDate=2026-11-04");
+    expect(call.endpoint).not.toContain("section");
+    expect(call.endpoint).not.toMatch(/[?&]from=/);
+    expect(call.endpoint).not.toMatch(/[?&]to=/);
+  });
 });

package/src/features/analytics/data/__tests__/models.spec.ts

@@ -7,6 +7,7 @@ import { AbstractApiData } from "../../../../core/abstracts/AbstractApiData";
 import { JsonApiHydratedDataInterface } from "../../../../core/interfaces/JsonApiHydratedDataInterface";
 import { analyticsModules } from "../../analytics.modules";
 import { AnalyticsBreakdown } from "../analytics-breakdown";
+import { AnalyticsDailyUniqueTimeline } from "../analytics-daily-unique-timeline";
 import { AnalyticsEvent } from "../analytics-event";
 import { AnalyticsPageView } from "../analytics-page-view";
 import { AnalyticsSession } from "../analytics-session";
@@ -89,6 +90,26 @@ describe("analytics models — rehydrate", () => {
     expect(m.pageViews).toBe(3);
   });
 
+  it("rehydrates a daily-unique row: the day into a UTC-midnight Date and both counts", () => {
+    const m = new AnalyticsDailyUniqueTimeline().rehydrate(hydrate({ day: "2026-11-03", visitors: 3, users: 1 }));
+    expect(m.day).toBeInstanceOf(Date);
+    expect(m.day.getTime()).toBe(new Date("2026-11-03").getTime());
+    expect(m.visitors).toBe(3);
+    expect(m.users).toBe(1);
+  });
+
+  it("rehydrates an unknown daily-unique count to null, whether sent as null or missing", () => {
+    const m = new AnalyticsDailyUniqueTimeline().rehydrate(hydrate({ day: "2026-11-03", visitors: null }));
+    expect(m.visitors).toBeNull();
+    expect(m.users).toBeNull();
+  });
+
+  it("keeps a zero daily-unique count as 0, not null", () => {
+    const m = new AnalyticsDailyUniqueTimeline().rehydrate(hydrate({ day: "2026-11-03", visitors: 0, users: 0 }));
+    expect(m.visitors).toBe(0);
+    expect(m.users).toBe(0);
+  });
+
   it("rehydrates every breakdown attribute", () => {
     const m = new AnalyticsBreakdown().rehydrate(
       hydrate({ dimension: "source", key: "linkedin", visitors: 4, sessions: 5, pageViews: 6 }),
@@ -254,6 +275,14 @@ describe("analytics models — createJsonApi", () => {
     expect(JSON.parse(JSON.stringify(doc)).data.attributes.bucket).toBe("2026-09-01");
   });
 
+  it("emits the daily-unique day as YYYY-MM-DD via formatLocalDate, never a raw Date", () => {
+    const doc = new AnalyticsDailyUniqueTimeline().createJsonApi({ id: "2026-11-03", day: new Date(2026, 10, 3) });
+    expect(doc.data.type).toBe("analytics/administration/daily-uniques");
+    expect(doc.data.id).toBe("2026-11-03");
+    expect(doc.data.attributes.day).toBe("2026-11-03");
+    expect(JSON.parse(JSON.stringify(doc)).data.attributes.day).toBe("2026-11-03");
+  });
+
   it("serialises a breakdown row", () => {
     const doc = new AnalyticsBreakdown().createJsonApi({
       id: "source|linkedin",

package/src/features/analytics/data/analytics-daily-unique-timeline.interface.ts

@@ -0,0 +1,11 @@
+import { ApiDataInterface } from "../../../core";
+
+/** One calendar day of the unique visitors / unique users charts. */
+export interface AnalyticsDailyUniqueTimelineInterface extends ApiDataInterface {
+  /** Backend declares this `type: "date"`, so it is a Date in memory. */
+  get day(): Date;
+  /** null = unknown for that day (drawn as a gap). */
+  get visitors(): number | null;
+  /** null = unknown for that day (drawn as a gap). */
+  get users(): number | null;
+}

package/src/features/analytics/data/analytics-daily-unique-timeline.ts

@@ -0,0 +1,53 @@
+import { AbstractApiData, formatLocalDate, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { AnalyticsDailyUniqueTimelineInterface } from "./analytics-daily-unique-timeline.interface";
+import { AnalyticsDailyUniqueTimelineInput } from "./analytics.types";
+
+/** One day of the daily unique visitors / users charts. A null count is an unknown day, never 0. */
+export class AnalyticsDailyUniqueTimeline extends AbstractApiData implements AnalyticsDailyUniqueTimelineInterface {
+  private _day: Date = new Date(0);
+  private _visitors: number | null = null;
+  private _users: number | null = null;
+
+  get day(): Date {
+    return this._day;
+  }
+
+  get visitors(): number | null {
+    return this._visitors;
+  }
+
+  get users(): number | null {
+    return this._users;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attrs = data.jsonApi.attributes;
+    // Wire format is "YYYY-MM-DD" (always present); the interface promises a Date.
+    this._day = new Date(attrs.day);
+    this._visitors = attrs.visitors ?? null;
+    this._users = attrs.users ?? null;
+
+    return this;
+  }
+
+  createJsonApi(data: AnalyticsDailyUniqueTimelineInput) {
+    const response: any = {
+      data: {
+        type: Modules.AnalyticsDailyUniqueTimeline.name,
+        id: data.id,
+        attributes: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    // `day` is type: "date" on the backend descriptor: formatLocalDate, never the raw Date.
+    if (data.day !== undefined) response.data.attributes.day = formatLocalDate(data.day);
+    if (data.visitors !== undefined) response.data.attributes.visitors = data.visitors;
+    if (data.users !== undefined) response.data.attributes.users = data.users;
+
+    return response;
+  }
+}

package/src/features/analytics/data/analytics.types.ts

@@ -59,6 +59,16 @@ export type AnalyticsTimelineInput = {
   pageViews: number;
 };
 
+export type AnalyticsDailyUniqueTimelineInput = {
+  id: string;
+  /** Backend field type is "date" — emitted via formatLocalDate, never raw. */
+  day?: Date;
+  /** null = unknown for that day. */
+  visitors?: number | null;
+  /** null = unknown for that day. */
+  users?: number | null;
+};
+
 export type AnalyticsBreakdownInput = {
   id: string;
   dimension: string;

package/src/features/analytics/data/index.ts

@@ -5,6 +5,8 @@ export { AnalyticsSummary } from "./analytics-summary";
 export type { AnalyticsSummaryInterface } from "./analytics-summary.interface";
 export { AnalyticsTimeline } from "./analytics-timeline";
 export type { AnalyticsTimelineInterface } from "./analytics-timeline.interface";
+export { AnalyticsDailyUniqueTimeline } from "./analytics-daily-unique-timeline";
+export type { AnalyticsDailyUniqueTimelineInterface } from "./analytics-daily-unique-timeline.interface";
 export { AnalyticsBreakdown } from "./analytics-breakdown";
 export type { AnalyticsBreakdownInterface } from "./analytics-breakdown.interface";
 export { AnalyticsSession } from "./analytics-session";

package/src/features/analytics/i18n-keys.ts

@@ -38,6 +38,8 @@ export const ANALYTICS_ADMIN_I18N_KEYS = [
   "analytics.admin.panels.sessions",
   "analytics.admin.panels.journey",
   "analytics.admin.panels.other_sessions",
+  "analytics.admin.panels.daily_visitors",
+  "analytics.admin.panels.daily_users",
 
   // Breakdown tabs
   "analytics.admin.dimensions.source",
@@ -73,4 +75,10 @@ export const ANALYTICS_ADMIN_I18N_KEYS = [
   // Timeline chart series
   "analytics.admin.series.visitors",
   "analytics.admin.series.page_views",
+
+  // Daily uniques charts
+  "analytics.admin.daily_uniques.visitors",
+  "analytics.admin.daily_uniques.users",
+  "analytics.admin.daily_uniques.today",
+  "analytics.admin.daily_uniques.no_data",
 ] as const;

package/src/features/analytics/index.ts

@@ -18,6 +18,7 @@ export { AnalyticsAdminContainer } from "./components/AnalyticsAdminContainer";
 export { AnalyticsAdminFilterBar } from "./components/AnalyticsAdminFilterBar";
 export { AnalyticsAdminTiles } from "./components/AnalyticsAdminTiles";
 export { AnalyticsTimelineChart } from "./components/AnalyticsTimelineChart";
+export { AnalyticsDailyUniquesChart } from "./components/AnalyticsDailyUniquesChart";
 export { AnalyticsBreakdownTable } from "./components/AnalyticsBreakdownTable";
 export { AnalyticsSessionsTable } from "./components/AnalyticsSessionsTable";
 export { AnalyticsJourneyContainer } from "./components/AnalyticsJourneyContainer";

package/src/offline/server/build-offline-manifest.ts

@@ -19,9 +19,10 @@ async function listFiles(dir: string): Promise<string[]> {
  * Describes the running build for the service worker's offline shell precache
  * (`/offline-manifest.json`): the build id from `<distDir>/BUILD_ID` and every
  * file under `<distDir>/static`, as the `/_next/static/...` URL Next serves it at.
- * `next dev` writes no BUILD_ID (its folder is `.next/dev`): the id is then derived from the
- * asset list, whose chunk names carry content hashes, so an edit gives a new id and the
- * service worker refreshes the shell.
+ * `next dev` writes no BUILD_ID (its folder is `.next/dev`): the id is then `dev-` plus a hash
+ * of the asset list. Dev chunk names do NOT carry content hashes (an edit rewrites a chunk under
+ * the same name), so the id changes only when files appear or disappear; the service worker
+ * therefore serves `/_next/static/` network first for a `dev-` build (pwa/sw.js).
  * `distDir` must be the value the app's next.config uses. `extraAssets` are further same-origin
  * URLs the shell needs with no network (the SQLite files the device worker loads).
  */

package/src/offline/sync/__tests__/sync-root.spec.ts

@@ -23,7 +23,7 @@ vi.mock("../../../unified/JsonApiRequest", () => ({
   buildUrl: (endpoint: string) => `http://api.test/${endpoint}`,
 }));
 
-import { syncAll, syncRoot } from "../sync-root";
+import { SYNC_FETCH_CONCURRENCY, syncAll, syncRoot } from "../sync-root";
 import { getOfflineState, subscribeOfflineState } from "../../state";
 
 type Answer = { ok: boolean; response: number; raw?: any; data?: any };
@@ -169,9 +169,9 @@ describe("syncRoot", () => {
     await syncRoot("C");
 
     const endpoints = JsonApiGet.mock.calls.map((call) => call[0].endpoint);
-    expect(endpoints).toEqual([
-      "roots/C/sync",
-      "roots/C",
+    // The sync answer, then the root record; the other reads run concurrently, in any order.
+    expect(endpoints.slice(0, 2)).toEqual(["roots/C/sync", "roots/C"]);
+    expect([...endpoints.slice(2)].sort()).toEqual([
       "roots/C/npcs?fetchAll=true&updatedSince=2026-10-31T00:00:00.000Z",
       "templates/t1",
     ]);
@@ -612,12 +612,13 @@ describe("syncRoot", () => {
     await syncRoot("C");
 
     const calls = JsonApiGet.mock.calls.map((call) => call[0]);
-    expect(calls.map((call) => call.endpoint)).toEqual([
-      "roots/C/sync",
-      "roots/C/sessions/s1/player-notes",
+    // The target reads run concurrently, in any order.
+    expect(calls[0].endpoint).toBe("roots/C/sync");
+    expect(calls.slice(1).map((call) => call.endpoint).sort()).toEqual([
       "roots/C/clues/k1/player-notes",
+      "roots/C/sessions/s1/player-notes",
     ]);
-    expect(calls[1].classKey).toBe(PlayerNotes);
+    expect(calls.slice(1).every((call) => call.classKey === PlayerNotes)).toBe(true);
     expect((await store.getRecord("player-notes", "p1"))?.updatedAt).toEqual(new Date("2026-10-31T10:00:00.000Z"));
     expect(await store.getRecord("player-notes", "p3")).toBeDefined();
     expect(await store.getRecord("player-notes", "p2")).toBeUndefined();
@@ -626,6 +627,85 @@ describe("syncRoot", () => {
     warn.mockRestore();
   });
 
+  it(`keeps at most SYNC_FETCH_CONCURRENCY (${SYNC_FETCH_CONCURRENCY}) record reads in flight at once`, async () => {
+    const ids = ["t1", "t2", "t3", "t4", "t5", "t6", "t7", "t8"];
+    const pending: (() => void)[] = [];
+    let inFlight = 0;
+    let maxInFlight = 0;
+    JsonApiGet.mockImplementation(async ({ endpoint }: { endpoint: string }) => {
+      if (endpoint === "roots/C/sync") return syncAnswer({ entries: ids.map((id) => entry("templates", id)) });
+      inFlight += 1;
+      maxInFlight = Math.max(maxInFlight, inFlight);
+      await new Promise<void>((resolve) => pending.push(resolve));
+      inFlight -= 1;
+      const id = endpoint.split("/")[1];
+      return oneAnswer({ type: "templates", id, attributes: { name: id } });
+    });
+
+    const running = syncRoot("C");
+    await vi.waitFor(() => expect(pending).toHaveLength(SYNC_FETCH_CONCURRENCY));
+    for (let released = 0; released < ids.length; released += 1) {
+      await vi.waitFor(() => expect(pending.length).toBeGreaterThan(0));
+      pending.shift()!();
+    }
+    await running;
+
+    expect(maxInFlight).toBe(SYNC_FETCH_CONCURRENCY);
+    expect(JsonApiGet).toHaveBeenCalledTimes(1 + ids.length);
+    for (const id of ids) expect((await store.getRecord("templates", id))?.resource.attributes.name).toBe(id);
+  });
+
+  it("finishes the root record's read before any other type's read starts", async () => {
+    const events: string[] = [];
+    JsonApiGet.mockImplementation(async ({ endpoint }: { endpoint: string }) => {
+      if (endpoint === "roots/C/sync") {
+        return syncAnswer({ entries: [entry("roots", "C"), entry("npcs", "n1"), entry("templates", "t1")] });
+      }
+      events.push(`start ${endpoint}`);
+      if (endpoint === "roots/C") {
+        await new Promise((resolve) => setTimeout(resolve, 5));
+        events.push(`end ${endpoint}`);
+        return oneAnswer({ type: "roots", id: "C", attributes: { name: "Camp" } });
+      }
+      events.push(`end ${endpoint}`);
+      if (endpoint === "roots/C/npcs?fetchAll=true") return listAnswer([npc("n1", "Alda")]);
+      if (endpoint === "templates/t1") return oneAnswer({ type: "templates", id: "t1", attributes: { name: "T" } });
+      throw new Error(`unexpected GET ${endpoint}`);
+    });
+
+    await syncRoot("C");
+
+    expect(events.slice(0, 2)).toEqual(["start roots/C", "end roots/C"]);
+    expect(events).toHaveLength(6);
+    expect(await store.getRecord("npcs", "n1")).toBeDefined();
+    expect(await store.getRecord("templates", "t1")).toBeDefined();
+  });
+
+  it("a failing read (not 403/404) stops the sync: no new read starts and nothing is written", async () => {
+    const ids = ["t1", "t2", "t3", "t4", "t5", "t6", "t7", "t8"];
+    const pending: (() => void)[] = [];
+    JsonApiGet.mockImplementation(async ({ endpoint }: { endpoint: string }) => {
+      if (endpoint === "roots/C/sync") {
+        return syncAnswer({ entries: [entry("npcs", "n1"), ...ids.map((id) => entry("templates", id))] });
+      }
+      if (endpoint === "templates/t1") return statusAnswer(500);
+      await new Promise<void>((resolve) => pending.push(resolve));
+      if (endpoint === "roots/C/npcs?fetchAll=true") return listAnswer([npc("n1", "Alda")]);
+      const id = endpoint.split("/")[1];
+      return oneAnswer({ type: "templates", id, attributes: { name: id } });
+    });
+
+    await expect(syncRoot("C")).rejects.toThrow("templates/t1 answered 500");
+
+    // The reads already in flight finish; their results are discarded and nothing more is asked.
+    for (const release of pending.splice(0)) release();
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    expect(JsonApiGet).toHaveBeenCalledTimes(1 + SYNC_FETCH_CONCURRENCY);
+    expect((await store.getSyncState("C")).serverTime).toBeNull();
+    expect(await store.getRecord("npcs", "n1")).toBeUndefined();
+    for (const id of ids) expect(await store.getRecord("templates", id)).toBeUndefined();
+  });
+
   it("a locked answer stores locked and downloads nothing", async () => {
     serve({
       "roots/C/sync": syncAnswer({ locked: true, lockedFrom: "2026-10-30T00:00:00.000Z", entries: [], links: [] }),

package/src/offline/sync/sync-root.ts

@@ -46,6 +46,49 @@ async function fetchResources(
   return Array.isArray(data) ? data : [data];
 }
 
+/** How many record reads one root record's sync keeps in flight at once (after the root record). */
+export const SYNC_FETCH_CONCURRENCY = 4;
+
+type FetchTask = () => Promise<void>;
+
+/**
+ * Runs the tasks with at most `limit` in flight, starting them in list order. After the first
+ * rejection no new task starts and the returned promise rejects with that error; tasks already in
+ * flight may still finish, their outcome is ignored.
+ */
+async function runWithConcurrency(tasks: FetchTask[], limit: number): Promise<void> {
+  if (tasks.length === 0) return;
+  await new Promise<void>((resolve, reject) => {
+    let next = 0;
+    let active = 0;
+    let failed = false;
+    const launch = (): void => {
+      if (failed) return;
+      if (next >= tasks.length && active === 0) {
+        resolve();
+        return;
+      }
+      while (active < limit && next < tasks.length) {
+        const task = tasks[next++];
+        active += 1;
+        new Promise<void>((done) => done(task())).then(
+          () => {
+            active -= 1;
+            launch();
+          },
+          (error) => {
+            active -= 1;
+            if (failed) return;
+            failed = true;
+            reject(error);
+          },
+        );
+      }
+    };
+    launch();
+  });
+}
+
 async function imagesOfRoot(store: DeviceStore, rootId: string): Promise<{ type: string; id: string; url: string }[]> {
   const images: { type: string; id: string; url: string }[] = [];
   for (const typeConfig of getOfflineConfig().types) {
@@ -73,8 +116,10 @@ async function removeRootIfIdle(store: DeviceStore, rootId: string): Promise<voi
 /**
  * Brings one root record's device copy up to date with the sync answer (C2): records changed since
  * the stored server time are fetched (C3), records gone from the root record are deleted, the links
- * are replaced, and artwork images are downloaded. The sync state is stored only once every
- * fetch succeeded (or answered 403/404). A record with a waiting change is never overwritten.
+ * are replaced, and artwork images are downloaded. The root record is fetched first; the other
+ * reads then run up to SYNC_FETCH_CONCURRENCY at a time. The sync state is stored only once every
+ * fetch succeeded (or answered 403/404); the first failure stops the sync before anything is
+ * written. A record with a waiting change is never overwritten.
  */
 export async function syncRoot(rootId: string, kind?: OfflineRootKind): Promise<void> {
   const config = getOfflineConfig();
@@ -148,13 +193,10 @@ export async function syncRoot(rootId: string, kind?: OfflineRootKind): Promise<
   // Records the answers include whose type the device does not sync itself (the root record's
   // owner): kept for display only, so a local answer can include them as the server does.
   const included: any[] = [];
-  // The root record of the kind is fetched before the other types: a kind's `typeEndpoints` are
-  // built from it.
+  // The root record of the kind is fetched first and alone: a kind's `typeEndpoints` are built
+  // from it. Every other read (each type's list, each by-id record, each linked-list target) then
+  // runs as one flat task list, at most SYNC_FETCH_CONCURRENCY in flight.
   const rootTypeName = rootKind.module.name;
-  const orderedTypes = [
-    ...config.types.filter((typeConfig) => typeConfig.module.name === rootTypeName),
-    ...config.types.filter((typeConfig) => typeConfig.module.name !== rootTypeName),
-  ];
   const rootResource = async (): Promise<StoredRecord["resource"]> => {
     const fresh = fetched.find((resource) => resource?.type === rootTypeName && resource?.id === rootId);
     if (fresh) return fresh;
@@ -162,16 +204,21 @@ export async function syncRoot(rootId: string, kind?: OfflineRootKind): Promise<
     if (storedRoot) return storedRoot.resource;
     throw new Error(`[offline] ${rootTypeName} ${rootId}: the root record is needed to build the type endpoints`);
   };
-  for (const typeConfig of orderedTypes) {
+  const fetchTasksOf = (typeConfig: (typeof config.types)[number]): FetchTask[] => {
     const changedOfType = changed.filter((entry) => entry.type === typeConfig.module.name);
-    if (changedOfType.length === 0) continue;
+    if (changedOfType.length === 0) return [];
 
     const typeEndpoint = rootKind.typeEndpoints?.find((candidate) => candidate.module.name === typeConfig.module.name);
     if (typeEndpoint) {
       // One full list read under this kind, never with `updatedSince`.
-      const endpoint = typeEndpoint.endpoint({ id: rootId, resource: await rootResource() });
-      fetched.push(...(await fetchResources(typeConfig.module, endpoint, skipped, included)));
-    } else if (typeConfig.fetch === "root-list") {
+      return [
+        async () => {
+          const endpoint = typeEndpoint.endpoint({ id: rootId, resource: await rootResource() });
+          fetched.push(...(await fetchResources(typeConfig.module, endpoint, skipped, included)));
+        },
+      ];
+    }
+    if (typeConfig.fetch === "root-list") {
       // One list read per type. With `updatedSince` when every changed record is inside the
       // window; without it when a record older than the window is missing or stale on the
       // device, so the whole list comes in the same single request (never one read per record).
@@ -181,8 +228,14 @@ export async function syncRoot(rootId: string, kind?: OfflineRootKind): Promise<
         childEndpoint: typeConfig.module,
       }).addAdditionalParam("fetchAll", "true");
       if (since && changedOfType.every(inWindow)) endpoint.addAdditionalParam("updatedSince", since.toISOString());
-      fetched.push(...(await fetchResources(typeConfig.module, endpoint.generate(), skipped, included)));
-    } else if (typeConfig.fetch === "linked-list") {
+      const generated = endpoint.generate();
+      return [
+        async () => {
+          fetched.push(...(await fetchResources(typeConfig.module, generated, skipped, included)));
+        },
+      ];
+    }
+    if (typeConfig.fetch === "linked-list") {
       // Read only as a list per target: the targets are the other ends of the changed records'
       // sync links of `linkKind`; each target's list is read once, and only the type's entries kept.
       if (!typeConfig.linkedList) throw new Error(`[offline] ${typeConfig.module.name}: linked-list needs linkedList`);
@@ -194,19 +247,22 @@ export async function syncRoot(rootId: string, kind?: OfflineRootKind): Promise<
           continue;
         targets.set(keyOf(link.toType, link.toId), { type: link.toType, id: link.toId });
       }
-      for (const target of targets.values()) {
+      return [...targets.values()].map((target) => async () => {
         const resources = await fetchResources(typeConfig.module, endpoint(rootId, target), skipped, included);
         fetched.push(
           ...resources.filter((resource) => resource?.type === typeConfig.module.name && changedIds.has(resource.id)),
         );
-      }
-    } else {
-      for (const entry of changedOfType) {
-        const endpoint = new EndpointCreator({ endpoint: typeConfig.module, id: entry.id }).generate();
-        fetched.push(...(await fetchResources(typeConfig.module, endpoint, skipped, included)));
-      }
+      });
     }
-  }
+    return changedOfType.map((entry) => async () => {
+      const endpoint = new EndpointCreator({ endpoint: typeConfig.module, id: entry.id }).generate();
+      fetched.push(...(await fetchResources(typeConfig.module, endpoint, skipped, included)));
+    });
+  };
+  const rootTypes = config.types.filter((typeConfig) => typeConfig.module.name === rootTypeName);
+  const otherTypes = config.types.filter((typeConfig) => typeConfig.module.name !== rootTypeName);
+  await runWithConcurrency(rootTypes.flatMap(fetchTasksOf), SYNC_FETCH_CONCURRENCY);
+  await runWithConcurrency(otherTypes.flatMap(fetchTasksOf), SYNC_FETCH_CONCURRENCY);
 
   const fetchedKeys = new Set(fetched.map((resource) => keyOf(resource?.type, resource?.id)));
   const previousImageUrls = new Map<string, string>();

package/src/pwa/__tests__/sw.spec.ts

@@ -463,14 +463,18 @@ describe("pwa/sw.js", () => {
       expect(deleted).toEqual(["test-images", "test-shell-build-1"]);
     });
 
-    function shellWorker(shellEntries: Record<string, Response | undefined>, offlinePage?: Response) {
+    function shellWorker(
+      shellEntries: Record<string, Response | undefined>,
+      offlinePage?: Response,
+      buildId: string = "build-2",
+    ) {
       const worker = loadWorker(SHELL_CONFIG);
       const entries: Record<string, Response | undefined> = { [SHELL_COMPLETE_URL]: new Response(""), ...shellEntries };
       const shellCache = makeCache({ match: vi.fn(async (url: string) => entries[url]) });
       const offlineCache = makeCache({ match: vi.fn().mockResolvedValue(offlinePage) });
-      worker.sandbox.caches.keys.mockResolvedValue(["test-offline-abc12345", "test-shell-build-2"]);
+      worker.sandbox.caches.keys.mockResolvedValue(["test-offline-abc12345", `test-shell-${buildId}`]);
       worker.sandbox.caches.open.mockImplementation(async (name: string) =>
-        name === "test-shell-build-2" ? shellCache : offlineCache,
+        name === `test-shell-${buildId}` ? shellCache : offlineCache,
       );
       worker.sandbox.fetch.mockRejectedValue(new TypeError("Failed to fetch"));
       return { ...worker, shellCache, offlineCache };
@@ -563,6 +567,32 @@ describe("pwa/sw.js", () => {
       expect(sandbox.fetch).toHaveBeenCalledWith(missRequest);
     });
 
+    it("under next dev (a dev- build id) a GET under /_next/static/ goes to the network first, keeps the cache current, and falls back to the cache offline", async () => {
+      // next dev keeps a chunk's file name when its content changes: answering from the cache
+      // would hand the page a chunk of an earlier build next to the server's current ones.
+      const url = `${ORIGIN}/_next/static/chunks/a.js`;
+      const cachedChunk = new Response("cached chunk");
+      const { sandbox, dispatch, shellCache } = shellWorker({ [url]: cachedChunk }, undefined, "dev-0123456789abcdef");
+      const request = { method: "GET", mode: "no-cors", destination: "script", url };
+
+      const network = new Response("network chunk");
+      sandbox.fetch.mockResolvedValue(network);
+      const online = dispatch("fetch", { request });
+      expect(online.respondWith).toHaveBeenCalledTimes(1);
+      expect(await online.respondWithPromise).toBe(network);
+      expect(sandbox.fetch).toHaveBeenCalledWith(request);
+      expect(shellCache.put).toHaveBeenCalledTimes(1);
+      expect(shellCache.put.mock.calls[0][0]).toBe(url);
+      expect(await (shellCache.put.mock.calls[0][1] as Response).text()).toBe("network chunk");
+
+      sandbox.fetch.mockRejectedValue(new TypeError("Failed to fetch"));
+      const offline = dispatch("fetch", { request });
+      expect(await offline.respondWithPromise).toBe(cachedChunk);
+
+      const missing = dispatch("fetch", { request: { ...request, url: `${ORIGIN}/_next/static/chunks/missing.js` } });
+      expect(((await missing.respondWithPromise) as Response).type).toBe("error");
+    });
+
     it("another same-origin GET in the shell cache (the device worker, SQLite) goes to the network first and is answered from the cache when the network fails", async () => {
       const workerUrl = `${ORIGIN}/offline-sqlite/device-worker.mjs`;
       const cachedWorker = new Response("cached worker");