harness.py

Part of Claustrowordia.

"""Scripted-input harness: exercises the title screen, pickup, drop, and scoring.

Captures frames at key moments to demonstrate the gameplay loop:

    01_idle.png         starting board (4 pre-placed centre tiles + 7 hand tiles)
    02_pickup.png       picked up the leftmost hand tile
    03_hover_cell.png   tile follows cursor; drop-preview snaps to grid cell
    04_placed.png       tile dropped on the board (place punch + pop sound)
    05_word_scored.png  word formed: letters flash green, score increments
    06_full_board.png   several more tiles placed, score climbing

Run:
    uv run python examples/ports/claustrowordia/harness.py
"""

from __future__ import annotations

import sys
from collections.abc import Callable
from pathlib import Path

_PORT_DIR = Path(__file__).parent
if str(_PORT_DIR) not in sys.path:
    sys.path.insert(0, str(_PORT_DIR))

from main import HEIGHT, WIDTH, ClaustrowordiaRoot  # noqa: E402
from nodes import dictionary as dict_mod  # noqa: E402
from nodes.grid import GRID_H, GRID_W  # noqa: E402
from nodes.textures import TILE_SIZE  # noqa: E402

from simvx.core.input.enums import MouseButton  # noqa: E402
from simvx.core.testing import InputSimulator  # noqa: E402
from simvx.graphics import App, save_png  # noqa: E402

OUT = _PORT_DIR / "screenshots"

# Pre-place letters so the harness reliably forms a real word. Game deals the
# four centre tiles in the order (2,2), (4,2), (2,4), (4,4) and then draws the
# seven hand tiles, all off the front of the pool. Cells (2,2) and (2,4) share
# column 2, so seeding C and T there and dealing A as the first hand tile makes
# a drop at (2,3) spell "CAT" vertically. The other two corners are fillers.
HARNESS_POOL_PREFIX = [
    "C",
    "Q",
    "T",
    "Q",  # centre tiles at (2,2)=C, (4,2)=Q, (2,4)=T, (4,4)=Q
    "A",
    "B",
    "D",
    "E",
    "F",
    "G",
    "H",  # hand tiles 0..6
]


def cell_to_world_xy(viewport_w: int, viewport_h: int, gx: int, gy: int) -> tuple[float, float]:
    """Mirror Game.grid.cell_to_world(); used to compute click positions."""
    cx = viewport_w / 2
    grid_centre_y = viewport_h * 0.46
    cell_spacing = TILE_SIZE + 8
    x = cx + (gx - (GRID_W - 1) / 2) * cell_spacing
    y = grid_centre_y + (gy - (GRID_H - 1) / 2) * cell_spacing
    return float(x), float(y)


def hand_tile_xy(viewport_w: int, viewport_h: int, slot: int, total: int = 7) -> tuple[float, float]:
    """Mirror Hand.layout(): returns the world-space centre of slot `slot`."""
    cx = viewport_w / 2
    hand_y = viewport_h - 92
    spacing = TILE_SIZE + 14
    x = cx + (slot - (total - 1) / 2) * spacing
    return float(x), float(hand_y)


def capture_sequence() -> None:
    OUT.mkdir(exist_ok=True)
    # Seed dictionary RNG (this also clears the pool) + prime the letters.
    dict_mod.seed(42)
    dict_mod.push_front(HARNESS_POOL_PREFIX)

    app = App(width=WIDTH, height=HEIGHT, title="Claustrowordia Harness", visible=False)
    sim = InputSimulator()

    captures: dict[int, str] = {}
    actions: dict[int, Callable[[], None]] = {}

    def move(x: float, y: float) -> Callable[[], None]:
        return lambda: sim.move_mouse(x, y)

    def click(x: float, y: float) -> Callable[[], None]:
        # Press only: the game reads the press edge, and holding the button
        # across a few frames matches how a player actually drags a tile.
        return lambda: sim.press_mouse(MouseButton.LEFT, (x, y))

    def release_lmb() -> Callable[[], None]:
        return lambda: sim.release_mouse(MouseButton.LEFT)

    # Hand slot 0 should be "A" (first letter after the four centre tiles).
    h0_x, h0_y = hand_tile_xy(WIDTH, HEIGHT, 0)
    cell_2_3_x, cell_2_3_y = cell_to_world_xy(WIDTH, HEIGHT, 2, 3)

    # Frames 5..10: dismiss the title screen so the board is dealt.
    actions[5] = click(WIDTH / 2, HEIGHT / 2)
    actions[10] = release_lmb()

    # Frame 30: idle starting state
    captures[30] = "01_idle.png"

    # Frame 50: pick up hand tile 0 ("A"); then move the cursor up so the
    # tile follows it visibly (otherwise the screenshot just looks like the
    # tile is still in the hand).
    actions[45] = click(h0_x, h0_y)
    actions[50] = release_lmb()
    actions[55] = move(WIDTH * 0.3, HEIGHT * 0.55)
    captures[70] = "02_pickup.png"

    # Frame 80: hover the cell (2, 3), between C at (2,2) and T at (2,4).
    # Capture *before* the drop click so the shot shows the held tile snapped
    # to the drop preview rather than the scoring flash that follows.
    actions[80] = move(cell_2_3_x, cell_2_3_y)
    captures[90] = "03_hover_cell.png"

    # Frame 105: click to drop on the cell: forms vertical "CAT"
    actions[105] = click(cell_2_3_x, cell_2_3_y)
    actions[110] = release_lmb()
    captures[125] = "04_placed.png"

    # Frame 160: scoring animation has fired: capture the green flashed tiles
    captures[160] = "05_word_scored.png"

    # Frames 200..360: place several more tiles to demonstrate accumulation.
    plan = [
        # (frame_pickup, frame_drop, hand_slot, target_cell)
        # After dropping A, hand re-fills from the random pool, so the next
        # tiles aren't deterministic, so we pick targets that are likely empty
        # and don't require a specific letter to score.
        (210, 230, 0, (3, 2)),
        (250, 270, 0, (3, 4)),
        (290, 310, 0, (1, 3)),
        (330, 350, 0, (5, 3)),
    ]
    for fp, fd, slot, (gx, gy) in plan:
        hx, hy = hand_tile_xy(WIDTH, HEIGHT, slot)
        tx, ty = cell_to_world_xy(WIDTH, HEIGHT, gx, gy)
        actions[fp] = click(hx, hy)
        actions[fp + 5] = release_lmb()
        actions[fp + 10] = move(tx, ty)
        actions[fd] = click(tx, ty)
        actions[fd + 5] = release_lmb()

    captures[370] = "06_full_board.png"

    total_frames = 400

    def on_frame(idx, _t):
        fn = actions.get(idx)
        if fn is not None:
            fn()

    def capture_fn(idx):
        return idx in captures

    frames = app.run_headless(
        ClaustrowordiaRoot(),
        frames=total_frames,
        on_frame=on_frame,
        capture_fn=capture_fn,
    )

    capture_indices = sorted(captures.keys())
    for fi, img in zip(capture_indices, frames, strict=False):
        out = OUT / captures[fi]
        save_png(img, out)
        print(f"saved {out}")
    print(f"{len(capture_indices)} screenshots written")


if __name__ == "__main__":
    capture_sequence()