Simplify ChartForgeX document placement and preserve layout

Build/Test-AotProjectCoverage.ps1

@@ -123,6 +123,11 @@ $nonNativeValidated = @(
         classification = 'managed-cross-platform'
         evidence = 'Static Mermaid Word/PDF/HTML/PowerPoint integration, packed .NET 8 and 10 consumers and .NET Framework 4.7.2 cross-compilation are validated; complete adapter NativeAOT qualification is separate.'
     }
+    [ordered]@{
+        name = 'OfficeIMO.ChartForgeX.Examples'
+        classification = 'managed-cross-platform'
+        evidence = 'The document-delivery example is a managed .NET application qualified through saved-format and rendered artifact checks; NativeAOT execution is not claimed.'
+    }
     [ordered]@{
         name = 'OfficeIMO.Browser'
         classification = 'managed-cross-platform'

MIGRATION.md

@@ -1060,6 +1060,54 @@ File overloads reject an oversized source before buffering. Applications that
 previously attached larger XML must reduce or split the payload before using
 these methods.
 
+## ChartForgeX 2.0 adapter integration
+
+`OfficeVisualConversionOptions.SvgPolicy` defaults to `RasterizeWhenNeeded` to
+preserve appearance when vector import is incomplete. Set `PreserveVector`
+explicitly to retain the previous imported-vector behavior, or `RequireVector`
+to reject unsupported content. Inspect the existing conversion report for
+fallback, approximation and omission diagnostics.
+
+When both `WidthPoints` and `HeightPoints` are supplied, `Fit` defaults to
+`OfficeImageFit.Contain`. Set `Fit = OfficeImageFit.Stretch` for the previous exact
+width-and-height sizing. A single dimension still preserves proportions.
+
+`AddVisualArtifact(artifact)` inserts directly. Word constrains an oversized
+visual to its paragraph's authored content-width estimate when no explicit size
+is supplied. PDF constrains oversized visuals to the current flow width by
+default; a custom `PdfDrawingStyle` controls `ConstrainToContentWidth` explicitly.
+The existing conversion-result overloads retain explicit Word placement.
+Use worksheet ranges and `PowerPointLayoutBox` for bounded placement.
+`OfficeVisualConversionResult.WithSize` resizes retained content without another
+render/import; prepare again to change label layout or typography. Use
+`OfficeVisualDocumentStyle.CreateContext` to prepare at the intended point size.
+
+Native Visio graph titles measure their saved text at the configured native font.
+`Title(..., height: ...)` supplies a minimum height. Preserved ChartForgeX geometry
+keeps its node and route positions; a title that cannot fit its free header
+corridor is omitted with `TitleNotProjected` rather than covering those objects.
+
+Rebuild callers of `OfficeIMO.ChartForgeX` against ChartForgeX 2.0. The bridge keeps
+its core-only ChartForgeX dependency. Add `ChartForgeX.Visuals` to the application
+when rendering factual tables, canvases, or watermarks; optional story and motion
+producers belong to `ChartForgeX.Stories`. Pass their common static artifacts to
+the existing `ToOfficeVisual` and document-placement APIs.
+
+Replace `VisualArtifactRenderOptions.Watermarks.Add(watermark)` with
+`artifact.WithWatermarks(watermark)` before conversion. Native editable Visio
+does not project those static layers. Inspect `WatermarkNotProjected`, or reject
+it through `RejectedDiagnostics`/`RequireLossless`; the diagnostic also survives
+interchange envelope and UTF-8 JSON handoff.
+
+Use `prepared.ToArtifact(id, kind)` when placing a prepared chart or diagram.
+It retains the resolved viewport, accessible text, and producer-owned semantics.
+Complete topology projection consumes resolved connector routes and label bounds;
+unprepared envelopes retain the authored waypoint and named-port contract.
+Flow and sequence keep native editable semantics with `LayoutRecomputed` and
+reject `LayoutMode = Preserve`. Their native page does not promise the prepared
+scene's placement. The Markdown companion uses `ChartForgeX.Markup.Mermaid` 2.0
+and keeps static fence materialization and document placement in their owners.
+
 ## Native ChartForgeX topology placement
 
 `OfficeVisioVisualOptions.LayoutMode` defaults to `Auto`. A topology envelope with complete viewport, node, and included-group bounds now keeps those bounds instead of being laid out again. `PixelsPerInch` controls their physical size. Set `LayoutMode = OfficeVisioVisualLayoutMode.Reflow` to retain the previous native-layout behavior. Flow, sequence, and incomplete topology envelopes continue to use native layout in `Auto` mode. Native graph styling now uses source theme colors with portable Arial text; set `NativeTheme = VisioStyleTheme.Technical()` to retain the previous native palette and typography.

OfficeIMO.ChartForgeX.Examples/DeliveryEvidence.cs

@@ -0,0 +1,48 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using OfficeIMO.Drawing;
+using OfficeIMO.Excel;
+using OfficeIMO.Pdf;
+using OfficeIMO.PowerPoint;
+using OfficeIMO.Visio;
+using OfficeIMO.Word;
+
+namespace OfficeIMO.ChartForgeX.Examples;
+
+internal static class DeliveryEvidence {
+    private static readonly JsonSerializerOptions JsonOptions = new() {
+        WriteIndented = true, Converters = { new JsonStringEnumConverter() }
+    };
+
+    public static void RenderSavedDocuments(string output) {
+        using (var document = WordDocument.Load(Path.Combine(output, "service-review.docx"))) {
+            SaveImages(output, "word-layout", document.ExportImages(OfficeImageExportFormat.Png));
+            SaveImages(output, "word-layout", document.ExportImages(OfficeImageExportFormat.Svg));
+        }
+        using (var document = ExcelDocument.Load(Path.Combine(output, "service-review.xlsx")))
+            SaveImages(output, "excel-layout", document.ExportImages(OfficeImageExportFormat.Png,
+                new ExcelWorkbookImageExportOptions { ShowGridlines = false }));
+        using (var document = PowerPointPresentation.Load(Path.Combine(output, "service-review.pptx")))
+            SaveImages(output, "powerpoint-layout", document.ExportImages(OfficeImageExportFormat.Png));
+        var pdf = PdfDocument.Load(File.ReadAllBytes(Path.Combine(output, "service-review.pdf")));
+        SaveImages(output, "saved-pdf", pdf.Render.ExportImages(OfficeImageExportFormat.Png));
+        var visio = VisioDocument.Load(Path.Combine(output, "service-delivery.vsdx"));
+        SaveImages(output, "visio-layout", visio.ExportImages(OfficeImageExportFormat.Png));
+        SaveImages(output, "visio-layout", visio.ExportImages(OfficeImageExportFormat.Svg));
+    }
+
+    private static void SaveImages(string output, string route, IReadOnlyList<OfficeImageExportResult> images) {
+        if (images.Count == 0) throw new InvalidOperationException(route + " did not render a saved document image.");
+        var reports = new List<object>();
+        for (int index = 0; index < images.Count; index++) {
+            var image = images[index];
+            string fileName = route + "-" + (index + 1).ToString("D2") +
+                (image.Format == OfficeImageExportFormat.Svg ? ".svg" : ".png");
+            File.WriteAllBytes(Path.Combine(output, fileName), image.Bytes);
+            reports.Add(new { File = fileName, image.Width, image.Height, image.Diagnostics });
+        }
+        SaveJson(Path.Combine(output, route + "-" + images[0].Format.ToString().ToLowerInvariant() + ".json"), reports);
+    }
+
+    public static void SaveJson<T>(string path, T value) => File.WriteAllText(path, JsonSerializer.Serialize(value, JsonOptions));
+}

OfficeIMO.ChartForgeX.Examples/DocumentDelivery.cs

@@ -0,0 +1,117 @@
+using global::ChartForgeX.Themes;
+using global::ChartForgeX.VisualArtifacts;
+using OfficeIMO.Excel;
+using OfficeIMO.Pdf;
+using OfficeIMO.PowerPoint;
+using OfficeIMO.Word;
+
+namespace OfficeIMO.ChartForgeX.Examples;
+
+internal static class DocumentDelivery {
+    private static readonly OfficeVisualDocumentStyle Style = OfficeVisualDocumentStyle.Default;
+    public static void Write(string output, IReadOnlyList<VisualSpecimen> specimens) {
+        foreach (var specimen in specimens) {
+            File.WriteAllText(Path.Combine(output, "source-" + specimen.Name + ".svg"), specimen.Artifact.ToSvg());
+            File.WriteAllBytes(Path.Combine(output, "source-" + specimen.Name + ".png"), specimen.Artifact.ToPng());
+        }
+        WriteWord(Path.Combine(output, "service-review.docx"), specimens);
+        WriteExcel(Path.Combine(output, "service-review.xlsx"), specimens);
+        WritePowerPoint(Path.Combine(output, "service-review.pptx"), specimens);
+        WritePdf(Path.Combine(output, "service-review.pdf"), specimens);
+        WriteVisio(output, specimens);
+        DeliveryEvidence.SaveJson(Path.Combine(output, "visual-conversions.json"), specimens.Select(item => {
+            var conversion = item.Convert(450D);
+            return new { item.Name, item.ModeName, conversion.Id, conversion.WidthPoints, conversion.HeightPoints,
+                conversion.AlternativeText, conversion.PlacementMediaType, conversion.Report };
+        }));
+    }
+
+    private static void WriteWord(string path, IReadOnlyList<VisualSpecimen> specimens) {
+        using var document = WordDocument.Create(path);
+        document.Sections[0].PageSettings.PageSize = WordPageSize.A4;
+        document.Margins.Type = WordMargin.Normal;
+        for (int index = 0; index < specimens.Count; index++) {
+            if (index > 0) document.AddPageBreak();
+            var specimen = specimens[index];
+            var heading = document.AddParagraph().AddText(Heading(specimen));
+            heading.FontFamily = Style.FontFamily; heading.FontSizePoints = Style.HeadingSizePoints;
+            document.AddParagraph().AddVisualArtifact(specimen.Artifact);
+            var caption = document.AddParagraph().AddText(specimen.Caption);
+            caption.FontFamily = Style.FontFamily; caption.FontSizePoints = Style.CaptionSizePoints;
+        }
+        document.Save();
+    }
+
+    private static void WriteExcel(string path, IReadOnlyList<VisualSpecimen> specimens) {
+        using var document = ExcelDocument.Create(path);
+        foreach (var specimen in specimens) {
+            var sheet = document.AddWorksheet(specimen.Name);
+            for (int column = 1; column <= 9; column++) sheet.SetColumnWidth(column, 12D);
+            for (int row = 1; row <= 26; row++) sheet.SetRowHeight(row, 18D);
+            sheet.MergeRange("B1:I2");
+            sheet.CellValue(1, 2, Heading(specimen));
+            sheet.CellFontName(1, 2, Style.FontFamily); sheet.CellFontSize(1, 2, Style.HeadingSizePoints);
+            // The picture remains within the authored Letter print width after the half-inch margins.
+            sheet.SetPageSetup(fitToWidth: 1, fitToHeight: 0, paperSize: ExcelPaperSize.Letter);
+            sheet.SetMarginsPreset(ExcelMarginPreset.Narrow);
+            sheet.AddVisualArtifact("B4:I18", specimen.Artifact);
+            sheet.MergeRange("B21:I23");
+            sheet.CellValue(21, 2, specimen.Caption);
+            sheet.CellFontName(21, 2, Style.FontFamily); sheet.CellFontSize(21, 2, Style.CaptionSizePoints);
+            sheet.CellWrapText(21, 2);
+        }
+        document.Save();
+    }
+
+    private static void WritePowerPoint(string path, IReadOnlyList<VisualSpecimen> specimens) {
+        using var presentation = PowerPointPresentation.Create(path);
+        presentation.SlideSize.SetPreset(PowerPointSlideSizePreset.Screen16x9);
+        double slideWidth = presentation.SlideSize.WidthPoints, slideHeight = presentation.SlideSize.HeightPoints;
+        foreach (var specimen in specimens) {
+            var slide = presentation.AddSlide();
+            var colors = VisualTheme.Graphite().Resolve(specimen.Mode);
+            slide.BackgroundColor = colors.Background.ToHex().TrimStart('#');
+            Text(slide, Heading(specimen), 36D, 16D, slideWidth - 72D, 30D, Style.HeadingSizePoints, colors.Foreground.ToHex());
+            slide.AddVisualArtifact(specimen.Artifact,
+                PowerPointLayoutBox.FromPoints(36D, 60D, slideWidth - 72D, slideHeight - 130D));
+            Text(slide, specimen.Caption, 36D, slideHeight - 52D,
+                slideWidth - 72D, 36D, Style.CaptionSizePoints, colors.Foreground.ToHex());
+        }
+        presentation.Save();
+    }
+
+    private static void WritePdf(string path, IReadOnlyList<VisualSpecimen> specimens) {
+        var options = new PdfOptions { PageSize = PageSizes.A4, DefaultFontSize = Style.CaptionSizePoints };
+        options.EnableTaggedPdfCatalogMarkers();
+        PdfDocument.Create(document => document.Content(content => {
+            for (int index = 0; index < specimens.Count; index++) {
+                if (index > 0) content.PageBreak();
+                var specimen = specimens[index];
+                content.H1(Heading(specimen));
+                content.AddVisualArtifact(specimen.Artifact, spacingBefore: 12D, spacingAfter: 18D);
+                content.Text(specimen.Caption);
+            }
+        }), options).Save(path);
+    }
+
+    private static void WriteVisio(string output, IReadOnlyList<VisualSpecimen> specimens) {
+        var diagrams = specimens.Where(item => item.EditableTopology).ToArray();
+        var book = diagrams.Select(item => item.Artifact.ToInterchangeEnvelope()).ToOfficeVisioBook(
+            new OfficeVisioVisualOptions { LayoutMode = OfficeVisioVisualLayoutMode.Preserve, PixelsPerInch = 96D });
+        book.Document.Save(Path.Combine(output, "service-delivery.vsdx"));
+        DeliveryEvidence.SaveJson(Path.Combine(output, "native-visio-fidelity.json"), book.Pages.Select((page, index) => new {
+            diagrams[index].Name, page.Report, page.Page.Width, page.Page.Height,
+            Shapes = page.Page.Shapes.Select(shape => new { shape.Id, shape.Text, shape.PinX, shape.PinY, shape.Width, shape.Height }),
+            Connectors = page.Page.Connectors.Select(edge => new { edge.Id, edge.Label, edge.Waypoints.Count })
+        }));
+    }
+
+    private static void Text(PowerPointSlide slide, string text, double left, double top, double width, double height,
+        double size, string color) {
+        var box = slide.AddTextBox(text, PowerPointUnits.FromPoints(left), PowerPointUnits.FromPoints(top),
+            PowerPointUnits.FromPoints(width), PowerPointUnits.FromPoints(height));
+        box.FontName = Style.FontFamily; box.FontSize = (int)Math.Round(size); box.Color = color.TrimStart('#');
+    }
+
+    private static string Heading(VisualSpecimen specimen) => specimen.Artifact.Title + " · " + specimen.ModeName;
+}

OfficeIMO.ChartForgeX.Examples/OfficeIMO.ChartForgeX.Examples.csproj

@@ -0,0 +1,12 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net8.0;net10.0</TargetFrameworks>
+    <IsPackable>false</IsPackable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+  <ItemGroup>
+    <ProjectReference Include="../OfficeIMO.ChartForgeX/OfficeIMO.ChartForgeX.csproj" />
+  </ItemGroup>
+</Project>

OfficeIMO.ChartForgeX.Examples/Program.cs

@@ -0,0 +1,25 @@
+using OfficeIMO.ChartForgeX.Examples;
+using OfficeIMO.PowerPoint;
+
+if (args.Length is < 1 or > 2 || (args.Length == 2 && args[1] != "--native-powerpoint")) {
+    Console.Error.WriteLine("Usage: OfficeIMO.ChartForgeX.Examples <output-directory> [--native-powerpoint]");
+    return 1;
+}
+
+string output = Path.GetFullPath(args[0]);
+Directory.CreateDirectory(output);
+var specimens = VisualSpecimens.Create();
+DocumentDelivery.Write(output, specimens);
+DeliveryEvidence.RenderSavedDocuments(output);
+
+if (args.Length == 2) {
+    var result = PowerPointDesktopReferenceRenderer.TryRender(
+        Path.Combine(output, "service-review.pptx"), Path.Combine(output, "powerpoint-desktop"), enabled: true);
+    DeliveryEvidence.SaveJson(Path.Combine(output, "powerpoint-desktop.json"), result);
+    Console.WriteLine("PowerPoint Desktop: " + result.Status + ": " + result.Message);
+    if (!result.IsSuccessful) return 2;
+}
+
+Console.WriteLine("Saved documents and managed previews: " + output);
+Console.WriteLine("Managed previews describe OfficeIMO layout; they do not establish Microsoft Office application rendering.");
+return 0;

OfficeIMO.ChartForgeX.Examples/README.md

@@ -0,0 +1,28 @@
+# ChartForgeX document delivery example
+
+This executable places the same prepared service chart and topology in Word, Excel, PowerPoint and PDF. It uses the shared paired Graphite palette, the adapter's document typography style, full accessible descriptions and destination-aware insertion. A repeated light chart follows the dark variant, exercising reuse without treating an artifact identifier as an image-content identifier.
+
+The visual viewport is 600 × 360 logical pixels, prepared for a 450 × 270 point placement with `OfficeVisualDocumentStyle.Default`. Axis and legend text is 11.25 points at that size. Word and PDF constrain natural-size visuals to the available content width. Excel fits an authored cell range and PowerPoint fits a layout box, keeping chart proportions and reserving separate heading and caption space. The workbook uses an authored Letter print layout. Dark visuals retain their own filled canvas on white document pages; PowerPoint slide backgrounds use the selected palette.
+
+Run from the repository root with the adapter's ChartForgeX source-project configuration or a local qualified 2.0.0 package feed:
+
+```powershell
+$outputRoot = if ($env:EVOTEC_SCRATCH_ROOT) { $env:EVOTEC_SCRATCH_ROOT } else { [System.IO.Path]::GetTempPath() }
+if (-not (Test-Path -LiteralPath $outputRoot -PathType Container)) { throw 'The configured output volume is not available.' }
+$outputDirectory = Join-Path $outputRoot 'officeimo-chartforgex-delivery'
+dotnet run --project ./OfficeIMO.ChartForgeX.Examples/OfficeIMO.ChartForgeX.Examples.csproj -c Release -f net10.0 -- $outputDirectory
+```
+
+The output directory contains the source SVG/PNG images, a five-page DOCX/PDF, a five-sheet XLSX, a five-slide PPTX, and a two-page editable topology VSDX. The JSON reports describe placement conversion and native Visio fidelity. Managed PNG previews reopen the saved files and render their document layouts; SVG previews expose the saved editable Visio geometry.
+
+Managed Word previews use OfficeIMO's estimated pagination. Managed Excel and PowerPoint previews use their respective layout engines. Saved-PDF previews render the serialized PDF page content. These are distinct from Microsoft Office application rendering and must be assessed separately when an application-specific fidelity claim is needed.
+
+On Windows with PowerPoint Desktop installed, reuse that output directory and explicitly request its existing reference-render lane:
+
+```powershell
+dotnet run --project ./OfficeIMO.ChartForgeX.Examples/OfficeIMO.ChartForgeX.Examples.csproj -c Release -f net10.0 -- $outputDirectory --native-powerpoint
+```
+
+That opt-in produces `powerpoint-desktop/` and a separate result report. Unavailable or failed native rendering returns a nonzero exit code; it does not fall back to managed images and claim native proof. Ordinary generation and managed rendering do not launch Office applications.
+
+The editable Visio specimen uses prepared topology bounds and connector routes. Its report retains styling, font, accessibility and other conversion limits. Flow and sequence diagrams use their existing native reflow policy; this example does not establish exact editable layout preservation for those families.