PAGX File Structure Optimization

This skill provides a systematic checklist for optimizing PAGX file structure. The goals are to simplify file structure, reduce file size, and improve rendering performance.

Fundamental Constraint

All optimizations must preserve the original design appearance. This is a hard requirement that overrides any individual optimization direction below.

• •Allowed: Structural transformations that produce identical or near-identical rendering (minor pixel-level differences from node reordering or painter merging are acceptable).
• •Allowed: Removing provably invisible content — elements entirely outside the canvas bounds, unused resources, zero-width strokes, fully transparent elements, and other content that contributes nothing to the final rendered image.
• •Forbidden: Modifying any parameter that affects design intent — blur radius, spacing, density, colors, alpha, gradient stops, font sizes, shadow offsets, stroke widths, or any other visual attribute — unless the user explicitly approves the change.
• •Forbidden: Reducing Repeater density (increasing spacing), lowering blur values, changing opacity, or simplifying geometry in ways that alter the visual result, even if the change seems minor. These are design decisions, not optimization decisions.
• •When in doubt: If an optimization might change the rendered appearance, do not apply it. Instead, describe the potential optimization and its visual impact to the user, and ask for explicit approval before proceeding.

Optimization Checklist

Structure Cleanup (Sections 1-7)

For detailed examples and default value tables, read references/structure-cleanup.md.

Painter Merging (Sections 8-9)

Critical caveat (Section 8): Different geometry needing different painters must be isolated with Groups. This is the most common source of errors.

For detailed examples and scope isolation patterns, read references/painter-merging.md.

Resource Reuse (Sections 10-14)

For detailed examples and coordinate conversion formulas, read references/resource-reuse.md.

Performance Optimization (Section 15)

Rendering Cost Model:

• •Repeater: N copies = N× full rendering cost (no GPU instancing)
• •Nested Repeaters: Multiplicative (A×B elements)
• •BlurFilter / DropShadowStyle: Cost proportional to blur radius
• •Dashed Stroke under Repeater: Dash computation per copy
• •Layer vs Group: Layer creates extra surface; Group is lighter

Two categories:

1. •Equivalent (auto-apply): Downgrade Layer to Group, clip Repeater to canvas bounds
2. •Suggestions (never auto-apply): Reduce density, lower blur, simplify geometry

For detailed optimization techniques, read references/performance.md.

Appendix: Core Concepts

Painter Scope

Painters (Fill / Stroke) render all geometry accumulated in the current scope up to that painter's position. Subsequent painters continue to render the same geometry.

Group Scope Isolation

Group creates an isolated scope. Internal geometry accumulates only within the Group, and after the Group ends, its geometry propagates upward to the parent scope.

Layer vs Group

Selection rule: Use Layer for styles/filters/mask/composition/blendMode. Otherwise prefer Group.

For DropShadowStyle scope and color source coordinate system, see references/painter-merging.md and references/resource-reuse.md respectively.

PAGX Specification Quick Reference

For complete attribute defaults, required attributes, and enumeration values extracted from the PAGX spec, see references/pagx-quick-reference.md.