@molecule/app-react 1.0.0

package/dist/hooks/useTranslation.js

@@ -0,0 +1,131 @@
+/**
+ * React hook for internationalization.
+ *
+ * @module
+ */
+import { useCallback, useContext, useEffect, useState } from 'react';
+import { I18nError, t } from '@molecule/app-i18n';
+import { I18nContext } from '../contexts.js';
+/**
+ * Hook to access the i18n provider from context.
+ *
+ * @returns The i18n provider from context
+ * @throws {Error} Error if used outside of I18nProvider
+ */
+export function useI18nProvider() {
+    const provider = useContext(I18nContext);
+    if (!provider) {
+        throw new Error(t('react.error.useI18nOutsideProvider', undefined, {
+            defaultValue: 'useI18nProvider must be used within an I18nProvider',
+        }));
+    }
+    return provider;
+}
+/**
+ * Hook for internationalization.
+ *
+ * @returns Translation function and locale management
+ *
+ * @example
+ * ```tsx
+ * const { t, locale, setLocale, formatNumber } = useTranslation()
+ *
+ * return (
+ *   <div>
+ *     <h1>{t('welcome.title', { name: 'User' })}</h1>
+ *     <p>{formatNumber(1234.56, { style: 'currency', currency: 'USD' })}</p>
+ *     <select value={locale} onChange={(e) => setLocale(e.target.value)}>
+ *       <option value="en">English</option>
+ *       <option value="es">Spanish</option>
+ *     </select>
+ *   </div>
+ * )
+ * ```
+ */
+export function useTranslation() {
+    const provider = useI18nProvider();
+    const [locale, setLocaleState] = useState(() => provider.getLocale());
+    const [direction, setDirection] = useState(() => provider.getDirection());
+    const [locales, setLocales] = useState(() => provider.getLocales());
+    const [, forceUpdate] = useState({});
+    useEffect(() => {
+        const unsubscribe = provider.onLocaleChange(() => {
+            setLocaleState(provider.getLocale());
+            setDirection(provider.getDirection());
+            setLocales(provider.getLocales());
+            // Force re-render even when locale string is unchanged (e.g. when
+            // addTranslations adds new keys for the current locale).
+            forceUpdate({});
+        });
+        return unsubscribe;
+    }, [provider]);
+    // Memoized translation function
+    const t = useCallback((key, values, options) => provider.t(key, values, options), [provider, locale]);
+    // Memoized action wrappers
+    const setLocale = useCallback((code) => provider.setLocale(code), [provider]);
+    const formatNumber = useCallback((value, options) => provider.formatNumber(value, options), [provider]);
+    const formatDate = useCallback((value, options) => provider.formatDate(value, options), [provider]);
+    return {
+        t,
+        locale,
+        setLocale,
+        locales,
+        formatNumber,
+        formatDate,
+        direction,
+    };
+}
+/**
+ * Hook to get just the translation function.
+ *
+ * @returns The translation function
+ */
+export function useT() {
+    const provider = useI18nProvider();
+    return useCallback((key, values, options) => provider.t(key, values, options), [provider]);
+}
+/**
+ * Hook to get the current locale.
+ *
+ * @returns The current locale code
+ */
+export function useLocale() {
+    const { locale } = useTranslation();
+    return locale;
+}
+/**
+ * Hook to get the text direction.
+ *
+ * @returns The text direction ('ltr' or 'rtl')
+ */
+export function useDirection() {
+    const { direction } = useTranslation();
+    return direction;
+}
+/**
+ * Translates an error at render time so the displayed message updates automatically
+ * when the locale changes.
+ *
+ * **Always use this hook to display errors in React components** — accessing
+ * `error.message` directly bypasses re-translation and leaves stale text after a
+ * locale switch. If `error` is an `I18nError` (thrown via `throw new I18nError(key)`),
+ * its key is translated using the current locale. For plain `Error` instances,
+ * `error.message` is returned unchanged.
+ *
+ * @param error - The error to translate, or `null`/`undefined`.
+ * @returns The translated error string, or `null` if no error.
+ */
+export function useI18nError(error) {
+    const { t } = useTranslation();
+    if (!error)
+        return null;
+    // defaultValue is the I18nError's own message — the fallback text its throw
+    // site provided (for a server error: the server's already-translated
+    // message). Without it, a key the CLIENT dictionary happens to lack renders
+    // as the raw key ("user.error.passwordTooShort") instead of a message.
+    if (error instanceof I18nError) {
+        return t(error.i18nKey, error.i18nValues, { defaultValue: error.message });
+    }
+    return error.message;
+}
+//# sourceMappingURL=useTranslation.js.map

package/dist/hooks/useTranslation.js.map

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

package/dist/hooks/useVersion.d.ts

@@ -0,0 +1,41 @@
+/**
+ * React hook for version and update management.
+ *
+ * @module
+ */
+import type { UpdateCheckOptions, VersionState } from '@molecule/app-version';
+/**
+ * Hook return type.
+ */
+export interface UseVersionResult {
+    state: VersionState;
+    isUpdateAvailable: boolean;
+    isChecking: boolean;
+    isServiceWorkerWaiting: boolean;
+    newVersion: string | undefined;
+    checkForUpdates: () => Promise<boolean>;
+    applyUpdate: (options?: {
+        force?: boolean;
+    }) => void;
+    dismissUpdate: () => void;
+    startPeriodicChecks: (options?: UpdateCheckOptions) => void;
+    stopPeriodicChecks: () => void;
+}
+/**
+ * Hook for version state and update actions.
+ *
+ * Uses module-level `getProvider()` — version is a singleton, not context-provided.
+ *
+ * @returns Version state and action methods
+ *
+ * @example
+ * ```tsx
+ * const { isUpdateAvailable, newVersion, applyUpdate, dismissUpdate } = useVersion()
+ *
+ * if (isUpdateAvailable) {
+ *   return <div>Update to {newVersion} available! <button onClick={() => applyUpdate()}>Update</button></div>
+ * }
+ * ```
+ */
+export declare function useVersion(): UseVersionResult;
+//# sourceMappingURL=useVersion.d.ts.map

package/dist/hooks/useVersion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useVersion.d.ts","sourceRoot":"","sources":["../../src/hooks/useVersion.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAG7E;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,YAAY,CAAA;IACnB,iBAAiB,EAAE,OAAO,CAAA;IAC1B,UAAU,EAAE,OAAO,CAAA;IACnB,sBAAsB,EAAE,OAAO,CAAA;IAC/B,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,eAAe,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;IACvC,WAAW,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAA;IACpD,aAAa,EAAE,MAAM,IAAI,CAAA;IACzB,mBAAmB,EAAE,CAAC,OAAO,CAAC,EAAE,kBAAkB,KAAK,IAAI,CAAA;IAC3D,kBAAkB,EAAE,MAAM,IAAI,CAAA;CAC/B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,IAAI,gBAAgB,CAiE7C"}

package/dist/hooks/useVersion.js

@@ -0,0 +1,73 @@
+/**
+ * React hook for version and update management.
+ *
+ * @module
+ */
+import { useCallback, useRef, useSyncExternalStore } from 'react';
+import { getProvider } from '@molecule/app-version';
+/**
+ * Hook for version state and update actions.
+ *
+ * Uses module-level `getProvider()` — version is a singleton, not context-provided.
+ *
+ * @returns Version state and action methods
+ *
+ * @example
+ * ```tsx
+ * const { isUpdateAvailable, newVersion, applyUpdate, dismissUpdate } = useVersion()
+ *
+ * if (isUpdateAvailable) {
+ *   return <div>Update to {newVersion} available! <button onClick={() => applyUpdate()}>Update</button></div>
+ * }
+ * ```
+ */
+export function useVersion() {
+    const provider = getProvider();
+    // Cached ref for snapshot stability (prevents infinite re-renders with useSyncExternalStore)
+    const cachedStateRef = useRef(null);
+    const getSnapshot = useCallback(() => {
+        const next = provider.getState();
+        const prev = cachedStateRef.current;
+        if (prev !== null &&
+            prev.isUpdateAvailable === next.isUpdateAvailable &&
+            prev.isChecking === next.isChecking &&
+            prev.isServiceWorkerWaiting === next.isServiceWorkerWaiting &&
+            prev.newVersion === next.newVersion &&
+            prev.buildId === next.buildId &&
+            prev.version === next.version) {
+            return prev;
+        }
+        cachedStateRef.current = next;
+        return next;
+    }, [provider]);
+    const subscribe = useCallback((onStateChange) => {
+        const unsubs = [
+            provider.on('update-available', onStateChange),
+            provider.on('service-worker-waiting', onStateChange),
+            provider.on('service-worker-activated', onStateChange),
+            provider.on('check-start', onStateChange),
+            provider.on('check-complete', onStateChange),
+            provider.on('check-error', onStateChange),
+        ];
+        return () => unsubs.forEach((unsub) => unsub());
+    }, [provider]);
+    const state = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+    const checkForUpdates = useCallback(() => provider.checkForUpdates(), [provider]);
+    const applyUpdate = useCallback((options) => provider.applyUpdate(options), [provider]);
+    const dismissUpdate = useCallback(() => provider.dismissUpdate(), [provider]);
+    const startPeriodicChecks = useCallback((options) => provider.startPeriodicChecks(options), [provider]);
+    const stopPeriodicChecks = useCallback(() => provider.stopPeriodicChecks(), [provider]);
+    return {
+        state,
+        isUpdateAvailable: state.isUpdateAvailable,
+        isChecking: state.isChecking,
+        isServiceWorkerWaiting: state.isServiceWorkerWaiting,
+        newVersion: state.newVersion,
+        checkForUpdates,
+        applyUpdate,
+        dismissUpdate,
+        startPeriodicChecks,
+        stopPeriodicChecks,
+    };
+}
+//# sourceMappingURL=useVersion.js.map

package/dist/hooks/useVersion.js.map

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

package/dist/hooks/useWorkspace.d.ts

@@ -0,0 +1,18 @@
+/**
+ * React hook for IDE workspace provider.
+ *
+ * @module
+ */
+import type { WorkspaceProvider } from '@molecule/app-ide';
+import type { UseWorkspaceResult } from '../types.js';
+/**
+ * Access the workspace provider from context.
+ * @returns The result.
+ */
+export declare function useWorkspaceProvider(): WorkspaceProvider;
+/**
+ * Hook for IDE workspace layout management.
+ * @returns The workspace state and management methods.
+ */
+export declare function useWorkspace(): UseWorkspaceResult;
+//# sourceMappingURL=useWorkspace.d.ts.map

package/dist/hooks/useWorkspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useWorkspace.d.ts","sourceRoot":"","sources":["../../src/hooks/useWorkspace.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAW,iBAAiB,EAAkB,MAAM,mBAAmB,CAAA;AAGnF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAErD;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,iBAAiB,CAUxD;AAED;;;GAGG;AACH,wBAAgB,YAAY,IAAI,kBAAkB,CAyDjD"}

package/dist/hooks/useWorkspace.js

@@ -0,0 +1,67 @@
+/**
+ * React hook for IDE workspace provider.
+ *
+ * @module
+ */
+import { useCallback, useContext, useRef, useSyncExternalStore } from 'react';
+import { t } from '@molecule/app-i18n';
+import { WorkspaceContext } from '../contexts.js';
+/**
+ * Access the workspace provider from context.
+ * @returns The result.
+ */
+export function useWorkspaceProvider() {
+    const provider = useContext(WorkspaceContext);
+    if (!provider) {
+        throw new Error(t('react.error.useWorkspaceOutsideProvider', undefined, {
+            defaultValue: 'useWorkspaceProvider must be used within a WorkspaceProvider',
+        }));
+    }
+    return provider;
+}
+/**
+ * Hook for IDE workspace layout management.
+ * @returns The workspace state and management methods.
+ */
+export function useWorkspace() {
+    const provider = useWorkspaceProvider();
+    const cachedRef = useRef(null);
+    const getSnapshot = useCallback(() => {
+        const layout = provider.getLayout();
+        // Create a state object — provider.subscribe gives us the full WorkspaceState
+        // but getLayout only gives us the layout. Use a lightweight cache comparison.
+        const prev = cachedRef.current;
+        if (prev && prev.layout === layout) {
+            return prev;
+        }
+        const next = {
+            layout,
+            activePanel: null,
+            collapsedPanels: new Set(),
+            isFullscreen: false,
+        };
+        cachedRef.current = next;
+        return next;
+    }, [provider]);
+    const subscribe = useCallback((onStoreChange) => {
+        return provider.subscribe((state) => {
+            cachedRef.current = state;
+            onStoreChange();
+        });
+    }, [provider]);
+    const state = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+    const togglePanel = useCallback((panelId) => provider.togglePanel(panelId), [provider]);
+    const resizePanel = useCallback((panelId, size) => provider.resizePanel(panelId, size), [provider]);
+    const setActivePanel = useCallback((panelId) => provider.setActivePanel(panelId), [provider]);
+    const resetLayout = useCallback(() => provider.resetLayout(), [provider]);
+    return {
+        layout: state.layout,
+        activePanel: state.activePanel,
+        collapsedPanels: state.collapsedPanels,
+        togglePanel,
+        resizePanel,
+        setActivePanel,
+        resetLayout,
+    };
+}
+//# sourceMappingURL=useWorkspace.js.map

package/dist/hooks/useWorkspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useWorkspace.js","sourceRoot":"","sources":["../../src/hooks/useWorkspace.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAA;AAE7E,OAAO,EAAE,CAAC,EAAE,MAAM,oBAAoB,CAAA;AAGtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAGjD;;;GAGG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,QAAQ,GAAG,UAAU,CAAC,gBAAgB,CAAC,CAAA;IAC7C,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CACb,CAAC,CAAC,yCAAyC,EAAE,SAAS,EAAE;YACtD,YAAY,EAAE,8DAA8D;SAC7E,CAAC,CACH,CAAA;IACH,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,QAAQ,GAAG,oBAAoB,EAAE,CAAA;IACvC,MAAM,SAAS,GAAG,MAAM,CAAwB,IAAI,CAAC,CAAA;IAErD,MAAM,WAAW,GAAG,WAAW,CAAC,GAAG,EAAE;QACnC,MAAM,MAAM,GAAG,QAAQ,CAAC,SAAS,EAAE,CAAA;QACnC,8EAA8E;QAC9E,8EAA8E;QAC9E,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAA;QAC9B,IAAI,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YACnC,OAAO,IAAI,CAAA;QACb,CAAC;QACD,MAAM,IAAI,GAAmB;YAC3B,MAAM;YACN,WAAW,EAAE,IAAI;YACjB,eAAe,EAAE,IAAI,GAAG,EAAE;YAC1B,YAAY,EAAE,KAAK;SACpB,CAAA;QACD,SAAS,CAAC,OAAO,GAAG,IAAI,CAAA;QACxB,OAAO,IAAI,CAAA;IACb,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAA;IAEd,MAAM,SAAS,GAAG,WAAW,CAC3B,CAAC,aAAyB,EAAE,EAAE;QAC5B,OAAO,QAAQ,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;YAClC,SAAS,CAAC,OAAO,GAAG,KAAK,CAAA;YACzB,aAAa,EAAE,CAAA;QACjB,CAAC,CAAC,CAAA;IACJ,CAAC,EACD,CAAC,QAAQ,CAAC,CACX,CAAA;IAED,MAAM,KAAK,GAAG,oBAAoB,CAAC,SAAS,EAAE,WAAW,EAAE,WAAW,CAAC,CAAA;IAEvE,MAAM,WAAW,GAAG,WAAW,CAAC,CAAC,OAAgB,EAAE,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAA;IAEhG,MAAM,WAAW,GAAG,WAAW,CAC7B,CAAC,OAAgB,EAAE,IAAY,EAAE,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,EACvE,CAAC,QAAQ,CAAC,CACX,CAAA;IAED,MAAM,cAAc,GAAG,WAAW,CAChC,CAAC,OAAgB,EAAE,EAAE,CAAC,QAAQ,CAAC,cAAc,CAAC,OAAO,CAAC,EACtD,CAAC,QAAQ,CAAC,CACX,CAAA;IAED,MAAM,WAAW,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,WAAW,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAA;IAEzE,OAAO;QACL,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,eAAe,EAAE,KAAK,CAAC,eAAe;QACtC,WAAW;QACX,WAAW;QACX,cAAc;QACd,WAAW;KACZ,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * React framework bindings for the Molecule app stack.
+ *
+ * Provides React hooks, contexts, and provider components for all molecule
+ * core interfaces (auth, i18n, theme, routing, state, http, storage, logger,
+ * chat, workspace, editor, preview), so framework-agnostic providers plug
+ * into React idioms.
+ *
+ * @example
+ * ```tsx
+ * import { MoleculeProvider, useAuth, useTheme, useTranslation } from '@molecule/app-react'
+ * import { provider as stateProvider } from '@molecule/app-state-zustand'
+ * import { provider as themeProvider } from '@molecule/app-theme-css-variables'
+ * import { provider as i18nProvider } from '@molecule/app-i18n-react-i18next'
+ * import { createJWTAuthClient } from '@molecule/app-auth'
+ *
+ * const authClient = createJWTAuthClient({ baseURL: '/api' })
+ *
+ * function Dashboard() {
+ *   const { user, isAuthenticated, logout } = useAuth<{ name?: string }>()
+ *   const { t } = useTranslation()
+ *   const { theme, toggleTheme } = useTheme()
+ *
+ *   if (!isAuthenticated) {
+ *     return <p>{t('auth.required', undefined, { defaultValue: 'Please log in.' })}</p>
+ *   }
+ *   return (
+ *     <div style={{ background: theme.colors.background }}>
+ *       <h1>{t('greeting.welcome', { name: user?.name }, { defaultValue: 'Welcome, {{name}}!' })}</h1>
+ *       <button onClick={toggleTheme}>{t('theme.toggle', undefined, { defaultValue: 'Toggle theme' })}</button>
+ *       <button onClick={() => logout()}>{t('auth.logout', undefined, { defaultValue: 'Log out' })}</button>
+ *     </div>
+ *   )
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <MoleculeProvider
+ *       state={stateProvider}
+ *       auth={authClient}
+ *       theme={themeProvider}
+ *       i18n={i18nProvider}
+ *     >
+ *       <Dashboard />
+ *     </MoleculeProvider>
+ *   )
+ * }
+ * ```
+ *
+ * @remarks
+ * - **Every hook throws when its provider is not mounted.** `MoleculeProvider` wires ONLY the
+ *   services you pass as props — it is a convenience wrapper, not a default registry. The map:
+ *   `useAuth`→`auth`, `useTranslation`/`useT`→`i18n`, `useTheme`→`theme`, `useRouter`→`router`,
+ *   `useStore`→`state`, `useHttp`→`http`, `useStorage`→`storage`, `useLogger`→`logger`,
+ *   `useChat`→`chat`, `useWorkspace`→`workspace`, `useEditor`→`editor`, `usePreview`→`preview`.
+ *   "useXProvider must be used within an XProvider" means the matching prop (or individual
+ *   provider component) is missing ABOVE the component that calls the hook — fix the wiring,
+ *   never wrap the hook in try/catch.
+ * - **Locale-reactive text requires the hook.** Inside components always read `t` from
+ *   `useTranslation()` (or `useT()`); it re-renders on `onLocaleChange` — even when
+ *   `addTranslations()` only adds keys for the current locale. Calling the raw `t()` import from
+ *   `@molecule/app-i18n` in render works once but leaves stale text after a locale switch.
+ * - **Exactly one React copy.** In workspace/symlinked dev setups a second React instance makes
+ *   every hook fail ("Invalid hook call", or the provider errors above with the provider
+ *   mounted). Scaffolded Vite configs ship
+ *   `resolve.dedupe: ['react', 'react-dom', 'react-router', 'react-router']` — keep it, and
+ *   add any new hook-bearing peer library there too.
+ * - `RouterProvider` carries a molecule `Router` (e.g. `createReactRouter()` from
+ *   `@molecule/app-routing-react-router`). react-router's own `<BrowserRouter>` context is
+ *   separate — components that render react-router `<Link>` (several in
+ *   `@molecule/app-ui-react`) need it in addition to the molecule providers.
+ *
+ * @module
+ */
+export * from './agent-identity.js';
+export * from './contexts.js';
+export * from './hooks/index.js';
+export * from './providers.js';
+export * from './types.js';
+//# 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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,kBAAkB,CAAA;AAChC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,80 @@
+/**
+ * React framework bindings for the Molecule app stack.
+ *
+ * Provides React hooks, contexts, and provider components for all molecule
+ * core interfaces (auth, i18n, theme, routing, state, http, storage, logger,
+ * chat, workspace, editor, preview), so framework-agnostic providers plug
+ * into React idioms.
+ *
+ * @example
+ * ```tsx
+ * import { MoleculeProvider, useAuth, useTheme, useTranslation } from '@molecule/app-react'
+ * import { provider as stateProvider } from '@molecule/app-state-zustand'
+ * import { provider as themeProvider } from '@molecule/app-theme-css-variables'
+ * import { provider as i18nProvider } from '@molecule/app-i18n-react-i18next'
+ * import { createJWTAuthClient } from '@molecule/app-auth'
+ *
+ * const authClient = createJWTAuthClient({ baseURL: '/api' })
+ *
+ * function Dashboard() {
+ *   const { user, isAuthenticated, logout } = useAuth<{ name?: string }>()
+ *   const { t } = useTranslation()
+ *   const { theme, toggleTheme } = useTheme()
+ *
+ *   if (!isAuthenticated) {
+ *     return <p>{t('auth.required', undefined, { defaultValue: 'Please log in.' })}</p>
+ *   }
+ *   return (
+ *     <div style={{ background: theme.colors.background }}>
+ *       <h1>{t('greeting.welcome', { name: user?.name }, { defaultValue: 'Welcome, {{name}}!' })}</h1>
+ *       <button onClick={toggleTheme}>{t('theme.toggle', undefined, { defaultValue: 'Toggle theme' })}</button>
+ *       <button onClick={() => logout()}>{t('auth.logout', undefined, { defaultValue: 'Log out' })}</button>
+ *     </div>
+ *   )
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <MoleculeProvider
+ *       state={stateProvider}
+ *       auth={authClient}
+ *       theme={themeProvider}
+ *       i18n={i18nProvider}
+ *     >
+ *       <Dashboard />
+ *     </MoleculeProvider>
+ *   )
+ * }
+ * ```
+ *
+ * @remarks
+ * - **Every hook throws when its provider is not mounted.** `MoleculeProvider` wires ONLY the
+ *   services you pass as props — it is a convenience wrapper, not a default registry. The map:
+ *   `useAuth`→`auth`, `useTranslation`/`useT`→`i18n`, `useTheme`→`theme`, `useRouter`→`router`,
+ *   `useStore`→`state`, `useHttp`→`http`, `useStorage`→`storage`, `useLogger`→`logger`,
+ *   `useChat`→`chat`, `useWorkspace`→`workspace`, `useEditor`→`editor`, `usePreview`→`preview`.
+ *   "useXProvider must be used within an XProvider" means the matching prop (or individual
+ *   provider component) is missing ABOVE the component that calls the hook — fix the wiring,
+ *   never wrap the hook in try/catch.
+ * - **Locale-reactive text requires the hook.** Inside components always read `t` from
+ *   `useTranslation()` (or `useT()`); it re-renders on `onLocaleChange` — even when
+ *   `addTranslations()` only adds keys for the current locale. Calling the raw `t()` import from
+ *   `@molecule/app-i18n` in render works once but leaves stale text after a locale switch.
+ * - **Exactly one React copy.** In workspace/symlinked dev setups a second React instance makes
+ *   every hook fail ("Invalid hook call", or the provider errors above with the provider
+ *   mounted). Scaffolded Vite configs ship
+ *   `resolve.dedupe: ['react', 'react-dom', 'react-router', 'react-router']` — keep it, and
+ *   add any new hook-bearing peer library there too.
+ * - `RouterProvider` carries a molecule `Router` (e.g. `createReactRouter()` from
+ *   `@molecule/app-routing-react-router`). react-router's own `<BrowserRouter>` context is
+ *   separate — components that render react-router `<Link>` (several in
+ *   `@molecule/app-ui-react`) need it in addition to the molecule providers.
+ *
+ * @module
+ */
+export * from './agent-identity.js';
+export * from './contexts.js';
+export * from './hooks/index.js';
+export * from './providers.js';
+export * from './types.js';
+//# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,eAAe,CAAA;AAC7B,cAAc,kBAAkB,CAAA;AAChC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA"}