initiative/specs/033-fix-concentration-glow-clip/spec.md

Feature Specification: Fix Concentration Shake Glow Clipping

Feature Branch: 033-fix-concentration-glow-clip Created: 2026-03-11 Status: Draft Input: User description: "Fix concentration shake glow clipped at container edges"

User Scenarios & Testing (mandatory)

User Story 1 - Concentration Damage Glow Visible (Priority: P1)

As a game master viewing the encounter tracker, when a concentrating creature takes damage and the shake + glow animation plays, I see the full glow effect without any visual clipping on the left or right edges.

Why this priority: This is the core bug being fixed. The glow animation is the primary visual feedback for concentration damage events, and clipping undermines its purpose.

Independent Test: Can be tested by dealing damage to a concentrating creature and visually verifying the glow extends fully without being cut off at container boundaries.

Acceptance Scenarios:

1. Given a creature is concentrating on a spell, When the creature takes damage and the shake + glow animation triggers, Then the glow effect is fully visible on both the left and right sides throughout the entire animation duration
2. Given a creature is concentrating and the encounter list has its default layout, When damage triggers the animation, Then no part of the glow is clipped or hidden by overflow constraints

---

User Story 2 - No Layout Side Effects (Priority: P1)

As a user on any device, the glow fix does not introduce horizontal scrollbars, layout shifts, or visual artifacts outside the animation area.

Why this priority: A fix that trades one visual bug for another (e.g., scroll jank) would be a regression. This is equally critical as the glow fix itself.

Independent Test: Can be tested by triggering the animation repeatedly on both desktop and mobile viewports and confirming no horizontal scrollbar appears and no elements shift position.

Acceptance Scenarios:

1. Given the encounter tracker is displayed at desktop width, When the shake + glow animation plays, Then no horizontal scrollbar appears on the page or encounter container
2. Given the encounter tracker is displayed at mobile width (320px - 480px), When the shake + glow animation plays, Then no layout shift occurs and the animation renders correctly within the viewport

---

Edge Cases

• What happens when multiple concentrating creatures take damage simultaneously? The glow on each row must remain independently visible without overlap artifacts.
• What happens when the creature row is at the very top or bottom of a scrollable encounter list? The glow must still be fully visible.
• What happens on very narrow viewports (below 320px)? The glow should degrade gracefully without causing overflow.

Requirements (mandatory)

Functional Requirements

• FR-001: The concentration damage glow effect MUST be fully visible on both left and right edges of the combatant row throughout the shake animation
• FR-002: The glow fix MUST NOT introduce a horizontal scrollbar on the page or any parent container
• FR-003: The glow fix MUST NOT cause any layout shift or repositioning of other elements during or after the animation
• FR-004: The shake + glow animation MUST render correctly on mobile-width screens (320px and above)
• FR-005: The glow effect MUST remain visually correct when multiple combatant rows animate simultaneously

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: The glow effect is visually complete (no clipping) on 100% of concentration damage events across all supported viewport widths (320px and above)
• SC-002: Zero horizontal scrollbar appearances caused by the glow animation at any viewport width
• SC-003: Zero measurable layout shift (CLS = 0) introduced by the animation fix

Assumptions

• The existing shake animation behavior and timing are correct and should be preserved; only the glow clipping needs to be fixed.
• The glow effect uses CSS techniques (e.g., box-shadow, outline, or pseudo-elements) that may be clipped by overflow: hidden or similar properties on ancestor containers.
• "Mobile-width screens" refers to viewports of 320px width and above, consistent with standard mobile device support.