best-practices: Integrating with the app (event bus + feedBack API)

[topkoa]

Summary

First of four PRs closing the glaring gaps a completeness sweep found: we documented plugin mechanics well but under-covered the runtime integration API. This adds an "Integrating with the app" section — the single most-used integration surface.

Rules (30–33)

• 30 — Subscribe to app state through the event bus. Catalogs the commonly-used window.feedBack events with their event.detail payloads: screen:changed {id}, song:loading/song:ready/song:play/pause/stop/ended/seek/song:position-changed {time,duration}/song:arrangement-changed, library:changed {reason}, viz:renderer:ready/viz:reverted {reason}, highway:canvas-replaced/highway:visibility. Keep handlers cheap (some fire during playback) and unsubscribe when hidden.
• 31 — Drive the app through the feedBack API, not its DOM. navigate/getNavParams/showScreen/setReturnScreen, playSong/seek/setLoop/clearLoop/getLoop/playQueue, currentSong/isPlaying — never #btn-loop-* and friends (private, and they move between UI versions).
• 32 — Wrap Host functions carefully. If you wrap playSong/showScreen: always call + await the original, install once (idempotent, rule 12), clean up on transitions, and don't assume load order.
• 33 — Support both player UIs. Player-injecting plugins must work in v2 and v3 — detect uiVersion, mount into the Host slot (ui.playerControlSlot()), verify in both; don't rely on the compat shim.

Added an "Integrating with the app" checklist block; Shipping renumbered to 34–38 (contiguous 1–38).

Scope & stacking

Docs only. API framed as the current Host contract. Stacked on #8. Full stack: #2 → #4 → #3 → #5 → #6 → #7 → #8 → #9. Three more coming on top (server robustness, styling, diagnostics). mkdocs build --strict + check_versions.py pass.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4d879637-16e3-44da-9ad9-628b2ce04c8f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/best-practices-integration

---

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

[Copilot]

Pull request overview

Adds an “Integrating with the app” section to the best-practices guide, documenting how plugins should observe app state (event bus) and drive navigation/playback via the supported runtime API, plus a checklist update and corresponding changelog entry.

Changes:

• Documented the window.feedBack event bus and a catalog of commonly used lifecycle/transport events and payloads.
• Added guidance on driving navigation/playback via the Host runtime API (vs DOM), wrapping Host functions safely, and supporting both player UIs (v2/v3).
• Renumbered Shipping rules and extended the pre-publish checklist; updated CHANGELOG.md accordingly.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
spec/best-practices.md	Adds “Integrating with the app” rules (30–33), renumbers Shipping (34–38), and adds a checklist block.
CHANGELOG.md	Records the new best-practices section and its major points under Unreleased.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.