test(mcp-server): get_selection wiring test expects the classic page's answer when the shell is not built

The reminder step left out the root lockfile and scripts/, which change
what is bundled into the shell and trigger the publish workflow; and it
took any change of packages/mcp-server/package.json (a dependency bump)
for a version bump. It now compares the version field between the two
commits.

.github/workflows/publish-mcp.yml

@@ -1,7 +1,8 @@
 name: Publish MCP Server
 
 # Publishes @next-ai-drawio/mcp-server to npm via OIDC trusted publishing
-# (no token, no OTP). Triggers when packages/mcp-server changes on main;
+# (no token, no OTP). Triggers when packages/mcp-server or the web app code
+# bundled into the canvas shell (scripts/build-shell.mjs) changes on main;
 # skips silently if the package.json version is already on npm — so a
 # release is just "bump the version in a PR and merge".
 on:
@@ -10,6 +11,16 @@ on:
       - main
     paths:
       - "packages/mcp-server/**"
+      # The canvas shell is bundled from these with the root's lockfile
+      - "components/**"
+      - "contexts/**"
+      - "hooks/**"
+      - "lib/**"
+      - "stores/**"
+      - "app/globals.css"
+      - "package-lock.json"
+      # The package's build scripts import the root's scripts/drawio-zip.mjs
+      - "scripts/**"
   workflow_dispatch:
 
 permissions:
@@ -35,7 +46,9 @@ jobs:
         with:
           node-version: 24
           cache: "npm"
-          cache-dependency-path: packages/mcp-server/package-lock.json
+          cache-dependency-path: |
+            package-lock.json
+            packages/mcp-server/package-lock.json
           registry-url: "https://registry.npmjs.org"
 
       # Trusted publishing requires npm >= 11.5.1
@@ -54,6 +67,13 @@ jobs:
             echo "publish=true" >> "$GITHUB_OUTPUT"
           fi
 
+      # The canvas shell (scripts/build-shell.mjs) is bundled from the web
+      # app's components with the root's esbuild, Tailwind and React
+      - name: Install repository dependencies
+        if: steps.version.outputs.publish == 'true'
+        working-directory: .
+        run: npm ci
+
       - name: Install dependencies
         if: steps.version.outputs.publish == 'true'
         run: npm ci
@@ -62,6 +82,9 @@ jobs:
         if: steps.version.outputs.publish == 'true'
         run: npm test
 
+      # The build downloads the pinned draw.war from GitHub releases
+      # (scripts/fetch-drawio.mjs) and bundles a trimmed draw.io into
+      # dist/drawio; check-package confirms it is in the tarball
       - name: Build and check package contents
         if: steps.version.outputs.publish == 'true'
         run: npm run build && npm run check-package

.github/workflows/test.yml

@@ -28,20 +28,104 @@ jobs:
       - name: Run unit tests
         run: npm run test -- --run
 
-      # The MCP server package ships its own vitest because its DOM polyfill
-      # (linkedom) needs `environment: node`, while the root vitest uses jsdom
-      # for the Next.js app. Install + run its tests separately so CI catches
-      # multi-page mxfile regressions.
+  # The MCP server package: its own vitest (its DOM polyfill, linkedom, needs
+  # `environment: node`, while the root vitest uses jsdom for the Next.js
+  # app), the npm package as it is built, the draw.io file list, and the
+  # canvas shell in a browser.
+  mcp-shell:
+    name: MCP Server & Shell
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          # HEAD^1 is the base branch for the version bump reminder below
+          fetch-depth: 2
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: |
+            package-lock.json
+            packages/mcp-server/package-lock.json
+
+      # The shell is bundled from the web app's components with the root's
+      # esbuild, Tailwind and React; Playwright comes from the root too
+      - name: Install dependencies
+        run: npm ci
+
       - name: Install MCP server dependencies
         run: npm --prefix packages/mcp-server ci
 
+      - name: Cache Playwright browsers
+        uses: actions/cache@v5
+        id: playwright-cache
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
+
+      - name: Install Playwright browsers
+        if: steps.playwright-cache.outputs.cache-hit != 'true'
+        run: npx playwright install chromium --with-deps
+
+      - name: Install Playwright deps (cached)
+        if: steps.playwright-cache.outputs.cache-hit == 'true'
+        run: npx playwright install-deps chromium
+
       - name: Run MCP server unit tests
         run: npm --prefix packages/mcp-server test
 
-      # Tests run from src/, so check the built npm package separately
+      # Tests run from src/, so check the built npm package separately. The
+      # build downloads the pinned draw.war and bundles a trimmed draw.io.
       - name: Build MCP server and check package contents
         run: npm --prefix packages/mcp-server run build && npm --prefix packages/mcp-server run check-package
 
+      # The trimmed draw.io is cut from this list; the guard drives the full
+      # copy (public/drawio) in Chromium and fails when the editor requests a
+      # file the list does not have
+      - name: Download the full draw.io
+        run: node scripts/fetch-drawio.mjs
+
+      - name: Check the MCP draw.io file list
+        run: npm --prefix packages/mcp-server run check-drawio
+
+      # The canvas shell in a browser, from the package as npm installs it:
+      # the packed tarball goes into an empty directory, its dist/index.js is
+      # started over stdio and headless Chromium opens the URL start_session
+      # returns (packages/mcp-server/tests/e2e)
+      - name: Run the MCP shell E2E tests on the packed tarball
+        run: |
+          mkdir -p "$RUNNER_TEMP/mcp-pack" "$RUNNER_TEMP/mcp-install"
+          npm pack ./packages/mcp-server --pack-destination "$RUNNER_TEMP/mcp-pack"
+          npm --prefix "$RUNNER_TEMP/mcp-install" install "$RUNNER_TEMP"/mcp-pack/*.tgz
+          MCP_SERVER_ENTRY="$RUNNER_TEMP/mcp-install/node_modules/@next-ai-drawio/mcp-server/dist/index.js" \
+            npm --prefix packages/mcp-server run test:e2e
+        env:
+          CI: true
+
+      # The shell bundles the web app's canvas and the root's dependencies,
+      # so a change under these paths (the ones publish-mcp.yml triggers on)
+      # reaches users with the next MCP release, and publish-mcp.yml only
+      # publishes a new version number
+      - name: Remind to bump the MCP version when bundled code changed
+        if: github.event_name == 'pull_request'
+        run: |
+          changed=$(git diff --name-only HEAD^1 HEAD -- components contexts hooks lib stores app/globals.css package-lock.json scripts packages/mcp-server)
+          base_version=$(git show HEAD^1:packages/mcp-server/package.json | node -p "JSON.parse(require('fs').readFileSync(0, 'utf8')).version")
+          head_version=$(node -p "require('./packages/mcp-server/package.json').version")
+          if [ -n "$changed" ] && [ "$base_version" = "$head_version" ]; then
+            echo "::warning::Code bundled into the MCP server changed without a version bump in packages/mcp-server/package.json (still ${head_version}). Bump it if the change should be published."
+          fi
+
+      - name: Upload test results
+        uses: actions/upload-artifact@v6
+        if: always()
+        with:
+          name: playwright-report-mcp-shell
+          path: packages/mcp-server/test-results/
+          retention-days: 7
+
   e2e:
     # Six jobs at once, each with a sixth of the tests and one worker: the
     # same conditions per test, a fraction of the time

.github/workflows/wait-for-confirmation.yml

@@ -0,0 +1,55 @@
+# Issues labelled "wait for confrim" are waiting for the reporter. After 15
+# days without activity the issue gets a reminder and the "no response"
+# label; after 15 more days it is closed. A reply from the reporter removes
+# both labels, so the issue shows up as needing the maintainer again.
+name: Wait for confirmation
+
+on:
+  schedule:
+    - cron: "17 3 * * *"
+  workflow_dispatch:
+  issue_comment:
+    types: [created]
+
+permissions:
+  issues: write
+
+jobs:
+  remind-and-close:
+    if: github.event_name != 'issue_comment'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/stale@v9
+        with:
+          only-issue-labels: "wait for confrim"
+          days-before-issue-stale: 15
+          days-before-issue-close: 15
+          days-before-pr-stale: -1
+          days-before-pr-close: -1
+          stale-issue-label: "no response"
+          stale-issue-message: >-
+            Still there? We asked for more information 15 days ago. A reply
+            would help; if we hear nothing in another 15 days this issue will
+            be closed. It can be reopened any time.
+          close-issue-message: >-
+            No reply in 30 days, so this issue is closed for now. If the
+            problem is still there, reply or reopen it.
+          close-issue-reason: not_planned
+          remove-stale-when-updated: true
+
+  reporter-replied:
+    if: >-
+      github.event_name == 'issue_comment' &&
+      contains(github.event.issue.labels.*.name, 'wait for confrim') &&
+      github.event.comment.user.type != 'Bot' &&
+      !contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)
+    runs-on: ubuntu-latest
+    steps:
+      - name: The reporter answered, so the issue is the maintainer's again
+        run: >-
+          gh issue edit "$NUMBER" --repo "$REPO"
+          --remove-label "wait for confrim" --remove-label "no response"
+        env:
+          GH_TOKEN: ${{ github.token }}
+          NUMBER: ${{ github.event.issue.number }}
+          REPO: ${{ github.repository }}

.gitignore

@@ -16,6 +16,8 @@ packages/*/dist
 /coverage
 /playwright-report/
 /test-results/
+packages/*/playwright-report/
+packages/*/test-results/
 
 # next.js
 /.next/

README.md

@@ -114,9 +114,12 @@ claude mcp add drawio -- npx @next-ai-drawio/mcp-server@latest
 Then ask the AI for "a flowchart of user authentication with login, MFA and session management" and the diagram appears in your browser as it is drawn. The MCP server has most of the web app's drawing features:
 
 -   The same drawing rules and icon libraries (AWS, Azure, GCP, Kubernetes and more)
+-   The preview is the same canvas as the web app: the AI's changes are outlined, one Ctrl+Z takes them back, and the AI can read the shapes you select
+-   The draw.io editor ships inside the package, so after install the preview works offline (`DRAWIO_BASE_URL` points it at an external draw.io instead)
 -   A screenshot tool, so the AI can look at the rendered diagram and fix it
 -   Version history, multi-page diagrams, and download as `.drawio`, `.png`, `.svg` or `.drawio.svg`
 -   Auto-save to `~/.next-ai-drawio/`, so a diagram survives a restart
+-   Ask the AI to undo, and keep your own drawing rules in `~/.next-ai-drawio/instructions.md`
 
 See the [MCP server README](./packages/mcp-server/README.md) for VS Code, Cursor and other client configurations.
 

app/[lang]/layout.tsx

@@ -3,6 +3,7 @@ import type { Metadata, Viewport } from "next"
 import { Instrument_Sans, JetBrains_Mono } from "next/font/google"
 import { notFound } from "next/navigation"
 import Script from "next/script"
+import { LocaleProvider } from "@/components/canvas/locale-context"
 import { AppToaster } from "@/components/workspace/app-toaster"
 import { DiagramProvider } from "@/contexts/diagram-context"
 import { DictionaryProvider } from "@/hooks/use-dictionary"
@@ -184,7 +185,9 @@ export default async function RootLayout({
                 className={`${instrumentSans.variable} ${jetbrainsMono.variable} antialiased`}
             >
                 <DictionaryProvider dictionary={dictionary}>
-                    <DiagramProvider>{children}</DiagramProvider>
+                    <LocaleProvider locale={validLang}>
+                        <DiagramProvider>{children}</DiagramProvider>
+                    </LocaleProvider>
                 </DictionaryProvider>
                 <AppToaster />
             </body>

biome.json

@@ -11,6 +11,7 @@
             "**",
             "!public",
             "!packages/mcp-server/src/preview",
+            "!packages/mcp-server/shell/index.html",
             "!lib/model-catalog.json"
         ]
     },

components/canvas/canvas-stage.tsx

@@ -1,11 +1,14 @@
-import { useParams } from "next/navigation"
 import { useEffect, useRef, useState } from "react"
 import { DrawioFrame } from "@/components/canvas/drawio-frame"
-import { SelectionAsk } from "@/components/canvas/selection-ask"
-import { useChatEngine } from "@/components/chat/chat-engine"
+import { useLocale } from "@/components/canvas/locale-context"
 import { useDiagram } from "@/contexts/diagram-context"
 import { useDictionary } from "@/hooks/use-dictionary"
-import { DRAWIO_CSS, getDrawioSrc } from "@/lib/drawio/drawio-config"
+import {
+    DRAWIO_CSS,
+    type DrawioSource,
+    getDrawioSrc,
+    webDrawioSource,
+} from "@/lib/drawio/drawio-config"
 import { keepCenter, refitIfRecent } from "@/lib/drawio/editor-bridge"
 import { i18n, type Locale } from "@/lib/i18n/config"
 import { STORAGE_KEYS } from "@/lib/storage"
@@ -13,28 +16,42 @@ import { cn } from "@/lib/utils"
 import { useCanvasStore } from "@/stores/canvas-store"
 import { useSettingsStore } from "@/stores/settings-store"
 
+/** Size of the canvas area, for overlays that stay inside it */
+export interface CanvasSize {
+    width: number
+    height: number
+}
+
 /**
  * The draw.io canvas, with draw.io's own toolbar, menus and page tabs, and
- * the "ask AI" button laid over it (only when the page can drive draw.io
- * directly, not with an external cross-origin draw.io).
+ * an overlay laid over it (the web app's "ask AI" button; only when the
+ * page can drive draw.io directly, not with an external cross-origin
+ * draw.io).
  */
 export function CanvasStage({
     className,
     style,
     hideOverlays = false,
+    overlay,
+    drawioSource,
+    waitForSavedLocale = false,
 }: {
     className?: string
     style?: React.CSSProperties
-    /** Hide the "ask AI" button (e.g. while the start screen covers the canvas) */
+    /** Hide the overlay (e.g. while the start screen covers the canvas) */
     hideOverlays?: boolean
+    /** Rendered over the canvas once draw.io is ready */
+    overlay?: (size: CanvasSize) => React.ReactNode
+    /** Where the editor comes from; none: the web app's own copy (the MCP
+     * shell passes what its server configured) */
+    drawioSource?: DrawioSource
+    /** Web app: the page is about to switch to the language picked last
+     * time (useSavedLocale in the workspace); do not load draw.io in the
+     * URL's language meanwhile */
+    waitForSavedLocale?: boolean
 }) {
     const dict = useDictionary()
-    const params = useParams<{ lang: string }>()
-    const lang = (
-        i18n.locales.includes(params.lang as Locale)
-            ? params.lang
-            : i18n.defaultLocale
-    ) as Locale
+    const lang = useLocale()
     const {
         drawioRef,
         handleDiagramAutoSave,
@@ -43,7 +60,6 @@ export function CanvasStage({
         resetDrawioReady,
         isDrawioReady,
     } = useDiagram()
-    const engine = useChatEngine()
     const isDark = useSettingsStore((s) => s.isDark)
     const hasEditor = useCanvasStore((s) => s.hasEditor)
     // Canvas width when the chat panel starts sliding in or out
@@ -53,20 +69,24 @@ export function CanvasStage({
     // null until draw.io tells us whether we can drive it directly
     const [editorAccess, setEditorAccess] = useState<boolean | null>(null)
     const stageRef = useRef<HTMLDivElement>(null)
-    const [size, setSize] = useState({ width: 0, height: 0 })
+    const [size, setSize] = useState<CanvasSize>({ width: 0, height: 0 })
 
     useEffect(() => {
-        // The page is about to switch to the language picked last time
-        // (useSavedLocale): load draw.io once, in that language
-        const saved = localStorage.getItem(STORAGE_KEYS.locale)
-        if (saved && saved !== lang && i18n.locales.includes(saved as Locale)) {
-            return
+        // Load draw.io once, in the language the page will have
+        if (waitForSavedLocale) {
+            const saved = localStorage.getItem(STORAGE_KEYS.locale)
+            if (
+                saved &&
+                saved !== lang &&
+                i18n.locales.includes(saved as Locale)
+            ) {
+                return
+            }
         }
-        const isElectron = !!(window as { electronAPI?: unknown }).electronAPI
         // The theme class is set before the page renders; the settings store
         // may not have read it yet
         const dark = document.documentElement.classList.contains("dark")
-        setSrc(getDrawioSrc({ lang, isElectron, dark }))
+        setSrc(getDrawioSrc(drawioSource ?? webDrawioSource(lang), dark))
     }, [lang])
 
     // A new iframe starts over: draw.io reports load and access again
@@ -82,8 +102,7 @@ export function CanvasStage({
         if (editorAccess !== false || !src) return
         const startedDark = new URL(src).searchParams.get("dark") === "1"
         if (startedDark === isDark) return
-        const isElectron = !!(window as { electronAPI?: unknown }).electronAPI
-        setSrc(getDrawioSrc({ lang, isElectron, dark: isDark }))
+        setSrc(getDrawioSrc(drawioSource ?? webDrawioSource(lang), isDark))
     }, [isDark, editorAccess, lang, src])
 
     useEffect(() => {
@@ -159,13 +178,7 @@ export function CanvasStage({
                 </div>
             )}
 
-            {showOverlays && (
-                <SelectionAsk
-                    width={size.width}
-                    height={size.height}
-                    hidden={engine.isBusy}
-                />
-            )}
+            {showOverlays && overlay?.(size)}
         </div>
     )
 }

components/canvas/compare-dialog.tsx

@@ -1,5 +1,7 @@
 import { ChevronLeft, ChevronRight, RotateCcw } from "lucide-react"
 import { useEffect, useMemo, useState } from "react"
+import { VersionThumb } from "@/components/canvas/version-card"
+import { useVersionsContext } from "@/components/canvas/versions-context"
 import {
     Dialog,
     DialogContent,
@@ -11,11 +13,8 @@ import { useDiagram } from "@/contexts/diagram-context"
 import { useDictionary } from "@/hooks/use-dictionary"
 import { diffDiagrams, isSameDocument } from "@/lib/diagram-diff"
 import { formatMessage } from "@/lib/i18n/utils"
-import { describeChanges } from "@/lib/version-text"
+import { describeChangeSummary } from "@/lib/version-text"
 import { useUiStore } from "@/stores/ui-store"
-import { useVersionsStore } from "@/stores/versions-store"
-import { useChatEngine } from "./chat-engine"
-import { VersionThumb } from "./tool-activity"
 
 function Sheet({
     label,
@@ -40,12 +39,11 @@ function Sheet({
 export function CompareDialog() {
     const dict = useDictionary()
     const t = dict.versions
-    const engine = useChatEngine()
+    const { versions, isBusy, restore } = useVersionsContext()
     const { getVersionSvg, chartXML } = useDiagram()
     const versionId = useUiStore((s) => s.compareVersionId)
     const openCompare = useUiStore((s) => s.openCompare)
     const closeCompare = useUiStore((s) => s.closeCompare)
-    const versions = useVersionsStore((s) => s.versions)
     const [currentSvg, setCurrentSvg] = useState<string | null>(null)
 
     const index = versions.findIndex((v) => v.id === versionId)
@@ -82,7 +80,7 @@ export function CompareDialog() {
         return () => {
             cancelled = true
         }
-    }, [versionId, engine.isBusy])
+    }, [versionId, isBusy])
 
     return (
         <Dialog
@@ -98,7 +96,7 @@ export function CompareDialog() {
                             : same
                               ? t.isOnCanvas
                               : changes
-                                ? `${formatMessage(t.compareSince, { n: version.number })} ${describeChanges(changes, t)}`
+                                ? `${formatMessage(t.compareSince, { n: version.number })} ${describeChangeSummary(changes, t)}`
                                 : formatMessage(t.differsElsewhere, {
                                       n: version.number,
                                   })}
@@ -139,10 +137,10 @@ export function CompareDialog() {
                     </span>
                     <button
                         type="button"
-                        disabled={!version || same || engine.isBusy}
+                        disabled={!version || same || isBusy}
                         onClick={() => {
                             if (!version) return
-                            engine.restoreVersion(version.id)
+                            restore(version.id)
                             closeCompare()
                         }}
                         className="ml-auto inline-flex h-9 items-center gap-1.5 rounded-lg bg-primary px-3.5 text-[13px] font-medium text-primary-foreground hover:opacity-90 disabled:opacity-40"

components/canvas/locale-context.tsx

@@ -0,0 +1,29 @@
+"use client"
+
+import { createContext, useContext } from "react"
+import type { Locale } from "@/lib/i18n/config"
+
+const LocaleContext = createContext<Locale | null>(null)
+
+/** The page's language; the web layout feeds it from its route param */
+export function LocaleProvider({
+    locale,
+    children,
+}: {
+    locale: Locale
+    children: React.ReactNode
+}) {
+    return (
+        <LocaleContext.Provider value={locale}>
+            {children}
+        </LocaleContext.Provider>
+    )
+}
+
+export function useLocale(): Locale {
+    const locale = useContext(LocaleContext)
+    if (!locale) {
+        throw new Error("useLocale must be used within a LocaleProvider")
+    }
+    return locale
+}

components/canvas/selection-ask.tsx

@@ -10,25 +10,25 @@ const GAP = 10
 /**
  * "Ask AI to change this" next to the selected shapes. Clicking it moves
  * focus to the chat input, where the selection already shows as a chip.
+ * Hidden while an answer is changing the canvas.
  */
 export function SelectionAsk({
     width,
     height,
-    hidden,
 }: {
     /** Size of the canvas area, for keeping the button inside it */
     width: number
     height: number
-    hidden: boolean
 }) {
     const dict = useDictionary()
     const rect = useCanvasStore((s) => s.selectionRect)
     const selection = useCanvasStore((s) => s.selection)
     const isFreehand = useCanvasStore((s) => s.isFreehand)
     const popupOpen = useCanvasStore((s) => s.isDrawioPopupOpen)
+    const isBusy = useCanvasStore((s) => s.isBusy)
     const focusComposer = useUiStore((s) => s.focusComposer)
 
-    if (hidden || popupOpen || !rect || selection.length === 0 || isFreehand) {
+    if (isBusy || popupOpen || !rect || selection.length === 0 || isFreehand) {
         return null
     }
     // Selection scrolled out of view

components/canvas/version-card.tsx

@@ -0,0 +1,217 @@
+import { Redo2, RotateCcw, Undo2 } from "lucide-react"
+import { Shimmer } from "@/components/ai-elements/shimmer"
+import {
+    useVersionsContext,
+    type VersionItem,
+} from "@/components/canvas/versions-context"
+import { useDictionary } from "@/hooks/use-dictionary"
+import { formatMessage } from "@/lib/i18n/utils"
+import { cn } from "@/lib/utils"
+import { describeChangeSummary, describeTotals } from "@/lib/version-text"
+import { useUiStore } from "@/stores/ui-store"
+
+/** Picture of a version (SVG data URL), or what stands in for it */
+export function VersionThumb({
+    svg,
+    dimmed,
+    className,
+}: {
+    /** undefined or null: still being made; "": none could be made */
+    svg: string | null | undefined
+    dimmed?: boolean
+    className?: string
+}) {
+    const t = useDictionary().versions
+    if (svg) {
+        return (
+            // biome-ignore lint/performance/noImgElement: data URL thumbnail
+            <img
+                src={svg}
+                alt=""
+                className={cn(
+                    "object-contain transition-opacity",
+                    dimmed && "opacity-40",
+                    className,
+                )}
+            />
+        )
+    }
+    if (svg === "") {
+        return <span className="text-xs text-faint">{t.noPreview}</span>
+    }
+    return (
+        <Shimmer as="span" className="text-xs">
+            {t.rendering}
+        </Shimmer>
+    )
+}
+
+interface VersionCardProps extends React.ComponentProps<"div"> {
+    version: VersionItem
+    /** The newest version shows its picture; older ones fold into one row */
+    isLatest: boolean
+    /** What happened ("Drew the diagram"); an undone change says so instead */
+    label: string
+    /** Goes after the summary text (the chat adds its "Show XML" link) */
+    afterSummary?: React.ReactNode
+    /** Panel below the card (the chat shows the AI's XML there) */
+    children?: React.ReactNode
+}
+
+/**
+ * Card for one diagram version: picture, number, label, what changed, and
+ * the action (undo or redo on the latest, restore on older ones). The
+ * picture opens Compare. Other attributes go on the card's element.
+ */
+export function VersionCard({
+    version,
+    isLatest,
+    label,
+    afterSummary,
+    children,
+    className,
+    ...rest
+}: VersionCardProps) {
+    const t = useDictionary().versions
+    const source = useVersionsContext()
+    const openCompare = useUiStore((s) => s.openCompare)
+
+    const isUndone = source.undoneId === version.id
+    const isOnCanvas = source.onCanvasId === version.id
+    const title = isUndone ? t.undone : label
+    const summary = version.fromScratch
+        ? describeTotals(version.summary, t)
+        : describeChangeSummary(version.summary, t)
+    const badge = (
+        <span
+            className={cn(
+                "shrink-0 rounded-md px-1.5 py-0.5 text-[11px] font-semibold tabular-nums",
+                isOnCanvas
+                    ? "bg-marker-soft text-marker-ink"
+                    : "bg-muted text-muted-foreground",
+            )}
+        >
+            v{version.number}
+        </span>
+    )
+    const actionClass =
+        "inline-flex h-7 shrink-0 items-center gap-1 rounded-lg px-2 text-xs text-muted-foreground hover:bg-accent hover:text-foreground disabled:opacity-40"
+    const restoreButton = (
+        <button
+            type="button"
+            disabled={source.isBusy || isOnCanvas}
+            onClick={() => source.restore(version.id)}
+            className={actionClass}
+            data-testid="version-restore"
+        >
+            <RotateCcw className="size-3.5" />
+            {formatMessage(t.restoreVersion, { n: version.number })}
+        </button>
+    )
+    const summaryLine = (
+        <div className="text-xs text-muted-foreground">
+            {summary}
+            {afterSummary}
+        </div>
+    )
+
+    if (!isLatest) {
+        return (
+            <div
+                className={cn(
+                    "overflow-hidden rounded-xl border border-border bg-card",
+                    className,
+                )}
+                data-testid="version-card"
+                {...rest}
+            >
+                <div className="flex items-center gap-2.5 p-1.5 pr-2">
+                    <button
+                        type="button"
+                        onClick={() => openCompare(version.id)}
+                        className="sheet-light flex h-9 w-14 shrink-0 items-center justify-center overflow-hidden rounded-md border border-border bg-white hover:border-foreground/30"
+                        aria-label={t.compare}
+                        title={t.compare}
+                    >
+                        <VersionThumb
+                            svg={version.svg}
+                            className="max-h-8 max-w-[52px]"
+                        />
+                    </button>
+                    {badge}
+                    <div className="min-w-0 flex-1">
+                        <div className="truncate text-[13px] text-foreground">
+                            {title}
+                        </div>
+                        {summaryLine}
+                    </div>
+                    {restoreButton}
+                </div>
+                {children}
+            </div>
+        )
+    }
+
+    // Undo and redo belong to the newest change while it is (or was) on
+    // the canvas; after an older version was restored, this one is
+    // restored too
+    const canUndo = source.canUndo || source.canRedo
+    return (
+        <div
+            className={cn(
+                "overflow-hidden rounded-xl border border-border bg-card",
+                isOnCanvas && "border-foreground/15",
+                className,
+            )}
+            data-testid="version-card"
+            {...rest}
+        >
+            <button
+                type="button"
+                onClick={() => openCompare(version.id)}
+                className="group/thumb sheet-light relative flex h-24 w-full items-center justify-center border-b border-border bg-white"
+                aria-label={t.compare}
+            >
+                <VersionThumb
+                    svg={version.svg}
+                    dimmed={isUndone}
+                    className="max-h-20 max-w-[88%]"
+                />
+                <span className="absolute right-2 bottom-2 rounded-md bg-black/60 px-1.5 py-0.5 text-[11px] text-white opacity-0 transition-opacity group-hover/thumb:opacity-100">
+                    {t.compare}
+                </span>
+            </button>
+            {/* Title row with the action; the summary runs under both */}
+            <div className="grid grid-cols-[auto_minmax(0,1fr)_auto] items-center gap-x-2.5 px-3 py-2.5">
+                {badge}
+                <div className="truncate text-[13px] font-medium text-foreground">
+                    {title}
+                </div>
+                {canUndo ? (
+                    <button
+                        type="button"
+                        disabled={source.isBusy}
+                        onClick={() =>
+                            source.canRedo ? source.redo() : source.undo()
+                        }
+                        className={actionClass}
+                        data-testid="version-undo"
+                    >
+                        {source.canRedo ? (
+                            <Redo2 className="size-3.5" />
+                        ) : (
+                            <Undo2 className="size-3.5" />
+                        )}
+                        {source.canRedo ? t.redo : t.undo}
+                    </button>
+                ) : (
+                    restoreButton
+                )}
+                <div className="col-span-2 col-start-2 mt-0.5">
+                    {summaryLine}
+                </div>
+            </div>
+            {children}
+        </div>
+    )
+}

components/canvas/version-strip.tsx

@@ -1,17 +1,20 @@
 import { useEffect, useRef } from "react"
+import { useVersionsContext } from "@/components/canvas/versions-context"
 import { useDictionary } from "@/hooks/use-dictionary"
 import { cn } from "@/lib/utils"
 import { useUiStore } from "@/stores/ui-store"
-import { useVersionsStore } from "@/stores/versions-store"
-import { useChatEngine } from "./chat-engine"
 
 /** Row of version thumbnails under the panel header; click to compare */
-export function VersionStrip() {
+export function VersionStrip({
+    minVersions = 2,
+}: {
+    /** Hidden below this many versions: one version alone adds nothing to
+     * its card, unless the caller knows there is no card for it */
+    minVersions?: number
+}) {
     const dict = useDictionary()
-    const versions = useVersionsStore((s) => s.versions)
-    const onCanvasVersionId = useVersionsStore((s) => s.onCanvasVersionId)
+    const { versions, onCanvasId } = useVersionsContext()
     const openCompare = useUiStore((s) => s.openCompare)
-    const engine = useChatEngine()
     const scrollRef = useRef<HTMLDivElement>(null)
 
     // Keep the newest version in view
@@ -20,24 +23,7 @@ export function VersionStrip() {
         if (el) el.scrollTo({ left: el.scrollWidth, behavior: "smooth" })
     }, [versions.length])
 
-    // Versions with no card in the chat: saved by older app versions, from
-    // a turn that was retried, or drawn by a call that then failed its
-    // screenshot check (a call still running gets its card when done)
-    const hasCardless = versions.some(
-        (v) =>
-            !v.toolCallId ||
-            !engine.messages.some((m) =>
-                m.parts?.some((p) => {
-                    const part = p as { toolCallId?: string; state?: string }
-                    return (
-                        part.toolCallId === v.toolCallId &&
-                        part.state !== "output-error"
-                    )
-                }),
-            ),
-    )
-    // One version with a card: the strip adds nothing to it
-    if (versions.length < 2 && !hasCardless) return null
+    if (versions.length < minVersions) return null
 
     return (
         <div className="flex items-center gap-2 border-b border-border px-3.5 pt-1 pb-3">
@@ -49,13 +35,13 @@ export function VersionStrip() {
                 className="flex min-w-0 flex-1 gap-1.5 overflow-x-auto p-1 scrollbar-thin"
             >
                 {versions.map((version) => {
-                    const isCurrent = version.id === onCanvasVersionId
+                    const isCurrent = version.id === onCanvasId
                     return (
                         <button
                             key={version.id}
                             type="button"
                             onClick={() => openCompare(version.id)}
-                            title={`v${version.number}${version.id === onCanvasVersionId ? ` · ${dict.versions.currentCanvas}` : ""}`}
+                            title={`v${version.number}${isCurrent ? ` · ${dict.versions.currentCanvas}` : ""}`}
                             className={cn(
                                 "sheet-light relative flex h-12 w-[72px] shrink-0 items-center justify-center overflow-hidden rounded-lg border border-border bg-white transition-colors hover:border-foreground/30",
                                 // An outline with a gap reads on the white

components/canvas/versions-context.tsx

@@ -0,0 +1,72 @@
+"use client"
+
+import { createContext, useContext } from "react"
+import type { ChangeSummary } from "@/lib/diagram-diff"
+
+/** One saved state of the diagram, as the version card and the compare
+ * dialog show it */
+export interface VersionItem {
+    id: string
+    /** Shown as v{number} */
+    number: number
+    /** Full multi-page document */
+    xml: string
+    /** The page the change was made on; none: the first page */
+    pageId?: string
+    /** Document before the change, when it is known */
+    beforeXml?: string
+    /** SVG data URL thumbnail; undefined: still being made; "": none could
+     * be made */
+    svg?: string
+    summary: ChangeSummary
+    /** Drawn on an empty canvas (the card shows totals, not changes) */
+    fromScratch?: boolean
+}
+
+/**
+ * Where the versions come from and what can be done with them. The web app
+ * fills it from the chat's version store; the MCP shell from the server's
+ * history.
+ */
+export interface VersionsSource {
+    versions: VersionItem[]
+    /** The version the canvas shows now, or null (hand edits, undone) */
+    onCanvasId: string | null
+    /** The latest version, when its change was undone */
+    undoneId: string | null
+    /** Something is changing the canvas: version actions wait */
+    isBusy: boolean
+    /** The latest version's change can be undone */
+    canUndo: boolean
+    /** The latest version's change was undone and can be put back */
+    canRedo: boolean
+    restore: (id: string) => void
+    undo: () => void
+    redo: () => void
+}
+
+const VersionsContext = createContext<VersionsSource | null>(null)
+
+export function VersionsProvider({
+    value,
+    children,
+}: {
+    value: VersionsSource
+    children: React.ReactNode
+}) {
+    return (
+        <VersionsContext.Provider value={value}>
+            {children}
+        </VersionsContext.Provider>
+    )
+}
+
+export function useVersionsContext(): VersionsSource {
+    const source = useContext(VersionsContext)
+    if (!source) {
+        throw new Error(
+            "useVersionsContext must be used within a VersionsProvider",
+        )
+    }
+    return source
+}

components/chat/chat-engine.tsx

@@ -726,6 +726,11 @@ export function ChatEngineProvider({
     // isBusy of the latest render, for code that runs after an await
     const busyRef = useRef(isBusy)
     busyRef.current = isBusy
+    // Canvas components (version cards, the compare dialog, "ask AI") read
+    // the busy flag from the canvas store
+    useEffect(() => {
+        useCanvasStore.getState().set({ isBusy })
+    }, [isBusy])
     // The page goes (another language mounts a new one): the answer stops,
     // so it cannot reach the next page's canvas
     const stopRef = useRef(stop)

components/chat/chat-panel.tsx

@@ -7,6 +7,7 @@ import {
     Settings,
 } from "lucide-react"
 import { useRef } from "react"
+import { VersionStrip } from "@/components/canvas/version-strip"
 import { DevXmlSimulator } from "@/components/dev-xml-simulator"
 import { BrandMark } from "@/components/workspace/brand-mark"
 import { IconButton } from "@/components/workspace/icon-button"
@@ -21,11 +22,11 @@ import {
     useSettingsStore,
 } from "@/stores/settings-store"
 import { useUiStore } from "@/stores/ui-store"
+import { useVersionsStore } from "@/stores/versions-store"
 import { useChatEngine } from "./chat-engine"
 import { Composer } from "./composer"
 import { MessageList } from "./message-list"
 import { SessionMenu, useSessionTitle } from "./session-menu"
-import { VersionStrip } from "./version-strip"
 
 const DEBUG = process.env.NODE_ENV === "development"
 
@@ -97,6 +98,25 @@ export function ChatPanel({
     const openSettings = useUiStore((s) => s.openSettings)
     const setPanelOpen = useUiStore((s) => s.setPanelOpen)
 
+    // Versions with no card in the chat: saved by older app versions, from
+    // a turn that was retried, or drawn by a call that then failed its
+    // screenshot check (a call still running gets its card when done). The
+    // strip shows them even when there is only one.
+    const versions = useVersionsStore((s) => s.versions)
+    const hasCardless = versions.some(
+        (v) =>
+            !v.toolCallId ||
+            !engine.messages.some((m) =>
+                m.parts?.some((p) => {
+                    const part = p as { toolCallId?: string; state?: string }
+                    return (
+                        part.toolCallId === v.toolCallId &&
+                        part.state !== "output-error"
+                    )
+                }),
+            ),
+    )
+
     return (
         <aside
             className={cn(
@@ -160,7 +180,7 @@ export function ChatPanel({
                 </div>
             </header>
 
-            <VersionStrip />
+            <VersionStrip minVersions={hasCardless ? 1 : 2} />
 
             <div className="min-h-0 flex-1 overflow-y-auto scrollbar-thin">
                 {engine.messages.length > 0 ? <MessageList /> : <EmptyThread />}

components/chat/chat-versions.tsx

@@ -0,0 +1,46 @@
+"use client"
+
+import {
+    VersionsProvider,
+    type VersionsSource,
+} from "@/components/canvas/versions-context"
+import { useCanvasStore } from "@/stores/canvas-store"
+import { useVersionsStore } from "@/stores/versions-store"
+import { useChatEngine } from "./chat-engine"
+
+/**
+ * The chat's versions for the canvas components (version cards, the strip,
+ * the compare dialog): the version store's list and flags, and the chat
+ * engine's restore and undo
+ */
+export function ChatVersionsProvider({
+    children,
+}: {
+    children: React.ReactNode
+}) {
+    const { restoreVersion, undoVersion } = useChatEngine()
+    const versions = useVersionsStore((s) => s.versions)
+    const onCanvasId = useVersionsStore((s) => s.onCanvasVersionId)
+    const undoneId = useVersionsStore((s) => s.undoneVersionId)
+    const isBusy = useCanvasStore((s) => s.isBusy)
+
+    // Only the latest version can be undone, and only while it is (or was)
+    // on the canvas: after an older version was restored, the latest one
+    // is restored too
+    const latest = versions.at(-1)
+    const undoable = !!latest && latest.beforeXml !== undefined
+    const value: VersionsSource = {
+        versions,
+        onCanvasId,
+        undoneId,
+        isBusy,
+        canUndo: undoable && latest.id === onCanvasId,
+        canRedo: undoable && latest.id === undoneId,
+        restore: restoreVersion,
+        // The engine's undo toggles: it redoes a change that is undone
+        undo: () => latest && undoVersion(latest.id),
+        redo: () => latest && undoVersion(latest.id),
+    }
+
+    return <VersionsProvider value={value}>{children}</VersionsProvider>
+}

components/chat/tool-activity.tsx

@@ -5,19 +5,14 @@ import {
     Copy,
     Library,
     PenTool,
-    Redo2,
-    RotateCcw,
-    Undo2,
 } from "lucide-react"
 import { useState } from "react"
 import { Shimmer } from "@/components/ai-elements/shimmer"
+import { VersionCard as VersionCardView } from "@/components/canvas/version-card"
 import { CodeBlock } from "@/components/code-block"
 import { useDictionary } from "@/hooks/use-dictionary"
 import { useCopy } from "@/lib/clipboard"
-import { formatMessage } from "@/lib/i18n/utils"
 import { cn, isMxCellXmlComplete } from "@/lib/utils"
-import { describeChanges, describeTotals } from "@/lib/version-text"
-import { useUiStore } from "@/stores/ui-store"
 import { type DiagramVersion, useVersionsStore } from "@/stores/versions-store"
 import { useChatEngine } from "./chat-engine"
 import type { DiagramOperation, ToolPartLike } from "./types"
@@ -83,45 +78,9 @@ function toolText(part: ToolPartLike): string {
     return JSON.stringify(input, null, 2)
 }
 
-/** Picture of a version (SVG data URL), or what stands in for it */
-export function VersionThumb({
-    svg,
-    dimmed,
-    className,
-}: {
-    /** undefined or null: still being made; "": none could be made */
-    svg: string | null | undefined
-    dimmed?: boolean
-    className?: string
-}) {
-    const t = useDictionary().versions
-    if (svg) {
-        return (
-            // biome-ignore lint/performance/noImgElement: data URL thumbnail
-            <img
-                src={svg}
-                alt=""
-                className={cn(
-                    "object-contain transition-opacity",
-                    dimmed && "opacity-40",
-                    className,
-                )}
-            />
-        )
-    }
-    if (svg === "") {
-        return <span className="text-xs text-faint">{t.noPreview}</span>
-    }
-    return (
-        <Shimmer as="span" className="text-xs">
-            {t.rendering}
-        </Shimmer>
-    )
-}
-
 /**
- * Card for one diagram version produced by a tool call. The latest shows
- * its picture; older ones fold into one row (the picture opens Compare).
+ * Card for one diagram version produced by a tool call: the shared card
+ * with a link to what the AI wrote (shown in a panel under the card)
  */
 function VersionCard({
     part,
@@ -134,175 +93,49 @@ function VersionCard({
 }) {
     const dict = useDictionary()
     const t = dict.versions
-    const engine = useChatEngine()
-    const undoneVersionId = useVersionsStore((s) => s.undoneVersionId)
-    const onCanvasVersionId = useVersionsStore((s) => s.onCanvasVersionId)
-    const openCompare = useUiStore((s) => s.openCompare)
     const [showCode, setShowCode] = useState(false)
     const { copied, copy } = useCopy()
-
-    const isUndone = undoneVersionId === version.id
-    const isOnCanvas = onCanvasVersionId === version.id
     const isEdit = part.type === "tool-edit_diagram"
-    // Undo/redo belongs to the newest change while it is (or was) on the
-    // canvas; after an older version was restored, this one is restored too
-    const canUndo =
-        isLatest && version.beforeXml !== undefined && (isOnCanvas || isUndone)
-    const title = isUndone ? t.undone : isEdit ? t.edited : t.created
-    const summary = version.fromScratch
-        ? describeTotals(version.summary, t)
-        : describeChanges(version.summary, t)
-    const badge = (
-        <span
-            className={cn(
-                "shrink-0 rounded-md px-1.5 py-0.5 text-[11px] font-semibold tabular-nums",
-                isOnCanvas
-                    ? "bg-marker-soft text-marker-ink"
-                    : "bg-muted text-muted-foreground",
-            )}
-        >
-            v{version.number}
-        </span>
-    )
-    const actionClass =
-        "inline-flex h-7 shrink-0 items-center gap-1 rounded-lg px-2 text-xs text-muted-foreground hover:bg-accent hover:text-foreground disabled:opacity-40"
-    const restoreButton = (
-        <button
-            type="button"
-            disabled={engine.isBusy || isOnCanvas}
-            onClick={() => engine.restoreVersion(version.id)}
-            className={actionClass}
-            data-testid="version-restore"
-        >
-            <RotateCcw className="size-3.5" />
-            {formatMessage(t.restoreVersion, { n: version.number })}
-        </button>
-    )
-
-    // What the AI wrote: a text link in the summary line, so the card's
-    // only button is the action (undo or restore)
-    const summaryLine = (
-        <div className="text-xs text-muted-foreground">
-            {summary}
-            {/* The link wraps as one unit with its separator */}
-            <span className="whitespace-nowrap">
-                <span aria-hidden> · </span>
-                <button
-                    type="button"
-                    onClick={() => setShowCode((v) => !v)}
-                    className="underline decoration-foreground/30 underline-offset-2 hover:text-foreground hover:decoration-foreground"
-                >
-                    {showCode ? t.hideCode : t.showCode}
-                </button>
-            </span>
-        </div>
-    )
-    const codePanel = showCode && (
-        <div className="relative border-t border-border bg-surface-1 px-3 py-2.5">
-            <button
-                type="button"
-                onClick={() => copy(toolText(part))}
-                className="absolute top-2 right-2 z-10 inline-flex size-7 items-center justify-center rounded-lg bg-card text-muted-foreground shadow-float hover:text-foreground"
-                aria-label={dict.chat.copyResponse}
-            >
-                {copied ? (
-                    <Check className="size-3.5" />
-                ) : (
-                    <Copy className="size-3.5" />
-                )}
-            </button>
-            <ToolInputDetails part={part} />
-        </div>
-    )
-
-    if (!isLatest) {
-        return (
-            <div
-                className="overflow-hidden rounded-xl border border-border bg-card"
-                data-testid="version-card"
-                data-tool-state={part.state}
-            >
-                <div className="flex items-center gap-2.5 p-1.5 pr-2">
-                    <button
-                        type="button"
-                        onClick={() => openCompare(version.id)}
-                        className="sheet-light flex h-9 w-14 shrink-0 items-center justify-center overflow-hidden rounded-md border border-border bg-white hover:border-foreground/30"
-                        aria-label={t.compare}
-                        title={t.compare}
-                    >
-                        <VersionThumb
-                            svg={version.svg}
-                            className="max-h-8 max-w-[52px]"
-                        />
-                    </button>
-                    {badge}
-                    <div className="min-w-0 flex-1">
-                        <div className="truncate text-[13px] text-foreground">
-                            {title}
-                        </div>
-                        {summaryLine}
-                    </div>
-                    {restoreButton}
-                </div>
-                {codePanel}
-            </div>
-        )
-    }
 
     return (
-        <div
-            className={cn(
-                "overflow-hidden rounded-xl border border-border bg-card",
-                isOnCanvas && "border-foreground/15",
-            )}
-            data-testid="version-card"
+        <VersionCardView
+            version={version}
+            isLatest={isLatest}
+            label={isEdit ? t.edited : t.created}
             data-tool-state={part.state}
-        >
-            <button
-                type="button"
-                onClick={() => openCompare(version.id)}
-                className="group/thumb sheet-light relative flex h-24 w-full items-center justify-center border-b border-border bg-white"
-                aria-label={t.compare}
-            >
-                <VersionThumb
-                    svg={version.svg}
-                    dimmed={isUndone}
-                    className="max-h-20 max-w-[88%]"
-                />
-                <span className="absolute right-2 bottom-2 rounded-md bg-black/60 px-1.5 py-0.5 text-[11px] text-white opacity-0 transition-opacity group-hover/thumb:opacity-100">
-                    {t.compare}
-                </span>
-            </button>
-            {/* Title row with the action; the summary runs under both */}
-            <div className="grid grid-cols-[auto_minmax(0,1fr)_auto] items-center gap-x-2.5 px-3 py-2.5">
-                {badge}
-                <div className="truncate text-[13px] font-medium text-foreground">
-                    {title}
-                </div>
-                {canUndo ? (
+            // A text link, so the card's only button is the action (undo
+            // or restore); it wraps as one unit with its separator
+            afterSummary={
+                <span className="whitespace-nowrap">
+                    <span aria-hidden> · </span>
                     <button
                         type="button"
-                        disabled={engine.isBusy}
-                        onClick={() => engine.undoVersion(version.id)}
-                        className={actionClass}
-                        data-testid="version-undo"
+                        onClick={() => setShowCode((v) => !v)}
+                        className="underline decoration-foreground/30 underline-offset-2 hover:text-foreground hover:decoration-foreground"
                     >
-                        {isUndone ? (
-                            <Redo2 className="size-3.5" />
-                        ) : (
-                            <Undo2 className="size-3.5" />
-                        )}
-                        {isUndone ? t.redo : t.undo}
+                        {showCode ? t.hideCode : t.showCode}
                     </button>
-                ) : (
-                    restoreButton
-                )}
-                <div className="col-span-2 col-start-2 mt-0.5">
-                    {summaryLine}
+                </span>
+            }
+        >
+            {showCode && (
+                <div className="relative border-t border-border bg-surface-1 px-3 py-2.5">
+                    <button
+                        type="button"
+                        onClick={() => copy(toolText(part))}
+                        className="absolute top-2 right-2 z-10 inline-flex size-7 items-center justify-center rounded-lg bg-card text-muted-foreground shadow-float hover:text-foreground"
+                        aria-label={dict.chat.copyResponse}
+                    >
+                        {copied ? (
+                            <Check className="size-3.5" />
+                        ) : (
+                            <Copy className="size-3.5" />
+                        )}
+                    </button>
+                    <ToolInputDetails part={part} />
                 </div>
-            </div>
-            {codePanel}
-        </div>
+            )}
+        </VersionCardView>
     )
 }
 

components/chat/use-versions.ts

@@ -4,7 +4,10 @@ import { toast } from "sonner"
 import { useDiagram } from "@/contexts/diagram-context"
 import { useDictionary } from "@/hooks/use-dictionary"
 import { diffDiagrams, isSameDocument } from "@/lib/diagram-diff"
-import { clearHighlights, highlightCells } from "@/lib/drawio/editor-bridge"
+import {
+    clearHighlights,
+    highlightChangedCells,
+} from "@/lib/drawio/editor-bridge"
 import { formatMessage } from "@/lib/i18n/utils"
 import { BLANK_MXFILE } from "@/packages/mcp-server/src/pages.ts"
 import { useVersionsStore } from "@/stores/versions-store"
@@ -63,14 +66,7 @@ export function useVersions({
                 fromScratch,
             })
             // Mark what changed, unless the whole diagram is new
-            if (!fromScratch) {
-                setTimeout(() => {
-                    const marker = getComputedStyle(document.documentElement)
-                        .getPropertyValue("--marker")
-                        .trim()
-                    highlightCells(touchedIds, marker || "#ffd84d")
-                }, 60)
-            }
+            if (!fromScratch) highlightChangedCells(touchedIds)
             // The picture is of the canvas: take it right away, before a
             // newer version can be on it; once one is, this one gets none
             // rather than the newer one's

components/workspace/brand-mark.tsx

@@ -3,7 +3,7 @@
 import { getAssetUrl } from "@/lib/base-path"
 import { cn } from "@/lib/utils"
 
-/** The app icon in a rounded tile; the white variant is used in dark mode */
+/** The app icon in a rounded tile; the icon has its own white tile, so dark mode uses it too */
 export function BrandMark({ className }: { className?: string }) {
     return (
         <span
@@ -16,13 +16,7 @@ export function BrandMark({ className }: { className?: string }) {
             <img
                 src={getAssetUrl("/favicon-192x192.png")}
                 alt=""
-                className="size-full object-contain dark:hidden"
-            />
-            {/* biome-ignore lint/performance/noImgElement: tiny static icon */}
-            <img
-                src={getAssetUrl("/favicon-white.svg")}
-                alt=""
-                className="hidden size-5 object-contain dark:block"
+                className="size-full object-contain"
             />
         </span>
     )

components/workspace/workspace.tsx

@@ -4,12 +4,14 @@ import { MessageSquare, PanelRightOpen, Settings, Shapes } from "lucide-react"
 import { usePathname, useRouter } from "next/navigation"
 import { useEffect, useRef, useState } from "react"
 import { CanvasStage } from "@/components/canvas/canvas-stage"
+import { CompareDialog } from "@/components/canvas/compare-dialog"
+import { SelectionAsk } from "@/components/canvas/selection-ask"
 import {
     ChatEngineProvider,
     useChatEngine,
 } from "@/components/chat/chat-engine"
 import { ChatPanel } from "@/components/chat/chat-panel"
-import { CompareDialog } from "@/components/chat/compare-dialog"
+import { ChatVersionsProvider } from "@/components/chat/chat-versions"
 import { LobbyHero } from "@/components/chat/lobby-hero"
 import { SaveDialog } from "@/components/save-dialog"
 import { SettingsDialog } from "@/components/settings-dialog"
@@ -116,7 +118,9 @@ export function Workspace() {
 
     return (
         <ChatEngineProvider>
-            <WorkspaceLayout />
+            <ChatVersionsProvider>
+                <WorkspaceLayout />
+            </ChatVersionsProvider>
         </ChatEngineProvider>
     )
 }
@@ -267,6 +271,13 @@ function WorkspaceLayout() {
                         }
                         style={isMobile ? undefined : { right: canvasRight }}
                         hideOverlays={!isMobile && showHero}
+                        overlay={(size) => (
+                            <SelectionAsk
+                                width={size.width}
+                                height={size.height}
+                            />
+                        )}
+                        waitForSavedLocale
                     />
                     {isMobile ? (
                         mobileView === "chat" &&

contexts/diagram-context.tsx

@@ -60,6 +60,20 @@ export interface DiagramCommit {
     pageId?: string | null
 }
 
+/** An export as draw.io's export action takes it: the format, and for PNG
+ * its scale, width cap and the page to render (pageId) */
+export interface ExportRequest {
+    format: string
+    [key: string]: unknown
+}
+
+/** What draw.io answered: the image (a data URL, or SVG text) in data; for
+ * format "xml" the document in xml instead */
+export interface ExportResult {
+    data?: string
+    xml?: string
+}
+
 interface DiagramContextType {
     chartXML: string
     // chartXML right away, before the re-render (loadDiagram sets both)
@@ -91,6 +105,19 @@ interface DiagramContextType {
     getThumbnailSvg: () => Promise<string | null>
     getVersionSvg: () => Promise<string | null>
     captureValidationPng: () => Promise<string | null>
+    /** One export with its own result; null when draw.io does not answer
+     * in time (the MCP shell answers the server's export requests with it) */
+    requestExport: (
+        request: ExportRequest,
+        timeoutMs?: number,
+    ) => Promise<ExportResult | null>
+    /** Show a document for an export only (the MCP's one-page projection of
+     * another page): not recorded as the diagram, its autosaves ignored,
+     * until the next loadDiagram puts the real document back */
+    showTransient: (xml: string) => void
+    /** A full load was sent and draw.io has not reported it yet: the
+     * editor still shows the previous document */
+    hasPendingLoad: () => boolean
     isDrawioReady: boolean
     onDrawioLoad: () => void
     resetDrawioReady: () => void
@@ -141,13 +168,19 @@ export function DiagramProvider({ children }: { children: React.ReactNode }) {
     // The page to show again once a full load is done: draw.io shows the
     // first page of a loaded document
     const pageAfterLoadRef = useRef<string | null>(null)
+    // A transient document (showTransient) is on the canvas, and the page
+    // the user was on before it
+    const transientRef = useRef(false)
+    const pageBeforeTransientRef = useRef<string | null>(null)
 
     // Sends a full load. draw.io runs it when its message arrives, and then
     // reports "load": until then the editor shows the diagram from before,
     // so later changes go the same way and keep their order
-    const fullLoad = (xml: string) => {
+    const fullLoad = (
+        xml: string,
+        pageId: string | null = useCanvasStore.getState().currentPageId,
+    ) => {
         if (!drawioRef.current) return
-        const pageId = useCanvasStore.getState().currentPageId
         pageAfterLoadRef.current =
             pageId && xml.includes(`id="${pageId}"`) ? pageId : null
         pendingLoadsRef.current++
@@ -252,6 +285,38 @@ export function DiagramProvider({ children }: { children: React.ReactNode }) {
         return pngData?.startsWith("data:image/png") ? pngData : null
     }
 
+    // Like requestTaggedExport, with the request's other parameters (a PNG's
+    // page and width) and both parts of the answer
+    const requestExport = useCallback(
+        (request: ExportRequest, timeoutMs = 10000) =>
+            new Promise<ExportResult | null>((resolve) => {
+                if (!drawioRef.current) {
+                    resolve(null)
+                    return
+                }
+                const id = `export-${++exportSeqRef.current}`
+                const finish = (value: ExportResult | null) => {
+                    clearTimeout(timer)
+                    delete exportResolversRef.current[id]
+                    resolve(value)
+                }
+                const timer = setTimeout(() => finish(null), timeoutMs)
+                exportResolversRef.current[id] = (data, xml) =>
+                    finish({ data, xml })
+                drawioRef.current.exportDiagram({ ...request, message: id })
+            }),
+        [],
+    )
+
+    const showTransient = (xml: string) => {
+        if (!transientRef.current) {
+            pageBeforeTransientRef.current =
+                useCanvasStore.getState().currentPageId
+        }
+        transientRef.current = true
+        fullLoad(xml)
+    }
+
     const loadDiagram = (
         chart: string,
         skipValidation?: boolean,
@@ -261,6 +326,12 @@ export function DiagramProvider({ children }: { children: React.ReactNode }) {
         // The editor bridge is shared: a page that is gone (another language
         // mounted a new one) must not change the new page's canvas
         if (!mountedRef.current) return null
+        // A real document ends a transient one; the user goes back to the
+        // page they were on before it
+        const pageBeforeTransient = transientRef.current
+            ? pageBeforeTransientRef.current
+            : undefined
+        transientRef.current = false
         let xmlToLoad = chart
 
         // Validate XML structure before loading (unless skipped for internal
@@ -315,7 +386,7 @@ export function DiagramProvider({ children }: { children: React.ReactNode }) {
         if (!applied) {
             // A full load replaces any preview, and its base is stale now
             resetPreview()
-            fullLoad(xmlToLoad)
+            fullLoad(xmlToLoad, pageBeforeTransient)
         }
 
         if (mode === "commit") {
@@ -336,10 +407,10 @@ export function DiagramProvider({ children }: { children: React.ReactNode }) {
     }
 
     const handleDiagramExport = (data: DrawioExportEvent) => {
-        // Thumbnail, version, validation PNG and file save exports go only
-        // to their own caller
+        // Thumbnail, version, validation PNG, file save and requestExport
+        // exports go only to their own caller
         const tag = data.message?.message
-        if (/^(thumbnail|validation|version|save)-/.test(tag ?? "")) {
+        if (/^(thumbnail|validation|version|save|export)-/.test(tag ?? "")) {
             exportResolversRef.current[tag as string]?.(data.data, data.xml)
             return
         }
@@ -369,6 +440,11 @@ export function DiagramProvider({ children }: { children: React.ReactNode }) {
     // read refs: state captured in its closure would stay stale after a remount
     const handleDiagramAutoSave = (data: { xml?: string }) => {
         if (!data?.xml) return
+        // An edit of a transient document is not the diagram's; nor is one
+        // of the canvas a full load still on its way replaces (draw.io
+        // reports each load, in order, so no autosave of the new document
+        // comes before that)
+        if (transientRef.current || pendingLoadsRef.current > 0) return
         // Don't overwrite a pending restore - if we have a diagram but
         // DrawIO hasn't loaded yet, it means we're waiting to restore
         if (!hasCalledOnLoadRef.current && chartXMLRef.current) return
@@ -522,6 +598,9 @@ export function DiagramProvider({ children }: { children: React.ReactNode }) {
                 getThumbnailSvg,
                 getVersionSvg,
                 captureValidationPng,
+                requestExport,
+                showTransient,
+                hasPendingLoad: () => pendingLoadsRef.current > 0,
                 isDrawioReady,
                 onDrawioLoad,
                 resetDrawioReady,

docs/cn/README_CN.md

@@ -114,9 +114,12 @@ claude mcp add drawio -- npx @next-ai-drawio/mcp-server@latest
 然后对 AI 说"画一个用户认证流程图，包含登录、MFA 和会话管理"，图会实时出现在浏览器里。MCP 服务器包含网页版的大部分画图能力：
 
 -   同一套画图规则和图标库（AWS、Azure、GCP、Kubernetes 等）
+-   预览页就是网页版的画布：AI 的改动会被标出，按一次 Ctrl+Z 就能撤销，AI 还能读到你选中的图形
+-   draw.io 编辑器随包一起安装，装好后预览不需要联网（也可以用 `DRAWIO_BASE_URL` 改用外部的 draw.io）
 -   截图工具，AI 可以看一眼画好的图并自行修正
 -   版本历史、多页图表，下载为 `.drawio`、`.png`、`.svg` 或 `.drawio.svg`
 -   自动保存到 `~/.next-ai-drawio/`，重启后接着画
+-   可以让 AI 撤销修改，也可以在 `~/.next-ai-drawio/instructions.md` 里写下自己的画图规则
 
 VS Code、Cursor 等客户端的配置见 [MCP 服务器 README](../../packages/mcp-server/README.md)。
 

docs/cn/offline-deployment.md

@@ -14,7 +14,7 @@ Next AI Draw.io 自带一份 draw.io。`npm run build`（包括 Docker 构建）
 
 构建会从 [draw.io 发布页](https://github.com/jgraph/drawio/releases) 下载 `draw.war`（约 50 MB）。如果构建机器访问不了 GitHub：
 
-- 在另一台机器上下载 `scripts/fetch-drawio.mjs` 里写明的那个版本的 `draw.war`，解压到 `public/drawio`（删掉 `WEB-INF` 和 `META-INF`），再把版本号（例如 `v32.0.2`）写进 `public/drawio/.version`。构建时就会使用这份副本。
+- 在另一台机器上下载 `packages/mcp-server/src/drawio-version.json` 里写明的那个版本的 `draw.war`，解压到 `public/drawio`（删掉 `WEB-INF` 和 `META-INF`），再把版本号（例如 `v32.0.2`）写进 `public/drawio/.version`。构建时就会使用这份副本。
 - 或者在能联网的机器上构建镜像，再拷到离线网络里。
 
 ## 来自其他网站的图片

docs/en/offline-deployment.md

@@ -14,7 +14,7 @@ No separate draw.io container is needed.
 
 The build downloads `draw.war` (about 50 MB) from the [draw.io releases](https://github.com/jgraph/drawio/releases). If the build machine cannot reach GitHub:
 
-- On another machine, download `draw.war` for the version in `scripts/fetch-drawio.mjs`, unzip it into `public/drawio` (delete `WEB-INF` and `META-INF`), and write the version, for example `v32.0.2`, into `public/drawio/.version`. The build then uses this copy.
+- On another machine, download `draw.war` for the version in `packages/mcp-server/src/drawio-version.json`, unzip it into `public/drawio` (delete `WEB-INF` and `META-INF`), and write the version, for example `v32.0.2`, into `public/drawio/.version`. The build then uses this copy.
 - Or build the image on a machine with internet access and transfer it to the offline network.
 
 ## Images From Other Websites

docs/ja/README_JA.md

@@ -114,9 +114,12 @@ claude mcp add drawio -- npx @next-ai-drawio/mcp-server@latest
 あとは AI に「ログイン、MFA、セッション管理を含むユーザー認証のフローチャートを描いて」と頼めば、描かれていく様子がブラウザに表示されます。MCP サーバーには Web アプリの作図機能のほとんどが入っています。
 
 -   同じ作図ルールとアイコンライブラリ（AWS、Azure、GCP、Kubernetes など）
+-   プレビューは Web アプリと同じキャンバス。AI の変更には印が付き、Ctrl+Z 一回で元に戻せ、選択中の図形を AI が読み取れる
+-   draw.io エディターはパッケージに同梱されているので、インストール後はオフラインでもプレビューが動く（外部の draw.io を使うなら `DRAWIO_BASE_URL` を設定する）
 -   スクリーンショットツール。AI が描いた結果を確認して自分で直せる
 -   バージョン履歴、複数ページのダイアグラム、`.drawio`、`.png`、`.svg`、`.drawio.svg` でのダウンロード
 -   `~/.next-ai-drawio/` への自動保存。再起動後も続きから描ける
+-   AI に元に戻す操作を頼める。独自の作図ルールは `~/.next-ai-drawio/instructions.md` に書ける
 
 VS Code、Cursor などの設定は [MCP サーバーの README](../../packages/mcp-server/README.md) を参照してください。
 

docs/ja/offline-deployment.md

@@ -14,7 +14,7 @@ draw.io 用の別コンテナは不要です。
 
 ビルドは [draw.io のリリース](https://github.com/jgraph/drawio/releases) から `draw.war`（約 50 MB）をダウンロードします。ビルド環境から GitHub にアクセスできない場合は、次のどちらかを行ってください。
 
-- 別のマシンで `scripts/fetch-drawio.mjs` に書かれたバージョンの `draw.war` をダウンロードし、`public/drawio` に展開します（`WEB-INF` と `META-INF` は削除）。さらにバージョン（例：`v32.0.2`）を `public/drawio/.version` に書き込みます。ビルドはこのコピーを使います。
+- 別のマシンで `packages/mcp-server/src/drawio-version.json` に書かれたバージョンの `draw.war` をダウンロードし、`public/drawio` に展開します（`WEB-INF` と `META-INF` は削除）。さらにバージョン（例：`v32.0.2`）を `public/drawio/.version` に書き込みます。ビルドはこのコピーを使います。
 - インターネットに接続できるマシンでイメージをビルドし、オフライン環境に転送します。
 
 ## ほかのサイトの画像

lib/diagram-diff.ts

@@ -285,7 +285,13 @@ export function sameFileVars(a: string | null, b: string | null): boolean {
 
 /**
  * Whether two documents hold the same pages (names, cells, their order),
- * page settings and file variables
+ * page settings and file variables. This is the web app's one rule for "is
+ * this version on the canvas" (versions, compare, one-step commits). The
+ * MCP server's edit gate has its own (contentFingerprint): it compares the
+ * cells as written, and leaves page settings and file variables out. The
+ * two disagree both ways (a background change is a difference only here;
+ * a geometry written "40.0" and "40" is one only there), so neither is a
+ * subset of the other.
  */
 export function isSameDocument(a: string, b: string): boolean {
     const pagesOf = (doc: Document) => {

lib/drawio/drawio-config.ts

@@ -6,41 +6,66 @@ import { BLANK_MXFILE } from "@/packages/mcp-server/src/pages.ts"
 const EXTERNAL_DRAWIO_URL = process.env.NEXT_PUBLIC_DRAWIO_BASE_URL || ""
 
 /**
- * URL of the draw.io editor iframe. By default this is the copy bundled in
- * public/drawio, served from our own origin.
+ * Where the editor comes from and how it starts. The web app fills it from
+ * its build settings (webDrawioSource); the MCP's canvas shell from the
+ * config its server writes into the page.
  */
-export function getDrawioSrc({
-    lang,
-    isElectron,
-    dark,
-}: {
-    lang: Locale
-    isElectron: boolean
-    dark: boolean
-}): string {
-    // index.html: Next.js does not serve directory indexes
-    const base =
-        EXTERNAL_DRAWIO_URL ||
-        `${window.location.origin}${getAssetUrl("/drawio/index.html")}`
-    const url = new URL(base)
+export interface DrawioSource {
+    /** The editor page: the bundled copy's index.html on this origin, or an
+     * external draw.io (cross-origin, limited features) */
+    editorUrl: string
+    /** draw.io theme (its ui parameter); none: draw.io's default and the
+     * user's own pick */
+    ui?: string
+    /** Language in draw.io's naming ("zh-tw"); none: draw.io's own pick */
+    lang?: string
+    /** No calls to external services (the desktop app) */
+    offline?: boolean
+    /** draw.io's custom libraries (File > New Library, Open Library from,
+     * and the buttons under the shapes); the web app leaves them out */
+    libraries?: boolean
+}
+
+/**
+ * The web app's editor: the copy in public/drawio, served from our own
+ * origin (index.html, as Next.js serves no directory indexes), or
+ * NEXT_PUBLIC_DRAWIO_BASE_URL; the simple theme in the page's language.
+ */
+export function webDrawioSource(lang: Locale): DrawioSource {
+    const isElectron = !!(window as { electronAPI?: unknown }).electronAPI
+    return {
+        editorUrl: EXTERNAL_DRAWIO_URL || getAssetUrl("/drawio/index.html"),
+        ui: "simple",
+        // draw.io names Traditional Chinese "zh-tw"
+        lang: lang === "zh-Hant" ? "zh-tw" : lang,
+        offline: isElectron && !EXTERNAL_DRAWIO_URL,
+    }
+}
+
+/** URL of the draw.io editor iframe */
+export function getDrawioSrc(source: DrawioSource, dark: boolean): string {
+    const url = new URL(source.editorUrl, window.location.href)
     const params: Record<string, string> = {
         embed: "1",
         proto: "json",
         configure: "1",
-        ui: "simple",
+    }
+    // Without a fixed theme, embedded draw.io shows Extras > Theme only
+    // with themes=1 (its isThemeMenuVisible)
+    if (source.ui) params.ui = source.ui
+    else params.themes = "1"
+    Object.assign(params, {
         spin: "0",
-        libraries: "0",
+        libraries: source.libraries ? "1" : "0",
         noSaveBtn: "1",
         noExitBtn: "1",
         saveAndExit: "0",
         // draw.io's own dark mode (switched in place later when the editor
         // can be driven directly)
         dark: dark ? "1" : "0",
-        // draw.io names Traditional Chinese "zh-tw"
-        lang: lang === "zh-Hant" ? "zh-tw" : lang,
-    }
-    // No calls to external services from the desktop app
-    if (isElectron && !EXTERNAL_DRAWIO_URL) params.offline = "1"
+    })
+    if (source.lang) params.lang = source.lang
+    if (source.offline) params.offline = "1"
     for (const [key, value] of Object.entries(params)) {
         url.searchParams.set(key, value)
     }

lib/drawio/editor-bridge.ts

@@ -11,6 +11,7 @@
  */
 import { isSameDocument, sameFileVars } from "@/lib/diagram-diff"
 import { hasCells } from "@/packages/mcp-server/src/pages.ts"
+import type { SelectionAnswer } from "@/packages/mcp-server/src/selection.ts"
 import { type SelectedCell, useCanvasStore } from "@/stores/canvas-store"
 
 type EditorUi = any
@@ -262,19 +263,19 @@ function hasShapes(xml: string): boolean {
     })
 }
 
-// Page settings draw.io applies on a full load only: replacing the page in
-// place (Editor.readGraphState) keeps the old ones. (Its adaptive colors and
-// theme stay too: a diagram the AI writes does not set them.)
-function hasLoadOnlySettings(model: string): boolean {
-    const page = new DOMParser().parseFromString(
-        model,
-        "text/xml",
-    ).documentElement
+/**
+ * Page settings draw.io applies on a full load only: replacing the page in
+ * place (Editor.readGraphState) keeps the old ones. (Its adaptive colors and
+ * theme stay too: a diagram the AI writes does not set them.) Takes the
+ * page's mxGraphModel element; the MCP shell's sync asks the same question
+ * of a document before it reaches the editor.
+ */
+export function hasLoadOnlySettings(model: Element): boolean {
     return (
-        page.hasAttribute("backgroundImage") ||
-        page.hasAttribute("extFonts") ||
-        page.getAttribute("math") === "1" ||
-        page.getAttribute("shadow") === "1"
+        model.hasAttribute("backgroundImage") ||
+        model.hasAttribute("extFonts") ||
+        model.getAttribute("math") === "1" ||
+        model.getAttribute("shadow") === "1"
     )
 }
 
@@ -322,7 +323,9 @@ export function canReplaceDiagram(xml: string): boolean {
     // A document with them, or replacing one with them, loads in full
     return (
         model !== null &&
-        !hasLoadOnlySettings(model) &&
+        !hasLoadOnlySettings(
+            new DOMParser().parseFromString(model, "text/xml").documentElement,
+        ) &&
         !canvasHasLoadOnlySettings()
     )
 }
@@ -547,6 +550,19 @@ export function highlightCells(ids: string[], color: string) {
     }
 }
 
+/**
+ * Marks the cells an AI change touched in the page's marker color, once
+ * draw.io has drawn them (the web app's versions and the MCP shell share it)
+ */
+export function highlightChangedCells(ids: string[]) {
+    setTimeout(() => {
+        const marker = getComputedStyle(document.documentElement)
+            .getPropertyValue("--marker")
+            .trim()
+        highlightCells(ids, marker || "#ffd84d")
+    }, 60)
+}
+
 // ---------------------------------------------------------------------------
 // Selection
 // ---------------------------------------------------------------------------
@@ -584,6 +600,56 @@ function readSelection(): SelectedCell[] {
         }))
 }
 
+/**
+ * The selection with what an editing model needs (the MCP's get_selection):
+ * the page it is on, each cell's label, an edge's ends, a shape's geometry
+ * as the XML has it (relative to its container) and that container. Null
+ * without an editor (a cross-origin draw.io).
+ */
+export function readSelectionDetails(): SelectionAnswer | null {
+    const g = graph()
+    if (!g) return null
+    const page = ui?.currentPage
+    const cells = (g.getSelectionCells() as any[])
+        .filter((cell) => cell?.id)
+        .map((cell) => {
+            const info: SelectionAnswer["cells"][number] = {
+                id: String(cell.id),
+                label: cellLabel(cell),
+                edge: !!g.model.isEdge(cell),
+            }
+            if (info.edge) {
+                const source = g.model.getTerminal(cell, true)
+                const target = g.model.getTerminal(cell, false)
+                if (source?.id) info.source = String(source.id)
+                if (target?.id) info.target = String(target.id)
+            } else {
+                const geo = g.getCellGeometry(cell)
+                if (geo) {
+                    info.geometry = {
+                        x: geo.x,
+                        y: geo.y,
+                        width: geo.width,
+                        height: geo.height,
+                    }
+                }
+            }
+            // The container the cell is in; a layer is none (and the
+            // default parent is the group the user entered, if any, so it
+            // cannot tell the two apart)
+            const parent = g.model.getParent(cell)
+            if (parent?.id && !g.model.isLayer(parent)) {
+                info.parent = String(parent.id)
+            }
+            return info
+        })
+    return {
+        pageId: page?.getId ? String(page.getId()) : null,
+        pageName: page?.getName ? String(page.getName()) : null,
+        cells,
+    }
+}
+
 function readSelectionRect() {
     const g = graph()
     if (!g || g.isSelectionEmpty()) return null

lib/i18n/dictionaries/en.json

@@ -699,5 +699,20 @@
         "recent": "Recent diagrams",
         "drawYourself": "Start with a blank canvas",
         "openFileHint": "Keep working on a diagram you have"
+    },
+    "shell": {
+        "waiting": "Waiting for the MCP server…",
+        "toggleTheme": "Switch between light and dark",
+        "connected": "Connected to the MCP server",
+        "offline": "Can't reach the MCP server",
+        "tooLarge": "This diagram is too large to save to the MCP server (over 10 MB).",
+        "unreachable": "Can't reach the MCP server. Your changes are only in this tab for now.",
+        "restoredFromFile": "The diagram was restored from its saved file. What this tab showed before is in History.",
+        "aiChanged": "The AI changed the diagram while you were editing. Your last change was saved in History.",
+        "historyChanged": "History changed on the server. Please open it again.",
+        "restoreFailed": "Restore failed. Please try again.",
+        "userEdit": "Changed by hand",
+        "showVersions": "Show the versions",
+        "hideVersions": "Hide the versions"
     }
 }

lib/i18n/dictionaries/ja.json

@@ -699,5 +699,20 @@
         "recent": "最近の図",
         "drawYourself": "白紙のキャンバスから始める",
         "openFileHint": "手元の図の続きを編集"
+    },
+    "shell": {
+        "waiting": "MCP サーバーを待っています…",
+        "toggleTheme": "ライトとダークを切り替え",
+        "connected": "MCP サーバーに接続しました",
+        "offline": "MCP サーバーに接続できません",
+        "tooLarge": "この図は大きすぎて MCP サーバーに保存できません（10 MB 超）。",
+        "unreachable": "MCP サーバーに接続できません。変更は今のところこのタブにだけあります。",
+        "restoredFromFile": "図は保存済みファイルから復元されました。このタブに表示されていた内容は履歴にあります。",
+        "aiChanged": "編集中に AI が図を変更しました。最後の変更は履歴に保存されました。",
+        "historyChanged": "サーバー上の履歴が変わりました。もう一度開いてください。",
+        "restoreFailed": "復元に失敗しました。もう一度お試しください。",
+        "userEdit": "手で変更しました",
+        "showVersions": "バージョンを表示",
+        "hideVersions": "バージョンを隠す"
     }
 }

lib/i18n/dictionaries/zh-Hant.json

@@ -699,5 +699,20 @@
         "recent": "最近的圖紙",
         "drawYourself": "從空白畫布開始",
         "openFileHint": "接著編輯已有的圖"
+    },
+    "shell": {
+        "waiting": "正在等待 MCP 伺服器…",
+        "toggleTheme": "切換淺色或深色",
+        "connected": "已連接 MCP 伺服器",
+        "offline": "無法連接 MCP 伺服器",
+        "tooLarge": "這張圖太大，無法儲存到 MCP 伺服器（超過 10 MB）。",
+        "unreachable": "無法連接 MCP 伺服器。您的修改暫時只保存在這個分頁裡。",
+        "restoredFromFile": "圖表已從儲存的檔案還原。這個分頁之前顯示的內容已放入歷史記錄。",
+        "aiChanged": "您編輯時 AI 修改了圖表。您的最後一次修改已儲存到歷史記錄。",
+        "historyChanged": "伺服器上的歷史記錄已變化，請重新開啟。",
+        "restoreFailed": "還原失敗，請再試一次。",
+        "userEdit": "手動修改",
+        "showVersions": "顯示版本",
+        "hideVersions": "隱藏版本"
     }
 }

lib/i18n/dictionaries/zh.json

@@ -699,5 +699,20 @@
         "recent": "最近的图纸",
         "drawYourself": "从空白画布开始",
         "openFileHint": "接着编辑已有的图"
+    },
+    "shell": {
+        "waiting": "正在等待 MCP 服务器…",
+        "toggleTheme": "切换浅色或深色",
+        "connected": "已连接 MCP 服务器",
+        "offline": "无法连接 MCP 服务器",
+        "tooLarge": "这张图太大，无法保存到 MCP 服务器（超过 10 MB）。",
+        "unreachable": "无法连接 MCP 服务器。您的修改暂时只保存在这个标签页里。",
+        "restoredFromFile": "图表已从保存的文件恢复。这个标签页之前显示的内容已放入历史记录。",
+        "aiChanged": "您编辑时 AI 修改了图表。您的最后一次修改已保存到历史记录。",
+        "historyChanged": "服务器上的历史记录已变化，请重新打开。",
+        "restoreFailed": "恢复失败，请重试。",
+        "userEdit": "手动修改",
+        "showVersions": "显示版本",
+        "hideVersions": "隐藏版本"
     }
 }

lib/utils.ts

@@ -2,8 +2,6 @@ import { type ClassValue, clsx } from "clsx"
 import * as pako from "pako"
 import { twMerge } from "tailwind-merge"
 import { hasCells } from "@/packages/mcp-server/src/pages.ts"
-import { readStyleClasses } from "@/packages/mcp-server/src/style-classes.ts"
-import { repairQuoteBeforeSlash } from "@/packages/mcp-server/src/xml-validation.ts"
 
 export function cn(...inputs: ClassValue[]) {
     return twMerge(clsx(inputs))
@@ -34,55 +32,7 @@ export function isRealDiagram(xml: string | undefined | null): boolean {
 // mxCell XML Helpers
 // ============================================================================
 
-/**
- * Check if mxCell XML output is complete (not truncated).
- * Complete XML ends with a self-closing tag (/>) or closing mxCell tag.
- * Uses a robust approach that handles any LLM provider's wrapper tags
- * by finding the last valid mxCell ending and checking if suffix is just closing tags.
- * @param xml - The XML string to check (can be undefined/null)
- * @returns true if XML appears complete, false if truncated or empty
- */
-export function isMxCellXmlComplete(xml: string | undefined | null): boolean {
-    // Named style definitions before the cells are not cells: output cut off
-    // right after them is incomplete. A compact cell whose last quote is
-    // missing is complete; prepareNewDiagram repairs it.
-    const trimmed = repairQuoteBeforeSlash(
-        readStyleClasses(xml || "").xml,
-    ).trim()
-    if (!trimmed) return false
-
-    // Find position of last complete mxCell ending (either /> or </mxCell>)
-    const lastSelfClose = trimmed.lastIndexOf("/>")
-    const lastMxCellClose = trimmed.lastIndexOf("</mxCell>")
-
-    const lastValidEnd = Math.max(lastSelfClose, lastMxCellClose)
-
-    // No valid ending found at all
-    if (lastValidEnd === -1) return false
-
-    // If the last mxCell has no </mxCell> after it, it must be self-closing.
-    // Otherwise the trailing "/>" belongs to a child such as <mxGeometry .../>
-    // and the output was cut off before the cell was closed.
-    const lastCellStart = trimmed.lastIndexOf("<mxCell")
-    if (
-        lastCellStart > lastMxCellClose &&
-        // (quoted values may hold a raw "<", which the auto-fix escapes)
-        !/^<mxCell\b(?:[^<>"']|"[^"]*"|'[^']*')*\/>/.test(
-            trimmed.slice(lastCellStart),
-        )
-    ) {
-        return false
-    }
-
-    // Check what comes after the last valid ending
-    // For />: add 2 chars, for </mxCell>: add 9 chars
-    const endOffset = lastMxCellClose > lastSelfClose ? 9 : 2
-    const suffix = trimmed.slice(lastValidEnd + endOffset)
-
-    // If suffix is empty or only contains closing tags (any provider's wrapper) or whitespace, it's complete
-    // This regex matches any sequence of closing XML tags like </foo>, </bar>, </｜DSML｜xyz>
-    return /^(\s*<\/[^>]+>)*\s*$/.test(suffix)
-}
+export { isMxCellXmlComplete } from "@/packages/mcp-server/src/new-diagram.ts"
 
 /**
  * Extract only complete mxCell elements from partial/streaming XML.

lib/version-text.ts

@@ -17,7 +17,7 @@ const PARTS: [keyof ChangeSummary, string][] = [
  * singular (...One) and plural (...Other) form; languages without plurals
  * use the same text for both.
  */
-export function describeChanges(
+export function describeChangeSummary(
     summary: ChangeSummary,
     t: VersionDict,
 ): string {

package-lock.json

@@ -75,7 +75,7 @@
             },
             "devDependencies": {
                 "@anthropic-ai/tokenizer": "^0.0.4",
-                "@biomejs/biome": "2.5.7",
+                "@biomejs/biome": "2.5.15",
                 "@playwright/test": "^1.57.0",
                 "@tailwindcss/postcss": "^4",
                 "@tailwindcss/typography": "^0.5.19",
@@ -100,6 +100,7 @@
                 "husky": "^9.1.7",
                 "jsdom": "^27.4.0",
                 "lint-staged": "^16.2.7",
+                "postcss": "^8.5.6",
                 "shx": "^0.4.0",
                 "tailwindcss": "^4",
                 "typescript": "^5",
@@ -2093,9 +2094,9 @@
             }
         },
         "node_modules/@biomejs/biome": {
-            "version": "2.5.7",
-            "resolved": "https://registry.npmjs.org/@biomejs/biome/-/biome-2.5.7.tgz",
-            "integrity": "sha512-zr8K/DcY5tYsQOQwqMJ0AWElo6QgmgNI7idXgXLhevVszlt8RGVpesEJPqx3ThazLaOwjJ5Y8fz3BtH5fGZNsw==",
+            "version": "2.5.15",
+            "resolved": "https://registry.npmjs.org/@biomejs/biome/-/biome-2.5.15.tgz",
+            "integrity": "sha512-WZTW4slm/pdkh92K6t/3aEN++44JD1PQ7squ7RCMLI1flHGl43DVOIGXvCjHiZgBMO1V4uYxoFNtqrIA4qGuIQ==",
             "dev": true,
             "license": "MIT OR Apache-2.0",
             "bin": {
@@ -2109,20 +2110,20 @@
                 "url": "https://opencollective.com/biome"
             },
             "optionalDependencies": {
-                "@biomejs/cli-darwin-arm64": "2.5.7",
-                "@biomejs/cli-darwin-x64": "2.5.7",
-                "@biomejs/cli-linux-arm64": "2.5.7",
-                "@biomejs/cli-linux-arm64-musl": "2.5.7",
-                "@biomejs/cli-linux-x64": "2.5.7",
-                "@biomejs/cli-linux-x64-musl": "2.5.7",
-                "@biomejs/cli-win32-arm64": "2.5.7",
-                "@biomejs/cli-win32-x64": "2.5.7"
+                "@biomejs/cli-darwin-arm64": "2.5.15",
+                "@biomejs/cli-darwin-x64": "2.5.15",
+                "@biomejs/cli-linux-arm64": "2.5.15",
+                "@biomejs/cli-linux-arm64-musl": "2.5.15",
+                "@biomejs/cli-linux-x64": "2.5.15",
+                "@biomejs/cli-linux-x64-musl": "2.5.15",
+                "@biomejs/cli-win32-arm64": "2.5.15",
+                "@biomejs/cli-win32-x64": "2.5.15"
             }
         },
         "node_modules/@biomejs/cli-darwin-arm64": {
-            "version": "2.5.7",
-            "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-arm64/-/cli-darwin-arm64-2.5.7.tgz",
-            "integrity": "sha512-vxo/Ls3/PYdQWyLhYYcgMOCzQypAjcY+iihS8M0wW03l16TCLW4zqZzGo75gm1VdCMj38hTVZ31KBWrZ4G9dJw==",
+            "version": "2.5.15",
+            "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-arm64/-/cli-darwin-arm64-2.5.15.tgz",
+            "integrity": "sha512-BZVzFhJ/mUvTLMYbc9x6el0o2Uv5zP7bACYyhFb6fSc1giroXm7PL0a5KqMJ9F+/BnkYRjagD/ROSDVOZ6eapg==",
             "cpu": [
                 "arm64"
             ],
@@ -2137,9 +2138,9 @@
             }
         },
         "node_modules/@biomejs/cli-darwin-x64": {
-            "version": "2.5.7",
-            "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-x64/-/cli-darwin-x64-2.5.7.tgz",
-            "integrity": "sha512-Cd3Ga61amT/Yl/0x8elP5hhGYaFy4bw6WuysTgf7oo8TA5tJ5A1k+DkVoJ2BHbTVil51gTX9VPzArnrlLJ3Kyg==",
+            "version": "2.5.15",
+            "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-x64/-/cli-darwin-x64-2.5.15.tgz",
+            "integrity": "sha512-V5Kw63V+fVGNFhFrizDxMbGXAzZCh8kYzJpy3GI6gTapWDg7bZK9oYC9CbVgQSEdTnupz0U5Efz8Ev+5vdBBXw==",
             "cpu": [
                 "x64"
             ],
@@ -2154,9 +2155,9 @@
             }
         },
         "node_modules/@biomejs/cli-linux-arm64": {
-            "version": "2.5.7",
-            "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64/-/cli-linux-arm64-2.5.7.tgz",
-            "integrity": "sha512-rR2QE0yF2GYSuYuKIa7pKvODGJqnOH+2eDREAM8wV+mWKSkMQKdAp4zXEZfTaxY8PMoNONnpgSWcBCyLDPDOKg==",
+            "version": "2.5.15",
+            "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64/-/cli-linux-arm64-2.5.15.tgz",
+            "integrity": "sha512-XaG7P7eeSLYETD3K9grfB0mQmpLQZjygdbsxekWBJAg4am79fGAtRpfRyNnTvXB2fZFNnJZG3nXm7HBat0+VUw==",
             "cpu": [
                 "arm64"
             ],
@@ -2174,9 +2175,9 @@
             }
         },
         "node_modules/@biomejs/cli-linux-arm64-musl": {
-            "version": "2.5.7",
-            "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64-musl/-/cli-linux-arm64-musl-2.5.7.tgz",
-            "integrity": "sha512-xPI5yB6XlpDbNkS+bm1t42olw5c4l3UrlOmLg7KtLJvjvkNF/1V4tnUgfkylGIeb3u/T+BzMGYqgQhzjAoJzuQ==",
+            "version": "2.5.15",
+            "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64-musl/-/cli-linux-arm64-musl-2.5.15.tgz",
+            "integrity": "sha512-tGzZUTcJCV7tj5Adh/Gn6nR4MycqA3iohq2LEcrarAgRBkU0h0OKd2UzCRkOsOYOuUGaUJb4YmqRqyy2feGGSw==",
             "cpu": [
                 "arm64"
             ],
@@ -2194,9 +2195,9 @@
             }
         },
         "node_modules/@biomejs/cli-linux-x64": {
-            "version": "2.5.7",
-            "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64/-/cli-linux-x64-2.5.7.tgz",
-            "integrity": "sha512-FQgqJhscrqJUFptGaRSUJWlXAExwWcDwLuK49dvKfkQ1bB5SEEyFssnsxQY83Xm6jR0EbbX3+8+D5bfvYqUG2Q==",
+            "version": "2.5.15",
+            "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64/-/cli-linux-x64-2.5.15.tgz",
+            "integrity": "sha512-xE4iEW/3LqlYj9GFgGrFsFSH51dEEpUbYWBfeOv0q87WkUDxK2o/HhreSb7qMJqck70RVM6Lg96hgedcAYcOkA==",
             "cpu": [
                 "x64"
             ],
@@ -2214,9 +2215,9 @@
             }
         },
         "node_modules/@biomejs/cli-linux-x64-musl": {
-            "version": "2.5.7",
-            "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64-musl/-/cli-linux-x64-musl-2.5.7.tgz",
-            "integrity": "sha512-rE5VZi+qtmPgQH+l7jVxYoZ18b/TiHEhulhMpjmCZH1PltSbjRcxNWywC3HZ9tYottG7ORkeTtoscBilKSBm0g==",
+            "version": "2.5.15",
+            "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64-musl/-/cli-linux-x64-musl-2.5.15.tgz",
+            "integrity": "sha512-IlxUcyxilVGPsE008x13pWdkTbU3nQpP2i9b5UrbOYj6goBkKsRX1XB7yJLcV+O1H9LBchIIm4adOaVLZBX0ZQ==",
             "cpu": [
                 "x64"
             ],
@@ -2234,9 +2235,9 @@
             }
         },
         "node_modules/@biomejs/cli-win32-arm64": {
-            "version": "2.5.7",
-            "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-arm64/-/cli-win32-arm64-2.5.7.tgz",
-            "integrity": "sha512-Oq4x0CCwP4jirrcTywXs5kOGZ4v5vuEP+gWrbtjApOA2CL9F3F9GlIdQIci8AKSCa/zURanMRpX/4wQ7Am6hHg==",
+            "version": "2.5.15",
+            "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-arm64/-/cli-win32-arm64-2.5.15.tgz",
+            "integrity": "sha512-2kPKzhNlm8C+Ru3GcO0Me2ODkCBLrVOUNuyi84RJyWDVKAA4+Kjj3jMjL938lF6BRfvltC4vB2nPY9SvN51Ovg==",
             "cpu": [
                 "arm64"
             ],
@@ -2251,9 +2252,9 @@
             }
         },
         "node_modules/@biomejs/cli-win32-x64": {
-            "version": "2.5.7",
-            "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-x64/-/cli-win32-x64-2.5.7.tgz",
-            "integrity": "sha512-V+0wu/nrj2S+MhP4EQ0uHNolP0IALEsz45pg0WoKkHfDeh0+ItHwP/p7bX5RPoMOl9NkpHYWdYPhIcy2mACHvQ==",
+            "version": "2.5.15",
+            "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-x64/-/cli-win32-x64-2.5.15.tgz",
+            "integrity": "sha512-yAzh4UqEImV6Hcy0zjUqNfJAsUhoD64FBQCdTG8Md/Z2wQeVP/ZmJ3XRYAs1g8J9fjTFyl2fCtc5FB5til47+g==",
             "cpu": [
                 "x64"
             ],

package.json

@@ -110,7 +110,7 @@
     },
     "devDependencies": {
         "@anthropic-ai/tokenizer": "^0.0.4",
-        "@biomejs/biome": "2.5.7",
+        "@biomejs/biome": "2.5.15",
         "@playwright/test": "^1.57.0",
         "@tailwindcss/postcss": "^4",
         "@tailwindcss/typography": "^0.5.19",
@@ -135,6 +135,7 @@
         "husky": "^9.1.7",
         "jsdom": "^27.4.0",
         "lint-staged": "^16.2.7",
+        "postcss": "^8.5.6",
         "shx": "^0.4.0",
         "tailwindcss": "^4",
         "typescript": "^5",

packages/claude-plugin/README.md

@@ -24,15 +24,18 @@ claude mcp add drawio -- npx @next-ai-drawio/mcp-server@latest
 
 ## Features
 
-- **Real-time Preview**: Diagrams appear and update in your browser as Claude creates them
+- **Real-time Preview**: Diagrams appear and update in your browser as Claude creates them. The preview is the web app's canvas: a change Claude makes to the page on screen is outlined, and one Ctrl+Z takes it back
+- **Selection**: Select shapes in the preview and say "move these"; Claude reads what you selected with `get_selection`
 - **Drawing Rules and Shape Libraries**: Claude gets the web app's layout and style rules and the icon docs for AWS, Azure, GCP, Kubernetes and more
 - **Self-check**: Claude can take a screenshot of the rendered diagram and fix what looks wrong
-- **Version History**: Restore one of the last 20 versions from the **History** button, shown as thumbnails
+- **Draw from Your Files**: ask Claude to draw from a document, image or web page; it reads the source with its own tools and draws. Existing .drawio files open with load_diagram
+- **Version History**: The last 20 versions appear as cards next to the canvas, with thumbnails; restore one, undo the latest, or compare a version with the canvas
 - **Natural Language**: Describe diagrams in plain text - flowcharts, architecture diagrams, etc.
 - **Edit Support**: Modify existing diagrams with natural language instructions, including your own edits in the browser
 - **Export**: Save diagrams as `.drawio`, `.png`, `.svg`, or `.drawio.svg` files
 - **Auto-save**: Each diagram is saved to `~/.next-ai-drawio/`, so `claude --resume` can pick it up again
-- **Self-contained**: Embedded server, no external dependencies required
+- **Custom Instructions**: keep your own drawing rules in `~/.next-ai-drawio/instructions.md` (for example "Always draw in minimal style"); they are appended to the drawing guide on every call
+- **Self-contained**: Embedded server and the draw.io editor in one package; the preview works offline after install
 
 ## Use Case Examples
 
@@ -71,20 +74,35 @@ Create a sequence diagram showing OAuth 2.0 authorization code flow
 between user, client app, auth server, and resource server
 ```
 
+### 6. Draw From a Document
+
+```
+Read docs/architecture.md and draw the system as a diagram
+```
+
+### 7. Recreate a Sketch
+
+```
+Recreate the whiteboard photo at ~/Desktop/sketch.jpg as a clean draw.io diagram
+```
+
 ## Available Tools
 
 | Tool | Description |
 |------|-------------|
-| `start_session` | Opens browser with real-time diagram preview; the result includes the drawing rules |
+| `start_session` | Opens browser with real-time diagram preview; the result includes the drawing rules. Pass `session_id` to continue a saved diagram |
+| `list_saved_diagrams` | List the auto-saved diagrams of earlier sessions, newest first, with their pages |
 | `get_drawing_guide` | Return the drawing rules again |
 | `get_shape_library` | Return the shapes and icon styles of a library such as `aws4` |
 | `create_new_diagram` | Create a new diagram from XML |
-| `load_diagram` | Load a `.drawio` file from disk |
+| `load_diagram` | Load a `.drawio` or `.drawio.svg` file from disk |
 | `edit_diagram` | Edit diagram by ID-based operations; all or nothing |
 | `get_diagram` | Get the current diagram XML |
+| `get_selection` | Return the shapes and edges you selected in the preview, so Claude can act on "these" |
 | `screenshot_diagram` | Return a PNG of a page so Claude can check the result |
 | `export_diagram` | Save diagram to a `.drawio`, `.png`, `.svg`, or `.drawio.svg` file |
 | `list_pages`, `add_page`, `rename_page`, `delete_page` | Work with multi-page diagrams |
+| `restore_version` | Undo: go back to an earlier version from History (redo is possible too) |
 
 ## How It Works
 
@@ -102,8 +120,13 @@ Claude Code <--stdio--> MCP Server <--http--> Browser (draw.io)
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `PORT` | `6002` | Port for the embedded HTTP server |
-| `DRAWIO_BASE_URL` | `https://embed.diagrams.net` | Base URL for draw.io (for self-hosted deployments) |
-| `DRAWIO_DATA_DIR` | `~/.next-ai-drawio` | Folder for auto-saved diagrams; `off` turns auto-save off |
+| `DRAWIO_BASE_URL` | unset (the bundled draw.io) | An external draw.io, such as a self-hosted instance. With it Claude's changes are not outlined on the canvas, Ctrl+Z does not take them back and `get_selection` cannot read the selection |
+| `DRAWIO_DATA_DIR` | `~/.next-ai-drawio` | Folder for auto-saved diagrams and your `instructions.md`; `off` turns auto-save off (`instructions.md` is then read from the default folder) |
+| `DRAWIO_LANG` | unset | Language of the draw.io editor, such as `en`, `zh`, `zh-tw`, `ja` or `de`. Unset, draw.io chooses (the browser language on `embed.diagrams.net`, English on a self-hosted draw.io) and the user can change it under **Extras > Language** |
+| `DRAWIO_UI` | unset | draw.io theme: `kennedy`, `atlas`, `dark`, `min`, `sketch` or `simple`. Unset, the user picks one under **Extras > Theme** |
+| `DRAWIO_DARK` | `auto` | Dark mode of the preview and the editor until the user switches it with the button at the top right: `auto` follows the system, `1` starts dark, `0` starts light |
+| `DRAWIO_PREVIEW_UI` | `shell` | The preview page; `classic` opens the previous preview page for one more release |
+| `DRAWIO_AUTO_SCREENSHOT` | unset | Set to `true` to attach a screenshot to every `create_new_diagram` and `edit_diagram` result (costs 2 to 10 s per call) |
 | `DEBUG` | unset | Set to `true` to log debug messages |
 
 ## Links

packages/mcp-server/README.md

@@ -2,7 +2,7 @@
 
 MCP (Model Context Protocol) server that enables AI agents like Claude Desktop and Cursor to generate and edit draw.io diagrams with **real-time browser preview**.
 
-**Self-contained** - includes an embedded HTTP server, no external dependencies required.
+**Self-contained**: the embedded HTTP server and the draw.io editor are in the package, so after install the preview works offline.
 
 ## Quick Start
 
@@ -99,45 +99,63 @@ Use the standard MCP configuration with:
 1. Restart your MCP client after updating config
 2. Ask the AI to create a diagram:
    > "Create a flowchart showing user authentication with login, MFA, and session management"
+
+   > "Read docs/architecture.md and draw the system as a diagram"
 3. The diagram appears in your browser in real-time!
 
 ## Features
 
-- **Real-time Preview**: Diagrams appear and update in your browser as the AI creates them
+- **Real-time Preview**: Diagrams appear and update in your browser as the AI creates them. The preview is the web app's canvas: a change the AI makes to the page on screen is outlined, and one Ctrl+Z takes it back
+- **Selection**: Select shapes in the preview and say "move these" or "connect this box to that one"; the AI reads what you selected with `get_selection`
 - **Drawing Rules**: The AI gets the same layout, edge and style rules as the web app, plus the shape library docs (AWS, Azure, GCP, Kubernetes, Cisco and more), so it uses real icon names instead of guessing
-- **Self-check**: The AI can take a screenshot of the rendered diagram and fix overlapping shapes or edges that cross shapes
+- **Self-check**: The AI can take a screenshot of the rendered diagram (`screenshot: true` on `create_new_diagram` or `edit_diagram`, or `screenshot_diagram`) and fix overlapping shapes or edges that cross shapes
+- **Draw from Your Files**: ask the AI to draw from a document, image or web page; it reads the source with the host's own tools and draws. Existing .drawio files open with load_diagram
 - **Edit Support**: Modify existing diagrams with natural language instructions. If any change in an edit fails, nothing is written and the AI gets the reason and the current page XML
 - **Your Edits Are Kept**: Changes you make in the browser are read before the AI edits again. If the AI overwrites a change you were still making, your version is saved in History
-- **Version History**: Click **History** at the top right of the preview page to restore one of the last 20 versions, shown as thumbnails
-- **Download and Export**: Save as `.drawio`, `.png`, `.svg`, or `.drawio.svg` (an SVG with the diagram embedded, which draw.io can open and edit again), from the **Download** button or through `export_diagram`
+- **Version History**: The last 20 versions appear as cards next to the canvas, with a thumbnail and what changed. Restore one, undo and redo the latest, or compare a version with the canvas; or ask the AI to undo (`restore_version`)
+- **Export**: Save as `.drawio`, `.png`, `.svg`, or `.drawio.svg` (an SVG with the diagram embedded, which draw.io and `load_diagram` can open again) through `export_diagram`, or from the download button in the preview's header
 - **Multi-page**: List, add, rename, and delete pages, and edit any page
-- **Auto-save**: Each session's diagram is saved to `~/.next-ai-drawio/<session-id>.drawio`, so it survives a restart of the MCP client
-- **Themes and Dark Mode**: Pick a draw.io theme under **Extras > Theme**; the page follows the system dark mode
-- **Self-contained**: Embedded server, works offline (except draw.io UI which loads from `embed.diagrams.net` by default, configurable via `DRAWIO_BASE_URL`)
+- **Auto-save**: Each session's diagram is saved to `~/.next-ai-drawio/<session-id>.drawio`, and its last 20 versions to `<session-id>.history.json`, so the diagram, History and undo survive a restart of the MCP client
+- **Custom Instructions**: keep your own drawing rules in `~/.next-ai-drawio/instructions.md` (for example "Always draw in minimal style"); they are appended to the drawing guide on every call
+- **Themes and Dark Mode**: Pick a draw.io theme under **Extras > Theme**; the button at the top right switches the page and the editor between light and dark (the system setting until you choose). `DRAWIO_UI`, `DRAWIO_DARK` and `DRAWIO_LANG` fix them
+- **Self-contained**: The draw.io editor ships inside the package and is served from the preview's own origin, so after install the preview works offline. `DRAWIO_BASE_URL` points it at another draw.io instead
 
 ## Available Tools
 
 | Tool | Description |
 |------|-------------|
-| `start_session` | Opens browser with real-time diagram preview; the result includes the drawing rules |
-| `get_drawing_guide` | Return the drawing rules again, for example after a long conversation was compacted |
+| `start_session` | Opens browser with real-time diagram preview; the result includes the drawing rules. Pass `session_id` to continue a saved diagram |
+| `list_saved_diagrams` | List the auto-saved diagrams of earlier sessions, newest first, with their pages |
+| `get_drawing_guide` | Return the drawing rules again, for example after a long conversation was compacted, or, with `topic`, a short XML reference for tables, layers or groups |
 | `get_shape_library` | Return the shapes and icon styles of a library such as `aws4`, `azure2`, or `kubernetes` |
 | `create_new_diagram` | Create a new diagram from XML; a plain list of `mxCell` elements is enough |
-| `load_diagram` | Load a `.drawio` file from disk into the session (handles compressed files) |
+| `load_diagram` | Load a `.drawio` or `.drawio.svg` file into the session, from a `path` on disk or from its `xml` content (handles compressed files) |
 | `edit_diagram` | Edit diagram by ID-based operations (update/add/delete cells); all or nothing |
 | `get_diagram` | Get the current diagram XML, including your edits in the browser |
+| `get_selection` | Return the shapes and edges you selected in the preview (ids, labels, positions), so the AI can act on "these" |
 | `screenshot_diagram` | Return a PNG of a page so the AI can check the rendered diagram |
 | `export_diagram` | Save diagram to a `.drawio`, `.png`, `.svg`, or `.drawio.svg` file |
 | `list_pages` | List every page (tab) with id, name, index, and cell count |
 | `add_page` | Append a new page without touching existing ones |
 | `rename_page` | Rename a page |
 | `delete_page` | Delete a page (refuses to delete the last one) |
+| `restore_version` | Undo: put an earlier version from History back on the canvas; the current one is kept, so a redo is possible |
 
 ## Continue a Diagram Later
 
-After every change, the diagram is saved as a normal `.drawio` file in `~/.next-ai-drawio/`, and `start_session` tells the AI the file path. When you resume a conversation after restarting your MCP client (for example `claude --resume`), the AI calls `start_session` and then `load_diagram` with that path. You can also open the file in draw.io yourself.
+After every change, the diagram is saved as a normal `.drawio` file in `~/.next-ai-drawio/`, named after the session id (for example `mcp-mgd0a1b2-x7k2p1.drawio`). `start_session` tells the AI both the id and the file path.
 
-The newest 50 files are kept. Set `DRAWIO_DATA_DIR` to use another folder, or to `off` to turn auto-save off.
+To continue a diagram in a later conversation (for example after `claude --resume`, or in a new chat), the AI calls `start_session` with `session_id` set to that id: the same preview URL opens, the saved diagram is shown, and auto-save keeps writing to the same file. If the id is no longer in the conversation, `list_saved_diagrams` returns every saved diagram, newest first, with the names and cell counts of its pages, so you can ask for "the architecture diagram from yesterday" and let the AI pick it. `load_diagram` with the file path still works too, and you can open the file in draw.io yourself.
+
+History comes back with the diagram: the last 20 versions are saved next to it in `<session-id>.history.json` (without thumbnails). When the AI continues the session with `start_session` and its `session_id`, or a preview tab is still open after a restart, the version cards show them again and `restore_version` can undo to them.
+
+The newest 50 files are kept, each with its History file. Set `DRAWIO_DATA_DIR` to use another folder, or to `off` to turn auto-save off.
+
+## Custom Instructions
+
+To give the AI your own drawing rules, write them in `~/.next-ai-drawio/instructions.md` as Markdown, for example "Always draw in minimal style" or "Label every edge". The file is appended to the drawing guide under a `## Custom Instructions` heading each time the guide is returned (`start_session`, `get_drawing_guide` and the `diagram-workflow` prompt), so edits apply without restarting your MCP client. Only the first 5000 characters are used.
+
+`DRAWIO_DATA_DIR` changes the folder the file is read from; with `DRAWIO_DATA_DIR=off` the default folder is still used, since the file is only read. The text reaches the model as it is, so keep it to drawing rules you trust.
 
 ## How It Works
 
@@ -159,16 +177,24 @@ The newest 50 files are kept. Set `DRAWIO_DATA_DIR` to use another folder, or to
 ```
 
 1. **MCP Server** receives tool calls from Claude via stdio
-2. **Embedded HTTP Server** serves the draw.io UI and handles state
+2. **Embedded HTTP Server** serves the preview page and the draw.io editor, and handles state
 3. **Browser** shows real-time diagram updates via polling
 
+The server listens on `127.0.0.1` only. Every `/api` request must carry a token that the server generates at start and writes into the preview page, so another website open in the same browser cannot read or change the diagram; the preview page also refuses to be embedded in other pages. Opening the preview URL in another browser on the same machine works, since the page comes with the token.
+
 ## Configuration
 
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `PORT` | `6002` | Port for the embedded HTTP server |
-| `DRAWIO_BASE_URL` | `https://embed.diagrams.net` | Base URL for the draw.io embed. Set this to use a self-hosted draw.io instance for private deployments. |
-| `DRAWIO_DATA_DIR` | `~/.next-ai-drawio` | Folder for the auto-saved `.drawio` files. Set to `off` to turn auto-save off. |
+| `DRAWIO_BASE_URL` | unset (the bundled draw.io) | An external draw.io for the preview, such as a self-hosted instance (see below). The page cannot reach into an editor from another origin, so with it the AI's changes are not outlined, Ctrl+Z does not take them back and `get_selection` cannot read the selection. The version cards and everything else keep working. |
+| `DRAWIO_DATA_DIR` | `~/.next-ai-drawio` | Folder for the auto-saved `.drawio` files and your `instructions.md`. Set to `off` to turn auto-save off (`instructions.md` is then read from the default folder). |
+| `DRAWIO_LANG` | unset | Language of the draw.io editor and of the preview's own texts. Unset, the preview's texts follow the browser language, and draw.io chooses: English on the bundled copy until the user picks one under **Extras > Language**, the browser language on `embed.diagrams.net`. A code such as `en`, `zh`, `zh-tw`, `ja` or `de` fixes both and hides that submenu. |
+| `DRAWIO_UI` | unset | draw.io theme. Unset, the user picks one under **Extras > Theme** and draw.io remembers it. `kennedy`, `atlas`, `dark`, `min`, `sketch` or `simple` fixes the theme and hides that menu. |
+| `DRAWIO_DARK` | `auto` | Dark mode of the preview and the editor until the user switches it with the button at the top right (the browser remembers that choice): `auto` follows the system, `1` starts dark, `0` starts light. |
+| `DRAWIO_PREVIEW_UI` | `shell` | The preview page `start_session` opens. `classic` opens the previous preview page (see [Classic preview page](#classic-preview-page)). |
+| `DRAWIO_AUTO_SCREENSHOT` | unset | Set to `true` to attach a screenshot to every `create_new_diagram` and `edit_diagram` result, so the AI checks each drawing. Costs 2 to 10 s per call; the preview tab must be open and in front. A call can still pass `screenshot: false`. |
+| `BROWSER` | unset | Set to `none` and `start_session` does not open the preview in the system browser (the convention of Vite and Create React App dev servers); the result still names the URL. |
 | `DEBUG` | unset | Set to `true` to log debug messages to stderr. |
 
 ### Private Deployment (Self-hosted draw.io)
@@ -197,6 +223,16 @@ docker run -d -p 8080:8080 jgraph/drawio
 
 Then set `DRAWIO_BASE_URL=http://localhost:8080` (or your server's URL). The preview page loads nothing else from the internet, so with a local draw.io it works offline. One exception: shapes from the Material Design library show icons from `fonts.gstatic.com`.
 
+With an external draw.io the preview cannot reach into the editor (browsers keep pages and frames from other origins apart), so the AI's changes are not outlined on the canvas, Ctrl+Z does not take them back (use the version cards or `restore_version`), and `get_selection` cannot read what you selected. `start_session` tells the AI about this mode.
+
+Without `DRAWIO_BASE_URL` the preview uses the trimmed draw.io copy bundled with this package. It has the editor, the shape libraries, the templates, PlantUML and Mermaid; features that load more code when used (the org chart layout, for example) are not included. Set `DRAWIO_BASE_URL` to a full draw.io if you need them.
+
+Like the web app's bundled copy, it has no image proxy (`/drawio/proxy`): images from other websites, including the avatars in the Org Chart and Mind Map templates and the Arista icons in the network templates, show on the canvas only when online and are left out of PNG and SVG exports and version thumbnails. Insert such images from a file instead, or set `DRAWIO_BASE_URL` to a full draw.io (the `jgraph/drawio` Docker image includes the proxy). See [Offline deployment](https://github.com/DayuanJiang/next-ai-draw-io/blob/main/docs/en/offline-deployment.md).
+
+### Classic preview page
+
+`DRAWIO_PREVIEW_UI=classic` opens the preview page of the previous releases: draw.io with a **History** dialog and a **Download** button, without the outline of the AI's changes, Ctrl+Z for them, the version cards, Compare and `get_selection`. It stays for one more release and is then removed.
+
 ## Troubleshooting
 
 ### Port already in use
@@ -228,6 +264,10 @@ Check that the browser URL has the `?mcp=` query parameter. The MCP session ID c
 
 PNG and SVG files are rendered by draw.io in the preview tab. Browsers slow down tabs that stay in the background, so the tab may not answer in time. Bring the preview tab to the front and try again.
 
+### Preview is blank inside VS Code Simple Browser
+
+The preview page refuses to be embedded in other pages (it sends `Content-Security-Policy: frame-ancestors 'self'`), so in-editor browsers such as VS Code Simple Browser, Cursor's built-in browser or a port forward's "Preview in Editor" show a blank page. Open the Browser URL from the `start_session` result in a regular browser (Chrome, Edge, Firefox, Safari) instead.
+
 ## License
 
 Apache-2.0

packages/mcp-server/drawio-files.txt

@@ -0,0 +1,40 @@
+# Files copied from draw.war into dist/drawio by scripts/fetch-drawio.mjs
+# (the preview page embeds this copy from its own origin). `*` matches within
+# a path segment, `**` across segments.
+#
+# Always included: the language files, the image icon libraries (loaded one
+# icon at a time, as diagrams use them), the stylesheets, the licenses of the
+# icon sets, the templates of Insert > Template (the guard only sees the
+# previews it scrolled to) and the PlantUML parser of Insert > Advanced.
+images/osa_drive-harddisk.png
+img/LICENSE
+img/lib/**
+js/plantuml/drawio-plantuml.min.js
+mxgraph/css/**
+resources/dia*.txt
+shapes/LICENSE
+stencils/LICENSE
+styles/**
+templates/**
+
+# Requested by the editor; rewritten by scripts/check-drawio-files.mjs --update
+images/droptarget.png
+images/github-logo.svg
+images/logo-flat-small.png
+images/sidebar-general.png
+images/spin.gif
+img/clipart/Gear_128x128.png
+index.html
+js/PostConfig.js
+js/PreConfig.js
+js/app.min.js
+js/bootstrap.js
+js/extensions.min.js
+js/main.js
+js/open.js
+js/shapes-14-6-5.min.js
+js/stencils.min.js
+math4/es5/drawio-mathjax.min.js
+mxgraph/images/maximize.gif
+open.html
+shortcuts.svg

packages/mcp-server/package-lock.json

@@ -1,12 +1,12 @@
 {
     "name": "@next-ai-drawio/mcp-server",
-    "version": "0.3.0",
+    "version": "0.4.0",
     "lockfileVersion": 3,
     "requires": true,
     "packages": {
         "": {
             "name": "@next-ai-drawio/mcp-server",
-            "version": "0.3.0",
+            "version": "0.4.0",
             "license": "Apache-2.0",
             "dependencies": {
                 "@modelcontextprotocol/sdk": "^1.31.0",

packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@next-ai-drawio/mcp-server",
-    "version": "0.3.0",
+    "version": "0.4.0",
     "description": "MCP server for Next AI Draw.io - AI-powered diagram generation with real-time browser preview",
     "type": "module",
     "main": "dist/index.js",
@@ -8,12 +8,14 @@
         "next-ai-drawio-mcp": "./dist/index.js"
     },
     "scripts": {
-        "build": "tsc && node scripts/copy-assets.mjs",
+        "build": "tsc && tsc -p shell && node scripts/copy-assets.mjs && node scripts/fetch-drawio.mjs && node scripts/build-shell.mjs",
+        "check-drawio": "node scripts/check-drawio-files.mjs",
         "check-package": "node scripts/check-package.mjs",
         "dev": "tsx watch src/index.ts",
         "start": "node dist/index.js",
         "test": "vitest run",
         "test:watch": "vitest",
+        "test:e2e": "playwright test",
         "prepublishOnly": "npm run build"
     },
     "keywords": [

packages/mcp-server/playwright.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from "@playwright/test"
+
+// Browser tests of the built package (npm run build first): each spec
+// starts the MCP server itself over stdio, so there is no web server here.
+// Playwright comes from the repository root (npm ci there).
+export default defineConfig({
+    testDir: "./tests/e2e",
+    timeout: 90_000,
+    forbidOnly: !!process.env.CI,
+    retries: process.env.CI ? 1 : 0,
+    reporter: "list",
+    use: {
+        browserName: "chromium",
+        trace: "retain-on-failure",
+    },
+})

packages/mcp-server/scripts/build-shell.mjs

@@ -0,0 +1,79 @@
+// Build the canvas shell (shell/, the web app's canvas without the chat)
+// into dist/shell: shell.js with esbuild, shell.css with Tailwind, and the
+// page template. Needs the repository checked out with its root
+// devDependencies installed (esbuild, Tailwind, React and the shared
+// components come from there), like copy-assets.mjs needs ../../docs.
+import { cpSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { createRequire } from "node:module"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const pkg = join(dirname(fileURLToPath(import.meta.url)), "..")
+const root = join(pkg, "../..")
+const shell = join(pkg, "shell")
+const out = join(pkg, "dist/shell")
+
+// The root's copies: the shell's React must be the one the shared
+// components import, and the MCP core's pako and saxes should not be
+// bundled twice (packages/mcp-server has its own node_modules)
+const rootRequire = createRequire(join(root, "package.json"))
+const rootPackage = (name) =>
+    dirname(rootRequire.resolve(`${name}/package.json`))
+const { build } = await import(rootRequire.resolve("esbuild"))
+const postcss = (await import(rootRequire.resolve("postcss"))).default
+const tailwindcss = (await import(rootRequire.resolve("@tailwindcss/postcss")))
+    .default
+
+mkdirSync(out, { recursive: true })
+
+const result = await build({
+    entryPoints: [join(shell, "main.tsx")],
+    outfile: join(out, "shell.js"),
+    bundle: true,
+    minify: true,
+    format: "esm",
+    target: "es2022",
+    platform: "browser",
+    jsx: "automatic",
+    metafile: true,
+    absWorkingDir: root,
+    alias: {
+        "@": root,
+        pako: rootPackage("pako"),
+        saxes: rootPackage("saxes"),
+    },
+    define: {
+        "process.env.NODE_ENV": '"production"',
+        // The shell has no base path and takes its draw.io from the config
+        // the server writes into the page, not from the web app's build
+        // settings
+        "process.env.NEXT_PUBLIC_BASE_PATH": '""',
+        "process.env.NEXT_PUBLIC_DRAWIO_BASE_URL": '""',
+    },
+})
+const js = readFileSync(join(out, "shell.js"), "utf8")
+// A reference that the defines above missed would throw in the browser
+// ("process is not defined")
+const leftover = js.match(/process\.env\.[A-Z_]+/)
+if (leftover) {
+    throw new Error(`shell.js still reads ${leftover[0]}; define it above`)
+}
+
+const cssFile = join(shell, "shell.css")
+const css = await postcss([
+    // Tailwind scans the shell directory on its own; shell.css names the
+    // shared component directories with @source
+    tailwindcss({ base: shell, optimize: { minify: true } }),
+]).process(readFileSync(cssFile, "utf8"), {
+    from: cssFile,
+    to: join(out, "shell.css"),
+})
+writeFileSync(join(out, "shell.css"), css.css)
+
+cpSync(join(shell, "index.html"), join(out, "index.html"))
+
+const kb = (n) => `${(n / 1024).toFixed(0)} KB`
+const bundled = Object.values(result.metafile.outputs).find((o) => o.entryPoint)
+console.log(
+    `shell: shell.js ${kb(bundled.bytes)}, shell.css ${kb(Buffer.byteLength(css.css))} -> ${out}`,
+)

packages/mcp-server/scripts/check-drawio-files.mjs

@@ -0,0 +1,533 @@
+#!/usr/bin/env node
+import {
+    existsSync,
+    readdirSync,
+    readFileSync,
+    statSync,
+    writeFileSync,
+} from "node:fs"
+/**
+ * Guard for drawio-files.txt: opens the embedded editor from a FULL draw.io
+ * copy in headless Chromium, uses it the way the preview page does (every
+ * theme the user can switch to, diagrams with shapes from the icon libraries,
+ * the format panel, the shape sidebar, the menus, the page tabs, the export
+ * and edit dialogs, exports) and records every file the editor requests.
+ *
+ *   node scripts/check-drawio-files.mjs [--drawio <dir>] [--update]
+ *
+ * The full copy is --drawio, else the web app's public/drawio. Without
+ * --update it fails when the editor requested a file the list does not
+ * have; with --update it rewrites the requested section of the list.
+ * Needs Playwright from the repository root (npm ci at the root).
+ */
+import http from "node:http"
+import path from "node:path"
+import { fileURLToPath, pathToFileURL } from "node:url"
+import { readDrawioVersion } from "../../../scripts/drawio-zip.mjs"
+import {
+    formatFileList,
+    parseFileList,
+    readFileList,
+} from "./drawio-file-list.mjs"
+
+const PKG = path.join(path.dirname(fileURLToPath(import.meta.url)), "..")
+const LIST = path.join(PKG, "drawio-files.txt")
+const args = process.argv.slice(2)
+const update = args.includes("--update")
+const drawioDir = path.resolve(
+    args.includes("--drawio")
+        ? args[args.indexOf("--drawio") + 1]
+        : path.join(PKG, "../../public/drawio"),
+)
+if (!existsSync(path.join(drawioDir, "index.html"))) {
+    console.error(
+        `No draw.io copy at ${drawioDir}. Run "npm run dev" once at the repository root (it downloads one into public/drawio), or pass --drawio <dir>.`,
+    )
+    process.exit(2)
+}
+// The list is for the pinned release; the fetch scripts stamp the copy
+const { version } = readDrawioVersion()
+const stampFile = path.join(drawioDir, ".version")
+const stamp = existsSync(stampFile)
+    ? readFileSync(stampFile, "utf8").trim()
+    : null
+if (stamp !== version) {
+    console.error(
+        `${drawioDir} is draw.io ${stamp ?? "(no .version stamp)"}; the package pins ${version}. Delete it and run "npm run dev" at the repository root again, or pass --drawio <dir>.`,
+    )
+    process.exit(2)
+}
+const playwrightEntry = path.join(
+    PKG,
+    "../../node_modules/playwright/index.mjs",
+)
+if (!existsSync(playwrightEntry)) {
+    console.error("Playwright is missing: run npm ci at the repository root.")
+    process.exit(2)
+}
+const { chromium } = await import(pathToFileURL(playwrightEntry).href)
+
+// The themes a user can switch to under Extras > Theme (themes=1)
+const THEMES = ["kennedy", "min", "atlas", "dark", "sketch", "simple"]
+
+const MIME = {
+    ".html": "text/html",
+    ".js": "text/javascript",
+    ".css": "text/css",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".json": "application/json",
+    ".xml": "text/xml",
+    ".txt": "text/plain",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".ttf": "font/ttf",
+    ".ico": "image/x-icon",
+}
+
+// The page that embeds the editor, with the preview page's iframe query
+const parentPage = (ui) => `<!doctype html><html><body style="margin:0">
+<iframe id="f" style="width:1280px;height:860px;border:0" src="/drawio/index.html?embed=1&proto=json&configure=1&spin=1&libraries=1&noSaveBtn=1&noExitBtn=1&saveAndExit=0&themes=1&dark=0&ui=${ui}"></iframe>
+<script>
+const f = document.getElementById('f')
+window.exports = 0
+window.addEventListener('message', (e) => {
+    let m; try { m = JSON.parse(e.data) } catch { return }
+    if (m.event === 'configure') f.contentWindow.postMessage(JSON.stringify({ action: 'configure', config: {} }), '*')
+    if (m.event === 'init') window.ready = true
+    if (m.event === 'export') window.exports++
+})
+window.send = (msg) => f.contentWindow.postMessage(JSON.stringify(msg), '*')
+</script></body></html>`
+
+// Every path the editor asked for, in order; and the ones the full copy lacks
+const requested = []
+const notFound = new Set()
+const server = http.createServer((req, res) => {
+    const url = new URL(req.url, "http://localhost")
+    if (url.pathname === "/") {
+        res.writeHead(200, { "Content-Type": "text/html" })
+        res.end(parentPage(url.searchParams.get("ui") || "kennedy"))
+        return
+    }
+    const rel = path.posix.normalize(
+        decodeURIComponent(url.pathname.replace(/^\/drawio\//, "")),
+    )
+    const file = path.join(drawioDir, rel)
+    let stat
+    try {
+        stat = statSync(file)
+    } catch {
+        notFound.add(rel)
+        res.writeHead(404)
+        res.end()
+        return
+    }
+    if (!requested.includes(rel)) requested.push(rel)
+    res.writeHead(200, {
+        "Content-Type": MIME[path.extname(file)] || "application/octet-stream",
+        "Content-Length": stat.size,
+    })
+    res.end(readFileSync(file))
+})
+await new Promise((r) => server.listen(0, "127.0.0.1", r))
+const port = server.address().port
+
+const mb = (n) => (n / 1048576).toFixed(2)
+let seen = 0
+function report(step) {
+    const added = requested.slice(seen)
+    seen = requested.length
+    if (added.length === 0) return
+    const bytes = added.reduce(
+        (n, f) => n + statSync(path.join(drawioDir, f)).size,
+        0,
+    )
+    const names =
+        added.slice(0, 5).join(", ") + (added.length > 5 ? ", ..." : "")
+    console.log(
+        `  ${step}: +${added.length} files, +${mb(bytes)} MB [${names}]`,
+    )
+}
+
+// Diagrams: a plain shape, one shape from each icon library, and the styles
+// that make draw.io load code on demand (hand-drawn look, math)
+const cell = (id, style, x) =>
+    `<mxCell id="${id}" value="${id}" style="${style}" vertex="1" parent="1"><mxGeometry x="${x}" y="40" width="60" height="60" as="geometry"/></mxCell>`
+const doc = (cells, attrs = "") =>
+    `<mxfile><diagram id="p" name="P"><mxGraphModel ${attrs}><root><mxCell id="0"/><mxCell id="1" parent="0"/>${cells}</root></mxGraphModel></diagram></mxfile>`
+const LIBS = {
+    plain: "rounded=1;whiteSpace=wrap;html=1;",
+    aws4: "shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.a1_instance;fillColor=#ED7100;strokeColor=#ffffff;",
+    gcp2: "shape=mxgraph.gcp2.a7_power;fillColor=#4285F4;strokeColor=none;",
+    kubernetes:
+        "shape=mxgraph.kubernetes.icon;prIcon=api;fillColor=#326CE5;strokeColor=none;",
+    cisco19:
+        "shape=mxgraph.cisco19.rect;prIcon=aci;fillColor=#00bceb;strokeColor=none;",
+    flowchart:
+        "shape=mxgraph.flowchart.annotation_1;fillColor=#d5e8d4;strokeColor=#82b366;",
+    webicons:
+        "shape=mxgraph.webicons.adfty;fillColor=#3b5998;strokeColor=none;",
+    bpmn: "shape=mxgraph.bpmn.shape;symbol=message;outline=throwing;",
+    networks:
+        "shape=mxgraph.networks.server;fillColor=#29AAE1;strokeColor=none;",
+    azure2_image:
+        "image;aspect=fixed;image=img/lib/azure2/compute/Virtual_Machine.svg;",
+    sketch: "rounded=1;whiteSpace=wrap;html=1;sketch=1;",
+}
+const MATH_DOC = doc(
+    cell("math", "rounded=1;whiteSpace=wrap;html=1;", 40).replace(
+        'value="math"',
+        'value="$$x^2$$"',
+    ),
+    'math="1"',
+)
+
+// Dialogs and toggles, by draw.io action name (Actions.js); each is closed
+// again right after it opened. Insert > Template and Insert > Advanced >
+// PlantUML, which load files when used, are driven below. Mermaid needs no
+// extra files: its converter is in js/extensions.min.js, which the editor
+// loads at startup. Left out on purpose, to keep the package small: the org
+// chart layout (it loads js/orgchart.min.js). Not covered either: images
+// from other websites in some templates (Org Chart avatars, Arista icons)
+// and the /drawio/proxy requests draw.io makes for them when exporting;
+// the copy has no proxy, a known limitation (see the README).
+const ACTIONS = [
+    "editData",
+    "editDiagram",
+    "editStyle",
+    "editGeometry",
+    "editTooltip",
+    "editLink",
+    "insertImage",
+    "exportPng",
+    "exportSvg",
+    "exportJpg",
+    "exportWebp",
+    "exportPdf",
+    "exportXml",
+    "exportHtml",
+    "exportVsdx",
+    "embedHtml",
+    "embedImage",
+    "embedSvg",
+    "embedIframe",
+    "about",
+    "pageSetup",
+    "print",
+    "findReplace",
+    "tags",
+    "layers",
+    "outline",
+    "shapes",
+    "scratchpad",
+    "plugins",
+    "properties",
+    "fromText",
+    "csv",
+    "runLayout",
+    "insertFreehand",
+    "comments",
+    "customZoom",
+    "renamePage",
+    "format",
+    "format",
+    "toggleShapes",
+    "toggleShapes",
+    "darkMode",
+    "lightMode",
+    "autoMode",
+    "highContrast",
+    "highContrast",
+    "mathematicalTypesetting",
+    "mathematicalTypesetting",
+    "keyboardShortcuts",
+]
+// Enough for the other themes, whose dialogs are the same code
+const LIGHT_ACTIONS = ["editData", "exportPng", "shapes", "format", "format"]
+
+const wait = (page, ms) => page.waitForTimeout(ms)
+
+/**
+ * Open the editor in one theme and use it. The default theme gets the full
+ * tour; the others the parts that differ by theme (chrome, menus, panels).
+ */
+async function drive(browser, ui, full) {
+    console.log(`theme ${ui}${full ? "" : " (light)"}`)
+    const page = await browser.newPage({
+        viewport: { width: 1300, height: 900 },
+    })
+    page.on("popup", (p) => p.close().catch(() => {}))
+    await page.goto(`http://localhost:${port}/?ui=${ui}`)
+    await page.waitForFunction(() => window.ready === true, null, {
+        timeout: 60000,
+    })
+    await wait(page, 2000)
+    report("editor ready")
+
+    const load = (xml) =>
+        page.evaluate(
+            (x) => window.send({ action: "load", xml: x, autosave: 1 }),
+            xml,
+        )
+    let x = 40
+    for (const [name, style] of Object.entries(LIBS)) {
+        await load(doc(cell(name, style, (x += 100))))
+        await wait(page, full ? 1500 : 500)
+        report(`load ${name}`)
+        if (!full) break
+    }
+    if (full) {
+        await load(MATH_DOC)
+        await wait(page, 2500)
+        report("load math")
+    }
+
+    // The editor instance: in embed mode draw.io calls a plugin callback
+    // registered after startup right away
+    const frame = page.frames().find((f) => f.url().includes("/drawio/"))
+    await frame.evaluate(() => {
+        window.Draw.loadPlugin((u) => {
+            window.__ui = u
+        })
+        window.__ui.editor.graph.selectAll()
+    })
+    const closeAll = async () => {
+        await frame.evaluate(() => {
+            const ui = window.__ui
+            while (ui.dialogs && ui.dialogs.length > 0) ui.hideDialog()
+            ui.hideCurrentMenu?.()
+        })
+        await page.keyboard.press("Escape")
+        await wait(page, 100)
+    }
+
+    let opened = 0
+    const actions = full ? ACTIONS : LIGHT_ACTIONS
+    for (const name of actions) {
+        const result = await frame.evaluate((n) => {
+            const ui = window.__ui
+            const action = ui.actions.get(n)
+            if (!action) return "missing"
+            try {
+                action.funct()
+            } catch (e) {
+                return `failed: ${e.message}`
+            }
+            return ui.dialog || ui.dialogs?.length ? "dialog" : "ok"
+        }, name)
+        if (result === "dialog") opened++
+        if (result !== "ok" && result !== "dialog") {
+            console.log(`  action ${name}: ${result}`)
+        }
+        await wait(page, 400)
+        report(`action ${name}`)
+        await closeAll()
+    }
+    console.log(`  ${opened} of ${actions.length} actions opened a dialog`)
+
+    // File > Open Library from > Browser (libraries=1): the picker is an
+    // iframe on open.html, which loads js/open.js
+    await frame.evaluate(() => window.__ui.pickLibrary(window.App.MODE_BROWSER))
+    await wait(page, 1000)
+    report("library picker")
+    await closeAll()
+
+    // Menus: the visible menubar items, the toolbar buttons that open a menu
+    // in the other themes, and every menu rendered with its submenus
+    const menubarItems = frame.locator(".geMenubar .geItem:visible")
+    const menubarCount = await menubarItems.count()
+    for (let i = 0; i < menubarCount; i++) {
+        await menubarItems
+            .nth(i)
+            .click({ timeout: 2000 })
+            .catch(() => {})
+        await wait(page, 300)
+        await closeAll()
+    }
+    let toolbarCount = 0
+    for (const title of [
+        "Diagram",
+        "Insert",
+        "Shapes",
+        "Pages",
+        "View",
+        "Table",
+        "Layout",
+    ]) {
+        const button = frame.locator(`a[title="${title}"]:visible`).first()
+        if ((await button.count()) === 0) continue
+        toolbarCount++
+        await button.click({ timeout: 2000 }).catch(() => {})
+        await wait(page, 300)
+        await closeAll()
+    }
+    const failed = await frame.evaluate(() => {
+        const ui = window.__ui
+        const failed = []
+        for (const name of Object.keys(ui.menus.menus)) {
+            const menu = new window.mxPopupMenu()
+            menu.init()
+            document.body.appendChild(menu.div)
+            try {
+                ui.menus.get(name).funct(menu, null)
+            } catch {
+                failed.push(name)
+            }
+            menu.destroy()
+        }
+        return failed
+    })
+    await wait(page, 500)
+    console.log(
+        `  menus: ${menubarCount} menubar items, ${toolbarCount} toolbar menus clicked` +
+            (failed.length ? `; not rendered: ${failed.join(", ")}` : ""),
+    )
+    report("menus")
+
+    // Format panel tabs, with a shape selected
+    await frame.evaluate(() => window.__ui.editor.graph.selectAll())
+    for (const tab of ["Style", "Text", "Arrange", "Diagram"]) {
+        const el = frame
+            .locator(`.geFormatContainer div:text-is("${tab}")`)
+            .first()
+        if ((await el.count()) > 0)
+            await el.click({ timeout: 2000 }).catch(() => {})
+        await wait(page, 200)
+    }
+    report("format panel tabs")
+
+    // Shape sidebar: open every palette, then search
+    await frame.evaluate(() => {
+        const ui = window.__ui
+        for (const title of document.querySelectorAll(
+            ".geSidebarContainer .geTitle",
+        )) {
+            title.click()
+        }
+        ui.sidebar.searchShapes?.("server")
+    })
+    await wait(page, full ? 2500 : 1000)
+    report("sidebar palettes and search")
+
+    // Pages: insert, switch, duplicate, remove, and the tab bar
+    for (const name of [
+        "insertPage",
+        "nextPage",
+        "previousPage",
+        "duplicatePage",
+        "removePage",
+    ]) {
+        await frame.evaluate((n) => window.__ui.actions.get(n)?.funct(), name)
+        await wait(page, 150)
+        await closeAll()
+    }
+    for (const title of ["Insert Page", "Pages"]) {
+        const el = frame.locator(`a[title="${title}"]:visible`).first()
+        if ((await el.count()) > 0)
+            await el.click({ timeout: 2000 }).catch(() => {})
+        await wait(page, 300)
+        await closeAll()
+    }
+    report("page tabs")
+
+    if (full) {
+        // Insert > Advanced > PlantUML: the parser is loaded on first use
+        await frame.evaluate(() => window.__ui.actions.get("plantUml").funct())
+        await frame
+            .locator(".geDialog textarea")
+            .first()
+            .fill("@startuml\nA -> B\n@enduml")
+        await frame
+            .locator('.geDialog button:text-is("Insert")')
+            .first()
+            .click()
+        await wait(page, 3000)
+        report("plantUml insert")
+        await closeAll()
+
+        // Insert > Template: the index and the previews on screen
+        await frame.evaluate(() =>
+            window.__ui.actions.get("insertTemplate").funct(),
+        )
+        await wait(page, 2000)
+        report("template dialog")
+        await closeAll()
+
+        const formats = ["png", "svg", "xmlsvg", "xml"]
+        for (const [i, format] of formats.entries()) {
+            await page.evaluate(
+                (f) => window.send({ action: "export", format: f, scale: 2 }),
+                format,
+            )
+            await page
+                .waitForFunction((n) => window.exports >= n, i + 1, {
+                    timeout: 10000,
+                })
+                .catch(() => {})
+            report(`export ${format}`)
+        }
+        const exports = await page.evaluate(() => window.exports)
+        if (exports < formats.length) {
+            console.error(
+                `  only ${exports} of ${formats.length} exports answered`,
+            )
+            process.exitCode = 1
+        }
+    }
+    await page.close()
+}
+
+const browser = await chromium.launch()
+try {
+    for (const ui of THEMES) await drive(browser, ui, ui === THEMES[0])
+} finally {
+    await browser.close()
+    server.close()
+}
+
+// A full copy has every file the editor asks for; 404s mean this is not one
+if (notFound.size > 0) {
+    console.error(
+        `\nThe editor requested ${notFound.size} files that ${drawioDir} does not have (not a full draw.io copy?):\n  ${[...notFound].join("\n  ")}`,
+    )
+    process.exit(1)
+}
+
+// Compare with the list
+const list = readFileList(LIST)
+const missing = requested.filter((f) => !list.matches(f)).sort()
+
+function* walk(dir) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name)
+        if (entry.isDirectory()) yield* walk(full)
+        else yield path.relative(drawioDir, full).split(path.sep).join("/")
+    }
+}
+const summarize = (fileList) => {
+    let count = 0
+    let bytes = 0
+    for (const rel of walk(drawioDir)) {
+        if (!fileList.matches(rel)) continue
+        count++
+        bytes += statSync(path.join(drawioDir, rel)).size
+    }
+    return `${count} files, ${mb(bytes)} MB unpacked`
+}
+
+if (update) {
+    // Only the head decides what is already covered by "always include"
+    const always = parseFileList(list.head)
+    const kept = requested.filter((f) => !always.matches(f))
+    writeFileSync(LIST, formatFileList(list.head, kept))
+    console.log(`\nWrote ${LIST}: ${summarize(readFileList(LIST))}`)
+} else if (missing.length > 0) {
+    console.error(
+        `\nThe editor requested ${missing.length} files that drawio-files.txt does not list:\n  ${missing.join("\n  ")}\nRun with --update to add them.`,
+    )
+    process.exit(1)
+} else {
+    console.log(`\ndrawio-files.txt is complete: ${summarize(list)}`)
+}

packages/mcp-server/scripts/check-package.mjs

@@ -9,7 +9,26 @@ const REQUIRED = [
     "dist/preview/index.html",
     "dist/preview/preview.css",
     "dist/preview/preview.js",
+    "dist/drawio/index.html",
+    "dist/drawio/js/app.min.js",
+    "dist/drawio/LICENSE",
+    // The draw.io version stamp (part of every file's ETag); a dotfile, so
+    // make sure npm keeps it
+    "dist/drawio/.version",
+    "dist/shell/index.html",
+    "dist/shell/shell.js",
+    "dist/shell/shell.css",
 ]
+// The canvas shell (750 KB and 50 KB at version 0.4.0); a jump means a
+// dependency of the shared components grew the bundle
+const MAX_FILE_BYTES = {
+    "dist/shell/shell.js": 1.5 * 1024 * 1024,
+    "dist/shell/shell.css": 300 * 1024,
+}
+// The bundled draw.io is most of the package (15.3 MB packed with draw.io
+// v32.0.2 at version 0.4.0); a jump means the file list grew more than
+// intended
+const MAX_TARBALL_BYTES = 20 * 1024 * 1024
 
 const output = JSON.parse(
     execSync("npm pack --dry-run --json", { encoding: "utf8" }),
@@ -22,4 +41,23 @@ if (missing.length > 0) {
     console.error(`npm package is missing: ${missing.join(", ")}`)
     process.exit(1)
 }
-console.log(`npm package OK (${files.size} files)`)
+const mb = (n) => (n / 1048576).toFixed(1)
+const kb = (n) => (n / 1024).toFixed(0)
+for (const [path, limit] of Object.entries(MAX_FILE_BYTES)) {
+    const size = pack.files.find((f) => f.path === path).size
+    if (size > limit) {
+        console.error(
+            `${path} is ${kb(size)} KB, over the ${kb(limit)} KB limit`,
+        )
+        process.exit(1)
+    }
+}
+if (pack.size > MAX_TARBALL_BYTES) {
+    console.error(
+        `npm package is ${mb(pack.size)} MB packed, over the ${mb(MAX_TARBALL_BYTES)} MB limit`,
+    )
+    process.exit(1)
+}
+console.log(
+    `npm package OK (${files.size} files, ${mb(pack.size)} MB packed, ${mb(pack.unpackedSize)} MB unpacked)`,
+)

packages/mcp-server/scripts/drawio-file-list.mjs

@@ -0,0 +1,78 @@
+/**
+ * drawio-files.txt: the files copied from draw.war into dist/drawio.
+ *
+ * One path per line; `*` matches within a path segment and `**` across
+ * segments; `#` starts a comment. Everything above the marker line is kept
+ * as it is ("always include"); the paths below it are what the embedded
+ * editor requested in a guard run, rewritten by check-drawio-files.mjs
+ * --update.
+ */
+import fs from "node:fs"
+
+export const MARKER =
+    "# Requested by the editor; rewritten by scripts/check-drawio-files.mjs --update"
+
+function toRegExp(pattern) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    const source = escaped
+        .replace(/\*\*/g, "\0")
+        .replace(/\*/g, "[^/]*")
+        .replace(/\0/g, ".*")
+    return new RegExp(`^${source}$`)
+}
+
+const entries = (text) =>
+    text
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line && !line.startsWith("#"))
+
+export function parseFileList(text) {
+    const at = text.indexOf(MARKER)
+    if (at < 0) throw new Error(`drawio-files.txt has no "${MARKER}" line`)
+    const head = text.slice(0, at + MARKER.length)
+    const always = entries(head)
+    const requested = entries(text.slice(at + MARKER.length))
+
+    const exact = new Set()
+    const patterns = []
+    for (const entry of [...always, ...requested]) {
+        if (entry.includes("*")) {
+            patterns.push({ text: entry, re: toRegExp(entry), hit: false })
+        } else {
+            exact.add(entry)
+        }
+    }
+
+    return {
+        head,
+        always,
+        requested,
+        /** Whether the list names this file (remembers which patterns hit) */
+        matches(name) {
+            if (exact.has(name)) return true
+            let found = false
+            for (const p of patterns) {
+                if (p.re.test(name)) p.hit = found = true
+            }
+            return found
+        },
+        /** Entries that matched none of `seen` after matches() ran on them */
+        unmatched(seen) {
+            return [
+                ...[...exact].filter((name) => !seen.has(name)),
+                ...patterns.filter((p) => !p.hit).map((p) => p.text),
+            ]
+        },
+    }
+}
+
+export function readFileList(file) {
+    return parseFileList(fs.readFileSync(file, "utf8"))
+}
+
+/** The list text with a new requested section (sorted, unique) */
+export function formatFileList(head, requested) {
+    const body = [...new Set(requested)].sort().join("\n")
+    return `${head}\n${body}\n`
+}

packages/mcp-server/scripts/fetch-drawio.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * Build step: put a trimmed copy of draw.io into dist/drawio, so the preview
+ * page can embed the editor from its own origin (same-origin editor access,
+ * and no internet needed at runtime).
+ *
+ * Downloads the pinned draw.war (see src/drawio-version.json) into a cache
+ * directory (DRAWIO_WAR_CACHE, default <tmpdir>/next-ai-drawio), checks its
+ * SHA-256, and extracts only the files listed in drawio-files.txt. Set
+ * DRAWIO_WAR=<path> to use a local war without downloading. The list is kept
+ * up to date by scripts/check-drawio-files.mjs.
+ */
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+import {
+    readDrawioVersion,
+    readZipEntries,
+    sha256,
+} from "../../../scripts/drawio-zip.mjs"
+import { readFileList } from "./drawio-file-list.mjs"
+
+const PKG = path.join(path.dirname(fileURLToPath(import.meta.url)), "..")
+const DEST = path.join(PKG, "dist/drawio")
+const { version, sha256: expectedSha, downloadUrl } = readDrawioVersion()
+
+function log(message) {
+    console.log(`[fetch-drawio] ${message}`)
+}
+
+/** The draw.war as a buffer, from DRAWIO_WAR, the cache, or GitHub */
+async function readWar() {
+    const verified = (buf, source) => {
+        const actual = sha256(buf)
+        if (actual !== expectedSha) {
+            throw new Error(
+                `${source} is not draw.io ${version} (SHA-256 ${actual})`,
+            )
+        }
+        return buf
+    }
+
+    if (process.env.DRAWIO_WAR) {
+        log(`Using ${process.env.DRAWIO_WAR}`)
+        return verified(fs.readFileSync(process.env.DRAWIO_WAR), "DRAWIO_WAR")
+    }
+
+    const cacheDir =
+        process.env.DRAWIO_WAR_CACHE || path.join(os.tmpdir(), "next-ai-drawio")
+    const cached = path.join(cacheDir, `draw-${version}.war`)
+    if (fs.existsSync(cached)) {
+        try {
+            return verified(fs.readFileSync(cached), cached)
+        } catch (error) {
+            log(`${error.message}; downloading again`)
+            fs.rmSync(cached, { force: true })
+        }
+    }
+
+    log(`Downloading draw.io ${version} ...`)
+    const res = await fetch(downloadUrl)
+    if (!res.ok) throw new Error(`HTTP ${res.status} for ${downloadUrl}`)
+    const buf = verified(Buffer.from(await res.arrayBuffer()), downloadUrl)
+    fs.mkdirSync(cacheDir, { recursive: true })
+    const tmp = `${cached}.tmp-${process.pid}`
+    fs.writeFileSync(tmp, buf)
+    fs.renameSync(tmp, cached)
+    log(`Cached at ${cached}`)
+    return buf
+}
+
+/** Apache-2.0 text with a notice naming draw.io, for dist/drawio/LICENSE */
+function licenseText(warLicense) {
+    const notice =
+        `The files in this directory are an unmodified subset of draw.io ${version}\n` +
+        "(https://github.com/jgraph/drawio), Copyright (c) JGraph Ltd, redistributed\n" +
+        "under the Apache License, Version 2.0 reproduced below. The icon sets under\n" +
+        "img/lib and the stencils built into the scripts have additional terms, see\n" +
+        "img/LICENSE, shapes/LICENSE and stencils/LICENSE.\n\n"
+    if (warLicense) return notice + warLicense
+    // The standard terms, without this project's own copyright notice
+    const apache = fs.readFileSync(path.join(PKG, "../../LICENSE"), "utf8")
+    const end = "END OF TERMS AND CONDITIONS"
+    return notice + apache.slice(0, apache.indexOf(end) + end.length) + "\n"
+}
+
+async function main() {
+    const list = readFileList(path.join(PKG, "drawio-files.txt"))
+    const buf = await readWar()
+
+    const tmp = `${DEST}.tmp-${process.pid}`
+    fs.rmSync(tmp, { recursive: true, force: true })
+    const written = new Set()
+    let bytes = 0
+    let warLicense = null
+    for (const { name, data } of readZipEntries(buf)) {
+        // Server-side parts of the war; never shipped, whatever the list says
+        if (/^(WEB-INF|META-INF)\//.test(name)) continue
+        if (name === "LICENSE") warLicense = data.toString("utf8")
+        if (!list.matches(name)) continue
+        const target = path.join(tmp, name)
+        if (!target.startsWith(tmp + path.sep)) {
+            throw new Error(`Unsafe path in archive: ${name}`)
+        }
+        fs.mkdirSync(path.dirname(target), { recursive: true })
+        fs.writeFileSync(target, data)
+        written.add(name)
+        bytes += data.length
+    }
+
+    const missing = list.unmatched(written)
+    if (missing.length > 0) {
+        throw new Error(
+            `drawio-files.txt names files that draw.io ${version} does not have:\n  ${missing.join("\n  ")}\n` +
+                "Run scripts/check-drawio-files.mjs --update to refresh the list.",
+        )
+    }
+
+    fs.writeFileSync(path.join(tmp, "LICENSE"), licenseText(warLicense))
+    fs.writeFileSync(path.join(tmp, ".version"), `${version}\n`)
+    fs.rmSync(DEST, { recursive: true, force: true })
+    fs.renameSync(tmp, DEST)
+    log(
+        `Installed ${written.size} files (${(bytes / 1048576).toFixed(1)} MB) into dist/drawio`,
+    )
+}
+
+main().catch((error) => {
+    console.error(`[fetch-drawio] ${error.stack || error}`)
+    process.exit(1)
+})

packages/mcp-server/shell/canvas-shell.tsx

@@ -0,0 +1,159 @@
+import { Download, History, Moon, Sun } from "lucide-react"
+import { useMemo, useState } from "react"
+import { CanvasStage } from "@/components/canvas/canvas-stage"
+import { CompareDialog } from "@/components/canvas/compare-dialog"
+import { VersionsProvider } from "@/components/canvas/versions-context"
+import { type ExportFormat, SaveDialog } from "@/components/save-dialog"
+import { AppToaster } from "@/components/workspace/app-toaster"
+import { useDiagram } from "@/contexts/diagram-context"
+import { useDictionary } from "@/hooks/use-dictionary"
+import type { DrawioSource } from "@/lib/drawio/drawio-config"
+import { cn } from "@/lib/utils"
+import { useSettingsStore } from "@/stores/settings-store"
+import { useNodeVersions } from "./node-versions-source"
+import type { ShellConfig } from "./runtime-config"
+import { setDark } from "./theme"
+import { useMcpSync } from "./use-mcp-sync"
+import { VersionsPanel } from "./versions-panel"
+
+const iconButton =
+    "inline-flex size-8 shrink-0 items-center justify-center rounded-lg text-muted-foreground transition-colors hover:bg-accent hover:text-foreground [&_svg]:size-4"
+
+/**
+ * The MCP preview: the web app's canvas without the chat. A slim bar names
+ * the session and the sync state; the version cards (from the server's
+ * History), Compare and the export dialog come from the shared canvas
+ * components. The cards sit in a side panel, so the web app's versions strip
+ * above the canvas is left out: it would show the same list twice.
+ */
+export function CanvasShell({ config }: { config: ShellConfig }) {
+    const dict = useDictionary()
+    const isDark = useSettingsStore((s) => s.isDark)
+    const { saveDiagramToFile, hasPendingLoad } = useDiagram()
+    const { status, sync } = useMcpSync(config)
+    const versions = useNodeVersions(sync)
+    const [panelOpen, setPanelOpen] = useState(true)
+    const [saveOpen, setSaveOpen] = useState(false)
+    const drawioSource = useMemo<DrawioSource>(
+        () => ({
+            editorUrl: config.drawioBaseUrl,
+            ui: config.drawioUi || undefined,
+            lang: config.drawioLang || undefined,
+            // As the classic preview page: the user's own shape libraries
+            libraries: true,
+        }),
+        [config],
+    )
+    const hasVersions = versions.versions.length > 0
+    const showPanel = panelOpen && hasVersions
+
+    // draw.io exports what it shows: while a page export's one-page
+    // projection is on the canvas, or a full load has yet to reach the
+    // editor, that is not the document. Both end within seconds (the
+    // export's deadline is 15 s); the save waits for them, up to 20 s
+    const save = (filename: string, format: ExportFormat, tries = 0) => {
+        const canvasBusy = sync?.read().projectionActive || hasPendingLoad()
+        if (canvasBusy && tries < 66) {
+            setTimeout(() => save(filename, format, tries + 1), 300)
+            return
+        }
+        saveDiagramToFile(
+            filename,
+            format,
+            undefined,
+            dict.save.savedSuccessfully,
+        )
+    }
+
+    return (
+        <VersionsProvider value={versions}>
+            <div className="flex h-dvh flex-col bg-background text-foreground">
+                <header className="flex h-11 shrink-0 items-center gap-3 border-b border-border bg-surface-0 px-3.5">
+                    <span className="text-[13px] font-semibold tracking-[-0.01em]">
+                        Next AI Draw.io
+                    </span>
+                    {config.sessionId && (
+                        <span
+                            className="rounded-md bg-muted px-1.5 py-0.5 font-mono text-[11px] text-muted-foreground tabular-nums"
+                            title={config.sessionId}
+                            data-testid="shell-session"
+                        >
+                            {config.sessionId.slice(-8)}
+                        </span>
+                    )}
+                    <span
+                        className="truncate text-xs text-muted-foreground"
+                        data-testid="shell-status"
+                        data-status={status}
+                    >
+                        {dict.shell[status]}
+                    </span>
+                    {hasVersions && (
+                        <button
+                            type="button"
+                            onClick={() => setPanelOpen((open) => !open)}
+                            aria-label={
+                                panelOpen
+                                    ? dict.shell.hideVersions
+                                    : dict.shell.showVersions
+                            }
+                            title={
+                                panelOpen
+                                    ? dict.shell.hideVersions
+                                    : dict.shell.showVersions
+                            }
+                            aria-pressed={panelOpen}
+                            className={cn(
+                                iconButton,
+                                "ml-auto",
+                                panelOpen && "bg-accent text-foreground",
+                            )}
+                            data-testid="versions-toggle"
+                        >
+                            <History />
+                        </button>
+                    )}
+                    <button
+                        type="button"
+                        onClick={() => setSaveOpen(true)}
+                        aria-label={dict.workspace.export}
+                        title={dict.workspace.export}
+                        className={cn(iconButton, !hasVersions && "ml-auto")}
+                        data-testid="download"
+                    >
+                        <Download />
+                    </button>
+                    <button
+                        type="button"
+                        onClick={() => setDark(!isDark)}
+                        aria-label={dict.shell.toggleTheme}
+                        title={dict.shell.toggleTheme}
+                        className={iconButton}
+                        data-testid="theme-toggle"
+                    >
+                        {isDark ? <Sun /> : <Moon />}
+                    </button>
+                </header>
+                <div className="flex min-h-0 flex-1">
+                    <div className="relative min-w-0 flex-1">
+                        <CanvasStage
+                            className="inset-0"
+                            drawioSource={drawioSource}
+                        />
+                    </div>
+                    {showPanel && (
+                        <VersionsPanel versions={versions.versions} />
+                    )}
+                </div>
+                <CompareDialog />
+                <SaveDialog
+                    open={saveOpen}
+                    onOpenChange={setSaveOpen}
+                    onSave={save}
+                    defaultFilename={`diagram-${new Date().toLocaleDateString("sv-SE")}`}
+                />
+                <AppToaster />
+            </div>
+        </VersionsProvider>
+    )
+}

packages/mcp-server/shell/dictionary.ts

@@ -0,0 +1,46 @@
+import { i18n, type Locale } from "@/lib/i18n/config"
+import type { Dictionary } from "@/lib/i18n/dictionaries"
+import en from "@/lib/i18n/dictionaries/en.json"
+import ja from "@/lib/i18n/dictionaries/ja.json"
+import zh from "@/lib/i18n/dictionaries/zh.json"
+import zhHant from "@/lib/i18n/dictionaries/zh-Hant.json"
+
+// The web app loads one dictionary on the server (lib/i18n/dictionaries.ts
+// is server-only); the shell ships all four and picks in the browser
+const DICTIONARIES: Record<Locale, Dictionary> = {
+    en,
+    zh,
+    ja,
+    "zh-Hant": zhHant,
+}
+
+/** Our locale for a language tag ("zh-TW", "ja-JP", "en-US"), or null */
+export function matchLocale(tag: string): Locale | null {
+    const lower = tag.trim().toLowerCase()
+    if (!lower) return null
+    if (/^zh-(hant|tw|hk|mo)\b/.test(lower)) return "zh-Hant"
+    const base = lower.split("-")[0]
+    if (base === "zh") return "zh"
+    if (base === "ja") return "ja"
+    if (base === "en") return "en"
+    return null
+}
+
+/**
+ * The shell's language: the server's DRAWIO_LANG when it is one of ours,
+ * else the browser's first language we have, else English.
+ */
+export function pickLocale(
+    configLang: string,
+    browserLangs: readonly string[],
+): Locale {
+    for (const tag of [configLang, ...browserLangs]) {
+        const locale = matchLocale(tag)
+        if (locale) return locale
+    }
+    return i18n.defaultLocale
+}
+
+export function getShellDictionary(locale: Locale): Dictionary {
+    return DICTIONARIES[locale]
+}

packages/mcp-server/shell/index.html

@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Next AI Draw.io</title>
+    <link rel="icon" href="data:,">
+    <link rel="stylesheet" href="/shell/shell.css">
+    <script>window.__MCP_CONFIG__ = {{CONFIG_JSON}};</script>
+    <script>
+        // Dark class before the first paint (no white flash). The same rule
+        // as shell/theme.ts: the choice stored under "mcp:dark-mode", else
+        // the server's DRAWIO_DARK, else the system
+        try {
+            const config = window.__MCP_CONFIG__ || {}
+            const stored = localStorage.getItem("mcp:dark-mode")
+            const dark =
+                stored === "true" ||
+                (stored === null &&
+                    (config.drawioDark === "dark" ||
+                        (config.drawioDark !== "light" &&
+                            matchMedia("(prefers-color-scheme: dark)").matches)))
+            if (dark) document.documentElement.classList.add("dark")
+        } catch {}
+    </script>
+</head>
+<body class="antialiased">
+    <div id="root"></div>
+    <script type="module" src="/shell/shell.js"></script>
+</body>
+</html>

packages/mcp-server/shell/main.tsx

@@ -0,0 +1,28 @@
+// Entry of the MCP's canvas shell, bundled by scripts/build-shell.mjs into
+// dist/shell/shell.js and served at /shell/ by http-server.ts
+import { createRoot } from "react-dom/client"
+import { LocaleProvider } from "@/components/canvas/locale-context"
+import { DiagramProvider } from "@/contexts/diagram-context"
+import { DictionaryProvider } from "@/hooks/use-dictionary"
+import { CanvasShell } from "./canvas-shell"
+import { getShellDictionary, pickLocale } from "./dictionary"
+import { pageShellConfig } from "./runtime-config"
+import { initTheme } from "./theme"
+
+const config = pageShellConfig()
+const locale = pickLocale(config.lang, navigator.languages)
+// The stylesheet picks the CJK fonts by the document's language
+document.documentElement.lang = locale
+initTheme(config.drawioDark)
+
+const root = document.getElementById("root")
+if (!root) throw new Error("The shell page has no #root element")
+createRoot(root).render(
+    <DictionaryProvider dictionary={getShellDictionary(locale)}>
+        <LocaleProvider locale={locale}>
+            <DiagramProvider>
+                <CanvasShell config={config} />
+            </DiagramProvider>
+        </LocaleProvider>
+    </DictionaryProvider>,
+)

packages/mcp-server/shell/mcp-sync-core.ts

@@ -0,0 +1,964 @@
+/**
+ * The shell's side of the MCP server's state protocol (src/http-server.ts),
+ * ported from the classic preview page (src/preview/preview.js) without the
+ * page: the server is reached through fetch, the canvas through the
+ * SyncCanvas functions the hook (use-mcp-sync.ts) passes in. No React here,
+ * so the state machine can be driven step by step in tests.
+ *
+ * The protocol in short: the tab polls GET /api/state every 2 s and loads a
+ * newer version; a user edit is pushed with the version and state it is
+ * based on, and the server refuses (409) a push based on a version the AI
+ * has since written over, or on a state it has lost (it expired, the
+ * process restarted); the next poll then decides whose diagram wins
+ * (recoverState). get_diagram asks for a sync (the canvas as draw.io has
+ * it) and screenshots and file exports for an image, both through the poll.
+ */
+import { isSameDocument, sameFileVars } from "@/lib/diagram-diff"
+import { hasLoadOnlySettings } from "@/lib/drawio/editor-bridge"
+import { contentFingerprint } from "@/packages/mcp-server/src/edit-gate.ts"
+import {
+    normalizeToMxfile,
+    parseMxfile,
+    serializeMxfile,
+} from "@/packages/mcp-server/src/pages.ts"
+import type { SelectionAnswer } from "@/packages/mcp-server/src/selection.ts"
+
+export type ExportFormat = "png" | "svg" | "xmlsvg"
+
+/** GET /api/state as the server answers it */
+export interface ServerState {
+    xml: string | null
+    version: number
+    stateId: string | null
+    blank: boolean
+    syncRequested: boolean
+    exportFormat: ExportFormat | null
+    exportXml: string | null
+    exportOptions: { width?: number; pageId?: string } | null
+    exportId: string | null
+    /** A get_selection request waiting for this tab's answer */
+    selectionId?: string | null
+    /** Changes when History or the entry on the canvas does (the version
+     * cards read History again then); older servers send none */
+    historyKey?: string
+}
+
+/** An entry of GET /api/history */
+export interface HistoryEntryInfo {
+    id: number
+    index: number
+    svg: string
+    xml: string
+    /** Who made it: "user", "recover", "restore"; null for the AI's writes */
+    source: string | null
+    /** The oldest entry with the same content (itself when it is the first) */
+    firstId: number
+}
+
+/** GET /api/history as the server answers it, for the state the list is of */
+export interface HistoryList {
+    entries: HistoryEntryInfo[]
+    stateId: string | null
+    /** The entry whose content the canvas shows (the server's rule), or null */
+    currentId: number | null
+}
+
+/**
+ * How a server write goes on the canvas: as one undo step on the page the
+ * user is viewing (the editor highlights it and Ctrl+Z takes it back), or
+ * as a full load of the document (see decideLoad)
+ */
+export type LoadDecision =
+    | { mode: "commit"; pageId: string | null }
+    | { mode: "load" }
+
+export interface ExportRequest {
+    format: string
+    [key: string]: unknown
+}
+
+export interface ExportResult {
+    data?: string
+    xml?: string
+}
+
+/** The canvas as the sync drives it (the hook maps it onto DiagramProvider) */
+export interface SyncCanvas {
+    load(xml: string, decision: LoadDecision): void
+    /** Show a one-page projection for an export only: not recorded, its
+     * autosaves ignored until the next load */
+    showTransient(xml: string): void
+    /** draw.io's export; null when it does not answer in time */
+    export(
+        request: ExportRequest,
+        timeoutMs: number,
+    ): Promise<ExportResult | null>
+    /** The document on the canvas now ("" before the first load) */
+    currentXml(): string
+    /** The page on screen; null when unknown (external draw.io) */
+    currentPageId(): string | null
+    /** A full load was sent and draw.io has not reported it yet: the
+     * editor still shows the previous document */
+    loadPending(): boolean
+    /** The cells selected in the editor, for get_selection; `unavailable`
+     * when the page cannot reach the editor (external draw.io) */
+    readSelection(): SelectionAnswer
+}
+
+export type SyncStatus = "waiting" | "connected" | "offline"
+
+/** Texts shown to the user (the shell takes them from its dictionary) */
+export type SyncNotice =
+    | "tooLarge"
+    | "unreachable"
+    | "restoredFromFile"
+    | "aiChanged"
+    | "historyChanged"
+    | "restoreFailed"
+
+export interface SyncOptions {
+    sessionId: string
+    /** Prefix of the server's API paths ("/api") */
+    apiBase: string
+    /** Every request carries it in the X-Drawio-Token header */
+    token: string
+    canvas: SyncCanvas
+    onNotice: (notice: SyncNotice) => void
+    onStatus?: (status: SyncStatus) => void
+    /** The tab is hidden; another tab of this session may be in front */
+    isHidden?: () => boolean
+    /** The server made a new state for the session: History entries got
+     * new ids, so a list on screen is stale */
+    onStateRecreated?: () => void
+    /** The token of the process now answering on this port, read from a
+     * fresh copy of this page; default: tokenFromPage of location.href */
+    refreshToken?: () => Promise<string | null>
+    fetch?: typeof fetch
+}
+
+export interface McpSync {
+    /** Poll now and every 2 s */
+    start(): void
+    stop(): void
+    poll(): Promise<void>
+    /** draw.io is ready for exports (DiagramProvider's isDrawioReady) */
+    setReady(ready: boolean): void
+    /** draw.io sent an autosave: the canvas changed to this document */
+    onAutoSave(xml: string): void
+    /** draw.io reported a load done */
+    onDrawioLoad(): void
+    /** The server's History, with the state its ids belong to; null when
+     * it could not be read, or the state changed meanwhile (the version
+     * cards, shell/node-versions-source.ts) */
+    fetchHistory(): Promise<HistoryList | null>
+    /** Put a History entry back, naming the state its list belongs to */
+    restoreEntry(
+        id: number,
+        listStateId: string | null,
+    ): Promise<"ok" | "stale" | "failed">
+    /** Called when the server's diagram or History changed (a write
+     * loaded, an edit saved, a thumbnail sent, the state recreated): the
+     * version cards read History again. Returns the unsubscribe */
+    onServerChange(listener: () => void): () => void
+    /** For tests and the status bar */
+    read(): {
+        stateId: string | null
+        currentVersion: number
+        lastXml: string | null
+        latestXml: string | null
+        projectionActive: boolean
+        status: SyncStatus
+    }
+}
+
+export const POLL_INTERVAL_MS = 2000
+
+/** The API token the server wrote into a shell page (window.__MCP_CONFIG__) */
+export function tokenFromPage(html: string): string | null {
+    const match = html.match(/window\.__MCP_CONFIG__ = (\{.*?\});/)
+    if (!match) return null
+    try {
+        const token = JSON.parse(match[1]).token
+        return typeof token === "string" && token ? token : null
+    } catch {
+        return null
+    }
+}
+
+/**
+ * The same diagram, as text or as documents (draw.io re-serializes what it
+ * loads: another attribute order, filled-in defaults). Only documents with
+ * a page or a model are compared as documents: two without any would
+ * otherwise count as the same.
+ */
+function sameDiagram(a: string | null, b: string | null): boolean {
+    if (a === b) return true
+    if (a === null || b === null) return false
+    const hasModel = (xml: string) => /<(mxGraphModel|diagram)[\s>]/.test(xml)
+    return hasModel(a) && hasModel(b) && isSameDocument(a, b)
+}
+
+/** SVG as a data URL, as the server stores thumbnails */
+function svgDataUrl(svg: string): string {
+    if (svg.startsWith("data:")) return svg
+    return `data:image/svg+xml;base64,${btoa(unescape(encodeURIComponent(svg)))}`
+}
+
+/**
+ * Whether a server write can go on the canvas as one undo step: it has the
+ * same pages as the canvas, changes only the one the user is viewing (the
+ * one with currentPageId; a one-page document needs no id, several pages
+ * with the page unknown load in full), keeps the file variables and needs
+ * no load-only page setting. Pages are compared with the MCP core's
+ * contentFingerprint (names and cells). The editor bridge checks the same
+ * against the live editor and falls back to a full load on its own.
+ */
+export function decideLoad(
+    currentXml: string,
+    nextXml: string,
+    currentPageId: string | null,
+): LoadDecision {
+    const parse = (xml: string) => {
+        const normalized = normalizeToMxfile(xml)
+        return normalized ? parseMxfile(normalized) : null
+    }
+    const full: LoadDecision = { mode: "load" }
+    const current = parse(currentXml)
+    const next = parse(nextXml)
+    if (!current || !next) return full
+    if (
+        !sameFileVars(
+            current.documentElement.getAttribute("vars"),
+            next.documentElement.getAttribute("vars"),
+        )
+    ) {
+        return full
+    }
+    const pagesNow = Array.from(current.querySelectorAll("diagram"))
+    const pagesNext = Array.from(next.querySelectorAll("diagram"))
+    if (pagesNow.length === 0 || pagesNow.length !== pagesNext.length) {
+        return full
+    }
+    let index = pagesNow.findIndex(
+        (page) => page.getAttribute("id") === currentPageId,
+    )
+    if (index < 0) {
+        // The page on screen is unknown (an external draw.io cannot tell):
+        // with several pages the target cannot be told, load in full
+        if (pagesNow.length > 1) return full
+        index = 0
+    }
+    const target = pagesNext[index]
+    // The page is found by its id when the document has several
+    if (
+        pagesNow.length > 1 &&
+        target.getAttribute("id") !== pagesNow[index].getAttribute("id")
+    ) {
+        return full
+    }
+    const targetModel = target.querySelector("mxGraphModel")
+    if (targetModel && hasLoadOnlySettings(targetModel)) return full
+    // The other pages, as the MCP core compares them (edit-gate.ts)
+    const others = (doc: Document, pages: Element[]) => {
+        pages[index].remove()
+        return contentFingerprint(serializeMxfile(doc))
+    }
+    if (others(current, pagesNow) !== others(next, pagesNext)) return full
+    return { mode: "commit", pageId: target.getAttribute("id") }
+}
+
+export function createMcpSync(options: SyncOptions): McpSync {
+    const { sessionId, apiBase, canvas, onNotice, onStatus } = options
+    const fetchFn = options.fetch ?? ((...args) => globalThis.fetch(...args))
+    let token = options.token
+
+    let currentVersion = 0
+    let isReady = false
+    // What the server has (the text it sent or we pushed) and the newest
+    // diagram on the canvas, saved to the server or not
+    let lastXml: string | null = null
+    let latestXml: string | null = null
+    // The server state this tab is in step with; null until the first poll
+    let stateId: string | null = null
+    let pushFailing = false
+    const pushesInFlight: string[] = []
+    // After a recovery replaced the canvas, until draw.io reports the load:
+    // an autosave still on its way belongs to the canvas being replaced
+    let awaitingLoad = false
+    let awaitingLoadTimer: ReturnType<typeof setTimeout> | null = null
+    // A write taken in place (a commit) makes draw.io autosave its own copy
+    // of it, serialized its way: that one autosave is not an edit
+    let awaitingCommitCopy = false
+    let pollSeq = 0
+    let lastHandledPoll = 0 // polls overlap; older answers are dropped
+    // The edit whose SVG export is pending, and what it was based on
+    let pendingSvgExport: string | null = null
+    // The latest thumbnail export of a loaded server write: the state and
+    // version it showed, and the XML loaded
+    let thumbExport: {
+        stateId: string | null
+        version: number
+        xml: string
+    } | null = null
+    // Its picture was not taken because the user had changed the canvas by
+    // then: taken when the canvas shows the write again (an undo)
+    let thumbMissed = false
+    let pendingMcpExport: ExportFormat | null = null
+    let mcpExportSeq = 0
+    let mcpExportId: string | null = null
+    // A one-page projection is on screen for a page-targeted export
+    let projectionExportActive = false
+    // The restore load of the real document was sent; until draw.io reports
+    // it (or 5 s), the projection still counts as on screen
+    let projectionRestoreTimer: ReturnType<typeof setTimeout> | null = null
+    const endProjection = () => {
+        projectionExportActive = false
+        if (projectionRestoreTimer) clearTimeout(projectionRestoreTimer)
+        projectionRestoreTimer = null
+    }
+    // Load the server state on the next poll even at the same version
+    let forceReload = false
+    let pendingSyncExport = false
+    let syncExportSeq = 0
+    // The selection request answered last: the server shows a request until
+    // the answer arrives, and polls overlap
+    let answeredSelectionId: string | null = null
+    let status: SyncStatus = "waiting"
+    let interval: ReturnType<typeof setInterval> | null = null
+
+    const setStatus = (next: SyncStatus) => {
+        if (status === next) return
+        status = next
+        onStatus?.(next)
+    }
+
+    // Listeners of onServerChange, told once per History key seen (the
+    // server sends it with every state and push answer; a write, a restore
+    // and the first hand edit change it, further hand edits do not) and
+    // whenever History changed without one (a rejected edit kept, a
+    // thumbnail stored)
+    const changeListeners = new Set<() => void>()
+    let notedKey: string | null = null
+    let notedStateId: string | null = null
+    const emitChange = () => {
+        for (const listener of changeListeners) listener()
+    }
+    const noteHistory = (key: string, sid: string | null) => {
+        if (key === notedKey && sid === notedStateId) return
+        notedKey = key
+        notedStateId = sid
+        emitChange()
+    }
+
+    // A 403 means another MCP process (with its own token) now answers on
+    // this port: read its token and retry once, so the next poll can recover
+    // the session instead of being refused forever
+    let tokenRefresh: Promise<void> | null = null
+    const refreshToken = () => {
+        if (!tokenRefresh) {
+            const read =
+                options.refreshToken ??
+                (() =>
+                    fetchFn(location.href, { cache: "no-store" })
+                        .then((r) => r.text())
+                        .then(tokenFromPage))
+            tokenRefresh = read()
+                .then((next) => {
+                    if (next) token = next
+                })
+                .catch(() => {})
+                .finally(() => {
+                    tokenRefresh = null
+                })
+        }
+        return tokenRefresh
+    }
+
+    const api = async (path: string, init: RequestInit = {}) => {
+        const send = () =>
+            fetchFn(`${apiBase}${path}`, {
+                ...init,
+                headers: { ...(init.headers ?? {}), "X-Drawio-Token": token },
+            })
+        let r = await send()
+        if (r.status === 403) {
+            await refreshToken()
+            r = await send()
+        }
+        return r
+    }
+
+    const postJson = (path: string, body: unknown) =>
+        api(path, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        })
+
+    /** Put a server write on the canvas and take its thumbnail */
+    const loadFromServer = (xml: string, how: "decide" | "full") => {
+        lastXml = xml
+        latestXml = xml
+        const before = canvas.currentXml()
+        const decision: LoadDecision =
+            how === "decide"
+                ? decideLoad(before, xml, canvas.currentPageId())
+                : { mode: "load" }
+        canvas.load(xml, decision)
+        // draw.io autosaves its copy only when the write changed its
+        // document: after one that left the canvas as it was, the next
+        // autosave is the user's
+        awaitingCommitCopy =
+            decision.mode === "commit" && !sameDiagram(before, xml)
+        // currentVersion is the write's version
+        thumbExport = { stateId, version: currentVersion, xml }
+        thumbMissed = false
+        setTimeout(captureThumbnail, 500)
+    }
+
+    // The image of the server write on the canvas, for its History entry:
+    // only for the latest load, once draw.io is ready, and only if the
+    // canvas still shows it when the export answers
+    const captureThumbnail = () => {
+        const t = thumbExport
+        if (!t || !isReady) return
+        canvas.export({ format: "svg" }, 5000).then((result) => {
+            if (!result?.data || thumbExport !== t) return
+            if (!sameDiagram(latestXml, t.xml)) {
+                thumbMissed = true
+                return
+            }
+            thumbExport = null
+            thumbMissed = false
+            postJson("/history-svg", {
+                sessionId,
+                svg: svgDataUrl(result.data),
+                stateId: t.stateId,
+                version: t.version,
+            })
+                // The write's History entry has its picture now
+                .then(emitChange)
+                .catch(() => {})
+        })
+    }
+
+    // Until draw.io reports the load (its messages come in order), an
+    // autosave is from the canvas being replaced; in case no report comes,
+    // not for long
+    const expectLoad = () => {
+        awaitingLoad = true
+        if (awaitingLoadTimer) clearTimeout(awaitingLoadTimer)
+        awaitingLoadTimer = setTimeout(() => {
+            awaitingLoad = false
+        }, 5000)
+    }
+
+    // Restore the user's real document after a page-targeted projection
+    // export by reloading the server state (it also has any autosave that
+    // was still in flight when the projection started). projectionExportActive
+    // stays set until the poll loads the document: an edit on the
+    // projection before that must not be pushed.
+    const restoreFromProjection = () => {
+        if (!projectionExportActive) return
+        forceReload = true
+        poll()
+    }
+
+    // source is "sync" for replies to a server sync request, "recover" for
+    // the tab's copy after the server recovered the session, else "edit".
+    // sid is the server state the push is based on.
+    async function pushState(
+        xml: string,
+        svg = "",
+        baseVersion = currentVersion,
+        source: "edit" | "sync" | "recover" = "edit",
+        sid = stateId,
+    ): Promise<void> {
+        if (!sessionId) return
+        pushesInFlight.push(xml)
+        try {
+            const r = await postJson("/state", {
+                sessionId,
+                xml,
+                svg,
+                baseVersion,
+                source,
+                stateId: sid,
+            })
+            pushFailing = false
+            if (r.ok) {
+                const d = await r.json()
+                // An answer about a state this tab has left since, or one
+                // that comes after a newer version was loaded or saved
+                if (sid !== stateId || d.version < currentVersion) return
+                currentVersion = d.version
+                lastXml = xml
+                noteHistory(d.historyKey ?? String(d.version), stateId)
+                // The canvas changed while this edit was on its way, to
+                // something no pending autosave will send (an undo back to
+                // the previous version): send it now. A sync reply is
+                // draw.io's export of the canvas, in another format than its
+                // autosave.
+                if (
+                    latestXml &&
+                    latestXml !== xml &&
+                    pendingSvgExport !== latestXml &&
+                    source === "edit"
+                ) {
+                    pushState(latestXml)
+                }
+            } else if (r.status === 413) {
+                // Over the server's size limit: the image is most of it, so
+                // try once without it
+                if (svg) pushState(xml, "", baseVersion, source, sid)
+                else onNotice("tooLarge")
+            } else if (r.status === 409) {
+                // The AI wrote a newer version, or the server lost the state
+                // this push was based on; the next poll sorts it out
+                const d = await r.json().catch(() => ({}))
+                if (d.savedToHistory) {
+                    onNotice(
+                        source === "recover" ? "restoredFromFile" : "aiChanged",
+                    )
+                    // History grew without a new version
+                    emitChange()
+                }
+                poll()
+            }
+        } catch (error) {
+            console.error("Push failed:", error)
+            setStatus("offline")
+            if (!pushFailing) {
+                pushFailing = true
+                onNotice("unreachable")
+            }
+        } finally {
+            pushesInFlight.splice(pushesInFlight.indexOf(xml), 1)
+        }
+    }
+
+    // The server made a new state for this session: it expired, or the MCP
+    // process restarted. Decide whose diagram wins.
+    const recoverState = (s: ServerState) => {
+        stateId = s.stateId
+        options.onStateRecreated?.()
+        // The old state's pending work is gone with it
+        const projectionShown = projectionExportActive
+        endProjection()
+        forceReload = false
+        pendingMcpExport = null
+        pendingSyncExport = false
+        const mine = latestXml
+        currentVersion = s.version
+        if (s.blank || s.xml === lastXml) {
+            // The server knows nothing, or exactly what this tab last saved:
+            // the canvas can only be newer, so it wins (edits made while the
+            // server was down are saved now)
+            if (projectionShown && mine) {
+                canvas.load(mine, { mode: "load" })
+                expectLoad()
+            }
+            if (mine && !sameDiagram(mine, s.xml)) {
+                pushState(mine, "", s.version)
+            } else if (s.xml && !s.blank && mine) {
+                // The canvas still shows the diagram the server recovered:
+                // its History entry came back without a picture (the file
+                // keeps none), take one now
+                thumbExport = { stateId, version: currentVersion, xml: s.xml }
+                thumbMissed = false
+                captureThumbnail()
+            }
+        } else if (s.xml) {
+            // The server has a diagram this tab never showed (an AI write it
+            // missed, a saved file): show that, and keep this tab's copy in
+            // History unless it is the same. A full load, as the classic
+            // page does: whether the canvas can take the write in place is
+            // decided inside DiagramProvider, and the sync cannot tell; until
+            // draw.io reports the load, an autosave is from the canvas being
+            // replaced
+            loadFromServer(s.xml, "full")
+            expectLoad()
+            if (mine && !sameDiagram(mine, s.xml)) {
+                pushState(mine, "", s.version, "recover")
+            }
+        }
+    }
+
+    const startSyncExport = () => {
+        pendingSyncExport = true
+        // The version and state the export is taken at: a newer AI write may
+        // load meanwhile, and this older XML must not overwrite it
+        const base = currentVersion
+        const sid = stateId
+        const seq = ++syncExportSeq
+        canvas.export({ format: "xml" }, 5000).then((result) => {
+            // A late reply to an earlier request was taken at another version
+            if (seq !== syncExportSeq) return
+            pendingSyncExport = false
+            if (result?.xml) pushState(result.xml, "", base, "sync", sid)
+        })
+    }
+
+    // Handle an export request from the MCP server (png/svg).
+    //
+    // Plain export: capture whatever page is on screen (PNG: pageId picks a
+    // page, width caps the size).
+    //
+    // Page-targeted export: the server sends a single-page <mxfile>
+    // projection in exportXml. It goes on the canvas as a transient
+    // document, draw.io renders it, exports, then the real document is
+    // loaded back from the server. The session state is never changed.
+    const startMcpExport = (s: ServerState, justLoaded: boolean) => {
+        const format = s.exportFormat as ExportFormat
+        pendingMcpExport = format
+        const seq = ++mcpExportSeq
+        mcpExportId = s.exportId
+        const extra = s.exportOptions ?? {}
+        const fire = () => {
+            const request: ExportRequest =
+                format === "png"
+                    ? {
+                          format: "png",
+                          scale: 2,
+                          currentPage: !extra.pageId,
+                          ...extra,
+                      }
+                    : { format }
+            canvas.export(request, 10000).then((result) => {
+                // A later export is running by now, or this one ended
+                if (seq !== mcpExportSeq || pendingMcpExport === null) return
+                const d = result?.data ?? ""
+                const isPng = format === "png" && d.startsWith("data:image/png")
+                const isSvg =
+                    format !== "png" &&
+                    (d.startsWith("data:image/svg") || d.startsWith("<svg"))
+                const done = () => {
+                    if (seq !== mcpExportSeq) return
+                    pendingMcpExport = null
+                    // Page-targeted export: restore the user's real document
+                    restoreFromProjection()
+                }
+                if (!isPng && !isSvg) {
+                    done()
+                    return
+                }
+                // Keep pendingMcpExport set until the server has the result:
+                // a poll answered before that still sees the request and
+                // would start the same export again
+                postJson("/state", {
+                    sessionId,
+                    exportData: d,
+                    exportId: mcpExportId,
+                })
+                    .catch(() => {})
+                    .finally(done)
+            })
+        }
+        if (s.exportXml) {
+            projectionExportActive = true
+            canvas.showTransient(s.exportXml)
+            // Let draw.io render the loaded page before exporting
+            setTimeout(fire, 600)
+        } else if (justLoaded) {
+            // A write with a screenshot: give the new diagram's external
+            // icon images a moment to load before the PNG is taken
+            setTimeout(fire, 600)
+        } else {
+            fire()
+        }
+        // The whole export, result delivery included, ends in time: a result
+        // POST that never answers must not keep the projection on screen
+        // past the server's deadline (15 s). Only for this export: a later
+        // one may be running by then. The export is over: its result POST
+        // answering after this must not restore the document a second time.
+        setTimeout(() => {
+            if (pendingMcpExport && seq === mcpExportSeq) {
+                mcpExportSeq++
+                pendingMcpExport = null
+                restoreFromProjection()
+            }
+        }, 15000)
+    }
+
+    async function poll(): Promise<void> {
+        if (!sessionId) return
+        const seq = ++pollSeq
+        try {
+            const r = await api(
+                `/state?sessionId=${encodeURIComponent(sessionId)}`,
+            )
+            if (!r.ok) {
+                // Refused (another process answers on this port and its
+                // token could not be read) or failing: edits are not saved
+                setStatus("offline")
+                return
+            }
+            const s: ServerState = await r.json()
+            // An older answer than one already handled (the interval, the
+            // 409 handler and the projection restore each poll): it could
+            // name a state that is gone
+            if (seq < lastHandledPoll) return
+            lastHandledPoll = seq
+            setStatus("connected")
+            if (stateId === null) stateId = s.stateId
+            else if (s.stateId && s.stateId !== stateId) recoverState(s)
+            // Load a new version (before an export, so it pictures the
+            // latest). While a projection is on screen, only the restore
+            // (forceReload) replaces it, so a new version doesn't fight the
+            // projection; currentVersion stays unadvanced until then. The
+            // tab's own push still on its way is not loaded back: the canvas
+            // may have moved on since (an undo), and its answer follows.
+            const ownPush = s.xml !== null && pushesInFlight.includes(s.xml)
+            let justLoaded = false
+            if (
+                (forceReload ||
+                    (s.version > currentVersion &&
+                        !projectionExportActive &&
+                        !ownPush)) &&
+                s.xml
+            ) {
+                // The restore after a projection is a full load of the
+                // document the user had
+                const how = forceReload ? "full" : "decide"
+                forceReload = false
+                currentVersion = s.version
+                loadFromServer(s.xml, how)
+                // The projection stays on screen until draw.io reports this
+                // load (its messages come in order): an autosave before that
+                // is of the projection, not an edit
+                if (projectionExportActive && !projectionRestoreTimer) {
+                    projectionRestoreTimer = setTimeout(endProjection, 5000)
+                }
+                justLoaded = true
+            }
+            // Also the tab's own push, and a version a projection holds back
+            noteHistory(s.historyKey ?? String(s.version), stateId)
+            // A sync request (get_diagram): after the load above, so draw.io
+            // exports what it just loaded; never while a one-page projection
+            // is on screen, which would be sent as the whole document
+            if (
+                s.syncRequested &&
+                !pendingSyncExport &&
+                isReady &&
+                !projectionExportActive
+            ) {
+                startSyncExport()
+            }
+            // Nor an export while the projection is still on screen: it
+            // would picture the projection
+            if (
+                s.exportFormat &&
+                !pendingMcpExport &&
+                isReady &&
+                !projectionExportActive
+            ) {
+                startMcpExport(s, justLoaded)
+            }
+            // A selection request (get_selection): the editor's selection
+            // on the page the user is viewing, once draw.io is up (the
+            // bridge attaches to it at its first load), not while a
+            // projection replaces that page, and not while a full load (the
+            // one above, or one still on its way) has yet to reach the
+            // editor: it still shows the previous document
+            if (
+                s.selectionId &&
+                s.selectionId !== answeredSelectionId &&
+                isReady &&
+                !projectionExportActive &&
+                !canvas.loadPending()
+            ) {
+                const id = s.selectionId
+                answeredSelectionId = id
+                const answer = () => {
+                    // A hidden tab answers later: the canvas may have moved
+                    // on since the poll (a projection, a full load, draw.io
+                    // starting over). The same conditions as above; when
+                    // they no longer hold, the next poll decides again
+                    if (
+                        !isReady ||
+                        projectionExportActive ||
+                        canvas.loadPending()
+                    ) {
+                        if (answeredSelectionId === id) {
+                            answeredSelectionId = null
+                        }
+                        return
+                    }
+                    postJson("/state", {
+                        sessionId,
+                        selectionId: id,
+                        selection: canvas.readSelection(),
+                    })
+                        .then((r) => {
+                            if (!r.ok) throw new Error(String(r.status))
+                        })
+                        .catch(() => {
+                            // Not delivered: the next poll answers it again
+                            if (answeredSelectionId === id) {
+                                answeredSelectionId = null
+                            }
+                        })
+                }
+                // A hidden tab lets a tab in front (the same session open
+                // twice) answer first; the server takes the first answer
+                // and ignores the later one
+                if (options.isHidden?.()) {
+                    setTimeout(answer, POLL_INTERVAL_MS + 500)
+                } else {
+                    answer()
+                }
+            }
+        } catch {
+            setStatus("offline")
+        }
+    }
+
+    return {
+        start() {
+            if (!sessionId || interval) return
+            poll()
+            interval = setInterval(poll, POLL_INTERVAL_MS)
+        },
+        stop() {
+            if (interval) clearInterval(interval)
+            interval = null
+        },
+        poll,
+        setReady(ready) {
+            isReady = ready
+            // draw.io is starting over (an external editor reloads on a
+            // theme switch): an export in flight gets no answer, and a
+            // projection on the canvas is gone with the old frame. The next
+            // poll puts the document back and starts the server's export
+            // again
+            if (!ready && pendingMcpExport !== null) {
+                mcpExportSeq++
+                pendingMcpExport = null
+                if (projectionExportActive) forceReload = true
+            }
+            // A write loaded before draw.io was ready gets its thumbnail now
+            if (ready && thumbExport) captureThumbnail()
+        },
+        onAutoSave(xml) {
+            // Ignore autosave while a single-page projection is on screen
+            // for a page-targeted export; otherwise the projection would be
+            // pushed as the session's document
+            if (projectionExportActive) return
+            // An edit of the canvas that recovery is replacing: kept in
+            // History, never over the recovered diagram
+            if (awaitingLoad) {
+                pushState(xml, "", currentVersion, "recover")
+                return
+            }
+            // Also an edit undone back to what the server has, or draw.io's
+            // own copy of a write it took in place (a commit). Compared as
+            // documents only for that copy: a change of the paper size alone
+            // is the same document to isSameDocument when the server's copy
+            // names none
+            latestXml = xml
+            const commitCopy = awaitingCommitCopy
+            awaitingCommitCopy = false
+            // The canvas is back at a write whose picture was not taken (an
+            // edit came first): take it now
+            if (
+                thumbMissed &&
+                thumbExport &&
+                sameDiagram(xml, thumbExport.xml)
+            ) {
+                thumbMissed = false
+                captureThumbnail()
+            }
+            if (xml === lastXml || (commitCopy && sameDiagram(xml, lastXml))) {
+                return
+            }
+            // Request an SVG export, then push the edit with it; remember
+            // the version and state it is based on. Without an answer in
+            // time, push it without the image.
+            pendingSvgExport = xml
+            const base = currentVersion
+            const sid = stateId
+            canvas.export({ format: "svg" }, 2000).then((result) => {
+                // A later edit took over the slot, or this one was sent
+                if (pendingSvgExport !== xml) return
+                pendingSvgExport = null
+                const svg = result?.data ? svgDataUrl(result.data) : ""
+                pushState(xml, svg, base, "edit", sid)
+            })
+        },
+        onDrawioLoad() {
+            awaitingLoad = false
+            // A commit that fell back to a full load sends no copy
+            awaitingCommitCopy = false
+            // The restore load after a projection export is done
+            if (projectionRestoreTimer) endProjection()
+        },
+        async fetchHistory() {
+            // A list for a state the server recreated meanwhile has old ids
+            const sid = stateId
+            // A failed read is told again at the next poll: no other event
+            // comes for the same History
+            const failed = () => {
+                notedKey = null
+                return null
+            }
+            try {
+                const r = await api(
+                    `/history?sessionId=${encodeURIComponent(sessionId)}`,
+                )
+                if (!r.ok) return failed()
+                const d = await r.json()
+                if (sid !== stateId) return null
+                // A list from a state the poll has not seen yet (another
+                // process answers): its poll tells the cards to read again
+                if (typeof d.stateId === "string" && d.stateId !== sid) {
+                    return null
+                }
+                return {
+                    entries: d.entries ?? [],
+                    stateId: sid,
+                    currentId:
+                        typeof d.currentId === "number" ? d.currentId : null,
+                }
+            } catch {
+                return failed()
+            }
+        },
+        async restoreEntry(id, listStateId) {
+            try {
+                const r = await postJson("/restore", {
+                    sessionId,
+                    id,
+                    stateId: listStateId,
+                })
+                if (r.ok) {
+                    await poll()
+                    return "ok"
+                }
+                if (r.status === 409) {
+                    onNotice("historyChanged")
+                    return "stale"
+                }
+            } catch {
+                // reported below
+            }
+            onNotice("restoreFailed")
+            return "failed"
+        },
+        onServerChange(listener) {
+            changeListeners.add(listener)
+            return () => {
+                changeListeners.delete(listener)
+            }
+        },
+        read() {
+            return {
+                stateId,
+                currentVersion,
+                lastXml,
+                latestXml,
+                projectionActive: projectionExportActive,
+                status,
+            }
+        },
+    }
+}

packages/mcp-server/shell/node-versions-source.ts

@@ -0,0 +1,308 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react"
+import { toast } from "sonner"
+import type {
+    VersionItem,
+    VersionsSource,
+} from "@/components/canvas/versions-context"
+import { useDictionary } from "@/hooks/use-dictionary"
+import {
+    type ChangeSummary,
+    diffDiagrams,
+    isSameDocument,
+} from "@/lib/diagram-diff"
+import { formatMessage } from "@/lib/i18n/utils"
+import { contentFingerprint } from "@/packages/mcp-server/src/edit-gate.ts"
+import { BLANK_MXFILE, hasCells } from "@/packages/mcp-server/src/pages.ts"
+import { useCanvasStore } from "@/stores/canvas-store"
+import type { HistoryEntryInfo, HistoryList, McpSync } from "./mcp-sync-core"
+
+/**
+ * A version card of the shell: one per distinct content of the server's
+ * History, which keeps every state the diagram went through (a restore
+ * adds a copy of an older entry; copies fold into their first entry).
+ */
+export interface NodeVersion extends VersionItem {
+    /** The History entry to restore: the newest copy, as restore_version
+     * picks it (a later copy may carry page settings the first lacks) */
+    entryId: number
+    /** The version this one replaced, when it has a card (undo goes there) */
+    beforeId: string | null
+    /** Who made it: "user", "recover", "restore"; null for the AI */
+    source: string | null
+}
+
+// The blank page a tab shows before any drawing: the server keeps it in
+// History when the first write replaces it, but it is no version to show.
+// A blank page after a drawing is the canvas cleared, a version of its own
+// (restore_version offers both; the shell hides only the first)
+const BLANK_FINGERPRINT = contentFingerprint(BLANK_MXFILE)
+const isBlankPage = (xml: string) =>
+    !hasCells(xml) && contentFingerprint(xml) === BLANK_FINGERPRINT
+
+/** The ids of a document's pages; a bare model has one, without an id */
+function pageIds(xml: string): (string | undefined)[] {
+    const doc = new DOMParser().parseFromString(xml, "text/xml")
+    const ids = Array.from(doc.querySelectorAll("diagram")).map(
+        (page) => page.getAttribute("id") ?? undefined,
+    )
+    return ids.length > 0 ? ids : [undefined]
+}
+
+/** The page a change was made on: the first page with a change, else none */
+function changedPage(beforeXml: string, afterXml: string): string | undefined {
+    for (const id of pageIds(afterXml)) {
+        const { summary } = diffDiagrams(beforeXml, afterXml, id)
+        if (Object.values(summary).some((n) => n > 0)) return id
+    }
+    return undefined
+}
+
+/** What a version changed, kept from its first appearance (see buildVersions) */
+interface Change {
+    beforeXml: string
+    pageId?: string
+    summary: ChangeSummary
+    fromScratch: boolean
+}
+
+/**
+ * What buildVersions keeps between calls, keyed by content: a version's
+ * number and change never move, also when its first copy drops out of the
+ * server's buffer and a later copy stands in. Content no entry of the
+ * list has any more is dropped (the server keeps 20 entries; the full
+ * documents in here would otherwise grow with every edit of the session)
+ */
+export interface VersionCache {
+    numbers: Map<string, number>
+    changes: Map<string, Change>
+    /** The number the next new version gets */
+    next: number
+}
+
+export const newVersionCache = (): VersionCache => ({
+    numbers: new Map(),
+    changes: new Map(),
+    next: 1,
+})
+
+/**
+ * The version cards for a History list: entries folded by content, in the
+ * order of their first copy, numbered as they first appeared in this tab,
+ * each with what changed since the state it replaced (the entry right
+ * before its first copy; after a restore that is another than the card
+ * before). The thumbnail is the newest copy's that has one, or an older
+ * copy's of the same document (isSameDocument: a copy with other page
+ * settings looks different); the newest version on the canvas waits for
+ * its picture (the sync sends it), older ones without any show none.
+ */
+export function buildVersions(
+    list: HistoryList,
+    cache: VersionCache,
+): { versions: NodeVersion[]; onCanvasId: string | null } {
+    // The server folds entries by content (firstId). A blank page after a
+    // drawing is a clear of the canvas, a version of its own, which the
+    // server folds into the blank page the tab started with: blanks are
+    // grouped here, a restore's copy of a clear with the newest clear
+    const groups = new Map<number, HistoryEntryInfo[]>()
+    const keys = new Map<number, number>() // entry id -> its group
+    const befores = new Map<number, HistoryEntryInfo>() // group -> entry before it
+    const hidden = new Set<number>() // the blank page(s) before any drawing
+    let drawn = false
+    let lastClear: number | null = null
+    list.entries.forEach((entry, i) => {
+        let key = entry.firstId
+        if (!isBlankPage(entry.xml)) {
+            drawn = true
+        } else if (drawn || cache.numbers.has(`clear:${entry.id}`)) {
+            // A clear this tab has shown stays one when the drawing before
+            // it dropped out of the server's buffer
+            drawn = true
+            key =
+                entry.source === "restore" && lastClear !== null
+                    ? lastClear
+                    : entry.id
+            lastClear = key
+        } else {
+            hidden.add(key)
+        }
+        keys.set(entry.id, key)
+        const copies = groups.get(key)
+        if (copies) copies.push(entry)
+        else {
+            groups.set(key, [entry])
+            if (i > 0) befores.set(key, list.entries[i - 1])
+        }
+    })
+    const onCanvasId =
+        list.currentId !== null && keys.has(list.currentId)
+            ? String(keys.get(list.currentId))
+            : null
+    const versions: NodeVersion[] = []
+    const seen = new Set<string>() // the content keys of this list
+    for (const [key, copies] of groups) {
+        if (hidden.has(key)) continue
+        const first = copies[0]
+        const newest = copies[copies.length - 1]
+        const previous = befores.get(key) ?? null
+        // Clears have one content: each is its own version
+        const contentKey = isBlankPage(first.xml)
+            ? `clear:${key}`
+            : contentFingerprint(first.xml)
+        seen.add(contentKey)
+        let number = cache.numbers.get(contentKey)
+        if (number === undefined) {
+            number = cache.next++
+            cache.numbers.set(contentKey, number)
+        }
+        let change = cache.changes.get(contentKey)
+        if (!change) {
+            const beforeXml = previous?.xml ?? ""
+            const pageId = changedPage(beforeXml, first.xml)
+            const { summary, fromScratch } = diffDiagrams(
+                beforeXml,
+                first.xml,
+                pageId,
+            )
+            change = { beforeXml, pageId, summary, fromScratch }
+            cache.changes.set(contentKey, change)
+        }
+        const svg = [...copies]
+            .reverse()
+            .find((c) => c.svg && isSameDocument(c.xml, newest.xml))?.svg
+        const beforeKey = previous ? keys.get(previous.id) : undefined
+        versions.push({
+            id: String(key),
+            entryId: newest.id,
+            beforeId:
+                beforeKey !== undefined && !hidden.has(beforeKey)
+                    ? String(beforeKey)
+                    : null,
+            number,
+            xml: newest.xml,
+            beforeXml: change.beforeXml,
+            ...(change.pageId && { pageId: change.pageId }),
+            summary: change.summary,
+            fromScratch: change.fromScratch,
+            svg: svg || "",
+            source: first.source,
+        })
+    }
+    // The newest version on the canvas waits for its picture
+    const latest = versions.at(-1)
+    if (latest && !latest.svg && latest.id === onCanvasId) {
+        latest.svg = undefined
+    }
+    for (const key of cache.numbers.keys()) {
+        if (!seen.has(key)) cache.numbers.delete(key)
+    }
+    for (const key of cache.changes.keys()) {
+        if (!seen.has(key)) cache.changes.delete(key)
+    }
+    return { versions, onCanvasId }
+}
+
+/** The versions source with the shell's own version type */
+export interface NodeVersionsSource extends Omit<VersionsSource, "versions"> {
+    versions: NodeVersion[]
+}
+
+/**
+ * The canvas components' versions, from the MCP server's History: read
+ * again whenever the sync reports a change on the server, restored through
+ * it. Undo and redo of the newest version restore the one it replaced, or
+ * it again; the server keeps the state they leave as an entry of its own,
+ * so hand edits are never lost.
+ */
+export function useNodeVersions(sync: McpSync | null): NodeVersionsSource {
+    const dict = useDictionary()
+    const [list, setList] = useState<HistoryList | null>(null)
+    const [busy, setBusy] = useState(false)
+    // Stable across refreshes: a version's number and change never move
+    const cacheRef = useRef(newVersionCache())
+    // The server state the cards are of: another one (the session expired,
+    // the process restarted) is a History of its own, numbered anew
+    const cacheStateIdRef = useRef<string | null>(null)
+    // Reads overlap when changes come fast; only the latest one counts
+    const readSeqRef = useRef(0)
+
+    const refresh = useCallback(async () => {
+        if (!sync) return
+        const seq = ++readSeqRef.current
+        const next = await sync.fetchHistory()
+        if (!next || seq !== readSeqRef.current) return
+        if (next.stateId !== cacheStateIdRef.current) {
+            cacheRef.current = newVersionCache()
+            cacheStateIdRef.current = next.stateId
+        }
+        setList(next)
+    }, [sync])
+
+    useEffect(() => {
+        if (!sync) return
+        refresh()
+        return sync.onServerChange(refresh)
+    }, [sync, refresh])
+
+    const { versions, onCanvasId } = useMemo(
+        () =>
+            list
+                ? buildVersions(list, cacheRef.current)
+                : { versions: [], onCanvasId: null },
+        [list],
+    )
+
+    const restore = async (id: string) => {
+        if (!sync || !list || busy) return
+        const version = versions.find((v) => v.id === id)
+        if (!version) return
+        setBusy(true)
+        // The canvas components wait (SelectionAsk, the cards' buttons)
+        useCanvasStore.getState().set({ isBusy: true })
+        try {
+            const result = await sync.restoreEntry(
+                version.entryId,
+                list.stateId,
+            )
+            if (result === "ok") {
+                toast.success(
+                    formatMessage(dict.versions.restoredVersion, {
+                        n: version.number,
+                    }),
+                    { duration: 4000 },
+                )
+            }
+            // The sync's notices tell about a stale list or a failure; the
+            // list on screen is read again either way
+            await refresh()
+        } finally {
+            setBusy(false)
+            useCanvasStore.getState().set({ isBusy: false })
+        }
+    }
+
+    const latest = versions.at(-1)
+    // The version the newest one replaced (restore_version's steps_back=1)
+    const previous = latest?.beforeId
+        ? versions.find((v) => v.id === latest.beforeId)
+        : undefined
+    const canUndo = !!latest && !!previous && onCanvasId === latest.id
+    // The newest change is undone when the canvas is at the version before
+    const undoneId =
+        latest && previous && onCanvasId === previous.id ? latest.id : null
+
+    return {
+        versions,
+        onCanvasId,
+        undoneId,
+        isBusy: busy,
+        canUndo,
+        canRedo: undoneId !== null,
+        restore,
+        undo: () => {
+            if (canUndo && previous) restore(previous.id)
+        },
+        redo: () => {
+            if (undoneId && latest) restore(latest.id)
+        },
+    }
+}

packages/mcp-server/shell/runtime-config.ts

@@ -0,0 +1,64 @@
+/**
+ * What the MCP server writes into the shell page as window.__MCP_CONFIG__
+ * (http-server.ts fills the {{CONFIG_JSON}} placeholder of index.html).
+ */
+export interface ShellConfig {
+    sessionId: string
+    /** Every /api request carries it in the X-Drawio-Token header */
+    token: string
+    /** Prefix of the server's API paths */
+    apiBase: string
+    /** The editor page: the bundled copy's index.html on this origin, or an
+     * external draw.io */
+    drawioBaseUrl: string
+    /** draw.io theme fixed by DRAWIO_UI; "" leaves the pick to draw.io */
+    drawioUi: string
+    /** Editor language fixed by DRAWIO_LANG, in draw.io's naming; "" leaves
+     * the pick to draw.io */
+    drawioLang: string
+    /** DRAWIO_DARK: the theme when the user has not chosen one here */
+    drawioDark: "dark" | "light" | "auto"
+    /** DRAWIO_LANG as given, for the shell's own texts */
+    lang: string
+}
+
+const DEFAULTS: ShellConfig = {
+    sessionId: "",
+    token: "",
+    apiBase: "/api",
+    drawioBaseUrl: "/drawio/index.html",
+    drawioUi: "",
+    drawioLang: "",
+    drawioDark: "auto",
+    lang: "",
+}
+
+/**
+ * The page's config with every field present: a missing or malformed one
+ * (another server version) takes its default.
+ */
+export function readShellConfig(source: unknown): ShellConfig {
+    const given =
+        source && typeof source === "object"
+            ? (source as Record<string, unknown>)
+            : {}
+    const config = { ...DEFAULTS }
+    for (const key of Object.keys(DEFAULTS) as (keyof ShellConfig)[]) {
+        const value = given[key]
+        if (key === "drawioDark") {
+            if (value === "dark" || value === "light" || value === "auto") {
+                config.drawioDark = value
+            }
+        } else if (typeof value === "string") {
+            config[key] = value
+        }
+    }
+    return config
+}
+
+/** The config the server wrote into this page */
+export function pageShellConfig(): ShellConfig {
+    return readShellConfig(
+        (window as { __MCP_CONFIG__?: unknown }).__MCP_CONFIG__,
+    )
+}

packages/mcp-server/shell/shell.css

@@ -0,0 +1,20 @@
+/*
+ * Stylesheet of the MCP's canvas shell: the web app's theme and Tailwind,
+ * with the utility classes of the shared components the shell bundles.
+ * Built by scripts/build-shell.mjs; Tailwind scans this directory on its
+ * own, and the shared components through the @source lines.
+ */
+@import "../../../app/globals.css";
+@source "../../../components/canvas";
+@source "../../../components/ui";
+@source "../../../components/ai-elements";
+@source "../../../components/workspace/app-toaster.tsx";
+@source "../../../components/save-dialog.tsx";
+
+/* System fonts stand in for the web fonts the Next.js layout loads */
+:root {
+    --font-latin:
+        ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto,
+        "Helvetica Neue", Arial, sans-serif;
+    --font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+}

packages/mcp-server/shell/theme.ts

@@ -0,0 +1,61 @@
+import { useSettingsStore } from "@/stores/settings-store"
+import type { ShellConfig } from "./runtime-config"
+
+/**
+ * localStorage key of the user's theme choice here: "true" dark, "false"
+ * light, none: the server's DRAWIO_DARK, else the system. Its own prefix,
+ * so a web app dev server on the same port keeps its own settings.
+ * index.html repeats the key in its inline script (run before this bundle).
+ */
+export const THEME_STORAGE_KEY = "mcp:dark-mode"
+
+/** Whether the shell is dark, from the choice stored here, the server's
+ * setting and the system */
+export function isDarkPreferred(
+    stored: string | null,
+    drawioDark: ShellConfig["drawioDark"],
+    systemDark: boolean,
+): boolean {
+    if (stored === "true" || stored === "false") return stored === "true"
+    if (drawioDark === "auto") return systemDark
+    return drawioDark === "dark"
+}
+
+function read(): string | null {
+    try {
+        return localStorage.getItem(THEME_STORAGE_KEY)
+    } catch {
+        return null
+    }
+}
+
+// The canvas components read the settings store's isDark (and the theme
+// class, set before the first paint by index.html)
+function apply(isDark: boolean) {
+    document.documentElement.classList.toggle("dark", isDark)
+    useSettingsStore.setState({
+        hydrated: true,
+        isDark,
+        theme: isDark ? "dark" : "light",
+    })
+}
+
+/** Take the theme the inline script chose, and follow the system while
+ * nothing else decides */
+export function initTheme(drawioDark: ShellConfig["drawioDark"]) {
+    const query = window.matchMedia("(prefers-color-scheme: dark)")
+    apply(isDarkPreferred(read(), drawioDark, query.matches))
+    query.addEventListener("change", (event) => {
+        apply(isDarkPreferred(read(), drawioDark, event.matches))
+    })
+}
+
+/** The user's choice, kept for the next visit */
+export function setDark(isDark: boolean) {
+    try {
+        localStorage.setItem(THEME_STORAGE_KEY, String(isDark))
+    } catch {
+        // Storage can be unavailable (private mode, quota)
+    }
+    apply(isDark)
+}

packages/mcp-server/shell/tsconfig.json

@@ -0,0 +1,10 @@
+{
+    "extends": "../../../tsconfig.json",
+    "compilerOptions": {
+        "noEmit": true,
+        "incremental": false,
+        "plugins": []
+    },
+    "include": ["./**/*.ts", "./**/*.tsx"],
+    "exclude": ["node_modules"]
+}

packages/mcp-server/shell/use-mcp-sync.ts

@@ -0,0 +1,132 @@
+import { useEffect, useRef, useState } from "react"
+import { toast } from "sonner"
+import { useDiagram } from "@/contexts/diagram-context"
+import { useDictionary } from "@/hooks/use-dictionary"
+import { diffDiagrams } from "@/lib/diagram-diff"
+import {
+    highlightChangedCells,
+    readSelectionDetails,
+} from "@/lib/drawio/editor-bridge"
+import { useCanvasStore } from "@/stores/canvas-store"
+import { createMcpSync, type McpSync, type SyncStatus } from "./mcp-sync-core"
+import type { ShellConfig } from "./runtime-config"
+
+/**
+ * Keeps the canvas in step with the MCP server (mcp-sync-core.ts has the
+ * protocol): mounted once inside DiagramProvider. Server writes go on the
+ * canvas through loadDiagram, as one undo step when they can; the user's
+ * edits are pushed; the server's export and sync requests are answered.
+ * Returns the connection state for the status bar, and the sync itself for
+ * the version cards (History and restores go through it).
+ */
+export function useMcpSync(config: ShellConfig): {
+    status: SyncStatus
+    sync: McpSync | null
+} {
+    const dict = useDictionary()
+    const diagram = useDiagram()
+    const [status, setStatus] = useState<SyncStatus>("waiting")
+    const [sync, setSync] = useState<McpSync | null>(null)
+    const syncRef = useRef<McpSync | null>(null)
+    // The provider's functions are new on every render; the sync (created
+    // once) reads the latest through refs
+    const diagramRef = useRef(diagram)
+    diagramRef.current = diagram
+    const dictRef = useRef(dict)
+    dictRef.current = dict
+
+    useEffect(() => {
+        if (!config.sessionId) return
+        const sync = createMcpSync({
+            sessionId: config.sessionId,
+            apiBase: config.apiBase,
+            token: config.token,
+            canvas: {
+                load: (xml, decision) =>
+                    diagramRef.current.loadDiagram(
+                        xml,
+                        true,
+                        decision.mode,
+                        decision.mode === "commit"
+                            ? { pageId: decision.pageId }
+                            : undefined,
+                    ),
+                showTransient: (xml) => diagramRef.current.showTransient(xml),
+                export: (request, timeoutMs) =>
+                    diagramRef.current.requestExport(request, timeoutMs),
+                currentXml: () => diagramRef.current.chartXMLRef.current,
+                currentPageId: () => useCanvasStore.getState().currentPageId,
+                loadPending: () => diagramRef.current.hasPendingLoad(),
+                // The bridge reads the editor directly; without it (an
+                // external draw.io) the selection cannot be read
+                readSelection: () =>
+                    readSelectionDetails() ?? {
+                        pageId: null,
+                        pageName: null,
+                        cells: [],
+                        unavailable: true,
+                    },
+            },
+            onNotice: (notice) =>
+                toast(dictRef.current.shell[notice], { duration: 8000 }),
+            onStatus: setStatus,
+            isHidden: () => document.visibilityState === "hidden",
+        })
+        syncRef.current = sync
+        setSync(sync)
+        sync.setReady(diagramRef.current.isDrawioReady)
+        sync.start()
+
+        // draw.io's autosave and load events, as the classic page reads
+        // them: the frame component handles them for the canvas, the sync
+        // needs them for the protocol (an edit to push, a load done)
+        const drawioOrigin = new URL(config.drawioBaseUrl, location.href).origin
+        const onMessage = (event: MessageEvent) => {
+            if (event.source === window || event.origin !== drawioOrigin) {
+                return
+            }
+            if (typeof event.data !== "string") return
+            let message: { event?: string; xml?: unknown }
+            try {
+                message = JSON.parse(event.data)
+            } catch {
+                return
+            }
+            if (
+                message.event === "autosave" &&
+                typeof message.xml === "string"
+            ) {
+                sync.onAutoSave(message.xml)
+            } else if (message.event === "load") {
+                sync.onDrawioLoad()
+            }
+        }
+        window.addEventListener("message", onMessage)
+        return () => {
+            window.removeEventListener("message", onMessage)
+            sync.stop()
+            syncRef.current = null
+            setSync(null)
+        }
+    }, [config])
+
+    useEffect(() => {
+        syncRef.current?.setReady(diagram.isDrawioReady)
+    }, [diagram.isDrawioReady])
+
+    // Mark what a server write changed on the page, as the web app does
+    // for its versions (use-versions.ts); any action on the canvas clears it
+    useEffect(() => {
+        diagram.setCommitHandler(({ beforeXml, afterXml, pageId }) => {
+            const { touchedIds, fromScratch } = diffDiagrams(
+                beforeXml,
+                afterXml,
+                pageId,
+            )
+            if (!fromScratch) highlightChangedCells(touchedIds)
+        })
+        return () => diagram.setCommitHandler(null)
+    }, [])
+
+    return { status, sync }
+}

packages/mcp-server/shell/versions-panel.tsx

@@ -0,0 +1,50 @@
+import { useEffect, useRef } from "react"
+import { VersionCard } from "@/components/canvas/version-card"
+import { useDictionary } from "@/hooks/use-dictionary"
+import type { Dictionary } from "@/lib/i18n/dictionaries"
+import type { NodeVersion } from "./node-versions-source"
+
+/** What a card says happened: the web app's chat knows the tool that ran,
+ * the shell tells from who made the entry and what changed */
+export function versionLabel(version: NodeVersion, dict: Dictionary): string {
+    if (version.source === "user" || version.source === "recover") {
+        return dict.shell.userEdit
+    }
+    return version.fromScratch ? dict.versions.created : dict.versions.edited
+}
+
+/** The version cards, oldest first, as the web app's chat shows them */
+export function VersionsPanel({ versions }: { versions: NodeVersion[] }) {
+    const dict = useDictionary()
+    const listRef = useRef<HTMLDivElement>(null)
+
+    // Keep the newest version in view
+    useEffect(() => {
+        const el = listRef.current
+        if (el) el.scrollTo({ top: el.scrollHeight, behavior: "smooth" })
+    }, [versions.length])
+
+    return (
+        <aside
+            className="flex w-[340px] shrink-0 flex-col border-l border-border bg-surface-0"
+            data-testid="versions-panel"
+        >
+            <div className="flex h-9 shrink-0 items-center px-3.5 text-xs font-medium text-muted-foreground">
+                {dict.versions.strip}
+            </div>
+            <div
+                ref={listRef}
+                className="flex min-h-0 flex-1 flex-col gap-2 overflow-y-auto px-3 pb-3 scrollbar-thin"
+            >
+                {versions.map((version, i) => (
+                    <VersionCard
+                        key={version.id}
+                        version={version}
+                        isLatest={i === versions.length - 1}
+                        label={versionLabel(version, dict)}
+                    />
+                ))}
+            </div>
+        </aside>
+    )
+}

packages/mcp-server/src/custom-instructions.ts

@@ -0,0 +1,58 @@
+/**
+ * The user's own drawing rules, kept in a Markdown file and appended to the
+ * drawing guide, like the web app's custom system message
+ * (app/api/chat/route.ts). The file is read on every call, so edits apply
+ * without restarting the MCP host.
+ */
+
+import { readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+import { log } from "./logger.ts"
+import { expandHome } from "./persistence.ts"
+
+export const CUSTOM_INSTRUCTIONS_FILE = "instructions.md"
+
+// Same cap as the web app's custom system message
+const MAX_CHARS = 5000
+
+/**
+ * DRAWIO_DATA_DIR, default ~/.next-ai-drawio. "off" only turns auto-save
+ * off; this file is merely read, so the default folder is used then.
+ */
+export function customInstructionsDir(): string {
+    const dir = process.env.DRAWIO_DATA_DIR
+    return dir && dir !== "off"
+        ? expandHome(dir)
+        : join(homedir(), ".next-ai-drawio")
+}
+
+/** Full path of the instructions file. */
+export function customInstructionsPath(dir = customInstructionsDir()): string {
+    return join(dir, CUSTOM_INSTRUCTIONS_FILE)
+}
+
+let warned = false
+
+/** The file's content, trimmed and capped; "" when there is none. */
+export function readCustomInstructions(dir = customInstructionsDir()): string {
+    const path = customInstructionsPath(dir)
+    try {
+        return readFileSync(path, "utf-8").trim().slice(0, MAX_CHARS)
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT" && !warned) {
+            warned = true
+            log.warn(`Could not read the custom instructions ${path}: ${error}`)
+        }
+        return ""
+    }
+}
+
+/** The guide with the user's rules appended under "## Custom Instructions". */
+export function guideWithCustomInstructions(
+    guide: string,
+    dir?: string,
+): string {
+    const text = readCustomInstructions(dir)
+    return text ? `${guide}\n\n## Custom Instructions\n${text}` : guide
+}

packages/mcp-server/src/drawing-guide.ts

@@ -18,13 +18,19 @@ import {
 export const DRAWING_GUIDE = `# Draw.io drawing guide
 
 ## Workflow
-- create_new_diagram draws a new diagram and REPLACES the whole document. add_page adds another tab. edit_diagram changes cells of an existing page. load_diagram opens a .drawio file (the server reads the file itself). get_diagram returns the current XML, including the user's manual edits. export_diagram saves to a file.
+- create_new_diagram draws a new diagram and REPLACES the whole document. add_page adds another tab. edit_diagram changes cells of an existing page. load_diagram opens a .drawio file (the server reads the file itself, or takes the file's content as its 'xml' argument when you already have it in hand). get_diagram returns the current XML, including the user's manual edits. export_diagram saves to a file.
+- When the user refers to what they selected in the preview ("this box", "these arrows"), call get_selection: it returns the selected cells' ids, labels and page, ready for edit_diagram.
 - Before drawing, describe your layout plan in 2-3 sentences, so shapes do not overlap and edges do not cross shapes.
 - Send XML only through tool calls, never in chat text. Never draw a box just to send the user a message.
 - Before using any icon library (AWS, Azure, GCP, Kubernetes, Cisco, BPMN, Material Design, web icons...), call get_shape_library and use the exact style names it returns. NEVER guess icon style names. For AWS, use the AWS 2025 icons (library aws4).
-- After drawing or heavily editing a complex diagram, call screenshot_diagram once to see the result, and fix overlapping shapes and edges that cross shapes.
-- When replicating a diagram from an image, match its style and layout closely: straight or curved lines, rounded or square shapes.
-- The preview page has History (it saves a snapshot before every AI change and can restore any of the last 20 versions) and Download. You can make changes freely; nothing is lost.
+- After drawing or heavily editing a complex diagram, pass screenshot: true on that create_new_diagram or edit_diagram call (or call screenshot_diagram) to see the result, and fix overlapping shapes and edges that cross shapes.
+- Drawing from a source: to draw from a document (PDF, Markdown, code, data), an image or screenshot, or a web page, first read it yourself (the attachment the user shared, or your own file-reading or web-fetch tools), then plan the layout and draw. This server never receives attachments; it only receives the XML you send. Extract the entities and relationships the diagram needs; do not copy the text into boxes.
+- When replicating a diagram from an image, match its style and layout closely: straight or curved lines, rounded or square shapes, colors and relative positions. Call screenshot_diagram afterwards and compare with the original.
+- After a successful create_new_diagram or edit_diagram call, do not describe the diagram; the user sees it in the preview. One short sentence at most.
+- For artistic requests (a cat, a logo, a scene), compose the picture from standard shapes and connectors while keeping it clear.
+- To clear the canvas to one blank page, call create_new_diagram with only the two root cells <mxCell id="0"/><mxCell id="1" parent="0"/>; the previous diagram stays in History.
+- The preview keeps the last 20 versions (a snapshot before every AI change) and can restore any of them. You can make changes freely; nothing is lost.
+- If the user asks to undo or go back, call restore_version instead of re-sending the earlier XML from memory.
 
 ## The XML you send
 Single page (create_new_diagram, add_page): send ONLY the named styles and the mxCell elements. The server adds <mxfile>, <mxGraphModel>, <root> and the root cells id="0" and id="1", expands named styles (see Styles), adds html=1 to every cell and whiteSpace=wrap to shapes, and fills in vertex, edge, parent="1" and the mxGeometry element. A shape is one self-closing mxCell with x, y, w and h; an edge is one with source and target. A cell with source or target is always an edge. Write parent only for a shape inside a container, and an mxGeometry element only for edge waypoints or for a separate label cell placed on an edge: <mxCell id="9" value="yes" style="edgeLabel;" parent="<edge id>" connectable="0"><mxGeometry x="-0.5" relative="1" as="geometry"/></mxCell>. An edge's own text simply goes in its value.
@@ -47,6 +53,8 @@ Containers and swimlanes: children use the container id as parent and coordinate
 
 ${indent(SWIMLANE_EXAMPLE)}
 
+Large diagrams: if the diagram will not fit one call, send the first cells with create_new_diagram and add the rest with edit_diagram add operations (one per cell, same id rules). A call rejected because the XML ends inside an unfinished cell drew nothing: send all of its cells again, in smaller parts if needed.
+
 ## Layout
 - Keep every element of a page within x 0 to 800 and y 0 to 600, so the whole diagram fits one view without a page break.
 - Containers (for example AWS cloud boxes) are at most 700 pixels wide and 550 pixels tall.
@@ -87,6 +95,9 @@ ${indent(STYLE_CLASS_EXAMPLE)}
 - Edges: endArrow=block, open or none; startArrow=classic; curved=1; dashed=1; edgeStyle=orthogonalEdgeStyle
 - Text: fontSize=14, fontStyle=1 (bold), align=center or right
 - Animated connectors: add flowAnimation=1 to the edge style.
+- Edge options: dashed=1; strokeWidth=2; edgeStyle=elbowEdgeStyle;elbow=vertical (or horizontal); jumpStyle=arc;jumpSize=10 where edges cross.
+
+For tables, layers or groups, call get_drawing_guide with topic=tables, layers or groups.
 
 ## Minimal style
 When the user asks for a minimal, plain, black-and-white or unstyled diagram, use these rules instead of the styles above:
@@ -100,7 +111,7 @@ When the user asks for a minimal, plain, black-and-white or unstyled diagram, us
 - add inserts a new cell with a new id. One cell per operation.
 - delete removes a cell. Its children and every edge connected to it are deleted too, so give only the container's id.
 - All-or-nothing: if any operation fails, nothing is applied. A rejected call includes the current XML of the page; rebuild your operations on it and retry.
-- If the diagram is large, change it with edit_diagram instead of redrawing it.
+- Use create_new_diagram for a new diagram, a major restructuring or an empty canvas. Use edit_diagram for small changes: adding or removing a few elements, labels, colors or positions. Never redraw a large diagram for a small change.
 
     {"operations": [{"operation": "update", "cell_id": "3", "new_xml": "<mxCell id=\\"3\\" value=\\"New Label\\" style=\\"rounded=1;\\" x=\\"100\\" y=\\"100\\" w=\\"120\\" h=\\"60\\"/>"}]}
     {"page_name": "CNN", "operations": [{"operation": "add", "cell_id": "conv-1", "new_xml": "<mxCell id=\\"conv-1\\" value=\\"Conv\\" x=\\"40\\" y=\\"40\\" w=\\"120\\" h=\\"60\\"/>"}]}

packages/mcp-server/src/drawio-themes.ts

@@ -0,0 +1,24 @@
+export const DRAWIO_THEMES = [
+    "kennedy",
+    "atlas",
+    "dark",
+    "min",
+    "sketch",
+    "simple",
+] as const
+
+export type DrawioTheme = (typeof DRAWIO_THEMES)[number]
+
+export function isDrawioTheme(value: unknown): value is DrawioTheme {
+    return (
+        typeof value === "string" &&
+        (DRAWIO_THEMES as readonly string[]).includes(value)
+    )
+}
+
+/** draw.io's name for a locale: lowercase, "zh-tw" for Traditional and "zh" for Simplified Chinese */
+export function toDrawioLang(locale: string): string {
+    const lang = locale.toLowerCase()
+    if (lang === "zh-hant") return "zh-tw"
+    return lang === "zh-hans" ? "zh" : lang
+}

packages/mcp-server/src/drawio-version.json

@@ -0,0 +1,5 @@
+{
+    "version": "v32.0.2",
+    "sha256": "3cb8abec8e9bfc7504760c9cdc9194ecf7e8de178aa2a1d668801c32ecf1a1a7",
+    "downloadUrl": "https://github.com/jgraph/drawio/releases/download/v32.0.2/draw.war"
+}

packages/mcp-server/src/edit-gate.ts

@@ -142,3 +142,116 @@ export function markPageSeen(
         ? liveXml
         : lastSeenXml
 }
+
+const CELL_TAGS = new Set(["mxCell", "UserObject", "object"])
+
+/** The cells of a page by id: the direct children of its <root>. */
+function pageCells(page: Element): Map<string, Element> {
+    const cells = new Map<string, Element>()
+    for (const el of Array.from(page.querySelector("root")?.children ?? [])) {
+        const id = el.getAttribute("id")
+        if (id && CELL_TAGS.has(el.tagName)) cells.set(id, el)
+    }
+    return cells
+}
+
+/** `id ("label")`: the cell's value without HTML, cut at 30 characters. */
+function describeCell(id: string, cell: Element): string {
+    // getAttributeNode gives the decoded value (linkedom's getAttribute
+    // escapes it again); an HTML label then still holds tags and entities
+    const label = (
+        (cell.getAttributeNode("value") ?? cell.getAttributeNode("label"))
+            ?.value ?? ""
+    )
+        .replace(/<[^>]*>/g, " ")
+        .replace(/&nbsp;/g, " ")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&amp;/g, "&")
+        .replace(/\s+/g, " ")
+        .trim()
+    if (!label) return id
+    return `${id} ("${label.length > 30 ? `${label.slice(0, 30)}...` : label}")`
+}
+
+/** At most 20 entries, then "and N more". */
+function listCells(cells: string[]): string {
+    const shown = cells.slice(0, 20).join(", ")
+    return cells.length > 20 ? `${shown} and ${cells.length - 20} more` : shown
+}
+
+/**
+ * One paragraph naming what the user changed between the XML the model last
+ * saw and the live store, for stale rejections and get_diagram. Pages are
+ * paired by index (draw.io regenerates diagram ids on re-serialisation) and
+ * cells by id. Returns "" when there is nothing to compare or the two sides
+ * have the same content.
+ */
+export function describeChanges(lastSeenXml: string, liveXml: string): string {
+    if (!lastSeenXml || lastSeenXml === liveXml) return ""
+    const parse = (xml: string) => {
+        const normalized = normalizeToMxfile(xml)
+        return normalized ? parseMxfile(normalized) : null
+    }
+    const before = parse(lastSeenXml)
+    const live = parse(liveXml)
+    if (!before || !live) return ""
+    // Same rule as checkEditGate: a bare <mxGraphModel> carries no page name
+    const includeNames =
+        !isMxGraphModel(liveXml) && !isMxGraphModel(lastSeenXml)
+    if (
+        contentFingerprint(lastSeenXml, includeNames) ===
+        contentFingerprint(liveXml, includeNames)
+    )
+        return ""
+
+    const pagesBefore = Array.from(before.querySelectorAll("diagram"))
+    const pagesLive = Array.from(live.querySelectorAll("diagram"))
+    const pageCount = Math.max(pagesBefore.length, pagesLive.length)
+    const clauses: string[] = []
+    const renames: string[] = []
+    for (let i = 0; i < pageCount; i++) {
+        const pageBefore = pagesBefore[i]
+        const pageLive = pagesLive[i]
+        if (!pageBefore || !pageLive) {
+            clauses.push(`page ${i + 1} ${pageLive ? "added" : "removed"}`)
+            continue
+        }
+        const cellsBefore = pageCells(pageBefore)
+        const cellsLive = pageCells(pageLive)
+        const modified: string[] = []
+        const added: string[] = []
+        const removed: string[] = []
+        for (const [id, cell] of cellsLive) {
+            const old = cellsBefore.get(id)
+            if (!old) added.push(describeCell(id, cell))
+            else if (canonicalizeElement(old) !== canonicalizeElement(cell))
+                modified.push(describeCell(id, cell))
+        }
+        for (const [id, cell] of cellsBefore) {
+            if (!cellsLive.has(id)) removed.push(describeCell(id, cell))
+        }
+        // Name the page only when the document has several
+        const where = pageCount > 1 ? `page ${i + 1} ` : ""
+        if (modified.length)
+            clauses.push(`${where}modified ${listCells(modified)}`)
+        if (added.length) clauses.push(`${where}added ${listCells(added)}`)
+        if (removed.length)
+            clauses.push(`${where}removed ${listCells(removed)}`)
+        if (includeNames) {
+            const name = pageLive.getAttribute("name") ?? ""
+            if (name !== (pageBefore.getAttribute("name") ?? ""))
+                renames.push(`Page ${i + 1} renamed to "${name}".`)
+        }
+    }
+    // The fingerprint also covers the cell order (z-order) and anything in
+    // <root> that is not a cell
+    if (!clauses.length && !renames.length)
+        clauses.push("the order of the cells changed")
+    const intro = "Since you last saw it, the user changed the diagram"
+    const body = clauses.length
+        ? `${intro}: ${clauses.join("; ")}.`
+        : `${intro}.`
+    return [body, ...renames].join(" ")
+}

packages/mcp-server/src/history.ts

@@ -3,20 +3,36 @@
  * Stores {xml, svg} entries in a circular buffer
  */
 
+import { contentFingerprint } from "./edit-gate.ts"
 import { log } from "./logger.ts"
+import { isMxGraphModel } from "./pages.ts"
 
 const MAX_HISTORY = 20
 
-interface HistoryEntry {
+/**
+ * Who made an entry's diagram: an edit in the browser ("user"), a tab's
+ * copy kept when the server recovered the session ("recover"), a restored
+ * copy of an older entry ("restore"). The AI's writes and entries loaded
+ * from the saved file carry none.
+ */
+export type HistorySource = "user" | "recover" | "restore"
+
+export interface HistoryEntry {
     id: number // Stable across shifts of the circular buffer
     xml: string
     svg: string
+    source?: HistorySource
 }
 
 let nextEntryId = 0
 const historyStore = new Map<string, HistoryEntry[]>()
 
-export function addHistory(sessionId: string, xml: string, svg = ""): number {
+export function addHistory(
+    sessionId: string,
+    xml: string,
+    svg = "",
+    source?: HistorySource,
+): number {
     let history = historyStore.get(sessionId)
     if (!history) {
         history = []
@@ -32,7 +48,12 @@ export function addHistory(sessionId: string, xml: string, svg = ""): number {
         return history.length - 1
     }
 
-    history.push({ id: nextEntryId++, xml, svg })
+    history.push({
+        id: nextEntryId++,
+        xml,
+        svg,
+        ...(source && { source }),
+    })
 
     // Circular buffer
     if (history.length > MAX_HISTORY) {
@@ -59,6 +80,107 @@ export function clearHistory(sessionId: string): void {
     historyStore.delete(sessionId)
 }
 
+/**
+ * The versions the diagram can go back (or forward) to: every entry whose
+ * content differs from currentXml, newest first, one entry per distinct
+ * content (its newest copy). Re-serialised copies of one diagram count as
+ * the same version.
+ */
+export function otherVersions(
+    sessionId: string,
+    currentXml: string,
+): HistoryEntry[] {
+    const kept = [versionOf(currentXml)]
+    const result: HistoryEntry[] = []
+    const history = getHistory(sessionId)
+    for (let i = history.length - 1; i >= 0; i--) {
+        const version = entryVersion(history[i])
+        if (kept.some((seen) => sameVersion(seen, version))) continue
+        kept.push(version)
+        result.push(history[i])
+    }
+    return result
+}
+
+/** True when History holds a copy of this diagram. */
+export function isInHistory(sessionId: string, xml: string): boolean {
+    const version = versionOf(xml)
+    return getHistory(sessionId).some((entry) =>
+        sameVersion(version, entryVersion(entry)),
+    )
+}
+
+/**
+ * The entry the canvas shows: the newest one with the content of xml (the
+ * rule of otherVersions), or null when the canvas is in none of them
+ */
+export function currentEntryId(sessionId: string, xml: string): number | null {
+    const version = versionOf(xml)
+    const history = getHistory(sessionId)
+    for (let i = history.length - 1; i >= 0; i--) {
+        if (sameVersion(version, entryVersion(history[i]))) {
+            return history[i].id
+        }
+    }
+    return null
+}
+
+/**
+ * For every entry, the id of the oldest entry with the same content (its
+ * own when no earlier one has it). A restore adds a copy of an older entry;
+ * the shell shows one version per content, where its first copy is, and
+ * restores the newest copy (as restore_version picks it). An entry is
+ * compared with the first of each group, never with later copies: a bare
+ * model matches any page name, so "same" is not transitive, and every
+ * entry must name a first copy that has its content.
+ */
+export function firstCopyIds(sessionId: string): Map<number, number> {
+    const result = new Map<number, number>()
+    const firsts: { version: Version; id: number }[] = []
+    for (const entry of getHistory(sessionId)) {
+        const version = entryVersion(entry)
+        let first = firsts.find((f) => sameVersion(f.version, version))
+        if (!first) {
+            first = { version, id: entry.id }
+            firsts.push(first)
+        }
+        result.set(entry.id, first.id)
+    }
+    return result
+}
+
+interface Version {
+    bare: boolean
+    named: string
+    cells: string
+}
+
+/** A diagram's fingerprints, with and without its page names */
+function versionOf(xml: string): Version {
+    return {
+        bare: isMxGraphModel(xml),
+        named: contentFingerprint(xml),
+        cells: contentFingerprint(xml, false),
+    }
+}
+
+// An entry's XML never changes: its fingerprints are computed once
+const entryVersions = new WeakMap<HistoryEntry, Version>()
+function entryVersion(entry: HistoryEntry): Version {
+    let version = entryVersions.get(entry)
+    if (!version) {
+        version = versionOf(entry.xml)
+        entryVersions.set(entry, version)
+    }
+    return version
+}
+
+// Same rule as checkEditGate: a bare <mxGraphModel> (the browser's sync
+// can send one) has no page name, so names count only when both have them
+function sameVersion(a: Version, b: Version): boolean {
+    return a.bare || b.bare ? a.cells === b.cells : a.named === b.named
+}
+
 /**
  * Give the last entry the image the browser took of shownXml, the diagram
  * it just loaded, when that entry is this diagram

packages/mcp-server/src/http-server.ts

@@ -3,10 +3,11 @@
  * Serves draw.io embed with state sync and history UI
  */
 
-import { randomUUID } from "node:crypto"
-import { readFileSync } from "node:fs"
+import { randomBytes, randomUUID } from "node:crypto"
+import { createReadStream, existsSync, readFileSync, statSync } from "node:fs"
 import http from "node:http"
-import { dirname, join } from "node:path"
+import { dirname, extname, join, posix, resolve, sep } from "node:path"
+import { pipeline } from "node:stream"
 import { fileURLToPath } from "node:url"
 
 const MAX_BODY_BYTES = 10 * 1024 * 1024 // 10 MiB
@@ -44,20 +45,128 @@ function readBody(
     })
 }
 
+import { isDrawioTheme, toDrawioLang } from "./drawio-themes.ts"
 import { contentFingerprint } from "./edit-gate.ts"
 import {
     addHistory,
     clearHistory,
+    currentEntryId,
+    firstCopyIds,
     getHistory,
     getHistoryEntry,
     updateLastHistorySvg,
 } from "./history.ts"
 import { log } from "./logger.ts"
 import { BLANK_MXFILE } from "./pages.ts"
+import { parseSelectionAnswer, type SelectionAnswer } from "./selection.ts"
 
-// Configurable draw.io embed URL for private deployments
-const DRAWIO_BASE_URL =
+// Configurable draw.io embed URL for private deployments. Set, it replaces
+// the bundled copy (see drawioDir below).
+export const DRAWIO_BASE_URL =
     process.env.DRAWIO_BASE_URL || "https://embed.diagrams.net"
+const EXTERNAL_DRAWIO = !!process.env.DRAWIO_BASE_URL
+
+// Every /api request must carry this token in the X-Drawio-Token header.
+// The page reads it from its HTML. Another website cannot add a custom
+// header without a CORS preflight, which this server never grants, so its
+// requests stop here whatever Host and Origin they manage to send.
+const API_TOKEN = randomBytes(16).toString("hex")
+
+export function getApiToken(): string {
+    return API_TOKEN
+}
+
+// The trimmed draw.io copy that scripts/fetch-drawio.mjs puts in dist/drawio,
+// next to the compiled server; run from src with tsx, it is one level up
+const HERE = dirname(fileURLToPath(import.meta.url))
+let drawioDir: string | null =
+    [join(HERE, "drawio"), join(HERE, "../dist/drawio")].find((dir) =>
+        existsSync(join(dir, "index.html")),
+    ) ?? null
+let drawioVersion = readDrawioVersion(drawioDir)
+
+/** For tests: serve draw.io from this directory (null: no bundled copy) */
+export function setDrawioDir(dir: string | null): void {
+    drawioDir = dir
+    drawioVersion = readDrawioVersion(dir)
+}
+
+// The canvas shell (the web app's canvas without the chat), built by
+// scripts/build-shell.mjs into dist/shell
+let shellDir: string | null =
+    [join(HERE, "shell"), join(HERE, "../dist/shell")].find((dir) =>
+        existsSync(join(dir, "index.html")),
+    ) ?? null
+
+/** For tests: serve the shell from this directory (null: not built) */
+export function setShellDir(dir: string | null): void {
+    shellDir = dir
+}
+
+// This package's version, stamped into the shell files' ETags (see
+// readDrawioVersion for why)
+const PACKAGE_VERSION: string = JSON.parse(
+    readFileSync(join(HERE, "../package.json"), "utf8"),
+).version
+
+/**
+ * The preview page start_session opens: the canvas shell (shell/, the web
+ * app's canvas), or with DRAWIO_PREVIEW_UI=classic the classic page
+ * (src/preview), kept for one more release.
+ */
+export type PreviewUi = "classic" | "shell"
+
+export function previewUiFromEnv(
+    env: NodeJS.ProcessEnv = process.env,
+): PreviewUi {
+    return (env.DRAWIO_PREVIEW_UI ?? "").toLowerCase() === "classic"
+        ? "classic"
+        : "shell"
+}
+
+export const PREVIEW_UI: PreviewUi = previewUiFromEnv()
+
+/**
+ * The page start_session actually opens: the classic page stands in while
+ * the shell is not built (a run from the sources), as embed.diagrams.net
+ * does for a missing dist/drawio
+ */
+export function activePreviewUi(ui: PreviewUi = PREVIEW_UI): PreviewUi {
+    return ui === "shell" && shellDir === null ? "classic" : ui
+}
+
+export function previewUrl(
+    port: number,
+    sessionId: string,
+    ui: PreviewUi = PREVIEW_UI,
+): string {
+    const path = activePreviewUi(ui) === "shell" ? "/shell/" : ""
+    return `http://localhost:${port}${path}?mcp=${sessionId}`
+}
+
+/**
+ * The draw.io version the fetch script stamps into the copy. It is part of
+ * every file's ETag: an install that keeps the archive's dates (npm does
+ * not) would otherwise hand out the old ETag for a changed file of the
+ * same size after an upgrade.
+ */
+function readDrawioVersion(dir: string | null): string {
+    if (!dir) return ""
+    try {
+        return readFileSync(join(dir, ".version"), "utf8").trim()
+    } catch {
+        return ""
+    }
+}
+
+/**
+ * Whether the preview embeds draw.io from its own origin (the bundled copy),
+ * which lets the page call the editor directly. False with DRAWIO_BASE_URL,
+ * or when the bundled copy is missing.
+ */
+export function isSameOriginDrawio(): boolean {
+    return !EXTERNAL_DRAWIO && drawioDir !== null
+}
 
 // Extract origin (scheme + host + port) from URL for postMessage security check
 function getOrigin(url: string): string {
@@ -148,8 +257,10 @@ interface SessionState {
     exportFormat?: ExportFormat // Set by MCP tool to request browser export
     exportXml?: string // Single-page projection to load before a page-targeted export
     exportOptions?: ExportOptions // Extra draw.io export parameters (PNG only)
-    exportId?: number // Number of the pending export, echoed with its result
+    exportId?: string // Random id of the pending export, echoed with its result
     exportData?: string // Base64/SVG data returned by browser after export
+    selectionId?: string // Random id of the pending get_selection request
+    selection?: SelectionAnswer // The page's answer to it
 }
 
 /** draw.io export formats; xmlsvg is an SVG with the diagram embedded */
@@ -224,6 +335,8 @@ export function setState(
         exportOptions: existing?.exportOptions,
         exportId: existing?.exportId,
         exportData: existing?.exportData, // Preserve export result
+        selectionId: existing?.selectionId, // Preserve pending selection request
+        selection: existing?.selection,
     })
     log.debug(`State updated: session=${sessionId}, version=${newVersion}`)
     if (notify) stateListener?.(sessionId, xml)
@@ -242,7 +355,7 @@ export function keepInHistory(sessionId: string, xml: string, svg = ""): void {
     if (state && !state.userEdited && last && last.xml === state.serverXml) {
         return
     }
-    addHistory(sessionId, xml, svg)
+    addHistory(sessionId, xml, svg, state?.userEdited ? "user" : undefined)
 }
 
 /**
@@ -269,13 +382,13 @@ export function requestExport(
     state.exportOptions = options
     state.exportFormat = format
     // The browser sends this back with the result, so a late result of an
-    // export that timed out is not taken for this one
-    state.exportId = ++lastExportId
+    // export that timed out is not taken for this one. Random rather than
+    // counted: a counter restarts with the process, and the page retries a
+    // result refused with 403 against the process that took over the port
+    state.exportId = randomUUID()
     return true
 }
 
-let lastExportId = 0
-
 export function requestSync(sessionId: string): boolean {
     const state = stateStore.get(sessionId)
     if (state) {
@@ -301,6 +414,95 @@ export async function waitForSync(
     return false // Timeout
 }
 
+/**
+ * Ask the preview tab which cells the user has selected (the get_selection
+ * tool). Answered through the poll like an export: the tab sees selectionId
+ * in GET /api/state and POSTs its reading with that id. Returns false when
+ * the session is unknown.
+ */
+export function requestSelection(sessionId: string): boolean {
+    const state = stateStore.get(sessionId)
+    if (!state) return false
+    state.selection = undefined
+    // Random, as exportId: a late answer to an earlier request, or one meant
+    // for the process that had this port before, is not taken for this one
+    state.selectionId = randomUUID()
+    return true
+}
+
+/** The tab's answer to the pending selection request, or null in time */
+export async function waitForSelection(
+    sessionId: string,
+    timeoutMs = 10000,
+): Promise<SelectionAnswer | null> {
+    const start = Date.now()
+    let answer: SelectionAnswer | undefined
+    while (Date.now() - start < timeoutMs) {
+        // Re-read the store entry each tick: setState replaces it
+        answer = stateStore.get(sessionId)?.selection
+        if (answer) break
+        await new Promise((r) => setTimeout(r, 100))
+    }
+    const state = stateStore.get(sessionId)
+    if (state) {
+        state.selection = undefined
+        state.selectionId = undefined
+    }
+    if (!answer) log.warn(`Selection timeout for session=${sessionId}`)
+    return answer ?? null
+}
+
+// One selection slot per session, as the export slot: overlapping
+// get_selection calls take turns instead of replacing each other's request
+let selectionQueue: Promise<unknown> = Promise.resolve()
+
+/** requestSelection + waitForSelection, one call at a time; null when the
+ * session is unknown or the tab does not answer in time */
+export function readSelection(
+    sessionId: string,
+    timeoutMs = 10000,
+): Promise<SelectionAnswer | null> {
+    const run = selectionQueue.then(() => {
+        if (!requestSelection(sessionId)) return null
+        return waitForSelection(sessionId, timeoutMs)
+    })
+    selectionQueue = run.catch(() => {})
+    return run
+}
+
+/**
+ * What the version cards depend on: History's entries (their count and the
+ * newest id) and the entry the canvas shows. The shell reads History again
+ * only when this changes, so a hand edit (a new version, the same History)
+ * costs no download of every entry
+ */
+function historyKeyOf(sessionId: string, state?: SessionState): string {
+    const history = getHistory(sessionId)
+    const current =
+        state && history.length > 0
+            ? currentEntryId(sessionId, state.xml)
+            : null
+    return `${history.length}:${history.at(-1)?.id ?? -1}:${current}`
+}
+
+/** POST /api/state with a selection: the tab's answer to requestSelection */
+function handleSelectionResult(
+    sessionId: string,
+    data: { selectionId?: unknown; selection?: unknown },
+): void {
+    const state = stateStore.get(sessionId)
+    // Only the pending request's answer (none pending: none is taken)
+    if (!state?.selectionId || data.selectionId !== state.selectionId) {
+        log.debug(`Ignored a late selection answer for session=${sessionId}`)
+        return
+    }
+    const answer = parseSelectionAnswer(data.selection)
+    if (!answer) return
+    state.selection = answer
+    state.selectionId = undefined
+    log.debug(`Selection received for session=${sessionId}`)
+}
+
 export function startHttpServer(port = 6002): Promise<number> {
     return new Promise((resolve, reject) => {
         if (server) {
@@ -334,6 +536,16 @@ export function startHttpServer(port = 6002): Promise<number> {
         server.listen(port, "127.0.0.1", () => {
             serverPort = port
             log.info(`HTTP server running on http://localhost:${port}`)
+            if (!EXTERNAL_DRAWIO && drawioDir === null) {
+                log.warn(
+                    "No bundled draw.io (dist/drawio missing); the preview loads it from embed.diagrams.net",
+                )
+            }
+            if (PREVIEW_UI === "shell" && activePreviewUi() === "classic") {
+                log.warn(
+                    "The canvas shell is not built (dist/shell missing); start_session opens the classic page",
+                )
+            }
             resolve(port)
         })
     })
@@ -424,7 +636,10 @@ function routeRequest(
     if (requestOrigin === `http://localhost:${serverPort}`) {
         res.setHeader("Access-Control-Allow-Origin", requestOrigin)
         res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
-        res.setHeader("Access-Control-Allow-Headers", "Content-Type")
+        res.setHeader(
+            "Access-Control-Allow-Headers",
+            "Content-Type, X-Drawio-Token",
+        )
     }
 
     if (req.method === "OPTIONS") {
@@ -433,30 +648,43 @@ function routeRequest(
         return
     }
 
+    if (url.pathname.startsWith("/drawio/")) {
+        serveStaticFile(
+            req,
+            res,
+            drawioDir,
+            url.pathname.slice("/drawio/".length),
+            drawioVersion,
+        )
+        return
+    }
+
+    if (url.pathname === "/shell") {
+        res.writeHead(302, { Location: `/shell/${url.search}` })
+        res.end()
+        return
+    }
+    if (url.pathname.startsWith("/shell/")) {
+        const rest = url.pathname.slice("/shell/".length)
+        if (rest === "" || rest === "index.html") {
+            servePage(req, res, url, "/shell/", getShellPage)
+        } else {
+            serveStaticFile(req, res, shellDir, rest, PACKAGE_VERSION)
+        }
+        return
+    }
+
+    if (
+        url.pathname.startsWith("/api/") &&
+        req.headers["x-drawio-token"] !== API_TOKEN
+    ) {
+        res.writeHead(403)
+        res.end("Forbidden")
+        return
+    }
+
     if (url.pathname === "/" || url.pathname === "/index.html") {
-        const sessionId = url.searchParams.get("mcp") || ""
-        if (sessionId && !isValidSessionId(sessionId)) {
-            res.writeHead(400)
-            res.end("Invalid session id")
-            return
-        }
-
-        // Auto-redirect to most recent session if no sessionId provided
-        if (!sessionId) {
-            const recentSessionId = getMostRecentSessionId()
-            if (recentSessionId) {
-                res.writeHead(302, {
-                    Location: `/?mcp=${encodeURIComponent(recentSessionId)}`,
-                })
-                res.end()
-                return
-            }
-        }
-
-        ensureSessionStateInitialized(sessionId)
-
-        res.writeHead(200, { "Content-Type": "text/html" })
-        res.end(getHtmlPage(sessionId))
+        servePage(req, res, url, "/", getHtmlPage)
     } else if (url.pathname === "/api/state") {
         handleStateApi(req, res, url)
     } else if (url.pathname === "/api/history") {
@@ -471,6 +699,60 @@ function routeRequest(
     }
 }
 
+/**
+ * A preview page (the classic one at "/", the shell at "/shell/") for the
+ * session in ?mcp=<id>; without one, the most recent session's.
+ */
+function servePage(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+    url: URL,
+    pagePath: string,
+    render: (sessionId: string) => string | null,
+): void {
+    if (req.method !== "GET" && req.method !== "HEAD") {
+        res.writeHead(405)
+        res.end("Method Not Allowed")
+        return
+    }
+    const sessionId = url.searchParams.get("mcp") || ""
+    if (sessionId && !isValidSessionId(sessionId)) {
+        res.writeHead(400)
+        res.end("Invalid session id")
+        return
+    }
+
+    // Auto-redirect to most recent session if no sessionId provided
+    if (!sessionId) {
+        const recentSessionId = getMostRecentSessionId()
+        if (recentSessionId) {
+            res.writeHead(302, {
+                Location: `${pagePath}?mcp=${encodeURIComponent(recentSessionId)}`,
+            })
+            res.end()
+            return
+        }
+    }
+
+    const html = render(sessionId)
+    if (html === null) {
+        res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" })
+        res.end(
+            "The canvas shell is not built (dist/shell is missing); run npm run build in packages/mcp-server",
+        )
+        return
+    }
+    ensureSessionStateInitialized(sessionId)
+
+    // The page holds this process's token: never served from a cache
+    res.writeHead(200, {
+        "Content-Type": "text/html; charset=utf-8",
+        "Cache-Control": "no-store",
+        ...HTML_SECURITY_HEADERS,
+    })
+    res.end(req.method === "HEAD" ? undefined : html)
+}
+
 function handleStateApi(
     req: http.IncomingMessage,
     res: http.ServerResponse,
@@ -500,6 +782,8 @@ function handleStateApi(
                 exportXml: state?.exportXml || null,
                 exportOptions: state?.exportOptions || null,
                 exportId: state?.exportId ?? null,
+                selectionId: state?.selectionId ?? null,
+                historyKey: historyKeyOf(sessionId, state),
             }),
         )
     } else if (req.method === "POST") {
@@ -537,6 +821,14 @@ function handleStateApi(
                     return
                 }
 
+                // The tab is answering a selection request (get_selection)
+                if (data.selection !== undefined) {
+                    handleSelectionResult(sessionId, data)
+                    res.writeHead(200, { "Content-Type": "application/json" })
+                    res.end(JSON.stringify({ success: true }))
+                    return
+                }
+
                 // A push can come before the tab's first poll after a
                 // restart: recover the saved file first, so it is compared
                 // with that and never overwrites it unseen
@@ -568,7 +860,14 @@ function handleStateApi(
                             !!data.xml &&
                             data.xml !== current.xml
                         if (saved) {
-                            addHistory(sessionId, data.xml, data.svg || "")
+                            addHistory(
+                                sessionId,
+                                data.xml,
+                                data.svg || "",
+                                "recover",
+                            )
+                            // Saved with the History, as after any change
+                            stateListener?.(sessionId, current.xml)
                         }
                         res.writeHead(409, {
                             "Content-Type": "application/json",
@@ -603,8 +902,9 @@ function handleStateApi(
                     } else if (typeof data.xml === "string" && data.xml) {
                         // A user edit lost the race with an AI write. Keep
                         // it in history so the user can restore it.
-                        addHistory(sessionId, data.xml, data.svg || "")
+                        addHistory(sessionId, data.xml, data.svg || "", "user")
                         savedToHistory = true
+                        if (current) stateListener?.(sessionId, current.xml)
                     }
                     res.writeHead(409, { "Content-Type": "application/json" })
                     res.end(
@@ -626,7 +926,13 @@ function handleStateApi(
                 const saved = stateStore.get(sessionId)
                 if (saved && data.source !== "sync") saved.userEdited = true
                 res.writeHead(200, { "Content-Type": "application/json" })
-                res.end(JSON.stringify({ success: true, version }))
+                res.end(
+                    JSON.stringify({
+                        success: true,
+                        version,
+                        historyKey: historyKeyOf(sessionId, saved),
+                    }),
+                )
             } catch {
                 res.writeHead(400, { "Content-Type": "application/json" })
                 res.end(JSON.stringify({ error: "Invalid JSON" }))
@@ -656,7 +962,12 @@ function handleHistoryApi(
         return
     }
 
+    // The classic page reads index, id and svg; the shell's version cards
+    // the rest: the document, who made it, which earlier entry it is a copy
+    // of, the state the ids belong to, and the entry the canvas shows
     const history = getHistory(sessionId)
+    const firstIds = firstCopyIds(sessionId)
+    const state = stateStore.get(sessionId)
     res.writeHead(200, { "Content-Type": "application/json" })
     res.end(
         JSON.stringify({
@@ -664,12 +975,47 @@ function handleHistoryApi(
                 index: i,
                 id: entry.id,
                 svg: entry.svg,
+                xml: entry.xml,
+                source: entry.source ?? null,
+                firstId: firstIds.get(entry.id),
             })),
             count: history.length,
+            stateId: state?.stateId ?? null,
+            currentId: state ? currentEntryId(sessionId, state.xml) : null,
         }),
     )
 }
 
+/**
+ * Put a History entry back on the canvas (the preview page's Restore button
+ * and the restore_version tool). Returns the new version, or null when the
+ * entry is unknown.
+ */
+export function restoreHistoryEntry(
+    sessionId: string,
+    entryId: number,
+): number | null {
+    const entry = getHistoryEntry(sessionId, entryId)
+    if (!entry) return null
+
+    // Edits in the browser since the last entry are not in history
+    // yet: keep them, so the restore can be undone
+    // (any state besides a blank page; a cleared document with its
+    // own pages counts)
+    const current = stateStore.get(sessionId)
+    if (
+        current &&
+        contentFingerprint(current.xml) !== contentFingerprint(BLANK_MXFILE)
+    ) {
+        keepInHistory(sessionId, current.xml, current.svg)
+    }
+    const newVersion = setState(sessionId, entry.xml)
+    addHistory(sessionId, entry.xml, entry.svg, "restore")
+
+    log.info(`Restored session ${sessionId} to history entry ${entryId}`)
+    return newVersion
+}
+
 function handleRestoreApi(
     req: http.IncomingMessage,
     res: http.ServerResponse,
@@ -682,37 +1028,34 @@ function handleRestoreApi(
 
     readBody(req, res, (body) => {
         try {
-            const { sessionId, id } = JSON.parse(body)
+            const data = JSON.parse(body)
+            const { sessionId, id } = data
             if (!sessionId || typeof id !== "number") {
                 res.writeHead(400, { "Content-Type": "application/json" })
                 res.end(JSON.stringify({ error: "sessionId and id required" }))
                 return
             }
+            // Picked from the list of a state the server has since lost
+            // (a restart reloads History under new ids), or before the tab
+            // knew the state. A tab of an older version sends none.
+            const current = stateStore.get(sessionId)
+            if (
+                current &&
+                "stateId" in data &&
+                data.stateId !== current.stateId
+            ) {
+                res.writeHead(409, { "Content-Type": "application/json" })
+                res.end(JSON.stringify({ error: "Session was recreated" }))
+                return
+            }
 
-            const entry = getHistoryEntry(sessionId, id)
-            if (!entry) {
+            const newVersion = restoreHistoryEntry(sessionId, id)
+            if (newVersion === null) {
                 res.writeHead(404, { "Content-Type": "application/json" })
                 res.end(JSON.stringify({ error: "Entry not found" }))
                 return
             }
 
-            // Edits in the browser since the last entry are not in history
-            // yet: keep them, so the restore can be undone
-            // (any state besides a blank page; a cleared document with its
-            // own pages counts)
-            const current = stateStore.get(sessionId)
-            if (
-                current &&
-                contentFingerprint(current.xml) !==
-                    contentFingerprint(BLANK_MXFILE)
-            ) {
-                keepInHistory(sessionId, current.xml, current.svg)
-            }
-            const newVersion = setState(sessionId, entry.xml)
-            addHistory(sessionId, entry.xml, entry.svg)
-
-            log.info(`Restored session ${sessionId} to history entry ${id}`)
-
             res.writeHead(200, { "Content-Type": "application/json" })
             res.end(JSON.stringify({ success: true, newVersion }))
         } catch {
@@ -764,8 +1107,121 @@ function handleHistorySvgApi(
     })
 }
 
+// Pages may be framed only by this origin, and nothing is content-sniffed
+const HTML_SECURITY_HEADERS = {
+    "Content-Security-Policy": "frame-ancestors 'self'",
+    "X-Content-Type-Options": "nosniff",
+}
+
+const MIME_TYPES: Record<string, string> = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".ttf": "font/ttf",
+    ".txt": "text/plain; charset=utf-8",
+    ".xml": "text/xml; charset=utf-8",
+    ".json": "application/json",
+    ".ico": "image/x-icon",
+    ".wasm": "application/wasm",
+}
+
+/**
+ * GET /drawio/<path> or /shell/<path>: a file of the bundled draw.io copy or
+ * of the built shell. `stamp` names the files' version in their ETags.
+ */
+function serveStaticFile(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+    dir: string | null,
+    rawPath: string,
+    stamp: string,
+): void {
+    if (req.method !== "GET" && req.method !== "HEAD") {
+        res.writeHead(405)
+        res.end("Method Not Allowed")
+        return
+    }
+    let rel: string
+    try {
+        rel = decodeURIComponent(rawPath)
+    } catch {
+        res.writeHead(400)
+        res.end("Bad Request")
+        return
+    }
+    // One normalized path inside the directory; the war's server-side parts
+    // are never served, whatever was extracted
+    const normalized = posix.normalize(rel)
+    const file = dir ? resolve(dir, normalized) : null
+    if (
+        !dir ||
+        !file ||
+        /[\\\0]/.test(rel) ||
+        /(^|\/)(WEB-INF|META-INF)(\/|$)/i.test(normalized) ||
+        !file.startsWith(dir + sep)
+    ) {
+        res.writeHead(404)
+        res.end("Not Found")
+        return
+    }
+    let size: number
+    let etag: string
+    try {
+        const stat = statSync(file)
+        if (!stat.isFile()) throw new Error("not a file")
+        size = stat.size
+        etag = `"${stamp}-${size.toString(16)}-${Math.floor(stat.mtimeMs).toString(16)}"`
+    } catch {
+        res.writeHead(404)
+        res.end("Not Found")
+        return
+    }
+    // The file names do not change between draw.io versions, so the browser
+    // may keep a copy but asks before using it (a 304 from localhost is
+    // cheap); after a package upgrade the next preview gets the new files
+    const cacheHeaders = {
+        ETag: etag,
+        "Cache-Control": "no-cache",
+        "X-Content-Type-Options": "nosniff",
+    }
+    if (req.headers["if-none-match"] === etag) {
+        res.writeHead(304, cacheHeaders)
+        res.end()
+        return
+    }
+    const ext = extname(file).toLowerCase()
+    res.writeHead(200, {
+        ...cacheHeaders,
+        "Content-Type": MIME_TYPES[ext] || "application/octet-stream",
+        "Content-Length": size,
+        ...(ext === ".html" ? HTML_SECURITY_HEADERS : {}),
+    })
+    if (req.method === "HEAD") {
+        res.end()
+        return
+    }
+    // pipeline closes both ends when either fails or goes away (a tab closed
+    // mid-download), so no file handle leaks and no error goes unhandled; a
+    // client that left early is routine, not worth a log line
+    pipeline(createReadStream(file), res, () => {})
+}
+
+/** Where the iframe loads the editor from (without its query) */
+function drawioEditorUrl(): string {
+    return isSameOriginDrawio()
+        ? "/drawio/index.html"
+        : `${normalizeUrl(DRAWIO_BASE_URL)}/`
+}
+
 // The preview page lives in src/preview (the build copies it to dist/preview)
-const PREVIEW_DIR = join(dirname(fileURLToPath(import.meta.url)), "preview")
+const PREVIEW_DIR = join(HERE, "preview")
 let previewTemplate: string | null = null
 
 function loadPreviewTemplate(): string {
@@ -779,19 +1235,108 @@ function loadPreviewTemplate(): string {
     return previewTemplate
 }
 
-/** A JSON string literal that is safe inside a <script> element */
-const scriptJson = (value: string) =>
+/** JSON that is safe inside a <script> element ("<" escaped) */
+const scriptJson = (value: unknown) =>
     JSON.stringify(value).replace(/</g, "\\u003c")
 
+/**
+ * The editor settings the host config fixes: theme (DRAWIO_UI), language
+ * (DRAWIO_LANG) and dark mode (DRAWIO_DARK). ui and lang are "" unless set,
+ * because draw.io hides its Extras > Language / Theme submenu once they
+ * are given.
+ */
+function hostDrawioSettings(env: NodeJS.ProcessEnv): {
+    ui: string
+    lang: string
+    dark: "dark" | "light" | "auto"
+} {
+    const ui = (env.DRAWIO_UI ?? "").toLowerCase()
+    const dark = (env.DRAWIO_DARK ?? "").toLowerCase()
+    const lang = toDrawioLang(env.DRAWIO_LANG ?? "")
+    return {
+        ui: isDrawioTheme(ui) ? ui : "",
+        lang: /^[a-z]{2,3}(-[a-z]{2,4})?$/.test(lang) ? lang : "",
+        dark: ["1", "true", "dark"].includes(dark)
+            ? "dark"
+            : ["0", "false", "light"].includes(dark)
+              ? "light"
+              : // draw.io takes ui=dark as dark mode only when no dark
+                // parameter is present, and the pages always send one
+                !dark && ui === "dark"
+                ? "dark"
+                : "auto",
+    }
+}
+
+/**
+ * The configurable tail of the classic page's draw.io iframe query: dark
+ * mode, and the language and theme when the host config fixes them.
+ */
+export function drawioEmbedParams(
+    env: NodeJS.ProcessEnv = process.env,
+): string {
+    const settings = hostDrawioSettings(env)
+    const params = new URLSearchParams()
+    params.set(
+        "dark",
+        settings.dark === "auto"
+            ? "auto"
+            : settings.dark === "dark"
+              ? "1"
+              : "0",
+    )
+    if (settings.lang) params.set("lang", settings.lang)
+    if (settings.ui) params.set("ui", settings.ui)
+    return params.toString()
+}
+
+/**
+ * What the shell page gets as window.__MCP_CONFIG__ (shell/runtime-config.ts
+ * reads it): the session, the API token, where draw.io comes from and the
+ * host's editor settings.
+ */
+export function shellConfig(
+    sessionId: string,
+    env: NodeJS.ProcessEnv = process.env,
+): Record<string, string> {
+    const settings = hostDrawioSettings(env)
+    return {
+        sessionId,
+        token: API_TOKEN,
+        apiBase: "/api",
+        drawioBaseUrl: drawioEditorUrl(),
+        drawioUi: settings.ui,
+        drawioLang: settings.lang,
+        drawioDark: settings.dark,
+        lang: env.DRAWIO_LANG ?? "",
+    }
+}
+
+/** The shell page, or null when the shell is not built */
+function getShellPage(sessionId: string): string | null {
+    if (!shellDir) return null
+    const template = readFileSync(join(shellDir, "index.html"), "utf8")
+    return template.replace("{{CONFIG_JSON}}", () =>
+        scriptJson(shellConfig(sessionId)),
+    )
+}
+
 function getHtmlPage(sessionId: string): string {
-    return loadPreviewTemplate()
-        .replace("{{SESSION_BADGE}}", () =>
-            sessionId
-                ? `<span class="session">${sessionId.slice(-8)}</span>`
-                : "",
-        )
-        .replaceAll("{{DISABLED}}", sessionId ? "" : "disabled")
-        .replace("{{DRAWIO_URL}}", () => normalizeUrl(DRAWIO_BASE_URL))
-        .replace("{{SESSION_JSON}}", () => scriptJson(sessionId))
-        .replace("{{ORIGIN_JSON}}", () => scriptJson(DRAWIO_ORIGIN))
+    return (
+        loadPreviewTemplate()
+            .replace("{{SESSION_BADGE}}", () =>
+                sessionId
+                    ? `<span class="session">${sessionId.slice(-8)}</span>`
+                    : "",
+            )
+            .replaceAll("{{DISABLED}}", sessionId ? "" : "disabled")
+            .replace("{{DRAWIO_URL}}", () => drawioEditorUrl())
+            .replace("{{DRAWIO_PARAMS}}", () => drawioEmbedParams())
+            .replace("{{SESSION_JSON}}", () => scriptJson(sessionId))
+            // Same origin: the page fills in its own origin
+            .replace("{{ORIGIN_JSON}}", () =>
+                scriptJson(isSameOriginDrawio() ? "" : DRAWIO_ORIGIN),
+            )
+            .replace("{{TOKEN_JSON}}", () => scriptJson(API_TOKEN))
+    )
 }

packages/mcp-server/src/load-diagram.ts

@@ -18,7 +18,7 @@ import {
 import { getXmlSyntaxError } from "./xml-syntax.ts"
 
 export type LoadResult =
-    | { ok: true; xml: string }
+    | { ok: true; xml: string; hadCompressedPages: boolean }
     | { ok: false; error: string }
 
 /**
@@ -43,11 +43,27 @@ export function decompressPageContent(compressed: string): string | null {
     }
 }
 
+/**
+ * Read the diagram XML a .drawio.svg (Editable SVG) carries in its root
+ * element's content attribute. Returns undefined when the text is not an
+ * SVG, and "" when the SVG has no embedded diagram.
+ *
+ * Uses getAttributeNode().value rather than getAttribute(): linkedom's
+ * getAttribute re-escapes <, > and & in XML documents, which would turn
+ * the embedded "<mxfile" into "&lt;mxfile".
+ */
+export function extractSvgEmbeddedXml(text: string): string | undefined {
+    const doc = new DOMParser().parseFromString(text, "text/xml")
+    const root = doc.documentElement
+    if (root?.tagName !== "svg") return undefined
+    return (root.getAttributeNode("content")?.value ?? "").trim()
+}
+
 /**
  * Parse the content of a .drawio file into the canonical session shape:
  * an <mxfile> whose every page holds plain <mxGraphModel> XML. Accepts a
- * bare <mxGraphModel> (wrapped into a one-page mxfile) and decompresses
- * any compressed pages.
+ * bare <mxGraphModel> (wrapped into a one-page mxfile), a .drawio.svg with
+ * the diagram embedded, and decompresses any compressed pages.
  */
 export function parseDrawioFileContent(content: string): LoadResult {
     let trimmed = content.trim()
@@ -62,9 +78,25 @@ export function parseDrawioFileContent(content: string): LoadResult {
         trimmed = normalized
     }
     if (!isMxFile(trimmed)) {
+        const embedded = extractSvgEmbeddedXml(trimmed)
+        if (embedded === undefined) {
+            return {
+                ok: false,
+                error: "Not a draw.io file: expected an <mxfile> or <mxGraphModel> root element, or a .drawio.svg with the diagram embedded.",
+            }
+        }
+        if (!embedded) {
+            return {
+                ok: false,
+                error: "This SVG has no embedded diagram. Only .drawio.svg (Editable SVG) files can be loaded; ask for the .drawio file or redraw from the image.",
+            }
+        }
+        if (isMxFile(embedded) || isMxGraphModel(embedded)) {
+            return parseDrawioFileContent(embedded)
+        }
         return {
             ok: false,
-            error: "Not a draw.io file: expected an <mxfile> or <mxGraphModel> root element.",
+            error: "The SVG's embedded content is not draw.io XML.",
         }
     }
     const doc = parseMxfile(trimmed)
@@ -101,5 +133,9 @@ export function parseDrawioFileContent(content: string): LoadResult {
         decompressedAny = true
     }
     // Nothing changed — keep the file's own serialisation.
-    return { ok: true, xml: decompressedAny ? serializeMxfile(doc) : trimmed }
+    return {
+        ok: true,
+        xml: decompressedAny ? serializeMxfile(doc) : trimmed,
+        hadCompressedPages: decompressedAny,
+    }
 }

packages/mcp-server/src/new-diagram.ts

@@ -3,7 +3,14 @@
  * and the web app's display_diagram tool.
  */
 import { expandCompactCells } from "./compact-cells.ts"
-import { hasCells, normalizeToMxfile, wrapCellsInModel } from "./pages.ts"
+import {
+    generatePageId,
+    hasCells,
+    normalizeToMxfile,
+    parseMxfile,
+    serializeMxfile,
+    wrapCellsInModel,
+} from "./pages.ts"
 import {
     addDefaultStyles,
     applyStyleClasses,
@@ -12,7 +19,7 @@ import {
 } from "./style-classes.ts"
 import { readAttributes } from "./xml-attributes.ts"
 import { getXmlSyntaxError } from "./xml-syntax.ts"
-import { validateAndFixXml } from "./xml-validation.ts"
+import { repairQuoteBeforeSlash, validateAndFixXml } from "./xml-validation.ts"
 
 export type NewDiagram =
     | { ok: true; xml: string; fixes: string[] }
@@ -53,6 +60,74 @@ export function reservedIdError(input: string): string | null {
     return null
 }
 
+/**
+ * Check if mxCell XML output is complete (not truncated).
+ * Complete XML ends with a self-closing tag (/>) or closing mxCell tag.
+ * Uses a robust approach that handles any LLM provider's wrapper tags
+ * by finding the last valid mxCell ending and checking if suffix is just closing tags.
+ * @param xml - The XML string to check (can be undefined/null)
+ * @returns true if XML appears complete, false if truncated or empty
+ */
+export function isMxCellXmlComplete(xml: string | undefined | null): boolean {
+    // Named style definitions before the cells are not cells: output cut off
+    // right after them is incomplete. A compact cell whose last quote is
+    // missing is complete; prepareNewDiagram repairs it.
+    const trimmed = repairQuoteBeforeSlash(
+        readStyleClasses(xml || "").xml,
+    ).trim()
+    if (!trimmed) return false
+
+    // Find position of last complete mxCell ending (either /> or </mxCell>)
+    const lastSelfClose = trimmed.lastIndexOf("/>")
+    const lastMxCellClose = trimmed.lastIndexOf("</mxCell>")
+
+    const lastValidEnd = Math.max(lastSelfClose, lastMxCellClose)
+
+    // No valid ending found at all
+    if (lastValidEnd === -1) return false
+
+    // If the last mxCell has no </mxCell> after it, it must be self-closing.
+    // Otherwise the trailing "/>" belongs to a child such as <mxGeometry .../>
+    // and the output was cut off before the cell was closed.
+    const lastCellStart = trimmed.lastIndexOf("<mxCell")
+    if (
+        lastCellStart > lastMxCellClose &&
+        // (quoted values may hold a raw "<", which the auto-fix escapes)
+        !/^<mxCell\b(?:[^<>"']|"[^"]*"|'[^']*')*\/>/.test(
+            trimmed.slice(lastCellStart),
+        )
+    ) {
+        return false
+    }
+
+    // Check what comes after the last valid ending
+    // For />: add 2 chars, for </mxCell>: add 9 chars
+    const endOffset = lastMxCellClose > lastSelfClose ? 9 : 2
+    const suffix = trimmed.slice(lastValidEnd + endOffset)
+
+    // If suffix is empty or only contains closing tags (any provider's wrapper) or whitespace, it's complete
+    // This regex matches any sequence of closing XML tags like </foo>, </bar>, </｜DSML｜xyz>
+    return /^(\s*<\/[^>]+>)*\s*$/.test(suffix)
+}
+
+/**
+ * Output that stops inside an mxCell would be wrapped and rejected with an
+ * error about wrapper tags the model never sent. Bare cells only. Returns the
+ * error for the model, or null.
+ */
+export function truncatedCellError(input: string): string | null {
+    if (/<(mxGraphModel|mxfile)\b/.test(input)) return null
+    // Comments, and closing tags such as </mxCell/> that the auto-fix
+    // repairs, are no cut
+    const stripped = input
+        .replace(/<!--[\s\S]*?-->/g, "")
+        .replace(/<\/([a-zA-Z][a-zA-Z0-9]*)\s*\/>/g, "</$1>")
+    // No cell at all: the validator's message fits better
+    if (!/<mxCell\b/.test(stripped) || isMxCellXmlComplete(stripped))
+        return null
+    return `The XML ends inside an unfinished mxCell, so the output was probably cut off. Nothing was drawn. It ended with:\n${input.slice(-300)}\nResend the complete diagram, or send the first cells now and add the remaining cells with edit_diagram add operations.`
+}
+
 /**
  * The named style definitions are taken out first (style-classes.ts). Bare
  * cells then get the wrapper and root cells, since the strict parser rejects
@@ -96,6 +171,8 @@ export function prepareNewDiagram(
     if (styleError) return { ok: false, error: styleError }
     const reserved = reservedIdError(cells)
     if (reserved) return { ok: false, error: reserved }
+    const truncated = truncatedCellError(cells)
+    if (truncated) return { ok: false, error: truncated }
     let xml = wrapCellsInModel(cells)
     const { valid, error, fixed, fixes } = validateAndFixXml(xml)
     if (fixed) xml = fixed
@@ -112,12 +189,26 @@ export function prepareNewDiagram(
             error: `XML validation failed after expanding the cells - ${rewriteError}`,
         }
     }
-    const normalized = normalizeToMxfile(xml, page)
+    let normalized = normalizeToMxfile(xml, page)
     if (!normalized) {
         return {
             ok: false,
             error: "XML must be the mxCell elements of one page, a <mxGraphModel>, or an <mxfile> with one or more <diagram> children.",
         }
     }
+    // A <diagram> the model sent without an id gets one here. draw.io would
+    // otherwise make its own, which the server never sees, and get_selection
+    // would then name a page edit_diagram cannot find
+    const doc = parseMxfile(normalized)
+    if (doc) {
+        let added = false
+        doc.querySelectorAll("diagram").forEach((d) => {
+            if (!d.getAttribute("id")) {
+                d.setAttribute("id", generatePageId())
+                added = true
+            }
+        })
+        if (added) normalized = serializeMxfile(doc)
+    }
     return { ok: true, xml: normalized, fixes }
 }

packages/mcp-server/src/persistence.ts

@@ -3,7 +3,9 @@
  * diagram survives the MCP process (hosts start a new one when a
  * conversation is resumed). Like the web app's IndexedDB sessions
  * (lib/session-storage.ts): saved 1 second after the last change, at most
- * 50 kept. History is not saved.
+ * 50 kept. The session's History (the XML of its last 20 versions and who
+ * made each, without the thumbnails) is saved next to it as
+ * <session-id>.history.json.
  */
 
 import {
@@ -12,6 +14,7 @@ import {
     readdirSync,
     readFileSync,
     renameSync,
+    rmSync,
     statSync,
     unlinkSync,
     writeFileSync,
@@ -19,6 +22,7 @@ import {
 import { homedir } from "node:os"
 import { join } from "node:path"
 import { contentFingerprint } from "./edit-gate.ts"
+import type { HistorySource } from "./history.ts"
 import { log } from "./logger.ts"
 import { BLANK_MXFILE, hasCells } from "./pages.ts"
 
@@ -31,6 +35,16 @@ const isBlank = (xml: string) =>
 const DELAY_MS = 1000
 const MAX_FILES = 50
 
+/** A History entry as the file keeps it */
+export interface SavedHistoryEntry {
+    xml: string
+    source?: HistorySource
+}
+
+const SOURCES: readonly string[] = ["user", "recover", "restore"]
+const isSource = (v: unknown): v is HistorySource =>
+    typeof v === "string" && SOURCES.includes(v)
+
 /** Expand a leading ~ to the home directory (shells do this, MCP hosts don't). */
 export function expandHome(p: string): string {
     if (p === "~") return homedir()
@@ -65,6 +79,10 @@ export class Autosaver {
         private dir: string | null,
         private delayMs = DELAY_MS,
         private maxFiles = MAX_FILES,
+        // The session's History entries, saved next to its diagram
+        private history: (
+            sessionId: string,
+        ) => { id: number; xml: string; source?: HistorySource }[] = () => [],
     ) {}
 
     /** Path of a session's file, or null when saving is off. */
@@ -72,6 +90,72 @@ export class Autosaver {
         return this.dir ? join(this.dir, `${sessionId}.drawio`) : null
     }
 
+    /** Path of a session's History file, or null when saving is off. */
+    historyPathFor(sessionId: string): string | null {
+        return this.dir ? join(this.dir, `${sessionId}.history.json`) : null
+    }
+
+    /** The session's saved History entries, oldest first. */
+    loadHistory(sessionId: string): SavedHistoryEntry[] {
+        const path = this.historyPathFor(sessionId)
+        if (!path) return []
+        try {
+            const entries: unknown = JSON.parse(readFileSync(path, "utf-8"))
+            if (!Array.isArray(entries)) return []
+            const result: SavedHistoryEntry[] = []
+            for (const e of entries) {
+                // Files of earlier versions hold the XML strings alone
+                if (typeof e === "string") {
+                    result.push({ xml: e })
+                } else if (e && typeof e.xml === "string") {
+                    result.push({
+                        xml: e.xml,
+                        ...(isSource(e.source) && { source: e.source }),
+                    })
+                } else {
+                    return []
+                }
+            }
+            return result
+        } catch (error) {
+            if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+                log.warn(`Could not read the saved History ${path}: ${error}`)
+            }
+            return []
+        }
+    }
+
+    /** The folder the files are saved in, or null when saving is off. */
+    dataDir(): string | null {
+        return this.dir
+    }
+
+    /**
+     * Every file a session can resume (start_session's own files and
+     * hand-named ones such as mcp-notes.drawio), newest first. Empty when
+     * saving is off or the folder does not exist yet.
+     */
+    list(): { sessionId: string; path: string; savedAt: Date }[] {
+        return this.files(/^mcp-[a-z0-9-]{1,64}\.drawio$/).map((file) => ({
+            sessionId: file.name.slice(0, -".drawio".length),
+            path: file.path,
+            savedAt: file.mtime,
+        }))
+    }
+
+    /** The files in the folder whose name matches, newest first */
+    private files(pattern: RegExp) {
+        const dir = this.dir
+        if (!dir || !existsSync(dir)) return []
+        return readdirSync(dir)
+            .filter((name) => pattern.test(name))
+            .map((name) => {
+                const path = join(dir, name)
+                return { name, path, mtime: statSync(path).mtime }
+            })
+            .sort((a, b) => b.mtime.getTime() - a.mtime.getTime())
+    }
+
     // Saved files that could not be read back: never written over, since
     // the session then shows something else than what they hold. Cleared
     // once the file is read, or is surely gone (a folder without permission
@@ -132,30 +216,66 @@ export class Autosaver {
         }
         try {
             const isNew = !existsSync(path)
-            // A blank page the browser shows before any drawing: nothing to keep
-            if (isNew && isBlank(entry.xml)) return
+            // A blank page the browser shows before any drawing: nothing to
+            // keep (unless the diagram was cleared before its first save)
+            if (
+                isNew &&
+                isBlank(entry.xml) &&
+                this.history(sessionId).every((e) => isBlank(e.xml))
+            )
+                return
             mkdirSync(this.dir, { recursive: true })
             // Write to a temporary file first so a crash never leaves half a file
             writeFileSync(`${path}.tmp`, entry.xml, "utf-8")
             renameSync(`${path}.tmp`, path)
+            this.writeHistory(sessionId)
             if (isNew) this.removeOldest()
         } catch (error) {
             log.warn(`Auto-save failed for ${path}: ${error}`)
         }
     }
 
+    // What each session's History file holds (entry count and last id):
+    // draw.io autosaves often, and the file is only rewritten when the
+    // entries changed
+    private historyKeys = new Map<string, string>()
+
+    // Saved with the diagram, after the same delay, so the History entry
+    // that follows every tool write is included. The thumbnails are left
+    // out (large); the History grid shows the entry's number instead. Who
+    // made an entry goes with it: the shell's cards tell a clear of the
+    // canvas from a restore of one by it.
+    private writeHistory(sessionId: string): void {
+        const path = this.historyPathFor(sessionId)
+        const entries = this.history(sessionId)
+        if (!path || entries.length === 0) return
+        const key = `${entries.length}:${entries[entries.length - 1].id}`
+        if (this.historyKeys.get(sessionId) === key) return
+        try {
+            const saved: SavedHistoryEntry[] = entries.map((e) => ({
+                xml: e.xml,
+                ...(e.source && { source: e.source }),
+            }))
+            const json = JSON.stringify(saved)
+            writeFileSync(`${path}.tmp`, json, "utf-8")
+            renameSync(`${path}.tmp`, path)
+            this.historyKeys.set(sessionId, key)
+        } catch (error) {
+            log.warn(`Saving the History failed for ${path}: ${error}`)
+        }
+    }
+
     private removeOldest(): void {
-        if (!this.dir) return
-        const dir = this.dir
         // Only our own session files (mcp-<time in base 36>-<random>, made
         // by start_session): DRAWIO_DATA_DIR may be a folder that also holds
         // the user's diagrams
-        const files = readdirSync(dir)
-            .filter((f) => /^mcp-[0-9a-z]{8}-[0-9a-z]{1,6}\.drawio$/.test(f))
-            .map((f) => ({ f, mtime: statSync(join(dir, f)).mtimeMs }))
-            .sort((a, b) => b.mtime - a.mtime)
-        for (const { f } of files.slice(this.maxFiles)) {
-            unlinkSync(join(dir, f))
+        const own = this.files(/^mcp-[0-9a-z]{8}-[0-9a-z]{1,6}\.drawio$/)
+        for (const { name, path } of own.slice(this.maxFiles)) {
+            unlinkSync(path)
+            // Its History goes with it (there may be none), and is written
+            // again if the session saves once more
+            rmSync(path.replace(/\.drawio$/, ".history.json"), { force: true })
+            this.historyKeys.delete(name.slice(0, -".drawio".length))
         }
     }
 }

packages/mcp-server/src/preview/index.html

@@ -40,7 +40,7 @@
                 </button>
             </div>
         </div>
-        <iframe id="drawio" src="{{DRAWIO_URL}}/?embed=1&proto=json&spin=1&libraries=1&noSaveBtn=1&noExitBtn=1&saveAndExit=0&themes=1&dark=auto" title="draw.io editor"></iframe>
+        <iframe id="drawio" src="{{DRAWIO_URL}}?embed=1&proto=json&spin=1&libraries=1&noSaveBtn=1&noExitBtn=1&saveAndExit=0&themes=1&{{DRAWIO_PARAMS}}" title="draw.io editor"></iframe>
     </div>
     <div id="notice" role="status"></div>
     <div id="history-modal">
@@ -85,7 +85,9 @@
     </div>
     <script>
         const sessionId = {{SESSION_JSON}};
-        const DRAWIO_ORIGIN = {{ORIGIN_JSON}};
+        // Empty when draw.io is served from this origin
+        const DRAWIO_ORIGIN = {{ORIGIN_JSON}} || location.origin;
+        let API_TOKEN = {{TOKEN_JSON}};
     </script>
     <script>
 {{SCRIPT}}

packages/mcp-server/src/preview/preview.js

@@ -1,4 +1,25 @@
 const iframe = document.getElementById('drawio');
+// Every API request carries the token the server wrote into this page. A 403
+// means another MCP process (with its own token) now answers on this port:
+// read its token from a fresh copy of this page and retry once, so the next
+// poll can recover the session instead of being refused forever.
+let tokenRefresh = null;
+function refreshToken() {
+    if (!tokenRefresh) {
+        tokenRefresh = fetch(location.href, { cache: 'no-store' })
+            .then((r) => r.text())
+            .then((html) => { const m = html.match(/API_TOKEN = "([0-9a-f]+)"/); if (m) API_TOKEN = m[1]; })
+            .catch(() => {})
+            .finally(() => { tokenRefresh = null; });
+    }
+    return tokenRefresh;
+}
+async function api(url, init = {}) {
+    const send = () => fetch(url, { ...init, headers: { ...(init.headers || {}), 'X-Drawio-Token': API_TOKEN } });
+    let r = await send();
+    if (r.status === 403) { await refreshToken(); r = await send(); }
+    return r;
+}
 let currentVersion = 0, isReady = false, pendingXml = null, lastXml = null;
 // The server state this tab is in step with (see stateId in http-server.ts);
 // null until the first poll
@@ -82,7 +103,7 @@ window.addEventListener('message', (e) => {
                     // result: a poll answered before that still sees the
                     // request and would start the same export again.
                     const seq = msg.message.mcpExport;
-                    fetch('/api/state', {
+                    api('/api/state', {
                         method: 'POST',
                         headers: { 'Content-Type': 'application/json' },
                         body: JSON.stringify({ sessionId, exportData: d, exportId: mcpExportId })
@@ -126,7 +147,7 @@ window.addEventListener('message', (e) => {
                 const t = thumbExport;
                 if (!t || msg.message.thumbExport !== t.n || latestXml !== t.xml) return;
                 thumbExport = null;
-                fetch('/api/history-svg', {
+                api('/api/history-svg', {
                     method: 'POST',
                     headers: { 'Content-Type': 'application/json' },
                     body: JSON.stringify({ sessionId, svg, stateId: t.stateId, version: t.version })
@@ -184,7 +205,7 @@ async function pushState(xml, svg = '', baseVersion = currentVersion, source = '
     if (!sessionId) return;
     pushesInFlight.push(xml);
     try {
-        const r = await fetch('/api/state', {
+        const r = await api('/api/state', {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({ sessionId, xml, svg, baseVersion, source, stateId: sid })
@@ -237,6 +258,8 @@ async function pushState(xml, svg = '', baseVersion = currentVersion, source = '
 // process restarted. Decide whose diagram wins.
 function recoverState(s) {
     stateId = s.stateId;
+    // History entries got new ids with the new state: an open list is stale
+    if (historyModal.classList.contains('open')) cancelBtn.onclick();
     // The old state's pending work is gone with it
     const projectionShown = projectionExportActive;
     projectionExportActive = false;
@@ -280,7 +303,7 @@ async function poll() {
     if (!sessionId) return;
     const seq = ++pollSeq;
     try {
-        const r = await fetch('/api/state?sessionId=' + encodeURIComponent(sessionId));
+        const r = await api('/api/state?sessionId=' + encodeURIComponent(sessionId));
         if (!r.ok) return;
         const s = await r.json();
         // An older answer than one already handled (the interval, the 409
@@ -298,11 +321,13 @@ async function poll() {
         // The tab's own push still on its way is not loaded back: the
         // canvas may have moved on since (an undo), and its answer follows
         const ownPush = pushesInFlight.includes(s.xml);
+        let justLoaded = false; // this poll put a new version on the canvas
         if ((forceReload || (s.version > currentVersion && !projectionExportActive && !ownPush)) && s.xml) {
             forceReload = false;
             projectionExportActive = false;
             currentVersion = s.version;
             loadDiagram(s.xml, true);
+            justLoaded = true;
         }
         // Handle sync request - server needs fresh state. After the load
         // above, so draw.io exports what it just loaded; never while a
@@ -352,6 +377,10 @@ async function poll() {
                 // Let draw.io render the loaded page before exporting
                 // (same proven settle delay as the AI-preview path).
                 setTimeout(fireExport, 600);
+            } else if (justLoaded) {
+                // A write with a screenshot: give the new diagram's external
+                // icon images a moment to load before the PNG is taken
+                setTimeout(fireExport, 600);
             } else {
                 fireExport();
             }
@@ -453,18 +482,24 @@ const historyGrid = document.getElementById('history-grid');
 const historyEmpty = document.getElementById('history-empty');
 const restoreBtn = document.getElementById('restore-btn');
 const cancelBtn = document.getElementById('cancel-btn');
-let historyData = [], selectedId = null;
+// historyStateId: the server state the list belongs to, sent with a restore
+let historyData = [], historyStateId = null, selectedId = null;
 
 historyBtn.onclick = async () => {
     if (!sessionId) return;
+    // A list for a state the server recreated meanwhile has old ids
+    const sid = stateId;
     try {
-        const r = await fetch('/api/history?sessionId=' + encodeURIComponent(sessionId));
+        const r = await api('/api/history?sessionId=' + encodeURIComponent(sessionId));
         if (r.ok) {
             const d = await r.json();
+            if (sid !== stateId) return;
             historyData = d.entries || [];
+            historyStateId = sid;
             renderHistory();
         }
     } catch {}
+    if (sid !== stateId) return;
     historyModal.classList.add('open');
 };
 
@@ -515,12 +550,13 @@ restoreBtn.onclick = async () => {
     restoreBtn.disabled = true;
     restoreBtn.textContent = 'Restoring...';
     try {
-        const r = await fetch('/api/restore', {
+        const r = await api('/api/restore', {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ sessionId, id: selectedId })
+            body: JSON.stringify({ sessionId, id: selectedId, stateId: historyStateId })
         });
         if (r.ok) { cancelBtn.onclick(); await poll(); }
+        else if (r.status === 409) { cancelBtn.onclick(); showNotice('History changed on the server. Please open it again.'); }
         else { showNotice('Restore failed. Please try again.'); }
     } catch { showNotice('Restore failed. Please try again.'); }
     restoreBtn.textContent = 'Restore';

packages/mcp-server/src/selection.ts

@@ -0,0 +1,124 @@
+/**
+ * The cells the user has selected in the preview, as the page reads them
+ * from the editor (shell/use-mcp-sync.ts) and the get_selection tool
+ * reports them. The shape is shared with the shell; only plain data, so the
+ * server can take it from a POST as it is.
+ */
+
+export interface SelectedCellInfo {
+    id: string
+    /** The label as text, HTML removed and long ones cut */
+    label: string
+    edge: boolean
+    source?: string
+    target?: string
+    /** The cell's geometry as the XML has it (relative to its parent) */
+    geometry?: { x: number; y: number; width: number; height: number }
+    /** The container the cell is in, when it is not on the layer itself */
+    parent?: string
+}
+
+export interface SelectionAnswer {
+    /** The page on screen */
+    pageId: string | null
+    pageName: string | null
+    cells: SelectedCellInfo[]
+    /** The page cannot reach the editor (an external draw.io) */
+    unavailable?: boolean
+}
+
+/** A POST body's selection, if it has the shape above; else null */
+export function parseSelectionAnswer(value: unknown): SelectionAnswer | null {
+    if (!value || typeof value !== "object") return null
+    const given = value as Record<string, unknown>
+    if (given.unavailable === true) {
+        return { pageId: null, pageName: null, cells: [], unavailable: true }
+    }
+    if (!Array.isArray(given.cells)) return null
+    const text = (v: unknown) => (typeof v === "string" ? v : null)
+    const cells: SelectedCellInfo[] = []
+    for (const raw of given.cells) {
+        if (!raw || typeof raw !== "object") continue
+        const c = raw as Record<string, unknown>
+        if (typeof c.id !== "string" || !c.id) continue
+        const cell: SelectedCellInfo = {
+            id: c.id,
+            label: text(c.label) ?? "",
+            edge: c.edge === true,
+        }
+        if (text(c.source)) cell.source = c.source as string
+        if (text(c.target)) cell.target = c.target as string
+        if (text(c.parent)) cell.parent = c.parent as string
+        const g = c.geometry as Record<string, unknown> | undefined
+        if (
+            g &&
+            typeof g === "object" &&
+            [g.x, g.y, g.width, g.height].every(
+                (n) => typeof n === "number" && Number.isFinite(n),
+            )
+        ) {
+            cell.geometry = {
+                x: g.x as number,
+                y: g.y as number,
+                width: g.width as number,
+                height: g.height as number,
+            }
+        }
+        cells.push(cell)
+    }
+    return { pageId: text(given.pageId), pageName: text(given.pageName), cells }
+}
+
+/** describeSelection details at most this many cells; the rest by id only */
+export const MAX_LISTED_CELLS = 100
+
+/**
+ * The get_selection result text. `externalDrawio` names the draw.io origin
+ * when the preview loads it from another origin, where the page cannot
+ * read the editor. A selection of a whole large diagram would fill the
+ * model's context with labels and geometry: the first cells get them, the
+ * rest are listed by id alone (an edit on the selection needs every id).
+ */
+export function describeSelection(
+    answer: SelectionAnswer,
+    externalDrawio: string | null,
+): string {
+    if (answer.unavailable) {
+        return externalDrawio
+            ? `The preview loads draw.io from ${externalDrawio} (another origin), where the selection cannot be read. Ask the user which shapes they mean, or call get_diagram.`
+            : "The preview could not read the editor's selection. Ask the user which shapes they mean, or call get_diagram."
+    }
+    const page = answer.pageName
+        ? `page "${answer.pageName}"${answer.pageId ? ` (page_id="${answer.pageId}")` : ""}`
+        : "the page on screen"
+    if (answer.cells.length === 0) {
+        return `Nothing is selected on ${page}. Ask the user to select the shapes they mean in the preview, or call get_diagram.`
+    }
+    const listed = answer.cells.slice(0, MAX_LISTED_CELLS)
+    const lines = listed.map((cell) => {
+        const label = cell.label ? `"${cell.label}"` : "(no label)"
+        if (cell.edge) {
+            const ends =
+                cell.source || cell.target
+                    ? ` from ${cell.source ? `"${cell.source}"` : "nothing"} to ${cell.target ? `"${cell.target}"` : "nothing"}`
+                    : " (not connected)"
+            return `- id="${cell.id}" edge ${label}${ends}`
+        }
+        const g = cell.geometry
+        const where = g
+            ? ` at x=${g.x} y=${g.y} w=${g.width} h=${g.height}`
+            : ""
+        const parent = cell.parent ? ` inside "${cell.parent}"` : ""
+        return `- id="${cell.id}" shape ${label}${where}${parent}`
+    })
+    const rest = answer.cells.slice(MAX_LISTED_CELLS)
+    if (rest.length > 0) {
+        lines.push(
+            `- and ${rest.length} more cells, listed by id only: ${rest.map((c) => `"${c.id}"`).join(", ")}`,
+        )
+    }
+    const count =
+        answer.cells.length === 1 ? "1 cell" : `${answer.cells.length} cells`
+    const target = answer.pageId ? ` (page_id="${answer.pageId}")` : ""
+    return `${count} selected on ${page}:\n${lines.join("\n")}\n\nUse these ids with edit_diagram${target}; call get_diagram for their full XML.`
+}

packages/mcp-server/src/xml-reference.ts

@@ -0,0 +1,71 @@
+/**
+ * Short XML references returned by get_drawing_guide with a topic. Each
+ * snippet is the bare mxCell elements of one page, as create_new_diagram
+ * accepts them, and is checked by tests/xml-reference.test.ts.
+ */
+
+import { indent } from "./xml-examples.ts"
+
+const TABLE_ROW_STYLE =
+    "shape=tableRow;horizontal=0;startSize=0;swimlaneHead=0;swimlaneBody=0;strokeColor=inherit;top=0;left=0;bottom=0;right=0;collapsible=0;dropTarget=0;fillColor=none;points=[[0,0.5],[1,0.5]];portConstraint=eastwest;"
+
+const TABLE_CELL_STYLE =
+    "shape=partialRectangle;html=1;whiteSpace=wrap;connectable=0;strokeColor=inherit;overflow=hidden;fillColor=none;top=0;left=0;bottom=0;right=0;pointerEvents=1;"
+
+const TABLES_EXAMPLE = `<mxCell id="table1" style="shape=table;startSize=0;container=1;collapsible=0;childLayout=tableLayout;" vertex="1" parent="1">
+  <mxGeometry x="40" y="40" width="240" height="80" as="geometry"/>
+</mxCell>
+<mxCell id="row1" style="${TABLE_ROW_STYLE}" vertex="1" parent="table1">
+  <mxGeometry y="0" width="240" height="40" as="geometry"/>
+</mxCell>
+<mxCell id="cell11" value="Name" style="${TABLE_CELL_STYLE}fontStyle=1;" vertex="1" parent="row1">
+  <mxGeometry x="0" y="0" width="120" height="40" as="geometry"/>
+</mxCell>
+<mxCell id="cell12" value="Role" style="${TABLE_CELL_STYLE}fontStyle=1;" vertex="1" parent="row1">
+  <mxGeometry x="120" y="0" width="120" height="40" as="geometry"/>
+</mxCell>
+<mxCell id="row2" style="${TABLE_ROW_STYLE}" vertex="1" parent="table1">
+  <mxGeometry y="40" width="240" height="40" as="geometry"/>
+</mxCell>
+<mxCell id="cell21" value="Alice" style="${TABLE_CELL_STYLE}" vertex="1" parent="row2">
+  <mxGeometry x="0" y="0" width="120" height="40" as="geometry"/>
+</mxCell>
+<mxCell id="cell22" value="Admin" style="${TABLE_CELL_STYLE}" vertex="1" parent="row2">
+  <mxGeometry x="120" y="0" width="120" height="40" as="geometry"/>
+</mxCell>`
+
+const LAYERS_EXAMPLE = `<mxCell id="L2" value="Layer 2" parent="0"/>
+<mxCell id="2" value="On the default layer" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+  <mxGeometry x="40" y="40" width="120" height="60" as="geometry"/>
+</mxCell>
+<mxCell id="3" value="On Layer 2" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="L2">
+  <mxGeometry x="200" y="40" width="120" height="60" as="geometry"/>
+</mxCell>`
+
+const GROUPS_EXAMPLE = `<mxCell id="group1" style="group" vertex="1" connectable="0" parent="1">
+  <mxGeometry x="40" y="40" width="260" height="60" as="geometry"/>
+</mxCell>
+<mxCell id="2" value="A" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="group1">
+  <mxGeometry x="0" y="0" width="120" height="60" as="geometry"/>
+</mxCell>
+<mxCell id="3" value="B" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="group1">
+  <mxGeometry x="140" y="0" width="120" height="60" as="geometry"/>
+</mxCell>`
+
+export const XML_REFERENCE: Record<"tables" | "layers" | "groups", string> = {
+    tables: `## Tables
+A table is three levels of cells, as draw.io's sidebar inserts them: the table container (style "shape=table;startSize=0;container=1;collapsible=0;childLayout=tableLayout;", parent="1", geometry wide enough for all columns), one row per table row (style as below, parent = table id, width = table width, height = row height, y = row offset), and one cell per column inside each row (style as below, parent = row id, x = column offset, y = 0, width = column width, height = row height; the cell text is the value). A header row can use fontStyle=1 on its cells. Example with 2 rows and 2 columns:
+
+${indent(TABLES_EXAMPLE)}
+`,
+    layers: `## Layers
+A layer is the one case of a cell with parent="0" and no vertex or edge attribute; id="1" is the default layer. Add a layer cell and give shapes parent="<layer id>" to put them on it:
+
+${indent(LAYERS_EXAMPLE)}
+`,
+    groups: `## Groups
+A group is a container with style="group" (parent="1", geometry enclosing its children). Children use parent="<group id>" and coordinates relative to the group; moving the group moves them:
+
+${indent(GROUPS_EXAMPLE)}
+`,
+}

packages/mcp-server/tests/custom-instructions.test.ts

@@ -0,0 +1,99 @@
+/**
+ * Tests for the user's instructions.md appended to the drawing guide
+ * (src/custom-instructions.ts).
+ */
+
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs"
+import { homedir, tmpdir } from "node:os"
+import { join } from "node:path"
+import { afterEach, describe, expect, it } from "vitest"
+import {
+    CUSTOM_INSTRUCTIONS_FILE,
+    customInstructionsDir,
+    guideWithCustomInstructions,
+    readCustomInstructions,
+} from "../src/custom-instructions.ts"
+import { DRAWING_GUIDE } from "../src/drawing-guide.ts"
+
+const GUIDE = "# Drawing guide\n\nKeep edges orthogonal."
+const tempDir = () => mkdtempSync(join(tmpdir(), "mcp-instructions-"))
+const writeRules = (dir: string, text: string) =>
+    writeFileSync(join(dir, CUSTOM_INSTRUCTIONS_FILE), text)
+
+describe("readCustomInstructions", () => {
+    it("gives an empty string when there is no file", () => {
+        const dir = tempDir()
+        expect(readCustomInstructions(dir)).toBe("")
+        expect(guideWithCustomInstructions(GUIDE, dir)).toBe(GUIDE)
+    })
+
+    it("appends the file's content under its own heading", () => {
+        const dir = tempDir()
+        writeRules(dir, "\nAlways draw in minimal style.\n\n")
+        expect(readCustomInstructions(dir)).toBe(
+            "Always draw in minimal style.",
+        )
+        expect(guideWithCustomInstructions(GUIDE, dir)).toBe(
+            `${GUIDE}\n\n## Custom Instructions\nAlways draw in minimal style.`,
+        )
+    })
+
+    it("cuts the content at 5000 characters", () => {
+        const dir = tempDir()
+        writeRules(dir, "x".repeat(6000))
+        expect(readCustomInstructions(dir)).toBe("x".repeat(5000))
+    })
+
+    it("gives an empty string when the file cannot be read", () => {
+        const dir = tempDir()
+        // A folder in place of the file: readFileSync fails with EISDIR
+        mkdirSync(join(dir, CUSTOM_INSTRUCTIONS_FILE))
+        expect(readCustomInstructions(dir)).toBe("")
+        expect(guideWithCustomInstructions(GUIDE, dir)).toBe(GUIDE)
+    })
+
+    it("reads the file again on every call", () => {
+        const dir = tempDir()
+        writeRules(dir, "First rule.")
+        expect(readCustomInstructions(dir)).toBe("First rule.")
+        writeRules(dir, "Second rule.")
+        expect(readCustomInstructions(dir)).toBe("Second rule.")
+    })
+})
+
+describe("customInstructionsDir", () => {
+    const original = process.env.DRAWIO_DATA_DIR
+    afterEach(() => {
+        if (original === undefined) delete process.env.DRAWIO_DATA_DIR
+        else process.env.DRAWIO_DATA_DIR = original
+    })
+
+    it("honours DRAWIO_DATA_DIR", () => {
+        const dir = tempDir()
+        writeRules(dir, "Use blue fill #dae8fc.")
+        process.env.DRAWIO_DATA_DIR = dir
+        expect(customInstructionsDir()).toBe(dir)
+        expect(guideWithCustomInstructions(GUIDE)).toBe(
+            `${GUIDE}\n\n## Custom Instructions\nUse blue fill #dae8fc.`,
+        )
+    })
+
+    it("expands ~, which JSON configs pass on as it is", () => {
+        process.env.DRAWIO_DATA_DIR = "~/drawio-saves"
+        expect(customInstructionsDir()).toBe(join(homedir(), "drawio-saves"))
+    })
+
+    it("falls back to the home folder when DRAWIO_DATA_DIR is off or unset", () => {
+        const home = join(homedir(), ".next-ai-drawio")
+        process.env.DRAWIO_DATA_DIR = "off"
+        expect(customInstructionsDir()).toBe(home)
+        delete process.env.DRAWIO_DATA_DIR
+        expect(customInstructionsDir()).toBe(home)
+    })
+})
+
+describe("DRAWING_GUIDE", () => {
+    it("stays within its own budget; instructions.md adds up to 5000 more", () => {
+        expect(DRAWING_GUIDE.length).toBeLessThanOrEqual(15000)
+    })
+})

packages/mcp-server/tests/e2e/shell.spec.ts

@@ -0,0 +1,582 @@
+/**
+ * The canvas shell as start_session opens it by default: the built server
+ * (dist/index.js, or the copy MCP_SERVER_ENTRY names: CI installs the packed
+ * tarball in an empty directory) runs over stdio as an MCP client would
+ * start it, and headless Chromium opens the URL it returns.
+ */
+import { mkdtempSync, readFileSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { Client } from "@modelcontextprotocol/sdk/client/index.js"
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
+import { expect, type Page, test } from "@playwright/test"
+
+const pkg = join(dirname(fileURLToPath(import.meta.url)), "../..")
+
+let client: Client
+let dataDir: string
+let shellUrl: string
+
+test.beforeAll(async () => {
+    dataDir = mkdtempSync(join(tmpdir(), "mcp-shell-e2e-"))
+    const transport = new StdioClientTransport({
+        command: process.execPath,
+        args: [process.env.MCP_SERVER_ENTRY ?? join(pkg, "dist/index.js")],
+        env: {
+            ...process.env,
+            DRAWIO_DATA_DIR: dataDir,
+            // Away from the web app's dev server and other test runs
+            PORT: String(6100 + Math.floor(Math.random() * 400)),
+            BROWSER: "none",
+        },
+        stderr: "pipe",
+    })
+    client = new Client({ name: "shell-e2e", version: "0.0.1" })
+    await client.connect(transport)
+    const result = await client.callTool({
+        name: "start_session",
+        arguments: {},
+    })
+    const text = (result.content as { type: string; text?: string }[])
+        .map((c) => c.text ?? "")
+        .join("\n")
+    const match = text.match(/Browser URL: (\S+)/)
+    if (!match) throw new Error(`start_session gave no URL:\n${text}`)
+    shellUrl = match[1]
+})
+
+test.afterAll(async () => {
+    await client?.close()
+    rmSync(dataDir, { recursive: true, force: true })
+})
+
+test("start_session opens the shell, which loads the bundled draw.io", async ({
+    page,
+}) => {
+    expect(shellUrl).toMatch(/^http:\/\/localhost:\d+\/shell\/\?mcp=mcp-/)
+    const errors: string[] = []
+    page.on("console", (message) => {
+        if (message.type() === "error") errors.push(message.text())
+    })
+    page.on("pageerror", (error) => errors.push(error.message))
+
+    await page.goto(shellUrl)
+    const iframe = page.locator("iframe[title='draw.io']")
+    await expect(iframe).toHaveAttribute(
+        "src",
+        /^http:\/\/localhost:\d+\/drawio\/index\.html\?embed=1&proto=json&configure=1&/,
+    )
+    // The cover goes once draw.io sent "init" and loaded the first document
+    await expect(page.getByTestId("canvas-loading")).toHaveCount(0, {
+        timeout: 60_000,
+    })
+    const frame = page.frameLocator("iframe[title='draw.io']")
+    await expect(frame.locator(".geDiagramContainer")).toBeVisible()
+
+    // The shell's own texts and state: the first poll connects it
+    await expect(page.getByTestId("shell-status")).toHaveText(
+        "Connected to the MCP server",
+    )
+    await expect(page.getByTestId("shell-session")).toHaveText(
+        shellUrl.slice(-8),
+    )
+    expect(errors).toEqual([])
+})
+
+// --- The sync with the server (shell/use-mcp-sync.ts) ---
+
+// Each test draws labels of its own: the previous test's diagram is on the
+// canvas when a test starts, and a label shared with it would be visible
+// before the test's own write arrives
+const box = (id: string, label: string, x: number) =>
+    `<mxCell id="${id}" value="${label}" x="${x}" y="40" w="120" h="60"/>`
+
+const toolText = async (name: string, args: Record<string, unknown> = {}) => {
+    const result = await client.callTool({ name, arguments: args })
+    return (result.content as { type: string; text?: string }[])
+        .map((c) => c.text ?? "")
+        .join("\n")
+}
+
+/** The shell with the bundled draw.io ready and in step with the server */
+async function openShell(page: Page) {
+    await page.goto(shellUrl)
+    await expect(page.getByTestId("canvas-loading")).toHaveCount(0, {
+        timeout: 60_000,
+    })
+    await expect(page.getByTestId("shell-status")).toHaveAttribute(
+        "data-status",
+        "connected",
+    )
+    return page.frameLocator("iframe[title='draw.io']")
+}
+
+test("a diagram the MCP draws appears in the shell", async ({ page }) => {
+    const frame = await openShell(page)
+    await toolText("create_new_diagram", {
+        xml: `${box("2", "Alpha", 40)}\n${box("3", "Beta", 240)}\n<mxCell id="4" source="2" target="3"/>`,
+    })
+    await expect(frame.getByText("Alpha")).toBeVisible({ timeout: 10_000 })
+    await expect(frame.getByText("Beta")).toBeVisible()
+})
+
+test("an edit is marked on the canvas, and one Ctrl+Z takes it back for the server too", async ({
+    page,
+}) => {
+    const frame = await openShell(page)
+    await toolText("create_new_diagram", {
+        xml: `${box("2", "Node A", 40)}\n${box("3", "Node B", 240)}`,
+    })
+    await expect(frame.getByText("Node A")).toBeVisible({ timeout: 10_000 })
+    await toolText("edit_diagram", {
+        operations: [
+            { operation: "add", cell_id: "5", new_xml: box("5", "Gamma", 440) },
+        ],
+    })
+    await expect(frame.getByText("Gamma")).toBeVisible({ timeout: 10_000 })
+    // The editor bridge outlines the changed shape (editor-bridge.ts
+    // HIGHLIGHT_OUTLINE); the write went on the canvas in place
+    await expect(frame.locator('[stroke="#a86b00"]')).toHaveCount(1)
+
+    await frame
+        .locator(".geDiagramContainer")
+        .click({ position: { x: 10, y: 10 } })
+    await page.keyboard.press("Control+z")
+    await expect(frame.getByText("Gamma")).toHaveCount(0)
+    await expect(frame.getByText("Node A")).toBeVisible()
+    // The undo is pushed: the server's diagram has no Gamma (get_diagram
+    // also names the removed cell in its notes, so look at the XML)
+    await expect
+        .poll(async () => (await toolText("get_diagram")).includes('id="5"'), {
+            timeout: 10_000,
+        })
+        .toBe(false)
+    expect(await toolText("get_diagram")).toContain('value="Node A"')
+})
+
+test("a change made in the editor is pushed, and get_diagram returns it", async ({
+    page,
+}) => {
+    const frame = await openShell(page)
+    await toolText("create_new_diagram", { xml: box("2", "Solo", 40) })
+    await expect(frame.getByText("Solo")).toBeVisible({ timeout: 10_000 })
+    // draw.io keeps no global editor; in embed mode Draw.loadPlugin hands
+    // it to the callback at once
+    await frame.locator("body").evaluate((body) => {
+        const w = body.ownerDocument.defaultView as any
+        w.Draw.loadPlugin((ui: any) => {
+            const graph = ui.editor.graph
+            graph.getModel().beginUpdate()
+            try {
+                graph.insertVertex(
+                    graph.getDefaultParent(),
+                    "manual-1",
+                    "Manual",
+                    40,
+                    200,
+                    120,
+                    60,
+                    "rounded=1;",
+                )
+            } finally {
+                graph.getModel().endUpdate()
+            }
+        })
+    })
+    await expect(frame.getByText("Manual")).toBeVisible()
+    await expect
+        .poll(
+            async () =>
+                (await toolText("get_diagram")).includes('id="manual-1"'),
+            { timeout: 10_000 },
+        )
+        .toBe(true)
+})
+
+test("screenshot_diagram renders the canvas of the shell", async ({ page }) => {
+    const frame = await openShell(page)
+    await toolText("create_new_diagram", {
+        xml: `${box("2", "Shot A", 40)}\n${box("3", "Shot B", 240)}`,
+    })
+    await expect(frame.getByText("Shot B")).toBeVisible({ timeout: 10_000 })
+    const result = await client.callTool({
+        name: "screenshot_diagram",
+        arguments: {},
+    })
+    const image = (
+        result.content as { type: string; data?: string; mimeType?: string }[]
+    ).find((c) => c.type === "image")
+    expect(result.isError ?? false).toBe(false)
+    expect(image?.mimeType).toBe("image/png")
+    expect(image?.data?.length ?? 0).toBeGreaterThan(1000)
+})
+
+test("exporting another page shows it for a moment, then the user's page comes back", async ({
+    page,
+}) => {
+    const frame = await openShell(page)
+    await toolText("create_new_diagram", { xml: box("2", "First page", 40) })
+    await expect(frame.getByText("First page")).toBeVisible({ timeout: 10_000 })
+    await toolText("add_page", {
+        name: "Second",
+        xml: `<mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/><mxCell id="s1" value="OnSecond" style="rounded=1;" vertex="1" parent="1"><mxGeometry x="40" y="40" width="120" height="60" as="geometry"/></mxCell></root></mxGraphModel>`,
+    })
+    await expect(frame.getByText("Second")).toBeVisible({ timeout: 10_000 })
+    // SVG has no page option in draw.io: the server sends a one-page
+    // projection, which the shell shows only for the export
+    const file = join(dataDir, "second.svg")
+    const text = await toolText("export_diagram", {
+        path: file,
+        page_name: "Second",
+    })
+    expect(text).toContain("exported successfully")
+    expect(readFileSync(file, "utf8")).toContain("OnSecond")
+    await expect(frame.getByText("First page")).toBeVisible({ timeout: 10_000 })
+    await expect(frame.locator(".geTabContainer .geActivePage")).toHaveText(
+        "Page-1",
+    )
+    // The projection was never pushed as the document
+    const xml = await toolText("get_diagram")
+    expect(xml).toContain('value="First page"')
+    expect(xml).toContain('name="Second"')
+})
+
+test("a screenshot of another page leaves the page on screen alone", async ({
+    page,
+}) => {
+    const frame = await openShell(page)
+    await toolText("create_new_diagram", { xml: box("2", "Front page", 40) })
+    await expect(frame.getByText("Front page")).toBeVisible({ timeout: 10_000 })
+    await toolText("add_page", {
+        name: "Backside",
+        xml: `<mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/><mxCell id="b1" value="OnBack" style="rounded=1;" vertex="1" parent="1"><mxGeometry x="40" y="40" width="120" height="60" as="geometry"/></mxCell></root></mxGraphModel>`,
+    })
+    const tabs = frame.locator(".geTabContainer")
+    await expect(tabs.getByText("Backside", { exact: true })).toBeVisible({
+        timeout: 10_000,
+    })
+    const activeTab = tabs.locator(".geActivePage")
+    await expect(activeTab).toHaveText("Page-1")
+    // The page on screen, as the editor reports it to the server
+    const before = await toolText("get_selection")
+    expect(before).toContain('page "Page-1"')
+
+    // PNG: draw.io renders the other page by its id, off screen; the shell
+    // never shows it as a projection, so the page on screen does not change
+    const png = async (args: Record<string, unknown>) => {
+        const result = await client.callTool({
+            name: "screenshot_diagram",
+            arguments: args,
+        })
+        const image = (
+            result.content as {
+                type: string
+                data?: string
+                mimeType?: string
+            }[]
+        ).find((c) => c.type === "image")
+        expect(result.isError ?? false).toBe(false)
+        expect(image?.mimeType).toBe("image/png")
+        expect(image?.data?.length ?? 0).toBeGreaterThan(1000)
+        return image?.data ?? ""
+    }
+    const back = await png({ page_name: "Backside" })
+    await expect(activeTab).toHaveText("Page-1")
+    await expect(frame.getByText("Front page")).toBeVisible()
+    expect(await toolText("get_selection")).toContain('page "Page-1"')
+    // Another picture than the page on screen
+    expect(await png({})).not.toBe(back)
+})
+
+test("get_selection reports the cells selected in the editor", async ({
+    page,
+}) => {
+    const frame = await openShell(page)
+    await toolText("create_new_diagram", {
+        xml: `${box("2", "Pick me", 40)}\n${box("3", "Leave me", 240)}\n<mxCell id="4" value="link" source="2" target="3"/>`,
+    })
+    await expect(frame.getByText("Pick me")).toBeVisible({ timeout: 10_000 })
+    const nothing = await toolText("get_selection")
+    expect(nothing).toContain("Nothing is selected")
+    expect(nothing).toContain('page "Page-1"')
+
+    // Select a shape and the edge in the editor, as a click would
+    await frame.locator("body").evaluate((body) => {
+        const w = body.ownerDocument.defaultView as any
+        w.Draw.loadPlugin((ui: any) => {
+            const graph = ui.editor.graph
+            graph.setSelectionCells([
+                graph.model.getCell("2"),
+                graph.model.getCell("4"),
+            ])
+        })
+    })
+    const text = await toolText("get_selection")
+    expect(text).toContain('2 cells selected on page "Page-1"')
+    expect(text).toContain('id="2" shape "Pick me" at x=40 y=40 w=120 h=60')
+    expect(text).toContain('id="4" edge "link" from "2" to "3"')
+    expect(text).not.toContain('id="3"')
+
+    // A shape in a container is reported with it, also after the user
+    // entered the container (Ctrl+Shift+End), where it is the default parent
+    await toolText("create_new_diagram", {
+        xml: `<mxCell id="box" value="Box" style="swimlane;" vertex="1" parent="1"><mxGeometry x="40" y="40" width="300" height="200" as="geometry"/></mxCell>\n<mxCell id="kid" value="Kid" style="rounded=1;" vertex="1" parent="box"><mxGeometry x="20" y="30" width="120" height="60" as="geometry"/></mxCell>`,
+    })
+    await expect(frame.getByText("Kid")).toBeVisible({ timeout: 10_000 })
+    await frame.locator("body").evaluate((body) => {
+        const w = body.ownerDocument.defaultView as any
+        w.Draw.loadPlugin((ui: any) => {
+            const graph = ui.editor.graph
+            graph.enterGroup(graph.model.getCell("box"))
+            graph.setSelectionCell(graph.model.getCell("kid"))
+        })
+    })
+    const inside = await toolText("get_selection")
+    expect(inside).toContain(
+        'id="kid" shape "Kid" at x=20 y=30 w=120 h=60 inside "box"',
+    )
+    await frame.locator("body").evaluate((body) => {
+        const w = body.ownerDocument.defaultView as any
+        w.Draw.loadPlugin((ui: any) => ui.editor.graph.exitGroup())
+    })
+})
+
+test("the download button saves the diagram as a file", async ({ page }) => {
+    const frame = await openShell(page)
+    await toolText("create_new_diagram", { xml: box("2", "Keep me", 40) })
+    await expect(frame.getByText("Keep me")).toBeVisible({ timeout: 10_000 })
+    await page.getByTestId("download").click()
+    const dialog = page.getByRole("dialog")
+    await expect(dialog).toBeVisible()
+    // The dialog's utility classes are in the shell's stylesheet (shell.css
+    // names the shared component with @source): the formats in two columns
+    const columns = await dialog
+        .getByRole("radiogroup")
+        .evaluate((el) => getComputedStyle(el).gridTemplateColumns)
+    expect(columns.split(" ")).toHaveLength(2)
+    // .drawio is the default format
+    const download = page.waitForEvent("download")
+    await dialog.getByRole("button", { name: "Export" }).click()
+    const file = await download
+    expect(file.suggestedFilename()).toMatch(
+        /^diagram-\d{4}-\d{2}-\d{2}\.drawio$/,
+    )
+    // draw.io's own export of the document (compressed pages, as the web
+    // app saves them; load_diagram opens them)
+    const saved = readFileSync(await file.path(), "utf8")
+    expect(saved).toMatch(/^<mxfile\b/)
+    expect(saved).toContain('name="Page-1"')
+})
+
+test("the download waits for a page export's projection, and saves every page", async ({
+    page,
+}) => {
+    const frame = await openShell(page)
+    await toolText("create_new_diagram", { xml: box("2", "Stay here", 40) })
+    await expect(frame.getByText("Stay here")).toBeVisible({ timeout: 10_000 })
+    await toolText("add_page", {
+        name: "Elsewhere",
+        xml: `<mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/><mxCell id="e1" value="OnElsewhere" style="rounded=1;" vertex="1" parent="1"><mxGeometry x="40" y="40" width="120" height="60" as="geometry"/></mxCell></root></mxGraphModel>`,
+    })
+    await expect(
+        frame
+            .locator(".geTabContainer")
+            .getByText("Elsewhere", { exact: true }),
+    ).toBeVisible({ timeout: 10_000 })
+    await page.getByTestId("download").click()
+    const dialog = page.getByRole("dialog")
+    await expect(dialog).toBeVisible()
+    // The export's result is held up for 2 s: the one-page projection of
+    // the other page is surely still on the canvas when Export is clicked
+    await page.route("**/api/state", async (route) => {
+        const request = route.request()
+        if (
+            request.method() === "POST" &&
+            (request.postData() ?? "").includes('"exportData"')
+        ) {
+            await new Promise((r) => setTimeout(r, 2000))
+        }
+        await route.continue()
+    })
+    const exported = toolText("export_diagram", {
+        path: join(dataDir, "elsewhere.svg"),
+        page_name: "Elsewhere",
+    })
+    await expect(frame.getByText("OnElsewhere")).toBeVisible({
+        timeout: 10_000,
+    })
+    const download = page.waitForEvent("download")
+    await dialog.getByRole("button", { name: "Export" }).click()
+    // Saved once the user's document is back: both pages, not the projection
+    const saved = readFileSync(await (await download).path(), "utf8")
+    expect(saved.match(/<diagram\b/g)).toHaveLength(2)
+    expect(saved).toContain('name="Page-1"')
+    expect(saved).toContain('name="Elsewhere"')
+    expect(await exported).toContain("exported successfully")
+})
+
+// --- Version cards from the server's History (shell/node-versions-source.ts) ---
+
+test("the version cards follow the server's History; undo, redo and restore go through it", async ({
+    page,
+}) => {
+    // A session of its own, so History holds only this test's versions
+    const started = await toolText("start_session")
+    const url = started.match(/Browser URL: (\S+)/)?.[1]
+    if (!url) throw new Error(`start_session gave no URL:\n${started}`)
+    await page.goto(url)
+    await expect(page.getByTestId("canvas-loading")).toHaveCount(0, {
+        timeout: 60_000,
+    })
+    await expect(page.getByTestId("shell-status")).toHaveAttribute(
+        "data-status",
+        "connected",
+    )
+    const frame = page.frameLocator("iframe[title='draw.io']")
+    const cards = page.getByTestId("version-card")
+    const latestCard = cards.last()
+    const getDiagram = () => toolText("get_diagram")
+
+    // Three writes, three cards; the newest can be undone
+    await toolText("create_new_diagram", { xml: box("a", "Card A", 40) })
+    await expect(frame.getByText("Card A")).toBeVisible({ timeout: 10_000 })
+    await expect(cards).toHaveCount(1, { timeout: 10_000 })
+    await expect(cards.first()).toContainText("Drew the diagram")
+    await toolText("edit_diagram", {
+        operations: [
+            {
+                operation: "add",
+                cell_id: "b",
+                new_xml: box("b", "Card B", 240),
+            },
+        ],
+    })
+    await expect(frame.getByText("Card B")).toBeVisible({ timeout: 10_000 })
+    await toolText("edit_diagram", {
+        operations: [
+            {
+                operation: "add",
+                cell_id: "c",
+                new_xml: box("c", "Card C", 440),
+            },
+        ],
+    })
+    await expect(frame.getByText("Card C")).toBeVisible({ timeout: 10_000 })
+    await expect(cards).toHaveCount(3, { timeout: 10_000 })
+    await expect(latestCard).toContainText("Changed the diagram")
+    await expect(latestCard.getByTestId("version-undo")).toHaveText(
+        /Undo change/,
+    )
+
+    // Undo: the server restores the version before; the card says so
+    await latestCard.getByTestId("version-undo").click()
+    await expect(frame.getByText("Card C")).toHaveCount(0, { timeout: 10_000 })
+    await expect(frame.getByText("Card B")).toBeVisible()
+    await expect(latestCard).toContainText("Change undone")
+    await expect(latestCard.getByTestId("version-undo")).toHaveText(
+        /Redo change/,
+    )
+    // A restore adds a History entry, not a card
+    await expect(cards).toHaveCount(3)
+    await expect
+        .poll(async () => (await getDiagram()).includes('id="c"'), {
+            timeout: 10_000,
+        })
+        .toBe(false)
+
+    // Redo: the newest version is back on the canvas and the server
+    await latestCard.getByTestId("version-undo").click()
+    await expect(frame.getByText("Card C")).toBeVisible({ timeout: 10_000 })
+    await expect(latestCard).toContainText("Changed the diagram")
+    await expect(latestCard.getByTestId("version-undo")).toHaveText(
+        /Undo change/,
+    )
+    await expect
+        .poll(async () => (await getDiagram()).includes('id="c"'), {
+            timeout: 10_000,
+        })
+        .toBe(true)
+
+    // A hand edit: no version is on the canvas, so the newest card offers
+    // a restore, not an undo
+    await frame.locator("body").evaluate((body) => {
+        const w = body.ownerDocument.defaultView as any
+        w.Draw.loadPlugin((ui: any) => {
+            const graph = ui.editor.graph
+            graph.getModel().beginUpdate()
+            try {
+                graph.insertVertex(
+                    graph.getDefaultParent(),
+                    "manual-card",
+                    "By hand",
+                    40,
+                    200,
+                    120,
+                    60,
+                    "rounded=1;",
+                )
+            } finally {
+                graph.getModel().endUpdate()
+            }
+        })
+    })
+    await expect
+        .poll(async () => (await getDiagram()).includes('id="manual-card"'), {
+            timeout: 10_000,
+        })
+        .toBe(true)
+    await expect(latestCard.getByTestId("version-restore")).toBeVisible()
+    await expect(cards).toHaveCount(3)
+
+    // Restoring the first version keeps the hand edit as a version of its
+    // own, and get_diagram agrees with the canvas
+    await cards.first().getByTestId("version-restore").click()
+    await expect(frame.getByText("Card B")).toHaveCount(0, { timeout: 10_000 })
+    await expect(frame.getByText("By hand")).toHaveCount(0)
+    await expect(frame.getByText("Card A")).toBeVisible()
+    await expect(cards).toHaveCount(4, { timeout: 10_000 })
+    await expect(cards.nth(3)).toContainText("Changed by hand")
+    // The first version is on the canvas: its restore button rests
+    await expect(cards.first().getByTestId("version-restore")).toBeDisabled()
+    await expect
+        .poll(getDiagram, { timeout: 10_000 })
+        .toContain('value="Card A"')
+    const xml = await getDiagram()
+    expect(xml).not.toContain('id="b"')
+    expect(xml).not.toContain('id="manual-card"')
+    // The MCP tool sees the same versions: the hand edit is one step back
+    expect(await toolText("restore_version", { steps_back: 1 })).toContain(
+        "Restored the version 1 step(s) back",
+    )
+    await expect(frame.getByText("By hand")).toBeVisible({ timeout: 10_000 })
+    await expect(cards).toHaveCount(4)
+})
+
+test("the theme toggle switches the page and draw.io, and is remembered", async ({
+    page,
+}) => {
+    await page.goto(shellUrl)
+    await expect(page.getByTestId("canvas-loading")).toHaveCount(0, {
+        timeout: 60_000,
+    })
+    const html = page.locator("html")
+    const frameBody = page
+        .frameLocator("iframe[title='draw.io']")
+        .locator("body")
+    await expect(html).not.toHaveClass(/dark/)
+    await expect(frameBody).not.toHaveClass(/geDarkMode/)
+
+    await page.getByTestId("theme-toggle").click()
+    await expect(html).toHaveClass(/dark/)
+    // Same-origin draw.io switches in place, without a reload
+    await expect(frameBody).toHaveClass(/geDarkMode/)
+    expect(
+        await page.evaluate(() => localStorage.getItem("mcp:dark-mode")),
+    ).toBe("true")
+
+    await page.reload()
+    await expect(html).toHaveClass(/dark/)
+    await page.getByTestId("theme-toggle").click()
+    await expect(html).not.toHaveClass(/dark/)
+})

packages/mcp-server/tests/edit-gate.test.ts

@@ -19,6 +19,7 @@ beforeAll(() => {
 import {
     checkEditGate,
     contentFingerprint,
+    describeChanges,
     markPageSeen,
 } from "../src/edit-gate.ts"
 
@@ -168,3 +169,139 @@ describe("markPageSeen", () => {
         expect(markPageSeen("", live, { page_id: "A" })).toBe(live)
     })
 })
+
+describe("describeChanges", () => {
+    const BOX2 = `<mxCell id="box2" value="World" vertex="1" parent="1"><mxGeometry x="200" y="40" width="120" height="60" as="geometry"/></mxCell>`
+    const XML_A_PLUS_BOX2 = XML_A.replace("</root>", `${BOX2}</root>`)
+    const PAGE_2 = `<diagram id="p2" name="Page-2"><mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/></root></mxGraphModel></diagram>`
+    const XML_A_TWO_PAGES = XML_A.replace("</mxfile>", `${PAGE_2}</mxfile>`)
+
+    it("names a moved cell with its label", () => {
+        const summary = describeChanges(XML_A, XML_B)
+        expect(summary).toBe(
+            'Since you last saw it, the user changed the diagram: modified box1 ("Hello").',
+        )
+        expect(summary).toContain("modified box1")
+    })
+
+    it("names a deleted cell", () => {
+        expect(describeChanges(XML_A_PLUS_BOX2, XML_A)).toContain(
+            'removed box2 ("World")',
+        )
+    })
+
+    it("names an added cell", () => {
+        expect(describeChanges(XML_A, XML_A_PLUS_BOX2)).toContain(
+            'added box2 ("World")',
+        )
+    })
+
+    it("is empty for draw.io's re-serialisation of the same content", () => {
+        expect(describeChanges(XML_A, XML_A_RESERIALIZED)).toBe("")
+    })
+
+    it("is empty when the model has seen nothing yet", () => {
+        expect(describeChanges("", XML_B)).toBe("")
+    })
+
+    it("is empty when one side does not parse", () => {
+        expect(describeChanges(XML_A, "not xml at all")).toBe("")
+    })
+
+    it("reports a renamed page", () => {
+        const renamed = XML_A.replace('name="Page-1"', 'name="Renamed"')
+        expect(describeChanges(XML_A, renamed)).toBe(
+            'Since you last saw it, the user changed the diagram. Page 1 renamed to "Renamed".',
+        )
+    })
+
+    // A bare <mxGraphModel> push carries no page name, so the invented
+    // "Page-1" must not read as a rename
+    it("never reports a rename against a bare mxGraphModel", () => {
+        const seenRenamed = XML_A.replace('name="Page-1"', 'name="Arch"')
+        expect(describeChanges(seenRenamed, XML_A_BARE)).toBe("")
+        const bareMoved = XML_A_BARE.replace('x="40" y="40"', 'x="300" y="200"')
+        const summary = describeChanges(seenRenamed, bareMoved)
+        expect(summary).toContain("modified box1")
+        expect(summary).not.toContain("renamed")
+    })
+
+    it("strips HTML from labels and reads UserObject labels", () => {
+        const html = XML_A.replace(
+            'value="Hello"',
+            'value="&lt;b&gt;Hello&lt;/b&gt;"',
+        )
+        expect(describeChanges(XML_A, html)).toContain(
+            'modified box1 ("Hello")',
+        )
+        const userObject = XML_A.replace(
+            "</root>",
+            `<UserObject id="u1" label="&lt;i&gt;Link&lt;/i&gt;" link="https://x.y"><mxCell style="rounded=1;" vertex="1" parent="1"><mxGeometry x="0" y="0" width="80" height="40" as="geometry"/></mxCell></UserObject></root>`,
+        )
+        expect(describeChanges(XML_A, userObject)).toContain(
+            'added u1 ("Link")',
+        )
+    })
+
+    it("keeps the words of an HTML label apart and decodes its spaces", () => {
+        const lines = XML_A.replace(
+            'value="Hello"',
+            'value="Line1&lt;br&gt;Line2&amp;nbsp;end &amp;amp; more"',
+        )
+        expect(describeChanges(XML_A, lines)).toContain(
+            'modified box1 ("Line1 Line2 end & more")',
+        )
+    })
+
+    it("cuts long labels at 30 characters", () => {
+        const long = "a".repeat(40)
+        const summary = describeChanges(
+            XML_A,
+            XML_A.replace('value="Hello"', `value="${long}"`),
+        )
+        expect(summary).toContain(`("${"a".repeat(30)}...")`)
+    })
+
+    it("lists at most 20 cells and counts the rest", () => {
+        const many = Array.from(
+            { length: 25 },
+            (_, i) => `<mxCell id="n${i}" vertex="1" parent="1"/>`,
+        ).join("")
+        const summary = describeChanges(
+            XML_A,
+            XML_A.replace("</root>", `${many}</root>`),
+        )
+        expect(summary).toContain("added n0, n1,")
+        expect(summary).toContain("n19 and 5 more.")
+        expect(summary).not.toContain("n20")
+    })
+
+    it("reports added and removed pages", () => {
+        expect(describeChanges(XML_A, XML_A_TWO_PAGES)).toBe(
+            "Since you last saw it, the user changed the diagram: page 2 added.",
+        )
+        expect(describeChanges(XML_A_TWO_PAGES, XML_A)).toBe(
+            "Since you last saw it, the user changed the diagram: page 2 removed.",
+        )
+    })
+
+    it("names the page of a cell change in a multi-page document", () => {
+        const movedOnPage1 = XML_A_TWO_PAGES.replace(
+            'x="40" y="40"',
+            'x="300" y="200"',
+        )
+        expect(describeChanges(XML_A_TWO_PAGES, movedOnPage1)).toContain(
+            'page 1 modified box1 ("Hello")',
+        )
+    })
+
+    it("falls back to a generic clause when only the cell order changed", () => {
+        const reordered = XML_A_PLUS_BOX2.replace(BOX2, "").replace(
+            '<mxCell id="box1"',
+            `${BOX2}<mxCell id="box1"`,
+        )
+        expect(describeChanges(XML_A_PLUS_BOX2, reordered)).toBe(
+            "Since you last saw it, the user changed the diagram: the order of the cells changed.",
+        )
+    })
+})

packages/mcp-server/tests/history.test.ts

@@ -0,0 +1,205 @@
+/**
+ * Tests for the diagram history: the versions restore_version can go to.
+ */
+
+import { beforeAll, describe, expect, it } from "vitest"
+import { installDomPolyfill } from "../src/dom.ts"
+import {
+    addHistory,
+    clearHistory,
+    currentEntryId,
+    firstCopyIds,
+    getHistory,
+    isInHistory,
+    otherVersions,
+} from "../src/history.ts"
+
+beforeAll(() => {
+    // XML parsing for the content fingerprints
+    installDomPolyfill()
+})
+
+const page = (cellId: string) =>
+    `<mxfile><diagram id="p" name="P"><mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/><mxCell id="${cellId}" vertex="1" parent="1"/></root></mxGraphModel></diagram></mxfile>`
+
+const A = page("a")
+const B = page("b")
+const C = page("c")
+
+// draw.io's copy of B: other attribute order, whitespace and viewport
+// attributes, same diagram
+const B_COPY = `<mxfile host="app.diagrams.net">
+  <diagram name="P" id="p">
+    <mxGraphModel dx="100" dy="200" pageWidth="850">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="b" parent="1" vertex="1" />
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>`
+
+const fill = (id: string, versions: string[]) => {
+    clearHistory(id)
+    for (const xml of versions) addHistory(id, xml)
+}
+
+describe("otherVersions", () => {
+    it("lists the versions before the canvas, newest first", () => {
+        const id = "history-abc"
+        fill(id, [A, B, C])
+        expect(otherVersions(id, C).map((e) => e.xml)).toEqual([B, A])
+    })
+
+    it("lists each version once after an undo, the left one first", () => {
+        const id = "history-abcb"
+        fill(id, [A, B, C, B])
+        expect(otherVersions(id, B).map((e) => e.xml)).toEqual([C, A])
+    })
+
+    it("lists every version when the canvas is in none of them", () => {
+        const id = "history-manual"
+        fill(id, [A, B, C])
+        expect(otherVersions(id, page("manual")).map((e) => e.xml)).toEqual([
+            C,
+            B,
+            A,
+        ])
+    })
+
+    it("counts a re-serialised copy as the same version", () => {
+        const id = "history-copy"
+        fill(id, [A, B, B_COPY])
+        expect(otherVersions(id, B).map((e) => e.xml)).toEqual([A])
+        expect(otherVersions(id, B_COPY).map((e) => e.xml)).toEqual([A])
+    })
+
+    it("keeps the newest copy of a repeated version", () => {
+        const id = "history-newest"
+        fill(id, [A, B, A])
+        const [newestA] = otherVersions(id, B)
+        expect(newestA.id).toBe(getHistory(id)[2].id)
+        expect(otherVersions(id, B)).toHaveLength(1)
+    })
+
+    it("matches a bare model from the browser with its named page", () => {
+        const id = "history-bare"
+        const named = (xml: string) => xml.replace('name="P"', 'name="Arch"')
+        fill(id, [named(A), named(B)])
+        // The browser's sync sent page B without its <mxfile> wrapper
+        const bareB = B.replace(/^.*?(<mxGraphModel>)/, "$1").replace(
+            "</diagram></mxfile>",
+            "",
+        )
+        expect(otherVersions(id, bareB).map((e) => e.xml)).toEqual([named(A)])
+        expect(isInHistory(id, bareB)).toBe(true)
+        expect(isInHistory(id, C)).toBe(false)
+    })
+
+    it("still counts a rename when an unrelated bare model is in History", () => {
+        const id = "history-mixed"
+        const bareX = page("x")
+            .replace(/^.*?(<mxGraphModel>)/, "$1")
+            .replace("</diagram></mxfile>", "")
+        const arch = B.replace('name="P"', 'name="Arch"')
+        const overview = B.replace('name="P"', 'name="Overview"')
+        fill(id, [bareX, arch])
+        expect(otherVersions(id, overview).map((e) => e.xml)).toEqual([
+            arch,
+            bareX,
+        ])
+        expect(isInHistory(id, overview)).toBe(false)
+    })
+
+    it("returns nothing for an empty history", () => {
+        const id = "history-empty"
+        clearHistory(id)
+        expect(otherVersions(id, A)).toEqual([])
+    })
+})
+
+describe("entries", () => {
+    it("record who made them", () => {
+        const id = "history-fields"
+        clearHistory(id)
+        addHistory(id, A)
+        addHistory(id, B, "<svg/>", "user")
+        addHistory(id, C, "", "restore")
+        const [first, second, third] = getHistory(id)
+        expect(first.source).toBeUndefined()
+        expect(second.source).toBe("user")
+        expect(second.svg).toBe("<svg/>")
+        expect(third.source).toBe("restore")
+    })
+})
+
+// The shell's version cards: which entry the canvas shows, and which
+// entries are copies of an earlier one (a restore adds one)
+describe("currentEntryId and firstCopyIds", () => {
+    it("name the newest entry with the canvas's content, by the rule of otherVersions", () => {
+        const id = "history-current"
+        fill(id, [A, B, C, A])
+        const [a, b, c, aCopy] = getHistory(id)
+        expect(currentEntryId(id, A)).toBe(aCopy.id)
+        expect(currentEntryId(id, B_COPY)).toBe(b.id)
+        expect(currentEntryId(id, page("manual"))).toBeNull()
+        // A restore's copy belongs with its first entry; the others are
+        // their own
+        expect([...firstCopyIds(id).entries()]).toEqual([
+            [a.id, a.id],
+            [b.id, b.id],
+            [c.id, c.id],
+            [aCopy.id, a.id],
+        ])
+    })
+
+    it("group a bare model with the first named page it matches, never a later one", () => {
+        // A bare model (the browser's sync can send one) has no page name:
+        // it is the same as "Arch" and as "Overview", which differ from each
+        // other. Each entry names a first copy with its own content, so a
+        // card never shows one document and restores another
+        const id = "history-bare-groups"
+        const named = (name: string) => A.replace('name="P"', `name="${name}"`)
+        const bare = `<mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/><mxCell id="a" vertex="1" parent="1"/></root></mxGraphModel>`
+        fill(id, [named("Arch"), bare, named("Overview")])
+        const [arch, model, overview] = getHistory(id)
+        const firsts = firstCopyIds(id)
+        expect([...firsts.entries()]).toEqual([
+            [arch.id, arch.id],
+            [model.id, arch.id],
+            [overview.id, overview.id],
+        ])
+        // The entry named as first has the content of every entry in its
+        // group (otherVersions of that content never lists it)
+        for (const entry of getHistory(id)) {
+            expect(otherVersions(id, entry.xml).map((e) => e.id)).not.toContain(
+                firsts.get(entry.id),
+            )
+        }
+    })
+
+    it("agree with otherVersions on a page setting that only the canvas shows", () => {
+        // The same cells with another background: one version to the MCP
+        // core (the model's edits stay valid when the user changes a page
+        // setting), so the canvas still shows that entry and restore_version
+        // offers no other copy of it
+        const id = "history-background"
+        const withBackground = A.replace(
+            "<mxGraphModel>",
+            '<mxGraphModel background="#ffcc00" shadow="1">',
+        )
+        fill(id, [A, B])
+        const [a] = getHistory(id)
+        expect(currentEntryId(id, withBackground)).toBe(a.id)
+        expect(otherVersions(id, withBackground).map((e) => e.xml)).toEqual([B])
+        expect(isInHistory(id, withBackground)).toBe(true)
+    })
+
+    it("return nothing for an empty history", () => {
+        const id = "history-current-empty"
+        clearHistory(id)
+        expect(currentEntryId(id, A)).toBeNull()
+        expect(firstCopyIds(id).size).toBe(0)
+    })
+})

packages/mcp-server/tests/http-server.test.ts

@@ -6,32 +6,78 @@
  * node:http so tests can set raw paths and Host/Origin headers.
  */
 
+import {
+    mkdirSync,
+    mkdtempSync,
+    rmSync,
+    utimesSync,
+    writeFileSync,
+} from "node:fs"
 import http from "node:http"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
 import { afterAll, beforeAll, describe, expect, it } from "vitest"
 import { installDomPolyfill } from "../src/dom.ts"
 import { addHistory, getHistory } from "../src/history.ts"
 import {
+    activePreviewUi,
+    drawioEmbedParams,
+    getApiToken,
     getState,
+    isSameOriginDrawio,
     keepInHistory,
     onSessionRecreate,
+    onStateChange,
+    previewUiFromEnv,
+    previewUrl,
+    readSelection,
     requestExport,
+    requestSelection,
     requestSync,
+    restoreHistoryEntry,
+    setDrawioDir,
+    setShellDir,
     setState,
+    shellConfig,
     shutdown,
     startHttpServer,
+    waitForSelection,
     waitForSync,
 } from "../src/http-server.ts"
 
 let port = 0
+// A stand-in for the bundled draw.io copy (dist/drawio), with a server-side
+// part of the war that must never be served
+let drawioDir = ""
+// A stand-in for the built canvas shell (dist/shell)
+let shellDir = ""
 
 beforeAll(async () => {
     // XML parsing, as the server installs it at startup
     installDomPolyfill()
+    drawioDir = mkdtempSync(join(tmpdir(), "drawio-static-"))
+    mkdirSync(join(drawioDir, "js"))
+    mkdirSync(join(drawioDir, "WEB-INF"))
+    writeFileSync(join(drawioDir, "index.html"), "<html>draw.io</html>")
+    writeFileSync(join(drawioDir, ".version"), "v1\n")
+    writeFileSync(join(drawioDir, "js/app.min.js"), "// app")
+    writeFileSync(join(drawioDir, "WEB-INF/web.xml"), "<web-app/>")
+    setDrawioDir(drawioDir)
+    shellDir = mkdtempSync(join(tmpdir(), "shell-static-"))
+    writeFileSync(
+        join(shellDir, "index.html"),
+        "<html><script>window.__MCP_CONFIG__ = {{CONFIG_JSON}};</script></html>",
+    )
+    writeFileSync(join(shellDir, "shell.js"), "// shell")
+    writeFileSync(join(shellDir, "shell.css"), "body{}")
+    setShellDir(shellDir)
     port = await startHttpServer(40000 + Math.floor(Math.random() * 10000))
 })
 
 afterAll(() => {
     shutdown()
+    rmSync(drawioDir, { recursive: true, force: true })
+    rmSync(shellDir, { recursive: true, force: true })
 })
 
 interface Response {
@@ -40,7 +86,10 @@ interface Response {
     body: string
 }
 
-/** Send a request; `body` may be split into several writes. */
+/**
+ * Send a request as the preview page does (same Host, the API token);
+ * `body` may be split into several writes.
+ */
 function request(
     path: string,
     opts: {
@@ -56,7 +105,11 @@ function request(
                 port,
                 path,
                 method: opts.method ?? "GET",
-                headers: { host: `localhost:${port}`, ...opts.headers },
+                headers: {
+                    host: `localhost:${port}`,
+                    "x-drawio-token": getApiToken(),
+                    ...opts.headers,
+                },
             },
             (res) => {
                 const chunks: Buffer[] = []
@@ -256,6 +309,25 @@ describe("POST /api/state", () => {
         expect(history.at(-1)?.xml).toBe("<mxfile>lost user edit</mxfile>")
     })
 
+    it("asks for a save when a lost user edit is kept in history", async () => {
+        const id = "mcp-conflict-save"
+        setState(id, "<mxfile>user v1</mxfile>", undefined, true)
+        const aiVersion = setState(id, "<mxfile>AI edit</mxfile>")
+        const saves: string[] = []
+        onStateChange((sessionId, xml) => saves.push(`${sessionId} ${xml}`))
+        try {
+            await postJson("/api/state", {
+                sessionId: id,
+                xml: "<mxfile>lost user edit</mxfile>",
+                baseVersion: aiVersion - 1,
+            })
+        } finally {
+            onStateChange(() => {})
+        }
+        // The canvas stays the AI write; the save takes the new History
+        expect(saves).toEqual([`${id} <mxfile>AI edit</mxfile>`])
+    })
+
     it("ends a pending sync when the sync reply is older than an AI write", async () => {
         const id = "mcp-stale-sync"
         setState(id, "<mxfile>before</mxfile>", undefined, true)
@@ -336,6 +408,154 @@ describe("export requests", () => {
         expect(getState(id)?.exportData).toBeUndefined()
         expect(getState(id)?.exportFormat).toBe("svg")
     })
+
+    it("names exports at random, so a result meant for another process is not taken", async () => {
+        const id = "mcp-export-random-id"
+        setState(id, "<mxfile>x</mxfile>")
+        requestExport(id, "svg")
+        const poll = JSON.parse(
+            (await request(`/api/state?sessionId=${id}`)).body,
+        )
+        expect(poll.exportId).toMatch(/^[0-9a-f-]{36}$/)
+        // The page retries a result refused with 403 against the process
+        // that took over the port; a per-process counter would restart at 1
+        await postJson("/api/state", {
+            sessionId: id,
+            exportData: "<svg>OLD</svg>",
+            exportId: 1,
+        })
+        expect(getState(id)?.exportData).toBeUndefined()
+        expect(getState(id)?.exportFormat).toBe("svg")
+    })
+})
+
+describe("selection requests (get_selection)", () => {
+    const picked = {
+        pageId: "p1",
+        pageName: "Page-1",
+        cells: [{ id: "3", label: "Login", edge: false }],
+    }
+
+    it("shows the request to the page and takes its answer once", async () => {
+        const id = "mcp-selection"
+        setState(id, "<mxfile>x</mxfile>")
+        expect(requestSelection(id)).toBe(true)
+        const poll = JSON.parse(
+            (await request(`/api/state?sessionId=${id}`)).body,
+        )
+        expect(poll.selectionId).toMatch(/^[0-9a-f-]{36}$/)
+        // The request survives a write meanwhile
+        setState(id, "<mxfile>y</mxfile>")
+        const waiting = waitForSelection(id, 3000)
+        const answer = await postJson("/api/state", {
+            sessionId: id,
+            selectionId: poll.selectionId,
+            selection: picked,
+        })
+        expect(answer.status).toBe(200)
+        expect(await waiting).toEqual(picked)
+        // Taken: the next poll shows no request
+        const after = JSON.parse(
+            (await request(`/api/state?sessionId=${id}`)).body,
+        )
+        expect(after.selectionId).toBeNull()
+        expect(getState(id)?.xml).toBe("<mxfile>y</mxfile>")
+    })
+
+    it("ignores an answer to another request, and gives up in time", async () => {
+        const id = "mcp-selection-late"
+        setState(id, "<mxfile>x</mxfile>")
+        requestSelection(id)
+        const first = JSON.parse(
+            (await request(`/api/state?sessionId=${id}`)).body,
+        )
+        requestSelection(id)
+        await postJson("/api/state", {
+            sessionId: id,
+            selectionId: first.selectionId,
+            selection: picked,
+        })
+        expect(getState(id)?.selection).toBeUndefined()
+        expect(getState(id)?.selectionId).not.toBe(first.selectionId)
+        // A malformed answer is not taken either
+        const second = getState(id)?.selectionId
+        await postJson("/api/state", {
+            sessionId: id,
+            selectionId: second,
+            selection: { cells: "3" },
+        })
+        expect(getState(id)?.selection).toBeUndefined()
+        expect(await waitForSelection(id, 250)).toBeNull()
+        // The request is withdrawn with the timeout
+        expect(getState(id)?.selectionId).toBeUndefined()
+        expect(requestSelection("mcp-unknown-session")).toBe(false)
+    })
+
+    it("takes no answer while no request is pending", async () => {
+        const id = "mcp-selection-unasked"
+        setState(id, "<mxfile>x</mxfile>")
+        // Both undefined would compare equal
+        await postJson("/api/state", { sessionId: id, selection: picked })
+        expect(getState(id)?.selection).toBeUndefined()
+        requestSelection(id)
+        const { selectionId } = getState(id) ?? {}
+        await postJson("/api/state", { sessionId: id, selection: picked })
+        expect(getState(id)?.selection).toBeUndefined()
+        expect(getState(id)?.selectionId).toBe(selectionId)
+        await waitForSelection(id, 50)
+    })
+
+    it("keeps the first answer when two tabs answer the same request", async () => {
+        const id = "mcp-selection-two-tabs"
+        setState(id, "<mxfile>x</mxfile>")
+        requestSelection(id)
+        const { selectionId } = getState(id) ?? {}
+        await postJson("/api/state", {
+            sessionId: id,
+            selectionId,
+            selection: picked,
+        })
+        const other = { ...picked, cells: [] }
+        await postJson("/api/state", {
+            sessionId: id,
+            selectionId,
+            selection: other,
+        })
+        expect(await waitForSelection(id, 1000)).toEqual(picked)
+    })
+
+    it("lets overlapping get_selection calls take turns, each getting its own answer", async () => {
+        const id = "mcp-selection-overlap"
+        setState(id, "<mxfile>x</mxfile>")
+        const poll = async () =>
+            JSON.parse((await request(`/api/state?sessionId=${id}`)).body)
+        const first = readSelection(id, 3000)
+        const second = readSelection(id, 3000)
+        // The tab sees one request and answers it
+        let shown = await poll()
+        expect(shown.selectionId).toMatch(/^[0-9a-f-]{36}$/)
+        await postJson("/api/state", {
+            sessionId: id,
+            selectionId: shown.selectionId,
+            selection: picked,
+        })
+        expect(await first).toEqual(picked)
+        // Then the second call's request, another id, answered in turn
+        await new Promise((r) => setTimeout(r, 150))
+        const next = await poll()
+        expect(next.selectionId).toMatch(/^[0-9a-f-]{36}$/)
+        expect(next.selectionId).not.toBe(shown.selectionId)
+        const other = { ...picked, cells: [] }
+        await postJson("/api/state", {
+            sessionId: id,
+            selectionId: next.selectionId,
+            selection: other,
+        })
+        expect(await second).toEqual(other)
+        shown = await poll()
+        expect(shown.selectionId).toBeNull()
+        expect(await readSelection("mcp-unknown-session", 100)).toBeNull()
+    })
 })
 
 describe("a session state recreated after it was lost", () => {
@@ -441,8 +661,419 @@ describe("preview page", () => {
             .map((m) => m[1])
             .join("\n")
         expect(scripts).toContain('const sessionId = "mcp-test-script";')
+        expect(scripts).toContain(`let API_TOKEN = "${getApiToken()}";`)
         expect(() => new Function(scripts)).not.toThrow()
     })
+
+    it("embeds the bundled draw.io from its own origin, else the external one", async () => {
+        expect(isSameOriginDrawio()).toBe(true)
+        const res = await request("/?mcp=mcp-test-origin")
+        expect(res.body).toContain('src="/drawio/index.html?embed=1&')
+        // The page takes its own origin for draw.io's messages
+        expect(res.body).toContain(
+            'const DRAWIO_ORIGIN = "" || location.origin;',
+        )
+
+        setDrawioDir(null)
+        try {
+            expect(isSameOriginDrawio()).toBe(false)
+            const external = await request("/?mcp=mcp-test-origin")
+            expect(external.body).toContain(
+                'src="https://embed.diagrams.net/?embed=1&',
+            )
+            expect(external.body).toContain(
+                'const DRAWIO_ORIGIN = "https://embed.diagrams.net" || location.origin;',
+            )
+        } finally {
+            setDrawioDir(drawioDir)
+        }
+    })
+
+    it("sends the security headers with the page, which is never cached", async () => {
+        const res = await request("/?mcp=mcp-test-headers")
+        expect(res.headers["content-security-policy"]).toBe(
+            "frame-ancestors 'self'",
+        )
+        expect(res.headers["x-content-type-options"]).toBe("nosniff")
+        // It holds the process's token
+        expect(res.headers["cache-control"]).toBe("no-store")
+    })
+})
+
+describe("API token", () => {
+    it("refuses an API request without the token, or with another one", async () => {
+        setState("mcp-token", "<mxfile>kept</mxfile>")
+        for (const headers of [
+            { "x-drawio-token": "" },
+            { "x-drawio-token": "0123456789abcdef0123456789abcdef" },
+        ]) {
+            const get = await request("/api/state?sessionId=mcp-token", {
+                headers,
+            })
+            expect(get.status).toBe(403)
+            const post = await postJson(
+                "/api/state",
+                { sessionId: "mcp-token", xml: "<mxfile>replaced</mxfile>" },
+                headers,
+            )
+            expect(post.status).toBe(403)
+            const history = await request("/api/history?sessionId=mcp-token", {
+                headers,
+            })
+            expect(history.status).toBe(403)
+        }
+        expect(getState("mcp-token")?.xml).toBe("<mxfile>kept</mxfile>")
+    })
+
+    it("is not needed for the page and the draw.io files", async () => {
+        const headers = { "x-drawio-token": "" }
+        expect((await request("/?mcp=mcp-token", { headers })).status).toBe(200)
+        expect((await request("/drawio/index.html", { headers })).status).toBe(
+            200,
+        )
+    })
+})
+
+describe("bundled draw.io files", () => {
+    it("serves a file with its MIME type, cache and nosniff headers", async () => {
+        const res = await request("/drawio/js/app.min.js")
+        expect(res.status).toBe(200)
+        expect(res.body).toBe("// app")
+        expect(res.headers["content-type"]).toBe(
+            "text/javascript; charset=utf-8",
+        )
+        // Revalidated on every use: the file names stay the same across
+        // draw.io versions, so a package upgrade must reach the browser
+        expect(res.headers["cache-control"]).toBe("no-cache")
+        expect(res.headers.etag).toMatch(/^"v1-[0-9a-f]+-[0-9a-f]+"$/)
+        expect(res.headers["x-content-type-options"]).toBe("nosniff")
+        expect(res.headers["content-security-policy"]).toBeUndefined()
+    })
+
+    it("changes the ETag with the draw.io version, whatever the file dates say", async () => {
+        // An install that keeps the archive's dates gives the upgraded file
+        // the same date and, here, the same size as before
+        const file = join(drawioDir, "js/same-size.js")
+        const date = new Date("2020-01-01T00:00:00Z")
+        writeFileSync(file, "// v1")
+        utimesSync(file, date, date)
+        const first = await request("/drawio/js/same-size.js")
+        writeFileSync(file, "// v2")
+        utimesSync(file, date, date)
+        writeFileSync(join(drawioDir, ".version"), "v2\n")
+        setDrawioDir(drawioDir)
+        try {
+            const again = await request("/drawio/js/same-size.js", {
+                headers: { "if-none-match": first.headers.etag as string },
+            })
+            expect(again.status).toBe(200)
+            expect(again.body).toBe("// v2")
+            expect(again.headers.etag).not.toBe(first.headers.etag)
+        } finally {
+            writeFileSync(join(drawioDir, ".version"), "v1\n")
+            setDrawioDir(drawioDir)
+            rmSync(file, { force: true })
+        }
+    })
+
+    it("answers 304 to a matching If-None-Match, and HEAD without a body", async () => {
+        const first = await request("/drawio/js/app.min.js")
+        const again = await request("/drawio/js/app.min.js", {
+            headers: { "if-none-match": first.headers.etag as string },
+        })
+        expect(again.status).toBe(304)
+        expect(again.body).toBe("")
+        expect(again.headers.etag).toBe(first.headers.etag)
+        const changed = await request("/drawio/js/app.min.js", {
+            headers: { "if-none-match": '"0-0"' },
+        })
+        expect(changed.status).toBe(200)
+        const head = await request("/drawio/js/app.min.js", {
+            method: "HEAD",
+        })
+        expect(head.status).toBe(200)
+        expect(head.body).toBe("")
+        expect(head.headers["content-length"]).toBe("6")
+    })
+
+    it("keeps running when a file cannot be read", async () => {
+        // Readable for stat, not for open (root reads anything: skipped)
+        if (process.getuid?.() === 0) return
+        const file = join(drawioDir, "js/locked.js")
+        writeFileSync(file, "// locked", { mode: 0o000 })
+        try {
+            // The connection is dropped (the headers may be out already)
+            const res = await request("/drawio/js/locked.js").catch(() => null)
+            expect(res?.body ?? "").toBe("")
+        } finally {
+            rmSync(file, { force: true })
+        }
+        const next = await request("/drawio/js/app.min.js")
+        expect(next.status).toBe(200)
+        expect(next.body).toBe("// app")
+    })
+
+    it("frames the editor page only from this origin", async () => {
+        const res = await request("/drawio/index.html")
+        expect(res.status).toBe(200)
+        expect(res.headers["content-type"]).toBe("text/html; charset=utf-8")
+        expect(res.headers["content-security-policy"]).toBe(
+            "frame-ancestors 'self'",
+        )
+    })
+
+    it("never serves the war's server-side parts or files outside the copy", async () => {
+        for (const path of [
+            "/drawio/WEB-INF/web.xml",
+            "/drawio/web-inf/web.xml",
+            "/drawio/js/../WEB-INF/web.xml",
+            "/drawio/META-INF/MANIFEST.MF",
+            "/drawio/../package.json",
+            "/drawio/%2e%2e/package.json",
+            "/drawio/js/%2e%2e/%2e%2e/package.json",
+            "/drawio/js/..%5c..%5cpackage.json",
+            "/drawio/",
+            "/drawio/js",
+            "/drawio/missing.js",
+        ]) {
+            const res = await request(path)
+            expect([403, 404], path).toContain(res.status)
+            expect(res.body).not.toContain("web-app")
+            expect(res.body).not.toContain('"name"')
+        }
+    })
+
+    it("answers 404 when no copy is bundled", async () => {
+        setDrawioDir(null)
+        try {
+            expect((await request("/drawio/index.html")).status).toBe(404)
+        } finally {
+            setDrawioDir(drawioDir)
+        }
+    })
+})
+
+describe("canvas shell page", () => {
+    /** The config the served page carries */
+    const configOf = (body: string) => {
+        const match = body.match(
+            /window\.__MCP_CONFIG__ = (\{.*?\});<\/script>/s,
+        )
+        if (!match) throw new Error(`no config in ${body}`)
+        return JSON.parse(match[1])
+    }
+
+    it("writes the session, the token and where draw.io comes from into the page", async () => {
+        const res = await request("/shell/?mcp=mcp-shell-page")
+        expect(res.status).toBe(200)
+        expect(res.headers["content-type"]).toBe("text/html; charset=utf-8")
+        expect(res.body).not.toContain("{{")
+        expect(configOf(res.body)).toEqual({
+            sessionId: "mcp-shell-page",
+            token: getApiToken(),
+            apiBase: "/api",
+            drawioBaseUrl: "/drawio/index.html",
+            drawioUi: "",
+            drawioLang: "",
+            drawioDark: "auto",
+            lang: "",
+        })
+        // The page creates the session, as the classic page does
+        expect(getState("mcp-shell-page")).toBeDefined()
+        // The same page at its index.html name
+        const index = await request("/shell/index.html?mcp=mcp-shell-page")
+        expect(index.status).toBe(200)
+        expect(configOf(index.body).sessionId).toBe("mcp-shell-page")
+    })
+
+    it("passes the host's editor settings on, in the shell's own terms", () => {
+        const config = shellConfig("mcp-s", {
+            DRAWIO_UI: "Sketch",
+            DRAWIO_LANG: "zh-Hant",
+            DRAWIO_DARK: "1",
+        })
+        expect(config.drawioUi).toBe("sketch")
+        expect(config.drawioLang).toBe("zh-tw")
+        expect(config.drawioDark).toBe("dark")
+        // The language as given, for the shell's own texts
+        expect(config.lang).toBe("zh-Hant")
+        expect(shellConfig("mcp-s", { DRAWIO_DARK: "light" }).drawioDark).toBe(
+            "light",
+        )
+        expect(shellConfig("mcp-s", { DRAWIO_UI: "dark" }).drawioDark).toBe(
+            "dark",
+        )
+        expect(shellConfig("mcp-s", { DRAWIO_UI: "neon" }).drawioUi).toBe("")
+    })
+
+    it("names the external draw.io when there is no bundled copy", async () => {
+        setDrawioDir(null)
+        try {
+            const res = await request("/shell/?mcp=mcp-shell-external")
+            expect(configOf(res.body).drawioBaseUrl).toBe(
+                "https://embed.diagrams.net/",
+            )
+        } finally {
+            setDrawioDir(drawioDir)
+        }
+    })
+
+    it("escapes a value that could close the script element", async () => {
+        const before = process.env.DRAWIO_LANG
+        process.env.DRAWIO_LANG = "</script><script>alert(1)</script>"
+        try {
+            const res = await request("/shell/?mcp=mcp-shell-escape")
+            expect(res.body).not.toContain("</script><script>alert")
+            expect(res.body).toContain("\\u003c/script>")
+            expect(configOf(res.body).lang).toBe(process.env.DRAWIO_LANG)
+        } finally {
+            if (before === undefined) delete process.env.DRAWIO_LANG
+            else process.env.DRAWIO_LANG = before
+        }
+    })
+
+    it("sends the security headers, is never cached and needs no token", async () => {
+        const res = await request("/shell/?mcp=mcp-shell-headers", {
+            headers: { "x-drawio-token": "" },
+        })
+        expect(res.status).toBe(200)
+        expect(res.headers["content-security-policy"]).toBe(
+            "frame-ancestors 'self'",
+        )
+        expect(res.headers["x-content-type-options"]).toBe("nosniff")
+        expect(res.headers["cache-control"]).toBe("no-store")
+    })
+
+    it("rejects a bad session id and goes to the most recent session without one", async () => {
+        const bad = await request(
+            `/shell/?mcp=${encodeURIComponent('";alert(1)//')}`,
+        )
+        expect(bad.status).toBe(400)
+        setState("mcp-shell-recent", "<mxfile>recent</mxfile>")
+        const res = await request("/shell/")
+        expect(res.status).toBe(302)
+        // (other tests of this file create sessions in the same millisecond)
+        expect(res.headers.location).toMatch(/^\/shell\/\?mcp=mcp-/)
+        // Without the trailing slash the assets would resolve elsewhere
+        const slash = await request("/shell?mcp=mcp-shell-recent")
+        expect(slash.status).toBe(302)
+        expect(slash.headers.location).toBe("/shell/?mcp=mcp-shell-recent")
+    })
+
+    it("serves the shell's files with their MIME types, without a token", async () => {
+        const js = await request("/shell/shell.js", {
+            headers: { "x-drawio-token": "" },
+        })
+        expect(js.status).toBe(200)
+        expect(js.body).toBe("// shell")
+        expect(js.headers["content-type"]).toBe(
+            "text/javascript; charset=utf-8",
+        )
+        expect(js.headers["x-content-type-options"]).toBe("nosniff")
+        expect(js.headers["cache-control"]).toBe("no-cache")
+        expect(js.headers.etag).toMatch(/^"\d+\.\d+\.\d+-[0-9a-f]+-[0-9a-f]+"$/)
+        const css = await request("/shell/shell.css")
+        expect(css.headers["content-type"]).toBe("text/css; charset=utf-8")
+        for (const path of [
+            "/shell/../package.json",
+            "/shell/%2e%2e/package.json",
+            "/shell/missing.js",
+        ]) {
+            const res = await request(path)
+            expect(res.status, path).toBe(404)
+            expect(res.body).not.toContain('"name"')
+        }
+    })
+
+    it("says so when the shell is not built", async () => {
+        setShellDir(null)
+        try {
+            const page = await request("/shell/?mcp=mcp-shell-unbuilt")
+            expect(page.status).toBe(404)
+            expect(page.body).toContain("npm run build")
+            expect((await request("/shell/shell.js")).status).toBe(404)
+        } finally {
+            setShellDir(shellDir)
+        }
+    })
+
+    it("is what start_session opens, unless DRAWIO_PREVIEW_UI=classic", () => {
+        expect(previewUiFromEnv({})).toBe("shell")
+        expect(previewUiFromEnv({ DRAWIO_PREVIEW_UI: "shell" })).toBe("shell")
+        expect(previewUiFromEnv({ DRAWIO_PREVIEW_UI: "classic" })).toBe(
+            "classic",
+        )
+        expect(previewUiFromEnv({ DRAWIO_PREVIEW_UI: "Classic" })).toBe(
+            "classic",
+        )
+        expect(previewUrl(6002, "mcp-x", "shell")).toBe(
+            "http://localhost:6002/shell/?mcp=mcp-x",
+        )
+        expect(previewUrl(6002, "mcp-x", "classic")).toBe(
+            "http://localhost:6002?mcp=mcp-x",
+        )
+        // Not built: the classic page, which works, rather than a 404; the
+        // tools that need the shell (get_selection) see the classic page too
+        expect(activePreviewUi("shell")).toBe("shell")
+        expect(activePreviewUi("classic")).toBe("classic")
+        setShellDir(null)
+        try {
+            expect(previewUrl(6002, "mcp-x", "shell")).toBe(
+                "http://localhost:6002?mcp=mcp-x",
+            )
+            expect(activePreviewUi("shell")).toBe("classic")
+        } finally {
+            setShellDir(shellDir)
+        }
+    })
+})
+
+describe("draw.io embed parameters from the host config", () => {
+    it("follows the system dark mode and fixes nothing else by default", () => {
+        expect(drawioEmbedParams({})).toBe("dark=auto")
+    })
+
+    it("turns dark mode on with the dark theme", () => {
+        // draw.io ignores ui=dark for dark mode once a dark parameter is sent
+        const params = drawioEmbedParams({ DRAWIO_UI: "dark" })
+        expect(params).toContain("dark=1")
+        expect(params).toContain("ui=dark")
+        // Unless the user asked for light mode
+        expect(drawioEmbedParams({ DRAWIO_UI: "dark", DRAWIO_DARK: "0" })).toBe(
+            "dark=0&ui=dark",
+        )
+    })
+
+    it("reads the theme in any case", () => {
+        expect(drawioEmbedParams({ DRAWIO_UI: "Dark" })).toBe("dark=1&ui=dark")
+    })
+
+    it("ignores a theme or language draw.io does not know", () => {
+        expect(drawioEmbedParams({ DRAWIO_UI: "neon" })).toBe("dark=auto")
+        expect(drawioEmbedParams({ DRAWIO_LANG: "en;drop" })).toBe("dark=auto")
+        expect(drawioEmbedParams({ DRAWIO_LANG: "english" })).toBe("dark=auto")
+    })
+
+    it("uses draw.io's name for Traditional Chinese", () => {
+        for (const value of ["zh-Hant", "zh-hant"]) {
+            expect(drawioEmbedParams({ DRAWIO_LANG: value })).toBe(
+                "dark=auto&lang=zh-tw",
+            )
+        }
+        expect(drawioEmbedParams({ DRAWIO_LANG: "ja" })).toBe(
+            "dark=auto&lang=ja",
+        )
+        // and "zh" for Simplified Chinese
+        expect(drawioEmbedParams({ DRAWIO_LANG: "zh-Hans" })).toBe(
+            "dark=auto&lang=zh",
+        )
+    })
+
+    it("reads dark mode in any spelling", () => {
+        expect(drawioEmbedParams({ DRAWIO_DARK: "TRUE" })).toBe("dark=1")
+        expect(drawioEmbedParams({ DRAWIO_DARK: "light" })).toBe("dark=0")
+        expect(drawioEmbedParams({ DRAWIO_DARK: "maybe" })).toBe("dark=auto")
+    })
 })
 
 describe("history restore", () => {
@@ -468,6 +1099,34 @@ describe("history restore", () => {
     const page = (cellId: string) =>
         `<mxfile><diagram id="p" name="P"><mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/><mxCell id="${cellId}" vertex="1" parent="1"/></root></mxGraphModel></diagram></mxfile>`
 
+    it("refuses a restore picked from a state the server has since lost", async () => {
+        const id = "mcp-history-stale-state"
+        setState(id, page("now"))
+        addHistory(id, page("old"))
+        const [entry] = getHistory(id)
+        const stale = await postJson("/api/restore", {
+            sessionId: id,
+            id: entry.id,
+            stateId: "a-lost-state",
+        })
+        expect(stale.status).toBe(409)
+        // A list taken before the tab knew the state
+        const unknown = await postJson("/api/restore", {
+            sessionId: id,
+            id: entry.id,
+            stateId: null,
+        })
+        expect(unknown.status).toBe(409)
+        expect(getState(id)?.xml).toBe(page("now"))
+        const fresh = await postJson("/api/restore", {
+            sessionId: id,
+            id: entry.id,
+            stateId: getState(id)?.stateId,
+        })
+        expect(fresh.status).toBe(200)
+        expect(getState(id)?.xml).toBe(page("old"))
+    })
+
     // A thumbnail the tab took after loading the server write at `version`
     const thumbnail = (id: string, svg: string, version: number) =>
         postJson("/api/history-svg", {
@@ -584,6 +1243,164 @@ describe("history restore", () => {
         // The missing image is filled in
         expect(getHistory(id)[0].svg).toBe("SVG")
     })
+})
+
+// What the shell's version cards read (the classic page uses index, id
+// and svg of the same list)
+describe("GET /api/history for the version cards", () => {
+    const page = (cellId: string) =>
+        `<mxfile><diagram id="p" name="P"><mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/><mxCell id="${cellId}" vertex="1" parent="1"/></root></mxGraphModel></diagram></mxfile>`
+
+    it("lists each entry's document, maker and first copy, with the state and the entry on the canvas", async () => {
+        const id = "mcp-history-cards"
+        addHistory(id, page("a"))
+        addHistory(id, page("b"), "SVG-B", "user")
+        setState(id, page("b"))
+        const res = await request(`/api/history?sessionId=${id}`)
+        expect(res.status).toBe(200)
+        const d = JSON.parse(res.body)
+        const [a, b] = getHistory(id)
+        expect(d.count).toBe(2)
+        expect(d.stateId).toBe(getState(id)?.stateId)
+        expect(d.currentId).toBe(b.id)
+        expect(d.entries[0]).toEqual({
+            index: 0,
+            id: a.id,
+            svg: "",
+            xml: page("a"),
+            source: null,
+            firstId: a.id,
+        })
+        expect(d.entries[1]).toMatchObject({
+            id: b.id,
+            svg: "SVG-B",
+            source: "user",
+            firstId: b.id,
+        })
+    })
+
+    it("gives the state a History key, which a hand edit changes once and a further one not at all", async () => {
+        // The shell reads History (every entry's XML and picture) again
+        // only when the key changes
+        const id = "mcp-history-key"
+        setState(id, page("a"))
+        addHistory(id, page("a"))
+        const [a] = getHistory(id)
+        const first = JSON.parse(
+            (await request(`/api/state?sessionId=${id}`)).body,
+        )
+        expect(first.historyKey).toBe(`1:${a.id}:${a.id}`)
+        // A hand edit: the canvas is at no entry now, History is the same
+        const push = await postJson("/api/state", {
+            sessionId: id,
+            xml: page("b"),
+            baseVersion: first.version,
+            stateId: first.stateId,
+        })
+        expect(push.status).toBe(200)
+        expect(JSON.parse(push.body).historyKey).toBe(`1:${a.id}:null`)
+        const again = await postJson("/api/state", {
+            sessionId: id,
+            xml: page("c"),
+            baseVersion: first.version + 1,
+            stateId: first.stateId,
+        })
+        expect(JSON.parse(again.body).historyKey).toBe(`1:${a.id}:null`)
+        const polled = JSON.parse(
+            (await request(`/api/state?sessionId=${id}`)).body,
+        )
+        expect(polled.historyKey).toBe(`1:${a.id}:null`)
+        // A write keeps the edit in History: the key names the new entry
+        keepInHistory(id, page("c"))
+        setState(id, page("d"))
+        addHistory(id, page("d"))
+        const [, c, d] = getHistory(id)
+        expect(c.xml).toBe(page("c"))
+        const after = JSON.parse(
+            (await request(`/api/state?sessionId=${id}`)).body,
+        )
+        expect(after.historyKey).toBe(`3:${d.id}:${d.id}`)
+    })
+
+    it("names the entry a restored copy stands for, and marks the copy as a restore", async () => {
+        const id = "mcp-history-cards-restore"
+        addHistory(id, page("a"))
+        addHistory(id, page("b"))
+        setState(id, page("b"))
+        const [a, b] = getHistory(id)
+        const restore = await postJson("/api/restore", {
+            sessionId: id,
+            id: a.id,
+            stateId: getState(id)?.stateId,
+        })
+        expect(restore.status).toBe(200)
+        const d = JSON.parse(
+            (await request(`/api/history?sessionId=${id}`)).body,
+        )
+        // History: a, b, a' (the copy); the canvas shows a's content
+        expect(d.entries.map((e: { firstId: number }) => e.firstId)).toEqual([
+            a.id,
+            b.id,
+            a.id,
+        ])
+        expect(d.entries[2].source).toBe("restore")
+        expect(d.currentId).toBe(d.entries[2].id)
+    })
+
+    it("marks the user's edit that a write replaces, and one that lost the race", async () => {
+        const id = "mcp-history-cards-user"
+        const version = setState(id, page("ai"))
+        addHistory(id, page("ai"))
+        // The user edits in the browser; the AI writes over it
+        await postJson("/api/state", {
+            sessionId: id,
+            xml: page("user"),
+            baseVersion: version,
+            stateId: getState(id)?.stateId,
+        })
+        keepInHistory(id, page("user"))
+        const ai2 = setState(id, page("ai2"))
+        addHistory(id, page("ai2"))
+        // A tab that had not loaded the write yet pushes another edit
+        await postJson("/api/state", {
+            sessionId: id,
+            xml: page("late"),
+            baseVersion: ai2 - 1,
+            stateId: getState(id)?.stateId,
+        })
+        const d = JSON.parse(
+            (await request(`/api/history?sessionId=${id}`)).body,
+        )
+        expect(
+            d.entries.map((e: { xml: string; source: string | null }) => [
+                e.xml === page("user")
+                    ? "user"
+                    : e.xml === page("late")
+                      ? "late"
+                      : "ai",
+                e.source,
+            ]),
+        ).toEqual([
+            ["ai", null],
+            ["user", "user"],
+            ["ai", null],
+            ["late", "user"],
+        ])
+        // The canvas shows the write, not an edit
+        expect(d.currentId).toBe(getHistory(id)[2].id)
+    })
+
+    it("reports no state and no current entry for a session it does not know", async () => {
+        const d = JSON.parse(
+            (await request("/api/history?sessionId=mcp-never-seen")).body,
+        )
+        expect(d).toEqual({
+            entries: [],
+            count: 0,
+            stateId: null,
+            currentId: null,
+        })
+    })
 
     // draw.io's own copy of a diagram, as a sync reply or an edit brings it
     const drawioCopy = (xml: string, attrs = 'pageWidth="850"') =>
@@ -664,6 +1481,32 @@ describe("history restore", () => {
         expect(getState(id)?.xml).toBe(doc("ai"))
         expect(getHistory(id).map((e) => e.xml)).toContain(doc("manual"))
     })
+
+    it("restoreHistoryEntry leaves the canvas alone for an unknown entry", () => {
+        const id = "mcp-restore-unknown"
+        setState(id, page("x"))
+        addHistory(id, page("x"))
+        expect(restoreHistoryEntry(id, 999999)).toBeNull()
+        expect(getState(id)?.xml).toBe(page("x"))
+        expect(getHistory(id)).toHaveLength(1)
+    })
+
+    it("restoreHistoryEntry restores an entry and keeps the canvas in History", () => {
+        const id = "mcp-restore-entry"
+        addHistory(id, page("old"))
+        const [entry] = getHistory(id)
+        // The canvas is a later state that is not in History yet
+        setState(id, page("ai"))
+
+        const newVersion = restoreHistoryEntry(id, entry.id)
+        expect(newVersion).toBe(getState(id)?.version)
+        expect(getState(id)?.xml).toBe(page("old"))
+        expect(getHistory(id).map((e) => e.xml)).toEqual([
+            page("old"),
+            page("ai"),
+            page("old"),
+        ])
+    })
 })
 
 describe("bodies over the size limit", () => {
@@ -682,6 +1525,7 @@ describe("bodies over the size limit", () => {
                         method: "POST",
                         headers: {
                             host: `localhost:${port}`,
+                            "x-drawio-token": getApiToken(),
                             "content-type": "application/json",
                         },
                     },

packages/mcp-server/tests/load-diagram.test.ts

@@ -19,6 +19,7 @@ beforeAll(() => {
 
 import {
     decompressPageContent,
+    extractSvgEmbeddedXml,
     parseDrawioFileContent,
 } from "../src/load-diagram.ts"
 
@@ -54,7 +55,11 @@ describe("decompressPageContent", () => {
 describe("parseDrawioFileContent", () => {
     it("passes a plain-XML mxfile through unchanged", () => {
         const r = parseDrawioFileContent(PLAIN_MXFILE)
-        expect(r).toEqual({ ok: true, xml: PLAIN_MXFILE })
+        expect(r).toEqual({
+            ok: true,
+            xml: PLAIN_MXFILE,
+            hadCompressedPages: false,
+        })
     })
 
     it("wraps a bare mxGraphModel into a one-page mxfile", () => {
@@ -103,7 +108,11 @@ describe("parseDrawioFileContent", () => {
     it("keeps empty pages as-is", () => {
         const withEmpty = `<mxfile><diagram id="a" name="Page-1">${MODEL_XML}</diagram><diagram id="b" name="Empty"></diagram></mxfile>`
         const r = parseDrawioFileContent(withEmpty)
-        expect(r).toEqual({ ok: true, xml: withEmpty })
+        expect(r).toEqual({
+            ok: true,
+            xml: withEmpty,
+            hadCompressedPages: false,
+        })
     })
 
     it("rejects empty files", () => {
@@ -112,11 +121,17 @@ describe("parseDrawioFileContent", () => {
     })
 
     it("rejects non-drawio content", () => {
-        const r = parseDrawioFileContent("<svg><rect/></svg>")
+        const r = parseDrawioFileContent("<html><body/></html>")
         expect(r.ok).toBe(false)
         if (!r.ok) expect(r.error).toContain("Not a draw.io file")
     })
 
+    it("rejects an SVG without an embedded diagram", () => {
+        const r = parseDrawioFileContent("<svg><rect/></svg>")
+        expect(r.ok).toBe(false)
+        if (!r.ok) expect(r.error).toContain("embedded diagram")
+    })
+
     it("rejects a page whose content is neither XML nor compressed", () => {
         const bad = `<mxfile><diagram id="a" name="Broken">!!! not a diagram !!!</diagram></mxfile>`
         const r = parseDrawioFileContent(bad)
@@ -124,3 +139,139 @@ describe("parseDrawioFileContent", () => {
         if (!r.ok) expect(r.error).toContain('"Broken"')
     })
 })
+
+describe("hadCompressedPages", () => {
+    it("is false for a plain-XML mxfile", () => {
+        const r = parseDrawioFileContent(PLAIN_MXFILE)
+        expect(r.ok).toBe(true)
+        if (r.ok) expect(r.hadCompressedPages).toBe(false)
+    })
+
+    it("is false for a bare mxGraphModel", () => {
+        const r = parseDrawioFileContent(MODEL_XML)
+        expect(r.ok).toBe(true)
+        if (r.ok) expect(r.hadCompressedPages).toBe(false)
+    })
+
+    it("is true for a fully compressed mxfile", () => {
+        const r = parseDrawioFileContent(COMPRESSED_MXFILE)
+        expect(r.ok).toBe(true)
+        if (r.ok) expect(r.hadCompressedPages).toBe(true)
+    })
+
+    it("is true for a mixed plain/compressed file", () => {
+        const mixed = `<mxfile><diagram id="a" name="Plain">${MODEL_XML}</diagram><diagram id="b" name="Squeezed">${drawioCompress(MODEL_XML)}</diagram></mxfile>`
+        const r = parseDrawioFileContent(mixed)
+        expect(r.ok).toBe(true)
+        if (r.ok) expect(r.hadCompressedPages).toBe(true)
+    })
+})
+
+/**
+ * Escape text for an XML attribute the way draw.io/Chromium serialise the
+ * diagram into the SVG root's content attribute.
+ */
+function escapeAttr(text: string): string {
+    return text
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/\n/g, "&#xa;")
+}
+
+/** Build a .drawio.svg (Editable SVG) with the given mxfile embedded. */
+function drawioSvg(mxfileXml: string): string {
+    return `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="200px" height="100px" viewBox="-0.5 -0.5 200 100" content="${escapeAttr(mxfileXml)}"><defs/><g><rect x="40" y="40" width="120" height="60" fill="#ffffff" stroke="#000000"/></g></svg>`
+}
+
+const SVG_PROLOG = `<?xml version="1.0" encoding="UTF-8"?>
+<!-- Do not edit this file with editors other than draw.io -->
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+`
+
+describe("extractSvgEmbeddedXml", () => {
+    it("returns undefined for non-SVG text", () => {
+        expect(extractSvgEmbeddedXml(PLAIN_MXFILE)).toBeUndefined()
+        expect(extractSvgEmbeddedXml("hello")).toBeUndefined()
+    })
+
+    it("returns an empty string for an SVG without content", () => {
+        expect(extractSvgEmbeddedXml("<svg><rect/></svg>")).toBe("")
+    })
+
+    it("returns the decoded content attribute", () => {
+        expect(extractSvgEmbeddedXml(drawioSvg(PLAIN_MXFILE))).toBe(
+            PLAIN_MXFILE,
+        )
+    })
+})
+
+describe("parseDrawioFileContent with .drawio.svg", () => {
+    it("loads a compressed one-page mxfile embedded in an SVG", () => {
+        const r = parseDrawioFileContent(drawioSvg(COMPRESSED_MXFILE))
+        expect(r.ok).toBe(true)
+        if (r.ok) {
+            expect(r.xml).toContain("<mxfile")
+            expect(r.xml).toContain("<mxGraphModel")
+            expect(r.xml).toContain('value="Hello"')
+            expect(r.xml).not.toContain("<svg")
+        }
+    })
+
+    it("accepts draw.io's XML declaration, comment and DOCTYPE prolog", () => {
+        const r = parseDrawioFileContent(
+            SVG_PROLOG + drawioSvg(COMPRESSED_MXFILE),
+        )
+        expect(r.ok).toBe(true)
+        if (r.ok) expect(r.xml).toContain('value="Hello"')
+    })
+
+    it("round-trips &quot; and &#xa; in an uncompressed embedded label", () => {
+        const model = MODEL_XML.replace(
+            'value="Hello"',
+            'value="say &quot;hi&quot;&#xa;next"',
+        )
+        // A pretty-printed file: the newline between tags becomes &#xa; in
+        // the SVG attribute, the label's entities become &amp;quot; etc.
+        const mxfile = `<mxfile host="app.diagrams.net">\n<diagram id="p1" name="Page-1">${model}</diagram>\n</mxfile>`
+        const svg = drawioSvg(mxfile)
+        expect(svg).toContain("&amp;quot;")
+        expect(svg).toContain("&amp;#xa;")
+        expect(svg).toContain("&gt;&#xa;&lt;diagram")
+
+        const r = parseDrawioFileContent(svg)
+        expect(r.ok).toBe(true)
+        if (r.ok) {
+            expect(r.xml).toContain('value="say &quot;hi&quot;&#xa;next"')
+            const doc = new DOMParser().parseFromString(r.xml, "text/xml")
+            const cell = doc.querySelector('mxCell[id="box1"]') as Element
+            expect(cell.getAttributeNode("value")?.value).toBe('say "hi"\nnext')
+        }
+    })
+
+    it("loads a two-page embedded mxfile as two pages", () => {
+        const twoPages = `<mxfile compressed="true"><diagram id="a" name="First">${drawioCompress(MODEL_XML)}</diagram><diagram id="b" name="Second">${drawioCompress(MODEL_XML.replace("Hello", "World"))}</diagram></mxfile>`
+        const r = parseDrawioFileContent(drawioSvg(twoPages))
+        expect(r.ok).toBe(true)
+        if (r.ok) {
+            const doc = new DOMParser().parseFromString(r.xml, "text/xml")
+            const diagrams = Array.from(
+                doc.querySelectorAll("diagram"),
+            ) as Element[]
+            expect(diagrams).toHaveLength(2)
+            for (const d of diagrams) {
+                expect(d.querySelector("mxGraphModel")).not.toBeNull()
+            }
+            expect(r.xml).toContain('value="World"')
+        }
+    })
+
+    it("rejects an SVG whose content is not draw.io XML", () => {
+        const r = parseDrawioFileContent(
+            '<svg xmlns="http://www.w3.org/2000/svg" content="hello"><rect/></svg>',
+        )
+        expect(r.ok).toBe(false)
+        if (!r.ok) expect(r.error).toContain("not draw.io XML")
+    })
+})

packages/mcp-server/tests/new-diagram.test.ts

@@ -0,0 +1,215 @@
+/**
+ * Tests for prepareNewDiagram's truncation check: output that stops inside an
+ * mxCell gets a clear error instead of one about the wrapper tags the model
+ * never sent.
+ */
+
+import { beforeAll, describe, expect, it } from "vitest"
+import { installDomPolyfill } from "../src/dom.ts"
+
+beforeAll(() => {
+    installDomPolyfill()
+})
+
+import {
+    isMxCellXmlComplete,
+    prepareNewDiagram,
+    truncatedCellError,
+} from "../src/new-diagram.ts"
+
+describe("isMxCellXmlComplete", () => {
+    it("returns false for empty/null input", () => {
+        expect(isMxCellXmlComplete("")).toBe(false)
+        expect(isMxCellXmlComplete(null)).toBe(false)
+        expect(isMxCellXmlComplete(undefined)).toBe(false)
+    })
+
+    it("returns true for self-closing mxCell", () => {
+        const xml =
+            '<mxCell id="2" value="Hello" style="rounded=1;" vertex="1" parent="1"/>'
+        expect(isMxCellXmlComplete(xml)).toBe(true)
+        // A raw "<" in a value (escaped later by the auto-fix)
+        expect(
+            isMxCellXmlComplete(
+                '<mxCell id="3" value="<b>Title</b>" style="text;html=1;" vertex="1" parent="1"/>',
+            ),
+        ).toBe(true)
+    })
+
+    it("returns true for mxCell with closing tag", () => {
+        const xml = `<mxCell id="2" value="Hello" vertex="1" parent="1">
+            <mxGeometry x="100" y="100" width="120" height="60" as="geometry"/>
+        </mxCell>`
+        expect(isMxCellXmlComplete(xml)).toBe(true)
+    })
+
+    it("returns false for truncated mxCell", () => {
+        const xml =
+            '<mxCell id="2" value="Hello" style="rounded=1;" vertex="1" parent'
+        expect(isMxCellXmlComplete(xml)).toBe(false)
+    })
+
+    it("returns false for mxCell with unclosed geometry", () => {
+        const xml = `<mxCell id="2" value="Hello" vertex="1" parent="1">
+            <mxGeometry x="100" y="100" width="120"`
+        expect(isMxCellXmlComplete(xml)).toBe(false)
+    })
+
+    it("returns false when output stops after a child of an open mxCell", () => {
+        const xml = `<mxCell id="2" value="A" vertex="1" parent="1">
+            <mxGeometry x="0" y="0" width="80" height="40" as="geometry"/>
+        </mxCell>
+        <mxCell id="3" value="B" vertex="1" parent="1">
+            <mxGeometry x="100" y="0" width="80" height="40" as="geometry"/>`
+        expect(isMxCellXmlComplete(xml)).toBe(false)
+    })
+
+    it("returns false when output stops after </mxGeometry> of an open mxCell", () => {
+        const xml = `<mxCell id="e1" edge="1" parent="1" source="2" target="3">
+            <mxGeometry relative="1" as="geometry">
+                <mxPoint x="10" y="10" as="sourcePoint"/>
+            </mxGeometry>`
+        expect(isMxCellXmlComplete(xml)).toBe(false)
+    })
+
+    it("returns true for a self-closing last mxCell with > in its value", () => {
+        const xml = `<mxCell id="2" value="A" vertex="1" parent="1">
+            <mxGeometry as="geometry"/>
+        </mxCell>
+        <mxCell id="3" value="A -> B" vertex="1" parent="1"/></root>`
+        expect(isMxCellXmlComplete(xml)).toBe(true)
+    })
+
+    it("returns true for multiple complete mxCells", () => {
+        const xml = `<mxCell id="2" value="A" vertex="1" parent="1"/>
+            <mxCell id="3" value="B" vertex="1" parent="1"/>`
+        expect(isMxCellXmlComplete(xml)).toBe(true)
+    })
+})
+
+describe("prepareNewDiagram with cut-off output", () => {
+    const A = `<mxCell id="2" value="A" vertex="1" parent="1"><mxGeometry x="0" y="0" width="80" height="40" as="geometry"/></mxCell>`
+
+    it("rejects a cell cut off inside an attribute", () => {
+        const cut = `${A}<mxCell id="3" value="B" vertex="1" par`
+        const out = prepareNewDiagram(cut)
+        expect(out.ok).toBe(false)
+        if (out.ok) return
+        expect(out.error).toContain("cut off")
+        // The tail is quoted so the model knows where to resume
+        expect(out.error).toContain('<mxCell id="3" value="B" vertex="1" par')
+        expect(out.error).toContain("edit_diagram add")
+    })
+
+    it("rejects a cell cut off after its geometry", () => {
+        const cut = `${A}<mxCell id="3" value="B" vertex="1" parent="1"><mxGeometry x="200" y="0" width="80" height="40" as="geometry"/>`
+        const out = prepareNewDiagram(cut)
+        expect(out.ok).toBe(false)
+        if (out.ok) return
+        expect(out.error).toContain("cut off")
+        expect(out.error).not.toContain("</root>")
+    })
+
+    it("quotes at most the last 300 characters", () => {
+        const cut = `${A}<mxCell id="3" value="${"x".repeat(400)}`
+        const out = prepareNewDiagram(cut)
+        expect(out.ok).toBe(false)
+        if (out.ok) return
+        expect(out.error).toContain(cut.slice(-300))
+        expect(out.error).not.toContain(cut.slice(-301))
+    })
+
+    it("does not report complete cells followed by an XML comment as cut", () => {
+        const cells = `${A}<!-- end of the diagram -->`
+        expect(truncatedCellError(cells)).toBeNull()
+        expect(prepareNewDiagram(cells).ok).toBe(true)
+    })
+
+    it("leaves a closing tag the auto-fix repairs to the auto-fix", () => {
+        // </mxCell/> is a typo, not a cut
+        const typo = A.replace("</mxCell>", "</mxCell/>")
+        expect(truncatedCellError(typo)).toBeNull()
+        expect(prepareNewDiagram(typo).ok).toBe(true)
+    })
+
+    it("leaves input without any cell to the validator", () => {
+        for (const input of ["", "Here is the diagram"]) {
+            expect(truncatedCellError(input)).toBeNull()
+            const out = prepareNewDiagram(input)
+            expect(out.ok).toBe(false)
+            if (!out.ok) expect(out.error).not.toContain("cut off")
+        }
+    })
+
+    it("never checks a full <mxfile>", () => {
+        const cut = `<mxfile><diagram id="p1" name="Page-1"><mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/><mxCell id="2" value="A" vertex="1" par`
+        expect(truncatedCellError(cut)).toBeNull()
+        const out = prepareNewDiagram(cut)
+        expect(out.ok).toBe(false)
+        if (out.ok) return
+        expect(out.error).not.toContain("cut off")
+    })
+})
+
+describe("truncation check with named styles and compact cells", () => {
+    const BLUE =
+        '<mxStyle name="blue" value="fillColor=#dae8fc;strokeColor=#6c8ebf;"/>\n'
+    const A =
+        '<mxCell id="2" value="A" style="blue;" x="0" y="0" w="80" h="40"/>\n'
+
+    it("accepts complete compact cells after the definitions and expands them", () => {
+        const out = prepareNewDiagram(
+            `${BLUE}${A}<mxCell id="3" value="B" style="blue;" x="120" y="0" w="80" h="40"/>`,
+        )
+        expect(out.ok).toBe(true)
+        if (!out.ok) return
+        expect(out.xml).toContain("fillColor=#dae8fc")
+        expect(out.xml).toContain("<mxGeometry")
+        expect(out.xml).not.toContain("<mxStyle")
+    })
+
+    it("reports a cut inside a compact cell that follows the definitions", () => {
+        const cut = `${BLUE}${A}<mxCell id="3" value="B" style="blue;" x="120" y="0" w="8`
+        const out = prepareNewDiagram(cut)
+        expect(out.ok).toBe(false)
+        if (out.ok) return
+        expect(out.error).toContain("cut off")
+        expect(out.error).toContain(
+            '<mxCell id="3" value="B" style="blue;" x="120" y="0" w="8',
+        )
+        expect(out.error).toContain("edit_diagram add")
+    })
+
+    it("reports output that stops right after the definitions and the first cells", () => {
+        const cut = `${BLUE}${A}<mxCell id="3" value="B" style="blue;"`
+        expect(isMxCellXmlComplete(cut)).toBe(false)
+        expect(truncatedCellError(cut)).toContain("cut off")
+    })
+
+    it("does not treat a compact cell's quote slip as a cut", () => {
+        const slip = `${A}<mxCell id="3" value="B" x="120" y="0" w="80" h="40/>`
+        expect(isMxCellXmlComplete(slip)).toBe(true)
+        expect(truncatedCellError(slip)).toBeNull()
+        const out = prepareNewDiagram(slip)
+        expect(out.ok).toBe(true)
+        if (out.ok) expect(out.xml).toContain('height="40"')
+    })
+
+    it("leaves definitions without any cell to the style check", () => {
+        expect(truncatedCellError(BLUE)).toBeNull()
+        const out = prepareNewDiagram(BLUE)
+        expect(out.ok).toBe(false)
+        if (out.ok) return
+        expect(out.error).not.toContain("cut off")
+        expect(out.error).toContain("no cells")
+    })
+
+    it("leaves an unclosed definition to the style check", () => {
+        const cut = `${BLUE}<mxStyle name="flow" value="edgeSt`
+        const out = prepareNewDiagram(cut)
+        expect(out.ok).toBe(false)
+        if (out.ok) return
+        expect(out.error).not.toContain("cut off")
+        expect(out.error).toContain("not closed")
+    })
+})

packages/mcp-server/tests/persistence.test.ts

@@ -9,6 +9,7 @@ import {
     readdirSync,
     readFileSync,
     rmSync,
+    statSync,
     utimesSync,
     writeFileSync,
 } from "node:fs"
@@ -16,6 +17,7 @@ import { homedir, tmpdir } from "node:os"
 import { join } from "node:path"
 import { afterEach, beforeAll, describe, expect, it } from "vitest"
 import { installDomPolyfill } from "../src/dom.ts"
+import type { HistorySource } from "../src/history.ts"
 import { Autosaver, defaultDataDir } from "../src/persistence.ts"
 
 beforeAll(() => {
@@ -84,10 +86,14 @@ describe("Autosaver", () => {
             writeFileSync(join(dir, `${id}.drawio`), DIAGRAM)
             utimesSync(join(dir, `${id}.drawio`), 1000 + i, 1000 + i)
         }
+        // A session's History file goes with its diagram
+        writeFileSync(join(dir, "mcp-mgd0a1b2-old123.history.json"), "[]")
+        writeFileSync(join(dir, "mcp-mgd0a1b3-mid456.history.json"), "[]")
         saver.schedule("mcp-mgd0a1b4-new789", DIAGRAM)
         saver.flush()
         expect(readdirSync(dir).sort()).toEqual([
             "mcp-mgd0a1b3-mid456.drawio",
+            "mcp-mgd0a1b3-mid456.history.json",
             "mcp-mgd0a1b4-new789.drawio",
             "mcp-notes.drawio",
             "mcp-system-design-v2.drawio",
@@ -188,9 +194,228 @@ describe("Autosaver", () => {
     it("does nothing when saving is off", () => {
         const saver = new Autosaver(null)
         expect(saver.pathFor("mcp-x")).toBeNull()
+        expect(saver.historyPathFor("mcp-x")).toBeNull()
+        expect(saver.loadHistory("mcp-x")).toEqual([])
         saver.schedule("mcp-x", DIAGRAM)
         saver.flush()
     })
+
+    it("lists every session file newest first, hand-named ones included", () => {
+        const dir = tempDir()
+        const saver = new Autosaver(dir, 10)
+        const names = [
+            "mcp-mgd0a1b2-old123.drawio",
+            "mine.drawio",
+            "mcp-notes.drawio",
+            "mcp-readme.txt",
+            "mcp-mgd0a1b3-new456.drawio",
+        ]
+        for (const [i, name] of names.entries()) {
+            writeFileSync(join(dir, name), DIAGRAM)
+            utimesSync(join(dir, name), 1000 + i, 1000 + i)
+        }
+        expect(saver.dataDir()).toBe(dir)
+        expect(saver.list()).toEqual([
+            {
+                sessionId: "mcp-mgd0a1b3-new456",
+                path: join(dir, "mcp-mgd0a1b3-new456.drawio"),
+                savedAt: new Date(1004 * 1000),
+            },
+            {
+                sessionId: "mcp-notes",
+                path: join(dir, "mcp-notes.drawio"),
+                savedAt: new Date(1002 * 1000),
+            },
+            {
+                sessionId: "mcp-mgd0a1b2-old123",
+                path: join(dir, "mcp-mgd0a1b2-old123.drawio"),
+                savedAt: new Date(1000 * 1000),
+            },
+        ])
+    })
+
+    it("lists nothing when saving is off or the folder does not exist", () => {
+        const off = new Autosaver(null)
+        expect(off.dataDir()).toBeNull()
+        expect(off.list()).toEqual([])
+        expect(new Autosaver(join(tempDir(), "missing")).list()).toEqual([])
+    })
+})
+
+describe("Autosaver History", () => {
+    const V1 = DIAGRAM.replace('id="a"', 'id="v1"')
+    const V2 = DIAGRAM.replace('id="a"', 'id="v2"')
+    const V3 = DIAGRAM.replace('id="a"', 'id="v3"')
+    // One session's History entries, as history.ts keeps them (the saver
+    // leaves the thumbnails out)
+    const withHistory = (
+        dir: string,
+        entries: { id: number; xml: string; source?: HistorySource }[],
+    ) => new Autosaver(dir, 30, 50, () => entries)
+
+    it("saves the XML of the History entries next to the diagram", async () => {
+        const dir = tempDir()
+        const entries = [
+            { id: 0, xml: V1 },
+            { id: 1, xml: V2 },
+        ]
+        const saver = withHistory(dir, entries)
+        const path = saver.historyPathFor("mcp-h") as string
+        expect(path).toBe(join(dir, "mcp-h.history.json"))
+        saver.schedule("mcp-h", V2)
+        expect(existsSync(path)).toBe(false)
+        await sleep(80)
+        expect(JSON.parse(readFileSync(path, "utf-8"))).toEqual([
+            { xml: V1 },
+            { xml: V2 },
+        ])
+        expect(saver.loadHistory("mcp-h")).toEqual([{ xml: V1 }, { xml: V2 }])
+        expect(readdirSync(dir).sort()).toEqual([
+            "mcp-h.drawio",
+            "mcp-h.history.json",
+        ])
+    })
+
+    it("saves a diagram cleared before its first save, with its History", () => {
+        const dir = tempDir()
+        const saver = withHistory(dir, [{ id: 0, xml: V1 }])
+        saver.schedule("mcp-cleared", BLANK)
+        saver.flush()
+        expect(
+            readFileSync(saver.pathFor("mcp-cleared") as string, "utf-8"),
+        ).toBe(BLANK)
+        expect(saver.loadHistory("mcp-cleared")).toEqual([{ xml: V1 }])
+    })
+
+    it("still skips a blank page whose History holds only blank pages", () => {
+        const dir = tempDir()
+        const saver = withHistory(dir, [{ id: 0, xml: BLANK }])
+        saver.schedule("mcp-empty", BLANK)
+        saver.flush()
+        expect(readdirSync(dir)).toEqual([])
+    })
+
+    it("writes the History again after the cap removed it", () => {
+        const dir = tempDir()
+        const entries = [{ id: 0, xml: V1 }]
+        const saver = new Autosaver(dir, 10, 1, () => entries)
+        const old = "mcp-aaaaaaaa-old"
+        saver.schedule(old, V1)
+        saver.flush()
+        utimesSync(saver.pathFor(old) as string, 1000, 1000)
+        // A newer session pushes the old one out
+        saver.schedule("mcp-aaaaaaab-new", V1)
+        saver.flush()
+        expect(existsSync(saver.historyPathFor(old) as string)).toBe(false)
+        // The old session is still open and saves again, History unchanged
+        saver.schedule(old, V1)
+        saver.flush()
+        expect(saver.loadHistory(old)).toEqual([{ xml: V1 }])
+    })
+
+    it("rewrites the History file only when the entries changed", () => {
+        const dir = tempDir()
+        const entries = [{ id: 0, xml: V1 }]
+        const saver = withHistory(dir, entries)
+        saver.schedule("mcp-same", V1)
+        saver.flush()
+        const path = saver.historyPathFor("mcp-same") as string
+        utimesSync(path, 1000, 1000)
+        const old = statSync(path).mtimeMs
+
+        // draw.io's own autosave of an unchanged diagram
+        saver.schedule("mcp-same", V1)
+        saver.flush()
+        expect(statSync(path).mtimeMs).toBe(old)
+
+        entries.push({ id: 1, xml: V2 })
+        saver.schedule("mcp-same", V2)
+        saver.flush()
+        expect(statSync(path).mtimeMs).not.toBe(old)
+        expect(saver.loadHistory("mcp-same")).toEqual([
+            { xml: V1 },
+            { xml: V2 },
+        ])
+
+        // The circular buffer dropped the oldest entry: same length, new id
+        entries.shift()
+        entries.push({ id: 2, xml: V3 })
+        saver.schedule("mcp-same", V3)
+        saver.flush()
+        expect(saver.loadHistory("mcp-same")).toEqual([
+            { xml: V2 },
+            { xml: V3 },
+        ])
+    })
+
+    it("writes no History file while there are no entries", () => {
+        const dir = tempDir()
+        const saver = withHistory(dir, [])
+        saver.schedule("mcp-empty", DIAGRAM)
+        saver.flush()
+        expect(readdirSync(dir)).toEqual(["mcp-empty.drawio"])
+    })
+
+    it("reads [] for a missing or malformed History file", () => {
+        const dir = tempDir()
+        const saver = new Autosaver(dir, 10)
+        const path = saver.historyPathFor("mcp-bad") as string
+        expect(saver.loadHistory("mcp-bad")).toEqual([])
+        for (const content of [
+            "{not json",
+            '{"a":1}',
+            "[1, 2]",
+            '"x"',
+            '[{"source":"user"}]',
+        ]) {
+            writeFileSync(path, content)
+            expect(saver.loadHistory("mcp-bad")).toEqual([])
+        }
+    })
+
+    it("reads the History files of earlier versions, which hold the XML alone", () => {
+        const dir = tempDir()
+        const saver = new Autosaver(dir, 10)
+        writeFileSync(
+            saver.historyPathFor("mcp-old") as string,
+            JSON.stringify([V1, V2]),
+        )
+        expect(saver.loadHistory("mcp-old")).toEqual([{ xml: V1 }, { xml: V2 }])
+    })
+
+    it("keeps who made each entry, so the shell's cards look the same after a restart", () => {
+        // A clear of the canvas and a restore of it: without the source, the
+        // restored copy would show as a second clear
+        const dir = tempDir()
+        const saver = withHistory(dir, [
+            { id: 0, xml: V1 },
+            { id: 1, xml: BLANK, source: "user" },
+            { id: 2, xml: V2, source: "restore" },
+            { id: 3, xml: V1, source: "recover" },
+        ])
+        saver.schedule("mcp-who", V1)
+        saver.flush()
+        expect(saver.loadHistory("mcp-who")).toEqual([
+            { xml: V1 },
+            { xml: BLANK, source: "user" },
+            { xml: V2, source: "restore" },
+            { xml: V1, source: "recover" },
+        ])
+        // A source the server does not know is left out
+        writeFileSync(
+            saver.historyPathFor("mcp-who") as string,
+            JSON.stringify([{ xml: V1, source: "robot" }]),
+        )
+        expect(saver.loadHistory("mcp-who")).toEqual([{ xml: V1 }])
+    })
+
+    it("flush() writes the History on shutdown", () => {
+        const dir = tempDir()
+        const saver = withHistory(dir, [{ id: 0, xml: V1 }])
+        saver.schedule("mcp-exit", V1)
+        saver.flush()
+        expect(saver.loadHistory("mcp-exit")).toEqual([{ xml: V1 }])
+    })
 })
 
 describe("defaultDataDir", () => {

packages/mcp-server/tests/selection.test.ts

@@ -0,0 +1,165 @@
+import { describe, expect, it } from "vitest"
+import {
+    describeSelection,
+    MAX_LISTED_CELLS,
+    parseSelectionAnswer,
+    type SelectionAnswer,
+} from "../src/selection.ts"
+
+const page = { pageId: "p1", pageName: "Flow" }
+
+describe("get_selection text", () => {
+    it("lists shapes with their geometry and edges with their ends", () => {
+        const text = describeSelection(
+            {
+                ...page,
+                cells: [
+                    {
+                        id: "3",
+                        label: "Login",
+                        edge: false,
+                        geometry: { x: 100, y: 100, width: 120, height: 60 },
+                    },
+                    {
+                        id: "7",
+                        label: "",
+                        edge: false,
+                        geometry: { x: 20, y: 30, width: 80, height: 40 },
+                        parent: "box",
+                    },
+                    {
+                        id: "5",
+                        label: "yes",
+                        edge: true,
+                        source: "3",
+                        target: "4",
+                    },
+                    { id: "9", label: "", edge: true },
+                ],
+            },
+            null,
+        )
+        expect(text).toContain(
+            '4 cells selected on page "Flow" (page_id="p1"):',
+        )
+        expect(text).toContain(
+            '- id="3" shape "Login" at x=100 y=100 w=120 h=60',
+        )
+        expect(text).toContain(
+            '- id="7" shape (no label) at x=20 y=30 w=80 h=40 inside "box"',
+        )
+        expect(text).toContain('- id="5" edge "yes" from "3" to "4"')
+        expect(text).toContain('- id="9" edge (no label) (not connected)')
+        expect(text).toContain('edit_diagram (page_id="p1")')
+    })
+
+    it("details the first cells of a large selection and lists the rest by id", () => {
+        const cells = (n: number) =>
+            Array.from({ length: n }, (_, i) => ({
+                id: `c${i + 1}`,
+                label: `Cell ${i + 1}`,
+                edge: false,
+                geometry: { x: i, y: 0, width: 10, height: 10 },
+            }))
+        const text = describeSelection(
+            { ...page, cells: cells(MAX_LISTED_CELLS + 5) },
+            null,
+        )
+        expect(text).toContain(`${MAX_LISTED_CELLS + 5} cells selected`)
+        expect(text).toContain(`id="c${MAX_LISTED_CELLS}"`)
+        // No detail past the cap, but every id: the model acts on all of
+        // them, and get_diagram cannot tell which cells were selected
+        expect(text).not.toContain(`id="c${MAX_LISTED_CELLS + 1}"`)
+        expect(text).not.toContain(`shape "Cell ${MAX_LISTED_CELLS + 1}"`)
+        expect(text).toContain(
+            `- and 5 more cells, listed by id only: "c${MAX_LISTED_CELLS + 1}", "c${MAX_LISTED_CELLS + 2}", "c${MAX_LISTED_CELLS + 3}", "c${MAX_LISTED_CELLS + 4}", "c${MAX_LISTED_CELLS + 5}"`,
+        )
+        const exact = describeSelection(
+            { ...page, cells: cells(MAX_LISTED_CELLS) },
+            null,
+        )
+        expect(exact).not.toContain("more cells")
+    })
+
+    it("says clearly when nothing is selected", () => {
+        const text = describeSelection({ ...page, cells: [] }, null)
+        expect(text).toBe(
+            'Nothing is selected on page "Flow" (page_id="p1"). Ask the user to select the shapes they mean in the preview, or call get_diagram.',
+        )
+        expect(
+            describeSelection(
+                { pageId: null, pageName: null, cells: [] },
+                null,
+            ),
+        ).toContain("Nothing is selected on the page on screen.")
+    })
+
+    it("names the external draw.io when the page cannot read the editor", () => {
+        const unavailable: SelectionAnswer = {
+            pageId: null,
+            pageName: null,
+            cells: [],
+            unavailable: true,
+        }
+        expect(
+            describeSelection(unavailable, "https://embed.diagrams.net"),
+        ).toBe(
+            "The preview loads draw.io from https://embed.diagrams.net (another origin), where the selection cannot be read. Ask the user which shapes they mean, or call get_diagram.",
+        )
+        // Same origin, but the bridge did not attach (a draw.io change)
+        expect(describeSelection(unavailable, null)).toContain(
+            "could not read the editor's selection",
+        )
+    })
+})
+
+describe("the page's selection answer", () => {
+    it("takes the fields it knows and drops malformed cells", () => {
+        expect(
+            parseSelectionAnswer({
+                pageId: "p1",
+                pageName: "Flow",
+                cells: [
+                    {
+                        id: "3",
+                        label: "Login",
+                        edge: false,
+                        geometry: { x: 1, y: 2, width: 3, height: 4 },
+                        parent: "box",
+                        style: "ignored",
+                    },
+                    { id: "5", edge: true, source: "3", target: 4 },
+                    { id: "", label: "no id" },
+                    "not a cell",
+                    { id: "8", geometry: { x: "1", y: 2 } },
+                ],
+            }),
+        ).toEqual({
+            pageId: "p1",
+            pageName: "Flow",
+            cells: [
+                {
+                    id: "3",
+                    label: "Login",
+                    edge: false,
+                    geometry: { x: 1, y: 2, width: 3, height: 4 },
+                    parent: "box",
+                },
+                { id: "5", label: "", edge: true, source: "3" },
+                { id: "8", label: "", edge: false },
+            ],
+        })
+    })
+
+    it("keeps the unavailable mark and refuses other shapes", () => {
+        expect(parseSelectionAnswer({ unavailable: true })).toEqual({
+            pageId: null,
+            pageName: null,
+            cells: [],
+            unavailable: true,
+        })
+        expect(parseSelectionAnswer({ cells: "3,4" })).toBeNull()
+        expect(parseSelectionAnswer("3")).toBeNull()
+        expect(parseSelectionAnswer(null)).toBeNull()
+    })
+})

packages/mcp-server/tests/server-wiring.test.ts

@@ -9,11 +9,14 @@
  * package before testing). Running from source via tsx means it executes as
  * part of the normal `vitest run`.
  *
- * We deliberately do NOT call start_session — it would open a real browser
- * window via open(). The browser bridge is covered by the Playwright e2e suite.
+ * start_session is called only at the end, with BROWSER=none so no browser
+ * window opens, for the tools that need a session but no preview tab. The
+ * browser bridge is covered by the Playwright e2e suite.
  */
 
 import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process"
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
 import path from "node:path"
 import { fileURLToPath } from "node:url"
 import { afterAll, beforeAll, describe, expect, it } from "vitest"
@@ -42,11 +45,23 @@ const EXPECTED_TOOLS = [
     "get_drawing_guide",
     "get_shape_library",
     "screenshot_diagram",
+    "get_selection",
+    "list_saved_diagrams",
+    "restore_version",
 ]
 
+// Auto-save folder of the spawned server, holding one saved session
+const dataDir = mkdtempSync(path.join(tmpdir(), "mcp-wiring-"))
+const SAVED_ID = "mcp-aaaaaaaa-bbb"
+const SAVED_DIAGRAM = `<mxfile><diagram id="p" name="Flow"><mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/><mxCell id="a" vertex="1" parent="1"/></root></mxGraphModel></diagram></mxfile>`
+
 // Claude Code truncates tool descriptions and server instructions here
 const MAX_DESCRIPTION = 2048
 
+// The server reads <DRAWIO_DATA_DIR>/instructions.md into the guide; a
+// developer's real ~/.next-ai-drawio/instructions.md must not leak in
+const CUSTOM_RULE = "Always use blue fill #dae8fc."
+
 let proc: ChildProcessWithoutNullStreams
 let stdoutBuf = ""
 const pending = new Map<
@@ -72,8 +87,19 @@ function send(method: string, params: unknown, isNotification = false) {
 }
 
 beforeAll(async () => {
+    writeFileSync(path.join(dataDir, "instructions.md"), CUSTOM_RULE)
+    writeFileSync(path.join(dataDir, `${SAVED_ID}.drawio`), SAVED_DIAGRAM)
     proc = spawn(tsxBin, [entry], {
         stdio: ["pipe", "pipe", "pipe"],
+        env: {
+            ...process.env,
+            DRAWIO_DATA_DIR: dataDir,
+            // For the session tests at the end: no browser window, the
+            // default preview (the canvas shell), a port away from other
+            // servers
+            BROWSER: "none",
+            PORT: String(6500 + Math.floor(Math.random() * 400)),
+        },
     }) as ChildProcessWithoutNullStreams
 
     proc.stdout.on("data", (chunk: Buffer) => {
@@ -111,6 +137,7 @@ beforeAll(async () => {
 
 afterAll(() => {
     proc?.kill("SIGTERM")
+    rmSync(dataDir, { recursive: true, force: true })
 })
 
 describe("MCP server wiring", () => {
@@ -136,6 +163,40 @@ describe("MCP server wiring", () => {
         expect(props.page_index).toBeTruthy()
     })
 
+    it("advertises session_id on start_session", async () => {
+        const resp = await send("tools/list", {})
+        const start = resp.result.tools.find(
+            (t: { name: string }) => t.name === "start_session",
+        )
+        expect(start?.inputSchema?.properties?.session_id).toBeTruthy()
+        expect(start?.inputSchema?.required ?? []).not.toContain("session_id")
+    })
+
+    it("lists the saved diagrams with their pages, without a session", async () => {
+        const resp = await send("tools/call", {
+            name: "list_saved_diagrams",
+            arguments: {},
+        })
+        expect(resp.result.isError).toBeFalsy()
+        const text: string = resp.result.content[0].text
+        const line = text.split("\n").find((l) => l.startsWith(SAVED_ID))
+        expect(line, text).toBeTruthy()
+        expect(line).toContain("pages: Flow (3 cells)")
+        expect(line).toContain(path.join(dataDir, `${SAVED_ID}.drawio`))
+        expect(line).not.toContain("(current)")
+    })
+
+    it("advertises screenshot on create_new_diagram and edit_diagram", async () => {
+        const resp = await send("tools/list", {})
+        for (const name of ["create_new_diagram", "edit_diagram"]) {
+            const tool = resp.result.tools.find(
+                (t: { name: string }) => t.name === name,
+            )
+            const props = tool?.inputSchema?.properties ?? {}
+            expect(props.screenshot?.type, `${name} screenshot`).toBe("boolean")
+        }
+    })
+
     it("advertises name/id/xml on add_page", async () => {
         const resp = await send("tools/list", {})
         const addPage = resp.result.tools.find(
@@ -147,6 +208,32 @@ describe("MCP server wiring", () => {
         expect(props.xml).toBeTruthy()
     })
 
+    it("advertises steps_back on restore_version", async () => {
+        const resp = await send("tools/list", {})
+        const restore = resp.result.tools.find(
+            (t: { name: string }) => t.name === "restore_version",
+        )
+        expect(restore?.inputSchema?.properties?.steps_back).toBeTruthy()
+    })
+
+    it("refuses restore_version without a session", async () => {
+        const resp = await send("tools/call", {
+            name: "restore_version",
+            arguments: {},
+        })
+        expect(resp.result.isError).toBe(true)
+        expect(resp.result.content[0].text).toContain("start_session")
+    })
+
+    it("refuses get_selection without a session", async () => {
+        const resp = await send("tools/call", {
+            name: "get_selection",
+            arguments: {},
+        })
+        expect(resp.result.isError).toBe(true)
+        expect(resp.result.content[0].text).toContain("start_session")
+    })
+
     it("keeps every description and the instructions within the host limit", async () => {
         const resp = await send("tools/list", {})
         for (const tool of resp.result.tools) {
@@ -185,6 +272,119 @@ describe("MCP server wiring", () => {
         })
         const text: string = resp.result.content[0].text
         expect(text).toContain("Edge routing rules")
+        expect(text).toContain("do not describe the diagram")
+        expect(text).toContain("clear the canvas")
         expect(text.length).toBeLessThanOrEqual(15000)
     })
+
+    it("appends the user's instructions.md to the drawing guide", async () => {
+        const resp = await send("tools/call", {
+            name: "get_drawing_guide",
+            arguments: {},
+        })
+        const text: string = resp.result.content[0].text
+        expect(
+            text.endsWith(`\n\n## Custom Instructions\n${CUSTOM_RULE}`),
+        ).toBe(true)
+    })
+
+    it("advertises topic on get_drawing_guide", async () => {
+        const resp = await send("tools/list", {})
+        const guide = resp.result.tools.find(
+            (t: { name: string }) => t.name === "get_drawing_guide",
+        )
+        expect(guide?.inputSchema?.properties?.topic).toBeTruthy()
+    })
+
+    it("serves the table XML reference with topic=tables", async () => {
+        const resp = await send("tools/call", {
+            name: "get_drawing_guide",
+            arguments: { topic: "tables" },
+        })
+        expect(resp.result.isError).toBeFalsy()
+        const text: string = resp.result.content[0].text
+        expect(text).toContain("shape=table")
+        expect(text).not.toContain("Edge routing rules")
+    })
+})
+
+describe("load_diagram dual-source arguments", () => {
+    it("advertises both optional 'path' and 'xml' sources", async () => {
+        const resp = await send("tools/list", {})
+        const load = resp.result.tools.find(
+            (t: { name: string }) => t.name === "load_diagram",
+        )
+        const props = load?.inputSchema?.properties ?? {}
+        expect(props.path).toBeTruthy()
+        expect(props.xml).toBeTruthy()
+        const required: string[] = load?.inputSchema?.required ?? []
+        expect(required).not.toContain("path")
+        expect(required).not.toContain("xml")
+    })
+
+    it("rejects passing both 'path' and 'xml'", async () => {
+        // Argument validation fires before the session check: no session
+        // exists in this harness, so a both-args call must report the
+        // mutual-exclusion error, not "No active session".
+        const resp = await send("tools/call", {
+            name: "load_diagram",
+            arguments: { path: "/tmp/x.drawio", xml: "<mxfile/>" },
+        })
+        expect(resp.error, JSON.stringify(resp.error)).toBeUndefined()
+        expect(resp.result?.isError).toBe(true)
+        expect(resp.result?.content?.[0]?.text).toContain("not both")
+    })
+
+    it("rejects passing neither 'path' nor 'xml'", async () => {
+        const resp = await send("tools/call", {
+            name: "load_diagram",
+            arguments: {},
+        })
+        expect(resp.result?.isError).toBe(true)
+        expect(resp.result?.content?.[0]?.text).toContain("either 'path'")
+    })
+
+    it("accepts 'xml' alone as a source (fails only on the missing session)", async () => {
+        const resp = await send("tools/call", {
+            name: "load_diagram",
+            arguments: {
+                xml: '<mxfile><diagram id="p" name="P"><mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/></root></mxGraphModel></diagram></mxfile>',
+            },
+        })
+        expect(resp.result?.isError).toBe(true)
+        expect(resp.result?.content?.[0]?.text).toContain("No active session")
+    })
+})
+
+// After the tests above: start_session makes a session current
+describe("MCP server wiring with a session, without a preview tab", () => {
+    it("get_selection says the preview tab is not connected", async () => {
+        const started = await send("tools/call", {
+            name: "start_session",
+            arguments: {},
+        })
+        expect(started.result.isError).toBeFalsy()
+        expect(started.result.content[0].text).toContain("Browser URL:")
+        const resp = await send("tools/call", {
+            name: "get_selection",
+            arguments: {},
+        })
+        // Without the built shell (tests run before the build on CI and on
+        // a fresh clone) start_session opens the classic page, which cannot
+        // answer a selection request; the tool says so instead of waiting
+        const shellBuilt = existsSync(
+            path.join(__dirname, "../dist/shell/index.html"),
+        )
+        if (shellBuilt) {
+            expect(resp.result.isError).toBe(true)
+            expect(resp.result.content[0].text).toBe(
+                "Error: The preview tab is not open, or has not connected yet.",
+            )
+        } else {
+            expect(resp.result.isError).toBeFalsy()
+            expect(resp.result.content[0].text).toContain(
+                "classic preview page cannot read the selection",
+            )
+        }
+    })
 })

packages/mcp-server/tests/wrap-cells.test.ts

@@ -146,6 +146,24 @@ describe("reservedIdError", () => {
 })
 
 describe("prepareNewDiagram", () => {
+    it("gives every <diagram> without an id one, so the server and draw.io name the same pages", () => {
+        // draw.io makes up an id for a page without one, which the server
+        // never sees; get_selection would then name a page edit_diagram
+        // cannot find
+        const out = prepareNewDiagram(
+            `<mxfile><diagram name="One"><mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/></root></mxGraphModel></diagram><diagram name="Two" id="kept"><mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/></root></mxGraphModel></diagram></mxfile>`,
+        )
+        expect(out.ok).toBe(true)
+        if (!out.ok) return
+        const ids = [...out.xml.matchAll(/<diagram\b[^>]*\bid="([^"]*)"/g)].map(
+            (m) => m[1],
+        )
+        expect(ids).toHaveLength(2)
+        expect(ids[0]).toMatch(/^[a-z0-9]+-[a-z0-9]+$/)
+        expect(ids[1]).toBe("kept")
+        expect(out.xml).toContain('name="One"')
+    })
+
     it("rejects a shape that uses a root cell id", () => {
         // It would clash with the added root cell "1" and be renamed,
         // which breaks the edges that point to it
@@ -164,6 +182,15 @@ describe("prepareNewDiagram", () => {
         )
         expect(out.ok).toBe(true)
     })
+
+    it("accepts the root cells alone as a blank page", () => {
+        const out = prepareNewDiagram(
+            `<mxCell id="0"/><mxCell id="1" parent="0"/>`,
+        )
+        expect(out.ok).toBe(true)
+        if (!out.ok) return
+        expect(hasCells(out.xml)).toBe(false)
+    })
 })
 
 describe("labels that look like attributes", () => {

packages/mcp-server/tests/xml-reference.test.ts

@@ -0,0 +1,58 @@
+/**
+ * The XML references returned by get_drawing_guide with a topic. Each
+ * snippet must be accepted by create_new_diagram as bare mxCell elements;
+ * whether draw.io renders it as intended is checked by hand.
+ */
+
+import { beforeAll, describe, expect, it } from "vitest"
+import { installDomPolyfill } from "../src/dom.ts"
+
+beforeAll(() => {
+    installDomPolyfill()
+})
+
+import { prepareNewDiagram } from "../src/new-diagram.ts"
+import { hasCells } from "../src/pages.ts"
+import { XML_REFERENCE } from "../src/xml-reference.ts"
+
+/** The code block of a reference: the lines indented by four spaces. */
+function snippet(topic: keyof typeof XML_REFERENCE): string {
+    return XML_REFERENCE[topic]
+        .split("\n")
+        .filter((line) => line.startsWith("    "))
+        .map((line) => line.slice(4))
+        .join("\n")
+}
+
+describe("XML_REFERENCE", () => {
+    it.each(["tables", "layers", "groups"] as const)(
+        "%s snippet passes prepareNewDiagram",
+        (topic) => {
+            const xml = snippet(topic)
+            expect(xml).toContain("<mxCell")
+            const result = prepareNewDiagram(xml)
+            expect(result.ok, result.ok ? "" : result.error).toBe(true)
+            if (result.ok) expect(result.fixes).toEqual([])
+        },
+    )
+
+    it("tables use draw.io's table shapes", () => {
+        const xml = snippet("tables")
+        expect(xml).toContain("shape=table;")
+        expect(xml).toContain("shape=tableRow;")
+        expect(xml).toContain("shape=partialRectangle;")
+    })
+
+    it('layers keep the layer cell with parent="0"', () => {
+        const result = prepareNewDiagram(snippet("layers"))
+        expect(result.ok).toBe(true)
+        if (!result.ok) return
+        expect(hasCells(result.xml)).toBe(true)
+        expect(result.xml).toContain('id="L2"')
+        expect(result.xml).toContain('parent="L2"')
+    })
+
+    it("groups use a group container", () => {
+        expect(snippet("groups")).toContain('style="group"')
+    })
+})

public/favicon-white.svg

@@ -1,37 +0,0 @@
-<?xml version="1.0" standalone="no"?>
-<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20010904//EN"
- "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
-<svg version="1.0" xmlns="http://www.w3.org/2000/svg"
- width="1536.000000pt" height="1536.000000pt" viewBox="0 0 1536.000000 1536.000000"
- preserveAspectRatio="xMidYMid meet">
-<g transform="translate(0.000000,1536.000000) scale(0.100000,-0.100000)"
-fill="#ffffff" stroke="none">
-<path d="M2765 14404 c-100 -29 -181 -58 -225 -82 -227 -125 -359 -296 -431
--560 -19 -70 -19 -108 -19 -1175 0 -1068 1 -1104 20 -1172 58 -206 159 -356
-319 -474 71 -53 199 -121 226 -121 9 0 26 -5 38 -12 12 -6 62 -19 112 -29 85
--17 207 -18 2219 -19 1172 0 2133 -3 2138 -8 4 -4 7 -246 6 -538 l-3 -529
--2330 -5 c-2506 -6 -2373 -3 -2470 -54 -61 -31 -150 -113 -194 -178 -87 -128
--82 -77 -90 -1025 l-6 -838 -360 -6 c-292 -4 -368 -8 -405 -21 -194 -68 -303
--177 -373 -372 l-22 -61 1 -2887 c1 -2716 2 -2890 18 -2935 56 -153 161 -276
-286 -334 126 -59 0 -54 1400 -54 1394 0 1290 -4 1410 53 95 45 198 148 242
-241 62 133 58 -93 58 3026 0 2992 1 2883 -40 2990 -59 156 -183 272 -360 337
--25 9 -146 14 -440 18 l-405 5 0 540 0 540 2020 3 c1111 1 2030 0 2043 -3 l22
--5 -2 -538 -3 -537 -380 -6 c-312 -4 -388 -8 -426 -21 -195 -68 -326 -204
--383 -399 -15 -51 -16 -295 -16 -2921 0 -2778 1 -2867 19 -2920 36 -104 72
--167 134 -230 75 -78 115 -105 222 -151 l50 -22 1219 -3 c672 -1 1255 1 1300
-6 109 12 217 63 298 140 73 69 107 118 144 208 l29 69 3 2880 c2 2687 1 2884
--15 2945 -48 183 -188 332 -373 398 -37 13 -114 17 -430 21 l-385 6 -3 534
-c-2 421 0 536 10 543 7 4 925 8 2039 8 1718 0 2028 -2 2038 -14 8 -10 11 -154
-11 -531 -1 -284 -4 -523 -7 -531 -4 -12 -69 -14 -392 -14 -354 0 -391 -2 -448
--20 -168 -52 -282 -148 -353 -295 -22 -45 -40 -91 -40 -103 0 -11 -5 -33 -10
--47 -7 -18 -10 -988 -10 -2875 0 -2393 2 -2858 14 -2902 43 -167 148 -298 293
--369 57 -27 107 -44 151 -50 88 -11 2429 -11 2508 0 210 31 416 238 445 450 6
-39 8 1245 7 2926 -3 2713 -4 2862 -21 2900 -41 93 -74 150 -110 191 -46 52
--149 134 -169 134 -8 0 -19 5 -24 10 -6 6 -42 19 -80 30 -63 18 -100 20 -415
-20 -307 0 -348 2 -353 16 -3 9 -6 390 -6 848 0 797 -1 834 -19 886 -31 87 -50
-118 -111 183 -66 70 -141 119 -221 144 -50 16 -228 18 -2389 23 l-2335 5 0
-535 0 535 2165 5 c1191 3 2170 8 2176 12 6 4 35 12 65 17 201 35 435 198 539
-376 55 93 82 153 110 245 19 63 20 94 20 1167 0 1047 -1 1106 -19 1180 -70
-290 -275 523 -539 613 -160 54 232 50 -5028 49 -4182 0 -4856 -2 -4899 -15z"/>
-</g>
-</svg>

resources/favicon.svg

@@ -0,0 +1,16 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024">
+  <title>Next AI Draw.io</title>
+  <!-- Web icon, source of public/favicon.ico, app/favicon.ico and public/favicon-*.png.
+       The tile fills the canvas so the icon stays large in browser tabs. -->
+  <rect x="4" y="4" width="1016" height="1016" rx="228" fill="#ffffff" stroke="#dfe3e8" stroke-width="8"/>
+  <g transform="translate(512 512) scale(0.76) translate(-512 -438)" fill="#14181d">
+    <rect x="140" y="62" width="744" height="244" rx="56"/>
+    <rect x="478" y="300" width="68" height="224"/>
+    <rect x="142" y="378" width="740" height="68" rx="14"/>
+    <rect x="142" y="378" width="68" height="146" rx="14"/>
+    <rect x="814" y="378" width="68" height="146" rx="14"/>
+    <rect x="62" y="518" width="228" height="296" rx="40"/>
+    <rect x="398" y="518" width="228" height="296" rx="40"/>
+    <rect x="734" y="518" width="228" height="296" rx="40"/>
+  </g>
+</svg>

resources/icon.svg

@@ -0,0 +1,18 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024">
+  <title>Next AI Draw.io</title>
+  <!-- Desktop app icon, source of resources/icon.png (1024x1024).
+       The tile is 824px wide on the 1024 canvas, following the macOS icon grid. -->
+  <g transform="translate(100 100) scale(0.8046875)">
+    <rect x="4" y="4" width="1016" height="1016" rx="228" fill="#ffffff" stroke="#dfe3e8" stroke-width="8"/>
+    <g transform="translate(512 512) scale(0.66) translate(-512 -438)" fill="#14181d">
+      <rect x="140" y="62" width="744" height="244" rx="56"/>
+      <rect x="478" y="300" width="68" height="224"/>
+      <rect x="142" y="378" width="740" height="68" rx="14"/>
+      <rect x="142" y="378" width="68" height="146" rx="14"/>
+      <rect x="814" y="378" width="68" height="146" rx="14"/>
+      <rect x="62" y="518" width="228" height="296" rx="40"/>
+      <rect x="398" y="518" width="228" height="296" rx="40"/>
+      <rect x="734" y="518" width="228" height="296" rx="40"/>
+    </g>
+  </g>
+</svg>

scripts/drawio-zip.mjs

@@ -0,0 +1,67 @@
+/**
+ * Shared by the two draw.io fetch scripts (the web app's scripts/fetch-drawio.mjs
+ * and packages/mcp-server/scripts/fetch-drawio.mjs): the pinned release and a
+ * minimal reader for its draw.war zip file, so no extra dependency is needed.
+ */
+import crypto from "node:crypto"
+import fs from "node:fs"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+import zlib from "node:zlib"
+
+// Pinned because the UI relies on draw.io internals; bump deliberately. The
+// web app and the MCP server embed the same release.
+const VERSION_FILE = path.join(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "../packages/mcp-server/src/drawio-version.json",
+)
+
+/** { version, sha256, downloadUrl } of the pinned draw.war */
+export function readDrawioVersion() {
+    return JSON.parse(fs.readFileSync(VERSION_FILE, "utf8"))
+}
+
+export function sha256(buf) {
+    return crypto.createHash("sha256").update(buf).digest("hex")
+}
+
+// Minimal zip reader: finds the central directory and inflates each entry
+export function* readZipEntries(buf) {
+    const EOCD_SIG = 0x06054b50
+    let eocd = -1
+    for (let i = buf.length - 22; i >= Math.max(0, buf.length - 65557); i--) {
+        if (buf.readUInt32LE(i) === EOCD_SIG) {
+            eocd = i
+            break
+        }
+    }
+    if (eocd < 0) throw new Error("Not a zip file (end record not found)")
+
+    const count = buf.readUInt16LE(eocd + 10)
+    let offset = buf.readUInt32LE(eocd + 16)
+
+    for (let n = 0; n < count; n++) {
+        if (buf.readUInt32LE(offset) !== 0x02014b50) {
+            throw new Error("Corrupt zip central directory")
+        }
+        const method = buf.readUInt16LE(offset + 10)
+        const compressedSize = buf.readUInt32LE(offset + 20)
+        const nameLength = buf.readUInt16LE(offset + 28)
+        const extraLength = buf.readUInt16LE(offset + 30)
+        const commentLength = buf.readUInt16LE(offset + 32)
+        const localOffset = buf.readUInt32LE(offset + 42)
+        const name = buf.toString("utf8", offset + 46, offset + 46 + nameLength)
+        offset += 46 + nameLength + extraLength + commentLength
+
+        const localNameLength = buf.readUInt16LE(localOffset + 26)
+        const localExtraLength = buf.readUInt16LE(localOffset + 28)
+        const start = localOffset + 30 + localNameLength + localExtraLength
+        const raw = buf.subarray(start, start + compressedSize)
+
+        if (name.endsWith("/")) continue
+        if (method !== 0 && method !== 8) {
+            throw new Error(`Unsupported zip compression ${method} (${name})`)
+        }
+        yield { name, data: method === 8 ? zlib.inflateRawSync(raw) : raw }
+    }
+}

scripts/fetch-drawio.mjs

@@ -13,11 +13,10 @@
  * The release asset (draw.war) is a zip file; it is unpacked with node:zlib
  * so no extra dependency is needed.
  */
-import crypto from "node:crypto"
 import fs from "node:fs"
 import path from "node:path"
-import zlib from "node:zlib"
 import nextEnv from "@next/env"
+import { readDrawioVersion, readZipEntries, sha256 } from "./drawio-zip.mjs"
 
 // npm runs this before Next reads the .env files, so read them here: an
 // external draw.io set in .env.local must skip the download too
@@ -26,14 +25,15 @@ nextEnv.loadEnvConfig(
     process.env.npm_lifecycle_event === "predev",
 )
 
-// Pinned because the UI relies on draw.io internals; bump both deliberately
-const DRAWIO_VERSION = "v32.0.2"
-// SHA-256 of that release's draw.war, as GitHub lists it
-const DRAWIO_SHA256 =
-    "3cb8abec8e9bfc7504760c9cdc9194ecf7e8de178aa2a1d668801c32ecf1a1a7"
+// The pinned release and the SHA-256 of its draw.war, as GitHub lists it
+// (packages/mcp-server/src/drawio-version.json, shared with the MCP server)
+const {
+    version: DRAWIO_VERSION,
+    sha256: DRAWIO_SHA256,
+    downloadUrl: DOWNLOAD_URL,
+} = readDrawioVersion()
 const DEST = path.join(process.cwd(), "public", "drawio")
 const STAMP = path.join(DEST, ".version")
-const DOWNLOAD_URL = `https://github.com/jgraph/drawio/releases/download/${DRAWIO_VERSION}/draw.war`
 
 function log(message) {
     console.log(`[fetch-drawio] ${message}`)
@@ -47,47 +47,6 @@ function readStamp() {
     }
 }
 
-// Minimal zip reader: finds the central directory and inflates each entry
-function* readZipEntries(buf) {
-    const EOCD_SIG = 0x06054b50
-    let eocd = -1
-    for (let i = buf.length - 22; i >= Math.max(0, buf.length - 65557); i--) {
-        if (buf.readUInt32LE(i) === EOCD_SIG) {
-            eocd = i
-            break
-        }
-    }
-    if (eocd < 0) throw new Error("Not a zip file (end record not found)")
-
-    const count = buf.readUInt16LE(eocd + 10)
-    let offset = buf.readUInt32LE(eocd + 16)
-
-    for (let n = 0; n < count; n++) {
-        if (buf.readUInt32LE(offset) !== 0x02014b50) {
-            throw new Error("Corrupt zip central directory")
-        }
-        const method = buf.readUInt16LE(offset + 10)
-        const compressedSize = buf.readUInt32LE(offset + 20)
-        const nameLength = buf.readUInt16LE(offset + 28)
-        const extraLength = buf.readUInt16LE(offset + 30)
-        const commentLength = buf.readUInt16LE(offset + 32)
-        const localOffset = buf.readUInt32LE(offset + 42)
-        const name = buf.toString("utf8", offset + 46, offset + 46 + nameLength)
-        offset += 46 + nameLength + extraLength + commentLength
-
-        const localNameLength = buf.readUInt16LE(localOffset + 26)
-        const localExtraLength = buf.readUInt16LE(localOffset + 28)
-        const start = localOffset + 30 + localNameLength + localExtraLength
-        const raw = buf.subarray(start, start + compressedSize)
-
-        if (name.endsWith("/")) continue
-        if (method !== 0 && method !== 8) {
-            throw new Error(`Unsupported zip compression ${method} (${name})`)
-        }
-        yield { name, data: method === 8 ? zlib.inflateRawSync(raw) : raw }
-    }
-}
-
 async function main() {
     if (process.env.NEXT_PUBLIC_DRAWIO_BASE_URL) {
         log("NEXT_PUBLIC_DRAWIO_BASE_URL is set, skipping the bundled copy")
@@ -102,7 +61,7 @@ async function main() {
         if (!res.ok) throw new Error(`HTTP ${res.status} for ${DOWNLOAD_URL}`)
         buf = Buffer.from(await res.arrayBuffer())
         // The copy runs on the app's own origin: it must be the real release
-        const actual = crypto.createHash("sha256").update(buf).digest("hex")
+        const actual = sha256(buf)
         if (actual !== DRAWIO_SHA256) {
             throw new Error(`draw.war checksum mismatch (got ${actual})`)
         }

scripts/prepare-electron-build.mjs

@@ -87,7 +87,7 @@ console.log("Copying static files...")
 const targetStaticDir = join(targetDir, ".next", "static")
 copyDereferenced(staticDir, targetStaticDir)
 
-// Copy public folder (required for favicon-white.svg and other assets)
+// Copy public folder (required for favicons and other assets)
 console.log("Copying public folder...")
 const publicDir = join(rootDir, "public")
 const targetPublicDir = join(targetDir, "public")

stores/canvas-store.ts

@@ -30,6 +30,9 @@ interface CanvasState {
     isFreehand: boolean
     /** One of draw.io's menus or dialogs is open over the canvas */
     isDrawioPopupOpen: boolean
+    /** Something is changing the canvas (an answer streams in, a sync
+     * runs): version actions and "ask AI" wait */
+    isBusy: boolean
     set: (partial: Partial<Omit<CanvasState, "set">>) => void
 }
 
@@ -41,5 +44,6 @@ export const useCanvasStore = create<CanvasState>((set) => ({
     selectionRect: null,
     isFreehand: false,
     isDrawioPopupOpen: false,
+    isBusy: false,
     set: (partial) => set(partial),
 }))