@pyreon/kinetic 0.21.0 → 0.23.0

package/src/__tests__/Collapse.test.tsx

@@ -397,14 +397,35 @@ const wireWrapperRef = (vnode: VNode | null, el: HTMLElement) => {
   }
 }
 
-/** Find and wire contentRef inside Show > div children. */
+/**
+ * Find and wire contentRef on the inner div. Walks two shapes:
+ *
+ *  1. Initially-visible Collapse: outer → <Show>{<div ref=contentRef/>}</Show>
+ *     (the pre-SSR-fix shape, kept for the `wasInitiallyShown=true` branch
+ *     in CollapseRenderer)
+ *
+ *  2. Initially-hidden Collapse: outer → <div ref=contentRef/>
+ *     (the SSR-correct shape — children always rendered structurally so
+ *     the prerendered HTML carries content for SEO / social scrapers /
+ *     no-JS users; visual hiding via the outer wrapper's `height: 0;
+ *     overflow: hidden`. See CollapseRenderer's `wasInitiallyShown`
+ *     branch.)
+ *
+ * Tries the direct-div shape first; falls back to the Show-wrapped walk.
+ */
 const wireContentRef = (vnode: VNode | null, contentEl: HTMLElement) => {
   if (!vnode?.children) return
   const vnodeChildren = Array.isArray(vnode.children) ? vnode.children : [vnode.children]
   for (const c of vnodeChildren) {
-    if (!c || typeof c !== 'object' || !('type' in (c as object))) continue
-    const showNode = c as any
-    const showChildren = showNode.props?.children ?? showNode.children
+    if (!c || typeof c !== 'object' || !('props' in (c as object))) continue
+    const directRef = (c as any).props?.ref
+    if (directRef) {
+      if (typeof directRef === 'function') directRef(contentEl)
+      else if (typeof directRef === 'object') directRef.current = contentEl
+      return
+    }
+    // Fall through to Show-wrapped walk.
+    const showChildren = (c as any).props?.children ?? (c as any).children
     if (!showChildren) continue
     const sc = Array.isArray(showChildren) ? showChildren : [showChildren]
     for (const s of sc) {

package/src/__tests__/Transition.ssr.test.tsx

@@ -111,6 +111,34 @@ describe('Transition — SSR / initially-hidden children render', () => {
     expect(html).toContain('translateY(20px)')
   })
 
+  it('falls back to `enterStyle` as hidden style when leaveToStyle undefined (preset path)', async () => {
+    // The preset shape — `@pyreon/kinetic-presets` factories (fadeUp,
+    // blurInUp, slideLeft, …) populate `enterStyle` as the hidden state
+    // but may not set `leaveToStyle`. PR #717 shipped the
+    // `wasInitiallyShown` branch with `hiddenStyle = props.leaveToStyle`
+    // alone — so preset users SSR-rendered VISIBLE → flash-on-hydration.
+    // This regression test locks in the `?? props.enterStyle` fallback
+    // that aligns the style picker with the existing
+    // `hiddenClass = leaveTo ?? enterFrom` class picker.
+    //
+    // The companion `kinetic(tag).<mode>` paths (TransitionRenderer /
+    // TransitionItem / CollapseRenderer) got the same fallback in #719;
+    // this commit closes the matching gap on the direct `<Transition>`
+    // import path.
+    const html = await renderToString(
+      h(Transition, {
+        show: () => false,
+        enter: 'transition-all duration-300',
+        enterStyle: { opacity: 0, transform: 'translateY(16px)' },
+        enterToStyle: { opacity: 1, transform: 'translateY(0)' },
+        children: h('section', null, 'preset-shaped hidden state'),
+      }),
+    )
+    expect(html).toContain('preset-shaped hidden state')
+    expect(html).toContain('opacity: 0')
+    expect(html).toContain('translateY(16px)')
+  })
+
   it('merges the hidden class with any user-set class on the child', async () => {
     const html = await renderToString(
       h(Transition, {

package/src/__tests__/kinetic-modes.ssr.test.tsx

@@ -0,0 +1,214 @@
+/**
+ * SSR regression coverage for the `kinetic(tag).<mode>` API — the three
+ * renderer files PR #717 didn't reach:
+ *
+ *   - `TransitionRenderer`  → `kinetic('div').preset(...)` (default
+ *     `.transition` mode — the README's main example)
+ *   - `TransitionItem`      → `kinetic('ul').stagger()` per item (the
+ *     cascade-children mode); transitively `kinetic('ul').group()`
+ *   - `CollapseRenderer`    → `kinetic('div').collapse()` (height-animation
+ *     mode)
+ *
+ * Background. The top-level `<Transition>` was fixed in PR #717. But the
+ * `kinetic(tag).<mode>` API — which the README promotes as the primary
+ * surface — has its own per-mode renderers, and all three carried the
+ * SAME `<Show when={shouldMount} fallback={null}>` shape, dropping
+ * children from prerendered HTML when `show()` is false at SSR. That
+ * meant every documented `kinetic(tag).<mode>` consumer hit the bug
+ * even after #717 landed — including the cascading-Stagger pattern this
+ * report's author flagged on a real resume page.
+ *
+ * The fix mirrors #717: branch each renderer at setup on `props.show()`.
+ * Initially-visible → existing `<Show>`-gated mount (preserves runtime-
+ * unmount semantic). Initially-hidden → always render the inner content
+ * with the hidden-state class/style inlined; the existing `watch(stage)`
+ * effect drives the enter animation when `show` flips true.
+ *
+ * Hidden-state picker (mirrors #717): `leaveTo` / `leaveToStyle` win
+ * (explicit hidden-end state); fall back to `enterFrom` / `enterStyle`
+ * (pre-enter state). The `enterStyle` fallback covers the preset path —
+ * `@pyreon/kinetic-presets` factories populate `enterStyle` as the
+ * hidden state but may not set `leaveToStyle`. Without the fallback,
+ * preset users would SSR-render VISIBLE → flash-on-hydration.
+ *
+ * API note. `kinetic(tag)` takes animation config via CHAIN methods
+ * (`.enter()`, `.enterClass({from, to, active})`, `.leaveClass(...)`,
+ * `.preset()`), NOT as runtime props. Runtime props are limited to
+ * `show` / `appear` / `unmount` / `timeout` plus HTML attributes —
+ * anything else gets forwarded to the rendered element. The tests
+ * below use the chain API to faithfully exercise real user code.
+ *
+ * Coverage layered with PR #717: the test file there
+ * (`Transition.ssr.test.tsx`) covers the direct `<Transition>` import
+ * path; this file covers the `kinetic(tag).<mode>` factory paths.
+ */
+
+import { h } from '@pyreon/core'
+import { renderToString } from '@pyreon/runtime-server'
+import { describe, expect, it } from 'vitest'
+import kinetic from '../kinetic'
+
+describe('kinetic(tag).transition — SSR / initially-hidden (TransitionRenderer)', () => {
+  it('emits children when show=false initially (kinetic-mode shape, was: empty wrapper)', async () => {
+    // Cascading-bug shape — every `kinetic('div').preset(...)` user with a
+    // scroll-reveal `show` accessor hit this. Pre-fix: outer wrapper renders
+    // but children are dropped by the inner Show fallback.
+    const FadeSection = kinetic('section').enterClass({
+      active: 'transition-all duration-300',
+      from: 'opacity-0',
+      to: 'opacity-100',
+    })
+    const html = await renderToString(
+      h(FadeSection, { show: () => false },
+        h('h2', null, 'Work Experience'),
+        h('p', null, 'real content for SEO + social scrapers'),
+      ),
+    )
+    expect(html).toContain('<h2')
+    expect(html).toContain('Work Experience')
+    expect(html).toContain('real content for SEO + social scrapers')
+  })
+
+  it('inlines `leaveTo` class over `enterFrom` (explicit hidden-end state wins)', async () => {
+    const Panel = kinetic('aside')
+      .enterClass({ from: 'translate-y-4', to: 'translate-y-0' })
+      .leaveClass({ to: 'is-hidden opacity-0' })
+    const html = await renderToString(
+      h(Panel, { show: () => false },
+        h('div', null, 'panel content'),
+      ),
+    )
+    expect(html).toContain('is-hidden opacity-0')
+    expect(html).toContain('panel content')
+    // leaveTo wins — the competing enterFrom should NOT be applied.
+    expect(html).not.toContain('translate-y-4')
+  })
+
+  it('inlines `enterStyle` as hidden style when leaveToStyle undefined (preset path)', async () => {
+    // The preset shape — `@pyreon/kinetic-presets` factories populate
+    // `enterStyle` (= `.enter()` chain) as the hidden state. Without the
+    // enterStyle fallback, SSR would render VISIBLE → flash-on-hydration.
+    // This locks in the critical preset-compatibility behaviour.
+    const FadeUpDiv = kinetic('div')
+      .enter({ opacity: 0, transform: 'translateY(16px)' })
+      .enterTo({ opacity: 1, transform: 'translateY(0)' })
+      .enterTransition('all 300ms ease-out')
+    const html = await renderToString(
+      h(FadeUpDiv, { show: () => false },
+        h('h1', null, 'preset-shaped hidden state'),
+      ),
+    )
+    expect(html).toContain('preset-shaped hidden state')
+    expect(html).toContain('opacity: 0')
+    expect(html).toContain('translateY(16px)')
+  })
+
+  it('initially-visible (show=true) renders normally — unchanged behaviour', async () => {
+    const FadeDiv = kinetic('div').leaveClass({ to: 'is-hidden' })
+    const html = await renderToString(
+      h(FadeDiv, { show: () => true },
+        h('main', null, 'visible from the start'),
+      ),
+    )
+    expect(html).toContain('visible from the start')
+    // leaveTo must NOT leak onto the initially-visible render.
+    expect(html).not.toContain('is-hidden')
+  })
+
+  it('falls back to `enterFrom` class for scroll-reveal patterns (only enter side configured)', async () => {
+    const RevealSection = kinetic('section').enterClass({
+      active: 'transition-all duration-700',
+      from: 'opacity-0 translate-y-8',
+      to: 'opacity-100 translate-y-0',
+    })
+    const html = await renderToString(
+      h(RevealSection, { show: () => false, id: 'resume-section' },
+        h('p', null, 'work history goes here'),
+      ),
+    )
+    expect(html).toContain('id="resume-section"')
+    expect(html).toContain('work history goes here')
+    expect(html).toContain('opacity-0 translate-y-8')
+  })
+})
+
+describe('kinetic(tag).stagger() — SSR / initially-hidden (TransitionItem per item)', () => {
+  it('emits all child items when show=false initially (cascading stagger SSR shape)', async () => {
+    // The reported real-app pattern: cascading intro / list reveal.
+    // Pre-fix: every per-item TransitionItem rendered null on the server,
+    // dropping the full list from prerendered HTML.
+    const StaggerList = kinetic('ul')
+      .enterClass({
+        active: 'transition-all',
+        from: 'opacity-0 translate-y-4',
+        to: 'opacity-100 translate-y-0',
+      })
+      .stagger({ interval: 80 })
+    const html = await renderToString(
+      h(StaggerList, { show: () => false },
+        [
+          h('li', { key: 'h' }, 'Heading'),
+          h('li', { key: 't' }, 'tagline content'),
+          h('li', { key: 's' }, 'social icons row'),
+        ],
+      ),
+    )
+    expect(html).toContain('Heading')
+    expect(html).toContain('tagline content')
+    expect(html).toContain('social icons row')
+    // Every per-item TransitionItem should apply the hidden class
+    // (enterFrom in this scroll-reveal shape).
+    const occurrences = (html.match(/opacity-0 translate-y-4/g) ?? []).length
+    expect(occurrences).toBeGreaterThanOrEqual(3)
+  })
+
+  it('initially-visible stagger (show=true) renders all items unchanged', async () => {
+    const StaggerList = kinetic('ul')
+      .enterClass({ from: 'opacity-0', to: 'opacity-100' })
+      .leaveClass({ to: 'is-hidden' })
+      .stagger({ interval: 50 })
+    const html = await renderToString(
+      h(StaggerList, { show: () => true },
+        [h('li', { key: 'a' }, 'item-a'), h('li', { key: 'b' }, 'item-b')],
+      ),
+    )
+    expect(html).toContain('item-a')
+    expect(html).toContain('item-b')
+    // leaveTo must NOT leak onto visible items.
+    expect(html).not.toContain('is-hidden')
+  })
+})
+
+describe('kinetic(tag).collapse() — SSR / initially-hidden (CollapseRenderer)', () => {
+  it('emits inner content when show=false initially (was: empty 0-height wrapper)', async () => {
+    // Pre-fix: outer wrapper renders with `height: 0; overflow: hidden`
+    // but its children are stripped by the inner Show — empty wrapper in
+    // prerendered HTML. The fix keeps the outer wrapper's visual hiding
+    // (height: 0 IS the layout-safe collapse mechanism — flex slots see
+    // a 0-height box, no slot-collapse) while always rendering inner content.
+    const Accordion = kinetic('div').collapse()
+    const html = await renderToString(
+      h(Accordion, { show: () => false },
+        h('div', { class: 'panel-body' }, 'accordion panel content for SEO'),
+      ),
+    )
+    expect(html).toContain('accordion panel content for SEO')
+    expect(html).toContain('panel-body')
+    // The outer wrapper retains the collapse-controlled hidden style —
+    // visual hiding via height:0 + overflow:hidden, not by dropping children.
+    expect(html).toContain('height: 0px')
+    expect(html).toContain('overflow: hidden')
+  })
+
+  it('initially-visible collapse (show=true) renders content normally', async () => {
+    const Accordion = kinetic('section').collapse()
+    const html = await renderToString(
+      h(Accordion, { show: () => true },
+        h('p', null, 'expanded content'),
+      ),
+    )
+    expect(html).toContain('expanded content')
+    // height: 'auto' is the entered-state hint
+    expect(html).toContain('height: auto')
+  })
+})

package/src/__tests__/kinetic.browser.test.tsx

@@ -211,4 +211,117 @@ describe('@pyreon/kinetic browser smoke', () => {
     expect(el()!.classList.contains('enter-active')).toBe(true)
     unmount()
   })
+
+  // ── Initially-hidden kinetic(tag).<mode> — client-side parity with SSR ──
+  //
+  // Companion to PR #717's `<Transition>` direct-import specs (the two
+  // above). These exercise the `kinetic(tag).<mode>` factory paths — the
+  // README's primary documented surface — whose per-mode renderers carried
+  // the same SSR-children-dropped bug until this PR fixed them. SSR specs
+  // in `kinetic-modes.ssr.test.tsx` prove children land in prerendered
+  // HTML; these specs prove the SAME render path works under a real DOM —
+  // the element mounts with the hidden-state class/style applied, and an
+  // `applyEnter` triggered by a `show` flip cleanly transitions it out.
+
+  it('kinetic("div").transition with initial show=false mounts element with hidden class', async () => {
+    const Reveal = kinetic('section').enterClass({
+      active: 'enter-active',
+      from: 'hide-state',
+      to: 'show-state',
+    })
+    const show = signal(false)
+    const { container, unmount } = mountInBrowser(
+      h(Reveal, { show, 'data-id': 'reveal-target' }, h('p', null, 'scroll-reveal content')),
+    )
+    // Pre-fix: container.querySelector returns null (children dropped).
+    const el = container.querySelector('[data-id="reveal-target"]') as HTMLElement | null
+    expect(el).not.toBeNull()
+    expect(el!.textContent).toContain('scroll-reveal content')
+    // enterFrom is the fallback hidden-state class (scroll-reveal pattern
+    // configures only the enter side).
+    expect(el!.classList.contains('hide-state')).toBe(true)
+    unmount()
+  })
+
+  it('kinetic("div").transition show=true flip cleans hidden class + runs enter animation', async () => {
+    const Reveal = kinetic('section').enterClass({
+      active: 'enter-active',
+      from: 'hide-state',
+      to: 'show-state',
+    })
+    const show = signal(false)
+    const { container, unmount } = mountInBrowser(
+      h(Reveal, { show, 'data-id': 'reveal-target' }, h('p', null, 'content')),
+    )
+    const el = () => container.querySelector('[data-id="reveal-target"]') as HTMLElement | null
+    expect(el()!.classList.contains('hide-state')).toBe(true)
+
+    show.set(true)
+    await flush()
+    // Double-rAF for the applyEnter nextFrame → enterTo applied.
+    await new Promise<void>((resolve) =>
+      requestAnimationFrame(() => requestAnimationFrame(() => resolve())),
+    )
+    await flush()
+
+    expect(el()!.classList.contains('show-state')).toBe(true)
+    // enterFrom (hide-state) was removed; the symmetric applyEnter cleanup
+    // ALSO removes leave-side classes (none here) — locks in the
+    // companion fix that prevents residual hidden classes from fighting
+    // enterTo's CSS rules.
+    expect(el()!.classList.contains('hide-state')).toBe(false)
+    expect(el()!.classList.contains('enter-active')).toBe(true)
+    unmount()
+  })
+
+  it('kinetic("ul").stagger() with initial show=false mounts all items with hidden class', async () => {
+    // The reported real-app cascading-Stagger pattern at SSR. Each per-item
+    // TransitionItem must render structurally; the hidden class lands on
+    // each item via the enterFrom fallback.
+    const Staggered = kinetic('ul')
+      .enterClass({ active: 'enter-active', from: 'item-hidden', to: 'item-shown' })
+      .stagger({ interval: 50 })
+    const show = signal(false)
+    const { container, unmount } = mountInBrowser(
+      h(Staggered, { show, 'data-id': 'stagger-list' }, [
+        h('li', { key: 'a' }, 'first item'),
+        h('li', { key: 'b' }, 'second item'),
+        h('li', { key: 'c' }, 'third item'),
+      ]),
+    )
+    const list = container.querySelector('[data-id="stagger-list"]') as HTMLElement | null
+    expect(list).not.toBeNull()
+    const items = list!.querySelectorAll('li')
+    expect(items.length).toBe(3)
+    // Every per-item TransitionItem applies the hidden class.
+    for (const item of items) {
+      expect(item.classList.contains('item-hidden')).toBe(true)
+    }
+    expect(list!.textContent).toContain('first item')
+    expect(list!.textContent).toContain('second item')
+    expect(list!.textContent).toContain('third item')
+    unmount()
+  })
+
+  it('kinetic("div").collapse() with initial show=false mounts inner content (visually hidden via height:0)', async () => {
+    // CollapseRenderer's fix: outer wrapper retains height:0 + overflow:hidden
+    // (layout-safe visual hiding); inner content is always rendered so SSG
+    // ships the structural HTML for SEO. Real-DOM parity check.
+    const Accordion = kinetic('div').collapse()
+    const show = signal(false)
+    const { container, unmount } = mountInBrowser(
+      h(Accordion, { show, 'data-id': 'accordion' },
+        h('div', { 'data-id': 'inner' }, 'accordion content'),
+      ),
+    )
+    const wrapper = container.querySelector('[data-id="accordion"]') as HTMLElement | null
+    const inner = container.querySelector('[data-id="inner"]') as HTMLElement | null
+    expect(wrapper).not.toBeNull()
+    expect(inner).not.toBeNull() // ← was null pre-fix (Show dropped it)
+    expect(inner!.textContent).toBe('accordion content')
+    // Outer wrapper visually hides via height:0 (computed style — real CSS).
+    expect(wrapper!.style.height).toBe('0px')
+    expect(wrapper!.style.overflow).toBe('hidden')
+    unmount()
+  })
 })

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()
+  })
+})