@prohost/cli 0.13.3 → 0.15.0

package/dist/codehost/sizing.js

@@ -0,0 +1,434 @@
+/**
+ * Who sizes a Code-thread window on this Mac, and what each viewer is told about it.
+ *
+ * Every viewer of a window — the relay's (a phone, a browser) and the desktop app's — is its own
+ * tmux client, and tmux would size the window to whichever was active last (`window-size latest`):
+ * a phone opening the thread shrank it for the desktop typing in it. Instead every window is sized
+ * with `resize-window` (which makes that window `window-size manual`; never the server's global
+ * option, which tmux 3.4 can't start with), from its creation on, and this module picks one viewer
+ * per window to size it to (the approved policy, CONTRACTS C3):
+ *
+ * - a viewer that attaches, sends `{"type":"claim"}` (a phone on ready / foreground / touch / before
+ *   it types, the desktop's "Use this window's size"), or reports focus (`ESC [ I`: its window came
+ *   to the front) takes it — never a `watch` viewer, which can't type (it sizes a window only
+ *   nobody else shows);
+ * - typing alone takes it only from a sizing viewer idle {@link IDLE_TAKEOVER_MS} (CONTRACTS-R2
+ *   R2): two viewers typing in turn no longer resize the window, and redraw Claude Code's whole
+ *   transcript, on every keystroke;
+ * - when the sizing viewer leaves, the one active most recently among those left takes over;
+ * - a handover or resize reaches tmux once it has been quiet {@link HANDOVER_DEBOUNCE_MS}, and only
+ *   when the size changes: Claude Code reprints its whole transcript on every width change.
+ *
+ * Copy mode (scrolled back) is the PANE's, so one viewer's scroll freezes everyone's view. The pane
+ * leaves it when the sizing viewer changes and when the viewer that scrolled leaves.
+ *
+ * A viewer that said `{"type":"hello","client":{"kind","label"}}` is sent
+ * `{"type":"sizer","kind","label","cols","rows","you","scrolled"}` on attach and whenever the
+ * sizing viewer, its size or the pane's copy mode changes; one that never said hello (an older
+ * page) is never sent one.
+ *
+ * It also holds a new shell's first prompt until the first viewer's size has settled: zsh redraws
+ * its prompt on every resize, so a shell started detached at tmux's 80x24 and then resized by the
+ * page's fit showed one prompt per resize. A held window runs `tmux wait-for <channel>` before its
+ * shell (see {@link holdCommand}); the first viewer's resizes going quiet signals it.
+ */
+import { hasFocusIn, isHumanInput, leaveCopyModeArgs, paneInModeArgs, windowTarget } from './tmux.js';
+export const VIEWER_KINDS = new Set(['phone', 'tablet', 'desktop']);
+const MAX_LABEL_CHARS = 40;
+/** A `hello` frame's `client`, made safe to repeat to another viewer. */
+export function parseViewerClient(raw) {
+    const client = raw && typeof raw === 'object' ? raw : {};
+    const kind = typeof client.kind === 'string' && VIEWER_KINDS.has(client.kind) ? client.kind : 'unknown';
+    const label = typeof client.label === 'string'
+        ? // eslint-disable-next-line no-control-regex
+            client.label.replace(/[\u0000-\u001f\u007f-\u009f]/g, '').trim().slice(0, MAX_LABEL_CHARS)
+        : '';
+    return { kind, label: label || null };
+}
+/** Window option set on a window created holding its shell; cleared when it is released. */
+export const HOLD_OPTION = '@prohost_held';
+/** Quiet time after the first viewer's last resize before a held shell starts. */
+export const SETTLE_MS = 250;
+/** A held shell starts at most this long after its first viewer attached, resizes or not. */
+export const SETTLE_MAX_MS = 2_000;
+/** A handover or resize is applied once quiet this long (each width change makes Claude Code reprint). */
+export const HANDOVER_DEBOUNCE_MS = 300;
+/** After input that may enter or leave copy mode, the pane is asked once it has been quiet this long. */
+export const MODE_CHECK_MS = 150;
+/** A held shell nobody attached to starts anyway after this long. */
+export const HOLD_FALLBACK_MS = 60_000;
+/** Typing takes the window's size from a sizing viewer that hasn't typed or claimed for this long. */
+export const IDLE_TAKEOVER_MS = 30_000;
+export function holdChannel(name) {
+    return `prohost-hold-${name}`;
+}
+/**
+ * `command`, run once the window's hold is released. Waits on the tmux server the pane runs in
+ * (`$TMUX`); without a reachable tmux the wait fails at once and the shell starts unheld. A
+ * signal sent before the wait began is kept by tmux, so the order can't strand it.
+ */
+export function holdCommand(name, command) {
+    return `tmux wait-for ${holdChannel(name)} 2>/dev/null; ${command}`;
+}
+/** Signal the hold, only while the window still carries {@link HOLD_OPTION} (tmux keeps a signal nobody waits for). */
+export function releaseHoldArgs(name) {
+    const target = windowTarget(name);
+    return ['if-shell', '-F', '-t', target, `#{${HOLD_OPTION}}`, `wait-for -S ${holdChannel(name)} ; set-option -wu -t ${target} ${HOLD_OPTION}`];
+}
+export function resizeWindowArgs(name, cols, rows) {
+    return ['resize-window', '-t', windowTarget(name), '-x', String(cols), '-y', String(rows)];
+}
+/**
+ * The size a window created next starts at — only while no client is attached to the server
+ * (tmux picks a new window's size from its global `window-size`); {@link resizeWindowArgs} right
+ * after `new-window` is what holds whatever is attached.
+ */
+export function defaultSizeArgs(cols, rows) {
+    return ['set-option', '-g', 'default-size', `${cols}x${rows}`];
+}
+function defaultTimer(fn, ms) {
+    const timer = setTimeout(fn, ms);
+    timer.unref?.();
+    return () => clearTimeout(timer);
+}
+const key = (size) => `${size.cols}x${size.rows}`;
+export class TerminalSizing {
+    options;
+    windows = new Map();
+    nextId = 1;
+    seq = 0;
+    last;
+    setTimer;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.setTimer = options.setTimer ?? defaultTimer;
+        this.now = options.now ?? Date.now;
+        this.last = options.defaultSize ?? { cols: 120, rows: 32 };
+    }
+    /** The size a window was last sized to: what a window created with nobody watching starts at. */
+    lastSize() {
+        return { ...this.last };
+    }
+    state(name) {
+        let state = this.windows.get(name);
+        if (!state) {
+            state = { viewers: new Map(), settled: false, scrolled: false, maybeScrolled: false };
+            this.windows.set(name, state);
+        }
+        return state;
+    }
+    /**
+     * A window was just created (and resized to its first size). `held`: it runs
+     * {@link holdCommand} and carries {@link HOLD_OPTION}; its first viewer settling releases it, or
+     * {@link HOLD_FALLBACK_MS}.
+     */
+    created(name, options = {}) {
+        // The same state object: viewers already attached hold it.
+        const state = this.state(name);
+        state.cancelSettle?.();
+        state.cancelFallback?.();
+        state.cancelSettle = undefined;
+        state.cancelFallback = undefined;
+        state.settled = false;
+        state.settleDeadline = undefined;
+        state.scrolled = false;
+        state.maybeScrolled = false;
+        // Not taken as applied: the first owner's resize-window confirms it, a no-op (no SIGWINCH)
+        // when the window already has that size.
+        state.applied = undefined;
+        if (options.held)
+            state.cancelFallback = this.setTimer(() => void this.release(name, state), HOLD_FALLBACK_MS);
+        // Somebody already shows it (a window re-created under them): sized to them, and settled from now.
+        if (state.owner !== undefined) {
+            this.apply(name, state);
+            this.settle(name, state);
+        }
+    }
+    /**
+     * A window an earlier daemon made, found by `adopt`: it may still hold its shell (that daemon's
+     * timer died with it). Released after {@link HOLD_FALLBACK_MS} unless a viewer settles it first;
+     * the release is a no-op on a window that isn't held. Once per window per daemon.
+     */
+    adopted(name) {
+        if (this.windows.has(name))
+            return;
+        const state = this.state(name);
+        state.cancelFallback = this.setTimer(() => void this.release(name, state), HOLD_FALLBACK_MS);
+    }
+    /** Whether the pane may be in copy mode now (as read, or since input that may have entered it). */
+    mayBeScrolled(name) {
+        const state = this.windows.get(name);
+        return Boolean(state && (state.scrolled || state.maybeScrolled));
+    }
+    /** The pane just left copy mode (its keystroke or a relayed reply cancelled it): every viewer hears. */
+    leftCopyMode(name) {
+        const state = this.windows.get(name);
+        if (!state)
+            return;
+        state.cancelModeCheck?.();
+        state.cancelModeCheck = undefined;
+        state.maybeScrolled = false;
+        state.scroller = undefined;
+        if (state.scrolled) {
+            state.scrolled = false;
+            this.broadcast(state);
+        }
+    }
+    join(name, size) {
+        const state = this.state(name);
+        const viewer = {
+            id: this.nextId++,
+            cols: size.cols,
+            rows: size.rows,
+            watch: size.watch === true,
+            activeAt: ++this.seq,
+            inputAt: this.now(),
+        };
+        state.viewers.set(viewer.id, viewer);
+        // Attaching claims the size, as tmux did (`window-size latest`): a watch viewer only a window
+        // nobody else shows.
+        const ownerHere = state.owner !== undefined && state.viewers.has(state.owner);
+        if (!ownerHere || !viewer.watch)
+            this.handOver(name, state, viewer);
+        // The first viewer this daemon has seen on it: a shell held for it starts once its size settles
+        // (a window an earlier daemon held too: the release is a no-op on a window that isn't).
+        if (!state.settled)
+            this.settle(name, state);
+        let left = false;
+        return {
+            hello: (client) => {
+                if (left)
+                    return;
+                viewer.client = client;
+                viewer.lastSent = undefined;
+                // The sizing viewer's name changed for everyone; anyone else just learns who sizes it.
+                if (state.owner === viewer.id)
+                    this.broadcast(state);
+                else
+                    this.send(state, viewer);
+            },
+            resize: (cols, rows) => {
+                if (left || (viewer.cols === cols && viewer.rows === rows))
+                    return;
+                viewer.cols = cols;
+                viewer.rows = rows;
+                if (state.owner !== viewer.id)
+                    return;
+                this.apply(name, state);
+                this.broadcast(state);
+                if (!state.settled)
+                    this.settle(name, state);
+            },
+            claim: () => {
+                if (left || viewer.watch)
+                    return;
+                viewer.inputAt = this.now();
+                if (state.owner === viewer.id)
+                    return;
+                this.handOver(name, state, viewer);
+            },
+            typed: () => {
+                if (left || viewer.watch)
+                    return;
+                const now = this.now();
+                viewer.inputAt = now;
+                if (state.owner === viewer.id)
+                    return;
+                const owner = state.owner === undefined ? undefined : state.viewers.get(state.owner);
+                // The sizing viewer is at it too: its size stays until it goes quiet, or this one asks.
+                if (owner && now - owner.inputAt < IDLE_TAKEOVER_MS)
+                    return;
+                this.handOver(name, state, viewer);
+            },
+            scrolled: (moved = true) => {
+                if (left)
+                    return;
+                if (moved) {
+                    state.scroller = viewer.id;
+                    state.maybeScrolled = true;
+                }
+                this.checkMode(name, state);
+            },
+            isScroller: () => !left && state.scroller === viewer.id,
+            leave: () => {
+                if (left)
+                    return;
+                left = true;
+                viewer.listener = undefined;
+                state.viewers.delete(viewer.id);
+                // The one who scrolled everyone's view back is gone: nobody is left reading that scrollback.
+                if (state.scroller === viewer.id)
+                    void this.leaveCopyMode(name, state);
+                if (state.owner !== viewer.id)
+                    return;
+                let next;
+                for (const other of state.viewers.values())
+                    if (!next || other.activeAt > next.activeAt)
+                        next = other;
+                state.owner = undefined;
+                if (next)
+                    this.handOver(name, state, next);
+            },
+            onSizer: (listener) => {
+                if (left)
+                    return;
+                viewer.listener = listener;
+                viewer.lastSent = undefined;
+                this.send(state, viewer);
+            },
+        };
+    }
+    /** `viewer` sizes the window from now: copy mode is left (it froze everyone's view), the size follows. */
+    handOver(name, state, viewer) {
+        viewer.activeAt = ++this.seq;
+        const changed = state.owner !== viewer.id;
+        state.owner = viewer.id;
+        // Someone else's scroll no longer freezes the new sizing viewer's view; its own stays.
+        if (changed && (state.scrolled || state.maybeScrolled) && state.scroller !== viewer.id) {
+            void this.leaveCopyMode(name, state);
+        }
+        this.apply(name, state);
+        this.broadcast(state);
+    }
+    frameFor(state, viewer) {
+        const owner = state.owner === undefined ? undefined : state.viewers.get(state.owner);
+        if (!owner)
+            return undefined;
+        return {
+            type: 'sizer',
+            kind: owner.client?.kind ?? 'unknown',
+            label: owner.client?.label ?? null,
+            cols: owner.cols,
+            rows: owner.rows,
+            you: owner.id === viewer.id,
+            scrolled: state.scrolled,
+        };
+    }
+    /** Only to a viewer that said hello, and only what changed since its last frame. */
+    send(state, viewer) {
+        if (!viewer.client || !viewer.listener)
+            return;
+        const frame = this.frameFor(state, viewer);
+        if (!frame)
+            return;
+        const text = JSON.stringify(frame);
+        if (text === viewer.lastSent)
+            return;
+        viewer.lastSent = text;
+        try {
+            viewer.listener(frame);
+        }
+        catch {
+            /* a closing socket; its leave follows */
+        }
+    }
+    broadcast(state) {
+        for (const viewer of state.viewers.values())
+            this.send(state, viewer);
+    }
+    /** Leave copy mode (if the pane is in it) and tell every viewer. */
+    async leaveCopyMode(name, state) {
+        state.cancelModeCheck?.();
+        state.cancelModeCheck = undefined;
+        const { scroller, maybeScrolled } = state;
+        state.maybeScrolled = false;
+        state.scroller = undefined;
+        // Not left (tmux failed): who scrolled is kept (their leaving still exits it), and what the
+        // pane is in is read again, never assumed.
+        if (!(await this.options.tmux(leaveCopyModeArgs(name))).ok) {
+            state.scroller ??= scroller;
+            state.maybeScrolled ||= maybeScrolled;
+            this.checkMode(name, state);
+            return;
+        }
+        if (state.scrolled) {
+            state.scrolled = false;
+            this.broadcast(state);
+        }
+    }
+    /** Read the pane's copy mode once input has been quiet {@link MODE_CHECK_MS}; tell viewers when it changed. */
+    checkMode(name, state) {
+        state.cancelModeCheck?.();
+        state.cancelModeCheck = this.setTimer(() => {
+            state.cancelModeCheck = undefined;
+            void (async () => {
+                const read = await this.options.tmux(paneInModeArgs(name));
+                if (!read.ok)
+                    return;
+                const scrolled = (read.stdout ?? '').trim() === '1';
+                state.maybeScrolled = false;
+                if (!scrolled)
+                    state.scroller = undefined;
+                if (scrolled !== state.scrolled) {
+                    state.scrolled = scrolled;
+                    this.broadcast(state);
+                }
+            })();
+        }, MODE_CHECK_MS);
+    }
+    /**
+     * Size the window to its sizing viewer once the asks have been quiet {@link HANDOVER_DEBOUNCE_MS}:
+     * one `resize-window` at a time, the latest size last, none for a size it already has.
+     */
+    apply(name, state) {
+        const owner = state.owner === undefined ? undefined : state.viewers.get(state.owner);
+        if (!owner)
+            return;
+        state.desired = { cols: owner.cols, rows: owner.rows };
+        this.last = { ...state.desired };
+        state.cancelApply?.();
+        state.cancelApply = this.setTimer(() => {
+            state.cancelApply = undefined;
+            this.pump(name, state);
+        }, HANDOVER_DEBOUNCE_MS);
+    }
+    pump(name, state) {
+        if (state.applying)
+            return;
+        const run = async () => {
+            while (state.desired && key(state.desired) !== state.applied) {
+                const want = state.desired;
+                if (!(await this.options.tmux(resizeWindowArgs(name, want.cols, want.rows))).ok)
+                    return;
+                state.applied = key(want);
+            }
+        };
+        state.applying = run().finally(() => {
+            state.applying = undefined;
+        });
+    }
+    settle(name, state) {
+        const now = this.now();
+        state.settleDeadline ??= now + SETTLE_MAX_MS;
+        state.cancelSettle?.();
+        const wait = Math.max(0, Math.min(SETTLE_MS, state.settleDeadline - now));
+        state.cancelSettle = this.setTimer(() => void this.release(name, state), wait);
+    }
+    async release(name, state) {
+        if (state.settled)
+            return;
+        state.settled = true;
+        state.cancelSettle?.();
+        state.cancelFallback?.();
+        // At its size first: a debounced resize goes now, and the shell's first prompt is drawn once,
+        // at the size it keeps.
+        if (state.cancelApply) {
+            state.cancelApply();
+            state.cancelApply = undefined;
+            this.pump(name, state);
+        }
+        await state.applying;
+        await this.options.tmux(releaseHoldArgs(name));
+    }
+}
+/**
+ * What a chunk of a viewer's input says about who sizes the window: a focus-in report (its window
+ * came to the front) claims it; anything a person typed only takes it from an idle sizing viewer.
+ */
+export function noteInputTakeover(viewer, data) {
+    if (hasFocusIn(data))
+        viewer.claim();
+    else if (isHumanInput(data))
+        viewer.typed();
+}