feat(items): one item record, so an annotation survives the zoom

The operator reported that zoomed-in images lose their annotations. That was
never a rendering bug. Three functions independently walked a booth and derived
overlapping subsets of the same facts -- build_gallery (kind, caption, blur,
doc), booth_view_file (kind, doc, image ring) and list_booths (kind counts,
cover) -- and the zoom route's subset was the smallest. Caption resolution lived
inside build_gallery's loop and nowhere else, so there was no code path by which
a caption could reach the zoom template. It was never sent.

booth/items.py is now the one truth: booth_items() returns the full record --
rel, kind, section, caption, blur, doc kind, size -- and the gallery, the zoom
view, the doc view and the index all read it. Patching view.html would have
fixed the symptom for images and left the next surface starting from the same
missing truth.

Two things fall out of the consolidation:
  - the index and the booth page now agree on what an item IS. list_booths
    counted every non-dot file, so an A/B pair with two caption sidecars read
    as 4 items on the index and showed 2 tiles when you opened it.
  - "section" (the item's subfolder) is computed and carried but nothing renders
    it yet. That is deliberate: it is U7's whole input, and shipping the field
    now makes U7 a template change rather than a resolver change.

Doc bodies are NOT rendered by the resolver -- the index touches every booth on
every page load, and rendering every markdown file in every booth would be the
price of that convenience. render_doc_body is a separate step for the one
surface that inlines them; an invariant test monkeypatches it to raise and
loads the index.

Verified beyond the suite, because this repo has shipped two dead controls that
every test passed: the caption was measured in a real browser at 1280x41 px,
visible, with elementFromPoint at its centre returning the caption itself.
layout-probe reports all controls hittable across index, gallery, zoom and doc.

192 tests pass (173 before, 19 new).

Contract: docs/contracts/u1_item_record.contract.md
This commit is contained in:
vh
2026-09-21 22:04:07 -07:00
parent 726822b2b9
commit ce598b3cf6
6 changed files with 773 additions and 172 deletions
+11
View File
@@ -14,6 +14,11 @@
{% if prev_url %}<a class="vnav vprev" href="?f={{ prev_url }}" title="previous (←)" aria-label="previous image">‹</a>{% endif %}
{% if next_url %}<a class="vnav vnext" href="?f={{ next_url }}" title="next (→)" aria-label="next image">›</a>{% endif %}
<div class="vstage fit" id="vstage"><img id="vimg" src="{{ file_url }}" alt="{{ file }}"></div>
{# THE ANNOTATION, at full size. It was never rendered here before U1 — not
because the template dropped it, but because the route never resolved it.
A caption is most useful at the size where you are actually judging the
thing, so it belongs here at least as much as in the grid. #}
{% if caption %}<div class="vcap">{{ caption }}</div>{% endif %}
</div>
<style>
.vnav{position:fixed;top:50%;transform:translateY(-50%);z-index:40;display:flex;
@@ -23,6 +28,12 @@
-webkit-backdrop-filter:blur(4px);backdrop-filter:blur(4px);transition:background .15s,border-color .15s}
.vnav:hover{background:rgba(28,33,46,.92);border-color:var(--aus-bright-cyan,#42dcd1)}
.vprev{left:0}.vnext{right:0}
/* Bottom bar rather than the top chrome: a caption can run to CAPTION_MAX
(800 chars), which would shove the filename and the Fit/1:1 toggle around. */
.vcap{flex:0 0 auto;max-height:22vh;overflow-y:auto;padding:.6rem clamp(12px,3vw,20px);
font-size:.85rem;line-height:1.5;color:var(--fg-1);background:var(--rk-surface,rgba(20,23,32,.92));
border-top:1px solid rgba(255,255,255,.10);white-space:pre-wrap}
@media print{.vcap{max-height:none;overflow:visible}}
@media print{.vnav{display:none}}
</style>
<script>