npm - vocs - Versions diffs - 2.0.17 → 2.1.2 - Mend

vocs 2.0.17 → 2.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (306) hide show

package/dist/config.d.ts +1 -0
package/dist/config.d.ts.map +1 -1
package/dist/config.js +1 -0
package/dist/config.js.map +1 -1
package/dist/globals.d.ts +16 -0
package/dist/index.d.ts +1 -0
package/dist/index.d.ts.map +1 -1
package/dist/index.js +1 -0
package/dist/index.js.map +1 -1
package/dist/internal/config.d.ts +28 -0
package/dist/internal/config.d.ts.map +1 -1
package/dist/internal/config.js +10 -2
package/dist/internal/config.js.map +1 -1
package/dist/internal/llms.d.ts +21 -2
package/dist/internal/llms.d.ts.map +1 -1
package/dist/internal/llms.js +41 -1
package/dist/internal/llms.js.map +1 -1
package/dist/internal/markdown-negotiation.d.ts +36 -0
package/dist/internal/markdown-negotiation.d.ts.map +1 -0
package/dist/internal/markdown-negotiation.js +81 -0
package/dist/internal/markdown-negotiation.js.map +1 -0
package/dist/internal/markdown.d.ts.map +1 -1
package/dist/internal/markdown.js +5 -0
package/dist/internal/markdown.js.map +1 -1
package/dist/internal/openapi/anchors.d.ts +25 -0
package/dist/internal/openapi/anchors.d.ts.map +1 -0
package/dist/internal/openapi/anchors.js +37 -0
package/dist/internal/openapi/anchors.js.map +1 -0
package/dist/internal/openapi/app.d.ts +89 -0
package/dist/internal/openapi/app.d.ts.map +1 -0
package/dist/internal/openapi/app.js +62 -0
package/dist/internal/openapi/app.js.map +1 -0
package/dist/internal/openapi/index.d.ts +8 -0
package/dist/internal/openapi/index.d.ts.map +1 -0
package/dist/internal/openapi/index.js +5 -0
package/dist/internal/openapi/index.js.map +1 -0
package/dist/internal/openapi/markdown.d.ts +42 -0
package/dist/internal/openapi/markdown.d.ts.map +1 -0
package/dist/internal/openapi/markdown.js +235 -0
package/dist/internal/openapi/markdown.js.map +1 -0
package/dist/internal/openapi/openapi.d.ts +187 -0
package/dist/internal/openapi/openapi.d.ts.map +1 -0
package/dist/internal/openapi/openapi.js +44 -0
package/dist/internal/openapi/openapi.js.map +1 -0
package/dist/internal/openapi/openrpc.d.ts +90 -0
package/dist/internal/openapi/openrpc.d.ts.map +1 -0
package/dist/internal/openapi/openrpc.js +213 -0
package/dist/internal/openapi/openrpc.js.map +1 -0
package/dist/internal/openapi/parser.d.ts +181 -0
package/dist/internal/openapi/parser.d.ts.map +1 -0
package/dist/internal/openapi/parser.js +329 -0
package/dist/internal/openapi/parser.js.map +1 -0
package/dist/internal/openapi/registry.d.ts +36 -0
package/dist/internal/openapi/registry.d.ts.map +1 -0
package/dist/internal/openapi/registry.js +79 -0
package/dist/internal/openapi/registry.js.map +1 -0
package/dist/internal/openapi/sample.d.ts +115 -0
package/dist/internal/openapi/sample.d.ts.map +1 -0
package/dist/internal/openapi/sample.js +434 -0
package/dist/internal/openapi/sample.js.map +1 -0
package/dist/internal/openapi/search.d.ts +19 -0
package/dist/internal/openapi/search.d.ts.map +1 -0
package/dist/internal/openapi/search.js +98 -0
package/dist/internal/openapi/search.js.map +1 -0
package/dist/internal/openapi/sidebar.d.ts +30 -0
package/dist/internal/openapi/sidebar.d.ts.map +1 -0
package/dist/internal/openapi/sidebar.js +67 -0
package/dist/internal/openapi/sidebar.js.map +1 -0
package/dist/internal/openapi/union.d.ts +36 -0
package/dist/internal/openapi/union.d.ts.map +1 -0
package/dist/internal/openapi/union.js +69 -0
package/dist/internal/openapi/union.js.map +1 -0
package/dist/internal/search.d.ts.map +1 -1
package/dist/internal/search.js +20 -0
package/dist/internal/search.js.map +1 -1
package/dist/internal/vite-plugins.d.ts +12 -0
package/dist/internal/vite-plugins.d.ts.map +1 -1
package/dist/internal/vite-plugins.js +102 -11
package/dist/internal/vite-plugins.js.map +1 -1
package/dist/react/Badge.d.ts +2 -3
package/dist/react/Badge.d.ts.map +1 -1
package/dist/react/Layout.client.d.ts.map +1 -1
package/dist/react/Layout.client.js +2 -2
package/dist/react/Layout.client.js.map +1 -1
package/dist/react/OpenApi.d.ts +6 -0
package/dist/react/OpenApi.d.ts.map +1 -0
package/dist/react/OpenApi.js +6 -0
package/dist/react/OpenApi.js.map +1 -0
package/dist/react/internal/CodeToHtml.client.d.ts +53 -2
package/dist/react/internal/CodeToHtml.client.d.ts.map +1 -1
package/dist/react/internal/CodeToHtml.client.js +154 -21
package/dist/react/internal/CodeToHtml.client.js.map +1 -1
package/dist/react/internal/Sidebar.d.ts.map +1 -1
package/dist/react/internal/Sidebar.js +99 -2
package/dist/react/internal/Sidebar.js.map +1 -1
package/dist/react/internal/openapi/CodeSample.client.d.ts +21 -0
package/dist/react/internal/openapi/CodeSample.client.d.ts.map +1 -0
package/dist/react/internal/openapi/CodeSample.client.js +134 -0
package/dist/react/internal/openapi/CodeSample.client.js.map +1 -0
package/dist/react/internal/openapi/CollapsibleChildren.client.d.ts +17 -0
package/dist/react/internal/openapi/CollapsibleChildren.client.d.ts.map +1 -0
package/dist/react/internal/openapi/CollapsibleChildren.client.js +18 -0
package/dist/react/internal/openapi/CollapsibleChildren.client.js.map +1 -0
package/dist/react/internal/openapi/Disclosure.client.d.ts +28 -0
package/dist/react/internal/openapi/Disclosure.client.d.ts.map +1 -0
package/dist/react/internal/openapi/Disclosure.client.js +38 -0
package/dist/react/internal/openapi/Disclosure.client.js.map +1 -0
package/dist/react/internal/openapi/Endpoints.d.ts +26 -0
package/dist/react/internal/openapi/Endpoints.d.ts.map +1 -0
package/dist/react/internal/openapi/Endpoints.js +33 -0
package/dist/react/internal/openapi/Endpoints.js.map +1 -0
package/dist/react/internal/openapi/EndpointsView.d.ts +24 -0
package/dist/react/internal/openapi/EndpointsView.d.ts.map +1 -0
package/dist/react/internal/openapi/EndpointsView.js +26 -0
package/dist/react/internal/openapi/EndpointsView.js.map +1 -0
package/dist/react/internal/openapi/EnumValues.client.d.ts +14 -0
package/dist/react/internal/openapi/EnumValues.client.d.ts.map +1 -0
package/dist/react/internal/openapi/EnumValues.client.js +20 -0
package/dist/react/internal/openapi/EnumValues.client.js.map +1 -0
package/dist/react/internal/openapi/HeadingAnchor.d.ts +15 -0
package/dist/react/internal/openapi/HeadingAnchor.d.ts.map +1 -0
package/dist/react/internal/openapi/HeadingAnchor.js +12 -0
package/dist/react/internal/openapi/HeadingAnchor.js.map +1 -0
package/dist/react/internal/openapi/OpenApiPage.d.ts +79 -0
package/dist/react/internal/openapi/OpenApiPage.d.ts.map +1 -0
package/dist/react/internal/openapi/OpenApiPage.js +72 -0
package/dist/react/internal/openapi/OpenApiPage.js.map +1 -0
package/dist/react/internal/openapi/Operation.d.ts +25 -0
package/dist/react/internal/openapi/Operation.d.ts.map +1 -0
package/dist/react/internal/openapi/Operation.js +101 -0
package/dist/react/internal/openapi/Operation.js.map +1 -0
package/dist/react/internal/openapi/Playground.client.d.ts +33 -0
package/dist/react/internal/openapi/Playground.client.d.ts.map +1 -0
package/dist/react/internal/openapi/Playground.client.js +170 -0
package/dist/react/internal/openapi/Playground.client.js.map +1 -0
package/dist/react/internal/openapi/PropertyExample.client.d.ts +17 -0
package/dist/react/internal/openapi/PropertyExample.client.d.ts.map +1 -0
package/dist/react/internal/openapi/PropertyExample.client.js +21 -0
package/dist/react/internal/openapi/PropertyExample.client.js.map +1 -0
package/dist/react/internal/openapi/Reference.d.ts +55 -0
package/dist/react/internal/openapi/Reference.d.ts.map +1 -0
package/dist/react/internal/openapi/Reference.js +42 -0
package/dist/react/internal/openapi/Reference.js.map +1 -0
package/dist/react/internal/openapi/Schema.d.ts +110 -0
package/dist/react/internal/openapi/Schema.d.ts.map +1 -0
package/dist/react/internal/openapi/Schema.js +239 -0
package/dist/react/internal/openapi/Schema.js.map +1 -0
package/dist/react/internal/openapi/SchemaUnion.client.d.ts +25 -0
package/dist/react/internal/openapi/SchemaUnion.client.d.ts.map +1 -0
package/dist/react/internal/openapi/SchemaUnion.client.js +48 -0
package/dist/react/internal/openapi/SchemaUnion.client.js.map +1 -0
package/dist/react/internal/openapi/anchor-navigation.client.d.ts +47 -0
package/dist/react/internal/openapi/anchor-navigation.client.d.ts.map +1 -0
package/dist/react/internal/openapi/anchor-navigation.client.js +120 -0
package/dist/react/internal/openapi/anchor-navigation.client.js.map +1 -0
package/dist/react/internal/openapi/auth.d.ts +28 -0
package/dist/react/internal/openapi/auth.d.ts.map +1 -0
package/dist/react/internal/openapi/auth.js +75 -0
package/dist/react/internal/openapi/auth.js.map +1 -0
package/dist/react/useLayout.d.ts +2 -0
package/dist/react/useLayout.d.ts.map +1 -1
package/dist/react/useLayout.js +2 -0
package/dist/react/useLayout.js.map +1 -1
package/dist/server/handlers.d.ts +1 -1
package/dist/server/handlers.d.ts.map +1 -1
package/dist/server/handlers.js +26 -5
package/dist/server/handlers.js.map +1 -1
package/dist/server/og-assets.d.ts +5 -0
package/dist/server/og-assets.d.ts.map +1 -0
package/dist/server/og-assets.js +11 -0
package/dist/server/og-assets.js.map +1 -0
package/dist/server/openapi/assets.d.ts +33 -0
package/dist/server/openapi/assets.d.ts.map +1 -0
package/dist/server/openapi/assets.generated.d.ts +9 -0
package/dist/server/openapi/assets.generated.d.ts.map +1 -0
package/dist/server/openapi/assets.generated.js +1091 -0
package/dist/server/openapi/assets.generated.js.map +1 -0
package/dist/server/openapi/assets.js +32 -0
package/dist/server/openapi/assets.js.map +1 -0
package/dist/server/openapi/handler.d.ts +103 -0
package/dist/server/openapi/handler.d.ts.map +1 -0
package/dist/server/openapi/handler.js +198 -0
package/dist/server/openapi/handler.js.map +1 -0
package/dist/server/openapi/handler.test.d.ts +2 -0
package/dist/server/openapi/handler.test.d.ts.map +1 -0
package/dist/server/openapi/handler.test.js +203 -0
package/dist/server/openapi/handler.test.js.map +1 -0
package/dist/server/openapi/html.d.ts +16 -0
package/dist/server/openapi/html.d.ts.map +1 -0
package/dist/server/openapi/html.js +75 -0
package/dist/server/openapi/html.js.map +1 -0
package/dist/server/openapi/pages.d.ts +33 -0
package/dist/server/openapi/pages.d.ts.map +1 -0
package/dist/server/openapi/pages.js +130 -0
package/dist/server/openapi/pages.js.map +1 -0
package/dist/server/openapi/pages.test.d.ts +2 -0
package/dist/server/openapi/pages.test.d.ts.map +1 -0
package/dist/server/openapi/pages.test.js +94 -0
package/dist/server/openapi/pages.test.js.map +1 -0
package/dist/server/openapi/state.d.ts +42 -0
package/dist/server/openapi/state.d.ts.map +1 -0
package/dist/server/openapi/state.js +101 -0
package/dist/server/openapi/state.js.map +1 -0
package/dist/styles/index.css +16 -0
package/dist/styles/markdown.css +9 -7
package/dist/styles/openapi-playground.css +80 -0
package/dist/styles/openapi.css +660 -0
package/dist/vite.d.ts.map +1 -1
package/dist/vite.js +1 -0
package/dist/vite.js.map +1 -1
package/dist/waku/internal/middleware/md-router.d.ts +0 -4
package/dist/waku/internal/middleware/md-router.d.ts.map +1 -1
package/dist/waku/internal/middleware/md-router.js +3 -48
package/dist/waku/internal/middleware/md-router.js.map +1 -1
package/dist/waku/internal/patches/adapters/vercel-build-enhancer.js +1 -1
package/dist/waku/internal/patches/adapters/vercel-build-enhancer.js.map +1 -1
package/dist/waku/internal/patches/router.d.ts.map +1 -1
package/dist/waku/internal/patches/router.js +114 -1
package/dist/waku/internal/patches/router.js.map +1 -1
package/package.json +5 -1
package/src/config.ts +1 -0
package/src/globals.d.ts +16 -0
package/src/index.ts +1 -0
package/src/internal/config.ts +40 -1
package/src/internal/llms.ts +51 -1
package/src/internal/markdown-negotiation.test.ts +42 -0
package/src/internal/markdown-negotiation.ts +95 -0
package/src/internal/markdown.ts +5 -0
package/src/internal/openapi/anchors.ts +44 -0
package/src/internal/openapi/app.ts +127 -0
package/src/internal/openapi/index.ts +24 -0
package/src/internal/openapi/markdown.test.ts +115 -0
package/src/internal/openapi/markdown.ts +275 -0
package/src/internal/openapi/openapi.ts +212 -0
package/src/internal/openapi/openrpc.test.ts +239 -0
package/src/internal/openapi/openrpc.ts +295 -0
package/src/internal/openapi/parser.test.ts +203 -0
package/src/internal/openapi/parser.ts +613 -0
package/src/internal/openapi/registry.test.ts +89 -0
package/src/internal/openapi/registry.ts +89 -0
package/src/internal/openapi/sample.test.ts +283 -0
package/src/internal/openapi/sample.ts +562 -0
package/src/internal/openapi/search.test.ts +62 -0
package/src/internal/openapi/search.ts +108 -0
package/src/internal/openapi/sidebar.test.ts +131 -0
package/src/internal/openapi/sidebar.ts +94 -0
package/src/internal/openapi/union.test.ts +51 -0
package/src/internal/openapi/union.ts +74 -0
package/src/internal/search.ts +20 -0
package/src/internal/test/virtual-config.stub.ts +14 -0
package/src/internal/vite-plugins.ts +106 -11
package/src/openapi-app/App.tsx +64 -0
package/src/openapi-app/blocks.tsx +33 -0
package/src/openapi-app/client.tsx +25 -0
package/src/openapi-app/links.test.ts +84 -0
package/src/openapi-app/links.ts +66 -0
package/src/openapi-app/payload.ts +20 -0
package/src/openapi-app/virtual/config.ts +7 -0
package/src/openapi-app/virtual/group-icons.ts +2 -0
package/src/openapi-app/virtual/langs.ts +6 -0
package/src/openapi-app/virtual/openapi.ts +10 -0
package/src/openapi-app/virtual/search-index.ts +21 -0
package/src/openapi-app/virtual/slots.ts +4 -0
package/src/openapi-app/virtual/user-styles.ts +2 -0
package/src/openapi-app/waku.tsx +154 -0
package/src/react/Badge.tsx +2 -3
package/src/react/Layout.client.tsx +17 -4
package/src/react/OpenApi.tsx +5 -0
package/src/react/internal/CodeToHtml.client.tsx +283 -22
package/src/react/internal/Sidebar.tsx +126 -22
package/src/react/internal/openapi/CodeSample.client.tsx +294 -0
package/src/react/internal/openapi/CollapsibleChildren.client.tsx +41 -0
package/src/react/internal/openapi/Disclosure.client.tsx +67 -0
package/src/react/internal/openapi/Endpoints.tsx +58 -0
package/src/react/internal/openapi/EndpointsView.tsx +76 -0
package/src/react/internal/openapi/EnumValues.client.tsx +49 -0
package/src/react/internal/openapi/HeadingAnchor.tsx +28 -0
package/src/react/internal/openapi/OpenApiPage.tsx +173 -0
package/src/react/internal/openapi/Operation.test.tsx +101 -0
package/src/react/internal/openapi/Operation.tsx +335 -0
package/src/react/internal/openapi/Playground.client.tsx +234 -0
package/src/react/internal/openapi/PropertyExample.client.tsx +55 -0
package/src/react/internal/openapi/Reference.tsx +120 -0
package/src/react/internal/openapi/Schema.tsx +467 -0
package/src/react/internal/openapi/SchemaUnion.client.tsx +123 -0
package/src/react/internal/openapi/anchor-navigation.client.ts +154 -0
package/src/react/internal/openapi/auth.ts +69 -0
package/src/react/useLayout.ts +4 -0
package/src/server/handlers.ts +31 -6
package/src/server/og-assets.ts +14 -0
package/src/server/openapi/assets.generated.ts +1093 -0
package/src/server/openapi/assets.ts +57 -0
package/src/server/openapi/handler.test.ts +244 -0
package/src/server/openapi/handler.ts +277 -0
package/src/server/openapi/html.ts +84 -0
package/src/server/openapi/pages.test.ts +111 -0
package/src/server/openapi/pages.ts +153 -0
package/src/server/openapi/state.ts +136 -0
package/src/styles/index.css +16 -0
package/src/styles/markdown.css +9 -7
package/src/styles/openapi-playground.css +80 -0
package/src/styles/openapi.css +660 -0
package/src/vite.ts +1 -0
package/src/waku/internal/middleware/md-router.ts +8 -52
package/src/waku/internal/patches/adapters/vercel-build-enhancer.ts +1 -1
package/src/waku/internal/patches/router.ts +131 -1

package/src/server/openapi/assets.ts ADDED Viewed

@@ -0,0 +1,57 @@
+import { assets } from './assets.generated.js'
+/** A single emitted asset (JS chunk, CSS file, font, …). */
+export type AssetFile = {
+  /** MIME type, e.g. `text/javascript; charset=utf-8`. */
+  type: string
+  /** `utf8` for text assets, `base64` for binary (fonts/wasm). */
+  encoding: 'utf8' | 'base64'
+  /** File contents (string for `utf8`, base64 string for `base64`). */
+  body: string
+}
+/** The prebuilt standalone bundle manifest. */
+export type Assets = {
+  /** Whether the bundle was built (`false` for the committed stub). */
+  built: boolean
+  /** Entry JS file name (relative to the asset root), e.g. `client.js`. */
+  entry: string
+  /** CSS file names to inject into the shell `<head>`. */
+  styles: string[]
+  /** All emitted files, keyed by name relative to the asset root. */
+  files: Record<string, AssetFile>
+}
+/** URL path segment under which standalone assets are served. */
+export const assetRoot = '/_vocs/openapi/'
+/** Returns the prebuilt bundle manifest. */
+export function manifest(): Assets {
+  return assets
+}
+/**
+ * Resolves a request pathname to a bundled asset, matching by the
+ * {@link assetRoot} marker so assets resolve regardless of the Hono mount path
+ * (e.g. `/docs/_vocs/openapi/client.js` → `client.js`).
+ */
+export function match(pathname: string): AssetFile | undefined {
+  const index = pathname.lastIndexOf(assetRoot)
+  if (index === -1) return undefined
+  const name = pathname.slice(index + assetRoot.length)
+  return assets.files[name]
+}
+/** Builds a `Response` for a bundled asset with long-lived caching. */
+export function response(asset: AssetFile): Response {
+  const body =
+    asset.encoding === 'base64'
+      ? Uint8Array.from(atob(asset.body), (c) => c.charCodeAt(0))
+      : asset.body
+  return new Response(body, {
+    headers: {
+      'content-type': asset.type,
+      'cache-control': 'public, max-age=31536000, immutable',
+    },
+  })
+}

package/src/server/openapi/handler.test.ts ADDED Viewed

@@ -0,0 +1,244 @@
+import * as fs from 'node:fs/promises'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import { Hono } from 'hono'
+import { describe, expect, test } from 'vitest'
+import { openApi } from './handler.js'
+const spec = {
+  openapi: '3.1.0',
+  info: { title: 'Demo API', version: '1.0.0', description: 'A demo.' },
+  servers: [{ url: 'https://api.example.com' }],
+  tags: [{ name: 'Pets', description: 'Pet operations' }],
+  paths: {
+    '/pets': {
+      get: {
+        operationId: 'listPets',
+        summary: 'List pets',
+        tags: ['Pets'],
+        responses: { '200': { description: 'OK' } },
+      },
+    },
+  },
+}
+describe('Handler.openApi', () => {
+  test('serves the HTML shell with embedded payload', async () => {
+    const ref = openApi({ spec })
+    const response = await ref.fetch(new Request('http://localhost/'))
+    expect(response.status).toBe(200)
+    expect(response.headers.get('content-type')).toContain('text/html')
+    const html = await response.text()
+    expect(html).toContain('id="vocs-openapi-data"')
+    expect(html).toContain('Demo API')
+    // Asset references are absolute, prefixed by the inferred mount (root here).
+    expect(html).toContain('/_vocs/openapi/')
+    // Embedded payload includes the parsed group.
+    expect(html).toContain('"Pets"')
+    expect(html).toContain('listPets')
+  })
+  test('serves the prebuilt client bundle', async () => {
+    const ref = openApi({ spec })
+    const response = await ref.fetch(new Request('http://localhost/_vocs/openapi/client.js'))
+    expect(response.status).toBe(200)
+    expect(response.headers.get('content-type')).toContain('javascript')
+    expect(response.headers.get('cache-control')).toContain('immutable')
+    const body = await response.text()
+    expect(body.length).toBeGreaterThan(0)
+  })
+  test('serves assets regardless of mount prefix', async () => {
+    const ref = openApi({ spec })
+    const response = await ref.fetch(new Request('http://localhost/docs/_vocs/openapi/client.js'))
+    expect(response.status).toBe(200)
+    expect(response.headers.get('content-type')).toContain('javascript')
+  })
+  test('exposes a Node request listener', () => {
+    const ref = openApi({ spec })
+    expect(typeof ref.listener).toBe('function')
+  })
+  test('accepts an already-started spec promise', async () => {
+    const ref = openApi({ spec: Promise.resolve(spec) })
+    const response = await ref.fetch(new Request('http://localhost/'))
+    expect(response.status).toBe(200)
+    expect(await response.text()).toContain('listPets')
+  })
+  describe('custom css', () => {
+    test('injects an inline CSS string into the shell head, after the bundle styles', async () => {
+      const ref = openApi({ spec }, { css: ':root { --vocs-color-accent: #7c3aed }' })
+      const html = await (await ref.fetch(new Request('http://localhost/'))).text()
+      expect(html).toContain('<style>:root { --vocs-color-accent: #7c3aed }</style>')
+      // Custom CSS comes after the design-system stylesheets so it wins.
+      expect(html.indexOf('rel="stylesheet"')).toBeLessThan(html.indexOf('<style>'))
+    })
+    test('omits the inline <style> when no css is configured', async () => {
+      const ref = openApi({ spec })
+      const html = await (await ref.fetch(new Request('http://localhost/'))).text()
+      expect(html).not.toContain('<style>')
+    })
+    test('reads css from a { file }', async () => {
+      const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'vocs-openapi-css-'))
+      await fs.writeFile(path.join(dir, 'theme.css'), '.body { color: red }')
+      const ref = openApi({ spec }, { css: { file: 'theme.css' }, rootDir: dir })
+      const html = await (await ref.fetch(new Request('http://localhost/'))).text()
+      expect(html).toContain('<style>.body { color: red }</style>')
+      await fs.rm(dir, { recursive: true, force: true })
+    })
+    test('neutralizes a closing </style> tag without corrupting CSS', async () => {
+      const ref = openApi(
+        { spec },
+        { css: 'a > b { color: red } /* </style><script>x</script> */' },
+      )
+      const html = await (await ref.fetch(new Request('http://localhost/'))).text()
+      // `>` combinators are preserved. The closing tags are escaped so they
+      // can't break out of the `<style>` block (the opening `<script>` is inert
+      // as CSS text once `</style>` can't terminate the block).
+      expect(html).toContain('a > b { color: red }')
+      expect(html).toContain('<\\/style>')
+      expect(html).toContain('<\\/script>')
+      expect(html).not.toContain('</style><script>')
+    })
+  })
+  describe("fallback: 'next'", () => {
+    test('renders the reference at the host root, falls through elsewhere', async () => {
+      const app = new Hono()
+      app.get('/v1/blocks', (c) => c.json({ who: 'api' }))
+      app.route('/', openApi({ spec }, { fallback: 'next' }))
+      app.notFound((c) => c.json({ error: 'not_found' }, 404))
+      // Reference landing page is owned by the handler.
+      const landing = await app.request('http://localhost/')
+      expect(landing.status).toBe(200)
+      expect(landing.headers.get('content-type')).toContain('text/html')
+      // Assets resolve back to the root mount.
+      expect(await landing.text()).toContain('/_vocs/openapi/')
+      // A known section route (the "Pets" group) renders the shell too.
+      const group = await app.request('http://localhost/pets')
+      expect(group.status).toBe(200)
+      expect(group.headers.get('content-type')).toContain('text/html')
+      // Bundled assets are served by the handler.
+      const asset = await app.request('http://localhost/_vocs/openapi/client.js')
+      expect(asset.status).toBe(200)
+      expect(asset.headers.get('content-type')).toContain('javascript')
+      // The host API route wins.
+      const api = await app.request('http://localhost/v1/blocks')
+      expect(api.status).toBe(200)
+      expect(await api.json()).toEqual({ who: 'api' })
+      // An unrelated path falls through to the host notFound (not the shell).
+      const missing = await app.request('http://localhost/v1/missing')
+      expect(missing.status).toBe(404)
+      expect(await missing.json()).toEqual({ error: 'not_found' })
+    })
+    test('derives the mount prefix from the host basePath', async () => {
+      const app = new Hono().basePath('/api')
+      app.route('/', openApi({ spec }, { fallback: 'next' }))
+      const landing = await app.request('http://localhost/api/')
+      expect(landing.status).toBe(200)
+      // Asset URLs are prefixed with the host basePath so they route back here.
+      expect(await landing.text()).toContain('/api/_vocs/openapi/')
+      const asset = await app.request('http://localhost/api/_vocs/openapi/client.js')
+      expect(asset.status).toBe(200)
+    })
+  })
+  describe('markdown', () => {
+    test('serves the generated overview at `<intro>.md`', async () => {
+      const ref = openApi({ spec, path: '/api' })
+      const response = await ref.fetch(new Request('http://localhost/api.md'))
+      expect(response.status).toBe(200)
+      expect(response.headers.get('content-type')).toContain('text/markdown')
+      const md = await response.text()
+      expect(md).toContain('# Demo API')
+      expect(md).toContain('## Endpoints')
+      expect(md).toContain('- [`GET /pets`](/api/pets#listpets): List pets')
+    })
+    test('serves a generated category at `<group>.md`', async () => {
+      const ref = openApi({ spec, path: '/api' })
+      const response = await ref.fetch(new Request('http://localhost/api/pets.md'))
+      expect(response.status).toBe(200)
+      expect(response.headers.get('content-type')).toContain('text/markdown')
+      const md = await response.text()
+      expect(md).toContain('## List pets')
+      expect(md).toContain('`GET /pets`')
+    })
+    test('honors `Accept: text/markdown` without a `.md` suffix', async () => {
+      const ref = openApi({ spec, path: '/api' })
+      const response = await ref.fetch(
+        new Request('http://localhost/api', { headers: { accept: 'text/markdown' } }),
+      )
+      expect(response.status).toBe(200)
+      expect(response.headers.get('content-type')).toContain('text/markdown')
+      expect(await response.text()).toContain('# Demo API')
+    })
+    test('serves an authored guide page as its own Markdown', async () => {
+      const ref = openApi({
+        spec,
+        path: '/api',
+        pages: [{ path: '/guide', content: '---\ntitle: Guide\n---\n# Guide\n\nHello there.' }],
+      })
+      const response = await ref.fetch(new Request('http://localhost/api/guide.md'))
+      expect(response.status).toBe(200)
+      expect(response.headers.get('content-type')).toContain('text/markdown')
+      const md = await response.text()
+      expect(md).toContain('# Guide')
+      expect(md).toContain('Hello there.')
+    })
+    test('serves Markdown to terminal clients (curl) without a `.md` suffix', async () => {
+      const ref = openApi({ spec, path: '/api' })
+      const response = await ref.fetch(
+        new Request('http://localhost/api', { headers: { 'user-agent': 'curl/8.4.0' } }),
+      )
+      expect(response.status).toBe(200)
+      expect(response.headers.get('content-type')).toContain('text/markdown')
+      expect(await response.text()).toContain('# Demo API')
+    })
+    test('serves Markdown to AI agents without a `.md` suffix', async () => {
+      const ref = openApi({ spec, path: '/api' })
+      const response = await ref.fetch(
+        new Request('http://localhost/api', { headers: { 'user-agent': 'ChatGPT-User/2.0' } }),
+      )
+      expect(response.status).toBe(200)
+      expect(response.headers.get('content-type')).toContain('text/markdown')
+    })
+    test('does not serve Markdown to search engines without a `.md` suffix', async () => {
+      const ref = openApi({ spec, path: '/api' })
+      const response = await ref.fetch(
+        new Request('http://localhost/api', { headers: { 'user-agent': 'Googlebot/2.1' } }),
+      )
+      expect(response.headers.get('content-type') ?? '').not.toContain('text/markdown')
+    })
+    test('prefixes overview links with the live host mount', async () => {
+      const app = new Hono().basePath('/docs')
+      app.route('/', openApi({ spec, path: '/api' }, { fallback: 'next' }))
+      const response = await app.request('http://localhost/docs/api.md')
+      expect(response.status).toBe(200)
+      expect(await response.text()).toContain('](/docs/api/pets#listpets)')
+    })
+  })
+})

package/src/server/openapi/handler.ts ADDED Viewed

@@ -0,0 +1,277 @@
+import { getRequestListener } from '@hono/node-server'
+import { Hono } from 'hono'
+import { prefersMarkdown } from '../../internal/markdown-negotiation.js'
+import type { Payload } from '../../internal/openapi/app.js'
+import { inferMount, join, knownRoutes } from '../../internal/openapi/app.js'
+import * as Markdown from '../../internal/openapi/markdown.js'
+import type * as OpenApi from '../../internal/openapi/openapi.js'
+import { normalizePath } from '../../internal/openapi/openapi.js'
+import * as Assets from './assets.js'
+import * as Html from './html.js'
+import * as State from './state.js'
+/**
+ * A standalone OpenAPI reference handler: a Hono app augmented with a Node
+ * request `listener` so it can be mounted onto a Hono server (`app.route(...)`),
+ * served via the Web-standard `fetch`, or run with `node:http`.
+ */
+export type Handler<app extends Hono = Hono> = app & {
+  /** Node.js `(req, res)` request listener (for `http.createServer`). */
+  listener: ReturnType<typeof getRequestListener>
+}
+/**
+ * Creates a standalone, mountable OpenAPI reference (Scalar-style, rendered
+ * entirely client-side by a prebuilt browser bundle shipped inside Vocs).
+ *
+ * Accepts the same config as a `vocs.config.ts` `openapi[]` entry, except `path`
+ * is optional (the mount location is provided by the host server; `path` only
+ * seeds generated link bases). Supply `pages` to add `.md`/`.mdx` override/guide
+ * content to the sidebar.
+ *
+ * @example
+ * ```ts
+ * import { Hono } from 'hono'
+ * import { Handler } from 'vocs/server'
+ *
+ * const app = new Hono()
+ * app.route('/docs', Handler.openApi({ spec: 'https://example.com/openapi.json' }))
+ * export default app
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Node.js
+ * import * as http from 'node:http'
+ * import { Handler } from 'vocs/server'
+ *
+ * const ref = Handler.openApi({ spec: './openapi.yaml' })
+ * http.createServer(ref.listener).listen(3000)
+ * ```
+ */
+export function openApi(config: OpenApi.Config, options: openApi.Options = {}): Handler {
+  const app = new Hono()
+  // Parse the spec + compile pages once, lazily, and memoize. The first
+  // request's origin seeds `baseUrl` so a relative `x-openrpc` URL (e.g.
+  // `/openrpc.json`) can be fetched at runtime; the OpenRPC document is
+  // host-independent, so reusing the first origin across requests is correct.
+  let state: Promise<Payload> | undefined
+  const prepare = (baseUrl?: string) => {
+    if (!state) state = State.prepare(config, { rootDir: options.rootDir, baseUrl })
+    return state
+  }
+  // Resolve custom CSS once, lazily, and memoize (a `file` read needs `node:fs`,
+  // so only touch it when a file is actually configured).
+  let css: Promise<string | undefined> | undefined
+  const resolveCss = () => {
+    if (!css) css = State.resolveCss(options.css, { rootDir: options.rootDir })
+    return css
+  }
+  app.get('*', async (c, next) => {
+    const { pathname, origin } = new URL(c.req.url)
+    // Serve a bundled asset if the path targets the asset root.
+    const asset = Assets.match(pathname)
+    if (asset) return Assets.response(asset)
+    const payload = await prepare(origin)
+    const routes = knownRoutes(payload)
+    // Serve the Markdown / agent-facing version of a route: `<route>.md`, any
+    // route requested with `Accept: text/markdown`, or an AI/terminal client.
+    // Shares the exact negotiation rules of the site `.md` router (Open Graph
+    // bots and search engines stay on HTML). Generated routes (overview +
+    // categories) win over overrides, and authored guide pages serve their own
+    // Markdown.
+    const wantsMarkdown = prefersMarkdown({
+      pathname,
+      userAgent: c.req.header('user-agent'),
+      accept: c.req.header('accept'),
+    })
+    if (wantsMarkdown) {
+      const basePathname = pathname.endsWith('.md') ? pathname.slice(0, -3) : pathname
+      const mount =
+        options.fallback === 'next'
+          ? mountFromRoutePath(c.req.routePath)
+          : inferMount(basePathname, routes)
+      const markdown = resolveMarkdown(payload, relativeRoute(basePathname, mount), mount)
+      if (markdown) return c.text(markdown, 200, { 'content-type': 'text/markdown; charset=utf-8' })
+      // Explicit `.md` for an unknown route falls through to the normal handling
+      // below (renders the shell, or `next()` in fallback mode).
+    }
+    // Fallthrough mode: only own the reference's own routes (the intro/landing,
+    // each group/page, and the asset root above) and defer everything else to
+    // the host app via `next()`. This lets the handler be mounted at the host
+    // root (`app.route('/', handler)`) alongside a JSON API and a JSON
+    // `notFound` without its catch-all swallowing them. The mount prefix comes
+    // from Hono's matched `routePath` (e.g. `/api/*`), so it's exact — unlike
+    // suffix inference, an API path like `/api/v1/blocks` is never mistaken for
+    // a docs route.
+    if (options.fallback === 'next') {
+      const mount = mountFromRoutePath(c.req.routePath)
+      const relative = (pathname.startsWith(mount) ? pathname.slice(mount.length) : pathname) || '/'
+      if (!isKnownRoute(relative, routes)) return next()
+    }
+    // Otherwise render the HTML shell (client-side router takes over).
+    const manifest = Assets.manifest()
+    if (!manifest.built)
+      return c.text(
+        '[vocs] The standalone OpenAPI bundle has not been built. Run `pnpm build` (or install a published build of `vocs`).',
+        500,
+      )
+    // Infer the host mount prefix so asset URLs route back to this handler
+    // regardless of where it is mounted (and independent of a trailing slash).
+    const mount =
+      options.fallback === 'next'
+        ? mountFromRoutePath(c.req.routePath)
+        : inferMount(pathname, routes)
+    const customCss = await resolveCss()
+    // The shell references content-hashed assets, so it must never be cached:
+    // a stale shell would point at an old hash (404 after a rebuild), leaving
+    // the page rendered but unstyled. Assets themselves stay `immutable`.
+    return c.html(Html.render(payload, manifest, mount, customCss), 200, {
+      'cache-control': 'no-store, must-revalidate',
+    })
+  })
+  return withListener(app)
+}
+export declare namespace openApi {
+  type Options = {
+    /**
+     * Directory file-path specs/pages are resolved against.
+     * @default process.cwd()
+     */
+    rootDir?: string | undefined
+    /**
+     * Custom CSS injected into the shell `<head>` as an inline `<style>`, after
+     * the design-system stylesheets so it overrides them. Use it to tweak the
+     * standalone reference's theme without rebuilding the bundle.
+     *
+     * - A string of CSS.
+     * - `{ file }`: a path to a `.css` file, resolved against `rootDir` and read
+     *   with `node:fs` (Node only; pass a string on filesystem-less runtimes).
+     *
+     * @example
+     * ```ts
+     * Handler.openApi({ spec }, { css: ':root { --vocs-color-accent: #7c3aed }' })
+     * ```
+     *
+     * @example
+     * ```ts
+     * Handler.openApi({ spec }, { css: { file: './api-theme.css' } })
+     * ```
+     */
+    css?: string | { file: string } | undefined
+    /**
+     * How to handle requests that don't target one of the reference's own
+     * routes (the intro/landing, a group/page, or the asset root).
+     *
+     * - `'render'` (default): render the HTML shell for any path, so client-side
+     *   deep links work when the handler owns the whole mount (standalone docs).
+     * - `'next'`: call Hono's `next()` so the host app handles the request. Use
+     *   this when mounting at the host root next to other routes (e.g. a JSON
+     *   API + JSON `notFound`):
+     *
+     * @example
+     * ```ts
+     * app.route('/', Handler.openApi({ spec }, { fallback: 'next' }))
+     * ```
+     *
+     * @default 'render'
+     */
+    fallback?: 'render' | 'next' | undefined
+  }
+}
+/** Derives the host mount prefix from Hono's matched `routePath` (`/api/*` → `/api`, `/*` → ``). */
+function mountFromRoutePath(routePath: string | undefined): string {
+  return (routePath ?? '').replace(/\*+$/, '').replace(/\/+$/, '')
+}
+/** Whether a mount-relative path is one of the reference's known section routes. */
+function isKnownRoute(relativePath: string, routes: readonly string[]): boolean {
+  const path = stripTrailingSlash(relativePath) || '/'
+  return routes.some((route) => (stripTrailingSlash(route) || '/') === path)
+}
+/** Strips the host mount prefix from a pathname, yielding a section route. */
+function relativeRoute(pathname: string, mount: string): string {
+  const path = pathname.startsWith(mount) ? pathname.slice(mount.length) : pathname
+  return stripTrailingSlash(path) || '/'
+}
+/**
+ * Resolves the Markdown for a section route: the generated overview (intro), a
+ * generated category page, or an authored guide page's own Markdown. Returns
+ * `null` for unknown routes. `mount` is the live host prefix, prepended to the
+ * overview's endpoint links so they resolve back to this handler.
+ */
+function resolveMarkdown(payload: Payload, relative: string, mount: string): string | null {
+  const base = payload.ir.path || '/'
+  const linkBase = `${mount}${base === '/' ? '' : base}`
+  const introRoute = base === '/' ? '/' : normalizePath(base)
+  if (relative === introRoute) return Markdown.renderOverview(payload.ir, linkBase)
+  for (const group of payload.ir.groups)
+    if (relative === join(base, `/${group.id}`)) return Markdown.renderGroup(payload.ir, group)
+  for (const page of payload.pages)
+    if (page.markdown && relative === join(base, page.path)) return page.markdown
+  return null
+}
+function stripTrailingSlash(value: string): string {
+  return value.length > 1 && value.endsWith('/') ? value.slice(0, -1) : value
+}
+/**
+ * Composes multiple handlers onto a single Hono app mounted at `path`
+ * (default `/`).
+ */
+export function compose(handlers: readonly Handler[], options: compose.Options = {}): Handler {
+  const app = new Hono()
+  for (const handler of handlers) app.route(options.path ?? '/', handler)
+  app.notFound(() => new Response('Not Found', { status: 404 }))
+  return withListener(app)
+}
+export declare namespace compose {
+  type Options = {
+    /** Mount path for every composed handler. @default "/" */
+    path?: string | undefined
+  }
+}
+/**
+ * Augments a Hono app with a Node request `listener`.
+ *
+ * The listener is created lazily on first access. `getRequestListener`
+ * (from `@hono/node-server`) overwrites the global `Request`/`Response` with
+ * non-configurable Node polyfills the first time it runs; on edge runtimes
+ * (Cloudflare Workers, Deno, Bun) that would replace the native `Response` and
+ * make every `c.json()`/`c.html()` produce a value the runtime rejects. Edge
+ * consumers only ever call `.fetch()` (or mount via `app.route(...)`) and never
+ * touch `.listener`, so deferring its creation keeps the global `Response`
+ * native there, while Node consumers (`http.createServer(ref.listener)`) get the
+ * same behavior as before on first access.
+ */
+function withListener<app extends Hono>(app: app): Handler<app> {
+  let listener: ReturnType<typeof getRequestListener> | undefined
+  // Define the getter directly (not via `Object.assign`, which would invoke it
+  // immediately while copying the property and defeat the laziness).
+  Object.defineProperty(app, 'listener', {
+    configurable: true,
+    enumerable: true,
+    get() {
+      if (!listener) listener = getRequestListener((request) => app.fetch(request))
+      return listener
+    },
+  })
+  return app as Handler<app>
+}

package/src/server/openapi/html.ts ADDED Viewed

@@ -0,0 +1,84 @@
+import type { Payload } from '../../internal/openapi/app.js'
+import { type Assets, assetRoot } from './assets.js'
+/**
+ * Renders the prebuilt app's HTML shell: the real Vocs `<html data-vocs>` root
+ * (so the design system + theming apply), a pre-paint theme bootstrap, the
+ * embedded JSON payload, and references to the prebuilt browser bundle.
+ *
+ * Assets are referenced with absolute URLs prefixed by the inferred `mount`, so
+ * they route back to the handler regardless of where it is mounted (and
+ * independent of a trailing slash on the current URL).
+ *
+ * `css` is consumer-supplied custom CSS injected as an inline `<style>` after
+ * the design-system stylesheets so it overrides them.
+ */
+export function render(payload: Payload, assets: Assets, mount: string, css?: string): string {
+  const base = `${mount === '/' ? '' : mount}${assetRoot}`
+  const styles = assets.styles
+    .map((href) => `<link rel="stylesheet" href="${base}${href}">`)
+    .join('\n    ')
+  const userStyles = css ? `\n    <style>${escapeStyle(css)}</style>` : ''
+  const data = escapeJson(payload)
+  const colorScheme = (payload.config?.colorScheme as string | undefined) ?? 'light dark'
+  const accentColor =
+    (payload.config?.accentColor as string | undefined) ?? 'light-dark(black, white)'
+  const staticTheme = colorScheme === 'light' || colorScheme === 'dark' ? colorScheme : undefined
+  return `<!doctype html>
+<html data-vocs lang="en"${staticTheme ? ` data-vocs-theme="${staticTheme}"` : ''} style="color-scheme: ${escapeAttr(colorScheme)}; --vocs-color-accent: ${escapeAttr(accentColor)}" suppressHydrationWarning>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml(payload.title)}</title>
+    <script>${themeBootstrap(colorScheme)}</script>
+    ${styles}${userStyles}
+  </head>
+  <body data-version="1.0">
+    <script id="vocs-openapi-data" type="application/json">${data}</script>
+    <script type="module" src="${base}${assets.entry}"></script>
+  </body>
+</html>`
+}
+/**
+ * Applies the persisted (`localStorage.vocs-theme`) or system color scheme to
+ * `<html data-vocs-theme>` / `colorScheme` before first paint (matching
+ * {@link file://../../react/Root.client.tsx Root_client}).
+ */
+function themeBootstrap(colorScheme: string): string {
+  return `(function(){try{var s=${JSON.stringify(colorScheme)};var e=document.documentElement;var t;if(s==='light'||s==='dark')t=s;else{t=localStorage.getItem('vocs-theme');if(t!=='light'&&t!=='dark')t=matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light';}e.setAttribute('data-vocs-theme',t);e.style.colorScheme=t;}catch(_){}})()`
+}
+/** Escapes a value for safe embedding inside a `<script>` JSON block. */
+function escapeJson(value: unknown): string {
+  return JSON.stringify(value)
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029')
+}
+/** Escapes text for safe embedding in HTML element content. */
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+/** Escapes a value for safe embedding inside a double-quoted HTML attribute. */
+function escapeAttr(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;')
+}
+/**
+ * Neutralizes sequences that would prematurely close the inline `<style>` block
+ * (or smuggle in a `<script>`). CSS itself is left untouched — full HTML
+ * escaping would corrupt valid CSS like `>` child combinators.
+ */
+function escapeStyle(value: string): string {
+  return value.replace(/<\/(style|script)/gi, '<\\/$1')
+}