Enable real-time multi-user sync for local token storage

[Copilot]

Problem

When multiple users work on tokens in the same Figma file, changes made by one user are not visible to others until they manually restart the plugin. This leads to:

• Users working with stale token data
• Potential data loss when changes overwrite each other
• Poor collaboration experience for design teams
• Manual refresh workflows that interrupt creative flow

Solution

This PR implements automatic real-time synchronization for local token storage by leveraging Figma's native documentchange event system. When any user modifies tokens, all other users with the plugin open automatically receive and display the updates.

How it works

1. Detection: The plugin monitors Figma's documentchange events for remote modifications to token-related shared plugin data
2. Notification: When changes are detected, the plugin sends a TOKEN_DATA_CHANGED message to the UI with the updated timestamp
3. Reload: The UI requests fresh token data via the new RELOAD_TOKEN_DATA message
4. Update: Token state in Redux is updated automatically, and the UI reflects the changes

Key Features

• Automatic detection of remote token changes using Figma's event system
• Timestamp tracking prevents duplicate notifications and unnecessary reloads
• Origin filtering ensures only changes from other users trigger updates (not self-changes)
• Conditional activation only runs after initial startup to avoid interference
• Works transparently in the background with no user intervention required

Technical Implementation

New Message Types:

• TOKEN_DATA_CHANGED (plugin → UI): Notifies UI of remote token modifications
• RELOAD_TOKEN_DATA (UI → plugin): Requests fresh token data from storage

Modified Files:

• sendDocumentChange.ts: Enhanced to detect and notify about token data changes
• AppContainer.tsx: Added useEffect listener for automatic token reload
• AsyncMessages.ts: Added new message type definitions
• Created handlers: reloadTokenData.ts, tokenDataChanged.ts

Safeguards:

• Last-known timestamp tracking prevents duplicate notifications
• Only processes changes with origin: 'REMOTE' (from other users)
• Validates changes are to token-related shared plugin data keys
• Only activates after initial plugin startup is complete

Limitations

• Only works for local document storage (not remote sync providers like GitHub/GitLab)
• Requires all users to have the plugin open to receive updates
• Uses "last write wins" conflict resolution (no merge conflict UI)

Testing

• ✅ All linting passed
• ✅ AppContainer component tests verified
• ✅ Successful production build
• ✅ Code review completed with no issues

Documentation

Comprehensive documentation added in docs/REAL_TIME_SYNC.md explaining:

• Architecture and data flow
• Message types and their purposes
• Conflict prevention mechanisms
• Storage structure
• Future enhancement possibilities

---

Closes: Addresses the need for multi-user real-time collaboration on tokens within the same Figma file.

Original prompt

Enable real-time multi-user sync for local token storage in the Tokens Studio for Figma plugin. When a user changes tokens (add/edit/delete) in a Figma document, all other users with the plugin open in the same file must automatically see the updates—without needing to restart.

Constraints:

• The codebase is a monorepo (Yarn workspaces), TypeScript, React, Redux/Rematch, and chunked local storage (data is split into segments).
• The plugin uses a message-passing architecture between the UI (React, iframe) and Figma sandbox (plugin code).
• Storage logic is in src/storage, plugin code in src/plugin.
• Avoid data loss or overwrites: concurrent edits should not silently override; resolve or merge where possible.
• Only local document storage (not remote sync) is relevant for this feature.
• All changes must include a patch-level changeset (yarn changeset).

Plan a robust way to:

• Detect and broadcast local token changes to all plugin instances open on the same file
• Update chunked storage safely and efficiently
• Prevent or resolve conflicts across users
• Minimize disruption to existing architecture

Produce a stepwise implementation plan and checklist. - should be done in one task, no need for a huuuuuge complex task

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[changeset-bot]

🦋 Changeset detected

Latest commit: d481b33

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@tokens-studio/figma-plugin	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

⤵️ 📦 ✨ The artifact was successfully created! Want to test it? Download it here 👀 🎁

[github-actions]

Commit SHA:6d0d29693f8f48ae5d2e2792e1e34c2f5776e336

Test coverage results 🧪

Code coverage diff between base branch:main and head branch: copilot/enable-real-time-token-sync 

Status	File	% Stmts	% Branch	% Funcs	% Lines
🔴	total	64.96 (-0.07)	56.84 (-0.11)	61.72 (-0.12)	65.3 (-0.07)
🔴	packages/tokens-studio-for-figma/src/app/components/AppContainer/AppContainer.tsx	73.8 (-8.34)	72.41 (-15.82)	60 (-20)	73.8 (-8.34)
🟢	packages/tokens-studio-for-figma/src/plugin/controller.ts	98.27 (0.06)	100 (0)	75 (0)	100 (0)
✨ 🆕	packages/tokens-studio-for-figma/src/plugin/sendDocumentChange.ts	2.63	0	0	2.85
✨ 🆕	packages/tokens-studio-for-figma/src/plugin/asyncMessageHandlers/reloadTokenData.ts	16.66	0	0	16.66
✨ 🆕	packages/tokens-studio-for-figma/src/plugin/asyncMessageHandlers/tokenDataChanged.ts	100	100	0	100

[github-actions]

Commit SHA:6d0d29693f8f48ae5d2e2792e1e34c2f5776e336
Current PR reduces the test coverage percentage by 1 for some tests