@tallyrow/safesignal 1.2.0 → 1.4.0

package/README.md

@@ -2,11 +2,35 @@
 
 **SafeSignal** is a browser-first, vendor-neutral structured logging
 facade and safety boundary for browser applications and federated
-frontend modules. Secure-by-default sanitization, URL scrubbing,
-key + shape redaction, control-character escaping, and a pluggable
-transport boundary — all applied before any transport sees an event.
-Published on npm as `@tallyrow/safesignal` (TallyRow is the
-publishing organization; SafeSignal is the product).
+frontend modules. It catches the errors your users actually hit —
+uncaught exceptions, unhandled rejections, and React/Vue component
+crashes — and ships them securely to any backend. Secure-by-default
+sanitization, URL scrubbing, key + shape redaction, control-character
+escaping, and a pluggable transport boundary — all applied before any
+transport sees an event. Published on npm as `@tallyrow/safesignal`
+(TallyRow is the publishing organization; SafeSignal is the product).
+
+## What you get
+
+The visible wins — all opt-in subpaths, each routed through the same
+secure pipeline as any log:
+
+- ⭐ **[Catch the silent errors](#catch-uncaught-errors--capture-subpath)** —
+  the opt-in `./capture` subpath logs the **uncaught exceptions and
+  unhandled rejections** that otherwise never reach your transports.
+- **[Dev-mode console rendering](#pretty-dev-logs--dev-console-subpath)** —
+  readable, colorized log output in development.
+- **[Error breadcrumbs](#error-breadcrumbs--recent-event-context-on-errors)** —
+  bounded recent-event context attached to each error.
+- **[Readable, source-mapped error stacks](#readable-error-stacks--stacks-subpath)** —
+  turn a wall of minified frames into trimmed, structured ones.
+- **[React error boundary + hook](#catch-react-errors--framework-react-subpath)** —
+  `./framework-react` routes component-tree errors through your `Logger`.
+- **[Vue errorHandler adapter](#catch-vue-errors--framework-vue-subpath)** —
+  `./framework-vue` does the same for Vue 3.
+
+The core stays tiny and ships nothing you don't import. Here is *why*
+each of those stays safe:
 
 ## Why SafeSignal
 
@@ -14,7 +38,7 @@ publishing organization; SafeSignal is the product).
 - **Never-throw boundary**: no transport, redactor, or sanitizer failure propagates into your `log.info(...)` call site. Logging cannot break rendering, navigation, or state updates.
 - **Vendor-neutral transport**: ship to Datadog, Honeycomb, your own ingestion, or the built-in `./transport-beacon` subpath for body-only HTTPS delivery — same API regardless of destination.
 - **Federated-runtime aware**: host owns the configured runtime; modules import loggers without re-configuring. Hundreds of `Logger` instances per page stay constant-cost.
-- **Lightweight**: ~8 KB gzipped default entry; structured events with bounded depth and bounded size; no global listeners, no ambient state reads, no per-instance backend init.
+- **Lightweight**: ~8 KB gzipped default entry; structured events with bounded depth and bounded size; the core installs no global listeners and reads no ambient state (an opt-in host subpath may install one — see the [`./capture` subpath](#catch-uncaught-errors--capture-subpath)), and `Logger` creation does no per-instance backend init.
 
 ## Install
 
@@ -48,9 +72,15 @@ log.info('checkout opened', { cartItems: 3 });
   custom delivery primitive.
 - Read `process.env.NODE_ENV`, `import.meta.env`, `location`, or
   `document.cookie` — pass `environment` explicitly.
-- Install global listeners or singletons (RUM-style automatic
-  error capture, view tracking, web vitals, network
-  instrumentation are forward-looking; see Roadmap below).
+- Touch globals from the **core** or from `createLogger()` — the
+  core installs no global listeners and reads no ambient state. The
+  **one opt-in exception** is host-owned: a host may install a
+  single global **error** capturer via the
+  [`./capture` subpath](#catch-uncaught-errors--capture-subpath) —
+  explicit, opt-in, routed through the same secure pipeline;
+  federated modules never install it. Web Vitals, view tracking,
+  network instrumentation, and a server/monitoring backend remain out
+  of scope — SafeSignal is an error-logging library, not a RUM product.
 - Persist events to IndexedDB or any storage layer.
 - Batch, sample, or deduplicate events by default (opt-in
   batching is available via the `./transport-beacon` subpath).
@@ -194,6 +224,316 @@ getRootLogger().info('payment.authorized', { amount: 4200 });
   context-merge precedence (root → logger chain → `correlation()`); host and
   federated modules each contribute without per-`Logger` cost.
 
+### Tag the delivery request with `traceparent`
+
+Beyond the per-`LogRecord` trace fields above, the `./transport-otlp` transport
+can also set a W3C `traceparent` (and `tracestate`) **request header** on the
+delivery request itself, so a backend or collector can join the ingest request
+to its trace. It is **off by default** — opt in per transport:
+
+```ts
+const transport = createOtlpTransport({
+  endpoint: 'https://otlp.example.com/v1/logs',
+  headers: { authorization: `Bearer ${token}` }, // sent only on the wire
+  injectTraceparent: true, // ← opt in
+});
+```
+
+A delivery request carries the header **only when every event in the flushed
+batch shares one valid trace context** (the common case for a burst of logs in
+one span); a mixed-trace, trace-less, or empty batch sends no header — never an
+arbitrary "representative" one. `tracestate` rides along only when it is
+identical across the batch (and within the 512-char bound).
+
+- **Carry-only / fail-safe**: built from the events' existing `context.trace`;
+  no ids are minted, header construction never throws into a logging call or
+  blocks delivery, and the event payload is byte-identical either way.
+- **Secure**: the header carries only trace identifiers + bounded `tracestate`;
+  it never overwrites, duplicates, or exposes your auth/secret `headers`
+  (a consumer-supplied `traceparent` wins). Only `./transport-otlp` supports it
+  — `navigator.sendBeacon` cannot set custom request headers, so
+  `./transport-beacon` is out of scope.
+
+## Catch uncaught errors — `./capture` subpath
+
+Uncaught exceptions and unhandled promise rejections normally vanish —
+they never reach your configured transports. The **opt-in** `./capture`
+subpath lets a **host** route them through the same secure pipeline as
+every other log:
+
+```ts
+import { configureLogging, getRootLogger } from '@tallyrow/safesignal';
+import { createBeaconTransport } from '@tallyrow/safesignal/transport-beacon';
+import { installGlobalErrorCapture } from '@tallyrow/safesignal/capture';
+
+configureLogging({
+  application: { name: 'checkout-web', version: '4.2.0' },
+  environment: 'production',
+  transports: [createBeaconTransport({ endpoint: 'https://logs.example.com/ingest' })],
+});
+
+// Host installs once — returns a disposer.
+const dispose = installGlobalErrorCapture(getRootLogger());
+// …on teardown: dispose();
+```
+
+It emits an `error`-level event (`'Uncaught exception'` /
+`'Unhandled promise rejection'`) carrying the serialized error and a
+`safesignal.source` / `safesignal.errorType` marker, redacted +
+sanitized like any log.
+
+- **Host-owned, opt-in** (Principle VIII): it is **never** a side effect
+  of `createLogger()`; a **federated module never installs it** — only the
+  host that owns the runtime does. Pass it the host's `Logger`
+  (`getRootLogger()` or `createLogger({ module })`).
+- **Fail-safe**: it never throws into the page and never breaks
+  rendering/navigation; a failing transport is swallowed to
+  `onInternalError`.
+- **Additive**: it chains via `addEventListener` — your existing
+  `window.onerror`/handlers keep firing; it never `preventDefault()`s.
+- **Errors only** — no view tracking, web vitals, or network
+  instrumentation (that is RUM — out of scope). Duplicate package copies are
+  **isolated** (each capturer uses the `Logger` from its own copy).
+
+## Catch React errors — `./framework-react` subpath
+
+When a React component throws during render, the default outcome is a blank
+screen and an error that never reaches your transports. The **opt-in**
+`./framework-react` subpath is the **no-globals, per-component** counterpart to
+`./capture`: a `<LogErrorBoundary>` and a `useLogError()` hook that route React
+errors through your existing `Logger` and render a graceful fallback. `react` is
+a **peer dependency** (`>=16.8`) — the core and every other subpath stay
+React-free.
+
+```tsx
+import { configureLogging, createLogger } from '@tallyrow/safesignal';
+import { LoggerProvider, LogErrorBoundary, useLogError }
+  from '@tallyrow/safesignal/framework-react';
+
+configureLogging({ application: { name: 'checkout-web' }, environment: 'production', transports: [/* … */] });
+const log = createLogger({ module: 'checkout' });
+
+function App() {
+  return (
+    <LoggerProvider logger={log}>
+      <LogErrorBoundary fallback={<p>Something went wrong.</p>}>
+        <Checkout />
+      </LogErrorBoundary>
+    </LoggerProvider>
+  );
+}
+```
+
+A boundary-caught error emits an `error`-level event (`'React render error'`)
+carrying the serialized error and the React **component stack**
+(`safesignal.react.componentStack`), with `safesignal.source:
+'react-error-boundary'`, redacted + sanitized like any log. For the errors a
+boundary **cannot** catch — event handlers, async/`Promise` callbacks, effects —
+use the hook:
+
+```tsx
+function SaveButton() {
+  const logError = useLogError(); // stable callback; resolves the logger from context
+  const onClick = async () => {
+    try { await save(); } catch (err) { logError(err, { 'safesignal.action': 'save' }); }
+  };
+  return <button onClick={onClick}>Save</button>;
+}
+```
+
+- **No globals** (Principle VIII): patches nothing, attaches no `window`
+  listeners — the explicit contrast with `./capture`'s host-level install. The
+  two are complementary and can be used together.
+- **Fail-safe** (Principle III): a logging (or `onError`) failure is swallowed
+  and the fallback still renders; React semantics keep it loop-free.
+- **Fail-closed** (Principle V): errors route through the same redaction
+  pipeline as any log; if redaction fails the event is dropped.
+- **Explicit logger**: provide it via `<LoggerProvider>` or a `logger` prop /
+  `useLogError(logger)` argument. With no logger resolvable, the helpers are a
+  **safe no-op** (never throw). `<LogErrorBoundary>` also accepts `onError`,
+  `resetKeys`, and a render-prop `fallback={(error, reset) => …}` for recovery.
+  Duplicate package copies are **isolated** (each routes through the logger it is
+  handed).
+
+## Catch Vue errors — `./framework-vue` subpath
+
+The Vue 3 counterpart of `./framework-react`. When a Vue component throws during
+render, a lifecycle hook, a watcher, or a template handler, that error never
+reaches your transports. The **opt-in** `./framework-vue` subpath is the
+**no-globals, per-app** counterpart to `./capture`: an `app.config.errorHandler`
+adapter plus the `useLogError()` and `useErrorCapture()` composables that route
+Vue errors through your existing `Logger`. `vue` is a **peer dependency**
+(`>=3.0`) — the core and every other subpath stay Vue-free.
+
+```ts
+import { createApp } from 'vue';
+import { createLogger } from '@tallyrow/safesignal';
+import { safesignalErrorHandler } from '@tallyrow/safesignal/framework-vue';
+
+const log = createLogger({ module: 'checkout' });
+
+createApp(App)
+  .use(safesignalErrorHandler, { logger: log }) // sets app.config.errorHandler + provides the logger
+  .mount('#app');
+```
+
+A framework error emits an `error`-level event (`'Vue error'`) carrying the
+serialized error and best-effort Vue context (`safesignal.vue.info`,
+`safesignal.vue.componentName`), with `safesignal.source: 'vue-error-handler'`,
+redacted + sanitized like any log. Prefer to wire it yourself? The factory is
+side-effect-free: `app.config.errorHandler = createErrorHandler(log)`.
+
+For errors Vue's handler can't catch (async/`try`-`catch`, native listeners), use
+`useLogError()`; to contain and recover a subtree, use `useErrorCapture()`:
+
+```ts
+import { ref } from 'vue';
+import { useLogError, useErrorCapture } from '@tallyrow/safesignal/framework-vue';
+
+// In a component's setup():
+const logError = useLogError(); // stable callback; resolves the provided logger
+async function onClick() {
+  try { await save(); } catch (err) { logError(err, { 'safesignal.action': 'save' }); }
+}
+
+// In a wrapper component's setup() — a subtree boundary:
+const failed = ref(false);
+useErrorCapture({ onError: () => { failed.value = true; } });
+// descendant errors log once (safesignal.source: 'vue-error-captured') and, by
+// default, do NOT also reach the app-level handler. Pass { propagate: true } to bubble.
+```
+
+- **No globals** (Principle VIII): patches nothing, attaches no `window`
+  listeners — the explicit contrast with `./capture`. Complementary; usable together.
+- **Fail-safe** (Principle III): a logging (or `onError`) failure is swallowed and
+  the app keeps running; no error loop.
+- **Fail-closed** (Principle V): errors route through the same redaction pipeline
+  as any log; if redaction fails the event is dropped.
+- **Explicit logger**: provide it via the plugin (or `useLogError(logger)` /
+  `useErrorCapture({ logger })`). With no logger resolvable, the helpers are a
+  **safe no-op** (never throw). Duplicate package copies are **isolated**.
+
+## Readable error stacks — `./stacks` subpath
+
+A raw browser error stack is a wall of minified, framework-internal noise. The
+**opt-in** `./stacks` subpath parses an error's stack into **trimmed, structured
+frames** (function / file / line / column), and — when you supply a **synchronous
+source-map resolver** — maps minified production frames back to original source
+positions. **Off by default.**
+
+```ts
+import { configureLogging, getRootLogger } from '@tallyrow/safesignal';
+import { createStackNormalizer } from '@tallyrow/safesignal/stacks';
+
+// Optional: a SYNCHRONOUS resolver over source maps you have already loaded.
+const resolver = (f) => mySourceMaps.lookup(f.file, f.line, f.column) ?? null;
+
+configureLogging({
+  application: { name: 'checkout-web', version: '4.2.0' },
+  environment: 'production',
+  transports: [/* … */],
+  normalizeStack: createStackNormalizer({ resolver, maxFrames: 30 }), // OFF unless set
+});
+
+getRootLogger().error('checkout failed', { orderId: 'ord_9f3' }, new Error('boom'));
+```
+
+The delivered **error** event gains `attributes['safesignal.stack']` — an ordered
+array of `{ function?, file?, line?, column?, original? }` (the raw `error.stack`
+string is preserved unchanged). Other events are untouched.
+
+- **Trimmed**: `node_modules`, engine-internal, and boilerplate frames are removed
+  by default (`includeNodeModules` / `includeInternal` opt back in); bounded to
+  `maxFrames` (default 30, max 100).
+- **Source-mapped**: with a **synchronous** `resolver`, resolvable frames carry
+  `original`; an unmappable frame is left as-is. SafeSignal does **no** async work
+  or `.map` fetching — you load your maps; SafeSignal calls a fast sync lookup.
+- **Safe**: frames ride in `attributes`, so a secret in a frame URL's query is
+  scrubbed by the pipeline (whole-value guarantee). Off by default, fail-safe
+  (a throwing parser/resolver never breaks the page — the error is always
+  delivered), runtime-level (no per-`Logger` cost), and **no new dependency**.
+
+## Error breadcrumbs — recent-event context on errors
+
+When an error is logged, the hardest debugging question is "what happened *just
+before* this?" Enable **opt-in error breadcrumbs** and every error log
+automatically carries a bounded trail of the most recent events plus the error's
+cause chain — built only from SafeSignal's own already sanitized + redacted
+events. **Off by default.**
+
+```ts
+import { configureLogging, getRootLogger } from '@tallyrow/safesignal';
+
+configureLogging({
+  application: { name: 'checkout-web', version: '4.2.0' },
+  environment: 'production',
+  transports: [/* … */],
+  breadcrumbs: true,          // or { maxEvents: 30 } — default 20, max 100
+});
+
+const log = getRootLogger();
+log.info('checkout opened', { cartItems: 3 });
+log.warn('coupon expired');
+log.error('checkout failed', { orderId: 'ord_9f3' },
+  new Error('checkout failed', { cause: new Error('payment processor 5xx') }));
+```
+
+The delivered **error** event gains two documented, machine-parseable attribute
+fields (other events are untouched):
+
+- `attributes['safesignal.breadcrumbs']` — the recent events, oldest→newest, each
+  `{ ts, level, message, app?, module?, attributes? }` (host vs. federated-module
+  origin stays distinguishable).
+- `attributes['safesignal.errorCauses']` — the error's nested cause chain,
+  outermost→root, each `{ name, message }`.
+
+- **Bounded & cheap**: a single runtime-level ring buffer — constant memory (≤
+  `maxEvents`), constant-cost recording, **no** per-`Logger` cost. Duplicate
+  package copies are **isolated** (each runtime owns its buffer).
+- **Safe**: breadcrumbs carry only the post-redaction event; the cause chain runs
+  through the same redaction. It never mutates other (or already-delivered)
+  events, and never throws into the page — an error is always delivered, with or
+  without the trail.
+
+## Pretty dev logs — `./dev-console` subpath
+
+The built-in `ConsoleTransport` hands devtools the message plus the structured
+event object — correct and safe, but a wall of JSON to scan locally. The
+**opt-in** `./dev-console` subpath ships `DevConsoleTransport`: a pretty,
+**development-only** sibling that renders the *same* already sanitized + redacted
+event as a collapsed, level-styled group (icon/color, message, `app · module ·
+env`, attributes, error, and a trace link). Select it **only** in development so
+your bundler tree-shakes it out of production entirely:
+
+```ts
+import { configureLogging, getRootLogger, ConsoleTransport } from '@tallyrow/safesignal';
+import { DevConsoleTransport } from '@tallyrow/safesignal/dev-console';
+
+configureLogging({
+  application: { name: 'checkout-web', version: '4.2.0' },
+  environment: import.meta.env.DEV ? 'development' : 'production',
+  transports: [
+    import.meta.env.DEV
+      ? DevConsoleTransport({ traceUrl: ({ traceId }) => `https://trace.example/${traceId}` })
+      : ConsoleTransport(),
+  ],
+});
+
+getRootLogger().info('checkout opened', { cartItems: 3 });
+```
+
+- **Genuine zero production cost**: the dev branch is dead-code-eliminated from
+  your production build, so the renderer ships **0 bytes** there. SafeSignal's
+  default `.` entry (and `ConsoleTransport`) is byte-unchanged.
+- **Runtime-gated + defensive**: it renders pretty only when the event's
+  `environment === 'development'`; in any other environment — or where rich
+  console features are absent — it behaves exactly like `ConsoleTransport`
+  (`console[level](message, event)`), even if mistakenly used in production.
+- **Structured-only & safe**: it renders **only** the post-pipeline event (no
+  re-serialization of app objects), attaches **no** globals, reads no ambient
+  state, and never throws into the page. The optional `traceUrl` formatter is
+  carry-only — built from the event's existing trace ids, no ids minted.
+
 ## Level configuration
 
 In `production`, `debug` and `info` are dropped by default. Raise the
@@ -252,7 +592,7 @@ log.info('order placed', { orderId: order.id, total: order.total });
 enumeration of DO / DON'T patterns, the sanitizer's bounded-input
 rules, the redactor's default denylist and shape rules,
 `createRedactor()` composition, `scrubUrl()` usage, the
-diagnostics contract, and — per constitution Principle VI — every
+diagnostics contract, and — per constitution Principle VII — every
 documented behavior that drops, transforms, or otherwise bounds an
 event before delivery (level-filter drops, fail-closed redactor
 drops, sanitizer truncation markers, URL-scrubber replacements,
@@ -352,11 +692,12 @@ package copies", and "Vendor neutrality".
 
 ## Project resources
 
-[![pipeline status](https://gitlab.com/tallyrow/safesignal/badges/main/pipeline.svg)](https://gitlab.com/tallyrow/safesignal/-/commits/main)
+[![CI](https://github.com/TallyRow/safesignal/actions/workflows/ci.yml/badge.svg)](https://github.com/TallyRow/safesignal/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@tallyrow/safesignal.svg)](https://www.npmjs.com/package/@tallyrow/safesignal)
 
 Community and legal:
 
-- [`CONTRIBUTING.md`](CONTRIBUTING.md) — how to file issues, send MRs, sign commits (DCO)
+- [`CONTRIBUTING.md`](CONTRIBUTING.md) — how to file issues, open PRs, sign commits (DCO)
 - [`SECURITY.md`](SECURITY.md) — vulnerability disclosure policy
 - [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) — Contributor Covenant 2.1
 - [`GOVERNANCE.md`](GOVERNANCE.md) — how project decisions get made
@@ -381,21 +722,17 @@ Reference docs and design history:
 
 The following are forward-looking items (not shipping today):
 
-- **Trace-context propagation** — W3C Trace Context (`traceparent`,
-  `tracestate`) for correlating frontend logs with backend traces.
 - **OTLP/HTTP+protobuf encoding** for the
   [`./transport-otlp`](#ship-logs-to-otlp--transport-otlp-subpath)
   subpath — the subpath ships **JSON** today behind an internal
   encoding seam; a protobuf encoder is an additive follow-up (no
   public-API change).
-- **RUM features** — Web Vitals, automatic error capture, view
-  tracking, network instrumentation (planned as opt-in subpaths
-  under `./rum-*`).
-
-A separate sibling project, **`safesignal-server`**, is planned as
-a self-hostable monitoring backend that consumes SafeSignal's
-OTLP-formatted events. SafeSignal stays a small vendor-neutral
-SDK; the server lives in its own repo when it ships.
+
+SafeSignal is singly focused: it captures your errors — explicit
+`log.error`, framework boundaries, and opt-in global capture — and
+ships them securely to any backend. It is **not** a RUM/monitoring
+product (no Web Vitals, view tracking, network instrumentation, or
+server backend) and is not planned to become one.
 
 ## Migration history
 

package/dist/capture.cjs

@@ -0,0 +1,77 @@
+'use strict';
+
+// src/capture/index.ts
+var SOURCE = "global-error-capture";
+function noop() {
+}
+function safeNotify(hook, cause) {
+  if (!hook) return;
+  try {
+    hook(cause instanceof Error ? cause : new Error(String(cause)));
+  } catch {
+  }
+}
+function installGlobalErrorCapture(logger, options = {}) {
+  const target = options.target ?? globalThis;
+  const canListen = typeof target.addEventListener === "function" && typeof target.removeEventListener === "function";
+  if (!canListen) return noop;
+  let disposed = false;
+  let inFlight = false;
+  const emit = (message, errorType, errorValue, extra) => {
+    if (inFlight) return;
+    inFlight = true;
+    try {
+      const attributes = {
+        "safesignal.source": SOURCE,
+        "safesignal.errorType": errorType,
+        ...extra ?? {}
+      };
+      logger.error(message, attributes, errorValue);
+    } catch (err) {
+      safeNotify(options.onInternalError, err);
+    } finally {
+      inFlight = false;
+    }
+  };
+  const handleError = (event) => {
+    try {
+      const e = event;
+      const hasError = e.error !== void 0 && e.error !== null;
+      const extra = {};
+      if (!hasError) {
+        if (typeof e.filename === "string") extra.filename = e.filename;
+        if (typeof e.lineno === "number") extra.lineno = e.lineno;
+        if (typeof e.colno === "number") extra.colno = e.colno;
+      }
+      const errorValue = hasError ? e.error : typeof e.message === "string" ? e.message : "Uncaught exception";
+      emit(
+        "Uncaught exception",
+        "uncaught-exception",
+        errorValue,
+        Object.keys(extra).length > 0 ? extra : void 0
+      );
+    } catch (err) {
+      safeNotify(options.onInternalError, err);
+    }
+  };
+  const handleRejection = (event) => {
+    try {
+      const e = event;
+      emit("Unhandled promise rejection", "unhandled-rejection", e.reason);
+    } catch (err) {
+      safeNotify(options.onInternalError, err);
+    }
+  };
+  target.addEventListener("error", handleError);
+  target.addEventListener("unhandledrejection", handleRejection);
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    target.removeEventListener("error", handleError);
+    target.removeEventListener("unhandledrejection", handleRejection);
+  };
+}
+
+exports.installGlobalErrorCapture = installGlobalErrorCapture;
+//# sourceMappingURL=capture.cjs.map
+//# sourceMappingURL=capture.cjs.map

package/dist/capture.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/capture/index.ts"],"names":[],"mappings":"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","file":"capture.cjs","sourcesContent":["/**\n * Opt-in global error capture — the `./capture` subpath.\n *\n * A **host-level**, opt-in install that routes **uncaught exceptions** and\n * **unhandled promise rejections** through the host `Logger`'s existing secure\n * pipeline (sanitize → URL-scrub → redact → guard → transport). It is the single\n * explicit host-installed runtime-level global handler Principle VIII v1.5.0\n * sanctions — never a side effect of `createLogger()`, never installed by a\n * federated module.\n *\n * Properties (see `specs/013-global-error-capture/contracts/capture-api.md`):\n *   - Fail-closed: emits via `logger.error`, so stacks/messages are redacted +\n *     sanitized (drop-on-failure) before any transport sees them.\n *   - Fail-safe: never throws/rejects into the page; internal failures are\n *     swallowed (routed to `options.onInternalError`).\n *   - Additive: attaches via `addEventListener` — never assigns `window.onerror`\n *     and never calls `preventDefault()`, so existing handlers keep firing.\n *   - Loop-safe: a re-entrancy guard stops an error raised during emit from\n *     re-capturing.\n *   - Errors only: attaches ONLY `error` + `unhandledrejection` (not RUM).\n *\n * The only `src/` import is **type-only** from `../api/types.js`, so this bundle\n * shares no runtime state with the core (it operates through the passed\n * `Logger`, which closes over the host's configured runtime).\n */\n\nimport type { Attributes, Logger } from '../api/types.js';\n\n/** Options for {@link installGlobalErrorCapture}. */\nexport interface GlobalErrorCaptureOptions {\n  /** Where to attach listeners. Default: `globalThis`. */\n  target?: EventTarget;\n  /**\n   * Diagnostics hook for the capturer's OWN failures (event-build/dispatch\n   * throw). Invoked fail-safe — its own throw is swallowed. Distinct from the\n   * runtime's `onInternalError`.\n   */\n  onInternalError?: (err: Error) => void;\n}\n\n/** Removes the installed listeners and stops capture. Idempotent. */\nexport type GlobalErrorCaptureDisposer = () => void;\n\nconst SOURCE = 'global-error-capture';\n\nfunction noop(): void {\n  /* no-op disposer */\n}\n\nfunction safeNotify(\n  hook: ((err: Error) => void) | undefined,\n  cause: unknown,\n): void {\n  if (!hook) return;\n  try {\n    hook(cause instanceof Error ? cause : new Error(String(cause)));\n  } catch {\n    // A diagnostics hook that itself throws must not break capture.\n  }\n}\n\n/**\n * Install host-level capture of uncaught exceptions + unhandled promise\n * rejections, routed through `logger`'s configured pipeline. Returns a disposer.\n * Opt-in, host-owned; never a side effect of `createLogger()`. Never throws.\n */\nexport function installGlobalErrorCapture(\n  logger: Logger,\n  options: GlobalErrorCaptureOptions = {},\n): GlobalErrorCaptureDisposer {\n  const target: EventTarget =\n    options.target ?? (globalThis as unknown as EventTarget);\n\n  // Safe no-op where the target cannot register listeners (SSR / worker).\n  const canListen =\n    typeof (target as { addEventListener?: unknown }).addEventListener ===\n      'function' &&\n    typeof (target as { removeEventListener?: unknown }).removeEventListener ===\n      'function';\n  if (!canListen) return noop;\n\n  let disposed = false;\n  let inFlight = false;\n\n  const emit = (\n    message: string,\n    errorType: 'uncaught-exception' | 'unhandled-rejection',\n    errorValue: unknown,\n    extra?: Attributes,\n  ): void => {\n    if (inFlight) return; // loop-safety: drop a capture raised during emit.\n    inFlight = true;\n    try {\n      const attributes: Attributes = {\n        'safesignal.source': SOURCE,\n        'safesignal.errorType': errorType,\n        ...(extra ?? {}),\n      };\n      logger.error(message, attributes, errorValue);\n    } catch (err) {\n      safeNotify(options.onInternalError, err);\n    } finally {\n      inFlight = false;\n    }\n  };\n\n  const handleError = (event: Event): void => {\n    try {\n      const e = event as ErrorEvent;\n      const hasError = e.error !== undefined && e.error !== null;\n      const extra: Attributes = {};\n      if (!hasError) {\n        // Cross-origin \"Script error.\" cases carry no error object.\n        if (typeof e.filename === 'string') extra.filename = e.filename;\n        if (typeof e.lineno === 'number') extra.lineno = e.lineno;\n        if (typeof e.colno === 'number') extra.colno = e.colno;\n      }\n      const errorValue = hasError\n        ? e.error\n        : typeof e.message === 'string'\n          ? e.message\n          : 'Uncaught exception';\n      emit(\n        'Uncaught exception',\n        'uncaught-exception',\n        errorValue,\n        Object.keys(extra).length > 0 ? extra : undefined,\n      );\n    } catch (err) {\n      safeNotify(options.onInternalError, err);\n    }\n  };\n\n  const handleRejection = (event: Event): void => {\n    try {\n      const e = event as PromiseRejectionEvent;\n      emit('Unhandled promise rejection', 'unhandled-rejection', e.reason);\n    } catch (err) {\n      safeNotify(options.onInternalError, err);\n    }\n  };\n\n  target.addEventListener('error', handleError);\n  target.addEventListener('unhandledrejection', handleRejection);\n\n  return (): void => {\n    if (disposed) return;\n    disposed = true;\n    target.removeEventListener('error', handleError);\n    target.removeEventListener('unhandledrejection', handleRejection);\n  };\n}\n"]}

package/dist/capture.d.cts

@@ -0,0 +1,49 @@
+import { f as Logger } from './types-CZtSjgq5.cjs';
+
+/**
+ * Opt-in global error capture — the `./capture` subpath.
+ *
+ * A **host-level**, opt-in install that routes **uncaught exceptions** and
+ * **unhandled promise rejections** through the host `Logger`'s existing secure
+ * pipeline (sanitize → URL-scrub → redact → guard → transport). It is the single
+ * explicit host-installed runtime-level global handler Principle VIII v1.5.0
+ * sanctions — never a side effect of `createLogger()`, never installed by a
+ * federated module.
+ *
+ * Properties (see `specs/013-global-error-capture/contracts/capture-api.md`):
+ *   - Fail-closed: emits via `logger.error`, so stacks/messages are redacted +
+ *     sanitized (drop-on-failure) before any transport sees them.
+ *   - Fail-safe: never throws/rejects into the page; internal failures are
+ *     swallowed (routed to `options.onInternalError`).
+ *   - Additive: attaches via `addEventListener` — never assigns `window.onerror`
+ *     and never calls `preventDefault()`, so existing handlers keep firing.
+ *   - Loop-safe: a re-entrancy guard stops an error raised during emit from
+ *     re-capturing.
+ *   - Errors only: attaches ONLY `error` + `unhandledrejection` (not RUM).
+ *
+ * The only `src/` import is **type-only** from `../api/types.js`, so this bundle
+ * shares no runtime state with the core (it operates through the passed
+ * `Logger`, which closes over the host's configured runtime).
+ */
+
+/** Options for {@link installGlobalErrorCapture}. */
+interface GlobalErrorCaptureOptions {
+    /** Where to attach listeners. Default: `globalThis`. */
+    target?: EventTarget;
+    /**
+     * Diagnostics hook for the capturer's OWN failures (event-build/dispatch
+     * throw). Invoked fail-safe — its own throw is swallowed. Distinct from the
+     * runtime's `onInternalError`.
+     */
+    onInternalError?: (err: Error) => void;
+}
+/** Removes the installed listeners and stops capture. Idempotent. */
+type GlobalErrorCaptureDisposer = () => void;
+/**
+ * Install host-level capture of uncaught exceptions + unhandled promise
+ * rejections, routed through `logger`'s configured pipeline. Returns a disposer.
+ * Opt-in, host-owned; never a side effect of `createLogger()`. Never throws.
+ */
+declare function installGlobalErrorCapture(logger: Logger, options?: GlobalErrorCaptureOptions): GlobalErrorCaptureDisposer;
+
+export { type GlobalErrorCaptureDisposer, type GlobalErrorCaptureOptions, installGlobalErrorCapture };

package/dist/capture.d.ts

@@ -0,0 +1,49 @@
+import { f as Logger } from './types-CZtSjgq5.js';
+
+/**
+ * Opt-in global error capture — the `./capture` subpath.
+ *
+ * A **host-level**, opt-in install that routes **uncaught exceptions** and
+ * **unhandled promise rejections** through the host `Logger`'s existing secure
+ * pipeline (sanitize → URL-scrub → redact → guard → transport). It is the single
+ * explicit host-installed runtime-level global handler Principle VIII v1.5.0
+ * sanctions — never a side effect of `createLogger()`, never installed by a
+ * federated module.
+ *
+ * Properties (see `specs/013-global-error-capture/contracts/capture-api.md`):
+ *   - Fail-closed: emits via `logger.error`, so stacks/messages are redacted +
+ *     sanitized (drop-on-failure) before any transport sees them.
+ *   - Fail-safe: never throws/rejects into the page; internal failures are
+ *     swallowed (routed to `options.onInternalError`).
+ *   - Additive: attaches via `addEventListener` — never assigns `window.onerror`
+ *     and never calls `preventDefault()`, so existing handlers keep firing.
+ *   - Loop-safe: a re-entrancy guard stops an error raised during emit from
+ *     re-capturing.
+ *   - Errors only: attaches ONLY `error` + `unhandledrejection` (not RUM).
+ *
+ * The only `src/` import is **type-only** from `../api/types.js`, so this bundle
+ * shares no runtime state with the core (it operates through the passed
+ * `Logger`, which closes over the host's configured runtime).
+ */
+
+/** Options for {@link installGlobalErrorCapture}. */
+interface GlobalErrorCaptureOptions {
+    /** Where to attach listeners. Default: `globalThis`. */
+    target?: EventTarget;
+    /**
+     * Diagnostics hook for the capturer's OWN failures (event-build/dispatch
+     * throw). Invoked fail-safe — its own throw is swallowed. Distinct from the
+     * runtime's `onInternalError`.
+     */
+    onInternalError?: (err: Error) => void;
+}
+/** Removes the installed listeners and stops capture. Idempotent. */
+type GlobalErrorCaptureDisposer = () => void;
+/**
+ * Install host-level capture of uncaught exceptions + unhandled promise
+ * rejections, routed through `logger`'s configured pipeline. Returns a disposer.
+ * Opt-in, host-owned; never a side effect of `createLogger()`. Never throws.
+ */
+declare function installGlobalErrorCapture(logger: Logger, options?: GlobalErrorCaptureOptions): GlobalErrorCaptureDisposer;
+
+export { type GlobalErrorCaptureDisposer, type GlobalErrorCaptureOptions, installGlobalErrorCapture };