docs(design): beeldverwijzingen op een bullets+beeld-dia (#1801) #1802

Merged

brenno merged 2 commits from docs/1801-image-callouts-design into main

2026-08-27 12:14:02 +00:00

brenno commented

2026-08-27 12:08:37 +00:00

Owner

Legt het ontwerp voor #1801 vast: een bullet kan naar een plek in de afbeelding
ernaast wijzen, als genummerde speld, uitgelicht vlak of pijl. Alleen het
ontwerp — nog geen gedrag, nog geen Dart.

docs/design/** wordt bewust niet gebundeld, dus dit hoeft nergens
geregistreerd te worden.

Waarom dit ontwerp er zo uitziet

De drager is door meting gekozen, niet door voorkeur. git diff over het
hele parse/serialiseer/front-matter-pad tussen v0.4.9 en nu is leeg, dus
metingen tegen de ontwikkellijn zijn metingen van de uitgebrachte lezer.

Een nieuw ocideck_*-commentaar in een diablok overleeft geen enkele
opslag: het wordt weggegooid (drie posities) of het verandert in een
presentatienotitie (onderaan een bullets-dia). Die route valt dus af.
Een zichtbare (A) in de bullet komt overal heel terug en rendert als platte
tekst — ook na een echte link, na een losse ], en binnen nadruk.
Een genest blok onder een onbekende front-matter-sleutel komt byte-voor-byte
terug, in zes gevallen getoetst: ongewijzigd opslaan, een andere dia
bewerkt, een eigen sleutel gewijzigd, blok eerst, blok laatst, en met
handgeschreven #-commentaar eromheen. Dat is regel 1 van het formaatcontract
die in de praktijk houdt.
Coördinaten staan op drie decimalen. privacy_location_rules.dart ziet een
getallenpaar pas als coördinaat bij vier of meer decimalen, en
isPlausibleCoordinate(0.62, 0.28) is waar — vier decimalen zou van élke
callout een privacybevinding maken. Drie is bovendien precies wat
_formatFocal al doet.
De CSS-kant besteedt de cover-bijsnijding uit aan aspect-ratio in plaats van
hem na te rekenen. Gerenderd door een echte Marp CLI: een speld in slotruimte
mist zijn doel met ~6% van de diabreedte, dezelfde speld in de beelddoos ligt
precies goed. Het enige dat OciDeck hoeft weg te schrijven is de natuurlijke
beeldverhouding.

De botsing, hardop

Uitwisselbaarheid tegen een rijke functie. De pijl bestaat alleen binnen
OciDeck. Uitwisselbaarheid wint, en de manier waaróp is de splitsing in het
ontwerp: de pijl is een tekening over gegevens die zelf volledig meeneembaar
zijn. Wie weggaat houdt de betekenis — welke regel wijst waarheen, en wat daar
is, in gewone taal — en verliest alleen de tekening.

Waaronder ik van gedachten verander: zodra de pijl eigen meetkunde in het
bestand nodig heeft (knikpunten, handmatige routering, een met de hand geplaatste
staart), zijn de opgeslagen gegevens geen draagbare betekenis meer maar
OciDeck-instructies. Dan gaat de functie niet door. Daarom staan knikpunten en
handmatige routering expliciet buiten de reikwijdte, en gebruikt het ontwerp een
berekende rail in plaats van een geplaatste staart.

Ook eerlijk opgeschreven wat er sneuvelt: zonder --theme-set toont een vreemde
Marp-render geen overlay — en die aanroep is nu al de tweekolomsopmaak kwijt,
los van deze functie.

Poorten

make check-static groen
make check-secrets groen (gitleaks + trufflehog, werkboom én historie)
make sast groen (semgrep, 0 bevindingen)
dart run tool/check_translated_mermaid.dart en make translate-docs-check groen
make check gedraaid; wijziging raakt geen Dart

Bewaker-blik gedaan vóór de poort, zoals verplicht bij een wijziging die het
bestandsformaat raakt. De uitkomst staat in §11 van het document zelf, zodat de
afweging vindbaar blijft voor wie er niet bij was.

Legt het ontwerp voor #1801 vast: een bullet kan naar een plek in de afbeelding ernaast wijzen, als genummerde speld, uitgelicht vlak of pijl. Alleen het ontwerp — nog geen gedrag, nog geen Dart. `docs/design/**` wordt bewust niet gebundeld, dus dit hoeft nergens geregistreerd te worden. ## Waarom dit ontwerp er zo uitziet De drager is door **meting** gekozen, niet door voorkeur. `git diff` over het hele parse/serialiseer/front-matter-pad tussen `v0.4.9` en nu is leeg, dus metingen tegen de ontwikkellijn zijn metingen van de uitgebrachte lezer. - Een nieuw `ocideck_*`-commentaar in een diablok overleeft **geen enkele** opslag: het wordt weggegooid (drie posities) of het verandert in een presentatienotitie (onderaan een bullets-dia). Die route valt dus af. - Een zichtbare `(A)` in de bullet komt overal heel terug en rendert als platte tekst — ook na een echte link, na een losse `]`, en binnen nadruk. - Een genest blok onder een onbekende front-matter-sleutel komt byte-voor-byte terug, in zes gevallen getoetst: ongewijzigd opslaan, een **andere dia** bewerkt, een eigen sleutel gewijzigd, blok eerst, blok laatst, en met handgeschreven `#`-commentaar eromheen. Dat is regel 1 van het formaatcontract die in de praktijk houdt. - Coördinaten staan op **drie decimalen**. `privacy_location_rules.dart` ziet een getallenpaar pas als coördinaat bij vier of meer decimalen, en `isPlausibleCoordinate(0.62, 0.28)` is waar — vier decimalen zou van élke callout een privacybevinding maken. Drie is bovendien precies wat `_formatFocal` al doet. - De CSS-kant besteedt de cover-bijsnijding uit aan `aspect-ratio` in plaats van hem na te rekenen. Gerenderd door een echte Marp CLI: een speld in slotruimte mist zijn doel met ~6% van de diabreedte, dezelfde speld in de beelddoos ligt precies goed. Het enige dat OciDeck hoeft weg te schrijven is de natuurlijke beeldverhouding. ## De botsing, hardop **Uitwisselbaarheid tegen een rijke functie.** De pijl bestaat alleen binnen OciDeck. Uitwisselbaarheid wint, en de manier waaróp is de splitsing in het ontwerp: de pijl is een *tekening* over gegevens die zelf volledig meeneembaar zijn. Wie weggaat houdt de betekenis — welke regel wijst waarheen, en wat daar is, in gewone taal — en verliest alleen de tekening. **Waaronder ik van gedachten verander:** zodra de pijl eigen meetkunde in het bestand nodig heeft (knikpunten, handmatige routering, een met de hand geplaatste staart), zijn de opgeslagen gegevens geen draagbare betekenis meer maar OciDeck-instructies. Dan gaat de functie niet door. Daarom staan knikpunten en handmatige routering expliciet buiten de reikwijdte, en gebruikt het ontwerp een berekende rail in plaats van een geplaatste staart. Ook eerlijk opgeschreven wat er sneuvelt: zonder `--theme-set` toont een vreemde Marp-render geen overlay — en die aanroep is nu al de tweekolomsopmaak kwijt, los van deze functie. ## Poorten - `make check-static` groen - `make check-secrets` groen (gitleaks + trufflehog, werkboom én historie) - `make sast` groen (semgrep, 0 bevindingen) - `dart run tool/check_translated_mermaid.dart` en `make translate-docs-check` groen - `make check` gedraaid; wijziging raakt geen Dart Bewaker-blik gedaan vóór de poort, zoals verplicht bij een wijziging die het bestandsformaat raakt. De uitkomst staat in §11 van het document zelf, zodat de afweging vindbaar blijft voor wie er niet bij was.

brenno added 2 commits

2026-08-27 12:08:37 +00:00

docs(design): ontwerp voor beeldverwijzingen op een bullets+beeld-dia (#1801 ) 6323fe343c

Legt het bevroren formaatcontract vast voor callouts: een zichtbare
`(A)`-verwijzing in de bullet als koppelsleutel en terugval, de canonieke
gegevens in een front-matter-blok gesleuteld op dia-anker, en de overlay-opmaak
als afgeleide die bij elke opslag opnieuw wordt geschreven.

De drager is door meting gekozen, niet door voorkeur. Een nieuw
`ocideck_*`-commentaar in een diablok overleeft geen enkele opslag — het wordt
weggegooid of het verandert in een presentatienotitie. Een onbekende
front-matter-sleutel met genest blok komt wél byte-voor-byte terug; dat is regel
1 van het formaatcontract, en het is nagemeten in zes gevallen, waaronder een
bewerking op een ándere dia.

Ook vastgelegd: de coördinaten staan in beeldruimte op drie decimalen (vier of
meer zou elke callout een privacybevinding maken), en de CSS-kant besteedt de
cover-bijsnijding uit aan `aspect-ratio` in plaats van hem na te rekenen.

Ontwerp, nog geen gedrag. Uitvoering begint bij de collab-pariteit.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs(design): leg de waardenafweging achter het callout-formaat vast (#1801 )

scans / scans (pull_request) Successful in 2m5s

Details

static-gate / static-gate (pull_request) Successful in 4m56s

Details

8708504064

De bewaker-toets hoort in het ontwerp zelf te staan, niet alleen in het hoofd
van wie het schreef: uitwisselbaarheid botst hier met een rijke functie, en de
pijl bestaat alleen binnen OciDeck.

Vastgelegd waaróm dat mag — de pijl is een tekening over gegevens die zelf
volledig meeneembaar zijn — en waaronder het besluit omslaat: zodra de pijl
eigen meetkunde in het bestand nodig heeft, is het geen draagbare betekenis meer
maar een OciDeck-instructie, en gaat de functie niet door. Dat is meteen de
reden dat knikpunten en handmatige routering buiten de reikwijdte staan.

Ook eerlijk opgeschreven wat er wél sneuvelt zonder `--theme-set`, inclusief het
feit dat een vreemde Marp-render de tweekolomsopmaak nu al kwijt is.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

brenno referenced this pull request

2026-08-27 12:09:03 +00:00

[Feature] Map with arrows #1801

brenno merged commit ce370e11de into main

2026-08-27 12:14:02 +00:00

brenno referenced this pull request from a commit

2026-08-27 12:14:03 +00:00

Merge pull request 'docs(design): beeldverwijzingen op een bullets+beeld-dia (#1801)' (#1802) from docs/1801-image-callouts-design into main

brenno referenced this pull request

2026-08-27 12:14:35 +00:00

[Feature] Map with arrows #1801