Donner 0.5.1
Embeddable browser-grade SVG2 engine
Loading...
Searching...
No Matches
design_docs Directory Reference
Directory dependency graph for design_docs:

Detailed Description

Donner Design Docs

This directory holds every design doc for the Donner project, numbered ADR-style in the order they were first written. New docs append the next free number — NNNN-short_name.md — and existing numbers never change once assigned, so external references stay stable.

On number collisions.

  • Pre-merge (both docs unmerged): the second doc simply renumbers to the next free slot. Cheap — nothing external references an unmerged doc yet.
  • Post-merge (one doc is already on main): if a parallel branch assigned the same number, the new doc adopts a -2 suffix: NNNN-2-short_name.md (third collider -3, etc.). The already-landed doc keeps its bare NNNN- form so external links stay stable. No renumbering, no history rewrite.

For how Donner's runtime is organized and documented, start with the Developer Docs. Design docs capture why a piece of the system looks the way it does (or will look). Developer docs describe what ships today.

Workflow

  1. Draft (Status: Draft) — Use design_template.md. Goals, non-goals, open questions, a first pass at the implementation plan.
  2. In Progress — Mark TODOs in the implementation plan. Check them off as milestones land. The doc is the single source of truth for "where is this?"
  3. Shipped / Implemented — Convert the doc to a developer-facing explainer using developer_template.md, or fold the still-relevant content into ../developer_docs.md and leave a brief pointer behind.

See AGENTS.md in this directory for more detail on the conventions automated agents should follow when editing design docs.

Templates

  • design_template.md — in-flight designs
  • developer_template.md — shipped features

Document Index

# Doc Status Summary
0001 terminal_image_viewer — Plans for a terminal image viewer to preview SVG renders over SSH / in CI output.
0002 mcp_test_triage_server — MCP server that lets agents triage resvg golden-image diffs interactively.
0003 renderer_interface_design Shipped (Phases 1–2a; Phase 2b–4 future) The abstract RendererInterface / RendererDriver split that unblocked multiple backends.
0004 external_svg_references Shipped How <image href="…"> and <use href="…other.svg"> are fetched, sandboxed, and cached.
0005 incremental_invalidation Partially implemented Dirty-flag propagation from DOM mutations through layout, style, and compositing.
0006 color_emoji — Rendering strategy for COLR/CPAL and CBDT color-emoji tables.
0007 coverage_improvement_plan Complete The plan used to raise Donner's line coverage into the 80%+ range.
0008 css_fonts Partial CSS @font-face loading pipeline (TTF/OTF/WOFF/WOFF2).
0009 resvg_test_suite_bugs Living catalog Cases where resvg's golden images disagree with the SVG/CSS spec.
0010 text_rendering Implemented (Phases 1–6); backend refactor complete <text>, <tspan>, <textPath>, the stb / FreeType / HarfBuzz backend tiers.
0011 v0_5_release Shipped (v0.5.0, 2026-04-16) Release checklist and implementation plan for shipping v0.5, plus retrospective for the next release.
0012 continuous_fuzzing Design Dockerized always-on fuzzing harness for every parser surface.
0013 coverage_improvement In Progress (Round 1 complete, Round 2 in progress) Ongoing per-round coverage work: what's still uncovered and why.
0014 filter_performance Complete (all filters within 1.5× of Skia) How the tiny-skia filter pipeline caught up with Skia on every primitive.
0015 skia_filter_conformance In Progress Keeping tiny-skia's filter output pixel-close to the Skia reference.
0016 ci_escape_prevention Phase 1 Implemented Taxonomy of CI escapes and the checks that catch each one before merge.
0017 geode_renderer Phase 0–2 complete; Phase 5b resvg suite green on MSAA The GPU-backed Geode renderer (originally Dawn, now wgpu-native).
0018 bcr_release Active — first BCR release is planned for v0.5.0 Step-by-step for publishing Donner to the Bazel Central Registry.
0019 css_token_stream Implemented (Milestones 1–3); Milestone 4 STOP HERE The ComponentValueStream replacement for ad-hoc CSS token iteration.
0020 editor Draft Bringing jwmcglynn/donner-editor in-tree as //donner/editor.
0021 resvg_feature_gaps Living catalog SVG features Donner doesn't implement yet (or implements incompletely).
0022 resvg_test_suite_upgrade Design Upgrading the vendored resvg test suite snapshot to a newer revision.
0023 editor_sandbox Design Browser-style process isolation for the editor's parser / renderer.
0024 proposed_issues_2026q2 Draft Q2 2026 wishlist: feature gaps and CI improvements.
0025 composited_rendering Draft Layer-based compositor for fluid editor dragging without full re-render.
0026 svg_conformance_testing Draft Manifest-driven SVG 1.1 filter + WPT + scripted conformance program.
0027 scripting Draft donner::script: QuickJS-NG + IDL codegen that projects the ECS as the DOM.
0028 v1_0_release Draft Release checklist and implementation plan for shipping v1.0 (full ProjectRoadmap scope).
0029 ci_runtime Superseded by 0031 CI runtime reduction plan (post-Skia baseline, per-config cache slots, runner sizing). Scope folded into 0031.
0030 geode_performance In Progress Geode GPU-backend performance milestones (counters, arenas, shared command encoder, target reuse).
0031 ci_hardening_2026q2 Design Consolidated CI work for 2026-Q2: escape prevention (issue #552 class) + runtime reduction (subsumes 0029).

Cross-reference: developer docs

Once a design ships and stabilizes, its runtime surface is documented in the developer-facing tree under docs/. Especially relevant entry points: