dsh-pause-session 0.0.0-stage → 0.1.0

package/lib/types/client/burst.d.ts

@@ -0,0 +1,253 @@
+/**
+ * The re-read burst both browser controls share: a handful of reads after
+ * something moved, and silence once it settles.
+ *
+ * What a control reads is published through the host's command channel, and
+ * every read is two durable `command/run|done` records in the address session's
+ * log plus an aggregate read on the host. Reading is therefore something the
+ * host announces and the user asks for, never a heartbeat:
+ *
+ * - the host announces a transition by registering or unregistering the paused
+ *   session's marker commands, and — for a phase change, which no registration
+ *   of its own would show — by registering that session's status verb again.
+ *   Each of those emits `commands/change`, and that event, plus the user's own
+ *   press or decision, is what starts a burst;
+ * - one transition announces itself several times: a park registers two or three
+ *   marker commands per session and a phase change re-registers one, and the host
+ *   emits one `commands/change` per step. The burst therefore waits out a short
+ *   `windowMs` before its first read and any trigger inside that window
+ *   postpones it, so the announcements of one transition start one burst rather
+ *   than one each;
+ * - a change that arrives within `ACTION_ABSORB_MS` of the user's own action is
+ *   that action's own consequence, not news: the action already read the host,
+ *   so the answer is on screen, and the unregistrations it caused — one event
+ *   per marker command, measured seconds apart, which the window above cannot
+ *   merge — would only be read back. Such a change is absorbed, and each one
+ *   absorbed pushes the window out, because a storm that keeps arriving is
+ *   still the same storm. The window always closes: the first change after
+ *   `ACTION_ABSORB_MS` of quiet is news again, and a user action reads on its
+ *   own whatever the window says;
+ * - an absorbed change is deferred rather than lost: a control whose action left
+ *   a phase still moving asks for one look at the moment the window closes
+ *   ({@link ReadBurst.recheckAfterEcho}), which is the read that finds a
+ *   transition the window hid — the park can reach its final phase inside that
+ *   window and never announce anything again. One look per action, and only
+ *   while the state it left is still moving;
+ * - a burst is a fixed short list of waits, so at most that many reads answer
+ *   one transition, however long the page stays open;
+ * - a read that finds the verdict settled ends the burst at once, and the last
+ *   reading stays on screen — "the park is settled" is not a state change, so
+ *   it must not be re-asked;
+ * - a read that finds a phase still moving ends it just as fast. Every phase
+ *   transition is announced at its source, the flush that resolves `parking`
+ *   into `safe` included, and that announcement is the very event that starts
+ *   the next burst — so watching a moving phase from here spends records on a
+ *   transition that will speak for itself;
+ * - what the burst still owes after a read is delivery: the read one
+ *   announcement bought, and one more when a change lands while a pass is in
+ *   flight, which that pass cannot have answered. The bound is a bound, not a
+ *   heartbeat: a phase that never settles is left on screen unread until
+ *   something else moves;
+ * - the bound is a trade, taken knowingly: a reading left on screen when the
+ *   burst runs out is the host's own last answer, and the next trigger — a
+ *   forwarded change, a press, or the shell handing a control its session again
+ *   — reads the truth again. A reading nobody answered is never rendered as a
+ *   confident state. A longer watch is a longer list of waits, at a linear price
+ *   in the address session's log;
+ * - while the page is hidden no read is armed at all, and the wait a burst
+ *   still owed is armed again when the page comes back: hidden time is neither
+ *   charged to the burst nor lost from it.
+ *
+ * A burst is not restarted by a trigger that lands while one is running: every
+ * read it still owes happens after that trigger, so absorbing it loses nothing
+ * and a storm of registry changes costs one burst rather than one each.
+ * @module dsh-pause-session/client/burst
+ */
+/** Whether the page is on screen, as the shell reports it. */
+export type PageVisibility = () => boolean;
+/**
+ * One control's burst policy.
+ *
+ * `waitsMs` is the whole bound: a burst spends at most one read per wait, and
+ * an empty list turns bursting off entirely — which is how a test or a
+ * composition disables it without touching anything else.
+ */
+export interface BurstPolicy {
+    /** How long the burst collects triggers before its first wait starts. */
+    readonly windowMs: number;
+    /** Waits between the reads of one burst, in order; the first follows a trigger. */
+    readonly waitsMs: readonly number[];
+    /** Whether the page is on screen now. */
+    readonly visible: PageVisibility;
+}
+/** The policy every control uses unless a caller says otherwise. */
+export declare const DEFAULT_BURST_POLICY: BurstPolicy;
+/**
+ * How long after a client action a registry change is that action's own echo.
+ *
+ * A press, a release, a decision, a goal switch and an opened panel each read
+ * the host as they run, so their answer is already on screen when the host
+ * announces what they did — one `commands/change` per marker command, measured
+ * 0.44 s to 2.04 s apart, a cadence the coalescing window cannot merge. Reading
+ * those back is paying for an answer the user already has.
+ *
+ * The window is what makes `commands/change` mean "something moved that this
+ * browser did not do". It is refreshed by every change it absorbs, so a storm
+ * that keeps arriving stays absorbed rather than leaking one read per change,
+ * and it ends for good `ACTION_ABSORB_MS` after the last change: a change after
+ * that is news, and so is the next user action, which reads on its own.
+ *
+ * The margin over the measured 2.04 s gap is deliberate: a transition's own
+ * storm has to fit inside the window for the whole storm to stay absorbed.
+ */
+export declare const ACTION_ABSORB_MS = 2500;
+/**
+ * The waits one burst uses when its first wait is `first`: four reads spread
+ * over roughly ten times that. Long enough that a read a hidden page or an
+ * in-flight pass deferred is still taken, short enough that a state which never
+ * settles costs a handful of log records rather than a night of them.
+ * @param first - milliseconds before the burst's first read, after its window; `<= 0` disables bursting.
+ * @returns the waits, in order; empty when bursting is disabled.
+ */
+export declare function burstWaits(first: number): readonly number[];
+/** Start and clear one timer, spelled so a test can drive the clock. */
+export interface BurstClock {
+    /**
+     * @param callback - the read to run.
+     * @param ms - how long to wait.
+     * @returns the scheduled timer.
+     */
+    set(callback: () => void, ms: number): ReturnType<typeof setTimeout>;
+    /**
+     * @param timer - the timer to clear.
+     */
+    clear(timer: ReturnType<typeof setTimeout>): void;
+}
+/**
+ * One control's re-read burst. Every method is safe to call in any order and as
+ * often as the caller likes: a trigger starts at most one burst, and one burst
+ * never arms more than one read at a time.
+ */
+export declare class ReadBurst {
+    private readonly onRead;
+    private readonly policy;
+    private readonly clock;
+    /** The armed wait, when one is counting down. */
+    private timer;
+    /** Whether the burst is waiting out its collection window rather than a wait between reads. */
+    private window;
+    /** Waits this burst has not spent yet, front first. */
+    private left;
+    /** Whether a burst is in progress: it may be collecting, waiting, reading, or reading again. */
+    private running;
+    /** The absorption window a client action opened, while one is open. */
+    private absorbed;
+    /** Whether a control asked for the one look owed when the echo window closes. */
+    private recheck;
+    /**
+     * @param onRead - one more read. Called only for a read the burst owes and the page can show.
+     * @param policy - the collection window, the waits, and the visibility source.
+     * @param clock - the timer implementation.
+     */
+    constructor(onRead: () => void, policy: BurstPolicy, clock?: BurstClock);
+    /** Whether this control bursts at all. */
+    get enabled(): boolean;
+    /** Whether one more read is already counting down. */
+    get armed(): boolean;
+    /** Whether a burst is in progress, with or without a read counting down. */
+    get live(): boolean;
+    /** Whether a change right now is a client action's own echo. */
+    get absorbing(): boolean;
+    /**
+     * The user acted on this control and the action reads: a press, a release, a
+     * decision, a goal switch, an opened panel. Its read is the answer, and the
+     * registry changes it sets off announce themselves for a while afterwards, so
+     * until the window closes a trigger is that echo rather than news.
+     *
+     * Called as the action is taken, before its read lands, because the echo can
+     * arrive while the action is still running.
+     */
+    absorb(): void;
+    /**
+     * Ask for one read at the moment the echo window closes, because the action's
+     * own read left a state that is still moving.
+     *
+     * The echo window swallows a transition announced inside it — the forwarded
+     * event carries no payload, so nothing distinguishes a marker registration
+     * from a phase change — and after the window no change is guaranteed to come:
+     * the transition that was hidden may be the last one this park makes. The
+     * look owed here is the read that finds it, one per action, and it is not a
+     * watch: once the window has closed, every further change is news and buys its
+     * own read. A control whose action left a settled state owes nothing and asks
+     * for nothing.
+     */
+    recheckAfterEcho(): void;
+    /**
+     * Something moved — a registry change. The burst first waits out its
+     * collection window, and every trigger that lands inside it restarts that
+     * window: the two or three registrations of one park start one burst rather
+     * than one each. A burst already past its window takes this as covered —
+     * every read it still owes happens after the change.
+     *
+     * @returns whether the change is news rather than a client action's own echo.
+     * The echo announces what the action's read already answered, so only a news
+     * trigger is a change a control still owes a read for; a change that lands
+     * while a burst is under way is covered by the read that burst already owes.
+     * `false` also for a disabled burst, which reads nothing at all.
+     */
+    trigger(): boolean;
+    /**
+     * The control knows it still owes a read: a change that is news has arrived,
+     * or a reading just revealed something only a read can answer. A call outside
+     * any burst starts one. Absorption never applies here — this is not a change
+     * some action caused, it is a read the control already knows it needs.
+     */
+    next(): void;
+    /**
+     * Nothing is moving: end the burst and forget it. The last reading stays
+     * published, and the next trigger starts a fresh burst. Two things outlive
+     * this: an action's absorption window, which is about what the action caused
+     * rather than about the state, and the one look it may still owe — see
+     * {@link recheckAfterEcho}.
+     */
+    stop(): void;
+    /** Drop the armed wait. A burst that is still owed its read survives it; see {@link checkVisibility}. */
+    cancel(): void;
+    /**
+     * Re-evaluate one page-visibility change. Going off screen drops the armed
+     * wait — a hidden page is not being read — and coming back arms it again, so
+     * the burst resumes where it stopped instead of being spent while nobody was
+     * looking. A burst still collecting resumes its window, restarted from the
+     * moment the page came back: a trigger that arrived while it was hidden still
+     * postpones the read.
+     */
+    checkVisibility(): void;
+    /** Spend the next wait of the burst, or end it when the bound is reached. */
+    private owe;
+    /**
+     * (Re)start the collection window. While the page is hidden nothing is armed
+     * — hidden time is not charged to the burst — and a trigger that lands then
+     * is still collected, because coming back starts a whole window.
+     */
+    private armWindow;
+    /** Put back whatever the burst still owed: its window, or the wait after a read. */
+    private arm;
+    /**
+     * (Re)start the absorption window a client action opened. A hidden page keeps
+     * absorbing: this window is about what the action caused, not about what the
+     * page is doing. When the window closes, the one look an unsettled action owes
+     * is taken; the window is restarted by every change it absorbs, so that look
+     * waits for the echo to actually stop.
+     */
+    private armAbsorb;
+    /** Close the absorption window: changes are news again. */
+    private cancelAbsorb;
+    /**
+     * Arm one wait, spending it when it fires. The wait stays in `left` until
+     * then, so a page hidden mid-wait takes the whole wait again: hidden time is
+     * neither charged to the burst nor lost from it.
+     */
+    private armWait;
+    /** Whether the page counts as on screen now, with an absent `document` read as on screen. */
+    private visibleNow;
+}

package/lib/types/client/control.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Browser-side reading and driving of the host's park state for one session.
+ *
+ * The host publishes no push channel of its own — a third-party plugin cannot
+ * add a Client Remote namespace or a forwarded event — so this control reads
+ * the host's command registry, which is the only live surface it can publish
+ * through: `commands.list(sessionId)` is a Client-callable read, and the
+ * forwarded `commands/change` event says when to read it again. The resume
+ * definition's presence in that list IS the host's "this session is paused"
+ * fact, and the companion status definition answers with the park state as of
+ * the read; this module never derives either from its own press. That one
+ * answer carries the record's goal opt-out as well, so the switch beside the
+ * pause button can show it without a second host round-trip — and without it,
+ * the control renders no switch at all.
+ *
+ * Every phase the host reaches announces itself on that channel: a transition
+ * re-registers the status verb, so a transition is what buys the next read and a
+ * read that finds a phase still moving is the answer to the transition that
+ * produced it rather than a reason to keep asking (`./burst.ts`). One transition
+ * arrives as several registry changes — parking a session also registers its
+ * three commands — so the burst's own collection window is what turns a tick of
+ * changes into one read per shown session. A press or a goal switch reads as it
+ * runs, and the marker changes it causes are that action's own echo: those are
+ * absorbed for a short window (`./burst.ts`) rather than read back — except for
+ * the one look an action owes when that window closes, if the reading it left
+ * behind is still moving, because a transition announced inside the window would
+ * otherwise never be read at all.
+ *
+ * The whole-app control reads the same park and publishes what it found
+ * (`./global.ts`), and a header consults that answer before spending a read of
+ * its own: with nothing registered, no session can be paused, so a header that
+ * already says "running" is left saying it rather than paying a round-trip to
+ * hear it again. A header the host last showed on its way to a park is never
+ * answered that way — that reading is the newer fact — and the derivation is
+ * voided by the next whole-app answer that names a registered session, which
+ * the forwarded change a park causes is what brings in.
+ * @module dsh-pause-session/client/control
+ */
+import type { ClientRemote } from '@deepseek-ai/dsh-api-remotes/client';
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { BurstPolicy } from './burst.js';
+import type { GlobalReading } from './global.js';
+/**
+ * The whole-app answer as the session headers read it, or `undefined` before
+ * that control has heard from the host. Reading it costs nothing: it is the
+ * published snapshot, not a host round-trip.
+ */
+export type AggregateSource = () => GlobalReading | undefined;
+/**
+ * What the Session-header control knows about one session: what the host
+ * reported, or that no answer has arrived (`undefined`) or the last read
+ * failed. Neither of the latter claims a state the host never reported.
+ *
+ * `draining` and `parking` are the host's own two answers on the way to
+ * `safe`; the control shows them rather than rounding them up, because only
+ * `safe` means the pending input is durably stored.
+ */
+export type PausePhase = 'active' | 'draining' | 'parking' | 'safe' | 'flush-failed' | 'unavailable';
+/** One host answer about one session. */
+export interface PauseReading {
+    readonly phase: PausePhase;
+    /** Tools the host reported in flight; empty unless the phase is `draining`. */
+    readonly runningTools: readonly string[];
+    /**
+     * Whether the host's own record lets the next resume re-open this session's
+     * goal. Absent — not `true` — when the host did not say: the control shows no
+     * switch rather than the product default, because a default here would tell
+     * the user their rounds are safe when nobody has answered.
+     */
+    readonly rearmGoal?: boolean;
+}
+/** Per-session control state, keyed by Session id so a slot selector can watch one session. */
+export interface PauseState {
+    /** Reading per Session id; absent means no host answer yet. Writable: the store updates through a draft. */
+    bySession: Record<string, PauseReading | undefined>;
+}
+/** Owns the published reading per session; nothing else writes that state. */
+export declare class PauseControl {
+    private readonly commands;
+    private readonly lifetime;
+    private readonly aggregate;
+    /** State source the Session-header contribution binds its selector hook to. */
+    readonly store: SnapshotStore<PauseState>;
+    /** Sessions this control has shown; a host registry change re-reads every one of them. */
+    private readonly shown;
+    /** Highest read sequence requested per session: an answer older than it is dropped. */
+    private readonly latest;
+    /**
+     * Sessions a change has put back on the list of ones to read once — a
+     * transition this browser has been told about and has not answered yet.
+     */
+    private readonly owed;
+    /**
+     * Whether the look owed at the close of an echo window is still to be taken.
+     * It reads every shown session, exactly as a change does: the look exists
+     * because a change may have been swallowed, and a swallowed change carries no
+     * payload either.
+     */
+    private trailing;
+    /**
+     * Sessions whose header was answered from the whole-app "nothing is
+     * registered" instead of a read of their own, and which therefore have to be
+     * read for real if that answer stops holding.
+     */
+    private readonly derived;
+    /** The bounded burst of reads one transition buys; see `./burst.ts`. */
+    private readonly burst;
+    private reads;
+    /**
+     * @param commands - the Client-callable command namespace.
+     * @param lifetime - aborts in-flight calls and the burst when the plugin unloads.
+     * @param windowMs - how long the burst collects the registrations of one
+     * transition before its first read; also the wait after a press.
+     * @param policy - the burst waits and visibility source; defaults to the real page.
+     * @param aggregate - the whole-app control's published answer; absent means it is never consulted.
+     */
+    constructor(commands: ClientRemote['commands'], lifetime: AbortSignal, windowMs?: number, policy?: Omit<BurstPolicy, 'windowMs' | 'waitsMs'>, aggregate?: AggregateSource);
+    /**
+     * Read the host's state for one session.
+     * @param sessionId - session whose control was rendered.
+     * @returns after this read's answer is published or superseded by a newer one.
+     */
+    refresh(sessionId: SessionId): Promise<void>;
+    /**
+     * The host's command registry changed, so every session this control has
+     * shown may have moved — the forwarded event carries no payload, so the only
+     * honest answer is to look at all of them once. The reads run on the burst's
+     * own schedule rather than here, which is what makes a tick's worth of changes
+     * — parking a session registers three commands, and a phase change re-registers
+     * one more — one burst instead of one each. A change that is this browser's own
+     * action's echo owes nothing: the action read the host as it ran.
+     */
+    refreshAll(): void;
+    /**
+     * One pass of the burst: every shown session a change still owes a read. The
+     * forwarded event carries no payload, so a change may have touched any of
+     * them and each is read once. A session the whole-app answer has already
+     * spoken for is answered from it instead of being asked about; see
+     * {@link answerIsKnown}.
+     */
+    private readAll;
+    /** One session's read, published unless a newer read of that session supersedes it. */
+    private readOne;
+    /**
+     * Press the control: pause an active session, or take back a pause that is
+     * still on its way in (or already settled). The phase shown afterwards is the
+     * host's answer, never an assumed flip.
+     * @param sessionId - session whose control was pressed.
+     * @returns after the control re-reads the host.
+     */
+    toggle(sessionId: SessionId): Promise<void>;
+    /**
+     * Flip this session's goal opt-out. The verb belongs to the session it
+     * changes — the host registers it there, and it takes no other target — so
+     * this press needs no listed row. What the switch shows afterwards is the
+     * host's next answer, never a local flip: a refused switch leaves the record
+     * exactly as it was, and the re-read is what says so.
+     * @param sessionId - session whose switch was pressed.
+     * @returns after the control re-reads the host.
+     */
+    toggleGoal(sessionId: SessionId): Promise<void>;
+    /** Ask the host what this session's park state is, in the browser's vocabulary. */
+    private read;
+    private publish;
+    /**
+     * Whether the park has already answered for this header: with nothing
+     * registered, no session can be paused, so a header that says this session is
+     * running carries the whole fact and the read that would confirm it is a host
+     * round-trip plus two records in that session's log for nothing.
+     *
+     * A header the host last showed on its way to a park is never answered this
+     * way: that reading is newer than the aggregate the derivation rests on, and
+     * only a fresh host answer may replace it.
+     */
+    private answerIsKnown;
+    /**
+     * Whether the whole-app answer says the park holds nothing at all: the one
+     * predicate the derivation below and its revocation share.
+     */
+    private nothingParked;
+    /**
+     * Answer one header from the whole-app verdict, and remember that it was that
+     * kind of answer: the sessions to read for real are exactly the ones the
+     * aggregate may have been wrong about.
+     */
+    private deriveActive;
+    /**
+     * The whole-app answer moved. Whatever was answered from "nothing is
+     * registered" is read for real the moment that stops holding — the session a
+     * header stood in for may be the one the park just took, possibly parked from
+     * another window whose change this browser only sees as the forwarded event.
+     * Called on every published aggregate, so it must do nothing while the
+     * derivation still holds.
+     */
+    reconsider(): void;
+    /**
+     * Decide what the burst owes after a read: another look while a change this
+     * browser has not answered is still outstanding, and nothing once none is.
+     *
+     * A phase that is still moving is left alone. The host announces every
+     * transition on its command channel — the flush that settles a park included,
+     * which changes no registration of its own — so a read that finds `draining`
+     * or `parking` is the answer to the transition that produced it, and watching
+     * that phase from here would spend reads on a move that is going to speak for
+     * itself. What the burst still owes is the delivery of an announcement: a read
+     * still armed when the change arrived, and a read for a change that landed
+     * while the last pass was in flight.
+     *
+     * The one transition that cannot speak for itself is the one this browser's
+     * own echo window swallowed: a press reads the host, the park moves while the
+     * window is still open, and the changes that would have announced it look
+     * exactly like the press's own registrations. So an action that left a phase
+     * still moving asks for one look when that window closes, and only then — the
+     * read is owed at a moment, not watched. Once nothing is owed, the last
+     * reading stays on screen; the next change, the next user action, or the shell
+     * handing this control a session again is what asks next.
+     */
+    private follow;
+    /**
+     * Whether any shown session's last reading is a phase the host has not
+     * finished walking — the only states an action's own echo could be hiding a
+     * transition behind.
+     */
+    private moving;
+    /**
+     * Follow the page in and out of view. A hidden page is not being read — and
+     * the read the burst was about to take is not lost, it waits for the page to
+     * come back.
+     */
+    watchVisibility(): void;
+}