first commit

docs/ui/react/react-ui/src/pack/version-check/version-check.md

@@ -0,0 +1,66 @@
+# `version-check` — pack peerRange satisfier
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Pure helper that asks `semver.satisfies(reactUiVersion, peerRange)` so
+the chassis can decide whether a pack's declared `peerRange` is
+satisfied by the running `@suaveplan/react-ui` version. The function
+catches semver parse failures and returns `false` so a malformed range
+is treated as a mismatch (the pack is still registered but a warning
+fires).
+
+## Features
+
+- Uses `semver.satisfies` with `includePrerelease: true` so an
+  in-flight `0.0.0-canary.1` build still matches `^0.1.0`-shaped
+  ranges
+- Returns `false` on parser failure — never throws
+- Pure / synchronous; safe to call in any context
+
+## Usage: Basic example
+
+```ts
+import { satisfiesPeerRange } from "@suaveplan/react-ui/pack";
+
+const ok = satisfiesPeerRange({
+    reactUiVersion: "0.1.0",
+    peerRange: "^0.1.0",
+});
+```
+
+## Usage: Advanced example
+
+```ts
+import { satisfiesPeerRange } from "@suaveplan/react-ui/pack";
+import { REACT_UI_VERSION } from "@suaveplan/react-ui/version";
+
+function gate(packPeerRange: string): "ok" | "warn" {
+    return satisfiesPeerRange({
+        reactUiVersion: REACT_UI_VERSION,
+        peerRange: packPeerRange,
+    })
+        ? "ok"
+        : "warn";
+}
+```
+
+## API Reference
+
+- `satisfiesPeerRange(input: { reactUiVersion: string; peerRange: string }): boolean`
+  - Returns `true` when the version satisfies the range
+  - Returns `false` when the version does not satisfy or the range
+    fails to parse
+
+## Implementation notes
+
+The helper deliberately swallows parse errors rather than re-throwing
+because the caller (the chassis pack-registry provider) needs a binary
+"is this satisfied?" answer at register time. The
+`includePrerelease: true` flag keeps in-flight chassis dev builds
+working with realistic peer ranges; production releases pinned to
+exact versions still satisfy a `^X.Y.Z` range. The helper imports the
+`semver` library statically so tree-shaking does not strip it from the
+bundle.