M3: Flatten Transparency engine (M3.91)

[bflatastic]

Part of M3 (Paint & appearance). The Flatten Transparency engine: transparent art becomes opaque art that looks the same, as Illustrator's Object ▸ Flatten Transparency does. The dialog, presets manager and Flattener Preview panel come in the next PR.

• M3.91: object.flattenTransparency {preset?, …options, options?, ids?} → {ids, rasterized, vector, options}.
  • Grouping: the targets (ids or the selection) are split into groups of overlapping objects.
    • Groups without transparency are left as they are, though Text to Outlines and Strokes to Outlines still apply.
    • Each group with transparency becomes one opaque group.
  • Atomic regions: the faces of the arrangement of every fill, outlined stroke and clipping path, each filled with an exactly computed flat colour.
    • A small compositor in cmd/flatten.rs follows the renderer's model: isolated and non-isolated groups, knockout and knockout shape, clip groups, all through color::blend::composite.
    • It composites over white, or over nothing with preserveAlpha.
  • One image stands in for regions reached by gradients, patterns, images, opacity masks or raster effects.
    • It sits one pixel larger under the vector regions, so there are no seams there.
    • It is clipped to those regions with clipComplexRegions.
    • Gradient-only regions use the gradient resolution.
  • Raster/vector balance: 0 rasterizes everything; 100 rasterizes only what must be.
  • Paint kept: a region showing a single paint keeps that paint (CMYK, spot or swatch) and its overprint, unless preserveOverprints: false.
  • Options: FlattenOptions with built-in presets high, medium (default) and low. One undo step.

docs/mcp.md has a "Flatten Transparency" section.

Known limits:

• Regions are drawn edge to edge, so on-screen anti-aliasing can show faint hairlines between them.
• Anti-alias off only hard-edges the rasterized art.
• Symbol instances are expanded to their art rather than rasterized whole.

Checks

Rebased onto cc51495 (#32). cargo xtask ci passes all 7 steps (fmt, clippy, test, assets, brands, layers, wasm): 1,588 tests, 0 failed.

tests_flatten.rs has 12 tests:

• Regions: two 50% rects give 3 regions matching the rendered pixels within 1/255.
• Blend modes: all 16 at 100% and 70% opacity, within 2/255 where the renderer rounds twice, and checked against the exact formula.
• Groups: knockout, knockout shape, non-isolated, isolated, blending, clip, and a group with its own fill.
• Balance: 0, 5 and 100, clipped and unclipped.
• Other inputs: gradients, opacity masks, and a mixed scene with text, a drop shadow and a symbol, with a render diff per preset.
• Options and edits: undo, preserve alpha, kept paints, outlining, and option errors.

🤖 Generated with Claude Code