@dxos/plugin-file 0.0.0

package/dx.config.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Config2 } from '@dxos/app-framework/config';
+import { trim } from '@dxos/util';
+
+export default Config2.make({
+  plugin: {
+    key: 'org.dxos.plugin.file',
+    name: 'File',
+    author: 'DXOS',
+    description: trim`
+      FilePlugin enables DXOS Composer to store and preview binary files — images, videos, and PDFs — as
+      first-class ECHO objects. Uploaded bytes are routed through a pluggable backend system: the built-in
+      inline backend serialises the file directly onto the ECHO document, while external backends (e.g. WNFS)
+      can be contributed by other plugins.
+
+      Accepted formats are images (jpg, jpeg, png, gif, webp, svg), videos (mp4, webm, mov), and PDFs,
+      up to a 4 MB limit per file for the inline backend. The preview surface renders the appropriate HTML
+      element for each MIME class and surfaces inside article, section, and slide roles.
+
+      A UrlResolver capability lets external-storage backends convert opaque storage URIs into renderable
+      blob, data, or HTTP URLs at view time, keeping the ECHO object schema backend-agnostic. A companion
+      Markdown extension allows file objects to be embedded directly in Markdown documents.
+
+      Backend selection is user-configurable in the plugin settings panel, which lists all registered
+      backends with their descriptions. Selecting a backend persists the choice to the ECHO-backed settings
+      atom so the preference is shared across devices.
+    `,
+    icon: { key: 'ph--file--regular', hue: 'teal' },
+    source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/plugin-file',
+    spec: 'PLUGIN.mdl',
+  },
+});

package/package.json

@@ -0,0 +1,139 @@
+{
+  "name": "@dxos/plugin-file",
+  "version": "0.0.0",
+  "description": "Inline file (image / PDF) storage plugin for DXOS",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
+  "license": "FSL-1.1-Apache-2.0",
+  "author": "DXOS.org",
+  "sideEffects": true,
+  "type": "module",
+  "imports": {
+    "#skills": {
+      "source": "./src/skills/index.ts",
+      "types": "./dist/types/src/skills/index.d.ts",
+      "default": "./dist/lib/neutral/skills/index.mjs"
+    },
+    "#capabilities": {
+      "source": "./src/capabilities/index.ts",
+      "types": "./dist/types/src/capabilities/index.d.ts",
+      "default": "./dist/lib/neutral/capabilities/index.mjs"
+    },
+    "#components": {
+      "source": "./src/components/index.ts",
+      "types": "./dist/types/src/components/index.d.ts",
+      "default": "./dist/lib/neutral/components/index.mjs"
+    },
+    "#containers": {
+      "source": "./src/containers/index.ts",
+      "types": "./dist/types/src/containers/index.d.ts",
+      "default": "./dist/lib/neutral/containers/index.mjs"
+    },
+    "#meta": {
+      "source": "./src/meta.ts",
+      "types": "./dist/types/src/meta.d.ts",
+      "default": "./dist/lib/neutral/meta.mjs"
+    },
+    "#operations": {
+      "source": "./src/operations/index.ts",
+      "types": "./dist/types/src/operations/index.d.ts",
+      "default": "./dist/lib/neutral/operations/index.mjs"
+    },
+    "#plugin": {
+      "source": {
+        "node": "./src/FilePlugin.node.ts",
+        "default": "./src/FilePlugin.tsx"
+      },
+      "types": "./dist/types/src/FilePlugin.d.ts",
+      "node": "./dist/lib/neutral/FilePlugin.node.mjs",
+      "default": "./dist/lib/neutral/FilePlugin.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",
+      "types": "./dist/types/src/index.d.ts",
+      "default": "./dist/lib/neutral/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"
+    },
+    "./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"
+    }
+  },
+  "types": "dist/types/src/index.d.ts",
+  "files": [
+    "dist",
+    "dx.config.ts",
+    "src",
+    "PLUGIN.mdl"
+  ],
+  "dependencies": {
+    "@codemirror/language": "catalog:",
+    "@codemirror/state": "catalog:",
+    "@codemirror/view": "catalog:",
+    "@dxos/app-framework": "workspace:*",
+    "@dxos/app-toolkit": "workspace:*",
+    "@dxos/compute": "workspace:*",
+    "@dxos/echo": "workspace:*",
+    "@dxos/effect": "workspace:*",
+    "@dxos/keys": "workspace:*",
+    "@dxos/plugin-client": "workspace:*",
+    "@dxos/plugin-markdown": "workspace:*",
+    "@dxos/plugin-space": "workspace:*",
+    "@dxos/react-client": "workspace:*",
+    "@dxos/react-ui": "workspace:*",
+    "@dxos/react-ui-form": "workspace:*",
+    "@dxos/types": "workspace:*",
+    "@dxos/ui-editor": "workspace:*",
+    "@dxos/util": "workspace:*",
+    "@effect-atom/atom-react": "catalog:",
+    "effect": "catalog:",
+    "react-dropzone": "catalog:"
+  },
+  "devDependencies": {
+    "@dxos/plugin-testing": "workspace:*",
+    "@dxos/storybook-utils": "workspace:*",
+    "@dxos/ui-theme": "workspace:*",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
+    "react": "catalog:",
+    "react-dom": "catalog:",
+    "vite": "catalog:"
+  },
+  "peerDependencies": {
+    "@dxos/react-ui": "workspace:*",
+    "@dxos/ui-theme": "workspace:*",
+    "effect": "catalog:",
+    "react": "catalog:",
+    "react-dom": "catalog:"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/FilePlugin.node.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+import { AppPlugin } from '@dxos/app-toolkit';
+
+import { CreateObject, OperationHandler } from '#capabilities';
+import { meta } from '#meta';
+import { File } from '#types';
+
+export const FilePlugin = Plugin.define(meta).pipe(
+  AppPlugin.addCreateObjectModule({ activate: CreateObject }),
+  AppPlugin.addOperationHandlerModule({ activate: OperationHandler }),
+  AppPlugin.addSchemaModule({ schema: [File.File] }),
+  Plugin.make,
+);
+
+export default FilePlugin;

package/src/FilePlugin.test.ts

@@ -0,0 +1,26 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { ClientPlugin } from '@dxos/plugin-client/plugin';
+import { createComposerTestApp } from '@dxos/plugin-testing/harness';
+
+import { FilePlugin } from '#plugin';
+
+import { meta } from './meta';
+
+const moduleId = (name: string) => `${meta.profile.key}.module.${name}`;
+
+describe('FilePlugin', () => {
+  test('modules activate on the expected events', async ({ expect }) => {
+    await using harness = await createComposerTestApp({
+      plugins: [ClientPlugin({}), FilePlugin()],
+    });
+
+    expect(harness.manager.getActive()).toEqual(
+      expect.arrayContaining([moduleId('CreateObject'), moduleId('schema'), moduleId('OperationHandler')]),
+    );
+  });
+});

package/src/FilePlugin.tsx

@@ -0,0 +1,56 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+import { AppActivationEvents, AppPlugin } from '@dxos/app-toolkit';
+import { ClientEvents } from '@dxos/plugin-client';
+import { MarkdownEvents } from '@dxos/plugin-markdown';
+
+import {
+  CreateObject,
+  FileUploader,
+  InlineBackend,
+  Markdown,
+  OperationHandler,
+  ReactSurface,
+  Settings,
+  SkillDefinition,
+} from '#capabilities';
+import { meta } from '#meta';
+import { translations } from '#translations';
+import { File } from '#types';
+
+// eslint-disable-next-line import/no-relative-packages
+import pluginSpec from '../PLUGIN.mdl?raw';
+
+export const FilePlugin = Plugin.define(meta).pipe(
+  AppPlugin.addSkillDefinitionModule({ activate: SkillDefinition }),
+  AppPlugin.addCreateObjectModule({ activate: CreateObject }),
+  AppPlugin.addOperationHandlerModule({ activate: OperationHandler }),
+  AppPlugin.addSchemaModule({ schema: [File.File] }),
+  AppPlugin.addSettingsModule({ activate: Settings }),
+  AppPlugin.addSurfaceModule({ activate: ReactSurface }),
+  AppPlugin.addTranslationsModule({ translations }),
+  Plugin.addModule({
+    id: 'inline-backend',
+    activatesOn: AppActivationEvents.SetupSchema,
+    activate: InlineBackend,
+  }),
+  Plugin.addModule({
+    id: 'file-uploader',
+    activatesOn: ClientEvents.ClientReady,
+    activate: FileUploader,
+  }),
+  Plugin.addModule({
+    id: 'markdown',
+    activatesOn: MarkdownEvents.SetupExtensions,
+    activate: Markdown,
+  }),
+  AppPlugin.addPluginAssetModule({
+    asset: { pluginId: meta.profile.key, path: 'PLUGIN.mdl', content: pluginSpec, mimeType: 'application/x-mdl' },
+  }),
+  Plugin.make,
+);
+
+export default FilePlugin;

package/src/capabilities/create-object.ts

@@ -0,0 +1,30 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
+import { Type } from '@dxos/echo';
+import { SpaceCapabilities, SpaceOperation } from '@dxos/plugin-space';
+
+import { File, FileAction, FileOperation } from '#types';
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    return Capability.contributes(SpaceCapabilities.CreateObjectEntry, {
+      id: Type.getTypename(File.File),
+      inputSchema: FileAction.CreateFileSchema,
+      createObject: (props, options) =>
+        Effect.gen(function* () {
+          const { object } = yield* Operation.invoke(FileOperation.Create, { ...props, db: options.db });
+          return yield* Operation.invoke(SpaceOperation.AddObject, {
+            object,
+            target: options.target,
+            targetNodeId: options.targetNodeId,
+          });
+        }),
+    });
+  }),
+);

package/src/capabilities/file-uploader.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { AppCapabilities } from '@dxos/app-toolkit';
+import { EffectEx } from '@dxos/effect';
+import { SpaceOperation } from '@dxos/plugin-space';
+
+import { FileOperation } from '#types';
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const capabilities = yield* Capability.Service;
+
+    return Capability.contributes(AppCapabilities.FileUploader, (db, file) => {
+      const { invoke } = capabilities.get(Capabilities.OperationInvoker);
+      const program = Effect.gen(function* () {
+        const { object } = yield* invoke(FileOperation.Create, { db, file });
+        yield* invoke(SpaceOperation.AddObject, { target: db, object });
+        const external = object.data._tag === 'external' ? object.data : undefined;
+        return {
+          name: object.name ?? file.name,
+          type: object.type,
+          ...(external?.url ? { url: external.url } : {}),
+          ...(external?.cid ? { cid: external.cid } : {}),
+        };
+      });
+
+      return EffectEx.runAndForwardErrors(program);
+    });
+  }),
+);

package/src/capabilities/index.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Capability } from '@dxos/app-framework';
+import { OperationHandlerSet } from '@dxos/compute';
+
+export const SkillDefinition = Capability.lazy('SkillDefinition', () => import('./skill-definition'));
+export const CreateObject = Capability.lazy('CreateObject', () => import('./create-object'));
+export const FileUploader = Capability.lazy('FileUploader', () => import('./file-uploader'));
+export const InlineBackend = Capability.lazy('InlineBackend', () => import('./inline-backend'));
+export const Markdown = Capability.lazy('MarkdownExtension', () => import('./markdown-extension'));
+export const OperationHandler = Capability.lazy<OperationHandlerSet.OperationHandlerSet>(
+  'OperationHandler',
+  () => import('./operation-handler'),
+);
+export const ReactSurface = Capability.lazy('ReactSurface', () => import('./react-surface'));
+export const Settings = Capability.lazy('Settings', () => import('./settings'));

package/src/capabilities/inline-backend.ts

@@ -0,0 +1,41 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+
+import { File, FileCapabilities, MAX_FILE_SIZE, Settings, isAcceptedMimeType } from '#types';
+
+import { FileTooLargeError, UnsupportedFileTypeError } from '../operations/create';
+
+/**
+ * Inline backend: file bytes are stored on the ECHO object itself.
+ * Exported standalone for direct testing.
+ */
+export const inlineBackend: FileCapabilities.Backend = {
+  id: Settings.DEFAULT_BACKEND_ID,
+  name: 'Inline (ECHO)',
+  description: 'Store the file bytes directly inside the ECHO document. Capped at 4MB; images, videos, and PDFs only.',
+  upload: async (file) => {
+    if (!isAcceptedMimeType(file.type)) {
+      throw new UnsupportedFileTypeError(file.type);
+    }
+    // Check size before reading into memory to avoid allocating a large buffer.
+    if (file.size > MAX_FILE_SIZE) {
+      throw new FileTooLargeError(file.size);
+    }
+    const bytes = new Uint8Array(await file.arrayBuffer());
+    return {
+      name: file.name,
+      type: file.type,
+      size: bytes.byteLength,
+      data: File.inlineData(bytes),
+    };
+  },
+};
+
+export default Capability.makeModule(() =>
+  Effect.succeed(Capability.contributes(FileCapabilities.Backend, inlineBackend)),
+);

package/src/capabilities/markdown-extension.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { MarkdownCapabilities, type MarkdownExtensionProvider } from '@dxos/plugin-markdown/types';
+import { getSpace } from '@dxos/react-client/echo';
+
+import { FileCapabilities } from '#types';
+
+import { image } from '../extensions';
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const capabilities = yield* Capability.Service;
+
+    const provider: MarkdownExtensionProvider = ({ document, viewMode }) => {
+      if (viewMode === 'source') {
+        return undefined;
+      }
+
+      if (document) {
+        const space = getSpace(document);
+        if (!space) {
+          return undefined;
+        }
+        const resolvers = capabilities.getAll(FileCapabilities.UrlResolver);
+        return [image({ space, resolvers })];
+      }
+
+      return undefined;
+    };
+
+    return Capability.contributes(MarkdownCapabilities.ExtensionProvider, [provider]);
+  }),
+);

package/src/capabilities/operation-handler.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import type { OperationHandlerSet } from '@dxos/compute';
+
+import { FileOperationHandlerSet } from '#operations';
+
+export default Capability.makeModule<OperationHandlerSet.OperationHandlerSet>(
+  Effect.fnUntraced(function* () {
+    return Capability.contributes(Capabilities.OperationHandler, FileOperationHandlerSet);
+  }),
+);

package/src/capabilities/react-surface.tsx

@@ -0,0 +1,61 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import React, { useCallback } from 'react';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { Surface, useSettingsState } from '@dxos/app-framework/ui';
+import { AppSurface } from '@dxos/app-toolkit/ui';
+import { SchemaEx } from '@dxos/effect';
+import { type FormFieldRendererProps } from '@dxos/react-ui-form';
+
+import { FileInput } from '#components';
+import { FileArticle, FileSettings } from '#containers';
+import { meta } from '#meta';
+import { File, FileAction, type Settings } from '#types';
+
+export default Capability.makeModule(() =>
+  Effect.succeed(
+    Capability.contributes(Capabilities.ReactSurface, [
+      Surface.create({
+        id: 'article',
+        filter: AppSurface.oneOf(
+          AppSurface.object(AppSurface.Article, File.File),
+          AppSurface.object(AppSurface.Section, File.File),
+          AppSurface.object(AppSurface.Slide, File.File),
+        ),
+        component: ({ data, role }) => <FileArticle role={role} subject={data.subject} />,
+      }),
+      Surface.create({
+        id: 'createForm',
+        filter: AppSurface.formInputBySchema(
+          (ast) => !!SchemaEx.findAnnotation<Record<string, string[]>>(ast, FileAction.UploadAnnotationId),
+        ),
+        component: ({ data, ...props }) => {
+          const ast = data.fieldPropertyAst;
+          if (!ast) {
+            return null;
+          }
+
+          const inputProps = { ...props, type: ast } as unknown as FormFieldRendererProps;
+          const handleChange = useCallback(
+            (file: File) => inputProps.onValueChange?.(ast, file),
+            [ast, inputProps.onValueChange],
+          );
+
+          return <FileInput schema={data.schema} onChange={handleChange} />;
+        },
+      }),
+      Surface.create({
+        id: 'pluginSettings',
+        filter: AppSurface.settings(AppSurface.Article, meta.profile.key),
+        component: ({ data: { subject } }) => {
+          const { settings, updateSettings } = useSettingsState<Settings.Settings>(subject.atom);
+          return <FileSettings settings={settings} onSettingsChange={updateSettings} />;
+        },
+      }),
+    ]),
+  ),
+);

package/src/capabilities/settings.ts

@@ -0,0 +1,31 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { AppCapabilities } from '@dxos/app-toolkit';
+import { createKvsStore } from '@dxos/effect';
+
+import { meta } from '#meta';
+import { FileCapabilities, Settings } from '#types';
+
+export default Capability.makeModule(() =>
+  Effect.sync(() => {
+    const settingsAtom = createKvsStore({
+      key: meta.profile.key,
+      schema: Settings.Settings,
+      defaultValue: () => ({}),
+    });
+
+    return [
+      Capability.contributes(FileCapabilities.SettingsAtom, settingsAtom),
+      Capability.contributes(AppCapabilities.Settings, {
+        prefix: meta.profile.key,
+        schema: Settings.Settings,
+        atom: settingsAtom,
+      }),
+    ];
+  }),
+);

package/src/capabilities/skill-definition.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { AppCapabilities } from '@dxos/app-toolkit';
+
+import { FileSkill } from '#skills';
+
+const skillDefinition = () => Effect.succeed([Capability.contributes(AppCapabilities.SkillDefinition, FileSkill)]);
+
+export default skillDefinition;

package/src/components/FileInput/FileInput.tsx

@@ -0,0 +1,48 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import type * as Schema from 'effect/Schema';
+import React, { useCallback } from 'react';
+import { useDropzone } from 'react-dropzone';
+
+import { SchemaEx } from '@dxos/effect';
+import { useTranslation } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+
+import { meta } from '#meta';
+import { FileAction, MAX_FILE_SIZE } from '#types';
+
+export type FileInputProps = {
+  schema: Schema.Schema.AnyNoContext;
+  onChange: (file: File) => void;
+};
+
+export const FileInput = ({ schema, onChange }: FileInputProps) => {
+  const { t } = useTranslation(meta.profile.key);
+  const accept = SchemaEx.findAnnotation<Record<string, string[]>>(schema.ast, FileAction.UploadAnnotationId);
+
+  const onDropAccepted = useCallback((files: File[]) => onChange?.(files[0]), [onChange]);
+
+  const { acceptedFiles, getRootProps, getInputProps, isFocused, isDragAccept, isDragReject } = useDropzone({
+    multiple: false,
+    accept,
+    maxSize: MAX_FILE_SIZE,
+    onDropAccepted,
+  });
+
+  return (
+    <div
+      {...getRootProps()}
+      className={mx(
+        'flex flex-col items-center p-8 border border-separator',
+        isFocused && 'focus-ring',
+        isDragAccept && 'bg-attention-surface',
+        isDragReject && 'border-rose-bg',
+      )}
+    >
+      <input {...getInputProps()} />
+      {acceptedFiles[0] ? <p>{acceptedFiles[0].name}</p> : <p>{t('file-input.placeholder')}</p>}
+    </div>
+  );
+};

package/src/components/FileInput/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './FileInput';