first commit

docs/testkit/testing/testing-dom/src/errors/codes.md

@@ -0,0 +1,66 @@
+# 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).