@djangocfg/ui-tools 2.1.287 → 2.1.290

package/src/tools/OpenapiViewer/utils/codeSamples.ts

@@ -0,0 +1,287 @@
+/**
+ * Code sample generation.
+ *
+ * In-house, browser-safe generator for a small catalogue of languages
+ * (curl / fetch / Node axios / Python requests / Go / PHP / Ruby /
+ * Java OkHttp). We used to wrap Kong's ``httpsnippet`` here but it is
+ * Node-only — the bundle referenced ``global`` / ``stream`` /
+ * ``string_decoder`` and crashed in Vite dev. Writing our own keeps the
+ * chunk small (a few kB vs ~1.5 MB) and avoids runtime polyfills.
+ *
+ * Adding more targets later is one function plus a row in the catalogue.
+ */
+
+import type { HarRequest } from './operationToHar';
+
+// Prism language ids used by ``prism-react-renderer``. ``bash``,
+// ``ruby``, ``java`` and ``php`` aren't in the library's default
+// bundle, but our ``registerPrismLanguages`` module pulls their
+// grammars from ``prismjs`` at load time so they work as first-class
+// languages here.
+export const CODE_SAMPLE_TARGETS = [
+    { id: 'curl', label: 'cURL', prism: 'bash' },
+    { id: 'fetch', label: 'JavaScript', prism: 'javascript' },
+    { id: 'axios', label: 'Node (axios)', prism: 'javascript' },
+    { id: 'python', label: 'Python', prism: 'python' },
+    { id: 'go', label: 'Go', prism: 'go' },
+    { id: 'php', label: 'PHP', prism: 'php' },
+    { id: 'ruby', label: 'Ruby', prism: 'ruby' },
+    { id: 'java', label: 'Java', prism: 'java' },
+] as const;
+
+export type CodeSampleTargetId = typeof CODE_SAMPLE_TARGETS[number]['id'];
+
+// ─── Body literal helpers ─────────────────────────────────────────────────────
+//
+// Pre-formatted JSON bodies (``JSON.stringify(value, null, 2)``) carry
+// real newlines that we want the snippet to preserve — a one-line
+// escaped string like ``"{\n  \"id\": 10,\n …}"`` reads as a wall of
+// escape sequences. Each helper below returns a multi-line string
+// literal in the target language's native syntax so the snippet reads
+// like hand-written code.
+
+/** Go raw string literal — uses backticks. Falls back to a double-
+ *  quoted escaped literal when the body itself contains a backtick. */
+function goRawString(s: string): string {
+    return s.includes('`') ? JSON.stringify(s) : `\`${s}\``;
+}
+
+/** Python triple-quoted string — uses ``"""``. Falls back to escaped
+ *  form when the body already contains that sequence. */
+function pythonTripleQuote(s: string): string {
+    return s.includes('"""') ? JSON.stringify(s) : `"""${s}"""`;
+}
+
+/** Ruby squiggly heredoc — ``<<~JSON`` style strips common leading
+ *  whitespace. Safe unless the body literally contains ``JSON`` on a
+ *  line by itself, which is vanishingly rare. */
+function rubyHeredoc(s: string): string {
+    return `<<~JSON\n${s}\nJSON`;
+}
+
+/** PHP heredoc — ``<<<JSON`` style. Same caveat as Ruby's. Trailing
+ *  ``JSON;`` must sit at column 0 (enforced by this template). */
+function phpHeredoc(s: string): string {
+    return `<<<JSON\n${s}\nJSON`;
+}
+
+/** Java 15+ text block — ``"""``. Falls back to an escaped literal
+ *  when the body contains that sequence. */
+function javaTextBlock(s: string): string {
+    if (s.includes('"""')) return JSON.stringify(s);
+    // Text blocks need the opening ``"""`` on its own line — the
+    // parser strips the newline that immediately follows the delimiter.
+    return `"""\n${s}\n"""`;
+}
+
+function fullUrl(har: HarRequest): string {
+    if (!har.queryString.length) return har.url;
+    const qs = har.queryString
+        .map((p) => `${encodeURIComponent(p.name)}=${encodeURIComponent(p.value)}`)
+        .join('&');
+    const sep = har.url.includes('?') ? '&' : '?';
+    return `${har.url}${sep}${qs}`;
+}
+
+function shellEscape(value: string): string {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+function renderCurl(har: HarRequest): string {
+    const lines: string[] = [`curl -X ${har.method} ${shellEscape(fullUrl(har))}`];
+    for (const h of har.headers) {
+        lines.push(`  -H ${shellEscape(`${h.name}: ${h.value}`)}`);
+    }
+    if (har.postData?.text) {
+        lines.push(`  -d ${shellEscape(har.postData.text)}`);
+    }
+    return lines.join(' \\\n');
+}
+
+function jsHeadersLiteral(har: HarRequest, indent: string): string {
+    if (!har.headers.length) return '{}';
+    const entries = har.headers
+        .map((h) => `${indent}  ${JSON.stringify(h.name)}: ${JSON.stringify(h.value)}`)
+        .join(',\n');
+    return `{\n${entries},\n${indent}}`;
+}
+
+/** JS template literal — backtick string that preserves newlines and
+ *  escapes backticks / ``${`` sequences. Makes multi-line JSON body
+ *  readable inside the fetch() options. */
+function jsTemplateLiteral(s: string): string {
+    if (/[`$]/.test(s)) return JSON.stringify(s);
+    return `\`${s}\``;
+}
+
+function renderFetch(har: HarRequest): string {
+    const url = fullUrl(har);
+    const options: string[] = [`  method: ${JSON.stringify(har.method)}`];
+    if (har.headers.length) {
+        options.push(`  headers: ${jsHeadersLiteral(har, '  ')}`);
+    }
+    if (har.postData?.text) {
+        options.push(`  body: ${jsTemplateLiteral(har.postData.text)}`);
+    }
+    return `const response = await fetch(${JSON.stringify(url)}, {\n${options.join(',\n')},\n});\nconst data = await response.json();`;
+}
+
+function renderAxios(har: HarRequest): string {
+    const url = fullUrl(har);
+    const config: string[] = [
+        `  method: ${JSON.stringify(har.method.toLowerCase())}`,
+        `  url: ${JSON.stringify(url)}`,
+    ];
+    if (har.headers.length) {
+        config.push(`  headers: ${jsHeadersLiteral(har, '  ')}`);
+    }
+    if (har.postData?.text) {
+        // Axios auto-serializes objects; we pass the raw JSON string as data.
+        config.push(`  data: ${har.postData.text}`);
+    }
+    return `import axios from 'axios';\n\nconst { data } = await axios({\n${config.join(',\n')},\n});`;
+}
+
+function renderPython(har: HarRequest): string {
+    const lines: string[] = [`import requests`, ``];
+    lines.push(`url = ${JSON.stringify(fullUrl(har))}`);
+    if (har.headers.length) {
+        const headerEntries = har.headers
+            .map((h) => `    ${JSON.stringify(h.name)}: ${JSON.stringify(h.value)}`)
+            .join(',\n');
+        lines.push(`headers = {\n${headerEntries},\n}`);
+    }
+    if (har.postData?.text) {
+        // ``json=payload`` on ``requests`` expects a Python object, not
+        // a JSON string — so we leave the body as a raw dict literal
+        // (which Python parses identically to the JSON source for the
+        // shapes we generate). No wrapping helper needed here.
+        lines.push(`payload = ${har.postData.text}`);
+    }
+    const args = [`url`];
+    if (har.headers.length) args.push(`headers=headers`);
+    if (har.postData?.text) args.push(`json=payload`);
+    lines.push(``, `response = requests.${har.method.toLowerCase()}(${args.join(', ')})`);
+    lines.push(`data = response.json()`);
+    return lines.join('\n');
+}
+
+function renderGo(har: HarRequest): string {
+    const url = fullUrl(har);
+    const lines: string[] = [
+        `package main`,
+        ``,
+        `import (`,
+        `    "fmt"`,
+        `    "io"`,
+    ];
+    if (har.postData?.text) lines.push(`    "strings"`);
+    lines.push(`    "net/http"`);
+    lines.push(`)`, ``, `func main() {`);
+    if (har.postData?.text) {
+        lines.push(`    payload := strings.NewReader(${goRawString(har.postData.text)})`);
+        lines.push(`    req, _ := http.NewRequest(${JSON.stringify(har.method)}, ${JSON.stringify(url)}, payload)`);
+    } else {
+        lines.push(`    req, _ := http.NewRequest(${JSON.stringify(har.method)}, ${JSON.stringify(url)}, nil)`);
+    }
+    for (const h of har.headers) {
+        lines.push(`    req.Header.Add(${JSON.stringify(h.name)}, ${JSON.stringify(h.value)})`);
+    }
+    lines.push(
+        ``,
+        `    res, _ := http.DefaultClient.Do(req)`,
+        `    defer res.Body.Close()`,
+        `    body, _ := io.ReadAll(res.Body)`,
+        `    fmt.Println(string(body))`,
+        `}`,
+    );
+    return lines.join('\n');
+}
+
+function renderPhp(har: HarRequest): string {
+    const lines: string[] = [`<?php`, ``, `$curl = curl_init();`, ``, `curl_setopt_array($curl, [`];
+    lines.push(`    CURLOPT_URL => ${JSON.stringify(fullUrl(har))},`);
+    lines.push(`    CURLOPT_RETURNTRANSFER => true,`);
+    lines.push(`    CURLOPT_CUSTOMREQUEST => ${JSON.stringify(har.method)},`);
+    if (har.postData?.text) {
+        lines.push(`    CURLOPT_POSTFIELDS => ${phpHeredoc(har.postData.text)},`);
+    }
+    if (har.headers.length) {
+        const headerList = har.headers
+            .map((h) => `        ${JSON.stringify(`${h.name}: ${h.value}`)}`)
+            .join(',\n');
+        lines.push(`    CURLOPT_HTTPHEADER => [\n${headerList},\n    ],`);
+    }
+    lines.push(`]);`, ``, `$response = curl_exec($curl);`, `curl_close($curl);`, `echo $response;`);
+    return lines.join('\n');
+}
+
+function renderRuby(har: HarRequest): string {
+    const lines: string[] = [
+        `require 'net/http'`,
+        `require 'uri'`,
+        `require 'json'`,
+        ``,
+        `uri = URI(${JSON.stringify(fullUrl(har))})`,
+        `http = Net::HTTP.new(uri.host, uri.port)`,
+        `http.use_ssl = uri.scheme == 'https'`,
+        ``,
+    ];
+    const methodClass = har.method.charAt(0) + har.method.slice(1).toLowerCase();
+    lines.push(`request = Net::HTTP::${methodClass}.new(uri)`);
+    for (const h of har.headers) {
+        lines.push(`request[${JSON.stringify(h.name)}] = ${JSON.stringify(h.value)}`);
+    }
+    if (har.postData?.text) {
+        lines.push(`request.body = ${rubyHeredoc(har.postData.text)}`);
+    }
+    lines.push(``, `response = http.request(request)`, `puts response.body`);
+    return lines.join('\n');
+}
+
+function renderJava(har: HarRequest): string {
+    const lines: string[] = [
+        `OkHttpClient client = new OkHttpClient();`,
+        ``,
+    ];
+    if (har.postData?.text) {
+        lines.push(
+            `MediaType mediaType = MediaType.parse("application/json");`,
+            `RequestBody body = RequestBody.create(mediaType, ${javaTextBlock(har.postData.text)});`,
+            ``,
+        );
+    }
+    lines.push(`Request request = new Request.Builder()`);
+    lines.push(`  .url(${JSON.stringify(fullUrl(har))})`);
+    if (har.postData?.text) {
+        lines.push(`  .method(${JSON.stringify(har.method)}, body)`);
+    } else {
+        lines.push(`  .method(${JSON.stringify(har.method)}, null)`);
+    }
+    for (const h of har.headers) {
+        lines.push(`  .addHeader(${JSON.stringify(h.name)}, ${JSON.stringify(h.value)})`);
+    }
+    lines.push(`  .build();`, ``, `Response response = client.newCall(request).execute();`);
+    return lines.join('\n');
+}
+
+const RENDERERS: Record<CodeSampleTargetId, (har: HarRequest) => string> = {
+    curl: renderCurl,
+    fetch: renderFetch,
+    axios: renderAxios,
+    python: renderPython,
+    go: renderGo,
+    php: renderPhp,
+    ruby: renderRuby,
+    java: renderJava,
+};
+
+export function renderSnippet(har: HarRequest, targetId: CodeSampleTargetId): string | null {
+    const renderer = RENDERERS[targetId];
+    if (!renderer) return null;
+    try {
+        return renderer(har);
+    } catch {
+        return null;
+    }
+}

package/src/tools/OpenapiViewer/utils/index.ts

@@ -5,7 +5,10 @@
  */
 
 export * from './apiKeyManager';
+export * from './codeSamples';
+export * from './operationToHar';
 export * from './versionManager';
 export * from './formatters';
+export * from './sampler';
 export * from './schemaExport';
 export * from './url';

package/src/tools/OpenapiViewer/utils/operationToHar.ts

@@ -0,0 +1,119 @@
+/**
+ * OpenAPI endpoint → HAR request.
+ *
+ * Our in-house code-sample renderers consume a HAR 1.2-shaped request.
+ * This module shapes an ``ApiEndpoint`` + user-provided parameter
+ * values into that form — path substitution, query-string assembly,
+ * header inference, body formatting.
+ *
+ * We keep the HAR intermediate (rather than a bespoke type) so the
+ * renderers match well-known HAR semantics and stay easy to extend.
+ */
+
+import type { ApiEndpoint } from '../types';
+
+/** HAR 1.2 request subset that our renderers consume. We don't ship
+ *  the full HAR type surface — just the fields that snippet generators
+ *  actually read. */
+export interface HarRequest {
+    method: string;
+    url: string;
+    httpVersion: string;
+    headers: Array<{ name: string; value: string }>;
+    queryString: Array<{ name: string; value: string }>;
+    cookies: Array<{ name: string; value: string }>;
+    headersSize: number;
+    bodySize: number;
+    postData?: {
+        mimeType: string;
+        text: string;
+    };
+}
+
+export interface BuildHarInput {
+    endpoint: ApiEndpoint;
+    /** Raw body string — whatever the user typed in the playground or
+     *  the pre-sampled example. Passed through verbatim; the caller
+     *  decides the content shape. */
+    body?: string;
+    /** Path-param + query-param values, keyed by name. We look up each
+     *  parameter on ``endpoint`` to decide whether it slots into the
+     *  path or the query string. */
+    parameters?: Record<string, string>;
+    /** Extra headers to merge in (e.g. ``X-API-Key``, ``Authorization``).
+     *  Later entries with the same name override earlier ones. */
+    headers?: Record<string, string>;
+    /** Override the request URL's base. When absent we use
+     *  ``endpoint.path`` as-is (extractor already prepended base URL). */
+    baseUrl?: string;
+}
+
+/** Split a template path into path vs query. Substitutes ``{id}``-style
+ *  placeholders using the provided parameter map; unused entries flow
+ *  into the query string. */
+function buildUrl(
+    endpoint: ApiEndpoint,
+    parameters: Record<string, string>,
+    baseUrl?: string,
+): { url: string; queryString: HarRequest['queryString'] } {
+    const pathParamNames = new Set(
+        (endpoint.parameters ?? [])
+            .filter((p) => endpoint.path.includes(`{${p.name}}`))
+            .map((p) => p.name),
+    );
+
+    let path = endpoint.path;
+    for (const name of pathParamNames) {
+        const value = parameters[name] ?? `{${name}}`;
+        path = path.replaceAll(`{${name}}`, encodeURIComponent(value));
+    }
+
+    const queryString: HarRequest['queryString'] = [];
+    for (const param of endpoint.parameters ?? []) {
+        if (pathParamNames.has(param.name)) continue;
+        const value = parameters[param.name];
+        if (value === undefined || value === '') continue;
+        queryString.push({ name: param.name, value });
+    }
+
+    const url = baseUrl ? `${baseUrl.replace(/\/+$/, '')}${path.startsWith('/') ? path : `/${path}`}` : path;
+    return { url, queryString };
+}
+
+/** Build a HAR 1.2 request from an API endpoint + current form values. */
+export function buildHarRequest(input: BuildHarInput): HarRequest {
+    const { endpoint, body, parameters = {}, headers = {}, baseUrl } = input;
+    const { url, queryString } = buildUrl(endpoint, parameters, baseUrl);
+
+    const hasBody = Boolean(body && body.trim().length > 0);
+    const bodyMime = hasBody
+        ? 'application/json'
+        : undefined;
+
+    // Merge headers. Caller wins, but we default Content-Type for bodies
+    // and Accept for JSON endpoints — snippet consumers expect these.
+    const mergedHeaders: Record<string, string> = {};
+    if (hasBody && bodyMime) mergedHeaders['Content-Type'] = bodyMime;
+    mergedHeaders['Accept'] = 'application/json';
+    for (const [k, v] of Object.entries(headers)) {
+        if (v === undefined || v === '') continue;
+        mergedHeaders[k] = v;
+    }
+
+    const har: HarRequest = {
+        method: endpoint.method.toUpperCase(),
+        url,
+        httpVersion: 'HTTP/1.1',
+        headers: Object.entries(mergedHeaders).map(([name, value]) => ({ name, value })),
+        queryString,
+        cookies: [],
+        headersSize: -1,
+        bodySize: hasBody ? new TextEncoder().encode(body!).length : 0,
+    };
+
+    if (hasBody && bodyMime) {
+        har.postData = { mimeType: bodyMime, text: body! };
+    }
+
+    return har;
+}

package/src/tools/OpenapiViewer/utils/sampler.ts

@@ -0,0 +1,72 @@
+/**
+ * JSON Schema → example JSON.
+ *
+ * Thin wrapper over ``openapi-sampler`` (by Redocly — same library Redoc
+ * uses internally). Picks deterministic, realistic values from a
+ * dereferenced schema: honours ``const`` / ``examples`` / ``enum`` /
+ * ``default``, unpacks ``allOf`` / ``oneOf`` / ``anyOf``, respects
+ * string ``format`` (email/uuid/date-time/…).
+ *
+ * Replaces the previous hand-rolled ``exampleFromSchema`` — stricter on
+ * spec semantics and cheaper to maintain.
+ */
+
+import consola from 'consola';
+import { sample as openapiSample } from 'openapi-sampler';
+
+type JsonSchemaLike = Record<string, unknown>;
+
+export interface SampleOptions {
+    /** Skip properties marked ``readOnly`` — useful when the body will
+     *  be sent in a request (request body editor). Default ``false``. */
+    skipReadOnly?: boolean;
+    /** Skip properties marked ``writeOnly`` — useful when rendering a
+     *  response body (passwords etc. must not leak). Default ``false``. */
+    skipWriteOnly?: boolean;
+    /** Skip non-required properties. Rarely useful for a viewer — we
+     *  want to show the full shape. Default ``false``. */
+    skipNonRequired?: boolean;
+}
+
+/** Sample a JSON schema into a plain value. Returns ``null`` on failure
+ *  (malformed schema, circular refs the sampler can't unwind) so the
+ *  caller can show "no example" instead of crashing the page.
+ *
+ *  ``spec`` must be the root OpenAPI document whenever ``schema`` may
+ *  contain ``$ref`` nodes — ``openapi-sampler`` walks the tree and
+ *  resolves refs against it. Our own ``dereferenceSchema`` only inlines
+ *  refs up to a depth limit; anything deeper comes through here as a
+ *  live ``$ref`` and the sampler throws if ``spec`` is missing. */
+export function sampleSchema(
+    schema: JsonSchemaLike | undefined,
+    options: SampleOptions = {},
+    spec?: unknown,
+): unknown {
+    if (!schema) return null;
+    try {
+        return openapiSample(schema as never, options, spec as never);
+    } catch (err) {
+        // Sampler failures used to be silent, which meant "no example"
+        // in the UI looked like a missing spec entry. Log so we can see
+        // the real cause in dev (circular refs, missing type, etc.).
+        consola.warn('[OpenapiViewer] sampleSchema failed:', err, { schema });
+        return null;
+    }
+}
+
+/** Same as ``sampleSchema`` but returns a pre-stringified JSON payload
+ *  ready to drop into a textarea / code block. Returns ``undefined``
+ *  when sampling fails so the UI can conditionally hide the example. */
+export function sampleSchemaJson(
+    schema: JsonSchemaLike | undefined,
+    options: SampleOptions = {},
+    spec?: unknown,
+): string | undefined {
+    const value = sampleSchema(schema, options, spec);
+    if (value === null || value === undefined) return undefined;
+    try {
+        return JSON.stringify(value, null, 2);
+    } catch {
+        return undefined;
+    }
+}

package/src/tools/OpenapiViewer/utils/scrollParent.ts

@@ -0,0 +1,68 @@
+/**
+ * Find the nearest ancestor that actually scrolls vertically, or
+ * ``window`` when none exists. Handles the common embed scenarios:
+ *
+ * - Standalone page: nothing in the chain scrolls → caller scrolls
+ *   ``window`` and listens to ``window.scroll``.
+ * - Dev playground / modal shell: an intermediate ``overflow-auto``
+ *   container scrolls → caller scrolls that element and listens to
+ *   *its* ``scroll`` events (which do NOT bubble to window).
+ *
+ * A "scrollable" ancestor is one whose computed ``overflow-y`` is
+ * ``auto`` or ``scroll`` AND whose content actually overflows. We bail
+ * before ``document.body`` — ``documentElement`` is represented by
+ * ``window`` in the caller's hot path, so returning the body itself
+ * would double-count the scroll surface.
+ */
+export type ScrollTarget = HTMLElement | Window;
+
+export function getScrollParent(el: HTMLElement | null): ScrollTarget {
+    if (typeof window === 'undefined') return (null as unknown) as Window;
+    if (!el) return window;
+
+    let cur: HTMLElement | null = el.parentElement;
+    while (cur && cur !== document.body && cur !== document.documentElement) {
+        const style = getComputedStyle(cur);
+        const overflowY = style.overflowY;
+        const canScroll =
+            (overflowY === 'auto' || overflowY === 'scroll' || overflowY === 'overlay') &&
+            cur.scrollHeight > cur.clientHeight;
+        if (canScroll) return cur;
+        cur = cur.parentElement;
+    }
+    return window;
+}
+
+/** Top-relative scroll position of the target. */
+export function getScrollTop(target: ScrollTarget): number {
+    return target === window ? window.scrollY : (target as HTMLElement).scrollTop;
+}
+
+/** Visible viewport height of the target. */
+export function getViewportHeight(target: ScrollTarget): number {
+    return target === window ? window.innerHeight : (target as HTMLElement).clientHeight;
+}
+
+/** Y coordinate of the target's top edge, in viewport space. Used to
+ *  translate ``getBoundingClientRect().top`` into target-relative
+ *  coordinates. For ``window`` this is always ``0``. */
+export function getTargetTop(target: ScrollTarget): number {
+    return target === window ? 0 : (target as HTMLElement).getBoundingClientRect().top;
+}
+
+/** Scroll the target so that the given absolute Y lands at its top.
+ *
+ *  For ``window`` we ask the browser to animate smoothly — every engine
+ *  honours that path. Nested ``overflow-auto`` elements are a different
+ *  story: some layouts (e.g. dev-playground shells with flex parents)
+ *  silently drop the animation, leaving the user stuck. Direct
+ *  ``scrollTop`` writes always work, so we use them there — loss of
+ *  animation beats broken navigation. Consumers who want animated
+ *  scrolling inside a custom shell can wrap this function themselves. */
+export function scrollTargetTo(target: ScrollTarget, top: number) {
+    if (target === window) {
+        window.scrollTo({ top, behavior: 'smooth' });
+        return;
+    }
+    (target as HTMLElement).scrollTop = top;
+}

package/src/tools/PrettyCode/PrettyCode.client.tsx

@@ -8,6 +8,13 @@ import { useResolvedTheme } from '@djangocfg/ui-core/hooks';
 import { FloatingToolbar } from '../../components/FloatingToolbar';
 import { CopyAction } from '../../components/FloatingToolbar/actions';
 
+// Load extra Prism grammars (``bash``, ``ruby``, ``java``, ``php``)
+// that aren't in ``prism-react-renderer``'s default bundle. The hook
+// below subscribes to its ready state and re-renders this component
+// once loading completes, so the first tab click gets highlighted
+// correctly even if it happened before the dynamic import resolved.
+import { useEnsurePrismLanguages } from './registerPrismLanguages';
+
 interface PrettyCodeProps {
   data: string | object;
   language: Language;
@@ -23,13 +30,24 @@ interface PrettyCodeProps {
    * Set e.g. ``50`` to cap short snippets inline and scroll long ones.
    */
   maxLines?: number;
+  /**
+   * Visual variant. ``"card"`` (default) ships full chrome (border,
+   * background, hover toolbar, optional internal scroll). ``"plain"``
+   * is chrome-less — use when embedding inside another scroll
+   * container so the surface manages its own chrome and scroll. */
+  variant?: 'card' | 'plain';
 }
 
-const PrettyCode = ({ data, language, className, mode, inline = false, customBg, isCompact = false, scrollIsolation, maxLines }: PrettyCodeProps) => {
+const PrettyCode = ({ data, language, className, mode, inline = false, customBg, isCompact = false, scrollIsolation, maxLines, variant = 'card' }: PrettyCodeProps) => {
   const containerRef = useRef<HTMLDivElement>(null);
   const t = useAppT();
   const detectedTheme = useResolvedTheme();
 
+  // Subscribe to the extra-grammars ready state. When ``bash`` /
+  // ``ruby`` / ``java`` / ``php`` finish loading, this hook triggers a
+  // re-render so the code block picks up the new grammar.
+  useEnsurePrismLanguages();
+
   const labels = useMemo(() => ({
     copyCode: t('tools.code.copyCode'),
     noContent: t('tools.code.noContent'),
@@ -110,6 +128,16 @@ const PrettyCode = ({ data, language, className, mode, inline = false, customBg,
         return 'Text';
       case 'mermaid':
         return 'Mermaid';
+      case 'ruby':
+      case 'rb':
+        return 'Ruby';
+      case 'java':
+        return 'Java';
+      case 'php':
+        return 'PHP';
+      case 'go':
+      case 'golang':
+        return 'Go';
       default:
         return lang.charAt(0).toUpperCase() + lang.slice(1);
     }
@@ -140,7 +168,18 @@ const PrettyCode = ({ data, language, className, mode, inline = false, customBg,
         return 'markup';
       case 'bash':
       case 'shell':
+      case 'sh':
         return 'bash';
+      case 'ruby':
+      case 'rb':
+        return 'ruby';
+      case 'java':
+        return 'java';
+      case 'php':
+        return 'php';
+      case 'go':
+      case 'golang':
+        return 'go';
       case 'sql':
         return 'sql';
       case 'yaml':
@@ -160,6 +199,54 @@ const PrettyCode = ({ data, language, className, mode, inline = false, customBg,
 
   const displayLanguage = getLanguageDisplayName(language);
 
+  // Plain variant — chrome-less render for embedding inside other
+  // scroll containers. No border, no background, no hover toolbar, no
+  // internal scroll. The caller's ScrollArea/panel owns the chrome
+  // and scroll responsibilities.
+  if (variant === 'plain') {
+    return (
+      <Highlight theme={prismTheme} code={contentJson} language={normalizedLanguage as Language}>
+        {({ className: prismClassName, style, tokens, getLineProps, getTokenProps }) => {
+          const { backgroundColor: _bg, ...restStyle } = style;
+          return (
+            <pre
+              className={`${prismClassName} ${className || ''}`}
+              style={{
+                ...restStyle,
+                background: 'transparent',
+                margin: 0,
+                padding: isCompact ? '0.75rem 1rem' : '1rem',
+                fontSize,
+                lineHeight: lineHeightRatio,
+                fontFamily: 'monospace',
+                // ``break-all`` (not ``break-word``) so long unbroken
+                // strings without whitespace — typical of escaped
+                // JSON bodies in generated code samples — wrap at any
+                // character rather than overflowing the container.
+                whiteSpace: 'pre-wrap',
+                wordBreak: 'break-all',
+                overflowWrap: 'anywhere',
+                // Hard cap on width — parents (grid cells, panels)
+                // should constrain us but some callers render inside
+                // ``flex: 1 1 auto`` which lets the pre grow past
+                // intended bounds. ``max-width: 100%`` pins to parent.
+                maxWidth: '100%',
+              }}
+            >
+              {tokens.map((line, i) => (
+                <div key={i} {...getLineProps({ line })}>
+                  {line.map((token, key) => (
+                    <span key={key} {...getTokenProps({ token })} />
+                  ))}
+                </div>
+              ))}
+            </pre>
+          );
+        }}
+      </Highlight>
+    );
+  }
+
   if (inline) {
     const inlineBgClass = customBg || (isDarkMode ? 'bg-zinc-800' : 'bg-zinc-100');
     return (