@pathmx/player 0.5.0

package/gestures.ts

@@ -0,0 +1,143 @@
+type PlayerGestureCommands = Readonly<{
+  enabled(): boolean
+  surface(): HTMLElement | undefined
+  moveBeat(offset: -1 | 1): void
+  moveBlock(offset: -1 | 1): void
+}>
+
+type PointerOrigin = Readonly<{
+  id: number
+  x: number
+  y: number
+  time: number
+  axis?: "horizontal" | "vertical"
+}>
+
+const TAP_SLOP = 12
+const TAP_DURATION = 500
+const DIRECTION_LOCK_DISTANCE = 10
+const SWIPE_DISTANCE = 48
+const SWIPE_DOMINANCE = 1.5
+const PREVIOUS_TAP_ZONE = 1 / 3
+
+function ownsGesture(surface: HTMLElement, target: EventTarget | null) {
+  if (!(target instanceof Element) || !surface.contains(target)) return false
+  return !target.closest(
+    [
+      "a",
+      "button",
+      "input",
+      "select",
+      "textarea",
+      "summary",
+      "video",
+      "audio",
+      "iframe",
+      "[contenteditable]:not([contenteditable='false'])",
+      "[role='button']",
+      "[role='link']",
+      "[data-pmx-player-control]",
+    ].join(", "),
+  )
+}
+
+/** Install Slides-only touch navigation without claiming interactive content. */
+export function installPlayerGestures(commands: PlayerGestureCommands) {
+  let origin: PointerOrigin | undefined
+  let tapTimer: number | undefined
+
+  const reset = () => {
+    origin = undefined
+  }
+  const clearTap = () => {
+    if (tapTimer !== undefined) window.clearTimeout(tapTimer)
+    tapTimer = undefined
+  }
+  const pointerdown = (event: PointerEvent) => {
+    clearTap()
+    if (
+      !commands.enabled() ||
+      event.pointerType !== "touch" ||
+      !event.isPrimary ||
+      event.button !== 0
+    ) {
+      reset()
+      return
+    }
+    const surface = commands.surface()
+    if (!surface || !ownsGesture(surface, event.target)) {
+      reset()
+      return
+    }
+    origin = {
+      id: event.pointerId,
+      x: event.clientX,
+      y: event.clientY,
+      time: event.timeStamp,
+    }
+  }
+  const pointerup = (event: PointerEvent) => {
+    const start = origin
+    reset()
+    if (!start || start.id !== event.pointerId || !commands.enabled()) return
+    const surface = commands.surface()
+    if (!surface || !ownsGesture(surface, event.target)) return
+
+    const x = event.clientX - start.x
+    const y = event.clientY - start.y
+    const distance = Math.hypot(x, y)
+    if (
+      Math.abs(x) >= SWIPE_DISTANCE &&
+      (start.axis === "horizontal" ||
+        (!start.axis && Math.abs(x) > Math.abs(y) * SWIPE_DOMINANCE))
+    ) {
+      event.preventDefault()
+      commands.moveBlock(x < 0 ? 1 : -1)
+      return
+    }
+    if (distance > TAP_SLOP || event.timeStamp - start.time > TAP_DURATION)
+      return
+    event.preventDefault()
+    const rect = surface.getBoundingClientRect()
+    const position = (event.clientX - rect.left) / rect.width
+    tapTimer = window.setTimeout(() => {
+      tapTimer = undefined
+      if (!commands.enabled()) return
+      commands.moveBeat(position < PREVIOUS_TAP_ZONE ? -1 : 1)
+    })
+  }
+  const pointermove = (event: PointerEvent) => {
+    const start = origin
+    if (!start || start.id !== event.pointerId || !commands.enabled()) return
+    const x = event.clientX - start.x
+    const y = event.clientY - start.y
+    if (!start.axis && Math.hypot(x, y) >= DIRECTION_LOCK_DISTANCE) {
+      const axis =
+        Math.abs(x) > Math.abs(y) * SWIPE_DOMINANCE
+          ? "horizontal"
+          : Math.abs(y) > Math.abs(x) * SWIPE_DOMINANCE
+            ? "vertical"
+            : undefined
+      if (axis) origin = { ...start, axis }
+    }
+    if (origin?.axis === "horizontal") event.preventDefault()
+  }
+  const pointercancel = () => {
+    reset()
+    clearTap()
+  }
+
+  document.addEventListener("pointerdown", pointerdown, { capture: true })
+  document.addEventListener("pointermove", pointermove, { capture: true })
+  document.addEventListener("pointerup", pointerup, { capture: true })
+  document.addEventListener("pointercancel", pointercancel, { capture: true })
+  return () => {
+    clearTap()
+    document.removeEventListener("pointerdown", pointerdown, { capture: true })
+    document.removeEventListener("pointermove", pointermove, { capture: true })
+    document.removeEventListener("pointerup", pointerup, { capture: true })
+    document.removeEventListener("pointercancel", pointercancel, {
+      capture: true,
+    })
+  }
+}

package/grid.ts

@@ -0,0 +1,199 @@
+import type { PlayRoute } from "./route.ts"
+
+export type PlayGridDirection = "up" | "down" | "left" | "right"
+
+type GridTarget = {
+  block: HTMLElement
+  beatIndex: number
+  current: boolean
+}
+
+type PreviousAttributes = {
+  ariaCurrent: string | null
+  gridBlock: string | null
+  tabIndex: string | null
+}
+
+type PlayGridOptions = Readonly<{
+  route(): PlayRoute | undefined
+  activeIndex(): number
+  seenThrough(): number
+  select(beatIndex: number): void
+}>
+
+const ROOT_ATTRIBUTE = "data-pmx-play-grid"
+const BLOCK_ATTRIBUTE = "data-pmx-play-grid-block"
+const ROW_TOLERANCE = 8
+
+function setOrRemove(element: HTMLElement, name: string, value: string | null) {
+  if (value === null) element.removeAttribute(name)
+  else element.setAttribute(name, value)
+}
+
+function gridTargets(
+  route: PlayRoute,
+  activeIndex: number,
+  seenThrough: number,
+) {
+  const ranges = new Map<HTMLElement, { first: number; last: number }>()
+  route.beats.forEach((beat, index) => {
+    const range = ranges.get(beat.block)
+    if (range) range.last = index
+    else ranges.set(beat.block, { first: index, last: index })
+  })
+  return [...ranges].map(([block, range]) => ({
+    block,
+    beatIndex: range.first,
+    current: range.first <= activeIndex && activeIndex <= range.last,
+  }))
+}
+
+function targetState(target: GridTarget, seenThrough: number) {
+  if (target.current) return "current"
+  return target.beatIndex <= seenThrough ? "seen" : "upcoming"
+}
+
+function positioned(targets: readonly GridTarget[]) {
+  return targets
+    .map((target, order) => {
+      const rect = target.block.getBoundingClientRect()
+      return {
+        centerX: rect.left + rect.width / 2,
+        order,
+        rect,
+        target,
+      }
+    })
+    .sort(
+      (left, right) =>
+        left.rect.top - right.rect.top ||
+        left.rect.left - right.rect.left ||
+        left.order - right.order,
+    )
+}
+
+function arrowTarget(
+  targets: readonly GridTarget[],
+  current: GridTarget | undefined,
+  direction: PlayGridDirection,
+) {
+  const items = positioned(targets)
+  if (!items.length) return
+  const active =
+    items.find((item) => item.target.block === current?.block) ?? items[0]!
+
+  if (direction === "left" || direction === "right") {
+    const index = items.indexOf(active)
+    const offset = direction === "left" ? -1 : 1
+    return items[Math.max(0, Math.min(items.length - 1, index + offset))]
+      ?.target
+  }
+
+  const rows: Array<{ top: number; items: typeof items }> = []
+  for (const item of items) {
+    const row = rows.find(
+      (candidate) => Math.abs(candidate.top - item.rect.top) <= ROW_TOLERANCE,
+    )
+    if (row) row.items.push(item)
+    else rows.push({ top: item.rect.top, items: [item] })
+  }
+  const rowIndex = rows.findIndex((row) => row.items.includes(active))
+  const row = rows[rowIndex + (direction === "up" ? -1 : 1)]
+  if (!row) return active.target
+  return row.items.reduce((nearest, candidate) =>
+    Math.abs(candidate.centerX - active.centerX) <
+    Math.abs(nearest.centerX - active.centerX)
+      ? candidate
+      : nearest,
+  ).target
+}
+
+/** Temporarily projects the rendered Blocks into a selectable overview. */
+export function createPlayGrid(options: PlayGridOptions) {
+  let open = false
+  let targets: GridTarget[] = []
+  let focused: GridTarget | undefined
+  let disposeTargets = () => {}
+  let focusFrame = 0
+
+  function clearTargets() {
+    cancelAnimationFrame(focusFrame)
+    disposeTargets()
+    disposeTargets = () => {}
+    targets = []
+    focused = undefined
+  }
+
+  function applyTargets() {
+    clearTargets()
+    const route = options.route()
+    if (!open || !route) return
+    targets = gridTargets(route, options.activeIndex(), options.seenThrough())
+    const previous = new Map<HTMLElement, PreviousAttributes>()
+    const listeners = targets.map((target) => {
+      const { block } = target
+      previous.set(block, {
+        ariaCurrent: block.getAttribute("aria-current"),
+        gridBlock: block.getAttribute(BLOCK_ATTRIBUTE),
+        tabIndex: block.getAttribute("tabindex"),
+      })
+      block.setAttribute(
+        BLOCK_ATTRIBUTE,
+        targetState(target, options.seenThrough()),
+      )
+      block.setAttribute("tabindex", "0")
+      if (target.current) block.setAttribute("aria-current", "true")
+      else block.removeAttribute("aria-current")
+
+      const select = (event: MouseEvent) => {
+        event.preventDefault()
+        event.stopPropagation()
+        options.select(target.beatIndex)
+      }
+      const rememberFocus = () => {
+        focused = target
+      }
+      block.addEventListener("click", select, { capture: true })
+      block.addEventListener("focusin", rememberFocus)
+      return () => {
+        block.removeEventListener("click", select, { capture: true })
+        block.removeEventListener("focusin", rememberFocus)
+      }
+    })
+    focused = targets.find((target) => target.current) ?? targets[0]
+    focusFrame = requestAnimationFrame(() => {
+      focused?.block.focus({ preventScroll: true })
+      focused?.block.scrollIntoView({ block: "center", inline: "nearest" })
+    })
+    disposeTargets = () => {
+      for (const dispose of listeners) dispose()
+      for (const [block, attributes] of previous) {
+        setOrRemove(block, "aria-current", attributes.ariaCurrent)
+        setOrRemove(block, BLOCK_ATTRIBUTE, attributes.gridBlock)
+        setOrRemove(block, "tabindex", attributes.tabIndex)
+      }
+    }
+  }
+
+  function setOpen(next: boolean) {
+    if (next === open) return
+    open = next
+    document.documentElement.toggleAttribute(ROOT_ATTRIBUTE, open)
+    if (open) applyTargets()
+    else clearTargets()
+  }
+
+  return {
+    isOpen: () => open,
+    setOpen,
+    move(direction: PlayGridDirection) {
+      if (!open) return
+      focused = arrowTarget(targets, focused, direction)
+      focused?.block.focus({ preventScroll: true })
+      focused?.block.scrollIntoView({ block: "nearest", inline: "nearest" })
+    },
+    selectFocused() {
+      if (open && focused) options.select(focused.beatIndex)
+    },
+  }
+}

package/guide.ts

@@ -0,0 +1,86 @@
+import type { Beat } from "./route.ts"
+
+export type PlayGuideFrame = Readonly<{
+  guideLeft: number
+  top: number
+  height: number
+  targetLeft: number
+  targetWidth: number
+  highlight: "none" | "row" | "code"
+}>
+
+const GUIDE_GAP = 12
+const GUIDE_WIDTH = 3
+
+function pixelValue(value: string, fallback = 0) {
+  const parsed = Number.parseFloat(value)
+  return Number.isFinite(parsed) ? parsed : fallback
+}
+
+function contentLeft(target: HTMLElement, rect: DOMRect) {
+  if (!target.matches("li")) return rect.left
+  const style = getComputedStyle(target)
+  if (style.listStylePosition === "inside" || style.listStyleType === "none") {
+    return rect.left
+  }
+  const marker = getComputedStyle(target, "::marker")
+  const fontSize = pixelValue(marker.fontSize, pixelValue(style.fontSize))
+  const markerWidth = pixelValue(marker.width, fontSize * 0.4)
+  return rect.left - markerWidth - fontSize * 0.5
+}
+
+function guideLeft(target: HTMLElement, rect: DOMRect) {
+  return contentLeft(target, rect) - GUIDE_GAP - GUIDE_WIDTH
+}
+
+function normalFrame(
+  target: HTMLElement,
+  rect: DOMRect,
+  highlight: PlayGuideFrame["highlight"] = "none",
+): PlayGuideFrame {
+  return {
+    guideLeft: guideLeft(target, rect),
+    top: rect.top,
+    height: Math.max(3, rect.height),
+    targetLeft: rect.left,
+    targetWidth: rect.width,
+    highlight,
+  }
+}
+
+function codeFrame(beat: Beat, rect: DOMRect): PlayGuideFrame {
+  const code = beat.target.querySelector<HTMLElement>("pre code")
+  const lines = beat.member?.type === "code-lines" ? beat.member.lines : []
+  if (!code || !lines.length) return normalFrame(beat.target, rect)
+  const codeRect = code.getBoundingClientRect()
+  const style = getComputedStyle(code)
+  const lineHeight = Number.parseFloat(style.lineHeight)
+  const paddingTop = pixelValue(style.paddingTop)
+  const paddingLeft = pixelValue(style.paddingLeft)
+  const paddingRight = pixelValue(style.paddingRight)
+  const sourceLines = Math.max(1, code.textContent?.split("\n").length ?? 1)
+  const measuredLineHeight = Number.isFinite(lineHeight)
+    ? lineHeight
+    : codeRect.height / sourceLines
+  const first = Math.min(...lines)
+  const last = Math.max(...lines)
+  return {
+    guideLeft: guideLeft(beat.target, rect),
+    top: codeRect.top + paddingTop + (first - 1) * measuredLineHeight,
+    height: Math.max(3, (last - first + 1) * measuredLineHeight),
+    targetLeft: codeRect.left + paddingLeft,
+    targetWidth: Math.max(0, codeRect.width - paddingLeft - paddingRight),
+    highlight: "code",
+  }
+}
+
+/** Measure the Player-owned guide against the active rendered Beat member. */
+export function measurePlayGuide(beat: Beat): PlayGuideFrame {
+  const rect = beat.target.getBoundingClientRect()
+  if (beat.member?.type === "code-lines") return codeFrame(beat, rect)
+  return normalFrame(
+    beat.target,
+    rect,
+    beat.member?.type === "table-row" ? "row" : "none",
+  )
+}

package/index.ts

@@ -0,0 +1,59 @@
+import {
+  defineAppComponent,
+  html,
+  type AppContext,
+  type Plugin,
+} from "@pathmx/core"
+import { explicitBeatFragment } from "./fragments.ts"
+import { rewritePlayMedia } from "./media.ts"
+import { rewritePlayNotes } from "./notes.ts"
+
+function rewriteBeatFragments(html: string, app: AppContext) {
+  if (!html.includes("data-pmx-beat")) return html
+  return app.html.rewrite(html, [
+    [
+      "[data-pmx-beat]",
+      {
+        element(beat) {
+          if (beat.getAttribute("id")) return
+          const fragment = explicitBeatFragment(
+            beat.getAttribute("data-pmx-beat"),
+          )
+          if (fragment) beat.setAttribute("id", fragment)
+        },
+      },
+    ],
+  ])
+}
+
+const PlayerApp = defineAppComponent({
+  tag: "player:app",
+  client: new URL("./client.ts", import.meta.url),
+  async render(_use, _compiled, ctx) {
+    const description = await ctx.view.describeSource(ctx.source.id)
+    if (!description) return ""
+    return html`<div
+      data-component="player:app"
+      data-description="${JSON.stringify(description)}"
+    ></div>`
+  },
+})
+
+/** Authored React app for focused reading and slide presentation. */
+export function PlayerPlugin(): Plugin {
+  return {
+    id: "player",
+    name: "PlayerPlugin",
+    requires: ["image", "block-layout"],
+    components: [PlayerApp],
+    postcompile(html, { block }, app) {
+      if (!block) return html
+      return rewriteBeatFragments(
+        rewritePlayMedia(rewritePlayNotes(html), app),
+        app,
+      )
+    },
+  }
+}
+
+export default PlayerPlugin

package/keyboard.ts

@@ -0,0 +1,172 @@
+type PlayerKeyboardCommands = Readonly<{
+  active(): boolean
+  start(): void
+  controlsExpanded(): boolean
+  gridOpen(): boolean
+  actionCount(): number
+  activateAction(index: number): void
+  adjustIntensity(offset: -1 | 1): void
+  move(offset: -1 | 1): void
+  moveBlock(offset: -1 | 1): void
+  moveGrid(direction: "up" | "down" | "left" | "right"): void
+  selectGrid(): void
+  toggleGrid(): void
+  toggleMode(): void
+  exit(): void
+}>
+
+function isInteractive(target: EventTarget | null) {
+  return (
+    target instanceof Element &&
+    Boolean(
+      target.closest(
+        "a, button, input, select, textarea, summary, [contenteditable]:not([contenteditable='false'])",
+      ),
+    )
+  )
+}
+
+function isPlayerBeatButton(target: EventTarget | null) {
+  return (
+    target instanceof HTMLButtonElement && target.hasAttribute("data-pmx-beat")
+  )
+}
+
+function isPlayerControl(target: EventTarget | null) {
+  return (
+    target instanceof Element &&
+    Boolean(target.closest("[data-pmx-player-control]"))
+  )
+}
+
+function isEditable(target: EventTarget | null) {
+  return (
+    target instanceof Element &&
+    Boolean(
+      target.closest(
+        "input, select, textarea, [contenteditable]:not([contenteditable='false'])",
+      ),
+    )
+  )
+}
+
+function isBeatNavigationKey(event: KeyboardEvent) {
+  return (
+    event.key === "ArrowDown" ||
+    event.key === "ArrowUp" ||
+    event.key === "ArrowRight" ||
+    event.key === "ArrowLeft" ||
+    event.key === "PageDown" ||
+    event.key === "PageUp"
+  )
+}
+
+/**
+ * Play entry is a mode change: a launch link or button must not keep keyboard
+ * ownership and turn the first arrow press into native page scrolling.
+ * Editable controls retain focus so programmatic activation cannot interrupt
+ * input unexpectedly.
+ */
+export function returnKeyboardToDocument() {
+  const active = document.activeElement
+  if (!(active instanceof HTMLElement)) return
+  if (
+    active.matches(
+      "input, select, textarea, [contenteditable]:not([contenteditable='false'])",
+    )
+  ) {
+    return
+  }
+  active.blur()
+}
+
+/** Own Player's document-level keyboard mapping outside the session controller. */
+export function installPlayerKeyboard(commands: PlayerKeyboardCommands) {
+  const keydown = (event: KeyboardEvent) => {
+    const activation =
+      event.key === "Enter" &&
+      (event.metaKey || event.ctrlKey) &&
+      !event.altKey &&
+      !event.shiftKey
+    if (activation) {
+      if (!isEditable(event.target)) {
+        event.preventDefault()
+        if (!commands.active()) commands.start()
+      }
+      return
+    }
+    if (!commands.active()) return
+    if (commands.controlsExpanded()) return
+    const interactive =
+      isInteractive(event.target) && !isPlayerControl(event.target)
+    if (
+      interactive &&
+      !isPlayerBeatButton(event.target) &&
+      (!isBeatNavigationKey(event) ||
+        isEditable(event.target) ||
+        isPlayerControl(event.target))
+    )
+      return
+    let run: (() => void) | undefined
+    const key = event.key.toLowerCase()
+    const unmodified = !event.altKey && !event.metaKey && !event.ctrlKey
+    if (commands.gridOpen()) {
+      if (event.key === "Escape" || (unmodified && key === "g")) {
+        run = commands.toggleGrid
+      } else if (event.key === "ArrowDown") {
+        run = () => commands.moveGrid("down")
+      } else if (event.key === "ArrowUp") {
+        run = () => commands.moveGrid("up")
+      } else if (event.key === "ArrowRight") {
+        run = () => commands.moveGrid("right")
+      } else if (event.key === "ArrowLeft") {
+        run = () => commands.moveGrid("left")
+      } else if (event.key === "Enter" || event.key === " ") {
+        run = commands.selectGrid
+      }
+    } else if (event.key === "Escape") run = commands.exit
+    else if (unmodified && key === "g") run = commands.toggleGrid
+    else if (unmodified && key === "m") run = commands.toggleMode
+    else if (unmodified && (event.key === "+" || event.key === "=")) {
+      run = () => commands.adjustIntensity(1)
+    } else if (unmodified && (event.key === "-" || event.key === "_")) {
+      run = () => commands.adjustIntensity(-1)
+    } else if (!interactive && /^[1-9]$/.test(event.key)) {
+      const index = Number(event.key) - 1
+      if (index < commands.actionCount()) {
+        run = () => commands.activateAction(index)
+      }
+    } else if (
+      !interactive &&
+      event.key === "Enter" &&
+      commands.actionCount()
+    ) {
+      run = () => commands.activateAction(0)
+    } else if (
+      event.key === "ArrowDown" ||
+      event.key === "PageDown" ||
+      (event.key === " " && !event.shiftKey)
+    ) {
+      run = () => commands.move(1)
+    } else if (
+      event.key === "ArrowUp" ||
+      event.key === "PageUp" ||
+      (event.key === " " && event.shiftKey)
+    ) {
+      run = () => commands.move(-1)
+    } else if (event.key === "ArrowRight") {
+      run = () => commands.moveBlock(1)
+    } else if (event.key === "ArrowLeft") {
+      run = () => commands.moveBlock(-1)
+    }
+    if (!run) return
+    event.preventDefault()
+    run()
+    if (!commands.gridOpen() && isBeatNavigationKey(event)) {
+      returnKeyboardToDocument()
+    }
+  }
+  document.addEventListener("keydown", keydown, { capture: true })
+  return () =>
+    document.removeEventListener("keydown", keydown, { capture: true })
+}

package/media.ts

@@ -0,0 +1,47 @@
+import type { AppContext } from "@pathmx/core"
+
+/** Keep background images out of the presentation Beat route. */
+export function rewritePlayMedia(html: string, app: AppContext) {
+  if (!html.includes('data-pmx-image="background"')) return html
+  return app.html.rewrite(html, [
+    [
+      'img[data-pmx-image="background"]',
+      {
+        element(image) {
+          image.setAttribute("data-pmx-beats", "off")
+        },
+      },
+    ],
+  ])
+}
+
+function standaloneImageFrame(image: HTMLImageElement) {
+  const parent = image.parentElement
+  return parent?.matches("p") &&
+    parent.childElementCount === 1 &&
+    parent.firstElementChild === image
+    ? parent
+    : image
+}
+
+/** Mark the rendered container that participates in Player slide layout. */
+export function applyPlayMediaFrames(root: ParentNode) {
+  for (const previous of root.querySelectorAll<HTMLElement>(
+    "[data-pmx-play-media-frame]",
+  )) {
+    previous.removeAttribute("data-pmx-play-media-frame")
+    previous.removeAttribute("data-pmx-play-media")
+    previous.removeAttribute("data-pmx-play-fit")
+  }
+
+  for (const image of root.querySelectorAll<HTMLImageElement>("img")) {
+    const frame = standaloneImageFrame(image)
+    frame.setAttribute("data-pmx-play-media-frame", "")
+    if (image.dataset.pmxImage) {
+      frame.dataset.pmxPlayMedia = image.dataset.pmxImage
+    }
+    if (image.dataset.pmxImageFit) {
+      frame.dataset.pmxPlayFit = image.dataset.pmxImageFit
+    }
+  }
+}