@lincyaw/addon-motion 0.0.0-stage → 1.0.0-rc.1

package/src/client/SceneView.tsx

@@ -0,0 +1,424 @@
+import {
+  NAVIGATION,
+  PLAYBACK_CONTROL,
+  PmIconButton,
+  STEP_CLOCK,
+  useAppearance,
+  useCursor,
+  useMessages,
+  useService,
+  useStep,
+  useStepScope,
+  useStepTime,
+  useStaticRender,
+  useStore,
+  useViewRole,
+} from '@lincyaw/host'
+import type { PlaybackLease } from '@lincyaw/host'
+import { errorMessage } from '@lincyaw/kernel'
+import { useEffect, useLayoutEffect, useRef, useState } from 'react'
+import type { CSSProperties } from 'react'
+import type { SceneProps } from '../../components/PmScene.tsx'
+import {
+  MOTION_MESSAGES,
+  stepStarts,
+  timelinePosition,
+} from '../domain/index.ts'
+import { loadScene, preloadScenes } from './deck-scenes.ts'
+import type { Scene } from './scene.ts'
+import './scene.css'
+
+export default function SceneView(props: SceneProps) {
+  const t = useMessages(MOTION_MESSAGES)
+  const durations = props.durations?.length ? props.durations : [0]
+  const starts = stepStarts(durations)
+  const total = starts.at(-1)!
+  const scope = useStepScope()
+  const hostStep = useStep()
+  const cursor = useCursor()
+  const viewRole = useViewRole()
+  const navigation = useService(NAVIGATION)
+  const navigated = useStore(navigation?.position, undefined)
+  const clock = useService(STEP_CLOCK)
+  const playbackControl = useService(PLAYBACK_CONTROL)
+  const printed = useStaticRender()
+  const stepTime = useStepTime({ until: Math.max(...durations) })
+  const { dark } = useAppearance()
+  const expanded = scope.localPreview === true || !Number.isFinite(hostStep)
+  const [seen, setSeen] = useState(!expanded || printed)
+  const enabled = seen || printed || !expanded
+  const [local, setLocal] = useState<number>()
+  const [playing, setPlaying] = useState(false)
+  const [status, setStatus] = useState<
+    'loading' | 'ready' | 'missing' | 'failed'
+  >('loading')
+  const [failure, setFailure] = useState('')
+  const stage = useRef<HTMLDivElement>(null)
+  const instance = useRef<Scene | undefined>(undefined)
+  const frame = useRef(0)
+  const localTime = useRef<number | undefined>(undefined)
+  const previewReplay = useRef<number>()
+  const playbackLease = useRef<PlaybackLease>()
+  const playbackGeneration = useRef(0)
+  const activePlayback = useRef<number>()
+  const localNavigation = useRef<{ slide: number, step: number }>()
+  const followedNavigation = useRef({ source: navigation, position: navigated })
+  const shown =
+    expanded && local !== undefined
+      ? local
+      : timelinePosition(durations, scope.localStepAt(hostStep), stepTime)
+  const shownNow = useRef(shown)
+  shownNow.current = shown
+  const activeLocalStep = scope.localStepAt(hostStep)
+  const requestedStart = scope.localPreview && navigated?.boundary === 'start' && Number.isFinite(activeLocalStep) && local === starts[activeLocalStep] ? activeLocalStep : undefined
+  const selectedStep = Math.max(
+    0,
+    Math.min(
+      durations.length - 1,
+      expanded && local !== undefined
+        ? requestedStart ?? Math.max(
+            0,
+            starts.findIndex(
+              (start, i) =>
+                i < durations.length && local <= start + durations[i]!,
+            ),
+          )
+        : activeLocalStep,
+    ),
+  )
+  // A reader's local controls do not navigate the full document. Resolve their
+  // own authored snapshot while retaining the same local animation clock.
+  const localState = expanded && !scope.localPreview && local !== undefined ? scope.stateAt(selectedStep) : undefined
+  const sceneState = localState ? localState.state : scope.state
+  const sceneParameters = localState ? localState.parameters ?? {} : scope.parameters ?? {}
+  const stop = () => {
+    playbackGeneration.current++
+    activePlayback.current = undefined
+    playbackLease.current?.cancel()
+    localNavigation.current = undefined
+    cancelAnimationFrame(frame.current)
+    setPlaying(false)
+  }
+  useEffect(() => {
+    const lease = playbackControl?.register(stop)
+    playbackLease.current = lease
+    return () => {
+      if (playbackLease.current === lease) playbackLease.current = undefined
+      lease?.dispose()
+    }
+  }, [playbackControl])
+  const seekLocal = (at: number) => {
+    stop()
+    previewReplay.current = undefined
+    localTime.current = at
+    setLocal(at)
+  }
+  const jump = (step: number) => {
+    seekLocal(starts[step]! + durations[step]!)
+    if (scope.localPreview) previewReplay.current = step
+    const target = scope.step(step)
+    if (scope.localPreview && target >= 0) navigation?.go({ slide: cursor.slide, step: target })
+  }
+  const fail = (error: unknown) => {
+    stop()
+    setStatus('failed')
+    setFailure(errorMessage(error))
+    console.error(`[presmium.motion] the scene ${props.scene} failed`, error)
+  }
+  useEffect(() => {
+    const before = followedNavigation.current
+    followedNavigation.current = { source: navigation, position: navigated }
+    if (before.source !== navigation || before.position === navigated) return
+    if (!scope.localPreview || !expanded || !navigated || navigated.slide !== cursor.slide) return
+    const own = localNavigation.current
+    localNavigation.current = undefined
+    if (own?.slide === navigated.slide && own.step === navigated.step) return
+    const step = scope.localStepAt(navigated.step)
+    if (step >= 0 && step < durations.length) {
+      seekLocal(starts[step]! + (navigated.boundary === 'start' ? 0 : durations[step]!))
+      if (navigated.boundary !== 'start') previewReplay.current = step
+    }
+  }, [navigation, navigated, expanded, cursor.slide, scope.localPreview, scope.at, props.durations])
+  useEffect(() => {
+    if (!scope.localPreview || local === undefined || !navigation) return
+    const target = scope.step(selectedStep), current = navigation.position.getSnapshot()
+    if (target < 0 || (Number.isFinite(hostStep) && current.slide === cursor.slide && current.step === target)) return
+    // Use the existing local clock's discrete step boundary. Its own navigation
+    // updates semantic state without seeking or restarting that clock.
+    localNavigation.current = { slide: cursor.slide, step: target }
+    navigation.go(localNavigation.current)
+  }, [scope.localPreview, local !== undefined, selectedStep, navigation, cursor.slide, Number.isFinite(hostStep)])
+  useEffect(() => {
+    const generation = activePlayback.current
+    if (!playing || generation === undefined || generation !== playbackGeneration.current) return
+    const from =
+      localTime.current === undefined || localTime.current >= total
+        ? 0
+        : localTime.current
+    const began = performance.now() - from
+    const tick = () => {
+      if (activePlayback.current !== generation || playbackGeneration.current !== generation) return
+      const at = Math.min(total, performance.now() - began)
+      localTime.current = at
+      setLocal(at)
+      if (at < total) frame.current = requestAnimationFrame(tick)
+      else stop()
+    }
+    frame.current = requestAnimationFrame(tick)
+    return () => cancelAnimationFrame(frame.current)
+  }, [playing, total])
+  useLayoutEffect(() => {
+    try {
+      instance.current?.seek(shown)
+    } catch (error) {
+      fail(error)
+      const work = Promise.reject(error)
+      work.catch(() => {})
+      clock?.wait(work)
+    }
+  }, [shown, clock])
+  useEffect(() => {
+    if (seen) return
+    if (printed || !expanded || typeof IntersectionObserver === 'undefined') {
+      setSeen(true)
+      return
+    }
+    const root = stage.current
+    if (!root) return
+    // Observe the scene's stage against the viewport; after first visibility,
+    // retain the instance when reading past it so steps remain reversible.
+    const observer = new IntersectionObserver(
+      (entries) => {
+        if (!entries.some((entry) => entry.isIntersecting)) return
+        setSeen(true)
+        observer.disconnect()
+      },
+      { rootMargin: '200px' },
+    )
+    observer.observe(root)
+    return () => observer.disconnect()
+  }, [seen, printed, expanded])
+  useEffect(() => () => {
+    instance.current?.dispose?.()
+    instance.current = undefined
+  }, [])
+  useEffect(() => {
+    const root = stage.current
+    if (!enabled || !root) return
+    let disposed = false
+    let generation = 0
+    let observer: ResizeObserver | undefined
+    let resizeTimer: ReturnType<typeof setTimeout> | undefined
+    let dimensions = { width: root.clientWidth, height: root.clientHeight }
+    const build = async (version: number) => {
+      const current = () => !disposed && version === generation
+      const definition = await loadScene(props.scene)
+      if (!current()) return
+      if (!definition) {
+        setStatus('missing')
+        throw new Error(`the deck has no scene ${props.scene}`)
+      }
+      // A rebuild (another step's state, the theme, a resize) is made in a hidden layer while the
+      // shown scene keeps following the time; the two swap in one task. Disposed first, the shown
+      // scene would paint its authored DOM (a from() tween's end, later steps' elements) for frames.
+      const layer = root.appendChild(document.createElement('div'))
+      layer.className = 'pm-scene__layer'
+      layer.dataset.pending = ''
+      const box = { width: root.clientWidth, height: root.clientHeight }
+      dimensions = { width: box.width, height: box.height }
+      let swatch: CanvasRenderingContext2D | null | undefined
+      // A build that draws text on a canvas measures and paints it with the page's fonts, so they load first.
+      await document.fonts.ready
+      if (!current()) { layer.remove(); return }
+      const made = await definition.create({
+        root: layer,
+        parameters: sceneParameters,
+        state: sceneState,
+        durations,
+        at: (step) => starts[Math.max(0, Math.min(step, durations.length))]!,
+        total,
+        width: box.width || 640,
+        height: box.height || 360,
+        color(name) {
+          swatch ??= document
+            .createElement('canvas')
+            .getContext('2d', { willReadFrequently: true })
+          const css = getComputedStyle(root)
+            .getPropertyValue(`--pm-color-${name}`)
+            .trim()
+          if (!swatch || !css) return css
+          swatch.clearRect(0, 0, 1, 1)
+          swatch.fillStyle = css
+          swatch.fillRect(0, 0, 1, 1)
+          const [r, g, b, a] = swatch.getImageData(0, 0, 1, 1).data
+          return a === 255
+            ? `rgb(${r}, ${g}, ${b})`
+            : `rgba(${r}, ${g}, ${b}, ${Math.round((a! / 255) * 1000) / 1000})`
+        },
+      }).catch((error: unknown) => {
+        layer.remove()
+        if (current()) {
+          instance.current?.dispose?.()
+          instance.current = undefined
+          root.replaceChildren()
+        }
+        throw error
+      })
+      // The first frame shows the scene's pictures: the video export captures a step as soon as it is ready.
+      await Promise.all([...layer.querySelectorAll('img')].map((img) => img.decode().catch(() => undefined)))
+      if (!current()) {
+        try { made.dispose?.() }
+        finally { layer.remove() }
+        return
+      }
+      instance.current?.dispose?.()
+      for (const child of [...root.children]) if (child !== layer) child.remove()
+      delete layer.dataset.pending
+      instance.current = made
+      made.seek(shownNow.current)
+      setStatus('ready')
+    }
+    const rebuild = () => {
+      const version = ++generation
+      const work = build(version).catch((error: unknown) => {
+        if (!disposed && version === generation) throw error
+      })
+      work.catch((error) => {
+        if (!disposed && version === generation) fail(error)
+      })
+      clock?.wait(work)
+    }
+    preloadScenes()
+    rebuild()
+    observer = new ResizeObserver(([entry]) => {
+      const box = entry!.contentRect
+      if (!instance.current || !box.width || !box.height) return
+      if (instance.current.resize) {
+        instance.current.resize(box.width, box.height)
+        instance.current.seek(shownNow.current)
+        dimensions = { width: box.width, height: box.height }
+      } else if (
+        Math.abs(box.width - dimensions.width) > 1 ||
+        Math.abs(box.height - dimensions.height) > 1
+      ) {
+        clearTimeout(resizeTimer)
+        resizeTimer = setTimeout(rebuild, 150)
+      }
+    })
+    observer.observe(root)
+    return () => {
+      disposed = true
+      clearTimeout(resizeTimer)
+      observer?.disconnect()
+    }
+  }, [enabled, props.scene, JSON.stringify(durations), JSON.stringify(sceneParameters), sceneState, dark, clock])
+  const box: CSSProperties = props.height
+    ? { height: props.height }
+    : { aspectRatio: (props.aspect ?? '16/9').replace('/', ' / ') }
+  const notice =
+    status === 'loading'
+      ? t.loading
+      : status === 'missing'
+        ? t.missing(props.scene)
+        : status === 'failed'
+          ? t.failed(props.scene, failure)
+          : undefined
+  return (
+    <figure
+      className="pm-scene"
+      data-scene={props.scene}
+      data-status={status}
+      data-height={props.height ? '' : undefined}
+      data-presentation={viewRole !== 'reader' ? '' : undefined}
+      data-position={Math.round(shown)}
+    >
+      <div
+        className="pm-scene__frame"
+        style={box}
+        role="img"
+        aria-label={props.alt ?? props.scene}
+      >
+        <div ref={stage} className="pm-scene__stage" />
+        {notice && (
+          <p
+            className="pm-scene__notice"
+            role={status === 'loading' ? undefined : 'alert'}
+          >
+            {notice}
+          </p>
+        )}
+      </div>
+      {expanded && !printed && status === 'ready' && durations.length > 1 && (
+        <div
+          className="pm-scene__steps"
+          role="group"
+          aria-label={t.steps}
+          onKeyDown={(event) => event.stopPropagation()}
+        >
+          {durations.map((_, step) => (
+            <button
+              key={step}
+              type="button"
+              className="pm-scene__step"
+              aria-label={t.jump(step + 1)}
+              title={t.jump(step + 1)}
+              aria-pressed={selectedStep === step}
+              data-scene-jump={scope.step(step)}
+              disabled={scope.step(step) < 0}
+              onClick={() => jump(step)}
+            >
+              {step + 1}
+            </button>
+          ))}
+        </div>
+      )}
+      {expanded && status === 'ready' && total > 0 && (
+        <div
+          className="pm-scene__controls"
+          role="group"
+          onKeyDown={(event) => event.stopPropagation()}
+        >
+          <PmIconButton
+            small
+            icon={playing ? 'pause' : 'play'}
+            label={playing ? t.pause : t.play}
+            aria-pressed={playing}
+            onClick={() => {
+              if (playing) stop()
+              else {
+                const lease = playbackLease.current, generation = ++playbackGeneration.current
+                const start = () => {
+                  if (generation !== playbackGeneration.current || lease !== playbackLease.current) return
+                  const replay = previewReplay.current
+                  previewReplay.current = undefined
+                  if (scope.localPreview && replay !== undefined && replay < durations.length) {
+                    localTime.current = starts[replay]!
+                    setLocal(localTime.current)
+                    // The exact start is also the previous step's end. Keep
+                    // the selected step's identity while replaying its entry.
+                    localNavigation.current = { slide: cursor.slide, step: scope.step(replay) }
+                    navigation?.go({ ...localNavigation.current, boundary: 'start' })
+                  }
+                  activePlayback.current = generation
+                  setPlaying(true)
+                }
+                if (lease) void lease.requestStart().then(allowed => { if (allowed) start() }).catch(error => { if (generation === playbackGeneration.current) fail(error) })
+                else start()
+              }
+            }}
+          />
+          <input
+            type="range"
+            className="pm-scene__scrub"
+            min="0"
+            max={total}
+            step="1"
+            value={Math.round(shown)}
+            aria-label={t.scrub}
+            onChange={(event) => seekLocal(Number(event.target.value))}
+          />
+        </div>
+      )}
+    </figure>
+  )
+}

package/src/client/deck-scenes.ts

@@ -0,0 +1,27 @@
+import scenes from 'virtual:presmium-motion/scenes'
+import type { SceneDefinition } from './scene.ts'
+
+function isScene(value: unknown): value is SceneDefinition {
+  return typeof value === 'object' && value !== null && typeof (value as SceneDefinition).create === 'function'
+}
+
+let preloading = false
+
+/** Starts loading every scene of the deck while the page is idle, so a scene the presenter goes to is drawn at once. */
+export function preloadScenes(): void {
+  if (preloading || typeof window === 'undefined') return
+  preloading = true
+  const idle = window.requestIdleCallback ?? ((run: () => void) => setTimeout(run, 200))
+  idle(() => {
+    for (const load of Object.values(scenes)) void load().catch(() => undefined)
+  })
+}
+
+/** The scene `name` of the deck's `scenes/`; undefined when there is no such file. */
+export async function loadScene(name: string): Promise<SceneDefinition | undefined> {
+  const load = scenes[name]
+  if (!load) return undefined
+  const { default: scene } = await load()
+  if (!isScene(scene)) throw new Error(`scenes/${name} has no scene as its default export, e.g. export default gsapScene(...)`)
+  return scene
+}

package/src/client/env.d.ts

@@ -0,0 +1,4 @@
+declare module 'virtual:presmium-motion/scenes' {
+  const scenes: Record<string, () => Promise<{ default?: unknown }>>
+  export default scenes
+}

package/src/client/scene.css

@@ -0,0 +1,62 @@
+.pm-scene {
+  margin: 0 auto;
+  width: 100%;
+  max-width: var(--pm-scene-max-width);
+}
+.pm-scene[data-height],
+.pm-scene[data-presentation] {
+  max-width: none;
+}
+.pm-scene__frame {
+  position: relative;
+  width: 100%;
+  overflow: hidden;
+  border-radius: var(--pm-radius-control);
+}
+.pm-scene__stage {
+  position: absolute;
+  inset: 0;
+  /* A scene can size its layout to the picture with cqw and cqh. */
+  container-type: size;
+}
+.pm-scene__layer {
+  position: absolute;
+  inset: 0;
+  /* The scene's root, so its own cqw and cqh are the picture's, as the stage's are. */
+  container-type: size;
+}
+/* Laid out at the stage's size, so the scene being made can measure itself. */
+.pm-scene__layer[data-pending] {
+  visibility: hidden;
+}
+.pm-scene__notice {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  margin: 0;
+  padding: var(--pm-space-3);
+  color: var(--pm-color-muted);
+  font-family: var(--pm-font-sans);
+  font-size: var(--pm-text-sm);
+  text-align: center;
+}
+.pm-scene__controls {
+  display: flex;
+  align-items: center;
+  gap: var(--pm-space-2);
+  margin-top: var(--pm-space-2);
+}
+.pm-scene__scrub {
+  flex: 1;
+  accent-color: var(--pm-color-accent);
+}
+.pm-scene__steps { display: flex; gap: var(--pm-space-1); overflow-x: auto; padding-block: var(--pm-space-1); }
+.pm-scene__step { flex: none; min-width: var(--pm-size-tool); min-height: var(--pm-size-tool); padding: 0 var(--pm-space-1); border: 0; border-radius: var(--pm-radius-chip); background: transparent; color: var(--pm-color-muted); font-family: var(--pm-font-mono); font-size: var(--pm-text-xs); cursor: pointer; }
+.pm-scene__step[aria-pressed='true'], .pm-scene__step:hover, .pm-scene__step:focus-visible { background: var(--pm-color-accent-soft); color: var(--pm-color-accent); }
+html.pm-lecture-exporting .pm-scene__steps { display: none; }
+html.pm-lecture-exporting .pm-scene__frame { border-radius: 0; }
+@media (pointer: coarse) {
+  .pm-scene__step { min-width: var(--pm-control-hit-area); min-height: var(--pm-control-hit-area); }
+  .pm-scene__scrub { min-height: var(--pm-control-hit-area); }
+}