fix(core): preserve nested-rule selectors in composition CSS scoping (#2721) - #2733

Description

Fixes #2721. External-user report from qd3v: a nested CSS rule inside a composition's <style> block gets silently ignored.

Reproducer (from the issue, exact):

<style>
  /* All good */
  [data-composition-id="intro-comp"] h1 { color: orangered; font-size: 5rem; }

  /* Just ignored */
  [data-composition-id="intro-comp"] {
    .title { color: brown; font-size: 6rem; }
  }
</style>
<h1>Hyperframes</h1>
<div class="title">Welcome!</div>

The h1 gets styled; the .title doesn't.

Root cause

Modern browsers support native CSS Nesting (Chrome 112+, Firefox 117+, Safari 16.5+). A nested rule .title { … } inside [data-composition-id="intro-comp"] { … } resolves at match time to <parent> .title via the implicit & prefix.

scopeCssToComposition in packages/core/src/compiler/compositionScoping.ts walks every Rule via root.walkRules and re-scopes selectors:

root.walkRules((rule) => {
  if (isInsideGlobalAtRule(rule)) return;
  rule.selectors = rule.selectors.map((selector) => scopeSelector(selector, scope, …));
});

PostCSS's walkRules visits nested rules too. The nested .title selector was scoped to [data-composition-id="intro-comp"] .title — but the parent's selector was also scoped, so when CSS Nesting resolved the inner rule it prepended & (the parent scope) AGAIN, producing effectively:

[data-composition-id="intro-comp"]:not(:has(…)) [data-composition-id="intro-comp"] .title { … }

The composition root only appears once in the DOM, so <scope> <scope> .title matches nothing — the rule appears "just ignored" as the reporter described.

Fix

Add isNestedInsideAnotherRule predicate — mirrors the existing isInsideGlobalAtRule — and skip nested Rules in the walkRules callback. Top-level rules still get scoped; their nested descendants inherit scope naturally via CSS Nesting at match time.

 root.walkRules((rule) => {
   if (isInsideGlobalAtRule(rule)) return;
+  if (isNestedInsideAnotherRule(rule)) return;
   rule.selectors = rule.selectors.map((selector) => scopeSelector(…));
 });

Testing

• bunx vitest run packages/core/src/compiler/compositionScoping.test.ts — 37 tests pass (35 pre-existing + 2 new).
• New test: preserves nested-rule selectors so CSS Nesting inheritance works (#2721) — asserts nested .title and h2 selectors stay verbatim while top-level rules keep scoping, and no […] .title false-scoped selector appears.
• New test: preserves deeply-nested CSS Nesting rules (#2721) — same guarantee at depth 3.
• Traced the exact code path from the postcss root.walkRules bit; reproduced the double-scoping via a local postcss probe before writing the fix.

Note on other issues raised in the ticket

The reporter also mentioned two secondary points that are out of scope for this PR:

1. "If I try to use body tag instead of template, the rendering fails" — that's the standalone sub-composition contract (must have a <template> or <body> with [data-composition-id]). The error is correct; the docs could be clearer. Filing separately if it needs a doc update.
2. "linter or checker wants me to add data-layout-allow-overlap, but there's no such attribute in the docs" — that's a docs gap on hyperframes.heygen.com/concepts/data-attributes. Filing separately if needed.

— Rames Jusso