@nerdev/skillset 0.2.1

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

@@ -0,0 +1,150 @@
+# 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. Do not infer it from opacity, DOM presence, or timeline progress.
+
+## Setup
+
+Create one module that imports GSAP and only the plugins the project uses, registers them once, and exports them. Other modules import from it. With a script-tag install, do the same in one file that runs first.
+
+Give every owner a `gsap.context` scoped to its root element:
+
+- Selectors inside the context match only inside that root.
+- `revert()` on the context kills every tween, trigger, and split it created and restores inline styles.
+- Wrap callbacks and event handlers 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.
+
+Write setup so it is correct when it runs more than once on the same node. A bfcache restore, a same-document router revisiting a page, 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.
+- 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. The pre-paint hiding rule in [Page load and unload](page-load.md#initial-state-before-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.
+
+- Put the early marker and independent timer in `head`. Register owner rollback before module setup, initial writes, or split creation. A module that never evaluates cannot run cleanup, so the early script must release its gate unaided.
+- Check `document.readyState` before awaiting `DOMContentLoaded`. Preserve the original deadline through required preparation. For prerendering, arm the visible initialization budget on activation before revealing/starting; retain an activation recovery handler even if the bundle never arrives.
+- Fetch/swap navigation gets a fresh incoming owner before insertion/hiding. Invalidate outgoing entrance recovery before the outro; cancel preparation, frames, and listeners before replacing DOM. Persisted chrome has its own record. An aborted fetch restores the outgoing page only if it remains current.
+- On `pagehide`, invalidate pending work and leave the active page readable for bfcache. On `pageshow.persisted`, restore without replay and prevent old promises/timers from hiding it. Returning from a suspended tab rechecks elapsed deadlines.
+
+## 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 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 remove, replace, hide, or navigate.
+- Kill the active timeline on cleanup, but do not erase state a cover still needs.
+- No `display: none`, `hidden` attribute, or DOM removal before the outro completes.
+
+## Conditional show and hide
+
+Toggling `hidden`, `display`, or removing a node ends it before an outro can play. Add a presence controller where that matters. It should:
+
+- Show into initial state before the intro.
+- Stay in the DOM 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.
+- Hide or 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 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 a router 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 `pagehide` in case the user 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 for anything that depends on it.
+
+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. Read it in a shared `prefersReducedMotion()` helper that every timeline consults, mirror it as a root attribute so CSS can key on it, and rebuild `matchMedia` setups when it changes.
+
+## Scroll
+
+Use `gsap-scrolltrigger` for the API; these rules cover page lifetime and measurement.
+
+- Create triggers in document order. Refresh after fonts, images, or dynamic content change layout, and after scroll restoration on a history navigation.
+- Create triggers inside the owning context. Do not kill all triggers globally when one page leaves.
+- A page can load already scrolled, by reload, hash, or history. Reveal-on-scroll targets above the restored position must not stay hidden. Let the trigger evaluate on creation and keep the pre-paint rule from outliving the initial phase.
+- 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 navigation 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.
+- 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-vanilla/references/page-load.md

@@ -0,0 +1,96 @@
+# Page load and unload
+
+Read this for anything that happens when a document loads, is restored, or is left.
+
+## Load lifecycle
+
+**mount → initial state → intro → settled → outro → end state → unmount**
+
+On a full-document site:
+
+1. **Mount** is parsing. The DOM exists in pieces until parsing ends, and the browser may paint the top of a long page before it does.
+2. **Initial state** is applied before the browser paints. Otherwise the user sees the settled page flash and then vanish into the intro.
+3. **Intro** starts once targets exist and have their sizes: `DOMContentLoaded` for layout, `document.fonts.ready` for text, a specific image's `load` for a layout that depends on it.
+4. **Settled** clears temporary styles and hands the page to CSS.
+5. **Outro** runs on the live page after a link is clicked and before the browser follows it.
+6. **End state** commits the navigation from the completion callback.
+7. **Unmount** is the next document replacing this one. Nothing survives it.
+
+Store the current phase as a data attribute on the page root. CSS and tests read it; nothing infers it from opacity or DOM presence.
+
+## When scripts run
+
+- An inline script in `head` runs before any content is parsed or painted. It is the only place that can set state before first paint in every browser.
+- `defer` and `type="module"` scripts run after parsing and before `DOMContentLoaded`. The DOM is complete, but the browser may already have painted part of it. A deferred script cannot prevent that paint on its own.
+- `async` scripts run whenever they arrive. Do not use them for lifecycle code.
+- `blocking="render"` on a `head` script holds first paint until the script runs. Use it as a guarantee where supported, but keep the inline-script path as the baseline so other browsers do not flash.
+- A module script can run after `DOMContentLoaded` already fired. Check `document.readyState` before waiting on the event.
+
+## Initial state before first paint
+
+Never hide content unconditionally in CSS. A user without JavaScript, a crawler, or a script that failed to load must still see the page.
+
+- The inline `head` script sets a mark on `html` such as `data-motion="js"`. It can also skip the mark entirely under `prefers-reduced-motion`, so the page paints settled and no intro runs. Do not put a `data-phase` on `html`: the page root owns that attribute, and a second one on the document root reads to CSS, tests, and observers as another page changing phase.
+- The page root ships with `data-phase="initial"` in the HTML, and one CSS rule hides intro targets only under the mark and only in that phase, for example `html[data-motion="js"] [data-page][data-phase="initial"] [data-intro] { visibility: hidden }`. It releases the moment the controller changes the phase.
+- The controller writes every target's start values with `gsap.set` or `fromTo` before it changes the phase, so the release never shows the settled state.
+- Use `visibility`, not `display`, so layout is measured with the elements in place.
+
+The marking script arms an independent initialization deadline before hiding. Keep it active through preparation, not just controller registration. Roll back partial styles and split DOM on failure, then restore the current owner. Late work cannot hide a recovered visit. See [Initialization and recovery](initialization.md) for the full contract and checks.
+
+## Waiting for the DOM, fonts, and media
+
+- Build the controller on `DOMContentLoaded`, or immediately if the document is already interactive.
+- Bound any required `document.fonts.ready` or SplitText auto-split preparation by the initialization deadline; use unsplit text on failure.
+- Give images and media `width` and `height` or an aspect ratio so the intro does not wait for them. If a layout depends on an image without dimensions, wait for that image, not the whole `load` event.
+- Refresh ScrollTrigger on `load` and after fonts, since both change document height.
+
+## Navigation type
+
+`performance.getEntriesByType("navigation")[0].type` reports how this document was reached: `navigate`, `reload`, `back_forward`, or `prerender`. Where the Navigation API exists, `navigation.activation.navigationType` reports `push`, `replace`, `reload`, or `traverse`.
+
+- A new navigation gets the full intro.
+- A reload gets the full intro or a shorter one. The user did not arrive anywhere.
+- A history navigation to a fresh document gets an intro-only path with no travel. The user is returning. Never run an outro on the way back; the old page is gone before script hears about it.
+- A prerendered document is handled below.
+
+## Prerendered pages
+
+With Speculation Rules the browser may load and run the next page before the user clicks. `document.prerendering` is true while that happens, and `prerenderingchange` fires once on activation.
+
+Set initial state during prerendering. Start the intro and visible initialization deadline only after activation. Register that deadline’s activation handler in the early script so bundle failure still recovers. A timeline started while prerendering finishes invisibly, and the user gets a settled page with no intro.
+
+`pagereveal` also fires on activation, so a listener there sees prerendered pages and bfcache restores as well as fresh loads.
+
+## The bfcache
+
+When the user leaves, the browser may freeze the document in the back-forward cache instead of destroying it. Coming back restores it as it was, timelines and all, and fires `pageshow` with `persisted` set to true.
+
+- On `pagehide`, finish any outro instantly and leave the page in its readable settled state. That is what the user sees on return.
+- On `pageshow` with `persisted`, do not replay the intro. Refresh ScrollTrigger, resync anything time-based, and resume what was paused.
+- An outro end state that leaves the page faded or covered is a bug the user sees only when pressing back. Clear it in `pagehide`.
+- Never add `unload` listeners. A `beforeunload` listener blocks the bfcache in some browsers unless removed after use. Use `pagehide`, which fires in both cases and reports `persisted`.
+
+## Leaving a page with an outro
+
+There is no router to intercept. Intercept the click.
+
+- Listen on the document for clicks and resolve the closest `a[href]`. Leave native: modified clicks, non-primary buttons, other origins, `target`, `download`, `mailto` and `tel`, hash-only and same-location links, and links marked to opt out.
+- Prevent default, run the outro, then follow the link with `location.assign(href)` from the end-state callback. A navigation started from a click handler still counts as user-initiated for View Transitions.
+- Lock to one navigation. A second click during the outro is ignored, or retargets the destination if the design wants that.
+- Race the outro against a timeout so a stalled timeline never traps the user on the page. GSAP's ticker stops in a hidden tab, so a click from a background tab must still navigate.
+- Form submissions get no outro.
+- Under reduced motion, run the end-state callback immediately.
+
+Prefetch the destination during the outro with `<link rel="prefetch">` or Speculation Rules so the new document is ready when the outro ends. The outro's length is the only budget the network gets.
+
+## Shell chrome
+
+Header, navigation, and footer are rebuilt on every full load. An intro on them plays on every click.
+
+- Play a chrome intro once per session, gated by `sessionStorage`, or not at all.
+- Give chrome a `view-transition-name` so cross-document View Transitions hold it still while the content changes.
+- Keep chrome out of the page outro unless the design wants it to leave.
+
+## Hidden tabs
+
+`requestAnimationFrame` and GSAP's ticker stop in a hidden tab. Anything that awaits a frame or a timeline can wait forever. Race frame waits against a short timeout, and expect timelines to finish when the tab becomes visible.

package/skills/ui/gsap-vanilla/references/spa-navigation.md

@@ -0,0 +1,70 @@
+# Same-document navigation
+
+Read this only when the site fetches pages and swaps content without reloading the document.
+
+## Decide whether to own a router
+
+A same-document router must intercept links, fetch and parse HTML, swap content, update the title and URL, handle back and forward, restore scroll, move focus, re-run page scripts, cancel stale requests, and announce route changes. Swup, Barba, and Taxi do all of that and expose hooks where GSAP fits. Prefer one unless the project already owns a router or the user asks for one.
+
+With a library, everything below still applies. Map its leave and enter hooks to outro and intro, return the timeline's promise so the library waits, and keep the lock, the cover, and cleanup as described.
+
+## Page lifecycle
+
+**mount → initial state → intro → settled → outro → end state → unmount**
+
+1. **Outro.** The link is intercepted and the outgoing content plays its outro on live DOM while the next page is fetched.
+2. **End state.** Outgoing targets finalize and completion runs once. Raise the cover over the route container.
+3. **Unmount and mount.** The router replaces the container's children with the parsed content, updates the title, and pushes the URL.
+4. **Initial state.** The new content is in the DOM, sized, and measured. Start values are written behind the cover.
+5. **Intro.** Lower the cover and play one timeline to settled.
+6. **Settled.** Clear temporary styles. CSS owns the page.
+
+One navigation at a time. The first accepted destination wins through outro, fetch, swap, and cover. Release the lock when the intro starts, not when it ends, so a click mid-intro kills the intro and starts the outro from current values. Abort the in-flight fetch with an `AbortController` when a new destination is accepted.
+
+A killed timeline never resolves its promise. Wrap `await` in a helper that also resolves on `onInterrupt` and returns whether the timeline completed.
+
+## Intercepting links
+
+Listen on the document for clicks and resolve the closest `a[href]`. Leave native: modified clicks, non-primary buttons, other origins, `target`, `download`, `mailto` and `tel`, hash-only and same-location links, and links marked to opt out. Use `pushState` for accepted links and `replaceState` for links marked replace.
+
+Where the Navigation API exists, one `navigate` listener with `event.intercept({ handler })` covers link clicks, form submissions, and programmatic navigation, and reports `navigationType`. Keep the click path as the fallback for browsers without it.
+
+## Fetching and swapping
+
+- Fetch with an `Accept: text/html` header and parse with `DOMParser`. Take the route container's content, the `title`, and any `body` attributes such as `data-page` that pages differ on.
+- Scripts inside fetched HTML do not execute when inserted. Register page setups in one module keyed by `data-page` and call the matching one after the swap. Do not rely on inline page scripts.
+- Stylesheets some pages add must be loaded before those pages are revealed. Append the `link` and wait for its `load` event.
+- Keep one route container. Persistent chrome lives outside it and never reloads. Its state, timelines, and listeners survive navigation, which is the reason to go same-document at all.
+- Overlap old and new only inside a reserved wrapper so one box owns the geometry. Hold the container's height during the swap, or animate it between measured sizes on purpose.
+- Keep the cover inside the route container, not fixed to the viewport, unless the effect is a full-screen wipe on purpose.
+
+## History, scroll, and focus
+
+- Set `history.scrollRestoration` to `manual` and own it. On push, scroll to top or to the hash target after the swap. Save the scroll position in the history state before leaving so `popstate` can restore it after the swap, then refresh ScrollTrigger.
+- Back and forward never run an outro. On `popstate` the URL has already changed. Fetch, swap, and run initial state and intro only, or wrap the swap in `document.startViewTransition` so it is not a hard cut.
+- After the swap, move focus to the route container or its main heading if focus was on removed content or on `body`. Give the target `tabindex="-1"` and a focus style that fits the design.
+- Update `document.title` and announce the new page through a live region.
+- Do not transition to the current URL. Treat search-param changes as page changes only when they mean a different screen.
+
+## Cleanup on unmount
+
+Before replacing the container's children:
+
+- Revert the page's GSAP context, which kills its tweens, triggers, and splits and clears their inline styles.
+- Remove listeners, observers, timers, and plugin instances the page created.
+- Undo anything the page changed outside its container: scroll locks, root attributes, theme, body classes.
+- Do not kill triggers globally. Chrome and the next page own theirs.
+
+## Combining with same-document View Transitions
+
+`document.startViewTransition(() => swap())` snapshots the old content, runs the swap, and animates to the new snapshot. Use it for history navigation and plain crossfades. The rules are the same as cross-document: one engine per element, GSAP intros after `finished` for touched elements, and `::view-transition { pointer-events: none }`.
+
+## Cases to design for
+
+- Navigation requested mid-intro.
+- Two destinations clicked quickly.
+- A fetch that fails or returns something that is not HTML. Fall back to `location.assign`.
+- A slow fetch. The cover stays up; show a hint after a delay.
+- Back or forward with no outro.
+- A page that changes body classes, theme, or scroll lock.
+- A page setup that should run on every visit versus once per session.

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

@@ -0,0 +1,41 @@
+# 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.
+- Confirm the page is readable with JavaScript disabled and with the pre-paint mark set but the main script blocked.
+- 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 first paint. Throttle the network and reload; no settled content flashes.
+- Intro ends in one settled state.
+- Outro keeps the node in the DOM until completion runs.
+- Rapid or interrupted input ends in one coherent state.
+- Layout boxes do not jump.
+
+For full-document navigation, test an ordinary internal link, a reload, back and forward, a link clicked twice quickly, and a click from a background tab. Confirm URL, visible page, focus, history, and scroll agree. Press back after an outro and confirm the restored page is readable, whether it came from the bfcache or a fresh load.
+
+With cross-document View Transitions, confirm no element is animated by both engines, names are cleared after each transition, clicks land during a running transition, and the site still works with the transition unsupported.
+
+For same-document navigation, also test a failed fetch, a slow fetch, and a page that changed body classes or scroll lock.
+
+For conditional components, test show, hide, and one interruption. Confirm removal happens after the outro.
+
+## Builds and wider checks
+
+Run a production build for changes to the build setup, dependencies, or anything release-facing. Run wider browser, accessibility, responsive, 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.