feat: file-promise drops land — the screenshot thumbnail reaches the board (goal 0256) (#534)

A drag whose pasteboard carries only a file PROMISE (macOS's
post-screenshot floating thumbnail, an image dragged out of a browser
page) was refused before Mill saw it: the windowing toolkit's darwin
drag view registers NSFilenamesPboardType only, so AppKit showed the
no-entry cursor. No upstream support exists in v2 or v3.

Mill-side receiver, no fork: MillFilePromiseDropView (windowing
adapter, the sole toolkit port) registers NSFilePromiseReceiver's own
readableDraggedTypes and sits BELOW every existing subview -- AppKit
targets the frontmost registered candidate, so any drag carrying real
filenames keeps matching the toolkit's own view exactly as before,
untouched by construction. Receipt materializes each promised file
into a per-drop temp dir on a background queue; one exported Go
callback delivers paths + the drop point, and WireFileDropWindow
emits the same file-drop event with empty context. The frontend's two
drop consumers resolve that empty context by DOM hit-test at the drop
coordinates (resolveDropContext, Vitest-pinned), so a promise drop
routes by where it actually landed -- board or card page. The image
landing pipeline already byte-copies into the captures dir, so the
temp file's lifetime never matters downstream.

The attach is main-thread-marshaled (runMainThreadAction) and
fail-safe on a missing window; server/non-darwin builds get a no-op
stub. The real drag gesture is AppKit-session-bound end to end --
testing.md's manual registry carries the installed-build matrix
(thumbnail drag, browser-image drag, and a Finder-file control drag).


Claude-Session: https://claude.ai/code/session_012im1JxQQV2ahnXzZDdVmZq

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: alicoding

.claude/rules/testing.md

@@ -288,9 +288,18 @@ at:
     (clipboard screenshot) → ⌘V on the board lands the image at the
     pointer; Finder ⌘C a .png → ⌘V lands an image object mirroring
     the REAL file path; Finder ⌘C a .md → ⌘V lands a card, same as
-    dropping it. Known-refused, not a defect: dragging the
-    post-screenshot floating thumbnail shows the no-entry cursor
-    (upstream file-promise gap, BACKLOG 0P0-PROMISE).
+    dropping it.
+  - **File-promise drops: the post-screenshot floating thumbnail**
+    (goal 0256, `MillFilePromiseDropView` /
+    `AttachFilePromiseReceiver`) — a promise drag needs a real AppKit
+    drag session end to end; no harness can synthesize one. Verify on
+    an installed build: ⌘⇧4 a region, drag the floating THUMBNAIL
+    (before it saves) onto the board — the image object lands at the
+    drop point, no no-entry cursor; drag an image out of a browser
+    page — same; then drag a real file from Finder and confirm it
+    still lands exactly as before (the promise view sits BELOW the
+    toolkit's own drag view precisely so filename-carrying drags
+    never reroute).
 
 **Tests drive user primitives, not synthetic events.** An interaction
 test reaches behavior through the same primitives a user has — real

frontend/src/atlas/atlasFileDropShared.test.ts

@@ -0,0 +1,57 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { resolveDropContext } from './atlasFileDropShared'
+
+// resolveDropContext (goal 0256): the toolkit's own file-drop event
+// carries a hit-tested context attribute; the file-promise receiver
+// delivers coordinates only, so its empty-context payloads resolve
+// through a DOM hit-test at the drop point instead. The suite runs in
+// the node environment (no DOM package installed -- deliberate), so
+// `document` is stubbed to exactly the two calls the helper makes:
+// elementFromPoint, then closest().getAttribute() on its result.
+function stubDocument(elementAtPoint: unknown) {
+  const elementFromPoint = vi.fn(() => elementAtPoint)
+  vi.stubGlobal('document', { elementFromPoint })
+  return elementFromPoint
+}
+
+function elementInsideTarget(context: string | null) {
+  return {
+    closest: (selector: string) => {
+      if (selector !== '[data-file-drop-context]' || context === null) return null
+      return { getAttribute: () => context }
+    },
+  }
+}
+
+describe('resolveDropContext', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('returns the payload context when the toolkit supplied one, never hit-testing', () => {
+    const elementFromPoint = stubDocument(null)
+    expect(resolveDropContext({ context: 'board', x: 10, y: 10 })).toBe('board')
+    expect(elementFromPoint).not.toHaveBeenCalled()
+  })
+
+  it('hit-tests the drop point when the context is empty, walking up to the declared target', () => {
+    stubDocument(elementInsideTarget('card-page'))
+    expect(resolveDropContext({ context: '', x: 5, y: 5 })).toBe('card-page')
+  })
+
+  it('returns null when the point hits no declared drop target', () => {
+    stubDocument(elementInsideTarget(null))
+    expect(resolveDropContext({ x: 5, y: 5 })).toBeNull()
+  })
+
+  it('returns null when the point hits nothing at all', () => {
+    stubDocument(null)
+    expect(resolveDropContext({ x: 5, y: 5 })).toBeNull()
+  })
+
+  it('returns null without hit-testing when the payload carries no coordinates', () => {
+    const elementFromPoint = stubDocument(null)
+    expect(resolveDropContext({})).toBeNull()
+    expect(elementFromPoint).not.toHaveBeenCalled()
+  })
+})

frontend/src/atlas/atlasFileDropShared.ts

@@ -11,3 +11,17 @@
 export const FILE_DROP_EVENT_NAME = 'atlas-native-file-drop'
 export const FILE_DROP_CONTEXT_BOARD = 'board'
 export const FILE_DROP_CONTEXT_CARD_PAGE = 'card-page'
+
+// resolveDropContext answers WHERE a native drop landed: the payload's
+// own context when the toolkit's attribute hit-test supplied one, else
+// a DOM hit-test at the drop coordinates -- the file-promise receiver
+// (goal 0256) delivers materialized paths plus coordinates but no
+// attribute walk, so its payloads arrive with an empty context. Null
+// when the point hits no declared drop target (the drop is ignored,
+// same as the toolkit answering no attributes).
+export function resolveDropContext(payload: { context?: string; x?: number; y?: number }): string | null {
+  if (payload.context) return payload.context
+  if (payload.x === undefined || payload.y === undefined) return null
+  const el = document.elementFromPoint(payload.x, payload.y)
+  return el?.closest('[data-file-drop-context]')?.getAttribute('data-file-drop-context') ?? null
+}

frontend/src/atlas/useAtlasCardPageFileDrop.ts

@@ -6,7 +6,7 @@ import { AtlasService } from '../shared/bindings'
 import { titleFromFilename } from './atlasCreateHelpers'
 import { freeChildPosition } from './atlasContainmentPlacement'
 import { useAtlasFolderImportRequestStore } from './atlasFolderImportRequest'
-import { FILE_DROP_EVENT_NAME, FILE_DROP_CONTEXT_CARD_PAGE } from './atlasFileDropShared'
+import { FILE_DROP_EVENT_NAME, FILE_DROP_CONTEXT_CARD_PAGE, resolveDropContext } from './atlasFileDropShared'
 
 // The card-foremost half of the native OS file-drop door (D5, LOCKED
 // design): while a card's page is open, a dropped file becomes a
@@ -36,8 +36,9 @@ export function useAtlasCardPageFileDrop({ card, allCards, onSaved, onError }: {
 
   useEffect(() => {
     return Events.On(FILE_DROP_EVENT_NAME, (evt) => {
-      const payload = evt.data as { filenames?: string[]; context?: string } | undefined
-      if (!payload || payload.context !== FILE_DROP_CONTEXT_CARD_PAGE || !payload.filenames?.length) return
+      const payload = evt.data as { filenames?: string[]; x?: number; y?: number; context?: string } | undefined
+      if (!payload || !payload.filenames?.length) return
+      if (resolveDropContext(payload) !== FILE_DROP_CONTEXT_CARD_PAGE) return
       const { card: openCard, allCards: cards, onSaved: saved, onError: fail, requestFolderImport: request } = stateRef.current
 
       AtlasService.ResolveFileDropRoute(payload.filenames)

frontend/src/atlas/useAtlasNativeFileDrop.ts

@@ -6,7 +6,7 @@ import { titleFromFilename } from './atlasCreateHelpers'
 import { refreshAtlas } from './atlasStore'
 import { isExtensionEnabled } from '../shared/extensionEnablementStore'
 import { useAtlasFolderImportRequestStore } from './atlasFolderImportRequest'
-import { FILE_DROP_EVENT_NAME, FILE_DROP_CONTEXT_BOARD } from './atlasFileDropShared'
+import { FILE_DROP_EVENT_NAME, FILE_DROP_CONTEXT_BOARD, resolveDropContext } from './atlasFileDropShared'
 import { frameContainingPoint } from './atlasFramePoint'
 import { extensionOf } from './unitRegistry'
 import { thirdPartyNounForExtension, type ThirdPartyNounShape } from './atlasNounRegistry'
@@ -137,7 +137,8 @@ export function useAtlasNativeFileDrop({ parentID, topLevelBoxes, screenToFlowPo
   useEffect(() => {
     return Events.On(FILE_DROP_EVENT_NAME, (evt) => {
       const payload = evt.data as { filenames?: string[]; x?: number; y?: number; context?: string } | undefined
-      if (!payload || payload.context !== FILE_DROP_CONTEXT_BOARD || !payload.filenames?.length) return
+      if (!payload || !payload.filenames?.length) return
+      if (resolveDropContext(payload) !== FILE_DROP_CONTEXT_BOARD) return
       void landFiles(payload.filenames, { x: payload.x ?? 0, y: payload.y ?? 0 })
         .catch(() => setDropError(t('capture.dropError')))
     })

internal/adapters/windowing/filepromise_darwin.go

@@ -0,0 +1,63 @@
+//go:build darwin && !server
+
+package windowing
+
+/*
+#cgo CFLAGS: -mmacosx-version-min=10.13 -x objective-c
+#cgo LDFLAGS: -framework Foundation -framework AppKit
+
+#include "filepromise_darwin.h"
+*/
+import "C"
+
+import (
+	"sync"
+	"unsafe"
+)
+
+// promiseDropFn holds the one registered promise-drop callback -- a
+// package var, not per-window state, since only the main window is
+// ever wired (the same singular-resource shape clipboard's own
+// selfWriteText carries).
+var (
+	promiseDropMu sync.Mutex
+	promiseDropFn func(paths []string, x, y int)
+)
+
+//export millFilePromiseDropped
+func millFilePromiseDropped(paths **C.char, count C.int, x C.int, y C.int) {
+	n := int(count)
+	goPaths := make([]string, 0, n)
+	for _, p := range unsafe.Slice(paths, n) {
+		goPaths = append(goPaths, C.GoString(p))
+	}
+	promiseDropMu.Lock()
+	fn := promiseDropFn
+	promiseDropMu.Unlock()
+	if fn == nil {
+		return
+	}
+	// The caller is a GCD completion block, not a Go-owned thread --
+	// hop onto a goroutine so the callback can do arbitrary Go work
+	// (event emits, service calls) without holding the C side.
+	go fn(goPaths, int(x), int(y))
+}
+
+// AttachFilePromiseReceiver installs the file-promise drop view on
+// win and registers fn to receive each materialized drop's temp-file
+// paths plus the drop point (top-left webview coordinates, matching
+// the toolkit's own file-drop event). One callback app-wide; the last
+// registration wins. See filepromise_darwin.m's own view comment for
+// why this cannot interfere with ordinary file drops.
+func (win *Window) AttachFilePromiseReceiver(fn func(paths []string, x, y int)) {
+	promiseDropMu.Lock()
+	promiseDropFn = fn
+	promiseDropMu.Unlock()
+	runMainThreadAction("AttachFilePromiseReceiver", func() {
+		// NativeWindow is a stored-pointer read (nil when the window
+		// is destroyed or not yet realized -- the C side guards nil);
+		// read inside the marshal so the attach sees the freshest
+		// window state.
+		C.millAttachPromiseView(win.w.NativeWindow())
+	})
+}

internal/adapters/windowing/filepromise_darwin.h

@@ -0,0 +1,12 @@
+//go:build darwin && !server
+
+#ifndef MILL_FILEPROMISE_DARWIN_H
+#define MILL_FILEPROMISE_DARWIN_H
+
+// Installs the file-promise drop view on the given NSWindow* -- must
+// run on the AppKit main thread (the Go caller marshals through
+// runMainThreadAction). Implementation and design reasoning live in
+// filepromise_darwin.m.
+void millAttachPromiseView(void *nsWindowPtr);
+
+#endif

internal/adapters/windowing/filepromise_darwin.m

@@ -0,0 +1,124 @@
+//go:build darwin && !server
+
+#import <AppKit/AppKit.h>
+#include <stdlib.h>
+#include <string.h>
+#include "filepromise_darwin.h"
+
+// The Go-side receiver (filepromise_darwin.go's //export).
+extern void millFilePromiseDropped(char** paths, int count, int x, int y);
+
+// MillFilePromiseDropView receives FILE-PROMISE drags (the macOS
+// post-screenshot floating thumbnail, a browser image drag) that the
+// toolkit's own drag view structurally refuses -- it registers only
+// NSFilenamesPboardType, so a promise-only pasteboard never matches it
+// (docs/goals/0256). Registration here is promise-types-only, and the
+// view is inserted BELOW every existing subview: AppKit targets the
+// frontmost registered candidate under the pointer, so any drag that
+// carries real filenames keeps matching the toolkit's own topmost view
+// exactly as before -- existing drops are untouched by construction.
+@interface MillFilePromiseDropView : NSView
+@end
+
+@implementation MillFilePromiseDropView
+
+// Mouse events pass through to the webview underneath -- drag delivery
+// uses registerForDraggedTypes, not hitTest (same contract as the
+// toolkit's own drag view).
+- (NSView *)hitTest:(NSPoint)point {
+    return nil;
+}
+
+- (NSDragOperation)draggingEntered:(id<NSDraggingInfo>)sender {
+    return NSDragOperationCopy;
+}
+
+- (NSDragOperation)draggingUpdated:(id<NSDraggingInfo>)sender {
+    return NSDragOperationCopy;
+}
+
+- (BOOL)performDragOperation:(id<NSDraggingInfo>)sender {
+    NSPasteboard *pb = [sender draggingPasteboard];
+    NSArray<NSFilePromiseReceiver *> *receivers =
+        [pb readObjectsForClasses:@[[NSFilePromiseReceiver class]] options:@{}];
+    if (receivers.count == 0) {
+        return NO;
+    }
+
+    NSString *destDir = [NSTemporaryDirectory() stringByAppendingPathComponent:
+        [NSString stringWithFormat:@"mill-promise-drop-%@", [[NSUUID UUID] UUIDString]]];
+    if (![[NSFileManager defaultManager] createDirectoryAtPath:destDir
+                                   withIntermediateDirectories:YES
+                                                    attributes:nil
+                                                         error:nil]) {
+        return NO;
+    }
+    NSURL *destURL = [NSURL fileURLWithPath:destDir isDirectory:YES];
+
+    // Same top-left coordinate math as the toolkit's own drag view --
+    // the frontend hit-tests these against document.elementFromPoint.
+    NSPoint pWin = [sender draggingLocation];
+    NSPoint pView = [self convertPoint:pWin fromView:nil];
+    CGFloat contentHeight = self.window.contentView.frame.size.height;
+    int x = (int)pView.x;
+    int y = (int)(contentHeight - pView.y);
+
+    // Receipt is asynchronous BY the API's own contract (the promise
+    // source writes the file on its own schedule); the reader blocks
+    // run on this background queue, never the main thread, and the
+    // dispatch group fires the one Go callback once every promised
+    // file has either landed or errored.
+    NSOperationQueue *queue = [NSOperationQueue new];
+    dispatch_group_t group = dispatch_group_create();
+    NSMutableArray<NSString *> *landed = [NSMutableArray array];
+    NSLock *lock = [NSLock new];
+    for (NSFilePromiseReceiver *receiver in receivers) {
+        dispatch_group_enter(group);
+        [receiver receivePromisedFilesAtDestination:destURL
+                                            options:@{}
+                                     operationQueue:queue
+                                             reader:^(NSURL *fileURL, NSError *error) {
+            if (error == nil && fileURL != nil) {
+                [lock lock];
+                [landed addObject:fileURL.path];
+                [lock unlock];
+            }
+            dispatch_group_leave(group);
+        }];
+    }
+    dispatch_group_notify(group, dispatch_get_global_queue(QOS_CLASS_USER_INITIATED, 0), ^{
+        NSUInteger count = landed.count;
+        if (count == 0) {
+            return;
+        }
+        char **cArr = (char **)malloc(sizeof(char *) * count);
+        for (NSUInteger i = 0; i < count; i++) {
+            cArr[i] = strdup([landed[i] UTF8String]);
+        }
+        millFilePromiseDropped(cArr, (int)count, x, y);
+        for (NSUInteger i = 0; i < count; i++) {
+            free(cArr[i]);
+        }
+        free(cArr);
+    });
+    return YES;
+}
+
+@end
+
+void millAttachPromiseView(void *nsWindowPtr) {
+    // Fail-safe, never fail-crash: a missing window/contentView means
+    // no promise support this launch, not an abort at startup.
+    if (nsWindowPtr == NULL) {
+        return;
+    }
+    NSWindow *win = (__bridge NSWindow *)nsWindowPtr;
+    NSView *content = win.contentView;
+    if (content == nil) {
+        return;
+    }
+    MillFilePromiseDropView *v = [[MillFilePromiseDropView alloc] initWithFrame:content.bounds];
+    v.autoresizingMask = NSViewWidthSizable | NSViewHeightSizable;
+    [v registerForDraggedTypes:[NSFilePromiseReceiver readableDraggedTypes]];
+    [content addSubview:v positioned:NSWindowBelow relativeTo:nil];
+}

internal/adapters/windowing/filepromise_stub.go

@@ -0,0 +1,9 @@
+//go:build !darwin || server
+
+package windowing
+
+// AttachFilePromiseReceiver is a no-op off macOS and in server mode --
+// file-promise drags are an AppKit-only construct, and server mode has
+// no native window to attach to (filepromise_darwin.go carries the
+// real implementation and the design's own reasoning).
+func (win *Window) AttachFilePromiseReceiver(fn func(paths []string, x, y int)) {}

internal/services/atlassvc/atlasservice_filedrop.go

@@ -320,4 +320,12 @@ func (a *AtlasService) WireFileDropWindow(window *windowing.Window) {
 		}
 		windowing.Emit(FileDropEventName, payload)
 	})
+	// File-PROMISE drags (the post-screenshot floating thumbnail, a
+	// browser image drag -- goal 0256) arrive through Mill's own
+	// receiver with materialized temp-file paths but no attribute
+	// hit-test; Context stays empty and the frontend resolves it from
+	// the drop coordinates (atlasFileDropShared's resolveDropContext).
+	window.AttachFilePromiseReceiver(func(paths []string, x, y int) {
+		windowing.Emit(FileDropEventName, FileDropPayload{Filenames: paths, X: x, Y: y})
+	})
 }