包导出项

Orbz 将纯 API 访问、带环境保护的浏览器注册和独立浏览器包分开。所有框架最终都渲染原生 <orb-z> 元素。

入口对照表

导入路径	提供的内容	副作用
`@neongate-ai/orbz`	原生元素、对话运行时类型、常量、预设、规范化辅助函数、`orbzElementClassFactory()` 和 `defineOrbz()`	不注册标签
`@neongate-ai/orbz/browser`	主入口提供的全部内容	调用 `defineOrbz()`
`@neongate-ai/orbz/react-types`	为原生 `<orb-z>` 标签提供可选的 React JSX 类型扩展	无
`@neongate-ai/orbz/standalone`	浏览器入口的独立浏览器构建	调用 `defineOrbz()`
`@neongate-ai/orbz/index.css`	嵌入封闭 Shadow Root 的同一份源样式表	无
`@neongate-ai/orbz/package.json`	已发布包的元数据	无

包清单将浏览器入口和 standalone 入口标记为具有副作用，以便打包工具保留其注册调用。

react-types 不包含 React 组件或运行时适配器。仅在需要让 JSX 识别 <orb-z> 的 React 或 Next.js TypeScript 项目中导入它。

主入口

使用主入口进行显式注册，并获取可复用的领域类型：


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

仅导入主模块不会注册 orb-z。当页面需要将标签升级为自定义元素时，请调用 defineOrbz() 或导入 /browser。

常量

导出项	含义
`ORBZ_TAG_NAME`	字符串 `"orb-z"`
`ORBZ_OBSERVED_ATTRIBUTES`	具有响应性的原生属性名称
`ORBZ_STATES`	所有受支持的助手状态
`ORBZ_REDUCED_MOTION_MODES`	`system`、`always` 和 `never`
`ORBZ_PRESET_NAMES`	六个规范预设名称，第一个为 `neongate`
`ORBZ_PRESETS`	每个规范预设的冻结颜色值；保留一个已弃用、不可枚举且源于账户名称的别名
`ORBZ_COLOR_ATTRIBUTES`	颜色键到原生属性名称的映射
`ORBZ_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`	Neongate 预设的颜色
`config`	公开包常量的冻结命名空间，包括 `config.ORBZ_STATES`
`talk`	冻结的空兼容对象（`{}`）；由宿主定义对话步骤
`DEFAULT_TALK_FLOW`	冻结的空数组（`[]`）；不含内置问候语、角色或对话

这些数组和预设记录可用于生成经过验证的控件，无需复制包所接受的值。


import { DEFAULT_ORBZ_PRESET, 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) {
  const label = preset === DEFAULT_ORBZ_PRESET ? "Neongate" : preset;
  presetSelect.add(new Option(label, preset));
}

类型

导出项	结构
`OrbzState`	五个状态名称组成的联合类型
`OrbzReducedMotion`	`"system" \| "always" \| "never"`
`OrbzPresetName`	六个规范名称与一个已弃用、源于账户名称的输入别名组成的联合类型
`OrbzSize`	`number \| string`
`OrbzColors`	必需的字符串 `primary`、`secondary`、`accent`、`highlight` 和 `background`
`OrbzColorOverrides`	部分 `OrbzColors`
`OrbzBaseOptions`	状态、尺寸、速度、暂停、悬浮阴影和减少动态效果选项
`OrbzPresetOptions`	预设模式；自定义颜色键为 `never`
`OrbzCustomColorOptions`	自定义颜色模式；`preset` 为 `never`
`OrbzColorSelection`	预设模式与自定义颜色模式的联合类型
`OrbzOptions`	基础选项与颜色选择联合类型的组合
`OrbzElement`	原生元素属性与播放方法
`OrbzElementConstructor`	带类型的自定义元素构造函数
`OrbzTalkStep`	带类型的确定性对话步骤或由智能接口支持的对话步骤
`OrbzTalkContext`	对话执行器捕获并保存在内存中的值
`OrbzVoiceOptions`	可选的语音引擎、对话流程与智能接口配置
`OrbzVoiceEnginePort`	由实现方提供的语音输出契约
`OrbzIntelligencePort`	可选的非确定性回应契约
`WebSpeechAdapterOptions`	语言区域、首选语音、语速、音调、音量与语音加载选项
`OpenAISpeechAdapterOptions`	安全端点以及 OpenAI 语音模型、声音、指令与格式选项

语音适配器

导出项	用途
`WebSpeechAdapter`	明确选择语言区域和声音的浏览器语音合成
`OpenAISpeechAdapter`	通过实现方控制的安全端点提供 OpenAI 品质的语音

OpenAISpeechAdapter 默认使用 gpt-4o-mini-tts、marin 和 MP3。OpenAI API 密钥保留在端点一侧，绝不会包含在浏览器代码中。

验证与规范化函数

导出项	用途
`isOrbzState()`	检查受支持状态的类型守卫
`isOrbzPresetName()`	接受规范名称及一个已弃用、源于账户名称的别名的类型守卫
`isOrbzReducedMotion()`	检查减少动态效果值的类型守卫
`normalizeOrbzState()`	不受支持的输入变为 `idle`
`normalizeOrbzPreset()`	将已弃用的账户名称输入规范化为 `neongate`；不受支持的输入变为 `DEFAULT_ORBZ_PRESET`
`normalizeOrbzReducedMotion()`	不受支持的输入变为 `system`
`normalizeOrbzSize()`	数字转换为像素；无效数字或空输入变为 `16rem`
`normalizeOrbzSpeed()`	非正数或非有限值变为 `1`
`mergeOrbzColors()`	将有效且非空的覆盖值合并到基础配色中

在存储不可信的配置之前，先将其规范化：


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

注册辅助函数

defineOrbz() 是常规的显式注册 API。它可安全用于 SSR，且具有幂等性：


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

orbzElementClassFactory() 仅在 globalThis.HTMLElement 存在时创建并缓存该类。它供高级集成使用；大多数应用应调用 defineOrbz()。


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

当 DOM 不可用时，这两个辅助函数都不会求值 HTMLElement 的子类。