coatcheck 0.2.1

Contracts and a Playwright accessibility runner for Topcoat component workbenches.
Documentation
# Coatcheck

Coatcheck is a component workbench contract and semantic browser-test runner
for [Topcoat](https://github.com/tokio-rs/topcoat).

The library models stories, typed props, controls, scenes, manifests, and
isolated frames. The installable `coatcheck` binary turns a host manifest into
explicit Playwright and Axe tests. It produces screenshots for review, but it
does not store or compare pixel baselines.

## Install

After the 0.2 release is available from crates.io:

```sh
cargo install coatcheck --locked
```

From a local checkout:

```sh
cargo install --path . --locked
```

The crate package includes `Cargo.lock` and every runtime scaffold template,
so the locked install does not depend on repository-only files.

## Start a project

From the project that hosts the Topcoat workbench:

```sh
coatcheck init --package-manager bun
```

`init` writes:

- `Coatcheck.toml`;
- a private `package.json` when the project does not already have one;
- `coatcheck/example.spec.ts`;
- a `.coatcheck/` ignore entry;
- exact project-local `@playwright/test` and `@axe-core/playwright`
  development dependencies;
- Playwright Chromium.

It does not replace an existing JavaScript package manifest. Use
`--skip-install` when scaffolding offline.

## Configure the host

```toml
version = 1
name = "Cold Front"

[host]
command = ["topcoat", "dev"]
url = "http://127.0.0.1:3000"
health = "/health"
manifest = "/__coatcheck/manifest.json"
startup_timeout_seconds = 30

[test]
story_globs = ["coatcheck/**/*.spec.ts"]
artifacts = ".coatcheck/artifacts"
timeout_ms = 30000
axe_impacts = ["serious", "critical"]
```

`host.command` is an argument array and is executed directly, without a shell.
The generated configuration uses `topcoat dev` so asset bundles and live reload
behave exactly as they do during application development.
This keeps quoting deterministic and makes the process boundary explicit.

## Commands

```sh
coatcheck doctor
coatcheck doctor --fix
coatcheck dev
coatcheck test
coatcheck test --no-host
coatcheck test --headed
coatcheck test --headed --story route-option --slow-mo 150
```

- `doctor` validates configuration, Bun, project-local Playwright and Axe,
  Chromium, and reports whether the host is reachable.
- `doctor --fix` installs or repairs the JavaScript dependencies and Chromium.
- `dev` runs `host.command` in the foreground.
- `test` starts the host, waits for health, fetches the manifest, generates
  explicit tests under `.coatcheck/generated`, runs generated and custom
  specs, and stops the host.
- `test --no-host` uses an already-running host.

The generated semantic gate checks navigation, frame root/readiness/error
markers, uncaught page and console errors, and the configured Axe impacts.
Each case writes a PNG, DOM, Axe JSON, and console JSON. Playwright also writes
HTML, JSON, and failure traces. See [the runner contract](docs/runner.md).

## Host API

Versioned JSON and frame types are additive to the 0.1 static catalog:

```rust
use coatcheck::{
    Catalog,
    contract::{FrameContractV1, ManifestV1},
};

fn manifest(catalog: Catalog) -> ManifestV1 {
    ManifestV1::from_catalog(catalog, FrameContractV1::default())
}
```

The default host endpoints are:

```text
GET /__coatcheck/manifest.json
GET /__coatcheck/frame?story=<story-id>&scene=<scene-id>
```

The manifest owns the actual frame path, query names, and DOM selectors.
Detailed producer/consumer requirements are in
[the host contract](docs/contracts.md).

## Static catalog API

The allocation-free 0.1 API remains available:

```rust
use coatcheck::{ArgType, Catalog, ControlKind, Story, StoryKind};

const LABEL: ArgType = ArgType {
    name: "label",
    type_name: "String",
    control: ControlKind::Text,
    default_value: "Continue",
    description: "Visible action copy.",
    options: &[],
};

const STORIES: &[Story] = &[Story {
    id: "action-link",
    title: "Action link",
    tier: "Atoms",
    kind: StoryKind::Playground,
    description: "A navigational action.",
    source: "src/atoms.rs",
    args: &[LABEL],
}];

const CATALOG: Catalog = Catalog::new("Example", STORIES);

assert!(CATALOG.validate().is_ok());
```

## Repository navigation

Every tracked, human-maintained folder is linked here:

- [`.github/`].github/ — automation documentation.
- [`.github/workflows/`].github/workflows/ — CI and locked-install smoke
  checks.
- [`docs/`]docs/ — host and runner coordination contracts.
- [`src/`]src/ — library contracts, config, generation, and CLI.
- [`templates/`]templates/ — files embedded in the installable binary.
- [`tests/`]tests/ — process-level CLI integration tests.

## Status

Coatcheck is experimental and tracks Topcoat’s early-stage development.
Manifest and frame versions are explicit so future schemas can be added
without changing the 0.1 static story model.

## License

MIT