Scroll a coach-mark's anchor into view — a code-level reading (PR #157)

What changed, and why

A coaching step floats a small coach-mark beside a live control. When that control sits inside the scrollable compose dock — the figure picker, the message box, the wager chip, the send button — and the dock has scrolled it out of view, the control still reports a real, non-zero on-screen box. So the mark anchored to a point nobody could see: off-screen on mobile, and on desktop too. The phone tab-switch brings the right tab forward but never scrolls within the dock to the specific control.

The whole fix is one composable. useCoachAnchor already resolves a step's control to a live rect and tracks it; now, on a real step change, it also scrolls that control into view — the first moment the control actually resolves visible. No page wiring changed, no selector logic duplicated. Blast radius is the guided first-run tour alone: the composable runs nowhere else.

The contract, with the new step-entry behavior spelled out.

composables/useCoachAnchor.ts · 178 lines

composables/useCoachAnchor.ts178 lines · TypeScript

⋯ 17 lines hidden (lines 1–17)1import { ref, watch, onMounted, onBeforeUnmount, type Ref } from 'vue'
2 
3/** A target's live position in viewport coordinates. */
4export interface AnchorRect {
  top: number
  left: number
  width: number
  height: number
9}
10 
11export interface CoachAnchor {
  /** The resolved target's rect, or null when nothing's anchored/visible. */
  rect: Ref<AnchorRect | null>
  /** True when one of the selectors resolved to a visible element. */
  present: Ref<boolean>
16}
17 
18/**
* Resolve the first visible target among an ordered list of CSS selectors to a
* live viewport rect, tracked as the page scrolls, resizes, or rearranges — and,
* on a real step change, scroll that target into view on entry (see below). The
* ordered list is how a step falls back from a conditional control (the ⚡ chip)
* to an always-present one (the general ⚡ line).
*
* Returns present=false when no selector resolves to a *visible* element —
* missing, zero-area, display:none, or sitting in an inactive phone-tab panel —
* so the caller can detach to a corner. SSR-safe: inert until mounted, and the
* heavy observers run only while a selector list is set (i.e. while a tour beat
* is on screen), so there's no idle cost on the board.
*
* On a real step change (a new selector list) the freshly-resolved control is
* scrolled into view the first moment it resolves visible — so the mark never
* points at a control rendered but scrolled out of the compose dock, the one
* thing a phone tab-switch alone can't fix (issue #142). Gated on visibility, it
* naturally waits out that tab-switch instead of racing it.
*/
⋯ 142 lines hidden (lines 37–178)37export function useCoachAnchor(selectors: Ref<string[] | null>): CoachAnchor {
  const rect = ref<AnchorRect | null>(null)
  const present = ref(false)
40 
  function measure(el: Element): AnchorRect | null {
      // A zero-area rect is how a hidden control reads — display:none (an inactive
      // phone-tab panel) or an unrendered conditional chip both collapse to 0×0,
      // so the caller falls back instead of anchoring to a point nobody can see.
      const r = el.getBoundingClientRect()
      if (r.width === 0 && r.height === 0) return null
      return { top: r.top, left: r.left, width: r.width, height: r.height }
  }
49 
  function resolve() {
      const list = selectors.value
      if (!list || !list.length || typeof document === 'undefined') {
          rect.value = null
          present.value = false
          return
      }
      for (const sel of list) {
          const el = document.querySelector(sel)
          if (!el) continue
          const measured = measure(el)
          if (measured) {
              rect.value = measured
              present.value = true
              // First visible resolution of a new beat: bring the control into view.
              if (pendingScroll) {
                  pendingScroll = false
                  scrollAnchorIntoView(el)
              }
              return
          }
      }
      rect.value = null
      present.value = false
  }
75 
  // A real step change asks for its anchor to be scrolled into view once it
  // resolves visible — see resolve(). One-shot per beat: armed on entry below,
  // disarmed by the first scroll, so repositions within the beat never re-scroll.
  let pendingScroll = false
80 
  // Bring the beat's freshly-resolved control into view before the mark places — a
  // control rendered but scrolled out of the compose dock (mobile AND desktop)
  // otherwise leaves the mark pointing at an off-screen spot (issue #142). This is
  // the lone bit of MOTION here, so — unlike the event-driven tracking below — it
  // honors prefers-reduced-motion, snapping instantly when motion is off. block:
  // 'center' keeps room above and below for the card whichever way it places.
  function scrollAnchorIntoView(el: Element) {
      if (typeof el.scrollIntoView !== 'function') return
      // Read fresh here, not via usePrefersReducedMotion — a one-shot imperative
      // read at scroll time, not a reactive binding (mirrors stores/audio.ts).
      const reduce =
          typeof window !== 'undefined' &&
          typeof window.matchMedia === 'function' &&
          window.matchMedia('(prefers-reduced-motion: reduce)').matches
      el.scrollIntoView({ block: 'center', inline: 'nearest', behavior: reduce ? 'instant' : 'smooth' })
  }
97 
  // rAF-coalesced so a burst of scroll/mutation events repositions at most once
  // per frame. Event-driven layout sync, NOT an animation loop (nothing
  // self-re-arms), so it needs no reduced-motion guard.
  let frame = 0
  function schedule() {
      if (frame || typeof requestAnimationFrame === 'undefined') {
          if (typeof requestAnimationFrame === 'undefined') resolve()
          return
      }
      frame = requestAnimationFrame(() => {
          frame = 0
          resolve()
      })
  }
112 
  let tracking = false
  let ro: ResizeObserver | null = null
  let mo: MutationObserver | null = null
116 
  function start() {
      if (tracking || typeof window === 'undefined') return
      tracking = true
      resolve()
      window.addEventListener('scroll', schedule, { capture: true, passive: true })
      window.addEventListener('resize', schedule, { passive: true })
      if (typeof ResizeObserver !== 'undefined') {
          ro = new ResizeObserver(schedule)
          ro.observe(document.documentElement)
      }
      // Conditional controls (the ⚡ chip, the dice, a phone-tab swap) come and go
      // without a scroll or resize — watch the tree so the anchor re-resolves.
      if (typeof MutationObserver !== 'undefined') {
          mo = new MutationObserver(schedule)
          mo.observe(document.body, { childList: true, subtree: true, attributes: true })
      }
  }
134 
  function stop() {
      tracking = false
      if (frame) {
          cancelAnimationFrame(frame)
          frame = 0
      }
      if (typeof window !== 'undefined') {
          window.removeEventListener('scroll', schedule, { capture: true } as EventListenerOptions)
          window.removeEventListener('resize', schedule)
      }
      ro?.disconnect()
      ro = null
      mo?.disconnect()
      mo = null
      // Disarm here too, so the one-shot is local to this lifecycle: a beat armed
      // but never resolved-visible (its panel never came forward) can't leave a
      // stale latch that a later resolve() would honor on a torn-down beat.
      pendingScroll = false
      rect.value = null
      present.value = false
  }
156 
  onMounted(() => {
      if (selectors.value?.length) {
          pendingScroll = true
          start()
      }
  })
163 
  watch(selectors, (list) => {
      if (!list || !list.length) {
          stop()
          return
      }
      // A new beat's anchors — scroll its control into view once resolved (resolve()).
      pendingScroll = true
      if (!tracking) start()
      else resolve()
  })
174 
  onBeforeUnmount(stop)
176 
  return { rect, present }
178}

The scroll, where resolution already happens

resolve() walks the step's ordered selectors and stops at the first with a non-zero box — unchanged. The new lines fire only on the first visible resolution of a fresh step: scroll the control into view, then disarm the latch. The order on lines 66–67 is deliberate. A smooth scroll fires its own scroll events, which re-enter resolve(); clearing the latch before the scroll means that re-entry finds it already spent, so the scroll can never fire twice.

resolve(): the first visible hit now also scrolls — once.

composables/useCoachAnchor.ts · 178 lines

composables/useCoachAnchor.ts178 lines · TypeScript

⋯ 49 lines hidden (lines 1–49)1import { ref, watch, onMounted, onBeforeUnmount, type Ref } from 'vue'
2 
3/** A target's live position in viewport coordinates. */
4export interface AnchorRect {
  top: number
  left: number
  width: number
  height: number
9}
10 
11export interface CoachAnchor {
  /** The resolved target's rect, or null when nothing's anchored/visible. */
  rect: Ref<AnchorRect | null>
  /** True when one of the selectors resolved to a visible element. */
  present: Ref<boolean>
16}
17 
18/**
* Resolve the first visible target among an ordered list of CSS selectors to a
* live viewport rect, tracked as the page scrolls, resizes, or rearranges — and,
* on a real step change, scroll that target into view on entry (see below). The
* ordered list is how a step falls back from a conditional control (the ⚡ chip)
* to an always-present one (the general ⚡ line).
*
* Returns present=false when no selector resolves to a *visible* element —
* missing, zero-area, display:none, or sitting in an inactive phone-tab panel —
* so the caller can detach to a corner. SSR-safe: inert until mounted, and the
* heavy observers run only while a selector list is set (i.e. while a tour beat
* is on screen), so there's no idle cost on the board.
*
* On a real step change (a new selector list) the freshly-resolved control is
* scrolled into view the first moment it resolves visible — so the mark never
* points at a control rendered but scrolled out of the compose dock, the one
* thing a phone tab-switch alone can't fix (issue #142). Gated on visibility, it
* naturally waits out that tab-switch instead of racing it.
*/
37export function useCoachAnchor(selectors: Ref<string[] | null>): CoachAnchor {
  const rect = ref<AnchorRect | null>(null)
  const present = ref(false)
40 
  function measure(el: Element): AnchorRect | null {
      // A zero-area rect is how a hidden control reads — display:none (an inactive
      // phone-tab panel) or an unrendered conditional chip both collapse to 0×0,
      // so the caller falls back instead of anchoring to a point nobody can see.
      const r = el.getBoundingClientRect()
      if (r.width === 0 && r.height === 0) return null
      return { top: r.top, left: r.left, width: r.width, height: r.height }
  }
49 
  function resolve() {
      const list = selectors.value
      if (!list || !list.length || typeof document === 'undefined') {
          rect.value = null
          present.value = false
          return
      }
      for (const sel of list) {
          const el = document.querySelector(sel)
          if (!el) continue
          const measured = measure(el)
          if (measured) {
              rect.value = measured
              present.value = true
              // First visible resolution of a new beat: bring the control into view.
              if (pendingScroll) {
                  pendingScroll = false
                  scrollAnchorIntoView(el)
              }
              return
          }
      }
      rect.value = null
      present.value = false
  }
⋯ 104 lines hidden (lines 75–178)75 
  // A real step change asks for its anchor to be scrolled into view once it
  // resolves visible — see resolve(). One-shot per beat: armed on entry below,
  // disarmed by the first scroll, so repositions within the beat never re-scroll.
  let pendingScroll = false
80 
  // Bring the beat's freshly-resolved control into view before the mark places — a
  // control rendered but scrolled out of the compose dock (mobile AND desktop)
  // otherwise leaves the mark pointing at an off-screen spot (issue #142). This is
  // the lone bit of MOTION here, so — unlike the event-driven tracking below — it
  // honors prefers-reduced-motion, snapping instantly when motion is off. block:
  // 'center' keeps room above and below for the card whichever way it places.
  function scrollAnchorIntoView(el: Element) {
      if (typeof el.scrollIntoView !== 'function') return
      // Read fresh here, not via usePrefersReducedMotion — a one-shot imperative
      // read at scroll time, not a reactive binding (mirrors stores/audio.ts).
      const reduce =
          typeof window !== 'undefined' &&
          typeof window.matchMedia === 'function' &&
          window.matchMedia('(prefers-reduced-motion: reduce)').matches
      el.scrollIntoView({ block: 'center', inline: 'nearest', behavior: reduce ? 'instant' : 'smooth' })
  }
97 
  // rAF-coalesced so a burst of scroll/mutation events repositions at most once
  // per frame. Event-driven layout sync, NOT an animation loop (nothing
  // self-re-arms), so it needs no reduced-motion guard.
  let frame = 0
  function schedule() {
      if (frame || typeof requestAnimationFrame === 'undefined') {
          if (typeof requestAnimationFrame === 'undefined') resolve()
          return
      }
      frame = requestAnimationFrame(() => {
          frame = 0
          resolve()
      })
  }
112 
  let tracking = false
  let ro: ResizeObserver | null = null
  let mo: MutationObserver | null = null
116 
  function start() {
      if (tracking || typeof window === 'undefined') return
      tracking = true
      resolve()
      window.addEventListener('scroll', schedule, { capture: true, passive: true })
      window.addEventListener('resize', schedule, { passive: true })
      if (typeof ResizeObserver !== 'undefined') {
          ro = new ResizeObserver(schedule)
          ro.observe(document.documentElement)
      }
      // Conditional controls (the ⚡ chip, the dice, a phone-tab swap) come and go
      // without a scroll or resize — watch the tree so the anchor re-resolves.
      if (typeof MutationObserver !== 'undefined') {
          mo = new MutationObserver(schedule)
          mo.observe(document.body, { childList: true, subtree: true, attributes: true })
      }
  }
134 
  function stop() {
      tracking = false
      if (frame) {
          cancelAnimationFrame(frame)
          frame = 0
      }
      if (typeof window !== 'undefined') {
          window.removeEventListener('scroll', schedule, { capture: true } as EventListenerOptions)
          window.removeEventListener('resize', schedule)
      }
      ro?.disconnect()
      ro = null
      mo?.disconnect()
      mo = null
      // Disarm here too, so the one-shot is local to this lifecycle: a beat armed
      // but never resolved-visible (its panel never came forward) can't leave a
      // stale latch that a later resolve() would honor on a torn-down beat.
      pendingScroll = false
      rect.value = null
      present.value = false
  }
156 
  onMounted(() => {
      if (selectors.value?.length) {
          pendingScroll = true
          start()
      }
  })
163 
  watch(selectors, (list) => {
      if (!list || !list.length) {
          stop()
          return
      }
      // A new beat's anchors — scroll its control into view once resolved (resolve()).
      pendingScroll = true
      if (!tracking) start()
      else resolve()
  })
174 
  onBeforeUnmount(stop)
176 
  return { rect, present }
178}

The scroll itself is a single call. block: 'center' leaves room above and below for the card whichever side it places on. behavior is the only motion this composable makes, so it reads prefers-reduced-motion fresh at scroll time and snaps instantly when motion is off.

One guarded call; reduced-motion read fresh, not via a reactive ref.

composables/useCoachAnchor.ts · 178 lines

composables/useCoachAnchor.ts178 lines · TypeScript

⋯ 80 lines hidden (lines 1–80)1import { ref, watch, onMounted, onBeforeUnmount, type Ref } from 'vue'
2 
3/** A target's live position in viewport coordinates. */
4export interface AnchorRect {
  top: number
  left: number
  width: number
  height: number
9}
10 
11export interface CoachAnchor {
  /** The resolved target's rect, or null when nothing's anchored/visible. */
  rect: Ref<AnchorRect | null>
  /** True when one of the selectors resolved to a visible element. */
  present: Ref<boolean>
16}
17 
18/**
* Resolve the first visible target among an ordered list of CSS selectors to a
* live viewport rect, tracked as the page scrolls, resizes, or rearranges — and,
* on a real step change, scroll that target into view on entry (see below). The
* ordered list is how a step falls back from a conditional control (the ⚡ chip)
* to an always-present one (the general ⚡ line).
*
* Returns present=false when no selector resolves to a *visible* element —
* missing, zero-area, display:none, or sitting in an inactive phone-tab panel —
* so the caller can detach to a corner. SSR-safe: inert until mounted, and the
* heavy observers run only while a selector list is set (i.e. while a tour beat
* is on screen), so there's no idle cost on the board.
*
* On a real step change (a new selector list) the freshly-resolved control is
* scrolled into view the first moment it resolves visible — so the mark never
* points at a control rendered but scrolled out of the compose dock, the one
* thing a phone tab-switch alone can't fix (issue #142). Gated on visibility, it
* naturally waits out that tab-switch instead of racing it.
*/
37export function useCoachAnchor(selectors: Ref<string[] | null>): CoachAnchor {
  const rect = ref<AnchorRect | null>(null)
  const present = ref(false)
40 
  function measure(el: Element): AnchorRect | null {
      // A zero-area rect is how a hidden control reads — display:none (an inactive
      // phone-tab panel) or an unrendered conditional chip both collapse to 0×0,
      // so the caller falls back instead of anchoring to a point nobody can see.
      const r = el.getBoundingClientRect()
      if (r.width === 0 && r.height === 0) return null
      return { top: r.top, left: r.left, width: r.width, height: r.height }
  }
49 
  function resolve() {
      const list = selectors.value
      if (!list || !list.length || typeof document === 'undefined') {
          rect.value = null
          present.value = false
          return
      }
      for (const sel of list) {
          const el = document.querySelector(sel)
          if (!el) continue
          const measured = measure(el)
          if (measured) {
              rect.value = measured
              present.value = true
              // First visible resolution of a new beat: bring the control into view.
              if (pendingScroll) {
                  pendingScroll = false
                  scrollAnchorIntoView(el)
              }
              return
          }
      }
      rect.value = null
      present.value = false
  }
75 
  // A real step change asks for its anchor to be scrolled into view once it
  // resolves visible — see resolve(). One-shot per beat: armed on entry below,
  // disarmed by the first scroll, so repositions within the beat never re-scroll.
  let pendingScroll = false
80 
  // Bring the beat's freshly-resolved control into view before the mark places — a
  // control rendered but scrolled out of the compose dock (mobile AND desktop)
  // otherwise leaves the mark pointing at an off-screen spot (issue #142). This is
  // the lone bit of MOTION here, so — unlike the event-driven tracking below — it
  // honors prefers-reduced-motion, snapping instantly when motion is off. block:
  // 'center' keeps room above and below for the card whichever way it places.
  function scrollAnchorIntoView(el: Element) {
      if (typeof el.scrollIntoView !== 'function') return
      // Read fresh here, not via usePrefersReducedMotion — a one-shot imperative
      // read at scroll time, not a reactive binding (mirrors stores/audio.ts).
      const reduce =
          typeof window !== 'undefined' &&
          typeof window.matchMedia === 'function' &&
          window.matchMedia('(prefers-reduced-motion: reduce)').matches
      el.scrollIntoView({ block: 'center', inline: 'nearest', behavior: reduce ? 'instant' : 'smooth' })
  }
⋯ 82 lines hidden (lines 97–178)97 
  // rAF-coalesced so a burst of scroll/mutation events repositions at most once
  // per frame. Event-driven layout sync, NOT an animation loop (nothing
  // self-re-arms), so it needs no reduced-motion guard.
  let frame = 0
  function schedule() {
      if (frame || typeof requestAnimationFrame === 'undefined') {
          if (typeof requestAnimationFrame === 'undefined') resolve()
          return
      }
      frame = requestAnimationFrame(() => {
          frame = 0
          resolve()
      })
  }
112 
  let tracking = false
  let ro: ResizeObserver | null = null
  let mo: MutationObserver | null = null
116 
  function start() {
      if (tracking || typeof window === 'undefined') return
      tracking = true
      resolve()
      window.addEventListener('scroll', schedule, { capture: true, passive: true })
      window.addEventListener('resize', schedule, { passive: true })
      if (typeof ResizeObserver !== 'undefined') {
          ro = new ResizeObserver(schedule)
          ro.observe(document.documentElement)
      }
      // Conditional controls (the ⚡ chip, the dice, a phone-tab swap) come and go
      // without a scroll or resize — watch the tree so the anchor re-resolves.
      if (typeof MutationObserver !== 'undefined') {
          mo = new MutationObserver(schedule)
          mo.observe(document.body, { childList: true, subtree: true, attributes: true })
      }
  }
134 
  function stop() {
      tracking = false
      if (frame) {
          cancelAnimationFrame(frame)
          frame = 0
      }
      if (typeof window !== 'undefined') {
          window.removeEventListener('scroll', schedule, { capture: true } as EventListenerOptions)
          window.removeEventListener('resize', schedule)
      }
      ro?.disconnect()
      ro = null
      mo?.disconnect()
      mo = null
      // Disarm here too, so the one-shot is local to this lifecycle: a beat armed
      // but never resolved-visible (its panel never came forward) can't leave a
      // stale latch that a later resolve() would honor on a torn-down beat.
      pendingScroll = false
      rect.value = null
      present.value = false
  }
156 
  onMounted(() => {
      if (selectors.value?.length) {
          pendingScroll = true
          start()
      }
  })
163 
  watch(selectors, (list) => {
      if (!list || !list.length) {
          stop()
          return
      }
      // A new beat's anchors — scroll its control into view once resolved (resolve()).
      pendingScroll = true
      if (!tracking) start()
      else resolve()
  })
174 
  onBeforeUnmount(stop)
176 
  return { rect, present }
178}

A one-shot latch, armed on entry and flushed on visibility

pendingScroll is a single boolean, armed only when a new selector list arrives — a real step change — in onMounted for the first beat and in the selectors watcher for every beat after. Nothing else arms it, so a reposition (scroll, resize, a mutation) never re-scrolls, and a player who scrolled away mid-beat is left alone.

Armed on a real step change — never on a reposition.

composables/useCoachAnchor.ts · 178 lines

composables/useCoachAnchor.ts178 lines · TypeScript

⋯ 156 lines hidden (lines 1–156)1import { ref, watch, onMounted, onBeforeUnmount, type Ref } from 'vue'
2 
3/** A target's live position in viewport coordinates. */
4export interface AnchorRect {
  top: number
  left: number
  width: number
  height: number
9}
10 
11export interface CoachAnchor {
  /** The resolved target's rect, or null when nothing's anchored/visible. */
  rect: Ref<AnchorRect | null>
  /** True when one of the selectors resolved to a visible element. */
  present: Ref<boolean>
16}
17 
18/**
* Resolve the first visible target among an ordered list of CSS selectors to a
* live viewport rect, tracked as the page scrolls, resizes, or rearranges — and,
* on a real step change, scroll that target into view on entry (see below). The
* ordered list is how a step falls back from a conditional control (the ⚡ chip)
* to an always-present one (the general ⚡ line).
*
* Returns present=false when no selector resolves to a *visible* element —
* missing, zero-area, display:none, or sitting in an inactive phone-tab panel —
* so the caller can detach to a corner. SSR-safe: inert until mounted, and the
* heavy observers run only while a selector list is set (i.e. while a tour beat
* is on screen), so there's no idle cost on the board.
*
* On a real step change (a new selector list) the freshly-resolved control is
* scrolled into view the first moment it resolves visible — so the mark never
* points at a control rendered but scrolled out of the compose dock, the one
* thing a phone tab-switch alone can't fix (issue #142). Gated on visibility, it
* naturally waits out that tab-switch instead of racing it.
*/
37export function useCoachAnchor(selectors: Ref<string[] | null>): CoachAnchor {
  const rect = ref<AnchorRect | null>(null)
  const present = ref(false)
40 
  function measure(el: Element): AnchorRect | null {
      // A zero-area rect is how a hidden control reads — display:none (an inactive
      // phone-tab panel) or an unrendered conditional chip both collapse to 0×0,
      // so the caller falls back instead of anchoring to a point nobody can see.
      const r = el.getBoundingClientRect()
      if (r.width === 0 && r.height === 0) return null
      return { top: r.top, left: r.left, width: r.width, height: r.height }
  }
49 
  function resolve() {
      const list = selectors.value
      if (!list || !list.length || typeof document === 'undefined') {
          rect.value = null
          present.value = false
          return
      }
      for (const sel of list) {
          const el = document.querySelector(sel)
          if (!el) continue
          const measured = measure(el)
          if (measured) {
              rect.value = measured
              present.value = true
              // First visible resolution of a new beat: bring the control into view.
              if (pendingScroll) {
                  pendingScroll = false
                  scrollAnchorIntoView(el)
              }
              return
          }
      }
      rect.value = null
      present.value = false
  }
75 
  // A real step change asks for its anchor to be scrolled into view once it
  // resolves visible — see resolve(). One-shot per beat: armed on entry below,
  // disarmed by the first scroll, so repositions within the beat never re-scroll.
  let pendingScroll = false
80 
  // Bring the beat's freshly-resolved control into view before the mark places — a
  // control rendered but scrolled out of the compose dock (mobile AND desktop)
  // otherwise leaves the mark pointing at an off-screen spot (issue #142). This is
  // the lone bit of MOTION here, so — unlike the event-driven tracking below — it
  // honors prefers-reduced-motion, snapping instantly when motion is off. block:
  // 'center' keeps room above and below for the card whichever way it places.
  function scrollAnchorIntoView(el: Element) {
      if (typeof el.scrollIntoView !== 'function') return
      // Read fresh here, not via usePrefersReducedMotion — a one-shot imperative
      // read at scroll time, not a reactive binding (mirrors stores/audio.ts).
      const reduce =
          typeof window !== 'undefined' &&
          typeof window.matchMedia === 'function' &&
          window.matchMedia('(prefers-reduced-motion: reduce)').matches
      el.scrollIntoView({ block: 'center', inline: 'nearest', behavior: reduce ? 'instant' : 'smooth' })
  }
97 
  // rAF-coalesced so a burst of scroll/mutation events repositions at most once
  // per frame. Event-driven layout sync, NOT an animation loop (nothing
  // self-re-arms), so it needs no reduced-motion guard.
  let frame = 0
  function schedule() {
      if (frame || typeof requestAnimationFrame === 'undefined') {
          if (typeof requestAnimationFrame === 'undefined') resolve()
          return
      }
      frame = requestAnimationFrame(() => {
          frame = 0
          resolve()
      })
  }
112 
  let tracking = false
  let ro: ResizeObserver | null = null
  let mo: MutationObserver | null = null
116 
  function start() {
      if (tracking || typeof window === 'undefined') return
      tracking = true
      resolve()
      window.addEventListener('scroll', schedule, { capture: true, passive: true })
      window.addEventListener('resize', schedule, { passive: true })
      if (typeof ResizeObserver !== 'undefined') {
          ro = new ResizeObserver(schedule)
          ro.observe(document.documentElement)
      }
      // Conditional controls (the ⚡ chip, the dice, a phone-tab swap) come and go
      // without a scroll or resize — watch the tree so the anchor re-resolves.
      if (typeof MutationObserver !== 'undefined') {
          mo = new MutationObserver(schedule)
          mo.observe(document.body, { childList: true, subtree: true, attributes: true })
      }
  }
134 
  function stop() {
      tracking = false
      if (frame) {
          cancelAnimationFrame(frame)
          frame = 0
      }
      if (typeof window !== 'undefined') {
          window.removeEventListener('scroll', schedule, { capture: true } as EventListenerOptions)
          window.removeEventListener('resize', schedule)
      }
      ro?.disconnect()
      ro = null
      mo?.disconnect()
      mo = null
      // Disarm here too, so the one-shot is local to this lifecycle: a beat armed
      // but never resolved-visible (its panel never came forward) can't leave a
      // stale latch that a later resolve() would honor on a torn-down beat.
      pendingScroll = false
      rect.value = null
      present.value = false
  }
156 
  onMounted(() => {
      if (selectors.value?.length) {
          pendingScroll = true
          start()
      }
  })
163 
  watch(selectors, (list) => {
      if (!list || !list.length) {
          stop()
          return
      }
      // A new beat's anchors — scroll its control into view once resolved (resolve()).
      pendingScroll = true
      if (!tracking) start()
      else resolve()
  })
⋯ 5 lines hidden (lines 174–178)174 
  onBeforeUnmount(stop)
176 
  return { rect, present }
178}

Arming a step whose control is hidden — an inactive phone-tab panel, where the control reports a 0×0 box — does not scroll yet; the latch stays armed. When the tab comes forward and the panel renders, the MutationObserver already watching the tree re-runs resolve(), the control now measures visible, and the deferred scroll fires. Gated on visibility, the scroll waits out the tab-switch instead of racing it. The same mechanism covers desktop, where the control is visible at once and the scroll fires immediately on entry.

Teardown disarms the latch too, so a never-shown beat leaves nothing stale.

composables/useCoachAnchor.ts · 178 lines

composables/useCoachAnchor.ts178 lines · TypeScript

⋯ 144 lines hidden (lines 1–144)1import { ref, watch, onMounted, onBeforeUnmount, type Ref } from 'vue'
2 
3/** A target's live position in viewport coordinates. */
4export interface AnchorRect {
  top: number
  left: number
  width: number
  height: number
9}
10 
11export interface CoachAnchor {
  /** The resolved target's rect, or null when nothing's anchored/visible. */
  rect: Ref<AnchorRect | null>
  /** True when one of the selectors resolved to a visible element. */
  present: Ref<boolean>
16}
17 
18/**
* Resolve the first visible target among an ordered list of CSS selectors to a
* live viewport rect, tracked as the page scrolls, resizes, or rearranges — and,
* on a real step change, scroll that target into view on entry (see below). The
* ordered list is how a step falls back from a conditional control (the ⚡ chip)
* to an always-present one (the general ⚡ line).
*
* Returns present=false when no selector resolves to a *visible* element —
* missing, zero-area, display:none, or sitting in an inactive phone-tab panel —
* so the caller can detach to a corner. SSR-safe: inert until mounted, and the
* heavy observers run only while a selector list is set (i.e. while a tour beat
* is on screen), so there's no idle cost on the board.
*
* On a real step change (a new selector list) the freshly-resolved control is
* scrolled into view the first moment it resolves visible — so the mark never
* points at a control rendered but scrolled out of the compose dock, the one
* thing a phone tab-switch alone can't fix (issue #142). Gated on visibility, it
* naturally waits out that tab-switch instead of racing it.
*/
37export function useCoachAnchor(selectors: Ref<string[] | null>): CoachAnchor {
  const rect = ref<AnchorRect | null>(null)
  const present = ref(false)
40 
  function measure(el: Element): AnchorRect | null {
      // A zero-area rect is how a hidden control reads — display:none (an inactive
      // phone-tab panel) or an unrendered conditional chip both collapse to 0×0,
      // so the caller falls back instead of anchoring to a point nobody can see.
      const r = el.getBoundingClientRect()
      if (r.width === 0 && r.height === 0) return null
      return { top: r.top, left: r.left, width: r.width, height: r.height }
  }
49 
  function resolve() {
      const list = selectors.value
      if (!list || !list.length || typeof document === 'undefined') {
          rect.value = null
          present.value = false
          return
      }
      for (const sel of list) {
          const el = document.querySelector(sel)
          if (!el) continue
          const measured = measure(el)
          if (measured) {
              rect.value = measured
              present.value = true
              // First visible resolution of a new beat: bring the control into view.
              if (pendingScroll) {
                  pendingScroll = false
                  scrollAnchorIntoView(el)
              }
              return
          }
      }
      rect.value = null
      present.value = false
  }
75 
  // A real step change asks for its anchor to be scrolled into view once it
  // resolves visible — see resolve(). One-shot per beat: armed on entry below,
  // disarmed by the first scroll, so repositions within the beat never re-scroll.
  let pendingScroll = false
80 
  // Bring the beat's freshly-resolved control into view before the mark places — a
  // control rendered but scrolled out of the compose dock (mobile AND desktop)
  // otherwise leaves the mark pointing at an off-screen spot (issue #142). This is
  // the lone bit of MOTION here, so — unlike the event-driven tracking below — it
  // honors prefers-reduced-motion, snapping instantly when motion is off. block:
  // 'center' keeps room above and below for the card whichever way it places.
  function scrollAnchorIntoView(el: Element) {
      if (typeof el.scrollIntoView !== 'function') return
      // Read fresh here, not via usePrefersReducedMotion — a one-shot imperative
      // read at scroll time, not a reactive binding (mirrors stores/audio.ts).
      const reduce =
          typeof window !== 'undefined' &&
          typeof window.matchMedia === 'function' &&
          window.matchMedia('(prefers-reduced-motion: reduce)').matches
      el.scrollIntoView({ block: 'center', inline: 'nearest', behavior: reduce ? 'instant' : 'smooth' })
  }
97 
  // rAF-coalesced so a burst of scroll/mutation events repositions at most once
  // per frame. Event-driven layout sync, NOT an animation loop (nothing
  // self-re-arms), so it needs no reduced-motion guard.
  let frame = 0
  function schedule() {
      if (frame || typeof requestAnimationFrame === 'undefined') {
          if (typeof requestAnimationFrame === 'undefined') resolve()
          return
      }
      frame = requestAnimationFrame(() => {
          frame = 0
          resolve()
      })
  }
112 
  let tracking = false
  let ro: ResizeObserver | null = null
  let mo: MutationObserver | null = null
116 
  function start() {
      if (tracking || typeof window === 'undefined') return
      tracking = true
      resolve()
      window.addEventListener('scroll', schedule, { capture: true, passive: true })
      window.addEventListener('resize', schedule, { passive: true })
      if (typeof ResizeObserver !== 'undefined') {
          ro = new ResizeObserver(schedule)
          ro.observe(document.documentElement)
      }
      // Conditional controls (the ⚡ chip, the dice, a phone-tab swap) come and go
      // without a scroll or resize — watch the tree so the anchor re-resolves.
      if (typeof MutationObserver !== 'undefined') {
          mo = new MutationObserver(schedule)
          mo.observe(document.body, { childList: true, subtree: true, attributes: true })
      }
  }
134 
  function stop() {
      tracking = false
      if (frame) {
          cancelAnimationFrame(frame)
          frame = 0
      }
      if (typeof window !== 'undefined') {
          window.removeEventListener('scroll', schedule, { capture: true } as EventListenerOptions)
          window.removeEventListener('resize', schedule)
      }
      ro?.disconnect()
      ro = null
      mo?.disconnect()
      mo = null
      // Disarm here too, so the one-shot is local to this lifecycle: a beat armed
      // but never resolved-visible (its panel never came forward) can't leave a
      // stale latch that a later resolve() would honor on a torn-down beat.
      pendingScroll = false
      rect.value = null
      present.value = false
  }
⋯ 23 lines hidden (lines 156–178)156 
  onMounted(() => {
      if (selectors.value?.length) {
          pendingScroll = true
          start()
      }
  })
163 
  watch(selectors, (list) => {
      if (!list || !list.length) {
          stop()
          return
      }
      // A new beat's anchors — scroll its control into view once resolved (resolve()).
      pendingScroll = true
      if (!tracking) start()
      else resolve()
  })
174 
  onBeforeUnmount(stop)
176 
  return { rect, present }
178}

Tests pin each rule

Eight new cases pin the behavior. The discriminating one mirrors the exact mobile seam: a control starts hidden (0×0), the latch arms but does not scroll, then its class flips — the attribute mutation the body observer watches — and the scroll flushes exactly once, with no synthetic scroll/resize event involved.

The real #142 seam: a MutationObserver class-toggle flushes the deferred scroll.

tests/unit/composables/useCoachAnchor.nuxt.dom.spec.ts · 248 lines

tests/unit/composables/useCoachAnchor.nuxt.dom.spec.ts248 lines · TypeScript

⋯ 209 lines hidden (lines 1–209)1import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
2import { defineComponent, h, ref, nextTick, type VNode } from 'vue'
3import { mount, type VueWrapper } from '@vue/test-utils'
4import { useCoachAnchor } from '../../../composables/useCoachAnchor'
5 
6// DOM env (nuxt) so document / lifecycle hooks / getBoundingClientRect exist. The
7// composable resolves the FIRST visible selector to a live rect; happy-dom has no
8// layout engine, so each target's rect is stubbed (a 0×0 rect is "hidden").
9 
10const wrappers: VueWrapper[] = []
11 
12function addTarget(testid: string, rect: Partial<DOMRect> = {}) {
  const el = document.createElement('div')
  el.setAttribute('data-testid', testid)
  document.body.appendChild(el)
  const r = { top: 10, left: 20, width: 100, height: 30, right: 120, bottom: 40, x: 20, y: 10, ...rect }
  el.getBoundingClientRect = () => ({ ...r, toJSON: () => r }) as DOMRect
  return el
19}
20 
21function makeHost(initial: string[] | null) {
  const sel = ref<string[] | null>(initial)
  let anchor!: ReturnType<typeof useCoachAnchor>
  const Host = defineComponent({
      setup() {
          anchor = useCoachAnchor(sel)
          return (): VNode => h('div', { 'data-host': '' })
      }
  })
  const wrapper = mount(Host, { attachTo: document.body })
  wrappers.push(wrapper)
  return { sel, anchor }
33}
34 
35describe('useCoachAnchor', () => {
  beforeEach(() => { document.body.innerHTML = '' })
  afterEach(() => {
      wrappers.splice(0).forEach((w) => w.unmount())
      document.body.innerHTML = ''
  })
41 
  it('resolves a present target to its viewport rect', async () => {
      addTarget('alpha')
      const { anchor } = makeHost(['[data-testid="alpha"]'])
      await nextTick()
      expect(anchor.present.value).toBe(true)
      expect(anchor.rect.value).toMatchObject({ top: 10, left: 20, width: 100, height: 30 })
  })
49 
  it('reports absent when no selector matches', async () => {
      const { anchor } = makeHost(['[data-testid="nope"]'])
      await nextTick()
      expect(anchor.present.value).toBe(false)
      expect(anchor.rect.value).toBeNull()
  })
56 
  it('falls back to the next selector when the primary is absent', async () => {
      addTarget('fallback', { left: 5 })
      const { anchor } = makeHost(['[data-testid="primary-missing"]', '[data-testid="fallback"]'])
      await nextTick()
      expect(anchor.present.value).toBe(true)
      expect(anchor.rect.value?.left).toBe(5)
  })
64 
  it('prefers the primary over the fallback when both are present', async () => {
      addTarget('primary', { left: 1 })
      addTarget('fallback', { left: 2 })
      const { anchor } = makeHost(['[data-testid="primary"]', '[data-testid="fallback"]'])
      await nextTick()
      expect(anchor.rect.value?.left).toBe(1)
  })
72 
  it('treats a zero-area (hidden / inactive-tab) target as absent', async () => {
      addTarget('hidden', { width: 0, height: 0 })
      const { anchor } = makeHost(['[data-testid="hidden"]'])
      await nextTick()
      expect(anchor.present.value).toBe(false)
  })
79 
  it('re-resolves when the selector list changes', async () => {
      addTarget('a')
      addTarget('b', { left: 99 })
      const { anchor, sel } = makeHost(['[data-testid="a"]'])
      await nextTick()
      expect(anchor.rect.value?.left).toBe(20)
      sel.value = ['[data-testid="b"]']
      await nextTick()
      expect(anchor.rect.value?.left).toBe(99)
  })
90 
  it('clears when the selector list becomes null', async () => {
      addTarget('a')
      const { anchor, sel } = makeHost(['[data-testid="a"]'])
      await nextTick()
      expect(anchor.present.value).toBe(true)
      sel.value = null
      await nextTick()
      expect(anchor.present.value).toBe(false)
      expect(anchor.rect.value).toBeNull()
  })
101 
  // ── Scroll-into-view on step entry (issue #142) ───────────────────────────
  // A control rendered but scrolled out of the compose dock has a real (non-zero)
  // rect, so it resolves "present" yet sits off-screen. On a real beat change the
  // composable scrolls its freshly-resolved control into view so the mark never
  // points at a spot nobody can see. Each target's scrollIntoView is spied.
107 
  // A matchMedia stub — the composable reads only `.matches`; the full shape keeps
  // it assignable without a cast. The factory lets a test pin reduced-motion on/off
  // instead of leaning on the env default.
  const makeMatchMedia = (matches: boolean) => (query: string): MediaQueryList => ({
      matches,
      media: query,
      onchange: null,
      addListener: () => {},
      removeListener: () => {},
      addEventListener: () => {},
      removeEventListener: () => {},
      dispatchEvent: () => false
  })
121 
  // Makes a freshly-laid-out rect for a target that started hidden (0×0).
  const visibleRect = (): DOMRect => {
      const r = { top: 10, left: 20, width: 100, height: 30, right: 120, bottom: 40, x: 20, y: 10 }
      return { ...r, toJSON: () => r } as DOMRect
  }
127 
  it('scrolls the resolved anchor into view when a beat begins', async () => {
      const original = window.matchMedia
      window.matchMedia = makeMatchMedia(false) // motion on — pin it, don't lean on the env default
      try {
          const el = addTarget('alpha')
          el.scrollIntoView = vi.fn()
          makeHost(['[data-testid="alpha"]'])
          await nextTick()
          expect(el.scrollIntoView).toHaveBeenCalledTimes(1)
          expect(el.scrollIntoView).toHaveBeenCalledWith(
              expect.objectContaining({ block: 'center', inline: 'nearest', behavior: 'smooth' })
          )
      } finally {
          window.matchMedia = original
      }
  })
144 
  it('scrolls the new anchor when the beat changes', async () => {
      const a = addTarget('a')
      const b = addTarget('b', { left: 99 })
      a.scrollIntoView = vi.fn()
      b.scrollIntoView = vi.fn()
      const { sel } = makeHost(['[data-testid="a"]'])
      await nextTick()
      expect(a.scrollIntoView).toHaveBeenCalledTimes(1)
      sel.value = ['[data-testid="b"]']
      await nextTick()
      expect(b.scrollIntoView).toHaveBeenCalledTimes(1)
  })
157 
  it('scrolls the fallback element when the primary anchor is absent', async () => {
      // The wager beat is the one with a fallback (⚡ chip → ⚡ line); scrolling must
      // follow the same fallthrough resolution the rect does.
      const fallback = addTarget('fallback', { left: 5 })
      fallback.scrollIntoView = vi.fn()
      makeHost(['[data-testid="primary-missing"]', '[data-testid="fallback"]'])
      await nextTick()
      expect(fallback.scrollIntoView).toHaveBeenCalledTimes(1)
  })
167 
  it('snaps instantly (no smooth animation) under prefers-reduced-motion', async () => {
      const original = window.matchMedia
      window.matchMedia = makeMatchMedia(true)
      try {
          const el = addTarget('alpha')
          el.scrollIntoView = vi.fn()
          makeHost(['[data-testid="alpha"]'])
          await nextTick()
          expect(el.scrollIntoView).toHaveBeenCalledWith(expect.objectContaining({ behavior: 'instant' }))
      } finally {
          window.matchMedia = original
      }
  })
181 
  it('does not scroll when nothing resolves visible', async () => {
      const hidden = addTarget('hidden', { width: 0, height: 0 })
      hidden.scrollIntoView = vi.fn()
      makeHost(['[data-testid="hidden"]'])
      await nextTick()
      expect(hidden.scrollIntoView).not.toHaveBeenCalled()
  })
189 
  it('defers a hidden control, then flushes its scroll on a later reposition', async () => {
      // rAF runs in-band so the reposition resolves synchronously.
      vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => { cb(0); return 0 })
      try {
          const el = addTarget('late', { width: 0, height: 0 }) // hidden: its phone-tab panel isn't forward yet
          el.scrollIntoView = vi.fn()
          makeHost(['[data-testid="late"]'])
          await nextTick()
          expect(el.scrollIntoView).not.toHaveBeenCalled()
          // The panel comes forward — the control gains a real rect…
          el.getBoundingClientRect = visibleRect
          // …and the next reposition flushes the still-armed scroll, exactly once.
          window.dispatchEvent(new Event('resize'))
          await nextTick()
          expect(el.scrollIntoView).toHaveBeenCalledTimes(1)
      } finally {
          vi.unstubAllGlobals()
      }
  })
209 
  it('flushes the deferred scroll via the MutationObserver when the panel comes forward', async () => {
      // The real #142 mobile seam: the tab section's `hidden` class toggles, the
      // body-subtree observer catches it, and resolve() re-runs — no scroll/resize.
      vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => { cb(0); return 0 })
      try {
          const el = addTarget('panelled', { width: 0, height: 0 }) // hidden in an inactive tab panel
          el.scrollIntoView = vi.fn()
          makeHost(['[data-testid="panelled"]'])
          await nextTick()
          expect(el.scrollIntoView).not.toHaveBeenCalled()
          // The control gains a real rect, and its class flips — the exact attribute
          // mutation the observer watches.
          el.getBoundingClientRect = visibleRect
          el.setAttribute('class', 'now-visible')
          await nextTick()
          await nextTick()
          expect(el.scrollIntoView).toHaveBeenCalledTimes(1)
      } finally {
          vi.unstubAllGlobals()
      }
  })
⋯ 18 lines hidden (lines 231–248)231 
  it("scrolls a beat's anchor once, not on every reposition", async () => {
      vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => { cb(0); return 0 })
      try {
          const el = addTarget('alpha')
          el.scrollIntoView = vi.fn()
          makeHost(['[data-testid="alpha"]'])
          await nextTick()
          expect(el.scrollIntoView).toHaveBeenCalledTimes(1) // on entry
          window.dispatchEvent(new Event('scroll'))
          window.dispatchEvent(new Event('resize'))
          await nextTick()
          expect(el.scrollIntoView).toHaveBeenCalledTimes(1) // still once
      } finally {
          vi.unstubAllGlobals()
      }
  })
248})

The rest pin the edges: scroll on a beat's first entry (block:'center', smooth) and on a beat change; follow the fallback anchor (the wager chip → the ⚡ line); snap instant under reduced motion; do nothing when no control resolves visible; defer then flush on a later reposition; and scroll once, not on every reposition.