sanity-plugin-mux-input 2.16.0 → 2.17.0

package/src/components/UploadConfiguration.tsx

@@ -2,11 +2,12 @@ import {DocumentVideoIcon, ErrorOutlineIcon, UploadIcon} from '@sanity/icons'
 import {Box, Button, Card, Dialog, Flex, Label, Radio, Stack, Text} from '@sanity/ui'
 import {uuid} from '@sanity/uuid'
 import LanguagesList from 'iso-639-1'
-import {useEffect, useId, useReducer, useRef, useState} from 'react'
+import {memo, useEffect, useId, useReducer, useRef, useState} from 'react'
 import {FormField} from 'sanity'
 
 import {useFetchFileSize} from '../hooks/useFetchFileSize'
-import {useMediaMetadata} from '../hooks/useMediaMetadata'
+import {useMediaMetadata, type VideoAssetMetadata} from '../hooks/useMediaMetadata'
+import {convertWatermarkToMuxOverlay} from '../util/convertWatermarkToMux'
 import formatBytes from '../util/formatBytes'
 import {formatSeconds} from '../util/formatSeconds'
 import {
@@ -21,7 +22,9 @@ import {
   type SupportedMuxLanguage,
   type UploadConfig,
   type UploadTextTrack,
+  WatermarkConfig,
 } from '../util/types'
+import DraggableWatermark, {WatermarkControls} from './DraggableWatermark'
 import TextTracksEditor, {type TrackAction} from './TextTracksEditor'
 import PlaybackPolicy from './uploadConfiguration/PlaybackPolicy'
 import {
@@ -39,6 +42,7 @@ export type UploadConfigurationStateAction =
   | {action: 'signed_policy'; value: UploadConfig['signed_policy']}
   | {action: 'public_policy'; value: UploadConfig['public_policy']}
   | {action: 'drm_policy'; value: UploadConfig['drm_policy']}
+  | {action: 'watermark'; value: WatermarkConfig}
   | TrackAction
 
 const VIDEO_QUALITY_LEVELS = [
@@ -80,10 +84,13 @@ export default function UploadConfiguration({
   stagedUpload: StagedUpload
   secrets: Secrets
   pluginConfig: PluginConfig
-  startUpload: (settings: MuxNewAssetSettings) => void
+  startUpload: (settings: MuxNewAssetSettings, watermark: WatermarkConfig | undefined) => void
   onClose: () => void
 }) {
   const id = useId()
+  const [watermarkValidationError, setWatermarkValidationError] = useState<string | null>(null)
+  const watermarkPreviewContainerRef = useRef<HTMLDivElement>(null)
+  const watermarkPreviewVideoRef = useRef<HTMLVideoElement>(null)
   const autoTextTracks = useRef<NonNullable<UploadConfig['text_tracks']>>(
     pluginConfig.video_quality === 'plus' && pluginConfig.defaultAutogeneratedSubtitleLang
       ? [
@@ -130,6 +137,8 @@ export default function UploadConfiguration({
           return Object.assign({}, prev, {[action.action]: action.value})
         case 'drm_policy':
           return Object.assign({}, prev, {[action.action]: action.value})
+        case 'watermark':
+          return Object.assign({}, prev, {watermark: action.value})
         // Updating individual tracks
         case 'track': {
           const text_tracks = [...prev.text_tracks]
@@ -254,7 +263,12 @@ export default function UploadConfiguration({
   const {disableTextTrackConfig, disableUploadConfig} = pluginConfig
   const skipConfig = disableTextTrackConfig && disableUploadConfig
   useEffect(() => {
-    if (skipConfig) startUpload(formatUploadConfig(config, secrets))
+    if (skipConfig) {
+      const {settings, watermark} = formatUploadConfig(config, secrets, {
+        videoAspectRatio: videoAssetMetadata?.aspectRatio,
+      })
+      startUpload(settings, watermark)
+    }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [])
   if (skipConfig) return null
@@ -275,7 +289,7 @@ export default function UploadConfiguration({
       onClose={onClose}
     >
       <Stack padding={4} space={2}>
-        {validationError && (
+        {(validationError || watermarkValidationError) && (
           <Card padding={3} tone="critical" radius={2} marginBottom={2}>
             <Flex gap={2} align="flex-start">
               <ErrorOutlineIcon width={20} height={20} />
@@ -283,7 +297,7 @@ export default function UploadConfiguration({
                 <Text size={1} weight="semibold">
                   Validation Error
                 </Text>
-                <Text size={1}>{validationError}</Text>
+                <Text size={1}>{validationError || watermarkValidationError}</Text>
               </Stack>
             </Flex>
           </Card>
@@ -377,27 +391,38 @@ export default function UploadConfiguration({
             </FormField>
 
             {!basicConfig && (
-              <FormField title="Additional Configuration">
-                <Stack space={3}>
-                  <PlaybackPolicy id={id} config={config} secrets={secrets} dispatch={dispatch} />
-                  {maxSupportedResolution > 0 && (
-                    <ResolutionTierSelector
-                      id={id}
-                      config={config}
-                      dispatch={dispatch}
-                      maxSupportedResolution={maxSupportedResolution}
-                    />
-                  )}
-                  <StaticRenditionSelector id={id} config={config} dispatch={dispatch} />
-                  {!disableTextTrackConfig && (
-                    <TextTracksEditor
-                      tracks={config.text_tracks}
-                      dispatch={dispatch}
-                      defaultLang={pluginConfig.defaultAutogeneratedSubtitleLang}
-                    />
-                  )}
-                </Stack>
-              </FormField>
+              <>
+                <FormField title="Additional Configuration">
+                  <Stack space={3}>
+                    <PlaybackPolicy id={id} config={config} secrets={secrets} dispatch={dispatch} />
+                    {maxSupportedResolution > 0 && (
+                      <ResolutionTierSelector
+                        id={id}
+                        config={config}
+                        dispatch={dispatch}
+                        maxSupportedResolution={maxSupportedResolution}
+                      />
+                    )}
+                    <StaticRenditionSelector id={id} config={config} dispatch={dispatch} />
+                    {!disableTextTrackConfig && (
+                      <TextTracksEditor
+                        tracks={config.text_tracks}
+                        dispatch={dispatch}
+                        defaultLang={pluginConfig.defaultAutogeneratedSubtitleLang}
+                      />
+                    )}
+                  </Stack>
+                </FormField>
+                <WatermarkSection
+                  config={config}
+                  dispatch={dispatch}
+                  stagedUpload={stagedUpload}
+                  videoAssetMetadata={videoAssetMetadata}
+                  watermarkPreviewContainerRef={watermarkPreviewContainerRef}
+                  watermarkPreviewVideoRef={watermarkPreviewVideoRef}
+                  onValidationChange={setWatermarkValidationError}
+                />
+              </>
             )}
           </Stack>
         )}
@@ -415,7 +440,10 @@ export default function UploadConfiguration({
             tone="positive"
             onClick={() => {
               if (!validationError) {
-                startUpload(formatUploadConfig(config, secrets))
+                const {settings, watermark} = formatUploadConfig(config, secrets, {
+                  videoAspectRatio: videoAssetMetadata?.aspectRatio,
+                })
+                startUpload(settings, watermark)
               }
             }}
           />
@@ -449,7 +477,14 @@ function setAdvancedPlaybackPolicy(
   return advanced_playback_policies
 }
 
-function formatUploadConfig(config: UploadConfig, secrets: Secrets): MuxNewAssetSettings {
+function formatUploadConfig(
+  config: UploadConfig,
+  secrets: Secrets,
+  options?: {videoAspectRatio?: number | null}
+): {
+  settings: MuxNewAssetSettings
+  watermark?: WatermarkConfig
+} {
   const generated_subtitles = config.text_tracks
     .filter<AutogeneratedTextTrack>(isAutogeneratedTrack)
     .map<{name: string; language_code: SupportedMuxLanguage}>((track) => ({
@@ -457,36 +492,201 @@ function formatUploadConfig(config: UploadConfig, secrets: Secrets): MuxNewAsset
       language_code: track.language_code,
     }))
 
-  return {
-    input: [
-      {
-        type: 'video',
-        generated_subtitles: generated_subtitles.length > 0 ? generated_subtitles : undefined,
+  const inputs: NonNullable<MuxNewAssetSettings['input']> = [
+    {
+      type: 'video',
+      generated_subtitles: generated_subtitles.length > 0 ? generated_subtitles : undefined,
+    },
+    ...config.text_tracks.filter<CustomTextTrack>(isCustomTextTrack).reduce(
+      (acc, track) => {
+        if (track.language_code && track.file && track.name) {
+          acc.push({
+            url: track.file.contents,
+            type: 'text',
+            text_type: track.type === 'subtitles' ? 'subtitles' : undefined,
+            language_code: track.language_code,
+            name: track.name,
+            closed_captions: track.type === 'captions',
+          })
+        }
+        return acc
       },
-      ...config.text_tracks.filter<CustomTextTrack>(isCustomTextTrack).reduce(
-        (acc, track) => {
-          if (track.language_code && track.file && track.name) {
-            acc.push({
-              url: track.file.contents,
-              type: 'text',
-              text_type: track.type === 'subtitles' ? 'subtitles' : undefined,
-              language_code: track.language_code,
-              name: track.name,
-              closed_captions: track.type === 'captions',
-            })
-          }
-          return acc
-        },
-        [] as NonNullable<MuxNewAssetSettings['input']>
-      ),
-    ],
-    static_renditions:
-      config.static_renditions.length > 0
-        ? config.static_renditions.map((resolution) => ({resolution}))
-        : undefined,
-    advanced_playback_policies: setAdvancedPlaybackPolicy(config, secrets),
-    max_resolution_tier: config.max_resolution_tier,
-    video_quality: config.video_quality,
-    normalize_audio: config.normalize_audio,
+      [] as NonNullable<MuxNewAssetSettings['input']>
+    ),
+  ]
+
+  if (config.watermark?.imageUrl) {
+    const watermarkForMux: WatermarkConfig = {...config.watermark, enabled: true}
+    const overlaySettings = convertWatermarkToMuxOverlay(watermarkForMux, {
+      videoAspectRatio: options?.videoAspectRatio ?? undefined,
+      units: 'px',
+    })
+    if (overlaySettings) {
+      inputs.push({
+        url: config.watermark.imageUrl,
+        overlay_settings: overlaySettings,
+      } as NonNullable<MuxNewAssetSettings['input']>[number])
+    }
   }
+
+  return {
+    settings: {
+      input: inputs,
+      static_renditions:
+        config.static_renditions.length > 0
+          ? config.static_renditions.map((resolution) => ({resolution}))
+          : undefined,
+      advanced_playback_policies: setAdvancedPlaybackPolicy(config, secrets),
+      max_resolution_tier: config.max_resolution_tier,
+      video_quality: config.video_quality,
+      normalize_audio: config.normalize_audio,
+    },
+    watermark: config.watermark?.imageUrl
+      ? ({...config.watermark, enabled: true} as WatermarkConfig)
+      : undefined,
+  }
+}
+
+function WatermarkSection({
+  config,
+  dispatch,
+  stagedUpload,
+  videoAssetMetadata,
+  watermarkPreviewContainerRef,
+  watermarkPreviewVideoRef,
+  onValidationChange,
+}: {
+  config: UploadConfig
+  dispatch: (action: UploadConfigurationStateAction) => void
+  stagedUpload: StagedUpload
+  videoAssetMetadata: VideoAssetMetadata | null
+  watermarkPreviewContainerRef: React.RefObject<HTMLDivElement | null>
+  watermarkPreviewVideoRef: React.RefObject<HTMLVideoElement | null>
+  onValidationChange: (error: string | null) => void
+}) {
+  if (videoAssetMetadata?.isAudioOnly !== false) return null
+  return (
+    <FormField
+      title="Watermark"
+      description={
+        <>
+          Add a watermark overlay to your video using Mux&apos;s native watermark support.{' '}
+          <a
+            href="https://www.mux.com/docs/guides/add-watermarks-to-your-videos"
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            Learn more about Mux watermarks.
+          </a>
+        </>
+      }
+    >
+      <Stack space={3}>
+        <WatermarkControls
+          watermark={config.watermark || {enabled: false}}
+          onChange={(watermark) => {
+            dispatch({action: 'watermark', value: watermark})
+          }}
+          onValidationChange={onValidationChange}
+          previewContainerRef={watermarkPreviewContainerRef}
+          previewVideoRef={watermarkPreviewVideoRef}
+        />
+        {config.watermark?.imageUrl &&
+          stagedUpload.type === 'file' &&
+          // Canvas preview is only shown in "Canvas" mode (no explicit overlay_settings)
+          !config.watermark.overlay_settings && (
+            <WatermarkPreview
+              stagedUpload={stagedUpload}
+              watermark={config.watermark}
+              videoAspectRatio={videoAssetMetadata.aspectRatio}
+              onWatermarkChange={(watermark) => {
+                dispatch({action: 'watermark', value: watermark})
+              }}
+              previewContainerRef={watermarkPreviewContainerRef}
+              videoRef={watermarkPreviewVideoRef}
+            />
+          )}
+      </Stack>
+    </FormField>
+  )
 }
+
+// Memoized preview component to prevent unnecessary re-renders
+const WatermarkPreview = memo(function WatermarkPreview({
+  stagedUpload,
+  watermark,
+  onWatermarkChange,
+  videoAspectRatio,
+  previewContainerRef,
+  videoRef,
+}: {
+  stagedUpload: StagedUpload
+  watermark: WatermarkConfig
+  onWatermarkChange: (watermark: WatermarkConfig) => void
+  videoAspectRatio?: number | null
+  previewContainerRef: React.RefObject<HTMLDivElement | null>
+  videoRef: React.RefObject<HTMLVideoElement | null>
+}) {
+  // Initialize video source only once
+  useEffect(() => {
+    if (videoRef.current && stagedUpload.type === 'file') {
+      const file = stagedUpload.files[0]
+      const url = URL.createObjectURL(file)
+      videoRef.current.src = url
+
+      return () => {
+        URL.revokeObjectURL(url)
+      }
+    }
+    return undefined
+  }, [stagedUpload, videoRef])
+
+  const isVertical =
+    videoAspectRatio !== null && videoAspectRatio !== undefined && videoAspectRatio < 1
+
+  return (
+    <Card
+      tone="transparent"
+      border
+      style={{
+        overflow: 'hidden',
+        // For vertical videos, center the preview and limit its width
+        display: 'flex',
+        justifyContent: 'center',
+      }}
+    >
+      {/* Inner container that exactly matches the video aspect ratio - no padding, no letterbox */}
+      <div
+        ref={previewContainerRef}
+        style={{
+          position: 'relative',
+          // For vertical videos: limit width so the preview doesn't get too tall
+          // For horizontal videos: use full width
+          width: isVertical ? 'auto' : '100%',
+          aspectRatio: videoAspectRatio ? String(videoAspectRatio) : '16/9',
+          ...(isVertical ? {height: '400px', maxHeight: '50vh'} : {minHeight: '200px'}),
+          overflow: 'hidden',
+        }}
+      >
+        <video
+          ref={videoRef}
+          style={{
+            position: 'absolute',
+            top: 0,
+            left: 0,
+            width: '100%',
+            height: '100%',
+            objectFit: 'fill',
+            display: 'block',
+          }}
+        />
+        <DraggableWatermark
+          watermark={watermark}
+          onChange={onWatermarkChange}
+          containerRef={previewContainerRef as React.RefObject<HTMLDivElement>}
+          videoElementRef={videoRef as React.RefObject<HTMLVideoElement>}
+        />
+      </div>
+    </Card>
+  )
+})

package/src/components/Uploader.tsx

@@ -197,9 +197,13 @@ export default function Uploader(props: Props) {
    * the Mux configuration for the direct asset upload.
    *
    * @param settings The Mux new_asset_settings object to send to Sanity
+   * @param watermark Optional watermark configuration
    * @returns
    */
-  const startUpload = (settings: MuxNewAssetSettings) => {
+  const startUpload = (
+    settings: MuxNewAssetSettings,
+    watermark?: import('../util/types').WatermarkConfig
+  ) => {
     const {stagedUpload} = state
     if (!stagedUpload || uploadRef.current) return
     dispatch({action: 'commitUpload'})
@@ -211,6 +215,7 @@ export default function Uploader(props: Props) {
           client: props.client,
           url: stagedUpload.url,
           settings,
+          watermark,
         })
         break
       case 'file':
@@ -218,6 +223,7 @@ export default function Uploader(props: Props) {
           client: props.client,
           file: stagedUpload.files[0],
           settings,
+          watermark,
         }).pipe(
           takeUntil(
             cancelUploadButton.observable.pipe(

package/src/components/VideoPlayer.tsx

@@ -37,6 +37,7 @@ export default function VideoPlayer({
 
   const isAudio = assetIsAudio(asset)
   const muxPlayer = useRef<MuxPlayerRefAttributes>(null)
+  const playerContainerRef = useRef<HTMLDivElement>(null)
   const [error, setError] = useState<Error>()
 
   /* Playback ID that will be used to play the video */
@@ -149,6 +150,7 @@ export default function VideoPlayer({
   return (
     <>
       <Card
+        ref={playerContainerRef}
         tone="transparent"
         style={{
           aspectRatio: aspectRatio,

package/src/hooks/useMediaMetadata.ts

@@ -8,6 +8,7 @@ export interface VideoAssetMetadata {
   isAudioOnly?: boolean
   duration?: number
   size?: number
+  aspectRatio?: number
 }
 
 export function useMediaMetadata(stagedUpload: StagedUpload) {
@@ -48,6 +49,7 @@ export function useMediaMetadata(stagedUpload: StagedUpload) {
         const width = videoElement.videoWidth
         const height = videoElement.videoHeight
         const isAudioOnly = width <= 0 && height <= 0
+        const aspectRatio = width / height
         setVideoAssetMetadata((old) => {
           return {
             ...old,
@@ -55,6 +57,7 @@ export function useMediaMetadata(stagedUpload: StagedUpload) {
             width: width,
             height: height,
             isAudioOnly: isAudioOnly,
+            aspectRatio: aspectRatio,
           }
         })
       },

package/src/util/convertWatermarkToMux.ts

@@ -0,0 +1,160 @@
+import {roundPxString} from './roundPxString'
+import type {MuxOverlaySettings, WatermarkConfig} from './types'
+
+/**
+ * Converts a draggable watermark position (x, y percentages) to Mux's overlay_settings format.
+ *
+ * @param watermark - The watermark configuration with position, size, and opacity
+ * @returns Mux overlay_settings object
+ * @see {@link https://www.mux.com/docs/guides/add-watermarks-to-your-videos}
+ */
+export function convertWatermarkToMuxOverlay(
+  watermark: WatermarkConfig,
+  options?: {
+    /**
+     * Video aspect ratio (width / height). Needed for correct vertical positioning,
+     * especially on vertical videos.
+     */
+    videoAspectRatio?: number
+    /**
+     * Unit to emit for margins/width when generating overlay_settings from Canvas mode.
+     * - 'px' will generate pixel strings according to Mux's scaling rules:
+     *   values are applied as if the video were scaled to 1920x1080 (horizontal)
+     *   or 1080x1920 (vertical).
+     * - '%' preserves existing behavior.
+     */
+    units?: '%' | 'px'
+  }
+): MuxOverlaySettings | null {
+  if (!watermark.enabled || !watermark.imageUrl) {
+    return null
+  }
+
+  const size = watermark.size || 20
+  const opacity = watermark.opacity ?? 0.7
+
+  /**
+   * Convert a percentage to whole-pixel string, using Mux's base dimensions:
+   * - Horizontal video: 1920x1080
+   * - Vertical video:   1080x1920
+   */
+  const toPxString = (valuePercent: number, axis: 'x' | 'y') => {
+    const videoAspectRatio = options?.videoAspectRatio ?? 16 / 9
+    const isVertical = videoAspectRatio > 0 && videoAspectRatio < 1
+    const baseW = isVertical ? 1080 : 1920
+    const baseH = isVertical ? 1920 : 1080
+    const base = axis === 'x' ? baseW : baseH
+    const px = (valuePercent / 100) * base
+    let rounded = Math.round(px)
+    // Avoid sending 0px (and JS -0); keep sign for negative margins.
+    if (rounded === 0) rounded = px < 0 ? -1 : 1
+    return `${rounded}px`
+  }
+
+  const normalizeToPixels = (value: string | undefined, axis: 'x' | 'y'): string | undefined => {
+    if (!value) return value
+    const trimmed = value.trim()
+    if (trimmed.endsWith('px')) {
+      return roundPxString(trimmed)
+    }
+    if (trimmed.endsWith('%')) {
+      const n = Number(trimmed.slice(0, -1))
+      if (!Number.isFinite(n)) return value
+      return toPxString(n, axis)
+    }
+    return value
+  }
+
+  // If user provided explicit overlay settings, use them (Mux-documented format).
+  // When `options.units === 'px'`, we normalize both % and px to whole-pixel strings,
+  // honoring vertical vs horizontal video bases.
+  if (watermark.overlay_settings) {
+    const widthValue = watermark.overlay_settings.width
+    const widthNormalized =
+      options?.units === 'px' ? normalizeToPixels(widthValue, 'x') : widthValue
+    return {
+      ...watermark.overlay_settings,
+      horizontal_margin:
+        options?.units === 'px'
+          ? (normalizeToPixels(watermark.overlay_settings.horizontal_margin, 'x') ??
+            watermark.overlay_settings.horizontal_margin)
+          : watermark.overlay_settings.horizontal_margin,
+      vertical_margin:
+        options?.units === 'px'
+          ? (normalizeToPixels(watermark.overlay_settings.vertical_margin, 'y') ??
+            watermark.overlay_settings.vertical_margin)
+          : watermark.overlay_settings.vertical_margin,
+      width: widthNormalized ?? `${size}%`,
+      opacity: watermark.overlay_settings.opacity ?? `${Math.round(opacity * 100)}%`,
+    }
+  }
+
+  const position = watermark.position || {x: 50, y: 50}
+
+  /**
+   * Our UI stores watermark position as the *center point* in percentages.
+   * Mux margins are interpreted relative to an *edge* (based on align).
+   *
+   * To make "corner" placements match what the user dragged, we convert from
+   * center-position to top-left margins by subtracting half the watermark size.
+   *
+   * Note: `size` is a percentage of video width. Mux `width` is also expressed
+   * as a percentage of the video width, so we can reuse it for horizontal math.
+   * For vertical math, we approximate using the same percentage to keep behavior
+   * consistent with the current draggable UI (which also uses `size` in both axes
+   * for bounds).
+   */
+  // Allow negative margins to compensate for rounding / letterboxing edge-cases.
+  // We still clamp to a sane range so values don't explode.
+  const clampPercent = (value: number) => Math.max(-100, Math.min(100, value))
+
+  // Mux accepts percentage strings; avoid sending an exact "0%" by nudging to 0.01%.
+  // This also handles the JS -0 edge case and tiny floating point remnants.
+  const toPercentString = (value: number) => {
+    const epsilon = 1e-9
+    const isZeroish = value === 0 || Object.is(value, -0) || Math.abs(value) < epsilon
+    return `${isZeroish ? 0.01 : value}%`
+  }
+
+  const watermarkWidthPercentOfVideoWidth = size
+
+  /**
+   * Convert watermark height into % of video height.
+   * height% = (watermarkWidthPx / imageAspectRatio) / videoHeightPx
+   *         = (size% * videoWidthPx / imageAspectRatio) / videoHeightPx
+   *         = size% * (videoWidthPx/videoHeightPx) / imageAspectRatio
+   *         = size% * videoAspectRatio / imageAspectRatio
+   */
+  const videoAspectRatio = options?.videoAspectRatio ?? 16 / 9
+  const imageAspectRatio = watermark.imageAspectRatio ?? 1
+  const watermarkHeightPercentOfVideoHeight = Math.max(
+    0,
+    Math.min(100, (size * videoAspectRatio) / imageAspectRatio)
+  )
+
+  const halfWidth = watermarkWidthPercentOfVideoWidth / 2
+  const halfHeight = watermarkHeightPercentOfVideoHeight / 2
+
+  const leftMargin = clampPercent(
+    Math.min(position.x - halfWidth, 100 - watermarkWidthPercentOfVideoWidth)
+  )
+  const topMargin = clampPercent(
+    Math.min(position.y - halfHeight, 100 - watermarkHeightPercentOfVideoHeight)
+  )
+
+  const units = options?.units ?? '%'
+  const marginX = units === 'px' ? toPxString(leftMargin, 'x') : toPercentString(leftMargin)
+  const marginY = units === 'px' ? toPxString(topMargin, 'y') : toPercentString(topMargin)
+  const width = units === 'px' ? toPxString(size, 'x') : `${size}%`
+
+  const overlaySettings: MuxOverlaySettings = {
+    vertical_align: 'top',
+    vertical_margin: marginY,
+    horizontal_align: 'left',
+    horizontal_margin: marginX,
+    width,
+    opacity: `${Math.round(opacity * 100)}%`,
+  }
+
+  return overlaySettings
+}

package/src/util/roundPxString.ts

@@ -0,0 +1,16 @@
+/**
+ * Rounds the numeric part of a px string to the nearest integer.
+ * Returns undefined if the value is not a valid px string or not a finite number.
+ * Avoids sending 0px (and JS -0); snaps to ±1 instead.
+ */
+export function roundPxString(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined
+  const trimmed = value.trim()
+  if (!trimmed.endsWith('px')) return undefined
+  const n = Number(trimmed.slice(0, -2))
+  if (!Number.isFinite(n)) return undefined
+  let rounded = Math.round(n)
+  // Avoid sending 0px (and JS -0); keep sign when negative.
+  if (rounded === 0) rounded = n < 0 ? -1 : 1
+  return `${rounded}px`
+}