diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/next-drag.md | 178 |
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. |
