v0.4.0GitHub—

docs / getting started / markup

Markup and scanning

Choose what Swarm Troopers builds without changing the content or its layout.

##Automatic mode

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

html
<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>

ValueBehavior
Empty or autoClassify this element from computed styles.
typeReveal text with a caret and a typing rhythm.
frameDrag a frame to reveal a box, image, or field.
ruleTrace a horizontal or vertical divider.
stampCopy from a preceding repeat item; without a source, use a frame.
instantReveal without a worker gesture.
repeatTreat children as repeated items; eligible later frames become stamps.
scanTurn on automatic scanning within this subtree.
skipExclude the element and its descendants.
A registered custom nameUse the tool registered with defineTool(). Unknown tool names fall back to framing.

##Repeated items and mixed modes

html
<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.

html
<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.