Client SDK layering violation: web-platform layer depends on React

[EisenbergEffect]

Summary

The client SDK’s web-platform layer (e.g., UIResourceRendererWC, HTMLResourceRenderer, UIResourceRenderer, etc.) currently depends on React. This inverts the expected dependency direction (a layering/dependency-rule violation) and, in some cases, creates circular dependencies. Frameworks should depend on the platform layer, not the other way around.

Why this matters

• Adoption friction: Teams wanting to use the web-platform capabilities without a JS framework are forced to add React (often blocked by governance or bundle policy).
• Unnecessary coupling: Platform primitives become framework-specific, limiting use in non-React apps and Web Components–first stacks.
• Maintainability risk: Inverted arrows make it harder to evolve the platform or add first-class adapters for other frameworks (Angular, Vue, Svelte, etc.).

Current vs desired architecture

graph TD
  subgraph Current
    W["@mcp-ui/client (web platform: WC + HTML renderers)"] --> R["react / react-dom"]
    R -->|in some places| W
  end

Loading

graph TD
  subgraph Desired
    C["@mcp-ui/core (protocol, types, transport)"]
    W["@mcp-ui/web (platform: WC + HTML renderers)"]
    RA["@mcp-ui/react (framework adapter)"]
    VA["@mcp-ui/vue (framework adapter)"]
    AA["@mcp-ui/angular (framework adapter)"]

    W --> C
    RA --> W
    VA --> W
    AA --> W
  end

Loading

Arrow A --> B means “A depends on B.”

Proposal

1. Package split & boundaries
   • @mcp-ui/core: protocol, types, transport, utilities. No DOM / framework deps.
   • @mcp-ui/web: DOM/Web Components/HTML renderers built on standard web APIs. No framework deps.
   • @mcp-ui/react (and @mcp-ui/<framework>): thin adapters wrapping @mcp-ui/web for ergonomics within each framework.
2. API surface
   • Expose platform primitives (custom elements, imperative renderers) from @mcp-ui/web.
   • React/Vue/Angular packages provide idiomatic bindings that compose those primitives.
3. Enforcement
   • Add dependency rules to prevent @mcp-ui/web importing from any framework packages.
4. Migration path
   • Keep existing React entry points but re-implement them as wrappers around @mcp-ui/web.
   • Deprecate any platform modules that import React; provide codemods or upgrade notes.
   • Ship under a minor version with deprecation warnings, remove in next major.

Acceptance criteria

• Installing @mcp-ui/web does not install or require React (or any framework).
• Importing any web-platform renderer works in a framework-free app.
• Framework adapters depend on @mcp-ui/web, not vice-versa.
• No circular dependencies across core, web, and framework adapters.
• Lint/build checks enforce the layering rule.

Additional context

• This aligns with the established good architectural practice that source code dependencies point inward (frameworks → platform → core), not outward.