Replace difficulty glasses with a semantic tier rail #131

Effort: L

Target File / Section

• plugin.json — description
• README.md:128-160
• settings.html:33-36
• screen.js:1165-1215 — tier-to-glass presentation helpers
• screen.js:1725-1778 — difficulty_ladder.sections.v2
• screen.js:2370-2522 — standalone canvas HUD
• INTEGRATION.md — Section Map contract

Category

Calibration | Consistency | Workflow | Omission

Flaw Analysis

The glasses should be retired, not cosmetically restyled.

The metaphor attempts to encode two different facts at once:

• vessel height / glassSize = the tier where the phrase or section reaches full detail (top_difficulty);
• liquid height / fillPercentage = the currently presented tier relative to that threshold.

That mapping is not self-explanatory. A short full glass, tall half-full glass, and medium nearly-full glass require users to infer both object size and fill ratio, then translate them back into chart tiers while playing. The UI has no visible legend or numeric label.

The two implementations are also not one coherent component:

• The standalone canvas shows five phrases, changes fill color blue → gold → red, and outlines the current phrase in gold.
• Section Map shows sections, uses a fixed amber fill, and relies on section opacity/playhead for current state.
• Installing Section Map silently suppresses and relocates the standalone HUD through window.__slopsmithSectionMapHooksInstalled.
• showGlasses therefore does not identify a stable location or granularity.
• The canvas is pointer-inert and has no accessible name or keyboard-readable details; Section Map exposes information only through hover titles.
• The standalone HUD occupies a fixed top-center overlay at z-index 15 and redraws on every animation frame even though its meaningful inputs change at song load, phrase transition, or mastery change.

The cross-plugin event compounds the separation problem. Difficulty Ladder emits UI decisions (fillPercentage, glassSize) instead of semantic tier values. That makes Section Map inherit this metaphor and prevents alternative renderers from presenting the same data appropriately.

Remediation

Replace the glasses with a difficulty tier rail:

1. Emit a render-neutral event contract containing, per phrase/section:
   • stable id/index and time range;
   • currentTier;
   • topTier (tier where full detail is reached);
   • maxTier;
   • whether the entry is current;
   • optional player context.
2. Render a compact segmented rail. Lit segments show currentTier; a distinct notch/outline marks topTier. Do not encode difficulty by changing the component's physical size.
3. Provide readable detail such as Tier 2 of 4 · full detail at 3 on hover, focus, and an accessible label.
4. Use the same tokens, tier semantics, and current/upcoming treatment in standalone and Section Map presentations. Location/granularity may differ; meaning must not.
5. Make the standalone component event-driven. Update on song/phrase/mastery/settings changes, not every rAF frame.
6. Rename the setting to Show difficulty guide, migrate showGlasses, and state where the guide appears when Section Map is installed.
7. Keep the v2 event available for a transition period or version the new event/schema explicitly so Section Map upgrades do not break by load order.
8. Remove glassSize, glass drawing helpers, glass-specific docs, and the plugin description's glass terminology after the consumer migration lands.

Acceptance Criteria

• A first-time user can identify current tier and full-detail threshold without documentation.
• Standalone and Section Map renderers report identical tier values and visual semantics.
• Missing phrase data produces no guide rather than a zero-tier value.
• Keyboard and screen-reader users can inspect the current and upcoming values.
• No difficulty-guide work runs continuously at 60 fps.
• Split Screen/player-context instances remain isolated.
• Contract tests cover v2 transition behavior and the semantic v3 payload.