@stainless-api/docs 0.1.0-beta.9 → 0.1.0-beta.91

package/eslint-suppressions.json

@@ -0,0 +1,32 @@
+{
+  "plugin/buildAlgoliaIndex.ts": {
+    "@typescript-eslint/no-explicit-any": {
+      "count": 2
+    }
+  },
+  "plugin/components/SnippetCode.tsx": {
+    "@typescript-eslint/no-explicit-any": {
+      "count": 1
+    }
+  },
+  "plugin/globalJs/copy.ts": {
+    "@typescript-eslint/no-explicit-any": {
+      "count": 3
+    }
+  },
+  "plugin/index.ts": {
+    "@typescript-eslint/no-explicit-any": {
+      "count": 1
+    }
+  },
+  "plugin/languages.ts": {
+    "@typescript-eslint/no-explicit-any": {
+      "count": 1
+    }
+  },
+  "plugin/specs/worker.ts": {
+    "@typescript-eslint/no-explicit-any": {
+      "count": 3
+    }
+  }
+}

package/locals.d.ts

@@ -0,0 +1,17 @@
+type SidebarEntry = App.Locals['starlightRoute']['sidebar'][number];
+
+/**
+ * Extending Astro’s `App.Locals` interface
+ */
+declare namespace App {
+  interface Locals {
+    _stlStarlightPage?: {
+      skipRenderingStarlightTitle?: boolean;
+      hasMarkdownRoute?: boolean;
+      fullSidebar?: SidebarEntry[];
+    };
+
+    stainlessProject?: string;
+    language?: import('@stainless-api/docs-ui/routing').DocsLanguage;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "0.1.0-beta.9",
+  "version": "0.1.0-beta.91",
   "publishConfig": {
     "access": "public"
   },
@@ -9,24 +9,18 @@
   "exports": {
     ".": "./stl-docs/index.ts",
     "./plugin": "./plugin/index.ts",
-    "./OverviewRoute": "./plugin/routes/Overview.astro",
-    "./DocsRoute": "./plugin/routes/Docs.astro",
-    "./DocsStaticRoute": "./plugin/routes/DocsStatic.astro",
-    "./MarkdownRoute": "./plugin/routes/markdown.ts",
-    "./Search": "./plugin/components/search/Search.astro",
-    "./replaceSidebarPlaceholderMiddleware": "./plugin/replaceSidebarPlaceholderMiddleware.ts",
     "./plugin/middleware": "./plugin/middlewareBuilder/stlStarlightMiddleware.ts",
     "./plugin/MiddlewareTypes": "./plugin/middlewareBuilder/stainlessMiddleware.d.ts",
-    "./Header": "./stl-docs/components/Header.astro",
-    "./ThemeSelect": "./stl-docs/components/ThemeSelect.astro",
-    "./BaseSidebar": "./stl-docs/components/sidebars/BaseSidebar.astro",
-    "./SDKSelectSidebar": "./stl-docs/components/sidebars/SDKSelectSidebar.astro",
-    "./ContentPanel": "./stl-docs/components/content-panel/ContentPanel.astro",
-    "./tabsMiddleware": "./stl-docs/tabsMiddleware.ts",
+    "./plugin/languages": "./plugin/languages.ts",
     "./stainless-docs/mintlify-compat": "./stl-docs/components/mintlify-compat/index.ts",
-    "./theme": "./theme.css",
     "./mintlify-compat.css": "./styles/mintlify-compat.css",
-    "./font-imports": "./styles/fonts.css"
+    "./components": "./stl-docs/components/index.ts",
+    "./components/scripts": "./stl-docs/components/scripts.ts",
+    "./docs-config": "./stl-docs/loadStlDocsConfig.ts",
+    "./specs/fetchSpecSSR": "./plugin/specs/fetchSpecSSR.ts",
+    "./generate-docs-routes": "./plugin/helpers/generateDocsRoutes.ts",
+    "./components/Head": "./stl-docs/components/Head.astro",
+    "./components/ContentBreadcrumbs": "./stl-docs/components/ContentBreadcrumbs.tsx"
   },
   "keywords": [],
   "author": "",
@@ -35,41 +29,56 @@
     "node": ">=18.17.1"
   },
   "peerDependencies": {
-    "@astrojs/starlight": ">=0.34.0",
-    "astro": ">=5.5.0"
+    "@astrojs/starlight": ">=0.37.5",
+    "astro": ">=5.15.3",
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0",
+    "vite": ">=6.2.1"
   },
   "dependencies": {
-    "@astrojs/markdown-remark": "^6.3.2",
-    "@astrojs/react": "^4.3.1",
-    "@stainless-api/sdk": "0.1.0-alpha.12",
+    "@astrojs/markdown-remark": "^6.3.10",
+    "@astrojs/react": "^4.4.2",
+    "@stainless-api/sdk": "0.1.0-alpha.19",
+    "astro-expressive-code": "^0.41.6",
     "cheerio": "^1.1.2",
     "clsx": "^2.1.1",
-    "dotenv": "17.2.2",
-    "get-port": "^7.1.0",
-    "highlight.js": "^11.11.1",
-    "lucide-react": "^0.544.0",
-    "marked": "^16.0.0",
-    "react": "^19.1.1",
-    "react-dom": "^19.1.1",
+    "dotenv": "17.2.3",
+    "lucide-react": "^0.562.0",
+    "marked": "^17.0.1",
+    "node-html-parser": "^7.0.1",
+    "rehype-parse": "^9.0.1",
+    "rehype-remark": "^10.0.1",
+    "remark-gfm": "^4.0.1",
     "remark-github-alerts": "^0.1.1",
-    "shiki": "^3.9.2",
+    "remark-stringify": "^11.0.0",
+    "shiki": "^3.22.0",
+    "unified": "^11.0.5",
+    "vite-plugin-prebundle-workers": "^0.2.0",
     "web-worker": "^1.5.0",
-    "yaml": "^2.8.0",
-    "@stainless-api/docs-ui": "0.1.0-beta.7",
-    "@stainless-api/ui-primitives": "0.1.0-beta.8"
+    "yaml": "^2.8.2",
+    "@stainless-api/docs-search": "0.1.0-beta.21",
+    "@stainless-api/docs-ui": "0.1.0-beta.68",
+    "@stainless-api/ui-primitives": "0.1.0-beta.47"
   },
   "devDependencies": {
-    "@markdoc/markdoc": "^0.5.2",
-    "@types/node": "^24.4.0",
-    "@types/react": "^19.1.13",
-    "@types/react-dom": "^19.1.9",
-    "tsx": "^4.20.3",
-    "zod": "^4.0.0",
-    "@stainless/eslint-config": "0.0.0"
+    "@astrojs/check": "^0.9.6",
+    "@markdoc/markdoc": "^0.5.4",
+    "@types/node": "24.10.9",
+    "@types/react": "19.2.10",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "tsx": "^4.21.0",
+    "typescript": "5.9.3",
+    "vite": "^6.4.1",
+    "zod": "^4.3.5",
+    "@stainless/eslint-config": "0.1.0-beta.1",
+    "@stainless/sdk-json": "^0.1.0-beta.4"
   },
   "scripts": {
-    "vendor-deps": "pnpm tsx scripts/vendor_deps.ts",
+    "vendor-deps": "tsx scripts/vendor_deps.ts",
     "lint": "eslint . --max-warnings 0",
-    "sync": "astro sync"
+    "sync": "astro sync",
+    "check:types": "astro check"
   }
 }

package/playground-virtual-modules.d.ts

@@ -0,0 +1,96 @@
+declare module 'virtual:stl-playground/typescript.json' {
+  const data: {
+    links: [string, string][];
+    files: [string, string][];
+  } | null;
+  export { data as default };
+}
+declare module 'virtual:stl-playground/python.json' {
+  const data: { files: Record<string, string>; wheel: string } | null;
+  export { data as default };
+}
+declare module 'virtual:stl-playground/auth.json' {
+  const data:
+    | ({
+        type: 'http_bearer' | 'query' | 'header' | 'oauth2' | 'http_basic' | 'http_digest';
+        description?: string;
+        name: string;
+        title: string;
+        header: string | undefined;
+        example: string | undefined;
+      } & {
+        opts: {
+          name: string;
+          type: 'string' | 'number' | 'boolean' | 'null' | 'integer';
+          nullable: boolean;
+          description?: string | undefined;
+          example?: unknown;
+          default?: unknown;
+          read_env?: string | undefined;
+          auth?:
+            | {
+                security_scheme: string;
+                role?: 'value' | 'password' | 'username' | 'client_id' | 'client_secret' | undefined;
+              }
+            | undefined;
+        }[];
+      })[]
+    | null;
+  export { data as default };
+}
+declare module 'virtual:stl-playground/data' {
+  import type { Config } from 'virtual:stl-playground/create';
+  declare const data: Config;
+  export { data as default };
+}
+declare module 'virtual:stl-playground/create' {
+  export type PlaygroundLanguage = 'python' | 'typescript' | 'http';
+  export type Config = {
+    wheelUrl: string;
+    pyTypes: {
+      files: Record<string, string>;
+      wheel: string;
+    } | null;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    HIGHLIGHT_THEMES: any;
+    tsTypes: {
+      links: [string, string][];
+      files: [string, string][];
+    } | null;
+    authData:
+      | ({
+          type: 'http_bearer' | 'query' | 'header' | 'oauth2' | 'http_basic' | 'http_digest';
+          description?: string;
+          name: string;
+          title: string;
+          header: string | undefined;
+          example: string | undefined;
+        } & {
+          opts: {
+            name: string;
+            type: 'string' | 'number' | 'boolean' | 'null' | 'integer';
+            nullable: boolean;
+            description?: string | undefined;
+            example?: unknown;
+            default?: unknown;
+            read_env?: string | undefined;
+            auth?:
+              | {
+                  security_scheme: string;
+                  role?: 'value' | 'password' | 'username' | 'client_id' | 'client_secret' | undefined;
+                }
+              | undefined;
+          }[];
+        })[]
+      | null;
+  };
+  export function createPlayground(
+    props: {
+      lang: PlaygroundLanguage;
+      doc: string;
+      /** div.stl-snippet-request-container */
+      container: HTMLElement;
+      onLanguageSelect: (value: string) => void;
+    } & Config,
+  ): () => Promise<void>;
+}

package/plugin/assets/languages/cli.svg

@@ -0,0 +1,14 @@
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 20 20"
+      width="24"
+      height="24"
+      fill="nopne"
+    >
+      <path
+        fill-rule="evenodd"
+        d="M3.25 3A2.25 2.25 0 0 0 1 5.25v9.5A2.25 2.25 0 0 0 3.25 17h13.5A2.25 2.25 0 0 0 19 14.75v-9.5A2.25 2.25 0 0 0 16.75 3zm.943 8.752a.75.75 0 0 1 .055-1.06L6.128 9l-1.88-1.693a.75.75 0 1 1 1.004-1.114l2.5 2.25a.75.75 0 0 1 0 1.114l-2.5 2.25a.75.75 0 0 1-1.06-.055M9.75 10.25a.75.75 0 0 0 0 1.5h2.5a.75.75 0 0 0 0-1.5z"
+        clip-rule="evenodd"
+        fill="#a2a1a1"
+      />
+    </svg>

package/plugin/assets/languages/csharp.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" fill="none"><defs><linearGradient id="a-_r_1_" x1="46.77" x2="69.91" y1="86.46" y2="126.73" gradientTransform="matrix(8.78996,0,0,8.78996,-233.98,-518.97)" gradientUnits="userSpaceOnUse"><stop stop-color="#927be5"></stop><stop offset="1" stop-color="#512bd4"></stop></linearGradient><filter id="b-_r_1_" width="42.84" height="39.14" x="44.63" y="91.89" color-interpolation-filters="sRGB" filterUnits="userSpaceOnUse"><feFlood flood-opacity="0" result="BackgroundImageFix"></feFlood><feColorMatrix in="SourceAlpha" result="hardAlpha" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"></feColorMatrix><feOffset></feOffset><feColorMatrix values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.1 0"></feColorMatrix><feBlend in2="BackgroundImageFix" result="effect1_dropShadow_2037_2800"></feBlend><feColorMatrix in="SourceAlpha" result="hardAlpha" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"></feColorMatrix><feOffset dy="1"></feOffset><feGaussianBlur stdDeviation="2.5"></feGaussianBlur><feColorMatrix values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.1 0"></feColorMatrix><feBlend in2="effect1_dropShadow_2037_2800" result="effect2_dropShadow_2037_2800"></feBlend><feColorMatrix in="SourceAlpha" result="hardAlpha" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"></feColorMatrix><feOffset dy="4"></feOffset><feGaussianBlur stdDeviation="2"></feGaussianBlur><feColorMatrix values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.09 0"></feColorMatrix><feBlend in2="effect2_dropShadow_2037_2800" result="effect3_dropShadow_2037_2800"></feBlend><feColorMatrix in="SourceAlpha" result="hardAlpha" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"></feColorMatrix><feOffset dy="9"></feOffset><feGaussianBlur stdDeviation="2.5"></feGaussianBlur><feColorMatrix values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.05 0"></feColorMatrix><feBlend in2="effect3_dropShadow_2037_2800" result="effect4_dropShadow_2037_2800"></feBlend><feColorMatrix in="SourceAlpha" result="hardAlpha" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"></feColorMatrix><feOffset dy="15"></feOffset><feGaussianBlur stdDeviation="3"></feGaussianBlur><feColorMatrix values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.01 0"></feColorMatrix><feBlend in2="effect4_dropShadow_2037_2800" result="effect5_dropShadow_2037_2800"></feBlend><feBlend in="SourceGraphic" in2="effect5_dropShadow_2037_2800" result="shape"></feBlend></filter></defs><path fill="url(#a-_r_1_)" d="M135.73 285.85v173.93a60.2 60.2 0 0 0 30.13 52.17l150.62 86.97a60.2 60.2 0 0 0 60.25 0l150.62-86.97a60.2 60.2 0 0 0 30.13-52.17V285.85a60.2 60.2 0 0 0-30.13-52.18l-150.62-86.95a60.2 60.2 0 0 0-60.25 0l-150.62 86.95a60.3 60.3 0 0 0-30.13 52.18" transform="scale(0.44288615) matrix(0.1,0,0,0.1,-7.57,-10.19)"></path><path fill="#fff" d="M54.06 98.03v6.86a1.7 1.7 0 0 0 1.71 1.7 1.7 1.7 0 0 0 1.71-1.7 1.71 1.71 0 1 1 3.43 0 5.14 5.14 0 1 1-10.28 0v-6.86a5.14 5.14 0 1 1 10.28 0 1.71 1.71 0 1 1-3.43 0 1.71 1.71 0 1 0-3.42 0zm27.41 6.86a1.7 1.7 0 0 1-1.71 1.7h-1.71v1.72c0 .46-.18.9-.5 1.21a1.7 1.7 0 0 1-2.43 0 1.7 1.7 0 0 1-.5-1.2v-1.72h-3.43v1.71a1.7 1.7 0 0 1-1.71 1.72 1.7 1.7 0 0 1-1.72-1.72v-1.71h-1.71a1.71 1.71 0 1 1 0-3.43h1.71v-3.43h-1.71a1.71 1.71 0 1 1 0-3.42h1.71V94.6a1.71 1.71 0 1 1 3.43 0v1.72h3.43V94.6a1.71 1.71 0 1 1 3.43 0v1.72h1.7c.46 0 .9.18 1.22.5a1.7 1.7 0 0 1 0 2.42 1.7 1.7 0 0 1-1.21.5h-1.71v3.43h1.7a1.7 1.7 0 0 1 1.72 1.71m-6.85-5.14h-3.43v3.42h3.43z" filter="url(#b-_r_1_)" style="mix-blend-mode: screen;" transform="scale(0.44288615) matrix(0.879,0,0,0.879,-30.96,-62.09)"></path></svg>

package/plugin/buildAlgoliaIndex.ts

@@ -1,10 +1,10 @@
 import Markdoc from '@markdoc/markdoc';
 import Stainless from '@stainless-api/sdk';
-import { createSDKJSON, parseInputs, transformOAS } from './cms/worker';
-import type * as SDKJSON from '~/lib/json-spec-v2/types';
-import { Languages } from '@stainless-api/docs-ui/src/routing';
-import { buildIndex } from '@stainless-api/docs-ui/src/search/providers/algolia';
-import type { VersionUserConfig } from './loadPluginConfig';
+import { createSDKJSON, parseInputs, transformOAS } from './specs/worker';
+import type * as SDKJSON from '@stainless/sdk-json';
+import { Languages } from '@stainless-api/docs-ui/routing';
+import { buildIndex } from '@stainless-api/docs-search/providers/algolia';
+import type { AstroIntegrationLogger } from 'astro';
 
 const markdocConfig = {
   nodes: {
@@ -20,11 +20,38 @@ function renderMarkdown(content?: string) {
   return Markdoc.renderers.html(transformed);
 }
 
-export async function buildAlgoliaIndex({ version, apiKey }: { version: VersionUserConfig; apiKey: string }) {
+export async function buildAlgoliaIndex({
+  stainlessProject,
+  branch,
+  apiKey,
+  logger,
+}: {
+  stainlessProject: string;
+  branch: string;
+  apiKey: string;
+  logger?: AstroIntegrationLogger;
+}) {
+  function warnLog(message: string) {
+    if (logger) {
+      logger.warn(message);
+    } else {
+      console.warn(message);
+    }
+  }
+
+  function infoLog(message: string) {
+    if (logger) {
+      logger.info(message);
+    } else {
+      console.log(message);
+    }
+  }
+
+  // TODO: this is all redundant with the spec code and should be DRYed
   const client = new Stainless({ apiKey });
   const configs = await client.projects.configs.retrieve({
-    project: version.stainlessProject,
-    branch: version.branch,
+    project: stainlessProject,
+    branch,
     include: 'openapi',
   });
 
@@ -42,7 +69,6 @@ export async function buildAlgoliaIndex({ version, apiKey }: { version: VersionU
   const languages =
     config.docs?.languages ??
     (Object.entries(config.targets)
-      // @ts-expect-error we don't have the actual Stainless config type here
       .filter(([name, target]) => Languages.includes(name) && !target.skip)
       .map(([name]) => name) as SDKJSON.SpecLanguage[]);
 
@@ -50,6 +76,7 @@ export async function buildAlgoliaIndex({ version, apiKey }: { version: VersionU
     oas: transformedOAS,
     config,
     languages,
+    projectName: stainlessProject,
   });
 
   const {
@@ -64,9 +91,9 @@ export async function buildAlgoliaIndex({ version, apiKey }: { version: VersionU
       !indexName && 'PUBLIC_ALGOLIA_INDEX',
       !algoliaWriteKey && 'PRIVATE_ALGOLIA_WRITE_KEY',
     ].filter(Boolean);
-    console.warn(`⚠️ Skipping Algolia indexing due to missing environment variables: ${missing.join(', ')}`);
+    warnLog(`Skipping Algolia indexing due to missing environment variables: ${missing.join(', ')}`);
     return;
   }
   await buildIndex(appId, indexName, algoliaWriteKey, sdkJson, renderMarkdown);
-  console.log('Indexing complete.');
+  infoLog('Indexing complete.');
 }

package/plugin/components/MethodDescription.tsx

@@ -0,0 +1,54 @@
+import { MethodDescriptionProps } from '@stainless-api/docs-ui/components';
+import { useComponents } from '@stainless-api/docs-ui/contexts/use-components';
+import style from '@stainless-api/docs-ui/style';
+import { Button } from '@stainless-api/ui-primitives';
+
+function shouldCollapseDescription(description: string) {
+  const MIN_CHARS = 400;
+  const MIN_LINES = 6;
+
+  const lineCount = description.split('\n').length;
+
+  if (description.length >= MIN_CHARS) return true;
+  if (lineCount >= MIN_LINES) return true;
+
+  // Markdown structure often means longer content
+  if (/#\s/.test(description)) return true; // has headings
+  if (/```/.test(description)) return true; // has code blocks
+  if (/^\s*[-*]\s+/m.test(description)) return true; // has lists
+
+  return false;
+}
+
+export function MethodDescription({ description }: MethodDescriptionProps) {
+  const { Markdown } = useComponents();
+
+  if (description) {
+    // Attempt to determine if we should make the description collapsible initially
+    // or not. If we get this right, there will be no FOUC.
+    const collapsible = shouldCollapseDescription(description);
+
+    return (
+      <div className="stl-method-description">
+        <div
+          className={style.MethodDescription}
+          data-stldocs-property-group="method-description"
+          data-collapsed={collapsible ? 'true' : 'false'}
+        >
+          <Markdown content={description} />
+        </div>
+        <div className="stl-method-description-overflow-wrapper">
+          <Button
+            type="button"
+            data-method-description-toggle
+            size="sm"
+            variant="ghost"
+            hidden={!collapsible}
+          >
+            Show more
+          </Button>
+        </div>
+      </div>
+    );
+  }
+}

package/plugin/components/RequestBuilder/ParamEditor.tsx

@@ -0,0 +1,55 @@
+import { useMemo } from 'react';
+import { Button } from '@stainless-api/ui-primitives';
+import type { Param } from './spec-helpers';
+import { InfoIcon } from 'lucide-react';
+import { Input } from '@stainless-api/docs-ui/components';
+
+function setHighlight(stainlessPath: string, highlighted: boolean) {
+  const ele = document.getElementById(stainlessPath);
+  if (!ele) return;
+  ele.classList.toggle('stldocs-property-highlighted', highlighted);
+  if (highlighted) {
+    if (location.hash) {
+      const prevScroll = document.documentElement.scrollTop;
+      location.hash = '';
+      document.documentElement.scrollTop = prevScroll;
+    }
+    if (document.body.clientWidth >= 1280) {
+      ele.scrollIntoView({
+        behavior: 'smooth',
+      });
+    }
+  }
+}
+
+function htmlToText(html: string) {
+  const template = document.createElement('template');
+  template.innerHTML = html;
+  return template.content.textContent;
+}
+
+export function ParamEditor({ param }: { param: Param }) {
+  const type = useMemo(() => htmlToText(param.type), [param.type]);
+
+  return (
+    <label className="request-builder-param">
+      <Button
+        className="request-builder-param-info-button"
+        variant="ghost"
+        href={`#${encodeURIComponent(param.stainlessPath)}`}
+      >
+        <Button.Icon icon={InfoIcon} size={16} />
+      </Button>
+
+      <span className="request-builder-param-label">{param.key}</span>
+      <span className="request-builder-param-colon">:</span>
+
+      <Input
+        className="request-builder-param-value"
+        onFocus={() => setHighlight(param.stainlessPath, true)}
+        onBlur={() => setHighlight(param.stainlessPath, false)}
+        placeholder={type}
+      />
+    </label>
+  );
+}

package/plugin/components/RequestBuilder/SnippetStainlessIsland.tsx

@@ -0,0 +1,107 @@
+import { useState, useMemo, useEffect, useId, useSyncExternalStore, Activity, Fragment } from 'react';
+import { createPortal } from 'react-dom';
+import { Button } from '@stainless-api/ui-primitives';
+import { PlayIcon, RotateCcw } from 'lucide-react';
+import { SnippetStainlessIslandPropsSchema } from './props';
+import { ParamEditor } from './ParamEditor';
+import './styles.css';
+
+function useRequiredChild<T extends Element = Element>(
+  parent: Element | null,
+  selector: string,
+): React.RefObject<T> {
+  const elementRef = useMemo(() => {
+    const el = parent?.querySelector<T>(selector);
+    return el ? { current: el } : null;
+  }, [parent, selector]);
+  if (!elementRef) throw new Error(`Required child not found: ${selector}`);
+  return elementRef;
+}
+
+function useSetVisibility(elementRef: React.RefObject<HTMLElement>, visible: boolean) {
+  useEffect(() => {
+    elementRef.current.style.display = visible ? '' : 'none';
+  }, [elementRef, visible]);
+}
+
+export default function SnippetStainlessIsland({ parent }: { parent: HTMLElement }) {
+  const [expanded, setExpanded] = useState(false);
+
+  const trigger = useRequiredChild<HTMLButtonElement>(parent, '.try-it-footer .try-it-button');
+  const codeContainer = useRequiredChild<HTMLElement>(parent, '.stldocs-snippet-code');
+  const exampleContainer = useRequiredChild<HTMLElement>(parent, '.stldocs-snippet-multi-response');
+  useSetVisibility(codeContainer, !expanded);
+  useSetVisibility(exampleContainer, !expanded);
+  useSetVisibility(trigger, !expanded);
+  // Attach click handler to trigger
+  useEffect(() => {
+    if (!trigger.current) return;
+    const ac = new AbortController();
+    trigger.current.addEventListener('click', () => setExpanded(true), { signal: ac.signal });
+    return () => ac.abort();
+  });
+
+  const requestBuilderContainer = useRequiredChild<HTMLElement>(parent, '.request-builder-container');
+  const requestBuilderFooter = useRequiredChild<HTMLElement>(parent, '.request-builder-footer');
+  const requestBuilderResponse = useRequiredChild<HTMLElement>(parent, '.request-builder-response');
+  const requestBuilderProps = useRequiredChild<HTMLTemplateElement>(parent, '.request-builder-props').current;
+  const serializedProps = useSyncExternalStore(
+    (cb) => {
+      const mutationObserver = new MutationObserver(() => cb());
+      mutationObserver.observe(requestBuilderProps, { childList: true });
+      return () => mutationObserver.disconnect();
+    },
+    () => requestBuilderProps.content.textContent,
+  );
+  const deserializedProps = SnippetStainlessIslandPropsSchema.parse(JSON.parse(serializedProps));
+  const groupedParams = Map.groupBy(deserializedProps.params, (p) => p.location);
+
+  const formId = `request-builder-form-${useId()}`;
+
+  return (
+    <>
+      {createPortal(
+        <Activity mode={expanded ? 'visible' : 'hidden'}>
+          <form
+            onSubmit={(e) => {
+              alert('TODO: Submit button clicked');
+              e.preventDefault();
+            }}
+            id={formId}
+          >
+            {[...groupedParams.entries()].map(([location, params]) => (
+              <Fragment key={location}>
+                <h4>{location} parameters</h4>
+                {params.map((e) => (
+                  <ParamEditor param={e} key={e.location + e.key} />
+                ))}
+              </Fragment>
+            ))}
+          </form>
+        </Activity>,
+        requestBuilderContainer.current,
+      )}
+
+      {createPortal(
+        <Activity mode={expanded ? 'visible' : 'hidden'}>
+          <Button variant="ghost" border={true} onClick={() => setExpanded(false)}>
+            <Button.Icon icon={RotateCcw} />
+          </Button>
+
+          <Button variant="success" className="send-button" type="submit" form={formId}>
+            <Button.Label>Send</Button.Label>
+            <Button.Icon icon={PlayIcon} />
+          </Button>
+        </Activity>,
+        requestBuilderFooter.current,
+      )}
+
+      {createPortal(
+        <Activity mode={expanded ? 'visible' : 'hidden'}>
+          <div>{/* TODO */}</div>
+        </Activity>,
+        requestBuilderResponse.current,
+      )}
+    </>
+  );
+}

package/plugin/components/RequestBuilder/index.tsx

@@ -0,0 +1,31 @@
+import { ReactNode } from 'react';
+import * as SDKJSON from '@stainless/sdk-json';
+import { useSpec } from '@stainless-api/docs-ui/contexts';
+import { extractParams } from './spec-helpers';
+import type { SnippetStainlessIslandProps } from './props';
+
+/** Load and process the spec on the server side to avoid inflating client bundle */
+export function RequestBuilder({
+  className,
+  children,
+  method,
+}: {
+  className: string;
+  children: ReactNode;
+  method: SDKJSON.Method;
+}) {
+  const spec = useSpec();
+  if (!spec) throw new Error('Spec is required for RequestBuilder');
+  const params = spec && extractParams(spec, method);
+  const [httpMethod, path] = method.endpoint.split(' ') as [string, string];
+
+  return (
+    <stl-island component="SnippetStainlessIsland" className={className}>
+      {/* Pass state down to the client component. TODO: we need a better solution for this */}
+      <template className="request-builder-props">
+        {JSON.stringify({ method: httpMethod, path, params } satisfies SnippetStainlessIslandProps)}
+      </template>
+      {children}
+    </stl-island>
+  );
+}

package/plugin/components/RequestBuilder/props.ts

@@ -0,0 +1,9 @@
+import z from 'zod';
+import { ParamSchema } from './spec-helpers';
+
+export const SnippetStainlessIslandPropsSchema = z.object({
+  method: z.string(),
+  path: z.string(),
+  params: z.array(ParamSchema),
+});
+export type SnippetStainlessIslandProps = z.infer<typeof SnippetStainlessIslandPropsSchema>;