Step 1 of U2 Task 4: the handle layer as its own focusable svg, R-9 sizes, the chosen vertex, the old place, the refused place and the move-mode target.
223 lines
14 KiB
Markdown
223 lines
14 KiB
Markdown
# 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), with a visible focus ring. The layer's root sets
|
||
`pointer-events: none`; each handle's hit shape sets `pointer-events: all` 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 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 | none | 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).
|