tribunal-kit 6.0.1 → 7.0.0

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 (349) hide show
  1. package/.agent/ARCHITECTURE.md +9 -6
  2. package/.agent/agents/accessibility-reviewer.md +23 -16
  3. package/.agent/agents/ai-code-reviewer.md +25 -21
  4. package/.agent/agents/anti-pattern-reviewer.md +12 -7
  5. package/.agent/agents/api-architect.md +1 -0
  6. package/.agent/agents/backend-specialist.md +23 -22
  7. package/.agent/agents/cloud-engineer.md +1 -0
  8. package/.agent/agents/code-archaeologist.md +1 -0
  9. package/.agent/agents/complexity-reviewer.md +10 -7
  10. package/.agent/agents/database-architect.md +3 -2
  11. package/.agent/agents/db-latency-auditor.md +6 -2
  12. package/.agent/agents/debugger.md +3 -2
  13. package/.agent/agents/dependency-reviewer.md +1 -0
  14. package/.agent/agents/devops-engineer.md +9 -8
  15. package/.agent/agents/documentation-writer.md +6 -5
  16. package/.agent/agents/explorer-agent.md +1 -0
  17. package/.agent/agents/frontend-reviewer.md +21 -17
  18. package/.agent/agents/frontend-specialist.md +23 -20
  19. package/.agent/agents/game-developer.md +1 -0
  20. package/.agent/agents/interaction-reviewer.md +10 -5
  21. package/.agent/agents/logic-reviewer.md +3 -0
  22. package/.agent/agents/minimalist-reviewer.md +6 -0
  23. package/.agent/agents/mobile-developer.md +7 -6
  24. package/.agent/agents/mobile-reviewer.md +14 -13
  25. package/.agent/agents/orchestrator.md +3 -0
  26. package/.agent/agents/penetration-tester.md +1 -0
  27. package/.agent/agents/performance-optimizer.md +6 -5
  28. package/.agent/agents/performance-reviewer.md +6 -6
  29. package/.agent/agents/pipeline-reviewer.md +144 -0
  30. package/.agent/agents/precedence-reviewer.md +1 -0
  31. package/.agent/agents/product-manager.md +1 -0
  32. package/.agent/agents/product-owner.md +1 -0
  33. package/.agent/agents/product-reviewer.md +12 -7
  34. package/.agent/agents/project-planner.md +3 -0
  35. package/.agent/agents/qa-automation-engineer.md +50 -43
  36. package/.agent/agents/resilience-reviewer.md +1 -0
  37. package/.agent/agents/schema-reviewer.md +1 -0
  38. package/.agent/agents/security-auditor.md +24 -24
  39. package/.agent/agents/seo-specialist.md +33 -23
  40. package/.agent/agents/sql-reviewer.md +5 -4
  41. package/.agent/agents/supervisor-agent.md +12 -2
  42. package/.agent/agents/swarm-worker-contracts.md +13 -13
  43. package/.agent/agents/swarm-worker-registry.md +51 -51
  44. package/.agent/agents/system-architect.md +1 -0
  45. package/.agent/agents/test-coverage-reviewer.md +25 -22
  46. package/.agent/agents/test-engineer.md +12 -11
  47. package/.agent/agents/throughput-optimizer.md +45 -40
  48. package/.agent/agents/type-safety-reviewer.md +5 -4
  49. package/.agent/agents/ui-ux-auditor.md +6 -4
  50. package/.agent/agents/ui-visual-auditor.md +3 -0
  51. package/.agent/agents/ux-reviewer.md +11 -6
  52. package/.agent/agents/visual-reviewer.md +11 -6
  53. package/.agent/agents/vitals-reviewer.md +5 -4
  54. package/.agent/history/memory/.memory.idx +1532 -1
  55. package/.agent/history/memory/MEMORY.md +102 -1
  56. package/.agent/mcp_config.json +1 -6
  57. package/.agent/routing_index.json +2033 -263
  58. package/.agent/rules/GEMINI.md +11 -9
  59. package/.agent/rules/GEMINI_PLANNER.md +19 -21
  60. package/.agent/scripts/_colors.js +52 -54
  61. package/.agent/scripts/_utils.js +52 -53
  62. package/.agent/scripts/auto_preview.js +39 -43
  63. package/.agent/scripts/bundle_analyzer.js +47 -60
  64. package/.agent/scripts/case_law_manager.js +200 -294
  65. package/.agent/scripts/checklist.js +73 -94
  66. package/.agent/scripts/cicd_validator.js +305 -0
  67. package/.agent/scripts/compile_router.py +4 -111
  68. package/.agent/scripts/context_broker.js +317 -412
  69. package/.agent/scripts/contract_engine.js +402 -0
  70. package/.agent/scripts/dependency_analyzer.js +112 -124
  71. package/.agent/scripts/graph_builder.js +75 -103
  72. package/.agent/scripts/graph_visualizer.js +10 -12
  73. package/.agent/scripts/graph_zoom.js +38 -55
  74. package/.agent/scripts/guardrail_engine.js +195 -145
  75. package/.agent/scripts/impact_classifier.js +55 -30
  76. package/.agent/scripts/inner_loop_validator.js +108 -159
  77. package/.agent/scripts/integrity_manifest.js +59 -67
  78. package/.agent/scripts/lint_runner.js +65 -75
  79. package/.agent/scripts/marathon_harness.js +131 -208
  80. package/.agent/scripts/migrate_skills_frontmatter.py +4 -63
  81. package/.agent/scripts/minify_context.js +29 -33
  82. package/.agent/scripts/minimal_change_engine.js +95 -87
  83. package/.agent/scripts/mutation_runner.js +46 -62
  84. package/.agent/scripts/pipeline_engine.js +320 -209
  85. package/.agent/scripts/prompt_compiler.js +118 -93
  86. package/.agent/scripts/schema_validator.js +73 -121
  87. package/.agent/scripts/security_scan.js +88 -117
  88. package/.agent/scripts/session_manager.js +52 -69
  89. package/.agent/scripts/signal_detector.js +24 -22
  90. package/.agent/scripts/skill_evolution.js +184 -245
  91. package/.agent/scripts/skill_integrator.js +35 -48
  92. package/.agent/scripts/socratic_gate_policy.js +15 -12
  93. package/.agent/scripts/strengthen_skills.js +29 -33
  94. package/.agent/scripts/swarm_dispatcher.js +120 -151
  95. package/.agent/scripts/test_runner.js +54 -56
  96. package/.agent/scripts/token_budget_broker.js +9 -7
  97. package/.agent/scripts/trace_engine.js +126 -0
  98. package/.agent/scripts/verify_all.js +76 -93
  99. package/.agent/scripts/visual_audit.js +16 -21
  100. package/.agent/skill_topic_map.json +22 -3
  101. package/.agent/skills/12-principles-of-animation/SKILL.md +7 -0
  102. package/.agent/skills/60fps-animation/SKILL.md +7 -0
  103. package/.agent/skills/accessible-animation/SKILL.md +5 -1
  104. package/.agent/skills/adapt/SKILL.md +7 -1
  105. package/.agent/skills/advanced-rag-pipelines/SKILL.md +1 -0
  106. package/.agent/skills/agent-organizer/SKILL.md +1 -0
  107. package/.agent/skills/agentic-patterns/SKILL.md +33 -25
  108. package/.agent/skills/agentic-workflows-2026/SKILL.md +6 -2
  109. package/.agent/skills/ai-app-hardening/SKILL.md +9 -8
  110. package/.agent/skills/ai-prompt-injection-defense/SKILL.md +7 -6
  111. package/.agent/skills/animation-on-scroll/SKILL.md +24 -15
  112. package/.agent/skills/animation-systems/SKILL.md +11 -10
  113. package/.agent/skills/antfu-conventions/SKILL.md +7 -2
  114. package/.agent/skills/api-patterns/SKILL.md +14 -10
  115. package/.agent/skills/api-security-auditor/SKILL.md +15 -14
  116. package/.agent/skills/app-builder/SKILL.md +1 -0
  117. package/.agent/skills/app-builder/templates/nextjs-fullstack/TEMPLATE.md +2 -2
  118. package/.agent/skills/app-builder/templates/nextjs-saas/TEMPLATE.md +1 -1
  119. package/.agent/skills/app-builder/templates/nextjs-static/TEMPLATE.md +12 -12
  120. package/.agent/skills/app-builder/templates/nuxt-app/TEMPLATE.md +3 -3
  121. package/.agent/skills/apple-design/SKILL.md +8 -7
  122. package/.agent/skills/architecture/SKILL.md +3 -2
  123. package/.agent/skills/audit-and-fix/SKILL.md +8 -5
  124. package/.agent/skills/authentication-best-practices/SKILL.md +9 -8
  125. package/.agent/skills/backend-security-expert/SKILL.md +1 -0
  126. package/.agent/skills/baseline-ui/SKILL.md +8 -7
  127. package/.agent/skills/bash-linux/SKILL.md +1 -0
  128. package/.agent/skills/behavioral-modes/SKILL.md +1 -0
  129. package/.agent/skills/better-colors/SKILL.md +11 -7
  130. package/.agent/skills/better-typography/SKILL.md +30 -16
  131. package/.agent/skills/better-ui/SKILL.md +17 -10
  132. package/.agent/skills/bolder/SKILL.md +6 -0
  133. package/.agent/skills/brainstorming/SKILL.md +6 -4
  134. package/.agent/skills/browser-native-ai/SKILL.md +5 -4
  135. package/.agent/skills/build-primitive/SKILL.md +5 -0
  136. package/.agent/skills/building-native-ui/SKILL.md +1 -0
  137. package/.agent/skills/cicd-pro/SKILL.md +2 -1
  138. package/.agent/skills/clarify/SKILL.md +19 -14
  139. package/.agent/skills/clean-code/SKILL.md +16 -15
  140. package/.agent/skills/cloud-architect/SKILL.md +1 -0
  141. package/.agent/skills/cobejs/SKILL.md +7 -9
  142. package/.agent/skills/code-review-checklist/SKILL.md +1 -0
  143. package/.agent/skills/codebase-design/SKILL.md +7 -2
  144. package/.agent/skills/colorize/SKILL.md +8 -3
  145. package/.agent/skills/compact-landing/SKILL.md +8 -3
  146. package/.agent/skills/company-logos/SKILL.md +6 -0
  147. package/.agent/skills/config-validator/SKILL.md +10 -9
  148. package/.agent/skills/containerization-pro/SKILL.md +6 -5
  149. package/.agent/skills/context-engineering-pro/SKILL.md +5 -4
  150. package/.agent/skills/create-design-md/SKILL.md +13 -5
  151. package/.agent/skills/critique/SKILL.md +10 -8
  152. package/.agent/skills/csharp-developer/SKILL.md +1 -0
  153. package/.agent/skills/data-validation-schemas/SKILL.md +28 -23
  154. package/.agent/skills/database-design/SKILL.md +2 -1
  155. package/.agent/skills/delight/SKILL.md +6 -0
  156. package/.agent/skills/deployment-procedures/SKILL.md +2 -1
  157. package/.agent/skills/design-lab/SKILL.md +5 -0
  158. package/.agent/skills/devops-engineer/SKILL.md +3 -2
  159. package/.agent/skills/devops-incident-responder/SKILL.md +2 -1
  160. package/.agent/skills/diagnosing-bugs/SKILL.md +12 -2
  161. package/.agent/skills/distill/SKILL.md +7 -2
  162. package/.agent/skills/documentation-templates/SKILL.md +3 -2
  163. package/.agent/skills/domain-modeling/SKILL.md +12 -4
  164. package/.agent/skills/duckdb-analytical-sql/SKILL.md +7 -3
  165. package/.agent/skills/edge-ai-mobile/SKILL.md +5 -1
  166. package/.agent/skills/edge-computing/SKILL.md +9 -8
  167. package/.agent/skills/emil-design-eng/SKILL.md +43 -27
  168. package/.agent/skills/error-resilience/SKILL.md +34 -16
  169. package/.agent/skills/expo-router-v4/SKILL.md +2 -1
  170. package/.agent/skills/extract-design-system/SKILL.md +12 -11
  171. package/.agent/skills/fabel-protocol/SKILL.md +24 -17
  172. package/.agent/skills/fixing-accessibility/SKILL.md +23 -16
  173. package/.agent/skills/fixing-metadata/SKILL.md +24 -13
  174. package/.agent/skills/fixing-motion-performance/SKILL.md +7 -5
  175. package/.agent/skills/framer-motion-expert/SKILL.md +29 -15
  176. package/.agent/skills/frontend-design/SKILL.md +21 -13
  177. package/.agent/skills/frontend-security-expert/SKILL.md +1 -0
  178. package/.agent/skills/game-design-expert/SKILL.md +1 -0
  179. package/.agent/skills/game-engineering-expert/SKILL.md +1 -0
  180. package/.agent/skills/generative-ui-expert/SKILL.md +3 -2
  181. package/.agent/skills/geo-fundamentals/SKILL.md +2 -1
  182. package/.agent/skills/git-pro/SKILL.md +10 -9
  183. package/.agent/skills/github-operations/SKILL.md +2 -1
  184. package/.agent/skills/gpt-taste/SKILL.md +7 -0
  185. package/.agent/skills/gsap-core/SKILL.md +26 -22
  186. package/.agent/skills/gsap-frameworks/SKILL.md +6 -5
  187. package/.agent/skills/gsap-performance/SKILL.md +4 -3
  188. package/.agent/skills/gsap-plugins/SKILL.md +34 -33
  189. package/.agent/skills/gsap-react/SKILL.md +9 -8
  190. package/.agent/skills/gsap-scrolltrigger/SKILL.md +34 -33
  191. package/.agent/skills/gsap-timeline/SKILL.md +18 -15
  192. package/.agent/skills/gsap-utils/SKILL.md +25 -24
  193. package/.agent/skills/harden/SKILL.md +9 -3
  194. package/.agent/skills/harness-protocol/SKILL.md +1 -0
  195. package/.agent/skills/i18n-localization/SKILL.md +10 -9
  196. package/.agent/skills/impeccable/SKILL.md +5 -0
  197. package/.agent/skills/improve-codebase-architecture/SKILL.md +10 -5
  198. package/.agent/skills/improve-ui/SKILL.md +12 -5
  199. package/.agent/skills/intelligent-routing/SKILL.md +7 -6
  200. package/.agent/skills/knowledge-graph/SKILL.md +1 -0
  201. package/.agent/skills/landing-page/SKILL.md +1 -0
  202. package/.agent/skills/lint-and-validate/SKILL.md +9 -4
  203. package/.agent/skills/llm-engineering/SKILL.md +55 -54
  204. package/.agent/skills/local-first/SKILL.md +20 -19
  205. package/.agent/skills/local-first-architecture/SKILL.md +6 -1
  206. package/.agent/skills/lottie-animation/SKILL.md +7 -3
  207. package/.agent/skills/marquee-loop/SKILL.md +1 -0
  208. package/.agent/skills/masked-reveal/SKILL.md +17 -4
  209. package/.agent/skills/mcp-builder/SKILL.md +13 -10
  210. package/.agent/skills/micro-interaction/SKILL.md +20 -5
  211. package/.agent/skills/mobile-design/SKILL.md +26 -15
  212. package/.agent/skills/monorepo-management/SKILL.md +3 -2
  213. package/.agent/skills/morphing-icons/SKILL.md +16 -6
  214. package/.agent/skills/motion-engineering/SKILL.md +19 -15
  215. package/.agent/skills/nextjs-react-expert/SKILL.md +26 -21
  216. package/.agent/skills/nodejs-best-practices/SKILL.md +89 -76
  217. package/.agent/skills/observability/SKILL.md +45 -44
  218. package/.agent/skills/opentelemetry-observability/SKILL.md +2 -1
  219. package/.agent/skills/page-transition-animation/SKILL.md +6 -3
  220. package/.agent/skills/parallel-agents/SKILL.md +7 -2
  221. package/.agent/skills/performance-profiling/SKILL.md +24 -13
  222. package/.agent/skills/plan-writing/SKILL.md +1 -0
  223. package/.agent/skills/platform-engineer/SKILL.md +3 -2
  224. package/.agent/skills/platform-engineering-opentofu/SKILL.md +1 -0
  225. package/.agent/skills/playwright-ai-e2e/SKILL.md +3 -2
  226. package/.agent/skills/playwright-best-practices/SKILL.md +29 -28
  227. package/.agent/skills/polish/SKILL.md +13 -12
  228. package/.agent/skills/powershell-windows/SKILL.md +1 -0
  229. package/.agent/skills/pricing-page/SKILL.md +8 -3
  230. package/.agent/skills/product-aware-heuristics/SKILL.md +122 -72
  231. package/.agent/skills/progressive-blur/SKILL.md +9 -4
  232. package/.agent/skills/project-idioms/SKILL.md +1 -0
  233. package/.agent/skills/property-based-testing/SKILL.md +10 -12
  234. package/.agent/skills/python-patterns/SKILL.md +1 -0
  235. package/.agent/skills/python-pro/SKILL.md +1 -0
  236. package/.agent/skills/quieter/SKILL.md +6 -0
  237. package/.agent/skills/react-doctor/SKILL.md +6 -0
  238. package/.agent/skills/react-specialist/SKILL.md +32 -28
  239. package/.agent/skills/readme-builder/SKILL.md +1 -0
  240. package/.agent/skills/realtime-patterns/SKILL.md +34 -33
  241. package/.agent/skills/red-team-tactics/SKILL.md +1 -0
  242. package/.agent/skills/redesign-skill/SKILL.md +6 -0
  243. package/.agent/skills/review-animations/SKILL.md +5 -2
  244. package/.agent/skills/review-animations/STANDARDS.md +37 -23
  245. package/.agent/skills/rust-pro/SKILL.md +1 -0
  246. package/.agent/skills/seo-fundamentals/SKILL.md +4 -3
  247. package/.agent/skills/server-management/SKILL.md +1 -0
  248. package/.agent/skills/shadcn-ui-expert/SKILL.md +28 -22
  249. package/.agent/skills/shape/SKILL.md +9 -2
  250. package/.agent/skills/skill-creator/SKILL.md +1 -0
  251. package/.agent/skills/soft-skill/SKILL.md +6 -0
  252. package/.agent/skills/sounds-on-the-web/SKILL.md +1 -0
  253. package/.agent/skills/sql-pro/SKILL.md +1 -0
  254. package/.agent/skills/supabase-postgres-best-practices/SKILL.md +1 -0
  255. package/.agent/skills/svg-animation/SKILL.md +16 -7
  256. package/.agent/skills/swiftui-expert/SKILL.md +1 -0
  257. package/.agent/skills/swiss-design/SKILL.md +5 -0
  258. package/.agent/skills/system-design-pro/SKILL.md +1 -0
  259. package/.agent/skills/systematic-debugging/SKILL.md +1 -0
  260. package/.agent/skills/tailwind-patterns/SKILL.md +25 -11
  261. package/.agent/skills/taste-skill/SKILL.md +6 -0
  262. package/.agent/skills/tdd-workflow/SKILL.md +5 -0
  263. package/.agent/skills/test-result-analyzer/SKILL.md +1 -0
  264. package/.agent/skills/testing-patterns/SKILL.md +123 -115
  265. package/.agent/skills/thermo-nuclear-code-quality-review/SKILL.md +5 -0
  266. package/.agent/skills/thinking-protocol/SKILL.md +3 -0
  267. package/.agent/skills/to-spring-or-not-to-spring/SKILL.md +9 -8
  268. package/.agent/skills/transitions-dev/SKILL.md +19 -6
  269. package/.agent/skills/trend-researcher/SKILL.md +1 -0
  270. package/.agent/skills/typescript-advanced/SKILL.md +23 -18
  271. package/.agent/skills/typeset/SKILL.md +10 -1
  272. package/.agent/skills/ui-reasoning-engine/SKILL.md +67 -48
  273. package/.agent/skills/ui-skill-packs/SKILL.md +6 -1
  274. package/.agent/skills/ui-skills-root/SKILL.md +39 -38
  275. package/.agent/skills/ui-ux-pro-max/SKILL.md +34 -26
  276. package/.agent/skills/ui-ux-researcher/SKILL.md +1 -0
  277. package/.agent/skills/vector-search-pgvector/SKILL.md +3 -2
  278. package/.agent/skills/vue-expert/SKILL.md +22 -19
  279. package/.agent/skills/vulnerability-scanner/SKILL.md +22 -21
  280. package/.agent/skills/web-accessibility-auditor/SKILL.md +2 -1
  281. package/.agent/skills/web-design-guidelines/SKILL.md +16 -10
  282. package/.agent/skills/web-quality-audit/SKILL.md +5 -0
  283. package/.agent/skills/webapp-testing/SKILL.md +14 -13
  284. package/.agent/skills/webgpu-performance/SKILL.md +1 -0
  285. package/.agent/skills/whimsy-injector/SKILL.md +9 -5
  286. package/.agent/skills/workflow-optimizer/SKILL.md +1 -0
  287. package/.agent/skills/zero-trust-passkeys/SKILL.md +11 -6
  288. package/.agent/templates/DESIGN.md +119 -110
  289. package/.agent/templates/design-tokens.json +9 -6
  290. package/.agent/workflows/acf.md +1 -0
  291. package/.agent/workflows/api-tester.md +1 -0
  292. package/.agent/workflows/audit.md +1 -0
  293. package/.agent/workflows/brainstorm.md +1 -0
  294. package/.agent/workflows/changelog.md +1 -0
  295. package/.agent/workflows/contract.md +60 -0
  296. package/.agent/workflows/create.md +1 -0
  297. package/.agent/workflows/debug.md +1 -0
  298. package/.agent/workflows/deploy.md +1 -0
  299. package/.agent/workflows/enhance.md +1 -0
  300. package/.agent/workflows/fix-ci.md +89 -0
  301. package/.agent/workflows/fix.md +1 -0
  302. package/.agent/workflows/generate.md +1 -0
  303. package/.agent/workflows/marathon.md +1 -0
  304. package/.agent/workflows/migrate.md +1 -0
  305. package/.agent/workflows/minimal.md +9 -7
  306. package/.agent/workflows/orchestrate.md +1 -0
  307. package/.agent/workflows/performance-benchmarker.md +1 -0
  308. package/.agent/workflows/pipeline.md +26 -21
  309. package/.agent/workflows/plan.md +1 -0
  310. package/.agent/workflows/preview.md +1 -0
  311. package/.agent/workflows/refactor.md +3 -2
  312. package/.agent/workflows/review-ai.md +4 -3
  313. package/.agent/workflows/review.md +1 -0
  314. package/.agent/workflows/session.md +1 -0
  315. package/.agent/workflows/status.md +1 -0
  316. package/.agent/workflows/strengthen-skills.md +1 -0
  317. package/.agent/workflows/super-prompt.md +1 -0
  318. package/.agent/workflows/swarm.md +15 -3
  319. package/.agent/workflows/test.md +8 -7
  320. package/.agent/workflows/tribunal-backend.md +3 -2
  321. package/.agent/workflows/tribunal-cicd.md +104 -0
  322. package/.agent/workflows/tribunal-database.md +1 -0
  323. package/.agent/workflows/tribunal-frontend.md +8 -6
  324. package/.agent/workflows/tribunal-full.md +2 -1
  325. package/.agent/workflows/tribunal-mobile.md +6 -5
  326. package/.agent/workflows/tribunal-performance.md +1 -0
  327. package/.agent/workflows/tribunal-speed.md +1 -0
  328. package/.agent/workflows/tribunal-ui.md +29 -21
  329. package/.agent/workflows/ui-ux-pro-max.md +19 -15
  330. package/CONTRIBUTING.md +3 -3
  331. package/README.md +94 -44
  332. package/SECURITY.md +10 -10
  333. package/bin/mcp-server.js +385 -252
  334. package/bin/tribunal-kit.js +29 -30
  335. package/bin/wrapper.js +40 -46
  336. package/dist/cli.js +6 -0
  337. package/dist/commands/case.js +2 -0
  338. package/dist/commands/contract.js +440 -0
  339. package/dist/commands/status.js +6 -0
  340. package/dist/index.d.ts +8 -1
  341. package/package.json +13 -12
  342. package/scripts/benchmark.js +62 -86
  343. package/scripts/changelog.js +67 -73
  344. package/scripts/fix-vbc.js +13 -15
  345. package/scripts/fix-vbc.ps1 +2 -118
  346. package/scripts/stress_benchmark.js +358 -0
  347. package/scripts/sync-version.js +71 -41
  348. package/scripts/validate-payload.js +23 -30
  349. package/scripts/visual_audit.js +23 -13
@@ -20,6 +20,7 @@ scripts-binding:
20
20
  ## Mandatory Pre-Flight Context Inspection
21
21
 
22
22
  Before invoking GSAP plugins, you MUST inspect:
23
+
23
24
  1. `package.json` → Verify plugin installation and check for Club GSAP licensing requirements (`MorphSVG`, `SplitText`, `ScrollSmoother`)
24
25
  2. Plugin Registration (Section 18) → Always register plugins explicitly via `gsap.registerPlugin(...)` at module root
25
26
  3. Revert & Cleanup (Section 418) → Call `.revert()` on SplitText and Flip instances during component unmount
@@ -35,10 +36,10 @@ Apply when using or reviewing code that uses GSAP plugins: registering plugins,
35
36
  Register each plugin once so GSAP (and bundlers) know to include it. Use **gsap.registerPlugin()** with every plugin used in the project:
36
37
 
37
38
  ```javascript
38
- import gsap from "gsap";
39
- import { ScrollToPlugin } from "gsap/ScrollToPlugin";
40
- import { Flip } from "gsap/Flip";
41
- import { Draggable } from "gsap/Draggable";
39
+ import gsap from 'gsap';
40
+ import { ScrollToPlugin } from 'gsap/ScrollToPlugin';
41
+ import { Flip } from 'gsap/Flip';
42
+ import { Draggable } from 'gsap/Draggable';
42
43
 
43
44
  gsap.registerPlugin(ScrollToPlugin, Flip, Draggable);
44
45
  ```
@@ -56,8 +57,8 @@ Animates scroll position (window or a scrollable element). Use for “scroll to
56
57
  gsap.registerPlugin(ScrollToPlugin);
57
58
 
58
59
  gsap.to(window, { duration: 1, scrollTo: { y: 500 } });
59
- gsap.to(window, { duration: 1, scrollTo: { y: "#section", offsetY: 50 } });
60
- gsap.to(scrollContainer, { duration: 1, scrollTo: { x: "max" } });
60
+ gsap.to(window, { duration: 1, scrollTo: { y: '#section', offsetY: 50 } });
61
+ gsap.to(scrollContainer, { duration: 1, scrollTo: { x: 'max' } });
61
62
  ```
62
63
 
63
64
  **ScrollToPlugin — key config (scrollTo object):**
@@ -92,9 +93,9 @@ Capture state with `Flip.getState()`, then apply changes (e.g. layout or class c
92
93
  ```javascript
93
94
  gsap.registerPlugin(Flip);
94
95
 
95
- const state = Flip.getState(".item");
96
+ const state = Flip.getState('.item');
96
97
  // change DOM (reorder, add/remove, change classes)
97
- Flip.from(state, { duration: 0.5, ease: "power2.inOut" });
98
+ Flip.from(state, { duration: 0.5, ease: 'power2.inOut' });
98
99
  ```
99
100
 
100
101
  **Flip — key config (Flip.from vars):**
@@ -118,8 +119,8 @@ Makes elements draggable, spinnable, or throwable with mouse/touch. Use for slid
118
119
  ```javascript
119
120
  gsap.registerPlugin(Draggable, InertiaPlugin);
120
121
 
121
- Draggable.create(".box", { type: "x,y", bounds: "#container", inertia: true });
122
- Draggable.create(".knob", { type: "rotation" });
122
+ Draggable.create('.box', { type: 'x,y', bounds: '#container', inertia: true });
123
+ Draggable.create('.knob', { type: 'rotation' });
123
124
  ```
124
125
 
125
126
  **Draggable — key config options:**
@@ -140,19 +141,19 @@ Works with Draggable for momentum after release, or track the inertia/velocity o
140
141
 
141
142
  ```javascript
142
143
  gsap.registerPlugin(Draggable, InertiaPlugin);
143
- Draggable.create(".box", { type: "x,y", inertia: true });
144
+ Draggable.create('.box', { type: 'x,y', inertia: true });
144
145
  ```
145
146
 
146
147
  Or track velocity of a property:
147
148
 
148
149
  ```javascript
149
- InertiaPlugin.track(".box", "x");
150
+ InertiaPlugin.track('.box', 'x');
150
151
  ```
151
152
 
152
153
  Then use `"auto"` to continue the current velocity and glide to a stop:
153
154
 
154
155
  ```javascript
155
- gsap.to(obj, { inertia: { x: "auto" } });
156
+ gsap.to(obj, { inertia: { x: 'auto' } });
156
157
  ```
157
158
 
158
159
  ### Observer
@@ -163,7 +164,7 @@ Normalizes pointer and scroll input across devices. Use for swipe, scroll direct
163
164
  gsap.registerPlugin(Observer);
164
165
 
165
166
  Observer.create({
166
- target: "#area",
167
+ target: '#area',
167
168
  onUp: () => {},
168
169
  onDown: () => {},
169
170
  onLeft: () => {},
@@ -190,7 +191,7 @@ Splits an element’s text into characters, words, and/or lines (each in its own
190
191
  ```javascript
191
192
  gsap.registerPlugin(SplitText);
192
193
 
193
- const split = SplitText.create(".heading", { type: "words, chars" });
194
+ const split = SplitText.create('.heading', { type: 'words, chars' });
194
195
  gsap.from(split.chars, { opacity: 0, y: 20, stagger: 0.03, duration: 0.4 });
195
196
  // later: split.revert() or let gsap.context() cleanup revert
196
197
  ```
@@ -198,8 +199,8 @@ gsap.from(split.chars, { opacity: 0, y: 20, stagger: 0.03, duration: 0.4 });
198
199
  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:
199
200
 
200
201
  ```javascript
201
- SplitText.create(".split", {
202
- type: "lines",
202
+ SplitText.create('.split', {
203
+ type: 'lines',
203
204
  autoSplit: true,
204
205
  onSplit(self) {
205
206
  return gsap.from(self.lines, { y: 100, opacity: 0, stagger: 0.05, duration: 0.5 });
@@ -238,9 +239,9 @@ Animates text with a scramble/glitch effect. Use when revealing or transitioning
238
239
  ```javascript
239
240
  gsap.registerPlugin(ScrambleTextPlugin);
240
241
 
241
- gsap.to(".text", {
242
+ gsap.to('.text', {
242
243
  duration: 1,
243
- scrambleText: { text: "New message", chars: "01", revealDelay: 0.5 },
244
+ scrambleText: { text: 'New message', chars: '01', revealDelay: 0.5 },
244
245
  });
245
246
  ```
246
247
 
@@ -258,11 +259,11 @@ Reveals or hides the stroke of SVG elements by animating `stroke-dashoffset` / `
258
259
  gsap.registerPlugin(DrawSVGPlugin);
259
260
 
260
261
  // draw from nothing to full stroke
261
- gsap.from("#path", { duration: 1, drawSVG: 0 });
262
+ gsap.from('#path', { duration: 1, drawSVG: 0 });
262
263
  // or explicit segment: from 0–0 to 0–100%
263
- gsap.fromTo("#path", { drawSVG: "0% 0%" }, { drawSVG: "0% 100%", duration: 1 });
264
+ gsap.fromTo('#path', { drawSVG: '0% 0%' }, { drawSVG: '0% 100%', duration: 1 });
264
265
  // stroke only in the middle (gaps at ends)
265
- gsap.to("#path", { duration: 1, drawSVG: "20% 80%" });
266
+ gsap.to('#path', { duration: 1, drawSVG: '20% 80%' });
266
267
  ```
267
268
 
268
269
  **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.
@@ -279,13 +280,13 @@ Morphs one SVG shape into another by animating the `d` attribute (path data). St
279
280
  gsap.registerPlugin(MorphSVGPlugin);
280
281
 
281
282
  // convert primitives to path first if needed:
282
- MorphSVGPlugin.convertToPath("circle, rect, ellipse, line");
283
+ MorphSVGPlugin.convertToPath('circle, rect, ellipse, line');
283
284
 
284
- gsap.to("#diamond", { duration: 1, morphSVG: "#lightning", ease: "power2.inOut" });
285
+ gsap.to('#diamond', { duration: 1, morphSVG: '#lightning', ease: 'power2.inOut' });
285
286
  // object form:
286
- gsap.to("#diamond", {
287
+ gsap.to('#diamond', {
287
288
  duration: 1,
288
- morphSVG: { shape: "#lightning", type: "rotational", shapeIndex: 2 },
289
+ morphSVG: { shape: '#lightning', type: 'rotational', shapeIndex: 2 },
289
290
  });
290
291
  ```
291
292
 
@@ -318,9 +319,9 @@ Animates an element along an SVG path. Use when moving an object along a path (e
318
319
  ```javascript
319
320
  gsap.registerPlugin(MotionPathPlugin);
320
321
 
321
- gsap.to(".dot", {
322
+ gsap.to('.dot', {
322
323
  duration: 2,
323
- motionPath: { path: "#path", align: "#path", alignOrigin: [0.5, 0.5] },
324
+ motionPath: { path: '#path', align: '#path', alignOrigin: [0.5, 0.5] },
324
325
  });
325
326
  ```
326
327
 
@@ -341,7 +342,7 @@ Visual editor for MotionPath (alignment, offset). Use during development to tune
341
342
  ```javascript
342
343
  gsap.registerPlugin(MotionPathPlugin, MotionPathHelperPlugin);
343
344
 
344
- const helper = MotionPathHelper.create(".dot", "#path", { end: 0.5 });
345
+ const helper = MotionPathHelper.create('.dot', '#path', { end: 0.5 });
345
346
  // adjust in UI, then use helper.path or helper.getProgress() in your animation
346
347
  ```
347
348
 
@@ -353,8 +354,8 @@ Custom easing curves (cubic-bezier or SVG path). Use when a built-in ease is not
353
354
 
354
355
  ```javascript
355
356
  gsap.registerPlugin(CustomEase);
356
- const ease = CustomEase.create("name", ".17,.67,.83,.67");
357
- gsap.to(".el", { x: 100, ease: ease, duration: 1 });
357
+ const ease = CustomEase.create('name', '.17,.67,.83,.67');
358
+ gsap.to('.el', { x: 100, ease: ease, duration: 1 });
358
359
  ```
359
360
 
360
361
  ### EasePack
@@ -378,7 +379,7 @@ Bounce-style easing with configurable strength.
378
379
  ```javascript
379
380
  gsap.registerPlugin(Physics2DPlugin);
380
381
 
381
- gsap.to(".ball", {
382
+ gsap.to('.ball', {
382
383
  duration: 2,
383
384
  physics2D: {
384
385
  velocity: 250,
@@ -395,7 +396,7 @@ Applies physics to property values. Use for physics-driven property animation.
395
396
  ```javascript
396
397
  gsap.registerPlugin(PhysicsPropsPlugin);
397
398
 
398
- gsap.to(".obj", {
399
+ gsap.to('.obj', {
399
400
  duration: 2,
400
401
  physicsProps: {
401
402
  x: { velocity: 100, end: 300 },
@@ -20,6 +20,7 @@ scripts-binding:
20
20
  ## Mandatory Pre-Flight Context Inspection
21
21
 
22
22
  Before writing GSAP animation logic in React, you MUST inspect:
23
+
23
24
  1. `package.json` → Verify `@gsap/react` and `gsap` dependencies
24
25
  2. `useGSAP()` Hook setup (Section 27) → Pass `{ scope: containerRef }` so selectors target DOM nodes within component scope
25
26
  3. Cleanup & Context-Safe Callbacks (Section 89) → Use `contextSafe` for event handlers attached after component mount to prevent memory leaks
@@ -44,7 +45,7 @@ npm install @gsap/react
44
45
  When **@gsap/react** is available, use the **useGSAP()** hook instead of `useEffect()` for GSAP setup. It handles cleanup automatically and provides a scope and **contextSafe** for callbacks.
45
46
 
46
47
  ```javascript
47
- import { useGSAP } from "@gsap/react";
48
+ import { useGSAP } from '@gsap/react';
48
49
 
49
50
  gsap.registerPlugin(useGSAP); // register before running useGSAP or any GSAP code
50
51
 
@@ -52,8 +53,8 @@ const containerRef = useRef(null);
52
53
 
53
54
  useGSAP(
54
55
  () => {
55
- gsap.to(".box", { x: 100 });
56
- gsap.from(".item", { opacity: 0, stagger: 0.1 });
56
+ gsap.to('.box', { x: 100 });
57
+ gsap.from('.item', { opacity: 0, stagger: 0.1 });
57
58
  },
58
59
  { scope: containerRef },
59
60
  );
@@ -91,8 +92,8 @@ It's okay to use **gsap.context()** inside a regular **useEffect()** when @gsap/
91
92
  ```javascript
92
93
  useEffect(() => {
93
94
  const ctx = gsap.context(() => {
94
- gsap.to(".box", { x: 100 });
95
- gsap.from(".item", { opacity: 0, stagger: 0.1 });
95
+ gsap.to('.box', { x: 100 });
96
+ gsap.from('.item', { opacity: 0, stagger: 0.1 });
96
97
  }, containerRef);
97
98
  return () => ctx.revert();
98
99
  }, []);
@@ -116,7 +117,7 @@ useGSAP(
116
117
  gsap.to(goodRef.current, { x: 100 });
117
118
 
118
119
  // ❌ DANGER! This animation is created in an event handler that executes AFTER useGSAP() executes. It's not added to the context so it won't get cleaned up (reverted). The event listener isn't removed in cleanup function below either, so it persists between component renders (bad).
119
- badRef.current.addEventListener("click", () => {
120
+ badRef.current.addEventListener('click', () => {
120
121
  gsap.to(badRef.current, { y: 100 });
121
122
  });
122
123
 
@@ -125,12 +126,12 @@ useGSAP(
125
126
  gsap.to(goodRef.current, { rotation: 180 });
126
127
  });
127
128
 
128
- goodRef.current.addEventListener("click", onClickGood);
129
+ goodRef.current.addEventListener('click', onClickGood);
129
130
 
130
131
  // 👍 we remove the event listener in the cleanup function below.
131
132
  return () => {
132
133
  // <-- cleanup
133
- goodRef.current.removeEventListener("click", onClickGood);
134
+ goodRef.current.removeEventListener('click', onClickGood);
134
135
  };
135
136
  },
136
137
  { scope: container },
@@ -20,6 +20,7 @@ scripts-binding:
20
20
  ## Mandatory Pre-Flight Context Inspection
21
21
 
22
22
  Before creating or editing ScrollTrigger animations, you MUST inspect:
23
+
23
24
  1. Plugin Registration Requirement (Section 22) → Explicitly execute `gsap.registerPlugin(ScrollTrigger)` once at root; ban unregistered plugin usage
24
25
  2. Child Tween ScrollTrigger Ban (Section 288) → Attach `scrollTrigger` to top-level timeline/tweens ONLY; ban attaching `scrollTrigger` to child timeline steps
25
26
  3. Horizontal Ease-None Rule (Section 226) → Enforce `ease: "none"` on horizontal scrolling tweens; ban custom easing on containerAnimation tweens
@@ -45,14 +46,14 @@ gsap.registerPlugin(ScrollTrigger);
45
46
  Tie a tween or timeline to scroll position:
46
47
 
47
48
  ```javascript
48
- gsap.to(".box", {
49
+ gsap.to('.box', {
49
50
  x: 500,
50
51
  duration: 1,
51
52
  scrollTrigger: {
52
- trigger: ".box",
53
- start: "top center", // when top of trigger hits center of viewport
54
- end: "bottom center", // when the bottom of the trigger hits the center of the viewport
55
- toggleActions: "play reverse play reverse", // onEnter play, onLeave reverse, onEnterBack play, onLeaveBack reverse
53
+ trigger: '.box',
54
+ start: 'top center', // when top of trigger hits center of viewport
55
+ end: 'bottom center', // when the bottom of the trigger hits the center of the viewport
56
+ toggleActions: 'play reverse play reverse', // onEnter play, onLeave reverse, onEnterBack play, onLeaveBack reverse
56
57
  },
57
58
  });
58
59
  ```
@@ -89,10 +90,10 @@ Main properties for the `scrollTrigger` config object (shorthand: `scrollTrigger
89
90
 
90
91
  ```javascript
91
92
  ScrollTrigger.create({
92
- trigger: "#id",
93
- start: "top top",
94
- end: "bottom 50%+=100px",
95
- onUpdate: (self) => console.log(self.progress.toFixed(3), self.direction),
93
+ trigger: '#id',
94
+ start: 'top top',
95
+ end: 'bottom 50%+=100px',
96
+ onUpdate: self => console.log(self.progress.toFixed(3), self.direction),
96
97
  });
97
98
  ```
98
99
 
@@ -114,26 +115,26 @@ ScrollTrigger.create({
114
115
  - **batchMax** (Number | Function) — Max elements per batch. When full, the callback fires and the next batch starts. Use a **function** that returns a number for responsive layouts; it runs on refresh (resize, tab focus, etc.).
115
116
 
116
117
  ```javascript
117
- ScrollTrigger.batch(".box", {
118
+ ScrollTrigger.batch('.box', {
118
119
  onEnter: (elements, triggers) => {
119
120
  gsap.to(elements, { opacity: 1, y: 0, stagger: 0.15 });
120
121
  },
121
122
  onLeave: (elements, triggers) => {
122
123
  gsap.to(elements, { opacity: 0, y: 100 });
123
124
  },
124
- start: "top 80%",
125
- end: "bottom 20%",
125
+ start: 'top 80%',
126
+ end: 'bottom 20%',
126
127
  });
127
128
  ```
128
129
 
129
130
  With **batchMax** and **interval** for finer control:
130
131
 
131
132
  ```javascript
132
- ScrollTrigger.batch(".card", {
133
+ ScrollTrigger.batch('.card', {
133
134
  interval: 0.1,
134
135
  batchMax: 4,
135
- onEnter: (batch) => gsap.to(batch, { opacity: 1, y: 0, stagger: 0.1, overwrite: true }),
136
- onLeaveBack: (batch) => gsap.set(batch, { opacity: 0, y: 50, overwrite: true }),
136
+ onEnter: batch => gsap.to(batch, { opacity: 1, y: 0, stagger: 0.1, overwrite: true }),
137
+ onLeaveBack: batch => gsap.set(batch, { opacity: 0, y: 50, overwrite: true }),
137
138
  });
138
139
  ```
139
140
 
@@ -176,12 +177,12 @@ See [ScrollTrigger.scrollerProxy()](https://gsap.com/docs/v3/Plugins/ScrollTrigg
176
177
  Scrub ties animation progress to scroll. Use for “scroll-driven” feel:
177
178
 
178
179
  ```javascript
179
- gsap.to(".box", {
180
+ gsap.to('.box', {
180
181
  x: 500,
181
182
  scrollTrigger: {
182
- trigger: ".box",
183
- start: "top center",
184
- end: "bottom center",
183
+ trigger: '.box',
184
+ start: 'top center',
185
+ end: 'bottom center',
185
186
  scrub: true, // or number (smoothness delay in seconds), so 0.5 means it'd take 0.5 seconds to "catch up" to the current scroll position.
186
187
  },
187
188
  });
@@ -227,14 +228,14 @@ Drive a timeline with scroll and optional scrub:
227
228
  ```javascript
228
229
  const tl = gsap.timeline({
229
230
  scrollTrigger: {
230
- trigger: ".container",
231
- start: "top top",
232
- end: "+=2000",
231
+ trigger: '.container',
232
+ start: 'top top',
233
+ end: '+=2000',
233
234
  scrub: 1,
234
235
  pin: true,
235
236
  },
236
237
  });
237
- tl.to(".a", { x: 100 }).to(".b", { y: 50 }).to(".c", { opacity: 0 });
238
+ tl.to('.a', { x: 100 }).to('.b', { y: 50 }).to('.c', { opacity: 0 });
238
239
  ```
239
240
 
240
241
  The timeline’s progress is tied to scroll through the trigger’s start/end range.
@@ -251,27 +252,27 @@ A common pattern: **pin** a section, then as the user scrolls **vertically**, co
251
252
  4. To trigger things based on the horizontal movement caused by that tween, set **containerAnimation** to that tween.
252
253
 
253
254
  ```javascript
254
- const scrollingEl = document.querySelector(".horizontal-el");
255
+ const scrollingEl = document.querySelector('.horizontal-el');
255
256
  // Panel = pinned viewport-sized section. .horizontal-wrap = inner content that moves left.
256
257
  const scrollTween = gsap.to(scrollingEl, {
257
258
  xPercent: () => Max.max(0, window.innerWidth - scrollingEl.offsetWidth),
258
- ease: "none", // ease: "none" is required
259
+ ease: 'none', // ease: "none" is required
259
260
  scrollTrigger: {
260
261
  trigger: scrollingEl,
261
262
  pin: scrollingEl.parentNode, // wrapper so that we're not animating the pinned element
262
- start: "top top",
263
- end: "+=1000",
263
+ start: 'top top',
264
+ end: '+=1000',
264
265
  },
265
266
  });
266
267
 
267
268
  // other tweens that trigger based on horizontal movement should reference the containerAnimation:
268
- gsap.to(".nested-el-1", {
269
+ gsap.to('.nested-el-1', {
269
270
  y: 100,
270
271
  scrollTrigger: {
271
272
  containerAnimation: scrollTween, // IMPORTANT
272
- trigger: ".nested-wrapper-1",
273
- start: "left center", // based on horizontal movement
274
- toggleActions: "play none none reset",
273
+ trigger: '.nested-wrapper-1',
274
+ start: 'left center', // based on horizontal movement
275
+ toggleActions: 'play none none reset',
275
276
  },
276
277
  });
277
278
  ```
@@ -284,9 +285,9 @@ gsap.to(".nested-el-1", {
284
285
  - When removing animated elements or changing pages (e.g. in SPAs), **kill** associated ScrollTrigger instances so they don’t run on stale elements:
285
286
 
286
287
  ```javascript
287
- ScrollTrigger.getAll().forEach((t) => t.kill());
288
+ ScrollTrigger.getAll().forEach(t => t.kill());
288
289
  // or kill by the id assigned to the ScrollTrigger in its config object like {id: "my-id", ...}
289
- ScrollTrigger.getById("my-id")?.kill();
290
+ ScrollTrigger.getById('my-id')?.kill();
290
291
  ```
291
292
 
292
293
  In React, use the `useGSAP()` hook (@gsap/react NPM package) to ensure proper cleanup automatically, or manually kill in a cleanup (e.g. in useEffect return) when the component unmounts.
@@ -20,6 +20,7 @@ scripts-binding:
20
20
  ## Mandatory Pre-Flight Context Inspection
21
21
 
22
22
  Before creating GSAP timelines, you MUST inspect:
23
+
23
24
  1. Position Parameter Syntax (Section 27) → Pass position as the 3rd argument (`"<"`, `">"`, `"+=0.5"`) instead of using hardcoded delays
24
25
  2. Timeline Defaults (Section 45) → Pass `{ defaults: { duration, ease } }` into `gsap.timeline()` constructor to avoid repetitive child declarations
25
26
  3. ScrollTrigger Placement (Section 101) → Place `scrollTrigger` ONLY on the top-level timeline, never on child tweens inside a timeline
@@ -34,7 +35,9 @@ Apply when building multi-step animations, coordinating several tweens in sequen
34
35
 
35
36
  ```javascript
36
37
  const tl = gsap.timeline();
37
- tl.to(".a", { x: 100, duration: 1 }).to(".b", { y: 50, duration: 0.5 }).to(".c", { opacity: 0, duration: 0.3 });
38
+ tl.to('.a', { x: 100, duration: 1 })
39
+ .to('.b', { y: 50, duration: 0.5 })
40
+ .to('.c', { opacity: 0, duration: 0.3 });
38
41
  ```
39
42
 
40
43
  By default, tweens are **appended** one after another. Use the **position parameter** to place tweens at specific times or relative to other tweens.
@@ -51,10 +54,10 @@ Third argument (or position property in vars) controls placement:
51
54
  Examples:
52
55
 
53
56
  ```javascript
54
- tl.to(".a", { x: 100 }, 0); // at 0
55
- tl.to(".b", { y: 50 }, "+=0.5"); // 0.5s after last end
56
- tl.to(".c", { opacity: 0 }, "<"); // same start as previous
57
- tl.to(".d", { scale: 2 }, "<0.2"); // 0.2s after previous start
57
+ tl.to('.a', { x: 100 }, 0); // at 0
58
+ tl.to('.b', { y: 50 }, '+=0.5'); // 0.5s after last end
59
+ tl.to('.c', { opacity: 0 }, '<'); // same start as previous
60
+ tl.to('.d', { scale: 2 }, '<0.2'); // 0.2s after previous start
58
61
  ```
59
62
 
60
63
  ## Timeline Defaults
@@ -62,8 +65,8 @@ tl.to(".d", { scale: 2 }, "<0.2"); // 0.2s after previous start
62
65
  Pass defaults into the timeline so all child tweens inherit:
63
66
 
64
67
  ```javascript
65
- const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
66
- tl.to(".a", { x: 100 }).to(".b", { y: 50 }); // both use 0.5s and power2.out
68
+ const tl = gsap.timeline({ defaults: { duration: 0.5, ease: 'power2.out' } });
69
+ tl.to('.a', { x: 100 }).to('.b', { y: 50 }); // both use 0.5s and power2.out
67
70
  ```
68
71
 
69
72
  ## Timeline Options (constructor)
@@ -78,12 +81,12 @@ tl.to(".a", { x: 100 }).to(".b", { y: 50 }); // both use 0.5s and power2.out
78
81
  Add and use labels for readable, maintainable sequencing:
79
82
 
80
83
  ```javascript
81
- tl.addLabel("intro", 0);
82
- tl.to(".a", { x: 100 }, "intro");
83
- tl.addLabel("outro", "+=0.5");
84
- tl.to(".b", { opacity: 0 }, "outro");
85
- tl.play("outro"); // start from "outro"
86
- tl.tweenFromTo("intro", "outro"); // pauses the timeline and returns a new Tween that animates the timeline's playhead from intro to outro with no ease.
84
+ tl.addLabel('intro', 0);
85
+ tl.to('.a', { x: 100 }, 'intro');
86
+ tl.addLabel('outro', '+=0.5');
87
+ tl.to('.b', { opacity: 0 }, 'outro');
88
+ tl.play('outro'); // start from "outro"
89
+ tl.tweenFromTo('intro', 'outro'); // pauses the timeline and returns a new Tween that animates the timeline's playhead from intro to outro with no ease.
87
90
  ```
88
91
 
89
92
  ## Nesting Timelines
@@ -93,9 +96,9 @@ Timelines can contain other timelines.
93
96
  ```javascript
94
97
  const master = gsap.timeline();
95
98
  const child = gsap.timeline();
96
- child.to(".a", { x: 100 }).to(".b", { y: 50 });
99
+ child.to('.a', { x: 100 }).to('.b', { y: 50 });
97
100
  master.add(child, 0);
98
- master.to(".c", { opacity: 0 }, "+=0.2");
101
+ master.to('.c', { opacity: 0 }, '+=0.2');
99
102
  ```
100
103
 
101
104
  ## Controlling Playback
@@ -20,6 +20,7 @@ scripts-binding:
20
20
  ## Mandatory Pre-Flight Context Inspection
21
21
 
22
22
  Before using `gsap.utils`, you MUST inspect:
23
+
23
24
  1. Pure Number vs Unit strings (Section 306) → `mapRange` and `normalize` work ONLY on numbers; use `getUnit` and `unitize` for string values with units
24
25
  2. Reusable Function Form (Section 22) → Omit the value argument (or pass `true` as 4th param for `random()`) to get a reusable function for high-frequency loops
25
26
  3. Component Scoping (Section 219) → Use `gsap.utils.selector(containerRef)` inside React components to restrict selector targets
@@ -90,7 +91,7 @@ Interpolates between two values at a given progress (0–1). Handles numbers, co
90
91
 
91
92
  ```javascript
92
93
  gsap.utils.interpolate(0, 100, 0.5); // 50
93
- gsap.utils.interpolate("#ff0000", "#0000ff", 0.5); // mid color
94
+ gsap.utils.interpolate('#ff0000', '#0000ff', 0.5); // mid color
94
95
  gsap.utils.interpolate({ x: 0, y: 0 }, { x: 100, y: 50 }, 0.5); // { x: 50, y: 25 }
95
96
 
96
97
  let lerp = gsap.utils.interpolate(0, 100);
@@ -114,7 +115,7 @@ randomFn(); // random value in range, snapped to 10
114
115
  randomFn(); // another random value
115
116
 
116
117
  // array: pick one value at random
117
- gsap.utils.random(["red", "blue", "green"]); // "red", "blue", or "green"
118
+ gsap.utils.random(['red', 'blue', 'green']); // "red", "blue", or "green"
118
119
  let randomFromArray = gsap.utils.random([0, 100, 200], true);
119
120
  randomFromArray(); // 0, 100, or 200
120
121
  ```
@@ -122,8 +123,8 @@ randomFromArray(); // 0, 100, or 200
122
123
  **String form in tween vars:** use `"random(-100, 100)"`, `"random(-100, 100, 5)"`, or `"random([0, 100, 200])"`; GSAP evaluates it per target.
123
124
 
124
125
  ```javascript
125
- gsap.to(".box", { x: "random(-100, 100, 5)", duration: 1 });
126
- gsap.to(".item", { backgroundColor: "random([red, blue, green])" });
126
+ gsap.to('.box', { x: 'random(-100, 100, 5)', duration: 1 });
127
+ gsap.to('.item', { backgroundColor: 'random([red, blue, green])' });
127
128
  ```
128
129
 
129
130
  ### snap(snapTo, value?)
@@ -142,7 +143,7 @@ snapFn(23); // 20
142
143
  Use in tweens for grid or step-based animation:
143
144
 
144
145
  ```javascript
145
- gsap.to(".x", { x: 200, snap: { x: 20 } });
146
+ gsap.to('.x', { x: 200, snap: { x: 20 } });
146
147
  ```
147
148
 
148
149
  ### shuffle(array)
@@ -173,11 +174,11 @@ gsap.utils.shuffle([1, 2, 3, 4]); // e.g. [3, 1, 4, 2]
173
174
 
174
175
  ```javascript
175
176
  // Scale: middle elements 0.5, outer edges 3 (amount 2.5 distributed from center)
176
- gsap.to(".class", {
177
+ gsap.to('.class', {
177
178
  scale: gsap.utils.distribute({
178
179
  base: 0.5,
179
180
  amount: 2.5,
180
- from: "center",
181
+ from: 'center',
181
182
  }),
182
183
  });
183
184
  ```
@@ -188,10 +189,10 @@ gsap.to(".class", {
188
189
  const distributor = gsap.utils.distribute({
189
190
  base: 50,
190
191
  amount: 100,
191
- from: "center",
192
- ease: "power1.inOut",
192
+ from: 'center',
193
+ ease: 'power1.inOut',
193
194
  });
194
- const targets = gsap.utils.toArray(".box");
195
+ const targets = gsap.utils.toArray('.box');
195
196
  const valueForIndex2 = distributor(2, targets[2], targets);
196
197
  ```
197
198
 
@@ -204,8 +205,8 @@ See [distribute()](https://gsap.com/docs/v3/GSAP/UtilityMethods/distribute/) for
204
205
  Returns the unit string of a value (e.g. `"px"`, `"%"`, `"deg"`). Use when normalizing or converting values.
205
206
 
206
207
  ```javascript
207
- gsap.utils.getUnit("100px"); // "px"
208
- gsap.utils.getUnit("50%"); // "%"
208
+ gsap.utils.getUnit('100px'); // "px"
209
+ gsap.utils.getUnit('50%'); // "%"
209
210
  gsap.utils.getUnit(42); // "" (unitless)
210
211
  ```
211
212
 
@@ -214,8 +215,8 @@ gsap.utils.getUnit(42); // "" (unitless)
214
215
  Appends a unit to a number, or returns the value as-is if it already has a unit. Use when building CSS values or tween end values.
215
216
 
216
217
  ```javascript
217
- gsap.utils.unitize(100, "px"); // "100px"
218
- gsap.utils.unitize("2rem", "px"); // "2rem" (unchanged)
218
+ gsap.utils.unitize(100, 'px'); // "100px"
219
+ gsap.utils.unitize('2rem', 'px'); // "2rem" (unchanged)
219
220
  ```
220
221
 
221
222
  ### splitColor(color, returnHSL?)
@@ -223,10 +224,10 @@ gsap.utils.unitize("2rem", "px"); // "2rem" (unchanged)
223
224
  Converts a color string into an array: **[red, green, blue]** (0–255), or **[red, green, blue, alpha]** (4 elements for RGBA when alpha is present or required). Pass **true** as the second argument (**returnHSL**) to get **[hue, saturation, lightness]** or **[hue, saturation, lightness, alpha]** (HSL/HSLA) instead. Works with `"rgb()"`, `"rgba()"`, `"hsl()"`, `"hsla()"`, hex, and named colors (e.g. `"red"`). Use when animating color components or building gradients. See [splitColor()](https://gsap.com/docs/v3/GSAP/UtilityMethods/splitColor/).
224
225
 
225
226
  ```javascript
226
- gsap.utils.splitColor("red"); // [255, 0, 0]
227
- gsap.utils.splitColor("#6fb936"); // [111, 185, 54]
228
- gsap.utils.splitColor("rgba(204, 153, 51, 0.5)"); // [204, 153, 51, 0.5] (4 elements)
229
- gsap.utils.splitColor("#6fb936", true); // [94, 55, 47] (HSL: hue, saturation, lightness)
227
+ gsap.utils.splitColor('red'); // [255, 0, 0]
228
+ gsap.utils.splitColor('#6fb936'); // [111, 185, 54]
229
+ gsap.utils.splitColor('rgba(204, 153, 51, 0.5)'); // [204, 153, 51, 0.5] (4 elements)
230
+ gsap.utils.splitColor('#6fb936', true); // [94, 55, 47] (HSL: hue, saturation, lightness)
230
231
  ```
231
232
 
232
233
  ## Arrays and Collections
@@ -237,8 +238,8 @@ Returns a scoped selector function that finds elements only within the given ele
237
238
 
238
239
  ```javascript
239
240
  const q = gsap.utils.selector(containerRef);
240
- q(".box"); // array of .box elements inside container
241
- gsap.to(q(".circle"), { x: 100 });
241
+ q('.box'); // array of .box elements inside container
242
+ gsap.to(q('.circle'), { x: 100 });
242
243
  ```
243
244
 
244
245
  ### toArray(value, scope?)
@@ -246,8 +247,8 @@ gsap.to(q(".circle"), { x: 100 });
246
247
  Converts a value to an array: selector string (scoped to element), NodeList, HTMLCollection, single element, or array. Use when passing mixed inputs to GSAP (e.g. targets) and a true array is needed.
247
248
 
248
249
  ```javascript
249
- gsap.utils.toArray(".item"); // array of elements
250
- gsap.utils.toArray(".item", container); // scoped to container
250
+ gsap.utils.toArray('.item'); // array of elements
251
+ gsap.utils.toArray('.item', container); // scoped to container
251
252
  gsap.utils.toArray(nodeList); // [ ... ] from NodeList
252
253
  ```
253
254
 
@@ -257,8 +258,8 @@ Composes functions: **pipe(f1, f2, f3)(value)** returns f3(f2(f1(value))). Use w
257
258
 
258
259
  ```javascript
259
260
  const fn = gsap.utils.pipe(
260
- (v) => gsap.utils.normalize(0, 100, v),
261
- (v) => gsap.utils.snap(0.1, v),
261
+ v => gsap.utils.normalize(0, 100, v),
262
+ v => gsap.utils.snap(0.1, v),
262
263
  );
263
264
  fn(50); // normalized then snapped
264
265
  ```