@design.estate/dees-catalog 10.0.0 → 11.0.0

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

@@ -29,13 +29,46 @@ export interface ITerminalResizeDetail {
   cols: number;
 }
 
+/**
+ * Detail of `terminal-error`: xterm could not be loaded, or the live terminal
+ * refused output. The element stays usable and keeps buffering.
+ */
+export interface ITerminalErrorDetail {
+  error: unknown;
+}
+
+/**
+ * Upper bound on output buffered while no terminal is live, in bytes.
+ * `Uint8Array` chunks count their `byteLength`, strings their UTF-16 memory
+ * (two bytes per code unit). Beyond the bound the oldest chunks are dropped,
+ * and the flush then emits RIS before the survivors so a truncated prefix is
+ * never rendered as if it were contiguous output.
+ */
+export const maxPendingWriteBytes = 8 * 1024 * 1024;
+
+/**
+ * RIS (ESC c), a hard reset carried *inside* the write stream: xterm parses it
+ * in order and routes it to the very same `Terminal.reset()` (InputHandler's
+ * ESC-c handler calls `fullReset()`, which fires `onRequestReset`, which
+ * `Terminal` handles with `reset()`), whereas calling `reset()` directly is
+ * documented as out of band with the pending write queue.
+ */
+const RIS = '\x1bc';
+
+/** Memory cost of one buffered chunk, in bytes. */
+const chunkByteLength = (chunkArg: string | Uint8Array): number =>
+  typeof chunkArg === 'string' ? chunkArg.length * 2 : chunkArg.byteLength;
+
 /**
  * Transport-agnostic xterm.js surface: the host pipes remote PTY output into
  * `write()` and receives keystrokes via `terminal-input` — no process,
  * runtime, or socket coupling. `terminal-resize` reports the grid size after
- * every refit so the host can negotiate a PTY size. xterm loads through
- * DeesServiceLibLoader; CSP-locked hosts can pre-register bundled modules
- * with `provideXtermModules()` to avoid the CDN.
+ * 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.
  */
 @customElement('dees-terminal-view')
 export class DeesTerminalView extends DeesElement {
@@ -54,9 +87,37 @@ export class DeesTerminalView extends DeesElement {
   private resizeObserver: ResizeObserver | undefined;
   private inputDisposable: { dispose(): void } | undefined;
   private lastReportedSize = '';
-  // Output that arrives before xterm finished loading is replayed in order.
+  // Output that arrives before xterm is live is replayed in order, bounded by
+  // maxPendingWriteBytes and retained across a disconnect.
   private pendingWrites: Array<string | Uint8Array> = [];
+  private pendingWriteBytes = 0;
+  private pendingWritesDropped = false;
   private setupPromise: Promise<void> | undefined;
+  private readyPending = true;
+  private readyResolve: () => void = () => undefined;
+  private readyReject: (reasonArg: unknown) => void = () => undefined;
+
+  /**
+   * Resolves once the terminal of the current connection is live; a fresh
+   * promise is created for every connection. It rejects with the load error
+   * when xterm cannot be loaded (`terminal-error` carries the same error), and
+   * when the element is disconnected before the terminal came up.
+   */
+  public ready: Promise<void>;
+
+  constructor() {
+    super();
+    this.ready = this.createReadyPromise();
+    // The house lifecycle: startup runs on every connection with an abort
+    // signal, garbage on every disconnection, so a reattached element is a
+    // live surface again instead of a permanently dead one.
+    this.registerStartupFunction(async (signalArg) => {
+      await this.ensureTerminal(signalArg);
+    });
+    this.registerGarbageFunction(() => {
+      this.teardownTerminal();
+    });
+  }
 
   public static styles = [
     themeDefaultStyles,
@@ -209,43 +270,133 @@ export class DeesTerminalView extends DeesElement {
     return html`<div class="terminalHost"></div>`;
   }
 
-  public async firstUpdated(): Promise<void> {
-    this.setupPromise = this.setupTerminal();
-    await this.setupPromise;
+  public connectedCallback(): Promise<void> {
+    // A consumer awaiting readiness after reattaching must not be handed the
+    // settled promise of the previous connection.
+    if (!this.readyPending) this.ready = this.createReadyPromise();
+    return super.connectedCallback();
   }
 
   /** Feed remote output into the terminal; safe to call before setup finishes. */
   public write(dataArg: string | Uint8Array): void {
-    if (this.terminal) {
-      this.terminal.write(dataArg);
-    } else {
-      this.pendingWrites.push(dataArg);
+    // While detached the terminal is about to be disposed, so output belongs in
+    // the buffer rather than in a surface nobody will see again.
+    if (this.terminal && this.isConnected) {
+      this.writeToTerminal(this.terminal, dataArg);
+      return;
     }
+    this.bufferWrite(dataArg);
   }
 
   /** Reset the screen and scrollback, e.g. before a full replay. */
   public clear(): void {
-    this.pendingWrites = [];
-    this.terminal?.reset();
+    const terminal = this.terminal;
+    if (terminal && this.isConnected) {
+      this.writeToTerminal(terminal, RIS);
+      return;
+    }
+    // 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;
   }
 
   public focus(): void {
     this.terminal?.focus();
   }
 
-  /** Current grid size, or undefined while xterm is still loading. */
+  /** Current grid size, or undefined while no terminal is live. */
   public get currentSize(): ITerminalResizeDetail | undefined {
     if (!this.terminal) return undefined;
     return { rows: this.terminal.rows, cols: this.terminal.cols };
   }
 
-  private async setupTerminal(): Promise<void> {
+  private createReadyPromise(): Promise<void> {
+    this.readyPending = true;
+    const promise = new Promise<void>((resolveArg, rejectArg) => {
+      this.readyResolve = () => {
+        this.readyPending = false;
+        resolveArg();
+      };
+      this.readyReject = (reasonArg) => {
+        this.readyPending = false;
+        rejectArg(reasonArg);
+      };
+    });
+    // A readiness promise nobody awaits must never surface as an unhandled
+    // rejection; consumers that do await it still observe the reason.
+    promise.catch(() => undefined);
+    return promise;
+  }
+
+  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);
+      this.pendingWritesDropped = true;
+    }
+  }
+
+  private flushPendingWrites(terminalArg: Terminal): void {
+    const pending = this.pendingWrites;
+    const dropped = this.pendingWritesDropped;
+    this.pendingWrites = [];
+    this.pendingWriteBytes = 0;
+    this.pendingWritesDropped = false;
+    if (dropped && !this.writeToTerminal(terminalArg, RIS)) return;
+    for (const chunk of pending) {
+      if (!this.writeToTerminal(terminalArg, chunk)) return;
+    }
+  }
+
+  /** xterm throws at its own flow-control watermark; that has to reach the host. */
+  private writeToTerminal(terminalArg: Terminal, chunkArg: string | Uint8Array): boolean {
+    try {
+      terminalArg.write(chunkArg);
+      return true;
+    } catch (error) {
+      this.reportError(error);
+      return false;
+    }
+  }
+
+  private reportError(errorArg: unknown): void {
+    if (this.readyPending) this.readyReject(errorArg);
+    const detail: ITerminalErrorDetail = { error: errorArg };
+    this.dispatchEvent(
+      new CustomEvent('terminal-error', { detail, bubbles: true, composed: true }),
+    );
+  }
+
+  private ensureTerminal(signalArg: AbortSignal): Promise<void> {
+    if (this.terminal) return Promise.resolve();
+    if (!this.setupPromise) this.setupPromise = this.setupTerminal(signalArg);
+    return this.setupPromise;
+  }
+
+  private async setupTerminal(signalArg: AbortSignal): Promise<void> {
+    try {
+      await this.createTerminal(signalArg);
+    } catch (error) {
+      this.reportError(error);
+    } finally {
+      // Nothing came up: release the guard so the next connection retries.
+      if (!this.terminal) this.setupPromise = undefined;
+    }
+  }
+
+  private async createTerminal(signalArg: AbortSignal): Promise<void> {
+    await this.updateComplete;
     const libLoader = DeesServiceLibLoader.getInstance();
     const [xterm, fit] = await Promise.all([
       libLoader.loadXterm(),
       libLoader.loadXtermFitAddon(),
     ]);
-    if (!this.isConnected) return;
+    // The load was awaited: the element may have been detached meanwhile.
+    if (signalArg.aborted || !this.isConnected) return;
     const host = this.shadowRoot?.querySelector<HTMLElement>('.terminalHost');
     if (!host) return;
     const computed = getComputedStyle(this);
@@ -265,9 +416,21 @@ export class DeesTerminalView extends DeesElement {
         cursor: themeColor('--dees-color-accent-primary', '#e6e6e6'),
       },
     });
-    const fitAddon = new fit.FitAddon();
-    terminal.loadAddon(fitAddon);
-    terminal.open(host);
+    let fitAddon: FitAddon;
+    try {
+      fitAddon = new fit.FitAddon();
+      terminal.loadAddon(fitAddon);
+      terminal.open(host);
+    } catch (error) {
+      // The element does not own this instance yet, so teardown cannot reach
+      // it; a half-opened terminal would otherwise leak with its DOM attached.
+      try {
+        terminal.dispose();
+      } catch {
+        // Disposing a half-opened terminal must not mask the real failure.
+      }
+      throw error;
+    }
     this.terminal = terminal;
     this.fitAddon = fitAddon;
     this.inputDisposable = terminal.onData((dataArg) => {
@@ -277,11 +440,11 @@ export class DeesTerminalView extends DeesElement {
         new CustomEvent('terminal-input', { detail, bubbles: true, composed: true }),
       );
     });
-    for (const pending of this.pendingWrites) terminal.write(pending);
-    this.pendingWrites = [];
+    this.flushPendingWrites(terminal);
     this.refit();
     this.resizeObserver = new ResizeObserver(() => this.refit());
     this.resizeObserver.observe(host);
+    this.readyResolve();
   }
 
   private refit(): void {
@@ -303,8 +466,7 @@ export class DeesTerminalView extends DeesElement {
     );
   }
 
-  public async disconnectedCallback(): Promise<void> {
-    await super.disconnectedCallback();
+  private teardownTerminal(): void {
     this.resizeObserver?.disconnect();
     this.resizeObserver = undefined;
     this.inputDisposable?.dispose();
@@ -312,6 +474,16 @@ export class DeesTerminalView extends DeesElement {
     this.terminal?.dispose();
     this.terminal = undefined;
     this.fitAddon = undefined;
-    this.pendingWrites = [];
+    // Instance state of the finished connection: a reattached element has to
+    // re-announce its grid and may retry a load that failed.
+    this.lastReportedSize = '';
+    this.setupPromise = undefined;
+    // Buffered output deliberately survives, so a replay that arrived while the
+    // element was detached still reaches the next connection.
+    if (this.readyPending) {
+      this.readyReject(
+        new Error('dees-terminal-view was disconnected before the terminal became ready'),
+      );
+    }
   }
 }

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

@@ -361,6 +361,23 @@ export interface IHarnessSessionMeta {
   draggable?: boolean;
 }
 
+/** Discriminates the two kinds of rows the session list orders as peers. */
+export type THarnessSessionListItemKind = 'session' | 'resource';
+
+/**
+ * Stable reference to one ordered row. Session ids and resource ids are
+ * separate namespaces, so ordering always carries the kind alongside the id.
+ */
+export interface IHarnessSessionListItemRef {
+  kind: THarnessSessionListItemKind;
+  id: string;
+}
+
+/** Detail of `harness-session-select` and `harness-session-open`. */
+export interface IHarnessSessionEventDetail {
+  session: IHarnessSessionMeta;
+}
+
 /** Host-owned metadata for a resource that can be associated with a harness session. */
 export interface IHarnessResourceMeta<TState extends string = string> {
   /** Stable identity used by selection and association records. */
@@ -375,41 +392,51 @@ export interface IHarnessResourceMeta<TState extends string = string> {
   updatedAt?: number;
   /** Optional host-defined display state. */
   state?: TState;
+  /** Set false for pinned, non-sortable entries. Defaults to true. */
+  draggable?: boolean;
 }
 
-/** A controlled zero-or-one session association for one resource. */
+/**
+ * A controlled zero-or-one association for one resource. The target is any
+ * other list item — a session or another resource such as a terminal.
+ */
 export interface IHarnessResourceAssociation {
   resourceId: string;
-  sessionId: string;
+  target: IHarnessSessionListItemRef;
 }
 
 export interface IHarnessResourceEventDetail<TState extends string = string> {
   resource: IHarnessResourceMeta<TState>;
-  sessionId: string | null;
+  /** The controlled association target, or null when the resource is unattached. */
+  target: IHarnessSessionListItemRef | null;
 }
 
-export type THarnessResourceAssociationInteractionSource = 'drop' | 'action' | 'keyboard';
+/**
+ * Association is an explicit host action, never a drop: dragging a resource
+ * only moves it inside the ordered list.
+ */
+export type THarnessResourceAssociationInteractionSource = 'action' | 'keyboard';
 
 export type THarnessResourceAssociationRequestDetail<TState extends string = string> =
   | {
       intent: 'attach';
       resource: IHarnessResourceMeta<TState>;
-      fromSessionId: null;
-      toSessionId: string;
+      fromTarget: null;
+      toTarget: IHarnessSessionListItemRef;
       source: THarnessResourceAssociationInteractionSource;
     }
   | {
       intent: 'detach';
       resource: IHarnessResourceMeta<TState>;
-      fromSessionId: string;
-      toSessionId: null;
+      fromTarget: IHarnessSessionListItemRef;
+      toTarget: null;
       source: THarnessResourceAssociationInteractionSource;
     }
   | {
       intent: 'reassign';
       resource: IHarnessResourceMeta<TState>;
-      fromSessionId: string;
-      toSessionId: string;
+      fromTarget: IHarnessSessionListItemRef;
+      toTarget: IHarnessSessionListItemRef;
       source: THarnessResourceAssociationInteractionSource;
     };
 
@@ -423,7 +450,7 @@ export interface IHarnessResourceContextDetail<TState extends string = string>
   source: THarnessResourceContextSource;
   originalEvent: MouseEvent | KeyboardEvent;
   /** Routes a host menu choice through the component's validated controlled request event. */
-  requestAssociation: (toSessionId: string | null) => boolean;
+  requestAssociation: (toTarget: IHarnessSessionListItemRef | null) => boolean;
   /** Closes the external-menu disclosure state and restores focus to its invoking control. */
   close: () => void;
 }
@@ -438,22 +465,35 @@ export interface IHarnessSessionContextDetail {
   originalEvent: MouseEvent;
 }
 
-/** A user-defined session group; ordering of `sessionIds` is the display order. */
+/**
+ * A user-defined group of list items; ordering of `itemIds` is the display
+ * order. Sessions and resources may be members in any interleaving.
+ */
 export interface IHarnessSessionGroup {
   id: string;
   name: string;
-  sessionIds: string[];
+  itemIds: IHarnessSessionListItemRef[];
 }
 
-/** Detail of `harness-session-move`: a session was dropped into a group slot. */
-export interface IHarnessSessionMoveDetail {
-  sessionId: string;
+export type THarnessItemMoveSource = 'pointer' | 'keyboard';
+
+/** Detail of `harness-item-move`: one item landed in a new ordered position. */
+export interface IHarnessItemMoveDetail {
+  item: IHarnessSessionListItemRef;
+  /** Group the item came from, or null for the ungrouped section. */
+  fromGroupId: string | null;
   /** Target group, or null for the ungrouped section. */
+  toGroupId: string | null;
+  /** Stable target anchor in the dragged-item-excluded order; null means append. */
+  beforeItem: IHarnessSessionListItemRef | null;
+  source: THarnessItemMoveSource;
+}
+
+/** The open insertion slot a drag currently targets. */
+export interface IDropSlot {
   groupId: string | null;
-  /** Compatibility insertion index using the pre-drag order for same-section moves. */
+  /** Index within the section's sortable, dragged-item-excluded order. */
   index: number;
-  /** Stable target anchor in the dragged-card-excluded order; absent means append. */
-  beforeSessionId?: string;
 }
 
 /** Detail of `harness-group-context`, fired on right-click of a group header. */