v0.4.0GitHub—

docs / reference / api

JavaScript API

Create, control, inspect, and clean up a Swarm Troopers instance.

##Package exports

javascript
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

MethodResult and behavior
start(): voidStarts a manual or not-yet-started instance. Repeated calls are ignored.
pause(): voidPauses build updates without revealing pending content.
resume(): voidResumes a paused instance and wakes rendering.
finish(): voidReveals existing tasks, clears agents and annotations, and skips the finale. Completion can emit done.
refresh(): voidReconciles 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): voidq is full, light, or off; saves the preference and updates the budget. Off finishes and removes the canvas.
destroy(): voidCancels rendering and tools; removes the overlay, owned elements, observers, listeners, and pending classes. Idempotent.
own(element): voidRegisters a DOM element to be removed with the instance. Used by built-in controls.
on(type, handler): () => voidRegisters an event listener and returns an unsubscribe function.
off(type, handler): voidRemoves 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

javascript
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

EventPayloadWhen
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.
javascript
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.