@voltro/client 0.60.0 → 0.61.0

package/CHANGELOG.md

@@ -39,6 +39,31 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.61.0] — 2026-08-31
+
+### ⚠ BREAKING
+
+- **@voltro/client, @voltro/web, @voltro/cli** — `RpcError.kind` now distinguishes transport, handler, client, and unknown failures; manually emitted events must add the field, while `useConnectionStatus` now degrades only for transport failures and clears on the next rpc success.
+
+  **`voltro update` carries you across this** — codemod `0.61.0/01_rpc_errors_have_kinds`. If you pin versions by hand and never run it, print the notes without changing anything: `voltro update --codemods-only --from <your current version> --dry-run` (this one ships in 0.61.0).
+- **@voltro/plugin-sentry, @voltro/cli** — Browser RPC spans now join the active page/navigation transaction and link to the Effect/server trace instead of creating one root transaction per call; `tracesSampleRate`, `browserTracing`, and the new `rpcSpans` switch control the resulting browser trace volume.
+
+  **`voltro update` carries you across this** — codemod `0.61.0/02_sentry_rpc_spans_join_page`. If you pin versions by hand and never run it, print the notes without changing anything: `voltro update --codemods-only --from <your current version> --dry-run` (this one ships in 0.61.0).
+
+### Fixed
+
+- **@voltro/cli** — **Six SSR failure sites report to Sentry, not three.**
+
+  0.60.0 gave the web server its own Sentry and wired the three loud sites: the SSR shell throw, the SPA layout shell throw, and the general render error (which covers a loader throw). The docs said "shell throw, loader throw, PPR/SWR refresh" — and an enumeration in a claim is read as exhaustive.
+
+  The other three were `warn`-level and reported to nobody: a failed PPR hole pass, a failed background SWR refresh, and a `not-found.tsx` that throws while rendering. They are quieter because the request still serves something — stale HTML, an unfilled hole, a plain 404 — which says something about the REQUEST and nothing about who else could find out. The answer to that is nobody: none of them reaches a browser boundary, so the pod's stdout was the only record.
+
+  They carry their own `voltro.stage` (`not-found-render`, `ppr-holes`, `swr-refresh`), so a quota-conscious project can drop them by stage without losing the three that fail the request.
+
+  `webSentry.test.ts` now fails if a render-path `log.error`/`log.warn` gains no reporter beside it — the property, rather than the six call sites.
+
+---
+
 ## [0.60.0] — 2026-08-31
 
 ### ⚠ BREAKING

package/dist/index.d.ts

@@ -602,8 +602,8 @@ export declare interface ClientTraceEvent {
     /** W3C trace id (32 hex) of the call the client just started. */
     readonly traceId: string;
     /** W3C span id (16 hex) of the client span — the parent the server
-     *  continues from. Lets a vendor integration (Sentry) place the
-     *  browser-side span in the SAME trace tree as the server transaction. */
+     *  continues from. Lets a vendor integration correlate browser work to the
+     *  server trace without changing the browser span's page-owned parent. */
     readonly spanId: string;
     /** `'mutation'` | `'action'` | `'subscription'` — which surface started it. */
     readonly source: 'mutation' | 'action' | 'subscription';
@@ -686,7 +686,7 @@ export declare interface ConnectionState {
     readonly status: ConnectionStatus;
     /** `navigator.onLine` (true during SSR — nothing better is knowable there). */
     readonly online: boolean;
-    /** Consecutive rpc failures with no success in between. 0 when healthy. */
+    /** Consecutive transport failures with no server response or rpc success in between. */
     readonly failureCount: number;
     /** When the most recent failure was observed. */
     readonly lastFailureAt: number | undefined;
@@ -2497,10 +2497,14 @@ export declare interface RpcError {
     /** The raw error value. May be a Schema.TaggedError instance, a plain
      *  Error, an unknown thrown value. Pattern-match on `_tag` for typed errors. */
     readonly error: unknown;
-    /** Trace id of the failed call — the SAME id the server logged + the
-     *  dashboards show. Lets a listener (or `DefaultErrorFallback`) point at
-     *  `voltro logs --trace <id>`. Present when a client span was active
-     *  (always, in practice — Effect's native tracer is ambient). */
+    /** Failure origin. Use `transport` for connection-level UX; `handler` means
+     *  the rpc returned a declared failure; `client` is framework work that
+     *  failed locally; `unknown` is deliberately unclassified. */
+    readonly kind: RpcErrorKind;
+    /** Trace id of the CLIENT call span. When the server accepted the request,
+     *  @effect/rpc propagates this same id into its span. A transport failure may
+     *  happen before that, so the id is not proof that server logs exist. Present
+     *  only when a client span was active. */
     readonly traceId?: string;
 }
 
@@ -2542,6 +2546,12 @@ export declare class RpcErrorBus {
     emitSuccess(event: RpcSuccess): void;
 }
 
+/** Where the failure originated, classified only as far as the client can
+ * prove. In particular, `transport` does NOT mean the server definitely saw
+ * nothing: a connection can disappear after a request was accepted but before
+ * its response reached the browser. */
+export declare type RpcErrorKind = 'transport' | 'handler' | 'client' | 'unknown';
+
 export declare type RpcErrorListener = (event: RpcError) => void;
 
 /** A call that SUCCEEDED. Carries only its source and tag — there is no payload
@@ -3931,10 +3941,10 @@ export declare const useConnections: (apiName: string) => ConnectedAccountsContr
  * {status !== 'connected' && <OfflineBanner status={status} />}
  * ```
  *
- * `degraded` clears as soon as any rpc on that api succeeds again — call
- * `reportSuccess()` from a place that knows a call went through if you want to
- * clear it eagerly (the hook already clears it when the browser comes back
- * online).
+ * `degraded` clears as soon as any rpc on that api succeeds or returns a
+ * declared handler failure — both prove a server round trip. Call
+ * `reportSuccess()` when another signal proves reachability (the hook also
+ * clears when the browser comes back online).
  */
 export declare const useConnectionStatus: (apiName: string) => ConnectionState & {
     /** Clear the degraded state — call after a known-good round trip. */