Add structured preview for markdown customizations

[OrenMe]

Introduce a structured detail preview for markdown-backed customization files in the AI customization management editor. Changes include:

• Docs: document the structured preview behavior in AI_CUSTOMIZATIONS.md.
• Editor: add preview containers, front-matter/body rendering, issue rendering, a preview/raw toggle button and state, scheduling for re-render, accessibility labels, focus handling, and save status announcements. Integrate PromptFileParser, attribute definitions, and markdown renderer to build the preview. Support readonly/builtin edit rules and fall back to raw editor when unsupported.
• CSS: add styles for the editor mode button, preview layout, front-matter rows, issue box and rendered body, and various accessibility/UX tweaks.
• Tests & fixtures: add unit tests for editor preview/help behavior and update component fixtures to produce realistic prompt file contents, mock markdown rendering, model creation, and new screenshot fixtures for preview/raw scenarios.

Overall this enables a user-friendly, structured view of front-matter and rendered markdown while preserving the ability to view/edit the raw source when needed.

ai_customizations_markdown_preview.mp4

Solves #312544

Original prompt

The plan request:

the ui customization file viewer shows raw md file as text, plan a modified view where front matter is shown in dedicated view with per field click question mark showing hover explainer of field
The body will be shown as markdown and add ability to edit the file as raw on click edit
reuse as much of the existing UI framework and utilities and consult before adding any new depedendecy

The Plan.md

## Plan: Structured Customization Preview

Replace the current raw-markdown-only detail pane in the AI Customizations editor with a preview-first viewer for markdown customization files. Front matter should render as structured labeled rows with per-field help hovers sourced from existing prompt metadata, the body should render as markdown, and raw editing should remain available only through an explicit Edit/Raw toggle using the existing embedded editor. Reuse the current parser, metadata definitions, hover service, markdown renderer, and editor widget; do not add any new dependency unless explicitly re-approved.

**Status**
- Approved for implementation on 2026-04-25.
- Next step: hand off to an implementation agent to apply the changes and run validation.

- User requested full implementation, automation-based verification, and screenshots in the next step.
- Current session remains in planning mode, so implementation must continue in a coding-capable handoff/session.


**Steps**
1. Verify the current detail-pane flow and fixture baseline in `/Users/orenmelamed/code/vscode/src/vs/workbench/contrib/chat/browser/aiCustomization/aiCustomizationManagementEditor.ts`, `/Users/orenmelamed/code/vscode/src/vs/workbench/contrib/chat/browser/aiCustomization/media/aiCustomizationManagement.css`, `/Users/orenmelamed/code/vscode/src/vs/workbench/test/browser/componentFixtures/sessions/aiCustomizationManagementEditor.fixture.ts`, and `/Users/orenmelamed/code/vscode/src/vs/sessions/AI_CUSTOMIZATIONS.md`; keep Hooks, MCP, and Plugins explicitly out of scope.
2. In `/Users/orenmelamed/code/vscode/src/vs/workbench/contrib/chat/browser/aiCustomization/aiCustomizationManagementEditor.ts`, add a secondary editor display state such as `preview | raw` for markdown customization files while preserving the existing top-level `viewMode: 'list' | 'editor' | 'mcpDetail' | 'pluginDetail'`. Default to `preview` whenever a markdown customization file is opened. *Blocks steps 3–8.*
3. Extend the existing `.editor-content-container` instead of replacing the editor architecture: keep the current header/back/save area, add an Edit/Raw toggle in the header, and conditionally show either a new structured preview subtree or the existing `CodeEditorWidget`. *Depends on 2.*
4. Populate the preview from the current model using `IPromptsService.getParsedPromptFile(textModel)` / `PromptFileParser` results:
   - render front matter from `header.attributes` in file order
   - render the body via `body.getContent()` as markdown
   - surface `header.errors` as a compact warning/error state with a clear Raw/Edit path
   - if a file has no front matter, still show the markdown body and an empty-state for metadata instead of dropping straight to raw mode. *Depends on 3.*
5. Reuse existing prompt metadata for field explainers by resolving target/type with `getTarget(...)` and descriptions with `getAttributeDefinition(...)`; attach a keyboard-focusable question-mark/info button per field via `IHoverService.setupManagedHover(...)`, with localized `aria-label`s and a generic fallback for unknown fields. *Parallel with step 4 after step 3.*
6. Preserve current editability semantics in raw mode:
   - workspace/user files stay editable in place through the current `CodeEditorWidget`
   - built-in prompt/skill overrides keep the existing in-memory session + save-override flow
   - extension/plugin items remain read-only; expose “View Raw” instead of “Edit” if needed
   - switching back from raw mode to preview reparses and rerenders the latest model text rather than trying to build two-way structured editing in v1. *Depends on 3 and informed by 4–5.*
7. Add layout/styling in `/Users/orenmelamed/code/vscode/src/vs/workbench/contrib/chat/browser/aiCustomization/media/aiCustomizationManagement.css` for the preview container: front matter rows/cards, label/value alignment, help icon placement, markdown body region, error/empty states, and a responsive header toggle that still works in narrow widths. *Depends on 3.*
8. Extend `/Users/orenmelamed/code/vscode/src/vs/workbench/test/browser/componentFixtures/sessions/aiCustomizationManagementEditor.fixture.ts` to cover the new detail viewer and raw-toggle path, reusing its existing `openFirstItem` flow and stubbed `IMarkdownRendererService`. Add at least one preview fixture and one raw-mode fixture for a markdown customization type; if the preview layout becomes critical, promote the most representative fixture to CI-blocking coverage. *Parallel with step 7 after step 3.*
9. Update `/Users/orenmelamed/code/vscode/src/vs/sessions/AI_CUSTOMIZATIONS.md` to document the preview-first viewer, raw-edit fallback, and the reuse of prompt metadata/markdown services so future changes stay aligned. *After implementation.*

**Relevant files**
- `/Users/orenmelamed/code/vscode/src/vs/workbench/contrib/chat/browser/aiCustomization/aiCustomizationManagementEditor.ts` — main integration point; owns `createEmbeddedEditor()`, `showEmbeddedEditor()`, `goBackToList()`, `updateContentVisibility()`, and the editor header/state.
- `/Users/orenmelamed/code/vscode/src/vs/workbench/contrib/chat/browser/aiCustomization/media/aiCustomizationManagement.css` — current editor container/header/editor styling to extend with preview layout.
- `/Users/orenmelamed/code/vscode/src/vs/workbench/contrib/chat/common/promptSyntax/promptFileParser.ts` — source of `ParsedPromptFile`, `PromptHeader.attributes`, `PromptHeader.errors`, and `PromptBody.getContent()`.
- `/Users/orenmelamed/code/vscode/src/vs/workbench/contrib/chat/common/promptSyntax/languageProviders/promptFileAttributes.ts` — `getAttributeDefinition(...)` and `getTarget(...)` provide target-aware field descriptions and should remain the single source of truth for hover explainers.
- `/Users/orenmelamed/code/vscode/src/vs/workbench/contrib/chat/common/promptSyntax/languageProviders/promptHovers.ts` — reference pattern showing those attribute descriptions are already reused for editor hovers.
- `/Users/orenmelamed/code/vscode/src/vs/platform/markdown/browser/markdownRenderer.ts` — `IMarkdownRendererService` to render the markdown body with existing workbench infrastructure.
- `/Users/orenmelamed/code/vscode/src/vs/workbench/test/browser/componentFixtures/sessions/aiCustomizationManagementEditor.fixture.ts` — existing screenshot/component fixture seam with `selectedSection`, `openFirstItem`, and markdown renderer stubbing.
- `/Users/orenmelamed/code/vscode/src/vs/sessions/AI_CUSTOMIZATIONS.md` — required spec update per the customization-editor skill.

**Verification**
1. Check the `VS Code - Build` task output for compile/type errors after wiring in `IMarkdownRendererService` and any new preview helper logic.
2. Exercise the management editor fixture with an opened markdown customization item in preview mode and raw mode; verify front matter rows, help-icon hovers, markdown body rendering, and the expected read-only/editable labeling.
3. Manually verify Agents, Skills, Instructions, and Prompts across at least one editable workspace/user file and one built-in or read-only file:
   - preview opens by default
   - Edit/Raw toggles to the existing editor
   - existing back/save behavior still works
   - returning to preview reflects raw edits after reparsing.
4. Run hygiene/layer validation appropriate to the touched files, especially if new imports are added into the workbench/chat layer.
5. Smoke-test keyboard and accessibility behavior: tab order reaches the header toggle and per-field help buttons, icon-only controls have localized labels, and hover content is reachable from keyboard focus.

**Decisions**
- Included scope: Agents, Skills, Instructions, and Prompts that are markdown/front-matter-based customization files.
- Excluded scope: Hooks, MCP server detail, plugin detail, and inline structured editing of front matter fields.
- Default UX: preview-first viewer; raw mode is explicit and is the only editing surface in v1.
- Dependency rule: reuse existing services/utilities only (`IPromptsService`, `PromptFileParser`, `getAttributeDefinition`, `IMarkdownRendererService`, `IHoverService`, `CodeEditorWidget`). If a new dependency appears necessary, pause and consult before adding it.

**Further Considerations**
1. For invalid YAML/front matter, prefer best-effort preview plus a compact warning state instead of auto-falling back to raw mode.
2. For extension/plugin read-only files, prefer “View Raw” wording instead of “Edit” to preserve current permission semantics and avoid a misleading affordance.

Also ran 3 sub agents with diff model review for a few more small fixes at the end

[Copilot]

Pull request overview

Adds a structured “Preview” mode to the AI Customizations management editor for markdown-backed customization files, showing parsed front matter + rendered markdown body, with a toggle to switch to the raw editor/viewer.

Changes:

• Implement structured preview UI in AICustomizationManagementEditor (front matter rows, help hovers, issues rendering, markdown body rendering, preview/raw toggle, focus + save announcements).
• Add editor/preview styling to aiCustomizationManagement.css.
• Add unit tests + fixture updates to exercise preview/help behavior and generate realistic screenshot fixtures; document behavior in AI_CUSTOMIZATIONS.md.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/vs/workbench/test/browser/componentFixtures/sessions/aiCustomizationManagementEditor.fixture.ts	Updates fixtures/mocks to supply parsed prompt content + markdown rendering for preview/raw screenshot states.
src/vs/workbench/contrib/chat/test/browser/aiCustomization/aiCustomizationManagementEditor.test.ts	Adds unit coverage for mode button copy rules and preview help hover behavior.
src/vs/workbench/contrib/chat/browser/aiCustomization/media/aiCustomizationManagement.css	Adds styles for preview layout and the preview/raw toggle button.
src/vs/workbench/contrib/chat/browser/aiCustomization/aiCustomizationManagementEditor.ts	Core implementation of structured preview, toggle state, debounced re-rendering, focus handling, and save status announcements.
src/vs/sessions/AI_CUSTOMIZATIONS.md	Documents the structured detail preview behavior and components used.

[vs-code-engineering]

This feature request is now a candidate for our backlog. The community has 60 days to upvote the issue. If it receives 20 upvotes we will move it to our backlog. If not, we will close it. To learn more about how we handle feature requests, please see our documentation.

Happy Coding!

[joshspicer]

Thank you, this looks awesome! Looks like I introduced some merge conflicts earlier today (which I have Opus on). Other than that I am ready to merge it 🚀