Files
zeekay 392b23f734 workspace: New evens the columns, a split divides its pane on a new machine
New (shell, desktop, browser, cloud machine, and the host's menu) adds a
column at the end of the top level and gives every column an equal share
(tiles `append`, `balance`); it used to halve the focused pane, so the
third terminal got a quarter of the screen. A pane's own Split right /
Split down, and the bar's, divide that pane alone and, with a launcher,
start a new cloud machine in the new half without asking where. The
picker, where it still shows, offers New machine first.

A divider now drags against its own split's extent (`ratioAt`): read
against the whole box, a nested seam jumped away from the pointer.

The terminal is told Zen Mono first, from one constant.

Claude-Session: https://claude.ai/code/session_015XYKLnBbrbajqj1GpRydF8
2026-11-06 22:46:14 -08:00

342 lines
14 KiB
TypeScript

/**
* A terminal layout, as a value.
*
* A tiled workspace is a TREE, not a list of rectangles. The list is the shape
* that looks easier — every pane carries x/y/width/height — and then it cannot
* answer the one question that matters: close a pane, and who gets the space?
* With boxes you are left recomputing every neighbour and hoping the arithmetic
* closes. With a tree the answer is structural and exact: a pane's space belongs
* to its sibling, so closing it replaces the parent split WITH that sibling and
* nothing else moves.
*
* That is the whole reason for this file. Every operation here is a pure rewrite
* of one tree into another, so the interesting behaviour — split, close, resize,
* the order you sweep through panes in — is decided and tested without a browser,
* a layout engine, or a single pixel.
*
* `row` puts children side by side (the divider is vertical, it moves left/right).
* `col` stacks them (the divider is horizontal, it moves up/down). Those are the
* CSS flex-direction words, chosen so the renderer passes the value straight
* through rather than translating a private vocabulary into the platform's.
*/
export type Dir = 'row' | 'col';
export type Tile =
| { kind: 'pane'; id: string }
/** `ratio` is the fraction of the axis given to `a` (0..1). */
| { kind: 'split'; dir: Dir; ratio: number; a: Tile; b: Tile };
/** Which branch to take at each split, from the root. `[]` is the root itself. */
export type Path = ReadonlyArray<'a' | 'b'>;
/** A layout of one pane. */
export const pane = (id: string): Tile => ({ kind: 'pane', id });
/** How far a divider may be dragged, as a fraction of its axis.
*
* A pane squeezed to nothing is not a layout choice, it is a pane you can no
* longer find or drag back — so the split keeps a floor at both ends and a
* closed pane is the only way to reach zero. */
export const MIN_RATIO = 0.1;
export const MAX_RATIO = 0.9;
export const clampRatio = (r: number): number =>
Number.isFinite(r) ? Math.min(MAX_RATIO, Math.max(MIN_RATIO, r)) : 0.5;
/** Every pane id, left-to-right and top-to-bottom.
*
* This IS the sweep order — the sequence ⌥→ / ⌥← move through, and the order the
* roster lists. It falls out of the tree rather than being tracked beside it,
* which is why moving a pane cannot desynchronise the two. */
export function paneIds(t: Tile): string[] {
return t.kind === 'pane' ? [t.id] : [...paneIds(t.a), ...paneIds(t.b)];
}
export const hasPane = (t: Tile, id: string): boolean => paneIds(t).includes(id);
/** The pane after `id` in sweep order, wrapping. `step` of -1 goes back. */
export function neighbour(t: Tile, id: string, step: 1 | -1): string | null {
const ids = paneIds(t);
const i = ids.indexOf(id);
if (i < 0 || ids.length === 0) return ids[0] ?? null;
return ids[(i + step + ids.length) % ids.length]!;
}
/** Split the pane showing `targetId`, putting `newId` in the fresh half.
*
* The new pane takes the SECOND half so a split reads the way it is drawn: the
* thing you split stays where it was, and the new one appears to its right or
* below. A `targetId` no pane shows leaves the tree untouched — a split has to
* name where it happens, and inventing a location would put a terminal somewhere
* nobody asked for.
*/
export function splitPane(t: Tile, targetId: string, dir: Dir, newId: string): Tile {
if (t.kind === 'pane') {
return t.id === targetId
? { kind: 'split', dir, ratio: 0.5, a: t, b: pane(newId) }
: t;
}
return {
...t,
a: splitPane(t.a, targetId, dir, newId),
b: splitPane(t.b, targetId, dir, newId),
};
}
/** How many members a run of `dir` splits holds. A pane, or a split the other
* way, is one member: it is a box in that run, whatever is inside it. */
const members = (t: Tile, dir: Dir): number =>
t.kind === 'split' && t.dir === dir ? members(t.a, dir) + members(t.b, dir) : 1;
/** Give every member of the root's level an equal share of its axis.
*
* A level is the run of splits that share the root's direction: three columns
* are a split of one against a split of two, and nothing in the tree says they
* are one row except that both splits are `row`. Equal shares are therefore a
* ratio per split, each the fraction of the run's members on its `a` side, and
* the tree keeps its shape — only ratios change, so no pane moves in the DOM.
* A member that is itself split the other way keeps its inside as it was.
*/
export function balance(t: Tile): Tile {
if (t.kind === 'pane') return t;
const dir = t.dir;
const walk = (n: Tile): Tile => {
if (n.kind !== 'split' || n.dir !== dir) return n;
const a = members(n.a, dir);
return { ...n, ratio: a / (a + members(n.b, dir)), a: walk(n.a), b: walk(n.b) };
};
return walk(t);
}
/** Add `newId` as a new column at the end of the top level, and even the level.
*
* This is what New does, as against a split. A split divides the one pane it
* was asked of; New adds to the workspace, so the workspace makes room evenly —
* halving whichever pane happened to be last gave the third terminal a quarter
* of the screen. A layout stacked at the root becomes one column of the two.
*
* The column goes in at the far end of the run, so each seam divides one column
* from the ones after it: dragging the last seam moves the last two columns and
* leaves the others where they are.
*/
export function append(t: Tile | null, newId: string): Tile {
if (!t) return pane(newId);
const end = (n: Tile): Tile =>
n.kind === 'split' && n.dir === 'row'
? { ...n, b: end(n.b) }
: { kind: 'split', dir: 'row', ratio: 0.5, a: n, b: pane(newId) };
return balance(end(t));
}
/** Remove a pane. Its sibling takes the space, which is what a tree is for.
*
* Returns `null` when the last pane goes — an empty layout is a real state (no
* terminals to show) and saying so with `null` is honest, where a tree with a
* zero-size pane in it would be a lie the renderer has to keep re-checking.
*/
export function closePane(t: Tile, id: string): Tile | null {
if (t.kind === 'pane') return t.id === id ? null : t;
const a = closePane(t.a, id);
const b = closePane(t.b, id);
if (a === null) return b; // the sibling is promoted into this split's place
if (b === null) return a;
return { ...t, a, b };
}
/** Set the ratio of the split at `path`. Out-of-range values are clamped. */
export function setRatio(t: Tile, path: Path, ratio: number): Tile {
if (t.kind !== 'split') return t; // a path that outruns the tree changes nothing
if (path.length === 0) return { ...t, ratio: clampRatio(ratio) };
const [head, ...rest] = path;
return head === 'a'
? { ...t, a: setRatio(t.a, rest, ratio) }
: { ...t, b: setRatio(t.b, rest, ratio) };
}
/** Keep only panes whose id still exists, and drop the layout when none do.
*
* A layout outlives the sessions in it: it is restored from storage into a page
* whose terminals have since ended, and a pane pointing at a session that is gone
* frames a tunnel that stopped answering. Reconciling on load — rather than
* rendering a dead frame and waiting for someone to notice — is the difference
* between a saved layout and a stale one.
*/
export function retain(t: Tile, live: ReadonlySet<string>): Tile | null {
if (t.kind === 'pane') return live.has(t.id) ? t : null;
const a = retain(t.a, live);
const b = retain(t.b, live);
if (a === null) return b;
if (b === null) return a;
return { ...t, a, b };
}
// ---- derived geometry ------------------------------------------------------
//
// The tree is the MODEL; rectangles are output. Deriving them here — rather than
// nesting the panes in the DOM the way they nest in the tree — is what keeps a
// terminal alive across a split.
//
// Nested flex boxes are the obvious rendering, and they reload every terminal
// the moment you split one: a pane that changes position in the React tree is a
// new element, so its <iframe> is torn down and its shell reconnects from
// scratch. A multiplexer whose panes reset when you rearrange them is not a
// multiplexer. So the panes render as ONE flat list that never reorders, each
// positioned absolutely from the numbers below — the DOM order stays fixed, the
// iframes stay mounted, and only their coordinates change.
/** A pane's box, in percent of the container. */
export interface Rect {
id: string;
left: number;
top: number;
width: number;
height: number;
}
/** A divider's box, plus what to resize when it is dragged. */
export interface Divider {
path: Path;
dir: Dir;
left: number;
top: number;
width: number;
height: number;
/** Where the split it resizes starts on its axis, and how long it is, in
* percent. A nested split's ratio is a share of ITS extent, not of the
* container's, so a drag is read against these. */
from: number;
size: number;
}
/** The ratio a divider takes when dragged to `at`, a percent of the container
* along the divider's axis. */
export const ratioAt = (d: Pick<Divider, 'from' | 'size'>, at: number): number =>
d.size > 0 ? (at - d.from) / d.size : 0.5;
export interface Geometry {
rects: Rect[];
dividers: Divider[];
}
/** Project a layout onto the unit square, in percent. */
export function geometry(t: Tile): Geometry {
const rects: Rect[] = [];
const dividers: Divider[] = [];
const walk = (n: Tile, path: Path, left: number, top: number, w: number, h: number) => {
if (n.kind === 'pane') {
rects.push({ id: n.id, left, top, width: w, height: h });
return;
}
const r = clampRatio(n.ratio);
if (n.dir === 'row') {
const aw = w * r;
walk(n.a, [...path, 'a'], left, top, aw, h);
walk(n.b, [...path, 'b'], left + aw, top, w - aw, h);
// The divider straddles the seam; its thickness is the renderer's, so it
// is given a zero extent on the axis it splits and offset in CSS.
dividers.push({ path, dir: n.dir, left: left + aw, top, width: 0, height: h, from: left, size: w });
} else {
const ah = h * r;
walk(n.a, [...path, 'a'], left, top, w, ah);
walk(n.b, [...path, 'b'], left, top + ah, w, h - ah);
dividers.push({ path, dir: n.dir, left, top: top + ah, width: w, height: 0, from: top, size: h });
}
};
walk(t, [], 0, 0, 100, 100);
return { rects, dividers };
}
/** A DOM order that only ever grows.
*
* The panes render as a flat list whose ORDER decides React's reconciliation, so
* that order must never depend on anything a server sorts. It did: the list came
* straight from the sessions array, which the control plane orders by recency —
* so a session updating its `cwd` could reorder the array, move an iframe among
* its siblings, and remount every terminal on the page. The invariant this file
* exists to protect was being broken by the thing it was protecting.
*
* Appending new ids and never moving or removing an existing one makes the order
* a fact about THIS browser session rather than about the server's opinion.
*/
export function stableOrder(prev: readonly string[], present: readonly string[]): string[] {
const seen = new Set(prev);
const added = present.filter((id) => !seen.has(id));
return added.length === 0 ? (prev as string[]) : [...prev, ...added];
}
// ---- the phone projection ---------------------------------------------------
//
// A phone does not tile side by side. 390px cannot hold two terminals and stay
// legible — Blink, Termius and Prompt all refuse to, and none of them is short of
// design effort. What a phone HAS is 844px of height and a swipe.
//
// So the same tree is projected differently rather than modelled twice: a `row`
// split (side by side) becomes two PAGES you swipe between, and a `col` split
// (stacked) stays stacked, because vertical space is the space a phone has. The
// renderer is unchanged — it still consumes `Rect[]`.
export interface PageGeometry extends Geometry {
/** How many pages the layout occupies. `left` is `page * 100 + offset`. */
pages: number;
/** Which page each pane is on, for the tab strip. */
page: Record<string, number>;
}
/**
* Project a layout onto N pages of the unit square.
*
* `maxStack` bounds how many panes may share one page's height; a `col` group
* deeper than that spills onto the next page rather than rendering slivers.
*/
export function pageGeometry(t: Tile, maxStack: number): PageGeometry {
const rects: Rect[] = [];
const dividers: Divider[] = [];
const page: Record<string, number> = {};
const cap = Math.max(1, maxStack);
let next = 0;
/** How many panes a subtree wants to stack, if it were all on one page. */
const stackDepth = (n: Tile): number =>
n.kind === 'pane' ? 1 : n.dir === 'col' ? stackDepth(n.a) + stackDepth(n.b) : 1;
const place = (n: Tile, path: Path, pg: number, top: number, h: number) => {
if (n.kind === 'pane') {
rects.push({ id: n.id, left: pg * 100, top, width: 100, height: h });
page[n.id] = pg;
return;
}
if (n.dir === 'row') {
// Side by side does not fit: each half becomes its own page.
place(n.a, [...path, 'a'], pg, top, h);
place(n.b, [...path, 'b'], next++, 0, 100);
return;
}
// Stacked, at its ratio — unless the stack is deeper than the page allows.
if (stackDepth(n) > cap) {
place(n.a, [...path, 'a'], pg, top, h);
place(n.b, [...path, 'b'], next++, 0, 100);
return;
}
const r = clampRatio(n.ratio);
const ah = h * r;
place(n.a, [...path, 'a'], pg, top, ah);
place(n.b, [...path, 'b'], pg, top + ah, h - ah);
dividers.push({ path, dir: 'col', left: pg * 100, top: top + ah, width: 100, height: 0, from: top, size: h });
};
next = 1;
place(t, [], 0, 0, 100);
return { rects, dividers, pages: Math.max(next, 1), page };
}
/** How many panes may share one phone page, from the room actually available.
*
* Derived, not decreed: the legibility floor is ~20 rows, which at 13px mono plus
* a header is about 260px. A 844px phone therefore holds two; in landscape it
* holds one, which is the honest answer rather than three slivers. */
export const stackFor = (availableHeight: number): number =>
Math.min(3, Math.max(1, Math.floor(availableHeight / 260)));