@pathmx/player 0.5.0

package/client.ts

@@ -0,0 +1,1047 @@
+import "./play.css"
+import "./notes.css"
+import type { SourceDescription } from "@pathmx/core"
+import { actionsForBeat, type PlayAction } from "./actions.ts"
+import {
+  createPlayControls,
+  MOBILE_CONTROLS_QUERY,
+  type PlayIntensity,
+  type PlayMode,
+  type PlayThemeChoice,
+} from "./controls.tsx"
+import { installPlayerGestures } from "./gestures.ts"
+import { createPlayGrid } from "./grid.ts"
+import { measurePlayGuide } from "./guide.ts"
+import { installPlayerKeyboard, returnKeyboardToDocument } from "./keyboard.ts"
+import { applyBlockVariants } from "./variants.ts"
+import { applyPlayMediaFrames } from "./media.ts"
+import { installPlayLinkContinuation } from "./navigation.ts"
+import {
+  createPlayPreferenceStore,
+  type PlayPreferences,
+} from "./preferences.ts"
+import type { PlayProgressBlock } from "./progress.tsx"
+import {
+  extractPlayRoute,
+  playNoteForBlock,
+  type Beat,
+  type PlayRoute,
+} from "./route.ts"
+import {
+  createPlayScrollSync,
+  syncPresentationSnapTargets,
+  type PlayScrollBehavior,
+} from "./scroll.ts"
+import { isPlayTheme, sourcePlayTheme } from "./themes.ts"
+
+const QUIET_DELAY = 1800
+const preferenceStore = createPlayPreferenceStore()
+let preferences = preferenceStore.snapshot()
+
+function rememberPreferences(next: Partial<PlayPreferences>) {
+  preferences = preferenceStore.update(next)
+}
+
+function requestedState() {
+  const url = new URL(location.href)
+  const value = url.searchParams.get("play")
+  if (value === null) return
+  const mode: PlayMode = value === "presentation" ? "presentation" : "focus"
+  const requestedIntensity = url.searchParams.get("intensity")
+  const intensity: PlayIntensity =
+    requestedIntensity === "low" ||
+    requestedIntensity === "medium" ||
+    requestedIntensity === "high"
+      ? requestedIntensity
+      : preferences.intensity
+  const requestedTheme = url.searchParams.get("play-theme")
+  const theme: PlayThemeChoice =
+    requestedTheme === null
+      ? preferences.theme
+      : isPlayTheme(requestedTheme)
+        ? requestedTheme
+        : "source"
+  if (requestedTheme && !isPlayTheme(requestedTheme)) {
+    console.warn(
+      `[pathmx-play] unavailable theme "${requestedTheme}"; using Source default`,
+    )
+  }
+  return {
+    mode,
+    intensity,
+    theme,
+    guide: url.searchParams.has("play-guide")
+      ? url.searchParams.get("play-guide") !== "off"
+      : preferences.guide,
+    notes: url.searchParams.has("play-notes")
+      ? url.searchParams.get("play-notes") !== "off"
+      : preferences.notes,
+  }
+}
+
+function nearestElementIndex(elements: readonly HTMLElement[], ratio: number) {
+  const playhead = innerHeight * ratio
+  let nearest = 0
+  let distance = Number.POSITIVE_INFINITY
+  elements.forEach((element, index) => {
+    const rect = element.getBoundingClientRect()
+    const bottom = rect.top + rect.height
+    const nextDistance =
+      rect.top <= playhead && playhead <= bottom
+        ? 0
+        : Math.min(Math.abs(rect.top - playhead), Math.abs(bottom - playhead))
+    if (nextDistance < distance) {
+      nearest = index
+      distance = nextDistance
+    }
+  })
+  return nearest
+}
+
+function nearestBeatIndex(route: PlayRoute, currentIndex?: number) {
+  if (scrollY <= 32) return 0
+  const targets = [...new Set(route.beats.map((beat) => beat.target))]
+  const target = targets[nearestElementIndex(targets, 0.42)]
+  if (!target) return 0
+  const current =
+    currentIndex === undefined ? undefined : route.beats[currentIndex]
+  if (current && currentIndex !== undefined && current.target === target) {
+    return currentIndex
+  }
+  const index = route.beats.findIndex((beat) => beat.target === target)
+  return index >= 0 ? index : 0
+}
+
+function nearestBlockBeatIndex(route: PlayRoute, currentIndex: number) {
+  const blocks = [...new Set(route.beats.map((beat) => beat.block))]
+  const block = blocks[nearestElementIndex(blocks, 0.5)]
+  const current = route.beats[currentIndex]
+  if (current?.block === block) return currentIndex
+  const index = route.beats.findIndex((beat) => beat.block === block)
+  return index >= 0 ? index : currentIndex
+}
+
+function requestedFragment() {
+  if (!location.hash) return
+  try {
+    return decodeURIComponent(location.hash.slice(1)) || undefined
+  } catch {
+    return
+  }
+}
+
+function beatIndexForFragment(route: PlayRoute, fragment?: string) {
+  if (!fragment) return
+  const index = route.beats.findIndex(
+    (beat) =>
+      beat.id === fragment ||
+      beat.fragment === fragment ||
+      beat.element.id === fragment ||
+      beat.target.id === fragment,
+  )
+  return index >= 0 ? index : undefined
+}
+
+function currentPlayerAppRoot() {
+  return document.querySelector<HTMLElement>(
+    '[data-component="player:app"]',
+  )
+}
+
+function descriptionFrom(element: HTMLElement) {
+  return JSON.parse(
+    element.dataset.description ?? "null",
+  ) as SourceDescription | null
+}
+
+function extractCurrentPlayRoute() {
+  const document = window.document.querySelector<HTMLElement>(".pmx-document")
+  if (document) applyPlayMediaFrames(document)
+  return extractPlayRoute()
+}
+
+let route: PlayRoute | undefined
+let mode: PlayMode | undefined
+let intensity = preferences.intensity
+let theme = preferences.theme
+let guide = preferences.guide
+let notes = preferences.notes
+let autoHide = preferences.autoHide
+let expanded = false
+let activeIndex = -1
+let seenThrough = -1
+let pendingFragment: string | undefined
+let ownedFragment: string | undefined
+let activeActions: PlayAction[] = []
+let previousAriaCurrent: string | null | undefined
+let activeAriaElement: HTMLElement | undefined
+let quietTimer: number | undefined
+let guideFrameRequest = 0
+let progressBlocks: readonly PlayProgressBlock[] = []
+let previousScrollRestoration: ScrollRestoration | undefined
+
+const initialAppRoot = currentPlayerAppRoot()
+if (!initialAppRoot) throw new Error("Missing authored Player App Component.")
+let appRoot = initialAppRoot
+const description = descriptionFrom(appRoot)
+if (!description) throw new Error("Missing Player Source description.")
+let sourceDescription: SourceDescription = description
+
+type PlayHistoryBehavior = "replace" | "push" | "none"
+type PlayHistoryEntry = Readonly<{ sourceId: string; beatId: string }>
+const PLAY_HISTORY_KEY = "pmxPlay"
+
+function claimPresentationScroll() {
+  if (previousScrollRestoration === undefined) {
+    previousScrollRestoration = history.scrollRestoration
+  }
+  history.scrollRestoration = "manual"
+}
+
+function releasePresentationScroll() {
+  if (previousScrollRestoration === undefined) return
+  history.scrollRestoration = previousScrollRestoration
+  previousScrollRestoration = undefined
+}
+
+function playHistoryEntry(state: unknown): PlayHistoryEntry | undefined {
+  if (!state || typeof state !== "object" || Array.isArray(state)) return
+  const entry = (state as Record<string, unknown>)[PLAY_HISTORY_KEY]
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) return
+  const sourceId = (entry as Record<string, unknown>).sourceId
+  const beatId = (entry as Record<string, unknown>).beatId
+  if (typeof sourceId !== "string" || typeof beatId !== "string") return
+  return { sourceId, beatId }
+}
+
+function playHistoryState(active: Beat) {
+  const current = history.state
+  const state =
+    current && typeof current === "object" && !Array.isArray(current)
+      ? { ...current }
+      : {}
+  return {
+    ...state,
+    [PLAY_HISTORY_KEY]: {
+      sourceId: sourceDescription.source.id,
+      beatId: active.id,
+    },
+  }
+}
+
+function syncBeatHistory(active: Beat, behavior: PlayHistoryBehavior) {
+  if (behavior === "none") return
+  const url = new URL(location.href)
+  if (active.fragment) {
+    url.hash = encodeURIComponent(active.fragment)
+    ownedFragment = active.fragment
+  } else if (requestedFragment() === ownedFragment) {
+    url.hash = ""
+    ownedFragment = undefined
+  }
+  const state = playHistoryState(active)
+  if (behavior === "push") history.pushState(state, "", url)
+  else history.replaceState(state, "", url)
+}
+
+installPlayLinkContinuation(
+  () => (mode ? { mode, intensity, theme, guide, notes } : undefined),
+  (fragment) => navigateToBeatFragment(fragment, "push"),
+)
+
+function activateAction(index: number) {
+  activeActions[index]?.activate()
+}
+
+function usesMobileControls() {
+  return matchMedia(MOBILE_CONTROLS_QUERY).matches
+}
+
+function clearQuietTimer() {
+  if (quietTimer !== undefined) window.clearTimeout(quietTimer)
+  quietTimer = undefined
+}
+
+function scheduleQuiet() {
+  clearQuietTimer()
+  if (!mode || !autoHide || expanded || usesMobileControls()) return
+  quietTimer = window.setTimeout(() => controls.setVisible(false), QUIET_DELAY)
+}
+
+function revealControls() {
+  if (!mode) return
+  controls.setVisible(true)
+  scheduleQuiet()
+}
+
+const controls = createPlayControls(appRoot, sourceDescription, {
+  start: () => startPreferredPlay(),
+  previous: () => move(-1),
+  next: () => move(1),
+  setMode,
+  setIntensity,
+  setTheme,
+  setGuide,
+  setNotes,
+  setGrid,
+  setAutoHide,
+  setExpanded(nextExpanded) {
+    expanded = nextExpanded
+    revealControls()
+  },
+  exit: () => deactivate(),
+  activateAction,
+})
+
+controls.setAutoHide(autoHide)
+controls.setNotes(notes)
+
+const scrollSync = createPlayScrollSync({
+  start() {
+    document.documentElement.setAttribute("data-pmx-play-scrolling", "")
+    controls.setGuideFrame(undefined)
+  },
+  settle() {
+    document.documentElement.removeAttribute("data-pmx-play-scrolling")
+    adoptScrollPosition()
+    updateGuideFrame()
+  },
+  track(tracking) {
+    document.documentElement.toggleAttribute(
+      "data-pmx-play-guide-tracking",
+      tracking,
+    )
+    if (!tracking) updateGuideFrame()
+  },
+})
+
+const grid = createPlayGrid({
+  route: () => route,
+  activeIndex: () => activeIndex,
+  seenThrough: () => seenThrough,
+  select: selectGridBlock,
+})
+
+function deriveProgressBlocks(playRoute: PlayRoute) {
+  const blocks: PlayProgressBlock[] = []
+  let currentBlock: HTMLElement | undefined
+  playRoute.beats.forEach((beat, index) => {
+    const current = blocks.at(-1)
+    if (current && currentBlock === beat.block) {
+      blocks[blocks.length - 1] = { ...current, total: current.total + 1 }
+      return
+    }
+    currentBlock = beat.block
+    blocks.push({ start: index, total: 1 })
+  })
+  return blocks
+}
+
+function updateUrl(nextMode: PlayMode | undefined) {
+  const url = new URL(location.href)
+  if (nextMode) {
+    url.searchParams.set("play", nextMode)
+    url.searchParams.set("intensity", intensity)
+    if (theme === "source") url.searchParams.delete("play-theme")
+    else url.searchParams.set("play-theme", theme)
+    if (guide) url.searchParams.delete("play-guide")
+    else url.searchParams.set("play-guide", "off")
+    if (notes) url.searchParams.delete("play-notes")
+    else url.searchParams.set("play-notes", "off")
+  } else {
+    url.searchParams.delete("play")
+    url.searchParams.delete("intensity")
+    url.searchParams.delete("play-theme")
+    url.searchParams.delete("play-guide")
+    url.searchParams.delete("play-notes")
+  }
+  history.replaceState(history.state, "", url)
+}
+
+function effectiveTheme() {
+  return theme === "source" ? sourcePlayTheme(sourceDescription) : theme
+}
+
+function applyTheme() {
+  if (!route) return
+  route.document.dataset.pmxPlayTheme = effectiveTheme()
+  controls.setTheme(theme)
+}
+
+function clearRoutePresentation() {
+  if (!route) return
+  syncPresentationSnapTargets(route.document, false)
+  route.document.removeAttribute("data-pmx-play")
+  route.document.removeAttribute("data-pmx-play-intensity")
+  route.document.removeAttribute("data-pmx-play-theme")
+  for (const beat of route.beats) {
+    beat.element.removeAttribute("data-pmx-play-state")
+    beat.element.removeAttribute("data-pmx-play-row-active")
+    beat.block.removeAttribute("data-pmx-play-block")
+    beat.target.removeAttribute("data-pmx-play-target-active")
+  }
+  for (const block of route.document.querySelectorAll<HTMLElement>(
+    ":scope > section[data-pmx-block]",
+  )) {
+    block.removeAttribute("data-pmx-play-variant")
+  }
+  controls.setGuideFrame(undefined)
+  if (activeAriaElement) {
+    if (previousAriaCurrent === null) {
+      activeAriaElement.removeAttribute("aria-current")
+    } else if (previousAriaCurrent !== undefined) {
+      activeAriaElement.setAttribute("aria-current", previousAriaCurrent)
+    }
+  }
+  activeAriaElement = undefined
+  previousAriaCurrent = undefined
+}
+
+function applyMode(nextMode: PlayMode, reposition = true) {
+  if (!route) return
+  if (nextMode === "presentation") claimPresentationScroll()
+  else releasePresentationScroll()
+  mode = nextMode
+  route.document.dataset.pmxPlay = nextMode
+  syncPresentationSnapTargets(route.document, nextMode === "presentation")
+  document.documentElement.dataset.pmxPlayMode = nextMode
+  controls.setMode(nextMode)
+  applyTheme()
+  updateUrl(nextMode)
+  if (reposition) present(!grid.isOpen(), 0, false)
+}
+
+function setMode(nextMode: PlayMode) {
+  rememberPreferences({ mode: nextMode })
+  applyMode(nextMode)
+}
+
+function setIntensity(nextIntensity: PlayIntensity) {
+  if (!route || !mode) return
+  intensity = nextIntensity
+  route.document.dataset.pmxPlayIntensity = nextIntensity
+  controls.setIntensity(nextIntensity)
+  rememberPreferences({ intensity: nextIntensity })
+  updateUrl(mode)
+}
+
+function adjustIntensity(offset: -1 | 1) {
+  const choices: PlayIntensity[] = ["low", "medium", "high"]
+  const index = choices.indexOf(intensity)
+  setIntensity(
+    choices[Math.max(0, Math.min(choices.length - 1, index + offset))]!,
+  )
+}
+
+function toggleMode() {
+  if (mode) setMode(mode === "focus" ? "presentation" : "focus")
+}
+
+function setTheme(nextTheme: PlayThemeChoice) {
+  if (!route || !mode) return
+  theme = nextTheme
+  rememberPreferences({ theme: nextTheme })
+  applyTheme()
+  updateUrl(mode)
+}
+
+function setGuide(enabled: boolean) {
+  guide = enabled
+  rememberPreferences({ guide: enabled })
+  controls.setGuide(enabled)
+  if (route && mode) {
+    updateUrl(mode)
+    updateGuideFrame()
+  }
+}
+
+function setNotes(enabled: boolean) {
+  notes = enabled
+  rememberPreferences({ notes: enabled })
+  controls.setNotes(enabled)
+  if (route && mode) updateUrl(mode)
+}
+
+function setGrid(open: boolean, restoreActive = true) {
+  if ((open && (!route || !mode)) || open === grid.isOpen()) return
+  grid.setOpen(open)
+  controls.setGrid(open)
+  controls.setGuideFrame(undefined)
+  if (open) {
+    scrollSync.setEnabled(false)
+    return
+  }
+  returnKeyboardToDocument()
+  scrollSync.setEnabled(true)
+  if (restoreActive) {
+    requestAnimationFrame(() => {
+      if (route && mode && !grid.isOpen()) present(true, 0, false, "instant")
+    })
+  }
+}
+
+function selectGridBlock(beatIndex: number) {
+  setGrid(false, false)
+  requestAnimationFrame(() => {
+    if (!route || !mode || grid.isOpen()) return
+    if (beatIndex === activeIndex) present(true, 0, false, "instant")
+    else selectBeat(beatIndex, true, "instant")
+  })
+}
+
+function setAutoHide(enabled: boolean) {
+  autoHide = enabled
+  rememberPreferences({ autoHide: enabled })
+  controls.setAutoHide(enabled)
+  controls.setVisible(true)
+  scheduleQuiet()
+}
+
+function updateGuideFrame() {
+  cancelAnimationFrame(guideFrameRequest)
+  guideFrameRequest = requestAnimationFrame(() => {
+    const active = route?.beats[activeIndex]
+    controls.setGuideFrame(
+      active && mode && guide && !grid.isOpen()
+        ? measurePlayGuide(active)
+        : undefined,
+    )
+  })
+}
+
+function updatePlayerLayout() {
+  if (route) {
+    syncPresentationSnapTargets(route.document, mode === "presentation")
+  }
+  updateGuideFrame()
+}
+
+const guideResizeObserver =
+  typeof ResizeObserver === "undefined"
+    ? undefined
+    : new ResizeObserver(() => updateGuideFrame())
+
+function observeGuideLayout(active?: Beat) {
+  guideResizeObserver?.disconnect()
+  if (!active) return
+  guideResizeObserver?.observe(active.target)
+  for (const child of active.block.children) {
+    if (child instanceof HTMLElement && child !== active.target) {
+      guideResizeObserver?.observe(child)
+    }
+  }
+}
+
+function applyElementStates(active: Beat) {
+  if (!route) return
+  const byElement = new Map<HTMLElement, number[]>()
+  const byBlock = new Map<HTMLElement, number[]>()
+  route.beats.forEach((beat, index) => {
+    const indexes = byElement.get(beat.element) ?? []
+    indexes.push(index)
+    byElement.set(beat.element, indexes)
+    const blockIndexes = byBlock.get(beat.block) ?? []
+    blockIndexes.push(index)
+    byBlock.set(beat.block, blockIndexes)
+    beat.target.removeAttribute("data-pmx-play-target-active")
+    beat.element.removeAttribute("data-pmx-play-row-active")
+  })
+  for (const [block, indexes] of byBlock) {
+    block.dataset.pmxPlayBlock =
+      block === active.block
+        ? "active"
+        : Math.min(...indexes) <= seenThrough
+          ? "seen"
+          : "upcoming"
+  }
+  for (const [element, indexes] of byElement) {
+    element.dataset.pmxPlayState = indexes.includes(activeIndex)
+      ? "active"
+      : Math.max(...indexes) <= seenThrough
+        ? "seen"
+        : "upcoming"
+  }
+  active.target.setAttribute("data-pmx-play-target-active", "")
+  if (active.member?.type === "table-row") {
+    active.element.setAttribute("data-pmx-play-row-active", "")
+  }
+}
+
+function present(
+  scroll = true,
+  direction = 0,
+  announce = true,
+  scrollBehavior: PlayScrollBehavior = "smooth",
+  historyBehavior: PlayHistoryBehavior = "replace",
+) {
+  if (!route || !mode || activeIndex < 0) return
+  const active = route.beats[activeIndex]
+  if (!active) return
+  seenThrough = Math.max(seenThrough, activeIndex)
+  syncBeatHistory(active, historyBehavior)
+  applyElementStates(active)
+
+  if (activeAriaElement !== active.element) {
+    if (activeAriaElement) {
+      if (previousAriaCurrent === null) {
+        activeAriaElement.removeAttribute("aria-current")
+      } else if (previousAriaCurrent !== undefined) {
+        activeAriaElement.setAttribute("aria-current", previousAriaCurrent)
+      }
+    }
+    activeAriaElement = active.element
+    previousAriaCurrent = active.element.getAttribute("aria-current")
+    active.element.setAttribute("aria-current", "step")
+  }
+
+  activeActions = actionsForBeat(
+    active,
+    activeIndex === route.beats.length - 1 ? sourceDescription.actions : [],
+  )
+  controls.setActions(activeActions)
+  controls.setProgress(
+    activeIndex,
+    route.beats.length,
+    active.label,
+    progressBlocks,
+  )
+  controls.setNote(playNoteForBlock(active.block))
+  observeGuideLayout(active)
+  updateGuideFrame()
+  revealControls()
+
+  if (announce) {
+    active.element.dispatchEvent(
+      new CustomEvent("pmx:beatenter", {
+        bubbles: true,
+        detail: {
+          id: active.id,
+          index: activeIndex,
+          direction,
+          mode,
+          intensity,
+          member: active.member,
+        },
+      }),
+    )
+  }
+
+  if (scroll) {
+    scrollSync.navigate(active.target, active.block, mode, scrollBehavior)
+  }
+}
+
+function reanchorPresentation(beatId: string | undefined) {
+  scrollSync.setEnabled(false)
+  requestAnimationFrame(() => {
+    requestAnimationFrame(() => {
+      if (
+        mode === "presentation" &&
+        route?.beats[activeIndex]?.id === beatId
+      ) {
+        present(true, 0, false, "instant", "none")
+      }
+      requestAnimationFrame(() => {
+        if (mode) scrollSync.setEnabled(true)
+      })
+    })
+  })
+}
+
+function activate(
+  nextMode: PlayMode,
+  nextIntensity: PlayIntensity,
+  nextTheme: PlayThemeChoice = "source",
+  nextGuide = true,
+  nextNotes = true,
+  scrollBehavior: PlayScrollBehavior = "smooth",
+  position: "nearest" | "start" = "nearest",
+) {
+  const nextRoute = extractCurrentPlayRoute()
+  if (!nextRoute) return
+  clearRoutePresentation()
+  route = nextRoute
+  progressBlocks = deriveProgressBlocks(nextRoute)
+  mode = nextMode
+  intensity = nextIntensity
+  theme = nextTheme
+  guide = nextGuide
+  notes = nextNotes
+  rememberPreferences({
+    mode: nextMode,
+    intensity: nextIntensity,
+    theme: nextTheme,
+    guide: nextGuide,
+    notes: nextNotes,
+  })
+  applyBlockVariants(route, sourceDescription)
+  const fragment = requestedFragment()
+  const fragmentIndex = beatIndexForFragment(route, fragment)
+  pendingFragment =
+    fragment && fragmentIndex === undefined ? fragment : undefined
+  activeIndex =
+    fragmentIndex ?? (position === "start" ? 0 : nearestBeatIndex(route))
+  seenThrough = activeIndex
+  const active = route.beats[activeIndex]
+  const activationTop = active?.target.getBoundingClientRect().top
+  document.documentElement.setAttribute("data-pmx-play-active", "")
+  controls.setPlaying(true)
+  controls.setVisible(true)
+  controls.setGuide(guide)
+  controls.setNotes(notes)
+  route.document.dataset.pmxPlayIntensity = intensity
+  controls.setIntensity(intensity)
+  applyMode(nextMode, false)
+  present(nextMode === "presentation", 0, true, scrollBehavior)
+  returnKeyboardToDocument()
+  scheduleQuiet()
+  if (nextMode === "focus" && active && activationTop !== undefined) {
+    requestAnimationFrame(() => {
+      if (mode !== "focus" || !active.target.isConnected) return
+      scrollSync.preserve(active.target, activationTop)
+      updateGuideFrame()
+      requestAnimationFrame(() => {
+        if (mode === "focus") scrollSync.setEnabled(true)
+      })
+    })
+    return
+  }
+  if (
+    nextMode === "presentation" &&
+    (fragmentIndex !== undefined || position === "start") &&
+    document.readyState !== "complete"
+  ) {
+    window.addEventListener(
+      "load",
+      () => reanchorPresentation(active?.id),
+      { once: true },
+    )
+    scrollSync.setEnabled(false)
+    return
+  }
+  scrollSync.setEnabled(true)
+}
+
+function startPreferredPlay() {
+  activate(
+    preferences.mode,
+    preferences.intensity,
+    preferences.theme,
+    preferences.guide,
+    preferences.notes,
+  )
+}
+
+function restoreDocumentAnchor(target: HTMLElement, viewportTop: number) {
+  requestAnimationFrame(() => {
+    if (!target.isConnected || mode) return
+    const shift = target.getBoundingClientRect().top - viewportTop
+    if (Math.abs(shift) > 0.5) {
+      window.scrollBy({ top: shift, behavior: "instant" })
+    }
+  })
+}
+
+function deactivate(updateLocation = true) {
+  if (grid.isOpen()) setGrid(false, false)
+  const anchor = route?.beats[activeIndex]?.target
+  const anchorTop = anchor
+    ? Math.max(
+        innerHeight * 0.12,
+        Math.min(innerHeight * 0.78, anchor.getBoundingClientRect().top),
+      )
+    : undefined
+  clearRoutePresentation()
+  clearQuietTimer()
+  document.documentElement.removeAttribute("data-pmx-play-active")
+  document.documentElement.removeAttribute("data-pmx-play-mode")
+  document.documentElement.removeAttribute("data-pmx-play-scrolling")
+  document.documentElement.removeAttribute("data-pmx-play-guide-tracking")
+  scrollSync.setEnabled(false)
+  observeGuideLayout()
+  route = undefined
+  progressBlocks = []
+  mode = undefined
+  activeIndex = -1
+  seenThrough = -1
+  pendingFragment = undefined
+  ownedFragment = undefined
+  activeActions = []
+  expanded = false
+  controls.setActions([])
+  controls.setNote(undefined)
+  controls.setPlaying(false)
+  controls.setVisible(true)
+  releasePresentationScroll()
+  if (updateLocation) updateUrl(undefined)
+  if (anchor && anchorTop !== undefined)
+    restoreDocumentAnchor(anchor, anchorTop)
+}
+
+function selectBeat(
+  nextIndex: number,
+  scroll = true,
+  scrollBehavior: PlayScrollBehavior = "smooth",
+  historyBehavior: PlayHistoryBehavior = "replace",
+) {
+  if (!route || !mode) return
+  pendingFragment = undefined
+  nextIndex = Math.max(0, Math.min(route.beats.length - 1, nextIndex))
+  if (nextIndex === activeIndex) return
+  const current = route.beats[activeIndex]
+  const next = route.beats[nextIndex]
+  if (!next) return
+  const direction = Math.sign(nextIndex - activeIndex)
+  const shouldScroll =
+    scroll &&
+    (!current || current.block !== next.block || current.target !== next.target)
+  activeIndex = nextIndex
+  present(shouldScroll, direction, true, scrollBehavior, historyBehavior)
+}
+
+function navigateToBeatFragment(
+  fragment: string,
+  historyBehavior: PlayHistoryBehavior,
+) {
+  if (!route || !mode) return false
+  const nextIndex = beatIndexForFragment(route, fragment)
+  if (nextIndex === undefined) return false
+  pendingFragment = undefined
+  if (historyBehavior === "none") {
+    const nextFragment = route.beats[nextIndex]?.fragment
+    ownedFragment =
+      nextFragment === requestedFragment() ? nextFragment : undefined
+  }
+  if (nextIndex === activeIndex) {
+    present(true, 0, false, "instant", historyBehavior)
+  } else {
+    selectBeat(nextIndex, true, "instant", historyBehavior)
+  }
+  returnKeyboardToDocument()
+  return true
+}
+
+function restoreBeatHistory(event: PopStateEvent) {
+  if (!route || !mode) return
+  const entry = playHistoryEntry(event.state)
+  if (entry?.sourceId === sourceDescription.source.id) {
+    const nextIndex = route.beats.findIndex((beat) => beat.id === entry.beatId)
+    if (nextIndex >= 0) {
+      const next = route.beats[nextIndex]
+      const nextFragment = next?.fragment
+      pendingFragment = undefined
+      ownedFragment =
+        nextFragment === requestedFragment() ? nextFragment : undefined
+      if (nextIndex === activeIndex) {
+        present(true, 0, false, "instant", "none")
+      } else {
+        selectBeat(nextIndex, true, "instant", "none")
+      }
+      return
+    }
+  }
+  const fragment = requestedFragment()
+  if (fragment) navigateToBeatFragment(fragment, "none")
+}
+
+function move(change: number, scrollBehavior: PlayScrollBehavior = "smooth") {
+  selectBeat(activeIndex + change, true, scrollBehavior)
+}
+
+function moveBlock(
+  change: number,
+  scrollBehavior: PlayScrollBehavior = "smooth",
+) {
+  if (!route || !mode) return
+  const current = route.beats[activeIndex]
+  if (!current) return
+  const blocks = [...new Set(route.beats.map((beat) => beat.block))]
+  const blockIndex = blocks.indexOf(current.block)
+  const nextBlock = blocks[blockIndex + change]
+  if (!nextBlock) return
+  const nextIndex = route.beats.findIndex((beat) => beat.block === nextBlock)
+  if (nextIndex >= 0) selectBeat(nextIndex, true, scrollBehavior)
+}
+
+function adoptScrollPosition(announce = true) {
+  if (!route || !mode) return
+  const nextIndex =
+    mode === "presentation"
+      ? nearestBlockBeatIndex(route, activeIndex)
+      : nearestBeatIndex(route, activeIndex)
+  if (nextIndex === activeIndex) return
+  pendingFragment = undefined
+  const direction = Math.sign(nextIndex - activeIndex)
+  activeIndex = nextIndex
+  present(false, direction, announce)
+}
+
+function refreshRoute(type: "update" | "navigation" = "update") {
+  if (!route || !mode) return
+  const navigated = type === "navigation"
+  if (navigated) ownedFragment = undefined
+  const active = route.beats[activeIndex]
+  const previousId = navigated ? undefined : active?.id
+  const restoreGrid = grid.isOpen()
+  if (restoreGrid) setGrid(false, false)
+  clearRoutePresentation()
+  route = extractCurrentPlayRoute()
+  if (!route) {
+    deactivate()
+    return
+  }
+  progressBlocks = deriveProgressBlocks(route)
+  applyBlockVariants(route, sourceDescription)
+  const fragment = navigated ? requestedFragment() : pendingFragment
+  const fragmentIndex = beatIndexForFragment(route, fragment)
+  const resolvedFragment = fragmentIndex !== undefined
+  if (resolvedFragment) pendingFragment = undefined
+  else if (navigated) pendingFragment = fragment
+  const surviving = previousId
+    ? route.beats.findIndex((beat) => beat.id === previousId)
+    : -1
+  activeIndex = resolvedFragment
+    ? fragmentIndex
+    : surviving >= 0
+      ? surviving
+      : navigated
+        ? 0
+        : nearestBeatIndex(route)
+  seenThrough = navigated
+    ? activeIndex
+    : Math.max(activeIndex, Math.min(seenThrough, route.beats.length - 1))
+  route.document.dataset.pmxPlay = mode
+  route.document.dataset.pmxPlayIntensity = intensity
+  applyTheme()
+  present(
+    navigated || resolvedFragment,
+    0,
+    resolvedFragment,
+    navigated || resolvedFragment ? "instant" : "smooth",
+  )
+  if (restoreGrid) setGrid(true)
+}
+
+function reconcileLocation(event?: Event) {
+  const nextAppRoot = currentPlayerAppRoot()
+  if (!nextAppRoot) {
+    if (mode) deactivate(false)
+    controls.unmount()
+    return
+  }
+  appRoot = nextAppRoot
+  const nextDescription = descriptionFrom(appRoot)
+  if (nextDescription) {
+    sourceDescription = nextDescription
+    controls.setDescription(nextDescription)
+  }
+  controls.mount()
+  const requested = requestedState()
+  if (!requested) {
+    if (mode) deactivate(false)
+    return
+  }
+  if (!mode) {
+    activate(
+      requested.mode,
+      requested.intensity,
+      requested.theme,
+      requested.guide,
+      requested.notes,
+      "instant",
+      "start",
+    )
+    return
+  }
+  const renderType =
+    event instanceof CustomEvent
+      ? (event.detail as { type?: string } | undefined)?.type
+      : undefined
+  const navigated = renderType === "navigation" || renderType === "traverse"
+  refreshRoute(navigated ? "navigation" : "update")
+  if (mode !== requested.mode) setMode(requested.mode)
+  if (intensity !== requested.intensity) setIntensity(requested.intensity)
+  if (theme !== requested.theme) setTheme(requested.theme)
+  if (guide !== requested.guide) setGuide(requested.guide)
+  if (notes !== requested.notes) setNotes(requested.notes)
+}
+
+installPlayerKeyboard({
+  active: () => mode !== undefined,
+  start: startPreferredPlay,
+  controlsExpanded: () => expanded,
+  gridOpen: grid.isOpen,
+  actionCount: () => activeActions.length,
+  activateAction,
+  adjustIntensity,
+  move,
+  moveBlock,
+  moveGrid: grid.move,
+  selectGrid: grid.selectFocused,
+  toggleGrid: () => setGrid(!grid.isOpen()),
+  toggleMode,
+  exit: () => deactivate(),
+})
+
+installPlayerGestures({
+  enabled: () => mode === "presentation" && !expanded && !grid.isOpen(),
+  surface: () => route?.document,
+  moveBeat: (offset) => {
+    adoptScrollPosition(false)
+    move(offset, "instant")
+  },
+  moveBlock: (offset) => {
+    adoptScrollPosition(false)
+    moveBlock(offset, "instant")
+  },
+})
+
+document.addEventListener("click", (event) => {
+  if (
+    event.defaultPrevented ||
+    !route ||
+    !mode ||
+    !(event.target instanceof Element)
+  )
+    return
+  const element = event.target.closest<HTMLElement>("[data-pmx-beat]")
+  if (!element) return
+  const index = route.beats.findIndex((beat) => beat.element === element)
+  if (index >= 0) selectBeat(index, false)
+})
+
+document.addEventListener("pointermove", revealControls, { passive: true })
+document.addEventListener("pointerdown", revealControls, { passive: true })
+document.addEventListener("keydown", revealControls, { capture: true })
+document.addEventListener("pmx:render", reconcileLocation)
+document.addEventListener("pmx:beats", () => refreshRoute())
+window.addEventListener("popstate", restoreBeatHistory)
+window.addEventListener("hashchange", () => {
+  const fragment = requestedFragment()
+  if (fragment) navigateToBeatFragment(fragment, "none")
+})
+window.addEventListener("resize", updatePlayerLayout, { passive: true })
+window.addEventListener("scroll", updateGuideFrame, { passive: true })
+window.addEventListener("load", updatePlayerLayout, { passive: true })
+window.addEventListener("pagehide", releasePresentationScroll)
+window.addEventListener("pageshow", (event) => {
+  if (mode !== "presentation") return
+  claimPresentationScroll()
+  if (event.persisted) {
+    reanchorPresentation(route?.beats[activeIndex]?.id)
+  }
+})
+
+controls.setPlaying(false)
+const initial = requestedState()
+if (initial) {
+  activate(
+    initial.mode,
+    initial.intensity,
+    initial.theme,
+    initial.guide,
+    initial.notes,
+    "instant",
+    "start",
+  )
+}