docs / getting started / markup
Markup and scanning
Choose what Swarm Troopers builds without changing the content or its layout.
##Automatic mode
const swarmtroopers = create({ root: 'main', auto: true });Auto mode examines computed styles. Text-only runs become typing tasks; backgrounds, borders, shadows, and media become frames; thin rules become drawing tasks. Similar siblings can form a repeat group. Very large containers are left in place while their contents are scanned, avoiding a long drag across an entire screen.
Auto mode skips fixed or sticky elements, invisible content, excluded elements, and content fully outside the horizontal viewport. Interactive controls and their enclosing task containers remain visible in auto mode, unless a data-swarmtroopers value forces a tool on them; a negative tabindex is a focus target, not a control. Discovery is bounded by maxTasks and a budget of style reads on candidates that are not enrolled yet (annotated mode walks unannotated elements without reading them); overflow is left untouched. Content that is hidden when scanning begins is not automatically revisited when another animation reveals it; call refresh() after it becomes eligible, or give one animation ownership of it.
##Annotated mode
Without auto: true, only descendants matching selector are selected. The default selector is [data-swarmtroopers]. An annotation can also override automatic classification.
<main>
<h1 data-swarmtroopers="type">A precise introduction.</h1>
<article data-swarmtroopers="frame">A card in its original place.</article>
<hr data-swarmtroopers="rule">
<p data-swarmtroopers="instant">Show this without an agent gesture.</p>
</main>| Value | Behavior |
|---|---|
Empty or auto | Classify this element from computed styles. |
type | Reveal text with a caret and a typing rhythm. |
frame | Drag a frame to reveal a box, image, or field. |
rule | Trace a horizontal or vertical divider. |
stamp | Copy from a preceding repeat item; without a source, use a frame. |
instant | Reveal without a worker gesture. |
repeat | Treat children as repeated items; eligible later frames become stamps. |
scan | Turn on automatic scanning within this subtree. |
skip | Exclude the element and its descendants. |
| A registered custom name | Use the tool registered with defineTool(). Unknown tool names fall back to framing. |
##Repeated items and mixed modes
<section data-swarmtroopers="scan">
<h2>This section is scanned automatically.</h2>
<ul data-swarmtroopers="repeat">
<li>First item</li>
<li>Second item</li>
<li>Third item</li>
</ul>
</section>
<nav data-swarmtroopers-skip>Persistent navigation stays available.</nav>repeat preserves the actual children. It does not clone DOM nodes. Auto-detected repetition groups siblings by tag and classes; use explicit annotations when the structure is unusual. The scanner ignores its own overlay and controls.
##Name and scope each section
The outermost semantic section under the root owns its squad. Swarm Troopers recognizes section, header, footer, article, aside, nav, and [data-swarmtroopers-section]. Without section markup, it uses viewport-sized document bands.
<main>
<div data-swarmtroopers-section="Our work">
<h2 data-swarmtroopers="type">Selected projects</h2>
</div>
</main>Section names prefer data-swarmtroopers-section, then aria-label, a usable ID, the first heading, or the section role. Put a naming attribute on the section, not on the animated root itself.
##Keep important content immediately visible
Use data-swarmtroopers-skip on hero content when Largest Contentful Paint matters, on essential controls, and on any element owned by another animation. This exclusion works in both modes and excludes the subtree. Manual annotations can select fixed or sticky content that auto mode would reject; test those explicitly rather than assuming they follow normal document coordinates.