feat(ui-rewrite): POC Code tab + Preview for prompt details (#5448)

[a-effort]

Summary

• POC implementation of the Code tab and render-only Preview action for the prompt details drawer. Design
• Designed to drop into [UI-REWRITE]: Add prompt details drawer #5323's drawer as <PromptCodeTab prompt={selected} />; single prop, no callbacks, no drawer knowledge.
• The mount on the Prompts page (src/pages/Prompts.tsx) is temporary so the prototype can be exercised against the live gateway; remove it when [UI-REWRITE]: Add prompt details drawer #5323's drawer lands.

What this does for users

Serves developers wiring a gateway prompt into agents, MCP clients, or scripts. Today they reverse-engineer the wire format from the Template and Arguments blocks. This branch ships:

• Four-tab snippet view (curl, JSON-RPC, Python, TypeScript), each pre-filled with the prompt name and current argument values, each with a copy button. Paste-and-go for the most common call paths.
• Render-only Preview action that hits POST /prompts/{id}. Runs the plugin pipeline, returns the templated MCP messages array, and does not invoke an LLM. Status row reports HTTP code and client-measured render time. Re-run replays with whatever args are currently in the form.
• Controlled args form driven by the prompt's declared arguments schema, with required/optional badges and inline descriptions. The same args object feeds both the snippets and the Preview request, so what the user sees in the snippet is what gets sent.

The existing LLM-execution Test modal is unchanged. Preview complements it for the "what bytes do I send" question.

Technical notes

Public seam: <PromptCodeTab prompt={NonNullable<PromptRead>} />. The #5323 engineer drops it into a TabsContent slot.

Composition under the seam:

• PromptArgsForm (controlled, full-record emission on every change; null-safe over the orval (PromptArgument | null)[] array shape)
• PromptSnippetTabs with an actions slot for the trailing Preview button
• usePromptPreview(promptId, args) owns request lifecycle, performance.now() timing, ApiError.body.detail unwrap, sonner error toast
• PromptPreviewButton and PromptPreviewResult consume the hook independently so the trigger can live on the tab row while status and response render below

Snippet builders are pure functions of { promptName, args } exported individually (buildCurl, buildJsonRpc, buildPython, buildTypescript). 19-test escape-safety matrix covers double quotes, backslashes, newlines, dollar-sign literals (verified not shell-expanded inside single-quoted curl bodies), and apostrophes (bash '\'' escape). URL and bearer token are referenced as \$MCPGATEWAY_URL and \$MCPGATEWAY_BEARER_TOKEN literals.

API surface: new src/api/prompts.ts with promptsApi.render(id, args) going through the local api client rather than the orval-generated fetcher. Preserves cookie auth, CSRF header forwarding, and the 401-to-login redirect. ID validation regex mirrors validateToolId in tools.ts. Local RenderedPrompt type narrows the orval unknown response.

Shared primitives:

• src/components/ui/tabs.tsx is a new radix Tabs wrapper, styled to match the plain-text tab row pattern used in MCPServerDetailsPanel.tsx (gap-6, text-foreground active, text-muted-foreground hover:text-foreground inactive). Both this branch and [UI-REWRITE]: Add prompt details drawer #5323's Code|Definition row use it.
• src/components/ui/code-block.tsx wraps prism-react-renderer (added dependency, vsDark theme) for bash, json, python, tsx. Always-dark in both light and dark UI modes. Optional Copy affordance.

Token-level styling changes (intentional global):

• Button size=\"sm\" updated to p-2 gap-1.5 rounded-sm to match the design spec. Affects ~31 existing call sites; sharper corners and slightly tighter padding. Height held at h-8 so vertical row alignment in forms and drawers does not shift.
• Button variant=\"outline\" no longer renders bg-background, shadow-xs, or dark:bg-input/30 in the idle state. Border-only until hover. aria-expanded fill retained for dropdown triggers.

i18n under prompts.details.code.* and prompts.details.preview.* across en-US, es-ES, pt-BR. Spanish and Portuguese translations included; native review pending before ship.

Bundle impact: prism-react-renderer ^2.4.1 adds about 85 KB raw / 57 KB gzipped to the vendor chunk.

Tests: 1674 client tests pass, tsc -b clean, production build clean. New coverage includes 19 snippet-builder cases, hook lifecycle, button state transitions, result rendering for success and failure, and integration tests confirming arg-form keystrokes flow into the active snippet via prism's tokenized DOM.

Production CSRF posture: verified end-to-end. Login at /app/auth/login (routers/app.py:135) sets both auth and CSRF cookies on path /. The api client (client.ts:106) reads the cookie on every mutating request and forwards it as X-CSRF-Token. Same-origin guaranteed by vite.config.ts shipping the bundle under /static/app/ on the gateway itself. 401 path triggers redirect-to-login. No additional code needed.

Deliberately out of scope (carried as inline TODOs)

• Plugin-pass count in the status row: pending a backend response field. Layout scaffold in place, wiring is one line.
• Preview invocation tagging (header vs /preview sibling route): open question on the issue; isolated to promptsApi.render so the swap is a one-file change later.
• RBAC gate on the Preview button: deferred until a usePermission hook lands in the rewrite.
• Syntax-highlighting fidelity polish (currently vsDark; per-token color overrides could be added as a next step).

Related

• Slots into [UI-REWRITE]: Add prompt details drawer #5323

[a-effort]

This is a POC for prompt details drawer "preview" functionality (temp location: won't be an in page option in Prompts)

preview.mp4

[marekdano]

Clean POC for the prompt Code tab that will slot into the #5323 drawer. I'm happy with the flow and implementation.

Just a few findings:

Stale preview state when prompt changes (bug)

usePromptPreview never resets result/error/hasRun when promptId changes. PromptCodeTab resets args on prompt.id change via useEffect, but the preview hook holds its own state independently:

// PromptCodeTab.tsx — args are reset, but preview result is not
useEffect(() => {
  setArgs(seedArgs(prompt));
}, [prompt.id]);  // preview.result from the old prompt is still shown

If a user previews prompt A then switches to prompt B, they'll see prompt A's result until they click Preview again. Add a reset effect in the hook, or force remount via <PromptCodeTab key={prompt.id} prompt={prompt} />.

---

Inconsistency: snippets use prompt.name, Preview API uses prompt.id

PromptSnippetTabs receives prompt.name and generates URLs like /prompts/greet_user, while usePromptPreview(prompt.id, args) calls /prompts/p1. If the backend only accepts one form (ID vs slug), users copying a snippet could get 404s. Verify the backend accepts both, or unify the identifier used across snippets and the API call.

---

CodeBlock couples a generic UI component to prompt-specific i18n and gateway internals

src/components/ui/code-block.tsx imports from two places it shouldn't:

• import { copyToClipboard } from "@/components/gateways/utils" — a ui/ component shouldn't depend on a gateways/ utility.
• The copy toast hardcodes "prompts.details.code.copySuccess" — if CodeBlock is reused for tool or resource details, the toast will say "Copied curl snippet" incorrectly.

The copy callback and toast message should be caller-supplied (e.g. onCopy?: () => void) or the i18n key should be a prop.

---

promptName in snippets is not validated

validatePromptId guards the API call, but promptName (from prompt.name) flows directly into snippet strings without validation. A prompt whose name contains backticks would produce a malformed TypeScript snippet. Assert promptName matches the same [a-zA-Z0-9_-]+ pattern before passing it to builders.

---

Suggestions

args ?? {} is dead code in snippet builders — SnippetInput.args is typed Record<string, string> (non-nullable). The ?? {} fallbacks in buildCurl, buildPython, and buildTypescript can't fire. Remove them.

[a-effort]

Thanks for the review @marekdano! Feedback addressed in two commits:

• 8e5961527 fix(ui-rewrite): address review on prompt Code tab
• 75bbcf594 fix(ui-rewrite): unify prompt Preview and snippets on prompt.name

Stale preview state on prompt change: fixed in 8e59615. Reset moved into usePromptPreview via a useEffect keyed on the identifier, colocating it with the state that owns it. key={prompt.id} remounting was avoided since it would drop memoization in PromptArgsForm/PromptSnippetTabs during mid-typing edits. Regression test added.

CodeBlock coupling: fixed in 8e59615. copyToClipboard moved to lib/clipboard.ts (six call sites repointed). CodeBlock no longer imports sonner/react-intl or references prompt-domain i18n; it now exposes onCopy?: (code: string) => void, and PromptSnippetTabs owns the toast.

promptName not validated: fixed in 8e59615 and 75bbcf5. URL encoding used instead of regex validation, since the backend's name pattern (space/dot/dash allowed via SecurityValidator.NAME_PATTERN) is wider than the old validatePromptId. encodeURIComponent(promptName) added in buildCurl/buildPython/buildTypescript; JSON-RPC already escapes correctly as a field value. Tests added in builders.test.ts.

Snippets use prompt.name, Preview uses prompt.id: resolved in 75bbcf5 by unifying on prompt.name. Good catch: the endpoint accepts either (_find_prompt_by_name_or_id), so it was never a 404 risk, but the two call sites should agree. Went with name because:

1. MCP clients call prompts/get(name). There's no prompt ID at the MCP layer, so name-based snippets teach the correct pattern.
2. The [MCP RC blog post](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/) adds an Mcp-Name header as a wire field; staying name-shaped keeps today's URL and tomorrow's header the same reference.
3. The ambiguity path (422 when a name collides across scopes) surfaces through the existing toast, same as a copy-paste integrator would hit.

Also in 75bbcf5: usePromptPreview(promptName, args) param rename, validatePromptId renamed to validatePromptName with the widened regex, and JSDoc on promptsApi.render covering the acceptance semantics and ambiguity case. Routing Preview/snippets through the server-scoped MCP transport is a larger change (needs server context on the Prompts page); will track separately.

args ?? {} dead code: removed across all four builders (8e59615). SnippetInput.args is non-nullable, so the fallback was unreachable.

void _lineKey;: removed (8e59615); added _-prefix ignore pattern to client/eslint.config.js so the convention is enforced without the workaround.

extractBracedLiteral \" edge case: left as-is, with an inline comment noting the limitation and the two-state-lexer upgrade path for anyone extending TRICKY_ARGS.

[marekdano]

All findings from the previous review are addressed correctly!

LGTM 🚀 after fixing DCO check

[marekdano]

The PR can be merged when the conflicts are resolved, and all CI checks pass.