tmux-ide 2.9.11 → 2.9.13

package/packages/core/src/terminal-delivery-binary.ts

@@ -0,0 +1,160 @@
+/** TCB1 typed RLE tuples. No JSON cell encoding; shape validation belongs to semantic delivery. */
+const MAX_BYTES = 16 * 1024 * 1024,
+  MAX_STRING = 4096,
+  MAX_NODES = 8_000_000,
+  MAX_ARRAY = 1_000_000;
+const encoder = new TextEncoder(),
+  decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+export class BinaryTerminalLimitError extends RangeError {}
+export class BinaryTerminalWriter {
+  private data = new Uint8Array(4096);
+  private length = 0;
+  private nodes = 0;
+  private reserve(size: number) {
+    if (size > MAX_BYTES - this.length)
+      throw new BinaryTerminalLimitError("Binary terminal representation exceeds bound");
+    if (this.length + size > this.data.length) {
+      const next = new Uint8Array(
+        Math.min(MAX_BYTES, Math.max(this.length + size, this.data.length * 2)),
+      );
+      next.set(this.data);
+      this.data = next;
+    }
+  }
+  byte(value: number) {
+    this.reserve(1);
+    this.data[this.length++] = value;
+  }
+  uint(value: number) {
+    if (!Number.isSafeInteger(value) || value < 0) throw new TypeError("Invalid binary integer");
+    do {
+      const low = value % 128;
+      value = Math.floor(value / 128);
+      this.byte(low + (value ? 128 : 0));
+    } while (value);
+  }
+  array(length: number) {
+    if (length > MAX_ARRAY) throw new BinaryTerminalLimitError("Binary array bound");
+    this.byte(3);
+    this.uint(length);
+  }
+  value(value: unknown, depth = 0): void {
+    if (depth > 16 || ++this.nodes > MAX_NODES)
+      throw new BinaryTerminalLimitError("Binary node bound");
+    if (value === null) {
+      this.byte(0);
+      return;
+    }
+    if (typeof value === "number") {
+      this.byte(1);
+      this.uint(value);
+      return;
+    }
+    if (typeof value === "string") {
+      const bytes = encoder.encode(value);
+      if (bytes.length > MAX_STRING) throw new BinaryTerminalLimitError("Binary string bound");
+      if (decoder.decode(bytes) !== value)
+        throw new TypeError("Binary strings require well-formed Unicode");
+      this.byte(2);
+      this.uint(bytes.length);
+      this.reserve(bytes.length);
+      this.data.set(bytes, this.length);
+      this.length += bytes.length;
+      return;
+    }
+    if (Array.isArray(value)) {
+      this.array(value.length);
+      for (const child of value) this.value(child, depth + 1);
+      return;
+    }
+    throw new TypeError("Invalid binary tuple value");
+  }
+  header(
+    frame: "seed" | "patch" | "tombstone",
+    revision: number,
+    base?: number,
+    magic: "TCB1" | "TCP1" = "TCB1",
+  ) {
+    for (const b of magic === "TCP1" ? [84, 67, 80, 49] : [84, 67, 66, 49]) this.byte(b);
+    this.byte(frame === "seed" ? 0 : frame === "patch" ? 1 : 2);
+    this.uint(revision);
+    if (frame !== "seed") this.uint(base!);
+  }
+  get byteLength(): number {
+    return this.length;
+  }
+  finish() {
+    return this.data.slice(0, this.length);
+  }
+}
+export function decodeBinaryTerminalTuple(
+  bytes: Uint8Array,
+  magic: "TCB1" | "TCP1" = "TCB1",
+): {
+  frame: "seed" | "patch" | "tombstone";
+  revision: number;
+  baseRevision?: number;
+  value: unknown;
+} {
+  if (
+    bytes.length > MAX_BYTES ||
+    bytes.length < 7 ||
+    bytes[0] !== 84 ||
+    bytes[1] !== 67 ||
+    bytes[2] !== (magic === "TCP1" ? 80 : 66) ||
+    bytes[3] !== 49
+  )
+    throw new TypeError("Invalid binary terminal header");
+  let offset = 4,
+    nodes = 0;
+  const byte = () => {
+    if (offset >= bytes.length) throw new TypeError("Truncated binary terminal payload");
+    return bytes[offset++]!;
+  };
+  const uint = () => {
+    let value = 0,
+      scale = 1;
+    for (let index = 0; index < 8; index++) {
+      const b = byte();
+      value += (b & 127) * scale;
+      if (!Number.isSafeInteger(value)) throw new TypeError("Binary integer exceeds safe bound");
+      if (b < 128) {
+        if (index > 0 && b === 0) throw new TypeError("Noncanonical binary integer");
+        return value;
+      }
+      scale *= 128;
+    }
+    throw new TypeError("Binary integer is too long");
+  };
+  const read = (depth = 0): unknown => {
+    if (depth > 16 || ++nodes > MAX_NODES) throw new TypeError("Binary structure bound");
+    const tag = byte();
+    if (tag === 0) return null;
+    if (tag === 1) return uint();
+    if (tag === 2) {
+      const length = uint();
+      if (length > MAX_STRING || length > bytes.length - offset)
+        throw new TypeError("Binary string bound");
+      const result = decoder.decode(bytes.subarray(offset, offset + length));
+      offset += length;
+      return result;
+    }
+    if (tag === 3) {
+      const length = uint();
+      if (length > MAX_ARRAY || length > bytes.length - offset)
+        throw new TypeError("Binary array bound");
+      const result: unknown[] = [];
+      for (let i = 0; i < length; i++) result.push(read(depth + 1));
+      return result;
+    }
+    throw new TypeError("Unknown binary value tag");
+  };
+  const kind = byte();
+  if (kind > 2) throw new TypeError("Unknown binary frame");
+  const frame = kind === 0 ? "seed" : kind === 1 ? "patch" : "tombstone";
+  const revision = uint();
+  const baseRevision = kind === 0 ? undefined : uint();
+  const value = read();
+  if (offset !== bytes.length) throw new TypeError("Trailing binary data");
+  return { frame, revision, ...(baseRevision === undefined ? {} : { baseRevision }), value };
+}

package/packages/core/src/terminal-delivery.ts

@@ -1,3 +1,14 @@
+import {
+  TERMINAL_GRAPHICS_COMPRESSED_CAPABILITY_VERSION,
+  TERMINAL_GRAPHICS_COMPRESSED_LOCAL_CAPABILITY_VERSION,
+  TERMINAL_PROJECTION_CAPABILITY_VERSION,
+  TERMINAL_PROJECTION_LOCAL_CAPABILITY_VERSION,
+} from "@tmux-ide/contracts";
+import {
+  BinaryTerminalWriter,
+  BinaryTerminalLimitError,
+  decodeBinaryTerminalTuple,
+} from "./terminal-delivery-binary.ts";
 import { z } from "zod";
 import {
   isOwnedTerminalReplicaRow,
@@ -6,6 +17,8 @@ import {
   TERMINAL_REPLICA_SPACE_CELL,
 } from "./terminal-replica-owned-row.ts";
 import {
+  TERMINAL_DELIVERY_BINARY_CAPABILITY_VERSION,
+  TERMINAL_DELIVERY_BINARY_LOCAL_CAPABILITY_VERSION,
   TERMINAL_DELIVERY_CHUNK_BYTES,
   TERMINAL_DELIVERY_MAX_REPRESENTATION_BYTES,
   TERMINAL_DELIVERY_PROTOCOL_VERSION,
@@ -71,22 +84,52 @@ export function negotiateTerminalDelivery(
 ): TerminalDeliveryNegotiationResult {
   if (!offer.protocolVersions.includes(TERMINAL_DELIVERY_PROTOCOL_VERSION))
     return { accepted: false, reason: "protocol-version-mismatch" };
-  const encoding = (
-    ["semantic-compact-v1", "semantic-v1", "ansi-diff-v1", "ansi-raw-v1"] as const
-  ).find((value) => offer.encodings.includes(value));
+  const binary =
+    offer.protocolVersions.some(
+      (v) =>
+        v === TERMINAL_DELIVERY_BINARY_CAPABILITY_VERSION ||
+        v === TERMINAL_DELIVERY_BINARY_LOCAL_CAPABILITY_VERSION ||
+        v === TERMINAL_PROJECTION_CAPABILITY_VERSION ||
+        v === TERMINAL_PROJECTION_LOCAL_CAPABILITY_VERSION ||
+        v === TERMINAL_GRAPHICS_COMPRESSED_CAPABILITY_VERSION ||
+        v === TERMINAL_GRAPHICS_COMPRESSED_LOCAL_CAPABILITY_VERSION,
+    ) && offer.encodings.includes("semantic-compact-v1");
+  const encoding = binary
+    ? ("semantic-binary-v1" as const)
+    : (["semantic-compact-v1", "semantic-v1", "ansi-diff-v1", "ansi-raw-v1"] as const).find(
+        (value) => offer.encodings.includes(value),
+      );
   if (!encoding) return { accepted: false, reason: "encoding-mismatch" };
-  if (offer.richPlacements && encoding !== "semantic-v1" && encoding !== "semantic-compact-v1")
+  if (
+    offer.richPlacements &&
+    encoding !== "semantic-v1" &&
+    encoding !== "semantic-compact-v1" &&
+    encoding !== "semantic-binary-v1"
+  )
     return { accepted: false, reason: "unsupported-capability-combination" };
   return {
     accepted: true,
     negotiated: {
       protocolVersion: TERMINAL_DELIVERY_PROTOCOL_VERSION,
       encoding,
+      ...(binary &&
+      offer.protocolVersions.some(
+        (v) =>
+          v === TERMINAL_PROJECTION_CAPABILITY_VERSION ||
+          v === TERMINAL_PROJECTION_LOCAL_CAPABILITY_VERSION ||
+          v === TERMINAL_GRAPHICS_COMPRESSED_CAPABILITY_VERSION ||
+          v === TERMINAL_GRAPHICS_COMPRESSED_LOCAL_CAPABILITY_VERSION,
+      )
+        ? { alternateScreenProjection: "deferred-history-v1" as const }
+        : {}),
       ...(encoding === "semantic-compact-v1" && offer.encodings.includes("semantic-v1")
         ? { fallbackEncoding: "semantic-v1" as const }
         : {}),
       richPlacements:
-        offer.richPlacements && (encoding === "semantic-v1" || encoding === "semantic-compact-v1"),
+        offer.richPlacements &&
+        (encoding === "semantic-v1" ||
+          encoding === "semantic-compact-v1" ||
+          encoding === "semantic-binary-v1"),
       generation,
       deliveryNonce,
     },
@@ -370,6 +413,12 @@ function hasOwnedSeedRow(input: TerminalSemanticDeliveryPayload): boolean {
 export function encodeCompactSemanticTerminalUpdate(
   input: TerminalSemanticDeliveryPayload,
 ): Uint8Array {
+  const wire = compactSemanticWire(input);
+  const bytes = UTF8_ENCODER.encode(JSON.stringify(wire));
+  assertRepresentationSize(bytes);
+  return bytes;
+}
+function compactSemanticWire(input: TerminalSemanticDeliveryPayload) {
   const update = (
     hasOwnedPatchRow(input)
       ? CompactPatchEncodingPayloadSchema
@@ -406,9 +455,172 @@ export function encodeCompactSemanticTerminalUpdate(
             t: update.tombstone.reason,
             v: 1,
           };
-  const bytes = UTF8_ENCODER.encode(JSON.stringify(wire));
-  assertRepresentationSize(bytes);
-  return bytes;
+  return wire;
+}
+
+export function encodeBinarySemanticTerminalUpdate(
+  input: TerminalSemanticDeliveryPayload,
+): Uint8Array {
+  const wire = compactSemanticWire(input);
+  const writer = new BinaryTerminalWriter();
+  try {
+    writer.header(input.frame, wire.r, input.frame === "seed" ? undefined : input.baseRevision);
+    writer.value(wire.f === "s" ? wire.s : wire.f === "p" ? wire.p : wire.t);
+    return writer.finish();
+  } catch (error) {
+    if (error instanceof BinaryTerminalLimitError)
+      throw new TerminalDeliveryStateTooLargeError(TERMINAL_DELIVERY_MAX_REPRESENTATION_BYTES + 1);
+    throw error;
+  }
+}
+export function decodeBinarySemanticTerminalUpdate(
+  bytes: Uint8Array,
+): TerminalSemanticDeliveryPayload {
+  const decoded = decodeBinaryTerminalTuple(bytes),
+    budget = { ...compactDecodeBudget(bytes.length), maxCells: COMPACT_MAX_EXPANDED_CELLS };
+  if (decoded.frame === "seed")
+    return Object.freeze({
+      frame: "seed",
+      revision: decoded.revision,
+      snapshot: expandSnapshot(decoded.value, budget),
+    });
+  if (decoded.baseRevision === undefined || decoded.revision <= decoded.baseRevision)
+    throw new TypeError("Binary revision did not advance");
+  if (decoded.frame === "patch")
+    return Object.freeze({
+      frame: "patch",
+      revision: decoded.revision,
+      baseRevision: decoded.baseRevision,
+      patch: expandPatch(decoded.value, budget),
+    });
+  if (
+    typeof decoded.value !== "string" ||
+    !["pane-closed", "session-restarted", "runtime-disposed"].includes(decoded.value)
+  )
+    throw new TypeError("Invalid binary tombstone");
+  return Object.freeze({
+    frame: "tombstone",
+    revision: decoded.revision,
+    baseRevision: decoded.baseRevision,
+    tombstone: Object.freeze({
+      reason: decoded.value as "pane-closed" | "session-restarted" | "runtime-disposed",
+    }),
+  });
+}
+export async function encodeBinarySemanticTerminalUpdateCooperatively(
+  input: TerminalSemanticDeliveryPayload,
+  options: { readonly yieldControl: () => Promise<void>; readonly signal?: AbortSignal },
+): Promise<Uint8Array> {
+  options.signal?.throwIfAborted();
+  if (input.frame !== "seed") return encodeBinarySemanticTerminalUpdate(input);
+  const { snapshot: source, ...headerInput } = input;
+  const header = CompactSeedHeaderSchema.parse(headerInput);
+  const { grid, history, placements, ...metadataInput } = source;
+  const metadata = CompactSeedMetadataSchema.parse(metadataInput);
+  if (
+    !Array.isArray(grid) ||
+    !Array.isArray(history) ||
+    !Array.isArray(placements) ||
+    grid.length !== metadata.rows ||
+    metadata.cols > COMPACT_MAX_DIMENSION ||
+    metadata.rows > COMPACT_MAX_DIMENSION
+  )
+    compactEncodingLimit();
+  let rowCount = 0,
+    cellCount = 0,
+    runCount = 0,
+    work = 0,
+    encodedWork = 0;
+  const checkpoint = (characters: number): Promise<void> | undefined => {
+    options.signal?.throwIfAborted();
+    work++;
+    encodedWork += characters + 64;
+    if (work >= 256 || encodedWork >= 32 * 1024) {
+      work = 0;
+      encodedWork = 0;
+      return options.yieldControl().then(() => options.signal?.throwIfAborted());
+    }
+    return undefined;
+  };
+  const writer = new BinaryTerminalWriter();
+  try {
+    writer.header("seed", header.revision);
+    writer.array(8);
+    writer.value(metadata.cols);
+    writer.value(metadata.rows);
+    for (const rows of [grid, history]) {
+      writer.array(rows.length);
+      for (const row of rows) {
+        const owned = isOwnedTerminalReplicaRow(row);
+        const validatedRow =
+          owned &&
+          (validatedOwnedEncodingRows.has(row) || isSchemaValidProjectedTerminalReplicaRow(row));
+        const { cells, ...rowHeaderInput } = row;
+        const rowHeader = CompactRowHeaderSchema.parse(rowHeaderInput);
+        if (
+          ++rowCount > COMPACT_MAX_ROWS ||
+          !Array.isArray(cells) ||
+          cells.length !== metadata.cols
+        )
+          compactEncodingLimit();
+        cellCount += cells.length;
+        if (cellCount > COMPACT_MAX_EXPANDED_CELLS) compactEncodingLimit();
+        const runs: CompactCellRun[] = [];
+        let prior: CompactCellRun | undefined;
+        for (let offset = 0; offset < cells.length; offset += 256) {
+          const slice = cells.slice(offset, offset + 256);
+          const validated =
+            validatedRow || (owned && isValidatedTrustedBlankSlice(slice))
+              ? slice
+              : owned
+                ? validateOwnedCellSlice(slice)
+                : CompactCellSliceSchema.parse(slice);
+          for (const cell of validated) {
+            const encoded = compactCell(cell);
+            if (prior && compactRunCellEqual(prior, encoded)) prior[0]++;
+            else {
+              if (++runCount > COMPACT_MAX_RUNS) compactEncodingLimit();
+              runs.push(encoded);
+              prior = encoded;
+            }
+            const pending = checkpoint(cell.grapheme.length);
+            if (pending) await pending;
+          }
+        }
+        writer.array(2);
+        writer.value(rowHeader.wrapped ? 1 : 0);
+        writer.array(runs.length);
+        for (const run of runs) {
+          writer.value(run);
+          const pending = checkpoint(run[1].length);
+          if (pending) await pending;
+        }
+        if (owned) validatedOwnedEncodingRows.add(row);
+      }
+    }
+    writer.value(compactCursor(metadata.cursor));
+    writer.value(compactModes(metadata.modes));
+    if (placements.length > COMPACT_MAX_PLACEMENTS) compactEncodingLimit();
+    writer.array(placements.length);
+    for (const value of placements) {
+      const placement = compactPlacement(TerminalReplicaPlacementSchemaZ.parse(value));
+      writer.value(placement);
+      const pending = checkpoint(
+        placement.reduce<number>(
+          (size, value) => size + (typeof value === "string" ? value.length : 8),
+          0,
+        ),
+      );
+      if (pending) await pending;
+    }
+    writer.value(compactBootstrap(metadata.bootstrap));
+    options.signal?.throwIfAborted();
+    return writer.finish();
+  } catch (error) {
+    if (error instanceof BinaryTerminalLimitError)
+      throw new TerminalDeliveryStateTooLargeError(TERMINAL_DELIVERY_MAX_REPRESENTATION_BYTES + 1);
+    throw error;
+  }
 }
 
 // Keep the ordinary small-patch encoder unchanged. Large seeds are validated
@@ -3177,15 +3389,21 @@ export function commitTerminalDelivery(
     throw new TypeError("Terminal delivery representation hash mismatch");
   let canonicalSnapshot = state.canonicalSnapshot;
   let semanticUpdate: TerminalSemanticDeliveryPayload | null = null;
-  if (envelope.encoding === "semantic-v1" || envelope.encoding === "semantic-compact-v1") {
+  if (
+    envelope.encoding === "semantic-v1" ||
+    envelope.encoding === "semantic-compact-v1" ||
+    envelope.encoding === "semantic-binary-v1"
+  ) {
     const payload =
-      envelope.encoding === "semantic-compact-v1"
-        ? decodeVerifiedCompactSemanticTerminalUpdate(
-            staged.bytes,
-            canonicalSnapshot,
-            envelope.canonicalStateHash,
-          ).payload
-        : decodeSemanticTerminalUpdate(staged.bytes);
+      envelope.encoding === "semantic-binary-v1"
+        ? decodeBinarySemanticTerminalUpdate(staged.bytes)
+        : envelope.encoding === "semantic-compact-v1"
+          ? decodeVerifiedCompactSemanticTerminalUpdate(
+              staged.bytes,
+              canonicalSnapshot,
+              envelope.canonicalStateHash,
+            ).payload
+          : decodeSemanticTerminalUpdate(staged.bytes);
     semanticUpdate = payload;
     if (payload.frame !== envelope.frame || payload.revision !== envelope.canonicalRevision)
       throw new TypeError("Semantic frame or revision mismatch");
@@ -3407,3 +3625,146 @@ function isNewerIncarnation(current: string, candidate: string): boolean {
     Number(candidateEpoch) > Number(currentEpoch)
   );
 }
+
+/** Internal bounded viewport codec shared by the explicitly partial TCP1 protocol.
+ * Callers validate projection metadata; these adapters never construct a complete snapshot. */
+export function encodeTerminalProjectionViewportTuple(
+  snapshot: Omit<TerminalReplicaSnapshot, "history">,
+): readonly unknown[] {
+  const budget = {
+    ...compactDecodeBudget(TERMINAL_DELIVERY_MAX_REPRESENTATION_BYTES),
+    maxCells: COMPACT_MAX_EXPANDED_CELLS,
+  };
+  if (
+    snapshot.cols > COMPACT_MAX_DIMENSION ||
+    snapshot.rows > COMPACT_MAX_DIMENSION ||
+    snapshot.grid.length !== snapshot.rows
+  )
+    compactEncodingLimit();
+  return [
+    snapshot.cols,
+    snapshot.rows,
+    compactRows(snapshot.grid, snapshot.cols, budget),
+    compactCursor(snapshot.cursor),
+    compactModes(snapshot.modes),
+    compactPlacements(snapshot.placements, budget),
+    compactBootstrap(snapshot.bootstrap),
+  ];
+}
+export function decodeTerminalProjectionViewportTuple(
+  value: unknown,
+): Omit<TerminalReplicaSnapshot, "history"> {
+  const input = compactArray(value, 7, "projection viewport");
+  const budget = {
+    ...compactDecodeBudget(TERMINAL_DELIVERY_MAX_REPRESENTATION_BYTES),
+    maxCells: COMPACT_MAX_EXPANDED_CELLS,
+  };
+  const cols = compactInteger(input[0], 1, COMPACT_MAX_DIMENSION, "columns"),
+    rows = compactInteger(input[1], 1, COMPACT_MAX_DIMENSION, "rows");
+  return {
+    cols,
+    rows,
+    grid: expandRows(input[2], budget, cols, rows, "grid"),
+    cursor: expandCursor(input[3], cols, rows),
+    modes: expandModes(input[4]),
+    placements: expandPlacements(input[5], budget),
+    bootstrap: expandBootstrap(input[6]),
+  };
+}
+export function encodeTerminalProjectionPatchTuple(
+  patch: Omit<TerminalReplicaPatchPayload, "history" | "historyDelta">,
+): readonly unknown[] {
+  const tuple = compactPatch(patch);
+  return [tuple[0], tuple[1], tuple[4], tuple[5], tuple[6], tuple[7]];
+}
+export function decodeTerminalProjectionPatchTuple(
+  value: unknown,
+): Omit<TerminalReplicaPatchPayload, "history" | "historyDelta"> {
+  const tuple = compactArray(value, 6, "projection patch");
+  const budget = {
+    ...compactDecodeBudget(TERMINAL_DELIVERY_MAX_REPRESENTATION_BYTES),
+    maxCells: COMPACT_MAX_EXPANDED_CELLS,
+  };
+  // Null means absent patch operations, never an empty canonical history.
+  return expandPatch(
+    [tuple[0], tuple[1], null, null, tuple[2], tuple[3], tuple[4], tuple[5]],
+    budget,
+  );
+}
+
+/** Writes one bounded projection row, reusing immutable-row schema provenance. */
+export async function writeTerminalProjectionRowCooperatively(
+  writer: BinaryTerminalWriter,
+  row: TerminalReplicaRow,
+  cols: number | null,
+  options: { readonly yieldControl: () => Promise<void>; readonly signal?: AbortSignal },
+): Promise<void> {
+  options.signal?.throwIfAborted();
+  const owned = isOwnedTerminalReplicaRow(row);
+  const validatedRow =
+    owned && (validatedOwnedEncodingRows.has(row) || isSchemaValidProjectedTerminalReplicaRow(row));
+  const { cells, ...header } = row;
+  const rowHeader = CompactRowHeaderSchema.parse(header);
+  if (
+    !Array.isArray(cells) ||
+    cells.length > COMPACT_MAX_DIMENSION ||
+    (cols !== null && cells.length !== cols)
+  )
+    compactEncodingLimit();
+  const runs: CompactCellRun[] = [];
+  let prior: CompactCellRun | undefined,
+    work = 0,
+    characters = 0;
+  const checkpoint = (length: number): Promise<void> | undefined => {
+    options.signal?.throwIfAborted();
+    work++;
+    characters += length + 64;
+    if (work < 256 && characters < 32 * 1024) return undefined;
+    work = 0;
+    characters = 0;
+    return options.yieldControl().then(() => options.signal?.throwIfAborted());
+  };
+  for (let offset = 0; offset < cells.length; offset += 256) {
+    const slice = cells.slice(offset, offset + 256);
+    const validated =
+      validatedRow || (owned && isValidatedTrustedBlankSlice(slice))
+        ? slice
+        : owned
+          ? validateOwnedCellSlice(slice)
+          : CompactCellSliceSchema.parse(slice);
+    for (const cell of validated) {
+      const encoded = compactCell(cell);
+      if (prior && compactRunCellEqual(prior, encoded)) prior[0]++;
+      else {
+        runs.push(encoded);
+        prior = encoded;
+      }
+      const pause = checkpoint(cell.grapheme.length);
+      if (pause) await pause;
+    }
+  }
+  writer.array(2);
+  writer.value(rowHeader.wrapped ? 1 : 0);
+  writer.array(runs.length);
+  for (const run of runs) {
+    writer.value(run);
+    const pause = checkpoint(run[1].length);
+    if (pause) await pause;
+  }
+  if (owned) validatedOwnedEncodingRows.add(row);
+}
+/** Metadata-only tuples; no row graph, history, or JSON cell serialization. */
+export function encodeTerminalProjectionMetadataTuple(
+  value: Omit<TerminalReplicaSnapshot, "grid" | "history">,
+): readonly unknown[] {
+  const budget = {
+    ...compactDecodeBudget(TERMINAL_DELIVERY_MAX_REPRESENTATION_BYTES),
+    maxCells: COMPACT_MAX_EXPANDED_CELLS,
+  };
+  return [
+    compactCursor(value.cursor),
+    compactModes(value.modes),
+    compactPlacements(value.placements, budget),
+    compactBootstrap(value.bootstrap),
+  ];
+}

package/packages/core/src/terminal-projection-vectors.mjs

@@ -0,0 +1,82 @@
+// node --import tsx packages/core/src/terminal-projection-vectors.mjs
+import { writeFileSync } from "node:fs";
+import { URL } from "node:url";
+import {
+  blankTerminalReplicaSnapshot,
+  freezeTerminalReplicaSnapshot,
+  hashTerminalReplicaSnapshot,
+} from "./terminal-replica.ts";
+import {
+  encodeBinarySemanticTerminalUpdate,
+  hashTerminalDeliveryRepresentation,
+} from "./terminal-delivery.ts";
+import {
+  projectAlternateSnapshot,
+  applyTerminalProjectionPatch,
+  hashTerminalProjection,
+  hashSourceSnapshotFromProjection,
+  hashTerminalProjectionTombstone,
+  encodeTerminalProjection,
+} from "./terminal-projection.ts";
+import { hashTerminalReplicaTombstone } from "./terminal-replica.ts";
+const base = blankTerminalReplicaSnapshot(3, 2);
+const source = freezeTerminalReplicaSnapshot({
+  ...base,
+  modes: { ...base.modes, alternateScreen: true },
+  history: [base.grid[0], base.grid[1]],
+});
+const initial = projectAlternateSnapshot(source);
+const row = {
+  ...initial.grid[1],
+  cells: initial.grid[1].cells.map((cell, index) => (index ? cell : { ...cell, grapheme: "é" })),
+};
+const patch = { rows: [{ index: 1, row }], deferredHistory: initial.deferredHistory };
+const next = applyTerminalProjectionPatch(initial, patch);
+const entries = [
+  { payload: { frame: "seed", revision: 7, projection: initial }, projection: initial },
+  { payload: { frame: "patch", baseRevision: 7, revision: 8, patch }, projection: next },
+  {
+    payload: {
+      frame: "tombstone",
+      baseRevision: 8,
+      revision: 9,
+      tombstone: { reason: "pane-closed" },
+    },
+    projection: null,
+  },
+];
+const vectors = entries.map(({ payload, projection }) => {
+  const bytes = encodeTerminalProjection(payload);
+  return {
+    payload,
+    bytes: [...bytes],
+    representationHash: hashTerminalDeliveryRepresentation(bytes),
+    projectionStateHash: projection
+      ? hashTerminalProjection(projection)
+      : hashTerminalProjectionTombstone(payload.tombstone.reason),
+    canonicalStateHash: projection
+      ? hashSourceSnapshotFromProjection(projection)
+      : hashTerminalReplicaTombstone(payload.tombstone.reason),
+  };
+});
+const materialized = { ...source, grid: next.grid };
+const materializedBytes = encodeBinarySemanticTerminalUpdate({
+  frame: "seed",
+  revision: 8,
+  snapshot: materialized,
+});
+writeFileSync(
+  new URL("fixtures/terminal-projection-vectors.json", import.meta.url),
+  JSON.stringify(
+    {
+      source,
+      sourceHash: hashTerminalReplicaSnapshot(source),
+      materialized,
+      materializedBytes: [...materializedBytes],
+      materializedRepresentationHash: hashTerminalDeliveryRepresentation(materializedBytes),
+      vectors,
+    },
+    null,
+    2,
+  ) + "\n",
+);