Clarify POS validation and resolution contracts

.changeset/pos-intercept-doc-contracts.md

@@ -0,0 +1,5 @@
+---
+'@shopify/ui-extensions': patch
+---
+
+Clarify POS validation interceptor and resolution event semantics, including cash amounts, empty results, revalidation updates, and supported resolution components.

packages/ui-extensions/src/surfaces/point-of-sale/api/resolution-api/resolution-api.ts

@@ -17,8 +17,8 @@ export interface ResolutionApi<TEventData> {
 export interface ResolutionApiContent<TEventData> {
   /**
    * The data of the intercepted event this resolution target was opened for.
-   * The `value` property provides the current data, and `subscribe` allows
-   * listening for host-owned revalidation updates.
+   * The `value` property provides the current data, and `subscribe` receives
+   * Shopify POS revalidation updates.
    */
   event: ReadonlySignalLike<TEventData>;
 }

packages/ui-extensions/src/surfaces/point-of-sale/components/targets/ResolutionComponents.ts

@@ -2,12 +2,12 @@ import type {StandardComponents} from './StandardComponents';
 
 /**
  * Components available on validation resolution targets. Resolution UI renders
- * inside a POS-owned flow step, so page-level and block-level containers are
- * excluded, along with the smart-grid-only `Tile`.
+ * inside a POS-owned flow step, so page-level, block-level, smart-grid, and
+ * legacy navigation components are excluded.
  *
  * @private
  */
 export type ResolutionComponents = Exclude<
   StandardComponents,
-  'Page' | 'POSBlock' | 'PosBlock' | 'Tile'
+  'Page' | 'POSBlock' | 'PosBlock' | 'QrCode' | 'Route' | 'Router' | 'Tile'
 >;

packages/ui-extensions/src/surfaces/point-of-sale/events.ts

@@ -132,7 +132,7 @@ export interface PaymentValidationsEventData {
   /** The payment method staff selected. */
   readonly paymentMethod: InterceptedPaymentMethod;
 
-  /** The amount this tender would charge, in presentment currency. */
+  /** The cash amount received for this tender, in presentment currency. */
   readonly amount: MoneyV2;
 }
 
@@ -193,8 +193,9 @@ export type ShopifyInterceptor<K extends keyof ShopifyInterceptMap> = (
 ) => InterceptResult<ValidationTargetMap[K]>;
 
 /**
- * The result an interceptor returns. An empty `operations` list allows the
- * workflow; an `ERROR` validation blocks it.
+ * The result an interceptor returns. An empty `operations` list adds no
+ * findings from this interceptor and doesn't remove or override findings from
+ * other interceptors.
  *
  * @private
  */
@@ -226,7 +227,7 @@ export type ValidationLevel = 'WARNING' | 'ERROR';
 export interface ValidationAdd<
   TTarget extends ValidationTarget = ValidationTarget,
 > {
-  /** `ERROR` blocks the workflow. `WARNING` does not. */
+  /** `ERROR` creates a finding labeled `Required`. `WARNING` creates a finding labeled `Recommended`. */
   level: ValidationLevel;
 
   /**