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

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,71 @@
-# 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). 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.
+
+## Requirements
+
+- `@owdproject/core` ^3.4.0
+- `@owdproject/module-atproto` (provides OAuth session and agents)
+
+## Installation
+
+```bash
+pnpm desktop add module-atproto-persistence
+```
+
+## Configuration
+
+```ts
+// desktop/desktop.config.ts
+export default defineDesktopConfig({
+  modules: [
+    '@owdproject/module-atproto',
+    '@owdproject/module-atproto-persistence',
+  ],
+  atprotoPersistence: {
+    // Load atprotoDesktop.owner.did remote state on boot (not only /actor/:did)
+    loadOwnerDesktopOnMounted: false,
+  },
+})
+```
+
+## Actor resolution (remote hydrate)
+
+On first store read, remote state is fetched once per boot 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
+
+## 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>` |
+
+When logged in, mapped keys are written to the repo on change (`putRecord`).
+Unmapped keys stay local-only.
+
+## 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.3",
+  "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,100 @@
+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 {
+  putAtprotoApplicationState,
+  parseAtprotoStoreKey
+} from "./utils/utilAtprotoApplicationStates.js";
+import { ensureActorStatesLoaded } from "./utils/utilAtprotoPersistenceLoad.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;
+}
+export default defineNuxtPlugin({
+  name: "desktop-plugin-atproto-persistence",
+  dependsOn: ["pinia", "atproto"],
+  enforce: "pre",
+  async setup(nuxtApp) {
+    const pinia = nuxtApp.$pinia;
+    if (!pinia) {
+      return;
+    }
+    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;
+            }
+            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;
+              }
+            }
+            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);
+          }
+        }
+      })
+    );
+  }
+});

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

@@ -0,0 +1,24 @@
+/** Resolve PDS endpoint via PLC directory (Bluesky); custom PDSs use the same DID document shape. */
+export declare function resolveActorServiceEndpoint(did: string): Promise<string>;
+/**
+ * Maps a Pinia store id to an AT Protocol collection and rkey.
+ *
+ * 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>`)
+ *
+ * Returns `null` for keys that are not persisted to AT Proto.
+ */
+export declare function parseAtprotoStoreKey(key: string): {
+    collection: string;
+    rkey: string;
+} | null;
+export declare function listAtprotoApplicationStateRecords(agent: any, repo: string, collection: string): 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).
+ */
+export declare function loadActorDesktopStateMap(nuxtApp: any, actorDid: string): Promise<Record<string, any>>;

package/dist/runtime/utils/utilAtprotoApplicationStates.js

@@ -0,0 +1,110 @@
+import { useAtprotoAgent, useAtprotoSession } from "#imports";
+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 parseAtprotoStoreKey(key) {
+  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: appId
+      };
+    }
+  }
+  if (key === "desktop" || key.startsWith("desktop/")) {
+    const sub = key.split("/")[1] ?? "self";
+    if (!key.startsWith("desktop/application/")) {
+      return {
+        collection: "org.owdproject.desktop",
+        rkey: 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 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
+  });
+}
+export async function loadActorDesktopStateMap(nuxtApp, actorDid) {
+  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 [
+    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"
+    )
+  ]);
+  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 (atprotoApplicationWindowsList.status === "fulfilled") {
+    for (const record of atprotoApplicationWindowsList.value) {
+      const appId = record.uri.split("/").pop();
+      stateMap[`owd/application/${appId}/windows`] = {
+        windows: record.value.windows
+      };
+    }
+  }
+  if (atprotoApplicationMetaList.status === "fulfilled") {
+    for (const record of atprotoApplicationMetaList.value) {
+      const appId = record.uri.split("/").pop();
+      stateMap[`owd/application/${appId}/meta`] = {
+        ...record.value
+      };
+    }
+  }
+  return stateMap;
+}

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

@@ -0,0 +1,5 @@
+/** 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>>;

package/dist/runtime/utils/utilAtprotoPersistenceLoad.js

@@ -0,0 +1,56 @@
+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);
+  }
+}
+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) {
+    return desktop.atprotoDesktop?.owner?.did;
+  }
+  return void 0;
+}
+let actorStatesPromise = null;
+async function loadActorStatesOnce(nuxtApp) {
+  await waitForAtprotoReady(nuxtApp);
+  const actorDid = await resolveRestoreActorDid(nuxtApp);
+  if (!actorDid) {
+    return {};
+  }
+  try {
+    const states = await loadActorDesktopStateMap(nuxtApp, actorDid);
+    return states;
+  } catch (err) {
+    return {};
+  }
+}
+export function ensureActorStatesLoaded(nuxtApp) {
+  if (!actorStatesPromise) {
+    actorStatesPromise = loadActorStatesOnce(nuxtApp);
+  }
+  return actorStatesPromise;
+}

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,67 @@
 {
   "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.3",
+  "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 ."
+  },
+  "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"
+  },
+  "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"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha",
+    "registry": "https://registry.npmjs.org/"
+  }
+}