FullBleed.DotNet 0.2.7

Fullbleed for .NET

Generate deterministic PDFs from HTML/CSS in C# with Fullbleed PDF Engine. Build invoices, reports and other print documents with an in-process Rust renderer. You can also author documents with C# components, LINQ and reusable styles. Both paths support native rendering, PNG previews, diagnostics and compiled variable-data publishing (VDP).

Try your HTML/CSS in the browser playground or browse designed PDF examples and their source. The library and its native bridge are MIT-licensed; bundled dependencies and fonts retain their own notices.

This repository contains two complementary integration layers:

• FullBleedEngine calls a small, panic-safe C ABI over the Rust engine. Use it for in-process rendering, high-volume batches, and compiled VDP.
• FullBleedCliClient calls the installed fullbleed command with argument-safe process APIs and structured JSON. Use it for runtime discovery, verification, profiles, assets, scaffolding, agent contracts, and commands that evolve independently of the native ABI.

The managed assembly has no third-party NuGet runtime dependencies. Native runtime libraries are packaged using NuGet's runtimes/{rid}/native/ convention. PDF generation requires neither a browser nor the operating system's PDF stack. Standard-font previews use bundled outlines; explicit fonts provide your chosen type design. Both work without installed system fonts.

Status

Version 0.2.7 uses Fullbleed 2.5.43. Radial gradients preserve their final color outside the ending shape, including opacity changes. Gradient stitching intervals are corrected as well. The managed APIs and native ABI are unchanged. The NuGet package ID is FullBleed.DotNet.

Component trees and styles are immutable after construction. Text and attributes are escaped, LINQ children are enumerated once, and custom components are normal methods returning elements. Read the component guide, including how class names and styles connect.

CI assembles one NuGet package and consumes it separately on each supported platform and .NET version. It checks the designed component invoice, paid/empty/credit variants, escaping, multi-page tables, class selectors, inline overrides, compiled bindings and batching with independent PDF readers. Existing font, layout and tagged-structure checks remain in the development workflow.

Supported package targets in the current build pipeline:

• win-x64
• linux-x64
• osx-x64
• osx-arm64

The managed library targets net8.0, which applications on .NET 8, 9, and 10 can reference. CI runs the same assembled NuGet package in applications targeting each of those frameworks on every platform above, checks the actual runtime version, and compares fixture PDFs, independent PDFium renders, and native previews with both embedded fonts and unembedded standard fonts. See the verification workflow and its retained cross-platform-evidence artifact.

Use .NET 10 LTS for a new application. Microsoft's support policy lists November 10, 2026 as the end of support for both .NET 8 and 9; a library's minimum target does not require your application to stay on that runtime.

Install and render

With the .NET 10 SDK installed:

dotnet new console -n FullbleedDemo --framework net10.0
cd FullbleedDemo
dotnet add package FullBleed.DotNet --version 0.2.7

HTML/CSS to PDF

Replace Program.cs with this complete example:

using FullBleed.DotNet;

const string html = """
    <h1>Quarterly report</h1>
    <p class="notice">Deterministic print output.</p>
    """;
const string css = """
    @page { size: A4; margin: 18mm; }
    body { font-family: Helvetica; }
    .notice { color: #315d9b; font-size: 18pt; }
    """;

using var engine = new FullBleedEngine(new FullBleedEngineOptions
{
    DocumentLanguage = "en-US",
    DocumentTitle = "Quarterly report",
});
engine.RenderPdfToFile(html, css, "output/report.pdf");
engine.RenderImagePagesToDirectory(html, css, "output/preview", dpi: 96);

Run dotnet run and open output/report.pdf. Existing .NET 8 and 9 projects use the same package and API. For template files, pass strings from File.ReadAllText("report.html") and File.ReadAllText("report.css"). For a web response, engine.RenderPdf(html, css) returns the PDF bytes.

The renderer accepts static HTML/CSS; render any Razor templates before passing them in. JavaScript execution and live webpage capture require a browser. The Northstar invoice below shows a complete document with explicit fonts and richer styling.

C# components and reusable styles

Alternatively, replace Program.cs with the component version. WithClass("notice") writes the class name; the .notice rule in StyleSheet supplies its styling.

using FullBleed.DotNet;
using FullBleed.DotNet.UI;
using static FullBleed.DotNet.UI.Components;

var styles = new StyleSheet
{
    ["@page"] = new Style { ["size"] = "A4", ["margin"] = "18mm" },
    ["body"] = new Style { ["font-family"] = "Helvetica" },
    [".notice"] = new Style { ["color"] = "#315d9b", ["font-size"] = "18pt" },
};
var report = new Document(
    Stack(Heading(1, "Quarterly report"),
        Paragraph("Deterministic print output.").WithClass("notice"))
) { Title = "Quarterly report", Styles = styles };

using var engine = new FullBleedEngine(new FullBleedEngineOptions
{
    DocumentLanguage = "en-US",
    DocumentTitle = report.Title,
});
report.RenderPdfToFile(engine, "output/report.pdf");
report.RenderImagePagesToDirectory(engine, "output/preview", dpi: 96);

Run it with the same dotnet run command. The component guide covers reusable methods, conditional children, inline styles and HTML/CSS export.

FullBleedRenderer.Render(...) and RenderToFile(...) remain as compatibility helpers for the original proof of concept.

An invoice made from components

The component invoice uses typed records, LINQ rows, shared styles, an amount panel and a paid-state variant. Its 40-row check flows across four pages with repeated table headers. Explicit fonts and their licenses are included.

dotnet run --project samples/FullBleed.DotNet.Components -c Release -- output/components

Edit InvoiceDocument.cs to change the data, reusable methods or styles. It writes the PDF, PNG previews, diagnostics and the generated HTML/CSS for inspection. No HTML strings are needed to author the invoice.

A styled invoice you can run

The Northstar sample uses explicit fonts, print dimensions, CSS grid, tables, color, and typographic hierarchy. All content is fictional. Font files and their OFL notices are included; rendering needs no network access or system fonts.

dotnet run --project samples/FullBleed.DotNet.Showcase -c Release -- output/northstar

This writes invoice.pdf and a PNG preview. The sample source shows font registration and missing-glyph diagnostics. The same document is also rendered from the assembled NuGet package in CI. Inspect the design and download its HTML/CSS.

The 0.1.4 family-selection fix corrects the invoice's brand to its intended regular face. The release check compares it with an explicit regular-face control, while preserving the original family CSS in the real invoice. It also checks bold text, fixed and reflow records, Unicode text, and both font registration orders. See how to reproduce the comparison.

The historical 0.1.3 font-compaction evidence records this invoice changing from 81,227 to 34,542 bytes with identical text and pixels. That measurement uses the earlier font selection; the 0.1.4 correction changes its appearance and size. Savings depend on the document and fonts.

LINQ and compiled VDP

LINQ remains the modern .NET projection/filtering API. Fullbleed's selector-based BindingMap<T> enumerates the result once and converts it into validated columnar bindings:

var invoices = Enumerable.Range(1, 1_000)
    .Select(i => new Invoice($"INV-{i:000000}", $"Customer {i}", 100m + i))
    .Where(invoice => invoice.Total >= 250m)
    .OrderBy(invoice => invoice.Id);

using var engine = new FullBleedEngine();
using var compiled = engine.Compile(
    "<h1>{{invoice_id}}</h1><p>{{customer}}</p><strong>USD {{total}}</strong>",
    "body { font-family: Helvetica, sans-serif; }");

compiled.RenderBindingsToFile(
    invoices,
    map => map
        .Bind("invoice_id", invoice => invoice.Id)
        .Bind("customer", invoice => invoice.Customer)
        .Bind("total", invoice => invoice.Total, "0.00"),
    "output/invoices.pdf");

Use RenderBindings* only for paint-only values whose geometry is reserved by the template. Use RenderReflowBindings* when values can wrap, reshape, change element size, or repaginate:

compiled.RenderReflowBindingsToFile(
    records,
    map => map
        .Bind("title", record => record.Title)
        .Bind("narrative", record => record.Narrative),
    "output/reflow.pdf",
    CompiledFlowCompression.Throughput);

Structural data-fb-bind-html values are trusted HTML. Construct them from escaped fields or pass them through an application-approved allowlist sanitizer; ordinary {{slot}} values remain literal text.

See the complete executable example in samples/FullBleed.DotNet.LinqVdp.

Batches, diagnostics, and previews

var jobs = records.Select(record => new RenderJob(BuildHtml(record), reportCss));
var batch = engine.RenderBatch(jobs, new BatchRenderOptions
{
    Parallel = true,
    IncludePageData = true,
});
File.WriteAllBytes("output/batch.pdf", batch.Pdf);

var diagnostic = engine.RenderPdfWithDiagnostics(html, css);
foreach (var missing in diagnostic.Diagnostics.MissingGlyphs)
{
    Console.WriteLine($"U+{missing.Codepoint:X4}: {missing.Count}");
}

var previews = engine.RenderImagePagesToDirectory(
    html,
    css,
    "output/preview",
    dpi: 144);

Batch jobs must use matching page geometry. Parallel native batching is used when jobs share CSS. Mixed-CSS jobs retain input order and use the ordinary ordered batch lane.

For unembedded standard fonts such as Helvetica or Times, the native previewer uses bundled outline substitutes and works without installed system fonts. Register explicit font files when you need a particular type design. The styled invoice sample includes its fonts.

Runtime-authoritative CLI access

The CLI layer never assumes the installed release has the same surface as the compiled native package:

var client = new FullBleedCliClient();
var capabilities = await client.GetCapabilitiesAsync();
var contract = await client.GetAgentContractAsync();
var renderSchema = await client.GetSchemaAsync(["render"]);

var result = await client.RenderAsync(new FullBleedCliRenderRequest
{
    Html = "<h1>CLI render</h1>",
    Css = "body { font-family: Helvetica, sans-serif; }",
    OutputPath = "output/cli.pdf",
    Profile = "preflight",
    FailOn = ["overflow", "missing-glyphs"],
    EmitImageDirectory = "output/cli-preview",
});

result.EnsureSuccess();

RunAsync and RunJsonAsync expose every installed command without shell interpolation. Typed render/verify requests cover the current document flags, while AdditionalArguments and the generic runner provide forward compatibility.

Surface map

More detail is in docs/api.md, docs/native-abi.md, and docs/development.md.

PDF profiles and claims

Selecting PdfUa1, PdfUa2, a PDF/A profile, PDF/X, PDF/VT, WTPDF, or Tagged changes engine output configuration; it does not by itself prove conformance or accessibility. Supply the required embedded fonts/output intent, run Fullbleed verification, retain diagnostics, and use the applicable independent conformance checker before making claims.

Packaging

To build from source, install the .NET 8 SDK and Rust 1.85 or later, then run:

./scripts/build-native.ps1
dotnet test FullBleed.DotNet.sln -c Release

Cargo downloads the exact engine release from crates.io. No sibling checkout is required.

Build the current platform package locally:

./scripts/pack.ps1

Cross-platform release packages must contain every claimed RID asset. CI checks the binary architecture, retained license texts, and dependency provenance inside the final .nupkg, then tests it on each matching OS. The managed assembly has no third-party NuGet runtime dependencies; the separate CLI adapter requires an independently installed Fullbleed Python CLI. Details are in docs/development.md.

License

MIT. See LICENSE and THIRD_PARTY_NOTICES.md.