docs: plan browser inbox text file attachments

2026-06-29 09:57:21 +08:00
parent bd7558d2f9
commit 5be14d5ec0
4 changed files with 294 additions and 6 deletions
@@ -0,0 +1,112 @@
+# Browser Inbox Text File Attachment Design
+
+## Purpose
+
+Browser Inbox needs a first file attachment path that uses the current public
+plugin API instead of adding a private core inbox or binary write shortcut. This
+slice supports text file attachments end to end: the browser extension reads a
+user-selected text file, the local receiver publishes a `browser.capture.file`
+event, and Browser Inbox converts the capture into an ordinary workspace file
+through `api.files.writeText`.
+
+Binary attachments remain out of scope until the platform has an explicit
+public binary write API.
+
+## Scope
+
+This slice adds:
+
+- extension protocol support for `kind: "file"`;
+- popup file selection for text files;
+- local receiver validation and event publication for file captures;
+- Browser Inbox storage/rendering of file metadata and text content;
+- a `Create File` conversion action for workspace-scoped text file captures.
+
+It does not add drag-and-drop from web pages, screenshot capture, native download
+interception, binary files, folders, or a core `.verstak/inbox` staging area.
+
+## Capture Contract
+
+The extension sends schema version 1 with a new file object:
+
+```json
+{
+  "schemaVersion": 1,
+  "captureId": "generated-id",
+  "capturedAt": "2026-06-29T00:00:00.000Z",
+  "source": "verstak-browser-extension",
+  "kind": "file",
+  "page": {
+    "url": "https://example.com/current-page",
+    "title": "Current page",
+    "domain": "example.com"
+  },
+  "file": {
+    "name": "notes.txt",
+    "mime": "text/plain",
+    "size": 120,
+    "text": "file contents"
+  },
+  "browser": {
+    "name": "Firefox"
+  }
+}
+```
+
+`file.name` and `file.text` are required for `kind: "file"`. The extension
+limits text content to 2 MB so it stays within the current Files API text-read
+size and avoids turning local receiver events into large binary transport.
+
+## Receiver Event
+
+The desktop receiver accepts `kind: "file"` and publishes
+`browser.capture.file`. The event payload flattens file fields for Browser Inbox:
+
+```js
+{
+  captureId,
+  capturedAt,
+  source,
+  kind: 'file',
+  url,
+  title,
+  domain,
+  fileName,
+  fileMime,
+  fileSize,
+  fileText,
+  browserName
+}
+```
+
+Current workspace annotation continues to work the same as page, selection, and
+link captures.
+
+## Browser Inbox Conversion
+
+Browser Inbox subscribes to `browser.capture.file` and stores file fields in its
+plugin-owned queue. In a workspace view, file captures render a `Create File`
+action.
+
+On success:
+
+- write `<workspaceRootPath>/Files/<safe-file-name>` through
+  `api.files.writeText`;
+- use `{ createIfMissing: true, overwrite: false }`;
+- publish `browser.capture.converted` with `conversionType: "file"` and
+  `filePath`;
+- remove the capture from the queue.
+
+On write failure, Browser Inbox leaves the capture in the queue and renders an
+error status.
+
+## Testing
+
+Required checks:
+
+- browser extension protocol test builds and validates `kind: "file"`;
+- receiver unit test accepts a file capture and publishes
+  `browser.capture.file`;
+- Browser Inbox smoke test verifies `Create File` write path, content, write
+  options, queue removal, converted event, and failure behavior;
+- full repo checks continue to pass for touched repositories.