cortena-ui 1.8.0 → 1.11.0

package/CHANGELOG.md

@@ -3,6 +3,133 @@
 Notable changes per release. Versions before 1.6.0 are recorded in the git log
 and in `../../CONSUMING.md`; this file starts where the changelog does.
 
+## 1.11.0
+
+### Added
+
+- **`RichTextEditor`** (DESIGN-54). Rich text editing, which nothing in the
+  fleet had. KeyStone needs it for vision documents, PRDs and requirement
+  documents; Tasks needs it to be able to replace a `<textarea>` it chose on
+  purpose. TipTap on ProseMirror, React bindings, value is Markdown (GFM) in
+  and out. Exported from the barrel and from its own subpath entry,
+  `cortena-ui/rich-text-editor` — TipTap and ProseMirror are 619 kB and MCP app
+  HTML is capped at 512 kB, so `test/bundle-probe.test.mjs` now asserts that no
+  other entry carries a byte of the editor engine (`button` from the barrel is
+  still 37.7 kB and pulls none of it).
+  - **The round trip is the feature.** An untouched document serialises
+    byte-identically — same line endings, same trailing whitespace — and
+    editing one paragraph changes one paragraph. Tasks uses a plain textarea
+    because a rich editor "would reformat text nobody touched and land it as a
+    spurious revision"; that constraint is a requirement of this component.
+    `markdown-bridge.ts` is mdast-based and source-preserving rather than
+    `tiptap-markdown`, which serialises through Turndown and renormalises
+    everything it touches. Asserted over an 18-file corpus in
+    `test/fixtures/rich-text/`.
+  - **Supported subset**: paragraphs, h2–h4, bold, italic, strikethrough,
+    inline code, links, ordered/bullet/task lists, blockquote, fenced code, GFM
+    tables, horizontal rule, images by URL. Anything outside it — front matter,
+    HTML blocks, footnotes, display maths, h1, h5, h6 — is preserved as a raw
+    Markdown block, never dropped.
+  - **Slots, not features**: `mentionProvider`, `selectionActions`,
+    `renderChip`. A mention is stored as `[@Priya](mention:user-42)`, so it is
+    still Markdown. Editor JSON and HTML never leave the component.
+  - **Controlled `value` with an explicit `version`**: a new revision arriving
+    while the author is focused does not clobber them; `onExternalChange` fires
+    with an `apply` for a conflict banner.
+  - Toolbar on the existing `Toolbar` primitive, keyboard shortcuts, and the
+    Markdown input rules (`## `, `- `, `1. `, `> `, backticks).
+
+### Changed
+
+- The prose class map moved to `src/lib/prose.ts` and is now shared by
+  `Markdown` and `RichTextEditor`. No visual change — the strings are the same
+  ones — but the read view and the edit view can no longer drift apart, which
+  is what keeps a document from shifting when it enters edit mode.
+
+## 1.10.0
+
+1.9.0 was never released: it was published by mistake and has been deprecated.
+
+### Added
+
+- **Screens inside the pop-up** (DESIGN-78). An extension's tool can answer
+  with its own screen — a `ui://` resource — and until now only cortenaweb
+  could show it; the pop-up inside the extension had no host. The host is now
+  in this package, on the `cortena-ui/agent-chat` entry:
+  - `McpAppFrame` — the sandboxed iframe (`allow-scripts allow-forms`, never
+    `allow-same-origin`), the `srcdoc` with the CSP written ahead of the app's
+    markup (`default-src 'none'`, no `unsafe-eval`, `form-action 'none'`), the
+    JSON-RPC bridge (`ui/initialize`, `ui/message`, `tools/call`,
+    `ui/update-model-context`, size and theme), the source and origin check
+    on every message, the height clamp (120–720 px), the `ui/message` bound
+    (`MCP_APP_MAX_MESSAGE_CHARS`, 4,000 chars; longer is refused with
+    `-32602`, since that text reaches the model) and the theme push. It holds
+    no credential: `callTool({ name, arguments, extensionId, lane })` is
+    supplied by the mounting app. A name that visibly belongs to another
+    extension (`mcp__notes__x`, `notes.note.delete`) is refused with `-32602`
+    before the relay is reached; a bare name (`task_get`, and equally
+    `broker_invoke`, `exec`, `read_file`) names no extension, so the frame
+    does not claim to confine it — it arrives as `lane: "bare"` beside
+    `extensionId`, for a relay that resolves it on that extension and nowhere
+    else. A resource another extension owns, a non-HTML type or a document
+    over
+    `MCP_APP_MAX_DOCUMENT_CHARS` (512,000; exported so a caller can make the
+    bound its own later, PLATFORM-82) is drawn as nothing and reported through
+    `onRefused`. Design tokens go in as `tokensCss` (inlined) or `tokensUrl`
+    (linked; its origin joins `style-src`/`font-src`); nothing is fetched
+    implicitly.
+  - `renderMcpAppToolCall({ extensionId, callTool, onMessage, … })` — a
+    `renderToolCall` for one extension. A screen is drawn only when the
+    *producing tool* can be named as this extension's — `mcp__<extensionId>__*`,
+    or `broker_invoke` whose `source` argument is this extension — **and** the
+    result carries that extension's embedded `ui://` resource (with
+    `structuredContent` from the result, or from
+    `_meta.cortena.structuredContent` on the block, as a reopened chat carries
+    it). A result is not a permission: an `exec` or a `read_file` whose output
+    happens to embed a `ui://` block keeps the ordinary card. `isEligible`
+    replaces the allowlist for a host whose tools are spelled another way.
+    Anything else returns `undefined` and the default card is drawn. Same type
+    as the seam in every mode.
+  - `AgentChatPopup` and owned-mode `AgentChat` take `renderToolCall` as
+    hosted mode does — the prop was on the shared base already; this release
+    pins it with a type-level test that the 1.7.0 mount shapes still compile.
+    See "Screens inside the pop-up" in `README.md`.
+- **The pop-up keeps every turn, and a screen can answer back** (DESIGN-80).
+  The pop-up used to hold the current turn only: `send` emptied the tool
+  cards, so an extension's screen was unmounted by the very turn it asked
+  for. It now behaves like the main chat.
+  - **A turn's tool record is its own.** Each turn keeps its steps, its cards
+    and its screens, and they are drawn in the transcript **under the answer
+    that turn produced** rather than in a strip at the foot that the next run
+    clears. A screen from three turns ago is still on the page and still
+    running. `AgentChatState` gains `turns?: AgentChatTurn[]` — optional, so a
+    host projecting its own store onto `UseAgentChatResult` compiles and
+    behaves exactly as before — with `TURN_LIMIT` (20) turns kept.
+  - **A reopened chat gets the record back, not just the prose.**
+    `parseHistory(records)` returns the messages *and* the per-turn tool
+    record behind them: the calls (`tool_use`, `toolCall`, `serverToolUse` —
+    matched with the case and the underscores taken out, as cortenacore
+    matches them), their results, and the embedded `ui://` resource with its
+    payload read from `_meta.cortena.structuredContent` where the pod
+    persisted it. The budget is cortenaweb's: 1,100,000 characters for one
+    result (`MAX_HISTORY_TOOL_RESULT_CHARS`) and 2,000,000 for a whole load
+    (`MAX_HISTORY_SNAPSHOT_RESULT_CHARS`), spent newest turn first; past it a
+    result becomes a note giving its size, with the call id, the tool's name
+    and whether it failed all kept. `parseHistoryMessages` is unchanged.
+  - **`AgentToolRenderContext` gains `send(text)`**, and
+    `AgentChatToolsSlotProps` gains the same field for a host that replaces
+    the region and builds the context itself. Optional on both, so a host
+    that builds the render context as an object literal of its own — as
+    cortenaweb's step accordion does — compiles unchanged. `renderMcpAppToolCall` wires
+    `onMessage` to it by default, so `onMessage` is now optional: a
+    `ui/message` from a screen goes out as the MCP App action envelope —
+    `{ toolCallId, appUri, serverName, name: "message", payload: { text } }` —
+    attributed to the screen, with no user bubble, bounded by
+    `MCP_APP_MAX_MESSAGE_CHARS` (4,000) and refused while a run is live.
+  - A host that supplies `components.Tools` still owns the whole tool region:
+    it is handed every turn's entries, and the transcript draws none.
+  - See "Screens inside the pop-up" in `README.md`.
+
 ## 1.8.0
 
 ### Added

package/README.md

@@ -36,6 +36,7 @@ consumer's bundler getting tree-shaking right:
 | `cortena-ui/a2ui` | the A2UI catalogue and renderer | most of the package, by design |
 | `cortena-ui/sortable-list` | `SortableList`, `SortableHandle`, `arrayMove` | dnd-kit |
 | `cortena-ui/agent-chat` | `AgentChatPopup`, `AgentChat`, `createAguiAgentChatClient` | the A2UI catalogue, plus `@ag-ui/client` (rxjs, zod 3, uuid, protobuf) |
+| `cortena-ui/rich-text-editor` | `RichTextEditor`, `parseMarkdown`, `serializeMarkdown` | TipTap on ProseMirror, 619 kB — the heaviest entry in the package |
 
 Each component has exactly one home, so the barrel re-exports every entry
 without an ambiguous name. **Adding a component means adding it to its area
@@ -300,24 +301,101 @@ cortenacore.http.endpoints.agui.enabled          = true
 cortenacore.http.endpoints.controlPlane.enabled  = true
 ```
 
-### The MCP App frame
+### Screens inside the pop-up
 
-Rendering an extension's own screen means a sandboxed iframe, a `srcdoc` CSP, a
-JSON-RPC postMessage bridge and a `tools/invoke` proxy holding a credential —
-host concerns, not component ones. `renderToolCall` is the seam: it is handed
-each tool call and the `ui://` resource its result carries, and a node it
-returns replaces the default card.
+An extension's tool may answer with the extension's own screen — an embedded
+`ui://` resource whose body is HTML — and the pop-up draws it inside the
+conversation, sandboxed, with a postMessage bridge (DESIGN-78; the protocol as
+implemented is cortena's `docs/mcp-apps.md`). `renderToolCall` is the seam,
+in every mode, and `renderMcpAppToolCall` answers it for one extension:
 
 ```tsx
-<AgentChatPopup
-  extension={extension}
-  client={client}
-  renderToolCall={({ entry, mcpAppUri }) =>
-    mcpAppUri ? <McpAppFrame uri={mcpAppUri} result={entry.output} /> : undefined
-  }
-/>
+const renderToolCall = renderMcpAppToolCall({ extensionId: "tasks", callTool });
+<AgentChatPopup extension={extension} client={client} renderToolCall={renderToolCall} />
 ```
 
+That is the whole round trip. A tool answers with a screen, the screen is
+drawn under the answer it came with, a click inside it starts the next turn,
+and the screen is still there when the answer arrives (DESIGN-80).
+
+- **Only a tool that can be named as yours may draw a screen.** The default
+  allowlist is `mcp__<extensionId>__*`, and `broker_invoke` whose `source`
+  argument is your extension. A result is not a permission: an `exec` that
+  cat'd a fixture or a `read_file` over your test data answers with whatever
+  `ui://` block was in the file, and that stays an ordinary tool card. Pass
+  `isEligible(entry)` to replace the rule if your host's tools are spelled a
+  third way — you are replacing an allowlist, so you are deciding which tools
+  may put unreviewed HTML on the page.
+- `callTool(call)` is **yours**: the relay that reaches your extension — your
+  own MCP relay, or cortenaweb's `/tools/invoke` — and whatever credential it
+  takes stays with it. The frame never sees a token. It hands you
+  `{ name, arguments, extensionId, lane }`, and the lane is the point:
+
+  ```ts
+  type McpAppToolCaller = (call: {
+    name: string;
+    arguments: Record<string, unknown>;
+    extensionId: string;
+    lane: "mcp" | "broker" | "bare";
+  }) => Promise<unknown>;
+  ```
+
+  `lane: "mcp"` (`mcp__tasks__x`) and `lane: "broker"` (`tasks.task.get`)
+  carry the extension in the name, and a name that carries a *different* one
+  (`mcp__notes__x`, `notes.note.delete`) is refused with `-32602` before your
+  relay is reached. `lane: "bare"` (`task_get`) carries nothing: `exec`,
+  `read_file` and `broker_invoke` are bare names too. **Resolve a bare name on
+  `extensionId` and nowhere else** — never forward it as a tool name of your
+  own — and an app cannot reach past its extension whatever it asks for.
+- `onMessage(text)` is the app asking for something to be said, and **it is
+  wired for you**: with nothing passed, the text goes out through the seam's
+  own `send` as the next turn, attributed to the screen and not to the user —
+  nobody typed it, so no user bubble is drawn. What reaches the agent is the
+  MCP App action envelope (`{ toolCallId, appUri, serverName, name: "message",
+  payload: { text } }`), which is what lets an agent tell an event from your
+  board apart from one from another extension's card. It is bounded: the host
+  refuses text over 4,000 characters (`MCP_APP_MAX_MESSAGE_CHARS`) with
+  `-32602`, because this text reaches the model, and it is a no-op while a run
+  is already live — one run at a time, the same rule the composer follows.
+  Pass your own `onMessage` to do something else with it instead.
+  `onModelContext(ctx)` is its latest context for the next run.
+- A call from a tool outside the allowlist, or a result carrying another
+  extension's screen, a bare link, or no screen at all, returns `undefined`
+  and the default card is drawn.
+- Design tokens are not fetched implicitly. Pass `tokensCss` (the sheet,
+  inlined ahead of the app's markup) or `tokensUrl` (linked; its origin joins
+  `style-src` and `font-src`, never `connect-src`).
+
+What the frame owns and no caller can widen: `sandbox="allow-scripts
+allow-forms"` (never `allow-same-origin`, so the document runs in an opaque
+origin with no storage and no reach into the page), a CSP written into the
+`srcdoc` ahead of the app's markup (`default-src 'none'`, no `unsafe-eval`,
+`form-action 'none'`; `_meta.ui.csp` on the resource may open named `https`
+origins and nothing else), a message check that accepts only its own frame's
+window at an opaque origin, a height the app asks for clamped to 120–720 px,
+and a document bound of `MCP_APP_MAX_DOCUMENT_CHARS` (512,000) past which the
+resource is refused. A refusal draws nothing and reports through
+`onRefused(reason)`. `McpAppFrame` is exported for a host that finds the
+resource itself.
+
+**Where a screen lives.** Each turn keeps its own tool record — its steps, its
+cards and its screens — and the record is drawn in the transcript under the
+answer that turn produced, not in a strip at the foot that the next `send`
+empties. So a screen from three turns ago is still on the page, still running,
+and a turn sent from a screen does not unmount the screen that sent it. The
+record of a turn survives a reopen too: `chat.history` carries the calls and
+their results, so the cards, the worded steps and any screen come back with the
+prose (`parseHistory`). Twenty turns are kept (`TURN_LIMIT`), and a reopen
+spends at most 2 MB on tool results, newest turn first; past that a result
+becomes a note that says how big it was, with its call, its name and its
+outcome intact.
+
+`AgentToolRenderContext` therefore carries `send(text)` — the handle
+`renderMcpAppToolCall` wires `onMessage` to. A host that replaces the whole
+tool region with `components.Tools` gets the same handle on its slot props and
+passes it into `renderToolCall` itself; that host owns every card, so the
+transcript draws none, and its `entries` are every turn's, not just the newest.
+
 ### Hosting the surface
 
 `AgentChatPopup` owns its state. A host that already has state of its own —
@@ -354,6 +432,119 @@ names the session (the key is still written, so one window stays on one
 session), `listSessions: false` for a host with its own session list, and
 `mintSessionKey` for a host that binds sessions some other way.
 
+## RichTextEditor
+
+WYSIWYG editing whose value is Markdown (GFM), in and out. KeyStone needs it for
+vision documents, PRDs and requirement documents; nothing else in the fleet has
+rich text at all.
+
+```tsx
+import { RichTextEditor } from "cortena-ui/rich-text-editor";
+
+<RichTextEditor
+  value={markdown}
+  version={revision}
+  aria-label="Vision document"
+  onChange={setMarkdown}
+  onExternalChange={({ apply }) => setConflict(() => apply)}
+  mentionProvider={({ trigger, query }) => search(trigger, query)}
+  selectionActions={({ text, editor }) => <AskAgent text={text} />}
+/>
+```
+
+Editor JSON and HTML never leave the component. There is no `getHTML` escape
+hatch on purpose: the moment a consumer stores ProseMirror JSON, the document
+stops being a file that anything else can read.
+
+### The round trip is the feature
+
+Tasks deliberately uses a plain `<textarea>` for its section editor, because a
+rich editor "would reformat text nobody touched and land it as a spurious
+revision". That constraint is a requirement of this component, not a nice-to-have:
+
+- **An untouched document serialises byte-identically.** Same bytes, including
+  line endings, trailing whitespace and a byte order mark.
+- **Editing one paragraph changes one paragraph.** Every other block is written
+  back from the source it was parsed from.
+
+`test/rich-text-markdown.test.tsx` asserts both over an 18-file corpus in
+`test/fixtures/rich-text/`, covering nested lists, fences containing fences,
+tables with escaped pipes, links with titles, CRLF and trailing whitespace.
+
+### Why the bridge is written rather than adopted
+
+`tiptap-markdown` is the obvious candidate and it fails the one requirement
+above. It serialises by rendering the editor to HTML and running Turndown over
+it, so the output is whatever Turndown's rules produce: bullets become `*`,
+emphasis becomes `_`, tables are re-padded, and a document nobody edited comes
+back different from how it went in. A component that cannot replace the Tasks
+textarea has not delivered anything.
+
+A plain mdast serializer does not fix it either. Any AST round trip normalises —
+`mdast-util-to-markdown` has one way to write a bullet — and the moment the
+author's file disagrees, every untouched paragraph in it is rewritten.
+
+So `markdown-bridge.ts` is mdast-based **and** source-preserving. Parsing keeps
+the exact source slice of every top-level block; a block whose ProseMirror JSON
+is byte-for-byte what parsing produced is written back from that slice, and only
+a block the user actually changed goes through `mdast-util-to-markdown`. The
+dependencies are `mdast-util-from-markdown`, `mdast-util-to-markdown`,
+`mdast-util-gfm` and `micromark-extension-frontmatter` (all MIT), which is the
+same layer react-markdown already uses — `src/lib/prose.ts` is imported by both
+views and reaches neither react-markdown nor ProseMirror.
+
+### The supported subset, and what happens outside it
+
+Paragraphs; headings h2–h4 (h1 is reserved for the record's own title); bold,
+italic, strikethrough, inline code; links; ordered, bullet and task lists;
+blockquote; fenced code; GFM tables; horizontal rule; images by URL.
+
+Anything else — front matter, HTML blocks, footnotes, display maths, h1, h5, h6 —
+becomes a **raw block**: a code-like node holding the original Markdown as text,
+editable as raw Markdown and serialised with no escaping. It is never dropped.
+The rule applies at the block boundary, so a paragraph containing a footnote
+reference goes raw whole rather than losing the reference from an otherwise
+editable paragraph.
+
+Not in scope: maths rendering, collaborative cursors, comments UI, image upload,
+syntax highlighting in fences.
+
+### Slots, not features
+
+`@` and `#` mean nothing to this component. `mentionProvider` is asked for items
+and a chip is inserted; whether that resolves to a person, a task or a page is
+the consumer's business. A mention is stored as `[@Priya](mention:user-42)`, so
+the document is still ordinary Markdown and the editor reads the chip back on
+the next open.
+
+What survives in the **read** view is the label, not the link: `Markdown` passes
+URLs through react-markdown's `urlTransform`, which drops any protocol it does
+not know, so `[@Priya](mention:user-42)` renders as the text `@Priya` with no
+href. A host that wants mentions to be clickable in the read view passes its own
+`urlTransform` to `Markdown` and resolves `mention:` itself.
+
+`selectionActions` renders whatever the host wants over the current selection,
+and `renderChip` replaces how a mention looks in the menu.
+
+### The controlled value and `version`
+
+`value` is the document and `version` is the revision it belongs to. A new
+revision arriving while the author is focused does **not** replace what they are
+writing: `onExternalChange` fires with `{ value, version, apply }` so the
+consumer can show a conflict banner and adopt it on the author's say-so. When
+the author is not in the editor it is adopted silently. `version` defaults to
+`value`, so a consumer that simply echoes `onChange` back still behaves — an
+echo of our own output is never treated as a conflict.
+
+### Styling
+
+Prose comes from `src/lib/prose.ts`, the same class strings the `Markdown`
+renderer paints the read view with, handed to TipTap as each node's
+`HTMLAttributes.class`. That is the only reason a document does not shift when
+it enters edit mode, and `test/rich-text-editor.test.tsx` compares the computed
+font size, family, weight and line height of both components on the same source.
+Changing a prose style means changing it in `prose.ts`, for both views at once.
+
 ## Column widths
 
 `DataTable` lays the grid out `table-fixed`: every column is drawn at its

package/dist/agent-chat/mcp-app/bridge.d.ts

@@ -0,0 +1,194 @@
+"use client";
+//#region src/agent-chat/mcp-app/bridge.d.ts
+/**
+ * The host side of the MCP Apps postMessage bridge.
+ *
+ * Implements the host role of the MCP Apps specification dated 2026-01-26 —
+ * the one `@modelcontextprotocol/ext-apps` 1.7.5 publishes — with the method
+ * names and handshake verbatim, so an app built with the SDK's `App` class
+ * connects with no Cortena-specific code. Ported from cortenaweb's host
+ * (DESIGN-36); the spec strings are copied rather than imported so this
+ * package does not take `@modelcontextprotocol/sdk` and a zod copy into the
+ * browser bundle for one JSON-RPC dialogue, and the tests pin every one.
+ *
+ * ## Who the host will listen to
+ *
+ * Three checks, in order, before a frame's message is looked at at all:
+ *
+ * 1. `event.source === iframe.contentWindow` — the one thing a frame cannot
+ *    forge. Any other frame on the page fails here.
+ * 2. `event.origin === "null"` — an app runs without `allow-same-origin`, so
+ *    its origin is opaque and serialises as the string `"null"`. A message
+ *    from a real origin did not come from a sandboxed app, whatever its
+ *    `source` claims.
+ * 3. The body must be a JSON-RPC 2.0 envelope naming a method the host serves.
+ *
+ * Replies go out with `targetOrigin: "*"`, which is correct rather than lazy:
+ * an opaque origin cannot be named, so `"*"` is the only value that reaches
+ * it, and nothing sent is a secret — the tool result the app's own extension
+ * produced, and the theme.
+ */
+/** `LATEST_PROTOCOL_VERSION` in the MCP Apps spec. */
+export declare const MCP_APP_PROTOCOL_VERSION = "2026-01-26";
+/** Every method name the spec defines, as the host sees them. */
+export declare const MCP_APP_METHOD: {
+  readonly INITIALIZE: "ui/initialize";
+  readonly OPEN_LINK: "ui/open-link";
+  readonly MESSAGE: "ui/message";
+  readonly UPDATE_MODEL_CONTEXT: "ui/update-model-context";
+  readonly REQUEST_DISPLAY_MODE: "ui/request-display-mode";
+  readonly CALL_TOOL: "tools/call";
+  readonly PING: "ping";
+  readonly INITIALIZED: "ui/notifications/initialized";
+  readonly SIZE_CHANGED: "ui/notifications/size-changed";
+  readonly TOOL_INPUT: "ui/notifications/tool-input";
+  readonly TOOL_RESULT: "ui/notifications/tool-result";
+  readonly HOST_CONTEXT_CHANGED: "ui/notifications/host-context-changed";
+};
+/** JSON-RPC error codes the host returns. */
+export declare const MCP_APP_ERROR: {
+  readonly METHOD_NOT_FOUND: -32601;
+  readonly INVALID_PARAMS: -32602;
+  readonly INTERNAL: -32603;
+};
+/**
+ * The longest `ui/message` the host will carry.
+ *
+ * `ui/message` becomes a turn in the conversation, so the text an app sends
+ * is text that goes to the model — and an app is HTML nobody reviewed. An
+ * unbounded field is a way to spend a context window, and a paste of a
+ * hundred kilobytes is not a sentence a screen wanted said. Long enough for
+ * any real request; short enough that it cannot be the payload.
+ */
+export declare const MCP_APP_MAX_MESSAGE_CHARS = 4000;
+export interface McpAppHostContext {
+  theme?: "light" | "dark";
+  styles?: {
+    variables?: Record<string, string | undefined>;
+  };
+  displayMode?: "inline";
+  availableDisplayModes?: Array<"inline">;
+  containerDimensions?: {
+    maxWidth?: number;
+    maxHeight?: number;
+  };
+  locale?: string;
+  timeZone?: string;
+  userAgent?: string;
+  platform?: "web";
+  /** Cortena extension: where the app can fetch the design tokens, when the host serves them. */
+  cortena?: {
+    tokensCssUrl?: string;
+  };
+  [key: string]: unknown;
+}
+/**
+ * How a scoped `tools/call` reaches the app's own extension. Supplied by the
+ * mounting app; the frame never sees a token.
+ *
+ * The call arrives as one envelope rather than a name and arguments, because
+ * a name on its own cannot be confined. Two of the three spellings an app may
+ * use carry the extension (`mcp__tasks__x`, `tasks.task.get`) and are refused
+ * before they reach here when the extension is not this one; the third is
+ * **bare** (`task_get`), and a bare name names nothing — `broker_invoke`,
+ * `exec` and `read_file` are bare names too. So `extensionId` and `lane`
+ * travel with it: a relay handed `lane: "bare"` must resolve `name` on
+ * `extensionId` and nowhere else, and a relay that scopes on `extensionId`
+ * cannot be tricked into forwarding an app's bare name as a tool of its own.
+ */
+export type McpAppToolCaller = (call: {
+  name: string;
+  arguments: Record<string, unknown>;
+  extensionId: string;
+  lane: "mcp" | "broker" | "bare";
+}) => Promise<unknown>;
+export interface McpAppBridgeOptions {
+  /** The frame the app runs in. Its `contentWindow` is the only valid source. */
+  iframe: HTMLIFrameElement;
+  /** The extension the app belongs to; every `tools/call` is confined to it. */
+  extensionId: string;
+  /** `_meta.ui` the resource declared, echoed in `hostCapabilities.sandbox`. */
+  sandbox?: {
+    permissions?: unknown;
+    csp?: unknown;
+  };
+  /** Arguments the agent passed. Sent as `ui/notifications/tool-input`. */
+  toolArguments?: Record<string, unknown>;
+  /** The whole tool result. Sent as `ui/notifications/tool-result`. */
+  toolResult?: unknown;
+  hostContext: McpAppHostContext;
+  /** Present only when the app's own extension can be reached. */
+  callTool?: McpAppToolCaller;
+  /** `ui/message`: the text the app wants said in the conversation. */
+  onMessage?: (text: string) => void;
+  /** The app asked for a height. */
+  onSizeChanged?: (size: {
+    width?: number;
+    height?: number;
+  }) => void;
+  /** The handshake completed. */
+  onInitialized?: () => void;
+  /** `ui/open-link`. Defaults to a `noopener` `window.open`. */
+  onOpenLink?: (url: string) => boolean;
+  /** The app's latest `ui/update-model-context`. */
+  onModelContext?: (context: {
+    content?: unknown[];
+    structuredContent?: unknown;
+  }) => void;
+  /** For tests. Defaults to `window`. */
+  listenTarget?: Pick<Window, "addEventListener" | "removeEventListener">;
+}
+export declare class McpAppHostBridge {
+  private readonly options;
+  private readonly listenTarget;
+  private hostContext;
+  private toolResult;
+  private initialized;
+  private closed;
+  private readonly onMessage;
+  constructor(options: McpAppBridgeOptions);
+  start(): void;
+  close(): void;
+  /** Did the app complete `ui/initialize` + `ui/notifications/initialized`? */
+  get isInitialized(): boolean;
+  /**
+   * Capabilities the host advertises. `serverTools` only when there is a
+   * caller: an app that sees it absent knows not to try, which is the spec's
+   * own way of saying "not here" and better than letting it call and fail.
+   */
+  private capabilities;
+  /**
+   * A replaced tool result for a screen already running.
+   *
+   * The same call re-run answers with the same document, so the frame is not
+   * remounted and the app never repeats its handshake — which is where the
+   * payload is otherwise sent. Without this the screen would keep drawing the
+   * first answer's data for the rest of the conversation.
+   */
+  setToolResult(result: unknown): void;
+  /** Push a changed theme (or anything else) to a running app. */
+  setHostContext(patch: McpAppHostContext): void;
+  private post;
+  private notify;
+  private respond;
+  private fail;
+  /** The right window, and an origin that proves it is sandboxed. */
+  private isFromApp;
+  private handleMessage;
+  private dispatch;
+  /**
+   * `tools/call` from the app: scoped, not proxied. The app may call tools on
+   * *its own* extension and nothing else — see `scopeMcpAppToolCall` for the
+   * rule and why. A name that visibly belongs to another extension is refused
+   * here, before the relay is reached; a bare name reaches the relay wrapped
+   * in `extensionId` and `lane: "bare"`, so the relay resolves it on this
+   * extension rather than taking it for a tool of its own. Whatever the relay
+   * answers goes back as the result, and a throw becomes a tool result the
+   * app can show.
+   */
+  private handleCallTool;
+  /** The tool's arguments and result, once the app says it is listening. */
+  private sendToolPayload;
+}
+//#endregion
+//# sourceMappingURL=bridge.d.ts.map