# codes

## Purpose

`TESTING_DOM_CODES` is the package-local error code registry for `@suaveplan/testing-dom`. All codes share the `TESTING_DOM.` namespace so consumers can match on the prefix to spot testing-library failures in aggregated logs. The registry is hand-built here rather than going through `defineCodes` from `@suaveplan/error` because this package has zero `@suaveplan/*` deps by design.

## Features

- Frozen record of `TESTING_DOM.*` code strings
- `TestingDomCode` type alias for the discriminated union
- Stable — new codes append; removal requires a deprecation cycle
- Structural twin of the `defineCodes` output used by Layer 1 packages

## Usage: Basic Example

```ts
import { TESTING_DOM_CODES } from "@suaveplan/testing-dom";

TESTING_DOM_CODES.RENDER_FAILED; // "TESTING_DOM.RENDER.FAILED"
```

## Usage: Advanced Example

```ts
import {
    TestingDomError,
    TESTING_DOM_CODES,
    type TestingDomCode,
} from "@suaveplan/testing-dom";

function classify(err: TestingDomError): "retry" | "fail" {
    switch (err.code) {
        case TESTING_DOM_CODES.USER_EVENT_INIT_FAILED:
            return "retry";
        case TESTING_DOM_CODES.RENDER_FAILED:
        case TESTING_DOM_CODES.QUERY_FAILED:
            return "fail";
    }
}

function isTestingDomError(err: unknown): err is TestingDomError {
    return err instanceof TestingDomError;
}
```

## API Reference

### `TESTING_DOM_CODES`

Frozen record of reason → fully-qualified code string.

### `type TestingDomCode`

Union of every `TESTING_DOM_CODES[K]` value.

## Implementation Notes

The runtime record is built by hand (`Object.freeze({ ... })`) rather than via `defineCodes` to maintain the zero-workspace-dep constraint. Adding a new code: append to the record, append to the union type, and keep existing entries unchanged. The package's own test suite verifies that every entry carries a `TESTING_DOM.` prefix and that no two entries share a value.

### Registry Layout

Codes live under the `TESTING.DOM` namespace and are produced by `defineCodes` — same pattern as every other Suaveplan package. Current codes cover render host mount failures, query helper missing-element errors, matcher setup failures, and polyfill double-install attempts. The `TestingDomCode` union is the canonical parameter type for catch blocks and error-helper signatures.

### Stability

Adding a new code is append-only: no renumbering, no migrations. Consumers that type-narrow on `code` get a compile error when a new code is added without a matching branch only if they use the `TestingDomCode` union exhaustively (e.g. in a `switch` with `never` check).