docs(pos): source-grounded hardware API JSDoc corrections (audit proposal)

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

@@ -11,18 +11,18 @@ export interface CameraMediaOptions {
    */
   facingMode?: 'user' | 'environment';
   /**
-   * The maximum width (1 to 1920) of the image in pixels. Resizes the image to this width if it is larger.
+   * The requested maximum width of the captured image in pixels. Resizes the image to this width if it's larger. Values below 1 are clamped to 1, and values above 1920 are clamped to 1920 before capture. The `width` on the returned `CameraMediaResponse` is the actual captured image width.
    * @defaultValue 1080
    */
   maxWidth?: number;
   /**
-   * The maximum height (1 to 1920) of the image in pixels. Resizes the image to this height if it is larger.
+   * The requested maximum height of the captured image in pixels. Resizes the image to this height if it's larger. Values below 1 are clamped to 1, and values above 1920 are clamped to 1920 before capture. The `height` on the returned `CameraMediaResponse` is the actual captured image height.
    * @defaultValue 1080
    */
   maxHeight?: number;
   /**
    * The quality of the image returned.
-   * Percentile value between 0 (lowest quality/highest compression) and 1 (highest quality/lowest compression).
+   * A value between 0 (lowest quality, highest compression) and 1 (highest quality, lowest compression). Values outside this range throw an error.
    * @defaultValue 0.9
    */
   quality?: number;

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

@@ -6,6 +6,8 @@ export interface CashDrawerApiContent {
   /**
    * Opens the connected cash drawer device. The drawer will automatically open if a compatible cash drawer is connected to the POS device. Use for manual cash drawer operations, implementing custom payment workflows, or providing explicit cash drawer access in register management interfaces.
    *
+   * The returned promise doesn't confirm that the drawer physically opened.
+   *
    * @returns Void
    */
   open(): Promise<void>;

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

@@ -4,7 +4,7 @@
  */
 export interface DeviceApiContent {
   /**
-   * The name of the device as configured by the merchant or system. Use for displaying device information in interfaces, logging, or support contexts where device identification is helpful.
+   * The operating system device name (for example, the iPad name set in system settings), or the device model name when no name was set. For the merchant-assigned register name configured in POS settings, use `registerName`.
    */
   name: string;
   /**
@@ -13,6 +13,9 @@ export interface DeviceApiContent {
   registerName: string;
   /**
    * Retrieves the unique string identifier for the device. Returns a promise that resolves to the device ID. Use for device-specific data storage, analytics tracking, or implementing device-based permissions and configurations.
+   *
+   * This identifier differs from the numeric device ID available as `shopify.session.deviceId` and as `device.deviceId` on event data.
+   *
    * Note: While Shopify POS attempts to maintain a stable identifier, it is not guaranteed to be permanent and may change.
    */
   getDeviceId(): Promise<string>;

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

@@ -12,6 +12,8 @@ export interface PinPadApiContent {
    *
    * • **When rejected**: Displays the optional `errorMessage` and keeps the modal open.
    *
+   * Catch errors inside `onSubmit` and return `{result: 'reject', errorMessage}` with a message that's safe to display to the merchant.
+   *
    * Use for implementing secure authentication workflows, access control, or PIN-based verification systems.
    */
   showPinPad(

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

@@ -8,7 +8,7 @@ export interface Device {
    */
   name: string;
   /**
-   * The unique identifier for the POS device.
+   * The numeric Shopify POS device ID (the same value as `shopify.session.deviceId`). This differs from the string returned by `shopify.device.getDeviceId()`.
    */
   deviceId: number;
   /**

packages/ui-extensions/src/surfaces/point-of-sale/types/pin-pad.ts

@@ -35,7 +35,7 @@ export type PinLength = 4 | 5 | 6 | 7 | 8 | 9 | 10;
  */
 export interface PinPadActionType {
   /**
-   * The content for the prompt on the pin pad. Use to provide clear instructions or context about what the PIN is being used for.
+   * The label of the custom action button shown between the entry view and the keypad.
    */
   label: string;
   /**