docs(pos): source-grounded session/network/common JSDoc corrections (audit proposal)

packages/ui-extensions/src/api.ts

@@ -5,6 +5,10 @@ export interface I18nTranslate {
   /**
    * Returns a translated string matching a key in a locale file. Use this to display localized text in your extension based on the merchant's language preferences. Supports interpolation with replacement values and pluralization with the `count` option. Returns a string when replacements are primitives, or an array when replacements include UI components.
    *
+   * In POS extensions, translation lookup doesn't expose a separate success or error result. A missing key, a missing required plural form, or a missing pluralization count can produce diagnostic text as the return value, along with a console warning. A missing interpolation value leaves the unresolved placeholder in the returned text and emits a warning. Check the development console and test each locale, plural category, and interpolation key before displaying translated content. Don't rely on diagnostic message wording as a stable API contract.
+   *
+   * In POS extensions, pass the `count` option as a number for a pluralized translation key. Zero is a valid count. A numeric string doesn't select a plural form, and omitting the count or passing `undefined` produces a missing-count diagnostic for a pluralized key.
+   *
    * @param key - The translation key from your locale file (for example, "banner.title")
    * @param options - Optional replacement values for interpolation or the special `count` property for pluralization
    *
@@ -38,7 +42,9 @@ export interface I18n {
   /**
    * Returns a localized currency value formatted according to the user's locale and currency conventions. Use this to display prices, totals, or financial amounts in the appropriate format for the merchant's region. This function behaves like the standard `Intl.NumberFormat()` with a style of `currency` applied. Uses the current user's locale by default.
    *
-   * @param number - The currency amount to format
+   * In POS extensions, pass an amount in major currency units and provide `options.currency` as an [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code. For example, `formatCurrency(10, {currency: 'CAD'})` formats ten Canadian dollars. The function doesn't convert currencies or divide an integer minor-unit amount. Omitting the currency while using the currency style throws synchronously. Formatting errors from invalid Intl options are synchronous exceptions, not rejected promises.
+   *
+   * @param number - The currency amount to format, in major currency units
    * @param options.inExtensionLocale - If true, use the extension's default locale instead of the user's locale
    * @param options - Additional Intl.NumberFormatOptions for customizing the currency format, such as the currency code
    */

packages/ui-extensions/src/shared.ts

@@ -976,6 +976,8 @@ export interface ReadonlySignalLike<T> {
   readonly value: T;
   /**
    * Subscribes to value changes and calls the provided function whenever the value updates. Returns an unsubscribe function to clean up the subscription. Use to automatically react to changes in the signal's value.
+   *
+   * Read `value` when you need the initial snapshot. A subscription callback can also receive the current value during subscription setup, particularly when you use the `@shopify/ui-extensions/preact` integration, so a callback firing isn't proof that a new host event occurred. Save the returned unsubscribe function and call it during component cleanup.
    */
   subscribe(fn: (value: T) => void): () => void;
 }

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

@@ -11,7 +11,7 @@ export type ConnectivityStateSeverity = 'Connected' | 'Disconnected';
  */
 export interface ConnectivityState {
   /**
-   * The Internet connection status of the POS device.
+   * The Internet connection status of the POS device. The state defaults to `'Connected'` until POS has confirmed connectivity, and a confirmed outage is required before `'Disconnected'` is reported.
    */
   internetConnected: ConnectivityStateSeverity;
 }
@@ -22,7 +22,7 @@ export interface ConnectivityState {
  */
 export interface ConnectivityApiContent {
   /**
-   * Provides read-only access to the current connectivity state and allows subscribing to connectivity changes. Use for implementing connectivity-aware functionality and reactive connectivity handling.
+   * Provides read-only access to the current connectivity state and allows subscribing to connectivity changes. Use for implementing connectivity-aware functionality and reactive connectivity handling. The state defaults to `Connected` until POS has confirmed connectivity, so an initial `Connected` value doesn't guarantee that the device is online.
    */
   current: ReadonlySignalLike<ConnectivityState>;
 }

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

@@ -6,7 +6,7 @@ import type {ReadonlySignalLike} from '../../../../shared';
  */
 export interface LocaleApiContent {
   /**
-   * Provides read-only access to the current IETF-formatted locale and allows subscribing to locale changes. The `value` property provides the current locale, and `subscribe` allows listening to changes. Use for internationalization, locale-specific formatting, and reactive updates when merchants change language settings.
+   * Provides read-only access to the current IETF-formatted locale and allows subscribing to locale changes. The `value` property provides the current locale, and `subscribe` allows listening to changes. Use for internationalization, locale-specific formatting, and reactive updates when merchants change language settings. At cold start, the value can briefly reflect the device locale before the POS app locale is applied.
    */
   current: ReadonlySignalLike<string>;
 }

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

@@ -11,11 +11,13 @@ export interface SessionApiContent {
    */
   currentSession: Session;
   /**
-   * Provides read-only access to the staff member currently pinned into POS and allows subscribing to staff member changes. The value is `undefined` when no staff member is pinned in.
+   * Provides read-only access to the staff member currently pinned into POS and allows subscribing to staff member changes. The value is `undefined` when no staff member is pinned in, or while the pinned staff member is still loading.
    */
   staffMember: ReadonlySignalLike<StaffMember | undefined>;
   /**
-   * Generates a fresh session token for secure communication with your app's backend service. Returns `undefined` when the authenticated user lacks proper app permissions. The token is a Shopify OpenID Connect ID Token that should be used in `Authorization` headers for backend API calls. This is based on the authenticated user, not the pinned staff member.
+   * Generates a fresh session token for secure communication with your app's backend service. The token is a Shopify OpenID Connect ID Token that should be used in `Authorization` headers for backend API calls. This is based on the authenticated user, not the pinned staff member.
+   *
+   * Returns `undefined` when the token can't be minted, such as when the authenticated user lacks proper app permissions, the token service returns an empty response, or the request times out or fails. The promise can still reject on transport or lifecycle errors. Treat any falsy resolved value as a failure.
    */
   getSessionToken: () => Promise<string | undefined>;
   /**
@@ -25,7 +27,7 @@ export interface SessionApiContent {
    *
    * @example 123456
    * @see [Global IDs documentation](https://shopify.dev/docs/api/usage/gids) for more about GID format and structure
-   * @see [device.getDeviceId()](https://shopify.dev/docs/api/pos-ui-extensions/latest/target-apis/platform-apis/device-api) for physical device identifier (UUID format)
+   * @see [device.getDeviceId()](https://shopify.dev/docs/api/pos-ui-extensions/latest/target-apis/platform-apis/device-api) for the physical device identifier string
    */
   deviceId: number;
 }