# ADR-0010 — Drop Finder drag-and-drop from v3 scope

**Status:** Accepted
**Date:** 2026-05-05
**Deciders:** JT, Claude (in dialogue)
**Supersedes:** none
**Superseded by:** none

> *This ADR was drafted during the embedded-claude-terminal Phase 11 cleanup commit. It locks in the scope decision made in BUILD_SPEC §4 (item ADR-0007 in spec text; renumbered to 0010 because the repo already has ADRs 0001–0005).*

## Context

The Pasteboard is the buffer of file paths the user assembles before sending them into the embedded Claude session. Three input mechanisms were on the table:

1. **Tree-drag** — drag a file out of console-v2's tree component into the Pasteboard DropZone.
2. **`<input type="file">`** — click "Add Files" and use the OS file picker.
3. **Finder drag-and-drop** — drag a file straight from macOS Finder onto the DropZone.

Tree-drag and the file picker work because the source is either in-app (full path known) or routed through the file picker API (which on Chrome's HTML5 stack returns a `File` object with no `path` attribute exposed to JS — but the OS file picker does surface absolute paths through the File System Access API where available).

Finder drag-and-drop fails differently. When a user drags a file from Finder onto a webpage, Chrome populates `DataTransfer.files` with `File` objects but **does not expose the absolute path**. This is a security boundary: pages can't enumerate the user's filesystem. The File System Access API offers a partial workaround but requires explicit user permission grants per file, doesn't survive page reloads, and has uneven Safari support.

## Decision

Finder drag-and-drop is dropped from v3 scope. The Pasteboard supports tree-drag (in-app) and `<input type="file">` (OS picker) only.

Native helpers (Electron-style native file-path bridge) and progressive use of the File System Access API are tracked in §"Future Work" of the spec for a possible v4 pass.

## Consequences

**Coverage of primary workflow.** JT's working pattern is: review shots in the workspace tree, drag the relevant ones into the Pasteboard, ask Claude to do something with them. Tree-drag covers that path natively. The file picker covers the "I have something on disk that isn't in the tree yet" path.

**Lost edge case.** Dragging a screenshot from the desktop into the chat — a real, occasional pattern — does not work in v3. Users have to use the file picker for off-tree files.

**No security workarounds shipped.** v3 does not ship an Electron wrapper, a native file-path bridge, or per-file File System Access API permission grants. Each of those would have added a maintenance surface for an edge case.

**Scope discipline.** This ADR exists to resist scope creep — the temptation to "just add Finder DnD" repeatedly comes up in chat builds; recording the decision keeps it from re-litigating every phase.

## Alternatives considered

- **File System Access API everywhere.** Rejected — Safari support is incomplete; per-file permission grants don't survive reloads; introduces a permission-prompt surface that erodes the experience.
- **Electron native bridge.** Rejected — couples console-v2 to a desktop runtime; v3 is browser-first.
- **Custom Chrome extension.** Rejected — install friction; not a path JT will adopt.

## Implementation

- `recoil/console-v2/.../Pasteboard.tsx` — tree-drag + `<input type="file">` only. No Finder-DnD listeners.
- BUILD_SPEC §"Future Work" — tracks File System Access API and native-helper paths for a possible v4.

## Verification

Manual: dragging a file from Finder into the Pasteboard produces no Pasteboard entry. Tree-drag and the file picker both produce entries with absolute paths.