tmux-ide 2.9.12 → 2.9.13

package/packages/daemon/dist/terminal/pane-stream/pane-stream-websocket.js

@@ -1,4 +1,7 @@
-import { TERMINAL_PROJECTION_CAPABILITY_VERSION, TERMINAL_PROJECTION_LOCAL_CAPABILITY_VERSION, } from "@tmux-ide/contracts";
+import { TERMINAL_SURFACE_MAX_CONTROL_BYTES, TERMINAL_SURFACE_CAPABILITY_VERSION, } from "@tmux-ide/contracts";
+import { NativeSurfaceViewer } from "../graphics/native-surface-viewer.js";
+import { compressGraphicsChunk } from "../graphics/compress-chunk.js";
+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 { PANE_STREAM_INPUT_LIFETIME_CAPABILITY_VERSION, PANE_STREAM_INPUT_BYTES_CAPABILITY_VERSION, } from "@tmux-ide/contracts";
 import { inflateSync } from "node:zlib";
 import { PaneStreamLayoutSnapshotFrameSchemaZ } from "@tmux-ide/contracts";
@@ -116,6 +119,7 @@ function errorFrameCode(error) {
  * ticket digests; a daemon restart makes every prior descriptor inert.
  */
 export class PaneStreamAdmissionCoordinator {
+    #nativeSurfaces;
     #localImages;
     #instanceId;
     #webSocketUrl;
@@ -147,6 +151,9 @@ export class PaneStreamAdmissionCoordinator {
     #shuttingDown = false;
     #shutdownPromise = null;
     constructor(options) {
+        this.#nativeSurfaces = options.nativeSurfaces;
+        if (this.#nativeSurfaces && this.#nativeSurfaces.generation !== options.daemonInstanceId)
+            throw new Error("Native surface provider generation mismatch");
         this.#localImages = options.localImages;
         this.#instanceId = BindingIdSchemaZ.parse(options.daemonInstanceId);
         this.#webSocketUrl = PaneStreamLoopbackWebSocketUrlSchemaZ.parse(options.webSocketUrl);
@@ -410,6 +417,7 @@ export class PaneStreamAdmissionCoordinator {
                 let live;
                 try {
                     live = new PaneStreamLiveConnection({
+                        nativeSurfaces: this.#nativeSurfaces,
                         localImages: this.#localImages,
                         clientId: `psc-${this.#clientCounter}`,
                         socket,
@@ -618,6 +626,13 @@ export function rawGraphicsState(state) {
 }
 const GRAPHICS_SEND_WINDOW_BYTES = 2 * 1024 * 1024;
 export class PaneStreamLiveConnection {
+    // One bounded native negotiation per redeemed socket; never reuse on reconnect.
+    #nativeSurfaces;
+    #surfaceViewer = null;
+    #surfaceDemands = new Map();
+    #surfaceNative = false;
+    #surfaceSession = null;
+    #surfaceReceiver = null;
     #localImages;
     #localLeases = new Map();
     #clientId;
@@ -707,6 +722,7 @@ export class PaneStreamLiveConnection {
         return elapsed;
     }
     constructor(options) {
+        this.#nativeSurfaces = options.nativeSurfaces;
         this.#localImages = options.localImages;
         this.#clientId = options.clientId;
         this.#socket = options.socket;
@@ -801,6 +817,8 @@ export class PaneStreamLiveConnection {
         }
         this.#stopAuthoritySnapshots =
             this.#sessionRuntimeBinding?.onAuthoritySnapshot?.((snapshot) => this.#usesExplicitAuthority ? this.#sendAuthoritySnapshot(snapshot) : undefined) ?? null;
+        if (!this.#descriptor.terminalDelivery)
+            this.#observeSurfaceDemand(this.#descriptor.panes);
         void this.#subscribeAll();
     }
     close(code = 1000, reason = "stream-closed") {
@@ -808,6 +826,13 @@ export class PaneStreamLiveConnection {
             return;
         this.#recordDiagnosticLifecycle("pane-stream-terminal", code, reason);
         this.#closed = true;
+        for (const demand of this.#surfaceDemands.values())
+            demand.close();
+        this.#surfaceDemands.clear();
+        this.#surfaceViewer?.close();
+        this.#surfaceViewer = null;
+        this.#surfaceSession?.close();
+        this.#surfaceSession = null;
         this.#cancelDrainTick?.();
         this.#cancelDrainTick = null;
         // Departure force-returns every ticket within this same tick.
@@ -839,6 +864,8 @@ export class PaneStreamLiveConnection {
             const delivery = channel.delivery;
             channel.delivery = null;
             channel.closed = true;
+            this.#surfaceDemands.get(channel.semanticPaneId)?.close();
+            this.#surfaceDemands.delete(channel.semanticPaneId);
             if (sub)
                 closures.push(sub.close().catch(() => undefined));
             if (delivery)
@@ -1264,11 +1291,30 @@ export class PaneStreamLiveConnection {
         }
         await this.#awaitSemanticCredit(pane);
     }
+    #observeSurfaceDemand(panes) {
+        for (const pane of panes) {
+            if (this.#surfaceDemands.has(pane))
+                continue;
+            const demand = this.#nativeSurfaces?.demand.viewer(this.#descriptor.sessionName, [pane]);
+            if (!demand)
+                return;
+            demand.native(this.#surfaceNative);
+            this.#surfaceDemands.set(pane, demand);
+        }
+    }
+    #surfaceControl(type) {
+        if (type === "terminal-surface-offer")
+            return;
+        this.#surfaceNative = type === "terminal-surface-peer";
+        for (const demand of this.#surfaceDemands.values())
+            demand.native(this.#surfaceNative);
+    }
     /** Announce the pane's kitty graphics state; the client pulls bytes it lacks. */
     #startGraphics(channel) {
         const graphics = channel.delivery?.graphics;
         if (!graphics)
             return;
+        this.#observeSurfaceDemand([channel.semanticPaneId]);
         // Renderers that cannot inflate see raw formats; their bytes are inflated
         // when served.
         const zlib = this.#descriptor.terminalDelivery?.protocolVersions.includes(TERMINAL_GRAPHICS_ZLIB_CAPABILITY_VERSION) === true;
@@ -1277,7 +1323,11 @@ export class PaneStreamLiveConnection {
             !!this.#localImages &&
                 this.#descriptor.terminalDelivery?.protocolVersions.some((version) => version === TERMINAL_GRAPHICS_LOCAL_CAPABILITY_VERSION ||
                     version === TERMINAL_DELIVERY_BINARY_LOCAL_CAPABILITY_VERSION ||
-                    version === TERMINAL_PROJECTION_LOCAL_CAPABILITY_VERSION) === true;
+                    version === TERMINAL_PROJECTION_LOCAL_CAPABILITY_VERSION ||
+                    version === TERMINAL_GRAPHICS_COMPRESSED_LOCAL_CAPABILITY_VERSION) === true;
+        channel.graphicsCompressed =
+            this.#descriptor.terminalDelivery?.protocolVersions.some((version) => version === TERMINAL_GRAPHICS_COMPRESSED_CAPABILITY_VERSION ||
+                version === TERMINAL_GRAPHICS_COMPRESSED_LOCAL_CAPABILITY_VERSION) === true;
         channel.graphicsInline = new Set();
         channel.graphicsBinary =
             this.#descriptor.terminalDelivery?.protocolVersions.some((version) => version === TERMINAL_GRAPHICS_BINARY_CAPABILITY_VERSION ||
@@ -1285,7 +1335,9 @@ export class PaneStreamLiveConnection {
                 version === TERMINAL_DELIVERY_BINARY_CAPABILITY_VERSION ||
                 version === TERMINAL_PROJECTION_CAPABILITY_VERSION ||
                 version === TERMINAL_DELIVERY_BINARY_LOCAL_CAPABILITY_VERSION ||
-                version === TERMINAL_PROJECTION_LOCAL_CAPABILITY_VERSION) === true;
+                version === TERMINAL_PROJECTION_LOCAL_CAPABILITY_VERSION ||
+                version === TERMINAL_GRAPHICS_COMPRESSED_CAPABILITY_VERSION ||
+                version === TERMINAL_GRAPHICS_COMPRESSED_LOCAL_CAPABILITY_VERSION) === true;
         // Renderers that report cell pixels learn up front that this daemon
         // accepts them, before any image exists.
         const cellPixels = this.#descriptor.terminalDelivery?.protocolVersions.includes(TERMINAL_GRAPHICS_CELL_PIXELS_CAPABILITY_VERSION) === true;
@@ -1314,6 +1366,7 @@ export class PaneStreamLiveConnection {
                     ...(cellPixels ? { cellPixels: true } : {}),
                     ...(preciseCellPixels ? { preciseCellPixels: true } : {}),
                     ...(channel.graphicsBinary ? { binaryBlobs: true } : {}),
+                    ...(channel.graphicsCompressed ? { compressedBlobs: true } : {}),
                     ...(channel.graphicsLocal ? { localFiles: true } : {}),
                 },
             });
@@ -1332,6 +1385,7 @@ export class PaneStreamLiveConnection {
                     cellPixels: true,
                     ...(preciseCellPixels ? { preciseCellPixels: true } : {}),
                     ...(channel.graphicsBinary ? { binaryBlobs: true } : {}),
+                    ...(channel.graphicsCompressed ? { compressedBlobs: true } : {}),
                     ...(channel.graphicsLocal ? { localFiles: true } : {}),
                 },
             });
@@ -1452,6 +1506,29 @@ export class PaneStreamLiveConnection {
                         break;
                     const end = Math.min(total, offset + TERMINAL_GRAPHICS_BLOB_CHUNK_BYTES);
                     if (channel.graphicsBinary) {
+                        const header = {
+                            pane: channel.semanticPaneId,
+                            blob: {
+                                digest,
+                                format,
+                                width: image.width,
+                                height: image.height,
+                                total,
+                                offset,
+                            },
+                        };
+                        const compressed = channel.graphicsCompressed
+                            ? await compressGraphicsChunk(header, data.subarray(offset, end))
+                            : null;
+                        // Compression yields: a pane may close or replace this image meanwhile.
+                        if (this.#closed || channel.closed)
+                            return;
+                        if (graphics.image(digest) !== image)
+                            break;
+                        if (compressed) {
+                            this.#sendEncoded(null, Buffer.from(compressed), true);
+                            continue;
+                        }
                         this.#sendEncoded(null, Buffer.from(encodeTerminalGraphicsBinary({
                             pane: channel.semanticPaneId,
                             blob: {
@@ -1621,6 +1698,8 @@ export class PaneStreamLiveConnection {
         if (channel.closed)
             return;
         channel.closed = true;
+        this.#surfaceDemands.get(channel.semanticPaneId)?.close();
+        this.#surfaceDemands.delete(channel.semanticPaneId);
         const sub = channel.sub;
         channel.sub = null;
         if (sub)
@@ -2081,6 +2160,120 @@ export class PaneStreamLiveConnection {
             this.#acceptSemanticIntent(frame.operationId, frame.intent);
             return;
         }
+        if (frame.type === "terminal-surface-watch") {
+            if (byteLength > TERMINAL_SURFACE_MAX_CONTROL_BYTES ||
+                frame.generation !== this.#sessionRuntimeBinding?.generation ||
+                !this.#descriptor.terminalDelivery?.protocolVersions.includes(TERMINAL_SURFACE_CAPABILITY_VERSION) ||
+                !this.#nativeSurfaces ||
+                this.#surfaceReceiver)
+                return this.#failProtocol("protocol-error");
+            if (this.#surfaceViewer)
+                return;
+            this.#surfaceViewer = new NativeSurfaceViewer(this.#nativeSurfaces, this.#descriptor.panes, (control) => {
+                if (this.#closed)
+                    return false;
+                this.#surfaceControl(control.type);
+                this.#sendFrame(null, control);
+                return !this.#closed;
+            }, (pane, generation) => {
+                const channel = this.#panes.get(pane);
+                const address = channel?.deliveryAddress;
+                return !this.#closed &&
+                    channel &&
+                    !channel.closed &&
+                    channel.delivery &&
+                    address?.generation === generation
+                    ? address.deliveryNonce
+                    : null;
+            });
+            this.#surfaceViewer.start();
+            return;
+        }
+        if (frame.type === "terminal-surface-receiver") {
+            if (this.#surfaceViewer) {
+                if (byteLength > TERMINAL_SURFACE_MAX_CONTROL_BYTES || !this.#surfaceViewer.receive(frame))
+                    this.#failProtocol("protocol-error");
+                return;
+            }
+            if (byteLength > TERMINAL_SURFACE_MAX_CONTROL_BYTES ||
+                !this.#descriptor.terminalDelivery ||
+                frame.generation !== this.#sessionRuntimeBinding?.generation) {
+                return this.#failProtocol("protocol-error");
+            }
+            if (this.#surfaceReceiver) {
+                // Parsed schema order is deterministic. A duplicate cannot change the
+                // challenge, kernel identity or endpoint, nor amplify fallback replies.
+                if (JSON.stringify(frame) !== JSON.stringify(this.#surfaceReceiver)) {
+                    return this.#failProtocol("protocol-error");
+                }
+                return;
+            }
+            this.#surfaceReceiver = frame;
+            if (this.#descriptor.terminalDelivery.protocolVersions.includes(TERMINAL_SURFACE_CAPABILITY_VERSION)) {
+                const native = this.#nativeSurfaces?.open(frame, this.#descriptor.panes, (control) => {
+                    if (this.#closed)
+                        return false;
+                    this.#surfaceControl(control.type);
+                    this.#sendFrame(null, control);
+                    return !this.#closed;
+                }, (pane, generation) => {
+                    const channel = this.#panes.get(pane);
+                    const address = channel?.deliveryAddress;
+                    if (this.#closed ||
+                        !channel ||
+                        channel.closed ||
+                        !channel.delivery ||
+                        !address ||
+                        address.generation !== generation)
+                        return null;
+                    return address.deliveryNonce;
+                }) ?? null;
+                if (this.#closed) {
+                    native?.close();
+                    return;
+                }
+                this.#surfaceSession = native;
+                if (native)
+                    return;
+            }
+            // No provider/capability means no PID/slot lookup and no inferred locality.
+            this.#sendFrame(null, {
+                type: "terminal-surface-fallback",
+                version: 1,
+                generation: frame.generation,
+                connectionNonce: frame.connectionNonce,
+                reason: "unsupported",
+            });
+            return;
+        }
+        if (frame.type === "terminal-surface-fallback") {
+            if (this.#surfaceViewer) {
+                if (byteLength > TERMINAL_SURFACE_MAX_CONTROL_BYTES || !this.#surfaceViewer.fallback(frame))
+                    this.#failProtocol("protocol-error");
+                return;
+            }
+            if (byteLength > TERMINAL_SURFACE_MAX_CONTROL_BYTES ||
+                frame.generation !== this.#surfaceReceiver?.generation ||
+                frame.connectionNonce !== this.#surfaceReceiver.connectionNonce) {
+                return this.#failProtocol("protocol-error");
+            }
+            this.#surfaceSession?.fallback(frame.reason);
+            return;
+        }
+        if (frame.type === "terminal-surface-retired") {
+            if (this.#surfaceViewer) {
+                if (byteLength > TERMINAL_SURFACE_MAX_CONTROL_BYTES || !this.#surfaceViewer.retire(frame))
+                    this.#failProtocol("protocol-error");
+                return;
+            }
+            if (byteLength <= TERMINAL_SURFACE_MAX_CONTROL_BYTES &&
+                frame.generation === this.#surfaceReceiver?.generation &&
+                frame.connectionNonce === this.#surfaceReceiver.connectionNonce &&
+                this.#surfaceSession?.retire(frame.sequence))
+                return;
+            // Unissued/replayed ACKs must not retire another socket's native storage.
+            return this.#failProtocol("protocol-error");
+        }
         if (frame.type === "terminal-graphics-request") {
             this.#requestGraphics(frame.pane, frame.digests, frame.preferInline === true);
             return;

package/packages/daemon/dist/terminal/pane-stream/runtime.js

@@ -1,3 +1,4 @@
+import { NativeSurfaceProviderRegistry } from "../graphics/native-surface-provider.js";
 import { SessionRuntimeTransportBinder } from "../session-runtime/transport-binding.js";
 import { PaneStreamLeaseManager } from "./lease-manager.js";
 import { PaneStreamAdmissionCoordinator, } from "./pane-stream-websocket.js";
@@ -8,8 +9,14 @@ import { PaneStreamAdmissionCoordinator, } from "./pane-stream-websocket.js";
  */
 export class PaneStreamRuntime {
     coordinator;
+    nativeSurfaces;
     #disposePromise = null;
     constructor(options) {
+        this.nativeSurfaces =
+            options.nativeSurfaces ??
+                (process.platform === "darwin"
+                    ? new NativeSurfaceProviderRegistry(options.daemonInstanceId)
+                    : undefined);
         const leaseManager = new PaneStreamLeaseManager({
             daemonInstanceId: options.daemonInstanceId,
         });
@@ -17,6 +24,7 @@ export class PaneStreamRuntime {
         this.coordinator = new PaneStreamAdmissionCoordinator({
             ...options.admission,
             localImages: options.localImages,
+            nativeSurfaces: this.nativeSurfaces,
             daemonInstanceId: options.daemonInstanceId,
             webSocketUrl: options.webSocketUrl,
             leaseManager,
@@ -43,6 +51,7 @@ export class PaneStreamRuntime {
     dispose() {
         if (!this.#disposePromise) {
             this.#disposePromise = (async () => {
+                this.nativeSurfaces?.close();
                 await this.coordinator.shutdown();
             })();
         }

package/packages/daemon/src/command-center/resources/saved-machine-route.ts

@@ -1,3 +1,4 @@
+import { mountSavedMachineWatch } from "./saved-machine-watch.ts";
 import type { Hono } from "hono";
 import { bodyLimit } from "hono/body-limit";
 import { z } from "zod";
@@ -7,6 +8,7 @@ import {
   loadSavedMachines,
   mergeSavedMachines,
   updateSavedMachines,
+  watchSavedMachines,
 } from "../../lib/saved-machines.ts";
 import { ownerAuthorityGate } from "../owner-authority.ts";
 
@@ -26,8 +28,10 @@ export function mountSavedMachineRoute(
     read?: typeof loadSavedMachines;
     merge?: typeof mergeSavedMachines;
     update?: typeof updateSavedMachines;
+    watch?: typeof watchSavedMachines;
   },
 ) {
+  mountSavedMachineWatch(app, options);
   const authorize = ownerAuthorityGate(options.ownerToken, {
     whenOwnerless: "unavailable",
     unavailableMessage: "Machine registry unavailable",

package/packages/daemon/src/command-center/resources/saved-machine-watch.ts

@@ -0,0 +1,132 @@
+import { createHash } from "node:crypto";
+import type { Hono } from "hono";
+import { z } from "zod";
+import {
+  SavedMachineRegistrySchema,
+  type SavedMachineRegistry,
+  type DaemonInstanceIdentity,
+} from "@tmux-ide/contracts";
+import { loadSavedMachines, watchSavedMachines } from "../../lib/saved-machines.ts";
+import { ownerAuthorityGate } from "../owner-authority.ts";
+
+export const SAVED_MACHINE_WATCH_WAIT_MS = 20_000;
+const MAX_WATCHERS = 32;
+const Query = z.strictObject({
+  expectedInstanceId: z.uuid(),
+  after: z
+    .string()
+    .regex(/^[a-f0-9]{64}$/u)
+    .optional(),
+});
+type Snapshot = { revision: string; registry: SavedMachineRegistry };
+type Result =
+  | { status: 200; revision: string; registry: SavedMachineRegistry | null }
+  | { status: 408 | 503 };
+function snapshot(value: SavedMachineRegistry): Snapshot {
+  const registry = SavedMachineRegistrySchema.parse(value);
+  return {
+    registry,
+    revision: createHash("sha256").update(JSON.stringify(registry)).digest("hex"),
+  };
+}
+
+/** One bounded notification request. A new request always observes the latest registry. */
+export function mountSavedMachineWatch(
+  app: Hono,
+  options: {
+    daemon: DaemonInstanceIdentity;
+    ownerToken: string | null;
+    read?: typeof loadSavedMachines;
+    watch?: typeof watchSavedMachines;
+  },
+) {
+  const authorize = ownerAuthorityGate(options.ownerToken, {
+    whenOwnerless: "unavailable",
+    unavailableMessage: "Machine registry unavailable",
+    mismatchMessage: "Machine registry requires owner authority",
+  });
+  const read = options.read ?? loadSavedMachines;
+  const watch = options.watch ?? watchSavedMachines;
+  let active = 0;
+  app.get("/api/resources/saved-machines/watch", async (c) => {
+    const gate = authorize(c);
+    if (gate) return gate;
+    c.header("Cache-Control", "no-store");
+    const query = Query.safeParse(c.req.query());
+    if (!query.success) return c.json({ error: "Invalid registry watch request" }, 400);
+    if (query.data.expectedInstanceId !== options.daemon.instanceId)
+      return c.json({ error: "Daemon generation changed" }, 409);
+    if (active >= MAX_WATCHERS) return c.json({ error: "Registry watch capacity reached" }, 429);
+    active++;
+    try {
+      const initial = snapshot(read());
+      if (query.data.after !== initial.revision)
+        return c.json({ daemon: options.daemon, ...initial });
+      const signal = c.req.raw.signal;
+      const result = await new Promise<Result>((resolve) => {
+        let settled = false;
+        let stop = () => {};
+        const finish = (result: Result) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          signal.removeEventListener("abort", aborted);
+          try {
+            stop();
+          } finally {
+            resolve(result);
+          }
+        };
+        const aborted = () => finish({ status: 408 });
+        const timer = setTimeout(
+          () => finish({ status: 200, revision: initial.revision, registry: null }),
+          SAVED_MACHINE_WATCH_WAIT_MS,
+        );
+        timer.unref();
+        const changed = (value: SavedMachineRegistry) => {
+          if (settled) return;
+          try {
+            const next = snapshot(value);
+            if (next.revision !== initial.revision) finish({ status: 200, ...next });
+          } catch {
+            finish({ status: 503 });
+          }
+        };
+        signal.addEventListener("abort", aborted, { once: true });
+        if (signal.aborted) {
+          aborted();
+          return;
+        }
+        try {
+          stop = watch(changed, () => finish({ status: 503 }));
+          // Watch implementations may synchronously report an initial error/change.
+          if (settled) {
+            stop();
+            return;
+          }
+          // Close the read-before-subscribe race independently of watcher behavior.
+          changed(read());
+        } catch {
+          finish({ status: 503 });
+        }
+      });
+      if (result.status !== 200)
+        return c.json(
+          {
+            error:
+              result.status === 408 ? "Registry watch cancelled" : "Machine registry unavailable",
+          },
+          result.status,
+        );
+      return c.json({
+        daemon: options.daemon,
+        revision: result.revision,
+        registry: result.registry,
+      });
+    } catch {
+      return c.json({ error: "Machine registry unavailable" }, 503);
+    } finally {
+      active--;
+    }
+  });
+}

package/packages/daemon/src/command-center/server.ts

@@ -1,3 +1,4 @@
+import { TERMINAL_SURFACE_CAPABILITY_VERSION } from "@tmux-ide/contracts";
 import { mountAutomationRoutes } from "./automation.ts";
 import { mountTmuxServerRoutes } from "./tmux-servers.ts";
 import { streamBoundedLogs } from "./log-stream.ts";
@@ -197,6 +198,9 @@ export interface CreateAppOptions {
   /** Catalog + startup-barrier facts for the startup readiness ladder. */
   startupReadinessAttachmentBackend?: StartupReadinessAttachmentAuthority | null;
   paneStreamIssueBackend?: PaneStreamIssueBackend | null;
+  /** Current authenticated provider availability, never inferred from platform or PID. */
+  nativeSurfaceProviderAvailable?: () => boolean;
+  nativeSurfaceProviderSupported?: () => boolean;
   applicationShellInventoryBackend?: {
     discoverApplicationShellSession(
       requestedSessionName: string,
@@ -657,6 +661,20 @@ export function createApp(options: CreateAppOptions = {}): Hono {
         status: "ok" as const,
         daemon: daemonInstanceIdentity,
         capabilities: {
+          ...(c.req.query("nativeSurfaces") === "1"
+            ? {
+                nativeSurfaces: {
+                  supported:
+                    !!options.paneStreamIssueBackend &&
+                    options.nativeSurfaceProviderSupported?.() === true,
+                  available:
+                    options.paneStreamIssueBackend !== undefined &&
+                    options.paneStreamIssueBackend !== null &&
+                    options.nativeSurfaceProviderAvailable?.() === true,
+                  protocolVersion: TERMINAL_SURFACE_CAPABILITY_VERSION,
+                },
+              }
+            : {}),
           // Opt-in keeps the response compatible with older strict host schemas.
           ...(c.req.query("windowViewport") === "1"
             ? {

package/packages/daemon/src/command-center/tmux-servers.ts

@@ -1,3 +1,4 @@
+import { NativeSurfaceLocationSchema } from "../lib/native-surface-context.ts";
 import { mountTmuxServerHistoryAnchorRoute } from "./tmux-server-history-anchor.ts";
 import { mountTmuxServerDiagnosticsRoute } from "./tmux-server-diagnostics.ts";
 import { WindowSplitLayoutUnavailable } from "../terminal/mirror/window-split-authority.ts";
@@ -277,6 +278,19 @@ export function mountTmuxServerRoutes(app: Hono, options: TmuxServerRoutesOption
       );
     }),
   );
+  app.post(
+    `${scoped}/native-surface-context`,
+    route(async (c) => {
+      const server = scope(c);
+      const target = NativeSurfaceLocationSchema.parse(await boundedJson(c.req.raw, 8192));
+      c.req.raw.signal.throwIfAborted();
+      const context = await options.owners.withOwner(server, (owner) =>
+        owner.resolveNativeSurfaceContext(target, c.req.raw.signal),
+      );
+      c.req.raw.signal.throwIfAborted();
+      return c.json({ version: 1, server, context });
+    }),
+  );
   app.get(
     `${scoped}/inventory/:workspaceName`,
     route(async (c) => {

package/packages/daemon/src/lib/daemon-embed.ts

@@ -1,3 +1,5 @@
+import { createNativeSurfaceContextResolver } from "./native-surface-context.ts";
+import { NativeSurfaceProviderRegistry } from "../terminal/graphics/native-surface-provider.ts";
 import { TmuxServerVersionSchemaZ } from "@tmux-ide/contracts";
 import {
   createNativeSplitCapabilityProbe,
@@ -139,6 +141,7 @@ import {
   attachTerminalAttachmentWebSocket,
   type TerminalAttachmentWebSocketBoundary,
 } from "../server/terminal-attachment-upgrade.ts";
+import { attachNativeSurfaceProvider } from "../server/native-surface-provider-upgrade.ts";
 import {
   attachPaneStreamWebSocket,
   type PaneStreamWebSocketBoundary,
@@ -920,6 +923,10 @@ async function startHttpServer({
       issue: (request, context) => getTerminalAttachmentRuntime().admission.issue(request, context),
     },
     paneStreamIssueBackend: paneStreamRuntime.coordinator,
+    nativeSurfaceProviderSupported: () =>
+      serverOwners.isDefaultCurrent() && paneStreamRuntime.nativeSurfaces !== undefined,
+    nativeSurfaceProviderAvailable: () =>
+      serverOwners.isDefaultCurrent() && paneStreamRuntime.nativeSurfaces?.available === true,
     applicationShellInventoryBackend: terminalInventoryRuntime,
     startupReadinessAttachmentBackend: terminalInventoryRuntime,
     catalogLiveSessions,
@@ -970,12 +977,26 @@ async function startHttpServer({
       (create ? getTerminalAttachmentRuntime() : peekTerminalAttachmentRuntime())?.admission ??
       null,
   );
-  const paneStreamBoundary = attachPaneStreamWebSocket(
+  const paneStreamSocketBoundary = attachPaneStreamWebSocket(
     server,
     paneStreamRuntime.coordinator,
     PANE_STREAM_REDEEM_PATH,
     () => serverOwners.isDefaultCurrent(),
   );
+  const nativeProviderBoundary = paneStreamRuntime.nativeSurfaces
+    ? attachNativeSurfaceProvider(
+        server,
+        paneStreamRuntime.nativeSurfaces,
+        localBypassToken ?? null,
+        () => serverOwners.isDefaultCurrent(),
+      )
+    : null;
+  const paneStreamBoundary: PaneStreamWebSocketBoundary = {
+    async close() {
+      nativeProviderBoundary?.close();
+      await paneStreamSocketBoundary.close();
+    },
+  };
   serverOwners.attach(server);
 
   try {
@@ -1526,6 +1547,8 @@ async function startEmbeddedDaemonGeneration(
         externalInteractionObserver.setDiagnostics(diagnostics);
         setFleetFactsObserverDiagnostics(diagnostics);
       }
+      const nativeSurfaces =
+        process.platform === "darwin" ? new NativeSurfaceProviderRegistry(instanceId) : undefined;
       sessionRuntimeRegistry = new SessionRuntimeRegistry({
         generation: instanceId,
         ...(runtimeObservability ? { observability: runtimeObservability } : {}),
@@ -1561,6 +1584,8 @@ async function startEmbeddedDaemonGeneration(
           publishResourceChange: (change) => broadcastResourceChanged(change, instanceId),
         },
         mirror: {
+          onNativeClientPresence: (session, present) =>
+            nativeSurfaces?.demand.presence(session, present),
           splitLayoutEpoch: () => observationSelector?.nativeServerEpoch ?? null,
           splitLayoutPrepare: createNativeSplitReadiness({
             observation: () => observationSelector ?? null,
@@ -1762,6 +1787,7 @@ async function startEmbeddedDaemonGeneration(
         }
       }
       paneStreamRuntime = createPaneStreamRuntime({
+        nativeSurfaces,
         localImages,
         daemonInstanceId: instanceId,
         webSocketUrl: paneStreamWebSocketUrl(bindHostname, port),
@@ -1880,6 +1906,22 @@ async function startEmbeddedDaemonGeneration(
             return grant ? interactionEvidence.captureSourceBinding(grant) : null;
           },
           interactionReceipts,
+          resolveNativeSurfaceContext: createNativeSurfaceContextResolver({
+            generation: instanceId,
+            registry: workspaceRegistry,
+            catalog: createNativeTmuxServerCatalog(workspaceRegistry, fleetFactsTmuxRunner),
+            inventory: terminalInventoryRuntime,
+            run: (args, signal) => fleetFactsTmuxRunner(args, signal),
+            assertOpen: () => {
+              if (
+                defaultEditorContextRetired ||
+                serverOwners?.defaultRetired ||
+                !initialNativeServerIdentity ||
+                terminalInventoryRuntime?.lifecycleState() !== "ready"
+              )
+                throw new Error("Default native surface context owner is unavailable");
+            },
+          }),
           resolvePaneEditorContext: createPaneEditorContextResolver({
             generation: instanceId,
             registry: workspaceRegistry,