skillfullstack 0.0.0-stage → 1.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 (775) hide show
  1. package/.skillsRegistry/catalog.json +231 -0
  2. package/AGENTS.md +89 -0
  3. package/README.md +210 -2
  4. package/bin/index.js +508 -0
  5. package/package.json +57 -4
  6. package/skills/backend/apiEngineering/SKILL.md +102 -0
  7. package/skills/backend/apiEngineering/evals/evalApiEngineering.py +81 -0
  8. package/skills/backend/apiEngineering/evals/fixtures/invalid/sampleInvalidOpenApi.json +40 -0
  9. package/skills/backend/apiEngineering/evals/fixtures/valid/sampleValidOpenApi.json +47 -0
  10. package/skills/backend/apiEngineering/policies/compatibility.md +42 -0
  11. package/skills/backend/apiEngineering/policies/mandatory.md +48 -0
  12. package/skills/backend/apiEngineering/policies/performance.md +39 -0
  13. package/skills/backend/apiEngineering/policies/security.md +36 -0
  14. package/skills/backend/apiEngineering/references/apiObservability.md +39 -0
  15. package/skills/backend/apiEngineering/references/apiReference.md +3 -0
  16. package/skills/backend/apiEngineering/references/apiSecurityOwasp.md +47 -0
  17. package/skills/backend/apiEngineering/references/contractCompatibility.md +26 -0
  18. package/skills/backend/apiEngineering/references/databaseTransactions.md +40 -0
  19. package/skills/backend/apiEngineering/references/distributedReliability.md +26 -0
  20. package/skills/backend/apiEngineering/references/multiTenancy.md +27 -0
  21. package/skills/backend/apiEngineering/references/openApi32Standards.md +58 -0
  22. package/skills/backend/apiEngineering/references/paginationVersioning.md +57 -0
  23. package/skills/backend/apiEngineering/references/responseStandards.md +94 -0
  24. package/skills/backend/apiEngineering/scripts/auditApiContract.py +123 -0
  25. package/skills/backend/apiEngineering/scripts/checkBreakingChanges.py +77 -0
  26. package/skills/backend/apiEngineering/scripts/generateResponseEnvelope.py +88 -0
  27. package/skills/backend/apiEngineering/templates/apiChecklist.md +27 -0
  28. package/skills/backend/apiEngineering/templates/openapi.yaml +125 -0
  29. package/skills/backend/apiEngineering/templates/problemDetails.json +44 -0
  30. package/skills/backend/databaseArchitecture/SKILL.md +118 -0
  31. package/skills/backend/databaseArchitecture/evals/evalDatabaseArchitecture.py +85 -0
  32. package/skills/backend/databaseArchitecture/evals/fixtures/dangerousMigration.sql +4 -0
  33. package/skills/backend/databaseArchitecture/evals/fixtures/invalidSchema.sql +23 -0
  34. package/skills/backend/databaseArchitecture/evals/fixtures/safeMigration.sql +3 -0
  35. package/skills/backend/databaseArchitecture/evals/fixtures/validSchema.sql +37 -0
  36. package/skills/backend/databaseArchitecture/policies/integrity.md +25 -0
  37. package/skills/backend/databaseArchitecture/policies/mandatory.md +32 -0
  38. package/skills/backend/databaseArchitecture/policies/migration.md +22 -0
  39. package/skills/backend/databaseArchitecture/policies/normalization.md +25 -0
  40. package/skills/backend/databaseArchitecture/policies/performance.md +26 -0
  41. package/skills/backend/databaseArchitecture/policies/recovery.md +23 -0
  42. package/skills/backend/databaseArchitecture/policies/security.md +26 -0
  43. package/skills/backend/databaseArchitecture/policies/tableCreationChecklist.md +70 -0
  44. package/skills/backend/databaseArchitecture/references/analyticsWarehousing.md +32 -0
  45. package/skills/backend/databaseArchitecture/references/apiReference.md +3 -0
  46. package/skills/backend/databaseArchitecture/references/backupDisasterRecovery.md +27 -0
  47. package/skills/backend/databaseArchitecture/references/dataModelingLifecycle.md +30 -0
  48. package/skills/backend/databaseArchitecture/references/databaseTaxonomy.md +32 -0
  49. package/skills/backend/databaseArchitecture/references/indexingOptimization.md +32 -0
  50. package/skills/backend/databaseArchitecture/references/normalizationTheory.md +61 -0
  51. package/skills/backend/databaseArchitecture/references/scalabilitySharding.md +37 -0
  52. package/skills/backend/databaseArchitecture/references/transactionConcurrency.md +39 -0
  53. package/skills/backend/databaseArchitecture/scripts/analyzeMigration.py +99 -0
  54. package/skills/backend/databaseArchitecture/scripts/auditDatabaseSchema.py +177 -0
  55. package/skills/backend/databaseArchitecture/scripts/inspectDatabaseIndexes.py +149 -0
  56. package/skills/backend/databaseArchitecture/templates/adrTemplate.md +32 -0
  57. package/skills/backend/databaseArchitecture/templates/databaseChecklist.md +29 -0
  58. package/skills/backend/databaseArchitecture/templates/migrationPlan.md +40 -0
  59. package/skills/backend/durableBackgroundJobs/SKILL.md +112 -0
  60. package/skills/backend/durableBackgroundJobs/evals/durableJobVerification.json +14 -0
  61. package/skills/backend/durableBackgroundJobs/references/apiReference.md +3 -0
  62. package/skills/backend/durableBackgroundJobs/references/durableStepPatterns.md +6 -0
  63. package/skills/backend/durableBackgroundJobs/references/idempotencyKeys.md +5 -0
  64. package/skills/backend/durableBackgroundJobs/scripts/testWorkflowDispatch.py +24 -0
  65. package/skills/backend/golangStandard/SKILL.md +155 -0
  66. package/skills/backend/golangStandard/evals/goVerification.json +14 -0
  67. package/skills/backend/golangStandard/references/apiReference.md +3 -0
  68. package/skills/backend/golangStandard/references/layoutGuide.md +26 -0
  69. package/skills/backend/golangStandard/references/slogPatterns.md +26 -0
  70. package/skills/backend/golangStandard/scripts/scaffoldGoModule.py +105 -0
  71. package/skills/backend/pythonStandard/SKILL.md +138 -0
  72. package/skills/backend/pythonStandard/evals/pythonVerification.json +14 -0
  73. package/skills/backend/pythonStandard/references/apiReference.md +3 -0
  74. package/skills/backend/pythonStandard/references/pydanticPatterns.md +16 -0
  75. package/skills/backend/pythonStandard/references/pyprojectSpecs.md +37 -0
  76. package/skills/backend/pythonStandard/scripts/scaffoldUvProject.py +79 -0
  77. package/skills/backend/upstash/SKILL.md +98 -0
  78. package/skills/backend/upstash/evals/upstashVerification.json +14 -0
  79. package/skills/backend/upstash/references/apiReference.md +3 -0
  80. package/skills/backend/upstash/references/qstashFlowControl.md +34 -0
  81. package/skills/backend/upstash/references/ratelimitPatterns.md +53 -0
  82. package/skills/backend/upstash/references/workflowPatterns.md +35 -0
  83. package/skills/backend/upstash/scripts/testRedisConnection.py +36 -0
  84. package/skills/cicdDevops/cicdPipeline/SKILL.md +148 -0
  85. package/skills/cicdDevops/cicdPipeline/evals/evalCicd.py +37 -0
  86. package/skills/cicdDevops/cicdPipeline/references/apiReference.md +3 -0
  87. package/skills/cicdDevops/cicdPipeline/references/cicdDeploymentPatterns.md +27 -0
  88. package/skills/cicdDevops/cicdPipeline/scripts/auditDockerfileSecurity.py +56 -0
  89. package/skills/dataAi/mcpServerDevelopment/SKILL.md +123 -0
  90. package/skills/dataAi/mcpServerDevelopment/evals/mcpVerification.json +14 -0
  91. package/skills/dataAi/mcpServerDevelopment/references/apiReference.md +3 -0
  92. package/skills/dataAi/mcpServerDevelopment/references/mcpClientConfigs.md +38 -0
  93. package/skills/dataAi/mcpServerDevelopment/references/toolSchemaDesign.md +6 -0
  94. package/skills/dataAi/mcpServerDevelopment/scripts/runFastMcpBoilerplate.py +36 -0
  95. package/skills/dataAi/ragPipelineProduction/SKILL.md +113 -0
  96. package/skills/dataAi/ragPipelineProduction/evals/ragVerification.json +14 -0
  97. package/skills/dataAi/ragPipelineProduction/references/apiReference.md +3 -0
  98. package/skills/dataAi/ragPipelineProduction/references/chunkingStrategies.md +10 -0
  99. package/skills/dataAi/ragPipelineProduction/references/rrfAlgorithm.md +13 -0
  100. package/skills/dataAi/ragPipelineProduction/scripts/runHybridRrfSearch.py +33 -0
  101. package/skills/devopsCloud/cloudflare/SKILL.md +282 -0
  102. package/skills/devopsCloud/cloudflare/assets/README.md +48 -0
  103. package/skills/devopsCloud/cloudflare/assets/ai/agents-sdk.md +118 -0
  104. package/skills/devopsCloud/cloudflare/assets/ai/ai-gateway.md +105 -0
  105. package/skills/devopsCloud/cloudflare/assets/ai/ai-search.md +129 -0
  106. package/skills/devopsCloud/cloudflare/assets/ai/workers-ai.md +127 -0
  107. package/skills/devopsCloud/cloudflare/assets/cli/c3.md +292 -0
  108. package/skills/devopsCloud/cloudflare/assets/cli/cf-cli.md +90 -0
  109. package/skills/devopsCloud/cloudflare/assets/cli/wrangler.md +43 -0
  110. package/skills/devopsCloud/cloudflare/assets/compute/cron-triggers.md +486 -0
  111. package/skills/devopsCloud/cloudflare/assets/compute/service-bindings.md +251 -0
  112. package/skills/devopsCloud/cloudflare/assets/compute/smart-placement.md +435 -0
  113. package/skills/devopsCloud/cloudflare/assets/compute/static-assets.md +220 -0
  114. package/skills/devopsCloud/cloudflare/assets/compute/workers.md +129 -0
  115. package/skills/devopsCloud/cloudflare/assets/database-storage/d1.md +105 -0
  116. package/skills/devopsCloud/cloudflare/assets/database-storage/durable-objects.md +122 -0
  117. package/skills/devopsCloud/cloudflare/assets/database-storage/hyperdrive.md +210 -0
  118. package/skills/devopsCloud/cloudflare/assets/database-storage/kv.md +198 -0
  119. package/skills/devopsCloud/cloudflare/assets/database-storage/queues.md +105 -0
  120. package/skills/devopsCloud/cloudflare/assets/database-storage/r2.md +105 -0
  121. package/skills/devopsCloud/cloudflare/assets/database-storage/vectorize.md +97 -0
  122. package/skills/devopsCloud/cloudflare/assets/database-storage/workflows.md +141 -0
  123. package/skills/devopsCloud/cloudflare/assets/llms.txt +143 -0
  124. package/skills/devopsCloud/cloudflare/assets/networking-security/cache-cdn.md +109 -0
  125. package/skills/devopsCloud/cloudflare/assets/networking-security/dns.md +71 -0
  126. package/skills/devopsCloud/cloudflare/assets/networking-security/rate-limiting.md +130 -0
  127. package/skills/devopsCloud/cloudflare/assets/networking-security/tunnels.md +57 -0
  128. package/skills/devopsCloud/cloudflare/assets/networking-security/waf.md +143 -0
  129. package/skills/devopsCloud/cloudflare/assets/troubleshooting/1xxx-errors.md +209 -0
  130. package/skills/devopsCloud/cloudflare/assets/troubleshooting/5xx-errors.md +111 -0
  131. package/skills/devopsCloud/cloudflare/assets/troubleshooting/http-status-codes.md +38 -0
  132. package/skills/devopsCloud/cloudflare/evals/evals.json +75 -0
  133. package/skills/devopsCloud/cloudflare/references/ai-gateway/README.md +27 -0
  134. package/skills/devopsCloud/cloudflare/references/ai-gateway/configuration.md +18 -0
  135. package/skills/devopsCloud/cloudflare/references/ai-gateway/dynamic-routing.md +15 -0
  136. package/skills/devopsCloud/cloudflare/references/ai-gateway/features.md +22 -0
  137. package/skills/devopsCloud/cloudflare/references/ai-gateway/sdk-integration.md +19 -0
  138. package/skills/devopsCloud/cloudflare/references/ai-gateway/troubleshooting.md +16 -0
  139. package/skills/devopsCloud/cloudflare/references/ai-search/README.md +25 -0
  140. package/skills/devopsCloud/cloudflare/references/ai-search/api.md +13 -0
  141. package/skills/devopsCloud/cloudflare/references/ai-search/configuration.md +16 -0
  142. package/skills/devopsCloud/cloudflare/references/ai-search/gotchas.md +13 -0
  143. package/skills/devopsCloud/cloudflare/references/ai-search/patterns.md +15 -0
  144. package/skills/devopsCloud/cloudflare/references/bindings/README.md +16 -0
  145. package/skills/devopsCloud/cloudflare/references/bindings/api.md +19 -0
  146. package/skills/devopsCloud/cloudflare/references/bindings/configuration.md +20 -0
  147. package/skills/devopsCloud/cloudflare/references/bindings/gotchas.md +18 -0
  148. package/skills/devopsCloud/cloudflare/references/bindings/patterns.md +20 -0
  149. package/skills/devopsCloud/cloudflare/references/browser-rendering/README.md +18 -0
  150. package/skills/devopsCloud/cloudflare/references/browser-rendering/api.md +12 -0
  151. package/skills/devopsCloud/cloudflare/references/browser-rendering/configuration.md +12 -0
  152. package/skills/devopsCloud/cloudflare/references/browser-rendering/gotchas.md +15 -0
  153. package/skills/devopsCloud/cloudflare/references/browser-rendering/patterns.md +12 -0
  154. package/skills/devopsCloud/cloudflare/references/cliComparison.md +93 -0
  155. package/skills/devopsCloud/cloudflare/references/containers/README.md +23 -0
  156. package/skills/devopsCloud/cloudflare/references/containers/api.md +13 -0
  157. package/skills/devopsCloud/cloudflare/references/containers/configuration.md +15 -0
  158. package/skills/devopsCloud/cloudflare/references/containers/gotchas.md +16 -0
  159. package/skills/devopsCloud/cloudflare/references/containers/patterns.md +18 -0
  160. package/skills/devopsCloud/cloudflare/references/cron-triggers/README.md +20 -0
  161. package/skills/devopsCloud/cloudflare/references/cron-triggers/api.md +16 -0
  162. package/skills/devopsCloud/cloudflare/references/cron-triggers/configuration.md +16 -0
  163. package/skills/devopsCloud/cloudflare/references/cron-triggers/gotchas.md +17 -0
  164. package/skills/devopsCloud/cloudflare/references/cron-triggers/patterns.md +18 -0
  165. package/skills/devopsCloud/cloudflare/references/d1/README.md +15 -0
  166. package/skills/devopsCloud/cloudflare/references/d1/api.md +18 -0
  167. package/skills/devopsCloud/cloudflare/references/d1/configuration.md +18 -0
  168. package/skills/devopsCloud/cloudflare/references/d1/gotchas.md +18 -0
  169. package/skills/devopsCloud/cloudflare/references/d1/patterns.md +21 -0
  170. package/skills/devopsCloud/cloudflare/references/frameworkCompatibility.md +110 -0
  171. package/skills/devopsCloud/cloudflare/references/hyperdrive/README.md +28 -0
  172. package/skills/devopsCloud/cloudflare/references/hyperdrive/api.md +26 -0
  173. package/skills/devopsCloud/cloudflare/references/hyperdrive/configuration.md +34 -0
  174. package/skills/devopsCloud/cloudflare/references/hyperdrive/gotchas.md +20 -0
  175. package/skills/devopsCloud/cloudflare/references/hyperdrive/patterns.md +15 -0
  176. package/skills/devopsCloud/cloudflare/references/images/README.md +12 -0
  177. package/skills/devopsCloud/cloudflare/references/images/api.md +13 -0
  178. package/skills/devopsCloud/cloudflare/references/images/configuration.md +17 -0
  179. package/skills/devopsCloud/cloudflare/references/images/gotchas.md +16 -0
  180. package/skills/devopsCloud/cloudflare/references/images/patterns.md +16 -0
  181. package/skills/devopsCloud/cloudflare/references/kv/README.md +15 -0
  182. package/skills/devopsCloud/cloudflare/references/kv/api.md +18 -0
  183. package/skills/devopsCloud/cloudflare/references/kv/configuration.md +16 -0
  184. package/skills/devopsCloud/cloudflare/references/kv/gotchas.md +17 -0
  185. package/skills/devopsCloud/cloudflare/references/kv/patterns.md +21 -0
  186. package/skills/devopsCloud/cloudflare/references/miniflare/README.md +22 -0
  187. package/skills/devopsCloud/cloudflare/references/miniflare/api.md +16 -0
  188. package/skills/devopsCloud/cloudflare/references/miniflare/configuration.md +16 -0
  189. package/skills/devopsCloud/cloudflare/references/miniflare/gotchas.md +15 -0
  190. package/skills/devopsCloud/cloudflare/references/miniflare/patterns.md +19 -0
  191. package/skills/devopsCloud/cloudflare/references/observability/README.md +27 -0
  192. package/skills/devopsCloud/cloudflare/references/observability/api.md +20 -0
  193. package/skills/devopsCloud/cloudflare/references/observability/configuration.md +23 -0
  194. package/skills/devopsCloud/cloudflare/references/observability/gotchas.md +25 -0
  195. package/skills/devopsCloud/cloudflare/references/observability/patterns.md +14 -0
  196. package/skills/devopsCloud/cloudflare/references/pages/README.md +20 -0
  197. package/skills/devopsCloud/cloudflare/references/pages/api.md +13 -0
  198. package/skills/devopsCloud/cloudflare/references/pages/configuration.md +16 -0
  199. package/skills/devopsCloud/cloudflare/references/pages/gotchas.md +19 -0
  200. package/skills/devopsCloud/cloudflare/references/pages/patterns.md +15 -0
  201. package/skills/devopsCloud/cloudflare/references/pages-functions/README.md +20 -0
  202. package/skills/devopsCloud/cloudflare/references/pages-functions/api.md +13 -0
  203. package/skills/devopsCloud/cloudflare/references/pages-functions/configuration.md +14 -0
  204. package/skills/devopsCloud/cloudflare/references/pages-functions/gotchas.md +17 -0
  205. package/skills/devopsCloud/cloudflare/references/pages-functions/patterns.md +16 -0
  206. package/skills/devopsCloud/cloudflare/references/productSelectionMatrix.md +54 -0
  207. package/skills/devopsCloud/cloudflare/references/queues/README.md +24 -0
  208. package/skills/devopsCloud/cloudflare/references/queues/api.md +16 -0
  209. package/skills/devopsCloud/cloudflare/references/queues/configuration.md +20 -0
  210. package/skills/devopsCloud/cloudflare/references/queues/gotchas.md +18 -0
  211. package/skills/devopsCloud/cloudflare/references/queues/patterns.md +21 -0
  212. package/skills/devopsCloud/cloudflare/references/r2/README.md +26 -0
  213. package/skills/devopsCloud/cloudflare/references/r2/api.md +16 -0
  214. package/skills/devopsCloud/cloudflare/references/r2/configuration.md +19 -0
  215. package/skills/devopsCloud/cloudflare/references/r2/gotchas.md +17 -0
  216. package/skills/devopsCloud/cloudflare/references/r2/patterns.md +18 -0
  217. package/skills/devopsCloud/cloudflare/references/secrets-store/README.md +22 -0
  218. package/skills/devopsCloud/cloudflare/references/secrets-store/api.md +21 -0
  219. package/skills/devopsCloud/cloudflare/references/secrets-store/configuration.md +25 -0
  220. package/skills/devopsCloud/cloudflare/references/secrets-store/gotchas.md +19 -0
  221. package/skills/devopsCloud/cloudflare/references/secrets-store/patterns.md +27 -0
  222. package/skills/devopsCloud/cloudflare/references/skill-feedback.md +41 -0
  223. package/skills/devopsCloud/cloudflare/references/static-assets/README.md +21 -0
  224. package/skills/devopsCloud/cloudflare/references/static-assets/api.md +16 -0
  225. package/skills/devopsCloud/cloudflare/references/static-assets/configuration.md +16 -0
  226. package/skills/devopsCloud/cloudflare/references/static-assets/gotchas.md +18 -0
  227. package/skills/devopsCloud/cloudflare/references/static-assets/patterns.md +17 -0
  228. package/skills/devopsCloud/cloudflare/references/stream/README.md +22 -0
  229. package/skills/devopsCloud/cloudflare/references/stream/api-live.md +18 -0
  230. package/skills/devopsCloud/cloudflare/references/stream/api.md +21 -0
  231. package/skills/devopsCloud/cloudflare/references/stream/configuration.md +18 -0
  232. package/skills/devopsCloud/cloudflare/references/stream/gotchas.md +18 -0
  233. package/skills/devopsCloud/cloudflare/references/stream/patterns.md +22 -0
  234. package/skills/devopsCloud/cloudflare/references/tail-workers/README.md +21 -0
  235. package/skills/devopsCloud/cloudflare/references/tail-workers/api.md +13 -0
  236. package/skills/devopsCloud/cloudflare/references/tail-workers/configuration.md +15 -0
  237. package/skills/devopsCloud/cloudflare/references/tail-workers/gotchas.md +16 -0
  238. package/skills/devopsCloud/cloudflare/references/tail-workers/patterns.md +15 -0
  239. package/skills/devopsCloud/cloudflare/references/tunnel/README.md +20 -0
  240. package/skills/devopsCloud/cloudflare/references/tunnel/api.md +14 -0
  241. package/skills/devopsCloud/cloudflare/references/tunnel/configuration.md +14 -0
  242. package/skills/devopsCloud/cloudflare/references/tunnel/gotchas.md +15 -0
  243. package/skills/devopsCloud/cloudflare/references/tunnel/networking.md +14 -0
  244. package/skills/devopsCloud/cloudflare/references/tunnel/patterns.md +15 -0
  245. package/skills/devopsCloud/cloudflare/references/vectorize/README.md +22 -0
  246. package/skills/devopsCloud/cloudflare/references/vectorize/api.md +18 -0
  247. package/skills/devopsCloud/cloudflare/references/vectorize/configuration.md +19 -0
  248. package/skills/devopsCloud/cloudflare/references/vectorize/gotchas.md +15 -0
  249. package/skills/devopsCloud/cloudflare/references/vectorize/patterns.md +24 -0
  250. package/skills/devopsCloud/cloudflare/references/waf/README.md +21 -0
  251. package/skills/devopsCloud/cloudflare/references/waf/api.md +17 -0
  252. package/skills/devopsCloud/cloudflare/references/waf/configuration.md +18 -0
  253. package/skills/devopsCloud/cloudflare/references/waf/gotchas.md +19 -0
  254. package/skills/devopsCloud/cloudflare/references/waf/patterns.md +17 -0
  255. package/skills/devopsCloud/cloudflare/references/workers-ai/README.md +24 -0
  256. package/skills/devopsCloud/cloudflare/references/workers-ai/api.md +13 -0
  257. package/skills/devopsCloud/cloudflare/references/workers-ai/configuration.md +16 -0
  258. package/skills/devopsCloud/cloudflare/references/workers-ai/gotchas.md +15 -0
  259. package/skills/devopsCloud/cloudflare/references/workers-ai/patterns.md +14 -0
  260. package/skills/devopsCloud/cloudflare/references/workflows/README.md +23 -0
  261. package/skills/devopsCloud/cloudflare/references/workflows/api.md +17 -0
  262. package/skills/devopsCloud/cloudflare/references/workflows/configuration.md +18 -0
  263. package/skills/devopsCloud/cloudflare/references/workflows/gotchas.md +19 -0
  264. package/skills/devopsCloud/cloudflare/references/workflows/patterns.md +30 -0
  265. package/skills/devopsCloud/cloudflare/scripts/auditCloudflareProduction.py +95 -0
  266. package/skills/foundation/promptEvalTesting/SKILL.md +114 -0
  267. package/skills/foundation/promptEvalTesting/evals/promptEvalVerification.json +14 -0
  268. package/skills/foundation/promptEvalTesting/references/apiReference.md +3 -0
  269. package/skills/foundation/promptEvalTesting/references/evalMetricsCatalog.md +7 -0
  270. package/skills/foundation/promptEvalTesting/references/promptfooConfigSpecs.md +16 -0
  271. package/skills/foundation/promptEvalTesting/scripts/runPromptEvalSuite.py +29 -0
  272. package/skills/frontend/astro/SKILL.md +327 -0
  273. package/skills/frontend/astro/assets/README.md +71 -0
  274. package/skills/frontend/astro/assets/add-content-to-your-site/content-collections.md +1061 -0
  275. package/skills/frontend/astro/assets/add-content-to-your-site/data-fetching.md +109 -0
  276. package/skills/frontend/astro/assets/add-content-to-your-site/images.md +719 -0
  277. package/skills/frontend/astro/assets/add-content-to-your-site/markdown.md +725 -0
  278. package/skills/frontend/astro/assets/build-your-ui/components.md +402 -0
  279. package/skills/frontend/astro/assets/build-your-ui/fonts.md +437 -0
  280. package/skills/frontend/astro/assets/build-your-ui/front-end-frameworks.md +245 -0
  281. package/skills/frontend/astro/assets/build-your-ui/layouts.md +267 -0
  282. package/skills/frontend/astro/assets/build-your-ui/scripts-and-event-handling.md +229 -0
  283. package/skills/frontend/astro/assets/build-your-ui/styles-and-css.md +782 -0
  284. package/skills/frontend/astro/assets/build-your-ui/syntax-highlighting.md +269 -0
  285. package/skills/frontend/astro/assets/configuration/build-with-ai.md +389 -0
  286. package/skills/frontend/astro/assets/configuration/configuration-overview.md +122 -0
  287. package/skills/frontend/astro/assets/configuration/dev-toolbar.md +86 -0
  288. package/skills/frontend/astro/assets/configuration/editor-setup.md +166 -0
  289. package/skills/frontend/astro/assets/configuration/environment-variables.md +352 -0
  290. package/skills/frontend/astro/assets/configuration/typescript.md +379 -0
  291. package/skills/frontend/astro/assets/configuration/working-with-integrations.md +606 -0
  292. package/skills/frontend/astro/assets/reference/adapter-reference.md +1242 -0
  293. package/skills/frontend/astro/assets/reference/cli-reference.md +575 -0
  294. package/skills/frontend/astro/assets/reference/configuration-reference.md +3144 -0
  295. package/skills/frontend/astro/assets/reference/content-loader-reference.md +1682 -0
  296. package/skills/frontend/astro/assets/reference/directives-reference.md +324 -0
  297. package/skills/frontend/astro/assets/reference/image-service-reference.md +346 -0
  298. package/skills/frontend/astro/assets/reference/integrations-reference.md +2813 -0
  299. package/skills/frontend/astro/assets/reference/modules/astro-actions.md +604 -0
  300. package/skills/frontend/astro/assets/reference/modules/astro-app.md +460 -0
  301. package/skills/frontend/astro/assets/reference/modules/astro-assets.md +1657 -0
  302. package/skills/frontend/astro/assets/reference/modules/astro-config.md +395 -0
  303. package/skills/frontend/astro/assets/reference/modules/astro-content.md +720 -0
  304. package/skills/frontend/astro/assets/reference/modules/astro-env.md +46 -0
  305. package/skills/frontend/astro/assets/reference/modules/astro-fetch.md +346 -0
  306. package/skills/frontend/astro/assets/reference/modules/astro-hono.md +37 -0
  307. package/skills/frontend/astro/assets/reference/modules/astro-i18n.md +462 -0
  308. package/skills/frontend/astro/assets/reference/modules/astro-middleware.md +292 -0
  309. package/skills/frontend/astro/assets/reference/modules/astro-static-paths.md +74 -0
  310. package/skills/frontend/astro/assets/reference/modules/astro-transitions.md +595 -0
  311. package/skills/frontend/astro/assets/reference/modules/astro-zod.md +120 -0
  312. package/skills/frontend/astro/assets/reference/session-driver-reference.md +205 -0
  313. package/skills/frontend/astro/assets/routing-and-navigation/endpoints.md +251 -0
  314. package/skills/frontend/astro/assets/routing-and-navigation/internationalization.md +374 -0
  315. package/skills/frontend/astro/assets/routing-and-navigation/middleware.md +288 -0
  316. package/skills/frontend/astro/assets/routing-and-navigation/pages.md +205 -0
  317. package/skills/frontend/astro/assets/routing-and-navigation/prefetch.md +273 -0
  318. package/skills/frontend/astro/assets/routing-and-navigation/routing.md +760 -0
  319. package/skills/frontend/astro/assets/routing-and-navigation/view-transitions.md +792 -0
  320. package/skills/frontend/astro/assets/server-rendering/actions.md +770 -0
  321. package/skills/frontend/astro/assets/server-rendering/caching.md +255 -0
  322. package/skills/frontend/astro/assets/server-rendering/on-demand-rendering.md +289 -0
  323. package/skills/frontend/astro/assets/server-rendering/server-islands.md +126 -0
  324. package/skills/frontend/astro/assets/server-rendering/sessions.md +270 -0
  325. package/skills/frontend/astro/assets/start-a-new-project/develop-and-build.md +147 -0
  326. package/skills/frontend/astro/assets/start-a-new-project/installation.md +342 -0
  327. package/skills/frontend/astro/assets/start-a-new-project/project-structure.md +137 -0
  328. package/skills/frontend/astro/assets/upgrade-and-troubleshooting/testing.md +412 -0
  329. package/skills/frontend/astro/assets/upgrade-and-troubleshooting/troubleshooting.md +229 -0
  330. package/skills/frontend/astro/assets/upgrade-and-troubleshooting/upgrade-astro.md +205 -0
  331. package/skills/frontend/astro/assets/welcome/courses.md +46 -0
  332. package/skills/frontend/astro/assets/welcome/islands-architecture.md +135 -0
  333. package/skills/frontend/astro/assets/welcome/why-astro.md +90 -0
  334. package/skills/frontend/astro/evals/evals.json +66 -0
  335. package/skills/frontend/astro/references/contentCollections.md +164 -0
  336. package/skills/frontend/astro/references/islandsArchitecture.md +128 -0
  337. package/skills/frontend/astro/references/serverIslandsAndActions.md +187 -0
  338. package/skills/frontend/astro/scripts/auditAstroProduction.py +78 -0
  339. package/skills/frontend/generativeUi/SKILL.md +128 -0
  340. package/skills/frontend/generativeUi/evals/generativeUiVerification.json +14 -0
  341. package/skills/frontend/generativeUi/references/apiReference.md +3 -0
  342. package/skills/frontend/generativeUi/references/clientToolComponentMapping.md +8 -0
  343. package/skills/frontend/generativeUi/references/dataStreamProtocol.md +10 -0
  344. package/skills/frontend/generativeUi/scripts/generateUiComponentStub.py +46 -0
  345. package/skills/frontend/nextjs/SKILL.md +138 -0
  346. package/skills/frontend/nextjs/assets/README.md +67 -0
  347. package/skills/frontend/nextjs/assets/api-reference/cli/create-next-app.md +210 -0
  348. package/skills/frontend/nextjs/assets/api-reference/cli/next.md +484 -0
  349. package/skills/frontend/nextjs/assets/api-reference/components/font.md +952 -0
  350. package/skills/frontend/nextjs/assets/api-reference/components/form.md +387 -0
  351. package/skills/frontend/nextjs/assets/api-reference/components/image.md +1372 -0
  352. package/skills/frontend/nextjs/assets/api-reference/components/link.md +954 -0
  353. package/skills/frontend/nextjs/assets/api-reference/components/script.md +421 -0
  354. package/skills/frontend/nextjs/assets/api-reference/directives/use-cache-private.md +211 -0
  355. package/skills/frontend/nextjs/assets/api-reference/directives/use-cache-remote.md +652 -0
  356. package/skills/frontend/nextjs/assets/api-reference/directives/use-cache.md +848 -0
  357. package/skills/frontend/nextjs/assets/api-reference/directives/use-client.md +149 -0
  358. package/skills/frontend/nextjs/assets/api-reference/directives/use-server.md +234 -0
  359. package/skills/frontend/nextjs/assets/api-reference/edge-runtime.md +188 -0
  360. package/skills/frontend/nextjs/assets/api-reference/file-conventions/default.md +80 -0
  361. package/skills/frontend/nextjs/assets/api-reference/file-conventions/dynamic-routes.md +417 -0
  362. package/skills/frontend/nextjs/assets/api-reference/file-conventions/error.md +361 -0
  363. package/skills/frontend/nextjs/assets/api-reference/file-conventions/forbidden.md +75 -0
  364. package/skills/frontend/nextjs/assets/api-reference/file-conventions/instrumentation-client.md +308 -0
  365. package/skills/frontend/nextjs/assets/api-reference/file-conventions/instrumentation.md +177 -0
  366. package/skills/frontend/nextjs/assets/api-reference/file-conventions/intercepting-routes.md +78 -0
  367. package/skills/frontend/nextjs/assets/api-reference/file-conventions/layout.md +803 -0
  368. package/skills/frontend/nextjs/assets/api-reference/file-conventions/loading.md +209 -0
  369. package/skills/frontend/nextjs/assets/api-reference/file-conventions/mdx-components.md +84 -0
  370. package/skills/frontend/nextjs/assets/api-reference/file-conventions/metadata/app-icons.md +302 -0
  371. package/skills/frontend/nextjs/assets/api-reference/file-conventions/metadata/manifest.md +90 -0
  372. package/skills/frontend/nextjs/assets/api-reference/file-conventions/metadata/opengraph-image.md +580 -0
  373. package/skills/frontend/nextjs/assets/api-reference/file-conventions/metadata/robots.md +234 -0
  374. package/skills/frontend/nextjs/assets/api-reference/file-conventions/metadata/sitemap.md +459 -0
  375. package/skills/frontend/nextjs/assets/api-reference/file-conventions/not-found.md +278 -0
  376. package/skills/frontend/nextjs/assets/api-reference/file-conventions/page.md +283 -0
  377. package/skills/frontend/nextjs/assets/api-reference/file-conventions/parallel-routes.md +517 -0
  378. package/skills/frontend/nextjs/assets/api-reference/file-conventions/proxy.md +857 -0
  379. package/skills/frontend/nextjs/assets/api-reference/file-conventions/public-folder.md +47 -0
  380. package/skills/frontend/nextjs/assets/api-reference/file-conventions/route-groups.md +40 -0
  381. package/skills/frontend/nextjs/assets/api-reference/file-conventions/route-segment-config/dynamicParams.md +40 -0
  382. package/skills/frontend/nextjs/assets/api-reference/file-conventions/route-segment-config/ensureStatic.md +195 -0
  383. package/skills/frontend/nextjs/assets/api-reference/file-conventions/route-segment-config/instant.md +204 -0
  384. package/skills/frontend/nextjs/assets/api-reference/file-conventions/route-segment-config/maxDuration.md +42 -0
  385. package/skills/frontend/nextjs/assets/api-reference/file-conventions/route-segment-config/preferredRegion.md +55 -0
  386. package/skills/frontend/nextjs/assets/api-reference/file-conventions/route-segment-config/prefetch.md +113 -0
  387. package/skills/frontend/nextjs/assets/api-reference/file-conventions/route-segment-config/runtime.md +43 -0
  388. package/skills/frontend/nextjs/assets/api-reference/file-conventions/route.md +772 -0
  389. package/skills/frontend/nextjs/assets/api-reference/file-conventions/src-folder.md +42 -0
  390. package/skills/frontend/nextjs/assets/api-reference/file-conventions/template.md +174 -0
  391. package/skills/frontend/nextjs/assets/api-reference/file-conventions/unauthorized.md +143 -0
  392. package/skills/frontend/nextjs/assets/api-reference/functions/after.md +332 -0
  393. package/skills/frontend/nextjs/assets/api-reference/functions/cacheLife.md +642 -0
  394. package/skills/frontend/nextjs/assets/api-reference/functions/cacheTag.md +272 -0
  395. package/skills/frontend/nextjs/assets/api-reference/functions/catchError.md +267 -0
  396. package/skills/frontend/nextjs/assets/api-reference/functions/connection.md +114 -0
  397. package/skills/frontend/nextjs/assets/api-reference/functions/cookies.md +349 -0
  398. package/skills/frontend/nextjs/assets/api-reference/functions/draft-mode.md +173 -0
  399. package/skills/frontend/nextjs/assets/api-reference/functions/fetch.md +141 -0
  400. package/skills/frontend/nextjs/assets/api-reference/functions/forbidden.md +327 -0
  401. package/skills/frontend/nextjs/assets/api-reference/functions/generate-image-metadata.md +311 -0
  402. package/skills/frontend/nextjs/assets/api-reference/functions/generate-metadata.md +1510 -0
  403. package/skills/frontend/nextjs/assets/api-reference/functions/generate-sitemaps.md +102 -0
  404. package/skills/frontend/nextjs/assets/api-reference/functions/generate-static-params.md +606 -0
  405. package/skills/frontend/nextjs/assets/api-reference/functions/generate-viewport.md +347 -0
  406. package/skills/frontend/nextjs/assets/api-reference/functions/headers.md +92 -0
  407. package/skills/frontend/nextjs/assets/api-reference/functions/image-response.md +225 -0
  408. package/skills/frontend/nextjs/assets/api-reference/functions/io.md +131 -0
  409. package/skills/frontend/nextjs/assets/api-reference/functions/navigation.md +220 -0
  410. package/skills/frontend/nextjs/assets/api-reference/functions/next-request.md +116 -0
  411. package/skills/frontend/nextjs/assets/api-reference/functions/next-response.md +219 -0
  412. package/skills/frontend/nextjs/assets/api-reference/functions/next-root-params.md +479 -0
  413. package/skills/frontend/nextjs/assets/api-reference/functions/not-found.md +269 -0
  414. package/skills/frontend/nextjs/assets/api-reference/functions/permanentRedirect.md +92 -0
  415. package/skills/frontend/nextjs/assets/api-reference/functions/prefetch.md +202 -0
  416. package/skills/frontend/nextjs/assets/api-reference/functions/redirect.md +255 -0
  417. package/skills/frontend/nextjs/assets/api-reference/functions/refresh.md +91 -0
  418. package/skills/frontend/nextjs/assets/api-reference/functions/revalidatePath.md +248 -0
  419. package/skills/frontend/nextjs/assets/api-reference/functions/revalidateTag.md +175 -0
  420. package/skills/frontend/nextjs/assets/api-reference/functions/unauthorized.md +389 -0
  421. package/skills/frontend/nextjs/assets/api-reference/functions/unstable_cache.md +131 -0
  422. package/skills/frontend/nextjs/assets/api-reference/functions/unstable_noStore.md +61 -0
  423. package/skills/frontend/nextjs/assets/api-reference/functions/unstable_rethrow.md +79 -0
  424. package/skills/frontend/nextjs/assets/api-reference/functions/updateTag.md +173 -0
  425. package/skills/frontend/nextjs/assets/api-reference/functions/use-link-status.md +268 -0
  426. package/skills/frontend/nextjs/assets/api-reference/functions/use-offline.md +222 -0
  427. package/skills/frontend/nextjs/assets/api-reference/functions/use-params.md +102 -0
  428. package/skills/frontend/nextjs/assets/api-reference/functions/use-pathname.md +189 -0
  429. package/skills/frontend/nextjs/assets/api-reference/functions/use-report-web-vitals.md +175 -0
  430. package/skills/frontend/nextjs/assets/api-reference/functions/use-router.md +214 -0
  431. package/skills/frontend/nextjs/assets/api-reference/functions/use-search-params.md +416 -0
  432. package/skills/frontend/nextjs/assets/api-reference/functions/use-selected-layout-segment.md +214 -0
  433. package/skills/frontend/nextjs/assets/api-reference/functions/use-selected-layout-segments.md +116 -0
  434. package/skills/frontend/nextjs/assets/api-reference/functions/use-server-inserted-html.md +145 -0
  435. package/skills/frontend/nextjs/assets/api-reference/functions/userAgent.md +95 -0
  436. package/skills/frontend/nextjs/assets/api-reference/turbopack.md +552 -0
  437. package/skills/frontend/nextjs/assets/architecture/accessibility.md +47 -0
  438. package/skills/frontend/nextjs/assets/architecture/fast-refresh.md +122 -0
  439. package/skills/frontend/nextjs/assets/architecture/nextjs-compiler.md +376 -0
  440. package/skills/frontend/nextjs/assets/architecture/supported-browsers.md +146 -0
  441. package/skills/frontend/nextjs/assets/community/contribution-guide.md +459 -0
  442. package/skills/frontend/nextjs/assets/community/rspack.md +25 -0
  443. package/skills/frontend/nextjs/assets/getting-started/caching.md +626 -0
  444. package/skills/frontend/nextjs/assets/getting-started/css.md +336 -0
  445. package/skills/frontend/nextjs/assets/getting-started/deploying.md +115 -0
  446. package/skills/frontend/nextjs/assets/getting-started/error-handling.md +485 -0
  447. package/skills/frontend/nextjs/assets/getting-started/fetching-data.md +743 -0
  448. package/skills/frontend/nextjs/assets/getting-started/fonts.md +232 -0
  449. package/skills/frontend/nextjs/assets/getting-started/images.md +272 -0
  450. package/skills/frontend/nextjs/assets/getting-started/installation.md +446 -0
  451. package/skills/frontend/nextjs/assets/getting-started/layouts-and-pages.md +386 -0
  452. package/skills/frontend/nextjs/assets/getting-started/linking-and-navigating.md +475 -0
  453. package/skills/frontend/nextjs/assets/getting-started/metadata-and-og-images.md +370 -0
  454. package/skills/frontend/nextjs/assets/getting-started/mutating-data.md +679 -0
  455. package/skills/frontend/nextjs/assets/getting-started/project-structure.md +290 -0
  456. package/skills/frontend/nextjs/assets/getting-started/proxy.md +107 -0
  457. package/skills/frontend/nextjs/assets/getting-started/revalidating.md +241 -0
  458. package/skills/frontend/nextjs/assets/getting-started/route-handlers.md +233 -0
  459. package/skills/frontend/nextjs/assets/getting-started/server-and-client-components.md +683 -0
  460. package/skills/frontend/nextjs/assets/getting-started/upgrading.md +137 -0
  461. package/skills/frontend/nextjs/assets/glossary.md +315 -0
  462. package/skills/frontend/nextjs/evals/nextjsVerification.json +14 -0
  463. package/skills/frontend/nextjs/references/apiReference.md +3 -0
  464. package/skills/frontend/nextjs/references/dataAccessLayer.md +39 -0
  465. package/skills/frontend/nextjs/references/nextjsFeatureMap.md +276 -0
  466. package/skills/frontend/nextjs/references/productionChecklist.md +49 -0
  467. package/skills/frontend/nextjs/references/securityHeadersCsp.md +44 -0
  468. package/skills/frontend/nextjs/scripts/auditProductionReadiness.py +85 -0
  469. package/skills/frontend/shadcn-ui/SKILL.md +102 -0
  470. package/skills/frontend/shadcn-ui/assets/README.md +82 -0
  471. package/skills/frontend/shadcn-ui/assets/advanced/javascript.md +44 -0
  472. package/skills/frontend/shadcn-ui/assets/advanced/monorepo.md +254 -0
  473. package/skills/frontend/shadcn-ui/assets/advanced/react-19.md +166 -0
  474. package/skills/frontend/shadcn-ui/assets/advanced/tailwind-v4.md +333 -0
  475. package/skills/frontend/shadcn-ui/assets/ai-elements/chain-of-thought.md +519 -0
  476. package/skills/frontend/shadcn-ui/assets/ai-elements/chat.md +581 -0
  477. package/skills/frontend/shadcn-ui/assets/ai-elements/checkpoint.md +243 -0
  478. package/skills/frontend/shadcn-ui/assets/ai-elements/confirmation.md +382 -0
  479. package/skills/frontend/shadcn-ui/assets/ai-elements/context.md +188 -0
  480. package/skills/frontend/shadcn-ui/assets/ai-elements/file-tree.md +248 -0
  481. package/skills/frontend/shadcn-ui/assets/ai-elements/index.md +307 -0
  482. package/skills/frontend/shadcn-ui/assets/ai-elements/inline-citation.md +219 -0
  483. package/skills/frontend/shadcn-ui/assets/ai-elements/message.md +298 -0
  484. package/skills/frontend/shadcn-ui/assets/ai-elements/model-selector.md +368 -0
  485. package/skills/frontend/shadcn-ui/assets/ai-elements/plan.md +398 -0
  486. package/skills/frontend/shadcn-ui/assets/ai-elements/prompt-input.md +403 -0
  487. package/skills/frontend/shadcn-ui/assets/ai-elements/queue.md +517 -0
  488. package/skills/frontend/shadcn-ui/assets/ai-elements/reasoning.md +349 -0
  489. package/skills/frontend/shadcn-ui/assets/ai-elements/sources.md +303 -0
  490. package/skills/frontend/shadcn-ui/assets/ai-elements/stack-trace.md +514 -0
  491. package/skills/frontend/shadcn-ui/assets/ai-elements/subagent.md +551 -0
  492. package/skills/frontend/shadcn-ui/assets/ai-elements/suggestion.md +246 -0
  493. package/skills/frontend/shadcn-ui/assets/ai-elements/task.md +380 -0
  494. package/skills/frontend/shadcn-ui/assets/ai-elements/terminal.md +463 -0
  495. package/skills/frontend/shadcn-ui/assets/ai-elements/test-results.md +641 -0
  496. package/skills/frontend/shadcn-ui/assets/ai-elements/tool.md +915 -0
  497. package/skills/frontend/shadcn-ui/assets/components/accordion.md +490 -0
  498. package/skills/frontend/shadcn-ui/assets/components/alert-dialog.md +520 -0
  499. package/skills/frontend/shadcn-ui/assets/components/alert.md +351 -0
  500. package/skills/frontend/shadcn-ui/assets/components/aspect-ratio.md +206 -0
  501. package/skills/frontend/shadcn-ui/assets/components/attachment.md +715 -0
  502. package/skills/frontend/shadcn-ui/assets/components/avatar.md +581 -0
  503. package/skills/frontend/shadcn-ui/assets/components/badge.md +276 -0
  504. package/skills/frontend/shadcn-ui/assets/components/breadcrumb.md +556 -0
  505. package/skills/frontend/shadcn-ui/assets/components/bubble.md +706 -0
  506. package/skills/frontend/shadcn-ui/assets/components/button-group.md +969 -0
  507. package/skills/frontend/shadcn-ui/assets/components/button.md +523 -0
  508. package/skills/frontend/shadcn-ui/assets/components/calendar.md +959 -0
  509. package/skills/frontend/shadcn-ui/assets/components/card.md +684 -0
  510. package/skills/frontend/shadcn-ui/assets/components/carousel.md +643 -0
  511. package/skills/frontend/shadcn-ui/assets/components/chart.md +1295 -0
  512. package/skills/frontend/shadcn-ui/assets/components/checkbox.md +553 -0
  513. package/skills/frontend/shadcn-ui/assets/components/code-block.md +2041 -0
  514. package/skills/frontend/shadcn-ui/assets/components/collapsible.md +504 -0
  515. package/skills/frontend/shadcn-ui/assets/components/combobox.md +1102 -0
  516. package/skills/frontend/shadcn-ui/assets/components/command.md +682 -0
  517. package/skills/frontend/shadcn-ui/assets/components/context-menu.md +949 -0
  518. package/skills/frontend/shadcn-ui/assets/components/data-table.md +1667 -0
  519. package/skills/frontend/shadcn-ui/assets/components/date-picker.md +698 -0
  520. package/skills/frontend/shadcn-ui/assets/components/dialog.md +454 -0
  521. package/skills/frontend/shadcn-ui/assets/components/direction.md +205 -0
  522. package/skills/frontend/shadcn-ui/assets/components/drawer.md +806 -0
  523. package/skills/frontend/shadcn-ui/assets/components/dropdown-menu.md +1315 -0
  524. package/skills/frontend/shadcn-ui/assets/components/empty.md +562 -0
  525. package/skills/frontend/shadcn-ui/assets/components/field.md +1321 -0
  526. package/skills/frontend/shadcn-ui/assets/components/hover-card.md +342 -0
  527. package/skills/frontend/shadcn-ui/assets/components/index.md +82 -0
  528. package/skills/frontend/shadcn-ui/assets/components/input-group.md +980 -0
  529. package/skills/frontend/shadcn-ui/assets/components/input-otp.md +551 -0
  530. package/skills/frontend/shadcn-ui/assets/components/input.md +555 -0
  531. package/skills/frontend/shadcn-ui/assets/components/item.md +937 -0
  532. package/skills/frontend/shadcn-ui/assets/components/kbd.md +290 -0
  533. package/skills/frontend/shadcn-ui/assets/components/label.md +327 -0
  534. package/skills/frontend/shadcn-ui/assets/components/marker.md +445 -0
  535. package/skills/frontend/shadcn-ui/assets/components/menubar.md +804 -0
  536. package/skills/frontend/shadcn-ui/assets/components/message-scroller.md +2770 -0
  537. package/skills/frontend/shadcn-ui/assets/components/message.md +618 -0
  538. package/skills/frontend/shadcn-ui/assets/components/native-select.md +321 -0
  539. package/skills/frontend/shadcn-ui/assets/components/navigation-menu.md +568 -0
  540. package/skills/frontend/shadcn-ui/assets/components/pagination.md +425 -0
  541. package/skills/frontend/shadcn-ui/assets/components/popover.md +402 -0
  542. package/skills/frontend/shadcn-ui/assets/components/progress.md +240 -0
  543. package/skills/frontend/shadcn-ui/assets/components/questionnaire.md +2055 -0
  544. package/skills/frontend/shadcn-ui/assets/components/radio-group.md +440 -0
  545. package/skills/frontend/shadcn-ui/assets/components/resizable.md +302 -0
  546. package/skills/frontend/shadcn-ui/assets/components/scroll-area.md +226 -0
  547. package/skills/frontend/shadcn-ui/assets/components/select.md +647 -0
  548. package/skills/frontend/shadcn-ui/assets/components/separator.md +235 -0
  549. package/skills/frontend/shadcn-ui/assets/components/sheet.md +354 -0
  550. package/skills/frontend/shadcn-ui/assets/components/sidebar.md +1156 -0
  551. package/skills/frontend/shadcn-ui/assets/components/skeleton.md +217 -0
  552. package/skills/frontend/shadcn-ui/assets/components/slider.md +253 -0
  553. package/skills/frontend/shadcn-ui/assets/components/spinner.md +352 -0
  554. package/skills/frontend/shadcn-ui/assets/components/switch.md +296 -0
  555. package/skills/frontend/shadcn-ui/assets/components/table.md +572 -0
  556. package/skills/frontend/shadcn-ui/assets/components/tabs.md +425 -0
  557. package/skills/frontend/shadcn-ui/assets/components/textarea.md +218 -0
  558. package/skills/frontend/shadcn-ui/assets/components/toast.md +260 -0
  559. package/skills/frontend/shadcn-ui/assets/components/toggle-group.md +419 -0
  560. package/skills/frontend/shadcn-ui/assets/components/toggle.md +220 -0
  561. package/skills/frontend/shadcn-ui/assets/components/tooltip.md +332 -0
  562. package/skills/frontend/shadcn-ui/assets/components/trace.md +1890 -0
  563. package/skills/frontend/shadcn-ui/assets/components/typography.md +561 -0
  564. package/skills/frontend/shadcn-ui/assets/dark-mode/next.md +108 -0
  565. package/skills/frontend/shadcn-ui/assets/dark-mode/overview.md +75 -0
  566. package/skills/frontend/shadcn-ui/assets/dark-mode/vite.md +144 -0
  567. package/skills/frontend/shadcn-ui/assets/forms/next.md +716 -0
  568. package/skills/frontend/shadcn-ui/assets/forms/overview.md +60 -0
  569. package/skills/frontend/shadcn-ui/assets/forms/react-hook-form.md +2055 -0
  570. package/skills/frontend/shadcn-ui/assets/forms/tanstack-form.md +2236 -0
  571. package/skills/frontend/shadcn-ui/assets/installation/astro.md +252 -0
  572. package/skills/frontend/shadcn-ui/assets/installation/manual.md +255 -0
  573. package/skills/frontend/shadcn-ui/assets/installation/next.md +256 -0
  574. package/skills/frontend/shadcn-ui/assets/installation/react-router.md +226 -0
  575. package/skills/frontend/shadcn-ui/assets/installation/remix.md +52 -0
  576. package/skills/frontend/shadcn-ui/assets/installation/vite.md +314 -0
  577. package/skills/frontend/shadcn-ui/assets/mcp/mcp.md +338 -0
  578. package/skills/frontend/shadcn-ui/assets/overview/changelog.md +6 -0
  579. package/skills/frontend/shadcn-ui/assets/overview/cli.md +738 -0
  580. package/skills/frontend/shadcn-ui/assets/overview/components-json.md +379 -0
  581. package/skills/frontend/shadcn-ui/assets/overview/directory.md +74 -0
  582. package/skills/frontend/shadcn-ui/assets/overview/introduction.md +77 -0
  583. package/skills/frontend/shadcn-ui/assets/overview/skills.md +71 -0
  584. package/skills/frontend/shadcn-ui/assets/overview/theming.md +304 -0
  585. package/skills/frontend/shadcn-ui/assets/overview/typeset.md +242 -0
  586. package/skills/frontend/shadcn-ui/assets/registry/getting-started.md +648 -0
  587. package/skills/frontend/shadcn-ui/assets/registry/overview.md +90 -0
  588. package/skills/frontend/shadcn-ui/assets/registry/registry-item-json.md +483 -0
  589. package/skills/frontend/shadcn-ui/assets/registry/registry-json.md +178 -0
  590. package/skills/frontend/shadcn-ui/evals/componentVerification.json +19 -0
  591. package/skills/frontend/shadcn-ui/references/aiComponentsCatalog.md +51 -0
  592. package/skills/frontend/shadcn-ui/references/apiReference.md +3 -0
  593. package/skills/frontend/shadcn-ui/references/blocksCatalog.md +32 -0
  594. package/skills/frontend/shadcn-ui/references/cliCommands.md +47 -0
  595. package/skills/frontend/shadcn-ui/references/componentMarkdownSources.md +48 -0
  596. package/skills/frontend/shadcn-ui/scripts/fetchComponentDocs.py +43 -0
  597. package/skills/frontend/tsxReactStandard/SKILL.md +150 -0
  598. package/skills/frontend/tsxReactStandard/evals/tsxVerification.json +14 -0
  599. package/skills/frontend/tsxReactStandard/references/apiReference.md +3 -0
  600. package/skills/frontend/tsxReactStandard/references/discriminatedUnions.md +31 -0
  601. package/skills/frontend/tsxReactStandard/references/tsconfigStrict.md +36 -0
  602. package/skills/frontend/tsxReactStandard/scripts/validateTsxTypes.py +44 -0
  603. package/skills/gitVersionControl/gitWorkflow/SKILL.md +128 -0
  604. package/skills/gitVersionControl/gitWorkflow/assets/README.md +23 -0
  605. package/skills/gitVersionControl/gitWorkflow/assets/cli/gh-environment.md +87 -0
  606. package/skills/gitVersionControl/gitWorkflow/assets/cli/gh-formatting.md +156 -0
  607. package/skills/gitVersionControl/gitWorkflow/assets/cli/gh-reference.md +2363 -0
  608. package/skills/gitVersionControl/gitWorkflow/assets/using-git/about-git.md +156 -0
  609. package/skills/gitVersionControl/gitWorkflow/assets/using-git/about-remote-repositories.md +65 -0
  610. package/skills/gitVersionControl/gitWorkflow/assets/using-git/associating-text-editors-with-git.md +93 -0
  611. package/skills/gitVersionControl/gitWorkflow/assets/using-git/caching-your-github-credentials.md +115 -0
  612. package/skills/gitVersionControl/gitWorkflow/assets/using-git/getting-changes-from-a-remote-repository.md +76 -0
  613. package/skills/gitVersionControl/gitWorkflow/assets/using-git/ignoring-files.md +51 -0
  614. package/skills/gitVersionControl/gitWorkflow/assets/using-git/managing-remote-repositories.md +231 -0
  615. package/skills/gitVersionControl/gitWorkflow/assets/using-git/pushing-commits-to-a-remote-repository.md +119 -0
  616. package/skills/gitVersionControl/gitWorkflow/evals/evalGitWorkflow.py +43 -0
  617. package/skills/gitVersionControl/gitWorkflow/references/apiReference.md +3 -0
  618. package/skills/gitVersionControl/gitWorkflow/references/branchingModels.md +32 -0
  619. package/skills/gitVersionControl/gitWorkflow/scripts/diagnoseGitGraph.py +68 -0
  620. package/skills/github/assets/README.md +39 -0
  621. package/skills/github/assets/cli/gh-environment.md +87 -0
  622. package/skills/github/assets/cli/gh-formatting.md +156 -0
  623. package/skills/github/assets/cli/gh-reference.md +2363 -0
  624. package/skills/github/assets/docs-api/github-docs-api.md +60 -0
  625. package/skills/github/assets/rest-api/actions-secrets.md +1272 -0
  626. package/skills/github/assets/rest-api/actions-variables.md +1247 -0
  627. package/skills/github/assets/rest-api/actions-workflow-runs.md +1697 -0
  628. package/skills/github/assets/rest-api/actions-workflows.md +348 -0
  629. package/skills/github/assets/rest-api/authenticating.md +174 -0
  630. package/skills/github/assets/rest-api/branches.md +727 -0
  631. package/skills/github/assets/rest-api/checks-runs.md +1013 -0
  632. package/skills/github/assets/rest-api/checks-suites.md +1142 -0
  633. package/skills/github/assets/rest-api/code-scanning.md +2957 -0
  634. package/skills/github/assets/rest-api/collaborators.md +547 -0
  635. package/skills/github/assets/rest-api/commits.md +957 -0
  636. package/skills/github/assets/rest-api/dependabot-alerts.md +895 -0
  637. package/skills/github/assets/rest-api/orgs.md +1172 -0
  638. package/skills/github/assets/rest-api/overview.md +875 -0
  639. package/skills/github/assets/rest-api/pull-reviews.md +722 -0
  640. package/skills/github/assets/rest-api/pulls.md +1605 -0
  641. package/skills/github/assets/rest-api/quickstart.md +344 -0
  642. package/skills/github/assets/rest-api/releases.md +650 -0
  643. package/skills/github/assets/rest-api/repos.md +2957 -0
  644. package/skills/github/assets/rest-api/rules.md +1507 -0
  645. package/skills/github/assets/rest-api/secret-scanning.md +947 -0
  646. package/skills/github/assets/rest-api/teams.md +1690 -0
  647. package/skills/github/githubAction/SKILL.md +159 -0
  648. package/skills/github/githubAction/assets/README.md +38 -0
  649. package/skills/github/githubAction/assets/reference/contexts.md +918 -0
  650. package/skills/github/githubAction/assets/reference/dependency-caching.md +393 -0
  651. package/skills/github/githubAction/assets/reference/events-that-trigger-workflows.md +1348 -0
  652. package/skills/github/githubAction/assets/reference/expressions.md +441 -0
  653. package/skills/github/githubAction/assets/reference/metadata-syntax.md +803 -0
  654. package/skills/github/githubAction/assets/reference/variables.md +149 -0
  655. package/skills/github/githubAction/assets/reference/workflow-cancellation.md +22 -0
  656. package/skills/github/githubAction/assets/reference/workflow-commands.md +1056 -0
  657. package/skills/github/githubAction/assets/reference/workflow-syntax.md +1721 -0
  658. package/skills/github/githubAction/assets/rest-api/secrets.md +1272 -0
  659. package/skills/github/githubAction/assets/rest-api/workflow-runs.md +1697 -0
  660. package/skills/github/githubAction/assets/rest-api/workflows.md +348 -0
  661. package/skills/github/githubAction/assets/starter-workflows/automation/stale.yml +27 -0
  662. package/skills/github/githubAction/assets/starter-workflows/ci/blank.yml +36 -0
  663. package/skills/github/githubAction/assets/starter-workflows/ci/docker-image.yml +18 -0
  664. package/skills/github/githubAction/assets/starter-workflows/ci/go.yml +28 -0
  665. package/skills/github/githubAction/assets/starter-workflows/ci/maven.yml +35 -0
  666. package/skills/github/githubAction/assets/starter-workflows/ci/node.js.yml +31 -0
  667. package/skills/github/githubAction/assets/starter-workflows/ci/python-app.yml +39 -0
  668. package/skills/github/githubAction/assets/starter-workflows/ci/rust.yml +22 -0
  669. package/skills/github/githubAction/assets/starter-workflows/code-scanning/codeql.yml +97 -0
  670. package/skills/github/githubAction/evals/actionVerification.json +14 -0
  671. package/skills/github/githubAction/references/apiReference.md +3 -0
  672. package/skills/github/githubAction/references/workflowPatterns.md +81 -0
  673. package/skills/github/githubAction/scripts/validateWorkflowYaml.py +53 -0
  674. package/skills/github/githubQuality/SKILL.md +136 -0
  675. package/skills/github/githubQuality/assets/README.md +24 -0
  676. package/skills/github/githubQuality/assets/pull-requests/about-code-owners.md +178 -0
  677. package/skills/github/githubQuality/assets/pull-requests/about-merge-methods.md +48 -0
  678. package/skills/github/githubQuality/assets/pull-requests/creating-a-pull-request.md +170 -0
  679. package/skills/github/githubQuality/assets/pull-requests/giving-reviews.md +48 -0
  680. package/skills/github/githubQuality/assets/pull-requests/managing-a-merge-queue.md +134 -0
  681. package/skills/github/githubQuality/assets/pull-requests/merging-a-pull-request.md +101 -0
  682. package/skills/github/githubQuality/assets/pull-requests/resolving-reviews.md +59 -0
  683. package/skills/github/githubQuality/assets/pull-requests/status-checks.md +135 -0
  684. package/skills/github/githubQuality/assets/rest-api/checks-runs.md +1013 -0
  685. package/skills/github/githubQuality/assets/rest-api/checks-suites.md +1142 -0
  686. package/skills/github/githubQuality/assets/rest-api/commits.md +957 -0
  687. package/skills/github/githubQuality/assets/rest-api/pulls.md +1605 -0
  688. package/skills/github/githubQuality/assets/rest-api/reviews.md +722 -0
  689. package/skills/github/githubQuality/evals/qualityVerification.json +14 -0
  690. package/skills/github/githubQuality/references/apiReference.md +3 -0
  691. package/skills/github/githubQuality/references/codeownersExample.md +26 -0
  692. package/skills/github/githubQuality/references/prTemplate.md +20 -0
  693. package/skills/github/githubQuality/scripts/auditPrQuality.py +52 -0
  694. package/skills/github/githubSecurity/SKILL.md +170 -0
  695. package/skills/github/githubSecurity/assets/README.md +32 -0
  696. package/skills/github/githubSecurity/assets/code-scanning/code-scanning-alerts.md +133 -0
  697. package/skills/github/githubSecurity/assets/code-scanning/code-scanning.md +67 -0
  698. package/skills/github/githubSecurity/assets/code-scanning/codeql-code-scanning.md +79 -0
  699. package/skills/github/githubSecurity/assets/code-scanning/configure-code-scanning.md +121 -0
  700. package/skills/github/githubSecurity/assets/dependabot/about-the-dependabot-yml-file.md +74 -0
  701. package/skills/github/githubSecurity/assets/dependabot/dependabot-alerts.md +133 -0
  702. package/skills/github/githubSecurity/assets/dependabot/dependabot-security-updates.md +95 -0
  703. package/skills/github/githubSecurity/assets/dependabot/dependabot-version-updates.md +80 -0
  704. package/skills/github/githubSecurity/assets/rest-api/code-scanning.md +2957 -0
  705. package/skills/github/githubSecurity/assets/rest-api/dependabot-alerts.md +895 -0
  706. package/skills/github/githubSecurity/assets/rest-api/secret-scanning.md +947 -0
  707. package/skills/github/githubSecurity/assets/secret-scanning/enable-secret-scanning.md +59 -0
  708. package/skills/github/githubSecurity/assets/secret-scanning/secret-scanning.md +105 -0
  709. package/skills/github/githubSecurity/assets/security-advisories/github-advisory-database.md +148 -0
  710. package/skills/github/githubSecurity/evals/securityVerification.json +14 -0
  711. package/skills/github/githubSecurity/references/apiReference.md +3 -0
  712. package/skills/github/githubSecurity/references/codeqlAnalysis.yml +42 -0
  713. package/skills/github/githubSecurity/references/dependabotConfig.yml +27 -0
  714. package/skills/github/githubSecurity/scripts/auditRepoSecurity.py +47 -0
  715. package/skills/github/githubSetup/SKILL.md +137 -0
  716. package/skills/github/githubSetup/assets/README.md +40 -0
  717. package/skills/github/githubSetup/assets/branches/about-protected-branches.md +198 -0
  718. package/skills/github/githubSetup/assets/branches/changing-the-default-branch.md +49 -0
  719. package/skills/github/githubSetup/assets/branches/deleting-and-restoring-branches.md +44 -0
  720. package/skills/github/githubSetup/assets/branches/managing-a-branch-protection-rule.md +115 -0
  721. package/skills/github/githubSetup/assets/branches/renaming-a-branch.md +74 -0
  722. package/skills/github/githubSetup/assets/branches/viewing-branches-in-your-repository.md +30 -0
  723. package/skills/github/githubSetup/assets/repositories/about-repositories.md +127 -0
  724. package/skills/github/githubSetup/assets/repositories/cloning-a-repository.md +114 -0
  725. package/skills/github/githubSetup/assets/repositories/creating-a-new-repository.md +82 -0
  726. package/skills/github/githubSetup/assets/repositories/creating-a-repository-from-a-template.md +51 -0
  727. package/skills/github/githubSetup/assets/repositories/deleting-a-repository.md +34 -0
  728. package/skills/github/githubSetup/assets/repositories/managing-teams-and-people-with-access.md +69 -0
  729. package/skills/github/githubSetup/assets/repositories/renaming-a-repository.md +47 -0
  730. package/skills/github/githubSetup/assets/repositories/restoring-a-deleted-repository.md +61 -0
  731. package/skills/github/githubSetup/assets/repositories/setting-repository-visibility.md +137 -0
  732. package/skills/github/githubSetup/assets/rest-api/branches.md +727 -0
  733. package/skills/github/githubSetup/assets/rest-api/quickstart.md +344 -0
  734. package/skills/github/githubSetup/assets/rest-api/repos.md +2957 -0
  735. package/skills/github/githubSetup/assets/rulesets/about-rulesets.md +72 -0
  736. package/skills/github/githubSetup/assets/rulesets/available-rules-for-rulesets.md +383 -0
  737. package/skills/github/githubSetup/assets/rulesets/converting-branch-protections-to-rulesets.md +92 -0
  738. package/skills/github/githubSetup/assets/rulesets/creating-rulesets-for-a-repository.md +108 -0
  739. package/skills/github/githubSetup/assets/rulesets/managing-rulesets-for-a-repository.md +149 -0
  740. package/skills/github/githubSetup/assets/rulesets/troubleshooting-rules.md +122 -0
  741. package/skills/github/githubSetup/evals/setupVerification.json +14 -0
  742. package/skills/github/githubSetup/references/apiReference.md +3 -0
  743. package/skills/github/githubSetup/references/repoSettingsBlueprint.md +13 -0
  744. package/skills/github/githubSetup/references/rulesetTemplates.json +42 -0
  745. package/skills/github/githubSetup/scripts/configureRepoBaseline.py +46 -0
  746. package/skills/github/githubTeam/SKILL.md +115 -0
  747. package/skills/github/githubTeam/assets/README.md +21 -0
  748. package/skills/github/githubTeam/assets/organizations/about-organizations.md +69 -0
  749. package/skills/github/githubTeam/assets/organizations/repository-roles-for-an-organization.md +94 -0
  750. package/skills/github/githubTeam/assets/rest-api/collaborators.md +547 -0
  751. package/skills/github/githubTeam/assets/rest-api/orgs.md +1172 -0
  752. package/skills/github/githubTeam/assets/rest-api/teams.md +1690 -0
  753. package/skills/github/githubTeam/assets/teams/about-teams.md +82 -0
  754. package/skills/github/githubTeam/assets/teams/adding-members-to-a-team.md +55 -0
  755. package/skills/github/githubTeam/evals/teamVerification.json +14 -0
  756. package/skills/github/githubTeam/references/apiReference.md +3 -0
  757. package/skills/github/githubTeam/references/permissionMatrix.md +17 -0
  758. package/skills/github/githubTeam/references/reviewAssignment.md +17 -0
  759. package/skills/github/githubTeam/scripts/manageTeamSync.py +31 -0
  760. package/skills/securityQa/llmSecurityRedteaming/SKILL.md +86 -0
  761. package/skills/securityQa/llmSecurityRedteaming/evals/securityRedteamVerification.json +14 -0
  762. package/skills/securityQa/llmSecurityRedteaming/references/apiReference.md +3 -0
  763. package/skills/securityQa/llmSecurityRedteaming/references/jailbreakTaxonomy.md +6 -0
  764. package/skills/securityQa/llmSecurityRedteaming/references/owaspLlmTopTen.md +12 -0
  765. package/skills/securityQa/llmSecurityRedteaming/scripts/testPromptInjection.py +34 -0
  766. package/skills/softwareDevelopment/requirementsEngineering/SKILL.md +110 -0
  767. package/skills/softwareDevelopment/requirementsEngineering/evals/evalRequirements.py +33 -0
  768. package/skills/softwareDevelopment/requirementsEngineering/references/apiReference.md +3 -0
  769. package/skills/softwareDevelopment/requirementsEngineering/references/requirementsAnalysisModels.md +34 -0
  770. package/skills/softwareDevelopment/requirementsEngineering/scripts/validateUserStories.py +49 -0
  771. package/skills/testing/testDrivenDevelopment/SKILL.md +122 -0
  772. package/skills/testing/testDrivenDevelopment/evals/evalTdd.py +25 -0
  773. package/skills/testing/testDrivenDevelopment/references/apiReference.md +3 -0
  774. package/skills/testing/testDrivenDevelopment/references/testPyramidDoubles.md +35 -0
  775. package/skills/testing/testDrivenDevelopment/scripts/auditTestPyramid.py +58 -0
@@ -0,0 +1,2770 @@
1
+ ---
2
+ title: Message Scroller
3
+ description: A chat scroll container that anchors turns, opens saved transcripts, follows streamed responses, loads history without jumping, and jumps to any message.
4
+ base: base
5
+ component: true
6
+ ---
7
+
8
+ ```tsx
9
+ "use client"
10
+
11
+ import { useChat } from "@ai-sdk/react"
12
+ import {
13
+ ArrowUpIcon,
14
+ GlobeIcon,
15
+ ImageIcon,
16
+ MessageCircleDashedIcon,
17
+ PaperclipIcon,
18
+ PlusIcon,
19
+ RotateCwIcon,
20
+ TelescopeIcon,
21
+ } from "lucide-react"
22
+
23
+ import { createChat, getMessageText } from "@/lib/ai"
24
+ import { MessageAnimated } from "@/components/message-animated"
25
+ import { Button } from "@/components/ui/button"
26
+ import {
27
+ Card,
28
+ CardAction,
29
+ CardContent,
30
+ CardDescription,
31
+ CardFooter,
32
+ CardHeader,
33
+ CardTitle,
34
+ } from "@/components/ui/card"
35
+ import {
36
+ DropdownMenu,
37
+ DropdownMenuContent,
38
+ DropdownMenuItem,
39
+ DropdownMenuSeparator,
40
+ DropdownMenuTrigger,
41
+ } from "@/components/ui/dropdown-menu"
42
+ import {
43
+ Empty,
44
+ EmptyDescription,
45
+ EmptyHeader,
46
+ EmptyMedia,
47
+ EmptyTitle,
48
+ } from "@/components/ui/empty"
49
+ import {
50
+ InputGroup,
51
+ InputGroupAddon,
52
+ InputGroupButton,
53
+ } from "@/components/ui/input-group"
54
+ import {
55
+ MessageScroller,
56
+ MessageScrollerButton,
57
+ MessageScrollerContent,
58
+ MessageScrollerProvider,
59
+ MessageScrollerViewport,
60
+ } from "@/components/ui/message-scroller"
61
+ import {
62
+ Tooltip,
63
+ TooltipContent,
64
+ TooltipTrigger,
65
+ } from "@/components/ui/tooltip"
66
+
67
+ const chat = createChat()
68
+ .user(
69
+ "I'm building a chat for our app and the scroll behavior is driving me nuts. Every time the AI streams a reply, the whole thread jumps around."
70
+ )
71
+ .sleep(1000)
72
+ .assistant(
73
+ "That's the classic streaming scroll problem. Wrap your message list in `MessageScroller` and turn on `autoScroll` — the viewport pins to the bottom as tokens arrive, so users always see the latest text land in place.\n\nThe important part: it only auto-scrolls while the reader is already at the bottom. The moment they scroll up to read something earlier, auto-scroll backs off and their position is preserved. You get smooth streaming without fighting the user's intent."
74
+ )
75
+ .user(
76
+ "Okay, but when someone sends a new message the view still feels jarring — like the whole conversation reloads from the top."
77
+ )
78
+ .sleep(1000)
79
+ .assistant(
80
+ "MessageScrollerItem fixes that with turn anchoring. Set `scrollAnchor` on the turn that should settle near the top instead of blindly snapping to the document bottom.\n\nIt also leaves a small peek of the previous exchange visible above the anchor, so context isn't lost. The reply starts in view without that disorienting jump you get from a plain overflow container."
81
+ )
82
+ .user(
83
+ "And if they've scrolled up to re-read an older answer? I don't want to yank them back down."
84
+ )
85
+ .sleep(1000)
86
+ .assistant(
87
+ "You won't. Auto-scroll only runs when the viewport is already pinned to the bottom, so scrolling up is a deliberate opt-out — their place in the thread stays put even as new tokens keep arriving below.\n\nWhen there is content they haven't seen yet, `MessageScrollerButton` appears at the bottom of the viewport. One tap jumps them back to the newest message and re-engages auto-scroll. Same pattern as Slack or iMessage: quiet when you're caught up, helpful when you're not."
88
+ )
89
+ .user("Last one — does this work with assistive tech?")
90
+ .sleep(1000)
91
+ .assistant(
92
+ '`MessageScrollerContent` sets `role="log"` and `aria-relevant="additions"` by default, so screen readers announce new messages as they stream in.\n\nThe scroll button is a real `<button>` with an sr-only label, and it\'s removed from the tab order when you\'re already at the bottom — no ghost focus stops.'
93
+ )
94
+ const initialMessages = chat.get(0)
95
+ const transport = chat.transport({ delayMs: 20 })
96
+
97
+ export function MessageScrollerDemo() {
98
+ const { messages, sendMessage, status, setMessages } = useChat({
99
+ messages: initialMessages,
100
+ transport,
101
+ })
102
+ const nextMessage = chat.next(messages)
103
+ const isBusy = status === "submitted" || status === "streaming"
104
+
105
+ return (
106
+ <MessageScrollerProvider>
107
+ <div className="relative flex flex-col gap-4">
108
+ <Card className="mx-auto h-140 w-full max-w-sm gap-0">
109
+ <CardHeader className="gap-1 border-b">
110
+ <CardTitle>New Chat</CardTitle>
111
+ <CardDescription>How can I help you today?</CardDescription>
112
+ <CardAction>
113
+ <Tooltip>
114
+ <TooltipTrigger
115
+ render={
116
+ <Button
117
+ variant="outline"
118
+ size="icon"
119
+ aria-label="Reset conversation"
120
+ onClick={() => setMessages(initialMessages)}
121
+ disabled={isBusy}
122
+ />
123
+ }
124
+ >
125
+ <RotateCwIcon />
126
+ </TooltipTrigger>
127
+ <TooltipContent>
128
+ <p>Reset</p>
129
+ </TooltipContent>
130
+ </Tooltip>
131
+ </CardAction>
132
+ </CardHeader>
133
+ <CardContent className="flex-1 overflow-hidden p-0">
134
+ {messages.length === 0 ? (
135
+ <Empty className="h-full">
136
+ <EmptyHeader>
137
+ <EmptyMedia variant="icon">
138
+ <MessageCircleDashedIcon />
139
+ </EmptyMedia>
140
+ <EmptyTitle>Morning, shadcn!</EmptyTitle>
141
+ <EmptyDescription>
142
+ What are we working on today? Press send to start a new
143
+ conversation
144
+ </EmptyDescription>
145
+ </EmptyHeader>
146
+ </Empty>
147
+ ) : (
148
+ <MessageScroller>
149
+ <MessageScrollerViewport>
150
+ <MessageScrollerContent
151
+ aria-busy={isBusy}
152
+ className="p-(--card-spacing)"
153
+ >
154
+ {messages.map((message) => (
155
+ <MessageAnimated
156
+ key={message.id}
157
+ message={message}
158
+ scrollAnchor={message.role === "user"}
159
+ />
160
+ ))}
161
+ </MessageScrollerContent>
162
+ </MessageScrollerViewport>
163
+ <MessageScrollerButton />
164
+ </MessageScroller>
165
+ )}
166
+ </CardContent>
167
+ <CardFooter className="flex-col gap-2">
168
+ <form
169
+ onSubmit={(e) => {
170
+ e.preventDefault()
171
+ if (!nextMessage || isBusy) {
172
+ return
173
+ }
174
+ void sendMessage(nextMessage)
175
+ }}
176
+ className="w-full"
177
+ >
178
+ <InputGroup>
179
+ <div className="h-14 w-full px-3 py-2.5">
180
+ <span
181
+ className="line-clamp-2 opacity-60 data-[status=ready]:opacity-100"
182
+ data-status={status}
183
+ >
184
+ {nextMessage ? (
185
+ getMessageText(nextMessage)
186
+ ) : (
187
+ <span className="text-muted-foreground">
188
+ No messages queued. Reset the conversation.
189
+ </span>
190
+ )}
191
+ </span>
192
+ </div>
193
+ <InputGroupAddon align="block-end" className="pt-1">
194
+ <DropdownMenu>
195
+ <DropdownMenuTrigger
196
+ render={
197
+ <InputGroupButton
198
+ aria-label="Add files"
199
+ type="button"
200
+ size="icon-sm"
201
+ variant="outline"
202
+ />
203
+ }
204
+ >
205
+ <PlusIcon />
206
+ </DropdownMenuTrigger>
207
+ <DropdownMenuContent
208
+ align="start"
209
+ side="top"
210
+ className="w-44"
211
+ >
212
+ <DropdownMenuItem>
213
+ <PaperclipIcon />
214
+ Add Photos & Files
215
+ </DropdownMenuItem>
216
+ <DropdownMenuSeparator />
217
+ <DropdownMenuItem>
218
+ <ImageIcon />
219
+ Create Image
220
+ </DropdownMenuItem>
221
+ <DropdownMenuItem>
222
+ <TelescopeIcon />
223
+ Deep Research
224
+ </DropdownMenuItem>
225
+ <DropdownMenuItem>
226
+ <GlobeIcon />
227
+ Web Search
228
+ </DropdownMenuItem>
229
+ </DropdownMenuContent>
230
+ </DropdownMenu>
231
+ <InputGroupButton
232
+ type="submit"
233
+ variant="default"
234
+ size="icon-sm"
235
+ disabled={!nextMessage || isBusy}
236
+ className="ml-auto"
237
+ >
238
+ <ArrowUpIcon />
239
+ <span className="sr-only">Send</span>
240
+ </InputGroupButton>
241
+ </InputGroupAddon>
242
+ </InputGroup>
243
+ </form>
244
+ </CardFooter>
245
+ </Card>
246
+ <div className="px-0.5 text-center text-xs text-muted-foreground">
247
+ Demo is read only. Press send to send messages.
248
+ </div>
249
+ </div>
250
+ </MessageScrollerProvider>
251
+ )
252
+ }
253
+
254
+ ```
255
+
256
+ ## What Makes a Great Streaming Chat Experience
257
+
258
+ Building a chat interface used to be simple. You create an inverted list with
259
+ an input. Type a message, it appends at the bottom. When a reply comes in, the
260
+ list grows and scrolls. Done.
261
+
262
+ Streaming breaks that model. Messages arrive in chunks while you may still be
263
+ reading, scrolling, or looking somewhere else entirely.
264
+
265
+ Now the challenge is preserving the reader's place while the conversation keeps
266
+ changing. Get that wrong and the experience feels jumpy: people are pulled to
267
+ the bottom, lose context, and have to find their way back.
268
+
269
+ In practice, this comes down to scroll: when to follow, when to hold, and when
270
+ to let the reader decide. A great streaming chat should:
271
+
272
+ 1. **Move only when the reader asked to move.** If someone is reading, don’t pull them somewhere else. Auto-scroll should never be the default.
273
+ 2. **Follow only while they’re following.** If they’re at the live edge, keep the stream in view. If they scroll away, leave them there.
274
+ 3. **Every interaction is a signal.** Scrolling is not the only one. Selecting text, using the keyboard, opening a link, or searching should all stop the interface from moving.
275
+ 4. **Start a new turn near the top of the viewport.** This gives the new turn somewhere it can be read from the beginning.
276
+ 5. **Then stream in the answer.** The answer should grow into the screen, not immediately push everything away.
277
+ 6. **Keep part of the previous conversation in context.** The prompt and reply should stay visually connected, and enough of the previous turn should remain visible so the reader knows where they are.
278
+ 7. **Let new content arrive offscreen.** The conversation can keep streaming without changing what the reader is looking at.
279
+ 8. **Show what’s happening out of view.** Make it clear when a response is still streaming or when new messages have arrived.
280
+ 9. **Make it easy to return to the latest reply.** A “Jump to latest” action should bring the reader back and resume following.
281
+ 10. **Let people jump anywhere in the conversation.** Long threads need message links, search, unread markers, and direct navigation.
282
+ 11. **Reopen where the reader left off.** A saved conversation should open at the last meaningful turn. Often this is the last user message. Not the absolute bottom.
283
+ 12. **Keep the reader’s place when layout changes.** Images load. Markdown expands. Code blocks render. Older messages appear above. None of that should make the reader lose their place.
284
+ 13. **Handle interruptions without stealing position.** Stopping, retrying, regenerating, branching, or errors should not unexpectedly move the conversation.
285
+ 14. **Stay responsive in long threads.** Streaming text, markdown, code, images, and long history should still feel responsive.
286
+ 15. **Be accessible without the noise.** Keep the transcript navigable, preserve keyboard focus, and announce important events at a comfortable pace.
287
+
288
+ **Never move the reader against their intent.**
289
+
290
+ ## MessageScroller
291
+
292
+ MessageScroller is a chat transcript scroller built for these behaviors.
293
+ `MessageScrollerProvider` owns the scroll state and transcript-row behavior:
294
+ opening position, streamed output, new-turn anchoring, prepended history,
295
+ visibility, and scroll controls. `MessageScroller` is the styled frame that
296
+ renders inside it.
297
+
298
+ MessageScroller is scoped to the scroll viewport. It does not own messages, AI state,
299
+ transport, persistence, branching, or model state. Your product code stays
300
+ focused on composing messages, markers, tools, attachments, and prompt inputs.
301
+
302
+ It gives you the scroll behavior that chat needs, without taking over the rest
303
+ of the chat UI. And it stays fast, even in long conversations with rich
304
+ markdown.
305
+
306
+ ## Installation
307
+
308
+ <CodeTabs>
309
+
310
+ <TabsList>
311
+ <TabsTrigger value="cli">Command</TabsTrigger>
312
+ <TabsTrigger value="manual">Manual</TabsTrigger>
313
+ </TabsList>
314
+ <TabsContent value="cli">
315
+
316
+ ```bash
317
+ npx shadcn@latest add message-scroller
318
+ ```
319
+
320
+ </TabsContent>
321
+
322
+ <TabsContent value="manual">
323
+
324
+ <Steps className="mb-0 pt-2">
325
+
326
+ <Step>Install the following dependencies:</Step>
327
+
328
+ ```bash
329
+ npm install @shadcn/react
330
+ ```
331
+
332
+ <Step>Copy and paste the following code into your project.</Step>
333
+
334
+ <ComponentSource
335
+ name="message-scroller"
336
+ title="components/ui/message-scroller.tsx"
337
+ styleName="base-rhea"
338
+ />
339
+
340
+ <Step>Update the import paths to match your project setup.</Step>
341
+
342
+ </Steps>
343
+
344
+ </TabsContent>
345
+
346
+ </CodeTabs>
347
+
348
+ ## Usage
349
+
350
+ ```tsx
351
+ import { Message } from "@/components/ui/message"
352
+ import {
353
+ MessageScroller,
354
+ MessageScrollerButton,
355
+ MessageScrollerContent,
356
+ MessageScrollerItem,
357
+ MessageScrollerProvider,
358
+ MessageScrollerViewport,
359
+ } from "@/components/ui/message-scroller"
360
+ ```
361
+
362
+ ```tsx
363
+ <MessageScrollerProvider>
364
+ <MessageScroller>
365
+ <MessageScrollerViewport>
366
+ <MessageScrollerContent>
367
+ {messages.map((message) => (
368
+ <MessageScrollerItem
369
+ key={message.id}
370
+ messageId={message.id}
371
+ scrollAnchor={message.role === "user"}
372
+ >
373
+ <Message />
374
+ </MessageScrollerItem>
375
+ ))}
376
+ </MessageScrollerContent>
377
+ </MessageScrollerViewport>
378
+ <MessageScrollerButton />
379
+ </MessageScroller>
380
+ </MessageScrollerProvider>
381
+ ```
382
+
383
+ `MessageScroller` fills its parent, so place it inside a height-constrained
384
+ container.
385
+
386
+ ```tsx
387
+ <div className="flex h-screen flex-col">
388
+ <MessageScrollerProvider>
389
+ <MessageScroller className="flex-1">{/* transcript */}</MessageScroller>
390
+ </MessageScrollerProvider>
391
+ </div>
392
+ ```
393
+
394
+ ## Composition
395
+
396
+ ```tsx
397
+ <MessageScrollerProvider>
398
+ <MessageScroller>
399
+ <MessageScrollerViewport>
400
+ <MessageScrollerContent>
401
+ <MessageScrollerItem>
402
+ {/* a message, marker, or row */}
403
+ </MessageScrollerItem>
404
+ <MessageScrollerItem />
405
+ <MessageScrollerItem />
406
+ </MessageScrollerContent>
407
+ </MessageScrollerViewport>
408
+ <MessageScrollerButton />
409
+ </MessageScroller>
410
+ </MessageScrollerProvider>
411
+ ```
412
+
413
+ - **`MessageScrollerProvider`** — the headless root. Owns scroll state and the
414
+ behavior props for opening position, auto-scroll, anchoring, scroll commands,
415
+ and visibility tracking.
416
+ - **`MessageScroller`** — the styled frame. Lays out the viewport, content, and
417
+ controls inside the provider.
418
+ - **`MessageScrollerViewport`** — the scrollable element. Receives native scroll
419
+ events and preserves the visible row when older messages are prepended.
420
+ - **`MessageScrollerContent`** — the transcript container. Holds the rows and
421
+ provides the live-region defaults for new messages.
422
+ - **`MessageScrollerItem`** — the transcript row boundary. Wrap every direct
423
+ child of the content so the scroller can measure, anchor, preserve position,
424
+ track visibility, and jump to it. An item can be a message, marker, typing
425
+ indicator, separator, join/leave event, or "load earlier" row.
426
+ - **`MessageScrollerButton`** — the scroll control. Scrolls to the start or end of the transcript and is inert until there is content in its direction.
427
+
428
+ ## Core Concepts
429
+
430
+ ### Anchoring Turns
431
+
432
+ A turn is the part of the conversation that starts a new exchange. In a simple
433
+ AI chat, that is usually the user's message and the assistant reply that follows.
434
+
435
+ An anchor is the row the viewport should treat as the start of that turn. Mark
436
+ that row with `scrollAnchor`. When a new anchor is appended, the viewport moves
437
+ it near the top and keeps a peek of the previous item above it, so the new turn
438
+ does not feel detached from its context.
439
+
440
+ ```tsx
441
+ // This tells the scroller to anchor the user's message for the next turn.
442
+ <MessageScrollerItem
443
+ messageId={message.id}
444
+ scrollAnchor={message.role === "user"}
445
+ />
446
+ ```
447
+
448
+ Scroll anchors are not tied to message role. You can turn any row into an anchor:
449
+ a user message, a system marker, a handoff event, or anything else that starts a
450
+ meaningful turn. `MessageScroller` only needs to know which row should anchor the
451
+ viewport.
452
+
453
+ In the following example, the user's message is anchored. When you send a new message, the viewport anchors it near the top and appends the assistant reply below it. Toggle the anchor to the assistant's message to see the difference.
454
+
455
+ ```tsx
456
+ "use client"
457
+
458
+ import * as React from "react"
459
+ import {
460
+ ArrowUpIcon,
461
+ MessageCircleDashedIcon,
462
+ RotateCwIcon,
463
+ } from "lucide-react"
464
+
465
+ import { MessageAnimated } from "@/components/message-animated"
466
+ import { Button } from "@/components/ui/button"
467
+ import {
468
+ Card,
469
+ CardAction,
470
+ CardContent,
471
+ CardDescription,
472
+ CardFooter,
473
+ CardHeader,
474
+ CardTitle,
475
+ } from "@/components/ui/card"
476
+ import {
477
+ Empty,
478
+ EmptyDescription,
479
+ EmptyHeader,
480
+ EmptyMedia,
481
+ EmptyTitle,
482
+ } from "@/components/ui/empty"
483
+ import {
484
+ MessageScroller,
485
+ MessageScrollerButton,
486
+ MessageScrollerContent,
487
+ MessageScrollerProvider,
488
+ MessageScrollerViewport,
489
+ } from "@/components/ui/message-scroller"
490
+ import {
491
+ ToggleGroup,
492
+ ToggleGroupItem,
493
+ } from "@/components/ui/toggle-group"
494
+
495
+ type AnchorRole = "user" | "assistant"
496
+
497
+ type ChatMessage = {
498
+ id: string
499
+ role: AnchorRole
500
+ text: string
501
+ }
502
+
503
+ const scriptedMessages: ChatMessage[] = [
504
+ {
505
+ id: "anchor-1-user",
506
+ role: "user",
507
+ text: "Can you show me how anchoring behaves when a new prompt starts the turn?",
508
+ },
509
+ {
510
+ id: "anchor-1-assistant",
511
+ role: "assistant",
512
+ text: "Append the user prompt first, then append the assistant response. With User selected, the prompt settles near the top and the assistant response fills in below it.",
513
+ },
514
+ {
515
+ id: "anchor-2-user",
516
+ role: "user",
517
+ text: "What changes when assistant messages are the anchor?",
518
+ },
519
+ {
520
+ id: "anchor-2-assistant",
521
+ role: "assistant",
522
+ text: "Now each assistant response is the item `MessageScroller` keeps in view. This is useful when the reply is the moment you want readers to land on after each turn.",
523
+ },
524
+ {
525
+ id: "anchor-3-user",
526
+ role: "user",
527
+ text: "Can I switch roles and keep adding turns?",
528
+ },
529
+ {
530
+ id: "anchor-3-assistant",
531
+ role: "assistant",
532
+ text: "Yes. The next appended message with the selected role becomes the anchor, so you can compare user and assistant anchoring without resetting the demo.",
533
+ },
534
+ ]
535
+
536
+ export function MessageScrollerAnchoring() {
537
+ const [anchorRole, setAnchorRole] = React.useState<AnchorRole>("user")
538
+ const [messages, setMessages] = React.useState<ChatMessage[]>([])
539
+ const [messageIndex, setMessageIndex] = React.useState(0)
540
+ const nextMessage = scriptedMessages[messageIndex]
541
+
542
+ return (
543
+ <div className="relative flex flex-col gap-4">
544
+ <Card className="mx-auto h-140 w-full max-w-sm gap-0">
545
+ <CardHeader className="border-b">
546
+ <CardTitle>Anchoring Turns</CardTitle>
547
+ <CardDescription>
548
+ Choose which role settles near the top edge.
549
+ </CardDescription>
550
+ <CardAction>
551
+ <Button
552
+ type="button"
553
+ variant="outline"
554
+ size="icon"
555
+ aria-label="Reset anchored turns"
556
+ disabled={messages.length === 0}
557
+ onClick={() => {
558
+ setMessages([])
559
+ setMessageIndex(0)
560
+ }}
561
+ >
562
+ <RotateCwIcon />
563
+ </Button>
564
+ </CardAction>
565
+ </CardHeader>
566
+ <CardContent className="min-h-0 flex-1 overflow-hidden p-0">
567
+ {messages.length === 0 ? (
568
+ <Empty className="h-full">
569
+ <EmptyHeader>
570
+ <EmptyMedia variant="icon">
571
+ <MessageCircleDashedIcon />
572
+ </EmptyMedia>
573
+ <EmptyTitle>No anchored messages yet</EmptyTitle>
574
+ <EmptyDescription>
575
+ Send the first message to see the selected role anchor.
576
+ </EmptyDescription>
577
+ </EmptyHeader>
578
+ </Empty>
579
+ ) : (
580
+ <MessageScrollerProvider>
581
+ <MessageScroller>
582
+ <MessageScrollerViewport>
583
+ <MessageScrollerContent className="p-(--card-spacing)">
584
+ {messages.map((message) => (
585
+ <MessageAnimated
586
+ key={message.id}
587
+ message={message}
588
+ scrollAnchor={message.role === anchorRole}
589
+ userVariant="muted"
590
+ assistantVariant="ghost"
591
+ />
592
+ ))}
593
+ </MessageScrollerContent>
594
+ </MessageScrollerViewport>
595
+ <MessageScrollerButton />
596
+ </MessageScroller>
597
+ </MessageScrollerProvider>
598
+ )}
599
+ </CardContent>
600
+ <CardFooter>
601
+ <ToggleGroup
602
+ aria-label="Select scroll anchor role"
603
+ value={[anchorRole]}
604
+ onValueChange={(value) => {
605
+ const nextValue = value[0]
606
+
607
+ if (nextValue === "user" || nextValue === "assistant") {
608
+ setAnchorRole(nextValue)
609
+ setMessages([])
610
+ setMessageIndex(0)
611
+ }
612
+ }}
613
+ >
614
+ <ToggleGroupItem value="user" aria-label="Anchor user messages">
615
+ User
616
+ </ToggleGroupItem>
617
+ <ToggleGroupItem
618
+ value="assistant"
619
+ aria-label="Anchor assistant messages"
620
+ >
621
+ Assistant
622
+ </ToggleGroupItem>
623
+ </ToggleGroup>
624
+ <Button
625
+ type="button"
626
+ size="icon"
627
+ className="ml-auto"
628
+ disabled={!nextMessage}
629
+ onClick={() => {
630
+ if (!nextMessage) {
631
+ return
632
+ }
633
+
634
+ setMessages((messages) => [...messages, nextMessage])
635
+ setMessageIndex((index) => index + 1)
636
+ }}
637
+ >
638
+ <ArrowUpIcon />
639
+ <span className="sr-only">Send Message</span>
640
+ </Button>
641
+ </CardFooter>
642
+ </Card>
643
+ <div className="mx-auto max-w-xs px-0.5 text-center text-xs text-muted-foreground">
644
+ Toggle the anchor role, then send messages to compare where turns
645
+ settle.
646
+ </div>
647
+ </div>
648
+ )
649
+ }
650
+
651
+ ```
652
+
653
+ ### Group Chat
654
+
655
+ In a group chat, the turn boundary is more specific than "the user message". It is often
656
+ the message that asks the model to respond, or a marker like "Marcus joined the
657
+ chat". Typing indicators and history controls usually should not anchor.
658
+
659
+ Because anchoring is role-independent, you can anchor a marker just as easily as
660
+ a message.
661
+
662
+ ```tsx
663
+ <MessageScrollerItem messageId="marcus-joined" scrollAnchor>
664
+ <Marker variant="separator">
665
+ <MarkerContent>Marcus joined the chat</MarkerContent>
666
+ </Marker>
667
+ </MessageScrollerItem>
668
+ ```
669
+
670
+ ```tsx
671
+ "use client"
672
+
673
+ import * as React from "react"
674
+ import { RotateCwIcon } from "lucide-react"
675
+
676
+ import { Bubble, BubbleContent } from "@/components/ui/bubble"
677
+ import { Button } from "@/components/ui/button"
678
+ import {
679
+ Card,
680
+ CardAction,
681
+ CardContent,
682
+ CardDescription,
683
+ CardFooter,
684
+ CardHeader,
685
+ CardTitle,
686
+ } from "@/components/ui/card"
687
+ import { Marker, MarkerContent } from "@/components/ui/marker"
688
+ import {
689
+ Message,
690
+ MessageContent,
691
+ MessageHeader,
692
+ } from "@/components/ui/message"
693
+ import {
694
+ MessageScroller,
695
+ MessageScrollerButton,
696
+ MessageScrollerContent,
697
+ MessageScrollerItem,
698
+ MessageScrollerProvider,
699
+ MessageScrollerViewport,
700
+ } from "@/components/ui/message-scroller"
701
+ import {
702
+ Tooltip,
703
+ TooltipContent,
704
+ TooltipTrigger,
705
+ } from "@/components/ui/tooltip"
706
+
707
+ const currentUser = "Grace"
708
+
709
+ const initialItems = [
710
+ {
711
+ id: "group-1",
712
+ type: "message",
713
+ sender: "Grace",
714
+ role: "participant",
715
+ text: "@mary, the astrophage line keeps matching Venus energy output. Can you check my math?",
716
+ },
717
+ {
718
+ id: "group-2",
719
+ type: "message",
720
+ sender: "Mary (Agent)",
721
+ role: "assistant",
722
+ text: "Yes. Confirmed. The curve points to a microorganism harvesting stellar energy and breeding near carbon dioxide. If @rocky agrees, this is the clue we need.",
723
+ },
724
+ {
725
+ id: "group-3",
726
+ type: "message",
727
+ sender: "Grace",
728
+ role: "participant",
729
+ text: "ping @rocky",
730
+ scrollAnchor: true,
731
+ },
732
+ ] satisfies GroupChatItem[]
733
+
734
+ const rockyMarker = {
735
+ id: "group-4",
736
+ type: "event",
737
+ text: "Rocky has joined the chat",
738
+ scrollAnchor: true,
739
+ } satisfies GroupChatItem
740
+
741
+ const rockyMessage = {
742
+ id: "group-5",
743
+ type: "message",
744
+ sender: "Rocky",
745
+ role: "participant",
746
+ text: "Amaze. Astrophage eats light, makes heat, goes to carbon dioxide. Rocky has fuel model. Grace is smart.",
747
+ } satisfies GroupChatItem
748
+
749
+ type GroupChatItem =
750
+ | {
751
+ id: string
752
+ type: "event"
753
+ text: string
754
+ scrollAnchor?: boolean
755
+ }
756
+ | {
757
+ id: string
758
+ type: "message"
759
+ sender: string
760
+ role: "assistant" | "participant"
761
+ text: string
762
+ scrollAnchor?: boolean
763
+ }
764
+
765
+ export function MessageScrollerGroupChat() {
766
+ const [demoKey, setDemoKey] = React.useState(0)
767
+ const [rockyTurn, setRockyTurn] = React.useState<
768
+ "idle" | "marker" | "message"
769
+ >("idle")
770
+ const items =
771
+ rockyTurn === "message"
772
+ ? [...initialItems, rockyMarker, rockyMessage]
773
+ : rockyTurn === "marker"
774
+ ? [...initialItems, rockyMarker]
775
+ : initialItems
776
+ const buttonLabel =
777
+ rockyTurn === "idle" ? "Add Rocky" : "Send Message as Rocky"
778
+ const isComplete = rockyTurn === "message"
779
+
780
+ return (
781
+ <MessageScrollerProvider>
782
+ <div className="relative flex flex-col gap-4">
783
+ <Card className="mx-auto h-140 w-full max-w-sm gap-0">
784
+ <CardHeader className="gap-1 border-b">
785
+ <CardTitle>Group Chat</CardTitle>
786
+ <CardDescription>
787
+ A group chat with several participants and an assistant. The
788
+ Marker is marked as a turn.
789
+ </CardDescription>
790
+ <CardAction>
791
+ <Tooltip>
792
+ <TooltipTrigger
793
+ render={
794
+ <Button
795
+ type="button"
796
+ variant="outline"
797
+ size="icon"
798
+ aria-label="Reset conversation"
799
+ disabled={rockyTurn === "idle"}
800
+ onClick={() => {
801
+ setRockyTurn("idle")
802
+ setDemoKey((key) => key + 1)
803
+ }}
804
+ />
805
+ }
806
+ >
807
+ <RotateCwIcon />
808
+ </TooltipTrigger>
809
+ <TooltipContent>
810
+ <p>Reset</p>
811
+ </TooltipContent>
812
+ </Tooltip>
813
+ </CardAction>
814
+ </CardHeader>
815
+ <CardContent className="min-h-0 flex-1 p-0">
816
+ <MessageScrollerProvider>
817
+ <MessageScroller key={demoKey}>
818
+ <MessageScrollerViewport>
819
+ <MessageScrollerContent className="p-(--card-spacing)">
820
+ {items.map((item) =>
821
+ item.type === "message" ? (
822
+ <GroupChatMessage key={item.id} item={item} />
823
+ ) : (
824
+ <GroupChatMarker
825
+ key={item.id}
826
+ item={item}
827
+ scrollAnchor={item.scrollAnchor}
828
+ />
829
+ )
830
+ )}
831
+ </MessageScrollerContent>
832
+ </MessageScrollerViewport>
833
+ <MessageScrollerButton />
834
+ </MessageScroller>
835
+ </MessageScrollerProvider>
836
+ </CardContent>
837
+ <CardFooter className="flex flex-col items-center gap-2 border-t">
838
+ <Button
839
+ type="button"
840
+ disabled={isComplete}
841
+ onClick={() =>
842
+ setRockyTurn((turn) => (turn === "idle" ? "marker" : "message"))
843
+ }
844
+ className="w-full"
845
+ variant="secondary"
846
+ >
847
+ {buttonLabel}
848
+ </Button>
849
+ <p className="text-xs text-muted-foreground">
850
+ {rockyTurn === "idle"
851
+ ? "This will create a marker and make it the anchor"
852
+ : "Now send Rocky's reply into the conversation"}
853
+ </p>
854
+ </CardFooter>
855
+ </Card>
856
+ <div className="mx-auto max-w-sm px-0.5 text-center text-xs text-balance text-muted-foreground">
857
+ When a user joins, a marker is created. scrollAnchor on the marker
858
+ marks it as the next turn
859
+ </div>
860
+ </div>
861
+ </MessageScrollerProvider>
862
+ )
863
+ }
864
+
865
+ function GroupChatMessage({
866
+ item,
867
+ }: {
868
+ item: Extract<GroupChatItem, { type: "message" }>
869
+ }) {
870
+ const isCurrentUser = item.sender === currentUser
871
+ const variant = isCurrentUser
872
+ ? "muted"
873
+ : item.role === "assistant"
874
+ ? "ghost"
875
+ : "tinted"
876
+
877
+ return (
878
+ <MessageScrollerItem messageId={item.id} scrollAnchor={item.scrollAnchor}>
879
+ <Message align={isCurrentUser ? "end" : "start"}>
880
+ <MessageContent>
881
+ {!isCurrentUser && <MessageHeader>{item.sender}</MessageHeader>}
882
+ <Bubble variant={variant}>
883
+ <BubbleContent>{item.text}</BubbleContent>
884
+ </Bubble>
885
+ </MessageContent>
886
+ </Message>
887
+ </MessageScrollerItem>
888
+ )
889
+ }
890
+
891
+ function GroupChatMarker({
892
+ item,
893
+ scrollAnchor = false,
894
+ }: {
895
+ item: Extract<GroupChatItem, { type: "event" }>
896
+ scrollAnchor?: boolean
897
+ }) {
898
+ return (
899
+ <MessageScrollerItem scrollAnchor={scrollAnchor}>
900
+ <Marker variant="separator">
901
+ <MarkerContent>{item.text}</MarkerContent>
902
+ </Marker>
903
+ </MessageScrollerItem>
904
+ )
905
+ }
906
+
907
+ ```
908
+
909
+ ### Keeping Context Visible
910
+
911
+ When a new turn starts, it should still feel like part of the same continuous
912
+ thread. `scrollPreviousItemPeek` keeps a slice of the previous item visible
913
+ above the anchor, so the reader keeps their context instead of feeling like the
914
+ conversation restarted on a blank page.
915
+
916
+ ```tsx
917
+ // Keep 64px of the previous turn visible above the newly anchored row.
918
+ <MessageScrollerProvider scrollPreviousItemPeek={64}>
919
+ <MessageScroller>{/* anchored turns */}</MessageScroller>
920
+ </MessageScrollerProvider>
921
+ ```
922
+
923
+ Adjust the peek amount in the example below to see how it affects the conversation.
924
+
925
+ ```tsx
926
+ "use client"
927
+
928
+ import * as React from "react"
929
+ import { useChat } from "@ai-sdk/react"
930
+ import {
931
+ ArrowUpIcon,
932
+ GlobeIcon,
933
+ ImageIcon,
934
+ PaperclipIcon,
935
+ PlusIcon,
936
+ RotateCwIcon,
937
+ TelescopeIcon,
938
+ } from "lucide-react"
939
+
940
+ import { createChat, getMessageText } from "@/lib/ai"
941
+ import { MessageAnimated } from "@/components/message-animated"
942
+ import { Button } from "@/components/ui/button"
943
+ import {
944
+ Card,
945
+ CardAction,
946
+ CardContent,
947
+ CardDescription,
948
+ CardFooter,
949
+ CardHeader,
950
+ CardTitle,
951
+ } from "@/components/ui/card"
952
+ import {
953
+ DropdownMenu,
954
+ DropdownMenuContent,
955
+ DropdownMenuItem,
956
+ DropdownMenuSeparator,
957
+ DropdownMenuTrigger,
958
+ } from "@/components/ui/dropdown-menu"
959
+ import {
960
+ InputGroup,
961
+ InputGroupAddon,
962
+ InputGroupButton,
963
+ } from "@/components/ui/input-group"
964
+ import {
965
+ MessageScroller,
966
+ MessageScrollerButton,
967
+ MessageScrollerContent,
968
+ MessageScrollerProvider,
969
+ MessageScrollerViewport,
970
+ } from "@/components/ui/message-scroller"
971
+ import { Slider } from "@/components/ui/slider"
972
+ import {
973
+ Tooltip,
974
+ TooltipContent,
975
+ TooltipTrigger,
976
+ } from "@/components/ui/tooltip"
977
+
978
+ const DEFAULT_PEEK = 64
979
+
980
+ const chat = createChat()
981
+ .user(
982
+ "I'm building a chat for our app and the scroll behavior is driving me nuts. Every time the AI streams a reply, the whole thread jumps around."
983
+ )
984
+ .sleep(1000)
985
+ .assistant(
986
+ "That's the classic streaming scroll problem. Wrap your message list in `MessageScroller` and turn on `autoScroll` — the viewport pins to the bottom as tokens arrive, so users always see the latest text land in place.\n\nThe important part: it only auto-scrolls while the reader is already at the bottom. The moment they scroll up to read something earlier, auto-scroll backs off and their position is preserved. You get smooth streaming without fighting the user's intent."
987
+ )
988
+ .user(
989
+ "Okay, but when someone sends a new message the view still feels jarring — like the whole conversation reloads from the top."
990
+ )
991
+ .sleep(1000)
992
+ .assistant(
993
+ "MessageScrollerItem fixes that with turn anchoring. Set `scrollAnchor` on the turn that should settle near the top instead of blindly snapping to the document bottom.\n\nIt also leaves a small peek of the previous exchange visible above the anchor, so context isn't lost. The reply starts in view without that disorienting jump you get from a plain overflow container."
994
+ )
995
+ .user(
996
+ "And if they've scrolled up to re-read an older answer? I don't want to yank them back down."
997
+ )
998
+ .sleep(1000)
999
+ .assistant(
1000
+ "You won't. Auto-scroll only runs when the viewport is already pinned to the bottom, so scrolling up is a deliberate opt-out — their place in the thread stays put even as new tokens keep arriving below.\n\nWhen there is content they haven't seen yet, `MessageScrollerButton` appears at the bottom of the viewport. One tap jumps them back to the newest message and re-engages auto-scroll. Same pattern as Slack or iMessage: quiet when you're caught up, helpful when you're not."
1001
+ )
1002
+ .user("Last one — does this work with assistive tech?")
1003
+ .sleep(1000)
1004
+ .assistant(
1005
+ '`MessageScrollerContent` sets `role="log"` and `aria-relevant="additions"` by default, so screen readers announce new messages as they stream in.\n\nThe scroll button is a real `<button>` with an sr-only label, and it\'s removed from the tab order when you\'re already at the bottom — no ghost focus stops.'
1006
+ )
1007
+ const initialMessages = chat.get(2)
1008
+ const transport = chat.transport({ delayMs: 35 })
1009
+
1010
+ export function MessageScrollerPreviousContext() {
1011
+ const [demoKey, setDemoKey] = React.useState(0)
1012
+ const [peek, setPeek] = React.useState(DEFAULT_PEEK)
1013
+ const { messages, sendMessage, setMessages, status } = useChat({
1014
+ messages: initialMessages,
1015
+ transport,
1016
+ })
1017
+ const nextMessage = chat.next(messages)
1018
+ const isBusy = status === "submitted" || status === "streaming"
1019
+
1020
+ return (
1021
+ <MessageScrollerProvider
1022
+ key={demoKey}
1023
+ scrollMargin={24}
1024
+ scrollPreviousItemPeek={peek}
1025
+ >
1026
+ <div className="relative flex flex-col gap-4">
1027
+ <Card className="mx-auto h-140 w-full max-w-sm gap-0">
1028
+ <CardHeader className="gap-1 border-b">
1029
+ <CardTitle>Keeping Context Visible</CardTitle>
1030
+ <CardDescription>
1031
+ New turns keep part of the previous reply in view.
1032
+ </CardDescription>
1033
+ <CardAction>
1034
+ <Tooltip>
1035
+ <TooltipTrigger
1036
+ render={
1037
+ <Button
1038
+ variant="outline"
1039
+ size="icon"
1040
+ aria-label="Reset context example"
1041
+ disabled={isBusy}
1042
+ onClick={() => {
1043
+ setMessages(initialMessages)
1044
+ setPeek(DEFAULT_PEEK)
1045
+ setDemoKey((key) => key + 1)
1046
+ }}
1047
+ />
1048
+ }
1049
+ >
1050
+ <RotateCwIcon />
1051
+ </TooltipTrigger>
1052
+ <TooltipContent>
1053
+ <p>Reset</p>
1054
+ </TooltipContent>
1055
+ </Tooltip>
1056
+ </CardAction>
1057
+ </CardHeader>
1058
+ <CardContent className="flex-1 overflow-hidden p-0">
1059
+ <MessageScroller>
1060
+ <MessageScrollerViewport>
1061
+ <MessageScrollerContent
1062
+ aria-busy={isBusy}
1063
+ className="p-(--card-spacing)"
1064
+ >
1065
+ {messages.map((message) => (
1066
+ <MessageAnimated
1067
+ key={message.id}
1068
+ message={message}
1069
+ scrollAnchor={message.role === "user"}
1070
+ />
1071
+ ))}
1072
+ </MessageScrollerContent>
1073
+ </MessageScrollerViewport>
1074
+ <MessageScrollerButton />
1075
+ </MessageScroller>
1076
+ </CardContent>
1077
+ <CardFooter className="flex-col gap-2">
1078
+ <form
1079
+ onSubmit={(e) => {
1080
+ e.preventDefault()
1081
+ if (!nextMessage || isBusy) {
1082
+ return
1083
+ }
1084
+ void sendMessage(nextMessage)
1085
+ }}
1086
+ className="w-full"
1087
+ >
1088
+ <InputGroup>
1089
+ <div className="h-14 w-full px-3 py-2.5">
1090
+ <span
1091
+ className="line-clamp-2 opacity-60 data-[status=ready]:opacity-100"
1092
+ data-status={status}
1093
+ >
1094
+ {nextMessage ? (
1095
+ getMessageText(nextMessage)
1096
+ ) : (
1097
+ <span className="text-muted-foreground">
1098
+ No messages queued. Reset the context.
1099
+ </span>
1100
+ )}
1101
+ </span>
1102
+ </div>
1103
+ <InputGroupAddon align="block-end" className="pt-1">
1104
+ <DropdownMenu>
1105
+ <DropdownMenuTrigger
1106
+ render={
1107
+ <InputGroupButton
1108
+ aria-label="Add files"
1109
+ type="button"
1110
+ size="icon-sm"
1111
+ variant="outline"
1112
+ />
1113
+ }
1114
+ >
1115
+ <PlusIcon />
1116
+ </DropdownMenuTrigger>
1117
+ <DropdownMenuContent
1118
+ align="start"
1119
+ side="top"
1120
+ className="w-44"
1121
+ >
1122
+ <DropdownMenuItem>
1123
+ <PaperclipIcon />
1124
+ Add Photos & Files
1125
+ </DropdownMenuItem>
1126
+ <DropdownMenuSeparator />
1127
+ <DropdownMenuItem>
1128
+ <ImageIcon />
1129
+ Create Image
1130
+ </DropdownMenuItem>
1131
+ <DropdownMenuItem>
1132
+ <TelescopeIcon />
1133
+ Deep Research
1134
+ </DropdownMenuItem>
1135
+ <DropdownMenuItem>
1136
+ <GlobeIcon />
1137
+ Web Search
1138
+ </DropdownMenuItem>
1139
+ </DropdownMenuContent>
1140
+ </DropdownMenu>
1141
+ <div className="flex w-28 items-center gap-2">
1142
+ <span className="text-xs text-muted-foreground tabular-nums">
1143
+ {peek}px
1144
+ </span>
1145
+ <Slider
1146
+ aria-label="Previous context peek"
1147
+ value={[peek]}
1148
+ min={64}
1149
+ max={128}
1150
+ step={1}
1151
+ disabled={isBusy}
1152
+ onValueChange={(value) => {
1153
+ const nextValue = Array.isArray(value)
1154
+ ? value[0]
1155
+ : value
1156
+
1157
+ setPeek(nextValue ?? DEFAULT_PEEK)
1158
+ }}
1159
+ />
1160
+ </div>
1161
+ <InputGroupButton
1162
+ type="submit"
1163
+ variant="default"
1164
+ size="icon-sm"
1165
+ disabled={!nextMessage || isBusy}
1166
+ className="ml-auto"
1167
+ >
1168
+ <ArrowUpIcon />
1169
+ <span className="sr-only">Send</span>
1170
+ </InputGroupButton>
1171
+ </InputGroupAddon>
1172
+ </InputGroup>
1173
+ </form>
1174
+ </CardFooter>
1175
+ </Card>
1176
+ <div className="px-0.5 text-center text-xs text-muted-foreground">
1177
+ Adjust the slider and send. Observe the previous message peak
1178
+ </div>
1179
+ </div>
1180
+ </MessageScrollerProvider>
1181
+ )
1182
+ }
1183
+
1184
+ ```
1185
+
1186
+ ### Following the Live Edge
1187
+
1188
+ When the reader is at the live edge, either because they stayed there or
1189
+ returned there, `autoScroll` keeps streamed replies in view as they grow.
1190
+ Scrolling away from the live edge releases the view, whether by wheel, touch,
1191
+ keyboard scroll keys, or dragging the scrollbar. An explicit message jump
1192
+ releases it too. New chunks can then arrive without moving the reader.
1193
+
1194
+ `autoScroll` composes with turn anchoring. When a new turn anchors near the
1195
+ top, the view stays put while the reply streams into the room below it. Once
1196
+ the reply fills the viewport, the reader is back at the live edge and
1197
+ follow-output takes over from the anchor.
1198
+
1199
+ ```tsx
1200
+ <MessageScrollerProvider autoScroll>
1201
+ <MessageScroller>{/* streamed turns */}</MessageScroller>
1202
+ </MessageScrollerProvider>
1203
+ ```
1204
+
1205
+ ```tsx
1206
+ "use client"
1207
+
1208
+ import { useChat } from "@ai-sdk/react"
1209
+ import {
1210
+ ArrowUpIcon,
1211
+ GlobeIcon,
1212
+ ImageIcon,
1213
+ MessageCircleDashedIcon,
1214
+ PaperclipIcon,
1215
+ PlusIcon,
1216
+ RotateCwIcon,
1217
+ TelescopeIcon,
1218
+ } from "lucide-react"
1219
+
1220
+ import { createChat, getMessageText } from "@/lib/ai"
1221
+ import { MessageAnimated } from "@/components/message-animated"
1222
+ import { Button } from "@/components/ui/button"
1223
+ import {
1224
+ Card,
1225
+ CardAction,
1226
+ CardContent,
1227
+ CardDescription,
1228
+ CardFooter,
1229
+ CardHeader,
1230
+ CardTitle,
1231
+ } from "@/components/ui/card"
1232
+ import {
1233
+ DropdownMenu,
1234
+ DropdownMenuContent,
1235
+ DropdownMenuItem,
1236
+ DropdownMenuSeparator,
1237
+ DropdownMenuTrigger,
1238
+ } from "@/components/ui/dropdown-menu"
1239
+ import {
1240
+ Empty,
1241
+ EmptyDescription,
1242
+ EmptyHeader,
1243
+ EmptyMedia,
1244
+ EmptyTitle,
1245
+ } from "@/components/ui/empty"
1246
+ import {
1247
+ InputGroup,
1248
+ InputGroupAddon,
1249
+ InputGroupButton,
1250
+ } from "@/components/ui/input-group"
1251
+ import {
1252
+ MessageScroller,
1253
+ MessageScrollerButton,
1254
+ MessageScrollerContent,
1255
+ MessageScrollerProvider,
1256
+ MessageScrollerViewport,
1257
+ } from "@/components/ui/message-scroller"
1258
+ import {
1259
+ Tooltip,
1260
+ TooltipContent,
1261
+ TooltipTrigger,
1262
+ } from "@/components/ui/tooltip"
1263
+
1264
+ const chat = createChat()
1265
+ .user(
1266
+ "I'm building a chat for our app and the scroll behavior is driving me nuts. Every time the AI streams a reply, the whole thread jumps around."
1267
+ )
1268
+ .sleep(1000)
1269
+ .assistant(
1270
+ "That's the classic streaming scroll problem. Wrap your message list in `MessageScroller` and turn on `autoScroll` — the viewport pins to the bottom as tokens arrive, so users always see the latest text land in place.\n\nThe important part: it only auto-scrolls while the reader is already at the bottom. The moment they scroll up to read something earlier, auto-scroll backs off and their position is preserved. You get smooth streaming without fighting the user's intent."
1271
+ )
1272
+ .user(
1273
+ "Okay, but when someone sends a new message the view still feels jarring — like the whole conversation reloads from the top."
1274
+ )
1275
+ .sleep(1000)
1276
+ .assistant(
1277
+ "MessageScrollerItem fixes that with turn anchoring. Set `scrollAnchor` on the turn that should settle near the top instead of blindly snapping to the document bottom.\n\nIt also leaves a small peek of the previous exchange visible above the anchor, so context isn't lost. The reply starts in view without that disorienting jump you get from a plain overflow container."
1278
+ )
1279
+ .user(
1280
+ "And if they've scrolled up to re-read an older answer? I don't want to yank them back down."
1281
+ )
1282
+ .sleep(1000)
1283
+ .assistant(
1284
+ "You won't. Auto-scroll only runs when the viewport is already pinned to the bottom, so scrolling up is a deliberate opt-out — their place in the thread stays put even as new tokens keep arriving below.\n\nWhen there is content they haven't seen yet, `MessageScrollerButton` appears at the bottom of the viewport. One tap jumps them back to the newest message and re-engages auto-scroll. Same pattern as Slack or iMessage: quiet when you're caught up, helpful when you're not."
1285
+ )
1286
+ .user("Last one — does this work with assistive tech?")
1287
+ .sleep(1000)
1288
+ .assistant(
1289
+ '`MessageScrollerContent` sets `role="log"` and `aria-relevant="additions"` by default, so screen readers announce new messages as they stream in.\n\nThe scroll button is a real `<button>` with an sr-only label, and it\'s removed from the tab order when you\'re already at the bottom — no ghost focus stops.'
1290
+ )
1291
+ const initialMessages = chat.get(0)
1292
+ const transport = chat.transport({ delayMs: 20 })
1293
+
1294
+ export function MessageScrollerStreaming() {
1295
+ const { messages, sendMessage, setMessages, status } = useChat({
1296
+ messages: initialMessages,
1297
+ transport,
1298
+ })
1299
+ const nextMessage = chat.next(messages)
1300
+ const isBusy = status === "submitted" || status === "streaming"
1301
+
1302
+ return (
1303
+ <MessageScrollerProvider autoScroll>
1304
+ <div className="relative flex flex-col gap-4">
1305
+ <Card className="mx-auto h-140 w-full max-w-sm gap-0">
1306
+ <CardHeader className="gap-1 border-b">
1307
+ <CardTitle>Streaming Messages</CardTitle>
1308
+ <CardDescription>
1309
+ Auto-scroll follows the live edge of the conversation.
1310
+ </CardDescription>
1311
+ <CardAction>
1312
+ <Tooltip>
1313
+ <TooltipTrigger
1314
+ render={
1315
+ <Button
1316
+ variant="outline"
1317
+ size="icon"
1318
+ aria-label="Reset stream"
1319
+ onClick={() => setMessages(initialMessages)}
1320
+ disabled={messages.length === 0 || isBusy}
1321
+ />
1322
+ }
1323
+ >
1324
+ <RotateCwIcon />
1325
+ </TooltipTrigger>
1326
+ <TooltipContent>
1327
+ <p>Reset</p>
1328
+ </TooltipContent>
1329
+ </Tooltip>
1330
+ </CardAction>
1331
+ </CardHeader>
1332
+ <CardContent className="flex-1 overflow-hidden p-0">
1333
+ {messages.length === 0 ? (
1334
+ <Empty className="h-full">
1335
+ <EmptyHeader>
1336
+ <EmptyMedia variant="icon">
1337
+ <MessageCircleDashedIcon />
1338
+ </EmptyMedia>
1339
+ <EmptyTitle>Ready to Stream</EmptyTitle>
1340
+ <EmptyDescription>
1341
+ Press send to stream a scripted launch summary.
1342
+ </EmptyDescription>
1343
+ </EmptyHeader>
1344
+ </Empty>
1345
+ ) : (
1346
+ <MessageScroller>
1347
+ <MessageScrollerViewport>
1348
+ <MessageScrollerContent
1349
+ aria-busy={isBusy}
1350
+ className="p-(--card-spacing)"
1351
+ >
1352
+ {messages.map((message) => (
1353
+ <MessageAnimated
1354
+ key={message.id}
1355
+ message={message}
1356
+ scrollAnchor={message.role === "user"}
1357
+ />
1358
+ ))}
1359
+ </MessageScrollerContent>
1360
+ </MessageScrollerViewport>
1361
+ <MessageScrollerButton />
1362
+ </MessageScroller>
1363
+ )}
1364
+ </CardContent>
1365
+ <CardFooter className="flex-col gap-2">
1366
+ <form
1367
+ onSubmit={(e) => {
1368
+ e.preventDefault()
1369
+ if (!nextMessage || isBusy) {
1370
+ return
1371
+ }
1372
+ void sendMessage(nextMessage)
1373
+ }}
1374
+ className="w-full"
1375
+ >
1376
+ <InputGroup>
1377
+ <div className="h-14 w-full px-3 py-2.5">
1378
+ <span
1379
+ className="line-clamp-2 opacity-60 data-[status=ready]:opacity-100"
1380
+ data-status={status}
1381
+ >
1382
+ {nextMessage ? (
1383
+ getMessageText(nextMessage)
1384
+ ) : (
1385
+ <span className="text-muted-foreground">
1386
+ No messages queued. Reset the stream.
1387
+ </span>
1388
+ )}
1389
+ </span>
1390
+ </div>
1391
+ <InputGroupAddon align="block-end" className="pt-1">
1392
+ <DropdownMenu>
1393
+ <DropdownMenuTrigger
1394
+ render={
1395
+ <InputGroupButton
1396
+ aria-label="Add files"
1397
+ type="button"
1398
+ size="icon-sm"
1399
+ variant="outline"
1400
+ />
1401
+ }
1402
+ >
1403
+ <PlusIcon />
1404
+ </DropdownMenuTrigger>
1405
+ <DropdownMenuContent
1406
+ align="start"
1407
+ side="top"
1408
+ className="w-44"
1409
+ >
1410
+ <DropdownMenuItem>
1411
+ <PaperclipIcon />
1412
+ Add Photos & Files
1413
+ </DropdownMenuItem>
1414
+ <DropdownMenuSeparator />
1415
+ <DropdownMenuItem>
1416
+ <ImageIcon />
1417
+ Create Image
1418
+ </DropdownMenuItem>
1419
+ <DropdownMenuItem>
1420
+ <TelescopeIcon />
1421
+ Deep Research
1422
+ </DropdownMenuItem>
1423
+ <DropdownMenuItem>
1424
+ <GlobeIcon />
1425
+ Web Search
1426
+ </DropdownMenuItem>
1427
+ </DropdownMenuContent>
1428
+ </DropdownMenu>
1429
+ <InputGroupButton
1430
+ type="submit"
1431
+ variant="default"
1432
+ size="icon-sm"
1433
+ disabled={!nextMessage || isBusy}
1434
+ className="ml-auto"
1435
+ >
1436
+ <ArrowUpIcon />
1437
+ <span className="sr-only">Send</span>
1438
+ </InputGroupButton>
1439
+ </InputGroupAddon>
1440
+ </InputGroup>
1441
+ </form>
1442
+ </CardFooter>
1443
+ </Card>
1444
+ <div className="px-0.5 text-center text-xs text-muted-foreground">
1445
+ Streaming is simulated. `autoScroll` is enabled.
1446
+ </div>
1447
+ </div>
1448
+ </MessageScrollerProvider>
1449
+ )
1450
+ }
1451
+
1452
+ ```
1453
+
1454
+ Calling `scrollToEnd`, or pressing `MessageScrollerButton`, re-engages
1455
+ follow-output when `autoScroll` is enabled, so a reader who scrolled away can
1456
+ return to the live edge and keep following. The root and viewport expose
1457
+ `data-autoscrolling` while that programmatic scroll to the latest message runs,
1458
+ so you can conditionally apply styles during the transition.
1459
+
1460
+ ### Opening Saved Threads
1461
+
1462
+ It can seem reasonable to reopen a saved thread at the absolute end of the
1463
+ transcript, but that often drops the reader into the conversation without enough
1464
+ context. A better default is `"last-anchor"`: show the last meaningful turn,
1465
+ like the user's latest message, with the reply below it.
1466
+
1467
+ That gives the reader an immediate place in the thread. They can see what they
1468
+ asked, where the answer starts, and continue from there without reconstructing
1469
+ the conversation from the bottom edge.
1470
+
1471
+ ```tsx
1472
+ <MessageScrollerProvider defaultScrollPosition="last-anchor">
1473
+ <MessageScroller>{/* transcript */}</MessageScroller>
1474
+ </MessageScrollerProvider>
1475
+ ```
1476
+
1477
+ ```tsx
1478
+ "use client"
1479
+
1480
+ import * as React from "react"
1481
+
1482
+ import { Bubble, BubbleContent } from "@/components/ui/bubble"
1483
+ import { Button } from "@/components/ui/button"
1484
+ import {
1485
+ Card,
1486
+ CardContent,
1487
+ CardDescription,
1488
+ CardFooter,
1489
+ CardHeader,
1490
+ CardTitle,
1491
+ } from "@/components/ui/card"
1492
+ import { Message, MessageContent } from "@/components/ui/message"
1493
+ import {
1494
+ MessageScroller,
1495
+ MessageScrollerButton,
1496
+ MessageScrollerContent,
1497
+ MessageScrollerItem,
1498
+ MessageScrollerProvider,
1499
+ MessageScrollerViewport,
1500
+ useMessageScroller,
1501
+ } from "@/components/ui/message-scroller"
1502
+ import { Tabs, TabsList, TabsTrigger } from "@/components/ui/tabs"
1503
+
1504
+ const messages = [
1505
+ {
1506
+ id: "open-1",
1507
+ role: "user",
1508
+ text: "This is the first message the user sent in the conversation.",
1509
+ },
1510
+ {
1511
+ id: "open-2",
1512
+ role: "assistant",
1513
+ text: "Workspace creation rose 8%, but first invite completion only rose 2%.",
1514
+ },
1515
+ {
1516
+ id: "open-3",
1517
+ role: "user",
1518
+ text: "This is the last message the user sent in the conversation.",
1519
+ },
1520
+ {
1521
+ id: "open-4",
1522
+ role: "assistant",
1523
+ text: "Start with the invite step. Teams are creating workspaces but waiting to add collaborators.\n\nRecommended follow-up:\n\n1. Compare invite drop-off by account size.\n2. Check whether users who skip invites still return within 24 hours.\n3. Review the empty-state copy on the first project screen.\n4. Segment activation by template, since template users may not need invites right away.\n\nIf that pattern holds, the next experiment should make collaboration useful earlier instead of prompting for invites harder.",
1524
+ },
1525
+ ] satisfies Array<{
1526
+ id: string
1527
+ role: "user" | "assistant"
1528
+ text: string
1529
+ }>
1530
+
1531
+ const positions = [
1532
+ { value: "start", label: "start" },
1533
+ { value: "end", label: "end" },
1534
+ { value: "last-anchor", label: "last-anchor" },
1535
+ ] satisfies Array<{
1536
+ value: "start" | "end" | "last-anchor"
1537
+ label: string
1538
+ }>
1539
+
1540
+ export function MessageScrollerOpeningPosition() {
1541
+ const [positionKey, setPositionKey] = React.useState(0)
1542
+ const [position, setPosition] = React.useState<
1543
+ "start" | "end" | "last-anchor"
1544
+ >("last-anchor")
1545
+
1546
+ return (
1547
+ <div className="relative flex flex-col gap-4">
1548
+ <Card className="mx-auto h-140 w-full max-w-sm gap-0">
1549
+ <CardHeader className="gap-1 border-b">
1550
+ <CardTitle>Opening Position</CardTitle>
1551
+ <CardDescription>
1552
+ Choose where a saved transcript opens.
1553
+ </CardDescription>
1554
+ </CardHeader>
1555
+ <CardContent className="flex-1 overflow-hidden p-0">
1556
+ <MessageScrollerProvider>
1557
+ <OpeningPositionScroller
1558
+ position={position}
1559
+ positionKey={positionKey}
1560
+ />
1561
+ </MessageScrollerProvider>
1562
+ </CardContent>
1563
+ <CardFooter className="flex items-center justify-center border-t">
1564
+ <Tabs
1565
+ value={position}
1566
+ onValueChange={(value) => {
1567
+ if (
1568
+ value === "start" ||
1569
+ value === "end" ||
1570
+ value === "last-anchor"
1571
+ ) {
1572
+ setPosition(value)
1573
+ setPositionKey((key) => key + 1)
1574
+ }
1575
+ }}
1576
+ className="w-full"
1577
+ >
1578
+ <TabsList className="w-full">
1579
+ {positions.map((option) => (
1580
+ <TabsTrigger key={option.value} value={option.value}>
1581
+ {option.label}
1582
+ </TabsTrigger>
1583
+ ))}
1584
+ </TabsList>
1585
+ </Tabs>
1586
+ </CardFooter>
1587
+ </Card>
1588
+ <div className="mx-auto max-w-sm px-0.5 text-center text-xs text-muted-foreground">
1589
+ Toggle the defaultScrollPosition to see where the transcript starts when
1590
+ you open the thread
1591
+ </div>
1592
+ </div>
1593
+ )
1594
+ }
1595
+
1596
+ function OpeningPositionScroller({
1597
+ position,
1598
+ positionKey,
1599
+ }: {
1600
+ position: "start" | "end" | "last-anchor"
1601
+ positionKey: number
1602
+ }) {
1603
+ const { scrollToEnd, scrollToMessage, scrollToStart } = useMessageScroller()
1604
+
1605
+ React.useLayoutEffect(() => {
1606
+ const frame = requestAnimationFrame(() => {
1607
+ if (position === "start") {
1608
+ scrollToStart({ behavior: "auto" })
1609
+ return
1610
+ }
1611
+
1612
+ if (position === "end") {
1613
+ scrollToEnd({ behavior: "auto" })
1614
+ return
1615
+ }
1616
+
1617
+ scrollToMessage("open-3", {
1618
+ align: "start",
1619
+ behavior: "auto",
1620
+ scrollMargin: 64,
1621
+ })
1622
+ })
1623
+
1624
+ return () => {
1625
+ cancelAnimationFrame(frame)
1626
+ }
1627
+ }, [position, positionKey, scrollToEnd, scrollToMessage, scrollToStart])
1628
+
1629
+ return (
1630
+ <MessageScroller>
1631
+ <MessageScrollerViewport>
1632
+ <MessageScrollerContent className="p-(--card-spacing)">
1633
+ {messages.map((message) => {
1634
+ const isUserMessage = message.role === "user"
1635
+
1636
+ return (
1637
+ <MessageScrollerItem
1638
+ key={message.id}
1639
+ messageId={message.id}
1640
+ scrollAnchor={isUserMessage}
1641
+ >
1642
+ <Message align={isUserMessage ? "end" : "start"}>
1643
+ <MessageContent>
1644
+ <Bubble variant={isUserMessage ? "muted" : "ghost"}>
1645
+ <BubbleContent className="space-y-2">
1646
+ {message.text
1647
+ .split(/\n\s*\n/)
1648
+ .map((paragraph) => paragraph.trim())
1649
+ .filter(Boolean)
1650
+ .map((paragraph, index) => (
1651
+ <p key={index} className="whitespace-pre-wrap">
1652
+ {paragraph}
1653
+ </p>
1654
+ ))}
1655
+ </BubbleContent>
1656
+ </Bubble>
1657
+ </MessageContent>
1658
+ </Message>
1659
+ </MessageScrollerItem>
1660
+ )
1661
+ })}
1662
+ </MessageScrollerContent>
1663
+ </MessageScrollerViewport>
1664
+ <MessageScrollerButton />
1665
+ </MessageScroller>
1666
+ )
1667
+ }
1668
+
1669
+ ```
1670
+
1671
+ `"last-anchor"` is keyed on `scrollAnchor`, not message role. If no anchor
1672
+ exists, or the last anchored turn already fits in the viewport, it falls back to
1673
+ `"end"`.
1674
+
1675
+ Use `"start"` when you want to resume at the beginning of a conversation, or
1676
+ `"end"` when the absolute latest message is the right place to land.
1677
+
1678
+ ### Avoiding a Flash on Reload
1679
+
1680
+ A scroll container always opens at the top. HTML has no way to set `scrollTop`,
1681
+ so a server-rendered transcript shows the oldest messages first. After
1682
+ JavaScript runs, `defaultScrollPosition` moves the view, and you see a jump.
1683
+
1684
+ When `defaultScrollPosition` is `"end"` or `"last-anchor"`, the viewport has
1685
+ `data-pending-scroll` until that position is applied. The styled viewport stays
1686
+ hidden while the attribute is present, so you see the frame instead of the jump.
1687
+ `"start"` does not need this.
1688
+
1689
+ If you want `"end"` visible on first paint, add an inline script right after the
1690
+ viewport. Give the viewport an `id`, scroll it to the bottom, and remove
1691
+ `data-pending-scroll`.
1692
+
1693
+ ```tsx
1694
+ const scrollToEndScript = `(function () {
1695
+ var viewport = document.getElementById("messages")
1696
+ if (!viewport) {
1697
+ return
1698
+ }
1699
+ viewport.scrollTop = viewport.scrollHeight
1700
+ viewport.removeAttribute("data-pending-scroll")
1701
+ })()`
1702
+
1703
+ <MessageScroller>
1704
+ <MessageScrollerViewport id="messages" suppressHydrationWarning>
1705
+ <MessageScrollerContent>{/* transcript */}</MessageScrollerContent>
1706
+ </MessageScrollerViewport>
1707
+ <script dangerouslySetInnerHTML={{ __html: scrollToEndScript }} />
1708
+ <MessageScrollerButton />
1709
+ </MessageScroller>
1710
+ ```
1711
+
1712
+ Put the script in your page, not in the scroller. It only works for `"end"`, and
1713
+ only when the messages are already in the HTML. Add `suppressHydrationWarning` on
1714
+ the viewport. If you use a Content Security Policy, pass a `nonce`.
1715
+
1716
+ Do not use this script with `"last-anchor"`. Skip it when messages load on the
1717
+ client.
1718
+
1719
+ ### Loading Earlier Messages
1720
+
1721
+ Loading earlier messages should not move the conversation the reader is already
1722
+ looking at. When older rows are prepended above the current transcript,
1723
+ `MessageScrollerViewport` preserves the visible row so the reader stays in the
1724
+ same place while history loads above them.
1725
+
1726
+ This is enabled by default through `preserveScrollOnPrepend`.
1727
+
1728
+ ```tsx
1729
+ "use client"
1730
+
1731
+ import * as React from "react"
1732
+ import { RotateCwIcon } from "lucide-react"
1733
+ import { toast } from "sonner"
1734
+
1735
+ import { createChat, getMessageText } from "@/lib/ai"
1736
+ import { Bubble, BubbleContent } from "@/components/ui/bubble"
1737
+ import { Button } from "@/components/ui/button"
1738
+ import {
1739
+ Card,
1740
+ CardAction,
1741
+ CardContent,
1742
+ CardDescription,
1743
+ CardFooter,
1744
+ CardHeader,
1745
+ CardTitle,
1746
+ } from "@/components/ui/card"
1747
+ import { Marker, MarkerContent } from "@/components/ui/marker"
1748
+ import { Message, MessageContent } from "@/components/ui/message"
1749
+ import {
1750
+ MessageScroller,
1751
+ MessageScrollerButton,
1752
+ MessageScrollerContent,
1753
+ MessageScrollerItem,
1754
+ MessageScrollerProvider,
1755
+ MessageScrollerViewport,
1756
+ } from "@/components/ui/message-scroller"
1757
+ import {
1758
+ Tooltip,
1759
+ TooltipContent,
1760
+ TooltipTrigger,
1761
+ } from "@/components/ui/tooltip"
1762
+
1763
+ const chat = createChat()
1764
+ .user("Can you summarize the incident channel?")
1765
+ .assistant(
1766
+ "The first alert was a delayed export job. It started backing up around 09:42 UTC and triggered the warning once the retry queue crossed the threshold.\n\nNo customer-facing checkout paths were affected, but exports for larger workspaces were running about 12 minutes behind."
1767
+ )
1768
+ .user("Was checkout affected?")
1769
+ .assistant(
1770
+ "No checkout errors were reported. Payment authorization, order creation, and confirmation emails stayed inside their normal latency bands.\n\nThe only elevated metric was export queue depth, which maps to analytics downloads instead of checkout."
1771
+ )
1772
+ .user("What changed in the last deploy?")
1773
+ .assistant(
1774
+ "Only the export queue worker changed. The deploy moved large CSV jobs onto the shared retry policy, which made each failed attempt hold a worker slot longer than before.\n\nThe app deploy did not include checkout, pricing, or billing API changes."
1775
+ )
1776
+ .user("Do we need to roll back?")
1777
+ .assistant(
1778
+ "Not yet. Queue depth is recovering after we reduced retry concurrency, and the oldest pending job is now under five minutes old.\n\nKeep rollback ready if the queue starts climbing again, but the current trend points toward recovery."
1779
+ )
1780
+ .user("Keep watching for customer-visible issues.")
1781
+ .assistant(
1782
+ "I will watch the queue and support tags for another 15 minutes. I am tracking export failures, delayed download requests, and any support thread that mentions missing reports.\n\nIf those stay quiet through the next batch window, we can close this as an internal degradation."
1783
+ )
1784
+
1785
+ const history = chat.get()
1786
+ const INITIAL_VISIBLE_COUNT = 5
1787
+
1788
+ export function MessageScrollerLoadHistory() {
1789
+ const [demoKey, setDemoKey] = React.useState(0)
1790
+ const [visibleCount, setVisibleCount] = React.useState(INITIAL_VISIBLE_COUNT)
1791
+ const visibleMessages = history.slice(-visibleCount)
1792
+ const canLoadHistory = visibleCount < history.length
1793
+
1794
+ return (
1795
+ <MessageScrollerProvider>
1796
+ <div className="relative flex flex-col gap-4">
1797
+ <Card className="mx-auto h-140 w-full max-w-sm gap-0">
1798
+ <CardHeader className="gap-1 border-b">
1799
+ <CardTitle>Load History</CardTitle>
1800
+ <CardDescription>
1801
+ Prepended messages keep your place.
1802
+ </CardDescription>
1803
+ <CardAction>
1804
+ <Tooltip>
1805
+ <TooltipTrigger
1806
+ render={
1807
+ <Button
1808
+ type="button"
1809
+ variant="outline"
1810
+ size="icon"
1811
+ aria-label="Reset loaded messages"
1812
+ disabled={visibleCount === INITIAL_VISIBLE_COUNT}
1813
+ onClick={() => {
1814
+ setVisibleCount(INITIAL_VISIBLE_COUNT)
1815
+ setDemoKey((key) => key + 1)
1816
+ }}
1817
+ />
1818
+ }
1819
+ >
1820
+ <RotateCwIcon />
1821
+ </TooltipTrigger>
1822
+ <TooltipContent>
1823
+ <p>Reset</p>
1824
+ </TooltipContent>
1825
+ </Tooltip>
1826
+ </CardAction>
1827
+ </CardHeader>
1828
+ <CardContent className="flex-1 overflow-hidden p-0">
1829
+ <MessageScroller key={demoKey}>
1830
+ <MessageScrollerViewport>
1831
+ <MessageScrollerContent className="p-(--card-spacing)">
1832
+ {visibleMessages.map((message) => {
1833
+ const isUserMessage = message.role === "user"
1834
+
1835
+ return (
1836
+ <MessageScrollerItem
1837
+ key={message.id}
1838
+ messageId={message.id}
1839
+ >
1840
+ <Message align={isUserMessage ? "end" : "start"}>
1841
+ <MessageContent>
1842
+ <Bubble variant={isUserMessage ? "muted" : "ghost"}>
1843
+ <BubbleContent className="space-y-2">
1844
+ {getMessageText(message)
1845
+ .split(/\n\s*\n/)
1846
+ .map((paragraph) => paragraph.trim())
1847
+ .filter(Boolean)
1848
+ .map((paragraph, index) => (
1849
+ <p
1850
+ key={index}
1851
+ className="whitespace-pre-wrap"
1852
+ >
1853
+ {paragraph}
1854
+ </p>
1855
+ ))}
1856
+ </BubbleContent>
1857
+ </Bubble>
1858
+ </MessageContent>
1859
+ </Message>
1860
+ </MessageScrollerItem>
1861
+ )
1862
+ })}
1863
+ <MessageScrollerItem scrollAnchor={false}>
1864
+ <Marker variant="separator">
1865
+ <MarkerContent>End of Conversation</MarkerContent>
1866
+ </Marker>
1867
+ </MessageScrollerItem>
1868
+ </MessageScrollerContent>
1869
+ </MessageScrollerViewport>
1870
+ <MessageScrollerButton />
1871
+ </MessageScroller>
1872
+ </CardContent>
1873
+ <CardFooter className="flex flex-col items-center gap-2 border-t">
1874
+ <Button
1875
+ type="button"
1876
+ disabled={!canLoadHistory}
1877
+ onClick={() => {
1878
+ setVisibleCount(history.length)
1879
+ toast("History loaded", {
1880
+ description: "Scroll up to see earlier messages.",
1881
+ })
1882
+ }}
1883
+ className="w-full"
1884
+ variant="secondary"
1885
+ >
1886
+ {canLoadHistory ? "Load History" : "History Loaded"}
1887
+ </Button>
1888
+ <p className="text-xs text-muted-foreground">
1889
+ Restore earlier messages while keeping your place.
1890
+ </p>
1891
+ </CardFooter>
1892
+ </Card>
1893
+ <div className="mx-auto max-w-sm px-0.5 text-center text-xs text-balance text-muted-foreground">
1894
+ Click Load History to load the entire conversation
1895
+ </div>
1896
+ </div>
1897
+ </MessageScrollerProvider>
1898
+ )
1899
+ }
1900
+
1901
+ ```
1902
+
1903
+ Use stable `messageId` values for message rows. That gives the scroller a
1904
+ specific row to preserve instead of guessing from whichever pixel happens to sit
1905
+ at the viewport edge.
1906
+
1907
+ ### Animating New Messages
1908
+
1909
+ `MessageScrollerItem` can be animated directly. Create a motion version of the
1910
+ item, keep `messageId` and `scrollAnchor` on it, and use transform and opacity
1911
+ for the entrance.
1912
+
1913
+ A common chat pattern is to animate the user's message when it is sent, then let
1914
+ the assistant reply stream into a regular row below it. Start the user row below
1915
+ its final position so it feels like it rises from the live edge of the viewport.
1916
+
1917
+ ```tsx
1918
+ const MotionMessageScrollerItem = motion.create(MessageScrollerItem)
1919
+ ```
1920
+
1921
+ ```tsx
1922
+ "use client"
1923
+
1924
+ import * as React from "react"
1925
+ import { useChat } from "@ai-sdk/react"
1926
+ import {
1927
+ ArrowUpIcon,
1928
+ MessageCircleDashedIcon,
1929
+ RotateCwIcon,
1930
+ } from "lucide-react"
1931
+
1932
+ import { createChat } from "@/lib/ai"
1933
+ import {
1934
+ MESSAGE_ANIMATIONS,
1935
+ type MessageAnimationId,
1936
+ } from "@/lib/message-animations"
1937
+ import { MessageAnimated } from "@/components/message-animated"
1938
+ import { Button } from "@/components/ui/button"
1939
+ import {
1940
+ Card,
1941
+ CardAction,
1942
+ CardContent,
1943
+ CardDescription,
1944
+ CardFooter,
1945
+ CardHeader,
1946
+ CardTitle,
1947
+ } from "@/components/ui/card"
1948
+ import {
1949
+ Empty,
1950
+ EmptyDescription,
1951
+ EmptyHeader,
1952
+ EmptyMedia,
1953
+ EmptyTitle,
1954
+ } from "@/components/ui/empty"
1955
+ import {
1956
+ MessageScroller,
1957
+ MessageScrollerButton,
1958
+ MessageScrollerContent,
1959
+ MessageScrollerProvider,
1960
+ MessageScrollerViewport,
1961
+ } from "@/components/ui/message-scroller"
1962
+ import {
1963
+ Select,
1964
+ SelectContent,
1965
+ SelectGroup,
1966
+ SelectItem,
1967
+ SelectTrigger,
1968
+ SelectValue,
1969
+ } from "@/components/ui/select"
1970
+
1971
+ const chat = createChat()
1972
+ .user("Can user messages pop in like iMessage without breaking anchoring?")
1973
+ .sleep(1000)
1974
+ .assistant(
1975
+ "Yes. Animate the user row with transform and opacity, and let the assistant response stream normally below it.\n\nThat keeps the row measurement predictable while still giving the newly sent bubble a more tactile entrance."
1976
+ )
1977
+ .user("What makes the animation feel more like iMessage?")
1978
+ .sleep(1000)
1979
+ .assistant(
1980
+ "Use a quick spring from the trailing edge: a little scale, a small upward move, and no layout animation.\n\nThe bubble feels tactile, but the measured row stays predictable, so anchoring and auto-scroll do not have to fight a changing layout."
1981
+ )
1982
+ .user("Can I switch between presets while testing the same thread?")
1983
+ .sleep(1000)
1984
+ .assistant(
1985
+ "Yes. Keep the conversation in place while you change the preset, then send the next message to compare the new entrance against the same context.\n\nThat makes it easier to judge the difference between a subtle fade, a snappy pop, and a more dramatic 3D tilt without rebuilding the scenario each time."
1986
+ )
1987
+
1988
+ const initialMessages = chat.get(0)
1989
+ const transport = chat.transport({ delayMs: 15 })
1990
+
1991
+ export function MessageScrollerAnimation() {
1992
+ const { messages, sendMessage, setMessages, status } = useChat({
1993
+ messages: initialMessages,
1994
+ transport,
1995
+ })
1996
+ const [presetId, setPresetId] = React.useState<MessageAnimationId>("fade")
1997
+ const nextMessage = chat.next(messages)
1998
+ const isBusy = status === "submitted" || status === "streaming"
1999
+ const preset = MESSAGE_ANIMATIONS[presetId as MessageAnimationId]
2000
+
2001
+ return (
2002
+ <div className="relative flex flex-col gap-4">
2003
+ <Card className="mx-auto h-140 w-full max-w-sm gap-0">
2004
+ <CardHeader className="border-b">
2005
+ <CardTitle>Animation</CardTitle>
2006
+ <CardDescription>
2007
+ Choose how user messages are animated when they are added to the
2008
+ conversation.
2009
+ </CardDescription>
2010
+ <CardAction className="flex items-center gap-2">
2011
+ <Button
2012
+ type="button"
2013
+ variant="outline"
2014
+ size="icon"
2015
+ aria-label="Reset animated messages"
2016
+ disabled={messages.length === 0 || isBusy}
2017
+ onClick={() => setMessages(initialMessages)}
2018
+ >
2019
+ <RotateCwIcon />
2020
+ </Button>
2021
+ </CardAction>
2022
+ </CardHeader>
2023
+ <CardContent className="min-h-0 flex-1 overflow-hidden p-0">
2024
+ {messages.length === 0 ? (
2025
+ <Empty className="h-full">
2026
+ <EmptyHeader>
2027
+ <EmptyMedia variant="icon">
2028
+ <MessageCircleDashedIcon />
2029
+ </EmptyMedia>
2030
+ <EmptyTitle>No Messages Yet</EmptyTitle>
2031
+ <EmptyDescription>
2032
+ Click the button below to send the first message.
2033
+ </EmptyDescription>
2034
+ </EmptyHeader>
2035
+ </Empty>
2036
+ ) : (
2037
+ <MessageScrollerProvider>
2038
+ <MessageScroller>
2039
+ <MessageScrollerViewport>
2040
+ <MessageScrollerContent
2041
+ aria-busy={isBusy}
2042
+ className="p-(--card-spacing)"
2043
+ >
2044
+ {messages.map((message) => (
2045
+ <MessageAnimated
2046
+ key={message.id}
2047
+ message={message}
2048
+ animationPreset={preset}
2049
+ userVariant="muted"
2050
+ assistantVariant="ghost"
2051
+ />
2052
+ ))}
2053
+ </MessageScrollerContent>
2054
+ </MessageScrollerViewport>
2055
+ <MessageScrollerButton />
2056
+ </MessageScroller>
2057
+ </MessageScrollerProvider>
2058
+ )}
2059
+ </CardContent>
2060
+ <CardFooter className="border-t">
2061
+ <Select
2062
+ value={presetId}
2063
+ onValueChange={(value) => {
2064
+ setPresetId(value as MessageAnimationId)
2065
+ }}
2066
+ >
2067
+ <SelectTrigger aria-label="Animation preset">
2068
+ <SelectValue>{preset.name}</SelectValue>
2069
+ </SelectTrigger>
2070
+ <SelectContent align="start" side="top">
2071
+ <SelectGroup>
2072
+ {Object.values(MESSAGE_ANIMATIONS).map((animation) => (
2073
+ <SelectItem key={animation.id} value={animation.id}>
2074
+ {animation.name}
2075
+ </SelectItem>
2076
+ ))}
2077
+ </SelectGroup>
2078
+ </SelectContent>
2079
+ </Select>
2080
+ <Button
2081
+ type="button"
2082
+ size="icon"
2083
+ className="ml-auto"
2084
+ disabled={!nextMessage || isBusy}
2085
+ onClick={() => {
2086
+ if (!nextMessage || isBusy) {
2087
+ return
2088
+ }
2089
+
2090
+ void sendMessage(nextMessage)
2091
+ }}
2092
+ >
2093
+ <ArrowUpIcon />
2094
+ <span className="sr-only">Send Message</span>
2095
+ </Button>
2096
+ </CardFooter>
2097
+ </Card>
2098
+ <div className="mx-auto max-w-sm px-0.5 text-center text-xs text-balance text-muted-foreground">
2099
+ Select an animation then click send to see it in action.
2100
+ </div>
2101
+ </div>
2102
+ )
2103
+ }
2104
+
2105
+ ```
2106
+
2107
+ Avoid animating height, margin, or padding for row entrances; those changes can
2108
+ fight the scroller's positioning work. If the reader prefers reduced motion,
2109
+ skip the entrance animation and keep the scroll behavior the same.
2110
+
2111
+ ### Jumping to Messages
2112
+
2113
+ Search results, permalinks, outline items, and toolbar buttons often need to
2114
+ drive the transcript from outside the message list. Use `useMessageScroller` for
2115
+ those controls. Because the hooks read from `MessageScrollerProvider`, they work
2116
+ in any component inside the provider, including controls rendered outside the
2117
+ `MessageScroller` frame.
2118
+
2119
+ ```tsx
2120
+ import { useMessageScroller } from "@/components/ui/message-scroller"
2121
+ ```
2122
+
2123
+ ```tsx
2124
+ const { scrollToMessage, scrollToEnd, scrollToStart } = useMessageScroller()
2125
+ ```
2126
+
2127
+ ```tsx
2128
+ "use client"
2129
+
2130
+ import * as React from "react"
2131
+
2132
+ import { createChat, getMessageText } from "@/lib/ai"
2133
+ import { Bubble, BubbleContent } from "@/components/ui/bubble"
2134
+ import { Button } from "@/components/ui/button"
2135
+ import {
2136
+ Card,
2137
+ CardAction,
2138
+ CardContent,
2139
+ CardDescription,
2140
+ CardHeader,
2141
+ CardTitle,
2142
+ } from "@/components/ui/card"
2143
+ import {
2144
+ DropdownMenu,
2145
+ DropdownMenuContent,
2146
+ DropdownMenuGroup,
2147
+ DropdownMenuItem,
2148
+ DropdownMenuLabel,
2149
+ DropdownMenuTrigger,
2150
+ } from "@/components/ui/dropdown-menu"
2151
+ import { Message, MessageContent } from "@/components/ui/message"
2152
+ import {
2153
+ MessageScroller,
2154
+ MessageScrollerButton,
2155
+ MessageScrollerContent,
2156
+ MessageScrollerItem,
2157
+ MessageScrollerProvider,
2158
+ MessageScrollerViewport,
2159
+ useMessageScroller,
2160
+ } from "@/components/ui/message-scroller"
2161
+
2162
+ const chat = createChat()
2163
+ .user(
2164
+ "We're seeing activation dip after workspace creation. Can you help me find the likely step?",
2165
+ { id: "command-activation" }
2166
+ )
2167
+ .assistant(
2168
+ "The sharpest drop is between creating the workspace and inviting the first teammate.\n\nWorkspace creation is still healthy, but the invite step is where users pause. That suggests the product is asking for collaboration before the user has enough confidence in the workspace."
2169
+ )
2170
+ .user("What should I compare before we change the onboarding flow?", {
2171
+ id: "command-compare",
2172
+ })
2173
+ .assistant(
2174
+ "Compare three cohorts:\n\n1. Users who choose a template before inviting teammates.\n2. Users who start from a blank workspace.\n3. Users who skip invites and return within 24 hours.\n\nIf template users invite faster, the fix is probably better first-run guidance rather than a louder invite prompt."
2175
+ )
2176
+ .user("Can you turn that into an experiment?", {
2177
+ id: "command-experiment",
2178
+ })
2179
+ .assistant(
2180
+ "Yes. Create a variant that shows a short checklist after workspace creation:\n\n- Pick a template.\n- Add one project detail.\n- Invite a teammate when the workspace has context.\n\nMeasure first invite completion, 24-hour return rate, and whether teams create a second project."
2181
+ )
2182
+ .user("What's the risk if we delay the invite prompt?", {
2183
+ id: "command-risk",
2184
+ })
2185
+ .assistant(
2186
+ "The main risk is reducing team creation for accounts that already know who they want to invite.\n\nTo protect that path, keep the invite action visible in the header and only change the primary empty-state guidance. That gives confident teams a direct route without forcing uncertain users through the invite step too early."
2187
+ )
2188
+
2189
+ const messages = chat.get()
2190
+ const userMessages = messages.filter((message) => message.role === "user")
2191
+
2192
+ export function MessageScrollerCommands() {
2193
+ return (
2194
+ <MessageScrollerProvider defaultScrollPosition="end">
2195
+ <div className="relative flex flex-col gap-4">
2196
+ <Card className="mx-auto h-140 w-full max-w-sm gap-0">
2197
+ <CardHeader className="gap-1 border-b">
2198
+ <CardTitle>Commands</CardTitle>
2199
+ <CardDescription>
2200
+ Drive the transcript from outside.
2201
+ </CardDescription>
2202
+ <CardAction>
2203
+ <CommandMenu />
2204
+ </CardAction>
2205
+ </CardHeader>
2206
+ <CardContent className="flex-1 overflow-hidden p-0">
2207
+ <MessageScroller>
2208
+ <MessageScrollerViewport>
2209
+ <MessageScrollerContent className="p-(--card-spacing)">
2210
+ {messages.map((message) => {
2211
+ const isUserMessage = message.role === "user"
2212
+ const text = getMessageText(message)
2213
+
2214
+ return (
2215
+ <MessageScrollerItem
2216
+ key={message.id}
2217
+ messageId={message.id}
2218
+ scrollAnchor={isUserMessage}
2219
+ >
2220
+ <Message align={isUserMessage ? "end" : "start"}>
2221
+ <MessageContent>
2222
+ <Bubble variant={isUserMessage ? "muted" : "ghost"}>
2223
+ <BubbleContent className="space-y-2">
2224
+ {text
2225
+ .split(/\n\s*\n/)
2226
+ .map((paragraph) => paragraph.trim())
2227
+ .filter(Boolean)
2228
+ .map((paragraph, index) => (
2229
+ <p
2230
+ key={index}
2231
+ className="whitespace-pre-wrap"
2232
+ >
2233
+ {paragraph}
2234
+ </p>
2235
+ ))}
2236
+ </BubbleContent>
2237
+ </Bubble>
2238
+ </MessageContent>
2239
+ </Message>
2240
+ </MessageScrollerItem>
2241
+ )
2242
+ })}
2243
+ </MessageScrollerContent>
2244
+ </MessageScrollerViewport>
2245
+ <MessageScrollerButton />
2246
+ </MessageScroller>
2247
+ </CardContent>
2248
+ </Card>
2249
+ <div className="mx-auto max-w-sm px-0.5 text-center text-xs text-balance text-muted-foreground">
2250
+ Use the controls to jump to any message in the conversation.
2251
+ </div>
2252
+ </div>
2253
+ </MessageScrollerProvider>
2254
+ )
2255
+ }
2256
+
2257
+ function CommandMenu() {
2258
+ const { scrollToMessage } = useMessageScroller()
2259
+
2260
+ return (
2261
+ <DropdownMenu>
2262
+ <DropdownMenuTrigger
2263
+ render={<Button type="button" variant="secondary" />}
2264
+ >
2265
+ Jump to...
2266
+ </DropdownMenuTrigger>
2267
+ <DropdownMenuContent align="end" side="bottom" className="w-64">
2268
+ <DropdownMenuGroup>
2269
+ <DropdownMenuLabel>Conversations</DropdownMenuLabel>
2270
+ {userMessages.map((message) => (
2271
+ <DropdownMenuItem
2272
+ key={message.id}
2273
+ onClick={() =>
2274
+ scrollToMessage(message.id, {
2275
+ align: "start",
2276
+ behavior: "smooth",
2277
+ })
2278
+ }
2279
+ >
2280
+ <span className="line-clamp-1 min-w-0">
2281
+ {getTrimmedMessageText(message)}
2282
+ </span>
2283
+ </DropdownMenuItem>
2284
+ ))}
2285
+ </DropdownMenuGroup>
2286
+ </DropdownMenuContent>
2287
+ </DropdownMenu>
2288
+ )
2289
+ }
2290
+
2291
+ function getTrimmedMessageText(message: (typeof userMessages)[number]) {
2292
+ const text = getMessageText(message)
2293
+
2294
+ return text.length > 42 ? `${text.slice(0, 39)}...` : text
2295
+ }
2296
+
2297
+ ```
2298
+
2299
+ `scrollToMessage` targets the `messageId` on `MessageScrollerItem`, so rows that
2300
+ need to be addressable should have stable ids. `scrollToMessage` returns `false`
2301
+ when the target is not mounted and cannot be queued.
2302
+
2303
+ `scrollToMessage` can queue a target before items exist, which covers
2304
+ client-resolved permalinks while the transcript mounts. After rows have mounted,
2305
+ a missing id returns `false` instead of starting a guessed retry loop. A `true`
2306
+ result means the scroll ran or was queued, not that the row is already in view.
2307
+
2308
+ ### Tracking the Reader's Position
2309
+
2310
+ Use `useMessageScrollerVisibility` to track the reader's position in the
2311
+ conversation. A common example is a table-of-contents or a jump menu that
2312
+ highlights the current anchored turn.
2313
+
2314
+ ```tsx
2315
+ import { useMessageScrollerVisibility } from "@/components/ui/message-scroller"
2316
+ ```
2317
+
2318
+ ```tsx
2319
+ const { currentAnchorId, visibleMessageIds } = useMessageScrollerVisibility()
2320
+ ```
2321
+
2322
+ ```tsx
2323
+ "use client"
2324
+
2325
+ import { createChat, getMessageText } from "@/lib/ai"
2326
+ import { Bubble, BubbleContent } from "@/components/ui/bubble"
2327
+ import {
2328
+ Card,
2329
+ CardContent,
2330
+ CardDescription,
2331
+ CardHeader,
2332
+ CardTitle,
2333
+ } from "@/components/ui/card"
2334
+ import {
2335
+ HoverCard,
2336
+ HoverCardContent,
2337
+ HoverCardTrigger,
2338
+ } from "@/components/ui/hover-card"
2339
+ import { Message, MessageContent } from "@/components/ui/message"
2340
+ import {
2341
+ MessageScroller,
2342
+ MessageScrollerButton,
2343
+ MessageScrollerContent,
2344
+ MessageScrollerItem,
2345
+ MessageScrollerProvider,
2346
+ MessageScrollerViewport,
2347
+ useMessageScroller,
2348
+ useMessageScrollerVisibility,
2349
+ } from "@/components/ui/message-scroller"
2350
+
2351
+ const chat = createChat()
2352
+ .user("Review the incident handoff and tell me what to read first.", {
2353
+ id: "vis-brief",
2354
+ })
2355
+ .assistant(
2356
+ "Start with the summary and the impact section. The regression affected the upload queue, but the recovery path completed for every queued job."
2357
+ )
2358
+ .user("What was the customer impact?", {
2359
+ id: "vis-impact",
2360
+ })
2361
+ .assistant(
2362
+ "Impact was limited to delayed processing.\n\nNo records were dropped, and the reconciliation worker confirmed each retry batch. Support saw confusion from two customers, but there were no checkout or billing errors."
2363
+ )
2364
+ .user("What actions are open?", {
2365
+ id: "vis-actions",
2366
+ })
2367
+ .assistant(
2368
+ "Keep the retry window enabled until the next deploy, then add a queue-depth alert as the long-term fix.\n\nThe alert should fire on sustained queue growth, not a single short spike."
2369
+ )
2370
+ .user("Give me the follow-up checklist.", {
2371
+ id: "vis-checklist",
2372
+ })
2373
+ .assistant(
2374
+ "After that, compare the queue recovery graph with the deploy timeline so the handoff shows exactly when processing returned to baseline. That makes it easier for support and engineering to answer the same customer questions without re-reading the whole incident thread.\n\nI would also add a short owner note beside each follow-up item. The checklist is small, but ownership keeps the retry-window decision, alert tuning, and support macro from drifting into separate follow-up conversations.\n\nKeep the retry window enabled until the next deploy, then add a queue-depth alert as the long-term fix.\n\nThe alert should fire on sustained queue growth, not a single short spike."
2375
+ )
2376
+
2377
+ const messages = chat.get()
2378
+ const userMessages = messages.filter((message) => message.role === "user")
2379
+
2380
+ export function MessageScrollerVisibility() {
2381
+ return (
2382
+ <MessageScrollerProvider scrollMargin={12}>
2383
+ <div className="relative flex flex-col gap-4">
2384
+ <div className="relative mx-auto w-full max-w-sm">
2385
+ <Card className="h-140 w-full gap-0">
2386
+ <CardHeader className="gap-1 border-b">
2387
+ <CardTitle>Transcript Outline</CardTitle>
2388
+ <CardDescription>
2389
+ Track the current anchored turn.
2390
+ </CardDescription>
2391
+ </CardHeader>
2392
+ <CardContent className="flex-1 overflow-hidden p-0">
2393
+ <MessageScroller>
2394
+ <MessageScrollerViewport>
2395
+ <MessageScrollerContent className="p-(--card-spacing)">
2396
+ {messages.map((message) => {
2397
+ const isUserMessage = message.role === "user"
2398
+ const text = getMessageText(message)
2399
+
2400
+ return (
2401
+ <MessageScrollerItem
2402
+ key={message.id}
2403
+ messageId={message.id}
2404
+ scrollAnchor={isUserMessage}
2405
+ >
2406
+ <Message align={isUserMessage ? "end" : "start"}>
2407
+ <MessageContent>
2408
+ <Bubble
2409
+ variant={isUserMessage ? "muted" : "ghost"}
2410
+ >
2411
+ <BubbleContent className="space-y-2">
2412
+ {text
2413
+ .split(/\n\s*\n/)
2414
+ .map((paragraph) => paragraph.trim())
2415
+ .filter(Boolean)
2416
+ .map((paragraph, index) => (
2417
+ <p
2418
+ key={index}
2419
+ className="whitespace-pre-wrap"
2420
+ >
2421
+ {paragraph}
2422
+ </p>
2423
+ ))}
2424
+ </BubbleContent>
2425
+ </Bubble>
2426
+ </MessageContent>
2427
+ </Message>
2428
+ </MessageScrollerItem>
2429
+ )
2430
+ })}
2431
+ </MessageScrollerContent>
2432
+ </MessageScrollerViewport>
2433
+ <MessageScrollerButton />
2434
+ </MessageScroller>
2435
+ </CardContent>
2436
+ </Card>
2437
+ <div className="absolute top-1/2 -right-12 -translate-y-1/2">
2438
+ <TranscriptOutline />
2439
+ </div>
2440
+ </div>
2441
+ <div className="mx-auto max-w-sm px-0.5 text-center text-xs text-muted-foreground">
2442
+ Open the outline to jump between anchored turns as you read.
2443
+ </div>
2444
+ </div>
2445
+ </MessageScrollerProvider>
2446
+ )
2447
+ }
2448
+
2449
+ function TranscriptOutline() {
2450
+ const { scrollToMessage } = useMessageScroller()
2451
+ const { currentAnchorId } = useMessageScrollerVisibility()
2452
+
2453
+ return (
2454
+ <HoverCard>
2455
+ <HoverCardTrigger
2456
+ render={
2457
+ <button
2458
+ type="button"
2459
+ aria-label="Open transcript outline"
2460
+ className="flex h-9 w-9 flex-col items-center justify-center gap-1 rounded-md transition-colors outline-none focus-visible:ring-3 focus-visible:ring-ring/50"
2461
+ />
2462
+ }
2463
+ >
2464
+ {userMessages.map((message) => (
2465
+ <span
2466
+ key={message.id}
2467
+ data-current={message.id === currentAnchorId}
2468
+ className="h-0.5 w-4 rounded-full bg-muted-foreground/40 data-[current=true]:bg-foreground"
2469
+ />
2470
+ ))}
2471
+ </HoverCardTrigger>
2472
+ <HoverCardContent
2473
+ align="center"
2474
+ side="left"
2475
+ sideOffset={-28}
2476
+ className="flex w-64 flex-col gap-1 rounded-2xl p-1"
2477
+ >
2478
+ {userMessages.map((message) => (
2479
+ <button
2480
+ key={message.id}
2481
+ type="button"
2482
+ aria-current={
2483
+ currentAnchorId === message.id ? "location" : undefined
2484
+ }
2485
+ className="flex min-h-7 items-center rounded-xl px-2 py-1.5 text-left text-sm transition-colors outline-none hover:bg-accent hover:text-accent-foreground focus-visible:bg-accent focus-visible:text-accent-foreground aria-current:bg-accent aria-current:text-accent-foreground"
2486
+ onClick={() =>
2487
+ scrollToMessage(message.id, {
2488
+ align: "start",
2489
+ behavior: "smooth",
2490
+ })
2491
+ }
2492
+ >
2493
+ <span className="line-clamp-1 min-w-0">
2494
+ {getTrimmedMessageText(message)}
2495
+ </span>
2496
+ </button>
2497
+ ))}
2498
+ </HoverCardContent>
2499
+ </HoverCard>
2500
+ )
2501
+ }
2502
+
2503
+ function getTrimmedMessageText(message: (typeof userMessages)[number]) {
2504
+ const text = getMessageText(message)
2505
+
2506
+ return text.length > 42 ? `${text.slice(0, 39)}...` : text
2507
+ }
2508
+
2509
+ ```
2510
+
2511
+ `currentAnchorId` answers "where am I" by reporting the current anchored turn,
2512
+ and it stays set after that anchor scrolls above the viewport. `visibleMessageIds`
2513
+ answers "what is on screen", in document order.
2514
+
2515
+ Visibility is pay-for-what-you-use. Tracking only runs while something
2516
+ subscribes to `useMessageScrollerVisibility`, and rows need a `messageId` to
2517
+ participate.
2518
+
2519
+ ### Reading Scroll State
2520
+
2521
+ Use `useMessageScrollerScrollable` when you need scroll state in JavaScript, such
2522
+ as a status indicator or a custom "jump to latest" control. It reports which
2523
+ edges the viewport can still scroll toward; "at the start/end" is the negation
2524
+ (`!start` / `!end`), and "scrollable at all" is `start || end`. For styling the
2525
+ scroller itself, prefer the `data-scrollable` attribute.
2526
+
2527
+ ```tsx
2528
+ import { useMessageScrollerScrollable } from "@/components/ui/message-scroller"
2529
+ ```
2530
+
2531
+ ```tsx
2532
+ const { start, end } = useMessageScrollerScrollable()
2533
+ ```
2534
+
2535
+ ```tsx
2536
+ "use client"
2537
+
2538
+ import { MessageAnimated } from "@/components/message-animated"
2539
+ import {
2540
+ Card,
2541
+ CardContent,
2542
+ CardDescription,
2543
+ CardFooter,
2544
+ CardHeader,
2545
+ CardTitle,
2546
+ } from "@/components/ui/card"
2547
+ import {
2548
+ MessageScroller,
2549
+ MessageScrollerButton,
2550
+ MessageScrollerContent,
2551
+ MessageScrollerProvider,
2552
+ MessageScrollerViewport,
2553
+ useMessageScrollerScrollable,
2554
+ } from "@/components/ui/message-scroller"
2555
+
2556
+ const messages = Array.from({ length: 12 }, (_, index) => ({
2557
+ id: `scrollable-${index + 1}`,
2558
+ role: index % 2 === 0 ? "user" : "assistant",
2559
+ text:
2560
+ index % 2 === 0
2561
+ ? `Review scroll checkpoint ${index + 1}.`
2562
+ : `Checkpoint ${index + 1} is synced. The scrollable hook updates as the viewport moves.\n\nWhen the reader is at the first message, the footer should only point them down. Once they move into the middle of the transcript, it should explain that both directions are available.\n\nAt the latest message, the footer should switch again and only point them back up.`,
2563
+ })) satisfies Array<{
2564
+ id: string
2565
+ role: "user" | "assistant"
2566
+ text: string
2567
+ }>
2568
+
2569
+ export function MessageScrollerScrollable() {
2570
+ return (
2571
+ <div className="mx-auto flex w-full max-w-sm flex-col gap-4">
2572
+ <Card className="h-140 w-full gap-0 overflow-hidden">
2573
+ <CardHeader className="gap-1 border-b">
2574
+ <CardTitle>Scroll Status</CardTitle>
2575
+ <CardDescription>
2576
+ Where the reader can go scroll to based on current scroll position.
2577
+ </CardDescription>
2578
+ </CardHeader>
2579
+ <MessageScrollerProvider defaultScrollPosition="start">
2580
+ <CardContent className="flex-1 overflow-hidden p-0">
2581
+ <MessageScroller>
2582
+ <MessageScrollerViewport>
2583
+ <MessageScrollerContent className="gap-4 p-(--card-spacing)">
2584
+ <Transcript />
2585
+ </MessageScrollerContent>
2586
+ </MessageScrollerViewport>
2587
+ <MessageScrollerButton />
2588
+ </MessageScroller>
2589
+ </CardContent>
2590
+ <ScrollStateFooter />
2591
+ </MessageScrollerProvider>
2592
+ </Card>
2593
+ <div className="px-0.5 text-center text-xs text-muted-foreground">
2594
+ Scroll the transcript to see the footer update.
2595
+ </div>
2596
+ </div>
2597
+ )
2598
+ }
2599
+
2600
+ function Transcript() {
2601
+ return messages.map((message) => (
2602
+ <MessageAnimated
2603
+ key={message.id}
2604
+ message={message}
2605
+ scrollAnchor={message.role === "user"}
2606
+ userVariant="muted"
2607
+ assistantVariant="ghost"
2608
+ />
2609
+ ))
2610
+ }
2611
+
2612
+ function ScrollStateFooter() {
2613
+ const { start, end } = useMessageScrollerScrollable()
2614
+
2615
+ const status = getScrollStatus({ start, end })
2616
+
2617
+ return (
2618
+ <CardFooter className="justify-center border-t text-center text-sm text-muted-foreground">
2619
+ {status}
2620
+ </CardFooter>
2621
+ )
2622
+ }
2623
+
2624
+ function getScrollStatus({ start, end }: { start: boolean; end: boolean }) {
2625
+ if (start && end) {
2626
+ return "You can scroll both ways."
2627
+ }
2628
+
2629
+ if (end) {
2630
+ return "You are at the top. You can only scroll down."
2631
+ }
2632
+
2633
+ if (start) {
2634
+ return "You are at the bottom. You can only scroll up."
2635
+ }
2636
+
2637
+ return "All messages fit in the viewport."
2638
+ }
2639
+
2640
+ ```
2641
+
2642
+ ## Performance
2643
+
2644
+ `MessageScroller` is benchmarked against large transcripts with markdown and
2645
+ composed message rows.
2646
+
2647
+ Our performance goal for `MessageScroller` is to keep the scroll hot path outside of React state: no React rerenders for
2648
+ transcript rows, no forced layout on every scroll, and as little off-screen paint
2649
+ work as the browser can avoid.
2650
+
2651
+ Scroll position, anchoring, and follow-output are tracked imperatively and mirrored onto the root and viewport through `data-*` attributes, so scrolling and streaming do not rerender transcript rows.
2652
+
2653
+ The styled `MessageScrollerItem` also ships with `content-visibility: auto` and
2654
+ `contain-intrinsic-size`. Rows stay in the DOM for selection, copy,
2655
+ find-in-page, SSR, and assistive tech, but the browser can skip rendering work
2656
+ for rows far outside the viewport.
2657
+
2658
+ Visibility tracking is pay-for-what-you-use. A jump menu or active
2659
+ turn indicator costs nothing until something subscribes to
2660
+ `useMessageScrollerVisibility`.
2661
+
2662
+ This is comfortable for the expected range of a chat transcript: hundreds to low
2663
+ thousands of turns, including messages with markdown and composed components.
2664
+
2665
+ ## Virtualization
2666
+
2667
+ Virtualization is intentionally left outside the primitive. `MessageScroller`
2668
+ renders real DOM rows and stays fast well into the thousands of turns (see
2669
+ [Performance](#performance)), so most transcripts never need it.
2670
+
2671
+ When a transcript is large enough to need virtualization, use
2672
+ `MessageScrollerViewport` as the scroll element and let the virtualizer own the
2673
+ rows.
2674
+
2675
+ ```tsx showLineNumbers
2676
+ import * as React from "react"
2677
+ import { useVirtualizer } from "@tanstack/react-virtual"
2678
+
2679
+ function VirtualizedTranscript({
2680
+ messages,
2681
+ }: {
2682
+ messages: Array<{ id: string; content: React.ReactNode }>
2683
+ }) {
2684
+ const viewportRef = React.useRef<HTMLDivElement>(null)
2685
+
2686
+ const virtualizer = useVirtualizer({
2687
+ count: messages.length,
2688
+ getScrollElement: () => viewportRef.current,
2689
+ estimateSize: () => 86,
2690
+ getItemKey: (index) => messages[index]?.id ?? index,
2691
+ overscan: 8,
2692
+ })
2693
+
2694
+ return (
2695
+ <MessageScrollerProvider>
2696
+ <MessageScroller>
2697
+ <MessageScrollerViewport ref={viewportRef}>
2698
+ <MessageScrollerContent className="block min-h-full">
2699
+ <div
2700
+ className="relative w-full"
2701
+ style={{ height: virtualizer.getTotalSize() }}
2702
+ >
2703
+ {virtualizer.getVirtualItems().map((virtualItem) => {
2704
+ const message = messages[virtualItem.index]
2705
+
2706
+ if (!message) {
2707
+ return null
2708
+ }
2709
+
2710
+ return (
2711
+ <div
2712
+ key={virtualItem.key}
2713
+ ref={virtualizer.measureElement}
2714
+ data-index={virtualItem.index}
2715
+ className="absolute start-0 top-0 w-full"
2716
+ style={{
2717
+ transform: `translateY(${virtualItem.start}px)`,
2718
+ }}
2719
+ >
2720
+ <Message>{message.content}</Message>
2721
+ </div>
2722
+ )
2723
+ })}
2724
+ </div>
2725
+ </MessageScrollerContent>
2726
+ </MessageScrollerViewport>
2727
+ <MessageScrollerButton />
2728
+ </MessageScroller>
2729
+ </MessageScrollerProvider>
2730
+ )
2731
+ }
2732
+ ```
2733
+
2734
+ ## Accessibility
2735
+
2736
+ `MessageScroller` keeps the scroll container keyboard reachable and the
2737
+ transcript announceable without forcing a specific message UI.
2738
+
2739
+ `MessageScrollerViewport` is a labelled, keyboard-focusable scroll region by
2740
+ default. It uses `role="region"`, `aria-label="Messages"`, and `tabIndex={0}`,
2741
+ so keyboard users can focus the transcript and scroll it directly.
2742
+
2743
+ `MessageScrollerContent` marks the transcript as a live region with
2744
+ `role="log"` and `aria-relevant="additions"`. New rows can be announced, but
2745
+ streamed text mutations do not have to be announced token by token.
2746
+
2747
+ ```tsx
2748
+ <MessageScrollerContent aria-busy={status === "streaming"}>
2749
+ {/* messages */}
2750
+ </MessageScrollerContent>
2751
+ ```
2752
+
2753
+ Pass `aria-busy` while a turn streams if announcements should wait for the
2754
+ completed message row.
2755
+
2756
+ `MessageScrollerButton` renders a real button. When there is nothing to scroll
2757
+ toward, it sets `inert`, uses `tabIndex={-1}`, and exposes `data-active="false"`
2758
+ so inactive scroll controls do not create extra focus stops.
2759
+
2760
+ ## Unstyled
2761
+
2762
+ The behavior in `MessageScroller` comes from the `@shadcn/react` package. To use
2763
+ it directly with your own markup and styles, see
2764
+ [Message Scroller](/docs/react/message-scroller) under @shadcn/react.
2765
+
2766
+ ## API Reference
2767
+
2768
+ The props, data attributes, and hooks for every part are documented on the
2769
+ [@shadcn/react Message Scroller](/docs/react/message-scroller#api-reference) page.
2770
+ They are identical for the styled component and the unstyled parts.