v0.4.0GitHub—

docs / reference / extending

Custom tools and plugins

Add a purposeful gesture or supply annotations from your own system.

##Register a generator tool

A tool is a synchronous generator. Each yield waits for the next frame and receives elapsed seconds adjusted by Swarm Troopers’ pacing. Register the tool before creating the instance or collecting its annotated elements.

javascript
import { create, defineTool } from 'swarmtroopers';

defineTool('spotlight', function* (c) {
  c.shape('cross');
  yield* c.move(() => {
    const r = c.rect();
    return { x: r.x + r.w / 2, y: r.y + r.h / 2 };
  }, { width: 40 });
  yield* c.click();
  c.reveal.pop();
  c.shape('arrow');
});

create({ root: 'main' });

html
<div data-swarmtroopers="spotlight">This element uses the registered gesture.</div>

When a generator returns, Swarm Troopers completes the task and restores its prior clip-path value and priority. Tool factories and generator steps are isolated: a failed task is revealed with a diagnostic. Cancellation failures cannot interrupt host cleanup. An unrecoverable renderer failure destroys the instance and restores the host. Use try/finally to release held pointer state and close long-lived annotations when a generator is interrupted.

##ToolContext reference

MemberPurpose
el, task, agentThe element, current Task, and Agent for this gesture. Treat scheduler state as read-only context.
randomSeeded random helper with next(), range(lo, hi), chance(p), and normal(mean?, sd?).
rect()Current element rectangle { x, y, w, h } in document CSS pixels.
sourceRect()Previous repeat item’s rectangle, or null.
move(pointOrFunction, options?)Movement generator. Options: target width, drag boolean, and onStep callback. A function tracks a moving destination.
wait(seconds)Wait generator. Use yield*.
click()Press-feedback generator. It does not dispatch a real click to your page.
shape(value)Choose arrow, beam, cross, stamp, or hand.
hold(boolean)Set the held-down pointer appearance.
dim(boolean)Dim the pointer, as when typing.
mark(init)Create a canvas annotation. Its returned done() starts removal.
label()Ask plugins for a label, with size fallback. Construction labels must be enabled.
text()Measured TextGeo or null: text sequence, pieces, lines, bands, dimensions, and padding.
reveal.begin(clip?)Remove the pending class, optionally setting an initial CSS clip-path.
reveal.clip(value)Update the element’s clip-path.
reveal.end()Restore the original inline clip-path.
reveal.pop()Reveal immediately with the short completion fade and mark the task done.

ToolGen is Generator<void, void, number>. A Point has x and y; a Rect additionally has w and h. Do not replace a generator with an async function or use timers to mutate an element after the task has finished.

##AnnotationInit

Every annotation has a required kind, optional color, optional ttl in seconds, and optional label. Color defaults to the agent’s color. Lifetime defaults to infinity, so explicitly call the returned annotation’s done() for temporary marks.

KindGeometry callbacks
drag, ghost, select, zonerect: () => Rect; select can display a label.
line, careta: () => Point and b: () => Point.
ripple, sparka: () => Point; use a finite lifetime for the effect.

Callbacks keep geometry aligned with scrolling and moving content. The public configuration accepts geometry callbacks; the returned annotation’s age, fade state, and closed flag belong to the renderer.

##SwarmTroopersPlugin

typescript
interface SwarmTroopersPlugin {
  name: string;
  setup?(swarmtroopers: SwarmTroopers): void;
  label?(el: SwarmTroopersElement, tool: string): string | null | undefined;
  invalidate?(): void;
}

javascript
const componentNames = {
  name: 'component-names',
  label(element) {
    return element.getAttribute('data-component');
  },
};

create({
  root: 'main', auto: true, inspect: true,
  plugins: [componentNames, 'tokens'],
});

setup runs during construction before initial collection. Label providers are checked in order; the first nonempty label wins. Returning null or undefined allows the next provider or default label. invalidate clears plugin caches when Swarm Troopers invalidates geometry. A setup function may return a cleanup callback, called on destroy and initialization rollback. Cleanup and invalidation exceptions are isolated. Register DOM additions with swarmtroopers.own(); use the setup cleanup to release external subscriptions.