test: make controls fan-out risk observable

Add deterministic controls fan-out and cleanup coverage.

Add a manual stress path in the Expo example.

Docs now frame controls as short UI text playback.

Long or dense workloads stay something to measure in the target app.

Constraint: Keep public API, package metadata, and lockfile unchanged

Rejected: Wall-clock CI benchmark | flaky and not representative of device FPS

Rejected: Document token-level fan-out as contract | would freeze renderer internals

Confidence: high

Scope-risk: narrow

Directive: Keep descriptor listener counts test-only

Directive: Revisit tests if controls batching is introduced

Tested: pnpm run format:check; pnpm run lint; pnpm run typecheck

Tested: pnpm run test; pnpm run build; pnpm run example:build; git diff --check

Not-tested: Real-device release FPS profiling beyond manual example inspection

Author: saseungmin

README.md

@@ -94,6 +94,8 @@ export function Headline() {
 
 `controls` is a command channel, not a progress value. Use it for buttons, screen focus, onboarding steps, example replay controls, and coordinated title/subtitle replay.
 
+Performance note: controls are intended for short UI text such as titles, labels, and product copy. If you plan to animate long paragraphs, grapheme-split copy, or many rows at once, measure in your target app before treating that as a supported workload.
+
 Controlled progress is useful when text motion should follow a raw value outside the component, such as scroll position, gesture progress, or another Reanimated shared value. In that mode the app owns the exact progress and the text component only renders the current state.
 
 Basic controlled progress usage:

example/src/App.tsx

@@ -177,6 +177,78 @@ const ControlsPlaybackText = defineTextMotion()
   .motion({ kind: 'timing', options: { duration: 420 } })
   .component();
 
+const ControlsStressWordsText = defineTextMotion()
+  .split(words())
+  .layout(nativeText())
+  .timeline(stagger(0.018))
+  .effect(rise({ y: 8 }).and(fade()))
+  .motion({ kind: 'timing', options: { duration: 320 } })
+  .component();
+
+const ControlsStressGraphemeText = defineTextMotion()
+  .split(graphemes())
+  .layout(nativeText())
+  .timeline(stagger(0.006))
+  .effect(scale({ from: 0.94 }).and(fade()))
+  .motion({ kind: 'timing', options: { duration: 260 } })
+  .component();
+
+type ControlsStressCase = {
+  Component: TextMotionComponent;
+  id: string;
+  label: string;
+  tokenNote: string;
+} & (
+  | {
+      rows?: never;
+      text: string;
+    }
+  | {
+      rows: readonly string[];
+      text?: never;
+    }
+);
+
+const controlsStressCases: readonly ControlsStressCase[] = [
+  {
+    Component: ControlsStressWordsText,
+    id: 'normal-words',
+    label: 'Normal word case',
+    text: 'Manual stress checks repeated controls replay across a longer headline',
+    tokenNote: '10 word tokens',
+  },
+  {
+    Component: ControlsStressGraphemeText,
+    id: 'heavy-graphemes',
+    label: 'Heavy grapheme case',
+    text: 'MotionKit'.repeat(8),
+    tokenNote: '72 grapheme tokens',
+  },
+  {
+    Component: ControlsStressGraphemeText,
+    id: 'extreme-graphemes',
+    label: 'Extreme grapheme case',
+    text: 'ControlStress'.repeat(12),
+    tokenNote: '156 grapheme tokens',
+  },
+  {
+    Component: ControlsStressWordsText,
+    id: 'shared-rows',
+    label: 'Shared rows case',
+    rows: [
+      'Replay rows without remounting',
+      'Shared controls fan out here',
+      'Several labels move together',
+      'Each row owns playback',
+      'Stress the command path',
+      'Watch for visible jank',
+      'Keep tapping replay quickly',
+      'Rows should stay responsive',
+    ],
+    tokenNote: '8 components, 33 word tokens',
+  },
+];
+
 const demoGroups: readonly DemoGroup[] = [
   { id: 'presets', title: 'Presets' },
   { id: 'splitters', title: 'Splitters' },
@@ -337,6 +409,13 @@ const demos: readonly Demo[] = [
     text: 'Controls replay without remounting',
     title: 'Playback Controls',
   },
+  {
+    caption: 'manual fan-out check',
+    groupId: 'playback',
+    id: 'controls-stress',
+    text: 'Controls stress case',
+    title: 'Controls Stress',
+  },
   {
     caption: 'progress={sharedValue}',
     groupId: 'playback',
@@ -358,6 +437,10 @@ function nextDemoIndex(index: number): number {
   return (index + 1) % demos.length;
 }
 
+function nextStressCaseIndex(index: number): number {
+  return (index + 1) % controlsStressCases.length;
+}
+
 function ControlsPlaybackDemo({ replaySignal, text }: { replaySignal: number; text: string }) {
   const controls = useTextMotionControls();
   const replaySignalRef = useRef(replaySignal);
@@ -396,6 +479,81 @@ function ControlsPlaybackDemo({ replaySignal, text }: { replaySignal: number; te
   );
 }
 
+function ControlsStressDemo({ replaySignal }: { replaySignal: number }) {
+  const controls = useTextMotionControls();
+  const [caseIndex, setCaseIndex] = useState(0);
+  const replaySignalRef = useRef(replaySignal);
+  const stressCase = controlsStressCases[caseIndex] ?? controlsStressCases[0];
+  const StressText = stressCase.Component;
+  const stressRows = stressCase.rows;
+
+  useEffect(() => {
+    if (replaySignalRef.current === replaySignal) {
+      return;
+    }
+
+    replaySignalRef.current = replaySignal;
+    controls.replay();
+  }, [controls, replaySignal]);
+
+  return (
+    <View style={styles.controlledDemo}>
+      <View style={styles.stressMetaGroup}>
+        <Text style={styles.stressMeta}>{stressCase.label}</Text>
+        <Text style={styles.stressMetaDetail}>{stressCase.tokenNote}</Text>
+      </View>
+
+      {stressRows ? (
+        <View style={styles.stressRows}>
+          {stressRows.map((rowText) => (
+            <StressText
+              controls={controls}
+              key={rowText}
+              style={[styles.motionText, styles.stressRowText]}
+            >
+              {rowText}
+            </StressText>
+          ))}
+        </View>
+      ) : (
+        <StressText
+          controls={controls}
+          key={stressCase.id}
+          style={[styles.motionText, styles.stressMotionText]}
+        >
+          {stressCase.text}
+        </StressText>
+      )}
+
+      <View style={styles.progressControls}>
+        <Pressable
+          accessibilityRole="button"
+          onPress={controls.replay}
+          style={styles.progressButton}
+        >
+          <Text style={styles.progressButtonText}>Replay</Text>
+        </Pressable>
+        <Pressable
+          accessibilityRole="button"
+          onPress={controls.reset}
+          style={styles.progressButton}
+        >
+          <Text style={styles.progressButtonText}>Reset</Text>
+        </Pressable>
+        <Pressable
+          accessibilityRole="button"
+          onPress={() => {
+            setCaseIndex((index) => nextStressCaseIndex(index));
+          }}
+          style={styles.progressButton}
+        >
+          <Text style={styles.progressButtonText}>Case</Text>
+        </Pressable>
+      </View>
+    </View>
+  );
+}
+
 function ControlledProgressDemo({ replaySignal, text }: { replaySignal: number; text: string }) {
   const progress = useSharedValue(0);
   const replaySignalRef = useRef(replaySignal);
@@ -455,6 +613,7 @@ export default function App() {
   const demo = demos[demoIndex] ?? demos[0];
   const MotionText = demo.Component;
   const controlsDemoSelected = demo.id === 'playback-controls';
+  const controlsStressDemoSelected = demo.id === 'controls-stress';
   const controlledDemoSelected = demo.id === 'controlled-progress';
 
   return (
@@ -505,6 +664,8 @@ export default function App() {
           <View style={styles.motionFrame}>
             {controlsDemoSelected ? (
               <ControlsPlaybackDemo key={demo.id} replaySignal={replayKey} text={demo.text} />
+            ) : controlsStressDemoSelected ? (
+              <ControlsStressDemo key={demo.id} replaySignal={replayKey} />
             ) : controlledDemoSelected ? (
               <ControlledProgressDemo key={demo.id} replaySignal={replayKey} text={demo.text} />
             ) : (
@@ -714,6 +875,36 @@ const styles = StyleSheet.create({
   stageTitleGroup: {
     flex: 1,
   },
+  stressMeta: {
+    color: '#0f766e',
+    fontSize: 12,
+    fontWeight: '800',
+    lineHeight: 16,
+    textAlign: 'center',
+  },
+  stressMetaDetail: {
+    color: '#64748b',
+    fontSize: 12,
+    fontWeight: '700',
+    lineHeight: 16,
+    textAlign: 'center',
+  },
+  stressMetaGroup: {
+    alignItems: 'center',
+    gap: 2,
+  },
+  stressMotionText: {
+    fontSize: 18,
+    lineHeight: 25,
+  },
+  stressRows: {
+    gap: 4,
+    width: '100%',
+  },
+  stressRowText: {
+    fontSize: 15,
+    lineHeight: 20,
+  },
   summary: {
     color: '#475569',
     fontSize: 15,

packages/text-motion/README.ko.md

@@ -343,6 +343,10 @@ export function Headline() {
 
 Text Motion은 playback을 위한 context/provider API나 public component ref API를 제공하지 않습니다. 연결 관계가 JSX에서 보이도록 `controls={controls}`로 명시적으로 전달하세요.
 
+성능 관점에서 `controls`는 짧은 UI 텍스트에 맞춰 설계되어 있습니다. Title, label, 짧은 product sentence라면 playback work가 작고 예측 가능합니다. 긴 문단, 많은 row, 글자 단위로 쪼개는 grapheme split 텍스트에 쓰려면 example의 stress case를 확인하고 target device에서 먼저 측정하세요.
+
+큰 workload가 중요해지면 renderer 내부 구현은 바뀔 수 있습니다. 그래서 example stress case는 controls 구현 방식에 대한 public promise가 아니라 profiling aid로 보는 편이 안전합니다.
+
 ### Raw Progress
 
 Text motion이 앱이 이미 소유한 raw value를 따라가야 한다면 `progress`를 사용하세요.

packages/text-motion/README.md

@@ -343,6 +343,10 @@ One controls object may be passed to multiple text motion components. Commands b
 
 Text Motion intentionally does not provide a context/provider playback API or a public component ref API. Pass controls explicitly with `controls={controls}` so the connection is visible in JSX.
 
+Performance note: controls are designed for short UI text. For a title, label, or short product sentence, playback work should stay small and predictable. For long paragraphs, dense lists, or grapheme-split text with many characters, check the example stress case and measure on your target device before using it in production.
+
+The renderer internals may change as larger workloads become important, so treat the example stress case as a profiling aid rather than a public promise about how controls are implemented.
+
 ### Raw Progress
 
 Use `progress` when text motion should follow a raw value the app already owns.

packages/text-motion/src/__tests__/controls.test.tsx

@@ -51,6 +51,29 @@ describe('text motion controls', () => {
     expect(commands).toEqual([]);
   });
 
+  it('fans out commands once per subscribed listener and stops after unsubscribe', () => {
+    const controls = createTextMotionControlsHandle();
+    const descriptor = readTextMotionControlsDescriptor(controls);
+    const callsByListener = Array.from({ length: 64 }, (): TextMotionControlCommand[] => []);
+    const unsubscribers = callsByListener.map((commands) =>
+      descriptor.subscribe((command) => {
+        commands.push(command);
+      }),
+    );
+
+    controls.replay();
+    controls.stop();
+
+    expect(callsByListener.every((commands) => commands.length === 2)).toBe(true);
+    expect(callsByListener.every((commands) => commands[0]?.kind === 'replay')).toBe(true);
+    expect(callsByListener.every((commands) => commands[1]?.kind === 'stop')).toBe(true);
+
+    unsubscribers.forEach((unsubscribe) => unsubscribe());
+    controls.play();
+
+    expect(callsByListener.every((commands) => commands.length === 2)).toBe(true);
+  });
+
   it('keeps old controls inactive after moving a listener to a different controls object', () => {
     const firstControls = createTextMotionControlsHandle();
     const secondControls = createTextMotionControlsHandle();