Donner 0.8.0-pre
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 — Write the developer-facing documentation the design earned (a new explainer via developer_template.md, or content folded into ../developer_docs.md). Never delete the design doc or recycle its number. Instead, rewrite it in place into a short summary: set Status to Implemented, briefly describe what the design was, and link the developer docs it spawned (plus a git-history pointer to the original full doc). The developer docs are "what ships today"; this stub keeps the number and every inbound link valid forever.
  4. Retrospective — Use retrospective_template.md after a difficult bug, incident, or workstream. Retrospectives may include history, but their output should be concrete decisions, review findings, and follow-up actions.

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
  • retrospective_template.md — bug/workstream retrospectives

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).
0032 sandbox_branch_split Design Plan for extracting general-purpose improvements off the sandbox branch into main-targeted PRs (tiered by porting cost).
0033 multithreading_and_dom_lifetime Implemented DOM lifetime ownership model, ConcurrentDom access guards, and immutable render snapshots. Shipped in #596; see linked dev docs.
0033-2 editor_design_tool_responsiveness Implementing Editor responsiveness plan for high-zoom dragging, async rendering, and composited presentation.
0034 progressive_rendering Removed Historical design for progressive intermediate frames; removed after stale-canvas tile bugs.
0035 filter_layer_compose_offset_bug Fixed Root cause and coverage for the filtered-layer compose-offset/source-sync bug class.
0036 composited_presentation_retrospective Retrospective Review of the filtered drag repro, flat-mode removal, fragile code paths, testing gaps, and cleanup actions.
0037 geode_presentation_glitch_investigation Investigation Handoff notes for the remaining Geode direct-texture drag/zoom overlay pops and texture-splat glitches.
0038 geode_tinyskia_text_parity Developer reference Geode↔tiny-skia text parity (complete): the shared PlacedTextGeometry layer both backends consume + the per-test parity gate.
0039 text_editor_focus_and_flash Implemented; see Editor Source Focus Source-pane focus view, changed-character flash highlight, and context-aware soft wrap without horizontal scrolling.
0040 semantic_text_completion Design Parser-backed text completion and source block movement that preserve cursor flow and document structure.
0041 geode_analytical_aa Developer reference Geode anti-aliasing & coverage: 4× MSAA sample_mask; the accepted sub-pixel floor vs tiny's Skia-AAA; appendix of rejected AA approaches.
0041-2 path_authoring_and_boolean_operations Prototype Illustrator-like path authoring, direct path editing, and Donner-level boolean path operations for the editor.
0042 geode_slug_conformance Developer reference Geode Slug implementation reference: encoder + shader pipeline, invariants, and known limitations.
0043 deterministic_replay_testing Design Deterministic multi-thread replay framework and premortem for re-enabling #601-related tests.
0044 coverage_improvement_2026q2 Implemented Raised line coverage 81.5→85.6% (phases 0–4); also fixed 3 bugs the push surfaced (2 TextEditor crashes + EncodeColor CurrentColor).
0044-2 editor_fluid_canvas_rendering Implementation in progress Viewport-bounded high-zoom rendering, immediate-mode editor chrome/spans, and large-selection LOD for fluid editor UX.
0045 editor_geode_chrome_migration Draft Next steps for moving source ropes and chip decorative chrome from ImGui draw lists to Geode-backed screen-space rendering.
0046 editor_group_layers Design User-facing editor layer tree for SVG groups and shapes, with per-tier previews and selection sync.
0047 v0_8_showcase Design v0.8 rebrand and splash showcase for Donner SVG Editor & Toolkit, including text-to-outlines and viewport SVG export with overlay chrome.

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: