raffel 1.1.97 → 1.1.98-next.e243022

package/dist/docs/try-it-proxy.d.ts

@@ -13,4 +13,19 @@ export interface DocsTryItProxyOptions {
     fetchImpl?: typeof fetch;
 }
 export declare function executeDocsTryItProxy(payload: DocsTryItRequest, options: DocsTryItProxyOptions): Promise<Response>;
+export interface DocsTryItStreamRequest {
+    url: string;
+    /** Optional bearer/authorization value forwarded upstream (EventSource cannot set headers itself). */
+    authorization?: string;
+}
+/**
+ * Same-origin proxy for a docs "try it out" SSE / EventSource console.
+ *
+ * Unlike {@link executeDocsTryItProxy} this does NOT buffer the response — it
+ * pipes the upstream `text/event-stream` body straight back so an infinite
+ * stream keeps flowing. The same origin allowlist applies: only declared USD
+ * server origins (or explicitly configured `allowedOrigins`) are reachable, so
+ * the console cannot be pointed at an arbitrary host.
+ */
+export declare function executeDocsTryItStreamProxy(payload: DocsTryItStreamRequest, options: DocsTryItProxyOptions): Promise<Response>;
 //# sourceMappingURL=try-it-proxy.d.ts.map

package/dist/docs/try-it-proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"try-it-proxy.d.ts","sourceRoot":"","sources":["../../src/docs/try-it-proxy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAErD,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,SAAS,EAAE,CAAA;IACrB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;IACzB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CACzB;AAED,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,QAAQ,CAAC,CA6DnB"}
+{"version":3,"file":"try-it-proxy.d.ts","sourceRoot":"","sources":["../../src/docs/try-it-proxy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAErD,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,SAAS,EAAE,CAAA;IACrB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;IACzB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CACzB;AAED,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,QAAQ,CAAC,CA6DnB;AAED,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAA;IACX,sGAAsG;IACtG,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,sBAAsB,EAC/B,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,QAAQ,CAAC,CAsDnB"}

package/dist/docs/try-it-proxy.js

@@ -60,6 +60,60 @@ export async function executeDocsTryItProxy(payload, options) {
         clearTimeout(timeout);
     }
 }
+/**
+ * Same-origin proxy for a docs "try it out" SSE / EventSource console.
+ *
+ * Unlike {@link executeDocsTryItProxy} this does NOT buffer the response — it
+ * pipes the upstream `text/event-stream` body straight back so an infinite
+ * stream keeps flowing. The same origin allowlist applies: only declared USD
+ * server origins (or explicitly configured `allowedOrigins`) are reachable, so
+ * the console cannot be pointed at an arbitrary host.
+ */
+export async function executeDocsTryItStreamProxy(payload, options) {
+    const target = parseTarget(payload?.url ?? '');
+    const allowedServers = resolveServerUrls(options.servers ?? []);
+    const allowedOrigins = new Set((options.allowedOrigins ?? []).flatMap(origin => {
+        const parsed = parseTarget(origin);
+        return parsed ? [parsed.origin] : [];
+    }));
+    if (!target || (!allowedOrigins.has(target.origin) && !allowedServers.some(server => isWithinServer(target, server)))) {
+        return problem(403, 'Request target is not allowed', 'The documentation proxy only connects to declared API server origins.');
+    }
+    const headers = new Headers({ accept: 'text/event-stream' });
+    if (payload.authorization)
+        headers.set('authorization', payload.authorization);
+    // Guard only the connection handshake; once headers arrive we stop the timer
+    // so the (potentially infinite) stream body is never aborted mid-flight.
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 15_000);
+    let upstream;
+    try {
+        upstream = await (options.fetchImpl ?? fetch)(target.toString(), {
+            method: 'GET',
+            headers,
+            redirect: 'manual',
+            signal: controller.signal,
+        });
+    }
+    catch {
+        clearTimeout(timeout);
+        const timedOut = controller.signal.aborted;
+        return problem(timedOut ? 504 : 502, timedOut ? 'Upstream stream timed out' : 'Upstream stream failed', timedOut
+            ? 'The declared upstream server did not start the stream before the configured timeout.'
+            : 'The declared upstream server could not open the stream.');
+    }
+    clearTimeout(timeout);
+    if (!upstream.ok || !upstream.body) {
+        return problem(upstream.status >= 400 ? upstream.status : 502, 'Upstream stream unavailable', 'The declared upstream server did not return a readable event stream.');
+    }
+    return new Response(upstream.body, {
+        status: 200,
+        headers: {
+            'Content-Type': 'text/event-stream; charset=utf-8',
+            'Cache-Control': 'no-store',
+        },
+    });
+}
 const HOP_BY_HOP_HEADERS = new Set([
     'connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization',
     'te', 'trailer', 'transfer-encoding', 'upgrade', 'host', 'content-length',

package/dist/docs/try-it-proxy.js.map

@@ -1 +1 @@
-{"version":3,"file":"try-it-proxy.js","sourceRoot":"","sources":["../../src/docs/try-it-proxy.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"try-it-proxy.js","sourceRoot":"","sources":["../../src/docs/try-it-proxy.ts"],"names":[],"mappings":"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"}

package/dist/docs/ui/assets/marked-renderer.js

@@ -70,7 +70,11 @@ function buildRenderer(currentPath, seenHeadingIds, deps) {
             return `<h${token.depth} class="md-h${token.depth}" id="${deps.escapeAttr(id)}"${ignored}><a class="heading-anchor" href="${deps.escapeAttr(href)}">#</a>${deps.parseMarkdown(parsed.title, currentPath).replace(/^<p class="md-p">|<\/p>\n?$/g, '')}</h${token.depth}>`;
         },
         paragraph(token) { return `<p class="md-p">${inline(this, token.tokens)}</p>`; },
-        list(token) { const tag = token.ordered ? 'ol' : 'ul'; return `<${tag} class="md-list">${token.items.map((item) => this.listitem(item)).join('')}</${tag}>`; },
+        list(token) {
+            const tag = token.ordered ? 'ol' : 'ul';
+            const start = token.ordered && token.start && token.start !== 1 ? ` start="${deps.escapeAttr(token.start)}"` : '';
+            return `<${tag} class="md-list"${start}>${token.items.map((item) => this.listitem(item)).join('')}</${tag}>`;
+        },
         listitem(item) { return `<li>${item.task ? `<input type="checkbox" disabled${item.checked ? ' checked' : ''}> ` : ''}${this.parser.parse(item.tokens)}</li>`; },
         codespan(token) { return `<code class="md-inline-code">${deps.esc(token.text)}</code>`; },
         code(token) {
@@ -106,7 +110,14 @@ function buildRenderer(currentPath, seenHeadingIds, deps) {
             const classAttr = parsed.attrs.classes.length > 0 ? '' : ' class="md-image"';
             return `<img${classAttr} src="${deps.escapeAttr(resolved)}" alt="${deps.escapeAttr(token.text)}"${attrs}>`;
         },
-        text(token) { return deps.renderEmojiShorthand(deps.esc(token.text)); },
+        text(token) {
+            // A block-level `text` token (e.g. an item in a tight list) carries its
+            // inline markup as child tokens. The default renderer recurses into them;
+            // returning the raw `token.text` would leak literal `**`, backticks, etc.
+            if (token.tokens && token.tokens.length)
+                return this.parser.parseInline(token.tokens);
+            return deps.renderEmojiShorthand(deps.esc(token.text));
+        },
     };
 }
 function isSafeMarkedUrl(url) {

package/dist/docs/ui/assets/protocol-console.js

@@ -1,3 +1,15 @@
+/**
+ * Resolve the URL an EventSource should open: the raw upstream in `direct`
+ * mode, or the same-origin `-/stream` proxy (with the upstream passed as a
+ * `url` query param) when the docs are configured for `proxy` mode. Routing
+ * through the proxy avoids CORS and keeps the stream on the declared origin.
+ */
+function resolveStreamUrl(tryItConfig, target) {
+    if (tryItConfig?.mode === 'proxy' && tryItConfig.streamProxyUrl) {
+        return `${tryItConfig.streamProxyUrl}?url=${encodeURIComponent(target)}`;
+    }
+    return target;
+}
 export function appendProtocolConsole(container, deps) {
     if (deps.activeProtocol === 'http')
         return;
@@ -76,7 +88,7 @@ function bindLiveConsole(panel, deps) {
                     run.textContent = 'Connect';
                     return;
                 }
-                events = new EventSource(url.value);
+                events = new EventSource(resolveStreamUrl(deps.tryItConfig, url.value));
                 events.onopen = () => { run.textContent = 'Close'; write('connected'); };
                 events.onmessage = (event) => write(`event ${event.data}`);
                 events.onerror = () => write('stream error');

package/dist/docs/ui/assets/raffel-docs.css

@@ -543,120 +543,11 @@
     }
 
     /* ========== INTRODUCTION SECTION ========== */
-    .introduction {
-      background: var(--bg-color);
-      padding: 80px 40px;
-      max-width: 100%;
-    }
-
-    .introduction-content {
-      max-width: 900px;
-      margin: 0 auto;
-      font-size: 1.1em;
-      line-height: 1.8;
-    }
-
-    .introduction-content h1 {
-      font-size: 2.5em;
-      margin-bottom: 24px;
-      color: var(--text-color);
-      font-weight: 700;
-      border-bottom: 2px solid var(--border-color);
-      padding-bottom: 16px;
-    }
-
-    .introduction-content h2 {
-      font-size: 1.8em;
-      margin: 48px 0 16px;
-      color: var(--text-color);
-      font-weight: 600;
-    }
-
-    .introduction-content h3 {
-      font-size: 1.4em;
-      margin: 32px 0 12px;
-      color: var(--text-color);
-      font-weight: 600;
-    }
-
-    .introduction-content p {
-      margin-bottom: 16px;
-      color: var(--text-muted);
-    }
-
-    .introduction-content ul,
-    .introduction-content ol {
-      margin: 16px 0;
-      padding-left: 24px;
-    }
-
-    .introduction-content li {
-      margin-bottom: 8px;
-      color: var(--text-muted);
-    }
-
-    .introduction-content pre {
-      background: var(--code-bg);
-      border-radius: 8px;
-      padding: 20px;
-      overflow-x: auto;
-      margin: 24px 0;
-    }
-
-    .introduction-content code {
-      font-family: 'JetBrains Mono', 'Fira Code', monospace;
-      font-size: 0.9em;
-    }
-
-    .introduction-content p code {
-      background: var(--code-bg);
-      padding: 2px 6px;
-      border-radius: 4px;
-    }
-
-    .introduction-content blockquote {
-      border-left: 4px solid var(--primary-color);
-      padding: 16px 24px;
-      margin: 24px 0;
-      background: var(--hover-bg);
-      border-radius: 0 8px 8px 0;
-    }
-
-    .introduction-content blockquote p {
-      margin: 0;
-    }
-
-    .introduction-content a {
-      color: var(--primary-color);
-      text-decoration: none;
-    }
-
-    .introduction-content a:hover {
-      text-decoration: underline;
-    }
-
-    .introduction-content table {
-      width: 100%;
-      border-collapse: collapse;
-      margin: 24px 0;
-    }
-
-    .introduction-content th,
-    .introduction-content td {
-      border: 1px solid var(--border-color);
-      padding: 12px 16px;
-      text-align: left;
-    }
-
-    .introduction-content th {
-      background: var(--code-bg);
-      font-weight: 600;
-    }
-
-    .introduction-content hr {
-      border: none;
-      border-top: 1px solid var(--border-color);
-      margin: 48px 0;
+    /* Rendered inside #mainContent on the root view, right after the overview
+       and before authentication/endpoints. Typography comes from
+       .markdown-content; only the surrounding spacing is set here. */
+    .docs-introduction {
+      margin: 32px 0;
     }
 
     /* ========== LAYOUT ========== */
@@ -1396,7 +1287,7 @@
 
     /* ========== BREADCRUMBS ========== */
     .docs-breadcrumb {
-      margin: 0 0 16px 0;
+      margin: 0 0 20px 0;
       font-size: 12px;
       color: var(--text-muted);
     }
@@ -1798,6 +1689,16 @@
       color: var(--text-secondary);
     }
 
+    /* The global `* { margin: 0 }` reset strips the UA heading margins; every
+       other md heading restores its own, so md-h1 needs one too — otherwise the
+       page title sits flush against the breadcrumb above and the content below. */
+    .markdown-content .md-h1 {
+      font-weight: 700;
+      color: var(--text-primary);
+      line-height: 1.25;
+      margin: 0 0 24px 0;
+    }
+
     .markdown-content .md-h2 {
       font-size: 16px;
       font-weight: 600;

package/dist/docs/ui/assets/raffel-docs.js

@@ -2287,11 +2287,168 @@ function renderAsyncContracts(title, entries, callbacks = false) {
     });
     return section;
 }
+// Merge content-type declarations across the three USD layers (operation →
+// protocol → global) the same way the reference generator does, so a console
+// row shows the effective default plus every supported media type.
+function resolveEffectiveContentTypes(operationTypes, protocolTypes) {
+    const globalTypes = (xUsd && xUsd.contentTypes) ? xUsd.contentTypes : {};
+    const defaultType = (operationTypes && operationTypes.default)
+        || (protocolTypes && protocolTypes.default)
+        || globalTypes.default
+        || 'application/json';
+    const supportedList = (operationTypes && operationTypes.supported)
+        || (protocolTypes && protocolTypes.supported)
+        || globalTypes.supported
+        || [];
+    const supported = Array.isArray(supportedList) ? supportedList.slice() : [];
+    if (defaultType && supported.indexOf(defaultType) === -1)
+        supported.unshift(defaultType);
+    return { default: defaultType, supported };
+}
+function appendContentTypesSection(container, label, contentTypes) {
+    if (!contentTypes)
+        return;
+    const section = doc.createElement('div');
+    section.className = 'endpoint-subsection';
+    section.innerHTML = `<div class="subsection-label">${esc(label)}</div>`;
+    const grid = doc.createElement('div');
+    grid.className = 'info-grid';
+    const supportedText = (contentTypes.supported && contentTypes.supported.length > 0)
+        ? contentTypes.supported.join(', ')
+        : contentTypes.default;
+    grid.innerHTML =
+        `<div class="info-card"><div class="info-card-title">Default</div><div class="info-card-value">${esc(contentTypes.default || 'application/json')}</div></div>` +
+            `<div class="info-card"><div class="info-card-title">Supported</div><div class="info-card-value">${esc(supportedText || 'application/json')}</div></div>`;
+    section.appendChild(grid);
+    container.appendChild(section);
+}
+// Multi-language client snippets for WebSocket channels.
+function generateWsCodeSample(lang, url, path, data) {
+    const channelType = data?.type || 'public';
+    const subscribeMsg = { type: 'subscribe', channel: path, id: '1' };
+    const subscribeMsgStr = JSON.stringify(subscribeMsg, null, 2);
+    const publishMsg = data?.publish?.message?.payload
+        ? { type: 'publish', channel: path, event: 'message', data: generateExampleFromSchema(data.publish.message.payload), id: '2' }
+        : null;
+    const needsAuth = channelType === 'private' || channelType === 'presence';
+    const authUrl = needsAuth ? `${url}?token=YOUR_TOKEN` : url;
+    const indent = (value, pad) => value.split('\n').map((line, i) => i === 0 ? line : pad + line).join('\n');
+    switch (lang) {
+        case 'wscat': {
+            let out = `wscat -c "${authUrl}"\n\n# Subscribe to channel:\n> ${JSON.stringify(subscribeMsg)}`;
+            if (publishMsg)
+                out += `\n\n# Publish a message:\n> ${JSON.stringify(publishMsg)}`;
+            return out;
+        }
+        case 'javascript': {
+            let out = `const ws = new WebSocket("${authUrl}");\n\n`;
+            out += `ws.onopen = () => {\n  console.log("Connected");\n  // Subscribe to channel\n  ws.send(JSON.stringify(${indent(subscribeMsgStr, '    ')}));\n};\n\n`;
+            out += `ws.onmessage = (event) => {\n  const msg = JSON.parse(event.data);\n  console.log("Received:", msg);\n`;
+            if (publishMsg)
+                out += `\n  // After subscribed, you can publish:\n  // ws.send(JSON.stringify(${JSON.stringify(publishMsg)}));\n`;
+            out += `};\n\nws.onclose = () => {\n  console.log("Disconnected");\n};`;
+            return out;
+        }
+        case 'recker': {
+            let out = `import { ws } from "recker";\n\n`;
+            out += needsAuth
+                ? `const socket = await ws("${url}", {\n  query: { token: "YOUR_TOKEN" }\n});\n\n`
+                : `const socket = await ws("${url}");\n\n`;
+            out += `// Subscribe to channel\nsocket.send(${indent(subscribeMsgStr, '  ')});\n\n`;
+            out += `// Listen for messages\nsocket.on("message", (data) => {\n  console.log("Received:", data);\n});\n`;
+            if (publishMsg)
+                out += `\n// Publish a message\n// socket.send(${JSON.stringify(publishMsg)});\n`;
+            return out;
+        }
+        case 'python': {
+            let out = `import asyncio\nimport websockets\nimport json\n\n`;
+            out += `async def connect():\n    async with websockets.connect("${authUrl}") as ws:\n`;
+            out += `        # Subscribe to channel\n        await ws.send(json.dumps(${indent(subscribeMsgStr, '        ')}))\n        \n`;
+            out += `        # Wait for messages\n        async for message in ws:\n            data = json.loads(message)\n            print(f"Received: {data}")\n\n`;
+            out += `asyncio.run(connect())`;
+            return out;
+        }
+        default:
+            return '// Not implemented';
+    }
+}
+// Multi-language client snippets for SSE / EventSource streams.
+function generateStreamCodeSample(lang, url) {
+    switch (lang) {
+        case 'curl':
+            return `curl -N "${url}"\n\n# -N disables buffering for streaming output`;
+        case 'eventsource':
+            return `const eventSource = new EventSource("${url}");\n\neventSource.onmessage = (event) => {\n  console.log("Received:", event.data);\n};\n\neventSource.onerror = (error) => {\n  console.error("Error:", error);\n  eventSource.close();\n};\n\n// To close the connection:\n// eventSource.close();`;
+        case 'recker':
+            return `import { sse } from "recker";\n\nconst stream = sse("${url}");\n\nfor await (const event of stream) {\n  console.log("Received:", event.data);\n}`;
+        case 'python':
+            return `import sseclient\nimport requests\n\nresponse = requests.get("${url}", stream=True)\nclient = sseclient.SSEClient(response)\n\nfor event in client.events():\n    print(f"Event: {event.event}, Data: {event.data}")`;
+        default:
+            return '// Not implemented';
+    }
+}
+// Tabbed client-code panel for the non-HTTP protocols that carry a live console
+// (WebSocket, streams). Mirrors renderCodeExamples' markup so the shared code
+// tab / copy styling applies.
+function renderProtocolCodeSamples(kind, endpoint, data) {
+    const base = String(spec.servers?.[0]?.url ?? 'http://localhost:3000').replace(/\/$/, '');
+    const isWs = kind === 'websocket';
+    const url = isWs
+        ? `${base.replace(/^http/, 'ws')}${wsSpec.path ?? '/ws'}`
+        : `${base}/${streamsSpec.pathPrefix ?? 'streams'}/${endpoint.path}`.replace(/([^:]\/)\/+/g, '$1');
+    const langs = isWs
+        ? [['wscat', 'wscat', 'bash'], ['javascript', 'WebSocket', 'javascript'], ['recker', 'Recker', 'typescript'], ['python', 'Python', 'python']]
+        : [['curl', 'cURL', 'bash'], ['eventsource', 'EventSource', 'javascript'], ['recker', 'Recker', 'typescript'], ['python', 'Python', 'python']];
+    const section = doc.createElement('div');
+    section.className = 'endpoint-subsection';
+    section.innerHTML = '<div class="subsection-label">Client examples</div>';
+    const wrap = doc.createElement('div');
+    wrap.className = 'http-code-samples';
+    const tabs = doc.createElement('div');
+    tabs.className = 'code-tabs';
+    const contents = doc.createElement('div');
+    contents.className = 'code-contents';
+    langs.forEach(([key, label, language], index) => {
+        const tab = doc.createElement('button');
+        tab.type = 'button';
+        tab.className = `code-tab${index === 0 ? ' active' : ''}`;
+        tab.textContent = label;
+        const content = doc.createElement('div');
+        content.className = `code-content${index === 0 ? ' active' : ''}`;
+        const pre = doc.createElement('pre');
+        pre.className = 'http-code-sample-pre';
+        pre.setAttribute('data-code-toolbar', 'managed');
+        const code = doc.createElement('code');
+        code.className = `language-${language}`;
+        code.textContent = isWs
+            ? generateWsCodeSample(key, url, endpoint.path, data)
+            : generateStreamCodeSample(key, url);
+        pre.appendChild(code);
+        content.appendChild(pre);
+        tab.onclick = () => {
+            tabs.querySelectorAll('.code-tab').forEach((t) => t.classList.remove('active'));
+            contents.querySelectorAll('.code-content').forEach((c) => c.classList.remove('active'));
+            tab.classList.add('active');
+            content.classList.add('active');
+        };
+        tabs.appendChild(tab);
+        contents.appendChild(content);
+    });
+    const copy = createSampleCopyButton('http-code-copy', () => {
+        const active = contents.querySelector('.code-content.active pre');
+        return active?.textContent ?? '';
+    });
+    tabs.appendChild(copy);
+    wrap.appendChild(tabs);
+    wrap.appendChild(contents);
+    section.appendChild(wrap);
+    return section;
+}
 function renderEndpointDetails(endpoint) {
     const container = doc.createElement('div');
     container.className = 'endpoint-details';
     const data = (endpoint.data ?? {});
-    appendProtocolConsole(container, { doc, spec, wsSpec, streamsSpec, jsonrpcSpec, activeProtocol, endpoint, data, esc, escapeAttr });
+    appendProtocolConsole(container, { doc, spec, wsSpec, streamsSpec, jsonrpcSpec, activeProtocol, endpoint, data, esc, escapeAttr, tryItConfig });
     const appendMany = (items) => items.forEach(([title, value]) => appendSchemaSubsection(container, title, value));
     if (activeProtocol === 'http') {
         // Two-column operation layout (ReDoc-style): the left column carries the
@@ -2417,6 +2574,9 @@ function renderEndpointDetails(endpoint) {
     if (activeProtocol === 'websocket') {
         appendInfoGrid(container, [['Channel Type', data.type], ['Path', endpoint.path]]);
         appendMany([['Parameters', parameterMapToSchema(data.parameters)], ['Subscribe Message', resolveMessagePayload(data.subscribe?.message)], ['Publish Message', resolveMessagePayload(data.publish?.message)]]);
+        appendContentTypesSection(container, 'Subscribe Content Types', resolveEffectiveContentTypes(data.subscribe?.contentTypes, wsSpec?.contentTypes));
+        appendContentTypesSection(container, 'Publish Content Types', resolveEffectiveContentTypes(data.publish?.contentTypes, wsSpec?.contentTypes));
+        container.appendChild(renderProtocolCodeSamples('websocket', endpoint, data));
     }
     if (activeProtocol === 'graphql') {
         appendInfoGrid(container, [['Endpoint', graphqlSpec.endpoint], ['Kind', data.kind], ['Resource', data.resource ?? data.name], ['Source', data.source]]);
@@ -2433,23 +2593,29 @@ function renderEndpointDetails(endpoint) {
         ]);
         appendStreamProjectionDiagnostics(container, resumable?.projections);
         appendMany([['Parameters', parameterMapToSchema(data.parameters)], ['Message Schema', resolveMessagePayload(data.message)]]);
+        appendContentTypesSection(container, 'Content Types', resolveEffectiveContentTypes(data.contentTypes, streamsSpec?.contentTypes));
+        container.appendChild(renderProtocolCodeSamples('streams', endpoint, data));
     }
     if (activeProtocol === 'jsonrpc') {
         appendInfoGrid(container, [['Method', endpoint.path], ['Notification', data['x-usd-notification'] === true ? 'yes' : undefined], ['Streaming', data['x-usd-streaming'] === true ? 'yes' : undefined]]);
         appendMany([['Parameters', data.params], ['Result', data.result], ['Errors', data.errors]]);
+        appendContentTypesSection(container, 'Content Types', resolveEffectiveContentTypes(data.contentTypes, jsonrpcSpec?.contentTypes));
     }
     if (activeProtocol === 'grpc') {
         const method = data.method ?? {};
         appendInfoGrid(container, [['Service', data.serviceName], ['Method', data.methodName], ['Type', getGrpcMethodType(method).replace(/_/g, ' ')]]);
         appendMany([['Request', method.input], ['Response', method.output]]);
+        appendContentTypesSection(container, 'Content Types', resolveEffectiveContentTypes(method.contentTypes, grpcSpec?.contentTypes));
     }
     if (activeProtocol === 'tcp') {
         appendInfoGrid(container, [['Host', data.host ?? 'localhost'], ['Port', data.port], ['TLS', data.tls?.enabled === true ? 'enabled' : undefined]]);
         appendMany([['Framing', data.framing], ['Inbound Message', resolveMessagePayload(data.messages?.inbound)], ['Outbound Message', resolveMessagePayload(data.messages?.outbound)]]);
+        appendContentTypesSection(container, 'Content Types', resolveEffectiveContentTypes(data.contentTypes, tcpSpec?.contentTypes));
     }
     if (activeProtocol === 'udp') {
         appendInfoGrid(container, [['Host', data.host ?? '127.0.0.1'], ['Port', data.port], ['Max Packet', data.maxPacketSize ? `${data.maxPacketSize} bytes` : undefined]]);
         appendMany([['Inbound Message', resolveMessagePayload(data.messages?.inbound)], ['Outbound Message', resolveMessagePayload(data.messages?.outbound)], ['Message Schema', resolveMessagePayload(data.message)]]);
+        appendContentTypesSection(container, 'Content Types', resolveEffectiveContentTypes(data.contentTypes, udpSpec?.contentTypes));
     }
     return container;
 }
@@ -3214,6 +3380,13 @@ function renderContent() {
     // mid-search, in which case the search results take the surface.
     if (!searchQuery) {
         main.appendChild(renderDocsOverview());
+        if (introductionMarkdown) {
+            const introduction = doc.createElement('section');
+            introduction.className = 'docs-introduction markdown-content';
+            introduction.id = 'introduction';
+            introduction.innerHTML = parseMarkdown(introductionMarkdown);
+            main.appendChild(introduction);
+        }
         const authentication = renderAuthenticationSection();
         if (authentication)
             main.appendChild(authentication);
@@ -4050,9 +4223,6 @@ function init() {
     if (activePagePath && activePagePath !== routeState.pagePath) {
         win.history?.replaceState?.(null, '', routeToHash(activePagePath, activeHeadingId));
     }
-    const intro = byId('introductionContent');
-    if (intro && introductionMarkdown)
-        intro.innerHTML = parseMarkdown(introductionMarkdown);
     initSidebarResize();
     bindEvents();
     renderFooter();

package/dist/docs/ui/client-script/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/docs/ui/client-script/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAqBH;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,gBAAgB,EAAE,MAAM,EACxB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,mBAAmB,EAAE,MAAM,EAC3B,gBAAgB,EAAE,MAAM,EACxB,kBAAkB,EAAE,MAAM,EAC1B,kBAAkB,EAAE,MAAM,EAC1B,kBAAkB,EAAE,MAAM,EAC1B,wBAAwB,EAAE,MAAM,EAChC,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,MAAM,EACvB,eAAe,GAAE,MAAe,EAChC,kBAAkB,GAAE,MAA6C,EACjE,cAAc,GAAE,MAAqC,EACrD,cAAc,GAAE,MAA6G,EAC7H,uBAAuB,GAAE,MAAa,EACtC,YAAY,GAAE,MAA4C,GACzD,MAAM,CAwBR;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,CAIpD;AAED,wBAAgB,sCAAsC,IAAI,MAAM,CAK/D;AAyKD;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,gBAAgB,EAAE,MAAM,EACxB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,mBAAmB,EAAE,MAAM,EAC3B,gBAAgB,EAAE,MAAM,EACxB,kBAAkB,EAAE,MAAM,EAC1B,kBAAkB,EAAE,MAAM,EAC1B,kBAAkB,EAAE,MAAM,EAC1B,wBAAwB,EAAE,MAAM,EAChC,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,MAAM,EACvB,eAAe,GAAE,MAAe,EAChC,kBAAkB,CAAC,EAAE,MAAM,EAC3B,cAAc,GAAE,MAAqC,GACpD,MAAM,CAoBR"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/docs/ui/client-script/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAWH;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,gBAAgB,EAAE,MAAM,EACxB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,mBAAmB,EAAE,MAAM,EAC3B,gBAAgB,EAAE,MAAM,EACxB,kBAAkB,EAAE,MAAM,EAC1B,kBAAkB,EAAE,MAAM,EAC1B,kBAAkB,EAAE,MAAM,EAC1B,wBAAwB,EAAE,MAAM,EAChC,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,MAAM,EACvB,eAAe,GAAE,MAAe,EAChC,kBAAkB,GAAE,MAA6C,EACjE,cAAc,GAAE,MAAqC,EACrD,cAAc,GAAE,MAA6G,EAC7H,uBAAuB,GAAE,MAAa,EACtC,YAAY,GAAE,MAA4C,GACzD,MAAM,CAwBR;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,CAQpD;AAED,wBAAgB,sCAAsC,IAAI,MAAM,CAK/D;AAoFD;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,gBAAgB,EAAE,MAAM,EACxB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,mBAAmB,EAAE,MAAM,EAC3B,gBAAgB,EAAE,MAAM,EACxB,kBAAkB,EAAE,MAAM,EAC1B,kBAAkB,EAAE,MAAM,EAC1B,kBAAkB,EAAE,MAAM,EAC1B,wBAAwB,EAAE,MAAM,EAChC,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,MAAM,EACvB,eAAe,GAAE,MAAe,EAChC,kBAAkB,CAAC,EAAE,MAAM,EAC3B,cAAc,GAAE,MAAqC,GACpD,MAAM,CAoBR"}