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.
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' });<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
| Member | Purpose |
|---|---|
el, task, agent | The element, current Task, and Agent for this gesture. Treat scheduler state as read-only context. |
random | Seeded 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.
| Kind | Geometry callbacks |
|---|---|
drag, ghost, select, zone | rect: () => Rect; select can display a label. |
line, caret | a: () => Point and b: () => Point. |
ripple, spark | a: () => 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
interface SwarmTroopersPlugin {
name: string;
setup?(swarmtroopers: SwarmTroopers): void;
label?(el: SwarmTroopersElement, tool: string): string | null | undefined;
invalidate?(): void;
}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.