Skip to Content
OrbzChangelog

Changelog

This page records user-facing changes to the public @neongate-ai/orbz package, the <orb-z> custom-element contract, and its supported integration paths.

The implementation source of truth is the GitHub repository . Published releases are available on npm , and the complete documentation is available at orbz.site .

1.0.2 — 2026-09-08

NeonGate preset correction

  • Restored neongate as the canonical default preset name, including DEFAULT_ORBZ_PRESET, ORBZ_PRESET_NAMES and the element’s normalized preset getter. The NeonGate colors are unchanged.
  • Retained the accidental gojhonny name from 1.0.1 as a deprecated input alias. Existing attributes, property assignments, typed inputs and guards still accept it; normalization and attribute reflection use neongate.
  • Preserved ORBZ_PRESETS.gojhonny as an immutable, non-enumerable alias of ORBZ_PRESETS.neongate. The canonical preset list still contains six entries.
  • Normalized legacy compact and complete configuration objects without mutating caller input, while preserving supplied colors and strict validation.

Upgrading from 1.0.1

Install the published patch and update pinned CDN URLs:

npm install @neongate-ai/orbz@1.0.2

Use neongate in new explicit preset values. Existing gojhonny inputs remain compatible; migrate them when convenient. Code that reads a normalized preset name should expect neongate. See NeonGate preset naming for default examples and palette access.

This correction supersedes the 1.0.1 naming guidance retained below as release history. The npm scope remains @neongate-ai/orbz, and the GitHub owner remains gojhonny.

View 1.0.2 on npm · Browse the v1.0.2 source tag · Compare the tagged source 

1.0.1 — 2026-09-08

Cleanup and compact configuration

  • Fixed orb cleanup (alias orb clean) in the Orbz source checkout to remove root and nested untracked node_modules and generated output by default. --dry-run previews the targets; --keep-dependencies retains dependencies. Tracked content, source/assets, harness metadata and nested repositories are preserved, and cleanup does not follow directory symlinks.
  • Simplified the authored configuration JSON. The transformer now fills omitted internal appearance, motion and speech groups from typed defaults, then validates, clones and freezes the runtime configuration. Explicit overrides for those groups remain supported.
  • Updated GitHub ownership links to gojhonny and refreshed the README, CLI guide and engineering checks. The npm package remains @neongate-ai/orbz.

Upgrading from 1.0.0

Install the patch and update pinned CDN URLs:

npm install @neongate-ai/orbz@1.0.1

The default preset is now named gojhonny, with the same five colors as the former neongate preset. Update explicit preset literals, typed preset names and named preset access to gojhonny:

<orb-z preset="gojhonny"></orb-z>

The old name is no longer a supported preset literal. If you maintain an Orbz source checkout, use orb cleanup --keep-dependencies to retain node_modules; plain orb cleanup now removes it. These migration details apply even though the published version is a patch release.

View 1.0.1 on npm · Compare the tagged source 

1.0.0 — 2026-09-06

Voice models and Realtime conversations

  • Added the typed JavaScript voiceModel property for web-speech, openai-speech, and openai-realtime. Selecting a provider remains silent; the host explicitly starts speech or a conversation after user activation.
  • Added OpenAIRealtimeAdapter and direct browser-to-provider WebRTC audio. Applications authorize session setup through realtimeSession, using their own endpoint or an async callback that returns an SDP answer.
  • Added startConversation(), stopConversation(), interruptConversation(), read-only conversationState, and the orbz-conversation-state-change and orbz-transcript events for application-owned controls and transcript UI.
  • Provider keys stay on the application backend. Model settings contain public configuration only; endpoint objects reject unknown fields such as apiKey, token, and headers. Neither secrets nor session tokens belong in HTML attributes, component properties, or the configuration JSON.

Canonical configuration and CLI

  • Fork maintainers now edit src/orbz.config.json for component, appearance, motion, speech, and Realtime defaults, then rebuild the package. Installed packages use bundled defaults rather than fetching configuration at runtime.
  • Added read-only orbzConfiguration and the pure transformOrbzConfiguration() utility to validate, clone, transform and freeze complete configuration objects without changing the package singleton.
  • Consolidated Orb CLI command handling and help. Existing public exports, visual attributes, native registration, and explicit voiceEngine integrations remain available.

Upgrading from 0.4.3

Install the published release and update any pinned CDN URLs:

npm install @neongate-ai/orbz@1.0.0

Existing visual examples keep the same <orb-z> tag and browser entry. New structured options use JavaScript properties; no voice-model HTML attribute exists. Realtime requires application-owned session authorization and explicit activation; upgrading the package does not start audio or request a microphone. An explicitly assigned voiceEngine takes precedence over voiceModel.

View 1.0.0 on npm

0.4.3 — 2026-09-04

Highlights since 0.3.1

  • Added the published orb POSIX shell CLI as the package binary. Run it transiently with npx -y --package=@neongate-ai/orbz@latest orb.
  • Orb project setup detects npm, pnpm, Yarn, or Bun from project metadata and lockfiles, installs the executing Orbz version, and does not generate or overwrite application source files.
  • WebSpeechAdapter now defaults to Brazilian Portuguese (pt-BR). Applications can override language, including en-US, when another locale is required.
  • Orbz now ships without a canned greeting, persona, or default conversation flow. Consumers provide speech or talkFlow, configure a voiceEngine, and explicitly call startTalking().

View 0.4.3 on npm

0.3.1 — 2026-08-25

Explicit speech opt-in

  • Connecting or upgrading <orb-z> no longer creates a default voice engine or starts a talk flow.
  • voiceEngine now defaults to undefined. Applications explicitly provide an engine and call startTalking() after the visitor opts in.
  • Assigning a voice engine remains silent; stopTalking() stops an active flow, and assigning undefined removes the configured engine.
  • Numeric strings passed through HTML or server-rendered markup now normalize to pixel lengths consistently with numeric property values.

View 0.3.1 on npm

0.3.0 — 2026-08-23

React and Next.js typing

  • Added the optional @neongate-ai/orbz/react-types entry for React and Next.js TypeScript projects.
  • The entry augments JSX so <orb-z> is typed without a framework wrapper component.
  • React remains absent from the Orbz runtime dependency surface; React types are used only to build the optional declaration entry.

0.2.0 — 2026-08-22

Orbz 0.2.0 expands the original visual assistant component into a voice-capable, framework-agnostic custom element. This release introduces a talk runtime, interchangeable speech and intelligence ports, stricter appearance controls, stronger encapsulation, and a single native integration model for every supported framework.

Breaking pre-1.0 release: applications using the 0.1.0 colors property, public CSS variables, Shadow Parts, open Shadow DOM, or @neongate-ai/orbz/react must migrate.

Voice and talk runtime

  • Added an automatic deterministic talk flow that starts after the element’s first connected render.
  • Added the built-in welcoming, askName, help, and answer steps through the public talk object and DEFAULT_TALK_FLOW.
  • Added runtime-only talk memory. The default flow captures the visitor’s name and makes it available through talkContext without writing to cookies, local storage, IndexedDB, or a backend.
  • Added startTalking() to reset the current runtime context and restart the configured flow.
  • Added receive(input) so host applications can continue an active ask or response step with text collected from their own interface.
  • Added stopTalking() to stop the active flow and voice output.
  • Added the configurable voiceEngine, talkFlow, and intelligence properties.
  • Added OrbzTalkStep, OrbzTalkContext, and OrbzVoiceOptions as public TypeScript contracts.
  • Added OrbzVoiceEnginePort so applications can replace speech output without changing the component.
  • Added OrbzIntelligencePort so applications can connect an agent or other response provider while keeping product logic and credentials outside Orbz.
  • Added local fallback responses when no intelligence provider is configured or when the configured provider fails.
  • Added the orbz-speaking-change event with { speaking: boolean } detail.
  • Added the orbz-talk-error event with the original error in { error: unknown } detail.
  • Made Orbz temporarily enter the speaking visual state while audio is playing and restore its previous visual state afterward.
  • Kept microphone capture, speech recognition, permissions, transcripts, and text-input ownership in the host application. Orbz only receives text passed through receive().

Browser speech

  • Added WebSpeechAdapter as the zero-configuration default voice engine.
  • Changed the default speech locale to en-US.
  • Made browser speech wait for the asynchronously loaded voice list before choosing a voice.
  • Added explicit English-language filtering instead of accepting an unrelated operating-system default voice.
  • Added preferred-voice selection for configured voices and higher-quality Google, Microsoft, natural, neural, premium, enhanced, or online voices when the browser exposes them.
  • Added configurable language, preferred voices, rate, pitch, volume, and voice loading timeout.
  • Added detection for speech that fails to start instead of leaving the talk flow indefinitely pending.
  • Made first-render speech retry automatically after the first pointer, keyboard, or touch interaction when the browser blocks automatic audio with NotAllowedError.
  • Removed the example behavior that depended on remounting the element through Reset all before speech could begin.
  • Clarified that browser speech still uses voices provided by the visitor’s browser and operating system. Voice selection can be improved, but a system voice does not become an OpenAI-generated voice.

OpenAI speech

  • Added OpenAISpeechAdapter for application-proxied OpenAI text-to-speech.
  • Configured the adapter to use gpt-4o-mini-tts, the marin voice, MP3 output, and natural American-English delivery instructions by default.
  • Added configurable model, voice, response format, instructions, credentials, headers, and fetch implementation.
  • Added compatibility with legacy tts-1 and tts-1-hd models, including a compatible default voice and omission of unsupported instructions.
  • Kept the OpenAI API key outside the browser and outside the Orbz package. The adapter calls an implementer-owned endpoint that returns generated audio.
  • Added cancellation of pending speech requests when output is stopped or replaced.
  • Added cleanup of generated audio object URLs after playback, cancellation, or failure.
  • Added browser-activation error handling so generated audio can participate in the same first-interaction retry lifecycle as browser speech.

Appearance and component API

  • Replaced the open colors property with two strict and mutually exclusive appearance modes:

    • a preset attribute or property;
    • the five color-primary, color-secondary, color-accent, color-highlight, and color-background attributes.

  • Added six built-in presets: neongate, periwinkle, magenta, peach, mocha, and ivory.

  • Made preset mode and custom-color mode mutually exclusive. When both are present, Orbz reports a conflict, applies the preset, and ignores the custom colors until the preset attribute is removed.

  • Added the elevated boolean attribute and property for an optional centered shadow.

  • Retained the five public visual states: idle, listening, thinking, speaking, and asleep.

  • Retained positive speed multipliers, size normalization, pause and play controls, animation restart, and the system, always, and never reduced-motion policies.

  • Retained public constants, guards, and normalizers for states, presets, reduced motion, size, speed, and color configuration.

  • Changed the Shadow DOM from open to closed.

  • Removed public Shadow Parts and external ::part(...) styling.

  • Removed public --orbz-* CSS-variable customization. Internal selectors and variables are now private implementation details.

  • Moved the component’s source styles to src/element/index.css, retained them inside the closed shadow root, and emitted the same stylesheet as dist/index.css.

Framework integration and package entry points

  • Removed the framework-specific React component and the @neongate-ai/orbz/react package entry.
  • Removed React as a package peer dependency and development dependency from the Orbz runtime package.
  • Standardized every framework integration on the literal <orb-z> custom element.
  • Updated React and Next.js integrations to register the browser entry and render <orb-z> directly.
  • Added local JSX intrinsic-element declarations to the React and Next.js examples for TypeScript awareness without introducing a wrapper component.
  • Kept @neongate-ai/orbz as the side-effect-free package entry for types, constants, adapters, ports, factories, and explicit registration helpers.
  • Kept @neongate-ai/orbz/browser as the browser entry that registers <orb-z>.
  • Kept @neongate-ai/orbz/standalone as the self-registering standalone browser bundle for CDN and direct-script integrations.
  • Kept custom-element class creation and registration guarded for server-rendered environments.
  • Kept defineOrbz() idempotent when multiple bundles or microfrontends attempt to register the element.
  • Renamed the advanced element-class creator to orbzElementClassFactory().
  • Moved browser registration side effects into the explicit browser entry instead of evaluating them from the package root.

Build, packaging, and internal organization

  • Added a prepack lifecycle that runs strict TypeScript validation and a fresh package build before npm pack or npm publish.
  • Restricted the npm package payload to generated dist artifacts plus the package files npm includes automatically, such as package.json, README.md, and LICENSE.
  • Kept documentation, examples, internal agent instructions, source files, and workspace configuration outside the npm tarball.
  • Added explicit .ts extensions to shared tsdown configuration imports so the build works with Node’s native TypeScript configuration loading.
  • Reorganized internal source modules around core, element, factories, ports, services, and talk.
  • Renamed the former voice source area to talk.
  • Consolidated related type declarations into .types.ts modules.
  • Removed redundant orbz prefixes from internal source filenames while retaining the public Orbz* symbol names.
  • Flattened unnecessary single-file source directories.
  • Removed the React runtime implementation from the package source entirely.

Examples and documentation

  • Added synchronized Vanilla, React, Vue, Svelte, Angular, and Next.js showcases built around the same <orb-z> interface.
  • Updated example reset controls to reset state without remounting the custom element.
  • Replaced the original VitePress scaffold with a Nextra documentation site.
  • Added getting-started documentation for native, framework, and CDN integrations.
  • Added concepts documentation for philosophy, states, appearance, motion, and accessibility.
  • Added framework, microfrontend, SSR, and voice-assistant guides.
  • Added complete element and package-export API references.
  • Added examples, troubleshooting, and migration guidance.
  • Established orbz.site  as the main documentation destination.
  • Established framework-specific subdomains as deployment destinations for the synchronized examples.

View 0.2.0 on npm

Migrating from 0.1.0

Replace the React adapter

Remove imports from the former React entry:

import { Orbz } from "@neongate-ai/orbz/react";
 
export function Assistant() {
  return <Orbz state="idle" />;
}

Register the browser entry and render the native custom element instead:

import "@neongate-ai/orbz/browser";
 
export function Assistant() {
  return <orb-z state="idle"></orb-z>;
}

Add a local JSX intrinsic-element declaration when TypeScript does not yet recognize orb-z. This declaration provides compile-time awareness only; it does not create a React component.

Replace the color API

Remove the former colors object:

orb.colors = {
  primary: "#7C3AED",
  secondary: "#22D3EE"
};

Use a built-in preset:

<orb-z preset="neongate"></orb-z>

Or use the five supported custom-color attributes without a preset:

<orb-z
  color-primary="#7C3AED"
  color-secondary="#22D3EE"
  color-accent="#F472B6"
  color-highlight="#FDE68A"
  color-background="#09090B"
></orb-z>

Do not combine an explicit preset with custom-color attributes unless the preset is intentionally expected to take precedence.

Remove external Shadow DOM customization

Remove integrations that depend on:

  • element.shadowRoot;
  • internal selectors;
  • ::part(...);
  • public --orbz-* CSS variables;
  • assumptions about internal DOM structure.

Use the documented attributes, properties, methods, ports, adapters, events, and exports instead.

Register the custom element explicitly

Use the browser entry when the current module should register <orb-z>:

import "@neongate-ai/orbz/browser";

Use the package root when importing types or utilities without browser side effects:

import {
  defineOrbz,
  type OrbzElement
} from "@neongate-ai/orbz";

Call defineOrbz() explicitly when registration needs to be controlled by the host application.

Opt in to speech

Versions 0.2.0 and 0.3.0 scheduled a talk flow after the first connected render. Version 0.3.1 removed that behavior: current applications assign voiceEngine, talkFlow, and intelligence, then explicitly call startTalking() after the visitor opts in.

import '@neongate-ai/orbz/browser'
import {
  OpenAISpeechAdapter,
  type OrbzElement
} from "@neongate-ai/orbz";
 
const orb = document.createElement("orb-z") as OrbzElement;
 
orb.voiceEngine = new OpenAISpeechAdapter({
  endpoint: "/api/orbz/speech"
});
 
document.body.append(orb);
 
const startVoiceButton = document.querySelector<HTMLButtonElement>("[data-start-voice]");
 
startVoiceButton?.addEventListener("click", async () => {
  await orb.startTalking();
});

If a browser rejects requested audio despite the explicit control, Orbz retries that requested flow on the next interaction.

0.1.0 — Initial public release

  • Published the first @neongate-ai/orbz package on npm.
  • Established Orbz as a framework-agnostic AI voice visual built with Web Components.
  • Shipped the five assistant states: idle, listening, thinking, speaking, and asleep.
  • Shipped configurable size, motion speed, pause and play controls, animation restart, and reduced-motion profiles.
  • Added SSR-safe custom-element creation and registration.
  • Added the browser registration entry and standalone browser bundle.
  • Added the initial React adapter.
  • Exposed color overrides through a JavaScript colors property.
  • Exposed public --orbz-* CSS variables.
  • Used open Shadow DOM and named Shadow Parts for external customization.

View 0.1.0 on npm

Versioning expectations

The documented attributes, properties, methods, events, ports, adapters, types, constants, and package exports are public API.

Starting with Orbz 1.0.0:

  • incompatible public API changes increment the major version;
  • backward-compatible capabilities increment the minor version;
  • backward-compatible fixes increment the patch version.

Examples, documentation, deployment configuration, and internal source organization may evolve without creating additional public runtime contracts. They demonstrate and explain the published package but do not become part of the npm API unless they are explicitly exported or included in the documented component contract.

Last updated on
Troubleshooting