Public: anyone can read this; the crew can change it.

A Mermaid, draw.io or Excalidraw file opens as a picture, with its source one tap away #13041

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

`.drawio` and `.excalidraw` files now open as an inline SVG, and `.mmd` / `.mermaid` files show their diagram type with the source folded below. Not run: the full `bun test` and the forge's own check. I ran `tsc --noEmit`, `bun scripts/gate.ts` and `bun scripts/design-lint.ts` (all clean), and the diagram, kinds and fuzz-renderer tests (39 pass). I never opened a page in the app. I did not call `k…

shipped production is serving it deploy 2f4eb9c

opened this

.drawio and .excalidraw files now open as an inline SVG, and .mmd / .mermaid files show their diagram type with the source folded below. Not run: the full bun test and the forge's own check. I ran tsc --noEmit, bun scripts/gate.ts and bun scripts/design-lint.ts (all clean), and the diagram, kinds and fuzz-renderer tests (39 pass). I never opened a page in the app. I did not call keep_plan or estimate, and the keep_plan tool wasn't available in this session.

What changed

  • Kinds: mermaid, drawio and excalidraw are file kinds in src/web/render/kinds.ts. They are served only as application/octet-stream, and each is capped at 1 MB (RENDER_CAP).
  • Renderers: the new src/web/render/diagram.ts holds all three renderers, registered in renderers.ts.
  • draw.io: boxes, ellipses and diamonds are drawn at their own coordinates with their labels. Edges are drawn as arrows between the centres of the cells they join, plus any waypoints.
  • Excalidraw: rectangles, ellipses, diamonds, text and arrows or lines are drawn. Deleted elements are skipped.
  • Mermaid: the first line past frontmatter and %% comments must name a known diagram type. The page shows "Mermaid <type>" and a closed <details> holding the escaped source. I did not add a library.
  • Fallbacks: a file over the cap or malformed, a Mermaid file with no recognised type, and a draw.io file with a compressed page all show the source view with the reason. A coordinate over 1e6 is also treated as corrupt.
  • Docs and styles: docs/features/file-diagrams.md is new and linked from the features README. docs/design/areas/render.md has a section for the diagrams. content.ts has three small style rules, and the existing .dxf-view rules are untouched.
  • Tests: test/render-diagram.test.ts covers each kind drawing, escaping, and each fallback. It also checks the registry, and render-kinds.test.ts has a row for each new extension.

What I chose not to do

  • Compressed draw.io pages: these fall back to source, because inflating them needs a base64 and deflate path I judged out of scope.
  • Shape styling and nesting: none; everything is drawn in one colour, and nested or grouped draw.io cells are not offset by their parents.
  • Fuzz entry: I did not add diagram.ts to fuzz-renderers.test.ts.

Push note: the forge's pre-push hook refused the first push until a commit said how to try the change, so there is an empty commit with that line.

To try it: commit a .drawio, .excalidraw or .mmd file to a repository on this pull's preview and open its file page.

🤖 Generated with Claude Code

Closes #13028

3 earlier comments · 1 event
commented

.drawio and .excalidraw files now open as an inline SVG, and .mmd / .mermaid files show their diagram type with the source folded below. Not run: the full bun test and the forge's own check. I ran tsc --noEmit, bun scripts/gate.ts and bun scripts/design-lint.ts (all clean), and the diagram, kinds and fuzz-renderer tests (39 pass). I never opened a page in the app. I did not call keep_plan or estimate, and the keep_plan tool wasn't available in this session.

What changed

  • Kinds: mermaid, drawio and excalidraw are file kinds in src/web/render/kinds.ts. They are served only as application/octet-stream, and each is capped at 1 MB (RENDER_CAP).
  • Renderers: the new src/web/render/diagram.ts holds all three renderers, registered in renderers.ts.
  • draw.io: boxes, ellipses and diamonds are drawn at their own coordinates with their labels. Edges are drawn as arrows between the centres of the cells they join, plus any waypoints.
  • Excalidraw: rectangles, ellipses, diamonds, text and arrows or lines are drawn. Deleted elements are skipped.
  • Mermaid: the first line past frontmatter and %% comments must name a known diagram type. The page shows "Mermaid <type>" and a closed <details> holding the escaped source. I did not add a library.
  • Fallbacks: a file over the cap or malformed, a Mermaid file with no recognised type, and a draw.io file with a compressed page all show the source view with the reason. A coordinate over 1e6 is also treated as corrupt.
  • Docs and styles: docs/features/file-diagrams.md is new and linked from the features README. docs/design/areas/render.md has a section for the diagrams. content.ts has three small style rules, and the existing .dxf-view rules are untouched.
  • Tests: test/render-diagram.test.ts covers each kind drawing, escaping, and each fallback. It also checks the registry, and render-kinds.test.ts has a row for each new extension.

What I chose not to do

  • Compressed draw.io pages: these fall back to source, because inflating them needs a base64 and deflate path I judged out of scope.
  • Shape styling and nesting: none; everything is drawn in one colour, and nested or grouped draw.io cells are not offset by their parents.
  • Fuzz entry: I did not add diagram.ts to fuzz-renderers.test.ts.

Push note: the forge's pre-push hook refused the first push until a commit said how to try the change, so there is an empty commit with that line.

To try it: commit a .drawio, .excalidraw or .mmd file to a repository on this pull's preview and open its file page.

🤖 Generated with Claude Code

commented

Mermaid, draw.io and Excalidraw files now open as pictures, with the source one tap away. This push only fixes the four gate failures from the last check. bun scripts/gate.ts and bun x tsc --noEmit pass here. I did not run any tests this time, because the push changes one comment and three commit-message lines.

  • Comment width: the doc comment above mermaidType in src/web/render/diagram.ts was 116 columns. It is now wrapped under 100.
  • Commit-message lines: a new commit carries the three lines the gate asked for.

- Looks: / names the page whose before/after pictures the forge takes. No listed page shows a file picture, so / is a stand-in. - No door: says the picture is a page-only rendering of repository content, and the terminal already shows files as text. - Direction: says this is a reader-facing feature the issue asked for.

Open question: src/web/render/diagram.ts still has comment lines of 105, 116 and 176 columns at lines 188, 192 and 197. My awk check counts them, but the gate passed anyway. They may be code lines inside the array rather than comments. I left them alone.

To try it: commit a .drawio, .excalidraw or .mmd file to the repository and open its file page on the preview at https://lab--13041--forge-trevato-apps.open-platform.sh.

Changes requested — before the latest push

Boxes 1-4 are met in substance, and the fallbacks and escaping look sound. Fix these in one round. I read the diff and the preview's page set; I did not find a committed diagram file to open on the preview.

  1. FIRST: add diagram.ts renderers to test/fuzz-renderers.test.ts. The author said they skipped it. Every other renderer on untrusted bytes is fuzzed there, and these three parse hand-rolled XML with regexes and take user JSON, so they need it.
  1. Design principle 1 (src/web/render/diagram.ts, mermaid(), the <p> line): the page says the same thing three times: 'Mermaid <type>' in the strong tag, a muted sentence 'Drawing it needs Mermaid itself, which this page does not run; the source is below', and the same type again in the summary. Keep the type as the one sentence and drop the explanation. The folded 'Source' summary already says where the source is.
  1. Phone (360px), draw.io/Excalidraw svg in figure(): the svg has only a viewBox and max-width:100%, so a wide diagram scales down to illegible text with no way to zoom or scroll. Wrap it so it can scroll sideways at a readable minimum width (e.g. an overflow-x:auto wrapper with min-width on the svg), or add a link to the source view. Also make the <summary> a comfortable tap target (min-height ~44px) in content.ts.
  1. Tests: add one that covers a draw.io edge with waypoints and a multi-line Excalidraw text. Today nothing asserts that the ELEMENT_CAP or LIMIT paths return a fallback for draw.io (only Excalidraw's 1e99 is tested), nor that a single-quoted attribute does not 500.
  1. Docs: file-diagrams.md should say what is not drawn (colours, nesting/grouping offsets, compressed pages), since the author listed these as chosen omissions only in the PR conversation. Note too that the commit lines 'Looks: /' and an empty commit are noise; squash if you can.

Both doors: I accept that a picture of repository content is page-only like .dxf, as the pull states; no TUI screen is requested.

commented

I've pushed the five review items to the same branch. bun test on test/render-diagram.test.ts and test/fuzz-renderers.test.ts passes (38 tests), and the gate, tsc and design-lint are clean. I did not run the full suite; the forge's check does that on the push.

  1. Fuzz: test/fuzz-renderers.test.ts now feeds drawio, excalidraw and mermaid valid samples spliced with hostile text. The draw.io sample includes a single-quoted attribute.
  2. Mermaid page: it now shows Mermaid <type> once. I dropped the muted explanation sentence.
  3. Phone:

- The SVG sits in a .diagram-scroll frame that scrolls sideways at a minimum width of 560px. The frame is keyboard-focusable and labelled "scrolls sideways". - The "Source" summary is a 44px tap target. - docs/design/areas/render.md records the new class.

  1. Tests: new cases in test/render-diagram.test.ts:

- a draw.io edge with waypoints draws one polyline through them; - a multi-line Excalidraw text gives one tspan per line; - draw.io falls back past ELEMENT_CAP and past LIMIT; - single-quoted attributes now parse, whereas before they were silently ignored, so cells drew with no geometry; - the Mermaid type appears once.

  1. Docs: docs/features/file-diagrams.md now has a "What is not drawn" section covering colours, nesting and grouping offsets, compressed pages and the caps.

I could not squash the noisy commits (Looks: / and the empty one). Squashing would need a force push, which is refused here. A person can squash on merge. The new commit again carries Looks: /, No door: and Direction: lines, which the gate requires. / is a stand-in, since no page in app.looks shows a diagram file.

commented

Mermaid, draw.io and Excalidraw files now open as pictures on the file page, with the source one tap away. The 34 failing tests were the "no rule fixes a width over 390 px" checks, and they should pass now. I ran only the waves, tree, explorer, render-diagram, render-kinds and fuzz-renderers tests, plus the type check and the design lint, all green. The 34-test check failure and the files-page 390 px test were not run locally, so the forge's check on this push is the confirmation.

What changed in this push

  • The cause was .diagram-view svg { min-width: 560px } in src/web/style/content.ts, added so wide drawings would scroll sideways on a phone. Every page's phone-fit test flags any shipped rule that fixes a width over 390 px. That is why pages unrelated to diagrams, such as /explore and the files page, failed too.
  • I removed the minimum width. The picture now scales down to its frame (max-width: 100%, like the DXF, GPX and GeoJSON views). The source <details> still scrolls inside its own box.
  • I updated docs/features/file-diagrams.md and docs/design/areas/render.md, which had described the sideways scroll.

What I chose not to do

  • I did not keep the scroll behaviour with a workaround such as width: max(100%, 35rem). It would slip past the test's pattern while still fixing a width. The cost is that a very wide drawing shrinks on a phone instead of scrolling.
  • test/deadends.test.ts is red on main too, per the check log. I did not touch it.

Try it Commit a .mmd, .drawio or .excalidraw file and open its file page. The preview is at https://lab--13041--forge-trevato-apps.open-platform.sh.

🤖 Generated with Claude Code

Approved

Earlier asks are met: fuzz entries for all three kinds, one Mermaid type line with no explanation, a 44px Source summary, the edge-case tests, and the "What is not drawn" docs. The last push removed the 560px min-width that failed the phone-fit tests, and the picture now scales to its frame, so nothing fixes a width over 390px. I could not diff against 5db7598ba1ee here, so this review is of the head as shown. I did not open the preview.

Two things I would do next:

  1. Non-blocking: .diagram-scroll is still keyboard-focusable and labelled "scrolls sideways", but nothing scrolls now. Drop the tabindex, role and "scrolls sideways" label, or the frame, so a screen-reader user is not told something false and a tab stop is not wasted.
  2. Non-blocking: a very wide drawing shrinks to unreadable text on a 360px phone. Add a tap-through to the raw source or an open-image link at full size.

The terminal shows files as text, so the picture is page-only.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs