[Image references 1/6] Core model, format v2 and lossless collaboration #1824

New issue

Closed

opened 2026-08-28 09:42:48 +00:00 by brenno · 0 comments

brenno commented

2026-08-28 09:42:48 +00:00

Owner

Parent: #1801
Contract: docs/design/IMAGE_CALLOUTS.md, frozen revision 4 (§2, §3, §8, §9 and §12)

Outcome

Introduce the dormant data foundation for image references without exposing an unfinished editor or renderer. After this slice, a reference can be represented, read, saved and synchronised without loss, but users cannot create one through the interface yet.

Scope

Add the typed slide model for point and region targets, reference groups, presentation mode and reveal mode.
Read and write the canonical ocideck_callouts front-matter block and the visible trailing (A) reference according to §2.
Implement the nested lossless merge contract: retain raw lines and rewrite only entries that were deliberately edited.
Preserve unknown children, future geometry, malformed known entries, comments, blank lines, original order, quoting and duplicate keys.
Reject invalid geometry from rendering without clamping or deleting it; report it through the checker.
Implement the exact binding rules for ordinary trailing (A) prose, duplicate bullets, duplicate entries and orphans.
Carry the new slide state through copy, reorder, delete, duplicate, split runs, display windows, undo and the full collaboration chain.
Write format version 2 only when the first image reference is saved.

Acceptance evidence

A checked-in fixture and target resolve the newest released tag, run its parser and writer, and prove that the future block survives unchanged.
A new-reader edit changes one known entry while every unknown or malformed raw line remains byte-for-byte intact.
The merge is idempotent.
The full §2.6 binding table and every §8 limit are tested at the limit and limit-plus-one.
YAML scalar tests cover quotes, #, :, <, &, </script>, backslashes, TeX metacharacters and a newline.
Two-client collaboration, reconnect and incompatible-client behaviour are covered.
FILE_FORMAT, SOURCE_MAP and CHANGELOG are updated in the same slice.

Boundaries

No public editor control or rendered marker in this slice.
Do not persist derived overlay markup, coordinate CSS or Marp fragment markers.
Rich-text bullets remain the blocked boundary specified in §6.
Tests, documentation and collaboration parity are part of this issue, not follow-up cleanup.

Use small coherent commits inside the pull request: model, parser, lossless writer, checker, collaboration, tests and documentation should remain individually reviewable where practical.

Parent: #1801 Contract: `docs/design/IMAGE_CALLOUTS.md`, frozen revision 4 (§2, §3, §8, §9 and §12) ## Outcome Introduce the dormant data foundation for image references without exposing an unfinished editor or renderer. After this slice, a reference can be represented, read, saved and synchronised without loss, but users cannot create one through the interface yet. ## Scope - Add the typed slide model for point and region targets, reference groups, presentation mode and reveal mode. - Read and write the canonical `ocideck_callouts` front-matter block and the visible trailing `(A)` reference according to §2. - Implement the nested lossless merge contract: retain raw lines and rewrite only entries that were deliberately edited. - Preserve unknown children, future geometry, malformed known entries, comments, blank lines, original order, quoting and duplicate keys. - Reject invalid geometry from rendering without clamping or deleting it; report it through the checker. - Implement the exact binding rules for ordinary trailing `(A)` prose, duplicate bullets, duplicate entries and orphans. - Carry the new slide state through copy, reorder, delete, duplicate, split runs, display windows, undo and the full collaboration chain. - Write format version 2 only when the first image reference is saved. ## Acceptance evidence - A checked-in fixture and target resolve the newest released tag, run its parser and writer, and prove that the future block survives unchanged. - A new-reader edit changes one known entry while every unknown or malformed raw line remains byte-for-byte intact. - The merge is idempotent. - The full §2.6 binding table and every §8 limit are tested at the limit and limit-plus-one. - YAML scalar tests cover quotes, `#`, `:`, `<`, `&`, `</script>`, backslashes, TeX metacharacters and a newline. - Two-client collaboration, reconnect and incompatible-client behaviour are covered. - `FILE_FORMAT`, `SOURCE_MAP` and `CHANGELOG` are updated in the same slice. ## Boundaries - No public editor control or rendered marker in this slice. - Do not persist derived overlay markup, coordinate CSS or Marp fragment markers. - Rich-text bullets remain the blocked boundary specified in §6. - Tests, documentation and collaboration parity are part of this issue, not follow-up cleanup. Use small coherent commits inside the pull request: model, parser, lossless writer, checker, collaboration, tests and documentation should remain individually reviewable where practical.

brenno added the

enhancement

accepted

labels

2026-08-28 09:42:48 +00:00

brenno referenced this issue

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

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

brenno referenced this issue

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

[Feature] Map with arrows #1801

brenno added the