Artboard renderer: how it works

Renders one artboard of a design state without a browser by running the editor's own export, so MCP tools can look at a design and iterate on it; paywall-gated editor exports are the second, not yet viable, use (hosting §1). API and commands: the app's README. Hosting: hosting. Paths are relative to apps/artboard-renderer/.

1. How it works

1.1 Layers

SelectionDownloader.exportSubState        editor     "export board X as png, jpg, svg or pdf"
Fabric, RasterizeImage, getSvgFromBoard   editor     "draw or serialize the objects"
@napi-rs/canvas (native Skia)             renderer   "make the pixels" (raster parts only)

tools/buildEngine.ts bundles the editor layers from @repo/rendering sources unchanged, except that the editor's synchronous test workers (workers-jest.ts) replace its Web Workers.

1.2 Fake DOM

The editor only calls browser globals. installFakeDom() in src/fakeDom.ts answers them with linkedom and native canvases, without changing editor code:

document.createElement('canvas') → linkedom element
canvas.getContext('2d')          → context2d() in src/canvas.ts: a Proxy over a native context
canvas.toDataURL() / toBlob()    → napi encoder
new Image(); img.src = url        → NetworkImage: fetch, decode with napi
fetch(url)                        → http(s) on allowed hosts only, no redirects, User-Agent, 10 s timeout,
                                    cached for the export; failures go to x-render-report

Fabric keeps a context across canvas resizes, and a resize replaces the native canvas, so the Proxy looks the native context up on every access:

// src/canvas.ts
get: (_target, key) => {
  const context = backing(canvas).getContext('2d'); // the native canvas at its current size
  ...

Also faked: FileReader (the export writes the DPI into PNG and JPEG files), classList tagged DOMTokenList (lodash's cloneDeep in SVG and PDF export breaks otherwise) and getElementsByTagName('*'). As in the editor's build, fs points at pdfkit's virtual fs.

1.3 One request

POST /render ─▶ supervisor (container/server.ts, container/supervisor.ts)
                  ├─ 408 past 15 s of upload; 413 when the design state body is over 10 MiB; 503 with 5 requests
                  │  held (counted before their body is read) or after 10 s in the queue
                  └─ one job at a time over IPC; 504 and SIGKILL past 25 s
                       ▼
                render process (container/renderChild.ts), engine loaded once
                  renderBoard (src/engine.ts): 400 on a bad body, format or size
                  migrateDesignState → keep one board → designStateToNormalised → exportSubState
                  x-render-report if an asset failed
                  then: cancel animation frames, clear the fetch cache and failures, shrink canvases,
                  GC if images were decoded

The supervisor replaces the render process, and the queue continues, when:

The editor's URLs are runtime config, not part of the bundle: one image serves every environment.

wrangler.jsonc vars (per env) ─▶ Renderer.envVars (src/index.ts) ─▶ container env
  API_STORAGE_URL ─┐
  USER_API_URL     ├─ editorEnv (src/runtimeEnv.ts) ─▶ REACT_APP_* in the render process's env,
  CONTENT_URL     ─┘    set before it imports the editor, which reads them at import time

1.4 Render report

A missing asset doesn't fail the render: the response is still 200 with the file, drawn without it, and the x-render-report header lists what's missing. The same header comes with every format, and the Worker passes it through.

complete    200, no x-render-report
missing     200, x-render-report: {"missingCount":2,"missingAssets":[
              {"src":"https://api-objects.stagingdesigner.com/users/…/paths/….json","reason":"http_403"},
              {"src":"http://169.254.169.254/meta-data.png","reason":"blocked_host"}]}
truncated   200, x-render-report: {"missingCount":14,"missingAssets":[…10 entries…],"truncated":true}

• No header isn't proof of a complete file: text in a workspace font can fall back to the default font unreported (§5).
• An image, illustration (SVG or edited paths) or font file counts. A font file fails like any asset (http_404, timeout). The user API doesn't count: without the caller's session it answers 401, and the editor falls back (its font list).
• A URL counts once, with its last reason; a URL a retry or a later load fetched isn't listed.
• At most 10 entries, each src cut to 300 characters, and fewer when escaping would take the header over 4 KB; missingCount is the real total. ASCII only: other characters are escaped as JSON \uXXXX.

The MCP tool puts it next to the image as a note:

const response = await fetch(`${baseUrl}/render?board=${boardId}`, { method: 'POST', body, headers });
const image = { type: 'image', data: toBase64(await response.arrayBuffer()), mimeType: 'image/png' };
const report = response.headers.get('x-render-report');
if (!report) {
  return { content: [image] };
}
const { missingCount, missingAssets } = JSON.parse(report);
const listed = missingAssets.map(({ src, reason }) => `${src} (${reason})`).join(', ');
return { content: [image, { type: 'text', text: `Incomplete preview: ${missingCount} asset(s) didn't load: ${listed}` }] };

1.5 What the MCP tool should ask for

The model's image tokens, not render CPU, are the cost: a render costs ≈ $0.00002, its image ~60× that in input tokens (hosting §3.1). size takes any width 16–2048 and barely changes render time, since loading and decoding dominate (hosting §2.2). So pick the smallest size that answers the question:

first read      stored preview, no render ── Design.preview
overview        contact sheet, ≤ 16 boards × 256 px cells    (to build)
one board       size=384
verify an edit  size=512, the changed board only
small text      size=1024, or crop/zoom at 512               (crop: to build)

*A common vision-model formula, ceil(w/28) × ceil(h/28), on a square image.

• Stored preview: Design.preview, a ~724 px JPEG written by editor saves, served by GET /designs/:id/preview?width=&height= and already returned as thumbnailUrl by the project list tool. It shows only config.previewBoardId, and is stale when the last change didn't come from the editor (an MCP edit through the API).
• Contact sheet: ~1,400 tokens for 16 boards, against 16 × 361 at 512. Render time still grows with boards (hosting §2.5), so cap it at ~16 and say so in the tool result; that covers p90 designs (13 boards).
• Result cache (to build): key = content hash of the board's JSON and its asset URLs, plus size and format; stored in R2 or KV. An unchanged board hits; an edited board misses by design.

2. Formats

pixelsOff is the share of pixels whose largest RGB channel difference is above 40/255, both images flattened onto white; meanDiff is the mean of that difference (0–255). References: §3.

3. Against Chrome

References are the editor's own exports in Chrome: the export snapshots in apps/editor/e2e/__screenshots__/ (Playwright Chromium, CPU raster) and one staging PNG export. SVG and PDF are rasterized as the e2e suite does it (a Chromium screenshot; pdf.js at scale 1).

Not covered: JPG (the only RGB JPEG reference removes the background, which /render doesn't offer) and boards wider than 2048.

napi output is deterministic per machine. amd64 and arm64 differ by meanDiff ≤ 0.105 with no pixel above 40/255 (Skia picks SIMD paths per CPU), so golden tests need a tolerance or a single architecture.

4. Why not CanvasKit

CanvasKit (Skia as WASM, with Google's JS Canvas2D emulation) is the alternative. napi is the renderer because it matches Chrome where CanvasKit doesn't:

transformed-shadows, CanvasKit left, napi right:

brand-kits-apply: CanvasKit, napi, and their difference in red:

5. Limitations

6. Before running as a shared service

6.1 Shared-package changes ship separately

The renderer relies on one @repo/rendering behavior that ships with the editor in its own PR: when toBlob returns null, alphaMask.ts rejects every waiting caller and clears its cache entry, so a later call can retry; alphaMask.test.ts covers it.

Known bugs the renderer works around (paths under packages/):

6.2 The double load

exportSubState loads the board into canvas #1, then hands it to exportTargets, the live editor's export path. That path serializes the board, rebuilds a cropped standalone state and loads it into canvas #2 before the only rasterize (paths under packages/editor-core/rendering/rendering/src/exporting/download/):

exportSubState(state)                                  selectionDownloader.ts:351
 ├─ loadStandaloneState(state, 'substate-export')      :367   LOAD 1 → canvas #1
 └─ exportTargets(canvas #1, { boardId | nodeIds })    :375
     ├─ waitForExportAssetsToLoad
     └─ _getAllDownloadObjectFromSelection
         ├─ mockupDesignManager.waitForPendingWarpWork
         ├─ gatherAllSelectionData(canvas #1)                 serialize objects, board, bounds
         └─ _getDownloadSelectionObject
             ├─ getSafeDimensions(bounds)
             ├─ getStandaloneState(…)                         cropped standalone state
             ├─ loadStandaloneState(…, 'selection-download')  :119  LOAD 2 → canvas #2
             └─ rasterize (png, jpg) or getSvgFromBoard (svg, pdf) on canvas #2

• Cost: load 2 ≈ load 1, 35–50% of render CPU (hosting §2.3).
• Origin: added with the canvas export capability (Kittl/mono#14186) by reusing exportTargets; no documented reason for canvas #2.
• Who pays: every exportSubState caller: this renderer and the editor's canvas capability (apps/editor/src/extensions/EditorService/EditorService.ts). The editor's main download path (live canvas → one clean copy) loads once and is unaffected.
• Fix direction, a @repo/rendering PR:
  1. Ask the author whether canvas #2 guards an edge case.
  2. Rasterize canvas #1 directly, keeping what the skipped steps compute: bounds and crop, safe dimensions, background removal, floating-board node targets, the mockup warp wait.
  3. Prove pixel parity in png, jpg, svg and pdf with pnpm test:e2e: baseline before, compare after.