fix: emit sync events when clicking on region annotations #8604

cloudmark · 2025-10-08T10:02:46Z

Here's a comprehensive PR description for the region synchronization fix:

PR Description

Reason for Change

Problem:
When clicking on region annotations (either directly on the plot or in the Regions sidebar/outliner), the view scrolls to show the region but does NOT synchronize with other synced media components. This breaks multi-modal data exploration workflows where users expect all synchronized components (Audio, TimeSeries, etc.) to seek to the same time position.

For example:

Click on a TimeSeries region labeled "Walking" → Only TimeSeries view scrolls
Audio player stays at current position
Other TimeSeries (velocity, acceleration, etc.) don't update
User cannot navigate synchronized data by clicking annotations

Root Cause:
The selectRegion() method in TimeSeriesRegion.js only calls scrollToRegion() which adjusts the view but does not:

Update the cursor position (setCursor())
Emit a sync event (syncSend()) to notify other components

This is inconsistent with how clicking directly on empty plot areas works, which DOES emit sync events.

Solution:
Modified TimeSeriesRegion.selectRegion() to emit sync events after scrolling to the region. The method now:

Scrolls the TimeSeries view to show the region (existing behavior)
Updates the cursor/playhead position using setCursor()
Calculates relative time from the region's start time
Emits a sync event via syncSend() to notify all components in the same sync group
Handles both date-formatted and numeric time columns properly

Videos

Bug demonstration: https://www.loom.com/share/2584716884114820a7e4b5b76a3316b3
- Shows clicking on regions only scrolls that component
- Audio and other TimeSeries don't synchronize
Fix demonstration: https://www.loom.com/share/9a6421fca42d424bb068779d9a4d7021
- Shows clicking on regions now syncs all components
- Audio, TimeSeries, and other synced components seek together

Rollout Strategy

No special rollout needed - This fix is gated by existing feature flag:

Requires FF_TIMESERIES_SYNC feature flag to be enabled
No new environment variables needed
No API changes
Backward compatible - only improves existing behavior
Change applies automatically when feature flag is active

Testing

Manual Testing Performed:

Basic Region Click Test
- Created TimeSeries task with Audio and multiple TimeSeries (acceleration, velocity)
- Created region annotations on TimeSeries
- Clicked on regions directly on the plot
- Verified all synced components seek to region's start time (see fix demo video)
- Tested with both numeric and date-formatted time columns
Regions Sidebar Test
- Clicked on regions in the Regions sidebar/outliner
- Verified all synced components synchronize
- Confirmed behavior is identical to clicking on plot
Edge Cases
- Regions at the very start/end of timeseries
- Multiple regions selected in sequence
- Instant regions (zero duration)
- Date-formatted time columns with millisecond precision
Interaction Consistency
- Clicking empty plot → syncs all components (existing behavior - works)
- Clicking region on plot → syncs all components (NEW - works)
- Clicking region in sidebar → syncs all components (NEW - works)
Multi-Component Synchronization
- Audio + multiple TimeSeries (acceleration, velocity, gyroscope)
- Verified sync works in all directions:
  - TimeSeries region → Audio seeks
  - Audio region → TimeSeries seek (if applicable)
  - All TimeSeries update together

Code Quality:

No linting errors introduced
Follows existing code patterns and conventions
Uses existing setCursor() and syncSend() methods
Properly checks feature flag before emitting sync

Risks

Risk Level: LOW

Performance:

No performance impact - only adds two method calls when regions are clicked
Sync events are already used throughout the system
No additional data processing or computations

Backward Compatibility:

No breaking changes
Only affects behavior when FF_TIMESERIES_SYNC is enabled
Users without the feature flag see no change
All existing TimeSeries functionality preserved

Security:

No security implications
No new dependencies added
No changes to data handling or storage
Uses existing sync infrastructure

User Experience:

Fixes broken behavior - strictly an improvement
Makes region clicks consistent with plot clicks
Improves multi-modal data exploration workflows

Reviewer Notes

Key Points to Review:

Implementation Location (web/libs/editor/src/regions/TimeSeriesRegion.js)
- Changes are in selectRegion() method (lines ~72-93)
- Feature flag check ensures safe rollout
- Time conversion handles both date and numeric formats

Code Logic:

// After existing scrollToRegion() call:
if (isFF(FF_TIMESERIES_SYNC) && self.parent.sync) {
  const regionStartTime = self.start;
  self.parent.setCursor(regionStartTime);
  
  const [minKey] = self.parent.keysRange;
  if (minKey !== undefined) {
    let relativeTime;
    if (self.parent.isDate) {
      relativeTime = (regionStartTime - minKey) / 1000;
    } else {
      relativeTime = regionStartTime - minKey;
    }
    self.parent.syncSend({ time: relativeTime, playing: false }, "seek");
  }
}

Consistency with Existing Code:
- Uses same pattern as handleMainAreaClick() and plotClickHandler()
- Reuses existing setCursor() and syncSend() methods
- Follows same time conversion logic as other seek operations
Testing the Fix:
- Watch both demonstration videos to see before/after behavior
- Load any TimeSeries task with sync enabled
- Click on regions (plot or sidebar) and verify all components sync

General Notes

Implementation Details:

The fix adds synchronization logic to TimeSeriesRegion.selectRegion():

Called when region is clicked on plot OR in sidebar
Scrolls view to region (existing behavior - preserved)
Updates cursor position to region start time (NEW)
Emits sync event to all synced components (NEW)

Time Conversion:

For date-formatted columns: converts milliseconds to seconds
For numeric columns: uses values directly
Matches existing time conversion patterns throughout TimeSeries

Feature Flag:

Protected by FF_TIMESERIES_SYNC feature flag
Safe to deploy with flag disabled
Can be enabled per-project or globally

Benefits:

Clicking any region (plot or sidebar) now syncs all components
Consistent behavior across all interaction methods
Critical for multi-modal workflows (IoT, wearables, autonomous vehicles)
Improved user experience for time-series annotation tasks

Files Changed:

web/libs/editor/src/regions/TimeSeriesRegion.js - Added sync logic to selectRegion()

No Migration Required - This is a transparent bug fix that improves behavior without requiring any user action or configuration changes.

Related Context

Related to Issue: #8603

When clicking on region annotations (either directly on the plot or in the Regions sidebar/outliner), the view would scroll to show the region but would NOT synchronize with other synced media components. This broke multi-modal data exploration workflows where users expect all synchronized components (Audio, TimeSeries, etc.) to seek to the same time position. For example, clicking on a TimeSeries region labeled "Walking" would only scroll the TimeSeries view but would not seek the Audio player or other synced TimeSeries to that time. Changes: - Modified TimeSeriesRegion.selectRegion() to emit sync events after scrolling to the region - Added setCursor() call to update the cursor/playhead position - Added syncSend() call with the region's start time to notify all synced components in the same sync group - Handles both date-formatted and numeric time columns properly - Applies to both direct region clicks and Regions sidebar/outliner clicks Benefits: - Clicking any region (plot or sidebar) now syncs all components - Consistent behavior between clicking empty plot vs clicking regions - Improved multi-modal data exploration and navigation - Users can now easily navigate synchronized data by clicking annotations Impact: - Affects all TimeSeries annotation tasks with synchronized media - Critical for multi-sensor data workflows (IoT, wearables, autonomous vehicles) - Requires FF_TIMESERIES_SYNC feature flag to be enabled Bug demonstration: https://www.loom.com/share/2584716884114820a7e4b5b76a3316b3 Fix demonstration: https://www.loom.com/share/9a6421fca42d424bb068779d9a4d7021 Files changed: - web/libs/editor/src/regions/TimeSeriesRegion.js

netlify · 2025-10-08T10:02:50Z

👷 Deploy request for heartex-docs pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	`38f829b`

netlify · 2025-10-08T10:02:50Z

👷 Deploy request for label-studio-docs-new-theme pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	`38f829b`

netlify · 2025-10-08T10:02:52Z

✅ Deploy Preview for label-studio-storybook ready!

Name	Link
🔨 Latest commit	`38f829b`
🔍 Latest deploy log	https://app.netlify.com/projects/label-studio-storybook/deploys/68e636c9c9f3cf0008921652
😎 Deploy Preview	https://deploy-preview-8604--label-studio-storybook.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

netlify · 2025-10-08T10:03:38Z

✅ Deploy Preview for label-studio-playground ready!

Name	Link
🔨 Latest commit	`38f829b`
🔍 Latest deploy log	https://app.netlify.com/projects/label-studio-playground/deploys/68e636c91b5d580008929794
😎 Deploy Preview	https://deploy-preview-8604--label-studio-playground.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

yyassi-heartex · 2025-10-08T12:46:12Z

web/package.json

    "on-headers": "1.1.0",
    "form-data": "4.0.4",
-    "stylus": "0.0.1-security"
+    "stylus": "0.64.0"


this seems unrelated - was that intended?

Yes, this was done so I could build it, "stylus": "0.0.1-security" was not being resolved, not sure if its just me or not.

If its me, we can simply revert.

the whole override can probably be removed

Great catch, @cloudmark! I think it's best to take it from this PR to avoid mixing concerns.
Let's review this separately @yyassi-heartex, as @nass600 said this can probably be removed since it's coming from the npm incident.

Hi @cloudmark we discussed internally, please leave the stylus version unchanged - we'll be creating a PR internally to remove it anyways

yyassi-heartex · 2025-10-17T19:52:15Z

/jira create

Workflow run
Jira issue TRIAG-1683 is created

cloudmark · 2025-10-21T17:30:15Z

you let me know what you want to do, if you want to remove Ill remove, alternatively feel free to remove it while you merge internally

…

On Tue, Oct 21, 2025 at 5:47 PM Raul Martin ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In web/package.json <#8604 (comment)> : > @@ -249,7 +249,7 @@ "moment": "2.29.4", "on-headers": "1.1.0", "form-data": "4.0.4", - "stylus": "0.0.1-security" + "stylus": "0.64.0" Great catch, @cloudmark <https://github.com/cloudmark>! I think it's best to take it from this PR to avoid mixing concerns. Let's review this separately @yyassi-heartex <https://github.com/yyassi-heartex>, as @nass600 <https://github.com/nass600> said this can probably be removed since it's coming from the npm incident. — Reply to this email directly, view it on GitHub <#8604 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AANKHJSCA6WHWV5CH37P6SL3YZIQ7AVCNFSM6AAAAACITM5YR2VHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZTGNRRGQ4DAMRZGQ> . You are receiving this because you were mentioned.Message ID: ***@***.***>

cloudmark requested a review from a team as a code owner October 8, 2025 10:02

github-actions bot added the fix label Oct 8, 2025

cloudmark mentioned this pull request Oct 8, 2025

Clicking on region annotations does not synchronize with other synced components (plot and sidebar) #8603

Open

yyassi-heartex reviewed Oct 8, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: emit sync events when clicking on region annotations #8604

fix: emit sync events when clicking on region annotations #8604

cloudmark commented Oct 8, 2025

Uh oh!

netlify bot commented Oct 8, 2025

Uh oh!

netlify bot commented Oct 8, 2025

Uh oh!

netlify bot commented Oct 8, 2025 •

edited

Loading

Uh oh!

netlify bot commented Oct 8, 2025 •

edited

Loading

Uh oh!

yyassi-heartex Oct 8, 2025

Uh oh!

cloudmark Oct 8, 2025

Uh oh!

nass600 Oct 21, 2025

Uh oh!

luarmr Oct 21, 2025

Uh oh!

yyassi-heartex Oct 22, 2025

Uh oh!

yyassi-heartex commented Oct 17, 2025 •

edited by atlassian bot

Loading

Uh oh!

cloudmark commented Oct 21, 2025 via email

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

fix: emit sync events when clicking on region annotations #8604

Are you sure you want to change the base?

fix: emit sync events when clicking on region annotations #8604

Conversation

cloudmark commented Oct 8, 2025

PR Description

Reason for Change

Videos

Rollout Strategy

Testing

Manual Testing Performed:

Code Quality:

Risks

Reviewer Notes

General Notes

Related Context

Uh oh!

netlify bot commented Oct 8, 2025

👷 Deploy request for heartex-docs pending review.

Uh oh!

netlify bot commented Oct 8, 2025

👷 Deploy request for label-studio-docs-new-theme pending review.

Uh oh!

netlify bot commented Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for label-studio-storybook ready!

Uh oh!

netlify bot commented Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for label-studio-playground ready!

Uh oh!

yyassi-heartex Oct 8, 2025

Choose a reason for hiding this comment

Uh oh!

cloudmark Oct 8, 2025

Choose a reason for hiding this comment

Uh oh!

nass600 Oct 21, 2025

Choose a reason for hiding this comment

Uh oh!

luarmr Oct 21, 2025

Choose a reason for hiding this comment

Uh oh!

yyassi-heartex Oct 22, 2025

Choose a reason for hiding this comment

Uh oh!

yyassi-heartex commented Oct 17, 2025 • edited by atlassian bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cloudmark commented Oct 21, 2025 via email

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

netlify bot commented Oct 8, 2025 •

edited

Loading

netlify bot commented Oct 8, 2025 •

edited

Loading

yyassi-heartex commented Oct 17, 2025 •

edited by atlassian bot

Loading