@vikast908/core

Shared foundation for OrbUX loaders.

This package provides the agent-state model, base custom element classes, motion helpers, and theme token plumbing used by @vikast908/loaders.

Install

npm install @vikast908/[email protected]

Published on npm as @vikast908/core (Plan A: this is the permanent public scope). Prefer 0.2.2 or newer. In this monorepo after pnpm install and pnpm --filter @vikast908/core build, the same import path works via workspace linking.

Use

import { OrbuxElement, Canvas2DElement, ShaderElement } from '@vikast908/core';
import { AGENT_STATES, type AgentState } from '@vikast908/core';

The agent state model

Eight transport-agnostic states: idle, thinking, streaming, tool-calling, waiting, done, error, and cancelled. done, error, and cancelled are the terminal outcomes. cancelled is a user-initiated stop (a Stop button or aborted request), rendered as a neutral halt rather than a success or failure cue.

Public surface

• OrbuxElement provides the shared contract: state, progress, size, speed, label, paused, quiet, show-label, pulse() / activity, a11y (with debounced live-region announcements), reduced-motion, offscreen/tab pause. Emits orbux:statechange ({ state, previous }) plus orbux:done / orbux:error / orbux:cancelled.
• Canvas2DElement: Canvas 2D base with DPR scaling and render loop
• ShaderElement: WebGL fragment-shader base with resize and CSS fallback
• AGENT_STATES / AgentState / ACTIVE_STATES / TERMINAL_STATES / STATE_LABELS: canonical agent lifecycle names and helpers
• Theme tokens (ORBUX_TOKENS, --orbux-*) and motion helpers (lerp, damp, clamp, noise1D, prefersReducedMotion)

Entry points

• .: the core classes, state model, tokens, and motion helpers above.

• ./adapters: optional, tree-shakeable mappings from popular agent protocols onto the state model, so a loader never ships adapter code it does not use:

  import { fromVercelStatus, fromAgUiEvent, fromOpenAiStream, bindAbort } from '@vikast908/core/adapters';
  
  loader.state = fromVercelStatus(status, { hasMessages: messages.length > 0 });
  
  const controller = new AbortController();
  bindAbort(loader, controller.signal); // abort → cancelled

The package is published from the packages/core workspace.