Merge branch 'main' into docs-sidebar-recency-pills

Author: AlemTuzlak

docs/partner-placement.md

@@ -0,0 +1,70 @@
+# Partner Placement
+
+Partner placement is split into three separate decisions:
+
+- **Eligibility:** whether a partner can appear for a surface, category, library, feature, or user context.
+- **Tier:** the partner's commercial/display tier, which controls visual treatment and relative access to surfaces.
+- **Order:** the sequence used inside a surface once eligible partners are known.
+
+The order policy should be explicit per surface. Avoid treating the partner array order or legacy score as the policy itself.
+
+## Order Strategies
+
+### `static-curated`
+
+Use for surfaces where the order is editorially or commercially curated and should remain stable. These surfaces can preserve the existing order, use partner seniority, or use private commercial priority when seniority is unavailable.
+
+Do not expose private commercial criteria in client-facing field names, comments, or API responses. If a private priority is required, keep the public/client value generic, such as `placementPriority` or an already-resolved ordered list.
+
+### `tier-rotated`
+
+Use for visible partner surfaces where partners in the same tier should cycle over time. Tier order remains fixed, but partners inside the same tier are selected with weighted-random ordering for each page view and surface.
+
+The root loader creates the initial page-view seed, so SSR and hydration receive the same value through loader data. A React provider owns the seed after hydration and refreshes it on client-side page views. Each surface combines its stable surface id with the page-view seed; avoid runtime-generated component ids in the seed because they can diverge across server and client rendering. Partners default to equal probability within their tier; a future `placementWeight` can bias same-tier odds without changing the ordering API.
+
+### `contextual-recommendation`
+
+Use when a surface behaves like a product recommendation or builder suggestion. Product fit should be established before commercial weighting affects order. This strategy currently preserves the legacy tier/priority behavior while giving recommendation surfaces a separate policy label.
+
+### `machine-readable`
+
+Use for AI- or crawler-facing outputs such as `llms.txt` and JSON feeds. These should be deterministic and relevance-first. Do not rotate them merely for logo fairness unless the downstream behavior has been designed and disclosed as such.
+
+## Reserved Rules
+
+Reserved rules should be narrow. For example, Cloudflare is reserved as the first deployment/hosting partner in any list that contains Cloudflare and other deployment partners. That should not imply Cloudflare is globally first across every partner surface; non-deployment partners can still appear before Cloudflare when the surface is mixed-category.
+
+Deployment action buttons are a deployment-only surface. Cloudflare remains first when present. Tier order is still preserved, and providers within the same tier can rotate by page view.
+
+## Current Surfaces
+
+- Partner directory: `tier-rotated` for active partners, `static-curated` for previous partners.
+- Partner grids and embeds: `tier-rotated`.
+- Docs and blog rails: `tier-rotated`.
+- Mobile docs strip: `tier-rotated`.
+- Builder feature picker and starter partner suggestions: `contextual-recommendation`.
+- Deploy action buttons: `tier-rotated` with deployment provider tiers preserved.
+- `llms.txt` and `/api/data/partners`: `machine-readable`.
+
+## Analytics
+
+Partner impression and click events should include:
+
+- `partner_id`
+- `placement`
+- `slot_index`
+- `partner_tier`
+- `order_strategy`
+- `rotation_seed` when the strategy rotates
+
+This lets reporting distinguish partner performance from placement policy and makes under/over-exposure easier to debug.
+
+## Contract Language
+
+Suggested external framing:
+
+> Partner tiers determine eligibility, visual treatment, reporting, and relative access to surfaces. Placement within the same tier may rotate or be curated depending on the surface. Some placements may include explicitly reserved rules for product, infrastructure, legal, or strategic reasons.
+
+For AI-assisted selection:
+
+> AI-assisted partner selection prioritizes user need and capability fit first. Partner tier may influence selection only among qualified options.

public/blog-assets/start-adds-rsbuild-support/header.jpg

@@ -0,0 +1,56 @@
+---
+published: 2026-06-02
+authors:
+  - Manuel Schiller
+title: 'TanStack Start Adds First-Class Rsbuild Support'
+excerpt: 'TanStack Start now supports Rsbuild 2 alongside Vite, so teams can choose the build tool that best fits their stack, preferences, and infrastructure.'
+library: start
+---
+
+![React Server Components](/blog-assets/start-adds-rsbuild-support/header.jpg)
+
+TanStack Start now supports Rsbuild 2 alongside Vite, giving teams two supported build-tool paths for Start.
+
+Some teams prefer Vite. Some prefer Rsbuild because it is built on Rspack, feels familiar to teams with Webpack experience, or matches how the rest of their frontend infrastructure is organized. The new adapter makes that choice explicit: Start fits into either build tool through its plugin system.
+
+We built the adapter together with the Rsbuild and Rspack team, and some of that work fed back into Rsbuild and Rspack along the way.
+
+For a React app, the config looks like this:
+
+```ts title='rsbuild.config.ts'
+import { defineConfig } from '@rsbuild/core'
+import { pluginReact } from '@rsbuild/plugin-react'
+import { tanstackStart } from '@tanstack/react-start/plugin/rsbuild'
+
+export default defineConfig({
+  plugins: [pluginReact(), tanstackStart()],
+})
+```
+
+React and Solid are supported today, and because the Rsbuild work lives at Start's shared build layer, future framework adapters have the same path available to them.
+
+Rsbuild owns the build, while the framework plugin handles React or Solid and `tanstackStart()` wires Start into both the client and server builds. If you have used Start with Vite, the pattern is intentionally familiar because the Start build-tool plugins are designed to fit naturally into the toolchain you choose.
+
+## A Start path for teams using Rsbuild
+
+Some teams want to use Start with Rsbuild because they want Rspack under the hood, a Webpack-familiar model, or a build tool that matches the rest of their stack.
+
+That also matters for existing apps. A team moving to Start can keep more of its build setup in place instead of changing framework and build tool at once. One large company is already using the adapter while moving several apps from a Webpack setup to Start on Rsbuild.
+
+That path includes the full Start feature set, including React and Solid apps, Server Functions, SSR and streaming SSR, HMR, import protection, and React Server Components for React apps.
+
+## The two-adapter rule
+
+There is a pattern we keep running into at TanStack: the first adapter proves something can work, and the second adapter shows which parts actually belong in the core.
+
+TanStack Router and TanStack Start already went through this once at the UI framework layer, where adding Solid made the React assumptions easier to see and improved the shared core. Adding Rsbuild brought the same clarity to the build layer.
+
+Because the first Start build adapter was Vite, some build logic naturally grew around Vite's plugin lifecycle, and adding Rsbuild made the boundary sharper: shared Start build behavior in one place, build-tool-specific behavior in the Vite and Rsbuild adapters.
+
+## Your build tool, your choice
+
+Choosing Start should let a team keep its preferred build tool. With Vite and Rsbuild both supported, teams can use the toolchain that fits their stack while building the same kind of Start app.
+
+Teams that prefer Rsbuild, or already work in the Webpack and Rspack world, now get a native Start integration through Rsbuild's plugin system.
+
+The Rsbuild adapter is available now. Try it in a new Rsbuild project or in an existing codebase moving to Start.

src/blog/start-adds-rsbuild-support.md

@@ -29,29 +29,6 @@ This is where you come in. We need your help. We need people to test out our wor
 
 The goal is simple: compose multiple typed LLM and agent steps as normal TypeScript async generators, stream each step to the UI, pause for human approval, and resume through the same SSE flow.
 
-## Try the PR build
-
-Install the PR packages directly from pkg.pr.new:
-
-```bash
-npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-orchestration@542
-npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai@542
-npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-react@542
-npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-client@542
-npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-openai@542
-```
-
-Use this only for evaluation, demos, and feedback. The public API can still change before stabilization.
-
-Full documentation for this PR lives on the GitHub branch, not the released TanStack docs site:
-
-- [Overview](https://github.com/TanStack/ai/blob/worktree-cryptic-singing-wadler/docs/orchestration/overview.md)
-- [Workflows guide](https://github.com/TanStack/ai/blob/worktree-cryptic-singing-wadler/docs/orchestration/workflows.md)
-- [Orchestrators](https://github.com/TanStack/ai/blob/worktree-cryptic-singing-wadler/docs/orchestration/orchestrators.md)
-- [Approvals](https://github.com/TanStack/ai/blob/worktree-cryptic-singing-wadler/docs/orchestration/approvals.md)
-- [Run persistence](https://github.com/TanStack/ai/blob/worktree-cryptic-singing-wadler/docs/orchestration/run-persistence.md)
-- [API reference](https://github.com/TanStack/ai/blob/worktree-cryptic-singing-wadler/docs/api/ai-orchestration.md)
-
 ## Define your agents
 
 Agents are typed wrappers around a `chat()` call or any async function. `defineAgent` gives each step an input schema, output schema, and implementation.
@@ -85,25 +62,23 @@ export const writer = defineAgent({
     }),
 })
 
+export const EditorReviewSchema = z.object({
+  approved: z.boolean(),
+  article: ArticleSchema,
+  notes: z.string(),
+})
+
 export const editor = defineAgent({
   name: 'editor',
   input: z.object({
     article: ArticleSchema,
     feedback: z.string().optional(),
   }),
-  output: z.object({
-    approved: z.boolean(),
-    article: ArticleSchema,
-    notes: z.string(),
-  }),
+  output: EditorReviewSchema,
   run: ({ input }) =>
     chat({
       adapter: openaiText('gpt-4o'),
-      outputSchema: z.object({
-        approved: z.boolean(),
-        article: ArticleSchema,
-        notes: z.string(),
-      }),
+      outputSchema: EditorReviewSchema,
       stream: true,
       systemPrompts: [
         'Edit the article for accuracy, clarity, and practical developer tone. Apply any optional reviewer feedback.',
@@ -129,11 +104,11 @@ import {
 import { z } from 'zod'
 import { ArticleSchema, editor, writer } from './agents'
 
-const ArticleInputSchema = z.object({
+export const ArticleInputSchema = z.object({
   topic: z.string(),
 })
 
-const ArticleWorkflowOutputSchema = z.discriminatedUnion('ok', [
+export const ArticleWorkflowOutputSchema = z.discriminatedUnion('ok', [
   z.object({
     ok: z.literal(true),
     article: ArticleSchema,
@@ -174,13 +149,13 @@ export const articleWorkflow = defineWorkflow({
 })
 ```
 
-The interesting part is the lack of framework ceremony. TypeScript knows the input expected by `agents.writer`, and it knows the shape returned after the `yield*`. The runtime can emit lifecycle events around each yielded step, stream text while it runs, validate the result, snapshot state, and resume the generator with the typed output.
+The interesting part is the lack of framework ceremony. TypeScript knows the input expected by `agents.writer`, and it knows the shape returned after the `yield*`.
 
-Why async generator workflows? There are a lot of ways to model agent workflows. You can build a graph DSL. You can define nodes in JSON. You can describe a DAG and ask the runtime to interpret it. Well, the reason we decided to go with generator workflows is because whenever you yield the agent's step, it's streamed straight down to the client. The user sees everything in real time, and then, by the end of it, you just get the final output back. The user saw everything that went on: tool calls, reasoning, whatever.
+Each `yield* agents.someAgent(...)` becomes a typed step. The runtime can emit lifecycle events around it, stream text while it runs, validate the result, snapshot state, and resume the generator with the typed output.
 
 The workflow body is just TypeScript. Use `if`, `for`, `while`, `try`, `await`, helper functions, and whatever domain code you already have. The orchestration runtime only cares about the things you `yield*`.
 
-Each `yield* agents.someAgent(...)` becomes a typed step. The runtime can emit lifecycle events around it, stream text while it runs, validate the result, snapshot state, and resume the generator with the typed output.
+Why async generator workflows? There are a lot of ways to model agent workflows. You can build a graph DSL. You can define nodes in JSON. You can describe a DAG and ask the runtime to interpret it. The reason we went with generator workflows is that whenever you yield the agent's step, it's streamed straight down to the client. The user sees everything in real time — tool calls, reasoning, whatever happens along the way — and by the end you just get the final output back.
 
 ## Expose it over SSE
 
@@ -215,33 +190,57 @@ export async function POST(request: Request) {
 
 The current built-in persistence is `inMemoryRunStore`. That is useful for local demos and single-process evaluation. Production durability is still future-facing and experimental run-store-interface territory, especially for long pauses, deploys, restarts, and multi-node environments. But the API is there to implement your own durable run store and swap it in when you're ready.
 
+## Run it without a UI
+
+A UI is optional. The SSE endpoint above exists so a browser can watch a run unfold, but the workflow itself is just a server-side async generator. If nothing is watching — a cron job, a queue worker, a batch script, or a plain JSON endpoint that only returns the final answer — you can run the workflow headless and never stream a single event to a client.
+
+`runWorkflow` returns an async iterable, and iterating it is what drives the workflow forward. So for a headless run you drain the stream to completion, then read the final result back from the run store:
+
+```typescript
+import { inMemoryRunStore, runWorkflow } from '@tanstack/ai-orchestration'
+import { articleWorkflow } from './article-workflow'
+
+const runStore = inMemoryRunStore({ ttl: 60 * 60 * 1000 })
+
+export async function generateArticle(topic: string) {
+  const runId = crypto.randomUUID()
+
+  const stream = runWorkflow({
+    workflow: articleWorkflow,
+    runStore,
+    runId,
+    input: { topic },
+  })
+
+  // No client is listening, so just drive the run to completion.
+  for await (const _event of stream) {
+    // Optionally log progress or persist events here.
+  }
+
+  const run = await runStore.getRunState(runId)
+
+  if (run?.status === 'finished') {
+    return run.output
+  }
+
+  throw new Error(run?.error?.message ?? `Workflow ended as "${run?.status}"`)
+}
+```
+
+The same typed agents, schemas, state snapshots, and validation apply. You just skip `toServerSentEventsResponse`, the React hooks, and the browser entirely.
+
+One caveat: a headless run has nobody to answer a `yield* approve(...)`. If the workflow hits an approval step, it pauses and `getRunState` reports `status: 'paused'` instead of `'finished'`. Server-only workflows shine when the pipeline runs end to end on its own. If you need a human in the loop, either resume the paused run programmatically with an `approval` result or keep a UI connected.
+
 ## Consume it from React
 
 On the client, `WorkflowClient`, `useWorkflow`, and `useOrchestration` consume the streamed events and keep local run state updated.
 
 ```tsx
 import { fetchWorkflowEvents, useWorkflow } from '@tanstack/ai-react'
-import { z } from 'zod'
-
-const ArticleSchema = z.object({
-  title: z.string(),
-  body: z.string(),
-})
-
-const ArticleInputSchema = z.object({
-  topic: z.string(),
-})
-
-const ArticleWorkflowOutputSchema = z.discriminatedUnion('ok', [
-  z.object({
-    ok: z.literal(true),
-    article: ArticleSchema,
-  }),
-  z.object({
-    ok: z.literal(false),
-    reason: z.string(),
-  }),
-])
+import {
+  ArticleInputSchema,
+  ArticleWorkflowOutputSchema,
+} from './article-workflow'
 
 export function ArticleWorkflowDemo() {
   const workflow = useWorkflow({
@@ -384,6 +383,10 @@ import {
 } from '@tanstack/ai-orchestration'
 import { z } from 'zod'
 import { ArticleSchema, editor, writer } from './agents'
+import {
+  ArticleInputSchema,
+  ArticleWorkflowOutputSchema,
+} from './article-workflow'
 
 const ArticleStateSchema = z.object({
   draft: ArticleSchema.optional(),
@@ -439,27 +442,27 @@ Routers may also yield if their decision needs async work, but their return valu
 
 That gives you the same behavior with a different control-flow style. A workflow puts the sequence directly in the generator body. An orchestrator puts the next-step decision in a router.
 
-## What is still experimental?
-
-Almost everything important enough to name.
-
-The package name is `@tanstack/ai-orchestration`, the public feature name is TanStack AI Workflows & Orchestrators, and the core shape is visible in PR 542. But this is still a PR build.
-
-Expect scrutiny around:
+## Try it and send feedback
 
-- API names and return shapes
-- Durable persistence beyond `inMemoryRunStore`
-- Resume behavior across deploys and multiple server nodes
-- Event naming and AG-UI compatibility details
-- How much of the run-store interface should be public now
-- How examples should guide production usage without overstating guarantees
+If you are building multi-step AI product flows, this is the moment to test the shape. This is a PR build meant for evaluation, demos, and feedback — the public API can still change before stabilization.
 
-The current implementation is useful enough to try and early enough to change.
+Install the PR packages directly from pkg.pr.new:
 
-## Try it and send feedback
+```bash
+npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-orchestration@542
+npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai@542
+npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-react@542
+npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-client@542
+npm i https://pkg.pr.new/TanStack/ai/@tanstack/ai-openai@542
+```
 
-If you are building multi-step AI product flows, this is the moment to test the shape.
+Full documentation for this PR lives on the GitHub branch, not the released TanStack docs site:
 
-Try the [PR build packages](https://github.com/TanStack/ai/pull/542#issuecomment-4416347869). Read the branch docs for [workflows](https://github.com/TanStack/ai/blob/worktree-cryptic-singing-wadler/docs/orchestration/workflows.md), [orchestrators](https://github.com/TanStack/ai/blob/worktree-cryptic-singing-wadler/docs/orchestration/orchestrators.md), [approvals](https://github.com/TanStack/ai/blob/worktree-cryptic-singing-wadler/docs/orchestration/approvals.md), [run persistence](https://github.com/TanStack/ai/blob/worktree-cryptic-singing-wadler/docs/orchestration/run-persistence.md), and the [API reference](https://github.com/TanStack/ai/blob/worktree-cryptic-singing-wadler/docs/api/ai-orchestration.md).
+- [Overview](https://github.com/TanStack/ai/blob/worktree-cryptic-singing-wadler/docs/orchestration/overview.md)
+- [Workflows guide](https://github.com/TanStack/ai/blob/worktree-cryptic-singing-wadler/docs/orchestration/workflows.md)
+- [Orchestrators](https://github.com/TanStack/ai/blob/worktree-cryptic-singing-wadler/docs/orchestration/orchestrators.md)
+- [Approvals](https://github.com/TanStack/ai/blob/worktree-cryptic-singing-wadler/docs/orchestration/approvals.md)
+- [Run persistence](https://github.com/TanStack/ai/blob/worktree-cryptic-singing-wadler/docs/orchestration/run-persistence.md)
+- [API reference](https://github.com/TanStack/ai/blob/worktree-cryptic-singing-wadler/docs/api/ai-orchestration.md)
 
 Then share demos, feedback, and rough edges on [PR 542](https://github.com/TanStack/ai/pull/542) before the API stabilizes.