summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/next-drag.md178
1 files changed, 178 insertions, 0 deletions
diff --git a/docs/next-drag.md b/docs/next-drag.md
new file mode 100644
index 00000000..d217bf94
--- /dev/null
+++ b/docs/next-drag.md
@@ -0,0 +1,178 @@
+# drag: panes and columns between windows, the window by its tagline
+
+> Web browsers open a new window when you drag a tab outside the window, we
+> should have this with panes and columns. They also let you drag the
+> window by dragging on a empty space near the tabs, we should do this when
+> the user drags some empty space on the window tagline. Also it should
+> take columns/panes from one window to another like web browsers do too.
+
+Three changes on the converge head (`oqolqlko`), cheapest first:
+`drag 1/3` (urzqmmmy), `drag 2/3` (xpxquklp), `drag 3/3` (xyxunnrn).
+
+## How windows relate (what the design stands on)
+
+One `pardes-gui` process per window, one core each, each a 9P session
+posted in the registry (`$XDG_RUNTIME_DIR/9p/pardes/<pid>`, a symlink to its
+socket, 9p_io.zig `postToRegistry`). Nothing else ties two windows: no
+shared process, no shared memory. So a pane moving between windows is
+serialised (Dump's format, as the brief said) and handed over 9P, and the
+window it goes to is found by asking every registry session.
+
+## As built
+
+### 1. The window dragged by the workspace tag's blank
+
+- `tagline.workspaceBlank(p, col, row, tag_hit)`: true on the workspace
+ tag's row for its inset (the 4 cells left of the text) and for every cell
+ two or more past the end of its text. The gap between two words is not
+ blank; the two cells after the text are kept for the caret, so B1 there
+ still types at the tag's end.
+- `gui.hitTest`, given to `SDL_SetWindowHitTest`: `SDL_HITTEST_DRAGGABLE`
+ on those cells. The compositor moves the window; pardes never sees the
+ press. B2 and B3 there are untouched (SDL takes only the left button).
+- Not in test mode (hidden windows), not attached (`--attach`: the session's
+ tag is another process's; `g.hit_core` is null there).
+
+### 2. A grip let go past the window's edge: a new window
+
+- gui: a button release whose point is outside the window sets
+ `Mouse.outside` (SDL keeps reporting a held button outside the window:
+ Wayland's implicit grab, X11's capture). `col`/`row` stay the last cell
+ inside, so nothing that ignores the flag changes behaviour.
+- `mouse.handleMouse`: a `.move` (pane grip) or `.column_move` (column
+ grip) released outside goes to `Handover.begin` instead of the layout
+ move. Inside the window the grip drag is exactly as before.
+- `src/Handover.zig` (`Pardes.handover`), the core half: the pane with the
+ panes attached to it (an attachment dragged alone goes alone, unattached),
+ or the column, is dumped alone: `dump.dumpBytes(p, keep, carried)`, which
+ `dumpState` now calls with no mask; `State.carried` (`pane`/`column`)
+ marks such a dump. Each carried pane's serial and `File.revision` is
+ recorded, the effect `hand_over` emitted, the message row says "to a new
+ window…".
+- The host half (gui `handOver`): the dump goes to
+ `$XDG_RUNTIME_DIR/pardes-handover-<pid>-<seq>.zon` (0600) and a detached
+ thread (`Handover.carry`) double-forks this program as
+ `pardes-gui -l <dump> --geometry=WxH` (the source window's size; `+X+Y`
+ at the pointer where SDL can place windows), in its own session, so it
+ outlives the source and leaves no zombie. It waits (up to 15 s) for the
+ child's registry entry to answer `status`; the child reads the dump before
+ it listens (gui.localSession), so then the file is removed and `handed`
+ is posted into `host_io.Inbox`.
+- `Handover.finish`: taken, each carried pane is closed with
+ `Pardes.removePane` (Del's rows rule: its rows go to its neighbour; a
+ carried column's empty column is dropped); a pane whose revision changed
+ since the dump is kept, unattached ("copied to …; edited on the way, kept
+ here too"). Refused or failed: everything stays, the reason on the
+ message row. One handover flies at a time.
+- New option `--geometry=WxH[+X+Y]` (main.zig, `Options.geometry`).
+
+### 3. A grip let go over another pardes window: it goes there
+
+- `/status` gains `pointer in|out` in a window host (`Pardes.windowed`, set
+ by the gui; a terminal's mouse reports never say the pointer left, so a
+ tty session would claim it for ever and says nothing).
+- Before spawning, the worker asks every registry session but its own
+ (skipped by the socket its entry links to) for `status`, up to 10 rounds
+ 40 ms apart while any answers with a `pointer` line at all. The one saying
+ `in` is written `adopt <dump>` on its root ctl.
+- `adopt` (ninep/ctl.zig) is a window's word to a window, as `size` is a
+ frontend's: no builtin, nothing in Help. `Handover.adopt` restores the
+ dumped panes into free slots and places them where the pointer is: a
+ pane goes right under the group the pointer is over, out of that group
+ owner's rows alone (the owner keeps its rows down to the pointer's row;
+ over one of its attachments, half); a column goes beside the column the
+ pointer is over, out of that column's width alone (`insertColumn`). Every
+ other pane's rect is unchanged (tested). The ctl write is answered after
+ the panes are in, so the source closes its pane only once the target has
+ it; a refusal (`NoRoom`, `TooManyPanes`, `NotText`) keeps it in the source
+ and opens no new window: the user aimed at a window.
+
+## What each platform allowed
+
+| | Wayland (Halley 0.8, this desktop) | X11 | macOS | tty |
+|---|---|---|---|---|
+| move by the tag (SDL hit test) | yes, `xdg_toplevel.move`; tried live | `_NET_WM_MOVERESIZE` (untested) | SDL's own (not wired: macos.zig is its own root) | no: the window is the terminal's |
+| release outside the window seen | yes (implicit grab) | yes (SDL auto-capture) | yes in SDL | no: mouse reports clamp to the grid |
+| new window at the pointer | no: no client positions a toplevel; Halley put it on top of the old one's place | `--geometry=+X+Y` from `SDL_GetGlobalMouseState` (untested) | — | — |
+| the window under the pointer | no global pointer, no window positions: asked of each window instead (`pointer in`) | geometry would work too; the same ask is used | — | never a target (no pointer line) |
+
+What SDL did not allow: a move that starts after a drag threshold (there is
+no `SDL_StartWindowMove`; the hit test answers on the press, so a B1 click
+on the blank no longer reaches pardes); being a drag-and-drop *source*
+(SDL 3 is a drop target only), which is what would have let the compositor
+tell the receiving window directly and draw the pane under the pointer
+between the windows; any drawing outside the window while the grip is out.
+
+## Measured (Debug, hidden PARDES_TEST windows, .scratch/e2e.py)
+
+| what | time |
+|---|---|
+| release over B → the pane closed in A (adopt answered) | 55, 58 ms |
+| release outside, no other window → new window up, pane closed in A | 407, 450 ms |
+| release outside, other windows not under the pointer | + up to 10×40 ms asking (estimated, not measured) |
+
+Live on the desktop: step 1 (a window moved ~370 px), step 2 twice (the
+last pane out: the old window closes; a.txt with an unsaved line: dirty in
+the new window, disk untouched, the dump file gone). Step 3 headless only:
+the author was using the desktop and the field panned under my pointer.
+
+## Open questions and positions
+
+1. **B1 on the blank is the compositor's.** Position: keep it, with the two
+ caret cells. A click there used to start typing at the tag's end, which
+ the caret cells still do; the inset (cells 0-3) did nothing before. The
+ alternative (only the inset, or Alt+drag) keeps every click but is not
+ what browsers do and the inset is narrow.
+2. **Terminals do not travel.** The shell is the source process's child;
+ the pane dies with it. Passing the pty master over `SCM_RIGHTS` would
+ keep the program running in the other window, but its exit status is
+ lost to the new owner (it cannot waitpid a non-child). Position: refuse
+ (as built) until someone wants it; an idle shell could be re-spawned in
+ its cwd with its scrollback, which Restore already does.
+3. **PDFs and images do not travel.** Dump/Restore handle them; `adopt`
+ restores file panes only. Position: cheap to add, left out to keep the
+ receiving side one restore path.
+4. **Undo history stays behind** (Dump does not carry it; acme's dump does
+ not either). The text, dirty state, dot and tag tail travel.
+5. **The last pane out closes its window** (removePane's `quitEmpty`): what
+ a browser does when its last tab leaves. Position: keep, it is right.
+6. **Where it lands in the target.** Under the pane the pointer is over,
+ from the pointer's row (acme's movePane split). Position: right for a
+ pane; a drop on a column's tag could mean "top of this column", not done.
+7. **No drop preview.** The target does not know a drag is under way (no
+ DnD), so it cannot show the guide row until the release. Position: the
+ source could announce a flying handover over 9P (`status`: `drag`) and
+ every window show the guide where its pointer is; worth one more step.
+8. **Path, not bytes.** `adopt` names a file on this machine; a registry
+ session is local by definition, so it is enough. A mounted remote
+ session (tcp, quic) would need the zon in the write.
+9. **Asking every window on each drop-out.** Reading the user's other
+ sessions' `status` is harmless (read-only), but an old pardes answers
+ none and a hung one costs its 2 s budget on the worker. Position: fine.
+10. **The `adopt` read is on the 9P task** (`ponytail:` in ctl.zig).
+
+## Rough
+
+- One handover at a time; a second grip let go outside while one flies is
+ refused with a message.
+- An edit made during the ~50-400 ms flight leaves a copy in both windows.
+- The new window inherits the source's environment: launched from a pardes
+ shell, it has that shell's `PARDES_*` (`-l` makes it a new session, so
+ nothing is forwarded, but its own panes overwrite them anyway).
+- `--geometry` and the hit test on X11 and macOS are untested.
+- Not changed: docs (prototype); /status's new line is undocumented in
+ reference.typ.
+
+## Tests
+
+`the workspace tag is blank left of its text and past its end, and nowhere
+else` (tagline.zig); `a grip let go past the window's edge dumps its pane
+alone, and closes it only once another window has it`, `a pane edited while
+it is on its way to another window stays here too`, `a terminal's grip let
+go past the edge stays`, `a pane let go over another window goes under the
+pane the pointer is over, out of its rows alone, unsaved text and all` (the
+layout invariant), `a column let go over another window goes beside the
+column the pointer is over, out of its width alone` (Handover.zig); the
+status test updated (ctl.zig). Run with `-Dtest-filter`; `dump`, `restore`,
+`wire`, `grip` filters pass but for the baseline's known "tagline pointer
+mapping retains physical grips". gui and tty builds compile.