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

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2025  Open Web Desktop Team ~ github.com/owdproject
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,147 @@
-# Temporary Holding Version
+<p align="center">
+  <img width="160" height="160" src="https://avatars.githubusercontent.com/u/201536780?s=160&v=4" />
+</p>
+<h1 align="center">ATProto Persistence Module</h1>
+<h3 align="center">
+  Hybrid Pinia persistence for Open Web Desktop: local-first with AT Protocol sync.
+</h3>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## Overview
+
+This module registers a Pinia persisted-state adapter backed by **IndexedDB**
+(`idb-keyval`) with optional sync to the user's AT Protocol repository. It
+replaces `@owdproject/nuxt-module-pinia-persistence` — **do not install both** in the same
+desktop.
+
+Boot order is handled without core coupling: the plugin runs in Nuxt's **pre**
+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
+
+- 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 nuxt-module-atproto-persistence
+```
+
+## Configuration
+
+```ts
+// desktop/desktop.config.ts
+export default defineDesktopConfig({
+  modules: [
+    '@owdproject/nuxt-module-atproto',
+    '@owdproject/nuxt-module-atproto-persistence',
+  ],
+  atprotoPersistence: {
+    // Load atprotoDesktop.owner.did remote state on boot (not only /actor/:did)
+    loadOwnerDesktopOnMounted: false,
+  },
+})
+```
+
+## Actor resolution (remote hydrate)
+
+After plugin initialization, remote state is fetched when an actor DID is
+resolved:
+
+1. Route `/actor/:did` — view another actor's desktop
+2. Logged-in session — `session.sub`
+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` | `<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. 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
+
+This module is released under the [MIT License](LICENSE).

package/dist/module.d.mts

@@ -0,0 +1,5 @@
+import { NuxtModule } from '@nuxt/schema';
+
+declare const module$1: NuxtModule<any>;
+
+export { module$1 as default };

package/dist/module.json

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

package/dist/module.mjs

@@ -0,0 +1,21 @@
+import { createResolver, addPlugin } from '@nuxt/kit';
+import { defineDesktopModule } from '@owdproject/nuxt/kit';
+
+const module$1 = defineDesktopModule({
+  meta: {
+    name: "desktop-module-atproto-persistence",
+    configKey: "atprotoPersistence"
+  },
+  defaults: {
+    loadOwnerDesktopOnMounted: false
+  },
+  setup(_options, _nuxt) {
+    const { resolve } = createResolver(import.meta.url);
+    addPlugin({
+      src: resolve("./runtime/plugin"),
+      mode: "client"
+    });
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/plugin.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
+export default _default;

package/dist/runtime/plugin.js

@@ -0,0 +1,275 @@
+import { createPersistedStatePlugin } from "pinia-plugin-persistedstate-2";
+import { defineNuxtPlugin } from "nuxt/app";
+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,
+  resolveDesktopId,
+  toLocalStorageKey
+} from "./utils/utilAtprotoApplicationStates.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/"))
+    return key.replace(/^desktop\/application\//, "owd/application/");
+  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"],
+  enforce: "pre",
+  setup(nuxtApp) {
+    const pinia = nuxtApp.$pinia;
+    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;
+    }
+    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
+              );
+            }
+          }
+        }
+      );
+    }
+    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);
+            }
+          });
+          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

@@ -0,0 +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). */
+/**
+ * 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: `<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, desktopId: string): {
+    collection: string;
+    rkey: string;
+} | null;
+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, desktopId: string): Promise<Record<string, any>>;

package/dist/runtime/utils/utilAtprotoApplicationStates.js

@@ -0,0 +1,171 @@
+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) {
+    throw new Error("Failed to fetch profile service endpoint");
+  }
+  const data = await response.json();
+  return data.service[0].serviceEndpoint;
+}
+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];
+    if (last === "windows" || last === "meta") {
+      const appId = parts.slice(2, -1).join("/");
+      return {
+        collection: `org.owdproject.application.${last}`,
+        rkey: `${desktopId}:${encodeRecordKeyPart(appId)}`
+      };
+    }
+  }
+  if (key === "desktop" || key.startsWith("desktop/")) {
+    if (!key.startsWith("desktop/application/")) {
+      const sub = key.slice("desktop/".length);
+      return {
+        collection: "org.owdproject.desktop",
+        rkey: key === "desktop" ? desktopId : `${desktopId}:${encodeRecordKeyPart(sub)}`
+      };
+    }
+  }
+  return null;
+}
+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({
+    repo,
+    collection,
+    rkey
+  });
+}
+export function putAtprotoApplicationState(agent, repo, collection, rkey, record) {
+  return agent.com.atproto.repo.putRecord({
+    repo,
+    collection,
+    rkey,
+    record: { ...record, $type: collection }
+  });
+}
+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)
+    );
+  }
+  const prefix = `${desktopId}:`;
+  const [
+    atprotoActorDesktopList,
+    atprotoApplicationWindowsList,
+    atprotoApplicationMetaList
+  ] = await Promise.allSettled([
+    listAtprotoApplicationStateRecords(
+      actorAgent,
+      actorDid,
+      "org.owdproject.desktop"
+    ),
+    listAtprotoApplicationStateRecords(
+      actorAgent,
+      actorDid,
+      "org.owdproject.application.windows"
+    ),
+    listAtprotoApplicationStateRecords(
+      actorAgent,
+      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();
+      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 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
+      };
+    }
+  }
+  if (atprotoApplicationMetaList.status === "fulfilled") {
+    for (const record of atprotoApplicationMetaList.value) {
+      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
+      };
+    }
+  }
+  return stateMap;
+}

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

@@ -0,0 +1,4 @@
+export declare function resolveRestoreActorDid(nuxtApp: any): Promise<string | undefined>;
+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

@@ -0,0 +1,44 @@
+import { useAtprotoSession } from "#imports";
+import { useRouter, useRuntimeConfig } from "nuxt/app";
+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;
+  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;
+}
+const loads = /* @__PURE__ */ new WeakMap();
+export async function ensureActorStatesLoaded(nuxtApp, refresh = false) {
+  const actorDid = await resolveRestoreActorDid(nuxtApp);
+  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 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/dist/types.d.mts

@@ -0,0 +1,7 @@
+import type { NuxtModule } from '@nuxt/schema'
+
+import type { default as Module } from './module.mjs'
+
+export type ModuleOptions = typeof Module extends NuxtModule<infer O> ? Partial<O> : Record<string, any>
+
+export { default } from './module.mjs'

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@owdproject/nuxt-module-atproto-persistence",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+  "author": {
+    "name": "Open Web Desktop Team",
+    "url": "https://github.com/owdproject"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "development": "./src/module.ts",
+      "import": "./dist/module.mjs",
+      "default": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "nx": {
+    "name": "module-atproto-persistence"
+  },
+  "scripts": {
+    "prepack": "nuxt-module-build build",
+    "dev": "pnpm run dev:prepare && cd playground && pnpm exec nuxt dev",
+    "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 .",
+    "test:persistence": "vitest run"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^4.6.2",
+    "idb-keyval": "^6.2.2",
+    "pinia-plugin-persistedstate-2": "^2.0.30",
+    "@owdproject/nuxt": "^4.0.0-alpha.3"
+  },
+  "devDependencies": {
+    "@nuxt/module-builder": "^1.0.2",
+    "@owdproject/nuxt-app-todo": "^4.0.0-alpha.3",
+    "@owdproject/core": "^4.0.0-alpha.3",
+    "nuxt": "^4.6.2",
+    "pinia": "^3.0.0",
+    "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 || ^4.0.0",
+    "@owdproject/nuxt": "^4.0.0-alpha.3",
+    "vue": ">=3.3.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha",
+    "registry": "https://registry.npmjs.org/"
+  }
+}