Troubleshooting
Chart renders but nothing moves
In v0.1, simulateData defaults to false. Either pass simulateData for a demo, or call updateAgent() via the ref after mount to push your own data.
Lines appear jittery or jagged
Smooth your tokensRate with a moving average before pushing. AgentStat expects relatively stable numeric inputs — the Catmull-Rom smoothing handles normal variation, not raw spiky data.
updateAgent() does nothing
Wrap calls in optional chaining: ref.current?.updateAgent(…). The ref populates after the first render. Also verify the id you're passing matches an id in your agents array exactly — unknown ids are silently ignored.
Canvas stays blank on load
AgentStat needs at least two data points per agent to draw a curve. Either push initial data via updateAgent() or enable simulateData temporarily. If the issue persists, check that your agents array is non-empty and each agent has visible: true.
My agent stays 'stuck' even when I set status back
When you call updateAgent() with an anomalous status (stuck or hallucinating), AgentStat locks the agent so the simulation won't auto-recover it. Pass a non-anomalous status (e.g. 'active') to clear the lock.
A fresh agents array literal wipes my updateAgent mutations
AgentStat tolerates fresh array literals as long as the id listdoesn't change. If your parent component rebuilds the array on every render with identical ids, your ref mutations are preserved. If the ids change, state for added/removed agents is resynced. To be safe, memoize the array with useMemo or declare it at module scope.
Performance drops with many agents
Hide agents you're not actively monitoring by setting visible: false. Hidden agents skip both the draw pass and the hover hit-test. The user can also toggle agents using the built-in overlay buttons.
Types look wrong: getLiveMetrics doesn't have status
Make sure you're on v0.1.0 or later. Earlier development builds returned only { tokensRate, progress }; the shipped release also includes status.
Still stuck?
Check the Real Data Integration guide for a complete working example, or review the API Reference for prop details.