Skip to content

Tell connected AI apps how to keep a picture's size #797

Open

Description

@HMarzban

Problem

When a connected AI app adds a picture through the docs.plus MCP tools, the pad draws it at 320×240. The real picture may be 16:9 and far wider.

The MCP Markdown parse leaves the image width and height empty. The pad then falls back to IMAGE_LAYOUT_FALLBACK (extensions/extension-hypermultimedia/src/loading/syncLayout.ts:5, used at extensions/extension-hypermultimedia/src/nodes/image/nodeView.ts:35). Settings Markdown replace does not have this problem, because it measures natural size in the browser (apps/webapp/src/components/TipTap/toolbar/desktop/commitImportedImageSizes.ts). An MCP write has no browser step.

The size block {width=… height=…} on the image line fixes it (docs/media-in-markdown.md). But no MCP tool tells the app that the block exists. Each tool's markdown field text in apps/hocuspocus.server/src/modules/mcp/tools/documentTools.ts explains headings and Mermaid only. All of them end with the same DIAGRAM_HINT (line 72).

The mistake also cannot be undone through the MCP. edit_blocks refuses to remove a block that holds media, and rewrite_section keeps each media block exactly as it is. Only a History restore in the app removes it.

How we found it

On 2026-11-15 the 2.3.6 banner went onto https://docs.plus/demo through edit_blocks. The {width=830 height=467} block was added before the write, and a headless check measured the banner at 830×467. Without the block, the code path above gives 320×240 (read from code, not measured on production).

Our own agents know the trap from apps/hocuspocus.server/CLAUDE.md and the release-product skill. Outside apps such as Claude and ChatGPT never read those files.

Proposed fix

Add a PICTURE_HINT constant beside DIAGRAM_HINT, and append it wherever DIAGRAM_HINT is used today. That covers markdownField (lines 74-80, used by create_document and append_to_document), edit_blocks (line 367) and rewrite_section (line 566). For example:

A picture keeps its size only when the line carries one: ![alt](url){width=830 height=467}. Without it the pad draws 320×240.

Add the same line to docs/mcp/reference.md. Keep the text short, because every tool call sends it to the app.

Decisions

  1. Fix the tool text only, or also change how the pad draws an unsized picture?
    • Recommended: tool text only. It is the smallest change, and it changes no stored data and no extension behaviour.
    • Other choice: when width and height are empty, the image node view draws the picture at its natural size after it loads, capped to the column. That fixes every write path, including REST PATCH. But it changes extension-hypermultimedia, which ships to npm users, and the page can move when the picture loads.
  2. Should the server fill in the size? Recommended: no. The server must not fetch pictures (apps/hocuspocus.server/CLAUDE.md, Markdown import rule), and it cannot know the size without fetching.

Done when

  • The markdown field text and docs/mcp/reference.md name the size block.
  • A picture written through edit_blocks with the block draws at that size, and the existing MCP tests still pass.

Activity

  1. added this to the v2.4.0 milestone on Nov 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions