#MarkStageProvider

Shares one animation between every character that looks the same.

import { MarkStageProvider, StagedMark, COLOR_IDS } from '@aora-bot/react';

export default function Demo() {
  return (
    <MarkStageProvider>
      <div className="site-demo">
        {Array.from({ length: 44 }, (_, i) => (
          <StagedMark
            key={i}
            shape="pebble"
            state={i % 3 === 0 ? 'happy' : i % 3 === 1 ? 'thinking' : 'idle'}
            color={COLOR_IDS[i % COLOR_IDS.length]}
            sizePx={34}
          />
        ))}
      </div>
    </MarkStageProvider>
  );
}

Forty-four characters above. Three running engines.

#How it works

The provider keeps a hidden character for each distinct appearance and every visible instance becomes <use href="#…"> pointing at it. The browser reuses whatever the source is rendering this frame, so a mirror costs one element and no animation work.

#Appearance is shape, state, face and pen

The key is shape, state, face style, nose, line weight, emphasis and pause. Colour and size are excluded, deliberately. A mark with a hud leaves the stage altogether and runs its own engine: a dial is a live readout, and keying on its value would mint a new source every tick.

Face style and nose are included, because a mirror shows exactly what its source draws: a line-face mark cannot borrow a source with another face. Two line-face blobs with different noses are two sources. A nose on the default face is moot, so it is dropped from the key and does not split the stage.

Ink is a CSS custom property, and inherited custom properties resolve at the point of use rather than the point of definition — so every mirror can be a different ink while sharing one animation. Size is set on the wrapper element, so it varies freely too.

This is the whole design, and it is easy to get wrong. Keying the stage by agent identity reads naturally, because an agent id is what an application has a list of. But it shares nothing: every agent is unique by definition, so fifty agents would mean fifty engines. Keying by appearance means fifty agents who are all idle blobs cost exactly one.

#Capping

maxSources limits concurrent engines, defaulting to 36. Past the cap, claims are still honoured but no new source is hosted, so the page degrades by leaving some characters still rather than by slowing all of them down.

#Claims are coalesced

An IntersectionObserver firing during a scroll can produce dozens of claims in a single frame. Committing each one separately would re-render the provider dozens of times at exactly the moment the main thread is busiest, so claims are batched into one update per frame.

#Source size

Hidden sources render at 96 pixels rather than collapsing to nothing. Anything that measures its own element reads the source's box, not the mirror's, so a source shrunk to a few pixels would make every mirror behave as though it were tiny.

#Outside a provider

StagedMark falls back to its own CharacterMark, so a component using it works in isolation — in a test, or in a documentation example — without a provider in the tree.

#Style and ref

style is applied last, so a --aora-fg set there overrides the ink derived from color. That is the only way to hand a mark an animatable custom property instead of a fixed ink — the group activity ink transition relies on it.

ref exposes the same CharacterHandle as CharacterMark, but only when the mark owns an engine — which, for a StagedMark, means outside a provider. Inside one every mark is a mirror of the stage's hidden source; it shares its animation with every other mark of the same appearance and so cannot move alone. The handle is simply never attached in that case, and usePokeCycle reports back that there was nothing to poke.

import { useRef, type CSSProperties } from 'react';
import { MarkStageProvider, StagedMark, type CharacterHandle } from '@aora-bot/react';

export default function Demo() {
  const own = useRef<CharacterHandle>(null);
  const mirror = useRef<CharacterHandle>(null);
  return (
    <div className="site-demo site-demo--center">
      <MarkStageProvider>
        <StagedMark
          shape="hex"
          color="cyan"
          state="happy"
          sizePx={72}
          style={{ '--aora-fg': '#0ea5e9' } as CSSProperties}
        />
        <StagedMark ref={mirror} shape="hex" color="cyan" state="happy" sizePx={72} />
      </MarkStageProvider>
      <StagedMark ref={own} shape="hex" color="cyan" state="happy" sizePx={72} />
      <button className="site-btn" onClick={() => (mirror.current ?? own.current)?.bounce()}>
        bounce
      </button>
    </div>
  );
}

The first mark restyles its ink through style; the second is a mirror whose handle stays null, so the button falls through to the third, which runs its own engine outside the provider. To move a whole roster on purpose, go through the shared mark commands rather than individual refs.

#API

#StagedMark

#Next

• Performance — how to render hundreds of characters
• Mark commands — hold, release, poke, spin