@nowline/mcp 0.7.0 → 0.8.0

package/src/ui/entry.ts

@@ -1,44 +1,37 @@
 // Browser entry bundled into the MCP Apps in-chat live preview.
 //
-// Unlike the VS Code webview entry — which receives pre-rendered SVG from
-// the extension host over postMessage — this entry runs standalone inside
-// the MCP host's sandboxed iframe. It reads the .nowline source the server
-// injected as a JSON <script> (#nl-preview-data), renders it to SVG in the
-// browser via `renderSource` (@nowline/browser, the same parse → layout →
-// render pipeline the embed CDN ships), and mounts the shared preview
-// viewport via `mountPreview` (@nowline/preview-shell). No host transport
-// is assumed, so the preview works in any MCP Apps host that renders the
-// embedded text/html resource.
+// The MCP host loads a pre-declared ui:// HTML resource and hydrates it via the
+// ext-apps handshake. The widget mounts from the earliest signal available:
+//   1. ontoolinput  — the LLM's tool arguments, delivered before the server runs.
+//      This is the primary, fast path for the common inline-`source` case and
+//      mirrors the official ext-apps examples (e.g. mermaid-mcp-app), which paint
+//      from tool input rather than waiting on the result notification.
+//   2. ontoolresult — the lean { kind: 'nowline.preview', source, … } payload the
+//      server returns. Authoritative: it carries the resolved `source` even when
+//      the caller passed `path:` instead of `source:`, so it reconciles the input
+//      render and covers hosts that never deliver ontoolinput.
+// A #nl-preview-data JSON <script> fallback remains for the /widget-preview dev
+// shim and non-handshake degradation.
 //
-// Mirrors packages/vscode-extension/src/preview/webview/entry.ts; the seam
-// is that this entry owns the render (no host editor feeding it SVG), so
-// theme / now / show-links changes re-render in-place via renderSource.
+// Mirrors packages/vscode-extension/src/preview/webview/entry.ts; this entry
+// owns the render (no host editor feeding it SVG), so theme / now / show-links
+// changes re-render in-place.
 
 // Runs in a browser-like iframe, not Node. Pull in the DOM lib only here
 // (the rest of @nowline/mcp is Node) — mirrors the VS Code webview entry.
 /// <reference lib="dom" />
 
-import { renderSource } from '@nowline/browser';
-import {
-    mountPreview,
-    type NowOverride,
-    type PreviewHandle,
-    type ThemeOverride,
-} from '@nowline/preview-shell';
-
-/** Server-injected render inputs (see buildPreviewHtml in server.ts). */
-interface PreviewPayload {
-    source: string;
-    theme?: string;
-    now?: string;
-    width?: number;
-    locale?: string;
-    showLinks?: boolean;
-    showMinimap?: boolean;
-    initialFit?: 'fitPage' | 'fitWidth' | 'actual';
-}
+// Injected by bundle-ui.mjs at build time from package.json; not a runtime import.
+declare const __MCP_VERSION__: string;
 
-type DiagramTheme = 'light' | 'dark' | 'grayscale';
+import { App } from '@modelcontextprotocol/ext-apps';
+import { mountLivePreview } from '@nowline/preview';
+import type { NowOverride, ThemeOverride } from '@nowline/preview-shell';
+import {
+    type PreviewPayload,
+    parsePreviewFromArguments,
+    parsePreviewFromContent,
+} from './payload.js';
 
 function readPayload(): PreviewPayload | undefined {
     const el = document.getElementById('nl-preview-data');
@@ -50,7 +43,7 @@ function readPayload(): PreviewPayload | undefined {
     }
 }
 
-/** Coerce a raw theme token to the shell's ThemeOverride (defaults to Auto). */
+/** Coerce a raw theme token from the payload to the shell's ThemeOverride. */
 function toThemeOverride(theme: string | undefined): ThemeOverride {
     switch (theme) {
         case 'light':
@@ -64,106 +57,158 @@ function toThemeOverride(theme: string | undefined): ThemeOverride {
     }
 }
 
-/** Map a shell ThemeOverride to a renderer ThemeName (Auto → renderer default). */
-function toDiagramTheme(theme: ThemeOverride): DiagramTheme | undefined {
-    switch (theme) {
-        case 'light':
-            return 'light';
-        case 'dark':
-            return 'dark';
-        case 'grayscale':
-        case 'greyscale':
-            return 'grayscale';
-        default:
-            return undefined;
+let mounted = false;
+let mountedSource: string | undefined;
+
+function mountFromPayload(payload: PreviewPayload): void {
+    const root = document.getElementById('nl-preview-root');
+    if (!root || typeof payload.source !== 'string') {
+        return;
     }
+
+    // Idempotent across the ontoolinput → ontoolresult sequence: the result
+    // notification normally repeats the same `source` the input already mounted,
+    // so skip it. A genuinely different `source` (e.g. path resolution, or a
+    // re-invocation on the same iframe) tears down the prior mount first.
+    if (mounted) {
+        if (payload.source === mountedSource) return;
+        (root as HTMLElement).replaceChildren();
+    }
+
+    mountLivePreview(root as HTMLElement, {
+        source: payload.source,
+        initialView: {
+            theme: toThemeOverride(payload.theme),
+            now: (payload.now ?? 'today') as NowOverride,
+            showLinks: payload.showLinks !== false,
+        },
+        renderOptions: {
+            width: payload.width,
+            locale: payload.locale,
+        },
+        themeControl: 'show',
+        exportControls: 'hide',
+        locale: payload.locale,
+        // Inline chat widget: fill the width and take the diagram's natural
+        // height (reportHeight sizes the iframe to match), rather than fitPage
+        // which centers a width-constrained diagram and leaves empty space.
+        initialFit: payload.initialFit ?? 'fitWidth',
+        showMinimap: payload.showMinimap,
+    });
+    mounted = true;
+    mountedSource = payload.source;
+}
+
+// Sizing for a size-to-content host (Claude Desktop), which sizes the iframe
+// from our ui/notifications/size-changed. The shell is a fill-the-container
+// layout (html / body / #nl-preview-root are height:100%) with no intrinsic
+// height, so the ext-apps SDK's default autoResize — which measures
+// documentElement at `max-content` — collapses to 0 and the host shrinks the
+// iframe to nothing (blank, no console error). We disable autoResize and report
+// the *diagram's* height instead: the rendered SVG shown at fit-width, clamped
+// to the host's available height. A short roadmap stays compact (no empty band
+// pushing it below the fold); a tall one is capped and scrolls internally. User
+// zoom does not resize the iframe (the report is viewBox-based, scale-free).
+// VS Code / embed own their panel height and never mount this entry.
+const MIN_HEIGHT_PX = 160;
+const DEFAULT_MAX_HEIGHT_PX = 640;
+const PREPAINT_HEIGHT_PX = 360;
+
+function hostMaxHeight(app: App): number {
+    const dims = app.getHostContext()?.containerDimensions as
+        | { height?: number; maxHeight?: number }
+        | undefined;
+    return Math.round(dims?.maxHeight ?? dims?.height ?? DEFAULT_MAX_HEIGHT_PX);
 }
 
-/** Map a shell NowOverride to the renderSource `today` input. */
-function toToday(now: NowOverride): Date | string | null | undefined {
-    if (now === 'today') return undefined;
-    if (now === 'hide' || now === 'none') return null;
-    return now;
+/** viewBox aspect of the rendered diagram, or null before the first paint. */
+function diagramNaturalSize(): { w: number; h: number } | null {
+    const svg = document.querySelector('#nl-preview-root svg') as SVGSVGElement | null;
+    const vb = svg?.viewBox?.baseVal;
+    return vb && vb.width > 0 && vb.height > 0 ? { w: vb.width, h: vb.height } : null;
 }
 
-function bootstrap(): void {
+let lastReportedHeight = -1;
+
+function desiredHeight(app: App): number {
+    const cap = Math.max(hostMaxHeight(app), MIN_HEIGHT_PX);
+    const nat = diagramNaturalSize();
+    const width = document.documentElement.clientWidth || 0;
+    if (!nat || width <= 0) {
+        // Pre-paint, or a diagnostics-only state: a modest non-zero height.
+        return Math.min(Math.max(PREPAINT_HEIGHT_PX, MIN_HEIGHT_PX), cap);
+    }
+    // Fit-width display height = naturalHeight × (width / naturalWidth).
+    const fitHeight = Math.ceil(nat.h * (width / nat.w));
+    return Math.min(Math.max(fitHeight, MIN_HEIGHT_PX), cap);
+}
+
+function reportHeight(app: App): void {
+    const height = desiredHeight(app);
+    if (height === lastReportedHeight) return;
+    lastReportedHeight = height;
+    // Concrete base for the height:100% chain (so the fill layout paints) and the
+    // height the host should give the iframe.
+    document.documentElement.style.height = `${height}px`;
+    void app.sendSizeChanged({ height });
+}
+
+function watchSize(app: App): void {
     const root = document.getElementById('nl-preview-root');
-    if (!root) {
-        console.error('nowline mcp preview: #nl-preview-root missing');
-        return;
+    if (!root) return;
+    let scheduled = false;
+    const trigger = (): void => {
+        if (scheduled) return;
+        scheduled = true;
+        requestAnimationFrame(() => {
+            scheduled = false;
+            reportHeight(app);
+        });
+    };
+    // Re-measure when the diagram (re)renders into the canvas…
+    if (typeof MutationObserver !== 'undefined') {
+        new MutationObserver(trigger).observe(root, { childList: true, subtree: true });
     }
-    const payload = readPayload();
-    if (!payload || typeof payload.source !== 'string') {
-        return;
+    // …and when the host changes our width.
+    if (typeof ResizeObserver !== 'undefined') {
+        new ResizeObserver(trigger).observe(root);
     }
-    const { source, width, locale } = payload;
-
-    // Live view state — seeded from the server payload, mutated by the
-    // shell's view-options menu, and read on every re-render.
-    const current = {
-        theme: toThemeOverride(payload.theme),
-        now: (payload.now ?? 'today') as NowOverride,
-        showLinks: payload.showLinks !== false,
+}
+
+async function bootstrap(): Promise<void> {
+    // autoResize:false — see the sizing block above.
+    const app = new App(
+        { name: 'NowlinePreview', version: __MCP_VERSION__ },
+        {},
+        { autoResize: false },
+    );
+
+    // Primary path: paint from the LLM's tool arguments the moment they arrive,
+    // before the server finishes rendering. Mirrors the official ext-apps examples.
+    app.ontoolinput = ({ arguments: args }) => {
+        const payload = parsePreviewFromArguments(args as Record<string, unknown> | undefined);
+        if (payload) mountFromPayload(payload);
     };
 
-    let handle: PreviewHandle | undefined;
-
-    async function render(): Promise<void> {
-        if (!handle) return;
-        try {
-            const result = await renderSource(source, {
-                theme: toDiagramTheme(current.theme),
-                today: toToday(current.now),
-                width,
-                locale,
-                showLinks: current.showLinks,
-            });
-            if (result.kind === 'svg') {
-                handle.setSvg(result.svg);
-                handle.setDiagnostics(result.warnings);
-            } else {
-                handle.setDiagnostics(result.diagnostics);
-            }
-        } catch (err) {
-            handle.setFatal(err instanceof Error ? err.message : String(err));
-        }
-    }
+    // Authoritative path: the server-resolved lean preview payload. Reconciles the
+    // input render and covers the `path:`-only case and hosts without ontoolinput.
+    app.ontoolresult = ({ content, isError }) => {
+        if (isError) return;
+        const payload = parsePreviewFromContent(content);
+        if (payload) mountFromPayload(payload);
+    };
 
-    handle = mountPreview(root, {
-        themeControl: 'show',
-        locale,
-        initialFit: payload.initialFit,
-        showMinimap: payload.showMinimap,
-        viewBaseline: {
-            theme: current.theme,
-            now: current.now,
-            showLinks: current.showLinks,
-        },
-        onViewOptions: (overrides) => {
-            if (overrides.theme !== undefined) current.theme = overrides.theme;
-            if (overrides.now !== undefined) current.now = overrides.now;
-            if (overrides.showLinks !== undefined) current.showLinks = overrides.showLinks;
-            void render();
-        },
-        onSave: (req) => {
-            // Best-effort in-iframe download; the host's iframe sandbox may
-            // block it, in which case the copy actions remain available.
-            try {
-                const type = req.format === 'png' ? 'image/png' : 'image/svg+xml';
-                const blob = new Blob([req.body as BlobPart], { type });
-                const url = URL.createObjectURL(blob);
-                const a = document.createElement('a');
-                a.href = url;
-                a.download = `roadmap.${req.format}`;
-                a.click();
-                setTimeout(() => URL.revokeObjectURL(url), 1000);
-            } catch {
-                // Download blocked by the sandbox — nothing to do.
-            }
-        },
-    });
+    // Re-report when the host changes our width / available height.
+    app.onhostcontextchanged = () => reportHeight(app);
 
-    void render();
+    await app.connect();
+    watchSize(app);
+    reportHeight(app);
+
+    if (!mounted) {
+        const fallback = readPayload();
+        if (fallback) mountFromPayload(fallback);
+    }
 }
 
-bootstrap();
+void bootstrap();

package/src/ui/payload.ts

@@ -0,0 +1,63 @@
+// Pure helpers shared by the MCP Apps preview entry (src/ui/entry.ts).
+//
+// Kept DOM-free and side-effect-free so they are unit-testable in Node: entry.ts
+// runs bootstrap() on import and touches the iframe DOM, so its logic can't be
+// imported directly under Vitest. The widget derives its render inputs from two
+// ext-apps signals — tool arguments (ontoolinput) and the tool result
+// (ontoolresult) — and both mappings live here.
+
+/** Server-injected or per-call render inputs for the live preview. */
+export interface PreviewPayload {
+    kind?: string;
+    source: string;
+    theme?: string;
+    now?: string;
+    width?: number;
+    locale?: string;
+    showLinks?: boolean;
+    showMinimap?: boolean;
+    initialFit?: 'fitPage' | 'fitWidth' | 'actual';
+}
+
+/**
+ * Extract the lean `{ kind: 'nowline.preview', source, … }` payload from a tool
+ * result's content blocks (the `ontoolresult` notification). This is the
+ * authoritative path: the server resolves `path:` → `source` before emitting it.
+ */
+export function parsePreviewFromContent(
+    content: Array<{ type: string; text?: string }> | undefined,
+): PreviewPayload | undefined {
+    if (!content) return undefined;
+    for (const block of content) {
+        if (block.type !== 'text' || !block.text) continue;
+        try {
+            const parsed = JSON.parse(block.text) as PreviewPayload;
+            if (parsed.kind === 'nowline.preview' && typeof parsed.source === 'string') {
+                return parsed;
+            }
+        } catch {
+            /* not JSON — skip */
+        }
+    }
+    return undefined;
+}
+
+/**
+ * Build a preview payload from the LLM's raw `render` tool arguments
+ * (the `ontoolinput` notification). Only viable for the inline-`source` case —
+ * when the caller passed `path:` instead, the file can't be read in the iframe,
+ * so we return undefined and wait for `ontoolresult` (which carries the
+ * server-resolved `source`). Locale mirrors the server default (`en-US`).
+ */
+export function parsePreviewFromArguments(
+    args: Record<string, unknown> | undefined,
+): PreviewPayload | undefined {
+    if (!args || typeof args.source !== 'string') return undefined;
+    return {
+        source: args.source,
+        theme: typeof args.theme === 'string' ? args.theme : undefined,
+        now: typeof args.now === 'string' ? args.now : undefined,
+        width: typeof args.width === 'number' ? args.width : undefined,
+        locale: 'en-US',
+    };
+}