kandev/docs/plans/frontend-rendering-cpu/task-04-pause-hidden-motion.md

id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design

id	title	status	wave	depends_on	plan	requirements	acceptance_criteria	system_design
04-pause-hidden-motion	Pause hidden status motion	done	4	03-repair-rendering-trigger	plan.md	REQ-UI-PERSISTENT-STATUS-MOTION-004	AC-UI-PERSISTENT-STATUS-MOTION-004.1 AC-UI-PERSISTENT-STATUS-MOTION-004.2 AC-UI-PERSISTENT-STATUS-MOTION-004.3 AC-UI-PERSISTENT-STATUS-MOTION-004.4 AC-UI-PERSISTENT-STATUS-MOTION-004.5	../../specs/ui/system-design/persistent-status-motion.md

Task 04: Pause hidden status motion

Summary

Pause host-owned persistent status motion while its target is hidden. Resume the current active state without losing updates or replaying settled activity.

In scope

Add a shared lifecycle helper for owned animation handles and integrate spin, pulse, and grid. Observe stable target wrappers, combine document/intersection visibility, and use existing panel visibility where needed. Apply scoped CSS fallback pause/resume. Preserve prior inline styles, cleanup, reduced-motion behavior, and grid stagger. Test mount-hidden, visibility changes, effect replacement, unmount, and settlement while hidden.

Out of scope

Backend/state changes, plugin implementation changes, transcript virtualization, and unmounting user content. No global production animation suppression.

Acceptance

Hidden targets have no running owned effects; visible active targets resume with no duplicate handles. Current state and all non-motion UI behavior survive hidden intervals. Desktop/mobile browser checks and three matched final trace captures record the resulting behavior and performance.

ASCII UI preview

UI-01, excerpt from the combined preview:

Desktop / phone existing task surface:
Visible active -> motion runs
Hidden active  -> motion pauses, state remains current
Visible settled -> settled status
Context ring -> arc transition only

Preserve the existing desktop panels and dedicated phone Chat composition. The work order's frontmatter ACs map this preview to its rendered checks.

Verification

From the repository root, after the plan's one-time dependency bootstrap:

(cd apps/web && rtk pnpm test lib/ui/persistent-motion-visibility.test.tsx lib/ui/compositor-pulse.test.tsx lib/ui/state-icons.test.tsx components/grid-spinner.test.tsx)
(cd apps/web && rtk pnpm run typecheck)
(cd apps/web && rtk pnpm e2e:run --project chromium tests/chat/persistent-animation-motion.spec.ts tests/chat/quick-chat-idle-dot.spec.ts)
(cd apps/web && rtk pnpm e2e:run --project mobile-chrome tests/chat/mobile-persistent-animation-motion.spec.ts tests/chat/mobile-quick-chat-idle-dot.spec.ts)
(cd apps/web && KANDEV_E2E_ANIMATION_TRACE=1 rtk pnpm e2e:run --project chromium tests/chat/animation-performance-trace.spec.ts)
rtk proxy python3 scripts/lint-spec-files.py --all
rtk git diff --check

Record actual discovery counts, failures, and results. Do not substitute a skipped trace run for performance evidence. Implementation uses TDD for changed logic; the attribution work order produces diagnostic evidence first.

Files likely touched

• apps/packages/ui/src/persistent-motion-visibility.tsx (new)
• apps/packages/ui/src/compositor-spin.tsx
• apps/packages/ui/src/compositor-pulse.tsx
• apps/web/components/grid-spinner.tsx
• apps/web/lib/ui/persistent-motion-visibility.test.tsx (new)
• apps/web/lib/ui/compositor-pulse.test.tsx
• apps/web/lib/ui/compositor-spin.test.tsx
• apps/web/lib/ui/state-icons.test.tsx
• apps/web/components/grid-spinner.test.tsx
• apps/web/e2e/helpers/animation-assertions.ts
• apps/web/e2e/tests/chat/persistent-animation-motion.spec.ts
• apps/web/e2e/tests/chat/mobile-persistent-animation-motion.spec.ts
• apps/web/e2e/tests/chat/animation-performance-trace.spec.ts
• apps/web/e2e/tests/chat/context-window-source.spec.ts
• apps/web/e2e/tests/chat/mobile-context-window-source.spec.ts

Dependencies

03-repair-rendering-trigger. See the manifest for evidence gates.

Risks

A hidden document is not the same as a blurred window. Intersection alone may not model all panel visibility. Unsupported observers must not freeze visible feedback. If Task 03 is unreproduced, this bounded work may proceed with that limitation recorded, but the package remains incomplete.

Parallelism

sequential

Inputs

• Requirements.
• Design.
• Existing animation trace, component tests, and desktop/mobile motion specs.
• Baseline findings in plan.md.

Results

Implemented the shared visibility controller in apps/packages/ui/src/persistent-motion-visibility.tsx and integrated it with the compositor spin, pulse, and grid primitives. It combines document and intersection visibility, pauses owned Web Animations and CSS fallbacks, resumes only active effects, and cleans up shared listeners and observers.

Focused unit coverage passed with 90 tests, including the visibility helper, spin, pulse, grid, and ring regressions. Desktop and mobile persistent-motion browser tests passed with 1 test each, including a real scroll across the intersection boundary. Desktop and mobile Quick Chat indicator tests passed with 2 tests each. The review-remediation three-repeat trace passed with non-empty target assertions, a matched script-enabled fallback baseline, and group-specific suppression checks. The supplied trace's production trigger remains unidentified, so this work order does not claim to complete Task 03.