donner

Using Donner as a library from a consumer's point of view — the public SVG DOM API (SVGParser/SVGDocument/SVGElement/Renderer), the runnable examples/ programs, consuming Donner via Bazel module or the generated CMake mirror, Geode embedded (host-owned WebGPU device) mode, and the ECS-is-internal public-API boundary. Use when writing or reviewing code that parses/renders SVGs through the public API, when working in examples/ or examples/cmake_consumer/, when answering "how do I add Donner to my project", when editing docs/getting_started.md or docs/guides/embedding_geode.md, or when a change might leak ECS types (Registry, EntityHandle, EnTT) into a public header.

Run, scope, and configure Donner's Bazel build/test surface: choosing a --config, the variant lanes (*_tiny/*_text_full/*_geode), authoring BUILD.bazel targets with the donner_* macros, sanitizers (asan/ubsan/tsan), coverage, WASM/Emscripten builds, and the CMake mirror. Use when running bazel test/build, debugging a *_lint or variant-lane failure, adding or modifying BUILD.bazel targets, running the presubmit ritual before pushing a PR, or reading a sanitizer report.

PR lifecycle and CI triage playbook for Donner: the pre-push gate, PR hygiene rules (🤖 comment convention, no agent branding), the ~7-minute monitoring loop, merge rules, main.yml anatomy, and the transient-vs-real failure decision tree with artifact-driven diagnosis. Use when opening, updating, rebasing, or monitoring any PR; when responding to review comments; when a GitHub Actions check is red, hanging, or selected the wrong Bazel targets; or when deciding whether a PR is ready to merge.

Build, serve, test, package, security-review, deploy, verify, and roll back Donner's browser editor static site. Use when asked to build or host the Donner WASM editor; prepare the Geode or TinySkia web package; run browser parity tests; create or inspect an immutable deployment candidate; configure HTTPS, WebGPU, SharedArrayBuffer, COOP/COEP, MIME, CSP, or cache headers; publish the editor to a static host; or diagnose a deployed editor that is blank, not cross-origin isolated, or unable to load its pthread or WebGPU assets.

The mandatory red-to-green bug-fix workflow for Donner — write a failing repro test first, capture failure evidence, commit red then fix, and write diagnosable gmock-based tests (including perf repros with donner_perf_cc_test). Use when fixing any reported bug, writing a regression or perf test, preparing a commit that says "Fixes

Donner's C++ conventions with failure signatures - naming, destFromSource transform discipline, string types, the lifetimebound view-return footgun, banned patterns and the *_lint tests that enforce them, no-exceptions/no-std::any, Doxygen style, formatting commands, and no-dead-code/refactor-in-place. Use when writing, editing, or reviewing any C++ under donner/, or when fixing a *_lint test failure or a clang-tidy / clang-diagnostic-dangling error.

Authoring Donner design docs and Doxygen developer documentation — doc-type selection, numbering and collision protocol, the no-history and invariants-name-a-CI-target rules, DesignReviewBot gating, finalization stubs, and Doxygen page authoring/rendering traps. Use when creating, updating, reviewing, or finalizing anything under docs/design_docs/, writing or editing developer docs under docs/, adding a page to the Doxygen site, or running tools/doxygen.sh / tools/build_docs.sh.

Reproduce and root-cause Donner editor visual/interaction bugs via .rnr replay (editor_rnr_gl_replay), the editor-control MCP server, layer-by-layer escalation, and deterministic replay scheduling. Use when debugging one-frame glitches, overlay jumps, stale drag content, checkerboard flashes, wrong-scale textures, or element pop-backs; when an editor screenshot or .rnr replay is needed; or when driving or extending the editor-control MCP under tools/mcp-servers/editor-control/.

The hard boundaries for Donner editor code: DOM-level editing only (never source-string surgery), Donner renders all vector graphics (never ImGui draw-list primitives for document content), the EditorApp::applyMutation/CommandQueue mutation funnel, and presentation invariants (overlay lockstep, no broad cache clears). Use when implementing or modifying editor operations (tools, reorder/rename/insert/delete/group, undo, source-pane behavior), UI panels/thumbnails/overlays, or anything touching files under donner/editor/ such as EditorApp, CommandQueue, DocumentSyncController, AsyncSVGDocument — or when tempted to draw document content with ImGui or splice source text.

Run, add, and triage Donner's libFuzzer fuzzers: the donner_cc_fuzzer three-target pattern, --config=asan-fuzzer, the manual deep-fuzz loop, corpus lifecycle, and the continuous-fuzzing harness in tools/fuzzing/. Use when a parser change warrants fuzz validation, when reproducing or fixing a crash-* / leak-* / timeout-* artifact or a fuzzer-filed GitHub issue, when adding a fuzzer for a new parser, or when managing fuzz corpora (manage_corpus.py, *_corpus dirs).

Working on Geode, Donner's GPU (WebGPU / wgpu-native) rendering backend: build configs, the pipeline-ownership rule, headless/llvmpipe environments, WGSL shaders, and Geode-lane test failures. Use when changing anything under donner/svg/renderer/geode/, when a *_geode variant or Geode golden test fails, when editing .wgsl shaders, when you see "[Geode/wgpu-native]" errors or WebGPU device/adapter problems, or when running Geode tests on headless/CI machines.

Conventions for Donner's parser suite (XML/SVG/CSS/scalar), the ParseWarningSink diagnostics contract, the CSS engine and PropertyRegistry, and the text-rendering tiers (TextBackendSimple/TextBackendFull). Use when editing or adding a parser under donner/base/parser, donner/base/xml, donner/svg/parser, or donner/css/parser; when emitting or testing ParseDiagnostic/ParseWarningSink output; when adding a CSS property or touching selectors/cascade/StyleSystem; or when changing text shaping/fonts under donner/svg/text and deciding which build tiers (--config=text-full, tiny) must be tested.

Author, triage, and update bitmap/golden-image comparisons in Donner using the one blessed comparator (bitmap_golden_compare / ImageComparisonTestFixture + pixelmatch), read diff PNGs, and regenerate goldens safely. Use when a golden-image or pixel-diff test fails (output mentions "pixels differ", actual_*.png / diff_*.png, or UPDATE_GOLDEN_IMAGES_DIR), when writing any new bitmap comparison (editor replay, layer thumbnails, renderer goldens), or when regenerating goldens after an intentional rendering change.

Cutting a Donner release end-to-end: pre-release quality gates, RELEASE_NOTES.md rules, the dedicated build-report commit that gets tagged, GitHub Release + binary verification, Bazel Central Registry (BCR) publishing pre-flight, and dependency-update handling. Use when preparing or cutting a release, editing RELEASE_NOTES.md, running tools/generate_build_report.py, publishing to BCR (.bcr/, release.yml publish-to-bcr job), or handling Renovate/dependency PRs.

Mental model and add-a-feature checklist for Donner's SVG rendering pipeline — ECS system order, RenderingInstanceComponent traversal, the RendererInterface contract, dual-backend (tiny-skia + Geode) obligations, and an end-to-end "add a new SVG element" walkthrough. Use when touching donner/svg/renderer/ or donner/svg/components/, adding an SVG element or presentation attribute that affects pixels, implementing a RendererInterface method, or diagnosing why an element renders wrong or is missing from the render tree.

Run and triage Donner's resvg SVG-conformance suite — filtering tests, reading [COMPARE] failures, editing Params::Skip/RenderOnly/threshold entries in resvg_test_suite.cc, and handling the per-backend comparison modes. Use when a resvg_test_suite test fails, when enabling tests for a newly implemented SVG feature, when adding/removing skip entries or thresholds, when running a DISABLED_ (skipped) comparison, or when touching donner/svg/renderer/tests/resvg_test_suite.cc or third_party/resvg-test-suite.