@nerdev/skillset 0.2.1

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

@@ -0,0 +1,284 @@
+---
+name: gsap-utils
+description: Official GSAP skill for gsap.utils — clamp, mapRange, normalize, interpolate, random, snap, toArray, wrap, pipe. Use when the user asks about gsap.utils, clamp, mapRange, random, snap, toArray, wrap, or helper utilities in GSAP.
+license: MIT
+---
+
+# gsap.utils
+
+## When to Use This Skill
+
+Apply when writing or reviewing code that uses **gsap.utils** for math, array/collection handling, unit parsing, or value mapping in animations (e.g. mapping scroll to a value, randomizing, snapping to a grid, or normalizing inputs).
+
+**Related skills:** Use with **gsap-core**, **gsap-timeline**, and **gsap-scrolltrigger** when building animations; CustomEase and other easing utilities are in **gsap-plugins**.
+
+## Overview
+
+**gsap.utils** provides pure helpers; no need to register. Use in tween vars (e.g. function-based values), in ScrollTrigger or Observer callbacks, or in any JS that drives GSAP. All are on **gsap.utils** (e.g. `gsap.utils.clamp()`).
+
+**Omitting the value: function form.** Many utils accept the value to transform as the **last** argument. If you omit that argument, the util returns a **function** that accepts the value later. Use the function form when you need to clamp, map, normalize, or snap many values with the same config (e.g. in a mousemove handler or tween callback). **Exception: random()** — pass **true** as the last argument to get a reusable function (do not omit the value); see [random()](https://gsap.com/docs/v3/GSAP/UtilityMethods/random()).
+
+```javascript
+// With value: returns the result
+gsap.utils.clamp(0, 100, 150); // 100
+
+// Without value: returns a function you call with the value later
+let c = gsap.utils.clamp(0, 100);
+c(150);  // 100
+c(-10);  // 0
+```
+
+## Clamping and Ranges
+
+### clamp(min, max, value?)
+
+Constrains a value between min and max. Omit **value** to get a function: `clamp(min, max)(value)`.
+
+```javascript
+gsap.utils.clamp(0, 100, 150); // 100
+gsap.utils.clamp(0, 100, -10); // 0
+
+let clampFn = gsap.utils.clamp(0, 100);
+clampFn(150); // 100
+```
+
+### mapRange(inMin, inMax, outMin, outMax, value?)
+
+Maps a value from one range to another. Use when converting scroll position, progress (0–1), or input range to an animation range. Omit **value** to get a function: `mapRange(inMin, inMax, outMin, outMax)(value)`.
+
+```javascript
+gsap.utils.mapRange(0, 100, 0, 500, 50);  // 250
+gsap.utils.mapRange(0, 1, 0, 360, 0.5);   // 180 (progress to degrees)
+
+let mapFn = gsap.utils.mapRange(0, 100, 0, 500);
+mapFn(50);  // 250
+```
+
+### normalize(min, max, value?)
+
+Returns a value normalized to 0–1 for the given range. Inverse of mapping when the target range is 0–1. Omit **value** to get a function: `normalize(min, max)(value)`.
+
+```javascript
+gsap.utils.normalize(0, 100, 50);   // 0.5
+gsap.utils.normalize(100, 300, 200); // 0.5
+
+let normFn = gsap.utils.normalize(0, 100);
+normFn(50); // 0.5
+```
+
+### interpolate(start, end, progress?)
+
+Interpolates between two values at a given progress (0–1). Handles numbers, colors, and objects with matching keys. Omit **progress** to get a function: `interpolate(start, end)(progress)`.
+
+```javascript
+gsap.utils.interpolate(0, 100, 0.5);       // 50
+gsap.utils.interpolate("#ff0000", "#0000ff", 0.5); // mid color
+gsap.utils.interpolate({ x: 0, y: 0 }, { x: 100, y: 50 }, 0.5); // { x: 50, y: 25 }
+
+let lerp = gsap.utils.interpolate(0, 100);
+lerp(0.5); // 50
+```
+
+## Random and Snap
+
+### random(minimum, maximum[, snapIncrement, returnFunction]) / random(array[, returnFunction])
+
+Returns a random number in the range **minimum**–**maximum**, or a random element from an **array**. Optional **snapIncrement** snaps the result to the nearest multiple (e.g. `5` → multiples of 5). **To get a reusable function**, pass **true** as the last argument (**returnFunction**); the returned function takes no args and returns a new random value each time. This is the only util that uses `true` for the function form instead of omitting the value.
+
+```javascript
+// immediate value: number in range
+gsap.utils.random(-100, 100);        // e.g. 42.7
+gsap.utils.random(0, 500, 5);        // 0–500, snapped to nearest 5
+
+// reusable function: pass true as last argument
+let randomFn = gsap.utils.random(-200, 500, 10, true);
+randomFn();  // random value in range, snapped to 10
+randomFn();  // another random value
+
+// array: pick one value at random
+gsap.utils.random(["red", "blue", "green"]);  // "red", "blue", or "green"
+let randomFromArray = gsap.utils.random([0, 100, 200], true);
+randomFromArray();  // 0, 100, or 200
+```
+
+**String form in tween vars:** use `"random(-100, 100)"`, `"random(-100, 100, 5)"`, or `"random([0, 100, 200])"`; GSAP evaluates it per target.
+
+```javascript
+gsap.to(".box", { x: "random(-100, 100, 5)", duration: 1 });
+gsap.to(".item", { backgroundColor: "random([red, blue, green])" });
+```
+
+### snap(snapTo, value?)
+
+Snaps a value to the nearest multiple of **snapTo**, or to the nearest value in an array of allowed values. Omit **value** to get a function: `snap(snapTo)(value)` (or `snap(snapArray)(value)`).
+
+```javascript
+gsap.utils.snap(10, 23);     // 20
+gsap.utils.snap(0.25, 0.7);  // 0.75
+gsap.utils.snap([0, 100, 200], 150); // 100 or 200 (nearest in array)
+
+let snapFn = gsap.utils.snap(10);
+snapFn(23); // 20
+```
+
+Use in tweens for grid or step-based animation:
+
+```javascript
+gsap.to(".x", { x: 200, snap: { x: 20 } });
+```
+
+### shuffle(array)
+
+Returns a new array with the same elements in random order. Use for randomizing order (e.g. stagger from "random" with a copy).
+
+```javascript
+gsap.utils.shuffle([1, 2, 3, 4]); // e.g. [3, 1, 4, 2]
+```
+
+### distribute(config)
+
+**Returns a function** that assigns a value to each target based on its position in the array (or in a grid). Used internally for advanced staggers; use it whenever you need values spread across many elements (e.g. scale, opacity, x, delay). The returned function receives `(index, target, targets)` — either call it manually or pass the result directly into a tween; GSAP will call it per target with index, element, and array.
+
+**Config (all optional):**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `base` | Number | Starting value. Default `0`. |
+| `amount` | Number | Total to distribute across all targets (added to base). E.g. `amount: 1` with 100 targets → 0.01 between each. Use **each** instead to set a fixed step per target. |
+| `each` | Number | Amount to add between each target (added to base). E.g. `each: 1` with 4 targets → 0, 1, 2, 3. Use **amount** instead to split a total. |
+| `from` | Number \| String \| Array | Where distribution starts: index, or `"start"`, `"center"`, `"edges"`, `"random"`, `"end"`, or ratios like `[0.25, 0.75]`. Default `0`. |
+| `grid` | String \| Array | Use grid position instead of flat index: `[rows, columns]` (e.g. `[5, 10]`) or `"auto"` to detect. Omit for flat array. |
+| `axis` | String | For grid: limit to one axis (`"x"` or `"y"`). |
+| `ease` | Ease | Distribute values along an ease curve (e.g. `"power1.inOut"`). Default `"none"`. |
+
+**In a tween:** pass the result of `distribute(config)` as the property value; GSAP calls the function for each target with `(index, target, targets)`.
+
+```javascript
+// Scale: middle elements 0.5, outer edges 3 (amount 2.5 distributed from center)
+gsap.to(".class", {
+  scale: gsap.utils.distribute({
+    base: 0.5,
+    amount: 2.5,
+    from: "center"
+  })
+});
+```
+
+**Manual use:** call the returned function with `(index, target, targets)` to get the value for that index.
+
+```javascript
+const distributor = gsap.utils.distribute({
+  base: 50,
+  amount: 100,
+  from: "center",
+  ease: "power1.inOut"
+});
+const targets = gsap.utils.toArray(".box");
+const valueForIndex2 = distributor(2, targets[2], targets);
+```
+
+See [distribute()](https://gsap.com/docs/v3/GSAP/UtilityMethods/distribute/) for more.
+
+## Units and Parsing
+
+### getUnit(value)
+
+Returns the unit string of a value (e.g. `"px"`, `"%"`, `"deg"`). Use when normalizing or converting values.
+
+```javascript
+gsap.utils.getUnit("100px");   // "px"
+gsap.utils.getUnit("50%");     // "%"
+gsap.utils.getUnit(42);        // "" (unitless)
+```
+
+### unitize(value, unit)
+
+Appends a unit to a number, or returns the value as-is if it already has a unit. Use when building CSS values or tween end values.
+
+```javascript
+gsap.utils.unitize(100, "px");  // "100px"
+gsap.utils.unitize("2rem", "px"); // "2rem" (unchanged)
+```
+
+### splitColor(color, returnHSL?)
+
+Converts a color string into an array: **[red, green, blue]** (0–255), or **[red, green, blue, alpha]** (4 elements for RGBA when alpha is present or required). Pass **true** as the second argument (**returnHSL**) to get **[hue, saturation, lightness]** or **[hue, saturation, lightness, alpha]** (HSL/HSLA) instead. Works with `"rgb()"`, `"rgba()"`, `"hsl()"`, `"hsla()"`, hex, and named colors (e.g. `"red"`). Use when animating color components or building gradients. See [splitColor()](https://gsap.com/docs/v3/GSAP/UtilityMethods/splitColor/).
+
+```javascript
+gsap.utils.splitColor("red");                    // [255, 0, 0]
+gsap.utils.splitColor("#6fb936");                // [111, 185, 54]
+gsap.utils.splitColor("rgba(204, 153, 51, 0.5)"); // [204, 153, 51, 0.5] (4 elements)
+gsap.utils.splitColor("#6fb936", true);          // [94, 55, 47] (HSL: hue, saturation, lightness)
+```
+
+## Arrays and Collections
+
+### selector(scope)
+
+Returns a scoped selector function that finds elements only within the given element (or ref). Use in components so selectors like `".box"` match only descendants of that component, not the whole document. Accepts a DOM element or a ref (e.g. React ref; handles `.current`).
+
+```javascript
+const q = gsap.utils.selector(containerRef);
+q(".box");        // array of .box elements inside container
+gsap.to(q(".circle"), { x: 100 });
+```
+
+### toArray(value, scope?)
+
+Converts a value to an array: selector string (scoped to element), NodeList, HTMLCollection, single element, or array. Use when passing mixed inputs to GSAP (e.g. targets) and a true array is needed.
+
+```javascript
+gsap.utils.toArray(".item");           // array of elements
+gsap.utils.toArray(".item", container); // scoped to container
+gsap.utils.toArray(nodeList);          // [ ... ] from NodeList
+```
+
+### pipe(...functions)
+
+Composes functions: **pipe(f1, f2, f3)(value)** returns f3(f2(f1(value))). Use when applying a chain of transforms (e.g. normalize → mapRange → snap) in a tween or callback.
+
+```javascript
+const fn = gsap.utils.pipe(
+  (v) => gsap.utils.normalize(0, 100, v),
+  (v) => gsap.utils.snap(0.1, v)
+);
+fn(50); // normalized then snapped
+```
+
+### wrap(min, max, value?)
+
+Wraps a value into the range min–max (inclusive min, exclusive max). Use for infinite scroll or cyclic values. Omit **value** to get a function: `wrap(min, max)(value)`.
+
+```javascript
+gsap.utils.wrap(0, 360, 370);  // 10
+gsap.utils.wrap(0, 360, -10);   // 350
+
+let wrapFn = gsap.utils.wrap(0, 360);
+wrapFn(370); // 10
+```
+
+### wrapYoyo(min, max, value?)
+
+Wraps value in range with a yoyo (bounces at ends). Use for back-and-forth within a range. Omit **value** to get a function: `wrapYoyo(min, max)(value)`.
+
+```javascript
+gsap.utils.wrapYoyo(0, 100, 150); // 50 (bounces back)
+
+let wrapY = gsap.utils.wrapYoyo(0, 100);
+wrapY(150); // 50
+```
+
+## Best practices
+
+- ✅ Omit the value argument to get a reusable function when the same range/config is used many times (e.g. scroll handler, tween callback): `let mapFn = gsap.utils.mapRange(0, 1, 0, 360); mapFn(progress)`.
+- ✅ Use **snap** for grid-aligned or step-based values; use **toArray** when GSAP or your code needs a real array from a selector or NodeList.
+- ✅ Use **gsap.utils.selector(scope)** in components so selectors are scoped to a container or ref.
+
+## Do Not
+
+- ❌ Assume **mapRange** / **normalize** handle units; they work on numbers. Use **getUnit** / **unitize** when units matter.
+- ❌ Override or rely on undocumented behavior; stick to the documented API.
+
+### Learn More
+
+https://gsap.com/docs/v3/HelperFunctions

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

@@ -0,0 +1,63 @@
+---
+name: gsap-vanilla
+description: "Build or review animation on plain HTML/CSS/JavaScript sites: GSAP page intros/outros, component show/hide, scroll effects, cross-document View Transitions, bfcache, and fetch/swap navigation with Swup, Barba, or Taxi. Use for first-paint flashes or interrupted navigation, even when GSAP is unnamed. Also covers hidden-content recovery and first-load performance. Not for component frameworks or isolated GSAP API questions."
+license: MIT
+metadata:
+  short-description: GSAP page and component lifecycles on plain HTML sites
+---
+
+# GSAP Vanilla
+
+**mount → initial state → intro → settled → outro → end state → unmount**
+
+On full document loads, the browser owns mount and unmount; animation owns the five phases between them. On same-document swaps, the router owns node replacement and persistent resources need explicit 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. Find out how pages are produced: hand-written HTML, a static generator with no client framework, a bundler such as Vite with no UI framework, or a transition library such as Swup, Barba, or Taxi. If a component framework renders the pages, say this skill does not cover it and use that framework's skill.
+2. Find out how GSAP loads: npm import, import map, or script tag. Keep it.
+3. Find out how scripts run: inline, `defer`, or `type="module"`. This decides when the DOM exists and whether the page can paint before the script runs.
+4. Check the target browsers. Cross-document View Transitions, `pageswap` and `pagereveal`, the Navigation API, and `blocking="render"` are not everywhere. Read installed transition-library docs/types and feature-detect browser APIs instead of trusting memory, and make sure the site works with all of them missing.
+
+## Pick a navigation model
+
+Identify the navigation model before writing lifecycle code. Assign one owner per navigation; a same-document router may still need a full-load fallback.
+
+- **Full document loads.** Every link replaces the document. The outro plays before the link is followed; the intro plays when the new page loads. This is the default and needs no router.
+- **Full document loads with cross-document View Transitions.** The browser snapshots the old page and animates to the new one. GSAP fills in what a snapshot pair cannot do.
+- **Same-document navigation.** Script fetches the next page and swaps content in place, so chrome, state, and timelines survive. Use a maintained library unless the project already owns a router or has a reason to. See [Same-document navigation](references/spa-navigation.md).
+
+## Choose the engine
+
+Use cross-document View Transitions for snapshot morphs or page crossfades, with an instant-swap fallback. Use GSAP for live-DOM outros that gate navigation, interruptible sequences, split text, or scroll-linked motion. One engine per element; see [combining engines](references/cross-document-navigation.md#combining-with-gsap).
+
+## 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).
+- First paint, script timing, fonts, navigation type, prerendering, the bfcache, hidden tabs, and leaving a page with an outro: [Page load and unload](references/page-load.md).
+- `@view-transition`, `pageswap`, `pagereveal`, types, render blocking, and handing off between the browser and GSAP: [Cross-document navigation](references/cross-document-navigation.md).
+- Fetch and swap routers, link interception, history, scroll, focus, script re-execution, and when to use a library: [Same-document navigation](references/spa-navigation.md).
+- The five phases, GSAP setup, contexts, 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 the relevant plugin skill 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 after the DOM it targets exists. Scope selectors with `gsap.context` to the page or component root. Clean up every tween, trigger, split, and listener when its owner goes away.
+- Reserve final geometry with normal CSS and a stable wrapper; overlap outgoing/incoming content without doubling layout space.
+- Set initial values before first paint, then reveal. Successful initialization never flashes settled content before the intro, and never a blank page without JavaScript.
+- Animate to one settled state and clear temporary styles there.
+- Keep outgoing content in the DOM and visible through outro and end state. Follow the link, remove the node, or swap only from the end callback.
+- Back and forward never run an outro. A fresh document reached by history gets an intro-only path, and a bfcache restore gets no intro at all.
+- A prerendered page sets initial state at once and waits for activation before it animates.
+- Keep native link behavior, focus, scroll restoration, and no-JavaScript readability.
+- Never add `unload` or `beforeunload` listeners for animation. They disable the bfcache. Use `pagehide`.
+- Reduced motion reaches the same settled state and still fires every completion callback.
+- Define interruption and rapid-click behavior; completion must release navigation waits exactly once.
+- Verify in a real browser when practical, including reload, back, forward, and a click from a background tab.

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

@@ -0,0 +1,7 @@
+interface:
+  display_name: "GSAP Vanilla"
+  short_description: "GSAP page and component lifecycles on plain HTML sites"
+  default_prompt: "Use $gsap-vanilla to add GSAP page transitions and component animation to this plain HTML, CSS, and JavaScript site."
+
+policy:
+  allow_implicit_invocation: true

package/skills/ui/gsap-vanilla/references/cross-document-navigation.md

@@ -0,0 +1,54 @@
+# Cross-document navigation
+
+Read this when a full-document site uses View Transitions, or when GSAP must hand off to the browser at a page boundary.
+
+## Opting in
+
+Both documents need `@view-transition { navigation: auto }` in their CSS. Then every same-origin navigation the user starts from page content, plus back and forward, snapshots the old page, loads the new one, and crossfades the root. Address-bar navigations, cross-origin pages, and pages without the rule get an instant swap.
+
+Feature-detect with `CSS.supports("view-transition-name: a")` for the CSS side and `"onpagereveal" in window` for the events. Browsers without support skip the transition and lose nothing else. Every GSAP path must work with the transition absent.
+
+## Events
+
+- `pageswap` fires on the old document just before it is replaced. `event.viewTransition` is the outbound transition or null. `event.activation` carries the navigation type and the from and to history entries. This is where the old page assigns `view-transition-name` to the element the user clicked, chosen from the destination URL, and where `skipTransition()` cancels a transition that should not run.
+- `pagereveal` fires on the new document at its first render opportunity, before first paint. `event.viewTransition` is the inbound transition or null. Read `navigation.activation.from` for where the user came from. Assign names to the matching elements here, then await `viewTransition.ready` and clear them.
+- `pagereveal` also fires on a bfcache restore and on prerender activation. Check `navigation.activation` before assuming a fresh load.
+
+Clear every `view-transition-name` you set once snapshots are taken. A name left on an element travels into the bfcache, and on return two elements can share it, which skips the transition.
+
+## Types and direction
+
+`@view-transition { types: slide-forward }` sets types statically. Set them in `pageswap` and `pagereveal` through `event.viewTransition.types` when the direction depends on the route pair, and key CSS on `html:active-view-transition-type(slide-forward)`. The GSAP controller can read the same decision to build a matching intro.
+
+## Stabilizing the new page
+
+The inbound transition starts at first render opportunity, which can be before the page has its fonts, its critical script, or its full above-the-fold markup. Then the new snapshot is wrong and the transition lands on a page that is still changing.
+
+- Stylesheets in `head` already block render.
+- Put `blocking="render"` on the module script that sets initial state, so the snapshot shows the initial state, not the settled one.
+- Add `<link rel="expect" href="#main" blocking="render">` so the browser parses the main element before revealing.
+- Keep those blocks small. Everything under them delays first paint on every load.
+
+## Combining with GSAP
+
+GSAP runs on the live page before the browser leaves it and on the new page after it arrives. The view transition runs between them, on snapshots. Keep their jobs separate.
+
+- One engine per element per transition. A named morph and a GSAP tween on the same node fight, and the GSAP end state becomes the old snapshot.
+- If a GSAP outro fades or moves content, that is what the browser snapshots. Either skip the transition for that navigation with `skipTransition()` in `pageswap`, or leave the shared element lit at end state so the morph has something to start from.
+- On the new page, start the GSAP intro after `viewTransition.finished` for elements the transition touched. Elements outside the transition can start at `pagereveal`. Both paths must also run when `viewTransition` is null.
+- Name only elements that morph. Name chrome to hold it still; the root crossfade covers the rest.
+- Reduced motion covers both: zero view transition durations in CSS under `prefers-reduced-motion` and take the GSAP reduced path.
+- Add `::view-transition { pointer-events: none }` so a running transition does not swallow clicks.
+
+## Back and forward
+
+A history navigation gets a view transition too, reversed if the CSS keys on type. GSAP never gets an outro on the way back. On the new page, a `traverse` activation selects the intro-only path.
+
+## Cases to design for
+
+- A link clicked while the outro is running.
+- A slow destination. The old page's end state sits on screen until the new document arrives; keep it presentable.
+- Back to a page in the bfcache: `pageshow` reports `persisted`, `pagereveal` reports a `traverse` activation, and timelines are still alive.
+- Back to a page not in the bfcache: full reload, `back_forward` navigation type, intro-only.
+- A prerendered destination, where `pagereveal` fires on activation.
+- Browsers without view transition support, which must still get the GSAP outro and intro.

package/skills/ui/gsap-vanilla/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.