@pyreon/kinetic 0.22.0 → 0.24.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

@@ -290,6 +290,32 @@ 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
@@ -338,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;
@@ -347,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,
@@ -402,22 +429,22 @@ const TransitionItem = (props) => {
 	}, { immediate: true });
 	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 = props.children.props ?? {};
+	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(props.children, extra);
+	return cloneVNode(child, extra);
 };
 
 //#endregion
@@ -512,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/kinetic",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "CSS-transition-based animation components for Pyreon",
   "license": "MIT",
   "repository": {
@@ -42,21 +42,21 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@pyreon/core": "^0.22.0",
-    "@pyreon/reactivity": "^0.22.0",
-    "@pyreon/runtime-dom": "^0.22.0",
-    "@pyreon/runtime-server": "^0.22.0",
-    "@pyreon/test-utils": "^0.13.9",
-    "@pyreon/typescript": "^0.22.0",
+    "@pyreon/core": "^0.24.0",
+    "@pyreon/reactivity": "^0.24.0",
+    "@pyreon/runtime-dom": "^0.24.0",
+    "@pyreon/runtime-server": "^0.24.0",
+    "@pyreon/test-utils": "^0.13.11",
+    "@pyreon/typescript": "^0.24.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.22.0",
-    "@pyreon/reactivity": "^0.22.0",
-    "@pyreon/runtime-dom": "^0.22.0"
+    "@pyreon/core": "^0.24.0",
+    "@pyreon/reactivity": "^0.24.0",
+    "@pyreon/runtime-dom": "^0.24.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>
     )
   }
@@ -260,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

package/src/__tests__/stagger-component-children-hydration.test.tsx

@@ -0,0 +1,191 @@
+/** @jsxImportSource @pyreon/core */
+/**
+ * Regression: `kinetic('div').stagger()` with `show={() => true}` +
+ * `appear` + multiple component-VNode children rendered `<undefined>`
+ * tags in place of the children's actual DOM post-hydrate.
+ *
+ * Real-app reporter (examples/bokisch.com Intro section): SSG'd HTML
+ * carried `<h1>Hello</h1>` + tagline + icons; client hydration produced
+ * `<undefined></undefined>` tags (literal HTML element with tagName
+ * "UNDEFINED") + `<!--pyreon-->` markers in place of every child.
+ *
+ * Bug class — Pyreon-compiler prop-inlining + cloneVNode-on-a-function:
+ *
+ *   1. The compiler rewrites local `const children = obj.x` then
+ *      `<Comp>{children}</Comp>` as `Comp({..., children: () => obj.x})`.
+ *      Component receives `props.children` as a FUNCTION, not an array.
+ *
+ *   2. StaggerRenderer iterated `(Array.isArray(children) ? children : [children])`
+ *      directly. `[function].filter(isVNode)` collapsed to `[]` → the
+ *      kinetic `<div>` rendered with zero children.
+ *
+ *   3. Even after StaggerRenderer's fix, TransitionItem's `cloneVNode(props.children, {ref})`
+ *      tried to clone the same function-wrapped value (also auto-wrapped
+ *      by the compiler one level down — `{cloneVNode(child, {style})}`
+ *      became `() => cloneVNode(child, {style})`). Spreading a function
+ *      via `{...fn, props: {...}}` yields `{props: {...}}` (no own
+ *      enumerable properties on functions) — the resulting vnode had
+ *      `type: undefined`. mountElement called `document.createElement(undefined)`
+ *      → the browser produced literal `<undefined>` tags.
+ *
+ * Fix: `resolveChildren` helper in both StaggerRenderer (iteration) AND
+ * TransitionItem (cloning). Unwraps function-wrapped children eagerly
+ * since kinetic snapshots children at render time and does not observe
+ * children changes.
+ *
+ * Bisect-verified: reverting either `resolveChildren` call in this PR
+ * fails this spec — StaggerRenderer revert produces zero children in the
+ * kinetic `<div>`; TransitionItem revert produces `<undefined>` tags
+ * with the right cloned style.
+ */
+import type { VNode } from '@pyreon/core'
+import { h } from '@pyreon/core'
+import { mount } from '@pyreon/runtime-dom'
+import { afterEach, describe, expect, it } from 'vitest'
+import kinetic from '../kinetic'
+import TransitionItem from '../kinetic/TransitionItem'
+
+// Build a kinetic Component VNode whose `props.children` is a FUNCTION
+// (not an array), mirroring what the Pyreon vite-plugin emits when JSX
+// children are inlined back at the call site (`<Entrance>{children}</Entrance>`
+// → `jsx(Entrance, { children: () => h.children })`). The kinetic test
+// pipeline uses `vl_rolldown_build` which does NOT do Pyreon's
+// prop-inlining, so we construct the shape directly.
+const buildEntranceWithFunctionChildren = (
+  // Wider call signature — kinetic('div').stagger() returns a stagger-mode
+  // component whose precise typed shape (`KineticComponent<'div', 'stagger'>`)
+  // is narrower than what `kinetic()`'s default returns. The function-
+  // children wrapper bypasses the strict children-required typing.
+  Entrance: (props: Record<string, unknown>) => VNode | null,
+  childArray: VNode[],
+): VNode => {
+  // h() puts children in vnode.children (rest args). For mountComponent's
+  // merge to leave props.children alone, set it explicitly here.
+  return h(Entrance, {
+    show: () => true,
+    appear: true,
+    children: (() => childArray) as unknown as VNode[],
+  })
+}
+
+let containers: HTMLElement[] = []
+afterEach(() => {
+  for (const c of containers) c.remove()
+  containers = []
+})
+
+describe('kinetic("div").stagger() — function-wrapped children survive render', () => {
+  it('iterates function-wrapped children correctly (no <undefined> tags)', () => {
+    const Entrance = kinetic('div')
+      .enter({ opacity: '0' })
+      .enterTo({ opacity: '1' })
+      .stagger({ interval: 20 })
+
+    const tree = buildEntranceWithFunctionChildren(Entrance as never, [
+      h('h1', { 'data-id': 'heading' }, 'Hello'),
+      h('p', { 'data-id': 'tagline' }, 'tagline'),
+      h('ul', { 'data-id': 'icons' }, h('li', null, 'icon-a')),
+    ])
+
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+    containers.push(container)
+
+    const dispose = mount(tree as VNode, container)
+
+    // Children are rendered with proper element tags — NOT <undefined>
+    const heading = container.querySelector('[data-id="heading"]')
+    const tagline = container.querySelector('[data-id="tagline"]')
+    const icons = container.querySelector('[data-id="icons"]')
+
+    expect(
+      heading,
+      `heading missing — pre-fix the function-wrapped child got mounted as <undefined>. ` +
+        `container.innerHTML=${container.innerHTML.slice(0, 600)}`,
+    ).not.toBeNull()
+    expect(heading?.tagName).toBe('H1')
+    expect(heading?.textContent).toBe('Hello')
+
+    expect(tagline).not.toBeNull()
+    expect(tagline?.tagName).toBe('P')
+
+    expect(icons).not.toBeNull()
+    expect(icons?.tagName).toBe('UL')
+
+    // Sanity: no `<undefined>` tags should exist anywhere (pre-fix
+    // TransitionItem's cloneVNode(props.children, {ref}) on a function
+    // produced `{type: undefined, props: {ref}}` → mountElement called
+    // document.createElement(undefined) → `<undefined>` element).
+    expect(container.querySelector('undefined')).toBeNull()
+
+    dispose()
+  })
+
+  it('TransitionItem resolves function-wrapped children before cloneVNode (no <undefined> tag)', () => {
+    // Direct test for the SECOND fix-site — TransitionItem's
+    // `cloneVNode(props.children, {ref})`. Pre-fix, when the parent
+    // (StaggerRenderer/GroupRenderer) emits `<TransitionItem>{cloneVNode(c, {style})}</TransitionItem>`
+    // under the Pyreon vite-plugin, the compiler wraps the JSX child as
+    // `() => cloneVNode(c, {style})`. TransitionItem then receives
+    // `props.children = function`. `cloneVNode(function, {ref})` spreads
+    // the function (no own enumerable properties) → produces
+    // `{type: undefined, props: {ref}}` → mountElement creates literal
+    // `<undefined>` tag.
+    const childVNode = h('h1', { 'data-id': 'ti-heading' }, 'Hello')
+    const tree = h(TransitionItem, {
+      show: () => true,
+      appear: false,
+      timeout: 100,
+      enterStyle: { opacity: '0' },
+      enterToStyle: { opacity: '1' },
+      enterTransition: 'opacity 50ms ease',
+      // Function-wrapped children, mirroring the compiler's emit.
+      children: (() => childVNode) as unknown as VNode,
+    })
+
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+    containers.push(container)
+
+    const dispose = mount(tree as VNode, container)
+
+    const heading = container.querySelector('[data-id="ti-heading"]')
+    expect(
+      heading,
+      `heading missing — pre-fix TransitionItem cloned the function, ` +
+        `producing <undefined>. container.innerHTML=${container.innerHTML.slice(0, 400)}`,
+    ).not.toBeNull()
+    expect(heading?.tagName).toBe('H1')
+    expect(heading?.textContent).toBe('Hello')
+    expect(container.querySelector('undefined')).toBeNull()
+
+    dispose()
+  })
+
+  it('iterates static-array children correctly (control — was always working)', () => {
+    const Entrance = kinetic('div')
+      .enter({ opacity: '0' })
+      .enterTo({ opacity: '1' })
+      .stagger({ interval: 20 })
+
+    // No compiler wrap — children as a plain array.
+    const tree = h(
+      Entrance,
+      { show: () => true, appear: true },
+      h('h1', { 'data-id': 'heading-static' }, 'Static'),
+      h('p', { 'data-id': 'tagline-static' }, 't'),
+    )
+
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+    containers.push(container)
+
+    const dispose = mount(tree as VNode, container)
+
+    expect(container.querySelector('[data-id="heading-static"]')?.tagName).toBe('H1')
+    expect(container.querySelector('[data-id="tagline-static"]')?.tagName).toBe('P')
+    expect(container.querySelector('undefined')).toBeNull()
+
+    dispose()
+  })
+})

package/src/__tests__/top-level-transition-stagger-function-children.test.tsx

@@ -0,0 +1,141 @@
+/** @jsxImportSource @pyreon/core */
+/**
+ * Regression: PR #731 fixed the kinetic-mode renderers (StaggerRenderer +
+ * TransitionItem under `src/kinetic/`) but missed the parallel TOP-LEVEL
+ * `<Transition>` and `<Stagger>` components in `src/Transition.tsx` and
+ * `src/Stagger.tsx`. They have the SAME iteration + cloneVNode shape and
+ * the SAME bug when the Pyreon compiler wraps the children prop in
+ * `() => x` (the prop-inlining pass).
+ *
+ * The Pyreon vite-plugin auto-wraps `<Comp>{x}</Comp>` JSX child
+ * expressions in `() => x` for stable prop-derived references; downstream
+ * libraries that iterate `props.children` directly at the VNode level or
+ * `cloneVNode` them silently break — the function spread produces
+ * `{type: undefined}` → `<undefined>` DOM tags. PR #732 added the
+ * compiler carve-out for stable references; library-side `resolveChildren`
+ * is still needed for the CallExpression-inside-JSX-child shape that the
+ * compiler (correctly) doesn't optimize.
+ *
+ * Bisect-verified: reverting the `resolveChildren` call in `Stagger.tsx`
+ * fails the Stagger spec (no children rendered); reverting in
+ * `Transition.tsx` fails the Transition spec (`<undefined>` tag rendered
+ * instead of the cloned child).
+ */
+import type { VNode } from '@pyreon/core'
+import { h } from '@pyreon/core'
+import { mount } from '@pyreon/runtime-dom'
+import { afterEach, describe, expect, it } from 'vitest'
+import Stagger from '../Stagger'
+import Transition from '../Transition'
+
+let containers: HTMLElement[] = []
+afterEach(() => {
+  for (const c of containers) c.remove()
+  containers = []
+})
+
+describe('top-level <Stagger> — function-wrapped children survive render', () => {
+  it('iterates function-wrapped children correctly (no empty render)', () => {
+    const childArray: VNode[] = [
+      h('h1', { 'data-id': 'st-h1' }, 'Hello'),
+      h('p', { 'data-id': 'st-p' }, 'tagline'),
+      h('ul', { 'data-id': 'st-ul' }, h('li', null, 'a')),
+    ]
+
+    const tree = h(Stagger, {
+      show: () => true,
+      appear: true,
+      interval: 20,
+      // Compiler-emitted shape: children is a function returning the array.
+      children: (() => childArray) as unknown as VNode[],
+    })
+
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+    containers.push(container)
+
+    const dispose = mount(tree as VNode, container)
+
+    const h1 = container.querySelector('[data-id="st-h1"]')
+    const p = container.querySelector('[data-id="st-p"]')
+    const ul = container.querySelector('[data-id="st-ul"]')
+
+    expect(
+      h1,
+      `Stagger collapsed when children is a function — html=${container.innerHTML.slice(0, 400)}`,
+    ).not.toBeNull()
+    expect(h1?.tagName).toBe('H1')
+    expect(h1?.textContent).toBe('Hello')
+    expect(p?.tagName).toBe('P')
+    expect(ul?.tagName).toBe('UL')
+    expect(container.querySelector('undefined')).toBeNull()
+
+    dispose()
+  })
+
+  it('static-array children control — was always working', () => {
+    const tree = h(
+      Stagger,
+      { show: () => true, appear: true, interval: 20 },
+      h('h1', { 'data-id': 'st-static' }, 'Static'),
+      h('p', { 'data-id': 'st-static-p' }, 't'),
+    )
+
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+    containers.push(container)
+    const dispose = mount(tree as VNode, container)
+
+    expect(container.querySelector('[data-id="st-static"]')?.tagName).toBe('H1')
+    expect(container.querySelector('[data-id="st-static-p"]')?.tagName).toBe('P')
+
+    dispose()
+  })
+})
+
+describe('top-level <Transition> — function-wrapped children survive render', () => {
+  it('resolves function-wrapped children before cloneVNode (no <undefined> tag)', () => {
+    const childVNode = h('h1', { 'data-id': 'tn-h1' }, 'Hello')
+
+    const tree = h(Transition, {
+      show: () => true,
+      appear: false,
+      // Compiler-emitted shape.
+      children: (() => childVNode) as unknown as VNode,
+    })
+
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+    containers.push(container)
+
+    const dispose = mount(tree as VNode, container)
+
+    const h1 = container.querySelector('[data-id="tn-h1"]')
+    expect(
+      h1,
+      `Transition produced <undefined> — html=${container.innerHTML.slice(0, 400)}`,
+    ).not.toBeNull()
+    expect(h1?.tagName).toBe('H1')
+    expect(h1?.textContent).toBe('Hello')
+    expect(container.querySelector('undefined')).toBeNull()
+
+    dispose()
+  })
+
+  it('static-VNode child control — was always working', () => {
+    const tree = h(
+      Transition,
+      { show: () => true, appear: false },
+      h('h1', { 'data-id': 'tn-static' }, 'Static'),
+    )
+
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+    containers.push(container)
+    const dispose = mount(tree as VNode, container)
+
+    expect(container.querySelector('[data-id="tn-static"]')?.tagName).toBe('H1')
+
+    dispose()
+  })
+})

package/src/kinetic/StaggerRenderer.tsx

@@ -1,7 +1,7 @@
 import type { VNode } from '@pyreon/core'
 import { h } from '@pyreon/core'
 import type { CSSProperties, TransitionCallbacks } from '../types'
-import { cloneVNode } from '../utils'
+import { cloneVNode, resolveChildren } from '../utils'
 import TransitionItem from './TransitionItem'
 import type { KineticConfig } from './types'
 
@@ -41,7 +41,9 @@ const StaggerRenderer = ({
   const effectiveInterval = interval ?? config.interval ?? 50
   const effectiveReverseLeave = reverseLeave ?? config.reverseLeave ?? false
 
-  const childArray = (Array.isArray(children) ? children : [children]).filter(isVNode)
+  // Unwrap compiler-emitted accessor wrap — see `resolveChildren` jsdoc.
+  const resolved = resolveChildren(children)
+  const childArray = (Array.isArray(resolved) ? resolved : [resolved]).filter(isVNode)
   const count = childArray.length
 
   const staggeredChildren = childArray.map((child, index) => {

package/src/kinetic/TransitionItem.tsx

@@ -5,7 +5,15 @@ import type { ClassTransitionProps, StyleTransitionProps, TransitionCallbacks }
 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'
 
 type TransitionItemProps = ClassTransitionProps &
   StyleTransitionProps &
@@ -78,6 +86,18 @@ const applyReducedMotion = (
  * Uses cloneVNode to inject ref onto the child — the child must accept ref.
  */
 const TransitionItem = (props: TransitionItemProps): VNode | null => {
+  // The Pyreon compiler wraps `{cloneVNode(child, {...})}` JSX child
+  // expressions in StaggerRenderer/GroupRenderer as `() => cloneVNode(...)`
+  // (prop-inlining for reactivity — see `resolveChildren` jsdoc). At this
+  // boundary `props.children` therefore arrives as a FUNCTION instead of a
+  // VNode. cloneVNode-on-a-function silently produces `{type: undefined,
+  // props: {ref: ...}}` (spreading a function yields no own properties
+  // because functions have none enumerable), which mountElement renders
+  // as a literal `<undefined>` tag in the DOM — the SSG'd `<h1>Hello</h1>`
+  // becomes an empty `<undefined></undefined>` post-hydrate (reproducer:
+  // bokisch.com Intro section). Resolve eagerly so the entire body below
+  // can treat `child` as a static VNode.
+  const child = resolveChildren(props.children) as VNode
   const appear = props.appear ?? false
   const unmount = props.unmount ?? true
   const timeout = props.timeout ?? 5000
@@ -91,7 +111,7 @@ const TransitionItem = (props: TransitionItemProps): VNode | null => {
   const mergedRef = mergeRefs(
     elementRef,
     stateRef,
-    (props.children.props as Record<string, unknown>)?.ref as
+    (child?.props as Record<string, unknown>)?.ref as
       | ((el: HTMLElement | null) => void)
       | undefined,
   )
@@ -182,10 +202,10 @@ const TransitionItem = (props: TransitionItemProps): VNode | null => {
         fallback={
           unmount
             ? null
-            : cloneVNode(props.children, {
+            : cloneVNode(child, {
                 ref: mergedRef,
                 style: mergeStyles(
-                  (props.children.props as Record<string, unknown>)?.style as
+                  (child?.props as Record<string, unknown>)?.style as
                     | Record<string, string | number | undefined>
                     | undefined,
                   { display: 'none' },
@@ -193,7 +213,7 @@ const TransitionItem = (props: TransitionItemProps): VNode | null => {
               })
         }
       >
-        {cloneVNode(props.children, { ref: mergedRef })}
+        {cloneVNode(child, { ref: mergedRef })}
       </Show>
     )
   }
@@ -210,7 +230,7 @@ const TransitionItem = (props: TransitionItemProps): VNode | null => {
   // Initially-visible items keep the unmount semantic.
   const hiddenClass = props.leaveTo ?? props.enterFrom
   const hiddenStyle = props.leaveToStyle ?? props.enterStyle
-  const childProps = (props.children.props ?? {}) as Record<string, unknown>
+  const childProps = (child?.props ?? {}) as Record<string, unknown>
   const childClass = childProps.class
   const mergedClass = hiddenClass
     ? cx([childClass as Parameters<typeof cx>[0], hiddenClass])
@@ -224,7 +244,7 @@ const TransitionItem = (props: TransitionItemProps): 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 TransitionItem

package/src/utils.ts

@@ -83,3 +83,31 @@ export const cloneVNode = (vnode: VNode, extraProps: Record<string, unknown>): V
   ...vnode,
   props: { ...vnode.props, ...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.
+ */
+export const resolveChildren = <T>(children: T | (() => T)): T =>
+  (typeof children === 'function' ? (children as () => T)() : children) as T