@appxiom/4react 0.1.6

package/LICENSE

@@ -0,0 +1,5 @@
+Copyright (c) 2026 BasilGregory Software Labs Private Limited
+
+All rights reserved.
+
+This software is licensed, not sold. No part of this software may be copied, modified, distributed, reverse engineered, or used except as expressly permitted by BasilGregory Software Labs Private Limited.

package/README.md

@@ -0,0 +1,252 @@
+# Appxiom React SDK (`@appxiom/4react`)
+
+`@appxiom/4react` initializes the Appxiom browser SDK and adds React-aware instrumentation for application lifecycle activity and `useRef` leak detection. It depends on `@appxiom/core`, which npm installs automatically.
+
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [TypeScript](#typescript)
+- [Automatic React Instrumentation](#automatic-react-instrumentation)
+- [Vite](#vite)
+- [SSR Frameworks](#ssr-frameworks)
+- [Production Deployment](#production-deployment)
+- [Public API](#public-api)
+- [Troubleshooting](#troubleshooting)
+
+## Requirements
+
+- React 18 or later.
+- A browser environment. The SDK uses browser APIs and must not run during server-side rendering.
+- Node.js 18 or later for package installation and builds.
+
+## Installation
+
+Install the React integration and React. `@appxiom/core` is installed automatically as a dependency.
+
+```bash
+npm install @appxiom/4react react
+```
+
+## Quick Start
+
+Initialize the SDK once from browser-only application startup code. Retain the returned `ax` instance to call its public API elsewhere in your application.
+
+### JavaScript
+
+```javascript
+import init from '@appxiom/4react';
+
+const ax = await init(
+  'YOUR_APP_KEY',
+  'YOUR_PLATFORM_KEY',
+  '1.0.0',
+  'build-001',
+);
+```
+
+### TypeScript
+
+```typescript
+import init, { type AXReact } from '@appxiom/4react';
+
+const ax: AXReact = await init(
+  'YOUR_APP_KEY',
+  'YOUR_PLATFORM_KEY',
+  '1.0.0',
+  'build-001',
+);
+```
+
+## TypeScript
+
+`@appxiom/4react` ships first-party TypeScript declarations. No separate `@types` package is required. `init(...)` returns `Promise<AXReact>`, and `AXReact` extends the public `AX` API from `@appxiom/core`.
+
+```typescript
+import init, { type AXReact } from '@appxiom/4react';
+import type { IssueSeverity } from '@appxiom/core';
+
+const ax: AXReact = await init(
+  'YOUR_APP_KEY',
+  'YOUR_PLATFORM_KEY',
+  '1.0.0',
+  'build-001',
+);
+
+const severity: IssueSeverity = 1;
+
+ax.setCustomId('user-12345');
+ax.startGoal('checkout');
+ax.logActivity('Checkout started', { cartValue: 120 });
+ax.reportCustomIssue('Payment failed', 'Gateway timed out.', severity, {
+  orderId: 'ORD-10023',
+});
+```
+
+`IssueSeverity` is limited to `0` (Minor), `1` (Major), or `2` (Fatal).
+
+## Automatic React Instrumentation
+
+After initialization, the integration adds automatic browser-side observation for React hook activity. It records lifecycle activity associated with `useEffect`, `useLayoutEffect`, `useState`, `useReducer`, `useMemo`, and `useCallback`. It also tracks `useRef` instances for leak analysis.
+
+Initialize the package before rendering the application so the instrumentation is available when components begin rendering. These integrations are installed once per page and do not require component-level wrappers or hooks.
+
+## Vite
+
+`@appxiom/4react` depends on `@appxiom/core`, which includes a WebAssembly binary. During local development, exclude both packages from Vite dependency optimization so Vite preserves the binary's source-relative URL:
+
+### JavaScript
+
+```javascript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  optimizeDeps: {
+    exclude: ['@appxiom/4react', '@appxiom/core'],
+  },
+});
+```
+
+### TypeScript
+
+```typescript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  optimizeDeps: {
+    exclude: ['@appxiom/4react', '@appxiom/core'],
+  },
+});
+```
+
+After adding the configuration, clear Vite's optimized-dependency cache and restart the development server:
+
+```bash
+rm -rf node_modules/.vite
+npm run dev -- --force
+```
+
+This setting only affects Vite's development dependency optimizer. It is safe to keep in the configuration for production builds.
+
+## SSR Frameworks
+
+For Next.js, Nuxt, SvelteKit, Remix, or any other server-rendered application, load and initialize the SDK only on the client. Do not import or initialize it from server components, route handlers, or server rendering code.
+
+### JavaScript
+
+```javascript
+if (typeof window !== 'undefined') {
+  const { default: init } = await import('@appxiom/4react');
+
+  const ax = await init(
+    'YOUR_APP_KEY',
+    'YOUR_PLATFORM_KEY',
+    '1.0.0',
+    'build-001',
+  );
+}
+```
+
+### TypeScript
+
+```typescript
+if (typeof window !== 'undefined') {
+  const { default: init } = await import('@appxiom/4react');
+
+  const ax = await init(
+    'YOUR_APP_KEY',
+    'YOUR_PLATFORM_KEY',
+    '1.0.0',
+    'build-001',
+  );
+}
+```
+
+For React client applications, initialize in the browser entry point before `createRoot(...).render(...)`. For Next.js, use a Client Component or another client-only initialization path.
+
+## Production Deployment
+
+Build and deploy the application normally. For a Vite application:
+
+```bash
+npm run build
+```
+
+The production build emits Appxiom's WebAssembly binary as an asset and rewrites its loader URL. Deploy the complete build output, including the generated `.wasm` file, without renaming or omitting assets.
+
+Your CDN or web server must return this header for WebAssembly assets:
+
+```http
+Content-Type: application/wasm
+```
+
+Ensure SPA fallback rules do not return `index.html` for `.wasm` requests. Returning HTML instead of the binary causes errors such as `expected magic word 00 61 73 6d`.
+
+## Public API
+
+### `init(appKey, platformKey, version, buildIdentifier)`
+
+Initializes the core SDK, installs the React instrumentation, and returns `Promise<AXReact>`.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `appKey` | `string` | Appxiom application key. |
+| `platformKey` | `string` | Appxiom platform key. |
+| `version` | `string` | Application version. |
+| `buildIdentifier` | `string` | Optional build or release identifier. |
+
+### Inherited `AX` methods
+
+The returned `AXReact` instance inherits these supported methods from `@appxiom/core`:
+
+- `setCustomId(customId)`: associates telemetry with an application user or account identifier.
+- `startGoal(name)`: starts a named goal.
+- `endGoal(name, properties?, value?)`: ends a named goal with optional metadata and numeric value.
+- `logActivity(name, properties?)`: records a custom activity with optional metadata.
+- `reportCustomIssue(title, description, severity, data?, stacktrace?)`: reports an application-defined issue.
+
+#### JavaScript
+
+```javascript
+ax.setCustomId('user-12345');
+ax.startGoal('checkout');
+ax.logActivity('Checkout started', { cartValue: 120 });
+ax.endGoal('checkout', { orderId: 'ORD-10023' }, 120);
+```
+
+#### TypeScript
+
+```typescript
+import type { IssueSeverity } from '@appxiom/core';
+
+const severity: IssueSeverity = 1;
+
+ax.setCustomId('user-12345');
+ax.startGoal('checkout');
+ax.logActivity('Checkout started', { cartValue: 120 });
+ax.reportCustomIssue('Payment failed', 'Gateway timed out.', severity, {
+  orderId: 'ORD-10023',
+});
+ax.endGoal('checkout', { orderId: 'ORD-10023' }, 120);
+```
+
+For the complete core API and deployment details, see the `@appxiom/core` package documentation.
+
+## Troubleshooting
+
+### Vite development reports a WASM MIME type or `expected magic word` error
+
+Add the Vite `optimizeDeps.exclude` configuration above, delete `node_modules/.vite`, and restart the development server with `--force`.
+
+### Production reports `expected magic word 00 61 73 6d`
+
+Confirm that the generated `.wasm` asset was deployed, that no SPA fallback rewrites its request to `index.html`, and that the response MIME type is `application/wasm`.
+
+### The SDK runs during server rendering
+
+Move the package import and `init(...)` call to browser-only code. Use a client component, framework client plugin, browser entry point, or a dynamic import guarded by `typeof window !== 'undefined'`.

package/core/ax-react.js

@@ -0,0 +1,18 @@
+import { AX } from '@appxiom/core';
+
+// Singleton AXReact class extending AX
+export class AXReact extends AX {
+    constructor(appKey, platformKey, version, buildIdentifier) {
+        super(appKey, platformKey, version, buildIdentifier);
+    }
+
+    async launch() {
+        await super.launch();
+        // Load runtime patches synchronously using dynamic imports
+
+        await import('../memory/ax-react-useref-leak.js');
+        await import('../lifecycle/patch.js');
+        
+        
+    }
+}

package/index.d.ts

@@ -0,0 +1,19 @@
+import type { AX } from '@appxiom/core';
+
+export class AXReact extends AX {
+  constructor(
+    appKey: string,
+    platformKey: string,
+    version: string,
+    buildIdentifier?: string,
+  );
+
+  launch(): Promise<void>;
+}
+
+export default function init(
+  appKey: string,
+  platformKey: string,
+  version: string,
+  buildIdentifier?: string,
+): Promise<AXReact>;

package/index.js

@@ -0,0 +1,9 @@
+import { AXReact } from './core/ax-react.js';
+
+export default async function init(appKey, platformKey, version, buildIdentifier) {
+    const ax = new AXReact(appKey, platformKey, version, buildIdentifier);
+    await ax.launch();
+    return ax;
+}
+
+export { AXReact };

package/lifecycle/patch.js

@@ -0,0 +1,296 @@
+// React lifecycle tracker module
+// React 18 / 19 compatible – dispatcher-based interception
+
+import React from 'react';
+import { AX } from '@appxiom/core';
+import { useRefLeakTracker } from '../memory/ax-react-useref-leak.js';
+
+function emitLifecycleEvent(name, payload = {}) {
+  try {
+    const instance = AX.instance;
+    if (!instance?.logEventActivity) return;
+    instance.logEventActivity(name, payload);
+  } catch {
+    // Never block app execution for lifecycle logging.
+  }
+}
+
+function lifecycleEventName(component, action) {
+  const label = component || 'Anonymous';
+  return `${label} :: ${action}`;
+}
+
+/* -------------------------------------------------------
+ * Component name (best-effort, non-fatal)
+ * ----------------------------------------------------- */
+function toComponentLabel(value) {
+  if (!value) return 'Anonymous';
+
+  const cleaned = String(value)
+    .replace(/^Object\./, '')
+    .replace(/:\d+:\d+$/, '')
+    .replace(/\?.*$/, '')
+    .replace(/#.*$/, '');
+
+  const fileOrSymbol = cleaned.split('/').pop() || cleaned;
+  const stem = fileOrSymbol.replace(/\.(jsx|tsx|js|ts)$/i, '');
+
+  // Prefer component-ish names (capitalized), otherwise keep best effort label.
+  if (/^[A-Z][A-Za-z0-9_$]*$/.test(stem)) {
+    return stem;
+  }
+
+  return stem || 'Anonymous';
+}
+
+function normalizeFrame(frameLine) {
+  const symbolMatch = frameLine.match(/at\s+([^\s(]+)/);
+  if (symbolMatch?.[1]) {
+    const symbol = symbolMatch[1].replace(/^Object\./, '');
+
+    // Stack frames in Vite dev can be raw URLs like
+    // http://localhost:5173/src/App.jsx:845:39
+    // Normalize these to file/component-ish names.
+    if (symbol.includes('://') || symbol.includes('/')) {
+      const cleaned = symbol
+        .replace(/^https?:\/\//, '')
+        .replace(/^[^/]+\//, '')
+        .replace(/:\d+:\d+$/, '');
+      const file = cleaned.split('/').pop() || cleaned;
+      return toComponentLabel(file);
+    }
+
+    return toComponentLabel(symbol);
+  }
+
+  const pathMatch = frameLine.match(/\((.*):(\d+):(\d+)\)$/) || frameLine.match(/at\s+(.*):(\d+):(\d+)$/);
+  if (pathMatch?.[1]) {
+    const rawPath = pathMatch[1];
+    const parts = rawPath.split('/');
+    return toComponentLabel(parts[parts.length - 1] || rawPath);
+  }
+
+  return 'Anonymous';
+}
+
+function getBestFrame(stack) {
+  if (!stack) return null;
+
+  const lines = stack
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  const ignoredMarkers = [
+    'ax-react/lifecycle/patch.js',
+    'getComponentName',
+    'getBestFrame',
+    'normalizeFrame',
+    'wrapHook',
+    'wrapped',
+    'emitLifecycleEvent',
+  ];
+
+  const candidateLines = lines.filter((line) => {
+    if (!line.startsWith('at ')) return false;
+    if (ignoredMarkers.some((marker) => line.includes(marker))) return false;
+    return true;
+  });
+
+  const appFrame = candidateLines.find((line) =>
+    line.includes('/src/') || line.includes('.jsx') || line.includes('.tsx'),
+  );
+
+  return appFrame || candidateLines[0] || null;
+}
+
+function getComponentName() {
+  const internals = React.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE;
+
+  try {
+    const reactStack = internals?.getCurrentStack?.();
+    const frame = getBestFrame(reactStack);
+    if (frame) return normalizeFrame(frame);
+  } catch {
+    // Fallback below.
+  }
+
+  try {
+    const stack = new Error().stack;
+    const frame = getBestFrame(stack);
+    if (frame) return normalizeFrame(frame);
+  } catch {
+    // Fall through.
+  }
+
+  return 'Anonymous';
+}
+
+/* -------------------------------------------------------
+ * Hook wrapper utility
+ * ----------------------------------------------------- */
+function wrapHook(dispatcher, name, wrapper) {
+  if (!dispatcher[name] || dispatcher[name].__AX_WRAPPED__) return;
+
+  const original = dispatcher[name];
+
+  function wrapped(...args) {
+    return wrapper(original, this, args);
+  }
+
+  wrapped.__AX_WRAPPED__ = true;
+  wrapped.__AX_ORIGINAL__ = original;
+  dispatcher[name] = wrapped;
+}
+
+/* -------------------------------------------------------
+ * Dispatcher patch (THIS is the critical layer)
+ * ----------------------------------------------------- */
+function patchDispatcher() {
+  const internals =
+    React.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE;
+
+  if (internals.__AX_DISPATCHER_PATCHED__) return;
+  internals.__AX_DISPATCHER_PATCHED__ = true;
+
+  let currentDispatcher = internals.H;
+
+  Object.defineProperty(internals, 'H', {
+    configurable: true,
+    get() {
+      const dispatcher = currentDispatcher;
+
+      if (!dispatcher || dispatcher.__AX_PATCHED__) {
+        return dispatcher;
+      }
+
+      dispatcher.__AX_PATCHED__ = true;
+
+      /* ---------------- useRef ---------------- */
+      wrapHook(dispatcher, 'useRef', (original, ctx, args) => {
+        const component = getComponentName();
+        const ref = original.apply(ctx, args);
+
+        try {
+          useRefLeakTracker.trackRef(ref, {
+            component,
+            createdAt: performance.now(),
+          });
+          emitLifecycleEvent(lifecycleEventName(component, 'React useRef Created'), {
+            component,
+            hasInitialValue: args[0] !== undefined,
+          });
+        } catch {
+        }
+
+        return ref;
+      });
+
+      /* ---------------- useEffect ---------------- */
+      wrapHook(dispatcher, 'useEffect', (original, ctx, args) => {
+        const component = getComponentName();
+        const effect = args[0];
+
+        args[0] = function wrappedEffect() {
+          emitLifecycleEvent(lifecycleEventName(component, 'React useEffect Mounted'), { component });
+          const cleanup = effect();
+
+          if (typeof cleanup === 'function') {
+            return function wrappedCleanup() {
+              emitLifecycleEvent(lifecycleEventName(component, 'React useEffect Cleanup'), { component });
+              return cleanup();
+            };
+          }
+          return cleanup;
+        };
+
+        return original.apply(ctx, args);
+      });
+
+      /* ---------------- useLayoutEffect ---------------- */
+      wrapHook(dispatcher, 'useLayoutEffect', (original, ctx, args) => {
+        const component = getComponentName();
+        const effect = args[0];
+
+        args[0] = function wrappedLayoutEffect() {
+          emitLifecycleEvent(lifecycleEventName(component, 'React useLayoutEffect Mounted'), { component });
+          const cleanup = effect();
+
+          if (typeof cleanup === 'function') {
+            return function wrappedLayoutCleanup() {
+              emitLifecycleEvent(lifecycleEventName(component, 'React useLayoutEffect Cleanup'), { component });
+              return cleanup();
+            };
+          }
+
+          return cleanup;
+        };
+
+        return original.apply(ctx, args);
+      });
+
+      /* ---------------- useState ---------------- */
+      wrapHook(dispatcher, 'useState', (original, ctx, args) => {
+        const component = getComponentName();
+        const [state, setState] = original.apply(ctx, args);
+
+        const wrappedSetState = (value) => {
+          emitLifecycleEvent(lifecycleEventName(component, 'React useState Updated'), {
+            component,
+            updateType: typeof value,
+          });
+          return setState(value);
+        };
+
+        return [state, wrappedSetState];
+      });
+
+      /* ---------------- useReducer ---------------- */
+      wrapHook(dispatcher, 'useReducer', (original, ctx, args) => {
+        const component = getComponentName();
+
+        const [state, dispatch] = original.apply(ctx, args);
+
+        const wrappedDispatch = (action) => {
+          emitLifecycleEvent(lifecycleEventName(component, 'React useReducer Dispatched'), {
+            component,
+            actionType: typeof action,
+          });
+          return dispatch(action);
+        };
+
+        return [state, wrappedDispatch];
+      });
+
+      /* ---------------- useMemo ---------------- */
+      wrapHook(dispatcher, 'useMemo', (original, ctx, args) => {
+        const component = getComponentName();
+        emitLifecycleEvent(lifecycleEventName(component, 'React useMemo Evaluated'), { component });
+        return original.apply(ctx, args);
+      });
+
+      /* ---------------- useCallback ---------------- */
+      wrapHook(dispatcher, 'useCallback', (original, ctx, args) => {
+        const component = getComponentName();
+        emitLifecycleEvent(lifecycleEventName(component, 'React useCallback Registered'), { component });
+        return original.apply(ctx, args);
+      });
+
+      return dispatcher;
+    },
+    set(v) {
+      currentDispatcher = v;
+    },
+  });
+}
+
+/* -------------------------------------------------------
+ * Public init API
+ * ----------------------------------------------------- */
+if (!React.__AX_REACT_PATCHED__) {
+
+  React.__AX_REACT_PATCHED__ = true;
+
+  patchDispatcher();
+
+}

package/memory/ax-react-useref-leak.js

@@ -0,0 +1,15 @@
+import { LeakTracker } from '@appxiom/core';
+
+class UseRefLeakTracker extends LeakTracker {
+  // Constructor
+  constructor() {
+    super(2); // useRef leak type
+  }
+
+  trackRef(ref, metadata = {}) {
+    if (!ref) return;
+    this.trackInstance(ref, metadata);
+  }
+}
+
+export const useRefLeakTracker = new UseRefLeakTracker();

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@appxiom/4react",
+  "description": "React integration layer for Appxiom Web Observability SDK",
+  "license": "UNLICENSED",
+  "author": "BasilGregory Software Labs Private Limited",
+  "homepage": "https://appxiom.io",
+  "version": "0.1.6",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "core/",
+    "lifecycle/",
+    "memory/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check:files": "test -f index.js && test -f core/ax-react.js && test -f lifecycle/patch.js && test -f memory/ax-react-useref-leak.js",
+    "check:types": "tsc --project test/types/tsconfig.json --noEmit",
+    "pack:dry-run": "npm pack --dry-run",
+    "prepublishOnly": "npm run check:files && npm run pack:dry-run"
+  },
+  "sideEffects": true,
+  "main": "index.js",
+  "module": "index.js",
+  "dependencies": {
+    "@appxiom/core": "^0.1.6"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "keywords": [
+    "appxiom",
+    "react",
+    "observability",
+    "monitoring",
+    "analytics",
+    "rum",
+    "performance"
+  ],
+  "type": "module"
+}