fix(docs): expose root response schemas and generate clean-checkout types

Author: emir-karabeg

apps/docs/components/docs/api-schema.tsx

@@ -88,14 +88,12 @@ export function ApiSchema({ schema: raw, document, name, required, ancestors = [
         : (reference?.split('/').at(-1) ?? 'value')
   return (
     <div className='min-w-0 py-4'>
-      {name && (
-        <div className='mb-2 flex flex-wrap items-baseline gap-2.5 font-mono text-docs-control leading-5'>
-          <span className='break-all text-[var(--docs-heading)]'>{name}</span>
-          <span className='text-[var(--docs-muted)]'>{type}</span>
-          {required && <span className='ml-auto text-[var(--docs-muted)]'>Required</span>}
-          {schema.deprecated === true && <NeutralBadge>Deprecated</NeutralBadge>}
-        </div>
-      )}
+      <div className='mb-2 flex flex-wrap items-baseline gap-2.5 font-mono text-docs-control leading-5'>
+        {name && <span className='break-all text-[var(--docs-heading)]'>{name}</span>}
+        <span className='text-[var(--docs-muted)]'>{type}</span>
+        {required && <span className='ml-auto text-[var(--docs-muted)]'>Required</span>}
+        {schema.deprecated === true && <NeutralBadge>Deprecated</NeutralBadge>}
+      </div>
       {typeof schema.description === 'string' && (
         <div className='text-[var(--docs-muted)] text-docs-table [&_p]:my-0 [&_p]:text-docs-table [&_p]:text-inherit'>
           <Markdown>{schema.description}</Markdown>

apps/docs/components/ui/tabs.tsx

@@ -170,7 +170,7 @@ export function Tabs({
       >
         <noscript>
           <style>{`
-            .docs-root [data-docs-tab-panel][hidden] { display: block; }
+            .docs-root [data-docs-tab-panel][hidden] { display: block !important; }
             .docs-root [data-docs-tabs-root] [role="tablist"],
             .docs-root [data-docs-tabs-root] select,
             .docs-root [data-docs-tabs-root] button { display: none; }

apps/docs/package.json

@@ -12,7 +12,7 @@
     "test": "vitest run",
     "test:negotiation:e2e": "bun scripts/test-negotiation-e2e.ts",
     "test:headers:e2e": "bun scripts/test-header-merge-e2e.ts",
-    "type-check": "bun run content:generate && tsc --noEmit",
+    "type-check": "bun run content:generate && next typegen && tsc --noEmit",
     "lint": "biome check --write --unsafe .",
     "lint:check": "biome check .",
     "format": "biome format --write .",

apps/docs/scripts/benchmark-readiness.ts

@@ -609,8 +609,8 @@ async function existingLink(page: Page, route: string): Promise<Locator | null>
 
 function searchInput(page: Page) {
   return page
-    .getByRole('combobox')
-    .or(page.getByRole('searchbox'))
+    .getByRole('combobox', { name: /Search/i })
+    .or(page.getByRole('searchbox', { name: /Search/i }))
     .or(page.getByPlaceholder(/Search/))
     .filter({ visible: true })
     .first()
@@ -629,7 +629,7 @@ async function readyForControls(page: Page) {
       .click()
   }
   await input.waitFor()
-  await page.waitForFunction(() => document.activeElement instanceof HTMLInputElement)
+  await expect(input).toBeFocused()
   await page.keyboard.press('Escape')
   await input.waitFor({ state: 'hidden' })
 }
@@ -940,11 +940,7 @@ async function interactions(browser: Browser, profile: Profile, repetition: numb
       const trigger = run.page
         .getByRole('button', { name: /^(Expand .*workflow preview|Inspect workflow: .*)$/i })
         .first()
-      if (!(await trigger.count()))
-        return {
-          status: 'unavailable',
-          error: 'No named workflow inspection trigger on this baseline.',
-        }
+      await trigger.waitFor({ state: 'visible', timeout: 15_000 })
       await trigger.scrollIntoViewIfNeeded()
       const start = performance.now()
       await trigger.click()
@@ -1007,6 +1003,44 @@ async function interactions(browser: Browser, profile: Profile, repetition: numb
   }
 }
 
+async function tabControl(
+  run: Awaited<ReturnType<typeof contextFor>>,
+  profile: Profile,
+  repetition: number,
+  route: string,
+  control: { scenario: string; label: string; choice: RegExp }
+) {
+  await measure(profile, route, repetition, control.scenario, async () => {
+    const list = run.page.getByRole('tablist', { name: control.label, exact: true })
+    const tab = list.getByRole('tab', { name: control.choice }).filter({ visible: true }).first()
+    if (!(await tab.count()))
+      return {
+        status: 'unavailable',
+        error: `No matching ${control.label} tab on this baseline.`,
+      }
+    const choices = await list.getByRole('tab').count()
+    await tab.scrollIntoViewIfNeeded()
+    const start = performance.now()
+    await tab.click()
+    await expect(tab).toHaveAttribute('aria-selected', 'true')
+    const id = await tab.getAttribute('aria-controls')
+    if (!id) throw new Error('Tab has no linked content')
+    const panel = run.page.locator(`[id="${id}"]`)
+    await panel.waitFor({ state: 'visible' })
+    await painted(run.page)
+    return {
+      status: 'completed',
+      feedbackMs: choices > 1 ? performance.now() - start : undefined,
+      data: {
+        choices,
+        selected: await tab.textContent(),
+        contentLength: (await panel.textContent())?.length,
+        applicableTransition: choices > 1,
+      },
+    }
+  })
+}
+
 async function apiControls(
   run: Awaited<ReturnType<typeof contextFor>>,
   profile: Profile,
@@ -1037,39 +1071,11 @@ async function apiControls(
     { scenario: 'response-status-control', label: 'Response status', choice: /^400$/ },
     {
       scenario: 'response-media-control',
-      label: 'Response 400 content type',
+      label: '400 response content type',
       choice: /^application\/json$/,
     },
   ]) {
-    await measure(profile, route, repetition, control.scenario, async () => {
-      const list = run.page.getByRole('tablist', { name: control.label, exact: true })
-      const tab = list.getByRole('tab', { name: control.choice }).filter({ visible: true }).first()
-      if (!(await tab.count()))
-        return {
-          status: 'unavailable',
-          error: `No matching ${control.label} tab on this baseline.`,
-        }
-      const choices = await list.getByRole('tab').count()
-      await tab.scrollIntoViewIfNeeded()
-      const start = performance.now()
-      await tab.click()
-      await expect(tab).toHaveAttribute('aria-selected', 'true')
-      const id = await tab.getAttribute('aria-controls')
-      if (!id) throw new Error('Tab has no linked content')
-      const panel = run.page.locator(`[id="${id}"]`)
-      await panel.waitFor({ state: 'visible' })
-      await painted(run.page)
-      return {
-        status: 'completed',
-        feedbackMs: choices > 1 ? performance.now() - start : undefined,
-        data: {
-          choices,
-          selected: await tab.textContent(),
-          contentLength: (await panel.textContent())?.length,
-          applicableTransition: choices > 1,
-        },
-      }
-    })
+    await tabControl(run, profile, repetition, route, control)
   }
   await measure(profile, route, repetition, 'schema-disclosure-control', async () => {
     const details = run.page.locator('main details:not([open])').filter({ visible: true }).first()
@@ -1127,6 +1133,21 @@ async function apiControls(
       data: { exactSelectedSampleCopied: true, characters: expected?.length },
     }
   })
+  const streamingRoute = '/api-reference/workflows/executeWorkflowV2'
+  await measure(profile, streamingRoute, repetition, 'response-format-readiness', async () => {
+    const response = await run.page.goto(new URL(streamingRoute, base).href, {
+      waitUntil: 'domcontentloaded',
+    })
+    if (!response?.ok()) throw new Error(`Document returned ${response?.status()}`)
+    await meaningful(run.page, streamingRoute)
+    await readyForControls(run.page)
+    return { status: 'completed' }
+  })
+  await tabControl(run, profile, repetition, streamingRoute, {
+    scenario: 'response-format-control',
+    label: '200 response content type',
+    choice: /^text\/event-stream$/,
+  })
 }
 
 async function lighthouse(profile: Profile, route: string, repetition: number) {
@@ -1282,6 +1303,14 @@ if (mode === 'lighthouse') {
           }
         }
         if (scenarios.has('interactions')) await interactions(browser, profile, repetition)
+        else if (scenarios.has('api-controls')) {
+          const run = await contextFor(browser, profile)
+          try {
+            await apiControls(run, profile, repetition)
+          } finally {
+            await run.context.close()
+          }
+        }
       }
   } finally {
     await browser.close()

apps/docs/scripts/test-navigation-e2e.ts

@@ -66,7 +66,7 @@ async function check(name: string, action: () => Promise<void>, unavailable?: st
 
 async function open(page: Page, path: string) {
   const response = await page.goto(new URL(path, target).href, { waitUntil: 'domcontentloaded' })
-  expect(response?.ok()).toBe(true)
+  expect(response?.ok() || response?.status() === 304).toBe(true)
   await expect(page.getByRole('heading', { level: 1 }).first()).toBeVisible()
   await page.evaluate(() => document.fonts.ready)
   await expect(
@@ -686,6 +686,75 @@ try {
       await expect(page.locator(`[id="${panelId}"]`)).toBeVisible()
       await page.screenshot({ path: join(directory, 'api-language-after-reload.png') })
     })
+    await check(
+      'Streaming response formats expose their type without changing request language',
+      async () => {
+        const page = await languageContext.newPage()
+        try {
+          await open(page, '/api-reference/workflows/executeWorkflowV2')
+          const language = page.getByRole('combobox', { name: 'Request status', exact: true })
+          const python = await language
+            .getByRole('option', { name: /^Python/ })
+            .first()
+            .getAttribute('value')
+          if (!python) throw new Error('Execute workflow has no Python request example')
+          await language.selectOption(python)
+          await expect(language).toHaveValue(python)
+          const requestId = await language.getAttribute('aria-controls')
+          if (!requestId) throw new Error('Selected request has no sample panel')
+          const request = page.locator(`[id="${requestId}"] code`)
+          const originalSample = await request.textContent()
+          const formats = page.getByRole('tablist', {
+            name: '200 response content type',
+            exact: true,
+          })
+          const observations = []
+          const missingTypes: string[] = []
+          for (const [index, format] of [
+            'application/json',
+            'application/x-ndjson',
+            'text/event-stream',
+          ].entries()) {
+            const tab = formats.getByRole('tab', { name: format, exact: true })
+            await tab.click()
+            await expect(tab).toHaveAttribute('aria-selected', 'true')
+            const panelId = await tab.getAttribute('aria-controls')
+            if (!panelId) throw new Error(`Response format ${format} has no panel`)
+            const panel = page.locator(`[id="${panelId}"]`)
+            await expect(panel).toBeVisible()
+            await expect(language).toHaveValue(python)
+            await expect(request).toHaveText(originalSample ?? '')
+            const stringTypeVisible = await panel
+              .getByText('string', { exact: true })
+              .first()
+              .isVisible()
+            if (format !== 'application/json' && !stringTypeVisible) missingTypes.push(format)
+            if (format === 'application/json')
+              expect((await panel.innerText()).trim().length).toBeGreaterThan(0)
+            observations.push({
+              format,
+              stringTypeVisible,
+              requestLanguage: 'Python',
+              requestSampleUnchanged: true,
+              contentLength: (await panel.innerText()).trim().length,
+            })
+            await panel.scrollIntoViewIfNeeded()
+            await page.screenshot({
+              path: join(directory, `streaming-response-format-${index}.png`),
+            })
+          }
+          await writeFile(
+            join(directory, 'streaming-response-formats.json'),
+            `${JSON.stringify(observations, null, 2)}\n`
+          )
+          expect(missingTypes, 'Streaming response schemas must display their string type').toEqual(
+            []
+          )
+        } finally {
+          await page.close()
+        }
+      }
+    )
     await check('API language preference tolerates an unavailable stored language', async () => {
       const page = await languageContext.newPage()
       await open(page, '/api-reference/logs/getLog')