OfficeIMO.Html 3.0.3

OfficeIMO.Html

OfficeIMO.Html contains the shared HTML and MHTML parser, resource policy, layout scene, and direct PNG/JPEG/TIFF/SVG/WebP rendering APIs used by OfficeIMO converters.

It owns the reusable parts that should behave consistently across HTML-to-Markdown, HTML-to-Word, HTML-to/from-RTF, and HTML-backed PDF workflows:

• trust-aware parsing profiles and shared source, DOM, CSS, selector, responsive-image, and semantic-metadata limits
• URL policy evaluation and base URI resolution
• AngleSharp document parsing helpers
• DOM traversal facts and node/depth limit tracking
• image source discovery for img, lazy-loading attributes, srcset, and picture/source
• image data URI parsing and media-type extension mapping
• MHTML/MHT web-archive loading, deterministic saving, root-part selection, and CID/Content-Location resource resolution
• deterministic accessible-name, ARIA heading, EPUB structural-semantic, and logical quote/code/footnote projection
• dependency-free HTML layout for continuous and paged output
• bounded CSS length math, caller stylesheets, deterministic media preferences, running strings, and Unicode-range-aware WOFF 1/OpenType fonts
• direct PNG, JPEG, TIFF, SVG, and lossless WebP export over OfficeIMO.Drawing
• semantic HTML to/from RTF conversion over the dependency-free OfficeIMO.Rtf model
• one typed semantic document projection shared by Excel, PowerPoint, and OneNote importers
• executable target capability contracts, preflight analysis, and source-to-target diagnostic provenance
• one operation-scoped resource session for policy, resolution, MIME checks, caching, deduplication, budgets, timeouts, and digests
• fidelity scoring across structure, text, styles, resources, annotations, formulas, charts, geometry, and reopened native artifacts

Markdown, Word, Excel, PowerPoint, RTF, and PDF models remain in their owning packages. Those projections are explicit: for example, HTML becomes a WordDocument through ToWordDocument() and a MarkdownDoc through ToMarkdownDocument().

Direct HTML rendering

using OfficeIMO.Drawing;
using OfficeIMO.Html;

string html = "<h1>Status</h1><p>Generated by OfficeIMO.</p>";
HtmlConversionDocument source = HtmlConversionDocument.Parse(html);
var options = new HtmlRenderOptions {
    ViewportWidth = 720,
    Margins = HtmlRenderMargins.All(24),
    Scale = 1.5,
    MediaFeatures = new HtmlRenderMediaFeatures {
        PreferredColorScheme = HtmlPreferredColorScheme.Light,
        ReducedMotion = HtmlReducedMotionPreference.Reduce
    }
};
options.AdditionalStylesheets.Add("body { color: hsl(215 35% 20%); }");

byte[] png = source.ToPng(options);
byte[] jpeg = source.ToJpeg(options);
byte[] tiff = source.ToTiff(options);
string svg = source.ToSvg(options);
byte[] webp = source.ToWebp(options);

OfficeImageExportResult pngSave = source.SaveAsPng("status.png", options);
IReadOnlyList<OfficeImageExportResult> webpPages = source
    .ToImages(options)
    .Paged()
    .AsWebp()
    .Save("status-pages");

MHTML web archives

MHTML uses the same bounded MIME mechanics as OfficeIMO.Email, but its root document, base URI, and embedded resources remain an HTML concern:

using OfficeIMO.Html;

MhtmlDocument archive = MhtmlDocument.Load("snapshot.mhtml");
Console.WriteLine(archive.HtmlDocument.NormalizedHtml);

var renderOptions = new HtmlRenderOptions();
archive.ConfigureRenderOptions(renderOptions);
byte[] png = archive.HtmlDocument.ToPng(renderOptions);

archive.Save("copy.mht");

ConfigureRenderOptions resolves cid: and Content-Location references from the archive before falling back to a caller-supplied resolver. It does not grant network access or weaken the configured URL policy.

Dependency footprint

• External: AngleSharp and AngleSharp.Css for DOM and CSS parsing.
• OfficeIMO: OfficeIMO.Drawing, OfficeIMO.Email, and OfficeIMO.Rtf. Resource policy, MHTML projection, layout scene, rendering, and format mappings are first-party.

See the complete OfficeIMO package map for related formats and conversion paths.

ToPng(), ToJpeg(), ToTiff(), ToSvg(), and ToWebp() return in-memory output. ExportImage() and ExportImages() return encoded output plus dimensions and diagnostics. Format-specific save methods and the shared ToImage() / ToImages() fluent builders write to files or caller-owned streams and return the same structured evidence.

Add OfficeIMO.Html.Pdf for direct PDF output. HtmlPdfSaveOptions derives from HtmlRenderOptions, so the same configured instance can be used for PDF and all five image formats.

using OfficeIMO.Html.Pdf;

var options = new HtmlPdfSaveOptions {
    Margins = HtmlRenderMargins.All(32)
};

byte[] pdf = source.ToPdf(options);
byte[] png = source.ToPng(options);
string svg = source.ToSvg(options);

RTF Bridge

using OfficeIMO.Html;
using OfficeIMO.Rtf;

HtmlConversionDocument source = HtmlConversionDocument.Parse("<p>Hello <strong>RTF</strong></p>");
RtfDocument document = source.ToRtfDocument();
string rtf = document.ToRtf();
var webOptions = RtfToHtmlOptions.CreateWebSafeProfile();
RtfToHtmlResult result = document.ToHtmlResult(webOptions);
string html = result.RequireValue();
result.Report.RequireNoLoss();

RTF-to-RTF editing in OfficeIMO.Rtf remains the lossless preservation path. The HTML bridge is semantic: it preserves supported text, inline formatting, links, lists, tables, bookmarks, fields, form fields, notes, tracked revisions, object metadata, shape metadata, and embedded PNG/JPEG images without Office/COM automation.

The web-safe profile is the default publishing boundary: only allowed web/mail URLs are emitted, private data-officeimo-rtf-* metadata is disabled, and image payloads require an explicit resolver. Use RtfToHtmlOptions.CreateRoundTripProfile() only for trusted OfficeIMO round trips; it can carry private metadata and embedded binary data and should not be published without sanitization.

URL Policy

var policy = HtmlUrlPolicy.CreateWebOnlyProfile();
string href = HtmlUrlPolicyEvaluator.ResolveUrl(
    "/docs/start.html",
    new Uri("https://example.com/"),
    policy);

Parsing And Base URIs

HtmlConversionDocument document = HtmlConversionDocument.Parse(
    html,
    new HtmlConversionDocumentOptions {
        BaseUri = new Uri("https://example.com/articles/")
    });
Uri? baseUri = document.BaseUri;

Trust and conversion limits

var options = HtmlConversionDocumentOptions.CreateUntrustedProfile();
options.Limits.MaxInputCharacters = 2_000_000;
options.Limits.MaxHtmlNodes = 50_000;
options.Limits.MaxSelectorEvaluations = 1_000_000;

HtmlConversionDocument source = HtmlConversionDocument.Parse(html, options);

The untrusted profile is the default. It rejects local-file navigation, does not fetch external resources by itself, and applies one shared set of limits before adapters allocate native Office objects. Embedded data: resources remain available through the separate resource policy and are still subject to renderer or adapter byte budgets. Use CreateTrustedProfile() only when the caller controls the HTML and resource locations.

HtmlConversionLimits is the common source for parser and CSS complexity decisions. Word forwards its compatibility limit properties to this object; Excel, PowerPoint, and OneNote use HtmlImportLimits for native artifact counts, image bytes, chart dimensions, table cells, and geometry. This keeps shared HTML decisions in OfficeIMO.Html while leaving format-specific constraints with the target model.

Shared Diagnostics And Gallery Contracts

var report = new HtmlDiagnosticReport();
report.Add("OfficeIMO.Word.Html", "HtmlCommentSkipped", "Comment skipped");

var scenario = new HtmlCapabilityGalleryScenario(
    "quarterly-report",
    "Quarterly Report",
    "Word HTML",
    "HTML import, DOCX validation, and round-trip export proof");

HtmlDiagnosticReport and the capability-gallery contracts provide a common shape for HTML converters, PDF bridges, readers, tests, and documentation generators.

Native adapters use HtmlConversionResult<TArtifact> when callers need conversion evidence. Each diagnostic has a stable code, severity, and LossKind (Approximation, Omission, or Failure). Convenience methods still return the native artifact directly; they throw HtmlConversionException when required semantic content is missing. Result methods retain the artifact and diagnostics so applications can decide how to handle the failure.

Conversion Document And Normalized HTML

var conversion = HtmlConversionDocumentBuilder.Build(html, new HtmlConversionDocumentOptions {
    Profile = HtmlConversionProfile.Document,
    Trust = HtmlInputTrust.Untrusted,
    BaseUri = new Uri("https://example.com/reports/"),
    UrlPolicy = HtmlUrlPolicy.CreateWebOnlyProfile()
});

string normalized = conversion.NormalizedHtml;
var resources = conversion.ResourcePlan.GetSummary(HtmlResourceKind.Image);
var styles = conversion.StyleSummary;

HtmlConversionDocument is the shared conversion contract for OfficeIMO HTML workflows. It parses once and retains one source DOM. Adapter DOMs, logical structure, computed styles, resources, and normalized output are created lazily when requested, then reused. This avoids paying for visual analysis during a semantic-only conversion and avoids retaining multiple eager document copies.

Target packages accept this shared document while keeping target-specific conversion in their owning packages. The prepared DOM can be sent to Word, Markdown, RTF, Excel, PowerPoint, OneNote, PDF, PNG, JPEG, TIFF, SVG, and WebP without inventing adapter-specific parsing rules. Excel and PowerPoint default to their versioned semantic envelopes for round trips and expose generic import mode for ordinary HTML. OneNote imports ordinary document sections directly.

Reuse the same document for analysis too: HtmlComputedStyleEngine.Compute(conversion) and HtmlRoundTripScorer.Compare(source, target) accept retained conversion documents. Their string overloads enter through the same bounded parser, so low-level helpers do not create competing trust or limit defaults.

Semantic IR and target preflight

HtmlConversionDocument source = HtmlConversionDocument.Parse(html);
HtmlSemanticDocument semantics = source.SemanticDocument;
HtmlConversionPreflight excel = source.AnalyzeFor(HtmlConversionTarget.Excel);

foreach (HtmlFeaturePreflightResult feature in excel.Features) {
    Console.WriteLine($"{feature.Feature}: {feature.Outcome} ({feature.OccurrenceCount})");
}

HtmlSemanticDocument is the single interpretation of sections, rich runs, nested lists, tables, links, forms, notes, resources, computed styles, and source locations. Generic Excel, PowerPoint, and OneNote importers consume it instead of independently deciding what the same DOM means. AnalyzeFor(target) uses the executable target registry to report Supported, Approximated, or Omitted before artifact creation. Diagnostics carry source and target provenance so applications can map a warning back to both sides of a conversion.

The generated HTML support matrix is checked against those executable contracts in the test suite. Run Build/Export-HtmlSupportMatrix.ps1 -Check to verify it or omit -Check to regenerate it.

Applications can inspect the same contract through HtmlRenderCapabilityCatalog.All. The catalog distinguishes full, partial, fallback, ignored, and rejected behavior and links partial behavior to stable diagnostic codes.

Resource sessions

var renderOptions = new HtmlRenderOptions {
    ResourceResolver = async (request, cancellationToken) =>
        await ResolveApprovedResourceAsync(request, cancellationToken)
};

HtmlResourceSession session = await HtmlResourceSession.ResolveAsync(
    source.ResourceManifest,
    renderOptions,
    cancellationToken: cancellationToken);

foreach (HtmlResourceSessionEntry resource in session.Resources) {
    Console.WriteLine($"{resource.CanonicalSource} {resource.ContentType} {resource.Sha256}");
}

The session owns one immutable policy and limit snapshot for the operation. It deduplicates canonical requests, validates MIME types, enforces request/count/per-resource/total-byte/import-depth budgets, and records accepted resource digests. Synchronous rendering uses the configured synchronous package resolver; application/network resolution remains an explicit asynchronous boundary.

Semantic envelope v2 and fidelity scoring

Current OfficeIMO semantic exports identify schema 2 and public-safe restoration metadata. Public-safe envelopes can be imported from untrusted input. A target-specific envelope marked trusted-target restores private target metadata only when the prepared input is trusted; otherwise the adapter uses the shared generic semantic path and reports the boundary. Schema 1 remains readable.

HtmlRoundTripScore score = HtmlRoundTripScorer.Compare(sourceHtml, exportedHtml);
Console.WriteLine(score.Dimensions["structure"]);
Console.WriteLine(score.Dimensions["styles"]);

// After the caller saves, reopens, and exports a native artifact:
HtmlArtifactReloadEvidence reload = HtmlArtifactReloadEvidence.Succeeded("DOCX", reopenedDocument.ToHtml());
HtmlRoundTripScore verified = HtmlRoundTripScorer.Compare(sourceHtml, exportedHtml, reload);
Console.WriteLine(verified.Dimensions["artifact-reload"]);

Version 2 scores top-level fidelity dimensions independently. A dimension absent from both inputs is omitted rather than counted as a perfect result. Artifact reload evidence is intentionally caller-supplied: the score is marked verified only when a native artifact was successfully reopened and its re-exported HTML was compared with the original source.

Conversion profile and trust are separate decisions. A Document or HighFidelityPrint profile does not make external resources trusted. Leave Trust as Untrusted for user-supplied HTML; set it to Trusted only when the caller controls the document and resource locations.

Normalized HTML output is policy-aware: hyperlink and resource URLs are evaluated separately, URL-bearing attributes are resolved against the configured base URI, disallowed URLs are removed, boolean attributes are normalized, event-handler attributes are stripped by default, and non-document executable elements are skipped. External bytes are loaded only through a caller-supplied bounded resolver. Normalized output is intended for clean review, gallery proof, and downstream adapter input selection, not as a browser sandbox.

Image Sources

string source = HtmlImageSourceResolver.ResolveImageSource(
    imageElement,
    baseUri,
    HtmlUrlPolicy.CreateOfficeIMOProfile());

Image Data URIs

if (HtmlImageDataUri.TryParse(source, out var dataUri) && dataUri.IsBase64) {
    byte[] bytes = dataUri.DecodeBytes();
    string extension = dataUri.FileExtension;
}