@nerdev/skillset 0.2.1

package/skills/ui/frontend-craftsmanship/SKILL.md

@@ -0,0 +1,462 @@
+---
+name: frontend-craftsmanship
+description: Use when building frontend, designing a screen, improving UI quality, establishing a design system, reverse-engineering premium interfaces, or when the user wants Shipd/Linear/Vercel-level output instead of generic AI slop. Load when the task involves product thinking, visual systems, interaction design, motion, typography, or frontend architecture. This is a core skill: it defines how the user wants frontend built, independent of any single project.
+---
+
+# Frontend Craftsmanship
+
+Purpose: enforce a specific standard for frontend quality across any project. Product-first thinking, design-system discipline, interaction states, motion rules, typography standards, reverse-engineering practice, and AI workflow for shipping polished interfaces.
+
+> This is one of the user's core skills. It defines how the user wants frontend built, independent of any single project. See also `house-style` for philosophy/restraint rules, `ui/ui-core` for the build process, `ui/motion` for motion implementation, `ui/typography-picker` for type direction, and `ui/impeccable` for audit/verify commands.
+
+## Core principles
+
+### Product-first, not component-first
+
+Developer-first:
+
+```
+Idea
+ ↓
+React
+ ↓
+Components
+ ↓
+API
+ ↓
+Done
+```
+
+Product-first:
+
+```
+Problem
+ ↓
+Product model
+ ↓
+User journey
+ ↓
+Information architecture
+ ↓
+Visual language
+ ↓
+Design system
+ ↓
+Interaction model
+ ↓
+Motion
+ ↓
+Frontend implementation
+ ↓
+States / edge cases
+ ↓
+Polish
+ ↓
+Done
+```
+
+### The homepage is a product demo
+
+Shipd's homepage doesn't list features. It makes you experience the product: leaderboard, code editor, terminal, reviews, bounty, challenges, rankings, quests, community. The landing page itself is a miniature product demo. Linear makes a similar point: dense interfaces remain calm when visual weight is carefully controlled. Vercel's Geist system is a technical reference for systematizing typography, colors, grid, and components.
+
+### One clear action per screen
+
+Every screen should have one obvious primary action. Color in small doses. Whitespace does the separating, not borders and shadows. Real type hierarchy: a headline, a sentence, a hint. Not five sizes of bold.
+
+### Feedback matches the action
+
+Manipulation (press, drag) gets a visual state: pressed, hovered, active. Completed work (saved, sent) gets a quiet status: a checkmark, a toast. Destructive work gets confirmation. Nothing else moves.
+
+## Design standards
+
+### Typography
+
+- One typeface family for UI, optionally one display face for headlines.
+- Tight type scale, real hierarchy.
+- `line-height` tuned per size: display tighter, body looser.
+- `letter-spacing` explicit for all-caps labels and display type.
+- Tabular figures for data columns.
+- Variable fonts preferred over static weights.
+
+### Spacing and layout
+
+- Think in tokens, not individual CSS values.
+- One spacing scale, used everywhere.
+- Grid over flex math.
+- Cards only when elevation earns them. Never cards inside cards.
+- Asymmetric layouts over perfect grids when the content allows.
+
+### Color
+
+- One accent color, used only for things that matter. Restraint is the accent.
+- One gray family, not five.
+- No purple gradients, glowing buttons, or gradient text.
+- Dark mode is designed, not inverted.
+
+### Motion
+
+- Fast, physical, quiet, purposeful.
+- State lands first. Nobody waits on a spring.
+- Animate `transform` and `opacity` only.
+- Nothing loops forever.
+- `prefers-reduced-motion: reduce` = instant state changes.
+- One motion per event. Pick the element that carries the change.
+- 200ms in, 150ms out. Spring curves (`cubic-bezier(0.16, 1, 0.3, 1)`), not keywords.
+- Exits exist. Whatever appears animated leaves animated.
+
+### Components
+
+Every component must define its states:
+
+```
+default
+hover
+active
+focus
+disabled
+loading
+error
+empty
+success
+mobile
+dark
+```
+
+A `Card` is not a product pattern. A `ChallengeCard`, `SubmissionPanel`, `LeaderboardRow`, `CodeReviewPanel`, `QuestHeader` is closer to a product language.
+
+### Frontend architecture
+
+Evolve from:
+
+```
+components/
+    Button
+    Card
+    Navbar
+```
+
+towards:
+
+```
+design-system/
+    primitives/
+    typography/
+    layout/
+    controls/
+    feedback/
+    navigation/
+
+patterns/
+    command-menu/
+    data-table/
+    activity-feed/
+    editor/
+    dashboard/
+    onboarding/
+
+features/
+    challenges/
+    leaderboard/
+    submissions/
+```
+
+## Interaction design
+
+Every interaction has a designed state:
+
+```
+idle
+ ↓
+hover
+ ↓
+press
+ ↓
+loading
+ ↓
+partial progress
+ ↓
+success
+ ↓
+next available action
+ ↓
+error / retry
+```
+
+Be obsessive about: hover, focus, active, disabled, loading, optimistic updates, empty states, skeletons, errors, success, transitions, keyboard interaction.
+
+## Reverse engineering method
+
+Don't just build products. **Copy excellent products.** Not by stealing their code. By rebuilding the experience.
+
+Pick: Shipd, Linear, Vercel, Raycast, Stripe, Arc, Resend, Cursor, Supabase, Notion, Figma.
+
+For each screen:
+
+```
+Why is this element here?
+Why this width?
+Why this spacing?
+Why this font?
+Why this border?
+Why does this section start here?
+Why does this interaction happen this way?
+What happens when there is no data?
+What happens when the user hovers?
+What happens when the user clicks?
+What happens on mobile?
+```
+
+Then rebuild it.
+
+## AI workflow for serious projects
+
+Don't let AI invent the product. Give it a **design specification first**:
+
+```
+PRODUCT:
+Developer competition platform.
+
+USER:
+Software engineers solving difficult programming problems.
+
+PRIMARY ACTION:
+Start a challenge.
+
+DESIGN DIRECTION:
+Dense developer-tool interface.
+Editorial typography.
+Dark neutral canvas.
+Very restrained color.
+Strong monospace usage.
+Thin borders.
+Minimal rounded corners.
+High information density.
+
+UX PRINCIPLES:
+Every screen should have one obvious primary action.
+Avoid decorative cards.
+Prefer information-rich panels.
+Use progressive disclosure.
+Keyboard-first where appropriate.
+Every async action needs explicit feedback.
+
+MOTION:
+150–250ms transitions.
+No gratuitous animation.
+Use motion to communicate hierarchy and state changes.
+
+STATES:
+Loading
+Empty
+Error
+Success
+Disabled
+Hover
+Focus
+Mobile
+
+TECH:
+Next.js
+TypeScript
+Tailwind
+...
+```
+
+Then: implement, then analyze, then implement P0/P1, then visual QA.
+
+```
+Analyze this interface as a senior product designer.
+
+Identify:
+1. visual hierarchy problems
+2. spacing inconsistencies
+3. typography problems
+4. interaction problems
+5. information architecture problems
+6. missing states
+7. accessibility problems
+8. responsive problems
+
+Do not rewrite the code yet.
+
+Give me a prioritized list of changes.
+```
+
+```
+Now implement only P0 and P1 issues.
+
+Do not change:
+- product behavior
+- information architecture
+- API contracts
+- existing design language
+
+Preserve the current component structure where reasonable.
+```
+
+```
+Now perform a visual QA pass.
+
+Look for:
+- inconsistent spacing
+- unnecessary borders
+- excessive cards
+- typography hierarchy
+- alignment
+- visual noise
+- interaction feedback
+- mobile behavior
+
+Make only changes that improve the product.
+```
+
+The AI workflow order:
+
+```
+                 IDEA
+                  │
+                  ▼
+            Product brief
+                  │
+                  ▼
+             User journey
+                  │
+                  ▼
+          Information architecture
+                  │
+                  ▼
+           Design specification
+                  │
+                  ▼
+             AI planning
+                  │
+                  ▼
+            Architecture
+                  │
+                  ▼
+          Design-system tokens
+                  │
+                  ▼
+             Components
+                  │
+                  ▼
+             Screens
+                  │
+                  ▼
+          Interactions/states
+                  │
+                  ▼
+             Polish
+                  │
+                  ▼
+             Evaluation
+                  │
+                  ▼
+               SHIP
+```
+
+Coding is not step 1.
+
+## Taste database
+
+Create a folder:
+
+```
+/design-research
+```
+
+Inside:
+
+```
+shipd.md
+linear.md
+vercel.md
+stripe.md
+cursor.md
+raycast.md
+supabase.md
+```
+
+Each file contains:
+
+```
+Typography:
+...
+
+Spacing:
+...
+
+Colors:
+...
+
+Borders:
+...
+
+Radius:
+...
+
+Motion:
+...
+
+Navigation:
+...
+
+Information density:
+...
+
+Interesting interaction:
+...
+
+What they avoid:
+...
+
+What I want to steal conceptually:
+...
+```
+
+Study what products **refuse to do**. That's one of the strongest lessons from good product design.
+
+## Anti-patterns
+
+| Anti-pattern | Correct approach |
+|---|---|
+| Generic AI SaaS dashboard: Navbar, Sidebar, Card, Card, Card, Table | Product-specific interface with one clear action per screen |
+| Purple gradients, glowing buttons, oversized rounded cards | Flat buttons, one accent, restraint |
+| Component-first thinking before product model | Product model → UX → IA → visual language → design system → implementation |
+| One-size-fits-all motion | Fast, physical, quiet, purposeful. 200ms in, 150ms out |
+| Missing states: no loading, empty, error, disabled | Every component defines all states |
+| Cards inside cards | Cards only when elevation earns them |
+| Decorative animation | Animation communicates what changed, nothing else |
+| AI inventing the product direction | Design specification first, then AI executes |
+| Five bold sizes masquerading as hierarchy | Real type hierarchy: display, headline, body, hint |
+| Individual CSS values instead of tokens | One spacing scale, one color family, one radius scale |
+
+## Checklist
+
+Before shipping any frontend work:
+
+- [ ] One clear primary action per screen
+- [ ] Typography hierarchy is real, not just bold sizes
+- [ ] Spacing uses tokens, not ad-hoc values
+- [ ] Color is restrained: one accent, one gray family
+- [ ] No purple gradients, glowing buttons, or gradient text
+- [ ] Every component defines: default, hover, active, focus, disabled, loading, error, empty, success, mobile, dark
+- [ ] Motion is transform/opacity only, 200ms in / 150ms out, spring curves
+- [ ] `prefers-reduced-motion: reduce` respected
+- [ ] Dark mode is designed, not inverted
+- [ ] No cards inside cards
+- [ ] Feedback matches action: manipulation gets visual state, completion gets quiet status
+- [ ] Empty, loading, and error states designed for every screen
+- [ ] Keyboard interaction works throughout
+- [ ] AI was given a design spec, not a vague prompt
+
+## References
+
+For implementation, refer to:
+
+- `ui/house-style`: The law (philosophy, restraint, no purple slop)
+- `ui/ui-core`: The process (pick direction, design system, build screen, verify)
+- `ui/motion`: The motion job (name, decide, build, review, audit)
+- `ui/typography-picker`: Font pairing, type scale, text motion
+- `ui/impeccable`: Commands/detectors for audit, polish, animate, verify
+- `ui/pick-ui-library`: Curated library picks for UI primitives

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

@@ -0,0 +1,56 @@
+---
+name: gsap-astro
+description: "Build or review Astro animation: GSAP page transitions, ClientRouter swap hooks, persisted islands, repeated setup, and cleanup. Use for missing or duplicated motion after navigation and choosing transition:animate versus GSAP. Without ClientRouter, use gsap-vanilla. Also covers hidden-content recovery and first-load performance. Not for standalone island frameworks or isolated GSAP API questions."
+license: MIT
+metadata:
+  short-description: GSAP page and component lifecycles in Astro
+---
+
+# GSAP Astro
+
+**mount → initial state → intro → settled → outro → end state → unmount**
+
+Without `<ClientRouter />`, use `gsap-vanilla` for full document loads. With it, mount and unmount correspond to body swaps; module scripts, global listeners, timelines, and persisted elements can survive. Animation owns the five phases between swaps.
+
+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. Read the installed Astro version. Read `node_modules/astro/dist/transitions/router.js`, `swap-functions.js`, and `node_modules/astro/components/ClientRouter.astro` before trusting memory; the package ships no changelog, so check the release notes for that version. Version gates: `<ClientRouter />` (5.0; `<ViewTransitions />` in 4.x, removed in 6.0), lifecycle events with `loader` and `newDocument` (3.6), form navigation (4.0), `transition:persist-props` and `data-astro-rerun` (4.5), `swapFunctions` (4.15).
+2. Find where `<ClientRouter />` is: the shared head, some pages, or nowhere, and its `fallback` prop. Nowhere means `gsap-vanilla`, including CSS `@view-transition`.
+3. Find which framework integrations render islands and which `client:*` directives are in use.
+4. Check `astro.config` for `prefetch` and `experimental.clientPrerender`.
+
+## Choose the engine
+
+Use `transition:name` / `transition:animate` for snapshot morphs, fades, or slides under ClientRouter. Use GSAP for live-DOM outros that hold the swap, interruptible sequences, split text, or scroll-linked motion. One engine per element; see [combining engines](references/client-router-navigation.md#combining-with-astros-animations).
+
+## 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 router's event sequence, outro before the swap, cleanup, initial state on the incoming page, direction, back and forward, scroll, focus, prefetch, fallback browsers: [ClientRouter navigation](references/client-router-navigation.md).
+- Which scripts run again, listeners that outlive pages, custom elements, islands and `client:*` directives, `transition:persist`: [Scripts and islands](references/scripts-and-islands.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 `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 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 before the swap that removes its owner.
+- A module script runs once per visit, not once per page. Setup runs from `astro:page-load` and is correct when it runs again on a new body or twice on the same one.
+- Listeners on `document` and `window` outlive the page. Register router listeners once, in one place, and have each handler find the current page before acting.
+- Reserve final geometry with normal CSS and a stable wrapper; overlap outgoing/incoming content without doubling layout space.
+- Set initial values before paint, then reveal. On first load that is the inline head script; after a swap it is `astro:before-swap` and `astro:after-swap`. 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.
+- The outro plays on live DOM inside `event.loader` in `astro:before-preparation`, and the router waits for it. Never animate in `astro:before-swap`: the user is looking at a snapshot.
+- Back and forward get an intro-only path. A traverse fires every event, so skip the outro on `navigationType === "traverse"` on purpose.
+- Keep `transition:persist` elements out of page-level cleanup and page-level intros. They cross the swap alive, timelines included.
+- Keep native link behavior, the router's history, scroll restoration, and route announcement. Do not add a click interceptor beside the router for motion; the only click listener is the capture-phase guard that holds the lock while a navigation is in flight.
+- Cleanup before the swap kills the page context; it does not revert it. A revert writes the intro's start values back onto a body that is still attached.
+- Reduced motion reaches the same settled state and still fires every completion callback. The router already disables its own animations under `prefers-reduced-motion`.
+- Use timelines for sequences. Decide up front what happens on rapid clicks and interrupted animations: the router lets a second click abort the first navigation while its outro is running, so first-click-wins needs the lock guard.
+- Verify in a real browser when practical, including a page visited twice, back, forward, and a click during an outro.

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

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

package/skills/ui/gsap-astro/references/client-router-navigation.md

@@ -0,0 +1,139 @@
+# ClientRouter navigation
+
+Read this when changing page-level motion or navigation on a site that uses `<ClientRouter />`.
+
+## Is the router running
+
+`<ClientRouter />` from `astro:transitions` goes in `<head>`, usually through a shared layout, and only pages that include it navigate in place. `transitionEnabledOnThisPage()` from `astro:transitions/client` reports the current page; `supportsViewTransitions` reports the browser. A link to a page without the router is fetched, found wanting, and followed as a full load, so an outro still plays but nothing survives into the next page.
+
+The `fallback` prop decides what browsers without View Transitions get. `animate` (default) simulates the transition by setting `data-astro-transition-fallback` to `old` and then `new` on `<html>` and waiting for the CSS animations those attributes start. `swap` replaces the page at once. `none` gives those browsers a full-page navigation and no router at all: no `astro:` event fires there, not even `astro:page-load` on first load. With `none`, keep `gsap-vanilla`'s load path as the baseline.
+
+Do not add a click interceptor beside the router to run motion. It listens on `document`, respects `defaultPrevented`, and leaves native: modified clicks, non-primary buttons, other origins, `target` other than `_self`, `download`, and anything marked `data-astro-reload`. `astro:before-preparation` is the hook. The one legitimate use of a click listener is the lock below: a capture-phase listener that calls `preventDefault()` on internal links only while a navigation is in flight, so the router never sees the second click.
+
+## The navigation sequence
+
+Verified against the router source. Read the installed version's `dist/transitions/router.js` if any step below carries the design.
+
+1. A link click, form submit, `navigate()`, or `popstate` starts a navigation. The previous navigation, if still running, is aborted.
+2. `astro:before-preparation` fires on `document` with the old page live and visible. Cancelable; `preventDefault()` hands the navigation to the browser as a full load.
+3. `event.loader()` runs: fetch, parse into `event.newDocument`, preload new stylesheets. Wrapping it delays everything after it.
+4. `astro:after-preparation` fires. The scroll position is saved to the history entry unless this is a traverse.
+5. `data-astro-transition` is set on `<html>` to the direction and `document.startViewTransition()` snapshots the old page. From here until the new page is revealed the user sees pixels, not DOM.
+6. `astro:before-swap` fires inside the transition callback with `event.newDocument`, `event.viewTransition`, and a replaceable `event.swap`. Not cancelable.
+7. The swap: scripts already run are deselected, `<html>` attributes are replaced with the new document's, `<head>` is diffed, focus is saved, `<body>` is replaced, `transition:persist` elements are moved into the new body, focus is restored if it was inside a persisted element.
+8. History is pushed or replaced, never on traverse. Scroll goes to the top or the hash, or is restored on traverse. This runs a microtask after the swap, so for a moment the incoming body is in the document under the outgoing URL. Anything that attributes DOM state to `location`, such as a phase log or analytics, sees the new page's initial state filed under the old path. Read the destination from `event.to`, not from `location`, until `astro:after-swap`.
+9. `astro:after-swap` fires. The new DOM is in place, history and scroll are updated, nothing has painted.
+10. The transition's update callback resolves. New scripts run in document order, then `astro:page-load` fires, then the route announcer reads the new title.
+11. The view transition animates and `finished` resolves; `data-astro-transition` is removed.
+
+On first load `astro:page-load` fires at window `load`, after images, and the router's module and the page's modules have already run by then.
+
+## Page lifecycle
+
+**mount → initial state → intro → settled → outro → end state → unmount**
+
+1. **Outro.** `astro:before-preparation`, inside the wrapped loader, on live DOM.
+2. **End state.** The outro's completion. Outgoing targets are finalized once; the loader promise resolves and the router proceeds.
+3. **Unmount and mount.** `astro:before-swap` is the last moment the old body exists; the swap replaces it.
+4. **Initial state.** `astro:before-swap` writes the pre-paint mark onto `event.newDocument`; `astro:after-swap` writes start values on the new body before paint.
+5. **Intro.** `astro:page-load`, after the new page's scripts ran.
+6. **Settled.** Clear temporary styles. CSS owns the page.
+
+Store the phase on the page root. A controller may track `waiting` or `preparing`, but they serve these five phases.
+
+## Event attributes
+
+`astro:before-preparation` and `astro:before-swap` share `from`, `to` (writable; its final value becomes the history entry), `direction`, `navigationType` (`push`, `replace`, `traverse`), `sourceElement` (the link, the form or submitter, or the element passed to `navigate()`), `info` from `navigate()`, `newDocument`, and `signal`, an `AbortSignal` that trips when a newer navigation starts (present in the router source, not in the docs; check the installed types). Before preparation adds `formData` and a writable `loader`, and its `direction` is writable and accepts any string. Before swap adds `viewTransition` (a same-shaped stand-in in fallback mode) and `swap`, and its `direction` is read-only. `astro:after-preparation`, `astro:after-swap`, and `astro:page-load` carry nothing.
+
+`navigate(href, { history, formData, info, state, sourceElement })` from `astro:transitions/client` starts a navigation from a script or an island. It does not sanitize `href`. Use `history.back()` and `history.forward()` for programmatic history moves; they reach the router through `popstate`. `data-astro-history="replace"` on a link does what `history: "replace"` does.
+
+## Outro before the swap
+
+Wrap the loader: capture `event.loader`, replace it with a function that starts the outro and the original loader together and resolves when both are done. The router waits, so the swap cannot show the end state early, and the outro's length is the only budget the fetch gets. Starting them together rather than in sequence keeps a slow route from adding its latency to the outro.
+
+- Skip the outro when `event.navigationType === "traverse"`, when `event.formData` is set, and when `event.to` is the current URL.
+- Same-page hash links fire no events; the router only scrolls.
+- One navigation at a time. The router itself offers no lock: a second click unconditionally aborts the first navigation and fires a new `astro:before-preparation` while the first outro may still be running, so "first destination wins" cannot be built from the events alone. Build it from the router's respect for `defaultPrevented`: a capture-phase click listener on `document`, active only from an accepted `astro:before-preparation` until the incoming intro starts, that applies the router's own exclusions and calls `preventDefault()` on any further internal link. If the design wants the last click to win instead, drop the guard, keep one outro by killing the running one and building the next from current values, and let the first wrapped loader resolve as soon as its `signal` aborts so nothing awaits a dead navigation.
+- A click during a running view transition skips that transition and starts over. The intro that was playing is killed by the new outro, not by the router.
+- Race the outro against a timeout. GSAP's ticker stops in a hidden tab, and a loader that never resolves leaves the user on a page that no longer answers clicks.
+- A killed timeline never resolves its promise. Await through a helper that also resolves on `onInterrupt`.
+- Under reduced motion, resolve at once.
+- A navigation the loader gives up on (fetch failed, next page has no router, cross-origin redirect) becomes a full load after the outro. The end state stays on screen until the new document paints; keep it presentable.
+- The loader rewrites `event.to` on a redirect, so a destination read at the start of preparation can differ from the page that arrives. Decide the intro from `event.to` in `astro:before-swap`.
+
+## Cleanup before the swap
+
+`astro:before-swap` is the last event with the old body in the DOM, and the user is watching a snapshot, so nothing done here is visible. Kill the page's GSAP context, kill its ScrollTriggers, revert splits, remove listeners and observers, and undo scroll locks and `<body>` classes. Kill, not revert: `revert()` restores the inline values recorded when the context was created, which for a settled page means writing the intro's start transform and opacity back onto nodes that are still attached, and that is what the fallback path or a late snapshot shows. The old body is about to be discarded, so its inline styles do not matter; the persisted subtrees and any split markup are the parts that do, and those get `revert()`. Skip `[data-astro-transition-persist]` subtrees; they leave with the new body. Killing after the swap leaves triggers listening to scroll on behalf of nodes that no longer exist.
+
+Do not animate here, and do not measure `event.newDocument`: it is an inert parsed document, so every box is zero.
+
+## Initial state on the incoming page
+
+Arm a per-navigation deadline before marking the incoming document. Dispose the outgoing entrance timer before its outro; never let it reveal the outgoing page. Use the [recovery integration](motion-system.md#initialization-and-recovery) for swap failure, persisted nodes, and late setup.
+
+The inline head script that marks `<html>` before first paint runs once per visit, and its attributes do not survive the swap because `<html>` attributes are replaced by the new document's. So:
+
+- In `astro:before-swap`, set the mark and the initial phase on `event.newDocument.documentElement`. The pre-paint CSS rule then hides intro targets in the new body from the first frame it exists.
+- In `astro:after-swap`, write every target's start values with `set` or `fromTo` on the live new body. Nothing has painted yet, on either the native or the fallback path.
+- In `astro:page-load`, build the page controller for the current body and start the intro. The new page's scripts have run by then.
+
+Reserve final sizes with CSS, not with inline styles a context revert would clear. The root animation you chose plays over this: with `none` on the root the new body appears at the swap holding its initial state; with `fade` it fades in holding it, and the intro starts after `viewTransition.finished` or is designed to look right under a crossfade.
+
+Setup must be correct when it runs twice on the same body: the layout module runs it on first execution because `astro:page-load` waits for window `load`, and the event then runs it again. Key the guard on the body node, not a boolean.
+
+## Direction
+
+`event.direction` is `"forward"` or `"back"`, or any string a before-preparation listener writes there to name a custom pair. Astro puts it on `<html>` as `data-astro-transition` for the length of the transition, which is what `transition:animate` keys its backwards animations on. Carry the value from `astro:before-swap` into the controller for the intro; in fallback modes the attribute can be gone by `astro:page-load`.
+
+## Back and forward
+
+History navigation goes through the same events with `navigationType === "traverse"`, and the old body is still live during preparation, so unlike a plain MPA an outro is possible. Do not use it. The URL has already changed, the user expects the page they left, and after a swipe gesture the browser has already animated: the router then drops its own animation and swaps at once. Give traverse an intro-only path with no travel. If the intro should also be skipped after a gesture, read `hasUAVisualTransition` from your own `popstate` listener; the router does not pass it on.
+
+A history entry the router did not create, or a return to a page loaded without the router, is a full reload; the first-load path handles it.
+
+The router keeps the document alive, so the bfcache is not involved while it handles navigation. A full load from `data-astro-reload`, a page without the router, or an external site still ends the document, and pressing back can restore it from the bfcache. Keep `gsap-vanilla`'s `pagehide` rule: finish any outro instantly and leave the page readable.
+
+## Scroll
+
+The router sets `history.scrollRestoration` to `manual` and owns it: push and replace scroll to the top or the hash; traverse restores the position saved on the last `scrollend`. Both happen before `astro:after-swap`, which is where the docs put a scroll override. Do not add a second reset.
+
+Create ScrollTriggers in `astro:page-load` and refresh after fonts and the new page's images, since window `load` does not fire again. On traverse the page is already scrolled when triggers are created; reveal targets above the restored position must not stay hidden. Refresh once more at settle if the intro changed heights above a trigger.
+
+## Focus and announcement
+
+After the swap, focus is restored only if it was inside a `transition:persist` element. Otherwise it is on `body`. On intro completion, move focus to the page container or main heading if it is still on `body`, with `tabindex="-1"` and a focus style that fits the design. Never take focus from a control inside a persisted region.
+
+The router appends an `aria-live="assertive"` announcer and reads the `<title>`, first `<h1>`, or pathname shortly after `astro:page-load`. Keep a `<title>` on every page and do not add a second live region.
+
+## Prefetch
+
+With the router present, prefetch is on for every internal link with the `hover` strategy unless `astro.config` says otherwise: `prefetch: false` turns it off, `prefetchAll: false` limits it to links with `data-astro-prefetch`, and `data-astro-prefetch="tap"`, `"viewport"`, or `"load"` changes one link. Data saver and slow connections fall back to `tap`.
+
+Hover prefetch means the fetch inside the wrapped loader usually hits cache and the outro is the whole wait. Where it cannot (tap, a link far from the viewport, Safari without cache headers), the fetch runs during the outro anyway because loader and outro start together. Importing `prefetch()` from `astro:prefetch` for programmatic warming needs the `prefetch` config even though the router turned prefetching on. `experimental.clientPrerender` turns prefetch into Speculation Rules (its `eagerness` option is 5.6+); `gsap-vanilla`'s prerender rules then apply to full loads only, since the router still fetches HTML for its own swaps.
+
+## Combining with Astro's animations
+
+Every element with a `transition:*` directive gets a `view-transition-name` and, by default, `transition:animate="fade"`. An element with a directive but no `transition:name` is named from its component and position, so the same component in the same place on both pages pairs up automatically. Everything else rides the browser's root crossfade. The browser animates snapshots between the swap and `finished`; GSAP animates live DOM before the snapshot and after the swap. Keep their jobs separate:
+
+- One engine per element per navigation. A named element under a GSAP tween during the transition fights its own snapshot, and the outro's end state becomes the old snapshot.
+- When GSAP owns the page transition, put `transition:name="root"` and `transition:animate="none"` on `<html>`. `none` compiles to no animation on old, new, and group, so the new body appears at the swap in its initial state and the outro's end state is the last thing seen before it. Then name only the elements the browser should morph, once per page. The `<html>` tag must be the first thing in the layout template after the frontmatter: a leading JSX-style comment or any other node makes the compiler emit a fragment with no `html`, `head`, or `body`, and the directive is dropped without a warning. An HTML comment is fine.
+- For a named element, start its GSAP intro after `event.viewTransition.finished` captured in `astro:before-swap`; until then the live element sits under its pseudo-element. Elements outside the transition start at `astro:page-load`.
+- `fade({ duration })` and `slide({ duration })` from `astro:transitions` adjust the presets. A custom animation is an object with `forwards` and `backwards`, each holding `old` and `new` keyframe animations, declared in component frontmatter with the keyframes in global CSS. Keep GSAP out of those.
+- `initial` hands the element to the browser's default and is not simulated in fallback mode.
+- Add `::view-transition { pointer-events: none }` so a running transition does not swallow clicks.
+- The router disables all of its animations, fallback included, under `prefers-reduced-motion`. GSAP takes its own reduced path.
+
+## Cases to design for
+
+- A click during the outro, and a click during the intro.
+- Back and forward, including a swipe gesture.
+- A link to a page without the router, or marked `data-astro-reload`.
+- A form submission.
+- A hash link on the same page and a hash link to another page.
+- A `transition:persist` element or island crossing the swap mid-animation.
+- A page visited a second time, whose module script does not run again.
+- A destination that redirects.
+- A browser without View Transitions, on the `fallback` value the site ships.
+- A click from a background tab on a prefetched link.
+
+Each case must end on one visible, interactive page with stable layout and no stale inline styles.