Archscribe: JSON specs rendered as animated Excalidraw diagrams

One JSON spec fans out into several artifacts

The unit of work is a JSON spec file, and a single spec produces several outputs rather than one picture. By default the browser renderer emits four artifacts together:

<basename>.excalidraw
<basename>.png
<basename>.gif
<basename>.mp4

The Excalidraw file stays editable and plain text, so the diagram can be opened and adjusted later, while the PNG serves as a static preview and the GIF and MP4 carry the motion. Two more formats are optional: a standalone SVG with embedded fonts, and an interactive HTML page. That HTML is more than a static export. Clicking a module highlights its connections, a checkbox can walk the whole chain to show breadth-first propagation, and there is hover text plus keyboard support, all inside one shareable file. A formats flag selects which of the six you actually want, since rendering every artifact is wasted work when you only need a still.

Three layout templates encode different topologies

The spec chooses among three layouts, and each suits a different kind of explanation. Panorama is the default and handles a full system overview, moving from input sources through a core pipeline to output panels; it takes between two and six inputs and two to four core cards, and its three bottom panels are all optional. Swimlane is for categorised horizontal bands and comparisons, taking two to five lanes with one to five steps each, a title column that can carry a subtitle, and connections that loop back through a dashed channel drawn beneath the cards. Graph is the free-form option for irregular flows, supporting two to 24 nodes and up to 40 edges, including explicit loop edges. The canvas height is computed from content, and a long rightward chain with more than seven sequential levels is automatically stacked downward so it does not get clipped.

Headless Chromium draws it, Pillow is the fallback

Rendering happens in a headless browser by default. A script launches its own headless Chromium through Playwright, uses rough.js to give every shape a hand-drawn look, and loads built-in webfonts so the result looks the same on every machine, independent of what fonts the host has installed. This browser is spawned by the tool itself and has nothing to do with any browser built into a coding agent, so nothing has to be started by hand. Enabling it means installing the browser requirements file and the Chromium binary for Playwright. If those are missing, the renderer does not fail loudly; it quietly drops to a classic Pillow pipeline, which is kept in the codebase as a fallback. That graceful degradation is convenient but also the main trap, since a missing browser looks like success while quietly downgrading the output. An icon-engine flag only affects the quality of icons on that Pillow fallback.

Two styles share one layout and animation engine

Style is purely a colour and finishing choice; the layout, animation, and icon behaviour are identical between the two built-in styles. The default style is a hand-drawn neon look on a pure black background, with flowing light beams, film grain, and a vignette, and it is the brand default. The paper style is a warm off-white page with alternating sage green and periwinkle bands, near-black ink lines, and white cards with coloured borders; in this style the flowing light animation is replaced by small dots that travel along the arrows, and the grain and vignette are dropped. The style can be set on the command line or in the spec, and when both are present the command line wins. If neither is set, the default applies, and any other style name is an outright error rather than a silent fallback. For the graph layout specifically, the docs advise against hand-writing the canvas width and height.

Animation presets set the frame budget

Motion is chosen from six named presets, and every layout supports all of them: flow, draw, relay, trace, chapter, and failure-recovery. The presets differ mainly in length and character, which is why they carry very different frame counts. Rendering runs at 20 frames per second on a canvas 1210 pixels wide, with the height derived from the layout. A flow loop is 41 frames, roughly a two-second cycle, which is the shortest of the presets. Draw needs at least 72 frames, and relay needs at least 88. That spread matters for output size and for the MP4-versus-GIF tradeoff the tool is built around: MP4 files are much smaller than GIFs and are natively supported by X and WeChat, while the GIFs use a shared global palette to stay small. When iterating on layout, the advice is to render a single PNG first, which takes seconds, before committing to a full animated render.

Validation is a first-class output check

The tool treats correctness checking as part of rendering rather than an afterthought. A validate-only mode runs the config pre-check and exits, reporting problems at the field level with a path, a message, and a suggested fix, which is structured so an automated agent can correct a bad spec and retry. The same pre-check runs automatically before a normal render. A check flag then validates the full output contract after the fact: image and GIF dimensions, frame counts, frames per second, whether the animation is real rather than a still repeated, MP4 stream parameters, embedded fonts in the SVG, interactive hotspots in the HTML, and invariants in the Excalidraw file. It also inspects graph layouts for clipping and vertical imbalance, and confirms long chains turned safely. A verify flag prints a sampled frame-difference report, where a non-zero count of changed pixels is the evidence that motion actually happened.

Brand overrides escape the built-in icon set

Customisation is handled by pointing entries at your own files rather than by editing the renderer. Any item can carry an icon_file reference to a local SVG or PNG, which is used as a colour icon or product logo with its original colours preserved. A panel-level badge_file places a brand mark in a panel header. An input_style set to plain switches to borderless colour input icons, and three label fields rewrite the built-in arrow captions, which is what you reach for when the default wording does not fit your process. There is also handling for the case where a signature is too long, such as a bare domain name: it is shifted left and given a stretched underline instead of being cropped, so a long value stays readable. The built-in icon system itself has three tiers, outline, illustrated, and hero, plus small deterministic motions such as a pulsing brain, a turning gear, a scanning eye, and a memory write, and on the flow preset the icons carry an extra wave-like bounce.

Editorial conclusion

Archscribe suits people writing technical articles or system explainers who want a hand-drawn look and an editable source file rather than a flat image, and who are willing to keep a JSON spec as the real version of the diagram. It is a weaker fit if you need one-off drawings edited by hand, since the layout logic and the validation flags assume the spec is the source of truth. Before adopting it, decide whether you will install the browser dependencies, because without Chromium the renderer quietly falls back to the Pillow pipeline and you lose the higher-fidelity hand-drawn look. Also check your frame budget, since the longer animation presets produce many more frames than a short loop.

Frequently asked questions

Official sources

1. Issues
2. lazypay/Archscribe on GitHub
3. License: MIT
4. README