@pyreon/kinetic 0.20.0 → 0.22.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, mergeProps, onMount, onUnmount, splitProps } from "@pyreon/core";
+import { Show, createRef, cx, h, mergeProps, onMount, onUnmount, splitProps } from "@pyreon/core";
 import { runUntracked, signal, watch } from "@pyreon/reactivity";
 import { jsx } from "@pyreon/core/jsx-runtime";
 
@@ -172,16 +172,20 @@ const CollapseRenderer = ({ config, htmlProps, show, appear, timeout, transition
 		...stage() !== "entered" ? { overflow: "hidden" } : {},
 		...stage() === "hidden" ? { height: "0px" } : stage() === "entered" ? { height: "auto" } : {}
 	};
-	return h(config.tag, mergeProps(htmlProps, {
-		ref: wrapperRef,
-		style: wrapperStyle
-	}), /* @__PURE__ */ jsx(Show, {
+	const innerContent = show() ? /* @__PURE__ */ jsx(Show, {
 		when: shouldRender,
 		children: /* @__PURE__ */ jsx("div", {
 			ref: contentRef,
 			children
 		})
-	}));
+	}) : /* @__PURE__ */ jsx("div", {
+		ref: contentRef,
+		children
+	});
+	return h(config.tag, mergeProps(htmlProps, {
+		ref: wrapperRef,
+		style: wrapperStyle
+	}), innerContent);
 };
 
 //#endregion
@@ -290,6 +294,9 @@ const cloneVNode = (vnode, extraProps) => ({
 //#endregion
 //#region src/kinetic/TransitionItem.tsx
 const applyEnter$1 = (el, config) => {
+	removeClasses(el, config.leave);
+	removeClasses(el, config.leaveFrom);
+	removeClasses(el, config.leaveTo);
 	addClasses(el, config.enter);
 	addClasses(el, config.enterFrom);
 	if (config.enterStyle) Object.assign(el.style, config.enterStyle);
@@ -393,7 +400,7 @@ const TransitionItem = (props) => {
 			el.style.transition = "";
 		}
 	}, { immediate: true });
-	return /* @__PURE__ */ jsx(Show, {
+	if (props.show()) return /* @__PURE__ */ jsx(Show, {
 		when: shouldMount,
 		fallback: unmount ? null : cloneVNode(props.children, {
 			ref: mergedRef,
@@ -401,6 +408,16 @@ const TransitionItem = (props) => {
 		}),
 		children: cloneVNode(props.children, { ref: mergedRef })
 	});
+	const hiddenClass = props.leaveTo ?? props.enterFrom;
+	const hiddenStyle = props.leaveToStyle ?? props.enterStyle;
+	const childProps = props.children.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);
 };
 
 //#endregion
@@ -531,6 +548,9 @@ const StaggerRenderer = ({ config, htmlProps, show, appear, timeout, interval, r
 //#endregion
 //#region src/kinetic/TransitionRenderer.tsx
 const applyEnter = (el, config) => {
+	removeClasses(el, config.leave);
+	removeClasses(el, config.leaveFrom);
+	removeClasses(el, config.leaveTo);
 	addClasses(el, config.enter);
 	addClasses(el, config.enterFrom);
 	if (config.enterStyle) Object.assign(el.style, config.enterStyle);
@@ -610,7 +630,7 @@ const TransitionRenderer = (props) => {
 			el.style.transition = "";
 		}
 	}, { immediate: true });
-	return /* @__PURE__ */ jsx(Show, {
+	if (props.show()) return /* @__PURE__ */ jsx(Show, {
 		when: shouldMount,
 		fallback: effectiveUnmount ? null : h(props.config.tag, mergeProps(props.htmlProps, {
 			ref: mergedRef,
@@ -621,6 +641,18 @@ const TransitionRenderer = (props) => {
 		}), props.children),
 		children: h(props.config.tag, mergeProps(props.htmlProps, { ref: mergedRef }), props.children)
 	});
+	const hiddenClass = props.config.leaveTo ?? props.config.enterFrom;
+	const hiddenStyle = props.config.leaveToStyle ?? props.config.enterStyle;
+	const childClass = props.htmlProps.class;
+	const mergedClass = hiddenClass ? cx([childClass, hiddenClass]) : void 0;
+	const mergedStyle = hiddenStyle ? {
+		...props.htmlProps.style ?? {},
+		...hiddenStyle
+	} : void 0;
+	const extra = { ref: mergedRef };
+	if (mergedClass !== void 0) extra.class = mergedClass;
+	if (mergedStyle !== void 0) extra.style = mergedStyle;
+	return h(props.config.tag, mergeProps(props.htmlProps, extra), props.children);
 };
 
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/kinetic",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "CSS-transition-based animation components for Pyreon",
   "license": "MIT",
   "repository": {
@@ -42,11 +42,12 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@pyreon/core": "^0.20.0",
-    "@pyreon/reactivity": "^0.20.0",
-    "@pyreon/runtime-dom": "^0.20.0",
-    "@pyreon/test-utils": "^0.13.7",
-    "@pyreon/typescript": "^0.20.0",
+    "@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",
     "@vitest/browser-playwright": "^4.1.4",
     "@vitus-labs/tools-rolldown": "^2.3.0"
   },
@@ -54,8 +55,8 @@
     "node": ">= 22"
   },
   "dependencies": {
-    "@pyreon/core": "^0.20.0",
-    "@pyreon/reactivity": "^0.20.0",
-    "@pyreon/runtime-dom": "^0.20.0"
+    "@pyreon/core": "^0.22.0",
+    "@pyreon/reactivity": "^0.22.0",
+    "@pyreon/runtime-dom": "^0.22.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,83 @@ 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`.
+  // Picker mirrors what #719 introduced for the kinetic(tag).<mode>
+  // renderers (TransitionRenderer / TransitionItem / CollapseRenderer):
+  // prefer leave-end state, fall back to pre-enter state. The
+  // `enterStyle` fallback covers the preset path — `@pyreon/kinetic-presets`
+  // factories (fadeUp, blurInUp, slideLeft, …) populate `enterStyle` as
+  // the hidden state but may not set `leaveToStyle`. Without this
+  // fallback, preset users SSR-render VISIBLE → flash-on-hydration.
+  // (PR #717 shipped this branch with `leaveToStyle` alone; the class
+  // picker already had the `enterFrom` fallback. This commit aligns the
+  // style picker so both halves match.)
+  const hiddenClass = props.leaveTo ?? props.enterFrom
+  const hiddenStyle = props.leaveToStyle ?? props.enterStyle
+  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__/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

@@ -0,0 +1,183 @@
+/**
+ * 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('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, {
+        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-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

@@ -144,4 +144,184 @@ 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()
+  })
+
+  // ── 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/kinetic/CollapseRenderer.tsx

@@ -166,6 +166,39 @@ const CollapseRenderer = ({
     ...(stage() === 'hidden' ? { height: '0px' } : stage() === 'entered' ? { height: 'auto' } : {}),
   }
 
+  // Initially-visible Collapses keep the original Show-gated inner content,
+  // preserving the runtime-unmount semantic that frees the inner subtree
+  // when the collapse is closed long-term. The SSR bug fires only when
+  // `show: () => false` at setup — the outer wrapper renders (with
+  // `height: 0; overflow: hidden`) but its children are stripped by the
+  // inner `<Show when={false}>` → empty wrapper in the prerendered HTML.
+  // Bad for SEO / social scrapers / accessibility / no-JS.
+  //
+  // Mirrors the fix shape applied to `<Transition>` (PR #717), the
+  // `TransitionRenderer` and `TransitionItem` (this PR). Ecosystem norm:
+  // content is structural, animation is visual.
+  //
+  // For initially-hidden Collapses, the inner content always renders —
+  // the outer wrapper's `height: 0px; overflow: hidden` already provides
+  // the visual hiding (genuinely layout-safe — no flex slot collapse;
+  // the outer wrapper participates in flex as a 0-height box, which is
+  // the standard CSS collapse behavior). When `show` flips true, the
+  // existing `watch(stage)` measures `content.scrollHeight` and animates
+  // height from 0 → that value — no change to the animation path.
+  //
+  // Trade-off: for initially-hidden Collapses, the inner subtree is
+  // ALWAYS mounted (never unmounted after a later close). Initially-
+  // visible Collapses keep the unmount behavior. Matches the trade-off
+  // documented across the other three kinetic renderers.
+  const wasInitiallyShown = show()
+  const innerContent = wasInitiallyShown ? (
+    <Show when={shouldRender}>
+      <div ref={contentRef}>{children}</div>
+    </Show>
+  ) : (
+    <div ref={contentRef}>{children}</div>
+  )
+
   // 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
@@ -176,9 +209,7 @@ const CollapseRenderer = ({
   return h(
     config.tag,
     mergeProps(htmlProps, { ref: wrapperRef, style: wrapperStyle }),
-    <Show when={shouldRender}>
-      <div ref={contentRef}>{children}</div>
-    </Show>,
+    innerContent,
   )
 }
 

package/src/kinetic/TransitionItem.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, TransitionCallbacks } from '../types'
 import useAnimationEnd from '../useAnimationEnd'
@@ -19,6 +19,14 @@ type TransitionItemProps = ClassTransitionProps &
   }
 
 const applyEnter = (el: HTMLElement, config: ClassTransitionProps & StyleTransitionProps) => {
+  // Symmetric to applyLeave: clear residual leave-cycle classes — including
+  // the `leaveTo`/`enterFrom` class the SSR/initially-hidden render path
+  // inlines (see the `wasInitiallyShown` branch below). Without this, the
+  // SSR-baked hidden class would compete with `enterTo`'s CSS rules.
+  removeClasses(el, config.leave)
+  removeClasses(el, config.leaveFrom)
+  removeClasses(el, config.leaveTo)
+
   addClasses(el, config.enter)
   addClasses(el, config.enterFrom)
   if (config.enterStyle) Object.assign(el.style, config.enterStyle)
@@ -155,26 +163,68 @@ const TransitionItem = (props: TransitionItemProps): VNode | null => {
     { immediate: true },
   )
 
-  return (
-    <Show
-      when={shouldMount}
-      fallback={
-        unmount
-          ? null
-          : cloneVNode(props.children, {
-              ref: mergedRef,
-              style: mergeStyles(
-                (props.children.props as Record<string, unknown>)?.style as
-                  | Record<string, string | number | undefined>
-                  | undefined,
-                { display: 'none' },
-              ),
-            })
-      }
-    >
-      {cloneVNode(props.children, { ref: mergedRef })}
-    </Show>
+  // Initially-visible items keep the original Show-gated mount, preserving
+  // the documented runtime-unmount semantic for visible→hidden. The SSR
+  // bug (children dropped from prerendered HTML) only fires for the
+  // initially-HIDDEN case below, where `<Show when={false}>` renders `null`
+  // on the server. For Stagger/Group usage at SSR (when the parent's
+  // `show: () => false`), each per-item TransitionItem hit this and
+  // dropped its child — full list missing from prerendered HTML.
+  //
+  // Mirrors the fix in `<Transition>` (PR #717) and `TransitionRenderer`
+  // (same PR as this). Ecosystem norm: content is structural, animation
+  // is visual.
+  const wasInitiallyShown = props.show()
+  if (wasInitiallyShown) {
+    return (
+      <Show
+        when={shouldMount}
+        fallback={
+          unmount
+            ? null
+            : cloneVNode(props.children, {
+                ref: mergedRef,
+                style: mergeStyles(
+                  (props.children.props as Record<string, unknown>)?.style as
+                    | Record<string, string | number | undefined>
+                    | undefined,
+                  { display: 'none' },
+                ),
+              })
+        }
+      >
+        {cloneVNode(props.children, { ref: mergedRef })}
+      </Show>
+    )
+  }
+
+  // Initially-hidden path — always emit the child with hidden-state class +
+  // style inlined. `leaveTo`/`leaveToStyle` (explicit hidden-end state)
+  // wins; falls back to `enterFrom`/`enterStyle` (pre-enter state — covers
+  // both class-based scroll-reveal AND the preset path, where
+  // `@pyreon/kinetic-presets` factories populate `enterStyle` as the
+  // hidden state but may not set `leaveToStyle`).
+  //
+  // Trade-off: for an initially-hidden item, `unmount: true` no longer
+  // triggers a true DOM removal after a later leave animation completes.
+  // 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 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,
   )
+
+  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 TransitionItem

package/src/kinetic/TransitionRenderer.tsx

@@ -1,5 +1,5 @@
 import type { VNode } from '@pyreon/core'
-import { createRef, h, mergeProps, Show } from '@pyreon/core'
+import { createRef, cx, h, mergeProps, Show } from '@pyreon/core'
 import { watch } from '@pyreon/reactivity'
 import type { CSSProperties, TransitionCallbacks } from '../types'
 import useAnimationEnd from '../useAnimationEnd'
@@ -20,6 +20,15 @@ type TransitionRendererProps = {
 }
 
 const applyEnter = (el: HTMLElement, config: KineticConfig) => {
+  // Symmetric to applyLeave's `removeClasses(enter)` / `removeClasses(enterTo)`:
+  // clear residual leave-cycle classes — including the `leaveTo` / `enterFrom`
+  // class the SSR / initially-hidden render path inlines for structural
+  // content (see the `wasInitiallyShown` branch below). Without this, the
+  // SSR-baked hidden-state class would compete with `enterTo`'s CSS rules.
+  removeClasses(el, config.leave)
+  removeClasses(el, config.leaveFrom)
+  removeClasses(el, config.leaveTo)
+
   addClasses(el, config.enter)
   addClasses(el, config.enterFrom)
   if (config.enterStyle) Object.assign(el.style, config.enterStyle)
@@ -131,38 +140,91 @@ const TransitionRenderer = (props: TransitionRendererProps): VNode | null => {
     { immediate: true },
   )
 
-  return (
-    <Show
-      when={shouldMount}
-      fallback={
-        effectiveUnmount
-          ? 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,
-                style: {
-                  ...((props.htmlProps.style as CSSProperties) ?? {}),
-                  display: 'none',
-                },
-              }),
-              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>
-  )
+  // Initially-visible kinetic-mode Transitions keep the original Show-gated
+  // mount, preserving the documented runtime-unmount semantic for the
+  // visible→hidden transition. The SSR bug (children dropped from prerendered
+  // HTML) only fires for the initially-HIDDEN case below, where
+  // `<Show when={false}>` renders `null` on the server — leaving SSG sites
+  // using kinetic-mode transitions (e.g. `kinetic('div').preset(fadeUp)` with
+  // `show: () => false` at SSR, the scroll-reveal pattern via
+  // `useIntersection`) without structural content for SEO / social scrapers
+  // / accessibility tools / no-JS users.
+  //
+  // Mirrors the same fix shape applied to the top-level `<Transition>` in
+  // PR #717. Ecosystem norm (Framer Motion / react-transition-group / react-
+  // spring): content is structural, animation is visual.
+  const wasInitiallyShown = props.show()
+  if (wasInitiallyShown) {
+    return (
+      <Show
+        when={shouldMount}
+        fallback={
+          effectiveUnmount
+            ? 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,
+                  style: {
+                    ...((props.htmlProps.style as CSSProperties) ?? {}),
+                    display: 'none',
+                  },
+                }),
+                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>
+    )
+  }
+
+  // Initially-hidden path — ecosystem-correct: always emit children with
+  // hidden-state class/style inlined so SSG / SEO / social scrapers / no-JS
+  // users see structural content. `leaveTo` (explicit hidden-end state)
+  // wins; falls back to `enterFrom` (pre-enter state) for scroll-reveal
+  // patterns that only configure the enter side. The existing
+  // `watch(stage)` effect drives the enter animation when `show` flips
+  // true; the symmetric `applyEnter` above clears these residual classes.
+  //
+  // Trade-off: for initially-hidden kinetic-mode Transitions, `unmount: true`
+  // no longer triggers a true DOM removal after a later leave animation
+  // completes — element stays in DOM with the leave-to class applied.
+  // Initially-visible Transitions (the branch above) keep the unmount
+  // semantic. Matches Framer Motion / react-transition-group conventions
+  // and is the price of SSR correctness.
+  // Mirrors the class picker: prefer `leaveTo`/`leaveToStyle` (explicit
+  // leave-end / hidden state) and fall back to `enterFrom`/`enterStyle`
+  // (pre-enter state). The fallback covers the preset path —
+  // `@pyreon/kinetic-presets` factories (fadeUp, slideLeft, blurInUp, …)
+  // populate `enterStyle` as the hidden state and may not set
+  // `leaveToStyle` at all; without this fallback, presets would SSR-render
+  // VISIBLE → flash-on-hydration.
+  const hiddenClass = props.config.leaveTo ?? props.config.enterFrom
+  const hiddenStyle = props.config.leaveToStyle ?? props.config.enterStyle
+  const childClass = props.htmlProps.class
+  const mergedClass = hiddenClass
+    ? cx([childClass as Parameters<typeof cx>[0], hiddenClass])
+    : undefined
+  const mergedStyle = hiddenStyle
+    ? { ...((props.htmlProps.style as CSSProperties) ?? {}), ...hiddenStyle }
+    : undefined
+
+  const extra: Record<string, unknown> = { ref: mergedRef }
+  if (mergedClass !== undefined) extra.class = mergedClass
+  if (mergedStyle !== undefined) extra.style = mergedStyle
+
+  return h(props.config.tag, mergeProps(props.htmlProps, extra), props.children)
 }
 
 export default TransitionRenderer