Overview

donner-svg is a command line utility for rendering SVG files to PNG and previewing output in terminal environments. A convenience wrapper is checked in at tools/donner-svg, which is the recommended way to invoke it from inside the repository.

Build and run:

tools/donner-svg input.svg

Rendering backend

donner-svg always renders with Donner's CPU (tiny-skia) backend, under every build configuration. A one-shot command-line render cannot amortize the GPU backend's fixed device and shader setup cost, so the CPU path is faster for single-frame output. The GPU (Geode) backend is Donner's interactive renderer, used by long-lived surfaces such as the editor, where that setup cost is paid once across many frames.

Common flags

--output <png>: Output filename (default output.png).
--width <px> / --height <px>: Override render size.
--scale <factor>: Scale the document's intrinsic size, for example --scale 2 for a 2x render. Cannot be combined with --width or --height, and each scaled side must be at most 65535 pixels.
--preview: Show a terminal preview.
--interactive: Enable mouse-driven terminal selection mode (implies --preview).
--quiet: Suppress parser warnings.
--verbose: Enable verbose renderer logs.
--experimental: Enable experimental parser features.
--help: Print usage.

Animated GIF export

--gif <file.gif> renders a declarative (SMIL) animation to a looping animated GIF instead of a PNG. Frames sample document time start + i / fps for every frame index i that falls before --end. When (end - start) * fps is a whole number, the animation loops seamlessly from end back to start; otherwise the last frame is shown for a full frame period. The canvas keeps its size at --start for every frame, and each side is limited to 65535 pixels. An export is limited to 10000 frames and 2^28 rendered pixels in total. The encoded file, encoder workspace, and renderer surfaces each have separate 256 MiB limits; the command also admits its snapshot and fitted-frame buffers within the workspace limit before entering the frame loop.

--end <s>: Animation end time in seconds (required).
--start <s>: First frame's document time in seconds (default 0).
--fps <n>: Frames per second (default 20, at least about 0.0016, the slowest rate a GIF frame delay can represent). GIF delays are whole centiseconds, so the delays alternate as needed to keep the total duration exact.
--scale, --width and --height set the GIF size as they do for PNG output.
--background <color>: Composite onto an opaque CSS color and produce an opaque GIF. Without it, the GIF keeps binary transparency: pixels below 50% opacity become transparent. Transparent exports reserve color-table index 0 consistently so common decoders clear disposed frames and loop restarts to transparency.

Each frame gets its own color table. Frames with at most 256 colors (255 without --background, which reserves one entry for transparency) are stored exactly; busier frames are reduced with median cut, which keeps large flat colors exact. Identical consecutive frames are merged into one longer frame, and opaque GIFs store only the changed region of each frame.

Examples

# Render to PNG
tools/donner-svg input.svg --output output.png
 
# Terminal preview mode
tools/donner-svg input.svg --preview
 
# Interactive mode
tools/donner-svg input.svg --interactive
 
# Animated GIF of the first 4 seconds at 20 fps and twice the intrinsic size
tools/donner-svg input.svg --gif output.gif --end 4 --fps 20 --scale 2 --background white

Note: tools/donner-svg is a thin shell wrapper that invokes bazel run //donner/svg/tool:donner-svg -- <args> with Bazel's progress/info output suppressed so the tool behaves like a normal CLI. The underlying Bazel target can also be invoked directly.

Terminal preview

--preview renders the SVG directly in the terminal using Unicode quadrant block characters with 24-bit truecolor foreground and background, giving 2x2 sub-pixels per character cell.

Interactive mode

--interactive implies --preview and adds mouse-driven selection: hover over the terminal image to see the element under the cursor, and click to lock the selection. The right-hand pane shows the DOM path and computed style of the selected element.