@stainless-api/docs 0.1.0-beta.53 → 0.1.0-beta.55

package/CHANGELOG.md

@@ -1,15 +1,39 @@
 # @stainless-api/docs
 
-## 0.1.0-beta.53
+## 0.1.0-beta.55
+
+### Patch Changes
+
+- ae56b3c: ensure changeset release commit doesn’t include [skip ci]
+- Updated dependencies [ae56b3c]
+  - @stainless-api/docs-ui@0.1.0-beta.46
+  - @stainless-api/ui-primitives@0.1.0-beta.35
+
+## 0.1.0-beta.54
 
 ### Minor Changes
 
-- 2b0fec9: Added prose indexing for search
+- a70f60c: Adds the title property
+
+### Patch Changes
+
+- 2ebf696: enable trusted publishing
+- Updated dependencies [2ebf696]
+- Updated dependencies [a70f60c]
+  - @stainless-api/docs-ui@0.1.0-beta.45
+  - @stainless-api/ui-primitives@0.1.0-beta.34
+
+## 0.1.0-beta.53
 
 ### Patch Changes
 
-- Updated dependencies [2b0fec9]
+- 2e1639a: Updated preview worker and added experimental playgrounds feature.
+- Updated dependencies [239e28c]
+- Updated dependencies [ddc4593]
+- Updated dependencies [2e1639a]
+- Updated dependencies [2e1639a]
   - @stainless-api/docs-ui@0.1.0-beta.44
+  - @stainless-api/ui-primitives@0.1.0-beta.33
 
 ## 0.1.0-beta.52
 

package/eslint-suppressions.json

@@ -21,7 +21,7 @@
   },
   "plugin/cms/worker.ts": {
     "@typescript-eslint/no-explicit-any": {
-      "count": 4
+      "count": 3
     }
   },
   "plugin/components/SnippetCode.tsx": {
@@ -29,6 +29,11 @@
       "count": 1
     }
   },
+  "plugin/globalJs/copy.ts": {
+    "@typescript-eslint/no-explicit-any": {
+      "count": 3
+    }
+  },
   "plugin/index.ts": {
     "@typescript-eslint/no-explicit-any": {
       "count": 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainless-api/docs",
-  "version": "0.1.0-beta.53",
+  "version": "0.1.0-beta.55",
   "publishConfig": {
     "access": "public"
   },
@@ -11,6 +11,7 @@
     "./plugin": "./plugin/index.ts",
     "./plugin/middleware": "./plugin/middlewareBuilder/stlStarlightMiddleware.ts",
     "./plugin/MiddlewareTypes": "./plugin/middlewareBuilder/stainlessMiddleware.d.ts",
+    "./plugin/languages": "./plugin/languages.ts",
     "./stainless-docs/mintlify-compat": "./stl-docs/components/mintlify-compat/index.ts",
     "./mintlify-compat.css": "./styles/mintlify-compat.css",
     "./font-imports": "./styles/fonts.css",
@@ -34,7 +35,6 @@
     "@astrojs/markdown-remark": "^6.3.9",
     "@astrojs/react": "^4.4.2",
     "@stainless-api/sdk": "0.1.0-alpha.16",
-    "astro-expressive-code": "^0.41.3",
     "cheerio": "^1.1.2",
     "clsx": "^2.1.1",
     "dotenv": "17.2.3",
@@ -49,16 +49,17 @@
     "remark-stringify": "^11.0.0",
     "shiki": "^3.19.0",
     "unified": "^11.0.5",
+    "vite-plugin-prebundle-workers": "^0.2.0",
     "web-worker": "^1.5.0",
     "yaml": "^2.8.2",
-    "@stainless-api/ui-primitives": "0.1.0-beta.32",
-    "@stainless-api/docs-ui": "0.1.0-beta.44"
+    "@stainless-api/docs-ui": "0.1.0-beta.46",
+    "@stainless-api/ui-primitives": "0.1.0-beta.35"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.6",
     "@markdoc/markdoc": "^0.5.4",
     "@types/node": "24.10.1",
-    "@types/react": "^19.2.7",
+    "@types/react": "19.2.7",
     "@types/react-dom": "^19.2.3",
     "react": "^19.2.1",
     "react-dom": "^19.2.1",
@@ -66,8 +67,8 @@
     "typescript": "5.9.3",
     "vite": "^6.4.1",
     "zod": "^4.1.13",
-    "@stainless/sdk-json": "^0.1.0-beta.0",
-    "@stainless/eslint-config": "0.1.0-beta.0"
+    "@stainless/eslint-config": "0.1.0-beta.0",
+    "@stainless/sdk-json": "^0.1.0-beta.1"
   },
   "scripts": {
     "vendor-deps": "tsx scripts/vendor_deps.ts",

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

@@ -67,7 +67,6 @@ export async function buildAlgoliaIndex({
   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[]);
 
@@ -75,6 +74,7 @@ export async function buildAlgoliaIndex({
     oas: transformedOAS,
     config,
     languages,
+    version,
   });
 
   const {

package/plugin/cms/server.ts

@@ -35,6 +35,30 @@ function redactApiKey(apiKey: string) {
     .join('');
 }
 
+export type Auth = Array<{
+  type: 'http_bearer' | 'query' | 'header' | 'oauth2' | 'http_basic' | 'http_digest';
+  description?: string;
+  name: string;
+  title: string;
+  header: string | undefined;
+  example: string | undefined;
+  opts: {
+    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;
+    name: string;
+  }[];
+}>;
+
 async function loadSpec({
   apiKey,
   devPaths,
@@ -45,8 +69,8 @@ async function loadSpec({
   devPaths: InputFilePaths;
   version: VersionUserConfig;
   logger: AstroIntegrationLogger;
-}) {
-  async function unsafeLoad() {
+}): Promise<{ data: SDKJSON.Spec; auth: Auth; id: string }> {
+  async function unsafeLoad(): Promise<{ data: SDKJSON.Spec; auth: Auth; id: string }> {
     let oasStr: string;
     let configStr: string;
     let versions: Record<DocsLanguage, string> | undefined;
@@ -82,7 +106,6 @@ async function loadSpec({
     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[]);
 
@@ -90,6 +113,7 @@ async function loadSpec({
       oas: transformedOAS,
       config,
       languages,
+      version,
     });
 
     if (versions) {
@@ -100,9 +124,14 @@ async function loadSpec({
     }
 
     const id = crypto.randomUUID();
+    const opts = Object.entries(config.client_settings.opts).map(([k, v]) => ({ name: k, ...v }));
 
     return {
       data: sdkJson,
+      auth: sdkJson.security_schemes.map((scheme) => ({
+        ...scheme,
+        opts: opts.filter((opt) => opt.auth?.security_scheme === scheme.name),
+      })),
       id,
     };
   }
@@ -127,7 +156,7 @@ async function loadSpec({
 }
 
 class Spec {
-  private specPromise: Promise<{ id: string; data: SDKJSON.Spec }>;
+  private specPromise: Promise<{ id: string; data: SDKJSON.Spec; auth: Auth }>;
   private devPaths: InputFilePaths;
   private apiKey: string;
   private version: VersionUserConfig;
@@ -153,6 +182,7 @@ class Spec {
       return {
         id: spec.id,
         data: null,
+        auth: null,
       };
     }
 

package/plugin/cms/worker.ts

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 import fs from 'fs/promises';
 import pathutils from 'path';
+import type { VersionUserConfig } from '../loadPluginConfig';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -12,7 +13,81 @@ const __dirname = dirname(__filename);
 const workerPath = resolve(__dirname, '..', 'vendor', 'preview.worker.docs.js');
 
 type OpenAPIDocument = Record<string, any>;
-type ParsedConfig = Record<string, any>;
+export type ParsedConfig = {
+  docs:
+    | {
+        title?: string | undefined;
+        favicon?: string | undefined;
+        logo_icon?: string | undefined;
+        search?:
+          | {
+              algolia?:
+                | {
+                    app_id: string;
+                    index_name: string;
+                    search_key: string;
+                  }
+                | undefined;
+            }
+          | undefined;
+        description?: string | undefined;
+        languages?:
+          | ('node' | 'typescript' | 'python' | 'java' | 'kotlin' | 'go' | 'ruby' | 'terraform' | 'http')[]
+          | undefined;
+        snippets?:
+          | {
+              exclude_languages?: string[] | undefined;
+            }
+          | undefined;
+        show_security?: boolean | undefined;
+        show_readme?: boolean | undefined;
+        base_path?: string | undefined;
+        navigation?:
+          | {
+              menubar?:
+                | {
+                    title: string;
+                    icon?: string;
+                    variant?: string;
+                    href?: string | undefined;
+                    page?: string | undefined;
+                  }[]
+                | undefined;
+              sidebar?:
+                | {
+                    title: string;
+                    icon?: string;
+                    variant?: string;
+                    href?: string | undefined;
+                    page?: string | undefined;
+                  }[]
+                | undefined;
+            }
+          | undefined;
+        pages?: unknown;
+        resources?: unknown[] | undefined;
+      }
+    | undefined;
+  targets: Record<string, { skip?: boolean }>;
+  client_settings: {
+    opts: {
+      [x: 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;
+      };
+    };
+  };
+};
 
 function runJob({ type, signal, data }: { type: string; signal?: AbortSignal; data: any }) {
   const stainlessWorker = new Worker(workerPath, {
@@ -22,6 +97,7 @@ function runJob({ type, signal, data }: { type: string; signal?: AbortSignal; da
 
   return new Promise<any>((resolve, reject) => {
     stainlessWorker.addEventListener('error', (e) => {
+      e.preventDefault();
       reject(e);
     });
 
@@ -85,10 +161,12 @@ export async function createSDKJSON({
   oas,
   config,
   languages,
+  version,
 }: {
   oas: OpenAPIDocument;
   config: ParsedConfig;
   languages: DocsLanguage[];
+  version: VersionUserConfig;
 }) {
   const templatePath = resolve(__dirname, '../vendor/templates');
   const readmeLoader = await Promise.all(
@@ -113,7 +191,7 @@ export async function createSDKJSON({
       config,
       languages,
       transform: false,
-      projectName: '',
+      projectName: version.stainlessProject,
       readmeTemplates,
     },
   });

package/plugin/components/SnippetCode.tsx

@@ -6,9 +6,33 @@ import type {
 import { useHighlight, useLanguage } from '@stainless-api/docs-ui/contexts';
 import style from '@stainless-api/docs-ui/style';
 import * as cheerio from 'cheerio/slim';
-import { EXPERIMENTAL_COLLAPSIBLE_SNIPPETS } from 'virtual:stl-starlight-virtual-module';
+import {
+  EXPERIMENTAL_COLLAPSIBLE_SNIPPETS,
+  EXPERIMENTAL_PLAYGROUNDS,
+} from 'virtual:stl-starlight-virtual-module';
 import clsx from 'clsx';
 import { Button } from '@stainless-api/ui-primitives';
+import { CopyIcon } from 'lucide-react';
+
+function PlaygroundIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width={16}
+      height={16}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className={'lucide ' + style.Icon}
+      aria-hidden="true"
+    >
+      <path d="m 1,2 h 1 a 4,4 0 0 1 4,4 v 1 m 5,15 H 10 A 4,4 0 0 1 6,18 V 6 a 4,4 0 0 1 4,-4 h 1 M 1,22 H 2 A 4,4 0 0 0 6,18 V 17 M 14.029059,8.147837 A 1.2853426,1.2853426 0 0 1 15.978924,7.0437277 L 22.40178,10.8959 a 1.2853426,1.2853426 0 0 1 0,2.208219 l -6.422856,3.852172 a 1.2853426,1.2853426 0 0 1 -1.949865,-1.105395 z" />
+    </svg>
+  );
+}
 
 /*
  * This may be replaced by additional data from the sdk.
@@ -185,6 +209,23 @@ export function CondensibleSnippetCode({
   );
 }
 
+export function SnippetButtons({ content }: { content: string }) {
+  void content;
+  const language = useLanguage();
+  return (
+    <>
+      <Button variant="outline" data-stldocs-snippet-copy>
+        <CopyIcon size={16} className={style.Icon} />
+      </Button>
+      {EXPERIMENTAL_PLAYGROUNDS &&
+        (language === 'python' || language === 'typescript' || language === 'http') && (
+          <Button data-stldocs-snippet-play variant="muted" border title="Play">
+            <PlaygroundIcon />
+          </Button>
+        )}
+    </>
+  );
+}
 export function SnippetCode({ content, signature, language: forcedLanguage }: SnippetCodeProps) {
   const lang = useLanguage();
   const language = forcedLanguage || lang;

package/plugin/create-playground.shim.tsx

@@ -0,0 +1,3 @@
+export function createPlayground(): () => Promise<void> {
+  return () => Promise.resolve();
+}

package/plugin/globalJs/code-snippets.ts

@@ -43,24 +43,31 @@ document.addEventListener(getPageLoadEvent(), () => {
       // This is a bit funky, but it animates pretty smooth.
       // 1. Toggle to new state so we can measure the target height
       // 2. Reset to starting height to trigger transition
-      const startHeight = el.scrollHeight;
+      el.style.height = '';
+      el.style.overflowY = '';
+      const startHeight = el.getBoundingClientRect().height;
       el.classList.toggle('stl-snippet-code-is-expanded', expand);
       el.classList.toggle('stl-snippet-code-is-collapsed', !expand);
 
-      const endHeight = el.scrollHeight;
-
-      el.style.height = `${startHeight}px`;
-
-      requestAnimationFrame(() => {
-        el.style.height = `${endHeight}px`;
-      });
+      const endHeight = el.getBoundingClientRect().height;
 
       const onEnd = (e: TransitionEvent) => {
         if (e.propertyName !== 'height') return;
         el.style.height = '';
+        el.style.overflowY = '';
         el.removeEventListener('transitionend', onEnd);
       };
       el.addEventListener('transitionend', onEnd);
+
+      // Set initial height
+      el.style.height = `${startHeight}px`;
+      el.style.overflowY = 'hidden';
+
+      // Force layout recalculation
+      el.getBoundingClientRect();
+
+      // Start transition to end state
+      el.style.height = `${endHeight}px`;
     };
 
     if (collapsedDiv) {

package/plugin/globalJs/copy.ts

@@ -1,30 +1,39 @@
 import { EXPERIMENTAL_COLLAPSIBLE_SNIPPETS } from 'virtual:stl-starlight-virtual-module';
+import { getPageLoadEvent } from '../helpers/getPageLoadEvent';
 const copyIcon = `<rect width="14" height="14" x="8" y="8" rx="2" ry="2"/><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/>`;
 const circleAlertIcon = `<circle cx="12" cy="12" r="10"/><line x1="12" x2="12" y1="8" y2="12"/><line x1="12" x2="12.01" y1="16" y2="16"/>`;
 const checkIcon = `<path d="M20 6 9 17l-5-5"/>`;
 
+function getContent(button: HTMLElement, full: boolean) {
+  const isContentCollapsed = !!document.querySelector('.stldocs-snippet-code.stl-snippet-code-is-collapsed');
+
+  const content = button.closest('[data-stldocs-copy-parent]')!.querySelector('[data-stldocs-copy-content]')!;
+
+  const contentCopy = content.cloneNode(true) as HTMLElement;
+
+  contentCopy.querySelectorAll('.ellipsis').forEach((el) => el.remove());
+  if (EXPERIMENTAL_COLLAPSIBLE_SNIPPETS && isContentCollapsed && !full) {
+    contentCopy.querySelectorAll('.hidden').forEach((el) => el.remove());
+    contentCopy.querySelectorAll('.leading-ws').forEach((el) => el.remove());
+  }
+
+  return contentCopy.textContent!;
+}
+
+const preloadPlayground = async (event: Event) => {
+  const playButton = (event.target as HTMLElement).closest('[data-stldocs-snippet-play]') as HTMLElement;
+  if (playButton) {
+    loadPlayground(playButton);
+  }
+};
+addEventListener('mouseover', preloadPlayground);
 addEventListener('click', async (event) => {
   const copyButton = (event.target as HTMLElement).closest('[data-stldocs-snippet-copy]') as HTMLElement;
   if (copyButton) {
     const iconElement = copyButton.querySelector('.stldocs-icon') as SVGElement;
     clearTimeout(copyButton.dataset.__stldocsCopyTimeout);
     try {
-      const isContentCollapsed = !!document.querySelector(
-        '.stldocs-snippet-code.stl-snippet-code-is-collapsed',
-      );
-
-      const content = copyButton
-        .closest('[data-stldocs-copy-parent]')!
-        .querySelector('[data-stldocs-copy-content]')!;
-
-      const contentCopy = content.cloneNode(true) as HTMLElement;
-
-      contentCopy.querySelectorAll('.ellipsis').forEach((el) => el.remove());
-      if (EXPERIMENTAL_COLLAPSIBLE_SNIPPETS && isContentCollapsed) {
-        contentCopy.querySelectorAll('.hidden').forEach((el) => el.remove());
-        contentCopy.querySelectorAll('.leading-ws').forEach((el) => el.remove());
-      }
-      await navigator.clipboard.writeText(contentCopy.textContent!);
+      await navigator.clipboard.writeText(getContent(copyButton, false));
       iconElement.innerHTML = checkIcon;
     } catch {
       iconElement.innerHTML = circleAlertIcon;
@@ -34,4 +43,60 @@ addEventListener('click', async (event) => {
         iconElement.innerHTML = copyIcon;
       }, 1000) + '';
   }
+
+  const playButton = (event.target as HTMLElement).closest('[data-stldocs-snippet-play]') as HTMLElement;
+  if (playButton) {
+    showPlayground(playButton);
+  }
+});
+
+async function showPlayground(playButton: HTMLElement) {
+  if (playButton.getAttribute('aria-disabled') === 'true') return;
+  const iconElement = playButton.querySelector('.stldocs-icon') as SVGElement;
+  try {
+    // use aria-disabled, not disabled, to avoid losing focus
+    playButton.setAttribute('aria-disabled', 'true');
+    playButton.setAttribute('aria-label', 'Loading playground...');
+    playButton.classList.add('stl-ui-button--loading');
+    const showPlayground = loadPlayground(playButton);
+    await showPlayground();
+  } catch (e) {
+    console.error(e);
+    iconElement.innerHTML = circleAlertIcon;
+  }
+  playButton.removeAttribute('aria-disabled');
+  playButton.removeAttribute('aria-label');
+  playButton.classList.remove('stl-ui-button--loading');
+}
+
+function loadPlayground(playButton: HTMLElement) {
+  (playButton as any).__playgroundLoadPromise ??= (async () => {
+    const container = playButton.closest('.stldocs-snippet') as HTMLElement;
+    const language = (container.querySelector('.stl-sdk-select') as HTMLElement).dataset.currentValue;
+    const code = getContent(playButton, true);
+    // eslint-disable-next-line turbo/no-undeclared-env-vars
+    if (import.meta.env.DEV) {
+      const id = '/@id/astro:scripts/before-hydration.js';
+      await import(/* @vite-ignore */ id).catch(console.warn);
+    }
+    const { createPlayground } = await import('virtual:stl-playground/create');
+    return createPlayground({
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      lang: language as any,
+      doc: (language === 'python' ? 'from rich import print\n' : '') + code.trimEnd(),
+      container,
+    });
+  })();
+  return async () => {
+    const promise = (playButton as any).__playgroundLoadPromise;
+    (playButton as any).__playgroundLoadPromise = null;
+    await ((await promise) as () => Promise<void>)();
+  };
+}
+document.addEventListener(getPageLoadEvent(), () => {
+  if (new URL(location.href).searchParams.has('play')) {
+    document.querySelectorAll('[data-stldocs-snippet-play]').forEach((e) => {
+      showPlayground(e as HTMLElement);
+    });
+  }
 });