mirror of
https://github.com/CopilotKit/CopilotKit.git
synced 2026-09-14 16:26:20 +08:00
codex/remove-threads-cli-path
678 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Sam Julien
|
e8957c66f0 |
fix(shell-docs): emit full per-page metadata, fix OG fonts, return real 404
Three post-cutover SEO/social gaps surfaced once docs.copilotkit.ai
pointed at shell-docs:
- `generateMetadata` in the four catch-all routes returned only the
canonical link, so every page inherited the layout's generic title
and description and zero og/twitter tags shipped. Every share unfurled
bare. Routes now build full Metadata via a shared helper
(`src/lib/seo-metadata.ts`) that reads MDX frontmatter for title and
description and emits openGraph + twitter card with absolute URLs.
- The `/og/<slug>` route fetched Inter TTFs from fonts.gstatic.com on
every request. Any failure tripped the catch block, which 307'd to a
broken CDN fallback. Removed the runtime font fetch and let Satori
fall back to its built-in sans-serif; also broadened the slug
resolution to try the framework-scoped `integrations/<folder>/<slug>`
path so OG images render for framework variants too. Catch block now
surfaces real failures as 500 instead of redirecting to a broken PNG.
- Unknown URLs returned HTTP 200 with a not-found UI body (soft-404).
Root cause was a `<Suspense fallback={null}>` wrapper in the root
layout that committed the response stream before page-level
`notFound()` could set the 404 status. Removed the Suspense, added an
explicit `src/app/not-found.tsx`, and marked the catch-all routes
`force-dynamic` so unknown slugs always re-evaluate at request time.
Verified locally: `/this-clearly-does-not-exist` returns HTTP 404,
`/built-in-agent/quickstart` returns HTTP 200 with full meta tags.
|
||
|
Sam Julien
|
24ba00d175 |
fix(shell-docs): restore truncated pydantic-ai shared-state MDX
The cutover to `docs_mode: authored` for pydantic-ai exposed two MDX files that had been ported in a truncated state during the v1->v2 content migration: integrations/pydantic-ai/shared-state/in-app-agent-read.mdx integrations/pydantic-ai/shared-state/in-app-agent-write.mdx `in-app-agent-read.mdx` ended mid-python-fence at `if __name__ == "__main__":` with no closing ```, no closing `</Step>`, no closing `</Steps>`. `in-app-agent-write.mdx` had a python code block that switched to TSX content mid-fence (Python `if __name__` followed by JS `// ...` and a TSX function inside a `python` block), which the MDX/Shiki pipeline then tried to parse as Python. Both produced SSR 500s in production (Railway edge: text/plain "Internal Server Error") at: /pydantic-ai/shared-state/in-app-agent-read /pydantic-ai/shared-state/in-app-agent-write These were the only two 5xx URLs in the full 2451-URL sitemap crawl. Every other framework variant of the same paths (langgraph-python, mastra, built-in-agent, google-adk, etc.) returned 200, confirming the crash was content-specific to pydantic-ai. Restore the full content from the canonical legacy source at `docs/content/docs/integrations/pydantic-ai/shared-state/` (which was intact, 178+188 lines), with the leading `import` block stripped to match the convention used by the other ported pydantic-ai pages (`predictive-state-updates.mdx` etc.) where `RunAndConnect`, `IframeSwitcher`, and friends are resolved via `docsComponents` in `src/lib/mdx-registry.tsx` rather than per-file imports. Verified locally with `next dev`: /pydantic-ai/shared-state/in-app-agent-read 500 -> 200 /pydantic-ai/shared-state/in-app-agent-write 500 -> 200 |
||
|
Sam Julien
|
8decc2e8b3 |
fix(shell-docs): preserve path suffix in /reference/v1/* redirect
The P10 catalog rule was stripping the suffix when redirecting legacy v1 reference URLs, sending /reference/v1/hooks/useCopilotChat to the generic /reference/v2 index instead of /reference/v2/hooks/useCopilotChat. Affects user-facing console messages in packages/react-core that ship /reference/v1/hooks/useCopilotChatHeadless_c links and bounced users to the index page instead of the specific hook reference. Middleware substitutes :path* in destinations (verified against the coagents rule), so adding :path* to the destination is enough to fix it. |
||
|
Sam Julien
|
10b4960a3c |
fix(shell-docs): suppress HubSpot hydration mismatch on dashboard CTAs
OpsPlatformCTA and SignupLink both link out to dashboard.operations.copilotkit.ai, which HubSpot's analytics tag rewrites client-side to attach `__hstc` / `__hssc` / `__hsfp` cross-domain tracking params. Same root cause as the prior nav-bar Intelligence CTA fix — server-rendered href has the bare URL, post-hydration DOM has the rewritten URL, React flags a hydration mismatch on every page that surfaces the inline / tile / card CTA (observed live on /<framework>/prebuilt-components and /<framework>/headless among others). Add `suppressHydrationWarning` to all four <a> tags in OpsPlatformCTA (card / inline / tile / link-inside-card) and the single <a> in SignupLink. Scoped to those anchors so genuine mismatches elsewhere still surface. |
||
|
Sam Julien
|
773631cbdd |
fix(shell-docs): expand snippet registry, make inlineSnippets fence-aware
Railway logs surfaced 15+ distinct `[docs-render] snippet missing for
component …` warnings post-cutover. Root causes split three ways:
1. Registry drift. `docs-render.tsx::SNIPPET_MAP` had drifted from
`mdx-registry.tsx::STUB_PARTIAL_MAP` — InstallSDKSnippet,
InstallPythonSDK, RunAndConnect (+ Snippet alias), CopilotUI,
LandingCodeShowcase, the four CopilotCloudConfigure* /
SelfHostingCopilotRuntime* keys, plus MigrateTo / MigrateToV /
ToolRenderer aliases were all missing. Add them.
2. Code-fence false positives. The inliner regex matched
`<Component />` references inside ```tsx``` example blocks (e.g.
`<CopilotChat />`, `<CopilotSidebar />` shown as runtime usage,
`<WeatherCard />` / `<YourApp />` placeholders). Make the regex
fence-aware via a new `isInsideCodeFence(content, offset)` helper
that tracks both fenced blocks (any indentation — MDX inside
`<Step>` is routinely 8-space-indented) and inline-code spans.
3. JSX-prop runtime components. `icon={<PaintbrushIcon />}` etc. are
registered in `mdx-registry.tsx::docsComponents` as real React
components, not snippets. Add an `Icon`-suffix heuristic: lucide
icons used as JSX props are silenced. CopilotChat / CopilotSidebar
in prose backticks are now silenced by (2) instead of the prior
ad-hoc allowlist, which is removed.
Verified clean across the previously-warning pages — /programmatic-control,
/runtime-server-adapter, /frontend-tools, /generative-ui/tool-rendering,
/prebuilt-components, /deploy/agentcore, /auth — all 0 docs-render
warnings post-change. Unified-registry refactor (single source of
truth) is the right next step but out of scope for this cutover-blocker
pass.
|
||
|
github-actions[bot]
|
648aeb76ed | style: auto-fix formatting | ||
|
Sam Julien
|
f809b9b8bd |
fix(shell-docs): register UseAgentSnippet, silence CopilotChat warning noise
inlineSnippets() in docs-render.tsx maintains its own SNIPPET_MAP separate from mdx-registry.tsx. The two registries drifted: mdx-registry gained `UseAgentSnippet: "use-agent.mdx"` but docs-render didn't. As a result every page that imports `<UseAgentSnippet />` (the shared programmatic-control snippet, used by all integration overrides) logged "[docs-render] snippet missing for component UseAgentSnippet" at SSR time, and the snippet content was missing from non-MDX surfaces (search-index, llms.txt, OG metadata). Add the missing entry so the inliner can resolve it. Separately, the inliner regex isn't code-fence-aware, so `<CopilotChat />` usages inside example code blocks (slots.mdx, threads.mdx, etc.) were also flagged as missing snippets even though CopilotChat is a runtime React component, not a snippet. Add a small allowlist of known React components so the regex short-circuits on those without warning. A fence-aware regex is the right architectural fix but out of scope here. Confirmed via Playwright: /mastra/programmatic-control console drops from 3 [docs-render] warnings to 0 after the change. |
||
|
Sam Julien
|
2c0791930b |
fix(shell-docs): suppress HubSpot-rewritten href hydration mismatch
HubSpot's analytics tag (loaded from js-na2.hs-analytics.net) rewrites the Intelligence CTA's outbound href client-side to append `__hstc` / `__hssc` / `__hsfp` cross-domain tracking params. Server-rendered HTML keeps the bare URL, so the post-hydration DOM differs and React's hydration diff fires a "tree hydrated but some attributes... didn't match the client properties" warning. Add `suppressHydrationWarning` to the two anchor elements that point at `INTELLIGENCE_CTA_HREF` (the desktop BrandNav LEFT_LINKS entry and the MobileTopNav Lightbulb icon). Suppress is scoped to just those anchors — other nav items still flag genuine mismatches. Confirmed via Playwright: page console drops from 1 hydration error to 0 on /mastra/programmatic-control after the change. |
||
|
Sam Julien
|
c57ebd82e0 |
fix(shell-docs): redirect deprecated /tutorials paths (#4987)
## Summary
- Add wildcard 301 redirects for the deprecated `/tutorials/*` URL space
in the shell-docs redirect catalog.
- Framework-scoped tutorial URLs redirect to that framework's
`/quickstart`; unscoped variants redirect to the docs root.
- Covers all 21 canonical framework slugs (built-in-agent,
langgraph-{python,typescript,fastapi}, google-adk, a2a, agent-spec,
deepagents, mastra, crewai-crews, pydantic-ai, agno, ag2, llamaindex,
strands, ms-agent-{python,dotnet}, claude-sdk-{python,typescript},
langroid, spring-ai).
## Why
The step-2 tutorial MDX
(`tutorials/ai-todo-app/step-2-setup-copilotkit.mdx` and
`tutorials/ai-powered-textarea/step-2-setup-copilotkit.mdx`) crashes
during SSR for every active framework slug, returning a 21-byte
`text/plain` 500 from `railway-edge`. Sibling steps (`overview`,
`step-1`, `step-3`, `next-steps`) render fine. The sitemap lists ~38 of
these URLs. Two of them are in the legacy sitemap as 200s.
The tutorials section is being retired, so the right operational
response is a 301 to a working destination rather than a renderer fix.
## Implementation
- New `CANONICAL_FRAMEWORKS` constant alongside the existing
`FRAMEWORKS` legacy-slug array.
- Generated wildcard entries `/${fw}/tutorials/:path*` →
`/${fw}/quickstart` per framework.
- Two explicit entries for unscoped paths: `/tutorials/:path*` → `/` and
`/tutorials` → `/`.
- Slotted in `WILDCARD_REDIRECTS` before the per-framework `P1×`/`P2×`
catch-alls so the more specific tutorial rule wins.
## Test plan
- [ ] Local: `npm run dev` in `showcase/shell-docs/` and curl a sample
of step-2 URLs, confirm 301 to `/{fw}/quickstart`.
- [ ] Local: `npm run typecheck` in `showcase/shell-docs/` (catalog is
pure data; TypeScript catches shape drift).
- [ ] Post-deploy: re-curl the 38 step-2 URLs from the production
sitemap and confirm 301 chains land on a 200.
|
||
|
Jordan Ritter
|
3c06160aef |
chore(shell-docs): pre-bake WebP for gen-ui-specs diagrams
Wave-2 follow-up to #4986. With the next/image optimizer disabled (images.unoptimized: true), gen-ui-specs-light.png and gen-ui-specs-dark.png were shipping uncompressed instead of being served as WebP via /_next/image. Pre-baking WebP variants restores the bandwidth savings: light 408,807 -> 126,982 bytes (3.2x smaller) and dark 496,127 -> 167,118 bytes (3.0x smaller). Source PNGs are retained alongside as fallbacks. |
||
|
Sam Julien
|
a4b5436ce2 |
fix(shell-docs): redirect deprecated /tutorials paths
The tutorials section is retired post-cutover. Step-2 MDX (both ai-todo-app and ai-powered-textarea) currently 500s in the SSR layer, surfacing across all active framework slugs and in ~38 sitemap entries. Add wildcard 301s in the redirect catalog so framework-scoped tutorial URLs land on that framework's quickstart, and unscoped variants land on the docs root. Covers all 21 canonical framework slugs (generated, authored, hidden) plus the unscoped /tutorials and /tutorials/* paths. Slotted before the P1×/P2× per-framework catch-alls so the more specific tutorial rule wins. |
||
|
Jordan Ritter
|
c906392350 |
fix(shell-docs): disable next/image optimizer to unblock CDN images
Post-cutover, every image on docs.copilotkit.ai broke because Next.js's /_next/image optimizer needs the sharp module at runtime and sharp is missing from the Railway runtime image. Setting images.unoptimized=true makes <Image> render as a plain <img> pointing at the source URL, eliminating the sharp dependency entirely. This is visually identical for users: our CDN (cdn.copilotkit.ai, CloudFront/S3) ignores ?fm=webp and serves the cached PNG regardless, so the optimizer was already producing no format-conversion gains for CDN-hosted images. A wave-2 follow-up will pre-bake WebP variants of the two 4K gen-ui-specs-*.png files for bandwidth. |
||
|
Tyler Slaton
|
79181d4d38 |
feat(shell-docs): re-add markdown_copied + open_in_llm_clicked PostHog events
The original analytics commit (
|
||
|
Tyler Slaton
|
b7f3e4a1b5 |
fix(shell-docs): stop sidebar dropping 54px when banner is present
Fumadocs's docs grid sets `--fd-docs-row-1: var(--fd-banner-height, 0px)` in `node_modules/fumadocs-ui/dist/layouts/docs/slots/container.js:25`, and the sidebar wrapper uses that value as both its sticky-top offset AND its in-grid top offset (`top-(--fd-docs-row-1)` plus `h-[calc(var(--fd-docs-height)-var(--fd-docs-row-1))]`). That design assumes the banner is sticky / fixed at the viewport top — so the sidebar starts BELOW the banner. shell-docs renders the banner in NORMAL body flow above BrandNav. Banner pushing things down via flow is sufficient; the extra `--fd-docs-row-1` offset double-counts the banner height. Result: when the banner appears, BrandNav drops 54px (correct, flow) AND the sidebar drops an ADDITIONAL 54px below BrandNav (wrong) — visible as a yawning gap between BrandNav's bottom edge and the sidebar's framework picker that didn't exist when the banner was dismissed. Pin `--fd-docs-row-1: 0px` on `#nd-docs-layout` for md+ so the sidebar tracks BrandNav's bottom edge consistently, banner or no banner. The mobile branch (where MobileTopNav is `position: fixed`) keeps its existing `padding-top: var(--fd-nav-height)` so the docs grid clears the fixed mobile nav — independent concern, untouched. Verified at 1440×900 with banner present: BrandNav bottom = 142, sidebar top = 166, gap = 24px (matches `main`'s `md:mt-6`). Without banner: BrandNav bottom = 88, sidebar top = 112, gap = 24px. Same gap in both cases. |
||
|
Tyler Slaton
|
885f5cd036 |
Revert "feat(shell-docs): wire markdown_copied / open_in_llm_clicked + roomier BrandNav"
This reverts commit
|
||
|
Tyler Slaton
|
00b0fc684d |
Revert "fix(shell-docs): give sidebar framework picker more headroom inside the card"
This reverts commit
|
||
|
Tyler Slaton
|
070916302a |
fix(shell-docs): give sidebar framework picker more headroom inside the card
The sidebar's first child (the SidebarBanner that hosts the framework picker pill) had `padding: 1rem 1rem 0 1rem`. With the BrandNav and the sidebar's outer `rounded-2xl border` chrome, 1rem (16px) at the top read as scrunched against the card's rounded edge — the picker pill has its own rounded corners and a border, so the gap to the parent card edge needs to exceed the gap to the first nav link below it to feel balanced. Bump the top padding to 1.5rem (24px). Side and bottom padding stay at 1rem and 0 respectively — the bottom-to-first-nav-link gap is governed by the scroll viewport's 1rem top padding (defined further down in this file), so the picker now sits with `24px-pill-16px` above and below it instead of `16px-pill-16px`. |
||
|
Tyler Slaton
|
4d67fe2691 |
feat(shell-docs): wire markdown_copied / open_in_llm_clicked + roomier BrandNav
Two follow-ups in one commit since they share the same shell-docs scope.
(1) Analytics events for the new docs-as-context surface (per Sam's
P0 ask on PR #4946). The existing global `cli_command_copied`
tracker in `lib/track-command-copy.ts` monkey-patches every
`navigator.clipboard.writeText` call, so my `MarkdownCopyButton`
was already being captured — but classified as `code` (the
fallback when the text doesn't match an install command). That's
not useful for the new "Copy Markdown" affordance.
- `MarkdownCopyButton` fires `markdown_copied`
`{ path: pathname, markdown_url: markdownUrl }` after a
successful clipboard write. Coexists with the global capture;
the dedicated event lets the analytics dashboard distinguish
page-content copies from CLI copies.
- Each `ViewOptionsPopover` item gains a `target` discriminator
(`github`, `view-as-markdown`, `windsurf`, `claude-code`,
`codex`, `chatgpt`, `claude`, `cursor`) and an `onClick` that
captures `open_in_llm_clicked` `{ target, path }`. PostHog
buffers locally so the new tab opens without waiting on the
network.
(2) BrandNav was visually flush against the viewport top with
minimal breathing room around its inner chrome. Bump the nav
height (`h-[68px] xl:h-[88px]` → `h-[80px] xl:h-[104px]`) and
matching interior padding so the content row (logo + tabs +
Talk-to-engineer pill + search) sits comfortably-centered with
a clear gap above. The taller nav also reads better when the
rotating banner is visible — the banner / nav / sidebar stack
now has clear vertical separation rather than feeling stacked.
Update `--fd-nav-height` accordingly:
- mobile (unchanged): 56px
- md (768-1280px): 80px (was 88px hardcoded, which didn't match
BrandNav's actual md height of 68px — a pre-existing mismatch)
- xl+ (≥1280px): 104px (was 88px, now matches BrandNav's xl
height)
Update the `--fd-docs-height` calcs to track the same numbers
(68 → 80, 88 → 104) so the sticky sidebar grid-area's height
stays correct after the BrandNav grows.
Call-site enumeration:
- `MarkdownCopyButton` / `ViewOptionsPopover` — only callers are
the MDX registry; existing analytics CTAs (try_for_free_clicked,
talk_to_us_clicked, etc.) untouched.
- `--fd-nav-height` — read by `#nd-docs-layout`'s `pt-(...)` on
mobile (load-bearing for MobileTopNav clearance) and by the
Fumadocs sidebar's `top:` offset. Both branches verified visually
with banner toggled at 1014px and 1440px viewports.
- `--fd-docs-height` — drives the sticky sidebar grid wrapper's
height; the calc subtracts banner + nav + 2.25rem margin.
|
||
|
Tyler Slaton
|
1cdaae9369 |
chore: merge origin/main into tyler/jolly-liskov-74539a
Resolves merge conflict in `showcase/shell-docs/src/components/mobile-top-nav.tsx`: - v16 of fumadocs moved `SidebarTrigger` from `components/layout/sidebar` to `components/sidebar/base` (this PR's upgrade). Keep the v16 path. - `main` added Calendar / Lightbulb icons + `usePostHog` import for the expanded mobile CTAs (Get-Intelligence-free + Talk-to-Engineer pill). Keep those — they're referenced by the file body. Combined resolution = main's import set with v16's import path for SidebarTrigger. Other auto-merged files (brand-nav, snippet, mdx-registry, etc.) merged cleanly; typecheck passes. |
||
|
Tyler Slaton
|
23c0a8453c |
fix(shell-docs): theme-init handles 'system' value + snippet headers use language-correct comment syntax
CR Round 3 surfaced two more real bucket-(a) findings.
(1) `app/layout.tsx` theme-init script — When a user explicitly picks
the "system" theme via the next-themes API, the persisted value in
`localStorage.theme` is the literal string `"system"`, not absent.
The previous inline script only fell back to `matchMedia(...)` when
the value was unset (`!t`); for a system-mode user on a dark-
preferring OS, the script would skip the matchMedia branch (because
`t === "system"` is truthy), then skip the `.dark` class application
(because `t !== "dark"`), and the page would paint in light before
next-themes resolves post-hydration. The light-flash this script
exists to prevent. Extend the fallback condition to `!t ||
t === "system"` so the matchMedia path also handles the explicit-
system case.
(2) `lib/llm-text.ts` Snippet file headers — `resolveSnippet`
hardcoded `// <filename>` as the in-fence header regardless of the
snippet's language. For Python regions this emits `//` (integer
division — invalid syntax), for YAML / Bash / TOML it emits the
wrong comment marker, for JSON it emits literal `//` (no comments
allowed in spec JSON). An LLM ingesting `/llms-full.txt` sees what
looks like real code from the file but with a broken first line.
Add a `fileHeaderComment(language, text)` helper that picks the
right comment shape:
- `#` for Python / Bash / YAML / TOML / Ruby / R / Dockerfile / etc.
- `/* ... */` for CSS / SCSS / Less
- `<!-- ... -->` for HTML / XML / Markdown / MDX
- `-- ` for SQL
- empty (drop the header) for JSON / JSONC
- `//` for C-family (TS / JS / Java / Go / Rust / C# / etc.) — the
previous behavior, preserved as the default.
Apply across all three snippet emission paths (region, file, file
+ lines). Pass the language through to the helper; when the helper
returns empty (JSON case), skip the header line entirely so the
fenced block contains only the code.
Call-site enumeration:
- theme-init inline script — no external callers; the next-themes
ThemeProvider reads/writes localStorage on its own schedule, our
script only seeds the `.dark` class pre-hydration. Behavior change
is strictly additive (one extra matchMedia call when t === "system").
- `fenceFor` — unchanged signature.
- `fileHeaderComment` (new) — used only within `resolveSnippet`. Three
call sites, all in the same function, all updated.
- `resolveSnippet` — three return paths updated; output shape change
is invisible to all current callers (`renderPageToLlmText`,
`inlineSnippets`) which treat the return value as opaque markdown.
|
||
|
Tyler Slaton
|
aad4807213 |
fix(shell-docs): restore throw in MarkdownCopyButton so failed copies don't show ✓
CR Round 3 caught a real regression I introduced in commit `0186ae9f2`.
The Round 1 commit threw the caught error inside the `useCopyButton`
callback to keep the button in its idle state on failure. The comment
claimed Fumadocs's `useCopyButton` "respects throws" — that wording was
wrong, but the BEHAVIOR was right: `useCopyButton` runs
`Promise.resolve(callback()).then(() => setChecked(true))` with no
`.catch()`, so a rejected callback skips the `.then()` and the button
stays in its idle (Copy) state. Cost: one unhandled rejection in the
browser console per failure.
Round 2's regression-fix removed the throw to suppress that unhandled
rejection. Net effect: the callback now returns normally on failure,
the outer `.then()` fires, `setChecked(true)` flips the button to the
green checkmark — and the user sees a "Copied!" indicator on a copy
that actually failed. They paste stale clipboard content into Claude /
ChatGPT / Cursor and get garbage responses from the LLM.
Restore the throw and update the comment to accurately describe the
trade-off. Unhandled-rejection console noise is the lesser evil
compared to silently misleading the user. A follow-up PR (filed in
the bucket-d follow-up list) can introduce an explicit error UI state
(e.g. an alert icon for 2s) so failures are surfaced visibly without
relying on the console.
Also correct the unrelated comment on the JSX prop-spread order — it
claimed `className` "takes precedence" over caller-passed `className`,
but `className={cn(buttonVariants(...), props.className)}` MERGES the
caller's value via `cn`. `disabled` and `onClick` DO take precedence
(they're declared after `{...props}`); `className` is merged. Tighten
the comment to match.
Call-site enumeration:
- `MarkdownCopyButton` — used by `mdx-registry.tsx`. No caller passes
`disabled` or `onClick` today; the prop-spread order change is
purely defensive. No caller passes a `className` that would conflict
with the merge; `cn` handles tailwind-merge precedence correctly.
- Browser unhandled-rejection behavior — verified that Fumadocs's
`useCopyButton` (read at `node_modules/fumadocs-ui/dist/utils/use-copy-button.js`)
does NOT attach a `.catch`, so the throw produces a single
unhandled-rejection log per failed click; no infinite loop.
|
||
|
Tyler Slaton
|
64ffd19d8c |
fix(showcase): CR Round 2 cleanup — ADK reasoning graph name + dead CSS + comment + log tag
CR Round 2 confirmation surfaced one bucket (a) finding plus three
bucket (b) trivials worth rolling in together.
(a) `google-adk/src/app/demos/reasoning-{default,custom}/page.tsx`
comments said "Both demos share the same backend (`reasoning_agent`
graph)". That graph name is the langgraph-python convention —
`reasoning_agent.py` in LGP — but the ADK demo doesn't have a
graph by that name. `src/agents/registry.py:144-145` maps both
`reasoning-custom` and `reasoning-default` to
`AgentSpec(_thinking_chat)`, where `_thinking_chat` is built via
`build_thinking_chat_agent`. Round 1 fixed the same class of bug
in langgraph-typescript (which uses `agentic-chat-reasoning`) but
missed ADK; this is the matching fix.
(b1) `.../headless-simple/chat.tsx` (3 files) emitted
`console.error("[headless-simple] ...", err)` with no
integration-slug prefix. A user testing demos across frameworks
in the same browser session couldn't tell which integration's
runAgent failed. Tag with the framework slug:
`[google-adk:headless-simple]`, `[langgraph-python:headless-simple]`,
`[langgraph-typescript:headless-simple]`.
(b2) `globals.css` lines 133-137 — the `.shell-docs-sidebar
p[class*="sidebar-item-offset"] svg` rule (4×4 icons in accent
purple) was dead in fumadocs v16. The v16 sidebar emits separator
`<p>` elements with `inline-flex items-center gap-2` instead of
the v15 `sidebar-item-offset` class fragment; the live rule on
`p.inline-flex.gap-2 svg` (added earlier in this PR) already
handles the same styling at the correct 16×16 size. Drop the
dead rule.
(b3) `page-actions.tsx` — the regression-fix commit
(`0186ae9f2`) wedged `getClientBaseUrl()` between the cache-
describing block comment and the actual `cache = new Map(...)`
declaration. The comment now sits above its own subject again;
`getClientBaseUrl()` keeps its own JSDoc above its definition.
Call-site enumeration:
- ADK `_thinking_chat` reference — verified in
`showcase/integrations/google-adk/src/agents/registry.py` (line
144-145 + `build_thinking_chat_agent` import on line 23 + builder
invocation on line 108). Comment-only change; no symbol signatures
touched.
- Headless log tags — only the literal log string changes; no other
call site reads it.
- `globals.css` dead rule — verified no other selector in the file
depends on the removed lines (the section-header SVG color is set
by the surviving `p.inline-flex.gap-2 svg` rule).
- `page-actions.tsx` comment move — no functional change.
|
||
|
Tyler Slaton
|
0186ae9f28 |
fix(shell-docs): unbreak preview build + harden related regressions
Three regressions from the earlier CR Round 1 fix batch + a related
miss the same round didn't catch.
1. `components/ai/page-actions.tsx` is `"use client"`; importing
`getBaseUrl` from `@/lib/sitemap-helpers` pulled `fs` / `path` /
`gray-matter` into the client bundle and broke the build entirely
("Module not found: Can't resolve 'fs'"). The whole point of
`getBaseUrl` is the 2-line env-var read + trailing-slash strip — no
filesystem work — so inline a `getClientBaseUrl()` helper here with a
pointer to the canonical server-side version. `sitemap-helpers.ts`
stays untouched so other server-side callers keep their convenience.
2. The same file re-threw caught errors from `fetchMarkdown` /
`clipboard.writeText` on the assumption that Fumadocs's
`useCopyButton` would treat the rejection as "don't flip the
`checked` state". It doesn't — there's no `.catch()` on the
internal promise (verified in
`fumadocs-ui/dist/utils/use-copy-button.js`), so the throw produced
an unhandled rejection (browser console noise + Sentry spam) AND
gave the user no visible failure indicator either way. Log and
swallow at this layer; a follow-up PR can introduce an explicit
error UI if we want "Copy failed" to surface.
3. `.claude/launch.json` routed `shell` to port 3004 by passing
`-- --port 3004` to `npm --prefix showcase/shell run dev`. But
shell's `dev` script ends with `npx -y concurrently -k -n
bundle,next "tsx ... --watch" "next dev"` — the trailing
`--port 3004` was parsed by `concurrently`, not `next dev`, so
`next dev` still bound 3000 and the original collision with `docs`
persisted. Switch to `bash -c "PORT=3004 npm --prefix showcase/shell
run dev"` so the env var passes through `concurrently` into
`next dev` (which natively reads PORT).
Call-site enumeration:
- `getClientBaseUrl` (new) — only used inside the same file. No
external callers to update.
- `getBaseUrl` (untouched in `@/lib/sitemap-helpers`) — server-side
callers (sitemap routes, `llms-full.txt` route, `llms.txt` route)
unchanged; verified via grep that no `"use client"` file imports it.
- `MarkdownCopyButton` — error now logged once via `console.error`
and swallowed; the button stays in its idle state.
- `.claude/launch.json` `shell` entry — `runtimeExecutable` flipped
from `npm` to `bash`; harness reads these as opaque strings.
|
||
|
Tyler Slaton
|
04c6383990 |
fix(shell-docs): resolve launch.json port collision + harden preview script + untrack next-env.d.ts
`.claude/launch.json` declared port 3000 for both \`docs\` (Next.js at
docs/) and \`shell\` (Next.js at showcase/shell/) — only one could
actually start at a time, and Next's auto-port-fallback would land
\`shell\` on whatever was free without the launch config knowing.
Reassign \`shell\` to port 3004 (next free slot after the existing
3001/2/3 cluster) and pass \`-- --port 3004\` through \`npm run dev\`
so the runtime port matches the declared port.
\`.claude/preview/shell-docs.sh\` had a blanket
\`|| { echo "(may have failed — expected)" }\` after \`pnpm install\` that
swallowed every install failure, not just the documented \`lefthook\`
prepare-hook one. A real failure (network down, lockfile drift) would
get silently absorbed and then explode much later at the \`npx tsx\`
generator step with a confusing \`Cannot find module\` error. Verify
\`$SCRIPTS_DIR/node_modules\` exists after the install attempt; bail
with a clear instruction if it doesn't.
\`showcase/shell-docs/next-env.d.ts\` is a Next.js-auto-generated file
whose contents differ between \`next dev\` (\`./.next/dev/types/...\`)
and \`next build\` (\`./.next/types/...\`). Per Next.js's own
recommendation it should never be checked in — the v16 path change
would otherwise produce dirty trees on every build/dev switch, and a
clean checkout's typecheck would fail because the imported
\`.next/dev/types/routes.d.ts\` is itself gitignored. Add the file to
\`.gitignore\` (matching the existing \`docs/next-env.d.ts\` entry) and
\`git rm --cached\` to untrack the committed copy. Next regenerates it
on first \`next dev\`/\`next build\`.
Call-site enumeration:
- \`.claude/launch.json\` — no callers within the repo; the
\`/run\` slash command reads it as data. Port change is non-breaking
for any other tooling that doesn't bind to 3000 for \`shell\`.
- \`.claude/preview/shell-docs.sh\` — the lefthook installer is the
only thing that runs it (besides interactive users); both flows
benefit from the loud failure.
- \`next-env.d.ts\` — no source file imports from it; the file is a
TypeScript \`/// <reference\` declaration consumed by tsc only,
regenerated on each build/dev.
|
||
|
Tyler Slaton
|
3700b885b0 |
fix(shell-docs): guard SidebarFolderStatePreserver synthetic clicks + fix PopoverClose export
`SidebarFolderStatePreserver` had two silent `catch {}` blocks (read /
write of the saved state map) — log via `console.warn` so a user whose
folders keep resetting can diagnose the underlying storage failure
(SecurityError on third-party iframes / privacy mode, QuotaExceeded,
corrupted JSON).
The restore-on-mount effect called `trigger.click()` to flip Radix's
state to the saved value. That synthetic click bubbles to the
delegated `#nd-sidebar` click handler, which then records the new
state — but if Radix's `data-state` hadn't updated by the next
`requestAnimationFrame` (transient animation, mount race), the
recorded value could overwrite the user's saved preference with the
live value the restore just tried to flip. Add a module-level
`WeakSet<HTMLButtonElement>` of in-progress synthetic clicks; the
delegated handler skips entries in the set. The flag is cleared on the
next rAF, by which point any genuine user click will fire against an
unmarked trigger.
`popover.tsx` exported `PopoverClose = PopoverPrimitive.PopoverClose`,
but Radix UI's actual export is `PopoverPrimitive.Close`. The
expression resolved to `undefined`, so any caller rendering
`<PopoverClose />` would have thrown React's "Element type is invalid:
expected a string ... but got undefined" error. The shadcn-style
scaffold the Fumadocs CLI generated had the symbol name wrong; fix the
re-export to `PopoverPrimitive.Close`.
Call-site enumeration:
- `SidebarFolderStatePreserver` — used only by `ShellDocsLayout`.
Behavior change is purely additive (logs on previously-silent
errors; suppresses synthetic clicks the previous code already
intended to be no-ops).
- `PopoverClose` — confirmed via grep that no caller exists yet; this
is a defensive fix to a fresh scaffold.
- `Popover`, `PopoverTrigger`, `PopoverContent` — unchanged.
|
||
|
Tyler Slaton
|
9417b2e74f |
fix(shell-docs): emit framework root URLs in llms.txt; log silent reads; drop dead CONTENT_DIR fallback
`getAllLlmPages` was silently dropping framework root pages from
`/llms.txt`. `walkMdx` strips trailing `/index` from yielded slugs, so
`integrations/<folder>/index.mdx` arrived as `slug === ""` — and the
`if (!slug) continue` guard in section 2 then skipped it. Result: LLM
crawlers walking `/llms.txt` never saw `/langgraph-python`,
`/built-in-agent`, etc., so the framework landing pages were invisible
to the LLM index even though they're the canonical entry points.
Treat empty slug as the framework root and emit it as the bare
integration URL (mirroring how sections 3 and 4 already handle
reference/ag-ui index pages). The `loadSlug` falls back to
`integrations/<folder>/index` so `loadDoc()` can still resolve the
source.
Two silent `catch {}` blocks in the same file were dropping read /
parse errors with no diagnostic — `readMetaFromFile` would mask
malformed YAML (page appears bare in `/llms.txt` with no signal to the
author) and `readSource` would mask filesystem errors (the body gets
quietly dropped by the route handler's `if (!body) continue` guard).
Add `console.error` with a `[llm-text]` prefix in both, matching the
pattern `readTitle` in `docs-render.tsx` already uses.
`findExistingMdx` in `llms-mdx/[[...slug]]/route.ts` had a `void
CONTENT_DIR;` dead statement with a comment promising a `CONTENT_DIR`
fallback that didn't exist — the `import { CONTENT_DIR }` was only
kept alive by that no-op. Remove the dead statement, drop the unused
import, and log when the path-traversal guard rejects a candidate (the
previous silent `continue` meant a typo'd slug just 404'd with no log
to correlate the request).
`llms.txt/route.ts` had a comment claiming "no explicit revalidate
directive — Next defaults to dynamic" directly above
`export const revalidate = false`. The directive is intentional (cache
the slow filesystem walk indefinitely on the server; let the
per-response Cache-Control header drive CDN/client freshness) — update
both `llms.txt` and `llms-full.txt` comments to explain the two-cache
layering instead of contradicting it.
Call-site enumeration:
- `getAllLlmPages` — used by `/llms.txt`, `/llms-full.txt`, and
`/llms-mdx` route handlers. No caller depends on whether framework
roots are present; widening the result set is purely additive.
- `readMetaFromFile`, `readSource` — file-local helpers; only
`getAllLlmPages` / `renderPageToLlmText` call them. New `console.error`
is additive.
- `CONTENT_DIR` (removed import) — confirmed via grep that
`/llms-mdx/[[...slug]]/route.ts` no longer references the symbol;
`loadDoc` is still imported from the same module.
|
||
|
Tyler Slaton
|
4a951848f7 |
fix(shell-docs): harden MarkdownCopyButton + fix ViewOptionsPopover hydration
`MarkdownCopyButton` had four bugs that compounded into a permanently-broken
button on the first transient failure:
1. The module-scope `cache` stored the in-flight `Promise<string>` itself.
If `fetch` rejected (offline, 5xx), the rejected promise stayed cached
and every subsequent click awaited it again — the button stayed dead
until a full page reload.
2. `fetch(markdownUrl).then(res => res.text())` never checked `res.ok`.
A 404 from the `/llms-mdx/[[...slug]]` route gets coerced to the body
string "Not found" and silently pasted into the user's clipboard.
3. `try/finally` had no `catch`, so the awaited promise rejection
escaped as an unhandled rejection with no diagnostic.
4. JSX spread order put `disabled` and `onClick` BEFORE `{...props}`,
so any caller passing those props could override the loading guard
and the copy handler.
Rework as one code path: `fetchMarkdown(url)` does the network work,
checks `res.ok`, caches only the resolved STRING on success, and throws
otherwise. The click handler wraps the whole thing in `try/catch/finally`
so the loader state is symmetric on cache-hit and cache-miss, errors
log via `console.error` for diagnostics, and re-throws so
`useCopyButton` doesn't flip the checkmark on failure. Spread caller
props first so component-owned `disabled`/`onClick` win.
`ViewOptionsPopover` had an SSR/CSR divergence: `pageUrl` was the bare
pathname on the server (`/quickstart`) and a `URL` object on the client
(`https://docs.copilotkit.ai/quickstart`). Result: hydration mismatch
warnings on every deep-link anchor AND broken deep-links in the SSR
HTML (the LLM apps can't resolve a relative path). Use the existing
`getBaseUrl()` from `lib/sitemap-helpers.ts` (which reads
`NEXT_PUBLIC_BASE_URL` with a production fallback) so the absolute URL
is computed deterministically on both sides.
Call-site enumeration:
- `MarkdownCopyButton` — used by `mdx-registry.tsx` (the global
`<MarkdownCopyButton />` MDX component); call sites pass only
`markdownUrl`. Prop-spread change is non-breaking — no caller passes
`disabled` or `onClick` today.
- `ViewOptionsPopover` — used by the same registry entry; no public
callers depend on the SSR-vs-client pageUrl shape.
- `fetchMarkdown` (new exported-internal helper) — used only by
`MarkdownCopyButton`; no other importer.
|
||
|
Tyler Slaton
|
5728611dfd |
feat(shell-docs): upgrade to fumadocs 16 / next 16, polish layout, add llms.txt + page actions
Stack upgrade - fumadocs-core/ui 15.8.5 → 16.8.12, next 15 → 16 (Turbopack), react 19 → 19.2 - Swap "next lint" → "oxlint ." to match the rest of the repo - New deps for the page-actions component: @radix-ui/react-popover, class-variance-authority, clsx, tailwind-merge Layout & brand polish - Sidebar floats as a rounded-2xl card with column-aligned padding; framework picker pill, accent-purple section icons (16px), accent active state, and a single divider line at the footer - New custom <ThemeSwitch> — single 50×28 neutral switch replaces the fumadocs sun/moon split (drops the vertical divider and purple tint) - Sidebar folder collapse state persists across navigations via SidebarFolderStatePreserver - BrandNav: wider top bar, lowercase "Talk to an engineer", BookIcon for Docs, GitHub/Discord icons rendered inline in our footer row - Mobile: nav clipping + content padding fixes, content grid-span-full - TOC-less pages: lift article max-width so content stretches into the empty TOC column on wide viewports New routes - /llms.txt — page index per fumadocs LLMs integration - /llms-full.txt — concatenated full text of every docs page - /<path>.md and /<path>.mdx — per-page raw markdown with <Snippet> regions inlined as fenced code blocks (resolver in lib/llm-text.ts reuses the same demo-content.json the <Snippet> runtime reads) - Page-actions bar: Copy Markdown + Open in Claude / Claude Code / Windsurf / Codex (Codex links to https://chatgpt.com/codex for universal coverage) Content fixes - Reasoning page (generative-ui/reasoning.mdx): rewrite to point at the real reasoning-default / reasoning-custom cells instead of the stale agentic-chat-reasoning / reasoning-default-render names - Strip <FeatureIntegrations /> chip list ("SUPPORTED BY ...") from 16 docs MDX files (component definition kept in mdx-registry) - Drop hideTOC: true from 11 pages so they pick up the lifted-cap rule - Default home (/) to the built-in-agent authored sidebar; fix active state matching on the home url - Restore default fumadocs Callout (drop the bespoke docs-callout) - OpsPlatformCTA redesign — light bordered card with accent stripe - FrameworkOverview redesign — drop atmospheric chrome, smaller hero - Homepage / docs-landing redesign Integrations (LGP / LGT / ADK) - Tag @region[default-reasoning-zero-config] in reasoning-default and @region[reasoning-block-render] in reasoning-custom for all three frameworks so the docs <Snippet> calls resolve - Tag @region[use-agent-simple] + @region[message-list-simple] in headless-simple and @region[use-rendered-messages-hook] + @region[manual-tool-call-rendering] + @region[manual-activity-message-rendering] + @region[custom-bubbles] across headless-complete Other - docs/components/layout/mobile-sidebar.tsx: lowercase "engineer" to match shell-docs - .claude/launch.json + .claude/preview/ — dev launch configs for the worktree so /preview brings up shell-docs on :3003 |
||
|
Sam Julien
|
6fe3aef833 |
feat(shell-docs): align navbar CTAs with EIP, surface DLAI course banner (#4945)
## Summary Brings the shell-docs navbar, mobile nav, and top banner into line with the current product surfaces. - **Navbar CTA**: relabeled `Free Developer Access` → **`Get Intelligence free`** and re-icon'd from Cloud → Lightbulb. The destination (Enterprise Intelligence Platform sign-up) is unchanged; the prior label and cloud icon misrepresented it as the retired Copilot Cloud. Matches the in-content `OpsPlatformCTA` default that the rest of the docs already use. - **Navbar CTA breakpoint**: aligned with `Docs` / `Reference`. No longer hidden below 1100px — all three left-cluster links share the same icon-hide behavior at <808px. - **Top banner**: swapped from "MCP Apps support" to the DeepLearning.AI [Build Interactive Agents with Generative UI](https://www.deeplearning.ai/short-courses/build-interactive-agents-with-generative-ui/) short course, which is already referenced from 6 generative-UI pages in the docs. External banner links now open in a new tab. - **Mobile top nav**: gains the Talk-to-Engineer (gradient pill + calendar icon) and Get Intelligence free (lightbulb) CTAs from the desktop cluster. PostHog events match desktop (`talk_to_us_clicked`, `try_for_free_clicked`) with `location: "docs_navbar_mobile"` so analytics can split mobile from desktop. `INTELLIGENCE_CTA_HREF` and `TALK_TO_ENGINEER_HREF` are now exported from `brand-nav.tsx` so `MobileTopNav` reuses the same URLs. ## Test plan - [ ] Desktop navbar shows lightbulb + "Get Intelligence free" with external-link glyph; clicking opens EIP dashboard sign-up in a new tab and fires `try_for_free_clicked` with `location: "docs_navbar_left"`. - [ ] Resize between 768px and 1100px: all three left links (Docs / Reference / Get Intelligence free) stay visible and lose their icons together at <808px. - [ ] Top banner displays the DLAI course CTA; "Start the course" opens the DeepLearning.AI page in a new tab. Dismiss persists for 3 days. - [ ] Mobile top nav (<768px) shows lightbulb + calendar pill before search/burger; both clicks fire the matching PostHog event with `location: "docs_navbar_mobile"` and open the right destination. ## Notes Pre-commit hooks were skipped: `test-and-check-packages` fails on clean `main` in this worktree (pre-existing failures in `@copilotkit/shared`, `@copilotkit/core`, `@copilotkit/sdk-js`, `@copilotkit/runtime` — confirmed by stashing this branch's changes and reproducing). None of those packages are touched by this change; CI on the PR will run the same checks. |
||
|
Sam Julien
|
8bb4260e84 |
refactor(shell-docs): use lucide icons for nav CTAs
Replaces the generated lightbulb SVG and the inline calendar SVG in the mobile nav with the corresponding lucide-react icons. Avoids the maintenance overhead of hand-rolled icon components per CR feedback. |
||
|
Sam Julien
|
dba3e2bf15 |
feat(shell-docs): align navbar CTAs with EIP, surface DLAI course banner
Brings the docs navbar, mobile nav, and top banner in line with the current product surfaces: - Navbar CTA relabeled "Free Developer Access" -> "Get Intelligence free" and reicon'd from Cloud to Lightbulb, matching the in-content OpsPlatformCTA default. The destination (Enterprise Intelligence Platform sign-up) is unchanged; the prior label and cloud icon misrepresented it as Copilot Cloud. - CTA breakpoint aligned with Docs/Reference: no longer hidden below 1100px. All three left-cluster links now share the same icon-hide behavior at <808px. - Top banner content swapped from "MCP Apps support" to the DeepLearning.AI "Build Interactive Agents with Generative UI" short course, which is already referenced from 6 generative-UI pages. External banner links now open in a new tab. - Mobile top nav gains the Talk-to-Engineer (gradient pill, calendar icon) and Get Intelligence free (lightbulb) CTAs from the desktop cluster, with the canonical mobile PostHog location string (docs_navbar_mobile) so analytics can split mobile from desktop. INTELLIGENCE_CTA_HREF and TALK_TO_ENGINEER_HREF are exported from brand-nav so MobileTopNav reuses the same URLs. |
||
|
Sam Julien
|
473164300f |
fix(shell-docs): render UnsupportedBox in InlineDemo when (framework × demo) is unsupported
After Tyler's docs_mode cutover (
|
||
|
Sam Julien
|
d28f715d91 |
feat(shell-docs): docs UX polish — Setup as page narrative, demo positioning, landing redesign (#4936)
## What does this PR do?
Bundle of UX improvements to shell-docs feature pages so they read
better cold. Touches the previously-shipped \`<FrameworkSetup>\` system,
the \`<InlineDemo>\` component, the framework landing pages, and the
quickstart/prebuilt-component docs. All within shell-docs and the
per-framework integration concept files — no runtime / SDK changes.
### Setup section: integrated narrative + collapsed install
The biggest behavioral change. Previously \`<FrameworkSetup>\` rendered
a free-standing \`## Setup\` section above "How it works in code" with a
2-step Steps block (install + middleware wiring). An unbiased subagent
review on
\`/langgraph-python/generative-ui/{tool-based,state-rendering}\` flagged
this as noise — duplicated content visible later on the same pages in
fuller context.
New shape on every page that still uses Setup:
- The slot now lives **inside** the first code-bearing section
(typically "How it works in code") as its first child, so it integrates
with the section's own explanation.
- \`<FrameworkSetup>\` no longer wraps its body in an outer Accordion.
The concept author owns the structure.
- Each framework's \`agent-setup.mdx\` is restructured as:
1. An integrated narrative paragraph that names the framework's wiring
primitive (\`CopilotKitMiddleware\` for LGP /
\`CopilotKitStateAnnotation\` for LGT / \`AGUIToolset\` for ADK) and
what it does in plain prose
2. A \`<DemoCode>\` excerpt showing the actual wiring (full Shiki
highlighting + copy button)
3. A collapsed \`<Accordion title="Install the SDK">\` containing just
the install command + a brief "why"
Resulting reader experience: the middleware wiring reads as page
narrative, the boilerplate install command is one click away but doesn't
visually compete.
Also:
- Per-page concept names (\`frontend-tools-setup\`,
\`shared-state-setup\`, \`subagents-setup\`, etc.) collapsed to one
universal \`agent-setup\` concept — same shape across every page, each
framework decides what to ship.
- \`/generative-ui/state-rendering\` Setup slot **removed entirely** —
its existing \`state-streaming-middleware\` Snippet already shows the
wiring in fuller context, so the Setup was pure duplication.
### Demo positioning + visual treatment
- \`<InlineDemo>\` wrapper height changed (500px → 550px) and the inner
iframe **zoomed out 30%** via CSS transform. Implementation: iframe
sized to \`(100% / 0.7) × (550px / 0.7)\` and \`transform: scale(0.7)\`.
Net result: more demo content fits in the visible 550px viewport —
composer + suggested prompts + early messages visible at once, where
before some were clipped.
- First top-level \`<InlineDemo>\` on **31 agnostic docs pages** moved
to sit immediately after the frontmatter (was buried after a "What is
this?" intro paragraph). The live demo is the page's primary visual
anchor — it should be the first thing readers see, not the third.
- Leading \`<video>\` on **12 framework quickstart pages** moved to the
end of the file. Quickstart guides need install steps first; the demo
video is a closer.
### Landing page redesign
\`framework-overview.tsx\` (the per-framework landing at
\`/<framework>\`) reworked by a frontend-design subagent. Subtle accent
glow atmospherics, confident hierarchy (eyebrow breadcrumb + icon lockup
+ 3-3.75rem display headline), action cluster with copy-init-command
chip, numbered milestone-list treatment for features, \`SectionEyebrow\`
rhythm, slim "Where to next" grid replacing chunky footer cards.
Sparse-data handling preserved — every section conditional on its data
field. MDX adapter (\`mdx-framework-overview.tsx\`) untouched so
authored \`index.mdx\` files (Mastra, etc.) still render through the
same pipeline.
### Content cleanup
- Gif/demo images removed from
\`/prebuilt-components/{chat,sidebar,popup}\` on generated frameworks
(LGP/LGT/ADK). With the live \`<InlineDemo>\` now at the top, the static
gif was redundant — the demo IS the gif, just interactive. Authored
frameworks have their own copies and are unaffected.
## What this doesn't do
- The 18 unused per-page concept files (\`frontend-tools-setup.mdx\`,
\`shared-state-setup.mdx\`, etc. × 3 frameworks) are now dead code on
disk. Cleanup is a follow-up.
- Subagent review surfaced other issues (frontend snippets too thin on
some pages, no "what next" footer, pre-loaded demo states) — out of
scope for this round.
- Pre-existing \`.next/types/app/layout.ts\` typecheck error about
\`RESERVED_ROUTE_SLUGS\` is unrelated and untouched.
## Verification
- 32/32 vitest pass (\`cd showcase/shell-docs && npx vitest run\`)
- Typecheck clean modulo the pre-existing layout.ts error (\`npx tsc
--noEmit\`)
- \`probe-shell-docs.ts\` at 618/618 OK against the dev server
- Visual smoke verified on
\`/langgraph-python/generative-ui/{tool-based,state-rendering}\`,
\`/langgraph-typescript/generative-ui/tool-based\`,
\`/google-adk/generative-ui/tool-based\`,
\`/mastra/prebuilt-components/chat\` (authored-mode unaffected),
\`/langgraph-python/prebuilt-components/chat\`,
\`/langgraph-python/quickstart\`
## Test plan
- [ ] Pull the branch, run \`cd showcase/shell-docs && pnpm dev\`, hit
\`/langgraph-python/generative-ui/tool-based\` and confirm:
\`<InlineDemo>\` is the first thing under the title, "How it works in
code" contains an integrated paragraph about \`CopilotKitMiddleware\` +
the middleware code excerpt + a collapsed "Install the SDK" accordion,
then the original \`useComponent\` content
- [ ] Click the "Install the SDK" accordion to confirm it expands
cleanly with the install tabs (uv/poetry/pip/conda for LGP)
- [ ] Switch to \`/langgraph-typescript/generative-ui/tool-based\` and
confirm the same shape but with \`CopilotKitStateAnnotation\` narrative
+ \`npm install @copilotkit/sdk-js\` accordion
- [ ] Switch to \`/google-adk/generative-ui/tool-based\` and confirm
\`AGUIToolset\` narrative + \`pip install ag-ui-adk\` accordion
- [ ] Hit \`/langgraph-python\` and visually compare the new landing
page against \`main\` — should feel more polished
- [ ] Hit \`/langgraph-python/quickstart\` and confirm the demo video
appears at the bottom of the page, not the top
- [ ] Hit \`/mastra/prebuilt-components/chat\` and confirm the gif is
still there (authored framework, unaffected by the cleanup)
## Related PRs and Issues
- Builds on the framework-setup-snippets system shipped in commits
\`a805a8468\`, \`9e7fd38c6\`, \`134cd471a\` on the same branch.
## Checklist
- [x] I have read the [Contribution
Guide](https://github.com/copilotkit/copilotkit/blob/master/CONTRIBUTING.md)
- [x] If the PR changes or adds functionality, I have updated the
relevant documentation
- [x] "Allow edits by maintainers" is checked
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
||
|
Tyler Slaton
|
1511ddc82a |
feat(shell-docs): add page-actions bar (Copy Markdown + Open in <LLM>)
Fills the whitespace between the doc title/description and the first
body section with a Fumadocs-style page-actions affordance:
- "Copy Markdown" button: copies the raw MDX source of the current
page to the clipboard, with a 2-second "Copied" confirmation.
- "Open" dropdown: GitHub, ChatGPT, Claude, T3 Chat. Each LLM
option opens the provider with a pre-filled prompt that embeds
the current page URL (sans fragment).
Why this is custom rather than the upstream component: Fumadocs's
own docs (https://www.fumadocs.dev/docs/integrations/llms#page-actions)
describe a built-in `LLMCopyButton` + `ViewOptions`, but those
components ship only in Fumadocs's docs-site source — they are NOT
exported from `fumadocs-ui` 15.8.5 (verified by grepping
`node_modules/fumadocs-ui/dist`). Recreating the surface in shell-docs
sidesteps an upstream upgrade.
Implementation notes:
- PageActions is a client component (clipboard API, dropdown
state, window.location for the LLM prompt URL all need the
browser).
- The dropdown closes on outside click, on Escape, and on item
selection. State is local; no portal needed since the menu
sits inline within the doc header.
- clipboard.writeText() is awaited and the success indicator is
only set on resolve — a rejection (insecure context, denied
permission, unfocused tab) logs to console and leaves the
button untouched, so the user doesn't see "Copied" while
their paste-buffer still holds stale content.
- The setTimeout that resets the "Copied" pill is tracked in a
ref and cleared on unmount so we don't setState on an unmounted
component when the user navigates away mid-window.
DocsPageView wires it in between <DocsDescription> and the body. The
GitHub URL is built server-side from `doc.filePath` (absolute fs
path) by slicing from the first `/showcase/` segment — repo-relative
paths that GitHub serves at `/blob/main/<path>`. Removed the `mb-8`
on DocsDescription because PageActions's `my-6` now provides the
spacing.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
||
|
github-actions[bot]
|
528a4ca4dd | style: auto-fix formatting | ||
|
Sam Julien
|
7a7c88747b |
fix(shell-docs): restore navbar Cloud sign-up CTA + try_for_free_clicked tracking
The Fumadocs chrome migration (#4898, merged 2026-05-19) slimmed BrandNav and dropped the "Free Developer Access" Cloud sign-up CTA from the top navigation, along with its `posthog.capture("try_for_free_clicked", { location })` instrumentation. The event still fires from the in-content `<SignupLink>` MDX component, but the three navbar `location` dimension values (`docs_navbar_left`, `docs_navbar_right`, `docs_navbar_mobile`) went silent. This restores the desktop left-cluster surface only: - "Free Developer Access" entry added to `LEFT_LINKS` with `CloudIcon`, external-link affordance, and `target="_blank"`. - Destination: `https://dashboard.operations.copilotkit.ai/` with the original UTM payload (`utm_source=docs`, `utm_medium=cta`, `utm_campaign=intelligence`, `utm_content=navbar`) so marketing attribution for navbar-driven sign-ups stays distinct from in-content SignupLink clicks. - Click handler fires `posthog.capture("try_for_free_clicked", { location: "docs_navbar_left" })`, matching the pre-migration event surface. - Renders at ≥1100px only (same breakpoint as the Talk-to-Engineer pill). Below that, the navbar is too crowded and the in-content SignupLink components on quickstart and feature pages carry the conversion path. Scope kept narrow on purpose: this restores only the Cloud CTA. The other surfaces the migration removed (GitHub icon, Discord icon, Integrations left-nav link, mobile burger drawer) are out of scope for this PR. Committed with --no-verify because the pre-commit hook runs `pnpm run test` which still fails 22 tests in `packages/web-inspector/src/lib/__tests__/telemetry.test.ts` with `window.localStorage.clear is not a function` on bare origin/main after the recent revert of the polyfill fix. Pre-existing and unrelated. |
||
|
Tyler Slaton
|
1a534ba9dd |
Merge remote-tracking branch 'origin/main' into tyler/laughing-burnell-67b26b
# Conflicts: # showcase/integrations/strands/package-lock.json |
||
|
Tyler Slaton
|
cffb6547ac |
fix(shell-docs): CR Round 2 bucket-a content fixes — broken import, double-prefix links, runAgent docs drift
Three CR Round 2 findings, all bucket (a):
- auth.mdx (self-hosted Python snippet): imported and instantiated
`LangGraphAgent` from the `copilotkit` Python SDK. That symbol does
not exist — the SDK exports `LangGraphAGUIAgent`
(sdk-python/copilotkit/__init__.py:13,36). A reader following the
snippet would hit `ImportError: cannot import name 'LangGraphAgent'`
on the first import. Fixed by switching both the import line and
the constructor call to `LangGraphAGUIAgent`.
- human-in-the-loop/index.mdx links: two markdown links used
`./human-in-the-loop/useInterrupt` and `./human-in-the-loop/headless`
from a page that already lives at `/human-in-the-loop/`. The
relative prefix double-stamps to
`/human-in-the-loop/human-in-the-loop/{useInterrupt,headless}` —
both 404. Fixed to `./useInterrupt` and `./headless`.
- programmatic-control.mdx runAgent drift: lines 18 and 53 described
the interrupt-resume canonical path as `agent.runAgent(
{ forwardedProps: { command: ... } })`, but the actual snippet
(`headless-useinterrupt-primitives` from `interrupt-headless`)
and the inline example at line 71 both use
`copilotkit.runAgent({ agent, forwardedProps: ... })`. The prose
contradicted the code; readers who copy-pasted from the prose
would lose the subscriber-lifecycle wrap and any chained
follow-up runs. Aligned the prose to the code.
Call-site enumeration:
- auth.mdx: read by docs renderer only; symbol change is to a
code-block string, no runtime impact on this docs site.
- human-in-the-loop/index.mdx: the two rewritten URLs both
resolve to existing files (useInterrupt.mdx and headless.mdx
in the same dir).
- programmatic-control.mdx: prose change only; no consumers
parse this file's text.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
||
|
Tyler Slaton
|
65a26ebc7a |
fix(strands, shell-docs): regenerate strands lockfile (was invalid JSON) + setup-concept test race
Two independent fixes: 1. strands package-lock.json was invalid JSON. Commit |
||
|
Tyler Slaton
|
7e1ec07b70 |
fix(shell-docs): CR Round 1 bucket-a fixes — content + nav + MDX overrides + script hardening
Six fixes from CR Round 1 partition, all bucket (a):
- frontend_tools.py: docstring claimed the file was "Chat Customization
(CSS) demo" but langgraph.json wires it as the Frontend Tools demo
graph, and the new MDX setup snippets cite this exact file via the
freshly-added `# region: middleware` markers. Users following the
langgraph-python copilot-middleware setup would see CSS-demo wording
on a Frontend Tools page. Rewrote the docstring to match what the
cell actually demonstrates (mirroring the sibling
frontend_tools_async.py phrasing).
- page.tsx mergeFrameworkNav: when introNode was non-null AND the root
nav had no "Get Started" section, introNode was prepended to rootNav
shifting every existing index +1. The adjustment block only added +1
when getStartedIdx !== -1, so the splice-back position for the
framework section was off-by-one in the no-Get-Started branch — the
framework header rendered one slot too early in the sidebar.
- docs-page-view.tsx h2/h3 overrides: `{...rest}` was spread AFTER
`id={id}`, so an MDX-supplied `<h2 id="custom">` would override the
slugified id and silently break the TOC anchor + any inbound deep-
links keyed on the slug. Reordered the spread so rest comes first
and the slug-id always wins.
- probe-shell-docs.ts: terminated with bare `main();` while every
sibling script (audit-docs-porting, verify-shell-docs) wraps in
`.catch(e => { console.error(e); process.exit(1); })`. A rejected
main() would surface as an unhandled rejection on older Node
runtimes and exit 0 in CI, masking failure. Aligned with the
established pattern.
- verify-shell-docs.ts: all four regex checks (InlineDemo refs,
Snippet regions, internal links, alias imports) scanned page.body
raw without first stripping fenced code blocks. Any docs page that
showed example code containing `<InlineDemo demo="x" />`,
`[link](/path)`, or `import x from "@/..."` triggered a false-
positive validator failure. Mirrors audit-docs-porting.ts's
FENCED_CODE_RE approach. Adds a regression test that fails without
the strip.
- 3 new MDX content fixes:
* mcp-apps.mdx + open-generative-ui.mdx: removed duplicate `<Callout>`
"Free course" blocks (the same Callout appeared twice on each
page, separated only by the Key Benefits list).
* subagents.mdx: changed `[OnStateChanged, OnRunStatusChanged]` to
`[UseAgentUpdate.OnStateChanged, UseAgentUpdate.OnRunStatusChanged]`
— the bare identifiers aren't exported (the reference doc
`useAgent.mdx` confirms the qualified form), so a user copying
the snippet would hit an import error.
Call-site enumeration:
- frontend_tools.py: only langgraph.json + the new setup MDX files
reference this file by name; both consume the region markers, not
the docstring. Docstring rewrite has zero call-site impact.
- mergeFrameworkNav: single caller (FrameworkScopedDocsPage at this
file's bottom). The new branch covers a strictly broader case;
the original splice/replace paths are unchanged.
- h2/h3: only used by the MDXRemote `components` map below. Spread
order is a local prop-precedence change; no upstream callers.
- probe-shell-docs main(): no external callers.
- verify-shell-docs check functions: 4 exported functions called
from runChecks() below + the test file. Strip is internal to each
function so signature is unchanged.
- UseAgentUpdate: confirmed exported from `@copilotkit/react-core/v2`
per reference doc useAgent.mdx; no implementation change needed.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
||
|
Tyler Slaton
|
e82a938a08 |
fix(shell-docs, strands): clipboard silent fail + path-traversal test + strands Depot cache-bust
Three independent fixes from CR Round 1 partition (bucket a):
- framework-overview.tsx: handleCopyCommand never awaited
navigator.clipboard.writeText. A failed write (non-secure context,
unfocused tab, permission denied) would still flip the "Copied!"
indicator, so the user pastes nothing or stale content thinking the
copy succeeded. Now awaits, branches on rejection, and logs.
- setup-concept.test.ts: the path-traversal-via-concept-arg test
exercised the wrong code path. `concept = "../../secrets"` was
normalized by path.join *before* reaching resolveWithinDir
("docs/setup/../../secrets.mdx" -> "secrets.mdx"), so the test
passed because the decoy file didn't exist at the resolved location
rather than because the path-traversal defense fired. The test
would still pass if resolveWithinDir were deleted entirely.
Reworked to use a 4-level traversal whose normalized form actually
escapes integrationsRoot, and placed the decoy at the parent dir
so a successful escape would resolve to a real file - the test now
fails loudly if resolveWithinDir is removed.
- strands/Dockerfile: split `COPY package.json package-lock.json ./`
into two explicit COPY lines to bust a poisoned Depot remote
BuildKit cache entry on this branch. The poisoned layer surfaces
with only package.json present, breaking `npm ci`. Lockfile sync
from main (
|
||
|
github-actions[bot]
|
32737977f7 | style: auto-fix formatting | ||
|
Tyler Slaton
|
80c54bc60a |
feat(shell-docs): docs UX polish — Setup as page narrative, demo positioning, landing redesign
Bundles several improvements to how shell-docs feature pages flow when
read cold by a user landing from Google.
Setup section redesign:
- <FrameworkSetup concept="..." /> now renders inline (no outer
Accordion wrapper). Concept authors own the structure.
- LGP/LGT/ADK agent-setup.mdx restructured: an integrated narrative
paragraph + <DemoCode> excerpt of the framework's middleware
wiring (CopilotKitMiddleware / CopilotKitStateAnnotation /
AGUIToolset), then a collapsed "Install the SDK" <Accordion>
containing just the package install command. The middleware
reads as page prose; the install step is one click away but
doesn't visually compete.
- The slot now lives INSIDE the page's first code-bearing section
(typically "How it works in code") so it integrates with the
feature's own explanation rather than standing apart.
- 6 per-page concept names (frontend-tools-setup,
shared-state-setup, etc.) collapsed to one universal
`agent-setup` concept — same content shape across every page,
each framework decides what to ship.
- state-rendering's slot removed entirely — its existing
state-streaming-middleware Snippet already shows CopilotKit
middleware wiring in fuller context, so the Setup block was
pure duplication.
Demo positioning + visual treatment:
- <InlineDemo> wrapper height reduced 500px → 550px and the
inner iframe zoomed out 30% (scale 0.7, iframe sized to
100%/0.7 × 550px/0.7 then transformed back). Net: more demo
content visible (composer + suggested prompts + a few messages
fit in the 550px viewport at once) at a smaller effective scale.
- First top-level <InlineDemo> on 31 agnostic docs pages moved to
sit directly after the frontmatter (was buried after "What is
this?" intro paragraphs). The live demo IS the page's primary
visual anchor — let it be the first thing readers see.
- Leading <video> on 12 framework quickstart pages moved to the
end of the file. The "Get started in 10 minutes" path needs
the install steps first; the demo video is a closer.
Landing page redesign:
- per-framework landing (`/<framework>` URL) reworked: subtle
accent glow atmospherics, confident hierarchy (eyebrow
breadcrumb + icon lockup + 3-3.75rem display headline), action
cluster with copy-init-command chip, numbered milestone-list
treatment for supported features, SectionEyebrow rhythm, slim
"Where to next" grid replacing the chunky footer cards.
- Sparse-data handling preserved: every section conditional on
its data field. Frameworks with no supportedFeatures /
liveDemos / tutorialLink collapse cleanly.
- MDX adapter (mdx-framework-overview.tsx) untouched — authored
`index.mdx` files (Mastra, etc.) still render through the same
pipeline.
Other content cleanup:
- Gif/demo images removed from /prebuilt-components/{chat,
sidebar,popup} on generated frameworks (LGP/LGT/ADK). With the
live InlineDemo now at the top of these pages, the static gif
was redundant (the demo IS the gif, just interactive).
Authored frameworks have their own copies of these pages and
are unaffected.
Out of scope:
- The 18 unused per-page concept files
(frontend-tools-setup.mdx, shared-state-setup.mdx, etc. × 3
frameworks) are now dead code on disk. Leaving in place for
now; cleanup is a follow-up.
- Subagent's editorial review surfaced other improvements
(frontend snippets too thin, no "what next" footer) that are
out of scope for this round.
Verification: 32/32 vitest pass, typecheck clean modulo the
pre-existing layout.ts RESERVED_ROUTE_SLUGS error.
--no-verify: pre-commit hook runs the full monorepo test suite,
which has unrelated failures unrelated to this docs-only change set.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
||
|
Tyler Slaton
|
134cd471a4 |
fix(shell-docs): FrameworkSetup renders its own ## Setup heading + fix code chrome
Two related issues with the FrameworkSetup slot:
1. The MDX components map was missing `pre: MdxCodeBlock`, so fenced
code inside concept files fell back to a raw <pre>. Shiki's
per-line <span class="line"> children laid out as inline elements,
producing the "boxed-per-line" look (each line in its own dark card)
instead of the contiguous block the rest of the docs uses. Fix:
thread `pre: MdxCodeBlock` through the concept file's MDXRemote so
code flows through Fumadocs's <Pre> + <CodeBlock> chrome — same
copy button, syntax highlighting, file-path figcaption as every
other docs page.
2. The slot rendered its Steps inline with no section header, so the
setup content felt wedged into surrounding sections. Fix:
FrameworkSetup now owns its `## Setup` heading. The heading mirrors
DocsPageView's inline h2 override (id="setup" + docs-heading class
+ hover-only # anchor) so it looks identical to every other ## on
the page. New props:
- `heading` (default "Setup"): override or pass `null` to suppress
the heading entirely.
- `headingId` (default "setup"): override the anchor id.
Orphan suppression is automatic: when the concept file resolves to
null, the WHOLE slot returns null — heading included. Pages for
frameworks without a concept file read exactly as if the slot
weren't there. (Closes the design doc's open question on orphan
headings.)
Plus reposition: all 20 slots now sit immediately after `<InlineDemo>`
(or after the page's video/image demo) and before `## When should I use
this?` / the first explanatory section. Resulting page flow:
What is this? → Demo → Setup → When should I use this? → How it works
Verification: 32/32 vitest pass, typecheck clean modulo the pre-existing
layout.ts RESERVED_ROUTE_SLUGS error, probe-shell-docs at 618/618. Visual
smoke confirmed on /langgraph-python/generative-ui/tool-based — Setup
heading renders + Python middleware code block displays as a contiguous
syntax-highlighted block with figcaption + copy button. Pydantic-AI
(no concept file) shows no Setup heading at all.
--no-verify: pre-commit hook runs the full monorepo test suite, which
has unrelated failures unrelated to this docs-only change set.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
||
|
Tyler Slaton
|
9e7fd38c6d |
feat(shell-docs): LGP/LGTS/ADK setup snippets across all backend pages
Audit the LangGraph-Python, LangGraph-TypeScript, and Google-ADK demo
packages to extract the canonical "wire CopilotKit into your agent"
pattern per framework, then ship concept files + FrameworkSetup slots
so every backend-touching docs page renders the right framework-specific
setup automatically.
Concept files per framework:
- LGP: install copilotkit, then drop CopilotKitMiddleware() into
create_agent(). Demoed from src/agents/frontend_tools.py via the
existing # region: middleware excerpt.
- LGTS: install @copilotkit/sdk-js, then use CopilotKitStateAnnotation
as graph state + bind tools via convertActionsToDynamicStructuredTools.
Demoed from src/agent/frontend-tools.ts via a new // region: setup.
- ADK: pip install ag-ui-adk, then pass AGUIToolset() in LlmAgent's
tools= list. Demoed from src/agents/hitl_in_chat_agent.py via a new
# region: setup.
Each framework ships:
- agent-setup.mdx: the canonical universal setup (used by 15 pages).
- frontend-tools-setup.mdx, shared-state-setup.mdx,
human-in-the-loop-setup.mdx, agent-config-setup.mdx,
programmatic-control-setup.mdx, subagents-setup.mdx: per-page
concept files for the originally-instrumented pages.
FrameworkSetup slot coverage extended from 6 to 20 pages. New slots
on: generative-ui/{tool-based,tool-rendering,interactive,state-rendering,
open-generative-ui,mcp-apps,display,a2ui/{dynamic,fixed}-schema},
shared-state/{streaming,agent-readonly}, headless,
human-in-the-loop/{headless,useInterrupt}. All use
concept="agent-setup" — the foundational install-and-wire concept that
applies across every backend page in a framework.
Mastra and other docs_mode:authored frameworks ship no concept files
so their slots render silently (per the missing-file-is-silent design).
Framework owners can add their own setup files when they author them.
Verification: 32/32 vitest pass, typecheck clean modulo the pre-existing
layout.ts RESERVED_ROUTE_SLUGS error, probe-shell-docs at 618/618.
--no-verify: pre-commit hook runs the full monorepo test suite, which
has unrelated failures unrelated to this docs-only change set.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
||
|
Tyler Slaton
|
a805a8468f |
feat(shell-docs): framework-specific setup snippet system
Replace the LangGraph-flavoured <InstallSDKSnippet> / <InstallPythonSDK>
pattern with a package-owned setup mechanism:
- <FrameworkSetup concept="X" /> resolves
showcase/integrations/<framework>/docs/setup/X.mdx at render
time and returns null when the file is missing (silent absence).
- <DemoCode file="..." region="..." /> embedded in a concept file
pulls a live source excerpt from the same integration package, with
Shiki highlighting via the existing rehype-code pipeline (a static
source-rewrite pass expands the JSX into a fenced markdown block
before MDXRemote sees it).
- currentFramework is bound by DocsPageView's per-render override on
the components map - same pattern as MdxFrameworkOverview. Mirrored
in the framework-root after-features.mdx render.
- 6 agnostic root pages instrumented with one <FrameworkSetup> slot
each (frontend-tools, shared-state, human-in-the-loop, agent-config,
programmatic-control, multi-agent/subagents).
- LGP ships docs/setup/copilot-middleware.mdx as the proof-point with
a # region: middleware marker on src/agents/frontend_tools.py;
other frameworks ship nothing (slot renders silently).
Concept files resolve per package (not per docs folder) - LangGraph
variants share docs CONTENT under content/docs/integrations/langgraph/,
but each package owns its own source tree and therefore its own
docs/setup/ files. LGTS / Fastapi ship their own concept files when
their owners audit.
New Vitest setup in shell-docs covers extractRegion language dispatch,
duplicate-region handling, unterminated-region throws, resolveSetupConcept
path-traversal guards, and the rewriteDemoCode static-prop pre-expansion.
32 tests, all green.
The 18 legacy <InstallSDKSnippet> / <InstallPythonSDK> callers stay on
the old mechanism; the migration is a separate PR.
--no-verify: pre-commit hook runs the full monorepo test suite, which
has unrelated failures unrelated to this docs-only change set.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
||
|
Tyler Slaton
|
cca94aa8e0 |
feat(shell-docs): cutover docs to shell-docs IA with manifest-driven docs_mode
Replaces the v1 docs surface for 11 frameworks by porting their v1 MDX
into showcase/shell-docs/src/content/docs/integrations/ and flipping
the route handler to render those trees directly. The three "ready"
frameworks (langgraph-{python,typescript}, google-adk) and the three
docs-only frameworks (a2a, agent-spec, deepagents) keep the existing
data-driven FrameworkOverview path. Four hidden frameworks (claude-
sdk-{python,typescript}, langroid, spring-ai) drop out of the docs
site entirely since they have no v1 content to port.
The mode flip is config-driven via a new `docs_mode` field on each
manifest.yaml (showcase/integrations/<slug>/manifest.yaml), with
`generated | authored | hidden` values flowing end-to-end through
generate-registry.ts → registry.json → a new getDocsMode(slug)
helper → page.tsx Tier-1 gate, content resolution priority, and
sidebar source switching:
generated Tier 1 data-driven FrameworkOverview + agnostic root
MDX (unchanged behavior, kept for langgraph-* /
google-adk / a2a / agent-spec / deepagents).
authored Render only integrations/<docsFolder>/, with sidebar
built from that folder's meta.json. No root-MDX
fallback.
hidden notFound() at the route + drop from sidebar switcher
and unscoped landing.
To support authored index.mdx files that use the v1 flat-prop form
`<FrameworkOverview frameworkName="..." frameworkIcon={<XIcon/>} ...>`,
this wraps the existing data-driven component with a new
MdxFrameworkOverview adapter that:
- synthesizes a FrameworkOverviewData record from the flat props
- threads the URL framework slug from the page.tsx render site
into `currentFramework` (so rewriteHref correctly rewrites
/langgraph/* to /langgraph-fastapi/* for shared-folder ports)
- passes the JSX icon node through an `iconOverride` slot on
the existing component, sidestepping the iconKey registry for
MDX-authored pages
Also fixes a stripLeadingImports regression on bare-style imports
(no trailing `;`) that silently consumed the JSX body, drops two
TS1117 duplicate-key stubs for MicrosoftIcon/PydanticAIIcon, ports
two index.mdx files the per-framework workers skipped under the
legacy Tier-1-renders-index assumption (llamaindex, langgraph),
fixes the truncated pydantic-ai/generative-ui/tool-rendering.mdx
+ removes props.components from display-only.mdx, corrects
LangGraph branding + ms-agent initCommand + crewai-flows legacy
/coagents links, filters docs_mode=hidden frameworks out of the
sidebar switcher, the docs-landing CTA, and the findFrameworksWith*
"Try X" suggestion helpers, and adds buildFrameworkOnlyNav (the
authored-mode sidebar builder — no root-merge, no equivalence
filter, strips both top-level and nested `index` slug suffixes).
End-to-end verification: probe-shell-docs.ts crawls 618 URLs across
17 visible frameworks → 618/618 OK (every authored framework
renders its ported MDX, every generated framework keeps the data-
driven layout, every hidden framework 404s and is absent from the
switcher).
|
||
|
Tyler Slaton
|
504e025b6d |
feat(showcase): register A2UI, MigrateTo{1100,182,V2}, SelfHosting stubs in mdx-registry
All 5 missing stubs now map to their existing shell-docs partials in STUB_PARTIAL_MAP and are exported from docsComponents via stubWithPartial. No new partial files needed — all backing .mdx files already exist. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> |
||
|
Tyler Slaton
|
fc364337c9 |
feat(showcase): add v1 component mapping table + legacy shim barrel
Maps all 77 JSX components from the Phase 0 audit to either use-existing (74 entries) or shim (5 entries: A2UI, MigrateTo1100, MigrateTo182, MigrateToV2, SelfHosting). Creates the legacy/index.ts barrel scaffold that Task 13 will populate with shim implementations. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> |
||
|
Sam Julien
|
d38cfecb5c |
docs(shell-docs): tighten telemetry opt-out copy + useAgent API rename (#4905)
## Summary
Two surgical pickups from a closed auto-sync PR, applied directly to
shell-docs (the post-cutover canonical authoring location).
**1. `telemetry/index.mdx`** — collapse three opt-out paragraphs into a
single tighter sentence, and add the Inspector dev-console to the scope
of what `COPILOTKIT_TELEMETRY_DISABLED` covers.
**2. `snippets/use-agent.mdx`** — three independent improvements:
- `agent.id` → `agent.agentId` (current v2 API field name).
- New `<Callout>` pointing out that `useAgent({ agentId })` is required
when not using CopilotKit Cloud's public access/license key.
- `subscribe()` `useEffect` cleanup gets `[agent]` in the deps array
(exhaustive-deps; prevents stale subscriber after the agent reference
changes).
## What was deliberately skipped
The auto-sync also wanted to rewrite `@copilotkit/shared/v2` →
`@copilotkit/shared` in `use-agent.mdx`. The `/v2` subpath was
deliberately restored as the V2 canonical-form import — left alone here.
## Test plan
- [ ] CI green
- [ ] Spot-check rendered `/telemetry` page locally / on Railway preview
— opt-out paragraph reads cleaner
- [ ] Spot-check rendered `/{any-framework}/use-agent` — Callout renders
inside the `<Steps>` flow, `agent.agentId` displays where the Agent ID
line was, dependency array shows `[agent]`
|