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

package/dist/index.d.cts

@@ -366,10 +366,9 @@ declare function useApiSuspenseInfiniteQuery<TPage = unknown, TError = Error>(op
 /**
  * useApiStream - Declarative SSE streaming hook
  *
- * Accepts a StreamDescriptor from @gears-frontx/api and manages the EventSource
- * lifecycle: connects on mount, disconnects on unmount/descriptor change.
- * Returns the latest event, accumulated events, connection status, and
- * a manual disconnect function.
+ * Accepts a StreamDescriptor from @gears-frontx/api and returns the latest
+ * event, accumulated events, connection status, and a manual disconnect
+ * function.
  *
  * @example
  * ```tsx
@@ -395,17 +394,96 @@ interface ApiStreamOptions {
 }
 /** Return type of useApiStream. */
 interface ApiStreamResult<TEvent> {
-    /** Latest event payload (always set in both modes). */
+    /** Latest event payload, set in both modes — `undefined` until the first event and after each connect attempt resets it. */
     data: TEvent | undefined;
     /** All received events when `mode: 'accumulate'`; empty array in `'latest'` mode. */
     events: TEvent[];
     /** Connection lifecycle status. */
     status: StreamStatus;
-    /** Error if the connection failed. */
+    /** Last connect error — set when a connect attempt rejects, cleared when the next attempt starts. */
     error: Error | null;
     /** Manually close the connection. */
     disconnect: () => void;
 }
+/**
+ * Manages the status lifecycle for a single SSE stream connection.
+ *
+ * **Status values**
+ * - `'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'` — 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
+ *   `'connected'`, this status also serves as "still receiving events."
+ * - `'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, 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**
+ * - 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
+ *   (or immediately skipped if it rejected). All four share the same cleanup
+ *   path: the effect's cleanup runs on every dependency change and on unmount.
+ * - Calling `disconnect()`: if a connection id is already resolved, it is
+ *   disconnected immediately and status becomes `'disconnected'`. If
+ *   `connect()` is still pending, the request is recorded and honored when
+ *   the promise settles — the newly resolved connection is torn down instead
+ *   of being adopted, and status is `'disconnected'`. One caveat:
+ *   `disconnect()` does not cancel the event callback, so a buffered or
+ *   in-flight event landing after the call re-asserts `'connected'` — and in
+ *   the pending-connect case the settle handler tears the connection down
+ *   without touching status, so that stray `'connected'` persists.
+ * - Stream completion while `connect()` is still pending: the current
+ *   implementation lets `onComplete` set `'disconnected'`, then the settle
+ *   handler adopts the connection id and re-asserts `'connected'` anyway.
+ *   This is known current behavior, not a durable guarantee: a pending
+ *   upstream derived-status rewrite is expected to remove this transition.
+ *
+ * `enabled` (default `true`) is the only way to defer connecting past mount;
+ * flipping it back to `true` re-runs the same connect sequence as a fresh
+ * mount would.
+ */
 declare function useApiStream<TEvent>(descriptor: StreamDescriptor<TEvent>, options?: ApiStreamOptions): ApiStreamResult<TEvent>;
 
 /**
@@ -498,7 +576,7 @@ declare const MfeProvider: React__default.FC<MfeProviderProps>;
  *   // bridge.executeActionsChain(chain);
  *   // bridge.subscribeToProperty(propertyTypeId, callback);
  *
- *   return <div>Domain: {bridge.domainId}</div>;
+ *   return <div>Domain: {bridge.extDomainId}</div>;
  * }
  * ```
  */
@@ -698,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.
@@ -721,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

@@ -366,10 +366,9 @@ declare function useApiSuspenseInfiniteQuery<TPage = unknown, TError = Error>(op
 /**
  * useApiStream - Declarative SSE streaming hook
  *
- * Accepts a StreamDescriptor from @gears-frontx/api and manages the EventSource
- * lifecycle: connects on mount, disconnects on unmount/descriptor change.
- * Returns the latest event, accumulated events, connection status, and
- * a manual disconnect function.
+ * Accepts a StreamDescriptor from @gears-frontx/api and returns the latest
+ * event, accumulated events, connection status, and a manual disconnect
+ * function.
  *
  * @example
  * ```tsx
@@ -395,17 +394,96 @@ interface ApiStreamOptions {
 }
 /** Return type of useApiStream. */
 interface ApiStreamResult<TEvent> {
-    /** Latest event payload (always set in both modes). */
+    /** Latest event payload, set in both modes — `undefined` until the first event and after each connect attempt resets it. */
     data: TEvent | undefined;
     /** All received events when `mode: 'accumulate'`; empty array in `'latest'` mode. */
     events: TEvent[];
     /** Connection lifecycle status. */
     status: StreamStatus;
-    /** Error if the connection failed. */
+    /** Last connect error — set when a connect attempt rejects, cleared when the next attempt starts. */
     error: Error | null;
     /** Manually close the connection. */
     disconnect: () => void;
 }
+/**
+ * Manages the status lifecycle for a single SSE stream connection.
+ *
+ * **Status values**
+ * - `'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'` — 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
+ *   `'connected'`, this status also serves as "still receiving events."
+ * - `'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, 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**
+ * - 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
+ *   (or immediately skipped if it rejected). All four share the same cleanup
+ *   path: the effect's cleanup runs on every dependency change and on unmount.
+ * - Calling `disconnect()`: if a connection id is already resolved, it is
+ *   disconnected immediately and status becomes `'disconnected'`. If
+ *   `connect()` is still pending, the request is recorded and honored when
+ *   the promise settles — the newly resolved connection is torn down instead
+ *   of being adopted, and status is `'disconnected'`. One caveat:
+ *   `disconnect()` does not cancel the event callback, so a buffered or
+ *   in-flight event landing after the call re-asserts `'connected'` — and in
+ *   the pending-connect case the settle handler tears the connection down
+ *   without touching status, so that stray `'connected'` persists.
+ * - Stream completion while `connect()` is still pending: the current
+ *   implementation lets `onComplete` set `'disconnected'`, then the settle
+ *   handler adopts the connection id and re-asserts `'connected'` anyway.
+ *   This is known current behavior, not a durable guarantee: a pending
+ *   upstream derived-status rewrite is expected to remove this transition.
+ *
+ * `enabled` (default `true`) is the only way to defer connecting past mount;
+ * flipping it back to `true` re-runs the same connect sequence as a fresh
+ * mount would.
+ */
 declare function useApiStream<TEvent>(descriptor: StreamDescriptor<TEvent>, options?: ApiStreamOptions): ApiStreamResult<TEvent>;
 
 /**
@@ -498,7 +576,7 @@ declare const MfeProvider: React__default.FC<MfeProviderProps>;
  *   // bridge.executeActionsChain(chain);
  *   // bridge.subscribeToProperty(propertyTypeId, callback);
  *
- *   return <div>Domain: {bridge.domainId}</div>;
+ *   return <div>Domain: {bridge.extDomainId}</div>;
  * }
  * ```
  */
@@ -698,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.
@@ -721,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;
     /**