@agentskit/doc-bridge 1.6.4 → 1.7.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentskit/doc-bridge",
-  "version": "1.6.4",
+  "version": "1.7.45",
   "mcpName": "io.github.AgentsKit-io/doc-bridge",
   "description": "Human↔agent documentation bridge — deterministic handoffs, doc-site links, memory→docs, optional AgentsKit RAG/chat.",
   "type": "module",
@@ -46,51 +46,6 @@
     "src",
     "skills"
   ],
-  "scripts": {
-    "prebuild": "node scripts/sync-version.mjs",
-    "build": "tsup",
-    "test": "vitest run && pnpm test:cursor-plugin && pnpm test:claude-plugin && pnpm test:copilot-plugin && pnpm test:portable-skill",
-    "test:watch": "vitest",
-    "coverage": "vitest run --coverage",
-    "check:ecosystem-upstream": "node scripts/check-ecosystem-upstream.mjs",
-    "check:no-legacy-chat-imports": "node scripts/check-no-legacy-chat-imports.mjs",
-    "typecheck": "tsc --noEmit",
-    "smoke:packaged": "node scripts/smoke-packaged.mjs",
-    "smoke:docsites": "node scripts/smoke-docsites.mjs",
-    "smoke:real-docsites": "node scripts/smoke-real-docsites.mjs",
-    "smoke:ollama": "node scripts/smoke-ollama.mjs",
-    "mcpb:stage": "npm run build && node scripts/build-mcpb.mjs stage",
-    "mcpb:validate": "node scripts/build-mcpb.mjs validate",
-    "mcpb:smoke": "node scripts/smoke-mcpb.mjs",
-    "mcpb:pack": "npm run mcpb:stage && npm run mcpb:smoke && node scripts/build-mcpb.mjs pack",
-    "test:mcpb": "node --test scripts/mcpb-contract.test.mjs",
-    "test:cursor-plugin": "node --test scripts/cursor-plugin-contract.test.mjs",
-    "test:claude-plugin": "node --test scripts/claude-plugin-contract.test.mjs",
-    "test:copilot-plugin": "node --test scripts/copilot-plugin-contract.test.mjs",
-    "test:portable-skill": "node --test scripts/portable-skill-contract.test.mjs",
-    "coverage:badge": "node scripts/update-coverage-badge.mjs",
-    "changeset": "changeset",
-    "version-packages": "changeset version && node scripts/sync-version.mjs",
-    "release": "npm run build && npm test && changeset publish",
-    "version": "node scripts/sync-version.mjs && git add package.json src/version.ts action.yml",
-    "prepublishOnly": "npm run build && npm test",
-    "prepare": "node scripts/prepare.mjs",
-    "prepack": "npm run build",
-    "docs:dev": "cd apps/docs && next dev",
-    "docs:artifacts": "node scripts/build-docs-artifacts.mjs",
-    "docs:build": "pnpm build && node bin/ak-docs.js index && pnpm docs:artifacts && cd apps/docs && next build",
-    "docs:typecheck": "cd apps/docs && fumadocs-mdx && tsc --noEmit",
-    "docs:e2e": "playwright test",
-    "report:visual": "node scripts/report-visual-check.mjs",
-    "test:verification-harness": "node --test scripts/verification-harness.test.mjs",
-    "docs:lighthouse": "lhci autorun",
-    "test:readme-standard": "node --test scripts/readme-standard.test.mjs",
-    "test:marketplace": "node --test scripts/marketplace-contract.test.mjs",
-    "check:marketplace": "node scripts/check-marketplace-contract.mjs",
-    "test:docs-artifacts": "node --test scripts/docs-artifacts-contract.test.mjs",
-    "check:readme-standard": "node scripts/check-readme-standard.mjs",
-    "check:docs": "pnpm check:readme-standard && node bin/ak-docs.js gate run && node bin/ak-docs.js conformance run documentation-standard-v1 --text && pnpm docs:typecheck && pnpm docs:build && pnpm test:docs-artifacts"
-  },
   "keywords": [
     "agentskit",
     "documentation",
@@ -120,10 +75,10 @@
   },
   "dependencies": {
     "github-slugger": "^2.0.0",
-    "mermaid": "^11.16.1",
+    "mermaid": "^11.17.2",
     "minimatch": "^10.2.6",
     "typescript": "^6.0.3",
-    "zod": "^3.24.2"
+    "zod": "^4.4.3"
   },
   "peerDependencies": {
     "@agentskit/adapters": ">=0.12.0 <1",
@@ -154,30 +109,31 @@
     }
   },
   "devDependencies": {
-    "@agentskit/chat": "0.4.0",
-    "@agentskit/core": "1.12.3",
-    "@agentskit/ink": "0.10.4",
+    "@agentskit/chat": "0.4.1",
+    "@agentskit/core": "1.12.8",
+    "@agentskit/ink": "0.10.9",
     "@agentskit/react": "0.7.4",
     "@anthropic-ai/mcpb": "2.1.2",
-    "@changesets/cli": "^2.31.0",
+    "@changesets/cli": "^3.0.1",
     "@lhci/cli": "^0.15.1",
-    "@playwright/test": "1.61.1",
-    "@tailwindcss/postcss": "4.3.2",
-    "@types/node": "^22.15.3",
-    "@types/react": "19.2.17",
-    "@types/react-dom": "19.2.3",
-    "@vitest/coverage-v8": "4.1.10",
-    "esbuild": "^0.28.1",
-    "fumadocs-core": "15.6.5",
-    "fumadocs-mdx": "11.6.4",
-    "fumadocs-ui": "15.6.5",
-    "lucide-react": "0.460.0",
-    "next": "15.5.21",
-    "react": "19.2.0",
-    "react-dom": "19.2.0",
-    "tailwindcss": "4.3.2",
+    "@playwright/test": "1.62.1",
+    "@tailwindcss/postcss": "4.3.3",
+    "@types/node": "^26.4.0",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.5",
+    "@vitest/coverage-v8": "4.1.11",
+    "esbuild": "^0.28.2",
+    "fumadocs-core": "16.15.4",
+    "fumadocs-mdx": "15.4.0",
+    "fumadocs-ui": "16.15.4",
+    "lucide-react": "1.34.0",
+    "next": "16.3.3",
+    "proxy-agent": "8.0.2",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "tailwindcss": "4.3.3",
     "tsup": "^8.5.0",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.11"
   },
   "directories": {
     "doc": "docs",
@@ -188,5 +144,47 @@
   "bugs": {
     "url": "https://github.com/AgentsKit-io/doc-bridge/issues"
   },
-  "homepage": "https://doc-bridge.agentskit.io/"
-}
+  "homepage": "https://doc-bridge.agentskit.io/",
+  "scripts": {
+    "prebuild": "node scripts/sync-version.mjs",
+    "build": "tsup",
+    "test": "vitest run && pnpm test:cursor-plugin && pnpm test:claude-plugin && pnpm test:copilot-plugin && pnpm test:portable-skill",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "check:ecosystem-upstream": "node scripts/check-ecosystem-upstream.mjs",
+    "check:no-legacy-chat-imports": "node scripts/check-no-legacy-chat-imports.mjs",
+    "typecheck": "tsc --noEmit",
+    "smoke:packaged": "node scripts/smoke-packaged.mjs",
+    "smoke:docsites": "node scripts/smoke-docsites.mjs",
+    "smoke:real-docsites": "node scripts/smoke-real-docsites.mjs",
+    "smoke:ollama": "node scripts/smoke-ollama.mjs",
+    "mcpb:stage": "npm run build && node scripts/build-mcpb.mjs stage",
+    "mcpb:validate": "node scripts/build-mcpb.mjs validate",
+    "mcpb:smoke": "node scripts/smoke-mcpb.mjs",
+    "mcpb:pack": "npm run mcpb:stage && npm run mcpb:smoke && node scripts/build-mcpb.mjs pack",
+    "test:mcpb": "node --test scripts/mcpb-contract.test.mjs",
+    "test:cursor-plugin": "node --test scripts/cursor-plugin-contract.test.mjs",
+    "test:claude-plugin": "node --test scripts/claude-plugin-contract.test.mjs",
+    "test:copilot-plugin": "node --test scripts/copilot-plugin-contract.test.mjs",
+    "test:portable-skill": "node --test scripts/portable-skill-contract.test.mjs",
+    "coverage:badge": "node scripts/update-coverage-badge.mjs",
+    "changeset": "changeset",
+    "version-packages": "changeset version && node scripts/sync-version.mjs",
+    "release": "npm run build && npm test && changeset publish",
+    "version": "node scripts/sync-version.mjs && git add package.json src/version.ts action.yml",
+    "docs:dev": "cd apps/docs && next dev",
+    "docs:artifacts": "node scripts/build-docs-artifacts.mjs",
+    "docs:build": "pnpm build && node bin/ak-docs.js index && pnpm docs:artifacts && cd apps/docs && next build",
+    "docs:typecheck": "cd apps/docs && fumadocs-mdx && tsc --noEmit",
+    "docs:e2e": "playwright test",
+    "report:visual": "node scripts/report-visual-check.mjs",
+    "test:verification-harness": "node --test scripts/verification-harness.test.mjs",
+    "docs:lighthouse": "lhci autorun",
+    "test:readme-standard": "node --test scripts/readme-standard.test.mjs",
+    "test:marketplace": "node --test scripts/marketplace-contract.test.mjs",
+    "check:marketplace": "node scripts/check-marketplace-contract.mjs",
+    "test:docs-artifacts": "node --test scripts/docs-artifacts-contract.test.mjs",
+    "check:readme-standard": "node scripts/check-readme-standard.mjs",
+    "check:docs": "pnpm check:readme-standard && node bin/ak-docs.js gate run && node bin/ak-docs.js conformance run documentation-standard-v1 --text && pnpm docs:typecheck && pnpm docs:build && pnpm test:docs-artifacts"
+  }
+}

package/scripts/check-ecosystem-upstream.mjs

@@ -41,8 +41,9 @@ for (const file of requiredFiles) {
   if (localDigest !== expectedDigest) {
     throw new Error(`${file} differs from its recorded upstream SHA-256 digest.`)
   }
-  const url = `https://raw.githubusercontent.com/${metadata.repository}/${metadata.ref}/${file}`
-  const upstream = await fetchText(url)
+  const url = new URL(`https://raw.githubusercontent.com/${metadata.repository}/${metadata.ref}/${file}`)
+  if (url.hostname !== 'raw.githubusercontent.com') throw new Error('Unexpected upstream host.')
+  const upstream = await fetchText(url.href)
   if (sha256(upstream) !== expectedDigest || upstream !== local) {
     throw new Error(`${file} is stale against ${metadata.repository}@${metadata.ref}. Sync the canonical snapshot and digest.`)
   }

package/scripts/report-visual-check.mjs

@@ -1,5 +1,6 @@
-import { mkdirSync, writeFileSync } from 'node:fs'
-import { join, resolve } from 'node:path'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { join, relative, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
 
 import { chromium } from '@playwright/test'
@@ -15,6 +16,7 @@ const themes = ['light', 'dark']
 const failures = []
 const checks = []
 const networkRequests = []
+const clock = () => performance.now()
 
 mkdirSync(outputDir, { recursive: true })
 
@@ -92,6 +94,12 @@ const inspect = async (frame, width, height) => frame.evaluate(({ width: viewpor
     diagnosticCount: typeof globalThis.__DOC_BRIDGE_DATA__?.diagnosticCount === 'number'
       ? globalThis.__DOC_BRIDGE_DATA__.diagnosticCount
       : Number.parseInt(document.querySelector('#finding-count')?.textContent ?? '', 10) || document.querySelectorAll('.finding').length,
+    actionableCount: typeof globalThis.__DOC_BRIDGE_DATA__?.actionableCount === 'number'
+      ? globalThis.__DOC_BRIDGE_DATA__.actionableCount
+      : Number.parseInt((document.querySelector('#finding-count')?.textContent ?? '').match(/(\d+) actionable findings/)?.[1] ?? '0', 10),
+    confirmedCount: typeof globalThis.__DOC_BRIDGE_DATA__?.confirmedCount === 'number'
+      ? globalThis.__DOC_BRIDGE_DATA__.confirmedCount
+      : Number.parseInt((document.querySelector('#finding-count')?.textContent ?? '').match(/(\d+) confirmed checks/)?.[1] ?? '0', 10),
     unnamedButtonCount: unnamedButtons.length,
     visibleOverflowCount: visibleOverflow.length,
     contrastFailures,
@@ -99,25 +107,46 @@ const inspect = async (frame, width, height) => frame.evaluate(({ width: viewpor
 }, { width, height })
 
 const poll = async (read, predicate, label, timeoutMs = interactionTimeoutMs) => {
-  const started = Date.now()
-  while (Date.now() - started < timeoutMs) {
-    if (predicate(await read())) return Date.now() - started
+  const started = clock()
+  while (clock() - started < timeoutMs) {
+    if (predicate(await read())) return Math.round(clock() - started)
     await new Promise((resolve) => setTimeout(resolve, 50))
   }
   throw new Error(`${label} did not reach the expected state within ${timeoutMs}ms`)
 }
 
 const exercise = async (frame, result) => {
-  const run = async (label, action, verify) => {
-    const started = Date.now()
+  result.interactionDurationsMs ??= []
+  const run = async (label, action, verify, browserEvent) => {
+    const started = clock()
     try {
+      if (browserEvent) await frame.evaluate((type) => {
+        document.documentElement.dataset.docBridgeInteractionStartedAt = ''
+        window.addEventListener(type, () => {
+          document.documentElement.dataset.docBridgeInteractionStartedAt = String(performance.now())
+        }, { capture: true, once: true })
+      }, browserEvent)
       await Promise.race([
         (async () => { await action(); if (verify) await verify() })(),
         new Promise((_, reject) => setTimeout(() => reject(new Error('interaction timeout')), interactionTimeoutMs)),
       ])
-      const durationMs = Date.now() - started
+      const gestureDurationMs = Math.round(clock() - started)
+      const durationMs = browserEvent
+        ? await frame.evaluate(() => {
+          const startedAt = Number(document.documentElement.dataset.docBridgeInteractionStartedAt)
+          return Number.isFinite(startedAt) ? Math.round(performance.now() - startedAt) : null
+        })
+        : gestureDurationMs
+      if (durationMs == null) throw new Error(`${browserEvent} event was not observed`)
+      result.interactionDurationsMs.push({ label, durationMs, ...(browserEvent ? { gestureDurationMs } : {}) })
+      if (browserEvent) {
+        const renderTimings = await frame.evaluate(() => JSON.parse(document.documentElement.dataset.docBridgeRenderTimings || '{}'))
+        result.renderTimings ??= []
+        result.renderTimings.push({ label, ...renderTimings })
+      }
       if (durationMs > 2000) result.failures.push(`${label} took ${durationMs}ms`)
     } catch (error) {
+      result.interactionDurationsMs.push({ label, durationMs: Math.round(clock() - started), failed: true })
       result.failures.push(`${label}: ${error instanceof Error ? error.message : String(error)}`)
     }
   }
@@ -134,7 +163,8 @@ const exercise = async (frame, result) => {
     if (await load.count()) await load.click()
     else if (result.diagnosticCount > 0 && await frame.locator('.finding-group').count() === 0) throw new Error('finding loader is missing while findings are present')
   }, async () => {
-    if (result.diagnosticCount > 0) {
+    const evidenceView = await frame.locator('body').getAttribute('data-report-view') === 'coverage'
+    if (result.actionableCount > 0 || (evidenceView && result.confirmedCount > 0)) {
       await poll(() => frame.locator('.finding-group').count(), (count) => count > 0, 'finding groups')
     } else if (await frame.locator('.finding-group').count() !== 0) {
       throw new Error('finding groups rendered despite zero findings')
@@ -165,7 +195,7 @@ const exercise = async (frame, result) => {
         await poll(() => frame.locator('[data-level][aria-pressed="true"]').getAttribute('data-level'), (actual) => actual === expectedLevel, `drill-down ${expectedLevel}`)
         const details = await frame.locator('#details').innerText()
         if (/Select a node in the map/i.test(details)) throw new Error('details panel did not update')
-      })
+      }, 'dblclick')
     }
     if (await frame.locator('#breadcrumbs [data-breadcrumb-level]').count() < 1) result.failures.push('drill-down did not create usable breadcrumbs')
     await run('breadcrumb back to repository', () => frame.locator('#breadcrumbs [data-breadcrumb-level="overview"]').click(), async () => {
@@ -189,6 +219,9 @@ const exercise = async (frame, result) => {
 let browser
 try {
   browser = await chromium.launch()
+  const warmup = await browser.newPage()
+  await warmup.goto('about:blank')
+  await warmup.close()
   for (const theme of themes) {
     for (const viewport of viewports) {
       const page = await browser.newPage()
@@ -203,10 +236,12 @@ try {
       try {
         await page.setViewportSize({ width: viewport[0], height: viewport[1] })
         await page.emulateMedia({ colorScheme: theme })
+        const renderStarted = clock()
         await page.goto(pathToFileURL(reportPath).href, { waitUntil: 'load' })
         const frame = page.frames().find((candidate) => candidate !== page.mainFrame() && candidate.url().endsWith('/report/index.html')) ?? page.mainFrame()
         await frame.locator('#graph').waitFor({ state: 'visible', timeout: interactionTimeoutMs })
         result = await inspect(frame, viewport[0], viewport[1])
+        result.firstRenderMs = Math.round(clock() - renderStarted)
         await exercise(frame, result)
         result.pageErrors = pageErrors
         result.consoleErrors = consoleErrors
@@ -229,8 +264,15 @@ try {
 }
 
 const status = failures.length || checks.some((check) => check.failures.length) ? 'failed' : humanApproved ? 'passed' : 'pending-human-review'
+const artifacts = checks.map((check) => {
+  const path = join(outputDir, `${check.viewport}-${check.theme}.png`)
+  return existsSync(path) ? { type: 'screenshot', path: relative(process.cwd(), path), sha256: createHash('sha256').update(readFileSync(path)).digest('hex'), viewport: check.viewport, theme: check.theme } : null
+}).filter(Boolean)
 const result = {
   status,
+  capability: 'real-browser',
+  artifacts,
+  criteria: { 'report-ui': { status: status === 'failed' ? 'failed' : 'passed' } },
   reportPath,
   outputDir,
   viewports,
@@ -245,6 +287,16 @@ const result = {
       : 'Automated checks passed; screenshots require human visual review. Re-run with --human-approved only after review.',
 }
 writeFileSync(join(outputDir, 'result.json'), `${JSON.stringify(result, null, 2)}\n`, 'utf8')
-console.log(JSON.stringify(result, null, 2))
-console.log(JSON.stringify({ status }))
+console.log(JSON.stringify({
+  status,
+  capability: result.capability,
+  artifacts: result.artifacts,
+  criteria: result.criteria,
+  reportPath: result.reportPath,
+  outputDir: result.outputDir,
+  viewports: result.viewports,
+  themes: result.themes,
+  failures: result.failures,
+  note: result.note,
+}))
 if (status === 'failed') process.exitCode = 1