@owdproject/nuxt-module-atproto-persistence 4.0.0-alpha.3 → 4.0.0-alpha.4

package/README.md

@@ -14,19 +14,42 @@ replaces `@owdproject/nuxt-module-pinia-persistence` — **do not install both**
 desktop.
 
 Boot order is handled without core coupling: the plugin runs in Nuxt's **pre**
-phase (registers the adapter only). Remote hydration runs **lazily** on the first
-`getItem`, after the `atproto` OAuth plugin has finished init. Core and apps
-already await `$persistedState.isReady()` before restoring windows.
+phase (registers the adapter only). Stores hydrate locally first. Remote hydration runs at `app:created`, after
+the `atproto` OAuth plugin has finished initialization. The Nuxt application
+controllers await `$persistedState.isReady()` before restoring local windows.
 
 ## Requirements
 
-- `@owdproject/core` ^3.4.0
-- `@owdproject/module-atproto` (provides OAuth session and agents)
+- The matching `@owdproject/nuxt` adapter revision with persisted store opt-ins
+  and `ApplicationController.restoreApplication()` (release these together).
+- `@owdproject/nuxt-module-atproto` (provides OAuth session and agents)
+
+### OAuth scope
+
+The special `atproto` scope only covers identity. Writing the desktop profile to
+the repository requires explicit **`repo:`** permissions *with actions* (the PDS
+checks `action=create`/`action=update` for `putRecord`), otherwise the write is
+rejected (403 / `ScopeMissingError`):
+
+```ts
+// desktop/nuxt.config.ts
+const ACTIONS = 'action=create&action=update&action=delete'
+atproto: {
+  oauth: {
+    signInOptions: { scope: `atproto repo:org.owdproject.desktop?${ACTIONS} repo:org.owdproject.application.windows?${ACTIONS} repo:org.owdproject.application.meta?${ACTIONS}` },
+    clientMetadata: { local: { scope: `atproto repo:org.owdproject.desktop?${ACTIONS} repo:org.owdproject.application.windows?${ACTIONS} repo:org.owdproject.application.meta?${ACTIONS}` } },
+  },
+}
+```
+
+You can use `repo:*?action=create&action=update&action=delete` instead to grant
+access to every record type. Changing the scope requires signing in again
+(existing sessions keep their original grant).
 
 ## Installation
 
 ```bash
-pnpm desktop add module-atproto-persistence
+pnpm desktop add nuxt-module-atproto-persistence
 ```
 
 ## Configuration
@@ -35,8 +58,8 @@ pnpm desktop add module-atproto-persistence
 // desktop/desktop.config.ts
 export default defineDesktopConfig({
   modules: [
-    '@owdproject/module-atproto',
-    '@owdproject/module-atproto-persistence',
+    '@owdproject/nuxt-module-atproto',
+    '@owdproject/nuxt-module-atproto-persistence',
   ],
   atprotoPersistence: {
     // Load atprotoDesktop.owner.did remote state on boot (not only /actor/:did)
@@ -47,7 +70,7 @@ export default defineDesktopConfig({
 
 ## Actor resolution (remote hydrate)
 
-On first store read, remote state is fetched once per boot when an actor DID is
+After plugin initialization, remote state is fetched when an actor DID is
 resolved:
 
 1. Route `/actor/:did` — view another actor's desktop
@@ -55,16 +78,69 @@ resolved:
 3. `loadOwnerDesktopOnMounted: true` — `atprotoDesktop.owner.did`
 4. Otherwise — IndexedDB only
 
+## Desktop scoping
+
+Persisted state is namespaced by the **desktop distribution id**, declared as
+`id` in `desktop.config.ts`:
+
+```ts
+export default defineDesktopConfig({
+  id: 'atproto-os',
+  // ...
+})
+```
+
+The id is resolved from `runtimeConfig.public.desktop.id` (falling back to the
+reversibly encoded branded title/affix, then `name`). It prefixes the AT Protocol record rkeys and
+the local IndexedDB keys, so products configured with distinct stable ids do not share a profile.
+Using the same id deliberately shares that namespace for the same account. Records that do not carry the current desktop prefix are ignored.
+
 ## AT Protocol collections
 
 | Pinia store id | AT Proto collection | rkey |
 |---|---|---|
-| `desktop` | `org.owdproject.desktop` | `self` |
-| `desktop/application/<appId>/windows` | `org.owdproject.application.windows` | `<appId>` |
-| `desktop/application/<appId>/meta` | `org.owdproject.application.meta` | `<appId>` |
+| `desktop` | `org.owdproject.desktop` | `<desktopId>` |
+| `desktop/<sub>` | `org.owdproject.desktop` | `<desktopId>:<encoded sub>` |
+| `desktop/application/<appId>/windows` | `org.owdproject.application.windows` | `<desktopId>:<encoded appId>` |
+| `desktop/application/<appId>/meta` | `org.owdproject.application.meta` | `<desktopId>:<encoded appId>` |
 
 When logged in, mapped keys are written to the repo on change (`putRecord`).
-Unmapped keys stay local-only.
+Unmapped keys stay local-only. Local IndexedDB keys are `<desktopId>/<pinia store id>`.
+
+## Sign-out
+
+On sign-out the module forgets the cached remote state map and wipes the local
+IndexedDB keys for the desktop (`atproto:sessionDeleted`, or the
+`authenticated → anonymous` transition). The desktop shell is expected to close
+its windows on the same lifecycle event so the next account never inherits the
+previous one's layout (see the atproto OS host plugin
+`atproto-reset-on-signout.client.ts`).
+
+## Restore and delivery guarantees
+
+The adapter registers synchronously before stores are created. Stores first
+hydrate from IndexedDB. Remote hydration runs at `app:created`, after OAuth
+initialization finishes, without treating a slow login as a guest session.
+Session changes and network recovery can retry failed reads. Remote hydration
+keeps changes made locally while a read was in flight, and a repeated session
+hook does not reopen closed windows.
+
+Authenticated changes are saved to a desktop/account-scoped IndexedDB outbox.
+Remote writes are serialized per store; failures retry after five seconds or
+on network recovery. An entry is removed only after a successful write of that
+value. Pending entries survive reloads and take precedence over older remote
+records. This is snapshot persistence, not real-time collaboration; Jetstream
+integration remains separate.
+
+Explicit desktop ids preserve case and punctuation and must contain 1–64 ASCII
+letters, digits, dots, underscores or hyphens, starting with a letter or digit.
+Use a stable explicit id for each distribution. Hosts without one retain a
+reversibly encoded branding fallback; changing that branding changes the profile
+namespace. Record-key components encode reserved characters reversibly, including
+multi-segment store ids. Reads paginate through all collection records.
+
+Run `pnpm run test:persistence` after installing dev dependencies to verify the
+identity mapping, pagination, slow OAuth, remote restore and offline write retry.
 
 ## License
 

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "desktop-module-atproto-persistence",
   "configKey": "atprotoPersistence",
-  "version": "4.0.0-alpha.3",
+  "version": "4.0.0-alpha.4",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "3.6.1"

package/dist/runtime/plugin.js

@@ -1,100 +1,275 @@
 import { createPersistedStatePlugin } from "pinia-plugin-persistedstate-2";
 import { defineNuxtPlugin } from "nuxt/app";
-function deepEqual(obj1, obj2) {
-  if (obj1 === obj2) return true;
-  if (!obj1 || !obj2 || typeof obj1 !== "object" || typeof obj2 !== "object") return false;
-  const keys1 = Object.keys(obj1);
-  const keys2 = Object.keys(obj2);
-  if (keys1.length !== keys2.length) return false;
-  for (const key of keys1) {
-    if (!Object.prototype.hasOwnProperty.call(obj2, key)) return false;
-    if (!deepEqual(obj1[key], obj2[key])) return false;
-  }
-  return true;
-}
-import { useAtprotoSession, useAtprotoAgent } from "#imports";
-import { get, set, del } from "idb-keyval";
+import { nextTick, watch } from "vue";
+import { useAtprotoAgent, useAtprotoSession } from "#imports";
+import { useDesktopApplication } from "@owdproject/nuxt/runtime/composables/useDesktopApplication";
+import { get, set, del, keys } from "idb-keyval";
 import {
+  parseAtprotoStoreKey,
   putAtprotoApplicationState,
-  parseAtprotoStoreKey
+  resolveDesktopId,
+  toLocalStorageKey
 } from "./utils/utilAtprotoApplicationStates.js";
-import { ensureActorStatesLoaded } from "./utils/utilAtprotoPersistenceLoad.js";
+import {
+  ensureActorStatesLoaded,
+  resolveRestoreActorDid,
+  invalidateActorStates
+} from "./utils/utilAtprotoPersistenceLoad.js";
+import { createAtprotoWriteQueue } from "./utils/utilAtprotoWriteQueue.js";
 function mapStoreKey(key) {
-  if (key === "desktop") {
-    return "owd/desktop";
-  }
-  if (key.startsWith("desktop/application/")) {
+  if (key === "desktop") return "owd/desktop";
+  if (key.startsWith("desktop/application/"))
     return key.replace(/^desktop\/application\//, "owd/application/");
-  }
-  if (key.startsWith("desktop/")) {
+  if (key.startsWith("desktop/"))
     return key.replace(/^desktop\//, "owd/desktop/");
-  }
   return key;
 }
+function replaceState(store, value) {
+  store.$patch((state) => {
+    for (const [key, next] of Object.entries(value)) {
+      const current = state[key];
+      if (current && next && !Array.isArray(current) && !Array.isArray(next) && typeof current === "object" && typeof next === "object") {
+        for (const old of Object.keys(current)) delete current[old];
+        Object.assign(current, next);
+      } else {
+        state[key] = next;
+      }
+    }
+  });
+}
 export default defineNuxtPlugin({
   name: "desktop-plugin-atproto-persistence",
-  dependsOn: ["pinia", "atproto"],
+  dependsOn: ["pinia"],
   enforce: "pre",
-  async setup(nuxtApp) {
+  setup(nuxtApp) {
     const pinia = nuxtApp.$pinia;
-    if (!pinia) {
-      return;
+    if (!pinia) return;
+    const desktopId = resolveDesktopId(nuxtApp);
+    const stores = /* @__PURE__ */ new Map();
+    const defaults = /* @__PURE__ */ new Map();
+    const localWrites = /* @__PURE__ */ new Map();
+    const versions = /* @__PURE__ */ new Map();
+    let hydrating = false;
+    let armed = false;
+    let booted = false;
+    let currentDid;
+    let scopeWarned = false;
+    let resetTask;
+    let stopSessionWatch;
+    let retry;
+    let syncTask;
+    let restoredActor;
+    const localKey = (key) => toLocalStorageKey(desktopId, key);
+    const outboxPrefix = (did) => `${desktopId}/outbox/${did}/`;
+    function authenticatedDid() {
+      if (!nuxtApp.$atproto) return void 0;
+      const { isLogged, session } = nuxtApp.runWithContext(
+        () => useAtprotoSession()
+      );
+      return isLogged.value ? session.value?.sub : void 0;
     }
-    await ensureActorStatesLoaded(nuxtApp);
-    pinia.use(
-      createPersistedStatePlugin({
-        persist: false,
-        storage: {
-          getItem: async (piniaKey) => {
-            const remote = await ensureActorStatesLoaded(nuxtApp);
-            const mappedKey = mapStoreKey(piniaKey);
-            if (Object.prototype.hasOwnProperty.call(remote, mappedKey)) {
-              return JSON.stringify(remote[mappedKey]);
-            }
-            const value = await get(piniaKey);
-            return value ?? null;
-          },
-          setItem: async (piniaKey, piniaValue) => {
-            const previousPiniaValue = await get(piniaKey) ?? null;
-            await set(piniaKey, piniaValue);
-            const atprotoTargetRecord = parseAtprotoStoreKey(piniaKey);
-            if (!atprotoTargetRecord) {
-              return piniaValue;
+    function createQueue() {
+      return createAtprotoWriteQueue(
+        async (key, value) => {
+          const did = authenticatedDid();
+          if (!did || did !== currentDid)
+            throw new Error("AT Protocol session changed before sync");
+          const target = parseAtprotoStoreKey(key, desktopId);
+          if (!target) return;
+          const agent = nuxtApp.runWithContext(
+            () => useAtprotoAgent("authenticated")
+          );
+          await putAtprotoApplicationState(
+            agent,
+            did,
+            target.collection,
+            target.rkey,
+            JSON.parse(value)
+          );
+          const outboxKey = `${outboxPrefix(did)}${key}`;
+          if (await get(outboxKey) === value) await del(outboxKey);
+        },
+        {
+          onError: (error) => {
+            if (!scopeWarned) {
+              scopeWarned = true;
+              console.warn(
+                "[OWD persistence] Remote save failed; queued locally for retry. For ScopeMissingError, request the matching repo: permissions in OAuth metadata and sign in again.",
+                error
+              );
             }
-            const { isLogged } = nuxtApp.runWithContext(() => useAtprotoSession());
-            if (!isLogged.value) {
-              return piniaValue;
-            }
-            const { collection, rkey } = atprotoTargetRecord;
-            try {
-              const currentObj = JSON.parse(piniaValue);
-              const previousObj = previousPiniaValue ? JSON.parse(previousPiniaValue) : null;
-              if (previousObj && deepEqual(currentObj, previousObj)) {
-                return piniaValue;
-              }
-            } catch {
-              if (piniaValue === previousPiniaValue) {
-                return piniaValue;
-              }
+          }
+        }
+      );
+    }
+    let queue = createQueue();
+    const adapter = createPersistedStatePlugin({
+      persist: false,
+      assertStorage: () => {
+      },
+      storage: {
+        getItem: async (key) => await get(localKey(key)) ?? null,
+        setItem(key, value) {
+          if (resetTask) return resetTask;
+          if (!hydrating) versions.set(key, (versions.get(key) ?? 0) + 1);
+          const did = armed && !hydrating ? authenticatedDid() : void 0;
+          const previous = localWrites.get(key) ?? Promise.resolve();
+          const task = previous.catch(() => {
+          }).then(async () => {
+            await set(localKey(key), value);
+            if (did && did === currentDid && parseAtprotoStoreKey(key, desktopId)) {
+              await set(`${outboxPrefix(did)}${key}`, value);
+              void queue.enqueue(key, value);
             }
-            const agent = nuxtApp.runWithContext(() => useAtprotoAgent("authenticated"));
-            return putAtprotoApplicationState(
-              agent,
-              agent.assertDid,
-              collection,
-              rkey,
-              JSON.parse(piniaValue)
-            ).then(() => {
-              return piniaValue;
-            }).catch(() => {
-              return piniaValue;
-            });
-          },
-          removeItem: async (key) => {
-            await del(key);
+          });
+          localWrites.set(key, task);
+          return task;
+        },
+        removeItem: async (key) => {
+          await del(localKey(key));
+        }
+      }
+    });
+    pinia.use((context) => {
+      const initial = JSON.stringify(context.store.$state);
+      const result = adapter(context);
+      if (context.store.$persistedState) {
+        stores.set(context.store.$id, context.store);
+        defaults.set(context.store.$id, initial);
+      }
+      return result;
+    });
+    async function syncRemote() {
+      await Promise.all(
+        [...stores.values()].map((store) => store.$persistedState.isReady())
+      );
+      await Promise.all(localWrites.values());
+      const baseline = new Map(versions);
+      const actor = await resolveRestoreActorDid(nuxtApp);
+      const did = authenticatedDid();
+      if (currentDid !== did) {
+        queue.stop();
+        queue = createQueue();
+      }
+      currentDid = did;
+      if (restoredActor === (actor ?? "guest")) return;
+      try {
+        const remote = await ensureActorStatesLoaded(nuxtApp, true);
+        if (actor !== await resolveRestoreActorDid(nuxtApp) || did !== authenticatedDid())
+          return;
+        await Promise.all(
+          [...stores.values()].map((store) => store.$persistedState.isReady())
+        );
+        await Promise.all(localWrites.values());
+        const applications = nuxtApp.runWithContext(
+          () => useDesktopApplication()
+        );
+        hydrating = true;
+        try {
+          for (const [key, store] of stores) {
+            const pending = did ? await get(`${outboxPrefix(did)}${key}`) : void 0;
+            const value = pending ? JSON.parse(pending) : remote[mapStoreKey(key)];
+            if (!value || (versions.get(key) ?? 0) !== (baseline.get(key) ?? 0))
+              continue;
+            const match = /^desktop\/application\/(.+)\/windows$/.exec(key);
+            const app = match ? applications.get(match[1]) : void 0;
+            app?.closeAllWindows();
+            replaceState(store, value);
+            if (app) await app.restoreApplication();
           }
+        } finally {
+          await nextTick();
+          hydrating = false;
+        }
+        await Promise.all(localWrites.values());
+        armed = true;
+        restoredActor = actor ?? "guest";
+        if (did) {
+          for (const key of await keys()) {
+            if (typeof key !== "string" || !key.startsWith(outboxPrefix(did)))
+              continue;
+            const value = await get(key);
+            if (value != null)
+              void queue.enqueue(key.slice(outboxPrefix(did).length), value);
+          }
+        }
+      } catch {
+        armed = true;
+        console.warn(
+          "[OWD persistence] Remote restore failed; keeping local windows and retrying."
+        );
+        if (!retry)
+          retry = setTimeout(() => {
+            retry = void 0;
+            void synchronize();
+          }, 5e3);
+      }
+    }
+    function synchronize() {
+      if (!booted) return Promise.resolve();
+      if (!syncTask)
+        syncTask = syncRemote().finally(() => {
+          syncTask = void 0;
+        });
+      return syncTask;
+    }
+    nuxtApp.hook("app:created", async () => {
+      booted = true;
+      await synchronize();
+    });
+    const lifecycle = nuxtApp.hook;
+    lifecycle("atproto:sessionCreated", () => synchronize());
+    lifecycle("atproto:sessionRestored", () => synchronize());
+    function resetPersistence() {
+      if (resetTask) return resetTask;
+      armed = false;
+      currentDid = void 0;
+      restoredActor = void 0;
+      invalidateActorStates(nuxtApp);
+      queue.stop();
+      queue = createQueue();
+      if (retry) clearTimeout(retry);
+      retry = void 0;
+      const pending = [...localWrites.values()];
+      resetTask = (async () => {
+        await nextTick();
+        for (const [key, store] of stores) {
+          const initial = defaults.get(key);
+          if (initial) replaceState(store, JSON.parse(initial));
+        }
+        await nextTick();
+        await Promise.allSettled(pending);
+        for (const key of await keys()) {
+          if (typeof key === "string" && key.startsWith(`${desktopId}/`))
+            await del(key);
+        }
+      })().finally(() => {
+        resetTask = void 0;
+      });
+      return resetTask;
+    }
+    lifecycle("atproto:sessionDeleted", resetPersistence);
+    nuxtApp.hook("app:mounted", () => {
+      const atproto = nuxtApp.$atproto;
+      if (!atproto) return;
+      stopSessionWatch = watch(
+        () => atproto.status?.value,
+        (next, previous) => {
+          if (previous === "authenticated" && next !== "authenticated")
+            void resetPersistence();
         }
-      })
-    );
+      );
+    });
+    const online = () => {
+      void queue.flush();
+      void synchronize();
+    };
+    window.addEventListener("online", online);
+    nuxtApp.vueApp.onUnmount?.(() => {
+      queue.stop();
+      stopSessionWatch?.();
+      if (retry) clearTimeout(retry);
+      window.removeEventListener("online", online);
+    });
   }
 });

package/dist/runtime/utils/utilAtprotoApplicationStates.d.ts

@@ -1,24 +1,47 @@
+/** Reversible record-key encoding; AT Protocol permits `~`, but not `/` or `%`. */
+export declare function encodeRecordKeyPart(value: string): string;
 /** Resolve PDS endpoint via PLC directory (Bluesky); custom PDSs use the same DID document shape. */
 export declare function resolveActorServiceEndpoint(did: string): Promise<string>;
+/** Slug used inside rkeys (RecordKey forbids `/`, so desktop state is namespaced with this). */
 /**
- * Maps a Pinia store id to an AT Protocol collection and rkey.
+ * Identity of the desktop distribution that owns the persisted profile.
+ *
+ * Declared as `id` in `desktop.config.ts` (`defineDesktopConfig({ id: 'atproto-os' })`)
+ * and surfaced on `runtimeConfig.public.desktop`. Falling back to the branded
+ * title/affix keeps two different OWD distributions from sharing records when an
+ * explicit `id` is missing.
+ */
+export declare function resolveDesktopId(nuxtApp: any): string;
+/** IndexedDB key for a Pinia store id, scoped to the current desktop distribution. */
+export declare function toLocalStorageKey(desktopId: string, piniaKey: string): string;
+/**
+ * Maps a Pinia store id to an AT Protocol collection and desktop-scoped rkey.
+ *
+ * The rkey is prefixed with the desktop id so two different OWD distributions
+ * (e.g. "Marco's OWD" vs "Alessio's OWD") never read or overwrite each other's
+ * profile, even for the same logged-in user.
  *
  * Key format → AT Proto mapping:
- * - `desktop/application/<appId>/windows` → collection: `org.owdproject.application.windows`, rkey: `<appId>`
- * - `desktop/application/<appId>/meta`    → collection: `org.owdproject.application.meta`,    rkey: `<appId>`
- * - `desktop` (or `desktop/<sub>`)        → collection: `org.owdproject.desktop`,              rkey: `self` (or `<sub>`)
+ * - `desktop/application/<appId>/windows` → collection: `org.owdproject.application.windows`, rkey: `<desktopId>:<appId>`
+ * - `desktop/application/<appId>/meta`    → collection: `org.owdproject.application.meta`,    rkey: `<desktopId>:<appId>`
+ * - `desktop`                             → collection: `org.owdproject.desktop`,              rkey: `<desktopId>`
+ * - `desktop/<sub>`                       → collection: `org.owdproject.desktop`,              rkey: `<desktopId>:<sub>`
  *
  * Returns `null` for keys that are not persisted to AT Proto.
  */
-export declare function parseAtprotoStoreKey(key: string): {
+export declare function parseAtprotoStoreKey(key: string, desktopId: string): {
     collection: string;
     rkey: string;
 } | null;
-export declare function listAtprotoApplicationStateRecords(agent: any, repo: string, collection: string): any;
+export declare function listAtprotoApplicationStateRecords(agent: any, repo: string, collection: string): Promise<any[]>;
 export declare function getAtprotoApplicationState(agent: any, repo: string, collection: string, rkey: string): any;
 export declare function putAtprotoApplicationState(agent: any, repo: string, collection: string, rkey: string, record: any): any;
 /**
  * Loads the full desktop state map for a given actor from the AT Protocol
  * repository. Returns a map keyed by Pinia store id (`desktop/` prefix).
+ *
+ * Only records belonging to `desktopId` are considered: rkeys must be exactly
+ * `<desktopId>` or start with `<desktopId>:`. Legacy/foreign records are ignored,
+ * so opening another distribution's OWD never loads an unrelated profile.
  */
-export declare function loadActorDesktopStateMap(nuxtApp: any, actorDid: string): Promise<Record<string, any>>;
+export declare function loadActorDesktopStateMap(nuxtApp: any, actorDid: string, desktopId: string): Promise<Record<string, any>>;

package/dist/runtime/utils/utilAtprotoApplicationStates.js

@@ -1,4 +1,14 @@
+import { useRuntimeConfig } from "nuxt/app";
 import { useAtprotoAgent, useAtprotoSession } from "#imports";
+export function encodeRecordKeyPart(value) {
+  return Array.from(new TextEncoder().encode(value), (byte) => {
+    const char = String.fromCharCode(byte);
+    return /[a-zA-Z0-9._-]/.test(char) ? char : `~${byte.toString(16).padStart(2, "0")}`;
+  }).join("");
+}
+function decodeRecordKeyPart(value) {
+  return decodeURIComponent(value.replace(/~/g, "%"));
+}
 export async function resolveActorServiceEndpoint(did) {
   const response = await fetch(`https://plc.directory/${did}`);
   if (!response.ok) {
@@ -7,7 +17,24 @@ export async function resolveActorServiceEndpoint(did) {
   const data = await response.json();
   return data.service[0].serviceEndpoint;
 }
-export function parseAtprotoStoreKey(key) {
+export function resolveDesktopId(nuxtApp) {
+  const runtimeConfig = nuxtApp.runWithContext(() => useRuntimeConfig());
+  const desktop = runtimeConfig.public?.desktop ?? {};
+  if (typeof desktop.id === "string" && desktop.id.length > 0) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(desktop.id)) {
+      throw new Error(
+        "[OWD persistence] Invalid desktop id; use 1\u201364 ASCII letters, digits, dots, underscores or hyphens."
+      );
+    }
+    return desktop.id;
+  }
+  const branded = [desktop.title, desktop.affix].filter(Boolean).join("-");
+  return `legacy-${encodeRecordKeyPart(branded || desktop.name || "owd")}`;
+}
+export function toLocalStorageKey(desktopId, piniaKey) {
+  return `${desktopId}/${piniaKey}`;
+}
+export function parseAtprotoStoreKey(key, desktopId) {
   if (key.startsWith("desktop/application/")) {
     const parts = key.split("/");
     const last = parts[parts.length - 1];
@@ -15,26 +42,39 @@ export function parseAtprotoStoreKey(key) {
       const appId = parts.slice(2, -1).join("/");
       return {
         collection: `org.owdproject.application.${last}`,
-        rkey: appId
+        rkey: `${desktopId}:${encodeRecordKeyPart(appId)}`
       };
     }
   }
   if (key === "desktop" || key.startsWith("desktop/")) {
-    const sub = key.split("/")[1] ?? "self";
     if (!key.startsWith("desktop/application/")) {
+      const sub = key.slice("desktop/".length);
       return {
         collection: "org.owdproject.desktop",
-        rkey: sub
+        rkey: key === "desktop" ? desktopId : `${desktopId}:${encodeRecordKeyPart(sub)}`
       };
     }
   }
   return null;
 }
-export function listAtprotoApplicationStateRecords(agent, repo, collection) {
-  return agent.com.atproto.repo.listRecords({
-    repo,
-    collection
-  }).then((response) => response.data).then((data) => data.records).catch(() => []);
+export async function listAtprotoApplicationStateRecords(agent, repo, collection) {
+  const records = [];
+  let cursor;
+  const seen = /* @__PURE__ */ new Set();
+  do {
+    const { data } = await agent.com.atproto.repo.listRecords({
+      repo,
+      collection,
+      cursor,
+      limit: 100
+    });
+    records.push(...data.records);
+    cursor = data.cursor;
+    if (cursor && seen.has(cursor))
+      throw new Error("AT Protocol returned a repeated records cursor");
+    if (cursor) seen.add(cursor);
+  } while (cursor);
+  return records;
 }
 export function getAtprotoApplicationState(agent, repo, collection, rkey) {
   return agent.com.atproto.repo.getRecord({
@@ -48,19 +88,24 @@ export function putAtprotoApplicationState(agent, repo, collection, rkey, record
     repo,
     collection,
     rkey,
-    record
+    record: { ...record, $type: collection }
   });
 }
-export async function loadActorDesktopStateMap(nuxtApp, actorDid) {
-  const { isLogged, session } = nuxtApp.runWithContext(() => useAtprotoSession());
+export async function loadActorDesktopStateMap(nuxtApp, actorDid, desktopId) {
+  const { isLogged, session } = nuxtApp.runWithContext(
+    () => useAtprotoSession()
+  );
   const isOwner = isLogged.value && session.value?.sub === actorDid;
   let actorAgent;
   if (isOwner) {
     actorAgent = nuxtApp.runWithContext(() => useAtprotoAgent("authenticated"));
   } else {
     const actorServiceEndpoint = await resolveActorServiceEndpoint(actorDid);
-    actorAgent = nuxtApp.runWithContext(() => useAtprotoAgent(actorServiceEndpoint));
+    actorAgent = nuxtApp.runWithContext(
+      () => useAtprotoAgent(actorServiceEndpoint)
+    );
   }
+  const prefix = `${desktopId}:`;
   const [
     atprotoActorDesktopList,
     atprotoApplicationWindowsList,
@@ -82,17 +127,31 @@ export async function loadActorDesktopStateMap(nuxtApp, actorDid) {
       "org.owdproject.application.meta"
     )
   ]);
+  for (const result of [
+    atprotoActorDesktopList,
+    atprotoApplicationWindowsList,
+    atprotoApplicationMetaList
+  ]) {
+    if (result.status === "rejected") throw result.reason;
+  }
   const stateMap = {};
   if (atprotoActorDesktopList.status === "fulfilled") {
     for (const record of atprotoActorDesktopList.value) {
       const rkey = record.uri.split("/").pop();
-      const piniaKey = rkey === "self" ? "owd/desktop" : `owd/desktop/${rkey}`;
-      stateMap[piniaKey] = record.value;
+      if (rkey === desktopId) {
+        const { $type, ...state } = record.value;
+        stateMap["owd/desktop"] = state;
+      } else if (typeof rkey === "string" && rkey.startsWith(prefix)) {
+        const { $type, ...state } = record.value;
+        stateMap[`owd/desktop/${decodeRecordKeyPart(rkey.slice(prefix.length))}`] = state;
+      }
     }
   }
   if (atprotoApplicationWindowsList.status === "fulfilled") {
     for (const record of atprotoApplicationWindowsList.value) {
-      const appId = record.uri.split("/").pop();
+      const rkey = record.uri.split("/").pop();
+      if (typeof rkey !== "string" || !rkey.startsWith(prefix)) continue;
+      const appId = decodeRecordKeyPart(rkey.slice(prefix.length));
       stateMap[`owd/application/${appId}/windows`] = {
         windows: record.value.windows
       };
@@ -100,7 +159,9 @@ export async function loadActorDesktopStateMap(nuxtApp, actorDid) {
   }
   if (atprotoApplicationMetaList.status === "fulfilled") {
     for (const record of atprotoApplicationMetaList.value) {
-      const appId = record.uri.split("/").pop();
+      const rkey = record.uri.split("/").pop();
+      if (typeof rkey !== "string" || !rkey.startsWith(prefix)) continue;
+      const appId = decodeRecordKeyPart(rkey.slice(prefix.length));
       stateMap[`owd/application/${appId}/meta`] = {
         ...record.value
       };

package/dist/runtime/utils/utilAtprotoPersistenceLoad.d.ts

@@ -1,5 +1,4 @@
-/** Wait until the nuxt-atproto plugin has finished OAuth init (or timeout as guest). */
-export declare function waitForAtprotoReady(nuxtApp: any): Promise<void>;
 export declare function resolveRestoreActorDid(nuxtApp: any): Promise<string | undefined>;
-/** One remote fetch per boot; subsequent getItem calls reuse the same promise. */
-export declare function ensureActorStatesLoaded(nuxtApp: any): Promise<Record<string, unknown>>;
+export declare function ensureActorStatesLoaded(nuxtApp: any, refresh?: boolean): Promise<Record<string, unknown>>;
+/** Invalidate this host's remote profile when its account signs out. */
+export declare function invalidateActorStates(nuxtApp: object): void;

package/dist/runtime/utils/utilAtprotoPersistenceLoad.js

@@ -1,56 +1,44 @@
 import { useAtprotoSession } from "#imports";
 import { useRouter, useRuntimeConfig } from "nuxt/app";
-import { loadActorDesktopStateMap } from "./utilAtprotoApplicationStates.js";
-const ATPROTO_READY_TIMEOUT_MS = 2e3;
-const ATPROTO_READY_POLL_MS = 10;
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-export async function waitForAtprotoReady(nuxtApp) {
-  const deadline = Date.now() + ATPROTO_READY_TIMEOUT_MS;
-  while (Date.now() < deadline) {
-    const $atproto = nuxtApp.$atproto;
-    if ($atproto && $atproto.status.value !== "initializing") {
-      return;
-    }
-    await sleep(ATPROTO_READY_POLL_MS);
-  }
-}
+import {
+  loadActorDesktopStateMap,
+  resolveDesktopId
+} from "./utilAtprotoApplicationStates.js";
 export async function resolveRestoreActorDid(nuxtApp) {
   const router = nuxtApp.runWithContext(() => useRouter());
   await router.isReady();
   const routeDid = router.currentRoute.value.params.did;
-  if (typeof routeDid === "string" && routeDid.length > 0) {
-    return routeDid;
-  }
-  const { isLogged, session } = nuxtApp.runWithContext(() => useAtprotoSession());
-  if (isLogged.value && session.value?.sub) {
-    return session.value.sub;
-  }
-  const runtimeConfig = nuxtApp.runWithContext(() => useRuntimeConfig());
-  const desktop = runtimeConfig.public.desktop;
-  if (desktop.atprotoPersistence?.loadOwnerDesktopOnMounted) {
+  if (typeof routeDid === "string" && routeDid.length > 0) return routeDid;
+  if (!nuxtApp.$atproto) return void 0;
+  const { isLogged, session } = nuxtApp.runWithContext(
+    () => useAtprotoSession()
+  );
+  if (isLogged.value && session.value?.sub) return session.value.sub;
+  const desktop = nuxtApp.runWithContext(() => useRuntimeConfig()).public.desktop;
+  if (desktop.atprotoPersistence?.loadOwnerDesktopOnMounted)
     return desktop.atprotoDesktop?.owner?.did;
-  }
   return void 0;
 }
-let actorStatesPromise = null;
-async function loadActorStatesOnce(nuxtApp) {
-  await waitForAtprotoReady(nuxtApp);
+const loads = /* @__PURE__ */ new WeakMap();
+export async function ensureActorStatesLoaded(nuxtApp, refresh = false) {
   const actorDid = await resolveRestoreActorDid(nuxtApp);
-  if (!actorDid) {
-    return {};
-  }
-  try {
-    const states = await loadActorDesktopStateMap(nuxtApp, actorDid);
-    return states;
-  } catch (err) {
-    return {};
+  if (!actorDid) return {};
+  const desktopId = resolveDesktopId(nuxtApp);
+  let cache = loads.get(nuxtApp);
+  if (!cache) loads.set(nuxtApp, cache = /* @__PURE__ */ new Map());
+  const key = `${desktopId}/${actorDid}`;
+  if (refresh) cache.delete(key);
+  if (!cache.has(key)) {
+    const task = loadActorDesktopStateMap(nuxtApp, actorDid, desktopId).catch(
+      (error) => {
+        cache.delete(key);
+        throw error;
+      }
+    );
+    cache.set(key, task);
   }
+  return cache.get(key);
 }
-export function ensureActorStatesLoaded(nuxtApp) {
-  if (!actorStatesPromise) {
-    actorStatesPromise = loadActorStatesOnce(nuxtApp);
-  }
-  return actorStatesPromise;
+export function invalidateActorStates(nuxtApp) {
+  loads.delete(nuxtApp);
 }

package/dist/runtime/utils/utilAtprotoWriteQueue.d.ts

@@ -0,0 +1,9 @@
+/** Serializes remote writes per store and retries the latest value after failures. */
+export declare function createAtprotoWriteQueue(write: (key: string, value: string) => Promise<void>, options?: {
+    retryMs?: number;
+    onError?: (error: unknown) => void;
+}): {
+    enqueue(key: string, value: string): Promise<void> | undefined;
+    flush: () => Promise<void[]>;
+    stop(): void;
+};

package/dist/runtime/utils/utilAtprotoWriteQueue.js

@@ -0,0 +1,57 @@
+export function createAtprotoWriteQueue(write, options = {}) {
+  const pending = /* @__PURE__ */ new Map();
+  const acknowledged = /* @__PURE__ */ new Map();
+  const running = /* @__PURE__ */ new Map();
+  const timers = /* @__PURE__ */ new Map();
+  let stopped = false;
+  async function drain(key) {
+    while (!stopped && pending.has(key)) {
+      const value = pending.get(key);
+      try {
+        await write(key, value);
+        acknowledged.set(key, value);
+        if (pending.get(key) === value) pending.delete(key);
+      } catch (error) {
+        options.onError?.(error);
+        if (!stopped && !timers.has(key)) {
+          timers.set(
+            key,
+            setTimeout(() => {
+              timers.delete(key);
+              void flush(key);
+            }, options.retryMs ?? 5e3)
+          );
+        }
+        return;
+      }
+    }
+  }
+  function flush(key) {
+    if (stopped) return Promise.resolve();
+    const active = running.get(key);
+    if (active) return active;
+    const timer = timers.get(key);
+    if (timer) clearTimeout(timer);
+    timers.delete(key);
+    const task = drain(key).finally(() => {
+      running.delete(key);
+    });
+    running.set(key, task);
+    return task;
+  }
+  return {
+    enqueue(key, value) {
+      if (stopped) return;
+      if (!pending.has(key) && acknowledged.get(key) === value) return;
+      pending.set(key, value);
+      return flush(key);
+    },
+    flush: () => Promise.all([...pending.keys()].map(flush)),
+    stop() {
+      stopped = true;
+      for (const timer of timers.values()) clearTimeout(timer);
+      timers.clear();
+      pending.clear();
+    }
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owdproject/nuxt-module-atproto-persistence",
-  "version": "4.0.0-alpha.3",
+  "version": "4.0.0-alpha.4",
   "description": "Pinia persistence via AT Protocol repository, ESM-friendly",
   "license": "MIT",
   "homepage": "https://github.com/atproto-os/module-atproto-persistence",
@@ -37,7 +37,8 @@
     "dev:build": "nuxt build playground",
     "dev:generate": "NUXT_APP_BASE_URL=${NUXT_APP_BASE_URL:-/module-atproto-persistence/} nuxt generate playground",
     "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && cd playground && pnpm exec nuxt prepare",
-    "validate": "desktop validate ."
+    "validate": "desktop validate .",
+    "test:persistence": "vitest run"
   },
   "dependencies": {
     "@nuxt/kit": "^4.6.2",
@@ -51,13 +52,16 @@
     "@owdproject/core": "^4.0.0-alpha.3",
     "nuxt": "^4.6.2",
     "pinia": "^3.0.0",
-    "typescript": "~6.0.3"
+    "typescript": "~6.0.3",
+    "vitest": "^4.1.12",
+    "vue": "^3.5.44"
   },
   "peerDependencies": {
     "@owdproject/core": "^4.0.0-alpha.3",
     "@owdproject/nuxt-module-atproto": "^4.0.0-alpha.3",
-    "pinia": "^3.0.0",
-    "@owdproject/nuxt": "^4.0.0-alpha.3"
+    "pinia": "^3.0.0 || ^4.0.0",
+    "@owdproject/nuxt": "^4.0.0-alpha.3",
+    "vue": ">=3.3.0"
   },
   "publishConfig": {
     "access": "public",