@pyreon/kinetic 0.19.0 → 0.21.0

package/README.md

@@ -211,6 +211,29 @@ const AnimatedButton = kinetic(Button).preset(fade)
 AnimatedButton({ show: isVisible, primary: true, size: 'large', children: 'Click me' })
 ```
 
+## 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).
+
+```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')
+
+// 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.
+<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>`.
+
 ## Peer Dependencies
 
 | Package            | Version  |

package/lib/index.js

@@ -1,4 +1,4 @@
-import { Show, createRef, h, onMount, onUnmount } from "@pyreon/core";
+import { Show, createRef, h, mergeProps, onMount, onUnmount, splitProps } from "@pyreon/core";
 import { runUntracked, signal, watch } from "@pyreon/reactivity";
 import { jsx } from "@pyreon/core/jsx-runtime";
 
@@ -172,11 +172,10 @@ const CollapseRenderer = ({ config, htmlProps, show, appear, timeout, transition
 		...stage() !== "entered" ? { overflow: "hidden" } : {},
 		...stage() === "hidden" ? { height: "0px" } : stage() === "entered" ? { height: "auto" } : {}
 	};
-	return h(config.tag, {
+	return h(config.tag, mergeProps(htmlProps, {
 		ref: wrapperRef,
-		...htmlProps,
 		style: wrapperStyle
-	}, /* @__PURE__ */ jsx(Show, {
+	}), /* @__PURE__ */ jsx(Show, {
 		when: shouldRender,
 		children: /* @__PURE__ */ jsx("div", {
 			ref: contentRef,
@@ -479,7 +478,7 @@ const GroupRenderer = ({ config, htmlProps, appear, timeout, callbacks, children
 				children: element
 			});
 		});
-		return h(config.tag, { ...htmlProps }, ...groupedChildren);
+		return h(config.tag, htmlProps, ...groupedChildren);
 	});
 };
 
@@ -526,7 +525,7 @@ const StaggerRenderer = ({ config, htmlProps, show, appear, timeout, interval, r
 			} })
 		}, child.key ?? index);
 	});
-	return h(config.tag, { ...htmlProps }, ...staggeredChildren);
+	return h(config.tag, htmlProps, ...staggeredChildren);
 };
 
 //#endregion
@@ -613,18 +612,14 @@ const TransitionRenderer = (props) => {
 	}, { immediate: true });
 	return /* @__PURE__ */ jsx(Show, {
 		when: shouldMount,
-		fallback: effectiveUnmount ? null : h(props.config.tag, {
+		fallback: effectiveUnmount ? null : h(props.config.tag, mergeProps(props.htmlProps, {
 			ref: mergedRef,
-			...props.htmlProps,
 			style: {
 				...props.htmlProps.style ?? {},
 				display: "none"
 			}
-		}, props.children),
-		children: h(props.config.tag, {
-			ref: mergedRef,
-			...props.htmlProps
-		}, props.children)
+		}), props.children),
+		children: h(props.config.tag, mergeProps(props.htmlProps, { ref: mergedRef }), props.children)
 	});
 };
 
@@ -651,10 +646,7 @@ const KINETIC_KEYS = new Set([
 */
 const createKineticComponent = (config) => {
 	const Component = (props) => {
-		const htmlProps = {};
-		const kineticProps = {};
-		for (const key in props) if (KINETIC_KEYS.has(key)) kineticProps[key] = props[key];
-		else htmlProps[key] = props[key];
+		const [kineticProps, htmlPropsWithChildren] = splitProps(props, [...KINETIC_KEYS]);
 		const { show, appear, unmount, timeout, transition, interval, reverseLeave, onEnter, onAfterEnter, onLeave, onAfterLeave } = kineticProps;
 		const callbacks = {
 			onEnter: onEnter ?? config.onEnter,
@@ -662,7 +654,8 @@ const createKineticComponent = (config) => {
 			onLeave: onLeave ?? config.onLeave,
 			onAfterLeave: onAfterLeave ?? config.onAfterLeave
 		};
-		const { children, ...restHtml } = htmlProps;
+		const [childHolder, restHtml] = splitProps(htmlPropsWithChildren, ["children"]);
+		const children = childHolder.children;
 		if (config.mode === "collapse") return /* @__PURE__ */ jsx(CollapseRenderer, {
 			config,
 			htmlProps: restHtml,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/kinetic",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "CSS-transition-based animation components for Pyreon",
   "license": "MIT",
   "repository": {
@@ -42,11 +42,12 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@pyreon/core": "^0.19.0",
-    "@pyreon/reactivity": "^0.19.0",
-    "@pyreon/runtime-dom": "^0.19.0",
-    "@pyreon/test-utils": "^0.13.6",
-    "@pyreon/typescript": "^0.19.0",
+    "@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",
     "@vitest/browser-playwright": "^4.1.4",
     "@vitus-labs/tools-rolldown": "^2.3.0"
   },
@@ -54,8 +55,8 @@
     "node": ">= 22"
   },
   "dependencies": {
-    "@pyreon/core": "^0.19.0",
-    "@pyreon/reactivity": "^0.19.0",
-    "@pyreon/runtime-dom": "^0.19.0"
+    "@pyreon/core": "^0.21.0",
+    "@pyreon/reactivity": "^0.21.0",
+    "@pyreon/runtime-dom": "^0.21.0"
   }
 }

package/src/Transition.tsx

@@ -1,5 +1,5 @@
 import type { VNode } from '@pyreon/core'
-import { createRef, Show } from '@pyreon/core'
+import { createRef, cx, Show } from '@pyreon/core'
 import { watch } from '@pyreon/reactivity'
 import type { ClassTransitionProps, StyleTransitionProps, TransitionProps } from './types'
 import useAnimationEnd from './useAnimationEnd'
@@ -16,8 +16,22 @@ const applyEnter = (
     enterStyle,
     enterToStyle,
     enterTransition,
+    leave,
+    leaveFrom,
+    leaveTo,
   }: ClassTransitionProps & StyleTransitionProps,
 ) => {
+  // Symmetric to applyLeave's `removeClasses(enter)` / `removeClasses(enterTo)`:
+  // clear any residual leave-cycle classes — including the `leaveTo` /
+  // `enterFrom` class the SSR / initial-hidden render path inlines for
+  // ecosystem-correct structural content (see the `wasInitiallyShown`
+  // branch below). Without this, the SSR-baked hidden-state class would
+  // compete with `enterTo`'s CSS rules and the enter animation would
+  // visually fight itself.
+  removeClasses(el, leave)
+  removeClasses(el, leaveFrom)
+  removeClasses(el, leaveTo)
+
   addClasses(el, enter)
   addClasses(el, enterFrom)
   if (enterStyle) Object.assign(el.style, enterStyle)
@@ -170,24 +184,73 @@ const Transition = (props: TransitionProps): VNode | null => {
     { immediate: true },
   )
 
-  return (
-    <Show
-      when={shouldMount}
-      fallback={
-        unmount
-          ? null
-          : cloneVNode(props.children, {
-              ref: mergedRef,
-              style: mergeStyles(
-                childProps.style as Record<string, string | number | undefined> | undefined,
-                { display: 'none' },
-              ),
-            })
-      }
-    >
-      {cloneVNode(props.children, { ref: mergedRef })}
-    </Show>
+  // Initially-visible Transitions keep the original Show-gated mount,
+  // which preserves the documented runtime-unmount semantic for the
+  // visible → hidden transition (modal close, dropdown collapse, etc.).
+  // The SSR bug (children dropped from prerendered HTML) only fires for
+  // the initially-HIDDEN case below, because `<Show when={false}>`
+  // renders `null` on the server.
+  const wasInitiallyShown = props.show()
+  if (wasInitiallyShown) {
+    return (
+      <Show
+        when={shouldMount}
+        fallback={
+          unmount
+            ? null
+            : cloneVNode(props.children, {
+                ref: mergedRef,
+                style: mergeStyles(
+                  childProps.style as Record<string, string | number | undefined> | undefined,
+                  { display: 'none' },
+                ),
+              })
+        }
+      >
+        {cloneVNode(props.children, { ref: mergedRef })}
+      </Show>
+    )
+  }
+
+  // Initially-hidden path — ecosystem-correct (Framer Motion / react-
+  // transition-group / react-spring all render children in SSR regardless
+  // of animation state; visual hiding is class/style only). Always emits
+  // children so SSG / SEO / social scrapers / no-JS users see the
+  // structural content. The hidden visual is supplied by `leaveTo`
+  // (explicit hidden-end state) or `enterFrom` (pre-enter state — covers
+  // the scroll-reveal pattern that only configures the enter side).
+  //
+  // Trade-off: for an initially-hidden Transition, `unmount: true` 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 unmount semantic
+  // (the branch above). This matches Framer Motion / react-transition-
+  // group conventions and is the price of SSR correctness; the rare
+  // user who needs true unmount on a started-hidden element can drive
+  // mount/unmount themselves outside `<Transition>`.
+  //
+  // 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`.
+  const hiddenClass = props.leaveTo ?? props.enterFrom
+  const hiddenStyle = props.leaveToStyle
+  const childClass = childProps.class
+  const mergedClass = hiddenClass
+    ? cx([childClass as Parameters<typeof cx>[0], hiddenClass])
+    : undefined
+  const mergedStyle = mergeStyles(
+    childProps.style as Record<string, string | number | undefined> | undefined,
+    hiddenStyle,
   )
+
+  // Build extra-props carefully — undefined values must NOT be passed to
+  // cloneVNode because `{...vnode.props, ...extraProps}` spreads them and
+  // overrides any user-set `class`/`style` on the child vnode with undefined.
+  const extra: Record<string, unknown> = { ref: mergedRef }
+  if (mergedClass !== undefined) extra.class = mergedClass
+  if (mergedStyle !== undefined) extra.style = mergedStyle
+
+  return cloneVNode(props.children, extra)
 }
 
 export default Transition

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

@@ -0,0 +1,155 @@
+/**
+ * SSR regression coverage for `<Transition>` (the missing test layer that
+ * let the children-dropped-on-SSR bug ship).
+ *
+ * Background. `<Transition show={() => false} ...>` used to render `<Show
+ * when={false} fallback={null}>` on the server, which emitted EMPTY HTML —
+ * any SSG site using kinetic for scroll-triggered reveal (the documented
+ * `useIntersection` + sticky-signal pattern, where `show` is false at SSR
+ * because IntersectionObserver can't fire until client hydration) shipped
+ * with the wrapped content STRUCTURALLY ABSENT from the prerendered HTML.
+ * Bad for SEO, social scrapers, accessibility tools, and no-JS users.
+ *
+ * Ecosystem norm (the framing this fix aligns Pyreon with): Framer Motion,
+ * react-transition-group, react-spring, AutoAnimate all render children in
+ * SSR regardless of animation state and only apply animation styles on the
+ * client. "Content is structural, animation is visual."
+ *
+ * What the fix changes. `Transition` now branches at setup on
+ * `props.show()`:
+ *   - initially-visible → existing `<Show>`-gated mount (unchanged;
+ *     preserves the runtime-unmount semantic for the visible→hidden case)
+ *   - initially-hidden → always render children with hidden-state classes
+ *     inlined (`leaveTo` if defined, else `enterFrom` — covers the
+ *     scroll-reveal pattern that only configures the enter side). The
+ *     existing `watch(stage)` effect drives the enter animation when
+ *     `show` flips true.
+ *
+ * Why these tests are load-bearing. Zero existing tests exercised
+ * `show: () => false` initial state (the bug class). The fact that this
+ * shipped is exactly the "no test catches it because no test runs the real
+ * path" failure mode the `test-environment-parity.md` rule was written to
+ * prevent — both real `h()` AND a SSR-driving environment (`renderToString`)
+ * are needed to catch it.
+ *
+ * Bisect-verified: reverting `Transition.tsx`'s `wasInitiallyShown` branch
+ * fails every spec below with `expected '' to contain '...'` (the empty-
+ * children bug). Restored → all green.
+ */
+
+import { h } from '@pyreon/core'
+import { renderToString } from '@pyreon/runtime-server'
+import { describe, expect, it } from 'vitest'
+import Transition from '../Transition'
+
+describe('Transition — SSR / initially-hidden children render', () => {
+  it('emits children when show=false initially (was: <Show fallback={null}> → empty)', async () => {
+    // The canonical bug shape — scroll-reveal pattern at SSR time.
+    const html = await renderToString(
+      h(Transition, {
+        show: () => false,
+        enterFrom: 'opacity-0',
+        enterTo: 'opacity-100',
+        enter: 'transition-opacity duration-300',
+        children: h('section', null, 'real content for SEO + social scrapers'),
+      }),
+    )
+    // Structural content must land in the prerendered HTML. Pre-fix this
+    // assertion failed with `expected '' to contain '...'`.
+    expect(html).toContain('<section')
+    expect(html).toContain('real content for SEO + social scrapers')
+  })
+
+  it('inlines `leaveTo` as the hidden-state class (explicit hidden-end state takes precedence)', async () => {
+    const html = await renderToString(
+      h(Transition, {
+        show: () => false,
+        enterFrom: 'opacity-0 translate-y-4', // present but NOT selected
+        enterTo: 'opacity-100 translate-y-0',
+        leave: 'transition-opacity',
+        leaveFrom: 'opacity-100',
+        leaveTo: 'is-hidden opacity-0', // ← explicit hidden-end state, selected
+        children: h('div', null, 'panel content'),
+      }),
+    )
+    expect(html).toContain('is-hidden opacity-0')
+    expect(html).toContain('panel content')
+    // The competing `enterFrom` should NOT be applied (leaveTo wins).
+    expect(html).not.toContain('translate-y-4')
+  })
+
+  it('falls back to `enterFrom` as the hidden class for scroll-reveal patterns (only enter side configured)', async () => {
+    // The exact pattern the reported bug surfaced on — only the enter
+    // animation is configured (because IO triggers `show` true; there's
+    // no leave side for the reveal pattern).
+    const html = await renderToString(
+      h(Transition, {
+        show: () => false,
+        enter: 'transition-all duration-700',
+        enterFrom: 'opacity-0 translate-y-8',
+        enterTo: 'opacity-100 translate-y-0',
+        children: h('section', { id: 'resume-section' }, 'work history goes here'),
+      }),
+    )
+    expect(html).toContain('id="resume-section"')
+    expect(html).toContain('work history goes here')
+    // enterFrom IS the resting hidden state for this pattern.
+    expect(html).toContain('opacity-0 translate-y-8')
+  })
+
+  it('inlines `leaveToStyle` as the hidden inline style when defined', async () => {
+    const html = await renderToString(
+      h(Transition, {
+        show: () => false,
+        leaveTo: 'animated-section',
+        leaveToStyle: { opacity: 0, transform: 'translateY(20px)' },
+        children: h('article', null, 'article body'),
+      }),
+    )
+    expect(html).toContain('article body')
+    expect(html).toContain('opacity: 0')
+    expect(html).toContain('translateY(20px)')
+  })
+
+  it('merges the hidden class with any user-set class on the child', async () => {
+    const html = await renderToString(
+      h(Transition, {
+        show: () => false,
+        leaveTo: 'is-hidden',
+        children: h('div', { class: 'card card--featured' }, 'merged-class content'),
+      }),
+    )
+    expect(html).toContain('merged-class content')
+    expect(html).toContain('card')
+    expect(html).toContain('card--featured')
+    expect(html).toContain('is-hidden')
+  })
+
+  it('emits children unchanged when neither leaveTo nor enterFrom is defined (graceful no-op)', async () => {
+    // An unusual config — no enter/leave classes at all. Children should
+    // still render structurally (the SEO/SSG contract); no hidden class
+    // is appended because there's nothing to append.
+    const html = await renderToString(
+      h(Transition, {
+        show: () => false,
+        children: h('div', null, 'bare content'),
+      }),
+    )
+    expect(html).toContain('bare content')
+  })
+
+  it('initially-visible Transition (show=true) renders children normally — unchanged behavior', async () => {
+    // The other branch of the fix — initially-visible Transitions keep
+    // the original `<Show>`-gated path. This spec locks in the no-
+    // regression contract for the existing common case.
+    const html = await renderToString(
+      h(Transition, {
+        show: () => true,
+        leaveTo: 'is-hidden', // must NOT leak onto initially-visible
+        children: h('main', null, 'visible from the start'),
+      }),
+    )
+    expect(html).toContain('visible from the start')
+    expect(html).not.toContain('is-hidden')
+  })
+})

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

@@ -1,11 +1,42 @@
 /** @jsxImportSource @pyreon/core */
 import { describe, expect, it } from 'vitest'
+import { _rp, h } from '@pyreon/core'
 import { signal } from '@pyreon/reactivity'
 import { flush, mountInBrowser } from '@pyreon/test-utils/browser'
+import kinetic from '../kinetic'
 import { nextFrame, mergeClassNames } from '../utils'
 import Transition from '../Transition'
 
 describe('@pyreon/kinetic browser smoke', () => {
+  // Regression: createKineticComponent + the 4 renderers used to value-copy
+  // user props (`for…in` / `const { children, ...rest }` / `{ ...htmlProps }`),
+  // firing every getter at component-setup time. The compiler emits a
+  // reactive HTML attr as `_rp(() => sig())`; mount.ts's makeReactiveProps
+  // turns it into a getter on `props`. The value-copy collapsed that getter
+  // to a static snapshot, freezing the attribute forever. The fix routes
+  // every hop through descriptor-preserving splitProps / mergeProps / by-ref
+  // so runtime-dom's applyProps detects the getter descriptor and wraps the
+  // read in a renderEffect. Bisect-verified: reverting createKineticComponent's
+  // splitProps split back to `for…in` fails this with `expected 'a' to be 'b'`.
+  it('forwards a reactive HTML attr through the kinetic pipeline (descriptor-preserving)', async () => {
+    const FadeDiv = kinetic('div')
+    const show = signal(true)
+    const v = signal('a')
+    const { container, unmount } = mountInBrowser(
+      h(
+        FadeDiv,
+        { show, 'data-testid': 'fd', 'data-variant': _rp(() => v()) },
+        h('span', { 'data-id': 'kc' }, 'hi'),
+      ),
+    )
+    const el = () => container.querySelector('[data-testid="fd"]')
+    expect(el()?.getAttribute('data-variant')).toBe('a')
+    v.set('b')
+    await flush()
+    expect(el()?.getAttribute('data-variant')).toBe('b')
+    unmount()
+  })
+
   it('Transition mounts a visible child into real DOM', async () => {
     const show = signal(true)
     const { container, unmount } = mountInBrowser(
@@ -51,6 +82,61 @@ describe('@pyreon/kinetic browser smoke', () => {
     expect(mergeClassNames(undefined, undefined)).toBe(undefined)
   })
 
+  // Regression: a kinetic-wrapped component must FORWARD a compiler-shaped
+  // reactive HTML attr (`<KineticDiv class={sig()}>` → `_rp(() => sig())`,
+  // which `makeReactiveProps` turns into a getter on `props`) so the DOM
+  // patches when the signal changes. The factory's prop split + the
+  // renderers' element spread used to value-copy props, firing the getter
+  // once at setup and freezing the attribute. We build the vnode with
+  // `h()` + `_rp()` directly because this browser config has no Pyreon
+  // compiler plugin — that faithfully reproduces the exact post-
+  // makeReactiveProps shape the mount pipeline sees in a real app.
+  //
+  // Bisect-verified: revert createKineticComponent's splitProps back to
+  // `htmlProps[key] = props[key]` → this fails with the className stuck
+  // at 'one' (`expected 'one' to be 'two'`). Restored → passes.
+  it('forwards a compiler-shaped reactive HTML attr — DOM patches on signal change (transition mode)', async () => {
+    const KineticDiv = kinetic('div')
+    const cls = signal('one')
+    const { container, unmount } = mountInBrowser(
+      h(
+        KineticDiv,
+        { show: () => true, class: _rp(() => cls()) },
+        h('span', { 'data-id': 'k' }, 'x'),
+      ),
+    )
+    const el = () => container.querySelector('div')
+    expect(el()?.querySelector('[data-id="k"]')?.textContent).toBe('x')
+    expect(el()?.className).toBe('one')
+
+    cls.set('two')
+    await flush()
+    expect(el()?.className).toBe('two')
+
+    cls.set('three')
+    await flush()
+    expect(el()?.className).toBe('three')
+    unmount()
+  })
+
+  it('forwards a compiler-shaped reactive HTML attr — collapse mode (mergeProps path)', async () => {
+    const KineticDiv = kinetic('div').collapse()
+    const cls = signal('a')
+    const { container, unmount } = mountInBrowser(
+      h(
+        KineticDiv,
+        { show: () => true, class: _rp(() => cls()) },
+        h('span', { 'data-id': 'c' }, 'y'),
+      ),
+    )
+    const el = () => container.querySelector('div')
+    expect(el()?.className).toBe('a')
+    cls.set('b')
+    await flush()
+    expect(el()?.className).toBe('b')
+    unmount()
+  })
+
   it('runs in a real browser — Vitest defines `process.env.NODE_ENV !== "production"`', () => {
     // Sanity check the test env: dev gates use bundler-agnostic
     // `process.env.NODE_ENV !== 'production'`. Vitest's Vite pipeline
@@ -58,4 +144,71 @@ describe('@pyreon/kinetic browser smoke', () => {
     // `"development" !== "production"` → `true` in dev runs.
     expect(process.env.NODE_ENV).not.toBe('production')
   })
+
+  // ── Initially-hidden Transition: client-side parity with the SSR fix ─────
+  //
+  // The SSR test file (`Transition.ssr.test.tsx`) proves 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 applied,
+  // and an `applyEnter` triggered by a `show` flip cleanly transitions it
+  // out of the hidden state (the companion `applyEnter` fix that removes
+  // residual `leave`/`leaveFrom`/`leaveTo` classes ensures the SSR-baked
+  // hidden class doesn't fight `enterTo`).
+
+  it('Transition with initial show=false mounts the element with the hidden class (no null)', async () => {
+    const show = signal(false)
+    const { container, unmount } = mountInBrowser(
+      <Transition
+        show={show}
+        enterFrom="hide-state"
+        enterTo="show-state"
+        enter="transition-opacity"
+      >
+        <div data-id="reveal-target">scroll-reveal content</div>
+      </Transition>,
+    )
+    // Pre-fix: container.querySelector returns null (children were dropped).
+    const el = container.querySelector('[data-id="reveal-target"]') as HTMLElement | null
+    expect(el).not.toBeNull()
+    expect(el!.textContent).toBe('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('flipping show=true on an initially-hidden Transition cleans the hidden class and runs enter', async () => {
+    const show = signal(false)
+    const { container, unmount } = mountInBrowser(
+      <Transition
+        show={show}
+        enterFrom="hide-state"
+        enterTo="show-state"
+        enter="enter-active"
+      >
+        <div data-id="reveal-target">content</div>
+      </Transition>,
+    )
+    const el = () => container.querySelector('[data-id="reveal-target"]') as HTMLElement | null
+    // Starts hidden.
+    expect(el()!.classList.contains('hide-state')).toBe(true)
+    // Flip show → true; applyEnter runs in the watch effect on the SAME
+    // element (the SSR fix guarantees the element is already in DOM).
+    show.set(true)
+    await flush()
+    // The companion applyEnter fix removes residual `leave`/`leaveFrom`/
+    // `leaveTo` AND adds `enter` + `enterFrom`. enterFrom was already
+    // applied (it WAS the hidden-state class); the next frame removes it
+    // and adds enterTo. Two rAFs for full transition.
+    await new Promise<void>((resolve) =>
+      requestAnimationFrame(() => requestAnimationFrame(() => resolve())),
+    )
+    await flush()
+    // After the double-rAF, enterTo is applied + enterFrom removed.
+    expect(el()!.classList.contains('show-state')).toBe(true)
+    expect(el()!.classList.contains('hide-state')).toBe(false)
+    // `enter` (the active marker) is applied throughout the transition.
+    expect(el()!.classList.contains('enter-active')).toBe(true)
+    unmount()
+  })
 })

package/src/kinetic/CollapseRenderer.tsx

@@ -1,5 +1,5 @@
 import type { VNode } from '@pyreon/core'
-import { createRef, h, Show } from '@pyreon/core'
+import { createRef, h, mergeProps, Show } from '@pyreon/core'
 import { runUntracked, signal, watch } from '@pyreon/reactivity'
 import type { CSSProperties, TransitionCallbacks, TransitionStage } from '../types'
 import useAnimationEnd from '../useAnimationEnd'
@@ -166,9 +166,16 @@ const CollapseRenderer = ({
     ...(stage() === 'hidden' ? { height: '0px' } : stage() === 'entered' ? { height: 'auto' } : {}),
   }
 
+  // mergeProps (descriptor-preserving) instead of `{ ...htmlProps }` —
+  // every non-style HTML attr keeps its reactive getter; ref + the
+  // collapse-controlled style come last so they win (mergeProps is
+  // last-source-wins). The one-time `htmlProps.style` read above that
+  // seeds wrapperStyle is intentional: collapse OWNS the style prop
+  // (height/overflow are animation-driven), so a static merge of the
+  // user's initial style with the collapse overrides is correct here.
   return h(
     config.tag,
-    { ref: wrapperRef, ...htmlProps, style: wrapperStyle },
+    mergeProps(htmlProps, { ref: wrapperRef, style: wrapperStyle }),
     <Show when={shouldRender}>
       <div ref={contentRef}>{children}</div>
     </Show>,

package/src/kinetic/GroupRenderer.tsx

@@ -140,7 +140,9 @@ const GroupRenderer = ({
       )
     })
 
-    return h(config.tag, { ...htmlProps }, ...groupedChildren)
+    // By reference — `{ ...htmlProps }` would value-copy and freeze any
+    // reactive HTML attr the kinetic split preserved as a getter.
+    return h(config.tag, htmlProps, ...groupedChildren)
   }) as unknown as VNode
 }
 

package/src/kinetic/StaggerRenderer.tsx

@@ -82,7 +82,11 @@ const StaggerRenderer = ({
     )
   })
 
-  return h(config.tag, { ...htmlProps }, ...staggeredChildren)
+  // Pass htmlProps by reference — `{ ...htmlProps }` value-copies, firing
+  // any reactive getter the kinetic split preserved (frozen attr forever).
+  // runtime-dom's applyProps detects the getter descriptor on the live
+  // object and wraps it in renderEffect.
+  return h(config.tag, htmlProps, ...staggeredChildren)
 }
 
 export default StaggerRenderer

package/src/kinetic/TransitionRenderer.tsx

@@ -1,5 +1,5 @@
 import type { VNode } from '@pyreon/core'
-import { createRef, h, Show } from '@pyreon/core'
+import { createRef, h, mergeProps, Show } from '@pyreon/core'
 import { watch } from '@pyreon/reactivity'
 import type { CSSProperties, TransitionCallbacks } from '../types'
 import useAnimationEnd from '../useAnimationEnd'
@@ -139,19 +139,28 @@ const TransitionRenderer = (props: TransitionRendererProps): VNode | null => {
           ? null
           : h(
               props.config.tag,
-              {
+              // mergeProps keeps every reactive HTML-attr getter; ref + the
+              // hidden-state `display:none` style come last and win. The
+              // one-time `props.htmlProps.style` read seeds the hidden
+              // style — display:none must compose over the user's style.
+              mergeProps(props.htmlProps, {
                 ref: mergedRef,
-                ...props.htmlProps,
                 style: {
                   ...((props.htmlProps.style as CSSProperties) ?? {}),
                   display: 'none',
                 },
-              },
+              }),
               props.children,
             )
       }
     >
-      {h(props.config.tag, { ref: mergedRef, ...props.htmlProps }, props.children)}
+      {h(
+        props.config.tag,
+        // Descriptor-preserving merge — reactive HTML attrs keep their
+        // getters; ref wins last. `{ ...props.htmlProps }` would freeze them.
+        mergeProps(props.htmlProps, { ref: mergedRef }),
+        props.children,
+      )}
     </Show>
   )
 }

package/src/kinetic/createKineticComponent.tsx

@@ -1,4 +1,5 @@
 import type { VNode } from '@pyreon/core'
+import { splitProps } from '@pyreon/core'
 import type { CSSProperties, TransitionCallbacks } from '../types'
 import CollapseRenderer from './CollapseRenderer'
 import GroupRenderer from './GroupRenderer'
@@ -30,17 +31,25 @@ const createKineticComponent = <Tag extends string, Mode extends KineticMode = '
   config: KineticConfig,
 ): KineticComponent<Tag, Mode> => {
   const Component = (props: Record<string, unknown>): VNode | null => {
-    // Separate kinetic-specific props from HTML pass-through props
-    const htmlProps: Record<string, unknown> = {}
-    const kineticProps: Record<string, unknown> = {}
-
-    for (const key in props) {
-      if (KINETIC_KEYS.has(key)) {
-        kineticProps[key] = props[key]
-      } else {
-        htmlProps[key] = props[key]
-      }
-    }
+    // Separate kinetic-specific props from HTML pass-through props.
+    // MUST use splitProps (descriptor-preserving) — a plain
+    // `htmlProps[key] = props[key]` value-copy fires every getter at
+    // component-setup time. The compiler emits `<KineticDiv class={sig()}>`
+    // as `_rp(() => sig())`, which `makeReactiveProps` turns into a getter
+    // on `props`; reading it here (outside any tracking scope) would
+    // collapse it to a static snapshot and freeze the HTML attr forever.
+    // splitProps copies DESCRIPTORS via Object.getOwnPropertyDescriptor +
+    // Object.defineProperty, so the getter survives to the renderer's
+    // `h(config.tag, htmlProps)` where runtime-dom's applyProps detects
+    // the descriptor and wraps the read in renderEffect.
+    // `props` is `Record<string, unknown>`, so `Omit<…, string>` collapses
+    // to `{}` at the type level — the runtime split is correct (splitProps
+    // copies descriptors for every own key not in the pick set), only the
+    // inferred result types degrade. Cast back to the real shape.
+    const [kineticProps, htmlPropsWithChildren] = splitProps(props, [...KINETIC_KEYS]) as [
+      Record<string, unknown>,
+      Record<string, unknown>,
+    ]
 
     const {
       show,
@@ -71,8 +80,12 @@ const createKineticComponent = <Tag extends string, Mode extends KineticMode = '
       onAfterLeave: onAfterLeave ?? config.onAfterLeave,
     }
 
-    // Extract children from htmlProps (it's not an HTML attribute)
-    const { children, ...restHtml } = htmlProps
+    // Carve `children` out of the HTML pass-through set — also via
+    // splitProps so the remaining HTML attrs keep their getter
+    // descriptors (`const { children, ...restHtml } = …` is the same
+    // value-copy footgun as the split above).
+    const [childHolder, restHtml] = splitProps(htmlPropsWithChildren, ['children'])
+    const children = childHolder.children
 
     if (config.mode === 'collapse') {
       return (