feat: configure west gutter position

Author: petertriho

docs/configuration.md

@@ -27,6 +27,7 @@ require("scrollbar").setup({
             row = 0,
             col = 0,
             gutter = "avoid", -- "avoid" or "overlap"
+            gutter_position = "inner", -- "inner" or "outer"
         },
     },
     layout = {
@@ -168,6 +169,7 @@ width belongs to the layout, not the provider.
 - `float.placement.relative`: `"window"` or `"editor"`.
 - `float.placement.anchor`: `"NW"`, `"NE"`, `"SW"`, or `"SE"`.
 - `float.placement.gutter`: `"avoid"` or `"overlap"`.
+- `float.placement.gutter_position`: `"inner"` or `"outer"`.
 - `float.placement.row` and `col`: signed integers.
 - `thumb.text`: one positive-display-width string without control characters.
 - Exclusion options: dense string lists.

docs/layout-and-geometry.md

@@ -82,7 +82,8 @@ ordered prefix remains and the tail is omitted. Custom providers emitting
 window. `"editor"` uses editor coordinates and renders only the active source
 window. `anchor` selects `NW`, `NE`, `SW`, or `SE`; signed `row` and `col`
 offsets are applied literally. `gutter` selects `"avoid"` (the default) or
-`"overlap"`.
+`"overlap"`. `gutter_position` selects `"inner"` (the default, beside buffer
+text) or `"outer"` (at the source-window edge) within an avoided west gutter.
 
 Gutter placement applies as follows:
 
@@ -94,20 +95,22 @@ Gutter placement applies as follows:
 
 For a window-relative west anchor, let `G` be the source's gutter width before
 the scrollbar reservation, `W` the rendered float width, and `C` the configured
-`col`. In `avoid` mode the renderer reserves `max(0, W + C)` blank cells at the
-text edge and places the float at `G + C`. With the default `col = 0`, the float
-occupies only those new cells and its right edge meets the shifted buffer-text
-edge. A positive offset leaves a gap before the float. A negative offset remains
-literal and may deliberately overlap existing gutter cells.
+`col`. In `avoid` mode the renderer reserves `max(0, W + C)` blank cells. With
+`gutter_position = "inner"`, the reservation follows the existing gutter and
+the float starts at `G + C`, beside the shifted buffer-text edge. With
+`gutter_position = "outer"`, the reservation precedes the existing gutter and
+the float starts at `C`, beside the source-window edge. A positive offset leaves
+a gap before the float within its reservation. A negative offset remains
+literal and may deliberately extend outside or overlap adjacent gutter cells.
 
 The reservation temporarily wraps the window-local `statuscolumn` and expands
 its available width. Existing fold, sign, number, custom-format, and `%!`
-content remains before the reserved blank cells. The original `statuscolumn`
-and `numberwidth` are restored when the scrollbar is hidden, disposed, becomes
-ineligible, or switches to an unaffected placement. An external edit made while
-the reservation is active is preserved instead of overwritten. Each split owns
-and restores its reservation independently, including splits created from an
-already reserved window.
+content remains intact before an `"inner"` reservation or after an `"outer"`
+reservation. The original `statuscolumn` and `numberwidth` are restored when the
+scrollbar is hidden, disposed, becomes ineligible, or switches to an unaffected
+placement. An external edit made while the reservation is active is preserved
+instead of overwritten. Each split owns and restores its reservation
+independently, including splits created from an already reserved window.
 
 Neovim limits the maximum statuscolumn width. If a declared west layout is too
 wide to reserve completely, the renderer omits that scrollbar instead of

docs/presets.md

@@ -29,8 +29,8 @@ require("scrollbar").setup({ preset = "review" })
 - `gvim`: a solid two-column conventional scrollbar without annotations.
 - `eclipse`: a bar plus diagnostic, navigation, and catch-all annotation lanes.
 - `sublime`: a trackless translucent thumb with all marks above it.
-- `emacs`: a west-anchored bar in a dedicated gutter reservation, with an
-  inward diagnostic fringe.
+- `emacs`: a west-anchored bar at the outer edge of a dedicated gutter
+  reservation, with an inward diagnostic fringe.
 - `xcode`: a compact bar with navigation and diagnostic stripes.
 
 Editor-named presets approximate scrollbar and annotation structure in terminal
@@ -129,7 +129,7 @@ layout = {
 layout = { direction = "auto", columns = { { "thumb", "marks" } } }
 
 -- emacs
-float = { placement = { anchor = "NW", gutter = "avoid" } }
+float = { placement = { anchor = "NW", gutter = "avoid", gutter_position = "outer" } }
 layout = {
     direction = "auto",
     columns = {

lua/scrollbar/config.lua

@@ -24,6 +24,7 @@ local DEFAULTS = {
             row = 0,
             col = 0,
             gutter = "avoid",
+            gutter_position = "inner",
         },
     },
     layout = {
@@ -197,7 +198,14 @@ local NESTED_KEYS = {
     autohide = { enabled = true, delay_ms = true },
     render = { interval_ms = true, geometry = true },
     float = { zindex = true, hide_on_cursor = true, placement = true },
-    ["float.placement"] = { relative = true, anchor = true, row = true, col = true, gutter = true },
+    ["float.placement"] = {
+        relative = true,
+        anchor = true,
+        row = true,
+        col = true,
+        gutter = true,
+        gutter_position = true,
+    },
     layout = { direction = true, columns = true },
     track = { highlight = true },
     mouse = { enabled = true },
@@ -260,6 +268,7 @@ local ENUMS = {
     relative = { window = true, editor = true },
     anchor = { NW = true, NE = true, SW = true, SE = true },
     gutter = { avoid = true, overlap = true },
+    gutter_position = { inner = true, outer = true },
     direction = { auto = true, ltr = true, rtl = true },
     search_backend = { sync = true, worker = true },
 }
@@ -822,6 +831,7 @@ local function normalize(overrides)
     validate_enum(result.float.placement.relative, "float.placement.relative", ENUMS.relative)
     validate_enum(result.float.placement.anchor, "float.placement.anchor", ENUMS.anchor)
     validate_enum(result.float.placement.gutter, "float.placement.gutter", ENUMS.gutter)
+    validate_enum(result.float.placement.gutter_position, "float.placement.gutter_position", ENUMS.gutter_position)
     if not is_integer(result.float.placement.row) then
         invalid("float.placement.row must be an integer")
     end

lua/scrollbar/presets.lua

@@ -112,7 +112,7 @@ local BUILTINS = {
         thumb = { blend = 60 },
     },
     emacs = {
-        float = { placement = { anchor = "NW", gutter = "avoid" } },
+        float = { placement = { anchor = "NW", gutter = "avoid", gutter_position = "outer" } },
         layout = {
             direction = "auto",
             columns = {
@@ -149,7 +149,14 @@ local NESTED_FIELDS = {
     track = { highlight = true },
     thumb = { text = true, blend = true, highlight = true, hide_if_all_visible = true },
     mark = { text = true, priority = true, highlight = true },
-    placement = { relative = true, anchor = true, row = true, col = true, gutter = true },
+    placement = {
+        relative = true,
+        anchor = true,
+        row = true,
+        col = true,
+        gutter = true,
+        gutter_position = true,
+    },
     layer = { kind = true, types = true, max_width = true },
 }
 

lua/scrollbar/renderer.lua

@@ -17,6 +17,7 @@ local STATUSCOLUMN_WRAPPER_PATTERN = '^%%!v:lua%.require%("scrollbar%.renderer"%
 ---@field applied_numberwidth integer
 ---@field span integer
 ---@field base_textoff integer
+---@field position ScrollbarGutterPosition
 ---@field limited boolean
 ---@field failed boolean
 
@@ -178,8 +179,9 @@ end
 
 ---@param source_win integer
 ---@param span integer
+---@param position ScrollbarGutterPosition
 ---@return ScrollbarStatuscolumnReservation?
-local function ensure_statuscolumn(source_win, span)
+local function ensure_statuscolumn(source_win, span, position)
     restore_inherited_statuscolumn(source_win)
     if span <= 0 then
         release_statuscolumn(source_win)
@@ -194,6 +196,7 @@ local function ensure_statuscolumn(source_win, span)
         if
             current_statuscolumn ~= reservation.applied_statuscolumn
             or current_numberwidth ~= reservation.applied_numberwidth
+            or reservation.position ~= position
         then
             release_statuscolumn(source_win)
             reservation = nil
@@ -224,6 +227,7 @@ local function ensure_statuscolumn(source_win, span)
             applied_numberwidth = original_numberwidth + span,
             span = span,
             base_textoff = vim.fn.getwininfo(source_win)[1].textoff,
+            position = position,
             limited = false,
             failed = false,
         }
@@ -317,7 +321,8 @@ M._statuscolumn = function(owner_win)
         value = type(evaluated) == "string" and evaluated or vim.fn.string(evaluated)
     end
     if drawn_win == owner_win then
-        value = value .. string.rep(" ", reservation.span)
+        local gap = string.rep(" ", reservation.span)
+        value = reservation.position == "outer" and gap .. value or value .. gap
     end
     return value
 end
@@ -540,7 +545,10 @@ local function float_config(active_config, source_win, area, container_width, wi
     local placement = active_config.float.placement
     local north = placement.anchor == "NW" or placement.anchor == "NE"
     local west = placement.anchor == "NW" or placement.anchor == "SW"
-    local west_origin = reserves_statuscolumn(active_config) and reservation_base_textoff(source_win) or 0
+    local west_origin = 0
+    if reserves_statuscolumn(active_config) and placement.gutter_position == "inner" then
+        west_origin = reservation_base_textoff(source_win)
+    end
     local vertical_anchor
     if placement.relative == "window" then
         vertical_anchor = north and 0 or area.height
@@ -1020,7 +1028,10 @@ local function render_source(source_win, selection, root_config)
     if reserved then
         local initial_width = existing_state and existing_state.width or active_config.layout.width
         local initial_span = math.max(0, initial_width + active_config.float.placement.col)
-        if initial_span > 0 and ensure_statuscolumn(source_win, initial_span) == nil then
+        if
+            initial_span > 0
+            and ensure_statuscolumn(source_win, initial_span, active_config.float.placement.gutter_position) == nil
+        then
             close_source(source_win)
             return nil
         end
@@ -1096,7 +1107,7 @@ local function render_source(source_win, selection, root_config)
         if span == (current and current.span or 0) then
             break
         end
-        if span > 0 and ensure_statuscolumn(source_win, span) == nil then
+        if span > 0 and ensure_statuscolumn(source_win, span, active_config.float.placement.gutter_position) == nil then
             close_source(source_win)
             return nil
         end
@@ -1124,7 +1135,11 @@ local function render_source(source_win, selection, root_config)
         if state ~= nil then
             close_state(state)
             if reserved then
-                ensure_statuscolumn(source_win, math.max(0, output.width + active_config.float.placement.col))
+                ensure_statuscolumn(
+                    source_win,
+                    math.max(0, output.width + active_config.float.placement.col),
+                    active_config.float.placement.gutter_position
+                )
             end
         end
         local active_float_config =

lua/scrollbar/types.lua

@@ -5,6 +5,7 @@
 ---@alias ScrollbarPlacementRelative "window"|"editor"
 ---@alias ScrollbarFloatAnchor "NW"|"NE"|"SW"|"SE"
 ---@alias ScrollbarGutterMode "avoid"|"overlap"
+---@alias ScrollbarGutterPosition "inner"|"outer"
 ---@alias ScrollbarLayoutDirection "auto"|"ltr"|"rtl"
 ---@alias ScrollbarSearchBackend "sync"|"worker"
 ---@alias ScrollbarText string|string[]
@@ -18,6 +19,7 @@
 ---@field row? integer
 ---@field col? integer
 ---@field gutter? ScrollbarGutterMode
+---@field gutter_position? ScrollbarGutterPosition
 
 ---@class ScrollbarUserFloatConfig
 ---@field zindex? integer
@@ -143,6 +145,7 @@
 ---@field row integer
 ---@field col integer
 ---@field gutter ScrollbarGutterMode
+---@field gutter_position ScrollbarGutterPosition
 
 ---@class ScrollbarFloatConfig
 ---@field zindex integer

tests/test_config.lua

@@ -55,6 +55,7 @@ T["normalizes a fresh one-column default without setup-only state"] = function()
     local second = set()
     expect.equality(second.visibility, "all")
     expect.equality(second.float.placement.gutter, "avoid")
+    expect.equality(second.float.placement.gutter_position, "inner")
     expect.equality(second.layout.direction, "auto")
     expect.equality(second.layout.width, 1)
     expect.equality(layer_kinds(second.layout.columns[1]), { "track", "thumb", "marks" })
@@ -182,7 +183,14 @@ T["accepts the complete typed runtime schema"] = function()
         float = {
             zindex = 60,
             hide_on_cursor = false,
-            placement = { relative = "editor", anchor = "SW", row = -2, col = 3, gutter = "overlap" },
+            placement = {
+                relative = "editor",
+                anchor = "SW",
+                row = -2,
+                col = 3,
+                gutter = "overlap",
+                gutter_position = "outer",
+            },
         },
         layout = {
             direction = "rtl",
@@ -222,6 +230,7 @@ T["accepts the complete typed runtime schema"] = function()
     expect.equality(result.max_lines, 1000)
     expect.equality(result.float.placement.row, -2)
     expect.equality(result.float.placement.gutter, "overlap")
+    expect.equality(result.float.placement.gutter_position, "outer")
     expect.equality(result.layout.direction, "rtl")
     expect.equality(result.layout.width, 2)
     expect.equality(result.track.highlight, track_highlight)
@@ -339,6 +348,11 @@ T["failed setup preserves active config"] = function()
         "float.placement.gutter must be one of: avoid, overlap"
     )
     expect.equality(config.get(), before)
+    expect_invalid(
+        { float = { placement = { gutter_position = "middle" } } },
+        "float.placement.gutter_position must be one of: inner, outer"
+    )
+    expect.equality(config.get(), before)
     expect_invalid({ excluded_filetypes = { "lua", false } }, "excluded_filetypes%[2%] must be a string")
     expect.equality(config.get(), before)
 end

tests/test_presets.lua

@@ -149,7 +149,7 @@ T["resolves exact isolated built-in presentation definitions"] = function()
             thumb = { blend = 60 },
         },
         emacs = {
-            float = { placement = { anchor = "NW", gutter = "avoid" } },
+            float = { placement = { anchor = "NW", gutter = "avoid", gutter_position = "outer" } },
             layout = {
                 direction = "auto",
                 columns = {
@@ -219,7 +219,7 @@ T["applies built-in overlays inheritance and root overrides deterministically"]
         presets = {
             child = {
                 extends = "vscode",
-                float = { placement = { gutter = "overlap" } },
+                float = { placement = { gutter = "overlap", gutter_position = "outer" } },
                 thumb = { blend = 30 },
                 marks = { Search = { text = { "C" } } },
             },
@@ -234,6 +234,7 @@ T["applies built-in overlays inheritance and root overrides deterministically"]
 
     expect.equality(result.layout.columns[1][1], "track")
     expect.equality(result.float.placement.gutter, "overlap")
+    expect.equality(result.float.placement.gutter_position, "outer")
     expect.equality(result.thumb, { text = "V", blend = 40 })
     expect.equality(result.marks.Search.text, { "R" })
     expect.equality(result.preset, nil)

tests/test_profiles.lua

@@ -35,7 +35,7 @@ T["compiles profile variants with setup-local presets and settled precedence"] =
                 match = { filetypes = { "lua" } },
                 preset = "local_review",
                 config = {
-                    float = { placement = { gutter = "overlap" } },
+                    float = { placement = { gutter = "overlap", gutter_position = "outer" } },
                     thumb = { blend = 10 },
                     mouse = { enabled = false },
                 },
@@ -57,12 +57,14 @@ T["compiles profile variants with setup-local presets and settled precedence"] =
     expect.equality(variants[2].config.thumb.text, "R")
     expect.equality(variants[2].config.thumb.blend, 10)
     expect.equality(variants[2].config.float.placement.gutter, "overlap")
+    expect.equality(variants[2].config.float.placement.gutter_position, "outer")
     expect.equality(variants[2].config.mouse.enabled, false)
     expect.equality(variants[2].config.visibility, root.visibility)
     expect.equality(variants[3].id, 2)
     expect.equality(variants[3].config.layout.width, 1)
     expect.equality(variants[3].config.thumb.blend, 35)
     expect.equality(variants[3].config.float.placement.gutter, "avoid")
+    expect.equality(variants[3].config.float.placement.gutter_position, "inner")
     expect.equality(variants[3].config.render.geometry, "screen")
 
     for _, variant in ipairs(variants) do
@@ -92,6 +94,14 @@ T["validates profile schema and the nested render-safe boundary"] = function()
             },
         },
     }, "float.placement.gutter must be one of: avoid, overlap")
+    expect_invalid({
+        profiles = {
+            {
+                match = { filetypes = { "lua" } },
+                config = { float = { placement = { gutter_position = "middle" } } },
+            },
+        },
+    }, "float.placement.gutter_position must be one of: inner, outer")
 
     local rejected = {
         { show = false },