@design.estate/dees-catalog 12.0.0 → 12.2.0

package/ts_web/elements/00group-harness/dees-terminal-view/dees-terminal-view.ts

@@ -9,6 +9,7 @@ import {
 } from '@design.estate/dees-element';
 import type { Terminal } from 'xterm';
 import type { FitAddon } from 'xterm-addon-fit';
+import * as plugins from '../../00plugins.js';
 import { themeDefaultStyles } from '../../00theme.js';
 import { DeesServiceLibLoader } from '../../../services/index.js';
 
@@ -23,7 +24,10 @@ export interface ITerminalInputDetail {
   data: string;
 }
 
-/** Detail of `terminal-resize`, fired after the terminal refits its container. */
+/**
+ * A terminal grid size. It is the detail of `terminal-resize`, fired after the
+ * terminal refits its container, and the size `restore()` paints a snapshot at.
+ */
 export interface ITerminalResizeDetail {
   rows: number;
   cols: number;
@@ -59,6 +63,49 @@ const RIS = '\x1bc';
 const chunkByteLength = (chunkArg: string | Uint8Array): number =>
   typeof chunkArg === 'string' ? chunkArg.length * 2 : chunkArg.byteLength;
 
+/** Identity of a grid size, as compared when deciding whether to report a refit. */
+const gridKey = (sizeArg: ITerminalResizeDetail): string => `${sizeArg.rows}x${sizeArg.cols}`;
+
+/**
+ * Grid bounds `restore()` accepts. xterm silently widens anything narrower than
+ * two columns (a wide character needs two cells), which would paint a snapshot
+ * at a size other than the one it was serialized at; a PTY window size is a
+ * 16-bit field, so no real snapshot is larger than the upper bound.
+ */
+const minRestoreCols = 2;
+const minRestoreRows = 1;
+const maxRestoreGridSize = 0xffff;
+
+const isGridDimension = (valueArg: number, minArg: number): boolean =>
+  Number.isInteger(valueArg) && valueArg >= minArg && valueArg <= maxRestoreGridSize;
+
+/**
+ * One `restore()` call: the snapshot, the grid it was serialized at, and the
+ * deferred whose promise is handed back to the caller. Its rejections are
+ * lifecycle outcomes, not programming errors, so, as with `ready`, an
+ * unawaited promise never surfaces as an unhandled rejection; a caller that
+ * awaits it still observes the reason.
+ */
+class TerminalRestore {
+  public readonly deferred = plugins.smartpromise.defer<void>();
+
+  constructor(
+    public readonly data: string | Uint8Array,
+    public readonly size: ITerminalResizeDetail,
+  ) {
+    this.deferred.promise.catch(() => undefined);
+  }
+}
+
+/** Everything buffered while no terminal is live, in replay order. */
+interface IPendingOutput {
+  /** The base of the writes; it resets everything that was buffered before it. */
+  restore: TerminalRestore | undefined;
+  writes: Array<string | Uint8Array>;
+  /** Whether older output was dropped, so the replay has to reset before the writes. */
+  dropped: boolean;
+}
+
 /**
  * Transport-agnostic xterm.js surface: the host pipes remote PTY output into
  * `write()` and receives keystrokes via `terminal-input` — no process,
@@ -66,9 +113,10 @@ const chunkByteLength = (chunkArg: string | Uint8Array): number =>
  * every refit so the host can negotiate a PTY size. Output that arrives while
  * no terminal is live is buffered up to `maxPendingWriteBytes` and replayed in
  * order on the next connection, so a replay may start before the element is
- * ready and survives being detached. xterm loads through DeesServiceLibLoader;
- * CSP-locked hosts can pre-register bundled modules with
- * `provideXtermModules()` to avoid the CDN.
+ * ready and survives being detached. `restore()` paints a serialized snapshot
+ * invisibly at the grid it was taken at, then fits it to the container. xterm
+ * loads through DeesServiceLibLoader; CSP-locked hosts can pre-register
+ * bundled modules with `provideXtermModules()` to avoid the CDN.
  */
 @customElement('dees-terminal-view')
 export class DeesTerminalView extends DeesElement {
@@ -88,11 +136,24 @@ export class DeesTerminalView extends DeesElement {
   private inputDisposable: { dispose(): void } | undefined;
   private lastReportedSize = '';
   // Output that arrives before xterm is live is replayed in order, bounded by
-  // maxPendingWriteBytes and retained across a disconnect.
+  // maxPendingWriteBytes and retained across a disconnect. A buffered restore
+  // resets everything before it, so there is at most one and it is the base
+  // of the chunks buffered after it; its bytes count towards the bound.
+  private pendingRestore: TerminalRestore | undefined;
   private pendingWrites: Array<string | Uint8Array> = [];
   private pendingWriteBytes = 0;
   private pendingWritesDropped = false;
   private setupPromise: Promise<void> | undefined;
+  /**
+   * The restore handed to the live terminal whose snapshot is not parsed yet. While it is set the
+   * grid belongs to the snapshot: the terminal stays invisible and nothing refits it.
+   */
+  private activeRestore: TerminalRestore | undefined;
+  /**
+   * Set only by an explicit `focus()` that arrived before the terminal existed. Nothing else sets
+   * it, so a re-render, a write, or a resize can never move the caret into this element.
+   */
+  private focusWhenReady = false;
   private readyPending = true;
   private readyResolve: () => void = () => undefined;
   private readyReject: (reasonArg: unknown) => void = () => undefined;
@@ -136,6 +197,14 @@ export class DeesTerminalView extends DeesElement {
         box-sizing: border-box;
       }
 
+      /*
+       * A restore paints invisibly. The grid keeps its layout, so fitting still measures it, and
+       * it stays focusable: visibility: hidden would blur the input surface and refuse focus().
+       */
+      .terminalHost.restoring {
+        opacity: 0;
+      }
+
       /* xterm.js styles (shadow DOM needs them locally) */
       .xterm {
         font-feature-settings: 'liga' 0;
@@ -288,7 +357,10 @@ export class DeesTerminalView extends DeesElement {
     this.bufferWrite(dataArg);
   }
 
-  /** Reset the screen and scrollback, e.g. before a full replay. */
+  /**
+   * Reset the screen and scrollback, e.g. before a full replay. Before the terminal exists it also
+   * replaces a buffered `restore()`, whose promise then resolves as superseded.
+   */
   public clear(): void {
     const terminal = this.terminal;
     if (terminal && this.isConnected) {
@@ -297,16 +369,104 @@ export class DeesTerminalView extends DeesElement {
     }
     // Without a terminal the reset is expressed as a buffered sentinel, so the
     // flush of the next connection still performs it in the right order.
-    this.pendingWrites = [RIS];
-    this.pendingWriteBytes = chunkByteLength(RIS);
-    this.pendingWritesDropped = false;
+    this.discardPendingOutput();
+    this.bufferWrite(RIS);
+  }
+
+  /**
+   * Replace the terminal state with a serialized snapshot, e.g. from xterm's serialize addon, and
+   * show it only once it is complete. A snapshot is exact only in a grid of the size it was
+   * serialized at, so the terminal is fully reset (screen, scrollback, modes, alternate buffer),
+   * set to `sizeArg`, fed `dataArg` while invisible, then fitted to its container and revealed.
+   * `terminal-resize` fires at the end when the fitted grid differs from `sizeArg`, which is the
+   * host's cue to resize the PTY so the application redraws at the new size. Until then
+   * `currentSize` reports `sizeArg`, so the closing event, or this promise, is what a host
+   * negotiates a PTY size on.
+   *
+   * The restore is part of the output stream: writes issued after it are applied after the
+   * snapshot, in order, at the fitted size. Like `write()` it is safe before the terminal exists
+   * and while the element is detached; a buffered restore replaces everything buffered before
+   * it. The terminal keeps its focus and keeps forwarding input while the restore runs.
+   *
+   * The promise resolves once the snapshot is on screen, and also, without revealing anything,
+   * when a newer `restore()` supersedes this one or `clear()` replaces it while it is buffered.
+   * It rejects, without ever surfacing as an unhandled rejection, when the element is
+   * disconnected while the snapshot is being parsed (the terminal is disposed with it, as with
+   * any live output), when output buffered after it pushes it out of `maxPendingWriteBytes`, and
+   * when xterm refuses the data (`terminal-error` carries the same error). Buffered output is
+   * dropped oldest first and the restore is the oldest entry, so a buffered snapshot that alone
+   * exceeds the bound is dropped by the next buffered write of any size. An invalid size is a
+   * programming error: the promise rejects with a `RangeError` and nothing changes; unlike the
+   * reasons above this one is not pre-handled, so a `restore()` nobody observes reports it as an
+   * unhandled rejection.
+   *
+   * There is a fourth outcome: a restore that is still buffered when the element is disconnected
+   * stays pending, because the snapshot survives the move like buffered output and is applied on
+   * the next connection. A host that discards the element instead of reattaching it must not await
+   * that promise.
+   *
+   * @param dataArg The serialized terminal state.
+   * @param sizeArg The grid the snapshot was serialized at: integer `cols` in [2, 65535] and
+   *   `rows` in [1, 65535].
+   */
+  public restore(dataArg: string | Uint8Array, sizeArg: ITerminalResizeDetail): Promise<void> {
+    const { cols, rows } = sizeArg;
+    if (!isGridDimension(cols, minRestoreCols) || !isGridDimension(rows, minRestoreRows)) {
+      return Promise.reject(
+        new RangeError(
+          `restore() needs integer cols in [${minRestoreCols}, ${maxRestoreGridSize}] and rows in ` +
+            `[${minRestoreRows}, ${maxRestoreGridSize}], got ${cols}x${rows}`,
+        ),
+      );
+    }
+    const restore = new TerminalRestore(dataArg, { cols, rows });
+    const terminal = this.terminal;
+    if (terminal && this.isConnected) {
+      this.startRestore(terminal, restore);
+    } else {
+      this.discardPendingOutput();
+      this.pendingRestore = restore;
+      this.pendingWriteBytes = chunkByteLength(dataArg);
+    }
+    return restore.deferred.promise;
+  }
+
+  /**
+   * Moves the caret into the terminal's input surface, so the next keystroke goes to the pty
+   * rather than to whatever the page focused last. This is the call a host makes when the user
+   * selects a terminal in a list.
+   *
+   * The terminal is created asynchronously — the xterm modules are loaded on first connection —
+   * so a call that arrives before it exists is remembered and applied once it is ready, exactly
+   * once. The same applies to an element that is focused while detached and then reattached: the
+   * pending request is dropped on disconnect, because by then the user's intent has expired, and
+   * a fresh `focus()` after the move is what a host should issue.
+   *
+   * Only this method arms that behaviour; re-renders, buffered output and background updates
+   * never steal focus.
+   */
+  public focus(optionsArg?: FocusOptions): void {
+    const terminal = this.terminal;
+    if (terminal && this.isConnected) {
+      this.focusWhenReady = false;
+      terminal.focus();
+      return;
+    }
+    // Preventing scroll is a hint for the eventual focus, not a reason to skip it.
+    void optionsArg;
+    this.focusWhenReady = true;
   }
 
-  public focus(): void {
-    this.terminal?.focus();
+  /** True while an explicit `focus()` is waiting for the terminal to come up. */
+  public get focusPending(): boolean {
+    return this.focusWhenReady;
   }
 
-  /** Current grid size, or undefined while no terminal is live. */
+  /**
+   * Current grid size, or undefined while no terminal is live. While a snapshot is being parsed
+   * this is the grid the snapshot was serialized at; the closing `terminal-resize`, or the promise
+   * `restore()` returned, is the grid to negotiate a PTY size on.
+   */
   public get currentSize(): ITerminalResizeDetail | undefined {
     if (!this.terminal) return undefined;
     return { rows: this.terminal.rows, cols: this.terminal.cols };
@@ -333,25 +493,105 @@ export class DeesTerminalView extends DeesElement {
   private bufferWrite(chunkArg: string | Uint8Array): void {
     this.pendingWrites.push(chunkArg);
     this.pendingWriteBytes += chunkByteLength(chunkArg);
-    while (this.pendingWriteBytes > maxPendingWriteBytes && this.pendingWrites.length > 1) {
-      const droppedChunk = this.pendingWrites.shift()!;
-      this.pendingWriteBytes -= chunkByteLength(droppedChunk);
+    // Oldest first, and never the newest entry: a buffered restore is older
+    // than every chunk, so it goes before any of them.
+    while (
+      this.pendingWriteBytes > maxPendingWriteBytes &&
+      this.pendingWrites.length > (this.pendingRestore ? 0 : 1)
+    ) {
+      const droppedRestore = this.pendingRestore;
+      if (droppedRestore) {
+        this.pendingRestore = undefined;
+        this.pendingWriteBytes -= chunkByteLength(droppedRestore.data);
+        droppedRestore.deferred.reject(
+          new Error(
+            'dees-terminal-view dropped a buffered restore: the output buffered after it exceeded maxPendingWriteBytes',
+          ),
+        );
+      } else {
+        this.pendingWriteBytes -= chunkByteLength(this.pendingWrites.shift()!);
+      }
       this.pendingWritesDropped = true;
     }
   }
 
-  private flushPendingWrites(terminalArg: Terminal): void {
-    const pending = this.pendingWrites;
-    const dropped = this.pendingWritesDropped;
+  /** Hands the buffered output over and leaves the buffer empty. */
+  private takePendingOutput(): IPendingOutput {
+    const output: IPendingOutput = {
+      restore: this.pendingRestore,
+      writes: this.pendingWrites,
+      dropped: this.pendingWritesDropped,
+    };
+    this.pendingRestore = undefined;
     this.pendingWrites = [];
     this.pendingWriteBytes = 0;
     this.pendingWritesDropped = false;
+    return output;
+  }
+
+  /** Empties the buffer ahead of a reset; a buffered restore is superseded by it. */
+  private discardPendingOutput(): void {
+    this.takePendingOutput().restore?.deferred.resolve();
+  }
+
+  private flushPendingWrites(terminalArg: Terminal): void {
+    const { restore, writes, dropped } = this.takePendingOutput();
+    if (restore && !this.startRestore(terminalArg, restore)) return;
     if (dropped && !this.writeToTerminal(terminalArg, RIS)) return;
-    for (const chunk of pending) {
+    for (const chunk of writes) {
       if (!this.writeToTerminal(terminalArg, chunk)) return;
     }
   }
 
+  /**
+   * Queues a restore into xterm's write stream. Resetting and resizing happen in the callback of
+   * the reset, so they take effect exactly at the restore's position in the stream, and the
+   * restore ends in the callback of its snapshot, before xterm parses the next chunk.
+   */
+  private startRestore(terminalArg: Terminal, restoreArg: TerminalRestore): boolean {
+    this.activeRestore?.deferred.resolve();
+    this.activeRestore = restoreArg;
+    this.terminalHost?.classList.add('restoring');
+    try {
+      terminalArg.write(RIS, () => this.applyRestoreSize(terminalArg, restoreArg));
+      terminalArg.write(restoreArg.data, () => this.finishRestore(restoreArg));
+      return true;
+    } catch (error) {
+      // xterm refused the snapshot at its flow-control watermark. A reset it did accept is parsed
+      // later, finds the restore inactive and leaves the grid alone.
+      this.endRestore();
+      this.reportError(error);
+      restoreArg.deferred.reject(error);
+      return false;
+    }
+  }
+
+  private applyRestoreSize(terminalArg: Terminal, restoreArg: TerminalRestore): void {
+    if (this.activeRestore !== restoreArg) return;
+    terminalArg.resize(restoreArg.size.cols, restoreArg.size.rows);
+    // The host serialized the snapshot at this grid, so it is the size the host already knows:
+    // the closing refit reports only a difference from it.
+    this.lastReportedSize = gridKey(restoreArg.size);
+  }
+
+  private finishRestore(restoreArg: TerminalRestore): void {
+    // A superseded restore was settled when the newer one started.
+    if (this.activeRestore !== restoreArg) return;
+    this.endRestore();
+    restoreArg.deferred.resolve();
+  }
+
+  /**
+   * Hands the grid back to the container: one refit, then the terminal is revealed. The refit
+   * dispatches `terminal-resize` synchronously, and a restore its listener starts keeps the
+   * terminal hidden.
+   */
+  private endRestore(): void {
+    this.activeRestore = undefined;
+    this.refit();
+    if (!this.activeRestore) this.terminalHost?.classList.remove('restoring');
+  }
+
   /** xterm throws at its own flow-control watermark; that has to reach the host. */
   private writeToTerminal(terminalArg: Terminal, chunkArg: string | Uint8Array): boolean {
     try {
@@ -371,6 +611,10 @@ export class DeesTerminalView extends DeesElement {
     );
   }
 
+  private get terminalHost(): HTMLElement | null {
+    return this.shadowRoot?.querySelector<HTMLElement>('.terminalHost') ?? null;
+  }
+
   private ensureTerminal(signalArg: AbortSignal): Promise<void> {
     if (this.terminal) return Promise.resolve();
     if (!this.setupPromise) this.setupPromise = this.setupTerminal(signalArg);
@@ -397,7 +641,7 @@ export class DeesTerminalView extends DeesElement {
     ]);
     // The load was awaited: the element may have been detached meanwhile.
     if (signalArg.aborted || !this.isConnected) return;
-    const host = this.shadowRoot?.querySelector<HTMLElement>('.terminalHost');
+    const host = this.terminalHost;
     if (!host) return;
     const computed = getComputedStyle(this);
     const themeColor = (nameArg: string, fallbackArg: string): string => {
@@ -444,17 +688,23 @@ export class DeesTerminalView extends DeesElement {
     this.refit();
     this.resizeObserver = new ResizeObserver(() => this.refit());
     this.resizeObserver.observe(host);
+    // An explicit focus() that arrived before the terminal existed is honoured now, once.
+    if (this.focusWhenReady) {
+      this.focusWhenReady = false;
+      terminal.focus();
+    }
     this.readyResolve();
   }
 
   private refit(): void {
-    if (!this.terminal || !this.fitAddon) return;
+    // A restore owns the grid until its snapshot is parsed and refits once when it ends.
+    if (!this.terminal || !this.fitAddon || this.activeRestore) return;
     try {
       this.fitAddon.fit();
     } catch {
       return;
     }
-    const size = `${this.terminal.rows}x${this.terminal.cols}`;
+    const size = gridKey(this.terminal);
     if (size === this.lastReportedSize) return;
     this.lastReportedSize = size;
     const detail: ITerminalResizeDetail = {
@@ -471,6 +721,11 @@ export class DeesTerminalView extends DeesElement {
     this.resizeObserver = undefined;
     this.inputDisposable?.dispose();
     this.inputDisposable = undefined;
+    // A disposed terminal never parses the rest of its queue, so a restore in flight would
+    // otherwise stay pending forever; the snapshot is lost with the terminal, like live output.
+    const interruptedRestore = this.activeRestore;
+    this.activeRestore = undefined;
+    this.terminalHost?.classList.remove('restoring');
     this.terminal?.dispose();
     this.terminal = undefined;
     this.fitAddon = undefined;
@@ -478,6 +733,9 @@ export class DeesTerminalView extends DeesElement {
     // re-announce its grid and may retry a load that failed.
     this.lastReportedSize = '';
     this.setupPromise = undefined;
+    // A focus request belongs to the connection it was made in; a reattached element must not
+    // grab the caret from wherever the user moved it meanwhile.
+    this.focusWhenReady = false;
     // Buffered output deliberately survives, so a replay that arrived while the
     // element was detached still reaches the next connection.
     if (this.readyPending) {
@@ -485,5 +743,8 @@ export class DeesTerminalView extends DeesElement {
         new Error('dees-terminal-view was disconnected before the terminal became ready'),
       );
     }
+    interruptedRestore?.deferred.reject(
+      new Error('dees-terminal-view was disconnected before the restore completed'),
+    );
   }
 }

package/ts_web/elements/00group-harness/harness.styles.ts

@@ -110,3 +110,119 @@ export const harnessMonoStyles: CSSResult = css`
     text-decoration: underline;
   }
 `;
+
+/**
+ * Panel chrome of the harness sidebars: a full-height column of collapsible
+ * sections, each a heading button (chevron, optional icon, label, right-aligned
+ * summary) above the scrolling body of the expanded section. Shared by
+ * `dees-harness-sidebar` and `dees-harness-session-sidebar` so a host-composed
+ * panel and the session panel are the same surface. It expects the
+ * `.sidebar` > `.section` > `.sectionHeading` + `.sectionContent` structure and
+ * styles the element itself, so it belongs to those two elements only.
+ */
+export const harnessSidebarStyles: CSSResult = css`
+  :host {
+    display: flex;
+    flex-direction: column;
+    min-width: 0;
+    min-height: 0;
+    height: 100%;
+    font-family: var(--dees-font-family);
+    color: var(--dees-color-text-primary);
+  }
+
+  .sidebar {
+    display: flex;
+    flex-direction: column;
+    min-height: 0;
+    height: 100%;
+    overflow: hidden;
+  }
+
+  .section {
+    display: flex;
+    flex: 0 0 auto;
+    flex-direction: column;
+    min-height: 0;
+    overflow: hidden;
+    border-bottom: 1px solid var(--dees-color-border-subtle);
+  }
+
+  .section.expanded {
+    flex: 1 1 0;
+  }
+
+  .section:last-child {
+    border-bottom: 0;
+  }
+
+  .sectionHeading {
+    display: flex;
+    flex: 0 0 auto;
+    align-items: center;
+    gap: var(--dees-spacing-xs);
+    width: 100%;
+    min-height: 36px;
+    margin: 0;
+    padding: 6px 12px 6px 8px;
+    border: 0;
+    background: var(--dees-color-bg-canvas);
+    color: var(--dees-color-text-primary);
+    font-family: inherit;
+    font-size: var(--dees-font-control-size-sm, 12px);
+    font-weight: 600;
+    text-align: left;
+    cursor: pointer;
+  }
+
+  .sectionHeading:hover {
+    background: var(--dees-color-badge-default-bg);
+  }
+
+  .sectionHeading:focus-visible {
+    position: relative;
+    z-index: 1;
+    outline: 2px solid var(--dees-color-accent-primary);
+    outline-offset: -2px;
+  }
+
+  .sectionHeading dees-icon {
+    flex: 0 0 auto;
+    color: var(--dees-color-text-secondary);
+  }
+
+  .sectionHeadingText {
+    min-width: 0;
+    flex-shrink: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .sectionSummary {
+    flex: 0 1 auto;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    margin-left: auto;
+    color: var(--dees-color-text-muted);
+    font-size: 11px;
+    font-variant-numeric: tabular-nums;
+    font-weight: 500;
+  }
+
+  .sectionContent {
+    flex: 1;
+    min-height: 0;
+    overflow-x: hidden;
+    overflow-y: auto;
+    padding: var(--dees-spacing-sm) var(--dees-spacing-md);
+    scrollbar-width: thin;
+    scrollbar-color: var(--dees-color-scrollbar-thumb) transparent;
+  }
+
+  .sectionContent[hidden] {
+    display: none;
+  }
+`;

package/ts_web/elements/00group-harness/index.ts

@@ -20,6 +20,7 @@ export * from './dees-harness-message-list/index.js';
 export * from './dees-harness-reasoning/index.js';
 export * from './dees-harness-session-list/index.js';
 export * from './dees-harness-session-sidebar/index.js';
+export * from './dees-harness-sidebar/index.js';
 export * from './dees-terminal-view/index.js';
 export * from './dees-harness-status/index.js';
 export * from './dees-harness-todos/index.js';