Ekklesia/packages/module-ui-host/src/isolated-root.ts

/**
 * The isolated root a host mounts a browser artifact into (ADR 0040).
 *
 * Every declared browser artifact — a module's primary UI, its display UI, and a contributed
 * renderer — is mounted the same way, into its own Shadow DOM root the loader creates and owns:
 *
 * ```text
 * host container            ← the host's element; the loader never mutates it beyond this child
 * └─ <div data-ekklesia-module-ui>            ← shadow host, created and removed by the loader
 *      #shadow-root (open)
 *        ├─ <style data-ekklesia-module-ui-styles>  base rules + the artifact's declared CSS
 *        └─ <div data-ekklesia-module-ui-root>      ← the Element handed to mount()
 * ```
 *
 * Shadow DOM is chosen because it is the one mechanism in a browser that actually **enforces** the
 * rule rather than describing it: rules inside a shadow root do not apply outside it, and document
 * rules do not apply inside it. A class-name convention, a build-time prefix, or a "please scope
 * your selectors" instruction are all conventions a single mistake defeats, and the failure mode is
 * a module silently restyling the Dashboard or another module's renderer.
 *
 * It is **not** a security boundary, and nothing here should be read as one. `mode: "open"` is
 * deliberate: an installed module is trusted first-party code running in the host's own realm
 * (ADR 0022, ADR 0024), it could reach `document` directly if it wanted to, and `mode: "closed"`
 * would buy no protection while making the artifact's DOM unreachable to the host's own tests and
 * diagnostics. This is a correctness boundary for *styles*, not a sandbox.
 *
 * Custom properties inherit through a shadow boundary, so the design tokens a host installed at its
 * root (ADR 0039) are available inside every artifact with nothing passed and nothing imported.
 */

export const MODULE_UI_ISOLATION_ATTRIBUTE = "data-ekklesia-module-ui";
export const MODULE_UI_ISOLATION_STYLE_ATTRIBUTE = "data-ekklesia-module-ui-styles";
export const MODULE_UI_ISOLATION_ROOT_ATTRIBUTE = "data-ekklesia-module-ui-root";

/**
 * The rules the host always installs, before any artifact CSS.
 *
 * Both wrappers are `display: contents`, so the two elements the loader adds contribute no boxes of
 * their own and an artifact's own top-level elements lay out inside the host's container exactly as
 * they did before isolation existed. They are declared as CSS rather than inline styles precisely so
 * an artifact's own stylesheet — which the host appends *after* these — can override them when it
 * genuinely needs a box to size.
 */
const BASE_STYLESHEET = `:host{display:contents}\n[${MODULE_UI_ISOLATION_ROOT_ATTRIBUTE}]{display:contents}`;

export interface IsolatedArtifactRoot {
  /** The element handed to the artifact's `mount`. */
  readonly mountTarget: Element;
  /** The open shadow root, for a host's own tests and diagnostics. */
  readonly shadowRoot: ShadowRoot;
  /** Removes the whole isolated root — content and styles together. Idempotent. */
  dispose(): void;
}

/**
 * Builds one isolated root inside `container` and returns it.
 *
 * Nothing is attached to `container` until the shadow root, its stylesheet, and its mount target
 * have all been created, so a host whose environment cannot provide Shadow DOM gets a thrown error
 * and an untouched container rather than a half-built, unisolated mount.
 *
 * Each call creates a **fresh** root, and `dispose` removes it whole. That is what makes styles
 * deterministic in both directions: a mount installs exactly one `<style>`, an unmount removes it
 * with the element that owns it, and remounting cannot accumulate a second copy because there is
 * nothing left to accumulate onto.
 */
export function createIsolatedArtifactRoot(
  container: Element,
  styles: string | undefined,
): IsolatedArtifactRoot {
  const ownerDocument = container.ownerDocument;
  if (!ownerDocument) {
    throw new TypeError("A module UI container must belong to a document.");
  }

  const shadowHost = ownerDocument.createElement("div");
  shadowHost.setAttribute(MODULE_UI_ISOLATION_ATTRIBUTE, "");
  if (typeof shadowHost.attachShadow !== "function") {
    throw new TypeError("This environment does not support Shadow DOM.");
  }
  const shadowRoot = shadowHost.attachShadow({ mode: "open" });

  const style = ownerDocument.createElement("style");
  style.setAttribute(MODULE_UI_ISOLATION_STYLE_ATTRIBUTE, "");
  // The artifact's own CSS comes last, so it wins over the base rules above by ordinary cascade
  // order rather than by anything the host has to special-case.
  style.textContent = styles === undefined ? BASE_STYLESHEET : `${BASE_STYLESHEET}\n${styles}`;
  shadowRoot.appendChild(style);

  const mountTarget = ownerDocument.createElement("div");
  mountTarget.setAttribute(MODULE_UI_ISOLATION_ROOT_ATTRIBUTE, "");
  shadowRoot.appendChild(mountTarget);

  container.appendChild(shadowHost);

  let disposed = false;
  return {
    dispose: () => {
      if (disposed) {
        return;
      }
      disposed = true;
      shadowHost.remove();
    },
    mountTarget,
    shadowRoot,
  };
}