@wow-two-beta/ui-vue 0.0.4 → 0.0.6

package/README.md

@@ -1,23 +1,7 @@
 # @wow-two-beta/ui-vue
 
-> ⚠️ **Beta-forever.** `0.x.y` with no semver guarantees, no CHANGELOG, no API stability, no graduation roadmap. Ship fast, fix-forward. Pin exact versions if stability matters.
-
-The Vue 3 port of [`@wow-two-beta/ui`](../wow-two-front-beta-sdk) — same layering, same token contract, same public subpath map, Vue components instead of React ones.
-
-The package is **self-contained**: the framework-agnostic layer (utils, themes engine, http, formatters, …) is copied rather than depended on. Deliberate for the pilot — the two packages evolve independently until the port proves out.
-
-**Coming from `@wow-two-beta/ui`? → [`MIGRATION.md`](./MIGRATION.md)** — every API delta in one list.
-
-## What's in the box
-
-| Layer | Ships |
-|---|---|
-| `presentation/*` | 231 components across `actions` (14) · `display` (73) · `feedback` (27) · `forms` (74) · `layout` (24) · `nav` (11) · `overlays` (8) — 389 SFCs |
-| `foundation/*` | 21 modules — incl. `primitives` (17 headless), `hooks` (17 composables), `utils`, `themes`, `icons`, `http`, `storage`, `validation`, `datetime`, `format`, `resilience` |
-| `domain/*` | `color` · `emoji` |
-| standalone | `router` · `query` (+ `query/testing`) · `auth` · `feedback` · `analytics` · `flags` · `forms-engine` (+ `house` + `tanstack`) |
-
-Every `presentation` group matches the React package folder-for-folder. Not yet ported: 20 of the React package's 41 `foundation` modules — `animation`, `clipboard`, `commands`, `device`, `geolocation`, `gestures`, `i18n`, `media`, `net`, `notifications`, `observers`, `screen`, `selection`, `share`, `speech`, `sync`, `undo`, `uploads`, `virtualization`, `workers`. `package.json` declares export subpaths for all 41 ahead of the source, so importing one of the 20 fails at resolve time — see [`MIGRATION.md` §11](./MIGRATION.md#11-known-gaps).
+Vue 3 components, application adapters and browser capabilities for the wow-two ecosystem.
+This beta package evolves independently of React. Pin an exact version when upgrading.
 
 ## Install
 
@@ -25,23 +9,24 @@ Every `presentation` group matches the React package folder-for-folder. Not yet
 pnpm add @wow-two-beta/ui-vue vue
 ```
 
-Three peers are **optional** — install only what the subpaths you import need:
+Vue is required. Install optional peers only for the entries you use:
 
-| Peer | Needed by |
-|---|---|
-| `vue-router@^4` | `@wow-two-beta/ui-vue/router` |
-| `@tanstack/vue-query@^5` | `@wow-two-beta/ui-vue/query` |
-| `@tanstack/vue-form@^1` | `@wow-two-beta/ui-vue/forms-engine/tanstack` |
+| Entry                    | Optional peers                                                 |
+| ------------------------ | -------------------------------------------------------------- |
+| `/router`                | `vue-router@^4`                                                |
+| `/query`                 | `@tanstack/vue-query@^5.102.8`                                 |
+| `/query/testing`         | `@tanstack/vue-query@^5.102.8`, `@vue/test-utils@^2.4.6`       |
+| `/forms-engine/tanstack` | `@tanstack/vue-form@^1`                                        |
+| `/styles.css` build      | `tailwindcss@^4.1` plus the application's Tailwind integration |
 
-The root entry and every `foundation` / `domain` / `presentation` subpath are peer-free.
+Core JavaScript entries and the house form adapter do not require these optional peers.
+The manifest's `exports` map is the entry inventory; builds fail for missing source entries.
 
 ## Use
 
-The root barrel re-exports all seven presentation groups flat, plus `utils` / `hooks` / `icons` / `primitives` / `themes` / `color` / `emoji` as namespaces:
-
 ```vue
 <script setup lang="ts">
-import { Button } from '@wow-two-beta/ui-vue';
+import { Button } from '@wow-two-beta/ui-vue/presentation/actions';
 import '@wow-two-beta/ui-vue/styles.css';
 </script>
 
@@ -50,64 +35,215 @@ import '@wow-two-beta/ui-vue/styles.css';
 </template>
 ```
 
-Subpath imports for tree-shake-friendly consumption — one per layer/group, mirroring the React package 1:1:
+`styles.css` contains Tailwind 4 source directives; process it through the application's Tailwind build.
+It registers the package's own utility classes, which Tailwind otherwise excludes inside `node_modules`.
+`themes.css` contains generated theme tokens and `themes.json` their manifest.
+Load the theme stylesheet when using a generated theme class.
+
+The root exports presentation components and the `styles`, `dom`, `optionals`, `state`, `numbers`, `json`, `icons`, `primitives`, `themes`,
+`color` and `emoji` namespaces. Dedicated subpaths expose application adapters:
 
 ```ts
-import { Button } from '@wow-two-beta/ui-vue/presentation/actions';
-import { cn } from '@wow-two-beta/ui-vue/foundation/utils';
-import { THEMES } from '@wow-two-beta/ui-vue/foundation/themes';
+import { createAppRouter } from '@wow-two-beta/ui-vue/router';
+import { queryPlugin, useAppQuery } from '@wow-two-beta/ui-vue/query';
 import { useAppForm } from '@wow-two-beta/ui-vue/forms-engine/house';
+import { THEMES } from '@wow-two-beta/ui-vue/foundation/themes';
 ```
 
-`router`, `query`, `forms-engine`, `auth`, `feedback`, `analytics` and `flags` are **not** on the root barrel — reach them by subpath, so their peers never ride along:
+Use capability names `/foundation/formatters`, `/foundation/channels`, `/foundation/history`
+and `/foundation/validators`. The retired `format`, `sync`, `undo` and `validation` entries are absent.
+
+## Exact numbers and JSON
+
+`foundation/numbers` exposes the immutable `ExactNumber` value/factory. Create values from decimal text
+or `bigint`; native safe integers have an explicit factory. Native floating-point inputs cannot recover
+precision already lost. Operations return the SDK `Result`:
 
 ```ts
-import { createAppRouter } from '@wow-two-beta/ui-vue/router';
-import { queryPlugin, useAppQuery } from '@wow-two-beta/ui-vue/query';
+import { ExactNumber, NumberRounding } from '@wow-two-beta/ui-vue/foundation/numbers';
+import { LosslessJson } from '@wow-two-beta/ui-vue/foundation/json';
+import { createApiClient } from '@wow-two-beta/ui-vue/foundation/http';
+
+const left = ExactNumber.parse('0.1');
+const right = ExactNumber.parse('0.2');
+if (left.ok && right.ok) {
+  const sum = left.value.add(right.value);
+  if (sum.ok) console.log(sum.value.toString()); // '0.3'
+}
+
+const api = createApiClient({ json: LosslessJson });
 ```
 
-## Stack
+The explicit HTTP codec handles incoming and outgoing numeric tokens without native JSON conversion.
+All decoded JSON numbers are `ExactNumber`, including small integers; endpoint decoders validate their
+shape and deliberately convert fields that need native integers. Existing clients retain their native
+JSON behavior until configured with this codec. FormData bypasses JSON encoding.
 
-- Vue 3.5+ · `<script setup>` SFCs (no TSX) · TypeScript strict
-- **Tailwind v4**, CSS-first via `@theme` — `src/index.css` is copied verbatim from the React package and shipped unprocessed; consumers run it through their own Tailwind
-- `@floating-ui/vue` · `lucide-vue-next` · `tailwind-variants`
-- Build: Vite library mode (`@vitejs/plugin-vue` + `vite-plugin-dts`), multi-entry, ESM only
-- Lint: ESLint 9 flat config — `eslint-plugin-vue` + `typescript-eslint` + `eslint-plugin-boundaries`
-- Tests: Vitest 4, four projects — `unit` (node) · `ssr` · `dom` · `browser` (Playwright chromium + `@vue/test-utils`). Smoke layer (mount + a11y), not the React package's story-driven suite.
+Addition, subtraction, multiplication and truncating remainder are exact within the documented resource
+budget. Division and rounding require `{ decimalPlaces, rounding: NumberRounding.HalfEven }` (or another
+explicit mode). Use `equals`/`compare` for numeric comparison. JavaScript operators, `Math`, native
+`JSON.stringify` and identity comparison do not implement custom numeric arithmetic. Numeric/default
+coercion and native JSON serialization throw instead of silently approximating; `toApproximateNumber`
+is the explicitly lossy conversion. Powers, roots and transcendental functions are not this API's scope.
 
-## Develop
+`LosslessJson` preserves numeric token spelling on parse/write, including exponent notation and negative
+zero. Arithmetic produces normalized tokens. It preserves ordinary strings and own object keys, rejects
+duplicate decoded keys, and builds null-prototype records. Encoding rejects unsupported custom instances,
+accessors, sparse arrays, circular references and native non-integer numbers instead of guessing or dropping
+data. Encode domain values such as dates explicitly. `NumberLimits` and `JsonLimits` document centralized
+resource budgets; exceeding them returns a failure rather than rounding, wrapping or truncating a value.
 
-```bash
-pnpm install
-pnpm build        # vite lib build + dts + index.css + themes.css/json
-pnpm dev          # vite build --watch
-pnpm typecheck    # vue-tsc --noEmit + scripts/check-sfc.mjs (real SFC compile — vue-tsc green ≠ buildable)
-pnpm check:sfc    # just the SFC compile pass
-pnpm lint         # ESLint, layering enforced by eslint-plugin-boundaries
-pnpm test         # all projects
-pnpm test:unit    # node project
-pnpm test:browser # chromium project
-pnpm coverage     # report-only, never a gate
-```
+## Architecture
+
+| Layer                | Responsibility                                                     |
+| -------------------- | ------------------------------------------------------------------ |
+| `foundation/*`       | Primitives, infrastructure and browser capabilities                |
+| `domain/*`           | Color and emoji models and operations                              |
+| `presentation/*`     | Actions, display, feedback, forms, layout, navigation and overlays |
+| Application adapters | Router, query, auth, feedback, forms, analytics and flags          |
 
-## Layering
+ESLint enforces dependency direction. Foundation cannot import higher layers.
+Application adapters have separate entries to scope optional vendor dependencies.
 
-Enforced by `eslint-plugin-boundaries`, identical to the React package:
+## Compatibility and verification
 
-- `src/foundation/*` — infra. May import `foundation` only.
-- `src/domain/*` — pure types/ops. May import `foundation`.
-- `src/presentation/*` — components. May import `foundation`, `domain`, and any sibling presentation group.
-- `src/{router,query,auth,feedback,forms-engine,analytics,flags}` — standalone top-level subpaths, each keeping its optional peer out of every other entry.
-- `src/index.ts` — the root barrel. Mirrors the React package's: foundation/domain namespaces + the seven presentation groups flat, and nothing that carries a peer.
+The package ships ESM and TypeScript declarations. Consumer checks use strict TypeScript with
+`moduleResolution: Bundler` and `skipLibCheck: false`. CommonJS consumption is unsupported.
 
-## Casing
+The sweep's local compatibility baseline is Node 20.10.0, Vue 3.5.41, TypeScript 5.9.3,
+Vite 6.4.3, Tailwind 4.3.3 and Playwright 1.62.1. Optional-adapter checks use
+Vue Router 4.6.4, Vue Query 5.102.8 and Vue Form 1.33.5. These are tested versions,
+not evidence that every version accepted by a dependency range was tested.
 
-Folders `camelCase` · files `PascalCase` (`Button.vue`, `ButtonStyles.ts`) · index files lowercase (`index.ts`).
+Tests distinguish DOM-free imports, Node server rendering, happy-dom interaction and real Chromium behavior.
+Chromium runs in ordinary and forced-colors modes. This does not establish hydration, browser or
+assistive-technology coverage for every component.
+
+Browser APIs remain subject to secure contexts, permissions and user activation. Read typed outcomes.
+Give `LocaleProvider` the same request locale on server and client; its fallback is `en-US`.
+Apply browser preferences explicitly after hydration.
+
+## Develop
+
+```bash
+pnpm install --frozen-lockfile
+pnpm exec playwright install chromium
+pnpm typecheck
+pnpm lint
+pnpm format:check
+pnpm test
+pnpm build
+pnpm check:package
+pnpm check:package --install
+```
+
+`typecheck` runs `vue-tsc`, the capability import/cycle check and actual SFC compilation.
+`check:package` validates the tarball's exports, runtime imports and strict public types in isolated core
+and optional-adapter consumers. `--install` additionally installs the tarball and peers into a fresh npm project.
+`--output /absolute/path/package.tgz` retains the exact verified artifact.
+
+Tests live under `tests/`; examples live under `apps/`.
+`pnpm playground` starts the playground; `pnpm dev` watches the library build.
+Playground source aliases derive from the same public export manifest as the library build.
 
 ## Release
 
-CI (`.github/workflows/release-vue.yml`) validates, auto-bumps `0.0.y`, and publishes on every push to `main` that touches this directory. Tags are prefixed `ui-vue-v*` so they never collide with the React package's `v*` tags.
+The repository's `release-vue` workflow validates, bumps the beta patch version, builds, checks the packed
+consumer and publishes that verified tarball. Tags use `ui-vue-v`. React has an independent release.
 
 ## License
 
 MIT
+
+## Public runtime support matrix
+
+This matrix covers all **72 manifest export keys**: 68 JavaScript entries and four asset/metadata entries. Public paths below are relative to `@wow-two-beta/ui-vue`; `.` means the package root. The package gate imports/types **64 JavaScript entries without optional adapter peers**, then all **68 with the selected peers installed**, in Node without DOM globals. Those are import/declaration checks: they do not invoke every browser operation or prove component server rendering. The final release artifact must rerun `check:package` after source changes.
+
+Verified baseline: Node **20.10.0**, Vue **3.5.41**, TypeScript **5.9.3**, ES2022 ESM build output, and Chromium **151.0.7922.34** with Playwright **1.62.1**. Chromium normal/forced-colors checks pass **30 tests across six project files**. Firefox and WebKit behavior is unverified; **no broader browser minimum is verified**. ES2022 is a compilation target, not evidence of browser API/CSS availability. Peer ranges describe install compatibility, not an assertion that every allowed version was tested. Optional adapters' tested versions appear above.
+
+Server evidence labels: **fixtures** means only the named suite's concrete render cases, **import only** means no entry-wide server-render claim, and **asset** is not a JavaScript runtime entry. Pure operations can run in Node when their listed platform inputs exist; Vue hooks require their documented owning scope. Browser methods remain conditional on API presence, permission, secure context, user activation and host policy. Their declared Result/state/error contract governs unavailable APIs; this table does not turn every method into the same fallback.
+
+| Public subpath                 | Server/render evidence                                                             | Runtime requirements when used                                                            |
+| ------------------------------ | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `.`                            | import only                                                                        | Union of re-exported core/presentation requirements; no optional adapter peers            |
+| `./foundation/state`           | import only                                                                        | Vue scope/reactivity; caller-owned state                                                  |
+| `./foundation/icons`           | fixtures: corresponding foundation `*.ssr.test.ts`                                 | Vue + SVG; Lucide dependency                                                              |
+| `./foundation/primitives`      | fixtures: corresponding foundation `*.ssr.test.ts`                                 | Mounted DOM; focus/events/Teleport; observer/positioning APIs per primitive               |
+| `./foundation/themes`          | import only                                                                        | Theme data is pure; applying a theme needs a DOM root and shipped CSS                     |
+| `./foundation/http`            | import only                                                                        | Fetch, Headers, Request/Response, AbortController; caller supplies origin/auth            |
+| `./foundation/results`         | import only                                                                        | No browser API                                                                            |
+| `./foundation/storage`         | import only                                                                        | Memory storage or selected Storage API; persistence is caller-owned                       |
+| `./foundation/storage/zustand` | import only                                                                        | Caller-supplied compatible store; selected persistence backend                            |
+| `./foundation/resilience`      | import only                                                                        | Timers/AbortSignal when retry/timeout operations run                                      |
+| `./foundation/identifiers`     | import only                                                                        | Crypto/random source for generated identifiers                                            |
+| `./foundation/i18n`            | locale render/hydration probe only; other exports import only                      | Intl; explicit request locale for deterministic first render                              |
+| `./foundation/config`          | import only                                                                        | Caller-supplied configuration sources                                                     |
+| `./foundation/shortcuts`       | import only                                                                        | Mounted event target and keyboard events                                                  |
+| `./foundation/formatters`      | import only                                                                        | Intl for localized formatters                                                             |
+| `./foundation/files`           | import only                                                                        | File/Blob and URL/FileReader/browser download APIs for selected operations                |
+| `./foundation/commands`        | import only                                                                        | Vue scope and caller command handlers; keyboard binding needs DOM                         |
+| `./foundation/errors`          | import only                                                                        | No browser API for classification                                                         |
+| `./foundation/share`           | import only                                                                        | Web Share or selected clipboard fallback; activation/permission policy                    |
+| `./foundation/logger`          | import only                                                                        | Caller log sink; console sink uses host console                                           |
+| `./foundation/device`          | import only                                                                        | Browser preference/device APIs when observed; server fallback is operation-specific       |
+| `./foundation/notifications`   | import only                                                                        | Notification/Permissions APIs; secure context and permission for requests                 |
+| `./foundation/uploads`         | import only                                                                        | Caller upload transport; File/Blob and AbortSignal                                        |
+| `./foundation/gestures`        | import only                                                                        | Mounted DOM, Pointer/Touch events and geometry                                            |
+| `./foundation/selection`       | import only                                                                        | Vue state; DOM only when consumer binds interactions                                      |
+| `./foundation/media`           | import only                                                                        | HTML media APIs; MediaDevices/MediaRecorder for selected operations and permissions       |
+| `./foundation/animation`       | import only                                                                        | DOM geometry + Web Animations when animation runs; reduced-motion preference              |
+| `./foundation/virtualization`  | import only                                                                        | Mounted scroll container and geometry/ResizeObserver                                      |
+| `./foundation/observers`       | import only                                                                        | Selected IntersectionObserver/ResizeObserver/MutationObserver; mounted target             |
+| `./foundation/crypto`          | import only                                                                        | Web Crypto + TextEncoder; secure context for SubtleCrypto operations                      |
+| `./foundation/channels`        | import only                                                                        | BroadcastChannel or configured channel backend; owned cleanup/timers                      |
+| `./foundation/idb`             | import only                                                                        | IndexedDB for database operations; explicit availability checks                           |
+| `./foundation/workers`         | import only                                                                        | Worker supplied/created by caller; CSP and worker loading policy                          |
+| `./foundation/screen`          | import only                                                                        | Selected Fullscreen/Wake Lock/orientation API; activation/secure-context policy           |
+| `./foundation/geolocation`     | import only                                                                        | Geolocation; secure context and permission                                                |
+| `./foundation/async`           | import only                                                                        | Promises, timers and AbortSignal; no DOM requirement for pure coordination                |
+| `./foundation/history`         | import only                                                                        | Caller-owned undo state; shortcut binding needs DOM                                       |
+| `./foundation/clipboard`       | import only                                                                        | Clipboard API or selected fallback; permissions/activation may apply                      |
+| `./foundation/speech`          | import only                                                                        | SpeechSynthesis/voice events for speech operations                                        |
+| `./foundation/collections`     | import only                                                                        | No browser API                                                                            |
+| `./foundation/datetime`        | import only                                                                        | Imported temporal-polyfill implementation; no global installation                         |
+| `./foundation/validators`      | import only                                                                        | No browser API for native schemas; caller Standard Schema may add requirements            |
+| `./foundation/net`             | import only                                                                        | EventSource/WebSocket for connections; timers, online events and caller polling transport |
+| `./foundation/oauth`           | import only                                                                        | Mounted DOM + Google Identity script/network; CSP and provider configuration              |
+| `./analytics`                  | import only                                                                        | Caller-owned adapter/client; browser sinks require their platform APIs                    |
+| `./flags`                      | fixtures: `tests/unit/providers/Providers.ssr.test.ts` (registered cases only)     | Caller-owned provider/flag source                                                         |
+| `./domain/color`               | import only                                                                        | No browser API for color math                                                             |
+| `./domain/emoji`               | import only                                                                        | No browser API for emoji data/search                                                      |
+| `./presentation/actions`       | fixtures: corresponding `tests/unit/presentation/*/*.ssr.test.ts`                  | Vue + DOM for interaction; per-component API requirements; shipped styles                 |
+| `./presentation/display`       | fixtures: corresponding `tests/unit/presentation/*/*.ssr.test.ts`                  | Vue + DOM for interaction; per-component API requirements; shipped styles                 |
+| `./presentation/feedback`      | fixtures: corresponding `tests/unit/presentation/*/*.ssr.test.ts`                  | Vue + DOM for interaction; per-component API requirements; shipped styles                 |
+| `./presentation/forms`         | fixtures: corresponding `tests/unit/presentation/*/*.ssr.test.ts`                  | Vue + DOM for interaction; per-component API requirements; shipped styles                 |
+| `./presentation/layout`        | fixtures: corresponding `tests/unit/presentation/*/*.ssr.test.ts`                  | Vue + DOM for interaction; per-component API requirements; shipped styles                 |
+| `./presentation/nav`           | fixtures: corresponding `tests/unit/presentation/*/*.ssr.test.ts`                  | Vue + DOM for interaction; per-component API requirements; shipped styles                 |
+| `./presentation/overlays`      | fixtures: corresponding `tests/unit/presentation/*/*.ssr.test.ts`                  | Vue + DOM for interaction; per-component API requirements; shipped styles                 |
+| `./router`                     | ProgressProvider SSR fixture only; router lifecycle is not covered by that fixture | vue-router peer; browser history requires DOM, server callers use memory history          |
+| `./query`                      | import only                                                                        | @tanstack/vue-query peer; per-app/request QueryClient and caller fetch transport          |
+| `./query/testing`              | import only                                                                        | @tanstack/vue-query + @vue/test-utils peers; DOM for mounting helpers                     |
+| `./auth`                       | fixtures: `tests/unit/providers/Providers.ssr.test.ts` (registered cases only)     | Per-app strategy/bridge; browser storage/redirect operations are strategy-specific        |
+| `./feedback`                   | import only                                                                        | Vue provider/host; mounted DOM for rendered notices                                       |
+| `./forms-engine`               | import only                                                                        | Vue + Standard Schema contract; focus helpers require DOM                                 |
+| `./forms-engine/house`         | import only                                                                        | Vue-owned form scope; transport signal handled by caller                                  |
+| `./forms-engine/tanstack`      | import only                                                                        | @tanstack/vue-form peer; Vue-owned form scope and caller transport                        |
+| `./styles.css`                 | asset                                                                              | Bundler/CSS import; package source scanning and app theme composition                     |
+| `./themes.css`                 | asset                                                                              | CSS theme tokens; apply the selected theme on an app-owned root                           |
+| `./themes.json`                | asset                                                                              | JSON consumer; no browser runtime                                                         |
+| `./package.json`               | asset                                                                              | Package metadata reader; no browser runtime                                               |
+| `./foundation/styles`          | import only                                                                        | Class/variant utilities are pure; applied appearance needs shipped CSS                    |
+| `./foundation/dom`             | import only                                                                        | Most operations need a mounted DOM target; pure normalization has no DOM requirement      |
+| `./foundation/optionals`       | import only                                                                        | No browser API                                                                            |
+| `./foundation/numbers`         | pure numeric operations                                                            | Exact-value methods; explicit precision and rounding for division; no browser API          |
+| `./foundation/json`            | pure parsing and encoding                                                          | Lossless numeric tokens; explicit resource budgets; no browser API                         |
+
+### SSR, hydration and ownership limits
+
+Node SSR fixtures create a fresh Vue app and call `renderToString` without DOM globals (`tests/support/Smoke.ts`). A successful fixture proves its selected props/slot/provider setup, not every branch, Teleport hydration or full request-resource cleanup. A separate locale probe checks two independent roots, provider replacement and deterministic happy-dom hydration even when browser language differs. No package-wide hydration guarantee is made. Portal/Teleport content requires the app's supported server/client composition; modal and focus behavior is accepted through browser tests, not Node render output.
+
+Create mutable auth bridges, query clients, form engines, stores and buses per app/request. Share only immutable data or non-user formatting caches. Server code must explicitly release any resources it starts; client unmount hooks do not run after server rendering. Provider smoke tests do not establish that every arbitrary adapter supplied by a caller disposes correctly.
+
+Focused lifecycle evidence includes auth strategy replacement/unmount and stale sign-in/out, query-client isolation and stale lazy-query reset/disposal, form reset/cancel/session invalidation, and locale root isolation. Passing real-browser focus-scope tests cover nested/portalled layers, owner documents, inert restoration and dismissal cleanup in ordinary and forced-colors Chromium. Representative public root-ref tests exercise native focus/measurement and unmount lifetime under happy-dom. This evidence does not establish geometry or keyboard acceptance for every component or browser.
+
+`foundation/datetime` imports its declared Temporal implementation locally; it does not patch a global prototype. Apps using native Temporal elsewhere own that global/runtime policy. Feature-specific API availability must be checked at the operation boundary, even on the tested Chromium baseline. Stylesheet support and forced-colors/reduced-motion behavior are separate from JavaScript import support.

package/dist/analytics/Analytics.d.ts

@@ -3,12 +3,12 @@ import { AnalyticsErrorHandler, AnalyticsProvider } from './AnalyticsProvider';
 /** Defines the options for {@link createAnalytics}. */
 export interface AnalyticsOptions {
     /** The sinks registered up front; more may join later via `register`. */
-    readonly providers?: readonly AnalyticsProvider[];
+    readonly providers?: ReadonlyArray<AnalyticsProvider>;
     /** Whether calls dispatch at all. Default `true`; flip at runtime with `setEnabled` for consent / Do-Not-Track. */
     readonly enabled?: boolean;
     /** The initial super-properties merged into every event. */
     readonly context?: AnalyticsProperties;
-    /** The max calls buffered while no provider is registered — the oldest is dropped past it. Default `100`; `0` disables buffering. */
+    /** The calls buffered while no provider is registered; the oldest drops past it. Default `100`, `0` disables. */
     readonly maxQueueSize?: number;
     /** Receives every sink failure. Omitted means failures are swallowed — analytics is never worth an app crash. */
     readonly onError?: AnalyticsErrorHandler;
@@ -35,14 +35,14 @@ export interface Analytics {
     setEnabled(enabled: boolean): void;
     /** Reports whether dispatch is currently on. */
     isEnabled(): boolean;
-    /** Awaits every registered sink's optional `flush` — for page unload and test drainage. */
+    /** Awaits dispatched calls, then every registered sink's optional `flush` — for page unload and test drainage. */
     flush(): Promise<void>;
 }
-/** Creates an {@link Analytics} client — one per app, shared by every caller. Apps that don't need isolation use the default {@link analytics}. */
+/** Creates an {@link Analytics} client — one per app. Without isolation, use the default {@link analytics}. */
 export declare function createAnalytics(options?: AnalyticsOptions): Analytics;
 /** The default app-wide client — what the bare {@link track} / {@link identify} / {@link page} helpers bind to. */
 export declare const analytics: Analytics;
-/** Records a named event on the default {@link analytics} client — the everyday `track('signup_completed')` entry point. */
+/** Records a named event on the default {@link analytics} client — the `track('signup_completed')` entry point. */
 export declare function track(name: string, properties?: AnalyticsProperties): void;
 /** Binds subsequent calls on the default {@link analytics} client to a user. */
 export declare function identify(userId: string, traits?: AnalyticsProperties): void;

package/dist/analytics/AnalyticsProvider.d.ts

@@ -33,5 +33,5 @@ export interface AnalyticsErrorContext {
     /** The call being dispatched — omitted for a `flush` failure, which belongs to no single call. */
     readonly call?: AnalyticsCall;
 }
-/** Defines the sink-failure handler — analytics must never break the caller, so every provider throw lands here instead. */
+/** Defines the sink-failure handler; analytics never breaks the caller, so a provider throw lands here. */
 export type AnalyticsErrorHandler = (error: unknown, context: AnalyticsErrorContext) => void;

package/dist/analytics/MemoryAnalyticsProvider.d.ts

@@ -3,13 +3,13 @@ import { AnalyticsProvider } from './AnalyticsProvider';
 /** Defines the in-memory sink returned by {@link memoryAnalyticsProvider} — a provider plus the capture it records. */
 export interface MemoryAnalyticsProvider extends AnalyticsProvider {
     /** Every call received, in dispatch order across all three kinds. */
-    readonly calls: readonly AnalyticsCall[];
+    readonly calls: ReadonlyArray<AnalyticsCall>;
     /** The `track` events received, in order. */
-    readonly events: readonly AnalyticsEvent[];
+    readonly events: ReadonlyArray<AnalyticsEvent>;
     /** The `page` events received, in order. */
-    readonly pages: readonly AnalyticsEvent[];
+    readonly pages: ReadonlyArray<AnalyticsEvent>;
     /** The `identify` payloads received, in order. */
-    readonly identities: readonly AnalyticsIdentity[];
+    readonly identities: ReadonlyArray<AnalyticsIdentity>;
     /** How many times `flush` was invoked. */
     readonly flushCount: number;
     /** Clears every capture — for a `beforeEach` reset of a shared instance. */

package/dist/analytics/index.js

@@ -24,6 +24,7 @@ function createAnalytics(options = {}) {
   const { maxQueueSize = 100, onError, now = Date.now } = options;
   const providers = new Set(options.providers ?? []);
   const queue = [];
+  const pendingDeliveries = /* @__PURE__ */ new Set();
   let context = { ...options.context };
   let enabled = options.enabled ?? true;
   const report = (error, provider, phase, call) => {
@@ -47,7 +48,7 @@ function createAnalytics(options = {}) {
     }
     return Promise.resolve();
   };
-  const deliver = (provider, call) => {
+  const deliverNow = (provider, call) => {
     switch (call.kind) {
       case AnalyticsCallKind.Track:
         return invoke(provider, AnalyticsFailurePhase.Track, call, () => provider.track?.(call.event));
@@ -57,6 +58,12 @@ function createAnalytics(options = {}) {
         return invoke(provider, AnalyticsFailurePhase.Page, call, () => provider.page?.(call.event));
     }
   };
+  const deliver = (provider, call) => {
+    const pending = deliverNow(provider, call);
+    pendingDeliveries.add(pending);
+    void pending.finally(() => pendingDeliveries.delete(pending));
+    return pending;
+  };
   const dispatch = (call) => {
     if (!enabled) return;
     if (providers.size === 0) {
@@ -108,6 +115,7 @@ function createAnalytics(options = {}) {
       return enabled;
     },
     async flush() {
+      await Promise.all([...pendingDeliveries]);
       const drains = [...providers].map(
         (provider) => invoke(provider, AnalyticsFailurePhase.Flush, void 0, () => provider.flush?.())
       );

package/dist/analytics/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../src/analytics/AnalyticsEvent.ts","../../src/analytics/AnalyticsProvider.ts","../../src/analytics/Analytics.ts","../../src/analytics/ConsoleAnalyticsProvider.ts","../../src/analytics/MemoryAnalyticsProvider.ts"],"sourcesContent":["// The wire model every sink sees. Three canonical calls (`track` · `identify` · `page`) rather than one\n// generic event, because every vendor (GA · PostHog · Segment) models exactly these three — a single\n// shape would force each adapter to re-derive the distinction from a magic property name. `page` carries\n// the same `AnalyticsEvent` payload as `track` but stays a separate call so an adapter can route it to a\n// pageview rather than a custom event.\n//\n// Two non-obvious decisions:\n//\n// - **The client stamps `timestamp`, not the adapter.** A call buffered before a provider registers keeps\n//   the time it HAPPENED, not the time it was delivered — otherwise the whole pre-init window collapses\n//   onto the instant the vendor script finished loading.\n// - **`AnalyticsCall` exists for that buffer.** Replay has to preserve `identify` → `track` ordering (an\n//   event replayed before its identify attaches to the wrong profile), so the queue holds discriminated\n//   calls rather than a flat event list.\n\n/** Defines the free-form properties attached to a call — JSON-shaped values a sink serializes. */\nexport type AnalyticsProperties = Record<string, unknown>;\n\n/** Provides the event name used when `page()` is called without one — sinks route it as a page / screen view. */\nexport const DefaultPageName = 'page_view';\n\n/** Defines a single analytics event handed to every registered sink — the payload of a `track` or `page` call. */\nexport interface AnalyticsEvent {\n  /** The event name (`'checkout_completed'`; a route like `'/pricing'` for a page). */\n  readonly name: string;\n\n  /** The merged properties — super-properties first, call-site values winning. Omitted when empty. */\n  readonly properties?: AnalyticsProperties;\n\n  /** When the call happened (epoch ms), stamped at call time — never at delivery time. */\n  readonly timestamp: number;\n}\n\n/** Defines the payload of an `identify` call — who the user is, plus optional descriptive traits. */\nexport interface AnalyticsIdentity {\n  /** The stable user id the sink keys the profile on. */\n  readonly userId: string;\n\n  /** The user traits (email, plan, locale…) — these describe the PERSON, so super-properties are never merged in. */\n  readonly traits?: AnalyticsProperties;\n\n  /** When the call happened (epoch ms), stamped at call time. */\n  readonly timestamp: number;\n}\n\n/** Defines the kind of call dispatched or buffered — the discriminant of {@link AnalyticsCall}. */\nexport const AnalyticsCallKind = {\n  /** Refers to a `track` call — a named event. */\n  Track: 'track',\n  /** Refers to an `identify` call — binding subsequent events to a user. */\n  Identify: 'identify',\n  /** Refers to a `page` call — a page / screen view. */\n  Page: 'page',\n} as const;\n\nexport type AnalyticsCallKind = (typeof AnalyticsCallKind)[keyof typeof AnalyticsCallKind];\n\n/** Defines one dispatched or buffered call — discriminated so a replayed queue preserves cross-kind ordering. */\nexport type AnalyticsCall =\n  /** Refers to a `track` call carrying its named event. */\n  | { readonly kind: typeof AnalyticsCallKind.Track; readonly event: AnalyticsEvent }\n  /** Refers to an `identify` call carrying its user identity. */\n  | { readonly kind: typeof AnalyticsCallKind.Identify; readonly identity: AnalyticsIdentity }\n  /** Refers to a `page` call carrying its page-view event. */\n  | { readonly kind: typeof AnalyticsCallKind.Page; readonly event: AnalyticsEvent };\n","// The sink seam — one small interface between the client and whatever actually ships the data\n// (GA · PostHog · Segment · a console logger · a test double).\n//\n// Every method is OPTIONAL: a sink that only cares about events implements `track` and nothing else, and\n// the client skips what is absent instead of making each adapter stub three no-ops. Methods may return a\n// promise, but the client never awaits one on the hot path — `track` stays fire-and-forget, so a rejected\n// promise is routed to `onError` exactly like a synchronous throw (see `Analytics.ts`). `flush` is the one\n// call a consumer awaits, for page-unload and test drainage.\n//\n// `AnalyticsFailurePhase` reuses the `AnalyticsCallKind` values and adds `flush`, so a handler can switch\n// over one vocabulary covering every place a third-party sink can fail.\n\nimport { AnalyticsCallKind, type AnalyticsCall, type AnalyticsEvent, type AnalyticsIdentity } from './AnalyticsEvent';\n\n/** Defines a sink the client fans calls out to — implement only the calls the vendor actually supports. */\nexport interface AnalyticsProvider {\n  /** The name used in diagnostics and `onError` reporting. */\n  readonly name?: string;\n\n  /** Ships a tracked event. */\n  readonly track?: (event: AnalyticsEvent) => void | Promise<void>;\n\n  /** Binds subsequent events to a user. */\n  readonly identify?: (identity: AnalyticsIdentity) => void | Promise<void>;\n\n  /** Ships a page / screen view. */\n  readonly page?: (event: AnalyticsEvent) => void | Promise<void>;\n\n  /** Drains whatever the sink batched — the only method `Analytics.flush()` awaits. */\n  readonly flush?: () => void | Promise<void>;\n}\n\n/** Defines where a provider failure came from — the three call kinds plus `flush`. */\nexport const AnalyticsFailurePhase = {\n  /** Refers to a failure raised by `track`. */\n  Track: AnalyticsCallKind.Track,\n  /** Refers to a failure raised by `identify`. */\n  Identify: AnalyticsCallKind.Identify,\n  /** Refers to a failure raised by `page`. */\n  Page: AnalyticsCallKind.Page,\n  /** Refers to a failure raised by `flush`. */\n  Flush: 'flush',\n} as const;\n\nexport type AnalyticsFailurePhase = (typeof AnalyticsFailurePhase)[keyof typeof AnalyticsFailurePhase];\n\n/** Defines the context handed to `onError` when a sink throws or rejects. */\nexport interface AnalyticsErrorContext {\n  /** The provider that failed. */\n  readonly provider: AnalyticsProvider;\n\n  /** The phase the failure came from. */\n  readonly phase: AnalyticsFailurePhase;\n\n  /** The call being dispatched — omitted for a `flush` failure, which belongs to no single call. */\n  readonly call?: AnalyticsCall;\n}\n\n/** Defines the sink-failure handler — analytics must never break the caller, so every provider throw lands here instead. */\nexport type AnalyticsErrorHandler = (error: unknown, context: AnalyticsErrorContext) => void;\n","// The client every app talks to. Five decisions worth stating, because none of them is the obvious one:\n//\n// - **Failure isolation.** A sink is third-party code on a non-critical path, so a throwing (or rejecting)\n//   provider must never reach the caller — `track()` is called from render paths and click handlers where\n//   an exception is a real bug. Every dispatch is wrapped and routed to `onError`; one broken provider\n//   never stops the others in the fan-out.\n// - **Buffering before ready.** Vendor scripts load late, so calls made before any provider registers are\n//   queued (drop-oldest at `maxQueueSize`) and replayed on the first `register`. Without this the most\n//   valuable events — the ones at app start — are exactly the ones silently lost.\n// - **The enabled gate is read at CALL time, not at construction.** Consent and Do-Not-Track resolve after\n//   the client exists. Disabled calls do not queue either, and `setEnabled(false)` DROPS what is already\n//   buffered: replaying pre-consent events the moment consent is granted would defeat the gate.\n// - **Super-properties merge into event properties only, never into `identify` traits.** Traits describe\n//   the person, properties describe the moment; merging the two writes request-scoped noise into the\n//   permanent user profile.\n// - **The queue drains to the newly registered provider only.** The buffer is non-empty only while no\n//   provider is registered, so the one that registers is the only possible recipient — a later provider\n//   gets live traffic, never a replay of history it was absent for.\n\nimport {\n  AnalyticsCallKind,\n  DefaultPageName,\n  type AnalyticsCall,\n  type AnalyticsEvent,\n  type AnalyticsIdentity,\n  type AnalyticsProperties,\n} from './AnalyticsEvent';\nimport { AnalyticsFailurePhase, type AnalyticsErrorHandler, type AnalyticsProvider } from './AnalyticsProvider';\n\n/** Narrows an unknown sink return value to a thenable — a vendor adapter may hand back a non-native promise. */\nfunction isPromiseLike(value: unknown): value is PromiseLike<unknown> {\n  return typeof value === 'object' && value !== null && typeof (value as { then?: unknown }).then === 'function';\n}\n\n/** Defines the options for {@link createAnalytics}. */\nexport interface AnalyticsOptions {\n  /** The sinks registered up front; more may join later via `register`. */\n  readonly providers?: readonly AnalyticsProvider[];\n\n  /** Whether calls dispatch at all. Default `true`; flip at runtime with `setEnabled` for consent / Do-Not-Track. */\n  readonly enabled?: boolean;\n\n  /** The initial super-properties merged into every event. */\n  readonly context?: AnalyticsProperties;\n\n  /** The max calls buffered while no provider is registered — the oldest is dropped past it. Default `100`; `0` disables buffering. */\n  readonly maxQueueSize?: number;\n\n  /** Receives every sink failure. Omitted means failures are swallowed — analytics is never worth an app crash. */\n  readonly onError?: AnalyticsErrorHandler;\n\n  /** Supplies the call timestamp (epoch ms) — injectable for deterministic tests. Default `Date.now`. */\n  readonly now?: () => number;\n}\n\n/** Defines the headless analytics client — fans the three canonical calls out to every registered sink. */\nexport interface Analytics {\n  /** Records a named event, with super-properties merged under the given properties. */\n  track(name: string, properties?: AnalyticsProperties): void;\n\n  /** Binds subsequent calls to a user, with optional traits describing them. */\n  identify(userId: string, traits?: AnalyticsProperties): void;\n\n  /** Records a page / screen view; the name defaults to {@link DefaultPageName}. */\n  page(name?: string, properties?: AnalyticsProperties): void;\n\n  /** Merges super-properties into the set attached to every subsequent event. */\n  setContext(context: AnalyticsProperties): void;\n\n  /** Drops every super-property. */\n  clearContext(): void;\n\n  /** Reads a copy of the current super-properties. */\n  getContext(): AnalyticsProperties;\n\n  /** Registers a sink, replaying anything buffered into it; returns an unregister. */\n  register(provider: AnalyticsProvider): () => void;\n\n  /** Turns dispatch on / off at runtime — the consent gate. Turning it off discards anything still buffered. */\n  setEnabled(enabled: boolean): void;\n\n  /** Reports whether dispatch is currently on. */\n  isEnabled(): boolean;\n\n  /** Awaits every registered sink's optional `flush` — for page unload and test drainage. */\n  flush(): Promise<void>;\n}\n\n/** Creates an {@link Analytics} client — one per app, shared by every caller. Apps that don't need isolation use the default {@link analytics}. */\nexport function createAnalytics(options: AnalyticsOptions = {}): Analytics {\n  const { maxQueueSize = 100, onError, now = Date.now } = options;\n  const providers = new Set<AnalyticsProvider>(options.providers ?? []);\n  const queue: AnalyticsCall[] = [];\n  let context: AnalyticsProperties = { ...options.context };\n  let enabled = options.enabled ?? true;\n\n  /** Routes a sink failure to `onError` — an `onError` that itself throws is swallowed, since there is nowhere left to report. */\n  const report = (error: unknown, provider: AnalyticsProvider, phase: AnalyticsFailurePhase, call?: AnalyticsCall): void => {\n    if (!onError) return;\n    try {\n      onError(error, { provider, phase, call });\n    } catch {\n      // The handler is the last line of defence; a throw here must not reach the caller either.\n    }\n  };\n\n  /** Invokes one sink method under full isolation — a synchronous throw and a rejected promise both land in `report`. */\n  const invoke = (\n    provider: AnalyticsProvider,\n    phase: AnalyticsFailurePhase,\n    call: AnalyticsCall | undefined,\n    method: () => void | Promise<void>,\n  ): Promise<void> => {\n    try {\n      const result: unknown = method();\n      if (isPromiseLike(result)) {\n        return Promise.resolve(result).then(\n          () => undefined,\n          (error: unknown) => report(error, provider, phase, call),\n        );\n      }\n    } catch (error) {\n      report(error, provider, phase, call);\n    }\n    return Promise.resolve();\n  };\n\n  /** Delivers one call to one sink, picking the matching method — an absent method is simply skipped. */\n  const deliver = (provider: AnalyticsProvider, call: AnalyticsCall): Promise<void> => {\n    switch (call.kind) {\n      case AnalyticsCallKind.Track:\n        return invoke(provider, AnalyticsFailurePhase.Track, call, () => provider.track?.(call.event));\n      case AnalyticsCallKind.Identify:\n        return invoke(provider, AnalyticsFailurePhase.Identify, call, () => provider.identify?.(call.identity));\n      case AnalyticsCallKind.Page:\n        return invoke(provider, AnalyticsFailurePhase.Page, call, () => provider.page?.(call.event));\n    }\n  };\n\n  /** Fans one call out to every registered sink, or buffers it while none has registered yet. */\n  const dispatch = (call: AnalyticsCall): void => {\n    if (!enabled) return;\n\n    if (providers.size === 0) {\n      if (maxQueueSize <= 0) return;\n      while (queue.length >= maxQueueSize) queue.shift();\n      queue.push(call);\n      return;\n    }\n\n    for (const provider of providers) void deliver(provider, call);\n  };\n\n  /** Builds the event — super-properties spread first so a call-site key of the same name wins. */\n  const toEvent = (name: string, properties?: AnalyticsProperties): AnalyticsEvent => {\n    const merged: AnalyticsProperties = { ...context, ...properties };\n    const timestamp = now();\n    return Object.keys(merged).length > 0 ? { name, properties: merged, timestamp } : { name, timestamp };\n  };\n\n  return {\n    track(name: string, properties?: AnalyticsProperties): void {\n      dispatch({ kind: AnalyticsCallKind.Track, event: toEvent(name, properties) });\n    },\n\n    identify(userId: string, traits?: AnalyticsProperties): void {\n      const timestamp = now();\n      const identity: AnalyticsIdentity = traits ? { userId, traits, timestamp } : { userId, timestamp };\n      dispatch({ kind: AnalyticsCallKind.Identify, identity });\n    },\n\n    page(name?: string, properties?: AnalyticsProperties): void {\n      dispatch({ kind: AnalyticsCallKind.Page, event: toEvent(name ?? DefaultPageName, properties) });\n    },\n\n    setContext(next: AnalyticsProperties): void {\n      context = { ...context, ...next };\n    },\n\n    clearContext(): void {\n      context = {};\n    },\n\n    getContext(): AnalyticsProperties {\n      return { ...context };\n    },\n\n    register(provider: AnalyticsProvider): () => void {\n      providers.add(provider);\n\n      if (queue.length > 0) {\n        for (const call of queue.splice(0, queue.length)) void deliver(provider, call);\n      }\n\n      return () => void providers.delete(provider);\n    },\n\n    setEnabled(next: boolean): void {\n      enabled = next;\n      if (!next) queue.length = 0;\n    },\n\n    isEnabled(): boolean {\n      return enabled;\n    },\n\n    async flush(): Promise<void> {\n      const drains = [...providers].map((provider) =>\n        invoke(provider, AnalyticsFailurePhase.Flush, undefined, () => provider.flush?.()),\n      );\n      await Promise.all(drains);\n    },\n  };\n}\n\n/** The default app-wide client — what the bare {@link track} / {@link identify} / {@link page} helpers bind to. */\nexport const analytics: Analytics = createAnalytics();\n\n/** Records a named event on the default {@link analytics} client — the everyday `track('signup_completed')` entry point. */\nexport function track(name: string, properties?: AnalyticsProperties): void {\n  analytics.track(name, properties);\n}\n\n/** Binds subsequent calls on the default {@link analytics} client to a user. */\nexport function identify(userId: string, traits?: AnalyticsProperties): void {\n  analytics.identify(userId, traits);\n}\n\n/** Records a page / screen view on the default {@link analytics} client. */\nexport function page(name?: string, properties?: AnalyticsProperties): void {\n  analytics.page(name, properties);\n}\n","// The dev sink — the \"is anything even firing?\" provider.\n//\n// Deliberately NOT registered by default: an SDK that logs unasked is noise (GWDNBM), so an app opts in\n// explicitly. `console` is read inside each call rather than captured at factory time, so a test that\n// stubs `console.info` after construction still sees the stub, and importing this file stays free of any\n// environment assumption.\n\nimport type { AnalyticsProvider } from './AnalyticsProvider';\n\n/** Defines the options for {@link consoleAnalyticsProvider}. */\nexport interface ConsoleAnalyticsProviderOptions {\n  /** The tag each line is prefixed with. Default `'[analytics]'`. */\n  readonly prefix?: string;\n}\n\n/** Creates a console-logging sink for development — one line per call, nothing batched, nothing to flush. */\nexport function consoleAnalyticsProvider(options: ConsoleAnalyticsProviderOptions = {}): AnalyticsProvider {\n  const prefix = options.prefix ?? '[analytics]';\n\n  return {\n    name: 'console',\n    track: (event) => console.info(`${prefix} track`, event.name, event.properties ?? {}),\n    identify: (identity) => console.info(`${prefix} identify`, identity.userId, identity.traits ?? {}),\n    page: (event) => console.info(`${prefix} page`, event.name, event.properties ?? {}),\n  };\n}\n","// The test double — a sink that ships nowhere and remembers everything.\n//\n// Assertions want two different views of the same traffic: \"which events fired\" (`events`) and \"what\n// happened, in order, across all three call kinds\" (`calls`). Deriving one from the other at every\n// assertion site is noise, so both are recorded. The arrays surface through getters typed `readonly`, so\n// a test reads the live capture without being able to push into it. `flushCount` is a plain counter\n// rather than a spy, so drainage can be asserted without wiring a mocking library in.\n\nimport { AnalyticsCallKind, type AnalyticsCall, type AnalyticsEvent, type AnalyticsIdentity } from './AnalyticsEvent';\nimport type { AnalyticsProvider } from './AnalyticsProvider';\n\n/** Defines the in-memory sink returned by {@link memoryAnalyticsProvider} — a provider plus the capture it records. */\nexport interface MemoryAnalyticsProvider extends AnalyticsProvider {\n  /** Every call received, in dispatch order across all three kinds. */\n  readonly calls: readonly AnalyticsCall[];\n\n  /** The `track` events received, in order. */\n  readonly events: readonly AnalyticsEvent[];\n\n  /** The `page` events received, in order. */\n  readonly pages: readonly AnalyticsEvent[];\n\n  /** The `identify` payloads received, in order. */\n  readonly identities: readonly AnalyticsIdentity[];\n\n  /** How many times `flush` was invoked. */\n  readonly flushCount: number;\n\n  /** Clears every capture — for a `beforeEach` reset of a shared instance. */\n  reset(): void;\n}\n\n/** Creates an in-memory sink capturing every call — the test double for asserting what an app reports. */\nexport function memoryAnalyticsProvider(): MemoryAnalyticsProvider {\n  const calls: AnalyticsCall[] = [];\n  const events: AnalyticsEvent[] = [];\n  const pages: AnalyticsEvent[] = [];\n  const identities: AnalyticsIdentity[] = [];\n  let flushCount = 0;\n\n  return {\n    name: 'memory',\n\n    get calls() {\n      return calls;\n    },\n    get events() {\n      return events;\n    },\n    get pages() {\n      return pages;\n    },\n    get identities() {\n      return identities;\n    },\n    get flushCount() {\n      return flushCount;\n    },\n\n    track: (event) => {\n      calls.push({ kind: AnalyticsCallKind.Track, event });\n      events.push(event);\n    },\n\n    identify: (identity) => {\n      calls.push({ kind: AnalyticsCallKind.Identify, identity });\n      identities.push(identity);\n    },\n\n    page: (event) => {\n      calls.push({ kind: AnalyticsCallKind.Page, event });\n      pages.push(event);\n    },\n\n    flush: () => {\n      flushCount += 1;\n    },\n\n    reset: () => {\n      calls.length = 0;\n      events.length = 0;\n      pages.length = 0;\n      identities.length = 0;\n      flushCount = 0;\n    },\n  };\n}\n"],"names":[],"mappings":"AAmBO,MAAM,kBAAkB;AA2BxB,MAAM,oBAAoB;AAAA;AAAA,EAE/B,OAAO;AAAA;AAAA,EAEP,UAAU;AAAA;AAAA,EAEV,MAAM;AACR;ACpBO,MAAM,wBAAwB;AAAA;AAAA,EAEnC,OAAO,kBAAkB;AAAA;AAAA,EAEzB,UAAU,kBAAkB;AAAA;AAAA,EAE5B,MAAM,kBAAkB;AAAA;AAAA,EAExB,OAAO;AACT;ACZA,SAAS,cAAc,OAA+C;AACpE,SAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,OAAQ,MAA6B,SAAS;AACtG;AAyDO,SAAS,gBAAgB,UAA4B,IAAe;AACzE,QAAM,EAAE,eAAe,KAAK,SAAS,MAAM,KAAK,QAAQ;AACxD,QAAM,YAAY,IAAI,IAAuB,QAAQ,aAAa,CAAA,CAAE;AACpE,QAAM,QAAyB,CAAA;AAC/B,MAAI,UAA+B,EAAE,GAAG,QAAQ,QAAA;AAChD,MAAI,UAAU,QAAQ,WAAW;AAGjC,QAAM,SAAS,CAAC,OAAgB,UAA6B,OAA8B,SAA+B;AACxH,QAAI,CAAC,QAAS;AACd,QAAI;AACF,cAAQ,OAAO,EAAE,UAAU,OAAO,MAAM;AAAA,IAC1C,QAAQ;AAAA,IAER;AAAA,EACF;AAGA,QAAM,SAAS,CACb,UACA,OACA,MACA,WACkB;AAClB,QAAI;AACF,YAAM,SAAkB,OAAA;AACxB,UAAI,cAAc,MAAM,GAAG;AACzB,eAAO,QAAQ,QAAQ,MAAM,EAAE;AAAA,UAC7B,MAAM;AAAA,UACN,CAAC,UAAmB,OAAO,OAAO,UAAU,OAAO,IAAI;AAAA,QAAA;AAAA,MAE3D;AAAA,IACF,SAAS,OAAO;AACd,aAAO,OAAO,UAAU,OAAO,IAAI;AAAA,IACrC;AACA,WAAO,QAAQ,QAAA;AAAA,EACjB;AAGA,QAAM,UAAU,CAAC,UAA6B,SAAuC;AACnF,YAAQ,KAAK,MAAA;AAAA,MACX,KAAK,kBAAkB;AACrB,eAAO,OAAO,UAAU,sBAAsB,OAAO,MAAM,MAAM,SAAS,QAAQ,KAAK,KAAK,CAAC;AAAA,MAC/F,KAAK,kBAAkB;AACrB,eAAO,OAAO,UAAU,sBAAsB,UAAU,MAAM,MAAM,SAAS,WAAW,KAAK,QAAQ,CAAC;AAAA,MACxG,KAAK,kBAAkB;AACrB,eAAO,OAAO,UAAU,sBAAsB,MAAM,MAAM,MAAM,SAAS,OAAO,KAAK,KAAK,CAAC;AAAA,IAAA;AAAA,EAEjG;AAGA,QAAM,WAAW,CAAC,SAA8B;AAC9C,QAAI,CAAC,QAAS;AAEd,QAAI,UAAU,SAAS,GAAG;AACxB,UAAI,gBAAgB,EAAG;AACvB,aAAO,MAAM,UAAU,aAAc,OAAM,MAAA;AAC3C,YAAM,KAAK,IAAI;AACf;AAAA,IACF;AAEA,eAAW,YAAY,UAAW,MAAK,QAAQ,UAAU,IAAI;AAAA,EAC/D;AAGA,QAAM,UAAU,CAAC,MAAc,eAAqD;AAClF,UAAM,SAA8B,EAAE,GAAG,SAAS,GAAG,WAAA;AACrD,UAAM,YAAY,IAAA;AAClB,WAAO,OAAO,KAAK,MAAM,EAAE,SAAS,IAAI,EAAE,MAAM,YAAY,QAAQ,UAAA,IAAc,EAAE,MAAM,UAAA;AAAA,EAC5F;AAEA,SAAO;AAAA,IACL,MAAM,MAAc,YAAwC;AAC1D,eAAS,EAAE,MAAM,kBAAkB,OAAO,OAAO,QAAQ,MAAM,UAAU,GAAG;AAAA,IAC9E;AAAA,IAEA,SAAS,QAAgB,QAAoC;AAC3D,YAAM,YAAY,IAAA;AAClB,YAAM,WAA8B,SAAS,EAAE,QAAQ,QAAQ,UAAA,IAAc,EAAE,QAAQ,UAAA;AACvF,eAAS,EAAE,MAAM,kBAAkB,UAAU,UAAU;AAAA,IACzD;AAAA,IAEA,KAAK,MAAe,YAAwC;AAC1D,eAAS,EAAE,MAAM,kBAAkB,MAAM,OAAO,QAAQ,QAAQ,iBAAiB,UAAU,GAAG;AAAA,IAChG;AAAA,IAEA,WAAW,MAAiC;AAC1C,gBAAU,EAAE,GAAG,SAAS,GAAG,KAAA;AAAA,IAC7B;AAAA,IAEA,eAAqB;AACnB,gBAAU,CAAA;AAAA,IACZ;AAAA,IAEA,aAAkC;AAChC,aAAO,EAAE,GAAG,QAAA;AAAA,IACd;AAAA,IAEA,SAAS,UAAyC;AAChD,gBAAU,IAAI,QAAQ;AAEtB,UAAI,MAAM,SAAS,GAAG;AACpB,mBAAW,QAAQ,MAAM,OAAO,GAAG,MAAM,MAAM,EAAG,MAAK,QAAQ,UAAU,IAAI;AAAA,MAC/E;AAEA,aAAO,MAAM,KAAK,UAAU,OAAO,QAAQ;AAAA,IAC7C;AAAA,IAEA,WAAW,MAAqB;AAC9B,gBAAU;AACV,UAAI,CAAC,KAAM,OAAM,SAAS;AAAA,IAC5B;AAAA,IAEA,YAAqB;AACnB,aAAO;AAAA,IACT;AAAA,IAEA,MAAM,QAAuB;AAC3B,YAAM,SAAS,CAAC,GAAG,SAAS,EAAE;AAAA,QAAI,CAAC,aACjC,OAAO,UAAU,sBAAsB,OAAO,QAAW,MAAM,SAAS,QAAA,CAAS;AAAA,MAAA;AAEnF,YAAM,QAAQ,IAAI,MAAM;AAAA,IAC1B;AAAA,EAAA;AAEJ;AAGO,MAAM,YAAuB,gBAAA;AAG7B,SAAS,MAAM,MAAc,YAAwC;AAC1E,YAAU,MAAM,MAAM,UAAU;AAClC;AAGO,SAAS,SAAS,QAAgB,QAAoC;AAC3E,YAAU,SAAS,QAAQ,MAAM;AACnC;AAGO,SAAS,KAAK,MAAe,YAAwC;AAC1E,YAAU,KAAK,MAAM,UAAU;AACjC;ACvNO,SAAS,yBAAyB,UAA2C,IAAuB;AACzG,QAAM,SAAS,QAAQ,UAAU;AAEjC,SAAO;AAAA,IACL,MAAM;AAAA,IACN,OAAO,CAAC,UAAU,QAAQ,KAAK,GAAG,MAAM,UAAU,MAAM,MAAM,MAAM,cAAc,CAAA,CAAE;AAAA,IACpF,UAAU,CAAC,aAAa,QAAQ,KAAK,GAAG,MAAM,aAAa,SAAS,QAAQ,SAAS,UAAU,CAAA,CAAE;AAAA,IACjG,MAAM,CAAC,UAAU,QAAQ,KAAK,GAAG,MAAM,SAAS,MAAM,MAAM,MAAM,cAAc,CAAA,CAAE;AAAA,EAAA;AAEtF;ACQO,SAAS,0BAAmD;AACjE,QAAM,QAAyB,CAAA;AAC/B,QAAM,SAA2B,CAAA;AACjC,QAAM,QAA0B,CAAA;AAChC,QAAM,aAAkC,CAAA;AACxC,MAAI,aAAa;AAEjB,SAAO;AAAA,IACL,MAAM;AAAA,IAEN,IAAI,QAAQ;AACV,aAAO;AAAA,IACT;AAAA,IACA,IAAI,SAAS;AACX,aAAO;AAAA,IACT;AAAA,IACA,IAAI,QAAQ;AACV,aAAO;AAAA,IACT;AAAA,IACA,IAAI,aAAa;AACf,aAAO;AAAA,IACT;AAAA,IACA,IAAI,aAAa;AACf,aAAO;AAAA,IACT;AAAA,IAEA,OAAO,CAAC,UAAU;AAChB,YAAM,KAAK,EAAE,MAAM,kBAAkB,OAAO,OAAO;AACnD,aAAO,KAAK,KAAK;AAAA,IACnB;AAAA,IAEA,UAAU,CAAC,aAAa;AACtB,YAAM,KAAK,EAAE,MAAM,kBAAkB,UAAU,UAAU;AACzD,iBAAW,KAAK,QAAQ;AAAA,IAC1B;AAAA,IAEA,MAAM,CAAC,UAAU;AACf,YAAM,KAAK,EAAE,MAAM,kBAAkB,MAAM,OAAO;AAClD,YAAM,KAAK,KAAK;AAAA,IAClB;AAAA,IAEA,OAAO,MAAM;AACX,oBAAc;AAAA,IAChB;AAAA,IAEA,OAAO,MAAM;AACX,YAAM,SAAS;AACf,aAAO,SAAS;AAChB,YAAM,SAAS;AACf,iBAAW,SAAS;AACpB,mBAAa;AAAA,IACf;AAAA,EAAA;AAEJ;"}
+{"version":3,"file":"index.js","sources":["../../src/analytics/AnalyticsEvent.ts","../../src/analytics/AnalyticsProvider.ts","../../src/analytics/Analytics.ts","../../src/analytics/ConsoleAnalyticsProvider.ts","../../src/analytics/MemoryAnalyticsProvider.ts"],"sourcesContent":["// The wire model every sink sees. Three canonical calls (`track` · `identify` · `page`) rather than one\n// generic event, because every vendor (GA · PostHog · Segment) models exactly these three — a single\n// shape would force each adapter to re-derive the distinction from a magic property name. `page` carries\n// the same `AnalyticsEvent` payload as `track` but stays a separate call so an adapter can route it to a\n// pageview rather than a custom event.\n//\n// Two non-obvious decisions:\n//\n// - **The client stamps `timestamp`, not the adapter.** A call buffered before a provider registers keeps\n//   the time it HAPPENED, not the time it was delivered — otherwise the whole pre-init window collapses\n//   onto the instant the vendor script finished loading.\n// - **`AnalyticsCall` exists for that buffer.** Replay has to preserve `identify` → `track` ordering (an\n//   event replayed before its identify attaches to the wrong profile), so the queue holds discriminated\n//   calls rather than a flat event list.\n\n/** Defines the free-form properties attached to a call — JSON-shaped values a sink serializes. */\nexport type AnalyticsProperties = Record<string, unknown>;\n\n/** Provides the event name used when `page()` is called without one — sinks route it as a page / screen view. */\nexport const DefaultPageName = 'page_view';\n\n/** Defines a single analytics event handed to every registered sink — the payload of a `track` or `page` call. */\nexport interface AnalyticsEvent {\n  /** The event name (`'checkout_completed'`; a route like `'/pricing'` for a page). */\n  readonly name: string;\n\n  /** The merged properties — super-properties first, call-site values winning. Omitted when empty. */\n  readonly properties?: AnalyticsProperties;\n\n  /** When the call happened (epoch ms), stamped at call time — never at delivery time. */\n  readonly timestamp: number;\n}\n\n/** Defines the payload of an `identify` call — who the user is, plus optional descriptive traits. */\nexport interface AnalyticsIdentity {\n  /** The stable user id the sink keys the profile on. */\n  readonly userId: string;\n\n  /** The user traits (email, plan, locale…) — these describe the PERSON, so super-properties are never merged in. */\n  readonly traits?: AnalyticsProperties;\n\n  /** When the call happened (epoch ms), stamped at call time. */\n  readonly timestamp: number;\n}\n\n/** Defines the kind of call dispatched or buffered — the discriminant of {@link AnalyticsCall}. */\nexport const AnalyticsCallKind = {\n  /** Refers to a `track` call — a named event. */\n  Track: 'track',\n  /** Refers to an `identify` call — binding subsequent events to a user. */\n  Identify: 'identify',\n  /** Refers to a `page` call — a page / screen view. */\n  Page: 'page',\n} as const;\n\nexport type AnalyticsCallKind = (typeof AnalyticsCallKind)[keyof typeof AnalyticsCallKind];\n\n/** Defines one dispatched or buffered call — discriminated so a replayed queue preserves cross-kind ordering. */\nexport type AnalyticsCall =\n  /** Refers to a `track` call carrying its named event. */\n  | { readonly kind: typeof AnalyticsCallKind.Track; readonly event: AnalyticsEvent }\n  /** Refers to an `identify` call carrying its user identity. */\n  | { readonly kind: typeof AnalyticsCallKind.Identify; readonly identity: AnalyticsIdentity }\n  /** Refers to a `page` call carrying its page-view event. */\n  | { readonly kind: typeof AnalyticsCallKind.Page; readonly event: AnalyticsEvent };\n","// The sink seam — one small interface between the client and whatever actually ships the data\n// (GA · PostHog · Segment · a console logger · a test double).\n//\n// Every method is OPTIONAL: a sink that only cares about events implements `track` and nothing else, and\n// the client skips what is absent instead of making each adapter stub three no-ops. Methods may return a\n// promise, but the client never awaits one on the hot path — `track` stays fire-and-forget, so a rejected\n// promise is routed to `onError` exactly like a synchronous throw (see `Analytics.ts`). `flush` is the one\n// call a consumer awaits, for page-unload and test drainage.\n//\n// `AnalyticsFailurePhase` reuses the `AnalyticsCallKind` values and adds `flush`, so a handler can switch\n// over one vocabulary covering every place a third-party sink can fail.\n\nimport { AnalyticsCallKind, type AnalyticsCall, type AnalyticsEvent, type AnalyticsIdentity } from './AnalyticsEvent';\n\n/** Defines a sink the client fans calls out to — implement only the calls the vendor actually supports. */\nexport interface AnalyticsProvider {\n  /** The name used in diagnostics and `onError` reporting. */\n  readonly name?: string;\n\n  /** Ships a tracked event. */\n  readonly track?: (event: AnalyticsEvent) => void | Promise<void>;\n\n  /** Binds subsequent events to a user. */\n  readonly identify?: (identity: AnalyticsIdentity) => void | Promise<void>;\n\n  /** Ships a page / screen view. */\n  readonly page?: (event: AnalyticsEvent) => void | Promise<void>;\n\n  /** Drains whatever the sink batched — the only method `Analytics.flush()` awaits. */\n  readonly flush?: () => void | Promise<void>;\n}\n\n/** Defines where a provider failure came from — the three call kinds plus `flush`. */\nexport const AnalyticsFailurePhase = {\n  /** Refers to a failure raised by `track`. */\n  Track: AnalyticsCallKind.Track,\n  /** Refers to a failure raised by `identify`. */\n  Identify: AnalyticsCallKind.Identify,\n  /** Refers to a failure raised by `page`. */\n  Page: AnalyticsCallKind.Page,\n  /** Refers to a failure raised by `flush`. */\n  Flush: 'flush',\n} as const;\n\nexport type AnalyticsFailurePhase = (typeof AnalyticsFailurePhase)[keyof typeof AnalyticsFailurePhase];\n\n/** Defines the context handed to `onError` when a sink throws or rejects. */\nexport interface AnalyticsErrorContext {\n  /** The provider that failed. */\n  readonly provider: AnalyticsProvider;\n\n  /** The phase the failure came from. */\n  readonly phase: AnalyticsFailurePhase;\n\n  /** The call being dispatched — omitted for a `flush` failure, which belongs to no single call. */\n  readonly call?: AnalyticsCall;\n}\n\n/** Defines the sink-failure handler; analytics never breaks the caller, so a provider throw lands here. */\nexport type AnalyticsErrorHandler = (error: unknown, context: AnalyticsErrorContext) => void;\n","// The client every app talks to. Five decisions worth stating, because none of them is the obvious one:\n//\n// - **Failure isolation.** A sink is third-party code on a non-critical path, so a throwing (or rejecting)\n//   provider must never reach the caller — `track()` is called from render paths and click handlers where\n//   an exception is a real bug. Every dispatch is wrapped and routed to `onError`; one broken provider\n//   never stops the others in the fan-out.\n// - **Buffering before ready.** Vendor scripts load late, so calls made before any provider registers are\n//   queued (drop-oldest at `maxQueueSize`) and replayed on the first `register`. Without this the most\n//   valuable events — the ones at app start — are exactly the ones silently lost.\n// - **The enabled gate is read at CALL time, not at construction.** Consent and Do-Not-Track resolve after\n//   the client exists. Disabled calls do not queue either, and `setEnabled(false)` DROPS what is already\n//   buffered: replaying pre-consent events the moment consent is granted would defeat the gate.\n// - **Super-properties merge into event properties only, never into `identify` traits.** Traits describe\n//   the person, properties describe the moment; merging the two writes request-scoped noise into the\n//   permanent user profile.\n// - **The queue drains to the newly registered provider only.** The buffer is non-empty only while no\n//   provider is registered, so the one that registers is the only possible recipient — a later provider\n//   gets live traffic, never a replay of history it was absent for.\n\nimport {\n  AnalyticsCallKind,\n  DefaultPageName,\n  type AnalyticsCall,\n  type AnalyticsEvent,\n  type AnalyticsIdentity,\n  type AnalyticsProperties,\n} from './AnalyticsEvent';\nimport { AnalyticsFailurePhase, type AnalyticsErrorHandler, type AnalyticsProvider } from './AnalyticsProvider';\n\n/** Narrows an unknown sink return value to a thenable — a vendor adapter may hand back a non-native promise. */\nfunction isPromiseLike(value: unknown): value is PromiseLike<unknown> {\n  return typeof value === 'object' && value !== null && typeof (value as { then?: unknown }).then === 'function';\n}\n\n/** Defines the options for {@link createAnalytics}. */\nexport interface AnalyticsOptions {\n  /** The sinks registered up front; more may join later via `register`. */\n  readonly providers?: ReadonlyArray<AnalyticsProvider>;\n\n  /** Whether calls dispatch at all. Default `true`; flip at runtime with `setEnabled` for consent / Do-Not-Track. */\n  readonly enabled?: boolean;\n\n  /** The initial super-properties merged into every event. */\n  readonly context?: AnalyticsProperties;\n\n  /** The calls buffered while no provider is registered; the oldest drops past it. Default `100`, `0` disables. */\n  readonly maxQueueSize?: number;\n\n  /** Receives every sink failure. Omitted means failures are swallowed — analytics is never worth an app crash. */\n  readonly onError?: AnalyticsErrorHandler;\n\n  /** Supplies the call timestamp (epoch ms) — injectable for deterministic tests. Default `Date.now`. */\n  readonly now?: () => number;\n}\n\n/** Defines the headless analytics client — fans the three canonical calls out to every registered sink. */\nexport interface Analytics {\n  /** Records a named event, with super-properties merged under the given properties. */\n  track(name: string, properties?: AnalyticsProperties): void;\n\n  /** Binds subsequent calls to a user, with optional traits describing them. */\n  identify(userId: string, traits?: AnalyticsProperties): void;\n\n  /** Records a page / screen view; the name defaults to {@link DefaultPageName}. */\n  page(name?: string, properties?: AnalyticsProperties): void;\n\n  /** Merges super-properties into the set attached to every subsequent event. */\n  setContext(context: AnalyticsProperties): void;\n\n  /** Drops every super-property. */\n  clearContext(): void;\n\n  /** Reads a copy of the current super-properties. */\n  getContext(): AnalyticsProperties;\n\n  /** Registers a sink, replaying anything buffered into it; returns an unregister. */\n  register(provider: AnalyticsProvider): () => void;\n\n  /** Turns dispatch on / off at runtime — the consent gate. Turning it off discards anything still buffered. */\n  setEnabled(enabled: boolean): void;\n\n  /** Reports whether dispatch is currently on. */\n  isEnabled(): boolean;\n\n  /** Awaits dispatched calls, then every registered sink's optional `flush` — for page unload and test drainage. */\n  flush(): Promise<void>;\n}\n\n/** Creates an {@link Analytics} client — one per app. Without isolation, use the default {@link analytics}. */\nexport function createAnalytics(options: AnalyticsOptions = {}): Analytics {\n  const { maxQueueSize = 100, onError, now = Date.now } = options;\n  const providers = new Set<AnalyticsProvider>(options.providers ?? []);\n  const queue: AnalyticsCall[] = [];\n  const pendingDeliveries = new Set<Promise<void>>();\n  let context: AnalyticsProperties = { ...options.context };\n  let enabled = options.enabled ?? true;\n\n  /** Routes a sink failure to `onError`; an `onError` that throws is swallowed, having nowhere left to report. */\n  const report = (\n    error: unknown,\n    provider: AnalyticsProvider,\n    phase: AnalyticsFailurePhase,\n    call?: AnalyticsCall,\n  ): void => {\n    if (!onError) return;\n    try {\n      onError(error, { provider, phase, call });\n    } catch {\n      // The handler is the last line of defence; a throw here must not reach the caller either.\n    }\n  };\n\n  /** Invokes one sink method isolated — a throw and a rejected promise both land in `report`. */\n  const invoke = (\n    provider: AnalyticsProvider,\n    phase: AnalyticsFailurePhase,\n    call: AnalyticsCall | undefined,\n    method: () => void | Promise<void>,\n  ): Promise<void> => {\n    try {\n      const result: unknown = method();\n      if (isPromiseLike(result)) {\n        return Promise.resolve(result).then(\n          () => undefined,\n          (error: unknown) => report(error, provider, phase, call),\n        );\n      }\n    } catch (error) {\n      report(error, provider, phase, call);\n    }\n    return Promise.resolve();\n  };\n\n  /** Delivers one call to one sink, picking the matching method — an absent method is simply skipped. */\n  const deliverNow = (provider: AnalyticsProvider, call: AnalyticsCall): Promise<void> => {\n    switch (call.kind) {\n      case AnalyticsCallKind.Track:\n        return invoke(provider, AnalyticsFailurePhase.Track, call, () => provider.track?.(call.event));\n      case AnalyticsCallKind.Identify:\n        return invoke(provider, AnalyticsFailurePhase.Identify, call, () => provider.identify?.(call.identity));\n      case AnalyticsCallKind.Page:\n        return invoke(provider, AnalyticsFailurePhase.Page, call, () => provider.page?.(call.event));\n    }\n  };\n\n  const deliver = (provider: AnalyticsProvider, call: AnalyticsCall): Promise<void> => {\n    const pending = deliverNow(provider, call);\n    pendingDeliveries.add(pending);\n    void pending.finally(() => pendingDeliveries.delete(pending));\n    return pending;\n  };\n\n  /** Fans one call out to every registered sink, or buffers it while none has registered yet. */\n  const dispatch = (call: AnalyticsCall): void => {\n    if (!enabled) return;\n\n    if (providers.size === 0) {\n      if (maxQueueSize <= 0) return;\n      while (queue.length >= maxQueueSize) queue.shift();\n      queue.push(call);\n      return;\n    }\n\n    for (const provider of providers) void deliver(provider, call);\n  };\n\n  /** Builds the event — super-properties spread first so a call-site key of the same name wins. */\n  const toEvent = (name: string, properties?: AnalyticsProperties): AnalyticsEvent => {\n    const merged: AnalyticsProperties = { ...context, ...properties };\n    const timestamp = now();\n    return Object.keys(merged).length > 0 ? { name, properties: merged, timestamp } : { name, timestamp };\n  };\n\n  return {\n    track(name: string, properties?: AnalyticsProperties): void {\n      dispatch({ kind: AnalyticsCallKind.Track, event: toEvent(name, properties) });\n    },\n\n    identify(userId: string, traits?: AnalyticsProperties): void {\n      const timestamp = now();\n      const identity: AnalyticsIdentity = traits ? { userId, traits, timestamp } : { userId, timestamp };\n      dispatch({ kind: AnalyticsCallKind.Identify, identity });\n    },\n\n    page(name?: string, properties?: AnalyticsProperties): void {\n      dispatch({ kind: AnalyticsCallKind.Page, event: toEvent(name ?? DefaultPageName, properties) });\n    },\n\n    setContext(next: AnalyticsProperties): void {\n      context = { ...context, ...next };\n    },\n\n    clearContext(): void {\n      context = {};\n    },\n\n    getContext(): AnalyticsProperties {\n      return { ...context };\n    },\n\n    register(provider: AnalyticsProvider): () => void {\n      providers.add(provider);\n\n      if (queue.length > 0) {\n        for (const call of queue.splice(0, queue.length)) void deliver(provider, call);\n      }\n\n      return () => void providers.delete(provider);\n    },\n\n    setEnabled(next: boolean): void {\n      enabled = next;\n      if (!next) queue.length = 0;\n    },\n\n    isEnabled(): boolean {\n      return enabled;\n    },\n\n    async flush(): Promise<void> {\n      await Promise.all([...pendingDeliveries]);\n      const drains = [...providers].map((provider) =>\n        invoke(provider, AnalyticsFailurePhase.Flush, undefined, () => provider.flush?.()),\n      );\n      await Promise.all(drains);\n    },\n  };\n}\n\n/** The default app-wide client — what the bare {@link track} / {@link identify} / {@link page} helpers bind to. */\nexport const analytics: Analytics = createAnalytics();\n\n/** Records a named event on the default {@link analytics} client — the `track('signup_completed')` entry point. */\nexport function track(name: string, properties?: AnalyticsProperties): void {\n  analytics.track(name, properties);\n}\n\n/** Binds subsequent calls on the default {@link analytics} client to a user. */\nexport function identify(userId: string, traits?: AnalyticsProperties): void {\n  analytics.identify(userId, traits);\n}\n\n/** Records a page / screen view on the default {@link analytics} client. */\nexport function page(name?: string, properties?: AnalyticsProperties): void {\n  analytics.page(name, properties);\n}\n","// The dev sink — the \"is anything even firing?\" provider.\n//\n// Deliberately NOT registered by default: an SDK that logs unasked is noise (GWDNBM), so an app opts in\n// explicitly. `console` is read inside each call rather than captured at factory time, so a test that\n// stubs `console.info` after construction still sees the stub, and importing this file stays free of any\n// environment assumption.\n\nimport type { AnalyticsProvider } from './AnalyticsProvider';\n\n/** Defines the options for {@link consoleAnalyticsProvider}. */\nexport interface ConsoleAnalyticsProviderOptions {\n  /** The tag each line is prefixed with. Default `'[analytics]'`. */\n  readonly prefix?: string;\n}\n\n/** Creates a console-logging sink for development — one line per call, nothing batched, nothing to flush. */\nexport function consoleAnalyticsProvider(options: ConsoleAnalyticsProviderOptions = {}): AnalyticsProvider {\n  const prefix = options.prefix ?? '[analytics]';\n\n  return {\n    name: 'console',\n    track: (event) => console.info(`${prefix} track`, event.name, event.properties ?? {}),\n    identify: (identity) => console.info(`${prefix} identify`, identity.userId, identity.traits ?? {}),\n    page: (event) => console.info(`${prefix} page`, event.name, event.properties ?? {}),\n  };\n}\n","// The test double — a sink that ships nowhere and remembers everything.\n//\n// Assertions want two different views of the same traffic: \"which events fired\" (`events`) and \"what\n// happened, in order, across all three call kinds\" (`calls`). Deriving one from the other at every\n// assertion site is noise, so both are recorded. The arrays surface through getters typed `readonly`, so\n// a test reads the live capture without being able to push into it. `flushCount` is a plain counter\n// rather than a spy, so drainage can be asserted without wiring a mocking library in.\n\nimport { AnalyticsCallKind, type AnalyticsCall, type AnalyticsEvent, type AnalyticsIdentity } from './AnalyticsEvent';\nimport type { AnalyticsProvider } from './AnalyticsProvider';\n\n/** Defines the in-memory sink returned by {@link memoryAnalyticsProvider} — a provider plus the capture it records. */\nexport interface MemoryAnalyticsProvider extends AnalyticsProvider {\n  /** Every call received, in dispatch order across all three kinds. */\n  readonly calls: ReadonlyArray<AnalyticsCall>;\n\n  /** The `track` events received, in order. */\n  readonly events: ReadonlyArray<AnalyticsEvent>;\n\n  /** The `page` events received, in order. */\n  readonly pages: ReadonlyArray<AnalyticsEvent>;\n\n  /** The `identify` payloads received, in order. */\n  readonly identities: ReadonlyArray<AnalyticsIdentity>;\n\n  /** How many times `flush` was invoked. */\n  readonly flushCount: number;\n\n  /** Clears every capture — for a `beforeEach` reset of a shared instance. */\n  reset(): void;\n}\n\n/** Creates an in-memory sink capturing every call — the test double for asserting what an app reports. */\nexport function memoryAnalyticsProvider(): MemoryAnalyticsProvider {\n  const calls: AnalyticsCall[] = [];\n  const events: AnalyticsEvent[] = [];\n  const pages: AnalyticsEvent[] = [];\n  const identities: AnalyticsIdentity[] = [];\n  let flushCount = 0;\n\n  return {\n    name: 'memory',\n\n    get calls() {\n      return calls;\n    },\n    get events() {\n      return events;\n    },\n    get pages() {\n      return pages;\n    },\n    get identities() {\n      return identities;\n    },\n    get flushCount() {\n      return flushCount;\n    },\n\n    track: (event) => {\n      calls.push({ kind: AnalyticsCallKind.Track, event });\n      events.push(event);\n    },\n\n    identify: (identity) => {\n      calls.push({ kind: AnalyticsCallKind.Identify, identity });\n      identities.push(identity);\n    },\n\n    page: (event) => {\n      calls.push({ kind: AnalyticsCallKind.Page, event });\n      pages.push(event);\n    },\n\n    flush: () => {\n      flushCount += 1;\n    },\n\n    reset: () => {\n      calls.length = 0;\n      events.length = 0;\n      pages.length = 0;\n      identities.length = 0;\n      flushCount = 0;\n    },\n  };\n}\n"],"names":[],"mappings":"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"}

package/dist/auth/AuthBridge.d.ts

@@ -13,18 +13,18 @@ export type SessionListener<TUser = unknown> = (session: AuthSession<TUser>) =>
  *   in-flight me-resolve to settle before allowing or redirecting.
  */
 export interface AuthBridge<TUser = unknown> {
-    /** Fires the 401 signal — pass as the api client's `onUnauthorized`; safe to call with no provider mounted (no-op). */
+    /** Fires the 401 signal — pass as the api client's `onUnauthorized`; a no-op with no provider mounted. */
     onUnauthorized(error?: unknown): void;
-    /** Resolves whether the session is authenticated, waiting for an unsettled session to settle — matches the router guard's `isAuthenticated` callback shape. */
+    /** Resolves whether the session is authenticated, waiting for an unsettled session to settle. */
     isAuthenticated(): Promise<boolean>;
     /** Reads the latest published session snapshot (`unknown` until a provider publishes). */
     getSession(): AuthSession<TUser>;
-    /** Publishes a session snapshot — called by `AuthProvider` on every transition; call manually only in custom (non-provider) integrations. */
+    /** Publishes a session snapshot — `AuthProvider` publishes every transition; call it manually only without one. */
     publishSession(session: AuthSession<TUser>): void;
     /** Subscribes to bridged 401s — used by `AuthProvider`; returns an unsubscribe. */
     subscribeUnauthorized(listener: UnauthorizedListener): () => void;
     /** Subscribes to published session snapshots; returns an unsubscribe. */
     subscribeSession(listener: SessionListener<TUser>): () => void;
 }
-/** Creates an {@link AuthBridge} — one per app, module scope, shared by the api client, the router guards, and the `AuthProvider`. */
+/** Creates an {@link AuthBridge} — one per app, at module scope, shared by the api client, guards, and provider. */
 export declare function createAuthBridge<TUser = unknown>(): AuthBridge<TUser>;