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

package/dx.config.ts

@@ -17,19 +17,23 @@ export default Config2.make({
       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.
+      up to a 4 MB limit per file for the inline backend (other backends scale beyond it). 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.
+      A File object's \`data\` field is a reference to a \`Blob\` ECHO object (from \`@dxos/echo\`), which
+      abstracts where bytes actually live. \`Blob.url\`/\`Blob.read\` resolve a renderable URL or the raw
+      bytes regardless of backend, keeping the File object schema backend-agnostic without a separate
+      URL-resolver capability. 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' },
+    icon: { key: 'ph--file--regular', hue: 'indigo' },
     source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/plugin-file',
     spec: 'PLUGIN.mdl',
+    tags: ['alpha'],
   },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/plugin-file",
-  "version": "0.9.1-staging.ee54ba693a",
+  "version": "0.11.0",
   "description": "Inline file (image / PDF) storage plugin for DXOS",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -16,32 +16,36 @@
     "#skills": {
       "source": "./src/skills/index.ts",
       "types": "./dist/types/src/skills/index.d.ts",
-      "default": "./dist/lib/neutral/skills/index.mjs"
+      "default": "./dist/lib/skills.mjs"
     },
     "#capabilities": {
-      "source": "./src/capabilities/index.ts",
+      "source": {
+        "node": "./src/capabilities/node.ts",
+        "default": "./src/capabilities/index.ts"
+      },
       "types": "./dist/types/src/capabilities/index.d.ts",
-      "default": "./dist/lib/neutral/capabilities/index.mjs"
+      "node": "./dist/lib/capabilities/node.mjs",
+      "default": "./dist/lib/capabilities.mjs"
     },
     "#components": {
       "source": "./src/components/index.ts",
       "types": "./dist/types/src/components/index.d.ts",
-      "default": "./dist/lib/neutral/components/index.mjs"
+      "default": "./dist/lib/components.mjs"
     },
     "#containers": {
       "source": "./src/containers/index.ts",
       "types": "./dist/types/src/containers/index.d.ts",
-      "default": "./dist/lib/neutral/containers/index.mjs"
+      "default": "./dist/lib/containers.mjs"
     },
     "#meta": {
       "source": "./src/meta.ts",
       "types": "./dist/types/src/meta.d.ts",
-      "default": "./dist/lib/neutral/meta.mjs"
+      "default": "./dist/lib/meta.mjs"
     },
     "#operations": {
       "source": "./src/operations/index.ts",
       "types": "./dist/types/src/operations/index.d.ts",
-      "default": "./dist/lib/neutral/operations/index.mjs"
+      "default": "./dist/lib/operations.mjs"
     },
     "#plugin": {
       "source": {
@@ -49,41 +53,41 @@
         "default": "./src/FilePlugin.tsx"
       },
       "types": "./dist/types/src/FilePlugin.d.ts",
-      "node": "./dist/lib/neutral/FilePlugin.node.mjs",
-      "default": "./dist/lib/neutral/FilePlugin.mjs"
+      "node": "./dist/lib/FilePlugin.node.mjs",
+      "default": "./dist/lib/FilePlugin.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": {
       "source": "./src/types/index.ts",
       "types": "./dist/types/src/types/index.d.ts",
-      "default": "./dist/lib/neutral/types/index.mjs"
+      "import": "./dist/lib/types.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
@@ -94,44 +98,44 @@
     "PLUGIN.mdl"
   ],
   "dependencies": {
-    "@codemirror/language": "^6.12.3",
-    "@codemirror/state": "^6.6.0",
-    "@codemirror/view": "^6.43.0",
-    "@effect-atom/atom-react": "^0.5.0",
+    "@codemirror/language": "^6.12.4",
+    "@codemirror/state": "^6.7.1",
+    "@codemirror/view": "^6.43.6",
+    "@effect-atom/atom": "^0.5.3",
     "effect": "3.21.4",
     "react-dropzone": "^14.2.3",
-    "@dxos/app-framework": "0.9.1-staging.ee54ba693a",
-    "@dxos/app-toolkit": "0.9.1-staging.ee54ba693a",
-    "@dxos/echo": "0.9.1-staging.ee54ba693a",
-    "@dxos/compute": "0.9.1-staging.ee54ba693a",
-    "@dxos/effect": "0.9.1-staging.ee54ba693a",
-    "@dxos/plugin-markdown": "0.9.1-staging.ee54ba693a",
-    "@dxos/plugin-client": "0.9.1-staging.ee54ba693a",
-    "@dxos/keys": "0.9.1-staging.ee54ba693a",
-    "@dxos/plugin-space": "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/react-ui-form": "0.9.1-staging.ee54ba693a",
-    "@dxos/ui-editor": "0.9.1-staging.ee54ba693a",
-    "@dxos/util": "0.9.1-staging.ee54ba693a"
+    "@dxos/app-framework": "0.11.0",
+    "@dxos/app-toolkit": "0.11.0",
+    "@dxos/compute": "0.11.0",
+    "@dxos/echo": "0.11.0",
+    "@dxos/effect": "0.11.0",
+    "@dxos/keys": "0.11.0",
+    "@dxos/plugin-client": "0.11.0",
+    "@dxos/plugin-markdown": "0.11.0",
+    "@dxos/plugin-space": "0.11.0",
+    "@dxos/react-client": "0.11.0",
+    "@dxos/react-ui": "0.11.0",
+    "@dxos/react-ui-form": "0.11.0",
+    "@dxos/types": "0.11.0",
+    "@dxos/ui-editor": "0.11.0",
+    "@dxos/util": "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/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"
   },
   "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/FilePlugin.node.ts

@@ -4,6 +4,7 @@
 
 import { Plugin } from '@dxos/app-framework';
 import { AppPlugin } from '@dxos/app-toolkit';
+import { Blob } from '@dxos/echo';
 
 import { CreateObject, OperationHandler } from '#capabilities';
 import { meta } from '#meta';
@@ -12,7 +13,7 @@ import { File } from '#types';
 export const FilePlugin = Plugin.define(meta).pipe(
   AppPlugin.addCreateObjectModule({ activate: CreateObject }),
   AppPlugin.addOperationHandlerModule({ activate: OperationHandler }),
-  AppPlugin.addSchemaModule({ schema: [File.File] }),
+  AppPlugin.addSchemaModule({ schema: [File.File, Blob.Blob] }),
   Plugin.make,
 );
 

package/src/FilePlugin.tsx

@@ -4,11 +4,13 @@
 
 import { Plugin } from '@dxos/app-framework';
 import { AppActivationEvents, AppPlugin } from '@dxos/app-toolkit';
+import { Blob } from '@dxos/echo';
 import { ClientEvents } from '@dxos/plugin-client';
 import { MarkdownEvents } from '@dxos/plugin-markdown';
 
 import {
   CreateObject,
+  EdgeBackend,
   FileUploader,
   InlineBackend,
   Markdown,
@@ -28,7 +30,7 @@ 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.addSchemaModule({ schema: [File.File, Blob.Blob] }),
   AppPlugin.addSettingsModule({ activate: Settings }),
   AppPlugin.addSurfaceModule({ activate: ReactSurface }),
   AppPlugin.addTranslationsModule({ translations }),
@@ -42,6 +44,11 @@ export const FilePlugin = Plugin.define(meta).pipe(
     activatesOn: ClientEvents.ClientReady,
     activate: FileUploader,
   }),
+  Plugin.addModule({
+    id: 'edge-backend',
+    activatesOn: ClientEvents.ClientReady,
+    activate: EdgeBackend,
+  }),
   Plugin.addModule({
     id: 'markdown',
     activatesOn: MarkdownEvents.SetupExtensions,

package/src/capabilities/FileUploadField.tsx

@@ -0,0 +1,37 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { useCallback } from 'react';
+
+import { type Surface } from '@dxos/app-framework/ui';
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { type FormFieldRendererProps } from '@dxos/react-ui-form';
+
+import { FileInput } from '#components';
+
+/** The form renderer's own props ride alongside `data` on the surface envelope. */
+export type FileUploadFieldProps = Surface.ComponentProps<AppSurface.FormInputData> &
+  Pick<FormFieldRendererProps<File>, 'onValueChange'>;
+
+/**
+ * Form field that uploads a file for an upload-annotated property. It consumes the whole surface
+ * envelope, so it is registered without a `props` mapper.
+ */
+export const FileUploadField = ({ data, onValueChange }: FileUploadFieldProps) => {
+  const ast = data.fieldPropertyAst;
+  const handleChange = useCallback(
+    (file: File) => {
+      if (ast) {
+        onValueChange?.(ast, file);
+      }
+    },
+    [ast, onValueChange],
+  );
+
+  if (!ast) {
+    return null;
+  }
+
+  return <FileInput schema={data.schema} onChange={handleChange} />;
+};

package/src/capabilities/edge-backend.ts

@@ -0,0 +1,27 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { Blob } from '@dxos/echo';
+import { ClientCapabilities } from '@dxos/plugin-client';
+
+import { FileCapabilities } from '#types';
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const client = yield* Capability.get(ClientCapabilities.Client);
+    const edgeUrl = client.config.values.runtime?.services?.edge?.url;
+    if (!edgeUrl) {
+      return Capability.contributes(Capabilities.Null, null);
+    }
+
+    return Capability.contributes(FileCapabilities.Backend, {
+      name: 'Edge',
+      description: 'Store files on the DXOS edge network. Scales beyond the inline size cap.',
+      storage: Blob.Storage.edge,
+    });
+  }),
+);

package/src/capabilities/file-uploader.ts

@@ -3,9 +3,11 @@
 //
 
 import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
 
 import { Capabilities, Capability } from '@dxos/app-framework';
 import { AppCapabilities } from '@dxos/app-toolkit';
+import { Blob, Database } from '@dxos/echo';
 import { EffectEx } from '@dxos/effect';
 import { SpaceOperation } from '@dxos/plugin-space';
 
@@ -20,12 +22,12 @@ export default Capability.makeModule(
       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;
+        const blob = yield* Database.load(object.data);
+        const urlOption = yield* Blob.url(blob).pipe(Effect.provide(Database.layer(db)));
         return {
           name: object.name ?? file.name,
-          type: object.type,
-          ...(external?.url ? { url: external.url } : {}),
-          ...(external?.cid ? { cid: external.cid } : {}),
+          type: blob.type ?? 'application/octet-stream',
+          ...(Option.isSome(urlOption) ? { url: urlOption.value } : {}),
         };
       });
 

package/src/capabilities/index.ts

@@ -7,6 +7,7 @@ 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 EdgeBackend = Capability.lazy('EdgeBackend', () => import('./edge-backend'));
 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'));

package/src/capabilities/inline-backend.ts

@@ -5,35 +5,18 @@
 import * as Effect from 'effect/Effect';
 
 import { Capability } from '@dxos/app-framework';
+import { Blob } from '@dxos/echo';
 
-import { File, FileCapabilities, MAX_FILE_SIZE, Settings, isAcceptedMimeType } from '#types';
-
-import { FileTooLargeError, UnsupportedFileTypeError } from '../operations/create';
+import { FileCapabilities } from '#types';
 
 /**
- * Inline backend: file bytes are stored on the ECHO object itself.
+ * Inline backend descriptor: 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),
-    };
-  },
+  storage: Blob.Storage.inline,
 };
 
 export default Capability.makeModule(() =>

package/src/capabilities/markdown-extension.ts

@@ -8,14 +8,10 @@ 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;
-
+export default Capability.makeModule(() =>
+  Effect.sync(() => {
     const provider: MarkdownExtensionProvider = ({ document, viewMode }) => {
       if (viewMode === 'source') {
         return undefined;
@@ -26,8 +22,7 @@ export default Capability.makeModule(
         if (!space) {
           return undefined;
         }
-        const resolvers = capabilities.getAll(FileCapabilities.UrlResolver);
-        return [image({ space, resolvers })];
+        return [image({ space })];
       }
 
       return undefined;

package/src/capabilities/node.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Capability } from '@dxos/app-framework';
+import { OperationHandlerSet } from '@dxos/compute';
+
+// The capabilities `FilePlugin.node` activates, and only those. `Capability.lazy` defers the
+// import at runtime but a bundler still walks it, so listing the React surfaces here would pull
+// the plugin's components into every node and bun build.
+
+export const CreateObject = Capability.lazy('CreateObject', () => import('./create-object'));
+export const OperationHandler = Capability.lazy<OperationHandlerSet.OperationHandlerSet>(
+  'OperationHandler',
+  () => import('./operation-handler'),
+);

package/src/capabilities/react-surface.ts

@@ -0,0 +1,46 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { Surface } from '@dxos/app-framework/ui';
+import { AppSurface } from '@dxos/app-toolkit/ui';
+import { SchemaEx } from '@dxos/effect';
+
+import { FileArticle, FileSettings } from '#containers';
+import { meta } from '#meta';
+import { File, FileAction } from '#types';
+
+import { FileUploadField } from './FileUploadField';
+
+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: FileArticle,
+        props: ({ role, data: { subject } }) => ({ role, subject }),
+      }),
+      Surface.create({
+        id: 'createForm',
+        filter: AppSurface.formInputBySchema(
+          (ast) => !!SchemaEx.findAnnotation<Record<string, string[]>>(ast, FileAction.UploadAnnotationId),
+        ),
+        component: FileUploadField,
+      }),
+      Surface.create({
+        id: 'pluginSettings',
+        filter: AppSurface.settings(AppSurface.Article, meta.profile.key),
+        component: FileSettings,
+        props: ({ data: { subject } }) => ({ subject }),
+      }),
+    ]),
+  ),
+);

package/src/components/FileInput/FileInput.tsx

@@ -11,7 +11,7 @@ import { useTranslation } from '@dxos/react-ui';
 import { mx } from '@dxos/ui-theme';
 
 import { meta } from '#meta';
-import { FileAction, MAX_FILE_SIZE } from '#types';
+import { FileAction } from '#types';
 
 export type FileInputProps = {
   schema: Schema.Schema.AnyNoContext;
@@ -24,10 +24,11 @@ export const FileInput = ({ schema, onChange }: FileInputProps) => {
 
   const onDropAccepted = useCallback((files: File[]) => onChange?.(files[0]), [onChange]);
 
+  // No client-side size cap here — the active backend determines the limit (inline is capped,
+  // edge/wnfs are not), and `op:Create` enforces it against the actual selected backend.
   const { acceptedFiles, getRootProps, getInputProps, isFocused, isDragAccept, isDragReject } = useDropzone({
     multiple: false,
     accept,
-    maxSize: MAX_FILE_SIZE,
     onDropAccepted,
   });
 

package/src/containers/FileArticle/FileArticle.tsx

@@ -2,63 +2,64 @@
 // Copyright 2026 DXOS.org
 //
 
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
 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 { Blob, Database, Obj } from '@dxos/echo';
+import { EffectEx } from '@dxos/effect';
 import { Panel } from '@dxos/react-ui';
 
 import { FilePreview } from '#components';
-import { File, FileCapabilities } from '#types';
+import { File } 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);
+  const [rendered, setRendered] = useState<{ url: string; type: 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);
+    setRendered(undefined);
+
+    const db = Obj.getDatabase(file);
+    if (!db) {
+      return;
     }
 
-    // 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);
+    const program = Effect.gen(function* () {
+      const blob = yield* Database.load(file.data);
+      const type = blob.type ?? 'application/octet-stream';
+      const urlOption = yield* Blob.url(blob);
+      if (Option.isSome(urlOption)) {
+        return { url: urlOption.value, type };
+      }
+      const bytes = yield* Blob.read(blob);
+      // `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 `bytes` differently.
+      const url = URL.createObjectURL(new globalThis.Blob([bytes as BlobPart], { type }));
+      return { url, type };
+    }).pipe(
+      Effect.provide(Database.layer(db)),
+      Effect.catchAll(() => Effect.succeed(undefined)),
+    );
+
+    void EffectEx.runPromise(program).then((result) => {
+      if (cancelled) {
+        if (result?.url.startsWith('blob:')) {
+          URL.revokeObjectURL(result.url);
+        }
         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);
-          }
-        });
-    }
+      if (result?.url.startsWith('blob:')) {
+        createdBlobUrl = result.url;
+      }
+      setRendered(result);
+    });
 
     return () => {
       cancelled = true;
@@ -66,19 +67,25 @@ export const FileArticle = ({ role, subject: file }: FileArticleProps) => {
         URL.revokeObjectURL(createdBlobUrl);
       }
     };
-  }, [file, file.data, file.type, resolvers]);
+    // Keyed on `file.id` rather than `file`/`file.data` directly: ECHO's reactive proxy returns a
+    // fresh `Ref` wrapper for `.data` on every access, so including it (or the proxy object itself)
+    // here would rerun this effect on every render — clearing the render state and re-resolving it
+    // each time, which flickers the image while the object settles.
+  }, [file.id]);
 
-  if (!renderUrl) {
+  if (!rendered) {
     return null;
   }
 
   return (
-    <Panel.Root role={role} className='dx-document'>
+    <Panel.Root role={role} classNames='dx-document'>
       <Panel.Content asChild>
-        <FilePreview type={file.type} url={renderUrl} />
+        <FilePreview type={rendered.type} url={rendered.url} />
       </Panel.Content>
     </Panel.Root>
   );
 };
 
 export default FileArticle;
+
+FileArticle.displayName = 'FileArticle';