@dxos/plugin-file 0.0.0

package/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-Apache-2.0
+
+## Notice
+
+Copyright 2026 DXOS
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/PLUGIN.mdl

@@ -0,0 +1,372 @@
+---
+id: org.dxos.plugin.file
+name: FilePlugin
+version: 0.1.0
+---
+
+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.
+A URL-resolver 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.
+
+## Extensions
+
+The following extension dialects are used in this document.
+Each extension is defined in the Appendix or resolved via its URI.
+
+| Term        | URI                            |
+|-------------|--------------------------------|
+| `type`      | `org.dxos.mdl.type@1.0`       |
+| `feat`      | `org.dxos.mdl.feat@1.0`       |
+| `test`      | `org.dxos.mdl.test@1.0`       |
+| `component` | `org.dxos.mdl.component@1.0`  |
+| `op`        | `org.dxos.mdl.op@1.0`         |
+
+## Types
+
+```mdl
+type FileDataInline
+  desc: File bytes stored directly on the ECHO object.
+  fields:
+    _tag: 'inline'
+    bytes: Uint8Array
+```
+
+```mdl
+type FileDataExternal
+  desc: File bytes stored outside ECHO; referenced by URL.
+  fields:
+    _tag: 'external'
+    url: string
+    cid?: string             # optional content-addressed identifier
+```
+
+```mdl
+type FileData
+  desc: Discriminated union of inline and external storage.
+  literals: FileDataInline | FileDataExternal
+```
+
+```mdl
+type File
+  desc: ECHO object (typename dxos.org.type.file) representing an uploaded binary asset.
+  fields:
+    name?: string
+    type: string             # MIME type
+    size: number             # byte count
+    data: FileData
+    timestamp?: string       # ISO 8601 upload time
+```
+
+```mdl
+type UploadResult
+  desc: Normalised return value from a Backend.upload call.
+  fields:
+    name: string
+    type: string
+    size: number
+    data: FileData
+```
+
+```mdl
+type Settings
+  desc: Per-user plugin settings stored in the ECHO space.
+  fields:
+    backend?: string         # active backend id; defaults to 'inline'
+```
+
+## Components
+
+```mdl
+component FilePreview
+  desc: |
+    Renders a File object using the appropriate HTML element for its MIME type.
+    Images use <img>, videos use <video controls>, PDFs use <iframe>, and
+    all other types fall back to a download link.
+  props:
+    type: string             # MIME type
+    url: string              # renderable blob:, data:, or http(s): URL
+  layout: |
+    ┌──────────────────────────────┐
+    │  <img> / <video> / <iframe>  │
+    │  or [Download file] link     │
+    └──────────────────────────────┘
+```
+
+```mdl
+component FileInput
+  desc: Drag-and-drop / browse file picker used inside the Create Object form.
+  props:
+    schema: Schema           # effect/Schema with UploadAnnotation on the file field
+  emits:
+    onChange(file: File)
+  layout: |
+    ┌──────────────────────────────┐
+    │  [ Drop file or click here ] │
+    └──────────────────────────────┘
+```
+
+```mdl
+component FileSettings
+  desc: Plugin settings panel rendered in the Composer settings surface.
+  props:
+    settings: Settings
+  emits:
+    onSettingsChange(settings: Settings)
+  layout: |
+    ┌──────────────────────────────┐
+    │  Storage backend: [select ▼] │
+    │  (one row per registered     │
+    │   backend with description)  │
+    └──────────────────────────────┘
+```
+
+```mdl
+component FileArticle
+  desc: |
+    Full-viewport article container rendered for article, section, and slide
+    roles. Resolves a renderable URL from the File object via inline blob
+    conversion or registered UrlResolver capabilities, then delegates to
+    FilePreview. Shows an empty state while the URL is resolving.
+  props:
+    role: AppSurface.Role
+    subject: File
+  layout: |
+    ┌──────────────────────────────┐
+    │                              │
+    │      FilePreview             │
+    │      (fills container)       │
+    │                              │
+    └──────────────────────────────┘
+```
+
+## Operations
+
+```mdl
+op Create
+  key: org.dxos.plugin.file.operation.create
+  desc: |
+    Validates a browser File object (MIME type and size), routes the upload to the
+    active Backend capability, and constructs a File ECHO object from the result.
+    Does not add the object to the space — callers do that separately.
+  input:
+    file: BrowserFile        # browser File (globalThis.File)
+    db: Database
+  output: { object: File }
+  errors:
+    UnsupportedFileTypeError: MIME type is not image/*, video/*, or application/pdf
+    FileTooLargeError: file exceeds the 4 MB inline limit
+    NoBackendError: no Backend capability is registered
+```
+
+## Features
+
+```mdl
+feat F-1: File upload
+
+  req F-1.1: Accepted MIME types MUST be image/* (jpg, jpeg, png, gif, webp, svg),
+    video/* (mp4, webm, mov), and application/pdf only.
+
+  req F-1.2: Maximum upload size MUST be 4 MB for the inline backend.
+
+  req F-1.3:
+    when: user submits the Create Object form with a valid file
+    then:
+      - op:Create is invoked with the selected file and active database
+      - the resulting File object is added to the space via SpaceOperation.AddObject
+      - FileUploader capability returns metadata to the caller (name, type, url/cid)
+
+  req F-1.4:
+    when: file MIME type is not accepted
+    then: UnsupportedFileTypeError returned; no ECHO write occurs
+
+  req F-1.5:
+    when: file size exceeds the limit
+    then: FileTooLargeError returned; no ECHO write occurs
+```
+
+```mdl
+feat F-2: Backend capability system
+
+  req F-2.1: Any plugin may contribute a Backend capability. Multiple backends
+    may be registered simultaneously.
+
+  req F-2.2: The inline backend MUST always be registered by FilePlugin itself.
+    It serialises bytes directly onto the ECHO object.
+
+  req F-2.3: The active backend is determined by Settings.backend. If the
+    configured id is absent or unrecognised, the inline backend is used.
+
+  req F-2.4: A UrlResolver capability allows external backends to convert an
+    opaque storage URI (e.g. wnfs://…) into a renderable URL at view time.
+    FileArticle iterates registered resolvers and uses the first that matches.
+```
+
+```mdl
+feat F-3: File preview
+
+  req F-3.1: FileArticle MUST resolve a renderable URL before rendering
+    FilePreview. For inline files a blob: URL is created from the stored bytes
+    and revoked on unmount.
+
+  req F-3.2: FilePreview MUST render the appropriate element for each MIME class:
+    image/* → <img>, video/* → <video controls>, application/pdf → <iframe>,
+    other → <a download>.
+
+  req F-3.3: FileArticle surfaces are registered for article, section,
+    and slide roles so files embed correctly in Markdown and Presenter layouts.
+```
+
+```mdl
+feat F-4: Markdown integration
+
+  req F-4.1: A Markdown extension contributed at MarkdownEvents.SetupExtensions
+    MUST allow files to be embedded in Markdown documents as inline attachments.
+```
+
+```mdl
+feat F-5: Settings
+
+  req F-5.1: The Settings panel MUST list all registered backends with their
+    id, display name, and optional description.
+
+  req F-5.2: Selecting a backend MUST persist the choice to Settings.backend
+    via the SettingsAtom capability.
+```
+
+## Acceptance
+
+```mdl
+test T-1: Upload image inline
+  given: only the inline backend is registered
+  when: user uploads a 1 MB PNG via the Create Object form
+  then:
+    - op:Create returns a File with data._tag === 'inline'
+    - File.type === 'image/png', File.size === byte count
+    - File is added to the space
+```
+
+```mdl
+test T-2: Reject oversized file
+  given: inline backend registered, 4 MB limit
+  when: user uploads a 5 MB JPEG
+  then:
+    - FileTooLargeError is returned
+    - no File object is created
+    - no ECHO write occurs
+```
+
+```mdl
+test T-3: Reject unsupported MIME type
+  given: inline backend registered
+  when: user uploads a .zip file
+  then:
+    - UnsupportedFileTypeError is returned
+    - no File object is created
+```
+
+```mdl
+test T-4: Preview inline image
+  given: a File with data._tag === 'inline' and type === 'image/png'
+  when: FileArticle is rendered
+  then:
+    - a blob: URL is created from File.data.bytes
+    - FilePreview renders an <img> element with that URL
+    - the blob: URL is revoked on unmount
+```
+
+```mdl
+test T-5: Preview PDF
+  given: a File with type === 'application/pdf' and a resolved HTTP URL
+  when: FilePreview is rendered
+  then: an <iframe> element is rendered with the file URL as src
+```
+
+```mdl
+test T-6: Backend fallback to inline
+  given: Settings.backend is 'wnfs' but no WNFS backend is registered
+  when: op:Create is invoked
+  then: the inline backend is used and the file is stored inline
+```
+
+```mdl
+test T-7: External URL resolved by UrlResolver
+  given: a File with data._tag === 'external' and data.url === 'wnfs://cid/file.jpg'
+  and: a UrlResolver capability registered that handles 'wnfs://' URIs
+  when: FileArticle is rendered
+  then:
+    - UrlResolver.resolve is called with the wnfs:// URL
+    - FilePreview receives the resolved renderable URL
+```
+
+```mdl
+test T-8: No backend error
+  given: no Backend capability is registered
+  when: op:Create is invoked
+  then: NoBackendError is returned
+```
+
+---
+
+## Appendix: Extension Definitions
+
+```mdl
+ext type
+  uri: org.dxos.mdl.type@1.0
+  desc: A named data structure with typed fields and optional literals.
+  fields:
+    desc?: Prose
+    fields?: FieldMap
+    literals?: UnionList
+    extends?: TypeRef[]
+```
+
+```mdl
+ext feat
+  uri: org.dxos.mdl.feat@1.0
+  desc: A named feature grouping one or more requirements.
+  fields:
+    desc?: Prose
+    req: RequirementList
+  nesting: self
+```
+
+```mdl
+ext test
+  uri: org.dxos.mdl.test@1.0
+  desc: An acceptance scenario expressed as given / when / then steps.
+  fields:
+    given?: Step | Step[]
+    when?: Step | Step[]
+    then: Step | Step[]
+    tags?: TagList
+```
+
+```mdl
+ext component
+  uri: org.dxos.mdl.component@1.0
+  desc: A UI component with props, internal state, slots, actions, and events.
+  fields:
+    desc?: Prose
+    props?: FieldMap
+    state?: FieldMap
+    slots?: FieldMap
+    actions?: ActionMap
+    emits?: EventMap
+    layout?: CodeBlock
+```
+
+```mdl
+ext op
+  uri: org.dxos.mdl.op@1.0
+  desc: A named operation with typed inputs, outputs, and declared errors.
+  fields:
+    desc?: Prose
+    input?: FieldMap
+    output?: TypeExpr
+    errors?: ErrorMap
+    effects?: EffectList
+    requires?: ServiceList
+    note?: Prose
+```

package/dist/lib/neutral/FileArticle-YU6NN3KN.mjs

@@ -0,0 +1,80 @@
+import "./chunk-J5LGTIGS.mjs";
+
+// src/containers/FileArticle/FileArticle.tsx
+import React, { useEffect, useState } from "react";
+import { useCapabilities } from "@dxos/app-framework/ui";
+import { getSpace } from "@dxos/react-client/echo";
+import { Panel } from "@dxos/react-ui";
+import { FilePreview } from "#components";
+import { FileCapabilities } from "#types";
+var FileArticle = ({ role, subject: file }) => {
+  const resolvers = useCapabilities(FileCapabilities.UrlResolver);
+  const [renderUrl, setRenderUrl] = useState(void 0);
+  useEffect(() => {
+    const { data } = file;
+    if (data._tag === "inline") {
+      const url = URL.createObjectURL(new Blob([
+        data.bytes
+      ], {
+        type: file.type
+      }));
+      setRenderUrl(url);
+      return () => URL.revokeObjectURL(url);
+    }
+    let cancelled = false;
+    let createdBlobUrl;
+    if (/^(?:https?|data|blob):/i.test(data.url)) {
+      setRenderUrl(data.url);
+    } else {
+      const resolver = resolvers.find((r) => r.test(data.url));
+      if (!resolver) {
+        setRenderUrl(void 0);
+        return;
+      }
+      setRenderUrl(void 0);
+      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(void 0);
+        }
+      });
+    }
+    return () => {
+      cancelled = true;
+      if (createdBlobUrl) {
+        URL.revokeObjectURL(createdBlobUrl);
+      }
+    };
+  }, [
+    file,
+    file.data,
+    file.type,
+    resolvers
+  ]);
+  if (!renderUrl) {
+    return null;
+  }
+  return /* @__PURE__ */ React.createElement(Panel.Root, {
+    role,
+    className: "dx-document"
+  }, /* @__PURE__ */ React.createElement(Panel.Content, {
+    asChild: true
+  }, /* @__PURE__ */ React.createElement(FilePreview, {
+    type: file.type,
+    url: renderUrl
+  })));
+};
+export {
+  FileArticle as default
+};
+//# sourceMappingURL=FileArticle-YU6NN3KN.mjs.map

package/dist/lib/neutral/FileArticle-YU6NN3KN.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/containers/FileArticle/FileArticle.tsx"],
+  "sourcesContent": ["//\n// Copyright 2026 DXOS.org\n//\n\nimport React, { useEffect, useState } from 'react';\n\nimport { useCapabilities } from '@dxos/app-framework/ui';\nimport { type AppSurface } from '@dxos/app-toolkit/ui';\nimport { getSpace } from '@dxos/react-client/echo';\nimport { Panel } from '@dxos/react-ui';\n\nimport { FilePreview } from '#components';\nimport { File, FileCapabilities } from '#types';\n\nexport type FileArticleProps = AppSurface.ObjectArticleProps<File.File>;\n\nexport const FileArticle = ({ role, subject: file }: FileArticleProps) => {\n  const resolvers = useCapabilities(FileCapabilities.UrlResolver);\n  const [renderUrl, setRenderUrl] = useState<string | undefined>(undefined);\n\n  useEffect(() => {\n    const { data } = file;\n    if (data._tag === 'inline') {\n      const url = URL.createObjectURL(new Blob([data.bytes as BlobPart], { type: file.type }));\n      setRenderUrl(url);\n      return () => URL.revokeObjectURL(url);\n    }\n\n    // External URL: pass through `http(s):`/`data:`/`blob:` directly; otherwise dispatch to a resolver.\n    let cancelled = false;\n    let createdBlobUrl: string | undefined;\n\n    if (/^(?:https?|data|blob):/i.test(data.url)) {\n      setRenderUrl(data.url);\n    } else {\n      const resolver = resolvers.find((r) => r.test(data.url));\n      if (!resolver) {\n        setRenderUrl(undefined);\n        return;\n      }\n      setRenderUrl(undefined);\n      void resolver\n        .resolve(data.url, file, getSpace(file))\n        .then((url) => {\n          if (cancelled) {\n            if (url?.startsWith('blob:')) {\n              URL.revokeObjectURL(url);\n            }\n            return;\n          }\n          if (url?.startsWith('blob:')) {\n            createdBlobUrl = url;\n          }\n          setRenderUrl(url);\n        })\n        .catch(() => {\n          if (!cancelled) {\n            setRenderUrl(undefined);\n          }\n        });\n    }\n\n    return () => {\n      cancelled = true;\n      if (createdBlobUrl) {\n        URL.revokeObjectURL(createdBlobUrl);\n      }\n    };\n  }, [file, file.data, file.type, resolvers]);\n\n  if (!renderUrl) {\n    return null;\n  }\n\n  return (\n    <Panel.Root role={role} className='dx-document'>\n      <Panel.Content asChild>\n        <FilePreview type={file.type} url={renderUrl} />\n      </Panel.Content>\n    </Panel.Root>\n  );\n};\n\nexport default FileArticle;\n"],
+  "mappings": ";;;AAIA,OAAOA,SAASC,WAAWC,gBAAgB;AAE3C,SAASC,uBAAuB;AAEhC,SAASC,gBAAgB;AACzB,SAASC,aAAa;AAEtB,SAASC,mBAAmB;AAC5B,SAAeC,wBAAwB;AAIhC,IAAMC,cAAc,CAAC,EAAEC,MAAMC,SAASC,KAAI,MAAoB;AACnE,QAAMC,YAAYT,gBAAgBI,iBAAiBM,WAAW;AAC9D,QAAM,CAACC,WAAWC,YAAAA,IAAgBb,SAA6Bc,MAAAA;AAE/Df,YAAU,MAAA;AACR,UAAM,EAAEgB,KAAI,IAAKN;AACjB,QAAIM,KAAKC,SAAS,UAAU;AAC1B,YAAMC,MAAMC,IAAIC,gBAAgB,IAAIC,KAAK;QAACL,KAAKM;SAAoB;QAAEC,MAAMb,KAAKa;MAAK,CAAA,CAAA;AACrFT,mBAAaI,GAAAA;AACb,aAAO,MAAMC,IAAIK,gBAAgBN,GAAAA;IACnC;AAGA,QAAIO,YAAY;AAChB,QAAIC;AAEJ,QAAI,0BAA0BC,KAAKX,KAAKE,GAAG,GAAG;AAC5CJ,mBAAaE,KAAKE,GAAG;IACvB,OAAO;AACL,YAAMU,WAAWjB,UAAUkB,KAAK,CAACC,MAAMA,EAAEH,KAAKX,KAAKE,GAAG,CAAA;AACtD,UAAI,CAACU,UAAU;AACbd,qBAAaC,MAAAA;AACb;MACF;AACAD,mBAAaC,MAAAA;AACb,WAAKa,SACFG,QAAQf,KAAKE,KAAKR,MAAMP,SAASO,IAAAA,CAAAA,EACjCsB,KAAK,CAACd,QAAAA;AACL,YAAIO,WAAW;AACb,cAAIP,KAAKe,WAAW,OAAA,GAAU;AAC5Bd,gBAAIK,gBAAgBN,GAAAA;UACtB;AACA;QACF;AACA,YAAIA,KAAKe,WAAW,OAAA,GAAU;AAC5BP,2BAAiBR;QACnB;AACAJ,qBAAaI,GAAAA;MACf,CAAA,EACCgB,MAAM,MAAA;AACL,YAAI,CAACT,WAAW;AACdX,uBAAaC,MAAAA;QACf;MACF,CAAA;IACJ;AAEA,WAAO,MAAA;AACLU,kBAAY;AACZ,UAAIC,gBAAgB;AAClBP,YAAIK,gBAAgBE,cAAAA;MACtB;IACF;EACF,GAAG;IAAChB;IAAMA,KAAKM;IAAMN,KAAKa;IAAMZ;GAAU;AAE1C,MAAI,CAACE,WAAW;AACd,WAAO;EACT;AAEA,SACE,sBAAA,cAACT,MAAM+B,MAAI;IAAC3B;IAAY4B,WAAU;KAChC,sBAAA,cAAChC,MAAMiC,SAAO;IAACC,SAAAA;KACb,sBAAA,cAACjC,aAAAA;IAAYkB,MAAMb,KAAKa;IAAML,KAAKL;;AAI3C;",
+  "names": ["React", "useEffect", "useState", "useCapabilities", "getSpace", "Panel", "FilePreview", "FileCapabilities", "FileArticle", "role", "subject", "file", "resolvers", "UrlResolver", "renderUrl", "setRenderUrl", "undefined", "data", "_tag", "url", "URL", "createObjectURL", "Blob", "bytes", "type", "revokeObjectURL", "cancelled", "createdBlobUrl", "test", "resolver", "find", "r", "resolve", "then", "startsWith", "catch", "Root", "className", "Content", "asChild"]
+}

package/dist/lib/neutral/FilePlugin.mjs

@@ -0,0 +1,58 @@
+import "./chunk-J5LGTIGS.mjs";
+
+// src/FilePlugin.tsx
+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";
+
+// raw-loader:/Users/jdw/Code/dxos/packages/plugins/plugin-file/PLUGIN.mdl
+var PLUGIN_default = "---\nid: org.dxos.plugin.file\nname: FilePlugin\nversion: 0.1.0\n---\n\nFilePlugin enables DXOS Composer to store and preview binary files \u2014 images, videos, and PDFs \u2014 as first-class ECHO objects.\nUploaded bytes are routed through a pluggable backend system: the built-in `inline` backend serialises the file directly\nonto the ECHO document, while external backends (e.g. WNFS) can be contributed by other plugins.\nA URL-resolver capability lets external-storage backends convert opaque storage URIs into renderable blob, data, or HTTP URLs\nat view time, keeping the ECHO object schema backend-agnostic.\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 FileDataInline\n  desc: File bytes stored directly on the ECHO object.\n  fields:\n    _tag: 'inline'\n    bytes: Uint8Array\n```\n\n```mdl\ntype FileDataExternal\n  desc: File bytes stored outside ECHO; referenced by URL.\n  fields:\n    _tag: 'external'\n    url: string\n    cid?: string             # optional content-addressed identifier\n```\n\n```mdl\ntype FileData\n  desc: Discriminated union of inline and external storage.\n  literals: FileDataInline | FileDataExternal\n```\n\n```mdl\ntype File\n  desc: ECHO object (typename dxos.org.type.file) representing an uploaded binary asset.\n  fields:\n    name?: string\n    type: string             # MIME type\n    size: number             # byte count\n    data: FileData\n    timestamp?: string       # ISO 8601 upload time\n```\n\n```mdl\ntype UploadResult\n  desc: Normalised return value from a Backend.upload call.\n  fields:\n    name: string\n    type: string\n    size: number\n    data: FileData\n```\n\n```mdl\ntype Settings\n  desc: Per-user plugin settings stored in the ECHO space.\n  fields:\n    backend?: string         # active backend id; defaults to 'inline'\n```\n\n## Components\n\n```mdl\ncomponent FilePreview\n  desc: |\n    Renders a File object using the appropriate HTML element for its MIME type.\n    Images use <img>, videos use <video controls>, PDFs use <iframe>, and\n    all other types fall back to a download link.\n  props:\n    type: string             # MIME type\n    url: string              # renderable blob:, data:, or http(s): URL\n  layout: |\n    \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n    \u2502  <img> / <video> / <iframe>  \u2502\n    \u2502  or [Download file] link     \u2502\n    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n```mdl\ncomponent FileInput\n  desc: Drag-and-drop / browse file picker used inside the Create Object form.\n  props:\n    schema: Schema           # effect/Schema with UploadAnnotation on the file field\n  emits:\n    onChange(file: File)\n  layout: |\n    \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n    \u2502  [ Drop file or click here ] \u2502\n    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n```mdl\ncomponent FileSettings\n  desc: Plugin settings panel rendered in the Composer settings surface.\n  props:\n    settings: Settings\n  emits:\n    onSettingsChange(settings: Settings)\n  layout: |\n    \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n    \u2502  Storage backend: [select \u25BC] \u2502\n    \u2502  (one row per registered     \u2502\n    \u2502   backend with description)  \u2502\n    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n```mdl\ncomponent FileArticle\n  desc: |\n    Full-viewport article container rendered for article, section, and slide\n    roles. Resolves a renderable URL from the File object via inline blob\n    conversion or registered UrlResolver capabilities, then delegates to\n    FilePreview. Shows an empty state while the URL is resolving.\n  props:\n    role: AppSurface.Role\n    subject: File\n  layout: |\n    \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n    \u2502                              \u2502\n    \u2502      FilePreview             \u2502\n    \u2502      (fills container)       \u2502\n    \u2502                              \u2502\n    \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n## Operations\n\n```mdl\nop Create\n  key: org.dxos.plugin.file.operation.create\n  desc: |\n    Validates a browser File object (MIME type and size), routes the upload to the\n    active Backend capability, and constructs a File ECHO object from the result.\n    Does not add the object to the space \u2014 callers do that separately.\n  input:\n    file: BrowserFile        # browser File (globalThis.File)\n    db: Database\n  output: { object: File }\n  errors:\n    UnsupportedFileTypeError: MIME type is not image/*, video/*, or application/pdf\n    FileTooLargeError: file exceeds the 4 MB inline limit\n    NoBackendError: no Backend capability is registered\n```\n\n## Features\n\n```mdl\nfeat F-1: File upload\n\n  req F-1.1: Accepted MIME types MUST be image/* (jpg, jpeg, png, gif, webp, svg),\n    video/* (mp4, webm, mov), and application/pdf only.\n\n  req F-1.2: Maximum upload size MUST be 4 MB for the inline backend.\n\n  req F-1.3:\n    when: user submits the Create Object form with a valid file\n    then:\n      - op:Create is invoked with the selected file and active database\n      - the resulting File object is added to the space via SpaceOperation.AddObject\n      - FileUploader capability returns metadata to the caller (name, type, url/cid)\n\n  req F-1.4:\n    when: file MIME type is not accepted\n    then: UnsupportedFileTypeError returned; no ECHO write occurs\n\n  req F-1.5:\n    when: file size exceeds the limit\n    then: FileTooLargeError returned; no ECHO write occurs\n```\n\n```mdl\nfeat F-2: Backend capability system\n\n  req F-2.1: Any plugin may contribute a Backend capability. Multiple backends\n    may be registered simultaneously.\n\n  req F-2.2: The inline backend MUST always be registered by FilePlugin itself.\n    It serialises bytes directly onto the ECHO object.\n\n  req F-2.3: The active backend is determined by Settings.backend. If the\n    configured id is absent or unrecognised, the inline backend is used.\n\n  req F-2.4: A UrlResolver capability allows external backends to convert an\n    opaque storage URI (e.g. wnfs://\u2026) into a renderable URL at view time.\n    FileArticle iterates registered resolvers and uses the first that matches.\n```\n\n```mdl\nfeat F-3: File preview\n\n  req F-3.1: FileArticle MUST resolve a renderable URL before rendering\n    FilePreview. For inline files a blob: URL is created from the stored bytes\n    and revoked on unmount.\n\n  req F-3.2: FilePreview MUST render the appropriate element for each MIME class:\n    image/* \u2192 <img>, video/* \u2192 <video controls>, application/pdf \u2192 <iframe>,\n    other \u2192 <a download>.\n\n  req F-3.3: FileArticle surfaces are registered for article, section,\n    and slide roles so files embed correctly in Markdown and Presenter layouts.\n```\n\n```mdl\nfeat F-4: Markdown integration\n\n  req F-4.1: A Markdown extension contributed at MarkdownEvents.SetupExtensions\n    MUST allow files to be embedded in Markdown documents as inline attachments.\n```\n\n```mdl\nfeat F-5: Settings\n\n  req F-5.1: The Settings panel MUST list all registered backends with their\n    id, display name, and optional description.\n\n  req F-5.2: Selecting a backend MUST persist the choice to Settings.backend\n    via the SettingsAtom capability.\n```\n\n## Acceptance\n\n```mdl\ntest T-1: Upload image inline\n  given: only the inline backend is registered\n  when: user uploads a 1 MB PNG via the Create Object form\n  then:\n    - op:Create returns a File with data._tag === 'inline'\n    - File.type === 'image/png', File.size === byte count\n    - File is added to the space\n```\n\n```mdl\ntest T-2: Reject oversized file\n  given: inline backend registered, 4 MB limit\n  when: user uploads a 5 MB JPEG\n  then:\n    - FileTooLargeError is returned\n    - no File object is created\n    - no ECHO write occurs\n```\n\n```mdl\ntest T-3: Reject unsupported MIME type\n  given: inline backend registered\n  when: user uploads a .zip file\n  then:\n    - UnsupportedFileTypeError is returned\n    - no File object is created\n```\n\n```mdl\ntest T-4: Preview inline image\n  given: a File with data._tag === 'inline' and type === 'image/png'\n  when: FileArticle is rendered\n  then:\n    - a blob: URL is created from File.data.bytes\n    - FilePreview renders an <img> element with that URL\n    - the blob: URL is revoked on unmount\n```\n\n```mdl\ntest T-5: Preview PDF\n  given: a File with type === 'application/pdf' and a resolved HTTP URL\n  when: FilePreview is rendered\n  then: an <iframe> element is rendered with the file URL as src\n```\n\n```mdl\ntest T-6: Backend fallback to inline\n  given: Settings.backend is 'wnfs' but no WNFS backend is registered\n  when: op:Create is invoked\n  then: the inline backend is used and the file is stored inline\n```\n\n```mdl\ntest T-7: External URL resolved by UrlResolver\n  given: a File with data._tag === 'external' and data.url === 'wnfs://cid/file.jpg'\n  and: a UrlResolver capability registered that handles 'wnfs://' URIs\n  when: FileArticle is rendered\n  then:\n    - UrlResolver.resolve is called with the wnfs:// URL\n    - FilePreview receives the resolved renderable URL\n```\n\n```mdl\ntest T-8: No backend error\n  given: no Backend capability is registered\n  when: op:Create is invoked\n  then: NoBackendError is returned\n```\n\n---\n\n## Appendix: Extension Definitions\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\n    literals?: UnionList\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\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\n    state?: FieldMap\n    slots?: FieldMap\n    actions?: ActionMap\n    emits?: EventMap\n    layout?: CodeBlock\n```\n\n```mdl\next op\n  uri: org.dxos.mdl.op@1.0\n  desc: A named operation with typed inputs, outputs, and declared errors.\n  fields:\n    desc?: Prose\n    input?: FieldMap\n    output?: TypeExpr\n    errors?: ErrorMap\n    effects?: EffectList\n    requires?: ServiceList\n    note?: Prose\n```\n";
+
+// src/FilePlugin.tsx
+var 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: PLUGIN_default,
+    mimeType: "application/x-mdl"
+  }
+}), Plugin.make);
+var FilePlugin_default = FilePlugin;
+export {
+  FilePlugin,
+  FilePlugin_default as default
+};
+//# sourceMappingURL=FilePlugin.mjs.map