feat(core): the audio group model — element, membership, helpers

[vanceingalls]

Summary

• Adds <hf-audio-group> + data-audio-group: a non-rendering group element and member-held membership attribute, parse-only foundation for B2–B7 (routing, UI, mute/solo, carve, bus strip) and C1 (timeline FX entry).
• packages/core/src/audioGroups.ts: resolveAudioGroups(root) and audioGroupOf(el), pure DOM reads, no state. Groups don't nest (self-referential data-audio-group ignored); a group with members but no element still resolves (label = id); removing a member from the DOM drops it on next resolve.
• New ./audio-groups package subpath (mirrors ./audio-carve).
• New audio-groups canary at percentage: 0, sunsetAfter: 2027-01-15 — gates the future Studio UI only.
• Studio attribute-write path (handleDomAttributeLiveCommit) verified to set/remove data-audio-group like any other data attribute (new test in useDomEditCommits.test.tsx).

Deviations from the step doc (verified, not guessed — see commit message)

• The step's suggested display:none injection point (an existing runtime base stylesheet) doesn't exist in this codebase — grepped, confirmed absent. Skipped rather than inventing new infrastructure: an empty, childless custom element already renders as a zero-size inline box, and hyperframes lint against a fixture with the element confirms it produces no visible/lint findings.
• No lint rule flags unknown elements or data-* attributes — confirmed by grep, added nothing per the step's own instruction.
• Timeline's clip-collection selector already excludes the group element (no data-start/data-track-index/data-composition-id, not video/audio/img) — confirmed by reading timeline.ts, zero changes needed.

Depends on

Stacked on #3277 (P2) → #3276 (P1) → #3275 (A2) → #3274 (A1). Should merge after all four.

Test plan

• bun run build clean
• packages/core test: 2352/2352 (new audioGroups.test.ts: round-trip, group-absent, no-nesting, dangling-member, video-ignored)
• packages/studio test: 4245/4245 (new attribute set/remove test)
• hyperframes lint on a fixture containing <hf-audio-group> — 0 findings reference the element or its attributes
• oxfmt/oxlint clean

[miguel-heygen]

The member-held model and document-order resolver are a good foundation: resolveAudioGroups recomputes from live DOM state, tolerates a missing metadata element, and the package subpath is wired consistently. Two model-contract gaps need closing before downstream routing/UI build on it.

1. blocker — the advertised “non-rendering” group element is not non-rendering. audioGroups.ts:12 introduces <hf-audio-group> as a normal unknown custom element, but nothing gives it display:none/hidden semantics. Empty inline content is not equivalent to being absent from layout: inside a flex/grid composition root it is an extra item (and therefore adds a gap, affects placement/alignment and :nth-child selectors); in inline formatting it can also affect the line box. The PR explicitly skipped the execution plan's display:none requirement, and the lint smoke cannot detect this visual/layout effect. Enforce inertness universally (runtime stylesheet/custom-element registration, or a required hidden representation with a contract test) rather than relying on “empty childless” markup.

2. blocker — the two public membership readers disagree on what can be a member. resolveAudioGroups correctly restricts v1 membership to audio[...] and documents that video is ignored (audioGroups.ts:24-34), but audioGroupOf at :54-58 returns the attribute from any non-hf-audio-group element. So audioGroupOf(<video data-audio-group="voiceover">) returns "voiceover" while the same DOM resolves to no group; an empty attribute also returns "" despite the function's “or null” contract and the resolver ignoring it. Make this helper enforce the same audio-only/non-empty membership predicate and add the mirror negative tests.

CI at the exact head is green; these are contract failures not surfaced by the current eight pure-DOM tests.

Verdict: REQUEST CHANGES
Reasoning: the metadata element can change authored layout despite being specified as non-rendering, and the exported helpers give contradictory answers for the same video/empty membership shapes.

— Magi

[miga-heygen]

Review

Approve. Independent read at exact head. Sound foundation for the 6 PRs above it that I already approved.

Group model: Clean DOM-centric design — membership held by the member (data-audio-group pointing at a group id), not by nesting, so a removed track simply disappears on re-resolve. HfAudioGroup interface is minimal (id, label, memberIds). The module is correctly scoped as parse-only.

Consistency invariant: Both resolveAudioGroups and audioGroupOf derive from MEMBER_SELECTOR, so the two readers can never disagree about a given element. The docstring explains the real bug this fixed (preview routing a track the export would never group because video elements were handled inconsistently). Five edge cases pinned: absent group element, video exclusion, empty attribute, group-element-is-not-a-member, DOM removal.

Inert style: !important is justified — the test proves a #voiceover{display:flex} author rule (higher specificity) would override without it. Injection is idempotent and runs at init before timeline bind.

Character presets: chipmunk/giant/monster follow the existing preset pattern in all three maps (presets, copy, style). Plans doc honestly updated on what landed and what's still out of scope.

Canary: audio-groups at 0% gates Studio UI only; parse+play works regardless.

No issues. Ship it.

— Miga