- guardDrawing commits a keyboard or size series the focus still holds (its blur) and ends only the mode: a pending series is never dropped. - A started move ended by a selection change is said (R-13). - handleSize: no module-level state; useHandleSizes reads the device once per handle layer. The layer reads ResizeObserver contentRect. - Dead kind check removed in SelectionPointCommands; long lines wrapped (code, doc). - e2e: the zoom check waits for the transform to change; the move-mode arrow clicks are under expectNoShift.
14 KiB
Annotation rendering contract
Status: source of truth since Step 5. Replaces ANATOMY-SVG-CONVENTION.md
(the legacy data-anno-* attributes authored inside the SVG files). Rewritten
at R3 (2026-10-14) to describe the code exactly, before the renderer moved to
Rust; nothing in the rendering changed with this rewrite.
The drawing of a sheet is a plain SVG asset with no annotation element. The
application draws the markers itself from the canonical document
(docs/development/ANATOMICAL_SHEET_MODEL.md). One layer renderer turns the
annotations of one view into a <g data-layer="annotations" data-view-id="…">
appended last to the view's <svg>, above the drawing. Since R3 the editor
canvas gets the whole view (sanitised drawing + layer) from the Rust core
(crates/core/src/anatomy); so do the PDF writer (R4) and the curation
pipeline's review drawings (R5). The TypeScript renderer
(packages/anatomy/src/render) it replaced was deleted at R5.7.
Elements emitted per annotation
The element follows the geometry type, not the annotation kind, except for a trigger.
| Annotation | Elements |
|---|---|
detail_trigger, any geometry |
one dashed shape: fill and stroke = the colour, fill-opacity 0.06, stroke-width 2, stroke-dasharray 8,4, pointer-events all, style cursor:pointer, class detail-zone |
point or zone with a circle |
a transparent hitbox (the geometry's r, fill transparent, stroke none, pointer-events visibleFill, style cursor:pointer; the R3 form kept for the seed review drawings has no stroke and pointer-events all) then a visible twin on top (radius max(2, r − 12), the colour, fill-opacity 0.65 on the main view / 0.5 on a detail view, stroke #000 1.5, pointer-events none; visiblePainted in the editor canvas, see below) |
point or zone with a polygon or a path |
one filled shape: fill and stroke = the colour, fill-opacity 0.3, stroke-width 2, pointer-events all, style cursor:pointer |
Annotations without geometry draw nothing. Annotations follow the document
order of the view, in the PDF view and the review drawings. The editor canvas
paints and hits them in three passes, each in document order (« the visible
wins », owner decision 2026-11-01, V1-2.2): every point hitbox, then every
filled shape (zones and triggers), then every visible twin, which captures on
what it paints (pointer-events visiblePainted). A tap on a point's visible
disc selects that point even where a zone or another point's hitbox lies
under it; a zone keeps every pixel no visible disc covers, the hitbox ring of
a point included; a hitbox ring keeps what neither covers. Until then each
annotation's elements followed one another, so a zone painted after a
vertebral junction took part of its disc. Visible consequence: a selected
point's hitbox, filled by the canvas stylesheet, sits under a neighbouring
zone, which tints the part it covers. Coordinates are printed as JavaScript prints numbers, never
rounded; a path's d is copied as written. Each element has one <title>
child, "name FR / name EN" (native tooltip), and the attributes below.
Owner decision 2026-10-15: until then an unnamed trigger carried the French
view name in both attributes and its title read "FR / FR"; the editor canvas
(Rust core) now follows the language of each attribute. The PDF engine's
TypeScript renderer keeps the old form until R4, where it is invisible: the
highlight drops every data-* attribute and a raster never shows a title.
Attributes (the application's read contract)
| Attribute | Value |
|---|---|
data-anno-id |
annotation id (stable, the report's annotationId) |
data-anno-kind |
point, zone or detail_trigger |
data-anno-lateral |
unpaired, bilateral, left or right |
data-anno-opens-view |
opens_view_id of a trigger |
data-anno-name-fr, data-anno-name-en |
the annotation's name in each language; a trigger without a name carries the opened view's name in each language (French in -fr, English in -en; an empty language takes the other one). Display only: never an identifier, never persisted |
data-anno-zone |
finding_zone_id, when present |
data-anno-region |
vertebral_region_code, when present |
data-state |
current on every element of an annotation of the active observation |
Click handling walks up to the nearest [data-anno-id] and hands the
annotation id to the core's click rule (zone.click, R2). Behaviour never
depends on a label, an element id or a class. The canvas sets and removes
data-state in place when the active observation changes (no rebuild), for
the annotation ids of every zone of that observation, whatever their view;
the custom tooltip reads the two name attributes (none on a trigger).
Deselection (D6b, R1): a press that begins outside any [data-anno-id]
element and ends as a click deselects the current annotation, in the editor
and in its read-only twin; the catalogue reader does not. The hit areas
themselves are unchanged. A drag, a pan, a zoom or a press with a second
finger never deselects.
Colours
annotations[].color gives the colour of one annotation; otherwise the colour
of its category (categories[].color); otherwise #888888 (no colour, or an
unknown category). Colours are document data, written by the curation
changeset, never by the renderer.
Views
A view renders on its frame (anatomy::frame::view_frame, V1-2.2 owner brief
2026-10-30): its view_box when set (the head view is the crop
60 100 500 380 of the main drawing), otherwise the asset's own viewBox read
as a browser reads it (four numbers, positive width and height) and written
back in JavaScript number printing (0,0,10,10 becomes 0 0 10 10). Without
a usable frame the canvas falls back to 0 0 100 100 and the PDF view carries
no viewBox. A detail view with its own svg_asset_id renders that asset,
otherwise the first asset up its parent chain. The root's width, height
and preserveAspectRatio are removed (the default xMidYMid meet shows the
whole frame, which a slice would crop where the box is not the frame's); its
other attributes are kept (after sanitising). The verdict and the preview
refuse an annotation not entirely inside this same frame
(verification.validation.out_of_frame), so a drawing whose viewBox moved
away from the annotations is refused, never drawn without its markers. Since
the owner brief of 2026-11-01 a frame is usable only within the range browsers
draw faithfully (edges within 2²⁰, spans from 1 unit, aspect at most
100, farthest edge at most 256 smaller spans; otherwise no usable frame), and
every annotation must show at least 4 CSS px on the smallest preview, the
editor at 320 × 568 (verification.validation.marker_too_small): a frame
blown up with its drawing scaled back keeps the drawing and shrinks every
marker, refused. A zone or a trigger drawn as a polygon or a path must also
fill a disc of 4 CSS px on that preview, under the nonzero rule the layer
fills with (it writes no fill-rule, and none reaches it), its stroke left out
(verification.validation.marker_interior_too_small, owner brief 2026-11-01):
an outline drawn forth and back, the same loop twice in opposite directions, or
a near-flat shape on a diagonal fills no point a tap can reach, refused. The
measure is conservative (a disc crossing no edge, curves cut into chords whose
deviation is taken off) and refuses in doubt; a point painted over a zone takes
the taps on its disc, which the measure does not count (known limitation,
RUST.md §12.14).
The editor canvas is inlined in the page, where #id resolves against the
whole document. Since V1-2.2 (owner decision 2026-10-29) the core writes
fv.<view id>. in front of every id of the drawing and of every local
reference to it (href, xlink:href, url(#…)), so each view resolves its
gradients, clip paths and <use> targets in its own drawing only, never in
another view's or in the page, and the composer refuses a canvas that would
keep a reference outside its scope. A drawing whose reference names an id it
does not define is refused by the reader (dangling_reference); a url( spelt
any other way than url(#id) with optional quotes and spaces is removed by the
reader, so the cleaning refuses the file as active content and the verdict as a
removal. A url( glued to a longer name (xurl(#a)) is no reference: the reader
removes the attribute holding it, whatever the attribute (2026-10-30), so the
canvas and the PDF view accept the same references as the reader; the canvas
still refuses a composed view over 4 MiB (too_large), its scope prefix
lengthening every id and reference. The annotation
layer carries no id. The PDF view keeps the drawing's ids: it is rasterised
as a document of its own. The R3 canvas goldens stay frozen; the tests apply
this declared change to them (withIdsScopedPerView,
with_ids_scoped_per_view).
Styling and states
The application stylesheet: .svg-canvas [data-state='current'] fills the
selected markers with the accent colour at 0.85, every [data-anno-id] shows
a pointer cursor and brightens on hover.
Editor overlay (V1-2.6)
The draft editor (admin, tab Annotations and the crop rectangle of tab Views)
puts a second <svg> over the core's composed view, inside the same transformed
container, with the composed root's own viewBox and preserveAspectRatio (the
attribute text, read with Number, never viewBox.baseVal). It draws no
annotation: the markers stay the core's (view.canvas) and the drawing is never
modified. The overlay holds numbers only, drawn from the editor's state: the
selection outline (dashed), the vertex circles, the tracing in progress, the
pending or dragged outline, the hollow cross of a corrected position and the
crop rectangle. It is aria-hidden and never takes the pointer. It sets
pointer-events: none on its own shapes; the pointer is read on the canvas
box and mapped to drawing units through the overlay's
getScreenCTM().inverse(). No overlay shape carries data-anno-id, so click
targeting still reads the core's markers only.
Handles live in a third <svg> of their own (the handle layer), above the
overlay in the same transformed container, with the same viewBox and
preserveAspectRatio. It is not aria-hidden: each handle is a focusable
role="button" (tabindex="0") named after what it moves (« Point {nom} » for
a point, « Accès {nom} » for a link circle), with a visible focus ring. The
layer's root sets pointer-events: none; each handle's hit shape turns it
back on (pointer-events: auto, painted shapes only) with a transparent fill
and carries data-handle (the JSON of its handle reference), which the press
machine reads through elementsFromPoint. Handle sizes are constant in CSS px
under zoom: the layer divides them by the drawing's px per unit (the box size
over the frame, times the zoom). The device size is read once per handle layer
from (any-pointer: coarse):
| Device | Vertex | « + » | « − » bubble | Hit radius |
|---|---|---|---|---|
| Coarse (finger) | 18 px | 24 px | 44 × 36 px | 22 px |
| Fine (mouse, pen) | 12 px | 16 px | board 05 size | 10 px |
The point handle covers the selected point's own circle (at least the hit radius), so the whole marker can be held. A chosen vertex is drawn bigger, filled and ringed, never by colour alone.
Marks of a gesture in progress, drawn by the overlay:
- the old place: grey dashes of the stored shape while a drag, a move mode, a size change or a keyboard series shows a preview;
- the preview itself: the selection outline at its new place or size;
- the refused place: red dashes of the shape the core refused, while the refusal message is shown (the shape stays where it was);
- the move-mode target: the shape the mode moves (the selection, or later the chosen vertex) keeps its handles; a drag anywhere on the drawing moves it.
The overlay only proposes geometry. Whether a position, a radius or a polygon is acceptable (frame, minimum visible size, interior) is the core's verdict on the candidate document; the page keeps no copy of those rules.
PDF highlight
The engine composes the observation's zones of one view: the markers of the
other annotations are dropped (not hidden), every data-* attribute is
removed, the kept elements get fill #b85a3f at 0.85 and, on the main view,
the osteo-halo filter (two Gaussian blurs merged with the source), in a
<defs> of the engine placed after the drawing's group, before the layer. The PDF
view keeps the drawing's ids, so osteo-halo is reserved (V1-2.2, owner brief
2026-10-30): the reader refuses a drawing holding it in any letter case
(reserved_id) and both composers refuse such a tree, so the halo the markers
name is always the engine's.
The composition root is the engine's (V1-2.2, owner brief 2026-10-30, RUST.md
§12.12): xmlns, xmlns:xlink and the frame only. The drawing's root becomes
a <g> holding its other attributes and its children; the layer (and the
halo's <defs>) are that group's siblings, so no property the drawing sets,
inherited (stroke-*, fill*, visibility…) or acting on a whole group
(opacity, display), reaches a marker: a root opacity="0" or
display="none" hides the drawing alone. A root visibility other than
visible stays refused by the reader (root_visibility) and by both
composers. The R3 trees stay frozen; the tests apply this declared change
(withIsolatedLayer, withDeclaredHitboxes, with_isolated_layer).
Checking the look
pnpm import:equine writes draft/review/app-main.svg and app-head.svg
(the curation pipeline's rendering, byte goldens until R5). Rasterise them with
ImageMagick next to the legacy files (strip the <title> elements first,
ImageMagick's own SVG renderer drops shapes that carry one) to compare markers
and framing. The editor canvas itself is compared in Chromium with
scripts/visual-canvas.mjs (capture before and after, pixel comparison).