@stigmer/react 3.9.0 → 3.11.0

package/src/__tests__/preflight-parity.layout.test.tsx

@@ -0,0 +1,156 @@
+// Preflight-parity regression suite for form controls (#374).
+//
+// Runs in a real Chromium via `vitest.a11y.config.ts` — the defect under
+// guard is the user agent's OWN default control styling (buttonface
+// background, built-in padding, UA font stack), which only a real browser
+// applies. happy-dom has no UA stylesheet, so it would pass vacuously.
+//
+// The contract: every SDK component is authored against Tailwind's preflight
+// baseline (our consoles run it globally). In a host WITHOUT a preflight —
+// third-party embeds, the packed demo tours — the scoped form-control
+// preflight in `styles.css` must reproduce that baseline under `.stgm`, or
+// every unstyled-by-intent button renders as a grey UA box (the #374
+// screenshots). Like the sibling layout suites (DD-21), this renders against
+// the SHIPPED stylesheet (`dist/styles.css`, rebuilt by `npm run build:css`)
+// and nothing else — exactly what an embed loads.
+//
+// Two directions, both load-bearing:
+// 1. UA defaults neutralized: bare controls show no buttonface box, no UA
+//    padding, no UA font.
+// 2. Utilities still win: the preflight lives in `@layer base`, so `bg-*`
+//    and `p-*` utilities on themed components must beat it. This half is
+//    what fails if the block ever migrates to a layer above `utilities`
+//    (the exact mistake that shipped three times with the border reset —
+//    see styles-border-layer-invariant.test.ts for the host-compiled twin).
+
+import "../../dist/styles.css";
+
+import { describe, it, expect, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import type { Stigmer } from "@stigmer/sdk";
+import { StigmerProvider } from "../provider";
+import { Button } from "../button/Button.js";
+import { UNSTYLED_BUTTON } from "../internal/form-primitives.js";
+
+afterEach(cleanup);
+
+// A minimal client (the provider-container suite's idiom): a null credential
+// keeps the provider's registry fetches non-blocking so rendering is
+// synchronous and never touches the network.
+function makeClient(): Stigmer {
+  return {
+    baseUrl: "https://example.test",
+    getAuthCredential: async () => null,
+    fetch: (async () => {
+      throw new Error("network disabled in test");
+    }) as unknown as typeof globalThis.fetch,
+  } as unknown as Stigmer;
+}
+
+/**
+ * Renders `ui` inside the provider, wrapped in a probe `<div>` with a
+ * distinctive font so inheritance is detectable: a control that inherits
+ * (`font: inherit`) computes to Georgia; one still wearing the UA button
+ * font does not.
+ */
+function renderScoped(ui: React.ReactNode): HTMLElement {
+  render(
+    <StigmerProvider client={makeClient()}>
+      <div data-testid="probe" style={{ fontFamily: "Georgia, serif" }}>
+        {ui}
+      </div>
+    </StigmerProvider>,
+  );
+  return document.querySelector('[data-testid="probe"]') as HTMLElement;
+}
+
+function computed(el: Element): CSSStyleDeclaration {
+  return getComputedStyle(el);
+}
+
+const TRANSPARENT = "rgba(0, 0, 0, 0)";
+
+describe("scoped form-control preflight (#374)", () => {
+  describe("UA defaults are neutralized under .stgm", () => {
+    it("a bare button loses the buttonface box, UA padding, and UA font", () => {
+      const probe = renderScoped(<button type="button">bare</button>);
+      const style = computed(probe.querySelector("button")!);
+
+      expect(style.backgroundColor, "UA buttonface background must be cleared").toBe(TRANSPARENT);
+      // Chromium's UA button padding is 1px 6px — all four sides must be 0.
+      expect(
+        [style.paddingTop, style.paddingRight, style.paddingBottom, style.paddingLeft],
+        "UA button padding must be zeroed",
+      ).toEqual(["0px", "0px", "0px", "0px"]);
+      expect(style.fontFamily, "button font must inherit, not the UA stack").toBe(
+        computed(probe).fontFamily,
+      );
+      expect(style.borderTopLeftRadius).toBe("0px");
+    });
+
+    it("an unstyled-by-intent tile button (the #371 shape) renders content-only", () => {
+      // The exact pattern the issue screenshotted: an image tile whose only
+      // classes are UNSTYLED_BUTTON + geometry.
+      const probe = renderScoped(
+        <button type="button" className={`${UNSTYLED_BUTTON} stg:relative stg:block stg:h-14 stg:w-14 stg:rounded-md`}>
+          tile
+        </button>,
+      );
+      const style = computed(probe.querySelector("button")!);
+
+      expect(style.backgroundColor).toBe(TRANSPARENT);
+      expect(style.paddingLeft).toBe("0px");
+      expect(style.cursor, "UNSTYLED_BUTTON supplies the pointer cursor").toBe("pointer");
+      // Geometry utilities keep working on top of the reset.
+      expect(style.width).toBe("56px");
+      expect(style.borderTopLeftRadius).not.toBe("0px");
+    });
+
+    it("bare input, textarea, and select lose UA backgrounds and inherit the font", () => {
+      const probe = renderScoped(
+        <>
+          <input readOnly value="i" />
+          <textarea readOnly value="t" />
+          <select defaultValue="o">
+            <option value="o">o</option>
+          </select>
+        </>,
+      );
+
+      for (const tag of ["input", "textarea", "select"] as const) {
+        const style = computed(probe.querySelector(tag)!);
+        expect(style.backgroundColor, `${tag} UA background must be cleared`).toBe(TRANSPARENT);
+        expect(style.fontFamily, `${tag} font must inherit`).toBe(computed(probe).fontFamily);
+      }
+      expect(
+        computed(probe.querySelector("textarea")!).resize,
+        "textareas resize vertically only (preflight parity)",
+      ).toBe("vertical");
+    });
+  });
+
+  describe("utilities still beat the preflight (the base-vs-utilities invariant, on the shipped artifact)", () => {
+    it("the themed Button keeps its background and padding", () => {
+      const probe = renderScoped(<Button variant="primary">go</Button>);
+      const style = computed(probe.querySelector("button")!);
+
+      // `bg-primary` must survive the preflight's background-color:
+      // transparent — this is the assertion that fails if the form-control
+      // block ever lands in a layer above `utilities`.
+      expect(style.backgroundColor, "bg-primary must win over the preflight").not.toBe(
+        TRANSPARENT,
+      );
+      // size "sm" = px-3 py-1.5 → 12px / 6px.
+      expect(style.paddingLeft, "p-* utilities must win over the preflight").toBe("12px");
+      expect(style.paddingTop).toBe("6px");
+    });
+
+    it("the ghost Button is transparent by design and stays that way", () => {
+      // Ghost sets NO bg-* utility: pre-#374 it silently wore the UA
+      // buttonface grey in embeds. Transparent here proves the preflight is
+      // what ghost was implicitly depending on all along.
+      const probe = renderScoped(<Button variant="ghost">go</Button>);
+      expect(computed(probe.querySelector("button")!).backgroundColor).toBe(TRANSPARENT);
+    });
+  });
+});

package/src/__tests__/scope-unprefixed.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from "vitest";
+import postcss from "postcss";
+import { scopeUnprefixedSelectors } from "../../scripts/lib/scope-unprefixed";
+
+/**
+ * Fixture-level pins for the build's scoping pass (stage 2 of
+ * `scripts/build-styles.ts`). The dist isolation invariant proves the OUTPUT
+ * is fully scoped; these pins prove the transform handles each selector shape
+ * the way the cascade requires — especially pseudo-element placement, where a
+ * guard in the wrong position is invalid CSS that a browser silently drops.
+ */
+
+function transform(css: string): string {
+  const root = postcss.parse(css);
+  scopeUnprefixedSelectors(root);
+  return root.toString();
+}
+
+describe("scopeUnprefixedSelectors", () => {
+  it("scopes unlayered rules (the xyflow tail) on the subject compound", () => {
+    expect(transform(".react-flow__node{position:absolute}")).toBe(
+      ".react-flow__node:where(.stgm, .stgm *){position:absolute}",
+    );
+  });
+
+  it("scopes only the subject of a complex selector", () => {
+    expect(transform(".react-flow .react-flow__edge>path{stroke:red}")).toBe(
+      ".react-flow .react-flow__edge>path:where(.stgm, .stgm *){stroke:red}",
+    );
+  });
+
+  it("places the guard BEFORE pseudo-elements (double- and single-colon)", () => {
+    expect(transform("*::before{content:''}")).toBe(
+      "*:where(.stgm, .stgm *)::before{content:''}",
+    );
+    // Minifier output uses legacy single-colon spellings.
+    expect(transform(".x:before{content:''}")).toBe(
+      ".x:where(.stgm, .stgm *):before{content:''}",
+    );
+    expect(transform("::backdrop{--tw-x:0}")).toBe(
+      ":where(.stgm, .stgm *)::backdrop{--tw-x:0}",
+    );
+  });
+
+  it("keeps pseudo-CLASSES inside the guarded compound", () => {
+    expect(transform(".react-flow__pane:hover{cursor:grab}")).toBe(
+      ".react-flow__pane:hover:where(.stgm, .stgm *){cursor:grab}",
+    );
+  });
+
+  it("scopes every alternative of a selector list", () => {
+    expect(transform("a,.b{color:red}")).toBe(
+      "a:where(.stgm, .stgm *),.b:where(.stgm, .stgm *){color:red}",
+    );
+  });
+
+  it("scopes @layer properties rules (universal --tw-* initial values)", () => {
+    expect(
+      transform("@layer properties{*,::before{--tw-translate-x:0}}"),
+    ).toBe(
+      "@layer properties{*:where(.stgm, .stgm *),:where(.stgm, .stgm *)::before{--tw-translate-x:0}}",
+    );
+  });
+
+  it("leaves named layers other than `properties` untouched (prefix covers them)", () => {
+    const stgm = "@layer stgm{.stg\\:flex{display:flex}}";
+    expect(transform(stgm)).toBe(stgm);
+    const base = "@layer base{.stgm *{border-width:0}}";
+    expect(transform(base)).toBe(base);
+  });
+
+  it("leaves keyframe steps untouched", () => {
+    const kf = "@keyframes spin{to{transform:rotate(360deg)}}";
+    expect(transform(kf)).toBe(kf);
+  });
+
+  it("leaves already-.stgm-scoped unlayered rules untouched", () => {
+    const scoped = ".stgm .hljs{color:red}";
+    expect(transform(scoped)).toBe(scoped);
+  });
+
+  it("is idempotent", () => {
+    const once = transform(".react-flow{direction:ltr}");
+    expect(transform(once)).toBe(once);
+  });
+});

package/src/__tests__/styles-border-layer-invariant.test.ts

@@ -1,35 +1,23 @@
 import { describe, it, expect } from "vitest";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import postcss, {
-  type AtRule,
-  type Rule,
-  type Container,
-  type Document as PostcssDocument,
-} from "postcss";
-import tailwindcss from "@tailwindcss/postcss";
-
-// The directory of `styles.css` — `@source` globs and relative `@import`s inside
-// it resolve from here, exactly as they do when a host app compiles it.
-const srcDir = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+import { type AtRule, type Rule, type Container, type Document as PostcssDocument } from "postcss";
+import { compileSdkStylesheet } from "./helpers/compile-sdk-styles";
 
 /**
- * Compile the SDK stylesheet the way the client apps actually do: the host's
- * Tailwind first (`@import "tailwindcss"`, which puts preflight in `base` and
- * utilities in `utilities`), then the SDK's `styles.css` layered on top. This is
- * the pipeline that broke every prior border fix — the standalone
- * `tailwindcss -i styles.css` build (which the apps never consume) hid the bug
- * because it lacks the competing host `utilities` layer.
+ * The border-layer invariant: the `.stgm` preflight-style reset (which zeroes
+ * `border-width` on every descendant) must never outrank the `border-*`
+ * utilities, or every border inside `.stgm` silently disappears — the defect
+ * that shipped twice before this test existed.
+ *
+ * Since #454 the SDK stylesheet is a self-contained compiled artifact (client
+ * apps and hosts consume `dist/styles.css`; nobody recompiles the source), so
+ * the cascade under test is the standalone build's own layer order: the reset
+ * lives in `base`, the `stg:`-prefixed utilities live in `stgm`, and the
+ * `@layer theme, base, components, utilities, stgm` declaration pins
+ * `base` below `stgm`. (Pre-#454 this test compiled a simulated host context,
+ * because hosts inlined the SDK source into their own Tailwind build and the
+ * utilities landed in the HOST's `utilities` layer — that pipeline no longer
+ * exists.)
  */
-async function compileHostContext(): Promise<string> {
-  const input = `@import "tailwindcss";\n@import "./styles.css";`;
-  const result = await postcss([tailwindcss({ base: srcDir })]).process(input, {
-    // A virtual entry inside src/ so `@import "./styles.css"` resolves to the
-    // real SDK stylesheet under test.
-    from: resolve(srcDir, "__border-layer-probe__.css"),
-  });
-  return result.css;
-}
 
 /** The nearest enclosing `@layer <name>` of a node, or null if unlayered. */
 function enclosingLayer(node: Rule | AtRule): string | null {
@@ -44,30 +32,31 @@ function enclosingLayer(node: Rule | AtRule): string | null {
   return null;
 }
 
-describe("styles.css border-layer invariant (host-compiled)", () => {
-  // The class-name assertions in ToolCallItem/ApprovalCard tests prove the
-  // markup *requests* a border; they run in happy-dom, which cannot resolve
-  // `@layer` and so cannot prove the border actually *renders*. This compiles
-  // the real host-context cascade and asserts the architecture that makes it
-  // render: the scoped preflight reset must never outrank the border utilities.
-  it("emits the .stgm border reset in `base`, below the `utilities` layer", async () => {
-    const css = await compileHostContext();
-    const root = postcss.parse(css);
+describe("styles.css border-layer invariant", () => {
+  it("emits the .stgm border reset in `base`, below the utilities in `stgm`", async () => {
+    const root = await compileSdkStylesheet();
 
-    // 1) Scanning/generation works: the prominent border-color utility exists.
-    //    (If this regresses, the border would silently fall back to the faint
-    //    --stgm-border default — the dark-mode half of the original defect.)
+    // 1) Scanning/generation works: the prominent border-color utility exists,
+    //    under the #454 prefix. (If this regresses, the border would silently
+    //    fall back to the faint --stgm-border default — the dark-mode half of
+    //    the original defect.)
     let prominentRule: Rule | null = null;
     root.walkRules((rule) => {
-      if (rule.selector.includes(".border-border-prominent")) prominentRule = rule;
+      if (rule.selector.includes(".stg\\:border-border-prominent")) {
+        prominentRule = rule;
+      }
     });
     expect(
       prominentRule,
-      "`.border-border-prominent` was not generated — host did not scan the SDK source",
+      "`.stg\\:border-border-prominent` was not generated — @source scanning or the stg: prefix broke",
     ).not.toBeNull();
+    expect(
+      enclosingLayer(prominentRule!),
+      "border utilities must live in @layer stgm (the standalone build's utility layer)",
+    ).toBe("stgm");
 
-    // 2) The reset (the rule that zeroes border-width on every .stgm descendant)
-    //    must live in `base`, not in a layer declared after `utilities`.
+    // 2) The reset (the rule that zeroes border-width on every .stgm
+    //    descendant) must live in `base`, declared before `stgm`.
     let resetRule: Rule | null = null;
     root.walkRules((rule) => {
       if (!rule.selector.includes(".stgm")) return;
@@ -82,24 +71,63 @@ describe("styles.css border-layer invariant (host-compiled)", () => {
     expect(resetRule, "the .stgm border-width:0 reset was not found").not.toBeNull();
     expect(
       enclosingLayer(resetRule!),
-      "the .stgm border reset must live in @layer base (it was placed in a layer above `utilities`, which silently zeroes every border inside .stgm)",
+      "the .stgm border reset must live in @layer base (a reset in a layer above the utilities silently zeroes every border inside .stgm)",
     ).toBe("base");
 
-    // 3) Belt and suspenders: `base` is declared before `utilities`, so a later
-    //    `border`/`border-*` utility wins the cascade.
-    const layerOrder: string[] = [];
+    // 3) The normative layer order comes from the bare `@layer a, b, c;`
+    //    declaration at the top of the stylesheet: `base` must precede `stgm`.
+    let order: string[] | null = null;
     root.walkAtRules("layer", (at) => {
-      if (!at.nodes) return; // skip the bare `@layer a, b, c;` ordering statement
-      const name = at.params.trim();
-      if (name && !layerOrder.includes(name)) layerOrder.push(name);
+      if (at.nodes) return; // only the bare ordering statement
+      const names = at.params.split(",").map((s) => s.trim());
+      if (!order && names.includes("base") && names.includes("stgm")) {
+        order = names;
+      }
+    });
+    expect(order, "the @layer ordering declaration is missing").not.toBeNull();
+    expect(
+      order!.indexOf("base"),
+      `expected base before stgm in [${order!.join(", ")}]`,
+    ).toBeLessThan(order!.indexOf("stgm"));
+  });
+
+  // The form-control preflight (#374) has the same one dangerous failure mode
+  // as the border reset: land it in any layer above the SDK's utilities and
+  // it silently overrides every `stg:bg-*`/`stg:p-*` utility on every button
+  // in the SDK. Same harness, same invariant — pinned separately because the
+  // rule is found by a different fingerprint (background-color on
+  // `.stgm button`).
+  it("emits the .stgm form-control preflight in `base`, below the utilities in `stgm`", async () => {
+    const root = await compileSdkStylesheet();
+
+    let controlRule: Rule | null = null;
+    root.walkRules((rule) => {
+      if (!rule.selector.includes(".stgm button")) return;
+      const clearsBackground = rule.some(
+        (decl) =>
+          decl.type === "decl" &&
+          decl.prop === "background-color" &&
+          decl.value.trim() === "transparent",
+      );
+      if (clearsBackground) controlRule = rule;
     });
-    const baseIdx = layerOrder.indexOf("base");
-    const utilitiesIdx = layerOrder.indexOf("utilities");
-    expect(baseIdx).toBeGreaterThanOrEqual(0);
-    expect(utilitiesIdx).toBeGreaterThanOrEqual(0);
     expect(
-      baseIdx,
-      `expected @layer base (#${baseIdx}) to precede @layer utilities (#${utilitiesIdx}); order was [${layerOrder.join(", ")}]`,
-    ).toBeLessThan(utilitiesIdx);
+      controlRule,
+      "the .stgm form-control preflight (background-color: transparent on .stgm button) was not found",
+    ).not.toBeNull();
+    expect(
+      enclosingLayer(controlRule!),
+      "the .stgm form-control preflight must live in @layer base (a layer above the utilities silently overrides every stg:bg-*/stg:p-* utility on every button in the SDK)",
+    ).toBe("base");
+
+    // The block must cover all five control elements, not just button —
+    // an accidental selector trim would silently re-expose the UA defaults
+    // on inputs/textareas in preflight-less hosts.
+    for (const control of ["input", "select", "optgroup", "textarea"]) {
+      expect(
+        controlRule!.selector,
+        `the form-control preflight selector must include .stgm ${control}`,
+      ).toContain(`.stgm ${control}`);
+    }
   });
 });

package/src/__tests__/styles-dist-isolation.test.ts

@@ -0,0 +1,195 @@
+import { describe, expect, it } from "vitest";
+import postcss, { type AtRule, type Container, type Rule, type Root } from "postcss";
+import selectorParser from "postcss-selector-parser";
+import { compileSdkStylesheet } from "./helpers/compile-sdk-styles";
+
+/**
+ * The #454 isolation invariant: NOTHING in the shipped SDK stylesheet may
+ * match a host application's DOM outside the `.stgm` scope containers.
+ *
+ * Before this invariant, the stylesheet emitted bare Tailwind utilities
+ * (`.relative`, `.grid-cols-1`, `.container`) inside `@layer stgm` — which
+ * the SDK's own layer-order declaration pins ABOVE a host's `utilities`
+ * layer. Loading the stylesheet silently broke any host element pairing a
+ * base utility with a variant override of the same property
+ * (`grid-cols-1 @xl:grid-cols-[...]`, `relative max-lg:fixed`) — permanently,
+ * regardless of load order. Observed in production (Stigmer Law).
+ *
+ * Every rule must therefore fall in exactly one of these categories:
+ *
+ *  1. `stg:`-prefixed — Tailwind utilities under the #454 prefix
+ *     (`.stg\:flex`). Collision-free by NAME: a host's Tailwind never emits
+ *     these class names.
+ *  2. `.stgm`-anchored — the scope container itself, hand-written
+ *     `.stgm .hljs-*` rules, and everything carrying the
+ *     `:where(.stgm, .stgm *)` guard added by the build's scoping pass
+ *     (xyflow, the `@layer properties` block).
+ *  3. `stgm-`-prefixed classes — hand-written component classes
+ *     (`.stgm-thread-item-enter`) and theme presets (`.stgm-theme-*`).
+ *  4. `:root`/`:host` rules whose declarations are ALL namespaced custom
+ *     properties: `--stgm-*` (the public token contract — deliberately on
+ *     `:root`, because custom properties resolve by inheritance PROXIMITY:
+ *     moving the defaults onto `.stgm` would shadow the documented
+ *     `:root { --stgm-primary: ... }` host override channel) or `--stg-*`
+ *     (Tailwind theme variables under the prefix).
+ *
+ * Allowed globals, by name rather than selector:
+ *  - `@property --tw-*` / `--stg-*` registrations (inherently global;
+ *    duplicate identical registrations are a no-op).
+ *  - `@keyframes` (cannot be selector-scoped; Tailwind names like `spin`
+ *    collide only with identical definitions from the same Tailwind version,
+ *    and our own animations use `stgm-*` names).
+ *
+ * This makes the entire leak CLASS a test failure — not just the two
+ * symptoms the issue reported.
+ */
+
+/** The names of all at-rules enclosing a node, outermost first. */
+function enclosingAtRuleNames(node: Rule | AtRule): string[] {
+  const names: string[] = [];
+  let parent: Container | undefined = node.parent as Container | undefined;
+  while (parent) {
+    if (parent.type === "atrule") names.unshift((parent as AtRule).name);
+    parent = parent.parent as Container | undefined;
+  }
+  return names;
+}
+
+/**
+ * Category check for a single selector (one comma-separated alternative).
+ * Implemented independently of the build's scoping pass on purpose: the test
+ * must not share the code it verifies.
+ */
+function selectorIsIsolated(selector: string): boolean {
+  let isolated = false;
+  try {
+    selectorParser((sel) => {
+      sel.walkClasses((cls) => {
+        if (
+          cls.value.startsWith("stg:") ||
+          cls.value === "stgm" ||
+          cls.value.startsWith("stgm-")
+        ) {
+          isolated = true;
+        }
+      });
+      // `data-stgm-*` attributes are the SDK's public selector namespace
+      // (data-stgm-root, data-stgm-portal, data-stgm-color-mode) — a host
+      // element matches only by explicitly opting into it.
+      sel.walkAttributes((attr) => {
+        if (attr.attribute.startsWith("data-stgm-")) isolated = true;
+      });
+    }).processSync(selector);
+  } catch {
+    return false;
+  }
+  return isolated;
+}
+
+/**
+ * A rule is isolated when its own selectors are, OR when it is nested inside
+ * an isolated rule (`&`-relative selectors cannot match anything the parent
+ * does not already scope — e.g. the unminified compile keeps
+ * `.stg\:[&>button:hover]:...` utilities as nested `&>button:hover` rules;
+ * the shipped minifier flattens these).
+ */
+function ruleIsIsolated(rule: Rule): boolean {
+  if (rule.selectors.every(selectorIsIsolated)) return true;
+  let parent: Container | undefined = rule.parent as Container | undefined;
+  while (parent) {
+    if (parent.type === "rule" && (parent as Rule).selectors.every(selectorIsIsolated)) {
+      return true;
+    }
+    parent = parent.parent as Container | undefined;
+  }
+  return false;
+}
+
+/** `:root` / `:host`-only selector? (Tolerates `:where()`-wrapped forms.) */
+function isRootSelector(selector: string): boolean {
+  return selector
+    .split(",")
+    .every((part) => /^\s*:(root|host|where\(\s*:(root|host)\s*\))\s*$/.test(part.trim()));
+}
+
+function ruleViolations(root: Root): string[] {
+  const violations: string[] = [];
+  root.walkRules((rule) => {
+    const atRules = enclosingAtRuleNames(rule);
+    if (atRules.some((n) => n === "keyframes" || n.endsWith("keyframes"))) {
+      return; // allowed global (see header)
+    }
+    if (isRootSelector(rule.selector)) {
+      // Category 4: every declaration must be a namespaced custom property.
+      rule.walkDecls((decl) => {
+        if (!/^--stgm?-/.test(decl.prop)) {
+          violations.push(
+            `:root rule declares non-namespaced property \`${decl.prop}\` — ` +
+              `it would apply to the host's document root`,
+          );
+        }
+      });
+      return;
+    }
+    if (!ruleIsIsolated(rule)) {
+      violations.push(
+        `unisolated selector \`${rule.selector}\`` +
+          (atRules.length > 0 ? ` (inside @${atRules.join(" @")})` : ""),
+      );
+    }
+  });
+  return violations;
+}
+
+describe("styles.css dist isolation invariant (#454)", () => {
+  it("emits no selector that can match host DOM outside the .stgm scope", async () => {
+    const root = await compileSdkStylesheet();
+
+    // Sanity: this is a real build, not an empty compile.
+    let ruleCount = 0;
+    root.walkRules(() => {
+      ruleCount++;
+    });
+    expect(ruleCount).toBeGreaterThan(500);
+
+    const violations = ruleViolations(root);
+    expect(
+      violations,
+      `the shipped stylesheet leaks into host pages:\n  ${violations.slice(0, 20).join("\n  ")}` +
+        (violations.length > 20 ? `\n  ... and ${violations.length - 20} more` : ""),
+    ).toEqual([]);
+  });
+
+  it("@property registrations stay in the internal variable namespaces", async () => {
+    const root = await compileSdkStylesheet();
+    const offenders: string[] = [];
+    let count = 0;
+    root.walkAtRules("property", (at) => {
+      count++;
+      if (!/^--(tw|stg)-/.test(at.params.trim())) offenders.push(at.params.trim());
+    });
+    expect(count).toBeGreaterThan(0);
+    expect(
+      offenders,
+      "a global @property registration outside --tw-*/--stg-* could clobber a host-registered property",
+    ).toEqual([]);
+  });
+
+  it("negative control: a bare utility selector is detected as a leak", async () => {
+    // Prove the walker actually catches the defect class this test exists
+    // for: inject the exact shape the pre-#454 stylesheet shipped.
+    const root = postcss.parse(
+      "@layer stgm{.relative{position:relative}.stg\\:flex{display:flex}}",
+    );
+    const violations = ruleViolations(root);
+    expect(violations).toHaveLength(1);
+    expect(violations[0]).toContain(".relative");
+  });
+
+  it("negative control: non-custom-property declarations on :root are detected", async () => {
+    const root = postcss.parse(":root{--stgm-x:1;color:red}");
+    const violations = ruleViolations(root);
+    expect(violations).toHaveLength(1);
+    expect(violations[0]).toContain("color");
+  });
+});