Registry

The Circle Health Registry serves installable components for Circle Health products through the shadcn CLI. Consumers copy components into their own codebase, own the generated files, and can edit them locally.

The Registry has four layers. Components are small primitives. Blocks combine them into product modules. Utilities provide behavior without a UI workflow. Themes provide the tokens that style all three.

Where to go

Page	Use it for
Install	Configure a consumer and install its first item.
Concepts	Registry ownership, namespaces, dependencies, and generated output.
Components	Actions, form controls, navigation, layout, and content primitives.
Blocks	Flows, commerce, booking, media, reporting, and patient-results patterns.
Utilities	Analytics helpers and browser tools with no UI workflow attached.
Themes	The token sets available to Circle Health surfaces.
Sample Data	Synthetic PDFs and brands for development and demos.
Skills	Copy-review and link-check skills.

Source of truth

Authored React source lives under packages/ui and registry/. The registry build writes shadcn-compatible JSON to apps/docs/public. Do not hand-edit generated registry JSON.

The documentation and public payloads ship from the same host: registry.circle.health.

Install

The Circle Health Registry distributes source through the shadcn CLI. The CLI downloads source into the consumer; it does not add a runtime package.

1. Start with a shadcn project

The consumer needs a valid components.json. If it does not have one yet, run:

pnpm dlx shadcn@latest init

2. Add the registries

Add the Circle Health namespaces to components.json:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "registries": {
    "@circle-ui": "https://registry.circle.health/circle-ui/{name}.json",
    "@blocks": "https://registry.circle.health/blocks/{name}.json",
    "@utilities": "https://registry.circle.health/utilities/{name}.json",
    "@i18n": "https://registry.circle.health/i18n/{name}.json",
    "@skills": "https://registry.circle.health/skills/{name}.json"
  }
}

@circle-ui contains primitives. @blocks contains product modules. @utilities contains behavior with no UI workflow attached. @i18n contains optional locale dictionaries referenced by those modules. @skills contains agent workflows installed under .agents/skills.

3. Install the base style

Install the shared tokens and defaults once per consumer:

pnpm dlx shadcn@latest add @circle-ui/circle

4. Add what the product needs

Install items by namespace and name:

pnpm dlx shadcn@latest add @circle-ui/button
pnpm dlx shadcn@latest add @blocks/booking-timeline
pnpm dlx shadcn@latest add @utilities/analytics

The CLI resolves registry dependencies and writes the files into the consumer. Review those files like any other source change.

Direct URL installation

When a consumer cannot edit components.json, install from the public JSON URL:

pnpm dlx shadcn@latest add https://registry.circle.health/circle-ui/button.json

Next

Use Components for primitives, Blocks for assembled product patterns, Utilities for behavior-only helpers, and Concepts for the ownership and dependency model.

Concepts

Installed source

The Circle Health Registry distributes source rather than a runtime component package. Installing an item copies files into the consumer. The consumer then owns those files and can change them without waiting for a central package release.

Reinstalling an item may replace local changes. Inspect the diff before accepting an update.

Components

Components are low-level UI with no product workflow attached. Each registry entry maps to one source module and uses the @circle-ui namespace.

Blocks

Blocks are product modules assembled from components. A block may pull in private hooks, types, or serialization helpers, but those implementation files are not separate catalog choices.

Install one focused block for one product capability. Use an umbrella entry only when the capability is intentionally shipped as a coordinated family.

Utilities

Utilities provide behavior without a visual primitive or product workflow. They use the @utilities namespace so consumers can distinguish instrumentation and browser helpers from UI blocks.

Localized copy

Optional locale dictionaries use the @i18n namespace. They stay separate from UI source so consumers own translation loading and locale boundaries. The owning block documents the relevant dictionary.

Themes

Themes are CSS-variable sets. Components and blocks refer to those variables rather than hard-coded product colors, so a consumer can change a surface without rewriting component logic.

Dependencies

Each registry item declares two dependency kinds:

Kind	Resolution
Registry dependency	The shadcn CLI installs another Registry item.
npm dependency	The consumer’s package manager installs a third-party package.

Registry dependencies use their full namespace in generated JSON. The docs show both dependency kinds on every reference page.

Authoring and generated output

Authoring source lives in packages/ui, packages/styles, and registry. Configuration lives in config/registry. pnpm registry:build produces the public JSON under apps/docs/public.

Treat generated JSON as build output. Change the authoring source or registry configuration, rebuild, and verify the generated diff.

Technical setup

This repository is a pnpm workspace managed by Turborepo. It builds two surfaces from the same source: the Nextra documentation site and the shadcn-compatible JSON consumed by Circle Health applications.

Manifest-backed stack

One workspace builds the catalog and the files it documents.

Package versions below come directly from the workspace manifests. The lockfile fixes the resolved dependency graph.

pnpm9.12.2Turborepo2.8.14TypeScript5.9.3Next.js16.2.7React19.2.7Nextra4.6.1Tailwind CSS4.2.1shadcn3.8.5

System boundary

The Registry distributes source, not a runtime UI package. @circle/ui is the private authoring package inside this workspace. Consumers use the shadcn CLI, receive files in their own source tree, and own those files from then on.

Build pipeline

1. Author

The durable sources are:

• packages/ui/src for components, blocks, utilities, types, and localized copy
• packages/styles/src/globals.css for base CSS variables and typography
• skills for installable agent workflows
• config/registry/items.json for item metadata and target overrides
• config/registry/styles.json for theme variants
• config/registry/site.json for namespaces, aliases, and the public host
• config/docs/registry.json for catalog grouping and navigation

Every root component must have one explicit registry item. An entry exported from packages/ui/src/index.ts can also receive a live documentation preview.

2. Compile

pnpm registry:sync runs scripts/registry/build.mjs. The script:

1. reads authored source and registry configuration;
2. maps each source module to one registry item;
3. rewrites local imports to namespaced registry paths;
4. derives npm and registry dependencies from imports;
5. writes transformed source to registry/berlin; and
6. writes manifests and catalog metadata to config/registry/generated and registry.json.

Explicit dependencies and file targets in items.json supplement values that cannot be derived from imports.

3. Publish

pnpm registry:build performs the registry sync, then runs shadcn build once per namespace. The resulting JSON is written below apps/docs/public:

/circle-ui/{name}.json
/blocks/{name}.json
/utilities/{name}.json
/i18n/{name}.json
/skills/{name}.json

The documentation application and these static payloads are served from registry.circle.health.

4. Generate documentation

pnpm docs:sync combines generated item metadata with docs configuration. It produces catalog pages, sidebar maps, skill pages, the CircleOS PII-mask page, and the rendered changelog.

Handwritten pages such as this one explain durable concepts. Item reference pages are generated so their install commands and dependencies stay aligned with the public payload. An item listed in its namespace’s authoredItems configuration keeps its handwritten page while still using live RegistryItem sections for installation and dependency data.

Workspace map

Documentation runtime

The docs app uses the Next.js App Router with Nextra. The catch-all route at apps/docs/app/[[...mdxPath]]/page.tsx imports pages from apps/docs/content. apps/docs/content/_meta.tsx owns the top-level navigation.

The docs package runs registry and docs generation in both predev and prebuild. A local or production Next.js build therefore uses current generated artifacts instead of whatever happened to be on disk beforehand.

The root layout marks the site noindex, nofollow, and noarchive. That is a crawler policy, not access control.

Generated boundaries

Change the source on the left, then regenerate the output on the right.

Do not hand-edit generated output. The relevant build removes and recreates managed directories.

Local workflow

Start the docs application:

pnpm install
pnpm dev:docs

After changing registry source or configuration:

pnpm registry:build
pnpm docs:sync
pnpm typecheck
pnpm build

pnpm build is the production gate. Turborepo type-checks the private UI package, rebuilds registry and docs artifacts through the docs package hooks, and runs the Next.js production build.

Failure modes

• An unconfigured root component stops the registry build.
• A catalogued item missing from config/docs/registry.json stops docs sync.
• An authoredItems entry without its handwritten page stops docs sync.
• Hand edits below generated paths are overwritten on the next build.
• Reinstalling a registry item in a consumer may replace its local changes; inspect the consumer diff before accepting an update.
• The generated JSON is committed. Unexpected payload changes should be investigated before merge, not hidden from the diff.

Themes

Themes are CSS-variable sets consumed by components and blocks. Install the base style first, then choose the token set that matches the product surface.

The catalog below is generated from config/registry/styles.json.

Skills

Installable AI skills for common Circle Health review and QA tasks.

• Copy Review — Review customer-facing copy for healing promises, language issues, and formal Sie phrasing.
• Link Check — Audit links for failures, redirects, insecure URLs, and mismatched destinations.

Copy Review

Review customer-facing copy for healing promises, language issues, and formal Sie phrasing.

Install

pnpm dlx shadcn@latest add @skills/copy-review

Skill

---
name: copy-review
description: Review customer-facing Circle Health copy for healing promises, German or English language issues, and formal Sie phrasing. Use before publishing UI text, websites, emails, notifications, translations, or other user-facing copy.
---
 
# Copy review
 
Review the supplied copy and:
 
- Flag cures, guaranteed outcomes, or specific medical results. Suggest cautious alternatives such as "kann unterstützen", "zielt darauf ab", or "may help support".
- Correct spelling, grammar, and awkward phrasing in German or English.
- Replace formal German "Sie", "Ihnen", and "Ihr" with warm, informal "Du", "dir", and "dein" forms.
 
For every issue, quote the original text, name the category, and provide a replacement. If no issues remain, confirm that the copy is ready.

Link Check

Audit links for failures, redirects, insecure URLs, and mismatched destinations.

Install

pnpm dlx shadcn@latest add @skills/link-check

Skill

---
name: link-check
description: Audit links in documentation, websites, or other content for failures, redirects, insecure HTTP URLs, and mismatched destinations. Use when reviewing content with Markdown, HTML, raw, or relative links.
---
 
# Link check
 
Extract every link from the supplied content, including Markdown links, HTML links, raw URLs, and relative paths.
 
Test each destination when network access is available. Report the link text, URL, status, final destination after redirects, and whether the destination matches the surrounding context. Classify each result as OK, Redirect, Broken, Insecure, or Not tested.
 
Finish with totals and concrete recommendations for links that should be updated or removed.

Changelog

Release history for The Circle Health Registry.

v2.0.0 — Canonical Registry

Added

• Nextra documentation with nested pages for components, blocks, utilities, skills, themes, sample data, concepts, and installation guidance.
• Copy Review and Link Check skills, published through the registry with copyable agent installation guidance.
• Brand reference pages for Decades, Praxis Kessler, and Soma Studio.
• Direct download and copyable URL references for synthetic lab reports and intake forms.

Changed

• Registry entries now map one-to-one to source modules.
• Supporting hooks, types, serializers, and copy dictionaries remain installable dependencies but are no longer separate catalog pages.
• Rating is a component and Support is a block; the mixed general module has been removed.
• Patient-results metric cards use the neutral reporting modules directly.
• Analytics helpers now live in the utilities namespace.
• Documentation navigation now follows the registry’s component and block categories.
• Registry documentation and metadata consistently use the Circle Health Registry name.
• Flow previews now fill their available surface.

Removed

• Duplicate install aliases. Install the owning module instead: form, address, booking-timeline, commerce, flow, media, or patient-results-report.
• The redundant Spacer component.
• The legacy unnamespaced /r registry endpoint. Use /circle-ui, /blocks, or /i18n.
• The unused Storybook workspace and superseded standalone prompts document.

v1.0.0 — Initial Release

The first public release of The Circle Health Registry at registry.circle.health.

Added

Pages

• Components — Catalog browser for core UI primitives, grouped by function
• Blocks — Pre-assembled flows and domain patterns built from core UI
• I18n — Shared locale dictionaries and copy packs
• Utilities — Utility reference page
• Themes — Theme browser with live previews
• Showcase — Featured compositions and usage examples
• Get Started — Onboarding guides for Components and Blocks

CMS (Registry Content System)

• Registry Item Catalog (items.json) — 98 indexed component entries with titles, descriptions, namespace assignments, and file mappings
• Site Configuration (site.json) — Namespace definitions, public paths, source policy, and base style/utils metadata
• Styles Catalog (styles.json) — Theme definitions with token overrides
• Registry JSON API (/r/[name]) — Serves cached registry payloads per item with cache headers for CLI consumption
• Build Pipeline — Automated scripts generating shadcn-compatible registry payloads from source

Core UI Components (30 primitives)

Blocks (62 compositions)

I18n Copy Packs

• Cookie Consent Copy — Shared locale dictionary for the cookie consent block

Themes

• Berlin — Default Circle Health product palette with warm sand surfaces and blue actions
• Linen — Brighter editorial variant with softer neutrals and a greener accent
• Graphite — Cooler, higher-contrast palette for dense internal tooling surfaces

Infrastructure

• shadcn CLI compatibility — All items installable via npx shadcn@latest add
• Namespace-based organization — circle-ui, blocks, i18n
• Berlin registry style — App-first Circle Health tokens and defaults
• Registry dependency graph — Items declare internal dependencies for automatic resolution
• Source policy — Primary (circle-app) and secondary (legacy-design-system) source references
• Storybook 10 integration — Isolated component previews

AGENTS.MD

General guidance for agents working across Circle Health repositories. More specific instructions closer to the code being changed take precedence.

Sources of truth

• Read the relevant code, configuration, and project documentation before editing. Do not rely on remembered framework behaviour when the installed version can answer the question.
• For Next.js work, read the relevant guide in node_modules/next/dist/docs/ before writing code. The installed version may contain breaking API, convention, or file-structure changes. Heed deprecation notices.
• When a task references Figma or another design source, inspect that source and match its copy, layout, styles, and assets. Do not invent missing design decisions.
• Preserve explicit product constraints such as privacy, indexing, security, and public visibility unless the task changes them.

Change discipline

• Keep changes small, local, and directly related to the feature or bug.
• Preserve unrelated work in a dirty worktree.
• Reuse existing primitives, tokens, and patterns before introducing a new abstraction.
• Verify changes with the narrowest useful tests, type checks, lint checks, or build steps for the affected area.

Structure and naming

• Prefer cute, neat names and logical domain boundaries. Use commerce/readiness/medusa.ts, not commerce-readiness.medusa.ts.
• Keep one clear responsibility per module and place it beside the domain that owns it.
• Prefer functional factories and functions over classes when they make dependency injection and testing simpler.
• Quote route-segment paths in shell commands so characters such as [] and () are not expanded by the shell.

Types and boundaries

• Do not introduce any, as any, @ts-ignore, or broad double casts when a practical typed alternative exists.
• Prefer generated types, schema-inferred types, unknown with narrowing, or a small explicit interface.
• If an escape hatch is unavoidable, keep it at the untyped boundary and explain why it is needed.
• Keep input validation and authorization checks close to the API, data, or service boundary they protect.

Interface work

• In localized surfaces, keep user-facing copy in the localization system. Preserve German as a first-class locale, update both English and German messages, and prefer message interpolation over string concatenation.
• Use the existing design system and component primitives instead of ad-hoc colours, typography, spacing, or controls.
• For technologies, AI models, and integrations, use the service’s domain.com/favicon.ico when a recognizable brand mark is needed and no canonical local asset exists.

Copy AGENTS.md

# Agent guidance
 
Use these rules throughout this repository. More specific instructions closer to
the code being changed take precedence.
 
## Sources of truth
 
- Read the relevant code, configuration, and project documentation before
  editing. Do not rely on remembered framework behaviour when the installed
  version can answer the question.
- For Next.js work, read the relevant guide in
  `node_modules/next/dist/docs/` before writing code. The installed version may
  contain breaking API, convention, or file-structure changes. Heed
  deprecation notices.
- When a task references Figma or another design source, inspect that source and
  match its copy, layout, styles, and assets. Do not invent missing design
  decisions.
- Preserve explicit product constraints such as privacy, indexing, security,
  and public visibility unless the task changes them.
 
## Change discipline
 
- Keep changes small, local, and directly related to the feature or bug.
- Preserve unrelated work in a dirty worktree.
- Reuse existing primitives, tokens, and patterns before introducing a new
  abstraction.
- Verify changes with the narrowest useful tests, type checks, lint checks, or
  build steps for the affected area.
 
## Structure and naming
 
- Prefer cute, neat names and logical domain boundaries. Use
  `commerce/readiness/medusa.ts`, not `commerce-readiness.medusa.ts`.
- Keep one clear responsibility per module and place it beside the domain that
  owns it.
- Prefer functional factories and functions over classes when they make
  dependency injection and testing simpler.
- Quote route-segment paths in shell commands so characters such as `[]` and
  `()` are not expanded by the shell.
 
## Types and boundaries
 
- Do not introduce `any`, `as any`, `@ts-ignore`, or broad double casts when a
  practical typed alternative exists.
- Prefer generated types, schema-inferred types, `unknown` with narrowing, or a
  small explicit interface.
- If an escape hatch is unavoidable, keep it at the untyped boundary and
  explain why it is needed.
- Keep input validation and authorization checks close to the API, data, or
  service boundary they protect.
 
## Interface work
 
- In localized surfaces, keep user-facing copy in the localization system.
  Preserve German as a first-class locale, update both English and German
  messages, and prefer message interpolation over string concatenation.
- Use the existing design system and component primitives instead of ad-hoc
  colours, typography, spacing, or controls.
- For technologies, AI models, and integrations, use the service's
  `domain.com/favicon.ico` when a recognizable brand mark is needed and no
  canonical local asset exists.

Components

Low-level UI with no product workflow attached.

• Actions & Status — Trigger actions and communicate state.
• Forms — Collect, validate, and submit user input.
• Navigation & Overlays — Move between views and reveal transient interfaces.
• Layout & Content — Structure pages and present content.

Alert

Status callout for inline feedback.

Install

pnpm dlx shadcn@latest add @circle-ui/alert

Use

import { AlertCard } from "@circle/ui";

Badge

Compact status or category label.

Install

pnpm dlx shadcn@latest add @circle-ui/badge

Use

import { Badge } from "@circle/ui";

Button

Primary, secondary, and text actions.

Install

pnpm dlx shadcn@latest add @circle-ui/button

Use

import { Button } from "@circle/ui";

Dependencies

Kind	Packages
npm	@radix-ui/react-slot, class-variance-authority

Progress Bar

Determinate progress track and indicator.

Install

pnpm dlx shadcn@latest add @circle-ui/progress-bar

Use

import { ProgressBar } from "@circle/ui";

Rating

Rating value, stars, and review count.

Install

pnpm dlx shadcn@latest add @circle-ui/rating

Use

import { Rating } from "@circle/ui";

Spinner

Indeterminate loading indicator.

Install

pnpm dlx shadcn@latest add @circle-ui/spinner

Use

import { Spinner } from "@circle/ui";

Tag

Removable or static metadata label.

Install

pnpm dlx shadcn@latest add @circle-ui/tag

Use

import { Tag } from "@circle/ui";

Checkbox

Controlled or uncontrolled checkbox.

Install

pnpm dlx shadcn@latest add @circle-ui/checkbox

Use

import { Checkbox } from "@circle/ui";

Dependencies

Kind	Packages
npm	@radix-ui/react-checkbox

Date Picker

Single-date calendar picker.

Install

pnpm dlx shadcn@latest add @circle-ui/date-picker

Use

import { DatePicker } from "@circle/ui";

Dependencies

Kind	Packages
npm	react-day-picker

Form Fields

Form state, text fields, text areas, selects, and phone input.

Install

pnpm dlx shadcn@latest add @circle-ui/form

Use

import { Form } from "@circle/ui";

Dependencies

Kind	Packages
npm	react-international-phone

Switch

Binary setting control.

Install

pnpm dlx shadcn@latest add @circle-ui/switch

Use

import { Switch } from "@circle/ui";

Dependencies

Kind	Packages
npm	@radix-ui/react-switch

Back Button

Back control with label, icon, and chevron variants.

Install

pnpm dlx shadcn@latest add @circle-ui/back-button

Use

import { BackButton } from "@circle/ui";

Link

Inline link with Circle Health typography and focus treatment.

Install

pnpm dlx shadcn@latest add @circle-ui/link

Use

import { TextLink } from "@circle/ui";

Overlay Action

Accessible action placed over media or another visual surface.

Install

pnpm dlx shadcn@latest add @circle-ui/overlay-action

Use

import { OverlayAction } from "@circle/ui";

Dependencies

Kind	Packages
npm	class-variance-authority

Sheet

Modal sheet with trigger, overlay, content, and close controls.

Install

pnpm dlx shadcn@latest add @circle-ui/sheet

Use

import { Sheet } from "@circle/ui";

Dependencies

Kind	Packages
Registry	@circle-ui/overlay-action
npm	class-variance-authority, vaul

Tabs

Tabbed navigation and content panels.

Install

pnpm dlx shadcn@latest add @circle-ui/tabs

Use

import { TabRoot } from "@circle/ui";

Dependencies

Kind	Packages
npm	@radix-ui/react-tabs

Tooltip

Contextual help with default or custom triggers.

Install

pnpm dlx shadcn@latest add @circle-ui/tooltip

Use

import { Tooltip, TooltipWrapper } from "@circle/ui";

<Tooltip content="Reviewed before sharing." side="right" />

<TooltipWrapper content="More context" side="top">
  <button type="button">Details</button>
</TooltipWrapper>

Dependencies

Kind	Packages
npm	@radix-ui/react-tooltip

Card

Surface, header, content, footer, and action slots.

Install

pnpm dlx shadcn@latest add @circle-ui/card

Use

import { Card } from "@circle/ui";

Container

Centered, width-constrained page container.

Install

pnpm dlx shadcn@latest add @circle-ui/container

Use

import { Container } from "@circle/ui";

Empty

Empty-state layouts with optional title and description.

Install

pnpm dlx shadcn@latest add @circle-ui/empty

Use

import { Empty } from "@circle/ui";

Text

Product typography with semantic element options.

Install

pnpm dlx shadcn@latest add @circle-ui/text

Use

import { Text } from "@circle/ui";

Text With Icon

Inline label paired with an icon.

Install

pnpm dlx shadcn@latest add @circle-ui/text-with-icon

Use

import { TextWithIcon } from "@circle/ui";

Timeline

Vertical sequence of connected steps.

Install

pnpm dlx shadcn@latest add @circle-ui/timeline

Use

import { Timeline } from "@circle/ui";

Blocks

Product modules composed from components.

• Flows — Frame multi-step product journeys and their controls.
• Commerce — Product, pricing, quantity, cart, and discount patterns.
• Booking Timeline — Ordered booking steps with progress, notes, directions, and tasks.
• Media & Support — Present media, locations, addresses, and support.
• Cookie Consent — Collect, store, revisit, and broadcast category consent preferences.
• Reporting — Compose metrics and result visualizations.
• Patient Results — Edit, render, export, and bundle patient result reports.

Flow

Shell, header, progress, choices, and actions for step-based journeys.

Install

pnpm dlx shadcn@latest add @blocks/flow

Use

import { FlowWrapper } from "@circle/ui";

Floating Flow Actions

Pinned submit action with loading and disabled states.

Install

pnpm dlx shadcn@latest add @blocks/floating-flow-actions

Use

import { FloatingFlowActions } from "@circle/ui";

Top Bar

Back, close, and logo controls for flow headers.

Install

pnpm dlx shadcn@latest add @blocks/top-bar

Use

import { TopBar } from "@circle/ui";

Fillout Flow

Schema-driven Fillout flow renderer with components from the circle-ui namespace and compatible submission payloads.

Install

pnpm dlx shadcn@latest add @blocks/fillout-flow

Use

import {
  FilloutFlow,
  createFilloutFlowDefinition,
  type FilloutFormMetadata,
} from "@circle/ui";

const flow = createFilloutFlowDefinition(form as FilloutFormMetadata, {
  steps: [
    { id: "goal", fields: ["kaRM"] },
    { id: "details", fields: ["h8ay", "goHS"] },
  ],
});

<FilloutFlow flow={flow} onSubmit={submitToFillout} />;

Commerce

Product, pricing, quantity, cart, and discount patterns.

Install

pnpm dlx shadcn@latest add @blocks/commerce

Use

import { ProductCard } from "@circle/ui";

Booking Timeline

Ordered booking steps with progress, notes, directions, and tasks.

Install

pnpm dlx shadcn@latest add @blocks/booking-timeline

Use

import { BookingTimeline } from "@circle/ui";

Media

Video, lightbox, gallery, carousel, and testimonial patterns.

Install

pnpm dlx shadcn@latest add @blocks/media

Use

import { Video } from "@circle/ui";

Map

Mapbox location preview with coordinate fallback.

Install

pnpm dlx shadcn@latest add @blocks/map

Use

import { Map } from "@circle/ui";

Address

Address search, manual entry, and mode switching.

Install

pnpm dlx shadcn@latest add @blocks/address

Use

import { AddressInput } from "@circle/ui";

Dependencies

Kind	Packages
Registry	@circle-ui/form
npm	mapbox-gl

Support

Support contact card with an avatar and link.

Install

pnpm dlx shadcn@latest add @blocks/support

Use

import { Support } from "@circle/ui";

Cookie Consent

CookieConsent combines a consent sheet with a controller for storage, reopening preferences, browser events, subscriptions, and optional server persistence.

Install

pnpm dlx shadcn@latest add @blocks/cookie-consent

Basic use

import {
  CookieConsent,
  createCookieConsentController,
  createCookieConsentCookieStorage,
} from "@/components/ui/cookie-consent";

const controller = createCookieConsentController({
  storage: createCookieConsentCookieStorage({
    days: 180,
    sameSite: "Lax",
    secure: process.env.NODE_ENV === "production",
  }),
});

export function CookieConsentProvider() {
  return <CookieConsent controller={controller} />;
}

Create one controller and pass the same instance to the sheet and to any code that reads consent. Without an explicit controller, the component creates one that uses window.localStorage.

Lifecycle

1. On mount, the component reads the configured storage key.
2. When a valid record exists, it restores the choices and emits a hydrate change. It does not auto-open the sheet.
3. When no valid record exists, autoOpen opens the sheet by default.
4. Accepting, rejecting, or saving a selection forces required categories to true, writes the record, emits change events, calls the persistence hook, and notifies subscribers.
5. openPreferences() reopens the sheet on its settings screen with the latest stored choices.

Stored records are normalized against the current categories whenever they are read. Removed category ids are dropped, new ids receive their configured default, and required categories remain enabled.

Production setup

Use the cookie adapter when the preference must be available across page loads as a cookie or shared by subdomains. Guard the shared domain so local and preview hosts keep a host-only cookie.

"use client";
 
import {
  CookieConsent,
  createCookieConsentController,
  createCookieConsentCookieStorage,
  type CookieConsentCategory,
} from "@/components/ui/cookie-consent";
 
const categories: CookieConsentCategory[] = [
  {
    id: "essential",
    label: "Essential",
    description: "Required to provide the requested service.",
    required: true,
  },
  {
    id: "analytics",
    label: "Analytics",
    description: "Helps us understand product usage.",
    defaultValue: false,
  },
  {
    id: "marketing",
    label: "Marketing",
    description: "Measures and personalizes campaigns.",
    defaultValue: false,
  },
];
 
function resolveCookieDomain(location: Location) {
  const hostname = location.hostname.toLowerCase();
 
  if (hostname === "circle.health" || hostname.endsWith(".circle.health")) {
    return ".circle.health";
  }
 
  return null;
}
 
export const cookieConsent = createCookieConsentController({
  categories,
  storage: createCookieConsentCookieStorage({
    days: 180,
    domain: resolveCookieDomain,
    sameSite: "Lax",
    secure: process.env.NODE_ENV === "production",
  }),
  storageKey: "ch_cc",
  version: "1",
});
 
export function CookieConsentProvider() {
  return (
    <CookieConsent
      controller={cookieConsent}
      policyLink={{
        href: "/privacy",
        label: "privacy and cookie policy",
      }}
    />
  );
}

Render the provider once near the application root. Keep category ids stable: they are the keys consumed by analytics, marketing, and personalization integrations.

Cookie storage options

The adapter is client-side and cannot create an HttpOnly cookie. When a domain is configured, it also removes an older host-only cookie so that one unambiguous record remains.

Categories and stored preferences

Category fields

The built-in categories are a starter configuration, not a policy. Define the categories owned by the consuming application.

Stored record

The default storage key is ch_cc. Both local storage and cookie storage use the same JSON record:

{
  "id": "8a9f9f61-cfdd-4556-9ed3-7537d7c7e580",
  "version": "1",
  "updatedAt": "2026-07-24T08:00:00.000Z",
  "consents": {
    "essential": true,
    "analytics": false,
    "marketing": false
  }
}

The id is retained when an existing preference is updated. updatedAt records the latest user choice. Increment version when a policy or category change requires a new choice; a stored record with a different version is treated as absent.

Gate optional services

Read the controller before loading an optional service, and react to later changes. Mounting the sheet with an existing record dispatches the current preferences with source: "hydrate".

const cookieConsent = createCookieConsentController({
  onPreferencesChange({ consents, source }) {
    if (consents.analytics) {
      startAnalytics();
    } else {
      stopAnalytics();
    }
 
    console.info("Consent applied", source);
  },
});

onPreferencesChange runs for a stored choice and for hydration. It is the most direct integration point when the controller and service bootstrap live in the same application.

Browser events

The two change events are CustomEvent<CookieConsentEventDetail> events. Their detail contains categories, consents, the complete preferences record, source, and version.

import type { CookieConsentEventDetail } from "@/components/ui/cookie-consent";
 
document.addEventListener("cookies-chosen", (event) => {
  const { consents } = (event as CustomEvent<CookieConsentEventDetail>).detail;
 
  if (consents.analytics) startAnalytics();
});

Set emitDataLayerEvents: true to also push { event: eventName } to window.dataLayer, or set dataLayerName for another array. Data-layer entries contain the event name only; use the callback or DOM event when the integration needs the preference detail.

Let people revisit their choice

Keep a cookie-settings action available after the sheet closes.

export function CookieSettingsButton() {
  return (
    <button type="button" onClick={() => cookieConsent.openPreferences()}>
      Cookie settings
    </button>
  );
}

Code without the controller can dispatch the exported default event:

import { DEFAULT_OPEN_PREFERENCES_EVENT } from "@/components/ui/cookie-consent";
 
window.dispatchEvent(new CustomEvent(DEFAULT_OPEN_PREFERENCES_EVENT));

The event only has an effect while a CookieConsent component is mounted.

Optional window bridge

Legacy scripts and tag-manager code can use a global bridge instead of importing the controller. Attach it from a client component and return the cleanup function from the effect.

import { useEffect } from "react";
 
import { attachCookieConsentBridge } from "@/components/ui/cookie-consent";
 
export function CookieConsentBridge() {
  useEffect(() => attachCookieConsentBridge(window, cookieConsent), []);
 
  return null;
}

The default global is window.CH_CC. It exposes consents, get, set, update, subscribe, delete, reset, openPreferences, and dispatchCurrentPreferences. Pass a third argument to change the global name. Cleanup restores any value that existed there before the bridge was attached.

Persist an audit record

persist receives the same event detail plus storageKey and optional persistText. It runs only after a user choice, not during hydration.

const cookieConsent = createCookieConsentController({
  persistText: "Cookie consent v3",
  async persist(payload) {
    await fetch("/api/consent", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify(payload),
    });
  },
});

Configured client storage is written first. Persistence is fire-and-forget: a rejected promise logs an error and does not roll back the local preference or keep the sheet open. Handle authentication, retries, and server validation in the application when the audit record is required.

Controller reference

Neither reset() nor delete() emits a consent change event or removes cookies owned by other services.

Controller options

Component props

Localization

The optional copy pack provides English and German dictionaries. It is data, not an automatic locale provider; map the selected dictionary into categories, labels, title, and description in the consuming application.

pnpm dlx shadcn@latest add @i18n/cookie-consent-copy

import { cookieConsentCopy } from "@/registry/berlin/i18n/cookie-consent-copy";
 
const copy = cookieConsentCopy.de;
 
<CookieConsent
  controller={cookieConsent}
  title={copy.title}
  labels={{
    acceptAll: copy.buttons.acceptAll,
    back: copy.buttons.back,
    customize: copy.buttons.customize,
    essential: copy.settings.essential,
    rejectAll: copy.buttons.rejectAll,
    required: copy.settings.required,
    saveSelection: copy.buttons.saveSelection,
    settingsAriaLabel: copy.settings.ariaLabel,
  }}
/>;

The {link} token in subtitle is an application interpolation point. The component does not replace it automatically.

Metric Donut Card

Circular metric card for compact progress and threshold summaries.

Install

pnpm dlx shadcn@latest add @blocks/metric-donut-card

Use

import { MetricDonutCard } from "@circle/ui";

Metric Range Card

Range-based metric card for score bands, ticks, and highlighted target ranges.

Install

pnpm dlx shadcn@latest add @blocks/metric-range-card

Use

import { MetricRangeCard } from "@circle/ui";

Metric Split Card

Two-sided comparison card for paired values or before-and-after measurements.

Install

pnpm dlx shadcn@latest add @blocks/metric-split-card

Use

import { MetricSplitCard } from "@circle/ui";

Metric Stat Card

Single-value metric card with optional status labelling.

Install

pnpm dlx shadcn@latest add @blocks/metric-stat-card

Use

import { MetricStatCard } from "@circle/ui";

Text Columns Card

Neutral two-column text layout with independent headings and copy.

Install

pnpm dlx shadcn@latest add @blocks/text-columns-card

Use

import { TextColumnsCard } from "@circle/ui";

Segment Muscle Analysis

Composed muscle-distribution block with a figure image, hotspots, and surrounding metric cards.

Install

pnpm dlx shadcn@latest add @blocks/segment-muscle-analysis

Use

import { SegmentMuscleAnalysis } from "@circle/ui";

Patient Results Editor

BlockNote editor with diagnostic blocks registered.

Install

pnpm dlx shadcn@latest add @blocks/patient-results-editor

Use

import { PatientResultsEditor } from "@circle/ui";

Dependencies

Kind	Packages
Registry	@blocks/diagnostic-interpretation-columns, @blocks/metric-donut-card, @blocks/metric-range-card, @blocks/metric-split-card, @blocks/metric-stat-card, @blocks/segment-muscle-analysis, @circle-ui/button
npm	@blocknote/core, @blocknote/shadcn

Patient Results Report

Preset-aware browser renderer for patient-results documents.

Install

pnpm dlx shadcn@latest add @blocks/patient-results-report

Use

import { PatientResultsReport } from "@circle/ui";

Patient Results PDF

React-pdf renderer for patient-results documents.

Install

pnpm dlx shadcn@latest add @blocks/patient-results-pdf

Use

import { pdf } from "@react-pdf/renderer";
import { PatientResultsPdfDocumentFromEditor } from "@/components/blocks/patient-results-pdf";

const blob = await pdf(
  <PatientResultsPdfDocumentFromEditor
    document={editor.document}
    presetId="vns-report"
  />,
).toBlob();

Patient Results Suite

Umbrella install for the editor, browser report, PDF, and presets.

Install

pnpm dlx shadcn@latest add @blocks/patient-results-blocks

Utilities

Installable helpers and browser tools with no UI workflow attached.

• Nextra Export — Export a complete Nextra site as rich Markdown or one component-faithful PDF.
• Analytics — Provider-neutral events and tag-manager bridge.
• Circle Mixpanel Config — Deferred Google Tag Manager and Mixpanel initialization for Circle Health web apps.
• CircleOS PII Mask — Prepare safe screenshots, recordings, and demos.

Nextra Export

Export a complete Nextra site as one Markdown file or a print-ready book. The PDF view renders the site’s real MDX and React components. Markdown components use a project-owned renderer registry.

Install

pnpm dlx shadcn@latest add @utilities/nextra-export

The command writes the exporter below src/lib/nextra-export. It installs unified and the Remark packages used for MDX normalization. The target site must already use Nextra 4.

Load the documentation tree

Create one project-specific loader:

import {
  collectNextraExportPages,
  loadNextraPageSources,
} from "@/lib/nextra-export";
import { importPage } from "nextra/pages";
import { getPageMap } from "nextra/page-map";
 
export async function loadDocsExportPages() {
  const pages = collectNextraExportPages(await getPageMap());
  return loadNextraPageSources(pages, importPage);
}

Page order follows Nextra navigation. Set export: false in a page’s frontmatter to omit it.

Add the PDF route

Reserve /export/pdf inside the existing Nextra catch-all. Next 16 can let the root optional catch-all shadow a sibling page at the same URL.

import { ExportBook } from "@/lib/nextra-export";
import { loadDocsExportPages } from "@/lib/docs-export";
 
async function PdfExportPage() {
  const pages = await loadDocsExportPages();
 
  return (
    <ExportBook
      title="My Docs"
      siteHref="https://docs.example.com"
      siteLabel="docs.example.com"
      pages={pages.map(({ Content, route, sectionPath, title }) => ({
        content: <Content />,
        route,
        sectionPath,
        title,
      }))}
    />
  );
}
 
export default async function Page({ params }) {
  const { mdxPath } = await params;
  if (mdxPath?.join("/") === "export/pdf") return <PdfExportPage />;
 
  // Keep the site's existing importPage(...) implementation here.
}

If the Nextra theme layout wraps the catch-all route, return children directly from that layout for export/pdf. This keeps the navbar and sidebar out of the book.

Add the button to the Nextra navbar:

import { ExportPdfButton } from "@/lib/nextra-export";
 
<Navbar logo={logo}>
  <ExportPdfButton />
</Navbar>;

The button opens the complete book and starts the browser print flow after its fonts and images settle. Choose Save as PDF to create one bundled file. The table of contents uses internal PDF jumps. Links inside exported pages are rewritten to canonical absolute URLs and printed in full after their labels, so they remain usable in strict PDF viewers and on paper. siteHref sets that canonical origin and adds the documentation link to the cover.

Add the Markdown route

Create a route handler outside the Nextra catch-all:

import { exportMarkdownBundle } from "@/lib/nextra-export";
import { loadDocsExportPages } from "@/lib/docs-export";
 
export async function GET() {
  const markdown = await exportMarkdownBundle({
    title: "My Docs",
    pages: await loadDocsExportPages(),
    siteUrl: "https://docs.example.com",
  });
 
  return new Response(markdown, {
    headers: {
      "Content-Disposition": 'attachment; filename="my-docs.md"',
      "Content-Type": "text/markdown; charset=utf-8",
    },
  });
}

Internal page links become anchors in the bundled document. Frontmatter and MDX module statements are removed.

Render custom MDX components

Pass a renderer for each project-specific component:

import type { ComponentRendererRegistry } from "@/lib/nextra-export";
 
export const components: ComponentRendererRegistry = {
  ProductCard: ({ attributes }) =>
    `**${attributes.title}** — [Open product](${attributes.href})`,
  Diagram: async ({ attributes }) =>
    `![${attributes.alt}](${await renderDiagramImage(attributes)})`,
};

Renderers receive literal attributes, normalized Markdown children, and the current page. They may return text, tables, code, links, or generated image URLs. Unregistered components keep their children and produce a labeled fallback instead of disappearing.

Pass the registry as components to exportMarkdownBundle.

Analytics

Provider-neutral events and tag-manager bridge.

Install

pnpm dlx shadcn@latest add @utilities/analytics

Use

import { trackEvent } from "@/lib/analytics";

trackEvent("booking_started", {
  serviceId,
  source: "service-page",
});

Circle Mixpanel Config

Deferred Google Tag Manager and Mixpanel initialization for Circle Health web apps.

Install

pnpm dlx shadcn@latest add @utilities/circle-mixpanel-config

Use

import { CircleMixpanelConfig } from "@circle/ui";

CircleOS PII Mask

The script masks tagged names, emails, phone numbers, birth dates, addresses, and avatars. Paste it into DevTools before screenshots or recordings. It installs window.__circlePiiMask, applies masking immediately, and watches for remounts.

Mark sensitive elements

<div data-pii="name">Jane Doe</div>
<div data-pii="email">jane@example.com</div>
<div data-pii="phone">+49 1512 1234567</div>
<div data-pii="dob">23.09.1988 (37)</div>
<div data-pii="address">Rosenthaler Str. 16\n10119 Berlin</div>
<img data-pii="avatar" src="/avatar.jpg" alt="" />

Runtime API

window.__circlePiiMask.mask();
window.__circlePiiMask.unmask();
window.__circlePiiMask.toggle();
window.__circlePiiMask.destroy();

Full script

(() => {
  if (window.__circlePiiMask?.destroy) {
    window.__circlePiiMask.destroy();
  }
 
  const CONFIG = {
    selector: "[data-pii]",
    avatarMode: "blur", // "blur" | "hide"
  };
 
  const NAME_SEEDS = [
    "Anna Schmidt",
    "Lukas Müller",
    "Sophie Fischer",
    "Paul Weber",
    "Leonie Wagner",
    "Jonas Becker",
    "Marie Hoffmann",
    "Felix Schäfer",
    "Clara Koch",
    "Noah Bauer",
    "Emma Richter",
    "Ben Klein",
    "Mila Wolf",
    "Leon Neumann",
    "Hannah Schwarz",
    "Finn Zimmermann",
    "Laura Braun",
    "Elias Krüger",
    "Johanna Hartmann",
    "Mats Lange",
    "Nele Werner",
    "David Schmitz",
    "Ida Krause",
    "Tom Meier",
    "Lina Lehmann",
    "Moritz Schulz",
    "Greta Maier",
    "Oskar Kraus",
    "Pia Keller",
    "Anton Herrmann",
    "Theresa König",
    "Julian Walter",
    "Mira Mayer",
    "Vincent Huber",
    "Paula Kaiser",
    "Emil Fuchs",
    "Amelie Peters",
    "Nico Lang",
    "Frieda Scholz",
    "Samuel Möller",
    "Lotta Weiß",
    "Maximilian Jung",
    "Carla Pohl",
    "Theo Simon",
    "Elisa Franke",
    "Jakob Albrecht",
    "Nina Vogt",
    "Henry Winter",
    "Jule Seidel",
    "Marlon Graf",
  ];
 
  const STREET_SEEDS = [
    "Lindenstrasse 12",
    "Bergweg 8",
    "Gartenallee 27",
    "Sonnenweg 14",
    "Feldstrasse 33",
    "Am Park 5",
    "Wiesenweg 19",
    "Birkenallee 42",
    "Bahnhofstrasse 11",
    "Mozartstrasse 24",
  ];
 
  const CITY_SEEDS = [
    ["10115", "Berlin"],
    ["20095", "Hamburg"],
    ["80331", "Muenchen"],
    ["50667", "Koeln"],
    ["60311", "Frankfurt am Main"],
    ["01067", "Dresden"],
    ["70173", "Stuttgart"],
    ["04109", "Leipzig"],
    ["28195", "Bremen"],
    ["30159", "Hannover"],
  ];
 
  const textStore = new WeakMap();
  const avatarStore = new WeakMap();
 
  let observer = null;
  let masked = false;
  let applying = false;
  let scheduled = false;
 
  const transliterate = (value) =>
    String(value)
      .normalize("NFKD")
      .replace(/[\u0300-\u036f]/g, "")
      .replace(/ä/g, "ae")
      .replace(/ö/g, "oe")
      .replace(/ü/g, "ue")
      .replace(/Ä/g, "Ae")
      .replace(/Ö/g, "Oe")
      .replace(/Ü/g, "Ue")
      .replace(/ß/g, "ss")
      .replace(/[^a-zA-Z0-9]+/g, "-")
      .replace(/^-+|-+$/g, "")
      .toLowerCase();
 
  const hashString = (value) => {
    let hash = 2166136261;
    for (let index = 0; index < value.length; index += 1) {
      hash ^= value.charCodeAt(index);
      hash = Math.imul(hash, 16777619);
    }
    return hash >>> 0;
  };
 
  const pickSeedName = (source) => {
    const index = hashString(source || "person") % NAME_SEEDS.length;
    return NAME_SEEDS[index];
  };
 
  const fakeEmail = (source) => {
    const [firstName, ...rest] = pickSeedName(source).split(" ");
    const lastName = rest.join(" ");
    const suffix = String((hashString(`email:${source}`) % 90) + 10);
    return `${transliterate(firstName)}.${transliterate(lastName)}${suffix}@beispiel.invalid`;
  };
 
  const fakePhone = (source) => {
    const prefixes = [
      "1512",
      "1523",
      "1550",
      "1577",
      "1590",
      "1602",
      "1704",
      "1718",
      "1726",
      "1763",
    ];
    const hash = hashString(`phone:${source}`);
    const prefix = prefixes[hash % prefixes.length];
    const tail = String(1000000 + (hash % 9000000));
    return `+49 ${prefix.slice(0, 3)} ${prefix.slice(3)} ${tail.slice(0, 3)} ${tail.slice(3)}`;
  };
 
  const fakeDob = (source) => {
    const day = String((hashString(`dob-day:${source}`) % 28) + 1).padStart(
      2,
      "0",
    );
    const month = String((hashString(`dob-month:${source}`) % 12) + 1).padStart(
      2,
      "0",
    );
    const year = String(1960 + (hashString(`dob-year:${source}`) % 40));
    const age = new Date().getFullYear() - Number(year);
    return `${day}.${month}.${year} (${age})`;
  };
 
  const fakeAddress = (source) => {
    const street =
      STREET_SEEDS[hashString(`street:${source}`) % STREET_SEEDS.length];
    const [postalCode, city] =
      CITY_SEEDS[hashString(`city:${source}`) % CITY_SEEDS.length];
    return `${street}\n${postalCode}, ${city}, DE`;
  };
 
  const getText = (element) => {
    if (
      element instanceof HTMLInputElement ||
      element instanceof HTMLTextAreaElement
    ) {
      return element.value;
    }
    return element.textContent || "";
  };
 
  const setText = (element, value) => {
    if (
      element instanceof HTMLInputElement ||
      element instanceof HTMLTextAreaElement
    ) {
      element.value = value;
      return;
    }
    element.textContent = value;
  };
 
  const maskTextValue = (kind, original) => {
    const clean = String(original || "").trim();
    if (!clean) return clean;
 
    if (kind === "name") return pickSeedName(clean);
    if (kind === "email") return fakeEmail(clean);
    if (kind === "phone") return fakePhone(clean);
    if (kind === "dob") return fakeDob(clean);
    if (kind === "address") return fakeAddress(clean);
    return clean;
  };
 
  const rememberText = (element) => {
    if (!textStore.has(element)) {
      textStore.set(element, getText(element));
    }
    return textStore.get(element);
  };
 
  const rememberAvatar = (element) => {
    if (!avatarStore.has(element)) {
      avatarStore.set(element, {
        filter: element.style.filter,
        opacity: element.style.opacity,
        transform: element.style.transform,
        transition: element.style.transition,
        pointerEvents: element.style.pointerEvents,
      });
    }
    return avatarStore.get(element);
  };
 
  const maskAvatar = (element) => {
    rememberAvatar(element);
    element.style.transition =
      "filter 120ms ease, opacity 120ms ease, transform 120ms ease";
    element.style.pointerEvents = "none";
 
    if (CONFIG.avatarMode === "hide") {
      element.style.opacity = "0.08";
      element.style.filter = "grayscale(1) brightness(1.15)";
      element.style.transform = "scale(1.02)";
      return;
    }
 
    element.style.opacity = "1";
    element.style.filter =
      "blur(12px) grayscale(1) saturate(0) brightness(1.05)";
    element.style.transform = "scale(1.08)";
  };
 
  const unmaskAvatar = (element) => {
    const original = avatarStore.get(element);
    if (!original) return;
    element.style.filter = original.filter;
    element.style.opacity = original.opacity;
    element.style.transform = original.transform;
    element.style.transition = original.transition;
    element.style.pointerEvents = original.pointerEvents;
  };
 
  const maskElement = (element) => {
    const kind = element.getAttribute("data-pii");
    if (!kind) return;
 
    if (kind === "avatar") {
      maskAvatar(element);
      element.setAttribute("data-pii-masked", "true");
      return;
    }
 
    const original = rememberText(element);
    setText(element, maskTextValue(kind, original));
    if (kind === "address") {
      element.style.whiteSpace = "pre-line";
    }
    element.setAttribute("data-pii-masked", "true");
  };
 
  const unmaskElement = (element) => {
    const kind = element.getAttribute("data-pii");
    if (!kind) return;
 
    if (kind === "avatar") {
      unmaskAvatar(element);
      element.removeAttribute("data-pii-masked");
      return;
    }
 
    if (!textStore.has(element)) return;
    setText(element, textStore.get(element));
    if (kind === "address") {
      element.style.whiteSpace = "";
    }
    element.removeAttribute("data-pii-masked");
  };
 
  const applyMask = (root = document) => {
    applying = true;
    root.querySelectorAll(CONFIG.selector).forEach(maskElement);
    applying = false;
  };
 
  const applyUnmask = (root = document) => {
    applying = true;
    root
      .querySelectorAll(`${CONFIG.selector}[data-pii-masked="true"]`)
      .forEach(unmaskElement);
    applying = false;
  };
 
  const scheduleRefresh = () => {
    if (!masked || scheduled) return;
    scheduled = true;
    requestAnimationFrame(() => {
      scheduled = false;
      applyMask(document);
    });
  };
 
  const startObserver = () => {
    if (observer) return;
 
    observer = new MutationObserver(() => {
      if (!applying) scheduleRefresh();
    });
 
    observer.observe(document.body, {
      childList: true,
      subtree: true,
      characterData: true,
      attributes: true,
    });
  };
 
  const stopObserver = () => {
    if (!observer) return;
    observer.disconnect();
    observer = null;
  };
 
  const api = {
    config: CONFIG,
    mask() {
      masked = true;
      applyMask(document);
      startObserver();
      console.info("PII masking enabled");
    },
    unmask() {
      masked = false;
      stopObserver();
      applyUnmask(document);
      console.info("PII masking disabled");
    },
    toggle() {
      if (masked) this.unmask();
      else this.mask();
    },
    destroy() {
      this.unmask();
      delete window.__circlePiiMask;
    },
  };
 
  window.__circlePiiMask = api;
  api.mask();
})();