Rendering Pipeline

August 24, 2026 ยท View on GitHub

This document describes the intended pipeline from authoring input to preview, export, and parse outputs.

Pipeline Stages

The architecture should treat the system as multiple related paths built around normalized document state.

Shared stages include:

  1. Authoring input is expressed through the Authoring Model.
  2. The system normalizes that input into the Canonical Presentation IR.
  3. Layout logic computes normalized placement and sizing information.
  4. Directional transforms feed preview, export, or parse results.

Authoring Path

Authoring API
    |
    v
Authoring Model
    |
    v
Normalization
    |
    v
Canonical Presentation IR

SVG Normalization Path

Raw SVG
   |
   v
@pptkit/svg-parser
   |
   v
Normalized SVG structures
   |
   v
@pptkit/svg-renderer
   |
   v
Canonical Presentation IR or export-ready drawing structures

This path exists to keep SVG handling explicit instead of letting format-specific logic leak across the system.

Preview Path

Canonical Presentation IR
    |
    v
 Layout Resolution (export-ready IR)
    |
    v
Preview Transform
    |
    v
Preview Output

The implemented preview transform is @pptkit/svg-renderer. It consumes the detached LayoutResult, combines layout-static and slide-local drawing order, and returns one standalone hybrid SVG string per slide. Asset paths remain an environment-adapter concern.

The preview path should remain derived from normalized document state rather than becoming the system of record.

Export Path

Canonical Presentation IR
    |
    v
Layout Resolution
    |
    v
 PPTX Export (OOXML package writer)
    |
    v
PPTX Package Model
    |
    v
.pptx

Parse Path

.pptx
    |
    v
PPTX Package Model
    |
    v
Package Inspection
    |
    v
Normalization
    |
    v
Canonical Presentation IR

Export Boundary

@pptkit/layout owns the detached layout result: page size, ordered slides, ordered elements, geometry, and normalized styles. @pptkit/pptx-exporter owns asset I/O, OOXML parts, relationships, ZIP packaging, and export diagnostics. Neither package becomes the authoring source of truth.

The export path normalizes the authoring document exactly once, passes that normalized IR to resolveNormalizedLayout, and then passes the detached layout result to the exporter package builder. resolveLayout(document) is the authoring convenience entry point; downstream pipelines should prefer the normalized entry point.

The runtime-neutral exporter entry orchestrates asset loading, OOXML generation, package-part collection, and ZIP encoding into Uint8Array output. Filesystem output and local-path asset loading belong to the explicit Node.js subpath, so importing the default entry never pulls Node built-ins into a browser dependency graph.

The SVG renderer is a sibling output transform rather than an exporter implementation detail. It does not read PPTX packages or reuse OOXML serializers. Its browser preview may warn and degrade independently while preserving the same Core/Layout semantics. A cross-renderer parity test validates that chart output remains consistent between the SVG renderer and PPTX exporter.

For charts, Layout owns output-neutral geometry and placement semantics. In particular, legend row/column flow and category-axis label/tick anchoring are resolved before either output transform runs. SVG draws the resolved item boxes directly; PPTX maps the same semantics to native chart position and axis settings rather than injecting a manual legend box that Office can responsively reflow.

The exporter writes one theme and master plus the normalized reusable slide-layout roster. Placeholder bindings, layout backgrounds, static layout content, notes, and slide-local content remain separate native package structures without leaking OOXML into @pptkit/core.

Why Use a Pipeline

A staged pipeline gives the project better control over:

  • Validation
  • Error reporting
  • Intermediate testing
  • Feature fallback behavior
  • Future support for other import or export paths

Failure Handling

The pipeline should prefer predictable degradation over silent corruption.

Examples:

  • Unsupported SVG features should surface clear warnings or documented fallback behavior.
  • Export validation should fail early when the model cannot be represented safely.
  • Parse failures should preserve diagnostics that help contributors reproduce issues.
  • Unknown OOXML structures should be preserved where practical instead of silently discarded.

Long-Term Value

Once this pipeline is stable, the project can grow more safely into:

  • Better layout systems
  • Richer asset support
  • Import workflows
  • Plugin hooks
  • Benchmarking and regression tests