# Blueprint — empirical verification for AI-built LiveView interactions

AI skills, code review rules, and component playbooks reduce the chance of an
ownership mistake. They do not prove what a real browser does when a real LiveView
patch lands. This project closes that gap with a generation-to-evidence loop:

```text
AI/Developer writes component + interaction contract
                         |
                         v
              real LiveView + real browser
          activate -> patch -> observe -> diagnose
                         |
                         v
                  CI evidence artifact
```

## Final product

The final product is a **LiveView Interaction Conformance Kit**, not primarily a UI
library. It has six layers:

1. **Calibration kernel** — this repository's multi-browser, multi-LiveView-version
   fixtures, Aha trial, red controls, and delegation ledger establish known behavior.
2. **Portable consumer contracts** — versioned declarative files describe a route,
   activation, an acknowledged patch, native probes, and before/after expectations.
3. **Browser execution engine** — a strict phase machine drives the consumer's real
   app and records patch proof, DOM object identity, and native state independently.
4. **Evidence and diagnostics** — results distinguish `pass`, `fail`, `inconclusive`,
   and infrastructure `error`; explanations are mechanically derived from evidence.
5. **Developer integration** — Mix tasks, JSON artifacts, terminal output, and CI
   browser/version matrices make the contracts part of normal application delivery.
6. **Compatibility knowledge** — only after the result schema stabilizes may
   app-specific evidence feed a broader, versioned ecosystem ledger.

The bundled research ledger and consumer-app evidence remain separate until their
semantics genuinely align.

## Consumer contract v1

The first public slice deliberately supports one interaction transaction:

```text
visit route
  -> real click activation
  -> verify before-state
  -> retain the subject DOM object
  -> read patch-ack attribute
  -> real click patch trigger
  -> wait for the subject-local attribute to change
  -> read the new DOM object and native state
  -> compare and report
```

Supported probes are `node_identity`, `popover`, `dialog`, and `focus`. Contracts are
strict JSON: unknown fields, unknown probes, arbitrary JavaScript, timer sleeps, and
non-local targets are rejected. A patch that is not acknowledged is **inconclusive**,
not a component failure and never a pass.

Example:

```json
{
  "schema_version": 1,
  "id": "account-menu-survives-refresh",
  "route": "/settings",
  "subject": {"selector": "#account-menu"},
  "activate": [
    {"type": "click", "selector": "#account-menu-trigger"}
  ],
  "patch": {
    "trigger": {"type": "click", "selector": "#refresh-account"},
    "ack": {
      "type": "attribute_change",
      "selector": "#account-menu",
      "attribute": "data-contract-rev"
    }
  },
  "expectations": [
    {"probe": "node_identity", "after": "same"},
    {"probe": "popover", "before": {"open": true}, "after": {"open": true}},
    {
      "probe": "focus",
      "selector": "#account-menu-trigger",
      "before": {"active": true},
      "after": {"active": true}
    }
  ]
}
```

Run it against an already-started local app:

```sh
mix live_interaction_contracts.check \
  --url http://127.0.0.1:4000 \
  --contract test/interaction_contracts/account_menu.json
```

## Evidence rules

- **Patch proof:** the acknowledgment element must be the subject or its descendant,
  and its named attribute must change after the trigger.
- **Identity:** same selector/ID is not enough; the pre-patch and post-patch DOM object
  references are compared directly.
- **Coherence:** native probes expose complete relevant vectors. Dialog means
  `open`, reflected `open` attribute, and `:modal`, not a generic open boolean.
- **Verdicts:** expectation mismatch after an acknowledged patch is `fail`; failed
  activation/preconditions or missing acknowledgment is `inconclusive`; malformed
  contracts, navigation, and browser failures are `error`.
- **Artifacts:** every result records contract, runner, Playwright, browser, target,
  patch acknowledgment, raw observations, diagnostics, and final verdict.

## Roadmap

### Milestone 1 — external-app vertical slice

- `mix live_interaction_contracts.check`
- strict JSON contract v1
- Chromium default, one fresh context, one run
- click activation/patch and subject-local attribute-change acknowledgment
- node identity, popover, dialog, and focus probes
- atomic JSON result plus human terminal report
- loopback-only by default

### Milestone 2 — practical interaction coverage

- input value/selection, scroll, and `aria-activedescendant` probes
- `fill`, `press`, and composition-safe actions
- Firefox/WebKit CI expansion and optional deterministic repeat
- reusable Phoenix test helpers for rendering acknowledgment revisions

### Milestone 3 — interaction continuity

- insert patches between pointer/key/composition event phases
- detect duplicate activation, stale listeners, hook remount, and focus handoff
- reconnect and async-result ordering contracts
- Playwright traces only as opt-in failure evidence

### Milestone 4 — AI verification loop

- a skill generates component code **and** a contract
- the agent runs the contract, reads structured diagnostics, and proposes a fix
- a fix is accepted only when the same empirical contract passes
- contract changes are reviewed like API changes; an agent may not weaken an
  expectation merely to manufacture green

### Milestone 5 — ecosystem evidence

- consumer-provided LiveView/app version metadata
- version-upgrade comparisons for consumer contracts
- opt-in aggregation across component patterns and libraries
- real assistive-technology and CJK IME evidence remain separately labelled

## Explicit non-goals for v1

- no arbitrary JavaScript in contracts
- no sleep-based patch completion
- no automatic application startup or port killing
- no credentials, recorded browser profiles, or production targets by default
- no AI auto-fix before raw evidence is available
- no claim that same DOM node implies a coherent interaction machine
- no merging consumer results into the research ledger yet