Package exports

Orbz separates pure API access, automatic browser registration, the React adapter, and the standalone browser bundle. Choose the narrowest entry point for the job.

Entry-point map

Import	Exposes	Side effect
`@neongate-ai/orbz`	Native element types, constants, presets, normalization helpers, `createOrbzElementClass()`, and `defineOrbz()`	Does not register the tag
`@neongate-ai/orbz/browser`	Everything from the root entry	Calls `defineOrbz()`
`@neongate-ai/orbz/react`	`<Orbz />`, `OrbzProps`, and related option types	Registers through the adapter after mount
`@neongate-ai/orbz/standalone`	Self-contained browser build of the browser entry	Calls `defineOrbz()`
`@neongate-ai/orbz/package.json`	Published package metadata	None

The browser and standalone entry points are marked as side-effectful in the package manifest so bundlers retain their registration call.

Root entry

Use the root entry for explicit registration and reusable domain types:


import {
  defineOrbz,
  ORBZ_PRESETS,
  ORBZ_STATES,
  type OrbzElement,
  type OrbzPresetName,
  type OrbzState,
} from "@neongate-ai/orbz";
 
defineOrbz();
 
const nextState: OrbzState = "listening";
const preset: OrbzPresetName = "neongate";
const colors = ORBZ_PRESETS[preset];
const orb = document.querySelector<OrbzElement>("orb-z");
 
if (orb) orb.state = nextState;

Importing the root module alone never registers orb-z. Call defineOrbz() or import /browser when a page should upgrade the tag.

Constants

Export	Meaning
`ORBZ_TAG_NAME`	The string `"orb-z"`
`ORBZ_OBSERVED_ATTRIBUTES`	Reactive native attribute names
`ORBZ_STATES`	All supported assistant states
`ORBZ_REDUCED_MOTION_MODES`	`system`, `always`, and `never`
`ORBZ_PRESET_NAMES`	All six preset names
`ORBZ_PRESETS`	Frozen color values for every preset
`ORBZ_COLOR_ATTRIBUTES`	Map from color keys to native attribute names
`ORBZ_COLOR_KEYS`	The five color keys
`DEFAULT_ORBZ_STATE`	`idle`
`DEFAULT_ORBZ_SIZE`	`16rem`
`DEFAULT_ORBZ_SPEED`	`1`
`DEFAULT_ORBZ_REDUCED_MOTION`	`system`
`DEFAULT_ORBZ_PRESET`	`neongate`
`DEFAULT_ORBZ_COLORS`	The NeonGate preset colors

The arrays and preset records are useful for generating validated controls without copying the package’s accepted values.


import { ORBZ_PRESET_NAMES, ORBZ_STATES } from "@neongate-ai/orbz";
 
for (const state of ORBZ_STATES) {
  stateSelect.add(new Option(state, state));
}
 
for (const preset of ORBZ_PRESET_NAMES) {
  presetSelect.add(new Option(preset, preset));
}

Types

Export	Shape
`OrbzState`	Union of the five state names
`OrbzReducedMotion`	`"system" \| "always" \| "never"`
`OrbzPresetName`	Union of the six preset names
`OrbzSize`	`number \| string`
`OrbzColors`	Required `primary`, `secondary`, `accent`, `highlight`, and `background` strings
`OrbzColorOverrides`	Partial `OrbzColors`
`OrbzBaseOptions`	State, size, speed, pause, elevation, and reduced-motion options
`OrbzPresetOptions`	Preset mode; custom color keys are `never`
`OrbzCustomColorOptions`	Custom-color mode; `preset` is `never`
`OrbzColorSelection`	Union of preset and custom-color mode
`OrbzOptions`	Base options combined with the color selection union
`OrbzElement`	Native element properties and playback methods
`OrbzElementConstructor`	Typed custom-element constructor

Validators and normalizers

Export	Purpose
`isOrbzState()`	Type guard for a supported state
`isOrbzPresetName()`	Type guard for a preset name
`isOrbzReducedMotion()`	Type guard for a reduced-motion value
`normalizeOrbzState()`	Unsupported input becomes `idle`
`normalizeOrbzPreset()`	Unsupported input becomes `neongate`
`normalizeOrbzReducedMotion()`	Unsupported input becomes `system`
`normalizeOrbzSize()`	Numbers become pixels; invalid numeric or empty input becomes `16rem`
`normalizeOrbzSpeed()`	Non-positive or non-finite input becomes `1`
`mergeOrbzColors()`	Merge valid, non-empty overrides over a base color set

Normalize untrusted configuration before storing it:


import {
  normalizeOrbzPreset,
  normalizeOrbzSpeed,
  normalizeOrbzState,
} from "@neongate-ai/orbz";
 
const config = {
  preset: normalizeOrbzPreset(payload.preset),
  speed: normalizeOrbzSpeed(payload.speed),
  state: normalizeOrbzState(payload.state),
};

Registration helpers

defineOrbz() is the normal explicit-registration API. It is SSR-safe and idempotent:


import { defineOrbz } from "@neongate-ai/orbz";
 
const constructor = defineOrbz();

createOrbzElementClass() creates and caches the class only when globalThis.HTMLElement exists. It is exported for advanced integrations; most applications should call defineOrbz() instead.


import { createOrbzElementClass } from "@neongate-ai/orbz";
 
const constructor = createOrbzElementClass();
// undefined on a server; an OrbzElementConstructor in a browser

Both helpers avoid evaluating an HTMLElement subclass when the DOM is not available.