18 per-framework MDX pages had the closing half of a multi-line
import statement left at the top of the file (the orphaned
"Symbol1, Symbol2, } from '...'" tail with the opening "import {"
line missing). The current sync-docs-from-main import stripper
handles multi-line imports correctly, so this was a historical
artifact from an earlier stripper version that misparsed them —
every affected file predates that fix.
MDX treats the orphan as plain text, so pages rendered the
identifier list and "} from ..." string as visible garbage at the
top before the real content started. Strip the orphan blocks; future
syncs won't re-introduce them.
The MDX registry had TailoredContent and TailoredContentOption
stubbed as passthrough <div>{children}</div> wrappers. MDX pages
author these as a variant-switcher (e.g. on Readables:
"Custom graph" vs "Prebuilt agent" paths for LangGraph setup), so
the stub rendered both option paths stacked — the same useAgentContext
example, the same steps, effectively duplicating multi-hundred-line
sections on every page that uses the component.
Swap the stubs for the real implementation at
components/react/tailored-content.tsx, which has been in the repo
since the shell-docs move but was never wired in. The real component
renders only the selected option and persists the choice in a URL
search param (?impl=graph / ?impl=prebuilt).
Registry slugs don't always match the integrations/<folder>/ name on
disk. Three LangChain/LangGraph variants (langgraph-python, langgraph-
typescript, langgraph-fastapi) read from the single langgraph/ tree,
ms-agent-dotnet and ms-agent-python share microsoft-agent-framework/,
and google-adk/strands are legacy renames that point at adk/ and
aws-strands/ respectively.
Before: the framework-scoped router, the sidebar-override nav
builder, and the "not available for this framework" fallback all
used the URL slug directly as a folder name, so any of the seven
mismatched slugs showed empty sidebars, 404s on framework-unique
pages (/langgraph-python/auth, /ms-agent-dotnet/auth), and missing
'available in other integrations' matches.
After: lib/registry exposes getDocsFolder(slug) backed by a small
DOCS_FOLDER_OVERRIDES table. Callers resolve the URL slug to its
actual folder before touching disk; findFrameworksWithPage takes the
resolver as a parameter so docs-render stays registry-free.
Per-page variant selectors authored as <Tabs groupId="..." default="Python">
now open with the URL-matching tab preselected instead of the author's
hardcoded default. getTabDefault(slug, groupId) reads
TAB_DEFAULTS_BY_SLUG; a wrapper in DocsPageView's MDX components map
injects the resolved value into <Tabs> via a 'default' prop alias.
/langgraph-typescript/configurable opens TypeScript, /ms-agent-dotnet/
auth opens .NET, /langgraph-fastapi/deep-agents opens FastAPI. Slugs
and groupIds without a mapping fall through to the existing behavior
(author default, then first items label).
Every framework under integrations/<fw>/ shipped its own copy of
contributing/ + telemetry/ content that was byte-identical (or
trivially divergent — a stray "cd" path, a legacy CLI name) to the
canonical copy at root (other)/. The duplicates were stale sync
artifacts with no framework-specific content: "how to contribute to
CopilotKit" and "how to configure telemetry" don't vary by agent
framework.
Beyond disk clutter (~2.5k lines across 8 frameworks), the duplicates
surfaced as a "Other" group nested under the framework-scoped
sidebar section whenever the merged nav built from meta.json — a
second copy of root's own "Other" section at the bottom of the
sidebar. Deleting the trees makes that UI bug disappear without any
filter patching.
Scope:
- Remove integrations/<fw>/(other)/ trees for ag2, agno, aws-strands,
crewai-flows, langgraph, llamaindex, mastra, microsoft-agent-framework.
- Drop ---Other--- + ...(other) entries from each framework's meta.json.
- Add a path-exclusion filter in sync-docs-from-main.ts so the next
sync run doesn't resurrect the subtrees when upstream edits touch
them. Upstream keeps its copies (removing them there means touching
all 13 parallel framework trees, out of scope for this branch).
The docs landing page and sidebar framework-selector both gated a
grayed-out card state and a "soon" label on integration.deployed.
That flag tracks whether a live showcase demo with tagged cells
exists — a showcase concern, not a docs concern. Built-in Agent has
ready docs even though no showcase package is published yet, so the
card was incorrectly rendered as "coming soon" and stayed visually
inert after clearing the stored framework.
Every integration that ships docs should be pickable from these
surfaces with the same visual weight. The deployed flag continues to
drive the showcase app, router-pivot filtering, and snippet cell
assertions — this change only touches the two docs-picker call sites.
Before this change, visiting /<framework>/<slug> for a topic that only
exists under integrations/<other-framework>/ returned a bare 404 — for
example, /mastra/advanced-configuration (the page only lives under
integrations/built-in-agent/).
Now the router checks whether the slug exists in any other integration
and renders a framework-scoped fallback page inside the docs shell:
sidebar and framework switcher stay intact, and the body lists the
integrations where the topic does exist with direct links. Genuine
unknown slugs still 404.
New helper findFrameworksWithPage walks integrations/<slug>/ for each
registered framework. NotAvailableForFrameworkPage renders the shell
around the fallback body. Nav tree build is hoisted so both the happy
path and the fallback share one source.
Per-framework meta.json files (mastra, langgraph, llamaindex, etc.)
mirror the root tree's section names ("Getting Started", "Basics").
Passing them through buildFrameworkOverridesNav into the merged
sidebar caused duplicate React keys when the merge ran — every root
section collided with the override's copy of the same title.
The override block is already wrapped in a single "{frameworkName}"
section by mergeFrameworkNav, so nested section headers added no
information anyway. Drop them at the filter step.
Registers Built-in Agent as a framework in the registry and wires up
a router + sidebar-nav pattern so its content can live at /built-in-agent/*
without needing a dedicated per-framework content tree for every topic.
Content model:
- Root MDX pages (/quickstart, /frontend-tools, /shared-state, etc.) are
the canonical home for framework-agnostic topics. Rendered at
/built-in-agent/<slug> via the existing framework-override mechanism.
- integrations/built-in-agent/*.mdx is the escape hatch for topics that
are genuinely BIA-specific (copilot-runtime, server-tools, mcp-servers,
model-selection, advanced-configuration, custom-agent). The router
falls back to these when no root equivalent exists.
- Root wins when both exist.
Changes:
- shared/manifest.schema.json: add 'built-in' to the category enum.
- shared/packages.json: register built-in-agent slug.
- packages/built-in-agent/manifest.yaml: new. deployed:false (showcase
package TBD in a follow-up), sort_order:0, category:popular so it
appears at the top of the framework dropdown.
- public/logos/built-in-agent.svg: new logo asset (extracted from the
inline CopilotKit mark in brand-nav.tsx).
- shell-docs/src/app/[framework]/[[...slug]]/page.tsx: router gains a
fallback to integrations/<framework>/<slug>.mdx when the root file
doesn't exist. Sidebar nav merges in per-framework overrides as a
labeled section positioned after 'App Control' (mirrors upstream's
integrations/built-in-agent/meta.json ordering).
- shell-docs/src/components/docs-page-view.tsx: new optional
contentSlugPath prop lets the router thread through the override
content path without changing the URL-slug used for breadcrumbs and
active-link detection.
- shell-docs/src/lib/docs-render.tsx: new buildFrameworkOverridesNav
helper that walks integrations/<framework>/* and filters out pages
that already exist at root.
The agent system prompt instructed the LLM to return <ui>...</ui> XML markup,
but the frontend renderer uses useJsonParser(message.content, kit.schema)
which expects a JSON object matching createUiKit(...).schema:
{
"ui": [
{ "metric": { "props": { "label": "...", "value": "..." } } },
{ "pieChart": { "props": { "title": "...", "data": "[{...}]" } } },
...
]
}
The XML syntax in useUiKit({ examples }) is hashbrowns prompt DSL for when
hashbrown drives the LLM directly (e.g. useUiChat); because this demo drives
the LLM via langgraph, the agent itself must emit the JSON wire format. With
XML content, useJsonParser returned { value: undefined } and the renderer
bailed to null, leaving the chat with only a loading indicator.
Rewrote the system prompt to produce the JSON envelope and updated the
renderer top-of-file docstring to match. Prop schemas tracked from the
current kit (metric: label+value, pieChart/barChart: title+data-as-JSON-string,
dealCard: title+stage+value, Markdown: children).
The multimodal demo failed three ways:
1. Try-with-sample-image rendered a broken thumbnail because the sample
PNG on disk is a Git LFS pointer stub when LFS is not pulled at build
time. The browser base64-encoded the 130-byte text stub, fed it into
the chat as a valid-looking image/png, and CopilotChat rendered it
as a broken <img>.
2. Try-with-sample-pdf attached in the composer but the agent said
"no image/document attached". Same broken-image pipeline also hid the
real symptom: the published @ag-ui/langgraph converter (0.0.x) only
understands the legacy { type: binary, mimeType, data | url }
AG-UI content-part shape. The modern { type: image | document,
source: {...} } parts CopilotChat emits are silently filtered out of
the LangChain message stream, so the LangGraph agent never saw them.
3. Manual drag-and-drop of an image failed for the same reason as #2.
Fixes:
- sample-attachment-buttons.tsx: reject Git LFS pointer stubs and
validate PNG/PDF magic bytes on the client before feeding them to the
attachment queue. Surfaces an actionable error pointing at
git-lfs-pull instead of silently producing a broken thumbnail.
- page.tsx: install an onRunInitialized subscriber on the active agent
that rewrites outgoing user-message image / document / audio / video
parts to the legacy binary shape the runtime converter preserves.
Everything else (CopilotChat UI, useAttachments upload pipeline,
paperclip + drag-drop + paste paths) is untouched; we only retarget
the wire format so the LangGraph side receives the attachment.
- multimodal_agent.py: after the rewrite, attachments arrive in the
agent as LangChain image_url content parts (data URLs) regardless of
upstream modality. Route on MIME instead of the AG-UI part type:
image/* forwards to GPT-4o natively, application/pdf is flattened to
text via pypdf. The modern document shape is still handled for
forward-compat when the runtime is upgraded.
Verified: classifier helpers pass inline unit checks; tsc --noEmit
introduces no new type errors relative to HEAD (module-resolution
errors for @copilotkit/shared and lucide-react are pre-existing on this
branch and unrelated to the multimodal demo).
## Summary
On integration profile pages (e.g. `/integrations/langgraph-python`),
the `cli-start` demo entry — which has a `command` field instead of a
`route` — was being rendered inside the Live Demos grid. Clicking it
opened `DemoDrawer` with an undefined `demoRoute`, so the iframe tried
to load `${backend_url}undefined`.
This PR:
- Splits `integration.demos` into `liveDemos` (runnable, have `route`)
and `commandDemos` (CLI-only, have `command`).
- Filters command-only entries out of the Live Demos grid.
- Adds a new **Get Started** section above Live Demos that renders each
`commandDemos` entry as a description + copy-able `<code>` block
(mirrors how `shell-dashboard` already handles these via `CommandCell`).
- Makes `Demo.route` optional and adds `Demo.command?: string` on the
`Demo` type.
Only `langgraph-python` currently has a command-only demo, so this is
the only profile page that changes visibly.
## Test plan
- [x] Ran `showcase/shell` dev server, visited
`/integrations/langgraph-python`, confirmed:
- New "Get Started" card shows `npx copilotkit@latest init --framework
langgraph-python` with a working Copy button.
- "Live Demos" grid no longer contains the broken "CLI Start Command"
tile.
- Other integrations (no `command` demos) render unchanged — Live Demos
still present, no empty "Get Started" section.
- [x] Pre-commit hooks (lint-fix, check-binaries,
test-and-check-packages — 1149 tests, commitlint) all pass.
Starting the /demos/auth cell unauthenticated meant the initial `/info`
handshake from CopilotKit returned 401 before any React error handler
could attach, crashing the page on load. Flip the default so the demo
mounts already signed in — the chat is immediately usable — and expose
Sign out / Sign in as the toggle for exercising the 401 path.
- use-demo-auth: default state flipped from unauthed to authed so the
page mounts with a valid Bearer header.
- page.tsx: add a ChatErrorBoundary around <CopilotChat /> that catches
any render-time throw from chat internals after signing out and shows
a friendly in-page message instead of white-screening. The boundary
resets on auth transitions so signing back in restores a live chat.
- auth-banner: rename Authenticate -> Sign in; status copy updated to
Signed in / Signed out to match the inverted default.
- tests/e2e/auth.spec.ts: flip assertions — page loads authenticated,
sign out triggers 401 on next send with banner still mounted, and
sign in clears the error and restores successful sends.
- qa/auth.md: refreshed checklist for the authenticated-default flow.
V1 CopilotRuntime wrapper silently drops `transcriptionService`, so the
composer never saw the mic button on /voice. Write it onto the V2 runtime
instance directly, and wrap the OpenAI service with a guard that throws an
"api key missing" error when OPENAI_API_KEY is absent (mapped by the
runtime error categorizer to AUTH_FAILED / 401) instead of the opaque 503
users were hitting.
Clicking any suggestion in the byoc-json-render demo crashed with
"useVisibility must be used within a VisibilityProvider". Renderer from
@json-render/react relies on StateProvider, VisibilityProvider,
ValidationProvider, and ActionProvider contexts that its internal
ElementRenderer consumes, but the assistant-message slot was rendering
Renderer bare.
Wrap it in JSONUIProvider (which composes all four required providers)
so streamed spec output renders without a context crash.
Also pass children through the MetricCard catalog wrapper. The agent's
Sales Dashboard worked example uses a MetricCard as the root with a
BarChart nested in its children array; previously that chart was
silently dropped by the registry wrapper, which only rendered the
MetricCard itself.
Wrap PieChart + BarChart with string-accepting wrappers that JSON-parse the
data prop, and change the hashbrown schema from s.streaming.array(...) to
s.string(). Drop the non-schema example props (trend on metric, assignee
+ dueDate on dealCard).
Wave 4a was ported from the starter, which used an older hashbrown where:
- optional props were declared via .optional()
- array props accepted stringified JSON in example JSX attributes
@hashbrownai/core@0.5.0-beta.4 dropped .optional() (props omitted from the
schema are treated as not-present) AND tightened example-prompt validation
to reject strings against array schemas. The build failed at prerender:
Error: Example prompt has 5 errors:
Prop 'trend' is not defined on <metric>
Prop 'data' on <pieChart>: Expected an array at: <root>
Prop 'data' on <barChart>: Expected an array at: <root>
Prop 'assignee' is not defined on <dealCard>
Prop 'dueDate' is not defined on <dealCard>
Modeling data as a string matches how the LLM streams it anyway (JSON
tokens through useJsonParser), and the wrappers are defensive about
partial tokens — they render nothing if the parse fails mid-stream.
Review feedback from #4196:
- `[slug]/[demo]/page.tsx` constructed `${backend_url}${demo.route}`
without a null check, so command-only demos (which have no `route`)
rendered an iframe pointing at `${backend_url}undefined`. Now builds
the src only when `demo.route` exists and renders a 'no live preview'
panel otherwise, mirroring the Get Started section on the profile
page. Also replaces the `any`-typed state with proper `Demo` and
`Integration` types imported from `@/lib/registry`.
- `[slug]/[demo]/preview/page.tsx` had the same bug — already typed
but TypeScript doesn't catch template-literal coercion of undefined.
Now bails with a command-focused message before concatenating.
- `profile-client.tsx` no longer duplicates `Demo`/`Integration`
interfaces — deleted the local copies and imports from
`@/lib/registry`. copyDemoCommand's catch now logs the failure so a
double-failure (no clipboard API + blocked prompt) is diagnosable.
Comment above the live-demos section updated from 'Demos' to
'Live Demos' to match the rendered heading.
The voice route was instantiating OpenAI() at module scope, which Next.js
triggers during 'collect page data' at build time. The Docker build context
does NOT have OPENAI_API_KEY set — only the running container does — so
every showcase-langgraph-python deploy has been failing since the voice
demo merged (#4224):
Error: Missing credentials. Please pass an `apiKey`, or set the
`OPENAI_API_KEY` environment variable.
[Error: Failed to collect page data for /api/copilotkit-voice]
Wrap the OpenAI + TranscriptionService + CopilotRuntime construction in
a getRuntime() function that runs on first request. Cached after first
call so there's no per-request cost in production.
This unblocks the full showcase deploy pipeline, not just voice.
Add *.wav to .gitattributes so audio assets follow the same LFS policy
as the existing *.png / *.pdf / *.gif / *.jpg / *.jpeg / *.mp4 / *.webm
rules. Re-stage sample.wav so the committed object becomes an LFS
pointer instead of a raw 87 KB blob.
- public/demo-audio/sample.wav (87KB, 16kHz mono, ~2.7s) — TTS "What is the weather in Tokyo?" for the voice demo's "Play sample" button
- public/demo-files/sample.png (10KB) — CopilotKit logo for the multimodal demo's "Try with sample image"
- public/demo-files/sample.pdf (2.4KB, one page, contains "CopilotKit" 9x) — quickstart excerpt for the multimodal demo's "Try with sample PDF"
Makes both demos fully self-contained end-to-end; the "Try with sample X" buttons now work without the user providing their own files.
Re-run `generate-starters.ts` for langgraph-python to emit the
byoc_json_render_agent.py starter agent and register it in langgraph.json
(post-merge drift-check was failing because the starter hadn't been
regenerated after adding the byoc-json-render demo).
Bump generate-catalog.test LGP-feature-count assertions 32->33 and
wired-totals 176->177 / 31->32, unshipped 486->485 / 6->5 to match the
new manifest.
Regenerate langgraph-python starter so agent_config_agent is included
(drift-check fails without this). Bump generate-catalog.test.ts counts
to match wiring of agent-config: LGP wired 31→32, LGP unshipped 6→5,
total wired 176→177, total unshipped 486→485.
Alem Tuzlak