[pullfrog]

Tier rail 4/4 (parent #131). Retires the render-bound v2 section-difficulty surface now that Section Map consumes the semantic v3 contract.

Important

Merge-gated on feedback-plugin-sectionmap#14 — Section Map's migration to the v3 fields is still open upstream. This PR must not merge until that lands; the milestone (M6) and the issue's acceptance criteria both require it.

What changed

screen.js — v2 surface removed

• Dropped SECTIONS_SCHEMA_V2 / SECTIONS_EVENT_V2, the v2 payload, and the difficulty:sections-updated event. The only section-difficulty contract is now difficulty:sections-updated-v3 (difficulty_ladder.sections.v3, Tier rail 1/4: define the render-neutral v3 sections event and its transition policy #156/Tier rail 2/4: render the standalone tier rail (event-driven, accessible) #157).
• Deleted the legacy canvas overlay: GLASS_* constants, ensureHudCanvas, drawHud, _drawHudGlasses/_drawHudBadge and all _hud* sizing/measurement helpers.
• Removed _computeSectionDifficulties, _sectionDifficultyData, and _maxPhraseDifficulty; _emitSectionDifficulties → _sectionsV3Payload only.
• Removed the retired showGlasses one-time forward-migration; only showDifficultyGuide is read (still default on).
• resetPerSongState keeps the _railPhraseIdx resync the rail needs; getPlayerEl/isPlayerActive retained.

settings.html — reads only showDifficultyGuide (guide !== false).

Tests — dropped the v2-only cases, retargeted all event filters to difficulty:sections-updated-v3, and rewrote the presentation test to pin the exact top-level + phrase key sets. node --test → 419 pass / 0 fail.

Docs — scrubbed glass terminology from README.md, INTEGRATION.md, COMPLIANCE.md, PLAYER_CONTEXT.md, CLAUDE.md and MIGRATION.md.

plugin.json — 0.40.3 → 0.41.0; CHANGELOG.md records the breaking change (the only file permitted to name glassSize).

Verification

• node --test → 419/419 pass.
• git grep for glass (case-insensitive) returns only CHANGELOG.md, satisfying the issue's acceptance criterion.
• No dangling references to any removed symbol in the repo.

Breaking change

Any third-party consumer still reading difficulty_ladder.sections.v2 (fillPercentage / glassSize) must migrate to the v3 fields (sections[].top_tier / .current_tier / .has_chart_content). No in-repo consumer remains.

Closes #159.

  ^{｜ View workflow run ｜ via Pullfrog ｜ Using big-pickle (free) ｜ 𝕏}

Summary by Sourcery

Retire the render-bound v2 section-difficulty API and legacy canvas overlay in favor of the v3 semantic contract.

Enhancements:

• Make the render-neutral v3 section-difficulty event the sole section-difficulty integration contract.
• Remove the legacy canvas difficulty overlay and associated presentation-specific section data and terminology.
• Read only the current difficulty-guide setting without migrating the retired predecessor key.

Build:

• Bump the plugin version from 0.40.3 to 0.41.0.

Documentation:

• Update integration, migration, compliance, player-context, README, and project guidance to document the v3 contract and remove retired overlay terminology.
• Document the breaking removal and v3 migration path in the changelog.

Tests:

• Retarget section-event coverage to v3 and strengthen payload tests to enforce the documented field sets.

[sourcery-ai]

Sorry @pullfrog[bot], you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 18 hours and 34 minutes by commenting @sourcery-ai review. Upgrade to get a review now.

[sourcery-ai]

Reviewer's Guide

This breaking change removes the v2 section-difficulty event and its presentation-bound glass payload, deletes the legacy canvas glass HUD and its setting migration, and standardizes all runtime consumers and tests on the render-neutral v3 tier contract; documentation and the plugin version are updated accordingly. Review the external Section Map migration gate before merging.

Sequence diagram for v3 section difficulty emission

sequenceDiagram
    participant Host
    participant DifficultyLadder
    participant SectionMap

    Host->>DifficultyLadder: calculateAndEmitSectionDifficulties()
    DifficultyLadder->>Host: getSections()
    DifficultyLadder->>Host: getPhrases()
    DifficultyLadder->>Host: getMastery()
    DifficultyLadder->>DifficultyLadder: _sectionsV3Payload()
    DifficultyLadder->>SectionMap: difficulty:sections-updated-v3
    SectionMap->>SectionMap: render section difficulty from current_tier, top_tier, has_chart_content

Loading

File-Level Changes

Change	Details	Files
Retire the render-bound v2 section-difficulty API and make the render-neutral v3 event the sole section contract.	Removed the v2 schema, event, payload construction, and legacy difficulty aggregation helpers. Continued emitting only difficulty:sections-updated-v3 with the v3 tier-based payload and capability marker. Updated event-contract, player-context, and Section Map integration documentation for the breaking migration.	screen.js INTEGRATION.md PLAYER_CONTEXT.md COMPLIANCE.md CLAUDE.md MIGRATION.md README.md
Remove the legacy glass canvas HUD and all glass-specific runtime behavior.	Deleted glass constants, canvas creation/drawing, sizing and measurement helpers, HUD animation state, and exports. Retained the event-driven DOM tier rail, scoring loop, player helpers, and rail phrase-index synchronization. Removed the one-time showGlasses storage migration and limited settings reads to showDifficultyGuide with an on-by-default fallback.	screen.js settings.html tests/tier_rail.test.js tests/scoring_pipelines.test.js tests/screen.test.js
Realign tests with the v3-only contract and enforce the published payload shape.	Retargeted section event assertions and split-player lifecycle coverage to the v3 event. Removed v2 and canvas-HUD tests, replacing presentation checks with exact key-set assertions for v3 payload levels. Preserved coverage for tier mapping, null mastery, player context, rail behavior, and section emission cadence.	tests/screen.test.js tests/tier_rail.test.js tests/scoring_pipelines.test.js
Document the breaking removal, terminology cleanup, and release version change.	Scrubbed retired glass terminology and v2 references from project documentation, except for the changelog record. Recorded migration guidance from v2 presentation fields to v3 tier/content fields. Bumped the plugin version from 0.40.3 to 0.41.0 and documented the Section Map merge gate.	CHANGELOG.md README.md INTEGRATION.md COMPLIANCE.md PLAYER_CONTEXT.md CLAUDE.md MIGRATION.md plugin.json

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#159	Retire the v2 section-difficulty event and presentation fields, remove the legacy glass HUD and related code, and eliminate glass terminology outside the changelog.	✅
#159	Document the breaking contract removal, update the plugin version and changelog, and remove obsolete v2 contract cases from tests.	✅
#159	Verify the migrated Section Map works with the v3 payload at the new plugin version, including when Difficulty Ladder is absent.	❌	The PR states that the Section Map migration is still open and that this PR is merge-gated on it. Thus the required post-migration compatibility verification has not yet been completed.

Possibly linked issues

• Tier rail 4/4: remove glassSize, glass drawing and glass terminology after consumers migrate #159: The PR removes the v2 event and glass rendering, scrubs terminology, updates docs/version/changelog, and tests the v3-only contract.
• Tier rail 4/4: remove glassSize, glass drawing and glass terminology after consumers migrate #159: The PR removes glass drawing and v2 fields, relying on Section Map’s v3 migration as the issue requires.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[pullfrog]

ℹ️ Minor suggestions only — one doc inaccuracy inline, plus confirmation of the upstream merge gate below.

Reviewed changes — the full #159 removal on 13cd698: the v2 section-difficulty surface (difficulty:sections-updated, SECTIONS_SCHEMA_V2, _computeSectionDifficulties and friends), the legacy canvas glass HUD (drawHud, ensureHudCanvas, GLASS_*, _hud* cursors, its rAF lifecycle), the showGlasses forward-migration and cross-tab storage adoption, and all glass terminology in docs; tests retargeted to the v3 event with exact payload key-set pins; version bumped to 0.41.0.

• screen.js — v2 event/payload and the entire dead canvas HUD path deleted; _emitSectionDifficulties collapses to a v3-only call with mastery nulled when the host reports none, matching the old reportsMastery ? mastery : null semantics. The DOM tier rail and scoring paths are untouched, so no runtime behavior changes on the active guide.
• settings.html — reads only showDifficultyGuide; the guide !== false default is preserved when the key is absent.
• Tests/docs — 419/419 pass locally on this head, matching the updated CLAUDE.md count; git grep -i glass (and drawHud/_hud/showGlasses/sections.v2) hits only CHANGELOG.md plus two intentional historical mentions, satisfying the acceptance criterion.

ℹ️ The upstream merge gate is real and not yet satisfied

The PR body gates on sectionmap#14; as of this review that issue is still open and its implementation PR (sectionmap#18) is open, not merged. Released Section Map 1.3.0 is v2-only: it finds the capability marker, subscribes to difficulty:sections-updated, and would silently render no section difficulty against this build. Keep the gate until #18 lands; after both sides ship, Section Map owes its own documented follow-up of deleting the now-dead v2 fallback (_smNormalizeSectionTiersV2 / _smOnSectionsUpdated).

Technical details

# Upstream gate status (verified 2026-10-17)

## Affected sites
- PR body / merge sequencing — sectionmap#14 open; sectionmap#18 (the v3
  consumer) open, not merged.
- sectionmap 1.3.0 (released): subscribes to the v2 event after seeing
  `window._ddCapabilities.sectionDifficulty`; this build no longer emits it.

## Required outcome
- Do not merge until sectionmap#18 is merged (and ideally released), so
  upgraded Difficulty Ladder builds never pair with a v2-only Section Map in
  the wild.

## Follow-up owed on the Section Map side
- sectionmap#18 keeps a bounded v2 fallback and its CLAUDE.md instructs
  deleting it once the peer drops v2 — schedule that after both land.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using big-pickle (free) ｜ 𝕏}

[pullfrog]

The failed check was pullfrog-approval ("Pullfrog has outstanding review feedback or requested changes"), not a test/build failure — the suite's only failing run. The one open review thread flagged a doc inaccuracy in README.md's Section Map peer row: it claimed Section Map's v3 consumer reads sections[].phrases[].top_tier/.current_tier, but _smNormalizeSectionTiers (sectionmap#18) reads the section-level Info fields directly.

Fixed in 03d4f7c — the row now reads sections[].top_tier/.current_tier. Verified against sectionmap#18's CLAUDE.md, replied inline, and resolved the thread. Working tree is clean and pushed to pullfrog/159-remove-glass.

Task list (7/7 completed)

• Checkout PR feat: remove glassSize, glass drawing and glass terminology (#159) #231 branch
• Diagnose the failed check suite (pullfrog-approval: outstanding review feedback)
• Verify failure was introduced by this PR
• Fix the doc inaccuracy and verify
• Commit and push to the PR branch
• Reply to and resolve the review thread
• Report progress

  ^{｜ View workflow run ｜ via Pullfrog ｜ Using big-pickle (free) ｜ 𝕏}

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Files Reviewed (13 files)

• CHANGELOG.md
• CLAUDE.md
• COMPLIANCE.md
• INTEGRATION.md
• MIGRATION.md
• PLAYER_CONTEXT.md
• README.md
• plugin.json
• screen.js
• settings.html
• tests/scoring_pipelines.test.js
• tests/screen.test.js
• tests/tier_rail.test.js

---

_{Reviewed by efficient · Input: 164.8K · Output: 9.9K · Cached: 364.8K}