prettyplay 0.0.2__py3-none-any.whl

prettyplay/engine/.usages/generation.md

@@ -0,0 +1,157 @@
+# Step generation
+
+Domain: generating executable code for an unknown step. Audience: library internals and engineers debugging a first run.
+
+## Generate a step
+
+```python
+from prettyplay.engine.renderer import PreparedStep
+from prettyplay.llm import ScenarioStep
+
+step = generator.generate(
+    identity=identity,
+    prepared=PreparedStep(
+        instruction="click the Sign in button"
+    ),  # the render product of the step — instruction, inputs, declarations
+    step_type="action",
+    previous_steps=[
+        ScenarioStep(sentence="open the login page", instruction="open the login page", group_prompt=""),
+        ScenarioStep(
+            sentence="enter the login and password", instruction="enter the login and password", group_prompt=""
+        ),
+    ],
+    group_prompt=None,  # None — an ordinary step; the group prompt of the step's group inside one
+    page=page,
+    attempt_history=history,
+    window=window,
+    memory=memory,
+)
+```
+
+- The loop: request code → execute against the live page → validate the returned result → on failure append the full attempt record and re-request with the fresh snapshot and the grown history
+- The attempt history is one continuous verbatim list: every record carries the outcome, the `URL before -> after` line, the complete candidate code and the complete error; no collapsing, no size limits — the attempt budgets are the only bound. The error text follows the engine error-text policy: the bulky aria-snapshot section Playwright appends to a failed check message is excluded — the fresh page state reaches the loop through the separately captured snapshot
+- Every request carries the honest inputs: the step type (action or assertion) and the prepared instruction of the step (with its INPUTS/RESULTS blocks when present) — the raw template sentence never reaches a request; the casefolded normalization is an addressing key only
+- The page may carry side effects of failed candidates and manual intervention — the replayability requirement of the system prompt tells the model a regeneration never rides that leftover state: an action step repeats its action; a first attempt works on the page the previous steps produced. The structural separation rides the same prompt: an action step ends at its action, an assertion step observes without changing the page
+- Every candidate execution runs under the settle window: transient failures re-execute the same code inside the window (settle_retry log records), no LLM budget consumed; deterministic failures go to the next request or classification; the URL pair brackets the whole attempt, settle re-executions included
+- A non-empty generation_prompt setting adds a USER INSTRUCTIONS block to every generation and regeneration request; classification requests never carry it; changing the instructions never invalidates the cache — cached steps run as stored
+- A non-empty classification_prompt setting adds a USER INSTRUCTIONS block to classification requests only; generation requests never carry it
+- Every generation and regeneration request carries the CHEAT SHEET block right before the USER INSTRUCTIONS block — the compact standard Playwright sync API reference carried by every request; guidance, not an allowlist: everything standard stays allowed, the error-driven regeneration loop is the second line of defense
+
+## Result contract
+
+A candidate of a step with result declarations must return the dictionary of exactly the declared names to
+non-blank observed strings. After a successful execution the loop validates it deterministically
+(`validate_step_result` from the renderer): a violation is a failed check — the record lands in the history with
+the violation text, the existing classification and healing budgets apply. A valid result publishes to the test
+memory together with the gate pass: an accepted candidate publishes its captures exactly once, after validation
+and the compliance gate; failed and gate-blocked attempts publish nothing.
+
+## The execution boundary
+
+The whole step executes inside the driver worker thread as one unit: compile and resolve stay on the calling thread,
+the step call itself runs in the worker and receives the genuine sync Page — the calling thread never touches
+Playwright, so interactive hosts keep working. An AssertionError of a step — a failed expect chain or a plain assert
+on an immediate read — reaches failure classification untouched.
+
+## The decision table
+
+Every classification verdict drives the same table — the category decides, the path only delivers:
+
+| Verdict | Action |
+|---|---|
+| product_defect | ProductDefectError carrying the verdict — loud, never healed |
+| rot, fixable | regeneration carrying the classification recommendation |
+| incurable | IncurableStepError carrying the verdict |
+
+## Failed candidate check (bounded healing)
+
+A failed check — an assertion that executed and did not hold, survived the settle window — appends its attempt
+record, then is classified:
+
+- product_defect → ProductDefectError with the verdict; one failed check is spent, never the whole budget
+- rot or fixable → exactly one regeneration funded from the healing budget, the request carrying the recommendation as a RECOMMENDATION block and the grown history; success stores the healed step; a repeat failure gets one final classification deciding only the terminal kind — product_defect → ProductDefectError, anything else → IncurableStepError; no further regeneration
+- incurable → IncurableStepError with the verdict
+- LLM unavailable at the classification → the verdict is skipped quietly (WARNING in the log) and IncurableStepError raises without it
+
+## Group steps (framing, no per-step classification)
+
+Inside a group the generator behaves differently in exactly two ways:
+
+- every request of a group step carries the additive group framing — the GROUP PROMPT block and
+  the group-marked earlier steps of the group on top of the full test scenario context; nothing
+  existing is removed
+- the two internal classification points — a failed check of a candidate and the
+  generation-budget exhaustion — are suppressed: no classification request, no healing-funded
+  regeneration; the loop appends the attempt record and raises IncurableStepError carrying the
+  failed code and the full failure text; the executor routes it to the group recovery
+
+With no group framing input (`group_prompt=None`) the ordinary paths are byte-identical. The
+previous-steps context is typed: each entry carries the raw sentence plus its prepared instruction —
+requests render the instruction field with the permanent group membership marked.
+
+## The instruction compliance gate
+
+Every successfully executed candidate is verified on two dimensions before it is cached —
+instruction compliance and step adequacy — the default behavior; switch it off with
+generation_approve = false:
+
+- one verdict request per candidate through the provider (the effective classification
+  model); zero requests when the switch is off or the instructions are empty
+- the request carries INSTRUCTIONS, STEP with its STEP TYPE line, optional INPUTS and RESULTS,
+  the ATTEMPT HISTORY records and the CODE block; the reviewer is instructed to use the attempt history as
+  the ground truth of what already happened on the page
+- a high finding of either dimension fails the attempt: the record lands in the history
+  with the violation text in its error field, the retry carries the grown history — the
+  model fixes the finding targeted; budget exhaustion with a standing high finding is the
+  terminal incurable failure naming the violated instruction or the unaccomplished step
+- medium and low findings pass with a WARNING naming the instructions
+- a malformed verdict (ComplianceVerdictError) and provider unavailability
+  (LLMUnavailableError) are hard failures — a candidate is never cached unchecked
+- replayed cached code is never re-gated: changing the instructions does not invalidate
+  the cache — purge it manually when the instructions change
+
+## Budget exhaustion
+
+Each provider request may resend the identical SDK request up to `llm_request_attempts`
+(default 3, initial send included). These transport sends consume no additional generation
+or healing budget and emit no additional generation-started hooks. If the provider raises
+`LLMUnavailableError` after its retry policy terminates, generation propagates it without
+another engine attempt; an optional terminal classification still uses the quiet verdict skip.
+
+Exhaustion of the generation attempts classifies the last candidate: rot or fixable grants exactly one extra
+recommendation-carrying regeneration funded from the healing budget — a repeat failure is terminal
+IncurableStepError without reclassification; any other verdict is terminal as before. LLM unavailability at this
+classification skips the verdict quietly.
+
+## Classification call
+
+Both engines classify through one routine:
+
+```python
+from prettyplay.engine import classify_step_failure
+
+classification = classify_step_failure(
+    config=config,
+    provider=provider,
+    step_text="click the «Sign in» button",
+    code=step_code,
+    error="element not found: button «Sign in»",
+    page=page,
+)
+```
+
+The routine collects the fresh page snapshot (plus the screenshot when enabled) and calls the provider with the engine classification prompt; a non-empty classification_prompt setting of the config reaches the request as a USER INSTRUCTIONS block. The step sentence is the prepared instruction passed by the caller — never the raw template sentence; the casefolded normalization is an addressing key only. The category set is four: rot, product_defect, fixable, incurable. Provider unavailability propagates: the calling path decides whether it is a terminal infrastructure failure or a quiet verdict skip.
+
+## The fixed form
+
+Generated code is one function receiving exactly one argument — the genuine sync Playwright Page — importing from
+playwright.sync_api and the Python standard library only (third-party libraries forbidden; imports global only, at
+the top level of the code block, before `def step`, never inside the function body) and working through the standard API: `page.get_by_role("button", name="Sign in").click()`,
+`page.locator("form > button.primary")`, `items = page.get_by_role("listitem")` with
+`assert items.count() > 1`,
+`with page.expect_event("dialog") as info: ... info.value.accept()`,
+`with page.expect_popup() as popup_info: ... popup_info.value`,
+`page.frame_locator("#checkout").get_by_role("button", name="Pay").click()`,
+`locator.scroll_into_view_if_needed()`, `page.mouse.wheel(0, 600)`. No provider constructs, no fixed delays, no
+page.close()/context.close(), no stateful actions (route, clock, add_init_script, tracing, HAR, CDP) — the prompt
+rules; the runtime never enforces them.

prettyplay/engine/.usages/healing.md

@@ -0,0 +1,61 @@
+# Step healing
+
+Domain: healing a failed cached step. Audience: library internals and engineers reasoning about healed runs.
+
+## Heal
+
+```python
+from prettyplay.engine.renderer import PreparedStep
+from prettyplay.llm import ScenarioStep
+
+healed = healer.heal(
+    step=failed_step,
+    error="element not found: button «Sign in»",
+    prepared=PreparedStep(instruction="click the Sign in button"),  # the render product of the failed step
+    step_type="action",
+    previous_steps=[ScenarioStep(sentence="open the login page", instruction="open the login page", group_prompt="")],
+    page=page,
+    attempt_history=history,
+    window=window,
+    memory=memory,
+)
+```
+
+The executor seeds record 0 of `attempt_history` before the delegation — the original cached code, the full replay
+error and the URL pair of the replay — so regeneration never loses the original: the history carries every record,
+the anchored cached code first. The prepared instruction and the step type ride every classification and regeneration
+request — the casefolded normalization is an addressing key only.
+
+The classification verdict decides the path — the uniform decision table:
+
+| Category | Path |
+|---|---|
+| rot, fixable | regenerate from the current page within the healing budget (default 2), the request carrying the classification recommendation as a RECOMMENDATION block and the grown attempt history; execute under the settle window, save back to the cache on success, report loudly |
+| product_defect | raise ProductDefectError carrying the verdict — explanation and recommendation reach the exception message and the log, all three fields reach the on_step_verdict hook (the category never renders) |
+| incurable | raise IncurableStepError carrying the verdict; the reason names the incurability cause |
+
+## Rules
+
+- A healed candidate passes the two-dimension compliance gate before the write-back: a high
+  finding of either dimension fails the healing attempt — the record lands in the history
+  with the violation text in its error field; medium and low findings pass with a WARNING;
+  a malformed verdict or provider unavailability is a hard failure — nothing is cached
+  unchecked
+- Anti-masking: healing never turns a product defect into a green test
+- The healed code replaces the cached code only after a successful execution
+- The accepted regeneration publishes its validated captures after the gate — nothing publishes on a failed or gate-blocked attempt
+- Generation and healing attempts live in one per-test registry — owned by the runtime of the test — with separate per-step limits (default 3 and 2)
+- Inside the regeneration loop no per-attempt classification happens (rejected: LLM cost): a failed attempt of any kind — a failed check included — appends its record and retries with the fresh error, the fresh snapshot and the grown history while budget remains; the entry classification guards the anti-masking
+- A regeneration budget exhaustion raises IncurableStepError carrying the verdict of the original classification — no extra LLM request
+- The scenario context is typed (the raw sentence + the prepared instruction + permanent group membership; requests render the instruction); group steps never reach the healer — their failures route to the group recovery
+- Provider unavailability during the classification raises LLMUnavailableError after the provider's bounded transport policy terminates. Transport sends consume no healing budget; the healer adds no retry on this infrastructure failure.
+- Healing never runs in strict mode: a failed cached step is at most classified, never regenerated
+- Interactive steering attempts are separate from healing: they consume no budgets, join the same per-step history and report their own healings
+
+## Verdicts
+
+Every terminal failure carries its verdict in full and the full underlying error in the error field: the exception
+message is the structured render — the first line carries the class name of the terminal failure and the authored
+reason, then the `---` separated step/error section, the conditional received/cause/Call log details section and the
+unpadded verdict block; the same text reaches on_step_verdict (structured fields) and the log record. IncurableStepError
+also carries the failed step code in the code field — a programmatic field, never rendered.

prettyplay/engine/__init__.py

@@ -0,0 +1,19 @@
+"""Facade of the prettyplay.engine cell: generation, execution and healing of step code."""
+
+from .attempts import StepAttempt
+from .classification import classify_step_failure
+from .compliance import check_step_compliance
+from .execution import run_step_code
+from .generator import StepGenerator
+from .healer import StepHealer
+from .text import format_step_error
+
+__all__ = [
+    "StepAttempt",
+    "StepGenerator",
+    "StepHealer",
+    "check_step_compliance",
+    "classify_step_failure",
+    "format_step_error",
+    "run_step_code",
+]

prettyplay/engine/attempts.py

@@ -0,0 +1,80 @@
+"""The verbatim attempt record of the engine: one immutable entry of the per-step attempt history."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, ConfigDict
+
+if TYPE_CHECKING:
+    from ..driver import PageFacade
+
+#: Record 0 of a healing cycle — the anchored cached code and the error of its failed replay.
+OUTCOME_ORIGINAL = "original cached code"
+
+#: The candidate executed but its own check — an AssertionError — did not hold.
+OUTCOME_FAILED_CHECK = "failed check"
+
+#: The candidate raised a non-assertion exception while executing.
+OUTCOME_EXECUTION_FAILED = "execution failed"
+
+#: The candidate executed green but the compliance gate blocked it from the cache.
+OUTCOME_COMPLIANCE_BLOCKED = "compliance blocked"
+
+#: The engineer rejected the candidate in the steering dialog; it never executed.
+OUTCOME_REJECTED = "rejected by the engineer, not executed"
+
+
+class StepAttempt(BaseModel):
+    """One immutable verbatim record of the per-step attempt history — never rewritten or truncated.
+
+    Attributes:
+        code: the complete candidate code of the attempt, verbatim.
+        error: the complete failure text — the execution error, the failed
+            check text, or the gate violation text; empty on no error.
+        outcome: the outcome label of the closed five-label set (the
+            ``OUTCOME_*`` constants of this module).
+        url_before: the page URL read immediately before the attempt's
+            execution.
+        url_after: the page URL read immediately after the attempt's
+            execution.
+    """
+
+    model_config = ConfigDict(kw_only=True, frozen=True)
+
+    code: str = ""
+    error: str = ""
+    outcome: str = ""
+    url_before: str = ""
+    url_after: str = ""
+
+    def render(self) -> str:
+        """Render the complete verbatim record text.
+
+        Returns:
+            The multi-line record text — the pinned four-part format:
+            outcome line, URL pair, the ``code:`` part and, when non-empty,
+            the ``error:`` part; no collapsing, no truncation.
+        """
+        record = f"{self.outcome}\nurl: {self.url_before} -> {self.url_after}\ncode:\n{self.code}"
+        if self.error:
+            if not record.endswith("\n"):
+                record += "\n"
+            record += f"error:\n{self.error}"
+        return record
+
+
+def _read_url(page: PageFacade) -> str:
+    """Read the page URL for an attempt bracket; never kills the attempt.
+
+    Args:
+        page: the page facade handle of the current test.
+
+    Returns:
+        The current URL of the page, or the empty string when the read
+        fails — the attempt itself proceeds normally.
+    """
+    try:
+        return page.url
+    except Exception:
+        return ""

prettyplay/engine/classification.py

@@ -0,0 +1,70 @@
+"""The shared classification call: collect the page state and ask the provider."""
+
+from ..config import Config
+from ..driver import PageFacade
+from ..llm import FailureClassification, LLMProvider
+
+#: System prompt of every classification request; used by both engines, applied verbatim.
+CLASSIFICATION_PROMPT = """You classify a failure of a web UI test step.
+
+Input you receive:
+- STEP: the step sentence
+- CODE: the step code that failed
+- ERROR: the failure description
+- PAGE SNAPSHOT: the accessibility snapshot of the current page
+- SCREENSHOT: an image of the page, when attached
+- USER INSTRUCTIONS: the project's binding classification guidance, when configured — follow it; it never overrides the fixed answer format above
+
+Answer with exactly one line of the form:
+category | explanation | recommendation
+
+where category is one of:
+- rot — the UI changed (selectors, texts, structure) and the step can be regenerated for the same intent
+- product_defect — the step works as written but the expected behavior of the application is genuinely broken
+- fixable — the step code is at fault (an ambiguous or wrong locator or strategy) while the intent stays satisfiable; regeneration for the same intent can help
+- incurable — the step sentence no longer matches reality, the intent is ambiguous, or regeneration cannot help
+
+explanation: one short sentence why. recommendation: one short sentence what the engineer should do.
+Output only that single line — no code, no extra text."""
+
+
+def classify_step_failure(  # noqa: PLR0913, PLR0917 — the parameter list is fixed by the engine contract
+    config: Config,
+    provider: LLMProvider,
+    step_text: str,
+    code: str,
+    error: str,
+    page: PageFacade,
+) -> FailureClassification:
+    """Classify a step failure: collect the page state and ask the provider.
+
+    Args:
+        config: project settings; ``send_screenshots`` attaches page images
+            and ``classification_prompt`` supplies the user instructions.
+        provider: the LLM port implementation classifying the failure.
+        step_text: the prepared instruction of the failed step as passed by
+            the calling engine — the code was generated for it; never the
+            raw template sentence, never the casefolded normalization.
+        code: the step code that failed.
+        error: the human-readable failure description.
+        page: the page facade of the current test.
+
+    Returns:
+        The classification verdict.
+
+    Raises:
+        LLMUnavailableError: the provider service failed — propagates
+            untouched, the calling path decides the handling.
+    """
+    snapshot = page.aria_snapshot()
+    screenshot = page.screenshot() if config.send_screenshots else None
+
+    return provider.classify_step_failure(
+        prompt=CLASSIFICATION_PROMPT,
+        user_instructions=config.classification_prompt,
+        step_text=step_text,
+        code=code,
+        error=error,
+        snapshot=snapshot,
+        screenshot=screenshot,
+    )

prettyplay/engine/compliance.py

@@ -0,0 +1,125 @@
+"""The two-dimension compliance gate: instruction compliance and step adequacy of a green candidate."""
+
+from ..config import Config
+from ..llm import ComplianceFinding, LLMProvider
+from .attempts import StepAttempt
+from .renderer import PreparedStep
+
+#: System prompt of every compliance verdict request; used by the engine gate, applied verbatim.
+#: Frozen mirror of the ``compliance_prompt`` practice of the engine CODEMANIFEST —
+#: the single source of the prompt; the constant changes only together with the manifest.
+COMPLIANCE_PROMPT = """You verify generated step code on two dimensions: the project's user instructions and what the step says.
+
+Input you receive:
+- INSTRUCTIONS: the project's user instructions, verbatim
+- STEP TYPE: action or assertion
+- STEP: the prepared instruction of the step — the plain-text sentence with actual values embedded
+- INPUTS: the call input bindings, one name = value line each — present when the step carries inputs
+- RESULTS: the declared result names — present when the step declares captures; the code must return a dictionary of exactly these names to non-blank strings observed on the page
+- ATTEMPT HISTORY: the verbatim record of every attempt of this step so far, when present — the original cached code first when it exists; each record carries the attempt outcome, the URL before -> after line, the complete candidate code and the complete error
+- CODE: the successfully executed candidate code
+
+Check the code on both dimensions and answer with exactly one JSON list of
+findings:
+[{"instruction": "<quote>", "priority": "high|medium|low",
+"explanation": "<one short sentence>", "dimension": "instruction|adequacy"}]
+
+Dimension calibration:
+- instruction — the code violates a project instruction: the quote is the
+  violated instruction
+- adequacy — the code does not match what the step says, given the step
+  type and the attempt history: the quote is the fragment of the step
+  sentence the code fails to accomplish, or — for behavior that exceeds
+  the step — the code line performing it
+
+Priority calibration:
+- high — a confident, material finding evident from the code, the step type
+  and the attempt history; for instruction: a material violation evident
+  from the code itself — the instruction was expressible through the page
+  API the code already uses, and the code plainly skipped or contradicted
+  it without any fallback attempt; for adequacy: an action step whose code
+  contains no action of the step — the page state the code relies on was
+  produced by a prior attempt or manual intervention, not by the code
+  itself, use the URL lines and the records of the history to see it — or
+  material behavior the step never asked for: an assertion step that
+  changes page state (a navigation, a click, a fill), a trailing check in
+  an action step that only confirms the action's own completion, a check
+  of a fact the step sentence never names; only high blocks the candidate
+- medium and low — minor observations, partial compliance or doubt: visible,
+  never blocking; when in doubt, never high
+- an empty list [] means the code complies and accomplishes the step
+
+Rules:
+- The attempt history is your ground truth for what already happened on the
+  page: the candidate ran on a page that may already contain effects of prior
+  attempts or manual intervention — code that only checks an already-achieved
+  state without producing it is an adequacy violation for an action step
+- Adequacy covers both directions: falling short of the step and exceeding
+  it — extra actions inside an assertion step, a trailing confirmation of
+  the action's own completion, extra checks of facts the step sentence
+  never names are adequacy findings too
+- Conditional prefer-type instructions are checked conditionally: when the code shows
+  a graceful fallback attempt, that is compliance; judge followability from the code
+  and the step sentence alone — never speculate about page state beyond the attempt
+  history and the inputs
+- An instruction the code could not follow because the step sentence itself prevents
+  it is not a violation; when the inputs leave the followability in doubt, the finding
+  is never high
+- Judge both dimensions: the code against the instructions, and the code against the
+  step sentence with its type
+- Treat RESULTS as the exact-key return contract: the code must return a dictionary of exactly
+  the declared names to non-blank strings observed on the page — code that cannot produce it
+  is an adequacy finding
+- When INPUTS values influence the step, code that hardcodes their current values instead of
+  reading step_inputs["vars"] cannot replay with new inputs; report a high adequacy finding
+- Output only the JSON list, no other text"""
+
+
+def check_step_compliance(  # noqa: PLR0913, PLR0917 — the parameter list is fixed by the engine contract
+    config: Config,
+    provider: LLMProvider,
+    prepared: PreparedStep,
+    step_type: str,
+    code: str,
+    attempt_history: list[StepAttempt],
+) -> list[ComplianceFinding]:
+    """Gate a successfully executed candidate on the two compliance dimensions.
+
+    Args:
+        config: project settings — ``generation_approve`` is the gate switch
+            and ``generation_prompt`` supplies the checked user instructions.
+        provider: the LLM port implementation returning the verdict.
+        prepared: the render product of the generated step — instruction,
+            input bindings and result declarations; the verdict request
+            renders them as the STEP, INPUTS and RESULTS blocks.
+        step_type: action or assertion — the adequacy dimension judges by it.
+        code: the successfully executed candidate code.
+        attempt_history: the step's attempt history — rendered through the
+            record render and passed to the verdict request as the ATTEMPT
+            HISTORY block.
+
+    Returns:
+        The verdict findings of both dimensions; an empty list — compliant
+        and adequate, or the gate is off. The single check of every caching
+        path — generation, healing and steering alike; never runs on
+        replayed cached code.
+
+    Raises:
+        LLMUnavailableError: the provider service failed after the bounded
+            transport retries; the calling path never caches the candidate.
+        ComplianceVerdictError: the provider answer did not parse into
+            findings; the calling path never caches the candidate.
+    """
+    if not config.generation_approve or not config.generation_prompt:
+        return []  # the gate is off or nothing to check against — zero provider calls
+
+    return provider.check_instruction_compliance(
+        prompt=COMPLIANCE_PROMPT,
+        user_instructions=config.generation_prompt,
+        instruction=prepared.instruction,
+        step_type=step_type,
+        inputs=prepared.inputs,
+        declarations=prepared.declarations,
+        code=code,
+        attempt_history=[record.render() for record in attempt_history],
+    )

prettyplay/engine/execution.py

@@ -0,0 +1,48 @@
+"""Execution of step code of the fixed form through the run primitive of the page handle."""
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+
+from ..driver import PageFacade
+
+_step_inputs: ContextVar[dict[str, object] | None] = ContextVar("prettyplay_step_inputs", default=None)
+
+
+@contextmanager
+def bind_step_inputs(memory: dict[str, str], inputs: dict[str, str]) -> Iterator[None]:
+    """Expose this execution's current bindings to generated code without changing its page argument."""
+    token = _step_inputs.set({**memory, "vars": dict(inputs)})
+    try:
+        yield
+    finally:
+        _step_inputs.reset(token)
+
+
+def run_step_code(code: str, page: PageFacade) -> dict[str, str] | None:
+    """Execute step code of the fixed form against the page handle of the test.
+
+    Args:
+        code: the step code text produced by generation or loaded from the
+            cache — compiled and resolved on the calling thread, Playwright
+            untouched.
+        page: the page handle of the current test — the whole step call
+            crosses the worker boundary as one unit, the step receives the
+            genuine sync Page.
+
+    Returns:
+        The step function's return as-is — the dictionary of declared names
+        to observed strings for a step with declarations, None for a
+        declaration-free step; plain data only.
+
+    Raises:
+        Exception: whatever the step code raises propagates as-is — never
+            swallowed, translated or retried here; the engine classifies it.
+    """
+    namespace: dict[str, object] = {"step_inputs": _step_inputs.get() or {}}
+    # the engine contract: compile and resolve on the calling thread, Playwright untouched
+    exec(compile(code, "<prettyplay-step>", "exec"), namespace)
+
+    step_fn = namespace["step"]
+    # the engine contract: one worker unit — the whole step against the genuine sync Page
+    return page.run(step_fn)