feat(FR-2907): add matte + natural-size cap for doc images, tighten capture guidance

- markdown-processor-web.ts: emit max-width=(pixel_width × 0.5) from PNG
  header so 2× zoom captures display at intended CSS size. Mirrors the
  PDF auto-scale logic. Explicit ![alt =<w>](url) size hints still win.
- styles-web.ts / styles.ts: move border/radius/shadow from .doc-image
  (img) to figure.doc-figure (wrapper); add padding + neutral background
  so the wrapper acts as a matte. Element-level captures with content
  flush to the PNG edges now have visible breathing room without any
  recapture. Cards/modals with their own rounded corners no longer
  compete with a second outer radius.
- markdown-processor.ts: export getImageDimensions + IMAGE_SCALE_FACTOR
  so the web renderer can reuse the PDF dimension/scale helpers.
- SCREENSHOT-GUIDELINES.md: document the matte, the renderer-side
  auto size cap, the parent-container-preferred rule, and the
  small-element rule (≤ 600 CSS px).
- docs-screenshot-capturer.md: prompt update — capture raw elements
  and let the matte frame them, prefer parent containers, handle
  small widgets via auto-cap or browser_evaluate repositioning.

Author: yomybaby

.claude/agents/docs-screenshot-capturer.md

@@ -129,6 +129,42 @@ Open the browser and log in:
 - Full-page captures only for page overview screenshots
 - Use `browser_snapshot` to find the correct `ref` for the element you want to capture
 - When UI has icon-only buttons, **always verify the button's accessible name** in the snapshot before clicking — e.g., "trash bin" vs download icon can look similar
+- **Do NOT bake padding into the screenshot.** The docs renderer adds a matte (padding + soft background + outer border + radius) around every captured image, so an element-level capture with content flush to the PNG edges still has visible breathing room in the docs. Capture the raw element; let the matte frame it.
+- **Do NOT try to "fix" the inner-vs-outer border-radius mismatch at capture time.** Inside the matte, the inner `<img>` is bare — the matte owns the only outer radius, so a screenshot of a card/modal with its own rounded corners sits cleanly on the matte instead of competing with a second radius.
+
+**Parent-container-preferred rule (modals, dialogs, panels):**
+
+Climb one DOM level whenever picking the tightest element would produce a cramped capture:
+
+- Modal/dialog: prefer `.ant-modal-wrap` (the wrapper) over `.ant-modal` (the dialog itself). Use the inner element only when the dialog is large enough that its own padding already gives the captured content breathing room.
+- Card / wizard step: prefer the containing `<section>` / panel over the tight card.
+- Toolbar / form row: prefer the panel that the row lives inside, not the row itself.
+
+The matte adds outer padding regardless, so picking the parent costs nothing visually but lets the capture pick up the application's intra-component spacing (and avoids clipping floating elements that overflow the inner element, like dropdown indicators or focus rings).
+
+**Small-element rule (≤ 600 CSS px in either dimension):**
+
+For tiny widgets — notifications, badges, button rows, toasts, status pills — pick one of two paths:
+
+1. **Capture as-is and trust the renderer's auto size cap.** The web/PDF renderers read the PNG header and cap the display width at `pixel_width × 0.5` (the 2× zoom convention from SCREENSHOT-GUIDELINES). A 760×190 notification renders at ~380 CSS px wide on web and PDF, framed by the matte. This is usually correct.
+2. **Reposition with `browser_evaluate` for a deliberately larger capture** when the auto-capped display feels too small for the surrounding documentation context. Apply temporary CSS to move the widget to the viewport center with extra padding around it, then capture, then reset the style. Example:
+   ```js
+   () => {
+     const el = document.querySelector('.target-notification');
+     el.dataset.originalStyle = el.getAttribute('style') ?? '';
+     el.style.cssText += 'position: fixed; top: 50%; left: 50%; transform: translate(-50%, -50%); padding: 32px; background: var(--bai-bg-muted); z-index: 9999;';
+     return 'ok';
+   }
+   // …take screenshot…
+   () => {
+     const el = document.querySelector('.target-notification');
+     el.setAttribute('style', el.dataset.originalStyle ?? '');
+     delete el.dataset.originalStyle;
+     return 'ok';
+   }
+   ```
+
+Default to path 1. Use path 2 only when you have a specific reason to fill more of the column.
 
 **Re-capture preflight (when overwriting an existing screenshot):**
 
@@ -141,9 +177,10 @@ The filename of an existing screenshot encodes a contract about what it shows. S
    ```
 2. Open `/tmp/old.png` and identify its scope:
    - Header strip: very wide, ≤300 px tall (e.g., 2358×222) → use `ref` of `[data-testid="webui-header"]`
-   - Modal/dialog only: medium, no chrome (e.g., 988×804) → use `ref` of `.ant-modal-wrap .ant-modal` or `[role="dialog"]`
+   - Modal/dialog: medium, no chrome (e.g., 988×804) → prefer `ref` of `.ant-modal-wrap` (parent-container rule) and fall back to `.ant-modal-wrap .ant-modal` / `[role="dialog"]` only when the dialog has enough internal padding
    - Sidebar segment: narrow column → use `ref` of `.ant-layout-sider`
    - Wizard step / panel: capture the specific panel `ref`, not the layout root
+   - Small widget (≤ 600 px / notification / badge / button row) → see **Small-element rule** above
    - Full page (~viewport × viewport): `fullPage: true` is acceptable
 3. After capture, sanity-check dimensions match the same order of magnitude as the old. If new dimensions differ by more than ~2× in either axis, you broke the framing — recapture with `ref`.
 

packages/backend.ai-docs-toolkit/src/markdown-processor-web.ts

@@ -14,6 +14,8 @@ import {
   normalizeRstTables,
   convertIndentedNotes,
   resolveMarkdownPath,
+  getImageDimensions,
+  IMAGE_SCALE_FACTOR,
 } from "./markdown-processor.js";
 import type { Chapter, Heading } from "./markdown-processor.js";
 import {
@@ -331,12 +333,32 @@ function reportLinkDiagnostics(diagnostics: LinkDiagnostic[]): void {
  * misses (defensive: should not happen because the pre-pass walks the
  * exact same tokens marked will render).
  */
+/**
+ * Convert a web-absolute image URL (e.g. `/sessions_all/images/foo.png`,
+ * the form `rewriteImagePathsForWeb` produces) back to a disk path under
+ * `<srcDir>/<lang>/…` so we can read the PNG header for natural-size
+ * auto-capping. Returns null for off-tree URLs (http(s):, leading-slash
+ * paths outside the lang dir, etc.) — the caller must fall back to
+ * unsized rendering in that case.
+ */
+function resolveWebImageDiskPath(
+  href: string,
+  srcDir: string | undefined,
+  lang: string | undefined,
+): string | null {
+  if (!srcDir || !lang) return null;
+  if (/^(?:https?|file):\/\//.test(href)) return null;
+  if (!href.startsWith("/")) return null;
+  return path.resolve(srcDir, lang, "." + href);
+}
+
 function buildWebRenderer(
   chapterSlug: string,
   headings: Heading[],
   options?: {
     chapterIndex?: number;
     lang?: string;
+    srcDir?: string;
     figureLabels?: Record<string, string>;
     /** Pre-rendered Shiki HTML keyed by `${lang}\0${code}`. */
     highlightedCode?: Map<string, string>;
@@ -346,6 +368,8 @@ function buildWebRenderer(
   const chapterIndex = options?.chapterIndex ?? 0;
   const figureLabel = getFigureLabel(options?.lang, options?.figureLabels);
   const highlightedCode = options?.highlightedCode;
+  const srcDir = options?.srcDir;
+  const lang = options?.lang;
 
   return {
     heading(text: string, level: number, _raw: string): string {
@@ -359,9 +383,28 @@ function buildWebRenderer(
       const titleAttr = title ? ` title="${title}"` : "";
       const { cleanAlt, sizeHint } = parseImageSizeHint(text || "");
 
+      // Size resolution order (matches the PDF renderer):
+      //   1. Explicit `![alt =<w>](url)` hint wins absolutely.
+      //   2. Otherwise, read the PNG/JPEG header and cap at the natural
+      //      CSS display width (pixel width × IMAGE_SCALE_FACTOR, which
+      //      undoes the 2× zoom capture convention). This keeps small
+      //      captures (a 760-px-wide notification → 380 CSS px) from
+      //      stretching to fill the full article column.
+      //   3. If neither path produces a size, emit no style — the
+      //      `.doc-image { max-width: 100% }` rule still prevents
+      //      horizontal overflow for legacy (non-2× / oversize) images.
       let styleAttr = "";
       if (sizeHint && sizeHint !== "auto") {
         styleAttr = ` style="width:${sizeHint}"`;
+      } else if (!sizeHint) {
+        const diskPath = resolveWebImageDiskPath(href, srcDir, lang);
+        if (diskPath) {
+          const dims = getImageDimensions(diskPath);
+          if (dims) {
+            const cap = Math.round(dims.width * IMAGE_SCALE_FACTOR);
+            styleAttr = ` style="max-width:${cap}px"`;
+          }
+        }
       }
 
       if (chapterIndex > 0) {
@@ -657,6 +700,7 @@ export async function processMarkdownFilesForWeb(
       renderer: buildWebRenderer(chapterSlug, headings, {
         chapterIndex,
         lang,
+        srcDir,
         figureLabels,
         highlightedCode,
       }),

packages/backend.ai-docs-toolkit/src/markdown-processor.ts

@@ -36,7 +36,7 @@ function renderShellSessionForPdf(code: string): string {
 /**
  * Read image dimensions from a PNG or JPEG file header.
  */
-function getImageDimensions(filePath: string): { width: number; height: number } | null {
+export function getImageDimensions(filePath: string): { width: number; height: number } | null {
   try {
     const buf = Buffer.alloc(32);
     const fd = fs.openSync(filePath, 'r');
@@ -76,7 +76,18 @@ function getImageDimensions(filePath: string): { width: number; height: number }
   return null;
 }
 
-const IMAGE_SCALE_FACTOR = 0.5;
+/**
+ * Display scaling factor for captured screenshots.
+ *
+ * Capture convention (SCREENSHOT-GUIDELINES.md): screenshots are taken
+ * at 2× CSS zoom for sharper text, so the PNG's pixel width is roughly
+ * twice the intended display width. Multiplying by 0.5 converts the
+ * captured pixel width back to its intended CSS display width.
+ *
+ * Used by both the PDF and web renderers when no explicit size hint is
+ * given via `![alt =<w>](url)`.
+ */
+export const IMAGE_SCALE_FACTOR = 0.5;
 
 function resolveImageFilePath(src: string): string | null {
   try {

packages/backend.ai-docs-toolkit/src/styles-web.ts

@@ -1856,48 +1856,63 @@ li > ul, li > ol {
 }
 
 /* ==========================================================================
-   Images (FR-2726 Phase 3 — BAI figure styling)
+   Images (FR-2726 Phase 3 / FR-2907 — BAI figure styling with matte)
    --------------------------------------------------------------------------
-   The doc-image wrapper acts as a clean BAI-style figure: 1px border,
-   12px radius, soft shadow. Captions (when produced by the markdown
-   pipeline as <figcaption>) sit centered below the image. Stat cards
-   and other content components opt into the BAI palette via the
-   .bai-stat-grid / .bai-stat-card classes below.
+   The doc-figure wrapper acts as a "matte" frame around captured UI:
+   - Border + radius + soft shadow live on the FIGURE, not the IMG,
+     so an inner card/modal screenshot's own rounded corners don't
+     visually clash with the outer wrapper radius.
+   - Padding + a subtly off-white background provide breathing room
+     around element-level captures whose content is flush to the
+     PNG's edges (Playwright ref screenshots have no padding by
+     default).
+   - The img is bare inside the matte (no border/radius/background)
+     so it sits cleanly on the matte surface.
+
+   For bare <img class="doc-image"> (catalog/sample contexts that
+   don't wrap in <figure>), keep a minimal border + radius as a
+   fallback so the image still reads as a framed figure.
    ========================================================================== */
 .doc-image {
   max-width: 100%;
   height: auto;
   display: block;
   margin: 1.25rem auto;
+  /* Bare-img fallback (no enclosing figure). Inside .doc-figure,
+     the matte rules below strip these. */
   border: 1px solid var(--bai-border);
-  border-radius: var(--bai-radius-lg);
-  box-shadow: var(--bai-shadow-sm);
+  border-radius: var(--bai-radius);
   background: var(--bai-bg);
 }
 
-figure {
-  /* Figure owns the outer vertical rhythm only. The image is
-     centered horizontally by the figure .doc-image rule below
-     (margin: 0 auto), and the caption is centered by figcaption's
-     own text-align rule — so this block intentionally avoids
-     setting text-align (which would only catch stray inline
-     content and could surprise authors). */
+figure.doc-figure {
+  /* Matte/frame around captured UI. Padding is the headline behavior
+     change here: it gives element-level Playwright captures (where
+     the screenshot bounding box has zero internal padding) visible
+     breathing room without recapture. */
   margin: 1.25rem 0;
+  padding: 16px;
+  background: var(--bai-bg-muted);
+  border: 1px solid var(--bai-border);
+  border-radius: var(--bai-radius-lg);
+  box-shadow: var(--bai-shadow-sm);
 }
 
-figure .doc-image {
-  /* Override .doc-image's default block centering only on the
-     vertical axis (figure owns the outer top/bottom margin); keep
-     auto on the horizontal axis so narrow images stay centered
-     instead of left-aligning to the figure's edge. */
+figure.doc-figure .doc-image {
+  /* Inside the matte: bare image. The wrapper owns the border and
+     radius so a screenshot of a card/modal with its own rounded
+     corners does not visually compete with a second outer radius. */
   margin: 0 auto;
+  border: 0;
+  border-radius: 0;
+  background: transparent;
 }
 
 figcaption {
   text-align: center;
   font-size: 12.5px;
   color: var(--bai-text-3);
-  padding: 12px;
+  padding: 12px 0 0;
 }
 
 /* Stat-card grid (opt-in HTML). Authors who need a quick numeric

packages/backend.ai-docs-toolkit/src/styles.ts

@@ -317,13 +317,22 @@ p {
 }
 
 /* ==========================================================================
-   Images – figure with caption and shadow
+   Images – figure with caption and matte (FR-2907)
+   --------------------------------------------------------------------------
+   The matte (padding + light off-white background + outer border) mirrors
+   the web build's .doc-figure treatment so PDF and HTML stay visually
+   aligned. Border and radius live on the figure, not the inner img, so
+   a screenshot of an already-rounded card/modal does not show a second
+   competing radius around it.
    ========================================================================== */
 .doc-figure {
   margin: 16px 0;
-  padding: 0;
+  padding: 12px;
   page-break-inside: avoid;
   text-align: center;
+  background: #fafafa;
+  border: 0.5px solid ${theme.borderColor};
+  border-radius: 8px;
 }
 
 .doc-figure figcaption {
@@ -345,10 +354,21 @@ p {
   max-width: 100%;
   height: auto;
   display: inline-block;
+  /* Bare-img fallback for catalog / non-figure contexts. Inside a
+     .doc-figure the matte wrapper above owns the border + radius and
+     this rule is visually neutralised (img sits on the matte). */
   border-radius: 4px;
   border: 0.5px solid #d0d0d0;
 }
 
+.doc-figure .doc-image {
+  /* Inside the matte the image is bare. Strips the bare-img border /
+     radius so the screenshot's own rounded corners (modal, card) are
+     not surrounded by a second mismatched radius. */
+  border: 0;
+  border-radius: 0;
+}
+
 /* ==========================================================================
    Tables
    ========================================================================== */

packages/backend.ai-webui-docs/SCREENSHOT-GUIDELINES.md

@@ -114,11 +114,40 @@ The resulting PNG will be ~2× the natural CSS dimensions in pixels (e.g., a 450
 ### Focused Cropping
 
 - **Prefer element-level screenshots over full-page captures** when documenting a specific feature or interaction
-- **For modals and dialogs: capture only the modal element itself**, not the full page. Use the modal's DOM element as the screenshot target (e.g., `.ant-modal-wrap .ant-modal`, `[role="dialog"]`)
+- **For modals and dialogs: prefer the modal wrapper, not the modal itself.** Use `ref` of `.ant-modal-wrap .ant-modal` (or `[role="dialog"]`) only when the inner element is large enough that its own padding gives the captured content breathing room. Otherwise, capture the surrounding wrapper element (e.g., `.ant-modal-wrap`, a `<section>` panel) so the screenshot picks up the application's natural spacing around the dialog.
 - Use `ref` parameter in `browser_take_screenshot` to capture only the relevant element (e.g., a modal, a toolbar section, a specific panel)
 - Full-page captures are appropriate for page overview screenshots, but for feature-specific documentation, crop to the relevant area so users can clearly identify what is being described
 - Include just enough surrounding context for users to orient themselves
 
+### Padding & Framing
+
+The docs renderer wraps every captured image in a "matte" frame — a soft off-white background with padding, an outer border, and rounded corners. The matte provides **visual breathing room** even when the captured PNG itself has no internal padding, so a tight element-level capture no longer reads as cramped. Two implications for authors:
+
+- **Border-radius on the matte is the only outer radius**. Inside the matte, the inner `<img>` is bare (no border, no radius). This is intentional: if a captured screen has its own rounded corners (a modal, a card), they sit cleanly on the matte and no longer compete with a second outer radius. **Do not** try to "fix" inner radius mismatches at capture time — capture the raw element and let the matte frame it.
+- **You do not need to bake padding into the screenshot.** The matte gives every image equal breathing room. The capture should still avoid clipping content (don't crop a button's last pixel column), but you do not need to expand the bounding box just to leave whitespace.
+
+#### Parent-container-preferred rule
+
+When in doubt about which element to capture, climb one level: `.ant-modal-wrap` over `.ant-modal`, a containing `<section>` over a tightly-bounded card, a wizard step's outer panel over the inner form. The renderer's matte adds outer padding regardless, so picking the parent costs nothing visually but gives the capture access to the application's own intra-component spacing.
+
+#### Small-element rule
+
+When the target element's bounding box is **≤ 600 CSS px** in either dimension (notifications, badges, button rows, toasts, small status pills), an unmodified element capture will produce a tiny PNG that the renderer would otherwise display proportionally small. Two acceptable handling paths:
+
+1. **Capture as-is and trust the auto size cap.** The renderer reads the PNG header and caps the display width at `pixel_width × 0.5` (the 2× zoom convention). A 760×190 notification capture will render at ~380 CSS px wide on the web and PDF, framed by the matte — usually fine.
+2. **Reposition the element on a neutral surface before capture** when you want the capture to *fill* the docs column. Use `browser_evaluate` to apply temporary CSS — e.g., move a floating notification to the viewport center with extra padding so the bounding box is larger and includes deliberate whitespace around the widget. Reset the style after capture.
+
+Pick path (2) only when the auto-capped display feels too small for the surrounding documentation context. Most small-element captures look correct with path (1).
+
+#### Image size caps (renderer-side, automatic)
+
+The web and PDF renderers automatically size images based on the captured PNG's pixel dimensions (assuming the 2× zoom convention):
+
+- Display width = `pixel_width × 0.5`, capped at the article column width.
+- Explicit overrides via the `![alt =<width>](url)` size hint take precedence (`=380px`, `=50%`, `=auto`). Use these sparingly — only when the automatic cap produces a visibly wrong result.
+
+Authors do not normally need to think about this. Capture at 2× zoom, the renderer handles the display size.
+
 ### Match the Existing Screenshot's Framing (for re-captures)
 
 When **replacing an existing screenshot** (same filename), the new image MUST match the previous image's framing scope. The filename encodes a contract about what the image shows.
@@ -141,9 +170,10 @@ Then capture the new screenshot at the **same scope**:
 | Old image scope | Capture method |
 |---|---|
 | Header strip (e.g., `header.png`) | `ref` of `header`/top-bar element only — never `fullPage: true` |
-| Modal/dialog only | `ref` of `.ant-modal-wrap .ant-modal` or `[role="dialog"]` |
+| Modal/dialog | `ref` of `.ant-modal-wrap` (wrapper, preferred — see [Parent-container-preferred rule](#parent-container-preferred-rule)) or `.ant-modal-wrap .ant-modal` / `[role="dialog"]` |
 | Sidebar segment | `ref` of the sidebar element |
 | Page region (e.g., a step in a wizard) | `ref` of the specific panel, not the whole layout |
+| Small widget (notification, badge, ≤ 600 CSS px) | See [Small-element rule](#small-element-rule) — capture as-is and trust the auto size cap, or reposition with `browser_evaluate` for full-column rendering |
 | Full page overview | `fullPage: true` is acceptable |
 
 **Anti-pattern observed in PR #6708**: `header.png` was 2358×222 (header strip only) on `main`, recaptured as 2880×1800 (full viewport including sidebar + main content + breadcrumbs). The filename promises "header" but the new image shows everything. **Always run the preflight above before re-capturing.**