An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): Core hydrates to the server markup; entry animation starts after hydration (#7621)
Cindy Zhangc9f265949703
diff --git a/docs/specs/AST-013/spec.md b/docs/specs/AST-013/spec.mdindex 5d7e0c2dbd..85cfd51a17 100644--- a/docs/specs/AST-013/spec.md+++ b/docs/specs/AST-013/spec.md@@ -14,7 +14,8 @@ affects_architecture:[architecture:layer-runtime, architecture:public-component-api]affects_families: [family:overlay-dismissal]affects_contributing: [contributing:api-conventions]-affects_consumer_docs: [browser-support, useLayer, Popover, Toast, Dialog]+affects_consumer_docs:+ [browser-support, useLayer, Popover, Toast, Dialog, useEntryAnimation]---# Browser and platform support system spec@@ -34,7 +35,8 @@ affects_consumer_docs: [browser-support, useLayer, Popover, Toast, Dialog]"FR8","FR9","FR10",- "FR12"+ "FR12",+ "FR13"]}}@@ -103,11 +105,15 @@ requirements. Assistive-technology evidence remains separately owned.or `NaN` geometry, hide essential content, make controls unreachable, orphan ortrap focus, block the surrounding page, corrupt controlled state, remain stuckpending, or flash a false open, closed, loading, positioned, or styled state.-- **FR9 — SSR and hydration are consistent.** SSR-capable components do not read- browser capability, geometry, input modality, or user-agent state during server- render. The first client render matches the server contract. Post-hydration- enhancement begins from a usable state and introduces no mismatch, broken- intermediate state, or visible false state.+- **FR9 — SSR and hydration are consistent.** A Core component is SSR-capable+ unless its component spec records an FR12 exception. A client directive does+ not exempt a component, because frameworks render client components on the+ server. SSR-capable components do not read browser capability, geometry, input+ modality, paint timing, or user-agent state during server render or during the+ client render that hydrates server markup. The hydrating render produces the+ same markup as the server. Post-hydration enhancement begins from a usable+ state and introduces no mismatch, broken intermediate state, or visible false+ state.- **FR10 — Browser-owned behavior needs real-browser evidence.** Source, unit, andjsdom tests may prove guards and deterministic state. Changes to layout, paint,focus, native Popover or Dialog behavior, top-layer order, browser event timing,@@ -134,6 +140,12 @@ requirements. Assistive-technology evidence remains separately owned.`spec:AST-013` and record only stricter requirements or explicit exceptions. Anexception names the affected capability, observable reduction, preservedFR7–FR9 obligations, evidence, owner, and review condition.+- **FR13 — Server-rendered elements skip their mount animation.** An element present in+ server markup hydrates in its settled state and does not play the animation it+ plays when it mounts (its entry animation). That mount animation plays only for+ an element the client mounts after hydration, or in a client-only root after+ the first paint. Later open, show, and state transitions of a hydrated element+ are outside this requirement, and reduced-motion behavior is unchanged.### Platform support@@ -155,15 +167,27 @@ support. Routine changes may land with evidence appropriate to their claims.Defects reproduced in an explicitly supported browser remain actionable whetheror not an automated lane exists.+`useEntryAnimation`, and FieldStatus through it, decides whether to animate from a+first-paint flag captured on its first render. When markup hydrates after the+page paints, the hydrating render produces entry-animation classes the server did+not send, and the hook's consumer documentation says it does not support server+rendering.++Other known FR9 and FR13 gaps: a Dialog rendered open in server markup plays its+entry animation on page load; CodeBlock's collapse chevron plays its reveal+animation on page load; and CodeBlock chooses between token-span and Highlight+API markup from browser capability and user-agent checks during render, so the+hydrating render can differ from the server's markup.+## Verification-| Contract | Required evidence | Failure signal |-| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| FR1–FR5 | Generated-row check plus guide/package/support/test reconciliation | A handwritten/build version becomes a support claim, explicit support rows disappear, or supported behavior is reduced |-| FR6–FR8 | Feature-present/absent tests and active fallback fixtures | Browser sniffing selects ordinary behavior, or fallback is unusable, inaccessible, unstable, or visibly broken |-| FR9 | Server render, hydration, and post-hydration browser fixture | Markup diverges, browser state is read on the server, or a false/broken state flashes |-| FR10 | Real-browser evidence for browser-owned behavior; the actual named browser for specific claims, browser-only defects, and compatibility changes | Browser-owned behavior is credited to jsdom, another engine stands in for a named-browser claim, or a supported-browser defect is dismissed for lack of a lane |-| FR11–FR12 | Release review and knowledge-record checks | A floor/fallback disappears without compatibility treatment, or a component silently overrides the baseline |+| Contract | Required evidence | Failure signal |+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1–FR5 | Generated-row check plus guide/package/support/test reconciliation | A handwritten/build version becomes a support claim, explicit support rows disappear, or supported behavior is reduced |+| FR6–FR8 | Feature-present/absent tests and active fallback fixtures | Browser sniffing selects ordinary behavior, or fallback is unusable, inaccessible, unstable, or visibly broken |+| FR9, FR13 | Server render then hydrate: no hydration warning or recoverable error, hydrated attributes equal the server markup, a client mount after hydration still plays its mount animation, plus a real-browser server render, hydration, and post-hydration fixture | Markup diverges, browser state is read on the server or while hydrating, a server-rendered element plays its mount animation, or a false/broken state flashes |+| FR10 | Real-browser evidence for browser-owned behavior; the actual named browser for specific claims, browser-only defects, and compatibility changes | Browser-owned behavior is credited to jsdom, another engine stands in for a named-browser claim, or a supported-browser defect is dismissed for lack of a lane |+| FR11–FR12 | Release review and knowledge-record checks | A floor/fallback disappears without compatibility treatment, or a component silently overrides the baseline |## Decision log@@ -191,6 +215,18 @@ browser-specific claim, fixes a defect reproduced only there, or changescompatibility. Missing automation neither narrows support nor justifies dismissinga reproduced defect.+### DEC-3 — Core hydrates to the server markup; server-rendered elements skip their mount animation++**Reference:** `spec:AST-013/DEC-3`+**Decider:** `cixzhang`, `2026-10-15`++Core components render the same markup on the server and in the hydrating client+render, including client components, and a server-rendered element stays settled+rather than playing its mount animation. Rejected: consumer-doc "does not support+SSR" exceptions, because FR12 records exceptions only in component specs.+Rejected: a "has painted" snapshot that turns true after hydration, because it+animates elements present on page load.+## Open questionsNone.