@hex1b/web-terminal 0.175.0-alpha.1905.1.34394d2 → 0.175.0

package/README.md

@@ -604,6 +604,37 @@ The per-title bound is not a limit on all parser buffering or saved-stack depth.
 An HMP1 snapshot with too much saved title state fails its 16 MiB replay limit
 rather than silently discarding saved titles.
 
+### Program status (OSC 7501)
+
+`terminal.programStatus` is an immutable snapshot of the last presented
+inventory. Its `records` contain `id`, `state`, nullable `kind`, `progress`,
+`app`, `effectiveApp`, `title` and `message`. The empty ID addresses the root;
+other IDs are slash-separated paths. `find(id)` looks up a record and
+`getDescendants(id)` returns existing descendants, excluding the addressed
+record. Parents need not exist, and their states do not aggregate.
+
+Supply `onProgramStatusChange(snapshot)` to receive the initial authoritative
+inventory before mount resolves, then distinct presented updates. The getter
+updates before callbacks. The snapshot and all its records are frozen; older
+snapshots retain their values. Metadata-only updates repaint without cell
+changes. Reports can coalesce between frames: this is current state, not an
+event log. Disconnect/disposal retains the last inventory; check `connected`
+separately.
+
+The states are `idle`, `working`, `blocked`, `done` and `error`. A blocked record
+may specify `permission`, `question` or `auth`. Progress is nullable (indeterminate)
+and applies only to working/blocked records. `effectiveApp` resolves the nearest
+ancestor's reported `app`; `app` retains the record's own reported value.
+Clearing replaces the inventory accordingly, rather than exposing a `clear` state.
+Messages and titles are untrusted plain text, not markup or authenticated identity.
+
+The paired server emits full inventory in every frame. Frames from a
+pre-extension HWT1 server without this field are treated as an empty inventory;
+malformed present inventories are rejected, never converted to empty state.
+No status UI, notifications, approval operations or automatic acknowledgement
+are supplied by the component. A host can build those on this API. See the
+[WebTerminalDemo scenario](../../samples/WebTerminalDemo/README.md#try-osc-7501-program-status).
+
 ### Application progress and shell activity
 
 `terminal.progress` exposes OSC 9;4 state as `{ state, percentage }`.

package/dist/index.js

@@ -396,6 +396,67 @@ var init_terminal_palette = __esm({
   }
 });
 
+// src/program-status.ts
+function text(value, limit) {
+  if (value === null) return;
+  if (typeof value !== "string" || value.length > limit || /[\u0000-\u001f\u007f-\u009f\ud800-\udfff]/u.test(value) || encoder.encode(value).byteLength > limit) throw new Error("Invalid program status text");
+}
+function validateProgramStatus(value) {
+  if (!isRecord(value) || !Array.isArray(value.records) || value.records.length > 256)
+    throw new Error("Invalid program status inventory");
+  const records = /* @__PURE__ */ new Map();
+  for (const record of value.records) {
+    if (!isRecord(record) || typeof record.id !== "string" || record.id !== "" && (!idPattern.test(record.id) || record.id.length > 128) || records.has(record.id)) throw new Error("Invalid or duplicate program status ID");
+    if (typeof record.state !== "string" || !["idle", "working", "blocked", "done", "error"].includes(record.state))
+      throw new Error("Invalid program status state");
+    if (record.kind !== null && (record.state !== "blocked" || typeof record.kind !== "string" || !["permission", "question", "auth"].includes(record.kind)))
+      throw new Error("Invalid program status kind");
+    if (record.progress !== null && (!(record.state === "working" || record.state === "blocked") || typeof record.progress !== "number" || !Number.isInteger(record.progress) || record.progress < 0 || record.progress > 100))
+      throw new Error("Invalid program status progress");
+    for (const app of [record.app, record.effectiveApp])
+      if (app !== null && (typeof app !== "string" || !appPattern.test(app)))
+        throw new Error("Invalid program status application");
+    text(record.title, 192);
+    text(record.message, 2048);
+    records.set(record.id, { id: record.id, app: record.app, effectiveApp: record.effectiveApp });
+  }
+  for (const record of records.values()) {
+    let expected = record.app;
+    let id = record.id;
+    while (expected === null && id !== "") {
+      const slash = id.lastIndexOf("/");
+      id = slash < 0 ? "" : id.slice(0, slash);
+      expected = records.get(id)?.app ?? null;
+    }
+    if (record.effectiveApp !== expected) throw new Error("Inconsistent program status application inheritance");
+  }
+}
+function programStatusSnapshot(inventory) {
+  const records = Object.freeze(inventory.records.map((record) => Object.freeze({ ...record })));
+  const index = new Map(records.map((record) => [record.id, record]));
+  return Object.freeze({
+    records,
+    find: (id) => index.get(id),
+    getDescendants: (id) => Object.freeze(records.filter((record) => record.id !== id && (id === "" || record.id.startsWith(`${id}/`))))
+  });
+}
+function sameProgramStatus(left, right) {
+  return left.records.length === right.records.length && left.records.every((record, index) => {
+    const other = right.records[index];
+    return record.id === other.id && record.state === other.state && record.kind === other.kind && record.progress === other.progress && record.app === other.app && record.effectiveApp === other.effectiveApp && record.title === other.title && record.message === other.message;
+  });
+}
+var encoder, idPattern, appPattern;
+var init_program_status = __esm({
+  "src/program-status.ts"() {
+    "use strict";
+    init_validation();
+    encoder = new TextEncoder();
+    idPattern = /^[A-Za-z0-9_.+-]{1,32}(?:\/[A-Za-z0-9_.+-]{1,32}){0,7}$/u;
+    appPattern = /^[A-Za-z0-9_.+-]{1,32}$/u;
+  }
+});
+
 // src/protocol.ts
 function assertCommandSize(command) {
   if (utf8Encoder.encode(JSON.stringify(command)).byteLength > LIMITS.commandBytes)
@@ -530,6 +591,8 @@ function validateMetadata(metadata2) {
     throw new Error("Invalid terminal title");
   }
   const progress = metadata2.progress;
+  if (metadata2.programStatus === void 0) metadata2.programStatus = { records: [] };
+  validateProgramStatus(metadata2.programStatus);
   if (!isRecord(progress) || typeof progress.state !== "string" || !["none", "normal", "error", "indeterminate", "warning"].includes(progress.state)) {
     throw new Error("Invalid terminal progress");
   }
@@ -700,9 +763,9 @@ function decodeFrame(buffer) {
     offset += 6;
     if (underlineStyle > 5) throw new Error("Unsupported underline style");
     requireBytes(textLength);
-    const text = utf8.decode(new Uint8Array(buffer, offset, textLength));
+    const text2 = utf8.decode(new Uint8Array(buffer, offset, textLength));
     offset += textLength;
-    cells2.push({ index, foreground, background, underlineColor: underlineColor2, attributes, width, underlineStyle, text });
+    cells2.push({ index, foreground, background, underlineColor: underlineColor2, attributes, width, underlineStyle, text: text2 });
   }
   const imageBytes = metadata2.images.reduce((total, image) => total + image.byteLength, 0);
   if (imageBytes !== view.byteLength - offset) throw new Error("Image payload length mismatch");
@@ -733,6 +796,7 @@ var init_protocol = __esm({
     init_validation();
     init_marker_state();
     init_terminal_palette();
+    init_program_status();
     LIMITS = Object.freeze({
       commandBytes: 64 * 1024,
       frameBytes: 96 * 1024 * 1024,
@@ -1343,8 +1407,8 @@ struct VertexOut {
           });
         }
         if (usedBytes) this.device.queue.writeBuffer(this.instanceBuffer, 0, instances, 0, quadCount * QUAD_STRIDE);
-        const encoder = this.device.createCommandEncoder();
-        const pass = encoder.beginRenderPass({
+        const encoder2 = this.device.createCommandEncoder();
+        const pass = encoder2.beginRenderPass({
           colorAttachments: [{
             view: this.context.getCurrentTexture().createView(),
             clearValue: { r: background[0], g: background[1], b: background[2], a: 1 },
@@ -1360,7 +1424,7 @@ struct VertexOut {
           pass.draw(6, batch.count, 0, batch.start);
         }
         pass.end();
-        this.device.queue.submit([encoder.finish()]);
+        this.device.queue.submit([encoder2.finish()]);
       }
       async idle() {
         await this.device.queue.onSubmittedWorkDone();
@@ -2530,7 +2594,7 @@ function send(message) {
     });
   }
 }
-function emitStats(text) {
+function emitStats(text2) {
   if (renderer && !renderer.disposed) Object.assign(stats, renderer.metrics());
   else if (renderer?.disposed) Object.assign(stats, {
     imageCount: 0,
@@ -2539,7 +2603,7 @@ function emitStats(text) {
     atlasBytes: 0,
     instanceBufferBytes: 0
   });
-  self.postMessage({ type: "stats", stats: { ...stats }, ...text === void 0 ? {} : { text } });
+  self.postMessage({ type: "stats", stats: { ...stats }, ...text2 === void 0 ? {} : { text: text2 } });
 }
 function fail(error) {
   if (failed || stopped) return;
@@ -2600,7 +2664,7 @@ async function drawFrame() {
       stats.mouseTracking = metadata.mouseTracking;
       stats.peer = metadata.peer;
       stats.history = metadata.history;
-      const text = screenText(cells, metadata.columns, metadata.rows);
+      const text2 = screenText(cells, metadata.columns, metadata.rows);
       self.postMessage({
         type: "geometry",
         columns: metadata.columns,
@@ -2614,15 +2678,16 @@ async function drawFrame() {
         title: metadata.title,
         progress: metadata.progress,
         shellIntegration: metadata.shellIntegration,
+        programStatus: metadata.programStatus ?? { records: [] },
         workingDirectory: metadata.workingDirectory,
         commandMark: metadata.commandMark,
-        text,
+        text: text2,
         hyperlinks: metadata.hyperlinks,
         lineRenditions: metadata.lineRenditions,
         ...links.present(cells, metadata)
       });
       send({ type: "ack", revision: frame.revision });
-      emitStats(text);
+      emitStats(text2);
     } else {
       const snapshot = links.snapshot();
       if (snapshot) self.postMessage({ type: "linkSnapshot", generation: links.generation, snapshot });
@@ -2930,17 +2995,17 @@ var link_detection_worker_exports = {};
 __export(link_detection_worker_exports, {
   scanLinks: () => scanLinks
 });
-function trimProse(text) {
-  let end = text.length;
+function trimProse(text2) {
+  let end = text2.length;
   const pairs = { ")": "(", "]": "[", "}": "{" };
   while (end > 0) {
-    const char = text[end - 1];
+    const char = text2[end - 1];
     if (".,;:!?".includes(char)) {
       end--;
       continue;
     }
     if (pairs[char]) {
-      const current = text.slice(0, end);
+      const current = text2.slice(0, end);
       if (current.split(char).length > current.split(pairs[char]).length) {
         end--;
         continue;
@@ -2948,7 +3013,7 @@ function trimProse(text) {
     }
     break;
   }
-  return text.slice(0, end);
+  return text2.slice(0, end);
 }
 function scanLinks(request) {
   try {
@@ -2985,22 +3050,22 @@ function scanLinks(request) {
           regex.lastIndex += (regex.unicode || regex.unicodeSets) && point !== void 0 && point > 65535 ? 2 : 1;
           continue;
         }
-        let text = match[0];
+        let text2 = match[0];
         if (builtin) {
           const before = chunk.text[match.index - 1];
           if (before !== void 0 && !/[\s([{"'<>=]/u.test(before)) continue;
-          if (builtin === "uri" && /^[a-z]:[\\/]/iu.test(text)) continue;
-          text = trimProse(text);
-          if (!text || builtin === "absolutePath" && (text === "/" || /^[a-z]:[\\/]$/iu.test(text))) continue;
+          if (builtin === "uri" && /^[a-z]:[\\/]/iu.test(text2)) continue;
+          text2 = trimProse(text2);
+          if (!text2 || builtin === "absolutePath" && (text2 === "/" || /^[a-z]:[\\/]$/iu.test(text2))) continue;
           if (builtin === "url") {
             try {
-              if (!new URL(text).hostname) continue;
+              if (!new URL(text2).hostname) continue;
             } catch {
               continue;
             }
           }
         }
-        const candidate = { index: match.index, text, captures: match.slice(1), groups: { ...match.groups } };
+        const candidate = { index: match.index, text: text2, captures: match.slice(1), groups: { ...match.groups } };
         resultText += linkMatchTextSize(candidate);
         if (resultText > LINK_LIMITS.resultText) {
           return { id: request.id, error: "limit", message: "Link result text limit exceeded" };
@@ -5002,6 +5067,7 @@ var terminalThemeCss = `
 
 // src/web-terminal.ts
 init_protocol();
+init_program_status();
 
 // src/selection-ui.ts
 init_validation();
@@ -5164,26 +5230,26 @@ function extractLinkText(snapshot, mode) {
   const { columns, rows, cells: cells2 } = snapshot;
   if (!Number.isSafeInteger(columns) || !Number.isSafeInteger(rows) || columns < 1 || rows < 1 || columns * rows > LINK_LIMITS.cells) throw new RangeError("Link grid exceeds cell limit");
   const result = [];
-  let text = "", spans = [], unsafe = /* @__PURE__ */ new Set(), firstRow = 0, total = 0;
+  let text2 = "", spans = [], unsafe = /* @__PURE__ */ new Set(), firstRow = 0, total = 0;
   let start = "unknown";
   const wrapped = (row) => row >= 0 && !!((cells2[(row + 1) * columns - 1]?.attributes ?? 0) & SOFT_WRAP);
   const finish = (end) => {
-    const chunk = Object.freeze({ text, mode, start, end });
-    const boundaries = /* @__PURE__ */ new Set([text.length]);
-    for (const segment of segmenter.segment(text)) boundaries.add(segment.index);
+    const chunk = Object.freeze({ text: text2, mode, start, end });
+    const boundaries = /* @__PURE__ */ new Set([text2.length]);
+    for (const segment of segmenter.segment(text2)) boundaries.add(segment.index);
     result.push({
       chunk,
       spans,
       unsafe,
       boundaries,
-      key: JSON.stringify([mode, firstRow, start, end, text])
+      key: JSON.stringify([mode, firstRow, start, end, text2])
     });
-    text = "";
+    text2 = "";
     spans = [];
     unsafe = /* @__PURE__ */ new Set();
   };
   for (let row = 0; row < rows; row++) {
-    if (text.length === 0) {
+    if (text2.length === 0) {
       firstRow = row;
       start = row === 0 ? "unknown" : wrapped(row - 1) ? "clipped" : "complete";
     }
@@ -5192,26 +5258,26 @@ function extractLinkText(snapshot, mode) {
       const width = cell?.width ?? 1;
       const valid = width >= 1 && width <= 2 && col + width <= columns && !(cell && (cell.attributes & HIDDEN || cell.text.codePointAt(0) === 1109742)) && (width !== 2 || cells2[row * columns + col + 1]?.width === 0);
       const value = valid ? cell?.text || " " : "\0";
-      if (total + value.length > LINK_LIMITS.totalText || text.length + value.length > LINK_LIMITS.chunk) {
+      if (total + value.length > LINK_LIMITS.totalText || text2.length + value.length > LINK_LIMITS.chunk) {
         throw new RangeError("Link text exceeds chunk or viewport limit");
       }
-      const offset = text.length;
-      text += value;
+      const offset = text2.length;
+      text2 += value;
       total += value.length;
-      if (valid) spans.push({ start: offset, end: text.length, row, startColumn: col, endColumn: col + width });
+      if (valid) spans.push({ start: offset, end: text2.length, row, startColumn: col, endColumn: col + width });
       else {
         unsafe.add(offset);
-        unsafe.add(text.length);
+        unsafe.add(text2.length);
       }
       if (valid && width === 2) col++;
     }
     const soft = wrapped(row);
-    if (!soft) unsafe.add(text.length);
+    if (!soft) unsafe.add(text2.length);
     if (mode === "physicalRow" || mode === "logicalLine" && !soft || row === rows - 1) {
       finish(soft ? "clipped" : "unknown");
     } else if (!soft) {
-      if (++total > LINK_LIMITS.totalText || text.length + 1 > LINK_LIMITS.chunk) throw new RangeError("Link text exceeds limit");
-      text += "\n";
+      if (++total > LINK_LIMITS.totalText || text2.length + 1 > LINK_LIMITS.chunk) throw new RangeError("Link text exceeds limit");
+      text2 += "\n";
     }
   }
   return result;
@@ -5559,6 +5625,7 @@ var WebTerminal = class _WebTerminal {
   #title = "";
   #hasTitle = false;
   #progress = { state: "none", percentage: null };
+  #programStatus = programStatusSnapshot({ records: [] });
   #shellIntegration = { phase: "unknown", lastExitCode: null };
   #workingDirectory = { uri: null, host: null, path: null };
   #commandMark = null;
@@ -5693,6 +5760,9 @@ var WebTerminal = class _WebTerminal {
   get progress() {
     return { ...this.#progress };
   }
+  get programStatus() {
+    return this.#programStatus;
+  }
   get shellIntegration() {
     return { ...this.#shellIntegration };
   }
@@ -6053,18 +6123,21 @@ var WebTerminal = class _WebTerminal {
       if (!this.#disposed && this.#connected && (this.#peer.id !== null || this.#peer.isPrimary)) {
         const titleChanged = !this.#hasTitle || this.#title !== message.title;
         const progressChanged = !this.#hasActivity || this.#progress.state !== message.progress.state || this.#progress.percentage !== message.progress.percentage;
+        const programStatusChanged = !this.#hasActivity || !sameProgramStatus(this.#programStatus, message.programStatus);
         const shellChanged = !this.#hasActivity || this.#shellIntegration.phase !== message.shellIntegration.phase || this.#shellIntegration.lastExitCode !== message.shellIntegration.lastExitCode;
         const workingDirectoryChanged = !this.#hasActivity || this.#workingDirectory.uri !== message.workingDirectory.uri;
         const commandMarkChanged = !this.#hasActivity || this.#commandMark?.phase !== message.commandMark?.phase || this.#commandMark?.exitCode !== message.commandMark?.exitCode || this.#commandMark?.rawParameters !== message.commandMark?.rawParameters;
         this.#title = message.title;
         this.#hasTitle = true;
         this.#progress = { ...message.progress };
+        if (programStatusChanged) this.#programStatus = programStatusSnapshot(message.programStatus);
         this.#shellIntegration = { ...message.shellIntegration };
         this.#workingDirectory = { ...message.workingDirectory };
         this.#commandMark = message.commandMark ? { ...message.commandMark } : null;
         this.#hasActivity = true;
         if (titleChanged) this.#options.onTitleChange?.(this.#title);
         if (!this.#disposed && progressChanged) this.#options.onProgressChange?.(this.progress);
+        if (!this.#disposed && programStatusChanged) this.#options.onProgramStatusChange?.(this.programStatus);
         if (!this.#disposed && shellChanged) this.#options.onShellIntegrationChange?.(this.shellIntegration);
         if (!this.#disposed && workingDirectoryChanged) this.#options.onWorkingDirectoryChange?.(this.workingDirectory);
         if (!this.#disposed && commandMarkChanged) this.#options.onCommandMarkChange?.(this.commandMark);
@@ -6261,11 +6334,11 @@ var WebTerminal = class _WebTerminal {
       if (!navigator.clipboard?.write || typeof ClipboardItem !== "function") {
         throw new Error("Clipboard writing is unavailable. Use a secure browser context with clipboard permission.");
       }
-      const text = this.#history.copy();
+      const text2 = this.#history.copy();
       this.#copying = true;
       this.#inspectionChanged();
-      const item = new ClipboardItem({ "text/plain": text.then((value2) => new Blob([value2], { type: "text/plain" })) });
-      const [value] = await Promise.all([text, navigator.clipboard.write([item])]);
+      const item = new ClipboardItem({ "text/plain": text2.then((value2) => new Blob([value2], { type: "text/plain" })) });
+      const [value] = await Promise.all([text2, navigator.clipboard.write([item])]);
       if (clear && serial === this.#copySerial && this.selection.status === "valid" && this.selection.requestId === selectionId && this.viewport.generation === generation)
         this.clearSelection();
       return value;
@@ -6350,10 +6423,10 @@ var WebTerminal = class _WebTerminal {
     }
   }
   /** Sends an explicit paste through the producer's mode-aware input encoder. */
-  paste(text) {
-    if (typeof text !== "string") throw new TypeError("Paste text must be a string");
+  paste(text2) {
+    if (typeof text2 !== "string") throw new TypeError("Paste text must be a string");
     if (!this.#canInput()) throw new Error("Terminal view does not accept input");
-    if (text) this.#inputCommand({ type: "paste", text });
+    if (text2) this.#inputCommand({ type: "paste", text: text2 });
   }
   async pasteClipboard() {
     if (!this.#canInput()) throw new Error("Terminal view does not accept input");
@@ -6363,11 +6436,11 @@ var WebTerminal = class _WebTerminal {
     const generation = this.viewport.generation;
     const selectionId = this.selection.requestId;
     const focused = document.activeElement;
-    const text = await navigator.clipboard.readText();
+    const text2 = await navigator.clipboard.readText();
     if (!this.#canInput() || serial !== this.#inputSerial || generation !== this.viewport.generation || selectionId !== this.selection.requestId || document.activeElement !== focused)
       throw new Error("Terminal input, selection, focus, or buffer changed while reading the clipboard. Paste again.");
-    this.paste(text);
-    return text;
+    this.paste(text2);
+    return text2;
   }
   get colorMode() {
     return this.#colorMode;
@@ -6521,17 +6594,17 @@ var WebTerminal = class _WebTerminal {
     const range = this.#osc8Rows.get(input.point.y)?.find((range2) => input.point.x >= range2.startColumn && input.point.x < range2.endColumn);
     const snapshot = this.#linkSnapshot;
     if (!range || !snapshot) return;
-    let text = "";
+    let text2 = "";
     for (let column = range.startColumn; column < range.endColumn; column++) {
       const cell = snapshot.cells[range.row * snapshot.columns + column];
-      if (cell?.width && !(cell.attributes & 64)) text += cell.text;
+      if (cell?.width && !(cell.attributes & 64)) text2 += cell.text;
     }
     const activation = Object.freeze({
       source: "osc8",
       ruleId: null,
       kind: "uri",
       target: pointer.target,
-      text,
+      text: text2,
       revision: this.#linkRevision,
       ranges: Object.freeze([Object.freeze({ row: range.row, startColumn: range.startColumn, endColumn: range.endColumn })])
     });
@@ -6611,9 +6684,9 @@ var WebTerminal = class _WebTerminal {
       const inputEvent = event instanceof InputEvent ? event : void 0;
       if (inputEvent?.isComposing || composing) return;
       clearTimeout(this.#compositionTimer);
-      const text = compositionCommit ?? inputEvent?.data ?? input.value;
+      const text2 = compositionCommit ?? inputEvent?.data ?? input.value;
       compositionCommit = null;
-      if (text && inputEvent?.inputType !== "insertFromPaste") this.#dispatchInput({ type: "text", text }, event);
+      if (text2 && inputEvent?.inputType !== "insertFromPaste") this.#dispatchInput({ type: "text", text: text2 }, event);
       input.value = "";
     }, options);
   }