@volter/editor-ui 0.5.210 → 0.5.212

package/src/react/composition-movie.ts

@@ -0,0 +1,247 @@
+/**
+ * A REACT COMPOSITION, RENDERED FRAME BY FRAME into `@volter/editor-movie`'s encoder: the story
+ * document's Render and `cyclotron render-movie --composition <story>` (the verb
+ * `story-render-movie`; docs/adr/movie-sound-and-react-frames.md, decision 3). A story is a
+ * composition when it reads `useMovieFrame()`; its `parameters.volter.movie` gives its length
+ * (`{ fps, frames }`) and, optionally, its size.
+ *
+ * - AN ISOLATED EVALUATION (DOCUMENT-VIEW-OWNERSHIP.md's Captures). The render has a mount of its
+ *   own, off-screen in the editor's document (so the project's scoped CSS styles it as it styles the
+ *   board), holding only the composition. The board's card and every other document are untouched,
+ *   and only the mount's own animations are read (`getAnimations({ subtree: true })`).
+ * - A FIXED REVISION. The composed story the registry holds at the start is the one rendered; when
+ *   the registry's story changes during the render (its module or a fixture was edited), the render
+ *   is refused by name and nothing is written.
+ * - EACH FRAME, IN THIS ORDER: React commits the frame (the SDK's isolated story mount commits
+ *   synchronously), so an element mounted, replaced or restyled at this frame exists; style is
+ *   recalculated, so the CSS animations and transitions that commit started exist; every animation
+ *   in the mount is paused and seeked to its own time, `1000 * (frame - f0) / fps` where `f0` is the
+ *   frame it was first found at; then the frame is drawn by the editor's capture
+ *   (`documents.drawElement`).
+ * - THE DRAWN COPY FREEZES MOTION, so before each draw the seeked value of every animated property
+ *   is written inline, `!important`, on its element, and removed after. An animated pseudo-element
+ *   cannot be written inline and draws un-animated.
+ * - TEARDOWN on end or failure: the root unmounted, the mount removed, the encoder closed.
+ */
+import { createElement } from 'react';
+import { beginMovie, type Movie } from '@volter/editor-movie';
+import { MovieFrameContext, type HeldMovieFrame } from '@volter/editor-movie/clock';
+import { getCurrentProject } from '@volter/sdk/active-project';
+import { commandJobs } from '@volter/sdk/commands';
+import { editorHost } from '@volter/sdk/host';
+import { mountIsolatedStory } from '@volter/sdk/stories/StoryPreviewMount';
+import type { ProjectPreviewStory } from '@volter/sdk/stories/story-types';
+
+/** What a render is asked for. `story` is the Storybook id, or an export name only one story has. */
+interface CompositionRenderRequest {
+  readonly story: string;
+  /** The project file the movie is written to; `movies/<story id>.webm` by default. */
+  readonly out?: string | undefined;
+  /** The first and last composition frames rendered; all of them by default. */
+  readonly from?: number | undefined;
+  readonly to?: number | undefined;
+  /** The movie's width; its height keeps the composition's aspect. */
+  readonly width?: number | undefined;
+}
+
+/** A composition's length and size, from its story's `parameters.volter.movie`. */
+interface CompositionMovie {
+  readonly fps: number;
+  readonly frames: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/** A render: where it stands, and once done the project file it wrote. */
+interface CompositionRender {
+  readonly story: string;
+  readonly out: string;
+  readonly frame: number;
+  readonly frames: number;
+  readonly state: 'rendering' | 'done' | 'failed';
+  readonly error?: string;
+  readonly bytes?: number;
+  readonly codec?: string;
+}
+
+/** The renders, by story id: what the story document's Render shows and the status verb answers. */
+export const compositionRenders = commandJobs<CompositionRender>();
+
+/** The story a request names, refused by name when none or several match. */
+async function compositionStory(name: string): Promise<ProjectPreviewStory> {
+  const stories = editorHost().stories;
+  await stories.whenReady();
+  const all = stories.previewStories();
+  const byId = all.find((story) => story.id === name);
+  if (byId) return byId;
+  const byExport = all.filter((story) => story.name === name);
+  if (byExport.length === 1) return byExport[0]!;
+  if (byExport.length > 1)
+    throw new Error(`Several stories are "${name}": ${byExport.map((story) => story.id).join(', ')}. Name one by its id.`);
+  throw new Error(`No story is "${name}". The project's stories: ${all.map((story) => story.id).join(', ') || 'none'}.`);
+}
+
+/** A story's `parameters.volter.movie`, or `undefined` when it declares none. */
+function movieParameters(story: { readonly parameters: Record<string, unknown> }): Record<string, unknown> | undefined {
+  const volter = story.parameters['volter'];
+  const movie = typeof volter === 'object' && volter !== null ? (volter as Record<string, unknown>)['movie'] : undefined;
+  return typeof movie === 'object' && movie !== null ? (movie as Record<string, unknown>) : undefined;
+}
+
+/** Whether a story declares a movie, so its document offers Render. */
+export const declaresMovie = (story: { readonly parameters: Record<string, unknown> }): boolean => movieParameters(story) !== undefined;
+
+/** The story's movie, with the project's resolution as its size when it gives none. */
+function compositionMovie(story: ProjectPreviewStory): CompositionMovie {
+  const movie = movieParameters(story) ?? {};
+  const positive = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value) && value > 0;
+  const { fps, frames } = movie;
+  if (!positive(fps) || !positive(frames) || !Number.isInteger(frames))
+    throw new Error(`The story ${story.id} (${story.modulePath}) declares no movie: a composition's story gives parameters.volter.movie = { fps, frames }.`);
+  const resolution = getCurrentProject()?.config.resolution;
+  const width = positive(movie['width']) ? movie['width'] : resolution?.width ?? 1280;
+  const height = positive(movie['height']) ? movie['height'] : resolution?.height ?? 720;
+  return { fps, frames, width, height };
+}
+
+const kebab = (property: string): string =>
+  property.startsWith('--') ? property : property.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+
+/** The CSS properties an animation sets on its element. */
+function animatedProperties(animation: Animation): string[] {
+  if (animation instanceof CSSTransition) return [animation.transitionProperty];
+  const effect = animation.effect;
+  if (!(effect instanceof KeyframeEffect)) return [];
+  const properties = new Set<string>();
+  for (const keyframe of effect.getKeyframes())
+    for (const key of Object.keys(keyframe))
+      if (!['offset', 'computedOffset', 'easing', 'composite'].includes(key)) properties.add(kebab(key));
+  return [...properties];
+}
+
+/** Each animated element's seeked values written inline, `!important`, and the undo. */
+function holdAnimatedValues(animations: readonly Animation[]): () => void {
+  const undo: (() => void)[] = [];
+  for (const animation of animations) {
+    const effect = animation.effect;
+    if (!(effect instanceof KeyframeEffect) || effect.pseudoElement || !(effect.target instanceof HTMLElement || effect.target instanceof SVGElement)) continue;
+    const element = effect.target;
+    const computed = getComputedStyle(element);
+    for (const property of animatedProperties(animation)) {
+      const value = computed.getPropertyValue(property);
+      const before = { value: element.style.getPropertyValue(property), priority: element.style.getPropertyPriority(property) };
+      element.style.setProperty(property, value, 'important');
+      undo.push(() => element.style.setProperty(property, before.value, before.priority));
+    }
+  }
+  return () => { for (const step of undo.reverse()) step(); };
+}
+
+/** Render `story` frames `from`..`to` into a WebM, which `@volter/editor-movie` has played before handing it back. */
+async function renderFrames(
+  story: ProjectPreviewStory,
+  request: CompositionRenderRequest,
+  progress: (frame: number, frames: number) => void,
+): Promise<{ readonly bytes: Uint8Array; readonly frames: number; readonly codec: string }> {
+  const composition = compositionMovie(story);
+  const from = request.from ?? 0;
+  const to = request.to ?? composition.frames - 1;
+  if (!Number.isInteger(from) || !Number.isInteger(to) || from < 0 || to >= composition.frames || to < from)
+    throw new Error(`Frames ${from}-${to} are not within the composition's 0-${composition.frames - 1}.`);
+  const scale = request.width ? request.width / composition.width : 1;
+  const size = { width: Math.round(composition.width * scale), height: Math.round(composition.height * scale) };
+  const host = editorHost();
+
+  // THE REVISION, bound at the start. A refresh a source write starts keeps every module the write did not touch, so
+  // only this story's own module or fixtures changing gives it a new composed component.
+  const bound = story.Component;
+  let revised: string | null = null;
+  const stopWatching = host.stories.subscribe(() => {
+    if (!host.stories.ready()) return;
+    const now = host.stories.previewStories().find((one) => one.id === story.id);
+    if (now?.Component !== bound) revised = `The composition ${story.id} changed while it rendered (${story.modulePath}); nothing was written. Render it again.`;
+  });
+
+  // The mount, off-screen: the drawn copy is the container alone, so where it sits does not show.
+  const shelf = document.createElement('div');
+  shelf.setAttribute('aria-hidden', 'true');
+  Object.assign(shelf.style, { position: 'fixed', left: '-100000px', top: '0', pointerEvents: 'none' });
+  const container = document.createElement('div');
+  Object.assign(container.style, { position: 'relative', width: `${composition.width}px`, height: `${composition.height}px`, overflow: 'hidden' });
+  shelf.appendChild(container);
+  let movie: Movie | null = null;
+  let unmount = () => {};
+  try {
+    document.body.appendChild(shelf);
+    await document.fonts.ready;
+    let held: HeldMovieFrame | null = null;
+    let read = false;
+    let loaded: Promise<unknown> | null = null;
+    // The story under the movie's clock; its loaders run once, for the first frame.
+    const Frame = Object.assign(
+      (props: Record<string, unknown>) => createElement(MovieFrameContext, { value: held }, createElement(story.Component, props)),
+      story.Component,
+      { load: () => (loaded ??= story.Component.load()) },
+    );
+    movie = await beginMovie({ ...size, fps: composition.fps });
+    const output = document.createElement('canvas');
+    const firstSeen = new Map<Animation, number>();
+    const projectRoot = host.projectLocalState.projectRootPath() ?? undefined;
+
+    for (let at = from; at <= to; at++) {
+      if (revised) throw new Error(revised);
+      held = {
+        value: { frame: at, fps: composition.fps, time: (1000 * at) / composition.fps },
+        read: () => { read = true; },
+      };
+      // 1. React commits this frame
+      const mounted = await mountIsolatedStory(container, story.modulePath, story.name, Frame);
+      if (!mounted) throw new Error(`The composition ${story.id} did not mount at frame ${at}.`);
+      unmount = mounted.unmount;
+      if (!read) throw new Error(`The story ${story.id} never reads useMovieFrame(), so it is not a composition.`);
+      // 2. style recalculated, so the animations that commit started exist
+      getComputedStyle(container).getPropertyValue('opacity');
+      // 3. the mount's own animations, each at its own time
+      const animations = container.getAnimations({ subtree: true });
+      for (const animation of animations) {
+        if (!firstSeen.has(animation)) firstSeen.set(animation, at);
+        animation.pause();
+        animation.currentTime = (1000 * (at - firstSeen.get(animation)!)) / composition.fps;
+      }
+      // 4. drawn
+      const release = holdAnimatedValues(animations);
+      try {
+        await host.documents.drawElement(container, output, { size, projectRoot });
+      } finally {
+        release();
+      }
+      await movie.frame(output);
+      progress(at - from + 1, to - from + 1);
+    }
+    if (revised) throw new Error(revised);
+    const ending = movie;
+    movie = null;
+    const bytes = await ending.end();
+    return { bytes, frames: ending.frames, codec: ending.codec };
+  } finally {
+    stopWatching();
+    movie?.cancel();
+    unmount();
+    shelf.remove();
+  }
+}
+
+/** Start rendering the composition a request names into its project file, answering at once. One story renders once
+ *  at a time. */
+export async function startCompositionRender(request: CompositionRenderRequest): Promise<CompositionRender> {
+  const story = await compositionStory(request.story);
+  if (compositionRenders.get(story.id)?.state === 'rendering') throw new Error(`The composition ${story.id} is already rendering.`);
+  const out = request.out ?? `movies/${story.id}.webm`;
+  if (!/\.webm$/i.test(out)) throw new Error(`A movie is written as .webm, not ${out}.`);
+  return compositionRenders.start(story.id, { story: story.id, out, frame: 0, frames: 0, state: 'rendering' }, async (report) => {
+    let render: CompositionRender = { story: story.id, out, frame: 0, frames: 0, state: 'rendering' };
+    const done = await renderFrames(story, request, (frame, frames) => { render = { ...render, frame, frames }; report(render); });
+    await editorHost().files.write(out, done.bytes);
+    report({ ...render, state: 'done', frame: done.frames, frames: done.frames, bytes: done.bytes.length, codec: done.codec });
+  });
+}