tribunal-kit 4.5.1 → 4.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (214) hide show
  1. package/.agent/.shared/ui-ux-pro-max/README.md +4 -4
  2. package/.agent/ARCHITECTURE.md +282 -277
  3. package/.agent/agents/accessibility-reviewer.md +187 -187
  4. package/.agent/agents/ai-code-reviewer.md +199 -199
  5. package/.agent/agents/api-architect.md +71 -66
  6. package/.agent/agents/backend-specialist.md +219 -215
  7. package/.agent/agents/cloud-engineer.md +98 -0
  8. package/.agent/agents/code-archaeologist.md +168 -161
  9. package/.agent/agents/database-architect.md +184 -184
  10. package/.agent/agents/db-latency-auditor.md +213 -216
  11. package/.agent/agents/debugger.md +198 -191
  12. package/.agent/agents/dependency-reviewer.md +106 -103
  13. package/.agent/agents/devops-engineer.md +218 -218
  14. package/.agent/agents/documentation-writer.md +209 -201
  15. package/.agent/agents/explorer-agent.md +167 -160
  16. package/.agent/agents/frontend-reviewer.md +162 -160
  17. package/.agent/agents/frontend-specialist.md +257 -248
  18. package/.agent/agents/game-developer.md +48 -48
  19. package/.agent/agents/logic-reviewer.md +118 -116
  20. package/.agent/agents/mobile-developer.md +197 -200
  21. package/.agent/agents/mobile-reviewer.md +159 -162
  22. package/.agent/agents/orchestrator.md +187 -181
  23. package/.agent/agents/penetration-tester.md +160 -157
  24. package/.agent/agents/performance-optimizer.md +183 -183
  25. package/.agent/agents/performance-reviewer.md +178 -178
  26. package/.agent/agents/precedence-reviewer.md +251 -250
  27. package/.agent/agents/product-manager.md +149 -142
  28. package/.agent/agents/product-owner.md +81 -80
  29. package/.agent/agents/project-planner.md +152 -142
  30. package/.agent/agents/qa-automation-engineer.md +216 -225
  31. package/.agent/agents/resilience-reviewer.md +88 -88
  32. package/.agent/agents/schema-reviewer.md +67 -67
  33. package/.agent/agents/security-auditor.md +180 -174
  34. package/.agent/agents/seo-specialist.md +188 -193
  35. package/.agent/agents/sql-reviewer.md +159 -161
  36. package/.agent/agents/supervisor-agent.md +173 -184
  37. package/.agent/agents/swarm-worker-contracts.md +170 -166
  38. package/.agent/agents/swarm-worker-registry.md +92 -92
  39. package/.agent/agents/system-architect.md +85 -0
  40. package/.agent/agents/test-coverage-reviewer.md +158 -160
  41. package/.agent/agents/test-engineer.md +118 -118
  42. package/.agent/agents/throughput-optimizer.md +291 -299
  43. package/.agent/agents/type-safety-reviewer.md +182 -175
  44. package/.agent/agents/ui-ux-auditor.md +300 -292
  45. package/.agent/agents/vitals-reviewer.md +223 -223
  46. package/.agent/mcp_config.json +37 -40
  47. package/.agent/patterns/generator.md +11 -9
  48. package/.agent/patterns/inversion.md +14 -12
  49. package/.agent/patterns/pipeline.md +11 -9
  50. package/.agent/patterns/reviewer.md +15 -13
  51. package/.agent/patterns/tool-wrapper.md +11 -9
  52. package/.agent/routing_index.json +714 -0
  53. package/.agent/rules/GEMINI.md +359 -352
  54. package/.agent/scripts/compile_router.py +112 -0
  55. package/.agent/scripts/migrate_skills_frontmatter.py +64 -0
  56. package/.agent/scripts/strengthen_skills.js +1 -1
  57. package/.agent/skills/advanced-rag-pipelines/SKILL.md +56 -0
  58. package/.agent/skills/agent-organizer/SKILL.md +156 -150
  59. package/.agent/skills/agentic-patterns/SKILL.md +313 -315
  60. package/.agent/skills/ai-prompt-injection-defense/SKILL.md +190 -184
  61. package/.agent/skills/api-patterns/SKILL.md +253 -247
  62. package/.agent/skills/api-security-auditor/SKILL.md +195 -193
  63. package/.agent/skills/app-builder/SKILL.md +573 -572
  64. package/.agent/skills/app-builder/templates/SKILL.md +108 -115
  65. package/.agent/skills/app-builder/templates/astro-static/TEMPLATE.md +76 -76
  66. package/.agent/skills/app-builder/templates/chrome-extension/TEMPLATE.md +92 -92
  67. package/.agent/skills/app-builder/templates/cli-tool/TEMPLATE.md +88 -88
  68. package/.agent/skills/app-builder/templates/electron-desktop/TEMPLATE.md +88 -88
  69. package/.agent/skills/app-builder/templates/express-api/TEMPLATE.md +83 -83
  70. package/.agent/skills/app-builder/templates/flutter-app/TEMPLATE.md +90 -90
  71. package/.agent/skills/app-builder/templates/monorepo-turborepo/TEMPLATE.md +90 -90
  72. package/.agent/skills/app-builder/templates/nextjs-fullstack/TEMPLATE.md +126 -122
  73. package/.agent/skills/app-builder/templates/nextjs-saas/TEMPLATE.md +127 -122
  74. package/.agent/skills/app-builder/templates/nextjs-static/TEMPLATE.md +172 -169
  75. package/.agent/skills/app-builder/templates/nuxt-app/TEMPLATE.md +139 -134
  76. package/.agent/skills/app-builder/templates/python-fastapi/TEMPLATE.md +83 -83
  77. package/.agent/skills/app-builder/templates/react-native-app/TEMPLATE.md +122 -119
  78. package/.agent/skills/appflow-wireframe/SKILL.md +146 -145
  79. package/.agent/skills/architecture/SKILL.md +226 -219
  80. package/.agent/skills/authentication-best-practices/SKILL.md +197 -189
  81. package/.agent/skills/backend-security-expert/SKILL.md +16 -2
  82. package/.agent/skills/bash-linux/SKILL.md +179 -179
  83. package/.agent/skills/behavioral-modes/SKILL.md +239 -223
  84. package/.agent/skills/brainstorming/SKILL.md +498 -486
  85. package/.agent/skills/browser-native-ai/SKILL.md +57 -4
  86. package/.agent/skills/building-native-ui/SKILL.md +202 -202
  87. package/.agent/skills/cicd-pro/SKILL.md +442 -0
  88. package/.agent/skills/clean-code/SKILL.md +400 -381
  89. package/.agent/skills/cloud-architect/SKILL.md +439 -0
  90. package/.agent/skills/code-review-checklist/SKILL.md +203 -194
  91. package/.agent/skills/config-validator/SKILL.md +165 -165
  92. package/.agent/skills/containerization-pro/SKILL.md +452 -0
  93. package/.agent/skills/csharp-developer/SKILL.md +518 -518
  94. package/.agent/skills/data-validation-schemas/SKILL.md +333 -328
  95. package/.agent/skills/database-design/SKILL.md +247 -240
  96. package/.agent/skills/deployment-procedures/SKILL.md +172 -169
  97. package/.agent/skills/devops-engineer/SKILL.md +345 -345
  98. package/.agent/skills/devops-incident-responder/SKILL.md +143 -137
  99. package/.agent/skills/documentation-templates/SKILL.md +291 -279
  100. package/.agent/skills/edge-computing/SKILL.md +183 -181
  101. package/.agent/skills/emil-design-eng/SKILL.md +147 -0
  102. package/.agent/skills/error-resilience/SKILL.md +411 -428
  103. package/.agent/skills/extract-design-system/SKILL.md +160 -158
  104. package/.agent/skills/framer-motion-expert/SKILL.md +253 -244
  105. package/.agent/skills/frontend-design/SKILL.md +208 -201
  106. package/.agent/skills/frontend-security-expert/SKILL.md +16 -3
  107. package/.agent/skills/game-design-expert/SKILL.md +132 -129
  108. package/.agent/skills/game-engineering-expert/SKILL.md +148 -146
  109. package/.agent/skills/generative-ui-expert/SKILL.md +57 -1
  110. package/.agent/skills/geo-fundamentals/SKILL.md +148 -147
  111. package/.agent/skills/git-pro/SKILL.md +435 -0
  112. package/.agent/skills/github-operations/SKILL.md +335 -329
  113. package/.agent/skills/gsap-core/SKILL.md +319 -308
  114. package/.agent/skills/gsap-frameworks/SKILL.md +213 -207
  115. package/.agent/skills/gsap-performance/SKILL.md +139 -133
  116. package/.agent/skills/gsap-plugins/SKILL.md +486 -480
  117. package/.agent/skills/gsap-react/SKILL.md +202 -189
  118. package/.agent/skills/gsap-scrolltrigger/SKILL.md +357 -350
  119. package/.agent/skills/gsap-timeline/SKILL.md +165 -161
  120. package/.agent/skills/gsap-utils/SKILL.md +344 -338
  121. package/.agent/skills/harness-protocol/SKILL.md +48 -0
  122. package/.agent/skills/i18n-localization/SKILL.md +174 -163
  123. package/.agent/skills/intelligent-routing/SKILL.md +202 -246
  124. package/.agent/skills/knowledge-graph/SKILL.md +60 -52
  125. package/.agent/skills/lint-and-validate/SKILL.md +261 -261
  126. package/.agent/skills/llm-engineering/SKILL.md +400 -394
  127. package/.agent/skills/local-first/SKILL.md +178 -178
  128. package/.agent/skills/mcp-builder/SKILL.md +143 -142
  129. package/.agent/skills/mobile-design/SKILL.md +272 -263
  130. package/.agent/skills/monorepo-management/SKILL.md +335 -334
  131. package/.agent/skills/motion-engineering/SKILL.md +266 -234
  132. package/.agent/skills/nextjs-react-expert/SKILL.md +236 -234
  133. package/.agent/skills/nodejs-best-practices/SKILL.md +547 -548
  134. package/.agent/skills/observability/SKILL.md +343 -343
  135. package/.agent/skills/parallel-agents/SKILL.md +143 -146
  136. package/.agent/skills/performance-profiling/SKILL.md +259 -267
  137. package/.agent/skills/plan-writing/SKILL.md +150 -142
  138. package/.agent/skills/platform-engineer/SKILL.md +148 -147
  139. package/.agent/skills/playwright-best-practices/SKILL.md +188 -187
  140. package/.agent/skills/powershell-windows/SKILL.md +162 -162
  141. package/.agent/skills/project-idioms/SKILL.md +137 -137
  142. package/.agent/skills/python-patterns/SKILL.md +260 -259
  143. package/.agent/skills/python-pro/SKILL.md +324 -323
  144. package/.agent/skills/react-specialist/SKILL.md +305 -277
  145. package/.agent/skills/readme-builder/SKILL.md +310 -300
  146. package/.agent/skills/realtime-patterns/SKILL.md +323 -319
  147. package/.agent/skills/red-team-tactics/SKILL.md +231 -218
  148. package/.agent/skills/review-animations/SKILL.md +72 -0
  149. package/.agent/skills/review-animations/STANDARDS.md +73 -0
  150. package/.agent/skills/rust-pro/SKILL.md +671 -673
  151. package/.agent/skills/seo-fundamentals/SKILL.md +179 -179
  152. package/.agent/skills/server-management/SKILL.md +218 -214
  153. package/.agent/skills/shadcn-ui-expert/SKILL.md +231 -231
  154. package/.agent/skills/skill-creator/SKILL.md +87 -86
  155. package/.agent/skills/sql-pro/SKILL.md +629 -629
  156. package/.agent/skills/supabase-postgres-best-practices/SKILL.md +97 -97
  157. package/.agent/skills/swiftui-expert/SKILL.md +204 -201
  158. package/.agent/skills/system-design-pro/SKILL.md +345 -0
  159. package/.agent/skills/systematic-debugging/SKILL.md +153 -142
  160. package/.agent/skills/tailwind-patterns/SKILL.md +610 -566
  161. package/.agent/skills/tdd-workflow/SKILL.md +169 -161
  162. package/.agent/skills/test-result-analyzer/SKILL.md +313 -309
  163. package/.agent/skills/testing-patterns/SKILL.md +566 -579
  164. package/.agent/skills/trend-researcher/SKILL.md +243 -237
  165. package/.agent/skills/typescript-advanced/SKILL.md +336 -335
  166. package/.agent/skills/ui-ux-pro-max/SKILL.md +590 -562
  167. package/.agent/skills/ui-ux-researcher/SKILL.md +244 -244
  168. package/.agent/skills/vue-expert/SKILL.md +294 -275
  169. package/.agent/skills/vulnerability-scanner/SKILL.md +416 -404
  170. package/.agent/skills/web-accessibility-auditor/SKILL.md +219 -218
  171. package/.agent/skills/web-design-guidelines/SKILL.md +192 -186
  172. package/.agent/skills/webapp-testing/SKILL.md +167 -169
  173. package/.agent/skills/webgpu-performance/SKILL.md +56 -2
  174. package/.agent/skills/whimsy-injector/SKILL.md +346 -325
  175. package/.agent/skills/workflow-optimizer/SKILL.md +231 -229
  176. package/.agent/workflows/acf.md +141 -0
  177. package/.agent/workflows/api-tester.md +176 -151
  178. package/.agent/workflows/audit.md +150 -127
  179. package/.agent/workflows/brainstorm.md +134 -110
  180. package/.agent/workflows/changelog.md +140 -112
  181. package/.agent/workflows/create.md +168 -124
  182. package/.agent/workflows/debug.md +190 -165
  183. package/.agent/workflows/deploy.md +201 -180
  184. package/.agent/workflows/enhance.md +154 -128
  185. package/.agent/workflows/fix.md +136 -114
  186. package/.agent/workflows/generate.md +198 -183
  187. package/.agent/workflows/marathon.md +37 -11
  188. package/.agent/workflows/migrate.md +184 -160
  189. package/.agent/workflows/orchestrate.md +192 -168
  190. package/.agent/workflows/performance-benchmarker.md +135 -114
  191. package/.agent/workflows/plan.md +196 -173
  192. package/.agent/workflows/preview.md +103 -80
  193. package/.agent/workflows/refactor.md +192 -161
  194. package/.agent/workflows/review-ai.md +125 -101
  195. package/.agent/workflows/review.md +141 -116
  196. package/.agent/workflows/session.md +122 -94
  197. package/.agent/workflows/status.md +101 -79
  198. package/.agent/workflows/strengthen-skills.md +164 -138
  199. package/.agent/workflows/super-prompt.md +24 -0
  200. package/.agent/workflows/swarm.md +193 -179
  201. package/.agent/workflows/test.md +211 -189
  202. package/.agent/workflows/tribunal-backend.md +136 -105
  203. package/.agent/workflows/tribunal-database.md +129 -95
  204. package/.agent/workflows/tribunal-frontend.md +140 -96
  205. package/.agent/workflows/tribunal-full.md +131 -100
  206. package/.agent/workflows/tribunal-mobile.md +129 -95
  207. package/.agent/workflows/tribunal-performance.md +136 -110
  208. package/.agent/workflows/tribunal-speed.md +209 -183
  209. package/.agent/workflows/ui-ux-pro-max.md +155 -122
  210. package/README.md +107 -55
  211. package/mcp_config.json +1 -3
  212. package/package.json +94 -94
  213. package/.agent/GEMINI.md +0 -121
  214. package/.agent/skills/doc.md +0 -177
package/.agent/skills/gsap-plugins/SKILL.md CHANGED
@@ -1,484 +1,488 @@
1
- ---
2
- name: gsap-plugins
3
- description: Official GSAP skill for GSAP plugins — registration, ScrollToPlugin, ScrollSmoother, Flip, Draggable, Inertia, Observer, SplitText, ScrambleText, SVG and physics plugins, CustomEase, EasePack, CustomWiggle, CustomBounce, GSDevTools. Use when the user asks about a GSAP plugin, scroll-to, flip animations, draggable, SVG drawing, or plugin registration.
4
- license: MIT
5
- ---
6
-
7
- # GSAP Plugins
8
-
9
- ## When to Use This Skill
10
-
11
- Apply when using or reviewing code that uses GSAP plugins: registering plugins, scroll-to, flip/FLIP animations, draggable elements, SVG (DrawSVG, MorphSVG, MotionPath), text (SplitText, ScrambleText), physics, easing plugins (CustomEase, EasePack, CustomWiggle, CustomBounce), or GSDevTools. ScrollTrigger has its own skill (gsap-scrolltrigger).
12
-
13
- **Related skills:** For core tweens use **gsap-core**; for ScrollTrigger use **gsap-scrolltrigger**; for React use **gsap-react**.
14
-
15
- ## Registering Plugins
16
-
17
- Register each plugin once so GSAP (and bundlers) know to include it. Use **gsap.registerPlugin()** with every plugin used in the project:
18
-
19
- ```javascript
20
- import gsap from "gsap";
21
- import { ScrollToPlugin } from "gsap/ScrollToPlugin";
22
- import { Flip } from "gsap/Flip";
23
- import { Draggable } from "gsap/Draggable";
24
-
25
- gsap.registerPlugin(ScrollToPlugin, Flip, Draggable);
26
- ```
27
-
28
- - ✅ Register before using the plugin in any tween or API call.
29
- - ✅ In React, register at top level or once in the app (e.g. before first useGSAP); do not register inside a component that re-renders. useGSAP is a plugin that needs to be registered before use.
30
-
31
- ## Scroll
32
-
33
- ### ScrollToPlugin
34
-
35
- Animates scroll position (window or a scrollable element). Use for “scroll to element” or “scroll to position” without ScrollTrigger.
36
-
37
- ```javascript
38
- gsap.registerPlugin(ScrollToPlugin);
39
-
40
- gsap.to(window, { duration: 1, scrollTo: { y: 500 } });
41
- gsap.to(window, { duration: 1, scrollTo: { y: "#section", offsetY: 50 } });
42
- gsap.to(scrollContainer, { duration: 1, scrollTo: { x: "max" } });
43
- ```
44
-
45
- **ScrollToPlugin — key config (scrollTo object):**
46
-
47
- | Option | Description |
48
- |--------|-------------|
49
- | `x`, `y` | Target scroll position (number), or `"max"` for maximum |
50
- | `element` | Selector or element to scroll to (for scroll-into-view) |
51
- | `offsetX`, `offsetY` | Offset in pixels from the target position |
52
-
53
- ### ScrollSmoother
54
-
55
- Smooth scroll wrapper (smooths native scroll). Requires ScrollTrigger and a specific DOM structure (content wrapper + smooth wrapper). Use when smooth, momentum-style scroll is needed. See GSAP docs for setup; register after ScrollTrigger. DOM structure would look like:
56
-
57
- ```html
58
- <body>
59
- <div id="smooth-wrapper">
60
- <div id="smooth-content">
61
- <!--- ALL YOUR CONTENT HERE --->
62
- </div>
63
- </div>
64
- <!-- position: fixed elements can go outside --->
65
- </body>
66
- ```
67
-
68
- ## DOM / UI
69
-
70
- ### Flip
71
-
72
- Capture state with `Flip.getState()`, then apply changes (e.g. layout or class changes), then use `Flip.from()` to animate from the previous state to the new state (FLIP: First, Last, Invert, Play). Use when animating between two layout states (lists, grids, expanded/collapsed).
73
-
74
- ```javascript
75
- gsap.registerPlugin(Flip);
76
-
77
- const state = Flip.getState(".item");
78
- // change DOM (reorder, add/remove, change classes)
79
- Flip.from(state, { duration: 0.5, ease: "power2.inOut" });
80
- ```
81
-
82
- **Flip — key config (Flip.from vars):**
83
-
84
- | Option | Description |
85
- |--------|-------------|
86
- | `absolute` | Use `position: absolute` during the flip (default: `false`) |
87
- | `nested` | When true, only the first level of children is measured (better for nested transforms) |
88
- | `scale` | When true, scale elements to fit (avoids stretch); default `true` |
89
- | `simple` | When true, only position/scale are animated (faster, less accurate) |
90
- | `duration`, `ease` | Standard tween options |
91
-
92
- #### More information
93
-
94
- https://gsap.com/docs/v3/Plugins/Flip
95
-
96
- ### Draggable
97
-
98
- Makes elements draggable, spinnable, or throwable with mouse/touch. Use for sliders, cards, reorderable lists, or any drag interaction.
99
-
100
- ```javascript
101
- gsap.registerPlugin(Draggable, InertiaPlugin);
102
-
103
- Draggable.create(".box", { type: "x,y", bounds: "#container", inertia: true });
104
- Draggable.create(".knob", { type: "rotation" });
105
- ```
106
-
107
- **Draggable — key config options:**
108
-
109
- | Option | Description |
110
- |--------|-------------|
111
- | `type` | `"x"`, `"y"`, `"x,y"`, `"rotation"`, `"scroll"` |
112
- | `bounds` | Element, selector, or `{ minX, maxX, minY, maxY }` to constrain drag |
113
- | `inertia` | `true` to enable throw/momentum (requires InertiaPlugin) |
114
- | `edgeResistance` | 0–1; resistance when dragging past bounds |
115
- | `cursor` | CSS cursor during drag |
116
- | `onDragStart`, `onDrag`, `onDragEnd` | Callbacks; receive event and target |
117
- | `onThrowUpdate`, `onThrowComplete` | Callbacks when inertia is active |
118
-
119
- ### Inertia (InertiaPlugin)
120
-
121
- Works with Draggable for momentum after release, or track the inertia/velocity of any property of any object so that it can then seamlessly glide to a stop using a simple tween. Register with Draggable when using `inertia: true`:
122
-
123
- ```javascript
124
- gsap.registerPlugin(Draggable, InertiaPlugin);
125
- Draggable.create(".box", { type: "x,y", inertia: true });
126
- ```
127
-
128
- Or track velocity of a property:
129
- ```javascript
130
- InertiaPlugin.track(".box", "x");
131
- ```
132
-
133
- Then use `"auto"` to continue the current velocity and glide to a stop:
134
-
135
- ```javascript
136
- gsap.to(obj, { inertia: { x: "auto" } });
137
- ```
138
-
139
- ### Observer
140
-
141
- Normalizes pointer and scroll input across devices. Use for swipe, scroll direction, or custom gesture logic without tying directly to scroll position like ScrollTrigger.
142
-
143
- ```javascript
144
- gsap.registerPlugin(Observer);
145
-
146
- Observer.create({
147
- target: "#area",
148
- onUp: () => {},
149
- onDown: () => {},
150
- onLeft: () => {},
151
- onRight: () => {},
152
- tolerance: 10
153
- });
154
- ```
155
-
156
- **Observer — key config options:**
157
-
158
- | Option | Description |
159
- |--------|-------------|
160
- | `target` | Element or selector to observe |
161
- | `onUp`, `onDown`, `onLeft`, `onRight` | Callbacks when swipe/scroll passes tolerance in that direction |
162
- | `tolerance` | Pixels before direction is detected; default 10 |
163
- | `type` | `"touch"`, `"pointer"`, or `"wheel"` (default: `"touch,pointer"`) |
164
-
165
- ## Text
166
-
167
- ### SplitText
168
-
169
- Splits an element’s text into characters, words, and/or lines (each in its own element) for staggered or per-unit animation. Use when animating text character-by-character, word-by-word, or line-by-line. Returns an instance with **chars**, **words**, **lines** (and **masks** when `mask` is set). Restore original markup with **revert()** or let **gsap.context()** revert. Integrates with **gsap.context()**, **matchMedia()**, and **useGSAP()**. API: **SplitText.create(target, vars)** (target = selector, element, or array).
170
-
171
- ```javascript
172
- gsap.registerPlugin(SplitText);
173
-
174
- const split = SplitText.create(".heading", { type: "words, chars" });
175
- gsap.from(split.chars, { opacity: 0, y: 20, stagger: 0.03, duration: 0.4 });
176
- // later: split.revert() or let gsap.context() cleanup revert
177
- ```
178
-
179
- With **onSplit()** (v3.13.0+), animations run on each split and on re-split when **autoSplit** is used; returning a tween/timeline from **onSplit()** lets SplitText clean up and sync progress on re-split:
180
-
181
- ```javascript
182
- SplitText.create(".split", {
183
- type: "lines",
184
- autoSplit: true,
185
- onSplit(self) {
186
- return gsap.from(self.lines, { y: 100, opacity: 0, stagger: 0.05, duration: 0.5 });
187
- }
188
- });
189
- ```
190
-
191
- **SplitText — key config (SplitText.create vars):**
192
-
193
- | Option | Description |
194
- |--------|-------------|
195
- | **type** | Comma-separated: `"chars"`, `"words"`, `"lines"`. Default `"chars,words,lines"`. Only split what is needed (e.g. `"words, chars"` if not using lines) for performance. Avoid chars-only without words/lines or use **smartWrap: true** to prevent odd line breaks. |
196
- | **charsClass**, **wordsClass**, **linesClass** | CSS class on each split element. Append `"++"` to add an incremented class (e.g. `linesClass: "line++"` → `line1`, `line2`, …). |
197
- | **aria** | `"auto"` (default), `"hidden"`, or `"none"`. Accessibility: `"auto"` adds `aria-label` on the split element and `aria-hidden` on line/word/char elements so screen readers read the label; `"hidden"` hides all from readers; `"none"` leaves aria unchanged. Use `"none"` plus a screen-reader-only duplicate if nested links/semantics must be exposed. |
198
- | **autoSplit** | When `true`, reverts and re-splits when fonts finish loading or when the element width changes (and lines are split), avoiding wrong line breaks. **Animations must be created inside onSplit()** so they target the newly split elements; **return** the animation from **onSplit()** for automatic cleanup and time-sync on re-split. |
199
- | **onSplit(self)** | Callback when split completes (and on each re-split if **autoSplit** is `true`). Receives the SplitText instance. Returning a GSAP tween or timeline enables automatic revert/sync of that animation when re-splitting. |
200
- | **mask** | `"lines"`, `"words"`, or `"chars"`. Wraps each unit in an extra element with `overflow: clip` for mask/reveal effects. Only one type; access wrappers on the instance’s **masks** array (or use class `-mask` if a class is set). |
201
- | **tag** | Wrapper element tag; default `"div"`. Use `"span"` for inline (note: transforms like rotation/scale may not render on inline elements in some browsers). |
202
- | **deepSlice** | When `true` (default), nested elements (e.g. `<strong>`) that span multiple lines are subdivided so lines don’t stretch vertically. Only applies when splitting lines. |
203
- | **ignore** | Selector or element(s) to leave unsplit (e.g. `ignore: "sup"`). |
204
- | **smartWrap** | When splitting **chars** only, wraps words in a `white-space: nowrap` span to avoid mid-word line breaks. Ignored if words or lines are split. Default `false`. |
205
- | **wordDelimiter** | Word boundary: string (default `" "`), RegExp, or `{ delimiter: RegExp, replaceWith: string }` for custom splitting (e.g. zero-width joiner for hashtags, or non-Latin). |
206
- | **prepareText(text, parent)** | Function that receives raw text and parent element; return modified text before splitting (e.g. to insert break markers for languages without spaces). |
207
- | **propIndex** | When `true`, adds a CSS variable with index on each split element (e.g. `--word: 1`, `--char: 2`). |
208
- | **reduceWhiteSpace** | Collapse consecutive spaces; default `true`. From v3.13.0 also honors line breaks and can insert `<br>` for `<pre>`. |
209
- | **onRevert** | Callback when the instance is reverted. |
210
-
211
- **Tips:** Split only what is animated (e.g. skip chars if only animating words). For custom fonts, split after they load (e.g. `document.fonts.ready.then(...)`) or use **autoSplit: true** with **onSplit()**. To avoid kerning shift when splitting chars, use CSS `font-kerning: none; text-rendering: optimizeSpeed;`. Avoid `text-wrap: balance`; it can interfere with splitting. SplitText does not support SVG `<text>`.
212
-
213
- **Learn more:** [SplitText](https://gsap.com/docs/v3/Plugins/SplitText/)
214
-
215
- ### ScrambleText
216
-
217
- Animates text with a scramble/glitch effect. Use when revealing or transitioning text with a scramble.
218
-
219
- ```javascript
220
- gsap.registerPlugin(ScrambleTextPlugin);
221
-
222
- gsap.to(".text", {
223
- duration: 1,
224
- scrambleText: { text: "New message", chars: "01", revealDelay: 0.5 }
225
- });
226
- ```
227
-
228
- ## SVG
229
-
230
- ### DrawSVG (DrawSVGPlugin)
231
-
232
- Reveals or hides the stroke of SVG elements by animating `stroke-dashoffset` / `stroke-dasharray`. Works on `<path>`, `<line>`, `<polyline>`, `<polygon>`, `<rect>`, `<ellipse>`. Use when “drawing” or “erasing” strokes.
233
-
234
- **drawSVG value:** Describes the **visible segment** of the stroke along the path (start and end positions), not “animate from A to B over time.” Format: `"start end"` in percent or length. Examples: `"0% 100%"` = full stroke; `"20% 80%"` = stroke only between 20% and 80% (gaps at both ends). The tween animates from the element’s **current** segment to the **target** segment — e.g. `gsap.to("#path", { drawSVG: "0% 100%" })` goes from whatever it is now to full stroke. Single value (e.g. `0`, `"100%"`) means start is 0: `"100%"` is equivalent to `"0% 100%"`.
235
-
236
- **Required:** The element must have a visible stroke — set `stroke` and `stroke-width` in CSS or as SVG attributes; otherwise nothing is drawn.
237
-
238
- ```javascript
239
- gsap.registerPlugin(DrawSVGPlugin);
240
-
241
- // draw from nothing to full stroke
242
- gsap.from("#path", { duration: 1, drawSVG: 0 });
243
- // or explicit segment: from 0–0 to 0–100%
244
- gsap.fromTo("#path", { drawSVG: "0% 0%" }, { drawSVG: "0% 100%", duration: 1 });
245
- // stroke only in the middle (gaps at ends)
246
- gsap.to("#path", { duration: 1, drawSVG: "20% 80%" });
247
- ```
248
-
249
- **Caveats:** Only affects stroke (not fill). Prefer single-segment `<path>` elements; multi-segment paths can render oddly in some browsers. Contents of `<use>` cannot be visually changed. **DrawSVGPlugin.getLength(element)** and **DrawSVGPlugin.getPosition(element)** return stroke length and current position.
250
-
251
- **Learn more:** [DrawSVG](https://gsap.com/docs/v3/Plugins/DrawSVGPlugin)
252
-
253
- ### MorphSVG (MorphSVGPlugin)
254
-
255
- Morphs one SVG shape into another by animating the `d` attribute (path data). Start and end shapes do not need the same number of points — MorphSVG converts to cubic beziers and adds points as needed. Use for icon-to-icon morphs, shape transitions, or path-based animations. Works on `<path>`, `<polyline>`, and `<polygon>`; `<circle>`, `<rect>`, `<ellipse>`, and `<line>` are converted internally or via **MorphSVGPlugin.convertToPath(selector | element)** (replaces the element in the DOM with a `<path>`).
256
-
257
- **morphSVG value:** Can be a **selector** (e.g. `"#lightning"`), an **element**, **raw path data** (e.g. `"M47.1,0.8 73.3,0.8..."`), or for polygon/polyline a **points string** (e.g. `"240,220 240,70 70,70 70,220"`). For full config use the **object form** with **shape** as the only required property.
258
-
259
- ```javascript
260
- gsap.registerPlugin(MorphSVGPlugin);
261
-
262
- // convert primitives to path first if needed:
263
- MorphSVGPlugin.convertToPath("circle, rect, ellipse, line");
264
-
265
- gsap.to("#diamond", { duration: 1, morphSVG: "#lightning", ease: "power2.inOut" });
266
- // object form:
267
- gsap.to("#diamond", {
268
- duration: 1,
269
- morphSVG: { shape: "#lightning", type: "rotational", shapeIndex: 2 }
270
- });
271
-
272
- ```
273
-
274
- **MorphSVG — key config (morphSVG object):**
275
-
276
- | Option | Description |
277
- |--------|-------------|
278
- | **shape** | _(Required.)_ Target shape: selector, element, or raw path string. |
279
- | **type** | `"linear"` (default) or `"rotational"`. Rotational uses angle/length interpolation and can avoid kinks mid-morph; try it when linear looks wrong. |
280
- | **map** | How segments are matched: `"size"` (default), `"position"`, or `"complexity"`. Use when start/end segments don’t line up; if none work, split into multiple paths and morph each. |
281
- | **shapeIndex** | Offsets which point in the start path maps to the first point in the end path (avoids shape “crossing over” or inverting). Number for single-segment paths; **array** for multi-segment (e.g. `[5, 1, -8]`). Negative reverses that segment. Use **shapeIndex: "log"** once to log the auto-calculated value, then paste the number/array into the tween. **findShapeIndex(start, end)** (separate utility) provides an interactive UI to find a good value. Only applies to closed paths. |
282
- | **smooth** | (v3.14+). Adds smoothing points. Number (e.g. `80`), `"auto"`, or object: `{ points: 40 \| "auto", redraw: true \| false, persist: true \| false }`. `redraw: false` keeps original anchors (perfect fidelity, less even spacing). `persist: false` removes added points when the tween ends. Use when the default morph looks jagged or unnatural. |
283
- | **curveMode** | Boolean (v3.14+). Interpolates control-handle angle/length instead of raw x/y to avoid kinks on curves. Try if a morph has a mid-morph kink. |
284
- | **origin** | Rotation origin for **type: "rotational"**. String: `"50% 50%"` (default) or `"20% 60%, 35% 90%"` for different start/end origins. |
285
- | **precision** | Decimal places for output path data; default `2`. |
286
- | **precompile** | Array of precomputed path strings (or use **precompile: "log"** once, copy from console). Skips expensive startup calculations; use for very complex morphs. Only for `<path>` (convert polygon/polyline first). |
287
- | **render** | Function(rawPath, target) called each update — e.g. draw to canvas. RawPath is an array of segments (each segment = array of alternating x,y cubic bezier coords). |
288
- | **updateTarget** | When using **render** (e.g. canvas-only), set **updateTarget: false** so the original `<path>` is not updated. **MorphSVGPlugin.defaultUpdateTarget** sets default. |
289
-
290
- **Utilities:** **MorphSVGPlugin.convertToPath(selector | element)** converts circle/rect/ellipse/line/polygon/polyline to `<path>` in the DOM. **MorphSVGPlugin.rawPathToString(rawPath)** and **stringToRawPath(d)** convert between path strings and raw arrays. The plugin stores the original `d` on the target (e.g. for tweening back: `morphSVG: "#originalId"` or the same element).
291
-
292
- **Tips:** For twisted or inverted morphs, set **shapeIndex** (use `"log"` or findShapeIndex()). For multi-segment paths, **shapeIndex** is an array (one value per segment). Precompile only when the first frame is slow; it does not fix jank during the tween (simplify the SVG or reduce size if needed).
293
-
294
- **Learn more:** [MorphSVG](https://gsap.com/docs/v3/Plugins/MorphSVGPlugin)
295
-
296
- ### MotionPath (MotionPathPlugin)
297
-
298
- Animates an element along an SVG path. Use when moving an object along a path (e.g. a curve or custom route).
299
-
300
- ```javascript
301
- gsap.registerPlugin(MotionPathPlugin);
302
-
303
- gsap.to(".dot", {
304
- duration: 2,
305
- motionPath: { path: "#path", align: "#path", alignOrigin: [0.5, 0.5] }
306
- });
307
- ```
308
-
309
- **MotionPath — key config (motionPath object):**
310
-
311
- | Option | Description |
312
- |--------|-------------|
313
- | `path` | SVG path element, selector, or path data string |
314
- | `align` | Path element or selector to align the target to |
315
- | `alignOrigin` | `[x, y]` origin (0–1); default `[0.5, 0.5]` |
316
- | `autoRotate` | Rotate element to follow path tangent |
317
- | `curviness` | 0–2; path smoothing |
318
-
319
- ### MotionPathHelper
320
-
321
- Visual editor for MotionPath (alignment, offset). Use during development to tune path alignment.
322
-
323
- ```javascript
324
- gsap.registerPlugin(MotionPathPlugin, MotionPathHelperPlugin);
325
-
326
- const helper = MotionPathHelper.create(".dot", "#path", { end: 0.5 });
327
- // adjust in UI, then use helper.path or helper.getProgress() in your animation
328
- ```
329
-
330
- ## Easing
331
-
332
- ### CustomEase
333
-
334
- Custom easing curves (cubic-bezier or SVG path). Use when a built-in ease is not enough. Basic usage is covered in gsap-core; register when using:
335
-
336
- ```javascript
337
- gsap.registerPlugin(CustomEase);
338
- const ease = CustomEase.create("name", ".17,.67,.83,.67");
339
- gsap.to(".el", { x: 100, ease: ease, duration: 1 });
340
- ```
341
-
342
- ### EasePack
343
-
344
- Adds more named eases (e.g. SlowMo, RoughEase, ExpoScaleEase). Register and use the ease names in tweens.
345
-
346
- ### CustomWiggle
347
-
348
- Wiggle/shake easing. Use when a value should “wiggle” (multiple oscillations).
349
-
350
- ### CustomBounce
351
-
352
- Bounce-style easing with configurable strength.
353
-
354
- ## Physics
355
-
356
- ### Physics2D (Physics2DPlugin)
357
-
358
- 2D physics (velocity, angle, gravity). Use when animating with simple physics (e.g. projectiles, bouncing).
359
-
360
- ```javascript
361
- gsap.registerPlugin(Physics2DPlugin);
362
-
363
- gsap.to(".ball", {
364
- duration: 2,
365
- physics2D: {
366
- velocity: 250,
367
- angle: 80,
368
- gravity: 500
369
- }
370
- });
371
- ```
372
-
373
- ### PhysicsProps (PhysicsPropsPlugin)
374
-
375
- Applies physics to property values. Use for physics-driven property animation.
376
-
377
- ```javascript
378
- gsap.registerPlugin(PhysicsPropsPlugin);
379
-
380
- gsap.to(".obj", {
381
- duration: 2,
382
- physicsProps: {
383
- x: { velocity: 100, end: 300 },
384
- y: { velocity: -50, acceleration: 200 }
385
- }
386
- });
387
- ```
388
-
389
- ## Development
390
-
391
- ### GSDevTools
392
-
393
- UI for scrubbing timelines, toggling animations, and debugging. Use during development only; do not ship. Register and create an instance with a timeline reference.
394
-
395
- ```javascript
396
- gsap.registerPlugin(GSDevTools);
397
- GSDevTools.create({ animation: tl });
398
- ```
399
-
400
- ## Other
401
-
402
- ### Pixi (PixiPlugin)
403
-
404
- Integrates GSAP with PixiJS for animating Pixi display objects. Register when animating Pixi objects with GSAP.
405
-
406
- ```javascript
407
- gsap.registerPlugin(PixiPlugin);
408
-
409
- const sprite = new PIXI.Sprite(texture);
410
- gsap.to(sprite, { pixi: { x: 200, y: 100, scale: 1.5 }, duration: 1 });
411
- ```
412
-
413
- ## Best practices
414
-
415
- - ✅ Register every plugin used with **gsap.registerPlugin()** before first use.
416
- - ✅ Use **Flip.getState()** → DOM change → **Flip.from()** for layout transitions; use **Draggable** + **InertiaPlugin** for drag with momentum.
417
- - ✅ Revert plugin instances (e.g. `SplitTextInstance.revert()`) when components unmount or elements are removed.
418
-
419
- ## Do Not
420
-
421
- - ❌ Use a plugin in a tween or API without registering it first (**gsap.registerPlugin()**).
422
- - ❌ Ship GSDevTools or development-only plugins to production.
423
-
424
- ### Learn More
425
-
426
- https://gsap.com/docs/v3/Plugins/
427
-
428
- ---
429
-
430
- **Slash command: `/review` or `/tribunal-full`**
431
- **Active reviewers: `logic-reviewer` · `security-auditor`**
432
-
433
- ### ❌ Forbidden AI Tropes
434
-
435
- 1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
436
- 2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
437
- 3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
438
-
439
- ---
440
-
441
- ## 🚨 LLM Trap Table
442
-
443
- |Pattern|What AI Does Wrong|What Is Actually Correct|
444
- |:---|:---|:---|
445
- |gsap-plugins|Using premium plugins without club membership|MorphSVG, SplitText, ScrollSmoother require Club GSAP|
446
- |gsap-plugins|Forgetting gsap.registerPlugin(Plugin)|Register EVERY plugin before its first use|
447
- |gsap-plugins|SplitText hurting SEO|Always call .revert() after animating SplitText to restore DOM structure|
448
-
449
- ---
450
-
451
- ## ✅ Pre-Flight Self-Audit
452
-
453
- Before producing any output, verify:
454
- ```
455
- ✅ Did I read the actual files before making claims about them?
456
- ✅ Did I verify all method names against official GSAP documentation?
457
- ✅ Did I add // VERIFY: on any uncertain API calls?
458
- ✅ Are all imports from packages that actually exist in package.json?
459
- ✅ Did I test my logic with edge cases (null, empty, 0, max)?
460
- ✅ Did I avoid generating code for more than one module at a time?
461
- ✅ Am I working from evidence, not assumption?
462
- ```
463
-
464
- ---
465
-
466
- ## 🔁 VBC Protocol (Verify → Build → Confirm)
467
-
468
- ```
469
- VERIFY: Read the actual codebase before writing anything
470
- BUILD: Generate the smallest meaningful unit of code
471
- CONFIRM: Verify the output is correct before presenting
472
- ```
473
-
474
-
475
- ## Pre-Flight Checklist
476
- - [ ] Have I reviewed the user's specific constraints and requests?
477
- - [ ] Have I checked the environment for relevant existing implementations?
478
-
479
- ## VBC Protocol (Verification-Before-Completion)
480
- You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
1
+ ---
2
+ name: gsap-plugins
3
+ description: Official GSAP skill for GSAP plugins — registration, ScrollToPlugin, ScrollSmoother, Flip, Draggable, Inertia, Observer, SplitText, ScrambleText, SVG and physics plugins, CustomEase, EasePack, CustomWiggle, CustomBounce, GSDevTools. Use when the user asks about a GSAP plugin, scroll-to, flip animations, draggable, SVG drawing, or plugin registration.
4
+ license: MIT
5
+ routing:
6
+ domain: general
7
+ tier: basic
8
+ ---
9
+
10
+ # GSAP Plugins
11
+
12
+ ## When to Use This Skill
13
+
14
+ Apply when using or reviewing code that uses GSAP plugins: registering plugins, scroll-to, flip/FLIP animations, draggable elements, SVG (DrawSVG, MorphSVG, MotionPath), text (SplitText, ScrambleText), physics, easing plugins (CustomEase, EasePack, CustomWiggle, CustomBounce), or GSDevTools. ScrollTrigger has its own skill (gsap-scrolltrigger).
15
+
16
+ **Related skills:** For core tweens use **gsap-core**; for ScrollTrigger use **gsap-scrolltrigger**; for React use **gsap-react**.
17
+
18
+ ## Registering Plugins
19
+
20
+ Register each plugin once so GSAP (and bundlers) know to include it. Use **gsap.registerPlugin()** with every plugin used in the project:
21
+
22
+ ```javascript
23
+ import gsap from "gsap";
24
+ import { ScrollToPlugin } from "gsap/ScrollToPlugin";
25
+ import { Flip } from "gsap/Flip";
26
+ import { Draggable } from "gsap/Draggable";
27
+
28
+ gsap.registerPlugin(ScrollToPlugin, Flip, Draggable);
29
+ ```
30
+
31
+ - ✅ Register before using the plugin in any tween or API call.
32
+ - ✅ In React, register at top level or once in the app (e.g. before first useGSAP); do not register inside a component that re-renders. useGSAP is a plugin that needs to be registered before use.
33
+
34
+ ## Scroll
35
+
36
+ ### ScrollToPlugin
37
+
38
+ Animates scroll position (window or a scrollable element). Use for “scroll to element” or “scroll to position” without ScrollTrigger.
39
+
40
+ ```javascript
41
+ gsap.registerPlugin(ScrollToPlugin);
42
+
43
+ gsap.to(window, { duration: 1, scrollTo: { y: 500 } });
44
+ gsap.to(window, { duration: 1, scrollTo: { y: "#section", offsetY: 50 } });
45
+ gsap.to(scrollContainer, { duration: 1, scrollTo: { x: "max" } });
46
+ ```
47
+
48
+ **ScrollToPlugin — key config (scrollTo object):**
49
+
50
+ | Option | Description |
51
+ | -------------------- | ------------------------------------------------------- |
52
+ | `x`, `y` | Target scroll position (number), or `"max"` for maximum |
53
+ | `element` | Selector or element to scroll to (for scroll-into-view) |
54
+ | `offsetX`, `offsetY` | Offset in pixels from the target position |
55
+
56
+ ### ScrollSmoother
57
+
58
+ Smooth scroll wrapper (smooths native scroll). Requires ScrollTrigger and a specific DOM structure (content wrapper + smooth wrapper). Use when smooth, momentum-style scroll is needed. See GSAP docs for setup; register after ScrollTrigger. DOM structure would look like:
59
+
60
+ ```html
61
+ <body>
62
+ <div id="smooth-wrapper">
63
+ <div id="smooth-content">
64
+ <!--- ALL YOUR CONTENT HERE --->
65
+ </div>
66
+ </div>
67
+ <!-- position: fixed elements can go outside --->
68
+ </body>
69
+ ```
70
+
71
+ ## DOM / UI
72
+
73
+ ### Flip
74
+
75
+ Capture state with `Flip.getState()`, then apply changes (e.g. layout or class changes), then use `Flip.from()` to animate from the previous state to the new state (FLIP: First, Last, Invert, Play). Use when animating between two layout states (lists, grids, expanded/collapsed).
76
+
77
+ ```javascript
78
+ gsap.registerPlugin(Flip);
79
+
80
+ const state = Flip.getState(".item");
81
+ // change DOM (reorder, add/remove, change classes)
82
+ Flip.from(state, { duration: 0.5, ease: "power2.inOut" });
83
+ ```
84
+
85
+ **Flip — key config (Flip.from vars):**
86
+
87
+ | Option | Description |
88
+ | ------------------ | -------------------------------------------------------------------------------------- |
89
+ | `absolute` | Use `position: absolute` during the flip (default: `false`) |
90
+ | `nested` | When true, only the first level of children is measured (better for nested transforms) |
91
+ | `scale` | When true, scale elements to fit (avoids stretch); default `true` |
92
+ | `simple` | When true, only position/scale are animated (faster, less accurate) |
93
+ | `duration`, `ease` | Standard tween options |
94
+
95
+ #### More information
96
+
97
+ https://gsap.com/docs/v3/Plugins/Flip
98
+
99
+ ### Draggable
100
+
101
+ Makes elements draggable, spinnable, or throwable with mouse/touch. Use for sliders, cards, reorderable lists, or any drag interaction.
102
+
103
+ ```javascript
104
+ gsap.registerPlugin(Draggable, InertiaPlugin);
105
+
106
+ Draggable.create(".box", { type: "x,y", bounds: "#container", inertia: true });
107
+ Draggable.create(".knob", { type: "rotation" });
108
+ ```
109
+
110
+ **Draggable — key config options:**
111
+
112
+ | Option | Description |
113
+ | ------------------------------------ | -------------------------------------------------------------------- |
114
+ | `type` | `"x"`, `"y"`, `"x,y"`, `"rotation"`, `"scroll"` |
115
+ | `bounds` | Element, selector, or `{ minX, maxX, minY, maxY }` to constrain drag |
116
+ | `inertia` | `true` to enable throw/momentum (requires InertiaPlugin) |
117
+ | `edgeResistance` | 0–1; resistance when dragging past bounds |
118
+ | `cursor` | CSS cursor during drag |
119
+ | `onDragStart`, `onDrag`, `onDragEnd` | Callbacks; receive event and target |
120
+ | `onThrowUpdate`, `onThrowComplete` | Callbacks when inertia is active |
121
+
122
+ ### Inertia (InertiaPlugin)
123
+
124
+ Works with Draggable for momentum after release, or track the inertia/velocity of any property of any object so that it can then seamlessly glide to a stop using a simple tween. Register with Draggable when using `inertia: true`:
125
+
126
+ ```javascript
127
+ gsap.registerPlugin(Draggable, InertiaPlugin);
128
+ Draggable.create(".box", { type: "x,y", inertia: true });
129
+ ```
130
+
131
+ Or track velocity of a property:
132
+
133
+ ```javascript
134
+ InertiaPlugin.track(".box", "x");
135
+ ```
136
+
137
+ Then use `"auto"` to continue the current velocity and glide to a stop:
138
+
139
+ ```javascript
140
+ gsap.to(obj, { inertia: { x: "auto" } });
141
+ ```
142
+
143
+ ### Observer
144
+
145
+ Normalizes pointer and scroll input across devices. Use for swipe, scroll direction, or custom gesture logic without tying directly to scroll position like ScrollTrigger.
146
+
147
+ ```javascript
148
+ gsap.registerPlugin(Observer);
149
+
150
+ Observer.create({
151
+ target: "#area",
152
+ onUp: () => {},
153
+ onDown: () => {},
154
+ onLeft: () => {},
155
+ onRight: () => {},
156
+ tolerance: 10,
157
+ });
158
+ ```
159
+
160
+ **Observer — key config options:**
161
+
162
+ | Option | Description |
163
+ | ------------------------------------- | ----------------------------------------------------------------- |
164
+ | `target` | Element or selector to observe |
165
+ | `onUp`, `onDown`, `onLeft`, `onRight` | Callbacks when swipe/scroll passes tolerance in that direction |
166
+ | `tolerance` | Pixels before direction is detected; default 10 |
167
+ | `type` | `"touch"`, `"pointer"`, or `"wheel"` (default: `"touch,pointer"`) |
168
+
169
+ ## Text
170
+
171
+ ### SplitText
172
+
173
+ Splits an element’s text into characters, words, and/or lines (each in its own element) for staggered or per-unit animation. Use when animating text character-by-character, word-by-word, or line-by-line. Returns an instance with **chars**, **words**, **lines** (and **masks** when `mask` is set). Restore original markup with **revert()** or let **gsap.context()** revert. Integrates with **gsap.context()**, **matchMedia()**, and **useGSAP()**. API: **SplitText.create(target, vars)** (target = selector, element, or array).
174
+
175
+ ```javascript
176
+ gsap.registerPlugin(SplitText);
177
+
178
+ const split = SplitText.create(".heading", { type: "words, chars" });
179
+ gsap.from(split.chars, { opacity: 0, y: 20, stagger: 0.03, duration: 0.4 });
180
+ // later: split.revert() or let gsap.context() cleanup revert
181
+ ```
182
+
183
+ With **onSplit()** (v3.13.0+), animations run on each split and on re-split when **autoSplit** is used; returning a tween/timeline from **onSplit()** lets SplitText clean up and sync progress on re-split:
184
+
185
+ ```javascript
186
+ SplitText.create(".split", {
187
+ type: "lines",
188
+ autoSplit: true,
189
+ onSplit(self) {
190
+ return gsap.from(self.lines, { y: 100, opacity: 0, stagger: 0.05, duration: 0.5 });
191
+ },
192
+ });
193
+ ```
194
+
195
+ **SplitText — key config (SplitText.create vars):**
196
+
197
+ | Option | Description |
198
+ | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
199
+ | **type** | Comma-separated: `"chars"`, `"words"`, `"lines"`. Default `"chars,words,lines"`. Only split what is needed (e.g. `"words, chars"` if not using lines) for performance. Avoid chars-only without words/lines or use **smartWrap: true** to prevent odd line breaks. |
200
+ | **charsClass**, **wordsClass**, **linesClass** | CSS class on each split element. Append `"++"` to add an incremented class (e.g. `linesClass: "line++"` → `line1`, `line2`, …). |
201
+ | **aria** | `"auto"` (default), `"hidden"`, or `"none"`. Accessibility: `"auto"` adds `aria-label` on the split element and `aria-hidden` on line/word/char elements so screen readers read the label; `"hidden"` hides all from readers; `"none"` leaves aria unchanged. Use `"none"` plus a screen-reader-only duplicate if nested links/semantics must be exposed. |
202
+ | **autoSplit** | When `true`, reverts and re-splits when fonts finish loading or when the element width changes (and lines are split), avoiding wrong line breaks. **Animations must be created inside onSplit()** so they target the newly split elements; **return** the animation from **onSplit()** for automatic cleanup and time-sync on re-split. |
203
+ | **onSplit(self)** | Callback when split completes (and on each re-split if **autoSplit** is `true`). Receives the SplitText instance. Returning a GSAP tween or timeline enables automatic revert/sync of that animation when re-splitting. |
204
+ | **mask** | `"lines"`, `"words"`, or `"chars"`. Wraps each unit in an extra element with `overflow: clip` for mask/reveal effects. Only one type; access wrappers on the instance’s **masks** array (or use class `-mask` if a class is set). |
205
+ | **tag** | Wrapper element tag; default `"div"`. Use `"span"` for inline (note: transforms like rotation/scale may not render on inline elements in some browsers). |
206
+ | **deepSlice** | When `true` (default), nested elements (e.g. `<strong>`) that span multiple lines are subdivided so lines don’t stretch vertically. Only applies when splitting lines. |
207
+ | **ignore** | Selector or element(s) to leave unsplit (e.g. `ignore: "sup"`). |
208
+ | **smartWrap** | When splitting **chars** only, wraps words in a `white-space: nowrap` span to avoid mid-word line breaks. Ignored if words or lines are split. Default `false`. |
209
+ | **wordDelimiter** | Word boundary: string (default `" "`), RegExp, or `{ delimiter: RegExp, replaceWith: string }` for custom splitting (e.g. zero-width joiner for hashtags, or non-Latin). |
210
+ | **prepareText(text, parent)** | Function that receives raw text and parent element; return modified text before splitting (e.g. to insert break markers for languages without spaces). |
211
+ | **propIndex** | When `true`, adds a CSS variable with index on each split element (e.g. `--word: 1`, `--char: 2`). |
212
+ | **reduceWhiteSpace** | Collapse consecutive spaces; default `true`. From v3.13.0 also honors line breaks and can insert `<br>` for `<pre>`. |
213
+ | **onRevert** | Callback when the instance is reverted. |
214
+
215
+ **Tips:** Split only what is animated (e.g. skip chars if only animating words). For custom fonts, split after they load (e.g. `document.fonts.ready.then(...)`) or use **autoSplit: true** with **onSplit()**. To avoid kerning shift when splitting chars, use CSS `font-kerning: none; text-rendering: optimizeSpeed;`. Avoid `text-wrap: balance`; it can interfere with splitting. SplitText does not support SVG `<text>`.
216
+
217
+ **Learn more:** [SplitText](https://gsap.com/docs/v3/Plugins/SplitText/)
218
+
219
+ ### ScrambleText
220
+
221
+ Animates text with a scramble/glitch effect. Use when revealing or transitioning text with a scramble.
222
+
223
+ ```javascript
224
+ gsap.registerPlugin(ScrambleTextPlugin);
225
+
226
+ gsap.to(".text", {
227
+ duration: 1,
228
+ scrambleText: { text: "New message", chars: "01", revealDelay: 0.5 },
229
+ });
230
+ ```
231
+
232
+ ## SVG
233
+
234
+ ### DrawSVG (DrawSVGPlugin)
235
+
236
+ Reveals or hides the stroke of SVG elements by animating `stroke-dashoffset` / `stroke-dasharray`. Works on `<path>`, `<line>`, `<polyline>`, `<polygon>`, `<rect>`, `<ellipse>`. Use when “drawing” or “erasing” strokes.
237
+
238
+ **drawSVG value:** Describes the **visible segment** of the stroke along the path (start and end positions), not “animate from A to B over time.” Format: `"start end"` in percent or length. Examples: `"0% 100%"` = full stroke; `"20% 80%"` = stroke only between 20% and 80% (gaps at both ends). The tween animates from the element’s **current** segment to the **target** segment — e.g. `gsap.to("#path", { drawSVG: "0% 100%" })` goes from whatever it is now to full stroke. Single value (e.g. `0`, `"100%"`) means start is 0: `"100%"` is equivalent to `"0% 100%"`.
239
+
240
+ **Required:** The element must have a visible stroke — set `stroke` and `stroke-width` in CSS or as SVG attributes; otherwise nothing is drawn.
241
+
242
+ ```javascript
243
+ gsap.registerPlugin(DrawSVGPlugin);
244
+
245
+ // draw from nothing to full stroke
246
+ gsap.from("#path", { duration: 1, drawSVG: 0 });
247
+ // or explicit segment: from 0–0 to 0–100%
248
+ gsap.fromTo("#path", { drawSVG: "0% 0%" }, { drawSVG: "0% 100%", duration: 1 });
249
+ // stroke only in the middle (gaps at ends)
250
+ gsap.to("#path", { duration: 1, drawSVG: "20% 80%" });
251
+ ```
252
+
253
+ **Caveats:** Only affects stroke (not fill). Prefer single-segment `<path>` elements; multi-segment paths can render oddly in some browsers. Contents of `<use>` cannot be visually changed. **DrawSVGPlugin.getLength(element)** and **DrawSVGPlugin.getPosition(element)** return stroke length and current position.
254
+
255
+ **Learn more:** [DrawSVG](https://gsap.com/docs/v3/Plugins/DrawSVGPlugin)
256
+
257
+ ### MorphSVG (MorphSVGPlugin)
258
+
259
+ Morphs one SVG shape into another by animating the `d` attribute (path data). Start and end shapes do not need the same number of points — MorphSVG converts to cubic beziers and adds points as needed. Use for icon-to-icon morphs, shape transitions, or path-based animations. Works on `<path>`, `<polyline>`, and `<polygon>`; `<circle>`, `<rect>`, `<ellipse>`, and `<line>` are converted internally or via **MorphSVGPlugin.convertToPath(selector | element)** (replaces the element in the DOM with a `<path>`).
260
+
261
+ **morphSVG value:** Can be a **selector** (e.g. `"#lightning"`), an **element**, **raw path data** (e.g. `"M47.1,0.8 73.3,0.8..."`), or for polygon/polyline a **points string** (e.g. `"240,220 240,70 70,70 70,220"`). For full config use the **object form** with **shape** as the only required property.
262
+
263
+ ```javascript
264
+ gsap.registerPlugin(MorphSVGPlugin);
265
+
266
+ // convert primitives to path first if needed:
267
+ MorphSVGPlugin.convertToPath("circle, rect, ellipse, line");
481
268
 
269
+ gsap.to("#diamond", { duration: 1, morphSVG: "#lightning", ease: "power2.inOut" });
270
+ // object form:
271
+ gsap.to("#diamond", {
272
+ duration: 1,
273
+ morphSVG: { shape: "#lightning", type: "rotational", shapeIndex: 2 },
274
+ });
275
+ ```
276
+
277
+ **MorphSVG — key config (morphSVG object):**
278
+
279
+ | Option | Description |
280
+ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
281
+ | **shape** | _(Required.)_ Target shape: selector, element, or raw path string. |
282
+ | **type** | `"linear"` (default) or `"rotational"`. Rotational uses angle/length interpolation and can avoid kinks mid-morph; try it when linear looks wrong. |
283
+ | **map** | How segments are matched: `"size"` (default), `"position"`, or `"complexity"`. Use when start/end segments don’t line up; if none work, split into multiple paths and morph each. |
284
+ | **shapeIndex** | Offsets which point in the start path maps to the first point in the end path (avoids shape “crossing over” or inverting). Number for single-segment paths; **array** for multi-segment (e.g. `[5, 1, -8]`). Negative reverses that segment. Use **shapeIndex: "log"** once to log the auto-calculated value, then paste the number/array into the tween. **findShapeIndex(start, end)** (separate utility) provides an interactive UI to find a good value. Only applies to closed paths. |
285
+ | **smooth** | (v3.14+). Adds smoothing points. Number (e.g. `80`), `"auto"`, or object: `{ points: 40 \| "auto", redraw: true \| false, persist: true \| false }`. `redraw: false` keeps original anchors (perfect fidelity, less even spacing). `persist: false` removes added points when the tween ends. Use when the default morph looks jagged or unnatural. |
286
+ | **curveMode** | Boolean (v3.14+). Interpolates control-handle angle/length instead of raw x/y to avoid kinks on curves. Try if a morph has a mid-morph kink. |
287
+ | **origin** | Rotation origin for **type: "rotational"**. String: `"50% 50%"` (default) or `"20% 60%, 35% 90%"` for different start/end origins. |
288
+ | **precision** | Decimal places for output path data; default `2`. |
289
+ | **precompile** | Array of precomputed path strings (or use **precompile: "log"** once, copy from console). Skips expensive startup calculations; use for very complex morphs. Only for `<path>` (convert polygon/polyline first). |
290
+ | **render** | Function(rawPath, target) called each update — e.g. draw to canvas. RawPath is an array of segments (each segment = array of alternating x,y cubic bezier coords). |
291
+ | **updateTarget** | When using **render** (e.g. canvas-only), set **updateTarget: false** so the original `<path>` is not updated. **MorphSVGPlugin.defaultUpdateTarget** sets default. |
292
+
293
+ **Utilities:** **MorphSVGPlugin.convertToPath(selector | element)** converts circle/rect/ellipse/line/polygon/polyline to `<path>` in the DOM. **MorphSVGPlugin.rawPathToString(rawPath)** and **stringToRawPath(d)** convert between path strings and raw arrays. The plugin stores the original `d` on the target (e.g. for tweening back: `morphSVG: "#originalId"` or the same element).
294
+
295
+ **Tips:** For twisted or inverted morphs, set **shapeIndex** (use `"log"` or findShapeIndex()). For multi-segment paths, **shapeIndex** is an array (one value per segment). Precompile only when the first frame is slow; it does not fix jank during the tween (simplify the SVG or reduce size if needed).
296
+
297
+ **Learn more:** [MorphSVG](https://gsap.com/docs/v3/Plugins/MorphSVGPlugin)
298
+
299
+ ### MotionPath (MotionPathPlugin)
300
+
301
+ Animates an element along an SVG path. Use when moving an object along a path (e.g. a curve or custom route).
302
+
303
+ ```javascript
304
+ gsap.registerPlugin(MotionPathPlugin);
305
+
306
+ gsap.to(".dot", {
307
+ duration: 2,
308
+ motionPath: { path: "#path", align: "#path", alignOrigin: [0.5, 0.5] },
309
+ });
310
+ ```
311
+
312
+ **MotionPath — key config (motionPath object):**
313
+
314
+ | Option | Description |
315
+ | ------------- | ----------------------------------------------- |
316
+ | `path` | SVG path element, selector, or path data string |
317
+ | `align` | Path element or selector to align the target to |
318
+ | `alignOrigin` | `[x, y]` origin (0–1); default `[0.5, 0.5]` |
319
+ | `autoRotate` | Rotate element to follow path tangent |
320
+ | `curviness` | 0–2; path smoothing |
321
+
322
+ ### MotionPathHelper
323
+
324
+ Visual editor for MotionPath (alignment, offset). Use during development to tune path alignment.
325
+
326
+ ```javascript
327
+ gsap.registerPlugin(MotionPathPlugin, MotionPathHelperPlugin);
328
+
329
+ const helper = MotionPathHelper.create(".dot", "#path", { end: 0.5 });
330
+ // adjust in UI, then use helper.path or helper.getProgress() in your animation
331
+ ```
332
+
333
+ ## Easing
334
+
335
+ ### CustomEase
336
+
337
+ Custom easing curves (cubic-bezier or SVG path). Use when a built-in ease is not enough. Basic usage is covered in gsap-core; register when using:
338
+
339
+ ```javascript
340
+ gsap.registerPlugin(CustomEase);
341
+ const ease = CustomEase.create("name", ".17,.67,.83,.67");
342
+ gsap.to(".el", { x: 100, ease: ease, duration: 1 });
343
+ ```
344
+
345
+ ### EasePack
346
+
347
+ Adds more named eases (e.g. SlowMo, RoughEase, ExpoScaleEase). Register and use the ease names in tweens.
348
+
349
+ ### CustomWiggle
350
+
351
+ Wiggle/shake easing. Use when a value should “wiggle” (multiple oscillations).
352
+
353
+ ### CustomBounce
354
+
355
+ Bounce-style easing with configurable strength.
356
+
357
+ ## Physics
358
+
359
+ ### Physics2D (Physics2DPlugin)
360
+
361
+ 2D physics (velocity, angle, gravity). Use when animating with simple physics (e.g. projectiles, bouncing).
362
+
363
+ ```javascript
364
+ gsap.registerPlugin(Physics2DPlugin);
365
+
366
+ gsap.to(".ball", {
367
+ duration: 2,
368
+ physics2D: {
369
+ velocity: 250,
370
+ angle: 80,
371
+ gravity: 500,
372
+ },
373
+ });
374
+ ```
375
+
376
+ ### PhysicsProps (PhysicsPropsPlugin)
377
+
378
+ Applies physics to property values. Use for physics-driven property animation.
379
+
380
+ ```javascript
381
+ gsap.registerPlugin(PhysicsPropsPlugin);
382
+
383
+ gsap.to(".obj", {
384
+ duration: 2,
385
+ physicsProps: {
386
+ x: { velocity: 100, end: 300 },
387
+ y: { velocity: -50, acceleration: 200 },
388
+ },
389
+ });
390
+ ```
391
+
392
+ ## Development
393
+
394
+ ### GSDevTools
395
+
396
+ UI for scrubbing timelines, toggling animations, and debugging. Use during development only; do not ship. Register and create an instance with a timeline reference.
397
+
398
+ ```javascript
399
+ gsap.registerPlugin(GSDevTools);
400
+ GSDevTools.create({ animation: tl });
401
+ ```
402
+
403
+ ## Other
404
+
405
+ ### Pixi (PixiPlugin)
406
+
407
+ Integrates GSAP with PixiJS for animating Pixi display objects. Register when animating Pixi objects with GSAP.
408
+
409
+ ```javascript
410
+ gsap.registerPlugin(PixiPlugin);
411
+
412
+ const sprite = new PIXI.Sprite(texture);
413
+ gsap.to(sprite, { pixi: { x: 200, y: 100, scale: 1.5 }, duration: 1 });
414
+ ```
415
+
416
+ ## Best practices
417
+
418
+ - ✅ Register every plugin used with **gsap.registerPlugin()** before first use.
419
+ - ✅ Use **Flip.getState()** → DOM change → **Flip.from()** for layout transitions; use **Draggable** + **InertiaPlugin** for drag with momentum.
420
+ - ✅ Revert plugin instances (e.g. `SplitTextInstance.revert()`) when components unmount or elements are removed.
421
+
422
+ ## Do Not
423
+
424
+ - ❌ Use a plugin in a tween or API without registering it first (**gsap.registerPlugin()**).
425
+ - ❌ Ship GSDevTools or development-only plugins to production.
426
+
427
+ ### Learn More
428
+
429
+ https://gsap.com/docs/v3/Plugins/
430
+
431
+ ---
432
+
433
+ **Slash command: `/review` or `/tribunal-full`**
434
+ **Active reviewers: `logic-reviewer` · `security-auditor`**
435
+
436
+ ### ❌ Forbidden AI Tropes
437
+
438
+ 1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
439
+ 2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
440
+ 3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
441
+
442
+ ---
443
+
444
+ ## 🚨 LLM Trap Table
445
+
446
+ | Pattern | What AI Does Wrong | What Is Actually Correct |
447
+ | :----------- | :-------------------------------------------- | :----------------------------------------------------------------------- |
448
+ | gsap-plugins | Using premium plugins without club membership | MorphSVG, SplitText, ScrollSmoother require Club GSAP |
449
+ | gsap-plugins | Forgetting gsap.registerPlugin(Plugin) | Register EVERY plugin before its first use |
450
+ | gsap-plugins | SplitText hurting SEO | Always call .revert() after animating SplitText to restore DOM structure |
451
+
452
+ ---
453
+
454
+ ## ✅ Pre-Flight Self-Audit
455
+
456
+ Before producing any output, verify:
457
+
458
+ ```
459
+ ✅ Did I read the actual files before making claims about them?
460
+ ✅ Did I verify all method names against official GSAP documentation?
461
+ ✅ Did I add // VERIFY: on any uncertain API calls?
462
+ ✅ Are all imports from packages that actually exist in package.json?
463
+ ✅ Did I test my logic with edge cases (null, empty, 0, max)?
464
+ ✅ Did I avoid generating code for more than one module at a time?
465
+ ✅ Am I working from evidence, not assumption?
466
+ ```
467
+
468
+ ---
469
+
470
+ ## 🔁 VBC Protocol (Verify → Build → Confirm)
471
+
472
+ ```
473
+ VERIFY: Read the actual codebase before writing anything
474
+ BUILD: Generate the smallest meaningful unit of code
475
+ CONFIRM: Verify the output is correct before presenting
476
+ ```
477
+
478
+ ## Pre-Flight Checklist
479
+
480
+ - [ ] Have I reviewed the user's specific constraints and requests?
481
+ - [ ] Have I checked the environment for relevant existing implementations?
482
+
483
+ ## VBC Protocol (Verification-Before-Completion)
484
+
485
+ You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.
482
486
 
483
487
  ---
484
488
 
@@ -508,6 +512,7 @@ AI coding assistants often fall into specific bad habits when dealing with this
508
512
  ### ✅ Pre-Flight Self-Audit
509
513
 
510
514
  Review these questions before confirming output:
515
+
511
516
  ```
512
517
  ✅ Did I rely ONLY on real, verified tools and methods?
513
518
  ✅ Is this solution appropriately scoped to the user's constraints?
@@ -518,5 +523,6 @@ Review these questions before confirming output:
518
523
  ### 🛑 Verification-Before-Completion (VBC) Protocol
519
524
 
520
525
  **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
526
+
521
527
  - ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
522
528
  - ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.