v0.4.0GitHub—

docs / guides / troubleshooting

Troubleshooting

Find why an effect is skipped, content stays hidden, or labels are missing.

##Nothing animates

  1. Check swarmtroopers.quality. A saved Off choice takes precedence over quality: 'full'.
  2. Check reduced motion and the once: 'session' completion key.
  3. Check selection: annotations are required unless auto: true.
  4. Confirm the script loaded, the root exists when you create Swarm Troopers, and manual instances receive start().
  5. Auto mode skips initially hidden, fixed, sticky, and off-canvas content. Confirm the element is eligible.
javascript
console.log(swarmtroopers.quality, swarmtroopers.stats);
console.log(localStorage.getItem('swarmtroopers:quality'));
console.log(sessionStorage.getItem('swarmtroopers:seen'));

For a controlled development reset, remove only the matching prefix’s keys and reload. Do not clear all of a visitor’s storage.

javascript
localStorage.removeItem('swarmtroopers:quality');
sessionStorage.removeItem('swarmtroopers:seen');
location.reload();

##Content stays hidden or flashes

Match the preload selector to the actual root, keep the 2.5-second safety timer, and inspect script errors. A missing explicit root is rejected before any content is hidden. Renderer startup failure leaves the page visible in Off mode. An annotated root itself is not a task: annotate descendants.

Call swarmtroopers.finish() to reveal collected tasks now, or swarmtroopers.destroy() to remove the instance’s effects and controls. If another library also hides the element, removing Swarm Troopers cannot override that library’s styles.

##Inspection or token labels are missing

Set inspect: true, finish the element’s build, and hover it with a mouse pointer. Construction labels additionally need labels: true and are suppressed on narrow screens. Quality Off has no overlay. Make sure tokens are declared on readable root stylesheets, use recognizable names, or pass a supported explicit source. No token match falls back to dimensions rather than inventing a token.

##New content or navigation is not built

Call refresh() after new elements mount and become visible. It removes disconnected tasks and discovers unknown eligible elements; it does not re-run known elements, detect in-place text updates, or update every construction option. Destroy and recreate after full view replacement, and keep one instance per view.

javascript
// After your application has mounted new content:
swarmtroopers.refresh();

// To replay an existing root:
swarmtroopers.destroy();
const replacement = create({ root: 'main', auto: true });

Returning from Off to Full also does not replay completed content. A page reloaded at a mid-page scroll position starts near the reader; content above can build when the reader scrolls back, while scrolled-past pending tasks can reveal immediately.

##There are duplicate cursors or control panels

Check effect cleanup, persistent layout mounts, route hooks, and whether both a JSON initializer and a custom element create an instance. Do not create Swarm Troopers on each render. Framework development remounts should destroy the first instance before creating the next. Swarm Troopers refuses overlapping roots rather than allowing two instances to own the same content.

##Images, script, or styles are blocked

Inspect the browser’s CSP messages. Allow your chosen script origin and required nonces or hashes. Embedded artwork needs img-src data:; if blocked it falls back, rather than downloading another image. ES modules also need their adjacent shared chunks. See the CSP guide.

##The text or language is unexpected

Check the document’s lang, locale, and chat.locale override. Bubble options can also change task and completion text. Quality-control labels are independently configurable; they do not use the chat locale. The custom element needs two or more comma-separated names to replace its pool.

##GitHub stars show an unavailable state

The site’s header badge is separate from the Swarm Troopers library. Before the public repository exists, the badge displays “Not published”; network errors, API limits, or malformed counts produce an unavailable state. That is not zero stars. The badge only reads metadata and never creates a repository or publishes the project.