@astryxdesign/build 0.4.7 → 0.5.0-canary.009bcb3

package/dist/vite.mjs

@@ -6,6 +6,7 @@ import stylex from "@stylexjs/unplugin";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
 var __dirname = path.dirname(fileURLToPath(import.meta.url));
 var LIBRARY_PATTERN = "node_modules/@astryxdesign/";
 var STYLEX_CSS_PATH = "/virtual:stylex.css";
@@ -119,54 +120,149 @@ function astryxStylex(options = {}) {
             if (!req.url?.startsWith(STYLEX_CSS_PATH)) {
               return next();
             }
-            if (!stylexPlugin) {
-              res.statusCode = 200;
-              res.setHeader("Content-Type", "text/css");
-              res.end("");
-              return;
-            }
-            const shared = stylexPlugin.__stylexGetSharedStore?.();
-            const rulesById = shared?.rulesById;
-            if (!rulesById || rulesById.size === 0) {
-              res.statusCode = 200;
-              res.setHeader("Content-Type", "text/css");
-              res.end("");
-              return;
-            }
-            const libraryRules = [];
-            const productRules = [];
-            for (const [filePath, rules] of rulesById.entries()) {
-              if (filePath.includes(libraryPattern)) {
-                libraryRules.push(...rules);
-              } else {
-                productRules.push(...rules);
-              }
-            }
-            const libraryCss = libraryRules.length ? stylexBabelPlugin.processStylexRules(libraryRules, {
-              useLayers: true
-            }) : "";
-            const productCss = productRules.length ? stylexBabelPlugin.processStylexRules(productRules, {
-              useLayers: true
-            }) : "";
-            const parts = [];
-            if (libraryCss)
-              parts.push(`@layer ${libraryLayer} {
-${libraryCss}
-}`);
-            if (productCss)
-              parts.push(`@layer ${productLayer} {
-${productCss}
-}`);
+            const rulesById = stylexPlugin?.__stylexGetSharedStore?.()?.rulesById;
             res.statusCode = 200;
             res.setHeader("Content-Type", "text/css");
             res.setHeader("Cache-Control", "no-store");
-            res.end(parts.join("\n\n"));
+            res.end(
+              renderSplitLayers(rulesById, {
+                libraryPattern,
+                libraryLayer,
+                productLayer
+              })
+            );
           }
         });
       };
     }
   };
-  return [configPlugin, layerOrderPlugin, basePlugin, splitLayerPlugin];
+  return [
+    configPlugin,
+    layerOrderPlugin,
+    basePlugin,
+    splitLayerPlugin,
+    buildLayerSplitPlugin(basePlugin, {
+      libraryPattern,
+      libraryLayer,
+      productLayer,
+      lightningcssOptions: stylexOptions.lightningcssOptions
+    })
+  ];
+}
+function renderSplitLayers(rulesById, options) {
+  if (!rulesById || rulesById.size === 0) return "";
+  const libraryRules = [];
+  const productRules = [];
+  for (const [filePath, rules] of rulesById.entries()) {
+    if (filePath.includes(options.libraryPattern)) {
+      libraryRules.push(...rules);
+    } else {
+      productRules.push(...rules);
+    }
+  }
+  const render = (rules, layer) => rules.length ? `@layer ${layer} {
+${stylexBabelPlugin.processStylexRules(rules, { useLayers: true })}
+}` : "";
+  return [
+    render(libraryRules, options.libraryLayer),
+    render(productRules, options.productLayer)
+  ].filter(Boolean).join("\n\n");
+}
+function buildLayerSplitPlugin(basePlugin, options) {
+  const stylex2 = basePlugin;
+  let base = "/";
+  return {
+    name: "astryx-build-layer-split",
+    apply: "build",
+    enforce: "post",
+    configResolved(config) {
+      base = config.base ?? "/";
+    },
+    writeBundle(outputOptions) {
+      const rulesById = stylex2.__stylexGetSharedStore?.().rulesById;
+      if (!rulesById || rulesById.size === 0) return;
+      const merged = stylex2.__stylexCollectCss?.();
+      if (!merged) return;
+      const split = postProcessCss(
+        renderSplitLayers(rulesById, options),
+        options.lightningcssOptions
+      );
+      const outDir = outputOptions.dir ? outputOptions.dir : outputOptions.file ? path.dirname(outputOptions.file) : null;
+      if (!outDir || !fs.existsSync(outDir)) return;
+      const patched = [];
+      for (const file of listCssFiles(outDir)) {
+        const css = fs.readFileSync(file, "utf-8");
+        const at = css.lastIndexOf(merged);
+        if (at === -1) continue;
+        fs.writeFileSync(
+          file,
+          css.slice(0, at) + split + css.slice(at + merged.length)
+        );
+        patched.push(file);
+      }
+      if (patched.length === 0) {
+        this.error(
+          `astryx-build-layer-split: StyleX emitted rules but its CSS block was not found in any stylesheet under ${outDir}, so Astryx and product styles could not be separated into their cascade layers. Leaving the build unsplit would let product styles lose to a theme. This usually means the StyleX plugin version changed how it emits CSS.`
+        );
+        return;
+      }
+      linkOrphanStylesheets(outDir, patched, base);
+    }
+  };
+}
+function listCssFiles(dir) {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...listCssFiles(full));
+    else if (entry.name.endsWith(".css")) out.push(full);
+  }
+  return out;
+}
+function listHtmlFiles(dir) {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...listHtmlFiles(full));
+    else if (entry.name.endsWith(".html")) out.push(full);
+  }
+  return out;
+}
+function linkOrphanStylesheets(outDir, cssFiles, base) {
+  const pages = listHtmlFiles(outDir);
+  if (pages.length === 0) return;
+  const orphans = cssFiles.filter((css) => {
+    const name = path.basename(css);
+    return !pages.some((page) => fs.readFileSync(page, "utf-8").includes(name));
+  });
+  if (orphans.length === 0) return;
+  const links = orphans.map((css) => {
+    const href = base.replace(/\/$/, "") + "/" + path.relative(outDir, css).split(path.sep).join("/");
+    return `<link rel="stylesheet" crossorigin href="${href}">`;
+  }).join("\n    ");
+  for (const page of pages) {
+    const html = fs.readFileSync(page, "utf-8");
+    if (!html.includes("</head>")) continue;
+    fs.writeFileSync(page, html.replace("</head>", `  ${links}
+  </head>`));
+  }
+}
+function postProcessCss(css, lightningcssOptions) {
+  if (!css) return css;
+  try {
+    const require_ = createRequire(import.meta.url);
+    const { transform, browserslistToTargets } = require_("lightningcss");
+    const browserslist = require_("browserslist");
+    const { code } = transform({
+      targets: browserslistToTargets(browserslist()),
+      ...lightningcssOptions,
+      filename: "stylex.css",
+      code: Buffer.from(css)
+    });
+    return code.toString();
+  } catch {
+    return css;
+  }
 }
 function astryxStylexLegacy(options) {
   const {
@@ -226,54 +322,33 @@ function astryxStylexLegacy(options) {
             if (!req.url?.startsWith(STYLEX_CSS_PATH)) {
               return next();
             }
-            if (!stylexPlugin) {
-              res.statusCode = 200;
-              res.setHeader("Content-Type", "text/css");
-              res.end("");
-              return;
-            }
-            const shared = stylexPlugin.__stylexGetSharedStore?.();
-            const rulesById = shared?.rulesById;
-            if (!rulesById || rulesById.size === 0) {
-              res.statusCode = 200;
-              res.setHeader("Content-Type", "text/css");
-              res.end("");
-              return;
-            }
-            const libraryRules = [];
-            const productRules = [];
-            for (const [filePath, rules] of rulesById.entries()) {
-              if (filePath.includes(libraryPattern)) {
-                libraryRules.push(...rules);
-              } else {
-                productRules.push(...rules);
-              }
-            }
-            const libraryCss = libraryRules.length ? stylexBabelPlugin.processStylexRules(libraryRules, {
-              useLayers: true
-            }) : "";
-            const productCss = productRules.length ? stylexBabelPlugin.processStylexRules(productRules, {
-              useLayers: true
-            }) : "";
-            const parts = [];
-            if (libraryCss)
-              parts.push(`@layer ${libraryLayer} {
-${libraryCss}
-}`);
-            if (productCss)
-              parts.push(`@layer ${productLayer} {
-${productCss}
-}`);
+            const rulesById = stylexPlugin?.__stylexGetSharedStore?.()?.rulesById;
             res.statusCode = 200;
             res.setHeader("Content-Type", "text/css");
             res.setHeader("Cache-Control", "no-store");
-            res.end(parts.join("\n\n"));
+            res.end(
+              renderSplitLayers(rulesById, {
+                libraryPattern,
+                libraryLayer,
+                productLayer
+              })
+            );
           }
         });
       };
     }
   };
-  return [layerOrderPlugin, basePlugin, splitLayerPlugin];
+  return [
+    layerOrderPlugin,
+    basePlugin,
+    splitLayerPlugin,
+    buildLayerSplitPlugin(basePlugin, {
+      libraryPattern,
+      libraryLayer,
+      productLayer,
+      lightningcssOptions: stylexOptions?.lightningcssOptions
+    })
+  ];
 }
 export {
   LIGHTNINGCSS_TARGETS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/build",
-  "version": "0.4.7",
+  "version": "0.5.0-canary.009bcb3",
   "description": "Build plugins for XDS source builds — babel, PostCSS, and Vite integrations",
   "author": "Meta Open Source",
   "license": "MIT",

package/src/vite.build.test.ts

@@ -0,0 +1,179 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Runs REAL Vite production builds of fixture apps and asserts on the
+ * stylesheets they emit.
+ *
+ * The unit tests in vite.test.ts check the plugin's wiring, and they passed
+ * while the build shipped a version that wrapped every StyleX rule — Astryx's
+ * and the app's alike — in the library layer. That inverts the bug rather than
+ * fixing it: product styles are supposed to outrank a theme, and wrapped in
+ * `astryx-base` they lose to one. Only the built artifact shows it, so this
+ * builds one.
+ *
+ * Two shapes, because StyleX emits through two different paths:
+ *
+ *   `layer-split`        the app imports a stylesheet, so the bundle has a CSS
+ *                        asset and StyleX appends to it in `generateBundle`
+ *   `layer-split-nocss`  the app imports none, so StyleX writes its own file in
+ *                        `writeBundle`, outside Rollup's graph
+ *
+ * The second is the one that was missing, and it hid two defects: the split did
+ * not run there at all, and the file StyleX writes is not linked by any page.
+ *
+ * What none of this can prove is which declaration actually paints — that is a
+ * cascade fact, and it lives in .github/scripts/theme-layer-cascade.js.
+ */
+
+import {describe, it, expect, beforeAll, afterAll} from 'vitest';
+import {build} from 'vite';
+import react from '@vitejs/plugin-react';
+import {mkdtempSync, readdirSync, readFileSync, rmSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {astryxStylex} from './vite';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '../../..');
+const FIXTURES = path.resolve(__dirname, '../__fixtures__');
+const CORE_SRC = path.join(REPO_ROOT, 'packages/core/src');
+
+/** The class prefixes @astryxdesign/build/babel assigns per origin. */
+const LIBRARY_CLASS = /\.astryx[a-z0-9]{5,}/g;
+const PRODUCT_CLASS = /\.x[a-z0-9]{5,}/g;
+
+type Built = {css: string; cssName: string; html: string; outDir: string};
+
+async function buildFixture(name: string): Promise<Built> {
+  const root = path.join(FIXTURES, name);
+  const outDir = mkdtempSync(path.join(tmpdir(), `astryx-${name}-`));
+  await build({
+    root,
+    logLevel: 'error',
+    build: {outDir, emptyOutDir: true},
+    resolve: {alias: {'@astryxdesign/core': CORE_SRC}},
+    plugins: [
+      react(),
+      ...astryxStylex({
+        stylexOptions: {
+          dev: false,
+          unstable_moduleResolution: {type: 'commonJS', rootDir: REPO_ROOT},
+          aliases: {
+            '@astryxdesign/core/*': [path.join(CORE_SRC, '*')],
+            '@astryxdesign/core': [CORE_SRC],
+          },
+        },
+        libraryPattern: 'packages/core/',
+      }),
+    ],
+  });
+
+  const assets = path.join(outDir, 'assets');
+  const cssName = readdirSync(assets).find(f => f.endsWith('.css'));
+  if (!cssName) throw new Error(`no stylesheet emitted into ${assets}`);
+  return {
+    css: readFileSync(path.join(assets, cssName), 'utf-8'),
+    cssName,
+    html: readFileSync(path.join(outDir, 'index.html'), 'utf-8'),
+    outDir,
+  };
+}
+
+/** The slice of a stylesheet inside a given top-level layer block. */
+function layerBlock(css: string, name: string): string {
+  const start = css.indexOf(`@layer ${name} {`);
+  expect(
+    start,
+    `@layer ${name} is not in the emitted stylesheet`,
+  ).toBeGreaterThan(-1);
+  let depth = 0;
+  for (let i = css.indexOf('{', start); i < css.length; i++) {
+    if (css[i] === '{') depth++;
+    else if (css[i] === '}' && --depth === 0) return css.slice(start, i + 1);
+  }
+  throw new Error(`@layer ${name} is unterminated`);
+}
+
+/** Both shapes must satisfy the same contract, so both run the same checks. */
+function itSplitsCorrectly(get: () => Built) {
+  it('declares the layer order the split depends on', () => {
+    expect(get().html).toContain(
+      '@layer reset, astryx-base, astryx-theme, product;',
+    );
+  });
+
+  it("puts Astryx's own rules in the library layer", () => {
+    const library = layerBlock(get().css, 'astryx-base');
+    expect(library.match(LIBRARY_CLASS)?.length ?? 0).toBeGreaterThan(50);
+    // The fixture's Button pulls in real component CSS, so a token it styles
+    // with is a fact about this block rather than about class-name shape.
+    expect(library).toContain('--radius-element');
+  });
+
+  // The regression this file exists for. The wrapped-not-split version put the
+  // app's own StyleX in astryx-base, below `astryx-theme`, so a theme could
+  // silently restyle code the theme has no business reaching.
+  it("puts the app's own rules in the product layer, not the library one", () => {
+    const {css} = get();
+    const product = layerBlock(css, 'product');
+    const library = layerBlock(css, 'astryx-base');
+
+    expect(product).toContain('11px');
+    expect(library).not.toContain('11px');
+
+    expect(product.match(LIBRARY_CLASS)).toBeNull();
+    expect(library.match(PRODUCT_CLASS)).toBeNull();
+  });
+
+  it('leaves no StyleX rule outside the two layers', () => {
+    const {css} = get();
+    const outside = css
+      .replace(layerBlock(css, 'astryx-base'), '')
+      .replace(layerBlock(css, 'product'), '');
+    expect(outside).not.toContain('@layer priority');
+  });
+
+  // StyleX runs its CSS through lightningcss before emitting it. Replacing that
+  // output means running the same pass, or the build quietly loses the prefixes
+  // the original had.
+  it('keeps the vendor prefixing StyleX applies', () => {
+    expect(get().css).toContain('-webkit-');
+  });
+
+  it('links the stylesheet from the page', () => {
+    const {html, cssName} = get();
+    expect(html).toContain(cssName);
+    expect(html.split(cssName).length - 1, 'linked more than once').toBe(1);
+  });
+}
+
+describe('a production build separates Astryx and product styles by layer', () => {
+  describe('when the app imports a stylesheet of its own', () => {
+    let built: Built;
+    beforeAll(async () => {
+      built = await buildFixture('layer-split');
+    }, 180_000);
+    afterAll(
+      () => built && rmSync(built.outDir, {recursive: true, force: true}),
+    );
+
+    itSplitsCorrectly(() => built);
+  });
+
+  // StyleX has no bundle asset to append to here, so it writes its own file in
+  // `writeBundle` — outside Rollup's graph, which is why Vite emits no `<link>`
+  // for it. Every assertion below failed before this case was handled: the
+  // stylesheet was unsplit AND the page loaded no styles at all.
+  describe('when the app imports no stylesheet at all', () => {
+    let built: Built;
+    beforeAll(async () => {
+      built = await buildFixture('layer-split-nocss');
+    }, 180_000);
+    afterAll(
+      () => built && rmSync(built.outDir, {recursive: true, force: true}),
+    );
+
+    itSplitsCorrectly(() => built);
+  });
+});

package/src/vite.test.ts

@@ -7,7 +7,7 @@
  *   theme layer name is fixed at `astryx-theme`.
  */
 
-import {describe, it, expect, beforeAll, afterAll} from 'vitest';
+import {describe, it, expect, beforeAll, afterAll, vi} from 'vitest';
 import {mkdtempSync, mkdirSync, rmSync} from 'node:fs';
 import {tmpdir} from 'node:os';
 import path from 'node:path';
@@ -53,6 +53,52 @@ describe('astryxStylex layer order (legacy API)', () => {
   });
 });
 
+/**
+ * A production build had no equivalent of the dev server's split-layer plugin,
+ * so StyleX's `@layer priorityN` blocks sat outside the declared order and
+ * outranked `astryx-theme` — every component override a theme set was dropped.
+ * The first fix WRAPPED those blocks in the library layer instead of splitting
+ * them, which fixed the theme and broke the app: product StyleX landed below
+ * `astryx-theme` too, so a theme could silently restyle code it does not own.
+ *
+ * These pin the plugin's wiring. That the partition is right in a real build is
+ * vite.build.test.ts, and what it means for the cascade is
+ * .github/scripts/theme-layer-cascade.js — unit tests over this hook passed
+ * throughout both bugs.
+ */
+describe('astryxStylex build-time layer split', () => {
+  const find = (plugins: ReturnType<typeof astryxStylex>) =>
+    plugins.find(p => p.name === 'astryx-build-layer-split');
+
+  it('is present on both the modern and the legacy API', () => {
+    expect(find(astryxStylex())).toBeTruthy();
+    expect(find(astryxStylex({stylexOptions: {}}))).toBeTruthy();
+  });
+
+  it('runs on a build only, after the StyleX plugin that emits the CSS', () => {
+    const plugin = find(astryxStylex());
+    expect(plugin?.apply).toBe('build');
+    expect(plugin?.enforce).toBe('post');
+  });
+
+  // The dev middleware and the build hook read the same partition, so a build
+  // that emits nothing is a build where StyleX collected nothing — never a
+  // silent pass-through of unsplit CSS.
+  it('does nothing when StyleX collected no rules', () => {
+    const plugin = find(astryxStylex());
+    const hook = (plugin as any).writeBundle;
+    const fn = typeof hook === 'function' ? hook : hook.handler;
+    const error = vi.fn();
+    expect(() =>
+      fn.call(
+        {error},
+        {dir: mkdtempSync(path.join(tmpdir(), 'astryx-empty-'))},
+      ),
+    ).not.toThrow();
+    expect(error).not.toHaveBeenCalled();
+  });
+});
+
 describe('astryxStylex optimizeDeps package discovery', () => {
   let rootDir: string;
 

package/src/vite.ts

@@ -6,6 +6,7 @@ import stylex from '@stylexjs/unplugin';
 import fs from 'node:fs';
 import path from 'node:path';
 import {fileURLToPath} from 'node:url';
+import {createRequire} from 'node:module';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -242,62 +243,273 @@ export function astryxStylex(
               return next();
             }
 
-            if (!stylexPlugin) {
-              res.statusCode = 200;
-              res.setHeader('Content-Type', 'text/css');
-              res.end('');
-              return;
-            }
-
-            const shared = stylexPlugin.__stylexGetSharedStore?.();
-            const rulesById = shared?.rulesById;
-
-            if (!rulesById || rulesById.size === 0) {
-              res.statusCode = 200;
-              res.setHeader('Content-Type', 'text/css');
-              res.end('');
-              return;
-            }
-
-            const libraryRules: any[] = [];
-            const productRules: any[] = [];
-
-            for (const [filePath, rules] of rulesById.entries()) {
-              if (filePath.includes(libraryPattern)) {
-                libraryRules.push(...rules);
-              } else {
-                productRules.push(...rules);
-              }
-            }
-
-            const libraryCss = libraryRules.length
-              ? stylexBabelPlugin.processStylexRules(libraryRules, {
-                  useLayers: true,
-                })
-              : '';
-            const productCss = productRules.length
-              ? stylexBabelPlugin.processStylexRules(productRules, {
-                  useLayers: true,
-                })
-              : '';
-
-            const parts: string[] = [];
-            if (libraryCss)
-              parts.push(`@layer ${libraryLayer} {\n${libraryCss}\n}`);
-            if (productCss)
-              parts.push(`@layer ${productLayer} {\n${productCss}\n}`);
+            const rulesById =
+              stylexPlugin?.__stylexGetSharedStore?.()?.rulesById;
 
             res.statusCode = 200;
             res.setHeader('Content-Type', 'text/css');
             res.setHeader('Cache-Control', 'no-store');
-            res.end(parts.join('\n\n'));
+            res.end(
+              renderSplitLayers(rulesById, {
+                libraryPattern,
+                libraryLayer,
+                productLayer,
+              }),
+            );
           },
         });
       };
     },
   };
 
-  return [configPlugin, layerOrderPlugin, basePlugin, splitLayerPlugin];
+  return [
+    configPlugin,
+    layerOrderPlugin,
+    basePlugin,
+    splitLayerPlugin,
+    buildLayerSplitPlugin(basePlugin, {
+      libraryPattern,
+      libraryLayer,
+      productLayer,
+      lightningcssOptions: stylexOptions.lightningcssOptions,
+    }),
+  ];
+}
+
+/**
+ * Partition StyleX's collected rules by the source file that authored them and
+ * render each half into its cascade layer: Astryx's own styles into the library
+ * layer (below `astryx-theme`, so a theme can override them), product styles
+ * into the product layer (above it, so an app always wins).
+ *
+ * This is the one implementation. The dev middleware and the build hook differ
+ * only in when they run and what they do with the string — the partition itself
+ * must not diverge, because it did: the build shipped a version that wrapped
+ * everything in the library layer, which put product styles UNDER a theme.
+ *
+ * `rulesById` is keyed by absolute source path, which is the only place the
+ * distinction survives — by the time the CSS is text, the origin is gone.
+ */
+function renderSplitLayers(
+  rulesById: Map<string, unknown[]> | undefined,
+  options: {
+    libraryPattern: string;
+    libraryLayer: string;
+    productLayer: string;
+  },
+): string {
+  if (!rulesById || rulesById.size === 0) return '';
+
+  const libraryRules: unknown[] = [];
+  const productRules: unknown[] = [];
+
+  for (const [filePath, rules] of rulesById.entries()) {
+    if (filePath.includes(options.libraryPattern)) {
+      libraryRules.push(...rules);
+    } else {
+      productRules.push(...rules);
+    }
+  }
+
+  const render = (rules: unknown[], layer: string) =>
+    rules.length
+      ? `@layer ${layer} {\n${stylexBabelPlugin.processStylexRules(rules as never, {useLayers: true})}\n}`
+      : '';
+
+  return [
+    render(libraryRules, options.libraryLayer),
+    render(productRules, options.productLayer),
+  ]
+    .filter(Boolean)
+    .join('\n\n');
+}
+
+/**
+ * The build half of the split. StyleX appends one merged block of CSS to the
+ * build's stylesheet, in its own top-level `@layer priority1…priorityN` — which
+ * is declared after `@layer reset, astryx-base, astryx-theme, product;` and so
+ * outranks every one of them. On the dev server `astryx-split-layers` re-serves
+ * the same rules already partitioned; a build had no equivalent, so a theme's
+ * component overrides were silently dropped in the built app while working in
+ * dev.
+ *
+ * This replaces that merged block with the partitioned pair. It runs in
+ * `writeBundle` because StyleX emits through two different paths depending on
+ * whether the bundle already has a stylesheet to append to (`generateBundle`)
+ * or has to write its own file (`writeBundle`) — on disk, after both, there is
+ * one case instead of two.
+ *
+ * The block is located by an exact match against StyleX's own collector rather
+ * than by looking for `@layer priority1`: a wrong guess about where the block
+ * starts silently moves rules between layers, which is the failure this exists
+ * to prevent. If the rules exist and the block cannot be found, the build
+ * fails.
+ */
+function buildLayerSplitPlugin(
+  basePlugin: unknown,
+  options: {
+    libraryPattern: string;
+    libraryLayer: string;
+    productLayer: string;
+    lightningcssOptions?: unknown;
+  },
+): Plugin {
+  const stylex = basePlugin as {
+    __stylexGetSharedStore?: () => {rulesById: Map<string, unknown[]>};
+    __stylexCollectCss?: () => string;
+  };
+  let base = '/';
+
+  return {
+    name: 'astryx-build-layer-split',
+    apply: 'build',
+    enforce: 'post',
+    configResolved(config) {
+      base = config.base ?? '/';
+    },
+    writeBundle(outputOptions) {
+      const rulesById = stylex.__stylexGetSharedStore?.().rulesById;
+      if (!rulesById || rulesById.size === 0) return;
+
+      const merged = stylex.__stylexCollectCss?.();
+      if (!merged) return;
+
+      const split = postProcessCss(
+        renderSplitLayers(rulesById, options),
+        options.lightningcssOptions,
+      );
+
+      const outDir = outputOptions.dir
+        ? outputOptions.dir
+        : outputOptions.file
+          ? path.dirname(outputOptions.file)
+          : null;
+      // `write: false` builds keep everything in memory; there is nothing to
+      // patch and nothing was shipped, so this is not a failure.
+      if (!outDir || !fs.existsSync(outDir)) return;
+
+      const patched: string[] = [];
+      for (const file of listCssFiles(outDir)) {
+        const css = fs.readFileSync(file, 'utf-8');
+        const at = css.lastIndexOf(merged);
+        if (at === -1) continue;
+        fs.writeFileSync(
+          file,
+          css.slice(0, at) + split + css.slice(at + merged.length),
+        );
+        patched.push(file);
+      }
+
+      if (patched.length === 0) {
+        this.error(
+          'astryx-build-layer-split: StyleX emitted rules but its CSS block ' +
+            `was not found in any stylesheet under ${outDir}, so Astryx and ` +
+            'product styles could not be separated into their cascade layers. ' +
+            'Leaving the build unsplit would let product styles lose to a ' +
+            'theme. This usually means the StyleX plugin version changed how ' +
+            'it emits CSS.',
+        );
+        return;
+      }
+
+      linkOrphanStylesheets(outDir, patched, base);
+    },
+  };
+}
+
+/** Every `.css` file under a directory, recursively. */
+function listCssFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...listCssFiles(full));
+    else if (entry.name.endsWith('.css')) out.push(full);
+  }
+  return out;
+}
+
+/** Every `.html` file under a directory, recursively. */
+function listHtmlFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...listHtmlFiles(full));
+    else if (entry.name.endsWith('.html')) out.push(full);
+  }
+  return out;
+}
+
+/**
+ * Link a stylesheet the build wrote but no page loads.
+ *
+ * When an app imports no CSS of its own, StyleX has no bundle asset to append
+ * to, so it writes `assets/stylex.css` itself — outside Rollup's graph, which
+ * means Vite's HTML plugin never learns about it and emits no `<link>`. The app
+ * ships every Astryx style correctly split into layers, and a completely
+ * unstyled page. Importing any stylesheet hides it, which is why it survives:
+ * the moment a project has one line of its own CSS the symptom disappears.
+ *
+ * Only orphans are linked. A stylesheet already referenced by a page is Vite's,
+ * and touching it would duplicate the load. A build with no HTML at all —
+ * library mode — is left alone: its consumer imports the CSS themselves.
+ */
+function linkOrphanStylesheets(
+  outDir: string,
+  cssFiles: string[],
+  base: string,
+): void {
+  const pages = listHtmlFiles(outDir);
+  if (pages.length === 0) return;
+
+  const orphans = cssFiles.filter(css => {
+    const name = path.basename(css);
+    return !pages.some(page => fs.readFileSync(page, 'utf-8').includes(name));
+  });
+  if (orphans.length === 0) return;
+
+  const links = orphans
+    .map(css => {
+      const href =
+        base.replace(/\/$/, '') +
+        '/' +
+        path.relative(outDir, css).split(path.sep).join('/');
+      return `<link rel="stylesheet" crossorigin href="${href}">`;
+    })
+    .join('\n    ');
+
+  for (const page of pages) {
+    const html = fs.readFileSync(page, 'utf-8');
+    if (!html.includes('</head>')) continue;
+    fs.writeFileSync(page, html.replace('</head>', `  ${links}\n  </head>`));
+  }
+}
+
+/**
+ * StyleX runs its collected CSS through lightningcss before emitting it, so
+ * anything replacing that output has to run the same pass or the build quietly
+ * loses the vendor prefixes and lowering the original had.
+ *
+ * lightningcss ships with both Vite and the StyleX plugin, either of which must
+ * be installed for this plugin to run at all. If it somehow is not resolvable,
+ * the unprocessed CSS is correct — just less compatible — so this degrades
+ * rather than failing the build.
+ */
+function postProcessCss(css: string, lightningcssOptions: unknown): string {
+  if (!css) return css;
+  try {
+    const require_ = createRequire(import.meta.url);
+    const {transform, browserslistToTargets} = require_('lightningcss');
+    const browserslist = require_('browserslist');
+    const {code} = transform({
+      targets: browserslistToTargets(browserslist()),
+      ...(lightningcssOptions as object),
+      filename: 'stylex.css',
+      code: Buffer.from(css),
+    });
+    return code.toString();
+  } catch {
+    return css;
+  }
 }
 
 /**
@@ -370,60 +582,35 @@ function astryxStylexLegacy(options: AstryxVitePluginLegacyOptions): Plugin[] {
               return next();
             }
 
-            if (!stylexPlugin) {
-              res.statusCode = 200;
-              res.setHeader('Content-Type', 'text/css');
-              res.end('');
-              return;
-            }
-
-            const shared = stylexPlugin.__stylexGetSharedStore?.();
-            const rulesById = shared?.rulesById;
-
-            if (!rulesById || rulesById.size === 0) {
-              res.statusCode = 200;
-              res.setHeader('Content-Type', 'text/css');
-              res.end('');
-              return;
-            }
-
-            const libraryRules: any[] = [];
-            const productRules: any[] = [];
-
-            for (const [filePath, rules] of rulesById.entries()) {
-              if (filePath.includes(libraryPattern)) {
-                libraryRules.push(...rules);
-              } else {
-                productRules.push(...rules);
-              }
-            }
-
-            const libraryCss = libraryRules.length
-              ? stylexBabelPlugin.processStylexRules(libraryRules, {
-                  useLayers: true,
-                })
-              : '';
-            const productCss = productRules.length
-              ? stylexBabelPlugin.processStylexRules(productRules, {
-                  useLayers: true,
-                })
-              : '';
-
-            const parts: string[] = [];
-            if (libraryCss)
-              parts.push(`@layer ${libraryLayer} {\n${libraryCss}\n}`);
-            if (productCss)
-              parts.push(`@layer ${productLayer} {\n${productCss}\n}`);
+            const rulesById =
+              stylexPlugin?.__stylexGetSharedStore?.()?.rulesById;
 
             res.statusCode = 200;
             res.setHeader('Content-Type', 'text/css');
             res.setHeader('Cache-Control', 'no-store');
-            res.end(parts.join('\n\n'));
+            res.end(
+              renderSplitLayers(rulesById, {
+                libraryPattern,
+                libraryLayer,
+                productLayer,
+              }),
+            );
           },
         });
       };
     },
   };
 
-  return [layerOrderPlugin, basePlugin, splitLayerPlugin];
+  return [
+    layerOrderPlugin,
+    basePlugin,
+    splitLayerPlugin,
+    buildLayerSplitPlugin(basePlugin, {
+      libraryPattern,
+      libraryLayer,
+      productLayer,
+      lightningcssOptions: (stylexOptions as {lightningcssOptions?: unknown})
+        ?.lightningcssOptions,
+    }),
+  ];
 }