@shopify/shop-minis-react 0.4.15 → 0.4.17

package/dist/utils/image.js.map

@@ -1 +1 @@
-{"version":3,"file":"image.js","sources":["../../src/utils/image.ts"],"sourcesContent":["import {toUint8Array} from 'js-base64'\nimport {thumbHashToDataURL} from 'thumbhash'\n\n/**\n * Converts a thumbhash string to a data URL for use as an image placeholder\n * @param thumbhash Base64 encoded thumbhash string\n * @returns Data URL that can be used as image source or undefined if conversion fails\n */\nexport function getThumbhashDataURL(thumbhash?: string): string | undefined {\n  if (!thumbhash) return\n\n  try {\n    const thumbhashArray = toUint8Array(thumbhash)\n    return thumbHashToDataURL(thumbhashArray)\n  } catch (error) {\n    console.warn('Failed to decode thumbhash to data URL', error)\n    return undefined\n  }\n}\n\n/** Converts a file to a data URI\n * @param file The file to convert\n * @returns A promise that resolves to the data URI string\n */\nexport function fileToDataUri(file: File): Promise<string> {\n  return new Promise((resolve, reject) => {\n    const reader = new FileReader()\n    reader.onloadend = () => resolve(reader.result as string)\n    reader.onerror = reject\n    reader.readAsDataURL(file)\n  })\n}\n\nconst ImageSizes = {\n  xxsUrl: 32,\n  xsUrl: 64,\n  sUrl: 128,\n  xxsmUrl: 256,\n  xsmUrl: 384,\n  smUrl: 512,\n  mUrl: 640,\n  lUrl: 1080,\n  xlUrl: 2048,\n} as const\n\ntype Key = keyof typeof ImageSizes\n\n/**\n * Acceptable offset for image sizes. An image could use the size that is within this offset.\n */\nconst offsetPercentage = 0.05\n\nconst sortedImageSizes = Object.entries(ImageSizes).sort(\n  ([, firstSize], [, secondSize]) => firstSize - secondSize\n)\n\nconst getImageSizeKeyWithSize = (size: number): Key => {\n  for (const [key, imgSize] of sortedImageSizes) {\n    const upperBoundSize = imgSize + imgSize * offsetPercentage\n    if (size <= upperBoundSize) return key as Key\n  }\n\n  return 'xlUrl'\n}\n\nconst resizeImage = (imageUrl: string, width: number) => {\n  const pattern = new RegExp(/\\?+/g)\n  const delimiter = pattern.test(imageUrl) ? '&' : '?'\n  return `${imageUrl}${delimiter}width=${width}`\n}\n\n/**\n * Optimizes Shopify CDN image URLs by adding a width parameter based on screen size\n * @param url The image URL to optimize\n * @returns The optimized URL with width parameter if it's a Shopify CDN image, otherwise returns the original URL\n */\n\nexport const getResizedImageUrl = (url?: string): string => {\n  if (!url) return ''\n\n  // Only process Shopify CDN images\n  if (!url.startsWith('https://cdn.shopify.com')) {\n    return url\n  }\n\n  const width = window.innerWidth ?? screen.width\n\n  const key = getImageSizeKeyWithSize(width)\n\n  return resizeImage(url, ImageSizes[key])\n}\n"],"names":["getThumbhashDataURL","thumbhash","thumbhashArray","toUint8Array","thumbHashToDataURL","error","fileToDataUri","file","resolve","reject","reader","ImageSizes","offsetPercentage","sortedImageSizes","firstSize","secondSize","getImageSizeKeyWithSize","size","key","imgSize","upperBoundSize","resizeImage","imageUrl","width","delimiter","getResizedImageUrl","url"],"mappings":";;AAQO,SAASA,EAAoBC,GAAwC;AAC1E,MAAKA;AAED,QAAA;AACI,YAAAC,IAAiBC,EAAaF,CAAS;AAC7C,aAAOG,EAAmBF,CAAc;AAAA,aACjCG,GAAO;AACN,cAAA,KAAK,0CAA0CA,CAAK;AACrD;AAAA,IAAA;AAEX;AAMO,SAASC,EAAcC,GAA6B;AACzD,SAAO,IAAI,QAAQ,CAACC,GAASC,MAAW;AAChC,UAAAC,IAAS,IAAI,WAAW;AAC9B,IAAAA,EAAO,YAAY,MAAMF,EAAQE,EAAO,MAAgB,GACxDA,EAAO,UAAUD,GACjBC,EAAO,cAAcH,CAAI;AAAA,EAAA,CAC1B;AACH;AAEA,MAAMI,IAAa;AAAA,EACjB,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,MAAM;AAAA,EACN,SAAS;AAAA,EACT,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,MAAM;AAAA,EACN,MAAM;AAAA,EACN,OAAO;AACT,GAOMC,IAAmB,MAEnBC,IAAmB,OAAO,QAAQF,CAAU,EAAE;AAAA,EAClD,CAAC,CAAG,EAAAG,CAAS,GAAG,GAAGC,CAAU,MAAMD,IAAYC;AACjD,GAEMC,IAA0B,CAACC,MAAsB;AACrD,aAAW,CAACC,GAAKC,CAAO,KAAKN,GAAkB;AACvC,UAAAO,IAAiBD,IAAUA,IAAUP;AACvC,QAAAK,KAAQG,EAAuB,QAAAF;AAAA,EAAA;AAG9B,SAAA;AACT,GAEMG,IAAc,CAACC,GAAkBC,MAAkB;AAEvD,QAAMC,IADU,IAAI,OAAO,MAAM,EACP,KAAKF,CAAQ,IAAI,MAAM;AACjD,SAAO,GAAGA,CAAQ,GAAGE,CAAS,SAASD,CAAK;AAC9C,GAQaE,IAAqB,CAACC,MAAyB;AACtD,MAAA,CAACA,EAAY,QAAA;AAGjB,MAAI,CAACA,EAAI,WAAW,yBAAyB;AACpC,WAAAA;AAGH,QAAAH,IAAQ,OAAO,cAAc,OAAO,OAEpCL,IAAMF,EAAwBO,CAAK;AAEzC,SAAOF,EAAYK,GAAKf,EAAWO,CAAG,CAAC;AACzC;"}
+{"version":3,"file":"image.js","sources":["../../src/utils/image.ts"],"sourcesContent":["import {toUint8Array} from 'js-base64'\nimport {thumbHashToDataURL} from 'thumbhash'\n\n/**\n * Converts a thumbhash string to a data URL for use as an image placeholder\n * @param thumbhash Base64 encoded thumbhash string\n * @returns Data URL that can be used as image source or undefined if conversion fails\n */\nexport function getThumbhashDataURL(thumbhash?: string): string | undefined {\n  if (!thumbhash) return\n\n  try {\n    const thumbhashArray = toUint8Array(thumbhash)\n    return thumbHashToDataURL(thumbhashArray)\n  } catch (error) {\n    console.warn('Failed to decode thumbhash to data URL', error)\n    return undefined\n  }\n}\n\n/**\n * Converts a data URL to a Blob\n * @param dataURL The data URL to convert\n * @returns A Blob object\n */\nexport function dataURLToBlob(dataURL: string): Blob {\n  const [header, base64Data] = dataURL.split(',')\n  const mimeMatch = header.match(/:(.*?);/)\n  const mime = mimeMatch ? mimeMatch[1] : 'image/png'\n  const binary = atob(base64Data)\n  const array = new Uint8Array(binary.length)\n  for (let i = 0; i < binary.length; i++) {\n    array[i] = binary.charCodeAt(i)\n  }\n  return new Blob([array], {type: mime})\n}\n\n/**\n * Converts a thumbhash string to a blob URL for use as an image placeholder\n * This is useful when CSP restrictions prevent data URLs\n * @param thumbhash Base64 encoded thumbhash string\n * @returns Blob URL that can be used as image source or undefined if conversion fails\n */\nexport function getThumbhashBlobURL(thumbhash?: string): string | undefined {\n  if (!thumbhash) return\n\n  try {\n    const dataURL = getThumbhashDataURL(thumbhash)\n    if (!dataURL) return\n\n    const blob = dataURLToBlob(dataURL)\n    return URL.createObjectURL(blob)\n  } catch (error) {\n    console.warn('Failed to create thumbhash blob URL', error)\n    return undefined\n  }\n}\n\n/** Converts a file to a data URI\n * @param file The file to convert\n * @returns A promise that resolves to the data URI string\n */\nexport function fileToDataUri(file: File): Promise<string> {\n  return new Promise((resolve, reject) => {\n    const reader = new FileReader()\n    reader.onloadend = () => resolve(reader.result as string)\n    reader.onerror = reject\n    reader.readAsDataURL(file)\n  })\n}\n\nconst ImageSizes = {\n  xxsUrl: 32,\n  xsUrl: 64,\n  sUrl: 128,\n  xxsmUrl: 256,\n  xsmUrl: 384,\n  smUrl: 512,\n  mUrl: 640,\n  lUrl: 1080,\n  xlUrl: 2048,\n} as const\n\ntype Key = keyof typeof ImageSizes\n\n/**\n * Acceptable offset for image sizes. An image could use the size that is within this offset.\n */\nconst offsetPercentage = 0.05\n\nconst sortedImageSizes = Object.entries(ImageSizes).sort(\n  ([, firstSize], [, secondSize]) => firstSize - secondSize\n)\n\nconst getImageSizeKeyWithSize = (size: number): Key => {\n  for (const [key, imgSize] of sortedImageSizes) {\n    const upperBoundSize = imgSize + imgSize * offsetPercentage\n    if (size <= upperBoundSize) return key as Key\n  }\n\n  return 'xlUrl'\n}\n\nconst resizeImage = (imageUrl: string, width: number) => {\n  const pattern = new RegExp(/\\?+/g)\n  const delimiter = pattern.test(imageUrl) ? '&' : '?'\n  return `${imageUrl}${delimiter}width=${width}`\n}\n\n/**\n * Optimizes Shopify CDN image URLs by adding a width parameter based on screen size\n * @param url The image URL to optimize\n * @returns The optimized URL with width parameter if it's a Shopify CDN image, otherwise returns the original URL\n */\n\nexport const getResizedImageUrl = (url?: string): string => {\n  if (!url) return ''\n\n  // Only process Shopify CDN images\n  if (!url.startsWith('https://cdn.shopify.com')) {\n    return url\n  }\n\n  const width = window.innerWidth ?? screen.width\n\n  const key = getImageSizeKeyWithSize(width)\n\n  return resizeImage(url, ImageSizes[key])\n}\n"],"names":["getThumbhashDataURL","thumbhash","thumbhashArray","toUint8Array","thumbHashToDataURL","error","dataURLToBlob","dataURL","header","base64Data","mimeMatch","mime","binary","array","i","getThumbhashBlobURL","blob","fileToDataUri","file","resolve","reject","reader","ImageSizes","offsetPercentage","sortedImageSizes","firstSize","secondSize","getImageSizeKeyWithSize","size","key","imgSize","upperBoundSize","resizeImage","imageUrl","width","delimiter","getResizedImageUrl","url"],"mappings":";;AAQO,SAASA,EAAoBC,GAAwC;AAC1E,MAAKA;AAED,QAAA;AACI,YAAAC,IAAiBC,EAAaF,CAAS;AAC7C,aAAOG,EAAmBF,CAAc;AAAA,aACjCG,GAAO;AACN,cAAA,KAAK,0CAA0CA,CAAK;AACrD;AAAA,IAAA;AAEX;AAOO,SAASC,EAAcC,GAAuB;AACnD,QAAM,CAACC,GAAQC,CAAU,IAAIF,EAAQ,MAAM,GAAG,GACxCG,IAAYF,EAAO,MAAM,SAAS,GAClCG,IAAOD,IAAYA,EAAU,CAAC,IAAI,aAClCE,IAAS,KAAKH,CAAU,GACxBI,IAAQ,IAAI,WAAWD,EAAO,MAAM;AAC1C,WAASE,IAAI,GAAGA,IAAIF,EAAO,QAAQE;AACjC,IAAAD,EAAMC,CAAC,IAAIF,EAAO,WAAWE,CAAC;AAEzB,SAAA,IAAI,KAAK,CAACD,CAAK,GAAG,EAAC,MAAMF,GAAK;AACvC;AAQO,SAASI,EAAoBd,GAAwC;AAC1E,MAAKA;AAED,QAAA;AACI,YAAAM,IAAUP,EAAoBC,CAAS;AAC7C,UAAI,CAACM,EAAS;AAER,YAAAS,IAAOV,EAAcC,CAAO;AAC3B,aAAA,IAAI,gBAAgBS,CAAI;AAAA,aACxBX,GAAO;AACN,cAAA,KAAK,uCAAuCA,CAAK;AAClD;AAAA,IAAA;AAEX;AAMO,SAASY,EAAcC,GAA6B;AACzD,SAAO,IAAI,QAAQ,CAACC,GAASC,MAAW;AAChC,UAAAC,IAAS,IAAI,WAAW;AAC9B,IAAAA,EAAO,YAAY,MAAMF,EAAQE,EAAO,MAAgB,GACxDA,EAAO,UAAUD,GACjBC,EAAO,cAAcH,CAAI;AAAA,EAAA,CAC1B;AACH;AAEA,MAAMI,IAAa;AAAA,EACjB,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,MAAM;AAAA,EACN,SAAS;AAAA,EACT,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,MAAM;AAAA,EACN,MAAM;AAAA,EACN,OAAO;AACT,GAOMC,IAAmB,MAEnBC,IAAmB,OAAO,QAAQF,CAAU,EAAE;AAAA,EAClD,CAAC,CAAG,EAAAG,CAAS,GAAG,GAAGC,CAAU,MAAMD,IAAYC;AACjD,GAEMC,IAA0B,CAACC,MAAsB;AACrD,aAAW,CAACC,GAAKC,CAAO,KAAKN,GAAkB;AACvC,UAAAO,IAAiBD,IAAUA,IAAUP;AACvC,QAAAK,KAAQG,EAAuB,QAAAF;AAAA,EAAA;AAG9B,SAAA;AACT,GAEMG,IAAc,CAACC,GAAkBC,MAAkB;AAEvD,QAAMC,IADU,IAAI,OAAO,MAAM,EACP,KAAKF,CAAQ,IAAI,MAAM;AACjD,SAAO,GAAGA,CAAQ,GAAGE,CAAS,SAASD,CAAK;AAC9C,GAQaE,IAAqB,CAACC,MAAyB;AACtD,MAAA,CAACA,EAAY,QAAA;AAGjB,MAAI,CAACA,EAAI,WAAW,yBAAyB;AACpC,WAAAA;AAGH,QAAAH,IAAQ,OAAO,cAAc,OAAO,OAEpCL,IAAMF,EAAwBO,CAAK;AAEzC,SAAOF,EAAYK,GAAKf,EAAWO,CAAG,CAAC;AACzC;"}

package/eslint/rules/validate-manifest.cjs

@@ -31,8 +31,8 @@ const hookPermissionsMap = {
   useImagePicker: ['CAMERA'],
 }
 
-// Extract domain from URL (returns domain in CSP format)
-function extractDomain(url) {
+// Extract domain and path from URL (returns {hostname, pathname} for CSP matching)
+function extractDomainAndPath(url) {
   if (!url || typeof url !== 'string') return null
 
   try {
@@ -48,25 +48,65 @@ function extractDomain(url) {
 
     // Parse URL
     const urlObj = new URL(url)
-    return urlObj.hostname
+    return {
+      hostname: urlObj.hostname,
+      pathname: urlObj.pathname,
+    }
   } catch (err) {
     // If URL parsing fails, might be a relative path
     return null
   }
 }
 
-// Check if domain matches a pattern (supports wildcards)
-function domainMatchesPattern(domain, pattern) {
+// Check if a URL matches a trusted_domain pattern
+// Supports: wildcards (*.example.com), paths with CSP semantics
+// CSP path matching: path with trailing slash matches directory, without matches exact or prefix
+function urlMatchesPattern(urlInfo, pattern) {
   if (pattern === '*') return true
-  if (pattern === domain) return true
 
-  // Handle wildcard subdomains (*.example.com)
-  if (pattern.startsWith('*.')) {
-    const basePattern = pattern.slice(2)
-    return domain === basePattern || domain.endsWith(`.${basePattern}`)
+  // Parse the pattern to extract hostname and optional path
+  let patternHostname = pattern
+  let patternPath = null
+
+  // Check if pattern contains a path (has / after the domain)
+  const slashIndex = pattern.indexOf('/')
+  if (slashIndex !== -1) {
+    patternHostname = pattern.slice(0, slashIndex)
+    patternPath = pattern.slice(slashIndex)
+  }
+
+  // First check hostname match
+  let hostnameMatches = false
+
+  if (patternHostname === urlInfo.hostname) {
+    hostnameMatches = true
+  } else if (patternHostname.startsWith('*.')) {
+    // Handle wildcard subdomains (*.example.com)
+    const basePattern = patternHostname.slice(2)
+    hostnameMatches =
+      urlInfo.hostname === basePattern ||
+      urlInfo.hostname.endsWith(`.${basePattern}`)
   }
 
-  return false
+  if (!hostnameMatches) {
+    return false
+  }
+
+  // If no path in pattern, hostname match is sufficient
+  if (!patternPath) {
+    return true
+  }
+
+  // CSP path matching semantics:
+  // - Path ending with / matches that directory and everything under it (prefix match)
+  // - Path without trailing / matches exact path only
+  if (patternPath.endsWith('/')) {
+    // Directory match: URL path must start with pattern path
+    return urlInfo.pathname.startsWith(patternPath)
+  } else {
+    // Exact match only
+    return urlInfo.pathname === patternPath
+  }
 }
 
 module.exports = {
@@ -308,10 +348,11 @@ module.exports = {
         // Check for fetch() calls
         if (node.callee.name === 'fetch' && firstArg.type === 'Literal') {
           const url = firstArg.value
-          const domain = extractDomain(url)
-          if (domain) {
+          const urlInfo = extractDomainAndPath(url)
+          if (urlInfo) {
             requiredDomains.add({
-              domain,
+              urlInfo,
+              url,
               reason: 'fetch() call',
               node,
             })
@@ -326,10 +367,11 @@ module.exports = {
           node.arguments[1].type === 'Literal'
         ) {
           const url = node.arguments[1].value
-          const domain = extractDomain(url)
-          if (domain) {
+          const urlInfo = extractDomainAndPath(url)
+          if (urlInfo) {
             requiredDomains.add({
-              domain,
+              urlInfo,
+              url,
               reason: 'XMLHttpRequest.open() call',
               node,
             })
@@ -340,11 +382,12 @@ module.exports = {
         if (node.callee.name === 'WebSocket' && firstArg.type === 'Literal') {
           const url = firstArg.value
           // WebSocket URLs use ws:// or wss://
-          const domain = url.replace(/^wss?:\/\//, 'https://')
-          const extracted = extractDomain(domain)
-          if (extracted) {
+          const normalizedUrl = url.replace(/^wss?:\/\//, 'https://')
+          const urlInfo = extractDomainAndPath(normalizedUrl)
+          if (urlInfo) {
             requiredDomains.add({
-              domain: extracted,
+              urlInfo,
+              url,
               reason: 'WebSocket connection',
               node,
             })
@@ -354,10 +397,11 @@ module.exports = {
         // Check for EventSource
         if (node.callee.name === 'EventSource' && firstArg.type === 'Literal') {
           const url = firstArg.value
-          const domain = extractDomain(url)
-          if (domain) {
+          const urlInfo = extractDomainAndPath(url)
+          if (urlInfo) {
             requiredDomains.add({
-              domain,
+              urlInfo,
+              url,
               reason: 'EventSource connection',
               node,
             })
@@ -371,10 +415,11 @@ module.exports = {
           firstArg.type === 'Literal'
         ) {
           const url = firstArg.value
-          const domain = extractDomain(url)
-          if (domain) {
+          const urlInfo = extractDomainAndPath(url)
+          if (urlInfo) {
             requiredDomains.add({
-              domain,
+              urlInfo,
+              url,
               reason: 'navigator.sendBeacon() call',
               node,
             })
@@ -389,10 +434,11 @@ module.exports = {
           firstArg.type === 'Literal'
         ) {
           const url = firstArg.value
-          const domain = extractDomain(url)
-          if (domain) {
+          const urlInfo = extractDomainAndPath(url)
+          if (urlInfo) {
             requiredDomains.add({
-              domain,
+              urlInfo,
+              url,
               reason: 'window.open() call',
               node,
             })
@@ -499,9 +545,9 @@ module.exports = {
 
         const attrName = node.name.name
         const url = node.value.value
-        const domain = extractDomain(url)
+        const urlInfo = extractDomainAndPath(url)
 
-        if (!domain) {
+        if (!urlInfo) {
           return
         }
 
@@ -522,7 +568,8 @@ module.exports = {
           ]
           if (supportedElements.includes(elementName)) {
             requiredDomains.add({
-              domain,
+              urlInfo,
+              url,
               reason: `<${elementName}> src attribute`,
               node,
             })
@@ -531,7 +578,8 @@ module.exports = {
         // poster attribute (video)
         else if (attrName === 'poster') {
           requiredDomains.add({
-            domain,
+            urlInfo,
+            url,
             reason: `<${elementName}> poster attribute`,
             node,
           })
@@ -539,7 +587,8 @@ module.exports = {
         // data attribute (object)
         else if (attrName === 'data') {
           requiredDomains.add({
-            domain,
+            urlInfo,
+            url,
             reason: `<${elementName}> data attribute`,
             node,
           })
@@ -547,7 +596,8 @@ module.exports = {
         // action attribute (form)
         else if (attrName === 'action') {
           requiredDomains.add({
-            domain,
+            urlInfo,
+            url,
             reason: `<${elementName}> action attribute`,
             node,
           })
@@ -692,26 +742,26 @@ module.exports = {
         })
 
         // Check trusted domains
-        requiredDomains.forEach(({domain, reason, node}) => {
+        requiredDomains.forEach(({urlInfo, url, reason, node}) => {
           if (!manifest) {
             issues.push({
               messageId: 'manifestNotFound',
-              data: {reason, domain},
+              data: {reason, domain: urlInfo.hostname},
             })
             return
           }
 
           const trustedDomains = manifest.trusted_domains || []
 
-          // Check if domain is trusted (supports wildcards)
+          // Check if URL is trusted (supports wildcards and paths)
           const isTrusted = trustedDomains.some(pattern =>
-            domainMatchesPattern(domain, pattern)
+            urlMatchesPattern(urlInfo, pattern)
           )
 
           if (!isTrusted) {
             issues.push({
               type: 'domain',
-              domain,
+              domain: urlInfo.hostname,
               reason,
               node,
             })

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shopify/shop-minis-react",
   "license": "SEE LICENSE IN LICENSE.txt",
-  "version": "0.4.15",
+  "version": "0.4.17",
   "sideEffects": false,
   "type": "module",
   "engines": {

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

@@ -20,11 +20,11 @@ export interface AlertDialogAtomProps {
   /** The description text shown in the alert dialog body */
   description: string
   /** The text shown in the cancel button */
-  cancelButtonText: string
+  cancelButtonText?: string
   /** The text shown in the confirmation button */
-  confirmationButtonText: string
+  confirmationButtonText?: string
   /** Whether the alert dialog is open */
-  open: boolean
+  open?: boolean
   /** Callback fired when the alert dialog open state changes */
   onOpenChange: (open: boolean) => void
   /** Callback fired when the confirmation button is clicked */

package/src/components/atoms/button.tsx

@@ -7,6 +7,28 @@ import {BaseButton, buttonVariants} from '../ui/button'
 
 import {Touchable} from './touchable'
 
+export interface ButtonDocProps {
+  /** Visual style variant */
+  variant?:
+    | 'default'
+    | 'secondary'
+    | 'destructive'
+    | 'outline'
+    | 'ghost'
+    | 'link'
+    | 'icon'
+  /** Button size */
+  size?: 'default' | 'sm' | 'lg' | 'icon'
+  /** Click handler */
+  onClick?: React.MouseEventHandler<HTMLButtonElement>
+  /** Prevent click from bubbling to parent elements */
+  stopPropagation?: boolean
+  /** Whether the button is disabled */
+  disabled?: boolean
+  /** Button content */
+  children?: React.ReactNode
+}
+
 export function Button({
   className,
   variant,

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

@@ -4,6 +4,21 @@ import {cn} from '../../lib/utils'
 
 import {Button} from './button'
 
+export interface IconButtonProps {
+  /** Click handler */
+  onClick?: () => void
+  /** Whether the button is in a filled/active state */
+  filled?: boolean
+  /** Button size variant */
+  size?: 'default' | 'sm' | 'lg'
+  /** Lucide icon component to render */
+  Icon: LucideIcon
+  /** Custom CSS classes for the button container */
+  buttonStyles?: string
+  /** Custom CSS classes for the icon */
+  iconStyles?: string
+}
+
 export function IconButton({
   onClick,
   filled = false,
@@ -11,14 +26,7 @@ export function IconButton({
   Icon,
   buttonStyles,
   iconStyles,
-}: {
-  onClick?: () => void
-  filled?: boolean
-  size?: 'default' | 'sm' | 'lg'
-  Icon: LucideIcon
-  buttonStyles?: string
-  iconStyles?: string
-}) {
+}: IconButtonProps) {
   const sizeMap = {
     sm: 'size-3',
     default: 'size-4',

package/src/components/atoms/image.test.tsx

@@ -1,13 +1,18 @@
-import {describe, expect, it, vi} from 'vitest'
+import {describe, expect, it, vi, beforeAll} from 'vitest'
 
 import {render, screen, waitFor} from '../../test-utils'
 
 import {Image} from './image'
 
+// Mock URL.revokeObjectURL for jsdom
+beforeAll(() => {
+  URL.revokeObjectURL = vi.fn()
+})
+
 // Mock the util functions
 vi.mock('../../utils', () => ({
-  getThumbhashDataURL: vi.fn((thumbhash?: string) =>
-    thumbhash ? `data:image/png;base64,${thumbhash}` : null
+  getThumbhashBlobURL: vi.fn((thumbhash?: string) =>
+    thumbhash ? `blob:http://localhost/${thumbhash}` : undefined
   ),
   getResizedImageUrl: vi.fn((url?: string) => url),
 }))
@@ -76,7 +81,7 @@ describe('Image', () => {
     expect(wrapper.style.aspectRatio).toBe('16/9')
   })
 
-  it('uses thumbhash as background when provided with fixed aspect ratio', () => {
+  it('uses thumbhash as placeholder when provided with fixed aspect ratio', () => {
     const {container} = render(
       <Image
         src="https://example.com/image.jpg"
@@ -86,10 +91,15 @@ describe('Image', () => {
       />
     )
 
-    const wrapper = container.firstChild as HTMLElement
-    expect(wrapper.style.backgroundImage).toContain(
-      'data:image/png;base64,testThumbhash'
+    // Thumbhash is now rendered as a separate img element (placeholder)
+    const images = container.querySelectorAll('img')
+    expect(images).toHaveLength(2) // placeholder + main image
+    const placeholderImg = images[0]
+    expect(placeholderImg).toHaveAttribute(
+      'src',
+      'blob:http://localhost/testThumbhash'
     )
+    expect(placeholderImg).toHaveAttribute('aria-hidden', 'true')
   })
 
   it('renders with natural sizing when aspectRatio is auto', () => {
@@ -122,13 +132,17 @@ describe('Image', () => {
       />
     )
 
-    const wrapper = container.firstChild as HTMLElement
-    const img = screen.getByRole('img')
-
-    expect(wrapper.style.backgroundImage).toContain(
-      'data:image/png;base64,testThumbhash'
+    // Thumbhash is now rendered as a separate img element (placeholder)
+    const images = container.querySelectorAll('img')
+    expect(images).toHaveLength(2) // placeholder + main image
+    const placeholderImg = images[0]
+    expect(placeholderImg).toHaveAttribute(
+      'src',
+      'blob:http://localhost/testThumbhash'
     )
-    expect(img).toHaveClass('w-full', 'h-auto')
+
+    const mainImg = images[1]
+    expect(mainImg).toHaveClass('w-full', 'h-auto')
   })
 
   it('passes additional props to img element', () => {

package/src/components/atoms/image.tsx

@@ -10,7 +10,24 @@ import {
 } from 'react'
 
 import {cn} from '../../lib/utils'
-import {getThumbhashDataURL, getResizedImageUrl} from '../../utils'
+import {getThumbhashBlobURL, getResizedImageUrl} from '../../utils'
+
+export interface ImageDocProps {
+  /** Remote image URL */
+  src?: string
+  /** File object from useImagePicker (auto-manages blob URL lifecycle) */
+  file?: File
+  /** Thumbhash string for progressive loading placeholder */
+  thumbhash?: string | null
+  /** Aspect ratio (e.g., 16/9, "4/3", or "auto") */
+  aspectRatio?: number | string
+  /** How the image should fit within its container */
+  objectFit?: 'cover' | 'contain' | 'fill' | 'scale-down' | 'none'
+  /** Alt text for accessibility */
+  alt?: string
+  /** Callback when image finishes loading */
+  onLoad?: () => void
+}
 
 type ImageProps = ImgHTMLAttributes<HTMLImageElement> & {
   src?: string
@@ -52,11 +69,20 @@ export const Image = memo(function Image(props: ImageProps) {
     }
   }, [file])
 
-  const thumbhashDataURL = useMemo(
-    () => getThumbhashDataURL(thumbhash ?? undefined),
+  const thumbhashBlobUrl = useMemo(
+    () => getThumbhashBlobURL(thumbhash ?? undefined),
     [thumbhash]
   )
 
+  // Cleanup blob URL when it changes or component unmounts
+  useEffect(() => {
+    return () => {
+      if (thumbhashBlobUrl) {
+        URL.revokeObjectURL(thumbhashBlobUrl)
+      }
+    }
+  }, [thumbhashBlobUrl])
+
   const handleLoad = useCallback(
     (event: React.SyntheticEvent<HTMLImageElement, Event>) => {
       setIsLoaded(true)
@@ -77,13 +103,20 @@ export const Image = memo(function Image(props: ImageProps) {
       style={{
         ...style,
         ...(aspectRatio !== 'auto' && {aspectRatio}),
-        backgroundImage: thumbhashDataURL
-          ? `url(${thumbhashDataURL})`
-          : undefined,
-        backgroundSize: 'cover',
-        backgroundPosition: 'center',
       }}
     >
+      {thumbhashBlobUrl && !isLoaded && (
+        <img
+          className={cn(
+            aspectRatio === 'auto'
+              ? 'w-full h-auto'
+              : 'absolute inset-0 size-full',
+            'object-cover'
+          )}
+          src={thumbhashBlobUrl}
+          aria-hidden="true"
+        />
+      )}
       <img
         className={cn(
           aspectRatio === 'auto'

package/src/components/atoms/list.tsx

@@ -12,7 +12,30 @@ import {Skeleton} from '../ui/skeleton'
 const DEFAULT_REFRESH_PULL_THRESHOLD = 200
 const ELEMENT_BIND_DELAY = 100
 
-interface Props<T = any>
+export interface ListDocProps<T = any> {
+  /** Array of items to render */
+  items: T[]
+  /** Function to render each item */
+  renderItem: (item: T, index: number) => React.ReactNode
+  /** Height of the list container */
+  height?: string | number
+  /** Show scrollbar (default: false) */
+  showScrollbar?: boolean
+  /** Header element rendered at the top of the list */
+  header?: React.ReactNode
+  /** Callback to fetch more items when scrolled to bottom */
+  fetchMore?: () => Promise<void>
+  /** Custom loading component shown while fetching more */
+  loadingComponent?: React.ReactNode
+  /** Callback for pull-to-refresh */
+  onRefresh?: () => Promise<void>
+  /** Whether the list is currently refreshing */
+  refreshing?: boolean
+  /** Enable pull-to-refresh gesture (default: true) */
+  enablePullToRefresh?: boolean
+}
+
+export interface ListProps<T = any>
   extends Omit<
     VirtuosoProps<T, unknown>,
     'data' | 'itemContent' | 'endReached'
@@ -41,7 +64,7 @@ export function List<T = any>({
   refreshing,
   enablePullToRefresh = true,
   ...virtuosoProps
-}: Props<T>) {
+}: ListProps<T>) {
   const inFlightFetchMoreRef = useRef<Promise<void> | null>(null)
   const virtuosoRef = useRef<any>(null)
   const containerRef = useRef<HTMLDivElement>(null)

package/src/components/atoms/text-input.tsx

@@ -3,7 +3,9 @@ import * as React from 'react'
 import {useKeyboardAvoidingView} from '../../hooks'
 import {Input} from '../ui/input'
 
-function TextInput({...props}: React.ComponentProps<'input'>) {
+export type TextInputProps = React.ComponentProps<'input'>
+
+function TextInput({...props}: TextInputProps) {
   const inputRef = React.useRef<HTMLInputElement>(null)
   const {onBlur, onFocus} = useKeyboardAvoidingView()
 

package/src/components/atoms/touchable.tsx

@@ -2,15 +2,26 @@ import * as React from 'react'
 
 import {motion, HTMLMotionProps, useAnimationControls} from 'motion/react'
 
+export interface TouchableDocProps {
+  /** Click handler */
+  onClick?: React.MouseEventHandler<HTMLDivElement>
+  /** Prevent click event from bubbling to parent elements */
+  stopPropagation?: boolean
+  /** Content to render inside the touchable area */
+  children?: React.ReactNode
+}
+
+export interface TouchableProps extends HTMLMotionProps<'div'> {
+  onClick?: React.MouseEventHandler<HTMLDivElement>
+  stopPropagation?: boolean
+}
+
 export const Touchable = ({
   children,
   onClick,
   stopPropagation = false,
   ...props
-}: HTMLMotionProps<'div'> & {
-  onClick?: React.MouseEventHandler<HTMLDivElement>
-  stopPropagation?: boolean
-}) => {
+}: TouchableProps) => {
   const ref = React.useRef<HTMLDivElement>(null)
   const controls = useAnimationControls()
 

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

@@ -17,24 +17,34 @@ export interface VideoPlayerRef {
   pause: () => void
 }
 
-interface VideoPlayerProps {
+export interface VideoPlayerProps {
+  /** The video source URL */
   src: string
-  /**
-   * The format/MIME type of the video.
-   * @default 'video/mp4'
-   */
+  /** The format/MIME type of the video (default: 'video/mp4') */
   format?: string
+  /** Whether the video should be muted */
   muted?: boolean
+  /** URL for the poster image shown before playback */
   poster?: string
+  /** Whether the video should autoplay */
   autoplay?: boolean
+  /** Preload behavior: 'none', 'metadata', or 'auto' */
   preload?: 'none' | 'metadata' | 'auto'
+  /** Whether the video should loop */
   loop?: boolean
+  /** Video width in pixels */
   width?: number
+  /** Video height in pixels */
   height?: number
+  /** Custom play button component */
   playButtonComponent?: React.ReactNode
+  /** Callback when video starts playing */
   onPlay?: () => void
+  /** Callback when video is paused */
   onPause?: () => void
+  /** Callback when video ends */
   onEnded?: () => void
+  /** Callback when video player is ready */
   onReady?: () => void
 }
 
@@ -49,7 +59,7 @@ export const VideoPlayer: React.ForwardRefExoticComponent<
       muted,
       autoplay,
       preload = 'auto',
-      loop = 'false',
+      loop = false,
       width,
       height,
       playButtonComponent,