fix(docs): restore Paper interaction styling and verify responsive controls

Author: waleedlatif1

apps/docs/components/docs/navigation-drawer.tsx

@@ -54,7 +54,7 @@ export function DocsNavigationDrawer({ children }: DocsNavigationDrawerProps) {
             }}
             className={cn(
               docsScrollAreaClass,
-              'mt-5 min-h-0 flex-1 overflow-y-auto overscroll-contain pb-6'
+              '-mx-1 mt-5 min-h-0 flex-1 overflow-y-auto overscroll-contain px-1 pb-6'
             )}
           >
             <SidebarNavigation

apps/docs/components/docs/navigation.tsx

@@ -17,7 +17,7 @@ interface NavigationItemProps extends Omit<SidebarNavigationProps, 'nodes'> {
 }
 
 const rowClass =
-  'group flex min-h-[30px] w-full items-center gap-1.5 rounded-lg px-2 py-[5px] text-docs-nav text-[var(--docs-text)] transition-colors focus-visible:outline-2 focus-visible:outline-[var(--docs-muted)] focus-visible:-outline-offset-2'
+  'group flex min-h-[30px] w-full items-center gap-1.5 rounded-lg px-2 py-[5px] text-docs-nav text-[var(--docs-text)] transition-colors focus-visible:outline-2 focus-visible:outline-[var(--docs-link)] focus-visible:outline-offset-2'
 
 function containsPath(node: NavNode, pathname: string): boolean {
   return (
@@ -68,7 +68,8 @@ function NavigationItem({ node, pathname, onNavigate }: NavigationItemProps) {
         <div
           className={cn(
             'group/branch flex min-h-[30px] items-center rounded-lg transition-colors hover:bg-[var(--docs-hover)] active:bg-[var(--docs-pressed)]',
-            isCurrent && 'bg-[var(--docs-selected)] hover:bg-[var(--docs-selected-hover)]'
+            isCurrent &&
+              'bg-[var(--docs-selected)] shadow-[var(--docs-current-edge)] hover:bg-[var(--docs-selected-hover)]'
           )}
         >
           <Link
@@ -89,7 +90,7 @@ function NavigationItem({ node, pathname, onNavigate }: NavigationItemProps) {
               aria-label={`${expanded ? 'Collapse' : 'Expand'} ${node.title}`}
               aria-expanded={expanded}
               onClick={toggle}
-              className='focus-visible:-outline-offset-2 mr-0.5 flex size-7 shrink-0 items-center justify-center rounded-md opacity-0 focus-visible:opacity-100 focus-visible:outline-2 focus-visible:outline-[var(--docs-muted)] group-focus-within/branch:opacity-100 group-hover/branch:opacity-100 [@media(hover:none)]:opacity-100'
+              className='mr-0.5 flex size-7 shrink-0 items-center justify-center rounded-md opacity-0 focus-visible:opacity-100 focus-visible:outline-2 focus-visible:outline-[var(--docs-link)] group-focus-within/branch:opacity-100 group-hover/branch:opacity-100 [@media(hover:none)]:opacity-100'
             >
               <ChevronDown
                 className={cn('size-4 transition-transform', !expanded && '-rotate-90')}

apps/docs/components/docs/primitives.tsx

@@ -10,11 +10,10 @@ export const docsMenuClass =
 export const docsDialogClass =
   'docs-portal rounded-2xl border border-[var(--docs-border)] bg-[var(--docs-overlay)] text-[var(--docs-text)] shadow-[var(--docs-dialog-shadow)] backdrop-blur-[var(--docs-chrome-blur)]'
 
-export const docsScrollAreaClass =
-  '[scrollbar-width:thin] [scrollbar-color:var(--docs-muted)_transparent] [&::-webkit-scrollbar]:size-1.5 [&::-webkit-scrollbar-thumb]:rounded-full [&::-webkit-scrollbar-thumb]:bg-[var(--docs-muted)] [&::-webkit-scrollbar-track]:bg-transparent'
+export const docsScrollAreaClass = '[scrollbar-width:thin]'
 
 export const docsInlineLinkClass =
-  'rounded-sm font-semibold text-[var(--docs-link)] focus-visible:outline-2 focus-visible:outline-[var(--docs-link)] focus-visible:outline-offset-2'
+  'rounded-sm text-[var(--docs-prose-link)] underline decoration-current underline-offset-4 focus-visible:outline-2 focus-visible:outline-[var(--docs-link)] focus-visible:outline-offset-2 dark:underline-offset-[3px]'
 
 export const docsMenuItemClass =
   'flex min-h-[30px] cursor-pointer items-center gap-2 rounded-md px-2 outline-none data-[highlighted]:bg-[var(--docs-hover)] data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50 dark:data-[disabled]:text-[var(--docs-disabled)] dark:data-[disabled]:opacity-100'

apps/docs/components/docs/search.tsx

@@ -104,10 +104,10 @@ export function DocsSearchTrigger({ compact = false }: DocsSearchTriggerProps) {
       aria-haspopup='dialog'
       onClick={(event) => show?.(event.currentTarget)}
       className={cn(
-        'flex items-center gap-1.5 rounded-lg text-[var(--docs-muted)] text-docs-nav focus-visible:outline-2 focus-visible:outline-[var(--docs-link)] focus-visible:outline-offset-2',
+        'flex items-center gap-1.5 rounded-lg text-[var(--docs-muted)] text-docs-nav transition-colors hover:bg-[var(--docs-hover)] focus-visible:outline-2 focus-visible:outline-[var(--docs-link)] focus-visible:outline-offset-2 active:bg-[var(--docs-pressed)] motion-reduce:transition-none',
         compact
-          ? 'before:-z-10 relative isolate size-11 justify-center before:absolute before:inset-1.5 before:rounded-lg before:transition-colors hover:before:bg-[var(--docs-hover)] active:before:bg-[var(--docs-pressed)] motion-reduce:before:transition-none'
-          : 'h-[30px] w-full border border-[var(--docs-border)] bg-[var(--docs-reading)] px-[7px] transition-colors hover:bg-[var(--docs-hover)] active:bg-[var(--docs-pressed)] motion-reduce:transition-none'
+          ? 'size-11 justify-center'
+          : 'h-[30px] w-full border border-[var(--docs-border)] bg-[var(--docs-reading)] px-[7px]'
       )}
     >
       <Search className='size-4 shrink-0' aria-hidden />

apps/docs/components/docs/shell.tsx

@@ -98,7 +98,7 @@ export function DocsShell({ children, navigationBySection }: DocsShellProps) {
               key={section}
               className={cn(
                 docsScrollAreaClass,
-                'sticky top-24 hidden max-h-[calc(100dvh-120px)] min-w-0 space-y-5 overflow-y-auto overscroll-contain pb-5 lg:block'
+                '-mx-1 sticky top-24 hidden max-h-[calc(100dvh-120px)] min-w-0 space-y-5 overflow-y-auto overscroll-contain px-1 pb-5 lg:block'
               )}
             >
               <DocsSearchTrigger />

apps/docs/components/docs/table-of-contents.tsx

@@ -29,7 +29,7 @@ export function TableOfContents({ headings, active, compact = false }: TableOfCo
               'dark:-mx-2 block rounded-md pointer-coarse:py-3 text-docs-control leading-5 transition-colors focus-visible:outline-2 focus-visible:outline-[var(--docs-link)] focus-visible:outline-offset-2 dark:px-2 dark:hover:bg-[var(--docs-hover)]',
               depth > 2 && 'pl-3 dark:pl-5',
               active === id
-                ? 'font-medium text-[var(--docs-toc-current)]'
+                ? 'text-[var(--docs-toc-current)] dark:underline dark:underline-offset-[3px]'
                 : 'text-[var(--docs-muted)] hover:text-[var(--docs-heading)] dark:hover:text-[var(--docs-muted)]'
             )}
           >

apps/docs/components/docs/tokens.css

@@ -45,8 +45,10 @@
   --docs-hover: rgb(10 10 10 / 6%);
   --docs-selected: rgb(0 0 0 / 8%);
   --docs-selected-hover: var(--docs-selected);
+  --docs-current-edge: none;
   --docs-pressed: rgb(0 0 0 / 12%);
   --docs-link: #0066cc;
+  --docs-prose-link: var(--docs-link);
   --docs-toc-current: var(--docs-link);
   --docs-glass: rgb(255 255 255 / 80%);
   --docs-overlay: rgb(255 255 255 / 88%);
@@ -132,8 +134,10 @@
   --docs-hover: #2b2b2b;
   --docs-selected: #333;
   --docs-selected-hover: var(--docs-pressed);
+  --docs-current-edge: inset 2px 0 0 var(--docs-boundary);
   --docs-pressed: #3a3a3a;
   --docs-link: #8abeff;
+  --docs-prose-link: var(--docs-heading);
   --docs-toc-current: var(--docs-muted);
   --docs-glass: rgb(20 20 20 / 92%);
   --docs-overlay: rgb(36 36 36 / 92%);

apps/docs/scripts/benchmark-readiness.ts

@@ -15,6 +15,7 @@ import { createLogger } from '@sim/logger'
 import { getErrorMessage } from '@sim/utils/errors'
 import { sleep } from '@sim/utils/helpers'
 import { isRecordLike } from '@sim/utils/object'
+import { escapeRegExp } from '@sim/utils/string'
 
 /** Bounded production measurements: no builds, writes to services, or corpus crawling. */
 const logger = createLogger('DocsReadinessBenchmark', { logLevel: 'INFO' })
@@ -1014,17 +1015,35 @@ async function tabControl(
   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()
+    const list = run.page.getByRole('tablist', {
+      name: control.label,
+      exact: true,
+      includeHidden: true,
+    })
+    const tab = list.getByRole('tab', { name: control.choice, includeHidden: 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 choices = await list.getByRole('tab', { includeHidden: true }).count()
+    const presentation = (await tab.isVisible()) ? 'tabs' : 'menu'
+    let trigger = tab
+    if (presentation === 'menu') {
+      const picker = run.page.getByRole('button', {
+        name: new RegExp(`^${escapeRegExp(control.label)}:`),
+      })
+      if (!(await picker.isVisible()))
+        return {
+          status: 'unavailable',
+          error: `No visible ${control.label} control on this baseline.`,
+        }
+      await picker.click()
+      trigger = run.page.getByRole('menuitemradio', { name: control.choice }).first()
+    }
+    await trigger.scrollIntoViewIfNeeded()
     const start = performance.now()
-    await tab.click()
+    await trigger.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')
@@ -1036,6 +1055,7 @@ async function tabControl(
       feedbackMs: choices > 1 ? performance.now() - start : undefined,
       data: {
         choices,
+        presentation,
         selected: await tab.textContent(),
         contentLength: (await panel.textContent())?.length,
         applicableTransition: choices > 1,
@@ -1117,11 +1137,13 @@ async function apiControls(
     if (!(await button.count()))
       return { status: 'unavailable', error: 'No named request-copy button on this baseline.' }
     const selected = run.page
-      .getByRole('tablist', { name: 'Request language', exact: true })
-      .getByRole('tab', { selected: true })
+      .getByRole('tablist', { name: 'Request language', exact: true, includeHidden: true })
+      .getByRole('tab', { selected: true, includeHidden: true })
     const id = await selected.getAttribute('aria-controls')
     if (!id) throw new Error('Selected request has no panel')
-    const expected = await run.page.locator(`[id="${id}"] code`).textContent()
+    const panel = run.page.locator(`[id="${id}"]`)
+    await panel.waitFor({ state: 'visible' })
+    const expected = await panel.locator('code').textContent()
     await button.scrollIntoViewIfNeeded()
     const start = performance.now()
     await button.click()

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

@@ -1602,6 +1602,13 @@ try {
   })
 } finally {
   await browser?.close()
+  if (!results.length)
+    results.push({
+      name: 'Check selection',
+      status: 'failed',
+      durationMs: 0,
+      error: `No checks matched DOCS_NAVIGATION_FILTER=${process.env.DOCS_NAVIGATION_FILTER ?? ''}`,
+    })
   await writeFile(
     reportPath,
     `${JSON.stringify({ origin: target.origin, engine, limitations: engine === 'webkit' ? ['Clipboard readback, reduced-transparency emulation and controlled network throttling remain Chromium-only; this is Playwright WebKit, not native Safari.'] : [], results }, null, 2)}\n`

apps/docs/scripts/test-search-postgres-e2e.ts

@@ -296,6 +296,33 @@ async function verifyDatabase() {
     assert.equal(results[0]?.id, probe)
     assert.equal(results[0]?.url, 'https://docs.sim.ai/introduction')
   })
+  await check('Repeated lower-ranked chunks do not outrank a stronger page match', async () => {
+    const otherPage = getPage('/getting-started')
+    assert(otherPage)
+    const rankingQuery = 'simrankingprobe'
+    try {
+      for (const candidate of [page, otherPage])
+        await sql`
+          INSERT INTO docs_embeddings (chunk_id, chunk_text, source_document, source_link, header_text, header_level, token_count, embedding, metadata)
+          VALUES (${generateId()}, ${candidate === page ? `${rankingQuery} ${rankingQuery}` : rankingQuery}, ${candidate.sourcePath}, ${`https://docs.sim.ai${candidate.url}`}, ${candidate.title}, 1, 2, ${vector}::vector, ${sql.json({ contentHash: candidate.contentHash })})
+        `
+      const expected = ['https://docs.sim.ai/introduction', 'https://docs.sim.ai/getting-started']
+      assert.deepEqual(
+        (await searchDocs(rankingQuery)).map((result) => result.url),
+        expected
+      )
+      await sql`
+        INSERT INTO docs_embeddings (chunk_id, chunk_text, source_document, source_link, header_text, header_level, token_count, embedding, metadata)
+        VALUES (${generateId()}, ${rankingQuery}, ${otherPage.sourcePath}, 'https://docs.sim.ai/getting-started', ${otherPage.title}, 1, 1, ${vector}::vector, ${sql.json({ contentHash: otherPage.contentHash })})
+      `
+      assert.deepEqual(
+        (await searchDocs(rankingQuery)).map((result) => result.url),
+        expected
+      )
+    } finally {
+      await sql`DELETE FROM docs_embeddings WHERE chunk_text_tsv @@ plainto_tsquery('english', ${rankingQuery})`
+    }
+  })
   await check('Stale index hashes cannot supply search citations', async () => {
     await sql`UPDATE docs_embeddings SET metadata = '{"contentHash":"stale"}' WHERE chunk_id = ${probe}`
     assert.deepEqual(await searchDocs(query), [])