From f58481f42124218bc42142087eb642cc295f709a Mon Sep 17 00:00:00 2001
From: Yasuhiro Matsumoto <mattn.jp@gmail.com>
Date: Tue, 17 Mar 2026 23:50:11 +0900
Subject: [PATCH 01/16] Add 'pumopacity' option for popup menu transparency

Add a new 'pumopacity' option (0-100) that controls the transparency
of the popup completion menu (pum).  When set, the underlying buffer
content shows through the pum's padding areas with blended attributes.

- pumopacity=0: fully opaque (default, normal pum behavior)
- pumopacity=1-99: partially transparent, higher = more transparent
- pumopacity=100: same as 0 (fully opaque)

Implementation saves the background screen content on the first pum
display and restores it for padding/space cells using hl_blend_attr()
for color blending.  Text cells are drawn normally with pum highlight.
Works with both cterm and termguicolors/GUI.
---
 src/option.h            |   1 +
 src/optiondefs.h        |   4 +
 src/popupmenu.c         | 243 ++++++++++++++++++++++++++++++++++++----
 src/proto/popupmenu.pro |   1 +
 4 files changed, 230 insertions(+), 19 deletions(-)

diff --git a/src/option.h b/src/option.h
index 305a92ad88e86b..a38dba67764259 100644
--- a/src/option.h
+++ b/src/option.h
@@ -553,6 +553,7 @@ EXTERN long	p_acl;		// 'autocompletedelay'
 EXTERN char_u	*p_csl;		// 'completeslash'
 #endif
 EXTERN long	p_ph;		// 'pumheight'
+EXTERN long	p_po;		// 'pumopacity'
 EXTERN long	p_pw;		// 'pumwidth'
 EXTERN long	p_pmw;		// 'pummaxwidth'
 EXTERN char_u	*p_pb;		// 'pumborder'
diff --git a/src/optiondefs.h b/src/optiondefs.h
index 33d0a711032a13..d78db3fe0cf80a 100644
--- a/src/optiondefs.h
+++ b/src/optiondefs.h
@@ -2088,6 +2088,10 @@ static struct vimoption options[] =
     {"pumheight",   "ph",   P_NUM|P_VI_DEF,
 			    (char_u *)&p_ph, PV_NONE, NULL, NULL,
 			    {(char_u *)0L, (char_u *)0L} SCTX_INIT},
+    {"pumopacity",  NULL,   P_NUM|P_VI_DEF,
+			    (char_u *)&p_po, PV_NONE,
+			    did_set_pumopacity, NULL,
+			    {(char_u *)100L, (char_u *)100L} SCTX_INIT},
     {"pummaxwidth", "pmw",   P_NUM|P_VI_DEF,
 			    (char_u *)&p_pmw, PV_NONE, NULL, NULL,
 			    {(char_u *)0L, (char_u *)0L} SCTX_INIT},
diff --git a/src/popupmenu.c b/src/popupmenu.c
index b8c72d44f8cd07..678dc5afb05c32 100644
--- a/src/popupmenu.c
+++ b/src/popupmenu.c
@@ -49,6 +49,15 @@ static int pum_border = 0;
 static int pum_margin = 0;	// margin of 1 cell on left and right
 static int pum_shadow = 0;
 
+// Opacity: saved background screen content (persists across pum_redraw calls)
+static sattr_T	*pum_bg_attrs = NULL;
+static schar_T	*pum_bg_lines = NULL;
+static u8char_T	*pum_bg_linesUC = NULL;
+static u8char_T	*pum_bg_linesC[MAX_MCO] = {NULL};
+static int	pum_bg_top = 0;
+static int	pum_bg_bot = 0;
+static int	pum_bg_cols = 0;
+
 // Border characters
 static struct {
     int top;
@@ -878,6 +887,87 @@ pum_align_order(int *order)
     order[2] = is_default ? CPT_MENU : cia_flags % 10;
 }
 
+static void pum_free_bg(void);
+
+/*
+ * Called when 'pumopacity' is changed.
+ */
+    char *
+did_set_pumopacity(optset_T *args UNUSED)
+{
+    if (p_po < 0)
+	p_po = 0;
+    if (p_po > 100)
+	p_po = 100;
+
+    // Invalidate cached background so it gets re-saved.
+    pum_free_bg();
+
+    if (pum_visible())
+    {
+	call_update_screen = TRUE;
+	pum_redraw();
+    }
+    return NULL;
+}
+
+    static void
+pum_free_bg(void)
+{
+    int k;
+    VIM_CLEAR(pum_bg_attrs);
+    VIM_CLEAR(pum_bg_lines);
+    VIM_CLEAR(pum_bg_linesUC);
+    for (k = 0; k < MAX_MCO; ++k)
+	VIM_CLEAR(pum_bg_linesC[k]);
+    pum_bg_top = 0;
+    pum_bg_bot = 0;
+    pum_bg_cols = 0;
+}
+
+/*
+ * For pumopacity: restore saved background characters in a range,
+ * but apply a blended attribute so the pum background is still visible.
+ * "pum_attr" is the popup menu highlight attribute for this area.
+ */
+    static void
+pum_opacity_fill(int row, int col_start, int col_end, int pum_attr)
+{
+    int	    c;
+    int	    blend = MIN((int)p_po, 99);
+
+    if (pum_bg_lines == NULL || row < pum_bg_top || row >= pum_bg_bot)
+	return;
+    if (col_start < 0)
+	col_start = 0;
+    if (col_end > pum_bg_cols)
+	col_end = pum_bg_cols;
+
+    for (c = col_start; c < col_end; ++c)
+    {
+	int off = LineOffset[row] + c;
+	int soff = (row - pum_bg_top) * pum_bg_cols + c;
+	int underlying_attr = pum_bg_attrs[soff];
+
+	// Restore the underlying character.
+	ScreenLines[off] = pum_bg_lines[soff];
+	if (enc_utf8 && pum_bg_linesUC != NULL && ScreenLinesUC != NULL)
+	{
+	    int k;
+	    ScreenLinesUC[off] = pum_bg_linesUC[soff];
+	    for (k = 0; k < MAX_MCO; ++k)
+		if (pum_bg_linesC[k] != NULL && ScreenLinesC[k] != NULL)
+		    ScreenLinesC[k][off] = pum_bg_linesC[k][soff];
+	}
+
+	// Blend underlying attr with pum attr: shows underlying text
+	// through the pum background.
+	ScreenAttrs[off] = hl_blend_attr(underlying_attr, pum_attr,
+								blend, TRUE);
+	screen_char(off, row, c);
+    }
+}
+
 /*
  * Redraw the popup menu, using "pum_first" and "pum_selected".
  */
@@ -906,6 +996,7 @@ pum_redraw(void)
     int		orig_attr = -1;
     int		scroll_range = pum_size - pum_height;
     bool	override_success;
+    int		opacity_active = (p_po > 0 && p_po < 100);
 
     // Use current window for highlight overrides when using 'winhighlight'
     override_success = push_highlight_overrides(curwin->w_hl, curwin->w_hl_len);
@@ -925,11 +1016,90 @@ pum_redraw(void)
     if (call_update_screen)
     {
 	call_update_screen = FALSE;
-	// Do not redraw in pum_may_redraw() and don't draw in the area where
-	// the popup menu will be.
-	pum_will_redraw = TRUE;
-	update_screen(0);
-	pum_will_redraw = FALSE;
+	if (opacity_active && pum_bg_lines != NULL)
+	{
+	    // Already have saved background; skip update_screen to avoid
+	    // flickering.  Just do a normal pum_will_redraw update.
+	    pum_will_redraw = TRUE;
+	    update_screen(0);
+	    pum_will_redraw = FALSE;
+	}
+	else if (opacity_active)
+	{
+	    // For opacity: draw background including the area under the
+	    // pum, then save it.
+	    pum_pretend_not_visible = TRUE;
+	    update_screen(0);
+	    pum_pretend_not_visible = FALSE;
+
+	    // Save background to static buffers.
+	    if (ScreenLines != NULL && ScreenAttrs != NULL)
+	    {
+		int	save_top, save_bot, save_ncells, k;
+
+		pum_free_bg();
+		save_top = pum_row - pum_border;
+		save_bot = pum_row + pum_height + pum_border
+					    + (pum_shadow ? 1 : 0) + 1;
+		if (save_top < 0)
+		    save_top = 0;
+		if (save_bot > screen_Rows)
+		    save_bot = screen_Rows;
+		pum_bg_top = save_top;
+		pum_bg_bot = save_bot;
+		pum_bg_cols = screen_Columns;
+		if (save_top < save_bot)
+		{
+		    save_ncells = (save_bot - save_top) * screen_Columns;
+		    pum_bg_attrs = LALLOC_MULT(sattr_T, save_ncells);
+		    pum_bg_lines = LALLOC_MULT(schar_T, save_ncells);
+		    if (enc_utf8)
+		    {
+			pum_bg_linesUC = LALLOC_MULT(u8char_T, save_ncells);
+			for (k = 0; k < MAX_MCO; ++k)
+			    pum_bg_linesC[k] = LALLOC_MULT(u8char_T,
+							    save_ncells);
+		    }
+		    if (pum_bg_attrs != NULL && pum_bg_lines != NULL)
+		    {
+			for (int r = save_top; r < save_bot; ++r)
+			{
+			    int soff = (r - save_top) * screen_Columns;
+			    int loff = LineOffset[r];
+
+			    mch_memmove(pum_bg_attrs + soff,
+				    ScreenAttrs + loff,
+				    screen_Columns * sizeof(sattr_T));
+			    mch_memmove(pum_bg_lines + soff,
+				    ScreenLines + loff,
+				    screen_Columns * sizeof(schar_T));
+			    if (enc_utf8 && pum_bg_linesUC != NULL
+						&& ScreenLinesUC != NULL)
+			    {
+				mch_memmove(pum_bg_linesUC + soff,
+					ScreenLinesUC + loff,
+					screen_Columns * sizeof(u8char_T));
+				for (k = 0; k < MAX_MCO; ++k)
+				    if (pum_bg_linesC[k] != NULL
+						    && ScreenLinesC[k] != NULL)
+					mch_memmove(pum_bg_linesC[k] + soff,
+						ScreenLinesC[k] + loff,
+						screen_Columns
+						    * sizeof(u8char_T));
+			    }
+			}
+		    }
+		}
+	    }
+	}
+	else
+	{
+	    // Do not redraw in pum_may_redraw() and don't draw in the area
+	    // where the popup menu will be.
+	    pum_will_redraw = TRUE;
+	    update_screen(0);
+	    pum_will_redraw = FALSE;
+	}
     }
 
     // never display more than we have
@@ -964,16 +1134,30 @@ pum_redraw(void)
 	attr = highlight_attr[hlf];
 
 	// prepend a space if there is room
-#ifdef FEAT_RIGHTLEFT
-	if (pum_rl)
+	if (opacity_active)
 	{
-	    if (pum_col < curwin->w_wincol + curwin->w_width - 1 - pum_border)
-		screen_putchar(' ', row, pum_col + 1, attr);
+#ifdef FEAT_RIGHTLEFT
+	    if (pum_rl)
+		pum_opacity_fill(row, pum_col + 1, pum_col + 2, attr);
+	    else
+#endif
+		if (pum_col > pum_border)
+		    pum_opacity_fill(row, pum_col - 1, pum_col, attr);
 	}
 	else
+	{
+#ifdef FEAT_RIGHTLEFT
+	    if (pum_rl)
+	    {
+		if (pum_col < curwin->w_wincol + curwin->w_width - 1
+								- pum_border)
+		    screen_putchar(' ', row, pum_col + 1, attr);
+	    }
+	    else
 #endif
-	    if (pum_col > pum_border)
-		screen_putchar(' ', row, pum_col - 1, attr);
+		if (pum_col > pum_border)
+		    screen_putchar(' ', row, pum_col - 1, attr);
+	}
 
 	// Display each entry, use two spaces for a Tab.
 	// Do this 3 times and order from p_cia
@@ -1016,15 +1200,24 @@ pum_redraw(void)
 #ifdef FEAT_RIGHTLEFT
 	    if (pum_rl)
 	    {
-		screen_fill(row, row + 1, pum_col - basic_width - n + 1,
-						col + 1, ' ', ' ', orig_attr);
+		if (opacity_active)
+		    pum_opacity_fill(row, pum_col - basic_width - n + 1,
+						    col + 1, orig_attr);
+		else
+		    screen_fill(row, row + 1,
+			    pum_col - basic_width - n + 1,
+			    col + 1, ' ', ' ', orig_attr);
 		col = pum_col - basic_width - n;
 	    }
 	    else
 #endif
 	    {
-		screen_fill(row, row + 1, col, pum_col + basic_width + n,
-							' ', ' ', orig_attr);
+		if (opacity_active)
+		    pum_opacity_fill(row, col,
+				    pum_col + basic_width + n, orig_attr);
+		else
+		    screen_fill(row, row + 1, col,
+			    pum_col + basic_width + n, ' ', ' ', orig_attr);
 		col = pum_col + basic_width + n;
 	    }
 	    totwidth = basic_width + n;
@@ -1032,12 +1225,23 @@ pum_redraw(void)
 
 #ifdef FEAT_RIGHTLEFT
 	if (pum_rl)
-	    screen_fill(row, row + 1, pum_col - pum_width + 1, col + 1, ' ',
-							    ' ', orig_attr);
+	{
+	    if (opacity_active)
+		pum_opacity_fill(row, pum_col - pum_width + 1, col + 1,
+								orig_attr);
+	    else
+		screen_fill(row, row + 1, pum_col - pum_width + 1, col + 1,
+							' ', ' ', orig_attr);
+	}
 	else
 #endif
-	    screen_fill(row, row + 1, col, pum_col + pum_width, ' ', ' ',
-								orig_attr);
+	{
+	    if (opacity_active)
+		pum_opacity_fill(row, col, pum_col + pum_width, orig_attr);
+	    else
+		screen_fill(row, row + 1, col, pum_col + pum_width,
+							' ', ' ', orig_attr);
+	}
 	pum_draw_scrollbar(row, i, thumb_pos, thumb_height);
 
 	++row;
@@ -1427,6 +1631,7 @@ pum_set_selected(int n, int repeat UNUSED)
     void
 pum_undisplay(void)
 {
+    pum_free_bg();
     pum_array = NULL;
     redraw_all_later(UPD_NOT_VALID);
     redraw_tabline = TRUE;
diff --git a/src/proto/popupmenu.pro b/src/proto/popupmenu.pro
index 66316dfab25b82..0e50ca8cc84a76 100644
--- a/src/proto/popupmenu.pro
+++ b/src/proto/popupmenu.pro
@@ -3,6 +3,7 @@ void pum_set_border(int enable);
 void pum_set_shadow(int enable);
 void pum_set_margin(int enable);
 void pum_display(pumitem_T *array, int size, int selected);
+char *did_set_pumopacity(optset_T *args);
 void pum_call_update_screen(void);
 int pum_under_menu(int row, int col, int only_redrawing);
 void pum_redraw(void);

From c072e408615fa66be85311919f8a6110c34979b3 Mon Sep 17 00:00:00 2001
From: Yasuhiro Matsumoto <mattn.jp@gmail.com>
Date: Wed, 18 Mar 2026 01:20:09 +0900
Subject: [PATCH 02/16] pumopacity: move blend processing into
 screen_puts_len/screen_fill

Move pum opacity blending from post-processing (pum_opacity_fill) into
screen_puts_len() and screen_fill() using the screen_pum_blend global.
This avoids double-blending issues and ensures text and space cells
use consistent blend calculations.

- screen_puts_len: blend text background with underlying attr
- screen_fill: restore underlying character and blend attrs
- pum_bg_* variables moved to globals.h for access from screen.c
- screen_pum_blend set during pum_redraw, cleared after
---
 src/globals.h   | 13 +++++++
 src/popupmenu.c | 90 +++++++++++++++++--------------------------------
 src/screen.c    | 40 ++++++++++++++++++++++
 3 files changed, 84 insertions(+), 59 deletions(-)

diff --git a/src/globals.h b/src/globals.h
index 4b40873a96c13a..f4ec70120259aa 100644
--- a/src/globals.h
+++ b/src/globals.h
@@ -125,6 +125,19 @@ EXTERN int	screen_zindex INIT(= 0);
 EXTERN win_T	*screen_opacity_popup INIT(= NULL);
 #endif
 
+// Blend value for popup menu opacity (0 = off, 1-99 = blend level).
+// Set during pum drawing when 'pumopacity' is active.
+EXTERN int	screen_pum_blend INIT(= 0);
+
+// Saved background screen content for pum opacity blending.
+EXTERN sattr_T	*pum_bg_attrs INIT(= NULL);
+EXTERN schar_T	*pum_bg_lines INIT(= NULL);
+EXTERN u8char_T	*pum_bg_linesUC INIT(= NULL);
+EXTERN u8char_T	*pum_bg_linesC[MAX_MCO];
+EXTERN int	pum_bg_top INIT(= 0);
+EXTERN int	pum_bg_bot INIT(= 0);
+EXTERN int	pum_bg_cols INIT(= 0);
+
 EXTERN int	screen_Rows INIT(= 0);	    // actual size of ScreenLines[]
 EXTERN int	screen_Columns INIT(= 0);   // actual size of ScreenLines[]
 
diff --git a/src/popupmenu.c b/src/popupmenu.c
index 678dc5afb05c32..648bd4599bdaf5 100644
--- a/src/popupmenu.c
+++ b/src/popupmenu.c
@@ -49,14 +49,10 @@ static int pum_border = 0;
 static int pum_margin = 0;	// margin of 1 cell on left and right
 static int pum_shadow = 0;
 
-// Opacity: saved background screen content (persists across pum_redraw calls)
-static sattr_T	*pum_bg_attrs = NULL;
-static schar_T	*pum_bg_lines = NULL;
-static u8char_T	*pum_bg_linesUC = NULL;
-static u8char_T	*pum_bg_linesC[MAX_MCO] = {NULL};
-static int	pum_bg_top = 0;
-static int	pum_bg_bot = 0;
-static int	pum_bg_cols = 0;
+// Opacity: pum_opacity_active is set during pum_redraw.
+// The pum_bg_* globals are defined in globals.h.
+static int	pum_opacity_active = FALSE;
+static void pum_opacity_fill(int row, int col_start, int col_end, int pum_attr);
 
 // Border characters
 static struct {
@@ -758,8 +754,9 @@ pum_display_ltr_text(
     if (truncated)
     {
 	if (over_cell > 0)
-	    screen_fill(row, row + 1, col + cells,
-		    col + cells + over_cell, ' ', ' ', attr);
+	    if (over_cell > 0)
+		screen_fill(row, row + 1, col + cells,
+			col + cells + over_cell, ' ', ' ', attr);
 
 	screen_putchar(trunc, row, col + cells + over_cell, trunc_attr);
     }
@@ -934,7 +931,7 @@ pum_free_bg(void)
 pum_opacity_fill(int row, int col_start, int col_end, int pum_attr)
 {
     int	    c;
-    int	    blend = MIN((int)p_po, 99);
+    int	    blend = 100 - (int)p_po;
 
     if (pum_bg_lines == NULL || row < pum_bg_top || row >= pum_bg_bot)
 	return;
@@ -998,6 +995,8 @@ pum_redraw(void)
     bool	override_success;
     int		opacity_active = (p_po > 0 && p_po < 100);
 
+    pum_opacity_active = opacity_active;
+
     // Use current window for highlight overrides when using 'winhighlight'
     override_success = push_highlight_overrides(curwin->w_hl, curwin->w_hl_len);
 
@@ -1120,6 +1119,10 @@ pum_redraw(void)
     screen_zindex = POPUPMENU_ZINDEX;
 #endif
 
+    // Set blend for screen_puts_len / screen_fill to use.
+    if (opacity_active)
+	screen_pum_blend = 100 - (int)p_po;
+
     // Draw border and shadow first if enabled
     if (pum_border)
 	pum_draw_border();
@@ -1134,30 +1137,17 @@ pum_redraw(void)
 	attr = highlight_attr[hlf];
 
 	// prepend a space if there is room
-	if (opacity_active)
-	{
 #ifdef FEAT_RIGHTLEFT
-	    if (pum_rl)
-		pum_opacity_fill(row, pum_col + 1, pum_col + 2, attr);
-	    else
-#endif
-		if (pum_col > pum_border)
-		    pum_opacity_fill(row, pum_col - 1, pum_col, attr);
+	if (pum_rl)
+	{
+	    if (pum_col < curwin->w_wincol + curwin->w_width - 1
+							    - pum_border)
+		screen_putchar(' ', row, pum_col + 1, attr);
 	}
 	else
-	{
-#ifdef FEAT_RIGHTLEFT
-	    if (pum_rl)
-	    {
-		if (pum_col < curwin->w_wincol + curwin->w_width - 1
-								- pum_border)
-		    screen_putchar(' ', row, pum_col + 1, attr);
-	    }
-	    else
 #endif
-		if (pum_col > pum_border)
-		    screen_putchar(' ', row, pum_col - 1, attr);
-	}
+	    if (pum_col > pum_border)
+		screen_putchar(' ', row, pum_col - 1, attr);
 
 	// Display each entry, use two spaces for a Tab.
 	// Do this 3 times and order from p_cia
@@ -1200,24 +1190,15 @@ pum_redraw(void)
 #ifdef FEAT_RIGHTLEFT
 	    if (pum_rl)
 	    {
-		if (opacity_active)
-		    pum_opacity_fill(row, pum_col - basic_width - n + 1,
-						    col + 1, orig_attr);
-		else
-		    screen_fill(row, row + 1,
-			    pum_col - basic_width - n + 1,
-			    col + 1, ' ', ' ', orig_attr);
+		screen_fill(row, row + 1, pum_col - basic_width - n + 1,
+						col + 1, ' ', ' ', orig_attr);
 		col = pum_col - basic_width - n;
 	    }
 	    else
 #endif
 	    {
-		if (opacity_active)
-		    pum_opacity_fill(row, col,
-				    pum_col + basic_width + n, orig_attr);
-		else
-		    screen_fill(row, row + 1, col,
-			    pum_col + basic_width + n, ' ', ' ', orig_attr);
+		screen_fill(row, row + 1, col, pum_col + basic_width + n,
+							' ', ' ', orig_attr);
 		col = pum_col + basic_width + n;
 	    }
 	    totwidth = basic_width + n;
@@ -1225,28 +1206,19 @@ pum_redraw(void)
 
 #ifdef FEAT_RIGHTLEFT
 	if (pum_rl)
-	{
-	    if (opacity_active)
-		pum_opacity_fill(row, pum_col - pum_width + 1, col + 1,
-								orig_attr);
-	    else
-		screen_fill(row, row + 1, pum_col - pum_width + 1, col + 1,
-							' ', ' ', orig_attr);
-	}
+	    screen_fill(row, row + 1, pum_col - pum_width + 1, col + 1,
+							    ' ', ' ', orig_attr);
 	else
 #endif
-	{
-	    if (opacity_active)
-		pum_opacity_fill(row, col, pum_col + pum_width, orig_attr);
-	    else
-		screen_fill(row, row + 1, col, pum_col + pum_width,
-							' ', ' ', orig_attr);
-	}
+	    screen_fill(row, row + 1, col, pum_col + pum_width, ' ', ' ',
+								orig_attr);
 	pum_draw_scrollbar(row, i, thumb_pos, thumb_height);
 
 	++row;
     }
 
+    screen_pum_blend = 0;
+
 #ifdef FEAT_PROP_POPUP
     screen_zindex = 0;
 #endif
diff --git a/src/screen.c b/src/screen.c
index 78927c163d4a57..f872289dda7554 100644
--- a/src/screen.c
+++ b/src/screen.c
@@ -1772,6 +1772,17 @@ screen_puts_len(
 		ScreenLines[off + mbyte_blen] = 0;
 	    ScreenLines[off] = c;
 	    ScreenAttrs[off] = attr;
+	    // For pum opacity: blend text background with underlying.
+	    if (screen_pum_blend > 0
+		    && pum_bg_attrs != NULL
+		    && row >= pum_bg_top && row < pum_bg_bot
+		    && col < pum_bg_cols)
+	    {
+		int soff = (row - pum_bg_top) * pum_bg_cols + col;
+
+		ScreenAttrs[off] = hl_blend_attr(pum_bg_attrs[soff],
+					    attr, screen_pum_blend, FALSE);
+	    }
 	    ScreenCols[off] = -1;
 	    if (enc_utf8)
 	    {
@@ -2652,6 +2663,35 @@ screen_fill(
 		}
 skip_opacity_fill:
 #endif
+		// For pum opacity: blend pum background with underlying.
+		// Only for space cells; text cells are handled normally.
+		if (screen_pum_blend > 0 && c == ' '
+			&& pum_bg_attrs != NULL
+			&& row >= pum_bg_top && row < pum_bg_bot
+			&& col < pum_bg_cols)
+		{
+		    int soff = (row - pum_bg_top) * pum_bg_cols + col;
+		    int underlying_attr = pum_bg_attrs[soff];
+
+		    // Restore underlying character so text shows through.
+		    ScreenLines[off] = pum_bg_lines[soff];
+		    if (enc_utf8 && pum_bg_linesUC != NULL
+						&& ScreenLinesUC != NULL)
+		    {
+			int k;
+			ScreenLinesUC[off] = pum_bg_linesUC[soff];
+			for (k = 0; k < MAX_MCO; ++k)
+			    if (pum_bg_linesC[k] != NULL
+						    && ScreenLinesC[k] != NULL)
+				ScreenLinesC[k][off] = pum_bg_linesC[k][soff];
+		    }
+		    // Blend both fg and bg so underlying text visibility
+		    // changes with pumopacity.
+		    ScreenAttrs[off] = hl_blend_attr(underlying_attr,
+					    attr, screen_pum_blend, TRUE);
+		    screen_char(off, row, col);
+		    goto next_col;
+		}
 #if defined(FEAT_GUI) || defined(UNIX)
 		// The bold trick may make a single row of pixels appear in
 		// the next character.  When a bold character is removed, the

From 31efdf13b77ef317a7e77fda771f89353a9c0476 Mon Sep 17 00:00:00 2001
From: Yasuhiro Matsumoto <mattn.jp@gmail.com>
Date: Wed, 18 Mar 2026 01:45:54 +0900
Subject: [PATCH 03/16] pumopacity: add hl_pum_blend_attr() for correct fg/bg
 blending

Add hl_pum_blend_attr() in highlight.c that blends fg and bg in the
correct direction for pum opacity:
- fg: pum_bg toward underlying_fg (opaque = text hidden, transparent = visible)
- bg: pum_bg toward underlying_bg (opaque = pum color, transparent = underlying)

This is different from hl_blend_attr(blend_fg=TRUE) which blends fg
in the opposite direction (designed for popup-over-popup compositing).

Use hl_pum_blend_attr() in screen_fill for pum space cells.
Use UPD_CLEAR in did_set_pumopacity to reset stale blended ScreenAttrs.
---
 src/highlight.c         | 132 ++++++++++++++++++++++++++++++++++++++++
 src/popupmenu.c         |   3 +
 src/proto/highlight.pro |   1 +
 src/screen.c            |   7 +--
 4 files changed, 139 insertions(+), 4 deletions(-)

diff --git a/src/highlight.c b/src/highlight.c
index 19d13907a11ea8..885cd22afed258 100644
--- a/src/highlight.c
+++ b/src/highlight.c
@@ -3321,6 +3321,138 @@ hl_blend_attr(int char_attr, int popup_attr, int blend, int blend_fg UNUSED)
     return get_attr_entry(&term_attr_table, &new_en);
 }
 
+/*
+ * Blend for pum opacity space cells: keep underlying fg, blend bg.
+ * This is different from hl_blend_attr(blend_fg=TRUE) where fg blends
+ * in the wrong direction for pum use.
+ */
+    int
+hl_pum_blend_attr(int char_attr, int popup_attr, int blend)
+{
+    attrentry_T *char_aep = NULL;
+    attrentry_T *popup_aep;
+    attrentry_T new_en;
+
+#ifdef FEAT_GUI
+    if (gui.in_use)
+    {
+	if (char_attr > HL_ALL)
+	    char_aep = syn_gui_attr2entry(char_attr);
+	if (char_aep != NULL)
+	    new_en = *char_aep;
+	else
+	{
+	    CLEAR_FIELD(new_en);
+	    new_en.ae_u.gui.fg_color = INVALCOLOR;
+	    new_en.ae_u.gui.bg_color = INVALCOLOR;
+	    new_en.ae_u.gui.sp_color = INVALCOLOR;
+	    if (char_attr <= HL_ALL)
+		new_en.ae_attr = char_attr;
+	}
+	if (popup_attr > HL_ALL)
+	{
+	    popup_aep = syn_gui_attr2entry(popup_attr);
+	    if (popup_aep != NULL)
+	    {
+		// Blend fg: pum_bg toward underlying_fg.
+		// blend=0 (opaque): fg = pum_bg (text hidden)
+		// blend=100 (transparent): fg = underlying_fg (text visible)
+		if (popup_aep->ae_u.gui.bg_color != INVALCOLOR)
+		{
+		    int base_fg = 0xFFFFFF;
+		    if (char_aep != NULL
+			    && char_aep->ae_u.gui.fg_color != INVALCOLOR)
+			base_fg = char_aep->ae_u.gui.fg_color;
+		    new_en.ae_u.gui.fg_color = blend_colors(
+			    popup_aep->ae_u.gui.bg_color, base_fg, blend);
+		}
+		// Blend bg: popup bg toward underlying bg.
+		if (popup_aep->ae_u.gui.bg_color != INVALCOLOR)
+		{
+		    guicolor_T underlying_bg = INVALCOLOR;
+		    if (char_aep != NULL)
+			underlying_bg = char_aep->ae_u.gui.bg_color;
+		    new_en.ae_u.gui.bg_color = blend_colors(
+			    popup_aep->ae_u.gui.bg_color,
+			    underlying_bg, blend);
+		}
+	    }
+	}
+	return get_attr_entry(&gui_attr_table, &new_en);
+    }
+#endif
+
+    if (IS_CTERM)
+    {
+	if (char_attr > HL_ALL)
+	    char_aep = syn_cterm_attr2entry(char_attr);
+	if (char_aep != NULL)
+	    new_en = *char_aep;
+	else
+	{
+	    CLEAR_FIELD(new_en);
+#ifdef FEAT_TERMGUICOLORS
+	    new_en.ae_u.cterm.bg_rgb = INVALCOLOR;
+	    new_en.ae_u.cterm.fg_rgb = INVALCOLOR;
+	    new_en.ae_u.cterm.ul_rgb = INVALCOLOR;
+#endif
+	    if (char_attr <= HL_ALL)
+		new_en.ae_attr = char_attr;
+	}
+	if (popup_attr > HL_ALL)
+	{
+	    popup_aep = syn_cterm_attr2entry(popup_attr);
+	    if (popup_aep != NULL)
+	    {
+		// Blend cterm fg: use popup bg (hides text when opaque)
+		if (popup_aep->ae_u.cterm.fg_color > 0)
+		    new_en.ae_u.cterm.fg_color =
+					popup_aep->ae_u.cterm.fg_color;
+		// Use popup cterm bg.
+		if (popup_aep->ae_u.cterm.bg_color > 0)
+		    new_en.ae_u.cterm.bg_color =
+					popup_aep->ae_u.cterm.bg_color;
+#ifdef FEAT_TERMGUICOLORS
+		// Blend fg_rgb: pum_bg toward underlying_fg.
+		if (popup_aep->ae_u.cterm.bg_rgb != INVALCOLOR)
+		{
+		    int base_fg = 0xFFFFFF;
+		    if (char_aep != NULL
+			    && char_aep->ae_u.cterm.fg_rgb != INVALCOLOR)
+			base_fg = char_aep->ae_u.cterm.fg_rgb;
+		    new_en.ae_u.cterm.fg_rgb = blend_colors(
+			    popup_aep->ae_u.cterm.bg_rgb, base_fg, blend);
+		}
+		// Blend bg_rgb.
+		if (popup_aep->ae_u.cterm.bg_rgb != INVALCOLOR)
+		{
+		    guicolor_T underlying_bg = INVALCOLOR;
+		    if (char_aep != NULL)
+			underlying_bg = char_aep->ae_u.cterm.bg_rgb;
+		    new_en.ae_u.cterm.bg_rgb = blend_colors(
+			    popup_aep->ae_u.cterm.bg_rgb,
+			    underlying_bg, blend);
+		}
+#endif
+	    }
+	}
+	return get_attr_entry(&cterm_attr_table, &new_en);
+    }
+
+    // term mode
+    if (char_attr > HL_ALL)
+	char_aep = syn_term_attr2entry(char_attr);
+    if (char_aep != NULL)
+	new_en = *char_aep;
+    else
+    {
+	CLEAR_FIELD(new_en);
+	if (char_attr <= HL_ALL)
+	    new_en.ae_attr = char_attr;
+    }
+    return get_attr_entry(&term_attr_table, &new_en);
+}
+
 #ifdef FEAT_GUI
     attrentry_T *
 syn_gui_attr2entry(int attr)
diff --git a/src/popupmenu.c b/src/popupmenu.c
index 648bd4599bdaf5..da9e25a447e928 100644
--- a/src/popupmenu.c
+++ b/src/popupmenu.c
@@ -902,6 +902,9 @@ did_set_pumopacity(optset_T *args UNUSED)
 
     if (pum_visible())
     {
+	// Force full screen clear so ScreenAttrs doesn't retain
+	// stale blended values from the previous pumopacity.
+	redraw_all_later(UPD_CLEAR);
 	call_update_screen = TRUE;
 	pum_redraw();
     }
diff --git a/src/proto/highlight.pro b/src/proto/highlight.pro
index 5d923173962519..856ce86b37dde9 100644
--- a/src/proto/highlight.pro
+++ b/src/proto/highlight.pro
@@ -21,6 +21,7 @@ int get_gui_attr_idx(int attr, guicolor_T fg, guicolor_T bg);
 void clear_hl_tables(void);
 int hl_combine_attr(int char_attr, int prim_attr);
 int hl_blend_attr(int char_attr, int popup_attr, int blend, int blend_fg);
+int hl_pum_blend_attr(int char_attr, int popup_attr, int blend);
 attrentry_T *syn_gui_attr2entry(int attr);
 int syn_attr2attr(int attr);
 attrentry_T *syn_term_attr2entry(int attr);
diff --git a/src/screen.c b/src/screen.c
index f872289dda7554..e57284f2074441 100644
--- a/src/screen.c
+++ b/src/screen.c
@@ -2685,10 +2685,9 @@ screen_fill(
 						    && ScreenLinesC[k] != NULL)
 				ScreenLinesC[k][off] = pum_bg_linesC[k][soff];
 		    }
-		    // Blend both fg and bg so underlying text visibility
-		    // changes with pumopacity.
-		    ScreenAttrs[off] = hl_blend_attr(underlying_attr,
-					    attr, screen_pum_blend, TRUE);
+		    // Keep underlying fg, blend bg only.
+		    ScreenAttrs[off] = hl_pum_blend_attr(underlying_attr,
+					    attr, screen_pum_blend);
 		    screen_char(off, row, col);
 		    goto next_col;
 		}

From 97c745ebf928e5b8e0860191e385ac8b4ab7c658 Mon Sep 17 00:00:00 2001
From: Yasuhiro Matsumoto <mattn.jp@gmail.com>
Date: Wed, 18 Mar 2026 01:54:16 +0900
Subject: [PATCH 04/16] pumopacity: remove dead code and fix duplicate
 condition

- Remove unused pum_opacity_fill() function and forward declaration
- Remove unused pum_opacity_active variable
- Remove duplicate if (over_cell > 0) condition
- Remove unnecessary comment
---
 src/popupmenu.c | 54 ++-----------------------------------------------
 1 file changed, 2 insertions(+), 52 deletions(-)

diff --git a/src/popupmenu.c b/src/popupmenu.c
index da9e25a447e928..527ae797336e16 100644
--- a/src/popupmenu.c
+++ b/src/popupmenu.c
@@ -49,10 +49,6 @@ static int pum_border = 0;
 static int pum_margin = 0;	// margin of 1 cell on left and right
 static int pum_shadow = 0;
 
-// Opacity: pum_opacity_active is set during pum_redraw.
-// The pum_bg_* globals are defined in globals.h.
-static int	pum_opacity_active = FALSE;
-static void pum_opacity_fill(int row, int col_start, int col_end, int pum_attr);
 
 // Border characters
 static struct {
@@ -754,9 +750,8 @@ pum_display_ltr_text(
     if (truncated)
     {
 	if (over_cell > 0)
-	    if (over_cell > 0)
-		screen_fill(row, row + 1, col + cells,
-			col + cells + over_cell, ' ', ' ', attr);
+	    screen_fill(row, row + 1, col + cells,
+		    col + cells + over_cell, ' ', ' ', attr);
 
 	screen_putchar(trunc, row, col + cells + over_cell, trunc_attr);
     }
@@ -925,49 +920,6 @@ pum_free_bg(void)
     pum_bg_cols = 0;
 }
 
-/*
- * For pumopacity: restore saved background characters in a range,
- * but apply a blended attribute so the pum background is still visible.
- * "pum_attr" is the popup menu highlight attribute for this area.
- */
-    static void
-pum_opacity_fill(int row, int col_start, int col_end, int pum_attr)
-{
-    int	    c;
-    int	    blend = 100 - (int)p_po;
-
-    if (pum_bg_lines == NULL || row < pum_bg_top || row >= pum_bg_bot)
-	return;
-    if (col_start < 0)
-	col_start = 0;
-    if (col_end > pum_bg_cols)
-	col_end = pum_bg_cols;
-
-    for (c = col_start; c < col_end; ++c)
-    {
-	int off = LineOffset[row] + c;
-	int soff = (row - pum_bg_top) * pum_bg_cols + c;
-	int underlying_attr = pum_bg_attrs[soff];
-
-	// Restore the underlying character.
-	ScreenLines[off] = pum_bg_lines[soff];
-	if (enc_utf8 && pum_bg_linesUC != NULL && ScreenLinesUC != NULL)
-	{
-	    int k;
-	    ScreenLinesUC[off] = pum_bg_linesUC[soff];
-	    for (k = 0; k < MAX_MCO; ++k)
-		if (pum_bg_linesC[k] != NULL && ScreenLinesC[k] != NULL)
-		    ScreenLinesC[k][off] = pum_bg_linesC[k][soff];
-	}
-
-	// Blend underlying attr with pum attr: shows underlying text
-	// through the pum background.
-	ScreenAttrs[off] = hl_blend_attr(underlying_attr, pum_attr,
-								blend, TRUE);
-	screen_char(off, row, c);
-    }
-}
-
 /*
  * Redraw the popup menu, using "pum_first" and "pum_selected".
  */
@@ -998,8 +950,6 @@ pum_redraw(void)
     bool	override_success;
     int		opacity_active = (p_po > 0 && p_po < 100);
 
-    pum_opacity_active = opacity_active;
-
     // Use current window for highlight overrides when using 'winhighlight'
     override_success = push_highlight_overrides(curwin->w_hl, curwin->w_hl_len);
 

From 5311443ab2545d5f6f52af70bb3028e76a7160ae Mon Sep 17 00:00:00 2001
From: Yasuhiro Matsumoto <mattn.jp@gmail.com>
Date: Wed, 18 Mar 2026 14:22:34 +0900
Subject: [PATCH 05/16] pumopacity: add tests for 'pumopacity' option

Add option value test (default, clamping, reset) and screendump tests
for pumopacity=50 and pumopacity=100.
---
 src/testdir/dumps/Test_pumopacity_100.dump | 20 +++++++
 src/testdir/dumps/Test_pumopacity_50.dump  | 20 +++++++
 src/testdir/test_popup.vim                 | 69 ++++++++++++++++++++++
 3 files changed, 109 insertions(+)
 create mode 100644 src/testdir/dumps/Test_pumopacity_100.dump
 create mode 100644 src/testdir/dumps/Test_pumopacity_50.dump

diff --git a/src/testdir/dumps/Test_pumopacity_100.dump b/src/testdir/dumps/Test_pumopacity_100.dump
new file mode 100644
index 00000000000000..d9e44da0f7160e
--- /dev/null
+++ b/src/testdir/dumps/Test_pumopacity_100.dump
@@ -0,0 +1,20 @@
+|h+0&#ffffff0|e|l@1|o| |w|o|r|l|d| @63
+|h|e|l@1|o| |v|i|m| @65
+|h|e|l@1|o| |o|p|a|c|i|t|y| @61
+|h|e|l|p| |m|e| @67
+|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G
+|R|O|U|N|D| @69
+|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G
+|R|O|U|N|D| @69
+|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G
+|R|O|U|N|D| @69
+|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G
+|R|O|U|N|D| @69
+|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G
+|R|O|U|N|D| @69
+|h|e|l@1|o> @69
+|h+0#0000001#e0e0e08|e|l@1|o| @9| +0#4040ff13#ffffff0@59
+|h+0#0000001#ffd7ff255|e|l|p| @10| +0#4040ff13#ffffff0@59
+|~| @73
+|~| @73
+|-+2#0000000&@1| |K|e|y|w|o|r|d| |c|o|m|p|l|e|t|i|o|n| |(|^|N|^|P|)| |m+0#00e0003&|a|t|c|h| |1| |o|f| |2| +0#0000000&@33
diff --git a/src/testdir/dumps/Test_pumopacity_50.dump b/src/testdir/dumps/Test_pumopacity_50.dump
new file mode 100644
index 00000000000000..d9e44da0f7160e
--- /dev/null
+++ b/src/testdir/dumps/Test_pumopacity_50.dump
@@ -0,0 +1,20 @@
+|h+0&#ffffff0|e|l@1|o| |w|o|r|l|d| @63
+|h|e|l@1|o| |v|i|m| @65
+|h|e|l@1|o| |o|p|a|c|i|t|y| @61
+|h|e|l|p| |m|e| @67
+|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G
+|R|O|U|N|D| @69
+|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G
+|R|O|U|N|D| @69
+|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G
+|R|O|U|N|D| @69
+|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G
+|R|O|U|N|D| @69
+|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G
+|R|O|U|N|D| @69
+|h|e|l@1|o> @69
+|h+0#0000001#e0e0e08|e|l@1|o| @9| +0#4040ff13#ffffff0@59
+|h+0#0000001#ffd7ff255|e|l|p| @10| +0#4040ff13#ffffff0@59
+|~| @73
+|~| @73
+|-+2#0000000&@1| |K|e|y|w|o|r|d| |c|o|m|p|l|e|t|i|o|n| |(|^|N|^|P|)| |m+0#00e0003&|a|t|c|h| |1| |o|f| |2| +0#0000000&@33
diff --git a/src/testdir/test_popup.vim b/src/testdir/test_popup.vim
index bf400d18f946c1..72486d67ef596d 100644
--- a/src/testdir/test_popup.vim
+++ b/src/testdir/test_popup.vim
@@ -2420,4 +2420,73 @@ func Test_popup_shadow_hiddenchar()
   call StopVimInTerminal(buf)
 endfunc
 
+" Test 'pumopacity' option value clamping and default
+func Test_pumopacity_option()
+  call assert_equal(100, &pumopacity)
+
+  set pumopacity=50
+  call assert_equal(50, &pumopacity)
+
+  " Clamp to 0
+  set pumopacity=-10
+  call assert_equal(0, &pumopacity)
+
+  " Clamp to 100
+  set pumopacity=200
+  call assert_equal(100, &pumopacity)
+
+  set pumopacity=0
+  call assert_equal(0, &pumopacity)
+
+  set pumopacity&
+  call assert_equal(100, &pumopacity)
+endfunc
+
+" Test pumopacity with screendump: background text should show through
+func Test_pumopacity_screendump()
+  CheckScreendump
+  let lines =<< trim END
+    set pumopacity=50
+    set completeopt=menu
+    call setline(1, ['hello world', 'hello vim', 'hello opacity', 'help me'])
+    for i in range(5)
+      call append(line('$'), repeat('BACKGROUND', 8))
+    endfor
+    normal gg
+  END
+  call writefile(lines, 'Xpumopacity', 'D')
+  let buf = RunVimInTerminal('-S Xpumopacity', {})
+  call TermWait(buf)
+  call term_sendkeys(buf, "Gohel\<C-N>")
+  call TermWait(buf, 100)
+  call VerifyScreenDump(buf, 'Test_pumopacity_50', {})
+  call term_sendkeys(buf, "\<C-E>\<Esc>u")
+  call TermWait(buf)
+  call StopVimInTerminal(buf)
+endfunc
+
+" Test pumopacity=100 (fully opaque, same as default)
+func Test_pumopacity_100()
+  CheckScreendump
+  let lines =<< trim END
+    set pumopacity=100
+    set completeopt=menu
+    call setline(1, ['hello world', 'hello vim', 'hello opacity', 'help me'])
+    for i in range(5)
+      call append(line('$'), repeat('BACKGROUND', 8))
+    endfor
+    normal gg
+  END
+  call writefile(lines, 'Xpumopacity100', 'D')
+  let buf = RunVimInTerminal('-S Xpumopacity100', {})
+  call TermWait(buf)
+  call term_sendkeys(buf, "Gohel\<C-N>")
+  call TermWait(buf, 100)
+  call VerifyScreenDump(buf, 'Test_pumopacity_100', {})
+  call term_sendkeys(buf, "\<C-E>\<Esc>u")
+  call TermWait(buf)
+  call StopVimInTerminal(buf)
+endfunc
+
+
 " vim: shiftwidth=2 sts=2 expandtab

From f7cf5cbc0d693d1ff06d4d4537f1a2ce43612b02 Mon Sep 17 00:00:00 2001
From: Yasuhiro Matsumoto <mattn.jp@gmail.com>
Date: Wed, 18 Mar 2026 14:34:01 +0900
Subject: [PATCH 06/16] pumopacity: remove stray blank line in popupmenu.c

---
 src/popupmenu.c | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/popupmenu.c b/src/popupmenu.c
index 527ae797336e16..c0cd637311c27e 100644
--- a/src/popupmenu.c
+++ b/src/popupmenu.c
@@ -49,7 +49,6 @@ static int pum_border = 0;
 static int pum_margin = 0;	// margin of 1 cell on left and right
 static int pum_shadow = 0;
 
-
 // Border characters
 static struct {
     int top;

From 1abdde60c0cf49c5207fe65964c6641dbd035bf4 Mon Sep 17 00:00:00 2001
From: Yasuhiro Matsumoto <mattn.jp@gmail.com>
Date: Wed, 18 Mar 2026 14:46:24 +0900
Subject: [PATCH 07/16] pumopacity: fix build error when FEAT_PROP_POPUP is not
 defined

Move next_col label outside of #ifdef FEAT_PROP_POPUP since it is also
used by the pum opacity code path.
---
 src/screen.c | 2 --
 1 file changed, 2 deletions(-)

diff --git a/src/screen.c b/src/screen.c
index e57284f2074441..436de3195b5f21 100644
--- a/src/screen.c
+++ b/src/screen.c
@@ -2737,9 +2737,7 @@ screen_fill(
 		if (!did_delete || c != ' ')
 		    screen_char(off, row, col);
 	    }
-#ifdef FEAT_PROP_POPUP
 next_col:
-#endif
 	    ScreenCols[off] = -1;
 	    ++off;
 	    if (col == start_col)

From 26ba5c64641bba20ed9204956f44c0368b351e23 Mon Sep 17 00:00:00 2001
From: Yasuhiro Matsumoto <mattn.jp@gmail.com>
Date: Wed, 18 Mar 2026 14:47:50 +0900
Subject: [PATCH 08/16] pumopacity: mark blend param UNUSED in
 hl_pum_blend_attr()

The blend parameter is only used inside FEAT_GUI and FEAT_TERMGUICOLORS
blocks, so it triggers -Wunused-parameter when both are disabled.
---
 src/highlight.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/highlight.c b/src/highlight.c
index 885cd22afed258..fb393e59e4cd59 100644
--- a/src/highlight.c
+++ b/src/highlight.c
@@ -3327,7 +3327,7 @@ hl_blend_attr(int char_attr, int popup_attr, int blend, int blend_fg UNUSED)
  * in the wrong direction for pum use.
  */
     int
-hl_pum_blend_attr(int char_attr, int popup_attr, int blend)
+hl_pum_blend_attr(int char_attr, int popup_attr, int blend UNUSED)
 {
     attrentry_T *char_aep = NULL;
     attrentry_T *popup_aep;

From 79ef5cde37f956061e126cc1051402373629c572 Mon Sep 17 00:00:00 2001
From: Yasuhiro Matsumoto <mattn.jp@gmail.com>
Date: Wed, 18 Mar 2026 14:53:00 +0900
Subject: [PATCH 09/16] pumopacity: fix did_set_pumopacity() order in proto
 file

Match the function declaration order to the implementation order in
popupmenu.c.
---
 src/proto/popupmenu.pro | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/proto/popupmenu.pro b/src/proto/popupmenu.pro
index 0e50ca8cc84a76..4fa3544984e93f 100644
--- a/src/proto/popupmenu.pro
+++ b/src/proto/popupmenu.pro
@@ -3,9 +3,9 @@ void pum_set_border(int enable);
 void pum_set_shadow(int enable);
 void pum_set_margin(int enable);
 void pum_display(pumitem_T *array, int size, int selected);
-char *did_set_pumopacity(optset_T *args);
 void pum_call_update_screen(void);
 int pum_under_menu(int row, int col, int only_redrawing);
+char *did_set_pumopacity(optset_T *args);
 void pum_redraw(void);
 void pum_position_info_popup(win_T *wp);
 void pum_undisplay(void);

From 5aedbfe9f4490dc9a2bc0f8b91c99aff5554923e Mon Sep 17 00:00:00 2001
From: Yasuhiro Matsumoto <mattn.jp@gmail.com>
Date: Wed, 18 Mar 2026 15:11:19 +0900
Subject: [PATCH 10/16] Fix pum opacity background mismatch after window resize

Invalidate cached background when screen size changes so the
blended pum background is re-captured from the updated screen.
---
 src/popupmenu.c | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/popupmenu.c b/src/popupmenu.c
index c0cd637311c27e..e9011a43b7caa5 100644
--- a/src/popupmenu.c
+++ b/src/popupmenu.c
@@ -967,6 +967,13 @@ pum_redraw(void)
     if (call_update_screen)
     {
 	call_update_screen = FALSE;
+	// Invalidate cached background if screen size changed (e.g.
+	// after window resize).
+	if (opacity_active && pum_bg_lines != NULL
+		&& (pum_bg_cols != screen_Columns
+		    || pum_bg_bot > screen_Rows))
+	    pum_free_bg();
+
 	if (opacity_active && pum_bg_lines != NULL)
 	{
 	    // Already have saved background; skip update_screen to avoid

From c56374397cfe3e128d9f42af0f1c1c5f7fac683b Mon Sep 17 00:00:00 2001
From: Yasuhiro Matsumoto <mattn.jp@gmail.com>
Date: Wed, 18 Mar 2026 15:39:43 +0900
Subject: [PATCH 11/16] pumopacity: fix option sort order in optiondefs.h

Move 'pumopacity' after 'pummaxwidth' to maintain alphabetical order.
This fixes the Test_set_all_one_column test failure.
---
 src/optiondefs.h | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/optiondefs.h b/src/optiondefs.h
index d78db3fe0cf80a..0701e775999d15 100644
--- a/src/optiondefs.h
+++ b/src/optiondefs.h
@@ -2088,13 +2088,13 @@ static struct vimoption options[] =
     {"pumheight",   "ph",   P_NUM|P_VI_DEF,
 			    (char_u *)&p_ph, PV_NONE, NULL, NULL,
 			    {(char_u *)0L, (char_u *)0L} SCTX_INIT},
+    {"pummaxwidth", "pmw",   P_NUM|P_VI_DEF,
+			    (char_u *)&p_pmw, PV_NONE, NULL, NULL,
+			    {(char_u *)0L, (char_u *)0L} SCTX_INIT},
     {"pumopacity",  NULL,   P_NUM|P_VI_DEF,
 			    (char_u *)&p_po, PV_NONE,
 			    did_set_pumopacity, NULL,
 			    {(char_u *)100L, (char_u *)100L} SCTX_INIT},
-    {"pummaxwidth", "pmw",   P_NUM|P_VI_DEF,
-			    (char_u *)&p_pmw, PV_NONE, NULL, NULL,
-			    {(char_u *)0L, (char_u *)0L} SCTX_INIT},
     {"pumwidth",    "pw",   P_NUM|P_VI_DEF,
 			    (char_u *)&p_pw, PV_NONE, NULL, NULL,
 			    {(char_u *)15L, (char_u *)15L} SCTX_INIT},

From 1667043d5f2b39dda105e592770c665264457042 Mon Sep 17 00:00:00 2001
From: Yasuhiro Matsumoto <mattn.jp@gmail.com>
Date: Fri, 20 Mar 2026 12:57:21 +0900
Subject: [PATCH 12/16] Add 'pumopt' option to consolidate pum settings

Add 'pumopt' as a single string option that controls popup menu
properties: border, height, width, maxwidth, opacity, shadow, margin.
This provides a consolidated alternative to the individual options
'pumborder', 'pumheight', 'pumwidth', 'pummaxwidth', and 'pumopacity'.

The existing individual options continue to work. Deprecation will be
handled in a separate change.

Example usage:
  :set pumopt=border:single,height:10,width:20,opacity:80

- Extract parse_pumopt_border() as shared border parser
- Add pum_opacity_changed() as public function
- Add expand_set_pumopt() for cmdline completion
- Update syntax/vim.vim, options.txt, gen_opt_test.vim
---
 runtime/doc/options.txt           |  57 +++++++
 runtime/syntax/vim.vim            |   4 +-
 src/option.h                      |   1 +
 src/optiondefs.h                  |   4 +
 src/optionstr.c                   | 275 ++++++++++++++++++++++--------
 src/popupmenu.c                   |  12 +-
 src/proto/optionstr.pro           |   2 +
 src/proto/popupmenu.pro           |   1 +
 src/testdir/util/gen_opt_test.vim |   5 +
 9 files changed, 289 insertions(+), 72 deletions(-)

diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 5f30fb715ea39b..ed51cbfd0f71c6 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -6880,6 +6880,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 			global
 	Defines a border and optional decorations for the popup menu in
 	completion.  The value is a comma-separated list of keywords.
+	See |'pumopt'| for a consolidated alternative.
 
 	Border styles (at most one):
 	"single"	use thin box-drawing characters
@@ -6915,6 +6916,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	Determines the maximum number of items to show in the popup menu for
 	Insert mode completion.  When zero as much space as available is used.
 	|ins-completion-menu|.
+	See |'pumopt'| for a consolidated alternative.
 
 						*'pummaxwidth'* *'pmw'*
 'pummaxwidth' 'pmw'	number	(default 0)
@@ -6926,12 +6928,67 @@ A jump table for the options with a short description can be found at |Q_op|.
 
 	This option takes precedence over 'pumwidth'.
 	|ins-completion-menu|.
+	See |'pumopt'| for a consolidated alternative.
+
+						*'pumopt'*
+'pumopt'		string	(default "")
+			global
+	Configures the popup menu used for Insert mode completion.
+	The value is a comma-separated list of key:value pairs and flags.
+
+	Keys with values:
+	  border:{style}	set a border style (at most one):
+				"single"  thin box-drawing characters
+				"double"  double-line box-drawing characters
+				"round"   rounded corners
+				"ascii"   ASCII characters (-, |, +)
+				"custom:X;X;X;X;X;X;X;X"
+					  eight characters separated by
+					  semicolons, in the order: top, right,
+					  bottom, left, topleft, topright,
+					  botright, botleft
+	  height:{n}		maximum number of items to show (default 0,
+				meaning as much space as available)
+	  width:{n}		minimum width (default 15)
+	  maxwidth:{n}		maximum width (default 0, meaning no limit).
+				This takes precedence over width.
+				Truncated text is indicated by "trunc" value
+				of 'fillchars' option.
+	  opacity:{n}		opacity percentage 0-100 (default 100).
+				When less than 100, background content shows
+				through the popup menu.
+
+	Flags (no value):
+	  margin		adds one-cell spacing inside the left and
+				right border.  Requires a border style.
+	  shadow		draws a shadow at the right and bottom edges.
+
+	Border styles using box-drawing characters ("single", "double",
+	"round") are only available when 'encoding' is "utf-8" and
+	'ambiwidth' is "single".
+
+	Highlight groups:
+	|hl-PmenuBorder|	used for the border characters
+	|hl-PmenuShadow|	used for the shadow
+
+	Note: When 'pumopt' is set, all values are reset to their defaults
+	first, then the specified keys are applied.  Unspecified keys get
+	their default values.
+
+	Examples: >
+		:set pumopt=border:single
+		:set pumopt=border:double,margin,shadow
+		:set pumopt=height:10,width:20,opacity:80
+		:set pumopt=border:custom:─;│;─;│;┌;┐;┘;└,shadow
+<
+	See also: |ins-completion-menu|.
 
 						*'pumwidth'* *'pw'*
 'pumwidth' 'pw'		number	(default 15)
 			global
 	Determines the minimum width to use for the popup menu for Insert mode
 	completion.  |ins-completion-menu|.
+	See |'pumopt'| for a consolidated alternative.
 
 						*'pythondll'*
 'pythondll'		string	(default depends on the build)
diff --git a/runtime/syntax/vim.vim b/runtime/syntax/vim.vim
index ed7ce5fb0a400d..2803850c77ede6 100644
--- a/runtime/syntax/vim.vim
+++ b/runtime/syntax/vim.vim
@@ -69,7 +69,7 @@ syn keyword vimOption contained co columns com comments cms commentstring cp com
 syn keyword vimOption contained efm errorformat ek esckeys ei eventignore eiw eventignorewin et expandtab ex exrc fenc fileencoding fencs fileencodings ff fileformat ffs fileformats fic fileignorecase ft filetype fcs fillchars ffu findfunc fixeol fixendofline fcl foldclose fdc foldcolumn fen foldenable fde foldexpr fdi foldignore fdl foldlevel fdls foldlevelstart fmr foldmarker fdm foldmethod fml foldminlines fdn foldnestmax fdo foldopen fdt foldtext fex formatexpr flp formatlistpat fo formatoptions fp formatprg fs fsync gd gdefault gfm grepformat gp grepprg gcr guicursor gfn guifont gfs guifontset gfw guifontwide ghr guiheadroom gli guiligatures go guioptions guipty gtl guitablabel gtt guitabtooltip hf helpfile hh helpheight hlg helplang hid hidden hl highlight skipwhite nextgroup=vimSetEqual,vimSetMod
 syn keyword vimOption contained hi history hk hkmap hkp hkmapp hls hlsearch icon iconstring ic ignorecase imaf imactivatefunc imak imactivatekey imc imcmdline imd imdisable imi iminsert ims imsearch imsf imstatusfunc imst imstyle inc include inex includeexpr is incsearch inde indentexpr indk indentkeys inf infercase im insertmode isf isfname isi isident isk iskeyword isp isprint js joinspaces jop jumpoptions key kmp keymap km keymodel kpc keyprotocol kp keywordprg lmap langmap lm langmenu lnr langnoremap lrm langremap ls laststatus lz lazyredraw lhi lhistory lbr linebreak lines lsp linespace lisp lop lispoptions lw lispwords list lcs listchars lpl loadplugins luadll magic mef makeef menc makeencoding mp makeprg mps matchpairs mat matchtime mco maxcombine mfd maxfuncdepth skipwhite nextgroup=vimSetEqual,vimSetMod
 syn keyword vimOption contained mmd maxmapdepth mm maxmem mmp maxmempattern mmt maxmemtot msc maxsearchcount mis menuitems mopt messagesopt msm mkspellmem ml modeline mle modelineexpr mls modelines ma modifiable mod modified more mouse mousef mousefocus mh mousehide mousem mousemodel mousemev mousemoveevent mouses mouseshape mouset mousetime mzq mzquantum mzschemedll mzschemegcdll nf nrformats nu number nuw numberwidth ofu omnifunc odev opendevice opfunc operatorfunc ost osctimeoutlen pp packpath para paragraphs paste pt pastetoggle pex patchexpr pm patchmode pa path perldll pi preserveindent pvh previewheight pvp previewpopup pvw previewwindow pdev printdevice penc printencoding pexpr printexpr pfn printfont pheader printheader pmbcs printmbcharset pmbfn printmbfont skipwhite nextgroup=vimSetEqual,vimSetMod
-syn keyword vimOption contained popt printoptions prompt pb pumborder ph pumheight pmw pummaxwidth pw pumwidth pythondll pythonhome pythonthreedll pythonthreehome pyx pyxversion qftf quickfixtextfunc qe quoteescape ro readonly rdt redrawtime re regexpengine rnu relativenumber remap rop renderoptions report rs restorescreen ri revins rl rightleft rlc rightleftcmd rubydll ru ruler ruf rulerformat rtp runtimepath scr scroll scb scrollbind scf scrollfocus sj scrolljump so scrolloff sbo scrollopt sect sections secure sel selection slm selectmode ssop sessionoptions sh shell shcf shellcmdflag sp shellpipe shq shellquote srr shellredir ssl shellslash stmp shelltemp st shelltype sxe shellxescape sxq shellxquote sr shiftround sw shiftwidth shm shortmess sn shortname sbr showbreak skipwhite nextgroup=vimSetEqual,vimSetMod
+syn keyword vimOption contained popt printoptions prompt pb pumborder ph pumheight pmw pummaxwidth pw pumwidth pumopt pythondll pythonhome pythonthreedll pythonthreehome pyx pyxversion qftf quickfixtextfunc qe quoteescape ro readonly rdt redrawtime re regexpengine rnu relativenumber remap rop renderoptions report rs restorescreen ri revins rl rightleft rlc rightleftcmd rubydll ru ruler ruf rulerformat rtp runtimepath scr scroll scb scrollbind scf scrollfocus sj scrolljump so scrolloff sbo scrollopt sect sections secure sel selection slm selectmode ssop sessionoptions sh shell shcf shellcmdflag sp shellpipe shq shellquote srr shellredir ssl shellslash stmp shelltemp st shelltype sxe shellxescape sxq shellxquote sr shiftround sw shiftwidth shm shortmess sn shortname sbr showbreak skipwhite nextgroup=vimSetEqual,vimSetMod
 syn keyword vimOption contained sc showcmd sloc showcmdloc sft showfulltag sm showmatch smd showmode stal showtabline stpl showtabpanel ss sidescroll siso sidescrolloff scl signcolumn scs smartcase si smartindent sta smarttab sms smoothscroll sts softtabstop spell spc spellcapcheck spf spellfile spl spelllang spo spelloptions sps spellsuggest sb splitbelow spk splitkeep spr splitright sol startofline stl statusline stlo statuslineopt su suffixes sua suffixesadd swf swapfile sws swapsync swb switchbuf smc synmaxcol syn syntax tcl tabclose tal tabline tpm tabpagemax tpl tabpanel tplo tabpanelopt ts tabstop tbs tagbsearch tc tagcase tfu tagfunc tl taglength tr tagrelative tag tags tgst tagstack tcldll term tbidi termbidi tenc termencoding tgc termguicolors trz termresize skipwhite nextgroup=vimSetEqual,vimSetMod
 syn keyword vimOption contained tsy termsync twk termwinkey twsl termwinscroll tws termwinsize twt termwintype terse ta textauto tx textmode tw textwidth tsr thesaurus tsrfu thesaurusfunc top tildeop to timeout tm timeoutlen title titlelen titleold titlestring tb toolbar tbis toolbariconsize ttimeout ttm ttimeoutlen tbi ttybuiltin tf ttyfast ttym ttymouse tsl ttyscroll tty ttytype udir undodir udf undofile ul undolevels ur undoreload uc updatecount ut updatetime vsts varsofttabstop vts vartabstop vbs verbose vfile verbosefile vdir viewdir vop viewoptions vi viminfo vif viminfofile ve virtualedit vb visualbell warn wiv weirdinvert ww whichwrap wc wildchar wcm wildcharm wig wildignore wic wildignorecase wmnu wildmenu wim wildmode wop wildoptions wak winaltkeys wcr wincolor skipwhite nextgroup=vimSetEqual,vimSetMod
 syn keyword vimOption contained wi window wfb winfixbuf wfh winfixheight wfw winfixwidth wh winheight whl winhighlight wmh winminheight wmw winminwidth winptydll wiw winwidth wse wlseat wst wlsteal wtm wltimeoutlen wrap wm wrapmargin ws wrapscan write wa writeany wb writebackup wd writedelay xtermcodes skipwhite nextgroup=vimSetEqual,vimSetMod
@@ -108,7 +108,7 @@ syn keyword vimOptionVarName contained co columns com comments cms commentstring
 syn keyword vimOptionVarName contained efm errorformat ek esckeys ei eventignore eiw eventignorewin et expandtab ex exrc fenc fileencoding fencs fileencodings ff fileformat ffs fileformats fic fileignorecase ft filetype fcs fillchars ffu findfunc fixeol fixendofline fcl foldclose fdc foldcolumn fen foldenable fde foldexpr fdi foldignore fdl foldlevel fdls foldlevelstart fmr foldmarker fdm foldmethod fml foldminlines fdn foldnestmax fdo foldopen fdt foldtext fex formatexpr flp formatlistpat fo formatoptions fp formatprg fs fsync gd gdefault gfm grepformat gp grepprg gcr guicursor gfn guifont gfs guifontset gfw guifontwide ghr guiheadroom gli guiligatures go guioptions guipty gtl guitablabel gtt guitabtooltip hf helpfile hh helpheight hlg helplang hid hidden hl highlight
 syn keyword vimOptionVarName contained hi history hk hkmap hkp hkmapp hls hlsearch icon iconstring ic ignorecase imaf imactivatefunc imak imactivatekey imc imcmdline imd imdisable imi iminsert ims imsearch imsf imstatusfunc imst imstyle inc include inex includeexpr is incsearch inde indentexpr indk indentkeys inf infercase im insertmode isf isfname isi isident isk iskeyword isp isprint js joinspaces jop jumpoptions key kmp keymap km keymodel kpc keyprotocol kp keywordprg lmap langmap lm langmenu lnr langnoremap lrm langremap ls laststatus lz lazyredraw lhi lhistory lbr linebreak lines lsp linespace lisp lop lispoptions lw lispwords list lcs listchars lpl loadplugins luadll magic mef makeef menc makeencoding mp makeprg mps matchpairs mat matchtime mco maxcombine
 syn keyword vimOptionVarName contained mfd maxfuncdepth mmd maxmapdepth mm maxmem mmp maxmempattern mmt maxmemtot msc maxsearchcount mis menuitems mopt messagesopt msm mkspellmem ml modeline mle modelineexpr mls modelines ma modifiable mod modified more mouse mousef mousefocus mh mousehide mousem mousemodel mousemev mousemoveevent mouses mouseshape mouset mousetime mzq mzquantum mzschemedll mzschemegcdll nf nrformats nu number nuw numberwidth ofu omnifunc odev opendevice opfunc operatorfunc ost osctimeoutlen pp packpath para paragraphs paste pt pastetoggle pex patchexpr pm patchmode pa path perldll pi preserveindent pvh previewheight pvp previewpopup pvw previewwindow pdev printdevice penc printencoding pexpr printexpr pfn printfont pheader printheader pmbcs printmbcharset
-syn keyword vimOptionVarName contained pmbfn printmbfont popt printoptions prompt pb pumborder ph pumheight pmw pummaxwidth pw pumwidth pythondll pythonhome pythonthreedll pythonthreehome pyx pyxversion qftf quickfixtextfunc qe quoteescape ro readonly rdt redrawtime re regexpengine rnu relativenumber remap rop renderoptions report rs restorescreen ri revins rl rightleft rlc rightleftcmd rubydll ru ruler ruf rulerformat rtp runtimepath scr scroll scb scrollbind scf scrollfocus sj scrolljump so scrolloff sbo scrollopt sect sections secure sel selection slm selectmode ssop sessionoptions sh shell shcf shellcmdflag sp shellpipe shq shellquote srr shellredir ssl shellslash stmp shelltemp st shelltype sxe shellxescape sxq shellxquote sr shiftround sw shiftwidth shm shortmess
+syn keyword vimOptionVarName contained pmbfn printmbfont popt printoptions prompt pb pumborder ph pumheight pmw pummaxwidth pw pumwidth pumopt pythondll pythonhome pythonthreedll pythonthreehome pyx pyxversion qftf quickfixtextfunc qe quoteescape ro readonly rdt redrawtime re regexpengine rnu relativenumber remap rop renderoptions report rs restorescreen ri revins rl rightleft rlc rightleftcmd rubydll ru ruler ruf rulerformat rtp runtimepath scr scroll scb scrollbind scf scrollfocus sj scrolljump so scrolloff sbo scrollopt sect sections secure sel selection slm selectmode ssop sessionoptions sh shell shcf shellcmdflag sp shellpipe shq shellquote srr shellredir ssl shellslash stmp shelltemp st shelltype sxe shellxescape sxq shellxquote sr shiftround sw shiftwidth shm shortmess
 syn keyword vimOptionVarName contained sn shortname sbr showbreak sc showcmd sloc showcmdloc sft showfulltag sm showmatch smd showmode stal showtabline stpl showtabpanel ss sidescroll siso sidescrolloff scl signcolumn scs smartcase si smartindent sta smarttab sms smoothscroll sts softtabstop spell spc spellcapcheck spf spellfile spl spelllang spo spelloptions sps spellsuggest sb splitbelow spk splitkeep spr splitright sol startofline stl statusline stlo statuslineopt su suffixes sua suffixesadd swf swapfile sws swapsync swb switchbuf smc synmaxcol syn syntax tcl tabclose tal tabline tpm tabpagemax tpl tabpanel tplo tabpanelopt ts tabstop tbs tagbsearch tc tagcase tfu tagfunc tl taglength tr tagrelative tag tags tgst tagstack tcldll term tbidi termbidi tenc termencoding
 syn keyword vimOptionVarName contained tgc termguicolors trz termresize tsy termsync twk termwinkey twsl termwinscroll tws termwinsize twt termwintype terse ta textauto tx textmode tw textwidth tsr thesaurus tsrfu thesaurusfunc top tildeop to timeout tm timeoutlen title titlelen titleold titlestring tb toolbar tbis toolbariconsize ttimeout ttm ttimeoutlen tbi ttybuiltin tf ttyfast ttym ttymouse tsl ttyscroll tty ttytype udir undodir udf undofile ul undolevels ur undoreload uc updatecount ut updatetime vsts varsofttabstop vts vartabstop vbs verbose vfile verbosefile vdir viewdir vop viewoptions vi viminfo vif viminfofile ve virtualedit vb visualbell warn wiv weirdinvert ww whichwrap wc wildchar wcm wildcharm wig wildignore wic wildignorecase wmnu wildmenu wim wildmode
 syn keyword vimOptionVarName contained wop wildoptions wak winaltkeys wcr wincolor wi window wfb winfixbuf wfh winfixheight wfw winfixwidth wh winheight whl winhighlight wmh winminheight wmw winminwidth winptydll wiw winwidth wse wlseat wst wlsteal wtm wltimeoutlen wrap wm wrapmargin ws wrapscan write wa writeany wb writebackup wd writedelay xtermcodes
diff --git a/src/option.h b/src/option.h
index a38dba67764259..ceddf522dbb1fd 100644
--- a/src/option.h
+++ b/src/option.h
@@ -557,6 +557,7 @@ EXTERN long	p_po;		// 'pumopacity'
 EXTERN long	p_pw;		// 'pumwidth'
 EXTERN long	p_pmw;		// 'pummaxwidth'
 EXTERN char_u	*p_pb;		// 'pumborder'
+EXTERN char_u	*p_pumopt;	// 'pumopt'
 EXTERN char_u	*p_com;		// 'comments'
 EXTERN char_u	*p_cpo;		// 'cpoptions'
 #ifdef FEAT_CSCOPE
diff --git a/src/optiondefs.h b/src/optiondefs.h
index 0701e775999d15..5726ac039bd066 100644
--- a/src/optiondefs.h
+++ b/src/optiondefs.h
@@ -2095,6 +2095,10 @@ static struct vimoption options[] =
 			    (char_u *)&p_po, PV_NONE,
 			    did_set_pumopacity, NULL,
 			    {(char_u *)100L, (char_u *)100L} SCTX_INIT},
+    {"pumopt",	    NULL,   P_STRING|P_VI_DEF|P_COMMA|P_NODUP|P_COLON,
+			    (char_u *)&p_pumopt, PV_NONE,
+			    did_set_pumopt, expand_set_pumopt,
+			    {(char_u *)"", (char_u *)NULL} SCTX_INIT},
     {"pumwidth",    "pw",   P_NUM|P_VI_DEF,
 			    (char_u *)&p_pw, PV_NONE, NULL, NULL,
 			    {(char_u *)15L, (char_u *)15L} SCTX_INIT},
diff --git a/src/optionstr.c b/src/optionstr.c
index 8f964b9837d736..8d4cbfe9138d82 100644
--- a/src/optionstr.c
+++ b/src/optionstr.c
@@ -3697,114 +3697,251 @@ expand_set_rightleftcmd(optexpand_T *args, int *numMatches, char_u ***matches)
     } while (0)
 
 /*
- * The 'pumborder' option is changed.
- * Rules:
- *   - One of { single, double, round, ascii, custom:XXXXXXXX } may appear.
- *   - "margin" may appear, but only together with exactly one border style.
- *   - "shadow" is independent and can be combined freely.
+ * Parse a border value from a pumopt "border:" token.
+ * Returns OK on success, FAIL on error.
  */
-    char *
-did_set_pumborder(optset_T *args)
+    static int
+parse_pumopt_border(char_u *val, int len)
 {
-    char_u  **varp = (char_u **)args->os_varp;
     // Use box-drawing characters only when 'encoding' is "utf-8" and
     // 'ambiwidth' is "single".
     int	    can_use_box_chars = (enc_utf8 && *p_ambw == 's');
-    char_u  *p, *token;
-    int	    len;
+    char_u  *token;
+
+    token = vim_strnsave(val, len);
+    if (token == NULL)
+	return FAIL;
+
+    if (can_use_box_chars && STRCMP(token, "single") == 0)
+	pum_set_border_chars(0x2500, 0x2502, 0x2500, 0x2502, // ─ │ ─ │
+		0x250c, 0x2510, 0x2518, 0x2514); // ┌ ┐ ┘ └
+    else if (can_use_box_chars && STRCMP(token, "double") == 0)
+	pum_set_border_chars(0x2550, 0x2551, 0x2550, 0x2551, // ═ ║ ═ ║
+		0x2554, 0x2557, 0x255D, 0x255A); // ╔ ╗ ╝  ╚
+    else if (can_use_box_chars && STRCMP(token, "round") == 0)
+	pum_set_border_chars(0x2500, 0x2502, 0x2500, 0x2502, // ─ │ ─ │
+		0x256d, 0x256e, 0x256f, 0x2570); // ╭ ╮ ╯ ╰
+    else if (STRCMP(token, "ascii") == 0)
+	pum_set_border_chars('-', '|', '-', '|', '+', '+', '+', '+');
+    else if (STRNCMP(token, "custom:", 7) == 0)
+    {
+	char_u	*q = token + 7;
+	int	out[8];
+
+	for (int i = 0; i < 8; i++)
+	{
+	    if (*q == NUL || *q == ',')
+	    {
+		vim_free(token);
+		return FAIL;
+	    }
+	    out[i] = mb_ptr2char(q);
+	    mb_ptr2char_adv(&q);
+	    if (i < 7)
+	    {
+		if (*q != ';')
+		{
+		    vim_free(token);
+		    return FAIL;
+		}
+		q++;
+	    }
+	}
+	if (*q != NUL && *q != ',')
+	{
+	    vim_free(token);
+	    return FAIL;
+	}
+	pum_set_border_chars(out[0], out[1], out[2], out[3], out[4], out[5],
+		out[6], out[7]);
+    }
+    else
+    {
+	vim_free(token);
+	return FAIL;
+    }
+
+    vim_free(token);
+    pum_set_border(TRUE);
+    return OK;
+}
+
+/*
+ * The 'pumopt' option is changed.
+ * Format: comma-separated key:value pairs.
+ *   border:{single|double|round|ascii|custom:X;X;X;X;X;X;X;X}
+ *   height:{n}
+ *   width:{n}
+ *   maxwidth:{n}
+ *   opacity:{n}
+ *   shadow
+ *   margin (requires border)
+ */
+    char *
+did_set_pumopt(optset_T *args)
+{
+    char_u  **varp = (char_u **)args->os_varp;
+    char_u  *p;
     int	    have_border = FALSE;
     int	    have_margin = FALSE;
 
+    // Reset to defaults.
     PUM_BORDER_CLEAR();
+    pum_set_border_chars(0, 0, 0, 0, 0, 0, 0, 0);
+    p_ph = 0;
+    p_pw = 15;
+    p_pmw = 0;
+    p_po = 100;
 
     if (*varp == NULL || **varp == NUL)
 	return NULL;
 
     for (p = *varp; p != NULL && *p != NUL; )
     {
-	// end of token is either ',' or NUL
 	char_u *comma = vim_strchr(p, ',');
+	int len;
+
 	if (comma != NULL)
 	    len = (int)(comma - p);
 	else
 	    len = (int)STRLEN(p);
 
-	token = vim_strnsave(p, len);
-	if (token == NULL)
-	    goto error;
-
-	if ((can_use_box_chars && (STRCMP(token, "single") == 0
-			|| STRCMP(token, "double") == 0
-			|| STRCMP(token, "round") == 0))
-		|| STRCMP(token, "ascii") == 0
-		|| (STRNCMP(token, "custom:", 7) == 0))
+	if (STRNCMP(p, "border:", 7) == 0)
 	{
 	    if (have_border)
-	    {
-		// multiple border styles not allowed
-		vim_free(token);
 		goto error;
-	    }
 	    have_border = TRUE;
+	    if (parse_pumopt_border(p + 7, len - 7) == FAIL)
+		goto error;
+	}
+	else if (STRNCMP(p, "height:", 7) == 0)
+	{
+	    long n = atol((char *)p + 7);
+	    if (n < 0)
+		goto error;
+	    p_ph = n;
+	}
+	else if (STRNCMP(p, "width:", 6) == 0)
+	{
+	    long n = atol((char *)p + 6);
+	    if (n < 0)
+		goto error;
+	    p_pw = n;
+	}
+	else if (STRNCMP(p, "maxwidth:", 9) == 0)
+	{
+	    long n = atol((char *)p + 9);
+	    if (n < 0)
+		goto error;
+	    p_pmw = n;
+	}
+	else if (STRNCMP(p, "opacity:", 8) == 0)
+	{
+	    long n = atol((char *)p + 8);
+	    if (n < 0 || n > 100)
+		goto error;
+	    p_po = n;
+	}
+	else if (len == 6 && STRNCMP(p, "shadow", 6) == 0)
+	    pum_set_shadow(TRUE);
+	else if (len == 6 && STRNCMP(p, "margin", 6) == 0)
+	{
+	    have_margin = TRUE;
+	    pum_set_margin(TRUE);
+	}
+	else
+	    goto error;
 
-	    if (STRCMP(token, "single") == 0)
-		pum_set_border_chars(0x2500, 0x2502, 0x2500, 0x2502, // ─ │ ─ │
-			0x250c, 0x2510, 0x2518, 0x2514); // ┌ ┐ ┘ └
-	    else if (STRCMP(token, "double") == 0)
-		pum_set_border_chars(0x2550, 0x2551, 0x2550, 0x2551, // ═ ║ ═ ║
-			0x2554, 0x2557, 0x255D, 0x255A); // ╔ ╗ ╝  ╚
-	    else if (STRCMP(token, "round") == 0)
-		pum_set_border_chars(0x2500, 0x2502, 0x2500, 0x2502, // ─ │ ─ │
-			0x256d, 0x256e, 0x256f, 0x2570); // ╭ ╮ ╯ ╰
-	    else if (STRCMP(token, "ascii") == 0)
-		pum_set_border_chars('-', '|', '-', '|', '+', '+', '+', '+');
-	    else if (STRNCMP(token, "custom:", 7) == 0)
-	    {
-		char_u	*q = token + 7;
-		int	out[8];
+	if (comma != NULL)
+	    p = comma + 1;
+	else
+	    break;
+    }
 
-		for (int i = 0; i < 8; i++)
-		{
-		    if (*q == NUL || *q == ',')
-			goto error;
-		    out[i] = mb_ptr2char(q);
-		    mb_ptr2char_adv(&q);
-		    if (i < 7)
-		    {
-			if (*q != ';')
-			    goto error;  // must be semicolon
-			q++;
-		    }
-		}
-		if (*q != NUL && *q != ',') // must end exactly after the 8th char
-		    goto error;
-		pum_set_border_chars(out[0], out[1], out[2], out[3], out[4], out[5],
-			out[6], out[7]);
-	    }
-	}
-	else if (STRCMP(token, "shadow") == 0)
+    if (have_margin && !have_border)
+	goto error;
+
+    // Invalidate cached background for opacity changes.
+    pum_opacity_changed();
+
+    return NULL;
+
+error:
+    PUM_BORDER_CLEAR();
+    pum_set_border_chars(0, 0, 0, 0, 0, 0, 0, 0);
+    p_ph = 0;
+    p_pw = 15;
+    p_pmw = 0;
+    p_po = 100;
+    return e_invalid_argument;
+}
+
+    int
+expand_set_pumopt(optexpand_T *args, int *numMatches, char_u ***matches)
+{
+    static char *(p_pumopt_values[]) = {"border:", "height:", "width:",
+	"maxwidth:", "opacity:", "shadow", "margin", NULL};
+    return expand_set_opt_string(
+	    args,
+	    p_pumopt_values,
+	    ARRAY_LENGTH(p_pumopt_values) - 1,
+	    numMatches,
+	    matches);
+}
+
+/*
+ * The 'pumborder' option is changed.
+ * Rules:
+ *   - One of { single, double, round, ascii, custom:XXXXXXXX } may appear.
+ *   - "margin" may appear, but only together with exactly one border style.
+ *   - "shadow" is independent and can be combined freely.
+ */
+    char *
+did_set_pumborder(optset_T *args)
+{
+    char_u  **varp = (char_u **)args->os_varp;
+    char_u  *p;
+    int	    len;
+    int	    have_border = FALSE;
+    int	    have_margin = FALSE;
+
+    PUM_BORDER_CLEAR();
+
+    if (*varp == NULL || **varp == NUL)
+	return NULL;
+
+    for (p = *varp; p != NULL && *p != NUL; )
+    {
+	char_u *comma = vim_strchr(p, ',');
+	if (comma != NULL)
+	    len = (int)(comma - p);
+	else
+	    len = (int)STRLEN(p);
+
+	if (STRNCMP(p, "shadow", len) == 0 && len == 6)
 	    pum_set_shadow(TRUE);
-	else if (STRCMP(token, "margin") == 0)
+	else if (STRNCMP(p, "margin", len) == 0 && len == 6)
 	{
 	    have_margin = TRUE;
 	    pum_set_margin(TRUE);
 	}
 	else
 	{
-	    vim_free(token);
-	    goto error;
+	    if (have_border)
+		goto error;
+	    have_border = TRUE;
+	    if (parse_pumopt_border(p, len) == FAIL)
+		goto error;
 	}
 
-	vim_free(token);
-
 	if (comma != NULL)
-	    p = comma + 1; // move to next token (skip comma)
+	    p = comma + 1;
 	else
 	    break;
     }
 
     if (have_margin && !have_border)
-	goto error; // margin must be combined with border
+	goto error;
 
     return NULL;
 
@@ -3817,12 +3954,12 @@ did_set_pumborder(optset_T *args)
     int
 expand_set_pumborder(optexpand_T *args, int *numMatches, char_u ***matches)
 {
-    static char *(p_rlc_values[]) = {"single", "double", "round", "ascii",
+    static char *(p_pb_values[]) = {"single", "double", "round", "ascii",
 	"custom", "shadow", "margin", NULL};
     return expand_set_opt_string(
 	    args,
-	    p_rlc_values,
-	    ARRAY_LENGTH(p_rlc_values) - 1,
+	    p_pb_values,
+	    ARRAY_LENGTH(p_pb_values) - 1,
 	    numMatches,
 	    matches);
 }
diff --git a/src/popupmenu.c b/src/popupmenu.c
index e9011a43b7caa5..4efa18a0952fc6 100644
--- a/src/popupmenu.c
+++ b/src/popupmenu.c
@@ -891,6 +891,17 @@ did_set_pumopacity(optset_T *args UNUSED)
     if (p_po > 100)
 	p_po = 100;
 
+    pum_opacity_changed();
+    return NULL;
+}
+
+/*
+ * Called when the pum opacity value has changed.
+ * Invalidates cached background and triggers redraw if pum is visible.
+ */
+    void
+pum_opacity_changed(void)
+{
     // Invalidate cached background so it gets re-saved.
     pum_free_bg();
 
@@ -902,7 +913,6 @@ did_set_pumopacity(optset_T *args UNUSED)
 	call_update_screen = TRUE;
 	pum_redraw();
     }
-    return NULL;
 }
 
     static void
diff --git a/src/proto/optionstr.pro b/src/proto/optionstr.pro
index be8b8e97b52ba1..cb174e73c0f4ae 100644
--- a/src/proto/optionstr.pro
+++ b/src/proto/optionstr.pro
@@ -136,6 +136,8 @@ int expand_set_printoptions(optexpand_T *args, int *numMatches, char_u ***matche
 char *did_set_renderoptions(optset_T *args);
 char *did_set_rightleftcmd(optset_T *args);
 int expand_set_rightleftcmd(optexpand_T *args, int *numMatches, char_u ***matches);
+char *did_set_pumopt(optset_T *args);
+int expand_set_pumopt(optexpand_T *args, int *numMatches, char_u ***matches);
 char *did_set_pumborder(optset_T *args);
 int expand_set_pumborder(optexpand_T *args, int *numMatches, char_u ***matches);
 char *did_set_rulerformat(optset_T *args);
diff --git a/src/proto/popupmenu.pro b/src/proto/popupmenu.pro
index 4fa3544984e93f..a89b8c93b20a44 100644
--- a/src/proto/popupmenu.pro
+++ b/src/proto/popupmenu.pro
@@ -6,6 +6,7 @@ void pum_display(pumitem_T *array, int size, int selected);
 void pum_call_update_screen(void);
 int pum_under_menu(int row, int col, int only_redrawing);
 char *did_set_pumopacity(optset_T *args);
+void pum_opacity_changed(void);
 void pum_redraw(void);
 void pum_position_info_popup(win_T *wp);
 void pum_undisplay(void);
diff --git a/src/testdir/util/gen_opt_test.vim b/src/testdir/util/gen_opt_test.vim
index 72ff49b62ee842..6a02c531bdc9c2 100644
--- a/src/testdir/util/gen_opt_test.vim
+++ b/src/testdir/util/gen_opt_test.vim
@@ -291,6 +291,11 @@ let test_values = {
       \		'double,margin,shadow', 'custom:─;│;─;│;┌;┐;┘;└,shadow',
       \		'ascii,margin'],
       \		['xxx', 'margin', 'margin,shadow', 'custom:', 'custom:+;']],
+      \ 'pumopt': [['', 'border:single', 'border:double', 'border:ascii',
+      \		'height:10', 'width:20', 'maxwidth:30', 'opacity:50',
+      \		'border:double,margin,shadow',
+      \		'height:10,width:20,maxwidth:30,opacity:80'],
+      \		['xxx', 'opacity:200', 'opacity:-1', 'margin']],
       \ 'renderoptions': [[''], ['xxx']],
       \ 'rightleftcmd': [['search'], ['xxx']],
       \ 'rulerformat': [['', 'xxx'], ['%-', '%(', '%15(%%']],

From 6f50ba89b62eede8bfa2fb53b5b58604acbe6c0b Mon Sep 17 00:00:00 2001
From: Yasuhiro Matsumoto <mattn.jp@gmail.com>
Date: Sun, 22 Mar 2026 19:42:05 +0900
Subject: [PATCH 13/16] Remove 'pumopacity' option, use 'pumopt' opacity:
 instead

The standalone 'pumopacity' option is unnecessary since 'pumopt' already
supports opacity via the opacity:{n} key.  Remove the option definition
and move the internal p_po variable to globals.h.  Update tests to use
'pumopt=opacity:50' instead of 'set pumopacity=50'.
---
 src/globals.h                                 |  6 ++-
 src/option.h                                  |  1 -
 src/optiondefs.h                              |  4 --
 src/popupmenu.c                               | 15 ------
 src/proto/popupmenu.pro                       |  1 -
 ..._100.dump => Test_pumopt_opacity_100.dump} |  8 ++--
 ...ty_50.dump => Test_pumopt_opacity_50.dump} |  8 ++--
 src/testdir/test_popup.vim                    | 47 +++++--------------
 8 files changed, 25 insertions(+), 65 deletions(-)
 rename src/testdir/dumps/{Test_pumopacity_100.dump => Test_pumopt_opacity_100.dump} (76%)
 rename src/testdir/dumps/{Test_pumopacity_50.dump => Test_pumopt_opacity_50.dump} (76%)

diff --git a/src/globals.h b/src/globals.h
index f4ec70120259aa..87c0a6be63a8cd 100644
--- a/src/globals.h
+++ b/src/globals.h
@@ -125,8 +125,12 @@ EXTERN int	screen_zindex INIT(= 0);
 EXTERN win_T	*screen_opacity_popup INIT(= NULL);
 #endif
 
+// Pum opacity level (0 = fully transparent, 100 = fully opaque).
+// Set via 'pumopt' opacity: key.
+EXTERN long	p_po INIT(= 100);
+
 // Blend value for popup menu opacity (0 = off, 1-99 = blend level).
-// Set during pum drawing when 'pumopacity' is active.
+// Set during pum drawing when pum opacity is active.
 EXTERN int	screen_pum_blend INIT(= 0);
 
 // Saved background screen content for pum opacity blending.
diff --git a/src/option.h b/src/option.h
index ceddf522dbb1fd..adafbd8d36eeff 100644
--- a/src/option.h
+++ b/src/option.h
@@ -553,7 +553,6 @@ EXTERN long	p_acl;		// 'autocompletedelay'
 EXTERN char_u	*p_csl;		// 'completeslash'
 #endif
 EXTERN long	p_ph;		// 'pumheight'
-EXTERN long	p_po;		// 'pumopacity'
 EXTERN long	p_pw;		// 'pumwidth'
 EXTERN long	p_pmw;		// 'pummaxwidth'
 EXTERN char_u	*p_pb;		// 'pumborder'
diff --git a/src/optiondefs.h b/src/optiondefs.h
index 5726ac039bd066..4b1ee2bc49b1ff 100644
--- a/src/optiondefs.h
+++ b/src/optiondefs.h
@@ -2091,10 +2091,6 @@ static struct vimoption options[] =
     {"pummaxwidth", "pmw",   P_NUM|P_VI_DEF,
 			    (char_u *)&p_pmw, PV_NONE, NULL, NULL,
 			    {(char_u *)0L, (char_u *)0L} SCTX_INIT},
-    {"pumopacity",  NULL,   P_NUM|P_VI_DEF,
-			    (char_u *)&p_po, PV_NONE,
-			    did_set_pumopacity, NULL,
-			    {(char_u *)100L, (char_u *)100L} SCTX_INIT},
     {"pumopt",	    NULL,   P_STRING|P_VI_DEF|P_COMMA|P_NODUP|P_COLON,
 			    (char_u *)&p_pumopt, PV_NONE,
 			    did_set_pumopt, expand_set_pumopt,
diff --git a/src/popupmenu.c b/src/popupmenu.c
index 4efa18a0952fc6..bd68cf0de5a8cb 100644
--- a/src/popupmenu.c
+++ b/src/popupmenu.c
@@ -880,21 +880,6 @@ pum_align_order(int *order)
 
 static void pum_free_bg(void);
 
-/*
- * Called when 'pumopacity' is changed.
- */
-    char *
-did_set_pumopacity(optset_T *args UNUSED)
-{
-    if (p_po < 0)
-	p_po = 0;
-    if (p_po > 100)
-	p_po = 100;
-
-    pum_opacity_changed();
-    return NULL;
-}
-
 /*
  * Called when the pum opacity value has changed.
  * Invalidates cached background and triggers redraw if pum is visible.
diff --git a/src/proto/popupmenu.pro b/src/proto/popupmenu.pro
index a89b8c93b20a44..4afd678125cd45 100644
--- a/src/proto/popupmenu.pro
+++ b/src/proto/popupmenu.pro
@@ -5,7 +5,6 @@ void pum_set_margin(int enable);
 void pum_display(pumitem_T *array, int size, int selected);
 void pum_call_update_screen(void);
 int pum_under_menu(int row, int col, int only_redrawing);
-char *did_set_pumopacity(optset_T *args);
 void pum_opacity_changed(void);
 void pum_redraw(void);
 void pum_position_info_popup(win_T *wp);
diff --git a/src/testdir/dumps/Test_pumopacity_100.dump b/src/testdir/dumps/Test_pumopt_opacity_100.dump
similarity index 76%
rename from src/testdir/dumps/Test_pumopacity_100.dump
rename to src/testdir/dumps/Test_pumopt_opacity_100.dump
index d9e44da0f7160e..dfc05172c596bb 100644
--- a/src/testdir/dumps/Test_pumopacity_100.dump
+++ b/src/testdir/dumps/Test_pumopt_opacity_100.dump
@@ -9,12 +9,12 @@
 |B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G
 |R|O|U|N|D| @69
 |B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G
-|R|O|U|N|D| @69
-|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G
+|R| +0#0000001#e0e0e08|h|e|l@1|o| @9| +0#0000000#ffffff0@57
+|B| +0#0000001#ffd7ff255|h|e|l|p| @10|U+0#0000000#ffffff0|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G
 |R|O|U|N|D| @69
 |h|e|l@1|o> @69
-|h+0#0000001#e0e0e08|e|l@1|o| @9| +0#4040ff13#ffffff0@59
-|h+0#0000001#ffd7ff255|e|l|p| @10| +0#4040ff13#ffffff0@59
+|~+0#4040ff13&| @73
+|~| @73
 |~| @73
 |~| @73
 |-+2#0000000&@1| |K|e|y|w|o|r|d| |c|o|m|p|l|e|t|i|o|n| |(|^|N|^|P|)| |m+0#00e0003&|a|t|c|h| |1| |o|f| |2| +0#0000000&@33
diff --git a/src/testdir/dumps/Test_pumopacity_50.dump b/src/testdir/dumps/Test_pumopt_opacity_50.dump
similarity index 76%
rename from src/testdir/dumps/Test_pumopacity_50.dump
rename to src/testdir/dumps/Test_pumopt_opacity_50.dump
index d9e44da0f7160e..ac1aad12048b49 100644
--- a/src/testdir/dumps/Test_pumopacity_50.dump
+++ b/src/testdir/dumps/Test_pumopt_opacity_50.dump
@@ -9,12 +9,12 @@
 |B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G
 |R|O|U|N|D| @69
 |B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G
-|R|O|U|N|D| @69
-|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G
+|R| +0#0000001#e0e0e08|h|e|l@1|o| @9| +0#0000000#ffffff0@57
+|B| +0#0000001#ffd7ff255|h|e|l|p|O|U|N|D|B|A|C|K|G|R|O|U+0#0000000#ffffff0|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G
 |R|O|U|N|D| @69
 |h|e|l@1|o> @69
-|h+0#0000001#e0e0e08|e|l@1|o| @9| +0#4040ff13#ffffff0@59
-|h+0#0000001#ffd7ff255|e|l|p| @10| +0#4040ff13#ffffff0@59
+|~+0#4040ff13&| @73
+|~| @73
 |~| @73
 |~| @73
 |-+2#0000000&@1| |K|e|y|w|o|r|d| |c|o|m|p|l|e|t|i|o|n| |(|^|N|^|P|)| |m+0#00e0003&|a|t|c|h| |1| |o|f| |2| +0#0000000&@33
diff --git a/src/testdir/test_popup.vim b/src/testdir/test_popup.vim
index 72486d67ef596d..0ea6ae48e33eed 100644
--- a/src/testdir/test_popup.vim
+++ b/src/testdir/test_popup.vim
@@ -2420,33 +2420,11 @@ func Test_popup_shadow_hiddenchar()
   call StopVimInTerminal(buf)
 endfunc
 
-" Test 'pumopacity' option value clamping and default
-func Test_pumopacity_option()
-  call assert_equal(100, &pumopacity)
-
-  set pumopacity=50
-  call assert_equal(50, &pumopacity)
-
-  " Clamp to 0
-  set pumopacity=-10
-  call assert_equal(0, &pumopacity)
-
-  " Clamp to 100
-  set pumopacity=200
-  call assert_equal(100, &pumopacity)
-
-  set pumopacity=0
-  call assert_equal(0, &pumopacity)
-
-  set pumopacity&
-  call assert_equal(100, &pumopacity)
-endfunc
-
-" Test pumopacity with screendump: background text should show through
-func Test_pumopacity_screendump()
+" Test pumopt opacity with screendump: background text should show through
+func Test_pumopt_opacity_screendump()
   CheckScreendump
   let lines =<< trim END
-    set pumopacity=50
+    set pumopt=opacity:50
     set completeopt=menu
     call setline(1, ['hello world', 'hello vim', 'hello opacity', 'help me'])
     for i in range(5)
@@ -2454,22 +2432,22 @@ func Test_pumopacity_screendump()
     endfor
     normal gg
   END
-  call writefile(lines, 'Xpumopacity', 'D')
-  let buf = RunVimInTerminal('-S Xpumopacity', {})
+  call writefile(lines, 'Xpumoptopacity', 'D')
+  let buf = RunVimInTerminal('-S Xpumoptopacity', {})
   call TermWait(buf)
   call term_sendkeys(buf, "Gohel\<C-N>")
   call TermWait(buf, 100)
-  call VerifyScreenDump(buf, 'Test_pumopacity_50', {})
+  call VerifyScreenDump(buf, 'Test_pumopt_opacity_50', {})
   call term_sendkeys(buf, "\<C-E>\<Esc>u")
   call TermWait(buf)
   call StopVimInTerminal(buf)
 endfunc
 
-" Test pumopacity=100 (fully opaque, same as default)
-func Test_pumopacity_100()
+" Test pumopt opacity:100 (fully opaque, same as default)
+func Test_pumopt_opacity_100()
   CheckScreendump
   let lines =<< trim END
-    set pumopacity=100
+    set pumopt=opacity:100
     set completeopt=menu
     call setline(1, ['hello world', 'hello vim', 'hello opacity', 'help me'])
     for i in range(5)
@@ -2477,16 +2455,15 @@ func Test_pumopacity_100()
     endfor
     normal gg
   END
-  call writefile(lines, 'Xpumopacity100', 'D')
-  let buf = RunVimInTerminal('-S Xpumopacity100', {})
+  call writefile(lines, 'Xpumoptopacity100', 'D')
+  let buf = RunVimInTerminal('-S Xpumoptopacity100', {})
   call TermWait(buf)
   call term_sendkeys(buf, "Gohel\<C-N>")
   call TermWait(buf, 100)
-  call VerifyScreenDump(buf, 'Test_pumopacity_100', {})
+  call VerifyScreenDump(buf, 'Test_pumopt_opacity_100', {})
   call term_sendkeys(buf, "\<C-E>\<Esc>u")
   call TermWait(buf)
   call StopVimInTerminal(buf)
 endfunc
 
-
 " vim: shiftwidth=2 sts=2 expandtab

From b5847311d40a963d82627c318eca85b3f75a5e04 Mon Sep 17 00:00:00 2001
From: Yasuhiro Matsumoto <mattn.jp@gmail.com>
Date: Sun, 22 Mar 2026 19:49:43 +0900
Subject: [PATCH 14/16] Add 'pumopt' tag to doc/tags

---
 runtime/doc/tags | 1 +
 1 file changed, 1 insertion(+)

diff --git a/runtime/doc/tags b/runtime/doc/tags
index 77b19ec7ffe126..0f91e2a41356f7 100644
--- a/runtime/doc/tags
+++ b/runtime/doc/tags
@@ -891,6 +891,7 @@ $quote	eval.txt	/*$quote*
 'pumborder'	options.txt	/*'pumborder'*
 'pumheight'	options.txt	/*'pumheight'*
 'pummaxwidth'	options.txt	/*'pummaxwidth'*
+'pumopt'	options.txt	/*'pumopt'*
 'pumwidth'	options.txt	/*'pumwidth'*
 'pvh'	options.txt	/*'pvh'*
 'pvp'	options.txt	/*'pvp'*

From b361b48185d4660b69cc56aef8bebb4708dd4d21 Mon Sep 17 00:00:00 2001
From: Yasuhiro Matsumoto <mattn.jp@gmail.com>
Date: Thu, 26 Mar 2026 18:07:39 +0900
Subject: [PATCH 15/16] Fix pum position offset when using 'pumopt'

pum_set_border_chars() unconditionally sets pum_border = 1.
Calling it with all zeros during pumopt reset re-enabled the border
right after PUM_BORDER_CLEAR() disabled it, causing the pum to appear
one row lower than expected.
---
 src/optionstr.c | 2 --
 1 file changed, 2 deletions(-)

diff --git a/src/optionstr.c b/src/optionstr.c
index 8d4cbfe9138d82..9647f7c015f967 100644
--- a/src/optionstr.c
+++ b/src/optionstr.c
@@ -3787,7 +3787,6 @@ did_set_pumopt(optset_T *args)
 
     // Reset to defaults.
     PUM_BORDER_CLEAR();
-    pum_set_border_chars(0, 0, 0, 0, 0, 0, 0, 0);
     p_ph = 0;
     p_pw = 15;
     p_pmw = 0;
@@ -3868,7 +3867,6 @@ did_set_pumopt(optset_T *args)
 
 error:
     PUM_BORDER_CLEAR();
-    pum_set_border_chars(0, 0, 0, 0, 0, 0, 0, 0);
     p_ph = 0;
     p_pw = 15;
     p_pmw = 0;

From 75285fd76e5382070a4b26eb94244709880ffc12 Mon Sep 17 00:00:00 2001
From: Yasuhiro Matsumoto <mattn.jp@gmail.com>
Date: Thu, 26 Mar 2026 18:27:36 +0900
Subject: [PATCH 16/16] Fix pum opacity rendering issues with border

- Draw border/shadow before setting screen_pum_blend so they render
  opaque instead of partially transparent.
- Expand pum_under_menu() to cover border, margin, and shadow areas
  to prevent flicker during completion selection.
- Remove text cell blending in screen_puts_len() that caused
  underlying syntax highlight colors to leak into pum foreground.
---
 src/popupmenu.c                               | 26 ++++++++++++-------
 src/screen.c                                  | 11 --------
 .../dumps/Test_pumopt_opacity_100.dump        |  8 +++---
 src/testdir/dumps/Test_pumopt_opacity_50.dump |  8 +++---
 4 files changed, 25 insertions(+), 28 deletions(-)

diff --git a/src/popupmenu.c b/src/popupmenu.c
index bd68cf0de5a8cb..2ee720087d1686 100644
--- a/src/popupmenu.c
+++ b/src/popupmenu.c
@@ -406,11 +406,17 @@ pum_call_update_screen(void)
     int
 pum_under_menu(int row, int col, int only_redrawing)
 {
+    int	extra_left = pum_border + (pum_margin && pum_border ? 1 : 0);
+    int	extra_right = pum_border + (pum_margin && pum_border ? 1 : 0)
+						+ (pum_shadow ? 2 : 0);
+    int	extra_above = pum_border;
+    int	extra_below = pum_border + (pum_shadow ? 1 : 0);
+
     return (!only_redrawing || pum_will_redraw)
-	    && row >= pum_row
-	    && row < pum_row + pum_height
-	    && col >= pum_col - 1
-	    && col < pum_col + pum_width + pum_scrollbar;
+	    && row >= pum_row - extra_above
+	    && row < pum_row + pum_height + extra_below
+	    && col >= pum_col - 1 - extra_left
+	    && col < pum_col + pum_width + pum_scrollbar + extra_right;
 }
 
 /*
@@ -1073,16 +1079,18 @@ pum_redraw(void)
     screen_zindex = POPUPMENU_ZINDEX;
 #endif
 
-    // Set blend for screen_puts_len / screen_fill to use.
-    if (opacity_active)
-	screen_pum_blend = 100 - (int)p_po;
-
-    // Draw border and shadow first if enabled
+    // Draw border and shadow first if enabled, before setting blend
+    // so that border/shadow characters are drawn without opacity.
     if (pum_border)
 	pum_draw_border();
     if (pum_shadow)
 	pum_draw_shadow();
 
+    // Set blend for screen_puts_len / screen_fill to use.
+    // Only the pum content area should be blended, not border/shadow.
+    if (opacity_active)
+	screen_pum_blend = 100 - (int)p_po;
+
     for (i = 0; i < pum_height; ++i)
     {
 	idx = i + pum_first;
diff --git a/src/screen.c b/src/screen.c
index 436de3195b5f21..e1ee69b014fb89 100644
--- a/src/screen.c
+++ b/src/screen.c
@@ -1772,17 +1772,6 @@ screen_puts_len(
 		ScreenLines[off + mbyte_blen] = 0;
 	    ScreenLines[off] = c;
 	    ScreenAttrs[off] = attr;
-	    // For pum opacity: blend text background with underlying.
-	    if (screen_pum_blend > 0
-		    && pum_bg_attrs != NULL
-		    && row >= pum_bg_top && row < pum_bg_bot
-		    && col < pum_bg_cols)
-	    {
-		int soff = (row - pum_bg_top) * pum_bg_cols + col;
-
-		ScreenAttrs[off] = hl_blend_attr(pum_bg_attrs[soff],
-					    attr, screen_pum_blend, FALSE);
-	    }
 	    ScreenCols[off] = -1;
 	    if (enc_utf8)
 	    {
diff --git a/src/testdir/dumps/Test_pumopt_opacity_100.dump b/src/testdir/dumps/Test_pumopt_opacity_100.dump
index dfc05172c596bb..d9e44da0f7160e 100644
--- a/src/testdir/dumps/Test_pumopt_opacity_100.dump
+++ b/src/testdir/dumps/Test_pumopt_opacity_100.dump
@@ -9,12 +9,12 @@
 |B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G
 |R|O|U|N|D| @69
 |B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G
-|R| +0#0000001#e0e0e08|h|e|l@1|o| @9| +0#0000000#ffffff0@57
-|B| +0#0000001#ffd7ff255|h|e|l|p| @10|U+0#0000000#ffffff0|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G
+|R|O|U|N|D| @69
+|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G
 |R|O|U|N|D| @69
 |h|e|l@1|o> @69
-|~+0#4040ff13&| @73
-|~| @73
+|h+0#0000001#e0e0e08|e|l@1|o| @9| +0#4040ff13#ffffff0@59
+|h+0#0000001#ffd7ff255|e|l|p| @10| +0#4040ff13#ffffff0@59
 |~| @73
 |~| @73
 |-+2#0000000&@1| |K|e|y|w|o|r|d| |c|o|m|p|l|e|t|i|o|n| |(|^|N|^|P|)| |m+0#00e0003&|a|t|c|h| |1| |o|f| |2| +0#0000000&@33
diff --git a/src/testdir/dumps/Test_pumopt_opacity_50.dump b/src/testdir/dumps/Test_pumopt_opacity_50.dump
index ac1aad12048b49..d9e44da0f7160e 100644
--- a/src/testdir/dumps/Test_pumopt_opacity_50.dump
+++ b/src/testdir/dumps/Test_pumopt_opacity_50.dump
@@ -9,12 +9,12 @@
 |B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G
 |R|O|U|N|D| @69
 |B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G
-|R| +0#0000001#e0e0e08|h|e|l@1|o| @9| +0#0000000#ffffff0@57
-|B| +0#0000001#ffd7ff255|h|e|l|p|O|U|N|D|B|A|C|K|G|R|O|U+0#0000000#ffffff0|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G
+|R|O|U|N|D| @69
+|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G|R|O|U|N|D|B|A|C|K|G
 |R|O|U|N|D| @69
 |h|e|l@1|o> @69
-|~+0#4040ff13&| @73
-|~| @73
+|h+0#0000001#e0e0e08|e|l@1|o| @9| +0#4040ff13#ffffff0@59
+|h+0#0000001#ffd7ff255|e|l|p| @10| +0#4040ff13#ffffff0@59
 |~| @73
 |~| @73
 |-+2#0000000&@1| |K|e|y|w|o|r|d| |c|o|m|p|l|e|t|i|o|n| |(|^|N|^|P|)| |m+0#00e0003&|a|t|c|h| |1| |o|f| |2| +0#0000000&@33