@dxos/plugin-wnfs 0.9.1-staging.ee54ba693a → 0.11.0

package/dx.config.ts

@@ -19,10 +19,10 @@ export default Config2.make({
       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.
+      The plugin registers a \`BlobBackend\` on the ECHO Hypergraph (and a matching \`FileCapabilities.Backend\`
+      descriptor) so any plugin that uses \`plugin-file\` (e.g. \`plugin-studio\`) 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: { key: 'ph--file-cloud--regular', hue: 'teal' },
     source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/plugin-wnfs',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/plugin-wnfs",
-  "version": "0.9.1-staging.ee54ba693a",
+  "version": "0.11.0",
   "description": "WNFS file management plugin",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -16,17 +16,17 @@
     "#capabilities": {
       "source": "./src/capabilities/index.ts",
       "types": "./dist/types/src/capabilities/index.d.ts",
-      "default": "./dist/lib/neutral/capabilities/index.mjs"
+      "default": "./dist/lib/capabilities.mjs"
     },
     "#helpers": {
       "source": "./src/helpers/index.ts",
       "types": "./dist/types/src/helpers/index.d.ts",
-      "default": "./dist/lib/neutral/helpers/index.mjs"
+      "default": "./dist/lib/helpers.mjs"
     },
     "#meta": {
       "source": "./src/meta.ts",
       "types": "./dist/types/src/meta.d.ts",
-      "default": "./dist/lib/neutral/meta.mjs"
+      "default": "./dist/lib/meta.mjs"
     },
     "#plugin": {
       "source": {
@@ -35,37 +35,37 @@
         "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"
+      "workerd": "./dist/lib/WnfsPlugin.workerd.mjs",
+      "node": "./dist/lib/WnfsPlugin.node.mjs",
+      "default": "./dist/lib/WnfsPlugin.mjs"
     },
     "#translations": {
       "source": "./src/translations.ts",
       "types": "./dist/types/src/translations.d.ts",
-      "default": "./dist/lib/neutral/translations.mjs"
+      "default": "./dist/lib/translations.mjs"
     },
     "#types": {
       "source": "./src/types/index.ts",
       "types": "./dist/types/src/types/index.d.ts",
-      "default": "./dist/lib/neutral/types/index.mjs"
+      "default": "./dist/lib/types.mjs"
     }
   },
   "exports": {
     ".": {
       "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
-      "default": "./dist/lib/neutral/index.mjs"
+      "import": "./dist/lib/index.mjs"
     },
     "./assets/PLUGIN.mdl": "./PLUGIN.mdl",
     "./plugin": {
       "source": "./src/plugin.ts",
       "types": "./dist/types/src/plugin.d.ts",
-      "default": "./dist/lib/neutral/plugin.mjs"
+      "import": "./dist/lib/plugin.mjs"
     },
     "./translations": {
       "source": "./src/translations.ts",
       "types": "./dist/types/src/translations.d.ts",
-      "default": "./dist/lib/neutral/translations.mjs"
+      "import": "./dist/lib/translations.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
@@ -87,37 +87,39 @@
     "multiformats": "^13.2.2",
     "uint8arrays": "^5.1.0",
     "wnfs": "0.2.2",
-    "@dxos/app-framework": "0.9.1-staging.ee54ba693a",
-    "@dxos/app-toolkit": "0.9.1-staging.ee54ba693a",
-    "@dxos/crypto": "0.9.1-staging.ee54ba693a",
-    "@dxos/echo": "0.9.1-staging.ee54ba693a",
-    "@dxos/invariant": "0.9.1-staging.ee54ba693a",
-    "@dxos/log": "0.9.1-staging.ee54ba693a",
-    "@dxos/plugin-client": "0.9.1-staging.ee54ba693a",
-    "@dxos/plugin-file": "0.9.1-staging.ee54ba693a",
-    "@dxos/react-client": "0.9.1-staging.ee54ba693a",
-    "@dxos/react-ui": "0.9.1-staging.ee54ba693a",
-    "@dxos/types": "0.9.1-staging.ee54ba693a",
-    "@dxos/util": "0.9.1-staging.ee54ba693a",
-    "@dxos/keys": "0.9.1-staging.ee54ba693a"
+    "@dxos/app-toolkit": "0.11.0",
+    "@dxos/client": "0.11.0",
+    "@dxos/echo": "0.11.0",
+    "@dxos/echo-protocol": "0.11.0",
+    "@dxos/crypto": "0.11.0",
+    "@dxos/invariant": "0.11.0",
+    "@dxos/keys": "0.11.0",
+    "@dxos/log": "0.11.0",
+    "@dxos/plugin-client": "0.11.0",
+    "@dxos/react-client": "0.11.0",
+    "@dxos/react-ui": "0.11.0",
+    "@dxos/types": "0.11.0",
+    "@dxos/plugin-file": "0.11.0",
+    "@dxos/util": "0.11.0",
+    "@dxos/app-framework": "0.11.0"
   },
   "devDependencies": {
     "@types/react": "~19.2.17",
     "@types/react-dom": "~19.2.3",
     "react": "~19.2.7",
     "react-dom": "~19.2.7",
-    "vite": "^8.0.16",
-    "@dxos/plugin-testing": "0.9.1-staging.ee54ba693a",
-    "@dxos/random": "0.9.1-staging.ee54ba693a",
-    "@dxos/ui-theme": "0.9.1-staging.ee54ba693a",
-    "@dxos/storybook-utils": "0.9.1-staging.ee54ba693a"
+    "vite": "^8.1.4",
+    "@dxos/plugin-testing": "0.11.0",
+    "@dxos/storybook-utils": "0.11.0",
+    "@dxos/ui-theme": "0.11.0",
+    "@dxos/random": "0.11.0"
   },
   "peerDependencies": {
     "effect": "3.21.4",
     "react": "~19.2.7",
     "react-dom": "~19.2.7",
-    "@dxos/react-ui": "0.9.1-staging.ee54ba693a",
-    "@dxos/ui-theme": "0.9.1-staging.ee54ba693a"
+    "@dxos/react-ui": "^0.11.0",
+    "@dxos/ui-theme": "^0.11.0"
   },
   "publishConfig": {
     "access": "public"

package/src/WnfsPlugin.tsx

@@ -2,16 +2,14 @@
 // Copyright 2024 DXOS.org
 //
 
-import * as Effect from 'effect/Effect';
-
-import { Capability, Plugin } from '@dxos/app-framework';
+import { Plugin } from '@dxos/app-framework';
 import { AppPlugin } from '@dxos/app-toolkit';
 import { ClientEvents } from '@dxos/plugin-client';
 
-import { Backend, Blockstore, UrlResolver } from '#capabilities';
+import { BlobBackend, Dependencies } from '#capabilities';
 import { meta } from '#meta';
 import { translations } from '#translations';
-import { WnfsCapabilities } from '#types';
+import { WnfsEvents } from '#types';
 
 // eslint-disable-next-line import/no-relative-packages
 import pluginSpec from '../PLUGIN.mdl?raw';
@@ -19,28 +17,15 @@ import pluginSpec from '../PLUGIN.mdl?raw';
 export const WnfsPlugin = Plugin.define(meta).pipe(
   AppPlugin.addTranslationsModule({ translations }),
   Plugin.addModule({
-    id: 'blockstore',
-    activatesOn: ClientEvents.ClientReady,
-    activate: Blockstore,
-  }),
-  Plugin.addModule({
-    id: 'instances',
+    id: 'dependencies',
     activatesOn: ClientEvents.ClientReady,
-    activate: () =>
-      Effect.sync(() => {
-        const instances: WnfsCapabilities.Instances = {};
-        return Capability.contributes(WnfsCapabilities.Instances, instances);
-      }),
+    firesAfterActivation: [WnfsEvents.DependenciesReady],
+    activate: Dependencies,
   }),
   Plugin.addModule({
-    id: 'backend',
-    activatesOn: ClientEvents.ClientReady,
-    activate: Backend,
-  }),
-  Plugin.addModule({
-    id: 'url-resolver',
-    activatesOn: ClientEvents.ClientReady,
-    activate: UrlResolver,
+    id: 'blob-backend',
+    activatesOn: WnfsEvents.DependenciesReady,
+    activate: BlobBackend,
   }),
   AppPlugin.addPluginAssetModule({
     asset: { pluginId: meta.profile.key, path: 'PLUGIN.mdl', content: pluginSpec, mimeType: 'application/x-mdl' },

package/src/capabilities/blob-backend.test.ts

@@ -0,0 +1,108 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test, vi } from 'vitest';
+
+import { type Client } from '@dxos/client';
+import { SpaceId } from '@dxos/keys';
+
+import { WnfsCapabilities } from '#types';
+
+vi.mock('../helpers', () => ({
+  loadWnfs: vi.fn(),
+  readWnfsFile: vi.fn(),
+  upload: vi.fn(),
+  getBlobUrl: vi.fn(),
+}));
+
+import { getBlobUrl, loadWnfs, readWnfsFile, upload } from '../helpers';
+import { createWnfsBlobBackend } from './blob-backend';
+
+describe('createWnfsBlobBackend', () => {
+  // Test doubles: `Client`/`Space`/`Blockstore`/`PrivateDirectory`/`PrivateForest` are only ever
+  // passed through to the mocked `../helpers` functions below, never inspected by the backend
+  // itself, so minimal stand-ins are sufficient.
+  const spaceId = SpaceId.random();
+  const space = { id: spaceId } as any;
+  const client = { spaces: { get: (id: SpaceId) => (id === spaceId ? space : undefined) } } as unknown as Client;
+  const blockstore = {} as any;
+
+  test('schemes includes the wnfs scheme', ({ expect }) => {
+    const backend = createWnfsBlobBackend({ client, blockstore });
+    expect(backend.schemes).toContain(WnfsCapabilities.WNFS_SCHEME);
+  });
+
+  test('put uploads via the upload helper and returns its url as the URI', async ({ expect }) => {
+    vi.mocked(upload).mockResolvedValueOnce({
+      name: 'photo.png',
+      type: 'image/png',
+      url: 'wnfs://spaces/x/files/abc',
+      cid: 'abc',
+    });
+    const backend = createWnfsBlobBackend({ client, blockstore });
+
+    const response = await backend.put({
+      spaceId,
+      data: new Uint8Array([1, 2, 3]),
+      contentType: 'image/png',
+      contentHash: 'abc',
+    });
+
+    expect(response.uri).toBe('wnfs://spaces/x/files/abc');
+    expect(upload).toHaveBeenCalledWith(expect.objectContaining({ blockstore, space }));
+  });
+
+  test('get returns undefined when the space is not found', async ({ expect }) => {
+    const backend = createWnfsBlobBackend({ client, blockstore });
+    const result = await backend.get({ spaceId: SpaceId.random(), uri: 'wnfs://x' });
+    expect(result).toBeUndefined();
+  });
+
+  test('get reads bytes via loadWnfs + readWnfsFile', async ({ expect }) => {
+    const directory = {} as any;
+    const forest = {} as any;
+    vi.mocked(loadWnfs).mockResolvedValueOnce({ directory, forest });
+    vi.mocked(readWnfsFile).mockResolvedValueOnce(new Uint8Array([9, 8, 7]));
+
+    const backend = createWnfsBlobBackend({ client, blockstore });
+    const result = await backend.get({ spaceId, uri: 'wnfs://spaces/x/files/abc' });
+
+    expect(result).toEqual(new Uint8Array([9, 8, 7]));
+    expect(readWnfsFile).toHaveBeenCalledWith(
+      expect.objectContaining({ wnfsUrl: 'wnfs://spaces/x/files/abc', directory, forest }),
+    );
+  });
+
+  test('get returns undefined when reading throws', async ({ expect }) => {
+    vi.mocked(loadWnfs).mockRejectedValueOnce(new Error('boom'));
+    const backend = createWnfsBlobBackend({ client, blockstore });
+    const result = await backend.get({ spaceId, uri: 'wnfs://spaces/x/files/missing' });
+    expect(result).toBeUndefined();
+  });
+
+  test('has reflects whether get resolves bytes', async ({ expect }) => {
+    vi.mocked(loadWnfs).mockResolvedValueOnce({ directory: {} as any, forest: {} as any });
+    vi.mocked(readWnfsFile).mockResolvedValueOnce(new Uint8Array([1]));
+    const backend = createWnfsBlobBackend({ client, blockstore });
+    expect(await backend.has({ spaceId, uri: 'wnfs://spaces/x/files/abc' })).toBe(true);
+
+    vi.mocked(loadWnfs).mockRejectedValueOnce(new Error('boom'));
+    expect(await backend.has({ spaceId, uri: 'wnfs://spaces/x/files/missing' })).toBe(false);
+  });
+
+  test('getUrl resolves via the getBlobUrl helper', async ({ expect }) => {
+    const directory = {} as any;
+    const forest = {} as any;
+    vi.mocked(loadWnfs).mockResolvedValueOnce({ directory, forest });
+    vi.mocked(getBlobUrl).mockResolvedValueOnce('blob:http://local/abc');
+
+    const backend = createWnfsBlobBackend({ client, blockstore });
+    const url = await backend.getUrl!({ spaceId, uri: 'wnfs://spaces/x/files/abc', contentType: 'image/png' });
+
+    expect(url).toBe('blob:http://local/abc');
+    expect(getBlobUrl).toHaveBeenCalledWith(
+      expect.objectContaining({ wnfsUrl: 'wnfs://spaces/x/files/abc', type: 'image/png' }),
+    );
+  });
+});

package/src/capabilities/blob-backend.ts

@@ -0,0 +1,104 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import type { Blockstore } from 'interface-blockstore';
+
+import { Capability } from '@dxos/app-framework';
+import { type Client } from '@dxos/client';
+import { type BlobBackend } from '@dxos/echo-protocol';
+import { invariant } from '@dxos/invariant';
+import { type SpaceId } from '@dxos/keys';
+import { log } from '@dxos/log';
+import { ClientCapabilities } from '@dxos/plugin-client';
+import { FileCapabilities } from '@dxos/plugin-file/types';
+
+import { WnfsCapabilities } from '#types';
+
+import { getBlobUrl, loadWnfs, readWnfsFile, upload } from '../helpers';
+
+interface CreateWnfsBlobBackendOptions {
+  client: Client;
+  blockstore: Blockstore;
+  instances?: WnfsCapabilities.Instances;
+}
+
+/**
+ * Blob backend that stores bytes in a space's WNFS private forest, addressed by `wnfs://…` URIs.
+ * The underlying WASM bindings (`directory.read`) don't expose a distinct not-found error type, so
+ * `readBytes`/`getUrl` can't tell a missing path from a genuine transport/blockstore failure —
+ * both are logged and reported as a miss (`undefined`) rather than risk rethrowing on the common
+ * missing-file path.
+ */
+export const createWnfsBlobBackend = ({ client, blockstore, instances }: CreateWnfsBlobBackendOptions): BlobBackend => {
+  const readBytes = async (spaceId: SpaceId, uri: string) => {
+    const space = client.spaces.get(spaceId);
+    if (!space) {
+      return undefined;
+    }
+    try {
+      const { directory, forest } = await loadWnfs({ blockstore, instances, space });
+      return await readWnfsFile({ wnfsUrl: uri, blockstore, forest, directory });
+    } catch (error) {
+      log.warn('failed to read wnfs blob', { spaceId, uri, error });
+      return undefined;
+    }
+  };
+
+  return {
+    schemes: [WnfsCapabilities.WNFS_SCHEME],
+
+    put: async ({ spaceId, data, contentType, contentHash, name }) => {
+      const space = client.spaces.get(spaceId);
+      invariant(space, 'Space not found');
+      // `Uint8Array` is generic over `ArrayBufferLike` (incl. `SharedArrayBuffer`) while DOM's
+      // `BlobPart` only covers `ArrayBuffer`-backed views — a gap between the DOM lib types and
+      // the TS standard lib, not fixable by typing `data` differently.
+      const file = new File([data as BlobPart], name ?? contentHash, { type: contentType });
+      const info = await upload({ file, blockstore, instances, space });
+      return { uri: info.url };
+    },
+
+    get: async ({ spaceId, uri }) => readBytes(spaceId, uri),
+
+    has: async ({ spaceId, uri }) => (await readBytes(spaceId, uri)) !== undefined,
+
+    getUrl: async ({ spaceId, uri, contentType }) => {
+      const space = client.spaces.get(spaceId);
+      if (!space) {
+        return undefined;
+      }
+      try {
+        const { directory, forest } = await loadWnfs({ blockstore, instances, space });
+        return await getBlobUrl({ wnfsUrl: uri, blockstore, directory, forest, type: contentType });
+      } catch (error) {
+        log.warn('failed to resolve wnfs blob url', { spaceId, uri, error });
+        return undefined;
+      }
+    },
+  };
+};
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const client = yield* Capability.get(ClientCapabilities.Client);
+    const blockstore = yield* Capability.get(WnfsCapabilities.Blockstore);
+    const instances = yield* Capability.get(WnfsCapabilities.Instances);
+
+    const cleanup = client.graph.registerBlobBackend(
+      WnfsCapabilities.WNFS_BACKEND,
+      createWnfsBlobBackend({ client, blockstore, instances }),
+    );
+
+    return Capability.contributes(
+      FileCapabilities.Backend,
+      {
+        name: 'WNFS',
+        description: 'Decentralized, end-to-end encrypted storage via Web Native File System.',
+        storage: WnfsCapabilities.WNFS_BACKEND,
+      },
+      () => Effect.sync(() => cleanup()),
+    );
+  }),
+);

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

@@ -18,6 +18,11 @@ export default Capability.makeModule(
     const blockstore = Blockstore.create(apiHost);
     yield* Effect.tryPromise(() => blockstore.open());
 
-    return Capability.contributes(WnfsCapabilities.Blockstore, blockstore);
+    const instances: WnfsCapabilities.Instances = {};
+
+    return [
+      Capability.contributes(WnfsCapabilities.Blockstore, blockstore),
+      Capability.contributes(WnfsCapabilities.Instances, instances),
+    ];
   }),
 );

package/src/capabilities/index.ts

@@ -4,8 +4,6 @@
 
 import { Capability } from '@dxos/app-framework';
 
-export const Backend = Capability.lazy('Backend', () => import('./backend'));
+export const BlobBackend = Capability.lazy('BlobBackend', () => import('./blob-backend'));
 
-export const Blockstore = Capability.lazy('Blockstore', () => import('./blockstore'));
-
-export const UrlResolver = Capability.lazy('UrlResolver', () => import('./url-resolver'));
+export const Dependencies = Capability.lazy('Dependencies', () => import('./dependencies'));

package/src/helpers/wnfs-url.ts

@@ -17,6 +17,23 @@ export const getPathFromUrl = (wnfsUrl: string) =>
     .split('/')
     .map((p) => decodeURIComponent(p));
 
+export const readWnfsFile = async ({
+  wnfsUrl,
+  blockstore,
+  forest,
+  directory,
+}: {
+  wnfsUrl: string;
+  blockstore: Blockstore;
+  forest: PrivateForest;
+  directory: PrivateDirectory;
+}): Promise<Uint8Array> => {
+  const path = getPathFromUrl(wnfsUrl);
+  const wnfsStore = store(blockstore);
+  const { result } = await directory.read(path, true, forest, wnfsStore);
+  return result;
+};
+
 export const getBlobUrl = async ({
   wnfsUrl,
   blockstore,
@@ -30,9 +47,10 @@ export const getBlobUrl = async ({
   directory: PrivateDirectory;
   type?: string;
 }) => {
-  const path = getPathFromUrl(wnfsUrl);
-  const wnfsStore = store(blockstore);
-  const { result } = await directory.read(path, true, forest, wnfsStore);
-  const blob = new Blob([result], { type });
+  const result = await readWnfsFile({ wnfsUrl, blockstore, forest, directory });
+  // `Uint8Array` is generic over `ArrayBufferLike` (incl. `SharedArrayBuffer`) while DOM's
+  // `BlobPart` only covers `ArrayBuffer`-backed views — a gap between the DOM lib types and the
+  // TS standard lib, not fixable by typing `result` differently.
+  const blob = new Blob([result as BlobPart], { type });
   return URL.createObjectURL(blob);
 };

package/src/types/WnfsCapabilities.ts

@@ -16,3 +16,12 @@ export const Blockstore = Capability.make<BlockstoreInterface>(`${meta.profile.k
 
 export type Instances = Record<SpaceId, { directory: PrivateDirectory; forest: PrivateForest }>;
 export const Instances = Capability.make<Instances>(`${meta.profile.key}.capability.instances`);
+
+/**
+ * Name this extension registers its `BlobBackend` under on the ECHO Hypergraph. Core packages
+ * (`@dxos/echo`, `@dxos/echo-client`, `@dxos/client`) never reference this constant.
+ */
+export const WNFS_BACKEND = 'wnfs';
+
+/** URI scheme this extension's `BlobBackend` resolves at read time. */
+export const WNFS_SCHEME = 'wnfs';

package/src/types/WnfsEvents.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import { ActivationEvent } from '@dxos/app-framework';
+
+import { meta } from '#meta';
+
+/**
+ * Fired by the `dependencies` module (via `firesAfterActivation`) once it finishes contributing
+ * `WnfsCapabilities.Blockstore`/`Instances`. `blob-backend` activates on this event rather than
+ * `ClientEvents.ClientReady` directly — `dependencies` also activates on `ClientReady`, and
+ * modules activating on the same event load concurrently with capabilities invisible to each
+ * other until the whole batch settles, so `blob-backend` couldn't otherwise be guaranteed to run
+ * after `dependencies`.
+ */
+export const DependenciesReady = ActivationEvent.make(`${meta.profile.key}.event.dependenciesReady`);

package/src/types/index.ts

@@ -3,3 +3,4 @@
 //
 
 export * as WnfsCapabilities from './WnfsCapabilities';
+export * as WnfsEvents from './WnfsEvents';

package/dist/lib/neutral/WnfsPlugin.mjs

@@ -1,51 +0,0 @@
-import "./chunk-J5LGTIGS.mjs";
-
-// src/WnfsPlugin.tsx
-import * as Effect from "effect/Effect";
-import { Capability, Plugin } from "@dxos/app-framework";
-import { AppPlugin } from "@dxos/app-toolkit";
-import { ClientEvents } from "@dxos/plugin-client";
-import { Backend, Blockstore, UrlResolver } from "#capabilities";
-import { meta } from "#meta";
-import { translations } from "#translations";
-import { WnfsCapabilities } from "#types";
-
-// raw-loader:/__w/dxos/dxos/packages/plugins/plugin-wnfs/PLUGIN.mdl
-var PLUGIN_default = "---\nid: org.dxos.plugin.wnfs\nname: WnfsPlugin\nversion: 0.1.0\n---\n\nA decentralized file storage plugin for `DXOS` Composer built on the Web Native File System (WNFS) protocol.\n\nWNFS provides a content-addressed, end-to-end encrypted private file system using a cryptographic \"dark forest\"\nstructure. Files are stored as IPLD blocks referenced by CID, replicated to a DXOS edge blob service, and\ncached locally in IndexedDB. The plugin implements the `FileCapabilities.Backend` and `FileCapabilities.UrlResolver`\ninterfaces from `plugin-file`, so other plugins (e.g. `plugin-gallery`) can upload and resolve `wnfs://` URLs\nwithout knowing the underlying storage layer. Uploads are scoped to a DXOS Space; the private forest root CID\nis persisted on the space's ECHO properties and updated atomically on every write.\n\n## Extensions\n\nThe following extension dialects are used in this document.\nEach extension is defined in the Appendix or resolved via its URI.\n\n| Term        | URI                            |\n|-------------|--------------------------------|\n| `type`      | `org.dxos.mdl.type@1.0`       |\n| `feat`      | `org.dxos.mdl.feat@1.0`       |\n| `test`      | `org.dxos.mdl.test@1.0`       |\n| `component` | `org.dxos.mdl.component@1.0`  |\n| `op`        | `org.dxos.mdl.op@1.0`         |\n\n## Types\n\n```mdl\ntype Cid\n  desc: A content-addressed identifier encoded as a base-32 multibase string (CIDv1, sha2-256).\n  fields:\n    value: string\n```\n\n```mdl\ntype WnfsPath\n  desc: A WNFS path encoded as a wnfs:// URL; segments are percent-encoded.\n  fields:\n    url: string               # wnfs://spaces/<spaceId>/files/<cid>\n```\n\n```mdl\ntype FileInfo\n  desc: Metadata returned after a successful upload.\n  fields:\n    name: string              # Original file name\n    type: string              # MIME type\n    url: WnfsPath             # wnfs:// URL for later retrieval\n    cid: Cid                  # Raw content CID of the file bytes\n```\n\n```mdl\ntype BlockstoreState\n  desc: Runtime state of the MixedBlockstore.\n  fields:\n    isConnected: boolean      # Online / offline status\n    queueLength: number       # Blocks pending remote flush\n    apiHost: string           # DXOS edge service base URL\n```\n\n```mdl\ntype WnfsInstances\n  desc: In-memory cache mapping forest CID \u2192 loaded PrivateDirectory/PrivateForest pair.\n  fields:\n    entries: Record<string, WnfsInstance>\n```\n\n```mdl\ntype WnfsInstance\n  desc: A loaded WNFS private file system rooted at a specific forest CID.\n  fields:\n    directory: PrivateDirectory\n    forest: PrivateForest\n```\n```\n\n## Operations\n\nPure operations \u2014 no external effects.\n\n```mdl\nop wnfsUrl\n  desc: Encodes a WNFS path array into a wnfs:// URL with percent-encoded segments.\n  input:\n    filePath: string[]\n  output: string\n```\n\n```mdl\nop getPathFromUrl\n  desc: Decodes a wnfs:// URL back into a path segment array.\n  input:\n    wnfsUrl: string\n  output: string[]\n```\n\nEffectful operations \u2014 read or write persistent state.\n\n```mdl\nop uploadFile\n  desc: |\n    Reads a File, writes its bytes into the WNFS private directory at a\n    CID-derived path, persists the updated forest pointer to the space's\n    ECHO properties, and returns FileInfo.\n  input:\n    file: File\n    space: Space\n  output: FileInfo\n  effects: [fs:read, echo:write, http:post]\n  errors:\n    SpaceNotFound: no space matching the given spaceId\n    BlockstoreError: local or remote block I/O failure\n  note: |\n    Uses sha256 for block hashing (not the rs-wnfs default Blake3) for\n    broader runtime support. Writes are atomic from ECHO's perspective:\n    the forest CID property is only updated after the forest is stored.\n```\n\n```mdl\nop resolveWnfsUrl\n  desc: |\n    Reads file bytes from the WNFS private directory for a wnfs:// URL,\n    wraps them in a Blob, and returns an object URL for in-browser display.\n  input:\n    wnfsUrl: string\n    space: Space\n    type?: string             # MIME type hint for Blob construction\n  output: string              # blob: object URL\n  effects: [fs:read, http:get]\n  errors:\n    UrlNotResolvable: space not available or file not found in directory\n  note: Errors are swallowed and undefined is returned to avoid breaking image renders.\n```\n\n```mdl\nop flushBlockQueue\n  desc: |\n    Drains the pending-upload queue by assembling a CAR archive and POSTing\n    it to the edge blob service. Called automatically (debounced 5 s) on\n    block writes and on the browser `online` event.\n  input:\n    blockstore: Blockstore\n  output: void\n  effects: [http:post]\n  errors:\n    NetworkError: remote POST failed\n  note: Queue is persisted to IndexedDB so pending blocks survive page reloads.\n```\n\n## Features\n\n```mdl\nfeat F-1: Upload File\n\n  req F-1.1:\n    when: a FileCapabilities.Backend consumer calls upload(file, db)\n    then: the file is read, hashed, written to the WNFS private directory,\n          and stored in the blockstore\n\n  req F-1.2:\n    when: the write succeeds\n    then: the space's ECHO properties are updated with the new privateForestCid\n\n  req F-1.3:\n    when: the upload completes\n    then: a FileInfo object with name, type, size, and wnfs:// URL is returned to the caller\n```\n\n```mdl\nfeat F-2: Resolve wnfs:// URL\n\n  req F-2.1:\n    when: FileCapabilities.UrlResolver.test(url) is called with a wnfs:// URL\n    then: returns true\n\n  req F-2.2:\n    when: FileCapabilities.UrlResolver.resolve(url, file, space) is called\n    then: loads or reuses a cached WnfsInstance for the space and reads the file bytes\n\n  req F-2.3:\n    when: bytes are successfully read\n    then: a blob: object URL is returned for in-browser display\n\n  req F-2.4:\n    when: the space is undefined or reading fails\n    then: undefined is returned; no error is propagated\n```\n\n```mdl\nfeat F-3: Blockstore Sync\n\n  req F-3.1:\n    when: a block is written via blockstore.put\n    then: the block is saved to IndexedDB and added to the upload queue\n\n  req F-3.2:\n    when: the browser is online and the queue is non-empty\n    then: blocks are batched into a CAR archive and flushed to the edge service\n\n  req F-3.3:\n    when: the browser goes offline\n    then: the queue is persisted to IndexedDB; no upload is attempted\n\n  req F-3.4:\n    when: the browser comes back online\n    then: the flush is triggered automatically\n\n  req F-3.5:\n    when: a block is requested via blockstore.get and is present in IndexedDB\n    then: the block is returned from the local cache without a network request\n\n  req F-3.6:\n    when: a block is not in IndexedDB and the browser is online\n    then: the block is fetched from the edge service and cached locally\n```\n\n```mdl\nfeat F-4: Space-Scoped Private File System\n\n  req F-4.1:\n    when: a space has no existing WNFS properties\n    then: a new PrivateForest and PrivateDirectory are created and stored\n\n  req F-4.2:\n    when: a space already has a privateForestCid\n    then: the existing forest and directory are loaded from the blockstore\n\n  req F-4.3:\n    when: a WnfsInstance is already cached for the current forest CID\n    then: the cached instance is reused without reloading from the blockstore\n\n  req F-4.4:\n    when: legacy snake_case WNFS properties are found on a space\n    then: they are deleted and replaced with the current camelCase schema\n    tags: [migration]\n```\n\n## Acceptance\n\n```mdl\ntest T-1: Upload creates FileInfo\n  given: an active space and a registered WNFS backend\n  when: a file is uploaded via the Backend capability\n  then:\n    - FileInfo.url starts with wnfs://\n    - space.properties.wnfs.privateForestCid is set\n    - block for the file is present in the local IndexedDB blockstore\n```\n\n```mdl\ntest T-2: Resolve uploaded file\n  given: a file was previously uploaded and FileInfo.url is known\n  when: UrlResolver.resolve(url, file, space) is called\n  then:\n    - a blob: object URL is returned\n    - URL can be used as an img src\n```\n\n```mdl\ntest T-3: Resolve without space returns undefined\n  given: a wnfs:// URL\n  when: UrlResolver.resolve is called with space = undefined\n  then: undefined is returned; no error is thrown\n```\n\n```mdl\ntest T-4: Blockstore offline queuing\n  given: the browser is offline\n  when: a block is written to the blockstore\n  then:\n    - block is saved to IndexedDB\n    - queue length increases by 1\n    - no HTTP request is made\n```\n\n```mdl\ntest T-5: Blockstore queue flushes on reconnect\n  given: blocks are queued while offline\n  when: the browser comes back online\n  then:\n    - a CAR archive containing all queued blocks is POSTed to the edge service\n    - the queue is cleared\n```\n\n```mdl\ntest T-6: New space initializes WNFS directory\n  given: a space with no WNFS properties\n  when: loadWnfs is called for that space\n  then:\n    - a new PrivateForest and PrivateDirectory are created\n    - space.properties.wnfs.privateForestCid is populated\n```\n\n```mdl\ntest T-7: WnfsInstance cache hit\n  given: a WnfsInstance is cached for the current forest CID\n  when: loadWnfs is called again for the same space\n  then: the cached instance is returned; no blockstore reads occur\n```\n\n---\n\n## Appendix: Extension Definitions\n\nExtension block types used in this document are defined below using\nthe core `ext` primitive \u2014 the only construct the base language provides.\n\n```mdl\next type\n  uri: org.dxos.mdl.type@1.0\n  desc: A named data structure with typed fields and optional literals.\n  fields:\n    desc?: Prose\n    fields?: FieldMap        # name[?]: TypeExpr  (# inline comment)\n    literals?: UnionList     # a | b | c\n    extends?: TypeRef[]\n```\n\n```mdl\next feat\n  uri: org.dxos.mdl.feat@1.0\n  desc: A named feature grouping one or more requirements.\n  fields:\n    desc?: Prose\n    req: RequirementList\n  nesting: self              # feat blocks may contain feat blocks\n```\n\n```mdl\next test\n  uri: org.dxos.mdl.test@1.0\n  desc: An acceptance scenario expressed as given / when / then steps.\n  fields:\n    given?: Step | Step[]\n    when?: Step | Step[]\n    then: Step | Step[]\n    tags?: TagList\n```\n\n```mdl\next component\n  uri: org.dxos.mdl.component@1.0\n  desc: A UI component with props, internal state, slots, actions, and events.\n  fields:\n    desc?: Prose\n    props?: FieldMap            # external inputs (immutable inside component)\n    state?: FieldMap            # internal reactive state\n    slots?: FieldMap            # named ReactNode injection points\n    actions?: ActionMap         # methods the component exposes or handles\n    emits?: EventMap            # events the component raises to its parent\n    layout?: CodeBlock          # ASCII sketch of visual structure (non-normative)\n```\n\n```mdl\next op\n  uri: org.dxos.mdl.op@1.0\n  desc: |\n    A named operation with typed inputs, outputs, and declared errors.\n    Pure ops have no effects or requires. Effectful ops declare both.\n  fields:\n    desc?: Prose\n    input?: FieldMap            # named input parameters\n    output?: TypeExpr           # return type\n    errors?: ErrorMap           # name: Prose  (when this error occurs)\n    effects?: EffectList        # echo:read | echo:write | http | fs | ...\n    requires?: ServiceList      # injected service dependencies\n    note?: Prose                # implementation guidance (non-normative)\n```\n";
-
-// src/WnfsPlugin.tsx
-var WnfsPlugin = Plugin.define(meta).pipe(AppPlugin.addTranslationsModule({
-  translations
-}), Plugin.addModule({
-  id: "blockstore",
-  activatesOn: ClientEvents.ClientReady,
-  activate: Blockstore
-}), Plugin.addModule({
-  id: "instances",
-  activatesOn: ClientEvents.ClientReady,
-  activate: () => Effect.sync(() => {
-    const instances = {};
-    return Capability.contributes(WnfsCapabilities.Instances, instances);
-  })
-}), Plugin.addModule({
-  id: "backend",
-  activatesOn: ClientEvents.ClientReady,
-  activate: Backend
-}), Plugin.addModule({
-  id: "url-resolver",
-  activatesOn: ClientEvents.ClientReady,
-  activate: UrlResolver
-}), AppPlugin.addPluginAssetModule({
-  asset: {
-    pluginId: meta.profile.key,
-    path: "PLUGIN.mdl",
-    content: PLUGIN_default,
-    mimeType: "application/x-mdl"
-  }
-}), Plugin.make);
-var WnfsPlugin_default = WnfsPlugin;
-export {
-  WnfsPlugin,
-  WnfsPlugin_default as default
-};
-//# sourceMappingURL=WnfsPlugin.mjs.map

package/dist/lib/neutral/WnfsPlugin.mjs.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../src/WnfsPlugin.tsx", "raw-loader:/__w/dxos/dxos/packages/plugins/plugin-wnfs/PLUGIN.mdl"],
-  "sourcesContent": ["//\n// Copyright 2024 DXOS.org\n//\n\nimport * as Effect from 'effect/Effect';\n\nimport { Capability, Plugin } from '@dxos/app-framework';\nimport { AppPlugin } from '@dxos/app-toolkit';\nimport { ClientEvents } from '@dxos/plugin-client';\n\nimport { Backend, Blockstore, UrlResolver } from '#capabilities';\nimport { meta } from '#meta';\nimport { translations } from '#translations';\nimport { WnfsCapabilities } from '#types';\n\n// eslint-disable-next-line import/no-relative-packages\nimport pluginSpec from '../PLUGIN.mdl?raw';\n\nexport const WnfsPlugin = Plugin.define(meta).pipe(\n  AppPlugin.addTranslationsModule({ translations }),\n  Plugin.addModule({\n    id: 'blockstore',\n    activatesOn: ClientEvents.ClientReady,\n    activate: Blockstore,\n  }),\n  Plugin.addModule({\n    id: 'instances',\n    activatesOn: ClientEvents.ClientReady,\n    activate: () =>\n      Effect.sync(() => {\n        const instances: WnfsCapabilities.Instances = {};\n        return Capability.contributes(WnfsCapabilities.Instances, instances);\n      }),\n  }),\n  Plugin.addModule({\n    id: 'backend',\n    activatesOn: ClientEvents.ClientReady,\n    activate: Backend,\n  }),\n  Plugin.addModule({\n    id: 'url-resolver',\n    activatesOn: ClientEvents.ClientReady,\n    activate: UrlResolver,\n  }),\n  AppPlugin.addPluginAssetModule({\n    asset: { pluginId: meta.profile.key, path: 'PLUGIN.mdl', content: pluginSpec, mimeType: 'application/x-mdl' },\n  }),\n  Plugin.make,\n);\n\nexport default WnfsPlugin;\n", "---\nid: org.dxos.plugin.wnfs\nname: WnfsPlugin\nversion: 0.1.0\n---\n\nA decentralized file storage plugin for `DXOS` Composer built on the Web Native File System (WNFS) protocol.\n\nWNFS provides a content-addressed, end-to-end encrypted private file system using a cryptographic \"dark forest\"\nstructure. Files are stored as IPLD blocks referenced by CID, replicated to a DXOS edge blob service, and\ncached locally in IndexedDB. The plugin implements the `FileCapabilities.Backend` and `FileCapabilities.UrlResolver`\ninterfaces from `plugin-file`, so other plugins (e.g. `plugin-gallery`) can upload and resolve `wnfs://` URLs\nwithout knowing the underlying storage layer. Uploads are scoped to a DXOS Space; the private forest root CID\nis persisted on the space's ECHO properties and updated atomically on every write.\n\n## Extensions\n\nThe following extension dialects are used in this document.\nEach extension is defined in the Appendix or resolved via its URI.\n\n| Term        | URI                            |\n|-------------|--------------------------------|\n| `type`      | `org.dxos.mdl.type@1.0`       |\n| `feat`      | `org.dxos.mdl.feat@1.0`       |\n| `test`      | `org.dxos.mdl.test@1.0`       |\n| `component` | `org.dxos.mdl.component@1.0`  |\n| `op`        | `org.dxos.mdl.op@1.0`         |\n\n## Types\n\n```mdl\ntype Cid\n  desc: A content-addressed identifier encoded as a base-32 multibase string (CIDv1, sha2-256).\n  fields:\n    value: string\n```\n\n```mdl\ntype WnfsPath\n  desc: A WNFS path encoded as a wnfs:// URL; segments are percent-encoded.\n  fields:\n    url: string               # wnfs://spaces/<spaceId>/files/<cid>\n```\n\n```mdl\ntype FileInfo\n  desc: Metadata returned after a successful upload.\n  fields:\n    name: string              # Original file name\n    type: string              # MIME type\n    url: WnfsPath             # wnfs:// URL for later retrieval\n    cid: Cid                  # Raw content CID of the file bytes\n```\n\n```mdl\ntype BlockstoreState\n  desc: Runtime state of the MixedBlockstore.\n  fields:\n    isConnected: boolean      # Online / offline status\n    queueLength: number       # Blocks pending remote flush\n    apiHost: string           # DXOS edge service base URL\n```\n\n```mdl\ntype WnfsInstances\n  desc: In-memory cache mapping forest CID \u2192 loaded PrivateDirectory/PrivateForest pair.\n  fields:\n    entries: Record<string, WnfsInstance>\n```\n\n```mdl\ntype WnfsInstance\n  desc: A loaded WNFS private file system rooted at a specific forest CID.\n  fields:\n    directory: PrivateDirectory\n    forest: PrivateForest\n```\n```\n\n## Operations\n\nPure operations \u2014 no external effects.\n\n```mdl\nop wnfsUrl\n  desc: Encodes a WNFS path array into a wnfs:// URL with percent-encoded segments.\n  input:\n    filePath: string[]\n  output: string\n```\n\n```mdl\nop getPathFromUrl\n  desc: Decodes a wnfs:// URL back into a path segment array.\n  input:\n    wnfsUrl: string\n  output: string[]\n```\n\nEffectful operations \u2014 read or write persistent state.\n\n```mdl\nop uploadFile\n  desc: |\n    Reads a File, writes its bytes into the WNFS private directory at a\n    CID-derived path, persists the updated forest pointer to the space's\n    ECHO properties, and returns FileInfo.\n  input:\n    file: File\n    space: Space\n  output: FileInfo\n  effects: [fs:read, echo:write, http:post]\n  errors:\n    SpaceNotFound: no space matching the given spaceId\n    BlockstoreError: local or remote block I/O failure\n  note: |\n    Uses sha256 for block hashing (not the rs-wnfs default Blake3) for\n    broader runtime support. Writes are atomic from ECHO's perspective:\n    the forest CID property is only updated after the forest is stored.\n```\n\n```mdl\nop resolveWnfsUrl\n  desc: |\n    Reads file bytes from the WNFS private directory for a wnfs:// URL,\n    wraps them in a Blob, and returns an object URL for in-browser display.\n  input:\n    wnfsUrl: string\n    space: Space\n    type?: string             # MIME type hint for Blob construction\n  output: string              # blob: object URL\n  effects: [fs:read, http:get]\n  errors:\n    UrlNotResolvable: space not available or file not found in directory\n  note: Errors are swallowed and undefined is returned to avoid breaking image renders.\n```\n\n```mdl\nop flushBlockQueue\n  desc: |\n    Drains the pending-upload queue by assembling a CAR archive and POSTing\n    it to the edge blob service. Called automatically (debounced 5 s) on\n    block writes and on the browser `online` event.\n  input:\n    blockstore: Blockstore\n  output: void\n  effects: [http:post]\n  errors:\n    NetworkError: remote POST failed\n  note: Queue is persisted to IndexedDB so pending blocks survive page reloads.\n```\n\n## Features\n\n```mdl\nfeat F-1: Upload File\n\n  req F-1.1:\n    when: a FileCapabilities.Backend consumer calls upload(file, db)\n    then: the file is read, hashed, written to the WNFS private directory,\n          and stored in the blockstore\n\n  req F-1.2:\n    when: the write succeeds\n    then: the space's ECHO properties are updated with the new privateForestCid\n\n  req F-1.3:\n    when: the upload completes\n    then: a FileInfo object with name, type, size, and wnfs:// URL is returned to the caller\n```\n\n```mdl\nfeat F-2: Resolve wnfs:// URL\n\n  req F-2.1:\n    when: FileCapabilities.UrlResolver.test(url) is called with a wnfs:// URL\n    then: returns true\n\n  req F-2.2:\n    when: FileCapabilities.UrlResolver.resolve(url, file, space) is called\n    then: loads or reuses a cached WnfsInstance for the space and reads the file bytes\n\n  req F-2.3:\n    when: bytes are successfully read\n    then: a blob: object URL is returned for in-browser display\n\n  req F-2.4:\n    when: the space is undefined or reading fails\n    then: undefined is returned; no error is propagated\n```\n\n```mdl\nfeat F-3: Blockstore Sync\n\n  req F-3.1:\n    when: a block is written via blockstore.put\n    then: the block is saved to IndexedDB and added to the upload queue\n\n  req F-3.2:\n    when: the browser is online and the queue is non-empty\n    then: blocks are batched into a CAR archive and flushed to the edge service\n\n  req F-3.3:\n    when: the browser goes offline\n    then: the queue is persisted to IndexedDB; no upload is attempted\n\n  req F-3.4:\n    when: the browser comes back online\n    then: the flush is triggered automatically\n\n  req F-3.5:\n    when: a block is requested via blockstore.get and is present in IndexedDB\n    then: the block is returned from the local cache without a network request\n\n  req F-3.6:\n    when: a block is not in IndexedDB and the browser is online\n    then: the block is fetched from the edge service and cached locally\n```\n\n```mdl\nfeat F-4: Space-Scoped Private File System\n\n  req F-4.1:\n    when: a space has no existing WNFS properties\n    then: a new PrivateForest and PrivateDirectory are created and stored\n\n  req F-4.2:\n    when: a space already has a privateForestCid\n    then: the existing forest and directory are loaded from the blockstore\n\n  req F-4.3:\n    when: a WnfsInstance is already cached for the current forest CID\n    then: the cached instance is reused without reloading from the blockstore\n\n  req F-4.4:\n    when: legacy snake_case WNFS properties are found on a space\n    then: they are deleted and replaced with the current camelCase schema\n    tags: [migration]\n```\n\n## Acceptance\n\n```mdl\ntest T-1: Upload creates FileInfo\n  given: an active space and a registered WNFS backend\n  when: a file is uploaded via the Backend capability\n  then:\n    - FileInfo.url starts with wnfs://\n    - space.properties.wnfs.privateForestCid is set\n    - block for the file is present in the local IndexedDB blockstore\n```\n\n```mdl\ntest T-2: Resolve uploaded file\n  given: a file was previously uploaded and FileInfo.url is known\n  when: UrlResolver.resolve(url, file, space) is called\n  then:\n    - a blob: object URL is returned\n    - URL can be used as an img src\n```\n\n```mdl\ntest T-3: Resolve without space returns undefined\n  given: a wnfs:// URL\n  when: UrlResolver.resolve is called with space = undefined\n  then: undefined is returned; no error is thrown\n```\n\n```mdl\ntest T-4: Blockstore offline queuing\n  given: the browser is offline\n  when: a block is written to the blockstore\n  then:\n    - block is saved to IndexedDB\n    - queue length increases by 1\n    - no HTTP request is made\n```\n\n```mdl\ntest T-5: Blockstore queue flushes on reconnect\n  given: blocks are queued while offline\n  when: the browser comes back online\n  then:\n    - a CAR archive containing all queued blocks is POSTed to the edge service\n    - the queue is cleared\n```\n\n```mdl\ntest T-6: New space initializes WNFS directory\n  given: a space with no WNFS properties\n  when: loadWnfs is called for that space\n  then:\n    - a new PrivateForest and PrivateDirectory are created\n    - space.properties.wnfs.privateForestCid is populated\n```\n\n```mdl\ntest T-7: WnfsInstance cache hit\n  given: a WnfsInstance is cached for the current forest CID\n  when: loadWnfs is called again for the same space\n  then: the cached instance is returned; no blockstore reads occur\n```\n\n---\n\n## Appendix: Extension Definitions\n\nExtension block types used in this document are defined below using\nthe core `ext` primitive \u2014 the only construct the base language provides.\n\n```mdl\next type\n  uri: org.dxos.mdl.type@1.0\n  desc: A named data structure with typed fields and optional literals.\n  fields:\n    desc?: Prose\n    fields?: FieldMap        # name[?]: TypeExpr  (# inline comment)\n    literals?: UnionList     # a | b | c\n    extends?: TypeRef[]\n```\n\n```mdl\next feat\n  uri: org.dxos.mdl.feat@1.0\n  desc: A named feature grouping one or more requirements.\n  fields:\n    desc?: Prose\n    req: RequirementList\n  nesting: self              # feat blocks may contain feat blocks\n```\n\n```mdl\next test\n  uri: org.dxos.mdl.test@1.0\n  desc: An acceptance scenario expressed as given / when / then steps.\n  fields:\n    given?: Step | Step[]\n    when?: Step | Step[]\n    then: Step | Step[]\n    tags?: TagList\n```\n\n```mdl\next component\n  uri: org.dxos.mdl.component@1.0\n  desc: A UI component with props, internal state, slots, actions, and events.\n  fields:\n    desc?: Prose\n    props?: FieldMap            # external inputs (immutable inside component)\n    state?: FieldMap            # internal reactive state\n    slots?: FieldMap            # named ReactNode injection points\n    actions?: ActionMap         # methods the component exposes or handles\n    emits?: EventMap            # events the component raises to its parent\n    layout?: CodeBlock          # ASCII sketch of visual structure (non-normative)\n```\n\n```mdl\next op\n  uri: org.dxos.mdl.op@1.0\n  desc: |\n    A named operation with typed inputs, outputs, and declared errors.\n    Pure ops have no effects or requires. Effectful ops declare both.\n  fields:\n    desc?: Prose\n    input?: FieldMap            # named input parameters\n    output?: TypeExpr           # return type\n    errors?: ErrorMap           # name: Prose  (when this error occurs)\n    effects?: EffectList        # echo:read | echo:write | http | fs | ...\n    requires?: ServiceList      # injected service dependencies\n    note?: Prose                # implementation guidance (non-normative)\n```\n"],
-  "mappings": ";;;AAIA,YAAYA,YAAY;AAExB,SAASC,YAAYC,cAAc;AACnC,SAASC,iBAAiB;AAC1B,SAASC,oBAAoB;AAE7B,SAASC,SAASC,YAAYC,mBAAmB;AACjD,SAASC,YAAY;AACrB,SAASC,oBAAoB;AAC7B,SAASC,wBAAwB;;;ACbjC;;;ADkBO,IAAMC,aAAaC,OAAOC,OAAOC,IAAAA,EAAMC,KAC5CC,UAAUC,sBAAsB;EAAEC;AAAa,CAAA,GAC/CN,OAAOO,UAAU;EACfC,IAAI;EACJC,aAAaC,aAAaC;EAC1BC,UAAUC;AACZ,CAAA,GACAb,OAAOO,UAAU;EACfC,IAAI;EACJC,aAAaC,aAAaC;EAC1BC,UAAU,MACDE,YAAK,MAAA;AACV,UAAMC,YAAwC,CAAC;AAC/C,WAAOC,WAAWC,YAAYC,iBAAiBC,WAAWJ,SAAAA;EAC5D,CAAA;AACJ,CAAA,GACAf,OAAOO,UAAU;EACfC,IAAI;EACJC,aAAaC,aAAaC;EAC1BC,UAAUQ;AACZ,CAAA,GACApB,OAAOO,UAAU;EACfC,IAAI;EACJC,aAAaC,aAAaC;EAC1BC,UAAUS;AACZ,CAAA,GACAjB,UAAUkB,qBAAqB;EAC7BC,OAAO;IAAEC,UAAUtB,KAAKuB,QAAQC;IAAKC,MAAM;IAAcC,SAASC;IAAYC,UAAU;EAAoB;AAC9G,CAAA,GACA9B,OAAO+B,IAAI;AAGb,IAAA,qBAAehC;",
-  "names": ["Effect", "Capability", "Plugin", "AppPlugin", "ClientEvents", "Backend", "Blockstore", "UrlResolver", "meta", "translations", "WnfsCapabilities", "WnfsPlugin", "Plugin", "define", "meta", "pipe", "AppPlugin", "addTranslationsModule", "translations", "addModule", "id", "activatesOn", "ClientEvents", "ClientReady", "activate", "Blockstore", "sync", "instances", "Capability", "contributes", "WnfsCapabilities", "Instances", "Backend", "UrlResolver", "addPluginAssetModule", "asset", "pluginId", "profile", "key", "path", "content", "pluginSpec", "mimeType", "make"]
-}