Spec-compliant resource_link returns + synapse-app UI rebuild

[mgoldsborough]

Summary

Two coordinated changes that land together because they depend on each other: the server stops inlining binary artifacts in tool results, and the UI is rebuilt as a proper synapse app that consumes those resources over the ext-apps bridge.

Server side:

• preview, preview_template, export_pdf, compile_typst return MCP-spec resource_link content blocks instead of inline base64 bytes. Results shrink from multi-MB to ~450 bytes.
• New collateral://exports/{export_id}.{ext} resource template for rendered PDFs + new collateral://assets/{filename} resource template for user-uploaded assets. Clients read bytes via standard resources/read.
• Rendering unified on PDF output — preview stops rasterizing to PNGs per page. Browser renders the PDF via the new viewer.
• export_pdf drops its include_data: bool param (was meaningless once bytes moved to a resource). Breaking change for direct MCP callers; LLM-facing behavior is unchanged.

UI side:

• Rebuilt as a proper synapse app: <SynapseProvider> wrapping, decomposed into views/ + components/ + hooks/ (mirrors the synapse-crm pattern). Previously a 1298-line monolith that imported synapse hooks but never wrapped with a provider.
• PDF viewer renders directly to <canvas> via unpdf / PDF.js (no intermediate PNG data URLs). DPR-aware sharpness, ImageBitmap cache for instant zoom-back, render cancellation, float-quantized fit-scale that doesn't flicker at container boundaries.
• Fully theme-aware: consumes the host's LIGHT_TOKENS / DARK_TOKENS design system. Host tokens injected as CSS custom properties on :root, styles reference via var(--token). Dark mode flips automatically (host re-sends tokens on mode change).
• Responsive: 1024 / 768 / 640 breakpoints. Left rail + preview stack below 768px; action cluster collapses to a kebab menu; dialogs + settings go full-width on mobile. Respects prefers-reduced-motion.
• Assets promoted to a first-class tab (third peer of Documents / Templates) with upload (drag-and-drop + picker) and in-app preview.
• Bytes fetched via synapse.readResource(uri) (shipped in synapse 0.4.3), so the iframe doesn't need to know anything about the host's URL space.

Why

In a 15-hour production session the primary artifact workflow kept crashing because preview, preview_template, and export_pdf returned 1MB-5MB of inline base64 PNG/PDF data, exceeding the engine's 1,000,000-char maxToolResultSize cap:

Tool result too large (4,896,022 chars, limit: 1,000,000). Ask the user to constrain the query or use pagination.

The PDF export is the whole point of the tool. The cap isn't wrong — inlining megabytes of base64 into every tool result is a bad pattern. The MCP spec already offers resource_link content blocks for exactly this: tools return a tiny URI, clients fetch bytes via resources/read.

Wire format

Before:

{
  "content": [
    { "type": "text", "text": "Exported 10-page PDF." },
    { "type": "image", "data": "<base64 MB>", "mimeType": "image/png" }
  ]
}

After:

{
  "content": [
    { "type": "text", "text": "Export of Demo: 10 pages, 1.1MB" },
    {
      "type": "resource_link",
      "uri": "collateral://exports/exp_97aceaf3649231ea.pdf",
      "name": "Export of Demo",
      "mimeType": "application/pdf",
      "annotations": { "audience": ["user"] }
    }
  ],
  "structuredContent": {
    "export_id": "exp_97aceaf3649231ea",
    "page_count": 10, "size_bytes": 1108461, "mime_type": "application/pdf"
  }
}

Total tool-result payload: ~450 bytes regardless of PDF size.

Design decisions

• Unified on PDF output. Dropped the PNG-per-page raster branch — preview, preview_template, export_pdf, and compile_typst all now call the same PDF compile path and return a single resource_link. The UI renders the PDF in-browser (canvas via PDF.js). Kept tool names distinct for agent clarity even though implementations collapse.
• Kept existing ui://collateral/preview.pdf for backward compat with any external MCP client relying on it.
• No embedded UI app for asset bytes. collateral://assets/{filename} is a standard resource template, not a ui:// app. The iframe calls synapse.readResource to fetch bytes; rendering happens in-iframe.
• Host theme tokens over hand-rolled palette. Killed every hardcoded hex fallback (#2563eb etc.) in favor of var(--color-text-accent) with light-mode fallbacks so standalone file:// renders still work.
• Canvas rendering over PNG data URLs. unpdf.renderPageAsImage was simple but rasterized to PNG → base64 → <img>. The new path is getDocumentProxy + pdfPage.render({canvasContext, viewport}) directly into a sized <canvas>. Sharper, smaller memory footprint, sets up for a future selectable text layer.
• Fit scale: both axes + floor + 24px gutter + max-width/height CSS cap. Belt-and-suspenders against container-scrollbar oscillation at the fit boundary.

File-level overview

~30 files changed, +3170 / -1300 lines.

Server (Python):

• src/mcp_collateral/server.py — tool return rewrites, new resource templates, MIME helper
• src/mcp_collateral/workspace.py — store_export / load_export, _exports dir + TTL cleanup, PNG compile branch removed
• src/mcp_collateral/compiler.py — PDF-only
• src/mcp_collateral/models.py — dead PreviewResult / ExportResult / PagePreview removed
• tests/test_tool_contracts.py — 10+ new contract tests + asset resource tests

UI (TypeScript/React):

• ui/src/main.tsx — wrapped in <SynapseProvider>
• ui/src/App.tsx — thin shell (~250 lines, down from 1298)
• ui/src/{views,components,hooks,styles}/ — new structure mirroring synapse-crm
• ui/src/components/PDFViewer.tsx — canvas renderer, zoom controls, page nav
• ui/src/views/AssetsView.tsx — new first-class assets tab
• ui/src/styles/responsive.ts — media queries for 1024 / 768 / 640 + dark mode + reduced motion

Test plan

• uv run pytest tests/ — 76 passing, 10+ new contract tests covering the new return shapes and resource templates (asset + export round-trips, MIME-per-extension dispatch, missing-file handling, directory-traversal refusal)
• uv run ruff check — clean
• npm run build in ui/ — clean, final bundle 2053KB / 629KB gzip
• @nimblebrain/synapse pinned at ^0.4.3 (shipped readResource), installed from registry, readResource confirmed present in the bundled SDK

Not yet covered: UI-level unit tests (follow-up; synapse-crm doesn't have them either — test infra is a separate investment).

Breaking changes

1. export_pdf loses its include_data: bool param. The old contract returned base64 PDF bytes in the result when this was true; the new contract never does. Direct MCP callers passing this arg will now error on schema validation. LLM-facing behavior is unchanged (the agent doesn't reason about include_data).
2. preview / preview_template stop returning ImageContent blocks. Anything that was reading result.content[n].data to get a PNG is broken. Replacement: fetch via resources/read on the returned resource_link URI.

If you want to cushion the breakage, happy to add a deprecation pass where the old params are accepted but emit a warning and return empty bytes. Just say the word — default position is to ship the clean cut given this is an internal platform.

Dependencies

• synapse 0.4.3 — readResource / readServerResource ✅ merged and released
• nimblebrain#36 — POST /v1/resources/read + bridge case + chat renderer. Required for the iframe to work end-to-end in the host (the iframe's synapse.readResource lands on a host endpoint that doesn't exist without it). The collateral server itself works against any MCP client that understands resource_link; the UI specifically needs nimblebrain#36.

[mgoldsborough]

Addressed QA review in 185f090.

Critical 1 (path traversal) — fixed. collateral_asset now resolves the candidate path and rejects anything outside ASSETS_DIR.resolve() before reading bytes. The existing upload-side _validate_filename stays — this is defense-in-depth at the resource-handler boundary. On any escape attempt (traversal, absolute path, OS error during resolve) the handler returns an empty payload rather than throwing, matching the existing missing-file behavior.

Suggestion 1 (traversal test) — added. test_asset_resource_rejects_path_traversal covers three vectors: classic ../../../etc/passwd, mid-path sub/../../etc/passwd, absolute /etc/passwd. All return empty content.

Warning 1 (breaking change doc) — added. New Breaking changes section at the top of CLAUDE.md explicitly documents the export_pdf include_data removal and the render tools' PNG-output removal. Covers direct MCP callers who'd otherwise only find the change in the PR body.

Suggestion 2 (stale README) — fixed. README Tools list was referencing v2 tools that no longer exist (set_template, set_content, get_brand, update_brand_colors, set_logo, list_brand_presets, load_brand_preset, get_content, list_sections, get_template_schema, reset_workspace, preview_page). Replaced with the real v3 surface grouped by lifecycle, and added a Resources section listing the ui://, collateral://, and skill:// namespaces.

Skipped:

• Warning 2 (pre-existing tsc --noEmit error in ui/src/types.ts) — QA flagged not a blocker; this is pre-existing auto-generated Python-syntax leak from the Pydantic → TS codegen, out of scope for this PR.
• Suggestion 3 (byte-size sanity check in usePreview.ts) — nice-to-have, skipped to keep this PR tight. Happy to land as a follow-up if you want a specific cap.

Verification:

• uv run pytest tests/ — 77/77 (+1 new traversal test)
• uv run ruff check — clean
• cd ui && npm run build — clean, bundle unchanged at 2053KB / 629KB gzip

Ready for re-review. Still gated on nimblebrain#36 for the host-side POST /v1/resources/read endpoint — the collateral server itself works against any spec-compliant MCP client today, but the iframe in nimblebrain needs that endpoint to fetch bytes.

[mgoldsborough]

nimblebrain#36 is merged — the host-side POST /v1/resources/read endpoint is on main. The iframe path is now end-to-end unblocked (once nimblebrain deploys). This PR has no other external dependencies.