feat(ai-orchestration): generator-based workflows + orchestrators

examples/ts-react-chat/package.json

@@ -21,6 +21,7 @@
     "@tanstack/ai-ollama": "workspace:*",
     "@tanstack/ai-openai": "workspace:*",
     "@tanstack/ai-openrouter": "workspace:*",
+    "@tanstack/ai-orchestration": "workspace:*",
     "@tanstack/ai-react": "workspace:*",
     "@tanstack/ai-react-ui": "workspace:*",
     "@tanstack/nitro-v2-vite-plugin": "^1.154.7",
@@ -41,6 +42,7 @@
     "rehype-raw": "^7.0.0",
     "rehype-sanitize": "^6.0.0",
     "remark-gfm": "^4.0.1",
+    "shiki": "^4.0.2",
     "tailwindcss": "^4.1.18",
     "vite-tsconfig-paths": "^5.1.4",
     "zod": "^4.2.0"

examples/ts-react-chat/src/components/ArticleModal.tsx

@@ -0,0 +1,120 @@
+import { useEffect } from 'react'
+
+interface Article {
+  title: string
+  paragraphs: Array<string>
+}
+
+export function ArticleModal(props: { article: Article; onClose: () => void }) {
+  // Close on Escape, lock body scroll while open.
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') props.onClose()
+    }
+    document.addEventListener('keydown', onKey)
+    const prev = document.body.style.overflow
+    document.body.style.overflow = 'hidden'
+    return () => {
+      document.removeEventListener('keydown', onKey)
+      document.body.style.overflow = prev
+    }
+  }, [props])
+
+  const date = new Date().toLocaleDateString('en-US', {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+  })
+
+  return (
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-label="Published article"
+      className="fixed inset-0 z-50 anim-log-in"
+    >
+      {/* backdrop */}
+      <div
+        onClick={props.onClose}
+        className="absolute inset-0 bg-ink/85 backdrop-blur-sm"
+      />
+
+      {/* page wrapper — scrollable */}
+      <div className="relative h-full overflow-auto px-4 sm:px-8 py-10 flex justify-center">
+        <article className="relative max-w-3xl w-full bg-cream text-ink shadow-[16px_16px_0_0_var(--color-citron)] my-4">
+          {/* paper grain */}
+          <div
+            className="absolute inset-0 pointer-events-none opacity-25 mix-blend-multiply"
+            style={{
+              backgroundImage:
+                "url(\"data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='200' height='200'><filter id='n'><feTurbulence type='fractalNoise' baseFrequency='1.2' numOctaves='2' stitchTiles='stitch'/></filter><rect width='100%' height='100%' filter='url(%23n)' opacity='0.6'/></svg>\")",
+            }}
+          />
+
+          {/* hazard tape header strip */}
+          <div className="tape-citron h-2.5" />
+
+          {/* close button */}
+          <button
+            onClick={props.onClose}
+            aria-label="Close"
+            className="absolute top-5 right-5 z-10 w-9 h-9 flex items-center justify-center bg-ink text-cream hover:bg-rust transition-colors label-mono"
+          >
+            ✕
+          </button>
+
+          <div className="relative px-8 sm:px-14 py-12">
+            {/* masthead */}
+            <div className="flex items-baseline justify-between border-b border-ink pb-3 mb-10">
+              <span className="label-mono text-rust">Published</span>
+              <span className="label-mono text-taupe-deep tabular">{date}</span>
+            </div>
+
+            <h1
+              className="text-[clamp(2.25rem,5.5vw,4.25rem)] leading-[0.96] tracking-tight mb-10"
+              style={{
+                fontFamily: 'var(--font-display)',
+                fontVariationSettings: "'opsz' 144, 'SOFT' 30, 'WONK' 1",
+              }}
+            >
+              {props.article.title}
+            </h1>
+
+            {/* article body — column layout for longer pieces */}
+            <div className="columns-1 md:columns-2 gap-10">
+              {props.article.paragraphs.map((p, i) => (
+                <p
+                  key={i}
+                  className={`mb-5 text-ink leading-[1.65] text-[17px] break-inside-avoid ${
+                    i === 0
+                      ? 'first-letter:float-left first-letter:text-7xl first-letter:font-bold first-letter:leading-[0.85] first-letter:mr-3 first-letter:text-rust'
+                      : ''
+                  }`}
+                  style={{
+                    fontFamily: 'var(--font-display)',
+                    fontVariationSettings: "'opsz' 17, 'SOFT' 100, 'WONK' 0",
+                  }}
+                >
+                  {p}
+                </p>
+              ))}
+            </div>
+
+            {/* colophon */}
+            <footer className="mt-14 pt-5 border-t border-ink/40 flex items-baseline justify-between label-mono text-taupe-deep">
+              <span>TanStack AI · Article Pipeline</span>
+              <span>—fin—</span>
+            </footer>
+          </div>
+
+          <div className="tape-citron h-2.5" />
+        </article>
+      </div>
+
+      {/* corner hint */}
+      <div className="absolute bottom-4 left-1/2 -translate-x-1/2 label-mono text-bone/60">
+        press esc or click outside to close
+      </div>
+    </div>
+  )
+}

examples/ts-react-chat/src/components/CodeBlock.tsx

@@ -0,0 +1,104 @@
+import { useEffect, useState } from 'react'
+import {
+  getHighlighter,
+  inferLangFromFilename,
+  normalizeLang,
+} from '@/lib/shiki/highlighter'
+
+interface CodeBlockProps {
+  code: string
+  /** Explicit language override; takes precedence over `filename`. */
+  lang?: string
+  /** Used to infer language when `lang` is omitted (e.g. `src/server.ts`). */
+  filename?: string
+  /** Optional cap; longer code renders a scrollable region. */
+  maxHeight?: string
+  /** Append a blinking caret while content is still streaming. */
+  streaming?: boolean
+  className?: string
+}
+
+/**
+ * Async-highlighted code block. Renders raw pre/code first (so the streaming
+ * patch text shows up immediately) then swaps to shiki's HTML output once the
+ * highlighter is ready and the language is loaded. Subsequent updates to
+ * `code` re-highlight without re-loading the highlighter.
+ *
+ * XSS note: the inner HTML below is the return value of shiki's `codeToHtml`,
+ * which runs the input through a textmate grammar and emits HTML-escaped
+ * tokens. The only attack surface would be a bug in shiki itself; the model-
+ * generated `code` string is otherwise opaque (no React render of raw user
+ * HTML happens).
+ */
+export function CodeBlock(props: CodeBlockProps) {
+  const lang = normalizeLang(
+    props.lang ?? inferLangFromFilename(props.filename),
+  )
+  const [html, setHtml] = useState<string | null>(null)
+  const [errored, setErrored] = useState(false)
+
+  useEffect(() => {
+    // Object wrapper so the cleanup closure can mutate without ESLint's
+    // no-unnecessary-condition narrowing the bool to `false` at the check
+    // sites (it doesn't see the deferred cleanup mutation).
+    const ctl = { cancelled: false }
+    void (async () => {
+      try {
+        const highlighter = await getHighlighter()
+        if (!highlighter.getLoadedLanguages().includes(lang)) {
+          await highlighter.loadLanguage(
+            lang as Parameters<typeof highlighter.loadLanguage>[0],
+          )
+        }
+        if (ctl.cancelled) return
+        const out = highlighter.codeToHtml(props.code, {
+          lang,
+          theme: 'tanstack-ink',
+        })
+        setHtml(out)
+      } catch {
+        if (!ctl.cancelled) setErrored(true)
+      }
+    })()
+    return () => {
+      ctl.cancelled = true
+    }
+  }, [props.code, lang])
+
+  const containerStyle: React.CSSProperties = {
+    maxHeight: props.maxHeight,
+  }
+
+  if (!html || errored) {
+    return (
+      <pre
+        className={
+          'font-mono text-[12.5px] leading-relaxed text-bone whitespace-pre-wrap bg-ink-soft/60 border-l-2 border-citron px-3 py-2 overflow-auto ' +
+          (props.className ?? '')
+        }
+        style={containerStyle}
+      >
+        {props.code}
+        {props.streaming && <span className="anim-blink text-citron">▌</span>}
+      </pre>
+    )
+  }
+
+  return (
+    <div
+      className={
+        'shiki-wrap text-[12.5px] leading-relaxed border-l-2 border-citron overflow-auto ' +
+        (props.className ?? '')
+      }
+      style={containerStyle}
+    >
+      {/* HTML produced by shiki — see XSS note in the component docblock. */}
+      <div dangerouslySetInnerHTML={{ __html: html }} />
+      {props.streaming && (
+        <div className="px-3 pb-2 -mt-2 bg-ink-soft/60">
+          <span className="anim-blink text-citron">▌</span>
+        </div>
+      )}
+    </div>
+  )
+}

examples/ts-react-chat/src/components/DraftPreview.tsx

@@ -0,0 +1,134 @@
+import { useEffect, useRef, useState } from 'react'
+
+interface Draft {
+  title?: string
+  paragraphs?: Array<string>
+}
+
+export function DraftPreview(props: {
+  draft: unknown
+  phase?: string
+  /** When true the draft is being assembled from a live structured-output stream. */
+  streaming?: boolean
+}) {
+  const draft = (
+    props.draft && typeof props.draft === 'object' ? props.draft : null
+  ) as Draft | null
+
+  // Pulse highlight when the draft content changes — gives a sense of life.
+  const [bumpKey, setBumpKey] = useState(0)
+  const lastSerialized = useRef('')
+  useEffect(() => {
+    const next = JSON.stringify(draft ?? {})
+    if (next !== lastSerialized.current) {
+      lastSerialized.current = next
+      setBumpKey((k) => k + 1)
+    }
+  }, [draft])
+
+  const hasContent =
+    draft && (draft.title || (draft.paragraphs && draft.paragraphs.length > 0))
+
+  return (
+    <aside className="relative">
+      <div className="flex items-baseline justify-between border-b border-bone pb-3 mb-4">
+        <div className="flex items-baseline gap-3">
+          <span className="label-mono text-bone">Draft Preview</span>
+          {props.streaming && (
+            <span className="label-mono text-citron anim-citron-pulse">
+              ◉ streaming
+            </span>
+          )}
+        </div>
+        <span className="label-mono text-taupe tabular">
+          {hasContent
+            ? `${(draft.paragraphs?.length ?? 0).toString().padStart(2, '0')} ¶`
+            : '—'}
+        </span>
+      </div>
+
+      <div className="relative bg-cream text-ink shadow-[8px_8px_0_0_var(--color-ink-soft)] border border-ink overflow-hidden">
+        {/* phase stamp */}
+        {props.phase && (
+          <div className="absolute top-3 right-3 px-2 py-0.5 bg-ink text-cream label-mono">
+            {props.phase}
+          </div>
+        )}
+
+        {/* paper grain */}
+        <div
+          className="absolute inset-0 pointer-events-none opacity-30 mix-blend-multiply"
+          style={{
+            backgroundImage:
+              "url(\"data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='160' height='160'><filter id='n'><feTurbulence type='fractalNoise' baseFrequency='1.4' numOctaves='2' stitchTiles='stitch'/></filter><rect width='100%' height='100%' filter='url(%23n)' opacity='0.5'/></svg>\")",
+          }}
+        />
+
+        <div
+          key={bumpKey}
+          className="relative px-6 py-7 max-h-[34rem] overflow-auto anim-log-in"
+        >
+          {!hasContent ? (
+            <Empty />
+          ) : (
+            <>
+              <div className="label-mono text-taupe-deep mb-3">
+                Draft № {String(bumpKey).padStart(2, '0')}
+              </div>
+              {draft.title && (
+                <h2
+                  className="text-[clamp(1.5rem,2.4vw,2rem)] leading-[0.98] tracking-tight mb-5"
+                  style={{
+                    fontFamily: 'var(--font-display)',
+                    fontVariationSettings: "'opsz' 144, 'SOFT' 30, 'WONK' 1",
+                  }}
+                >
+                  {draft.title}
+                </h2>
+              )}
+              {draft.paragraphs?.map((p, i) => {
+                const isLast = i === (draft.paragraphs?.length ?? 0) - 1
+                return (
+                  <p
+                    key={i}
+                    className={`mb-3.5 text-[14px] leading-[1.55] text-ink ${
+                      i === 0
+                        ? 'first-letter:float-left first-letter:text-5xl first-letter:font-bold first-letter:leading-[0.85] first-letter:mr-2 first-letter:text-rust'
+                        : ''
+                    }`}
+                    style={{
+                      fontFamily: 'var(--font-display)',
+                      fontVariationSettings: "'opsz' 14, 'SOFT' 100, 'WONK' 0",
+                    }}
+                  >
+                    {p}
+                    {props.streaming && isLast && (
+                      <span className="anim-blink text-rust ml-0.5">▌</span>
+                    )}
+                  </p>
+                )
+              })}
+            </>
+          )}
+        </div>
+      </div>
+    </aside>
+  )
+}
+
+function Empty() {
+  return (
+    <div className="py-10 text-center">
+      <div
+        className="text-3xl text-taupe-deep italic mb-2"
+        style={{
+          fontFamily: 'var(--font-display)',
+          fontVariationSettings: "'opsz' 96, 'SOFT' 80, 'WONK' 1",
+        }}
+      >
+        no draft yet.
+      </div>
+      <div className="label-mono text-taupe">awaiting writer</div>
+    </div>
+  )
+}