spec(draft): add split display mode

Add a fourth McpUiDisplayMode, "split": the View is displayed in a
persistent, non-overlapping region while the host's primary
conversational interface remains visible and interactive. This keeps
interactive Views (spreadsheets, maps, dashboards) referenceable as the
conversation scrolls on, instead of losing them off-screen.

- spec.types.ts + draft spec: define "split" semantics and non-goals
- regenerate Zod/JSON schemas via `npm run generate:schemas`
- debug-server: add a "Split" display-mode control
- basic-host: advertise "split" and render the View in a resizable,
  docked region without remounting the iframe, so View state survives
  inline <-> split transitions
- unit + E2E coverage for negotiation and transitions

Prototype for #684; relates to #412 and #430.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: caseprince

examples/basic-host/src/global.css

@@ -38,3 +38,9 @@ html, body {
 code {
   font-size: 1em;
 }
+
+/* While a View is in split display mode, reserve the right-hand region for it
+   so the conversation column and the split View never overlap. */
+body.split-view-active {
+  margin-right: var(--split-view-width, 40vw);
+}

examples/basic-host/src/implementation.ts

@@ -262,15 +262,19 @@ function hookInitializedCallback(appBridge: AppBridge): Promise<void> {
 export type ModelContext = McpUiUpdateModelContextRequest["params"];
 export type AppMessage = McpUiMessageRequest["params"];
 
+/** Display modes this host supports and advertises to apps. */
+export type HostDisplayMode = "inline" | "fullscreen" | "split";
+export const HOST_AVAILABLE_DISPLAY_MODES: HostDisplayMode[] = ["inline", "fullscreen", "split"];
+
 export interface AppBridgeCallbacks {
   onContextUpdate?: (context: ModelContext | null) => void;
   onMessage?: (message: AppMessage) => void;
-  onDisplayModeChange?: (mode: "inline" | "fullscreen") => void;
+  onDisplayModeChange?: (mode: HostDisplayMode) => void;
 }
 
 export interface AppBridgeOptions {
   containerDimensions?: { maxHeight?: number; width?: number } | { height: number; width?: number };
-  displayMode?: "inline" | "fullscreen";
+  displayMode?: HostDisplayMode;
 }
 
 export function newAppBridge(
@@ -296,7 +300,7 @@ export function newAppBridge(
       },
       containerDimensions: options?.containerDimensions ?? { maxHeight: 6000 },
       displayMode: options?.displayMode ?? "inline",
-      availableDisplayModes: ["inline", "fullscreen"],
+      availableDisplayModes: HOST_AVAILABLE_DISPLAY_MODES,
     },
   });
 
@@ -395,7 +399,9 @@ export function newAppBridge(
   // Handle display mode change requests from the app
   appBridge.onrequestdisplaymode = async (params) => {
     log.info("Display mode request from MCP App:", params);
-    const newMode = params.mode === "fullscreen" ? "fullscreen" : "inline";
+    const newMode = (HOST_AVAILABLE_DISPLAY_MODES as string[]).includes(params.mode)
+      ? (params.mode as HostDisplayMode)
+      : "inline";
     // Update host context and notify the app
     appBridge.sendHostContextChange({
       displayMode: newMode,

examples/basic-host/src/index.module.css

@@ -183,6 +183,54 @@
       border-radius: 0;
     }
   }
+
+  /* Persistent, non-overlapping region docked to the right; the host's
+     conversation column shifts aside via body.split-view-active (global.css)
+     and stays visible and interactive. */
+  &.split {
+    position: fixed;
+    top: 0;
+    right: 0;
+    bottom: 0;
+    width: var(--split-view-width, 40vw);
+    z-index: 900;
+    margin: 0;
+    padding: 1rem;
+    max-width: none;
+    background: var(--color-bg);
+    border: none;
+    border-left: 1px solid var(--color-border);
+    border-radius: 0;
+    display: flex;
+    flex-direction: column;
+
+    /* The split region is dedicated to the View */
+    .collapsiblePanel {
+      display: none;
+    }
+
+    iframe {
+      flex: 1;
+      height: 100%;
+      border: none;
+      border-radius: 0;
+    }
+  }
+}
+
+.splitResizeHandle {
+  position: absolute;
+  top: 0;
+  left: -3px;
+  width: 6px;
+  height: 100%;
+  cursor: col-resize;
+  touch-action: none;
+  user-select: none;
+
+  &:hover {
+    background: var(--color-primary);
+  }
 }
 
 .appToolbar {

examples/basic-host/src/index.tsx

@@ -2,7 +2,7 @@ import { getToolUiResourceUri, McpUiToolMetaSchema } from "@modelcontextprotocol
 import type { Tool } from "@modelcontextprotocol/sdk/types.js";
 import { Component, type ErrorInfo, type ReactNode, StrictMode, Suspense, use, useEffect, useMemo, useRef, useState } from "react";
 import { createRoot } from "react-dom/client";
-import { callTool, connectToServer, hasAppHtml, initializeApp, loadSandboxProxy, log, newAppBridge, type ServerInfo, type ToolCallInfo, type ModelContext, type AppMessage } from "./implementation";
+import { callTool, connectToServer, hasAppHtml, initializeApp, loadSandboxProxy, log, newAppBridge, type ServerInfo, type ToolCallInfo, type ModelContext, type AppMessage, type HostDisplayMode } from "./implementation";
 import { getTheme, toggleTheme, onThemeChange, type Theme } from "./theme";
 import styles from "./index.module.css";
 
@@ -417,6 +417,50 @@ function CollapsiblePanel({ icon, label, content, badge, defaultExpanded = false
 }
 
 
+// Reserve the split region on <body> while at least one View is in split
+// mode, so the host's conversation column shifts aside instead of being
+// overlapped. Counted so multiple panels (and Strict Mode re-runs) compose.
+let splitViewCount = 0;
+function acquireSplitRegion(): () => void {
+  if (++splitViewCount === 1) {
+    document.body.classList.add("split-view-active");
+  }
+  return () => {
+    if (--splitViewCount === 0) {
+      document.body.classList.remove("split-view-active");
+      document.documentElement.style.removeProperty("--split-view-width");
+    }
+  };
+}
+
+// Keep the split region within sensible bounds: wide enough to be useful,
+// narrow enough that the conversation column stays usable.
+function setSplitViewWidth(clientX: number) {
+  const width = Math.min(
+    Math.max(window.innerWidth - clientX, 280),
+    window.innerWidth - 320,
+  );
+  document.documentElement.style.setProperty("--split-view-width", `${width}px`);
+}
+
+function SplitResizeHandle() {
+  return (
+    <div
+      className={styles.splitResizeHandle}
+      title="Drag to resize"
+      onPointerDown={(e) => {
+        e.preventDefault();
+        e.currentTarget.setPointerCapture(e.pointerId);
+      }}
+      onPointerMove={(e) => {
+        if (e.currentTarget.hasPointerCapture(e.pointerId)) {
+          setSplitViewWidth(e.clientX);
+        }
+      }}
+    />
+  );
+}
+
 interface AppIFramePanelProps {
   toolCallInfo: Required<ToolCallInfo>;
   isDestroying?: boolean;
@@ -427,7 +471,14 @@ function AppIFramePanel({ toolCallInfo, isDestroying, onTeardownComplete }: AppI
   const appBridgeRef = useRef<ReturnType<typeof newAppBridge> | null>(null);
   const [modelContext, setModelContext] = useState<ModelContext | null>(null);
   const [messages, setMessages] = useState<AppMessage[]>([]);
-  const [displayMode, setDisplayMode] = useState<"inline" | "fullscreen">("inline");
+  const [displayMode, setDisplayMode] = useState<HostDisplayMode>("inline");
+
+  // Reserve the split region while active. Only the panel's className
+  // changes, so the iframe is never remounted and View state survives.
+  useEffect(() => {
+    if (displayMode !== "split") return;
+    return acquireSplitRegion();
+  }, [displayMode]);
 
   useEffect(() => {
     const iframe = iframeRef.current!;
@@ -510,12 +561,17 @@ function AppIFramePanel({ toolCallInfo, isDestroying, onTeardownComplete }: AppI
   };
   const messagesText = messages.map(formatMessage).join("\n\n");
 
-  const panelClassName = displayMode === "fullscreen"
-    ? `${styles.appIframePanel} ${styles.fullscreen}`
-    : styles.appIframePanel;
+  const panelClassName = [
+    styles.appIframePanel,
+    displayMode === "fullscreen" && styles.fullscreen,
+    displayMode === "split" && styles.split,
+  ]
+    .filter(Boolean)
+    .join(" ");
 
   return (
     <div className={panelClassName}>
+      {displayMode === "split" && <SplitResizeHandle />}
       <iframe ref={iframeRef} />
       {messages.length > 0 && (
         <CollapsiblePanel

examples/debug-server/mcp-app.html

@@ -134,6 +134,7 @@ <h3>Display Mode</h3>
             <button id="display-inline-btn" class="btn-small">Inline</button>
             <button id="display-fullscreen-btn" class="btn-small">Fullscreen</button>
             <button id="display-pip-btn" class="btn-small">PiP</button>
+            <button id="display-split-btn" class="btn-small">Split</button>
           </div>
         </div>
 

examples/debug-server/src/mcp-app.ts

@@ -99,6 +99,7 @@ const updateContextImageBtn = document.getElementById(
 const displayInlineBtn = document.getElementById("display-inline-btn")!;
 const displayFullscreenBtn = document.getElementById("display-fullscreen-btn")!;
 const displayPipBtn = document.getElementById("display-pip-btn")!;
+const displaySplitBtn = document.getElementById("display-split-btn")!;
 
 const linkUrlEl = document.getElementById("link-url") as HTMLInputElement;
 const openLinkBtn = document.getElementById("open-link-btn")!;
@@ -347,7 +348,10 @@ function handleHostContextChanged(ctx: McpUiHostContext): void {
 
 const app = new App(
   { name: "Debug App", version: "1.0.0" },
-  { tools: { listChanged: true } }, // Declare tools capability for oncalltool/onlisttools
+  {
+    tools: { listChanged: true }, // Declare tools capability for oncalltool/onlisttools
+    availableDisplayModes: ["inline", "fullscreen", "pip", "split"],
+  },
   { autoResize: false }, // We'll manage auto-resize ourselves for toggle demo
 );
 
@@ -514,7 +518,7 @@ updateContextImageBtn.addEventListener("click", async () => {
 // ============================================================================
 
 async function requestDisplayMode(
-  mode: "inline" | "fullscreen" | "pip",
+  mode: "inline" | "fullscreen" | "pip" | "split",
 ): Promise<void> {
   try {
     const result = await app.requestDisplayMode({ mode });
@@ -529,6 +533,7 @@ displayFullscreenBtn.addEventListener("click", () =>
   requestDisplayMode("fullscreen"),
 );
 displayPipBtn.addEventListener("click", () => requestDisplayMode("pip"));
+displaySplitBtn.addEventListener("click", () => requestDisplayMode("split"));
 
 // ============================================================================
 // Link Action

specification/draft/apps.mdx

@@ -559,7 +559,7 @@ interface McpUiAppCapabilities {
    * Display modes the app supports. See Display Modes section for details.
    * @example ["inline", "fullscreen"]
    */
-  availableDisplayModes?: Array<"inline" | "fullscreen" | "pip">;
+  availableDisplayModes?: Array<"inline" | "fullscreen" | "pip" | "split">;
 }
 ```
 
@@ -589,7 +589,7 @@ interface HostContext {
     };
   };
   /** How the View is currently displayed */
-  displayMode?: "inline" | "fullscreen" | "pip";
+  displayMode?: "inline" | "fullscreen" | "pip" | "split";
   /** Display modes the host supports */
   availableDisplayModes?: string[];
   /** Container dimensions for the iframe. Specify either width or maxWidth, and either height or maxHeight. */
@@ -805,12 +805,23 @@ Views using the SDK automatically send size-changed notifications via ResizeObse
 Views can be displayed in different modes depending on the host's capabilities and the view's declared support.
 
 ```typescript
-type McpUiDisplayMode = "inline" | "fullscreen" | "pip";
+type McpUiDisplayMode = "inline" | "fullscreen" | "pip" | "split";
 ```
 
 - **inline**: Default mode, embedded within the host's content flow
 - **fullscreen**: View takes over the full screen/window
 - **pip**: Picture-in-picture, floating overlay
+- **split**: View is displayed in a persistent, non-overlapping region while the host's primary conversational interface remains visible and interactive
+
+#### Split Mode
+
+In `split` mode, the View occupies a dedicated region of the host UI (e.g., a side panel) that does not overlap the host's primary conversational interface. Both remain visible and interactive at the same time, allowing users to keep referencing the View as the conversation continues.
+
+- Host controls the orientation, placement, and dimensions of the split region, how (and whether) it can be resized, and how many split Views it permits at once.
+- Entering or leaving `split` mode SHOULD NOT inherently recreate the current View: it is a presentation change of the already-rendered View, and its state SHOULD be preserved across the transition.
+- This mode does not define reusing Views across separate tool calls; each tool call still renders a new View instance.
+
+`split` is additive: existing hosts and apps are unaffected.
 
 #### Declaring Support
 
@@ -1177,7 +1188,7 @@ Host behavior:
   id: 3,
   method: "ui/request-display-mode",
   params: {
-    mode: "inline" | "fullscreen" | "pip"  // Requested display mode
+    mode: "inline" | "fullscreen" | "pip" | "split"  // Requested display mode
   }
 }
 
@@ -1186,7 +1197,7 @@ Host behavior:
   jsonrpc: "2.0",
   id: 3,
   result: {
-    mode: "inline" | "fullscreen" | "pip"  // Actual display mode set
+    mode: "inline" | "fullscreen" | "pip" | "split"  // Actual display mode set
   }
 }
 ```

src/app-bridge.test.ts

@@ -624,6 +624,78 @@ describe("App <-> AppBridge integration", () => {
     });
   });
 
+  describe("display mode negotiation", () => {
+    it("app.requestDisplayMode round-trips the granted mode through bridge.onrequestdisplaymode", async () => {
+      const requestedModes: string[] = [];
+      bridge.onrequestdisplaymode = async ({ mode }) => {
+        requestedModes.push(mode);
+        return { mode };
+      };
+
+      await bridge.connect(bridgeTransport);
+      await app.connect(appTransport);
+      const result = await app.requestDisplayMode({ mode: "split" });
+
+      expect(requestedModes).toEqual(["split"]);
+      expect(result.mode).toBe("split");
+    });
+
+    it("default handler returns the current mode from host context", async () => {
+      const [newAppTransport, newBridgeTransport] =
+        InMemoryTransport.createLinkedPair();
+      const bridgeWithContext = new AppBridge(
+        createMockClient() as Client,
+        testHostInfo,
+        testHostCapabilities,
+        { hostContext: { displayMode: "fullscreen" } },
+      );
+
+      await bridgeWithContext.connect(newBridgeTransport);
+      await app.connect(newAppTransport);
+      const result = await app.requestDisplayMode({ mode: "split" });
+
+      expect(result.mode).toBe("fullscreen");
+
+      await newAppTransport.close();
+      await newBridgeTransport.close();
+    });
+
+    it("app and host can declare split in availableDisplayModes", async () => {
+      const [newAppTransport, newBridgeTransport] =
+        InMemoryTransport.createLinkedPair();
+      const splitApp = new App(
+        testAppInfo,
+        { availableDisplayModes: ["inline", "split"] },
+        { autoResize: false },
+      );
+      const bridgeWithContext = new AppBridge(
+        createMockClient() as Client,
+        testHostInfo,
+        testHostCapabilities,
+        {
+          hostContext: {
+            availableDisplayModes: ["inline", "fullscreen", "split"],
+          },
+        },
+      );
+
+      await bridgeWithContext.connect(newBridgeTransport);
+      await splitApp.connect(newAppTransport);
+
+      expect(
+        bridgeWithContext.getAppCapabilities()?.availableDisplayModes,
+      ).toEqual(["inline", "split"]);
+      expect(splitApp.getHostContext()?.availableDisplayModes).toEqual([
+        "inline",
+        "fullscreen",
+        "split",
+      ]);
+
+      await newAppTransport.close();
+      await newBridgeTransport.close();
+    });
+  });
+
   describe("deprecated method aliases", () => {
     beforeEach(async () => {
       await bridge.connect(bridgeTransport);