@hex1b/web-terminal 0.173.0-alpha.1801.1.3dc2d9b → 0.173.0

package/README.md

@@ -169,6 +169,7 @@ const container = document.getElementById("terminal");
 if (!container) throw new Error("Missing terminal container");
 const terminal = await WebTerminal.mount(container, {
   url: "/ws/terminal",
+  preserveOnDisconnect: true,
   colorMode: "system", // "light", "dark", or the browser's prefers-color-scheme.
   lightModePalette: { ...defaultLightPalette, background: "#fafafa" },
   darkModePalette: { ...defaultDarkPalette, background: "#202020" },
@@ -297,7 +298,41 @@ view after transport loss or leave an ended tab/dialog visible. Abort, explicit
 disposal, mount timeout, and local initialization/renderer failures do not
 synthesize `onClose`; no callback runs after disposal. Callback exceptions are
 reported to the host, not swallowed or retried, and do not leave mounting pending.
-The API does not retain the producer after exit or promise a final rendered frame.
+Set `preserveOnDisconnect: true` to finish presenting the last accepted complete
+frame before `onClose` and keep it visible until `dispose()`. The retained view
+can repaint when its container or palette changes, but input and producer-backed
+history, selection, and copying are disconnected. Cursor/text blinking stops.
+The default is `false`, preserving the existing renderer-release behavior.
+Explicit disposal or abort still removes the view and releases its GPU resources.
+Local rendering failures cannot guarantee preservation.
+
+Preservation retains the received KGP and Sixel textures and placements, including
+PNG/compressed KGP, cropped and relative placements, Unicode placeholders, and
+the current server-driven animation frame. Animation freezes rather than replaying
+locally. Styled/wide/combining text, DEC enlarged rows, the current alternate
+screen, link decorations already presented, selection highlights, viewport text,
+markers, and activity metadata remain available for display and local redraw.
+Link activation and producer-backed navigation/copy operations stop. Only the
+current received history viewport is retained, not a browsable offline scrollback
+archive; historical HWT1 viewports do not currently include graphics.
+
+Preservation alone cannot recover bytes the server never sent. On the server,
+await `Hex1bTerminal.RunAsync()` to finish consuming process output, then await
+`Hwt1PresentationAdapter.DrainAsync(cancellationToken)` **while the frame sender
+and client-message receiver remain running**. Only after the drain completes
+should the host cancel those loops, close the transport, and dispose the
+producer. The drain requests a fresh snapshot and waits for the final
+presentation acknowledgement, including all marker inventory pages; its total
+wait is bounded by `AcknowledgementTimeout`, and cancellation or timeout reports
+failure rather than claiming delivery. An HMP1 replica must also finish consuming
+its ordered output before its HWT1 drain. The demo does this for direct and relay
+views on normal workload exit.
+
+HWT1 transfers coalesced terminal state, not every intermediate output event.
+The guarantee is the final retained terminal view, not an unlimited output log.
+Abrupt network loss can retain only the last complete frame actually received;
+it cannot promise the producer's final state. The API does not retain the producer
+after exit.
 
 ### Browser and deployment requirements
 
@@ -425,6 +460,7 @@ does not claim universal or individually verified bundler support.
 | `label` | Accessible label for the terminal's hidden keyboard input. |
 | `onTitleChange` | Initial authoritative workload title, then distinct presented changes; see below. |
 | `onClose` | Native WebSocket close details, including pre-mount transport failure; not workload completion. |
+| `preserveOnDisconnect` | Opt-in final-frame presentation and retained display after transport close, until disposal; defaults to `false`. |
 | `onProgressChange`, `onShellIntegrationChange` | Initial authoritative activity, then distinct presented changes for host-owned chrome. |
 | `onWorkingDirectoryChange`, `onCommandMarkChange` | Initial authoritative OSC 7 directory and latest OSC 133 marker, then distinct presented changes; see below. |
 | `inputBindings`, `onInput`, `actions` | Per-view input policy and custom actions. |

package/dist/index.js

@@ -767,9 +767,14 @@ var init_transport_session = __esm({
       #ready = Promise.withResolvers();
       #connection;
       #frame = false;
+      #receiving;
+      #closing = false;
       #sending = false;
       #queue = [];
       #bytes = 0;
+      get closing() {
+        return this.#closing;
+      }
       start(transport2) {
         void this.#connect(transport2);
       }
@@ -777,16 +782,20 @@ var init_transport_session = __esm({
         try {
           const connection = await transport2.connect({
             signal: this.#abort.signal,
-            onFrame: (frame) => this.#receive(frame),
+            onFrame: (frame) => {
+              const receiving = this.#receive(frame);
+              this.#receiving = receiving;
+              return receiving;
+            },
             onClose: (details) => {
-              if (this.#abort.signal.aborted) return;
+              if (this.#abort.signal.aborted || this.#closing) return;
               if (!details || typeof details.reason !== "string" || details.code !== void 0 && (!Number.isInteger(details.code) || typeof details.wasClean !== "boolean")) {
                 this.#fail(new TypeError("Invalid terminal transport close details"));
                 return;
               }
               const snapshot = details.code === void 0 ? { reason: details.reason } : { code: details.code, reason: details.reason, wasClean: details.wasClean };
-              this.dispose();
-              this.callbacks.onClose(snapshot);
+              this.#closing = true;
+              void this.#close(snapshot);
             },
             onError: (error) => this.#fail(error)
           });
@@ -806,6 +815,7 @@ var init_transport_session = __esm({
       async #receive(frame) {
         try {
           this.#abort.signal.throwIfAborted();
+          if (this.#closing) throw new Error("Terminal transport is closing");
           if (this.#frame) throw new Error("Concurrent terminal transport frames are not allowed");
           if (!(frame instanceof ArrayBuffer) && !(frame instanceof Uint8Array && frame.buffer instanceof ArrayBuffer))
             throw new TypeError("Transport frames must be ArrayBuffer or Uint8Array backed by ArrayBuffer");
@@ -823,8 +833,19 @@ var init_transport_session = __esm({
           throw error;
         }
       }
+      async #close(details) {
+        try {
+          await this.#receiving;
+        } catch {
+          return;
+        }
+        if (this.#abort.signal.aborted) return;
+        this.dispose();
+        this.callbacks.onClose(details);
+      }
       send(control) {
         if (this.#abort.signal.aborted) return Promise.reject(this.#abort.signal.reason);
+        if (this.#closing) return Promise.reject(new DOMException("Terminal transport is closing", "AbortError"));
         const bytes = new TextEncoder().encode(control).byteLength;
         if (this.#queue.length >= 256 || this.#bytes + bytes > 1024 * 1024) {
           const error = new Error("Terminal transport control queue exceeded its bounded capacity");
@@ -842,7 +863,7 @@ var init_transport_session = __esm({
         this.#sending = true;
         try {
           await this.#ready.promise;
-          while (!this.#abort.signal.aborted && this.#queue.length) {
+          while (!this.#abort.signal.aborted && !this.#closing && this.#queue.length) {
             const item = this.#queue[0];
             await this.#connection.send(item.control);
             if (this.#abort.signal.aborted) return;
@@ -851,7 +872,7 @@ var init_transport_session = __esm({
             item.resolve();
           }
         } catch (error) {
-          this.#fail(error);
+          if (!this.#closing) this.#fail(error);
         } finally {
           this.#sending = false;
         }
@@ -2503,10 +2524,21 @@ function postStatus(message, level = "info") {
   self.postMessage({ type: "status", message, level });
 }
 function send(message) {
-  if (stats.connected && !failed && !stopped) void transport?.send(JSON.stringify(message)).catch(fail);
+  if (stats.connected && !disconnected && !transport?.closing && !failed && !stopped) {
+    void transport?.send(JSON.stringify(message)).catch((error) => {
+      if (!transport?.closing) fail(error);
+    });
+  }
 }
 function emitStats(text) {
   if (renderer && !renderer.disposed) Object.assign(stats, renderer.metrics());
+  else if (renderer?.disposed) Object.assign(stats, {
+    imageCount: 0,
+    textureBytes: 0,
+    atlasGlyphs: 0,
+    atlasBytes: 0,
+    instanceBufferBytes: 0
+  });
   self.postMessage({ type: "stats", stats: { ...stats }, ...text === void 0 ? {} : { text } });
 }
 function fail(error) {
@@ -2524,11 +2556,11 @@ function fail(error) {
 }
 function scheduleRender() {
   needsRender = true;
-  if (scheduled || drawing || processing || failed || stopped || !metadata || markerPages.pending || awaitingFull) return;
+  if (scheduled || drawing || processing || failed || stopped || disconnected && stats.connected || !metadata || markerPages.pending || awaitingFull) return;
   scheduled = true;
   self.requestAnimationFrame(() => {
     scheduled = false;
-    if (processing || drawing || failed || stopped || markerPages.pending || awaitingFull) return;
+    if (processing || drawing || failed || stopped || disconnected && stats.connected || markerPages.pending || awaitingFull) return;
     renderPromise = drawFrame();
   });
 }
@@ -2541,7 +2573,7 @@ async function drawFrame() {
     if (frame) links.prepare(cells, metadata);
     const linkSubmission = links.submission();
     renderer.resize(metadata.columns, metadata.rows, viewport);
-    const blink = Math.floor(performance.now() / 600) % 2 === 0;
+    const blink = disconnected || Math.floor(performance.now() / 600) % 2 === 0;
     const result = renderer.render(cells, metadata, blink, linkSubmission.mask, palette);
     await renderer.idle();
     if (failed || stopped) return;
@@ -2605,7 +2637,7 @@ async function drawFrame() {
   }
 }
 async function receiveFrame(buffer) {
-  if (failed || stopped || !renderer) return;
+  if (failed || stopped || disconnected || !renderer) return;
   if (frameInFlight) throw new Error("Server sent a second state frame before acknowledgement");
   frameInFlight = true;
   processing = true;
@@ -2666,6 +2698,7 @@ async function receiveFrame(buffer) {
 }
 async function initialize(message) {
   if (renderer || transport) throw new Error("Worker is already initialized");
+  preserveOnDisconnect = message.preserveOnDisconnect ?? false;
   palette = compilePalette(normalizePalette(message.palette === void 0 ? defaultDarkPalette : message.palette));
   if (typeof self.requestAnimationFrame !== "function") {
     throw new Error("This browser does not support requestAnimationFrame in a dedicated OffscreenCanvas worker");
@@ -2693,17 +2726,31 @@ async function initialize(message) {
     onFrame: receiveFrame,
     onError: fail,
     onClose(details) {
-      if (failed || stopped) return;
-      stats.connected = false;
-      stats.gpu = "stopped";
-      stats.fps = 0;
-      stopped = true;
+      if (failed || stopped || disconnected) return;
+      disconnected = true;
       clearInterval(metricsTimer);
       clearInterval(blinkTimer);
-      renderer?.dispose();
-      self.postMessage({ type: "closed", details });
-      postStatus(`View disconnected (${details.code === void 0 ? details.reason : `${details.code}${details.reason ? `: ${details.reason}` : ""}`}). Attach another view to reconnect.`, "error");
-      emitStats();
+      void finishClose().catch(fail);
+      async function finishClose() {
+        if (preserveOnDisconnect) {
+          await renderPromise;
+          if (failed || stopped) return;
+          if ((needsRender || hasBlink && !lastBlink) && !markerPages.pending && !awaitingFull) {
+            needsRender = true;
+            await drawFrame();
+          }
+          if (failed || stopped) return;
+        } else {
+          stopped = true;
+          renderer?.dispose();
+        }
+        stats.connected = false;
+        stats.gpu = "stopped";
+        stats.fps = 0;
+        self.postMessage({ type: "closed", details });
+        postStatus(`View disconnected (${details.code === void 0 ? details.reason : `${details.code}${details.reason ? `: ${details.reason}` : ""}`}). Attach another view to reconnect.`, "error");
+        emitStats();
+      }
     }
   });
   metricsTimer = setInterval(() => {
@@ -2732,7 +2779,7 @@ async function initialize(message) {
     }
   });
 }
-var renderer, transport, bridge, bridgeReady, bridgeSent, failed, stopped, processing, drawing, frameInFlight, scheduled, needsRender, hasBlink, lastBlink, metadata, cells, localRevision, pendingFrame, renderPromise, metricsTimer, blinkTimer, viewport, links, markerPages, awaitingFull, requestedColorEncoding, palette, stats, sample;
+var renderer, transport, bridge, bridgeReady, bridgeSent, failed, stopped, disconnected, preserveOnDisconnect, processing, drawing, frameInFlight, scheduled, needsRender, hasBlink, lastBlink, metadata, cells, localRevision, pendingFrame, renderPromise, metricsTimer, blinkTimer, viewport, links, markerPages, awaitingFull, requestedColorEncoding, palette, stats, sample;
 var init_terminal_worker = __esm({
   "src/terminal-worker.ts"() {
     "use strict";
@@ -2746,6 +2793,8 @@ var init_terminal_worker = __esm({
     init_transport_session();
     failed = false;
     stopped = false;
+    disconnected = false;
+    preserveOnDisconnect = false;
     processing = false;
     drawing = false;
     frameInFlight = false;
@@ -2847,7 +2896,7 @@ var init_terminal_worker = __esm({
         } catch (error) {
           fail(error);
         }
-      } else if (message.type === "linkDetection" && !failed && !stopped) {
+      } else if (message.type === "linkDetection" && !failed && !stopped && !disconnected) {
         try {
           if (!links.configure(message.enabled, message.generation)) return;
           if (!processing && !drawing && !pendingFrame) {
@@ -2858,7 +2907,7 @@ var init_terminal_worker = __esm({
         } catch (error) {
           fail(error);
         }
-      } else if (message.type === "linkDecorations" && !failed && !stopped) {
+      } else if (message.type === "linkDecorations" && !failed && !stopped && !disconnected) {
         try {
           if (links.accept(
             message.revision,
@@ -5496,6 +5545,7 @@ var WebTerminal = class _WebTerminal {
   #connected = false;
   #closed = false;
   #readOnly;
+  #preserveOnDisconnect;
   #disposed = false;
   #hasGeometry = false;
   #resizeTimer;
@@ -5575,6 +5625,9 @@ var WebTerminal = class _WebTerminal {
     if (options.readOnly !== void 0 && typeof options.readOnly !== "boolean")
       throw new TypeError("readOnly must be a boolean");
     this.#readOnly = options.readOnly ?? false;
+    if (options.preserveOnDisconnect !== void 0 && typeof options.preserveOnDisconnect !== "boolean")
+      throw new TypeError("preserveOnDisconnect must be a boolean");
+    this.#preserveOnDisconnect = options.preserveOnDisconnect ?? false;
     this.#renderer = normalizeRenderer(options.renderer);
     this.#colorMode = normalizeColorMode(options.colorMode);
     this.#palettes = {
@@ -5889,7 +5942,8 @@ var WebTerminal = class _WebTerminal {
       scale,
       font,
       renderer: this.#renderer,
-      palette: this.#palettes[this.resolvedColorMode]
+      palette: this.#palettes[this.resolvedColorMode],
+      preserveOnDisconnect: this.#preserveOnDisconnect
     }, [canvas]);
     this.#applyPalette();
     this.#postLinkConfiguration();
@@ -5914,7 +5968,8 @@ var WebTerminal = class _WebTerminal {
       this.#transportSession.start(this.#transport);
     } else if (message.type === "transportSend") {
       void Promise.resolve(this.#transportFrame?.promise).then(() => this.#transportSession?.send(message.control)).then(() => this.#post({ type: "transportSent" })).catch((error) => {
-        if (!this.#disposed) this.#post({ type: "transportError", message: errorMessage(error) });
+        if (!this.#disposed && !this.#transportSession?.closing)
+          this.#post({ type: "transportError", message: errorMessage(error) });
       });
     } else if (message.type === "transportReceived") {
       this.#transportFrame?.resolve();