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.

Author: samjulien

showcase/shell-docs/src/lib/docs-render.tsx

@@ -798,22 +798,33 @@ export const SNIPPET_MAP: Record<string, string> = {
   SelfHosting: "shared/premium/self-hosting.mdx",
   Slots: "shared/basics/slots.mdx",
   Threads: "shared/threads/threads.mdx",
+  ToolRenderer: "shared/generative-ui/tool-rendering.mdx", // alias of ToolRendering
   ToolRendering: "shared/generative-ui/tool-rendering.mdx",
   DefaultToolRendering: "shared/guides/default-tool-rendering.mdx",
+  // Versionless aliases retained for backward compat with older MDX that
+  // emits `<MigrateTo />` / `<MigrateToV />`; both resolve to v2.
+  MigrateTo: "shared/troubleshooting/migrate-to-v2.mdx",
+  MigrateToV: "shared/troubleshooting/migrate-to-v2.mdx",
+  CopilotUI: "copilot-ui.mdx",
+  LandingCodeShowcase: "landing-code-showcase.mdx",
   UseAgentSnippet: "use-agent.mdx",
+  InstallSDKSnippet: "install-sdk.mdx",
+  InstallPythonSDK: "install-python-sdk.mdx",
+  RunAndConnect: "coagents/run-and-connect-agent.mdx",
+  RunAndConnectSnippet: "coagents/run-and-connect-agent.mdx", // alias of RunAndConnect
+  CopilotCloudConfigureCopilotKitProvider:
+    "copilot-cloud-configure-copilotkit-provider.mdx",
+  // Historical spelling (no `Provider` suffix) still appears in tutorials.
+  CopilotCloudConfigureCopilotKit:
+    "copilot-cloud-configure-copilotkit-provider.mdx",
+  SelfHostingCopilotRuntimeCreateEndpoint:
+    "self-hosting-copilot-runtime-create-endpoint.mdx",
+  SelfHostingCopilotRuntimeConfigureCopilotKitProvider:
+    "self-hosting-copilot-runtime-configure-copilotkit-provider.mdx",
+  SelfHostingCopilotRuntimeConfigureCopilotKit:
+    "self-hosting-copilot-runtime-configure-copilotkit-provider.mdx",
 };
 
-// JSX components that legitimately appear as `<Component />` inside MDX
-// code fences (rendered example code) but are NOT snippet imports. The
-// `inlineSnippets()` regex isn't code-fence-aware, so without this set
-// these false positives spam the dev console and look like missing
-// snippet errors. CopilotChat is the runtime React component used in
-// example snippets across slots.mdx, threads.mdx, use-agent.mdx, etc.
-//
-// If a real snippet ever needs one of these names, register it in
-// SNIPPET_MAP above; the lookup short-circuits before this check.
-const KNOWN_REACT_COMPONENTS_IN_CODE_FENCES = new Set<string>(["CopilotChat"]);
-
 export const SUBPATH_TO_COMPONENT: Record<string, string> = {
   "ag-ui": "AGUI",
   "coding-agents": "CodingAgents",
@@ -940,6 +951,68 @@ export function stripLeadingImports(source: string): string {
   return out.join("\n");
 }
 
+/**
+ * Returns true if `offset` falls inside a Markdown fenced code block
+ * (```...``` or ~~~...~~~) or an inline code span (`...`) within
+ * `content`. Best-effort: scans from the start of `content` and tracks
+ * fence state line by line. Markdown requires fence markers at the start
+ * of a line (optionally preceded by up to three spaces), so we anchor on
+ * that. Used by `inlineSnippets()` to skip JSX-looking matches that
+ * appear inside example code (e.g. `<CopilotChat />` shown as runtime
+ * usage in slots.mdx) rather than as snippet imports.
+ */
+function isInsideCodeFence(content: string, offset: number): boolean {
+  // Split the text up to the match into completed lines + a possibly
+  // partial trailing line. We treat all completed lines as candidate
+  // fence boundaries and the trailing partial line as the context for
+  // inline-code (single-backtick) detection.
+  const lines = content.slice(0, offset).split("\n");
+  const completed = lines.slice(0, -1);
+  const currentLine = lines[lines.length - 1] ?? "";
+
+  // Fenced blocks: walk completed lines and toggle on matching
+  // opener/closer. CommonMark allows up to 3 leading spaces; MDX in
+  // shell-docs is more permissive — fences inside `<Step>` and other
+  // JSX containers are routinely indented 8+ spaces. Match any
+  // leading whitespace so those fences aren't missed.
+  let inFence = false;
+  let openerChar: string | null = null;
+  for (const line of completed) {
+    const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
+    if (!fenceMatch) continue;
+    const marker = fenceMatch[1];
+    if (!inFence) {
+      inFence = true;
+      openerChar = marker[0];
+    } else if (marker[0] === openerChar) {
+      inFence = false;
+      openerChar = null;
+    }
+  }
+  if (inFence) return true;
+
+  // Inline code: count single-backtick toggles on the partial current
+  // line. A single backtick opens an inline span that closes on the
+  // next single backtick. Runs of 2+ backticks are rare in prose
+  // (literal-backtick spans) and intentionally ignored so the common
+  // `<Component />` case is caught reliably.
+  let inlineToggles = 0;
+  let i = 0;
+  while (i < currentLine.length) {
+    if (currentLine[i] !== "`") {
+      i++;
+      continue;
+    }
+    let run = 0;
+    while (i + run < currentLine.length && currentLine[i + run] === "`") {
+      run++;
+    }
+    if (run === 1) inlineToggles++;
+    i += run;
+  }
+  return inlineToggles % 2 === 1;
+}
+
 export function inlineSnippets(
   content: string,
   slugPath: string = "",
@@ -949,7 +1022,16 @@ export function inlineSnippets(
 
   result = result.replace(
     /<([A-Z]\w*)\s*(?:components=\{[^}]*\}\s*)?\/>/g,
-    (match, componentName) => {
+    (match, componentName, offset: number, source: string) => {
+      // Skip JSX-looking strings inside code fences / inline code: those
+      // are rendered example code, not snippet imports. Suppresses the
+      // bulk of `[docs-render] snippet missing` warnings that surfaced
+      // post-cutover (e.g. <CopilotChat />, <YourApp />, <WeatherCard />
+      // shown as usage examples inside ```tsx ... ``` blocks).
+      if (isInsideCodeFence(source, offset)) {
+        return match;
+      }
+
       let snippetRel = SNIPPET_MAP[componentName];
 
       if (!snippetRel && componentName === "SharedContent" && slugPath) {
@@ -979,15 +1061,20 @@ export function inlineSnippets(
       }
 
       if (!snippetRel) {
-        // Suppress noise for runtime React components that appear inside
-        // example code fences (the regex isn't fence-aware — see comment
-        // above KNOWN_REACT_COMPONENTS_IN_CODE_FENCES).
-        if (KNOWN_REACT_COMPONENTS_IN_CODE_FENCES.has(componentName)) {
+        // Components ending in `Icon` are conventionally lucide-react
+        // icons. shell-docs's MDX renders them via the `docsComponents`
+        // global registry in mdx-registry.tsx, so they're real runtime
+        // React components — not snippet imports. Skip silently rather
+        // than warn (matches the same shape as the fence-aware short
+        // circuit above for `<CopilotChat />` in prose backticks).
+        if (componentName.endsWith("Icon")) {
           return match;
         }
         // Log so docs authors see a clean signal when a <Component />
         // reference can't be mapped to a snippet file (previously the
-        // component just silently rendered nothing).
+        // component just silently rendered nothing). Matches inside code
+        // fences are short-circuited above so this warning only fires on
+        // genuine prose-level references.
         console.warn(
           "[docs-render] snippet missing for component",
           componentName,