npm - @maravilla-labs/frames - Versions diffs - 0.1.0 → 0.2.0 - Mend

@maravilla-labs/frames 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md CHANGED Viewed

@@ -1,92 +1,135 @@
 # @maravilla-labs/frames
-A tiny, zero-dependency helper that lets a page declare a Web Animations
-API timeline once and have it driven two different ways:
+Declare a timeline of animations and video playback for a page. The same
+declaration works two ways:
-- **In a normal browser:** the animations auto-play as soon as the page
-  loads — just like any CSS or WAAPI animation.
-- **In the Maravilla deterministic renderer:** the animations stay
-  paused and the Rust renderer steps `currentTime` frame-by-frame via
-  `window.__mvFrames.applyState(t)`, producing a deterministic MP4.
+- In a normal browser, each item plays at its scheduled time on its own.
+- When the page is rendered to video by the Maravilla runtime, the
+  timeline is stepped frame by frame to produce a deterministic clip.
-The whole package is under 50 lines of vanilla TypeScript. No
-framework, no scheduler, no `requestAnimationFrame`, no `Date.now()`.
+Zero dependencies. Bring your own animation library if you want one;
+nothing is required.
-## Web Animations API model
+## Install
-Each entry in `TimelineSchema.instructions` is mapped to a single
-[`Animation`](https://developer.mozilla.org/en-US/docs/Web/API/Animation)
-created by `Element.animate(keyframes, { duration, fill: "both" })`.
-Because the animation has `fill: "both"`, setting `currentTime` to any
-value in `[0, duration]` deterministically positions every animated
-property — no implicit clock involved.
-The renderer signals its presence by setting
-`window.__mvFramesRendererPresent = true` **before** navigating to the
-page. `defineTimeline` reads that flag at call time:
-- flag set ⇒ each animation is paused immediately; the renderer drives
-  state via `applyState(t)`.
-- flag unset ⇒ animations play normally, so humans visiting the page
-  can preview what the renderer will capture.
+```sh
+pnpm add @maravilla-labs/frames
+```
 ## Usage
-```html
-<!doctype html>
-<html>
-  <body>
-    <h1 id="title">Hello</h1>
-    <script type="module">
-      import { defineTimeline } from "@maravilla-labs/frames";
-      defineTimeline({
-        duration: 2000,
-        instructions: [
-          { at: 0, selector: "#title", props: [{ opacity: 0 }, { opacity: 1 }] },
-        ],
-      });
-    </script>
-  </body>
-</html>
+```ts
+import { defineTimeline } from "@maravilla-labs/frames";
+defineTimeline({
+  duration: 5000, // total timeline length, ms
+  instructions: [
+    // Title fades in from t=0 over the first 500 ms.
+    {
+      at: 0,
+      duration: 500,
+      selector: "h1",
+      props: [{ opacity: 0 }, { opacity: 1 }],
+    },
+    // Subtitle slides up, starting 300 ms after the title begins.
+    {
+      at: 300,
+      duration: 600,
+      selector: ".subtitle",
+      props: [
+        { opacity: 0, transform: "translateY(20px)" },
+        { opacity: 1, transform: "translateY(0)" },
+      ],
+    },
+    // A clip plays from t=2000 ms until t=5000 ms (3 s of video).
+    {
+      kind: "video",
+      at: 2000,
+      duration: 3000,
+      selector: "video.intro",
+    },
+  ],
+});
 ```
-In Rust the renderer then does, per frame `i`:
+Call `defineTimeline` once, after the elements referenced by every
+`selector` exist in the DOM.
-```js
-await window.__mvFrames.applyState(i * frameMs);
-```
+## How `at` and `duration` interact
+| Field      | Meaning                                                            |
+| ---------- | ------------------------------------------------------------------ |
+| `at`       | When on the timeline this item starts, in ms                       |
+| `duration` | How long this item runs from `at`, in ms. Omit for sensible default |
+Two animations with the same `at` start at the same time. Two
+animations with different `at` values start at different times. A
+`duration` of `500` ms means the animation reaches its end keyframe
+500 ms after it started, regardless of how long the total timeline is.
+If you omit `duration` on an animation, it runs from `at` until the
+end of the timeline. If you omit `duration` on a video, it plays for
+its natural length.
-followed by a CDP `HeadlessExperimental.beginFrame` call that captures
-the rendered pixels — see the runtime plan for the full pipeline.
+## Animations
-## API
+Each animation instruction maps to a single
+[`Animation`](https://developer.mozilla.org/en-US/docs/Web/API/Animation)
+created via `Element.animate(keyframes, { duration, fill: "both" })`.
+Anything the Web Animations API supports as a keyframe is valid in
+`props`:
-### `defineTimeline(schema: TimelineSchema): void`
+```ts
+{
+  at: 1000,
+  duration: 800,
+  selector: ".card",
+  props: [
+    { transform: "scale(0.9)", opacity: 0 },
+    { transform: "scale(1)",   opacity: 1 },
+  ],
+}
+```
-Sets up the per-page animations and installs
-`window.__mvFrames.applyState`. Call it once, after the elements
-referenced by every `selector` exist in the DOM.
+## Video
+Use `kind: "video"` to schedule a `<video>` element on the timeline.
+Optionally seek inside the source file with `seek`:
 ```ts
-type FrameInstr = {
-  at: number;          // start offset, ms (currently informational)
-  selector: string;    // any querySelector
-  props: Keyframe[];   // WAAPI keyframes, e.g. [{ opacity: 0 }, { opacity: 1 }]
-};
-type TimelineSchema = {
-  duration: number;    // ms — total length the renderer will step through
-  instructions: FrameInstr[];
-};
+{
+  kind: "video",
+  at: 4000,       // start playing at t=4 s on the timeline
+  duration: 6000, // play for 6 s
+  seek: 12000,    // start 12 s into the source file
+  selector: "video#hero",
+}
+```
+The `<video>` element itself stays as you'd write it in HTML — set
+`src`, `preload="auto"`, and `muted` so the browser autoplay policy
+doesn't block it.
+```html
+<video class="intro" src="/clips/intro.mp4" preload="auto" muted playsinline></video>
 ```
-Throws if any `selector` doesn't match an element. Do not call
-`defineTimeline` more than once per page.
+If the same composition will be rendered to a final video by the
+Maravilla runtime, the audio track of the embedded `<video>` is not
+captured (browsers don't expose decoded audio to the rendering API).
+Use the `audio` option on `FRAMES.render(...)` to mix a soundtrack
+into the final output instead.
 ## Bring your own animation library
-Any library that exposes an explicit time value works the same way:
-GSAP, Lottie, Three.js. Drive their time cursor inside an
-`applyState`-equivalent and the renderer will sample them
-deterministically. `defineTimeline` is just the trivial WAAPI case
-that ships in the box.
+Any library that exposes an explicit time value works alongside this
+helper. Drive its time cursor inside the same applyState-equivalent
+hook and the renderer samples it deterministically. GSAP, Lottie, and
+Three.js all fit this shape.
+## License
+MIT

package/dist/index.d.ts CHANGED Viewed

@@ -1,20 +1,39 @@
 /**
- * @maravilla-labs/frames — declare Web Animations API timelines that the
- * Maravilla runtime renderer can drive frame-accurately.
+ * @maravilla-labs/frames — declare a timeline of animations and video
+ * playback for a page. The same declaration works two ways:
  *
- * In a normal browser visit, animations auto-play.
- * In the renderer (which sets `window.__mvFramesRendererPresent = true`
- * before navigating), animations stay paused and the renderer steps
- * them via `window.__mvFrames.applyState(t)` for deterministic output.
+ * - In a normal browser, each item plays at its scheduled `at` time.
+ * - Inside the Maravilla renderer, the timeline is stepped frame by
+ *   frame to produce deterministic video output.
  */
-export type FrameInstr = {
+export type AnimationInstr = {
+    /** Optional discriminator. Defaults to `"animation"`. */
+    kind?: "animation";
+    /** When on the timeline this animation starts, in milliseconds. */
     at: number;
+    /** How long the animation runs from `at`, in ms. Defaults to (schema.duration - at). */
+    duration?: number;
+    /** CSS selector for the element being animated. */
     selector: string;
+    /** Web Animations API keyframes, e.g. `[{ opacity: 0 }, { opacity: 1 }]`. */
     props: Keyframe[];
 };
+export type VideoInstr = {
+    /** Discriminator — required for video instructions. */
+    kind: "video";
+    /** When on the timeline the video starts, in milliseconds. */
+    at: number;
+    /** How long the clip plays, in ms. Defaults to the video's natural duration. */
+    duration?: number;
+    /** Start offset WITHIN the video file, in ms. Defaults to 0. */
+    seek?: number;
+    /** CSS selector for the `<video>` element. */
+    selector: string;
+};
+export type Instr = AnimationInstr | VideoInstr;
 export type TimelineSchema = {
     duration: number;
-    instructions: FrameInstr[];
+    instructions: Instr[];
 };
 declare global {
     interface Window {

package/dist/index.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA~~;;;;;;;;GAQG~~;AAEH,MAAM,MAAM,~~UAAU~~,GAAG;~~IAAE~~,EAAE,EAAE,MAAM,CAAC;~~IAAC~~,QAAQ,EAAE,MAAM,CAAC;~~IAAC~~,KAAK,EAAE,QAAQ,EAAE,~~CAAA~~;~~CAAE~~,CAAC;~~AAC7E~~,MAAM,MAAM,cAAc,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,~~UAAU~~,EAAE,CAAA;CAAE,CAAC;~~AAE9E~~,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,UAAU,EAAE;YAAE,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;SAAE,CAAC;QACrD,yBAAyB,CAAC,EAAE,OAAO,CAAC;KACrC;CACF;~~AAED~~,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,~~QAkBpD~~"}
1	+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,cAAc,GAAG;IAC3B,yDAAyD;IACzD,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,mEAAmE;IACnE,EAAE,EAAE,MAAM,CAAC;IACX,wFAAwF;IACxF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,uDAAuD;IACvD,IAAI,EAAE,OAAO,CAAC;IACd,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC;IACX,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,KAAK,GAAG,cAAc,GAAG,UAAU,CAAC;AAChD,MAAM,MAAM,cAAc,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,KAAK,EAAE,CAAA;CAAE,CAAC;AAEzE,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,UAAU,EAAE;YAAE,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;SAAE,CAAC;QACrD,yBAAyB,CAAC,EAAE,OAAO,CAAC;KACrC;CACF;AAMD,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAqD3D"}

package/dist/index.js CHANGED Viewed

@@ -1,29 +1,63 @@
 /**
- * @maravilla-labs/frames — declare Web Animations API timelines that the
- * Maravilla runtime renderer can drive frame-accurately.
+ * @maravilla-labs/frames — declare a timeline of animations and video
+ * playback for a page. The same declaration works two ways:
  *
- * In a normal browser visit, animations auto-play.
- * In the renderer (which sets `window.__mvFramesRendererPresent = true`
- * before navigating), animations stay paused and the renderer steps
- * them via `window.__mvFrames.applyState(t)` for deterministic output.
+ * - In a normal browser, each item plays at its scheduled `at` time.
+ * - Inside the Maravilla renderer, the timeline is stepped frame by
+ *   frame to produce deterministic video output.
  */
 export function defineTimeline(schema) {
     const rendererPresent = typeof window !== "undefined" && window.__mvFramesRendererPresent === true;
-    const animations = schema.instructions.map((i) => {
+    const slots = schema.instructions.map((i) => {
         const el = document.querySelector(i.selector);
         if (!el)
             throw new Error(`defineTimeline: no element matches ${i.selector}`);
-        const anim = el.animate(i.props, { duration: schema.duration, fill: "both" });
-        if (rendererPresent)
-            anim.pause();
-        return { at: i.at, anim };
+        if (i.kind === "video") {
+            if (!(el instanceof HTMLVideoElement)) {
+                throw new Error(`defineTimeline: ${i.selector} is not a <video> element`);
+            }
+            const seek = i.seek ?? 0;
+            const naturalMs = isFinite(el.duration) ? el.duration * 1000 : Infinity;
+            const duration = i.duration ?? Math.min(naturalMs, schema.duration - i.at);
+            el.pause();
+            el.currentTime = seek / 1000;
+            return { kind: "video", at: i.at, duration, seek, el };
+        }
+        const duration = i.duration ?? Math.max(0, schema.duration - i.at);
+        const anim = el.animate(i.props, { duration, fill: "both" });
+        anim.pause();
+        return { kind: "animation", at: i.at, duration, anim };
     });
     window.__mvFrames = {
         async applyState(t) {
-            for (const { anim } of animations)
-                anim.currentTime = t;
+            for (const s of slots) {
+                const local = clamp(t - s.at, 0, s.duration);
+                if (s.kind === "video") {
+                    s.el.pause();
+                    s.el.currentTime = (s.seek + local) / 1000;
+                }
+                else {
+                    s.anim.currentTime = local;
+                }
+            }
             await document.fonts.ready;
         },
     };
+    if (!rendererPresent) {
+        for (const s of slots) {
+            window.setTimeout(() => {
+                if (s.kind === "video") {
+                    s.el.currentTime = s.seek / 1000;
+                    void s.el.play();
+                }
+                else {
+                    s.anim.play();
+                }
+            }, s.at);
+        }
+    }
+}
+function clamp(v, lo, hi) {
+    return v < lo ? lo : v > hi ? hi : v;
 }
 //# sourceMappingURL=index.js.map

package/dist/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA~~;;;;;;;;GAQG~~;~~AAYH~~,MAAM,UAAU,cAAc,CAAC,MAAsB;IACnD,MAAM,eAAe,GACnB,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,CAAC,yBAAyB,KAAK,IAAI,CAAC;IAE7E,MAAM,~~UAAU~~,~~GAAG~~,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;~~QAC/C~~,MAAM,EAAE,GAAG,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;QAC9C,IAAI,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;~~QAC7E~~,MAAM,IAAI,GAAG,EAAE,CAAC,~~OAAO~~,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,~~EAAE~~,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;~~QAC9E~~,IAAI,~~eAAe~~;~~YAAE~~,IAAI,CAAC,KAAK,EAAE,CAAC;~~QAClC~~,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC;~~IAC5B~~,CAAC,CAAC,CAAC;IAEH,MAAM,CAAC,UAAU,GAAG;QAClB,KAAK,CAAC,UAAU,CAAC,CAAS;YACxB,KAAK,MAAM,EAAE,IAAI,EAAE,IAAI,~~UAAU~~;~~gBAAE~~,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC;~~YACxD~~,MAAM,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC;QAC7B,CAAC;KACF,CAAC;~~AACJ~~,CAAC"}
1	+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@maravilla-labs/frames",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Tiny vanilla helper for declaring Web Animations API timelines that the Maravilla runtime renderer drives frame-accurately.",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts CHANGED Viewed

@@ -1,15 +1,40 @@
 /**
- * @maravilla-labs/frames — declare Web Animations API timelines that the
- * Maravilla runtime renderer can drive frame-accurately.
+ * @maravilla-labs/frames — declare a timeline of animations and video
+ * playback for a page. The same declaration works two ways:
  *
- * In a normal browser visit, animations auto-play.
- * In the renderer (which sets `window.__mvFramesRendererPresent = true`
- * before navigating), animations stay paused and the renderer steps
- * them via `window.__mvFrames.applyState(t)` for deterministic output.
+ * - In a normal browser, each item plays at its scheduled `at` time.
+ * - Inside the Maravilla renderer, the timeline is stepped frame by
+ *   frame to produce deterministic video output.
  */
-export type FrameInstr = { at: number; selector: string; props: Keyframe[] };
-export type TimelineSchema = { duration: number; instructions: FrameInstr[] };
+export type AnimationInstr = {
+  /** Optional discriminator. Defaults to `"animation"`. */
+  kind?: "animation";
+  /** When on the timeline this animation starts, in milliseconds. */
+  at: number;
+  /** How long the animation runs from `at`, in ms. Defaults to (schema.duration - at). */
+  duration?: number;
+  /** CSS selector for the element being animated. */
+  selector: string;
+  /** Web Animations API keyframes, e.g. `[{ opacity: 0 }, { opacity: 1 }]`. */
+  props: Keyframe[];
+};
+export type VideoInstr = {
+  /** Discriminator — required for video instructions. */
+  kind: "video";
+  /** When on the timeline the video starts, in milliseconds. */
+  at: number;
+  /** How long the clip plays, in ms. Defaults to the video's natural duration. */
+  duration?: number;
+  /** Start offset WITHIN the video file, in ms. Defaults to 0. */
+  seek?: number;
+  /** CSS selector for the `<video>` element. */
+  selector: string;
+};
+export type Instr = AnimationInstr | VideoInstr;
+export type TimelineSchema = { duration: number; instructions: Instr[] };
 declare global {
   interface Window {
@@ -18,22 +43,65 @@ declare global {
   }
 }
-export function defineTimeline(schema: TimelineSchema) {
+type AnimSlot = { kind: "animation"; at: number; duration: number; anim: Animation };
+type VideoSlot = { kind: "video"; at: number; duration: number; seek: number; el: HTMLVideoElement };
+type Slot = AnimSlot | VideoSlot;
+export function defineTimeline(schema: TimelineSchema): void {
   const rendererPresent =
     typeof window !== "undefined" && window.__mvFramesRendererPresent === true;
-  const animations = schema.instructions.map((i) => {
+  const slots: Slot[] = schema.instructions.map((i) => {
     const el = document.querySelector(i.selector);
     if (!el) throw new Error(`defineTimeline: no element matches ${i.selector}`);
-    const anim = el.animate(i.props, { duration: schema.duration, fill: "both" });
-    if (rendererPresent) anim.pause();
-    return { at: i.at, anim };
+    if (i.kind === "video") {
+      if (!(el instanceof HTMLVideoElement)) {
+        throw new Error(`defineTimeline: ${i.selector} is not a <video> element`);
+      }
+      const seek = i.seek ?? 0;
+      const naturalMs = isFinite(el.duration) ? el.duration * 1000 : Infinity;
+      const duration = i.duration ?? Math.min(naturalMs, schema.duration - i.at);
+      el.pause();
+      el.currentTime = seek / 1000;
+      return { kind: "video", at: i.at, duration, seek, el };
+    }
+    const duration = i.duration ?? Math.max(0, schema.duration - i.at);
+    const anim = el.animate(i.props, { duration, fill: "both" });
+    anim.pause();
+    return { kind: "animation", at: i.at, duration, anim };
   });
   window.__mvFrames = {
     async applyState(t: number) {
-      for (const { anim } of animations) anim.currentTime = t;
+      for (const s of slots) {
+        const local = clamp(t - s.at, 0, s.duration);
+        if (s.kind === "video") {
+          s.el.pause();
+          s.el.currentTime = (s.seek + local) / 1000;
+        } else {
+          s.anim.currentTime = local;
+        }
+      }
       await document.fonts.ready;
     },
   };
+  if (!rendererPresent) {
+    for (const s of slots) {
+      window.setTimeout(() => {
+        if (s.kind === "video") {
+          s.el.currentTime = s.seek / 1000;
+          void s.el.play();
+        } else {
+          s.anim.play();
+        }
+      }, s.at);
+    }
+  }
+}
+function clamp(v: number, lo: number, hi: number): number {
+  return v < lo ? lo : v > hi ? hi : v;
 }