Simplify ChartForgeX document placement and preserve layout

MIGRATION.md

@@ -841,6 +841,29 @@ 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
+
+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,119 @@
+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 {
+    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;
+        double usableWidth = ((document.Sections[0].PageSettings.Width ?? throw new InvalidOperationException("Missing page width."))
+            - document.Margins.Left - document.Margins.Right) / 20D;
+        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 = "Arial"; heading.FontSizePoints = 18D;
+            document.AddParagraph().AddVisualArtifact(specimen.Convert(usableWidth));
+            var caption = document.AddParagraph().AddText(specimen.Caption);
+            caption.FontFamily = "Arial"; caption.FontSizePoints = 11D;
+        }
+        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, "Arial"); sheet.CellFontSize(1, 2, 18D);
+            // 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(4, 2, specimen.Convert(612D - 72D));
+            sheet.MergeRange("B21:I23");
+            sheet.CellValue(21, 2, specimen.Caption);
+            sheet.CellFontName(21, 2, "Arial"); sheet.CellFontSize(21, 2, 11D);
+            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, 18, colors.Foreground.ToHex());
+            var conversion = specimen.Convert(slideWidth - 72D);
+            slide.AddVisualArtifact(conversion, (slideWidth - conversion.WidthPoints) / 2D, 60D);
+            Text(slide, specimen.Caption, 36D, Math.Min(slideHeight - 52D, 60D + conversion.HeightPoints + 18D),
+                slideWidth - 72D, 36D, 11, colors.Foreground.ToHex());
+        }
+        presentation.Save();
+    }
+
+    private static void WritePdf(string path, IReadOnlyList<VisualSpecimen> specimens) {
+        var options = new PdfOptions { PageSize = PageSizes.A4, DefaultFontSize = 11D };
+        options.EnableTaggedPdfCatalogMarkers();
+        double usableWidth = options.PageWidth - options.MarginLeft - options.MarginRight;
+        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.Convert(usableWidth), 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,
+        int size, string color) {
+        var box = slide.AddTextBox(text, PowerPointUnits.FromPoints(left), PowerPointUnits.FromPoints(top),
+            PowerPointUnits.FromPoints(width), PowerPointUnits.FromPoints(height));
+        box.FontName = "Arial"; box.FontSize = 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,25 @@
+# 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 with document-sized typography, full accessible descriptions and explicit placement dimensions. 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. Placements use at most 450 points of width and also respect the actual page or slide content width. Axis and legend text is 15 logical pixels, or 11.25 points at the full placement size. The workbook uses an authored Letter print layout; its picture, heading and full caption occupy separate rows. 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
+dotnet run --project ./OfficeIMO.ChartForgeX.Examples/OfficeIMO.ChartForgeX.Examples.csproj -c Release -f net10.0 -- <scratch-root>/officeimo-chartforgex-delivery
+```
+
+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, explicitly request its existing reference-render lane:
+
+```powershell
+dotnet run --project ./OfficeIMO.ChartForgeX.Examples/OfficeIMO.ChartForgeX.Examples.csproj -c Release -f net10.0 -- <scratch-root>/officeimo-chartforgex-delivery --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.