deck-contract

An open standard + reference MCP server for AI-native editable artifacts. An AI edits one component of a deck surgically (by stable id) instead of regenerating the whole slide. No font drift (style is theme-token-only), no overflow (constraints + a render-and-check loop). First domain: presentations. Designed to extend to docs / resume / landing / LaTeX through the same contract.

Inference runs on the user's own AI subscription via MCP (the tool pays $0 for tokens); rendering is local (Chromium, $0 COGS).

Architecture (functional core / imperative shell)

template package (data)
  -> deck.json            immutable tree, stable string ids
  -> apply(deck, ops[])   pure, transactional (all-or-nothing), inverse for free
  -> compileHtml(deck)    PURE, zero I/O -> deterministic HTML/CSS
  -> render (Day 2)       Playwright -> PNG + machine-readable issues[]
  -> loop: model -> apply_patch -> render -> until issues = []
  -> export PDF

MCP, Playwright and git are swappable adapters at the edge; the core knows nothing about transport.

Packages

package	role
@deck/contract	Zod schemas, contract version, issues[] enum. Zero deps.
@deck/core	immutable tree, stable id allocator, transactional apply+inverse, token validation
@deck/compile	compileHtml(deck) — pure, deterministic deck → HTML/CSS
@deck/renderer	LocalChromiumRenderer — headless Chromium → PNG + issues[] (overflow/out-of-bounds)
@deck/loop	render-and-check loop with monotone gate + anti-oscillation + bounded iters
@deck/loader	FileTemplateSource — resolve self-contained template packages from a folder/git
@deck/mcp-server	10 MCP tools over stdio (thin shell); handle-based state behind a DeckStore
@deck/viewer	local interactive viewer — click to select, edit text, mark an "AI target"; live reload

Dependency rule: everything depends on contract; contract depends on nothing. The domain ("slide", "title") must never leak into core/contract.

Load-bearing invariants (expensive to change later)

1. Stable string ids are identity — ops address nodes by id, never by position.
2. Token-only style — node styles are token refs only; raw hex/px are rejected at the schema boundary, so font drift has nothing to drift to.
3. compileHtml is pure — no I/O, time, or randomness; same deck → byte-identical HTML.
4. Versioned format — spec: "deck-contract/1", tolerant reader, open node type.

Develop

pnpm install
pnpm --filter @deck/renderer exec playwright install chromium   # one-time
pnpm test        # 38 tests: id stability, atomicity, inverse, token-only, determinism, render, convergence
pnpm preview     # compile the sample deck -> examples/out/preview.html
pnpm render      # surgical edit -> headless Chromium -> examples/out/slide-*.png
pnpm loop        # run the fix loop on an overflowing deck -> monotone descent + before/after PNGs
pnpm agent       # drive the MCP tools as a model would -> examples/out/deck-*.png + deck.pdf
pnpm viewer      # open the interactive viewer on a working deck (http://localhost:4570)

Two ways to edit — you and the AI, one deck.json

The point is not full AI generation. The source of truth is one deck.json, and both you and the model edit it through the same id-addressed ops:

• You, directly — pnpm viewer renders the live deck. Click any element to see its stable id; double-click a title/heading to edit text in place; edits write back and reload live.
• You point, the AI acts — click an element and hit "Set as AI target". The model (via get_selection) reads exactly what you pointed at, then apply_patch changes it. With open_deck the model edits the very file the viewer shows, so its changes appear live in front of you.

Use it in Claude Code / Cursor

A project-scoped .mcp.json is included. From a client that supports MCP, point it at the stdio server:

{
  "mcpServers": {
    "deck-contract": { "command": "npx", "args": ["tsx", "packages/mcp-server/src/bin.ts"] }
  }
}

Then the model has 10 tools: list_templates, load_template, open_deck, get_selection, get_outline, get_node, apply_patch, insert_block, render, export_deck. A typical turn: load_template (or open_deck to share the viewer's file) → get_selection/get_outline → apply_patch (surgical edit) → render (see the PNG + any overflow issues) → fix → export_deck (PDF). Inference runs on the client's own model; this server only edits structure and renders locally.

Status

• [x] Day 1 — contract, core (tree/ids/ops), pure compile, tests without a browser

• [x] Day 2 — LocalChromiumRenderer: warm browser, network-blocked, fonts awaited, deterministic overflow / out-of-bounds measurement, PNG screenshots

• [x] Day 3 — render-and-check loop (monotone gate, anti-oscillation, bounded iters); proven to converge on golden fixtures with a deterministic solver (406→192→48→0px)

• [x] Day 4 — 8 MCP tools over stdio, PDF export, template loader + first minimal-dark package, handle-based session state; full model-flow integration test green

• [x] Day 5 — interactive viewer (click-select, inline text edit, "AI target"); get_selection + open_deck so user and model edit one shared deck.json live

MVP complete: an AI can load a template, surgically edit one component, render and self-check for overflow, and export a PDF — and the user can see the deck, edit elements directly, or point the AI at exactly the element they want changed — all on the client's own model.