The value is a pk- prefixed PUBLISHABLE key (the Stripe vocabulary, and what the build-time gate already tests for). EVENT_INGEST_KEY hid that. One substitution covers all three spellings, since the framework prefixes wrap the same token: EVENT_INGEST_KEY -> PUBLISHABLE_KEY, NEXT_PUBLIC_* and VITE_* follow. KMS already carries deploy/PUBLISHABLE_KEY (env prod) with the same value, written and read back first, so no build can reach a name that does not exist yet. Co-authored-by: Hanzo Dev <[email protected]>
31 KiB
@hanzo/ui — LLM context
What this is. The React component library for AI applications: 161+
components, 24+ blocks, two themes, and a single typed import surface, all on ONE
substrate (@hanzo/gui) so the same import runs on web, native and desktop.
Published as @hanzo/ui (v8) on npm. Docs at https://ui.hanzo.ai. Dev port: 3003.
Canonical role. This is the canonical impl repo for Hanzo's web UI kit —
frontend components, not an SDK. It sits alongside the two SDK lines (full cloud
SDK generated from OpenAPI in hanzo-<lang>/sdk + wrapper in hanzoai/<lang>-sdk;
AI/agents lib hanzo in hanzoai/python-sdk flagship, @hanzo/ai in hanzo-js/ai).
@hanzo/event (telemetry, POST /v1/event) lives here in pkgs/event. DRY: one
impl, one place — link out, never duplicate.
Brand rules (hard).
- Never call Hanzo an "LLM gateway" or position it against LiteLLM — it is a full AI SDK / AI cloud, not a proxy. Purge that framing on sight.
- Paths are
/v1/…only — never an/api/prefix. - Zen models are our own family — never name upstream models.
- Voice: "Hanzo — the Open AI Cloud." Developer-first, crisp, no emoji-spam.
Install / run.
pnpm add @hanzo/ui # consume
# dev:
pnpm install && pnpm build:registry && pnpm dev # registry MUST build before app
Key entry points. pkg/ui/ (core lib + v8 subpaths: /product /data /canvas
/dashboard /usage /gitops) · app/registry/{default,new-york}/
(component SOURCE OF TRUTH) · pkgs/* (auto-published @hanzo/* packages) ·
packages/shadcn/ (CLI) · app/content/docs/ (MDX docs). Publish = bump a
package version + merge to main (.github/workflows/publish.yml).
Spec / more context. Canonical SDK + docs model: ~/work/hanzo/SDK-ARCHITECTURE.md.
Detailed engineering notes (build order, import surface, telemetry, upstream sync,
gotchas) follow below.
v8 — the canonical @hanzo/ui (pkg/ui)
@hanzo/ui@8 (pkg/ui) is THE Hanzo component library, and there is ONE
substrate: every component renders through @hanzo/gui (Tamagui) primitives on
the @hanzo/tokens scale, so one import works on web, native (expo) and desktop
(Tauri). The Radix + Tailwind surface it used to ship alongside is gone — it
lives on as its own package, @hanzo/shadcn, and @hanzo/ui no longer depends
on it, on any @radix-ui/* package, on cva, cmdk or sonner.
@hanzo/ui-shadcn (pkgs/ui, v5.x) is the legacy standalone package —
superseded, being retired.
Layout
pkg/ui/src/
core/ design core: cn.ts (clsx+tailwind-merge),
tokens.ts (re-export of @hanzo/tokens), fonts.ts (Geist vars)
root.tsx <Hanzo> — the root. Carries the gui config AND the stylesheet.
gallery.tsx EVERY component, once, in every variant. The one list.
theme.css SELF-CONTAINED token CSS vars + Geist Sans/Mono — the identity
backends/gui/ THE component surface on @hanzo/gui. index.ts is its manifest.
product/ the product/app layer (charts, PageHeader, ComboBox, …)
models/ the unified ModelSelector + catalog helpers
primitives/ GENERATED per-member entrypoints (scripts/gen-primitives.mjs)
index.ts root barrel = the component surface + cn
Out of the box — the package carries its own config and its own CSS
import { Hanzo, Button } from '@hanzo/ui'
<Hanzo><Button>Ship</Button></Hanzo>
That is the entire setup. No gui.config.ts, no CSS import, no generator script.
Three things used to be each app's job:
-
The stylesheet. gui compiles a style prop to an atomic class the first time something RENDERS it, so the sheet does not exist until a render has happened — which is why every app ran a
gen-gui-css.mjsof its own. hanzo.app never did: it shipped 103_bg-classes and 26_dsp-classes against a stylesheet containing ZERO of either, every gui-styled element unstyled in production, green build throughout. The render happens at OUR publish time now (scripts/gen-css.mjsrenderssrc/gallery.tsxin both themes and writesdist/styles.css— 381 KB, 35 KB gzipped, 340 atomic selectors), and<Hanzo>imports it. Styles gui generates at RUNTIME for props we could not know at publish time still reach the document throughinsertStyleRules; the shipped sheet is what makes the FIRST paint and every SSR/static render correct. -
The config.
<Hanzo>passesconfigfromgui-config.tstoGuiProvider— as a VALUE, never a bareimport './gui-config'. Vite 8 (rolldown) ignores package.jsonsideEffectsARRAYS outright: with any array the registration is dropped and the first render dies on "Missing hanzogui config"; onlysideEffects: truekeeps it, and that costs +63% bundle (404 KB → 661 KB measured). Correctness does not live in bundler metadata. -
The theme. gui throws
Missing theme.for any component with no root theme context, so a root is structurally required — there is no version of this with no root at all. Forgetting<Hanzo>is therefore a hard crash on first paint, never a silently unstyled page.
theme.css is dark-first at :root (it used to claim dark-first while shipping
LIGHT at :root, so an app that mounted the dark default and read --background
got white). .light retunes, and both answer to gui's own .t_light/.t_dark
that <Hanzo> stamps on the body — one theme, named the same by the CSS custom
properties and the component tokens.
Three tests, one list of components
src/gallery.tsx is the specification of "what this package has to style", and
all three layers render THAT — a second copy of the list is how a component gets
styled by one and missed by another.
| Layer | Command | What it catches |
|---|---|---|
src/styles.test.tsx |
pnpm test:unit |
every atomic class the gallery renders vs every class dist/styles.css defines a rule for. Not "the intersection is large" — TOTAL. Catches a stale sheet. |
src/backends/gui/render.test.tsx |
pnpm test:unit |
the surface mounts under the real provider; a component that throws on first paint fails. |
test/consumer.spec.ts |
pnpm test:consumer |
packs the tarball, installs it into a temp app OUTSIDE the repo (never a workspace link — that hides files/exports/workspace:* defects), builds, serves, and asserts COMPUTED styles + screenshots at 390 and 1280 in both themes. |
The consumer spec also fails on a solid-white border (the @hanzo/design
border-card: var(--white…) defect — borders are low-alpha hairlines) and on any
element that has a text child and a zero-height box.
House rules for a component
- Style through gui props and theme tokens (
$background,$color12,$borderColor) — never a utility class string, never a hard-coded font. - Touch targets meet the 44px floor via
hitSlop, never via padding. - Behaviour (focus, portalling, keyboard, a11y) comes from the matching
@hanzogui/*primitive; nothing reimplements it. - Free-form text children go through
ink();data-slotmarkers throughslot(). One helper each, one place. - Module scope stays side-effect free —
forwardRef/createContextcalls carry/* @__PURE__ */and nothing assignsdisplayName, so importing one symbol never drags a neighbour in. A one-symbol import bundles ~4.7KB against ~29KB for the whole barrel. - Utility classes carry
hz-. This sheet used to claim.row,.skeleton,.fade,.mono,.dragand.tnumat the document level, in a package an app imports once at its root; an app with its own.rowgot no warning, it got whichever rule the cascade preferred. The unprefixed selectors survive as aliases on the same rules for one minor version and are REMOVED IN 8.1.0. Nothing here emits them —styles.test.tsxscans everyclassName=literal insrc/and fails on an unprefixed one.glass/elevation-Nare the one family still bare: they are an API VALUE (glass(3).className), not a typed literal, so they move on their own change. - A prop must actually arrive. gui is not the DOM, and two measured cases prove
it in both directions:
nameis gui's OWN prop (it names a styled component and a theme) and is consumed before it reaches the element, so anameon a field type-checks and renders nothing; and gui dropssecureTextEntryon web, which is why masking needs BOTH spellings viamasked()inbackends/gui/mask.tsand why<Input type="password">rendered passwords in PLAIN TEXT until 8.0.61 (the wrapper destructuredtypeout and never forwarded it, next to an eye offering to reveal what was already visible). Render it and read the markup before you believe a prop works.
Subpaths
| Subpath | What |
|---|---|
@hanzo/ui |
the component API: Button, Badge, Card*, Checkbox, Dialog*, DropdownMenu*, Input, Toaster, Avatar*, Tabs*, Select*, Tooltip*, Popover*, Command*, Collapsible*, Resizable*, ScrollArea, Slider, Switch, Progress, Separator, Label, Textarea, AspectRatio — + cn (the product layer is kept off root, at /product) |
@hanzo/ui/components |
alias of the root surface, for hosts that shim the package through a declare module |
@hanzo/ui/product |
the product/app layer: charts, metrics, PageHeader, StatusTag, EmptyState, ComboBox, SlideOver, Toast, Reorder, Field |
@hanzo/ui/models |
ModelSelector + fetchModelCatalog + catalog helpers |
@hanzo/ui/core · /tokens |
cn, Geist font vars, the @hanzo/tokens color/theme/radii/spacing scale |
@hanzo/ui/theme.css |
the design tokens alone (custom properties + Geist + touch/elevation) |
@hanzo/ui/styles.css |
the COMPLETE sheet — tokens + motion + the generated gui atomic/theme CSS. <Hanzo> imports it, so an app never has to |
@hanzo/ui/gallery |
every component, once — what the generator, the unit test and the consumer test all render |
@hanzo/ui/primitives/<Member> |
per-member entrypoints (for hosts that modularize @hanzo/ui imports) |
@hanzo/ui/data |
@hanzo/data: RecordsView, DataTable, typed field editors |
@hanzo/ui/{canvas,dashboard,usage,gitops} |
the optional-peer kits (each re-exports its home package) |
@hanzo/ui/product/* · /primitives/* |
deep imports — one module without its barrel |
@hanzo/ui/product/pure |
the product layer's RULES with none of the layer (below) |
@hanzo/ui/product/theme-toggle-next |
the @hanzogui/next-theme binding, off the barrel on purpose (below) |
@hanzo/ui/css |
substitute() — resolve a var() chain, for tests jsdom cannot answer (below) |
Everything ships COMPILED from dist — every exports target is a real file in
the tarball, including theme.css and all 90 primitives/* entrypoints.
src/dist.test.ts asserts that against the built output, wildcards included; a
subpath pointing at a file tsc never emitted is invisible from source.
Three doors that exist because the barrel is not one
@hanzo/ui/product mounts the whole gui runtime to give you one component, and
for three kinds of caller that is not a cost — it is a wall.
@hanzo/ui/product/pure — the rules, without the layer. pages(),
masked(), displayName(), tone(), orgScope, filterOptions,
resolveBrand and the wordmark geometry. Every module it re-exports imports
NOTHING (src/dist.test.ts asserts the closure is empty) and is on
postbuild.mjs's DATA list, so none is stamped 'use client' — a stamped
module is a client REFERENCE on React's server layer, and calling pages()
through one in a server component throws instead of paging. It loads under a
bare require() with no transform and no DOM; the test proves it in a child
node process rather than under vitest, which has vite's transform already
installed and would prove nothing.
The components import these same modules, so there is one definition and not a testable copy of a shipped one.
@hanzo/ui/product/theme-toggle-next — Next, quarantined.
@hanzogui/next-theme's provider imports next/script, so the product barrel's
one export { ThemeToggleNext } line put Next in the graph of every Vite,
Express and Tauri host — the hosts this layer promises to run on. A barrel
re-export is a static edge no bundler can split. It is off the barrel; <ThemeToggle />
with no props still reaches it by dynamic import and degrades when next-theme is
absent, and dist.test.ts asserts BOTH — no static edge, and the dynamic one
still there, because a test that only asserted the absence would pass on a
deleted feature. next is now an OPTIONAL peer here: next-theme requires it and
nothing in this package admitted that.
@hanzo/ui/css — substitute(value, vars?). jsdom does not resolve
var(); it hands a test the text verbatim. The theme rungs are
var(--border, rgb(255 255 255 / .10)) on purpose (follow the live cascade
where design's sheet is mounted, keep the audited literal where it is not), so
every consumer trying to assert a border's contrast compared a colour to a
function call. With no vars map the answer is exact rather than approximate:
jsdom mounts no design sheet, so the fallback IS what a browser computes. It is
NOT part of @hanzo/ui/core — that subpath is ESM-only because @hanzo/design
publishes no require condition, and a jest consumer is the caller that needs
this. Importing nothing is what lets it ship both formats.
One DropdownMenu
There is one DropdownMenu, with one API. It is the compound surface (Trigger,
Content, Item, CheckboxItem, RadioItem, Label, Separator, Shortcut, Group,
Portal, Sub*, RadioGroup) AND it accepts the declarative trigger + items
spec, which it renders through those very same parts. @hanzo/ui and
@hanzo/ui/product export the same component; there is no second shape.
modularizeImports support
scripts/gen-primitives.mjs reads the gui backend barrel and emits one
src/primitives/<Member>.tsx per exported value (re-export from the backend).
This makes @hanzo/ui/primitives/Button etc. resolve, so a host whose
next.config rewrites @hanzo/ui → @hanzo/ui/primitives/{{member}} works
unchanged. Re-run pnpm gen:primitives after changing the surface.
Build — plain tsc, one file in, one file out
There is no bundler. pnpm build is two tsc passes, scripts/postbuild.mjs,
then scripts/gen-css.mjs (which renders the gallery through vite's SSR pipeline
to harvest config.getCSS() into dist/styles.css — the slow step, ~2 min):
| Pass | Config | Emits |
|---|---|---|
| ESM + types | tsconfig.build.json |
dist/**/*.js, .d.ts, .js.map, .d.ts.map |
| CJS | tsconfig.cjs.json (--noCheck) |
dist-cjs/**/*.js, folded into dist/**/*.cjs |
postbuild.mjs does the only two things tsc will not: it resolves every
relative specifier to a fully-specified path (./button → ./button.js,
./x → ./x/index.js; .cjs on the CJS half) so Node ESM and strict bundlers
resolve, and it prepends 'use client' to every emitted module — the whole
library is client-side @hanzo/gui UI and Next's flight-client loader wants the
directive first. It is prepended without a newline so source-map lines hold.
@hanzo/data runs this same script, with its package root and its own data
modules as arguments (node ../ui/scripts/postbuild.mjs . theme,table/logic,…).
It has the same two formats and the same two problems, and a second copy of the
file would be a second place to get the barrel rule wrong. That package used to
point its exports at src/index.ts and ship raw TSX — every consumer had to
transpile it, and require('@hanzo/data') could not load at all, which is one of
the two edges that broke require('@hanzo/ui'). It emits dist/ now, both
formats, from 1.2.2.
The output is UNBUNDLED and mirrors src/ one-for-one, so a consumer importing
one symbol pulls one module. A bundler here would be actively harmful: tsup's
code splitting emitted 11 shared chunk-*.js, and importing Button alone
dragged in chunk-RCMDRI6V.js (48K of source). Measured with esbuild, import { Button } from '@hanzo/ui' costs 4717 bytes bundled from tsup output vs 2021
from tsc output. Dropping rollup-plugin-dts (tsup's dts worker) is also
what makes the package build on TypeScript 7, which it cannot do otherwise.
Everything under src/ is emitted, so every exports subpath resolves by
construction — no hand-maintained entry list to drift.
NOTE: pkg/ui (singular) sits OUTSIDE the pkgs/* pnpm workspace, installs
standalone, and publishes via the maintainer flow, not publish.yml. Because the
optional-peer kits (canvas/dashboard/gitops/usage) are not on the public
registry, a standalone install must skip auto-installing peers. .npmrc and
pnpm-lock.yaml are gitignored here, so create the .npmrc once:
cd pkg/ui
printf 'auto-install-peers=false\nstrict-peer-dependencies=false\n' > .npmrc
pnpm install --ignore-workspace # component-surface deps (radix, cmdk, sonner, …) + @hanzo/tokens
pnpm gen:primitives # refresh the per-member entrypoints
pnpm typecheck:ui # scoped typecheck of the component surface (green)
@hanzo/tokens (pkgs/tokens) must be built first (pnpm --filter @hanzo/tokens build)
so the file: link resolves. The scoped typecheck:ui excludes the optional-peer
subpaths, whose homes aren't installed standalone.
The kits = canvas, wallet, network, billing, dashboard, usage, gitops, data.
Add one by mirroring src/gitops.ts (a one-line export *) + a ./name export
- an optional peer/devDep.
pkg/*is a pnpm workspace member (forworkspace:*dev links), butpkg/uipublishes via the maintainer flow, notpublish.yml(which auto-publishes onlypkgs/*on a version bump — see PUBLISH_GUIDE.md). The shared shell lives here too:AppHeader+BrandMark(@hanzo/logo) +OrgSwitcher+orgScope(the console org-scope contract, hoisted per #36). Lux surfaces use@luxfi/web3for wallet/login;@hanzo/ui/wallet+/networkare the Hanzo-branded equivalents.
Repository Structure
ui/
app/ Hanzo documentation site (Next.js 15.3.1, React 19)
registry/ Component registry (SOURCE OF TRUTH)
default/ui/ 150+ components
default/example/ Usage demos
default/blocks/ 24+ full-page sections
new-york/ Alternative theme
content/docs/ MDX documentation
scripts/ Build scripts
apps/
v4/ Upstream shadcn v4 docs/registry app (port 4000)
packages/
shadcn/ shadcn CLI v4.1.0 (font system, chart colors, scaffold)
tests/ Integration tests for shadcn CLI
og/ OG image generation (Hanzo-only)
pkg/
ui/ Core library (npm)
react/ React primitives
brand/ Branding system
commerce/ E-commerce components
checkout/ Checkout flow
shop/ Shop components
agent-ui/ AI agent UI components
tokens/ Design tokens
skills/
shadcn/ AI skill definitions for shadcn CLI
templates/ Project templates (next, vite, astro, react-router, start + monorepo variants)
template/next/ Hanzo-customized Next.js template
Critical: Build Order
Registry MUST build before app. The registry generates JSON that the CLI reads.
pnpm build:registry # MUST run first
pnpm build # Then build app
Commands
pnpm dev # Dev server (:3003)
pnpm build:registry # Build component registry
pnpm build # Build app
pnpm lint # Lint all workspaces
pnpm typecheck # Type checking
pnpm test # Unit tests
pnpm test:e2e # Playwright E2E
How this ships
One way, and it runs on our own stack:
push -> github.com/hanzoai/ui (a mirror)
.github/workflows/sync.yml carries refs onward
-> git.hanzo.ai/hanzoai/ui CANONICAL
.hanzo/workflows/ci.yml lint, typecheck, build, test
.hanzo/workflows/registries.yml the v4 registry check
.hanzo/workflows/publish.yml publishes every pkgs/* package
.hanzo/workflows/deploy.yml builds ghcr.io/hanzoai/ui
-> hanzoai/universe crs/ui.yaml names the tag that is live
-> hanzoai/operator reconciles the App
-> hanzoai/static behind hanzoai/ingress serves ui.hanzo.ai
git.hanzo.ai is canonical; GitHub is a mirror. .github/workflows/ holds
exactly one file, sync.yml, and its only job is getting refs to the forge. Every
build, check, publish and deploy is a workflow under .hanzo/workflows/, which the
forge reads. .hanzo/workflows uses GitHub Actions syntax, so a workflow moves
between the two by changing directory and nothing else.
No Vercel. ci.yml used to end in a deploy-preview job that ran vercel deploy
on every PR; previews come from our own stack or not at all, so that job is gone.
Its status job never depended on it.
Publishing
One way: bump a package's version in its package.json and merge to main.
.hanzo/workflows/publish.yml detects the changed @hanzo/* package and publishes
it to npm (needs NPM_TOKEN as a forge secret). No changesets, no version-PR bot
— the semver bump is the trigger.
It is the SOLE publisher of every non-private @hanzo/* in pkgs/*, and it
mirrors the same tarball to api.hanzo.ai/v1/packages/hanzo/npm when
HANZO_REGISTRY_TOKEN is present. That mirror is best-effort by construction: no
token means a notice, not a failure, and npmjs stays authoritative either way.
Deploying the site
app/ is a Next.js static export (output: "export", trailingSlash: true);
pnpm build there writes app/out, which Dockerfile copies into
ghcr.io/hanzoai/static. ui.hanzo.ai has been served that way since 2026-07-25 —
no Cloudflare, no GitHub Pages.
What was missing until now is the build. crs/ui.yaml is live and promoted, but no
workflow ever produced the image it pins: every tag up to v5.7.6 was pushed by
hand. .hanzo/workflows/deploy.yml is that step. It publishes
ghcr.io/hanzoai/ui:<sha> and stops there — a build never deploys itself. A human
sets spec.image.tag in hanzoai/universe
infra/k8s/operator/crs/ui.yaml, which is the one live thing that says which build
serves.
Coverage lives in ci.yml's test job, which runs pnpm test:coverage so the
lcov it uploads to Codecov actually exists. A separate coverage.yml used to run
the same suite a second time for the same upload plus a PR comment through the
GitHub API; one workflow does it now.
registries.yml keeps the apps/v4 registry honest: reserved namespaces are
rejected and pnpm --filter=v4 validate:registries must pass. Its other job
labelled and commented on pull requests with the gh CLI against the GitHub API,
which does not exist on the forge, so that job did not come along.
Telemetry — @hanzo/event is the ONE client (pkgs/event)
@hanzo/event is the single canonical telemetry client for every Hanzo surface.
ONE API surface over TWO planes — the client never sends the org; the server
resolves the tenant.
- Event stream — pageview/event/identify/group (and an error breadcrumb),
batched to
POST {host}/v1/eventwith{ batch: [Event, …] }-> { accepted, dropped }. Tenant from the session or a publishablepk_key. - Error plane — every captured exception is ALSO framed as a real Sentry
envelope and POSTed to
POST {dsn.origin}/v1/sentry/{projectId}/envelope/?sentry_key=…. This is the ONLY thing that reaches the Sentry error dashboard.
There is NO server-side fan-out from
/v1/eventinto Sentry. Versions ≤ 0.3.1 claimed there was ("lensed server-side into … error tracking"). There is not: cloud's handler folds the exception intoproperties.$exception, writes one row to the event warehouse (readable viaGET /v1/errors), and stops. Because every property believed that claim, the whole fleet reported zero errors to Sentry until 0.3.2 added the envelope. Do not re-collapse these planes.
Configure the error plane with dsn (or NEXT_PUBLIC_HANZO_EVENT_DSN), minted
per property via POST /v1/sentry/projects. The DSN key is publishable and
write-only — safe in a bundle, same trust class as pk_. No DSN => the error
plane is inert (fail-safe: nothing sent, nothing thrown, event stream
unaffected); assert client.errorPlaneEnabled if you need to know.
There is NO third plane. Web analytics used to be one — analytics.hanzo.ai/hz.js
posting a bare JSON array of {site, ts, type, …} to a second collector behind an
identical path spelling — and 0.3.7 deleted both. hz.js now lives in this package
as the script-tag DISTRIBUTION of this client: same WireEvent, same
{ batch: [ … ] }, same POST {host}/v1/event. Point everything at the API host.
It could not authenticate until 0.3.12: it sent no Authorization and no
?ingest_key=, so a keyed static surface's writes were unattributed, the door
refused them (401), and nothing in the page said so. data-ingest-key="pk-…".
Entries: . (framework-agnostic: createAnalytics, EVENTS, GOALS,
attribution + DSN/scrub helpers) and ./react (AnalyticsProvider,
useAnalytics, usePageview, ErrorBoundary). Auto error capture
(window.onerror / unhandledrejection / React boundary) makes it the drop-in
error-tracking replacement. Secrets and PII are scrubbed client-side before an
error leaves the device. SSR-safe, fail-soft, beacon-on-unload.
Build is a tsup dual bundle: CJS → .cjs, ESM → .mjs (required under
"type": "module" — a CJS .js is parsed as ESM and crashes require() with
"exports is not defined"). Each exports condition carries its own types.
Interaction analytics — <Hanzo analytics> is the one wiring
An app instruments nothing. <Hanzo analytics> (pkg/ui/src/root.tsx) is the
whole setup, and every click / change / submit / route change inside the tree
reaches POST /v1/event named by the component it happened on:
<Hanzo analytics={{ product: 'console', ingestKey: process.env.NEXT_PUBLIC_PUBLISHABLE_KEY }}>
Four packages, one of each concern, no duplication:
| Concern | Where | Note |
|---|---|---|
| client + wire | @hanzo/event (pkgs/event) |
one endpoint, one key |
| capture engine | @hanzo/observe (pkgs/observe) |
delegated listeners, semantic annotation, redaction |
| provider + consent | @hanzogui/telemetry (~/work/hanzo/gui) |
<TelemetryProvider/>; owns DNT/GPC + stored choice |
| curated events | @hanzo/ui/product instrument.ts |
emit({component, action}) — what autocapture cannot know |
analytics is a prop, not a default. Mounting a component library must not
start a network conversation the app did not ask for. Off, no provider renders.
Component names are real in production. Every primitive already carries a
data-slot (via slot()); componentName() in pkgs/observe/src/annotate.ts
reads it, ranked ABOVE the React fiber owner deliberately — the fiber name is
dev-only, so grouping on it silently empties the dashboard at deploy. Labels keep
the qualifier: card/button[Save].
It cannot double-count. The engine installs delegated listeners on a root,
so two engines on one root report everything twice — which is what an app got by
mounting a library provider AND <ObserveProvider/>, both correct instructions.
Since observe 0.1.7 the first engine claims its root under a Symbol.for
registry (page-wide, so duplicate copies of the package still see each other) and
any later one stays inert (engine.capturing === false). Verified in Chromium,
not only in jsdom.
Consent is decided in ONE layer. The engine takes enabled as a value; the
provider resolves policy (GPC, DNT, stored hz_consent, build kill switch) and
passes the answer down. Do not add a second, partial copy to the engine — the two
then disagree about an explicit opt-in.
One way — supersessions (no divergent telemetry client)
| Package | Status | Note |
|---|---|---|
@hanzo/event |
canonical | pkgs/event, posts /v1/event only |
@hanzo/capture (npm) |
deprecated → @hanzo/event |
the old name of this package; @hanzo/event is a superset |
pkgs/capture (@hanzo/[email protected] dup) |
deleted | stale in-repo duplicate, removed |
hanzoai/analytics packages/event (@hanzo/[email protected]) |
deleted | An unpublished FORK of this package in another repo. It was the only copy that could actually reach Sentry, while the published one here could not — the fleet's error telemetry died in that gap. Its envelope + scrub implementation was merged here in 0.3.2. Never fork this package again; it publishes from pkgs/event only. |
Three-Layer Architecture
- Components (
registry/{style}/ui/) — single primitives (Button, Card, Dialog). CLI-installable. - Examples (
registry/{style}/example/) — usage demos for docs via<ComponentPreview />. - Blocks (
registry/{style}/blocks/) — full-page sections (Dashboard, Login). NOT CLI-installable, docs only.
Import Path Transformation
Registry files use @/registry/default/ui/button. After CLI install, rewritten to @/components/ui/button.
Package Exports
import { Button, Card } from '@hanzo/ui'
import { Button } from '@hanzo/ui/components'
import * as Dialog from '@hanzo/ui/primitives/dialog'
import { cn } from '@hanzo/ui/lib/utils'
Adding a Component
- Create in BOTH themes:
app/registry/{default,new-york}/ui/my-component.tsx - Create example:
app/registry/default/example/my-component-demo.tsx - Create docs:
app/content/docs/components/my-component.mdx - Update nav:
app/config/docs.ts - Build:
pnpm build:registry
Tech Stack
React 19, Next.js 15.3+, Tailwind CSS 4 (OKLCH colors), Radix UI, Turborepo + pnpm, Fumadocs (MDX), class-variance-authority.
Upstream Sync
Remote shadcn points to a local clone of shadcn-ui/ui.
hanzoai/ui is NOT a GitHub fork — no shared object store, so large merges can fail on push.
Strategy: file-level checkout from shadcn/main for specific directories (not git merge).
- Take theirs: packages/shadcn/, packages/tests/, apps/, templates/, scripts/, skills/
- Keep ours: app/, pkg/, demo/, docs/, template/next/, pnpm-workspace.yaml, package.json
- Regenerate: pnpm-lock.yaml after sync
Key Features
- Page Builder (
/builder): drag-drop block assembly with @dnd-kit, export to TSX - White-Label: Zoo/Lux forks via
brands/{BRAND}.brand.ts - External Registries: 35+ sources in
app/registries.json, install vianpx @hanzo/ui add @aceternity/spotlight
Gotchas
- Registry index is
Index[style][name], NOTIndex[name]— caused silent block render failures - Shiki
getHighlighterincompatible with static export — replaced with basic pre/code - Some blocks (login-01, login-02, sidebar-02) have Server Component issues with event handlers
@hanzo/authv2.6.0 uses a pluggable provider registry:registerAuthProvider('firebase', FirebaseAuthService)
Rules
- Always build registry before app
- Keep default and new-york themes in sync
- Blocks are docs only, not CLI-installable
- Use pnpm, not npm/yarn
- Never commit symlinked files (AGENTS.md, CLAUDE.md, etc.)
- Documentation goes in
app/content/docs/, not random root MD files