1# Renderer plane23This directory contains the complete Cloudflare renderer plane for diagram.zip.45| Path | Purpose |6| --- | --- |7| `catalog/` | Health and capability catalog service; it does not render diagrams |8| `browser-run/` | Private Browser Run service, per-engine Durable Object sessions, and pinned frames under `frames/` |9| `edge/` | JavaScript and WebAssembly renderer Workers |10| `python/` | Python renderer and translation Workers |11| `shared/` | Engine identities shared by the catalog and runtime units |12| `scripts/` | Cross-runtime deployment and smoke-test orchestration |1314All 32 catalog engines have a final renderer path. No renderer uses the Fly.io application. No renderer can use an origin fallback.1516Each engine has a hostname:1718```text19https://{engine}.render.diagram.zip20```2122The hostname selects the engine. A render request does not contain an engine selector.2324The Worker in `catalog/` serves `diagram.zip/render/v1/*`. It provides health and catalog routes. It does not provide a render proxy.2526## Validation2728Run these commands from `renderers/`:2930```sh31npm --prefix edge install32npm --prefix edge run generate:types33npm --prefix edge run check34npm --prefix edge test35npm --prefix edge run deploy:dry-run36```3738Run `npm --prefix edge run smoke:renderers` after all units are deployed. This command checks one repository fixture or capability response for each catalog engine. It checks coverage and SVG structure. It does not compare pixels.3940Run `npm --prefix edge run smoke:catalog` against a local catalog Worker. This command checks the health route, the 32-engine catalog, and the absence of the old render proxy.4142## HTTP unit contract4344An HTTP renderer provides these routes:4546- `GET /v1/health`47- `GET /v1/capabilities`48- `POST /v1/svg`4950The POST body contains source, options, metadata, and presentation settings. It does not contain an engine field.5152The response headers identify the unit, build, and pipeline:5354- `X-Diagram-Unit`55- `X-Renderer-Build`56- `X-Diagram-Pipeline`5758## Browser Run contract5960Mermaid and diagrams.net expose the same public HTTP unit contract as every other engine. Their public Workers validate the hostname-selected request and call the private `browser-run/` Worker through a service binding. The private Worker has no public route.6162Browser Run keeps one serialized Durable Object session per engine, launches the pinned frame, and uses the `diagram.zip:renderer:v1` message protocol internally. Idle sessions close after 60 seconds. A failed browser render does not select another renderer.6364The Browser Run engines are Mermaid and diagrams.net. BPMN and Excalidraw use JavaScript Workers; TikZ uses a WebAssembly Worker.6566## Dependency groups6768One Worker can serve several hostnames when the engines use the same dependency stack.6970- `blockdiag-family` serves BlockDiag, SeqDiag, ActDiag, NwDiag, PacketDiag, and RackDiag.71- `graphviz-family` serves GraphViz, DBML, and ERD.72- `plantuml-family` serves PlantUML and C4 PlantUML.73- `svgbob-family` serves Svgbob and the Ditaa translation.74- `vega-family` serves Vega and Vega-Lite.7576Some units translate source into another engine. The pipeline header lists each stage in order. WireViz translates to GraphViz. Structurizr translates to PlantUML. DBML and ERD translate to GraphViz. Ditaa translates to Svgbob.7778## Runtime split7980| Runtime | Count | Engines |81| --- | ---: | --- |82| Worker JavaScript | 11 | BPMN, Bytefield, Excalidraw, Nomnoml, Squaring, Structurizr, TRN, UMLet, Vega, Vega-Lite, WaveDrom |83| Worker Python | 8 | BlockDiag, SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag, Symbolator, WireViz |84| Worker WebAssembly | 11 | PlantUML, C4 PlantUML, GraphViz, DBML, ERD, D2, Ditaa, GoAT, Pikchr, Svgbob, TikZ |85| Browser Run | 2 | Mermaid, diagrams.net |8687The total is 32 of 32 engines. The Fly.io Java rendering image is not part of this renderer plane.8889## Output policy9091Every renderer returns SVG through its public HTTP unit. The unit sanitizes and canonicalizes the result before it reaches the application, which applies presentation without rerunning the renderer.9293Scripts, event handlers, active embedded HTML, and external resources are not allowed. Renderer-specific losses are listed in the catalog and in each unit's capabilities response.