From 8dcb17616080b7e1fd0c95fceb64741bd958f3d1 Mon Sep 17 00:00:00 2001 From: scottkalw Date: Mon, 16 Nov 2026 17:28:14 -0600 Subject: [PATCH 1/2] The recorder puts a box's label outside it and off the page's own writing A box's label used to sit just above the box's top-left edge. On the station screen the boxed thing sits under its card's title, so the label covered the title's first words (class 2.1, 2026-11-15). The label now tries spots in turn: above the box at its left end, then its right; below, the same; beside its right edge, then its left. A spot off the frame, under the sticky header, on the caption bar, in the narrator's corner, on the box, or over any line of the page's text is passed over; the text is found from the elements under a 5 by 3 grid of points on the spot and the rectangles of their own text nodes. A label with no clear spot refuses the take, naming the step. marks.json gains label_box on a pointed say; the header band is one shared function. Co-Authored-By: Claude Opus 5.5 Signed-off-by: scottkalw --- scripts/record-scene.py | 121 +++++++++++-- scripts/scenes/README.md | 11 +- ...utside_it_and_off_the_pages_own_writing.py | 161 ++++++++++++++++++ 3 files changed, 272 insertions(+), 21 deletions(-) create mode 100644 tests/test_a_boxs_label_sits_outside_it_and_off_the_pages_own_writing.py diff --git a/scripts/record-scene.py b/scripts/record-scene.py index eee37791..bae78339 100644 --- a/scripts/record-scene.py +++ b/scripts/record-scene.py @@ -678,16 +678,82 @@ def overlay_script(badge: str, captions: bool = True) -> str: {{ duration: {int(RIPPLE_SECONDS * 1000)}, easing: 'ease-out' }}).onfinish = () => ring.remove(); }}; // The box round what a line is about, following it if the page moves it, until cleared. + // + // Its label goes where it covers nothing of the page's: tried in turn above + // the box (at its left end, then its right), below it (the same), then + // beside its right edge and its left. A spot is taken only if it is wholly + // on the frame, below the page's sticky header, above the caption bar, out + // of the narrator's corner, off the box, and clear of every line of the + // page's own writing (a card's title above the box is the one it used to + // cover). The writing is looked for cheaply: the elements under a 5 by 3 + // grid of points on the spot, and the rectangles of their own text. With no + // clear spot the label is drawn inside the box's top left and the call says + // why, which refuses the take. let callout = null; + const headerBand = {HEADER_BAND_JS.strip()}; + const overlaps = (a, b) => a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h; + const writingUnder = (spot) => {{ + const seen = new Set(); + for (let i = 0; i < 5; i++) for (let j = 0; j < 3; j++) {{ + const x = spot.x + 1 + (spot.w - 2) * i / 4, y = spot.y + 1 + (spot.h - 2) * j / 2; + for (const node of document.elementsFromPoint(x, y)) {{ + if (seen.has(node) || (node.id && node.id.startsWith('fs-scene'))) continue; + seen.add(node); + for (const text of node.childNodes) {{ + if (text.nodeType !== Node.TEXT_NODE || !text.textContent.trim()) continue; + const range = document.createRange(); + range.selectNodeContents(text); + for (const r of range.getClientRects()) {{ + const line = {{ x: r.left, y: r.top, w: r.width, h: r.height }}; + if (overlaps(spot, line)) return text.textContent.trim().slice(0, 40); + }} + }} + }} + }} + return null; + }}; + const labelSpot = (el, r, tab, pad) => {{ + const w = tab.offsetWidth, h = tab.offsetHeight, gap = 4; + const box = {{ x: r.left - pad, y: r.top - pad, w: r.width + 2 * pad, h: r.height + 2 * pad }}; + const band = headerBand(el); + const cap = document.getElementById('fs-scene-cap'); + const capTop = cap && cap.offsetHeight ? cap.getBoundingClientRect().top : innerHeight; + const floor = Math.min(innerHeight - {CAPTION_HEIGHT}, capTop); + const corner = {{ x: innerWidth - {AVATAR_WIDTH}, y: innerHeight - {AVATAR_HEIGHT}, + w: {AVATAR_WIDTH}, h: {AVATAR_HEIGHT} }}; + const atLeft = Math.max(0, box.x), atRight = Math.min(innerWidth, box.x + box.w) - w; + const above = box.y - gap - h, below = box.y + box.h + gap, top = Math.max(box.y, band); + const tries = [ + ['above', atLeft, above], ['above, right', atRight, above], + ['below', atLeft, below], ['below, right', atRight, below], + ['right', box.x + box.w + gap, top], ['left', box.x - gap - w, top], + ]; + const why = []; + for (const [side, x, y] of tries) {{ + const spot = {{ x, y, w, h }}; + const fault = x < 0 || y < 0 || x + w > innerWidth || y + h > innerHeight ? 'off the frame' + : y < band ? 'under the header' + : y + h > floor ? 'on the caption bar' + : overlaps(spot, corner) ? "in the narrator's corner" + : overlaps(spot, box) ? 'on the box' + : null; + const words = fault ? null : writingUnder(spot); + if (!fault && !words) return {{ side, dx: x - r.left, dy: y - r.top }}; + why.push(`${{side}}: ${{fault || `over "${{words}}"`}}`); + }} + return {{ side: null, dx: Math.max(0, box.x) - r.left + 6, dy: Math.max(0, box.y) - r.top + 6, + why: why.join('; ') }}; + }}; window.__sceneCallout = (el, label, style) => {{ window.__sceneCalloutClear(); const box = document.createElement('div'); box.id = 'fs-scene-callout'; if (style === 'spotlight') box.classList.add('fs-spot'); const tab = label ? document.createElement('div') : null; - if (tab) {{ tab.id = 'fs-scene-callout-label'; tab.textContent = label; }} + if (tab) {{ tab.id = 'fs-scene-callout-label'; tab.textContent = label; tab.style.left = '-9999px'; }} document.documentElement.append(box, ...(tab ? [tab] : [])); const pad = {CALLOUT_PAD}; + const spot = tab && el.isConnected ? labelSpot(el, el.getBoundingClientRect(), tab, pad) : null; const place = () => {{ if (callout === null || callout.box !== box) return; if (el.isConnected) {{ @@ -696,16 +762,9 @@ def overlay_script(badge: str, captions: bool = True) -> str: box.style.top = (r.top - pad) + 'px'; box.style.width = (r.width + 2 * pad) + 'px'; box.style.height = (r.height + 2 * pad) + 'px'; - if (tab) {{ - // On the box's top left, outside it; below the box when the box is at - // the top; inside its top left when it fills the frame both ways. - const high = tab.offsetHeight; - const aboveAt = r.top - pad - high - 2; - const belowAt = r.bottom + pad + 2; - const floor = innerHeight - {CAPTION_HEIGHT}; - tab.style.left = Math.max(0, r.left - pad) + 'px'; - tab.style.top = (aboveAt >= 0 ? aboveAt - : belowAt + high <= floor ? belowAt : Math.max(0, r.top - pad) + 6) + 'px'; + if (spot) {{ + tab.style.left = (r.left + spot.dx) + 'px'; + tab.style.top = (r.top + spot.dy) + 'px'; }} }} callout.frame = requestAnimationFrame(place); @@ -713,7 +772,13 @@ def overlay_script(badge: str, captions: bool = True) -> str: callout = {{ box, tab, frame: 0 }}; place(); const drawn = box.getBoundingClientRect(); - return {{ x: drawn.left, y: drawn.top, w: drawn.width, h: drawn.height }}; + const answer = {{ x: drawn.left, y: drawn.top, w: drawn.width, h: drawn.height }}; + if (tab) {{ + const t = tab.getBoundingClientRect(); + answer.label = {{ x: t.left, y: t.top, w: t.width, h: t.height, side: spot ? spot.side : null, + why: spot && spot.why ? spot.why : null }}; + }} + return answer; }}; window.__sceneCalloutClear = () => {{ if (!callout) return; @@ -1029,8 +1094,16 @@ def point_out(self, line: str, at: str, label: str, style: str) -> dict: right = min(width, round(drawn["x"] + drawn["w"])) bottom = min(height, round(drawn["y"] + drawn["h"])) box = {"x": left, "y": top, "w": max(0, right - left), "h": max(0, bottom - top)} - print(f" box {box}" + (f" {label!r}" if label else ""), flush=True) - return {"box": box, "label": label, "selector": at, "style": style} + pointer = {"box": box, "label": label, "selector": at, "style": style} + if label: + tab = drawn["label"] + if tab["side"] is None: + raise SystemExit(f"step {self.step_number}: the label {label!r} on the box round `at = {at!r}` has" + f" no clear spot outside the box ({tab['why']}); the take is refused rather than" + " filmed with the label over the page's own writing") + pointer["label_box"] = {key: round(tab[key]) for key in ("x", "y", "w", "h")} + print(f" box {box}" + (f" {label!r} {pointer['label_box']}" if label else ""), flush=True) + return pointer def hold(self, seconds: float) -> None: self.note(f"hold {seconds}s", "hold") @@ -1283,8 +1356,9 @@ def render_slide(browser, card: str, path: Path, width: int, height: int) -> Non #: recorder's own layer); when the element's top is inside it, the element #: is scrolled to sit `headroom` below the band. `scroll-margin-top` does the #: scrolling so that a thing inside a scrolling panel is moved too. -CLEAR_OF_HEADER_SCRIPT = """ -(node, headroom) => { +#: The band itself: how far down the window the stuck things reach over `node`'s width. +HEADER_BAND_JS = """ +(node) => { const box = node.getBoundingClientRect(); const stuck = []; for (const el of document.body.querySelectorAll('*')) { @@ -1304,6 +1378,15 @@ def render_slide(browser, card: str, path: Path, width: int, height: int) -> Non if (r.top <= band + 2 && r.bottom > band) { band = r.bottom; grew = true; } } } + return band; +} +""" + +#: Bring the element out from under the band. +CLEAR_OF_HEADER_SCRIPT = """ +(node, headroom) => { + const box = node.getBoundingClientRect(); + const band = (""" + HEADER_BAND_JS.strip() + """)(node); if (!band || box.top >= band + headroom) return band; const was = node.style.scrollMarginTop; node.style.scrollMarginTop = (band + headroom) + 'px'; @@ -1599,7 +1682,8 @@ def readme(scene: dict, facts: dict) -> str: "- `marks.json` — the seconds every step landed at; the frame's size and the GIF's; on every" " click, `x` and `y`, the pixel of the mp4's frame the click landed on, and on every click, fill" " and choose `cursor_from` and `ripple_at`; on a line that points at something, `box`" - " (`x`, `y`, `w`, `h` in the mp4's pixels), `label`, `selector` and `style`", + " (`x`, `y`, `w`, `h` in the mp4's pixels), `label`, `selector` and `style`, and with a label" + " `label_box`, where the label sat", "", ] return "\n".join(lines) @@ -1674,7 +1758,8 @@ def marks_document(scene: dict, made: dict, gif: Path, gif_seconds_taken: float) `ripple_at` (the second its ripple started, as the press was sent), and a `fill` or `choose` also `x`, `y` (where it pointed) and a `fill` `typed_seconds`; a `say` with `at` carries `box` (`{x, y, w, h}`, integers, - in frame pixels, clipped to the frame), `label`, `selector` and `style`. + in frame pixels, clipped to the frame), `label`, `selector` and `style`, + and, when it has a label, `label_box` (`{x, y, w, h}`), where the label sat. """ return { "frame": {"width": int(scene["width"]), "height": int(scene["height"])}, diff --git a/scripts/scenes/README.md b/scripts/scenes/README.md index 3aad4ab4..54b48455 100644 --- a/scripts/scenes/README.md +++ b/scripts/scenes/README.md @@ -33,9 +33,14 @@ cursor presses the list and the value changes. A `say` with `at` (a selector, as `click` takes) draws a box round that thing as the caption appears, for the line's hold, and through any `mark` straight after it, so those stills show the box; `label` puts a few words on a tab -at the box's top left (below it when the box is at the top of the frame, -inside it when the box fills the frame); `style = "spotlight"` dims the rest -of the frame instead. A thing off the frame, or under the page's sticky +just outside the box, never over the page's own writing: above the box at +its left end, else above at its right end, else below it (left, then right), +else beside its right edge, else beside its left. A spot under the sticky +header, on the caption bar, in the narrator's corner, off the frame, on the +box, or over any text of the page (a card's title above the box) is passed +over; a label with no clear spot refuses the take, naming the step, so keep +labels short. `marks.json` says where it sat (`label_box`). `style = +"spotlight"` dims the rest of the frame instead. A thing off the frame, or under the page's sticky header or the caption bar, or reaching into the narrator's corner at the bottom right (240 by 200), is scrolled clear first; a thing not on the page refuses the take, naming the step. Point `at` something smaller than the diff --git a/tests/test_a_boxs_label_sits_outside_it_and_off_the_pages_own_writing.py b/tests/test_a_boxs_label_sits_outside_it_and_off_the_pages_own_writing.py new file mode 100644 index 00000000..4f5ab045 --- /dev/null +++ b/tests/test_a_boxs_label_sits_outside_it_and_off_the_pages_own_writing.py @@ -0,0 +1,161 @@ +"""The label on a box sits just outside it, and never over the page's own writing. + +The recorder used to put a box's label on the box's top-left edge, above it. +On the station screen the boxed thing sits under its card's title, so the +label covered the title's first words ("Jobs due" over MAINTENANCE, "In +spec" over RECENT RESULTS in class 2.1, 2026-11-15). The label now tries +spots in turn (above, below, beside the right edge, beside the left), passes +over any that sits on text of the page's, under the header, on the caption +bar or in the narrator's corner, and refuses the take when none is clear. +This drives the runner's own stage in Chromium against pages of those +shapes; no plant is needed. +""" + +from __future__ import annotations + +import importlib.util +from pathlib import Path + +import pytest + +pytestmark = [pytest.mark.slow, pytest.mark.browser] + +REPO = Path(__file__).resolve().parents[1] +RUNNER = REPO / "scripts" / "record-scene.py" + +VIEWPORT = {"width": 1280, "height": 720} +ORIGIN = "http://scene.test/" + +# A full-width card: its title at the top left, the boxed reading straight under it. +CARD = ( + "" + "
" + "

MAINTENANCE WINDOW AND JOBS

" + "
3 due
" +) + +# A thing at the very top of the frame: there is no room above it. +AT_TOP = ( + "" + "
at the top
" +) + +# A card on the right just above the narrator's corner (which starts at y 520, +# x 1040), its title row written at both ends, as the station's cards are: +# above is on the title, below is in the corner, right is off the frame; only +# the left is clear. +BY_THE_CORNER = ( + "" + "
" + "

" + "ISSUE MATERIAL2 lots

" + "
lot
" +) + +# A thing as big as the frame: there is no outside to put a label in. +EVERYTHING = ( + "" + "
all of it
" +) + + +@pytest.fixture(scope="module") +def runner(): + spec = importlib.util.spec_from_file_location("record_scene_label_outside", RUNNER) + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +@pytest.fixture() +def on_a_page(runner, tmp_path): + from playwright.sync_api import sync_playwright + + with sync_playwright() as pw: + browser = pw.chromium.launch() + + def open_page(body: str): + page = browser.new_page(viewport=VIEWPORT) + page.add_init_script(runner.overlay_script("pre-alpha · simulated plant · vtest")) + page.route(ORIGIN, lambda route: route.fulfill(status=200, content_type="text/html", body=body)) + page.goto(ORIGIN, wait_until="load") + stage = runner.BrowserStage(page, tmp_path, 0.0) + stage.step_number = 7 + return stage + + yield open_page + browser.close() + + +def rect(page, selector: str) -> dict: + return page.evaluate( + """(sel) => { const r = document.querySelector(sel).getBoundingClientRect(); + return {x: r.left, y: r.top, w: r.width, h: r.height}; }""", + selector, + ) + + +def writing(page, selector: str) -> dict: + """Where the words of `selector` are drawn, not the element round them.""" + return page.evaluate( + """(sel) => { const range = document.createRange(); + range.selectNodeContents(document.querySelector(sel)); + const r = range.getBoundingClientRect(); + return {x: r.left, y: r.top, w: r.width, h: r.height}; }""", + selector, + ) + + +def the_label(page) -> dict: + return rect(page, "#fs-scene-callout-label") + + +def overlap(a: dict, b: dict) -> bool: + across = a["x"] < b["x"] + b["w"] and b["x"] < a["x"] + a["w"] + return across and a["y"] < b["y"] + b["h"] and b["y"] < a["y"] + a["h"] + + +def test_a_label_on_a_box_under_a_card_title_does_not_cover_the_title(on_a_page): + stage = on_a_page(CARD) + + stage.say("Three jobs are due.", 0.05, at="#jobs", label="Jobs due") + + label, title = the_label(stage.page), writing(stage.page, "#title") + assert not overlap(label, title), f"the label {label} covers the card's title {title}" + assert not overlap(label, rect(stage.page, "#fs-scene-callout")), "the label is on its own box" + assert stage.marks[-1]["label_box"] == {key: round(label[key]) for key in ("x", "y", "w", "h")} + + +def test_a_box_at_the_top_of_the_frame_gets_its_label_below_it(on_a_page): + stage = on_a_page(AT_TOP) + + stage.say("At the top.", 0.05, at="#top", label="Top") + + label, box = the_label(stage.page), rect(stage.page, "#fs-scene-callout") + assert label["y"] >= box["y"] + box["h"], f"the label {label} is not below the box {box}" + assert label["y"] + label["h"] <= VIEWPORT["height"] - stage_caption_height(stage) + + +def stage_caption_height(stage) -> int: + return stage.page.evaluate("document.getElementById('fs-scene-cap').offsetHeight") + + +def test_a_box_beside_the_narrators_corner_keeps_its_label_out_of_the_corner_and_off_the_title(runner, on_a_page): + stage = on_a_page(BY_THE_CORNER) + + stage.say("Issue the lot.", 0.05, at="#issue", label="Issue") + + label = the_label(stage.page) + corner = {"x": VIEWPORT["width"] - runner.AVATAR_WIDTH, "y": VIEWPORT["height"] - runner.AVATAR_HEIGHT, + "w": runner.AVATAR_WIDTH, "h": runner.AVATAR_HEIGHT} + assert not overlap(label, corner), f"the label {label} is in the narrator's corner" + for words in ("#name", "#count"): + assert not overlap(label, writing(stage.page, words)), f"the label {label} covers the card's title" + assert label["x"] >= 0 and label["x"] + label["w"] <= VIEWPORT["width"] + + +def test_a_label_with_no_clear_spot_refuses_the_take_naming_the_step(on_a_page): + stage = on_a_page(EVERYTHING) + + with pytest.raises(SystemExit, match=r"^step 7: the label 'Everything'"): + stage.say("All of it.", 0.05, at="#all", label="Everything") From 80eb74a56922a8ab54c8d6536d21cb9569c00114 Mon Sep 17 00:00:00 2001 From: scottkalw Date: Mon, 16 Nov 2026 17:39:28 -0600 Subject: [PATCH 2/2] A label with nowhere clear may cover only the boxed thing's own caption The first re-take of class 2.1 stopped twice: the Characteristic list and the order's status pill sit in rows of fields so tight that every spot round them holds a neighbour's words. Both times the only free space is over the thing's own caption, the word that already names it. When no spot is clear, the label now tries again on the box's edge, as a tab, allowed to cover that caption (its