@nerdev/skillset 0.2.1

package/skills/ui/gsap-nextjs/references/motion-system.md

@@ -0,0 +1,158 @@
+# Lifecycle implementation
+
+Read this to implement the five phases for pages and components without layout shift.
+
+## The contract
+
+**mount → initial state → intro → settled → outro → end state → unmount**
+
+One controller owns a node from mount to unmount and exposes one current phase:
+
+1. **Initial state.** Mounted, final size reserved, measured, start values applied, not yet shown.
+2. **Intro.** One timeline from initial values to settled.
+3. **Settled.** Visible, stable, interactive, and controlled by normal CSS.
+4. **Outro.** Still mounted while one timeline moves it toward removal.
+5. **End state.** Still mounted, final values applied, completion run once. Safe to unmount.
+
+The user's request defines how each phase looks. If it only describes an intro or outro, implement the other phases as the minimum needed to enter and leave cleanly.
+
+Store the current phase in state, a ref, or a data attribute. Do not infer it from opacity, DOM presence, or timeline progress.
+
+## Setup and React lifecycle
+
+Create one client-only module that imports GSAP, `useGSAP`, and only the plugins the project uses, and registers them once. Other modules import from it.
+
+Use `useGSAP` in components:
+
+- Pass a root ref as `scope`.
+- Use refs for single targets and scoped selectors for repeated ones.
+- Add dependencies only when the animation must rebuild. Set `revertOnUpdate` when a rebuild needs full cleanup first.
+- Wrap callbacks and event handlers that create GSAP work in `contextSafe`.
+- Return a teardown for listeners and other non-GSAP resources.
+
+Never run GSAP or plugin code during server rendering. Keep the client boundary small; the rest of the page can stay server-rendered.
+
+Do not call another component's `contextSafe` synchronously inside `useGSAP`: its context becomes a child and dies on the outer revert. Hand shared-controller work off through a microtask, effect, or event.
+
+Write setup so it is correct when it runs more than once on the same node. React development checks do this, and with `cacheComponents` a hidden route runs cleanup on hide and setup again on re-show with its settled DOM intact. Async work started by the first run can still be in flight when the second run starts, so anything a setup triggers outside its own context, such as a shared cover, must be safe to request twice. So: explicit initial writes (`set` or `fromTo`) rather than `from` tweens that trust a fresh node, and cleanup that leaves the node readable. Use a ref guard only for work that should happen once per visit rather than once per setup.
+
+## Initial state
+
+Build the final layout with normal CSS first. The initial state changes appearance, not layout. The element that owns geometry must exist before the animated node mounts.
+
+- Mount content before measuring or animating it.
+- Give images and media dimensions or an aspect ratio.
+- Reserve async regions with a wrapper when their size is known.
+- Prefer transforms, `autoAlpha`, masks, or clipping, which keep the layout box.
+
+If the effect changes width, height, or position:
+
+- Animate a transform on an inner element while an outer wrapper holds the settled size.
+- For a real expand or collapse, measure start and end sizes first, animate the wrapper, and decide how surrounding content moves.
+- For layout-to-layout changes, use Flip: capture the old state, apply the new layout, animate.
+- When old and new content share one region, reserve the parent and overlap the children so only the parent affects layout.
+
+Content must stay readable without JavaScript. Any pre-paint hiding rule needs a no-script path.
+
+## Initialization and recovery
+
+Apply the [initialization contract](initialization.md) whenever content starts hidden. It includes recovery ordering, indexing/performance limits, and failure checks.
+
+- Put the early marker and independent deadline in the root document before streamed content can paint. Use the installed Next.js script/CSP integration; verify emitted HTML, ordering, and hydration. A client effect is too late. Keep meaningful content in Server Components or SSR output.
+- In `useGSAP`, register rollback before initial writes or splits. Catch synchronous setup and async callback failures. Keep the initialization timer through preparation; `contextSafe` tracks GSAP resources but does not reject stale promises.
+- Store the visit's recovery decision in the persistent boundary, outside disposable effect setup. React's setup/cleanup replay must not reset it. Streamed or Suspense regions that arrive after recovery stay readable; give separately animated regions their own bounded owner.
+- With `cacheComponents`, invalidate work on hide and scope recovery to the active route. Never reveal a preserved `<Activity>` subtree. A real route re-show can start a new visit; a repeated setup cannot. Keep persistent shell recovery separate and release only the matching cover/focus request.
+
+## Intro and settled
+
+Write reusable intro and outro builders only when behavior repeats. Each returns a timeline so the controller can compose, kill, reverse, or await it.
+
+- Make settled the source of truth. It must not depend on a paused timeline.
+- Clear temporary transform, visibility, transition, and `will-change` styles once settled.
+- Run intro completion and settled callbacks once, including under reduced motion.
+- On rapid state changes, replace, kill, or reverse the active timeline. Do not stack conflicting tweens.
+- Update assistive text and state immediately. Animate the visual, not the meaning.
+
+## Outro and end state
+
+Start the outro from current rendered values. Keep the node mounted, laid out, and owned until the timeline completes.
+
+- Reject duplicate outro requests or define which wins.
+- If an intro is running, reverse it only when the outro is its exact inverse. Otherwise kill it and build the outro from current values.
+- Disable pointer events when the visual can no longer support them, without removing the layout box.
+- Run end-state work once. Only then unmount, replace, hide, or hand off.
+- Kill the active timeline on cleanup, but do not erase state the route cover still needs.
+- No `display: none`, conditional removal, or DOM replacement before the outro completes.
+
+## Conditional show and hide
+
+React unmounts conditional content before an outro can play. Add a presence controller where that matters. It should:
+
+- Mount into initial state before the intro.
+- Stay mounted through settled and outro.
+- Keep the active timeline.
+- On re-show during an outro, reverse only if that gives the intended intro. Otherwise kill, set from current values, and build a fresh intro.
+- Remove the node only after the end-state callback.
+- Keep all five phases under reduced motion.
+
+When content in a shared region changes size, decide who owns the region's geometry before mounting either child. Overlap old and new inside a reserved wrapper, or animate a measured wrapper between known sizes. Do not let unmount then mount push surrounding content twice.
+
+Do not use presence for content that can simply appear, or for routes the transition boundary already manages.
+
+- Focus a panel when its intro completes, not when it mounts. An element at `visibility: hidden` refuses focus silently, and `autoAlpha: 0` is exactly that. Reduced motion jumps to completion synchronously, so the focus still lands.
+- When the outro ends and React is asked to unmount the children, clear only `will-change` from the wrapper. The unmount is queued, not immediate; clearing the collapsed height or visibility in the same tick flashes the content at full size for a frame.
+
+An intercepting-route modal is a presence controller with the router as its unmount. Its close plays the outro and only then calls `router.back()`. Under `cacheComponents` the intercepted page is hidden, not unmounted, so the setup runs again on re-show and everything the modal changed outside itself (scroll lock, key listener, focus, header state) is undone in the effect teardown, which is the only thing that runs on a hide. Treat opening it as an overlay navigation: no outro on the page underneath, no cover, no request lock.
+
+## Reduced and responsive motion
+
+The OS preference is the default. Add an app override only if the product needs one.
+
+Every effect needs initial, settled, and end states under reduced motion. Do not just shorten a disorienting effect. Skip travel, rotation, scale, parallax, and scrambling unless essential. A zero-duration timeline or an immediate `set` still fires completion for anything that depends on it.
+
+Use `gsap.matchMedia()` for responsive and reduced-motion variants that must rebuild when conditions change. Revert it through the owning component. Do not nest a second GSAP context for the same setup.
+
+An app-level override is not a media query, so `matchMedia` cannot see it. Read it in a shared `prefersReducedMotion()` helper that every timeline consults, mirror it as a root attribute so CSS can key on it, and for setups that live inside a `matchMedia` block either gate the block on the store through a hook dependency or accept that the block follows the OS alone and say so.
+
+## Scroll
+
+Use `gsap-scrolltrigger` for the API; these rules cover route lifetime and measurement.
+
+- Create triggers in document order. Refresh after fonts, images, or dynamic content change layout.
+- Create triggers inside the owning context. Do not kill all triggers globally when one page leaves.
+- A route hidden by `<Activity>` measures zero. Create triggers once visible and refresh on re-show after scroll restoration settles. Refresh once more when the page settles if anything above the trigger changed height during the intro.
+- A `useGSAP` context revert calls `revert()` on each trigger with no arguments, which ScrollTrigger treats as `kill(true)`: the pin spacer is removed and the pinned element's original inline styles are restored. Leaving a route mid-pin under `cacheComponents` needs no extra cleanup. `gsap.matchMedia()` created inside the same setup registers with that context and is reverted with it; it is not a second context for the same setup.
+- A `will-change` written from an `onToggle` callback is outside the context and survives its revert. Write it as a plain style and undo it in the matchMedia cleanup, or write it before the trigger is created.
+
+Under reduced motion, go straight from initial to settled without unnecessary triggers. Keep outro and end callbacks that control navigation or unmount.
+
+## Text
+
+Use SplitText when the effect needs per-character, word, or line targets.
+
+- For character splits, keep scoped `font-kerning: none; text-rendering: optimizeSpeed` before, during, and after revert, including reduced motion. Wrappers disrupt kerning and can cause horizontal snapping; use words/lines if natural kerning is essential. See [SplitText limitations](https://gsap.com/docs/v3/Plugins/SplitText/#tips--limitations).
+- Apparent weight changes can be clipped ink: check computed fonts/readiness, then mask edges, punctuation, and descenders. For confirmed clipping, add scoped mask padding with compensating negative margins; verify spacing and both hidden endpoints before trying compositing workarounds.
+- Keep reading accessible with the plugin's ARIA support. If text contains links or controls, keep an unsplit accessible version instead of hiding them.
+- Use word-aware wrapping for character animation. Use auto re-split for line animation that must survive width or font changes.
+- When line measurement needs fonts, bound the wait or auto-split preparation by the [initialization deadline](initialization.md#bound-initialization-not-choreography). Reserve settled height before splitting if wrappers could shift layout.
+- Keep a handle to the split's animation so re-split and cleanup can dispose of it. With `autoSplit`, build the animation inside `onSplit` and return it: the plugin records its playhead before a re-split and restores it on the new lines, and `revert()` undoes the tween's values. With line splitting and `autoSplit`, the plugin waits for fonts itself; no separate font wait is needed.
+- A split heading inside a page takes its timing from the page phase, not its own clock. Hold at initial while the page is initial, rise when the page enters, drop when it leaves. Give it its own pre-paint rule rather than marking it as a page target, or the page's stagger and the split's rise fight over one element.
+- Revert splits on interruption and unmount. Do not leave wrapper spans in stale content.
+
+Revert when the owning phase no longer needs the split. Compare glyph appearance, character positions, wrapping, and height immediately before/after cleanup at desktop/mobile widths, with reduced motion and interruption. Stable boxes alone do not prove stable ink; distinguish subpixel rounding from visible movement.
+
+## Interaction
+
+Pointer motion needs keyboard parity. Pair hover with focus on interactive elements. Do not animate a non-interactive element like a control.
+
+Keep gestures bounded, provide a non-gesture path, and dispose of interaction plugins with their owner. See `gsap-plugins` for Draggable, Observer, and Flip APIs.
+
+## Layout stability and performance
+
+- Prefer `x`, `y`, scale, rotation, and `autoAlpha` over layout properties.
+- Use `clip-path`, filters, and variable-font axes deliberately; they can cost paint or shift layout.
+- Batch reads before writes.
+- The stable wrapper's box should not jump between mount, initial, settled, outro, end, and unmount. Intentional transforms move pixels; layout boxes do not.
+- Set `will-change` just before animating and clear it after. Do not promote everything.
+- Do not animate hundreds of nodes at once. Reduce targets, batch, or virtualize.
+- Do not add a CSS transition on a property GSAP controls.

package/skills/ui/gsap-nextjs/references/verification.md

@@ -0,0 +1,40 @@
+# Verification
+
+Check in proportion to what changed. Do not turn a focused animation task into a full audit.
+
+## Always
+
+- Run the repo's type, lint, format, and test commands where they exist.
+- Confirm settled content is visible, interactive, and free of leftover GSAP inline styles.
+- Confirm timelines, triggers, listeners, and plugin DOM changes are cleaned up.
+- Test reduced motion when the change has a reduced-motion branch.
+
+## Initially hidden content
+
+Run the [failure verification matrix](initialization.md#failure-verification) when adding or changing hiding, preparation, or recovery. It covers disabled JavaScript, a blocked bundle after the marker, throws before/after styles and splits, stalled fonts/media, late initialization, no-flash success, reduced motion, and interruption/repeated setup. Assert text and native links, not opacity alone. Include shell/footer and intentionally hidden content.
+
+Use this framework's [integration rules](motion-system.md#initialization-and-recovery) for rendering and navigation expectations. Measure document-load LCP separately from transitions when first-load behavior changes; report measured results and untested paths.
+
+## Runtime changes
+
+Check the changed lifecycle in a real browser when practical:
+
+- Initial state is applied before reveal.
+- Intro ends in one settled state.
+- Outro keeps the node mounted until completion runs.
+- Rapid or interrupted input ends in one coherent state.
+- Layout boxes do not jump.
+
+For route navigation, test the paths the change affects: an ordinary internal link, back and forward, and a rapid double navigation. Confirm URL, visible route, focus, history, and scroll agree.
+
+With `cacheComponents` on, also navigate away and back. The returning route must re-run initial state and intro on its preserved DOM with no doubled tweens, and scroll triggers must measure correctly after re-show. Use visibility-aware selectors in browser tests, such as role queries or an explicit visible filter, since hidden routes stay in the DOM.
+
+When both `<ViewTransition>` and GSAP are involved, confirm no element is animated by both and that clicks land during a running transition.
+
+For conditional components, test show, hide, and one interruption. Confirm unmount happens after the outro.
+
+## Builds and wider checks
+
+Run a production build for changes to routes, Next config, dependencies, server and client boundaries, or anything release-facing. Run wider browser, accessibility, responsive, streaming, and performance checks only when the change touches them or the user asks for a full audit.
+
+Report which checks ran and which could not. Do not claim runtime behavior was verified when only static review was possible.

package/skills/ui/gsap-nuxt/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: gsap-nuxt
+description: "Build or review Nuxt 3/4 animation: GSAP pageTransition and layoutTransition hooks, component enter/exit, scroll effects, keepalive, and cleanup. Use for interrupted navigation, missing done callbacks, or choosing Vue CSS and View Transitions, even when GSAP is unnamed. Also covers hidden-content recovery and first-load performance. Not for plain Vue or isolated GSAP API questions."
+license: MIT
+metadata:
+  short-description: GSAP page and component lifecycles in Nuxt
+---
+
+# GSAP Nuxt
+
+**mount → initial state → intro → settled → outro → end state → unmount**
+
+Mount and unmount belong to Vue; animation owns the five phases between them. During a Nuxt page leave, the component is torn down while its root element remains until `done`. The transition hooks (`css: false`) must own the outro independently of component cleanup.
+
+Keep the requested look and existing project conventions. Add GSAP/plugins only as needed; do not replace the chosen animation library unless asked.
+
+## Start with the project
+
+Read repository instructions, existing animation, layouts, navigation, CSS, accessibility conventions, and checks. Then:
+
+1. Confirm Nuxt with a `pages/` directory. If the project is plain Vue with Vue Router and no Nuxt, say this skill does not cover it and use `gsap-frameworks`.
+2. Read the installed Nuxt, Vue, and Vue Router versions from `node_modules`. Prefer the installed types and their JSDoc (`node_modules/@nuxt/schema`, `node_modules/nuxt/dist`, `node_modules/@vue/runtime-core/dist`, `node_modules/vue-router/dist`) and that version's docs over memory. Version gates: `onPrehydrate` (3.12), `useRuntimeHook` (3.14), the `app/` source directory (4), view transition types (4.4), `prefetch` in the `<NuxtLink custom>` slot (4.5).
+3. Read `nuxt.config`: `ssr`, `srcDir`, `app.pageTransition`, `app.layoutTransition`, `app.keepalive`, `experimental.viewTransition`, `future.compatibilityVersion`. Nuxt 4 puts `pages/`, `layouts/`, `middleware/`, `plugins/`, `composables/`, `app.vue`, and `router.options.ts` under `app/`; Nuxt 3 keeps them at the root. `~/` resolves to the source directory in both.
+
+## Choose the engine
+
+Use Vue Transition CSS for simple page fades/slides, `experimental.viewTransition` for snapshot morphs, and GSAP JavaScript hooks for live-DOM outros, sequencing, interruption, or controlled overlap. Use one engine per element and do not run Vue hooks and a view transition on the same navigation. See [View Transitions](references/navigation.md#view-transitions).
+
+## Read only what you need
+
+- Invisible entrances, failed initialization, indexing, and first-load performance: [Initialization and recovery](references/initialization.md), plus the [framework integration](references/motion-system.md#initialization-and-recovery).
+- The hooks, `done`, modes, what dies when the leave starts, first load, layouts, direction, interruptions: [Page transitions](references/page-transitions.md).
+- Page keys, keepalive, Nuxt app hooks, scroll and focus, outro before navigation, back and forward, View Transitions, SSR and first paint: [Navigation](references/navigation.md).
+- The five phases, GSAP setup, Vue lifecycle, show and hide, layout stability, scroll, text, plugins: [Lifecycle implementation](references/motion-system.md).
+- Before calling work done: [Verification](references/verification.md).
+
+Install the [official GSAP skills](https://github.com/greensock/gsap-skills) alongside this repository. Load `gsap-core` for API details and `gsap-frameworks` for component setup only as needed.
+
+## Rules
+
+- Preserve invisible intros on successful setup; recover the current incoming owner on failure. Follow the initialization contract before adding hiding rules.
+- GSAP runs only on the client. Guard with `import.meta.client`, `onMounted`, or `<ClientOnly>`. Scope selectors. Clean up every tween, trigger, split, and listener.
+- Reserve final geometry with normal CSS and a stable wrapper; overlap outgoing/incoming content without doubling layout space. Pages and layouts need a single root element or the transition does not run.
+- Mount, then set initial values, then paint. `onBeforeEnter` runs before the incoming root is inserted and `onEnter` right after, before the browser paints. Successful initialization never flashes settled content before the intro.
+- Animate to one settled state and clear temporary styles there.
+- Always call `done`: from `onComplete`, from `onInterrupt`, and synchronously under reduced motion. A leave that never calls `done` leaves the old page in the DOM forever.
+- The page component is unmounted, or deactivated under keepalive, when the leave starts, not when it ends. Its context revert and `onUnmounted` run while the outro plays. Build the outro in `onLeave` against `el`, in a context the hooks own.
+- Keep outgoing pages and components in the DOM through outro and end state. Vue does this as long as `done` waits.
+- The outro cannot start before the incoming page has resolved. Design the wait: the old page stays on screen and interactive.
+- Under keepalive, a page lifecycle runs again on reactivation against DOM that already holds settled values. Never assume a fresh node.
+- Back and forward run the same hooks as a click. Detect history navigation yourself and give it a quieter path. Never fake an outro that did not happen.
+- Never use `appear` on a server-rendered page: Vue's SSR wraps the child of `<Transition appear>` in `<template>`, so the page is blank until hydration and without JavaScript.
+- Keep native link behavior, focus, scroll, and no-JavaScript readability.
+- Reduced motion reaches the same settled state and still calls `done` and every completion callback.
+- Define interruption and rapid-click behavior; completion must release navigation waits exactly once.
+- Verify in a real browser when practical. Use a production build for route, config, dependency, or release changes.

package/skills/ui/gsap-nuxt/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "GSAP Nuxt"
+  short_description: "GSAP page and component lifecycles in Nuxt"
+  default_prompt: "Use $gsap-nuxt to add GSAP page transitions and component animation to this Nuxt app."
+
+policy:
+  allow_implicit_invocation: true

package/skills/ui/gsap-nuxt/references/initialization.md

@@ -0,0 +1,87 @@
+<!-- Generated from shared/initialization.md; run scripts/sync_initialization.py. -->
+
+# Invisible intros, recovery, and first load
+
+Read this whenever an entrance hides meaningful content. The matching framework skill owns initialization, navigation, recovery, and interruption. Motion recipes own teardown and restoration of their changes. Styles select the look and pacing only.
+
+## Keep the successful intro
+
+Build readable, settled HTML and CSS first. Preserve invisible-to-visible entrances with a small early script and scoped pre-paint CSS:
+
+```css
+html[data-motion-boot="pending"] [data-motion-owner][data-phase="initial"][data-intro],
+html[data-motion-boot="pending"] [data-motion-owner][data-phase="initial"] [data-intro] {
+  visibility: hidden;
+}
+```
+
+Names are examples. Use separate attributes for boot status, motion preference, and lifecycle phase. Rename a `data-motion="js"` boot example if the app already uses `data-motion="full|reduced"` for preference. Opt in only targets intended to enter visibly, including hidden ancestors, shell, cards, and footer. Give independent owners their own readiness records. One ready page must not cancel a footer's protection.
+
+- Run the marker before content can paint, using the framework's document integration and CSP nonce/hash support. Arm its recovery timer before setting the marker. It must work without GSAP or the application bundle. If the marker is blocked, content stays readable.
+- Never emit the active marker in server HTML. JavaScript disabled means no marker and readable HTML. A `noscript` override alone does not cover JavaScript enabled with a failed bundle.
+- Skip hiding under reduced motion. Preserve completion, focus, navigation, and removal semantics through the instant path.
+- Before releasing CSS hiding, prepare all required start values and attach the entrance's completion/interruption handlers. Start the timeline in the same turn. Do not flip the phase early to claim readiness: that can flash settled content.
+- Do not hide server content through unconditional CSS, inline styles, client-only wrappers, or a hidden ancestor that the fallback cannot restore.
+
+## Bound initialization, not choreography
+
+Give each incoming owner an initialization deadline, measured from its first pre-paint hiding. Choose and document a short budget; roughly one second is a starting point, not a universal performance target.
+
+The early timer covers bundle delivery and hydration. Register recovery before any setup work, including plugin registration, selectors, initial writes, and splits. Keep the deadline armed through required font/media preparation and timeline construction. Registration or a `live` flag is not readiness. Handing off timers must leave no unprotected interval and must not restart the budget.
+
+A successful handoff occurs only when the prepared intro can run with its handlers attached. Cancel the initialization timer then. A deliberate hold or stagger inside that timeline belongs to animation duration, even if it exceeds the initialization budget. Handle runtime exceptions and interruptions separately; if a running timeline needs a watchdog, derive it from its planned duration, delay, repeats, and pause policy. Never cut a healthy intro short with the boot timer. Recheck deadlines on return from a suspended tab; timers cannot recover a blocked main thread.
+
+Wait only for dependencies the effect needs. Bound font readiness, image load/decode, SplitText auto-split preparation, and frame waits. Prefer reserved image dimensions and a fallback font or unsplit heading over waiting for every font, image, or window `load`. A timed-out promise may still resolve: racing it does not cancel its continuation.
+
+## Recover one owner
+
+Track an owner, a visit/generation token, and a terminal recovery decision outside disposable effect setup. Use boot status such as `pending`, `running`, `recovered`, `disposed` separately from the framework's lifecycle phases. A recovery is permanent for that visit; a genuine later navigation may create a new visit. Repeated setup is not a new visit.
+
+On timeout, rejection, setup exception, or failed entrance:
+
+1. Verify the captured owner and generation are still current and intended to be visible. Invalidate the generation first. Mark it recovered so reentrant handlers cannot restart it.
+2. Abort preparation where supported. Cancel queued frames, timers, event listeners, observers, and subscriptions that can recreate motion. Kill owned timelines, delayed calls, triggers, and ambient effects before restoring content. Do not kill unrelated GSAP work globally.
+3. Run registered effect teardown in reverse order. Each builder must roll back partial changes if it throws before returning a handle. Continue other cleanup if one disposer throws; always reach the final readable fallback.
+4. Revert split wrappers, masks, cloned accessibility text, and plugin DOM changes. Preserve framework-owned nodes and nested links/controls; never overwrite their subtree with a stale HTML snapshot. SplitText revert can reconstruct descendants: split a dedicated text leaf or visual copy when controls, state, or framework bindings must survive. Restore only owned inline properties to their original values, then apply the owner's readable settled state. A marker removal or `autoAlpha: 1` alone cannot undo clipping, transforms, child opacity, or a hidden parent. Avoid `clearProps: "all"` on application-owned styles.
+5. Release only this owner's hiding, cover, busy/inert state, and navigation lock. Apply essential settled completion once, including appropriate focus and transition `done`. Do not replay decorative effects or call an outgoing navigation callback as entrance completion.
+
+The bootstrap must retain a terminal recovery record even before the bundle arrives. With no application changes yet, it can release its CSS gate alone. Once setup starts, it must invoke the registered rollback as well. Releasing a shared document gate must not expose other still-preparing owners; use per-owner gates or transfer every owner's initial values before releasing it.
+
+Every async continuation and controller entry point checks its captured token **before any DOM write or effect creation**, including `set`, `fromTo`, `onSplit`, resize/font callbacks, and `contextSafe` callbacks. Context ownership does not cancel promises. Catch failures inside those callbacks too. Late controller registration reads the terminal boot record and settles without hiding or splitting. Do not infer recovery only from an absent marker that navigation can later recreate.
+
+On navigation, deactivate the outgoing owner's entrance recovery before the outro. Cancel stale work without revealing that owner. Recovery must exclude outgoing/end-state pages, cached hidden routes, closed dialogs, inactive tabs/panels, and decorative clones. Restore the outgoing page only if navigation itself is cancelled and that page becomes current again. Persistent shell elements keep separate visits. Dispose obsolete recovery timers on removal; never let them unlock or focus a newer route.
+
+## Rendering and indexing
+
+Keep primary text, headings, and meaningful links in server-rendered or prerendered HTML where supported. Preserve real `a[href]` links and independently accessible route URLs. Client-only rendering cannot reveal HTML that was never sent; provide a useful static shell/fallback and report that limit. Do not turn an entire page client-only to facilitate animation.
+
+Google renders JavaScript and uses rendered HTML for indexing. An automatic intro does not inherently prevent indexing; that is an inference from Google's rendering model, not a guarantee for a particular page. Check rendered output when indexing is in question. Static hiding rules alone do not establish production indexing failures. See [JavaScript SEO basics](https://developers.google.com/search/docs/crawling-indexing/javascript/javascript-seo-basics).
+
+Do not require a click, scroll, or hover to load primary indexable content. Keep primary hero media eagerly discoverable; reserve lazy loading for appropriate offscreen content. See [Google's lazy-loading guidance](https://developers.google.com/search/docs/crawling-indexing/javascript/lazy-loading).
+
+## First-load performance
+
+Initially hidden primary content can delay Largest Contentful Paint. LCP concerns eligible visible content painted in the viewport, not the end of a GSAP timeline. A heading or hero may become a candidate before the remaining stagger, footer, or ambient animation completes. Browser eligibility and candidate changes matter; do not calculate LCP from total timeline duration. See [Largest Contentful Paint](https://web.dev/articles/lcp).
+
+Reveal primary headings and hero imagery without waiting for unrelated plugins, particle setup, below-fold media, or every font weight. Keep ambitious motion where requested; reduce unnecessary preparation and deliberate blank holds before weakening the effect. Never serve crawler-specific content or use near-zero opacity tricks to manipulate metrics.
+
+Measure cold first loads separately from client-side transitions. Record the LCP element and timestamp, resource timing, layout shift, and a filmstrip under representative network/CPU conditions. Compare normal and reduced motion; use field data when available. Smooth route transitions do not prove fast document loads. Better performance does not promise ranking or indexing outcomes. See [Google's page-experience guidance](https://developers.google.com/search/docs/appearance/page-experience).
+
+## Failure verification
+
+Use the framework's production build and actual rendering mode. For every supported failure, assert meaningful text, usable links, restored owned styles/DOM, and absence of stale cover, lock, focus, or completion effects. Check page and shell owners separately.
+
+| Case | Required observation |
+|---|---|
+| JavaScript disabled | Server/static content and native links work. Client-only routes get their documented static fallback, not invented SSR content. |
+| Bundle blocked after marker | Prove the early marker executed; let its deadline expire. Content becomes readable without application cleanup. |
+| Setup throws before initial writes | Readable settled state; no unresolved completion or navigation wait. |
+| Setup throws after styles or split DOM | Timelines stop, original text/links return, temporary styles and masks disappear. |
+| Fonts/media stall or reject | Bounded fallback. Resolve them afterward and confirm no new hiding or splitting. |
+| Initialization arrives after recovery | Observe multiple frames after release and beyond the old timeline/deadline. No hidden frame or duplicate completion. |
+| Successful delayed startup within budget | Hidden first frame, then full intended intro. No flash of settled content; intentional duration may exceed the boot budget. |
+| Reduced motion | Readable first paint, functional links, normal completion semantics without travel. |
+| Navigation during preparation or intro | One correct destination; stale recovery cannot reveal outgoing/hidden content or unlock/focus the new visit. |
+| Repeated setup, history, and preserved nodes | No duplicate wrappers, listeners, callbacks, or replay after recovery within the same visit. |
+
+Block only application resources in the bundle test, not the early script or stylesheet. Distinguish an intentionally delayed intro from stalled preparation. Record what ran, rendering limitations, and remaining browser/production gaps; these checks do not prove Google indexed the page or establish field LCP.

package/skills/ui/gsap-nuxt/references/motion-system.md

@@ -0,0 +1,161 @@
+# Lifecycle implementation
+
+Read this to implement the five phases for pages and components without layout shift.
+
+## The contract
+
+**mount → initial state → intro → settled → outro → end state → unmount**
+
+One controller owns a node from mount to unmount and exposes one current phase:
+
+1. **Initial state.** In the DOM, final size reserved, measured, start values applied, not yet shown.
+2. **Intro.** One timeline from initial values to settled.
+3. **Settled.** Visible, stable, interactive, and controlled by normal CSS.
+4. **Outro.** Still in the DOM while one timeline moves it toward removal.
+5. **End state.** Still in the DOM, final values applied, completion run once. Safe to remove.
+
+The user's request defines how each phase looks. If it only describes an intro or outro, implement the other phases as the minimum needed to enter and leave cleanly.
+
+Store the current phase in a data attribute on the owned node, or in a ref mirrored to one. Do not infer it from opacity, DOM presence, or timeline progress.
+
+## Setup and Vue lifecycle
+
+Create one client-only module that imports GSAP and only the plugins the project uses, registers them once, and exports them. In Nuxt that is the `useGSAP` composable from `gsap-frameworks` or a `.client.ts` plugin. Other modules import from it.
+
+Give every owner a `gsap.context` scoped to its root:
+
+- Components: create it in `onMounted` with the template ref as scope and revert it in `onBeforeUnmount`. Under keepalive, revert in `onDeactivated` and rebuild in `onActivated`. Both unmount hooks run before a leave transition finishes, so neither is a place for outro work.
+- Pages: the page's context owns settled-state work and reverts at leave start. The transition module owns a second context per `el` for the intro and the outro, created in `onBeforeEnter` or `onLeave` and reverted in `onAfterEnter` or `onAfterLeave`.
+- Selectors inside a context match only inside its root. `revert()` kills every tween, trigger, and split it created and restores inline styles.
+- Wrap event handlers and delayed callbacks that create GSAP work in `context.add` so they belong to the context.
+- Store listeners, observers, and timers next to the context and remove them in the same cleanup.
+
+Wait for the DOM before measuring. After a reactive change that alters the template, `await nextTick()` before reading sizes or refreshing ScrollTrigger. Content inside `<ClientOnly>` appears only after mount; watch its template ref.
+
+Inside `<NuxtPage>` a page's `onMounted` runs when its Suspense resolves: on navigation that is at leave start or after the leave depending on `mode`, and on first load it is after hydration. Component-level setup belongs there; page-level phases belong to the transition hooks.
+
+Write setup so it is correct when it runs more than once on the same node. `onActivated` under keepalive, development hot reload, and a presence controller re-showing content all hand you a node that already holds settled values. Write initial state explicitly with `set` or `fromTo` rather than a `from` tween that trusts a fresh node, and make cleanup leave the node readable.
+
+## Initial state
+
+Build the final layout with normal CSS first. The initial state changes appearance, not layout. The element that owns geometry must exist before the animated node does.
+
+- Mount content before measuring or animating it.
+- Give images and media dimensions or an aspect ratio; `<NuxtImg>` and `<NuxtPicture>` take `width` and `height`.
+- Reserve async regions with a wrapper when their size is known. A `useAsyncData` region that resolves after mount is a component with its own controller.
+- Prefer transforms, `autoAlpha`, masks, or clipping, which keep the layout box.
+
+If the effect changes width, height, or position:
+
+- Animate a transform on an inner element while an outer wrapper holds the settled size.
+- For a real expand or collapse, measure start and end sizes first, animate the wrapper, and decide how surrounding content moves.
+- For layout-to-layout changes, use Flip: capture the old state, apply the new layout, `await nextTick()`, animate.
+- When old and new content share one region, reserve the parent and overlap the children so only the parent affects layout.
+
+Content must stay readable without JavaScript. The pre-paint rule in [SSR and first paint](navigation.md#ssr-and-first-paint) is the only sanctioned way to hide before the intro.
+
+## Initialization and recovery
+
+Apply the [initialization contract](initialization.md) whenever content starts hidden. It includes recovery ordering, indexing/performance limits, and failure checks.
+
+- Use the early head script described in [SSR and first paint](navigation.md#ssr-and-first-paint), with its own timer. Preserve SSR HTML; `ClientOnly`/`ssr: false` cannot supply missing page content without JavaScript.
+- Register rollback before first-load `onMounted` setup and before navigation's `onBeforeEnter` writes. Keep the deadline through preparation and `onEnter` timeline construction. Catch failures in both hooks and deferred callbacks; claiming the document does not cancel recovery.
+- Keep per-element records outside the page context that Nuxt may revert at leave start. Wrap each hook's `done` once and release it on completion, recovery, or cancellation as appropriate. A cancelled enter must not run stale `onAfterEnter` focus or reveal a leaving page.
+- Invalidate before leave, unmount, and keepalive deactivation; do not reveal keepalive storage. A real activation starts a new visit after layout is available. Persistent layouts/chrome retain their own records, including when `pageTransition: false`.
+
+## Intro and settled
+
+Write reusable intro and outro builders only when behavior repeats. Each returns a timeline so the controller can compose, kill, reverse, or await it, and each takes the `done` callback when a Vue hook drives it.
+
+- Make settled the source of truth. It must not depend on a paused timeline.
+- Clear temporary transform, visibility, transition, and `will-change` styles once settled.
+- Run intro completion and settled callbacks once, including under reduced motion.
+- On rapid state changes, replace, kill, or reverse the active timeline. Do not stack conflicting tweens.
+- Update assistive text and state immediately. Animate the visual, not the meaning.
+
+## Outro and end state
+
+Start the outro from current rendered values. Keep the node in the DOM, laid out, and owned until the timeline completes.
+
+- Reject duplicate outro requests or define which wins.
+- If an intro is running, reverse it only when the outro is its exact inverse. Otherwise kill it and build the outro from current values.
+- Disable pointer events when the visual can no longer support them, without removing the layout box.
+- Run end-state work once. Only then call `done`, remove, hide, or navigate.
+- Kill the active timeline on cleanup, but do not erase state a cover still needs.
+- No `v-if` toggle, `v-show` off, `display: none`, or DOM removal before the outro completes.
+
+## Conditional show and hide
+
+Vue's `<Transition>` is the presence controller. Wrap the conditional node in `<Transition :css="false">` with the same JavaScript hooks pages use. It should:
+
+- Show into initial state in `onBeforeEnter`, before the intro in `onEnter`.
+- Stay in the DOM through settled and through `onLeave` until `done`.
+- Keep the active timeline where the hooks can kill it.
+- Keep all five phases under reduced motion and still call `done`.
+
+Choose the toggle by what re-show during an outro should do. With `v-show`, the same element stays: Vue fires `onLeaveCancelled` and starts `onEnter` on it, so reverse is possible when it gives the intended intro. With `v-if`, Vue finishes the pending leave at once and mounts a fresh node, so build a fresh intro from initial state. Wrap a component only if it has a single root element.
+
+`appear` is safe only on content that is not server-rendered. On SSR output it wraps the child in `<template>` and hides it until hydration.
+
+Use `<TransitionGroup>` for lists. The same hooks run once per item with that item's `el`; read a `data-index` attribute for stagger, give every item a key, and set `:css="false"`. Its move animation is CSS-only, so use Flip when moves must be sequenced with GSAP.
+
+When content in a shared region changes size, decide who owns the region's geometry before showing either child. Overlap old and new inside a reserved wrapper, or animate a measured wrapper between known sizes. Do not let hide then show push surrounding content twice.
+
+Do not use presence for content that can simply appear, or for page content `<NuxtPage>` already manages.
+
+- Focus a panel when its intro completes, not when it is shown. An element at `visibility: hidden` refuses focus silently, and `autoAlpha: 0` is exactly that. Reduced motion completes synchronously, so the focus still lands.
+- A dialog or menu that locks scroll, traps focus, or adds a key listener undoes all of it in its end-state callback, and again in `onBeforeUnmount` or `onDeactivated` in case its page leaves mid-open.
+
+## Reduced and responsive motion
+
+The OS preference is the default. Add a site override only if the product needs one.
+
+Every effect needs initial, settled, and end states under reduced motion. Do not just shorten a disorienting effect. Skip travel, rotation, scale, parallax, and scrambling unless essential. A zero-duration timeline or an immediate `set` still fires completion, and every Vue hook still calls `done`.
+
+Use `gsap.matchMedia()` for responsive and reduced-motion variants that must rebuild when conditions change. Create it inside the owner's context so it reverts with the owner.
+
+A site-level override is not a media query, so `matchMedia` cannot see it. Keep it in `useState` or a store, read it in a shared `prefersReducedMotion()` helper that every builder consults, mirror it as a root attribute so CSS can key on it, and rebuild `matchMedia` setups when it changes. `experimental.viewTransition: true` already skips the browser side under the OS preference.
+
+## Scroll
+
+Use `gsap-scrolltrigger` for the API; these rules cover route lifetime and measurement.
+
+- Create triggers in document order. Refresh after fonts, images, or async data change layout, after `await nextTick()`, and after Nuxt's post-transition scroll.
+- Create triggers inside the owning context. Do not kill all triggers globally when one page leaves.
+- Nuxt scrolls after the outro and one frame into the intro. Create page-level triggers in `onAfterEnter`, or after `page:transition:finish` plus a frame, and let them evaluate on creation so targets above the restored position are not left hidden.
+- A page in keepalive storage measures zero. Kill triggers in `onDeactivated` and create them again in `onActivated` after the scroll settles.
+- Reverting a pinned trigger removes its spacer. That happens at leave start, so hold the wrapper's height through the outro.
+- A `will-change` written from an `onToggle` callback is outside the context and survives its revert. Write it as a plain style and undo it in cleanup, or write it before the trigger is created.
+
+Under reduced motion, go straight from initial to settled without unnecessary triggers. Keep outro and end callbacks that control `done` or removal.
+
+## Text
+
+Use SplitText when the effect needs per-character, word, or line targets.
+
+- For character splits, keep scoped `font-kerning: none; text-rendering: optimizeSpeed` before, during, and after revert, including reduced motion. Wrappers disrupt kerning and can cause horizontal snapping; use words/lines if natural kerning is essential. See [SplitText limitations](https://gsap.com/docs/v3/Plugins/SplitText/#tips--limitations).
+- Apparent weight changes can be clipped ink: check computed fonts/readiness, then mask edges, punctuation, and descenders. For confirmed clipping, add scoped mask padding with compensating negative margins; verify spacing and both hidden endpoints before trying compositing workarounds.
+- Keep reading accessible with the plugin's ARIA support. If text contains links or controls, keep an unsplit accessible version instead of hiding them.
+- Use word-aware wrapping for character animation. Use auto re-split for line animation that must survive width or font changes.
+- When line measurement needs fonts, bound the wait or auto-split preparation by the [initialization deadline](initialization.md#bound-initialization-not-choreography). Reserve settled height before splitting if wrappers could shift layout.
+- With `autoSplit`, build the animation inside `onSplit` and return it. The plugin records the playhead before a re-split, restores it on the new lines, and waits for fonts itself.
+- A split heading takes its timing from the page phase, not its own clock. Give it its own pre-paint rule rather than marking it as a page target, or the page's stagger and the split's rise fight over one element.
+- Split after hydration, never in server-rendered markup. Revert splits on interruption, on leave, and on deactivate. Do not leave wrapper spans in stale content.
+
+Revert when the owning phase no longer needs the split. Compare glyph appearance, character positions, wrapping, and height immediately before/after cleanup at desktop/mobile widths, with reduced motion and interruption. Stable boxes alone do not prove stable ink; distinguish subpixel rounding from visible movement.
+
+## Interaction
+
+Pointer motion needs keyboard parity. Pair hover with focus on interactive elements. Do not animate a non-interactive element like a control.
+
+Keep gestures bounded, provide a non-gesture path, and dispose of interaction plugins with their owner. See `gsap-plugins` for Draggable, Observer, and Flip APIs.
+
+## Layout stability and performance
+
+- Prefer `x`, `y`, scale, rotation, and `autoAlpha` over layout properties.
+- Use `clip-path`, filters, and variable-font axes deliberately; they can cost paint or shift layout.
+- Batch reads before writes.
+- The stable wrapper's box should not jump between mount, initial, settled, outro, end, and unmount. Intentional transforms move pixels; layout boxes do not.
+- Set `will-change` just before animating and clear it after. Do not promote everything.
+- Do not animate hundreds of nodes at once. Reduce targets, batch, or virtualize.
+- Do not add a CSS transition on a property GSAP controls, and do not leave Vue transition classes active on a GSAP-driven root; `css: false` prevents that.