@shipeasy/sdk 4.4.0 → 5.0.0

package/README.md

@@ -69,12 +69,12 @@ try {
 }
 
 // Non-exception problems — the name is a stable identifier (it participates
-// in the issue fingerprint); variable data goes in .message() / .extras():
+// in the issue fingerprint); all variable data goes in .extras():
 if (rows.length > LIMIT) {
   see.Violation("large query")
-    .message(`got ${rows.length} rows`)
     .causes_the("search results")
-    .to("be trimmed");
+    .to("be trimmed")
+    .extras({ rows: rows.length });
 }
 
 // Expected control-flow exceptions: document them, report nothing —
@@ -82,7 +82,7 @@ if (rows.length > LIMIT) {
 try {
   return decodeFoo(blob);
 } catch (e) {
-  see.ControlFlowException(e, "because it wasn't an encoded Foo");
+  see.ControlFlowException(e).because("because it wasn't an encoded Foo");
   return decodeBar(blob);
 }
 ```
@@ -94,16 +94,19 @@ occurrence timeseries. The chain dispatches on the next microtask — no
 `fetch` on the server), spam-guarded by a 30s dedup window and a per-session
 cap.
 
-The client SDK also auto-captures uncaught exceptions, unhandled rejections,
-and network failures (fetch network errors + 5xx) into the same primitive
-(`autoCollect: { errors }`, on by default). Auto-capture is the outer safety
-net — it does not replace `see()` in catch blocks, where you know the
-consequence and it cannot.
-
-**Rules**: if you don't know the consequence, don't catch the exception. Never
-`see()` then `throw` (double counting — either handle or rethrow). Never use
-`see.Violation()` for a caught exception (you'd drop the stack). No PII or
-high-cardinality data in extras.
+The client SDK also auto-captures **network failures** (fetch network errors +
+5xx) into the same primitive (`autoCollect: { errors }`, on by default) — each
+names a specific endpoint and a specific outcome. It deliberately does **not**
+blanket-report uncaught exceptions or unhandled promise rejections: those carry
+no actionable consequence ("the page hit an error" names the plumbing, not the
+feature). Code that knows the consequence reports it explicitly with `see()` at
+the catch site.
+
+**Rules**: if you don't know the consequence, don't catch the exception. You
+**may** `see()` then re-throw — the re-thrown error links to its inner report
+as a `caused_by` chain instead of double-counting. Never use `see.Violation()`
+for a caught exception (you'd drop the stack). No PII or high-cardinality data
+in extras.
 
 ## Drop-in `<script>` loader (no bundler)
 

package/dist/client/index.d.mts

@@ -8,15 +8,13 @@ interface Consequence {
 }
 /**
  * Non-exception problem, built by `violation(name)`. A plain branded object
- * (not an Error subclass) so `.message()` can be a builder method without
- * colliding with `Error.prototype.message`.
+ * (not an Error subclass). The name is the whole identity — there is no
+ * separate message; any variable/context data belongs in `.extras()` on the
+ * see chain, never on the violation itself.
  */
 interface Violation {
     readonly __seViolation: true;
     readonly violationName: string;
-    readonly violationMessage?: string;
-    /** Attach free-form detail. Variable data goes HERE (or in extras), never in the name. */
-    message(msg: string): Violation;
 }
 /**
  * Identity of a problem that see() already reported, carried on the wire as
@@ -84,9 +82,22 @@ interface SeeChain {
     /** camelCase alias of {@link SeeChain.causes_the}. */
     causesThe(subject: string): SeeOutcomeStep;
 }
-interface SeeViolationChain extends SeeChain {
-    /** Free-form detail. Variable data goes here (or extras), never in the name. */
-    message(msg: string): SeeViolationChain;
+/**
+ * Violations share the exception consequence grammar exactly — there is no
+ * separate `.message()`. Put any variable/context data in `.extras()`.
+ */
+type SeeViolationChain = SeeChain;
+interface SeeControlFlowTail {
+    /**
+     * Optional debugging context for the expected exception. Kept on the mark for
+     * local debugging only (expected exceptions are never reported). Callable
+     * repeatedly — keys merge, later wins.
+     */
+    extras(extras: SeeExtras): SeeControlFlowTail;
+}
+interface SeeControlFlowChain {
+    /** Document why the exception is expected. The reason should start with "because". */
+    because(reason: string): SeeControlFlowTail;
 }
 
 declare global {
@@ -430,28 +441,29 @@ interface SeeApi {
     /**
      * Report a non-exception problem. Prefer passing a caught Error to `see()`
      * when one exists. The name is a stable identifier (it participates in the
-     * issue fingerprint) — variable data goes in `.message()` or `.extras()`.
+     * issue fingerprint) — variable data goes in `.extras()`, never the name.
      *
      * ```ts
      * if (rows.length > LIMIT) {
-     *   see.Violation("large query").message(`got ${rows.length} rows`)
-     *      .causes_the("search results").to("be trimmed");
+     *   see.Violation("large query")
+     *      .causes_the("search results").to("be trimmed").extras({ rows: rows.length });
      * }
      * ```
      */
     Violation(name: string): SeeViolationChain;
     /**
      * Mark an exception as expected control flow — auto-capture skips it and
-     * nothing is reported. The reason must start with "because".
+     * nothing is reported. Say why with `.because()` (reason should start with
+     * "because"); attach optional debug context with `.extras()`.
      *
      * ```ts
      * } catch (e) {
-     *   see.ControlFlowException(e, "because the blob wasn't an encoded Foo");
+     *   see.ControlFlowException(e).because("because the blob wasn't an encoded Foo");
      *   return decodeAsBar(blob);
      * }
      * ```
      */
-    ControlFlowException(err: unknown, because: string): void;
+    ControlFlowException(err: unknown): SeeControlFlowChain;
 }
 /**
  * Structured error reporter — the whole grammar hangs off this one import.
@@ -497,4 +509,4 @@ interface I18nFacade {
 }
 declare const i18n: I18nFacade;
 
-export { type AutoCollectGroups, type BootstrapPayload, type Consequence, type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type SeeApi, type SeeChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };
+export { type AutoCollectGroups, type BootstrapPayload, type Consequence, type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };

package/dist/client/index.d.ts

@@ -8,15 +8,13 @@ interface Consequence {
 }
 /**
  * Non-exception problem, built by `violation(name)`. A plain branded object
- * (not an Error subclass) so `.message()` can be a builder method without
- * colliding with `Error.prototype.message`.
+ * (not an Error subclass). The name is the whole identity — there is no
+ * separate message; any variable/context data belongs in `.extras()` on the
+ * see chain, never on the violation itself.
  */
 interface Violation {
     readonly __seViolation: true;
     readonly violationName: string;
-    readonly violationMessage?: string;
-    /** Attach free-form detail. Variable data goes HERE (or in extras), never in the name. */
-    message(msg: string): Violation;
 }
 /**
  * Identity of a problem that see() already reported, carried on the wire as
@@ -84,9 +82,22 @@ interface SeeChain {
     /** camelCase alias of {@link SeeChain.causes_the}. */
     causesThe(subject: string): SeeOutcomeStep;
 }
-interface SeeViolationChain extends SeeChain {
-    /** Free-form detail. Variable data goes here (or extras), never in the name. */
-    message(msg: string): SeeViolationChain;
+/**
+ * Violations share the exception consequence grammar exactly — there is no
+ * separate `.message()`. Put any variable/context data in `.extras()`.
+ */
+type SeeViolationChain = SeeChain;
+interface SeeControlFlowTail {
+    /**
+     * Optional debugging context for the expected exception. Kept on the mark for
+     * local debugging only (expected exceptions are never reported). Callable
+     * repeatedly — keys merge, later wins.
+     */
+    extras(extras: SeeExtras): SeeControlFlowTail;
+}
+interface SeeControlFlowChain {
+    /** Document why the exception is expected. The reason should start with "because". */
+    because(reason: string): SeeControlFlowTail;
 }
 
 declare global {
@@ -430,28 +441,29 @@ interface SeeApi {
     /**
      * Report a non-exception problem. Prefer passing a caught Error to `see()`
      * when one exists. The name is a stable identifier (it participates in the
-     * issue fingerprint) — variable data goes in `.message()` or `.extras()`.
+     * issue fingerprint) — variable data goes in `.extras()`, never the name.
      *
      * ```ts
      * if (rows.length > LIMIT) {
-     *   see.Violation("large query").message(`got ${rows.length} rows`)
-     *      .causes_the("search results").to("be trimmed");
+     *   see.Violation("large query")
+     *      .causes_the("search results").to("be trimmed").extras({ rows: rows.length });
      * }
      * ```
      */
     Violation(name: string): SeeViolationChain;
     /**
      * Mark an exception as expected control flow — auto-capture skips it and
-     * nothing is reported. The reason must start with "because".
+     * nothing is reported. Say why with `.because()` (reason should start with
+     * "because"); attach optional debug context with `.extras()`.
      *
      * ```ts
      * } catch (e) {
-     *   see.ControlFlowException(e, "because the blob wasn't an encoded Foo");
+     *   see.ControlFlowException(e).because("because the blob wasn't an encoded Foo");
      *   return decodeAsBar(blob);
      * }
      * ```
      */
-    ControlFlowException(err: unknown, because: string): void;
+    ControlFlowException(err: unknown): SeeControlFlowChain;
 }
 /**
  * Structured error reporter — the whole grammar hangs off this one import.
@@ -497,4 +509,4 @@ interface I18nFacade {
 }
 declare const i18n: I18nFacade;
 
-export { type AutoCollectGroups, type BootstrapPayload, type Consequence, type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type SeeApi, type SeeChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };
+export { type AutoCollectGroups, type BootstrapPayload, type Consequence, type ExperimentResult, FlagsClientBrowser, type FlagsClientBrowserEnv, type FlagsClientBrowserOptions, type I18nFacade, type I18nKey, type I18nRichComponents, type I18nString, type I18nTagRenderer, type I18nVariables, LABEL_MARKER_END, LABEL_MARKER_RE, LABEL_MARKER_SEP, LABEL_MARKER_START, type LabelAttrs, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyClientConfig, type ShipeasySdkBridge, type User, type Violation, _resetShipeasyForTests, attachDevtools, configureShipeasy, encodeLabelMarker, flags, getShipeasyClient, i18n, injectCorrelationHeader, isDevtoolsRequested, labelAttrs, loadDevtools, readConfigOverride, readExpOverride, readGateOverride, sameOrigin, see, shipeasy, version };

package/dist/client/index.js

@@ -126,25 +126,29 @@ function causesThe(subject) {
   };
 }
 function violation(name) {
-  const make = (msg) => ({
-    __seViolation: true,
-    violationName: String(name),
-    ...msg !== void 0 ? { violationMessage: msg } : {},
-    message(m) {
-      return make(String(m));
-    }
-  });
-  return make();
+  return { __seViolation: true, violationName: String(name) };
 }
 function isViolation(p) {
   return typeof p === "object" && p !== null && p.__seViolation === true;
 }
 var EXPECTED_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:see-expected");
-function markExpected(err, because) {
+function readExpectedMark(err) {
+  if (typeof err !== "object" || err === null) return void 0;
+  const v = err[EXPECTED_SYM];
+  return v !== void 0 && v !== null && typeof v === "object" ? v : void 0;
+}
+function markExpected(err, because, extras) {
   if (typeof err !== "object" || err === null) return;
+  const prev = readExpectedMark(err);
+  const clean = sanitizeExtras(extras);
+  const merged = prev?.extras || clean ? { ...prev?.extras, ...clean } : void 0;
+  const mark = {
+    because: String(because),
+    ...merged ? { extras: merged } : {}
+  };
   try {
     Object.defineProperty(err, EXPECTED_SYM, {
-      value: String(because),
+      value: mark,
       enumerable: false,
       configurable: true
     });
@@ -225,7 +229,7 @@ function buildSeeEvent(problem, consequence, extras, ctx, kindOverride, correlat
   let kind;
   if (isViolation(problem)) {
     errorType = problem.violationName;
-    message = problem.violationMessage ?? problem.violationName;
+    message = problem.violationName;
     stack = captureCallsiteStack();
     kind = kindOverride ?? "violation";
   } else if (problem instanceof Error) {
@@ -308,19 +312,21 @@ function startSeeChain(getProblem, dispatch) {
   return { causes_the: start, causesThe: start };
 }
 function startSeeViolationChain(name, dispatch) {
-  let msg;
-  const base = startSeeChain(
-    () => msg !== void 0 ? violation(name).message(msg) : violation(name),
-    dispatch
-  );
-  const chain = {
-    ...base,
-    message(m) {
-      msg = String(m);
-      return chain;
+  return startSeeChain(() => violation(name), dispatch);
+}
+function startControlFlowChain(err) {
+  return {
+    because(reason) {
+      markExpected(err, reason);
+      const tail = {
+        extras(x) {
+          markExpected(err, reason, x);
+          return tail;
+        }
+      };
+      return tail;
     }
   };
-  return chain;
 }
 function topStackLine(stack) {
   if (!stack) return "";
@@ -575,39 +581,11 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
     }
   }
   if (groups.errors) {
-    const origOnError = window.onerror;
-    window.onerror = (msg, source, lineno, _colno, err) => {
-      if (!isExpected(err)) {
-        const problem = err ?? (typeof msg === "string" && msg ? msg : "Unknown error");
-        reportSee(
-          problem,
-          causesThe("page").to("hit an unhandled error"),
-          {
-            source: typeof source === "string" ? source : void 0,
-            line: lineno ?? void 0
-          },
-          "uncaught"
-        );
-      }
-      if (typeof origOnError === "function") return origOnError(msg, source, lineno, _colno, err);
-      return false;
-    };
-    window.addEventListener("unhandledrejection", (e) => {
-      const reason = e.reason;
-      if (isExpected(reason)) return;
-      reportSee(
-        reason ?? "Unhandled promise rejection",
-        causesThe("page").to("hit an unhandled promise rejection"),
-        void 0,
-        "unhandled_rejection"
-      );
-    });
     const origFetch = window.fetch;
     window.fetch = async function(...args) {
       const startedAt = typeof performance !== "undefined" ? performance.now() : 0;
       const url = typeof args[0] === "string" ? args[0] : args[0].toString();
       const ignored = ignoreUrlPrefixes.some((p) => p && url.startsWith(p));
-      const bareUrl = url.split("?")[0].slice(0, 200);
       let corr;
       if (!ignored && sameOrigin(url) && typeof crypto !== "undefined" && crypto.randomUUID) {
         corr = crypto.randomUUID();
@@ -619,7 +597,7 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
       } catch (err) {
         if (!ignored && !isExpected(err)) {
           reportSee(
-            violation("NetworkError").message(`request to ${bareUrl} failed`),
+            violation("NetworkError"),
             causesThe(`request to ${endpointTemplate(url)}`).to("get no response"),
             { status: 0, url: url.slice(0, 200) },
             "network"
@@ -630,7 +608,7 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
       if (!ignored && res.status >= 500) {
         const elapsed = typeof performance !== "undefined" ? performance.now() - startedAt : 0;
         reportSee(
-          violation("Http5xx").message(`request to ${bareUrl} returned ${res.status}`),
+          violation("Http5xx"),
           causesThe(`request to ${endpointTemplate(url)}`).to("fail with a server error"),
           { status: res.status, url: url.slice(0, 200), duration_ms: Math.round(elapsed) },
           "network",
@@ -1409,7 +1387,7 @@ var see = Object.assign(
   (problem) => startSeeChain(() => problem, dispatchSee),
   {
     Violation: (name) => startSeeViolationChain(name, dispatchSee),
-    ControlFlowException: markExpected
+    ControlFlowException: (err) => startControlFlowChain(err)
   }
 );
 var LABEL_MARKER_START = "\uFFF9";

package/dist/client/index.mjs

@@ -78,25 +78,29 @@ function causesThe(subject) {
   };
 }
 function violation(name) {
-  const make = (msg) => ({
-    __seViolation: true,
-    violationName: String(name),
-    ...msg !== void 0 ? { violationMessage: msg } : {},
-    message(m) {
-      return make(String(m));
-    }
-  });
-  return make();
+  return { __seViolation: true, violationName: String(name) };
 }
 function isViolation(p) {
   return typeof p === "object" && p !== null && p.__seViolation === true;
 }
 var EXPECTED_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:see-expected");
-function markExpected(err, because) {
+function readExpectedMark(err) {
+  if (typeof err !== "object" || err === null) return void 0;
+  const v = err[EXPECTED_SYM];
+  return v !== void 0 && v !== null && typeof v === "object" ? v : void 0;
+}
+function markExpected(err, because, extras) {
   if (typeof err !== "object" || err === null) return;
+  const prev = readExpectedMark(err);
+  const clean = sanitizeExtras(extras);
+  const merged = prev?.extras || clean ? { ...prev?.extras, ...clean } : void 0;
+  const mark = {
+    because: String(because),
+    ...merged ? { extras: merged } : {}
+  };
   try {
     Object.defineProperty(err, EXPECTED_SYM, {
-      value: String(because),
+      value: mark,
       enumerable: false,
       configurable: true
     });
@@ -177,7 +181,7 @@ function buildSeeEvent(problem, consequence, extras, ctx, kindOverride, correlat
   let kind;
   if (isViolation(problem)) {
     errorType = problem.violationName;
-    message = problem.violationMessage ?? problem.violationName;
+    message = problem.violationName;
     stack = captureCallsiteStack();
     kind = kindOverride ?? "violation";
   } else if (problem instanceof Error) {
@@ -260,19 +264,21 @@ function startSeeChain(getProblem, dispatch) {
   return { causes_the: start, causesThe: start };
 }
 function startSeeViolationChain(name, dispatch) {
-  let msg;
-  const base = startSeeChain(
-    () => msg !== void 0 ? violation(name).message(msg) : violation(name),
-    dispatch
-  );
-  const chain = {
-    ...base,
-    message(m) {
-      msg = String(m);
-      return chain;
+  return startSeeChain(() => violation(name), dispatch);
+}
+function startControlFlowChain(err) {
+  return {
+    because(reason) {
+      markExpected(err, reason);
+      const tail = {
+        extras(x) {
+          markExpected(err, reason, x);
+          return tail;
+        }
+      };
+      return tail;
     }
   };
-  return chain;
 }
 function topStackLine(stack) {
   if (!stack) return "";
@@ -527,39 +533,11 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
     }
   }
   if (groups.errors) {
-    const origOnError = window.onerror;
-    window.onerror = (msg, source, lineno, _colno, err) => {
-      if (!isExpected(err)) {
-        const problem = err ?? (typeof msg === "string" && msg ? msg : "Unknown error");
-        reportSee(
-          problem,
-          causesThe("page").to("hit an unhandled error"),
-          {
-            source: typeof source === "string" ? source : void 0,
-            line: lineno ?? void 0
-          },
-          "uncaught"
-        );
-      }
-      if (typeof origOnError === "function") return origOnError(msg, source, lineno, _colno, err);
-      return false;
-    };
-    window.addEventListener("unhandledrejection", (e) => {
-      const reason = e.reason;
-      if (isExpected(reason)) return;
-      reportSee(
-        reason ?? "Unhandled promise rejection",
-        causesThe("page").to("hit an unhandled promise rejection"),
-        void 0,
-        "unhandled_rejection"
-      );
-    });
     const origFetch = window.fetch;
     window.fetch = async function(...args) {
       const startedAt = typeof performance !== "undefined" ? performance.now() : 0;
       const url = typeof args[0] === "string" ? args[0] : args[0].toString();
       const ignored = ignoreUrlPrefixes.some((p) => p && url.startsWith(p));
-      const bareUrl = url.split("?")[0].slice(0, 200);
       let corr;
       if (!ignored && sameOrigin(url) && typeof crypto !== "undefined" && crypto.randomUUID) {
         corr = crypto.randomUUID();
@@ -571,7 +549,7 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
       } catch (err) {
         if (!ignored && !isExpected(err)) {
           reportSee(
-            violation("NetworkError").message(`request to ${bareUrl} failed`),
+            violation("NetworkError"),
             causesThe(`request to ${endpointTemplate(url)}`).to("get no response"),
             { status: 0, url: url.slice(0, 200) },
             "network"
@@ -582,7 +560,7 @@ function installAutoGuardrails(buffer, userId, anonId, groups, reportSee, ignore
       if (!ignored && res.status >= 500) {
         const elapsed = typeof performance !== "undefined" ? performance.now() - startedAt : 0;
         reportSee(
-          violation("Http5xx").message(`request to ${bareUrl} returned ${res.status}`),
+          violation("Http5xx"),
           causesThe(`request to ${endpointTemplate(url)}`).to("fail with a server error"),
           { status: res.status, url: url.slice(0, 200), duration_ms: Math.round(elapsed) },
           "network",
@@ -1361,7 +1339,7 @@ var see = Object.assign(
   (problem) => startSeeChain(() => problem, dispatchSee),
   {
     Violation: (name) => startSeeViolationChain(name, dispatchSee),
-    ControlFlowException: markExpected
+    ControlFlowException: (err) => startControlFlowChain(err)
   }
 );
 var LABEL_MARKER_START = "\uFFF9";

package/dist/next/index.d.mts

@@ -0,0 +1,50 @@
+import { NextRequest, NextFetchEvent, NextResponse } from 'next/server';
+
+/** The first-party cookie that carries the stable anonymous bucketing unit. */
+declare const ANON_ID_COOKIE = "__se_anon_id";
+interface AnonIdResult {
+    /** The stable bucketing id for this request (existing cookie, or freshly minted). */
+    anonId: string;
+    /** True when there was no valid cookie and we minted a new id (must be persisted). */
+    minted: boolean;
+}
+/**
+ * Read + validate the `__se_anon_id` cookie, minting one when absent/invalid.
+ * When `requestHeaders` is supplied and we mint, the new id is appended to the
+ * forwarded `cookie` header so THIS request's SSR (and any inner middleware)
+ * already sees it. Pair with {@link commitAnonId} to persist a minted id.
+ */
+declare function readOrMintAnonId(req: NextRequest, requestHeaders?: Headers): AnonIdResult;
+/**
+ * Persist a freshly-minted anon id as a first-party cookie on `res` (no-op when
+ * `minted` is false). Non-httpOnly by contract — the browser SDK reads it via
+ * `document.cookie` to bucket identically to SSR. Returns `res` for chaining.
+ */
+declare function commitAnonId(res: NextResponse, result: AnonIdResult, req: NextRequest): NextResponse;
+type ShipeasyMiddleware = (req: NextRequest, event: NextFetchEvent) => NextResponse | Response | undefined | null | void | Promise<NextResponse | Response | undefined | null | void>;
+/**
+ * Wrap an existing Next middleware so every matched request also mints the
+ * shared `__se_anon_id` cookie. Your middleware runs against a request that
+ * already carries the id (its own logic + SSR see it), and the cookie is set on
+ * whatever response it returns. Called with no argument, returns a standalone
+ * mint-only middleware (what the default {@link middleware} export uses).
+ *
+ * If your middleware forwards custom request headers via
+ * `NextResponse.next({ request: { headers } })`, prefer composing the
+ * {@link readOrMintAnonId} + {@link commitAnonId} primitives inside it — that
+ * preserves your forwarding verbatim; this wrapper rebuilds the pass-through
+ * `next()` and so would drop request-header forwarding the inner handler added.
+ */
+declare function withShipeasy(handler?: ShipeasyMiddleware): ShipeasyMiddleware;
+/** Drop-in middleware: `export { middleware, config } from "@shipeasy/sdk/next";` */
+declare const middleware: ShipeasyMiddleware;
+/**
+ * Matcher for the drop-in middleware: every HTML route (landing + app), skipping
+ * Next internals, API routes, and static files (any path segment with a dot).
+ * Define your own `config` if you need a narrower scope.
+ */
+declare const config: {
+    matcher: string[];
+};
+
+export { ANON_ID_COOKIE, type AnonIdResult, type ShipeasyMiddleware, commitAnonId, config, middleware, readOrMintAnonId, withShipeasy };

package/dist/next/index.d.ts

@@ -0,0 +1,50 @@
+import { NextRequest, NextFetchEvent, NextResponse } from 'next/server';
+
+/** The first-party cookie that carries the stable anonymous bucketing unit. */
+declare const ANON_ID_COOKIE = "__se_anon_id";
+interface AnonIdResult {
+    /** The stable bucketing id for this request (existing cookie, or freshly minted). */
+    anonId: string;
+    /** True when there was no valid cookie and we minted a new id (must be persisted). */
+    minted: boolean;
+}
+/**
+ * Read + validate the `__se_anon_id` cookie, minting one when absent/invalid.
+ * When `requestHeaders` is supplied and we mint, the new id is appended to the
+ * forwarded `cookie` header so THIS request's SSR (and any inner middleware)
+ * already sees it. Pair with {@link commitAnonId} to persist a minted id.
+ */
+declare function readOrMintAnonId(req: NextRequest, requestHeaders?: Headers): AnonIdResult;
+/**
+ * Persist a freshly-minted anon id as a first-party cookie on `res` (no-op when
+ * `minted` is false). Non-httpOnly by contract — the browser SDK reads it via
+ * `document.cookie` to bucket identically to SSR. Returns `res` for chaining.
+ */
+declare function commitAnonId(res: NextResponse, result: AnonIdResult, req: NextRequest): NextResponse;
+type ShipeasyMiddleware = (req: NextRequest, event: NextFetchEvent) => NextResponse | Response | undefined | null | void | Promise<NextResponse | Response | undefined | null | void>;
+/**
+ * Wrap an existing Next middleware so every matched request also mints the
+ * shared `__se_anon_id` cookie. Your middleware runs against a request that
+ * already carries the id (its own logic + SSR see it), and the cookie is set on
+ * whatever response it returns. Called with no argument, returns a standalone
+ * mint-only middleware (what the default {@link middleware} export uses).
+ *
+ * If your middleware forwards custom request headers via
+ * `NextResponse.next({ request: { headers } })`, prefer composing the
+ * {@link readOrMintAnonId} + {@link commitAnonId} primitives inside it — that
+ * preserves your forwarding verbatim; this wrapper rebuilds the pass-through
+ * `next()` and so would drop request-header forwarding the inner handler added.
+ */
+declare function withShipeasy(handler?: ShipeasyMiddleware): ShipeasyMiddleware;
+/** Drop-in middleware: `export { middleware, config } from "@shipeasy/sdk/next";` */
+declare const middleware: ShipeasyMiddleware;
+/**
+ * Matcher for the drop-in middleware: every HTML route (landing + app), skipping
+ * Next internals, API routes, and static files (any path segment with a dot).
+ * Define your own `config` if you need a narrower scope.
+ */
+declare const config: {
+    matcher: string[];
+};
+
+export { ANON_ID_COOKIE, type AnonIdResult, type ShipeasyMiddleware, commitAnonId, config, middleware, readOrMintAnonId, withShipeasy };

package/dist/next/index.js

@@ -0,0 +1,97 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/next/index.ts
+var next_exports = {};
+__export(next_exports, {
+  ANON_ID_COOKIE: () => ANON_ID_COOKIE,
+  commitAnonId: () => commitAnonId,
+  config: () => config,
+  middleware: () => middleware,
+  readOrMintAnonId: () => readOrMintAnonId,
+  withShipeasy: () => withShipeasy
+});
+module.exports = __toCommonJS(next_exports);
+var import_server = require("next/server");
+var ANON_ID_COOKIE = "__se_anon_id";
+var ANON_ID_RX = /^[A-Za-z0-9_-]{1,64}$/;
+var ANON_ID_MAX_AGE = 60 * 60 * 24 * 365;
+function mint() {
+  return typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `anon_${Math.random().toString(36).slice(2)}`;
+}
+function appendCookie(headers, name, value) {
+  const existing = headers.get("cookie") ?? "";
+  const parts = existing.split(";").map((c) => c.trim()).filter((c) => c && !c.startsWith(`${name}=`));
+  parts.push(`${name}=${value}`);
+  headers.set("cookie", parts.join("; "));
+}
+function readOrMintAnonId(req, requestHeaders) {
+  const raw = req.cookies.get(ANON_ID_COOKIE)?.value;
+  const valid = !!raw && ANON_ID_RX.test(raw);
+  const anonId = valid ? raw : mint();
+  const minted = !valid;
+  if (minted && requestHeaders) appendCookie(requestHeaders, ANON_ID_COOKIE, anonId);
+  return { anonId, minted };
+}
+function commitAnonId(res, result, req) {
+  if (result.minted) {
+    res.cookies.set(ANON_ID_COOKIE, result.anonId, {
+      httpOnly: false,
+      secure: req.nextUrl.protocol === "https:",
+      sameSite: "lax",
+      path: "/",
+      maxAge: ANON_ID_MAX_AGE
+    });
+  }
+  return res;
+}
+function withShipeasy(handler) {
+  return async (req, event) => {
+    const requestHeaders = new Headers(req.headers);
+    const anon = readOrMintAnonId(req, requestHeaders);
+    if (anon.minted) req.cookies.set(ANON_ID_COOKIE, anon.anonId);
+    const userRes = handler ? await handler(req, event) : void 0;
+    const isPassThrough = !userRes || userRes instanceof import_server.NextResponse && userRes.headers.get("x-middleware-next") === "1";
+    if (isPassThrough) {
+      const res2 = import_server.NextResponse.next({ request: { headers: requestHeaders } });
+      if (userRes instanceof import_server.NextResponse) {
+        userRes.cookies.getAll().forEach((c) => res2.cookies.set(c));
+        userRes.headers.forEach((v, k) => {
+          if (k !== "x-middleware-next") res2.headers.set(k, v);
+        });
+      }
+      return commitAnonId(res2, anon, req);
+    }
+    const res = userRes instanceof import_server.NextResponse ? userRes : userRes instanceof Response ? new import_server.NextResponse(userRes.body, userRes) : import_server.NextResponse.next({ request: { headers: requestHeaders } });
+    return commitAnonId(res, anon, req);
+  };
+}
+var middleware = withShipeasy();
+var config = {
+  matcher: ["/((?!api/|_next/|.*\\..*).*)"]
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ANON_ID_COOKIE,
+  commitAnonId,
+  config,
+  middleware,
+  readOrMintAnonId,
+  withShipeasy
+});

package/dist/next/index.mjs

@@ -0,0 +1,67 @@
+// src/next/index.ts
+import { NextResponse } from "next/server";
+var ANON_ID_COOKIE = "__se_anon_id";
+var ANON_ID_RX = /^[A-Za-z0-9_-]{1,64}$/;
+var ANON_ID_MAX_AGE = 60 * 60 * 24 * 365;
+function mint() {
+  return typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `anon_${Math.random().toString(36).slice(2)}`;
+}
+function appendCookie(headers, name, value) {
+  const existing = headers.get("cookie") ?? "";
+  const parts = existing.split(";").map((c) => c.trim()).filter((c) => c && !c.startsWith(`${name}=`));
+  parts.push(`${name}=${value}`);
+  headers.set("cookie", parts.join("; "));
+}
+function readOrMintAnonId(req, requestHeaders) {
+  const raw = req.cookies.get(ANON_ID_COOKIE)?.value;
+  const valid = !!raw && ANON_ID_RX.test(raw);
+  const anonId = valid ? raw : mint();
+  const minted = !valid;
+  if (minted && requestHeaders) appendCookie(requestHeaders, ANON_ID_COOKIE, anonId);
+  return { anonId, minted };
+}
+function commitAnonId(res, result, req) {
+  if (result.minted) {
+    res.cookies.set(ANON_ID_COOKIE, result.anonId, {
+      httpOnly: false,
+      secure: req.nextUrl.protocol === "https:",
+      sameSite: "lax",
+      path: "/",
+      maxAge: ANON_ID_MAX_AGE
+    });
+  }
+  return res;
+}
+function withShipeasy(handler) {
+  return async (req, event) => {
+    const requestHeaders = new Headers(req.headers);
+    const anon = readOrMintAnonId(req, requestHeaders);
+    if (anon.minted) req.cookies.set(ANON_ID_COOKIE, anon.anonId);
+    const userRes = handler ? await handler(req, event) : void 0;
+    const isPassThrough = !userRes || userRes instanceof NextResponse && userRes.headers.get("x-middleware-next") === "1";
+    if (isPassThrough) {
+      const res2 = NextResponse.next({ request: { headers: requestHeaders } });
+      if (userRes instanceof NextResponse) {
+        userRes.cookies.getAll().forEach((c) => res2.cookies.set(c));
+        userRes.headers.forEach((v, k) => {
+          if (k !== "x-middleware-next") res2.headers.set(k, v);
+        });
+      }
+      return commitAnonId(res2, anon, req);
+    }
+    const res = userRes instanceof NextResponse ? userRes : userRes instanceof Response ? new NextResponse(userRes.body, userRes) : NextResponse.next({ request: { headers: requestHeaders } });
+    return commitAnonId(res, anon, req);
+  };
+}
+var middleware = withShipeasy();
+var config = {
+  matcher: ["/((?!api/|_next/|.*\\..*).*)"]
+};
+export {
+  ANON_ID_COOKIE,
+  commitAnonId,
+  config,
+  middleware,
+  readOrMintAnonId,
+  withShipeasy
+};

package/dist/server/index.d.mts

@@ -10,15 +10,13 @@ interface Consequence {
 }
 /**
  * Non-exception problem, built by `violation(name)`. A plain branded object
- * (not an Error subclass) so `.message()` can be a builder method without
- * colliding with `Error.prototype.message`.
+ * (not an Error subclass). The name is the whole identity — there is no
+ * separate message; any variable/context data belongs in `.extras()` on the
+ * see chain, never on the violation itself.
  */
 interface Violation {
     readonly __seViolation: true;
     readonly violationName: string;
-    readonly violationMessage?: string;
-    /** Attach free-form detail. Variable data goes HERE (or in extras), never in the name. */
-    message(msg: string): Violation;
 }
 /**
  * Identity of a problem that see() already reported, carried on the wire as
@@ -87,9 +85,22 @@ interface SeeChain {
     /** camelCase alias of {@link SeeChain.causes_the}. */
     causesThe(subject: string): SeeOutcomeStep;
 }
-interface SeeViolationChain extends SeeChain {
-    /** Free-form detail. Variable data goes here (or extras), never in the name. */
-    message(msg: string): SeeViolationChain;
+/**
+ * Violations share the exception consequence grammar exactly — there is no
+ * separate `.message()`. Put any variable/context data in `.extras()`.
+ */
+type SeeViolationChain = SeeChain;
+interface SeeControlFlowTail {
+    /**
+     * Optional debugging context for the expected exception. Kept on the mark for
+     * local debugging only (expected exceptions are never reported). Callable
+     * repeatedly — keys merge, later wins.
+     */
+    extras(extras: SeeExtras): SeeControlFlowTail;
+}
+interface SeeControlFlowChain {
+    /** Document why the exception is expected. The reason should start with "because". */
+    because(reason: string): SeeControlFlowTail;
 }
 
 declare const version = "4.0.0";
@@ -367,20 +378,26 @@ interface SeeApi {
     /**
      * Report a non-exception problem. Prefer passing a caught Error to `see()`
      * when one exists. The name is a stable identifier (it participates in the
-     * issue fingerprint) — variable data goes in `.message()` or `.extras()`.
+     * issue fingerprint) — variable data goes in `.extras()`, never the name.
      *
      * ```ts
      * if (results.length > LIMIT) {
-     *   see.Violation("large query").causes_the("search results").to("be trimmed");
+     *   see.Violation("large query")
+     *      .causes_the("search results").to("be trimmed").extras({ rows: results.length });
      * }
      * ```
      */
     Violation(name: string): SeeViolationChain;
     /**
      * Mark an exception as expected control flow — documents the expectation and
-     * reports nothing. The reason must start with "because".
+     * reports nothing. Say why with `.because()` (reason should start with
+     * "because"); attach optional debug context with `.extras()`.
+     *
+     * ```ts
+     * see.ControlFlowException(e).because("because the metric may not exist yet");
+     * ```
      */
-    ControlFlowException(err: unknown, because: string): void;
+    ControlFlowException(err: unknown): SeeControlFlowChain;
 }
 /**
  * Structured error reporter — the whole grammar hangs off this one import.
@@ -389,4 +406,4 @@ interface SeeApi {
  */
 declare const see: SeeApi;
 
-export { ANON_ID_COOKIE, type BootstrapHtmlOptions, type BootstrapPayload, type Consequence, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type I18nForRequest, type LabelFile, type SeeApi, type SeeChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type User, type Violation, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, isExpected, see, seeContext, shipeasy, version };
+export { ANON_ID_COOKIE, type BootstrapHtmlOptions, type BootstrapPayload, type Consequence, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type I18nForRequest, type LabelFile, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type User, type Violation, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, isExpected, see, seeContext, shipeasy, version };

package/dist/server/index.d.ts

@@ -10,15 +10,13 @@ interface Consequence {
 }
 /**
  * Non-exception problem, built by `violation(name)`. A plain branded object
- * (not an Error subclass) so `.message()` can be a builder method without
- * colliding with `Error.prototype.message`.
+ * (not an Error subclass). The name is the whole identity — there is no
+ * separate message; any variable/context data belongs in `.extras()` on the
+ * see chain, never on the violation itself.
  */
 interface Violation {
     readonly __seViolation: true;
     readonly violationName: string;
-    readonly violationMessage?: string;
-    /** Attach free-form detail. Variable data goes HERE (or in extras), never in the name. */
-    message(msg: string): Violation;
 }
 /**
  * Identity of a problem that see() already reported, carried on the wire as
@@ -87,9 +85,22 @@ interface SeeChain {
     /** camelCase alias of {@link SeeChain.causes_the}. */
     causesThe(subject: string): SeeOutcomeStep;
 }
-interface SeeViolationChain extends SeeChain {
-    /** Free-form detail. Variable data goes here (or extras), never in the name. */
-    message(msg: string): SeeViolationChain;
+/**
+ * Violations share the exception consequence grammar exactly — there is no
+ * separate `.message()`. Put any variable/context data in `.extras()`.
+ */
+type SeeViolationChain = SeeChain;
+interface SeeControlFlowTail {
+    /**
+     * Optional debugging context for the expected exception. Kept on the mark for
+     * local debugging only (expected exceptions are never reported). Callable
+     * repeatedly — keys merge, later wins.
+     */
+    extras(extras: SeeExtras): SeeControlFlowTail;
+}
+interface SeeControlFlowChain {
+    /** Document why the exception is expected. The reason should start with "because". */
+    because(reason: string): SeeControlFlowTail;
 }
 
 declare const version = "4.0.0";
@@ -367,20 +378,26 @@ interface SeeApi {
     /**
      * Report a non-exception problem. Prefer passing a caught Error to `see()`
      * when one exists. The name is a stable identifier (it participates in the
-     * issue fingerprint) — variable data goes in `.message()` or `.extras()`.
+     * issue fingerprint) — variable data goes in `.extras()`, never the name.
      *
      * ```ts
      * if (results.length > LIMIT) {
-     *   see.Violation("large query").causes_the("search results").to("be trimmed");
+     *   see.Violation("large query")
+     *      .causes_the("search results").to("be trimmed").extras({ rows: results.length });
      * }
      * ```
      */
     Violation(name: string): SeeViolationChain;
     /**
      * Mark an exception as expected control flow — documents the expectation and
-     * reports nothing. The reason must start with "because".
+     * reports nothing. Say why with `.because()` (reason should start with
+     * "because"); attach optional debug context with `.extras()`.
+     *
+     * ```ts
+     * see.ControlFlowException(e).because("because the metric may not exist yet");
+     * ```
      */
-    ControlFlowException(err: unknown, because: string): void;
+    ControlFlowException(err: unknown): SeeControlFlowChain;
 }
 /**
  * Structured error reporter — the whole grammar hangs off this one import.
@@ -389,4 +406,4 @@ interface SeeApi {
  */
 declare const see: SeeApi;
 
-export { ANON_ID_COOKIE, type BootstrapHtmlOptions, type BootstrapPayload, type Consequence, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type I18nForRequest, type LabelFile, type SeeApi, type SeeChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type User, type Violation, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, isExpected, see, seeContext, shipeasy, version };
+export { ANON_ID_COOKIE, type BootstrapHtmlOptions, type BootstrapPayload, type Consequence, type ExperimentResult, type FetchLabelsOptions, FlagsClient, type FlagsClientEnv, type FlagsClientOptions, type I18nForRequest, type LabelFile, type SeeApi, type SeeChain, type SeeControlFlowChain, type SeeErrorEvent, type SeeExtras, type SeeKind, type SeeViolationChain, type ShipeasyServerConfig, type ShipeasyServerHandle, type User, type Violation, _resetShipeasyServerForTests, configureShipeasyServer, fetchLabelsForSSR, flags, getBootstrapHtml, getShipeasyServerClient, i18n, isExpected, see, seeContext, shipeasy, version };

package/dist/server/index.js

@@ -128,25 +128,29 @@ function causesThe(subject) {
   };
 }
 function violation(name) {
-  const make = (msg) => ({
-    __seViolation: true,
-    violationName: String(name),
-    ...msg !== void 0 ? { violationMessage: msg } : {},
-    message(m) {
-      return make(String(m));
-    }
-  });
-  return make();
+  return { __seViolation: true, violationName: String(name) };
 }
 function isViolation(p) {
   return typeof p === "object" && p !== null && p.__seViolation === true;
 }
 var EXPECTED_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:see-expected");
-function markExpected(err, because) {
+function readExpectedMark(err) {
+  if (typeof err !== "object" || err === null) return void 0;
+  const v = err[EXPECTED_SYM];
+  return v !== void 0 && v !== null && typeof v === "object" ? v : void 0;
+}
+function markExpected(err, because, extras) {
   if (typeof err !== "object" || err === null) return;
+  const prev = readExpectedMark(err);
+  const clean = sanitizeExtras(extras);
+  const merged = prev?.extras || clean ? { ...prev?.extras, ...clean } : void 0;
+  const mark = {
+    because: String(because),
+    ...merged ? { extras: merged } : {}
+  };
   try {
     Object.defineProperty(err, EXPECTED_SYM, {
-      value: String(because),
+      value: mark,
       enumerable: false,
       configurable: true
     });
@@ -227,7 +231,7 @@ function buildSeeEvent(problem, consequence, extras, ctx, kindOverride, correlat
   let kind;
   if (isViolation(problem)) {
     errorType = problem.violationName;
-    message = problem.violationMessage ?? problem.violationName;
+    message = problem.violationName;
     stack = captureCallsiteStack();
     kind = kindOverride ?? "violation";
   } else if (problem instanceof Error) {
@@ -310,19 +314,21 @@ function startSeeChain(getProblem, dispatch) {
   return { causes_the: start, causesThe: start };
 }
 function startSeeViolationChain(name, dispatch) {
-  let msg;
-  const base = startSeeChain(
-    () => msg !== void 0 ? violation(name).message(msg) : violation(name),
-    dispatch
-  );
-  const chain = {
-    ...base,
-    message(m) {
-      msg = String(m);
-      return chain;
+  return startSeeChain(() => violation(name), dispatch);
+}
+function startControlFlowChain(err) {
+  return {
+    because(reason) {
+      markExpected(err, reason);
+      const tail = {
+        extras(x) {
+          markExpected(err, reason, x);
+          return tail;
+        }
+      };
+      return tail;
     }
   };
-  return chain;
 }
 function topStackLine(stack) {
   if (!stack) return "";
@@ -1027,7 +1033,7 @@ var see = Object.assign(
   (problem) => startSeeChain(() => problem, dispatchSee),
   {
     Violation: (name) => startSeeViolationChain(name, dispatchSee),
-    ControlFlowException: markExpected
+    ControlFlowException: (err) => startControlFlowChain(err)
   }
 );
 // Annotate the CommonJS export names for ESM import in node:

package/dist/server/index.mjs

@@ -81,25 +81,29 @@ function causesThe(subject) {
   };
 }
 function violation(name) {
-  const make = (msg) => ({
-    __seViolation: true,
-    violationName: String(name),
-    ...msg !== void 0 ? { violationMessage: msg } : {},
-    message(m) {
-      return make(String(m));
-    }
-  });
-  return make();
+  return { __seViolation: true, violationName: String(name) };
 }
 function isViolation(p) {
   return typeof p === "object" && p !== null && p.__seViolation === true;
 }
 var EXPECTED_SYM = /* @__PURE__ */ Symbol.for("@shipeasy/sdk:see-expected");
-function markExpected(err, because) {
+function readExpectedMark(err) {
+  if (typeof err !== "object" || err === null) return void 0;
+  const v = err[EXPECTED_SYM];
+  return v !== void 0 && v !== null && typeof v === "object" ? v : void 0;
+}
+function markExpected(err, because, extras) {
   if (typeof err !== "object" || err === null) return;
+  const prev = readExpectedMark(err);
+  const clean = sanitizeExtras(extras);
+  const merged = prev?.extras || clean ? { ...prev?.extras, ...clean } : void 0;
+  const mark = {
+    because: String(because),
+    ...merged ? { extras: merged } : {}
+  };
   try {
     Object.defineProperty(err, EXPECTED_SYM, {
-      value: String(because),
+      value: mark,
       enumerable: false,
       configurable: true
     });
@@ -180,7 +184,7 @@ function buildSeeEvent(problem, consequence, extras, ctx, kindOverride, correlat
   let kind;
   if (isViolation(problem)) {
     errorType = problem.violationName;
-    message = problem.violationMessage ?? problem.violationName;
+    message = problem.violationName;
     stack = captureCallsiteStack();
     kind = kindOverride ?? "violation";
   } else if (problem instanceof Error) {
@@ -263,19 +267,21 @@ function startSeeChain(getProblem, dispatch) {
   return { causes_the: start, causesThe: start };
 }
 function startSeeViolationChain(name, dispatch) {
-  let msg;
-  const base = startSeeChain(
-    () => msg !== void 0 ? violation(name).message(msg) : violation(name),
-    dispatch
-  );
-  const chain = {
-    ...base,
-    message(m) {
-      msg = String(m);
-      return chain;
+  return startSeeChain(() => violation(name), dispatch);
+}
+function startControlFlowChain(err) {
+  return {
+    because(reason) {
+      markExpected(err, reason);
+      const tail = {
+        extras(x) {
+          markExpected(err, reason, x);
+          return tail;
+        }
+      };
+      return tail;
     }
   };
-  return chain;
 }
 function topStackLine(stack) {
   if (!stack) return "";
@@ -980,7 +986,7 @@ var see = Object.assign(
   (problem) => startSeeChain(() => problem, dispatchSee),
   {
     Violation: (name) => startSeeViolationChain(name, dispatchSee),
-    ControlFlowException: markExpected
+    ControlFlowException: (err) => startControlFlowChain(err)
   }
 );
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipeasy/sdk",
-  "version": "4.4.0",
+  "version": "5.0.0",
   "description": "Shipeasy SDK — feature gates, runtime configs, experiments, and metrics for the Shipeasy hosted service.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://shipeasy.ai",
@@ -21,6 +21,9 @@
       ],
       "server": [
         "./dist/server/index.d.ts"
+      ],
+      "next": [
+        "./dist/next/index.d.ts"
       ]
     }
   },
@@ -39,11 +42,17 @@
       "types": "./dist/client/index.d.ts",
       "default": "./dist/client/index.js"
     },
+    "./next": {
+      "types": "./dist/next/index.d.ts",
+      "import": "./dist/next/index.mjs",
+      "default": "./dist/next/index.js"
+    },
     "./templates/*": "./templates/*.js"
   },
   "files": [
     "dist/server/",
     "dist/client/",
+    "dist/next/",
     "templates/",
     "LICENSE",
     "README.md"
@@ -58,9 +67,18 @@
   "dependencies": {
     "murmurhash-js": "^1.0.0"
   },
+  "peerDependencies": {
+    "next": ">=13"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/murmurhash-js": "^1.0.6",
     "@types/node": "^20.0.0",
+    "next": "^16.2.3",
     "tsup": "^8.3.0",
     "typescript": "^5.7.4",
     "vitest": "^2.1.0",