@carlonicora/nextjs-jsonapi 6.12.1 → 6.13.0

package/src/offline/__tests__/generic-answers.spec.ts

@@ -0,0 +1,380 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { buildGenericRoutes, linksOfKind, listAnswer } from "../generic-answers";
+import { matchRoute } from "../router";
+import { setOfflineState } from "../state";
+import type { DeviceStore } from "../store/DeviceStore";
+import type { OfflineAnswer, OfflineConfig, OfflineMethod } from "../types";
+import { npc, offlineConfig, seededStore } from "./offline-fixtures";
+
+const API = "http://api.test/";
+
+async function answer(
+  store: DeviceStore,
+  method: OfflineMethod,
+  relative: string,
+  body?: any,
+  config: OfflineConfig = offlineConfig(),
+): Promise<OfflineAnswer> {
+  const [path, query = ""] = relative.split("?");
+  const match = matchRoute(buildGenericRoutes(config), method, path);
+  if (!match) throw new Error(`no generic route for ${method} ${path}`);
+  return match.route.answer({
+    request: { method, path, query: new URLSearchParams(query), body, url: `${API}${relative}` },
+    params: match.params,
+    store,
+  });
+}
+
+describe("generic answers", () => {
+  let store: DeviceStore;
+
+  beforeEach(async () => {
+    store = await seededStore();
+  });
+
+  afterEach(() => {
+    setOfflineState({ lockedRootIds: [] });
+  });
+
+  it("GET npcs/:id answers the resource with the linked resources as included", async () => {
+    const result = await answer(store, "GET", "npcs/n1");
+
+    expect(result.status).toBe(200);
+    expect(result.body.data).toEqual(npc("n1", "Alda", "C"));
+    expect(result.body.included).toEqual([
+      { type: "factions", id: "f1", attributes: { name: "Guild" } },
+      { type: "roots", id: "C", attributes: { name: "Camp C" } },
+    ]);
+  });
+
+  it("included also follows the relationships of the record and of its included records to stored records (the root record, then its owner)", async () => {
+    await store.putRecord({
+      type: "roots",
+      id: "C",
+      rootId: "C",
+      resource: {
+        type: "roots",
+        id: "C",
+        attributes: { name: "Camp C" },
+        relationships: { owner: { data: { type: "users", id: "u1" } } },
+      },
+      updatedAt: null,
+    });
+    await store.putRecord({
+      type: "users",
+      id: "u1",
+      rootId: "C",
+      resource: { type: "users", id: "u1", attributes: { name: "The GM" } },
+      updatedAt: null,
+    });
+
+    const result = await answer(store, "GET", "npcs/n1");
+
+    expect(
+      result.body.included.map((resource: { type: string; id: string }) => `${resource.type}:${resource.id}`),
+    ).toEqual(["factions:f1", "roots:C", "users:u1"]);
+  });
+
+  it("GET npcs/:id of a record not on the device (or a literal endpoint with no answer) needs a connection", async () => {
+    for (const relative of ["npcs/missing", "npcs/playing"]) {
+      const result = await answer(store, "GET", relative);
+      expect(result.status).toBe(503);
+      expect(result.body.errors[0].code).toBe("needs-connection");
+    }
+  });
+
+  it("a list of a root record or parent that is not on the device needs a connection", async () => {
+    for (const relative of ["roots/X/npcs?fetchAll=true", "factions/missing/npcs?fetchAll=true"]) {
+      const result = await answer(store, "GET", relative);
+      expect(result.status).toBe(503);
+      expect(result.body.errors[0].code).toBe("needs-connection");
+    }
+  });
+
+  it("a stored parent with no linked records answers 200 with an empty list", async () => {
+    const result = await answer(store, "GET", "npcs/n2/factions?fetchAll=true");
+
+    expect(result.status).toBe(200);
+    expect(result.body.data).toEqual([]);
+  });
+
+  it("GET roots/C/npcs lists only C's NPCs", async () => {
+    const result = await answer(store, "GET", "roots/C/npcs?fetchAll=true");
+
+    expect(result.body.data.map((r: any) => r.id).sort()).toEqual(["n1", "n2"]);
+    expect(result.body.links).toEqual({ self: `${API}roots/C/npcs?fetchAll=true` });
+  });
+
+  it("honours search like the server's fulltext index: every token, case-insensitive, in any string attribute", async () => {
+    const byName = await answer(store, "GET", "roots/C/npcs?fetchAll=true&search=BRO");
+    const acrossFields = await answer(store, "GET", "roots/C/npcs?fetchAll=true&search=brom%20TEXT");
+    const noMatch = await answer(store, "GET", "roots/C/npcs?fetchAll=true&search=brom%20guild");
+
+    expect(byName.body.data.map((r: any) => r.id)).toEqual(["n2"]);
+    expect(acrossFields.body.data.map((r: any) => r.id)).toEqual(["n2"]);
+    expect(noMatch.body.data).toEqual([]);
+  });
+
+  it("honours orderBy as the server reads it: `field` or `field ASC|DESC`", async () => {
+    const ascending = await answer(store, "GET", "roots/C/npcs?fetchAll=true&orderBy=name");
+    const descending = await answer(store, "GET", "roots/C/npcs?fetchAll=true&orderBy=name%20DESC");
+    const explicitAsc = await answer(store, "GET", "roots/C/npcs?fetchAll=true&orderBy=name%20asc");
+
+    expect(ascending.body.data.map((r: any) => r.id)).toEqual(["n1", "n2"]);
+    expect(descending.body.data.map((r: any) => r.id)).toEqual(["n2", "n1"]);
+    expect(explicitAsc.body.data.map((r: any) => r.id)).toEqual(["n1", "n2"]);
+  });
+
+  it("an orderBy the server refuses (`-name`) answers 400 like the server", async () => {
+    expect((await answer(store, "GET", "roots/C/npcs?fetchAll=true&orderBy=-name")).status).toBe(400);
+  });
+
+  it("with no orderBy, lists in the server's default order (updatedAt DESC)", async () => {
+    const older = { ...npc("n1", "Alda", "C"), attributes: { name: "Alda", updatedAt: "2026-01-01T00:00:00.000Z" } };
+    const newer = { ...npc("n2", "brom", "C"), attributes: { name: "brom", updatedAt: "2026-02-01T00:00:00.000Z" } };
+    await store.putRecord({
+      type: "npcs",
+      id: "n1",
+      rootId: "C",
+      resource: older,
+      updatedAt: new Date("2026-01-01"),
+    });
+    await store.putRecord({
+      type: "npcs",
+      id: "n2",
+      rootId: "C",
+      resource: newer,
+      updatedAt: new Date("2026-02-01"),
+    });
+
+    const result = await answer(store, "GET", "roots/C/npcs?fetchAll=true");
+
+    expect(result.body.data.map((r: any) => r.id)).toEqual(["n2", "n1"]);
+  });
+
+  it("listAnswer pages, searches and orders any set of stored records for app answers", async () => {
+    const records = await store.listRecords({ type: "npcs", rootId: "C" });
+
+    const result = await listAnswer(
+      {
+        request: { method: "GET", path: "x", query: new URLSearchParams("orderBy=name%20DESC&page[size]=1") },
+        params: {},
+        store,
+      },
+      records,
+    );
+
+    expect(result.body.data.map((r: any) => r.id)).toEqual(["n2"]);
+    expect(result.body.meta.total).toBe(2);
+  });
+
+  it("pages with page[size]/page[offset] and links shaped like the server's", async () => {
+    const first = await answer(store, "GET", "roots/C/npcs?orderBy=name&page[size]=1");
+
+    expect(first.body.data.map((r: any) => r.id)).toEqual(["n1"]);
+    expect(first.body.links.self).toBe(`${API}roots/C/npcs?orderBy=name&page[size]=1`);
+    expect(first.body.links.next).toBe(`${API}roots/C/npcs?orderBy=name&page[size]=1&page[offset]=1`);
+    expect(first.body.links.prev).toBeUndefined();
+
+    const second = await answer(store, "GET", "roots/C/npcs?orderBy=name&page[size]=1&page[offset]=1");
+
+    expect(second.body.data.map((r: any) => r.id)).toEqual(["n2"]);
+    expect(second.body.links.next).toBeUndefined();
+    expect(second.body.links.prev).toBe(`${API}roots/C/npcs?orderBy=name&page[size]=1&page[offset]=0`);
+  });
+
+  it("GET factions/:id/npcs and npcs/:id/factions answer records linked in either direction", async () => {
+    const npcs = await answer(store, "GET", "factions/f1/npcs?fetchAll=true");
+    const factions = await answer(store, "GET", "npcs/n1/factions?fetchAll=true");
+
+    expect(npcs.body.data.map((r: any) => r.id)).toEqual(["n1"]);
+    expect(factions.body.data.map((r: any) => r.id)).toEqual(["f1"]);
+  });
+
+  it("POST npcs stores a local-only record, queues the body with base null and answers 201", async () => {
+    const body = { data: npc("n9", "New", "C") };
+
+    const result = await answer(store, "POST", "npcs", body);
+
+    expect(result.status).toBe(201);
+    expect(result.body.data).toEqual(npc("n9", "New", "C"));
+    expect(result.body.included).toEqual([{ type: "roots", id: "C", attributes: { name: "Camp C" } }]);
+    const stored = await store.getRecord("npcs", "n9");
+    expect(stored).toMatchObject({ rootId: "C", localOnly: true, base: null });
+    const [entry] = await store.queue();
+    expect(entry).toMatchObject({ rootId: "C", method: "POST", path: "npcs", body, base: null, status: "pending" });
+  });
+
+  it.each(["PATCH", "PUT"] as const)(
+    "%s npcs/:id applies the body, sets base once and queues the body untouched",
+    async (method) => {
+      const body = { data: { type: "npcs", id: "n1", attributes: { name: "Alda the Bold" } } };
+
+      const result = await answer(store, method, "npcs/n1", body);
+      await answer(store, method, "npcs/n1", { data: { type: "npcs", id: "n1", attributes: { name: "Alda II" } } });
+
+      expect(result.status).toBe(200);
+      expect(result.body.data.attributes).toEqual({ name: "Alda the Bold", description: "Alda text" });
+      expect(result.body.included.map((r: any) => `${r.type}:${r.id}`)).toEqual(["factions:f1", "roots:C"]);
+      const stored = await store.getRecord("npcs", "n1");
+      expect(stored?.resource.attributes.name).toBe("Alda II");
+      expect(stored?.base).toEqual(npc("n1", "Alda", "C"));
+      const entries = await store.queue();
+      expect(entries).toHaveLength(2);
+      expect(entries[0]).toMatchObject({
+        method,
+        path: "npcs/n1",
+        body,
+        recordType: "npcs",
+        recordId: "n1",
+        base: npc("n1", "Alda", "C"),
+      });
+      expect(entries[1].base).toEqual(npc("n1", "Alda", "C"));
+    },
+  );
+
+  it("DELETE npcs/:id removes the record and its links, queues it with base and answers 204", async () => {
+    const result = await answer(store, "DELETE", "npcs/n1");
+
+    expect(result).toEqual({ status: 204, body: undefined });
+    expect(await store.getRecord("npcs", "n1")).toBeUndefined();
+    expect(await store.linksFrom("f1")).toEqual([]);
+    const [entry] = await store.queue();
+    expect(entry).toMatchObject({
+      method: "DELETE",
+      path: "npcs/n1",
+      recordType: "npcs",
+      recordId: "n1",
+      base: npc("n1", "Alda", "C"),
+    });
+  });
+
+  describe("link kinds", () => {
+    const withKinds = (): OfflineConfig => {
+      const config = offlineConfig();
+      config.types = config.types.map((typeConfig) =>
+        typeConfig.module.name === "npcs" ? { ...typeConfig, relationshipKinds: { faction: "MEMBER_OF" } } : typeConfig,
+      );
+      return config;
+    };
+    const withFaction = (id: string, name: string, factionIds: string[]) => ({
+      ...npc(id, name, "C"),
+      relationships: {
+        root: { data: { type: "roots", id: "C" } },
+        faction: { data: factionIds.map((factionId) => ({ type: "factions", id: factionId })) },
+      },
+    });
+
+    it("a link written on the device carries the Neo4j type when the type config maps the relationship name", async () => {
+      await answer(store, "PATCH", "npcs/n2", { data: withFaction("n2", "brom", ["f1"]) }, withKinds());
+
+      expect((await store.linksFrom("n2")).map((link) => link.kind)).toEqual(["MEMBER_OF"]);
+    });
+
+    it("without a mapping the link carries the relationship name", async () => {
+      await answer(store, "PATCH", "npcs/n2", { data: withFaction("n2", "brom", ["f1"]) });
+
+      expect((await store.linksFrom("n2")).map((link) => link.kind)).toEqual(["faction"]);
+    });
+
+    it("removing a relationship target removes only links of that relationship (name or Neo4j type)", async () => {
+      await store.putRecord({
+        type: "npcs",
+        id: "n1",
+        rootId: "C",
+        resource: withFaction("n1", "Alda", ["f1"]),
+        updatedAt: null,
+      });
+      await store.putLink({
+        fromType: "factions",
+        fromId: "f1",
+        toType: "npcs",
+        toId: "n1",
+        kind: "ENEMY_OF",
+        props: {},
+      });
+
+      await answer(store, "PATCH", "npcs/n1", { data: withFaction("n1", "Alda", []) }, withKinds());
+
+      expect((await store.linksTo("n1")).map((link) => link.kind)).toEqual(["ENEMY_OF"]);
+    });
+
+    it("a related list follows only the links of the relationship toward the parent, by name or by Neo4j type", async () => {
+      await store.putRecord({
+        type: "npcs",
+        id: "n1",
+        rootId: "C",
+        resource: withFaction("n1", "Alda", ["f1"]),
+        updatedAt: null,
+      });
+      await store.putLink({
+        fromType: "factions",
+        fromId: "f1",
+        toType: "npcs",
+        toId: "n2",
+        kind: "ENEMY_OF",
+        props: {},
+      });
+      await store.putLink({
+        fromType: "npcs",
+        fromId: "n3",
+        toType: "factions",
+        toId: "f1",
+        kind: "faction",
+        props: {},
+      });
+      await store.putRecord({
+        type: "npcs",
+        id: "n3",
+        rootId: "C",
+        resource: npc("n3", "Cora", "C"),
+        updatedAt: null,
+      });
+
+      const result = await answer(store, "GET", "factions/f1/npcs?fetchAll=true&orderBy=name", undefined, withKinds());
+
+      expect(result.body.data.map((r: any) => r.id)).toEqual(["n1", "n3"]);
+    });
+
+    it("linksOfKind answers the links of any of the kinds, in the direction asked", async () => {
+      await store.putLink({
+        fromType: "npcs",
+        fromId: "n1",
+        toType: "factions",
+        toId: "f1",
+        kind: "faction",
+        props: {},
+      });
+
+      const both = await linksOfKind(store, "n1", ["MEMBER_OF", "faction"], "both");
+      const out = await linksOfKind(store, "n1", ["MEMBER_OF", "faction"], "out");
+
+      expect(both.map((link) => link.kind).sort()).toEqual(["MEMBER_OF", "faction"]);
+      expect(out.map((link) => link.kind)).toEqual(["faction"]);
+    });
+  });
+
+  it("a write to a readOnly type answers 503 needs-connection", async () => {
+    const result = await answer(store, "PATCH", "characters/ch1", {
+      data: { type: "characters", id: "ch1", attributes: { name: "X" } },
+    });
+
+    expect(result.status).toBe(503);
+    expect(result.body.errors[0].code).toBe("needs-connection");
+    expect(await store.queue()).toEqual([]);
+  });
+
+  it("a write to a locked root record answers 503 needs-connection", async () => {
+    setOfflineState({ lockedRootIds: ["C"] });
+
+    const patch = await answer(store, "PATCH", "npcs/n1", {
+      data: { type: "npcs", id: "n1", attributes: { name: "X" } },
+    });
+    const post = await answer(store, "POST", "npcs", { data: npc("n9", "New", "C") });
+
+    expect(patch.status).toBe(503);
+    expect(patch.body.errors[0].code).toBe("needs-connection");
+    expect(post.status).toBe(503);
+    expect(await store.queue()).toEqual([]);
+  });
+});

package/src/offline/__tests__/local-transport.spec.ts

@@ -0,0 +1,150 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { configureJsonApi } from "../../unified/JsonApiRequest";
+import { localTransport } from "../local-transport";
+import { getOfflineState, setOfflineState } from "../state";
+import type { DeviceStore } from "../store/DeviceStore";
+import { NeedsConnectionError, type OfflineRoute } from "../types";
+import { setDeviceStoreOpener } from "../config";
+import { Roots, Npcs, setUpOffline, tearDownOffline } from "./offline-fixtures";
+
+const API = "http://api.test/";
+
+const mergeRoute = (answer = vi.fn()): OfflineRoute => ({
+  method: "POST",
+  pattern: [Npcs, ":id", "merge"],
+  answer: answer.mockImplementation(async ({ store, params }) => {
+    await store.deleteRecord("npcs", params.id);
+    return { status: 200, body: { data: { type: "npcs", id: "n2", attributes: { name: "merged" } } } };
+  }),
+  queue: true,
+});
+
+describe("localTransport", () => {
+  let store: DeviceStore;
+
+  beforeEach(() => {
+    configureJsonApi({ apiUrl: API });
+  });
+
+  afterEach(() => {
+    tearDownOffline();
+  });
+
+  it("answers a generic GET from the device in the ApiData shape", async () => {
+    store = await setUpOffline();
+
+    const response = await localTransport({ method: "GET", url: `${API}npcs/n1` });
+
+    expect(response).toMatchObject({ ok: true, status: 200 });
+    expect(response.data.data.id).toBe("n1");
+  });
+
+  it("an unknown path answers 503 with errors[0].code needs-connection", async () => {
+    store = await setUpOffline();
+
+    const response = await localTransport({ method: "POST", url: `${API}sessions/s1/recap` });
+
+    expect(response).toMatchObject({ ok: false, status: 503 });
+    expect(response.data.errors[0].code).toBe("needs-connection");
+  });
+
+  it("a device copy that cannot be opened (another tab holds it) answers 503 needs-connection, never 500", async () => {
+    store = await setUpOffline();
+    setDeviceStoreOpener(async () => {
+      throw new Error("Access Handles cannot be created if there is another open Access Handle");
+    });
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+
+    const response = await localTransport({ method: "GET", url: `${API}npcs/n1` });
+
+    expect(response).toMatchObject({ ok: false, status: 503 });
+    expect(response.data.errors[0].code).toBe("needs-connection");
+    warn.mockRestore();
+  });
+
+  it("custom routes win over the generic ones", async () => {
+    const custom: OfflineRoute = {
+      method: "GET",
+      pattern: [Npcs, ":id"],
+      answer: async () => ({ status: 200, body: { data: { type: "npcs", id: "custom" } } }),
+      queue: false,
+    };
+    store = await setUpOffline([custom]);
+
+    const response = await localTransport({ method: "GET", url: `${API}npcs/n1` });
+
+    expect(response.data.data.id).toBe("custom");
+  });
+
+  it("a queue:true custom route is enqueued after its answer updated the store, with the original method, path and body", async () => {
+    const answer = vi.fn();
+    store = await setUpOffline([mergeRoute(answer)]);
+    const body = { data: { type: "npcs", id: "n2" } };
+
+    const response = await localTransport({ method: "POST", url: `${API}npcs/n1/merge?keep=true`, body });
+
+    expect(response.status).toBe(200);
+    expect(answer).toHaveBeenCalledTimes(1);
+    expect(await store.getRecord("npcs", "n1")).toBeUndefined();
+    const [entry] = await store.queue();
+    expect(entry).toMatchObject({ rootId: "C", method: "POST", path: "npcs/n1/merge?keep=true", body });
+    expect(getOfflineState().pending).toBe(1);
+  });
+
+  it("a queue:true custom route on a locked root record answers needs-connection and runs nothing", async () => {
+    const answer = vi.fn();
+    store = await setUpOffline([mergeRoute(answer)]);
+    setOfflineState({ lockedRootIds: ["C"] });
+
+    const response = await localTransport({ method: "POST", url: `${API}npcs/n1/merge`, body: {} });
+
+    expect(response.status).toBe(503);
+    expect(answer).not.toHaveBeenCalled();
+    expect(await store.queue()).toEqual([]);
+  });
+
+  it("a custom write that is not queued is refused on a locked root record; its GET answers stay allowed", async () => {
+    const write = vi.fn(async () => ({ status: 200, body: { data: { type: "npcs", id: "n1" } } }));
+    const read = vi.fn(async () => ({ status: 200, body: { data: { type: "npcs", id: "n1" } } }));
+    store = await setUpOffline([
+      { method: "POST", pattern: [Npcs, ":id", "pin"], answer: write, queue: false },
+      { method: "GET", pattern: [Npcs, ":id", "pin"], answer: read, queue: false },
+    ]);
+    setOfflineState({ lockedRootIds: ["C"] });
+
+    const refused = await localTransport({ method: "POST", url: `${API}npcs/n1/pin`, body: {} });
+    const allowed = await localTransport({ method: "GET", url: `${API}npcs/n1/pin` });
+
+    expect(refused.status).toBe(503);
+    expect(refused.data.errors[0].code).toBe("needs-connection");
+    expect(write).not.toHaveBeenCalled();
+    expect(allowed.status).toBe(200);
+    expect(read).toHaveBeenCalledTimes(1);
+  });
+
+  it("a custom answer that throws NeedsConnectionError answers 503 needs-connection", async () => {
+    store = await setUpOffline([
+      {
+        method: "POST",
+        pattern: [Roots, ":id", "sessions", "end"],
+        answer: async () => {
+          throw new NeedsConnectionError();
+        },
+        queue: false,
+      },
+    ]);
+
+    const response = await localTransport({ method: "POST", url: `${API}roots/C/sessions/end` });
+
+    expect(response.status).toBe(503);
+    expect(response.data.errors[0].code).toBe("needs-connection");
+  });
+
+  it("a file upload needs a connection", async () => {
+    store = await setUpOffline();
+
+    const response = await localTransport({ method: "POST", url: `${API}npcs`, body: {}, files: new Blob(["x"]) });
+
+    expect(response.data.errors[0].code).toBe("needs-connection");
+  });
+});

package/src/offline/__tests__/logout.spec.ts

@@ -0,0 +1,122 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  configureOffline,
+  DeviceStoreUnavailableError,
+  getOfflineStore,
+  resetOfflineConfig,
+  setDeviceStoreOpener,
+} from "../config";
+import { finishOfflineLogout, prepareOfflineLogout } from "../logout";
+import { getOfflineState, resetOfflineState, setOfflineState } from "../state";
+import type { DeviceStore, QueueEntry } from "../store/DeviceStore";
+import type { OfflineConfig } from "../types";
+
+const lifecycle = vi.hoisted(() => ({ deleteDeviceStore: vi.fn() }));
+vi.mock("../store/lifecycle", () => lifecycle);
+const runtime = vi.hoisted(() => ({ stopOfflineRuntime: vi.fn() }));
+vi.mock("../sync/runtime", () => runtime);
+
+function config(userId: string | undefined, requireOptIn?: boolean): OfflineConfig {
+  return {
+    getUserId: () => userId,
+    requireOptIn,
+    rootModule: { name: "roots" } as any,
+    types: [],
+    routes: [],
+    listSyncRoots: async () => [],
+    shellPath: () => "/offline-shell",
+    syncIntervalMs: 300000,
+  };
+}
+
+function storeWithQueue(entries: Partial<QueueEntry>[]): DeviceStore {
+  return { queue: vi.fn(async () => entries as QueueEntry[]) } as unknown as DeviceStore;
+}
+
+describe("offline logout", () => {
+  beforeEach(() => {
+    lifecycle.deleteDeviceStore.mockReset().mockResolvedValue(undefined);
+  });
+
+  afterEach(() => {
+    resetOfflineConfig();
+  });
+
+  it("prepareOfflineLogout counts every unsent queue entry of the signed-in user", async () => {
+    configureOffline(config("u1"));
+    const opener = vi.fn(async () =>
+      storeWithQueue([{ status: "pending" }, { status: "conflict" }, { status: "failed" }]),
+    );
+    setDeviceStoreOpener(opener);
+
+    expect(await prepareOfflineLogout()).toEqual({ pending: 3 });
+    expect(opener).toHaveBeenCalledWith("u1");
+  });
+
+  it("prepareOfflineLogout answers 0 when offline mode is not configured or nobody is signed in", async () => {
+    expect(await prepareOfflineLogout()).toEqual({ pending: 0 });
+
+    configureOffline(config(undefined));
+    const opener = vi.fn();
+    setDeviceStoreOpener(opener);
+    expect(await prepareOfflineLogout()).toEqual({ pending: 0 });
+    expect(opener).not.toHaveBeenCalled();
+  });
+
+  it("finishOfflineLogout deletes the user's database and the images cache", async () => {
+    const caches = {
+      keys: vi.fn(async () => ["wyrdli-offline-abc", "wyrdli-shell-b1", "wyrdli-images"]),
+      delete: vi.fn(async () => true),
+    };
+    vi.stubGlobal("caches", caches);
+
+    await finishOfflineLogout("u1");
+
+    expect(lifecycle.deleteDeviceStore).toHaveBeenCalledWith("u1");
+    expect(caches.delete).toHaveBeenCalledTimes(1);
+    expect(caches.delete).toHaveBeenCalledWith("wyrdli-images");
+    vi.unstubAllGlobals();
+  });
+
+  it("finishOfflineLogout stops the runtime first and blocks any reopen of the store, so a sync still running cannot recreate the deleted file", async () => {
+    vi.stubGlobal("caches", { keys: vi.fn(async () => []), delete: vi.fn() });
+    configureOffline(config("u1"));
+    const opener = vi.fn(async () => storeWithQueue([]));
+    setDeviceStoreOpener(opener);
+    runtime.stopOfflineRuntime.mockReset();
+    const order: string[] = [];
+    runtime.stopOfflineRuntime.mockImplementation(() => void order.push("stop"));
+    lifecycle.deleteDeviceStore.mockImplementation(async () => {
+      order.push("delete");
+      // A sync that was still running asks for the store while the file is deleted.
+      await expect(getOfflineStore()).rejects.toBeInstanceOf(DeviceStoreUnavailableError);
+    });
+
+    await finishOfflineLogout("u1");
+
+    expect(order).toEqual(["stop", "delete"]);
+    await expect(getOfflineStore()).rejects.toBeInstanceOf(DeviceStoreUnavailableError);
+    expect(opener).not.toHaveBeenCalled();
+    vi.unstubAllGlobals();
+  });
+
+  it("finishOfflineLogout turns the device switch off and clears the sync state and the last sync time", async () => {
+    vi.stubGlobal("caches", { keys: vi.fn(async () => []), delete: vi.fn() });
+    localStorage.setItem("nja-offline-enabled:u1", "1");
+    localStorage.setItem("nja-offline-last-sync:u1", "1761990000000");
+    configureOffline(config("u1", true));
+    setOfflineState({ rootCount: 2, syncProgress: { done: 1, total: 2 } });
+    expect(getOfflineState().lastSyncedAt).toBe(1761990000000);
+
+    await finishOfflineLogout("u1");
+
+    expect(localStorage.getItem("nja-offline-enabled:u1")).toBeNull();
+    expect(localStorage.getItem("nja-offline-last-sync:u1")).toBeNull();
+    expect(getOfflineState()).toEqual(
+      expect.objectContaining({ enabled: false, syncProgress: null, lastSyncedAt: null, rootCount: null }),
+    );
+    localStorage.clear();
+    resetOfflineState();
+    vi.unstubAllGlobals();
+  });
+});