@hanzo/observe

中文文档
0.1.17发布于 2026/10/31MITTypeScriptESM + CJS近 30 天下载 1.4万

Hanzo Observe — default-on interaction capture for React. Watches every click/input/nav/visibility across the tree, annotates each with a semantic hierarchy (component path / role / data-testid / aria) auto-derived from the DOM, and emits it through @hanz

原始使用文档
文档目录10 节
  1. Most apps should not mount this directly.
  2. Events
  3. Engaged time
  4. The semantic hierarchy
  5. One root, one engine
  6. Privacy
  7. Session playback
  8. Framework-agnostic core
  9. Note on build-time component names
  10. License

@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 entry point (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 with properties like:

{
  "$el": "Dashboard/UserCard/button[save]",   // the significant-node trail
  "$role": "button",
  "$testid": "save",
  "$component": "SaveButton",
  "$path": ["Dashboard", "UserCard", "button[save]"],
  "$href": "/pricing",                        // the link it follows
  "$id": "save",                              // the target's own id
  "$section": "plans"                         // the section of the page it sits in
}

Events

EventWhenProperties beyond the annotation
$clickevery clickposition (below), when a pointer pressed it
$rageclickthe third press inside 1 s and 30 px of the last; once a burstposition
$inputa field's keystrokes, debounced per field (400 ms)$value (redacted)
$changea field settled$value (redacted)
$submita form submitted
$viewa [data-hz-view] element once half of it is in view, or what is in view of it covers half the viewport (so a section taller than two viewports is still seen); once per element; elements mounted after start() included. A section already wholly above the viewport when the engine starts, on a page freshly opened at its top (no fragment, not a reload or back/forward), was scrolled past before anything watched it: it is reported then with passed: true and no ratioratio, or passed
$scrollthe document scrolled to 25, 50, 75 and 100 % of its height, each once a page viewdepth, $page_width, $page_height, $viewport_width, $viewport_height
$pageviewan SPA navigation, when nav is onpath
$pageleavea page view's engaged time, in segments: when the page is hidden, unloaded, routed away from, or the engine stopsbelow

Every event carries the annotation ($el, $role, $path, and $testid, $name, $component, $kind when the target has them) and, when it has them, where it happened:

  • $href — the closest a[href], the target or an ancestor: a pathname on this origin, origin + pathname on another, the bare scheme (mailto:, tel:) for anything that is not http(s). Never a query or a fragment.
  • $id — the target's own id.
  • $section — the closest section[id] or [data-hz-view]: its data-hz-view value, else its id.

Each is at most 256 characters, and dropped rather than clipped past that.

Position, on $click and $rageclick, is what a heat map is drawn from:

KeyValue
$x, $ythe pointer in page coordinates (viewport coordinates for a fixed or sticky target)
$target_fixedwhether the target stays put when the page scrolls
$el_x, $el_ythe pointer inside the target's box, from its top left
$viewport_width, $viewport_heightthe window it was measured in
$page_width, $page_heightthe document's scrollWidth / scrollHeight

All rounded to the pixel. A click no pointer pressed — a keyboard activation, el.click(), a label forwarding to its field (detail === 0) — carries none, and never counts toward a rage click.

Scroll depth is measured once a frame from a passive listener that only reads, and asks for no frames once a page view has reached every milestone. A new address starts the milestones again, with nav on or off; the top of a page is not a scroll, so a router putting the next page there reports nothing. Only an engine on document measures it.

Engaged time

$pageleave says how long a page view held the visitor. Active time is time the document was visible, the window had focus, and the visitor did something (pointer, key, wheel, touch, scroll) in the last 60 s (IDLE_MS), so a tab left open overnight does not read as eight hours on one page.

A view reports in segments: when the page is hidden (the last moment a phone reliably runs script), when it is unloaded, when the router leaves it, and when the engine stops. A view that comes back reports again with only what it added, and a segment that added nothing is not sent. The time on a page view is the sum of $active_ms over its $view_id; nothing is counted twice. A segment is filed under the page it measured (the event's url/path), not the address the router has already moved to. The bindings send a hidden or unloaded page's segment at once by beacon.

KeyValue
$view_id, $seqthe page view, and the segment's place in it (0 first)
$reasonhidden, pagehide, nav or stop
$active_msactive milliseconds in this segment
$elapsed_mswall time since the view began (the first view: since navigation start)
$sections{ name: ms }: active time each watched section (viewSelector, named by data-hz-view or id) was in view in this segment, by the $view rule
$scroll_maxthe furthest the view was scrolled, in px from the top (a running maximum)
$depth_maxhow much of the page that showed, in percent
$page_*, $viewport_*the sizes it was measured against
$ttfb_ms, $fcp_ms, $lcp_ms, $cls, $inp_msthe page load's timings and Core Web Vitals, on the hard-loaded view only, as they stand; a browser that does not time one omits it

Only an engine on document measures it; engage: false turns it off.

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:

  1. data-hz-name / data-component — written by a person, about this node.
  2. data-observe — stamped at build time by @hanzo/annotate.
  3. data-slot — the part name a design system puts on the element it renders (button, select-trigger, dialog-content). @hanzo/ui stamps 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.
  4. The nearest named React fiber owner — richer (SaveButton, not button), but development-only: a production build strips _debugOwner and minifies the name. It ranks below data-slot deliberately — 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/$change event carries the field's kind and value length, never the typed text.
  • Sensitive fields are always redacted (password / email / card / cvv / token / ssn / …) — not even a length.
  • data-hz-private (or data-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).

版本与发布记录

@hanzo/observe 共发布 14 个版本,首次发布于 2026/07/23;过去 12 个月发布了 14 个版本。

版本发布日期距今
0.1.17latest2026/10/3117 天前
0.1.162026/10/3017 天前
0.1.152026/10/3017 天前
0.1.142026/10/3018 天前
0.1.132026/10/3018 天前
0.1.122026/10/2622 天前

关于 @hanzo/observe 的常见问题

@hanzo/observe 是什么?

Hanzo Observe — default-on interaction capture for React. Watches every click/input/nav/visibility across the tree, annotates each with a semantic hierarchy (component path / role / data-testid / aria) auto-derived from the DOM, and emits it through @hanz

如何安装 @hanzo/observe?

在项目目录运行 npm install @hanzo/observe,或使用 pnpm add / yarn add / bun add。

@hanzo/observe 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@hanzo/observe 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@hanzo/observe 可以商用吗?

@hanzo/observe 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@hanzo/observe 的下载量有多少?

根据 npm 官方下载统计,@hanzo/observe 在 2026/10/17 – 2026/11/15 这 30 天内被下载 13,682 次,日均约 456 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@hanzo/observe 还在维护吗?

最新版本 0.1.17 发布于 2026/10/31(17 天前);至今共发布 14 个版本,其中过去 12 个月发布了 14 个;首次发布于 2026/07/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。