[Image references 3/6] Numbered markers from authoring to export #1826

New issue

Closed

opened 2026-08-28 09:43:37 +00:00 by brenno · 0 comments

brenno commented

2026-08-28 09:43:37 +00:00

Owner

Parent: #1801
Depends on: #1824 and #1825
Contract: docs/design/IMAGE_CALLOUTS.md, frozen revision 4 (pin rows of §3.1, §5, §6, §8, §9 and §12)

Outcome

Deliver the first complete, usable version of image references: an author links a bullet to one or more places in its image and the audience sees matching numbered markers on every supported OciDeck surface.

Scope

Add an Image references section to the Bullets + image editor and a dedicated editing stage using the real crop and layout.
Allocate the next free reference while skipping letters already used as trailing prose.
Place, select, move, delete and restore point targets; support several targets for one reference.
Carry references when bullets are reordered and require an explicit recovery choice when a bullet or image is removed or replaced.
Provide complete keyboard and non-drag paths, focus order, Undo and named targets.
Render numbered markers in Flutter preview, presenter and audience; OciDeck HTML export; LaTeX/Beamer; and the raster path used by PDF, PPTX and ODP.
Keep plain Marp honest: visible (A) text and canonical front matter, but no persisted or stale mark.
Apply theme-derived styling with the mandatory two-tone edge.
Implement the accessibility contract: reference-level description, target ordinal, linked bullet semantics, hidden description in HTML and equivalent Flutter semantics.
Append descriptions to image alternative text where an export format exposes such a slot.

Acceptance evidence

End-to-end author journey: create, place, add another target, move, delete, undo, reorder, duplicate and reload.
Same-frame raster capture, including consecutive slides whose markers occupy opposite corners.
HTML bounding-box checks, a real TeX compile and raster comparison.
Keyboard-only and screen-reader journeys, including one reference with multiple targets.
Light, dark, busy and greyscale images at full-slide and slide-rail sizes.
Redaction removes the overlay; descriptions remain scannable content and three-decimal geometry produces no coordinate privacy finding.
All visible strings have the full localisation set.
USER_GUIDE, FILE_FORMAT, SOURCE_MAP, architecture documentation and CHANGELOG are updated with actual shipped behaviour.

Boundaries

This slice exposes only the user-facing numbered marker presentation.
Highlighted regions, stepwise reveal and arrows belong to #1801's later slices.
Do not expose developer terms such as callout, pin, region or arrow as untranslated interface concepts.
Tests, documentation, accessibility and translations are part of this issue, not later cleanup.

Build through small coherent commits even though the issue is a vertical slice: editor, Flutter render, export surfaces, accessibility, localisation/tests and documentation should remain reviewable.

Parent: #1801 Depends on: #1824 and #1825 Contract: `docs/design/IMAGE_CALLOUTS.md`, frozen revision 4 (pin rows of §3.1, §5, §6, §8, §9 and §12) ## Outcome Deliver the first complete, usable version of image references: an author links a bullet to one or more places in its image and the audience sees matching numbered markers on every supported OciDeck surface. ## Scope - Add an `Image references` section to the `Bullets + image` editor and a dedicated editing stage using the real crop and layout. - Allocate the next free reference while skipping letters already used as trailing prose. - Place, select, move, delete and restore point targets; support several targets for one reference. - Carry references when bullets are reordered and require an explicit recovery choice when a bullet or image is removed or replaced. - Provide complete keyboard and non-drag paths, focus order, Undo and named targets. - Render numbered markers in Flutter preview, presenter and audience; OciDeck HTML export; LaTeX/Beamer; and the raster path used by PDF, PPTX and ODP. - Keep plain Marp honest: visible `(A)` text and canonical front matter, but no persisted or stale mark. - Apply theme-derived styling with the mandatory two-tone edge. - Implement the accessibility contract: reference-level description, target ordinal, linked bullet semantics, hidden description in HTML and equivalent Flutter semantics. - Append descriptions to image alternative text where an export format exposes such a slot. ## Acceptance evidence - End-to-end author journey: create, place, add another target, move, delete, undo, reorder, duplicate and reload. - Same-frame raster capture, including consecutive slides whose markers occupy opposite corners. - HTML bounding-box checks, a real TeX compile and raster comparison. - Keyboard-only and screen-reader journeys, including one reference with multiple targets. - Light, dark, busy and greyscale images at full-slide and slide-rail sizes. - Redaction removes the overlay; descriptions remain scannable content and three-decimal geometry produces no coordinate privacy finding. - All visible strings have the full localisation set. - `USER_GUIDE`, `FILE_FORMAT`, `SOURCE_MAP`, architecture documentation and `CHANGELOG` are updated with actual shipped behaviour. ## Boundaries - This slice exposes only the user-facing **numbered marker** presentation. - Highlighted regions, stepwise reveal and arrows belong to #1801's later slices. - Do not expose developer terms such as `callout`, `pin`, `region` or `arrow` as untranslated interface concepts. - Tests, documentation, accessibility and translations are part of this issue, not later cleanup. Build through small coherent commits even though the issue is a vertical slice: editor, Flutter render, export surfaces, accessibility, localisation/tests and documentation should remain reviewable.

brenno added the

enhancement

accepted

labels

2026-08-28 09:43:37 +00:00

brenno referenced this issue

2026-08-28 09:44:31 +00:00

[Image references 5/6] Stepwise reveal #1828

brenno referenced this issue

2026-08-28 09:45:26 +00:00

[Feature] Map with arrows #1801

brenno added the