tempest-react-sdk 0.22.0 → 0.23.0

package/README.md

@@ -169,7 +169,7 @@ The minimum install is just:
 npm install tempest-react-sdk react react-dom
 ```
 
-**Bundle impact**: every bundled dep is externalised in the SDK's Rollup config, so the SDK's published bundle stays at ~104 KB ESM. Your app's bundler (Vite / webpack / Rspack) resolves these from `node_modules` and tree-shakes — if you never call `createOfflineStore`, Dexie never enters your final bundle.
+**Bundle impact**: every bundled dep is externalised in the SDK's Rollup config, and `dist/` ships with the module graph preserved (one file per source module), so your bundler drops what you don't import instead of inheriting one opaque blob — importing `cn` alone costs **118 B** brotli, a full app shell around **6.8 KB**. Your app's bundler (Vite / webpack / Rspack) resolves the deps from `node_modules` and tree-shakes them the same way — if you never call `createOfflineStore`, Dexie never enters your final bundle.
 
 **Version conflicts**: if your app already pins (say) `zod@3.20`, npm dedupes when the range is compatible. If ranges diverge you get two copies — pin a single version in your own `package.json` to force one, or open an issue if the SDK's range is too tight.
 
@@ -193,67 +193,69 @@ The styles ship hashed under the `tempest_` namespace — they do **not** collid
 
 Every module is re-exported from the package root — `import { Button, useDebounce, createApiClient } from "tempest-react-sdk"` always works.
 
-| Module                                                                                            | Exports                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `components`                                                                                      | `Avatar`, `Badge`, `Breadcrumbs`, `Button`, `Card`, `Checkbox`, `ChipInput`, `ConfirmDialog`, `Container`, `DatePicker`, `Drawer`, `EmptyState`, `ErrorState`, `FileUpload`, `Form` (`FormSection`, `FormRow`, `FormActions`), `Grid`, `Input`, `InstallBanner`, `InstallButton`, `Modal`, `Pagination`, `Progress`, `Radio`, `RadioGroup`, `SearchBar`, `Select`, `Skeleton`, `Spinner`, `Stack`, `Stepper`, `Switch`, `Table`, `Tabs`, `Textarea`, `Toast` (`ToastProvider`, `useToast`), `Tooltip`, `VirtualList`                                                                                                                                         |
-| `hooks`                                                                                           | `useDebounce`, `usePagination`, `useClientFilter`, `useMediaQuery`, `useOnline`, `useDocumentVisibility`, `useIntersectionObserver`, `useResizeObserver`, `useClipboard`, `useKeyboardShortcut`, `useBeforeInstallPrompt`, `useIdle`, `useGeolocation`, `useScrollLock`, `useFocusTrap`, `useStableCallback`, `useDeepMemo`, `useObjectUrl`, `useLongPressHandlers` (spreadable long-press handlers + `wasLongPress()` guard), `useInstallPrompt` (install-method resolver with decline cooldown), PWA env helpers `isIOS`/`isAndroid`/`isAndroidWithoutPromptApi`/`isStandalone`/`buildOpenInChromeIntent`, type `BeforeInstallPromptEvent`                 |
-| `http`                                                                                            | `createApiClient`, `parseResponse`, `uploadWithProgress`, `retry`, `generateIdempotencyKey`, `usePoll`, types: `ApiClient`, `ApiClientConfig`, `ApiError`, `RequestOptions`, `RetryOptions`, `UploadProgressEvent`, `UploadWithProgressOptions`, `UsePollOptions`, `UsePollResult`                                                                                                                                                                                                                                                                                                                                                                           |
-| `auth` _(peer: `zustand`)_                                                                        | `createAuthStore`, `AuthGuard`, `decodeJWT`, `isJWTExpired`, `lazyWithRetry`, `createRefreshQueue`, types: `AuthState`, `CreateAuthStoreOptions`, `AuthGuardProps`, `DecodedJWT`, `LazyWithRetryOptions`                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `query` _(peer: `@tanstack/react-query`)_                                                         | `QueryProvider`, `createQueryKeys`, `STALE_TIME`, `CACHE_TIME`, `REFETCH_TIME`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `router` _(dep: `react-router-dom`)_                                                              | `defineRoutes`, `AppRouter`, `RouteGuard`, + re-exports (`Link`, `NavLink`, `Outlet`, `Navigate`, `useNavigate`, `useParams`, `useSearchParams`, `useLocation`, `useMatch`, `useRouteError`, `redirect`, `BrowserRouter`/`HashRouter`/`MemoryRouter`/`Routes`/`Route`), types: `TempestRouteObject`, `RouterKind`, `AppRouterProps`, `RouteGuardProps`                                                                                                                                                                                                                                                                                                       |
-| `store` _(dep: `zustand`)_                                                                        | `createStore`, `createSelectors`, types: `CreateStoreOptions`, `CreateStorePersistOptions`, `WithSelectors`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `app`                                                                                             | `AppProviders` (composes `ErrorBoundary` → `QueryProvider` → `ThemeProvider` → `I18nProvider`), type: `AppProvidersProps`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `vite` _(subpath `tempest-react-sdk/vite`)_                                                       | `createViteConfig`, `tempestPwaManifest` (emits `precache-manifest.json` for offline precache), `tempestPwaIcons` (generates the PNG icon set from one SVG via `sharp`), `tempestPwaDevSw` (serves the SW under `npm run dev`), `tempestPwaIcons({ appleSplash })` (Apple splash screens), types: `CreateViteConfigOptions`, `ProxyEntry`, `TempestViteConfig`, `TempestPwaManifestOptions`, `TempestPwaIconsOptions`, `TempestPwaDevSwOptions`, `AppleSplashSpec`, `TempestVitePlugin`                                                                                                                                                                      |
-| `forms` _(peer: `zod`, `react-hook-form`)_                                                        | `validateForm`, `zodResolver`, `useZodForm`, `validateCPF`, `validateCNPJ`, `formatCEP`, `formatCNPJ`, `unmask`, `CPFInput`, `CNPJInput`, `PhoneInput`, `CEPInput`, `MoneyInput`, `useViaCEP`                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `sse`                                                                                             | `createEventStream`, `useEventStream`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `ws`                                                                                              | `createWebSocket`, `useWebSocket`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `geo` _(opt. peer `leaflet`)_                                                                     | `haversineKm`, `pathLengthKm`, `bearingDeg`, `estimateTravel`, `createOSRMBackend`, `boundingBox`, `projectMercator`, `fitProjection`, `createPositionTracker`, `usePositionTracker`, `TrajectoryMap` — tile-free SVG map + trajectory tracking (no external/paid API; Leaflet is an opt-in, lazy-loaded tile layer for self-hosted tiles), types: `Coordinate`, `TrackPoint`, `TravelEstimate`, `TravelMode`, `GeoBounds`, `RoutingBackend`                                                                                                                                                                                                                 |
-| `br` _(subpath `tempest-react-sdk/br`)_                                                           | `BrazilMap`, `BrazilStateMap`, `BrazilStateCitySelect`, `listStates`, `getState`, `citiesByUf`, `statesByRegion`, `ufChoices`, `cityChoices`, `isValidUf`, `normalizeUf`, `isValidCity`, `loadBrUfGeoJson`, `loadStateMunicipalities`, types `UF`, `BrRegion`, `BrazilState` — clickable 27-UF SVG map + per-state municipality submaps (bundled simplified IBGE GeoJSON, lazy per UF) + states/cities dataset, no external API; mirrors the FastAPI SDK `utils/locations`                                                                                                                                                                                   |
-| `push`                                                                                            | `WebPushClient`, `WebPushUnsupportedError`, `WebPushPermissionDeniedError`, `usePushSubscription`, `urlBase64ToUint8Array`, `isPushSupported`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `sw` _(also subpath `tempest-react-sdk/sw`)_                                                      | `registerServiceWorker` (opt-in `autoUpdate` poll + reload, no `vite-plugin-pwa`), `skipWaiting`, `unregisterAllServiceWorkers`, `installPushHandler`, `installNotificationClickHandler`, `installSkipWaitingListener`, `installPrecache` (app-shell offline), `installRuntimeCache` (per-route caching, incl. `rangeRequests`), `createPartialResponse` (206 range slicing), `installBackgroundSync` (offline mutation queue) — the React-free `tempest-react-sdk/sw` subpath is ideal for bundling into your own `sw.ts`                                                                                                                                   |
-| `charts` _(subpath `tempest-react-sdk/charts`, opt. peer `recharts`)_                             | `AreaChart`, `BarChart`, `LineChart`, `PieChart`, `RadarChart`, `DEFAULT_CHART_COLORS` — themed recharts wrappers (recharts externalized; install it only if you use charts)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `audio`                                                                                           | `createAudioPlayer`, `playAudio`, `stopAudio`, `useAudio`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `offline` _(peer: `dexie`)_                                                                       | `createOfflineStore`, `createOfflineSync` (outbox + delta-pull + watermark engine), types: `OfflineStore`, `OfflineStoreConfig`, `ListOptions`, `OfflineSync`, `OfflineSyncConfig`, `OutboxEntry`, `PullPage`, `SyncRunSummary`, `SyncTrigger`, `WatermarkStore`                                                                                                                                                                                                                                                                                                                                                                                             |
-| `error-boundary`                                                                                  | `ErrorBoundary`, `useErrorHandler`, types: `ErrorBoundaryProps`, `ErrorBoundaryRenderProps`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `theme`                                                                                           | `ThemeProvider`, `useTheme`, `getInitialTheme`, `themeInitScript`, types: `ThemeMode`, `ResolvedTheme`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `i18n`                                                                                            | `createI18n`, `I18nProvider`, `useI18n`, `useTranslate`, types: `Catalog`, `Messages`, `I18n`, `InterpolationValues`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `logger`                                                                                          | `createLogger`, `consoleSink`, types: `Logger`, `LogEntry`, `LogLevel`, `LoggerSink`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `telemetry`                                                                                       | `TelemetryProvider`, `useTelemetry`, `consoleTelemetryAdapter`, `createSentryTelemetryAdapter`, `createPostHogTelemetryAdapter`, types: `TelemetryAdapter`, `TelemetryEvent`, `TelemetryUser`, `CreateSentryTelemetryAdapterOptions`, `SentryLike`, `CreatePostHogTelemetryAdapterOptions`, `PostHogLike`                                                                                                                                                                                                                                                                                                                                                    |
-| `feature-flags`                                                                                   | `FeatureFlagsProvider`, `useFeatureFlag`, `useFlagValue`, `createInMemoryFlags`, `createGrowthBookFeatureFlagsAdapter`, `createLaunchDarklyFeatureFlagsAdapter`, types: `FeatureFlagsAdapter`, `FlagValue`, `GrowthBookLike`, `LDClientLike`                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `share`                                                                                           | `share`, `isShareSupported`, `shareOrDownloadBlob` (Web Share file → download fallback), types: `SharePayload`, `ShareResult`, `ShareOrDownloadOptions`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `utils`                                                                                           | `cn`, format BR (`formatCurrency`, `formatDate`, `formatDateTime`, `formatPhone`, `formatCPF`, `formatPercent`), `storage`, strings (`slugify`, `truncate`, `capitalize`, `camelCase`, `kebabCase`, `pluralize`), numbers (`clamp`, `formatBytes`, `formatCompactNumber`), arrays (`groupBy`, `uniqueBy`, `chunk`, `range`), objects (`pick`, `omit`, `deepMerge`, `isEmpty`), guards (`isDefined`, `isString`, `isNumber`, `isPlainObject`, `assertNever`), functions (`debounce`, `throttle`, `once`, `memoizeOne`), promises (`sleep`, `withTimeout`), `randomId`, `relativeTime`, `writeXlsx` (generic single-sheet OOXML `.xlsx` writer → `Uint8Array`) |
-| generic components                                                                                | display (`CopyButton`, `RelativeTime`, `Money`, `TruncateText`, `VisuallyHidden`), headless (`Portal`, `ClickOutside`, `ConditionalWrapper`, `For`, `ErrorText`), media/content (`Image`, `DataList`, `DescriptionList`)                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| Module                                                                                            | Exports                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------                                                                         |
-| `components`                                                                                      | `Avatar`, `Badge`, `Breadcrumbs`, `Button`, `Card`, `Checkbox`, `ChipInput`, `ConfirmDialog`, `Container`, `DatePicker`, `Drawer`, `EmptyState`, `ErrorState`, `FileUpload`, `Form` (`FormSection`, `FormRow`, `FormActions`), `Grid`, `Input`, `InstallBanner`, `InstallButton`, `Modal`, `Pagination`, `Progress`, `Radio`, `RadioGroup`, `SearchBar`, `Select`, `Skeleton`, `Spinner`, `Stack`, `Stepper`, `Switch`, `Table`, `Tabs`, `Textarea`, `Toast` (`ToastProvider`, `useToast`), `Tooltip`, `VirtualList`                                                                                                                                         |
-| `hooks`                                                                                           | `useDebounce`, `usePagination`, `useClientFilter`, `useMediaQuery`, `useOnline`, `useDocumentVisibility`, `useIntersectionObserver`, `useResizeObserver`, `useClipboard`, `useKeyboardShortcut`, `useBeforeInstallPrompt`, `useIdle`, `useGeolocation`, `useScrollLock`, `useFocusTrap`, `useStableCallback`, `useDeepMemo`, `useObjectUrl`, `useLongPressHandlers` (spreadable long-press handlers + `wasLongPress()` guard), `useInstallPrompt` (install-method resolver with decline cooldown), PWA env helpers `isIOS`/`isAndroid`/`isAndroidWithoutPromptApi`/`isStandalone`/`buildOpenInChromeIntent`, type `BeforeInstallPromptEvent`                 |
-| `http`                                                                                            | `createApiClient`, `parseResponse`, `uploadWithProgress`, `retry`, `generateIdempotencyKey`, `usePoll`, types: `ApiClient`, `ApiClientConfig`, `ApiError`, `RequestOptions`, `RetryOptions`, `UploadProgressEvent`, `UploadWithProgressOptions`, `UsePollOptions`, `UsePollResult`                                                                                                                                                                                                                                                                                                                                                                           |
-| `auth` _(peer: `zustand`)_                                                                        | `createAuthStore`, `AuthGuard`, `decodeJWT`, `isJWTExpired`, `lazyWithRetry`, `createRefreshQueue`, types: `AuthState`, `CreateAuthStoreOptions`, `AuthGuardProps`, `DecodedJWT`, `LazyWithRetryOptions`                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `query` _(peer: `@tanstack/react-query`)_                                                         | `QueryProvider`, `createQueryKeys`, `STALE_TIME`, `CACHE_TIME`, `REFETCH_TIME`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `router` _(dep: `react-router-dom`)_                                                              | `defineRoutes`, `AppRouter`, `RouteGuard`, + re-exports (`Link`, `NavLink`, `Outlet`, `Navigate`, `useNavigate`, `useParams`, `useSearchParams`, `useLocation`, `useMatch`, `useRouteError`, `redirect`, `BrowserRouter`/`HashRouter`/`MemoryRouter`/`Routes`/`Route`), types: `TempestRouteObject`, `RouterKind`, `AppRouterProps`, `RouteGuardProps`                                                                                                                                                                                                                                                                                                       |
-| `store` _(dep: `zustand`)_                                                                        | `createStore`, `createSelectors`, types: `CreateStoreOptions`, `CreateStorePersistOptions`, `WithSelectors`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `app`                                                                                             | `AppProviders` (composes `ErrorBoundary` → `QueryProvider` → `ThemeProvider` → `I18nProvider`), type: `AppProvidersProps`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `vite` _(subpath `tempest-react-sdk/vite`)_                                                       | `createViteConfig`, `tempestPwaManifest` (emits `precache-manifest.json` for offline precache), `tempestPwaIcons` (generates the PNG icon set from one SVG via `sharp`), `tempestPwaDevSw` (serves the SW under `npm run dev`), `tempestPwaIcons({ appleSplash })` (Apple splash screens), types: `CreateViteConfigOptions`, `ProxyEntry`, `TempestViteConfig`, `TempestPwaManifestOptions`, `TempestPwaIconsOptions`, `TempestPwaDevSwOptions`, `AppleSplashSpec`, `TempestVitePlugin`                                                                                                                                                                      |
-| `forms` _(peer: `zod`, `react-hook-form`)_                                                        | `validateForm`, `zodResolver`, `useZodForm`, `validateCPF`, `validateCNPJ`, `formatCEP`, `formatCNPJ`, `unmask`, `CPFInput`, `CNPJInput`, `PhoneInput`, `CEPInput`, `MoneyInput`, `useViaCEP`                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `sse`                                                                                             | `createEventStream`, `useEventStream`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `ws`                                                                                              | `createWebSocket`, `useWebSocket`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `geo` _(opt. peer `leaflet`)_                                                                     | `haversineKm`, `pathLengthKm`, `bearingDeg`, `estimateTravel`, `createOSRMBackend`, `boundingBox`, `projectMercator`, `fitProjection`, `createPositionTracker`, `usePositionTracker`, `TrajectoryMap` — tile-free SVG map + trajectory tracking (no external/paid API; Leaflet is an opt-in, lazy-loaded tile layer for self-hosted tiles), types: `Coordinate`, `TrackPoint`, `TravelEstimate`, `TravelMode`, `GeoBounds`, `RoutingBackend`                                                                                                                                                                                                                 |
-| `br` _(subpath `tempest-react-sdk/br`)_                                                           | `BrazilMap`, `BrazilStateMap`, `BrazilStateCitySelect`, `listStates`, `getState`, `citiesByUf`, `statesByRegion`, `ufChoices`, `cityChoices`, `isValidUf`, `normalizeUf`, `isValidCity`, `loadBrUfGeoJson`, `loadStateMunicipalities`, types `UF`, `BrRegion`, `BrazilState` — clickable 27-UF SVG map + per-state municipality submaps (bundled simplified IBGE GeoJSON, lazy per UF) + states/cities dataset, no external API; mirrors the FastAPI SDK `utils/locations`                                                                                                                                                                                   |
-| `push`                                                                                            | `WebPushClient`, `WebPushUnsupportedError`, `WebPushPermissionDeniedError`, `usePushSubscription`, `urlBase64ToUint8Array`, `isPushSupported`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `sw` _(also subpath `tempest-react-sdk/sw`)_                                                      | `registerServiceWorker` (opt-in `autoUpdate` poll + reload, no `vite-plugin-pwa`), `skipWaiting`, `unregisterAllServiceWorkers`, `installPushHandler`, `installNotificationClickHandler`, `installSkipWaitingListener`, `installPrecache` (app-shell offline), `installRuntimeCache` (per-route caching, incl. `rangeRequests`), `createPartialResponse` (206 range slicing), `installBackgroundSync` (offline mutation queue) — the React-free `tempest-react-sdk/sw` subpath is ideal for bundling into your own `sw.ts`                                                                                                                                   |
-| `editor` _(subpath `tempest-react-sdk/editor`, opt. peers `@tiptap/react`+`@tiptap/starter-kit`)_ | `RichTextEditor` — themed tiptap v3 rich-text editor with toolbar (tiptap externalized; install it only if you use the editor)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `vision` _(subpath `tempest-react-sdk/vision`, opt. peer `onnxruntime-web`)_                      | `Classifier`, `Detector`, `Segmenter` + results/labels/preprocess — on-device ONNX vision inference, vendored from `@mauriciobenjamin700/ort-vision-sdk-web` (onnxruntime-web externalized; install it only if you use vision). Plus browser capture primitives: `useCameraStream` (rear-camera `getUserMedia` + classified errors + `retry()`), `computeImageLuminance`/`isLuminanceAcceptable`/`LowLuminanceError`/`LUMINANCE_SAMPLE_MAX_EDGE` (BT.709 brightness), `useLiveLuminance` (live rAF sampling)                                                                                                                                                 |
-| `audio`                                                                                           | `createAudioPlayer`, `playAudio`, `stopAudio`, `useAudio`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `offline` _(peer: `dexie`)_                                                                       | `createOfflineStore`, `createOfflineSync` (outbox + delta-pull + watermark engine), types: `OfflineStore`, `OfflineStoreConfig`, `ListOptions`, `OfflineSync`, `OfflineSyncConfig`, `OutboxEntry`, `PullPage`, `SyncRunSummary`, `SyncTrigger`, `WatermarkStore`                                                                                                                                                                                                                                                                                                                                                                                             |
-| `error-boundary`                                                                                  | `ErrorBoundary`, `useErrorHandler`, types: `ErrorBoundaryProps`, `ErrorBoundaryRenderProps`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `theme`                                                                                           | `ThemeProvider`, `useTheme`, `getInitialTheme`, `themeInitScript`, types: `ThemeMode`, `ResolvedTheme`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `i18n`                                                                                            | `createI18n`, `I18nProvider`, `useI18n`, `useTranslate`, types: `Catalog`, `Messages`, `I18n`, `InterpolationValues`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `logger`                                                                                          | `createLogger`, `consoleSink`, types: `Logger`, `LogEntry`, `LogLevel`, `LoggerSink`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `telemetry`                                                                                       | `TelemetryProvider`, `useTelemetry`, `consoleTelemetryAdapter`, `createSentryTelemetryAdapter`, `createPostHogTelemetryAdapter`, types: `TelemetryAdapter`, `TelemetryEvent`, `TelemetryUser`, `CreateSentryTelemetryAdapterOptions`, `SentryLike`, `CreatePostHogTelemetryAdapterOptions`, `PostHogLike`                                                                                                                                                                                                                                                                                                                                                    |
-| `feature-flags`                                                                                   | `FeatureFlagsProvider`, `useFeatureFlag`, `useFlagValue`, `createInMemoryFlags`, `createGrowthBookFeatureFlagsAdapter`, `createLaunchDarklyFeatureFlagsAdapter`, types: `FeatureFlagsAdapter`, `FlagValue`, `GrowthBookLike`, `LDClientLike`                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `share`                                                                                           | `share`, `isShareSupported`, `shareOrDownloadBlob` (Web Share file → download fallback), types: `SharePayload`, `ShareResult`, `ShareOrDownloadOptions`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `utils`                                                                                           | `cn`, format BR (`formatCurrency`, `formatDate`, `formatDateTime`, `formatPhone`, `formatCPF`, `formatPercent`), `storage`, strings (`slugify`, `truncate`, `capitalize`, `camelCase`, `kebabCase`, `pluralize`), numbers (`clamp`, `formatBytes`, `formatCompactNumber`), arrays (`groupBy`, `uniqueBy`, `chunk`, `range`), objects (`pick`, `omit`, `deepMerge`, `isEmpty`), guards (`isDefined`, `isString`, `isNumber`, `isPlainObject`, `assertNever`), functions (`debounce`, `throttle`, `once`, `memoizeOne`), promises (`sleep`, `withTimeout`), `randomId`, `relativeTime`, `writeXlsx` (generic single-sheet OOXML `.xlsx` writer → `Uint8Array`) |
-| generic components                                                                                | display (`CopyButton`, `RelativeTime`, `Money`, `TruncateText`, `VisuallyHidden`), headless (`Portal`, `ClickOutside`, `ConditionalWrapper`, `For`, `ErrorText`), media/content (`Image`, `DataList`, `DescriptionList`)                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Module                                                                                            | Exports                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `components`                                                                                      | `Avatar`, `Badge`, `Breadcrumbs`, `Button`, `Card`, `Checkbox`, `ChipInput`, `ConfirmDialog`, `Container`, `DatePicker`, `Drawer`, `EmptyState`, `ErrorState`, `FileUpload`, `Form` (`FormSection`, `FormRow`, `FormActions`), `Grid`, `Input`, `InstallBanner`, `InstallButton`, `Modal`, `Pagination`, `Progress`, `Radio`, `RadioGroup`, `SearchBar`, `Select`, `Skeleton`, `Spinner`, `Stack`, `Stepper`, `Switch`, `Table`, `Tabs`, `Textarea`, `Toast` (`ToastProvider`, `useToast`), `Tooltip`, `VirtualList`                                                                                                                                                                                                                                                                                         |
+| `hooks`                                                                                           | `useDebounce`, `usePagination`, `useClientFilter`, `useMediaQuery`, `useOnline`, `useDocumentVisibility`, `useIntersectionObserver`, `useResizeObserver`, `useClipboard`, `useKeyboardShortcut`, `useBeforeInstallPrompt`, `useIdle`, `useGeolocation`, `useScrollLock`, `useFocusTrap`, `useStableCallback`, `useDeepMemo`, `useObjectUrl`, `useLongPressHandlers` (spreadable long-press handlers + `wasLongPress()` guard), `useInstallPrompt` (install-method resolver with decline cooldown), `useServiceWorkerUpdate` (consent-based SW update flow), `useStorageEstimate` + `estimateStorage`/`requestPersistentStorage` (Storage API quota & persistence), PWA env helpers `isIOS`/`isAndroid`/`isAndroidWithoutPromptApi`/`isStandalone`/`buildOpenInChromeIntent`, type `BeforeInstallPromptEvent` |
+| `http`                                                                                            | `createApiClient`, `parseResponse`, `uploadWithProgress`, `retry`, `generateIdempotencyKey`, `usePoll`, types: `ApiClient`, `ApiClientConfig`, `ApiError`, `RequestOptions`, `RetryOptions`, `UploadProgressEvent`, `UploadWithProgressOptions`, `UsePollOptions`, `UsePollResult`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `auth` _(peer: `zustand`)_                                                                        | `createAuthStore`, `AuthGuard`, `decodeJWT`, `isJWTExpired`, `lazyWithRetry`, `createRefreshQueue`, types: `AuthState`, `CreateAuthStoreOptions`, `AuthGuardProps`, `DecodedJWT`, `LazyWithRetryOptions`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `oauth` _(caller injects `@react-oauth/google`)_                                                  | `GoogleSignIn` (normalises Google's credential/error payload), `useOAuthCallback` (runs the callback exchange once, StrictMode-proof), types: `GoogleSignInProps`, `OAuthCredential`, `OAuthError`, `UseOAuthCallbackOptions`, `UseOAuthCallbackResult`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `query` _(peer: `@tanstack/react-query`)_                                                         | `QueryProvider`, `createQueryKeys`, `STALE_TIME`, `CACHE_TIME`, `REFETCH_TIME`, `usePaginatedQuery`, `useCursorQuery`, `useOfflineMutation` (optimistic offline mutation + cache rollback), `upsertById`/`removeById` (optimistic list-cache helpers), `persistQueryClientOffline` (IndexedDB cache persistence for offline reads)                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `router` _(dep: `react-router-dom`)_                                                              | `defineRoutes`, `AppRouter`, `RouteGuard`, + re-exports (`Link`, `NavLink`, `Outlet`, `Navigate`, `useNavigate`, `useParams`, `useSearchParams`, `useLocation`, `useMatch`, `useRouteError`, `redirect`, `BrowserRouter`/`HashRouter`/`MemoryRouter`/`Routes`/`Route`), types: `TempestRouteObject`, `RouterKind`, `AppRouterProps`, `RouteGuardProps`                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `store` _(dep: `zustand`)_                                                                        | `createStore`, `createSelectors`, types: `CreateStoreOptions`, `CreateStorePersistOptions`, `WithSelectors`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `app`                                                                                             | `AppProviders` (composes `ErrorBoundary` → `QueryProvider` → `ThemeProvider` → `I18nProvider`), type: `AppProvidersProps`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `vite` _(subpath `tempest-react-sdk/vite`)_                                                       | `createViteConfig`, `tempestPwaManifest` (emits `precache-manifest.json` for offline precache), `tempestPwaIcons` (generates the PNG icon set from one SVG via `sharp`), `tempestPwaDevSw` (serves the SW under `npm run dev`), `tempestPwaIcons({ appleSplash })` (Apple splash screens), types: `CreateViteConfigOptions`, `ProxyEntry`, `TempestViteConfig`, `TempestPwaManifestOptions`, `TempestPwaIconsOptions`, `TempestPwaDevSwOptions`, `AppleSplashSpec`, `TempestVitePlugin`                                                                                                                                                                                                                                                                                                                      |
+| `forms` _(peer: `zod`, `react-hook-form`)_                                                        | `validateForm`, `zodResolver`, `useZodForm`, `validateCPF`, `validateCNPJ`, `formatCEP`, `formatCNPJ`, `unmask`, `CPFInput`, `CNPJInput`, `PhoneInput`, `CEPInput`, `MoneyInput`, `useViaCEP`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `sse`                                                                                             | `createEventStream`, `useEventStream`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `ws`                                                                                              | `createWebSocket`, `useWebSocket`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `geo` _(opt. peer `leaflet`)_                                                                     | `haversineKm`, `pathLengthKm`, `bearingDeg`, `estimateTravel`, `createOSRMBackend`, `boundingBox`, `projectMercator`, `fitProjection`, `createPositionTracker`, `usePositionTracker`, `TrajectoryMap` — tile-free SVG map + trajectory tracking (no external/paid API; Leaflet is an opt-in, lazy-loaded tile layer for self-hosted tiles), types: `Coordinate`, `TrackPoint`, `TravelEstimate`, `TravelMode`, `GeoBounds`, `RoutingBackend`                                                                                                                                                                                                                                                                                                                                                                 |
+| `br` _(subpath `tempest-react-sdk/br`)_                                                           | `BrazilMap`, `BrazilStateMap`, `BrazilStateCitySelect`, `listStates`, `getState`, `citiesByUf`, `statesByRegion`, `ufChoices`, `cityChoices`, `isValidUf`, `normalizeUf`, `isValidCity`, `loadBrUfGeoJson`, `loadStateMunicipalities`, types `UF`, `BrRegion`, `BrazilState` — clickable 27-UF SVG map + per-state municipality submaps (bundled simplified IBGE GeoJSON, lazy per UF) + states/cities dataset, no external API; mirrors the FastAPI SDK `utils/locations`                                                                                                                                                                                                                                                                                                                                   |
+| `push`                                                                                            | `WebPushClient`, `WebPushUnsupportedError`, `WebPushPermissionDeniedError`, `usePushSubscription`, `urlBase64ToUint8Array`, `isPushSupported`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `sw` _(also subpath `tempest-react-sdk/sw`)_                                                      | `registerServiceWorker` (opt-in `autoUpdate` poll + reload, no `vite-plugin-pwa`), `skipWaiting`, `unregisterAllServiceWorkers`, `installPushHandler`, `installNotificationClickHandler`, `installSkipWaitingListener`, `installPrecache` (app-shell offline + Navigation Preload), `installRuntimeCache` (per-route caching, incl. `rangeRequests`), `createPartialResponse` (206 range slicing), `installBackgroundSync` (offline mutation queue + `periodicsync`), `registerPeriodicSync` (main-thread periodic sync), `inspectCaches`/`clearCaches` (cache observability) — the React-free `tempest-react-sdk/sw` subpath is ideal for bundling into your own `sw.ts`                                                                                                                                    |
+| `charts` _(subpath `tempest-react-sdk/charts`, opt. peer `recharts`)_                             | `AreaChart`, `BarChart`, `LineChart`, `PieChart`, `RadarChart`, `DEFAULT_CHART_COLORS` — themed recharts wrappers (recharts externalized; install it only if you use charts)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `audio`                                                                                           | `createAudioPlayer`, `playAudio`, `stopAudio`, `useAudio`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `offline` _(peer: `dexie`)_                                                                       | `createOfflineStore`, `createOfflineSync` (outbox + delta-pull + watermark engine, now with `subscribe`/`getState`/`dispose` + cross-tab `crossTab`), `useOfflineSync`/`useSyncStatus` (reactive hooks), `lastWriteWins`/`higherVersionWins` (conflict resolvers), types: `OfflineStore`, `OfflineStoreConfig`, `ListOptions`, `OfflineSync`, `OfflineSyncConfig`, `OutboxEntry`, `PullPage`, `SyncPhase`, `SyncState`, `SyncRunSummary`, `SyncTrigger`, `SyncStatus`, `SyncTone`, `WatermarkStore`                                                                                                                                                                                                                                                                                                          |
+| `error-boundary`                                                                                  | `ErrorBoundary`, `useErrorHandler`, types: `ErrorBoundaryProps`, `ErrorBoundaryRenderProps`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `theme`                                                                                           | `ThemeProvider`, `useTheme`, `getInitialTheme`, `themeInitScript`, types: `ThemeMode`, `ResolvedTheme`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `i18n`                                                                                            | `createI18n`, `I18nProvider`, `useI18n`, `useTranslate`, types: `Catalog`, `Messages`, `I18n`, `InterpolationValues`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `logger`                                                                                          | `createLogger`, `consoleSink`, types: `Logger`, `LogEntry`, `LogLevel`, `LoggerSink`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `telemetry`                                                                                       | `TelemetryProvider`, `useTelemetry`, `consoleTelemetryAdapter`, `createSentryTelemetryAdapter`, `createPostHogTelemetryAdapter`, types: `TelemetryAdapter`, `TelemetryEvent`, `TelemetryUser`, `CreateSentryTelemetryAdapterOptions`, `SentryLike`, `CreatePostHogTelemetryAdapterOptions`, `PostHogLike`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `feature-flags`                                                                                   | `FeatureFlagsProvider`, `useFeatureFlag`, `useFlagValue`, `createInMemoryFlags`, `createGrowthBookFeatureFlagsAdapter`, `createLaunchDarklyFeatureFlagsAdapter`, types: `FeatureFlagsAdapter`, `FlagValue`, `GrowthBookLike`, `LDClientLike`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `share`                                                                                           | `share`, `isShareSupported`, `shareOrDownloadBlob` (Web Share file → download fallback), types: `SharePayload`, `ShareResult`, `ShareOrDownloadOptions`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `utils`                                                                                           | `cn`, format BR (`formatCurrency`, `formatDate`, `formatDateTime`, `formatPhone`, `formatCPF`, `formatPercent`), `storage`, strings (`slugify`, `truncate`, `capitalize`, `camelCase`, `kebabCase`, `pluralize`), numbers (`clamp`, `formatBytes`, `formatCompactNumber`), arrays (`groupBy`, `uniqueBy`, `chunk`, `range`), objects (`pick`, `omit`, `deepMerge`, `isEmpty`), guards (`isDefined`, `isString`, `isNumber`, `isPlainObject`, `assertNever`), functions (`debounce`, `throttle`, `once`, `memoizeOne`), promises (`sleep`, `withTimeout`), `randomId`, `relativeTime`, `writeXlsx` (generic single-sheet OOXML `.xlsx` writer → `Uint8Array`)                                                                                                                                                 |
+| generic components                                                                                | display (`CopyButton`, `RelativeTime`, `Money`, `TruncateText`, `VisuallyHidden`), headless (`Portal`, `ClickOutside`, `ConditionalWrapper`, `For`, `ErrorText`), media/content (`Image`, `DataList`, `DescriptionList`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Module                                                                                            | Exports                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------                                                                                                                                                                                                                         |
+| `components`                                                                                      | `Avatar`, `Badge`, `Breadcrumbs`, `Button`, `Card`, `Checkbox`, `ChipInput`, `ConfirmDialog`, `Container`, `DatePicker`, `Drawer`, `EmptyState`, `ErrorState`, `FileUpload`, `Form` (`FormSection`, `FormRow`, `FormActions`), `Grid`, `Input`, `InstallBanner`, `InstallButton`, `Modal`, `Pagination`, `Progress`, `Radio`, `RadioGroup`, `SearchBar`, `Select`, `Skeleton`, `Spinner`, `Stack`, `Stepper`, `Switch`, `Table`, `Tabs`, `Textarea`, `Toast` (`ToastProvider`, `useToast`), `Tooltip`, `VirtualList`                                                                                                                                                                                                                                                                                         |
+| `hooks`                                                                                           | `useDebounce`, `usePagination`, `useClientFilter`, `useMediaQuery`, `useOnline`, `useDocumentVisibility`, `useIntersectionObserver`, `useResizeObserver`, `useClipboard`, `useKeyboardShortcut`, `useBeforeInstallPrompt`, `useIdle`, `useGeolocation`, `useScrollLock`, `useFocusTrap`, `useStableCallback`, `useDeepMemo`, `useObjectUrl`, `useLongPressHandlers` (spreadable long-press handlers + `wasLongPress()` guard), `useInstallPrompt` (install-method resolver with decline cooldown), `useServiceWorkerUpdate` (consent-based SW update flow), `useStorageEstimate` + `estimateStorage`/`requestPersistentStorage` (Storage API quota & persistence), PWA env helpers `isIOS`/`isAndroid`/`isAndroidWithoutPromptApi`/`isStandalone`/`buildOpenInChromeIntent`, type `BeforeInstallPromptEvent` |
+| `http`                                                                                            | `createApiClient`, `parseResponse`, `uploadWithProgress`, `retry`, `generateIdempotencyKey`, `usePoll`, types: `ApiClient`, `ApiClientConfig`, `ApiError`, `RequestOptions`, `RetryOptions`, `UploadProgressEvent`, `UploadWithProgressOptions`, `UsePollOptions`, `UsePollResult`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `auth` _(peer: `zustand`)_                                                                        | `createAuthStore`, `AuthGuard`, `decodeJWT`, `isJWTExpired`, `lazyWithRetry`, `createRefreshQueue`, types: `AuthState`, `CreateAuthStoreOptions`, `AuthGuardProps`, `DecodedJWT`, `LazyWithRetryOptions`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `oauth` _(caller injects `@react-oauth/google`)_                                                  | `GoogleSignIn` (normalises Google's credential/error payload), `useOAuthCallback` (runs the callback exchange once, StrictMode-proof), types: `GoogleSignInProps`, `OAuthCredential`, `OAuthError`, `UseOAuthCallbackOptions`, `UseOAuthCallbackResult`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `query` _(peer: `@tanstack/react-query`)_                                                         | `QueryProvider`, `createQueryKeys`, `STALE_TIME`, `CACHE_TIME`, `REFETCH_TIME`, `usePaginatedQuery`, `useCursorQuery`, `useOfflineMutation` (optimistic offline mutation + cache rollback), `upsertById`/`removeById` (optimistic list-cache helpers), `persistQueryClientOffline` (IndexedDB cache persistence for offline reads)                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `router` _(dep: `react-router-dom`)_                                                              | `defineRoutes`, `AppRouter`, `RouteGuard`, + re-exports (`Link`, `NavLink`, `Outlet`, `Navigate`, `useNavigate`, `useParams`, `useSearchParams`, `useLocation`, `useMatch`, `useRouteError`, `redirect`, `BrowserRouter`/`HashRouter`/`MemoryRouter`/`Routes`/`Route`), types: `TempestRouteObject`, `RouterKind`, `AppRouterProps`, `RouteGuardProps`                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `store` _(dep: `zustand`)_                                                                        | `createStore`, `createSelectors`, types: `CreateStoreOptions`, `CreateStorePersistOptions`, `WithSelectors`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `app`                                                                                             | `AppProviders` (composes `ErrorBoundary` → `QueryProvider` → `ThemeProvider` → `I18nProvider`), type: `AppProvidersProps`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `vite` _(subpath `tempest-react-sdk/vite`)_                                                       | `createViteConfig`, `tempestPwaManifest` (emits `precache-manifest.json` for offline precache), `tempestPwaIcons` (generates the PNG icon set from one SVG via `sharp`), `tempestPwaDevSw` (serves the SW under `npm run dev`), `tempestPwaIcons({ appleSplash })` (Apple splash screens), types: `CreateViteConfigOptions`, `ProxyEntry`, `TempestViteConfig`, `TempestPwaManifestOptions`, `TempestPwaIconsOptions`, `TempestPwaDevSwOptions`, `AppleSplashSpec`, `TempestVitePlugin`                                                                                                                                                                                                                                                                                                                      |
+| `forms` _(peer: `zod`, `react-hook-form`)_                                                        | `validateForm`, `zodResolver`, `useZodForm`, `validateCPF`, `validateCNPJ`, `formatCEP`, `formatCNPJ`, `unmask`, `CPFInput`, `CNPJInput`, `PhoneInput`, `CEPInput`, `MoneyInput`, `useViaCEP`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `sse`                                                                                             | `createEventStream`, `useEventStream`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `ws`                                                                                              | `createWebSocket`, `useWebSocket`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `geo` _(opt. peer `leaflet`)_                                                                     | `haversineKm`, `pathLengthKm`, `bearingDeg`, `estimateTravel`, `createOSRMBackend`, `boundingBox`, `projectMercator`, `fitProjection`, `createPositionTracker`, `usePositionTracker`, `TrajectoryMap` — tile-free SVG map + trajectory tracking (no external/paid API; Leaflet is an opt-in, lazy-loaded tile layer for self-hosted tiles), types: `Coordinate`, `TrackPoint`, `TravelEstimate`, `TravelMode`, `GeoBounds`, `RoutingBackend`                                                                                                                                                                                                                                                                                                                                                                 |
+| `br` _(subpath `tempest-react-sdk/br`)_                                                           | `BrazilMap`, `BrazilStateMap`, `BrazilStateCitySelect`, `listStates`, `getState`, `citiesByUf`, `statesByRegion`, `ufChoices`, `cityChoices`, `isValidUf`, `normalizeUf`, `isValidCity`, `loadBrUfGeoJson`, `loadStateMunicipalities`, types `UF`, `BrRegion`, `BrazilState` — clickable 27-UF SVG map + per-state municipality submaps (bundled simplified IBGE GeoJSON, lazy per UF) + states/cities dataset, no external API; mirrors the FastAPI SDK `utils/locations`                                                                                                                                                                                                                                                                                                                                   |
+| `push`                                                                                            | `WebPushClient`, `WebPushUnsupportedError`, `WebPushPermissionDeniedError`, `usePushSubscription`, `urlBase64ToUint8Array`, `isPushSupported`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `sw` _(also subpath `tempest-react-sdk/sw`)_                                                      | `registerServiceWorker` (opt-in `autoUpdate` poll + reload, no `vite-plugin-pwa`), `skipWaiting`, `unregisterAllServiceWorkers`, `installPushHandler`, `installNotificationClickHandler`, `installSkipWaitingListener`, `installPrecache` (app-shell offline + Navigation Preload), `installRuntimeCache` (per-route caching, incl. `rangeRequests`), `createPartialResponse` (206 range slicing), `installBackgroundSync` (offline mutation queue + `periodicsync`), `registerPeriodicSync` (main-thread periodic sync), `inspectCaches`/`clearCaches` (cache observability) — the React-free `tempest-react-sdk/sw` subpath is ideal for bundling into your own `sw.ts`                                                                                                                                    |
+| `editor` _(subpath `tempest-react-sdk/editor`, opt. peers `@tiptap/react`+`@tiptap/starter-kit`)_ | `RichTextEditor` — themed tiptap v3 rich-text editor with toolbar (tiptap externalized; install it only if you use the editor)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `vision` _(subpath `tempest-react-sdk/vision`, opt. peer `onnxruntime-web`)_                      | `Classifier`, `Detector`, `Segmenter` + results/labels/preprocess — on-device ONNX vision inference, vendored from `@mauriciobenjamin700/ort-vision-sdk-web` (onnxruntime-web externalized; install it only if you use vision). Plus browser capture primitives: `useCameraStream` (rear-camera `getUserMedia` + classified errors + `retry()`), `computeImageLuminance`/`isLuminanceAcceptable`/`LowLuminanceError`/`LUMINANCE_SAMPLE_MAX_EDGE` (BT.709 brightness), `useLiveLuminance` (live rAF sampling)                                                                                                                                                                                                                                                                                                 |
+| `audio`                                                                                           | `createAudioPlayer`, `playAudio`, `stopAudio`, `useAudio`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `offline` _(peer: `dexie`)_                                                                       | `createOfflineStore`, `createOfflineSync` (outbox + delta-pull + watermark engine, now with `subscribe`/`getState`/`dispose` + cross-tab `crossTab`), `useOfflineSync`/`useSyncStatus` (reactive hooks), `lastWriteWins`/`higherVersionWins` (conflict resolvers), types: `OfflineStore`, `OfflineStoreConfig`, `ListOptions`, `OfflineSync`, `OfflineSyncConfig`, `OutboxEntry`, `PullPage`, `SyncPhase`, `SyncState`, `SyncRunSummary`, `SyncTrigger`, `SyncStatus`, `SyncTone`, `WatermarkStore`                                                                                                                                                                                                                                                                                                          |
+| `error-boundary`                                                                                  | `ErrorBoundary`, `useErrorHandler`, types: `ErrorBoundaryProps`, `ErrorBoundaryRenderProps`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `theme`                                                                                           | `ThemeProvider`, `useTheme`, `getInitialTheme`, `themeInitScript`, types: `ThemeMode`, `ResolvedTheme`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `i18n`                                                                                            | `createI18n`, `I18nProvider`, `useI18n`, `useTranslate`, types: `Catalog`, `Messages`, `I18n`, `InterpolationValues`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `logger`                                                                                          | `createLogger`, `consoleSink`, types: `Logger`, `LogEntry`, `LogLevel`, `LoggerSink`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `telemetry`                                                                                       | `TelemetryProvider`, `useTelemetry`, `consoleTelemetryAdapter`, `createSentryTelemetryAdapter`, `createPostHogTelemetryAdapter`, types: `TelemetryAdapter`, `TelemetryEvent`, `TelemetryUser`, `CreateSentryTelemetryAdapterOptions`, `SentryLike`, `CreatePostHogTelemetryAdapterOptions`, `PostHogLike`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `feature-flags`                                                                                   | `FeatureFlagsProvider`, `useFeatureFlag`, `useFlagValue`, `createInMemoryFlags`, `createGrowthBookFeatureFlagsAdapter`, `createLaunchDarklyFeatureFlagsAdapter`, types: `FeatureFlagsAdapter`, `FlagValue`, `GrowthBookLike`, `LDClientLike`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `share`                                                                                           | `share`, `isShareSupported`, `shareOrDownloadBlob` (Web Share file → download fallback), types: `SharePayload`, `ShareResult`, `ShareOrDownloadOptions`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `utils`                                                                                           | `cn`, format BR (`formatCurrency`, `formatDate`, `formatDateTime`, `formatPhone`, `formatCPF`, `formatPercent`), `storage`, strings (`slugify`, `truncate`, `capitalize`, `camelCase`, `kebabCase`, `pluralize`), numbers (`clamp`, `formatBytes`, `formatCompactNumber`), arrays (`groupBy`, `uniqueBy`, `chunk`, `range`), objects (`pick`, `omit`, `deepMerge`, `isEmpty`), guards (`isDefined`, `isString`, `isNumber`, `isPlainObject`, `assertNever`), functions (`debounce`, `throttle`, `once`, `memoizeOne`), promises (`sleep`, `withTimeout`), `randomId`, `relativeTime`, `writeXlsx` (generic single-sheet OOXML `.xlsx` writer → `Uint8Array`)                                                                                                                                                 |
+| generic components                                                                                | display (`CopyButton`, `RelativeTime`, `Money`, `TruncateText`, `VisuallyHidden`), headless (`Portal`, `ClickOutside`, `ConditionalWrapper`, `For`, `ErrorText`), media/content (`Image`, `DataList`, `DescriptionList`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 
 Full per-module docs are published as a bilingual MkDocs site on GitHub Pages — **[Português (BR)](https://mauriciobenjamin700.github.io/tempest-react-sdk/)** / **[English (US)](https://mauriciobenjamin700.github.io/tempest-react-sdk/en/)** (one page per module + draw.io diagrams in [`docs/diagrams/`](./docs/diagrams)). The source markdown lives in [`docs/`](./docs) (PT-BR base files + `.en.md` translations).
 
@@ -1779,8 +1781,9 @@ npm run clean          # rm -rf dist coverage
 
 Snapshot of current health:
 
-- 444 tests / 164 files. 95% line / 96% function coverage.
-- ESM 98 KB → 28 KB gzip. CJS 71 KB → 24 KB gzip. CSS 32 KB → 6 KB gzip.
+- 1490 tests / 358 files.
+- What your app actually pays (brotli, tree-shaken slices measured by `npm run size`): `cn` alone 118 B · one `Button` 820 B · a typical app shell (5 components + router + providers + HTTP + auth + a hook) 6.83 KB · offline/PWA surface 4.45 KB · `styles.css` 20.6 KB.
+- Full-barrel ceiling — nobody imports this, it is the no-tree-shaking worst case: 64.5 KB ESM / 79.9 KB CJS.
 - Husky pre-commit runs `lint-staged` (eslint --fix + prettier --write) on staged files.
 
 The demo gallery lives in `examples/gallery` and consumes the local SDK via `file:../..`:

package/dist/access/Can.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("react/jsx-runtime"),l=require("./use-can.cjs");function a({action:r,resource:t,params:u,children:i,fallback:n}){const{allowed:s,isLoading:o}=l.useCan({action:r,resource:t,params:u});return o?e.jsx(e.Fragment,{children:n??null}):e.jsx(e.Fragment,{children:s?i:n??null})}exports.Can=a;
+//# sourceMappingURL=Can.cjs.map

package/dist/access/Can.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Can.cjs","sources":["../../src/access/Can.tsx"],"sourcesContent":["import type { ReactNode } from \"react\";\nimport { useCan } from \"./use-can\";\nimport type { CanParams } from \"./types\";\n\nexport interface CanProps extends CanParams {\n    /** Rendered when the action is allowed. */\n    children: ReactNode;\n    /** Rendered when the action is denied. Defaults to nothing. */\n    fallback?: ReactNode;\n}\n\n/**\n * Conditionally render based on an access check. Renders `children` when the\n * action is allowed, otherwise `fallback` (or nothing). While an async check is\n * pending, nothing is rendered.\n *\n * @example\n * ```tsx\n * <Can action=\"create\" resource=\"posts\" fallback={<p>No access</p>}>\n *   <NewPostButton />\n * </Can>\n * ```\n */\nexport function Can({ action, resource, params, children, fallback }: CanProps) {\n    const { allowed, isLoading } = useCan({ action, resource, params });\n    if (isLoading) return <>{fallback ?? null}</>;\n    return <>{allowed ? children : (fallback ?? null)}</>;\n}\n"],"names":["Can","action","resource","params","children","fallback","allowed","isLoading","useCan","jsx","Fragment"],"mappings":"gJAuBO,SAASA,EAAI,CAAE,OAAAC,EAAQ,SAAAC,EAAU,OAAAC,EAAQ,SAAAC,EAAU,SAAAC,GAAsB,CAC5E,KAAM,CAAE,QAAAC,EAAS,UAAAC,GAAcC,EAAAA,OAAO,CAAE,OAAAP,EAAQ,SAAAC,EAAU,OAAAC,EAAQ,EAClE,OAAII,EAAkBE,MAAAC,EAAAA,SAAA,CAAG,SAAAL,GAAY,KAAK,EACnCI,EAAAA,IAAAC,EAAAA,SAAA,CAAG,SAAAJ,EAAUF,EAAYC,GAAY,KAAM,CACtD"}

package/dist/access/Can.js

@@ -0,0 +1,10 @@
+import { jsx as r, Fragment as o } from "react/jsx-runtime";
+import { useCan as d } from "./use-can.js";
+function c({ action: e, resource: i, params: t, children: l, fallback: n }) {
+  const { allowed: u, isLoading: m } = d({ action: e, resource: i, params: t });
+  return m ? /* @__PURE__ */ r(o, { children: n ?? null }) : /* @__PURE__ */ r(o, { children: u ? l : n ?? null });
+}
+export {
+  c as Can
+};
+//# sourceMappingURL=Can.js.map

package/dist/access/Can.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Can.js","sources":["../../src/access/Can.tsx"],"sourcesContent":["import type { ReactNode } from \"react\";\nimport { useCan } from \"./use-can\";\nimport type { CanParams } from \"./types\";\n\nexport interface CanProps extends CanParams {\n    /** Rendered when the action is allowed. */\n    children: ReactNode;\n    /** Rendered when the action is denied. Defaults to nothing. */\n    fallback?: ReactNode;\n}\n\n/**\n * Conditionally render based on an access check. Renders `children` when the\n * action is allowed, otherwise `fallback` (or nothing). While an async check is\n * pending, nothing is rendered.\n *\n * @example\n * ```tsx\n * <Can action=\"create\" resource=\"posts\" fallback={<p>No access</p>}>\n *   <NewPostButton />\n * </Can>\n * ```\n */\nexport function Can({ action, resource, params, children, fallback }: CanProps) {\n    const { allowed, isLoading } = useCan({ action, resource, params });\n    if (isLoading) return <>{fallback ?? null}</>;\n    return <>{allowed ? children : (fallback ?? null)}</>;\n}\n"],"names":["Can","action","resource","params","children","fallback","allowed","isLoading","useCan","jsx","Fragment"],"mappings":";;AAuBO,SAASA,EAAI,EAAE,QAAAC,GAAQ,UAAAC,GAAU,QAAAC,GAAQ,UAAAC,GAAU,UAAAC,KAAsB;AAC5E,QAAM,EAAE,SAAAC,GAAS,WAAAC,MAAcC,EAAO,EAAE,QAAAP,GAAQ,UAAAC,GAAU,QAAAC,GAAQ;AAClE,SAAII,IAAkB,gBAAAE,EAAAC,GAAA,EAAG,UAAAL,KAAY,MAAK,IACnC,gBAAAI,EAAAC,GAAA,EAAG,UAAAJ,IAAUF,IAAYC,KAAY,MAAM;AACtD;"}

package/dist/access/access-control-context.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const n=require("react/jsx-runtime"),e=require("react"),t=e.createContext(null);function s({control:o,children:r}){return n.jsx(t.Provider,{value:o,children:r})}function c(){return e.useContext(t)}exports.AccessControlProvider=s;exports.useAccessControl=c;
+//# sourceMappingURL=access-control-context.cjs.map

package/dist/access/access-control-context.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-control-context.cjs","sources":["../../src/access/access-control-context.tsx"],"sourcesContent":["import { createContext, useContext } from \"react\";\nimport type { ReactNode } from \"react\";\nimport type { AccessControl } from \"./types\";\n\nconst AccessControlContext = createContext<AccessControl | null>(null);\n\nexport interface AccessControlProviderProps {\n    /** The access-control strategy made available to descendants. */\n    control: AccessControl;\n    children: ReactNode;\n}\n\n/**\n * Provide an {@link AccessControl} strategy to the React tree. Components such\n * as `<Can>` and the `useCan` hook read it from context.\n *\n * @example\n * ```tsx\n * <AccessControlProvider control={createRoleAccessControl({ role: \"admin\", roles: { admin: [\"*\"] } })}>\n *   <App />\n * </AccessControlProvider>\n * ```\n */\nexport function AccessControlProvider({ control, children }: AccessControlProviderProps) {\n    return (\n        <AccessControlContext.Provider value={control}>{children}</AccessControlContext.Provider>\n    );\n}\n\n/**\n * Read the current {@link AccessControl} from context.\n *\n * Returns `null` when no {@link AccessControlProvider} is present. Callers MUST\n * treat the absence of a provider as **\"allow all\"** — i.e. when this returns\n * `null`, access checks should default to permitted. This keeps the SDK\n * opt-in: dropping in a provider adds enforcement, removing it disables it.\n */\nexport function useAccessControl(): AccessControl | null {\n    return useContext(AccessControlContext);\n}\n"],"names":["AccessControlContext","createContext","AccessControlProvider","control","children","useAccessControl","useContext"],"mappings":"wIAIMA,EAAuBC,EAAAA,cAAoC,IAAI,EAmB9D,SAASC,EAAsB,CAAE,QAAAC,EAAS,SAAAC,GAAwC,CACrF,aACKJ,EAAqB,SAArB,CAA8B,MAAOG,EAAU,SAAAC,EAAS,CAEjE,CAUO,SAASC,GAAyC,CACrD,OAAOC,EAAAA,WAAWN,CAAoB,CAC1C"}

package/dist/access/access-control-context.js

@@ -0,0 +1,14 @@
+import { jsx as e } from "react/jsx-runtime";
+import { useContext as n, createContext as c } from "react";
+const o = c(null);
+function i({ control: t, children: r }) {
+  return /* @__PURE__ */ e(o.Provider, { value: t, children: r });
+}
+function l() {
+  return n(o);
+}
+export {
+  i as AccessControlProvider,
+  l as useAccessControl
+};
+//# sourceMappingURL=access-control-context.js.map

package/dist/access/access-control-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-control-context.js","sources":["../../src/access/access-control-context.tsx"],"sourcesContent":["import { createContext, useContext } from \"react\";\nimport type { ReactNode } from \"react\";\nimport type { AccessControl } from \"./types\";\n\nconst AccessControlContext = createContext<AccessControl | null>(null);\n\nexport interface AccessControlProviderProps {\n    /** The access-control strategy made available to descendants. */\n    control: AccessControl;\n    children: ReactNode;\n}\n\n/**\n * Provide an {@link AccessControl} strategy to the React tree. Components such\n * as `<Can>` and the `useCan` hook read it from context.\n *\n * @example\n * ```tsx\n * <AccessControlProvider control={createRoleAccessControl({ role: \"admin\", roles: { admin: [\"*\"] } })}>\n *   <App />\n * </AccessControlProvider>\n * ```\n */\nexport function AccessControlProvider({ control, children }: AccessControlProviderProps) {\n    return (\n        <AccessControlContext.Provider value={control}>{children}</AccessControlContext.Provider>\n    );\n}\n\n/**\n * Read the current {@link AccessControl} from context.\n *\n * Returns `null` when no {@link AccessControlProvider} is present. Callers MUST\n * treat the absence of a provider as **\"allow all\"** — i.e. when this returns\n * `null`, access checks should default to permitted. This keeps the SDK\n * opt-in: dropping in a provider adds enforcement, removing it disables it.\n */\nexport function useAccessControl(): AccessControl | null {\n    return useContext(AccessControlContext);\n}\n"],"names":["AccessControlContext","createContext","AccessControlProvider","control","children","useAccessControl","useContext"],"mappings":";;AAIA,MAAMA,IAAuBC,EAAoC,IAAI;AAmB9D,SAASC,EAAsB,EAAE,SAAAC,GAAS,UAAAC,KAAwC;AACrF,2BACKJ,EAAqB,UAArB,EAA8B,OAAOG,GAAU,UAAAC,GAAS;AAEjE;AAUO,SAASC,IAAyC;AACrD,SAAOC,EAAWN,CAAoB;AAC1C;"}

package/dist/access/create-role-access-control.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function n(e){const s=new Set(e.permissions??[]),r=e.role?Array.isArray(e.role)?e.role:[e.role]:[];for(const o of r)for(const t of e.roles?.[o]??[])s.add(t);return s}function l(e){const s=n(e);return{can({action:r,resource:o}){return s.has("*")||o!==void 0&&(s.has(`${o}:*`)||s.has(`${o}:${r}`))||o===void 0&&s.has(r)?{can:!0}:{can:!1,reason:"missing permission"}}}}exports.createRoleAccessControl=l;
+//# sourceMappingURL=create-role-access-control.cjs.map

package/dist/access/create-role-access-control.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-role-access-control.cjs","sources":["../../src/access/create-role-access-control.ts"],"sourcesContent":["import type { AccessControl, CanParams, CanResult } from \"./types\";\n\nexport interface RoleAccessControlConfig {\n    /** Permission strings granted directly, regardless of role. */\n    permissions?: string[];\n    /** Map of role name → permission strings granted by that role. */\n    roles?: Record<string, string[]>;\n    /** The active role(s). Their permissions (from `roles`) are merged in. */\n    role?: string | string[];\n}\n\nfunction resolvePermissions(config: RoleAccessControlConfig): Set<string> {\n    const set = new Set<string>(config.permissions ?? []);\n    const roles = config.role ? (Array.isArray(config.role) ? config.role : [config.role]) : [];\n    for (const role of roles) {\n        for (const perm of config.roles?.[role] ?? []) {\n            set.add(perm);\n        }\n    }\n    return set;\n}\n\n/**\n * Build a simple RBAC {@link AccessControl} from a static permission set.\n *\n * Permission strings are `\"<resource>:<action>\"` (e.g. `\"posts:create\"`) or a\n * bare `\"<action>\"`. Wildcards are supported: `\"*\"` grants everything and\n * `\"<resource>:*\"` grants every action on a resource.\n *\n * The effective set is `config.permissions` plus, for each active role in\n * `config.role`, the permissions listed in `config.roles[role]`.\n *\n * @param config - Permissions, role map, and active role(s).\n * @returns An access-control strategy backed by the resolved permission set.\n *\n * @example\n * ```ts\n * const ac = createRoleAccessControl({\n *   role: \"editor\",\n *   roles: { editor: [\"posts:*\", \"comments:read\"] },\n * });\n * ac.can({ action: \"create\", resource: \"posts\" }); // true\n * ```\n */\nexport function createRoleAccessControl(config: RoleAccessControlConfig): AccessControl {\n    const granted = resolvePermissions(config);\n\n    return {\n        can({ action, resource }: CanParams): CanResult {\n            const allowed =\n                granted.has(\"*\") ||\n                (resource !== undefined &&\n                    (granted.has(`${resource}:*`) || granted.has(`${resource}:${action}`))) ||\n                (resource === undefined && granted.has(action));\n\n            return allowed ? { can: true } : { can: false, reason: \"missing permission\" };\n        },\n    };\n}\n"],"names":["resolvePermissions","config","set","roles","role","perm","createRoleAccessControl","granted","action","resource"],"mappings":"gFAWA,SAASA,EAAmBC,EAA8C,CACtE,MAAMC,EAAM,IAAI,IAAYD,EAAO,aAAe,CAAA,CAAE,EAC9CE,EAAQF,EAAO,KAAQ,MAAM,QAAQA,EAAO,IAAI,EAAIA,EAAO,KAAO,CAACA,EAAO,IAAI,EAAK,CAAA,EACzF,UAAWG,KAAQD,EACf,UAAWE,KAAQJ,EAAO,QAAQG,CAAI,GAAK,CAAA,EACvCF,EAAI,IAAIG,CAAI,EAGpB,OAAOH,CACX,CAwBO,SAASI,EAAwBL,EAAgD,CACpF,MAAMM,EAAUP,EAAmBC,CAAM,EAEzC,MAAO,CACH,IAAI,CAAE,OAAAO,EAAQ,SAAAC,GAAkC,CAO5C,OALIF,EAAQ,IAAI,GAAG,GACdE,IAAa,SACTF,EAAQ,IAAI,GAAGE,CAAQ,IAAI,GAAKF,EAAQ,IAAI,GAAGE,CAAQ,IAAID,CAAM,EAAE,IACvEC,IAAa,QAAaF,EAAQ,IAAIC,CAAM,EAEhC,CAAE,IAAK,EAAA,EAAS,CAAE,IAAK,GAAO,OAAQ,oBAAA,CAC3D,CAAA,CAER"}

package/dist/access/create-role-access-control.js

@@ -0,0 +1,19 @@
+function t(s) {
+  const e = new Set(s.permissions ?? []), o = s.role ? Array.isArray(s.role) ? s.role : [s.role] : [];
+  for (const r of o)
+    for (const n of s.roles?.[r] ?? [])
+      e.add(n);
+  return e;
+}
+function a(s) {
+  const e = t(s);
+  return {
+    can({ action: o, resource: r }) {
+      return e.has("*") || r !== void 0 && (e.has(`${r}:*`) || e.has(`${r}:${o}`)) || r === void 0 && e.has(o) ? { can: !0 } : { can: !1, reason: "missing permission" };
+    }
+  };
+}
+export {
+  a as createRoleAccessControl
+};
+//# sourceMappingURL=create-role-access-control.js.map

package/dist/access/create-role-access-control.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-role-access-control.js","sources":["../../src/access/create-role-access-control.ts"],"sourcesContent":["import type { AccessControl, CanParams, CanResult } from \"./types\";\n\nexport interface RoleAccessControlConfig {\n    /** Permission strings granted directly, regardless of role. */\n    permissions?: string[];\n    /** Map of role name → permission strings granted by that role. */\n    roles?: Record<string, string[]>;\n    /** The active role(s). Their permissions (from `roles`) are merged in. */\n    role?: string | string[];\n}\n\nfunction resolvePermissions(config: RoleAccessControlConfig): Set<string> {\n    const set = new Set<string>(config.permissions ?? []);\n    const roles = config.role ? (Array.isArray(config.role) ? config.role : [config.role]) : [];\n    for (const role of roles) {\n        for (const perm of config.roles?.[role] ?? []) {\n            set.add(perm);\n        }\n    }\n    return set;\n}\n\n/**\n * Build a simple RBAC {@link AccessControl} from a static permission set.\n *\n * Permission strings are `\"<resource>:<action>\"` (e.g. `\"posts:create\"`) or a\n * bare `\"<action>\"`. Wildcards are supported: `\"*\"` grants everything and\n * `\"<resource>:*\"` grants every action on a resource.\n *\n * The effective set is `config.permissions` plus, for each active role in\n * `config.role`, the permissions listed in `config.roles[role]`.\n *\n * @param config - Permissions, role map, and active role(s).\n * @returns An access-control strategy backed by the resolved permission set.\n *\n * @example\n * ```ts\n * const ac = createRoleAccessControl({\n *   role: \"editor\",\n *   roles: { editor: [\"posts:*\", \"comments:read\"] },\n * });\n * ac.can({ action: \"create\", resource: \"posts\" }); // true\n * ```\n */\nexport function createRoleAccessControl(config: RoleAccessControlConfig): AccessControl {\n    const granted = resolvePermissions(config);\n\n    return {\n        can({ action, resource }: CanParams): CanResult {\n            const allowed =\n                granted.has(\"*\") ||\n                (resource !== undefined &&\n                    (granted.has(`${resource}:*`) || granted.has(`${resource}:${action}`))) ||\n                (resource === undefined && granted.has(action));\n\n            return allowed ? { can: true } : { can: false, reason: \"missing permission\" };\n        },\n    };\n}\n"],"names":["resolvePermissions","config","set","roles","role","perm","createRoleAccessControl","granted","action","resource"],"mappings":"AAWA,SAASA,EAAmBC,GAA8C;AACtE,QAAMC,IAAM,IAAI,IAAYD,EAAO,eAAe,CAAA,CAAE,GAC9CE,IAAQF,EAAO,OAAQ,MAAM,QAAQA,EAAO,IAAI,IAAIA,EAAO,OAAO,CAACA,EAAO,IAAI,IAAK,CAAA;AACzF,aAAWG,KAAQD;AACf,eAAWE,KAAQJ,EAAO,QAAQG,CAAI,KAAK,CAAA;AACvC,MAAAF,EAAI,IAAIG,CAAI;AAGpB,SAAOH;AACX;AAwBO,SAASI,EAAwBL,GAAgD;AACpF,QAAMM,IAAUP,EAAmBC,CAAM;AAEzC,SAAO;AAAA,IACH,IAAI,EAAE,QAAAO,GAAQ,UAAAC,KAAkC;AAO5C,aALIF,EAAQ,IAAI,GAAG,KACdE,MAAa,WACTF,EAAQ,IAAI,GAAGE,CAAQ,IAAI,KAAKF,EAAQ,IAAI,GAAGE,CAAQ,IAAID,CAAM,EAAE,MACvEC,MAAa,UAAaF,EAAQ,IAAIC,CAAM,IAEhC,EAAE,KAAK,GAAA,IAAS,EAAE,KAAK,IAAO,QAAQ,qBAAA;AAAA,IAC3D;AAAA,EAAA;AAER;"}

package/dist/access/permissions-from-token.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const c=require("../auth/jwt.cjs");function n(r){return Array.isArray(r)?r.filter(t=>typeof t=="string"):typeof r=="string"?r.split(/\s+/).filter(Boolean):[]}function f(r,t){try{const{payload:e}=c.decodeJWT(r),s=t?.claim??"permissions",i=n(e[s]);if(i.length>0)return i;if(t?.claim===void 0){const o=n(e.scopes);return o.length>0?o:n(e.scope)}return i}catch{return[]}}exports.permissionsFromToken=f;
+//# sourceMappingURL=permissions-from-token.cjs.map

package/dist/access/permissions-from-token.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions-from-token.cjs","sources":["../../src/access/permissions-from-token.ts"],"sourcesContent":["import { decodeJWT } from \"@/auth/jwt\";\n\nexport interface PermissionsFromTokenOptions {\n    /** JWT claim to read permissions from. Default: `\"permissions\"`. */\n    claim?: string;\n}\n\nfunction toPermissionList(value: unknown): string[] {\n    if (Array.isArray(value)) {\n        return value.filter((item): item is string => typeof item === \"string\");\n    }\n    if (typeof value === \"string\") {\n        // Space-delimited scope strings (OAuth convention).\n        return value.split(/\\s+/).filter(Boolean);\n    }\n    return [];\n}\n\n/**\n * Extract a permission list from a JWT.\n *\n * Reads the configured claim (default `\"permissions\"`); if absent, falls back to\n * the OAuth `\"scopes\"`/`\"scope\"` claims. Array claims are used as-is; string\n * claims are split on whitespace. Returns `[]` on any decode failure or when no\n * recognizable claim is present.\n *\n * @param token - The JWT to inspect (signature is **not** verified).\n * @param options - Optional claim override.\n * @returns The list of permission strings, or `[]` on failure.\n */\nexport function permissionsFromToken(\n    token: string,\n    options?: PermissionsFromTokenOptions,\n): string[] {\n    try {\n        const { payload } = decodeJWT(token);\n        const claim = options?.claim ?? \"permissions\";\n        const primary = toPermissionList(payload[claim]);\n        if (primary.length > 0) return primary;\n\n        if (options?.claim === undefined) {\n            const scopes = toPermissionList(payload[\"scopes\"]);\n            if (scopes.length > 0) return scopes;\n            return toPermissionList(payload[\"scope\"]);\n        }\n        return primary;\n    } catch {\n        return [];\n    }\n}\n"],"names":["toPermissionList","value","item","permissionsFromToken","token","options","payload","decodeJWT","claim","primary","scopes"],"mappings":"mHAOA,SAASA,EAAiBC,EAA0B,CAChD,OAAI,MAAM,QAAQA,CAAK,EACZA,EAAM,OAAQC,GAAyB,OAAOA,GAAS,QAAQ,EAEtE,OAAOD,GAAU,SAEVA,EAAM,MAAM,KAAK,EAAE,OAAO,OAAO,EAErC,CAAA,CACX,CAcO,SAASE,EACZC,EACAC,EACQ,CACR,GAAI,CACA,KAAM,CAAE,QAAAC,CAAA,EAAYC,EAAAA,UAAUH,CAAK,EAC7BI,EAAQH,GAAS,OAAS,cAC1BI,EAAUT,EAAiBM,EAAQE,CAAK,CAAC,EAC/C,GAAIC,EAAQ,OAAS,EAAG,OAAOA,EAE/B,GAAIJ,GAAS,QAAU,OAAW,CAC9B,MAAMK,EAASV,EAAiBM,EAAQ,MAAS,EACjD,OAAII,EAAO,OAAS,EAAUA,EACvBV,EAAiBM,EAAQ,KAAQ,CAC5C,CACA,OAAOG,CACX,MAAQ,CACJ,MAAO,CAAA,CACX,CACJ"}

package/dist/access/permissions-from-token.js

@@ -0,0 +1,21 @@
+import { decodeJWT as c } from "../auth/jwt.js";
+function o(r) {
+  return Array.isArray(r) ? r.filter((t) => typeof t == "string") : typeof r == "string" ? r.split(/\s+/).filter(Boolean) : [];
+}
+function p(r, t) {
+  try {
+    const { payload: i } = c(r), s = t?.claim ?? "permissions", n = o(i[s]);
+    if (n.length > 0) return n;
+    if (t?.claim === void 0) {
+      const e = o(i.scopes);
+      return e.length > 0 ? e : o(i.scope);
+    }
+    return n;
+  } catch {
+    return [];
+  }
+}
+export {
+  p as permissionsFromToken
+};
+//# sourceMappingURL=permissions-from-token.js.map

package/dist/access/permissions-from-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions-from-token.js","sources":["../../src/access/permissions-from-token.ts"],"sourcesContent":["import { decodeJWT } from \"@/auth/jwt\";\n\nexport interface PermissionsFromTokenOptions {\n    /** JWT claim to read permissions from. Default: `\"permissions\"`. */\n    claim?: string;\n}\n\nfunction toPermissionList(value: unknown): string[] {\n    if (Array.isArray(value)) {\n        return value.filter((item): item is string => typeof item === \"string\");\n    }\n    if (typeof value === \"string\") {\n        // Space-delimited scope strings (OAuth convention).\n        return value.split(/\\s+/).filter(Boolean);\n    }\n    return [];\n}\n\n/**\n * Extract a permission list from a JWT.\n *\n * Reads the configured claim (default `\"permissions\"`); if absent, falls back to\n * the OAuth `\"scopes\"`/`\"scope\"` claims. Array claims are used as-is; string\n * claims are split on whitespace. Returns `[]` on any decode failure or when no\n * recognizable claim is present.\n *\n * @param token - The JWT to inspect (signature is **not** verified).\n * @param options - Optional claim override.\n * @returns The list of permission strings, or `[]` on failure.\n */\nexport function permissionsFromToken(\n    token: string,\n    options?: PermissionsFromTokenOptions,\n): string[] {\n    try {\n        const { payload } = decodeJWT(token);\n        const claim = options?.claim ?? \"permissions\";\n        const primary = toPermissionList(payload[claim]);\n        if (primary.length > 0) return primary;\n\n        if (options?.claim === undefined) {\n            const scopes = toPermissionList(payload[\"scopes\"]);\n            if (scopes.length > 0) return scopes;\n            return toPermissionList(payload[\"scope\"]);\n        }\n        return primary;\n    } catch {\n        return [];\n    }\n}\n"],"names":["toPermissionList","value","item","permissionsFromToken","token","options","payload","decodeJWT","claim","primary","scopes"],"mappings":";AAOA,SAASA,EAAiBC,GAA0B;AAChD,SAAI,MAAM,QAAQA,CAAK,IACZA,EAAM,OAAO,CAACC,MAAyB,OAAOA,KAAS,QAAQ,IAEtE,OAAOD,KAAU,WAEVA,EAAM,MAAM,KAAK,EAAE,OAAO,OAAO,IAErC,CAAA;AACX;AAcO,SAASE,EACZC,GACAC,GACQ;AACR,MAAI;AACA,UAAM,EAAE,SAAAC,EAAA,IAAYC,EAAUH,CAAK,GAC7BI,IAAQH,GAAS,SAAS,eAC1BI,IAAUT,EAAiBM,EAAQE,CAAK,CAAC;AAC/C,QAAIC,EAAQ,SAAS,EAAG,QAAOA;AAE/B,QAAIJ,GAAS,UAAU,QAAW;AAC9B,YAAMK,IAASV,EAAiBM,EAAQ,MAAS;AACjD,aAAII,EAAO,SAAS,IAAUA,IACvBV,EAAiBM,EAAQ,KAAQ;AAAA,IAC5C;AACA,WAAOG;AAAA,EACX,QAAQ;AACJ,WAAO,CAAA;AAAA,EACX;AACJ;"}

package/dist/access/use-can.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("react"),i=require("./access-control-context.cjs");function u(e){return typeof e=="boolean"?{can:e}:e}function f(e){const n=i.useAccessControl(),c=JSON.stringify(e),[l,s]=r.useState(()=>n?{allowed:!1,isLoading:!0}:{allowed:!0,isLoading:!1});return r.useEffect(()=>{if(!n){s({allowed:!0,isLoading:!1});return}let a=!1;return s(t=>({...t,isLoading:!0})),Promise.resolve(n.can(e)).then(t=>{if(a)return;const o=u(t);s({allowed:o.can,isLoading:!1,reason:o.reason})}).catch(t=>{a||s({allowed:!1,isLoading:!1,reason:t instanceof Error?t.message:"access check failed"})}),()=>{a=!0}},[n,c]),l}exports.useCan=f;
+//# sourceMappingURL=use-can.cjs.map

package/dist/access/use-can.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-can.cjs","sources":["../../src/access/use-can.ts"],"sourcesContent":["import { useEffect, useState } from \"react\";\nimport { useAccessControl } from \"./access-control-context\";\nimport type { CanParams, CanResult } from \"./types\";\n\nexport interface UseCanResult {\n    /** Whether the action is permitted. Defaults to `true` while loading is not the concern of the caller. */\n    allowed: boolean;\n    /** `true` while an async `can` check is pending. */\n    isLoading: boolean;\n    /** Optional explanation, typically present when `allowed` is `false`. */\n    reason?: string;\n}\n\nfunction normalize(result: boolean | CanResult): CanResult {\n    return typeof result === \"boolean\" ? { can: result } : result;\n}\n\n/**\n * Resolve an access check against the {@link AccessControl} in context.\n *\n * Handles sync booleans, sync {@link CanResult}, and promises of either. When\n * no provider is present, access is allowed (see `useAccessControl`). The check\n * re-runs whenever the params change.\n *\n * @param params - The action/resource being checked.\n */\nexport function useCan(params: CanParams): UseCanResult {\n    const control = useAccessControl();\n    const paramsKey = JSON.stringify(params);\n\n    const [state, setState] = useState<UseCanResult>(() =>\n        control ? { allowed: false, isLoading: true } : { allowed: true, isLoading: false },\n    );\n\n    useEffect(() => {\n        if (!control) {\n            setState({ allowed: true, isLoading: false });\n            return;\n        }\n\n        let cancelled = false;\n        setState((prev) => ({ ...prev, isLoading: true }));\n\n        Promise.resolve(control.can(params))\n            .then((raw) => {\n                if (cancelled) return;\n                const result = normalize(raw);\n                setState({ allowed: result.can, isLoading: false, reason: result.reason });\n            })\n            .catch((error: unknown) => {\n                if (cancelled) return;\n                setState({\n                    allowed: false,\n                    isLoading: false,\n                    reason: error instanceof Error ? error.message : \"access check failed\",\n                });\n            });\n\n        return () => {\n            cancelled = true;\n        };\n        // `paramsKey` is the stable stringified form of `params`.\n        // eslint-disable-next-line react-hooks/exhaustive-deps\n    }, [control, paramsKey]);\n\n    return state;\n}\n"],"names":["normalize","result","useCan","params","control","useAccessControl","paramsKey","state","setState","useState","useEffect","cancelled","prev","raw","error"],"mappings":"mJAaA,SAASA,EAAUC,EAAwC,CACvD,OAAO,OAAOA,GAAW,UAAY,CAAE,IAAKA,GAAWA,CAC3D,CAWO,SAASC,EAAOC,EAAiC,CACpD,MAAMC,EAAUC,EAAAA,iBAAA,EACVC,EAAY,KAAK,UAAUH,CAAM,EAEjC,CAACI,EAAOC,CAAQ,EAAIC,EAAAA,SAAuB,IAC7CL,EAAU,CAAE,QAAS,GAAO,UAAW,EAAA,EAAS,CAAE,QAAS,GAAM,UAAW,EAAA,CAAM,EAGtFM,OAAAA,EAAAA,UAAU,IAAM,CACZ,GAAI,CAACN,EAAS,CACVI,EAAS,CAAE,QAAS,GAAM,UAAW,GAAO,EAC5C,MACJ,CAEA,IAAIG,EAAY,GAChB,OAAAH,EAAUI,IAAU,CAAE,GAAGA,EAAM,UAAW,IAAO,EAEjD,QAAQ,QAAQR,EAAQ,IAAID,CAAM,CAAC,EAC9B,KAAMU,GAAQ,CACX,GAAIF,EAAW,OACf,MAAMV,EAASD,EAAUa,CAAG,EAC5BL,EAAS,CAAE,QAASP,EAAO,IAAK,UAAW,GAAO,OAAQA,EAAO,OAAQ,CAC7E,CAAC,EACA,MAAOa,GAAmB,CACnBH,GACJH,EAAS,CACL,QAAS,GACT,UAAW,GACX,OAAQM,aAAiB,MAAQA,EAAM,QAAU,qBAAA,CACpD,CACL,CAAC,EAEE,IAAM,CACTH,EAAY,EAChB,CAGJ,EAAG,CAACP,EAASE,CAAS,CAAC,EAEhBC,CACX"}