@gears-frontx/react 0.2.0-alpha.2 → 0.2.0-alpha.3

package/dist/index.d.cts

@@ -409,15 +409,23 @@ interface ApiStreamResult<TEvent> {
  * Manages the status lifecycle for a single SSE stream connection.
  *
  * **Status values**
- * - `'idle'` — no connection is being attempted. This is the initial status
- *   before the first connect effect runs, and it is ordinarily the status
- *   while `enabled` is `false`. Consumers must not assume `'idle'` means "never
+ * - `'idle'` — no connection is being attempted. This is the status whenever
+ *   `enabled` is `false`, including on mount: a hook that mounts disabled
+ *   never reports anything but `'idle'` until `enabled` flips to `true`. A
+ *   hook that mounts enabled skips `'idle'` entirely — the status is set
+ *   during render, so its very first render already reports `'connecting'`.
+ *   Consumers must not assume `'idle'` means "never
  *   connected" — a stream that is disabled after having connected returns to
  *   `'idle'` too, and `data`/`events` from the earlier connection are not
  *   cleared by that transition alone (they are cleared by mode/key changes,
  *   see below).
- * - `'connecting'` — `descriptor.connect()` has been called and its promise
- *   has not yet settled.
+ * - `'connecting'` — a connection attempt is committed to but has not settled.
+ *   It is published during the render that turns the stream on, which is
+ *   before `descriptor.connect()` runs: the call is made from an effect after
+ *   that render commits. So `'connecting'` means "this stream is being
+ *   opened", not "the connect promise is pending" — for one render the two
+ *   differ, and a consumer that reads the status as proof a request is already
+ *   in flight is reading it too strongly.
  * - `'connected'` — set both when `connect()` resolves (unless a disconnect
  *   was requested while it was pending) and, independently, whenever the
  *   `onEvent` callback delivers a new event. Because every event re-asserts
@@ -425,20 +433,33 @@ interface ApiStreamResult<TEvent> {
  * - `'disconnected'` — reached via any of: the descriptor's `onComplete`
  *   callback firing (the stream ended normally), `connect()` rejecting while
  *   a disconnect was requested concurrently, or the manual `disconnect()`
- *   function being called. `disconnect()` has no `enabled` guard: called
- *   while the stream is disabled it still sets `'disconnected'`, which
- *   persists until the next connect-effect run.
+ *   function being called. `disconnect()` has no `enabled` guard, but calling
+ *   it while the stream is disabled is not observable: the stored status moves
+ *   to `'disconnected'` while the published one stays `'idle'`, and flipping
+ *   `enabled` back to `true` sets `'connecting'` during that render, so the
+ *   stored `'disconnected'` is overwritten before it is ever returned.
  * - `'error'` — `connect()` rejected and no disconnect was requested while it
  *   was pending. `error` holds the rejection, coerced to an `Error` if it
  *   wasn't one already.
  *
  * **Transitions**
- * - Mount / `enabled` becomes `true` / `descriptor.key` or `mode` changes:
- *   `data`, `events`, and `error` are reset, then status goes to
- *   `'connecting'` and `connect()` is called.
- * - `enabled` becomes `false` (or starts `false`): status is forced to
- *   `'idle'` and `connect()` is never called; no other field is reset by
- *   this transition alone.
+ * - Mounting enabled, `enabled` becoming `true`, or `descriptor.key` / `mode`
+ *   changing while `enabled` is `true`: `data`, `events`, and `error` are reset
+ *   and status is set to `'connecting'` synchronously during render (not from
+ *   an effect); `connect()` is then called from an effect that runs after that
+ *   render commits.
+ * - `descriptor.key` or `mode` changing while `enabled` is `false`: `data`,
+ *   `events`, and `error` are reset all the same, since that reset is not gated
+ *   on `enabled`, but the status write is - so no `'connecting'` is written and
+ *   the published status stays `'idle'`; `connect()` is not called. The skipped
+ *   `'connecting'` is not owed later either: the change counts as handled when
+ *   it happens, so what publishes `'connecting'` is the subsequent flip of
+ *   `enabled` to `true`, once, for whichever key and mode are in force by then.
+ * - `enabled` becomes `false` (or starts `false`): the published status is
+ *   `'idle'` for as long as `enabled` stays `false` — it is derived from
+ *   `enabled` rather than written, so nothing a prior connection stored can
+ *   surface through it — and `connect()` is never called; no other field is
+ *   reset by this transition alone.
  * - Unmount, `descriptor.key` change, `mode` change, or `enabled` flipping to
  *   `false` while connected or connecting: the previous connection is torn
  *   down via `descriptor.disconnect()` once its `connect()` promise settles
@@ -755,13 +776,23 @@ declare function useRegisteredPackages(): string[];
  *
  * Styling strategy:
  * 1. adoptHostStylesIntoShadowRoot() clones all host <style> and <link> into the
- *    shadow root, bringing the full compiled Tailwind CSS (including MFE utilities,
- *    since the host's content paths cover src/mfe_packages/**).
+ *    front of the shadow root, bringing the full compiled Tailwind CSS (including
+ *    MFE utilities, since the host's content paths cover src/mfe_packages/**).
+ *    Front, not back, so the MFE's own stylesheets outrank them - see the method.
  * 2. injectBaseResets() adds box-model resets and :host defaults that aren't part
- *    of Tailwind's compiled output but are needed for consistent rendering.
+ *    of Tailwind's compiled output but are needed for consistent rendering, and
+ *    positions them at the end of the shell-owned head - after the adopted block
+ *    and the isolation style, ahead of the MFE's own CSS.
  * 3. Subclasses may override initializeStyles() to inject additional CSS that is
  *    not covered by the host stylesheet (e.g., MFE-specific @font-face rules).
  *
+ * Every mount therefore leaves the same sequence - adopted host block, shadow
+ * isolation, base resets, then the MFE's stylesheets - so the shell's CSS is
+ * context and the MFE wins every specificity tie against all three shell blocks.
+ * Steps 1 and 2 both position what they own rather than appending beside it,
+ * because a remounted container arrives with its shadow root intact and the MFE's
+ * own stylesheet removed and re-appended around the remount - see each method.
+ *
  * Theme CSS variables are delivered via CSS inheritance from :root (Shadow DOM)
  * or via MountManager injection (iframe). MFE lifecycles do NOT need to subscribe
  * to theme changes or call applyThemeToShadowRoot.
@@ -778,12 +809,83 @@ declare abstract class ThemeAwareReactLifecycle implements MfeEntryLifecycle<Chi
     /**
      * Copy all inline <style> and <link rel="stylesheet"> from the host document
      * into the shadow root so that Tailwind and component styles apply inside the MFE.
+     *
+     * The clones are inserted ahead of everything already in the shadow root, never
+     * appended, because adopted host styles are context rather than authority: where
+     * they and the MFE's own CSS declare the same property at equal specificity, the
+     * MFE has to win. Appending inverted that. `MfeHandlerMF` injects the MFE's
+     * compiled stylesheet into the shadow root before it calls mount, so an appended
+     * clone of the shell's Tailwind preflight - whose
+     * `button, [type='button'], [type='reset'], [type='submit']` rule sets
+     * `background-color: transparent` at specificity (0,1,0) - tied with
+     * `@gears-frontx/ui-kit`'s single-class button rule and won on document order,
+     * leaving every kit Button transparent until it was hovered.
+     *
+     * Inserting at the front rather than pushing MFE styles to the back is what makes
+     * the invariant hold for stylesheets that appear after mount too - a lazily
+     * imported component's CSS module, or whatever initializeStyles() adds - since
+     * those land behind the adopted block by construction.
+     *
+     * A cascade layer around the adopted CSS was the alternative and is rejected:
+     * layered rules lose to unlayered ones at *any* specificity, so a host utility
+     * class would stop overriding an MFE element selector. Document order keeps
+     * specificity in charge and only settles the ties.
+     *
+     * The block replaces its predecessor instead of stacking on it, the same
+     * upsert shape `injectStylesheet` and `injectCssVariables` use in
+     * `@gears-frontx/mfes`' shadow utilities, widened from one id-keyed node to a
+     * marked block. Replacement is required rather than tidy: `createShadowRoot`
+     * hands back an existing `element.shadowRoot` instead of attaching a new one,
+     * so remounting the same container runs this method again on a shadow root
+     * that already holds a full adopted block, and appending would grow it once
+     * per mount with no bound. It does not save re-resolving the cloned `<link>`s -
+     * every mount clones them afresh and the browser resolves each clone; what
+     * replacement buys is that the count stays at one block instead of one per
+     * mount.
+     *
+     * The block is rebuilt from the host head rather than left in place, because
+     * the head is not fixed: a lazily imported chunk adds stylesheets to it after
+     * the first mount, and the second mount has to pick those up.
+     *
+     * The fresh block goes in before the previous one comes out. Removing first
+     * leaves the shadow root with no host CSS at all, and everything between that
+     * removal and the insertion is synchronous work in this same task - so the gap
+     * never reaches a paint, but any code that reads computed styles from the tree
+     * in between sees an unstyled one. Inserting first costs one moment with two
+     * blocks present, which changes nothing: the old block is a clone of the same
+     * host head and loses every tie to the new one on document order anyway.
      */
     protected adoptHostStylesIntoShadowRoot(shadowRoot: ShadowRoot): void;
     /**
      * Box-model resets and :host defaults needed inside every shadow root.
      * These aren't part of Tailwind's compiled output but are required for
      * consistent rendering across browsers.
+     *
+     * Reuses the node a previous mount left behind, exactly as `injectStylesheet`
+     * does in `@gears-frontx/mfes`' shadow utilities: a remount runs against a
+     * shadow root that `createShadowRoot` handed back intact, and appending a
+     * second copy would add one node per mount forever.
+     *
+     * Reuse alone is not enough, which is why the node is also positioned on every
+     * mount rather than left where the previous one sat. These resets are context
+     * like the adopted block is - `border-color: currentColor` on `*` is a 0-0-0
+     * declaration that beats an MFE preflight's own 0-0-0 reset purely on document
+     * order - so they have to stay ahead of the MFE's CSS, and where they land is
+     * not stable on its own. `MfeHandlerMF.wrapLifecycleWithStylesheets` removes the
+     * MFE's stylesheet on unmount and appends a fresh one before the next mount, so
+     * a node merely left in place ends up ahead of that stylesheet on a remount and
+     * behind it on the first mount: two different cascades for one component.
+     * Anchoring it to the end of the shell-owned head gives every mount the same
+     * order - adopted block, isolation, resets, MFE - which is also the order the
+     * adoption method's invariant is written against.
+     *
+     * With no shell-owned node to anchor to, the resets go to the front. That is the
+     * plain-`Element` container: no adopted block, no isolation style, and the MFE
+     * stylesheet already appended by the handler, so the front is again the only
+     * position that leaves the MFE winning ties.
+     *
+     * Looked up by attribute-selector form rather than `getElementById`, which
+     * `ShadowRoot` has but `Element` does not, and this hook takes either.
      */
     private injectBaseResets;
     /**

package/dist/index.d.ts

@@ -409,15 +409,23 @@ interface ApiStreamResult<TEvent> {
  * Manages the status lifecycle for a single SSE stream connection.
  *
  * **Status values**
- * - `'idle'` — no connection is being attempted. This is the initial status
- *   before the first connect effect runs, and it is ordinarily the status
- *   while `enabled` is `false`. Consumers must not assume `'idle'` means "never
+ * - `'idle'` — no connection is being attempted. This is the status whenever
+ *   `enabled` is `false`, including on mount: a hook that mounts disabled
+ *   never reports anything but `'idle'` until `enabled` flips to `true`. A
+ *   hook that mounts enabled skips `'idle'` entirely — the status is set
+ *   during render, so its very first render already reports `'connecting'`.
+ *   Consumers must not assume `'idle'` means "never
  *   connected" — a stream that is disabled after having connected returns to
  *   `'idle'` too, and `data`/`events` from the earlier connection are not
  *   cleared by that transition alone (they are cleared by mode/key changes,
  *   see below).
- * - `'connecting'` — `descriptor.connect()` has been called and its promise
- *   has not yet settled.
+ * - `'connecting'` — a connection attempt is committed to but has not settled.
+ *   It is published during the render that turns the stream on, which is
+ *   before `descriptor.connect()` runs: the call is made from an effect after
+ *   that render commits. So `'connecting'` means "this stream is being
+ *   opened", not "the connect promise is pending" — for one render the two
+ *   differ, and a consumer that reads the status as proof a request is already
+ *   in flight is reading it too strongly.
  * - `'connected'` — set both when `connect()` resolves (unless a disconnect
  *   was requested while it was pending) and, independently, whenever the
  *   `onEvent` callback delivers a new event. Because every event re-asserts
@@ -425,20 +433,33 @@ interface ApiStreamResult<TEvent> {
  * - `'disconnected'` — reached via any of: the descriptor's `onComplete`
  *   callback firing (the stream ended normally), `connect()` rejecting while
  *   a disconnect was requested concurrently, or the manual `disconnect()`
- *   function being called. `disconnect()` has no `enabled` guard: called
- *   while the stream is disabled it still sets `'disconnected'`, which
- *   persists until the next connect-effect run.
+ *   function being called. `disconnect()` has no `enabled` guard, but calling
+ *   it while the stream is disabled is not observable: the stored status moves
+ *   to `'disconnected'` while the published one stays `'idle'`, and flipping
+ *   `enabled` back to `true` sets `'connecting'` during that render, so the
+ *   stored `'disconnected'` is overwritten before it is ever returned.
  * - `'error'` — `connect()` rejected and no disconnect was requested while it
  *   was pending. `error` holds the rejection, coerced to an `Error` if it
  *   wasn't one already.
  *
  * **Transitions**
- * - Mount / `enabled` becomes `true` / `descriptor.key` or `mode` changes:
- *   `data`, `events`, and `error` are reset, then status goes to
- *   `'connecting'` and `connect()` is called.
- * - `enabled` becomes `false` (or starts `false`): status is forced to
- *   `'idle'` and `connect()` is never called; no other field is reset by
- *   this transition alone.
+ * - Mounting enabled, `enabled` becoming `true`, or `descriptor.key` / `mode`
+ *   changing while `enabled` is `true`: `data`, `events`, and `error` are reset
+ *   and status is set to `'connecting'` synchronously during render (not from
+ *   an effect); `connect()` is then called from an effect that runs after that
+ *   render commits.
+ * - `descriptor.key` or `mode` changing while `enabled` is `false`: `data`,
+ *   `events`, and `error` are reset all the same, since that reset is not gated
+ *   on `enabled`, but the status write is - so no `'connecting'` is written and
+ *   the published status stays `'idle'`; `connect()` is not called. The skipped
+ *   `'connecting'` is not owed later either: the change counts as handled when
+ *   it happens, so what publishes `'connecting'` is the subsequent flip of
+ *   `enabled` to `true`, once, for whichever key and mode are in force by then.
+ * - `enabled` becomes `false` (or starts `false`): the published status is
+ *   `'idle'` for as long as `enabled` stays `false` — it is derived from
+ *   `enabled` rather than written, so nothing a prior connection stored can
+ *   surface through it — and `connect()` is never called; no other field is
+ *   reset by this transition alone.
  * - Unmount, `descriptor.key` change, `mode` change, or `enabled` flipping to
  *   `false` while connected or connecting: the previous connection is torn
  *   down via `descriptor.disconnect()` once its `connect()` promise settles
@@ -755,13 +776,23 @@ declare function useRegisteredPackages(): string[];
  *
  * Styling strategy:
  * 1. adoptHostStylesIntoShadowRoot() clones all host <style> and <link> into the
- *    shadow root, bringing the full compiled Tailwind CSS (including MFE utilities,
- *    since the host's content paths cover src/mfe_packages/**).
+ *    front of the shadow root, bringing the full compiled Tailwind CSS (including
+ *    MFE utilities, since the host's content paths cover src/mfe_packages/**).
+ *    Front, not back, so the MFE's own stylesheets outrank them - see the method.
  * 2. injectBaseResets() adds box-model resets and :host defaults that aren't part
- *    of Tailwind's compiled output but are needed for consistent rendering.
+ *    of Tailwind's compiled output but are needed for consistent rendering, and
+ *    positions them at the end of the shell-owned head - after the adopted block
+ *    and the isolation style, ahead of the MFE's own CSS.
  * 3. Subclasses may override initializeStyles() to inject additional CSS that is
  *    not covered by the host stylesheet (e.g., MFE-specific @font-face rules).
  *
+ * Every mount therefore leaves the same sequence - adopted host block, shadow
+ * isolation, base resets, then the MFE's stylesheets - so the shell's CSS is
+ * context and the MFE wins every specificity tie against all three shell blocks.
+ * Steps 1 and 2 both position what they own rather than appending beside it,
+ * because a remounted container arrives with its shadow root intact and the MFE's
+ * own stylesheet removed and re-appended around the remount - see each method.
+ *
  * Theme CSS variables are delivered via CSS inheritance from :root (Shadow DOM)
  * or via MountManager injection (iframe). MFE lifecycles do NOT need to subscribe
  * to theme changes or call applyThemeToShadowRoot.
@@ -778,12 +809,83 @@ declare abstract class ThemeAwareReactLifecycle implements MfeEntryLifecycle<Chi
     /**
      * Copy all inline <style> and <link rel="stylesheet"> from the host document
      * into the shadow root so that Tailwind and component styles apply inside the MFE.
+     *
+     * The clones are inserted ahead of everything already in the shadow root, never
+     * appended, because adopted host styles are context rather than authority: where
+     * they and the MFE's own CSS declare the same property at equal specificity, the
+     * MFE has to win. Appending inverted that. `MfeHandlerMF` injects the MFE's
+     * compiled stylesheet into the shadow root before it calls mount, so an appended
+     * clone of the shell's Tailwind preflight - whose
+     * `button, [type='button'], [type='reset'], [type='submit']` rule sets
+     * `background-color: transparent` at specificity (0,1,0) - tied with
+     * `@gears-frontx/ui-kit`'s single-class button rule and won on document order,
+     * leaving every kit Button transparent until it was hovered.
+     *
+     * Inserting at the front rather than pushing MFE styles to the back is what makes
+     * the invariant hold for stylesheets that appear after mount too - a lazily
+     * imported component's CSS module, or whatever initializeStyles() adds - since
+     * those land behind the adopted block by construction.
+     *
+     * A cascade layer around the adopted CSS was the alternative and is rejected:
+     * layered rules lose to unlayered ones at *any* specificity, so a host utility
+     * class would stop overriding an MFE element selector. Document order keeps
+     * specificity in charge and only settles the ties.
+     *
+     * The block replaces its predecessor instead of stacking on it, the same
+     * upsert shape `injectStylesheet` and `injectCssVariables` use in
+     * `@gears-frontx/mfes`' shadow utilities, widened from one id-keyed node to a
+     * marked block. Replacement is required rather than tidy: `createShadowRoot`
+     * hands back an existing `element.shadowRoot` instead of attaching a new one,
+     * so remounting the same container runs this method again on a shadow root
+     * that already holds a full adopted block, and appending would grow it once
+     * per mount with no bound. It does not save re-resolving the cloned `<link>`s -
+     * every mount clones them afresh and the browser resolves each clone; what
+     * replacement buys is that the count stays at one block instead of one per
+     * mount.
+     *
+     * The block is rebuilt from the host head rather than left in place, because
+     * the head is not fixed: a lazily imported chunk adds stylesheets to it after
+     * the first mount, and the second mount has to pick those up.
+     *
+     * The fresh block goes in before the previous one comes out. Removing first
+     * leaves the shadow root with no host CSS at all, and everything between that
+     * removal and the insertion is synchronous work in this same task - so the gap
+     * never reaches a paint, but any code that reads computed styles from the tree
+     * in between sees an unstyled one. Inserting first costs one moment with two
+     * blocks present, which changes nothing: the old block is a clone of the same
+     * host head and loses every tie to the new one on document order anyway.
      */
     protected adoptHostStylesIntoShadowRoot(shadowRoot: ShadowRoot): void;
     /**
      * Box-model resets and :host defaults needed inside every shadow root.
      * These aren't part of Tailwind's compiled output but are required for
      * consistent rendering across browsers.
+     *
+     * Reuses the node a previous mount left behind, exactly as `injectStylesheet`
+     * does in `@gears-frontx/mfes`' shadow utilities: a remount runs against a
+     * shadow root that `createShadowRoot` handed back intact, and appending a
+     * second copy would add one node per mount forever.
+     *
+     * Reuse alone is not enough, which is why the node is also positioned on every
+     * mount rather than left where the previous one sat. These resets are context
+     * like the adopted block is - `border-color: currentColor` on `*` is a 0-0-0
+     * declaration that beats an MFE preflight's own 0-0-0 reset purely on document
+     * order - so they have to stay ahead of the MFE's CSS, and where they land is
+     * not stable on its own. `MfeHandlerMF.wrapLifecycleWithStylesheets` removes the
+     * MFE's stylesheet on unmount and appends a fresh one before the next mount, so
+     * a node merely left in place ends up ahead of that stylesheet on a remount and
+     * behind it on the first mount: two different cascades for one component.
+     * Anchoring it to the end of the shell-owned head gives every mount the same
+     * order - adopted block, isolation, resets, MFE - which is also the order the
+     * adoption method's invariant is written against.
+     *
+     * With no shell-owned node to anchor to, the resets go to the front. That is the
+     * plain-`Element` container: no adopted block, no isolation style, and the MFE
+     * stylesheet already appended by the handler, so the front is again the only
+     * position that leaves the MFE winning ties.
+     *
+     * Looked up by attribute-selector form rather than `getElementById`, which
+     * `ShadowRoot` has but `Element` does not, and this hook takes either.
      */
     private injectBaseResets;
     /**

package/dist/index.js

@@ -1089,6 +1089,9 @@ function useRegisteredPackages() {
 // src/mfe/ThemeAwareReactLifecycle.tsx
 import { createRoot } from "react-dom/client";
 import { jsx as jsx4 } from "react/jsx-runtime";
+var ADOPTED_HOST_STYLE_ATTR = "data-frontx-adopted-host-style";
+var BASE_RESETS_STYLE_ID = "__frontx-base-resets__";
+var SHELL_OWNED_SHADOW_STYLE_IDS = ["__frontx-shadow-isolation__", "__frontx-css-variables__"];
 function resolveProviderMountOptions(app, bridge, mountContext) {
   const extensionId = mountContext?.extensionId;
   const domainId = mountContext?.domainId;
@@ -1143,27 +1146,108 @@ var ThemeAwareReactLifecycle = class {
   /**
    * Copy all inline <style> and <link rel="stylesheet"> from the host document
    * into the shadow root so that Tailwind and component styles apply inside the MFE.
+   *
+   * The clones are inserted ahead of everything already in the shadow root, never
+   * appended, because adopted host styles are context rather than authority: where
+   * they and the MFE's own CSS declare the same property at equal specificity, the
+   * MFE has to win. Appending inverted that. `MfeHandlerMF` injects the MFE's
+   * compiled stylesheet into the shadow root before it calls mount, so an appended
+   * clone of the shell's Tailwind preflight - whose
+   * `button, [type='button'], [type='reset'], [type='submit']` rule sets
+   * `background-color: transparent` at specificity (0,1,0) - tied with
+   * `@gears-frontx/ui-kit`'s single-class button rule and won on document order,
+   * leaving every kit Button transparent until it was hovered.
+   *
+   * Inserting at the front rather than pushing MFE styles to the back is what makes
+   * the invariant hold for stylesheets that appear after mount too - a lazily
+   * imported component's CSS module, or whatever initializeStyles() adds - since
+   * those land behind the adopted block by construction.
+   *
+   * A cascade layer around the adopted CSS was the alternative and is rejected:
+   * layered rules lose to unlayered ones at *any* specificity, so a host utility
+   * class would stop overriding an MFE element selector. Document order keeps
+   * specificity in charge and only settles the ties.
+   *
+   * The block replaces its predecessor instead of stacking on it, the same
+   * upsert shape `injectStylesheet` and `injectCssVariables` use in
+   * `@gears-frontx/mfes`' shadow utilities, widened from one id-keyed node to a
+   * marked block. Replacement is required rather than tidy: `createShadowRoot`
+   * hands back an existing `element.shadowRoot` instead of attaching a new one,
+   * so remounting the same container runs this method again on a shadow root
+   * that already holds a full adopted block, and appending would grow it once
+   * per mount with no bound. It does not save re-resolving the cloned `<link>`s -
+   * every mount clones them afresh and the browser resolves each clone; what
+   * replacement buys is that the count stays at one block instead of one per
+   * mount.
+   *
+   * The block is rebuilt from the host head rather than left in place, because
+   * the head is not fixed: a lazily imported chunk adds stylesheets to it after
+   * the first mount, and the second mount has to pick those up.
+   *
+   * The fresh block goes in before the previous one comes out. Removing first
+   * leaves the shadow root with no host CSS at all, and everything between that
+   * removal and the insertion is synchronous work in this same task - so the gap
+   * never reaches a paint, but any code that reads computed styles from the tree
+   * in between sees an unstyled one. Inserting first costs one moment with two
+   * blocks present, which changes nothing: the old block is a clone of the same
+   * host head and loses every tie to the new one on document order anyway.
    */
   adoptHostStylesIntoShadowRoot(shadowRoot) {
-    const styleElements = document.head.querySelectorAll("style");
-    styleElements.forEach((el) => {
-      const clone = document.createElement("style");
-      clone.textContent = el.textContent ?? "";
-      shadowRoot.appendChild(clone);
-    });
-    const linkElements = document.head.querySelectorAll('link[rel="stylesheet"]');
-    linkElements.forEach((el) => {
-      const clone = el.cloneNode(true);
-      shadowRoot.appendChild(clone);
+    const supersededStyles = Array.from(shadowRoot.querySelectorAll(`[${ADOPTED_HOST_STYLE_ATTR}]`));
+    const adoptedStyles = document.createDocumentFragment();
+    const hostStyleNodes = document.head.querySelectorAll('style, link[rel="stylesheet"]');
+    hostStyleNodes.forEach((el) => {
+      if (el instanceof HTMLStyleElement) {
+        const clone = document.createElement("style");
+        clone.textContent = el.textContent ?? "";
+        clone.setAttribute(ADOPTED_HOST_STYLE_ATTR, "");
+        adoptedStyles.appendChild(clone);
+        return;
+      }
+      const linkClone = el.cloneNode(true);
+      linkClone.setAttribute(ADOPTED_HOST_STYLE_ATTR, "");
+      adoptedStyles.appendChild(linkClone);
     });
+    shadowRoot.insertBefore(adoptedStyles, shadowRoot.firstChild);
+    supersededStyles.forEach((el) => el.remove());
   }
   /**
    * Box-model resets and :host defaults needed inside every shadow root.
    * These aren't part of Tailwind's compiled output but are required for
    * consistent rendering across browsers.
+   *
+   * Reuses the node a previous mount left behind, exactly as `injectStylesheet`
+   * does in `@gears-frontx/mfes`' shadow utilities: a remount runs against a
+   * shadow root that `createShadowRoot` handed back intact, and appending a
+   * second copy would add one node per mount forever.
+   *
+   * Reuse alone is not enough, which is why the node is also positioned on every
+   * mount rather than left where the previous one sat. These resets are context
+   * like the adopted block is - `border-color: currentColor` on `*` is a 0-0-0
+   * declaration that beats an MFE preflight's own 0-0-0 reset purely on document
+   * order - so they have to stay ahead of the MFE's CSS, and where they land is
+   * not stable on its own. `MfeHandlerMF.wrapLifecycleWithStylesheets` removes the
+   * MFE's stylesheet on unmount and appends a fresh one before the next mount, so
+   * a node merely left in place ends up ahead of that stylesheet on a remount and
+   * behind it on the first mount: two different cascades for one component.
+   * Anchoring it to the end of the shell-owned head gives every mount the same
+   * order - adopted block, isolation, resets, MFE - which is also the order the
+   * adoption method's invariant is written against.
+   *
+   * With no shell-owned node to anchor to, the resets go to the front. That is the
+   * plain-`Element` container: no adopted block, no isolation style, and the MFE
+   * stylesheet already appended by the handler, so the front is again the only
+   * position that leaves the MFE winning ties.
+   *
+   * Looked up by attribute-selector form rather than `getElementById`, which
+   * `ShadowRoot` has but `Element` does not, and this hook takes either.
    */
   injectBaseResets(container) {
-    const style = document.createElement("style");
+    const existing = container.querySelector(
+      `style[id="${BASE_RESETS_STYLE_ID}"]`
+    );
+    const style = existing ?? document.createElement("style");
+    style.id = BASE_RESETS_STYLE_ID;
     style.textContent = `
       *, *::before, *::after {
         box-sizing: border-box;
@@ -1181,7 +1265,17 @@ var ThemeAwareReactLifecycle = class {
         background-color: hsl(var(--background));
       }
     `;
-    container.appendChild(style);
+    const shellOwnedHead = container.querySelectorAll(
+      [
+        `[${ADOPTED_HOST_STYLE_ATTR}]`,
+        ...SHELL_OWNED_SHADOW_STYLE_IDS.map((id) => `[id="${id}"]`)
+      ].join(", ")
+    );
+    const lastShellOwnedNode = shellOwnedHead[shellOwnedHead.length - 1];
+    container.insertBefore(
+      style,
+      lastShellOwnedNode ? lastShellOwnedNode.nextSibling : container.firstChild
+    );
   }
   /**
    * Hook for subclasses to inject additional CSS not covered by the adopted host