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

package/src/client/scene.ts

@@ -0,0 +1,317 @@
+import type * as AnimeModule from 'animejs'
+import type * as D3Module from 'd3'
+import type { gsap as Gsap } from 'gsap'
+import type * as MotionModule from 'motion'
+import type * as ReactModule from 'react'
+import type * as RemotionModule from 'remotion'
+import type * as ThreeModule from 'three'
+
+/** What a scene gets to draw itself. */
+export interface SceneContext {
+  /** Complete parameters and semantic state resolved for the authored Step ID. */
+  parameters: Readonly<Record<string, unknown>>
+  state?: string
+  /** The element the scene draws in; the scene owns its children. */
+  root: HTMLElement
+  /** The length of each step of the scene (ms), from `:durations:`. */
+  durations: readonly number[]
+  /** Where step `k` starts on the scene's timeline (ms). */
+  at(step: number): number
+  /** The length of the timeline (ms). */
+  total: number
+  /** The layout size of `root` in CSS pixels, before any ancestor's presentation scaling. */
+  width: number
+  height: number
+  /** A color of the design system as the page shows it now, as `rgb()` or `rgba()`: `color('accent')` is `--pm-color-accent`. */
+  color(name: string): string
+}
+
+/** A scene drawn at a place on its timeline. Its look is a function of that place only. */
+export interface Scene {
+  /** Shows the scene at `ms` on its timeline. */
+  seek(ms: number): void
+  /** `root` changed size (the scene is shown again at its place afterwards). */
+  resize?(width: number, height: number): void
+  dispose?(): void
+}
+
+export interface SceneDefinition {
+  engine: string
+  create(ctx: SceneContext): Promise<Scene>
+}
+
+type Made = Scene | ((ms: number) => void)
+
+function scene(made: Made): Scene {
+  return typeof made === 'function' ? { seek: made } : made
+}
+
+/** A scene of its own code: `create` draws in `ctx.root` and returns the function of the time (or a `Scene`). */
+export function defineScene(create: (ctx: SceneContext) => Made | Promise<Made>): SceneDefinition {
+  return { engine: 'custom', create: async ctx => scene(await create(ctx)) }
+}
+
+type GsapAnimation = ReturnType<typeof Gsap.timeline> | ReturnType<typeof Gsap.to>
+
+/** GSAP's plugins that draw the same at the same time; ScrambleText (random each render) and the scroll and drag ones are left out. */
+async function gsapPlugins(gsap: typeof Gsap) {
+  // Each plugin registers itself with `window.gsap` when it loads. GSAP sets that global only when nothing holds the
+  // name, and an element with the id `gsap` (a section labelled `(gsap)=`) does, so the plugins would find the element.
+  const page = window as unknown as { gsap?: unknown }
+  if (page.gsap !== gsap) page.gsap = gsap
+  const [{ SplitText }, { TextPlugin }, { DrawSVGPlugin }, { MorphSVGPlugin }, { MotionPathPlugin }, { CustomEase }, { CustomBounce }, { CustomWiggle }, { Physics2DPlugin }, { PhysicsPropsPlugin }, { Flip }] = await Promise.all([
+    import('gsap/SplitText'),
+    import('gsap/TextPlugin'),
+    import('gsap/DrawSVGPlugin'),
+    import('gsap/MorphSVGPlugin'),
+    import('gsap/MotionPathPlugin'),
+    import('gsap/CustomEase'),
+    import('gsap/CustomBounce'),
+    import('gsap/CustomWiggle'),
+    import('gsap/Physics2DPlugin'),
+    import('gsap/PhysicsPropsPlugin'),
+    import('gsap/Flip'),
+  ])
+  return { SplitText, TextPlugin, DrawSVGPlugin, MorphSVGPlugin, MotionPathPlugin, CustomEase, CustomBounce, CustomWiggle, Physics2DPlugin, PhysicsPropsPlugin, Flip }
+}
+
+export type GsapPlugins = Awaited<ReturnType<typeof gsapPlugins>>
+
+/**
+ * A GSAP timeline (or tween), built in a `gsap.context` scoped to `ctx.root`, so selectors find the
+ * scene's elements and disposing reverts them. Times are seconds, as in GSAP: `ctx.at(k) / 1000`.
+ * `plugins` are registered before `build`: tweens can use `drawSVG`, `morphSVG`, `motionPath`, `text`,
+ * `physics2D`, `physicsProps`, and the scene can call `plugins.SplitText.create`, `plugins.CustomEase.create`.
+ */
+export function gsapScene(build: (ctx: SceneContext & { gsap: typeof Gsap, plugins: GsapPlugins }) => GsapAnimation): SceneDefinition {
+  return {
+    engine: 'gsap',
+    async create(ctx) {
+      const { gsap } = await import('gsap')
+      const plugins = await gsapPlugins(gsap)
+      // A tweened box on its own 3D layer is drawn a little differently from the same box at rest, so a frame would
+      // depend on how it was reached; scenes keep 2D transforms.
+      gsap.config({ force3D: false })
+      gsap.registerPlugin(...Object.values(plugins))
+      let animation: GsapAnimation | undefined
+      const context = gsap.context(() => {}, ctx.root)
+      try {
+        context.add(() => {
+          animation = build({ ...ctx, gsap, plugins })
+        })
+        animation?.pause()
+        return {
+          seek: ms => animation?.totalTime(ms / 1000, true),
+          dispose: () => context.revert(),
+        }
+      } catch (error) {
+        context.revert()
+        throw error
+      }
+    },
+  }
+}
+
+type AnimeAnimation = ReturnType<typeof AnimeModule.createTimeline> | ReturnType<typeof AnimeModule.animate>
+
+/** An Anime.js timeline (or animation), made in a scope rooted at `ctx.root`. Times are milliseconds. */
+export function animeScene(build: (ctx: SceneContext & { anime: typeof AnimeModule }) => AnimeAnimation): SceneDefinition {
+  return {
+    engine: 'anime',
+    async create(ctx) {
+      const anime = await import('animejs')
+      const scope = anime.createScope({ root: ctx.root })
+      const animation = scope.execute(() => build({ ...ctx, anime }))
+      animation.pause()
+      // Until a tween has been reached once it shows the element's own value, not its from-value: going to the end and
+      // back sets them all up, so a time looks the same whatever was shown before it.
+      animation.seek(animation.duration, true)
+      animation.seek(0, true)
+      return {
+        // From the start each time: going back past a later tween that gives its own from-value does not restore
+        // the value before it, so a time is reached the same way whichever time was shown before.
+        seek(ms) {
+          animation.seek(0, true)
+          animation.seek(ms, true)
+        },
+        dispose: () => scope.revert(),
+      }
+    },
+  }
+}
+
+type MotionControls = ReturnType<typeof MotionModule.animate>
+
+/** A Motion sequence, to type the segments a scene builds. */
+export type MotionSequence = MotionModule.AnimationSequence
+
+/** Motion animations (`animate`, a sequence, or several); Motion counts seconds, so the scene sets `time` to `ms / 1000`. */
+export function motionScene(build: (ctx: SceneContext & { motion: typeof MotionModule }) => MotionControls | MotionControls[]): SceneDefinition {
+  return {
+    engine: 'motion',
+    async create(ctx) {
+      const motion = await import('motion')
+      const controls = [build({ ...ctx, motion })].flat()
+      for (const control of controls) control.pause()
+      return {
+        seek(ms) {
+          for (const control of controls) control.time = ms / 1000
+          // Only what the browser animates (opacity, background color, filter, clip-path) shows at once; transforms,
+          // SVG, CSS variables and function segments wait for Motion's next frame, so it is drawn now.
+          for (const step of ['update', 'preRender', 'render'] as const) motion.frameSteps[step].process(motion.frameData)
+        },
+        dispose() {
+          for (const control of controls) control.cancel()
+        },
+      }
+    },
+  }
+}
+
+export interface ThreeView {
+  /** Draws the scene at `ms` on the timeline (`renderer.render(scene, camera)`). */
+  render(ms: number): void
+  resize?(width: number, height: number): void
+  dispose?(): void
+}
+
+/** The three.js addons a scene can use: HTML labels, lines wider than a pixel, and geometries the core lacks. */
+async function threeAddons() {
+  const [{ CSS2DRenderer, CSS2DObject }, { Line2 }, { LineGeometry }, { LineMaterial }, { ParametricGeometry }, { RoundedBoxGeometry }, { ConvexGeometry }] = await Promise.all([
+    import('three/addons/renderers/CSS2DRenderer.js'),
+    import('three/addons/lines/Line2.js'),
+    import('three/addons/lines/LineGeometry.js'),
+    import('three/addons/lines/LineMaterial.js'),
+    import('three/addons/geometries/ParametricGeometry.js'),
+    import('three/addons/geometries/RoundedBoxGeometry.js'),
+    import('three/addons/geometries/ConvexGeometry.js'),
+  ])
+  return { CSS2DRenderer, CSS2DObject, Line2, LineGeometry, LineMaterial, ParametricGeometry, RoundedBoxGeometry, ConvexGeometry }
+}
+
+export type ThreeAddons = Awaited<ReturnType<typeof threeAddons>>
+
+/**
+ * A Three.js scene: the adapter keeps logical dimensions for the scene and a drawing buffer matched
+ * to `root`'s displayed pixels, including presentation scaling; `build` returns (or resolves to) how to draw it at a time.
+ */
+export function threeScene(build: (ctx: SceneContext & { THREE: typeof ThreeModule, renderer: ThreeModule.WebGLRenderer, addons: ThreeAddons }) => ThreeView | ThreeView['render'] | Promise<ThreeView | ThreeView['render']>): SceneDefinition {
+  return {
+    engine: 'three',
+    async create(ctx) {
+      const [THREE, addons] = await Promise.all([import('three'), threeAddons()])
+      // The drawing buffer is kept so a screenshot of a frame (the lecture's video) shows it.
+      const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true, preserveDrawingBuffer: true })
+      Object.assign(renderer.domElement.style, { width: '100%', height: '100%', display: 'block' })
+      ctx.root.append(renderer.domElement)
+      let width = ctx.width, height = ctx.height
+      let bufferWidth = 0, bufferHeight = 0, sizedWidth = 0, sizedHeight = 0
+      const gl = renderer.getContext()
+      const maxSize = Math.min(renderer.capabilities.maxTextureSize, Number(gl.getParameter(gl.MAX_RENDERBUFFER_SIZE)))
+      const syncBuffer = () => {
+        const box = ctx.root.getBoundingClientRect()
+        const dpr = window.devicePixelRatio || 1
+        // Hidden or newly mounted roots can have no height yet. The next seek measures them again.
+        const scale = box.width > 0 && box.height > 0 ? Math.max(box.width / width, box.height / height) : 1
+        // Scale down for a smaller presentation too; only the GPU's size limit caps magnification.
+        const ratio = Math.max(1 / Math.min(width, height), Math.min(dpr * scale, maxSize / width, maxSize / height))
+        const nextWidth = Math.floor(width * ratio), nextHeight = Math.floor(height * ratio)
+        if (nextWidth === bufferWidth && nextHeight === bufferHeight && width === sizedWidth && height === sizedHeight) return false
+        renderer.setDrawingBufferSize(width, height, ratio)
+        bufferWidth = nextWidth; bufferHeight = nextHeight
+        sizedWidth = width; sizedHeight = height
+        return true
+      }
+      syncBuffer()
+      // An async build can load its textures (`new THREE.TextureLoader().loadAsync(url)`) before the first frame.
+      const made = await build({ ...ctx, THREE, renderer, addons })
+      const view: ThreeView = typeof made === 'function' ? { render: made } : made
+      return {
+        seek(ms) {
+          // Ancestor transforms change displayed pixels without triggering a layout ResizeObserver.
+          if (syncBuffer()) view.resize?.(width, height)
+          view.render(ms)
+        },
+        resize(w, h) {
+          if (!(w > 0 && h > 0)) return
+          width = w; height = h
+          syncBuffer()
+          view.resize?.(width, height)
+        },
+        dispose() {
+          view.dispose?.()
+          renderer.dispose()
+          renderer.forceContextLoss()
+          renderer.domElement.remove()
+        },
+      }
+    },
+  }
+}
+
+/**
+ * A D3 scene: D3 turns the data into shapes (scales, axes, layouts, shape generators), and the scene draws them at
+ * a time with D3's interpolators and eases. `build` returns the drawing function `(ms) => void` (or a `Scene`);
+ * transitions run on D3's own timer, so they have no place here.
+ */
+export function d3Scene(build: (ctx: SceneContext & { d3: typeof D3Module }) => Made | Promise<Made>): SceneDefinition {
+  return {
+    engine: 'd3',
+    async create(ctx) {
+      const d3 = await import('d3')
+      return scene(await build({ ...ctx, d3 }))
+    },
+  }
+}
+
+export interface RemotionComposition {
+  component: ReactModule.ComponentType<Record<string, unknown>>
+  fps: number
+  width: number
+  height: number
+  /** Default: the scene's timeline at `fps`. */
+  durationInFrames?: number
+  inputProps?: Record<string, unknown>
+}
+
+/**
+ * A Remotion composition, drawn frame by frame with the player's `Thumbnail`: the scene's place on
+ * its timeline picks the frame. `build` gets React and Remotion to write the component with
+ * `React.createElement`.
+ */
+export function remotionScene(build: (ctx: SceneContext & { React: typeof ReactModule, remotion: typeof RemotionModule }) => RemotionComposition | Promise<RemotionComposition>): SceneDefinition {
+  return {
+    engine: 'remotion',
+    async create(ctx) {
+      const [React, { flushSync }, { createRoot }, remotion, { Thumbnail }] = await Promise.all([
+        import('react'),
+        import('react-dom'),
+        import('react-dom/client'),
+        import('remotion'),
+        import('@remotion/player'),
+      ])
+      const composition = await build({ ...ctx, React, remotion })
+      const frames = composition.durationInFrames ?? Math.max(1, Math.ceil(ctx.total * composition.fps / 1000))
+      const root = createRoot(ctx.root)
+      return {
+        seek(ms) {
+          // Half a millisecond of slack: the lecture export asks for whole milliseconds (frame 1 at 30 fps is
+          // 33 ms, not 33.3), which would otherwise show the frame before, every third frame.
+          const frame = Math.min(frames - 1, Math.max(0, Math.floor((ms + 0.5) * composition.fps / 1000)))
+          flushSync(() => root.render(React.createElement(Thumbnail, {
+            component: composition.component,
+            compositionWidth: composition.width,
+            compositionHeight: composition.height,
+            durationInFrames: frames,
+            fps: composition.fps,
+            frameToDisplay: frame,
+            inputProps: composition.inputProps ?? {},
+            noSuspense: true,
+            style: { width: '100%', height: '100%' },
+          })))
+        },
+        dispose: () => root.unmount(),
+      }
+    },
+  }
+}

package/src/domain/index.ts

@@ -0,0 +1,32 @@
+export const MOTION_ID = 'presmium.motion'
+
+/** The directory of a deck's scenes, as `components/` holds its components. */
+export const SCENES_DIR = 'scenes'
+
+// Not .tsx nor .jsx: the file does not tell which runtime its JSX is for (React's, Vue's).
+export const SCENE_EXTENSIONS = ['.ts', '.js', '.mjs'] as const
+
+/** The scene names a deck can use: the path under `scenes/` without its extension, `/` between folders. */
+export const SCENE_NAME = /^[\w-]+(?:\/[\w-]+)*$/
+
+/** Where each step starts on a scene's timeline (ms), and its end. */
+export function stepStarts(durations: readonly number[]): number[] {
+  const starts = [0]
+  for (const ms of durations) starts.push(starts.at(-1)! + ms)
+  return starts
+}
+
+/**
+ * The scene's place on its timeline (ms) at block step `step` (from 0), `time` ms into it: step k
+ * plays the k-th part of the timeline, `durations[k]` long. Before the block's first step the scene
+ * is at its start; after the last, at its end; `time` is `Infinity` when the step is settled.
+ */
+export function timelinePosition(durations: readonly number[], step: number, time: number): number {
+  const starts = stepStarts(durations)
+  if (step < 0) return 0
+  if (step >= durations.length) return starts.at(-1)!
+  return starts[step]! + Math.min(Math.max(0, time), durations[step]!)
+}
+
+export { MOTION_MESSAGES } from './messages.ts'
+export type { MotionMessages } from './messages.ts'

package/src/domain/messages.ts

@@ -0,0 +1,35 @@
+import type { Locale } from '@lincyaw/kernel/contracts'
+
+export interface MotionMessages {
+  steps: string
+  jump(step: number): string
+  loading: string
+  missing(scene: string): string
+  failed(scene: string, reason: string): string
+  play: string
+  pause: string
+  scrub: string
+}
+
+export const MOTION_MESSAGES: Record<Locale, MotionMessages> = {
+  'zh-CN': {
+    steps: '动画步骤',
+    jump: step => `跳到动画第 ${step} 步`,
+    loading: '正在加载动画…',
+    missing: scene => `文稿的 scenes/ 中没有动画 ${scene}`,
+    failed: (scene, reason) => `无法播放动画 ${scene}：${reason}`,
+    play: '播放动画',
+    pause: '暂停动画',
+    scrub: '动画进度',
+  },
+  en: {
+    steps: 'Animation steps',
+    jump: step => `Jump to Animation Step ${step}`,
+    loading: 'Loading the animation…',
+    missing: scene => `The document’s scenes/ has no animation ${scene}`,
+    failed: (scene, reason) => `Couldn’t play the animation ${scene}: ${reason}`,
+    play: 'Play Animation',
+    pause: 'Pause Animation',
+    scrub: 'Animation progress',
+  },
+}

package/src/node/presmium.ts

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join, relative, resolve, sep } from 'node:path'
+import { parseDuration } from '@lincyaw/kernel'
+import type { ComponentNode, DirectiveSpec, MdastNode, PresmiumNodePlugin } from '@lincyaw/kernel'
+import { MOTION_ID, SCENE_EXTENSIONS, SCENE_NAME, SCENES_DIR } from '../domain/index.ts'
+import { deckScenes, sceneFile, SCENES_MODULE, scenesModule } from './scenes.ts'
+
+const { version } = createRequire(import.meta.url)('../../package.json') as { version: string }
+
+const posix = (path: string) => path.split(sep).join('/')
+
+const ASPECT = /^\d+(?:\.\d+)?\s*[/:]\s*\d+(?:\.\d+)?$/
+const STARTER = readFileSync(new URL('./scene-starter.txt', import.meta.url), 'utf8')
+
+const scene: DirectiveSpec = {
+  name: 'scene',
+  arg: true,
+  body: true,
+  options: { durations: 'list', aspect: 'string', height: 'string', still: 'string' },
+  toIR(input, ctx) {
+    const report = (message: string, severity: 'error' | 'warning' = 'error') => ctx.report({ checkId: MOTION_ID, severity, message: `{scene}: ${message}` })
+    const name = input.arg?.trim() ?? ''
+    if (!name) report(`needs the name of a scene of the deck's ${SCENES_DIR}/, e.g. {scene} merge for ${SCENES_DIR}/merge.ts`)
+    else if (!SCENE_NAME.test(name)) report(`"${name}" is not a scene name: the path under ${SCENES_DIR}/ without its extension, e.g. merge or bpe/merge`)
+    else {
+      // Every file the scene could be, so that adding it (or another extension of it) compiles the deck again.
+      ctx.watch(...SCENE_EXTENSIONS.map(ext => join(ctx.deckDir, SCENES_DIR, `${name}${ext}`)))
+      if (!sceneFile(ctx.deckDir, name)) report(`the deck has no ${SCENES_DIR}/${name}.ts (nor .js, .mjs)`)
+    }
+    const listed = Array.isArray(input.options.durations) ? input.options.durations as string[] : []
+    const durations = listed.map(parseDuration)
+    const bad = listed.filter((_, i) => durations[i] === undefined)
+    if (bad.length) report(`:durations: takes durations as {cue}\`pause\` does (1.2, 1.2s or 800ms), not ${bad.join(', ')}`)
+    const steps = durations.filter((ms): ms is number => ms !== undefined)
+    if (steps.length === 0) steps.push(0)
+    const aspect = typeof input.options.aspect === 'string' ? input.options.aspect.trim() : undefined
+    if (aspect && !ASPECT.test(aspect)) report(`:aspect: takes width/height, e.g. 16/9, not ${aspect}`)
+    const height = typeof input.options.height === 'string' ? input.options.height.trim() : undefined
+    const caption = input.body.trim()
+    const parsed = caption ? ctx.parse(caption) : undefined
+    const fallback: MdastNode = { type: 'root', children: [...(parsed?.children as MdastNode[] | undefined) ?? []] }
+    // The durations go in the node only: the renderers give them to the component as the prop durations.
+    const props: Record<string, unknown> = { scene: name }
+    if (aspect && ASPECT.test(aspect)) props.aspect = aspect.replace(':', '/').replace(/\s+/g, '')
+    if (height) props.height = height
+    if (caption) props.alt = caption.replace(/\s+/g, ' ')
+    const node: ComponentNode = { type: 'component', plugin: MOTION_ID, name: 'PmScene', props, durations: steps, fallback }
+    const definition = SCENE_NAME.test(name) ? sceneFile(ctx.deckDir, name) : undefined
+    if (definition) node.definition = { file: definition, language: definition.endsWith('.ts') ? 'typescript' : 'javascript' }
+    const still = typeof input.options.still === 'string' ? input.options.still.trim() : undefined
+    if (still) {
+      const file = resolve(dirname(ctx.file), still)
+      ctx.watch(file)
+      if (!existsSync(file)) report(`:still: file not found: ${still}`)
+      const url = posix(relative(dirname(ctx.file), file))
+      props.still = url
+      node.assets = { still: url }
+      fallback.children!.unshift({ type: 'paragraph', children: [{ type: 'image', url, alt: caption || name }] })
+    }
+    return { node, span: steps.length - 1 }
+  },
+}
+
+const plugin: PresmiumNodePlugin = {
+  id: MOTION_ID,
+  version,
+  kernel: '^1.0.0',
+  directives: [scene],
+  passes: [{
+    name: 'presmium.motion.catalog',
+    after: 'execute',
+    run(doc, ctx) {
+      const scenes = deckScenes(ctx.deckDir)
+      ctx.watch(join(ctx.deckDir, SCENES_DIR), ...scenes.values())
+      const own = doc.config.presmium[MOTION_ID]
+      doc.config.presmium[MOTION_ID] = { ...(typeof own === 'object' && own !== null ? own : {}), scenes: [...scenes.keys()], starter: { language: 'typescript', code: STARTER } }
+    },
+  }],
+  documentModules: ({ deckDir }) => ({ [SCENES_MODULE]: scenesModule(deckDir) }),
+}
+
+export default plugin

package/src/node/scene-starter.txt

@@ -0,0 +1,6 @@
+import { gsapScene } from '@lincyaw/addon-motion/scene'
+
+export default gsapScene(({ root, gsap }) => {
+  root.innerHTML = '<div style="width:var(--pm-space-12);height:var(--pm-space-12);background:var(--pm-color-accent)"></div>'
+  return gsap.timeline().fromTo(root.firstElementChild!, { xPercent: 0 }, { xPercent: 200, duration: 1 })
+})

package/src/node/scenes.ts

@@ -0,0 +1,40 @@
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { join, relative, sep } from 'node:path'
+import { SCENE_EXTENSIONS, SCENE_NAME, SCENES_DIR } from '../domain/index.ts'
+
+export const SCENES_MODULE = 'virtual:presmium-motion/scenes'
+
+/** The file of scene `name` in the deck (`scenes/<name>.ts` and the other extensions), if there is one. */
+export function sceneFile(deckDir: string, name: string): string | undefined {
+  if (!SCENE_NAME.test(name)) return undefined
+  return SCENE_EXTENSIONS.map(ext => join(deckDir, SCENES_DIR, `${name}${ext}`)).find(file => existsSync(file))
+}
+
+/** The deck's scenes by name: the files under `scenes/`, the first extension of SCENE_EXTENSIONS winning. */
+export function deckScenes(deckDir: string): Map<string, string> {
+  const root = join(deckDir, SCENES_DIR)
+  const scenes = new Map<string, string>()
+  const walk = (dir: string) => {
+    for (const entry of readdirSync(dir).sort()) {
+      const path = join(dir, entry)
+      if (statSync(path).isDirectory()) {
+        walk(path)
+        continue
+      }
+      const ext = SCENE_EXTENSIONS.find(e => entry.endsWith(e))
+      if (!ext) continue
+      const name = relative(root, path).slice(0, -ext.length).split(sep).join('/')
+      const known = scenes.get(name)
+      if (SCENE_NAME.test(name) && (!known || SCENE_EXTENSIONS.indexOf(ext) < SCENE_EXTENSIONS.findIndex(e => known.endsWith(e)))) scenes.set(name, path)
+    }
+  }
+  if (existsSync(root) && statSync(root).isDirectory()) walk(root)
+  return scenes
+}
+
+/** The source of `virtual:presmium-motion/scenes`: each scene of the deck, by name, to an import of its file. */
+export function scenesModule(deckDir: string): string {
+  const entries = [...deckScenes(deckDir)].map(([name, file]) => `  ${JSON.stringify(name)}: () => import(${JSON.stringify(file)}),`)
+  return `export default {\n${entries.join('\n')}\n}\n`
+}
+