@dxos/plugin-wnfs 0.8.4-main.c85a9c8dae → 0.8.4-main.d9fc60f731

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/plugin-wnfs",
-  "version": "0.8.4-main.c85a9c8dae",
+  "version": "0.8.4-main.d9fc60f731",
   "description": "WNFS file management plugin",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -8,86 +8,115 @@
     "type": "git",
     "url": "https://github.com/dxos/dxos"
   },
-  "license": "MIT",
+  "license": "FSL-1.1-Apache-2.0",
   "author": "DXOS.org",
+  "sideEffects": true,
   "type": "module",
+  "imports": {
+    "#capabilities": {
+      "source": "./src/capabilities/index.ts",
+      "types": "./dist/types/src/capabilities/index.d.ts",
+      "default": "./dist/lib/neutral/capabilities/index.mjs"
+    },
+    "#helpers": {
+      "source": "./src/helpers/index.ts",
+      "types": "./dist/types/src/helpers/index.d.ts",
+      "default": "./dist/lib/neutral/helpers/index.mjs"
+    },
+    "#meta": {
+      "source": "./src/meta.ts",
+      "types": "./dist/types/src/meta.d.ts",
+      "default": "./dist/lib/neutral/meta.mjs"
+    },
+    "#plugin": {
+      "source": {
+        "workerd": "./src/WnfsPlugin.workerd.ts",
+        "node": "./src/WnfsPlugin.node.ts",
+        "default": "./src/WnfsPlugin.tsx"
+      },
+      "types": "./dist/types/src/WnfsPlugin.d.ts",
+      "workerd": "./dist/lib/neutral/WnfsPlugin.workerd.mjs",
+      "node": "./dist/lib/neutral/WnfsPlugin.node.mjs",
+      "default": "./dist/lib/neutral/WnfsPlugin.mjs"
+    },
+    "#translations": {
+      "source": "./src/translations.ts",
+      "types": "./dist/types/src/translations.d.ts",
+      "default": "./dist/lib/neutral/translations.mjs"
+    },
+    "#types": {
+      "source": "./src/types/index.ts",
+      "types": "./dist/types/src/types/index.d.ts",
+      "default": "./dist/lib/neutral/types/index.mjs"
+    }
+  },
   "exports": {
     ".": {
       "source": "./src/index.ts",
-      "browser": "./dist/lib/browser/index.mjs",
-      "types": "./dist/types/src/index.d.ts"
+      "types": "./dist/types/src/index.d.ts",
+      "default": "./dist/lib/neutral/index.mjs"
     },
-    "./types": {
-      "source": "./src/types/index.ts",
-      "browser": "./dist/lib/browser/types/index.mjs",
-      "types": "./dist/types/src/types/index.d.ts"
+    "./assets/PLUGIN.mdl": "./PLUGIN.mdl",
+    "./plugin": {
+      "source": "./src/plugin.ts",
+      "types": "./dist/types/src/plugin.d.ts",
+      "default": "./dist/lib/neutral/plugin.mjs"
+    },
+    "./translations": {
+      "source": "./src/translations.ts",
+      "types": "./dist/types/src/translations.d.ts",
+      "default": "./dist/lib/neutral/translations.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {
-      "types": [
-        "dist/types/src/types/index.d.ts"
-      ]
-    }
-  },
   "files": [
     "dist",
-    "src"
+    "src",
+    "PLUGIN.mdl"
   ],
   "dependencies": {
-    "@codemirror/language": "^6.11.3",
-    "@codemirror/state": "^6.5.2",
-    "@codemirror/view": "^6.38.4",
     "@ipld/car": "^5.3.3",
     "blockstore-core": "^5.0.1",
     "blockstore-idb": "^2.0.0",
     "debounce": "^2.2.0",
-    "effect": "3.19.16",
+    "effect": "3.21.2",
     "idb-keyval": "^6.2.1",
     "interface-blockstore": "^5.2.10",
     "it-all": "^3.0.6",
     "multiformats": "^13.2.2",
-    "react-dropzone": "^14.2.3",
     "uint8arrays": "^5.1.0",
     "wnfs": "0.2.2",
-    "@dxos/app-framework": "0.8.4-main.c85a9c8dae",
-    "@dxos/app-toolkit": "0.8.4-main.c85a9c8dae",
-    "@dxos/crypto": "0.8.4-main.c85a9c8dae",
-    "@dxos/effect": "0.8.4-main.c85a9c8dae",
-    "@dxos/log": "0.8.4-main.c85a9c8dae",
-    "@dxos/echo": "0.8.4-main.c85a9c8dae",
-    "@dxos/invariant": "0.8.4-main.c85a9c8dae",
-    "@dxos/operation": "0.8.4-main.c85a9c8dae",
-    "@dxos/plugin-markdown": "0.8.4-main.c85a9c8dae",
-    "@dxos/plugin-client": "0.8.4-main.c85a9c8dae",
-    "@dxos/plugin-space": "0.8.4-main.c85a9c8dae",
-    "@dxos/react-client": "0.8.4-main.c85a9c8dae",
-    "@dxos/react-ui": "0.8.4-main.c85a9c8dae",
-    "@dxos/react-ui-form": "0.8.4-main.c85a9c8dae",
-    "@dxos/react-ui-editor": "0.8.4-main.c85a9c8dae",
-    "@dxos/schema": "0.8.4-main.c85a9c8dae",
-    "@dxos/ui-editor": "0.8.4-main.c85a9c8dae",
-    "@dxos/util": "0.8.4-main.c85a9c8dae",
-    "@dxos/react-ui-stack": "0.8.4-main.c85a9c8dae",
-    "@dxos/react-ui-mosaic": "0.8.4-main.c85a9c8dae"
+    "@dxos/app-toolkit": "0.8.4-main.d9fc60f731",
+    "@dxos/app-framework": "0.8.4-main.d9fc60f731",
+    "@dxos/crypto": "0.8.4-main.d9fc60f731",
+    "@dxos/echo": "0.8.4-main.d9fc60f731",
+    "@dxos/invariant": "0.8.4-main.d9fc60f731",
+    "@dxos/keys": "0.8.4-main.d9fc60f731",
+    "@dxos/log": "0.8.4-main.d9fc60f731",
+    "@dxos/plugin-file": "0.8.4-main.d9fc60f731",
+    "@dxos/plugin-client": "0.8.4-main.d9fc60f731",
+    "@dxos/react-client": "0.8.4-main.d9fc60f731",
+    "@dxos/react-ui": "0.8.4-main.d9fc60f731",
+    "@dxos/types": "0.8.4-main.d9fc60f731",
+    "@dxos/util": "0.8.4-main.d9fc60f731"
   },
   "devDependencies": {
     "@types/react": "~19.2.7",
     "@types/react-dom": "~19.2.3",
     "react": "~19.2.3",
     "react-dom": "~19.2.3",
-    "vite": "^7.1.11",
-    "@dxos/random": "0.8.4-main.c85a9c8dae",
-    "@dxos/storybook-utils": "0.8.4-main.c85a9c8dae",
-    "@dxos/ui-theme": "0.8.4-main.c85a9c8dae"
+    "vite": "^8.0.14",
+    "@dxos/plugin-testing": "0.8.4-main.d9fc60f731",
+    "@dxos/random": "0.8.4-main.d9fc60f731",
+    "@dxos/storybook-utils": "0.8.4-main.d9fc60f731",
+    "@dxos/ui-theme": "0.8.4-main.d9fc60f731"
   },
   "peerDependencies": {
-    "effect": "3.19.16",
+    "effect": "3.21.2",
     "react": "~19.2.3",
     "react-dom": "~19.2.3",
-    "@dxos/react-ui": "0.8.4-main.c85a9c8dae",
-    "@dxos/ui-theme": "0.8.4-main.c85a9c8dae"
+    "@dxos/react-ui": "0.8.4-main.d9fc60f731",
+    "@dxos/ui-theme": "0.8.4-main.d9fc60f731"
   },
   "publishConfig": {
     "access": "public"

package/src/WnfsPlugin.node.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+
+import { meta } from '#meta';
+
+export const WnfsPlugin = Plugin.define(meta).pipe(Plugin.make);
+
+export default WnfsPlugin;

package/src/WnfsPlugin.test.ts

@@ -0,0 +1,20 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { ClientPlugin } from '@dxos/plugin-client/plugin';
+import { createComposerTestApp } from '@dxos/plugin-testing/harness';
+
+import { WnfsPlugin } from '#plugin';
+
+describe('WnfsPlugin', () => {
+  test('activates without errors', async ({ expect }) => {
+    await using harness = await createComposerTestApp({
+      plugins: [ClientPlugin({}), WnfsPlugin()],
+    });
+
+    expect(harness.manager.getActive()).toBeInstanceOf(Array);
+  });
+});

package/src/WnfsPlugin.tsx

@@ -6,37 +6,17 @@ import * as Effect from 'effect/Effect';
 
 import { Capability, Plugin } from '@dxos/app-framework';
 import { AppPlugin } from '@dxos/app-toolkit';
-import { Operation } from '@dxos/operation';
 import { ClientEvents } from '@dxos/plugin-client';
-import { MarkdownEvents } from '@dxos/plugin-markdown';
-import { SpaceCapabilities, SpaceEvents } from '@dxos/plugin-space';
-import { type CreateObject } from '@dxos/plugin-space/types';
 
-import { Blockstore, FileUploader, Markdown, OperationResolver, ReactSurface } from './capabilities';
-import { meta } from './meta';
-import { translations } from './translations';
-import { WnfsAction, WnfsCapabilities, WnfsFile, WnfsOperation } from './types';
+import { Backend, Blockstore, UrlResolver } from '#capabilities';
+import { meta } from '#meta';
+import { translations } from '#translations';
+import { WnfsCapabilities } from '#types';
+
+// eslint-disable-next-line import/no-relative-packages
+import pluginSpec from '../PLUGIN.mdl?raw';
 
 export const WnfsPlugin = Plugin.define(meta).pipe(
-  AppPlugin.addMetadataModule({
-    metadata: {
-      id: WnfsFile.File.typename,
-      metadata: {
-        // TODO(wittjosiah): Would be nice if icon could change based on the type of the file.
-        icon: 'ph--file--regular',
-        iconHue: 'teal',
-        inputSchema: WnfsAction.UploadFileSchema,
-        createObject: ((props, { db }) =>
-          Effect.gen(function* () {
-            const { object } = yield* Operation.invoke(WnfsOperation.CreateFile, { ...props, db });
-            return object;
-          })) satisfies CreateObject,
-      },
-    },
-  }),
-  AppPlugin.addOperationResolverModule({ activate: OperationResolver }),
-  AppPlugin.addSchemaModule({ schema: [WnfsFile.File] }),
-  AppPlugin.addSurfaceModule({ activate: ReactSurface }),
   AppPlugin.addTranslationsModule({ translations }),
   Plugin.addModule({
     id: 'blockstore',
@@ -53,24 +33,19 @@ export const WnfsPlugin = Plugin.define(meta).pipe(
       }),
   }),
   Plugin.addModule({
-    id: 'on-space-created',
-    activatesOn: SpaceEvents.SpaceCreated,
-    activate: () =>
-      Effect.succeed(
-        Capability.contributes(SpaceCapabilities.OnCreateSpace, (params) =>
-          Operation.invoke(WnfsOperation.OnCreateSpace, params),
-        ),
-      ),
+    id: 'backend',
+    activatesOn: ClientEvents.ClientReady,
+    activate: Backend,
   }),
   Plugin.addModule({
-    id: 'file-uploader',
+    id: 'url-resolver',
     activatesOn: ClientEvents.ClientReady,
-    activate: FileUploader,
+    activate: UrlResolver,
   }),
-  Plugin.addModule({
-    id: 'markdown',
-    activatesOn: MarkdownEvents.SetupExtensions,
-    activate: Markdown,
+  AppPlugin.addPluginAssetModule({
+    asset: { pluginId: meta.id, path: 'PLUGIN.mdl', content: pluginSpec, mimeType: 'application/x-mdl' },
   }),
   Plugin.make,
 );
+
+export default WnfsPlugin;

package/src/WnfsPlugin.workerd.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+
+import { meta } from '#meta';
+
+export const WnfsPlugin = Plugin.define(meta).pipe(Plugin.make);
+
+export default WnfsPlugin;

package/src/annotations.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Annotation } from '@dxos/echo';
+
+/** WNFS filesystem state stored on space properties meta. */
+export const WnfsStateAnnotation = Annotation.make({
+  id: 'org.dxos.plugin.wnfs.state',
+  schema: Schema.Struct({
+    accessKey: Schema.String,
+    privateForestCid: Schema.String,
+  }),
+});

package/src/blockstore.ts

@@ -145,7 +145,7 @@ export class MixedBlockstore extends BaseBlockstore {
 
   // QUEUE
 
-  readonly queueCacheName = `${storeName()}/state/queue`;
+  readonly queueCacheName = `${storeName()}.state.queue`;
 
   async #addToQueue(key: CID): Promise<void> {
     await this.#saveQueue([...this.#queue, key.toString()]);

package/src/capabilities/backend.ts

@@ -0,0 +1,43 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { invariant } from '@dxos/invariant';
+import { ClientCapabilities } from '@dxos/plugin-client';
+import { FileCapabilities } from '@dxos/plugin-file/types';
+import { File } from '@dxos/types';
+
+import { WnfsCapabilities } from '#types';
+
+import { upload } from '../helpers';
+
+export const WNFS_BACKEND_ID = 'wnfs';
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const capabilities = yield* Capability.Service;
+
+    return Capability.contributes(FileCapabilities.Backend, {
+      id: WNFS_BACKEND_ID,
+      name: 'WNFS',
+      description: 'Decentralized, end-to-end encrypted storage via Web Native File System.',
+      upload: async (file, db) => {
+        const client = capabilities.get(ClientCapabilities.Client);
+        const blockstore = capabilities.get(WnfsCapabilities.Blockstore);
+        const instances = capabilities.get(WnfsCapabilities.Instances);
+        const space = client.spaces.get(db.spaceId);
+        invariant(space, 'Space not found');
+        const info = await upload({ file, blockstore, instances, space });
+        return {
+          name: info.name,
+          type: info.type,
+          size: file.size,
+          data: File.externalData(info.url, info.cid),
+        };
+      },
+    });
+  }),
+);

package/src/capabilities/{blockstore/blockstore.ts → blockstore.ts}

@@ -7,8 +7,9 @@ import * as Effect from 'effect/Effect';
 import { Capability } from '@dxos/app-framework';
 import { ClientCapabilities } from '@dxos/plugin-client';
 
-import * as Blockstore from '../../blockstore';
-import { WnfsCapabilities } from '../../types';
+import { WnfsCapabilities } from '#types';
+
+import * as Blockstore from '../blockstore';
 
 export default Capability.makeModule(
   Effect.fnUntraced(function* () {

package/src/capabilities/index.ts

@@ -2,8 +2,17 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './blockstore';
-export * from './file-uploader';
-export * from './markdown';
-export * from './operation-resolver';
-export * from './react-surface';
+import { Capability } from '@dxos/app-framework';
+import { type FileCapabilities } from '@dxos/plugin-file/types';
+
+export const Backend: Capability.LazyCapability<
+  void,
+  Capability.Capability<Capability.InterfaceDef<FileCapabilities.Backend>>
+> = Capability.lazy('Backend', () => import('./backend'));
+
+export const Blockstore = Capability.lazy('Blockstore', () => import('./blockstore'));
+
+export const UrlResolver: Capability.LazyCapability<
+  void,
+  Capability.Capability<Capability.InterfaceDef<FileCapabilities.UrlResolver>>
+> = Capability.lazy('UrlResolver', () => import('./url-resolver'));

package/src/capabilities/url-resolver.ts

@@ -0,0 +1,44 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { FileCapabilities } from '@dxos/plugin-file/types';
+
+import { WnfsCapabilities } from '#types';
+
+import { getBlobUrl, loadWnfs } from '../helpers';
+
+export const WNFS_URL_RESOLVER_ID = 'wnfs';
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const capabilities = yield* Capability.Service;
+
+    return Capability.contributes(FileCapabilities.UrlResolver, {
+      id: WNFS_URL_RESOLVER_ID,
+      test: (url) => url.startsWith('wnfs://'),
+      resolve: async (wnfsUrl, file, space) => {
+        if (!space) {
+          return undefined;
+        }
+        try {
+          const blockstore = capabilities.get(WnfsCapabilities.Blockstore);
+          const instances = capabilities.get(WnfsCapabilities.Instances);
+          const { directory, forest } = await loadWnfs({ blockstore, instances, space });
+          return await getBlobUrl({
+            wnfsUrl,
+            blockstore,
+            directory,
+            forest,
+            type: file.type,
+          });
+        } catch {
+          return undefined;
+        }
+      },
+    });
+  }),
+);

package/src/helpers/load.ts

@@ -2,16 +2,18 @@
 // Copyright 2024 DXOS.org
 //
 
+import * as Option from 'effect/Option';
 import type { Blockstore } from 'interface-blockstore';
 import { CID } from 'multiformats';
 import * as Uint8Arrays from 'uint8arrays';
 import { AccessKey, PrivateDirectory, PrivateForest, PrivateNode } from 'wnfs';
 
-import { Obj } from '@dxos/echo';
+import { Annotation, Obj } from '@dxos/echo';
 import { type Space } from '@dxos/react-client/echo';
 
-import { type WnfsCapabilities } from '../types';
+import { type WnfsCapabilities } from '#types';
 
+import { WnfsStateAnnotation } from '../annotations';
 import { Rng, store } from './common';
 
 //
@@ -28,23 +30,37 @@ export const loadWnfs = async ({
   instances?: WnfsCapabilities.Instances;
 }) => {
   // TODO(wittjosiah): Remove.
-  // Delete old properties if they exist.
-  if (space.properties.wnfs_access_key !== undefined && space.properties.wnfs_private_forest_cid !== undefined) {
-    Obj.change(space.properties, (p) => {
-      delete p['wnfs_access_key'];
-      delete p['wnfs_private_forest_cid'];
+  // Delete old properties if they exist (pre-DX-971 migration cleanup).
+  const propsAny = space.properties as any;
+  if (propsAny.wnfs_access_key !== undefined && propsAny.wnfs_private_forest_cid !== undefined) {
+    Obj.update(space.properties, (obj) => {
+      delete (obj as any)['wnfs_access_key'];
+      delete (obj as any)['wnfs_private_forest_cid'];
+    });
+  }
+  // Migrate legacy wnfs data key to annotation.
+  if (propsAny.wnfs !== undefined && Option.isNone(Annotation.get(space.properties, WnfsStateAnnotation))) {
+    Obj.update(space.properties, (properties) => {
+      Annotation.set(properties, WnfsStateAnnotation, propsAny.wnfs);
+      delete (properties as any)['wnfs'];
     });
   }
 
-  const cacheKey = space.properties.wnfs?.privateForestCid;
-  if (instances?.[cacheKey]) {
+  const wnfsState = Annotation.get(space.properties, WnfsStateAnnotation).pipe(Option.getOrUndefined);
+  const cacheKey = wnfsState?.privateForestCid as any;
+  if (cacheKey && instances?.[cacheKey]) {
     return instances[cacheKey];
   }
 
-  const exists = !!space.properties.wnfs;
+  const exists = !!wnfsState;
   const instance = exists ? await loadWnfsDir(blockstore, space) : await createWnfsDir(blockstore, space);
   if (instances) {
-    instances[cacheKey] = instance;
+    // Re-read after createWnfsDir so newly created instances are cached under the real CID.
+    const newCacheKey = Annotation.get(space.properties, WnfsStateAnnotation).pipe(Option.getOrUndefined)
+      ?.privateForestCid as any;
+    if (newCacheKey) {
+      instances[newCacheKey] = instance;
+    }
   }
 
   return instance;
@@ -68,11 +84,11 @@ const createWnfsDir = async (blockstore: Blockstore, space: Space) => {
 
   const cidBytes = await newForest.store(wnfsStore);
 
-  Obj.change(space.properties, (p) => {
-    p.wnfs = {
+  Obj.update(space.properties, (properties) => {
+    Annotation.set(properties, WnfsStateAnnotation, {
       accessKey: Uint8Arrays.toString(accessKeyRaw.toBytes(), 'base64'),
       privateForestCid: CID.decode(cidBytes).toString(),
-    };
+    });
   });
 
   return {
@@ -84,11 +100,9 @@ const createWnfsDir = async (blockstore: Blockstore, space: Space) => {
 const loadWnfsDir = async (blockstore: Blockstore, space: Space) => {
   const wnfsStore = store(blockstore);
 
-  const accessKey = AccessKey.fromBytes(Uint8Arrays.fromString(space.properties.wnfs.accessKey, 'base64'));
-  const forest: PrivateForest = await PrivateForest.load(
-    CID.parse(space.properties.wnfs.privateForestCid).bytes,
-    wnfsStore,
-  );
+  const wnfsState = Annotation.get(space.properties, WnfsStateAnnotation).pipe(Option.getOrUndefined)!;
+  const accessKey = AccessKey.fromBytes(Uint8Arrays.fromString(wnfsState.accessKey, 'base64'));
+  const forest: PrivateForest = await PrivateForest.load(CID.parse(wnfsState.privateForestCid).bytes, wnfsStore);
   const node: PrivateNode = await PrivateNode.load(accessKey, forest, wnfsStore);
 
   return {

package/src/helpers/upload.ts

@@ -2,17 +2,19 @@
 // Copyright 2024 DXOS.org
 //
 
+import * as Option from 'effect/Option';
 import type { Blockstore } from 'interface-blockstore';
 import { CID } from 'multiformats';
 import * as Raw from 'multiformats/codecs/raw';
 import { sha256 } from 'multiformats/hashes/sha2';
 
 import type { Space } from '@dxos/client/echo';
-import { Obj } from '@dxos/echo';
+import { Annotation, Obj } from '@dxos/echo';
 import { log } from '@dxos/log';
 
-import { type WnfsCapabilities } from '../types';
+import { type WnfsCapabilities } from '#types';
 
+import { WnfsStateAnnotation } from '../annotations';
 import { Rng, filePath, store } from './common';
 import { loadWnfs } from './load';
 import { wnfsUrl } from './wnfs-url';
@@ -47,8 +49,15 @@ export const upload = async ({
   const cidBytes = await updatedForest.store(wnfsStore);
 
   // Update the forest pointer on the associated space.
-  Obj.change(space.properties, (p) => {
-    p.wnfs.privateForestCid = CID.decode(cidBytes).toString();
+  const currentState = Annotation.get(space.properties, WnfsStateAnnotation).pipe(Option.getOrUndefined);
+  if (!currentState) {
+    throw new Error('WnfsStateAnnotation missing after loadWnfs; cannot persist forest CID.');
+  }
+  Obj.update(space.properties, (properties) => {
+    Annotation.set(properties, WnfsStateAnnotation, {
+      ...currentState,
+      privateForestCid: CID.decode(cidBytes).toString(),
+    });
   });
 
   // Generate `wnfs://` URL & return the info.

package/src/index.ts

@@ -2,6 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-export { WnfsCapabilities } from './types';
+export * from './annotations';
+export * from './helpers';
 export * from './meta';
-export * from './WnfsPlugin';
+export * from './types';

package/src/meta.ts

@@ -2,17 +2,33 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type Plugin } from '@dxos/app-framework';
+import { Plugin } from '@dxos/app-framework';
+import { DXN } from '@dxos/keys';
+import { meta as fileMeta } from '@dxos/plugin-file';
 import { trim } from '@dxos/util';
 
-export const meta: Plugin.Meta = {
-  id: 'dxos.org/plugin/wnfs',
+export const meta = Plugin.makeMeta({
+  key: DXN.make('org.dxos.plugin.wnfs'),
   name: 'WNFS',
+  author: 'DXOS',
   description: trim`
-    Decentralized file storage using the Web Native File System protocol.
-    Store and sync files with end-to-end encryption across devices without central servers.
+    Decentralized, end-to-end encrypted file storage for DXOS Composer built on the Web Native File System (WNFS) protocol.
+
+    WNFS organizes files inside a cryptographic "dark forest" — a content-addressed private file system
+    where each write produces a new immutable root CID. Files are stored as IPLD blocks (CIDv1, sha2-256),
+    cached locally in IndexedDB, and asynchronously replicated to the DXOS edge blob service as CAR archives.
+    Uploads and reads are scoped to a DXOS Space; the forest root CID is persisted atomically on the
+    space's ECHO properties so the file system state survives across sessions and devices.
+
+    The plugin registers as a \`FileCapabilities.Backend\` and \`FileCapabilities.UrlResolver\` so any plugin
+    that uses \`plugin-file\` (e.g. \`plugin-gallery\`) can upload files and resolve \`wnfs://\` URLs without
+    coupling to the storage implementation. The blockstore automatically queues blocks while offline and
+    flushes them when connectivity is restored.
   `,
   icon: 'ph--file-cloud--regular',
   iconHue: 'teal',
   source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/plugin-wnfs',
-};
+  spec: 'PLUGIN.mdl',
+  tags: ['labs'],
+  dependsOn: [fileMeta.id],
+});

package/src/plugin.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+
+import { meta } from './meta';
+
+export const WnfsPlugin = Plugin.lazy(meta, () => import('#plugin'));