docs / reference / api
JavaScript API
Create, control, inspect, and clean up a Swarm Troopers instance.
##Package exports
import {
SwarmTroopers, create, controls, tokens, defineTool, version,
} from 'swarmtroopers';create(options?) returns a new SwarmTroopers; new SwarmTroopers(options) is equivalent. controls() returns a control element, tokens() returns a plugin, and defineTool(name, generator) registers a tool for subsequent tasks. version is the built package version. The IIFE exposes these on window.SwarmTroopers.
The separate swarmtroopers/element entry exports SwarmTroopersOverlayElement and defineElement, and registers the swarmtroopers-overlay tag as a side effect. The IIFE includes that registration; the main ES module entry does not.
##Lifecycle methods
| Method | Result and behavior |
|---|---|
start(): void | Starts a manual or not-yet-started instance. Repeated calls are ignored. |
pause(): void | Pauses build updates without revealing pending content. |
resume(): void | Resumes a paused instance and wakes rendering. |
finish(): void | Reveals existing tasks, clears agents and annotations, and skips the finale. Completion can emit done. |
refresh(): void | Reconciles removed descendants, scans for new eligible ones, and invalidates geometry. It does not replay known elements or detect in-place text changes automatically. |
setQuality(q): void | q is full, light, or off; saves the preference and updates the budget. Off finishes and removes the canvas. |
destroy(): void | Cancels rendering and tools; removes the overlay, owned elements, observers, listeners, and pending classes. Idempotent. |
own(element): void | Registers a DOM element to be removed with the instance. Used by built-in controls. |
on(type, handler): () => void | Registers an event listener and returns an unsubscribe function. |
off(type, handler): void | Removes that handler for the event type. |
destroy() is final for that instance. Replay by creating a new one; neither start() nor changing Off back to Full replays completed content.
##Read-only properties
swarmtroopers.root; // Resolved root Element
swarmtroopers.quality; // 'full' | 'light' | 'off'
swarmtroopers.stats; // { tasks, done, agents, active }
swarmtroopers.theme; // { background, text, rgb, palette }stats.tasks is the number of collected tasks; done counts completed tasks, agents counts agents spawned during the instance, and active is the current agent count. These are snapshots, not DOM inventories. An instance created Off without inspection may not collect tasks at all.
theme.background and theme.text are resolved colors, rgb is the background RGB tuple, and palette is the color list used for agent identities and section survey outlines. Use these values when styling custom controls.
##Events and timing
| Event | Payload | When |
|---|---|---|
start | { tasks: number } | A build starts. Immediate startup occurs inside construction, before a later listener can subscribe. |
task | { el: SwarmTroopersElement, tool: string } | A task completes, including tasks revealed immediately. |
done | { tasks: number, agents: number, duration: number } | The instance completes its build; duration is elapsed seconds. This does not wait for the finale to disappear. |
quality | { quality: Quality } | A quality change takes effect. Re-selecting the current value does not emit a change. |
const swarmtroopers = create({ root: 'main', auto: true, trigger: 'manual' });
const unsubscribe = swarmtroopers.on('done', ({ tasks, duration }) => {
console.log(tasks, 'elements completed in', duration, 'seconds');
});
swarmtroopers.on('start', ({ tasks }) => console.log('Starting', tasks));
swarmtroopers.start();
// Keep unsubscribe for your view's teardown callback.When the view unmounts, call unsubscribe() to remove this listener and swarmtroopers.destroy() to clean up the instance. Keep that teardown separate from the startup code above.
Use manual startup when you must observe the first start event. Instances initially Off or already skipped by once do not perform a normal build. Event handler exceptions are logged without preventing other listeners from running.
##TypeScript surface
The package exports SwarmTroopersOptions, SwarmTroopersStats, SwarmTroopersEventMap, SwarmTroopersElement, SwarmTroopersPlugin, ControlsOptions, TokensOptions, ChatOptions, ChatLines, ChatKey, Quality, QualitySetting, Trigger, CursorShape, PaletteSpec, Point, Rect, Tool, ToolContext, ToolGen, Agent, Task, AnnotationInit, and AnnotationKind. DOM-facing APIs require DOM types in your TypeScript application.