framesheet 0.1.0__tar.gz

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.
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024, Philipp Temminghoff
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.
22
+
@@ -0,0 +1,219 @@
1
+ Metadata-Version: 2.4
2
+ Name: framesheet
3
+ Version: 0.1.0
4
+ Summary: Frame-accurate contact sheets and motion maps for animated SVG and HTML, for humans and AI agents
5
+ Keywords:
6
+ Author: Philipp Temminghoff
7
+ Author-email: Philipp Temminghoff <philipptemminghoff@googlemail.com>
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Framework :: Pydantic
12
+ Classifier: Framework :: Pydantic :: 2
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3 :: Only
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Programming Language :: Python :: 3.14
19
+ Classifier: Topic :: Software Development
20
+ Classifier: Topic :: Utilities
21
+ Classifier: Typing :: Typed
22
+ Requires-Dist: pillow>=11.0.0
23
+ Requires-Dist: playwright>=1.50.0
24
+ Requires-Dist: pydantic
25
+ Requires-Dist: schemez
26
+ Requires-Dist: typer>=0.15.0
27
+ Requires-Python: >=3.13
28
+ Project-URL: Code coverage, https://app.codecov.io/gh/phil65/framesheet
29
+ Project-URL: Documentation, https://phil65.github.io/framesheet/
30
+ Project-URL: Issues, https://github.com/phil65/framesheet/issues
31
+ Project-URL: Source, https://github.com/phil65/framesheet
32
+ Description-Content-Type: text/markdown
33
+
34
+ # framesheet
35
+
36
+ [![PyPI License](https://img.shields.io/pypi/l/framesheet.svg)](https://pypi.org/project/framesheet/)
37
+ [![Package status](https://img.shields.io/pypi/status/framesheet.svg)](https://pypi.org/project/framesheet/)
38
+ [![Monthly downloads](https://img.shields.io/pypi/dm/framesheet.svg)](https://pypi.org/project/framesheet/)
39
+ [![Distribution format](https://img.shields.io/pypi/format/framesheet.svg)](https://pypi.org/project/framesheet/)
40
+ [![Wheel availability](https://img.shields.io/pypi/wheel/framesheet.svg)](https://pypi.org/project/framesheet/)
41
+ [![Python version](https://img.shields.io/pypi/pyversions/framesheet.svg)](https://pypi.org/project/framesheet/)
42
+ [![Implementation](https://img.shields.io/pypi/implementation/framesheet.svg)](https://pypi.org/project/framesheet/)
43
+ [![Releases](https://img.shields.io/github/downloads/phil65/framesheet/total.svg)](https://github.com/phil65/framesheet/releases)
44
+ [![Github Contributors](https://img.shields.io/github/contributors/phil65/framesheet)](https://github.com/phil65/framesheet/graphs/contributors)
45
+ [![Github Forks](https://img.shields.io/github/forks/phil65/framesheet)](https://github.com/phil65/framesheet/forks)
46
+ [![Github Issues](https://img.shields.io/github/issues/phil65/framesheet)](https://github.com/phil65/framesheet/issues)
47
+ [![Github Issues](https://img.shields.io/github/issues-pr/phil65/framesheet)](https://github.com/phil65/framesheet/pulls)
48
+ [![Github Watchers](https://img.shields.io/github/watchers/phil65/framesheet)](https://github.com/phil65/framesheet/watchers)
49
+ [![Github Stars](https://img.shields.io/github/stars/phil65/framesheet)](https://github.com/phil65/framesheet/stars)
50
+ [![Github Repository size](https://img.shields.io/github/repo-size/phil65/framesheet)](https://github.com/phil65/framesheet)
51
+ [![Github last commit](https://img.shields.io/github/last-commit/phil65/framesheet)](https://github.com/phil65/framesheet/commits)
52
+ [![Github release date](https://img.shields.io/github/release-date/phil65/framesheet)](https://github.com/phil65/framesheet/releases)
53
+ [![Github language count](https://img.shields.io/github/languages/count/phil65/framesheet)](https://github.com/phil65/framesheet)
54
+ [![Github commits this month](https://img.shields.io/github/commit-activity/m/phil65/framesheet)](https://github.com/phil65/framesheet)
55
+ [![Package status](https://codecov.io/gh/phil65/framesheet/branch/main/graph/badge.svg)](https://codecov.io/gh/phil65/framesheet/)
56
+ [![PyUp](https://pyup.io/repos/github/phil65/framesheet/shield.svg)](https://pyup.io/repos/github/phil65/framesheet/)
57
+
58
+ [Read the documentation!](https://phil65.github.io/framesheet/)
59
+
60
+ **framesheet** renders an animated SVG or HTML page at exact, evenly spaced points in
61
+ virtual time and turns them into images you (or an AI agent) can check at a glance.
62
+
63
+ An agent can only look at still images, and one screenshot shows one moment. A dot that
64
+ sits at `(0,0)` for the first second, a label that overflows its card, a box that flies
65
+ off the canvas halfway through, a loop that jumps back at the end: none of these show up
66
+ reliably in a single screenshot. framesheet captures the whole cycle, frame-accurately
67
+ and deterministically (same input, same PNG bytes), and adds numbers to back it up.
68
+
69
+ ## What you get
70
+
71
+ For every input, in the output directory:
72
+
73
+ | File | Use it for |
74
+ | --- | --- |
75
+ | `full.png` | One full-resolution frame (default `t=0`, `--at SECONDS`): layout, text, margins. |
76
+ | `sheet.png` | Contact sheet: N frames (default 12) over one cycle, each labelled `t=0.50s`. The last tile is one 60 fps frame before the cycle end, so you can judge the loop against the first tile. |
77
+ | `heatmap.png` | Motion heatmap: every pixel that changes at any time, coloured over a dimmed first frame. Shows what moves at all, including things that should not. |
78
+ | `report.json` | Detected duration and how it was found, static findings, per-frame changed-pixel ratios, bounding boxes of animated elements, elements outside the viewBox or at `(0,0)`, loop seamlessness. |
79
+
80
+ A short summary is printed to stdout (`--json` prints the report instead).
81
+
82
+ Contact sheet of [`tests/fixtures/pipeline.svg`](tests/fixtures/pipeline.svg) (SMIL dots,
83
+ a pulsing CSS hub and a spinning badge; detected cycle: LCM of 2s and 4s):
84
+
85
+ ![Contact sheet: 12 frames of the pipeline fixture](https://raw.githubusercontent.com/phil65/framesheet/main/docs/assets/pipeline_sheet.png)
86
+
87
+ Its motion heatmap:
88
+
89
+ ![Motion heatmap of the pipeline fixture](https://raw.githubusercontent.com/phil65/framesheet/main/docs/assets/pipeline_heatmap.png)
90
+
91
+ And a buggy one, [`tests/fixtures/parked_dot.svg`](tests/fixtures/parked_dot.svg):
92
+ `<animateMotion begin="1s">` leaves the dot parked in the top-left corner for a second.
93
+ Tiles 1-4 show it, the heatmap marks the corner, and the report says
94
+ `parked-at-origin: circle#dot sits at the SVG origin (0,0) at t=0.00s, 0.27s, 0.55s, 0.82s`.
95
+
96
+ ![Contact sheet of the parked-dot fixture](https://raw.githubusercontent.com/phil65/framesheet/main/docs/assets/parked_dot_sheet.png)
97
+
98
+ ![Motion heatmap of the parked-dot fixture](https://raw.githubusercontent.com/phil65/framesheet/main/docs/assets/parked_dot_heatmap.png)
99
+
100
+ ## Install
101
+
102
+ ```bash
103
+ uv tool install framesheet # or: pip install framesheet
104
+ framesheet install-browser # downloads Playwright's Chromium (once)
105
+ ```
106
+
107
+ `framesheet install-browser` runs `python -m playwright install chromium` in framesheet's
108
+ own environment, so the browser matches the installed Playwright version. In a project
109
+ environment, `uv run playwright install chromium` does the same. On a bare Linux CI
110
+ runner add `--with-deps` (`uv run playwright install --with-deps chromium`).
111
+
112
+ ## CLI
113
+
114
+ ```bash
115
+ framesheet inspect banner.svg # writes to a new temp dir, prints it
116
+ framesheet inspect banner.svg --out /tmp/check # choose the output dir
117
+ framesheet inspect banner.svg -n 16 --at 1.25 # 16 tiles, full.png at t=1.25s
118
+ framesheet inspect page.html --size 1440x900 --scale 2
119
+ framesheet inspect canvas.html --duration 4 # JS-driven: give the cycle length
120
+ framesheet inspect a.svg b.svg --out /tmp/all # one subdirectory per input
121
+ cat snippet.svg | framesheet inspect - # SVG or HTML snippet on stdin
122
+ framesheet inspect https://example.com/anim.html
123
+ framesheet inspect banner.svg --json | jq .loop
124
+ ```
125
+
126
+ Options: `--frames/-n`, `--duration`, `--at`, `--size WxH`, `--scale`, `--out/-o`,
127
+ `--tile`, `--columns`, `--keep-frames` (also write every frame to `frames/`), `--dark`
128
+ (`prefers-color-scheme: dark`), `--json`. The exit code is 1 if an error-level finding
129
+ was reported (for example malformed XML or a broken `#id` reference), 2 for usage
130
+ problems or a missing browser, 0 otherwise.
131
+
132
+ Example summary:
133
+
134
+ ```text
135
+ framesheet: tests/fixtures/non_seamless.svg (svg, 400x200 @1x)
136
+ duration: 3s detected: loop period 3s (1 animation(s): css-animation) [looping]
137
+ frames: 12 at t=0.00..2.98s; max change 2.8% at t=2.45s
138
+ loop: NOT seamless (last frame -> first frame changes 4.73% of pixels, one normal step changes 0.40%)
139
+ animated elements: circle#runner
140
+ findings: 0 error(s), 1 warning(s), 0 info
141
+ WARN [render] non-seamless-loop: The loop jumps at the cycle end: ...
142
+ images:
143
+ full /tmp/framesheet-x1y2/full.png (t=0s: layout, text, margins)
144
+ sheet /tmp/framesheet-x1y2/sheet.png (motion over one cycle)
145
+ heatmap /tmp/framesheet-x1y2/heatmap.png (what moves at all)
146
+ report /tmp/framesheet-x1y2/report.json
147
+ ```
148
+
149
+ ## Python API
150
+
151
+ ```python
152
+ import framesheet
153
+
154
+ result = framesheet.inspect("banner.svg", frames=12, out="/tmp/check")
155
+ print(result.summary())
156
+ print(result.duration.seconds, result.duration.detail)
157
+ print(result.loop.seamless, result.images.sheet)
158
+ for finding in result.findings:
159
+ print(finding.severity, finding.code, finding.element, finding.times)
160
+
161
+ # Markup strings work too (anything starting with "<").
162
+ framesheet.inspect('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10">...</svg>')
163
+ ```
164
+
165
+ `inspect()` returns an `InspectionResult` (pydantic model): image paths, `duration`,
166
+ `times`, `frames` (per-frame metrics), `elements` (per-frame boxes of animated elements),
167
+ `loop`, `findings` and `console_errors`. It uses Playwright's sync API, so call it
168
+ outside a running asyncio loop (or in a worker thread).
169
+
170
+ ## The agent loop
171
+
172
+ 1. Run `framesheet inspect FILE --out DIR`.
173
+ 2. Read the summary, fix every `ERROR` and `WARN`.
174
+ 3. Look at `full.png` for layout: text clipping, cramped margins, connectors meeting
175
+ card edges, contrast.
176
+ 4. Look at `sheet.png` for motion: does every tile look intentional? Do the first and
177
+ last tile join up for a loop?
178
+ 5. Look at `heatmap.png` for unexpected movement: anything coloured that should be still?
179
+ 6. Use `report.json` for numbers (boxes per frame, changed-pixel ratios, seam ratio).
180
+ 7. Re-run until clean.
181
+
182
+ ## How time is controlled
183
+
184
+ framesheet never takes wall-clock screenshots. Everything runs on a virtual clock:
185
+
186
+ - **SMIL**: `pauseAnimations()` + `setCurrentTime(t)` on every outermost `<svg>`.
187
+ - **CSS animations/transitions and Web Animations**: every `document.getAnimations()`
188
+ entry is paused and its `currentTime` set to `t`.
189
+ - **JavaScript** (`requestAnimationFrame`, canvas, `Date`, `performance.now`, timers):
190
+ Playwright's fake clock is installed before the page loads and only advances when
191
+ framesheet moves to the next sample time, firing every due timer and rAF callback.
192
+
193
+ The cycle length is detected from SMIL `begin`/`dur`/`repeatCount` and CSS/Web Animation
194
+ timing (delay + duration x iterations, alternate = 2x duration, several loops = least
195
+ common multiple when short enough). Override it with `--duration`; with no declarative
196
+ animation framesheet samples 3 seconds and tells you so.
197
+
198
+ ## Checks
199
+
200
+ Static checks (ported from the `svg-animation` skill's `verify_svg.py`): malformed XML,
201
+ missing `xmlns`/`viewBox`/title, `<script>`, `on*` handlers, external URLs and fonts,
202
+ `<foreignObject>`, duplicate ids, broken `#id`/`url(#id)` references, positive
203
+ `<animateMotion begin>`, missing `prefers-reduced-motion`, CSS transforms without
204
+ `transform-box`, large files.
205
+
206
+ Render checks (from geometry at every sampled frame): `parked-at-origin`,
207
+ `outside-bounds`, `text-overflow` (SVG text vs. the rect under it; HTML text larger than
208
+ its box), `svg-transform-box` (CSS transform animation pivoting around the SVG origin),
209
+ `non-seamless-loop`, `js-driven-motion`, `console-error`.
210
+
211
+ ## Limitations
212
+
213
+ - Chromium only. Fonts are whatever the machine has, so text widths can differ from
214
+ macOS/Windows; leave slack in text containers.
215
+ - Animations created by script after load are timed from the sample at which framesheet
216
+ first sees them (accurate to one sample step).
217
+ - JS clocks run about 17 ms (one frame) ahead of SMIL/CSS time so that rAF content has
218
+ painted at `t=0`.
219
+ - Content outside the viewBox is clipped in the images; the report still lists it.
@@ -0,0 +1,186 @@
1
+ # framesheet
2
+
3
+ [![PyPI License](https://img.shields.io/pypi/l/framesheet.svg)](https://pypi.org/project/framesheet/)
4
+ [![Package status](https://img.shields.io/pypi/status/framesheet.svg)](https://pypi.org/project/framesheet/)
5
+ [![Monthly downloads](https://img.shields.io/pypi/dm/framesheet.svg)](https://pypi.org/project/framesheet/)
6
+ [![Distribution format](https://img.shields.io/pypi/format/framesheet.svg)](https://pypi.org/project/framesheet/)
7
+ [![Wheel availability](https://img.shields.io/pypi/wheel/framesheet.svg)](https://pypi.org/project/framesheet/)
8
+ [![Python version](https://img.shields.io/pypi/pyversions/framesheet.svg)](https://pypi.org/project/framesheet/)
9
+ [![Implementation](https://img.shields.io/pypi/implementation/framesheet.svg)](https://pypi.org/project/framesheet/)
10
+ [![Releases](https://img.shields.io/github/downloads/phil65/framesheet/total.svg)](https://github.com/phil65/framesheet/releases)
11
+ [![Github Contributors](https://img.shields.io/github/contributors/phil65/framesheet)](https://github.com/phil65/framesheet/graphs/contributors)
12
+ [![Github Forks](https://img.shields.io/github/forks/phil65/framesheet)](https://github.com/phil65/framesheet/forks)
13
+ [![Github Issues](https://img.shields.io/github/issues/phil65/framesheet)](https://github.com/phil65/framesheet/issues)
14
+ [![Github Issues](https://img.shields.io/github/issues-pr/phil65/framesheet)](https://github.com/phil65/framesheet/pulls)
15
+ [![Github Watchers](https://img.shields.io/github/watchers/phil65/framesheet)](https://github.com/phil65/framesheet/watchers)
16
+ [![Github Stars](https://img.shields.io/github/stars/phil65/framesheet)](https://github.com/phil65/framesheet/stars)
17
+ [![Github Repository size](https://img.shields.io/github/repo-size/phil65/framesheet)](https://github.com/phil65/framesheet)
18
+ [![Github last commit](https://img.shields.io/github/last-commit/phil65/framesheet)](https://github.com/phil65/framesheet/commits)
19
+ [![Github release date](https://img.shields.io/github/release-date/phil65/framesheet)](https://github.com/phil65/framesheet/releases)
20
+ [![Github language count](https://img.shields.io/github/languages/count/phil65/framesheet)](https://github.com/phil65/framesheet)
21
+ [![Github commits this month](https://img.shields.io/github/commit-activity/m/phil65/framesheet)](https://github.com/phil65/framesheet)
22
+ [![Package status](https://codecov.io/gh/phil65/framesheet/branch/main/graph/badge.svg)](https://codecov.io/gh/phil65/framesheet/)
23
+ [![PyUp](https://pyup.io/repos/github/phil65/framesheet/shield.svg)](https://pyup.io/repos/github/phil65/framesheet/)
24
+
25
+ [Read the documentation!](https://phil65.github.io/framesheet/)
26
+
27
+ **framesheet** renders an animated SVG or HTML page at exact, evenly spaced points in
28
+ virtual time and turns them into images you (or an AI agent) can check at a glance.
29
+
30
+ An agent can only look at still images, and one screenshot shows one moment. A dot that
31
+ sits at `(0,0)` for the first second, a label that overflows its card, a box that flies
32
+ off the canvas halfway through, a loop that jumps back at the end: none of these show up
33
+ reliably in a single screenshot. framesheet captures the whole cycle, frame-accurately
34
+ and deterministically (same input, same PNG bytes), and adds numbers to back it up.
35
+
36
+ ## What you get
37
+
38
+ For every input, in the output directory:
39
+
40
+ | File | Use it for |
41
+ | --- | --- |
42
+ | `full.png` | One full-resolution frame (default `t=0`, `--at SECONDS`): layout, text, margins. |
43
+ | `sheet.png` | Contact sheet: N frames (default 12) over one cycle, each labelled `t=0.50s`. The last tile is one 60 fps frame before the cycle end, so you can judge the loop against the first tile. |
44
+ | `heatmap.png` | Motion heatmap: every pixel that changes at any time, coloured over a dimmed first frame. Shows what moves at all, including things that should not. |
45
+ | `report.json` | Detected duration and how it was found, static findings, per-frame changed-pixel ratios, bounding boxes of animated elements, elements outside the viewBox or at `(0,0)`, loop seamlessness. |
46
+
47
+ A short summary is printed to stdout (`--json` prints the report instead).
48
+
49
+ Contact sheet of [`tests/fixtures/pipeline.svg`](tests/fixtures/pipeline.svg) (SMIL dots,
50
+ a pulsing CSS hub and a spinning badge; detected cycle: LCM of 2s and 4s):
51
+
52
+ ![Contact sheet: 12 frames of the pipeline fixture](https://raw.githubusercontent.com/phil65/framesheet/main/docs/assets/pipeline_sheet.png)
53
+
54
+ Its motion heatmap:
55
+
56
+ ![Motion heatmap of the pipeline fixture](https://raw.githubusercontent.com/phil65/framesheet/main/docs/assets/pipeline_heatmap.png)
57
+
58
+ And a buggy one, [`tests/fixtures/parked_dot.svg`](tests/fixtures/parked_dot.svg):
59
+ `<animateMotion begin="1s">` leaves the dot parked in the top-left corner for a second.
60
+ Tiles 1-4 show it, the heatmap marks the corner, and the report says
61
+ `parked-at-origin: circle#dot sits at the SVG origin (0,0) at t=0.00s, 0.27s, 0.55s, 0.82s`.
62
+
63
+ ![Contact sheet of the parked-dot fixture](https://raw.githubusercontent.com/phil65/framesheet/main/docs/assets/parked_dot_sheet.png)
64
+
65
+ ![Motion heatmap of the parked-dot fixture](https://raw.githubusercontent.com/phil65/framesheet/main/docs/assets/parked_dot_heatmap.png)
66
+
67
+ ## Install
68
+
69
+ ```bash
70
+ uv tool install framesheet # or: pip install framesheet
71
+ framesheet install-browser # downloads Playwright's Chromium (once)
72
+ ```
73
+
74
+ `framesheet install-browser` runs `python -m playwright install chromium` in framesheet's
75
+ own environment, so the browser matches the installed Playwright version. In a project
76
+ environment, `uv run playwright install chromium` does the same. On a bare Linux CI
77
+ runner add `--with-deps` (`uv run playwright install --with-deps chromium`).
78
+
79
+ ## CLI
80
+
81
+ ```bash
82
+ framesheet inspect banner.svg # writes to a new temp dir, prints it
83
+ framesheet inspect banner.svg --out /tmp/check # choose the output dir
84
+ framesheet inspect banner.svg -n 16 --at 1.25 # 16 tiles, full.png at t=1.25s
85
+ framesheet inspect page.html --size 1440x900 --scale 2
86
+ framesheet inspect canvas.html --duration 4 # JS-driven: give the cycle length
87
+ framesheet inspect a.svg b.svg --out /tmp/all # one subdirectory per input
88
+ cat snippet.svg | framesheet inspect - # SVG or HTML snippet on stdin
89
+ framesheet inspect https://example.com/anim.html
90
+ framesheet inspect banner.svg --json | jq .loop
91
+ ```
92
+
93
+ Options: `--frames/-n`, `--duration`, `--at`, `--size WxH`, `--scale`, `--out/-o`,
94
+ `--tile`, `--columns`, `--keep-frames` (also write every frame to `frames/`), `--dark`
95
+ (`prefers-color-scheme: dark`), `--json`. The exit code is 1 if an error-level finding
96
+ was reported (for example malformed XML or a broken `#id` reference), 2 for usage
97
+ problems or a missing browser, 0 otherwise.
98
+
99
+ Example summary:
100
+
101
+ ```text
102
+ framesheet: tests/fixtures/non_seamless.svg (svg, 400x200 @1x)
103
+ duration: 3s detected: loop period 3s (1 animation(s): css-animation) [looping]
104
+ frames: 12 at t=0.00..2.98s; max change 2.8% at t=2.45s
105
+ loop: NOT seamless (last frame -> first frame changes 4.73% of pixels, one normal step changes 0.40%)
106
+ animated elements: circle#runner
107
+ findings: 0 error(s), 1 warning(s), 0 info
108
+ WARN [render] non-seamless-loop: The loop jumps at the cycle end: ...
109
+ images:
110
+ full /tmp/framesheet-x1y2/full.png (t=0s: layout, text, margins)
111
+ sheet /tmp/framesheet-x1y2/sheet.png (motion over one cycle)
112
+ heatmap /tmp/framesheet-x1y2/heatmap.png (what moves at all)
113
+ report /tmp/framesheet-x1y2/report.json
114
+ ```
115
+
116
+ ## Python API
117
+
118
+ ```python
119
+ import framesheet
120
+
121
+ result = framesheet.inspect("banner.svg", frames=12, out="/tmp/check")
122
+ print(result.summary())
123
+ print(result.duration.seconds, result.duration.detail)
124
+ print(result.loop.seamless, result.images.sheet)
125
+ for finding in result.findings:
126
+ print(finding.severity, finding.code, finding.element, finding.times)
127
+
128
+ # Markup strings work too (anything starting with "<").
129
+ framesheet.inspect('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10">...</svg>')
130
+ ```
131
+
132
+ `inspect()` returns an `InspectionResult` (pydantic model): image paths, `duration`,
133
+ `times`, `frames` (per-frame metrics), `elements` (per-frame boxes of animated elements),
134
+ `loop`, `findings` and `console_errors`. It uses Playwright's sync API, so call it
135
+ outside a running asyncio loop (or in a worker thread).
136
+
137
+ ## The agent loop
138
+
139
+ 1. Run `framesheet inspect FILE --out DIR`.
140
+ 2. Read the summary, fix every `ERROR` and `WARN`.
141
+ 3. Look at `full.png` for layout: text clipping, cramped margins, connectors meeting
142
+ card edges, contrast.
143
+ 4. Look at `sheet.png` for motion: does every tile look intentional? Do the first and
144
+ last tile join up for a loop?
145
+ 5. Look at `heatmap.png` for unexpected movement: anything coloured that should be still?
146
+ 6. Use `report.json` for numbers (boxes per frame, changed-pixel ratios, seam ratio).
147
+ 7. Re-run until clean.
148
+
149
+ ## How time is controlled
150
+
151
+ framesheet never takes wall-clock screenshots. Everything runs on a virtual clock:
152
+
153
+ - **SMIL**: `pauseAnimations()` + `setCurrentTime(t)` on every outermost `<svg>`.
154
+ - **CSS animations/transitions and Web Animations**: every `document.getAnimations()`
155
+ entry is paused and its `currentTime` set to `t`.
156
+ - **JavaScript** (`requestAnimationFrame`, canvas, `Date`, `performance.now`, timers):
157
+ Playwright's fake clock is installed before the page loads and only advances when
158
+ framesheet moves to the next sample time, firing every due timer and rAF callback.
159
+
160
+ The cycle length is detected from SMIL `begin`/`dur`/`repeatCount` and CSS/Web Animation
161
+ timing (delay + duration x iterations, alternate = 2x duration, several loops = least
162
+ common multiple when short enough). Override it with `--duration`; with no declarative
163
+ animation framesheet samples 3 seconds and tells you so.
164
+
165
+ ## Checks
166
+
167
+ Static checks (ported from the `svg-animation` skill's `verify_svg.py`): malformed XML,
168
+ missing `xmlns`/`viewBox`/title, `<script>`, `on*` handlers, external URLs and fonts,
169
+ `<foreignObject>`, duplicate ids, broken `#id`/`url(#id)` references, positive
170
+ `<animateMotion begin>`, missing `prefers-reduced-motion`, CSS transforms without
171
+ `transform-box`, large files.
172
+
173
+ Render checks (from geometry at every sampled frame): `parked-at-origin`,
174
+ `outside-bounds`, `text-overflow` (SVG text vs. the rect under it; HTML text larger than
175
+ its box), `svg-transform-box` (CSS transform animation pivoting around the SVG origin),
176
+ `non-seamless-loop`, `js-driven-motion`, `console-error`.
177
+
178
+ ## Limitations
179
+
180
+ - Chromium only. Fonts are whatever the machine has, so text widths can differ from
181
+ macOS/Windows; leave slack in text containers.
182
+ - Animations created by script after load are timed from the sample at which framesheet
183
+ first sees them (accurate to one sample step).
184
+ - JS clocks run about 17 ms (one frame) ahead of SMIL/CSS time so that rAF content has
185
+ painted at `t=0`.
186
+ - Content outside the viewBox is clipped in the images; the report still lists it.