@mythicalos/react-ui 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work, excluding
+          those notices that do not pertain to any part of the Derivative
+          Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do
+          not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 mythicalOS
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,5 @@
+mythical-ui (@mythicalos/ui-core, @mythicalos/preact-ui, @mythicalos/react-ui, @mythicalos/shell)
+Copyright 2026 mythicalOS
+
+This product includes software developed by mythicalOS
+(https://github.com/mythicalOS).

package/README.md

@@ -0,0 +1,78 @@
+# @mythicalos/react-ui
+
+The mythicalOS **thin React bindings** over `@mythicalos/ui-core` — the executable component
+layer's React half. Apache-2.0.
+
+## The thin-binding principle
+
+This package is render + framework wiring **only**. Every class string, poll-scheduling policy,
+glyph map, typed-name-match decision, and toast text composition is derived by
+`@mythicalos/ui-core`'s pure, framework-agnostic logic — this package never re-implements any of
+it. A sibling `@mythicalos/preact-ui` binding renders the exact same markup from the exact same core
+functions, so the two frameworks can never drift apart. Genuine React — no `preact/compat`.
+
+`react`/`react-dom` are peer dependencies (the consuming app supplies the single instance); so is
+`@mythicalos/tokens` (optional — only needed if you're not already loading it another way).
+
+## Install
+
+```sh
+npm add @mythicalos/react-ui react react-dom
+```
+
+## Import
+
+```tsx
+import { Button, ToastProvider } from "@mythicalos/react-ui";
+
+// serve, in order:
+import "@mythicalos/tokens/tokens.css";
+import "@mythicalos/ui-core/styles.css"; // this package ships NO CSS of its own
+```
+
+## Exports
+
+- `Button` — 5 variants × 6 states, loading spinner, inert+aria-busy.
+- `Input`, `Toggle`, `Checkbox` — inputs with the "unconfigured is a valid state" neutral empty.
+- `MaskedSecretInput` — presence-only secret slots; the value never round-trips to the UI.
+- `EmptyState` — the designed empty moments (spine motif; never an error tone).
+- `ConfirmDialog` (+ `typedNameMatches`), `Scrim` — modal danger confirms (Esc cancels, safe action
+  focused first, optional typed-name-match gate for irreversible deletes).
+- `Toast`, `ToastProvider`, `composeToastText`, `ToastContext`, `useToast` — the toast bus.
+- `usePoll`, `useInterval`, `shouldResetEpoch` — the request/response poll hooks.
+- `Chip`, `Card`, `Avatar`, `StatusLine`, `SearchInput`, `Banner`, `Gauge` — the 7 atoms graduated
+  from design-export's proposed additions.
+- Public types: every `*Props` type, the tone/variant enums (`BtnVariant`/`BtnState`, `ChipTone`,
+  `StatusTone`, `BannerTone`, `Tone`, `DialogBullet`, `ToastStatus`/`ToastSpec`/`ToastBus`), and the
+  hook contracts (`PollResult`, `PollEpochGuard`, `PollTickIO`, `GaugeGeom`).
+- Re-exported core support API — so a consumer can import everything it needs from this one
+  package: `buttonClass`, `typedNameMatches`, `BULLET_ICON`, `composeToastText`, `TOAST_SEP`,
+  `chipClass`, `statusLineClass`, `bannerClass`, `BANNER_ICON`, `gaugeTone`, `gaugeGeom`,
+  `nextPollDelay`, `makePollEpochGuard`, `runPollTick`, `POLL_JITTER_RATIO`, `POLL_BACKOFF_CAP_MS`.
+
+## Parity with the Preact sibling
+
+`@mythicalos/react-ui` mirrors `@mythicalos/preact-ui`'s export surface name-for-name — same
+components, same hooks, same re-exported core symbols, same `*Props` type names. Two small,
+deliberate API deltas from porting Preact idioms to idiomatic React (documented in full in each
+component's header comment):
+
+- `Chip`/`Card`/`Avatar`'s passthrough class prop is `className` here, not `class` — the one
+  intentional public-prop rename, because `className` is what every React consumer reaches for.
+- `Input`/`SearchInput` keep the Preact binding's `onInput` prop **name** (so switching bindings
+  doesn't rename props at every call site) but wire it internally to React's `onChange` — which
+  fires on the same "every keystroke" cadence as the native `input` event Preact's `onInput`
+  listens to, so behavior matches, only the DOM event name under the hood differs.
+
+Every class string either binding renders is produced by the exact same `@mythicalos/ui-core`
+function call — the two bindings cannot silently drift apart.
+
+## Styles
+
+This package ships **no stylesheet**. Serve `@mythicalos/ui-core/styles.css` (after
+`@mythicalos/tokens`) — it carries every class this package's components emit, including the 7
+atoms (`.my-chip`, `.my-status`, `.my-card`, `.my-avatar`, `.my-search`, `.my-banner`, `.my-gauge`).
+
+## License
+
+Apache-2.0.

package/dist/Avatar.d.ts

@@ -0,0 +1,5 @@
+export interface AvatarProps {
+    initials: string;
+    className?: string;
+}
+export declare function Avatar(props: AvatarProps): import("react").JSX.Element;

package/dist/Avatar.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+export function Avatar(props) {
+    const { initials, className: cls = "" } = props;
+    return _jsx("span", { className: `my-avatar__initials ${cls}`, children: initials });
+}

package/dist/Banner.d.ts

@@ -0,0 +1,10 @@
+import type { ReactNode } from "react";
+import { bannerClass, BANNER_ICON, type BannerTone } from "@mythicalos/ui-core/logic";
+export { bannerClass, BANNER_ICON, type BannerTone };
+export interface BannerProps {
+    tone?: BannerTone;
+    glyph?: string;
+    action?: ReactNode;
+    children?: ReactNode;
+}
+export declare function Banner(props: BannerProps): import("react").JSX.Element;

package/dist/Banner.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { bannerClass, BANNER_ICON } from "@mythicalos/ui-core/logic";
+export { bannerClass, BANNER_ICON };
+export function Banner(props) {
+    const { tone = "info", glyph, action, children } = props;
+    return (_jsxs("div", { className: bannerClass(tone), children: [_jsx("span", { className: "my-banner__glyph", children: glyph ?? BANNER_ICON[tone] }), _jsx("span", { children: children }), action] }));
+}

package/dist/Button.d.ts

@@ -0,0 +1,14 @@
+import type { MouseEvent, ReactNode } from "react";
+import { buttonClass, type BtnVariant, type BtnState } from "@mythicalos/ui-core/logic";
+export { buttonClass, type BtnVariant, type BtnState };
+export interface ButtonProps {
+    variant?: BtnVariant;
+    loading?: boolean;
+    disabled?: boolean;
+    small?: boolean;
+    type?: "button" | "submit";
+    title?: string;
+    onClick?: (e: MouseEvent<HTMLButtonElement>) => void;
+    children?: ReactNode;
+}
+export declare function Button(props: ButtonProps): import("react").JSX.Element;

package/dist/Button.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { buttonClass } from "@mythicalos/ui-core/logic";
+export { buttonClass };
+export function Button(props) {
+    const { variant = "sec", loading = false, disabled = false, small = false } = props;
+    const inert = disabled || loading;
+    return (_jsxs("button", { type: props.type ?? "button", className: buttonClass(variant, { loading, disabled, small }), disabled: inert, "aria-busy": loading ? "true" : undefined, title: props.title, onClick: inert ? undefined : props.onClick, children: [loading ? _jsx("span", { className: "spin", "aria-hidden": "true" }) : null, props.children] }));
+}

package/dist/Card.d.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from "react";
+export interface CardProps {
+    title?: string;
+    flush?: boolean;
+    className?: string;
+    children?: ReactNode;
+}
+export declare function Card(props: CardProps): import("react").JSX.Element;

package/dist/Card.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function Card(props) {
+    const { title, flush = false, className: cls = "", children } = props;
+    return (_jsxs("section", { className: `my-card${flush ? " my-card--flush" : ""} ${cls}`, children: [title ? _jsx("h3", { className: "my-card__title", children: title }) : null, children] }));
+}

package/dist/Chip.d.ts

@@ -0,0 +1,9 @@
+import type { ReactNode } from "react";
+import { chipClass, type ChipTone } from "@mythicalos/ui-core/logic";
+export { chipClass, type ChipTone };
+export interface ChipProps {
+    tone?: ChipTone;
+    className?: string;
+    children?: ReactNode;
+}
+export declare function Chip(props: ChipProps): import("react").JSX.Element;

package/dist/Chip.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { chipClass } from "@mythicalos/ui-core/logic";
+export { chipClass };
+export function Chip(props) {
+    const { tone = "neutral", className: cls = "" } = props;
+    return _jsx("span", { className: `${chipClass(tone)} ${cls}`, children: props.children });
+}

package/dist/ConfirmDialog.d.ts

@@ -0,0 +1,25 @@
+import type { ReactNode } from "react";
+import { typedNameMatches, BULLET_ICON, type DialogBullet } from "@mythicalos/ui-core/logic";
+export { typedNameMatches, BULLET_ICON, type DialogBullet };
+export declare function Scrim(props: {
+    children: ReactNode;
+    onCancel: () => void;
+}): import("react").JSX.Element;
+export interface ConfirmDialogProps {
+    title: string;
+    body: ReactNode;
+    bullets?: DialogBullet[];
+    confirmLabel: string;
+    cancelLabel?: string;
+    /** Typed-name-match gate (rules-of-use 9): when set, the danger action stays disabled until the
+     * operator types EXACTLY this string (e.g. the slot name being deleted). */
+    requireName?: string;
+    /** Overrides the typed-name entry hint ("Type <name> to confirm" by default). */
+    requireNameHint?: string;
+    loading?: boolean;
+    onConfirm: () => void;
+    onCancel: () => void;
+}
+/** A destructive confirm — danger FILL, safe action focused first (Esc cancels), with an optional
+ * typed-name-match gate for irreversible deletes. */
+export declare function ConfirmDialog(props: ConfirmDialogProps): import("react").JSX.Element;

package/dist/ConfirmDialog.js

@@ -0,0 +1,46 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// @mythicalos/react-ui — confirm dialogs (ds/components-dialogs). Modal 400px, radius 16, modal
+// shadow over the scrim, Esc = cancel, the safe action focused first. Danger FILL is reserved for
+// genuine destructive confirms (book §7.7). The generic, fully prop-driven `ConfirmDialog` (with
+// its optional typed-name-match gate — rules-of-use 9) + the exported `Scrim` are the shared
+// commons; app-specific wrappers compose them in the app (design note §1b-D21: neutral prop
+// names only — no product domain vocabulary leaks from this package).
+//
+// React twin of packages/preact-ui/src/ConfirmDialog.tsx. `typedNameMatches` and
+// `BULLET_ICON`/`DialogBullet` are imported (never re-implemented) from `@mythicalos/ui-core`, same
+// as the Preact sibling. Two Preact→React deltas: (1) the typed-name `<input>` now attaches
+// `onChange` unconditionally (it always has local state behind it, so this is really a no-op
+// change); (2) the bullets `<li>` list now carries an explicit `key` — React's dev-mode key
+// warning fires at element-creation time (even under `renderToStaticMarkup`), while Preact never
+// checks for one, so a bare `.map()` here would print console noise the Preact sibling never has.
+// `window`'s native KeyboardEvent below is the DOM global, not React's synthetic type — no `react`
+// import shadows it in this file.
+import { useEffect, useRef, useState } from "react";
+import { typedNameMatches, BULLET_ICON } from "@mythicalos/ui-core/logic";
+export { typedNameMatches, BULLET_ICON };
+export function Scrim(props) {
+    useEffect(() => {
+        const onKey = (e) => {
+            if (e.key === "Escape")
+                props.onCancel();
+        };
+        window.addEventListener("keydown", onKey);
+        return () => window.removeEventListener("keydown", onKey);
+    }, [props.onCancel]);
+    return (_jsx("div", { className: "scrim", role: "dialog", "aria-modal": "true", children: _jsx("div", { className: "dlg", children: props.children }) }));
+}
+/** A destructive confirm — danger FILL, safe action focused first (Esc cancels), with an optional
+ * typed-name-match gate for irreversible deletes. */
+export function ConfirmDialog(props) {
+    const cancelRef = useRef(null);
+    const [typed, setTyped] = useState("");
+    useEffect(() => {
+        cancelRef.current?.focus();
+    }, []);
+    const nameOk = typedNameMatches(props.requireName, typed);
+    const confirmDisabled = props.loading === true || !nameOk;
+    return (_jsxs(Scrim, { onCancel: props.onCancel, children: [_jsx("h2", { children: props.title }), _jsx("p", { children: props.body }), props.bullets ? (_jsx("ul", { children: props.bullets.map((b, i) => (_jsxs("li", { children: [_jsx("i", { className: `ic-${b.tone}`, "aria-hidden": "true", children: BULLET_ICON[b.tone] }), _jsx("span", { children: b.text })] }, i))) })) : null, props.requireName !== undefined ? (_jsxs("label", { className: "field", children: [_jsx("span", { className: "field-label", children: props.requireNameHint ?? `Type ${props.requireName} to confirm` }), _jsx("input", { className: "input mono", type: "text", value: typed, placeholder: props.requireName, autoComplete: "off", autoCapitalize: "off", spellCheck: false, onChange: (e) => setTyped(e.target.value) })] })) : null, _jsxs("div", { className: "dlg-foot", children: [_jsx("button", { ref: cancelRef, type: "button", className: "btn btn--sec", onClick: props.onCancel, children: props.cancelLabel ?? "Cancel" }), _jsxs("button", { type: "button", className: `btn danf${confirmDisabled ? " is-disabled" : ""}`, disabled: confirmDisabled, "aria-busy": props.loading ? "true" : undefined, onClick: () => {
+                            if (!confirmDisabled)
+                                props.onConfirm();
+                        }, children: [props.loading ? _jsx("span", { className: "spin", "aria-hidden": "true" }) : null, props.confirmLabel] })] }), _jsx("div", { className: "esc", children: "Esc cancels \u00B7 focus starts on the safe action" })] }));
+}

package/dist/EmptyState.d.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from "react";
+export interface EmptyStateProps {
+    variant: "unconfigured" | "asleep" | "neutral";
+    title: string;
+    body: string;
+    actions?: ReactNode;
+}
+export declare function EmptyState(props: EmptyStateProps): import("react").JSX.Element;

package/dist/EmptyState.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+function SpineArt(props) {
+    if (props.variant === "unconfigured") {
+        // solid up to the live petrol tip, dashed beyond; hollow muted nodes = not-yet
+        // (§1a-8: package-owned tokenized classes — no literal strokes, no gauge-block classes)
+        return (_jsxs("svg", { className: "spine-empty", viewBox: "0 0 200 36", role: "img", "aria-label": "setup is the live step", children: [_jsx("line", { className: "spine-track", x1: "10", y1: "18", x2: "118", y2: "18", strokeWidth: "3" }), _jsx("line", { className: "spine-dash", x1: "118", y1: "18", x2: "190", y2: "18", strokeWidth: "3", strokeDasharray: "2 7", strokeLinecap: "round" }), _jsx("circle", { className: "spine-node", cx: "10", cy: "18", r: "7", strokeWidth: "3" }), _jsx("circle", { className: "spine-node", cx: "64", cy: "18", r: "7", strokeWidth: "3" }), _jsx("circle", { className: "spine-here", cx: "118", cy: "18", r: "8" })] }));
+    }
+    if (props.variant === "asleep") {
+        return (_jsxs("svg", { className: "spine-empty", viewBox: "0 0 200 36", role: "img", "aria-label": "the hollow tip waits", children: [_jsx("line", { className: "spine-track", x1: "10", y1: "18", x2: "190", y2: "18", strokeWidth: "3" }), _jsx("circle", { className: "spine-dot", cx: "10", cy: "18", r: "7" }), _jsx("circle", { className: "spine-dot", cx: "64", cy: "18", r: "7" }), _jsx("circle", { className: "spine-dot", cx: "118", cy: "18", r: "7" }), _jsx("circle", { className: "spine-node", cx: "182", cy: "18", r: "8", strokeWidth: "3" })] }));
+    }
+    return null;
+}
+export function EmptyState(props) {
+    return (_jsxs("div", { className: "empty", children: [_jsx(SpineArt, { variant: props.variant }), _jsx("h2", { children: props.title }), _jsx("p", { children: props.body }), props.actions ? _jsx("div", { className: "ebtns", children: props.actions }) : null] }));
+}

package/dist/Gauge.d.ts

@@ -0,0 +1,9 @@
+import { gaugeGeom, gaugeTone, type GaugeGeom, type Tone } from "@mythicalos/ui-core/logic";
+export { gaugeGeom, gaugeTone, type GaugeGeom, type Tone };
+export interface GaugeProps {
+    pct?: number;
+    size?: number;
+    stroke?: number;
+    showLabel?: boolean;
+}
+export declare function Gauge(props: GaugeProps): import("react").JSX.Element;

package/dist/Gauge.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// @mythicalos/react-ui — circular gauge for context/usage. `pct` 0–100. Fill color steps by
+// threshold per token rule #4: accent < 75%, warn 75–89%, error ≥ 90%. Pure SVG presentation
+// attributes (no inline CSS) — the stroke color is a class, the arc is a dash attribute.
+//
+// React twin of packages/preact-ui/src/Gauge.tsx. `gaugeGeom`/`gaugeTone` (geometry + threshold
+// math) are imported from `@mythicalos/ui-core`, never reimplemented — this binding only renders
+// the SVG from the values those functions return. SVG stroke attributes go through React's
+// camelCase props (`strokeWidth`/`strokeDasharray`/`strokeDashoffset`), which serialize back to the
+// same kebab-case DOM attributes as the Preact sibling's output.
+import { gaugeGeom, gaugeTone } from "@mythicalos/ui-core/logic";
+export { gaugeGeom, gaugeTone };
+export function Gauge(props) {
+    const { pct = 0, size = 44, stroke = 4, showLabel = true } = props;
+    const { r, circ, offset } = gaugeGeom(size, stroke, pct);
+    const tone = gaugeTone(pct);
+    // gaugeGeom/gaugeTone each clamp `pct` to 0–100 independently (ui-core's gauge.ts: "so either
+    // can be called on its own ... and stay consistent with the other"); the label needs that same
+    // 0–100 clamp to restate the identical number as a percentage — trivial arithmetic, not the
+    // tone/geometry derivation itself, which stays entirely in gaugeTone/gaugeGeom above.
+    const clampedPct = Math.round(Math.max(0, Math.min(100, pct)));
+    return (_jsxs("span", { className: "my-gauge__wrap", children: [_jsx("span", { className: "my-gauge", children: _jsxs("svg", { width: size, height: size, children: [_jsx("circle", { className: "my-gauge__track", cx: size / 2, cy: size / 2, r: r, strokeWidth: stroke }), _jsx("circle", { className: `my-gauge__fill my-gauge__fill--${tone}`, cx: size / 2, cy: size / 2, r: r, strokeWidth: stroke, strokeDasharray: circ, strokeDashoffset: offset })] }) }), showLabel ? _jsxs("span", { className: "my-gauge__label", children: [clampedPct, "%"] }) : null] }));
+}

package/dist/Input.d.ts

@@ -0,0 +1,31 @@
+import type { ReactNode, KeyboardEvent } from "react";
+export interface InputProps {
+    label?: ReactNode;
+    value?: string;
+    placeholder?: string;
+    error?: string;
+    help?: ReactNode;
+    disabled?: boolean;
+    readOnly?: boolean;
+    mono?: boolean;
+    dirty?: boolean;
+    type?: string;
+    id?: string;
+    onInput?: (value: string) => void;
+    onKeyDown?: (e: KeyboardEvent<HTMLInputElement>) => void;
+}
+export declare function Input(props: InputProps): import("react").JSX.Element;
+export interface ToggleProps {
+    on: boolean;
+    disabled?: boolean;
+    label?: string;
+    onToggle?: (next: boolean) => void;
+}
+export declare function Toggle(props: ToggleProps): import("react").JSX.Element;
+export interface CheckboxProps {
+    checked: boolean;
+    disabled?: boolean;
+    label?: ReactNode;
+    onToggle?: (next: boolean) => void;
+}
+export declare function Checkbox(props: CheckboxProps): import("react").JSX.Element;

package/dist/Input.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+export function Input(props) {
+    const cls = ["input"];
+    if (props.error)
+        cls.push("is-err");
+    if (props.mono)
+        cls.push("mono");
+    if (props.dirty)
+        cls.push("is-dirty");
+    if (props.readOnly)
+        cls.push("readonly-input");
+    const field = (_jsxs(_Fragment, { children: [_jsx("input", { id: props.id, type: props.type ?? "text", className: cls.join(" "), value: props.value ?? "", placeholder: props.placeholder, disabled: props.disabled, readOnly: props.readOnly, 
+                // Local single-user config UI: these are identifiers/paths/config values (slugs, names,
+                // model ids, urls), never autofill targets — kill browser autocomplete, the annoying
+                // first-letter auto-capitalize, autocorrect, and spellcheck squiggles on all of them.
+                autoComplete: "off", autoCapitalize: "off", autoCorrect: "off", spellCheck: false, "aria-invalid": props.error ? "true" : undefined, onChange: (e) => props.onInput?.(e.target.value), onKeyDown: props.onKeyDown }), props.help && !props.error ? _jsx("div", { className: "help", children: props.help }) : null, props.error ? (_jsxs("div", { className: "emsg", children: [_jsx("span", { "aria-hidden": "true", children: "\u26A0" }), _jsx("span", { children: props.error })] })) : null] }));
+    if (!props.label)
+        return field;
+    return (_jsxs("label", { className: "field", children: [_jsx("span", { className: "field-label", children: props.label }), field] }));
+}
+export function Toggle(props) {
+    const cls = ["tog"];
+    if (!props.on)
+        cls.push("is-off");
+    if (props.disabled)
+        cls.push("is-disabled");
+    return (_jsx("button", { type: "button", className: cls.join(" "), role: "switch", "aria-checked": props.on ? "true" : "false", "aria-label": props.label, disabled: props.disabled, onClick: props.disabled ? undefined : () => props.onToggle?.(!props.on), children: _jsx("i", { "aria-hidden": "true" }) }));
+}
+export function Checkbox(props) {
+    const cls = ["cb"];
+    if (props.checked)
+        cls.push("is-on");
+    if (props.disabled)
+        cls.push("is-disabled");
+    const box = (_jsx("button", { type: "button", className: cls.join(" "), role: "checkbox", "aria-checked": props.checked ? "true" : "false", disabled: props.disabled, onClick: props.disabled ? undefined : () => props.onToggle?.(!props.checked), children: props.checked ? _jsx("span", { "aria-hidden": "true", children: "\u2713" }) : null }));
+    if (!props.label)
+        return box;
+    return (_jsxs("label", { className: "check-row", children: [box, _jsx("span", { children: props.label })] }));
+}

package/dist/MaskedSecretInput.d.ts

@@ -0,0 +1,15 @@
+export interface MaskedSecretInputProps {
+    label: string;
+    /** Full slot name, e.g. "model/claude" — shown as the chip. */
+    slot: string;
+    /** True when the server's secrets list contains `slot`. */
+    filled: boolean;
+    /** The server's masked echo, when known (e.g. "sk-…3kfa"). */
+    masked?: string;
+    /** Labels the entry lane so the operator knows what to paste. */
+    entryHint?: string;
+    disabled?: boolean;
+    /** Called with the raw entered value on submit — the parent PUTs it and never reads it back. */
+    onSubmit?: (value: string) => void;
+}
+export declare function MaskedSecretInput(props: MaskedSecretInputProps): import("react").JSX.Element;

package/dist/MaskedSecretInput.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// @mythicalos/react-ui — masked secret input with slot chip (ds/components-inputs "secret slots").
+// A filled slot shows the server's mask (readonly — the value never round-trips to the UI) + the
+// slot chip + a "Replace" affordance that re-opens entry; an unset slot shows the dashed empty
+// chip ("unconfigured is a valid state"). Submitting a new value is the PARENT's concern (it PUTs
+// to the secrets route and never reads the value back); this component is presentation + entry only.
+//
+// React twin of packages/preact-ui/src/MaskedSecretInput.tsx. Both the filled-mask input (readOnly,
+// no handler needed — React's controlled-without-onChange warning is suppressed by `readOnly`) and
+// the entry input (local `useState`, always has a real `onChange`) are already React-safe with no
+// extra wiring required.
+import { useState } from "react";
+import { Button } from "./Button.js";
+export function MaskedSecretInput(props) {
+    const [editing, setEditing] = useState(!props.filled);
+    const [value, setValue] = useState("");
+    const chip = props.filled ? (_jsx("span", { className: "chip", children: props.slot })) : (_jsx("span", { className: "chip chip--empty", children: "slot empty" }));
+    if (props.filled && !editing) {
+        return (_jsxs("label", { className: "field", children: [_jsx("span", { className: "field-label", children: props.label }), _jsxs("div", { className: "slot", children: [_jsx("input", { className: "input mono readonly-input", value: props.masked ?? "••••••••", readOnly: true }), chip, _jsx("button", { type: "button", className: "rep", disabled: props.disabled, onClick: () => setEditing(true), children: "Replace" })] }), _jsx("div", { className: "help", children: "Readonly mask; Replace re-opens entry. The value never round-trips to the UI." })] }));
+    }
+    return (_jsxs("label", { className: "field", children: [_jsx("span", { className: "field-label", children: props.label }), _jsxs("div", { className: "slot", children: [_jsx("input", { className: "input mono", 
+                        // diff r1-F10 (S1a-11): a replacement credential is a SECRET while typed — masked entry
+                        // (type=password) + new-password so the browser neither displays nor offers to save it.
+                        type: "password", value: value, placeholder: props.entryHint ?? "paste token…", disabled: props.disabled, 
+                        // A pasted credential: never autofill/autocapitalize/autocorrect/spellcheck it.
+                        autoComplete: "new-password", autoCapitalize: "off", autoCorrect: "off", spellCheck: false, onChange: (e) => setValue(e.target.value) }), chip, _jsx(Button, { variant: "sec", small: true, disabled: props.disabled || value.trim().length === 0, onClick: () => {
+                            props.onSubmit?.(value);
+                            setValue("");
+                            if (props.filled)
+                                setEditing(false);
+                        }, children: "Save" })] }), _jsx("div", { className: "help", children: "Unconfigured is a valid state \u2014 no error until submit." })] }));
+}

package/dist/SearchInput.d.ts

@@ -0,0 +1,8 @@
+import type { ChangeEvent, MouseEvent } from "react";
+export interface SearchInputProps {
+    value?: string;
+    placeholder?: string;
+    onInput?: (e: ChangeEvent<HTMLInputElement>) => void;
+    onClear?: (e: MouseEvent<HTMLButtonElement>) => void;
+}
+export declare function SearchInput(props: SearchInputProps): import("react").JSX.Element;

package/dist/SearchInput.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const noop = () => { };
+export function SearchInput(props) {
+    const { value, onInput, onClear, placeholder = "Search…" } = props;
+    return (_jsxs("div", { className: "my-search", children: [_jsx("span", { className: "my-search__icon", children: "\u2315" }), _jsx("input", { className: "my-search__input", value: value, onChange: onInput ?? noop, placeholder: placeholder }), value ? (_jsx("button", { type: "button", className: "my-search__clear", title: "Clear", onClick: onClear, children: "\u2715" })) : null] }));
+}

package/dist/StatusLine.d.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from "react";
+import { statusLineClass, type StatusTone } from "@mythicalos/ui-core/logic";
+export { statusLineClass, type StatusTone };
+export interface StatusLineProps {
+    tone?: StatusTone;
+    children?: ReactNode;
+}
+export declare function StatusLine(props: StatusLineProps): import("react").JSX.Element;

package/dist/StatusLine.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { statusLineClass } from "@mythicalos/ui-core/logic";
+export { statusLineClass };
+export function StatusLine(props) {
+    const { tone = "ok" } = props;
+    return (_jsxs("span", { className: statusLineClass(tone), children: [_jsx("span", { className: "my-status__dot" }), props.children] }));
+}

package/dist/Toast.d.ts

@@ -0,0 +1,18 @@
+import type { ReactNode } from "react";
+import { type ToastStatus } from "./toast-context.js";
+import { composeToastText, TOAST_SEP } from "@mythicalos/ui-core/logic";
+export { composeToastText, TOAST_SEP };
+export declare function ToastProvider(props: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+export interface ToastProps {
+    status: ToastStatus;
+    title: string;
+    body?: string;
+    action?: {
+        label: string;
+        onAction: () => void;
+    };
+    onClose?: () => void;
+}
+export declare function Toast(props: ToastProps): import("react").JSX.Element;

package/dist/Toast.js

@@ -0,0 +1,51 @@
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+// @mythicalos/react-ui — toasts (ds/components-toasts): tone-colored (ok = surface/ink/border;
+// warn/error/info = soft fill + status ink/border), icon + bold lead carry the state (never color
+// alone). Auto-dismiss every tone on one cadence; each stacked toast runs its own timer. Max 3
+// visible — older collapse into "+n more".
+//
+// React twin of packages/preact-ui/src/Toast.tsx. `composeToastText`/`TOAST_SEP` are imported
+// (never re-implemented) from `@mythicalos/ui-core`; the tone→icon/dismiss-cadence lookup tables
+// stay local, same as the Preact sibling (literal presentational maps, not branchy derivation).
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { ToastContext } from "./toast-context.js";
+import { composeToastText, TOAST_SEP } from "@mythicalos/ui-core/logic";
+export { composeToastText, TOAST_SEP };
+const ICON = { ok: "✓", info: "ℹ", warn: "▲", error: "⬤" };
+const DISMISS_MS = { ok: 2600, info: 2600, warn: 2600, error: 2600 };
+export function ToastProvider(props) {
+    const [toasts, setToasts] = useState([]);
+    const nextId = useRef(1);
+    const timers = useRef(new Map());
+    const dismiss = useCallback((id) => {
+        setToasts((prev) => prev.filter((t) => t.id !== id));
+        const timer = timers.current.get(id);
+        if (timer) {
+            clearTimeout(timer);
+            timers.current.delete(id);
+        }
+    }, []);
+    const push = useCallback((spec) => {
+        const id = nextId.current++;
+        setToasts((prev) => [...prev, { ...spec, id }]);
+        const ms = DISMISS_MS[spec.status];
+        if (ms !== null) {
+            timers.current.set(id, setTimeout(() => dismiss(id), ms));
+        }
+    }, [dismiss]);
+    useEffect(() => {
+        const map = timers.current;
+        return () => {
+            for (const t of map.values())
+                clearTimeout(t);
+            map.clear();
+        };
+    }, []);
+    const bus = useMemo(() => ({ push }), [push]);
+    const visible = toasts.slice(-3);
+    const hiddenCount = toasts.length - visible.length;
+    return (_jsxs(ToastContext.Provider, { value: bus, children: [props.children, _jsxs("div", { className: "toast-stack", "aria-live": "polite", children: [hiddenCount > 0 ? _jsxs("div", { className: "toast-more", children: ["+", hiddenCount, " more"] }) : null, visible.map((t) => (_jsx(Toast, { status: t.status, title: t.title, body: t.body, action: t.action, onClose: () => dismiss(t.id) }, t.id)))] })] }));
+}
+export function Toast(props) {
+    return (_jsxs("div", { className: `toast toast--${props.status}`, role: "status", children: [_jsx("i", { className: "toast-icon", "aria-hidden": "true", children: ICON[props.status] }), _jsxs("span", { children: [_jsx("b", { children: props.title }), props.body ? (_jsxs(_Fragment, { children: [TOAST_SEP, props.body] })) : null] }), props.action ? (_jsx("button", { type: "button", className: "toast-action", onClick: props.action.onAction, children: props.action.label })) : null, _jsx("button", { type: "button", className: "toast-x", "aria-label": "Dismiss", onClick: props.onClose, children: "\u2715" })] }));
+}

package/dist/hooks.d.ts

@@ -0,0 +1,21 @@
+import { nextPollDelay, makePollEpochGuard, runPollTick, shouldResetEpoch, POLL_JITTER_RATIO, POLL_BACKOFF_CAP_MS, type PollResult, type PollEpochGuard, type PollTickIO } from "@mythicalos/ui-core/logic";
+export { nextPollDelay, makePollEpochGuard, runPollTick, shouldResetEpoch, POLL_JITTER_RATIO, POLL_BACKOFF_CAP_MS, type PollResult, type PollEpochGuard, type PollTickIO, };
+/**
+ * Poll `fn` on the `ms` cadence while `enabled`, under the U7 policy: every delay ±20% jittered,
+ * exponential ×2 backoff on consecutive failures capped at 60 s (reset on success), and
+ * `document.hidden` PAUSES the loop (immediate refresh when visibility returns). Fires immediately
+ * on mount / when a dep changes, cancels in-flight results after unmount, and never overlaps a
+ * slow response with the next tick — ONE scheduler per call site, never parallel duplicate polls.
+ * `fn` should resolve (never reject) with the value; thrown errors surface in `error`.
+ *
+ * Pass an `epochKey` to opt into epoch isolation: a change of key (or an `enabled` false→true
+ * transition) clears the retained `data`/`error` and returns to `loading` until the new epoch's
+ * first settle. Without `epochKey` the hook retains data/error across toggles and dep changes.
+ */
+export declare function usePoll<T>(fn: () => Promise<T>, ms: number, opts?: {
+    enabled?: boolean;
+    deps?: readonly unknown[];
+    epochKey?: unknown;
+}): PollResult<T>;
+/** Run `fn` on a fixed interval while `enabled` (no return value; for fire-and-forget effects). */
+export declare function useInterval(fn: () => void, ms: number, enabled?: boolean): void;

package/dist/hooks.js

@@ -0,0 +1,136 @@
+// @mythicalos/react-ui — small shared hooks (polling + interval). A family UI talks plain
+// request/response to its service; pages poll on their cadence via `usePoll`. Extends the U7
+// polling policy (design note §1b-D7, r2-F8): per-call interval, ±20% jitter on every delay,
+// exponential ×2 backoff on consecutive failures capped at 60 s (reset on success), and
+// `document.hidden` pauses the loop with an immediate refresh on visibility return.
+//
+// React twin of packages/preact-ui/src/hooks.ts. The pure, DOM-free scheduling math
+// (`nextPollDelay`, `makePollEpochGuard`, `runPollTick`, `shouldResetEpoch` — the r3-F1 fire-time
+// epoch stamp) lives in `@mythicalos/ui-core` and is imported, never reimplemented — identical to
+// the Preact sibling. Only the actual React hooks (`usePoll`/`useInterval`, which import `react`
+// instead of `preact/hooks`) differ; the hook bodies below are otherwise verbatim.
+import { useEffect, useRef, useState } from "react";
+import { nextPollDelay, makePollEpochGuard, runPollTick, shouldResetEpoch, POLL_JITTER_RATIO, POLL_BACKOFF_CAP_MS, } from "@mythicalos/ui-core/logic";
+export { nextPollDelay, makePollEpochGuard, runPollTick, shouldResetEpoch, POLL_JITTER_RATIO, POLL_BACKOFF_CAP_MS, };
+/**
+ * Poll `fn` on the `ms` cadence while `enabled`, under the U7 policy: every delay ±20% jittered,
+ * exponential ×2 backoff on consecutive failures capped at 60 s (reset on success), and
+ * `document.hidden` PAUSES the loop (immediate refresh when visibility returns). Fires immediately
+ * on mount / when a dep changes, cancels in-flight results after unmount, and never overlaps a
+ * slow response with the next tick — ONE scheduler per call site, never parallel duplicate polls.
+ * `fn` should resolve (never reject) with the value; thrown errors surface in `error`.
+ *
+ * Pass an `epochKey` to opt into epoch isolation: a change of key (or an `enabled` false→true
+ * transition) clears the retained `data`/`error` and returns to `loading` until the new epoch's
+ * first settle. Without `epochKey` the hook retains data/error across toggles and dep changes.
+ */
+export function usePoll(fn, ms, opts = {}) {
+    const enabled = opts.enabled ?? true;
+    const deps = opts.deps ?? [];
+    const useEpoch = "epochKey" in opts;
+    const epochKey = opts.epochKey;
+    const [data, setData] = useState(undefined);
+    const [error, setError] = useState(undefined);
+    const [loading, setLoading] = useState(enabled);
+    const [nonce, setNonce] = useState(0);
+    const fnRef = useRef(fn);
+    fnRef.current = fn;
+    // diff r3-F1: one persistent guard per call site — the render-time reset below invalidates it
+    // IMMEDIATELY, so an in-flight response for the old epoch is dropped even though the old
+    // effect's cleanup (which flips `alive`) only runs after paint.
+    const guardRef = useRef(null);
+    if (guardRef.current === null)
+        guardRef.current = makePollEpochGuard();
+    const guard = guardRef.current;
+    const epochRef = useRef({ key: epochKey, enabled });
+    if (shouldResetEpoch(useEpoch, epochRef.current, epochKey, enabled)) {
+        guard.invalidate(); // FIRST — stale in-flight responses die here, not at deferred cleanup (r3-F1)
+        if (data !== undefined)
+            setData(undefined);
+        if (error !== undefined)
+            setError(undefined);
+        if (enabled && !loading)
+            setLoading(true);
+    }
+    if (useEpoch)
+        epochRef.current = { key: epochKey, enabled };
+    useEffect(() => {
+        if (!enabled) {
+            setLoading(false);
+            return;
+        }
+        let alive = true;
+        let timer;
+        let stopped = false;
+        let failures = 0; // consecutive failed reads — drives the ×2 backoff ladder (reset on success)
+        const isHidden = () => typeof document !== "undefined" && document.hidden === true;
+        const schedule = () => {
+            if (!alive || stopped)
+                return;
+            // U7 pause: while the document is hidden no timer is armed — the
+            // visibilitychange handler below refreshes immediately on return.
+            if (isHidden())
+                return;
+            timer = setTimeout(() => void tick(), nextPollDelay(ms, failures));
+        };
+        // diff r3-F1: every response routes through runPollTick — stamped with the epoch at fire
+        // time, applied only while that epoch is still live. A stale settle leaves loading alone
+        // (the reset already set it for the new epoch) but still rearms via schedule()'s own guards.
+        const tick = () => runPollTick({
+            fetch: () => fnRef.current(),
+            guard,
+            isAlive: () => alive && !stopped,
+            isHidden,
+            onSuccess: (v) => {
+                failures = 0;
+                setData(v);
+                setError(undefined);
+            },
+            onFailure: (message) => {
+                failures += 1;
+                setError(message);
+            },
+            onSettled: (applied) => {
+                if (applied)
+                    setLoading(false);
+                schedule();
+            },
+        });
+        const onVisibility = () => {
+            if (!alive || stopped)
+                return;
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            if (!isHidden())
+                void tick(); // immediate refresh on visibility return
+        };
+        if (typeof document !== "undefined")
+            document.addEventListener("visibilitychange", onVisibility);
+        setLoading(true);
+        void tick();
+        return () => {
+            alive = false;
+            stopped = true;
+            guard.invalidate(); // r3-F1: teardown supersedes the epoch for legacy (no-epochKey) callers too
+            if (timer)
+                clearTimeout(timer);
+            if (typeof document !== "undefined")
+                document.removeEventListener("visibilitychange", onVisibility);
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [enabled, ms, nonce, epochKey, ...deps]);
+    return { data, error, loading, refresh: () => setNonce((n) => n + 1) };
+}
+/** Run `fn` on a fixed interval while `enabled` (no return value; for fire-and-forget effects). */
+export function useInterval(fn, ms, enabled = true) {
+    const fnRef = useRef(fn);
+    fnRef.current = fn;
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const id = setInterval(() => fnRef.current(), ms);
+        return () => clearInterval(id);
+    }, [ms, enabled]);
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { Button, buttonClass, type ButtonProps, type BtnVariant, type BtnState } from "./Button.js";
+export { Input, Toggle, Checkbox, type InputProps, type ToggleProps, type CheckboxProps } from "./Input.js";
+export { MaskedSecretInput, type MaskedSecretInputProps } from "./MaskedSecretInput.js";
+export { EmptyState, type EmptyStateProps } from "./EmptyState.js";
+export { Scrim, ConfirmDialog, typedNameMatches, BULLET_ICON, type DialogBullet, type ConfirmDialogProps, } from "./ConfirmDialog.js";
+export { Toast, ToastProvider, composeToastText, TOAST_SEP, type ToastProps, } from "./Toast.js";
+export { ToastContext, useToast, type ToastStatus, type ToastSpec, type ToastBus, } from "./toast-context.js";
+export { usePoll, useInterval, shouldResetEpoch, nextPollDelay, makePollEpochGuard, runPollTick, POLL_JITTER_RATIO, POLL_BACKOFF_CAP_MS, type PollResult, type PollEpochGuard, type PollTickIO, } from "./hooks.js";
+export { Chip, chipClass, type ChipProps, type ChipTone } from "./Chip.js";
+export { Card, type CardProps } from "./Card.js";
+export { Avatar, type AvatarProps } from "./Avatar.js";
+export { StatusLine, statusLineClass, type StatusLineProps, type StatusTone } from "./StatusLine.js";
+export { SearchInput, type SearchInputProps } from "./SearchInput.js";
+export { Banner, bannerClass, BANNER_ICON, type BannerProps, type BannerTone } from "./Banner.js";
+export { Gauge, gaugeTone, gaugeGeom, type GaugeProps, type GaugeGeom, type Tone } from "./Gauge.js";

package/dist/index.js

@@ -0,0 +1,22 @@
+// @mythicalos/react-ui — barrel. React twin of packages/preact-ui/src/index.ts — the SAME export
+// surface (components, hooks, re-exported core symbols, Props types) so the two bindings can never
+// drift. The two intentional prop-name deltas (Chip/Card/Avatar's `class` → `className`) live on
+// the component types themselves, not the barrel — see each file's header comment and the task
+// report. Serve `@mythicalos/ui-core/styles.css` (after `@mythicalos/tokens`) so these components'
+// classes resolve — this package ships no CSS of its own.
+export { Button, buttonClass } from "./Button.js";
+export { Input, Toggle, Checkbox } from "./Input.js";
+export { MaskedSecretInput } from "./MaskedSecretInput.js";
+export { EmptyState } from "./EmptyState.js";
+export { Scrim, ConfirmDialog, typedNameMatches, BULLET_ICON, } from "./ConfirmDialog.js";
+export { Toast, ToastProvider, composeToastText, TOAST_SEP, } from "./Toast.js";
+export { ToastContext, useToast, } from "./toast-context.js";
+export { usePoll, useInterval, shouldResetEpoch, nextPollDelay, makePollEpochGuard, runPollTick, POLL_JITTER_RATIO, POLL_BACKOFF_CAP_MS, } from "./hooks.js";
+// ── the 7 new atoms (design-export's "proposed additions" — Task 6 graduation) ──
+export { Chip, chipClass } from "./Chip.js";
+export { Card } from "./Card.js";
+export { Avatar } from "./Avatar.js";
+export { StatusLine, statusLineClass } from "./StatusLine.js";
+export { SearchInput } from "./SearchInput.js";
+export { Banner, bannerClass, BANNER_ICON } from "./Banner.js";
+export { Gauge, gaugeTone, gaugeGeom } from "./Gauge.js";

package/dist/toast-context.d.ts

@@ -0,0 +1,4 @@
+import { type ToastStatus, type ToastSpec, type ToastBus } from "@mythicalos/ui-core/logic";
+export { type ToastStatus, type ToastSpec, type ToastBus };
+export declare const ToastContext: import("react").Context<ToastBus>;
+export declare function useToast(): ToastBus;

package/dist/toast-context.js

@@ -0,0 +1,14 @@
+// @mythicalos/react-ui — the toast bus context (decoupled from any app API client). Shared with the
+// Preact sibling so both family UIs can push toasts through one implementation shape. The app
+// provides <ToastProvider> at its root and components push via useToast().
+//
+// React twin of packages/preact-ui/src/toast-context.ts. `ToastStatus`/`ToastSpec`/`ToastBus` are
+// imported from `@mythicalos/ui-core` (framework-agnostic); only the `createContext`/`useContext`
+// wiring differs — `react` instead of `preact`/`preact/hooks`.
+import { createContext, useContext } from "react";
+import {} from "@mythicalos/ui-core/logic";
+export {};
+export const ToastContext = createContext({ push: () => { } });
+export function useToast() {
+    return useContext(ToastContext);
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@mythicalos/react-ui",
+  "version": "0.1.0",
+  "description": "mythicalOS thin React bindings over @mythicalos/ui-core — Button, Input/Toggle/Checkbox, MaskedSecretInput, EmptyState, ConfirmDialog/Scrim, Toast/ToastProvider, Chip, Card, Avatar, StatusLine, SearchInput, Banner, Gauge, and the usePoll/useInterval hooks. Render + framework wiring only — every class string, poll-scheduling math, glyph map, and text composition is derived by @mythicalos/ui-core so this binding and its Preact sibling can never drift. Apache-2.0.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mythicalOS/mythical-ui.git",
+    "directory": "packages/react-ui"
+  },
+  "homepage": "https://github.com/mythicalOS/mythical-ui#packages",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md", "NOTICE"],
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19",
+    "react-dom": "^18.2.0 || ^19",
+    "@mythicalos/tokens": "^0.5.11"
+  },
+  "peerDependenciesMeta": {
+    "@mythicalos/tokens": {
+    "optional": true
+  }
+},
+"dependencies": {
+  "@mythicalos/ui-core": "^0.1.0"
+},
+"scripts": {
+  "build": "tsc -p tsconfig.build.json",
+  "typecheck": "tsc --noEmit",
+  "test": "bun test",
+  "prepublishOnly": "bun run build && bun test && bun run typecheck"
+},
+"devDependencies": {
+  "react": "^19.2.8",
+  "react-dom": "^19.2.8",
+  "@types/react": "^19",
+  "@types/react-dom": "^19",
+  "typescript": "^5"
+}
+}