@dxos/plugin-file 0.0.0

package/src/components/FilePreview/FilePreview.tsx

@@ -0,0 +1,55 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { ForwardedRef } from 'react';
+
+import { composable, composableProps } from '@dxos/react-ui';
+
+export type FilePreviewProps = { type: string; url: string };
+
+/**
+ * File/content preview — image, video, PDF (iframe), or fallback download link.
+ */
+export const FilePreview = composable<HTMLElement, FilePreviewProps>(
+  ({ type, url, children, ...props }, forwardedRef) => {
+    if (type.startsWith('image/')) {
+      return (
+        <img
+          {...composableProps(props, { classNames: 'h-full w-full object-contain' })}
+          src={url}
+          ref={forwardedRef as ForwardedRef<HTMLImageElement>}
+        />
+      );
+    } else if (type.startsWith('video/')) {
+      return (
+        <video
+          {...composableProps(props, { classNames: 'h-full w-full object-contain' })}
+          src={url}
+          controls
+          ref={forwardedRef as ForwardedRef<HTMLVideoElement>}
+        />
+      );
+    } else if (type === 'application/pdf') {
+      return (
+        <iframe
+          {...composableProps(props, { classNames: 'h-full w-full overflow-auto' })}
+          src={url}
+          title='PDF preview'
+          ref={forwardedRef as ForwardedRef<HTMLIFrameElement>}
+        />
+      );
+    } else {
+      return (
+        <a
+          {...composableProps(props, { classNames: 'p-4 underline' })}
+          href={url}
+          download
+          ref={forwardedRef as ForwardedRef<HTMLAnchorElement>}
+        >
+          Download file
+        </a>
+      );
+    }
+  },
+);

package/src/components/FilePreview/index.ts

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

package/src/components/index.ts

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

package/src/containers/FileArticle/FileArticle.tsx

@@ -0,0 +1,84 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { useEffect, useState } from 'react';
+
+import { useCapabilities } from '@dxos/app-framework/ui';
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { getSpace } from '@dxos/react-client/echo';
+import { Panel } from '@dxos/react-ui';
+
+import { FilePreview } from '#components';
+import { File, FileCapabilities } from '#types';
+
+export type FileArticleProps = AppSurface.ObjectArticleProps<File.File>;
+
+export const FileArticle = ({ role, subject: file }: FileArticleProps) => {
+  const resolvers = useCapabilities(FileCapabilities.UrlResolver);
+  const [renderUrl, setRenderUrl] = useState<string | undefined>(undefined);
+
+  useEffect(() => {
+    const { data } = file;
+    if (data._tag === 'inline') {
+      const url = URL.createObjectURL(new Blob([data.bytes as BlobPart], { type: file.type }));
+      setRenderUrl(url);
+      return () => URL.revokeObjectURL(url);
+    }
+
+    // External URL: pass through `http(s):`/`data:`/`blob:` directly; otherwise dispatch to a resolver.
+    let cancelled = false;
+    let createdBlobUrl: string | undefined;
+
+    if (/^(?:https?|data|blob):/i.test(data.url)) {
+      setRenderUrl(data.url);
+    } else {
+      const resolver = resolvers.find((r) => r.test(data.url));
+      if (!resolver) {
+        setRenderUrl(undefined);
+        return;
+      }
+      setRenderUrl(undefined);
+      void resolver
+        .resolve(data.url, file, getSpace(file))
+        .then((url) => {
+          if (cancelled) {
+            if (url?.startsWith('blob:')) {
+              URL.revokeObjectURL(url);
+            }
+            return;
+          }
+          if (url?.startsWith('blob:')) {
+            createdBlobUrl = url;
+          }
+          setRenderUrl(url);
+        })
+        .catch(() => {
+          if (!cancelled) {
+            setRenderUrl(undefined);
+          }
+        });
+    }
+
+    return () => {
+      cancelled = true;
+      if (createdBlobUrl) {
+        URL.revokeObjectURL(createdBlobUrl);
+      }
+    };
+  }, [file, file.data, file.type, resolvers]);
+
+  if (!renderUrl) {
+    return null;
+  }
+
+  return (
+    <Panel.Root role={role} className='dx-document'>
+      <Panel.Content asChild>
+        <FilePreview type={file.type} url={renderUrl} />
+      </Panel.Content>
+    </Panel.Root>
+  );
+};
+
+export default FileArticle;

package/src/containers/FileArticle/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { FileArticle as default } from './FileArticle';

package/src/containers/FileSettings/FileSettings.tsx

@@ -0,0 +1,67 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { useCallback } from 'react';
+
+import { useCapabilities } from '@dxos/app-framework/ui';
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { Select, useTranslation } from '@dxos/react-ui';
+import { Form } from '@dxos/react-ui-form';
+
+import { meta } from '#meta';
+import { FileCapabilities, Settings } from '#types';
+
+export type FileSettingsProps = AppSurface.SettingsProps<Settings.Settings>;
+
+export const FileSettings = ({ settings, onSettingsChange }: FileSettingsProps) => {
+  const { t } = useTranslation(meta.profile.key);
+  const backends = useCapabilities(FileCapabilities.Backend);
+  const requestedId = settings.backend ?? Settings.DEFAULT_BACKEND_ID;
+  const active =
+    backends.find((b) => b.id === requestedId) ?? backends.find((b) => b.id === Settings.DEFAULT_BACKEND_ID);
+  // Use the resolved backend id so the Select never shows a missing/stale value.
+  const activeId = active?.id ?? Settings.DEFAULT_BACKEND_ID;
+
+  const handleChange = useCallback(
+    (value: string) => onSettingsChange?.((current) => ({ ...current, backend: value })),
+    [onSettingsChange],
+  );
+
+  return (
+    <Form.Root
+      schema={Settings.Settings}
+      values={settings}
+      variant='settings'
+      readonly={!onSettingsChange}
+      onValuesChanged={(values) => onSettingsChange?.((current) => ({ ...current, ...values }))}
+    >
+      <Form.Viewport scroll>
+        <Form.Content>
+          <Form.Section title={meta.profile.name ?? meta.profile.key}>
+            <Form.Row
+              label={t('settings.backend.label')}
+              description={active?.description ?? t('settings.backend.description')}
+            >
+              <Select.Root value={activeId} onValueChange={handleChange} disabled={!onSettingsChange}>
+                <Select.TriggerButton placeholder={t('settings.backend.placeholder')} />
+                <Select.Portal>
+                  <Select.Content>
+                    <Select.Viewport>
+                      {backends.map((backend) => (
+                        <Select.Option key={backend.id} value={backend.id}>
+                          {backend.name}
+                        </Select.Option>
+                      ))}
+                    </Select.Viewport>
+                    <Select.Arrow />
+                  </Select.Content>
+                </Select.Portal>
+              </Select.Root>
+            </Form.Row>
+          </Form.Section>
+        </Form.Content>
+      </Form.Viewport>
+    </Form.Root>
+  );
+};

package/src/containers/FileSettings/index.ts

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

package/src/containers/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type ComponentType, lazy } from 'react';
+
+export const FileArticle: ComponentType<any> = lazy(() => import('./FileArticle'));
+
+export * from './FileSettings';

package/src/extensions/image.tsx

@@ -0,0 +1,232 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { syntaxTree } from '@codemirror/language';
+import { type EditorState, type Extension, type Range, StateField } from '@codemirror/state';
+import { Decoration, EditorView, WidgetType } from '@codemirror/view';
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+
+import { Filter, Obj } from '@dxos/echo';
+import { EID } from '@dxos/keys';
+import { type Space } from '@dxos/react-client/echo';
+import { Status, ThemeProvider } from '@dxos/react-ui';
+import { defaultTx } from '@dxos/react-ui';
+import { focusField } from '@dxos/ui-editor';
+import { type MaybePromise } from '@dxos/util';
+
+import { File, FileCapabilities } from '#types';
+
+const WAIT_UNTIL_LOADER = 1500;
+
+export type ImageOptions = {
+  space: Space;
+  resolvers: readonly FileCapabilities.UrlResolver[];
+};
+
+/**
+ * Decorate `![](echo:...)` references that resolve to File objects with inline image previews.
+ */
+export const image = (options: ImageOptions): Extension[] => {
+  const blobUrlCache: Record<string, string> = {};
+  const preloaded = new Set<string>();
+
+  const preload = (url: string) => {
+    if (!preloaded.has(url)) {
+      const img = document.createElement('img');
+      img.src = url;
+      preloaded.add(url);
+    }
+  };
+
+  return [
+    StateField.define({
+      create: (state) =>
+        Decoration.set(buildDecorations({ from: 0, to: state.doc.length, state, blobUrlCache, preload, options })),
+      update: (value, tr) => {
+        if (!tr.docChanged && !tr.selection) {
+          return value;
+        }
+
+        const cursor = tr.state.selection.main.head;
+        const oldCursor = tr.changes.mapPos(tr.startState.selection.main.head);
+        let from = Math.min(cursor, oldCursor);
+        let to = Math.max(cursor, oldCursor);
+        tr.changes.iterChangedRanges((_fromA, _toA, fromB, toB) => {
+          from = Math.min(from, fromB);
+          to = Math.max(to, toB);
+        });
+
+        from = tr.state.doc.lineAt(from).from;
+        to = tr.state.doc.lineAt(to).to;
+
+        return value.map(tr.changes).update({
+          filterFrom: from,
+          filterTo: to,
+          filter: () => false,
+          add: buildDecorations({ from, to, state: tr.state, blobUrlCache, preload, options }),
+        });
+      },
+      provide: (field) => EditorView.decorations.from(field),
+    }),
+  ];
+};
+
+const buildDecorations = ({
+  state,
+  from,
+  to,
+  blobUrlCache,
+  preload,
+  options: { space, resolvers },
+}: {
+  state: EditorState;
+  from: number;
+  to: number;
+  blobUrlCache: Record<string, string>;
+  preload: (url: string) => void;
+  options: ImageOptions;
+}) => {
+  const decorations: Range<Decoration>[] = [];
+  const cursor = state.selection.main.head;
+  syntaxTree(state).iterate({
+    enter: (node) => {
+      if (node.name !== 'Image') {
+        return;
+      }
+
+      const urlNode = node.node.getChild('URL');
+      if (!urlNode) {
+        return;
+      }
+
+      const hide = state.readOnly || cursor < node.from || cursor > node.to;
+      const urlText = state.sliceDoc(urlNode.from, urlNode.to);
+      if (!EID.isEID(urlText)) {
+        return;
+      }
+
+      let echoUri: string | undefined;
+      let echoSpaceId: string | undefined;
+      try {
+        const parsed = EID.parse(urlText);
+        echoUri = EID.getEntityId(parsed);
+        echoSpaceId = EID.getSpaceId(parsed);
+      } catch {
+        return;
+      }
+      if (!echoUri) {
+        return;
+      }
+
+      // Skip references to objects in other spaces.
+      if (echoSpaceId && echoSpaceId !== space.id) {
+        return;
+      }
+
+      const cacheKey = urlText;
+      const blobUrlPromise = (async () => {
+        const matched = await space.db.query(Filter.id(echoUri!)).first();
+        if (!matched || !Obj.instanceOf(File.File, matched)) {
+          return undefined;
+        }
+
+        let url: string | undefined;
+        const { data } = matched;
+        if (data._tag === 'inline') {
+          url = URL.createObjectURL(new Blob([data.bytes as BlobPart], { type: matched.type }));
+        } else if (/^(?:https?|data|blob):/i.test(data.url)) {
+          url = data.url;
+        } else {
+          const resolver = resolvers.find((r) => r.test(data.url));
+          url = await resolver?.resolve(data.url, matched, space);
+        }
+        if (!url) {
+          return undefined;
+        }
+        blobUrlCache[cacheKey] = url;
+        preload(url);
+        return url;
+      })();
+
+      decorations.push(
+        Decoration.replace({
+          block: true,
+          widget: new DxnImageWidget(urlText, blobUrlCache[cacheKey] ?? blobUrlPromise),
+        }).range(hide ? node.from : node.to, node.to),
+      );
+    },
+    from,
+    to,
+  });
+
+  return decorations;
+};
+
+const createImg = (view: EditorView, url: string) => {
+  const img = document.createElement('img');
+  img.setAttribute('src', url);
+  img.setAttribute('class', 'cm-image-with-loader');
+  if (view.state.field(focusField)) {
+    img.onload = () => img.classList.add('cm-loaded-image');
+  } else {
+    img.classList.add('cm-loaded-image');
+  }
+  return img;
+};
+
+class DxnImageWidget extends WidgetType {
+  constructor(
+    readonly _dxnUrl: string,
+    readonly _url: MaybePromise<string | undefined>,
+  ) {
+    super();
+  }
+
+  override eq(other: this) {
+    return this._dxnUrl === other._dxnUrl;
+  }
+
+  override toDOM(view: EditorView) {
+    if (typeof this._url === 'string') {
+      return createImg(view, this._url);
+    }
+
+    const widget = document.createElement('div');
+    widget.className = 'cm-image-wrapper';
+    const loader = document.createElement('div');
+    loader.className = 'mx-auto transition-opacity';
+    let loaderAdded = false;
+
+    const timeout = setTimeout(() => {
+      const root = createRoot(loader);
+      root.render(
+        <ThemeProvider tx={defaultTx}>
+          <Status indeterminate />
+        </ThemeProvider>,
+      );
+      widget.appendChild(loader);
+      loaderAdded = true;
+    }, WAIT_UNTIL_LOADER);
+
+    void Promise.resolve(this._url)
+      .then((url) => {
+        clearTimeout(timeout);
+        if (loaderAdded) {
+          widget.removeChild(loader);
+        }
+        if (url) {
+          widget.appendChild(createImg(view, url));
+        }
+      })
+      .catch(() => {
+        clearTimeout(timeout);
+        if (loaderAdded) {
+          widget.removeChild(loader);
+        }
+      });
+
+    return widget;
+  }
+}

package/src/extensions/index.ts

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

package/src/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './skills';
+export * from './meta';
+export * from './types';

package/src/meta.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+
+import config from '../dx.config';
+
+export const meta = Plugin.getMetaFromConfig(config);

package/src/operations/create.test.ts

@@ -0,0 +1,53 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { inlineBackend } from '../capabilities/inline-backend';
+import { MAX_FILE_SIZE } from '../types';
+import { FileTooLargeError, UnsupportedFileTypeError } from './create';
+
+const makeFile = (name: string, type: string, bytes: Uint8Array): File => new File([bytes as BlobPart], name, { type });
+
+// Database is unused by the inline backend, but the type signature requires it.
+const stubDb: any = {};
+
+describe('inlineBackend.upload', () => {
+  test('produces an inline FileData for a small PNG', async ({ expect }) => {
+    const bytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    const result = await inlineBackend.upload(makeFile('icon.png', 'image/png', bytes), stubDb);
+    expect(result.name).toBe('icon.png');
+    expect(result.type).toBe('image/png');
+    expect(result.size).toBe(bytes.byteLength);
+    expect(result.data._tag).toBe('inline');
+    expect(result.data._tag === 'inline' && result.data.bytes).toBeInstanceOf(Uint8Array);
+    expect(result.data._tag === 'inline' && result.data.bytes.byteLength).toBe(bytes.byteLength);
+  });
+
+  test('produces an inline FileData for a PDF', async ({ expect }) => {
+    const result = await inlineBackend.upload(makeFile('doc.pdf', 'application/pdf', new Uint8Array(1024)), stubDb);
+    expect(result.type).toBe('application/pdf');
+    expect(result.size).toBe(1024);
+    expect(result.data._tag).toBe('inline');
+  });
+
+  test('rejects files larger than 4MB', async ({ expect }) => {
+    const oversized = new Uint8Array(MAX_FILE_SIZE + 1);
+    await expect(inlineBackend.upload(makeFile('big.png', 'image/png', oversized), stubDb)).rejects.toThrow(
+      FileTooLargeError,
+    );
+  });
+
+  test('accepts video', async ({ expect }) => {
+    const result = await inlineBackend.upload(makeFile('movie.mp4', 'video/mp4', new Uint8Array(8)), stubDb);
+    expect(result.type).toBe('video/mp4');
+    expect(result.data._tag).toBe('inline');
+  });
+
+  test('rejects text/plain', async ({ expect }) => {
+    await expect(inlineBackend.upload(makeFile('notes.txt', 'text/plain', new Uint8Array(8)), stubDb)).rejects.toThrow(
+      UnsupportedFileTypeError,
+    );
+  });
+});

package/src/operations/create.ts

@@ -0,0 +1,87 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
+
+import { File, FileCapabilities, FileOperation, MAX_FILE_SIZE, Settings, isAcceptedMimeType } from '../types';
+
+export class UnsupportedFileTypeError extends Error {
+  constructor(public readonly type: string) {
+    super(`Unsupported file type: ${type}`);
+    this.name = 'UnsupportedFileTypeError';
+  }
+}
+
+export class FileTooLargeError extends Error {
+  constructor(
+    public readonly size: number,
+    public readonly limit: number = MAX_FILE_SIZE,
+  ) {
+    super(`File is too large: ${size} bytes (limit: ${limit} bytes)`);
+    this.name = 'FileTooLargeError';
+  }
+}
+
+export class NoBackendError extends Error {
+  constructor() {
+    super('No file storage backend is registered.');
+    this.name = 'NoBackendError';
+  }
+}
+
+/**
+ * Resolve the configured {@link FileCapabilities.Backend} from the plugin
+ * settings atom. Falls back to the inline backend (or the first registered
+ * one) if the configured id is missing or settings aren't available.
+ */
+export const resolveActiveBackend = Effect.gen(function* () {
+  const backends = yield* Capability.getAll(FileCapabilities.Backend);
+  if (backends.length === 0) {
+    return yield* Effect.fail(new NoBackendError());
+  }
+
+  const settingsAtomOpt = yield* Capability.get(FileCapabilities.SettingsAtom).pipe(Effect.option);
+  const registryOpt = yield* Capability.get(Capabilities.AtomRegistry).pipe(Effect.option);
+
+  if (settingsAtomOpt._tag === 'Some' && registryOpt._tag === 'Some') {
+    const settings = registryOpt.value.get(settingsAtomOpt.value) as Settings.Settings;
+    const id = settings.backend ?? Settings.DEFAULT_BACKEND_ID;
+    const match = backends.find((b) => b.id === id);
+    if (match) {
+      return match;
+    }
+  }
+
+  return backends.find((b) => b.id === Settings.DEFAULT_BACKEND_ID) ?? backends[0];
+});
+
+const handler: Operation.WithHandler<typeof FileOperation.Create> = FileOperation.Create.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* ({ file, db }) {
+      // Validate before hitting the backend so the contract is consistent regardless of backend.
+      if (!isAcceptedMimeType(file.type)) {
+        return yield* Effect.fail(new UnsupportedFileTypeError(file.type));
+      }
+      if (file.size > MAX_FILE_SIZE) {
+        return yield* Effect.fail(new FileTooLargeError(file.size));
+      }
+      const backend = yield* resolveActiveBackend;
+      const info = yield* Effect.promise(() => backend.upload(file, db));
+      return {
+        object: File.make({
+          name: info.name,
+          type: info.type,
+          size: info.size,
+          data: info.data,
+          timestamp: new Date().toISOString(),
+        }),
+      };
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/index.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/compute';
+
+export const FileOperationHandlerSet = OperationHandlerSet.lazy(
+  () => import('./create'),
+  () => import('./read'),
+);

package/src/operations/read.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Operation } from '@dxos/compute';
+import { Database } from '@dxos/echo';
+import { ContentBlock } from '@dxos/types';
+
+import { FileOperation } from '../types';
+
+const handler: Operation.WithHandler<typeof FileOperation.Read> = FileOperation.Read.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ file }) {
+      const obj = yield* Database.load(file);
+      const url =
+        obj.data._tag === 'inline'
+          ? `data:${obj.type};base64,${Buffer.from(obj.data.bytes).toString('base64')}`
+          : obj.data.url;
+
+      return ContentBlock.ContentBlockResult.make({
+        content: [
+          ContentBlock.File.make({
+            url,
+            name: obj.name,
+            mediaType: obj.type,
+          }),
+        ],
+      });
+    }),
+  ),
+);
+
+export default handler;