Docs/Diffs: clarify PDF file guidance and viewer behavior

CHANGELOG.md

@@ -26,6 +26,7 @@ Docs: https://docs.openclaw.ai
 - Feishu/Doc permissions: support optional owner permission grant fields on `feishu_doc` create and report permission metadata only when the grant call succeeds, with regression coverage for success/failure/omitted-owner paths. (#28295) Thanks @zhoulongchao77.
 - Web UI/i18n: add German (`de`) locale support and auto-render language options from supported locale constants in Overview settings. (#28495) thanks @dsantoreis.
 - Tools/Diffs: add a new optional `diffs` plugin tool for read-only diff rendering from before/after text or unified patches, with gateway viewer URLs for canvas and PNG image output. Thanks @gumadeiras.
+- Tools/Diffs: add PDF file output support and rendering quality customization controls (`fileQuality`, `fileScale`, `fileMaxWidth`) for generated diff artifacts, and document PDF as the preferred option when messaging channels compress images. (#31342) Thanks @gumadeiras.
 - Memory/LanceDB: support custom OpenAI `baseUrl` and embedding dimensions for LanceDB memory. (#17874) Thanks @rish2jain and @vincentkoc.
 - ACP/ACPX streaming: pin ACPX plugin support to `0.1.15`, add configurable ACPX command/version probing, and streamline ACP stream delivery (`final_only` default + reduced tool-event noise) with matching runtime and test updates. (#30036) Thanks @osolmaz.
 - Shell env markers: set `OPENCLAW_SHELL` across shell-like runtimes (`exec`, `acp`, `acp-client`, `tui-local`) so shell startup/config rules can target OpenClaw contexts consistently, and document the markers in env/exec/acp/TUI docs. Thanks @vincentkoc.

docs/tools/diffs.md

@@ -88,7 +88,7 @@ All fields are optional unless noted:
 - `mode` (`"view" | "file" | "both"`): output mode. Defaults to plugin default `defaults.mode`.
 - `theme` (`"light" | "dark"`): viewer theme. Defaults to plugin default `defaults.theme`.
 - `layout` (`"unified" | "split"`): diff layout. Defaults to plugin default `defaults.layout`.
-- `expandUnchanged` (`boolean`): expand unchanged sections.
+- `expandUnchanged` (`boolean`): expand unchanged sections when full context is available. Per-call option only (not a plugin default key).
 - `fileFormat` (`"png" | "pdf"`): rendered file format. Defaults to plugin default `defaults.fileFormat`.
 - `fileQuality` (`"standard" | "hq" | "print"`): quality preset for PNG or PDF rendering.
 - `fileScale` (`number`): device scale override (`1`-`4`).
@@ -137,6 +137,14 @@ Mode behavior summary:
 - `mode: "file"`: file fields only, no viewer artifact.
 - `mode: "both"`: viewer fields plus file fields. If file rendering fails, viewer still returns with `fileError`.
 
+## Collapsed unchanged sections
+
+- The viewer can show rows like `N unmodified lines`.
+- Expand controls on those rows are conditional and not guaranteed for every input kind.
+- Expand controls appear when the rendered diff has expandable context data, which is typical for before and after input.
+- For many unified patch inputs, omitted context bodies are not available in the parsed patch hunks, so the row can appear without expand controls. This is expected behavior.
+- `expandUnchanged` applies only when expandable context exists.
+
 ## Plugin defaults
 
 Set plugin-wide defaults in `~/.openclaw/openclaw.json`:
@@ -314,6 +322,11 @@ Viewer accessibility issues:
   - use `gateway.bind=custom` and `gateway.customBindHost`
 - Enable `security.allowRemoteViewer` only when you intend external viewer access.
 
+Unmodified-lines row has no expand button:
+
+- This can happen for patch input when the patch does not carry expandable context.
+- This is expected and does not indicate a viewer failure.
+
 Artifact not found:
 
 - Artifact expired due TTL.

docs/tools/index.md

@@ -174,7 +174,7 @@ Optional plugin tools:
 
 - [Lobster](/tools/lobster): typed workflow runtime with resumable approvals (requires the Lobster CLI on the gateway host).
 - [LLM Task](/tools/llm-task): JSON-only LLM step for structured workflow output (optional schema validation).
-- [Diffs](/tools/diffs): read-only diff viewer and PNG renderer for before/after text or unified patches.
+- [Diffs](/tools/diffs): read-only diff viewer and PNG or PDF file renderer for before/after text or unified patches.
 
 ## Tool inventory
 

extensions/diffs/README.md

@@ -53,7 +53,7 @@ Useful options:
 - `fileQuality`: `standard`, `hq`, or `print`
 - `fileScale`: device scale override (`1`-`4`)
 - `fileMaxWidth`: max width override in CSS pixels (`640`-`2400`)
-- `expandUnchanged`: expand unchanged sections
+- `expandUnchanged`: expand unchanged sections (per-call option only, not a plugin default key)
 - `path`: display name for before and after input
 - `title`: explicit viewer title
 - `ttlSeconds`: artifact lifetime
@@ -128,7 +128,7 @@ This is version two.
 Render a file (PNG or PDF):
 
 ```text
-Use the `diffs` tool in `file` mode for this before and after input. After it returns `details.filePath`, use the `message` tool with `path` or `filePath` to send me the rendered diff image.
+Use the `diffs` tool in `file` mode for this before and after input. After it returns `details.filePath`, use the `message` tool with `path` or `filePath` to send me the rendered diff file.
 
 Path: README.md
 
@@ -176,4 +176,5 @@ diff --git a/src/example.ts b/src/example.ts
 - Remote viewer misses are throttled to reduce token-guess abuse.
 - PNG or PDF rendering requires a Chromium-compatible browser. Set `browser.executablePath` if auto-detection is not enough.
 - If your delivery channel compresses images heavily (for example Telegram or WhatsApp), prefer `fileFormat: "pdf"` to preserve readability.
+- `N unmodified lines` rows may not always include expand controls for patch input, because many patch hunks do not carry full expandable context data.
 - Diff rendering is powered by [Diffs](https://diffs.com).