fix(docs): finish accessible controls and cached content validation

Author: waleedlatif1

apps/docs/components/docs/article.tsx

@@ -5,7 +5,8 @@ import { ContentInteractions } from '@/components/docs/content-interactions'
 import { PageActions } from '@/components/docs/page-actions'
 import { IntegrationIcon } from '@/components/ui/integration-icon'
 import { getNavigation, getNeighbours } from '@/lib/content/catalog'
-import type { DocsPage, NavNode } from '@/lib/content/types'
+import { findNavigationGroup } from '@/lib/content/navigation'
+import type { DocsPage } from '@/lib/content/types'
 import { DOCS_BASE_URL } from '@/lib/urls'
 
 interface ArticleProps {
@@ -14,21 +15,9 @@ interface ArticleProps {
   aside?: ReactNode
 }
 
-function findGroup(nodes: NavNode[], url: string, label = ''): string | undefined {
-  let current = label
-  for (const node of nodes) {
-    if (node.kind === 'label') current = node.title
-    if (node.url === url) return current
-    if (node.children) {
-      const found = findGroup(node.children, url, node.title)
-      if (found !== undefined) return found
-    }
-  }
-}
-
 export function Article({ page, children, aside }: ArticleProps) {
   const group =
-    findGroup(getNavigation(page.section), page.url) ||
+    findNavigationGroup(getNavigation(page.section), page.url) ||
     { docs: 'Documentation', api: 'API reference', cli: 'CLI', mcp: 'MCP' }[page.section]
   const { previous, next } = getNeighbours(page)
   const source = page.operation

apps/docs/components/docs/page-actions.tsx

@@ -87,13 +87,19 @@ export function PageActions({ url }: PageActionsProps) {
       </Dropdown.Root>
       <span
         role='status'
-        className='absolute top-full right-0 z-10 whitespace-nowrap text-[var(--docs-muted)] text-docs-caption'
+        className={
+          showCopied
+            ? 'sr-only'
+            : 'absolute top-full right-0 z-10 whitespace-nowrap text-[var(--docs-muted)] text-docs-caption'
+        }
       >
         {status === 'error'
           ? 'Could not copy. Try again or view Markdown.'
           : status === 'ready'
             ? 'Select again to copy.'
-            : ''}
+            : showCopied
+              ? 'Copied to clipboard.'
+              : ''}
       </span>
     </div>
   )

apps/docs/components/ui/tabs.tsx

@@ -181,8 +181,7 @@ export function Tabs({
               .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; }
+            .docs-root [data-docs-tabs-select] { display: none; }
           `}</style>
         </noscript>
         {items && (
@@ -216,6 +215,7 @@ export function TabsSelect({ items, label, className, ...props }: TabsSelectProp
     <Dropdown.Root modal={false}>
       <Dropdown.Trigger
         {...props}
+        data-docs-tabs-select=''
         aria-label={`${label}: ${selected?.label ?? ''}`}
         className={cn(docsControlClass, 'min-w-0 max-w-full shrink px-2', className)}
       >

apps/docs/lib/content/markdown.ts

@@ -117,11 +117,13 @@ export function serializeMarkdown(tree: Root): string {
       switch (node.name) {
         case 'WorkflowPreview':
           return [paragraph('Workflow configuration'), json(props.workflow)]
-        case 'BlockPreview':
-          return [
-            paragraph(`${String(props.type)} block configuration`),
-            json(BLOCK_DISPLAY_WORKFLOWS[String(props.type)]),
-          ]
+        case 'BlockPreview': {
+          const type = props.type
+          if (typeof type !== 'string' || !Object.hasOwn(BLOCK_DISPLAY_WORKFLOWS, type))
+            throw new Error(`Unknown documentation block preview: ${String(type)}`)
+          const workflow = BLOCK_DISPLAY_WORKFLOWS[type]
+          return [paragraph(`${type} block configuration`), json(workflow)]
+        }
         case 'OutputBundle':
           return [
             paragraph(`Output from ${String(props.blockName)}`),

apps/docs/lib/content/navigation.ts

@@ -178,3 +178,16 @@ export function flattenNavigation(nodes: NavNode[]): NavNode[] {
   walk(nodes)
   return flat
 }
+
+/** Returns the same parent label used by page headers and search results. */
+export function findNavigationGroup(nodes: NavNode[], url: string, label = ''): string | undefined {
+  let current = label
+  for (const node of nodes) {
+    if (node.kind === 'label') current = node.title
+    if (node.url === url) return current
+    if (node.children) {
+      const found = findNavigationGroup(node.children, url, node.title)
+      if (found !== undefined) return found
+    }
+  }
+}

apps/docs/lib/http/pages.ts

@@ -54,7 +54,8 @@ export function listPages(input: z.input<typeof listPagesSchema>) {
 /** Catalog lookup is the entire read boundary: no caller-supplied URL is fetched. */
 export function readPage(path: string) {
   const parsed = pagePathSchema.parse(path)
-  const page = getPage(parsed)
+  const canonical = parsed === '/' ? parsed : parsed.replace(/\/$/, '')
+  const page = getPage(canonical)
   if (!page || page.url === '/') return null
   return { ...pageMetadata(page), headings: page.headings, markdown: page.markdown }
 }

apps/docs/lib/search/service.ts

@@ -1,6 +1,7 @@
 import { createLogger } from '@sim/logger'
 import { compareStrings, truncateAtCodePoint } from '@sim/utils/string'
-import { getPage } from '@/lib/content/catalog'
+import { getNavigation, getPage } from '@/lib/content/catalog'
+import { findNavigationGroup } from '@/lib/content/navigation'
 import type { DocsPage } from '@/lib/content/types'
 import { generateSearchEmbedding } from '@/lib/embeddings'
 import { getSearchIndex } from '@/lib/search/precomputed'
@@ -27,12 +28,18 @@ const SECTION_LABELS = { docs: 'Documentation', api: 'API reference', cli: 'CLI'
 let hybridRequests = 0
 
 function resultFor(page: DocsPage, id: string, url: string, heading: string): SearchResult {
+  const section = SECTION_LABELS[page.section]
+  const group = findNavigationGroup(getNavigation(page.section), page.url)
   return {
     id,
     type: 'page',
     url,
     content: heading || page.title,
-    breadcrumbs: [SECTION_LABELS[page.section], page.title],
+    breadcrumbs: [
+      section,
+      ...(group && group !== section && group !== page.title ? [group] : []),
+      page.title,
+    ],
   }
 }
 

apps/docs/migration/VERIFICATION.md

@@ -69,7 +69,7 @@ Compared the introduction and Files pages with the live docs and their source co
 
 All eight new framing scenarios failed on the previous renderer ([report](verification/images-before-fix.json)). They now pass at 390px and 1440px, checking loaded backgrounds, relative image geometry, the hero crop, and viewer backgrounds. The complete production browser suite passes all 58 scenarios; [all 2,996 corpus/asset checks pass](verification/image-corpus.json). See [desktop hero](verification/screenshots/image-hero-1440.png), [mobile hero](verification/screenshots/image-hero-390.png), [overview](verification/screenshots/image-overview-1440.png), and [detail](verification/screenshots/image-detail-1440.png).
 
-The retained corpus report is the unmodified `docs-corpus.json` from [CI run 40987306209](https://github.com/simstudioai/sim/actions/runs/40987306209), artifact `12947558143`, at screenshot commit `703e2c1b0e50f908766e52091026777f40ed6145`. It started at `2026-10-30T01:44:31.862Z` and records 2,996 passing checks, zero failures. Its SHA-256 is `591694c2df9152307881fa7722b52cfa0ba9ada327d1d7a80f251091691742b6`. That workflow failed in another suite; this report establishes the corpus result only. It replaces a summary whose source report could not be verified.
+The retained corpus report contains the complete `docs-corpus.json` from [CI run 40987306209](https://github.com/simstudioai/sim/actions/runs/40987306209), artifact `12947558143`, at screenshot commit `703e2c1b0e50f908766e52091026777f40ed6145`. It started at `2026-10-30T01:44:31.862Z` and records 2,996 passing checks, zero failures. The raw artifact SHA-256 is `591694c2df9152307881fa7722b52cfa0ba9ada327d1d7a80f251091691742b6`; the committed copy has repository formatting with identical JSON values and SHA-256 `dbd979dd2eb1053db948a6b755bb83aedca61789efdc1ef74f753f8534ca51a9`. That workflow failed in another suite; this report establishes the corpus result only. It replaces a summary whose source report could not be verified.
 
 Production build, root lint, all 26 workspace type checks, all 61 audits, the docs unit suite, and the block registry check passed. The root test command stopped on six timeouts across four script files; rerunning those files after the other checks completed passed all 78 tests. The latest root invocation did not reach the workspace suites.
 

apps/docs/migration/verification/image-corpus.json

@@ -180,6 +180,15 @@ async function readCache(): Promise<CompiledCache> {
   }
 }
 
+function validateMedia(relative: string, mediaPaths: string[]) {
+  for (const media of mediaPaths)
+    if (
+      media.startsWith('/') &&
+      !existsSync(path.join(DOCS_ROOT, 'public', decodeURIComponent(media.split(/[?#]/)[0])))
+    )
+      throw new Error(`${relative}: missing media ${media}`)
+}
+
 async function generate() {
   await mkdir(path.join(OUTPUT_ROOT, 'pages'), { recursive: true })
   const pipelineFiles = [
@@ -221,6 +230,7 @@ async function generate() {
       prior?.hash === sourceHash &&
       existsSync(javascriptPath)
     ) {
+      validateMedia(relative, prior.media)
       const { lastModified: _previousDate, ...content } = prior.page
       const date = dates.get(file)
       const page = { ...content, ...(date ? { lastModified: date } : {}) }
@@ -256,12 +266,7 @@ async function generate() {
       contentHash: hash(markdown),
       ...(dates.get(file) ? { lastModified: dates.get(file) } : {}),
     }
-    for (const media of result.media)
-      if (
-        media.startsWith('/') &&
-        !existsSync(path.join(DOCS_ROOT, 'public', decodeURIComponent(media.split(/[?#]/)[0])))
-      )
-        throw new Error(`${relative}: missing media ${media}`)
+    validateMedia(relative, result.media)
     await writeFile(javascriptPath, result.javascript)
     await writeFile(
       javascriptPath.replace(/\.js$/, '.d.ts'),