@maravilla-labs/frames 0.1.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 (8) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +92 -0
  3. package/dist/index.d.ts +28 -0
  4. package/dist/index.d.ts.map +1 -0
  5. package/dist/index.js +29 -0
  6. package/dist/index.js.map +1 -0
  7. package/package.json +41 -0
  8. package/src/index.ts +39 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 SOLUTAS GmbH
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,92 @@
1
+ # @maravilla-labs/frames
2
+
3
+ A tiny, zero-dependency helper that lets a page declare a Web Animations
4
+ API timeline once and have it driven two different ways:
5
+
6
+ - **In a normal browser:** the animations auto-play as soon as the page
7
+ loads — just like any CSS or WAAPI animation.
8
+ - **In the Maravilla deterministic renderer:** the animations stay
9
+ paused and the Rust renderer steps `currentTime` frame-by-frame via
10
+ `window.__mvFrames.applyState(t)`, producing a deterministic MP4.
11
+
12
+ The whole package is under 50 lines of vanilla TypeScript. No
13
+ framework, no scheduler, no `requestAnimationFrame`, no `Date.now()`.
14
+
15
+ ## Web Animations API model
16
+
17
+ Each entry in `TimelineSchema.instructions` is mapped to a single
18
+ [`Animation`](https://developer.mozilla.org/en-US/docs/Web/API/Animation)
19
+ created by `Element.animate(keyframes, { duration, fill: "both" })`.
20
+ Because the animation has `fill: "both"`, setting `currentTime` to any
21
+ value in `[0, duration]` deterministically positions every animated
22
+ property — no implicit clock involved.
23
+
24
+ The renderer signals its presence by setting
25
+ `window.__mvFramesRendererPresent = true` **before** navigating to the
26
+ page. `defineTimeline` reads that flag at call time:
27
+
28
+ - flag set ⇒ each animation is paused immediately; the renderer drives
29
+ state via `applyState(t)`.
30
+ - flag unset ⇒ animations play normally, so humans visiting the page
31
+ can preview what the renderer will capture.
32
+
33
+ ## Usage
34
+
35
+ ```html
36
+ <!doctype html>
37
+ <html>
38
+ <body>
39
+ <h1 id="title">Hello</h1>
40
+ <script type="module">
41
+ import { defineTimeline } from "@maravilla-labs/frames";
42
+
43
+ defineTimeline({
44
+ duration: 2000,
45
+ instructions: [
46
+ { at: 0, selector: "#title", props: [{ opacity: 0 }, { opacity: 1 }] },
47
+ ],
48
+ });
49
+ </script>
50
+ </body>
51
+ </html>
52
+ ```
53
+
54
+ In Rust the renderer then does, per frame `i`:
55
+
56
+ ```js
57
+ await window.__mvFrames.applyState(i * frameMs);
58
+ ```
59
+
60
+ followed by a CDP `HeadlessExperimental.beginFrame` call that captures
61
+ the rendered pixels — see the runtime plan for the full pipeline.
62
+
63
+ ## API
64
+
65
+ ### `defineTimeline(schema: TimelineSchema): void`
66
+
67
+ Sets up the per-page animations and installs
68
+ `window.__mvFrames.applyState`. Call it once, after the elements
69
+ referenced by every `selector` exist in the DOM.
70
+
71
+ ```ts
72
+ type FrameInstr = {
73
+ at: number; // start offset, ms (currently informational)
74
+ selector: string; // any querySelector
75
+ props: Keyframe[]; // WAAPI keyframes, e.g. [{ opacity: 0 }, { opacity: 1 }]
76
+ };
77
+ type TimelineSchema = {
78
+ duration: number; // ms — total length the renderer will step through
79
+ instructions: FrameInstr[];
80
+ };
81
+ ```
82
+
83
+ Throws if any `selector` doesn't match an element. Do not call
84
+ `defineTimeline` more than once per page.
85
+
86
+ ## Bring your own animation library
87
+
88
+ Any library that exposes an explicit time value works the same way:
89
+ GSAP, Lottie, Three.js. Drive their time cursor inside an
90
+ `applyState`-equivalent and the renderer will sample them
91
+ deterministically. `defineTimeline` is just the trivial WAAPI case
92
+ that ships in the box.
package/dist/index.d.ts ADDED
@@ -0,0 +1,28 @@
1
+ /**
2
+ * @maravilla-labs/frames — declare Web Animations API timelines that the
3
+ * Maravilla runtime renderer can drive frame-accurately.
4
+ *
5
+ * In a normal browser visit, animations auto-play.
6
+ * In the renderer (which sets `window.__mvFramesRendererPresent = true`
7
+ * before navigating), animations stay paused and the renderer steps
8
+ * them via `window.__mvFrames.applyState(t)` for deterministic output.
9
+ */
10
+ export type FrameInstr = {
11
+ at: number;
12
+ selector: string;
13
+ props: Keyframe[];
14
+ };
15
+ export type TimelineSchema = {
16
+ duration: number;
17
+ instructions: FrameInstr[];
18
+ };
19
+ declare global {
20
+ interface Window {
21
+ __mvFrames: {
22
+ applyState(t: number): Promise<void>;
23
+ };
24
+ __mvFramesRendererPresent?: boolean;
25
+ }
26
+ }
27
+ export declare function defineTimeline(schema: TimelineSchema): void;
28
+ //# sourceMappingURL=index.d.ts.map
package/dist/index.d.ts.map ADDED
@@ -0,0 +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"}
package/dist/index.js ADDED
@@ -0,0 +1,29 @@
1
+ /**
2
+ * @maravilla-labs/frames — declare Web Animations API timelines that the
3
+ * Maravilla runtime renderer can drive frame-accurately.
4
+ *
5
+ * In a normal browser visit, animations auto-play.
6
+ * In the renderer (which sets `window.__mvFramesRendererPresent = true`
7
+ * before navigating), animations stay paused and the renderer steps
8
+ * them via `window.__mvFrames.applyState(t)` for deterministic output.
9
+ */
10
+ export function defineTimeline(schema) {
11
+ const rendererPresent = typeof window !== "undefined" && window.__mvFramesRendererPresent === true;
12
+ const animations = schema.instructions.map((i) => {
13
+ const el = document.querySelector(i.selector);
14
+ if (!el)
15
+ throw new Error(`defineTimeline: no element matches ${i.selector}`);
16
+ const anim = el.animate(i.props, { duration: schema.duration, fill: "both" });
17
+ if (rendererPresent)
18
+ anim.pause();
19
+ return { at: i.at, anim };
20
+ });
21
+ window.__mvFrames = {
22
+ async applyState(t) {
23
+ for (const { anim } of animations)
24
+ anim.currentTime = t;
25
+ await document.fonts.ready;
26
+ },
27
+ };
28
+ }
29
+ //# sourceMappingURL=index.js.map
package/dist/index.js.map ADDED
@@ -0,0 +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"}
package/package.json ADDED
@@ -0,0 +1,41 @@
1
+ {
2
+ "name": "@maravilla-labs/frames",
3
+ "version": "0.1.0",
4
+ "description": "Tiny vanilla helper for declaring Web Animations API timelines that the Maravilla runtime renderer drives frame-accurately.",
5
+ "type": "module",
6
+ "main": "./dist/index.js",
7
+ "module": "./dist/index.js",
8
+ "types": "./dist/index.d.ts",
9
+ "exports": {
10
+ ".": {
11
+ "types": "./dist/index.d.ts",
12
+ "import": "./dist/index.js"
13
+ }
14
+ },
15
+ "files": [
16
+ "dist",
17
+ "src",
18
+ "README.md",
19
+ "LICENSE"
20
+ ],
21
+ "scripts": {
22
+ "build": "tsc",
23
+ "typecheck": "tsc --noEmit",
24
+ "prepublishOnly": "tsc"
25
+ },
26
+ "keywords": [
27
+ "maravilla",
28
+ "frames",
29
+ "web-animations",
30
+ "timeline",
31
+ "rendering"
32
+ ],
33
+ "author": "SOLUTAS GmbH",
34
+ "license": "MIT",
35
+ "devDependencies": {
36
+ "typescript": "^5.0.0"
37
+ },
38
+ "publishConfig": {
39
+ "access": "public"
40
+ }
41
+ }
package/src/index.ts ADDED
@@ -0,0 +1,39 @@
1
+ /**
2
+ * @maravilla-labs/frames — declare Web Animations API timelines that the
3
+ * Maravilla runtime renderer can drive frame-accurately.
4
+ *
5
+ * In a normal browser visit, animations auto-play.
6
+ * In the renderer (which sets `window.__mvFramesRendererPresent = true`
7
+ * before navigating), animations stay paused and the renderer steps
8
+ * them via `window.__mvFrames.applyState(t)` for deterministic output.
9
+ */
10
+
11
+ export type FrameInstr = { at: number; selector: string; props: Keyframe[] };
12
+ export type TimelineSchema = { duration: number; instructions: FrameInstr[] };
13
+
14
+ declare global {
15
+ interface Window {
16
+ __mvFrames: { applyState(t: number): Promise<void> };
17
+ __mvFramesRendererPresent?: boolean;
18
+ }
19
+ }
20
+
21
+ export function defineTimeline(schema: TimelineSchema) {
22
+ const rendererPresent =
23
+ typeof window !== "undefined" && window.__mvFramesRendererPresent === true;
24
+
25
+ const animations = schema.instructions.map((i) => {
26
+ const el = document.querySelector(i.selector);
27
+ if (!el) throw new Error(`defineTimeline: no element matches ${i.selector}`);
28
+ const anim = el.animate(i.props, { duration: schema.duration, fill: "both" });
29
+ if (rendererPresent) anim.pause();
30
+ return { at: i.at, anim };
31
+ });
32
+
33
+ window.__mvFrames = {
34
+ async applyState(t: number) {
35
+ for (const { anim } of animations) anim.currentTime = t;
36
+ await document.fonts.ready;
37
+ },
38
+ };
39
+ }