tmux-ide 2.9.11 → 2.9.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmux-ide",
-  "version": "2.9.11",
+  "version": "2.9.13",
   "description": "The open-source workspace for coding agents: run Claude Code, Codex and other agents in tmux with live status",
   "type": "module",
   "bin": {

package/packages/contracts/src/index.ts

@@ -50,6 +50,8 @@ export * from "./session-runtime.ts";
 export * from "./terminal-replica.ts";
 export * from "./terminal-delivery.ts";
 export * from "./terminal-graphics.ts";
+export * from "./terminal-graphics-compressed.ts";
+export * from "./terminal-surfaces.ts";
 export * from "./terminal-runtime-inventory.ts";
 export * from "./experience-shell.ts";
 export * from "./application-shell.ts";
@@ -120,3 +122,7 @@ export * from "./tmux-agent-open.ts";
 export * from "./tmux-server-diagnostics.ts";
 
 export * from "./terminal-history-anchor.ts";
+
+export * from "./terminal-delivery-binary-chunk.ts";
+
+export * from "./terminal-projection.ts";

package/packages/contracts/src/pane-stream.ts

@@ -1,3 +1,17 @@
+import {
+  TerminalSurfaceWatchSchemaZ,
+  TerminalSurfaceReceiverSchemaZ,
+  TerminalSurfaceAvailableSchemaZ,
+  TerminalSurfacePeerSchemaZ,
+  TerminalSurfaceOfferSchemaZ,
+  TerminalSurfaceRetiredSchemaZ,
+  TerminalSurfaceFallbackSchemaZ,
+} from "./terminal-surfaces.ts";
+import {
+  TerminalProjectionEnvelopeSchemaZ,
+  TerminalProjectionReceiptSchemaZ,
+  TerminalProjectionMaterializeSchemaZ,
+} from "./terminal-projection.ts";
 import { z } from "zod";
 import { isTmuxServerPaneStreamPath } from "./tmux-server-scope.ts";
 import {
@@ -45,6 +59,7 @@ import {
   SessionRuntimePresenceStateSchemaZ,
   SessionRuntimeSemanticIntentSchemaZ,
   SessionRuntimeTerminalKeyInputSchemaZ,
+  SessionRuntimeTerminalBytesInputSchemaZ,
   SessionRuntimeTerminalKeyNameSchemaZ,
   SessionRuntimeTerminalTextInputSchemaZ,
 } from "./session-runtime.ts";
@@ -232,6 +247,8 @@ export const PaneStreamKeyNameSchemaZ = SessionRuntimeTerminalKeyNameSchemaZ;
 
 /** Negotiated only with callers offering this additive delivery capability. */
 export const PANE_STREAM_INPUT_LIFETIME_CAPABILITY_VERSION = 105;
+/** Exact hex bytes require explicit offer + ready acknowledgement; older daemons may omit it. */
+export const PANE_STREAM_INPUT_BYTES_CAPABILITY_VERSION = 106;
 export const PaneStreamInputLifetimeSchemaZ = z
   .object({
     generation: z.string().min(1).max(256),
@@ -254,6 +271,7 @@ export const PaneStreamInputFrameSchemaZ = z
   .discriminatedUnion("kind", [
     SessionRuntimeTerminalTextInputSchemaZ.extend(PaneStreamInputFrameMetadataShape),
     SessionRuntimeTerminalKeyInputSchemaZ.extend(PaneStreamInputFrameMetadataShape),
+    SessionRuntimeTerminalBytesInputSchemaZ.extend(PaneStreamInputFrameMetadataShape),
   ])
   .superRefine((value, context) => {
     if (!value.causalProbe) return;
@@ -279,6 +297,18 @@ export type PaneStreamConsumedFrame = z.infer<typeof PaneStreamConsumedFrameSche
 export const PaneStreamTerminalDeliveryAckFrameSchemaZ = z
   .object({ type: z.literal("terminal-delivery-ack"), ack: TerminalDeliveryAckSchemaZ })
   .strict();
+export const PaneStreamTerminalProjectionReceiptFrameSchemaZ = z
+  .object({
+    type: z.literal("terminal-projection-receipt"),
+    receipt: TerminalProjectionReceiptSchemaZ,
+  })
+  .strict();
+export const PaneStreamTerminalProjectionMaterializeFrameSchemaZ = z
+  .object({
+    type: z.literal("terminal-projection-materialize"),
+    request: TerminalProjectionMaterializeSchemaZ,
+  })
+  .strict();
 export const PaneStreamTerminalDeliveryNackFrameSchemaZ = z
   .object({ type: z.literal("terminal-delivery-nack"), nack: TerminalDeliveryNackSchemaZ })
   .strict();
@@ -363,6 +393,7 @@ export const PaneStreamClockProbeFrameSchemaZ = z
 export const PaneStreamTerminalGraphicsRequestFrameSchemaZ = z
   .object({
     type: z.literal("terminal-graphics-request"),
+    preferInline: z.literal(true).optional(),
     pane: PaneStreamSemanticPaneIdSchemaZ,
     digests: z
       .array(TerminalGraphicsDigestSchemaZ)
@@ -371,6 +402,15 @@ export const PaneStreamTerminalGraphicsRequestFrameSchemaZ = z
   })
   .strict();
 
+export const PaneStreamTerminalGraphicsLocalReleaseFrameSchemaZ = z
+  .object({
+    type: z.literal("terminal-graphics-local-release"),
+    pane: PaneStreamSemanticPaneIdSchemaZ,
+    generation: z.uuid(),
+    leaseId: z.uuid(),
+  })
+  .strict();
+
 /** The renderer's terminal cell size in device pixels (see capability 103). */
 export const PaneStreamTerminalCellPixelsFrameSchemaZ = z
   .object({
@@ -391,6 +431,8 @@ export const PaneStreamClientFrameSchemaZ = z.union([
   PaneStreamInputFrameSchemaZ,
   PaneStreamConsumedFrameSchemaZ,
   PaneStreamTerminalDeliveryAckFrameSchemaZ,
+  PaneStreamTerminalProjectionReceiptFrameSchemaZ,
+  PaneStreamTerminalProjectionMaterializeFrameSchemaZ,
   PaneStreamTerminalDeliveryNackFrameSchemaZ,
   PaneStreamTerminalDeliveryVisibilityFrameSchemaZ,
   PaneStreamSemanticIntentFrameSchemaZ,
@@ -401,7 +443,12 @@ export const PaneStreamClientFrameSchemaZ = z.union([
   PaneStreamAuthorityReleaseFrameSchemaZ,
   PaneStreamClockProbeFrameSchemaZ,
   PaneStreamTerminalGraphicsRequestFrameSchemaZ,
+  PaneStreamTerminalGraphicsLocalReleaseFrameSchemaZ,
   PaneStreamTerminalCellPixelsFrameSchemaZ,
+  TerminalSurfaceWatchSchemaZ,
+  TerminalSurfaceReceiverSchemaZ,
+  TerminalSurfaceRetiredSchemaZ,
+  TerminalSurfaceFallbackSchemaZ,
 ]);
 export type PaneStreamClientFrame = z.infer<typeof PaneStreamClientFrameSchemaZ>;
 
@@ -421,6 +468,7 @@ export const PaneStreamReadyFrameSchemaZ = z
   .object({
     type: z.literal("ready"),
     inputLifetime: z.literal(true).optional(),
+    inputBytes: z.literal(true).optional(),
     protocolVersion: z.literal(PANE_STREAM_PROTOCOL_VERSION),
     daemonInstanceId: BoundedIdentitySchemaZ,
     requestId: z.uuid(),
@@ -678,6 +726,13 @@ export const PaneStreamTerminalDeliveryEnvelopeFrameSchemaZ = z
     envelope: TerminalDeliveryEnvelopeSchemaZ,
   })
   .strict();
+export const PaneStreamTerminalProjectionEnvelopeFrameSchemaZ = z
+  .object({
+    type: z.literal("terminal-projection-envelope"),
+    pane: PaneStreamSemanticPaneIdSchemaZ,
+    envelope: TerminalProjectionEnvelopeSchemaZ,
+  })
+  .strict();
 export const PaneStreamTerminalDeliveryChunkFrameSchemaZ = z
   .object({
     type: z.literal("terminal-delivery-chunk"),
@@ -709,6 +764,22 @@ export const PaneStreamTerminalGraphicsBlobFrameSchemaZ = z
     data: Base64SchemaZ(Math.ceil(TERMINAL_GRAPHICS_BLOB_CHUNK_BYTES / 3) * 4).min(4),
   })
   .strict();
+export const PaneStreamTerminalGraphicsLocalFrameSchemaZ = z
+  .object({
+    type: z.literal("terminal-graphics-local"),
+    pane: PaneStreamSemanticPaneIdSchemaZ,
+    generation: z.uuid(),
+    leaseId: z.uuid(),
+    path: z
+      .string()
+      .min(1)
+      .max(4096)
+      .refine((path) => path.startsWith("/") && !path.includes("\0")),
+    expiresAt: z.number().int().positive().safe(),
+    blob: TerminalGraphicsBlobSchemaZ.extend({ offset: z.literal(0) }),
+  })
+  .strict();
+
 export const PaneStreamSemanticIntentAckFrameSchemaZ = z
   .object({
     type: z.literal("semantic-intent-ack"),
@@ -797,6 +868,10 @@ export const PaneStreamErrorFrameSchemaZ = z
   .strict();
 
 export const PaneStreamServerFrameSchemaZ = z.discriminatedUnion("type", [
+  TerminalSurfaceAvailableSchemaZ,
+  TerminalSurfacePeerSchemaZ,
+  TerminalSurfaceOfferSchemaZ,
+  TerminalSurfaceFallbackSchemaZ,
   PaneStreamReadyFrameSchemaZ,
   PaneStreamSeedBatchFrameSchemaZ,
   PaneStreamOutputFrameSchemaZ,
@@ -811,10 +886,12 @@ export const PaneStreamServerFrameSchemaZ = z.discriminatedUnion("type", [
   PaneStreamCausalCellFailureFrameSchemaZ,
   PaneStreamTerminalDeliveryReadyFrameSchemaZ,
   PaneStreamTerminalDeliveryEnvelopeFrameSchemaZ,
+  PaneStreamTerminalProjectionEnvelopeFrameSchemaZ,
   PaneStreamTerminalDeliveryChunkFrameSchemaZ,
   PaneStreamTerminalDeliveryFaultFrameSchemaZ,
   PaneStreamTerminalGraphicsFrameSchemaZ,
   PaneStreamTerminalGraphicsBlobFrameSchemaZ,
+  PaneStreamTerminalGraphicsLocalFrameSchemaZ,
   PaneStreamSemanticIntentAckFrameSchemaZ,
   PaneStreamViewportAckFrameSchemaZ,
   PaneStreamAuthoritySnapshotFrameSchemaZ,

package/packages/contracts/src/terminal-delivery-binary-chunk.ts

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import { TerminalAttachmentSemanticPaneIdSchemaZ } from "./semantic-identity.ts";
+import { TERMINAL_DELIVERY_CHUNK_BYTES } from "./terminal-delivery.ts";
+export const TerminalDeliveryBinaryChunkHeaderSchemaZ = z
+  .object({
+    pane: TerminalAttachmentSemanticPaneIdSchemaZ,
+    transactionId: z.uuid(),
+    index: z.number().int().min(0).max(255),
+  })
+  .strict();
+export type TerminalDeliveryBinaryChunkHeader = z.infer<
+  typeof TerminalDeliveryBinaryChunkHeaderSchemaZ
+>;
+/** TDC1 + u32be metadata length + strict header + unchanged representation chunk. */
+export function encodeTerminalDeliveryBinaryChunk(
+  header: TerminalDeliveryBinaryChunkHeader,
+  bytes: Uint8Array,
+): Uint8Array {
+  const parsed = TerminalDeliveryBinaryChunkHeaderSchemaZ.parse(header);
+  const json = new TextEncoder().encode(JSON.stringify(parsed));
+  if (json.length > 4096 || bytes.length > TERMINAL_DELIVERY_CHUNK_BYTES)
+    throw new TypeError("Binary delivery chunk bound");
+  const result = new Uint8Array(8 + json.length + bytes.length);
+  result.set([84, 68, 67, 49]);
+  new DataView(result.buffer).setUint32(4, json.length, false);
+  result.set(json, 8);
+  result.set(bytes, 8 + json.length);
+  return result;
+}
+export function decodeTerminalDeliveryBinaryChunk(data: Uint8Array): {
+  header: TerminalDeliveryBinaryChunkHeader;
+  bytes: Uint8Array;
+} {
+  if (
+    data.length < 9 ||
+    data.length > 8 + 4096 + TERMINAL_DELIVERY_CHUNK_BYTES ||
+    data[0] !== 84 ||
+    data[1] !== 68 ||
+    data[2] !== 67 ||
+    data[3] !== 49
+  )
+    throw new TypeError("Invalid binary delivery packet");
+  const length = new DataView(data.buffer, data.byteOffset, data.byteLength).getUint32(4, false);
+  if (
+    length < 1 ||
+    length > 4096 ||
+    8 + length > data.length ||
+    data.length - 8 - length > TERMINAL_DELIVERY_CHUNK_BYTES
+  )
+    throw new TypeError("Invalid binary delivery header bound");
+  const header = TerminalDeliveryBinaryChunkHeaderSchemaZ.parse(
+    JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(data.subarray(8, 8 + length))),
+  );
+  return { header, bytes: data.subarray(8 + length) };
+}

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

@@ -1,3 +1,4 @@
+import type { TerminalProjectionEnvelope } from "./terminal-projection.ts";
 import { z } from "zod";
 import { CausalCellProofV1SchemaZ } from "./causal-cell.ts";
 import { TerminalAttachmentSemanticPaneIdSchemaZ } from "./semantic-identity.ts";
@@ -13,6 +14,11 @@ import {
 export const STOCK_CAPTURE_TAB_UNAVAILABLE =
   "This tmux server cannot provide an exact snapshot of saved tab cells. Continue this session in native tmux, or use a new session started with tmux-ide's bundled server.";
 
+/** Opt-in bundles:109 adds binary cells+107 graphics;110 also adds108 local image leases.
+ * Offer compact in encodings for old-daemon compatibility; new daemons respond binary explicitly. */
+export const TERMINAL_DELIVERY_BINARY_CAPABILITY_VERSION = 109;
+export const TERMINAL_DELIVERY_BINARY_LOCAL_CAPABILITY_VERSION = 110;
+
 export const TERMINAL_DELIVERY_PROTOCOL_VERSION = 1 as const;
 export const TERMINAL_DELIVERY_CHUNK_BYTES = 256 * 1024;
 export const TERMINAL_DELIVERY_PATCH_TO_SEED_BYTES = 512 * 1024;
@@ -20,6 +26,7 @@ export const TERMINAL_DELIVERY_MAX_REPRESENTATION_BYTES = 16 * 1024 * 1024;
 
 export const TerminalDeliveryEncodingSchemaZ = z.enum([
   "semantic-compact-v1",
+  "semantic-binary-v1",
   "semantic-v1",
   "ansi-diff-v1",
   "ansi-raw-v1",
@@ -28,7 +35,8 @@ export type TerminalDeliveryEncoding = z.infer<typeof TerminalDeliveryEncodingSc
 
 export const TerminalDeliveryOfferSchemaZ = z
   .object({
-    protocolVersions: z.array(z.number().int().positive()).min(1).max(8),
+    // Interactive binary/graphics offers use eight slots; native surfaces add one.
+    protocolVersions: z.array(z.number().int().positive()).min(1).max(9),
     encodings: z.array(TerminalDeliveryEncodingSchemaZ).min(1).max(4),
     richPlacements: z.boolean(),
   })
@@ -46,18 +54,22 @@ export const TerminalDeliveryNegotiatedSchemaZ = z
     protocolVersion: z.literal(TERMINAL_DELIVERY_PROTOCOL_VERSION),
     encoding: TerminalDeliveryEncodingSchemaZ,
     fallbackEncoding: z.literal("semantic-v1").nullable().optional(),
+    alternateScreenProjection: z.literal("deferred-history-v1").optional(),
     richPlacements: z.boolean(),
     generation: SessionRuntimeGenerationSchemaZ,
     deliveryNonce: z.uuid(),
   })
   .strict()
   .superRefine((value, context) => {
+    if (value.alternateScreenProjection && value.encoding !== "semantic-binary-v1")
+      context.addIssue({ code: "custom", message: "projection requires binary semantic delivery" });
     if (value.fallbackEncoding && value.encoding !== "semantic-compact-v1")
       context.addIssue({ code: "custom", message: "fallback encoding requires compact semantic" });
     if (
       value.richPlacements &&
       value.encoding !== "semantic-v1" &&
-      value.encoding !== "semantic-compact-v1"
+      value.encoding !== "semantic-compact-v1" &&
+      value.encoding !== "semantic-binary-v1"
     )
       context.addIssue({ code: "custom", message: "rich placements require semantic delivery" });
   });
@@ -118,7 +130,10 @@ export const TerminalDeliveryEnvelopeSchemaZ = DeliveryAddressSchemaZ.extend({
 })
   .strict()
   .superRefine((value, context) => {
-    const semantic = value.encoding === "semantic-v1" || value.encoding === "semantic-compact-v1";
+    const semantic =
+      value.encoding === "semantic-v1" ||
+      value.encoding === "semantic-compact-v1" ||
+      value.encoding === "semantic-binary-v1";
     const expectedChunks = Math.max(
       1,
       Math.ceil(value.representationBytes / TERMINAL_DELIVERY_CHUNK_BYTES),
@@ -206,6 +221,7 @@ export type TerminalDeliveryNack = z.infer<typeof TerminalDeliveryNackSchemaZ>;
 
 export type TerminalDeliveryServerMessage =
   | TerminalDeliveryEnvelope
+  | TerminalProjectionEnvelope
   | TerminalDeliveryChunk
   | TerminalDeliveryFault;
 

package/packages/contracts/src/terminal-graphics-compressed.ts

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import {
+  TerminalGraphicsBinaryHeaderSchemaZ,
+  TERMINAL_GRAPHICS_BINARY_HEADER_BYTES,
+  TERMINAL_GRAPHICS_BLOB_CHUNK_BYTES,
+} from "./terminal-graphics.ts";
+
+/** TGB2 uses an independent zlib stream per chunk. Digest/offset/total still
+ * describe the original image bytes. Decoders must require exact output length,
+ * stream termination and complete input consumption before hashing or painting. */
+export const TerminalGraphicsCompressedHeaderSchemaZ = TerminalGraphicsBinaryHeaderSchemaZ.extend({
+  compression: z.literal("zlib"),
+  decodedBytes: z.number().int().min(1).max(TERMINAL_GRAPHICS_BLOB_CHUNK_BYTES),
+}).superRefine((header, context) => {
+  if (
+    header.blob.offset + header.decodedBytes > header.blob.total ||
+    (header.blob.format !== "rgb" && header.blob.format !== "rgba")
+  )
+    context.addIssue({ code: "custom", message: "Invalid compressed graphics range or format" });
+});
+export type TerminalGraphicsCompressedHeader = z.infer<
+  typeof TerminalGraphicsCompressedHeaderSchemaZ
+>;
+export function encodeTerminalGraphicsCompressed(
+  header: TerminalGraphicsCompressedHeader,
+  bytes: Uint8Array,
+): Uint8Array {
+  const parsed = TerminalGraphicsCompressedHeaderSchemaZ.parse(header);
+  const json = new TextEncoder().encode(JSON.stringify(parsed));
+  if (
+    json.length > TERMINAL_GRAPHICS_BINARY_HEADER_BYTES ||
+    bytes.length < 1 ||
+    bytes.length >= parsed.decodedBytes
+  )
+    throw new Error("Invalid compressed graphics bounds");
+  const result = new Uint8Array(8 + json.length + bytes.length);
+  result.set([84, 71, 66, 50]);
+  new DataView(result.buffer).setUint32(4, json.length, false);
+  result.set(json, 8);
+  result.set(bytes, 8 + json.length);
+  return result;
+}
+/** Only parses the envelope; inflation belongs on the receiving worker. */
+export function decodeTerminalGraphicsCompressed(data: Uint8Array): {
+  header: TerminalGraphicsCompressedHeader;
+  bytes: Uint8Array;
+} {
+  if (
+    data.length < 10 ||
+    data.length > 8 + TERMINAL_GRAPHICS_BINARY_HEADER_BYTES + TERMINAL_GRAPHICS_BLOB_CHUNK_BYTES ||
+    data[0] !== 84 ||
+    data[1] !== 71 ||
+    data[2] !== 66 ||
+    data[3] !== 50
+  )
+    throw new Error("Invalid compressed graphics frame");
+  const length = new DataView(data.buffer, data.byteOffset, data.byteLength).getUint32(4, false);
+  if (length < 1 || length > TERMINAL_GRAPHICS_BINARY_HEADER_BYTES || 8 + length >= data.length)
+    throw new Error("Invalid compressed graphics header");
+  const header = TerminalGraphicsCompressedHeaderSchemaZ.parse(
+    JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(data.subarray(8, 8 + length))),
+  );
+  const bytes = data.subarray(8 + length);
+  if (bytes.length >= header.decodedBytes) throw new Error("Invalid compressed graphics payload");
+  return { header, bytes };
+}

package/packages/contracts/src/terminal-graphics.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { TerminalAttachmentSemanticPaneIdSchemaZ } from "./semantic-identity.ts";
 
 /**
  * Kitty graphics protocol side channel.
@@ -15,6 +16,16 @@ import { z } from "zod";
  * version; daemons that know it send graphics frames only to such renderers.
  */
 export const TERMINAL_GRAPHICS_CAPABILITY_VERSION = 101;
+/** Raw binary blob frames; requires the graphics side channel (101). */
+export const TERMINAL_GRAPHICS_BINARY_CAPABILITY_VERSION = 107;
+/** Bundles 113/114 include projection 111/112 and bounded lossless raw-pixel chunks.
+ * Older daemons ignore these and retain the offered compact/text and JSON graphics fallback. */
+export const TERMINAL_GRAPHICS_COMPRESSED_CAPABILITY_VERSION = 113;
+export const TERMINAL_GRAPHICS_COMPRESSED_LOCAL_CAPABILITY_VERSION = 114;
+/** Verified same-host file leases, including binary-blob fallback (107).
+ * Offer 108 instead of 107 to retain the existing eight-capability bound.
+ * Never infer locality from a loopback URL. */
+export const TERMINAL_GRAPHICS_LOCAL_CAPABILITY_VERSION = 108;
 /** Renderers that inflate `rgba-zlib`/`rgb-zlib` themselves offer this too. */
 export const TERMINAL_GRAPHICS_ZLIB_CAPABILITY_VERSION = 102;
 /**
@@ -92,6 +103,9 @@ export const TerminalGraphicsStateSchemaZ = z
     /** The daemon accepts `terminal-cell-pixels` (only sent to renderers offering 103). */
     cellPixels: z.literal(true).optional(),
     preciseCellPixels: z.literal(true).optional(),
+    binaryBlobs: z.literal(true).optional(),
+    compressedBlobs: z.literal(true).optional(),
+    localFiles: z.literal(true).optional(),
   })
   .strict();
 export type TerminalGraphicsState = z.infer<typeof TerminalGraphicsStateSchemaZ>;
@@ -116,3 +130,62 @@ export type TerminalGraphicsServerMessage =
       readonly blob: TerminalGraphicsBlob;
       readonly bytes: Uint8Array;
     };
+
+/** TGB1 + u32be header bytes + strict JSON {pane,blob} + raw payload.
+ * No compression is applied here: PNG and negotiated zlib are already encoded.
+ */
+export const TERMINAL_GRAPHICS_BINARY_HEADER_BYTES = 4096;
+export const TerminalGraphicsBinaryHeaderSchemaZ = z
+  .object({
+    pane: TerminalAttachmentSemanticPaneIdSchemaZ,
+    blob: TerminalGraphicsBlobSchemaZ,
+  })
+  .strict();
+export type TerminalGraphicsBinaryHeader = z.infer<typeof TerminalGraphicsBinaryHeaderSchemaZ>;
+export function encodeTerminalGraphicsBinary(
+  header: TerminalGraphicsBinaryHeader,
+  bytes: Uint8Array,
+): Uint8Array {
+  const parsed = TerminalGraphicsBinaryHeaderSchemaZ.parse(header);
+  const json = new TextEncoder().encode(JSON.stringify(parsed));
+  if (
+    json.length > TERMINAL_GRAPHICS_BINARY_HEADER_BYTES ||
+    bytes.length < 1 ||
+    bytes.length > TERMINAL_GRAPHICS_BLOB_CHUNK_BYTES ||
+    parsed.blob.offset + bytes.length > parsed.blob.total
+  )
+    throw new Error("Invalid binary graphics bounds");
+  const result = new Uint8Array(8 + json.length + bytes.length);
+  result.set([84, 71, 66, 49]);
+  new DataView(result.buffer).setUint32(4, json.length, false);
+  result.set(json, 8);
+  result.set(bytes, 8 + json.length);
+  return result;
+}
+export function decodeTerminalGraphicsBinary(data: Uint8Array): {
+  header: TerminalGraphicsBinaryHeader;
+  bytes: Uint8Array;
+} {
+  if (
+    data.length < 10 ||
+    data.length > 8 + TERMINAL_GRAPHICS_BINARY_HEADER_BYTES + TERMINAL_GRAPHICS_BLOB_CHUNK_BYTES ||
+    data[0] !== 84 ||
+    data[1] !== 71 ||
+    data[2] !== 66 ||
+    data[3] !== 49
+  )
+    throw new Error("Invalid binary graphics frame");
+  const length = new DataView(data.buffer, data.byteOffset, data.byteLength).getUint32(4, false);
+  if (length < 1 || length > TERMINAL_GRAPHICS_BINARY_HEADER_BYTES || 8 + length >= data.length)
+    throw new Error("Invalid binary graphics header");
+  const header = TerminalGraphicsBinaryHeaderSchemaZ.parse(
+    JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(data.subarray(8, 8 + length))),
+  );
+  const bytes = data.subarray(8 + length);
+  if (
+    bytes.length > TERMINAL_GRAPHICS_BLOB_CHUNK_BYTES ||
+    header.blob.offset + bytes.length > header.blob.total
+  )
+    throw new Error("Invalid binary graphics payload");
+  return { header, bytes };
+}

package/packages/contracts/src/terminal-projection.ts

@@ -0,0 +1,153 @@
+import { z } from "zod";
+import {
+  TerminalReplicaSnapshotSchemaZ,
+  TerminalReplicaPatchPayloadSchemaZ,
+  TerminalReplicaTombstonePayloadSchemaZ,
+} from "./terminal-replica.ts";
+import { TerminalAttachmentSemanticPaneIdSchemaZ } from "./semantic-identity.ts";
+import { SessionRuntimeGenerationSchemaZ } from "./session-runtime.ts";
+import { WorkspaceIdSchemaZ } from "./workspace-state.ts";
+import {
+  TERMINAL_DELIVERY_CHUNK_BYTES,
+  TERMINAL_DELIVERY_MAX_REPRESENTATION_BYTES,
+} from "./terminal-delivery.ts";
+
+/** Bundles111/112 include109/110 respectively; the old-compatible encoding offer stays compact. */
+export const TERMINAL_PROJECTION_CAPABILITY_VERSION = 111;
+export const TERMINAL_PROJECTION_LOCAL_CAPABILITY_VERSION = 112;
+const Hash = z.string().regex(/^[0-9a-f]{16}$/u);
+const Revision = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+export const TerminalDeferredHistorySchemaZ = z
+  .object({ rows: z.number().int().min(0).max(10000), digest: Hash })
+  .strict();
+export type TerminalDeferredHistory = z.infer<typeof TerminalDeferredHistorySchemaZ>;
+const ProjectionModes = TerminalReplicaSnapshotSchemaZ.shape.modes.extend({
+  alternateScreen: z.literal(true),
+});
+/** A viewport projection is not a materialized canonical snapshot. History is deliberately absent. */
+export const TerminalProjectionSnapshotSchemaZ = TerminalReplicaSnapshotSchemaZ.omit({
+  history: true,
+})
+  .extend({
+    cols: z.number().int().min(1).max(4096),
+    rows: z.number().int().min(1).max(4096),
+    grid: TerminalReplicaSnapshotSchemaZ.shape.grid.max(4096),
+    modes: ProjectionModes,
+    placements: TerminalReplicaSnapshotSchemaZ.shape.placements.max(4096),
+    deferredHistory: TerminalDeferredHistorySchemaZ,
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    if (
+      value.grid.length !== value.rows ||
+      value.grid.some((row) => row.cells.length !== value.cols) ||
+      value.cols * value.rows > 1_000_000
+    )
+      ctx.addIssue({ code: "custom", message: "Invalid projection grid dimensions" });
+    if (
+      value.cursor.x >= value.cols ||
+      value.cursor.y >= value.rows ||
+      value.placements.some((p) => p.row + p.rows > value.rows || p.column + p.columns > value.cols)
+    )
+      ctx.addIssue({ code: "custom", message: "Projection metadata outside viewport" });
+  });
+export type TerminalProjectionSnapshot = z.infer<typeof TerminalProjectionSnapshotSchemaZ>;
+export const TerminalProjectionPatchSchemaZ = TerminalReplicaPatchPayloadSchemaZ.omit({
+  history: true,
+  historyDelta: true,
+})
+  .extend({
+    modes: ProjectionModes.optional(),
+    dimensions: z
+      .object({ cols: z.number().int().min(1).max(4096), rows: z.number().int().min(1).max(4096) })
+      .strict()
+      .optional(),
+    placements: TerminalReplicaSnapshotSchemaZ.shape.placements.max(4096).optional(),
+    deferredHistory: TerminalDeferredHistorySchemaZ,
+    rows: TerminalReplicaPatchPayloadSchemaZ.shape.rows.max(4096),
+  })
+  .strict();
+export type TerminalProjectionPatch = z.infer<typeof TerminalProjectionPatchSchemaZ>;
+export const TerminalProjectionPayloadSchemaZ = z
+  .discriminatedUnion("frame", [
+    z
+      .object({
+        frame: z.literal("seed"),
+        revision: Revision,
+        projection: TerminalProjectionSnapshotSchemaZ,
+      })
+      .strict(),
+    z
+      .object({
+        frame: z.literal("patch"),
+        baseRevision: Revision,
+        revision: Revision,
+        patch: TerminalProjectionPatchSchemaZ,
+      })
+      .strict(),
+    z
+      .object({
+        frame: z.literal("tombstone"),
+        baseRevision: Revision,
+        revision: Revision,
+        tombstone: TerminalReplicaTombstonePayloadSchemaZ,
+      })
+      .strict(),
+  ])
+  .superRefine((value, ctx) => {
+    if (value.frame !== "seed" && value.revision <= value.baseRevision)
+      ctx.addIssue({ code: "custom", message: "Projection revision must advance" });
+  });
+export type TerminalProjectionPayload = z.infer<typeof TerminalProjectionPayloadSchemaZ>;
+const Address = z.object({
+  workspaceName: WorkspaceIdSchemaZ,
+  semanticPaneId: TerminalAttachmentSemanticPaneIdSchemaZ,
+  generation: SessionRuntimeGenerationSchemaZ,
+  incarnation: z.string().min(1).max(256),
+  deliveryNonce: z.uuid(),
+});
+const Proof = Address.extend({
+  transactionId: z.uuid(),
+  /** Source canonical root/revision; receipt does not assert history materialization. */
+  canonicalRevision: Revision,
+  canonicalStateHash: Hash,
+  projectionStateHash: Hash,
+  representationHash: Hash,
+});
+export const TerminalProjectionEnvelopeSchemaZ = Proof.extend({
+  type: z.literal("terminal.projection"),
+  performanceTraceId: z.uuid().optional(),
+  protocolVersion: z.literal(1),
+  encoding: z.literal("alternate-projection-binary-v1"),
+  frame: z.enum(["seed", "patch", "tombstone"]),
+  baseRevision: Revision.nullable(),
+  representationBytes: z.number().int().min(1).max(TERMINAL_DELIVERY_MAX_REPRESENTATION_BYTES),
+  chunkCount: z.number().int().min(1).max(256),
+  canonicalEquivalent: z.literal(false),
+  history: z.literal("deferred"),
+  richPlacements: z.boolean(),
+})
+  .strict()
+  .superRefine((value, ctx) => {
+    if (value.chunkCount !== Math.ceil(value.representationBytes / TERMINAL_DELIVERY_CHUNK_BYTES))
+      ctx.addIssue({ code: "custom", message: "Projection chunk count mismatch" });
+    if (
+      value.frame === "seed"
+        ? value.baseRevision !== null
+        : value.baseRevision === null || value.canonicalRevision <= value.baseRevision
+    )
+      ctx.addIssue({ code: "custom", message: "Projection base revision mismatch" });
+  });
+export type TerminalProjectionEnvelope = z.infer<typeof TerminalProjectionEnvelopeSchemaZ>;
+/** This is never a TerminalDeliveryAck and must not advance a complete baseline. */
+export const TerminalProjectionReceiptSchemaZ = Proof.extend({
+  type: z.literal("terminal.projection.receipt"),
+}).strict();
+export type TerminalProjectionReceipt = z.infer<typeof TerminalProjectionReceiptSchemaZ>;
+export const TerminalProjectionMaterializeSchemaZ = Address.extend({
+  type: z.literal("terminal.projection.materialize"),
+  requestId: z.uuid(),
+  canonicalRevision: Revision,
+  projectionStateHash: Hash,
+}).strict();
+export type TerminalProjectionMaterialize = z.infer<typeof TerminalProjectionMaterializeSchemaZ>;