fix(cli): stop promising a universal per-time filmstrip for --layout strip - #3867
Merged
Merged
Conversation
…strip `keyframes --shot --layout strip`'s help text, its type's inline doc comment, and the CLI reference docs all described 'strip' as an unqualified "filmstrip by time". In reality a real per-time pixel filmstrip is only produced when the sampled selector is an SVG element (gated by an internal SVG-shape check); any other selector — including every nested sub-composition host, which is always a `<div data-composition-src>` — silently falls back to one live screenshot plus vector position markers instead. That's not a capture bug: for a non-SVG selector, per-time pixel compositing was never implemented, only true 3D bbox/marker sampling. But the documented behavior over-promised what the tool does for the overwhelmingly common case (a DOM/sub-composition selector), so a user following the docs sees root captions and empty image boxes where they expected the nested composition's actual content to move across frames. Reworded all three descriptions to state the SVG-only condition and the DOM/sub-composition fallback explicitly. No behavior changed. Adds a test asserting the CLI help text no longer makes the unqualified claim and does disclose the SVG-only condition, to catch a future regression back to the misleading wording. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
miguel-heygen
approved these changes
Sep 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
keyframes --shot --layout strip's help text, its type's inline doc comment, and the CLI reference docs all describedstripas an unqualified "filmstrip by time." The tool doesn't actually do that for the overwhelmingly common case.Why
A real per-time pixel filmstrip is only produced when the sampled selector is an SVG element (gated by an internal shape check —
typeof element.getBBox === "function" && typeof element.getScreenCTM === "function"). Any other selector — including every nested sub-composition host, which is always a<div data-composition-src>— silently falls back to one live screenshot plus vector position markers instead.This isn't a capture bug: for a non-SVG selector, real per-time pixel compositing was never implemented, only 3D bbox/marker sampling. But the documented behavior over-promised what the tool does, so a user following the docs on the common case (a DOM/sub-composition selector) sees root captions and empty image boxes where they expected the nested composition's actual content to move across frames — the diagnostic strip is misleading, even though the real render is correct.
How
Reworded all three descriptions (CLI help text,
ShotOptions.layoutTSDoc, and the reference docs table) to state the SVG-only condition and the DOM/sub-composition fallback explicitly. No behavior changed — this is a documentation-accuracy fix, per the ticket's own framing that a doc-only fix fully resolves the reported symptom (a silent, misleading omission) for a P3.Testing
Added a test asserting the CLI help text no longer makes the unqualified "filmstrip by time" claim and does disclose the SVG-only condition — guards against a future regression back to the misleading wording. Verified RED (fails against the pre-fix string) and GREEN (passes after the fix) via a local before/after comparison.
bunx vitest run src/commands/keyframes.test.ts src/commands/motionShotLayout.test.ts— 46/46 passingbunx tsc --noEmitinpackages/cli— cleanbunx oxlint/bunx oxfmt --writeon changed files — clean🤖 Generated with Claude Code