`@hashintel/refractive` Feature Request: Add framework-agnostic support (Vanilla HTML/CSS, SSR, and Astro)

[Stephcraft]

To increase the versatility and adoption of @hashintel/refractive, I would like to request support for non-SPA environments. Currently, the library is optimized for client-side frameworks, but providing compatibility for static site generation, Server-Side Rendering (SSR), and integration with frameworks like Astro would significantly broaden the use cases.

Goals:

• Vanilla HTML/CSS Support: Provide a way to utilize Refractive’s design patterns or components without a heavy framework dependency.
• SSR Compatibility: Ensure that components can be rendered on the server without errors (handling window or document dependencies gracefully).
• Astro Integration: Provide a path for seamless integration within Astro projects (e.g., via Web Components or Astro Islands).

Proposed Implementation Considerations:

• Web Components (Custom Elements): Creating framework-agnostic components as standard Web Components would allow them to be consumed by Vanilla HTML, Astro, and SSR environments natively.
• SSR Hooks: Ensure proper handling of hydration if/when components are used in islands or server-rendered pages.

Impact:
This will allow developers to use Refractive in content-heavy sites, landing pages, and projects that prefer the performance benefits of Astro or static HTML without sacrificing the UI/UX consistency provided by the library.

[Stephcraft]

@hashintel/refractive currently cannot be used in Astro as-is:

[astro-island] Error hydrating /node_modules/@hashintel/refractive/dist/index.js SyntaxError: The requested module '/node_modules/react/compiler-runtime.js?v=e8b1029e' does not provide an export named 'c' (at index.js:2:10)

Related issue: nuxt-modules/sanity#1277

See failing demo: https://stackblitz.com/edit/github-kzuzuduk?file=src%2Fpages%2Findex.astro

[Stephcraft]

Current workaround:

import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import path from 'path';
import { fileURLToPath } from 'url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

export default defineConfig({
  integrations: [react()],
  vite: {
    ssr: {
      // Tell Astro to let the server handle the library, preventing RSC environment contamination
      noExternal: ['@hashintel/refractive']
    },
    resolve: {
      alias: {
        // Force Vite to completely bypass node_modules for this import and look at our clean local file
        'react/compiler-runtime': path.resolve(__dirname, './src/compiler-bridge.js')
      }
    }
  }
});

// src/compiler-bridge.js
import React from 'react';

// Safely extract the React 19 memoization hook primitive
const dispatcher = React.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE?.H;

export function c(size) {
  if (!dispatcher) {
    // Fallback array allocation if evaluated outside a component context
    return new Array(size).fill(Symbol.for('react.memo_cache_sentinel'));
  }
  return dispatcher.useMemoCache(size);
}