@dxos/plugin-file 0.0.0

package/src/plugin.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+
+import { meta } from './meta';
+
+export const FilePlugin = Plugin.lazy(meta, () => import('#plugin'));
+
+export { FileOperationHandlerSet } from './operations';

package/src/skills/file-skill.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Skill, Template } from '@dxos/compute';
+import { trim } from '@dxos/util';
+
+import { FileOperation } from '../types';
+
+export const SKILL_KEY = 'org.dxos.skill.file';
+
+const make = () =>
+  Skill.make({
+    key: SKILL_KEY,
+    name: 'File',
+    description: 'Read the contents of files (images, videos, PDFs) as File content blocks.',
+    tools: Skill.toolDefinitions({
+      operations: [FileOperation.Read],
+    }),
+    instructions: Template.make({
+      source: trim`
+        {{! File }}
+
+        You can read the contents of files.
+        Calling the read tool returns the file contents as a File content block (a data URL for
+        inline files, the original URL for external files). The model receives the file natively
+        and can describe, transcribe, or otherwise reason over its contents.
+      `,
+    }),
+    agentCanEnable: true,
+  });
+
+const skill: Skill.Definition = {
+  key: SKILL_KEY,
+  make,
+};
+
+export default skill;

package/src/skills/index.ts

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

package/src/translations.ts

@@ -0,0 +1,37 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Type } from '@dxos/echo';
+import { type Resource } from '@dxos/react-ui';
+
+import { meta } from '#meta';
+import { File } from '#types';
+
+export const translations = [
+  {
+    'en-US': {
+      [Type.getTypename(File.File)]: {
+        'typename.label': 'File',
+        'typename.label_zero': 'Files',
+        'typename.label_one': 'File',
+        'typename.label_other': 'Files',
+        'object-name.placeholder': 'New file',
+        'add-object.label': 'Add file',
+        'rename-object.label': 'Rename file',
+        'delete-object.label': 'Delete file',
+        'object-deleted.label': 'File deleted',
+      },
+      [meta.profile.key]: {
+        'plugin.name': 'File',
+        'file-input.placeholder': 'Drop a file here, or click to select a file',
+        'too-large-error.message': 'File is too large. Maximum size is 4MB.',
+        'unsupported-type-error.message': 'Unsupported file type. Only images, videos, and PDFs are allowed.',
+        'settings.backend.label': 'Storage backend',
+        'settings.backend.description':
+          'Where uploaded files are stored. Install additional plugins (e.g. WNFS) to add backends.',
+        'settings.backend.placeholder': 'Select backend',
+      },
+    },
+  },
+] as const satisfies Resource[];

package/src/types/FileCapabilities.ts

@@ -0,0 +1,58 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import { type Atom } from '@effect-atom/atom-react';
+
+import { Capability } from '@dxos/app-framework';
+import { type Database } from '@dxos/echo';
+import { type Space } from '@dxos/react-client/echo';
+import { File } from '@dxos/types';
+
+import { meta } from '#meta';
+
+import * as Settings from './Settings';
+
+/**
+ * A file storage backend. Each backend ingests a File from the user and
+ * returns the metadata + the {@link File.FileData} to attach to a
+ * {@link File.File} object.
+ */
+export type Backend = {
+  /** Stable backend id (e.g. 'inline', 'wnfs'). Used as the settings key. */
+  readonly id: string;
+  /** Display label shown in the settings UI. */
+  readonly name: string;
+  /** Description shown next to the backend in settings. */
+  readonly description?: string;
+  /** Upload a file. Throws on validation errors (size cap, unsupported MIME). */
+  readonly upload: (file: globalThis.File, db: Database.Database) => Promise<UploadResult>;
+};
+
+export type UploadResult = {
+  readonly name: string;
+  readonly type: string;
+  readonly size: number;
+  readonly data: File.FileData;
+};
+
+export const Backend = Capability.make<Backend>(`${meta.profile.key}.capability.backend`);
+
+/**
+ * Resolves an external URL (e.g. `wnfs://…`) into a renderable URL (a
+ * `blob:`, `data:`, or `http(s):` URL). Consumers iterate registered
+ * resolvers and pick the first that returns true from {@link UrlResolver#test}.
+ */
+export type UrlResolver = {
+  readonly id: string;
+  readonly test: (url: string) => boolean;
+  readonly resolve: (url: string, file: File.File, space?: Space) => Promise<string | undefined>;
+};
+
+export const UrlResolver = Capability.make<UrlResolver>(`${meta.profile.key}.capability.url-resolver`);
+
+export const SettingsAtom = Capability.make<Atom.Writable<Settings.Settings>>(
+  `${meta.profile.key}.capability.settings`,
+);

package/src/types/FileOperation.ts

@@ -0,0 +1,44 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
+import { Database, DXN, Ref, Type } from '@dxos/echo';
+import { ContentBlock, File } from '@dxos/types';
+
+import { meta } from '#meta';
+
+import { FileAction } from './types';
+
+const makeKey = (name: string) => DXN.make(`${meta.profile.key}.operation.${name}`);
+
+export const Create = Operation.make({
+  meta: { key: makeKey('create'), name: 'Create File', icon: 'ph--file--regular' },
+  services: [Capability.Service],
+  input: Schema.extend(FileAction.CreateFileSchema, Schema.Struct({ db: Database.Database })),
+  output: Schema.Struct({
+    object: Type.getSchema(File.File),
+  }),
+});
+
+export const Read = Operation.make({
+  meta: {
+    key: makeKey('read'),
+    name: 'Read File',
+    description:
+      'Reads the contents of a file and returns them as a File content block (data URL for inline files, original URL for external files).',
+    icon: 'ph--file-arrow-down--regular',
+  },
+  input: Schema.Struct({
+    file: Ref.Ref(File.File).annotations({
+      description: 'The file to read.',
+    }),
+  }),
+  output: ContentBlock.ContentBlockResult,
+  services: [Database.Service],
+});

package/src/types/Settings.ts

@@ -0,0 +1,23 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+export const DEFAULT_BACKEND_ID = 'inline';
+
+export const Settings = Schema.mutable(
+  Schema.Struct({
+    backend: Schema.optional(
+      Schema.String.annotations({
+        title: 'File storage backend',
+        description:
+          'Where uploaded files are stored. Defaults to inline (bytes saved on the ECHO object). Install additional plugins (e.g. WNFS) to add external backends.',
+      }),
+    ),
+  }),
+);
+
+export interface Settings extends Schema.Schema.Type<typeof Settings> {}

package/src/types/index.ts

@@ -0,0 +1,12 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { File } from '@dxos/types';
+
+export * from './limits';
+export * from './types';
+
+export * as FileCapabilities from './FileCapabilities';
+export * as FileOperation from './FileOperation';
+export * as Settings from './Settings';

package/src/types/limits.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export const MAX_FILE_SIZE = 4 * 1024 * 1024;
+
+export const ACCEPTED_MIME: Record<string, string[]> = {
+  'image/*': ['.jpg', '.jpeg', '.png', '.gif', '.webp', '.svg'],
+  'video/*': ['.mp4', '.webm', '.mov'],
+  'application/pdf': ['.pdf'],
+};
+
+export const isAcceptedMimeType = (type: string): boolean => {
+  if (type === 'application/pdf') {
+    return true;
+  }
+  if (type.startsWith('image/') || type.startsWith('video/')) {
+    return true;
+  }
+  return false;
+};

package/src/types/types.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { meta } from '#meta';
+
+import { ACCEPTED_MIME } from './limits';
+
+export namespace FileAction {
+  export const UploadAnnotationId = Symbol.for(`${meta.profile.key}.annotation.upload`);
+
+  export const CreateFileSchema = Schema.Struct({
+    file: Schema.instanceOf(File).annotations({
+      [UploadAnnotationId]: ACCEPTED_MIME,
+    }),
+  });
+
+  export type CreateFileForm = Schema.Schema.Type<typeof CreateFileSchema>;
+}

package/src/vite-env.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="vite/client" />
+
+//
+// Copyright 2026 DXOS.org
+//
+
+declare module '*.mdl?raw' {
+  const content: string;
+  export default content;
+}