fix(studio): server-side DOM patching, render CSS scoping, and resilience

.github/workflows/ci.yml

@@ -223,6 +223,71 @@ jobs:
       - run: bun install --frozen-lockfile
       - run: bun run --filter @hyperframes/core test:hyperframe-runtime-ci
 
+  studio-load-smoke:
+    name: "Studio: load smoke"
+    needs: [changes]
+    if: needs.changes.outputs.code == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          lfs: true
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 22
+      - run: bun install --frozen-lockfile
+      - run: bun run --cwd packages/core build:hyperframes-runtime
+      - name: Start studio and check for runtime errors
+        run: |
+          # Start the studio dev server in the background
+          bun run --filter '@hyperframes/studio' dev -- --port 5199 &
+          SERVER_PID=$!
+
+          # Wait for the server to be ready (up to 20s)
+          for i in $(seq 1 40); do
+            if curl -sf http://localhost:5199/ >/dev/null 2>&1; then break; fi
+            sleep 0.5
+          done
+
+          if ! curl -sf http://localhost:5199/ >/dev/null 2>&1; then
+            echo "FAIL: studio dev server did not start"
+            kill $SERVER_PID 2>/dev/null || true
+            exit 1
+          fi
+
+          # Load the studio in headless Chrome and capture console errors
+          # puppeteer is a dependency of @hyperframes/producer; resolve from there
+          cd packages/producer
+          node --input-type=module <<'SMOKE_EOF'
+          import puppeteer from "puppeteer";
+          const browser = await puppeteer.launch({
+            headless: "new",
+            args: ["--no-sandbox", "--disable-setuid-sandbox"],
+          });
+          const page = await browser.newPage();
+          const errors = [];
+          page.on("pageerror", (err) => errors.push(err.message));
+          page.on("console", (msg) => {
+            if (msg.type() === "error") errors.push(msg.text());
+          });
+          await page.goto("http://localhost:5199/", { waitUntil: "networkidle0", timeout: 30000 });
+          await new Promise((r) => setTimeout(r, 3000));
+          await browser.close();
+          const fatal = errors.filter(
+            (e) => !e.includes("favicon") && !e.includes("ERR_CONNECTION_REFUSED"),
+          );
+          if (fatal.length > 0) {
+            console.error("FAIL: studio had runtime errors on load:");
+            for (const e of fatal) console.error("  •", e);
+            process.exit(1);
+          }
+          console.log("PASS: studio loaded without runtime errors");
+          SMOKE_EOF
+
+          kill $SERVER_PID 2>/dev/null || true
+
   smoke-global-install:
     name: "Smoke: global install"
     needs: [changes, build]

.oxlintrc.json

@@ -4,5 +4,5 @@
     "correctness": "error"
   },
   "plugins": ["react", "typescript"],
-  "ignorePatterns": ["dist/", "coverage/", "node_modules/"]
+  "ignorePatterns": ["dist/", "coverage/", "node_modules/", "playground/"]
 }

packages/core/src/compiler/compositionScoping.test.ts

@@ -497,6 +497,55 @@ window.__afterTimeline = window.__timelines.scene;
     expect(errorSpy).not.toHaveBeenCalled();
   });
 
+  it("uses compound selector when authored root is the scoped element itself", () => {
+    const scoped = scopeCssToComposition(
+      "#chrome-overlay-root { --primary: #FFDC8B; }",
+      "chrome-overlay",
+      undefined,
+      "chrome-overlay-root",
+      { compoundAuthoredRoot: true },
+    );
+
+    // Both attributes are on the same element after inlining, so the selector
+    // must be compound (no space) to match.
+    expect(scoped).toContain(
+      '[data-composition-id="chrome-overlay"][data-hf-authored-id="chrome-overlay-root"]',
+    );
+    expect(scoped).not.toContain(
+      '[data-composition-id="chrome-overlay"] [data-hf-authored-id="chrome-overlay-root"]',
+    );
+  });
+
+  it("uses compound selector for authored root with descendant combinators", () => {
+    const scoped = scopeCssToComposition(
+      "#chrome-overlay-root .chrome { display: flex; }",
+      "chrome-overlay",
+      undefined,
+      "chrome-overlay-root",
+      { compoundAuthoredRoot: true },
+    );
+
+    // The authored root part is compound with scope, .chrome is a descendant
+    expect(scoped).toContain(
+      '[data-composition-id="chrome-overlay"][data-hf-authored-id="chrome-overlay-root"] .chrome',
+    );
+    expect(scoped).not.toMatch(
+      /\[data-composition-id="chrome-overlay"\]\s+\[data-hf-authored-id="chrome-overlay-root"\]\s+\.chrome/,
+    );
+  });
+
+  it("still uses descendant selector for non-root selectors with authoredRootId", () => {
+    const scoped = scopeCssToComposition(
+      ".child-element { color: red; }",
+      "chrome-overlay",
+      undefined,
+      "chrome-overlay-root",
+    );
+
+    // Regular child selectors still get a descendant combinator (space)
+    expect(scoped).toContain('[data-composition-id="chrome-overlay"] .child-element');
+  });
+
   it("rewrites #id CSS selectors to [data-hf-authored-id] when authoredRootId is provided", () => {
     const scoped = scopeCssToComposition(
       `#intro { background: #111; }

packages/core/src/compiler/compositionScoping.ts

@@ -101,6 +101,7 @@ function scopeSelector(
   scope: string,
   compositionId: string,
   authoredRootId?: string | null,
+  compoundAuthoredRoot?: boolean,
 ): string {
   const selectorWithoutAuthoredRootId = normalizeAuthoredRootIdSelector(selector, authoredRootId);
   const selectorWithoutRootTiming = normalizeCompositionRootSelector(
@@ -120,6 +121,15 @@ function scopeSelector(
   }
   const leading = selectorWithoutRootTiming.match(/^\s*/)?.[0] ?? "";
   const trailing = selectorWithoutRootTiming.match(/\s*$/)?.[0] ?? "";
+  if (compoundAuthoredRoot) {
+    const authoredRootAttr = authoredRootId
+      ? `[${AUTHORED_ROOT_ID_ATTR}="${escapeCssAttributeValue(authoredRootId)}"]`
+      : null;
+    if (authoredRootAttr && trimmed.startsWith(authoredRootAttr)) {
+      const rest = trimmed.slice(authoredRootAttr.length);
+      return `${leading}${scope}${authoredRootAttr}${rest}${trailing}`;
+    }
+  }
   return `${leading}${scope} ${trimmed}${trailing}`;
 }
 
@@ -158,6 +168,7 @@ export function scopeCssToComposition(
   compositionId: string,
   scopeSelectorOverride?: string,
   authoredRootId?: string | null,
+  options?: { compoundAuthoredRoot?: boolean },
 ): string {
   const trimmedCompositionId = compositionId.trim();
   if (!css || !trimmedCompositionId) return css;
@@ -169,7 +180,13 @@ export function scopeCssToComposition(
   root.walkRules((rule) => {
     if (isInsideGlobalAtRule(rule)) return;
     rule.selectors = rule.selectors.map((selector) =>
-      scopeSelector(selector, scope, trimmedCompositionId, authoredRootId),
+      scopeSelector(
+        selector,
+        scope,
+        trimmedCompositionId,
+        authoredRootId,
+        options?.compoundAuthoredRoot,
+      ),
     );
   });
 

packages/core/src/compiler/inlineSubCompositions.test.ts

@@ -151,4 +151,35 @@ describe("inlineSubCompositions – #ID selector scoping divergence", () => {
 
     expect(host.getAttribute("data-composition-id")).toBe("intro");
   });
+
+  it("producer path: scoped CSS matches host element when both attributes coexist", () => {
+    const document = makeHostDocument("intro");
+    const host = document.querySelector('[data-composition-src="intro.html"]')!;
+
+    const result = inlineSubCompositions(document, [host], {
+      resolveHtml: () => SUB_COMP_HTML,
+      parseHtml: (html) => parseHTML(html).document,
+      compoundAuthoredRoot: true,
+    });
+
+    // After inlining, the host has both data-composition-id and data-hf-authored-id.
+    // CSS selectors targeting the root must be compound (no space) so they match
+    // when both attributes are on the same element.
+    expect(host.getAttribute("data-composition-id")).toBe("intro");
+    expect(host.getAttribute("data-hf-authored-id")).toBe("intro");
+
+    const scopedCss = result.styles.join("\n");
+
+    // Root-only selector: must be compound
+    expect(scopedCss).toMatch(/\[data-composition-id="intro"\]\[data-hf-authored-id="intro"\]/);
+    // Must NOT have a descendant combinator between the two attribute selectors
+    expect(scopedCss).not.toMatch(
+      /\[data-composition-id="intro"\]\s+\[data-hf-authored-id="intro"\]\s*\{/,
+    );
+
+    // Descendant selector: compound root + space + child
+    expect(scopedCss).toMatch(
+      /\[data-composition-id="intro"\]\[data-hf-authored-id="intro"\]\s+\.title/,
+    );
+  });
 });

packages/core/src/compiler/inlineSubCompositions.ts

@@ -60,6 +60,15 @@ export interface InlineSubCompositionsOptions {
    */
   flattenInnerRoot?: (innerRoot: Element) => Element;
 
+  /**
+   * When true, CSS selectors targeting the authored root use a compound
+   * selector (`[scope][root]`) instead of a descendant (`[scope] [root]`).
+   * Enable this in the producer path where the inner root merges onto
+   * the host element via innerHTML — both attributes end up on the same
+   * element and a descendant selector won't match.
+   */
+  compoundAuthoredRoot?: boolean;
+
   /**
    * Read declared variable defaults from a sub-composition's `<html>` element.
    * The bundler passes `readDeclaredDefaults`; the producer can omit this.
@@ -139,6 +148,7 @@ export function inlineSubCompositions(
     hostIdentityMap,
     rewriteInlineStyles = false,
     flattenInnerRoot,
+    compoundAuthoredRoot,
     readVariableDefaults,
     parseHostVariables,
     buildScopeSelector = defaultBuildScopeSelector,
@@ -211,7 +221,9 @@ export function inlineSubCompositions(
         const css = rewriteCssAssetUrls(s.textContent || "", src);
         styles.push(
           scopeCompId
-            ? scopeCssToComposition(css, scopeCompId, runtimeScope || undefined, authoredRootId)
+            ? scopeCssToComposition(css, scopeCompId, runtimeScope || undefined, authoredRootId, {
+                compoundAuthoredRoot: compoundAuthoredRoot === true,
+              })
             : css,
         );
       }
@@ -228,7 +240,9 @@ export function inlineSubCompositions(
       const css = rewriteCssAssetUrls(s.textContent || "", src);
       styles.push(
         scopeCompId
-          ? scopeCssToComposition(css, scopeCompId, runtimeScope || undefined, authoredRootId)
+          ? scopeCssToComposition(css, scopeCompId, runtimeScope || undefined, authoredRootId, {
+              compoundAuthoredRoot: compoundAuthoredRoot === true,
+            })
           : css,
       );
       s.remove();