docs: add v0.6 migration guide (#960)

apps/docs/content/docs/migrations/deprecation-policy.mdx

@@ -0,0 +1,41 @@
+---
+title: Deprecation Policy
+---
+
+assistant-ui is committed to providing a stable API, so you can spend your time building amazing things on top of it.
+
+Rarely, we need to deprecate a feature we've already shipped, because it is causing performance, usability, or security issues.
+In such cases, we will communicate the intent to unship as soon as possible by marking the feature as `@deprecated` and publishing a notice in the documentation.
+
+Deprecations and breaking changes primarily affect new features released. The longer an API has been in the library, the less likely it is to be deprecated.
+For features that have long existed in the library, we will provider a longer deprecation notice period (as described below).
+
+Below is a list of features considered stable and those considered experimental.
+
+## Experimental Features
+
+These features may be removed at any time without notice.
+
+- Anything marked as `unstable_`, `experimental_`, or `internal`
+- The `RuntimeCore` API (conisdered internal)
+
+## Beta Features
+
+A deprecation of this features will undergo a short (<1) month deprecation notice period.
+
+- TailwindCSS Plugins (e.g. `@assistant-ui/react/tailwindcss`)
+- Context API
+- Runtime API
+- Message types
+- Styled UI components
+- Primitive Hooks (e.g. useBranchPickerNext)
+- Attachment APIs
+- shadcn-ui styles
+
+## Stable Features
+
+A deprecation of this features will undergo a long (>3 month) deprecation notice period.
+
+The following features are considered stable:
+
+- Primitives (except for `AttachmentPrimitive`)

apps/docs/content/docs/migrations/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "Migrations",
-  "pages": ["v0-5", "v0-4", "v0-3"]
+  "pages": ["deprecation-policy", "v0-6"]
 }

apps/docs/content/docs/migrations/v0-6.mdx

@@ -0,0 +1,163 @@
+---
+title: Migration to v0.6
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+<Callout type="info">
+  This migration guide is for the upcoming v0.6 release.
+</Callout>
+
+This guide serves as a reference for users facing breaking changes during upgrade to v0.6. You do not need to read this guide to upgrade to v0.6.
+
+All breaking changes in v0.6 are renames or removals of existing APIs. Therefore, all breaking changes should cause a Typescript error, so you can simply check for errors after upgrading.
+
+# Context API simplifications
+
+## `useThreadContext`, `useMessageContext`, ... replaced with direct imports of stores
+
+`useAssistantContext`, `useThreadContext`, `useMessageContext` and `useContentPartContext` have been removed in favor of direct exports from `@assistant-ui/react`;
+
+```diff
+-const { useThread } = useThreadContext();
+
++import { useThread } from "@assistant-ui/react";
+```
+
+# Assistant Context API simplifications
+
+## `useAssistantActions` replaced with `useAssistantRuntime`
+
+`useAssistantActions` has been removed in favor of `useAssistantRuntime`.
+
+```diff
+-const switchToNewThread = useAssistantActions(a => a.switchToNewThread);
++const runtime = useAssistantRuntime();
++runtime.switchToNewThread();
+```
+
+## `switchToThread(null)` replaced with `switchToNewThread()`
+
+```diff
+-useThreadRuntime().switchToThread(null);
++useThreadRuntime().switchToNewThread();
+```
+
+## `runtime.subscribe` removed, `subscribeToMainThread` removed
+
+Previously, you needed to subscribe to the runtime to receive updates whenever the main thread changed and resubscribe to the main thread whenever you switched to a new thread. The `runtime.thread` value now always refers to the current main thread, there is no need to subscribe to the runtime anymore.
+
+# ThreadRuntime API simplifications
+
+## `useThreadActions` replaced with `useThreadRuntime`
+
+`useThreadActions` has been removed in favor of `useThreadRuntime`.
+
+```diff
+-const reload = useThreadActions(a => a.reload);
++const threadRuntime = useThreadRuntime();
++threadRuntime.reload();
+```
+
+## State values moved to `threadRuntime.getState()`
+
+In order to make it clear that accessing the state only provides a snapshot of the current state and will not cause a re-render on changes, the state values of `useThreadRutnime` have been moved to `threadRuntime.getState()`.
+
+```diff
+-const isRunning = useThreadRuntime().isRunning; // anti-pattern, your code will not update on change
++const isRunning = useThread(t => t.isRunning);
+```
+
+## `useThreadStore` replaced with `useThreadRuntime().getState()`
+
+`useThreadStore` has been removed in favor of `useThreadRuntime().getState()`.
+
+## `threadRuntime.getBranches()` replaced with `useThreadRuntime().getMessageByIndex(idx).getState().branchNumber/Count`
+
+The branch IDs are an internal implementation detail. The new Message Runtime API provides `branchNumber` and `branchCount` state fields that can be used instead.
+
+## New Message Runtime API replaces several methods from `useThreadRuntime`
+
+A few methods from `useThreadRuntime` have been moved to `useMessageRuntime()`.
+
+- `threadRuntime.switchToBranch()` has been removed in favor of `useThreadRuntime().getMessageByIndex(idx).switchToBranch()`.
+- `threadRuntime.addToolResult()` has been removed in favor of `useThreadRuntime().getMessageByIndex(idx).getContentPartByToolCallId(toolCallId).addToolResult()`.
+- `threadRuntime.speak()` has been removed in favor of `useThreadRuntime().getMessageByIndex(idx).speak()`.
+- `threadRuntime.submitFeedback()` has been removed in favor of `useThreadRuntime().getMessageByIndex(idx).submitFeedback()`.
+- `threadRuntime.getEditComposer()` has been removed in favor of `useThreadRuntime().getMesssageById(id).getMessageByIndex(idx).composer`.
+- `threadRuntime.beginEdit()` has been removed in favor of `useThreadRuntime().getMesssageById(id).getMessageByIndex(idx).composer.beginEdit()`.
+
+# Composer Runtime API simplifications
+
+## Methods inside `useComposer` moved to `useComposerRuntime`
+
+`useComposer()` used to provide several methods such as `setText`, `addAttachment`, `send`, `edit`, `cancel`, ...
+These methods have been moved to `useComposerRuntime()`.
+
+## `useComposerStore` replaced with `useComposerRuntime().getState()`
+
+`useComposerStore` has been removed in favor of `useComposerRuntime().getState()`.
+
+## `value` `setValue` replaced with `text` `setText`
+
+```diff
+-useComposer(c => c.value);
++useComposer(c => c.text);
+```
+
+## `reset`, `focus`, `onFocus` methods removed
+
+These methods have been removed.
+
+# Message Context API simplifications
+
+## Flattened context values `useMessage().message` -> `useMessage()`
+
+`MessageState` is now itself a message, so you no longer need to access the nested `useMessage().message` field.
+
+```diff
+-useMessage(m => m.message.content);
++useMessage(m => m.content);
+```
+
+## `useMessageStore` replaced with `useMessageRuntime().getState()`
+
+`useMessageStore` has been removed in favor of `useMessageRuntime().getState()`.
+
+# Content Part Context API simplifications
+
+## Flattened context values `useContentPart().part` -> `useContentPart()`
+
+`ContentPartState` is now itself a content part, so you no longer need to access the nested `useContentPart().part` field.
+
+```diff
+-useContentPart(c => c.part.type);
++useContentPart(c => c.type);
+```
+
+This also applies to tool UI render functions:
+
+```diff
+ makeAssistantToolUI({
+   ...
+-  render: ({ part: { args } }) => <>{args}</>,
++  render: ({ args }) => <>{args}</>,
+ });
+```
+
+# Attachment Context API simplifications
+
+## Flattened context values `useAttachment().attachment` -> `useAttachment()`
+
+`AttachmentState` is now itself an attachment, so you no longer need to access the nested `useAttachment().attachment` field.
+
+```diff
+-useAttachment(a => a.attachment.type);
++useAttachment(a => a.type);
+```
+
+# Roundtrips rename to steps
+
+`AssistantMessage.roundtrips` was renamed to `AssistantMessage.metadata.steps`.
+
+Edge runtime's `maxToolRoundtrips` was replaced with `maxSteps` (which is `maxToolRoundtrips` + 1; if you had `maxToolRoundtrips` at 2, set `maxSteps` to 3).