[XDGFX]

Stacked on #9 (coil-pipes).

Summary

A plumbing plan, or a prepended file, can frame parts that sit together, such as everything in one enclosure.

groups:
  water_box:
    label: WATER BOX                      # optional title, top left
    members: [pump, accumulator, tee.t1]  # parts as a chain names them

 root (ELK layered)
+  elk.hierarchyHandling: INCLUDE_CHILDREN      # only when the sheet has groups
   card, card, ...
+  frame:water_box                              # compound node, padded for its title
+    member cards
+    turn node, when both its ends are members
   turn nodes

• The frame holds its members and no other card; pipes cross the border. It is drawn first, beneath cards and pipes, dashed in the theme's faint colour.
• A fresh instance (adapter.) cannot be a member. A fitting between two members that is not listed is drawn outside the frame, and its pipes go the long way round; the docs say to name it and list it.
• A member no chain names is left out; a group with none drawn is an error, as are an undeclared component, a pipe, a part listed twice or in two groups, and any key but label and members.
• diagram.wrap works: a frame is kept whole on one row.
• elkjs throws ordering a nested graph by model order, so parts inside a frame are ordered by ELK alone. A plan may lay out differently once it has a group.

Evidence

• Before: no way to show which parts share an enclosure.
  After: a real heating plan with a nine-member water_box group renders a frame tight round those nine cards, with the heater and the second heat exchanger outside and no pipe through a card. One unlisted adapter between two members sends a hose round the frame; naming and listing it gives a clean sheet. Both were rendered and checked by eye, as were frames with wrap, a turn inside a frame, between two frames, and from a frame to a bare card.
• Sheets without groups are byte-identical: all 14 SVGs and 10 Markdown tables of the project that uses ferrule were rendered from this branch and compared with cmp against the committed ones, 0 differ.
• npm run typecheck, npm test (93 pass, 8 new in test/groups.test.ts) and npm run build pass.

a frame encloses its members, under a band for its title, and no other card
a frame is at least as wide as its title
a turn stays inside a frame when both its ends do, and outside every frame otherwise
a sheet with frames still wraps into rows, each frame kept whole
a frame is drawn first, beneath cards and pipes, and only a sheet with groups carries its style
rejects a group that names what it can't frame

Merge Danger

Door: two-way

Opt-in key; reverting removes it and nothing else.

Blast Radius: none-unless-opted-in

A plan that already has a stray top-level groups key is now read, and fails if it is not in this shape. Groups are plumbing only; a loom's groups is still ignored.

🤖 Generated with Claude Code