domain0 0.3.3 → 0.4.0

package/README.md

@@ -286,12 +286,14 @@ it to resolve records in the browser. Conditional intent is resolved by the
 backend when the provider is selected, preventing a caller from claiming a
 capability the provider has not proved.
 
-The framework-neutral UI exposes fully typed `onStepChange`, `onSuccess`, and
-`onClose` lifecycle callbacks. Step events are deduplicated, success is emitted
-once per open modal session, and close events distinguish the close button,
-Escape, programmatic close, and destruction. The lower-level
-`onConnectionChange` observer is revision-aware and does not repeat an
-unchanged connection.
+The framework-neutral UI exposes fully typed `onStepChange`, `onSuccess`,
+`onFailure`, `onError`, and `onClose` lifecycle callbacks. Step events are
+deduplicated, success is emitted once per open modal session, and each failed
+connection revision emits once. SDK errors are classified into sanitized
+configuration, API, transport, protocol, and unexpected variants. Close events
+separate their interaction `trigger` from the final success, failure,
+cancellation, or incomplete `outcome`. The lower-level `onConnectionChange`
+observer is revision-aware and does not repeat an unchanged connection.
 
 For an Entri-style high-level lifecycle, use the singleton `domain0` export or
 create an isolated instance with `createDomain0()`. `connectDomain()` mounts
@@ -401,6 +403,8 @@ await domain0.connectDomain({
   onEvent: (event) => {
     switch (event.type) {
       case 'success':
+      case 'failure':
+      case 'error':
       case 'close':
       case 'step_change':
       case 'manual_setup_documentation_click':
@@ -419,6 +423,13 @@ await domain0.connectDomain({
 })
 ```
 
+`failure` means the persisted connection workflow entered
+`failed_retryable` or `failed_terminal`. `error` means the SDK itself could not
+complete an operation. The distinction lets hosts offer connection recovery
+without treating network or integration faults as domain-state transitions.
+Error events contain stable safe codes, retryability, and an API request ID
+when available; raw causes and provider responses are never emitted.
+
 Providing `onRequestClose` intercepts only the in-widget Close button. The
 modal remains open until the host closes it, and `onClose` fires only after the
 real close. Manual-guide events fire only from the manual instructions screen.