@@ -435,13 +435,23 @@ above. The plugin catalogue's apps area rides with that change rather than after
 that shows what is installed and what is running, so without it the view has nothing to be opened from. The agent capability follows the view: it is the only part that can be reviewed against a
 working page, since a plugin's agent calls are only observable from a page this client can display.
 
+### The proxy makes the document framable
+
+The page is framed by this client, on a different origin, so a page must not be able to refuse. The proxy
+therefore drops `X-Frame-Options` from every response it forwards and removes the `frame-ancestors`
+directive from a page's own CSP while leaving its other directives alone — the Mini App's origin is a
+separate origin from the client's, so the rest of its policy governs a document that cannot reach the
+client anyway. Nothing is added: no header the page did not ask for, no CSP of the proxy's own.
+
+The document is the one response the proxy rewrites. The page bridge has to be in the document before the
+page's own scripts run, so the proxy injects a script tag for it before `</head>`, or after the opening
+`<body>` tag when a page has no head, or ahead of the document when it has neither, and restates the
+`Content-Length` because the body it sends is not the body it received. Everything else — paths, methods,
+status codes, the page's own headers — passes through unchanged.
+
 ## Open implementation questions
 
-1. **Framing the page through the proxy.** One listener per Mini App is decided above; what remains is
-   which response headers the proxy must add or drop for the document to be framable at all, and what
-   it does with a Mini App that sets framing or CSP headers of its own. The desktop client offers no
-   precedent: it never frames the page and writes no response headers of its own.
-2. **The bridge's method-level error mapping.** Which failure code each bridge call answers when the
+1. **The bridge's method-level error mapping.** Which failure code each bridge call answers when the
    host cannot serve it — an unsupported capability, a full queue, a runtime that stopped between two
    calls — and how a page's request identifier survives the `postMessage` boundary.
 
 
@@ -37,12 +37,28 @@ export function deriveMiniAppProxyPort(pluginId: string): number {
   return PROXY_PORT_MIN + (digest.readUInt32BE(0) % PROXY_PORT_RANGE);
 }
 
+/**
+ * The page bridge the proxy injects into the Mini App's document.
+ *
+ * The proxy owns the seam — which document, where the tag goes, what headers survive — while the script
+ * itself belongs to the bridge, which knows what `window.mcode.miniapp` exposes.
+ */
+export interface MiniAppPageBridge {
+  /** Absolute path on the proxy origin that serves the script, e.g. `/__miniapp/bridge.js`. */
+  readonly path: string;
+  readonly script: string;
+}
+
 export interface StartMiniAppProxyInput {
   readonly target: MiniAppProxyTarget;
   /** Defaults to the derived port; a test or a retry may pass the next candidate. */
   readonly port?: number;
+  readonly bridge?: MiniAppPageBridge;
 }
 
+const FRAME_BLOCKING_HEADERS = ['x-frame-options'] as const;
+const CSP_HEADER = 'content-security-policy';
+
 /**
  * One loopback listener per running Mini App.
  *
@@ -62,6 +78,12 @@ export async function startMiniAppProxy(input: StartMiniAppProxyInput): Promise<
   const sockets = new Set<{ destroy(): void }>();
 
   const server = http.createServer((request, response) => {
+    if (input.bridge && request.url === input.bridge.path) {
+      response
+        .writeHead(200, { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-store' })
+        .end(input.bridge.script);
+      return;
+    }
     const forwarded = http.request(
       {
         host: upstream.hostname,
@@ -75,8 +97,28 @@ export async function startMiniAppProxy(input: StartMiniAppProxyInput): Promise<
         agent: false,
       },
       (upstreamResponse) => {
-        response.writeHead(upstreamResponse.statusCode ?? 502, upstreamResponse.headers);
-        upstreamResponse.pipe(response);
+        const headers = frameableHeaders(upstreamResponse.headers);
+        if (!isHtml(upstreamResponse.headers) || !input.bridge) {
+          response.writeHead(upstreamResponse.statusCode ?? 502, headers);
+          upstreamResponse.pipe(response);
+          return;
+        }
+        // The document is the one response this proxy rewrites: the page bridge has to be in it before
+        // the page's own scripts run, and a page cannot be allowed to decide it will not be framed.
+        const chunks: Buffer[] = [];
+        upstreamResponse.on('data', (chunk: Buffer) => chunks.push(chunk));
+        upstreamResponse.on('end', () => {
+          const body = Buffer.from(
+            injectBridge(Buffer.concat(chunks).toString('utf8'), input.bridge as MiniAppPageBridge),
+            'utf8',
+          );
+          // The body length changed, so the upstream framing no longer applies.
+          delete headers['transfer-encoding'];
+          headers['content-length'] = String(body.byteLength);
+          response.writeHead(upstreamResponse.statusCode ?? 502, headers);
+          response.end(body);
+        });
+        upstreamResponse.on('error', () => response.destroy());
       },
     );
     forwarded.on('error', () => {
@@ -147,3 +189,43 @@ export async function startMiniAppProxy(input: StartMiniAppProxyInput): Promise<
     },
   };
 }
+
+function isHtml(headers: http.IncomingHttpHeaders): boolean {
+  const contentType = headers['content-type'];
+  return typeof contentType === 'string' && contentType.toLowerCase().includes('text/html');
+}
+
+/**
+ * The page is framed by the WebUI client, on a different origin, so a page that asks not to be framed
+ * must not be able to refuse: `X-Frame-Options` is dropped and a `frame-ancestors` directive is removed
+ * from the page's own CSP. Everything else the page declares is left alone — the Mini App's origin is a
+ * separate origin from the client's, so its CSP governs a document that cannot reach the client anyway.
+ */
+function frameableHeaders(headers: http.IncomingHttpHeaders): http.OutgoingHttpHeaders {
+  const result: http.OutgoingHttpHeaders = {};
+  for (const [name, value] of Object.entries(headers)) {
+    if (FRAME_BLOCKING_HEADERS.includes(name.toLowerCase() as 'x-frame-options')) continue;
+    if (name.toLowerCase() === CSP_HEADER && typeof value === 'string') {
+      const directives = value
+        .split(';')
+        .map((directive) => directive.trim())
+        .filter((directive) => directive.length > 0 && !directive.toLowerCase().startsWith('frame-ancestors'));
+      result[name] = directives.join('; ');
+      continue;
+    }
+    result[name] = value;
+  }
+  return result;
+}
+
+function injectBridge(document: string, bridge: MiniAppPageBridge): string {
+  const tag = `<script src="${bridge.path}"></script>`;
+  const headEnd = document.search(/<\/head\s*>/iu);
+  if (headEnd >= 0) return `${document.slice(0, headEnd)}${tag}${document.slice(headEnd)}`;
+  const bodyStart = document.search(/<body[^>]*>/iu);
+  if (bodyStart >= 0) {
+    const insertAt = document.indexOf('>', bodyStart) + 1;
+    return `${document.slice(0, insertAt)}${tag}${document.slice(insertAt)}`;
+  }
+  return `${tag}${document}`;
+}
@@ -28,6 +28,20 @@ let proxy: MiniAppProxy;
 beforeAll(async () => {
   upstream = http.createServer((request, response) => {
     seen.push({ method: request.method, url: request.url, headers: { ...request.headers } });
+    if (request.url === '/page') {
+      response
+        .writeHead(200, {
+          'content-type': 'text/html; charset=utf-8',
+          'x-frame-options': 'DENY',
+          'content-security-policy': "default-src 'self'; frame-ancestors 'none'; script-src 'self'",
+        })
+        .end('<!doctype html><html><head><title>app</title></head><body>page</body></html>');
+      return;
+    }
+    if (request.url === '/bare') {
+      response.writeHead(200, { 'content-type': 'text/html' }).end('<p>no head here</p>');
+      return;
+    }
     if (request.url === '/echo') {
       response.writeHead(200, { 'content-type': 'text/plain' }).end('from-upstream');
       return;
@@ -52,6 +66,7 @@ beforeAll(async () => {
       credentialHeader: CREDENTIAL_HEADER,
     },
     port: 0,
+    bridge: { path: '/__miniapp/bridge.js', script: 'globalThis.__bridge = true;' },
   });
 });
 
@@ -142,3 +157,36 @@ describe('Mini App proxy', () => {
     expect(deriveMiniAppProxyPort('another.miniapp')).not.toBe(first);
   });
 });
+
+describe('Mini App proxy document rewrite', () => {
+  it('injects the bridge before the document head ends', async () => {
+    const result = await get(proxy.port, '/page');
+
+    expect(result.status).toBe(200);
+    expect(result.body).toContain('<script src="/__miniapp/bridge.js"></script></head>');
+    expect(result.body).toContain('<title>app</title>');
+  });
+
+  it('makes the document framable: drops X-Frame-Options and the frame-ancestors directive', async () => {
+    const result = await get(proxy.port, '/page');
+
+    expect(result.headers).not.toHaveProperty('x-frame-options');
+    expect(result.headers['content-security-policy']).toBe("default-src 'self'; script-src 'self'");
+  });
+
+  it('injects before the body when the document has no head', async () => {
+    const result = await get(proxy.port, '/bare');
+
+    expect(result.body).toBe('<script src="/__miniapp/bridge.js"></script><p>no head here</p>');
+  });
+
+  it('serves the bridge itself and never forwards that path upstream', async () => {
+    const before = seen.length;
+    const result = await get(proxy.port, '/__miniapp/bridge.js');
+
+    expect(result.status).toBe(200);
+    expect(result.body).toBe('globalThis.__bridge = true;');
+    expect(result.headers['content-type']).toContain('text/javascript');
+    expect(seen.length).toBe(before);
+  });
+});