Repository navigation
Description
A picture in a pad can carry alt text, but nobody can edit it. Alt text is the description a screen reader reads out in place of the picture. The image node stores it in its alt attribute (extensions/extension-hypermultimedia/src/nodes/image/image.ts:96), and Markdown import fills it from . After that, no surface can change it.
What we found
On 2026-11-15 we needed to change one word in the alt text of the 2.3.0 banner on the live demo pad (docs.plus/demo). None of the three ways worked:
- Media toolbar. The inline actions are Align, Caption, View original, Download and Comment. The More actions menu holds Replace URL, Copy and Delete (
BASE_ACTIONSinextensions/extension-hypermultimedia/src/toolbar/actions.ts:141). None of them edits alt text. - MCP tools.
read_documentshows a picture only as[image], and a connected app never edits media, by design (apps/hocuspocus.server/CLAUDE.md). So an AI app cannot fix alt text either. - Replace the pad from a Markdown file. That would change the alt text, but it gives every heading a new id, so heading chats lose their rooms (Settings file replace re-keys every heading, so the digest rewrites whole sections and heading chats lose their rooms #474). We did not use it.
So a wrong or missing description stays on the picture for good, unless someone deletes the picture and inserts it again.
Who it affects
- Screen reader users. They hear the stored alt text, or nothing when it is empty.
- Pad owners who import Markdown. A typo in
![alt]cannot be fixed after import. - Owners of public pads like the demo, where the alt text is part of what a reader gets.
What other editors do
Google Docs and Microsoft Word both let you edit a picture's alt text from the picture's own menu. This is read from memory and was not checked against their help pages today. We have not checked Notion. Per AGENTS.md §Workflow And Review Expectations, the builder should confirm the majority behaviour first.
Proposed change
Add an Alt text action to the media toolbar for pictures. It opens a small form with one text field and Save, like the Replace URL form (extensions/extension-hypermultimedia/src/toolbar/replaceUrl.ts). Save writes the alt attribute in one transaction, so Undo restores the old text. Markdown export already writes ![alt] (extensions/extension-hypermultimedia/src/markdown/typedMediaMarkdown.ts:358), so the new text round-trips with no other change.
Decisions
- Where does the action live? Recommended: in the extension's
BASE_ACTIONS, becausealtis a core attribute of the publishedimagenode, and every user of the extension gains it. The other option is a webapp-only action through themediaActionshook (apps/webapp/src/components/TipTap/TipTap.tsx:255). - Inline or in More actions? Recommended: in More actions, beside Replace URL, so the inline row does not grow.
- Which media kinds? Recommended: pictures only, for now. Video and embeds have no
alttoday. - Who may edit? Recommended: anyone who can edit the pad, like Caption. A read-only pad hides the action.
- Should MCP get an alt text tool? Recommended: no, not in this issue. The rule that connected apps never edit media stays. A separate ruling can revisit it.
Done when
- A picture's More actions menu has Alt text, and Save changes the
altattribute. - Undo restores the old text.
- Markdown export writes the new text.
- The extension CHANGELOG and the image README (
extensions/extension-hypermultimedia/src/nodes/image/README.md) list the new action. - The 2.3.0 banner on the demo pad says "…a section dragged in the TOC". That fixes the one leftover from the 2026-11-15 rename of "outline" to "TOC".
Activity