acorde-render-svg

Pure-Rust/WASM SVG renderer driven by acorde-core and acorde-layout.

The crate provides render_svg, render_svg_with_layout, render_svg_row, render_svg_metadata, and render_svg_with_annotations. Host-defined RenderAnnotation providers can add safe text marks using viewport coordinates; provider and mark IDs are validated and serialized deterministically. Providers may additionally return SvgAnnotationMetrics and SvgAnnotationCollisionPolicy from collision_policy() to route selected marks through the same deterministic priority/class/direction collision pass as logical layout. Bounds are provider-supplied SVG-pixel geometry; the renderer does not load fonts or infer text metrics. Providers that return no policy retain their requested position. Native measure text (including rehearsal marks and figured bass), simultaneous note lyrics, dynamics, chord symbols, and articulations use that pass after existing note-annotation clearance calculation. Spans and tablature lanes remain separate. The renderer accepts at most 10,000 marks and 16 KiB of UTF-8 text per mark; excess input returns a typed error before SVG emission. Output is deterministic and may include stable data-note-addr hooks for host-side selection and hit testing. glyph_coverage() reports the built-in resource ID, supported clefs, and accidental range before rendering; unsupported clefs/accidentals return RenderError rather than a blank fallback. The renderer has no browser/DOM dependency and uses font-independent SVG geometry for notation glyphs. Tablature staffs render their configured line count, explicit string/fret positions, and guitar bend/slide/hammer-on/pull-off technique labels; missing positions are shown as an explicit ? marker rather than inferred silently. Authored ties are emitted only between pitched note endpoints; a tie start adjacent to a rest is not drawn across silence. Metadata contract version 22 exposes typed note semantics (including tie_start and tie_end), score and measure text, tablature positions and technique connections, object-style overrides, harp-pedal diagrams, semantic section breaks, and staff presentation without requiring hosts to parse SVG geometry. Standard staves use the authored line count and line distance; tablature uses its configured string-line count. A cutaway staff is omitted from a system containing only implicit rests while retaining its vertical coordinate slot for stable cross-staff addresses. render_preflight() reports the renderer's unsupported staff or measure clef, accidental, and tablature-position boundaries with stable score source locations before SVG emission. This also covers clef changes represented on individual measures rather than only the staff default. Measure-level StyledText entries are emitted as deterministic acorde-measure-text-* SVG text classes, with stable part/staff/measure/text-index hooks when interactive output is enabled. Placement and MusicXML offset hints are projected into host-neutral coordinates; font selection, font metrics, embedding, and final publication remain host responsibilities. Text is bounded to the same 16 KiB-per-entry limit as host annotations, and non-finite or non-representable offsets are rejected before any SVG is emitted. XML 1.0-incompatible control characters in score text and host annotations are also rejected before serialization, rather than being escaped into invalid XML. render_preflight() reports oversized measure text, invalid text offsets, and invalid XML characters with source locations before the renderer is invoked. Finite extreme vertical text offsets expand the content-aware SVG breathing room rather than being clipped by the ordinary staff margins. Multiple measure-level entries on the same side of a staff are stacked in source order with a stable staff-space separation; this is a bounded deterministic policy, not full font-aware engraving collision optimization. Legacy measure fields (tempo_text, rehearsal, navigation, and expression_text) are normalized into the same StyledText render and metadata path. Explicit entries retain priority, and an identical style/text pair retained by an importer is emitted only once. Negative measure-level horizontal offsets expand the left content margin and move the system content together; font-width-aware wrapping and positive-offset typography remain host work. Non-zero Pitch::microtone_cents values, including notes on tablature staffs, are rendered as explicit deterministic acorde-microtone text markers such as +25c. The glyph_coverage().microtone_marker capability reports this as svg-text-cents with exact signed cents preservation. This does not claim equivalence to any particular quarter-tone glyph font; hosts may augment the marker with a richer resource. Unpitched notes retain their display placement and receive an acorde-unpitched class plus a data-acorde-unpitched="true" hook. Their explicit NoteHead shape also receives a bounded acorde-percussion-notehead-* resource hook reported by glyph_coverage(); the renderer does not invent a percussion sound mapping. Tab positions outside the owning staff's line range return RenderError::InvalidTabPosition before SVG emission; invalid metric arithmetic returns RenderError::TabMetricsOverflow. The public tab_fret_metrics() contract and self-authored fixture pin the digit-width and gap assumptions used for deterministic multi-position spacing; installed-font metrics remain host work.

use acorde_core::Score;
use acorde_render_svg::{render_svg, SvgRenderOptions};

let svg = render_svg(&Score::default(), &SvgRenderOptions::default())?;

Unsupported clefs, accidentals, rows, layouts, and invalid options return RenderError rather than being silently dropped. See the browser contract.

API documentation · Repository

SVG output and annotation trust-boundary rules are documented in the security contract.