vh/booth
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(u3): a verbatim report declares the seam, the Booth mounts into it

Browse Source 
A booth that ships its own index.html was served through ten regular
expressions applied to markup the Booth did not write: six in
wrap_verbatim_html hunting for somewhere to hang a favicon and a chip, four
in booth/inline.py substituting rendered ask markup into the author's own
tags. Both worked. Both were the most fragile thing in the service, on the
path the operator uses most.

The whole class is replaced by a declared seam. A report carries one line —
<script src="/_booth/embed.js" defer></script> — and the chrome mounts
through DOM APIs. What the server does to author HTML is now, in full:

    return html if declares_embed(html) else html + EMBED_SCRIPT_TAG

Two substring tests and a concatenation. Both of the old wrapper's hard
constraints stop existing rather than being satisfied more carefully:
nothing can displace a leading doctype into quirks mode and nothing can push
the charset meta out of its detection window, because nothing in front of
them ever moves. A page that declares the seam is served exactly as written.

Fragments are still rendered by the _ask_inline.html macros and handed over
GET /b/<name>/embed.json; embed.js places them and decides nothing. Openness
comes from open_marks, order from (created, id), questions in declaration
order. A single-question pick normalizes to key None, so the payload carries
questions as a list rather than an object — keying by name would serialize
that as the string "null".

Placement is an anchor fill, not a replacement: el.insertAdjacentHTML(
'beforeend'), so an author's wrapper and its contents survive. The regex it
replaces was eating the opening tag of dfa-concepts' styled .ask blocks and
orphaning their headings, live, unreported.

data-booth-mark is canonical; data-booth-ask stays a kept alias because two
live reports use it. The comment placeholders are dropped — no users.

Declared cost: the verbatim path now needs JavaScript. The never-invisible
guarantee holds through the index badge and /b/<name>/marks, both of which
render server-side.

Deleted: booth/inline.py entire, wrap_verbatim_html and its six patterns,
_BACK_CHIP, asks_chip, inject_asks, FAVICON_LINK, the styles() macro.

Tests 410 -> 434. tests/test_embed_browser.py drives a real Chromium: the
placement algorithm and the form= binding of a scattered multi-question form
cannot be observed any other way, and that binding was measured rather than
assumed (N=3 per condition, with a form-first positive control and a
points-at-nothing negative control).

Contract: docs/contracts/u3_declared_embed_seam.contract.md, with the
in-session seam review and the cold contract panel both recorded. Two of the
panel's findings were code fixes: a vacuous INV-3 falsifier that a renamed
regex walked straight through, and a bare-substring seam detection that read
a report merely quoting the path as declaring it and silently served it with
no chrome.
This commit is contained in:
vh
2026-09-22 10:43:41 -07:00
parent 42ea67f33f
commit 87e2c5364c
17 changed files with 2015 additions and 503 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tests/test_asks.py
+71 -67
View File
@@ -13,7 +13,7 @@ import pathlib
import pytest
from fastapi.testclient import TestClient
from booth.app import build_gallery, create_app, list_booths
from booth.app import EMBED_SCRIPT_TAG, build_gallery, create_app, list_booths
from booth.asks import (
ANSWER_SUFFIX,
ASK_SUFFIX,
@@ -410,32 +410,37 @@ def test_declare_pick_accepts_a_full_multi_doc(tmp_path):
# into the verbatim page plus a standalone /asks page that carries the forms.
def test_verbatim_booth_renders_the_ask_inline(client):
def test_verbatim_booth_offers_the_ask_over_the_seam(client):
"""U3: the report is served as written and the ask crosses the declared seam.
Before U3 the fragments were substituted into the page body by regex; the
guarantee that the ask is reachable FROM THE REPORT, not from another page,
is unchanged — it is the delivery that moved."""
c, data = client
b = _ask(data / "b")
(b / "index.html").write_text("<!doctype html><title>report</title><body>hi</body>")
html = c.get("/b/b/").text
assert "hi" in html # the report is still served verbatim
assert "Which render wins?" in html # ...with the ask ON it, not elsewhere
assert 'type="radio"' in html and 'action="/b/b/answer"' in html
assert "bk-ask" in html # self-contained fragment styles
assert "booth-nav-asks" in html # chip remains, as a jump link
assert "#bk-ask-winner-top" in html
assert "Which render wins?" not in html # ...and NOTHING was injected into it
assert html.endswith(EMBED_SCRIPT_TAG)
(m,) = c.get("/b/b/embed.json").json()["marks"]
assert "Which render wins?" in m["whole"]
assert 'type="radio"' in m["whole"] and 'action="/b/b/answer"' in m["submit"]
def test_verbatim_chip_disappears_once_answered(client):
c, data = client
b = _ask(data / "b")
(b / "index.html").write_text("<!doctype html><body>hi</body>")
assert c.get("/b/b/embed.json").json()["open"] == ["winner"]
answer_pick(b, "winner", "A — baseline")
assert "booth-nav-asks" not in c.get("/b/b/").text
assert c.get("/b/b/embed.json").json()["open"] == []
def test_verbatim_booth_without_asks_is_untouched(client):
c, data = client
(data / "b").mkdir()
(data / "b" / "index.html").write_text("<!doctype html><body>hi</body>")
assert "booth-nav-asks" not in c.get("/b/b/").text
assert c.get("/b/b/embed.json").json()["marks"] == []
def test_asks_page_renders_forms_and_answers_back_to_itself(client):
@@ -477,42 +482,64 @@ def test_asks_page_shows_a_single_ask_title(client):
assert "emmie — pick the anchor" in c.get("/b/b/marks").text
# ---- inline placement in a verbatim report -----------------------------------
# ---- placement in a verbatim report ------------------------------------------
#
# Operator verdict 2026-09-09 on the separate /asks page: "the asks should be
# inline with the artifacts, not on a separate page." A four-voice audition wants
# each voice's radio group under that voice's audio, and one submit for the lot.
#
# U3 kept the semantics and moved the mechanism. The author still marks up where
# each piece goes; the pieces are still rendered by the `_ask_inline.html`
# macros; they now reach the page through `/b/<name>/embed.json` and are mounted
# by `/_booth/embed.js` instead of substituted into the author's tags by regex.
#
# So the placement ASSERTIONS moved too, and where each half lives is not
# arbitrary: what the server offers is checked here, in Python; where it LANDS,
# and whether a form scattered down a report actually submits, is checked in
# tests/test_embed_browser.py against a real DOM. No string assertion can see
# the second thing, and that is exactly the part the operator depends on.
REPORT = """<!doctype html><title>audition</title><body>
<h1>Three voices</h1>
<section id="lawson"><audio src="a.wav"></audio>
<div data-booth-ask="batch:r1"></div></section>
<section id="jo"><audio src="b.wav"></audio>
<!-- booth:ask batch:r2 --></section>
<div data-booth-mark="batch:r2"></div></section>
<div data-booth-ask-submit="batch"></div>
<script src="/_booth/embed.js" defer></script>
</body>"""
def test_per_question_placeholders_land_where_the_author_put_them(client):
def test_the_author_markup_is_never_touched_by_the_server(client):
"""The whole point of the seam. A page that declares it comes back exactly
as written — placeholders still empty, waiting for the DOM."""
c, data = client
b = _multi(data / "b")
(b / "index.html").write_text(REPORT)
html = c.get("/b/b/").text
# each group is inside its own section, in document order
lawson = html.index('id="lawson"')
jo = html.index('id="jo"')
assert lawson < html.index('name="choice.r1"') < jo
assert jo < html.index('name="choice.r2"')
# one shared form, bound by the HTML5 form= attribute, submitted once
assert html.count('<form id="bk-ask-form-batch"') == 1
assert html.count('action="/b/b/answer"') == 1
assert html.count('form="bk-ask-form-batch"') >= 4
# the submit block landed at its own placeholder, not appended after </body>
assert html.index("bk-ask-form-batch") < html.index("</body>")
assert c.get("/b/b/").text == REPORT
def test_inline_form_submits_every_question_in_one_post(client):
def test_every_piece_the_author_can_place_is_offered(client):
"""One fragment per addressable piece: the whole ask, each question, and the
submit block that carries the shared <form>. The author's markup decides
which are used; the payload never decides for them."""
c, data = client
b = _multi(data / "b")
(m,) = c.get("/b/b/embed.json").json()["marks"]
assert [q["key"] for q in m["questions"]] == ["r1", "r2"]
assert 'name="choice.r1"' in m["questions"][0]["html"]
assert 'name="choice.r2"' in m["questions"][1]["html"]
# ONE form, and it lives with the submit block, so question groups scattered
# down a report bind to it by id from wherever they sit.
assert m["submit"].count('<form id="bk-ask-form-batch"') == 1
assert m["submit"].count('action="/b/b/answer"') == 1
assert 'form="bk-ask-form-batch"' in m["questions"][0]["html"]
assert 'form="bk-ask-form-batch"' in m["questions"][1]["html"]
def test_a_scattered_form_still_posts_as_one_answer(client):
"""The POST half of the multi-question guarantee, which U3 did not touch:
every question in one request, or the route refuses it."""
c, data = client
b = _multi(data / "b")
(b / "index.html").write_text(REPORT)
@@ -521,44 +548,21 @@ def test_inline_form_submits_every_question_in_one_post(client):
assert r.status_code == 303
ans = _answer_of(b, "batch")
assert ans["answers"]["r1"]["choice"] == "keep" and ans["answers"]["r2"]["choice"] == "d"
# and the recorded pick now shows inline, on the report itself
html = c.get("/b/b/").text
assert "recorded:" in html and "bk-done" in html
assert 'value="keep" required checked' in html.replace("\n", " ") or "checked" in html
# and the recorded pick comes back marked answered, on the report's own seam
(m,) = c.get("/b/b/embed.json").json()["marks"]
assert "recorded:" in m["whole"] and "bk-done" in m["whole"]
assert "checked" in m["questions"][0]["html"]
def test_whole_ask_placeholder_renders_everything_there(client):
c, data = client
b = _ask(data / "b")
(b / "index.html").write_text('<!doctype html><body><p>x</p><div data-booth-ask="winner"></div></body>')
html = c.get("/b/b/").text
assert html.index("Which render wins?") > html.index("<p>x</p>")
assert html.index("bk-ask-go") < html.index("</body>") # submit placed inline too
def test_placeholder_for_a_missing_ask_is_left_alone(client):
c, data = client
b = _ask(data / "b")
(b / "index.html").write_text('<!doctype html><body><div data-booth-ask="typo"></div></body>')
html = c.get("/b/b/").text
assert 'data-booth-ask="typo"' in html # author's markup untouched, not blanked
assert "Which render wins?" in html # the real ask still appended, never lost
def test_questions_placed_without_a_submit_still_get_one(client):
c, data = client
b = _multi(data / "b")
(b / "index.html").write_text('<!doctype html><body><div data-booth-ask="batch:r1"></div></body>')
html = c.get("/b/b/").text
assert html.count('<form id="bk-ask-form-batch"') == 1 # appended, so it is submittable
assert 'name="choice.r2"' in html # r2 unplaced -> must still appear
def test_styles_are_emitted_once(client):
def test_the_page_carries_no_fragment_styles(client):
"""`styles()` is gone from the template: the scoped `.bk-ask-*` rules live in
embed.js, next to the code that mounts them. One asset, emitted once by
construction rather than by a seen-set."""
c, data = client
b = _multi(data / "b")
(b / "index.html").write_text(REPORT)
assert c.get("/b/b/").text.count(".bk-ask-opt:has(input:checked)") == 1
assert ".bk-ask-opt:has(input:checked)" not in c.get("/b/b/").text
assert c.get("/_booth/embed.js").text.count(".bk-ask-opt:has(input:checked)") == 1
def test_radios_are_not_html_required_anywhere(client):
@@ -566,20 +570,20 @@ def test_radios_are_not_html_required_anywhere(client):
is exactly what stopped the operator leaving one blank."""
c, data = client
b = _multi(data / "b")
assert "required" not in c.get("/b/b/").text
(b / "index.html").write_text('<!doctype html><body><div data-booth-ask="batch"></div></body>')
assert "required" not in c.get("/b/b/").text
(m,) = c.get("/b/b/embed.json").json()["marks"]
assert "required" not in m["whole"]
assert not any("required" in q["html"] for q in m["questions"])
assert "required" not in c.get("/b/b/marks").text
def test_partial_answer_renders_as_skipped_inline(client):
def test_partial_answer_renders_as_skipped(client):
c, data = client
b = _multi(data / "b")
(b / "index.html").write_text('<!doctype html><body><div data-booth-ask="batch"></div></body>')
(b / "index.html").write_text(REPORT)
c.post("/b/b/answer", data={"ask": "batch", "choice.r1": "keep"})
html = c.get("/b/b/").text
assert "bk-skip" in html and "left blank" in html
assert "1 of 2 answered" in html
(m,) = c.get("/b/b/embed.json").json()["marks"]
assert "bk-skip" in m["whole"] and "left blank" in m["whole"]
assert "1 of 2 answered" in m["submit"]
def test_empty_submission_is_refused_with_400(client):