Interaction analytics was app work. Every surface wired its own client and instrumented its own call sites, so a click on the same Button was named three ways or not at all. `<Hanzo analytics>` is now the whole wiring: one prop on the root an app already mounts, and every click, change, submit and route change inside the tree reaches the ONE front door named by the component it happened on — `card/button[Save]` — with input values withheld. A prop, not a default. Mounting a component library must never start a network conversation the app did not ask for; off, no provider renders and no listener is installed. On, it renders @hanzogui/telemetry's provider, which is where consent already lives (GPC, DNT, the stored choice a banner writes). No second client, no second stream, no second consent policy. Component names are real in production. Every primitive already carries a `data-slot` through one helper, so `componentName()` reads it — ranked ABOVE the React fiber owner deliberately, because the fiber name is development-only and a dashboard grouped on it empties silently at deploy. A named node keeps its qualifier now (`button[Save]`, not `button`): a component name says what KIND of thing it is, and a library renders hundreds of each. It cannot double-count. The engine installs DELEGATED listeners on a root, so two engines on one root report everything twice — which is exactly what an app got by following two true sets of instructions at once, since a library provider starts an engine and observe's own README told apps to mount another. The first engine to start now claims its root and any later one stays inert. The claim lives on the page under a `Symbol.for` registry rather than in module scope: two copies of the package in one bundle have two module scopes and would not see each other's claim, which is precisely when a duplicate is most likely. Driving it in Chromium found what jsdom could not: the input debounce was ONE slot shared across elements, so moving to the next field cleared the previous field's pending timer and a filled form reported only the last field touched. Keyed by field now. hz.js could not authenticate at all. Through 0.3.11 it sent no `Authorization` and no `?ingest_key=`, so every keyed static surface wrote unattributed, the door refused it (401 ingest_key_required), and nothing in the page said so — the tag measured fine in the browser and the surface was simply missing from the warehouse. `data-ingest-key="pk-…"` now rides the header on fetch and the query on a headerless unload beacon, the same pair the npm client uses. It also honors Global Privacy Control and the stored `hz_consent` choice, not DNT alone, and its stamped `libraryVersion` is pinned to the package version by a test — it had drifted three patches, dating every static-site row to the wrong release. The hz.js suite ran none of its tests: Node >= 21 ships a `navigator` whose descriptor has no setter, so the harness's assignment threw. The one shipped file with no bundler and no import-time typing had no executed coverage. It runs again, and now asserts what reaches the wire — transport, URL, headers — not only the batch. @hanzo/event 0.3.12, @hanzo/observe 0.1.7, @hanzo/ui 8.0.58. Co-authored-by: Hanzo Dev <[email protected]>
@hanzo/observe
Default-on interaction capture for React, on top of @hanzo/event.
Mount one provider and every click, input, navigation, and (opt-in) visibility is
captured — each one annotated with a semantic hierarchy auto-derived from the
tree (component path / role / data-testid / accessible name) — and emitted
through @hanzo/event to the ONE front door (POST /v1/event). Privacy-gated
(input redaction) and fail-soft by default. A live event-stream hook powers
session playback.
Most apps should not mount this directly.
This is the ENGINE. The one wiring an app mounts is its provider —
<Hanzo analytics>from@hanzo/ui, or<TelemetryProvider/>from@hanzogui/telemetry— and both start this engine for you, with consent resolved and the client already built. Mounting<ObserveProvider/>as well is not an upgrade; it is a second engine, and until 0.1.7 it doubled every event (see One root, one engine).Reach for the provider below when you are building one of those wirings, or hosting the engine somewhere neither reaches.
'use client'
import { AnalyticsProvider } from '@hanzo/event/react'
import { ObserveProvider } from '@hanzo/observe/react'
export function Root({ children }) {
return (
<AnalyticsProvider config={{ product: 'console' }}>
<ObserveProvider>{children}</ObserveProvider>
</AnalyticsProvider>
)
}
Every interaction now arrives on the pipe as a reserved
autocapture event ($click, $input, $change, $submit, $pageview, $view)
with properties like:
{
"$el": "Dashboard/UserCard/button[save]", // the significant-node trail
"$role": "button",
"$testid": "save",
"$component": "SaveButton",
"$path": ["Dashboard", "UserCard", "button[save]"]
}
The semantic hierarchy
For the element an interaction lands on, the engine walks the DOM ancestry and
describes each step as a SemanticNode — tag, ARIA role (explicit or
implicit), testid, accessible name, and component. The result is a small
JSON-LD document (@context, @type: "Interaction", path, target, label)
carried with the event. So a click is not "a click at (x, y)" but "a click on the
Save button, inside UserCard, inside the Dashboard navigation."
Component names resolve most-authoritative-first, and the order is chosen so a name does not change when you ship:
data-hz-name/data-component— written by a person, about this node.data-observe— stamped at build time by@hanzo/annotate.data-slot— the part name a design system puts on the element it renders (button,select-trigger,dialog-content).@hanzo/uistamps one on every primitive through a single helper, and shadcn does the same, so a whole component library becomes attributable with no per-call-site code.- The nearest named React fiber owner — richer (
SaveButton, notbutton), but development-only: a production build strips_debugOwnerand minifies the name. It ranks belowdata-slotdeliberately — a name that evaporates at deploy time silently empties the dashboard grouped on it.
Whichever wins, the node keeps its qualifier: card/button[Save], not card/ button. A component name says what KIND of thing it is, and a library renders
hundreds of each.
One root, one engine
The engine installs delegated listeners on a root (document, normally), so
two running engines on one root capture every interaction twice — and a
doubled click is indistinguishable downstream from an engaged visitor. That is
not hypothetical: an app got one by following two true sets of instructions at
once, because a library provider starts an engine and this README used to tell
apps to mount another.
Since 0.1.7 the first engine to start() claims its root and holds it until it
stops; a later engine on the same root stays inert, and says so
(engine.capturing === false). The claim lives on the page, under a
Symbol.for registry rather than in module scope — two copies of this package
in one bundle have two module scopes and would not see each other's claim at
all, which is exactly the case where a duplicate is most likely. Distinct roots
(a scoped Element, plus document) coexist fine.
Privacy
Privacy-first by default:
- Input values are withheld. An
$input/$changeevent carries the field'skindand valuelength, never the typed text. - Sensitive fields are always redacted (password / email / card / cvv / token / ssn / …) — not even a length.
data-hz-private(ordata-observe="off"/data-private) on an element or any ancestor excludes the whole subtree from capture.
To capture non-sensitive text values (e.g. a search box), pass
redaction={{ maskInput: false }} — sensitive fields stay redacted regardless.
Consent is not decided here. The engine takes enabled as a value; whether
a visitor may be observed at all (Global Privacy Control, Do Not Track, a stored
banner choice, a build-time kill switch) is one policy in one place — the
provider layer — and it passes the answer down. Braiding a second, partial copy
of that policy into the engine is how the two end up disagreeing about an
explicit opt-in.
Session playback
import { useEventStream } from '@hanzo/observe/react'
function Timeline() {
const { events, clear } = useEventStream({ limit: 200 })
return <ol>{events.map((e, i) => <li key={i}>{e.name} → {e.semantic.label}</li>)}</ol>
}
useEventStream subscribes to the same stream the engine feeds; it is a rolling,
in-memory window for building a live session-playback UI.
Framework-agnostic core
The . entry has no React or transport dependency — it is the engine, the
annotator, the redactor, and the stream:
import { observe } from '@hanzo/observe'
const engine = observe((i) => analytics.capture(i.name, { el: i.semantic.label }))
engine.stream.subscribe(render) // live playback
engine.stop()
This is what the Svelte (@hanzo/observe-svelte) and native
(@hanzo/observe-native) adaptors build on.
Note on build-time component names
Reliable component names in production want a build step that stamps data-hz-name
onto rendered elements (the runtime already reads it). That is a JSX/AST codemod —
separate tooling from this runtime SDK — and is a documented follow-on, not part of
this package.
License
MIT © Hanzo AI — see LICENSE.md. HIP-0137 (hanzoai/hips).