Groups

A group is a container layer. Anything inside it (other layers — including more groups) renders together, transforms together, and can blend or clip as a single unit.

#Why groups matter

Without groups, a rich design becomes a flat list of 50+ items in the layers panel. Groups let you:

• Treat a logo as one thing. Move, scale, and apply effects to the whole logo without per-layer fiddling.
• Apply blend / opacity once. A drop shadow on the group shadows the merged silhouette, not each child individually.
• Show / hide a section of the design with one toggle.
• Clip a whole group to the layer beneath.
• Nest — groups inside groups inside groups.

#Creating a group

• Select two or more layers
• Ctrl+G — wrap the selection in a new group
• The group appears in the layers panel with a chevron; click it to expand / collapse

To pull layers back out: select the group and Ctrl+Shift+G.

#Group properties

Each group carries:

• id — stable identifier
• name — editable label in the layers panel
• children — ordered array of layer / group ids
• opacity — applied to the merged group result
• blendMode — applied to the merged group result
• clipToBelow — same toggle as for leaf layers
• effects — group-level shadow / glow / stroke (planned for richer effect parity with leaves)
• visible, locked

When you adjust group opacity, the editor first composites all children to an offscreen canvas, then applies the group opacity once. That's why opacity 50% on a group with overlapping shapes looks different from setting each child to 50% — the latter would let children show through each other.

#Reordering across groups

Drag a layer in the layers panel to:

• Move it inside a group (drop on the group's row)
• Move it out (drop on a parent or empty space)
• Reorder among siblings

Keyboard Ctrl+] / Ctrl+[ moves within the current parent.

#Schema notes

groups is a top-level array on the document state — separate from layers. Each layer carries an optional groupId pointer to its parent group.

Why this shape? Because:

• It keeps z-order trivial (still one flat list of layer ids).
• Group metadata (opacity, blend) doesn't need to be re-derived from a tree walk.
• Serialization stays additive — pre-Tier-1 documents without groups load unchanged.

The Tier 1 schema bump (v1 → v2) made groups a required array (default []). Older v1 files migrate automatically — see The .img format.

#Performance tips

• Flatten heavy groups when possible. A rasterize-group action (planned) will collapse a static group to a single bitmap layer for faster rendering.
• Keep nesting shallow. 3–4 levels is comfortable; 10+ levels of nested groups slow the layers panel re-render.
• Group effects render in the worker. Pixel-heavy operations don't block dragging.