Checking Layer Support With CSS.supports in JavaScript

// All of these return false in fully supporting browsers.
CSS.supports('@layer');                 // false — not a declaration
CSS.supports('@layer', 'base');         // false — not a property/value pair
CSS.supports('at-rule(@layer)');        // false — not the JS form of the syntax

// WHY: CSS.supports takes either a "property: value" declaration or, in its
// one-argument form, a condition made of such declarations and selector()
// tests. At-rules are outside its grammar entirely, so the answer is always
// false — which is indistinguishable from "not supported" and therefore a
// trap.
CSS.supports('color', 'revert-layer');  // true in supporting browsers ✓

// WHY a constructed stylesheet: it never touches the document, so the probe
// cannot affect rendering. If the engine does not understand @layer it
// discards the rule at parse time, and cssRules comes back empty.
export function supportsCascadeLayers() {
  try {
    const sheet = new CSSStyleSheet();
    sheet.replaceSync('@layer probe { }');
    return sheet.cssRules.length > 0 &&
           sheet.cssRules[0].constructor.name === 'CSSLayerBlockRule';
  } catch {
    // Constructable stylesheets are themselves a 2021+ feature; a browser
    // without them certainly predates @layer, so false is the right answer.
    return false;
  }
}

/* WHY at-rule() rather than JavaScript: no script, no layout shift, no
   hydration timing. The browser evaluates this while parsing. */
@supports at-rule(@layer) {
  @layer components {
    .card { border: 1px solid var(--color-border); }
  }
}

/* WHY the negated branch is a separate, self-contained block: an engine that
   does not understand @layer also discards the @layer block above ENTIRELY,
   so the fallback must restate the rules rather than adjust them. */
@supports not at-rule(@layer) {
  .card { border: 1px solid #d4c89a; }
}

// WHY a decision, not a reflex: each option has a real cost, and for most
// audiences the right answer is the last one.
if (!supportsCascadeLayers()) {
  // Option A — fetch the polyfilled bundle. Costs a round trip for old
  // browsers only, and the polyfill inflates specificity for everyone in it.
  import('/assets/index.polyfilled.css');

  // Option B — degrade. The layered stylesheet was discarded, so the page
  // needs a complete unlayered fallback, not a patch.

  // Option C — do nothing. Correct when the affected traffic is negligible,
  // and by far the cheapest to maintain.
}

# Every selector in the layered bundle should have a counterpart in the
# fallback — an unsupported @layer block is discarded whole, not partially.
grep -o "^\s*\.[a-z0-9_-]*" dist/assets/index.css | sort -u > /tmp/layered.txt
grep -o "^\s*\.[a-z0-9_-]*" dist/assets/fallback.css | sort -u > /tmp/fallback.txt
comm -23 /tmp/layered.txt /tmp/fallback.txt

// src/lib/layer-support.js — complete, dependency-free detection.

/**
 * Definitive test for @layer support.
 * WHY a constructed sheet: it is never adopted into the document, so the
 * probe has no rendering side effects and no cleanup.
 */
export function supportsCascadeLayers() {
  if (typeof CSSStyleSheet === 'undefined') return false;
  try {
    const sheet = new CSSStyleSheet();
    sheet.replaceSync('@layer probe { }');
    if (sheet.cssRules.length === 0) return false;
    // WHY instanceof with a guard: constructor.name breaks under minifiers
    // that rename globals; the guard covers engines lacking the interface.
    return typeof CSSLayerBlockRule !== 'undefined' &&
           sheet.cssRules[0] instanceof CSSLayerBlockRule;
  } catch {
    return false;
  }
}

/**
 * Cheap proxy for the same question, usable where a constructed sheet is
 * unavailable. WHY it works: `revert-layer` shipped in the same releases as
 * @layer, and unlike an at-rule it IS testable by CSS.supports.
 */
export function supportsCascadeLayersProxy() {
  return typeof CSS !== 'undefined' &&
         CSS.supports?.('color', 'revert-layer') === true;
}

/**
 * The only decision most applications need to make.
 * WHY it is async and lazy: the fallback bundle must not cost anything for
 * the overwhelming majority of visitors who do not need it.
 */
export async function ensureStyles() {
  if (supportsCascadeLayers()) return 'native';
  const link = document.createElement('link');
  link.rel = 'stylesheet';
  link.href = '/assets/index.fallback.css';
  document.head.append(link);
  return 'fallback';
}

/* src/styles/entry.css — the CSS-only equivalent, preferred where the
   difference is purely visual. */
@supports at-rule(@layer) {
  @layer reset, base, theme, components, utilities;
  @import url("./layers/all.css");
}

/* WHY a full restatement rather than a patch: without @layer support the
   block above is discarded in its entirety, so this branch is not an
   override — it is the whole stylesheet for those engines. */
@supports not at-rule(@layer) {
  @import url("./fallback/all.css");
}