v0.4.0GitHub—

docs / guides / accessibility

Accessibility and performance

Keep content available and treat motion as a progressive enhancement.

##Content first

Write complete semantic HTML before loading Swarm Troopers. The overlay canvas is decorative and marked aria-hidden; it never intercepts the pointer. Text remains in the DOM, while visual reveals use opacity and clip-path without moving the underlying layout.

Do not treat DOM presence as a complete accessibility audit. Swarm Troopers temporarily makes pending elements transparent and non-pointer-interactive. Keep essential navigation, form controls, critical calls to action, and content needed for an immediate task outside the effect. Auto mode leaves controls and their enclosing boxes visible. A focusin handler immediately settles an explicitly annotated focused task and its dependencies. Printing settles reveals and hides decorative UI. The native document must remain useful with JavaScript disabled.

##Reader preferences

Without a saved quality choice, reduced motion selects Off at construction. A saved explicit reader choice takes precedence. Always offer the controls when motion is decorative. Test Off and reduced motion separately: both should leave content visible without an overlay, and the choice should survive a reload when storage is allowed.

In auto quality with no saved manual choice, a running instance follows later system motion changes without persisting them. Explicit reader choices take precedence. Turning motion back on does not replay completed content.

##Loading and Largest Contentful Paint

Hiding a hero until Swarm Troopers reveals it can postpone Largest Contentful Paint. Exclude that hero with data-swarmtroopers-skip, or limit Swarm Troopers to a dedicated demonstration below it. Avoid scroll-triggered hiding for content that must be visible on first paint.

The preload snippet avoids flashing content before the animation starts, but that tradeoff is deliberate. It is opt-in, belongs in head, uses explicit data-swarmtroopers-preload markers, and needs its safety timer. It must not hide excluded or critical content. Never replace it with a permanent CSS rule that hides the page when the script fails.

##Rendering budget

Swarm Troopers uses one fixed canvas. Full mode caps device pixel ratio at 1.5; Light caps it at 1. The loop sleeps when nothing moves and pauses updates in background tabs. Layout rectangles and token lookups are cached and invalidated when necessary.

Use a focused root, a modest worker count, and the task limit on large pages. The core has no raster completion assets; the optional full profile includes them. Decode is skipped for disabled finales and inspection-only instances; measure your actual built output with npm run size rather than assuming a historical size. Profile the real page on target devices; desktop emulation cannot establish performance on a physical phone.

##Content Security Policy

Serve the library from a domain allowed by script-src. Give inline initialization and the preload script/style valid nonces or hashes, or use external initialization and omit the preload. The self-hosted script path is under your control.

Styles normally use constructable stylesheets. When those are unavailable, Swarm Troopers falls back to a style element, which a strict style-src policy can block. If neither stylesheet path is available, Swarm Troopers uses visible quality Off instead of enrolling hidden tasks. The preload style also needs to satisfy that policy.

The high-five artwork and dock mark are embedded data: image URLs. Allow data: in img-src if those images should display. When decoding is blocked or fails, the finale uses its vector fallback and the dock keeps its text label. No remote image host is required by the library.

##Existing animations and browser checks

Choose one owner for an element’s visibility and clip-path. Auto mode skips initially invisible elements, but two systems controlling the same visible element can still conflict. Remove the other reveal animation or exclude the element from Swarm Troopers.

The implementation uses Canvas 2D, Path2D, CSS clip-path, generators, and modern observer APIs. An absent IntersectionObserver makes tasks count as visible; ResizeObserver is optional. Validate your supported browser matrix, fonts, nested scrolling, touch behavior, and strict CSP on the site itself. Shadow-tree roots and transformed documents that invalidate viewport coordinates fall back to visible quality Off with a diagnostic. Overlapping instance roots are refused. Portability and real React Strict Mode/navigation fixtures are tested in Chrome, Firefox and Playwright WebKit. The full landing/demo suite runs in Chrome. Physical devices, Safari itself, assistive technologies and other framework runtimes still require validation. Include 320px layouts, no-JavaScript rendering, mid-build destroy(), and route changes in your checks.