From dfd806aa9f8aac1532ce73525717fd4a24fcbe3d Mon Sep 17 00:00:00 2001 From: Vuong Hoang Date: Wed, 23 Sep 2026 06:57:32 -0700 Subject: [PATCH] docs(booth.html): name the .rail cross-file contract at the selector that depends on it The SVOS retheme makes .rail load-bearing in two files owned by two different agents: this template's grid-cursor start, and base.html's --rail-h measuring script that publishes the rail's height for scroll-margin-top (the rail wraps, so no CSS number can know it). Neither breaks loudly if it is renamed. Ours starts the cursor one tile too high; theirs falls back to a fixed guess. design-dev's sheet carries the mirror of this note above the .rail rule, so the coupling is documented from both ends rather than from whichever side happened to notice. --- booth/templates/booth.html | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/booth/templates/booth.html b/booth/templates/booth.html index 9faef1e..58a5e65 100644 --- a/booth/templates/booth.html +++ b/booth/templates/booth.html @@ -411,6 +411,16 @@ The first tile whose bottom edge clears the sticky rail is the one the reader is looking at, so that is where the cursor picks up. */ function fromViewport() { + /* ⚠ `.rail` IS A CROSS-FILE CONTRACT, read by two scripts in two files + owned by two different agents: this one, and the --rail-h measuring + script in base.html that publishes the rail's height for + `scroll-margin-top` (the rail wraps, so no CSS number can know it). + RENAMING IT BREAKS BOTH, and neither breaks loudly — this one falls back + to treating the viewport top as the boundary and starts the cursor one + tile too high; that one falls back to a fixed guess. base.html carries + the mirror of this note above the `.rail` rule. Agreed with design-dev + 2026-09-23 during the SVOS retheme, which is the change that made the + selector load-bearing in two places instead of one. */ var t = tiles(), rail = document.querySelector('.rail'); var top = rail ? rail.getBoundingClientRect().bottom : 0; for (var i = 0; i < t.length; i++) {