booth/tests/test_navigation.py

"""U7 — the rail, the filters, the grid keyboard, and the groups.

All four components. The fourth — replacing directory sections with
filename-derived groups — was a scope DEPARTURE from ROADMAP's U7 row and was
ratified by the operator on 2026-09-22; `test_no_group_rail_is_shipped_yet`,
the guard that held it back while the ruling was outstanding, was deleted in
the commit that built it. A guard that outlives its reason is worse than no
guard, because the next reader trusts it.

`unanswered` is taken to mean HAS AN OPEN PICK — the U4 hold predicate, which
already exists and already has a home. The alternative reading ("has no mark at
all") is a real and different question and is the contract's open question.
"""

from __future__ import annotations

import json
import pathlib
import sys

import pytest
from fastapi.testclient import TestClient

sys.path.insert(0, str(pathlib.Path(__file__).parent.parent))

from booth.app import create_app  # noqa: E402
from booth.marks import declare_pick, set_flag, write_note  # noqa: E402

PNG = b"\x89PNG\r\n\x1a\n"


@pytest.fixture
def gallery(tmp_path):
    """A booth with one of each: flagged, annotated, open pick, and plain."""
    b = tmp_path / "g"
    b.mkdir()
    for n in ("a.png", "b.png", "c.png", "d.png"):
        (b / n).write_bytes(PNG)
    set_flag(b, "a.png", True)
    write_note(b, "b.png", "a remark")
    declare_pick(b, "q", {"prompt": "Which?", "options": ["x", "y"]}, target="c.png")
    app = create_app(tmp_path, ttl_hours=24, start_sweeper=False)
    return TestClient(app), b


def _tiles(body: str) -> list[str]:
    """The rels the grid actually rendered, in render order."""
    import re
    # `data-item` already exists on every tile (both the doc and media
    # variants). Reusing it rather than adding a parallel `data-rel` is the
    # same one-fact-one-place discipline INV-1 states for item facts.
    return re.findall(r'data-item="([^"]+)"', body)


def test_the_rail_counts_every_filter(gallery):
    c, _ = gallery
    body = c.get("/b/g/").text
    assert 'class="rail"' in body
    for token in ("all", "flagged", "annotated", "unanswered"):
        assert f'data-filter="{token}"' in body, token


@pytest.mark.parametrize("flt,expected", [
    ("all", ["a.png", "b.png", "c.png", "d.png"]),
    ("flagged", ["a.png"]),
    ("annotated", ["b.png"]),
    ("unanswered", ["c.png"]),
])
def test_a_filter_narrows_the_grid_server_side(gallery, flt, expected):
    """INV-4: a filter is a LINK, not a script. Fetched directly, with no JS
    executed, the server must return the narrowed grid.

    Defeating change: binding filters to a click handler and returning the full
    grid for every URL — under which this test gets four tiles every time."""
    c, _ = gallery
    assert _tiles(c.get(f"/b/g/?filter={flt}").text) == expected


def test_filtering_never_reorders(gallery):
    """INV-2, the load-bearing one. Grouping and filtering are VIEWS.

    The defeating change is sorting the grid by anything derived from the
    filter — which looks right and silently changes what "the third one" means,
    the misfiled-judgment failure CLAUDE.md invariant 6 exists to prevent.

    Asserted as a SUBSEQUENCE rather than a set: order is the property, so a
    filter that returned the right tiles in the wrong sequence must go red."""
    c, _ = gallery
    # ⚠ THE BASELINE IS COMPUTED INDEPENDENTLY, and that is the whole test.
    # The first version of this compared each filtered view against the
    # UNFILTERED RESPONSE — and a mutation that reversed the order reversed
    # both sides, so it stayed green under the exact change it forbade. Caught
    # by running the mutation rather than trusting the assertion, which is the
    # discipline in persistent-memory.d/2026-09-22-vacuous-falsifiers.md and
    # which this test failed first time out.
    #
    # The independent truth is U1 INV-3: the item order IS `sorted(rel)`. So
    # each filtered view must be sorted, full stop, with no reference to any
    # other response.
    for flt in ("all", "flagged", "annotated", "unanswered"):
        got = _tiles(c.get(f"/b/g/?filter={flt}").text)
        assert got == sorted(got), f"{flt} rendered out of sorted(rel) order: {got}"
    # and every filtered view is a SUBSEQUENCE of the true order, not a reshuffle
    every = sorted(["a.png", "b.png", "c.png", "d.png"])
    for flt in ("all", "flagged", "annotated", "unanswered"):
        got = _tiles(c.get(f"/b/g/?filter={flt}").text)
        assert got == [r for r in every if r in got], flt


def test_an_unknown_filter_falls_back_to_all_and_does_not_500(gallery):
    """A filter arrives from a URL, which is operator-editable and link-shared.
    Defeating change: indexing a dict by the raw parameter."""
    c, _ = gallery
    for junk in ("nonsense", "", "../../etc", "flagged;drop"):
        r = c.get(f"/b/g/?filter={junk}")
        assert r.status_code == 200, junk
        assert len(_tiles(r.text)) == 4, junk


def test_the_zoom_ring_is_identical_under_every_filter(gallery):
    """The ring is the item order filtered to images and must not notice the
    grid's filter — otherwise `next` means something different depending on how
    the operator arrived, and a flag lands on the wrong artifact.

    Defeating change: building the ring from the filtered list."""
    c, _ = gallery
    rings = set()
    for flt in ("all", "flagged", "annotated", "unanswered"):
        c.get(f"/b/g/?filter={flt}")
        body = c.get("/b/g/b.png?view=1").text
        import re
        rings.add(tuple(re.findall(r'href="([^"]*\.png[^"]*)"', body)))
    assert len(rings) == 1, f"the ring changed with the filter: {rings}"


def test_the_rail_is_absent_on_a_booth_with_no_grid(tmp_path):
    """INV-5's sibling: a rail over nothing is chrome. The standing link board
    has no items, so it must not render one."""
    b = tmp_path / "links"
    b.mkdir()
    (b / "links.md").write_text("- [r](https://x.test/) <sub>· a · 2026-09-01 00:00</sub>\n")
    c = TestClient(create_app(tmp_path, ttl_hours=24, start_sweeper=False))
    assert 'class="rail"' not in c.get("/b/links/").text


def test_the_keyboard_is_not_bound_when_there_is_no_grid(tmp_path):
    """INV-5. Defeating change: binding the handler unconditionally, so `f` on
    the standing link board swallows the keystroke and flags nothing."""
    b = tmp_path / "links"
    b.mkdir()
    (b / "links.md").write_text("- [r](https://x.test/) <sub>· a · 2026-09-01 00:00</sub>\n")
    c = TestClient(create_app(tmp_path, ttl_hours=24, start_sweeper=False))
    assert "gridkeys" not in c.get("/b/links/").text


def test_the_keyboard_is_bound_when_there_is_one(gallery):
    c, _ = gallery
    assert "gridkeys" in c.get("/b/g/").text




# --- U7 slice 2: the groups ----------------------------------------------


@pytest.fixture
def grouped(tmp_path):
    """Two groups whose members INTERLEAVE in `sorted(rel)`.

    `a/x1.png, a/y1.png, b/x2.png, b/y2.png` is the sorted order; group `x` is
    at positions 0 and 2, group `y` at 1 and 3. That interleaving is the whole
    point of the fixture — a grid re-sorted by `(group, rel)` to make groups
    render contiguously would pass every set-based assertion and fail these.
    """
    b = tmp_path / "g"
    for rel in ("a/x1.png", "a/y1.png", "b/x2.png", "b/y2.png"):
        p = b / rel
        p.parent.mkdir(parents=True, exist_ok=True)
        p.write_bytes(PNG)
    app = create_app(tmp_path, ttl_hours=24, start_sweeper=False)
    return TestClient(app), b


def _groups(body: str) -> list[str]:
    """The group keys the rail listed, in render order."""
    import re
    return re.findall(r'data-group="([^"]+)"', body)


def test_the_rail_lists_groups_when_grouping_is_informative(grouped):
    c, _ = grouped
    body = c.get("/b/g/").text
    assert 'class="rail-groups"' in body
    assert _groups(body) == ["x", "y"]


def test_group_order_is_the_position_of_the_first_member(tmp_path):
    """The settled rule (ROADMAP, operator 2026-09-22): groups order by where
    each group's FIRST member falls in the rendered sequence.

    ⚠ THIS FIXTURE IS BUILT SO THE THREE PLAUSIBLE RULES ALL DISAGREE. The
    first version used `w, x, y` — whose positional order happens to BE
    alphabetical, so it stayed green under the very change it forbade. Caught
    by running the mutation, not by reading the assertion; the same trap
    persistent-memory.d/2026-09-22-vacuous-falsifiers.md names and the same one
    `test_filtering_never_reorders` fell into an hour after it was written.

        sorted(rel):  a/z1  a/z2  b/a1  b/a2  b/a3  c/m1  c/m2
        by position:  z (0), a (2), m (5)      <- the rule
        alphabetical: a, m, z                  <- wrong, and differs
        by count:     a(3), z(2), m(2)         <- wrong, and differs
    """
    b = tmp_path / "g"
    for rel in ("a/z1.png", "a/z2.png", "b/a1.png", "b/a2.png", "b/a3.png",
                "c/m1.png", "c/m2.png"):
        q = b / rel
        q.parent.mkdir(parents=True, exist_ok=True)
        q.write_bytes(PNG)
    c = TestClient(create_app(tmp_path, ttl_hours=24, start_sweeper=False))
    assert _groups(c.get("/b/g/").text) == ["z", "a", "m"]


def test_grouping_never_reorders_the_grid(grouped):
    """INV-2, the load-bearing one.

    The defeating change is sorting the grid by `(group, rel)` so groups render
    contiguously — which looks right, passes any set comparison, and silently
    changes what "the third one" means. This fixture interleaves precisely so
    that change goes red.

    The baseline is INDEPENDENT (U1 INV-3: the order IS `sorted(rel)`), not a
    second response — the vacuous-falsifier trap this suite already fell into
    once."""
    c, _ = grouped
    tiles = _tiles(c.get("/b/g/").text)
    assert tiles == ["a/x1.png", "a/y1.png", "b/x2.png", "b/y2.png"]
    assert tiles == sorted(tiles)


def test_every_group_anchor_lands_on_a_rendered_tile(grouped):
    """A jump-to-group link that scrolls nowhere is worse than no link. Every
    anchor must name an id the page actually carries.

    Defeating change: anchoring to the group KEY (`#group-x`) while the tiles
    carry `id="item-<rel>"` — which renders, looks right, and does nothing."""
    import re
    c, _ = grouped
    body = c.get("/b/g/").text
    hrefs = re.findall(r'class="rail-g"[^>]*href="#([^"]+)"', body)
    assert hrefs, "the rail rendered no group anchors"
    for h in hrefs:
        assert f'id="{h}"' in body, f"anchor #{h} names no element on the page"


def test_no_group_rail_when_every_item_is_its_own_group(gallery):
    """INV-3's real failure mode, and it is NOT the one the contract feared.

    `a.png b.png c.png d.png` yields four groups of one — a rail that is a
    second copy of the grid. Measured live: `pewpew-ui-brief` gives 23 groups
    for 34 items, `dfa-concepts` 13 for 20. The contract only guarded the
    opposite degeneracy (one group for everything), which is why this test
    exists.

    Defeating change: `{% if rail.groups %}`, true for four singletons."""
    c, _ = gallery
    body = c.get("/b/g/").text
    assert 'class="rail-groups"' not in body
    assert 'class="rail"' in body, "the filter rail must still be here"


def test_no_group_rail_when_there_is_only_one_group(tmp_path):
    """INV-3 as the contract states it, with the live specimen: `sc-iso-spread`
    is `DSC0001.jpg` through `DSC0006.jpg` — one group, six images.

    Defeating change: `{% if rail.groups %}`, true for a single group."""
    b = tmp_path / "flat"
    b.mkdir()
    for i in range(1, 7):
        (b / f"DSC{i:04d}.jpg").write_bytes(PNG)
    c = TestClient(create_app(tmp_path, ttl_hours=24, start_sweeper=False))
    body = c.get("/b/flat/").text
    assert 'class="rail-groups"' not in body
    assert 'class="rail"' in body


def test_groups_describe_the_filtered_grid(tmp_path):
    """The rail describes what is ON SCREEN. An anchor to a group the filter
    has hidden would scroll nowhere — the same defect as a wrong id, arriving
    by a different route.

    Three groups of two; the flag covers `x` and `y` entirely and `z` not at
    all. Under `?filter=flagged` the rail must list x and y and MUST NOT list
    z, whose two tiles are not on the page.

    Defeating change: deriving groups from the full gallery rather than from
    the rendered list — under which `z` appears and its anchor goes nowhere."""
    b = tmp_path / "g"
    b.mkdir()
    for n in ("x1.png", "x2.png", "y1.png", "y2.png", "z1.png", "z2.png"):
        (b / n).write_bytes(PNG)
    for n in ("x1.png", "x2.png", "y1.png", "y2.png"):
        set_flag(b, n, True)
    c = TestClient(create_app(tmp_path, ttl_hours=24, start_sweeper=False))

    assert _groups(c.get("/b/g/").text) == ["x", "y", "z"]
    body = c.get("/b/g/?filter=flagged").text
    assert _groups(body) == ["x", "y"]
    assert _tiles(body) == ["x1.png", "x2.png", "y1.png", "y2.png"]


def test_a_filtered_view_too_small_to_group_drops_the_group_row(grouped):
    """The informativeness rule binds to the RENDERED list, not to the booth.

    One flagged tile is one group of one, which cannot navigate — so the group
    row goes away even though the unfiltered booth has a perfectly good one.
    The filter rail stays, because that is how the operator gets back."""
    c, b = grouped
    set_flag(b, "a/x1.png", True)
    assert 'class="rail-groups"' in c.get("/b/g/").text
    body = c.get("/b/g/?filter=flagged").text
    assert 'class="rail-groups"' not in body
    assert 'class="rail"' in body


def test_the_zoom_ring_ignores_grouping(grouped):
    """The ring is `sorted(rel)` filtered to images and must not notice groups
    any more than it notices filters.

    THE FIXTURE IS THE FALSIFIER. From `a/x1.png`, sorted order says next is
    `a/y1.png` — a DIFFERENT group. A ring rebuilt per group would say
    `b/x2.png`, the next member of group `x`, and `→` would start walking a
    sequence the operator never saw on the page. That is invariant 6's
    misfiled-judgment failure exactly: the flag lands on the wrong artifact."""
    import re
    c, _ = grouped
    body = c.get("/b/g/view?f=a/x1.png").text
    nxt = re.findall(r'class="vnav vnext" href="\?f=([^"&]+)"', body)
    assert nxt == ["a/y1.png"], f"the ring followed the group, not sorted(rel): {nxt}"
    # and the zoom page has no group chrome at all — it is one artifact, not a wall
    assert "data-group" not in body


def test_no_route_body_derives_a_group(gallery):
    """INV-1, the same assertion U1 makes for `classify` and `render_doc`.

    Defeating change: a route or template computing a prefix inline — the
    caption bug in a new field."""
    import inspect

    import booth.app as app_mod

    src = inspect.getsource(app_mod.create_app)
    assert "_group_of" not in src, "create_app must read Item.group, not derive it"


def test_a_hostile_filename_cannot_break_out_of_the_rail(tmp_path):
    """Group keys and anchors are AGENT-AUTHORED — they are filenames, and a
    session makes a booth by making a folder with no validation anywhere in the
    path. CLAUDE.md names autoescape as load-bearing for exactly this.

    Defeating change: building the rail markup with `|safe`, or assembling the
    href by string concatenation outside Jinja. Both render, both look right,
    and both put attacker-controlled bytes into an attribute."""
    b = tmp_path / "g"
    b.mkdir()
    for n in ('q"x1.png', 'q"x2.png', "s<script>1.png", "s<script>2.png"):
        (b / n).write_bytes(PNG)
    c = TestClient(create_app(tmp_path, ttl_hours=24, start_sweeper=False))
    import re
    r = c.get("/b/g/")
    assert r.status_code == 200
    body = r.text

    # THE RAIL ITSELF, isolated — asserting over the whole page would pass on a
    # booth where the escaping happened somewhere else.
    nav = re.search(r'<nav class="rail-groups".*?</nav>', body, re.S)
    assert nav, "the rail rendered no group row"
    nav = nav.group(0)

    # No tag the template did not write, and no attribute the filename closed.
    # Asserted as the SET of element names rather than by counting `<`, which
    # the first version got wrong by forgetting the `<b>` counts — an arithmetic
    # slip that made the test red for a reason unrelated to escaping.
    tags = set(re.findall(r"</?([a-zA-Z][a-zA-Z0-9]*)", nav))
    assert tags == {"nav", "a", "b"}, f"the rail grew an element: {tags}"
    assert 'data-group="q"' not in nav, "the quote closed the attribute"
    assert "&lt;script&gt;" in nav and "<script" not in nav
    assert "&#34;" in nav or "&quot;" in nav, "the quote was not escaped"


def test_a_group_key_is_never_the_empty_string(tmp_path):
    """`_group_of` returns None rather than "" for a stem with nothing before
    the digits. A "" key would render a nameless rail row that files every
    numbered render under it — the failure the None is there to prevent.

    Defeating change: `return segs[0]` without the `or None`."""
    b = tmp_path / "g"
    b.mkdir()
    for n in ("01.png", "02.png", "03.png", "ac1.png", "ac2.png"):
        (b / n).write_bytes(PNG)
    c = TestClient(create_app(tmp_path, ttl_hours=24, start_sweeper=False))
    body = c.get("/b/g/").text
    assert 'data-group=""' not in body
    assert "" not in _groups(body)


# --- from the heid bug-hunt panel, 2026-09-22 -----------------------------
# 4-of-4 convergence on the anchor, two strong solos from Gróa, and three of
# this file's own falsifiers shown vacuous by the arms' guard-strength passes.


def test_a_group_anchor_survives_a_filename_that_percent_decodes(tmp_path):
    """THE 4-OF-4 FINDING. The anchor was the RAW rel spliced into an href
    fragment with no percent-encoding, while the tile id was equally raw.

    A browser matches a fragment against ids RAW FIRST, then percent-decoded —
    so the failure is not "goes nowhere", it is worse: with both `a b.png` and
    `a%20b.png` in one booth, the first's href resolves to the fragment
    `item-a%20b.png` and the raw pass matches the SECOND file's id. The jump
    lands on the wrong artifact, which is the misfiled-judgment failure
    invariant 6 exists to prevent, arriving through a path invariant 6 never
    looked at.

    Both sides now use the already-percent-encoded `Item.url`, which is
    injective (`a b` -> `a%20b`, `a%20b` -> `a%2520b`) and is the convention
    `booth_flag` has always used. Defeating change: building either side from
    `name`."""
    b = tmp_path / "g"
    b.mkdir()
    for n in ("a b-1.png", "a b-2.png", "a%20b-1.png", "a%20b-2.png"):
        (b / n).write_bytes(PNG)
    c = TestClient(create_app(tmp_path, ttl_hours=24, start_sweeper=False))
    body = c.get("/b/g/").text

    import re
    hrefs = re.findall(r'class="rail-g"[^>]*href="#([^"]+)"', body, re.S)
    assert len(hrefs) == 2, f"expected two groups, got {hrefs}"
    # Every anchor names an id that exists AND no two anchors collide.
    assert len(set(hrefs)) == len(hrefs), f"two groups share one anchor: {hrefs}"
    for h in hrefs:
        assert f'id="{h}"' in body, f"anchor #{h} names no element"
    # and the raw form must NOT appear as an id, or the raw-first match steals it
    assert 'id="item-a b-1.png"' not in body


def test_a_group_anchor_names_the_FIRST_member(grouped):
    """GRÓA + HULDA + REGIN all found the same hole independently: the original
    anchor test only checked the href occurred as SOME id on the page, so a
    `v[0]` -> `v[-1]` mutation survived it completely. Three arms, one gap,
    and my own mutation table had no row for it — the fifth vacuous falsifier
    of the day.

    `a/x1.png` and `b/x2.png` are group x; the anchor must be the first."""
    import re
    c, _ = grouped
    body = c.get("/b/g/").text
    got = dict(re.findall(r'class="rail-g" data-group="([^"]+)"\s*\n?\s*href="#item-([^"]+)"', body))
    assert got == {"x": "a/x1.png", "y": "a/y1.png"}, got


def test_a_group_row_reports_its_own_size(grouped):
    """HULDA's guard table: `len(v)` -> `len(v) + 1` survived every assertion.
    The counts were rendered and never checked."""
    import re
    c, _ = grouped
    body = c.get("/b/g/").text
    counts = re.findall(r'class="rail-g"[^>]*>\s*(\S+)\s*<b>(\d+)</b>', body, re.S)
    assert dict((k, int(v)) for k, v in counts) == {"x": 2, "y": 2}


def test_the_informativeness_guard_reads_the_middle_not_the_largest(tmp_path):
    """HULDA's guard table: `sizes[len(sizes)//2]` -> `sizes[-1]` survived,
    because no fixture distinguished the middle group from the biggest one.

    Three singletons and one group of four: the largest is 4, the upper median
    is 1. The rail must be ABSENT — a rail whose rows are three-quarters
    single tiles is the second-copy-of-the-grid degeneracy."""
    b = tmp_path / "g"
    b.mkdir()
    for n in ("p1.png", "q1.png", "r1.png",
              "z1.png", "z2.png", "z3.png", "z4.png"):
        (b / n).write_bytes(PNG)
    c = TestClient(create_app(tmp_path, ttl_hours=24, start_sweeper=False))
    assert 'class="rail-groups"' not in c.get("/b/g/").text


def test_a_filter_that_matches_nothing_leaves_a_way_back(tmp_path):
    """GRÓA's strongest solo, and in her words the finding most likely to bite
    users this week.

    `{% elif items %}` gated the ENTIRE rail on the FILTERED list, so a valid
    filter with zero hits removed the rail, the filter links, and the way back
    to `all` — and the empty-booth branch then announced the booth was empty
    while `rail.total` held the real count. No recovery without editing the
    address bar, and it degraded the same way with JavaScript off.

    ⚠ THE FIXTURE MUST ACTUALLY HAVE NO HITS. The first version of this test
    used the shared `gallery` fixture, which carries one of each mark — so
    `?filter=flagged` returned one tile and the test passed without ever
    reaching the state it names. Four unmarked images; every filter but `all`
    is empty.

    Defeating change: gating the rail on `items` instead of `all_items`."""
    b = tmp_path / "g"
    b.mkdir()
    for n in ("a.png", "b.png", "c.png", "d.png"):
        (b / n).write_bytes(PNG)
    c = TestClient(create_app(tmp_path, ttl_hours=24, start_sweeper=False))

    for flt in ("flagged", "annotated", "unanswered"):
        body = c.get(f"/b/g/?filter={flt}").text
        assert _tiles(body) == [], flt
        assert 'class="rail"' in body, f"{flt}: the rail vanished with the filtered list"
        assert 'href="/b/g/"' in body, f"{flt}: no way back to `all`"
        assert "This booth is empty" not in body, f"{flt}: an empty FILTER is not an empty booth"
        assert "4 items" in body, f"{flt}: the rail must still report the real total"


def test_an_empty_booth_still_says_it_is_empty(tmp_path):
    """The negative control for the test above: the empty-booth message must
    survive the fix that stops a filter from triggering it."""
    b = tmp_path / "hollow"
    b.mkdir()
    c = TestClient(create_app(tmp_path, ttl_hours=24, start_sweeper=False))
    body = c.get("/b/hollow/").text
    assert "This booth is empty" in body
    assert 'class="rail"' not in body


def test_the_keyboard_flag_targets_a_real_button(gallery):
    """HULDA: the `f` handler selected `.flagbtn, [name="target"]`. No element
    in this repo has ever had class `flagbtn`, so it fell through to the HIDDEN
    target input — and clicking a hidden input does not submit its form. The
    shortcut has never worked, while still calling preventDefault and
    swallowing the keystroke.

    Asserted against the markup the macro actually emits."""
    import re
    c, _ = gallery
    body = c.get("/b/g/").text
    assert 'class="flagtoggle' in body, "the flag form is not what this thinks"

    # THE SELECTOR ITSELF, not the whole page — the first version asserted
    # `"flagbtn" not in body` and went red on the code COMMENT explaining the
    # bug. An assertion that cannot tell markup from prose about markup is not
    # asserting about markup.
    sel = re.search(r"case 'f': click\((.*?)\);", body)
    assert sel, "the `f` handler is gone"
    assert "flagbtn" not in sel.group(1), "the selector names a class nothing emits"
    assert ".flagtoggle button" in sel.group(1), \
        "the key handler must click the flag form's real submit button"