# Local extension contract

## Required imports

Load `assets/reference.css`, then `assets/fidelity.css`. The latter contains
the measured heading, grid, mobile, and dark-family corrections. Benchmark report
pages also load `assets/reports.css` and `assets/reports.js`. Keep
`assets/reference.js` for shared local fixture behavior. The generated HTML in
`examples/` shows the exact order. Copying the base stylesheet alone is incomplete.

On a narrow Speech report, the language selector chooses one metric beside the model
column. All 15 rows remain available, and sorting acts on the visible metric. The
Real-SWE task selector chooses a mobile card with eight models and eight outcome squares
per model. The squares represent captured aggregate counts, not the original trial
sequence. Desktop tables retain the complete captured data.

This contract governs additions to this static research reference. It does not describe
Specific Labs' private application, permissions, storage, or upload service.

## Choose the right boundary

Use the ten primary public routes and the independent inventory as the design context.
New local components and states are permitted when marked as original additions.
Unobserved private service behavior is excluded, not something an implementer must guess.
Do not add claims about real permissions, payments, retention, offline durability, or
conflict resolution. A production integration needs a separate authorized contract.

## Shared implementation rules

- Reuse the recipe shell, named spacing tokens, native form elements, labels, and focus
  treatment from `assets/reference.css` and the matching family specimen.
- For a new pattern, record anatomy, inputs, events, states, content limits, responsive
  behavior, accessibility, provenance, and two distinct composition contexts.
- Page code owns fixture values and status. A child control owns only its local open,
  pressed, or selected state. Keep state in page memory, with no persistence or network.
- Put plain status text in an existing `data-status` region or a new `role="status"`
  region after the affected control. Use `textContent`, never HTML from user values.
- Keep focus on an activating button while reporting progress. On invalid submission,
  focus the first invalid field. On dialog close, restore focus to the opening control.

## Cross-cutting local cases

An extension can exercise loading, empty, error, narrow layouts, long translated text,
and keyboard accessibility without inventing a private service. A deterministic fixture
may take a local `success`, `empty`, or `error` outcome and a bounded delay as inputs.
Label that selector as reference-only. Make the initial state `idle`; activation changes
it to `loading`, then the selected outcome. Ignore duplicate activation while loading.

An error must preserve entered fixture values and explain how to retry. Retry returns to
`loading` and uses the current local outcome setting. Empty is not success and needs its
own readable message. All status changes must remain understandable without color.
This specifies browser behavior only. It promises no actual request or durable retry.

## Acceptance

Verify both pointer and keyboard activation, exact before/after states, focus ownership,
status announcements in the accessibility tree, and no outbound mutation requests.
Check 390px and 1440px widths, plus a 320px reflow stress case. Use long labels and
two-line messages without clipping. Test errors and recovery, not just the happy path.
Record commands, exit codes, screenshots, changed files, source records, and any
consequential question within this local boundary. Production-only unknowns belong in
the exclusion list rather than the local acceptance result.