@pyreon/kinetic 0.21.0 → 0.23.0

package/README.md

@@ -1,149 +1,131 @@
 # @pyreon/kinetic
 
-CSS-first animation library for Pyreon. Enter/exit transitions, staggered animations, height collapse, and list reconciliation — all in ~3KB gzipped.
+CSS-transition animation library — enter/exit, stagger, collapse, list reconciliation, ~3KB.
 
-## Why Kinetic?
-
-Most animation libraries run their own JavaScript animation loop on the main thread. Kinetic takes a different approach: it delegates all interpolation to the browser's CSS transition engine (compositor thread for `transform`/`opacity`), and only handles orchestration — mount/unmount lifecycle, stagger timing, height measurement, and list diffing.
-
-The result: GPU-composited 60/120 FPS animations with a 3.2KB footprint.
-
-### How It Compares
-
-| Library                | Gzipped    | Engine              | Enter/Exit | Stagger | List Recon. | Collapse | Reduced Motion |
-| ---------------------- | ---------- | ------------------- | ---------- | ------- | ----------- | -------- | -------------- |
-| **@pyreon/kinetic**    | **3.2 KB** | CSS transitions     | Yes        | Yes     | Yes         | Yes      | Yes            |
-| Motion (framer-motion) | ~34 KB     | JS (rAF + WAAPI)    | Yes        | Yes     | Yes         | Quirky   | Yes            |
-| @react-spring/web      | ~16-24 KB  | JS (spring physics) | Yes        | Partial | Yes         | Manual   | Yes            |
-| react-transition-group | ~5 KB      | CSS classes         | Yes        | No      | Yes         | No       | No             |
-| AutoAnimate            | ~2.5 KB    | JS (FLIP)           | Yes        | No      | Yes         | No       | Yes            |
-
-**Key advantages:**
-
-- **10x smaller than Motion** for CSS-transition use cases
-- **CSS-first**: `transform`/`opacity` run on GPU compositor thread, not main thread
-- **Only library** combining CSS transitions + stagger + collapse + list reconciliation
-- **122 presets** available via `@pyreon/kinetic-presets`
+`@pyreon/kinetic` delegates interpolation to the browser's CSS transition engine (GPU compositor thread for `transform` / `opacity`) and only handles orchestration: mount/unmount lifecycle, stagger timing, height measurement, and key-based list diffing. The result is 60/120fps animations with a 3.2KB footprint and four composable modes (transition, collapse, stagger, group) accessed through a chainable, immutable API. Pair with `@pyreon/kinetic-presets` for 120+ ready-made animations, or define your own via inline `.enter()` / `.enterTo()` styles or class-based transitions (Tailwind, CSS modules). Reduced-motion is detected automatically; SSR renders children in their hidden-state class so scroll-reveal patterns reach SEO crawlers.
 
 ## Install
 
 ```bash
-bun add @pyreon/kinetic
+bun add @pyreon/kinetic @pyreon/core @pyreon/reactivity @pyreon/runtime-dom
 ```
 
-## Quick Start
+## Quick start
 
-```ts
+```tsx
 import { kinetic, fade, slideUp } from '@pyreon/kinetic'
 import { signal } from '@pyreon/reactivity'
 
-// Create animated components at module level
 const FadeDiv = kinetic('div').preset(fade)
 const SlideSection = kinetic('section').preset(slideUp)
 
-// Use with signals for reactive show/hide
 const show = signal(true)
-
-FadeDiv({ show: show(), children: 'Hello, world!' })
+<FadeDiv show={show()}>Hello, world!</FadeDiv>
 ```
 
-## API
+## How it compares
 
-### `kinetic(tag)`
+| Library                | Gzipped    | Engine              | Enter/Exit | Stagger | List Recon. | Collapse | Reduced Motion |
+| ---------------------- | ---------- | ------------------- | ---------- | ------- | ----------- | -------- | -------------- |
+| **@pyreon/kinetic**    | **3.2 KB** | CSS transitions     | Yes        | Yes     | Yes         | Yes      | Yes            |
+| Motion (framer-motion) | ~34 KB     | JS (rAF + WAAPI)    | Yes        | Yes     | Yes         | Quirky   | Yes            |
+| @react-spring/web      | ~16-24 KB  | JS (spring physics) | Yes        | Partial | Yes         | Manual   | Yes            |
+| react-transition-group | ~5 KB      | CSS classes         | Yes        | No      | Yes         | No       | No             |
+| AutoAnimate            | ~2.5 KB    | JS (FLIP)           | Yes        | No      | Yes         | No       | Yes            |
+
+Key advantages: 10x smaller than Motion for CSS-transition use cases; only library combining CSS transitions + stagger + collapse + key-based list reconciliation; 120+ presets via `@pyreon/kinetic-presets`.
 
-Creates an animated component. `tag` can be any HTML element string or Pyreon component.
+## `kinetic(tag)` — animated component factory
 
 ```ts
-kinetic('div') // HTML element
-kinetic('section') // Any HTML tag
-kinetic(MyComponent) // Pyreon component
+kinetic('div')           // HTML element string
+kinetic('section')
+kinetic(MyComponent)     // Any Pyreon component
 ```
 
-Returns a renderable Pyreon component with chain methods attached. Default mode: **transition**.
+Returns a renderable Pyreon component with chain methods. Default mode: **transition**.
 
-### Chain Methods
+## Chain methods
 
-All methods return a new component (immutable). The tag generic flows through, preserving HTML attribute types.
+Every method returns a new component (immutable). The tag generic flows through, preserving HTML attribute types.
 
 ```ts
-// Style-based animation config
-.enter(styles)            // CSSProperties applied at enter start
-.enterTo(styles)          // CSSProperties applied after first frame
-.enterTransition(value)   // CSS transition string for enter
-.leave(styles)            // CSSProperties applied at leave start
-.leaveTo(styles)          // CSSProperties applied after first frame
-.leaveTransition(value)   // CSS transition string for leave
-
-// Class-based animation config
+// Inline style-based config
+.enter(styles)            // CSSProperties at enter start
+.enterTo(styles)          // CSSProperties after first frame
+.enterTransition(value)   // CSS transition string
+.leave(styles)            // CSSProperties at leave start
+.leaveTo(styles)          // CSSProperties after first frame
+.leaveTransition(value)
+
+// Class-based config (Tailwind / CSS modules friendly)
 .enterClass({ active?, from?, to? })
 .leaveClass({ active?, from?, to? })
 
-// Apply a preset (spreads style + class props)
+// Preset (spreads style + class props)
 .preset(preset)
 
-// Behavior config
-.config(opts)             // appear, unmount, timeout (+ mode-specific)
-.on(callbacks)            // onEnter, onAfterEnter, onLeave, onAfterLeave
+// Behaviour
+.config({ appear, unmount, timeout, ... })
+.on({ onEnter, onAfterEnter, onLeave, onAfterLeave })
 
 // Mode switches
-.collapse(opts?)          // Height animation mode
-.stagger(opts?)           // Staggered children mode
+.collapse(opts?)          // Height-animation mode
+.stagger(opts?)           // Staggered-children mode
 .group()                  // Key-based list reconciliation mode
 ```
 
-### Four Modes
+## Four modes
 
-#### Transition (default)
+### Transition (default)
 
-Single element enter/leave with CSS transitions.
+Single-element enter/leave with CSS transitions.
 
-```ts
+```tsx
 const FadeDiv = kinetic('div').preset(fade)
-
-FadeDiv({ show: isOpen, children: 'Content' })
+<FadeDiv show={isOpen}>Content</FadeDiv>
 ```
 
-#### Collapse
+### Collapse
 
 Height animation with `overflow: hidden`. Measures `scrollHeight` automatically.
 
-```ts
+```tsx
 const Accordion = kinetic('div').collapse()
 const FancyAccordion = kinetic('section').collapse({
   transition: 'height 400ms cubic-bezier(0.4, 0, 0.2, 1)',
 })
 
-Accordion({ show: isExpanded, children: 'Expandable content' })
+<Accordion show={isExpanded}>Expandable content</Accordion>
 ```
 
-#### Stagger
+### Stagger
 
 Staggered entrance/exit for child elements.
 
-```ts
+```tsx
 const StaggerList = kinetic('ul').preset(slideUp).stagger({ interval: 75 })
 
-StaggerList({
-  show: isVisible,
-  children: [
-    h('li', { key: '1' }, 'Item 1'),
-    h('li', { key: '2' }, 'Item 2'),
-    h('li', { key: '3' }, 'Item 3'),
-  ],
-})
+<StaggerList show={isVisible}>
+  <li key="1">Item 1</li>
+  <li key="2">Item 2</li>
+  <li key="3">Item 3</li>
+</StaggerList>
 ```
 
-#### Group
+### Group
 
-Key-based enter/exit — adding a child triggers enter animation, removing triggers leave + unmount. No `show` prop.
+Key-based enter/exit — adding a keyed child triggers enter; removing triggers leave + unmount. No `show` prop.
 
-```ts
+```tsx
 const AnimatedList = kinetic('ul').preset(fade).group()
 
-AnimatedList({ children: items.map((item) => h('li', { key: item.id }, item.text)) })
+<AnimatedList>
+  {items.map((item) => <li key={item.id}>{item.text}</li>)}
+</AnimatedList>
 ```
 
-### Inline Configuration
+## Inline configuration
 
 Build animations without presets:
 
@@ -157,7 +139,7 @@ const SlidePanel = kinetic('aside')
   .leaveTransition('all 200ms ease-in')
 ```
 
-### Class-Based Transitions
+## Class-based transitions
 
 Works with Tailwind CSS, CSS modules, or any class-based approach:
 
@@ -167,79 +149,85 @@ const TailwindFade = kinetic('div')
   .leaveClass({ active: 'transition-opacity duration-200', from: 'opacity-100', to: 'opacity-0' })
 ```
 
-### Lifecycle Callbacks
+## Lifecycle callbacks
 
-```ts
-FadeDiv({
-  show: isOpen,
-  onEnter: () => console.log('entering'),
-  onAfterEnter: () => console.log('entered'),
-  onLeave: () => console.log('leaving'),
-  onAfterLeave: () => console.log('left'),
-  children: 'Content',
-})
+```tsx
+<FadeDiv
+  show={isOpen}
+  onEnter={() => console.log('entering')}
+  onAfterEnter={() => console.log('entered')}
+  onLeave={() => console.log('leaving')}
+  onAfterLeave={() => console.log('left')}
+>
+  Content
+</FadeDiv>
 ```
 
-### Accessibility
+## Composition with rocketstyle
 
-Kinetic automatically detects `prefers-reduced-motion: reduce`. When enabled, animations are skipped instantly — callbacks still fire, but no visual animation occurs. No configuration needed.
+Kinetic and rocketstyle compose naturally:
 
-## Built-in Presets
+```ts
+import rocketstyle from '@pyreon/rocketstyle'
 
-Six presets are included in the core package:
+const Button = rocketstyle()({ component: 'button', name: 'Button' })
+  .theme({ primaryColor: 'blue' })
 
-```ts
-import { fade, scaleIn, slideUp, slideDown, slideLeft, slideRight } from '@pyreon/kinetic'
+const AnimatedButton = kinetic(Button).preset(fade)
+// Has BOTH rocketstyle dimension props AND kinetic show/lifecycle props
+<AnimatedButton show={isVisible} state="primary" size="large">Click me</AnimatedButton>
 ```
 
-For 122 presets, factories, and composition utilities, install `@pyreon/kinetic-presets`.
+## Built-in presets
 
-## Composition with Rocketstyle
+Six presets are included in the core package: `fade`, `scaleIn`, `slideUp`, `slideDown`, `slideLeft`, `slideRight`. For 120+ presets, factories, and composition utilities, add `@pyreon/kinetic-presets`.
 
-Kinetic and rocketstyle compose naturally:
+## Low-level hooks
+
+If you need transition state outside `kinetic()`:
 
 ```ts
-import rocketstyle from '@pyreon/rocketstyle'
+import { useTransitionState, useAnimationEnd } from '@pyreon/kinetic'
 
-const Button = rocketstyle()({ component: 'button', name: 'Button' }).theme({
-  primaryColor: 'blue',
-})
+const state = useTransitionState({ show: () => isOpen() })
+// state.stage() → 'enter' | 'enter-active' | 'enter-to' | 'leave' | 'leave-active' | 'leave-to' | 'idle'
+```
 
-const AnimatedButton = kinetic(Button).preset(fade)
+## Accessibility
 
-// Has both rocketstyle props AND kinetic props
-AnimatedButton({ show: isVisible, primary: true, size: 'large', children: 'Click me' })
-```
+Kinetic automatically detects `prefers-reduced-motion: reduce`. When enabled, animations are skipped instantly — callbacks still fire, but no visual animation occurs. No configuration needed.
 
 ## SSR / SSG
 
 `<Transition show={() => false}>` **always renders children in SSR**, with the hidden-state class inlined (`leaveTo` if defined, else `enterFrom`). This matches Framer Motion / react-transition-group / react-spring conventions: content is structural, animation is visual.
 
-This is load-bearing for the scroll-reveal pattern on SSG sites — `useIntersection` can't fire on the server, so `show` is false at SSR. Without structural rendering, the wrapped content would be absent from prerendered HTML (bad for SEO, social scrapers, no-JS users).
+Load-bearing for scroll-reveal on SSG sites — `useIntersection` can't fire on the server, so `show` is false at SSR. Without structural rendering, the wrapped content would be absent from prerendered HTML (bad for SEO, social scrapers, no-JS users).
 
 ```tsx
 const RevealSection = kinetic('section')
-  .enter('transition-all duration-700')
-  .enterFrom('opacity-0 translate-y-8') // ← this IS the SSR hidden state
-  .enterTo('opacity-100 translate-y-0')
+  .enterClass({ active: 'transition-all duration-700', from: 'opacity-0 translate-y-8', to: 'opacity-100 translate-y-0' })
 
-// In your route — show is driven by useIntersection on the client.
-// At SSR: <section class="opacity-0 translate-y-8">…full content here…</section>
-// On client: when scrolled into view, show flips true, enter animation runs.
+// SSR: <section class="opacity-0 translate-y-8">…full content…</section>
+// Client: when scrolled into view, show flips true → enter animation runs
 <RevealSection show={isInView}>
   <h2>Work Experience</h2>
   <p>…content reaches SEO crawlers and social scrapers…</p>
 </RevealSection>
 ```
 
-**Trade-off**: for an initially-hidden Transition, `unmount: true` (the default) no longer triggers a true DOM removal after a later leave animation completes — the element stays in DOM with the leave-to class applied. **Initially-visible** Transitions (`show: () => true` at setup) keep the runtime-unmount semantic unchanged. If you need true unmount on a started-hidden element, drive mount/unmount yourself outside `<Transition>`.
+**Trade-off**: for an initially-hidden Transition, `unmount: true` (the default) no longer triggers a true DOM removal after a later leave animation completes — the element stays in DOM with the leave-to class applied. **Initially-visible** Transitions keep the runtime-unmount semantic unchanged. If you need true unmount on a started-hidden element, drive mount/unmount yourself outside `<Transition>`.
+
+## Gotchas
+
+- **Animations run on the GPU compositor thread** only when you animate `transform` / `opacity` / `filter`. Animating `width` / `height` / `top` / `left` falls back to the main thread and may jank.
+- **Stagger `interval` is per-CHILD**, not total duration. Five children at 75ms = 375ms total stagger window.
+- **Group mode requires keyed children.** Without `key=`, every render replaces every child and you get no animation. The compiler-suggested `<For each={items} by={i => i.id}>` is the idiomatic pattern.
+- **SSR initial-hidden Transitions break true-unmount semantics.** See SSR / SSG section above — opt out by driving mount/unmount yourself.
+- **Reduced-motion skips visuals but still fires callbacks.** Don't rely on the animation completing for state machine progression — use callbacks.
 
-## Peer Dependencies
+## Documentation
 
-| Package            | Version  |
-| ------------------ | -------- |
-| @pyreon/core       | >= 0.0.1 |
-| @pyreon/reactivity | >= 0.0.1 |
+Full docs: [docs.pyreon.dev/docs/kinetic](https://docs.pyreon.dev/docs/kinetic) (or `docs/docs/kinetic.md` in this repo).
 
 ## License
 

package/lib/index.js

@@ -1,4 +1,4 @@
-import { Show, createRef, h, mergeProps, onMount, onUnmount, splitProps } from "@pyreon/core";
+import { Show, createRef, cx, h, mergeProps, onMount, onUnmount, splitProps } from "@pyreon/core";
 import { runUntracked, signal, watch } from "@pyreon/reactivity";
 import { jsx } from "@pyreon/core/jsx-runtime";
 
@@ -172,16 +172,20 @@ const CollapseRenderer = ({ config, htmlProps, show, appear, timeout, transition
 		...stage() !== "entered" ? { overflow: "hidden" } : {},
 		...stage() === "hidden" ? { height: "0px" } : stage() === "entered" ? { height: "auto" } : {}
 	};
-	return h(config.tag, mergeProps(htmlProps, {
-		ref: wrapperRef,
-		style: wrapperStyle
-	}), /* @__PURE__ */ jsx(Show, {
+	const innerContent = show() ? /* @__PURE__ */ jsx(Show, {
 		when: shouldRender,
 		children: /* @__PURE__ */ jsx("div", {
 			ref: contentRef,
 			children
 		})
-	}));
+	}) : /* @__PURE__ */ jsx("div", {
+		ref: contentRef,
+		children
+	});
+	return h(config.tag, mergeProps(htmlProps, {
+		ref: wrapperRef,
+		style: wrapperStyle
+	}), innerContent);
 };
 
 //#endregion
@@ -286,10 +290,39 @@ const cloneVNode = (vnode, extraProps) => ({
 		...extraProps
 	}
 });
+/**
+* Resolves a `children` value the Pyreon compiler may have wrapped in a
+* deferred accessor.
+*
+* **Why:** the compiler's prop-inlining pass rewrites `<Comp>{children}</Comp>`
+* to `Comp({ ..., children: () => <inlined-expression> })` whenever
+* `children` is a local `const` derived from a getter-shaped binding
+* (`const children = childHolder.children` after `splitProps`). DOM-side
+* consumers route through `mountChild` which already treats function
+* children as reactive accessors, so the wrap is invisible there. Kinetic's
+* Stagger/Group/Transition/Collapse renderers iterate `children` directly
+* at the VNode level (to build per-child `TransitionItem`s), so a wrapped
+* function landed in `Array.isArray(children) ? children : [children]` as
+* `[function]` → `.filter(isVNode)` → `[]` → the rendered `<div>` had zero
+* children → SSR content vanished post-hydration. Reproducer:
+* `examples/bokisch.com`'s Intro section with `kinetic('div').stagger()`
+* + `appear` + `show={() => true}` + component children → SSG HTML had
+* `<h1>Hello</h1>`, post-hydrate the entire subtree was replaced by
+* `<!--pyreon-->` markers.
+*
+* Kinetic deliberately snapshots children at render time (animation state
+* is per-item, built once) — it does NOT observe children changes after
+* the initial render. Eagerly unwrapping the function matches that
+* contract; no reactivity is lost.
+*/
+const resolveChildren = (children) => typeof children === "function" ? children() : children;
 
 //#endregion
 //#region src/kinetic/TransitionItem.tsx
 const applyEnter$1 = (el, config) => {
+	removeClasses(el, config.leave);
+	removeClasses(el, config.leaveFrom);
+	removeClasses(el, config.leaveTo);
 	addClasses(el, config.enter);
 	addClasses(el, config.enterFrom);
 	if (config.enterStyle) Object.assign(el.style, config.enterStyle);
@@ -331,6 +364,7 @@ const applyReducedMotion$1 = (stage, callbacks, complete) => {
 * Uses cloneVNode to inject ref onto the child — the child must accept ref.
 */
 const TransitionItem = (props) => {
+	const child = resolveChildren(props.children);
 	const appear = props.appear ?? false;
 	const unmount = props.unmount ?? true;
 	const timeout = props.timeout ?? 5e3;
@@ -340,7 +374,7 @@ const TransitionItem = (props) => {
 		appear
 	});
 	const elementRef = createRef();
-	const mergedRef = mergeRefs(elementRef, stateRef, props.children.props?.ref);
+	const mergedRef = mergeRefs(elementRef, stateRef, (child?.props)?.ref);
 	const callbacks = {
 		onEnter: props.onEnter,
 		onAfterEnter: props.onAfterEnter,
@@ -393,14 +427,24 @@ const TransitionItem = (props) => {
 			el.style.transition = "";
 		}
 	}, { immediate: true });
-	return /* @__PURE__ */ jsx(Show, {
+	if (props.show()) return /* @__PURE__ */ jsx(Show, {
 		when: shouldMount,
-		fallback: unmount ? null : cloneVNode(props.children, {
+		fallback: unmount ? null : cloneVNode(child, {
 			ref: mergedRef,
-			style: mergeStyles(props.children.props?.style, { display: "none" })
+			style: mergeStyles((child?.props)?.style, { display: "none" })
 		}),
-		children: cloneVNode(props.children, { ref: mergedRef })
+		children: cloneVNode(child, { ref: mergedRef })
 	});
+	const hiddenClass = props.leaveTo ?? props.enterFrom;
+	const hiddenStyle = props.leaveToStyle ?? props.enterStyle;
+	const childProps = child?.props ?? {};
+	const childClass = childProps.class;
+	const mergedClass = hiddenClass ? cx([childClass, hiddenClass]) : void 0;
+	const mergedStyle = mergeStyles(childProps.style, hiddenStyle);
+	const extra = { ref: mergedRef };
+	if (mergedClass !== void 0) extra.class = mergedClass;
+	if (mergedStyle !== void 0) extra.style = mergedStyle;
+	return cloneVNode(child, extra);
 };
 
 //#endregion
@@ -495,7 +539,8 @@ const StaggerRenderer = ({ config, htmlProps, show, appear, timeout, interval, r
 	const effectiveTimeout = timeout ?? config.timeout ?? 5e3;
 	const effectiveInterval = interval ?? config.interval ?? 50;
 	const effectiveReverseLeave = reverseLeave ?? config.reverseLeave ?? false;
-	const childArray = (Array.isArray(children) ? children : [children]).filter(isVNode);
+	const resolved = resolveChildren(children);
+	const childArray = (Array.isArray(resolved) ? resolved : [resolved]).filter(isVNode);
 	const count = childArray.length;
 	const staggeredChildren = childArray.map((child, index) => {
 		const staggerIndex = !show() && effectiveReverseLeave ? count - 1 - index : index;
@@ -531,6 +576,9 @@ const StaggerRenderer = ({ config, htmlProps, show, appear, timeout, interval, r
 //#endregion
 //#region src/kinetic/TransitionRenderer.tsx
 const applyEnter = (el, config) => {
+	removeClasses(el, config.leave);
+	removeClasses(el, config.leaveFrom);
+	removeClasses(el, config.leaveTo);
 	addClasses(el, config.enter);
 	addClasses(el, config.enterFrom);
 	if (config.enterStyle) Object.assign(el.style, config.enterStyle);
@@ -610,7 +658,7 @@ const TransitionRenderer = (props) => {
 			el.style.transition = "";
 		}
 	}, { immediate: true });
-	return /* @__PURE__ */ jsx(Show, {
+	if (props.show()) return /* @__PURE__ */ jsx(Show, {
 		when: shouldMount,
 		fallback: effectiveUnmount ? null : h(props.config.tag, mergeProps(props.htmlProps, {
 			ref: mergedRef,
@@ -621,6 +669,18 @@ const TransitionRenderer = (props) => {
 		}), props.children),
 		children: h(props.config.tag, mergeProps(props.htmlProps, { ref: mergedRef }), props.children)
 	});
+	const hiddenClass = props.config.leaveTo ?? props.config.enterFrom;
+	const hiddenStyle = props.config.leaveToStyle ?? props.config.enterStyle;
+	const childClass = props.htmlProps.class;
+	const mergedClass = hiddenClass ? cx([childClass, hiddenClass]) : void 0;
+	const mergedStyle = hiddenStyle ? {
+		...props.htmlProps.style ?? {},
+		...hiddenStyle
+	} : void 0;
+	const extra = { ref: mergedRef };
+	if (mergedClass !== void 0) extra.class = mergedClass;
+	if (mergedStyle !== void 0) extra.style = mergedStyle;
+	return h(props.config.tag, mergeProps(props.htmlProps, extra), props.children);
 };
 
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/kinetic",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "CSS-transition-based animation components for Pyreon",
   "license": "MIT",
   "repository": {
@@ -42,21 +42,21 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@pyreon/core": "^0.21.0",
-    "@pyreon/reactivity": "^0.21.0",
-    "@pyreon/runtime-dom": "^0.21.0",
-    "@pyreon/runtime-server": "^0.21.0",
-    "@pyreon/test-utils": "^0.13.8",
-    "@pyreon/typescript": "^0.21.0",
+    "@pyreon/core": "^0.23.0",
+    "@pyreon/reactivity": "^0.23.0",
+    "@pyreon/runtime-dom": "^0.23.0",
+    "@pyreon/runtime-server": "^0.23.0",
+    "@pyreon/test-utils": "^0.13.10",
+    "@pyreon/typescript": "^0.23.0",
     "@vitest/browser-playwright": "^4.1.4",
-    "@vitus-labs/tools-rolldown": "^2.3.0"
+    "@vitus-labs/tools-rolldown": "^2.4.0"
   },
   "engines": {
     "node": ">= 22"
   },
   "dependencies": {
-    "@pyreon/core": "^0.21.0",
-    "@pyreon/reactivity": "^0.21.0",
-    "@pyreon/runtime-dom": "^0.21.0"
+    "@pyreon/core": "^0.23.0",
+    "@pyreon/reactivity": "^0.23.0",
+    "@pyreon/runtime-dom": "^0.23.0"
   }
 }

package/src/Stagger.tsx

@@ -2,7 +2,7 @@ import type { VNode } from '@pyreon/core'
 import { splitProps } from '@pyreon/core'
 import Transition from './Transition'
 import type { CSSProperties, StaggerProps } from './types'
-import { cloneVNode } from './utils'
+import { cloneVNode, resolveChildren } from './utils'
 
 const isVNode = (child: unknown): child is VNode =>
   child != null && typeof child === 'object' && 'type' in (child as object)
@@ -22,7 +22,12 @@ const Stagger = (props: StaggerProps): VNode | null => {
   const appear = own.appear ?? false
   const timeout = own.timeout ?? 5000
 
-  const childArray = (Array.isArray(own.children) ? own.children : [own.children]).filter(isVNode)
+  // Unwrap the compiler's `() => x` accessor wrap — see `resolveChildren`
+  // jsdoc. PR #731 fixed this on `StaggerRenderer` (the internal kinetic-
+  // mode renderer); this is the parallel fix for the top-level `<Stagger>`
+  // component, which has the same iteration shape and the same bug.
+  const resolved = resolveChildren(own.children)
+  const childArray = (Array.isArray(resolved) ? resolved : [resolved]).filter(isVNode)
   const count = childArray.length
 
   return (

package/src/Transition.tsx

@@ -5,7 +5,15 @@ import type { ClassTransitionProps, StyleTransitionProps, TransitionProps } from
 import useAnimationEnd from './useAnimationEnd'
 import { useReducedMotion } from './useReducedMotion'
 import useTransitionState from './useTransitionState'
-import { addClasses, cloneVNode, mergeRefs, mergeStyles, nextFrame, removeClasses } from './utils'
+import {
+  addClasses,
+  cloneVNode,
+  mergeRefs,
+  mergeStyles,
+  nextFrame,
+  removeClasses,
+  resolveChildren,
+} from './utils'
 
 const applyEnter = (
   el: HTMLElement,
@@ -109,8 +117,14 @@ const Transition = (props: TransitionProps): VNode | null => {
     appear,
   })
 
+  // Unwrap the compiler's `() => x` accessor wrap — see `resolveChildren`
+  // jsdoc. Parallel to `TransitionItem`'s fix (PR #731). Without this,
+  // `props.children.props` reads `function.props` (undefined), the merged
+  // ref is missing the child's own ref, and the downstream `cloneVNode`
+  // calls produce `{type: undefined}` → `<undefined>` DOM tags.
+  const child = resolveChildren(props.children) as VNode
   const elementRef = createRef<HTMLElement>()
-  const childProps = (props.children.props ?? {}) as Record<string, unknown>
+  const childProps = (child?.props ?? {}) as Record<string, unknown>
   const mergedRef = mergeRefs(
     elementRef,
     stateRef,
@@ -198,7 +212,7 @@ const Transition = (props: TransitionProps): VNode | null => {
         fallback={
           unmount
             ? null
-            : cloneVNode(props.children, {
+            : cloneVNode(child, {
                 ref: mergedRef,
                 style: mergeStyles(
                   childProps.style as Record<string, string | number | undefined> | undefined,
@@ -207,7 +221,7 @@ const Transition = (props: TransitionProps): VNode | null => {
               })
         }
       >
-        {cloneVNode(props.children, { ref: mergedRef })}
+        {cloneVNode(child, { ref: mergedRef })}
       </Show>
     )
   }
@@ -232,8 +246,18 @@ const Transition = (props: TransitionProps): VNode | null => {
   // The `watch(stage)` effect above drives the enter animation when
   // `show` flips true; `applyEnter` (above) clears these residual
   // hidden-state classes so they don't fight `enterTo`.
+  // Picker mirrors what #719 introduced for the kinetic(tag).<mode>
+  // renderers (TransitionRenderer / TransitionItem / CollapseRenderer):
+  // prefer leave-end state, fall back to pre-enter state. The
+  // `enterStyle` fallback covers the preset path — `@pyreon/kinetic-presets`
+  // factories (fadeUp, blurInUp, slideLeft, …) populate `enterStyle` as
+  // the hidden state but may not set `leaveToStyle`. Without this
+  // fallback, preset users SSR-render VISIBLE → flash-on-hydration.
+  // (PR #717 shipped this branch with `leaveToStyle` alone; the class
+  // picker already had the `enterFrom` fallback. This commit aligns the
+  // style picker so both halves match.)
   const hiddenClass = props.leaveTo ?? props.enterFrom
-  const hiddenStyle = props.leaveToStyle
+  const hiddenStyle = props.leaveToStyle ?? props.enterStyle
   const childClass = childProps.class
   const mergedClass = hiddenClass
     ? cx([childClass as Parameters<typeof cx>[0], hiddenClass])
@@ -250,7 +274,7 @@ const Transition = (props: TransitionProps): VNode | null => {
   if (mergedClass !== undefined) extra.class = mergedClass
   if (mergedStyle !== undefined) extra.style = mergedStyle
 
-  return cloneVNode(props.children, extra)
+  return cloneVNode(child, extra)
 }
 
 export default Transition