@shopify/shop-minis-react 0.15.1 → 0.16.2

package/eslint/config.cjs

@@ -45,7 +45,6 @@ module.exports = {
     'shop-minis/no-javascript-files': 'error',
     'shop-minis/no-secrets': ['error'],
     'shop-minis/prefer-sdk-components': 'warn',
-    'shop-minis/prefer-sdk-hooks': 'warn',
     'shop-minis/validate-manifest': 'error',
 
     // Unsafe code execution (built-in ESLint rules)
@@ -62,6 +61,16 @@ module.exports = {
         message:
           'WebAssembly is not supported in the Shop Minis environment. Consider using alternative JavaScript implementations.',
       },
+      {
+        name: 'localStorage',
+        message:
+          'localStorage is not available in the Shop Minis environment. Use useAsyncStorage (or useSecureStorage for sensitive data) from @shopify/shop-minis-react instead.',
+      },
+      {
+        name: 'sessionStorage',
+        message:
+          'sessionStorage is not available in the Shop Minis environment. Use useAsyncStorage (or useSecureStorage for sensitive data) from @shopify/shop-minis-react instead.',
+      },
     ],
     'no-restricted-syntax': [
       'error',
@@ -108,6 +117,31 @@ module.exports = {
         message:
           'navigator.share is not available in the Shop Minis environment. Use the SDK share functionality instead.',
       },
+      // localStorage / sessionStorage access via window or globalThis
+      {
+        selector:
+          "MemberExpression[object.name='window'][property.name='localStorage']",
+        message:
+          'localStorage is not available in the Shop Minis environment. Use useAsyncStorage (or useSecureStorage for sensitive data) from @shopify/shop-minis-react instead.',
+      },
+      {
+        selector:
+          "MemberExpression[object.name='window'][property.name='sessionStorage']",
+        message:
+          'sessionStorage is not available in the Shop Minis environment. Use useAsyncStorage (or useSecureStorage for sensitive data) from @shopify/shop-minis-react instead.',
+      },
+      {
+        selector:
+          "MemberExpression[object.name='globalThis'][property.name='localStorage']",
+        message:
+          'localStorage is not available in the Shop Minis environment. Use useAsyncStorage (or useSecureStorage for sensitive data) from @shopify/shop-minis-react instead.',
+      },
+      {
+        selector:
+          "MemberExpression[object.name='globalThis'][property.name='sessionStorage']",
+        message:
+          'sessionStorage is not available in the Shop Minis environment. Use useAsyncStorage (or useSecureStorage for sensitive data) from @shopify/shop-minis-react instead.',
+      },
     ],
     'compat/compat': 'error',
   },

package/eslint/index.cjs

@@ -11,7 +11,6 @@ const noInternalImports = require('./rules/no-internal-imports.cjs')
 const noJavaScriptFiles = require('./rules/no-javascript-files.cjs')
 const noSecrets = require('./rules/no-secrets.cjs')
 const preferSdkComponents = require('./rules/prefer-sdk-components.cjs')
-const preferSdkHooks = require('./rules/prefer-sdk-hooks.cjs')
 const validateManifest = require('./rules/validate-manifest.cjs')
 
 module.exports = {
@@ -23,7 +22,6 @@ module.exports = {
     'no-javascript-files': noJavaScriptFiles,
     'no-secrets': noSecrets,
     'prefer-sdk-components': preferSdkComponents,
-    'prefer-sdk-hooks': preferSdkHooks,
     'validate-manifest': validateManifest,
   },
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shopify/shop-minis-react",
   "license": "SEE LICENSE IN LICENSE.txt",
-  "version": "0.15.1",
+  "version": "0.16.2",
   "sideEffects": false,
   "type": "module",
   "engines": {
@@ -17,7 +17,6 @@
   "types": "src/index.ts",
   "files": [
     "src/**/*.{ts,tsx,css}",
-    "dist/**/*",
     "eslint/**/*.cjs",
     "eslint/**/*.md",
     "stylelint/**/*.mjs",
@@ -46,7 +45,7 @@
     "typescript": ">=5.0.0"
   },
   "dependencies": {
-    "@shopify/shop-minis-platform": "0.13.0",
+    "@shopify/shop-minis-platform": "0.14.1",
     "@tailwindcss/vite": "4.1.8",
     "@tanstack/react-query": "5.86.0",
     "@types/lodash": "4.17.20",
@@ -63,7 +62,7 @@
     "eslint-plugin-no-secrets": "2.2.1",
     "eslint-plugin-react": "7.37.5",
     "js-base64": "3.7.7",
-    "lodash": "4.17.21",
+    "lodash": "4.18.0",
     "lucide-react": "0.513.0",
     "motion": "12.17.3",
     "next-themes": "0.4.6",
@@ -74,7 +73,7 @@
     "react-virtuoso": "4.14.0",
     "react-window": "1.8.11",
     "sonner": "2.0.5",
-    "stylelint": "^16.26.1",
+    "stylelint": "16.26.1",
     "tailwind-merge": "2.6.0",
     "tailwindcss": "4.1.8",
     "thumbhash": "0.1.1",
@@ -84,24 +83,24 @@
     "video.js": "8.23.3"
   },
   "devDependencies": {
-    "@playwright/test": "^1.54.2",
-    "@testing-library/jest-dom": "^6.6.4",
-    "@testing-library/react": "^16.1.0",
-    "@testing-library/user-event": "^14.5.2",
-    "@types/node": "^22.18.0",
-    "@types/react": "^19.1.6",
-    "@types/react-dom": "^19.1.2",
-    "@vitest/coverage-v8": "^2.1.8",
-    "@vitest/ui": "^2.1.8",
-    "eslint-formatter-codeframe": "^7.32.1",
-    "jsdom": "^25.0.1",
-    "react": "^19.1.0",
-    "react-dom": "^19.1.0",
-    "serve": "^14.2.4",
-    "typescript": "^5.8.3",
-    "vite": "^6.3.3",
-    "vite-plugin-dts": "^4.3.0",
-    "vitest": "^2.1.8"
+    "@playwright/test": "1.54.2",
+    "@testing-library/jest-dom": "6.7.0",
+    "@testing-library/react": "16.3.0",
+    "@testing-library/user-event": "14.6.1",
+    "@types/node": "22.18.6",
+    "@types/react": "19.1.6",
+    "@types/react-dom": "19.1.6",
+    "@vitest/coverage-v8": "2.1.9",
+    "@vitest/ui": "2.1.9",
+    "eslint-formatter-codeframe": "7.32.2",
+    "jsdom": "25.0.1",
+    "react": "19.1.0",
+    "react-dom": "19.1.0",
+    "serve": "14.2.4",
+    "typescript": "5.8.3",
+    "vite": "6.3.5",
+    "vite-plugin-dts": "4.5.4",
+    "vitest": "2.1.9"
   },
   "keywords": [
     "react",

package/src/components/atoms/alert-dialog.tsx

@@ -12,6 +12,10 @@ import {
   AlertDialog as AlertDialogPrimitive,
 } from '../ui/alert-dialog'
 
+/**
+ * A composable component for important confirmations and alerts with customizable actions.
+ * @publicDocs
+ */
 export interface AlertDialogAtomProps {
   /** The trigger element that opens the alert dialog */
   children: React.ReactNode

package/src/components/atoms/button.tsx

@@ -7,6 +7,10 @@ import {BaseButton, buttonVariants} from '../ui/button'
 
 import {Touchable} from './touchable'
 
+/**
+ * A versatile button component with multiple variants and sizes for user interactions.
+ * @publicDocs
+ */
 export interface ButtonDocProps {
   /** Visual style variant */
   variant?:

package/src/components/atoms/content-wrapper.tsx

@@ -28,6 +28,16 @@ type ContentWrapperProps =
   | PublicIdContentWrapperProps
   | ExternalIdContentWrapperProps
 
+/**
+ * The `ContentWrapper` component fetches and provides user-generated content data using a render function pattern. It accepts either a `publicId` or `externalId` to identify the content, and passes the resolved content along with loading state to a child render function.
+ *
+ * If `content` is not set (and `loading` is `false`), the ID was either not found or the content has been moderated and will not be shown. Users will always be able to see their own content.
+ *
+ * Use `ContentWrapper` when you need full control over how content is rendered. For a simpler image-specific wrapper, see `ImageContentWrapper`.
+ *
+ * > Note: Content rendered through `ContentWrapper` is wrapped in a `ContentMonitor` that allows users to report it for moderation.
+ * @publicDocs
+ */
 // It's too messy in the docs to show the complete types here so we show a simplified version
 export interface ContentWrapperPropsForDocs extends BaseContentWrapperProps {
   /** The public ID of the content item (use this OR externalId). */

package/src/components/atoms/icon-button.tsx

@@ -4,6 +4,10 @@ import {cn} from '../../lib/utils'
 
 import {Button} from './button'
 
+/**
+ * A button component that displays an icon in various sizes.
+ * @publicDocs
+ */
 export interface IconButtonProps {
   /** Click handler */
   onClick?: () => void

package/src/components/atoms/image.tsx

@@ -12,6 +12,10 @@ import {
 import {cn} from '../../lib/utils'
 import {getThumbhashBlobURL, getResizedImageUrl} from '../../utils'
 
+/**
+ * An optimized image component that handles File objects, remote URLs, blob URL lifecycle management, and progressive loading with thumbhash placeholders. Ideal for displaying images from useImagePicker or any remote source.
+ * @publicDocs
+ */
 export interface ImageDocProps {
   /** Remote image URL */
   src?: string

package/src/components/atoms/list.tsx

@@ -12,6 +12,10 @@ import {Skeleton} from '../ui/skeleton'
 const DEFAULT_REFRESH_PULL_THRESHOLD = 200
 const ELEMENT_BIND_DELAY = 100
 
+/**
+ * A virtualized list component for efficiently rendering large datasets with customizable item rendering and built-in pull-to-refresh functionality.
+ * @publicDocs
+ */
 export interface ListDocProps<T = any> {
   /** Array of items to render */
   items: T[]

package/src/components/atoms/product-variant-price.tsx

@@ -1,6 +1,10 @@
 import {cn} from '../../lib/utils'
 import {formatMoney} from '../../utils/formatMoney'
 
+/**
+ * A component for displaying product pricing with support for discounts and custom styling.
+ * @publicDocs
+ */
 export interface ProductVariantPriceProps {
   amount: number | string
   currencyCode?: string

package/src/components/atoms/safe-area.tsx

@@ -1,7 +1,16 @@
 import {useSafeArea} from '../../hooks/util/useSafeArea'
 
-type Edge = 'top' | 'right' | 'bottom' | 'left'
+/** @publicDocs */
+export type Edge = 'top' | 'right' | 'bottom' | 'left'
 
+/**
+ * A container that applies safe area insets as padding or margin, ensuring content is not hidden behind system UI such as the home indicator on iOS or the navigation bar on Android.
+ *
+ * You can pass in custom classes and styles just like a regular `div`, so we recommend using it in place of your usual top-level wrapper.
+ *
+ * When no `edges` prop is specified, all four edges are applied. If you only need a specific edge, for example a sticky footer, use `edges={["bottom"]}`.
+ * @publicDocs
+ */
 export interface SafeAreaDocProps {
   /** Which edges to apply safe area insets to. Defaults to all edges. */
   edges?: Edge[]

package/src/components/atoms/static-area.tsx

@@ -1,3 +1,9 @@
+/**
+ * A layout wrapper that prevents header and footer content from animating during screen view transitions. Use this to keep navigation bars, headers, footers or bottom tab bars fixed in place while page content animates.
+ *
+ * > Caution: Only use one StaticArea per position (top or bottom) in your app. Multiple StaticAreas with the same position will have duplicate view transition names, which will cause view transitions to fail.
+ * @publicDocs
+ */
 export interface StaticAreaDocProps {
   /** Position of the fixed area on screen - either pinned to top or bottom */
   position: 'top' | 'bottom'

package/src/components/atoms/touchable.tsx

@@ -2,6 +2,10 @@ import * as React from 'react'
 
 import {motion, HTMLMotionProps, useAnimationControls} from 'motion/react'
 
+/**
+ * Animated wrapper providing native-like tap feedback. You can use it instead of raw div + onClick.
+ * @publicDocs
+ */
 export interface TouchableDocProps {
   /** Click handler */
   onClick?: React.MouseEventHandler<HTMLDivElement>

package/src/components/atoms/video-player.tsx

@@ -17,6 +17,10 @@ export interface VideoPlayerRef {
   pause: () => void
 }
 
+/**
+ * Video.js-powered player with automatic format handling. Includes custom play/pause overlay and imperative controls via ref (for advanced scenarios like synchronized playback). Video.js handles codec support, adaptive streaming, and disposal lifecycle automatically.
+ * @publicDocs
+ */
 export interface VideoPlayerProps {
   /** The video source URL */
   src: string

package/src/components/commerce/add-to-cart.tsx

@@ -10,6 +10,10 @@ import {useShopCartActions} from '../../internal/useShopCartActions'
 import {cn} from '../../lib/utils'
 import {Button} from '../atoms/button'
 
+/**
+ * Adds products to Shop's cart with checkmark animation feedback. Users can continue shopping and add more items before checkout. Use this for browsing experiences where customers might want multiple products. For immediate single-product purchases, use `BuyNowButton` instead.
+ * @publicDocs
+ */
 export interface AddToCartButtonProps {
   /** Whether the button is disabled */
   disabled?: boolean

package/src/components/commerce/buy-now.tsx

@@ -8,6 +8,10 @@ import {useShopCartActions} from '../../internal/useShopCartActions'
 import {cn} from '../../lib/utils'
 import {Button} from '../atoms/button'
 
+/**
+ * Navigates directly to Shop's express checkout, bypassing the cart entirely. Use for single-item purchases, limited-time offers, or when reducing friction is critical. Best for impulse buys and focused conversion flows.
+ * @publicDocs
+ */
 export interface BuyNowButtonProps {
   /** Whether the button is disabled */
   disabled?: boolean

package/src/components/commerce/favorite-button.tsx

@@ -2,6 +2,10 @@ import {Heart} from 'lucide-react'
 
 import {IconButton} from '../atoms/icon-button'
 
+/**
+ * A button component for toggling a favorite state, typically used for products.
+ * @publicDocs
+ */
 export interface FavoriteButtonProps {
   /** Click handler for toggling favorite state */
   onClick?: () => void

package/src/components/commerce/merchant-card.tsx

@@ -364,6 +364,10 @@ function MerchantCardHeader({
   )
 }
 
+/**
+ * Use when showcasing merchants as destinations, not just product sources. Automatically adapts to merchant's brand colors, logo placement, and featured product images. Respects merchant brand guidelines while maintaining consistent Shop UI patterns.
+ * @publicDocs
+ */
 export interface MerchantCardProps {
   /** The shop/merchant to display */
   shop: Shop

package/src/components/commerce/product-card.tsx

@@ -304,6 +304,10 @@ function ProductCardPriceOverlayBadge() {
   )
 }
 
+/**
+ * Optimized for grid layouts with three variants: `default`, `priceOverlay`, and `compact`. Use default for product grids where details matter, priceOverlay for visual-first feeds, compact when dealing with limited space. For some list views where space is limited, `ProductLink` may work better. Exposes composable subcomponents for custom layouts.
+ * @publicDocs
+ */
 export interface ProductCardProps {
   /** The product to display in the card */
   product: Product

package/src/components/commerce/product-link.tsx

@@ -228,6 +228,10 @@ function ProductLinkActions({
   )
 }
 
+/**
+ * A list item component for displaying products in search results, lists, and feeds. `ProductLink` works well for list views and search results where vertical space is limited. For grid layouts with larger images, you can use `ProductCard` instead. Supports custom actions (e.g., "Add to Cart") in place of the favorite button.
+ * @publicDocs
+ */
 export interface ProductLinkDocProps {
   /** The product to display */
   product: Product

package/src/components/commerce/quantity-selector.tsx

@@ -5,6 +5,10 @@ import {Minus, Plus} from 'lucide-react'
 import {cn} from '../../lib/utils'
 import {IconButton} from '../atoms/icon-button'
 
+/**
+ * A component with increment and decrement buttons for adjusting quantities.
+ * @publicDocs
+ */
 export interface QuantitySelectorProps {
   /** Current quantity value */
   quantity: number

package/src/components/commerce/search.tsx

@@ -34,6 +34,10 @@ function useSearchContext() {
   return context
 }
 
+/**
+ * Product search with automatic debouncing via `useProductSearch` hook. Two usage patterns: all-in-one `Search` component (fastest setup, fixed layout) or composable `SearchProvider` + `SearchInput` + `SearchResultsList` (custom layouts, shared search state). The all-in-one component handles input, loading skeletons, empty states, and infinite scroll. Use composable approach when you need custom result rendering or multiple search-dependent sections.
+ * @publicDocs
+ */
 export interface SearchProviderProps {
   initialQuery?: string
   children: React.ReactNode

package/src/components/content/image-content-wrapper.tsx

@@ -1,6 +1,11 @@
 import {ContentWrapper} from '../atoms/content-wrapper'
 import {Image} from '../atoms/image'
 
+/**
+ * The `ImageContentWrapper` component renders images uploaded via the `useCreateImageContent` hook. Use it instead of raw Image component when displaying any user-generated content. It accepts either a `publicId` or `externalId`.
+ * > Note: Uploaded images are moderated by Shop. Additionally, rendered images can be reported by users for moderation.
+ * @publicDocs
+ */
 export interface ImageContentWrapperDocProps {
   /** The public ID of the uploaded image (use this OR externalId) */
   publicId?: string

package/src/components/navigation/minis-router.tsx

@@ -4,6 +4,10 @@ import {NavigationManager} from '../../internal/navigation-manager'
 
 import {TransitionContainer} from './transition-container'
 
+/**
+ * MinisRouter is the main routing component for Shop Minis that wraps React Router's BrowserRouter and provides optional support for smooth navigation transitions using the CSS View Transitions API. It should be placed at the root of your application to enable client-side routing.
+ * @publicDocs
+ */
 export interface MinisRouterProps extends BrowserRouterProps {
   viewTransitions?: boolean
 }

package/src/components/navigation/transition-link.tsx

@@ -4,6 +4,12 @@ import {useHref} from 'react-router'
 
 import {useNavigateWithTransition} from '../../hooks/navigation/useNavigateWithTransition'
 
+/**
+ * Navigation component that triggers animated page changes based on CSS View Transitions. Use instead of React Router's `Link` or `<a>` tags when you want smooth native feeling navigation within your Mini. Should be wrapped within a `MinisRouter`.
+ *
+ * > Caution: In order for the animation transitions to work, you need to enable view transitions in `MinisRouter`
+ * @publicDocs
+ */
 export interface TransitionLinkDocProps {
   /** The target path to navigate to */
   to: string

package/src/components/ui/alert.tsx

@@ -4,6 +4,10 @@ import {cva, type VariantProps} from 'class-variance-authority'
 
 import {cn} from '../../lib/utils'
 
+/**
+ * A component with a title and description, available in different visual variants.
+ * @publicDocs
+ */
 export interface AlertDocProps {
   /** Visual style variant */
   variant?: 'default' | 'destructive'

package/src/components/ui/badge.tsx

@@ -5,6 +5,10 @@ import {Slot as SlotPrimitive} from 'radix-ui'
 
 import {cn} from '../../lib/utils'
 
+/**
+ * A component for displaying status, categories, or labels with multiple visual variants.
+ * @publicDocs
+ */
 export interface BadgeDocProps {
   /** Visual style variant */
   variant?: 'primary' | 'secondary' | 'destructive' | 'outline' | 'none'

package/src/components/ui/input.tsx

@@ -2,6 +2,10 @@ import * as React from 'react'
 
 import {cn} from '../../lib/utils'
 
+/**
+ * A simple component for inputting text.
+ * @publicDocs
+ */
 export interface InputDocProps {
   /** Ref to the input element (use instead of ref) */
   innerRef?: React.Ref<HTMLInputElement>

package/src/hooks/content/useCreateImageContent.ts

@@ -10,7 +10,7 @@ import {useHandleAction} from '../../internal/useHandleAction'
 import {useShopActions} from '../../internal/useShopActions'
 import {useImageUpload} from '../storage/useImageUpload'
 
-interface CreateImageContentParams {
+export interface CreateImageContentParams {
   /**
    * The image file to upload.
    */
@@ -47,7 +47,7 @@ interface CreateImageContentParams {
   productIds?: string[]
 }
 
-interface UseCreateImageContentReturns {
+export interface UseCreateImageContentReturns {
   /**
    * Upload an image and create content.
    */
@@ -113,3 +113,46 @@ export const useCreateImageContent = (): UseCreateImageContentReturns => {
     loading,
   }
 }
+
+/**
+ * The `useCreateImageContent` hook combines image upload with content creation to generate user-generated content entries. Built on top of `useImageUpload`, it extends the basic upload functionality with content management features including titles, descriptions, visibility controls, product associations, and unique IDs for sharing and discovery.
+ *
+ * ### Parameters
+ *
+ * The `createImageContent` function accepts an object with the following fields:
+ *
+ * - **`image`** (required): A `File` object representing the image to upload.
+ * - **`contentTitle`** (required): The title for the content entry.
+ * - **`visibility`** (optional): An array of `ContentVisibility` values (see below).
+ * - **`externalId`** (optional): A unique identifier from your own system that lets you look up content later via `ContentWrapper` using an ID you already know. If not provided, the content can only be retrieved by its `publicId`. Each `externalId` must be unique per Mini — creating content with a duplicate `externalId` returns a `DUPLICATE_EXTERNAL_ID` error.
+ * - **`description`** (optional): A text description for the content. Displayed alongside the content in Shop surfaces such as feeds and content detail views. Use this to provide context about the image, such as a caption or review text.
+ * - **`productIds`** (optional): An array of Shopify product GIDs (e.g. `'gid://shopify/Product/123'`) to associate with the content. Maximum 20 products. Associated products appear alongside the content, enabling shoppable content experiences. If any product IDs are ineligible, the mutation will return an `INELIGIBLE_PRODUCTS` error.
+ *
+ * ### Visibility Options
+ *
+ * The `visibility` parameter accepts an optional array of `ContentVisibility` values:
+ *
+ * - **`DISCOVERABLE`**: Makes content eligible for Shop's recommendation and discovery systems. Your content can appear in feeds and recommendations across the Shop app.
+ * - **`LINKABLE`**: Enables shareable URLs for the content. When set, the created `Content` object includes a `shareableUrl` field containing a URL that can be shared externally. The shareable page renders OpenGraph meta tags (`og:title`, `og:image`, `og:description`) using the content's `contentTitle`, uploaded image, and `description` — so link previews in social media, messaging apps, and other platforms will display a rich card with the content's title, image, and description. Use the `useShare` hook to trigger the native share sheet with this URL.
+ *
+ * ### Error Handling
+ *
+ * The hook may return `userErrors` in the response with the following codes:
+ *
+ * - **`DUPLICATE_EXTERNAL_ID`**: Returned when an `externalId` is provided that already exists for this Mini. Each `externalId` must be unique per content entry.
+ * - **`INELIGIBLE_PRODUCTS`**: Returned when one or more `productIds` refer to products that are not eligible for Shop. The error message includes the specific ineligible product GIDs.
+ *
+ * ### Use Cases
+ *
+ * - **Shareable content with rich link previews**: Include `LINKABLE` in the `visibility` array and provide a `contentTitle`, `description`, and image. The returned `shareableUrl` points to a page with OpenGraph tags, so when shared via social media or messaging apps the link preview displays the content's title, image, and description as a rich card. Pass the `shareableUrl` to the `useShare` hook to open the native share sheet.
+ * - **User reviews with photos**: Provide `description` for the review text, `productIds` to link the reviewed products, and `['DISCOVERABLE', 'LINKABLE']` visibility for maximum reach.
+ * - **Shoppable lookbooks**: Upload styled images with associated `productIds` so users can shop the look.
+ * - **Content lookup by your own ID**: Set `externalId` to an identifier from your system (e.g. a database row ID or slug) so you can retrieve the content later via `ContentWrapper` without storing the `publicId`.
+ *
+ * The hook handles both the image upload pipeline and content entity creation in a single operation, automatically associating content with your Mini and integrating with Shop's content systems.
+ *
+ * > Caution: You must run the [`setup`](/docs/api/shop-minis/commands/setup) CLI command before using this hook so the content can be associated with the Mini.
+ * @publicDocs
+ */
+export type UseCreateImageContentGeneratedType =
+  () => UseCreateImageContentReturns

package/src/hooks/index.ts

@@ -50,9 +50,11 @@ export * from './util/useShare'
 export * from './util/useImagePicker'
 export * from './util/useKeyboardAvoidingView'
 export * from './util/useRequestPermissions'
+export * from './util/useCheckPermissions'
 
 // - Intent Hooks
 export * from './intents/useIntent'
+export * from './intents/useUserImagePicker'
 
 // - Event Hooks
 export * from './events/useOnMiniFocus'

package/src/hooks/intents/useIntent.ts

@@ -111,3 +111,9 @@ export function useIntent(): UseIntentReturn {
     }
   }, [queryParams])
 }
+
+/**
+ * Parses an intent passed to the Mini via deeplink, following the [Shopify Intents API](https://shopify.dev/docs/api/admin-extensions/latest/target-apis/utility-apis/intents-api) URI format (`action:type,value`). Returns the parsed `query` (`action`, `type`, `value`) and optional `data` payload. Use this hook to receive intents from the host app (Host → Mini direction), for example when the Shop app launches a Mini to handle a virtual try-on for a specific product.
+ * @publicDocs
+ */
+export type UseIntentGeneratedType = () => UseIntentReturn

package/src/hooks/intents/useUserImagePicker.ts

@@ -0,0 +1,36 @@
+import {useCallback} from 'react'
+
+import {useShopIntent} from '../../internal/useShopIntent'
+
+import type {
+  CreateUserImageParams,
+  CreateUserImageResponse,
+  IntentResult,
+} from '@shopify/shop-minis-platform/actions'
+
+/**
+ * Hook for minis to create a user image via the host app's
+ * camera or photo library.
+ */
+export function useUserImagePicker() {
+  const {invokeQuery} = useShopIntent()
+
+  const pickImage = useCallback(
+    async (
+      options: CreateUserImageParams
+    ): Promise<IntentResult<CreateUserImageResponse>> => {
+      const result = await invokeQuery({
+        action: 'create',
+        type: 'shop/UserImage',
+        data: options,
+      })
+
+      // The bridge returns untyped data; the host handler guarantees
+      // the shape matches CreateUserImageResponse for this action+type.
+      return result as IntentResult<CreateUserImageResponse>
+    },
+    [invokeQuery]
+  )
+
+  return {pickImage}
+}

package/src/hooks/navigation/useCloseMini.ts

@@ -3,7 +3,7 @@ import {useCallback} from 'react'
 import {useHandleAction} from '../../internal/useHandleAction'
 import {useShopActions} from '../../internal/useShopActions'
 
-interface UseCloseMiniReturns {
+export interface UseCloseMiniReturns {
   /**
    * Closes the Mini viewer.
    */
@@ -20,3 +20,9 @@ export const useCloseMini = (): UseCloseMiniReturns => {
     closeMini: useCallback(() => handleClose(), [handleClose]),
   }
 }
+
+/**
+ * Closes the Mini and returns the user to the Shop app. The Mini's WebView is destroyed and all state is lost. Use this for explicit exit flows (order completed, user cancellation) or when navigation should leave the Mini context entirely. Unlike `useShopNavigation`, which navigates to other Shop screens while keeping the Mini in the navigation stack, this removes the Mini from the stack.
+ * @publicDocs
+ */
+export type UseCloseMiniGeneratedType = () => UseCloseMiniReturns

package/src/hooks/navigation/useDeeplink.ts

@@ -2,7 +2,7 @@ import {useMemo} from 'react'
 
 import {parseUrl} from '../../utils/parseUrl'
 
-interface UseDeeplinkReturnType {
+export interface UseDeeplinkReturnType {
   /**
    * The path of the deeplink.
    */
@@ -41,3 +41,9 @@ export const useDeeplink = (): UseDeeplinkReturnType => {
     }
   }, [handle, initialUrl])
 }
+
+/**
+ * Retrieves the deeplink URL that launched the Mini, enabling external links to open specific screens with context. Use on mount to route to the correct initial screen based on the returned `path`, `queryParams` or `hash`. Common use: email/notification links opening to specific nested screens.
+ * @publicDocs
+ */
+export type UseDeeplinkGeneratedType = () => UseDeeplinkReturnType