@plasius/error 1.0.5 → 1.0.6

package/CHANGELOG.md

@@ -20,6 +20,26 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
 - **Security**
   - (placeholder)
 
+## [1.0.6] - 2026-03-01
+
+- **Added**
+  - Error-boundary analytics integration hooks (`analyticsClient`, `errorContext`, `onErrorCaptured`).
+  - Exported `ErrorBoundaryReport` contract for forwarding boundary crashes to analytics clients.
+  - `installGlobalCrashReporter` for browser and process-level crash capture outside React boundaries.
+
+- **Changed**
+  - `ErrorBoundary` now forwards captured errors to an injected analytics-compatible client.
+  - Corrected render behavior so `fallback` is displayed only after an error is captured.
+
+- **Fixed**
+  - Enforced CommonJS runtime compatibility for dual-build output by generating and validating `dist-cjs/package.json` (`type: commonjs`) during build and package verification.
+  - Added tests covering analytics forwarding and no-error render behavior with fallback props.
+  - Added tests validating global crash capture (`window.error`, `window.unhandledrejection`, process exception/rejection handlers).
+  - Fixed CommonJS runtime compatibility by marking `dist-cjs/` output as `type: commonjs`, preventing `exports is not defined in ES module scope` when required by Node consumers.
+
+- **Security**
+  - Boundary reporting payload is constrained to essential debugging fields and delegated to analytics sanitization policies.
+
 ## [1.0.5] - 2026-02-28
 
 - **Added**
@@ -76,7 +96,7 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
 
 ---
 
-[Unreleased]: https://github.com/Plasius-LTD/error/compare/v1.0.5...HEAD
+[Unreleased]: https://github.com/Plasius-LTD/error/compare/v1.0.6...HEAD
 
 ## [1.0.0] - 2026-02-11
 
@@ -94,3 +114,4 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
 [1.0.3]: https://github.com/Plasius-LTD/error/releases/tag/v1.0.3
 [1.0.4]: https://github.com/Plasius-LTD/error/releases/tag/v1.0.4
 [1.0.5]: https://github.com/Plasius-LTD/error/releases/tag/v1.0.5
+[1.0.6]: https://github.com/Plasius-LTD/error/releases/tag/v1.0.6

package/README.md

@@ -17,12 +17,65 @@ Public package containing shared error boundary and error-handling utilities for
 npm install @plasius/error
 ```
 
+## Module formats
+
+`@plasius/error` ships dual module outputs:
+
+- ESM via `exports.import` (`dist/index.js`)
+- CJS via `exports.require` (`dist-cjs/index.js`, explicitly marked CommonJS)
+
 ## Usage
 
 ```ts
 import { ErrorBoundary } from "@plasius/error";
 ```
 
+### Error reporting with `@plasius/analytics`
+
+`ErrorBoundary` can forward captured errors into an analytics-compatible client:
+
+```tsx
+import { ErrorBoundary } from "@plasius/error";
+import { createFrontendAnalyticsClient } from "@plasius/analytics";
+
+const analytics = createFrontendAnalyticsClient({
+  source: "sharedcomponents",
+  endpoint: "https://analytics.example.com/collect",
+});
+
+<ErrorBoundary
+  name="CheckoutBoundary"
+  analyticsClient={analytics}
+  errorContext={{ feature: "checkout" }}
+>
+  <CheckoutPage />
+</ErrorBoundary>;
+```
+
+The boundary forwards a minimal report (`boundary`, `error`, component stack, severity, context), and `@plasius/analytics` handles sanitization and secure transport rules.
+
+### Whole application crash capture
+
+`installGlobalCrashReporter` captures crashes outside React boundaries where available:
+- browser: `window.error`, `window.unhandledrejection`
+- server/runtime: `process.uncaughtException`, `process.unhandledRejection`
+
+```ts
+import {
+  ErrorBoundary,
+  installGlobalCrashReporter,
+} from "@plasius/error";
+
+const crashReporter = installGlobalCrashReporter({
+  boundaryName: "GlobalApplication",
+  analyticsClient: analytics,
+  errorContext: { app: "frontend" },
+});
+
+// later during teardown
+crashReporter.dispose();
+```
+
 ## Development
 
 ```bash

package/dist/errorboundary.d.ts

@@ -1,8 +1,25 @@
 import React from "react";
+export type ErrorBoundarySeverity = "error" | "fatal";
+export interface ErrorBoundaryReport {
+    boundary: string;
+    error: unknown;
+    componentStack?: string;
+    handled?: boolean;
+    severity?: ErrorBoundarySeverity;
+    context?: Record<string, unknown>;
+    timestamp?: number;
+}
+export interface ErrorBoundaryAnalyticsClient {
+    reportError: (report: ErrorBoundaryReport) => void;
+}
 interface ErrorBoundaryProps {
     name: string;
     children: React.ReactNode;
     fallback?: React.ReactNode;
+    analyticsClient?: ErrorBoundaryAnalyticsClient;
+    errorContext?: Record<string, unknown>;
+    severity?: ErrorBoundarySeverity;
+    onErrorCaptured?: (report: ErrorBoundaryReport, info: React.ErrorInfo) => void;
 }
 interface ErrorBoundaryState {
     hasError: boolean;
@@ -12,6 +29,7 @@ export declare class ErrorBoundary extends React.Component<ErrorBoundaryProps, E
     static getDerivedStateFromError(): {
         hasError: boolean;
     };
+    private buildErrorReport;
     componentDidCatch(error: Error, info: React.ErrorInfo): void;
     render(): string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element | null | undefined;
 }

package/dist/errorboundary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errorboundary.d.ts","sourceRoot":"","sources":["../src/errorboundary.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,UAAU,kBAAkB;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B;AAED,UAAU,kBAAkB;IAC1B,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,qBAAa,aAAc,SAAQ,KAAK,CAAC,SAAS,CAChD,kBAAkB,EAClB,kBAAkB,CACnB;gBACa,KAAK,EAAE,kBAAkB;IAKrC,MAAM,CAAC,wBAAwB;;;IAItB,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS;IAIrD,MAAM;CAQhB;AAED,eAAe,aAAa,CAAC"}
+{"version":3,"file":"errorboundary.d.ts","sourceRoot":"","sources":["../src/errorboundary.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,OAAO,CAAC;AAEtD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,4BAA4B;IAC3C,WAAW,EAAE,CAAC,MAAM,EAAE,mBAAmB,KAAK,IAAI,CAAC;CACpD;AAED,UAAU,kBAAkB;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,eAAe,CAAC,EAAE,4BAA4B,CAAC;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,mBAAmB,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS,KAAK,IAAI,CAAC;CAChF;AAED,UAAU,kBAAkB;IAC1B,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,qBAAa,aAAc,SAAQ,KAAK,CAAC,SAAS,CAChD,kBAAkB,EAClB,kBAAkB,CACnB;gBACa,KAAK,EAAE,kBAAkB;IAKrC,MAAM,CAAC,wBAAwB;;;IAI/B,OAAO,CAAC,gBAAgB;IAYf,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS;IAOrD,MAAM;CAShB;AAED,eAAe,aAAa,CAAC"}

package/dist/errorboundary.js

@@ -8,14 +8,28 @@ export class ErrorBoundary extends React.Component {
     static getDerivedStateFromError() {
         return { hasError: true };
     }
+    buildErrorReport(error, info) {
+        return {
+            boundary: this.props.name,
+            error,
+            componentStack: info.componentStack ?? undefined,
+            handled: true,
+            severity: this.props.severity ?? "error",
+            context: this.props.errorContext,
+            timestamp: Date.now(),
+        };
+    }
     componentDidCatch(error, info) {
+        const report = this.buildErrorReport(error, info);
+        this.props.analyticsClient?.reportError(report);
+        this.props.onErrorCaptured?.(report, info);
         console.error(`Error caught by ${this.props.name}:`, error, info);
     }
     render() {
         if (this.state.hasError) {
             return (this.props.fallback ?? _jsxs("h2", { children: [this.props.name, " encountered an error."] }));
         }
-        return this.props.fallback ?? this.props.children;
+        return this.props.children;
     }
 }
 export default ErrorBoundary;

package/dist/globalcrash.d.ts

@@ -0,0 +1,17 @@
+import type { ErrorBoundaryAnalyticsClient, ErrorBoundaryReport, ErrorBoundarySeverity } from "./errorboundary.js";
+export type GlobalCrashOrigin = "window.error" | "window.unhandledrejection" | "process.uncaughtException" | "process.unhandledRejection";
+export interface GlobalCrashReporterOptions {
+    boundaryName?: string;
+    analyticsClient?: ErrorBoundaryAnalyticsClient;
+    errorContext?: Record<string, unknown>;
+    severity?: ErrorBoundarySeverity;
+    onErrorCaptured?: (report: ErrorBoundaryReport, origin: GlobalCrashOrigin) => void;
+    captureBrowserErrors?: boolean;
+    captureBrowserRejections?: boolean;
+    captureProcessErrors?: boolean;
+}
+export interface GlobalCrashReporterController {
+    dispose: () => void;
+}
+export declare function installGlobalCrashReporter(options?: GlobalCrashReporterOptions): GlobalCrashReporterController;
+//# sourceMappingURL=globalcrash.d.ts.map

package/dist/globalcrash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"globalcrash.d.ts","sourceRoot":"","sources":["../src/globalcrash.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,4BAA4B,EAC5B,mBAAmB,EACnB,qBAAqB,EACtB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,MAAM,iBAAiB,GACzB,cAAc,GACd,2BAA2B,GAC3B,2BAA2B,GAC3B,4BAA4B,CAAC;AAEjC,MAAM,WAAW,0BAA0B;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,4BAA4B,CAAC;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,mBAAmB,EAAE,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACnF,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AA0FD,wBAAgB,0BAA0B,CACxC,OAAO,GAAE,0BAA+B,GACvC,6BAA6B,CAgG/B"}

package/dist/globalcrash.js

@@ -0,0 +1,134 @@
+function isBrowserEventTarget(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.addEventListener === "function" &&
+        typeof candidate.removeEventListener === "function");
+}
+function isNodeProcessTarget(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const candidate = value;
+    return typeof candidate.on === "function" && typeof candidate.off === "function";
+}
+function normalizeError(error) {
+    if (error instanceof Error) {
+        return error;
+    }
+    if (typeof error === "string") {
+        return new Error(error);
+    }
+    if (error === null || error === undefined) {
+        return new Error("Unknown crash reason");
+    }
+    try {
+        return new Error(JSON.stringify(error));
+    }
+    catch {
+        return new Error(String(error));
+    }
+}
+function extractErrorEventContext(event) {
+    const details = {};
+    if (!event || typeof event !== "object") {
+        return {
+            error: event,
+            details,
+        };
+    }
+    const record = event;
+    if (typeof record.message === "string" && record.message.trim()) {
+        details.message = record.message;
+    }
+    if (typeof record.filename === "string" && record.filename.trim()) {
+        details.filename = record.filename;
+    }
+    if (typeof record.lineno === "number") {
+        details.lineno = record.lineno;
+    }
+    if (typeof record.colno === "number") {
+        details.colno = record.colno;
+    }
+    return {
+        error: record.error ?? record.reason ?? record,
+        details,
+    };
+}
+export function installGlobalCrashReporter(options = {}) {
+    const boundaryName = options.boundaryName?.trim() || "GlobalApplication";
+    const severity = options.severity ?? "fatal";
+    const baseContext = {
+        ...(options.errorContext ?? {}),
+    };
+    const disposers = [];
+    const emitReport = (origin, rawError, contextDetails = {}) => {
+        const error = normalizeError(rawError);
+        const report = {
+            boundary: boundaryName,
+            error,
+            handled: false,
+            severity,
+            context: {
+                ...baseContext,
+                crashOrigin: origin,
+                ...contextDetails,
+            },
+            timestamp: Date.now(),
+        };
+        options.analyticsClient?.reportError(report);
+        options.onErrorCaptured?.(report, origin);
+    };
+    const browserGlobal = typeof window !== "undefined" ? window : globalThis.window;
+    if (isBrowserEventTarget(browserGlobal)) {
+        if (options.captureBrowserErrors !== false) {
+            const handleBrowserError = (event) => {
+                const { error, details } = extractErrorEventContext(event);
+                emitReport("window.error", error, details);
+            };
+            browserGlobal.addEventListener("error", handleBrowserError);
+            disposers.push(() => {
+                browserGlobal.removeEventListener("error", handleBrowserError);
+            });
+        }
+        if (options.captureBrowserRejections !== false) {
+            const handleUnhandledRejection = (event) => {
+                const { error, details } = extractErrorEventContext(event);
+                emitReport("window.unhandledrejection", error, details);
+            };
+            browserGlobal.addEventListener("unhandledrejection", handleUnhandledRejection);
+            disposers.push(() => {
+                browserGlobal.removeEventListener("unhandledrejection", handleUnhandledRejection);
+            });
+        }
+    }
+    const processGlobal = globalThis.process;
+    if (options.captureProcessErrors !== false && isNodeProcessTarget(processGlobal)) {
+        const handleUncaughtException = (error) => {
+            emitReport("process.uncaughtException", error);
+        };
+        const handleUnhandledRejection = (reason) => {
+            emitReport("process.unhandledRejection", reason);
+        };
+        processGlobal.on("uncaughtException", handleUncaughtException);
+        processGlobal.on("unhandledRejection", handleUnhandledRejection);
+        disposers.push(() => {
+            processGlobal.off("uncaughtException", handleUncaughtException);
+            processGlobal.off("unhandledRejection", handleUnhandledRejection);
+        });
+    }
+    let disposed = false;
+    return {
+        dispose() {
+            if (disposed) {
+                return;
+            }
+            disposed = true;
+            for (const dispose of disposers) {
+                dispose();
+            }
+            disposers.length = 0;
+        },
+    };
+}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./errorboundary.js";
+export * from "./globalcrash.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -1 +1,2 @@
 export * from "./errorboundary.js";
+export * from "./globalcrash.js";

package/dist-cjs/errorboundary.d.ts

@@ -1,8 +1,25 @@
 import React from "react";
+export type ErrorBoundarySeverity = "error" | "fatal";
+export interface ErrorBoundaryReport {
+    boundary: string;
+    error: unknown;
+    componentStack?: string;
+    handled?: boolean;
+    severity?: ErrorBoundarySeverity;
+    context?: Record<string, unknown>;
+    timestamp?: number;
+}
+export interface ErrorBoundaryAnalyticsClient {
+    reportError: (report: ErrorBoundaryReport) => void;
+}
 interface ErrorBoundaryProps {
     name: string;
     children: React.ReactNode;
     fallback?: React.ReactNode;
+    analyticsClient?: ErrorBoundaryAnalyticsClient;
+    errorContext?: Record<string, unknown>;
+    severity?: ErrorBoundarySeverity;
+    onErrorCaptured?: (report: ErrorBoundaryReport, info: React.ErrorInfo) => void;
 }
 interface ErrorBoundaryState {
     hasError: boolean;
@@ -12,6 +29,7 @@ export declare class ErrorBoundary extends React.Component<ErrorBoundaryProps, E
     static getDerivedStateFromError(): {
         hasError: boolean;
     };
+    private buildErrorReport;
     componentDidCatch(error: Error, info: React.ErrorInfo): void;
     render(): string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element | null | undefined;
 }

package/dist-cjs/errorboundary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errorboundary.d.ts","sourceRoot":"","sources":["../src/errorboundary.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,UAAU,kBAAkB;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B;AAED,UAAU,kBAAkB;IAC1B,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,qBAAa,aAAc,SAAQ,KAAK,CAAC,SAAS,CAChD,kBAAkB,EAClB,kBAAkB,CACnB;gBACa,KAAK,EAAE,kBAAkB;IAKrC,MAAM,CAAC,wBAAwB;;;IAItB,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS;IAIrD,MAAM;CAQhB;AAED,eAAe,aAAa,CAAC"}
+{"version":3,"file":"errorboundary.d.ts","sourceRoot":"","sources":["../src/errorboundary.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,OAAO,CAAC;AAEtD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,4BAA4B;IAC3C,WAAW,EAAE,CAAC,MAAM,EAAE,mBAAmB,KAAK,IAAI,CAAC;CACpD;AAED,UAAU,kBAAkB;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,eAAe,CAAC,EAAE,4BAA4B,CAAC;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,mBAAmB,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS,KAAK,IAAI,CAAC;CAChF;AAED,UAAU,kBAAkB;IAC1B,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,qBAAa,aAAc,SAAQ,KAAK,CAAC,SAAS,CAChD,kBAAkB,EAClB,kBAAkB,CACnB;gBACa,KAAK,EAAE,kBAAkB;IAKrC,MAAM,CAAC,wBAAwB;;;IAI/B,OAAO,CAAC,gBAAgB;IAYf,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS;IAOrD,MAAM;CAShB;AAED,eAAe,aAAa,CAAC"}

package/dist-cjs/errorboundary.js

@@ -14,14 +14,28 @@ class ErrorBoundary extends react_1.default.Component {
     static getDerivedStateFromError() {
         return { hasError: true };
     }
+    buildErrorReport(error, info) {
+        return {
+            boundary: this.props.name,
+            error,
+            componentStack: info.componentStack ?? undefined,
+            handled: true,
+            severity: this.props.severity ?? "error",
+            context: this.props.errorContext,
+            timestamp: Date.now(),
+        };
+    }
     componentDidCatch(error, info) {
+        const report = this.buildErrorReport(error, info);
+        this.props.analyticsClient?.reportError(report);
+        this.props.onErrorCaptured?.(report, info);
         console.error(`Error caught by ${this.props.name}:`, error, info);
     }
     render() {
         if (this.state.hasError) {
             return (this.props.fallback ?? (0, jsx_runtime_1.jsxs)("h2", { children: [this.props.name, " encountered an error."] }));
         }
-        return this.props.fallback ?? this.props.children;
+        return this.props.children;
     }
 }
 exports.ErrorBoundary = ErrorBoundary;

package/dist-cjs/globalcrash.d.ts

@@ -0,0 +1,17 @@
+import type { ErrorBoundaryAnalyticsClient, ErrorBoundaryReport, ErrorBoundarySeverity } from "./errorboundary.js";
+export type GlobalCrashOrigin = "window.error" | "window.unhandledrejection" | "process.uncaughtException" | "process.unhandledRejection";
+export interface GlobalCrashReporterOptions {
+    boundaryName?: string;
+    analyticsClient?: ErrorBoundaryAnalyticsClient;
+    errorContext?: Record<string, unknown>;
+    severity?: ErrorBoundarySeverity;
+    onErrorCaptured?: (report: ErrorBoundaryReport, origin: GlobalCrashOrigin) => void;
+    captureBrowserErrors?: boolean;
+    captureBrowserRejections?: boolean;
+    captureProcessErrors?: boolean;
+}
+export interface GlobalCrashReporterController {
+    dispose: () => void;
+}
+export declare function installGlobalCrashReporter(options?: GlobalCrashReporterOptions): GlobalCrashReporterController;
+//# sourceMappingURL=globalcrash.d.ts.map

package/dist-cjs/globalcrash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"globalcrash.d.ts","sourceRoot":"","sources":["../src/globalcrash.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,4BAA4B,EAC5B,mBAAmB,EACnB,qBAAqB,EACtB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,MAAM,iBAAiB,GACzB,cAAc,GACd,2BAA2B,GAC3B,2BAA2B,GAC3B,4BAA4B,CAAC;AAEjC,MAAM,WAAW,0BAA0B;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,4BAA4B,CAAC;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,mBAAmB,EAAE,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACnF,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AA0FD,wBAAgB,0BAA0B,CACxC,OAAO,GAAE,0BAA+B,GACvC,6BAA6B,CAgG/B"}

package/dist-cjs/globalcrash.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installGlobalCrashReporter = installGlobalCrashReporter;
+function isBrowserEventTarget(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.addEventListener === "function" &&
+        typeof candidate.removeEventListener === "function");
+}
+function isNodeProcessTarget(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const candidate = value;
+    return typeof candidate.on === "function" && typeof candidate.off === "function";
+}
+function normalizeError(error) {
+    if (error instanceof Error) {
+        return error;
+    }
+    if (typeof error === "string") {
+        return new Error(error);
+    }
+    if (error === null || error === undefined) {
+        return new Error("Unknown crash reason");
+    }
+    try {
+        return new Error(JSON.stringify(error));
+    }
+    catch {
+        return new Error(String(error));
+    }
+}
+function extractErrorEventContext(event) {
+    const details = {};
+    if (!event || typeof event !== "object") {
+        return {
+            error: event,
+            details,
+        };
+    }
+    const record = event;
+    if (typeof record.message === "string" && record.message.trim()) {
+        details.message = record.message;
+    }
+    if (typeof record.filename === "string" && record.filename.trim()) {
+        details.filename = record.filename;
+    }
+    if (typeof record.lineno === "number") {
+        details.lineno = record.lineno;
+    }
+    if (typeof record.colno === "number") {
+        details.colno = record.colno;
+    }
+    return {
+        error: record.error ?? record.reason ?? record,
+        details,
+    };
+}
+function installGlobalCrashReporter(options = {}) {
+    const boundaryName = options.boundaryName?.trim() || "GlobalApplication";
+    const severity = options.severity ?? "fatal";
+    const baseContext = {
+        ...(options.errorContext ?? {}),
+    };
+    const disposers = [];
+    const emitReport = (origin, rawError, contextDetails = {}) => {
+        const error = normalizeError(rawError);
+        const report = {
+            boundary: boundaryName,
+            error,
+            handled: false,
+            severity,
+            context: {
+                ...baseContext,
+                crashOrigin: origin,
+                ...contextDetails,
+            },
+            timestamp: Date.now(),
+        };
+        options.analyticsClient?.reportError(report);
+        options.onErrorCaptured?.(report, origin);
+    };
+    const browserGlobal = typeof window !== "undefined" ? window : globalThis.window;
+    if (isBrowserEventTarget(browserGlobal)) {
+        if (options.captureBrowserErrors !== false) {
+            const handleBrowserError = (event) => {
+                const { error, details } = extractErrorEventContext(event);
+                emitReport("window.error", error, details);
+            };
+            browserGlobal.addEventListener("error", handleBrowserError);
+            disposers.push(() => {
+                browserGlobal.removeEventListener("error", handleBrowserError);
+            });
+        }
+        if (options.captureBrowserRejections !== false) {
+            const handleUnhandledRejection = (event) => {
+                const { error, details } = extractErrorEventContext(event);
+                emitReport("window.unhandledrejection", error, details);
+            };
+            browserGlobal.addEventListener("unhandledrejection", handleUnhandledRejection);
+            disposers.push(() => {
+                browserGlobal.removeEventListener("unhandledrejection", handleUnhandledRejection);
+            });
+        }
+    }
+    const processGlobal = globalThis.process;
+    if (options.captureProcessErrors !== false && isNodeProcessTarget(processGlobal)) {
+        const handleUncaughtException = (error) => {
+            emitReport("process.uncaughtException", error);
+        };
+        const handleUnhandledRejection = (reason) => {
+            emitReport("process.unhandledRejection", reason);
+        };
+        processGlobal.on("uncaughtException", handleUncaughtException);
+        processGlobal.on("unhandledRejection", handleUnhandledRejection);
+        disposers.push(() => {
+            processGlobal.off("uncaughtException", handleUncaughtException);
+            processGlobal.off("unhandledRejection", handleUnhandledRejection);
+        });
+    }
+    let disposed = false;
+    return {
+        dispose() {
+            if (disposed) {
+                return;
+            }
+            disposed = true;
+            for (const dispose of disposers) {
+                dispose();
+            }
+            disposers.length = 0;
+        },
+    };
+}

package/dist-cjs/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./errorboundary.js";
+export * from "./globalcrash.js";
 //# sourceMappingURL=index.d.ts.map

package/dist-cjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC"}

package/dist-cjs/index.js

@@ -15,3 +15,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./errorboundary.js"), exports);
+__exportStar(require("./globalcrash.js"), exports);

package/dist-cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/docs/adrs/adr-0003-dual-esm-cjs-runtime-compatibility.md

@@ -0,0 +1,34 @@
+# ADR-0003: Dual ESM and CJS Runtime Compatibility
+
+- Date: 2026-03-01
+- Status: Accepted
+
+## Context
+
+`@plasius/error` is published with `type: module` and dual exports for ESM and CJS
+consumers. The CJS build artifacts are emitted under `dist-cjs/*.js`, and Node
+can interpret those files as ESM unless that directory is explicitly marked as
+CommonJS.
+
+This caused Node `require("@plasius/error")` consumers to fail at runtime with:
+`exports is not defined in ES module scope`.
+
+## Decision
+
+Keep dual output and explicitly mark the `dist-cjs/` build directory with a
+generated `dist-cjs/package.json` containing:
+
+```json
+{
+  "type": "commonjs"
+}
+```
+
+Add publish verification checks to ensure this metadata exists and is included
+in the packed artifact.
+
+## Consequences
+
+- CJS consumers resolve and execute `@plasius/error` reliably.
+- ESM consumers remain unchanged (`dist/index.js`).
+- Packaging safety improves by preventing accidental regressions during release.

package/docs/adrs/index.md

@@ -2,3 +2,4 @@
 
 - [ADR-0001: Standalone @plasius/error Package Scope](./adr-0001-error-package-scope.md)
 - [ADR-0002: Public Repository Governance Baseline](./adr-0002-public-repo-governance.md)
+- [ADR-0003: Dual ESM and CJS Runtime Compatibility](./adr-0003-dual-esm-cjs-runtime-compatibility.md)

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@plasius/error",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "main": "./dist-cjs/index.js",
   "types": "./dist/index.d.ts",
   "private": false,
   "type": "module",
   "description": "Error handling functions and types for Plasius projects",
   "scripts": {
-    "build": "tsc --build --listEmittedFiles && rsync -av --include '*/' --include '*.module.css' --exclude '*' src/ dist/ || true && npm run build:cjs",
+    "build": "tsc --build --listEmittedFiles && (rsync -av --include '*/' --include '*.module.css' --exclude '*' src/ dist/ || true) && npm run build:cjs",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
@@ -20,7 +20,7 @@
     "audit:npm": "npm audit --audit-level=moderate || true",
     "audit:test": "vitest run --coverage",
     "audit:all": "npm-run-all -l audit:ts audit:eslint audit:deps audit:npm audit:test",
-    "build:cjs": "tsc -p tsconfig.json --module commonjs --moduleResolution node --outDir dist-cjs --tsBuildInfoFile dist-cjs/tsconfig.tsbuildinfo --listEmittedFiles && rsync -av --include '*/' --include '*.module.css' --exclude '*' src/ dist-cjs/ || true",
+    "build:cjs": "tsc -p tsconfig.json --module commonjs --moduleResolution node --outDir dist-cjs --tsBuildInfoFile dist-cjs/tsconfig.tsbuildinfo --listEmittedFiles && (rsync -av --include '*/' --include '*.module.css' --exclude '*' src/ dist-cjs/ || true) && node scripts/write-cjs-package-json.cjs",
     "lint": "eslint .",
     "prepare": "npm run build",
     "pack:check": "node scripts/verify-public-package.cjs",

package/src/errorboundary.tsx

@@ -1,9 +1,29 @@
 import React from "react";
 
+export type ErrorBoundarySeverity = "error" | "fatal";
+
+export interface ErrorBoundaryReport {
+  boundary: string;
+  error: unknown;
+  componentStack?: string;
+  handled?: boolean;
+  severity?: ErrorBoundarySeverity;
+  context?: Record<string, unknown>;
+  timestamp?: number;
+}
+
+export interface ErrorBoundaryAnalyticsClient {
+  reportError: (report: ErrorBoundaryReport) => void;
+}
+
 interface ErrorBoundaryProps {
   name: string;
   children: React.ReactNode;
   fallback?: React.ReactNode;
+  analyticsClient?: ErrorBoundaryAnalyticsClient;
+  errorContext?: Record<string, unknown>;
+  severity?: ErrorBoundarySeverity;
+  onErrorCaptured?: (report: ErrorBoundaryReport, info: React.ErrorInfo) => void;
 }
 
 interface ErrorBoundaryState {
@@ -23,7 +43,22 @@ export class ErrorBoundary extends React.Component<
     return { hasError: true };
   }
 
+  private buildErrorReport(error: Error, info: React.ErrorInfo): ErrorBoundaryReport {
+    return {
+      boundary: this.props.name,
+      error,
+      componentStack: info.componentStack ?? undefined,
+      handled: true,
+      severity: this.props.severity ?? "error",
+      context: this.props.errorContext,
+      timestamp: Date.now(),
+    };
+  }
+
   override componentDidCatch(error: Error, info: React.ErrorInfo) {
+    const report = this.buildErrorReport(error, info);
+    this.props.analyticsClient?.reportError(report);
+    this.props.onErrorCaptured?.(report, info);
     console.error(`Error caught by ${this.props.name}:`, error, info);
   }
 
@@ -33,8 +68,9 @@ export class ErrorBoundary extends React.Component<
         this.props.fallback ?? <h2>{this.props.name} encountered an error.</h2>
       );
     }
-    return this.props.fallback ?? this.props.children;
+
+    return this.props.children;
   }
 }
 
-export default ErrorBoundary;
+export default ErrorBoundary;

package/src/globalcrash.ts

@@ -0,0 +1,214 @@
+import type {
+  ErrorBoundaryAnalyticsClient,
+  ErrorBoundaryReport,
+  ErrorBoundarySeverity,
+} from "./errorboundary.js";
+
+export type GlobalCrashOrigin =
+  | "window.error"
+  | "window.unhandledrejection"
+  | "process.uncaughtException"
+  | "process.unhandledRejection";
+
+export interface GlobalCrashReporterOptions {
+  boundaryName?: string;
+  analyticsClient?: ErrorBoundaryAnalyticsClient;
+  errorContext?: Record<string, unknown>;
+  severity?: ErrorBoundarySeverity;
+  onErrorCaptured?: (report: ErrorBoundaryReport, origin: GlobalCrashOrigin) => void;
+  captureBrowserErrors?: boolean;
+  captureBrowserRejections?: boolean;
+  captureProcessErrors?: boolean;
+}
+
+export interface GlobalCrashReporterController {
+  dispose: () => void;
+}
+
+type BrowserEventTarget = {
+  addEventListener: (eventName: string, handler: (event: unknown) => void) => void;
+  removeEventListener: (eventName: string, handler: (event: unknown) => void) => void;
+};
+
+type NodeProcessTarget = {
+  on: (eventName: string, handler: (...args: unknown[]) => void) => void;
+  off: (eventName: string, handler: (...args: unknown[]) => void) => void;
+};
+
+function isBrowserEventTarget(value: unknown): value is BrowserEventTarget {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+
+  const candidate = value as Partial<BrowserEventTarget>;
+  return (
+    typeof candidate.addEventListener === "function" &&
+    typeof candidate.removeEventListener === "function"
+  );
+}
+
+function isNodeProcessTarget(value: unknown): value is NodeProcessTarget {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+
+  const candidate = value as Partial<NodeProcessTarget>;
+  return typeof candidate.on === "function" && typeof candidate.off === "function";
+}
+
+function normalizeError(error: unknown): Error {
+  if (error instanceof Error) {
+    return error;
+  }
+
+  if (typeof error === "string") {
+    return new Error(error);
+  }
+
+  if (error === null || error === undefined) {
+    return new Error("Unknown crash reason");
+  }
+
+  try {
+    return new Error(JSON.stringify(error));
+  } catch {
+    return new Error(String(error));
+  }
+}
+
+function extractErrorEventContext(event: unknown): {
+  error: unknown;
+  details: Record<string, unknown>;
+} {
+  const details: Record<string, unknown> = {};
+
+  if (!event || typeof event !== "object") {
+    return {
+      error: event,
+      details,
+    };
+  }
+
+  const record = event as Record<string, unknown>;
+
+  if (typeof record.message === "string" && record.message.trim()) {
+    details.message = record.message;
+  }
+
+  if (typeof record.filename === "string" && record.filename.trim()) {
+    details.filename = record.filename;
+  }
+
+  if (typeof record.lineno === "number") {
+    details.lineno = record.lineno;
+  }
+
+  if (typeof record.colno === "number") {
+    details.colno = record.colno;
+  }
+
+  return {
+    error: record.error ?? record.reason ?? record,
+    details,
+  };
+}
+
+export function installGlobalCrashReporter(
+  options: GlobalCrashReporterOptions = {}
+): GlobalCrashReporterController {
+  const boundaryName = options.boundaryName?.trim() || "GlobalApplication";
+  const severity = options.severity ?? "fatal";
+  const baseContext = {
+    ...(options.errorContext ?? {}),
+  };
+
+  const disposers: Array<() => void> = [];
+
+  const emitReport = (
+    origin: GlobalCrashOrigin,
+    rawError: unknown,
+    contextDetails: Record<string, unknown> = {}
+  ) => {
+    const error = normalizeError(rawError);
+    const report: ErrorBoundaryReport = {
+      boundary: boundaryName,
+      error,
+      handled: false,
+      severity,
+      context: {
+        ...baseContext,
+        crashOrigin: origin,
+        ...contextDetails,
+      },
+      timestamp: Date.now(),
+    };
+
+    options.analyticsClient?.reportError(report);
+    options.onErrorCaptured?.(report, origin);
+  };
+
+  const browserGlobal =
+    typeof window !== "undefined" ? window : (globalThis as { window?: unknown }).window;
+
+  if (isBrowserEventTarget(browserGlobal)) {
+    if (options.captureBrowserErrors !== false) {
+      const handleBrowserError = (event: unknown) => {
+        const { error, details } = extractErrorEventContext(event);
+        emitReport("window.error", error, details);
+      };
+
+      browserGlobal.addEventListener("error", handleBrowserError);
+      disposers.push(() => {
+        browserGlobal.removeEventListener("error", handleBrowserError);
+      });
+    }
+
+    if (options.captureBrowserRejections !== false) {
+      const handleUnhandledRejection = (event: unknown) => {
+        const { error, details } = extractErrorEventContext(event);
+        emitReport("window.unhandledrejection", error, details);
+      };
+
+      browserGlobal.addEventListener("unhandledrejection", handleUnhandledRejection);
+      disposers.push(() => {
+        browserGlobal.removeEventListener("unhandledrejection", handleUnhandledRejection);
+      });
+    }
+  }
+
+  const processGlobal = (globalThis as { process?: unknown }).process;
+
+  if (options.captureProcessErrors !== false && isNodeProcessTarget(processGlobal)) {
+    const handleUncaughtException = (error: unknown) => {
+      emitReport("process.uncaughtException", error);
+    };
+
+    const handleUnhandledRejection = (reason: unknown) => {
+      emitReport("process.unhandledRejection", reason);
+    };
+
+    processGlobal.on("uncaughtException", handleUncaughtException);
+    processGlobal.on("unhandledRejection", handleUnhandledRejection);
+
+    disposers.push(() => {
+      processGlobal.off("uncaughtException", handleUncaughtException);
+      processGlobal.off("unhandledRejection", handleUnhandledRejection);
+    });
+  }
+
+  let disposed = false;
+
+  return {
+    dispose() {
+      if (disposed) {
+        return;
+      }
+
+      disposed = true;
+      for (const dispose of disposers) {
+        dispose();
+      }
+      disposers.length = 0;
+    },
+  };
+}

package/src/index.ts

@@ -1 +1,2 @@
 export * from "./errorboundary.js";
+export * from "./globalcrash.js";