@cplieger/web-terminal-ui 5.3.1 → 5.4.0

package/src/features/tabs/model.ts

@@ -192,66 +192,6 @@ export const ACTIVE_TAB_KEY = "wt-active-session";
 // One-time "swipe to switch" hint, remembered across loads.
 export const SWIPE_HINT_KEY = "wt-swipe-hint-seen";
 
-/** localStorage key for the user's tab ARRANGEMENT: the strip's session ids in
- *  the order they are shown, so a drag-reorder (or a Move left/right) survives a
- *  reload instead of snapping back to the server's creation order.
- *
- *  Deliberately client-side, alongside ACTIVE_TAB_KEY: the arrangement is a
- *  per-viewer preference, not a property of the session. Keeping it here costs
- *  no engine API — the session REST surface is a fixed four routes, and adding a
- *  fifth for cosmetics would be a release-noted change to every consumer. The
- *  tradeoff is that two devices do not share an arrangement (each keeps its own),
- *  and that when several windows of the same browser are open the last order
- *  change written wins. */
-export const TAB_ORDER_KEY = "wt-tab-order";
-
-/** Bound on the persisted arrangement. Every id is a live PTY server-side, so a
- *  real strip is nowhere near this; the cap is there so a corrupted or hostile
- *  stored value cannot make the restore path do unbounded work. */
-export const MAX_PERSISTED_TAB_ORDER = 200;
-
-/** parseTabOrder reads a stored arrangement into a clean id list. Anything the
- *  restore path cannot trust yields [] (or is dropped), because falling back to
- *  the server's creation order is always a valid arrangement: a non-JSON or
- *  non-array value, a non-string or empty entry, and a duplicate id (which would
- *  make the insert position ambiguous) are all discarded rather than repaired.
- *  Pure, so it is testable without a storage backend; the caller owns the
- *  localStorage read and its try/catch. */
-export function parseTabOrder(raw: string | null): string[] {
-  if (raw === null || raw === "") {
-    return [];
-  }
-  let data: unknown;
-  try {
-    data = JSON.parse(raw);
-  } catch {
-    return [];
-  }
-  if (!Array.isArray(data)) {
-    return [];
-  }
-  const out: string[] = [];
-  const seen = new Set<string>();
-  for (const entry of data) {
-    if (typeof entry !== "string" || entry === "" || seen.has(entry)) {
-      continue;
-    }
-    seen.add(entry);
-    out.push(entry);
-    if (out.length >= MAX_PERSISTED_TAB_ORDER) {
-      break;
-    }
-  }
-  return out;
-}
-
-/** serializeTabOrder encodes an arrangement for storage, capped the same way the
- *  read is so a write can never produce a value its own parser would truncate
- *  differently. */
-export function serializeTabOrder(ids: readonly string[]): string {
-  return JSON.stringify(ids.slice(0, MAX_PERSISTED_TAB_ORDER));
-}
-
 /** The session statuses that raise the mobile switcher's aggregate attention
  *  cue. The rule is "only states that want the user — it's like a notification":
  *  a background terminal blocked on the user ("input"), one whose turn finished
@@ -278,11 +218,12 @@ export function isCueStatus(status: string): status is CueStatus {
  *  back on the next page load — and, since the snapshot is re-pushed on every
  *  SSE reconnect, on a phone simply returning to a backgrounded page.
  *
- *  Client-side for the same reason as ACTIVE_TAB_KEY and TAB_ORDER_KEY: "I have
- *  seen this" is a property of the VIEWER, not of the session. A phone
- *  acknowledging a finished turn must not blank the dot on the desktop watching
- *  the same server, so this needs no engine API and the session REST surface
- *  stays the fixed four routes.
+ *  Client-side for the same reason as ACTIVE_TAB_KEY: "I have seen this" is a
+ *  property of the VIEWER, not of the session. A phone acknowledging a finished
+ *  turn must not blank the dot on the desktop watching the same server, so this
+ *  needs no engine API. Contrast the tab ARRANGEMENT, which is a property of the
+ *  session set and so is the server's (see compareTabOrder): a reorder is meant
+ *  to reach the other device, and an acknowledgement is not.
  *
  *  Keyed per session rather than as one latest-wins slot: several background tabs
  *  can hold a latched status at once while the cue only ever shows the newest, so
@@ -290,10 +231,9 @@ export function isCueStatus(status: string): status is CueStatus {
  *  the next load. */
 export const CUE_SEEN_KEY = "wt-cue-seen";
 
-/** Bound on the acknowledgement map, same reasoning as MAX_PERSISTED_TAB_ORDER:
- *  every key is a live session server-side, so a real one is nowhere near this,
- *  and a corrupted or hostile stored value cannot make the restore path do
- *  unbounded work. */
+/** Bound on the acknowledgement map: every key is a live session server-side, so
+ *  a real one is nowhere near this, and a corrupted or hostile stored value
+ *  cannot make the restore path do unbounded work. */
 export const MAX_PERSISTED_CUE_SEEN = 200;
 
 /** parseCueSeen reads stored acknowledgements into a clean map. Anything it
@@ -336,31 +276,89 @@ export function serializeCueSeen(seen: ReadonlyMap<string, CueStatus>): string {
   return JSON.stringify(Object.fromEntries(seen));
 }
 
-/** orderedInsertIndex returns where `id` belongs in `current` (a list of tab ids
- *  in display order) to honour the stored arrangement `saved`.
+/** TabOrderKey is what the strip's order is decided by: the server's shared
+ *  position for the session, its creation timestamp, and its id. Both `Tab` and
+ *  the wire `SessionInfo` carry these three fields, so either can be passed
+ *  without a projection. */
+export interface TabOrderKey {
+  readonly id: string;
+  readonly createdAt: string;
+  /** the server's shared position, absent when the server keeps no order (an
+   *  engine before 3.9.0). Explicitly `| undefined` so a Tab, whose field is
+   *  always present and sometimes undefined, satisfies this under
+   *  exactOptionalPropertyTypes. */
+  readonly order?: number | undefined;
+}
+
+/** ORDER_ABSENT is the position given to a session the server did not place, so
+ *  it sorts after every session the server did. Absent must not read as 0, which
+ *  is a real position at the front of the strip. */
+const ORDER_ABSENT = Number.MAX_SAFE_INTEGER;
+
+/** createdMillis reads a wire createdAt as a number for comparison. An
+ *  unparseable value sorts LAST rather than first: the caller's question is where
+ *  a tab belongs in a strip, and the end is the answer that reads as "new" —
+ *  putting a tab the client cannot date at the head would rewrite the top of the
+ *  strip on the strength of a value it failed to read.
+ *
+ *  Milliseconds, deliberately, against a wire value carrying nanoseconds: the
+ *  server's own tiebreak is the id, this one's is too, and the pair therefore
+ *  agree on every input a human can produce. Comparing the STRINGS instead would
+ *  be wrong, not merely coarse — Go's RFC 3339 encoding drops trailing zeros
+ *  from the fraction, so ".15" sorts before ".1" lexically. */
+function createdMillis(raw: string): number {
+  const when = Date.parse(raw);
+  return Number.isNaN(when) ? Number.MAX_SAFE_INTEGER : when;
+}
+
+/** compareTabOrder is the total order the strip is built in: the server's shared
+ *  position, then age, then id.
  *
- *  This is what makes the restore independent of the order tabs ARRIVE in, which
- *  matters because they arrive from two racing sources: the status stream pushes
- *  a snapshot of the existing sessions on open, and the bootstrap's
- *  GET /api/sessions lands separately — whichever wins, each session is placed
- *  by the saved arrangement rather than by arrival.
+ *  The server owns the arrangement (engine 3.9.0, `PUT /api/sessions/order`), so
+ *  a drag on one device moves the tab on every device, and a browser with no
+ *  history of this server still opens on the arrangement its owner chose. This
+ *  replaced a per-browser `localStorage` arrangement, which by construction could
+ *  not travel and which left a second device with no arrangement at all.
  *
- *  An id absent from `saved` goes last: it is a session created after the
- *  arrangement was stored (here or in another browser), and a new tab belongs at
- *  the end. Ids in `current` that are absent from `saved` are transparent to the
- *  scan, so a saved tab can still slot ahead of them. */
-export function orderedInsertIndex(
-  current: readonly string[],
-  saved: readonly string[],
-  id: string,
-): number {
-  const rank = saved.indexOf(id);
-  if (rank < 0) {
-    return current.length;
+ *  Age and id remain, and each answers a case the position cannot: age orders
+ *  every session when the server keeps no order (an older engine sends no field,
+ *  so all positions are absent and creation order is the honest fallback), and
+ *  the id makes the order TOTAL, so two sessions created inside one millisecond
+ *  cannot swap places between two runs.
+ *
+ *  Age is read from the `createdAt` field rather than from the wire SEQUENCE on
+ *  purpose. Sessions arrive from two racing sources — the status stream's
+ *  snapshot on open, and the bootstrap's GET /api/sessions — so a client that
+ *  merges them sees neither source's order, however well each source sorted. */
+export function compareTabOrder(a: TabOrderKey, b: TabOrderKey): number {
+  const posA = a.order ?? ORDER_ABSENT;
+  const posB = b.order ?? ORDER_ABSENT;
+  if (posA !== posB) {
+    return posA < posB ? -1 : 1;
+  }
+  const bornA = createdMillis(a.createdAt);
+  const bornB = createdMillis(b.createdAt);
+  if (bornA !== bornB) {
+    return bornA < bornB ? -1 : 1;
+  }
+  if (a.id === b.id) {
+    return 0;
   }
+  return a.id < b.id ? -1 : 1;
+}
+
+/** orderedInsertIndex returns where `incoming` belongs in `current` (the tabs
+ *  already on the strip, in display order) under compareTabOrder: the index of
+ *  the first tab that sorts after it, else the end.
+ *
+ *  This is what makes the strip independent of the order tabs ARRIVE in. Each
+ *  insertion goes before the first tab that outranks the new one, which keeps a
+ *  list built from an empty strip sorted at every step, so all arrival orders of
+ *  one session set converge on the same strip. */
+export function orderedInsertIndex(current: readonly TabOrderKey[], incoming: TabOrderKey): number {
   for (let i = 0; i < current.length; i++) {
-    const other = saved.indexOf(current[i] ?? "");
-    if (other > rank) {
+    const other = current[i];
+    if (other !== undefined && compareTabOrder(other, incoming) > 0) {
       return i;
     }
   }
@@ -387,6 +385,10 @@ export interface Tab {
   /** The computed, de-duplicated label actually shown in the chrome. */
   display: string;
   createdAt: string;
+  /** The server's shared position for this session, or undefined against a server
+   *  that keeps no order. Updated from every status event, so a reorder made on
+   *  another device reaches this strip (see compareTabOrder). */
+  order: number | undefined;
   store: LineStore;
   el: HTMLElement;
   label: HTMLElement;
@@ -480,6 +482,17 @@ export interface SessionAPI {
   /** Remove a session's pinned name so its label falls back to the automatic
    *  sources. Throws on failure, for the same reason as setPinnedTitle. */
   clearPinnedTitle(id: string): Promise<void>;
+  /** Replace the display order every viewer of this server shares, by sending
+   *  every live session id in the wanted order.
+   *
+   *  THROWS on failure, and the status is the point. A 409 means the server's
+   *  session set is not the one the caller listed, so this client has not yet
+   *  seen a session created or closed elsewhere; the caller answers it by
+   *  re-listing and sending again, not by telling the user. Any other status is a
+   *  genuine failure of a reorder the user performed.
+   *
+   *  Absent from a server before engine 3.9.0, where it answers 404. */
+  setOrder(ids: readonly string[]): Promise<void>;
 }
 
 const SESSION_API_TIMEOUT_MS = 15000;
@@ -639,6 +652,19 @@ export function createSessionAPI(apiBase: string): SessionAPI {
         throw await sessionError("clear pinned title", r);
       }
     },
+    // The shared display order. The path is a literal segment rather than an id,
+    // so nothing is interpolated into it.
+    async setOrder(ids: readonly string[]): Promise<void> {
+      const r = await fetch(`${apiBase}/order`, {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ order: ids }),
+        signal: AbortSignal.timeout(SESSION_API_TIMEOUT_MS),
+      });
+      if (!r.ok) {
+        throw await sessionError("set order", r);
+      }
+    },
   };
 }
 

package/src/features/tabs/strip.ts

@@ -1,16 +1,84 @@
-// tabs/strip.ts — the desktop tab strip's chrome vocabulary: the shared SVG
-// glyphs, the one chip-content builder every chip site reuses, the strip tab
-// template, the shared control markup factories, the status-dot painter, and
-// the required-descendant picker. Everything here is closure-free markup +
-// tiny pure helpers; element construction with event wiring stays in index.ts
-// (it closes over the feature state). The mobile chrome templates live in
-// switcher.ts; the session model in model.ts.
+// tabs/strip.ts — the desktop tab strip's chrome vocabulary: the reorder-preview
+// constants, the shared SVG glyphs, the one chip-content builder every chip site
+// reuses, the strip tab template, the shared control markup factories, the
+// status-dot painter, and the required-descendant picker. Everything here is
+// closure-free markup + tiny pure helpers; element construction with event wiring
+// stays in index.ts (it closes over the feature state). The mobile chrome
+// templates and its gesture constants live in switcher.ts; the session model in
+// model.ts.
 
 // The status vocabulary itself (which statuses reveal a dot, and how each one is
 // worded for a human) lives in the DOM-free model, so the painters here and the
 // accessible names index.ts builds read one definition.
 import { statusPhrase, statusRevealsDot } from "./model.js";
 
+// --- Reorder preview -------------------------------------------------------
+// Every chip in this strip is the same width (see .wt-tab in 30-tabs.css: a
+// definite 300px with flex-grow 0, so a title changes the label and never the
+// box). That is what makes a reorder hard to read: the chip a release would
+// displace looks exactly like the one beside it, so the only thing that can say
+// where the drag will land is the strip's own motion. These are the numbers that
+// motion is spelled in — index.ts owns the mechanism, strip.ts owns the values,
+// the same split switcher.ts keeps for the mobile swipe.
+
+/** How long (ms) the pointer holds over one candidate slot before the strip
+ *  opens it.
+ *
+ *  Long on purpose. A sweep across a six-tab strip crosses five slots, and
+ *  committing each one in passing is what made the old reorder unreadable: the
+ *  strip rearranged itself continuously and the user chose a slot by stopping the
+ *  mouse at the right millisecond. A hold is a deliberate act, so the strip only
+ *  rearranges where the pointer actually rests.
+ *
+ *  It costs a fast drag nothing, because a release COMMITS the pending slot
+ *  (flushDwell) instead of discarding it: drop early and the reorder lands
+ *  immediately, exactly as it did before the preview existed. The hold is what
+ *  buys the animation, not a floor on the gesture. */
+export const REORDER_DWELL_MS = 1000;
+
+/** How far (px) each chip a commit would displace leans toward its destination
+ *  while the hold runs.
+ *
+ *  Small enough to read as a lean rather than a move, and large enough to be
+ *  unambiguous at a glance — it answers "the strip heard me, and it is about to
+ *  open THAT way" during a wait that is otherwise a second of nothing. The same
+ *  purpose the mobile switcher's PREVIEW_PEEK_MAX serves for its live swipe. */
+export const REORDER_LEAN_PX = 7;
+
+/** The one transition both preview stages use (the lean, and the slide that
+ *  commits it).
+ *
+ *  --dur-standard and --ease-standard written out as literals. JS-driven motion
+ *  in this package does not read tokens back out of the cascade; the switcher's
+ *  release reel spells its own transition the same way. Keep the two in step: a
+ *  token edit has to be mirrored here by hand.
+ *
+ *  The property is `translate`, NOT `transform`, and that is load-bearing rather
+ *  than stylistic. Declarations from a running CSS animation out-rank every normal
+ *  author declaration, inline style included, so a chip in the middle of
+ *  `wt-slot-in` or `wt-tab-in` (both animate `transform: scale`) would ignore an
+ *  inline `transform` outright and refuse to move. `translate` is a separate
+ *  property that composes with `transform` instead of competing for it. */
+export const REORDER_SHIFT_TRANS = "translate 0.2s cubic-bezier(0.2, 0, 0, 1)";
+
+/** When (ms after the slide starts) the inline transform and transition come off
+ *  the chips and the stylesheet has them back.
+ *
+ *  A margin past the 200ms transition, not a race with its own end event: an
+ *  interrupted transition fires no transitionend, and the strip must not be left
+ *  holding inline styles because a second drag arrived mid-slide. Mirrors the
+ *  switcher reel's 300ms net over a 250ms transition. */
+export const REORDER_SETTLE_MS = 300;
+
+/** How long (ms) the .wt-tab-slotted class stays on, one margin past the
+ *  --dur-enter fade the stylesheet runs with it.
+ *
+ *  A timer rather than animationend for the same reason .wt-tab-enter uses one:
+ *  the class must also come off when no animation ran at all — the animations
+ *  feature is optional, reduced motion flattens it, and a consumer stylesheet can
+ *  drop the rule. */
+export const REORDER_SLOT_FADE_MS = 300;
+
 // The +/x/keyboard glyphs are inline SVG (not font glyphs) so they center
 // exactly in their flex-centered buttons and stay symmetric regardless of the UI
 // font's metrics. Each is defined ONCE here and shared by every chip site and

package/src/features/tabs/switch-anim.ts

@@ -0,0 +1,29 @@
+// The switch-animation class → keyframe-name map, in one place because two
+// unrelated languages have to agree on it and neither compiler checks the other.
+//
+// `css/40-animations.css` declares the animation on `.term-output` for each of the
+// three `wt-switching*` classes the tabs feature toggles, and `features/tabs`
+// listens for the `animationend` of the ONE name that belongs to the switch it
+// started (a listener accepting any of the three lets a completed animation end the
+// NEXT switch a frame in). So the JS holds a copy of three CSS keyframe names, and a
+// rename on either side is silent: the listener stops matching, the class comes off
+// on the 360 ms fallback timer instead of the animation's own end, and every test
+// still passes because the tests dispatch the JS constant.
+//
+// Living here rather than inside the feature is what lets `css-contract.test.ts`
+// import it and assert the CSS agrees. Same reason `input-placeholder.ts` and
+// `kernel/gesture.ts` exist: a constant two places must keep in lockstep gets its
+// own module. NOT part of the package's `exports` map, so it is internal and can
+// change without a release note; the PUBLIC name contracts live in
+// `kernel/style-contract.ts`.
+export const SWITCH_ANIMATIONS = {
+  "wt-switching": "wt-switch-in",
+  "wt-switching-next": "wt-switch-next",
+  "wt-switching-prev": "wt-switch-prev",
+} as const;
+
+/** A class the tabs feature puts on the terminal surface to play a switch animation. */
+export type SwitchClass = keyof typeof SWITCH_ANIMATIONS;
+
+/** The three classes, for a caller that has to clear whichever one is present. */
+export const SWITCH_CLASSES = Object.keys(SWITCH_ANIMATIONS) as SwitchClass[];

package/src/kernel/kernel.ts

@@ -513,9 +513,12 @@ function buildTerminal(
     // WITHIN history never toggles follow, and that is exactly when paging has
     // to work. The trigger re-evaluates its own guards, so firing for the
     // browser's own clamps as well as gestures costs nothing.
-    onScrollPosition: () => {
-      render.maybeFetchHistory();
-    },
+    //
+    // ONE hook, deliberately. The renderer's scroll-position contract is two jobs
+    // (re-evaluate the paging trigger, and finish a drain that stopped with rows
+    // queued) and it owns the ordering and the guards for both. A consumer wiring
+    // them as two calls is a consumer that can wire one.
+    onScrollPosition: render.handleScrollPosition,
   });
 
   // The size this client would announce right now, or null when it cannot