add pause flag

[GeorgeHastings]

The Scene class has a bool pause attribute which can be toggled. This introduces that flag to the component so the user can pause and unpause the scene's rendering.

Summary by CodeRabbit

Release Notes

• New Features
  • Added the ability to pause and resume scene animation.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds a new paused prop to the UnicornScene component across both React and Next.js implementations. The prop is wired through type definitions, constants, and the useUnicornScene hook, which includes a new effect that synchronizes the paused state with the underlying scene reference.

Changes

Cohort / File(s)	Summary
Type Definitions & Constants src/shared/types.ts, src/shared/constants.ts	Added optional paused?: boolean property to UnicornSceneProps interface and paused: false to DEFAULT_VALUES constant.
Hook Implementation src/shared/hooks.ts	Extended UseUnicornSceneParams interface with paused?: boolean parameter. Introduced new effect that synchronizes external paused state with scene reference via sceneRef.current.paused.
Component Integration src/react/index.tsx, src/next/index.tsx	Added paused prop to UnicornScene component signatures with DEFAULT_VALUES fallback; threaded prop to useUnicornScene hook invocation.
Documentation README.md	Added paused prop to public API documentation table with boolean type and false default value.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• Next.js + App Router Mounting Bugfix #11 — Modifies the same useUnicornScene hook with changes to initialization concurrency and lifecycle logic.

Suggested reviewers

• diegopeixoto

Poem

🦄 A pause button for our magical friend,
Now scenes can rest without end!
Through hooks and props it smoothly flows,
Animation paused wherever it goes. ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'add pause flag' directly and clearly summarizes the main change: adding a pause flag to the React component to control scene rendering.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

src/shared/hooks.ts (1)

239-244: Consider setting initial paused state immediately after scene creation to eliminate a brief visual timing gap.

If paused is initially true, the scene briefly renders unpaused (when created at line 162) before the effect (lines 239-244) runs and pauses it. Set the initial state right after assignment to avoid this:

if (scene) {
  sceneRef.current = scene;
  if (paused !== undefined) {
    scene.paused = paused;
  }
  hasAttemptedRef.current = false;
  setInitError(null);
  isInitializingRef.current = false;
  onLoad?.();
}

The existing effect will continue to handle subsequent paused prop changes.

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 89ad625 and 0542413.

📒 Files selected for processing (6)

• README.md
• src/next/index.tsx
• src/react/index.tsx
• src/shared/constants.ts
• src/shared/hooks.ts
• src/shared/types.ts

🧰 Additional context used

🧬 Code graph analysis (2)

src/next/index.tsx (1)

src/shared/constants.ts (1)

• DEFAULT_VALUES (8-21)

src/react/index.tsx (1)

src/shared/constants.ts (1)

• DEFAULT_VALUES (8-21)

🔇 Additional comments (6)

README.md (1)

213-213: LGTM! Documentation is clear and accurate.

The prop is properly documented with correct type and default value, consistent with the implementation.

src/shared/types.ts (1)

20-20: LGTM! Type addition is correct.

The optional paused property is properly added to UnicornSceneProps. Note that UnicornStudioScene interface (line 33) already includes paused?: boolean, which aligns well with this change.

src/react/index.tsx (1)

22-22: LGTM! Implementation mirrors the Next.js version.

The paused prop is correctly integrated following the same pattern as in src/next/index.tsx. The same verification regarding Unicorn Studio library support applies here.

Also applies to: 51-51

src/shared/constants.ts (1)

17-17: LGTM! Appropriate default value.

Setting paused: false as the default is correct—scenes should animate by default, with users opting in to pause behavior when needed.

src/next/index.tsx (1)

25-25: Verify that Unicorn Studio's Scene class supports a paused property.

The prop is correctly wired through the component to the useUnicornScene hook, where it's synced to the scene object at lines 240–244 of hooks.ts. However, the Unicorn Studio v2.0.1 documentation does not explicitly document a paused property on the Scene class. The UnicornSceneConfig interface also does not include this property, meaning it can only be set post-initialization via direct assignment (sceneRef.current.paused = paused). Please confirm with Unicorn Studio that this property exists and is supported in v2.0.1 to ensure it will work as intended.

src/shared/hooks.ts (1)

23-23: LGTM! Clean interface extension.

The paused property is correctly added as optional to the interface and properly destructured in the hook parameters.

Also applies to: 40-40

[diegopeixoto]

Lgtm