@edraj/sauron-browser 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to `@edraj/sauron-browser` are documented here.
 
+## 1.6.0
+
+### Added
+
+- **Navigation direction on history breadcrumbs.** SPA navigation breadcrumbs
+  now carry `operation` alongside `from` and `to`: `push` for
+  `history.pushState`, `replace` for `history.replaceState`, and `pop` for
+  `popstate`. A breadcrumb trail no longer reads the same whether the user
+  advanced through a flow or backed out of it.
+
+  The vocabulary is shared with the Flutter SDK's `SauronNavigatorObserver`
+  (`push` / `pop` / `replace` / `remove`), so a trail reads the same whichever
+  SDK sent it. `remove` has no web equivalent and is never emitted here.
+
+  **A forward navigation is recorded as `pop`.** `history.forward()` fires the
+  same `popstate` event as `history.back()` and carries nothing to separate
+  them, so `pop` means "moved through history" rather than specifically "went
+  back". Telling them apart would mean writing a counter into `history.state`,
+  which the host app's router also owns — not a trade this SDK makes to
+  improve a breadcrumb.
+
+  No API change: `operation` is added to `data` on breadcrumbs the SDK already
+  emitted, and the same-path guard still suppresses a `replaceState` to the
+  current URL before any direction is recorded.
+
 ## 1.5.0
 
 ### Added

package/README.md

@@ -985,7 +985,7 @@ const appFrames = frames.filter((f) => isInAppFrame(f.filename));
 
 ```ts
 const SDK_NAME: string  // 'sauron.javascript'
-const SDK_VERSION: string // '1.5.0'
+const SDK_VERSION: string // '1.6.0'
 ```
 
 The SDK identity embedded in `header.sdk` of every envelope.
@@ -1027,7 +1027,7 @@ On by default:
 | `window.onunhandledrejection` | Error item from `event.reason`, mechanism `{ type: 'onunhandledrejection', handled: false }`, level `error`. |
 | `console.log/info/warn/error/debug` | Breadcrumb, category `console`, level mapped (`warn`→`warning`, `error`→`error`, `debug`→`debug`, else `info`), message = arguments joined and truncated to 512 chars, `data: { arguments: n }`. Output is untouched. |
 | `document` click listener (capture, passive) | Breadcrumb, category `ui.click`, message = a `tag#id.class` selector (up to 3 classes). Element text and attribute values are never serialized. |
-| `history.pushState` / `replaceState` / `popstate` | Breadcrumb, type `navigation`, category `history`, `data: { from, to }` as paths. Same-path transitions are skipped. |
+| `history.pushState` / `replaceState` / `popstate` | Breadcrumb, type `navigation`, category `history`, `data: { from, to, operation }` — paths plus the direction: `push`, `replace` or `pop`. Same-path transitions are skipped. |
 | `fetch` | Breadcrumb, category `fetch`, message `METHOD url`, `data: { method, url, status_code }`, level `warning` for status >= 400. |
 | `XMLHttpRequest.prototype.open` / `send` | Breadcrumb, category `xhr`, same shape as `fetch`. |
 | `document` `visibilitychange` + window `pagehide` | Beacon flush of the pending batch on unload. |
@@ -1040,6 +1040,16 @@ Opt-in:
 | `performance: true` | A `navigation` transaction for the initial page load (Navigation Timing, captured on `load`), an `http` transaction per instrumented `fetch` (`name` = `METHOD /path`, `status` `ok`/`error`), and a `navigation` transaction per SPA route change measured over one animation frame. No-op when `document` is undefined. |
 | `screenTracking: true` | Sets the screen to the new path on each SPA History navigation, which emits a `$screen` event on change. |
 
+`operation` uses the same vocabulary as the Flutter SDK's
+`SauronNavigatorObserver` (`push` / `pop` / `replace` / `remove`), so a trail
+reads the same whichever SDK sent it. `remove` has no web equivalent and is
+never emitted here. One limit worth knowing: **a forward navigation is recorded
+as `pop`.** `history.forward()` fires the same `popstate` event as
+`history.back()` and carries nothing to separate them, so `pop` means "moved
+through history", not specifically "went back". Distinguishing them would mean
+writing to `history.state`, which the host app's router also owns — not a
+trade the SDK makes.
+
 Two guards keep the SDK from observing itself: a reentrancy flag held while SDK
 code runs, and a denylist on the DSN host. Requests the transport makes are
 therefore never turned into breadcrumbs or transactions. Wrappers are tagged, so
@@ -1116,7 +1126,7 @@ Sauron.track('upgraded', {}, { tags: { tier: 'trial' } });
 
 ```html
 <script type="module">
-  import { Sauron } from 'https://esm.sh/@edraj/sauron-browser@1.5.0';
+  import { Sauron } from 'https://esm.sh/@edraj/sauron-browser@1.6.0';
   Sauron.init({ dsn: 'https://pk_test@ingest.example.com/42' });
 </script>
 ```

package/dist/index.cjs

@@ -8,7 +8,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 
 // src/utils.ts
 var SDK_NAME = "sauron.javascript";
-var SDK_VERSION = "1.5.0";
+var SDK_VERSION = "1.6.0";
 function getGlobal() {
   return globalThis;
 }
@@ -843,12 +843,12 @@ function installHistory() {
   const loc = g2.location;
   if (!hist) return;
   let lastPath = toPath(loc?.href ?? null, loc?.href);
-  const emit = (toHref) => {
+  const emit = (toHref, operation) => {
     const to = toPath(toHref, loc?.href);
     const from = lastPath;
     lastPath = to;
     if (from === to) return;
-    withInternal(() => addNavigationBreadcrumb(from, to));
+    withInternal(() => addNavigationBreadcrumb(from, to, operation));
     if (to && navHandler) {
       try {
         navHandler(to);
@@ -859,11 +859,12 @@ function installHistory() {
   const wrap = (name) => {
     const original = hist[name];
     if (typeof original !== "function" || isWrapped(original)) return;
+    const operation = name === "pushState" ? "push" : "replace";
     hist[name] = markWrapped(function sauronHistory(...args) {
       const result = original.apply(this, args);
       if (!isInternal()) {
         const urlArg = args[2];
-        emit(urlArg != null ? String(urlArg) : loc?.href ?? null);
+        emit(urlArg != null ? String(urlArg) : loc?.href ?? null, operation);
       }
       return result;
     });
@@ -875,7 +876,7 @@ function installHistory() {
   wrap("replaceState");
   if (typeof g2.addEventListener === "function") {
     const onPopState = () => {
-      if (!isInternal()) emit(loc?.href ?? null);
+      if (!isInternal()) emit(loc?.href ?? null, "pop");
     };
     g2.addEventListener("popstate", onPopState);
     registerPatch("popstate", () => {
@@ -2226,13 +2227,13 @@ function addBreadcrumb(input, hint) {
   if (!client) return;
   client.addBreadcrumb(normalizeBreadcrumb(input), hint);
 }
-function addNavigationBreadcrumb(from, to) {
+function addNavigationBreadcrumb(from, to, operation = "push") {
   addBreadcrumb({
     type: "navigation",
     category: "history",
     level: "info",
     message: null,
-    data: { from, to }
+    data: { from, to, operation }
   });
 }