docs(editor): document remaining load-bearing invariants in README

[ChrisBeWithYou]

What

Docs-only refresh of the README's "Architecture in five minutes" section, bringing the tracked contributor docs up to date with the invariants that have accumulated over the recent PR waves but so far lived only in code comments:

• Teardown registry — global listeners/timers must go through host.addGlobalListener (tracked via window.__editorScreenTeardown) or they leak across host screen re-injection; new chrome rides the rAF draw-coalesce.
• Kind inference — keys > drums > bass > guitar decides a part's entire view, and KEYS_PATTERN is start-anchored ("Electric Piano" is not a keys name).
• Capo pair — _soundingPitchPure adds the capo once (matching core's pitch_from_base); _absolutePitch deliberately omits it. Never compose them blindly.
• Transient UI marks — module WeakSets, never underscore note fields (which leak into the save body on solo notes and vanish on chord notes via reconstructChords).
• Backend paragraph now names _NOTE_TECH_FIELDS as the single source of truth for authorable techniques.
• Module count freshened ~40 → ~50 (ls src/*.js | wc -l on main).

Why

The README tells newcomers to "read this top-to-bottom once" — these are exactly the invariants reviewers keep re-explaining on PRs, so they belong in the tracked doc.

Testing

Docs-only diff. npm test (all suites pass) and npm run lint (0 errors; 3 pre-existing warnings) run clean on the branch. No CHANGELOG entry since nothing is user-visible.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EBQCHCNA81E9tHmSDHSe2Q

Summary by CodeRabbit

• Documentation
  • Updated the “Architecture in five minutes” guide to reflect the expanded frontend module structure and orchestration flow.
  • Clarified lifecycle requirements for global listeners and timers, part-view layout selection, capo pitch handling, and transient note UI state.
  • Expanded backend guidance covering session and workspace responsibilities, normalization, build behavior, authorable note techniques, and feedpak specification precedence.

[coderabbitai]

📝 Walkthrough

Walkthrough

The README architecture guide updates frontend module and orchestration details, adds frontend invariants, and expands backend responsibilities and precedence rules.

Changes

Architecture Documentation

Layer / File(s)	Summary
Frontend architecture and invariants README.md	Updates the frontend module count and src/main.js orchestration description, and documents teardown registration, part-view kind inference, capo pitch composition, and module WeakSet usage for transient note marks.
Backend architecture invariants README.md	Documents session workdir ownership, endpoint normalization, /build library writes, _NOTE_TECH_FIELDS, and feedpak specification precedence.

Estimated code review effort: 1 (Trivial) | ~3 minutes

🚥 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	The title clearly and concisely describes the documentation-only README update about editor invariants.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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 unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/readme-architecture-invariants

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@README.md`:
- Around line 90-93: Update the README guidance around host.addGlobalListener
and window.__editorScreenTeardown to distinguish global event listeners from
timers: state that timers such as _bootPollInterval are explicitly stopped or
cleared during teardown, rather than registered through the listener registry.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 60d38aa1-f464-4d16-aa15-541f7a673481

📥 Commits

Reviewing files that changed from the base of the PR and between e02a003 and 030504b.

📒 Files selected for processing (1)

• README.md

[coderabbitai]

🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

Clarify that timers are explicitly stopped, not registered through host.addGlobalListener.

src/main.js tracks _bootPollInterval separately and clears it from window.__editorScreenTeardown; the supplied implementation only places global event listeners in the registry. Please avoid implying that timers use the listener registry.

Proposed wording

-- Global listeners and timers must register with the teardown registry
-  (`host.addGlobalListener`, tracked via `window.__editorScreenTeardown`):
+- Global listeners must use the teardown registry (`host.addGlobalListener`);
+  timers and observers must also be explicitly stopped by
+  `window.__editorScreenTeardown`:

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	- **Global listeners and timers must register with the teardown registry**
	(`host.addGlobalListener`, tracked via `window.__editorScreenTeardown`):
	the host re-injects the screen, so anything unregistered leaks across
	re-injection. New chrome rides the rAF draw-coalesce — no per-frame work.
	- **Global listeners must use the teardown registry**
	(`host.addGlobalListener`);
	timers and observers must also be explicitly stopped by
	`window.__editorScreenTeardown`:
	the host re-injects the screen, so anything unregistered leaks across
	re-injection. New chrome rides the rAF draw-coalesce — no per-frame work.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` around lines 90 - 93, Update the README guidance around
host.addGlobalListener and window.__editorScreenTeardown to distinguish global
event listeners from timers: state that timers such as _bootPollInterval are
explicitly stopped or cleared during teardown, rather than registered through
the listener registry.