From 27565d264131edb5a6e3eb243896999e40e8e6f4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Artur=20M=C4=99dryga=C5=82?=
 <artur.medrygal@handsontable.com>
Date: Thu, 20 Aug 2026 13:09:30 +0200
Subject: [PATCH 1/2] fix(runner): insert re-created head assets before the
 demo's own styles (DEV-2581)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Follow-up to DEV-2576, found on prod. The re-created nodes were appended to
document.head, but the injected line runs at the end of the demo's module — by then
the demo has already appended its own <style>. A demo overrides the theme on the
same selector the theme itself uses, so specificity is equal and document order
decides, and appending put the theme stylesheet last: the demo's palette was
erased. Measured on 6z5k1q2bd4 at /share, against /d as the control:

  --ht-accent-color         #1a42e8   vs  #2f8fe0
  --ht-foreground-color     #222      vs  #123653
  header background         #f7f7f9   vs  #eaf4ff

Before DEV-2576 the demo had no theme; after it, the wrong one.

Everything now goes in at the head's start, against one anchor captured before the
loop so the assets keep their authored order among themselves. That reproduces the
document order /d has and already proves correct: the head's assets first, then the
demo's runtime <style>, then Handsontable's auto-injected core CSS.

Note the two axes, which are easy to conflate. Where the injected *line* sits in the
JS entry is unchanged — still last, so compile positions and babel code frames are
untouched (DEV-2557). Where the *DOM nodes* go is the opposite answer, and this is
that fix.

The test gap that let it through: every unit case seeded an empty head, so nothing
measured our nodes against content the demo adds at runtime. The fake document now
implements insertBefore/firstChild, three unit cases cover position, relative order
and the empty-head path, and the live spec's demo now applies a --ht-* override at
runtime that must survive.

Also fixed a flake the new assertion exposed: the spec read the head as soon as the
grid was visible, but the stylesheets are cross-origin and land later (one run in
three saw links=0). It now polls until the theme has actually applied — non-zero cell
padding, not a non-empty variable, because the demo's own override makes that
variable non-empty synchronously while the sheet is still in flight.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 runner/e2e/preview-head-assets.spec.ts     | 44 +++++++++++++++
 runner/packages/runtime/src/head-assets.ts | 18 +++++-
 runner/pipeline/head-assets.test.mjs       | 65 +++++++++++++++++++++-
 3 files changed, 124 insertions(+), 3 deletions(-)

diff --git a/runner/e2e/preview-head-assets.spec.ts b/runner/e2e/preview-head-assets.spec.ts
index 94f55693..7c36fa11 100644
--- a/runner/e2e/preview-head-assets.spec.ts
+++ b/runner/e2e/preview-head-assets.spec.ts
@@ -35,6 +35,14 @@ const CDN_THEME = "https://cdn.jsdelivr.net/npm/handsontable@18/styles/ht-theme-
 
 const DEMO_JS = `import Handsontable from 'handsontable';
 
+// What a styled demo actually does, and the DEV-2581 regression in one line: this
+// runs *before* the injected head assets are re-created, and it overrides the theme
+// on the same selector the theme itself uses. Equal specificity, so whichever lands
+// later wins — appending the re-created stylesheet erased this.
+const override = document.createElement('style');
+override.textContent = '.ht-theme-main { --ht-cell-vertical-padding: 11px }';
+document.head.appendChild(override);
+
 new Handsontable(document.getElementById('grid'), {
   data: [['a', 1], ['b', 2], ['c', 3]],
   colHeaders: true,
@@ -90,6 +98,34 @@ function readHead(page: Page) {
   });
 }
 
+/**
+ * Wait until the re-created head has finished loading before reading it.
+ *
+ * The stylesheets are cross-origin `<link>`s, so they land some time after the grid
+ * becomes visible — reading immediately made this spec flake (measured: one run in
+ * three saw `links=0`). Polling the observable end state is the fix; a fixed sleep
+ * would either flake again or slow every run to the worst case.
+ */
+async function headSettled(page: Page) {
+  await expect
+    .poll(
+      async () => {
+        const head = await readHead(page);
+        // Non-zero cell padding is the honest "the theme stylesheet applied" signal.
+        // `themeVar !== ""` is not: the demo's own override sets that variable
+        // synchronously, so it is already non-empty while the cross-origin sheet is
+        // still in flight — a readiness check that passes before the thing under test
+        // has happened, which then fails a later assertion for the wrong reason.
+        const themed = head.stylesheets.length > 0 && !head.cellPadding.startsWith("0px");
+        return themed
+          ? "ready"
+          : `pending: links=${head.stylesheets.length} padding=${head.cellPadding}`;
+      },
+      { timeout: 30_000, message: "the re-created head never finished loading" },
+    )
+    .toBe("ready");
+}
+
 test.describe("head assets reach the live preview", () => {
   test.skip(process.env.E2E_LIVE !== "1", "set E2E_LIVE=1 to run live-render checks");
 
@@ -109,6 +145,7 @@ test.describe("head assets reach the live preview", () => {
     await previewReady(page);
     await expect(grid(page)).toBeVisible({ timeout: 120_000 });
 
+    await headSettled(page);
     const head = await readHead(page);
 
     // Each of these is zero/empty on `master`; the message carries the measurement so
@@ -129,6 +166,12 @@ test.describe("head assets reach the live preview", () => {
     expect(head.themeVar, `measured --ht-cell-vertical-padding: ${JSON.stringify(head.themeVar)}`).not.toBe("");
     expect(head.cellPadding, `measured td padding: ${head.cellPadding}`).not.toBe("0px");
     expect(head.cellPadding).toMatch(/^[1-9]/);
+
+    // DEV-2581: the demo's own override, applied at runtime before the head was
+    // re-created, still wins. `4px` here means the re-created theme stylesheet landed
+    // after it and took the cascade — the state measured on prod for 6z5k1q2bd4,
+    // where the demo's blue/white palette was replaced by the theme's defaults.
+    expect(head.themeVar, "the demo's own theme override survives the re-created head").toBe("11px");
   });
 
   test("what the bundler already handles is not touched, and the workspace stays clean", async ({ page }) => {
@@ -142,6 +185,7 @@ test.describe("head assets reach the live preview", () => {
     await previewReady(page);
     await expect(grid(page)).toBeVisible({ timeout: 120_000 });
 
+    await headSettled(page);
     const head = await readHead(page);
 
     // A local stylesheet already applies today — the bundler resolves the local URL
diff --git a/runner/packages/runtime/src/head-assets.ts b/runner/packages/runtime/src/head-assets.ts
index a3bde191..93ff53da 100644
--- a/runner/packages/runtime/src/head-assets.ts
+++ b/runner/packages/runtime/src/head-assets.ts
@@ -162,6 +162,14 @@ const RECEIVER_HEAD = `(function (assets) {
   if (typeof document === 'undefined' || !assets || !assets.length) { return; }
   var MARK = '${MARK_ATTRIBUTE}';
   var head = document.head || document.getElementsByTagName('head')[0] || document.documentElement;
+  /* Everything goes in at the head's start, before whatever is already there
+     (DEV-2581). This line runs at the end of the demo's module, so by now the demo
+     has appended its own style, and a demo overrides the theme on the same selector
+     the theme itself uses: equal specificity, document order decides. Appending put
+     the theme after the override and erased it. One anchor, captured once, so the
+     assets keep their authored order among themselves; insertBefore(node, null)
+     appends, which is what an empty head wants. */
+  var anchor = head.firstChild;
 
   /* The demo has already built its grid against an unstyled DOM by the time this
      runs, and a cross-origin stylesheet lands later still. A generic bubbling
@@ -228,7 +236,7 @@ const RECEIVER_HEAD = `(function (assets) {
       style.setAttribute(MARK, '');
       if (asset.media) { style.setAttribute('media', asset.media); }
       style.appendChild(document.createTextNode(asset.css));
-      head.appendChild(style);
+      head.insertBefore(style, anchor);
       continue;
     }
     var element = document.createElement(asset.tag);
@@ -243,7 +251,7 @@ const RECEIVER_HEAD = `(function (assets) {
       element.onerror = nudge;
     }
     element.setAttribute(MARK, '');
-    head.appendChild(element);
+    head.insertBefore(element, anchor);
   }
   nudge();
 })(`;
@@ -296,6 +304,12 @@ export const HEAD_ASSETS_LINE_SUFFIX = `${jsonInner(RECEIVER_TAIL)}")}catch(e){}
  * Prepending would not buy the ordering it looks like it buys, either: a dynamically
  * inserted cross-origin `<link>` never blocks script execution, so the stylesheet
  * lands after the demo's module body either way. That is what `nudge` is for.
+ *
+ * Two different axes, easy to conflate: *this* decision is where the injected line
+ * sits in the JS entry, and it stays last. Where the DOM nodes go is a separate
+ * question with the opposite answer — they are inserted at the head's start, because
+ * the demo's own `<style>` is already there by then and would otherwise win the
+ * cascade (DEV-2581).
  */
 export function headAssetsModuleLine(assets: HeadAsset[]): string {
   return HEAD_ASSETS_LINE_PREFIX + jsonInner(JSON.stringify(assets)) + HEAD_ASSETS_LINE_SUFFIX;
diff --git a/runner/pipeline/head-assets.test.mjs b/runner/pipeline/head-assets.test.mjs
index 2ec65945..1bfc698a 100644
--- a/runner/pipeline/head-assets.test.mjs
+++ b/runner/pipeline/head-assets.test.mjs
@@ -261,7 +261,19 @@ test("injecting twice is a no-op, even when the head changed underneath", () =>
 
 /** A fake document, enough for the payload to build nodes against. */
 function fakeDocument() {
-  const head = { children: [], appendChild(node) { this.children.push(node); } };
+  const head = {
+    children: [],
+    appendChild(node) { this.children.push(node); return node; },
+    // Real insertion semantics: the whole point of the DEV-2581 cases is *where* a
+    // node lands relative to what the demo's own module already put here.
+    insertBefore(node, anchor) {
+      const at = anchor === null || anchor === undefined ? -1 : this.children.indexOf(anchor);
+      if (at === -1) this.children.push(node);
+      else this.children.splice(at, 0, node);
+      return node;
+    },
+    get firstChild() { return this.children.length > 0 ? this.children[0] : null; },
+  };
   const created = [];
   const doc = {
     title: "Sandbox - CodeSandbox",
@@ -605,3 +617,54 @@ test("a title's character references are decoded too", () => {
   const { doc } = runPayload("<head><title>Sales &amp; Ops &#8212; Q3</title></head>");
   assert.equal(doc.title, "Sales & Ops — Q3");
 });
+
+// ------------------------------------- cascade order (DEV-2581, regression on prod)
+
+test("re-created assets land before styles the demo's own module already added", () => {
+  // The demo's module body runs first and appends its own <style>; our line runs at
+  // the end of that module. Appending our nodes therefore put the authored theme
+  // stylesheet *after* the demo's overrides, and a demo overrides the theme on the
+  // same selector the theme itself uses — equal specificity, so document order is
+  // the only tiebreak, and the theme won. Measured on prod for 6z5k1q2bd4:
+  // --ht-accent-color resolved to the theme's #1a42e8 instead of the demo's #2f8fe0.
+  //
+  // `/d` serves the authored HTML, where the head links parse before the module ever
+  // runs. Reproducing that means inserting at the head's start, not the end.
+  const demoStyle = { tagName: "STYLE", attrs: {}, children: [], textContent: ".ht-theme-main { --ht-accent-color: #2f8fe0 }" };
+  const { appended } = runPayload(FIXTURE, [demoStyle]);
+
+  const ours = appended.filter((node) => node.attrs["data-hot-runner-head"] === "");
+  const demoAt = appended.indexOf(demoStyle);
+  assert.equal(demoAt, ours.length, "every re-created node sits before the demo's own style");
+  assert.ok(appended.slice(0, ours.length).every((node) => node.attrs["data-hot-runner-head"] === ""));
+});
+
+test("inserting at the start keeps the authored order among the assets themselves", () => {
+  // Inserting each node before the same anchor in source order is what preserves it;
+  // inserting each before the *previous* one would silently reverse the cascade
+  // between two stylesheets that set the same variable.
+  const demoStyle = { tagName: "STYLE", attrs: {}, children: [], textContent: "/* demo */" };
+  const { appended } = runPayload(FIXTURE, [demoStyle]);
+  const ours = appended.filter((node) => node.attrs["data-hot-runner-head"] === "");
+  assert.deepEqual(
+    ours.map((node) => node.attrs.href ?? node.attrs.name ?? node.textContent),
+    [
+      CDN_CORE,
+      CDN_THEME,
+      ":root { --e2e-head-sentinel: 7px }",
+      "viewport",
+      CDN_ICONS,
+      "data:text/css,%3Aroot%7B--e2e-data-sentinel%3A%209px%7D",
+    ],
+  );
+});
+
+test("an empty head still receives every asset, in order", () => {
+  // The anchor is null in this case, and `insertBefore(node, null)` appends — the
+  // shape every other case in this file exercises, kept explicit so a change to the
+  // anchor logic cannot quietly break the common path.
+  const { appended } = runPayload(FIXTURE);
+  assert.equal(appended.length, 6);
+  assert.equal(appended[0].attrs.href, CDN_CORE);
+  assert.equal(appended.at(-1).attrs.href, "data:text/css,%3Aroot%7B--e2e-data-sentinel%3A%209px%7D");
+});

From f1c5bb03ffa6b67388811fcc40eb3bd0bfbe4bdb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Artur=20M=C4=99dryga=C5=82?=
 <artur.medrygal@handsontable.com>
Date: Thu, 20 Aug 2026 13:43:56 +0200
Subject: [PATCH 2/2] test(runner): give the head-assets spec a budget its own
 waits fit in (DEV-2581)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review of #244: the spec inherited playwright.config.ts's 60s per-test default while
the waits inside one test already allow more — previewReady 120s, the grid 120s,
headSettled 30s. On a cold bundler the test would abort with Playwright's generic
"Test timeout of 60000ms exceeded" before any of those could report what they
measured, so the least informative failure is the one a reviewer sees. 300s, matching
preview-scheme.spec.ts, which is the closest sibling and already does this.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 runner/e2e/preview-head-assets.spec.ts | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/runner/e2e/preview-head-assets.spec.ts b/runner/e2e/preview-head-assets.spec.ts
index 7c36fa11..310b5b53 100644
--- a/runner/e2e/preview-head-assets.spec.ts
+++ b/runner/e2e/preview-head-assets.spec.ts
@@ -128,6 +128,12 @@ async function headSettled(page: Page) {
 
 test.describe("head assets reach the live preview", () => {
   test.skip(process.env.E2E_LIVE !== "1", "set E2E_LIVE=1 to run live-render checks");
+  // The config default is 60s, and the waits inside one test already allow more than
+  // that on a cold bundler: `previewReady` 120s, the grid 120s, `headSettled` 30s. At
+  // 60s the test aborts with Playwright's generic "Test timeout exceeded" *before*
+  // those waits can report what they measured — the least informative failure wins.
+  // Same budget as `preview-scheme.spec.ts`, the closest sibling.
+  test.describe.configure({ timeout: 300_000 });
 
   test("a demo styled only from its <head> renders themed", async ({ page }) => {
     await page.route("**/api/versions", (route) =>