v0.4.0GitHub—

docs / guides / controls

Quality and controls

Respect reader preferences and expose a clear Full, Light, Off choice.

##Add the built-in controls

javascript
import { create, controls } from 'swarmtroopers';

const swarmtroopers = create({ root: 'main', auto: true });
const panel = controls(swarmtroopers, {
  position: 'bottom-right',
  labels: { title: 'Swarm Troopers', full: 'Full', light: 'Light', off: 'Off' },
});

The helper returns an HTMLElement with three pressed-state buttons. It reads the host theme, synchronizes when quality changes, and registers the panel with swarmtroopers.own(), so destroy() removes it.

ControlsOptions fieldDefaultMeaning
positionbottom-leftbottom-left, bottom-right, top-left, or top-right.
labelsBuild / Full / Light / OffPartial overrides of title, full, light, and off. Labels are not automatically translated.
containerdocument.bodyDOM parent for the panel. Its built-in positioning remains fixed.

The canvas zIndex option does not change the controls’ CSS stacking level, which is 2147483001. Adapt host CSS if your application requires a different control placement.

##Initial quality resolution

  1. A valid saved full, light, or off value under storageKey + ':quality' wins.
  2. Without that preference, prefers-reduced-motion: reduce selects Off.
  3. Then an explicit quality other than Auto is used.
  4. Auto selects Light for data-saving connections, four or fewer reported CPU cores, or four or fewer GB of reported device memory. Otherwise it selects Full.

Viewport width alone does not choose Light. Narrow screens separately use smaller pointers and shorter patience. Later system motion changes are resolved the same way while the page is open, when there is no saved manual choice. Explicit reader choices retain precedence.

BudgetWorkersCanvas densityResult
Full6 by default, plus orchestratorDevice pixel ratio capped at 1.5The complete build and inspection experience.
LightAt most 3, plus orchestratorCapped at 1Fewer workers and faster gestures.
OffNo build overlayNo canvasThe existing page is immediately available.

##Changing quality

javascript
swarmtroopers.setQuality('light');
swarmtroopers.setQuality('off');   // Completes pending work and removes the canvas.
swarmtroopers.setQuality('full');  // Does not replay content already completed.

The choice persists across reloads when localStorage is available. If storage is blocked, the page still works but the choice is not remembered. Do not continually overwrite a reader’s choice during navigation.

##Session scope and replay

once: 'session' saves completion under storageKey + ':seen'. It is not automatically keyed by URL. Use a page-specific prefix when different pages should each build once; this also gives each prefix its own quality preference.

javascript
const swarmtroopers = create({
  root: 'main', auto: true,
  once: 'session',
  storageKey: 'swarmtroopers:portfolio',
});

For a Replay button, destroy the previous instance and create another with once: false. Keep your chosen configuration in application code rather than accessing internal settings.