feat(workspace): guide tonight's first pre-chorus on map and player

[seonghobae]

Product outcome

Name tonight's first labeled pre-chorus so the room can play the lift into the chorus. Workspace Open scrolls the matching map section. The player Hear action exists only when playback can seek.

Exact current identity

• Protected base: develop@acdbea6344fe1231c39535b575f4de35e4c607c9.
• Exact head: 95e74ee869d5b0f461bd2a7775475f839f0a09d9.
• Branch: feat/workspace-first-prechorus-lift.
• Do not mix with 🔒 [보안] CLI 무제한 파일 읽기 취약점 수정 #811 or test(analysis): govern real YouTube known-stem benchmark #828.

Current exact scope

• resolveFirstPreChorus selects the earliest bounded pre-chorus and the corroborated holding part, or a band-wide lift when no unique active ranked role remains.
• It does not invent a pre-chorus from intro, verse, chorus, bridge, outro, tag, pickup, stop, handoff, or the first unlabeled section.
• Workspace workspace-scroll always offers Open and scrolls the renderer-owned song-structure child.
• Player callback-only offers Hear only when onPlayFromSeconds exists and delegates that exact second.
• Copy names the holding part when corroborated, the localized lift, and the time so the next action is obvious: play the lift into the chorus.
• Reduced-motion map navigation uses behavior: "auto" when the OS requests it.

Verification

Desktop Vitest on this head: 233 passed. Included coverage files are at 100% statements/branches/functions/lines after the i18n helper. Typecheck is clean. This slice adds no dependency, lockfile, workflow, model, or database change.

The JavaScript dependency-security baseline remains owned by canonical #783 and must not be duplicated or suppressed here.

Merge gate

• Require every exact-current-head repository and central CI/security/SAST/SBOM/coverage/review gate to reach terminal success.
• Require zero valid unresolved current-head findings.
• Require a qualifying independent non-author latest-head APPROVED review.
• Never bypass branch protection or transfer predecessor evidence.
• Queued, pending, skipped-required, cancelled, failed, predecessor-head, author-only, model-only, or synthetic evidence is non-passing.

Summary by CodeRabbit

• 새 기능

  • 워크스페이스에서 첫 번째 프리코러스, 담당 역할, 시작 시간을 안내합니다.
  • 해당 구간으로 이동하거나 바로 재생하고 완료 상태를 확인할 수 있습니다.
  • 영어·한국어 UI와 프리코러스 라벨 번역을 지원합니다.

• 개선 사항

  • 곡이 없거나 분석되지 않은 경우 안내 메시지를 표시합니다.
  • 동작 줄이기 설정에 맞춰 이동 방식을 조정합니다.
  • 곡 교체 시 이전 완료 상태를 초기화합니다.
  • 플레이어의 섹션 정보와 오디오 안내를 현지화했습니다.

• 문서

  • 프리코러스 탐색 및 관련 동작 기준을 문서화했습니다.

---

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 671a9a92-5719-48f9-9cee-22954678161e

📥 Commits

Reviewing files that changed from the base of the PR and between 95e74ee and 1e9fcc8.

📒 Files selected for processing (13)

• AGENTS.md
• ARCHITECTURE.md
• CHANGELOG.md
• CLAUDE.md
• apps/desktop/src/features/player/index.localization.test.tsx
• apps/desktop/src/features/player/index.tsx
• apps/desktop/src/features/workspace/Workspace.test.tsx
• apps/desktop/src/features/workspace/Workspace.tsx
• apps/desktop/src/features/workspace/firstPreChorus.time-bound.test.ts
• apps/desktop/src/features/workspace/firstPreChorus.ts
• apps/desktop/src/i18n/index.ts
• apps/desktop/src/locales/en/common.json
• apps/desktop/src/locales/ko/common.json

🚧 Files skipped from review as they are similar to previous changes (6)

• apps/desktop/src/features/workspace/firstPreChorus.ts
• apps/desktop/src/i18n/index.ts
• AGENTS.md
• apps/desktop/src/locales/ko/common.json
• apps/desktop/src/locales/en/common.json
• CLAUDE.md

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

첫 번째 유효한 pre-chorus를 해석하는 유틸리티와 라벨 번역을 추가했습니다. Workspace에는 섹션 스크롤 안내를, Player에는 선택적 재생 콜백 안내를 연결했습니다. 런타임 검증, 완료 상태 초기화, reduced-motion 동작, 현지화 및 관련 문서를 추가했습니다.

Changes

첫 프리코러스 안내

Layer / File(s)	Summary
Pre-chorus 해석 및 라벨 번역 apps/desktop/src/features/workspace/firstPreChorus.ts, apps/desktop/src/features/workspace/firstPreChorus.test.ts, apps/desktop/src/features/workspace/firstPreChorus.time-bound.test.ts, apps/desktop/src/i18n/*	유효한 pre-chorus를 시간과 ID 순서로 선택합니다. 활성 역할의 우선순위를 적용합니다. 시간 포맷과 섹션 라벨 번역을 추가했습니다.
Callout 동작 및 표시 apps/desktop/src/features/workspace/FirstPreChorusCallout.tsx, apps/desktop/src/features/workspace/FirstPreChorusCallout*.test.tsx, apps/desktop/src/locales/*/common.json, docs/design-system/*, docs/doctoring/*	FirstPreChorusCallout이 역할·구간·시간을 표시합니다. workspace-scroll과 callback-only 동작을 지원합니다. 곡 교체 시 완료 상태를 초기화하고 reduced-motion 설정을 적용합니다.
Workspace 통합 apps/desktop/src/features/workspace/Workspace.tsx, apps/desktop/src/features/workspace/Workspace.test.tsx, CLAUDE.md	Workspace에 callout을 배치하고 현재 곡을 전달합니다. 대상 타임라인으로 이동하는 동작을 검증합니다.
Player 재생 및 현지화 통합 apps/desktop/src/features/player/index.tsx, apps/desktop/src/features/player/index.test.tsx, apps/desktop/src/features/player/index.localization.test.tsx, apps/desktop/src/locales/*/common.json	Player가 섹션 요약과 오디오 안내를 로케일에 맞게 표시합니다. 재생 콜백이 있을 때만 Hear 액션을 제공합니다. 곡 없음, 빈 섹션, 잘못된 런타임 데이터를 처리합니다.
프로젝트 지침 및 변경 기록 AGENTS.md, ARCHITECTURE.md, CHANGELOG.md	첫 라벨 pre-chorus 안내, playable ranges, 아키텍처 동작, 정책 변경을 기록합니다.

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

Merge Risk: 🔵 Low · up to 1e9fc

The player experience adds copy that may bypass the English and Korean localization contract, which could produce inconsistent or untranslated text for some users. The change is mergeable with explicit owner awareness and follow-up on localization compliance.

Sequence Diagram(s)

sequenceDiagram
  participant Workspace
  participant FirstPreChorusCallout
  participant firstPreChorus
  participant SongStructureGrid
  participant PlayerFeature
  participant PlaybackSurface

  Workspace->>FirstPreChorusCallout: 현재 song 전달
  FirstPreChorusCallout->>firstPreChorus: 첫 pre-chorus 해석
  firstPreChorus-->>FirstPreChorusCallout: 구간·역할·시작 시간 반환
  FirstPreChorusCallout->>SongStructureGrid: Open 액션으로 대상 구간 스크롤
  PlayerFeature->>FirstPreChorusCallout: callback-only 모드와 seek callback 전달
  FirstPreChorusCallout->>PlaybackSurface: Hear 액션으로 시작 시간 전달

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목은 workspace의 map과 player에서 첫 번째 pre-chorus 안내를 추가하는 주요 변경사항을 정확히 요약합니다. 간결하고 구체적입니다.
Docstring Coverage	✅ Passed	Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 25 functions across 11 files. (6 skipped: 6…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 25 functions across 11 files. (6 skipped: 6 unsupported.)

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/workspace-first-prechorus-lift

---

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.}

[seonghobae]

Review finding verification on exact head d1975e182f529cad3acba1c6c6d7d0a74ac4e47a: the unresolved fast-check suggestion is not a current correctness defect in this PR. firstPreChorus.test.ts already directly covers bounded pre-chorus selection, earliest-start selection, stable-ID tie-breaking, and fail-closed holdingRole behavior for duplicate/invalid/inactive role/graph evidence. fast-check is declared only by @bandscope/shared-types; adding it to apps/desktop would create a new workspace dependency/root-lock delta, which belongs to canonical dependency owner #783 rather than this product slice. I am therefore not broadening #955 or regenerating the root lock here. Property-based expansion can be considered in the dependency-owning quality lane without transferring merge evidence.

[devin-ai-integration]

Devin Review found 3 potential issues.

[seonghobae]

Merged current develop into this branch: resolved shared-file conflicts by including both this feature's first-pre-chorus lift callout and the newly landed #957 playable-range work (Workspace.tsx keeps both imports; en/ko locales unioned with symmetric keys; AGENTS/CLAUDE/CHANGELOG unioned). No behavior dropped.

[devin-ai-integration]

Devin Review found 1 new potential issue.