themelia-ui 3.0.0 → 3.2.0

package/docs/learn/verification.md

@@ -32,8 +32,9 @@ test("global search returns focus after dismissal", async ({ page }) => {
 Prefer role- and name-based assertions over CSS Module selectors. When a visual or state
 assertion needs a DOM hook, use `data-slot`, documented BEM hooks, or the state attributes
 the primitives set (`data-open`, `data-checked`, `data-disabled`, `data-highlighted`,
-`data-popup-open`). These are Base UI's attributes, not Radix's: `[data-state="open"]`
-matches nothing.
+`data-popup-open`). Use Base UI's documented attributes for its primitive states rather
+than assuming Radix's `[data-state="open"]`. Some kit modules expose their own `data-state`
+contract; use it only where the selected API documents it.
 
 ## Theme contract check
 
@@ -41,11 +42,65 @@ Create one application fixture that changes primary colour, surface/background r
 radius, density, and typography scale at a scope boundary. If a component ignores it, report
 the module and token before adding a local patch: the package may be missing a derivation.
 
+## Offline diagnosis and skill freshness
+
+Run the commands from the package installed in this application:
+
+```bash
+node node_modules/themelia-ui/scripts/consumer/install-skill.mjs --project=. --check --json
+node node_modules/themelia-ui/scripts/consumer/diagnose.mjs --project=. --json src/
+```
+
+Both checks are read-only. Diagnostics use the consumer's installed TypeScript parser and
+the package's generated export/migration facts. Supply explicit paths. Unsupported formats,
+parse failures, missing paths, metadata or parser produce exit 2 (incomplete); definite
+contract errors produce exit 1; complete checks without errors produce exit 0. Advisory
+composition/private-style warnings do not establish a defect. Excluded build/dependency
+directories and symlinks are not followed. Reports name the checked and skipped rules/files.
+
+Freshness reports expected and installed versions plus missing, stale, modified or unmanaged
+copies. Review modifications before reinstalling a generated copy. The installer refuses local edits
+until `--overwrite-modified` explicitly replaces reviewed generated content. Keep application policy
+in a separate skill; an unmanaged same-name skill is preserved. Missing metadata requires
+repairing the package installation or consulting the matching release, never inventing an API.
+
+If an installed copy's manifest is missing or invalid, the installer repairs it automatically
+only when its remaining files match the packaged content. Differing or extra files require
+review and `--overwrite-modified`, just like edits to a copy with a valid manifest.
+
+Replacements are staged before writes, and caught write failures restore backups. An abrupt
+process termination can leave mixed versions across targets and sibling `.backup-*` or
+`.installing-*` directories. Run `--check`, review those retained directories, preserve any
+local policy, and reinstall the intended generated copies. A backup-cleanup error means the
+new copies were installed; the error names the retained backup for review and manual cleanup.
+
+The [browser observer](../build/browser-composition-fixture.ts) accepts an already open caller
+fixture and observes overflow, repeated sibling headings and control visibility. It performs
+no navigation, click or submission. These geometry/semantic observations are advisory; they
+do not establish accessibility or business acceptance. Optional browser tooling belongs in
+the application's test dependencies, not the UI runtime.
+
+Opt into interaction tests only against explicit mock actions. The [complete workflows](./reference-workflows.md)
+provide scoped late responses, pending/empty/error lists, nested cancel, resolved validation,
+workspace selection and retained locale drafts. Assert keyboard selection without accidental
+form submission, one Escape layer at a time, focus return, associated errors and explicit
+successful completion. Do not crawl unknown application routes or submit business forms.
+
+## Completion record
+
+Record installed package/skill versions; selected owners and seams; shared callers inspected;
+fixture routes and states; viewport widths; themes, densities and locales; keyboard/focus
+interactions; commands and observed results. Separate type/build evidence, behavior tests,
+visual inspection and application acceptance. Name unavailable conditions explicitly.
+
+When no browser is available, report types/build/static findings and mark interaction and
+visual checks unverified. Passing named static/browser checks does not establish permissions,
+data integrity, persistence, backend sanitization or every product workflow.
+
 ## Upgrade check
 
 Read the [changelog](../../CHANGELOG.md), run the package's codemod when a release names one
 (`node node_modules/themelia-ui/scripts/consumer/codemod.mjs --dry-run src/`), and let the
-application's own type-check compare the installed declarations. Within a major, a removal
-keeps a deprecated alias until the next major unless keeping it would be unsafe or
-incorrect; a major may remove names outright, and its migration guide lists each one. See
+application's own type-check compare the installed declarations. Removed names have no
+compatibility alias in 3.1; its migration guide lists each replacement. See
 [API compatibility](./api-compatibility.md).