@pathmx/player 0.5.0

package/preferences.ts

@@ -0,0 +1,71 @@
+import type { PlayIntensity, PlayMode, PlayThemeChoice } from "./controls.tsx"
+import { isPlayTheme } from "./themes.ts"
+
+export type PlayPreferences = Readonly<{
+  mode: PlayMode
+  intensity: PlayIntensity
+  theme: PlayThemeChoice
+  guide: boolean
+  notes: boolean
+  autoHide: boolean
+}>
+
+const PREFERENCES_KEY = "pathmx:play-preferences"
+const LEGACY_CONTROLS_KEY = "pathmx:play-controls"
+const DEFAULTS: PlayPreferences = {
+  mode: "focus",
+  intensity: "medium",
+  theme: "source",
+  guide: true,
+  notes: true,
+  autoHide: true,
+}
+
+function readPreferences(): PlayPreferences {
+  try {
+    const value = localStorage.getItem(PREFERENCES_KEY)
+    const stored = value ? (JSON.parse(value) as Record<string, unknown>) : {}
+    const legacyAutoHide =
+      localStorage.getItem(LEGACY_CONTROLS_KEY) !== "always"
+    return {
+      mode:
+        stored.mode === "focus" || stored.mode === "presentation"
+          ? stored.mode
+          : DEFAULTS.mode,
+      intensity:
+        stored.intensity === "low" ||
+        stored.intensity === "medium" ||
+        stored.intensity === "high"
+          ? stored.intensity
+          : DEFAULTS.intensity,
+      theme:
+        stored.theme === "source" ||
+        (typeof stored.theme === "string" && isPlayTheme(stored.theme))
+          ? stored.theme
+          : DEFAULTS.theme,
+      guide: typeof stored.guide === "boolean" ? stored.guide : DEFAULTS.guide,
+      notes: typeof stored.notes === "boolean" ? stored.notes : DEFAULTS.notes,
+      autoHide:
+        typeof stored.autoHide === "boolean" ? stored.autoHide : legacyAutoHide,
+    }
+  } catch {
+    return DEFAULTS
+  }
+}
+
+/** Own the browser-local Player settings boundary and legacy migration. */
+export function createPlayPreferenceStore() {
+  let preferences = readPreferences()
+  return {
+    snapshot: () => preferences,
+    update(next: Partial<PlayPreferences>) {
+      preferences = { ...preferences, ...next }
+      try {
+        localStorage.setItem(PREFERENCES_KEY, JSON.stringify(preferences))
+      } catch {
+        // Local preference storage is optional.
+      }
+      return preferences
+    },
+  }
+}

package/progress.tsx

@@ -0,0 +1,70 @@
+import type { CSSProperties } from "react"
+
+export type PlayProgressBlock = Readonly<{
+  start: number
+  total: number
+}>
+
+type PlayProgressProps = Readonly<{
+  playing: boolean
+  mode: "focus" | "presentation"
+  index: number
+  total: number
+  blocks: readonly PlayProgressBlock[]
+}>
+
+/** Render continuous Focus progress or Beat-filled Block Slides progress. */
+export function PlayProgress(props: PlayProgressProps) {
+  const compact = props.blocks.length > 18
+  return (
+    <div
+      className="pmx-play-progressbar"
+      data-pmx-play-progressbar=""
+      data-mode={props.mode}
+      aria-hidden="true"
+      hidden={!props.playing}
+      style={
+        {
+          "--pmx-play-progress": props.total
+            ? String((props.index + 1) / props.total)
+            : "0",
+          "--pmx-play-block-gap": compact ? "3px" : "5px",
+        } as CSSProperties
+      }
+    >
+      {props.mode === "presentation" ? (
+        <span className="pmx-play-progress-blocks">
+          {props.blocks.map((block) => (
+            <span
+              className="pmx-play-progress-block"
+              data-pmx-play-progress-block=""
+              data-beats={block.total}
+              data-state={
+                props.index >= block.start + block.total
+                  ? "complete"
+                  : props.index >= block.start
+                    ? "current"
+                    : "upcoming"
+              }
+              key={block.start}
+              style={
+                {
+                  "--pmx-play-block-progress":
+                    props.index < block.start
+                      ? "0"
+                      : props.index >= block.start + block.total
+                        ? "1"
+                        : String((props.index - block.start + 1) / block.total),
+                } as CSSProperties
+              }
+            >
+              <span data-pmx-play-progress-block-fill="" />
+            </span>
+          ))}
+        </span>
+      ) : (
+        <span data-pmx-play-progress-fill="" />
+      )}
+    </div>
+  )
+}

package/ref/deckset-exports/Letters from Sweden.dstheme

@@ -0,0 +1 @@
+{"type":0,"identifier":"letters from sweden","customizations":{}}

package/ref/deckset-exports/Merriweather.dstheme

@@ -0,0 +1 @@
+{"identifier":"merriweather","type":0,"customizations":{}}

package/ref/deckset-exports/Next.dstheme

@@ -0,0 +1 @@
+{"identifier":"next","type":0,"customizations":{}}

package/route.ts

@@ -0,0 +1,231 @@
+import { explicitBeatFragment } from "./fragments.ts"
+
+export type Beat = {
+  type: "beat"
+  id: string
+  fragment?: string
+  block: HTMLElement
+  element: HTMLElement
+  target: HTMLElement
+  label: string
+  member?:
+    | Readonly<{ type: "table-row" }>
+    | Readonly<{ type: "code-lines"; lines: readonly number[] }>
+}
+
+export type PlayRoute = {
+  document: HTMLElement
+  beats: Beat[]
+}
+
+const BLOCK_SELECTOR = ":scope > section[data-pmx-block]"
+const BEAT_SELECTOR = [
+  "[data-pmx-beat]",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "p",
+  "li",
+  "blockquote",
+  "dl",
+  "figure",
+  "picture",
+  "img",
+  "svg",
+  "canvas",
+  "iframe",
+  "video",
+  "audio",
+  "pre",
+  ".pmx-code-block",
+  "table",
+  "details",
+  "form",
+  "fieldset",
+  '[data-pathmx-math="display"]',
+  '[role="img"]',
+  "[data-component]",
+].join(",")
+
+function elementMode(element: Element) {
+  return element.closest<HTMLElement>("[data-pmx-beats]")?.dataset.pmxBeats
+}
+
+function isUnavailable(element: HTMLElement) {
+  return Boolean(
+    element.closest(
+      '[hidden], template, script, style, [aria-hidden="true"], [data-pmx-app], [data-pmx-beats="off"]',
+    ),
+  )
+}
+
+function isMeaningful(element: HTMLElement) {
+  if (element.matches("p") && !element.textContent?.trim()) return false
+  if (element.matches("img")) return Boolean(element.getAttribute("alt"))
+  return true
+}
+
+function playTarget(element: HTMLElement) {
+  const selector = element.dataset.pmxPlayTarget
+  if (!selector) return element
+  try {
+    const target = document.querySelector(selector)
+    return target instanceof HTMLElement ? target : element
+  } catch {
+    console.warn(`[pathmx-play] invalid target selector: ${selector}`)
+    return element
+  }
+}
+
+function labelFor(element: HTMLElement, fallback: string) {
+  const label =
+    element.dataset.pmxBeatLabel ??
+    element.getAttribute("aria-label") ??
+    element.getAttribute("alt") ??
+    element.textContent
+  const normalized = label?.replace(/\s+/g, " ").trim()
+  return normalized ? normalized.slice(0, 120) : fallback
+}
+
+function codeLineGroups(element: HTMLElement) {
+  const authored = element.dataset.pmxCodeSteps
+  if (!authored) return []
+  return authored.split("|").flatMap((part) => {
+    const [startText, endText = startText] = part.split("-")
+    const start = Number(startText)
+    const end = Number(endText)
+    if (!Number.isInteger(start) || !Number.isInteger(end) || start < 1) {
+      return []
+    }
+    const last = Math.min(Math.max(start, end), start + 200)
+    return [
+      Array.from({ length: last - start + 1 }, (_, index) => start + index),
+    ]
+  })
+}
+
+function authoredBlockFragment(block: HTMLElement) {
+  return /^block-\d+$/u.test(block.id) ? undefined : block.id || undefined
+}
+
+/** Return the compiled presenter notes owned by one rendered Block. */
+export function playNoteForBlock(block: HTMLElement) {
+  const notes = block.querySelectorAll<HTMLElement>("[data-pmx-play-note]")
+  if (!notes.length) return
+  return [...notes].map((note) => `<p>${note.innerHTML.trim()}</p>`).join("")
+}
+
+/** Derive one flat, ordered Play route from the rendered document. */
+export function extractPlayRoute(): PlayRoute | undefined {
+  const playDocument = document.querySelector(".pmx-document")
+  if (!(playDocument instanceof HTMLElement)) return
+
+  const beats: Beat[] = []
+  const ids = new Set<string>()
+  const blocks = playDocument.querySelectorAll<HTMLElement>(BLOCK_SELECTOR)
+
+  blocks.forEach((block, blockIndex) => {
+    const blockId = block.id || `block-${blockIndex}`
+    const accepted: HTMLElement[] = []
+
+    for (const element of block.querySelectorAll<HTMLElement>(BEAT_SELECTOR)) {
+      if (isUnavailable(element)) continue
+      const explicit = element.hasAttribute("data-pmx-beat")
+      if (!explicit && elementMode(element) === "explicit") continue
+      if (!explicit && !isMeaningful(element)) continue
+
+      const component = element.closest<HTMLElement>("[data-component]")
+      if (!explicit && component && component !== element) continue
+      if (!explicit && accepted.some((parent) => parent.contains(element))) {
+        continue
+      }
+
+      const authoredValue = element.dataset.pmxBeat?.trim()
+      const authoredId = explicitBeatFragment(authoredValue)
+      if (authoredValue && !authoredId) {
+        console.warn(
+          `[pathmx-play] invalid Beat fragment ignored: ${authoredValue}`,
+        )
+      }
+      const id = authoredId || `${blockId}:beat-${beats.length}`
+      if (ids.has(id)) {
+        console.warn(`[pathmx-play] duplicate beat id ignored: ${id}`)
+        continue
+      }
+      ids.add(id)
+      accepted.push(element)
+      const target = playTarget(element)
+      if (authoredId && !element.id) {
+        const owner = document.getElementById(authoredId)
+        if (!owner || owner === element) element.id = authoredId
+        else {
+          console.warn(
+            `[pathmx-play] Beat fragment collides with an existing id: ${authoredId}`,
+          )
+        }
+      }
+      beats.push({
+        type: "beat",
+        id,
+        fragment: element.id || target.id || authoredId,
+        block,
+        element,
+        target,
+        label: labelFor(element, id),
+      })
+
+      if (element.matches("table")) {
+        for (const [rowIndex, row] of element
+          .querySelectorAll<HTMLElement>("tbody > tr")
+          .entries()) {
+          const rowId = `${id}:row-${rowIndex + 1}`
+          ids.add(rowId)
+          beats.push({
+            type: "beat",
+            id: rowId,
+            block,
+            element: row,
+            target: row,
+            label: labelFor(row, `Table row ${rowIndex + 1}`),
+            member: { type: "table-row" },
+          })
+        }
+      }
+
+      if (element.matches(".pmx-code-block")) {
+        for (const [groupIndex, lines] of codeLineGroups(element).entries()) {
+          const groupId = `${id}:lines-${groupIndex + 1}`
+          ids.add(groupId)
+          beats.push({
+            type: "beat",
+            id: groupId,
+            block,
+            element,
+            target: element,
+            label: `Code lines ${lines.join(", ")}`,
+            member: { type: "code-lines", lines },
+          })
+        }
+      }
+    }
+
+    if (accepted.length === 0) {
+      const id = `${blockId}:beat`
+      ids.add(id)
+      beats.push({
+        type: "beat",
+        id,
+        fragment: authoredBlockFragment(block),
+        block,
+        element: block,
+        target: block,
+        label: labelFor(block, blockId),
+      })
+    }
+  })
+
+  return beats.length ? { document: playDocument, beats } : undefined
+}

package/scroll.ts

@@ -0,0 +1,276 @@
+import type { PlayMode } from "./controls.ts"
+
+export type PlayScrollBehavior = "smooth" | "instant"
+
+export type PlayScrollSync = {
+  navigate(
+    target: HTMLElement,
+    block: HTMLElement,
+    mode: PlayMode,
+    behavior?: PlayScrollBehavior,
+  ): void
+  preserve(target: HTMLElement, viewportTop: number): void
+  setEnabled(enabled: boolean): void
+}
+
+const SNAP_END_SELECTOR = ":scope > [data-pmx-play-snap-end]"
+
+/** Keep bottom-edge snap targets limited to document-scrolling tall Blocks. */
+export function syncPresentationSnapTargets(
+  playDocument: HTMLElement,
+  enabled: boolean,
+) {
+  const blocks = playDocument.querySelectorAll<HTMLElement>(
+    ":scope > section[data-pmx-block]",
+  )
+  for (const block of blocks) {
+    const existing = block.querySelector<HTMLElement>(SNAP_END_SELECTOR)
+    const needsEndTarget =
+      enabled && block.getBoundingClientRect().height > innerHeight + 1
+    if (!needsEndTarget) {
+      existing?.remove()
+      continue
+    }
+    if (existing) continue
+    const marker = document.createElement("span")
+    marker.dataset.pmxPlaySnapEnd = ""
+    marker.setAttribute("aria-hidden", "true")
+    block.append(marker)
+  }
+}
+
+/**
+ * Keep native scrolling authoritative. User scrolling suspends the spotlight;
+ * once it settles, the controller adopts the visible Beat without scrolling
+ * back. Programmatic Play navigation never enters that adoption path.
+ */
+export function createPlayScrollSync(callbacks: {
+  start(): void
+  settle(): void
+  track(tracking: boolean): void
+}): PlayScrollSync {
+  let enabled = false
+  let programmatic = false
+  let scrolling = false
+  let tracking = false
+  let settleTimer: number | undefined
+  let programTimer: number | undefined
+  let snapReleaseFrame: number | undefined
+  let userIntentUntil = 0
+
+  const markUserIntent = () => {
+    userIntentUntil = performance.now() + 700
+  }
+
+  const clearTimer = (timer: number | undefined) => {
+    if (timer !== undefined) window.clearTimeout(timer)
+  }
+
+  const releasePresentationSnap = () => {
+    if (snapReleaseFrame !== undefined) {
+      cancelAnimationFrame(snapReleaseFrame)
+      snapReleaseFrame = undefined
+    }
+    document.documentElement.removeAttribute(
+      "data-pmx-play-programmatic-scroll",
+    )
+  }
+
+  const suspendPresentationSnap = () => {
+    releasePresentationSnap()
+    document.documentElement.setAttribute(
+      "data-pmx-play-programmatic-scroll",
+      "",
+    )
+    snapReleaseFrame = requestAnimationFrame(() => {
+      snapReleaseFrame = requestAnimationFrame(releasePresentationSnap)
+    })
+  }
+
+  const setTracking = (value: boolean) => {
+    if (tracking === value) return
+    tracking = value
+    callbacks.track(value)
+  }
+
+  const settle = () => {
+    clearTimer(settleTimer)
+    settleTimer = undefined
+    if (programmatic) return
+    if (!scrolling) return
+    scrolling = false
+    userIntentUntil = 0
+    callbacks.settle()
+  }
+
+  const onScroll = (event: Event) => {
+    if (event.target !== document) return
+    if (!enabled) return
+    if (programmatic) {
+      clearTimer(programTimer)
+      programTimer = window.setTimeout(() => {
+        programmatic = false
+        setTracking(false)
+      }, 700)
+      return
+    }
+    if (!scrolling) {
+      if (performance.now() > userIntentUntil) return
+      scrolling = true
+      callbacks.start()
+    }
+    clearTimer(settleTimer)
+    settleTimer = window.setTimeout(settle, 160)
+  }
+
+  const onUserIntent = () => {
+    if (!enabled) return
+    releasePresentationSnap()
+    markUserIntent()
+    programmatic = false
+    setTracking(false)
+  }
+
+  const onKeyboardIntent = (event: KeyboardEvent) => {
+    if (
+      event.altKey ||
+      event.metaKey ||
+      event.ctrlKey ||
+      ![
+        "ArrowDown",
+        "ArrowUp",
+        "PageDown",
+        "PageUp",
+        "Home",
+        "End",
+        " ",
+      ].includes(event.key)
+    )
+      return
+    queueMicrotask(() => {
+      if (!event.defaultPrevented) onUserIntent()
+    })
+  }
+
+  const onScrollEnd = (event: Event) => {
+    if (event.target !== document) return
+    if (programmatic) {
+      clearTimer(programTimer)
+      programmatic = false
+      setTracking(false)
+      return
+    }
+    settle()
+  }
+
+  const focusOffset = (target: HTMLElement) => {
+    const rect = target.getBoundingClientRect()
+    const safeTop = innerHeight * 0.16
+    const safeBottom = innerHeight * 0.84
+    const fullyComfortable = rect.top >= safeTop && rect.bottom <= safeBottom
+    if (fullyComfortable) return 0
+    const playhead =
+      innerHeight * (rect.height > innerHeight * 0.65 ? 0.1 : 0.42)
+    return rect.top - playhead
+  }
+
+  const presentationScrollTarget = (
+    target: HTMLElement,
+    block: HTMLElement,
+  ) => {
+    const targetRect = target.getBoundingClientRect()
+    const blockRect = block.getBoundingClientRect()
+    const inset = Math.min(32, innerHeight * 0.08)
+    const visibleTop = Math.max(0, blockRect.top) + inset
+    const visibleBottom = Math.min(innerHeight, blockRect.bottom) - inset
+    if (targetRect.top >= visibleTop && targetRect.bottom <= visibleBottom) {
+      return
+    }
+
+    const localTop = targetRect.top - blockRect.top + block.scrollTop
+    const blockStartViewport = Math.min(block.clientHeight, innerHeight)
+    const fitsAtBlockStart =
+      localTop >= inset &&
+      localTop + targetRect.height <= blockStartViewport - inset
+    return fitsAtBlockStart ? block : target
+  }
+
+  document.addEventListener("scroll", onScroll, {
+    capture: true,
+    passive: true,
+  })
+  document.addEventListener("scrollend", onScrollEnd, { capture: true })
+  window.addEventListener("wheel", onUserIntent, { passive: true })
+  window.addEventListener("touchstart", onUserIntent, { passive: true })
+  window.addEventListener("pointerdown", onUserIntent, { passive: true })
+  document.addEventListener("keydown", onKeyboardIntent, { capture: true })
+
+  return {
+    navigate(target, block, mode, requestedBehavior = "smooth") {
+      programmatic = true
+      setTracking(true)
+      scrolling = false
+      userIntentUntil = 0
+      clearTimer(settleTimer)
+      clearTimer(programTimer)
+      const behavior =
+        requestedBehavior === "instant" ||
+        matchMedia("(prefers-reduced-motion: reduce)").matches
+          ? "instant"
+          : "smooth"
+      if (mode === "presentation") {
+        const destination = presentationScrollTarget(target, block)
+        if (!destination) {
+          programmatic = false
+          setTracking(false)
+          return
+        }
+        if (behavior === "instant") suspendPresentationSnap()
+        destination.scrollIntoView({
+          behavior,
+          block: destination === block ? "start" : "nearest",
+          inline: "nearest",
+        })
+      } else {
+        const top = focusOffset(target)
+        if (Math.abs(top) < 0.5) {
+          programmatic = false
+          setTracking(false)
+          return
+        }
+        window.scrollBy({ top, behavior })
+      }
+      programTimer = window.setTimeout(() => {
+        programmatic = false
+        setTracking(false)
+      }, 700)
+    },
+    preserve(target, viewportTop) {
+      programmatic = true
+      setTracking(true)
+      scrolling = false
+      userIntentUntil = 0
+      clearTimer(settleTimer)
+      clearTimer(programTimer)
+      const shift = target.getBoundingClientRect().top - viewportTop
+      if (Math.abs(shift) > 0.5) {
+        window.scrollBy({ top: shift, behavior: "instant" })
+      }
+      programTimer = window.setTimeout(() => {
+        programmatic = false
+        setTracking(false)
+      }, 100)
+    },
+    setEnabled(value) {
+      enabled = value
+      if (value) return
+      programmatic = false
+      setTracking(false)
+      scrolling = false
+      userIntentUntil = 0
+      clearTimer(settleTimer)
+      clearTimer(programTimer)
+      releasePresentationSnap()
+    },
+  }
+}

package/themes.ts

@@ -0,0 +1,39 @@
+import type { SourceDescription } from "@pathmx/core"
+
+export type PlayThemeId = "native" | "editorial" | "signal" | "code"
+
+export type PlayTheme = Readonly<{
+  id: PlayThemeId
+  label: string
+  description: string
+}>
+
+export const PLAY_THEMES: readonly PlayTheme[] = [
+  { id: "native", label: "Native", description: "Neutral PathMX baseline" },
+  {
+    id: "editorial",
+    label: "Editorial",
+    description: "Warm serif-led reading",
+  },
+  {
+    id: "signal",
+    label: "Signal",
+    description: "Bold, high-contrast talks",
+  },
+  {
+    id: "code",
+    label: "Code",
+    description: "Dark technical teaching",
+  },
+]
+
+export function isPlayTheme(value: unknown): value is PlayThemeId {
+  return PLAY_THEMES.some((theme) => theme.id === value)
+}
+
+export function sourcePlayTheme(description: SourceDescription): PlayThemeId {
+  const play = description.source.data.play
+  if (!play || typeof play !== "object" || Array.isArray(play)) return "native"
+  const theme = (play as Readonly<Record<string, unknown>>).theme
+  return isPlayTheme(theme) ? theme : "native"
+}