feat(#58-66): framework adapters — next/nuxt/vue/react/svelte/sveltekit/remix/astro/angular/partytown

All adapters are framework-agnostic — no peer dependencies. Consumer brings
their own React/Vue/Angular/etc, passing the framework primitives in via a
factory or constructor. Tree-shakeable: each adapter ships independently.

- ahize/react (#61): createUseAhize(React) → useAhize hook with isReady, identity, identify, show, hide, shutdown, pageView. Reads onIdentityChange so identity stays in sync.
- ahize/vue (#60): createUseAhize(Vue) returning a Composition API style composable with reactive isReady + identity refs.
- ahize/svelte (#62 partial): createAhizeStore returns a Svelte-store-shaped subscribe contract; auto-loads on first subscriber, unloads listener after last unsubscribe.
- ahize/sveltekit (#62): setupAhize(opts, navApi) wires afterNavigate from $app/navigation for auto pageView.
- ahize/next (#58): createAhizeComponent(React, nextNav) returns an <Ahize> component; auto-fires pageView on usePathname() + useSearchParams() changes.
- ahize/nuxt (#59): createNuxtAhizePlugin(opts) — drop-in for `~/plugins/ahize.client.ts`, hooks $router.afterEach for pageView.
- ahize/remix (#63): createRemixAhize(React, remix) hook reading useLocation().
- ahize/astro (#64): mountAhize() in island scripts; listens to astro:after-swap for view-transition pageView.
- ahize/angular (#65): AhizeAngularService<T> standalone-compatible service class subscribing to Router events.
- ahize/partytown (#66): partytownForward(...providers) returns the exact list of window globals each provider needs in @builder.io/partytown's forward config; partytownConfig() wraps it as a config fragment.

Closes #58 #59 #60 #61 #62 #63 #64 #65 #66

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: productdevbook

package.json

@@ -143,6 +143,46 @@
     "./diagnostics": {
       "types": "./dist/diagnostics.d.mts",
       "default": "./dist/diagnostics.mjs"
+    },
+    "./next": {
+      "types": "./dist/adapters/next.d.mts",
+      "default": "./dist/adapters/next.mjs"
+    },
+    "./nuxt": {
+      "types": "./dist/adapters/nuxt.d.mts",
+      "default": "./dist/adapters/nuxt.mjs"
+    },
+    "./vue": {
+      "types": "./dist/adapters/vue.d.mts",
+      "default": "./dist/adapters/vue.mjs"
+    },
+    "./react": {
+      "types": "./dist/adapters/react.d.mts",
+      "default": "./dist/adapters/react.mjs"
+    },
+    "./svelte": {
+      "types": "./dist/adapters/svelte.d.mts",
+      "default": "./dist/adapters/svelte.mjs"
+    },
+    "./sveltekit": {
+      "types": "./dist/adapters/sveltekit.d.mts",
+      "default": "./dist/adapters/sveltekit.mjs"
+    },
+    "./remix": {
+      "types": "./dist/adapters/remix.d.mts",
+      "default": "./dist/adapters/remix.mjs"
+    },
+    "./astro": {
+      "types": "./dist/adapters/astro.d.mts",
+      "default": "./dist/adapters/astro.mjs"
+    },
+    "./angular": {
+      "types": "./dist/adapters/angular.d.mts",
+      "default": "./dist/adapters/angular.mjs"
+    },
+    "./partytown": {
+      "types": "./dist/adapters/partytown.d.mts",
+      "default": "./dist/adapters/partytown.mjs"
     }
   },
   "scripts": {

src/adapters/angular.ts

@@ -0,0 +1,66 @@
+// Angular v16+ standalone-compatible service factory.
+// Consumer brings their Injectable + their Router for navigation events.
+
+import type { Identity, IdentityState, LoadOptions } from "../_types.ts";
+
+interface AhizeProvider {
+  load(options: LoadOptions): Promise<void>;
+  identify(identity: Identity): Promise<void>;
+  pageView(info?: { path?: string; locale?: string }): Promise<void>;
+  shutdown(): Promise<void>;
+  isReady(): boolean;
+  getIdentity(): IdentityState;
+}
+
+interface RouterLike {
+  events: {
+    subscribe: (cb: (event: { url?: string; constructor: { name: string } }) => void) => {
+      unsubscribe(): void;
+    };
+  };
+}
+
+export class AhizeAngularService<T extends LoadOptions> {
+  private subscription: { unsubscribe(): void } | undefined;
+
+  constructor(
+    private readonly provider: AhizeProvider,
+    private readonly options: T,
+    private readonly router?: RouterLike,
+  ) {}
+
+  async init(identity?: Identity): Promise<void> {
+    if (typeof window === "undefined") return;
+    await this.provider.load(this.options);
+    if (identity) await this.provider.identify(identity);
+
+    if (this.router) {
+      this.subscription = this.router.events.subscribe((event) => {
+        if (event.constructor.name === "NavigationEnd" && event.url) {
+          void this.provider.pageView({ path: event.url });
+        }
+      });
+    }
+  }
+
+  identify(identity: Identity): Promise<void> {
+    return this.provider.identify(identity);
+  }
+
+  pageView(info?: { path?: string; locale?: string }): Promise<void> {
+    return this.provider.pageView(info);
+  }
+
+  isReady(): boolean {
+    return this.provider.isReady();
+  }
+
+  getIdentity(): IdentityState {
+    return this.provider.getIdentity();
+  }
+
+  destroy(): void {
+    this.subscription?.unsubscribe();
+    void this.provider.shutdown();
+  }
+}

src/adapters/astro.ts

@@ -0,0 +1,32 @@
+// Astro island integration — `<AhizeIsland client:idle>` boots a provider on
+// the client side. Pure framework boundary helper since Astro just renders
+// strings server-side; the actual mount runs the provider's load() in the
+// browser.
+
+import type { Identity, LoadOptions } from "../_types.ts";
+
+interface AhizeProvider {
+  load(options: LoadOptions): Promise<void>;
+  identify(identity: Identity): Promise<void>;
+  pageView(info?: { path?: string; locale?: string }): Promise<void>;
+}
+
+export interface AstroAhizeOptions<T extends LoadOptions> {
+  provider: AhizeProvider;
+  options: T;
+  identity?: Identity;
+  /** Listen on the Astro view-transitions:after-swap event for pageView. */
+  autoPageView?: boolean;
+}
+
+export async function mountAhize<T extends LoadOptions>(opts: AstroAhizeOptions<T>): Promise<void> {
+  if (typeof window === "undefined") return;
+  await opts.provider.load(opts.options);
+  if (opts.identity) await opts.provider.identify(opts.identity);
+
+  if (opts.autoPageView !== false) {
+    document.addEventListener("astro:after-swap", () => {
+      void opts.provider.pageView({ path: location.pathname + location.search });
+    });
+  }
+}

src/adapters/next.ts

@@ -0,0 +1,73 @@
+// Next.js adapters — both App Router and Pages Router.
+//
+// App Router usage:
+//   "use client";
+//   import { Ahize } from "ahize/next";
+//   import * as intercom from "ahize/intercom";
+//   <Ahize provider={intercom} options={{ appId: "..." }} />
+//
+// Pages Router usage:
+//   import { Ahize } from "ahize/next";
+//   inside _app.tsx return <Ahize ... />
+//
+// pageView() auto-fires on usePathname() change. Bring your own React.
+
+import type { Identity, IdentityState, LoadOptions } from "../_types.ts";
+
+interface AhizeProvider {
+  load(options: LoadOptions): Promise<void>;
+  identify(identity: Identity): Promise<void>;
+  pageView(info?: { path?: string; locale?: string }): Promise<void>;
+  shutdown(): Promise<void>;
+  destroy(): Promise<void>;
+  onIdentityChange(listener: (next: IdentityState, prev: IdentityState) => void): () => void;
+  isReady(): boolean;
+}
+
+interface ReactLike {
+  useEffect(cb: () => void | (() => void), deps?: readonly unknown[]): void;
+  createElement(
+    tag: string | unknown,
+    props?: Record<string, unknown>,
+    ...children: unknown[]
+  ): unknown;
+}
+
+interface NextAppRouterHooks {
+  /** next/navigation usePathname() */
+  usePathname?: () => string;
+  /** next/navigation useSearchParams() */
+  useSearchParams?: () => { toString(): string };
+}
+
+export interface NextAhizeOptions<T extends LoadOptions> {
+  provider: AhizeProvider;
+  options: T;
+  /** Optional identity to apply after load(). */
+  identity?: Identity;
+  /** Auto-fire pageView on App Router path change. */
+  autoPageView?: boolean;
+}
+
+export function createAhizeComponent(React: ReactLike, nextNav?: NextAppRouterHooks) {
+  return function Ahize<T extends LoadOptions>(props: NextAhizeOptions<T>) {
+    React.useEffect(() => {
+      let mounted = true;
+      props.provider.load(props.options).then(() => {
+        if (mounted && props.identity) void props.provider.identify(props.identity);
+      });
+      return () => {
+        mounted = false;
+      };
+    }, [props.provider, JSON.stringify(props.options)]);
+
+    const pathname = nextNav?.usePathname?.();
+    const search = nextNav?.useSearchParams?.()?.toString();
+    React.useEffect(() => {
+      if (!props.autoPageView || !pathname) return;
+      void props.provider.pageView({ path: search ? `${pathname}?${search}` : pathname });
+    }, [pathname, search, props.autoPageView]);
+
+    return null;
+  };
+}

src/adapters/nuxt.ts

@@ -0,0 +1,55 @@
+// Nuxt 3 plugin factory. Use inside `~/plugins/ahize.client.ts`:
+//
+//   import { defineNuxtPlugin } from "#app";
+//   import { useNuxtApp } from "#imports";
+//   import * as intercom from "ahize/intercom";
+//   import { createNuxtAhizePlugin } from "ahize/nuxt";
+//
+//   export default defineNuxtPlugin(createNuxtAhizePlugin({
+//     provider: intercom,
+//     options: { appId: "abc" },
+//   }));
+
+import type { Identity, IdentityState, LoadOptions } from "../_types.ts";
+
+interface AhizeProvider {
+  load(options: LoadOptions): Promise<void>;
+  identify(identity: Identity): Promise<void>;
+  shutdown(): Promise<void>;
+  pageView(info?: { path?: string; locale?: string }): Promise<void>;
+  isReady(): boolean;
+  getIdentity(): IdentityState;
+}
+
+interface NuxtPluginContext {
+  provide?: (name: string, value: unknown) => void;
+  $router?: { afterEach?: (cb: (to: { fullPath: string }) => void) => void };
+  hook?: (name: string, cb: (...args: unknown[]) => void) => void;
+}
+
+export interface NuxtAhizeOptions<T extends LoadOptions> {
+  provider: AhizeProvider;
+  options: T;
+  identity?: Identity;
+  autoPageView?: boolean;
+  /** Inject under $ahize, default true. */
+  provide?: boolean;
+}
+
+export function createNuxtAhizePlugin<T extends LoadOptions>(opts: NuxtAhizeOptions<T>) {
+  return async (nuxtApp: NuxtPluginContext) => {
+    if (typeof window === "undefined") return;
+    await opts.provider.load(opts.options);
+    if (opts.identity) void opts.provider.identify(opts.identity);
+
+    if (opts.autoPageView !== false && nuxtApp.$router?.afterEach) {
+      nuxtApp.$router.afterEach((to) => {
+        void opts.provider.pageView({ path: to.fullPath });
+      });
+    }
+
+    if (opts.provide !== false) {
+      nuxtApp.provide?.("ahize", opts.provider);
+    }
+  };
+}

src/adapters/partytown.ts

@@ -0,0 +1,61 @@
+// Partytown adapter — sugar around the existing `partytown` flag on every
+// provider's load(). Use this when you want the provider's CDN script to run
+// in a worker via Builder's Partytown library.
+//
+// Setup:
+//   1. Install @builder.io/partytown and add <PartytownScript /> to your <head>.
+//   2. Forward the provider URL via Partytown's forward config:
+//        forwardSettings([
+//          'Intercom', 'intercomSettings',
+//          'Tawk_API', 'Tawk_LoadStart',
+//          // …
+//        ])
+//   3. Load with `partytown: true`.
+
+import type { ProviderName } from "../_types.ts";
+
+const FORWARD: Partial<Record<ProviderName, readonly string[]>> = {
+  intercom: ["Intercom", "intercomSettings"],
+  crisp: ["$crisp", "CRISP_WEBSITE_ID", "CRISP_TOKEN_ID", "CRISP_RUNTIME_CONFIG"],
+  tawk: ["Tawk_API", "Tawk_LoadStart"],
+  zendesk: ["zE", "zESettings"],
+  hubspot: ["HubSpotConversations", "hsConversationsSettings", "hsConversationsOnReady", "_hsq"],
+  chatwoot: ["chatwootSDK", "$chatwoot", "chatwootSettings"],
+  livechat: ["__lc", "LiveChatWidget"],
+  drift: ["drift", "driftt"],
+  freshchat: ["fcWidget", "fcSettings"],
+  olark: ["olark"],
+  userlike: ["userlikeMessenger"],
+  helpscout: ["Beacon"],
+  smartsupp: ["smartsupp", "_smartsupp"],
+  liveagent: ["LiveAgent"],
+  gist: ["gist", "gistAppId"],
+  jivochat: [
+    "jivo_api",
+    "jivo_onLoadCallback",
+    "jivo_onOpen",
+    "jivo_onClose",
+    "jivo_onMessageSent",
+  ],
+  tidio: ["tidioChatApi"],
+  sendbird: ["__sb_widget_settings"],
+};
+
+/**
+ * Returns the list of `forwardSettings` Partytown needs for a given provider.
+ * Pass these (flat-spread across providers) into the @builder.io/partytown
+ * <PartytownScript forward={...} />.
+ */
+export function partytownForward(...providers: ProviderName[]): string[] {
+  const out = new Set<string>();
+  for (const p of providers) for (const k of FORWARD[p] ?? []) out.add(k);
+  return [...out];
+}
+
+/**
+ * Convenience: returns a PartytownConfig fragment ready to merge into the
+ * Partytown script tag's `data-config` attribute.
+ */
+export function partytownConfig(...providers: ProviderName[]): { forward: string[] } {
+  return { forward: partytownForward(...providers) };
+}