ci: ignore generated SVG assets in Biome

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

.github/workflows/auto-format.yml

@@ -23,7 +23,9 @@ jobs:
           node-version: '24'
 
       - name: Run Biome format
-        run: npx @biomejs/biome@latest check --write --no-errors-on-unmatched .
+        # Pin to the version in package.json so CI matches local/pre-commit
+        # (npx @latest drifts — e.g. 2.5.0 broke this job on unrelated PRs).
+        run: npx @biomejs/[email protected] check --write --no-errors-on-unmatched .
 
       - name: Check for changes
         id: changes

.github/workflows/docker-build.yml

@@ -58,6 +58,8 @@ jobs:
         with:
           context: .
           push: ${{ github.event_name != 'pull_request' }}
+          provenance: mode=max
+          sbom: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
           cache-from: type=gha
@@ -89,4 +91,3 @@ jobs:
           docker pull ghcr.io/${REPO_LOWER}:latest
           docker tag ghcr.io/${REPO_LOWER}:latest ${{ secrets.AWS_ACCOUNT_ID }}.dkr.ecr.ap-northeast-1.amazonaws.com/next-ai-draw-io:latest
           docker push ${{ secrets.AWS_ACCOUNT_ID }}.dkr.ecr.ap-northeast-1.amazonaws.com/next-ai-draw-io:latest
-

.github/workflows/publish-mcp.yml

@@ -0,0 +1,67 @@
+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;
+# 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:
+  push:
+    branches:
+      - main
+    paths:
+      - "packages/mcp-server/**"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write # OIDC token for npm trusted publishing
+
+concurrency:
+  group: publish-mcp
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: packages/mcp-server
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: "npm"
+          cache-dependency-path: packages/mcp-server/package-lock.json
+          registry-url: "https://registry.npmjs.org"
+
+      # Trusted publishing requires npm >= 11.5.1
+      - name: Update npm
+        run: npm install -g npm@latest
+
+      - name: Check if version is already published
+        id: version
+        run: |
+          LOCAL=$(node -p "require('./package.json').version")
+          if npm view "@next-ai-drawio/mcp-server@${LOCAL}" version >/dev/null 2>&1; then
+            echo "Version ${LOCAL} already on npm - nothing to publish"
+            echo "publish=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "Version ${LOCAL} not on npm - publishing"
+            echo "publish=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Install dependencies
+        if: steps.version.outputs.publish == 'true'
+        run: npm ci
+
+      - name: Test
+        if: steps.version.outputs.publish == 'true'
+        run: npm test
+
+      - name: Publish to npm
+        if: steps.version.outputs.publish == 'true'
+        run: npm publish

.github/workflows/test.yml

@@ -28,6 +28,16 @@ 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.
+      - name: Install MCP server dependencies
+        run: npm --prefix packages/mcp-server ci
+
+      - name: Run MCP server unit tests
+        run: npm --prefix packages/mcp-server test
+
   e2e:
     name: E2E Tests
     runs-on: ubuntu-latest

README.md

@@ -211,6 +211,7 @@ See the [Next.js deployment documentation](https://nextjs.org/docs/app/building-
 -   Azure OpenAI
 -   Ollama
 -   OpenRouter
+-   AIHubMix
 -   DeepSeek
 -   SiliconFlow
 -   ModelScope
@@ -224,7 +225,7 @@ All providers except AWS Bedrock and OpenRouter support custom endpoints.
 
 ### Server-Side Multi-Model Configuration
 
-Administrators can configure multiple server-side models that are available to all users without requiring personal API keys. Configure via `AI_MODELS_CONFIG` environment variable (JSON string) or `ai-models.json` file.
+Administrators can configure multiple server-side models that are available to all users without requiring personal API keys. Configure via `AI_MODELS_CONFIG` environment variable (JSON string) or `ai-models.json` file. For a single-provider quick setup, list comma-separated model IDs in `AI_MODEL`.
 
 ### Admin Panel
 

app/api/aihubmix-models/route.ts

@@ -0,0 +1,61 @@
+import { NextResponse } from "next/server"
+import {
+    AIHUBMIX_MODELS_ENDPOINT,
+    extractAihubmixModelIds,
+} from "@/lib/aihubmix-models"
+import { SUGGESTED_MODELS } from "@/lib/types/model-config"
+
+const SUCCESS_CACHE_CONTROL =
+    "public, max-age=300, s-maxage=3600, stale-while-revalidate=86400"
+
+function fallbackResponse() {
+    return NextResponse.json(
+        {
+            models: SUGGESTED_MODELS.aihubmix || [],
+            source: "fallback",
+        },
+        {
+            headers: {
+                "Cache-Control": "no-store",
+            },
+        },
+    )
+}
+
+export async function GET() {
+    try {
+        const response = await fetch(AIHUBMIX_MODELS_ENDPOINT, {
+            next: { revalidate: 3600 },
+        })
+
+        if (!response.ok) {
+            console.warn(
+                `[aihubmix-models] Failed to fetch models: ${response.status}`,
+            )
+            return fallbackResponse()
+        }
+
+        const payload = await response.json()
+        const models = extractAihubmixModelIds(payload)
+
+        if (models.length === 0) {
+            console.warn("[aihubmix-models] Model list response was empty")
+            return fallbackResponse()
+        }
+
+        return NextResponse.json(
+            {
+                models,
+                source: "aihubmix",
+            },
+            {
+                headers: {
+                    "Cache-Control": SUCCESS_CACHE_CONTROL,
+                },
+            },
+        )
+    } catch (error) {
+        console.warn("[aihubmix-models] Failed to load models:", error)
+        return fallbackResponse()
+    }
+}

app/api/chat/route.ts

@@ -15,7 +15,6 @@ import { z } from "zod"
 import {
     getAIModel,
     SINGLE_SYSTEM_PROVIDERS,
-    supportsImageInput,
     supportsPromptCaching,
 } from "@/lib/ai-providers"
 import { findCachedResponse } from "@/lib/cached-responses"
@@ -266,16 +265,10 @@ async function handleChatRequest(req: Request): Promise<Response> {
         lastUserMessage?.parts?.filter((part: any) => part.type === "file") ||
         []
 
-    // Check if user is sending images to a model that doesn't support them
-    // AI SDK silently drops unsupported parts, so we need to catch this early
-    if (fileParts.length > 0 && !supportsImageInput(modelId)) {
-        return Response.json(
-            {
-                error: `The model "${modelId}" does not support image input. Please use a vision-capable model (e.g., GPT-4o, Claude, Gemini) or remove the image.`,
-            },
-            { status: 400 },
-        )
-    }
+    // Note: we used to pre-emptively reject images for models we guessed were
+    // text-only (by name matching). That heuristic misfired on newer models
+    // (see issue #874), so we now let the request through and surface the real
+    // provider error if the model genuinely can't accept images.
 
     // User input only - XML is now in a separate cached system message
     const formattedUserInput = `User input:

app/api/parse-url/route.ts

@@ -1,4 +1,4 @@
-import { extract } from "@extractus/article-extractor"
+import { extractFromHtml } from "@extractus/article-extractor"
 import { NextResponse } from "next/server"
 import TurndownService from "turndown"
 import { isPrivateUrl } from "@/lib/ssrf-protection"
@@ -7,6 +7,31 @@ const MAX_CONTENT_LENGTH = 150000 // Match PDF limit
 const EXTRACT_TIMEOUT_MS = 15000
 const USER_AGENT = "Mozilla/5.0 (compatible; NextAIDrawio/1.0)"
 
+// Detect the page's charset so non-UTF-8 pages (Shift_JIS/GBK/EUC/Big5, common
+// on CJK sites) are decoded correctly. Response.text() always assumes UTF-8 and
+// would produce mojibake; the article-extractor library does the same detection
+// when it fetches the page itself, which we no longer rely on.
+function detectCharset(
+    contentType: string | null,
+    buffer: ArrayBuffer,
+): string {
+    // 1. HTTP Content-Type header charset (most authoritative).
+    const headerCharset = contentType?.match(/charset=([^;]+)/i)?.[1]?.trim()
+    // 2. <meta charset> / <meta http-equiv> in the first bytes of the document.
+    const head = new TextDecoder("utf-8").decode(buffer.slice(0, 4096))
+    const metaCharset =
+        head.match(/<meta[^>]+charset=["']?\s*([\w-]+)/i)?.[1] ||
+        head.match(/<meta[^>]+content=["'][^"']*charset=([\w-]+)/i)?.[1]
+    const charset = (headerCharset || metaCharset || "utf-8").toLowerCase()
+    // TextDecoder throws on unknown encoding labels; fall back to UTF-8.
+    try {
+        new TextDecoder(charset)
+        return charset
+    } catch {
+        return "utf-8"
+    }
+}
+
 export async function POST(req: Request) {
     try {
         const { url } = await req.json()
@@ -31,21 +56,31 @@ export async function POST(req: Request) {
         // SSRF protection: parse-url has no use case for fetching internal
         // hosts, so private URLs are always rejected. ALLOW_PRIVATE_URLS only
         // governs LLM provider baseUrl overrides (validate-model, chat).
-        if (isPrivateUrl(url)) {
+        if (await isPrivateUrl(url)) {
             return NextResponse.json(
                 { error: "Cannot access private/internal URLs" },
                 { status: 400 },
             )
         }
-        const headController = new AbortController()
-        const headTimeout = setTimeout(() => headController.abort(), 3000)
+        // Fetch the page ourselves so we control redirect handling. The
+        // article-extractor library follows redirects internally and ignores a
+        // `redirect` option, which would let a public URL 302 to an internal
+        // host and bypass the SSRF check above. `redirect: "error"` rejects any
+        // redirect outright.
+        const controller = new AbortController()
+        const timeoutId = setTimeout(() => {
+            controller.abort()
+        }, EXTRACT_TIMEOUT_MS)
+
+        let html: string
         try {
-            const headResponse = await fetch(url, {
-                method: "HEAD",
+            const response = await fetch(url, {
                 headers: { "User-Agent": USER_AGENT },
-                signal: headController.signal,
+                redirect: "error",
+                signal: controller.signal,
             })
-            const contentType = headResponse.headers.get("content-type")
+
+            const contentType = response.headers.get("content-type")
             if (contentType?.includes("application/pdf")) {
                 return NextResponse.json(
                     {
@@ -54,27 +89,17 @@ export async function POST(req: Request) {
                     { status: 422 },
                 )
             }
-        } catch (err) {
-            console.warn(
-                "HEAD pre-check failed, proceeding with extraction:",
-                err,
-            )
-        } finally {
-            clearTimeout(headTimeout)
-        }
 
-        // Extract article content with timeout to avoid tying up server resources
-        const controller = new AbortController()
-        const timeoutId = setTimeout(() => {
-            controller.abort()
-        }, EXTRACT_TIMEOUT_MS)
+            if (!response.ok) {
+                return NextResponse.json(
+                    { error: "Could not fetch URL content" },
+                    { status: 400 },
+                )
+            }
 
-        let article
-        try {
-            article = await extract(url, undefined, {
-                headers: { "User-Agent": USER_AGENT },
-                signal: controller.signal,
-            })
+            const buffer = await response.arrayBuffer()
+            const charset = detectCharset(contentType, buffer)
+            html = new TextDecoder(charset).decode(buffer)
         } catch (err: any) {
             if (err?.name === "AbortError") {
                 return NextResponse.json(
@@ -82,11 +107,25 @@ export async function POST(req: Request) {
                     { status: 504 },
                 )
             }
-            throw err
+            // Redirects are rejected with a TypeError ("failed to fetch" /
+            // "unexpected redirect") when redirect: "error" is set.
+            return NextResponse.json(
+                { error: "Could not fetch URL content" },
+                { status: 400 },
+            )
         } finally {
             clearTimeout(timeoutId)
         }
 
+        // extractFromHtml throws (not returns null) on empty/non-HTML bodies,
+        // so map any parse error to the same 400 as the no-content case.
+        let article: Awaited<ReturnType<typeof extractFromHtml>>
+        try {
+            article = await extractFromHtml(html, url)
+        } catch {
+            article = null
+        }
+
         if (!article || !article.content) {
             return NextResponse.json(
                 { error: "Could not extract content from URL" },

app/api/validate-model/route.ts

@@ -5,11 +5,16 @@ import { createGateway } from "@ai-sdk/gateway"
 import { createGoogleGenerativeAI } from "@ai-sdk/google"
 import { createVertex } from "@ai-sdk/google-vertex"
 import { createOpenAI } from "@ai-sdk/openai"
+import { createAihubmix } from "@aihubmix/ai-sdk-provider"
 import { createOpenRouter } from "@openrouter/ai-sdk-provider"
 import { generateText } from "ai"
 import { NextResponse } from "next/server"
 import { createOllama } from "ollama-ai-provider-v2"
-import { normalizeMiniMaxBaseURL } from "@/lib/ai-providers"
+import {
+    AIHUBMIX_APP_CODE,
+    isAihubmixStandardBaseURL,
+    normalizeMiniMaxBaseURL,
+} from "@/lib/ai-providers"
 import { allowPrivateUrls, isPrivateUrl } from "@/lib/ssrf-protection"
 import { PROVIDER_INFO, type ProviderName } from "@/lib/types/model-config"
 
@@ -51,7 +56,7 @@ export async function POST(req: Request) {
         }
 
         // SECURITY: Block SSRF attacks via custom baseUrl
-        if (baseUrl && !allowPrivateUrls() && isPrivateUrl(baseUrl)) {
+        if (baseUrl && !allowPrivateUrls() && (await isPrivateUrl(baseUrl))) {
             return NextResponse.json(
                 { valid: false, error: "Invalid base URL" },
                 { status: 400 },
@@ -153,6 +158,28 @@ export async function POST(req: Request) {
                 break
             }
 
+            case "aihubmix": {
+                const defaultBaseURL = PROVIDER_INFO.aihubmix.defaultBaseUrl
+
+                if (
+                    isAihubmixStandardBaseURL(baseUrl) ||
+                    baseUrl === defaultBaseURL
+                ) {
+                    const aihubmix = createAihubmix({
+                        apiKey,
+                        appCode: AIHUBMIX_APP_CODE,
+                    })
+                    model = aihubmix(modelId)
+                } else {
+                    const aihubmixCompatible = createOpenAI({
+                        apiKey,
+                        baseURL: baseUrl,
+                    })
+                    model = aihubmixCompatible.chat(modelId)
+                }
+                break
+            }
+
             case "deepseek": {
                 if (baseUrl || apiKey) {
                     const ds = createDeepSeek({
@@ -345,12 +372,14 @@ export async function POST(req: Request) {
                 break
             }
 
-            // GLM, Qwen, Kimi, Qiniu, Novita - OpenAI compatible
+            // GLM, Qwen, Kimi, Qiniu, Novita, MiMo, Atlas Cloud - OpenAI compatible
             case "glm":
             case "qwen":
             case "kimi":
             case "qiniu":
-            case "novita": {
+            case "novita":
+            case "atlascloud":
+            case "mimo": {
                 const baseURL =
                     baseUrl ||
                     PROVIDER_INFO[provider as ProviderName]?.defaultBaseUrl ||

biome.json

@@ -6,7 +6,8 @@
         "useIgnoreFile": true
     },
     "files": {
-        "ignoreUnknown": false
+        "ignoreUnknown": false,
+        "includes": ["**", "!public/**/*.svg"]
     },
     "formatter": {
         "enabled": true,

components/model-config-dialog.tsx

@@ -54,6 +54,7 @@ import {
 import { Switch } from "@/components/ui/switch"
 import { useDictionary } from "@/hooks/use-dictionary"
 import type { UseModelConfigReturn } from "@/hooks/use-model-config"
+import { getApiEndpoint } from "@/lib/base-path"
 import { formatMessage } from "@/lib/i18n/utils"
 import type { ProviderConfig, ProviderName } from "@/lib/types/model-config"
 import { PROVIDER_INFO, SUGGESTED_MODELS } from "@/lib/types/model-config"
@@ -132,6 +133,14 @@ export function ModelConfigDialog({
         modelId: string
         message: string
     } | null>(null)
+    const [dynamicSuggestedModels, setDynamicSuggestedModels] = useState<
+        Partial<Record<ProviderName, string[]>>
+    >({})
+    const [loadedSuggestedProviders, setLoadedSuggestedProviders] = useState<
+        Partial<Record<ProviderName, boolean>>
+    >({})
+    const [loadingSuggestedProvider, setLoadingSuggestedProvider] =
+        useState<ProviderName | null>(null)
 
     const {
         config,
@@ -157,10 +166,68 @@ export function ModelConfigDialog({
         }
     }, [])
 
+    useEffect(() => {
+        if (
+            !open ||
+            selectedProvider?.provider !== "aihubmix" ||
+            loadedSuggestedProviders.aihubmix
+        ) {
+            return
+        }
+
+        let cancelled = false
+        setLoadingSuggestedProvider("aihubmix")
+
+        fetch(getApiEndpoint("/api/aihubmix-models"))
+            .then((response) => {
+                if (!response.ok) {
+                    throw new Error(`Failed to load models: ${response.status}`)
+                }
+                return response.json()
+            })
+            .then((data: { models?: unknown }) => {
+                if (cancelled || !Array.isArray(data.models)) {
+                    return
+                }
+
+                const models = data.models.filter(
+                    (model): model is string => typeof model === "string",
+                )
+                if (models.length > 0) {
+                    setDynamicSuggestedModels((current) => ({
+                        ...current,
+                        aihubmix: models,
+                    }))
+                }
+            })
+            .catch((error) => {
+                console.warn("Failed to load AIHubMix models:", error)
+            })
+            .finally(() => {
+                if (cancelled) {
+                    return
+                }
+
+                setLoadedSuggestedProviders((current) => ({
+                    ...current,
+                    aihubmix: true,
+                }))
+                setLoadingSuggestedProvider(null)
+            })
+
+        return () => {
+            cancelled = true
+        }
+    }, [open, selectedProvider?.provider, loadedSuggestedProviders.aihubmix])
+
     // Get suggested models for current provider
     const suggestedModels = selectedProvider
-        ? SUGGESTED_MODELS[selectedProvider.provider] || []
+        ? dynamicSuggestedModels[selectedProvider.provider] ||
+          SUGGESTED_MODELS[selectedProvider.provider] ||
+          []
         : []
+    const isLoadingSuggestedModels =
+        selectedProvider?.provider === loadingSuggestedProvider
 
     // Filter out already-added models from suggestions
     const existingModelIds =
@@ -168,6 +235,11 @@ export function ModelConfigDialog({
     const availableSuggestions = suggestedModels.filter(
         (modelId) => !existingModelIds.includes(modelId),
     )
+    const emptyStateSuggestions = selectedProvider
+        ? (SUGGESTED_MODELS[selectedProvider.provider] || [])
+              .filter((modelId) => !existingModelIds.includes(modelId))
+              .slice(0, 4)
+        : []
 
     // Handle adding a new provider
     const handleAddProvider = (providerType: ProviderName) => {
@@ -773,21 +845,26 @@ export function ModelConfigDialog({
                                                         }
                                                     }}
                                                     disabled={
+                                                        isLoadingSuggestedModels ||
                                                         availableSuggestions.length ===
-                                                        0
+                                                            0
                                                     }
                                                 >
                                                     <SelectTrigger className="w-28 h-8 rounded-lg hover:bg-interactive-hover">
-                                                        <span className="text-xs">
-                                                            {availableSuggestions.length ===
-                                                            0
-                                                                ? dict
-                                                                      .modelConfig
-                                                                      .allAdded
-                                                                : dict
-                                                                      .modelConfig
-                                                                      .suggested}
-                                                        </span>
+                                                        {isLoadingSuggestedModels ? (
+                                                            <Loader2 className="h-3.5 w-3.5 animate-spin" />
+                                                        ) : (
+                                                            <span className="text-xs">
+                                                                {availableSuggestions.length ===
+                                                                0
+                                                                    ? dict
+                                                                          .modelConfig
+                                                                          .allAdded
+                                                                    : dict
+                                                                          .modelConfig
+                                                                          .suggested}
+                                                            </span>
+                                                        )}
                                                     </SelectTrigger>
                                                     <SelectContent className="max-h-72">
                                                         {availableSuggestions.map(
@@ -816,7 +893,12 @@ export function ModelConfigDialog({
                                             0 ? (
                                                 <div className="p-6 text-center h-full flex flex-col items-center justify-center">
                                                     <div className="inline-flex items-center justify-center w-10 h-10 rounded-full bg-surface-2 mb-3">
-                                                        <Sparkles className="h-5 w-5 text-muted-foreground" />
+                                                        <ProviderLogo
+                                                            provider={
+                                                                selectedProvider.provider
+                                                            }
+                                                            className="size-5 text-muted-foreground"
+                                                        />
                                                     </div>
                                                     <p className="text-sm text-muted-foreground">
                                                         {
@@ -824,6 +906,36 @@ export function ModelConfigDialog({
                                                                 .noModelsConfigured
                                                         }
                                                     </p>
+                                                    {emptyStateSuggestions.length >
+                                                        0 && (
+                                                        <div className="mt-4 flex max-w-full flex-wrap items-center justify-center gap-2">
+                                                            {emptyStateSuggestions.map(
+                                                                (modelId) => (
+                                                                    <Button
+                                                                        key={
+                                                                            modelId
+                                                                        }
+                                                                        type="button"
+                                                                        variant="outline"
+                                                                        size="sm"
+                                                                        className="h-7 max-w-[220px] rounded-lg px-2 font-mono text-[11px]"
+                                                                        onClick={() =>
+                                                                            handleAddModel(
+                                                                                modelId,
+                                                                            )
+                                                                        }
+                                                                    >
+                                                                        <Plus className="h-3 w-3 shrink-0" />
+                                                                        <span className="truncate">
+                                                                            {
+                                                                                modelId
+                                                                            }
+                                                                        </span>
+                                                                    </Button>
+                                                                ),
+                                                            )}
+                                                        </div>
+                                                    )}
                                                 </div>
                                             ) : (
                                                 <div className="divide-y divide-border-subtle">

components/model-selector.tsx

@@ -158,7 +158,7 @@ export function ModelSelector({
     }, [])
 
     return (
-        <div ref={wrapperRef} className="inline-block">
+        <div ref={wrapperRef} className="min-w-0 max-w-48">
             <ModelSelectorRoot open={open} onOpenChange={setOpen}>
                 <ModelSelectorTrigger asChild>
                     <ButtonWithTooltip
@@ -167,7 +167,7 @@ export function ModelSelector({
                         size="sm"
                         disabled={disabled}
                         className={cn(
-                            "hover:bg-accent gap-1.5 h-8 px-2 transition-[padding,background-color] duration-150 ease-in-out",
+                            "h-8 min-w-0 max-w-full shrink overflow-hidden gap-1.5 px-2 transition-[padding,background-color] duration-150 ease-in-out hover:bg-accent",
                             !showLabel && "px-1.5 justify-center",
                         )}
                         // accessibility: expose label to screen readers
@@ -176,7 +176,7 @@ export function ModelSelector({
                         <Bot className="h-4 w-4 flex-shrink-0 text-muted-foreground" />
                         {/* show/hide visible label based on measured width */}
                         {showLabel ? (
-                            <span className="text-xs truncate">
+                            <span className="min-w-0 truncate text-xs">
                                 {selectedModel
                                     ? selectedModel.modelId
                                     : dict.modelConfig.default}

components/provider-credentials-fields.tsx

@@ -249,6 +249,11 @@ export function ProviderCredentialsFields({
                                 {dict.modelConfig.minimaxBaseUrlHint}
                             </p>
                         )}
+                        {provider === "mimo" && (
+                            <p className="text-xs text-muted-foreground">
+                                {dict.modelConfig.mimoBaseUrlHint}
+                            </p>
+                        )}
                     </div>
                 </>
             )}

docs/cn/README_CN.md

@@ -204,6 +204,7 @@ npm run dev
 -   Azure OpenAI
 -   Ollama
 -   OpenRouter
+-   AIHubMix
 -   DeepSeek
 -   SiliconFlow
 -   ModelScope
@@ -216,7 +217,7 @@ npm run dev
 
 ### 服务端多模型配置
 
-管理员可以配置多个服务端模型，让所有用户无需提供个人 API Key 即可使用。通过 `AI_MODELS_CONFIG` 环境变量（JSON 字符串）或 `ai-models.json` 文件配置。
+管理员可以配置多个服务端模型，让所有用户无需提供个人 API Key 即可使用。通过 `AI_MODELS_CONFIG` 环境变量（JSON 字符串）或 `ai-models.json` 文件配置。如果只需要单 provider 下的多个模型，也可以直接在 `AI_MODEL` 中用逗号分隔模型 ID。
 
 **模型要求**：此任务需要强大的模型能力，因为它涉及生成具有严格格式约束的长文本（draw.io XML）。推荐使用 Claude Sonnet 4.5、GPT-5.1、Gemini 3 Pro 和 DeepSeek V3.2/R1。
 

docs/cn/ai-providers.md

@@ -46,6 +46,21 @@ AI_MODEL=gpt-4o
 OPENAI_BASE_URL=https://your-custom-endpoint/v1
 ```
 
+### AIHubMix
+
+AIHubMix 通过单个 API Key 聚合 Claude、GPT、Gemini、DeepSeek 等模型。
+
+```bash
+AIHUBMIX_API_KEY=your_api_key
+AI_MODEL=claude-sonnet-4-5-20250929
+```
+
+可选的自定义端点：
+
+```bash
+AIHUBMIX_BASE_URL=https://aihubmix.com/v1
+```
+
 ### Anthropic
 
 ```bash
@@ -293,6 +308,19 @@ AI_MODEL=your_model_id
 QINIU_BASE_URL=https://your-custom-endpoint
 ```
 
+### MiMo (小米)
+
+```bash
+MIMO_API_KEY=your_api_key
+AI_MODEL=mimo-v2.5-pro
+```
+
+可选的自定义端点（Token Plan 订阅用户请设置专属 Base URL）：
+
+```bash
+MIMO_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1
+```
+
 ## 自动检测
 
 如果您只配置了**一个**提供商的 API 密钥，系统将自动检测并使用该提供商。无需设置 `AI_PROVIDER`。
@@ -300,7 +328,7 @@ QINIU_BASE_URL=https://your-custom-endpoint
 如果您配置了**多个** API 密钥，则必须显式设置 `AI_PROVIDER`：
 
 ```bash
-AI_PROVIDER=google  # 或：openai, anthropic, deepseek, siliconflow, doubao, azure, bedrock, openrouter, ollama, gateway, sglang, modelscope, minimax, glm, qwen, kimi, qiniu
+AI_PROVIDER=google  # 或：openai, anthropic, aihubmix, deepseek, siliconflow, doubao, azure, bedrock, openrouter, ollama, gateway, sglang, modelscope, minimax, glm, qwen, kimi, qiniu, mimo
 ```
 
 ## 服务端多模型配置
@@ -321,6 +349,17 @@ AI_MODELS_CONFIG='{"providers":[{"name":"OpenAI","provider":"openai","models":["
 
 在项目根目录创建 `ai-models.json` 文件（或通过 `AI_MODELS_CONFIG_PATH` 指定路径）。
 
+**方式三：`AI_MODEL` 用逗号分隔**（单 provider 的快速配置）
+
+如果只需要暴露同一 provider 下的多个模型，可以直接在 `AI_MODEL` 里用逗号分隔。第一个模型会作为默认值。
+
+```bash
+AI_PROVIDER=doubao
+AI_MODEL=doubao-seed-1-8-251215,doubao-seed-1-6-flash,doubao-seed-1-6-pro
+```
+
+这是等价 `ai-models.json` 的简写形式。如果需要配置多个 provider，或自定义 `apiKeyEnv` / `baseUrlEnv`，请使用方式一或方式二。
+
 ### 配置示例
 
 ```json

docs/en/ai-providers.md

@@ -61,6 +61,21 @@ Optional custom endpoint (for OpenAI-compatible services):
 OPENAI_BASE_URL=https://your-custom-endpoint/v1
 ```
 
+### AIHubMix
+
+AIHubMix provides access to Claude, GPT, Gemini, DeepSeek, and other models through a single API key.
+
+```bash
+AIHUBMIX_API_KEY=your_api_key
+AI_MODEL=claude-sonnet-4-5-20250929
+```
+
+Optional custom endpoint:
+
+```bash
+AIHUBMIX_BASE_URL=https://aihubmix.com/v1
+```
+
 ### Anthropic
 
 ```bash
@@ -308,6 +323,19 @@ Optional custom endpoint:
 QINIU_BASE_URL=https://your-custom-endpoint
 ```
 
+### MiMo (Xiaomi)
+
+```bash
+MIMO_API_KEY=your_api_key
+AI_MODEL=mimo-v2.5-pro
+```
+
+Optional custom endpoint (Token Plan subscribers should set their dedicated Base URL):
+
+```bash
+MIMO_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1
+```
+
 ## Auto-Detection
 
 If you only configure **one** provider's API key, the system will automatically detect and use that provider. No need to set `AI_PROVIDER`.
@@ -315,7 +343,7 @@ If you only configure **one** provider's API key, the system will automatically
 If you configure **multiple** API keys, you must explicitly set `AI_PROVIDER`:
 
 ```bash
-AI_PROVIDER=google  # or: openai, anthropic, deepseek, siliconflow, doubao, azure, bedrock, openrouter, ollama, gateway, sglang, modelscope, minimax, glm, qwen, kimi, qiniu
+AI_PROVIDER=google  # or: openai, anthropic, aihubmix, deepseek, siliconflow, doubao, azure, bedrock, openrouter, ollama, gateway, sglang, modelscope, minimax, glm, qwen, kimi, qiniu, mimo
 ```
 
 ## Server-Side Multi-Model Configuration
@@ -336,6 +364,17 @@ AI_MODELS_CONFIG='{"providers":[{"name":"OpenAI","provider":"openai","models":["
 
 Create an `ai-models.json` file in the project root (or set `AI_MODELS_CONFIG_PATH` to a custom location).
 
+**Option 3: Comma-separated `AI_MODEL`** (quick setup, single provider)
+
+If you only need multiple models from one provider, list them in `AI_MODEL` separated by commas. The first model is treated as the default.
+
+```bash
+AI_PROVIDER=doubao
+AI_MODEL=doubao-seed-1-8-251215,doubao-seed-1-6-flash,doubao-seed-1-6-pro
+```
+
+This is shorthand for the equivalent `ai-models.json`. For multiple providers or custom `apiKeyEnv` / `baseUrlEnv`, use Option 1 or 2 instead.
+
 ### Example Configuration
 
 ```json

docs/ja/README_JA.md

@@ -203,6 +203,7 @@ Next.jsアプリをデプロイする最も簡単な方法は、Next.jsの作成
 -   Azure OpenAI
 -   Ollama
 -   OpenRouter
+-   AIHubMix
 -   DeepSeek
 -   SiliconFlow
 -   ModelScope
@@ -215,7 +216,7 @@ AWS BedrockとOpenRouter以外のすべてのプロバイダーはカスタム
 
 ### サーバーサイドマルチモデル設定
 
-管理者は、ユーザーが個人のAPIキーを提供することなく利用できる複数のサーバーサイドモデルを設定できます。`AI_MODELS_CONFIG` 環境変数（JSON文字列）または `ai-models.json` ファイルで設定します。
+管理者は、ユーザーが個人のAPIキーを提供することなく利用できる複数のサーバーサイドモデルを設定できます。`AI_MODELS_CONFIG` 環境変数（JSON文字列）または `ai-models.json` ファイルで設定します。同一プロバイダー内の複数モデルだけが必要な場合は、`AI_MODEL` にカンマ区切りでモデルIDを列挙する簡易設定も使えます。
 
 **モデル要件**：このタスクは厳密なフォーマット制約（draw.io XML）を持つ長文テキスト生成を伴うため、強力なモデル機能が必要です。Claude Sonnet 4.5、GPT-5.1、Gemini 3 Pro、DeepSeek V3.2/R1を推奨します。
 

docs/ja/ai-providers.md

@@ -46,6 +46,21 @@ AI_MODEL=gpt-4o
 OPENAI_BASE_URL=https://your-custom-endpoint/v1
 ```
 
+### AIHubMix
+
+AIHubMix は、単一の API キーで Claude、GPT、Gemini、DeepSeek などのモデルへのアクセスを提供します。
+
+```bash
+AIHUBMIX_API_KEY=your_api_key
+AI_MODEL=claude-sonnet-4-5-20250929
+```
+
+任意のカスタムエンドポイント:
+
+```bash
+AIHUBMIX_BASE_URL=https://aihubmix.com/v1
+```
+
 ### Anthropic
 
 ```bash
@@ -293,6 +308,19 @@ AI_MODEL=your_model_id
 QINIU_BASE_URL=https://your-custom-endpoint
 ```
 
+### MiMo (Xiaomi)
+
+```bash
+MIMO_API_KEY=your_api_key
+AI_MODEL=mimo-v2.5-pro
+```
+
+オプションのカスタムエンドポイント（Token Plan 加入者は専用の Base URL を設定してください）：
+
+```bash
+MIMO_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1
+```
+
 ## 自動検出
 
 **1つ**のプロバイダーの API キーのみを設定した場合、システムはそのプロバイダーを自動的に検出して使用します。`AI_PROVIDER` を設定する必要はありません。
@@ -300,7 +328,7 @@ QINIU_BASE_URL=https://your-custom-endpoint
 **複数**の API キーを設定する場合は、`AI_PROVIDER` を明示的に設定する必要があります:
 
 ```bash
-AI_PROVIDER=google  # または: openai, anthropic, deepseek, siliconflow, doubao, azure, bedrock, openrouter, ollama, gateway, sglang, modelscope, minimax, glm, qwen, kimi, qiniu
+AI_PROVIDER=google  # または: openai, anthropic, aihubmix, deepseek, siliconflow, doubao, azure, bedrock, openrouter, ollama, gateway, sglang, modelscope, minimax, glm, qwen, kimi, qiniu, mimo
 ```
 
 ## サーバーサイドマルチモデル設定
@@ -321,6 +349,17 @@ AI_MODELS_CONFIG='{"providers":[{"name":"OpenAI","provider":"openai","models":["
 
 プロジェクトルートに `ai-models.json` ファイルを作成します（または `AI_MODELS_CONFIG_PATH` でパスを指定）。
 
+**方法3：`AI_MODEL` をカンマ区切りで指定**（単一プロバイダーの簡易設定）
+
+同一プロバイダー内の複数モデルだけを公開したい場合は、`AI_MODEL` にカンマ区切りで列挙できます。最初のモデルがデフォルトになります。
+
+```bash
+AI_PROVIDER=doubao
+AI_MODEL=doubao-seed-1-8-251215,doubao-seed-1-6-flash,doubao-seed-1-6-pro
+```
+
+これは等価な `ai-models.json` の簡易表記です。複数のプロバイダーや、カスタム `apiKeyEnv` / `baseUrlEnv` を使う場合は、方法1または方法2を使ってください。
+
 ### 設定例
 
 ```json

env.example

@@ -1,10 +1,14 @@
 # AI Provider Configuration
 # AI_PROVIDER: Which provider to use
-# Options: bedrock, openai, anthropic, google, vertexai, azure, ollama, openrouter, deepseek, siliconflow, gateway, novita
+# Options: bedrock, openai, anthropic, google, vertexai, azure, ollama, openrouter, aihubmix, deepseek, siliconflow, gateway, novita
 # Default: bedrock
 AI_PROVIDER=bedrock
 
 # AI_MODEL: The model ID for your chosen provider (REQUIRED)
+# Tip: For a single-provider quick multi-model setup, list comma-separated model IDs.
+# The first one becomes the default and the rest appear in the model picker.
+# For multiple providers or custom apiKeyEnv/baseUrlEnv, use AI_MODELS_CONFIG / ai-models.json instead.
+# Example: AI_MODEL=doubao-seed-1-8-251215,doubao-seed-1-6-flash,doubao-seed-1-6-pro
 AI_MODEL=global.anthropic.claude-sonnet-4-5-20250929-v1:0
 
 # AWS Bedrock Configuration
@@ -69,6 +73,10 @@ AI_MODEL=global.anthropic.claude-sonnet-4-5-20250929-v1:0
 # OPENROUTER_API_KEY=sk-or-v1-...
 # OPENROUTER_BASE_URL=https://openrouter.ai/api/v1  # Optional: Custom endpoint
 
+# AIHubMix Configuration
+# AIHUBMIX_API_KEY=your-aihubmix-api-key
+# AIHUBMIX_BASE_URL=https://aihubmix.com/v1  # Optional: Custom endpoint
+
 # DeepSeek Configuration
 # DEEPSEEK_API_KEY=sk-...
 # DEEPSEEK_BASE_URL=https://api.deepseek.com/v1  # Optional: Custom endpoint
@@ -181,3 +189,13 @@ AI_MODEL=global.anthropic.claude-sonnet-4-5-20250929-v1:0
 # Get your API key from: https://novita.ai/dashboard/key
 # NOVITA_API_KEY=your_novita_api_key
 # NOVITA_BASE_URL=https://api.novita.ai/openai  # Optional, default
+
+# MiMo (Xiaomi) Configuration (Optional)
+# Get your API key from: https://platform.xiaomimimo.com/
+# MIMO_API_KEY=your_mimo_api_key
+# MIMO_BASE_URL=https://api.xiaomimimo.com/v1  # Optional, default. Token Plan users: https://token-plan-cn.xiaomimimo.com/v1
+
+# Atlas Cloud Configuration (Optional)
+# Get your API key from: https://www.atlascloud.ai/console/api-keys
+# ATLASCLOUD_API_KEY=your_atlascloud_api_key
+# ATLASCLOUD_BASE_URL=https://api.atlascloud.ai/v1  # Optional, default. LLM chat endpoint; media generation uses a separate API.

lib/ai-providers.ts

@@ -6,6 +6,7 @@ import { createGateway, gateway } from "@ai-sdk/gateway"
 import { createGoogleGenerativeAI, google } from "@ai-sdk/google"
 import { createVertex } from "@ai-sdk/google-vertex"
 import { createOpenAI, openai } from "@ai-sdk/openai"
+import { aihubmix, createAihubmix } from "@aihubmix/ai-sdk-provider"
 import { fromNodeProviderChain } from "@aws-sdk/credential-providers"
 import { createOpenRouter } from "@openrouter/ai-sdk-provider"
 import { createOllama, ollama } from "ollama-ai-provider-v2"
@@ -13,6 +14,8 @@ import { PROVIDER_INFO, type ProviderName } from "@/lib/types/model-config"
 
 export type { ProviderName }
 
+export const AIHUBMIX_APP_CODE = "MSBS9675"
+
 interface ModelConfig {
     model: any
     providerOptions?: any
@@ -29,6 +32,7 @@ export const SINGLE_SYSTEM_PROVIDERS = new Set<ProviderName>([
     "kimi",
     "qiniu",
     "novita",
+    "mimo",
 ])
 
 /**
@@ -57,6 +61,18 @@ export function normalizeMiniMaxBaseURL(rawUrl: string): {
     return { baseURL, isAnthropicCompatible }
 }
 
+export function isAihubmixStandardBaseURL(
+    rawUrl: string | null | undefined,
+): boolean {
+    if (!rawUrl) return true
+
+    const baseURL = rawUrl.replace(/\/+$/, "")
+    return (
+        baseURL === "https://aihubmix.com" ||
+        baseURL === "https://aihubmix.com/v1"
+    )
+}
+
 export interface ClientOverrides {
     provider?: string | null
     baseUrl?: string | null
@@ -86,6 +102,7 @@ const ALLOWED_CLIENT_PROVIDERS: ProviderName[] = [
     "azure",
     "bedrock",
     "openrouter",
+    "aihubmix",
     "deepseek",
     "siliconflow",
     "sglang",
@@ -100,6 +117,8 @@ const ALLOWED_CLIENT_PROVIDERS: ProviderName[] = [
     "kimi",
     "minimax",
     "novita",
+    "mimo",
+    "atlascloud",
 ]
 
 // Bedrock provider options for Anthropic beta features
@@ -513,6 +532,7 @@ function buildProviderOptions(
 
         case "deepseek":
         case "openrouter":
+        case "aihubmix":
         case "siliconflow":
         case "sglang":
         case "gateway":
@@ -523,7 +543,9 @@ function buildProviderOptions(
         case "qwen":
         case "kimi":
         case "qiniu":
-        case "novita": {
+        case "novita":
+        case "atlascloud":
+        case "mimo": {
             // These providers don't have reasoning configs in AI SDK yet
             // Gateway passes through to underlying providers which handle their own configs
             break
@@ -546,6 +568,7 @@ export const PROVIDER_ENV_VARS: Record<ProviderName, string | null> = {
     azure: "AZURE_API_KEY",
     ollama: null, // No credentials needed for local Ollama
     openrouter: "OPENROUTER_API_KEY",
+    aihubmix: "AIHUBMIX_API_KEY",
     deepseek: "DEEPSEEK_API_KEY",
     siliconflow: "SILICONFLOW_API_KEY",
     sglang: "SGLANG_API_KEY",
@@ -559,6 +582,8 @@ export const PROVIDER_ENV_VARS: Record<ProviderName, string | null> = {
     kimi: "KIMI_API_KEY",
     minimax: "MINIMAX_API_KEY",
     novita: "NOVITA_API_KEY",
+    mimo: "MIMO_API_KEY",
+    atlascloud: "ATLASCLOUD_API_KEY",
 }
 
 /**
@@ -662,7 +687,7 @@ function validateProviderCredentials(
  * Get the AI model based on environment variables
  *
  * Environment variables:
- * - AI_PROVIDER: The provider to use (bedrock, openai, anthropic, google, azure, ollama, openrouter, deepseek, siliconflow, sglang, gateway, modelscope)
+ * - AI_PROVIDER: The provider to use (bedrock, openai, anthropic, google, azure, ollama, openrouter, aihubmix, deepseek, siliconflow, sglang, gateway, modelscope)
  * - AI_MODEL: The model ID/name for the selected provider
  *
  * Provider-specific env vars:
@@ -674,6 +699,7 @@ function validateProviderCredentials(
  * - AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY: AWS Bedrock credentials
  * - OLLAMA_BASE_URL: Ollama server URL (optional, defaults to https://ollama.com/api)
  * - OPENROUTER_API_KEY: OpenRouter API key
+ * - AIHUBMIX_API_KEY: AIHubMix API key
  * - DEEPSEEK_API_KEY: DeepSeek API key
  * - DEEPSEEK_BASE_URL: DeepSeek endpoint (optional)
  * - SILICONFLOW_API_KEY: SiliconFlow API key
@@ -710,8 +736,10 @@ export function getAIModel(overrides?: ClientOverrides): ModelConfig {
             (overrides?.provider === "vertexai" && overrides?.vertexApiKey))
     )
 
-    // Use client override if provided, otherwise fall back to env vars
-    const modelId = overrides?.modelId || process.env.AI_MODEL
+    // Use client override if provided, otherwise fall back to env vars.
+    // AI_MODEL may be comma-separated (multi-model fallback); pick the first.
+    const envModel = process.env.AI_MODEL?.split(",")[0]?.trim() || undefined
+    const modelId = overrides?.modelId || envModel
 
     if (!modelId) {
         if (isClientOverride) {
@@ -761,6 +789,7 @@ export function getAIModel(overrides?: ClientOverrides): ModelConfig {
                         `- GOOGLE_GENERATIVE_AI_API_KEY for Google\n` +
                         `- AWS_ACCESS_KEY_ID for Bedrock\n` +
                         `- OPENROUTER_API_KEY for OpenRouter\n` +
+                        `- AIHUBMIX_API_KEY for AIHubMix\n` +
                         `- AZURE_API_KEY for Azure\n` +
                         `- SILICONFLOW_API_KEY for SiliconFlow\n` +
                         `- SGLANG_API_KEY for SGLang\n` +
@@ -1003,6 +1032,42 @@ export function getAIModel(overrides?: ClientOverrides): ModelConfig {
             break
         }
 
+        case "aihubmix": {
+            const apiKey = resolveApiKey(overrides, "AIHUBMIX_API_KEY")
+            const serverBaseUrl = resolveBaseUrlEnv(
+                overrides,
+                "AIHUBMIX_BASE_URL",
+            )
+            const baseURL = resolveBaseURL(
+                overrides?.apiKey,
+                overrides?.baseUrl,
+                serverBaseUrl,
+                PROVIDER_INFO.aihubmix.defaultBaseUrl,
+            )
+            const defaultBaseURL = PROVIDER_INFO.aihubmix.defaultBaseUrl
+
+            if (
+                isAihubmixStandardBaseURL(baseURL) ||
+                baseURL === defaultBaseURL
+            ) {
+                const aihubmixProvider =
+                    overrides?.apiKey || apiKey
+                        ? createAihubmix({
+                              apiKey,
+                              appCode: AIHUBMIX_APP_CODE,
+                          })
+                        : aihubmix
+                model = aihubmixProvider(modelId)
+            } else {
+                const aihubmixCompatibleProvider = createOpenAI({
+                    apiKey,
+                    baseURL,
+                })
+                model = aihubmixCompatibleProvider.chat(modelId)
+            }
+            break
+        }
+
         case "deepseek": {
             const apiKey = resolveApiKey(overrides, "DEEPSEEK_API_KEY")
             const serverBaseUrl = resolveBaseUrlEnv(
@@ -1288,10 +1353,28 @@ export function getAIModel(overrides?: ClientOverrides): ModelConfig {
             break
         }
 
+        case "mimo": {
+            const apiKey = resolveApiKey(overrides, "MIMO_API_KEY")
+            const baseURL = resolveBaseURL(
+                overrides?.apiKey,
+                overrides?.baseUrl,
+                resolveBaseUrlEnv(overrides, "MIMO_BASE_URL"),
+                PROVIDER_INFO.mimo?.defaultBaseUrl,
+            )
+            // Use createDeepSeek to properly handle reasoning_content for MiMo
+            // thinking models (e.g., mimo-v2.5-pro). MiMo's API requires
+            // reasoning_content to be passed back during multi-turn tool calls
+            // (returns 400 otherwise), same convention as DeepSeek and Kimi.
+            const mimoProvider = createDeepSeek({ apiKey, baseURL })
+            model = mimoProvider(modelId)
+            break
+        }
+
         case "glm":
         case "qwen":
         case "qiniu":
-        case "novita": {
+        case "novita":
+        case "atlascloud": {
             const envVar = PROVIDER_ENV_VARS[provider]
             if (!envVar) {
                 throw new Error(
@@ -1322,7 +1405,7 @@ export function getAIModel(overrides?: ClientOverrides): ModelConfig {
                 overrides?.apiKey,
                 overrides?.baseUrl,
                 resolveBaseUrlEnv(overrides, "KIMI_BASE_URL"),
-                PROVIDER_INFO["kimi"]?.defaultBaseUrl,
+                PROVIDER_INFO.kimi?.defaultBaseUrl,
             )
             // Use createDeepSeek to properly handle reasoning_content for Kimi
             // thinking models (e.g., kimi-k2.6). Kimi's API uses the same
@@ -1335,7 +1418,7 @@ export function getAIModel(overrides?: ClientOverrides): ModelConfig {
 
         default:
             throw new Error(
-                `Unknown AI provider: ${provider}. Supported providers: bedrock, openai, anthropic, google, azure, ollama, openrouter, deepseek, siliconflow, sglang, gateway, edgeone, doubao, modelscope, glm, qwen, qiniu, kimi, minimax, novita`,
+                `Unknown AI provider: ${provider}. Supported providers: bedrock, openai, anthropic, google, azure, ollama, openrouter, aihubmix, deepseek, siliconflow, sglang, gateway, edgeone, doubao, modelscope, glm, qwen, qiniu, kimi, minimax, novita, mimo, atlascloud`,
             )
     }
 
@@ -1361,80 +1444,19 @@ export function supportsPromptCaching(modelId: string): boolean {
     )
 }
 
-/**
- * Check if a model supports image/vision input.
- * Some models silently drop image parts without error (AI SDK warning only).
- */
-export function supportsImageInput(modelId: string): boolean {
-    const lowerModelId = modelId.toLowerCase()
-
-    // Helper to check if model has vision capability indicator
-    const hasVisionIndicator =
-        lowerModelId.includes("vision") || lowerModelId.includes("vl")
-
-    // Models that DON'T support image/vision input (unless vision variant)
-    // Kimi K2 doesn't support images, but K2.5 does
-    // Only block kimi-k2 specifically, not other Kimi models
-    if (
-        (lowerModelId.includes("kimi-k2") ||
-            lowerModelId.includes("kimi_k2")) &&
-        !hasVisionIndicator &&
-        !lowerModelId.includes("2.5") &&
-        !lowerModelId.includes("k2.5")
-    ) {
-        return false
-    }
-
-    // Moonshot text models (moonshot-v1 series are text-only)
-    if (lowerModelId.includes("moonshot-v1") && !hasVisionIndicator) {
-        return false
-    }
-
-    // MiniMax text models (MiniMax-M2.x series are text-only; M3 supports image input)
-    if (
-        lowerModelId.includes("minimax") &&
-        !hasVisionIndicator &&
-        !lowerModelId.includes("m3")
-    ) {
-        return false
-    }
-
-    // DeepSeek text models (not vision variants)
-    if (lowerModelId.includes("deepseek") && !hasVisionIndicator) {
-        return false
-    }
-
-    // Qwen text models (not vision variants like qwen-vl)
-    // Qwen3.5 series (qwen3.5, qwen3.5-plus, qwen3.5-flash) natively support image input
-    // QvQ (Qwen Visual QA) models are vision models — exclude them even when prefixed with "qwen/"
-    if (
-        lowerModelId.includes("qwen") &&
-        !hasVisionIndicator &&
-        !lowerModelId.includes("qwen3.5") &&
-        !lowerModelId.includes("qvq")
-    ) {
-        return false
-    }
-
-    // GLM text models (not vision variants)
-    // GLM vision models: glm-4v, glm-4v-9b, glm-4.1v-9b-thinking
-    if (lowerModelId.includes("glm") && !hasVisionIndicator) {
-        if (!/[\d.]v/.test(lowerModelId)) {
-            return false
-        }
-    }
-
-    // Default: assume model supports images
-    return true
-}
-
 /**
  * Get the AI model for diagram validation.
  * Uses VALIDATION_MODEL env var if set, otherwise falls back to AI_MODEL.
- * Throws if the model doesn't support image input.
+ *
+ * Note: we no longer guess whether the model supports image input from its
+ * name — that heuristic misfired on newer models (see issue #874). If a
+ * configured validation model can't handle images, the API call simply errors
+ * and the validate-diagram route falls back to "valid".
  */
 export function getValidationModel(): ReturnType<typeof getAIModel>["model"] {
-    const modelId = process.env.VALIDATION_MODEL || process.env.AI_MODEL
+    // AI_MODEL may be comma-separated (multi-model fallback); pick the first.
+    const envFallback = process.env.AI_MODEL?.split(",")[0]?.trim() || undefined
+    const modelId = process.env.VALIDATION_MODEL || envFallback
 
     if (!modelId) {
         throw new Error(
@@ -1442,12 +1464,6 @@ export function getValidationModel(): ReturnType<typeof getAIModel>["model"] {
         )
     }
 
-    if (!supportsImageInput(modelId)) {
-        throw new Error(
-            `Validation requires a vision-capable model. Model "${modelId}" does not support image input.`,
-        )
-    }
-
     const { model } = getAIModel({ modelId })
     return model
 }

lib/aihubmix-models.ts

@@ -0,0 +1,79 @@
+export const AIHUBMIX_MODELS_ENDPOINT = "https://aihubmix.com/api/v1/models"
+
+const NON_CHAT_MODEL_TYPES = new Set([
+    "embedding",
+    "image_generation",
+    "rerank",
+    "transcription",
+    "tts",
+    "video",
+])
+
+type AihubmixModelListPayload = {
+    data?: unknown
+}
+
+type AihubmixModelRecord = {
+    model_id?: unknown
+    types?: unknown
+}
+
+function getModelTypes(types: unknown): Set<string> {
+    if (typeof types !== "string") {
+        return new Set()
+    }
+
+    return new Set(
+        types
+            .split(",")
+            .map((type) => type.trim())
+            .filter(Boolean),
+    )
+}
+
+function isChatModel(record: AihubmixModelRecord): record is {
+    model_id: string
+    types: string
+} {
+    if (typeof record.model_id !== "string" || !record.model_id.trim()) {
+        return false
+    }
+
+    const types = getModelTypes(record.types)
+    if (!types.has("llm")) {
+        return false
+    }
+
+    return !Array.from(NON_CHAT_MODEL_TYPES).some((type) => types.has(type))
+}
+
+export function extractAihubmixModelIds(payload: unknown): string[] {
+    const data = (payload as AihubmixModelListPayload)?.data
+    if (!Array.isArray(data)) {
+        return []
+    }
+
+    const seen = new Set<string>()
+    const modelIds: string[] = []
+
+    for (const item of data) {
+        if (!item || typeof item !== "object") {
+            continue
+        }
+
+        const record = item as AihubmixModelRecord
+        if (!isChatModel(record)) {
+            continue
+        }
+
+        const modelId = record.model_id.trim()
+        if (seen.has(modelId)) {
+            continue
+        }
+
+        seen.add(modelId)
+        modelIds.push(modelId)
+    }
+
+    return modelIds
+}

lib/i18n/dictionaries/en.json

@@ -34,7 +34,8 @@
         "glm": "GLM",
         "qwen": "Qwen",
         "kimi": "Kimi",
-        "qiniu": "Qiniu"
+        "qiniu": "Qiniu",
+        "mimo": "MiMo (Xiaomi)"
     },
     "chat": {
         "placeholder": "Describe your diagram or upload a file...",
@@ -371,6 +372,7 @@
         "baseUrlWithExample": "Base URL (optional, e.g. {example})",
         "customEndpoint": "Custom endpoint URL",
         "minimaxBaseUrlHint": "Use /anthropic for Anthropic-compatible API (recommended), or /v1 for OpenAI-compatible API",
+        "mimoBaseUrlHint": "Default works with pay-as-you-go keys (sk-...). Token Plan subscribers (tp-... keys) must set https://token-plan-cn.xiaomimimo.com/v1",
         "models": "Models",
         "customModelId": "Custom model ID...",
         "allAdded": "All added",

lib/i18n/dictionaries/ja.json

@@ -34,7 +34,8 @@
         "glm": "GLM",
         "qwen": "Qwen",
         "kimi": "Kimi",
-        "qiniu": "Qiniu"
+        "qiniu": "Qiniu",
+        "mimo": "MiMo (Xiaomi)"
     },
     "chat": {
         "placeholder": "ダイアグラムを説明するか、ファイルをアップロード...",
@@ -325,6 +326,7 @@
         "baseUrlWithExample": "ベース URL（オプション、例: {example}）",
         "customEndpoint": "カスタムエンドポイント URL",
         "minimaxBaseUrlHint": "/anthropic で Anthropic 互換 API（推奨）、または /v1 で OpenAI 互換 API を使用",
+        "mimoBaseUrlHint": "デフォルトは従量課金キー（sk-...）用です。Token Plan 加入者（tp-... キー）は https://token-plan-cn.xiaomimimo.com/v1 を設定してください",
         "models": "モデル",
         "customModelId": "カスタムモデル ID...",
         "allAdded": "すべて追加済み",

lib/i18n/dictionaries/zh-Hant.json

@@ -34,7 +34,8 @@
         "glm": "GLM",
         "qwen": "Qwen",
         "kimi": "Kimi",
-        "qiniu": "Qiniu"
+        "qiniu": "Qiniu",
+        "mimo": "MiMo (小米)"
     },
     "chat": {
         "placeholder": "描述您的圖表或上傳檔案...",
@@ -371,6 +372,7 @@
         "baseUrlWithExample": "基礎 URL（可選，例如 {example}）",
         "customEndpoint": "自訂端點 URL",
         "minimaxBaseUrlHint": "使用 /anthropic 端點為 Anthropic 相容 API（推薦），或使用 /v1 端點為 OpenAI 相容 API",
+        "mimoBaseUrlHint": "預設地址適用於按量付費金鑰（sk-...）。Token Plan 訂閱用戶（tp-... 金鑰）請設定為 https://token-plan-cn.xiaomimimo.com/v1",
         "models": "模型",
         "customModelId": "自訂模型 ID...",
         "allAdded": "已全部新增",

lib/i18n/dictionaries/zh.json

@@ -34,7 +34,8 @@
         "glm": "GLM",
         "qwen": "Qwen",
         "kimi": "Kimi",
-        "qiniu": "Qiniu"
+        "qiniu": "Qiniu",
+        "mimo": "MiMo (小米)"
     },
     "chat": {
         "placeholder": "描述您的图表或上传文件...",
@@ -371,6 +372,7 @@
         "baseUrlWithExample": "基础 URL（可选，例如 {example}）",
         "customEndpoint": "自定义端点 URL",
         "minimaxBaseUrlHint": "使用 /anthropic 端点为 Anthropic 兼容 API（推荐），或使用 /v1 端点为 OpenAI 兼容 API",
+        "mimoBaseUrlHint": "默认地址适用于按量付费密钥（sk-...）。Token Plan 订阅用户（tp-... 密钥）请设置为 https://token-plan-cn.xiaomimimo.com/v1",
         "models": "模型",
         "customModelId": "自定义模型 ID...",
         "allAdded": "已全部添加",

lib/server-model-config.ts

@@ -62,6 +62,53 @@ function getConfigPath(): string {
     return path.join(process.cwd(), "ai-models.json")
 }
 
+/**
+ * Synthesize a config from a comma-separated AI_MODEL value (Priority 3 fallback).
+ * Lets users expose multiple models without authoring AI_MODELS_CONFIG / ai-models.json.
+ * Triggers only when AI_MODEL contains a comma AND AI_PROVIDER is set to a known provider.
+ */
+function configFromCommaSeparatedAiModel(): ServerModelsConfig | null {
+    const aiModel = process.env.AI_MODEL
+    if (!aiModel || !aiModel.includes(",")) return null
+
+    const aiProvider = process.env.AI_PROVIDER
+    if (!aiProvider) {
+        console.warn(
+            "[server-model-config] AI_MODEL contains commas but AI_PROVIDER is not set; " +
+                "skipping multi-model fallback. Set AI_PROVIDER, or use AI_MODELS_CONFIG / ai-models.json.",
+        )
+        return null
+    }
+    if (!(aiProvider in PROVIDER_INFO)) {
+        console.warn(
+            `[server-model-config] AI_PROVIDER="${aiProvider}" is not a known provider; skipping multi-model fallback.`,
+        )
+        return null
+    }
+
+    const models = Array.from(
+        new Set(
+            aiModel
+                .split(",")
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0),
+        ),
+    )
+    if (models.length === 0) return null
+
+    const providerName = aiProvider as ProviderName
+    return {
+        providers: [
+            {
+                name: PROVIDER_INFO[providerName]?.label || providerName,
+                provider: providerName,
+                models,
+                default: true,
+            },
+        ],
+    }
+}
+
 export async function loadEnvServerModelsConfig(): Promise<ServerModelsConfig | null> {
     // Priority 1: AI_MODELS_CONFIG env var (JSON string) - for cloud deployments
     const envConfig = process.env.AI_MODELS_CONFIG
@@ -85,15 +132,17 @@ export async function loadEnvServerModelsConfig(): Promise<ServerModelsConfig |
         const json = JSON.parse(jsonStr)
         return ServerModelsConfigSchema.parse(json)
     } catch (err: any) {
-        if (err?.code === "ENOENT") {
+        if (err?.code !== "ENOENT") {
+            console.error(
+                "[server-model-config] Failed to load ai-models.json:",
+                err,
+            )
             return null
         }
-        console.error(
-            "[server-model-config] Failed to load ai-models.json:",
-            err,
-        )
-        return null
     }
+
+    // Priority 3: AI_MODEL with comma-separated values + AI_PROVIDER
+    return configFromCommaSeparatedAiModel()
 }
 
 export async function loadRawServerModelsConfig(): Promise<ServerModelsConfig | null> {

lib/ssrf-protection.ts

@@ -2,80 +2,108 @@
  * SSRF (Server-Side Request Forgery) protection utilities
  */
 
+import { lookup } from "node:dns/promises"
+
 /**
- * Check if URL points to private/internal network
- * Blocks: localhost, private IPs, link-local, AWS metadata service
+ * Check if an IP address (IPv4 or IPv6) belongs to a private/internal range.
+ * Works for both user-supplied literal IPs and DNS-resolved addresses.
  */
-export function isPrivateUrl(urlString: string): boolean {
+function isPrivateIp(ip: string): boolean {
+    const addr = ip.toLowerCase().replace(/^\[|\]$/g, "")
+
+    // IPv6
+    if (addr.includes(":")) {
+        if (addr === "::1" || addr === "::") return true
+        // unique-local (fc00::/7) and IPv4-mapped (::ffff:0:0/96)
+        if (
+            addr.startsWith("fc") ||
+            addr.startsWith("fd") ||
+            addr.startsWith("::ffff:")
+        ) {
+            return true
+        }
+        // link-local (fe80::/10)
+        const linkLocal = addr.match(/^fe([0-9a-f]{2}):/)
+        if (linkLocal) {
+            const high = parseInt(linkLocal[1], 16)
+            if (high >= 0x80 && high <= 0xbf) return true
+        }
+        return false
+    }
+
+    // IPv4
+    const ipv4Match = addr.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/)
+    if (ipv4Match) {
+        const [, a, b] = ipv4Match.map(Number)
+        if (a === 10) return true // 10.0.0.0/8
+        if (a === 172 && b >= 16 && b <= 31) return true // 172.16.0.0/12
+        if (a === 192 && b === 168) return true // 192.168.0.0/16
+        if (a === 169 && b === 254) return true // 169.254.0.0/16 (link-local)
+        if (a === 127) return true // 127.0.0.0/8 (loopback)
+        if (a === 0) return true // 0.0.0.0/8
+        if (a === 100 && b >= 64 && b <= 127) return true // 100.64.0.0/10 (CGNAT, used by some cloud internal networks)
+    }
+
+    return false
+}
+
+/**
+ * String-only check against well-known private hostnames and literal IPs.
+ * Fast path that avoids a DNS lookup for obvious cases.
+ */
+function isPrivateHostname(hostname: string): boolean {
+    const host = hostname
+        .toLowerCase()
+        .replace(/^\[|\]$/g, "")
+        .replace(/\.$/, "")
+
+    if (
+        host === "localhost" ||
+        host === "127.0.0.1" ||
+        host === "::1" ||
+        host === "::"
+    ) {
+        return true
+    }
+
+    if (host === "169.254.169.254" || host === "metadata.google.internal") {
+        return true
+    }
+
+    if (
+        host.endsWith(".local") ||
+        host.endsWith(".internal") ||
+        host.endsWith(".localhost")
+    ) {
+        return true
+    }
+
+    // Literal IP supplied directly in the URL
+    return isPrivateIp(host)
+}
+
+/**
+ * Check if URL points to private/internal network.
+ * Blocks: localhost, private IPs, link-local, AWS metadata service.
+ *
+ * Resolves the hostname via DNS and validates every returned address, so
+ * public-looking names that map to internal IPs (e.g. "127-0-0-1.sslip.io")
+ * are caught even though they pass the string-only check.
+ */
+export async function isPrivateUrl(urlString: string): Promise<boolean> {
     try {
         const url = new URL(urlString)
-        // Strip a trailing dot so FQDN forms like "localhost." (which still
-        // resolve to 127.0.0.1) cannot bypass the equality checks below.
         const hostname = url.hostname
-            .toLowerCase()
-            .replace(/^\[|\]$/g, "")
-            .replace(/\.$/, "")
 
-        // Block localhost
-        if (
-            hostname === "localhost" ||
-            hostname === "127.0.0.1" ||
-            hostname === "::1" ||
-            hostname === "::"
-        ) {
-            return true
-        }
+        // Fast path: obvious string matches and literal IPs.
+        if (isPrivateHostname(hostname)) return true
 
-        // Block IPv6 unique-local (fc00::/7), link-local (fe80::/10),
-        // and IPv4-mapped (::ffff:0:0/96) hosts.
-        if (hostname.includes(":")) {
-            if (
-                hostname.startsWith("fc") ||
-                hostname.startsWith("fd") ||
-                hostname.startsWith("::ffff:")
-            ) {
-                return true
-            }
-            const linkLocal = hostname.match(/^fe([0-9a-f]{2}):/)
-            if (linkLocal) {
-                const high = parseInt(linkLocal[1], 16)
-                if (high >= 0x80 && high <= 0xbf) return true
-            }
-        }
-
-        // Block AWS/cloud metadata endpoints
-        if (
-            hostname === "169.254.169.254" ||
-            hostname === "metadata.google.internal"
-        ) {
-            return true
-        }
-
-        // Check for private IPv4 ranges
-        const ipv4Match = hostname.match(
-            /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/,
-        )
-        if (ipv4Match) {
-            const [, a, b] = ipv4Match.map(Number)
-            if (a === 10) return true // 10.0.0.0/8
-            if (a === 172 && b >= 16 && b <= 31) return true // 172.16.0.0/12
-            if (a === 192 && b === 168) return true // 192.168.0.0/16
-            if (a === 169 && b === 254) return true // 169.254.0.0/16 (link-local)
-            if (a === 127) return true // 127.0.0.0/8 (loopback)
-        }
-
-        // Block common internal hostnames
-        if (
-            hostname.endsWith(".local") ||
-            hostname.endsWith(".internal") ||
-            hostname.endsWith(".localhost")
-        ) {
-            return true
-        }
-
-        return false
+        // Resolve DNS and reject if any address is private.
+        const stripped = hostname.replace(/^\[|\]$/g, "").replace(/\.$/, "")
+        const addresses = await lookup(stripped, { all: true })
+        return addresses.some(({ address }) => isPrivateIp(address))
     } catch {
-        return true // Invalid URL - block it
+        return true // Invalid URL or DNS failure - block it
     }
 }
 

lib/types/model-config.ts

@@ -9,6 +9,7 @@ export type ProviderName =
     | "bedrock"
     | "ollama"
     | "openrouter"
+    | "aihubmix"
     | "deepseek"
     | "siliconflow"
     | "sglang"
@@ -22,6 +23,8 @@ export type ProviderName =
     | "kimi"
     | "minimax"
     | "novita"
+    | "mimo"
+    | "atlascloud"
 
 // Individual model configuration
 export interface ModelConfig {
@@ -102,6 +105,7 @@ export const PROVIDER_LOGO_MAP: Record<string, string> = {
     azure: "azure",
     bedrock: "amazon-bedrock",
     openrouter: "openrouter",
+    aihubmix: "aihubmix",
     deepseek: "deepseek",
     siliconflow: "siliconflow",
     sglang: "openai", // SGLang is OpenAI-compatible
@@ -112,6 +116,8 @@ export const PROVIDER_LOGO_MAP: Record<string, string> = {
     modelscope: "modelscope",
     minimax: "minimax",
     novita: "novita",
+    mimo: "xiaomi",
+    atlascloud: "openai",
 }
 
 // Provider metadata
@@ -145,6 +151,10 @@ export const PROVIDER_INFO: Record<
         label: "OpenRouter",
         defaultBaseUrl: "https://openrouter.ai/api/v1",
     },
+    aihubmix: {
+        label: "AIHubMix",
+        defaultBaseUrl: "https://aihubmix.com/v1",
+    },
     deepseek: {
         label: "DeepSeek",
         defaultBaseUrl: "https://api.deepseek.com/v1",
@@ -194,6 +204,14 @@ export const PROVIDER_INFO: Record<
         label: "Novita AI",
         defaultBaseUrl: "https://api.novita.ai/openai",
     },
+    mimo: {
+        label: "MiMo (Xiaomi)",
+        defaultBaseUrl: "https://api.xiaomimimo.com/v1",
+    },
+    atlascloud: {
+        label: "Atlas Cloud",
+        defaultBaseUrl: "https://api.atlascloud.ai/v1",
+    },
 }
 
 // Suggested models per provider for quick add
@@ -317,6 +335,41 @@ export const SUGGESTED_MODELS: Partial<Record<ProviderName, string[]>> = {
         // MiniMax
         "minimax/minimax-m3",
     ],
+    aihubmix: [
+        // Fallback list. The settings UI loads the live model list from AIHubMix when available.
+        // Anthropic Claude
+        "claude-fable-5",
+        "claude-opus-4-8",
+        "claude-sonnet-4-6",
+        // OpenAI
+        "gpt-5.5",
+        "gpt-5.5-pro",
+        "gpt-5.4",
+        // Google Gemini
+        "gemini-3.5-flash",
+        "gemini-3.1-pro-preview",
+        "gemini-3-flash-preview",
+        // DeepSeek
+        "deepseek-v4-pro",
+        "deepseek-v4-flash",
+        // Qwen
+        "qwen3.7-max",
+        "qwen3-coder-next",
+        // Z.ai
+        "glm-5.1",
+        // Moonshot AI
+        "kimi-k2.6",
+        // MiniMax
+        "minimax-m3",
+        // xAI
+        "grok-4.3",
+        // Baidu
+        "ernie-5.1",
+        // Mistral
+        "mistral-large-3",
+        // Meta
+        "llama-4-maverick",
+    ],
     deepseek: [
         "deepseek-v4-pro",
         "deepseek-v4-flash",
@@ -396,6 +449,8 @@ export const SUGGESTED_MODELS: Partial<Record<ProviderName, string[]>> = {
         "moonshotai/kimi-k2.6",
         "deepseek/deepseek-v4-flash",
     ],
+    mimo: ["mimo-v2.5-pro", "mimo-v2.5"],
+    atlascloud: ["qwen/qwen3.5-flash", "deepseek-ai/deepseek-v4-pro"],
 }
 
 // Helper to generate UUID

package.json

@@ -40,6 +40,7 @@
         "@ai-sdk/google-vertex": "^4.0.16",
         "@ai-sdk/openai": "^3.0.0",
         "@ai-sdk/react": "^3.0.1",
+        "@aihubmix/ai-sdk-provider": "^2.1.0",
         "@aws-sdk/client-dynamodb": "^3.957.0",
         "@aws-sdk/credential-providers": "^3.943.0",
         "@extractus/article-extractor": "^8.0.18",
@@ -51,7 +52,7 @@
         "@opennextjs/cloudflare": "^1.17.1",
         "@openrouter/ai-sdk-provider": "^2.0.0",
         "@opentelemetry/api": "^1.9.0",
-        "@opentelemetry/exporter-trace-otlp-http": "^0.216.0",
+        "@opentelemetry/exporter-trace-otlp-http": "^0.221.0",
         "@opentelemetry/sdk-trace-node": "^2.2.0",
         "@radix-ui/react-alert-dialog": "^1.1.15",
         "@radix-ui/react-collapsible": "^1.1.12",
@@ -108,7 +109,7 @@
     },
     "devDependencies": {
         "@anthropic-ai/tokenizer": "^0.0.4",
-        "@biomejs/biome": "2.4.13",
+        "@biomejs/biome": "2.5.7",
         "@playwright/test": "^1.57.0",
         "@tailwindcss/postcss": "^4",
         "@tailwindcss/typography": "^0.5.19",
@@ -128,7 +129,7 @@
         "electron": "^39.2.7",
         "electron-builder": "^26.0.12",
         "esbuild": "^0.28.0",
-        "eslint": "9.39.4",
+        "eslint": "9.39.5",
         "eslint-config-next": "16.1.6",
         "husky": "^9.1.7",
         "jsdom": "^27.4.0",

packages/mcp-server/README.md

@@ -116,9 +116,14 @@ Use the standard MCP configuration with:
 |------|-------------|
 | `start_session` | Opens browser with real-time diagram preview |
 | `create_new_diagram` | Create a new diagram from XML (requires `xml` argument) |
+| `load_diagram` | Load a `.drawio` file from disk into the session (handles compressed files) |
 | `edit_diagram` | Edit diagram by ID-based operations (update/add/delete cells) |
 | `get_diagram` | Get the current diagram XML |
-| `export_diagram` | Save diagram to a `.drawio` file |
+| `export_diagram` | Save diagram to a `.drawio`, `.png`, or `.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) |
 
 ## How It Works
 

packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@next-ai-drawio/mcp-server",
-    "version": "0.2.0",
+    "version": "0.2.3",
     "description": "MCP server for Next AI Draw.io - AI-powered diagram generation with real-time browser preview",
     "type": "module",
     "main": "dist/index.js",
@@ -11,6 +11,8 @@
         "build": "tsc",
         "dev": "tsx watch src/index.ts",
         "start": "node dist/index.js",
+        "test": "vitest run",
+        "test:watch": "vitest",
         "prepublishOnly": "npm run build"
     },
     "keywords": [
@@ -44,7 +46,8 @@
     "devDependencies": {
         "@types/node": "^24.0.0",
         "tsx": "^4.19.0",
-        "typescript": "^5"
+        "typescript": "^5",
+        "vitest": "^4.1.8"
     },
     "engines": {
         "node": ">=18"

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

@@ -1,8 +1,14 @@
 /**
  * ID-based diagram operations
- * Copied from lib/utils.ts to avoid cross-package imports
+ *
+ * The xmlContent argument may be either a bare <mxGraphModel> (legacy) or a
+ * full <mxfile> with one or more <diagram> pages. For mxfile inputs, an
+ * optional pageSelector identifies which page to edit; when omitted, the
+ * first page is targeted (the "active page by convention" — see pages.ts).
  */
 
+import { findPageElement, hasPageSelector, type PageSelector } from "./pages.js"
+
 export interface DiagramOperation {
     operation: "update" | "add" | "delete"
     cell_id: string
@@ -22,15 +28,18 @@ export interface ApplyOperationsResult {
 
 /**
  * Apply diagram operations (update/add/delete) using ID-based lookup.
- * This replaces the text-matching approach with direct DOM manipulation.
  *
- * @param xmlContent - The full mxfile XML content
- * @param operations - Array of operations to apply
- * @returns Object with result XML and any errors
+ * @param xmlContent - The diagram XML. May be either a bare <mxGraphModel> or
+ *                     a full <mxfile> with one or more <diagram> children.
+ * @param operations - Array of operations to apply.
+ * @param pageSelector - Optional page selector for multi-page docs. Defaults
+ *                       to the first page.
+ * @returns Object with result XML (same shape as input) and any per-op errors.
  */
 export function applyDiagramOperations(
     xmlContent: string,
     operations: DiagramOperation[],
+    pageSelector?: PageSelector,
 ): ApplyOperationsResult {
     const errors: OperationError[] = []
 
@@ -53,22 +62,75 @@ export function applyDiagramOperations(
         }
     }
 
-    // Find the root element (inside mxGraphModel)
-    const root = doc.querySelector("root")
-    if (!root) {
-        return {
-            result: xmlContent,
-            errors: [
-                {
-                    type: "update",
-                    cellId: "",
-                    message: "Could not find <root> element in XML",
-                },
-            ],
+    // Locate the <root> element to operate on.
+    //
+    // - For <mxfile> input: resolve the page via pageSelector, then dive into
+    //   its <root>. This scopes querySelectorAll calls below to one page so
+    //   cells on other pages aren't accidentally matched.
+    // - For bare <mxGraphModel> input: use the document's only <root>.
+    let root: Element | null
+    if (doc.documentElement?.tagName === "mxfile") {
+        const found = findPageElement(doc as unknown as Document, pageSelector)
+        if (!found) {
+            const selDesc = hasPageSelector(pageSelector)
+                ? ` matching selector ${JSON.stringify(pageSelector)}`
+                : ""
+            return {
+                result: xmlContent,
+                errors: [
+                    {
+                        type: "update",
+                        cellId: "",
+                        message: `Page${selDesc} not found in <mxfile>`,
+                    },
+                ],
+            }
+        }
+        root = found.element.querySelector("root")
+        if (!root) {
+            const pageId =
+                found.element.getAttribute("id") || `(index ${found.index})`
+            return {
+                result: xmlContent,
+                errors: [
+                    {
+                        type: "update",
+                        cellId: "",
+                        message: `Page "${pageId}" has no <root> element`,
+                    },
+                ],
+            }
+        }
+    } else {
+        if (hasPageSelector(pageSelector)) {
+            return {
+                result: xmlContent,
+                errors: [
+                    {
+                        type: "update",
+                        cellId: "",
+                        message:
+                            "Page selector provided but document is not multi-page (no <mxfile> wrapper). Use create_new_diagram with a full <mxfile> first, or omit the page selector.",
+                    },
+                ],
+            }
+        }
+        root = doc.querySelector("root")
+        if (!root) {
+            return {
+                result: xmlContent,
+                errors: [
+                    {
+                        type: "update",
+                        cellId: "",
+                        message: "Could not find <root> element in XML",
+                    },
+                ],
+            }
         }
     }
 
-    // Build a map of cell IDs to elements
+    // Build a map of cell IDs to elements (scoped to the resolved page).
     const cellMap = new Map<string, Element>()
     root.querySelectorAll("mxCell").forEach((cell) => {
         const id = cell.getAttribute("id")
@@ -208,7 +270,9 @@ export function applyDiagramOperations(
                 cellsToDelete.add(cellId)
 
                 // Find children (cells where parent === cellId)
-                const children = root.querySelectorAll(
+                // Scoped to `root` so other pages' cells with the same parent id
+                // (notably "1") are never touched.
+                const children = root!.querySelectorAll(
                     `mxCell[parent="${cellId}"]`,
                 )
                 children.forEach((child) => {

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

@@ -0,0 +1,102 @@
+/**
+ * Workflow gate for edit_diagram.
+ *
+ * Instead of a wall-clock timeout (the old 30s rule rejected slow-but-correct
+ * clients, see #885), we compare content: `lastSeenXml` is the state-store
+ * XML the model last saw (get_diagram) or wrote itself (create_new_diagram /
+ * edit_diagram / page CRUD). The store only changes on server writes or
+ * browser pushes (user autosave, sync exports), so if the live store still
+ * matches `lastSeenXml`, nothing happened that the model hasn't seen — the
+ * edit is safe no matter how much time passed.
+ *
+ * "Matches" is structural, not byte-for-byte: draw.io re-serialises the
+ * document when it pushes state back (different attribute order, pretty-
+ * printed whitespace, regenerated diagram ids, viewport attributes like
+ * dx/dy/pageWidth on <mxGraphModel>, a different mxfile host). None of that
+ * is a user edit, so the fingerprint keeps only what a user can actually
+ * change: the set of pages, each page's name, and each page's cell tree
+ * (tags + sorted attributes + text). Byte equality is kept as a fast path.
+ */
+import { isMxGraphModel, normalizeToMxfile, parseMxfile } from "./pages.js"
+
+export type EditGateResult =
+    | { ok: true }
+    | { ok: false; reason: "no-context" | "stale" }
+
+/**
+ * Canonical serialisation of an element subtree: tag + attributes sorted by
+ * name + child elements in order + non-whitespace text. Whitespace-only text
+ * nodes (pretty-printing) are dropped.
+ */
+function canonicalizeElement(el: Element): string {
+    const attrs = Array.from(el.attributes)
+        .map((a) => `${a.name}=${JSON.stringify(a.value)}`)
+        .sort()
+        .join(" ")
+    let children = ""
+    for (const child of Array.from(el.childNodes)) {
+        if (child.nodeType === 1) {
+            children += canonicalizeElement(child as Element)
+        } else if (child.nodeType === 3 || child.nodeType === 4) {
+            const text = (child.textContent ?? "").trim()
+            if (text) children += JSON.stringify(text)
+        }
+    }
+    return `<${el.tagName} ${attrs}>${children}</${el.tagName}>`
+}
+
+/**
+ * Structural fingerprint of a diagram document: page names + each page's
+ * <root> subtree, ignoring everything draw.io rewrites on re-serialisation
+ * (mxfile/mxGraphModel attributes, diagram ids, formatting). A bare
+ * <mxGraphModel> fingerprints identically to its single-page mxfile wrapping.
+ * Unparseable input falls back to the trimmed raw string, degrading to the
+ * plain string comparison.
+ *
+ * `includeNames=false` drops page names from the fingerprint — used when the
+ * other side of a comparison is a bare <mxGraphModel>, which carries no page
+ * name at all (normalizeToMxfile would invent "Page-1", falsely mismatching
+ * any real page name).
+ */
+export function contentFingerprint(xml: string, includeNames = true): string {
+    const normalized = normalizeToMxfile(xml)
+    const doc = normalized ? parseMxfile(normalized) : null
+    if (!doc) return xml.trim()
+    const pages: string[] = []
+    doc.querySelectorAll("diagram").forEach((d) => {
+        const name = includeNames ? d.getAttribute("name") || "" : ""
+        const root = d.querySelector("root")
+        // No <root> means the page content is not plain XML (e.g. draw.io's
+        // compressed format) — fingerprint the raw text instead.
+        const body = root
+            ? canonicalizeElement(root)
+            : (d.textContent || "").trim()
+        pages.push(`${name}=${body}`)
+    })
+    return pages.join("\n")
+}
+
+export function checkEditGate(
+    lastSeenXml: string,
+    liveXml: string,
+): EditGateResult {
+    // Model never fetched or produced any diagram state in this session.
+    if (!lastSeenXml) return { ok: false, reason: "no-context" }
+    // Browser state moved since the model last looked (e.g. manual user
+    // edits): force a re-fetch so update/delete operations don't build on
+    // stale cell contents. An empty liveXml means the store has no entry to
+    // compare against, so there is nothing newer to have missed.
+    if (liveXml && liveXml !== lastSeenXml) {
+        // A bare <mxGraphModel> on either side carries no page name, so
+        // comparing names would mismatch against anything not called
+        // "Page-1". Compare cell trees only in that case.
+        const includeNames =
+            !isMxGraphModel(liveXml) && !isMxGraphModel(lastSeenXml)
+        if (
+            contentFingerprint(liveXml, includeNames) !==
+            contentFingerprint(lastSeenXml, includeNames)
+        )
+            return { ok: false, reason: "stale" }
+    }
+    return { ok: true }
+}

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

@@ -93,6 +93,7 @@ interface SessionState {
     svg?: string // Cached SVG from last browser save
     syncRequested?: number // Timestamp when sync requested, cleared when browser responds
     exportFormat?: "png" | "svg" // Set by MCP tool to request browser export
+    exportXml?: string // Single-page projection to load before a page-targeted export
     exportData?: string // Base64/SVG data returned by browser after export
 }
 
@@ -117,12 +118,37 @@ export function setState(sessionId: string, xml: string, svg?: string): number {
         svg: svg || existing?.svg, // Preserve cached SVG if not provided
         syncRequested: undefined, // Clear sync request when browser pushes state
         exportFormat: existing?.exportFormat, // Preserve pending export request
+        exportXml: existing?.exportXml, // Preserve pending projection
         exportData: existing?.exportData, // Preserve export result
     })
     log.debug(`State updated: session=${sessionId}, version=${newVersion}`)
     return newVersion
 }
 
+/**
+ * Ask the browser bridge to export the current diagram as png/svg.
+ *
+ * When `projectionXml` is given (a single-page <mxfile>), the bridge loads it
+ * first, waits for draw.io's own load event, exports, then reloads the
+ * session's real document — so a page-targeted export never mutates the
+ * canonical session state and needs no fixed-delay guessing on the server.
+ *
+ * Returns false when the session is unknown. Callers should then poll
+ * `getState(sessionId)?.exportData` for the result.
+ */
+export function requestExport(
+    sessionId: string,
+    format: "png" | "svg",
+    projectionXml?: string,
+): boolean {
+    const state = stateStore.get(sessionId)
+    if (!state) return false
+    state.exportData = undefined
+    state.exportXml = projectionXml
+    state.exportFormat = format
+    return true
+}
+
 export function requestSync(sessionId: string): boolean {
     const state = stateStore.get(sessionId)
     if (state) {
@@ -286,6 +312,7 @@ function handleStateApi(
                 version: state?.version || 0,
                 syncRequested: !!state?.syncRequested,
                 exportFormat: state?.exportFormat || null,
+                exportXml: state?.exportXml || null,
             }),
         )
     } else if (req.method === "POST") {
@@ -305,6 +332,7 @@ function handleStateApi(
                     if (state) {
                         state.exportData = data.exportData
                         state.exportFormat = undefined
+                        state.exportXml = undefined
                         log.debug(
                             `Export data received for session=${sessionId}`,
                         )
@@ -675,6 +703,8 @@ function getHtmlPage(sessionId: string): string {
         let pendingSvgExport = null;
         let pendingAiSvg = false;
         let pendingMcpExport = null; // 'png' or 'svg' when MCP requested export
+        let projectionExportActive = false; // page-targeted export: showing a transient single-page projection
+        let projectionRestoreXml = null; // the real document to reload once a projection export finishes
 
         window.addEventListener('message', (e) => {
             if (e.origin !== '${DRAWIO_ORIGIN}') return;
@@ -684,6 +714,10 @@ function getHtmlPage(sessionId: string): string {
                     isReady = true;
                     if (pendingXml) { loadDiagram(pendingXml); pendingXml = null; }
                 } else if ((msg.event === 'save' || msg.event === 'autosave') && msg.xml && msg.xml !== lastXml) {
+                    // Ignore autosave while a single-page projection is on screen
+                    // for a page-targeted export — otherwise we'd push the
+                    // transient projection back as the canonical session state.
+                    if (projectionExportActive) return;
                     // Request SVG export, then push state with SVG
                     pendingSvgExport = msg.xml;
                     iframe.contentWindow.postMessage(JSON.stringify({ action: 'export', format: 'svg' }), '*');
@@ -704,6 +738,9 @@ function getHtmlPage(sessionId: string): string {
                                 headers: { 'Content-Type': 'application/json' },
                                 body: JSON.stringify({ sessionId, exportData: d })
                             }).catch(() => {});
+                            // Page-targeted export: restore the user's real
+                            // multi-page document now that we have the image.
+                            restoreFromProjection();
                             return;
                         }
                     }
@@ -761,6 +798,22 @@ function getHtmlPage(sessionId: string): string {
             }
         }
 
+        // Restore the user's real document after a page-targeted projection
+        // export. If we never captured one (lastXml was null at projection
+        // start), fall back to forcing a reload from the server on the next
+        // poll by rewinding currentVersion — never leave the iframe stuck on
+        // the transient projection.
+        function restoreFromProjection() {
+            if (!projectionExportActive) return;
+            projectionExportActive = false;
+            if (projectionRestoreXml) {
+                iframe.contentWindow.postMessage(JSON.stringify({ action: 'load', xml: projectionRestoreXml, autosave: 1 }), '*');
+                projectionRestoreXml = null;
+            } else {
+                currentVersion = -1; // force the next poll to reload from server
+            }
+        }
+
         async function pushState(xml, svg = '') {
             if (!sessionId) return;
             try {
@@ -786,20 +839,54 @@ function getHtmlPage(sessionId: string): string {
                     pendingSyncExport = true;
                     iframe.contentWindow.postMessage(JSON.stringify({ action: 'export', format: 'xml' }), '*');
                 }
-                // Load new diagram from server (before export, so we export latest)
-                if (s.version > currentVersion && s.xml) {
+                // Load new diagram from server (before export, so we export latest).
+                // While a page-targeted projection is on screen, skip the reload
+                // so it doesn't fight the projection — and leave currentVersion
+                // unadvanced so this bump is re-detected and applied once the
+                // real document is restored.
+                if (s.version > currentVersion && s.xml && !projectionExportActive) {
                     currentVersion = s.version;
                     loadDiagram(s.xml, true);
                 }
-                // Handle export request from MCP server (png/svg) - after version update
+                // Handle export request from MCP server (png/svg).
+                //
+                // Plain export: capture whatever tab is currently displayed.
+                //
+                // Page-targeted export: the server sends a single-page <mxfile>
+                // projection in s.exportXml. We load it into the iframe, let
+                // draw.io render it, export, then reload the user's real
+                // document — all browser-side. The canonical session state is
+                // never mutated, so there is no server-side restore race and no
+                // dependence on poll timing. autosave is suppressed while the
+                // projection is showing (see projectionExportActive guard).
                 if (s.exportFormat && !pendingMcpExport && isReady) {
                     pendingMcpExport = s.exportFormat;
-                    const exportOpts = s.exportFormat === 'png'
-                        ? { action: 'export', format: 'png', scale: 2 }
-                        : { action: 'export', format: 'svg' };
-                    iframe.contentWindow.postMessage(JSON.stringify(exportOpts), '*');
-                    // Timeout: reset if draw.io never responds
-                    setTimeout(() => { if (pendingMcpExport) { pendingMcpExport = null; } }, 8000);
+                    const fireExport = () => {
+                        const exportOpts = pendingMcpExport === 'png'
+                            ? { action: 'export', format: 'png', scale: 2 }
+                            : { action: 'export', format: 'svg' };
+                        iframe.contentWindow.postMessage(JSON.stringify(exportOpts), '*');
+                    };
+                    if (s.exportXml) {
+                        // Stash the real document so we can restore after export.
+                        projectionRestoreXml = lastXml;
+                        projectionExportActive = true;
+                        // Load the projection without touching lastXml/server state.
+                        iframe.contentWindow.postMessage(JSON.stringify({ action: 'load', xml: s.exportXml, autosave: 0 }), '*');
+                        // Let draw.io render the loaded page before exporting
+                        // (same proven settle delay as the AI-preview path).
+                        setTimeout(fireExport, 600);
+                    } else {
+                        fireExport();
+                    }
+                    // Timeout: reset if draw.io never responds, and restore the
+                    // real document if a projection was left showing.
+                    setTimeout(() => {
+                        if (pendingMcpExport) {
+                            pendingMcpExport = null;
+                            restoreFromProjection();
+                        }
+                    }, 10000);
                 }
             } catch {}
         }
@@ -839,7 +926,11 @@ function getHtmlPage(sessionId: string): string {
             saveConfirmBtn.textContent = 'Exporting...';
 
             if (format === 'drawio') {
-                // Use lastXml directly instead of requesting export (avoids race with SVG exports)
+                // Use lastXml directly instead of requesting export (avoids race with SVG exports).
+                // session.xml is canonically <mxfile> after the multi-page refactor,
+                // so no wrapper injection is needed. The legacy fallback below
+                // remains only for documents that somehow slipped past
+                // normalisation (e.g. an older session loaded from external state).
                 let xmlData = lastXml || '';
                 if (xmlData && !xmlData.includes('<mxfile')) {
                     xmlData = '<mxfile host="mcp"><diagram name="Page-1">' + xmlData + '</diagram></mxfile>';

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

@@ -0,0 +1,101 @@
+/**
+ * File-loading helpers for the load_diagram tool.
+ *
+ * A .drawio file is an <mxfile> whose <diagram> children hold each page's
+ * <mxGraphModel> either as plain XML or — draw.io's default save format —
+ * compressed: encodeURIComponent(xml) → raw deflate → base64 as the
+ * diagram's text content. The rest of the server assumes plain XML inside
+ * every <diagram>, so loading decompresses all pages up front.
+ */
+import { inflateRawSync } from "node:zlib"
+import { DOMParser } from "linkedom"
+import {
+    isMxFile,
+    isMxGraphModel,
+    normalizeToMxfile,
+    parseMxfile,
+    serializeMxfile,
+} from "./pages.js"
+
+export type LoadResult =
+    | { ok: true; xml: string }
+    | { ok: false; error: string }
+
+/**
+ * Decode one compressed page body (base64 → raw deflate → URI-decode).
+ * Returns null if the text isn't in that format.
+ */
+export function decompressPageContent(compressed: string): string | null {
+    try {
+        const inflated = inflateRawSync(
+            Buffer.from(compressed.trim(), "base64"),
+        ).toString("utf-8")
+        try {
+            return decodeURIComponent(inflated)
+        } catch {
+            // Not URI-encoded (older files) — the inflated text is the XML.
+            return inflated
+        }
+    } catch {
+        return null
+    }
+}
+
+/**
+ * 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.
+ */
+export function parseDrawioFileContent(content: string): LoadResult {
+    const trimmed = content.trim()
+    if (!trimmed) return { ok: false, error: "File is empty." }
+
+    if (isMxGraphModel(trimmed)) {
+        const normalized = normalizeToMxfile(trimmed)
+        return normalized
+            ? { ok: true, xml: normalized }
+            : { ok: false, error: "Failed to parse <mxGraphModel> XML." }
+    }
+    if (!isMxFile(trimmed)) {
+        return {
+            ok: false,
+            error: "Not a draw.io file: expected an <mxfile> or <mxGraphModel> root element.",
+        }
+    }
+    const doc = parseMxfile(trimmed)
+    if (!doc) return { ok: false, error: "Failed to parse <mxfile> XML." }
+
+    let decompressedAny = false
+    for (const d of Array.from(doc.querySelectorAll("diagram"))) {
+        if (d.querySelector("mxGraphModel")) continue
+        const text = (d.textContent || "").trim()
+        if (!text) continue // an empty page is valid
+        const pageLabel =
+            d.getAttribute("name") || d.getAttribute("id") || "unnamed"
+        const xml = decompressPageContent(text)
+        if (!xml || !isMxGraphModel(xml)) {
+            return {
+                ok: false,
+                error: `Page "${pageLabel}" has content that is neither plain <mxGraphModel> XML nor draw.io's compressed format.`,
+            }
+        }
+        const inner = new DOMParser().parseFromString(xml, "text/xml")
+        if (
+            inner.querySelector("parsererror") ||
+            inner.documentElement?.tagName !== "mxGraphModel"
+        ) {
+            return {
+                ok: false,
+                error: `Page "${pageLabel}" decompressed but its XML failed to parse.`,
+            }
+        }
+        d.textContent = ""
+        d.appendChild(
+            doc.importNode(inner.documentElement as unknown as Node, true),
+        )
+        decompressedAny = true
+    }
+    // Nothing changed — keep the file's own serialisation.
+    return { ok: true, xml: decompressedAny ? serializeMxfile(doc) : trimmed }
+}

packages/mcp-server/src/pages.ts

@@ -0,0 +1,316 @@
+/**
+ * Multi-page (mxfile) helpers for draw.io diagrams.
+ *
+ * The on-disk and embed-protocol shape of a draw.io document is:
+ *
+ *   <mxfile host="...">
+ *     <diagram id="..." name="...">
+ *       <mxGraphModel><root><mxCell .../>...</root></mxGraphModel>
+ *     </diagram>
+ *     ...one or more <diagram> children...
+ *   </mxfile>
+ *
+ * This module centralises page CRUD so that index.ts, xml-validation.ts,
+ * and diagram-operations.ts can all agree on:
+ *   - what "the canonical in-memory shape" is (always mxfile),
+ *   - how to find a page (id, name, or index),
+ *   - how to add/rename/delete pages without re-parsing ad-hoc.
+ */
+
+import { DOMParser } from "linkedom"
+
+export interface PageInfo {
+    id: string
+    name: string
+    index: number
+    cellCount: number
+}
+
+/** Selector used by all multi-page-aware tools. All fields optional. */
+export interface PageSelector {
+    page_id?: string
+    page_name?: string
+    page_index?: number
+}
+
+/** True if the selector targets a specific page (any field set). */
+export function hasPageSelector(s?: PageSelector | null): boolean {
+    if (!s) return false
+    return (
+        Boolean(s.page_id) || Boolean(s.page_name) || s.page_index !== undefined
+    )
+}
+
+/**
+ * Generate a short page id similar in shape to drawio's auto-assigned ids.
+ * Format: 12 chars alphanumeric with a single dash. Not a UUID — drawio itself
+ * uses short ids; collisions are still astronomically unlikely for one session.
+ */
+export function generatePageId(): string {
+    const a = Math.random().toString(36).substring(2, 10)
+    const b = Math.random().toString(36).substring(2, 6)
+    return `${a}-${b}`
+}
+
+/** Cheap regex check — does the XML start with an <mxfile> root? */
+export function isMxFile(xml: string): boolean {
+    return /^\s*(<\?xml[^>]*\?>\s*)?<mxfile[\s>]/i.test(xml)
+}
+
+/** Cheap regex check — does the XML start with a bare <mxGraphModel>? */
+export function isMxGraphModel(xml: string): boolean {
+    return /^\s*(<\?xml[^>]*\?>\s*)?<mxGraphModel[\s>]/i.test(xml)
+}
+
+function escapeAttr(s: string): string {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+}
+
+/**
+ * Strip a leading <?xml ... ?> declaration from an XML string. The XML spec
+ * only permits the declaration at the very start of a document, so embedding
+ * a declaration inside another element produces invalid XML. Callers must
+ * strip before splicing a fragment into a wrapper.
+ */
+function stripXmlDeclaration(xml: string): string {
+    return xml.replace(/^\s*<\?xml[^>]*\?>\s*/i, "")
+}
+
+/**
+ * Wrap a bare <mxGraphModel> XML string in <mxfile><diagram>...</diagram></mxfile>.
+ * If the input is already an mxfile, returns it unchanged.
+ * If the input is neither shape, returns null so the caller can surface a clear error.
+ *
+ * Strips any leading <?xml ?> declaration before embedding — a declaration is
+ * only valid at the very start of a document, never inside a <diagram>.
+ */
+export function normalizeToMxfile(
+    xml: string,
+    opts: { pageId?: string; pageName?: string; host?: string } = {},
+): string | null {
+    const trimmed = xml.trim()
+    if (!trimmed) return null
+    if (isMxFile(trimmed)) return trimmed
+    if (!isMxGraphModel(trimmed)) return null
+
+    const pageId = opts.pageId || generatePageId()
+    const pageName = opts.pageName || "Page-1"
+    const host = opts.host || "app.diagrams.net"
+    const inner = stripXmlDeclaration(trimmed)
+    return `<mxfile host="${escapeAttr(host)}"><diagram id="${escapeAttr(pageId)}" name="${escapeAttr(pageName)}">${inner}</diagram></mxfile>`
+}
+
+/**
+ * Parse an mxfile XML string. Returns null on parse error or if the root
+ * isn't <mxfile> — callers are expected to have run normalizeToMxfile first.
+ */
+export function parseMxfile(xml: string): Document | null {
+    try {
+        const doc = new DOMParser().parseFromString(xml, "text/xml")
+        if (doc.querySelector("parsererror")) return null
+        if (doc.documentElement?.tagName !== "mxfile") return null
+        return doc as unknown as Document
+    } catch {
+        return null
+    }
+}
+
+/** Serialise an mxfile doc back to a string via the global XMLSerializer polyfill. */
+export function serializeMxfile(doc: Document): string {
+    const serializer = new XMLSerializer()
+    return serializer.serializeToString(doc)
+}
+
+export type PageProjection =
+    | { ok: true; xml: string; index: number; name: string }
+    | { ok: false; reason: "parse" | "notfound" }
+
+/**
+ * Project a single page out of an mxfile string into a standalone one-page
+ * <mxfile>. Used by get_diagram and export_diagram so the three call sites
+ * share one parse → find → serialise path.
+ *
+ * Returns { ok:false, reason:"parse" } if the xml isn't a parseable mxfile,
+ * or { ok:false, reason:"notfound" } if the selector matches no page.
+ */
+export function projectPage(
+    xml: string,
+    selector: PageSelector,
+): PageProjection {
+    const doc = parseMxfile(xml)
+    if (!doc) return { ok: false, reason: "parse" }
+    const found = findPageElement(doc, selector)
+    if (!found) return { ok: false, reason: "notfound" }
+    const serializer = new XMLSerializer()
+    return {
+        ok: true,
+        xml: `<mxfile host="app.diagrams.net">${serializer.serializeToString(found.element)}</mxfile>`,
+        index: found.index,
+        name: found.element.getAttribute("name") || "",
+    }
+}
+
+/** Walk every <diagram> child of <mxfile> and return summary info. */
+export function listPagesFromDoc(doc: Document): PageInfo[] {
+    const diagrams = doc.querySelectorAll("diagram")
+    const result: PageInfo[] = []
+    diagrams.forEach((d, idx) => {
+        const root = d.querySelector("root")
+        const cellCount = root ? root.querySelectorAll("mxCell").length : 0
+        result.push({
+            id: d.getAttribute("id") || "",
+            name: d.getAttribute("name") || `Page-${idx + 1}`,
+            index: idx,
+            cellCount,
+        })
+    })
+    return result
+}
+
+/**
+ * Resolve a page selector to its <diagram> element.
+ * Resolution order: page_id → page_name → page_index → default (first page).
+ *
+ * When no selector field is set we return the first page — the "active page
+ * by convention" mentioned in §3.4 of the design doc.
+ */
+export function findPageElement(
+    doc: Document,
+    selector?: PageSelector,
+): { element: Element; index: number } | null {
+    const diagrams = Array.from(doc.querySelectorAll("diagram"))
+    if (diagrams.length === 0) return null
+
+    if (!hasPageSelector(selector)) {
+        return { element: diagrams[0], index: 0 }
+    }
+
+    if (selector?.page_id) {
+        for (let i = 0; i < diagrams.length; i++) {
+            if (diagrams[i].getAttribute("id") === selector.page_id) {
+                return { element: diagrams[i], index: i }
+            }
+        }
+        return null
+    }
+    if (selector?.page_name) {
+        for (let i = 0; i < diagrams.length; i++) {
+            if (diagrams[i].getAttribute("name") === selector.page_name) {
+                return { element: diagrams[i], index: i }
+            }
+        }
+        return null
+    }
+    if (selector && selector.page_index !== undefined) {
+        const idx = selector.page_index
+        if (Number.isInteger(idx) && idx >= 0 && idx < diagrams.length) {
+            return { element: diagrams[idx], index: idx }
+        }
+        return null
+    }
+
+    return null
+}
+
+/**
+ * Append a new <diagram> to the mxfile doc. The new page's model defaults to
+ * an empty <mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/></root></mxGraphModel>.
+ *
+ * `opts.xml` must be a BARE <mxGraphModel> — passing a full <mxfile> would
+ * end up nested inside <diagram>, which is malformed. We reject the mxfile
+ * shape explicitly and strip any <?xml ?> declaration (only valid at
+ * document start, never inside <diagram>).
+ *
+ * Returns the new PageInfo. Throws if the requested id collides or the xml
+ * shape is wrong.
+ */
+export function addPageToDoc(
+    doc: Document,
+    opts: { id?: string; name?: string; xml?: string } = {},
+): PageInfo {
+    const existing = listPagesFromDoc(doc)
+    const id = opts.id || generatePageId()
+    if (existing.some((p) => p.id === id)) {
+        throw new Error(`Page id "${id}" already exists`)
+    }
+    const name = opts.name || `Page-${existing.length + 1}`
+
+    let inner: string
+    if (opts.xml?.trim()) {
+        const trimmed = stripXmlDeclaration(opts.xml.trim())
+        if (isMxFile(trimmed)) {
+            throw new Error(
+                "addPageToDoc: opts.xml must be a bare <mxGraphModel>; received a full <mxfile>. Extract the target diagram's <mxGraphModel> first.",
+            )
+        }
+        if (!isMxGraphModel(trimmed)) {
+            throw new Error(
+                "addPageToDoc: opts.xml must be a bare <mxGraphModel>.",
+            )
+        }
+        inner = trimmed
+    } else {
+        inner = `<mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/></root></mxGraphModel>`
+    }
+
+    const snippet = `<wrapper><diagram id="${escapeAttr(id)}" name="${escapeAttr(name)}">${inner}</diagram></wrapper>`
+    const tempDoc = new DOMParser().parseFromString(snippet, "text/xml")
+    if (tempDoc.querySelector("parsererror")) {
+        throw new Error(
+            "Failed to parse new page xml — make sure it is a valid <mxGraphModel>",
+        )
+    }
+    const newDiagram = tempDoc.querySelector("diagram")
+    if (!newDiagram) {
+        throw new Error("Failed to construct <diagram> element for new page")
+    }
+
+    const imported = doc.importNode(newDiagram, true) as Element
+    doc.documentElement.appendChild(imported)
+
+    return {
+        id,
+        name,
+        index: existing.length,
+        cellCount: imported.querySelectorAll("mxCell").length,
+    }
+}
+
+/** Rename the page matched by selector. Returns true on success. */
+export function renamePageInDoc(
+    doc: Document,
+    selector: PageSelector,
+    newName: string,
+): boolean {
+    const found = findPageElement(doc, selector)
+    if (!found) return false
+    found.element.setAttribute("name", newName)
+    return true
+}
+
+/**
+ * Delete a page. Refuses to delete the last remaining page — the embed needs
+ * at least one diagram to render anything, and silently recreating one would
+ * be surprising behaviour for an MCP caller.
+ */
+export function deletePageFromDoc(
+    doc: Document,
+    selector: PageSelector,
+): { ok: boolean; reason?: string; deletedId?: string; deletedIndex?: number } {
+    const pages = listPagesFromDoc(doc)
+    if (pages.length <= 1) {
+        return { ok: false, reason: "Cannot delete the only remaining page" }
+    }
+    const found = findPageElement(doc, selector)
+    if (!found) {
+        return { ok: false, reason: "Page not found" }
+    }
+    const id = found.element.getAttribute("id") || ""
+    const index = found.index
+    found.element.parentNode?.removeChild(found.element)
+    return { ok: true, deletedId: id, deletedIndex: index }
+}

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

@@ -119,8 +119,74 @@ function checkDuplicateAttributes(xml: string): string | null {
     return null
 }
 
-/** Check for duplicate IDs in XML */
+/**
+ * Check for duplicate IDs in XML.
+ *
+ * For multi-page documents (<mxfile> with multiple <diagram> children), cell
+ * IDs are unique **within a page**, not across the whole document — drawio
+ * legitimately reuses "0" and "1" for the root cells of every page. So we
+ * scope the cell-ID uniqueness check per <diagram>, and additionally check
+ * that the <diagram> ids themselves are unique.
+ *
+ * The legacy regex-based check is kept as a fallback for non-mxfile inputs
+ * and for XML that won't DOM-parse.
+ */
 function checkDuplicateIds(xml: string): string | null {
+    // The DOM-aware path only matters for <mxfile> wrappers; for legacy
+    // bare <mxGraphModel> inputs (the overwhelming majority of historic
+    // traffic), the cheap regex fallback at the bottom is enough. A quick
+    // string check avoids paying the DOMParser cost on every call.
+    const mightBeMxFile = /<mxfile[\s>]/i.test(xml)
+
+    // Try DOM-aware, page-scoped check first when the input looks mxfile-ish.
+    if (mightBeMxFile)
+        try {
+            const doc = new DOMParser().parseFromString(xml, "text/xml")
+            if (!doc.querySelector("parsererror")) {
+                const rootEl = doc.documentElement
+                if (rootEl && rootEl.tagName === "mxfile") {
+                    const diagrams = doc.querySelectorAll("diagram")
+
+                    // 1) <diagram> ids must be unique across the file.
+                    const diagramIds = new Map<string, number>()
+                    diagrams.forEach((d) => {
+                        const id = d.getAttribute("id")
+                        if (id)
+                            diagramIds.set(id, (diagramIds.get(id) || 0) + 1)
+                    })
+                    const dupDiagrams = Array.from(diagramIds.entries())
+                        .filter(([, c]) => c > 1)
+                        .map(([id]) => `'${id}'`)
+                    if (dupDiagrams.length > 0) {
+                        return `Invalid XML: Found duplicate <diagram> id(s): ${dupDiagrams.slice(0, 3).join(", ")}. Each page must have a unique id.`
+                    }
+
+                    // 2) Within each page, mxCell ids must be unique.
+                    for (let i = 0; i < diagrams.length; i++) {
+                        const diagram = diagrams[i]
+                        const pageId =
+                            diagram.getAttribute("id") || `(index ${i})`
+                        const cells = diagram.querySelectorAll("mxCell")
+                        const cellIds = new Map<string, number>()
+                        cells.forEach((c) => {
+                            const id = c.getAttribute("id")
+                            if (id) cellIds.set(id, (cellIds.get(id) || 0) + 1)
+                        })
+                        const dups = Array.from(cellIds.entries())
+                            .filter(([, c]) => c > 1)
+                            .map(([id, count]) => `'${id}' (${count}x)`)
+                        if (dups.length > 0) {
+                            return `Invalid XML: Found duplicate cell ID(s) in page "${pageId}": ${dups.slice(0, 3).join(", ")}. All mxCell ids must be unique within a page.`
+                        }
+                    }
+                    return null
+                }
+            }
+        } catch {
+            // fall through to regex
+        }
+
+    // Legacy regex-based check for bare <mxGraphModel> and parse-error cases.
     const idPattern = /\bid\s*=\s*["']([^"']+)["']/gi
     const ids = new Map<string, number>()
     let idMatch
@@ -770,35 +836,46 @@ export function autoFixXml(xml: string): { fixed: string; fixes: string[] } {
         fixes.push(`Fixed ${trueNestedFixed} true nested mxCell(s)`)
     }
 
-    // 22. Fix duplicate IDs by appending suffix
-    const seenIds = new Map<string, number>()
-    const duplicateIds: string[] = []
+    // 22. Fix duplicate IDs by appending suffix.
+    // Skipped for multi-page <mxfile> documents — cell ids "0" and "1" repeat
+    // across pages legitimately (every page has its own <root> with id="0"/"1"
+    // sentinel cells). Renaming them would break drawio's parent references.
+    // For mxfile inputs, duplicate-id validation is page-scoped in
+    // checkDuplicateIds() and a true duplicate produces a hard error rather
+    // than a silent rename.
+    if (!/<mxfile[\s>]/i.test(fixed)) {
+        const seenIds = new Map<string, number>()
+        const duplicateIds: string[] = []
 
-    const idPattern = /\bid\s*=\s*["']([^"']+)["']/gi
-    let idMatch
-    while ((idMatch = idPattern.exec(fixed)) !== null) {
-        const id = idMatch[1]
-        seenIds.set(id, (seenIds.get(id) || 0) + 1)
-    }
+        const idPattern = /\bid\s*=\s*["']([^"']+)["']/gi
+        let idMatch
+        while ((idMatch = idPattern.exec(fixed)) !== null) {
+            const id = idMatch[1]
+            seenIds.set(id, (seenIds.get(id) || 0) + 1)
+        }
 
-    for (const [id, count] of seenIds) {
-        if (count > 1) duplicateIds.push(id)
-    }
+        for (const [id, count] of seenIds) {
+            if (count > 1) duplicateIds.push(id)
+        }
 
-    if (duplicateIds.length > 0) {
-        const idCounters = new Map<string, number>()
-        fixed = fixed.replace(/\bid\s*=\s*["']([^"']+)["']/gi, (match, id) => {
-            if (!duplicateIds.includes(id)) return match
+        if (duplicateIds.length > 0) {
+            const idCounters = new Map<string, number>()
+            fixed = fixed.replace(
+                /\bid\s*=\s*["']([^"']+)["']/gi,
+                (match, id) => {
+                    if (!duplicateIds.includes(id)) return match
 
-            const count = idCounters.get(id) || 0
-            idCounters.set(id, count + 1)
+                    const count = idCounters.get(id) || 0
+                    idCounters.set(id, count + 1)
 
-            if (count === 0) return match
+                    if (count === 0) return match
 
-            const newId = `${id}_dup${count}`
-            return match.replace(id, newId)
-        })
-        fixes.push(`Renamed ${duplicateIds.length} duplicate ID(s)`)
+                    const newId = `${id}_dup${count}`
+                    return match.replace(id, newId)
+                },
+            )
+            fixes.push(`Renamed ${duplicateIds.length} duplicate ID(s)`)
+        }
     }
 
     // 23. Fix empty id attributes

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

@@ -0,0 +1,132 @@
+/**
+ * Unit tests for the edit_diagram workflow gate (edit-gate.ts).
+ *
+ * The gate replaced the old 30-second wall-clock rule (#885): an edit is
+ * allowed when the model has seen the current browser state, no matter how
+ * long ago — and rejected when the browser state moved since. "Seen" is
+ * judged structurally, so draw.io's re-serialisation of the same content
+ * (attribute order, whitespace, viewport attributes, wrapper shape) never
+ * reads as a user edit.
+ */
+
+import { DOMParser } from "linkedom"
+import { beforeAll, describe, expect, it } from "vitest"
+
+beforeAll(() => {
+    ;(globalThis as any).DOMParser = DOMParser
+})
+
+import { checkEditGate, contentFingerprint } from "../src/edit-gate.js"
+
+const XML_A = `<mxfile host="app.diagrams.net"><diagram id="p1" name="Page-1"><mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/><mxCell id="box1" value="Hello" style="rounded=0;" vertex="1" parent="1"><mxGeometry x="40" y="40" width="120" height="60" as="geometry"/></mxCell></root></mxGraphModel></diagram></mxfile>`
+
+// The same document as draw.io re-serialises it on autosave: different host,
+// regenerated diagram id, viewport attributes on mxGraphModel, re-ordered
+// cell attributes, pretty-printed whitespace.
+const XML_A_RESERIALIZED = `<mxfile host="embed.diagrams.net">
+  <diagram id="regenerated-id" name="Page-1">
+    <mxGraphModel dx="1596" dy="743" grid="1" pageWidth="827" pageHeight="1169">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="box1" parent="1" style="rounded=0;" value="Hello" vertex="1">
+          <mxGeometry height="60" width="120" x="40" y="40" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>`
+
+// A real user edit: box1 moved to a different position.
+const XML_B = XML_A.replace('x="40" y="40"', 'x="300" y="200"')
+
+// Bare mxGraphModel with identical page content to XML_A.
+const XML_A_BARE = `<mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/><mxCell id="box1" value="Hello" style="rounded=0;" vertex="1" parent="1"><mxGeometry x="40" y="40" width="120" height="60" as="geometry"/></mxCell></root></mxGraphModel>`
+
+describe("checkEditGate", () => {
+    it("rejects when no diagram context was ever established", () => {
+        expect(checkEditGate("", XML_A)).toEqual({
+            ok: false,
+            reason: "no-context",
+        })
+    })
+
+    it("allows when the browser state is exactly what the model saw", () => {
+        expect(checkEditGate(XML_A, XML_A)).toEqual({ ok: true })
+    })
+
+    it("allows when the browser state is a re-serialisation of the same content", () => {
+        expect(checkEditGate(XML_A, XML_A_RESERIALIZED)).toEqual({ ok: true })
+    })
+
+    it("rejects when a cell actually changed", () => {
+        expect(checkEditGate(XML_A, XML_B)).toEqual({
+            ok: false,
+            reason: "stale",
+        })
+    })
+
+    it("rejects a real edit even when wrapped in re-serialisation noise", () => {
+        const movedAndReserialized = XML_A_RESERIALIZED.replace(
+            'x="40" y="40"',
+            'x="300" y="200"',
+        )
+        expect(checkEditGate(XML_A, movedAndReserialized)).toEqual({
+            ok: false,
+            reason: "stale",
+        })
+    })
+
+    it("allows when the store has no live entry to compare against", () => {
+        expect(checkEditGate(XML_A, "")).toEqual({ ok: true })
+    })
+
+    // A bare <mxGraphModel> push carries no page name, so the gate must not
+    // compare the invented "Page-1" wrapper name against the real one.
+    it("allows a bare mxGraphModel push when the page has a custom name", () => {
+        const seenRenamed = XML_A.replace('name="Page-1"', 'name="Arch"')
+        expect(checkEditGate(seenRenamed, XML_A_BARE)).toEqual({ ok: true })
+    })
+
+    it("still rejects a bare mxGraphModel push whose cells changed", () => {
+        const seenRenamed = XML_A.replace('name="Page-1"', 'name="Arch"')
+        const bareMoved = XML_A_BARE.replace('x="40" y="40"', 'x="300" y="200"')
+        expect(checkEditGate(seenRenamed, bareMoved)).toEqual({
+            ok: false,
+            reason: "stale",
+        })
+    })
+})
+
+describe("contentFingerprint", () => {
+    it("is invariant under draw.io re-serialisation", () => {
+        expect(contentFingerprint(XML_A)).toBe(
+            contentFingerprint(XML_A_RESERIALIZED),
+        )
+    })
+
+    it("treats a bare mxGraphModel like its one-page mxfile wrapping", () => {
+        expect(contentFingerprint(XML_A_BARE)).toBe(contentFingerprint(XML_A))
+    })
+
+    it("changes when a cell attribute changes", () => {
+        expect(contentFingerprint(XML_A)).not.toBe(contentFingerprint(XML_B))
+    })
+
+    it("changes when a page is renamed", () => {
+        const renamed = XML_A.replace('name="Page-1"', 'name="Renamed"')
+        expect(contentFingerprint(XML_A)).not.toBe(contentFingerprint(renamed))
+    })
+
+    it("changes when a page is added", () => {
+        const twoPages = XML_A.replace(
+            "</mxfile>",
+            `<diagram id="p2" name="Page-2"><mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/></root></mxGraphModel></diagram></mxfile>`,
+        )
+        expect(contentFingerprint(XML_A)).not.toBe(contentFingerprint(twoPages))
+    })
+
+    it("falls back to the raw string for unparseable input", () => {
+        expect(contentFingerprint("not xml at all")).toBe("not xml at all")
+    })
+})

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

@@ -0,0 +1,126 @@
+/**
+ * Unit tests for load_diagram's file parsing (load-diagram.ts).
+ *
+ * A .drawio file stores each page's <mxGraphModel> either as plain XML or
+ * as draw.io's compressed default (encodeURIComponent → raw deflate →
+ * base64 text content). The loader must produce the canonical session
+ * shape: an <mxfile> whose every page is plain XML.
+ */
+
+import { deflateRawSync } from "node:zlib"
+import { DOMParser } from "linkedom"
+import { beforeAll, describe, expect, it } from "vitest"
+
+// Install the DOM polyfills exactly as index.ts does at runtime.
+beforeAll(() => {
+    ;(globalThis as any).DOMParser = DOMParser
+    class XMLSerializerPolyfill {
+        serializeToString(node: any): string {
+            if (node.outerHTML !== undefined) return node.outerHTML
+            if (node.documentElement) return node.documentElement.outerHTML
+            return ""
+        }
+    }
+    ;(globalThis as any).XMLSerializer = XMLSerializerPolyfill
+})
+
+import {
+    decompressPageContent,
+    parseDrawioFileContent,
+} from "../src/load-diagram.js"
+
+const MODEL_XML = `<mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/><mxCell id="box1" value="Hello" style="rounded=0;" vertex="1" parent="1"><mxGeometry x="40" y="40" width="120" height="60" as="geometry"/></mxCell></root></mxGraphModel>`
+
+/** Compress a page body exactly the way draw.io does when saving. */
+function drawioCompress(xml: string): string {
+    return deflateRawSync(
+        Buffer.from(encodeURIComponent(xml), "utf-8"),
+    ).toString("base64")
+}
+
+const PLAIN_MXFILE = `<mxfile host="app.diagrams.net"><diagram id="p1" name="Page-1">${MODEL_XML}</diagram></mxfile>`
+const COMPRESSED_MXFILE = `<mxfile host="app.diagrams.net" compressed="true"><diagram id="p1" name="Page-1">${drawioCompress(MODEL_XML)}</diagram></mxfile>`
+
+describe("decompressPageContent", () => {
+    it("round-trips draw.io's compressed format", () => {
+        expect(decompressPageContent(drawioCompress(MODEL_XML))).toBe(MODEL_XML)
+    })
+
+    it("handles non-URI-encoded legacy payloads", () => {
+        const legacy = deflateRawSync(Buffer.from(MODEL_XML, "utf-8")).toString(
+            "base64",
+        )
+        expect(decompressPageContent(legacy)).toBe(MODEL_XML)
+    })
+
+    it("returns null for garbage", () => {
+        expect(decompressPageContent("not base64 deflate")).toBeNull()
+    })
+})
+
+describe("parseDrawioFileContent", () => {
+    it("passes a plain-XML mxfile through unchanged", () => {
+        const r = parseDrawioFileContent(PLAIN_MXFILE)
+        expect(r).toEqual({ ok: true, xml: PLAIN_MXFILE })
+    })
+
+    it("wraps a bare mxGraphModel into a one-page mxfile", () => {
+        const r = parseDrawioFileContent(MODEL_XML)
+        expect(r.ok).toBe(true)
+        if (r.ok) {
+            expect(r.xml).toContain("<mxfile")
+            expect(r.xml).toContain('value="Hello"')
+        }
+    })
+
+    it("decompresses a compressed mxfile into plain XML pages", () => {
+        const r = parseDrawioFileContent(COMPRESSED_MXFILE)
+        expect(r.ok).toBe(true)
+        if (r.ok) {
+            expect(r.xml).toContain("<mxGraphModel")
+            expect(r.xml).toContain('value="Hello"')
+            // The compressed blob must be gone.
+            expect(r.xml).not.toContain(drawioCompress(MODEL_XML))
+        }
+    })
+
+    it("decompresses only the compressed pages of a mixed 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) {
+            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()
+            }
+        }
+    })
+
+    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 })
+    })
+
+    it("rejects empty files", () => {
+        const r = parseDrawioFileContent("   ")
+        expect(r.ok).toBe(false)
+    })
+
+    it("rejects non-drawio content", () => {
+        const r = parseDrawioFileContent("<svg><rect/></svg>")
+        expect(r.ok).toBe(false)
+        if (!r.ok) expect(r.error).toContain("Not a draw.io file")
+    })
+
+    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)
+        expect(r.ok).toBe(false)
+        if (!r.ok) expect(r.error).toContain('"Broken"')
+    })
+})

packages/mcp-server/tests/multi-page.test.ts

@@ -0,0 +1,545 @@
+/**
+ * Unit tests for multi-page (mxfile) support.
+ *
+ * Pinned to the user-visible contract described in
+ * multi-page-mcp-support-plan.md §5 (acceptance criteria):
+ *
+ *   AC1. create_new_diagram accepts both bare <mxGraphModel> and full <mxfile>.
+ *   AC2. get_diagram returns the full <mxfile> regardless of page count.
+ *   AC3. edit_diagram accepts an optional page selector.
+ *   AC6. Two tool calls reproduce the Transformer/CNN scenario.
+ *   AC9. The wrapper-injection hack at http-server.ts:845 is unnecessary.
+ *
+ * These tests pin the helpers (pages.ts), the validator update
+ * (xml-validation.ts), and the page-targeted edit logic
+ * (diagram-operations.ts) — i.e. the layers underneath the MCP tool surface.
+ */
+
+import { DOMParser } from "linkedom"
+import { beforeAll, describe, expect, it } from "vitest"
+
+// Install the DOM polyfill exactly as index.ts does at runtime — the
+// helpers under test rely on it.
+beforeAll(() => {
+    ;(globalThis as any).DOMParser = DOMParser
+    class XMLSerializerPolyfill {
+        serializeToString(node: any): string {
+            if (node.outerHTML !== undefined) return node.outerHTML
+            if (node.documentElement) return node.documentElement.outerHTML
+            return ""
+        }
+    }
+    ;(globalThis as any).XMLSerializer = XMLSerializerPolyfill
+})
+
+import { applyDiagramOperations } from "../src/diagram-operations.js"
+import {
+    addPageToDoc,
+    deletePageFromDoc,
+    findPageElement,
+    generatePageId,
+    hasPageSelector,
+    isMxFile,
+    isMxGraphModel,
+    listPagesFromDoc,
+    normalizeToMxfile,
+    parseMxfile,
+    projectPage,
+    renamePageInDoc,
+    serializeMxfile,
+} from "../src/pages.js"
+import { validateAndFixXml } from "../src/xml-validation.js"
+
+const BARE_MODEL_ONE_CELL = `<mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/><mxCell id="2" vertex="1" parent="1" value="Hello"><mxGeometry x="40" y="40" width="100" height="40" as="geometry"/></mxCell></root></mxGraphModel>`
+
+const TWO_PAGE_MXFILE = `<mxfile host="app.diagrams.net"><diagram id="page-transformer" name="Transformer"><mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/><mxCell id="2" vertex="1" parent="1" value="Encoder"><mxGeometry x="40" y="40" width="120" height="60" as="geometry"/></mxCell></root></mxGraphModel></diagram><diagram id="page-cnn" name="CNN"><mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/><mxCell id="2" vertex="1" parent="1" value="Conv1"><mxGeometry x="40" y="40" width="120" height="60" as="geometry"/></mxCell></root></mxGraphModel></diagram></mxfile>`
+
+describe("pages.ts — shape detection", () => {
+    it("isMxFile detects a multi-page mxfile", () => {
+        expect(isMxFile(TWO_PAGE_MXFILE)).toBe(true)
+    })
+
+    it("isMxFile rejects a bare mxGraphModel", () => {
+        expect(isMxFile(BARE_MODEL_ONE_CELL)).toBe(false)
+    })
+
+    it("isMxGraphModel detects a bare model", () => {
+        expect(isMxGraphModel(BARE_MODEL_ONE_CELL)).toBe(true)
+        expect(isMxGraphModel(TWO_PAGE_MXFILE)).toBe(false)
+    })
+
+    it("isMxFile tolerates an XML declaration prefix", () => {
+        expect(
+            isMxFile(
+                `<?xml version="1.0" encoding="UTF-8"?>${TWO_PAGE_MXFILE}`,
+            ),
+        ).toBe(true)
+    })
+})
+
+describe("pages.ts — normalizeToMxfile (backward compatibility, AC1)", () => {
+    it("wraps a bare mxGraphModel into a single-page mxfile", () => {
+        const out = normalizeToMxfile(BARE_MODEL_ONE_CELL, {
+            pageId: "p1",
+            pageName: "Page-1",
+        })
+        expect(out).not.toBeNull()
+        expect(out).toMatch(/^<mxfile/)
+        expect(out).toContain(`<diagram id="p1" name="Page-1">`)
+        expect(out).toContain("<mxGraphModel>")
+    })
+
+    it("returns mxfile inputs unchanged", () => {
+        const out = normalizeToMxfile(TWO_PAGE_MXFILE)
+        expect(out).toBe(TWO_PAGE_MXFILE)
+    })
+
+    it("returns null for neither shape", () => {
+        expect(normalizeToMxfile("<random/>")).toBeNull()
+        expect(normalizeToMxfile("")).toBeNull()
+    })
+
+    it("generated page ids look reasonable", () => {
+        for (let i = 0; i < 50; i++) {
+            const id = generatePageId()
+            expect(id).toMatch(/^[a-z0-9]+-[a-z0-9]+$/)
+        }
+    })
+
+    it("strips a leading <?xml ?> declaration when wrapping a bare model", () => {
+        // Regression for the bug Copilot caught: isMxGraphModel tolerates a
+        // declaration prefix, but the wrapper used to embed it inside
+        // <diagram>, producing invalid XML (<?xml ?> is only valid at the
+        // document start). The result must round-trip through parseMxfile
+        // and the declaration must be gone from inside <diagram>.
+        const withDecl = `<?xml version="1.0" encoding="UTF-8"?>${BARE_MODEL_ONE_CELL}`
+        const out = normalizeToMxfile(withDecl, {
+            pageId: "p1",
+            pageName: "Page-1",
+        })
+        expect(out).not.toBeNull()
+        expect(out).toMatch(/^<mxfile/)
+        // No <?xml inside the body of the wrapped document.
+        expect(out!.indexOf("<?xml")).toBe(-1)
+        // And it must still parse cleanly.
+        const doc = parseMxfile(out!)
+        expect(doc).not.toBeNull()
+        expect(listPagesFromDoc(doc!)).toHaveLength(1)
+    })
+})
+
+describe("pages.ts — addPageToDoc input validation", () => {
+    it("rejects opts.xml shaped as a full <mxfile>", () => {
+        // Regression for the Copilot-flagged bug: an mxfile passed as
+        // starting page xml would end up nested inside <diagram>, corrupting
+        // the document. Must throw with a clear message.
+        const doc = parseMxfile(TWO_PAGE_MXFILE)!
+        expect(() =>
+            addPageToDoc(doc, { name: "Bad", xml: TWO_PAGE_MXFILE }),
+        ).toThrowError(/bare <mxGraphModel>/i)
+    })
+
+    it("rejects opts.xml that is neither mxGraphModel nor mxfile", () => {
+        const doc = parseMxfile(TWO_PAGE_MXFILE)!
+        expect(() =>
+            addPageToDoc(doc, { name: "Junk", xml: "<root><x/></root>" }),
+        ).toThrowError(/bare <mxGraphModel>/i)
+    })
+
+    it("strips a <?xml ?> declaration prefix on opts.xml", () => {
+        const doc = parseMxfile(TWO_PAGE_MXFILE)!
+        const withDecl = `<?xml version="1.0"?>${BARE_MODEL_ONE_CELL}`
+        const info = addPageToDoc(doc, { name: "Sequence", xml: withDecl })
+        expect(info.cellCount).toBeGreaterThanOrEqual(3)
+        // Serialised document must not have <?xml ?> inside <diagram>.
+        const out = serializeMxfile(doc)
+        // The mxfile may have one <?xml ?> at the very start (the doc decl),
+        // but no further occurrence inside <diagram>.
+        const matches = out.match(/<\?xml/g) || []
+        expect(matches.length).toBeLessThanOrEqual(1)
+    })
+})
+
+describe("pages.ts — listPagesFromDoc / findPageElement", () => {
+    it("lists both pages in a two-page mxfile", () => {
+        const doc = parseMxfile(TWO_PAGE_MXFILE)!
+        const pages = listPagesFromDoc(doc)
+        expect(pages).toHaveLength(2)
+        expect(pages[0]).toMatchObject({
+            id: "page-transformer",
+            name: "Transformer",
+            index: 0,
+        })
+        expect(pages[1]).toMatchObject({
+            id: "page-cnn",
+            name: "CNN",
+            index: 1,
+        })
+        // Cell count is per-page (3 cells per page including the two root sentinels).
+        expect(pages[0].cellCount).toBe(3)
+        expect(pages[1].cellCount).toBe(3)
+    })
+
+    it("findPageElement defaults to the first page when selector is empty", () => {
+        const doc = parseMxfile(TWO_PAGE_MXFILE)!
+        const found = findPageElement(doc)
+        expect(found?.index).toBe(0)
+        expect(found?.element.getAttribute("id")).toBe("page-transformer")
+    })
+
+    it("findPageElement matches by id, name, and index — id wins when several are set", () => {
+        const doc = parseMxfile(TWO_PAGE_MXFILE)!
+        expect(findPageElement(doc, { page_id: "page-cnn" })?.index).toBe(1)
+        expect(findPageElement(doc, { page_name: "CNN" })?.index).toBe(1)
+        expect(findPageElement(doc, { page_index: 1 })?.index).toBe(1)
+        // id beats name beats index
+        const winner = findPageElement(doc, {
+            page_id: "page-cnn",
+            page_name: "Transformer",
+            page_index: 0,
+        })
+        expect(winner?.index).toBe(1)
+    })
+
+    it("findPageElement returns null for an unknown selector", () => {
+        const doc = parseMxfile(TWO_PAGE_MXFILE)!
+        expect(findPageElement(doc, { page_id: "ghost" })).toBeNull()
+        expect(findPageElement(doc, { page_name: "ghost" })).toBeNull()
+        expect(findPageElement(doc, { page_index: 99 })).toBeNull()
+        expect(findPageElement(doc, { page_index: -1 })).toBeNull()
+    })
+
+    it("hasPageSelector correctly detects empty vs populated selectors", () => {
+        expect(hasPageSelector()).toBe(false)
+        expect(hasPageSelector({})).toBe(false)
+        expect(hasPageSelector({ page_id: "x" })).toBe(true)
+        expect(hasPageSelector({ page_index: 0 })).toBe(true)
+    })
+})
+
+describe("pages.ts — addPageToDoc", () => {
+    it("appends a third page and returns its info", () => {
+        const doc = parseMxfile(TWO_PAGE_MXFILE)!
+        const info = addPageToDoc(doc, { name: "Sequence" })
+        expect(info.name).toBe("Sequence")
+        expect(info.index).toBe(2)
+        expect(info.id).toMatch(/.+/)
+        const pages = listPagesFromDoc(doc)
+        expect(pages).toHaveLength(3)
+        expect(pages[2].name).toBe("Sequence")
+    })
+
+    it("rejects a duplicate explicit id", () => {
+        const doc = parseMxfile(TWO_PAGE_MXFILE)!
+        expect(() =>
+            addPageToDoc(doc, { id: "page-transformer", name: "X" }),
+        ).toThrowError(/already exists/)
+    })
+
+    it("uses a sensible default name when none is supplied", () => {
+        const doc = parseMxfile(TWO_PAGE_MXFILE)!
+        const info = addPageToDoc(doc, {})
+        expect(info.name).toBe("Page-3")
+    })
+
+    it("accepts an inline starting mxGraphModel", () => {
+        const doc = parseMxfile(TWO_PAGE_MXFILE)!
+        const inner = `<mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/><mxCell id="2" vertex="1" parent="1" value="A"><mxGeometry x="10" y="10" width="20" height="20" as="geometry"/></mxCell></root></mxGraphModel>`
+        const info = addPageToDoc(doc, { name: "Custom", xml: inner })
+        expect(info.cellCount).toBeGreaterThanOrEqual(3)
+    })
+})
+
+describe("pages.ts — renamePageInDoc / deletePageFromDoc", () => {
+    it("renames an existing page by name", () => {
+        const doc = parseMxfile(TWO_PAGE_MXFILE)!
+        const ok = renamePageInDoc(doc, { page_name: "CNN" }, "CNN-v2")
+        expect(ok).toBe(true)
+        const pages = listPagesFromDoc(doc)
+        expect(pages[1].name).toBe("CNN-v2")
+    })
+
+    it("rename returns false when target page is missing", () => {
+        const doc = parseMxfile(TWO_PAGE_MXFILE)!
+        expect(renamePageInDoc(doc, { page_id: "ghost" }, "Z")).toBe(false)
+    })
+
+    it("deletes a page and removes the <diagram> element from the doc", () => {
+        const doc = parseMxfile(TWO_PAGE_MXFILE)!
+        const outcome = deletePageFromDoc(doc, { page_id: "page-cnn" })
+        expect(outcome.ok).toBe(true)
+        expect(outcome.deletedId).toBe("page-cnn")
+        expect(listPagesFromDoc(doc)).toHaveLength(1)
+    })
+
+    it("refuses to delete the only remaining page", () => {
+        // Build a single-page doc to test the guard.
+        const single = normalizeToMxfile(BARE_MODEL_ONE_CELL)!
+        const doc = parseMxfile(single)!
+        const outcome = deletePageFromDoc(doc, { page_index: 0 })
+        expect(outcome.ok).toBe(false)
+        expect(outcome.reason).toMatch(/only remaining page/)
+    })
+})
+
+describe("xml-validation.ts — multi-page support", () => {
+    it("accepts a valid two-page mxfile (the exact payload that used to fail)", () => {
+        const result = validateAndFixXml(TWO_PAGE_MXFILE)
+        expect(result.valid).toBe(true)
+        expect(result.error).toBeNull()
+    })
+
+    it("does NOT flag root sentinel ids 0 and 1 repeating across pages", () => {
+        // This is the regression the planning doc explicitly called out:
+        // before this work, the legacy regex-based duplicate-id check rejected
+        // any multi-page document because cells "0" and "1" appear in every page.
+        const result = validateAndFixXml(TWO_PAGE_MXFILE)
+        expect(result.valid).toBe(true)
+    })
+
+    it("rejects duplicate cell ids WITHIN a single page", () => {
+        const bad = `<mxfile host="app.diagrams.net"><diagram id="p1" name="P1"><mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/><mxCell id="dup" vertex="1" parent="1"/><mxCell id="dup" vertex="1" parent="1"/></root></mxGraphModel></diagram></mxfile>`
+        const result = validateAndFixXml(bad)
+        expect(result.valid).toBe(false)
+        expect(result.error).toMatch(/duplicate cell ID/i)
+    })
+
+    it("rejects duplicate <diagram> ids across the file", () => {
+        const bad = `<mxfile host="app.diagrams.net"><diagram id="p1" name="A"><mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/></root></mxGraphModel></diagram><diagram id="p1" name="B"><mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/></root></mxGraphModel></diagram></mxfile>`
+        const result = validateAndFixXml(bad)
+        expect(result.valid).toBe(false)
+        expect(result.error).toMatch(/duplicate <diagram> id/i)
+    })
+
+    it("still validates a bare <mxGraphModel> (legacy callers)", () => {
+        const result = validateAndFixXml(BARE_MODEL_ONE_CELL)
+        expect(result.valid).toBe(true)
+    })
+
+    it("auto-fix does NOT rename mxfile root cells 0/1 (would break drawio refs)", () => {
+        // Build a doc that triggers some other auto-fix (so autoFixXml runs)
+        // but contains valid multi-page 0/1 cells that must NOT be renamed.
+        const malformedButMultiPage = `<mxfile host="app.diagrams.net"><diagram id="p1" name="A"><mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/><mxCell id="2" vertex="1" parent="1" value="Q & A"><mxGeometry x="0" y="0" width="10" height="10" as="geometry"/></mxCell></root></mxGraphModel></diagram><diagram id="p2" name="B"><mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/></root></mxGraphModel></diagram></mxfile>`
+        const result = validateAndFixXml(malformedButMultiPage)
+        // The doc has an unescaped & — autoFix will repair that. After repair
+        // it should be valid AND must not have renamed the 0/1 cells.
+        const finalXml = result.fixed || malformedButMultiPage
+        expect(finalXml).not.toMatch(/id="0_dup/)
+        expect(finalXml).not.toMatch(/id="1_dup/)
+    })
+})
+
+describe("diagram-operations.ts — page-targeted edits (AC3)", () => {
+    it("adds a cell to the targeted page by id, leaving the other page untouched", () => {
+        const { result, errors } = applyDiagramOperations(
+            TWO_PAGE_MXFILE,
+            [
+                {
+                    operation: "add",
+                    cell_id: "conv-2",
+                    new_xml: `<mxCell id="conv-2" vertex="1" parent="1" value="Conv2"><mxGeometry x="200" y="40" width="120" height="60" as="geometry"/></mxCell>`,
+                },
+            ],
+            { page_id: "page-cnn" },
+        )
+        expect(errors).toHaveLength(0)
+        const doc = parseMxfile(result)!
+        const pages = listPagesFromDoc(doc)
+        // Transformer untouched (still 3 cells), CNN gained one cell.
+        expect(pages[0].cellCount).toBe(3)
+        expect(pages[1].cellCount).toBe(4)
+        expect(result).toContain(`id="conv-2"`)
+    })
+
+    it("defaults to the first page when no selector is given", () => {
+        const { result, errors } = applyDiagramOperations(TWO_PAGE_MXFILE, [
+            {
+                operation: "add",
+                cell_id: "shape-x",
+                new_xml: `<mxCell id="shape-x" vertex="1" parent="1"><mxGeometry x="0" y="0" width="10" height="10" as="geometry"/></mxCell>`,
+            },
+        ])
+        expect(errors).toHaveLength(0)
+        const doc = parseMxfile(result)!
+        const pages = listPagesFromDoc(doc)
+        expect(pages[0].cellCount).toBe(4) // Transformer (first page) grew
+        expect(pages[1].cellCount).toBe(3) // CNN untouched
+    })
+
+    it("errors clearly when the page is not found", () => {
+        const { errors } = applyDiagramOperations(
+            TWO_PAGE_MXFILE,
+            [
+                {
+                    operation: "delete",
+                    cell_id: "2",
+                },
+            ],
+            { page_id: "does-not-exist" },
+        )
+        expect(errors).toHaveLength(1)
+        expect(errors[0].message).toMatch(/Page.*not found/i)
+        // Page-level errors carry an empty cellId — edit_diagram relies on
+        // this to distinguish "nothing applied" from per-cell warnings and
+        // return a hard error instead of a false success.
+        expect(errors[0].cellId).toBe("")
+    })
+
+    it("delete on page 2 does NOT touch page 1's mxCell with the same id", () => {
+        // Both pages have a cell with id="2". A delete on CNN's "2" must not
+        // remove Transformer's "2".
+        const { result, errors } = applyDiagramOperations(
+            TWO_PAGE_MXFILE,
+            [{ operation: "delete", cell_id: "2" }],
+            { page_id: "page-cnn" },
+        )
+        expect(errors).toHaveLength(0)
+        const doc = parseMxfile(result)!
+        const pages = listPagesFromDoc(doc)
+        // CNN lost its only non-sentinel cell, Transformer keeps its three.
+        expect(pages[1].cellCount).toBe(2)
+        expect(pages[0].cellCount).toBe(3)
+    })
+
+    it("legacy bare-mxGraphModel input still works when no selector is given", () => {
+        const { result, errors } = applyDiagramOperations(BARE_MODEL_ONE_CELL, [
+            {
+                operation: "add",
+                cell_id: "new",
+                new_xml: `<mxCell id="new" vertex="1" parent="1"><mxGeometry x="100" y="100" width="50" height="50" as="geometry"/></mxCell>`,
+            },
+        ])
+        expect(errors).toHaveLength(0)
+        expect(result).toContain(`id="new"`)
+    })
+
+    it("page selector on a bare mxGraphModel returns a clear error", () => {
+        const { errors } = applyDiagramOperations(
+            BARE_MODEL_ONE_CELL,
+            [{ operation: "delete", cell_id: "2" }],
+            { page_id: "page-1" },
+        )
+        expect(errors).toHaveLength(1)
+        expect(errors[0].message).toMatch(/not multi-page/i)
+    })
+})
+
+describe("export_diagram — single-page projection (regression for selectPage bug)", () => {
+    // The previous implementation tried to drive drawio's iframe with an
+    // `action: 'selectPage'` postMessage, which the embed protocol silently
+    // ignores. The result was that PNG/SVG exports targeted the currently
+    // active tab regardless of the page selector — two visually different
+    // pages would yield byte-identical PNGs.
+    //
+    // The current implementation builds a single-page <mxfile> projection via
+    // the shared pages.ts:projectPage helper and hands it to the browser
+    // bridge to load BEFORE triggering export. These tests pin that helper so
+    // a future refactor can't silently re-introduce the multi-page drift.
+    function projectSinglePage(fullMxfile: string, sel: any): string {
+        const result = projectPage(fullMxfile, sel)
+        if (!result.ok) throw new Error(`projection failed: ${result.reason}`)
+        return result.xml
+    }
+
+    it("returns a parse error for a non-mxfile source", () => {
+        const result = projectPage(BARE_MODEL_ONE_CELL, { page_id: "x" })
+        expect(result.ok).toBe(false)
+        if (!result.ok) expect(result.reason).toBe("parse")
+    })
+
+    it("returns a notfound error for an unknown page", () => {
+        const result = projectPage(TWO_PAGE_MXFILE, { page_id: "ghost" })
+        expect(result.ok).toBe(false)
+        if (!result.ok) expect(result.reason).toBe("notfound")
+    })
+
+    it("projects only the requested page when targeted by id", () => {
+        const projected = projectSinglePage(TWO_PAGE_MXFILE, {
+            page_id: "page-cnn",
+        })
+        const pages = listPagesFromDoc(parseMxfile(projected)!)
+        expect(pages).toHaveLength(1)
+        expect(pages[0].id).toBe("page-cnn")
+        expect(pages[0].name).toBe("CNN")
+        // The projection must NOT contain the Transformer page anywhere.
+        expect(projected).not.toContain('id="page-transformer"')
+        expect(projected).not.toContain('name="Transformer"')
+    })
+
+    it("projects only the requested page when targeted by name", () => {
+        const projected = projectSinglePage(TWO_PAGE_MXFILE, {
+            page_name: "Transformer",
+        })
+        const pages = listPagesFromDoc(parseMxfile(projected)!)
+        expect(pages).toHaveLength(1)
+        expect(pages[0].name).toBe("Transformer")
+        expect(projected).not.toContain('id="page-cnn"')
+    })
+
+    it("projects only the requested page when targeted by index", () => {
+        const projected = projectSinglePage(TWO_PAGE_MXFILE, {
+            page_index: 1,
+        })
+        const pages = listPagesFromDoc(parseMxfile(projected)!)
+        expect(pages).toHaveLength(1)
+        expect(pages[0].index).toBe(0) // re-indexed: it's the only page in the projection
+        expect(pages[0].id).toBe("page-cnn")
+    })
+
+    it("two different page selectors produce visually distinct projections", () => {
+        // The regression: under the old selectPage bug, two exports would
+        // return the same active tab. With the projection approach, the
+        // payload that drawio renders is provably different.
+        const a = projectSinglePage(TWO_PAGE_MXFILE, {
+            page_id: "page-transformer",
+        })
+        const b = projectSinglePage(TWO_PAGE_MXFILE, { page_id: "page-cnn" })
+        expect(a).not.toBe(b)
+        expect(a).toContain('"Encoder"')
+        expect(a).not.toContain('"Conv1"')
+        expect(b).toContain('"Conv1"')
+        expect(b).not.toContain('"Encoder"')
+    })
+
+    it("the projection parses to a valid one-page mxfile", () => {
+        const projected = projectSinglePage(TWO_PAGE_MXFILE, {
+            page_id: "page-cnn",
+        })
+        // Validator accepts it.
+        expect(validateAndFixXml(projected).valid).toBe(true)
+        // And it has a real <root> with the cells from the source page.
+        const doc = parseMxfile(projected)!
+        const root = doc.querySelector("root")
+        expect(root).not.toBeNull()
+        const conv1 = doc.querySelector('mxCell[value="Conv1"]')
+        expect(conv1).not.toBeNull()
+    })
+})
+
+describe("end-to-end — Transformer + CNN scenario (AC6)", () => {
+    it("two tool-equivalent steps reproduce the motivating user scenario", () => {
+        // Step 1 — caller passes a single-page mxfile.
+        const step1 = normalizeToMxfile(BARE_MODEL_ONE_CELL, {
+            pageId: "page-transformer",
+            pageName: "Transformer",
+        })
+        expect(step1).not.toBeNull()
+        let xml = step1 as string
+        const validate1 = validateAndFixXml(xml)
+        expect(validate1.valid).toBe(true)
+
+        // Step 2 — equivalent of add_page("CNN") with a starting model.
+        const doc = parseMxfile(xml)!
+        addPageToDoc(doc, {
+            id: "page-cnn",
+            name: "CNN",
+            xml: `<mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/><mxCell id="2" vertex="1" parent="1" value="Conv1"><mxGeometry x="40" y="40" width="120" height="60" as="geometry"/></mxCell></root></mxGraphModel>`,
+        })
+        xml = serializeMxfile(doc)
+
+        // Now: two pages, both valid, with the right names.
+        const pages = listPagesFromDoc(parseMxfile(xml)!)
+        expect(pages.map((p) => p.name)).toEqual(["Transformer", "CNN"])
+        expect(validateAndFixXml(xml).valid).toBe(true)
+    })
+})

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

@@ -0,0 +1,142 @@
+/**
+ * Server-wiring test: boot the actual MCP stdio server (from source via tsx)
+ * and drive it the way a real MCP client does — initialize handshake,
+ * tools/list — to catch registration/schema regressions that the unit tests
+ * (which import helpers directly) can't see.
+ *
+ * This replaces the old standalone tests/smoke.mjs, which spawned the BUILT
+ * dist/index.js and was therefore never run in CI (CI doesn't build this
+ * 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.
+ */
+
+import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+import { afterAll, beforeAll, describe, expect, it } from "vitest"
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const entry = path.resolve(__dirname, "..", "src", "index.ts")
+const tsxBin = path.resolve(
+    __dirname,
+    "..",
+    "node_modules",
+    ".bin",
+    process.platform === "win32" ? "tsx.cmd" : "tsx",
+)
+
+const EXPECTED_TOOLS = [
+    "start_session",
+    "create_new_diagram",
+    "load_diagram",
+    "edit_diagram",
+    "get_diagram",
+    "export_diagram",
+    "list_pages",
+    "add_page",
+    "rename_page",
+    "delete_page",
+]
+
+let proc: ChildProcessWithoutNullStreams
+let stdoutBuf = ""
+const pending = new Map<
+    number,
+    { resolve: (m: any) => void; reject: (e: Error) => void; timeout: any }
+>()
+let nextId = 1
+
+function send(method: string, params: unknown, isNotification = false) {
+    const msg: Record<string, unknown> = { jsonrpc: "2.0", method, params }
+    if (!isNotification) msg.id = nextId++
+    proc.stdin.write(`${JSON.stringify(msg)}\n`)
+    if (isNotification) return Promise.resolve(undefined)
+    return new Promise<any>((resolve, reject) => {
+        const id = msg.id as number
+        const timeout = setTimeout(() => {
+            pending.delete(id)
+            reject(new Error(`Timed out waiting for response to ${method}`))
+        }, 15000)
+        pending.set(id, { resolve, reject, timeout })
+    })
+}
+
+beforeAll(async () => {
+    proc = spawn(tsxBin, [entry], {
+        stdio: ["pipe", "pipe", "pipe"],
+    }) as ChildProcessWithoutNullStreams
+
+    proc.stdout.on("data", (chunk: Buffer) => {
+        stdoutBuf += chunk.toString()
+        const lines = stdoutBuf.split("\n")
+        stdoutBuf = lines.pop() || ""
+        for (const line of lines) {
+            const trimmed = line.trim()
+            if (!trimmed) continue
+            let msg: any
+            try {
+                msg = JSON.parse(trimmed)
+            } catch {
+                // Non-JSON-RPC log line — ignore.
+                continue
+            }
+            const p = msg.id !== undefined ? pending.get(msg.id) : undefined
+            if (p) {
+                clearTimeout(p.timeout)
+                pending.delete(msg.id)
+                p.resolve(msg)
+            }
+        }
+    })
+
+    const initResp = await send("initialize", {
+        protocolVersion: "2024-11-05",
+        capabilities: {},
+        clientInfo: { name: "wiring-test", version: "0.0.0" },
+    })
+    expect(initResp.error, JSON.stringify(initResp.error)).toBeUndefined()
+    expect(initResp.result?.serverInfo?.name).toBeTruthy()
+    await send("notifications/initialized", {}, true)
+}, 30000)
+
+afterAll(() => {
+    proc?.kill("SIGTERM")
+})
+
+describe("MCP server wiring", () => {
+    it("registers all nine multi-page tools", async () => {
+        const resp = await send("tools/list", {})
+        expect(resp.error, JSON.stringify(resp.error)).toBeUndefined()
+        const names: string[] = (resp.result?.tools ?? []).map(
+            (t: { name: string }) => t.name,
+        )
+        for (const expected of EXPECTED_TOOLS) {
+            expect(names, `missing tool: ${expected}`).toContain(expected)
+        }
+    })
+
+    it("advertises page-selector params on edit_diagram", async () => {
+        const resp = await send("tools/list", {})
+        const edit = resp.result.tools.find(
+            (t: { name: string }) => t.name === "edit_diagram",
+        )
+        const props = edit?.inputSchema?.properties ?? {}
+        expect(props.page_id).toBeTruthy()
+        expect(props.page_name).toBeTruthy()
+        expect(props.page_index).toBeTruthy()
+    })
+
+    it("advertises name/id/xml on add_page", async () => {
+        const resp = await send("tools/list", {})
+        const addPage = resp.result.tools.find(
+            (t: { name: string }) => t.name === "add_page",
+        )
+        const props = addPage?.inputSchema?.properties ?? {}
+        expect(props.name).toBeTruthy()
+        expect(props.id).toBeTruthy()
+        expect(props.xml).toBeTruthy()
+    })
+})

packages/mcp-server/vitest.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from "vitest/config"
+
+export default defineConfig({
+    test: {
+        include: ["tests/**/*.test.ts"],
+        environment: "node",
+        // The package source uses Node16 module resolution with explicit .js
+        // extensions in imports. Vitest+esbuild handles the .ts→.js mapping
+        // transparently, so no extra alias config is needed.
+    },
+})

tests/unit/ai-providers.test.ts

@@ -1,10 +1,35 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
 import {
     getAIModel,
+    isAihubmixStandardBaseURL,
     resolveBaseURL,
-    supportsImageInput,
     supportsPromptCaching,
 } from "@/lib/ai-providers"
+import { extractAihubmixModelIds } from "@/lib/aihubmix-models"
+
+describe("extractAihubmixModelIds", () => {
+    it("extracts unique chat model IDs from the AIHubMix model list payload", () => {
+        const models = extractAihubmixModelIds({
+            data: [
+                { model_id: "claude-sonnet-4-5-20250929", types: "llm" },
+                { model_id: "gpt-5.1", types: "llm" },
+                { model_id: "gpt-5.1", types: "llm" },
+                { model_id: "gpt-image-2", types: "image_generation,llm" },
+                { model_id: "cohere-rerank-v4.0", types: "rerank" },
+                { model_id: "", types: "llm" },
+                { types: "llm" },
+            ],
+        })
+
+        expect(models).toEqual(["claude-sonnet-4-5-20250929", "gpt-5.1"])
+    })
+
+    it("returns an empty list for malformed payloads", () => {
+        expect(extractAihubmixModelIds({ data: null })).toEqual([])
+        expect(extractAihubmixModelIds({})).toEqual([])
+        expect(extractAihubmixModelIds(null)).toEqual([])
+    })
+})
 
 describe("resolveBaseURL", () => {
     const SERVER_BASE_URL = "https://server-proxy.example.com"
@@ -157,89 +182,6 @@ describe("supportsPromptCaching", () => {
     })
 })
 
-describe("supportsImageInput", () => {
-    it("returns true for models with vision capability", () => {
-        expect(supportsImageInput("gpt-4-vision")).toBe(true)
-        expect(supportsImageInput("qwen-vl")).toBe(true)
-        expect(supportsImageInput("deepseek-vl")).toBe(true)
-    })
-
-    it("returns false for Kimi K2 models without vision", () => {
-        expect(supportsImageInput("kimi-k2")).toBe(false)
-        expect(supportsImageInput("moonshot/kimi-k2")).toBe(false)
-    })
-
-    it("returns true for Kimi K2.5 models (supports vision)", () => {
-        expect(supportsImageInput("kimi-k2.5")).toBe(true)
-        expect(supportsImageInput("moonshotai/kimi-k2.5")).toBe(true)
-    })
-
-    it("returns false for Moonshot v1 text models", () => {
-        expect(supportsImageInput("moonshot-v1-8k")).toBe(false)
-        expect(supportsImageInput("moonshot-v1-32k")).toBe(false)
-        expect(supportsImageInput("moonshot-v1-128k")).toBe(false)
-    })
-
-    it("returns false for MiniMax M2 text models", () => {
-        expect(supportsImageInput("MiniMax-M2.7")).toBe(false)
-        expect(supportsImageInput("MiniMax-M2.7-highspeed")).toBe(false)
-        expect(supportsImageInput("MiniMax-M2")).toBe(false)
-    })
-
-    it("returns true for MiniMax M3 (supports image input)", () => {
-        expect(supportsImageInput("MiniMax-M3")).toBe(true)
-    })
-
-    it("returns false for DeepSeek text models", () => {
-        expect(supportsImageInput("deepseek-chat")).toBe(false)
-        expect(supportsImageInput("deepseek-coder")).toBe(false)
-    })
-
-    it("returns false for Qwen text models", () => {
-        expect(supportsImageInput("qwen-turbo")).toBe(false)
-        expect(supportsImageInput("qwen-plus")).toBe(false)
-        expect(supportsImageInput("qwen3-max")).toBe(false)
-    })
-
-    it("returns true for Qwen vision models", () => {
-        expect(supportsImageInput("qwen-vl")).toBe(true)
-        expect(supportsImageInput("Qwen3.5")).toBe(true)
-        expect(supportsImageInput("qwen3.5")).toBe(true)
-        expect(supportsImageInput("qwen3.5-plus")).toBe(true)
-        expect(supportsImageInput("qwen3.5-flash")).toBe(true)
-        expect(supportsImageInput("qwen3-vl-plus")).toBe(true)
-        expect(supportsImageInput("qwen3-vl-flash")).toBe(true)
-    })
-
-    it("returns true for QvQ (Qwen Visual QA) models including OpenRouter-prefixed names", () => {
-        expect(supportsImageInput("qvq-72b-preview")).toBe(true)
-        expect(supportsImageInput("qvq-max")).toBe(true)
-        expect(supportsImageInput("qwen/qvq-72b-preview")).toBe(true)
-        expect(supportsImageInput("qwen/qvq-max")).toBe(true)
-    })
-
-    it("returns false for GLM text models", () => {
-        expect(supportsImageInput("glm-4")).toBe(false)
-        expect(supportsImageInput("glm-4-plus")).toBe(false)
-        expect(supportsImageInput("glm-4-flash")).toBe(false)
-        expect(supportsImageInput("glm-4-long")).toBe(false)
-        expect(supportsImageInput("glm-4.7")).toBe(false)
-        expect(supportsImageInput("glm-5")).toBe(false)
-    })
-
-    it("returns true for GLM vision models", () => {
-        expect(supportsImageInput("glm-4v")).toBe(true)
-        expect(supportsImageInput("glm-4v-9b")).toBe(true)
-        expect(supportsImageInput("glm-4.1v-9b-thinking")).toBe(true)
-    })
-
-    it("returns true for Claude and GPT models by default", () => {
-        expect(supportsImageInput("claude-sonnet-4-5")).toBe(true)
-        expect(supportsImageInput("gpt-4o")).toBe(true)
-        expect(supportsImageInput("gemini-pro")).toBe(true)
-    })
-})
-
 vi.mock("ollama-ai-provider-v2", () => {
     const mockModel = { modelId: "test-model" }
     const mockProviderFn = vi.fn(() => mockModel)
@@ -256,6 +198,128 @@ vi.mock("@ai-sdk/deepseek", () => {
     return { createDeepSeek: mockCreateDeepSeek, deepseek: mockDeepseek }
 })
 
+vi.mock("@aihubmix/ai-sdk-provider", () => {
+    const mockModel = { modelId: "test-model" }
+    const mockProviderFn = vi.fn(() => mockModel)
+    const mockCreateAihubmix = vi.fn(() => mockProviderFn)
+    const mockAihubmix = vi.fn(() => mockModel)
+    return { aihubmix: mockAihubmix, createAihubmix: mockCreateAihubmix }
+})
+
+vi.mock("@ai-sdk/openai", () => {
+    const mockModel = { modelId: "test-model" }
+    const mockChat = vi.fn(() => mockModel)
+    const mockProviderFn = vi.fn(() => mockModel) as any
+    mockProviderFn.chat = mockChat
+    const mockCreateOpenAI = vi.fn(() => mockProviderFn)
+    const mockOpenai = vi.fn(() => mockModel)
+    return { createOpenAI: mockCreateOpenAI, openai: mockOpenai }
+})
+
+describe("AIHubMix provider", () => {
+    let createAihubmixMock: ReturnType<typeof vi.fn>
+    const savedEnv: Record<string, string | undefined> = {}
+
+    beforeEach(async () => {
+        savedEnv.AIHUBMIX_API_KEY = process.env.AIHUBMIX_API_KEY
+        savedEnv.AIHUBMIX_BASE_URL = process.env.AIHUBMIX_BASE_URL
+        delete process.env.AIHUBMIX_BASE_URL
+
+        const mod = await import("@aihubmix/ai-sdk-provider")
+        createAihubmixMock = mod.createAihubmix as ReturnType<typeof vi.fn>
+        createAihubmixMock.mockClear()
+    })
+
+    afterEach(() => {
+        process.env.AIHUBMIX_API_KEY = savedEnv.AIHUBMIX_API_KEY
+        process.env.AIHUBMIX_BASE_URL = savedEnv.AIHUBMIX_BASE_URL
+    })
+
+    it("uses AIHUBMIX_API_KEY for server configured AIHubMix", () => {
+        process.env.AIHUBMIX_API_KEY = "server-aihubmix-key"
+
+        getAIModel({
+            provider: "aihubmix",
+            modelId: "claude-sonnet-4-5-20250929",
+        })
+
+        expect(createAihubmixMock).toHaveBeenCalledWith({
+            apiKey: "server-aihubmix-key",
+            appCode: "MSBS9675",
+        })
+    })
+
+    it("uses client BYOK API key for AIHubMix", () => {
+        getAIModel({
+            provider: "aihubmix",
+            apiKey: "client-aihubmix-key",
+            modelId: "gpt-5.1",
+        })
+
+        expect(createAihubmixMock).toHaveBeenCalledWith({
+            apiKey: "client-aihubmix-key",
+            appCode: "MSBS9675",
+        })
+    })
+
+    it("recognizes AIHubMix standard endpoints", () => {
+        expect(isAihubmixStandardBaseURL(undefined)).toBe(true)
+        expect(isAihubmixStandardBaseURL("https://aihubmix.com")).toBe(true)
+        expect(isAihubmixStandardBaseURL("https://aihubmix.com/v1/")).toBe(true)
+        expect(isAihubmixStandardBaseURL("https://proxy.example.com/v1")).toBe(
+            false,
+        )
+    })
+})
+
+describe("Atlas Cloud provider", () => {
+    let createOpenAIMock: ReturnType<typeof vi.fn>
+    const savedEnv: Record<string, string | undefined> = {}
+
+    beforeEach(async () => {
+        savedEnv.ATLASCLOUD_API_KEY = process.env.ATLASCLOUD_API_KEY
+        savedEnv.ATLASCLOUD_BASE_URL = process.env.ATLASCLOUD_BASE_URL
+        delete process.env.ATLASCLOUD_BASE_URL
+
+        const mod = await import("@ai-sdk/openai")
+        createOpenAIMock = mod.createOpenAI as ReturnType<typeof vi.fn>
+        createOpenAIMock.mockClear()
+    })
+
+    afterEach(() => {
+        process.env.ATLASCLOUD_API_KEY = savedEnv.ATLASCLOUD_API_KEY
+        process.env.ATLASCLOUD_BASE_URL = savedEnv.ATLASCLOUD_BASE_URL
+    })
+
+    it("uses Atlas Cloud default endpoint with ATLASCLOUD_API_KEY", () => {
+        process.env.ATLASCLOUD_API_KEY = "server-atlas-key"
+
+        getAIModel({
+            provider: "atlascloud",
+            modelId: "qwen/qwen3.5-flash",
+        })
+
+        expect(createOpenAIMock).toHaveBeenCalledWith({
+            apiKey: "server-atlas-key",
+            baseURL: "https://api.atlascloud.ai/v1",
+        })
+    })
+
+    it("uses custom Atlas Cloud base URL when provided", () => {
+        getAIModel({
+            provider: "atlascloud",
+            apiKey: "client-atlas-key",
+            baseUrl: "https://proxy.example.com/v1",
+            modelId: "deepseek-ai/deepseek-v4-pro",
+        })
+
+        expect(createOpenAIMock).toHaveBeenCalledWith({
+            apiKey: "client-atlas-key",
+            baseURL: "https://proxy.example.com/v1",
+        })
+    })
+})
+
 describe("Kimi provider uses createDeepSeek for reasoning_content support", () => {
     let createDeepSeekMock: ReturnType<typeof vi.fn>
     const savedEnv: Record<string, string | undefined> = {}

tests/unit/server-model-config.test.ts

@@ -39,6 +39,22 @@ describe("ServerModelsConfigSchema", () => {
         expect(() => ServerModelsConfigSchema.parse(config)).not.toThrow()
     })
 
+    it("accepts Atlas Cloud provider names", () => {
+        const config: ServerModelsConfig = {
+            providers: [
+                {
+                    name: "Atlas Cloud Server",
+                    provider: "atlascloud",
+                    models: ["qwen/qwen3.5-flash"],
+                    apiKeyEnv: "ATLASCLOUD_API_KEY",
+                    baseUrlEnv: "ATLASCLOUD_BASE_URL",
+                },
+            ],
+        }
+
+        expect(() => ServerModelsConfigSchema.parse(config)).not.toThrow()
+    })
+
     it("rejects invalid provider names", () => {
         const invalidConfig = {
             providers: [
@@ -159,6 +175,44 @@ describe("loadFlattenedServerModels", () => {
         expect(defaultModel.modelId).toBe("gpt-4o") // First model of default provider
     })
 
+    it("falls back to comma-separated AI_MODEL when no other config is set", async () => {
+        process.env.AI_MODELS_CONFIG = ""
+        process.env.AI_MODELS_CONFIG_PATH = `non-existent-config-${Date.now()}.json`
+        process.env.AI_PROVIDER = "openai"
+        process.env.AI_MODEL = "gpt-4o, gpt-4o-mini, gpt-4o"
+
+        const models = await loadFlattenedServerModels()
+
+        // Trims, deduplicates, and preserves order
+        expect(models.map((m) => m.modelId)).toEqual(["gpt-4o", "gpt-4o-mini"])
+        expect(models.every((m) => m.provider === "openai")).toBe(true)
+
+        // First model is marked default (provider has default: true)
+        const defaults = models.filter((m) => m.isDefault)
+        expect(defaults.length).toBe(1)
+        expect(defaults[0].modelId).toBe("gpt-4o")
+    })
+
+    it("does not synthesize when AI_MODEL has no comma", async () => {
+        process.env.AI_MODELS_CONFIG = ""
+        process.env.AI_MODELS_CONFIG_PATH = `non-existent-config-${Date.now()}.json`
+        process.env.AI_PROVIDER = "openai"
+        process.env.AI_MODEL = "gpt-4o"
+
+        const models = await loadFlattenedServerModels()
+        expect(models).toEqual([])
+    })
+
+    it("does not synthesize when AI_PROVIDER is unset", async () => {
+        process.env.AI_MODELS_CONFIG = ""
+        process.env.AI_MODELS_CONFIG_PATH = `non-existent-config-${Date.now()}.json`
+        delete process.env.AI_PROVIDER
+        process.env.AI_MODEL = "gpt-4o, gpt-4o-mini"
+
+        const models = await loadFlattenedServerModels()
+        expect(models).toEqual([])
+    })
+
     it("preserves apiKeyEnv array in flattened models for load balancing", async () => {
         const config: ServerModelsConfig = {
             providers: [

tests/unit/ssrf-protection.test.ts

@@ -1,21 +1,79 @@
-import { describe, expect, it } from "vitest"
+import { beforeEach, describe, expect, it, vi } from "vitest"
 import { isPrivateUrl } from "@/lib/ssrf-protection"
 
+// Mock DNS so tests are deterministic and never hit the network.
+const lookupMock = vi.hoisted(() => vi.fn())
+vi.mock("node:dns/promises", () => ({
+    default: { lookup: lookupMock },
+    lookup: lookupMock,
+}))
+
 describe("isPrivateUrl", () => {
-    it("blocks private IPv6 URLs", () => {
-        expect(isPrivateUrl("http://[::1]/")).toBe(true)
-        expect(isPrivateUrl("http://[0:0:0:0:0:0:0:1]/")).toBe(true)
-        expect(isPrivateUrl("http://[::]/")).toBe(true)
-        expect(isPrivateUrl("http://[::ffff:127.0.0.1]/")).toBe(true)
-        expect(isPrivateUrl("http://[fc00::1]/")).toBe(true)
-        expect(isPrivateUrl("http://[fd12:3456:789a::1]/")).toBe(true)
-        expect(isPrivateUrl("http://[fe80::1]/")).toBe(true)
-        expect(isPrivateUrl("http://[fe9f::1]/")).toBe(true)
-        expect(isPrivateUrl("http://[febf::1]/")).toBe(true)
+    beforeEach(() => {
+        lookupMock.mockReset()
     })
 
-    it("allows public URLs", () => {
-        expect(isPrivateUrl("https://example.com/article")).toBe(false)
-        expect(isPrivateUrl("https://fc00.example.com/article")).toBe(false)
+    it("blocks private IPv6 URLs (string-only fast path, no DNS)", async () => {
+        expect(await isPrivateUrl("http://[::1]/")).toBe(true)
+        expect(await isPrivateUrl("http://[0:0:0:0:0:0:0:1]/")).toBe(true)
+        expect(await isPrivateUrl("http://[::]/")).toBe(true)
+        expect(await isPrivateUrl("http://[::ffff:127.0.0.1]/")).toBe(true)
+        expect(await isPrivateUrl("http://[fc00::1]/")).toBe(true)
+        expect(await isPrivateUrl("http://[fd12:3456:789a::1]/")).toBe(true)
+        expect(await isPrivateUrl("http://[fe80::1]/")).toBe(true)
+        expect(await isPrivateUrl("http://[fe9f::1]/")).toBe(true)
+        expect(await isPrivateUrl("http://[febf::1]/")).toBe(true)
+        expect(lookupMock).not.toHaveBeenCalled()
+    })
+
+    it("blocks literal private IPv4 without DNS", async () => {
+        expect(await isPrivateUrl("http://127.0.0.1/")).toBe(true)
+        expect(await isPrivateUrl("http://10.0.0.5/")).toBe(true)
+        expect(await isPrivateUrl("http://192.168.1.1/")).toBe(true)
+        expect(await isPrivateUrl("http://169.254.169.254/")).toBe(true)
+        expect(await isPrivateUrl("http://0.0.0.0/")).toBe(true)
+        // 100.64.0.0/10 CGNAT (RFC 6598), routable in some cloud internal nets
+        expect(await isPrivateUrl("http://100.64.0.1/")).toBe(true)
+        expect(await isPrivateUrl("http://100.127.255.255/")).toBe(true)
+        expect(lookupMock).not.toHaveBeenCalled()
+    })
+
+    it("treats CGNAT boundaries correctly", async () => {
+        // 100.63.x and 100.128.x are outside 100.64.0.0/10 → public
+        lookupMock.mockResolvedValue([{ address: "100.63.255.255", family: 4 }])
+        expect(await isPrivateUrl("http://just-below.example/")).toBe(false)
+        lookupMock.mockResolvedValue([{ address: "100.128.0.1", family: 4 }])
+        expect(await isPrivateUrl("http://just-above.example/")).toBe(false)
+    })
+
+    it("blocks a hostname that resolves to a private IPv6 address", async () => {
+        lookupMock.mockResolvedValue([{ address: "fd00::1", family: 6 }])
+        expect(await isPrivateUrl("http://v6.example.com/")).toBe(true)
+    })
+
+    it("allows public URLs that resolve to public IPs", async () => {
+        lookupMock.mockResolvedValue([{ address: "93.184.216.34", family: 4 }])
+        expect(await isPrivateUrl("https://example.com/article")).toBe(false)
+    })
+
+    it("blocks public-looking hostnames that resolve to a private IP (DNS-rebinding-style bypass)", async () => {
+        // e.g. 127-0-0-1.sslip.io resolves to 127.0.0.1
+        lookupMock.mockResolvedValue([{ address: "127.0.0.1", family: 4 }])
+        expect(await isPrivateUrl("http://127-0-0-1.sslip.io/")).toBe(true)
+    })
+
+    it("blocks when any resolved address is private", async () => {
+        lookupMock.mockResolvedValue([
+            { address: "93.184.216.34", family: 4 },
+            { address: "10.1.2.3", family: 4 },
+        ])
+        expect(await isPrivateUrl("http://mixed.example.com/")).toBe(true)
+    })
+
+    it("blocks when DNS resolution fails", async () => {
+        lookupMock.mockRejectedValue(new Error("ENOTFOUND"))
+        expect(await isPrivateUrl("http://does-not-resolve.example/")).toBe(
+            true,
+        )
     })
 })