@ops-ai/react-router-toggly 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+
+## [1.1.0] - 2026-09-18
+
+### Added
+- Default browser telemetry with independent collector URL, configurable flush interval and explicit opt-out.
+- Public usage, view, app-level counter, latest-value gauge and awaitable flush methods on the provider context.
+
+### Fixed
+- Synchronize changed provider groups/claims before passive refresh consumers without replacing the telemetry owner or overriding explicit identity context on equivalent props.
+- Snapshot only selected definitions and applicable local gates for each check while preserving immutable callback capture and short-circuit counts.
+- Preserve immutable selected definitions through entity/local callbacks and keep only the newest overlapping refresh and asynchronous hook completion.
+- Count effective local/entity-gated browser checks once per evaluated leaf, preserving short circuit and negation without duplicate component evaluation.
+- Isolate telemetry and hydrated snapshots when app/environment changes; release browser resources on real unmount while preserving StrictMode replay.
+- Capture original flag and attribution snapshots before reentrant callbacks; isolate failed/new contexts and late responses.
+- Prevent delayed refresh/identity completion from updating a disposed provider and discard pending telemetry on incompatible transport replacement.
+
+### Changed
+- Browser definitions and telemetry support host-minted instance tokens with precedence over client targeting, plus client identity fallback. Trusted server telemetry and loader/action behavior remain unchanged.
+
 ## 1.0.1
 
 2026-09-17

package/README.md

@@ -7,6 +7,56 @@ in-source (not published as a separate package).
 > Migrating from `@ops-ai/remix-toggly-*`? Those packages are deprecated. Install
 > `@ops-ai/react-router-toggly` and import from `/client` and `/server`.
 
+
+## Browser telemetry
+
+`TogglyProvider` and `RouterTogglyProvider` each own one compact browser reporter.
+With an app key, telemetry is enabled by default. Access explicit events through
+`useToggly()` or `useTogglyContext()`:
+
+```tsx
+const toggly = useToggly()
+// Call these from application actions or an explicit view event.
+toggly.recordUsage('Checkout')
+toggly.recordView('Checkout', 'control')
+toggly.incrementCounter('orders', 2)
+toggly.setGauge('cartSize', 3)
+await toggly.flushTelemetry()
+```
+
+Usage and view variants default to `enabled`; labels contain 1–64 ASCII letters,
+digits, underscores or hyphens. Counters sum nonnegative integer deltas, and gauges
+retain the latest finite nonnegative value. A single value cannot exceed 1,000,000.
+Metrics are app-level and contain no feature attribution.
+
+Automatic checks record each evaluated feature after local and entity gates,
+before negation. Short-circuited keys do not count. Direct cached reads, hooks and
+components count actual evaluations; hydration and refresh snapshots alone do
+not. Rendering never implicitly records usage or views. Boolean A/B helpers use
+enabled/disabled check labels; explicit events may specify a variant label.
+
+Provider `config` accepts `enableTelemetry` (default true), `metricsBaseUrl`
+(default `https://metrics.toggly.io`), and `telemetryFlushIntervalMs` (30000–60000 ms,
+default 45000). Set `enableTelemetry: false` to disable browser telemetry.
+`enableUsageTracking: false` disables checks/usage/views, and `enableMetrics: false`
+disables business metrics. Invalid intervals use the default. Invalid collector
+URLs disable telemetry without changing feature results; use absolute HTTP(S)
+URLs without credentials, query or fragment.
+
+SSR/build, keyless and opted-out providers create no frontend reporter resources.
+Payloads contain app/environment, optional `i` (host-minted instance token) or `u` (client identity), feature/variant counts and numeric metrics. Claims, groups, entity data and timestamps are excluded. Requests omit
+credentials, use native gzip when available, and have bounded buffers, timeout
+and retries. Page hiding and unmount trigger a bounded best-effort flush; await
+`flushTelemetry()` to wait for the current best-effort attempt before navigation; it does not guarantee server acknowledgement.
+
+Set `config.instanceId` to a token minted by your trusted host. It takes precedence over client identity/groups/claims in browser definition requests and telemetry. Rotate it with `await context.identify(identity, {instanceId})`; `identify(identity)` clears the token and uses client targeting. `reset()` clears identity and token. Groups/claims can be updated through the existing identify context. Changed provider groups/claims commit to the same owner, clear prior results to defaults, and become active on the next existing refresh trigger; they do not start an extra request. Omitted groups/claims clear those fields. Equivalent props preserve context explicitly set by `identify`. Failed context refreshes retain the new targeting scope with configured defaults; old results and pending responses cannot cross that boundary. Context changes preserve already queued events under their original attribution.
+
+Each mounted provider is independent. App/environment replacement releases the
+old reporter without relabeling its queue (incompatible collector/transport or opt-out replacement discards pending old data), and ignores loader snapshots explicitly
+labeled for another owner. StrictMode effect replay preserves the committed owner;
+real unmount releases it and remount creates a fresh one. Browser telemetry does
+not change trusted server loader/action metrics or their existing APIs.
+
 ## Install
 
 ```bash