Clipboard model for file operations

[crftwr]

Summary

I'd like to discuss adding a clipboard model to XeFM — cut / copy / paste with a
pending state — as a second, permanent transfer path alongside the existing
C / M keys.

To be clear up front about what this is not: C and M (immediate transfer to
the opposite pane) are the expected behaviour of a two-pane file manager and will
remain the standard operation for experienced users. Nothing about them changes,
and they are not deprecated by this proposal.

The clipboard started as a sub-problem of #263 (beginner keybindings), but it
turned out to be the larger idea, so it deserves its own thread.

Why this is worth doing on its own merits

Three reasons that have nothing to do with beginner keybindings:

1. It expresses something two panes cannot. Copying to a third location, or
   collecting files from several directories before placing them, has no
   representation in the source/destination model.
2. It is the natural transport for Explorer / Finder interop. Users already
   expect to copy files in XeFM and paste them into another application, and vice
   versa.
3. The destructive step moves to where the user is standing. More on this
   below.

The boundary between the two models

If both paths exist permanently, they must not look like "two ways to do the same
thing". I think the honest distinction is what kind of destination each one names:

	C / M	Clipboard
Destination	Spatial — the opposite pane, visible right now	Temporal — wherever I go next
Steps	One, immediate	Two, with a pending state
Scope	The two open panes	Anywhere, including other applications

If we ever find ourselves explaining both as "copy", the design has failed.

A useful consequence: because a safe, deliberate path exists separately, C and
M can stay fast. There is no need to add friction to them in the name of
safety — arguably the opposite.

Safety

The clipboard model splits a transfer into two phases where the first phase is
free:

• C today: pressing it commits a transfer to a destination determined by pane
  state the user may not have been attending to.
• Clipboard: pressing copy touches nothing on disk. It is a pure state change.
  The destructive step happens at paste, by which point the user is standing in
  the destination.

Note this does not address bare K (delete) or M (move). Accidental
single-key invocation is a separate problem from the transfer model, and is
better handled in #263.

Visibility (this is the interesting part)

There is a real weakness in existing file managers here. Finder shows nothing at
all when files are on the clipboard. Explorer ghosts cut items, but only inside
the window they were cut from. In both cases the state is visible where you
already know it (the source folder) and invisible where you need to decide
(the destination).

An invisible clipboard is arguably less safe than immediate transfer, because
the user is acting on state they cannot see. So visibility is a requirement here,
not polish.

XeFM has three distinct surfaces, and they map cleanly onto three different jobs:

1. What I am carrying — the StatusBar (global bottom row), left segment.
Location-independent, exactly like the state it represents. There is only one
StatusBar, which is the right cardinality. Something like [CUT 3] /
[COPY 3] — plain text rather than emoji, since the bar is a single line and
ambiguous-width characters make the measurement fragile.

Shown only when non-empty, so it never becomes wallpaper.

2. What happens if I paste here — the pane footers.
This is per-pane, and the pane footer already is. Both panes can show their own
preview simultaneously (e.g. "1 name conflict"), which is something a
single-window file manager structurally cannot offer. XeFM already has conflict
resolution in the copy engine; this surfaces it before the operation rather
than during it.

3. Which visible rows belong to the clipboard — row marking.
Auxiliary only. This is the Explorer failure mode if relied on as the primary
indicator, since it disappears the moment you navigate away. Mechanically it is
nearly free — the same shape as search_matches in file_pane.py, with
_dim_ink for cut rows.

Two implementation notes:

• The i-search bar currently replaces the StatusBar contents entirely. "Search for
  the destination, then paste" is a plausible flow, so the left segment needs to
  survive an open search.
• The pane footer redraws every frame — this is why disk usage is cached behind a
  TTL. Conflict detection must be computed on clipboard change and directory
  change, not per frame.

Staleness: file_monitor already exists, so clipboard entries whose files
have been moved or deleted can be marked stale rather than failing at paste time.

OS interoperability

XeFM would end up holding two clipboards, and they are not subsets of each
other:

• Internal — can represent things the OS clipboard cannot: S3 paths, entries
  inside archives, remote schemes.
• OS — can represent things XeFM does not have: files copied in Finder or
  Explorer. Also silently overwritten by other applications.

Rather than resolving this invisibly by sequence number, I suggest showing the
origin: "3 items from Finder" and "3 items from XeFM (includes S3)" genuinely
behave differently on paste. The ambiguity becomes explainable UI instead of
hidden state.

The good news is how little new logic this needs. The data paths already exist as
drag-and-drop:

• Paste-in is _on_drop: read-only archive refusal, virtual pane refusal,
  same-directory skip, the shared copy engine with confirmation and conflict
  resolution — all present.
• Copy-out is the path collection in _start_drag, including the local-only
  filter.

What is missing is a PuiKit primitive. panel.set_clipboard() is text-only;
there is no file clipboard (CF_HDROP / NSPasteboard). It would be close in
shape to the existing begin_file_drag. Worth noting that a Windows
implementation would share the shell data object with drag-out, which is
currently unimplemented there.

Terminal mode

Splitting this cleanly:

• The internal clipboard works fully in the TUI. It is application state, so
  it also covers remote and archive entries.
• OS interop is GUI-only, and this is not a parity failure. For a terminal
  session over SSH, "the OS clipboard" belongs to a different machine and has no
  meaningful relationship to the files being managed.

The principle I would suggest writing down: parity of capability, not parity of
keys or of OS integration.

Suggested staging

These are separable and can land independently:

1. Internal clipboard model — state, visibility, actions. TUI and GUI, all
   path schemes. Delivers value alone.
2. PuiKit OS file clipboard primitive — GUI backends; shares Windows shell
   work with drag-out.
3. Keybindings — including the beginner preset in Beginner keybinding (e.g. Cmd/Ctrl-C for Copy) #263. Note that "natural"
   is platform-specific here: Windows uses Ctrl-C/X/V with the move deferred to
   paste time, while Finder has no cut for files at all (Cmd-C then Cmd-Opt-V).

Open questions

• Does the clipboard get a surface in the expert keymap, or only in modifier
  chords? The "copy to a third location" advantage only exists if the actions
  are reachable from the letter-key keymap. If the clipboard lives only in
  Ctrl/Cmd chords, it is a beginner feature and that advantage disappears.
• Lifetime. Explorer consumes cut state on paste and keeps copy state. Does
  XeFM follow that? Is there an explicit clear?
• Should paste always confirm, or only when there are conflicts?

---

Follow-up comment

A note on how this relates to #263, since that's where this started.

If C / M remain the standard expert operation, then a beginner keymap has a
responsibility beyond being familiar: it has to lead somewhere. The failure
mode is a user who works entirely in Ctrl-C / Ctrl-V, never discovers the
two-pane operations, and concludes that XeFM is a slower Explorer. Since the
two-pane speed is the actual differentiator, that would be a quiet but real loss.

The mechanism can be light — surfacing the opposite-pane operation in the log or
hint line after a successful paste is probably enough. But I think the intent is
worth stating explicitly in the preset's design: beginner mode is a ramp, not a
destination.