Working On Views

Working on Views

Read docs/views.md for architecture, response format, and constraints. Read docs/view-design.md for when to build a view, interaction patterns, and visual principles.

CRITICAL: Rebuild After Every .svelte Change

worker/src/mcp/views.gen.ts is a committed build artifact — CI does not rebuild it. After modifying ANY .svelte file (in views/, worker/src/mcp/views/, or plugins/*/reference/views/), you MUST:

1. Run just build-views
2. Commit the regenerated views.gen.ts alongside your other changes

Forgetting this means production serves stale view HTML even after a successful cloud deploy. The deploy will succeed, the tests will pass, but users see the old view.

Verification

just build-views    # Rebuild views.gen.ts (required after any .svelte change)
just test-worker    # Handler + tool tests
just storybook-views  # Visual verification on port 6007

Two View Types

Game state views — one self-contained HTML per tool. Component + bridge bundled together.

• Location: worker/src/mcp/views/<slug>.svelte
• Slug maps to tool name: search-saves.svelte → tool search_saves

Reference views — one bundled HTML for query_reference containing ALL reference module components. Routes on structuredContent.module.

• Location: plugins/<game>/reference/views/<module-id>.svelte
• Filename maps to module ID: card-search.svelte → module card_search
• Auto-discovered by build — adding a .svelte file and rebuilding is sufficient.

Adding a New View

1. Create <name>.svelte — Svelte 5 component: let { data } = $props()
2. Create <name>.stories.svelte — Storybook story with fixture data
3. For game state views: update tool in tools.ts to return viewResult(structuredContent, narrative) instead of textResult()
4. Run just build-views then just test-worker
5. Commit views.gen.ts with other changes — CI does not rebuild it

Response Format

// Old (presentation hints — being replaced):
textResult(data, "Display as card gallery...");

// New (structured content for view rendering):
viewResult({ cards, total: cards.length }, "Found 5 cards.");
// For query_reference, handler injects module automatically:
// → { module: "card_search", cards: [...], total: 5 }

viewResult() returns { structuredContent, content }. The view renders structuredContent as UI. content carries BOTH the narrative AND the same data as JSON text — this is critical because Claude hides structuredContent from the model when a widget renders. Without data in content, the model is blind to what the view shows and cannot reason about it.

Bridge — Do Not Reimplement

The bridge at views/src/bridge.ts uses @modelcontextprotocol/ext-apps's App class. It handles the ui/initialize handshake that MCP hosts require before sending data.

Never use raw window.addEventListener("message", ...) — the host will not send tool results without the initialization handshake. The App class handles this.

View Philosophy

Views render the AI's synthesis. The conversation drives interaction. See docs/view-design.md.

Views are passive renderers of data the LLM assembled. If the player wants to go deeper, they type another message. The view presents; the LLM decides what to show next.

Used Capabilities

• app.updateModelContext() — The primary view interaction. When the player clicks or focuses on something, silently tell the model what they're looking at. Makes the next conversational turn contextually aware.
• app.requestDisplayMode("fullscreen") — User-initiated escalation for complex data. Also "pip" and "inline".
• app.openLink() — External links to authoritative sources ("View on Scryfall").
• ontoolinputpartial — Streaming preview while the LLM generates large arguments. Rendering optimization, not interactivity.
• onhostcontextchanged — Theme, locale, container dimension updates from host.

Not Used (intentionally)

• app.callServerTool() — Bypasses the conversation. Views that call tools build web apps in iframes, competing with established gaming tools. If the player wants more data, they ask the AI.
• app.sendMessage() — Hijacks the conversation. The player types when they want to talk.
• app.downloadFile() — If data needs exporting, the model provides it in text or the player uses the website.
• localStorage — Blocked in sandboxed iframes (unique origin). Views are stateless — everything arrives in structuredContent.

Styling

Savecraft design tokens in views/src/view.css: --color-bg, --color-panel-bg, --color-border, --color-gold, --color-text, --color-text-dim, --color-text-muted, --font-pixel, --font-heading, --font-body.

Host theme integration (optional, for native look):

import { applyDocumentTheme, applyHostStyleVariables, applyHostFonts } from "@modelcontextprotocol/ext-apps";

app.onhostcontextchanged = (ctx) => {
  if (ctx.theme) applyDocumentTheme(ctx.theme);
  if (ctx.styles?.variables) applyHostStyleVariables(ctx.styles.variables);
  if (ctx.styles?.css?.fonts) applyHostFonts(ctx.styles.css.fonts);
};

Host provides 50+ CSS variables: --color-background-*, --color-text-*, --font-sans, --font-mono, --border-radius-*, --shadow-*.

CSP Constraints

Default iframe CSP blocks external resources. To use external fonts, images, or APIs:

// In handler.ts, add to resource or tool _meta.ui:
_meta: {
  ui: {
    resourceUri: "ui://savecraft/reference.html",
    csp: {
      resourceDomains: ["https://fonts.googleapis.com", "https://fonts.gstatic.com"],  // fonts, images, styles
      connectDomains: ["https://api.example.com"],  // fetch/XHR/WebSocket
    }
  }
}

Key CSP facts:

• script-src 'self' 'unsafe-inline' — inline scripts OK, blob: URLs blocked
• style-src 'self' 'unsafe-inline' — inline styles OK, external stylesheets blocked unless declared in resourceDomains
• connect-src 'none' — no network unless declared in connectDomains
• font-src 'self' — no external fonts unless declared in resourceDomains

Build Pipeline

just build-views runs views/scripts/build.ts:

1. Discovers .svelte files (excluding .stories.svelte) from worker/src/mcp/views/ and plugins/*/reference/views/
2. Game state views → one IIFE entry per tool (bridge + component)
3. Reference views → one IIFE entry with component map importing all reference views
4. Wraps each in HTML with design tokens CSS
5. Outputs worker/src/mcp/views.gen.ts — committed, not rebuilt by CI

The handler imports VIEWS from views.gen.ts and auto-wires resources/list, resources/read, and _meta.ui.resourceUri on tools/list.

Attribution

Every view includes a collapsed legal footer rendered by views/src/Attribution.svelte. This is automatic — view authors don't need to do anything.

How it works: The build pipeline reads [attribution].sources from each plugin's plugin.toml, resolves source keys against shared presets in views/src/attributions.ts, and embeds the result as window.__ATTRIBUTION__ in the compiled HTML. The Attribution component reads this global and renders a collapsed ▸ Legal · Source1 · Source2 footer that expands to show full disclaimers on click.

• Game state views aggregate attribution from ALL plugins (they span multiple games)
• Reference views get attribution from their parent plugin only
• Build fails if any plugin is missing [attribution] or uses an unknown source key

To add a new attribution source: add it to SOURCES in views/src/attributions.ts, then reference it from plugin.toml.

Game Watermarks

Every reference view should display its game's icon as a subtle centered watermark. This is a first-class part of the Savecraft visual language — it gives each game identity without competing with content.

How it works:

• Panel accepts a watermark?: string prop — renders a centered, semi-transparent (10% opacity) <img> that shows through gaps between content elements
• The handler injects icon_url into structuredContent via resolveIconUrl() (uses per-isolate manifest cache)
• Views pass data.icon_url to their outer <Panel watermark={data.icon_url}>
• Stories include icon_url in fixture data: const iconUrl = "/plugins/<game>/icon.png"

Rules:

• Watermark is Panel's responsibility — never add per-component watermark CSS
• Every reference view's outer Panel should have watermark={data.icon_url}
• Every view's data interface should include icon_url?: string
• Every Storybook story should include icon_url: iconUrl in fixture data so the watermark is visible during development
• resolveIconUrl(plugins, serverUrl, gameId) is the single source of truth for icon URL construction — never duplicate the manifest lookup

For MtgCard specifically: The iconUrl prop passes through to <Panel watermark={iconUrl}> internally. Card-search passes data.icon_url to each MtgCard's iconUrl prop.

Visual Hierarchy

Views use a two-level hierarchy:

• Section — top-level titled container with pixel-font header bar. One per logical grouping.
• Nested Panel + .sub-label — sub-groupings within a Section. Use <Panel nested> with a <span class="sub-label"> heading (defined in view.css as a global utility class).

Anti-patterns:

• Never nest Section inside Section — title directly below title looks bad and confuses hierarchy
• Never use Section's count prop — the number badge in the upper-right is confusing and visually noisy. If a count matters, show it in the content area.
• Never add callout/alert components — views render pre-enrichment data from game modules, not AI synthesis. The LLM provides judgment in the conversation text, not the view.

Svelte 5 Component Pattern

<script lang="ts">
  // Props from structuredContent
  let { data }: { data: { cards: Card[]; total: number } } = $props();
</script>

<div class="gallery">
  {#each data.cards as card}
    <div class="card">{card.name}</div>
  {/each}
</div>

<style>
  .gallery { display: grid; gap: 10px; padding: 16px; }
  .card {
    background: var(--color-panel-bg);
    border: 1px solid var(--color-border);
    border-radius: 8px;
    padding: 12px;
    font-family: var(--font-heading);
    color: var(--color-text);
  }
</style>

Storybook Story Pattern

<script module>
  import { defineMeta } from "@storybook/addon-svelte-csf";
  import CardSearch from "./card-search.svelte";
  const { Story } = defineMeta({ title: "Reference/CardSearch", tags: ["autodocs"] });
</script>

<Story name="MultipleCards">
  <CardSearch data={{ cards: [{ name: "Lightning Bolt", ... }], total: 1 }} />
</Story>

Gotchas

• Claude caches resources at MCP connection time. View changes require disconnecting and reconnecting the MCP server in the host.
• views.gen.ts must be committed. CI does not run just build-views. Forgetting to rebuild and commit after .svelte changes means staging/production serves stale views.
• Extension negotiation required. Server declares extensions: { "io.modelcontextprotocol/ui": {} } in initialize response. Without this, hosts don't render views.
• Protocol version: 2025-06-18.

Key Paths

views/src/bridge.ts                    # App class bridge (do not reimplement)
views/src/view.css                     # Design system tokens
views/src/attributions.ts              # Attribution presets registry
views/src/Attribution.svelte           # Collapsed legal footer component
views/scripts/build.ts                 # Build → views.gen.ts
views/.storybook/                      # Storybook config (port 6007)
worker/src/mcp/views.gen.ts            # GENERATED — VIEWS record (commit this)
worker/src/mcp/handler.ts              # resources/list, resources/read, _meta.ui
worker/src/mcp/tools.ts                # viewResult(), textResult()
worker/src/mcp/views/                  # Game state views + stories
plugins/*/reference/views/             # Reference views + stories