feat: add stacked timeline tracks for annotations

[aiden-guan]

Summary

Overlapping annotations currently share one timeline row, so a short annotation can disappear behind a longer one. Add stacked tracks that keep each element visible, selectable and resizable, including compact pills with outside resize handles.

Annotations can be dragged vertically between layers or beyond the existing rows to create a layer. Dropping or resizing into an occupied layer creates a separate layer; higher tracks use the existing zIndex compositing order. Span and layer changes save together as one undo step, with no project-format migration. Identical overlapping annotations remain independent, and ambiguous legacy fragments at a shared clip boundary are kept separate instead of guessing their pairing.

The panel grows for annotation layers and scrolls when it reaches its height limit. Other modifier lanes also stack overlapping pills while retaining their existing timing rules. Includes translated track labels and drag hints for all 15 locales, architecture documentation, and regression coverage. The browser test's zoom fixture uses a 4K source so its four-preset keyboard check respects the existing source-magnification limit.

Related issue

No linked issue. Reproduces a full-length annotation with shorter overlapping annotations.

Type of change

• Bug fix
• Feature
• Enhancement
• Documentation
• Refactor / maintenance
• Performance
• Security

Release impact

• Patch
• Minor
• Major / breaking change
• No release note needed

Desktop impact

• Windows
• macOS
• Linux
• Installer / packaging
• Not platform-specific

Screenshots / video

Testing

Tested locally on macOS with Node 22.22.1 and npm 10.9.4:

• npm run test
• npx tsc -p tsconfig.test.json --noEmit
• npm run build-vite (includes app typecheck)
• npm run lint:fix and npm run lint (existing warnings, no errors)
• npm run i18n:check
• npm run docs:check
• Browser preview: npx vite --config vite.v4preview.config.ts, then E2E_BASE_URL=http://localhost:5207 npx playwright test tests/e2e/v4-shell.spec.ts tests/e2e/editor-smoke.spec.ts

Regression coverage includes nested/identical overlaps, independent selection and deletion, move/resize overlap placement, vertical layer changes, compact handles, clip-boundary fragments, layer persistence, undo/redo, and panel growth. Browser coverage exercises pointer drags, selection, persisted layer order, undo/redo and the editor smoke flow.

Native capture, GPU preview/export and packaged builds were not exercised; this change touches the renderer and document operations, and native compositing already consumes zIndex.

GitHub CI and Diagnostic artifact workflows are awaiting maintainer approval for this fork contribution. The PR remains a draft until the CI gate can run.

Summary by CodeRabbit

• New Features
  • Overlapping annotations appear on separate timeline tracks, where they can be selected and edited independently.
  • Drag annotations horizontally to adjust timing or vertically to change layers. New annotations are placed above existing layers, and timing and layer changes are saved together.
  • Timeline height expands to fit annotation tracks, up to a maximum height.
• Bug Fixes
  • Preserved annotation identity and layer placement across overlaps, clip boundaries, and undo/redo.
• Documentation
  • Clarified timeline behavior for overlapping annotations and other regions.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 90d73a72-eea7-49ff-8fbf-ffcf23cf08ee

📥 Commits

Reviewing files that changed from the base of the PR and between 8a1c8de and 37394f8.

⛔ Files ignored due to path filters: 1

• technical-documentation/assets/annotation-tracks.png is excluded by !**/*.png

📒 Files selected for processing: 2

• src/lib/ai-edition/timeline/timelineMap.test.ts
• src/lib/ai-edition/timeline/timelineMap.ts

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.

📝 Walkthrough

Timeline annotations can overlap on separate tracks while remaining independently selectable and editable. Users can move annotations between layers, and the timeline sizes lanes from packed region rows. Annotation span and layer changes are saved together, with localized drag guidance and test coverage.

Changes: Annotation tracks

Layer / File(s)	Summary
Annotation identity and span updates src/lib/ai-edition/timeline/timelineMap.ts, src/lib/ai-edition/store/useTimeline.ts, src/lib/ai-edition/timeline/timelineMap.test.ts, src/lib/ai-edition/store/useTimeline.test.ts, technical-documentation/architecture/timeline-model.md	Overlapping annotations remain separate pills with independent selection and editing. Ambiguous fragments remain separate. New annotations use the highest saved nonnegative layer plus one.
Packed rows and lane sizing src/lib/ai-edition/timeline/regionTracks.ts, src/components/ai-edition/v4/V4Timeline.tsx, src/components/ai-edition/NewEditorShell.tsx, src/components/ai-edition/v4/V4Timeline.geometry.test.tsx, src/components/ai-edition/NewEditorShell.timelineHeight.test.tsx	Timeline regions use packed-row geometry, and lanes size to fit their rows. Shell height includes annotation, audio, and effect lanes.
Vertical annotation dragging src/components/ai-edition/v4/V4Timeline.tsx, src/lib/ai-edition/store/useTimeline.ts, src/i18n/locales/*/timeline.json, tests/e2e/v4-shell.spec.ts	Vertical dragging selects an annotation layer. The span and layer are saved together. Localized labels and drag hints describe the interaction. Tests cover layer movement, persistence, and undo/redo.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant V4Timeline
  participant useTimeline
  participant timelineMap
  V4Timeline->>useTimeline: Submit annotation span and destination layer
  useTimeline->>timelineMap: Replace pill span with layer payload
  timelineMap-->>useTimeline: Return rebuilt annotation regions
  useTimeline-->>V4Timeline: Save the updated annotation

Loading

Merge Risk: ⚪ Minimal · up to 37394

No actionable issue remains from this review; the change is mergeable after normal checks.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 46.15% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 13 functions across 11 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Title check		The title clearly and concisely describes the primary change: adding stacked timeline tracks for annotations.
Description check		The description includes all required sections, explains the change and impact, provides testing details, and includes UI evidence. It also clearly states that no issue is linked.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}