Morph.Blazor 1.19.0

Morph.Blazor

Reusable Blazor WebAssembly components that convert Word .docx, Excel .xlsx and PowerPoint .pptx files to PNG, PDF, HTML, Markdown or plain text — or show them as they are, the way a browser shows a PDF — entirely in the browser. No file ever leaves the device.

This is the converter and viewer that power morph.papyrine.org, packaged so any Blazor app can drop them in. The app in src/Morph.Web is now only a shell — header, navigation, theme toggle and footer — around the MorphConverter and MorphViewer components from this package.

Install

dotnet add package Morph.Blazor

Set up

Three things, all in the host app:

1. Register the services:

   builder.Services.AddMorph();
   

2. Make sure a base-addressed HttpClient is registered — the Blazor WebAssembly template already does this. The components use it to fetch the bundled fonts and samples out of this package's static web assets.

3. Link the stylesheet in index.html, before the host's own, so the host can override anything in it:

   <link rel="stylesheet" href="_content/Morph.Blazor/morph.css" />
   

No <script> tag is needed: the JavaScript ships as an ES module and the components import it themselves.

Then use it:

<MorphConverter />

That is the whole widget — upload panel (or one of three bundled samples), a live page-image preview, an output-format picker with per-format options, and a download button. On a viewport wider than 1200px it also shows the selected format's real output beside the preview: Markdown and plain text inline, PDF and HTML in an iframe.

MorphConverter parameters

Selectable text

Every rendered page, in the converter's preview and in the viewer, carries a text layer: a transparent copy of the page's text laid exactly over the image — the technique PDF.js uses to make a rendered page selectable. Text can be dragged over, copied and found with the browser's own find, as in a PDF viewer.

The layer is read from the same single layout pass the image is painted from, so every run sits where it was drawn:

• one absolutely positioned element per line, with its runs inline — the browser's find cannot match across two positioned elements, so a word-per-element layer would leave every phrase unfindable;
• sized in container-query units of the page, so it tracks the image at any displayed width or zoom without any script running on resize;
• set in the same Aptos faces the browser raster uses, with only the spaces a justified line removed re-spaced to their drawn gaps, so selection highlights land on the drawn glyphs;
• copied through its own copy handler, so every engine yields the same plain text: words re-spaced where the layout removed spaces, a tab between table cells (a copied worksheet row pastes back into a spreadsheet as cells), a line break after each paragraph and row, the footer after the body. No rich-text flavour is offered, which would otherwise paste invisible transparent-coloured text into an editor.

Warped WordArt is one figure with no line geometry, so its whole box stands in for its text.

Viewer

<MorphViewer Source="bytes" FileName="report.docx" />

MorphViewer shows a .docx, .xlsx or .pptx without converting it, with the toolbar of a browser PDF viewer — and, for a Word document, lets its text be edited where it stands and its comments and tracked changes be read and settled in a pane beside it. The file is parsed and laid out once; after that only the pages in view are painted, one at a time, at the resolution the zoom and the screen's pixel density call for — so a long document opens fast and stays responsive on the single-threaded WebAssembly runtime, and zooming in sharpens the page rather than stretching it.

The viewer fills its box: give it a height (the stylesheet's default is 80vh). Its setup is the converter's — AddMorph(), a base-addressed HttpClient and the stylesheet.

Keyboard, with focus in the viewer: ←/→ page when the page does not scroll sideways, Home/End go to the first/last page, Ctrl++/-/0 zoom in/out/back to automatic, Ctrl+A selects the pages' text.

Editing

With editing on, a click on a paragraph opens it for typing where it stands on the page: the same text in the same face, set to the same measure, so it sits on the picture of itself. Typing happens in the browser, at the browser's speed; nothing is converted until the reader moves on — to another paragraph, or with Ctrl+Enter — and then the paragraph is written into the file, the file is laid out again, and the page redrawn.

The edit is worked out from the paragraph as it reads before and after, not from the keys that were pressed, and only what differs is changed in the file. Everything the editor does not show — bookmarks, the anchors of comments, a run's own spelling of its properties — stays exactly as it was, and a paragraph handed in unchanged leaves the file unchanged.

What is not text is shown and left in place: a picture, a field (a date, a page number, a cross-reference), a footnote's reference, and text a tracked change has deleted. The text around them is edited; they cannot be typed into or deleted here.

Review

A Word document's comments and tracked changes open in a pane beside the pages, one card each, in the order they occur in the document. The page itself shows what Word prints: an insertion underlined and a deletion struck through in the revision colour, with a change bar in the margin. While the pane is open the text each unresolved comment is attached to is highlighted on the page.

Every edit is made to the file itself and the result laid out again, so the pages always show exactly what Download will save; OnDocumentChanged hands the host the same bytes after each edit. Comments are written the way Word writes them — range marks in the document, comments.xml, and the thread and resolved state in commentsExtended.xml — so an edited file opens in Word with its threads intact.

A comment is dated by the reader's clock, which the viewer asks the browser for. .NET's own would be the server's under Blazor Server, and UTC in a WebAssembly app built without time zone data — and Word reads a comment's date at face value, so one dated in UTC shows there as made hours ago. The UTC time is written beside it (commentsExtensible.xml), as Word does.

What is recognised as a tracked change: inserted, deleted and moved text (paragraph marks included); character, paragraph, table and page-setup formatting changes; inserted and deleted table rows and cells, and merged cells. Rejecting a formatting change puts back the formatting it replaced.

Limits worth knowing:

• Text is edited in the document's body — its paragraphs, table cells and text boxes. Headers, footers and notes are other parts of the file, and are read only.
• Editing changes text, character formatting and alignment. It does not add or remove pictures, fields, tables or notes, change styles or fonts, or edit a workbook or a deck.
• The editor is set in the face the page was drawn in, to the width the page set it, so its lines break where the page's do. Justified text is set ragged while it is open, and text turned on its side is not opened in place.
• A document's own protection is honoured: one restricted to comments accepts comments and leaves its text and its tracked changes alone, one that has every change tracked has them tracked, and a read-only one lists everything and changes nothing. ReadOnly does the same for any document.
• An ISO 29500 Strict document is listed but not edited: saving it would change its conformance class.
• Comments are anchored in the document body. A tracked change in a header, a footer or a note is listed and can be settled, but has no place on a page to scroll to.
• Moved text is drawn as a deletion where it was and an insertion where it went, not in Word's own green.

MorphViewer parameters

Print is a raster at PrintDpi rather than vector text. A document mixing page sizes prints each at its own size where the browser supports named pages (Chromium, Firefox); elsewhere every sheet takes the first page's size.

Theming

The components declare no colours of their own. Every rule reads a --morph-* custom property with a literal fallback, so they look right with no configuration — and a host that sets those properties always wins, whatever the stylesheet link order:

To follow a palette the host already has, map them once — including through a light/dark switch, since both blocks land on the same element:

:root {
    --morph-primary: var(--primary-color);
    --morph-surface: var(--surface-color);
}

Building a custom UI

MorphConverter is the batteries-included option, not the only one. Everything under it is public:

• ConversionService — the conversion itself, over byte[] in and byte[] out: RenderPngPages, ToPdf, ToHtml, ToMarkdown, ToText, and BuildDownload (which picks the right extension and MIME type, zipping a multi-page PNG render). Also Detect, to identify an upload by extension — the browser's reported MIME type is unreliable for Office files.
• ConversionService.RenderPages — every page for display from one layout pass: the full-page PNG, the page size and its PageTextLayer. PageTextLayer.Text is the page's text as copying it yields.
• FontStore.EnsureAsync(http) — materialises the bundled fonts and returns the directory to hand the renderers. Idempotent, so call it early to take the download off the render's critical path.
• DocumentPreview, FormatSelector, ExportOptionsPanel, ConversionProgress, ErrorPanel — the individual pieces, each usable on its own. DocumentPreview.TextLayers takes the pages' layers alongside their image URLs and makes the preview selectable.
• MorphInterop — the browser bridge: file downloads, blob URLs for an iframe, viewport width, and RenderTextLayerAsync, which builds a page's text layer into an overlay of a custom page view.

Rendering is CPU-bound and the WebAssembly runtime is single-threaded, so wrap a conversion in Task.Run — it yields once, which lets a busy state paint before the compute begins.

Fonts

Rendering needs real font files, and a browser has none of its own. The four Aptos faces (400/700, upright and italic) ship as static web assets, are fetched once, and are written into the WASM in-memory filesystem; that directory is handed to every converter, with every unresolved family mapped to Aptos. So any file renders — its own fonts (Calibri, Times New Roman, "Aptos Light", …) substituted with Aptos. Layout and structure are preserved; exact glyph shapes are not. Shipping the real Microsoft fonts isn't an option.

Why a directory rather than the fonts embedded in Morph.dll: PdfSharp resolves fonts through its own global resolver, which can't reach embedded fonts at all, and the ImageSharp path — given no directory — walks an OS-font fallback chain that throws in the browser the moment a document names a weight the embedded set doesn't include. A pinned directory sidesteps both. The text exports (HTML, Markdown, plain text) rasterise nothing but take the directory too: Excel's column-width unit is the widest digit of the workbook's body font, so a sheet's td widths come out of whichever face resolves — left to the OS the same workbook exports different columns on every machine.

To take the ~940KB off the first render's critical path, preload them during the WASM boot:

<link rel="preload" href="_content/Morph.Blazor/fonts/Aptos_400.ttf" as="fetch" crossorigin />

crossorigin matters: without it the browser won't reuse the preload and downloads each font twice. FontStore.AssetPaths lists all four.

Trimming

The package ships MSBuild targets that root the reflection-heavy dependencies (DocumentFormat.OpenXml, AngleSharp, ImageSharp, PdfSharp) when the host app publishes trimmed. They resolve types by name at runtime, so a full trim would strip types they need and surface only as a browser-side crash part-way through a conversion. Nothing to configure — PublishTrimmed=true keeps working.

Backends

The package uses ImageSharp for PNG and PdfSharp for PDF, both pure-managed so they run in WebAssembly. Morph.Skia is deliberately avoided: SkiaSharp needs a native browser-wasm build that its NuGet packages don't ship.

The viewer and the text layer read Morph's laid-out pages directly — Morph and Morph.ImageSharp grant this package their internals — so it has to be used with the Morph packages of the same version. They are released together from one repository at one version number.