feat(workspace): guide tonight's first tag on the rehearsal map

[seonghobae]

Product outcome

After analysis, the rehearsal map names tonight's first labeled tag so the room can catch the last line together. Open moves to the matching rendered map section.

A tag is the short last-line ending. This PR does not invent one from outro, verse, chorus, pickup, stop, handoff, or the last unlabeled section.

Exact current identity

• Protected target: develop@acdbea6344fe1231c39535b575f4de35e4c607c9.
• Branch: feat/workspace-first-tag.
• Distinct from feat(workspace): guide tonight's first outro on the rehearsal map #986 first-outro, 🔒 [보안] CLI 무제한 파일 읽기 취약점 수정 #811 CLI authority, test(analysis): govern real YouTube known-stem benchmark #828 known-stem MIR, and feat(workspace): Storybook tokens for rehearsal components #897 Storybook tokens.

Current exact scope

• resolveFirstTag picks the earliest labeled tag with a bounded rehearsal window and the highest-priority unique active part that holds it.
• Missing, inherited, sparse, duplicated, or unlabeled endings stay guidance-only: No tag yet. Stay on tonight's map until the last line is labeled.
• Open scrolls the renderer-owned song-structure child (data-section-index). Analysis section.id is never DOM-ID authority.
• Completion copy (Catch the last line with {role} at {at}. End together.) arms only after scrollIntoView succeeds.
• Reduced-motion requests use behavior: "auto".
• Korean copy keeps dynamic role names particle-safe ({role} 파트).

Test-first evidence

• Resolver: labeled tag vs outro/verse/unlabeled last section; earliest-of-two; locale-independent id ties; band-wide landing; inherited/sparse/array-masquerade rejection.
• Callout: map Open, missing-target fail-closed, renderer-owned index navigation, song-change reset, Korean form-label localization.
• Workspace: Open Lead Vocal tag at 3:20 scrolls the rendered section.

Merge gate

• Do not mix with 🔒 [보안] CLI 무제한 파일 읽기 취약점 수정 #811, test(analysis): govern real YouTube known-stem benchmark #828, feat(workspace): Storybook tokens for rehearsal components #897, or feat(workspace): guide tonight's first outro on the rehearsal map #986.
• Canonical JavaScript dependency/security owner remains fix(security): establish canonical npm, PDF.js, Nanoid, and Undici baseline #783. Do not copy or suppress inherited nanoid / pdfjs-dist / undici findings here.
• Keep unmerged until the unchanged then-current head has every applicable repository/central CI, coverage, docstring, SAST/security/SBOM/supply-chain/package/release gate terminal-success; zero valid unresolved findings; a qualifying independent non-author last-push approval; and ordinary branch-protection acceptance.
• Queued, pending, skipped-required, failed, predecessor-head, protected-base, self/author, model-only, or administrative-bypass evidence is non-passing.

Security Notes

• Untrusted input: song, section, time-range, role, and section-local graph metadata are runtime data; inherited properties and arrays masquerading as records are not authority.
• Trust boundary: tag resolution accepts required fields only when the inspected record owns them. Navigation targets are renderer-owned child indexes, never analysis ids or payload strings.
• Mitigations: dense collections require own indexed elements; copy interpolation runs once; missing values stay pending; scroll no-ops when the surface cannot move.
• Test points: inherited song/section/timing/role/graph metadata is rejected; duplicate role identities stay band-wide; reduced-motion scroll uses auto.

---

Summary by CodeRabbit

• 새로운 기능

  • 워크스페이스에서 오늘의 첫 번째 태그 역할, 섹션, 시작 시간을 안내합니다.
  • 태그를 열어 해당 섹션으로 바로 이동할 수 있습니다.
  • 태그가 없거나 사용할 수 없는 경우 안내 메시지를 표시합니다.
  • 운영체제의 동작 줄이기 설정에 따라 이동 방식을 조정합니다.

• 개선 사항

  • 영어와 한국어 안내 문구 및 섹션 라벨 현지화를 지원합니다.
  • 한국어 역할명에 맞는 자연스러운 조사 표현을 제공합니다.
  • 잘못되거나 불완전한 곡 데이터에서도 안정적으로 안내합니다.

[coderabbitai]

Warning

Review limit reached

Next included review available in 31 minutes.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 0f4511c5-0cc4-4155-8037-a5a8cb69acf3

📥 Commits

Reviewing files that changed from the base of the PR and between b567215 and 79dcb21.

📒 Files selected for processing (10)

• AGENTS.md
• ARCHITECTURE.md
• CHANGELOG.md
• CLAUDE.md
• apps/desktop/src/features/workspace/FirstTagCallout.reduced-motion.test.tsx
• apps/desktop/src/features/workspace/FirstTagCallout.tsx
• apps/desktop/src/features/workspace/Workspace.test.tsx
• apps/desktop/src/features/workspace/Workspace.tsx
• apps/desktop/src/locales/en/common.json
• apps/desktop/src/locales/ko/common.json

📝 Walkthrough

Walkthrough

resolveFirstTag가 유효한 첫 라벨 태그를 찾습니다. FirstTagCallout이 역할, 섹션, 시간을 표시하고 해당 렌더러 섹션으로 이동합니다. 영어·한국어 문구와 reduced-motion 동작을 추가했습니다.

Changes

첫 태그 안내 및 탐색

Layer / File(s)	Summary
첫 태그 해석 계약 apps/desktop/src/features/workspace/firstTag.ts, apps/desktop/src/features/workspace/firstTag*.test.ts	소유 데이터 속성만 허용하도록 검증을 강화합니다. 유효한 tag 섹션과 활성 역할을 찾고, 잘못된 메타데이터와 중복 역할을 처리합니다. 해석 중 예외가 발생하면 null을 반환합니다.
안내 문구와 현지화 apps/desktop/src/features/workspace/FirstTagCallout.tsx, apps/desktop/src/features/workspace/FirstTagCallout*.test.tsx, apps/desktop/src/i18n/*, apps/desktop/src/locales/{en,ko}/common.json	첫 태그 안내, 역할별·밴드 전체 문구, 태그 없음 상태를 추가합니다. 버튼이 렌더러 소유 섹션으로 이동하고 곡 또는 태그가 변경되면 열린 상태를 초기화합니다. 한국어 라벨, 조사 형태, reduced-motion 동작을 검증합니다.
워크스페이스 통합 apps/desktop/src/features/workspace/Workspace.tsx, apps/desktop/src/features/workspace/Workspace.test.tsx, apps/desktop/vite.config.ts	워크스페이스에 FirstTagCallout을 렌더링합니다. 렌더러 섹션에 data-section-index를 추가합니다. 태그 탐색과 커버리지 대상을 검증합니다.
동작 계약 문서화 AGENTS.md, ARCHITECTURE.md, CHANGELOG.md, CLAUDE.md, docs/design-system/component-contract.md, docs/doctoring/reduced-motion-first-tag-navigation.md	첫 태그의 명명 규칙, 섹션 선택 규칙, 컴포넌트 계약과 reduced-motion 스크롤 동작을 문서화합니다.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: 🟡 Moderate · up to b5672

The first-tag guidance adds a map-opening action, but the current target lookup depends on an English accessibility label, so localized renderer labels such as Korean can leave users without navigation or completion feedback. This bounded correctness and accessibility issue should be fixed before merge.

Sequence Diagram(s)

sequenceDiagram
  participant Workspace
  participant FirstTagCallout
  participant resolveFirstTag
  participant RendererSection
  Workspace->>FirstTagCallout: song 전달
  FirstTagCallout->>resolveFirstTag: 첫 태그 해석
  resolveFirstTag-->>FirstTagCallout: 태그, 역할, 시간 반환
  FirstTagCallout->>RendererSection: 태그 섹션 위치 조회
  FirstTagCallout->>RendererSection: scrollIntoView 호출

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	제목은 리허설 맵에서 오늘 밤 첫 번째 태그를 안내하는 주요 변경 사항을 명확하고 간결하게 설명합니다.
Docstring Coverage	✅ Passed	Docstring coverage is 81.82% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 22 functions across 8 files. (1 skipped: 1 unsupported.)
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.

✨ 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-tag

---

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]

Re-review request for exact head c52c0a85ac28681181abd41fcb667d1917357ab4: all required status contexts are green on this head (including coverage-evidence and security scans) and all review threads are resolved. @opencode-agent please review current head c52c0a85ac28681181abd41fcb667d1917357ab4 and update the review decision.

[seonghobae]

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