Phase 1 (5/5): ManimView SwiftUI preview, demo scene, and docs

[ronaldmannak]

Summary

The presentation layer that completes Phase 1:

• ManimView — a SwiftUI player for ManimScene. Renders snapshot(at:) into a Canvas in Manim coordinates (origin center, +y up, 8-unit-tall frame, uniform fit), strokes partial outlines via trimmedPath for draw-in animations, fills through the mobject's opacity factors. Playback state is just an anchor time + the TimelineView clock, so play/pause, restart, scrubbing, and looping are pure arithmetic; a paused schedule stops the render loop entirely. Controls (play/pause, restart, scrubber, time label) carry accessibility labels.
• ManimScene.demo — a short tour (create → shift → morph to square → parallel rotate/scale → second morph → fades), wired into #Preview.
• README — full Phase 1 documentation: scene building, semantics, ManimView usage, shape reference, roadmap.

The whole file is fenced behind #if canImport(SwiftUI); the Linux CI job proves the rest of the package never depends on it.

Stack

PR 5/5 — stacked on #4. Closes out the Phase 1 stack (#1 → #5).

Intentionally not included (Phase 2+, tracked in issues)

Text/LaTeX mobjects, groups, axes, updaters, video export, camera moves — plus the deferred technical improvements filed as issues and linked from this PR after it opens.

Test strategy

The demo scene is pure timeline logic, so CI exercises it headlessly: evaluates non-empty at 21 sample times and ends fully faded out. Canvas rendering itself is not unit-testable; verification is #Preview on a Mac (blue circle draws in, morphs to red square, rotates/scales, morphs to hexagon, fades out). Called out here explicitly rather than pretending pixel coverage exists.

Concurrency

ManimView is a plain View struct; the only mutable state in the entire package is its SwiftUI @State (main-actor by construction). No @unchecked Sendable anywhere in Phase 1.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YGb3ukB5dQy4vgz7Z1hags

---

Generated by Claude Code

[ronaldmannak]

Deferred-work issues for the stack, as promised in the description:

• Phase 2 umbrella: text/LaTeX mobjects, groups, axes, updaters, video export #6 — Phase 2 umbrella (text/LaTeX, groups, axes, updaters, video export, camera)
• Morph quality: arc-length-based path resampling for transform alignment #7 — arc-length-based morph resampling (affects Phase 1 (2/5): Cubic Bézier engine — curves, paths, partials, morph alignment #2/Phase 1 (4/5): Animation timeline — rate functions, animations, ManimScene #4 internals, not user-visible for Phase 1 shapes)
• ManimView: cache converted SwiftUI Paths across frames #8 — ManimView path caching (profile-gated renderer optimization)
• BezierPath.interpolate: define behavior for structurally mismatched inputs #9 — BezierPath.interpolate contract for structurally mismatched inputs

---

Generated by Claude Code

[gemini-code-assist]

Code Review

This pull request introduces the SwiftUI-based ManimView player and a comprehensive demo scene to showcase Phase 1 features, alongside updated documentation and tests. Feedback on the implementation highlights several key areas for improvement: resetting anchorDate on view appearance to prevent premature timeline progression, removing redundant background fills in the canvas to reduce overdraw, guarding against zero or negative dimensions in frameSize to avoid division-by-zero errors, and clamping stroke path bounds to prevent rendering artifacts during overshoot animations.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Initializing @State private var anchorDate = Date() at the property declaration level means the date is captured when the ManimView struct is first instantiated. In SwiftUI, view structs can be created well before they are actually displayed on screen (e.g., when pre-rendering in a navigation stack, tab view, or parent view update).

When the view finally appears and starts playing, anchorDate will be in the past, causing the animation to instantly skip forward by that time difference (or skip the entire animation if the delay was longer than the duration).

To fix this, we should reset anchorDate to the current time when the view actually appears on screen.

        .background(uiColor(background))
        .onAppear {
            if isPlaying {
                anchorDate = Date()
            }
        }
    }

[ronaldmannak]

Fixed in caf2a65 ("Address review: re-anchor clock on appear, canvas guards, trim clamps"): added the suggested .onAppear that re-anchors anchorDate when autoplay is on, so a view instantiated before display doesn't start partway through (or past) the scene. Not unit-testable (needs a real SwiftUI lifecycle); noted in the PR description's test-strategy caveat and verified via the preview.

---

Generated by Claude Code

[gemini-code-assist]

This consolidated change addresses two opportunities for improvement:

1. Redundant Background Fill (Overdraw): The Canvas is filling its entire bounds with the background color on every frame, which is redundant because the parent view already has the background color set via .background(uiColor(background)) on line 68. Removing this fill reduces overdraw and improves rendering performance.
2. Defensive Guard: If a user passes a custom frameSize with a width (x) or height (y) of zero or less, the scale calculation on line 110 will result in Infinity or NaN. Adding a guard ensures we handle this safely.

        Canvas { context, size in
            guard size.width > 0, size.height > 0, frameSize.x > 0, frameSize.y > 0 else { return }

[ronaldmannak]

Fixed in caf2a65, both parts: the per-frame background fill is gone (the view's .background already covers the canvas), and the guard now also rejects non-positive frameSize components so the scale can't become infinite or NaN.

---

Generated by Claude Code

[gemini-code-assist]

SwiftUI's Path.trimmedPath(from:to:) expects values strictly within the range 0...1. If an easing function with overshoot (such as backIn or custom spring-like rate functions) drives strokeStart or strokeEnd slightly below 0 or above 1, trimmedPath can produce rendering artifacts or unexpected behavior.

We should clamp these values to 0...1 before passing them to trimmedPath.

Suggested change

	if mobject.strokeStart > 0 || mobject.strokeEnd < 1 {
	strokePath = path.trimmedPath(
	from: CGFloat(mobject.strokeStart),
	to: CGFloat(mobject.strokeEnd)
	)
	}
	if mobject.strokeStart > 0 || mobject.strokeEnd < 1 {
	strokePath = path.trimmedPath(
	from: CGFloat(clamp(mobject.strokeStart, 0...1)),
	to: CGFloat(clamp(mobject.strokeEnd, 0...1))
	)
	}

[ronaldmannak]

Fixed in caf2a65: trimmedPath bounds are clamped to 0...1 exactly as suggested. Belt-and-suspenders with PR #3's clamped effective alphas — strokeStart/strokeEnd themselves can still exceed the range under overshooting custom rates, so the renderer clamps at the boundary it owns.

---

Generated by Claude Code

[ronaldmannak]

@codex review

---

Generated by Claude Code

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. You're on a roll.

Reviewed commit: 6c1ae2e858

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ronaldmannak]

Ready for human review/merge.

Checklist:

• ✅ CI green on latest commit 6c1ae2e (test-macos + test-linux; demo-scene timeline tests run headlessly on both, and the Linux job proves the #if canImport(SwiftUI) fence holds)
• ✅ Codex reviewed latest commit: "Didn't find any major issues"
• ✅ All 3 Gemini review comments addressed and individually answered: onAppear clock re-anchoring, removed redundant canvas background fill + non-positive frameSize guard, clamped trimmedPath bounds — fixed in the "re-anchor clock on appear, canvas guards, trim clamps" commit (now 6c1ae2e after rebase)
• ✅ Rebased on Phase 1 (4/5): Animation timeline — rate functions, animations, ManimScene #4's latest (including its create/fade composition fixes)
• ✅ Deferred work tracked in linked issues: Phase 2 umbrella: text/LaTeX mobjects, groups, axes, updaters, video export #6 (Phase 2 umbrella), Morph quality: arc-length-based path resampling for transform alignment #7 (arc-length morph resampling), ManimView: cache converted SwiftUI Paths across frames #8 (renderer path caching), BezierPath.interpolate: define behavior for structurally mismatched inputs #9 (interpolate contract)

Remaining notes:

• Merge order: last in the stack (after Phase 1 (1/5): Package scaffold, CI, and core math layer #1→Phase 1 (4/5): Animation timeline — rate functions, animations, ManimScene #4); I'll retarget the base to main as parents merge.
• Known limitation, stated in the description: Canvas rendering itself has no pixel-level unit tests — playback/scene logic is CI-tested, visual output is verified via #Preview on a Mac. A quick human look at the demo scene in Xcode Previews is the recommended final check.
• No @unchecked Sendable; the only mutable state in the package is this view's @State.

---

Generated by Claude Code

[ronaldmannak]

Head refresh note: this branch was rebased several times as #2–#4 absorbed review fixes; its own diff is unchanged since Codex's clean review (only the README shape-table row and the demo scene inherit upstream behavior fixes). Current head 9cb42b9, CI green on it. The earlier "Ready for human review/merge" checklist stands.

---

Generated by Claude Code