@brendanbank/atrium-host-bundle-utils 0.15.0

package/LICENCE.md

@@ -0,0 +1,25 @@
+# BSD 2-Clause License
+
+Copyright (c) 2026, Brendan Bank
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,119 @@
+# `@brendanbank/atrium-host-bundle-utils`
+
+Runtime helpers, Vite preset, and React hooks for [atrium](https://github.com/brendanbank/atrium)
+host bundles. Wraps the dual-tree mount pattern so a host's
+`main.tsx` collapses to ~10 lines of registration calls.
+
+```tsx
+import {
+  AtriumRegistry,
+  makeWrapperElement,
+} from '@brendanbank/atrium-host-bundle-utils';
+import { MyWidget } from './MyWidget';
+
+const reg = window.__ATRIUM_REGISTRY__ as AtriumRegistry;
+reg.registerHomeWidget({
+  key: 'my-card',
+  render: () => makeWrapperElement(<MyWidget />),
+});
+```
+
+## Installation
+
+The package is published on **GitHub Packages**, not the public npm
+registry. Add an `.npmrc` to your host project that points the
+`@brendanbank` scope at GitHub Packages and supplies a token with
+`read:packages` scope:
+
+```
+# .npmrc
+@brendanbank:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+```
+
+In CI, `GITHUB_TOKEN` is provided automatically by Actions; locally,
+generate a [classic PAT](https://github.com/settings/tokens) with
+`read:packages` and export it. Then:
+
+```bash
+pnpm add @brendanbank/atrium-host-bundle-utils \
+        @brendanbank/atrium-host-types
+```
+
+## Three subpath entry-points
+
+| Import                                                     | What you get                                               |
+| ---------------------------------------------------------- | ---------------------------------------------------------- |
+| `@brendanbank/atrium-host-bundle-utils`                   | `makeWrapperElement`, `mountInside`, `unmountInside`, types |
+| `@brendanbank/atrium-host-bundle-utils/vite`              | `hostBundleConfig({ entry })` — returns a Vite config      |
+| `@brendanbank/atrium-host-bundle-utils/react`             | `useMe`, `usePerm`, `useRole`, `useUserContext`, `<AtriumProvider>` |
+
+## Vite preset
+
+```ts
+// vite.config.ts
+import { hostBundleConfig } from '@brendanbank/atrium-host-bundle-utils/vite';
+
+export default hostBundleConfig({ entry: 'src/main.tsx' });
+```
+
+The factory returns a complete Vite library-mode config: emits a
+single `dist/main.js` that atrium's loader dynamic-imports, inlines
+imported `.css` via runtime `<style>` tags, and defines
+`process.env.NODE_ENV` so the externalised React + TanStack Query
+references resolve. Pass `extraConfig` to layer additional plugins
+or overrides on top.
+
+`vite` and `vite-plugin-css-injected-by-js` are declared as optional
+peer deps; install them as devDependencies in the host's
+`frontend/package.json` only when building the bundle.
+
+## React hooks
+
+```tsx
+import {
+  AtriumProvider,
+  useMe,
+  usePerm,
+  useRole,
+} from '@brendanbank/atrium-host-bundle-utils/react';
+
+function CommissionsPage() {
+  const { data: me, isLoading } = useMe();
+  const hasPerm = usePerm();
+  if (isLoading) return <Loader />;
+  if (hasPerm('commission.view.all')) return <Admin />;
+  return <SelfCommissions userId={me?.id} />;
+}
+
+function App() {
+  return (
+    <QueryClientProvider client={hostQueryClient}>
+      <AtriumProvider apiBase="/api">
+        <CommissionsPage />
+      </AtriumProvider>
+    </QueryClientProvider>
+  );
+}
+```
+
+`<AtriumProvider>` reads from your existing `<QueryClientProvider>`
+by default — no second QueryClient. Pass `client={hostQueryClient}`
+to wrap one inline; pass `fetchUserContext={...}` to inject a custom
+fetcher (useful for tests or hosts that want axios-shaped retry).
+
+## Versioning
+
+The package version tracks atrium's image version. Pin `^0.15` for
+"compatible with atrium 0.15.x"; bump together with the atrium image
+to pick up new registry slots and SDK helpers.
+
+## See also
+
+- [`@brendanbank/atrium-host-types`](../host-types/) — the typed
+  registry declarations this package re-exports.
+- [`docs/published-images.md`](../../docs/published-images.md) — the
+  full host-extension contract.
+- [`examples/hello-world/`](../../examples/hello-world/) — the
+  canonical worked example exercising every extension slot through
+  these helpers.

package/dist/i18n.d.ts

@@ -0,0 +1,17 @@
+/** Translate a shared atrium key against the running atrium image's
+ *  i18next instance.
+ *
+ *  ```ts
+ *  import { __atrium_t__ } from '@brendanbank/atrium-host-bundle-utils';
+ *
+ *  <Button>{__atrium_t__('common.save')}</Button>
+ *  <Text>{__atrium_t__('common.welcome', { name: me.full_name })}</Text>
+ *  ```
+ *
+ *  - Missing atrium image (pre-0.14): returns the literal key.
+ *  - Missing key: returns the literal key (not empty string), so a
+ *    typo is visible in the rendered output.
+ *  - Missing translation in the active locale: falls back to English
+ *    via i18next's ``fallbackLng``. */
+export declare function __atrium_t__(key: string, vars?: Record<string, string | number>): string;
+//# sourceMappingURL=i18n.d.ts.map

package/dist/i18n.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../src/i18n.ts"],"names":[],"mappings":"AAkDA;;;;;;;;;;;;;;uCAcuC;AACvC,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GACrC,MAAM,CAWR"}

package/dist/i18n.js

@@ -0,0 +1,32 @@
+// Copyright (c) 2026 Brendan Bank
+// SPDX-License-Identifier: BSD-2-Clause
+/** Translate a shared atrium key against the running atrium image's
+ *  i18next instance.
+ *
+ *  ```ts
+ *  import { __atrium_t__ } from '@brendanbank/atrium-host-bundle-utils';
+ *
+ *  <Button>{__atrium_t__('common.save')}</Button>
+ *  <Text>{__atrium_t__('common.welcome', { name: me.full_name })}</Text>
+ *  ```
+ *
+ *  - Missing atrium image (pre-0.14): returns the literal key.
+ *  - Missing key: returns the literal key (not empty string), so a
+ *    typo is visible in the rendered output.
+ *  - Missing translation in the active locale: falls back to English
+ *    via i18next's ``fallbackLng``. */
+export function __atrium_t__(key, vars) {
+    if (typeof window === 'undefined')
+        return key;
+    const i18n = window
+        .__atrium_i18n__;
+    if (!i18n || typeof i18n.t !== 'function')
+        return key;
+    // ``defaultValue: key`` is the explicit "missing key → key" rule.
+    // i18next's default behaviour already returns the key when the
+    // lookup misses, but spelling it out makes the intent unambiguous
+    // and survives any future i18next config change in atrium.
+    const out = i18n.t(key, { ...vars, defaultValue: key });
+    return typeof out === 'string' ? out : key;
+}
+//# sourceMappingURL=i18n.js.map

package/dist/i18n.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.js","sourceRoot":"","sources":["../src/i18n.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,wCAAwC;AAiDxC;;;;;;;;;;;;;;uCAcuC;AACvC,MAAM,UAAU,YAAY,CAC1B,GAAW,EACX,IAAsC;IAEtC,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,OAAO,GAAG,CAAC;IAC9C,MAAM,IAAI,GAAI,MAAuD;SAClE,eAAe,CAAC;IACnB,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,CAAC,CAAC,KAAK,UAAU;QAAE,OAAO,GAAG,CAAC;IACtD,kEAAkE;IAClE,+DAA+D;IAC/D,kEAAkE;IAClE,2DAA2D;IAC3D,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,EAAE,GAAG,IAAI,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC,CAAC;IACxD,OAAO,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;AAC7C,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Atrium host-bundle runtime helpers.
+ *
+ * Atrium loads each host's frontend as a single ES module via
+ * `import(system.host_bundle_url)` after the SPA boots. The host
+ * bundle calls `window.__ATRIUM_REGISTRY__.register*(...)` at import
+ * time. The elements registered are atrium-React elements (created
+ * via `window.React.createElement`) whose ref callback mounts the
+ * host's *own* React tree inside via `react-dom/client`'s
+ * `createRoot`. Two React trees coexist in the DOM:
+ *
+ *   - atrium's React owns the page shell + the wrapper `<div>`
+ *   - the host's React owns the subtree (Mantine, hook state, query
+ *     cache)
+ *
+ * `makeWrapperElement` and `mountInside` package up the dual-tree
+ * pattern so the host's `main.tsx` becomes ten lines of registration
+ * calls — see `examples/hello-world/frontend/src/main.tsx` for the
+ * canonical use.
+ *
+ * Type re-exports below let a host that only needs the runtime
+ * helpers add a single dep instead of two.
+ */
+import type { ReactElement } from 'react';
+export { __atrium_t__ } from './i18n';
+export type { AdminUserRow, AdminTab, AtriumEvent, AtriumEventHandler, AtriumNotification, AtriumRegistry, HomeWidget, HomeWidgetWidth, LocaleOverlay, NavItem, NotificationKindRenderer, ProfileItem, ProfileSlot, RouteEntry, UserContext, } from '@brendanbank/atrium-host-types';
+/** Mount `child` inside `el` using a fresh React root, idempotent on
+ *  the same `el`/`child` pair.
+ *
+ *  Behaviour:
+ *
+ *  - First call: `createRoot(el).render(child)` and remember the root.
+ *  - Same `el` + same `child` reference: no-op (handles `<StrictMode>`
+ *    double-invoke and ref-callback re-fires on remount).
+ *  - Same `el` + different `child` reference: re-renders into the
+ *    existing root — cheaper than unmount/remount and preserves
+ *    component state where the new child's tree matches.
+ *
+ *  Hosts use this directly only when they want to manage their own
+ *  ref semantics. The common case is `makeWrapperElement(child)`
+ *  below, which closes over a single child and tracks the mounted
+ *  node via the ref callback's `null` signal so unmount is exact. */
+export declare function mountInside(el: HTMLElement, child: ReactElement): void;
+/** Unmount the React root previously attached to `el` by `mountInside`.
+ *  No-op when there is no tracked root. Called automatically by the
+ *  ref callback returned from `makeWrapperElement`; hosts only call
+ *  this directly when managing their own ref semantics. */
+export declare function unmountInside(el: HTMLElement): void;
+/** Build an atrium-React element whose ref callback mounts `child` via
+ *  the host's own React. Returns a `ReactElement` so it slots
+ *  directly into the registry option-bag types (`render: () =>
+ *  makeWrapperElement(<MyWidget />)`).
+ *
+ *  Each call captures the supplied `child` in a closure and tracks the
+ *  mounted DOM node so the React unmount fires when atrium drops the
+ *  wrapper (route swap, tab change). The closure-style tracking is the
+ *  correct fix for issue #31 — using a module-level WeakMap alone
+ *  meant a child swap on a reused DOM node could leave the previous
+ *  child's tree mounted; pinning state to one closure-per-call
+ *  guarantees one wrapper element owns one mount.
+ *
+ *  Note: the returned object is created via *atrium's* React, not the
+ *  host bundle's. The two trees only meet at this `<div>`; everything
+ *  inside the ref callback runs under the host's React. The
+ *  `ReactElement` cast is safe because atrium's React exposes the
+ *  same element shape — the type system can't tell them apart, and
+ *  the registry consumer treats either as opaque.
+ *
+ *  Tabler icons (and other hooks-free SVG components) can be passed
+ *  directly to `window.React.createElement(...)` — they don't need
+ *  the wrapper. The wrapper is only required for trees that use
+ *  hooks, context, or anything that depends on the host's React copy. */
+export declare function makeWrapperElement(child: ReactElement): ReactElement;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAG1C,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAEtC,YAAY,EACV,YAAY,EACZ,QAAQ,EACR,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,EACd,UAAU,EACV,eAAe,EACf,aAAa,EACb,OAAO,EACP,wBAAwB,EACxB,WAAW,EACX,WAAW,EACX,UAAU,EACV,WAAW,GACZ,MAAM,gCAAgC,CAAC;AA2CxC;;;;;;;;;;;;;;;qEAeqE;AACrE,wBAAgB,WAAW,CAAC,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,CAWtE;AAED;;;2DAG2D;AAC3D,wBAAgB,aAAa,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI,CAKnD;AAED;;;;;;;;;;;;;;;;;;;;;;;yEAuByE;AACzE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,CAsBpE"}

package/dist/index.js

@@ -0,0 +1,114 @@
+// Copyright (c) 2026 Brendan Bank
+// SPDX-License-Identifier: BSD-2-Clause
+import { createRoot } from 'react-dom/client';
+export { __atrium_t__ } from './i18n';
+/** Resolve the React instance atrium exposes on `window.React`. Throws
+ *  with a clear message when missing — the host bundle's import-time
+ *  side-effects are running before the SPA mounted, which means the
+ *  bundle is being loaded outside atrium's own loader. */
+function getAtriumReact() {
+    if (typeof window === 'undefined') {
+        throw new Error('[atrium-host-bundle-utils] makeWrapperElement requires a browser ' +
+            'environment; called from a non-window context');
+    }
+    const r = window.React;
+    if (!r || typeof r.createElement !== 'function') {
+        throw new Error('[atrium-host-bundle-utils] window.React is missing — atrium SPA ' +
+            'must mount and expose its React on window.React before the host ' +
+            'bundle is imported. Check that the bundle is being loaded via ' +
+            "atrium's host_bundle_url loader and not by the host's own SPA.");
+    }
+    return r;
+}
+// WeakMap so a DOM element going away (host route swap, profile card
+// re-render) doesn't pin the React root in memory. The entry is GC'd
+// alongside the element.
+const mounted = new WeakMap();
+/** Mount `child` inside `el` using a fresh React root, idempotent on
+ *  the same `el`/`child` pair.
+ *
+ *  Behaviour:
+ *
+ *  - First call: `createRoot(el).render(child)` and remember the root.
+ *  - Same `el` + same `child` reference: no-op (handles `<StrictMode>`
+ *    double-invoke and ref-callback re-fires on remount).
+ *  - Same `el` + different `child` reference: re-renders into the
+ *    existing root — cheaper than unmount/remount and preserves
+ *    component state where the new child's tree matches.
+ *
+ *  Hosts use this directly only when they want to manage their own
+ *  ref semantics. The common case is `makeWrapperElement(child)`
+ *  below, which closes over a single child and tracks the mounted
+ *  node via the ref callback's `null` signal so unmount is exact. */
+export function mountInside(el, child) {
+    const existing = mounted.get(el);
+    if (existing) {
+        if (existing.child === child)
+            return;
+        existing.root.render(child);
+        existing.child = child;
+        return;
+    }
+    const root = createRoot(el);
+    root.render(child);
+    mounted.set(el, { root, child });
+}
+/** Unmount the React root previously attached to `el` by `mountInside`.
+ *  No-op when there is no tracked root. Called automatically by the
+ *  ref callback returned from `makeWrapperElement`; hosts only call
+ *  this directly when managing their own ref semantics. */
+export function unmountInside(el) {
+    const existing = mounted.get(el);
+    if (!existing)
+        return;
+    existing.root.unmount();
+    mounted.delete(el);
+}
+/** Build an atrium-React element whose ref callback mounts `child` via
+ *  the host's own React. Returns a `ReactElement` so it slots
+ *  directly into the registry option-bag types (`render: () =>
+ *  makeWrapperElement(<MyWidget />)`).
+ *
+ *  Each call captures the supplied `child` in a closure and tracks the
+ *  mounted DOM node so the React unmount fires when atrium drops the
+ *  wrapper (route swap, tab change). The closure-style tracking is the
+ *  correct fix for issue #31 — using a module-level WeakMap alone
+ *  meant a child swap on a reused DOM node could leave the previous
+ *  child's tree mounted; pinning state to one closure-per-call
+ *  guarantees one wrapper element owns one mount.
+ *
+ *  Note: the returned object is created via *atrium's* React, not the
+ *  host bundle's. The two trees only meet at this `<div>`; everything
+ *  inside the ref callback runs under the host's React. The
+ *  `ReactElement` cast is safe because atrium's React exposes the
+ *  same element shape — the type system can't tell them apart, and
+ *  the registry consumer treats either as opaque.
+ *
+ *  Tabler icons (and other hooks-free SVG components) can be passed
+ *  directly to `window.React.createElement(...)` — they don't need
+ *  the wrapper. The wrapper is only required for trees that use
+ *  hooks, context, or anything that depends on the host's React copy. */
+export function makeWrapperElement(child) {
+    const AtriumReact = getAtriumReact();
+    let mountedNode = null;
+    let mountedRoot = null;
+    return AtriumReact.createElement('div', {
+        ref: (el) => {
+            // React calls the ref with `null` on unmount and again with the
+            // node on mount. Same node twice in a row is the StrictMode /
+            // remount case — skip.
+            if (el === mountedNode)
+                return;
+            if (mountedRoot && mountedNode) {
+                mountedRoot.unmount();
+                mountedRoot = null;
+            }
+            mountedNode = el;
+            if (el) {
+                mountedRoot = createRoot(el);
+                mountedRoot.render(child);
+            }
+        },
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,wCAAwC;AA0BxC,OAAO,EAAE,UAAU,EAAa,MAAM,kBAAkB,CAAC;AAEzD,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AA4BtC;;;0DAG0D;AAC1D,SAAS,cAAc;IACrB,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CACb,mEAAmE;YACjE,+CAA+C,CAClD,CAAC;IACJ,CAAC;IACD,MAAM,CAAC,GAAI,MAAmD,CAAC,KAAK,CAAC;IACrE,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,aAAa,KAAK,UAAU,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CACb,kEAAkE;YAChE,kEAAkE;YAClE,gEAAgE;YAChE,gEAAgE,CACnE,CAAC;IACJ,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAOD,qEAAqE;AACrE,qEAAqE;AACrE,yBAAyB;AACzB,MAAM,OAAO,GAAG,IAAI,OAAO,EAA2B,CAAC;AAEvD;;;;;;;;;;;;;;;qEAeqE;AACrE,MAAM,UAAU,WAAW,CAAC,EAAe,EAAE,KAAmB;IAC9D,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACjC,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,QAAQ,CAAC,KAAK,KAAK,KAAK;YAAE,OAAO;QACrC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5B,QAAQ,CAAC,KAAK,GAAG,KAAK,CAAC;QACvB,OAAO;IACT,CAAC;IACD,MAAM,IAAI,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC;IAC5B,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACnB,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AACnC,CAAC;AAED;;;2DAG2D;AAC3D,MAAM,UAAU,aAAa,CAAC,EAAe;IAC3C,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACjC,IAAI,CAAC,QAAQ;QAAE,OAAO;IACtB,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;IACxB,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AACrB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;yEAuByE;AACzE,MAAM,UAAU,kBAAkB,CAAC,KAAmB;IACpD,MAAM,WAAW,GAAG,cAAc,EAAE,CAAC;IACrC,IAAI,WAAW,GAAuB,IAAI,CAAC;IAC3C,IAAI,WAAW,GAAgB,IAAI,CAAC;IAEpC,OAAO,WAAW,CAAC,aAAa,CAAC,KAAK,EAAE;QACtC,GAAG,EAAE,CAAC,EAAsB,EAAE,EAAE;YAC9B,gEAAgE;YAChE,8DAA8D;YAC9D,uBAAuB;YACvB,IAAI,EAAE,KAAK,WAAW;gBAAE,OAAO;YAC/B,IAAI,WAAW,IAAI,WAAW,EAAE,CAAC;gBAC/B,WAAW,CAAC,OAAO,EAAE,CAAC;gBACtB,WAAW,GAAG,IAAI,CAAC;YACrB,CAAC;YACD,WAAW,GAAG,EAAE,CAAC;YACjB,IAAI,EAAE,EAAE,CAAC;gBACP,WAAW,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC;gBAC7B,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;KACF,CAAiB,CAAC;AACrB,CAAC"}

package/dist/react/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * React hooks + provider for atrium host bundles.
+ *
+ * One TanStack Query subscription serves the whole host tree:
+ * `useMe()` fetches `/users/me/context` once and shares the result
+ * with every `usePerm()`, `useRole()`, and `useUserContext()` caller.
+ * The hooks read the API base URL from `<AtriumProvider>` (default
+ * `'/api'`) so a host serving its bundle on a different prefix can
+ * point them at the right origin without forking the package.
+ *
+ * The hooks reuse the host's enclosing `<QueryClientProvider>` if one
+ * is already mounted; pass `client={hostQueryClient}` to
+ * `<AtriumProvider>` only if you want this provider to wrap the
+ * QueryClient too. Two QueryClients (atrium's + the host's) is the
+ * intended state — atrium clears its cache on logout via `qc.clear()`,
+ * and a shared client would lose host queries the user still wants.
+ */
+import { type ReactNode } from 'react';
+import { type QueryClient, type UseQueryResult } from '@tanstack/react-query';
+import type { UserContext } from '@brendanbank/atrium-host-types';
+export type { UserContext } from '@brendanbank/atrium-host-types';
+export { __atrium_t__ } from '../i18n';
+interface AtriumContextValue {
+    apiBase: string;
+    fetchUserContext: () => Promise<UserContext | null>;
+}
+export interface AtriumProviderProps {
+    /** API base URL the hooks prefix on every fetch. Default `'/api'` —
+     *  matches atrium's convention of mounting the API behind `/api/*`
+     *  on the same origin as the SPA. */
+    apiBase?: string;
+    /** Optional TanStack QueryClient. When supplied the provider wraps
+     *  children in a `<QueryClientProvider>`; otherwise the hooks
+     *  inherit the caller's enclosing one. Use this only when the host
+     *  hasn't already set up its own provider. */
+    client?: QueryClient;
+    /** Override the fetcher for `/users/me/context`. Useful for tests
+     *  and for hosts that want to layer an axios interceptor or extra
+     *  headers on top. The default uses `fetch` with `credentials:
+     *  'include'`. */
+    fetchUserContext?: () => Promise<UserContext | null>;
+    children: ReactNode;
+}
+/** Provider that supplies `apiBase` and (optionally) a QueryClient
+ *  to the atrium hooks below. Hosts that already wrap their tree in
+ *  `<QueryClientProvider>` can omit `client` — the hooks use the
+ *  caller's existing QueryClient. */
+export declare function AtriumProvider({ apiBase, client, fetchUserContext, children, }: AtriumProviderProps): import("react").FunctionComponentElement<import("react").ProviderProps<AtriumContextValue | null>> | import("react").FunctionComponentElement<import("@tanstack/react-query").QueryClientProviderProps>;
+/** Stable cache key for the `/users/me/context` query. Exported so
+ *  hosts can `queryClient.invalidateQueries({ queryKey: ME_QUERY_KEY })`
+ *  after a flow that changed the user's roles or permissions. */
+export declare const ME_QUERY_KEY: readonly ["atrium", "me"];
+/** Fetch the signed-in user's RBAC context. Returns the standard
+ *  TanStack Query result so callers can surface loading and error
+ *  states — `data` is `null` when the user is not signed in (atrium
+ *  responded 401/403) and the typed `UserContext` otherwise.
+ *
+ *  Cache is shared with `usePerm` / `useRole` / `useUserContext` —
+ *  one network request per host tree. Stale time is 60s, matching
+ *  atrium's own `useMe` so the host's cache invalidation rhythm
+ *  doesn't fight atrium's. */
+export declare function useMe(): UseQueryResult<UserContext | null>;
+/** Alias for `useMe()` — present because issue #40 documents both
+ *  names. The shape is identical; pick whichever reads better at the
+ *  call site. */
+export declare function useUserContext(): UseQueryResult<UserContext | null>;
+/** Returns a stable predicate `(code) => boolean` over the signed-in
+ *  user's permissions. While `useMe` is still loading or if the user
+ *  is signed out, the predicate returns `false` for every code — so
+ *  callers default to "not allowed" which is the safe fallback for
+ *  RBAC gating.
+ *
+ *  Returning a function (not a boolean) is deliberate: a single
+ *  call site can check several codes against one query subscription,
+ *  matching the pattern in issue #40:
+ *
+ *  ```tsx
+ *  const hasPerm = usePerm();
+ *  if (hasPerm('commission.view.all')) return <Admin />;
+ *  if (hasPerm('commission.view.own')) return <SelfCommissions />;
+ *  ```
+ */
+export declare function usePerm(): (code: string) => boolean;
+/** Convenience: does the signed-in user hold the named role? Returns
+ *  `false` while loading and when signed out, mirroring `usePerm`. */
+export declare function useRole(code: string): boolean;
+//# sourceMappingURL=index.d.ts.map

package/dist/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAML,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,cAAc,EACpB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAElE,YAAY,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,UAAU,kBAAkB;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CACrD;AAqBD,MAAM,WAAW,mBAAmB;IAClC;;yCAEqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;kDAG8C;IAC9C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;sBAGkB;IAClB,gBAAgB,CAAC,EAAE,MAAM,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IACrD,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;qCAGqC;AACrC,wBAAgB,cAAc,CAAC,EAC7B,OAA0B,EAC1B,MAAM,EACN,gBAAgB,EAChB,QAAQ,GACT,EAAE,mBAAmB,2MAYrB;AAED;;iEAEiE;AACjE,eAAO,MAAM,YAAY,2BAA4B,CAAC;AAsBtD;;;;;;;;8BAQ8B;AAC9B,wBAAgB,KAAK,IAAI,cAAc,CAAC,WAAW,GAAG,IAAI,CAAC,CAQ1D;AAED;;iBAEiB;AACjB,wBAAgB,cAAc,IAAI,cAAc,CAAC,WAAW,GAAG,IAAI,CAAC,CAEnE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,IAAI,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAMnD;AAED;sEACsE;AACtE,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAG7C"}

package/dist/react/index.js

@@ -0,0 +1,125 @@
+// Copyright (c) 2026 Brendan Bank
+// SPDX-License-Identifier: BSD-2-Clause
+/**
+ * React hooks + provider for atrium host bundles.
+ *
+ * One TanStack Query subscription serves the whole host tree:
+ * `useMe()` fetches `/users/me/context` once and shares the result
+ * with every `usePerm()`, `useRole()`, and `useUserContext()` caller.
+ * The hooks read the API base URL from `<AtriumProvider>` (default
+ * `'/api'`) so a host serving its bundle on a different prefix can
+ * point them at the right origin without forking the package.
+ *
+ * The hooks reuse the host's enclosing `<QueryClientProvider>` if one
+ * is already mounted; pass `client={hostQueryClient}` to
+ * `<AtriumProvider>` only if you want this provider to wrap the
+ * QueryClient too. Two QueryClients (atrium's + the host's) is the
+ * intended state — atrium clears its cache on logout via `qc.clear()`,
+ * and a shared client would lose host queries the user still wants.
+ */
+import { createContext, createElement, useCallback, useContext, useMemo, } from 'react';
+import { QueryClientProvider, useQuery, } from '@tanstack/react-query';
+export { __atrium_t__ } from '../i18n';
+const DEFAULT_API_BASE = '/api';
+async function defaultFetchUserContext(apiBase) {
+    const res = await fetch(`${apiBase}/users/me/context`, {
+        credentials: 'include',
+        headers: { Accept: 'application/json' },
+    });
+    if (res.status === 401 || res.status === 403)
+        return null;
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`/users/me/context: ${res.status} ${body}`.trim());
+    }
+    return (await res.json());
+}
+const AtriumContext = createContext(null);
+/** Provider that supplies `apiBase` and (optionally) a QueryClient
+ *  to the atrium hooks below. Hosts that already wrap their tree in
+ *  `<QueryClientProvider>` can omit `client` — the hooks use the
+ *  caller's existing QueryClient. */
+export function AtriumProvider({ apiBase = DEFAULT_API_BASE, client, fetchUserContext, children, }) {
+    const value = useMemo(() => {
+        const fetcher = fetchUserContext ?? (() => defaultFetchUserContext(apiBase));
+        return { apiBase, fetchUserContext: fetcher };
+    }, [apiBase, fetchUserContext]);
+    const inner = createElement(AtriumContext.Provider, { value }, children);
+    if (client) {
+        return createElement(QueryClientProvider, { client }, inner);
+    }
+    return inner;
+}
+/** Stable cache key for the `/users/me/context` query. Exported so
+ *  hosts can `queryClient.invalidateQueries({ queryKey: ME_QUERY_KEY })`
+ *  after a flow that changed the user's roles or permissions. */
+export const ME_QUERY_KEY = ['atrium', 'me'];
+// Module-level fallback so hooks work without an explicit
+// `<AtriumProvider>` — convenient for hosts that don't need to
+// override the API base or the fetcher. Lazily-allocated so the
+// import has no side effects.
+let DEFAULT_CTX = null;
+function defaultCtx() {
+    if (!DEFAULT_CTX) {
+        DEFAULT_CTX = {
+            apiBase: DEFAULT_API_BASE,
+            fetchUserContext: () => defaultFetchUserContext(DEFAULT_API_BASE),
+        };
+    }
+    return DEFAULT_CTX;
+}
+function useAtriumContextOrDefault() {
+    const ctx = useContext(AtriumContext);
+    return ctx ?? defaultCtx();
+}
+/** Fetch the signed-in user's RBAC context. Returns the standard
+ *  TanStack Query result so callers can surface loading and error
+ *  states — `data` is `null` when the user is not signed in (atrium
+ *  responded 401/403) and the typed `UserContext` otherwise.
+ *
+ *  Cache is shared with `usePerm` / `useRole` / `useUserContext` —
+ *  one network request per host tree. Stale time is 60s, matching
+ *  atrium's own `useMe` so the host's cache invalidation rhythm
+ *  doesn't fight atrium's. */
+export function useMe() {
+    const { fetchUserContext } = useAtriumContextOrDefault();
+    return useQuery({
+        queryKey: ME_QUERY_KEY,
+        queryFn: fetchUserContext,
+        staleTime: 60_000,
+        retry: false,
+    });
+}
+/** Alias for `useMe()` — present because issue #40 documents both
+ *  names. The shape is identical; pick whichever reads better at the
+ *  call site. */
+export function useUserContext() {
+    return useMe();
+}
+/** Returns a stable predicate `(code) => boolean` over the signed-in
+ *  user's permissions. While `useMe` is still loading or if the user
+ *  is signed out, the predicate returns `false` for every code — so
+ *  callers default to "not allowed" which is the safe fallback for
+ *  RBAC gating.
+ *
+ *  Returning a function (not a boolean) is deliberate: a single
+ *  call site can check several codes against one query subscription,
+ *  matching the pattern in issue #40:
+ *
+ *  ```tsx
+ *  const hasPerm = usePerm();
+ *  if (hasPerm('commission.view.all')) return <Admin />;
+ *  if (hasPerm('commission.view.own')) return <SelfCommissions />;
+ *  ```
+ */
+export function usePerm() {
+    const { data: me } = useMe();
+    return useCallback((code) => (me?.permissions ?? []).includes(code), [me?.permissions]);
+}
+/** Convenience: does the signed-in user hold the named role? Returns
+ *  `false` while loading and when signed out, mirroring `usePerm`. */
+export function useRole(code) {
+    const { data: me } = useMe();
+    return (me?.roles ?? []).includes(code);
+}
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"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"}

package/dist/vite/index.d.ts

@@ -0,0 +1,36 @@
+export interface HostBundleConfigOptions {
+    /** Path to the host bundle's entry. Resolved against the directory
+     *  containing the `vite.config.ts` that calls this factory. */
+    entry: string;
+    /** Output filename for the built bundle. Default `'main.js'` —
+     *  matches atrium's documented `system.host_bundle_url` of
+     *  `/host/main.js`. */
+    fileName?: string;
+    /** Output directory inside the host's frontend project. Default
+     *  `'dist'` — matches Vite's default and the `COPY --from=frontend-builder
+     *  /app/dist /opt/atrium/static/host` Dockerfile pattern. */
+    outDir?: string;
+    /** Include sourcemaps in the build. Default `true` — they are tiny
+     *  next to the bundle and make production debugging tractable. */
+    sourcemap?: boolean;
+    /** Override the JS target. Default `'es2022'`. */
+    target?: string;
+    /** Extra Vite config to merge on top of the defaults. Plugins are
+     *  appended; everything else uses Vite's standard merge semantics. */
+    extraConfig?: Record<string, unknown>;
+}
+/** Build a Vite config for an atrium host bundle.
+ *
+ *  Usage in the host's `vite.config.ts`:
+ *
+ *  ```ts
+ *  import { hostBundleConfig } from '@brendanbank/atrium-host-bundle-utils/vite';
+ *
+ *  export default hostBundleConfig({ entry: 'src/main.tsx' });
+ *  ```
+ *
+ *  The factory is async because it lazy-imports `vite` and the css
+ *  injection plugin so they can stay optional peer deps.
+ */
+export declare function hostBundleConfig(options: HostBundleConfigOptions): Promise<Record<string, unknown>>;
+//# sourceMappingURL=index.d.ts.map

package/dist/vite/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vite/index.ts"],"names":[],"mappings":"AAwCA,MAAM,WAAW,uBAAuB;IACtC;mEAC+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd;;2BAEuB;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;iEAE6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;sEACkE;IAClE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;0EACsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAiDlC"}

package/dist/vite/index.js

@@ -0,0 +1,85 @@
+// Copyright (c) 2026 Brendan Bank
+// SPDX-License-Identifier: BSD-2-Clause
+/**
+ * Vite preset for atrium host bundles.
+ *
+ * Imported only by `vite.config.ts`, never by runtime code, so Vite
+ * stays out of the host's production bundle. Vite + the css-injection
+ * plugin are declared as optional peer deps; install them only when
+ * building (typical: as devDependencies in the host's
+ * `frontend/package.json`).
+ *
+ * The preset returns a complete Vite config that:
+ *
+ *  - Builds in library mode (`build.lib`) emitting a single ES module
+ *    at `dist/main.js`. Atrium's loader does
+ *    `import(system.host_bundle_url)` with that URL — no IIFE / UMD
+ *    needed.
+ *  - Inlines every imported `.css` via a runtime `<style>` tag
+ *    (`vite-plugin-css-injected-by-js`). Without this Vite extracts
+ *    CSS to a sibling `main.css` that atrium's dynamic-import never
+ *    fetches, and Mantine / FullCalendar / any rich-text editor ships
+ *    silently unstyled.
+ *  - Defines `process.env.NODE_ENV` so the externalised React +
+ *    TanStack Query references resolve in lib-mode builds (Vite's
+ *    app-mode auto-replaces this; lib-mode does not).
+ *
+ *  Hosts can override anything by passing `extraConfig` (merged into
+ *  the returned object) — typical use: a host needing a SVG plugin or
+ *  a dev-only proxy. The defaults match the canonical
+ *  self-contained-bundle pattern documented in
+ *  `docs/published-images.md`.
+ */
+import { resolve } from 'node:path';
+/** Build a Vite config for an atrium host bundle.
+ *
+ *  Usage in the host's `vite.config.ts`:
+ *
+ *  ```ts
+ *  import { hostBundleConfig } from '@brendanbank/atrium-host-bundle-utils/vite';
+ *
+ *  export default hostBundleConfig({ entry: 'src/main.tsx' });
+ *  ```
+ *
+ *  The factory is async because it lazy-imports `vite` and the css
+ *  injection plugin so they can stay optional peer deps.
+ */
+export async function hostBundleConfig(options) {
+    const { entry, fileName = 'main.js', outDir = 'dist', sourcemap = true, target = 'es2022', extraConfig = {}, } = options;
+    const [vite, cssInjectedByJs] = await Promise.all([
+        import('vite'),
+        import('vite-plugin-css-injected-by-js'),
+    ]);
+    const mergeConfig = vite.mergeConfig;
+    const cssPluginFactory = (cssInjectedByJs.default ??
+        cssInjectedByJs);
+    // Build the config as a plain object — `defineConfig` is only a
+    // typing helper, and its strict `Plugin` typing fights the
+    // dynamically-imported CSS plugin. The merged config is what Vite
+    // actually consumes at build time.
+    const base = {
+        // Lib-mode builds don't auto-replace `process.env.NODE_ENV` the
+        // way Vite's app-mode builds do, and several deps (React internals,
+        // TanStack Query) reference it. Without these defines the bundle
+        // throws `ReferenceError: process is not defined` the moment the
+        // SPA dynamic-imports it.
+        define: {
+            'process.env.NODE_ENV': JSON.stringify('production'),
+            'process.env': '{}',
+        },
+        plugins: [cssPluginFactory()],
+        build: {
+            target,
+            lib: {
+                entry: resolve(process.cwd(), entry),
+                formats: ['es'],
+                fileName: () => fileName,
+            },
+            outDir,
+            emptyOutDir: true,
+            sourcemap,
+        },
+    };
+    return mergeConfig(base, extraConfig);
+}
+//# sourceMappingURL=index.js.map

package/dist/vite/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/vite/index.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,wCAAwC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6BpC;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAgC;IAEhC,MAAM,EACJ,KAAK,EACL,QAAQ,GAAG,SAAS,EACpB,MAAM,GAAG,MAAM,EACf,SAAS,GAAG,IAAI,EAChB,MAAM,GAAG,QAAQ,EACjB,WAAW,GAAG,EAAE,GACjB,GAAG,OAAO,CAAC;IAEZ,MAAM,CAAC,IAAI,EAAE,eAAe,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAChD,MAAM,CAAC,MAAM,CAAC;QACd,MAAM,CAAC,gCAAgC,CAAC;KACzC,CAAC,CAAC;IAEH,MAAM,WAAW,GAAI,IAA6D,CAAC,WAAW,CAAC;IAC/F,MAAM,gBAAgB,GACpB,CAAE,eAA0D,CAAC,OAAO;QACjE,eAA4C,CAAkB,CAAC;IAEpE,gEAAgE;IAChE,2DAA2D;IAC3D,kEAAkE;IAClE,mCAAmC;IACnC,MAAM,IAAI,GAA4B;QACpC,gEAAgE;QAChE,oEAAoE;QACpE,iEAAiE;QACjE,iEAAiE;QACjE,0BAA0B;QAC1B,MAAM,EAAE;YACN,sBAAsB,EAAE,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC;YACpD,aAAa,EAAE,IAAI;SACpB;QACD,OAAO,EAAE,CAAC,gBAAgB,EAAE,CAAC;QAC7B,KAAK,EAAE;YACL,MAAM;YACN,GAAG,EAAE;gBACH,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,KAAK,CAAC;gBACpC,OAAO,EAAE,CAAC,IAAI,CAAC;gBACf,QAAQ,EAAE,GAAG,EAAE,CAAC,QAAQ;aACzB;YACD,MAAM;YACN,WAAW,EAAE,IAAI;YACjB,SAAS;SACV;KACF,CAAC;IAEF,OAAO,WAAW,CAAC,IAAI,EAAE,WAAW,CAA4B,CAAC;AACnE,CAAC"}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@brendanbank/atrium-host-bundle-utils",
+  "version": "0.15.0",
+  "description": "Runtime helpers, Vite preset, and React hooks for atrium host bundles. Wraps the dual-tree mount pattern, the host-bundle Vite library config, and the /users/me/context hook so a host's main.tsx is ~10 lines of registration calls.",
+  "license": "BSD-2-Clause",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./vite": {
+      "types": "./dist/vite/index.d.ts",
+      "default": "./dist/vite/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
+    }
+  },
+  "dependencies": {
+    "@brendanbank/atrium-host-types": "0.15.0"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0",
+    "vite-plugin-css-injected-by-js": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    },
+    "vite-plugin-css-injected-by-js": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.100.5",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^25.6.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "jsdom": "^29.0.2",
+    "msw": "^2.7.0",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.10",
+    "vite-plugin-css-injected-by-js": "^3.5.2",
+    "vitest": "^4.1.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/brendanbank/atrium.git",
+    "directory": "packages/host-bundle-utils"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  }
+}