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.
- framesheet-0.1.0/LICENSE +22 -0
- framesheet-0.1.0/PKG-INFO +219 -0
- framesheet-0.1.0/README.md +186 -0
- framesheet-0.1.0/pyproject.toml +280 -0
- framesheet-0.1.0/pyproject.toml.orig +303 -0
- framesheet-0.1.0/src/framesheet/__init__.py +46 -0
- framesheet-0.1.0/src/framesheet/analysis.py +392 -0
- framesheet-0.1.0/src/framesheet/checks.py +246 -0
- framesheet-0.1.0/src/framesheet/cli.py +113 -0
- framesheet-0.1.0/src/framesheet/compose.py +259 -0
- framesheet-0.1.0/src/framesheet/core.py +340 -0
- framesheet-0.1.0/src/framesheet/log.py +25 -0
- framesheet-0.1.0/src/framesheet/models.py +195 -0
- framesheet-0.1.0/src/framesheet/py.typed +0 -0
- framesheet-0.1.0/src/framesheet/render.py +192 -0
- framesheet-0.1.0/src/framesheet/runtime.js +323 -0
- framesheet-0.1.0/src/framesheet/sources.py +135 -0
- framesheet-0.1.0/src/framesheet/timing.py +118 -0
framesheet-0.1.0/LICENSE
ADDED
|
@@ -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
|
+
[](https://pypi.org/project/framesheet/)
|
|
37
|
+
[](https://pypi.org/project/framesheet/)
|
|
38
|
+
[](https://pypi.org/project/framesheet/)
|
|
39
|
+
[](https://pypi.org/project/framesheet/)
|
|
40
|
+
[](https://pypi.org/project/framesheet/)
|
|
41
|
+
[](https://pypi.org/project/framesheet/)
|
|
42
|
+
[](https://pypi.org/project/framesheet/)
|
|
43
|
+
[](https://github.com/phil65/framesheet/releases)
|
|
44
|
+
[](https://github.com/phil65/framesheet/graphs/contributors)
|
|
45
|
+
[](https://github.com/phil65/framesheet/forks)
|
|
46
|
+
[](https://github.com/phil65/framesheet/issues)
|
|
47
|
+
[](https://github.com/phil65/framesheet/pulls)
|
|
48
|
+
[](https://github.com/phil65/framesheet/watchers)
|
|
49
|
+
[](https://github.com/phil65/framesheet/stars)
|
|
50
|
+
[](https://github.com/phil65/framesheet)
|
|
51
|
+
[](https://github.com/phil65/framesheet/commits)
|
|
52
|
+
[](https://github.com/phil65/framesheet/releases)
|
|
53
|
+
[](https://github.com/phil65/framesheet)
|
|
54
|
+
[](https://github.com/phil65/framesheet)
|
|
55
|
+
[](https://codecov.io/gh/phil65/framesheet/)
|
|
56
|
+
[](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
|
+

|
|
86
|
+
|
|
87
|
+
Its motion heatmap:
|
|
88
|
+
|
|
89
|
+

|
|
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
|
+

|
|
97
|
+
|
|
98
|
+

|
|
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
|
+
[](https://pypi.org/project/framesheet/)
|
|
4
|
+
[](https://pypi.org/project/framesheet/)
|
|
5
|
+
[](https://pypi.org/project/framesheet/)
|
|
6
|
+
[](https://pypi.org/project/framesheet/)
|
|
7
|
+
[](https://pypi.org/project/framesheet/)
|
|
8
|
+
[](https://pypi.org/project/framesheet/)
|
|
9
|
+
[](https://pypi.org/project/framesheet/)
|
|
10
|
+
[](https://github.com/phil65/framesheet/releases)
|
|
11
|
+
[](https://github.com/phil65/framesheet/graphs/contributors)
|
|
12
|
+
[](https://github.com/phil65/framesheet/forks)
|
|
13
|
+
[](https://github.com/phil65/framesheet/issues)
|
|
14
|
+
[](https://github.com/phil65/framesheet/pulls)
|
|
15
|
+
[](https://github.com/phil65/framesheet/watchers)
|
|
16
|
+
[](https://github.com/phil65/framesheet/stars)
|
|
17
|
+
[](https://github.com/phil65/framesheet)
|
|
18
|
+
[](https://github.com/phil65/framesheet/commits)
|
|
19
|
+
[](https://github.com/phil65/framesheet/releases)
|
|
20
|
+
[](https://github.com/phil65/framesheet)
|
|
21
|
+
[](https://github.com/phil65/framesheet)
|
|
22
|
+
[](https://codecov.io/gh/phil65/framesheet/)
|
|
23
|
+
[](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
|
+

|
|
53
|
+
|
|
54
|
+
Its motion heatmap:
|
|
55
|
+
|
|
56
|
+

|
|
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
|
+

|
|
64
|
+
|
|
65
|
+

|
|
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.
|