# Helixwright 1.0 Production Patterns

All examples target Browser RPC protocol `6`, core contract `0075`, and the
namespaced 1.0 public surface.

## Launch, inspect, and close

```python
import helixwright as hw

with hw.launch("https://example.com", name="example") as page:
    page.locator("body").wait(timeout_ms=10_000)
    print(page.url, page.title())
    print(page.rpc_endpoint_path, page.rpc_info["contract_hash"])
```

## Atomic slow-component action

```python
ready = hw.ReadinessContract(
    all_of=(
        hw.ReadinessSignal.attribute(
            "#continue", "data-hydrated", equals="true"
        ),
    ),
    stable_frames=3,
    quiet_ms=100,
)

effect = page.get_by_role("button", name="Continue").click(
    ready=ready,
    timeout_ms=20_000,
)
assert effect.ok
assert effect.dispatch_phase == "completed"
assert effect.receipt_confirmed
assert effect.receipt.action_id == effect.action_id
```

## Idempotent form completion

```python
def fill_if_needed(locator, value):
    if locator.input_value(timeout_ms=5_000) != value:
        effect = locator.fill(value, timeout_ms=15_000)
        assert effect.receipt_confirmed
    if locator.input_value(timeout_ms=5_000) != value:
        raise RuntimeError("field verification failed")

fill_if_needed(page.get_by_label("Full name"), "Example User")
fill_if_needed(page.get_by_label("Email"), "user@example.test")

terms = page.get_by_label("Accept terms")
if not terms.checked():
    effect = terms.click()
    assert effect.receipt_confirmed
if not terms.checked():
    raise RuntimeError("terms verification failed")
```

Verify every required field before submit. Do not assume a prior fill succeeded.

## iframe/OOPIF form

```python
payment = page.frame("iframe#payment")

card = payment.get_by_label("Card number")
if card.input_value() != "4111111111111111":
    card.fill("4111111111111111")

effect = payment.get_by_role("button", name="Pay").click(
    ready=hw.ReadinessContract(
        all_of=(
            hw.ReadinessSignal.attribute(
                "role=button@@name:Pay", "data-ready", equals="true"
            ),
        ),
        stable_frames=3,
    )
)
assert effect.receipt_confirmed
```

## Network-correlated action

```python
with page.network.expect_response(
    {"url": "https://api.example.test/order", "status": 200},
    timeout_ms=20_000,
) as response:
    effect = page.get_by_role("button", name="Submit order").click(
        ready=submit_ready
    )

assert effect.receipt_confirmed
print(response.value)
```

`expect_response` opens its private event cursor before the action. A callable action
may also be passed directly when a context manager is not desired.

## Full-fidelity response body

```python
page.network.listen()
event = page.network.wait_for_response("/api/order", timeout_ms=20_000)

body_id = event.get("body_id")
raw = page.network.bytes(event["url"], body_id)
headers = page.network.headers_raw(event["url"], body_id)
payload = page.network.json(event["url"])
```

`headers_raw()` preserves duplicate order; `bytes()` verifies complete body size and
SHA-256 before returning data.

## Popup/tab

```python
with page.tabs.expect(timeout_ms=15_000) as popup:
    effect = page.get_by_role("link", name="Open portal").click()

assert effect.receipt_confirmed
target = popup.value
page.tabs.switch(target["target_id"])
print(page.url)
```

## Download

```python
with page.downloads.expect(timeout_ms=30_000) as download:
    effect = page.get_by_role("button", name="Export").click()

assert effect.receipt_confirmed
print(download.value)
```

## Dialog policy

```python
page.dialogs.accept(prompt_text="confirmed")
effect = page.get_by_role("button", name="Open prompt").click()
page.dialogs.off()
```

The policy is declarative and installed before the triggering action.

## Balanced slider gesture

```python
slider_ready = hw.ReadinessContract(
    all_of=(
        hw.ReadinessSignal.attribute(
            "#slider", "data-initialized", equals="true"
        ),
    ),
    stable_frames=3,
    quiet_ms=100,
)

# Use the locator transaction when source and target are elements.
effect = page.locator("#handle").drag_to(
    page.locator("#slider-end"),
    ready=slider_ready,
    timeout_ms=20_000,
)
assert effect.receipt_confirmed
```

For an interface whose contract is an explicit coordinate path:

```python
gesture = page.input.gesture(timeout_ms=20_000)
gesture.move(300, 420).down().pause(120).move(680, 420, duration_ms=1800).up()
effect = gesture.commit()
assert effect.receipt_confirmed
assert effect.receipt.as_dict()["pointer_continuity_ok"] is True
```

## Strict statechart

```python
def submit(ctx):
    return ctx.scope.locator("#submit").click(ready=ctx.ready)

machine = hw.StateMachine(
    [
        hw.State(
            "form",
            match=hw.Signature(
                require_selectors=["#form", "#submit"],
                absent_selectors=["#complete", "#server-error"],
            ),
            ready=hw.ReadinessContract(
                all_of=(
                    hw.ReadinessSignal.element_state("#submit", "enabled"),
                ),
                quiet_ms=100,
            ),
            handler=submit,
            expect=hw.OutcomeContract(
                success_states=["done"],
                branch_states=["server_error"],
                progress=[hw.signals.DomChanged()],
                no_effect="report",
            ),
        ),
        hw.State(
            "server_error",
            match=hw.Signature(require_selectors=["#server-error"]),
            terminal=True,
        ),
        hw.State(
            "done",
            match=hw.Signature(require_selectors=["#complete"]),
            terminal=True,
        ),
    ],
    name="submit_flow",
)

result = machine.run(
    page,
    max_transitions=8,
    deadline_ms=120_000,
    failure_dir="evidence/state-failures",
)
```

## Persistent private authoring

```powershell
$run = "evidence\checkout-authoring"
python -m helixwright author start --url "https://shop.example/checkout" --run-dir $run
python -m helixwright author exec --run-dir $run --command-id inspect-001 --code "page.probe.forms()"
python -m helixwright author checkpoint --run-dir $run --label "checkout"
python -m helixwright author stop --run-dir $run
```

The same browser stays alive for incremental debugging. Evidence retains complete raw
private values under an owner-only boundary and is not automatically uploaded.

## Flow IR validation

```python
flow = hw.expert.FlowIR.load(
    "evidence/AUTOMATION_FLOW.json"
).require_valid()

assert flow.sdk_version == "1.0.0"
assert flow.core_contract == "0075"
print(flow.run_id, flow.trace_id, flow.terminal_states)
```

The production bundle must causally bind readiness, action id, final dispatch phase,
receipt, outcome, transition, and Trace window. A screenshot or passing final URL alone
is not sufficient evidence.