tmux-ide 2.9.11 → 2.9.13

package/packages/daemon/src/terminal/pane-stream/runtime.ts

@@ -1,3 +1,5 @@
+import type { LocalImageOwner } from "../graphics/local-image-owner.ts";
+import { NativeSurfaceProviderRegistry } from "../graphics/native-surface-provider.ts";
 import type { SemanticPaneCatalog } from "../attachments/semantic-pane-catalog.ts";
 import type { SessionRuntimeRegistry } from "../session-runtime/registry.ts";
 import { SessionRuntimeTransportBinder } from "../session-runtime/transport-binding.ts";
@@ -9,6 +11,8 @@ import {
 } from "./pane-stream-websocket.ts";
 
 export interface PaneStreamRuntimeOptions {
+  readonly nativeSurfaces?: NativeSurfaceProviderRegistry;
+  readonly localImages?: LocalImageOwner;
   readonly daemonInstanceId: string;
   readonly webSocketUrl: string;
   /** Canonical daemon-generation session/control owner. */
@@ -18,7 +22,7 @@ export interface PaneStreamRuntimeOptions {
   readonly observability?: SessionRuntimeObservability;
   readonly admission?: Omit<
     PaneStreamAdmissionCoordinatorOptions,
-    "daemonInstanceId" | "webSocketUrl" | "leaseManager" | "mirror"
+    "daemonInstanceId" | "webSocketUrl" | "leaseManager" | "mirror" | "nativeSurfaces"
   >;
 }
 
@@ -29,15 +33,23 @@ export interface PaneStreamRuntimeOptions {
  */
 export class PaneStreamRuntime {
   readonly coordinator: PaneStreamAdmissionCoordinator;
+  readonly nativeSurfaces: NativeSurfaceProviderRegistry | undefined;
   #disposePromise: Promise<void> | null = null;
 
   constructor(options: PaneStreamRuntimeOptions) {
+    this.nativeSurfaces =
+      options.nativeSurfaces ??
+      (process.platform === "darwin"
+        ? new NativeSurfaceProviderRegistry(options.daemonInstanceId)
+        : undefined);
     const leaseManager = new PaneStreamLeaseManager({
       daemonInstanceId: options.daemonInstanceId,
     });
     const transportBinder = new SessionRuntimeTransportBinder(options.sessionRuntimeRegistry);
     this.coordinator = new PaneStreamAdmissionCoordinator({
       ...options.admission,
+      localImages: options.localImages,
+      nativeSurfaces: this.nativeSurfaces,
       daemonInstanceId: options.daemonInstanceId,
       webSocketUrl: options.webSocketUrl,
       leaseManager,
@@ -66,6 +78,7 @@ export class PaneStreamRuntime {
   dispose(): Promise<void> {
     if (!this.#disposePromise) {
       this.#disposePromise = (async () => {
+        this.nativeSurfaces?.close();
         await this.coordinator.shutdown();
       })();
     }

package/packages/daemon/src/terminal/session-runtime/registry.ts

@@ -2472,6 +2472,8 @@ class SessionRuntimeConsumerImpl implements SessionRuntimeConsumer {
       negotiation: upstream.negotiation,
       closed: upstream.closed,
       ack: (ack: TerminalDeliveryAck) => upstream.ack(ack),
+      ...(upstream.projectionReceipt ? { projectionReceipt: upstream.projectionReceipt } : {}),
+      ...(upstream.materialize ? { materialize: upstream.materialize } : {}),
       nack: (nack: TerminalDeliveryNack) => upstream.nack(nack),
       setVisibility: (visibility: TerminalDeliveryVisibility) => upstream.setVisibility(visibility),
       close: async () => {

package/packages/daemon/src/terminal/session-runtime/runtime-observability.ts

@@ -81,7 +81,7 @@ export interface SessionRuntimeStageSpan {
     readonly attemptedLegacySeedSizeCapped?: boolean;
     readonly attemptedCompactPatchBytes?: number | null;
     readonly attemptedCompactSeedBytes?: number | null;
-    readonly selectedEncoding?: "semantic-v1" | "semantic-compact-v1";
+    readonly selectedEncoding?: "semantic-v1" | "semantic-compact-v1" | "semantic-binary-v1";
     readonly selectionStatus?:
       | "patch-preferred"
       | "seed-preferred"

package/packages/daemon/src/terminal/session-runtime/terminal-delivery-hub.ts

@@ -1,3 +1,15 @@
+import { prepareProjection, type ProjectionBaseline } from "./terminal-projection-delivery.ts";
+import {
+  TerminalProjectionEnvelopeSchemaZ,
+  TerminalProjectionReceiptSchemaZ,
+  TerminalProjectionMaterializeSchemaZ,
+  type TerminalProjectionEnvelope,
+  type TerminalProjectionReceipt,
+  type TerminalProjectionMaterialize,
+  type TerminalProjectionPayload,
+} from "@tmux-ide/contracts";
+import { encodeTerminalProjectionCooperatively } from "@tmux-ide/core";
+type DeliveryEnvelope = TerminalDeliveryEnvelope | TerminalProjectionEnvelope;
 import type { KittyImage } from "../graphics/kitty-graphics.ts";
 import { StockCaptureTabUnavailableError } from "./stock-capture-fidelity.ts";
 import {
@@ -37,6 +49,8 @@ import {
   applyTerminalReplicaUpdate,
   applyTerminalReplicaUpdateCooperatively,
   terminalReplicaUpdateNeedsCooperativeReduction,
+  encodeBinarySemanticTerminalUpdate,
+  encodeBinarySemanticTerminalUpdateCooperatively,
   encodeCompactSemanticTerminalUpdate,
   encodeCompactSemanticTerminalUpdateCooperatively,
   terminalSemanticUpdateNeedsCooperativeEncoding,
@@ -124,6 +138,8 @@ export interface TerminalDeliveryConnection {
   readonly closed: Promise<"closed" | "sink-failed">;
   readonly negotiation: TerminalDeliveryNegotiationResult;
   ack(ack: TerminalDeliveryAck): void;
+  projectionReceipt?(receipt: TerminalProjectionReceipt): void;
+  materialize?(request: TerminalProjectionMaterialize): void;
   nack(nack: TerminalDeliveryNack): void;
   setVisibility(visibility: TerminalDeliveryVisibility): void;
   close(): Promise<void>;
@@ -205,9 +221,14 @@ interface ClientState {
   visibility: TerminalDeliveryVisibility;
   baselineRevision: number;
   baselineHash: string | null;
+  projectionBaseline: ProjectionBaseline | null;
+  materializeRequested: boolean;
+  lastProjectionReceipt: TerminalProjectionReceipt | null;
+  lastMaterialize: TerminalProjectionMaterialize | null;
   reseedRequired: boolean;
   inFlight: {
-    envelope: TerminalDeliveryEnvelope;
+    envelope: DeliveryEnvelope;
+    projection: ProjectionBaseline | null;
     deliveryOrdinal: number;
     bytes: Uint8Array;
     nextChunk: number;
@@ -226,7 +247,7 @@ interface ClientState {
   captureUnavailable: boolean;
   lastAck: TerminalDeliveryAck | null;
   /** Delivery displaced by authoritative source close; its racing ACK is benign. */
-  sourceClosedFlight: TerminalDeliveryEnvelope | null;
+  sourceClosedFlight: DeliveryEnvelope | null;
   backgroundTimer: SessionRuntimeTimer | null;
 }
 
@@ -246,6 +267,11 @@ interface PendingClientEncoding {
   readonly reseedRequired: boolean;
   readonly traceStarted: number;
 }
+class DeferredProjectionEncoding extends Error {
+  constructor(readonly payload: TerminalProjectionPayload) {
+    super("Deferred projection encoding");
+  }
+}
 class DeferredSeedEncoding extends Error {
   constructor(readonly payload: TerminalSemanticDeliveryPayload) {
     super("Deferred compact seed encoding");
@@ -254,10 +280,16 @@ class DeferredSeedEncoding extends Error {
 
 interface CachedRepresentation {
   readonly bytes: Uint8Array;
-  readonly encoding?: "semantic-v1" | "semantic-compact-v1";
+  readonly encoding?:
+    | "semantic-v1"
+    | "semantic-compact-v1"
+    | "semantic-binary-v1"
+    | "alternate-projection-binary-v1";
+  readonly projection?: ProjectionBaseline;
+  readonly projectionBaseRevision?: number | null;
   readonly frame: "seed" | "patch" | "tombstone";
   readonly canonicalEquivalent: boolean;
-  readonly history: "complete" | "truncated" | "not-applicable";
+  readonly history: "complete" | "truncated" | "not-applicable" | "deferred";
   readonly representationHash?: string;
   /** Internal reachability metadata; never serialized onto the wire. */
   readonly cachePaneId?: string;
@@ -274,7 +306,7 @@ interface CachedRepresentation {
     attemptedLegacySeedSizeCapped: boolean;
     attemptedCompactPatchBytes: number | null;
     attemptedCompactSeedBytes: number | null;
-    selectedEncoding: "semantic-v1" | "semantic-compact-v1";
+    selectedEncoding: "semantic-v1" | "semantic-compact-v1" | "semantic-binary-v1";
     selectionStatus:
       | "patch-preferred"
       | "seed-preferred"
@@ -432,6 +464,10 @@ export class SessionRuntimeTerminalDeliveryHub {
         visibility: "visible",
         baselineRevision: -1,
         baselineHash: null,
+        projectionBaseline: null,
+        materializeRequested: false,
+        lastProjectionReceipt: null,
+        lastMaterialize: null,
         reseedRequired: false,
         inFlight: null,
         latestRevision: pane.latest?.update.revision ?? null,
@@ -456,6 +492,8 @@ export class SessionRuntimeTerminalDeliveryHub {
         negotiation,
         closed,
         ack: (ack) => this.#ack(client, ack),
+        projectionReceipt: (receipt) => this.#projectionReceipt(client, receipt),
+        materialize: (request) => this.#materialize(client, request),
         nack: (nack) => this.#nack(client, nack),
         setVisibility: (visibilityInput) => {
           if (client.closed) return;
@@ -956,7 +994,10 @@ export class SessionRuntimeTerminalDeliveryHub {
         client.lifecycleOpenRecorded = this.#recordDeliveryLifecycle(client, pane, "open");
       if (
         update.type === "terminal.tombstone" &&
-        (client.inFlight !== null || client.encoding !== null || client.visibility !== "visible")
+        (client.inFlight !== null ||
+          client.encoding !== null ||
+          client.visibility !== "visible" ||
+          client.projectionBaseline !== null)
       ) {
         this.#fault(client, "source-closed", "Terminal source closed before final state delivery");
         continue;
@@ -1079,15 +1120,22 @@ export class SessionRuntimeTerminalDeliveryHub {
     let deferred = false;
     let encodedRepresentation: CachedRepresentation | null = null;
     let failedSelectionObservation: SemanticSelectionObservation | null = null;
-    let deliveryEnvelope: TerminalDeliveryEnvelope | null = null;
+    let deliveryEnvelope: DeliveryEnvelope | null = null;
     let deliveryOrdinal: number | null = null;
     try {
       const representation = this.#representation(client, pane, target, completed?.outcome);
       encodedRepresentation = representation;
       const transactionId = this.#scheduler.createId();
       const chunkCount = Math.max(1, Math.ceil(representation.bytes.byteLength / (256 * 1024)));
-      const envelope = TerminalDeliveryEnvelopeSchemaZ.parse({
-        type: "terminal.delivery",
+      const envelope = (
+        representation.projection
+          ? TerminalProjectionEnvelopeSchemaZ
+          : TerminalDeliveryEnvelopeSchemaZ
+      ).parse({
+        type: representation.projection ? "terminal.projection" : "terminal.delivery",
+        ...(representation.projection
+          ? { projectionStateHash: representation.projection.hash }
+          : {}),
         workspaceName: client.deliveryWorkspaceName,
         semanticPaneId: target.update.semanticPaneId,
         generation: target.update.generation,
@@ -1098,7 +1146,11 @@ export class SessionRuntimeTerminalDeliveryHub {
         protocolVersion: 1,
         encoding: representation.encoding ?? client.negotiated.encoding,
         frame: representation.frame,
-        baseRevision: representation.frame === "seed" ? null : Math.max(0, client.baselineRevision),
+        baseRevision: representation.projection
+          ? representation.projectionBaseRevision
+          : representation.frame === "seed"
+            ? null
+            : Math.max(0, client.baselineRevision),
         canonicalRevision: target.update.revision,
         canonicalStateHash: target.update.stateHash,
         representationHash:
@@ -1115,6 +1167,7 @@ export class SessionRuntimeTerminalDeliveryHub {
       registerTerminalDeliveryObservationOrdinal(envelope, deliveryOrdinal);
       client.inFlight = {
         envelope,
+        projection: representation.projection ?? null,
         deliveryOrdinal,
         bytes: representation.bytes,
         nextChunk: 0,
@@ -1125,9 +1178,16 @@ export class SessionRuntimeTerminalDeliveryHub {
       if (target.trace?.traceId === pane.pendingDeliveryTrace?.traceId)
         pane.pendingDeliveryTrace = null;
     } catch (error) {
-      if (error instanceof DeferredSeedEncoding) {
+      if (error instanceof DeferredSeedEncoding || error instanceof DeferredProjectionEncoding) {
         deferred = true;
-        this.#startEncoding(client, pane, target, error.payload, traceStarted);
+        this.#startEncoding(
+          client,
+          pane,
+          target,
+          error.payload,
+          traceStarted,
+          error instanceof DeferredProjectionEncoding,
+        );
         return;
       }
       failedSelectionObservation = semanticSelectionObservationFromError(error);
@@ -1205,8 +1265,9 @@ export class SessionRuntimeTerminalDeliveryHub {
     client: ClientState,
     pane: PaneState,
     target: RevisionRecord,
-    payload: TerminalSemanticDeliveryPayload,
+    payload: TerminalSemanticDeliveryPayload | TerminalProjectionPayload,
     traceStarted: number,
+    projection = false,
   ): void {
     const key = cacheKey([
       target.update.workspaceName,
@@ -1217,6 +1278,9 @@ export class SessionRuntimeTerminalDeliveryHub {
       target.update.stateHash,
       client.negotiated.encoding,
       client.negotiated.richPlacements ? "rich" : "plain",
+      projection
+        ? `projection:${client.projectionBaseline?.revision ?? -1}:${client.projectionBaseline?.hash ?? "none"}`
+        : "complete",
     ]);
     let job = this.#pendingEncodings.get(key);
     let created = false;
@@ -1250,10 +1314,19 @@ export class SessionRuntimeTerminalDeliveryHub {
     };
     owned.clients.add(client);
     if (!created) return;
-    void encodeCompactSemanticTerminalUpdateCooperatively(payload, {
-      signal: owned.abort.signal,
-      yieldControl: () => this.#yieldEncoding(owned),
-    }).then(
+    const options = { signal: owned.abort.signal, yieldControl: () => this.#yieldEncoding(owned) };
+    const result = projection
+      ? encodeTerminalProjectionCooperatively(payload as TerminalProjectionPayload, options)
+      : client.negotiated.encoding === "semantic-binary-v1"
+        ? encodeBinarySemanticTerminalUpdateCooperatively(
+            payload as TerminalSemanticDeliveryPayload,
+            options,
+          )
+        : encodeCompactSemanticTerminalUpdateCooperatively(
+            payload as TerminalSemanticDeliveryPayload,
+            options,
+          );
+    void result.then(
       (bytes) => this.#completeEncoding(owned, { bytes }),
       (error) => this.#completeEncoding(owned, { error }),
     );
@@ -1328,6 +1401,32 @@ export class SessionRuntimeTerminalDeliveryHub {
     target: RevisionRecord,
     seedOutcome?: SeedEncodingOutcome,
   ): CachedRepresentation {
+    const snapshotForProjection = target.state.snapshot;
+    if (
+      client.negotiated.alternateScreenProjection &&
+      !client.materializeRequested &&
+      (client.baselineRevision < 0 || client.projectionBaseline !== null) &&
+      snapshotForProjection?.modes.alternateScreen &&
+      snapshotForProjection.history.length > 0
+    ) {
+      const { payload, retained } = prepareProjection(
+        snapshotForProjection,
+        target.update.revision,
+        target.update.incarnation,
+        client.reseedRequired ? null : client.projectionBaseline,
+      );
+      if (!seedOutcome) throw new DeferredProjectionEncoding(payload);
+      if ("error" in seedOutcome) throw seedOutcome.error;
+      return {
+        bytes: seedOutcome.bytes,
+        encoding: "alternate-projection-binary-v1",
+        frame: payload.frame,
+        history: "deferred",
+        canonicalEquivalent: false,
+        projection: retained,
+        projectionBaseRevision: payload.frame === "seed" ? null : payload.baseRevision,
+      };
+    }
     const key = cacheKey([
       target.update.workspaceName,
       target.update.semanticPaneId,
@@ -1351,17 +1450,27 @@ export class SessionRuntimeTerminalDeliveryHub {
     let result: CachedRepresentation | null = null;
     if (
       client.negotiated.encoding === "semantic-v1" ||
-      client.negotiated.encoding === "semantic-compact-v1"
+      client.negotiated.encoding === "semantic-compact-v1" ||
+      client.negotiated.encoding === "semantic-binary-v1"
     ) {
       const encodeSemantic = (payload: TerminalSemanticDeliveryPayload): Uint8Array => {
-        if (client.negotiated.encoding !== "semantic-compact-v1")
+        if (
+          client.negotiated.encoding !== "semantic-compact-v1" &&
+          client.negotiated.encoding !== "semantic-binary-v1"
+        )
           return encodeSemanticTerminalUpdate(payload);
-        if (terminalSemanticUpdateNeedsCooperativeEncoding(payload)) {
+        if (
+          payload.frame === "seed" &&
+          (client.negotiated.encoding === "semantic-binary-v1" ||
+            terminalSemanticUpdateNeedsCooperativeEncoding(payload))
+        ) {
           if (!seedOutcome) throw new DeferredSeedEncoding(payload);
           if ("error" in seedOutcome) throw seedOutcome.error;
           return seedOutcome.bytes;
         }
-        return encodeCompactSemanticTerminalUpdate(payload);
+        return client.negotiated.encoding === "semantic-binary-v1"
+          ? encodeBinarySemanticTerminalUpdate(payload)
+          : encodeCompactSemanticTerminalUpdate(payload);
       };
       if (client.reseedRequired) {
         const payload = semanticSeed(target);
@@ -1693,6 +1802,10 @@ export class SessionRuntimeTerminalDeliveryHub {
       return;
     }
     const envelope = flight.envelope;
+    if (envelope.type !== "terminal.delivery") {
+      this.#fault(client, "protocol-violation", "Canonical ACK cannot acknowledge a projection");
+      return;
+    }
     if (
       flight.nextChunk !== envelope.chunkCount ||
       ack.workspaceName !== envelope.workspaceName ||
@@ -1712,6 +1825,8 @@ export class SessionRuntimeTerminalDeliveryHub {
       this.#maxSlowClientMs,
       this.#scheduler.nowMs() - flight.sentAt,
     );
+    client.projectionBaseline = null;
+    client.lastProjectionReceipt = null;
     client.baselineRevision = ack.canonicalRevision;
     client.baselineHash = ack.canonicalStateHash;
     client.reseedRequired = false;
@@ -1769,6 +1884,85 @@ export class SessionRuntimeTerminalDeliveryHub {
     this.#recordDeliveryStatus(client, this.#panes.get(client.paneId));
   }
 
+  #projectionReceipt(client: ClientState, input: TerminalProjectionReceipt): void {
+    const receipt = TerminalProjectionReceiptSchemaZ.parse(input);
+    if (
+      client.lastProjectionReceipt &&
+      JSON.stringify(client.lastProjectionReceipt) === JSON.stringify(receipt)
+    )
+      return;
+    const flight = client.inFlight;
+    const envelope = flight?.envelope;
+    if (
+      !flight ||
+      !flight.projection ||
+      envelope?.type !== "terminal.projection" ||
+      flight.nextChunk !== envelope.chunkCount ||
+      receipt.workspaceName !== envelope.workspaceName ||
+      receipt.semanticPaneId !== envelope.semanticPaneId ||
+      receipt.generation !== envelope.generation ||
+      receipt.incarnation !== envelope.incarnation ||
+      receipt.deliveryNonce !== envelope.deliveryNonce ||
+      receipt.transactionId !== envelope.transactionId ||
+      receipt.canonicalRevision !== envelope.canonicalRevision ||
+      receipt.canonicalStateHash !== envelope.canonicalStateHash ||
+      receipt.projectionStateHash !== envelope.projectionStateHash ||
+      receipt.representationHash !== envelope.representationHash
+    ) {
+      this.#fault(
+        client,
+        "protocol-violation",
+        "Projection receipt does not identify the in-flight projection",
+      );
+      return;
+    }
+    client.projectionBaseline = flight.projection;
+    client.lastProjectionReceipt = receipt;
+    client.reseedRequired = false;
+    client.inFlight = null;
+    if (client.latestRevision === receipt.canonicalRevision) client.latestRevision = null;
+    if (client.materializeRequested)
+      client.latestRevision = this.#panes.get(client.paneId)?.latest?.update.revision ?? null;
+    this.#pruneCanonicalRevisions(client.paneId);
+    this.#schedule(client);
+    this.#recordDeliveryStatus(client, this.#panes.get(client.paneId));
+  }
+
+  #materialize(client: ClientState, input: TerminalProjectionMaterialize): void {
+    const request = TerminalProjectionMaterializeSchemaZ.parse(input);
+    if (
+      client.lastMaterialize &&
+      JSON.stringify(client.lastMaterialize) === JSON.stringify(request)
+    )
+      return;
+    const baseline = client.projectionBaseline;
+    if (
+      !client.negotiated.alternateScreenProjection ||
+      !baseline ||
+      request.workspaceName !== client.deliveryWorkspaceName ||
+      request.semanticPaneId !== client.paneId ||
+      request.generation !== client.negotiated.generation ||
+      request.incarnation !== baseline.incarnation ||
+      request.deliveryNonce !== client.negotiated.deliveryNonce ||
+      request.canonicalRevision !== baseline.revision ||
+      request.projectionStateHash !== baseline.hash
+    ) {
+      this.#fault(
+        client,
+        "protocol-violation",
+        "History request does not identify the retained projection",
+      );
+      return;
+    }
+    client.lastMaterialize = request;
+    client.materializeRequested = true;
+    this.#cancelEncoding(client);
+    client.latestRevision = this.#panes.get(client.paneId)?.latest?.update.revision ?? null;
+    // A queued projection still owns its transaction until its receipt arrives.
+    // The following complete seed then supersedes it, including at the same revision.
+    this.#schedule(client);
+  }
+
   #nack(client: ClientState, input: TerminalDeliveryNack): void {
     const nack = TerminalDeliveryNackSchemaZ.parse(input);
     const closed = client.sourceClosedFlight;
@@ -2224,7 +2418,7 @@ export function selectExactSemanticRepresentation<T extends { readonly frame: st
 
 function completeSemanticSelectionObservation(
   observation: ExactSemanticSelectionObservation,
-  selectedEncoding: "semantic-v1" | "semantic-compact-v1",
+  selectedEncoding: "semantic-v1" | "semantic-compact-v1" | "semantic-binary-v1",
   legacyAttempts: Readonly<{ patchBytes: number | null; seedBytes: number | null }> | null,
 ): SemanticSelectionObservation {
   const compact = selectedEncoding === "semantic-compact-v1";

package/packages/daemon/src/terminal/session-runtime/terminal-delivery-observation-identity.ts

@@ -1,9 +1,12 @@
-import type { TerminalDeliveryEnvelope } from "@tmux-ide/contracts";
+import type { TerminalDeliveryEnvelope, TerminalProjectionEnvelope } from "@tmux-ide/contracts";
 
-const deliveryOrdinals = new WeakMap<TerminalDeliveryEnvelope, number>();
+const deliveryOrdinals = new WeakMap<
+  TerminalDeliveryEnvelope | TerminalProjectionEnvelope,
+  number
+>();
 
 export function registerTerminalDeliveryObservationOrdinal(
-  envelope: TerminalDeliveryEnvelope,
+  envelope: TerminalDeliveryEnvelope | TerminalProjectionEnvelope,
   ordinal: number,
 ): void {
   if (!Number.isSafeInteger(ordinal) || ordinal < 1)
@@ -12,7 +15,7 @@ export function registerTerminalDeliveryObservationOrdinal(
 }
 
 export function terminalDeliveryObservationOrdinal(
-  envelope: TerminalDeliveryEnvelope,
+  envelope: TerminalDeliveryEnvelope | TerminalProjectionEnvelope,
 ): number | null {
   return deliveryOrdinals.get(envelope) ?? null;
 }

package/packages/daemon/src/terminal/session-runtime/terminal-projection-delivery.ts

@@ -0,0 +1,59 @@
+import type {
+  TerminalProjectionPayload,
+  TerminalProjectionSnapshot,
+  TerminalReplicaSnapshot,
+} from "@tmux-ide/contracts";
+import {
+  hashTerminalProjection,
+  projectAlternateSnapshot,
+  terminalReplicaRowsEqual,
+} from "@tmux-ide/core";
+
+/** A projection receipt never becomes a complete canonical baseline. */
+export interface ProjectionBaseline {
+  readonly revision: number;
+  readonly incarnation: string;
+  readonly hash: string;
+  readonly snapshot: TerminalProjectionSnapshot;
+}
+
+export function prepareProjection(
+  snapshot: TerminalReplicaSnapshot,
+  revision: number,
+  incarnation: string,
+  baseline: ProjectionBaseline | null,
+): { payload: TerminalProjectionPayload; retained: ProjectionBaseline } {
+  const projected = projectAlternateSnapshot(snapshot);
+  const retained = {
+    revision,
+    incarnation,
+    hash: hashTerminalProjection(projected),
+    snapshot: projected,
+  };
+  if (
+    !baseline ||
+    baseline.incarnation !== incarnation ||
+    baseline.snapshot.cols !== projected.cols ||
+    baseline.snapshot.rows !== projected.rows
+  )
+    return { payload: { frame: "seed", revision, projection: projected }, retained };
+  const rows = projected.grid.flatMap((row, index) =>
+    terminalReplicaRowsEqual(row, baseline.snapshot.grid[index]!) ? [] : [{ index, row }],
+  );
+  return {
+    retained,
+    payload: {
+      frame: "patch",
+      baseRevision: baseline.revision,
+      revision,
+      patch: {
+        rows,
+        deferredHistory: projected.deferredHistory,
+        cursor: projected.cursor,
+        modes: projected.modes,
+        placements: projected.placements,
+        bootstrap: projected.bootstrap,
+      },
+    },
+  };
+}

package/packages/daemon/src/terminal/session-runtime/terminal-replica-owner.ts

@@ -259,11 +259,10 @@ export class SessionRuntimeTerminalReplicaOwner {
     return this.#disposed ? null : this.#publishedIncarnation;
   }
 
-  /** Scalar admission fence; unavailable while canonical replacement is pending. */
+  /** Screen recapture does not replace the terminal lifetime. Keep its input fence
+   * while resizing; disposal or a new owner still invalidates held input. */
   inputAdmissionIncarnation(): string | null {
-    return this.#disposed || this.#reseed || this.#waitingForGeometryCapture
-      ? null
-      : this.#publishedIncarnation;
+    return this.#disposed ? null : this.#publishedIncarnation;
   }
 
   qualificationSnapshot(): TerminalReplicaQualificationSnapshot {

package/packages/daemon/src/tui/mirror/open-tui-workspace-runtime-port.ts

@@ -532,6 +532,10 @@ class WireTerminalEndpoint {
       return;
     }
     if (this.#unavailable) return;
+    if (message.type === "terminal.projection") {
+      this.#failConnection(new Error("Unsolicited alternate-screen projection"));
+      return;
+    }
     if (message.type === "terminal.delivery") {
       this.#acceptEnvelope(message);
       return;

package/packages/daemon/src/tui/mirror/runtime/application-terminal-interaction-controller.ts

@@ -1,3 +1,4 @@
+import { rendererProbe } from "./renderer-probe.ts";
 import { createTerminalSelectionWaiter } from "./terminal-selection-waiter.ts";
 import { WorkspaceWindowLinkSelectResultSchemaZ } from "@tmux-ide/contracts";
 import { windowLinkForPane, windowLinkTarget } from "./application-terminal-workspace-policy.ts";
@@ -1050,11 +1051,15 @@ export function createApplicationTerminalInteractionController(
       }
       return outcome.status === "sent";
     },
-    onFocusedPane: options.setFocusedPane,
+    onFocusedPane: (pane) => {
+      rendererProbe()?.cancel("selection-changed", nowMicros());
+      options.setFocusedPane(pane);
+    },
   });
 
   return {
     cancelPendingInput() {
+      rendererProbe()?.cancel("input-cancelled", nowMicros());
       selectionWaiter.cancel();
       finishLinkSelection(false);
       paneInput.invalidateSelection();
@@ -1064,6 +1069,7 @@ export function createApplicationTerminalInteractionController(
       selectionGeneration = snapshot;
       const control = controlIdentity(snapshot);
       if (!sameControl(selectedControl, control)) {
+        rendererProbe()?.cancel("control-changed", nowMicros());
         finishLinkSelection(false);
         paneInput.invalidateSelection();
       }
@@ -1118,6 +1124,7 @@ export function createApplicationTerminalInteractionController(
           next.fastLane !== inputAuthorityIdentity.fastLane ||
           next.adapter !== inputAuthorityIdentity.adapter);
       if (next === null || replaced) {
+        rendererProbe()?.cancel("generation-changed", nowMicros());
         finishLinkSelection(false);
         pendingWindowSwitch = null;
         pendingWindowRename = null;
@@ -1364,10 +1371,25 @@ export function createApplicationTerminalInteractionController(
       }
     },
     sendInput: async (input, parserOrigin) => {
-      await paneInput.sendInput({ input, parserOrigin });
+      const probe = rendererProbe();
+      const state = probe
+        ? (options.generation()?.fastLane?.lane.paneState(paneInput.focusedPane ?? "") ?? null)
+        : null;
+      const measured = probe?.admit(input, state, nowMicros());
+      const sent = await paneInput.sendInput({ input: measured ?? input, parserOrigin });
+      if (measured && !sent) probe?.cancel("dispatch-rejected", nowMicros());
+    },
+    sendInputToPane: async (paneId, input, parserOrigin) => {
+      const probe = rendererProbe();
+      const state = probe ? (options.generation()?.fastLane?.lane.paneState(paneId) ?? null) : null;
+      const measured = probe?.admit(input, state, nowMicros());
+      const sent = await paneInput.sendInputToPane(paneId, {
+        input: measured ?? input,
+        parserOrigin,
+      });
+      if (measured && !sent) probe?.cancel("dispatch-rejected", nowMicros());
+      return sent;
     },
-    sendInputToPane: (paneId, input, parserOrigin) =>
-      paneInput.sendInputToPane(paneId, { input, parserOrigin }),
     beginResizePointerIngress(input) {
       if (!options.diagnosticsEnabled) return null;
       const atMicros = diagnosticNowMicros();