Merge ce818a9a91 into 7121983c45

runtime/lua/vim/_editor.lua

@@ -31,6 +31,7 @@ for k, v in pairs({
   loader = true,
   func = true,
   F = true,
+  img = true,
   lsp = true,
   hl = true,
   diagnostic = true,

runtime/lua/vim/img.lua

@@ -0,0 +1,78 @@
+local img = vim._defer_require('vim.img', {
+  _backend = ..., --- @module 'vim.img._backend'
+  _detect = ..., --- @module 'vim.img._detect'
+  _image = ..., --- @module 'vim.img._image'
+  _terminal = ..., --- @module 'vim.img._terminal'
+})
+
+---Loads an image into memory, returning a wrapper around the image.
+---
+---Accepts `data` as base64-encoded bytes, or a `filename` that will be loaded.
+---@param opts {data?:string, filename?:string}
+---@return vim.img.Image
+function img.load(opts)
+  return img._image:new(opts)
+end
+
+img.protocol = (function()
+  ---@class vim.img.Protocol 'iterm2'|'kitty'|'sixel'
+
+  ---@type vim.img.Protocol|nil
+  local protocol = nil
+
+  local loaded = false
+
+  ---Determines the preferred graphics protocol to use by default.
+  ---
+  ---@return vim.img.Protocol|nil
+  return function()
+    if not loaded then
+      local graphics = img._detect().graphics
+
+      ---@diagnostic disable-next-line:cast-type-mismatch
+      ---@cast graphics vim.img.Protocol|nil
+      protocol = graphics
+
+      loaded = true
+    end
+
+    return protocol
+  end
+end)()
+
+---@class vim.img.Opts: vim.img.Backend.RenderOpts
+---@field backend? vim.img.Protocol|vim.img.Backend
+
+---Displays the image within the terminal used by neovim.
+---@param image vim.img.Image
+---@param opts? vim.img.Opts
+function img.show(image, opts)
+  opts = opts or {}
+
+  local backend = opts.backend
+
+  -- If no graphics are explicitly defined, attempt to detect the
+  -- preferred graphics. If we still cannot figure out a backend,
+  -- throw an error early versus silently trying a protocol.
+  if not backend then
+    backend = img.protocol()
+    assert(backend, 'no graphics backend available')
+  end
+
+  -- For named protocols, grab the appropriate backend, failing
+  -- if there is not a default backend for the specified protocol.
+  if type(backend) == 'string' then
+    local protocol = backend
+    backend = img._backend[protocol]
+    assert(backend, 'unsupported backend: ' .. protocol)
+  end
+
+  ---@cast backend vim.img.Backend
+  backend.render(image, {
+    pos = opts.pos,
+    size = opts.size,
+    crop = opts.crop,
+  })
+end
+
+return img

runtime/lua/vim/img/_backend.lua

@@ -0,0 +1,12 @@
+---@class vim.img.Backend
+---@field render fun(image:vim.img.Image, opts?:vim.img.Backend.RenderOpts)
+
+---@class vim.img.Backend.RenderOpts
+---@field crop? {x:integer, y:integer, width:integer, height:integer} units are pixels
+---@field pos? {row:integer, col:integer} units are cells
+---@field size? {width:integer, height:integer} units are cells
+
+return vim._defer_require('vim.img._backend', {
+  iterm2 = ..., --- @module 'vim.img._backend.iterm2'
+  kitty = ..., --- @module 'vim.img._backend.kitty'
+})

runtime/lua/vim/img/_backend/iterm2.lua

@@ -0,0 +1,100 @@
+---@class vim.img.Iterm2Backend: vim.img.Backend
+local M = {}
+
+---@param data string
+local function write_seq(data)
+  local terminal = require('vim.img._terminal')
+
+  terminal.write(terminal.code.ESC) -- Begin sequence
+  terminal.write(']1337;')
+
+  terminal.write(data)              -- Write primary message
+
+  terminal.write(terminal.code.BEL) -- End sequence
+end
+
+---@param image vim.img.Image
+---@param args table<string, string>
+local function write_multipart_image(image, args)
+  -- Begin the transfer of the image file
+  write_seq('MultipartFile=' .. table.concat(args, ';'))
+
+  -- Begin sending parts as chunks
+  image:for_each_chunk(function(chunk)
+    write_seq('FilePart=' .. chunk)
+  end)
+
+  -- Conclude the image display
+  write_seq('FileEnd')
+end
+
+---@param image vim.img.Image
+---@param args table<string, string>
+local function write_image(image, args)
+  local data = image.data
+  if not data then
+    return
+  end
+
+  write_seq('File=' .. table.concat(args, ';') .. ':' .. data)
+end
+
+---@param image vim.img.Image
+---@param opts? vim.img.Backend.RenderOpts
+function M.render(image, opts)
+  local terminal = require('vim.img._terminal')
+
+  if not image:is_loaded() then
+    return
+  end
+
+  opts = opts or {}
+  if opts.pos then
+    terminal.cursor.move(opts.pos.col, opts.pos.row, true)
+  end
+
+  local args = {
+    -- NOTE: We MUST mark as inline otherwise not rendered and put in a downloads folder
+    'inline=1',
+
+    -- This will show a progress indicator for a multipart image
+    'size=' .. tostring(image:size()),
+  }
+
+  -- Specify the name of the image, which iterm2 requires to be base64 encoded
+  if image.name then
+    table.insert(args, 'name=' .. vim.base64.encode(image.name))
+  end
+
+  -- If a size is provided (in cells), we add it as arguments
+  if opts.size then
+    table.insert(args, 'width=' .. tostring(opts.size.width))
+    table.insert(args, 'height=' .. tostring(opts.size.height))
+
+    -- We need to disable aspect ratio preservation, otherwise
+    -- the desired width/height won't be respected
+    table.insert(args, 'preserveAspectRatio=0')
+  end
+
+  -- Only iTerm2 3.5+ supports multipart images
+  --
+  -- WezTerm and others are assumed to NOT support multipart images
+  --
+  -- iTerm2 should have set TERM_PROGRAM and TERM_PROGRAM_VERSION,
+  -- otherwise we assume a different terminal!
+  ---@type string|nil
+  local prog = vim.env.TERM_PROGRAM
+  ---@type vim.Version|nil
+  local version = vim.version.parse(vim.env.TERM_PROGRAM_VERSION or '')
+  if prog == 'iTerm.app' and version and vim.version.ge(version, { 3, 5, 0 }) then
+    write_multipart_image(image, args)
+  else
+    write_image(image, args)
+  end
+
+  if opts.pos then
+    terminal.cursor.restore()
+  end
+end
+
+return M

runtime/lua/vim/img/_backend/kitty.lua

@@ -0,0 +1,108 @@
+---@class vim.img.KittyBackend: vim.img.Backend
+local M = {}
+
+---For kitty, we need to write an image in chunks
+---
+---Graphics codes are in this form:
+---
+---    <ESC>_G<control data>;<payload><ESC>\
+---
+---To stream data for a PNG, we specify the format `f=100`.
+---
+---To simultaneously transmit and display an image, we use `a=T`.
+---
+---Chunking data (such as from over a network) requires the
+---specification of `m=0|1`, where all chunks must have a
+---value of `1` except the very last chunk.
+---@param data string
+local function write_seq(data)
+  local terminal = require('vim.img._terminal')
+
+  terminal.write(terminal.code.ESC .. '_G') -- Begin sequence
+  terminal.write(data) -- Primary data
+  terminal.write(terminal.code.ESC .. '\\') -- End sequence
+end
+
+---Builds a header table of key value pairs.
+---@param opts vim.img.Backend.RenderOpts
+---@return table<string, string>
+local function make_header(opts)
+  ---@type table<string, string>
+  local header = {}
+
+  header['a'] = 'T'
+  header['f'] = '100'
+
+  local crop = opts.crop
+  local size = opts.size
+
+  if crop then
+    header['x'] = tostring(crop.x)
+    header['y'] = tostring(crop.y)
+    header['w'] = tostring(crop.width)
+    header['h'] = tostring(crop.height)
+  end
+
+  if size then
+    header['c'] = tostring(size.width)
+    header['r'] = tostring(size.height)
+  end
+
+  return header
+end
+
+---@param image vim.img.Image
+---@param opts vim.img.Backend.RenderOpts
+local function write_multipart_image(image, opts)
+  image:for_each_chunk(function(chunk, pos, has_more)
+    local data = {}
+
+    -- If at the beginning of our image, mark as a PNG to be
+    -- transmitted and displayed immediately
+    if pos == 1 then
+      -- Add an entry in our data to write out to the terminal
+      -- that is "k=v," for the key-value entries from the header
+      for key, value in pairs(make_header(opts)) do
+        table.insert(data, key .. '=' .. value .. ',')
+      end
+    end
+
+    -- If we are still sending chunks and not at the end
+    if has_more then
+      table.insert(data, 'm=1')
+    else
+      table.insert(data, 'm=0')
+    end
+
+    -- If we have a chunk available, write it
+    if string.len(chunk) > 0 then
+      table.insert(data, ';')
+      table.insert(data, chunk)
+    end
+
+    write_seq(table.concat(data))
+  end)
+end
+
+---@param image vim.img.Image
+---@param opts? vim.img.Backend.RenderOpts
+function M.render(image, opts)
+  local terminal = require('vim.img._terminal')
+
+  if not image:is_loaded() then
+    return
+  end
+
+  opts = opts or {}
+  if opts.pos then
+    terminal.cursor.move(opts.pos.col, opts.pos.row, true)
+  end
+
+  write_multipart_image(image, opts)
+
+  if opts.pos then
+    terminal.cursor.restore()
+  end
+end
+
+return M

runtime/lua/vim/img/_detect.lua

@@ -0,0 +1,88 @@
+local terminal = require('vim.img._terminal')
+
+local TERM_QUERY = {
+  -- Request device attributes (DA2).
+  --
+  -- It typically returns information about the terminal type and supported features.
+  --
+  -- Response format is typically something like '\033[>...;...;...c'
+  DEVICE_ATTRIBUTES = terminal.code.ESC .. '[>q',
+
+  -- Request device status report (DSR), checking if terminal is okay.
+  --
+  -- Response indicates its current state.
+  DEVICE_STATUS_REPORT = terminal.code.ESC .. '[5n',
+}
+
+local TERM_RESPONSE = {
+  -- Indicates that the terminal is functioning normally (no error).
+  --
+  -- 0 means 'OK'; other values indicate different states or errors.
+  OK = terminal.code.ESC .. '[0n',
+}
+
+---Detects supported graphics of the terminal.
+---@return {graphics:'iterm2'|'kitty'|'sixel'|nil, tmux:boolean, broken_sixel_cursor_placement:boolean}
+return function()
+  local results = { graphics = nil, tmux = false, broken_sixel_cursor_placement = false }
+
+  local term = os.getenv('TERM')
+  if term == 'xterm-kitty' or term == 'xterm-ghostty' or term == 'ghostty' then
+    results.graphics = 'kitty'
+  end
+
+  local term_program = os.getenv('TERM_PROGRAM')
+  if term_program == 'vscode' then
+    results.graphics = 'iterm2'
+    results.broken_sixel_cursor_placement = true
+  end
+
+  local _, err = terminal.query({
+    query = table.concat({
+      TERM_QUERY.DEVICE_ATTRIBUTES,
+      TERM_QUERY.DEVICE_STATUS_REPORT,
+    }),
+    handler = function(buffer)
+      local function has(s)
+        return string.find(buffer, s, 1, true) ~= nil
+      end
+
+      if has('iTerm2') or has('Konsole 2') then
+        results.graphics = 'iterm2'
+      end
+
+      if has('WezTerm') then
+        results.graphics = 'iterm2'
+        results.broken_sixel_cursor_placement = true
+      end
+
+      if has('kitty') or has('ghostty') then
+        results.graphics = 'kitty'
+      end
+
+      if has('mlterm') then
+        results.graphics = 'sixel'
+      end
+
+      if has('XTerm') or has('foot') then
+        results.graphics = 'sixel'
+        results.broken_sixel_cursor_placement = true
+      end
+
+      if has('tmux') then
+        results.tmux = true
+      end
+
+      -- Check if we have received the ok terminal response
+      local start = string.find(buffer, TERM_RESPONSE.OK, 1, true)
+      if start then
+        return string.sub(buffer, start)
+      end
+    end,
+    timeout = 250,
+  })
+
+  assert(not err, err)
+
+  return results
+end

runtime/lua/vim/img/_image.lua

@@ -0,0 +1,144 @@
+---@class vim.img.Image
+---@field name string|nil name of the image if loaded from disk
+---@field data string|nil base64 encoded data
+local M = {}
+M.__index = M
+
+---Creates a new image instance.
+---@param opts? {data?:string, filename?:string}
+---@return vim.img.Image
+function M:new(opts)
+  opts = opts or {}
+
+  local instance = {}
+  setmetatable(instance, M)
+
+  instance.data = opts.data
+  if not instance.data and opts.filename then
+    instance:load_from_file(opts.filename)
+  end
+
+  return instance
+end
+
+---Returns true if the image is loaded into memory.
+---@return boolean
+function M:is_loaded()
+  return self.data ~= nil
+end
+
+---Returns the size of the base64 encoded image.
+---@return integer
+function M:size()
+  return string.len(self.data or '')
+end
+
+---Iterates over the chunks of the image, invoking `f` per chunk.
+---@param f fun(chunk:string, pos:integer, has_more:boolean)
+---@param opts? {size?:integer}
+function M:for_each_chunk(f, opts)
+  opts = opts or {}
+
+  -- Chunk size, defaulting to 4k
+  local chunk_size = opts.size or 4096
+
+  local data = self.data
+  if not data then
+    return
+  end
+
+  local pos = 1
+  local len = string.len(data)
+  while pos <= len do
+    -- Get our next chunk from [pos, pos + chunk_size)
+    local end_pos = pos + chunk_size - 1
+    local chunk = data:sub(pos, end_pos)
+
+    -- If we have a chunk available, invoke our callback
+    if string.len(chunk) > 0 then
+      local has_more = end_pos + 1 <= len
+      pcall(f, chunk, pos, has_more)
+    end
+
+    pos = end_pos + 1
+  end
+end
+
+---Displays the image within the terminal used by neovim.
+---@param opts? vim.img.Opts
+function M:show(opts)
+  vim.img.show(self, opts)
+end
+
+---Loads data for an image from a file, replacing any existing data.
+---If a callback provided, will load asynchronously; otherwise, is blocking.
+---@param filename string
+---@param cb fun(err:string|nil, image:vim.img.Image|nil)
+---@overload fun(filename:string):vim.img.Image
+function M:load_from_file(filename, cb)
+  local name = vim.fn.fnamemodify(filename, ':t:r')
+
+  if not cb then
+    local stat = vim.uv.fs_stat(filename)
+    assert(stat, 'unable to stat ' .. filename)
+
+    local fd = vim.uv.fs_open(filename, 'r', 644) --[[ @type integer|nil ]]
+    assert(fd, 'unable to open ' .. filename)
+
+    local data = vim.uv.fs_read(fd, stat.size, -1) --[[ @type string|nil ]]
+    assert(data, 'unable to read ' .. filename)
+
+    self.name = name
+    self.data = vim.base64.encode(data)
+    return self
+  end
+
+  ---@param err string|nil
+  ---@return boolean
+  local function report_err(err)
+    if err then
+      vim.schedule(function()
+        cb(err)
+      end)
+    end
+
+    return err ~= nil
+  end
+
+  vim.uv.fs_stat(filename, function(stat_err, stat)
+    if report_err(stat_err) then
+      return
+    end
+    if not stat then
+      report_err('missing stat')
+      return
+    end
+
+    vim.uv.fs_open(filename, 'r', 644, function(open_err, fd)
+      if report_err(open_err) then
+        return
+      end
+      if not fd then
+        report_err('missing fd')
+        return
+      end
+
+      vim.uv.fs_read(fd, stat.size, -1, function(read_err, data)
+        if report_err(read_err) then
+          return
+        end
+
+        vim.uv.fs_close(fd, function() end)
+
+        self.name = name
+        self.data = vim.base64.encode(data or '')
+
+        vim.schedule(function()
+          cb(nil, self)
+        end)
+      end)
+    end)
+  end)
+end
+
+return M

runtime/lua/vim/img/_terminal.lua

@@ -0,0 +1,140 @@
+---@class vim.img.terminal
+---@field private __tty_name string
+local M = {}
+
+local TERM_CODE = {
+  BEL = '\x07', -- aka ^G
+  ESC = '\x1B', -- aka ^[ aka \033
+}
+
+---Retrieve the tty name used by the editor.
+---
+---E.g. /dev/ttys008
+---@return string|nil
+local function get_tty_name()
+  if vim.fn.has('win32') == 1 then
+    -- On windows, we use \\.\CON for reading and writing
+    return '\\\\.\\CON'
+  else
+    -- Linux/Mac: Use `tty` command, which reads the terminal name
+    --            in the form of something like /dev/ttys008
+    local handle = io.popen('tty 2>/dev/null')
+    if not handle then
+      return nil
+    end
+    local result = handle:read('*a')
+    handle:close()
+    result = vim.fn.trim(result)
+    if result == '' then
+      return nil
+    end
+    return result
+  end
+end
+
+---Returns the name of the tty associated with the terminal.
+---@return string
+function M.tty_name()
+  if not M.__tty_name then
+    M.__tty_name = assert(get_tty_name(), 'failed to read editor tty name')
+  end
+
+  return M.__tty_name
+end
+
+---Writes data to the editor tty.
+---@param ... string|number
+function M.write(...)
+  local handle = assert(io.open(M.tty_name(), 'w'))
+  handle:write(...)
+  handle:close()
+end
+
+---@class vim.img.terminal.cursor
+M.cursor = {}
+
+---@param x integer
+---@param y integer
+---@param save? boolean
+function M.cursor.move(x, y, save)
+  if save then
+    M.cursor.save()
+  end
+  M.write(TERM_CODE.ESC .. '[' .. y .. ';' .. x .. 'H')
+  vim.uv.sleep(1)
+end
+
+function M.cursor.save()
+  M.write(TERM_CODE.ESC .. '[s')
+end
+
+function M.cursor.restore()
+  M.write(TERM_CODE.ESC .. '[u')
+end
+
+---Terminal escape codes.
+M.code = TERM_CODE
+
+---@param opts {query:string, handler:(fun(buffer:string):string|nil), timeout?:integer}
+---@return string|nil result, string|nil err
+function M.query(opts)
+  local uv = vim.uv
+
+  opts = opts or {}
+  local query = opts.query
+  local handler = opts.handler
+  local timeout = opts.timeout or 250
+
+  local tty_fd, err
+  local function cleanup()
+    if tty_fd then
+      uv.fs_close(tty_fd)
+      tty_fd = nil
+    end
+  end
+
+  -- Identify the path to the editor's tty
+  -- NOTE: This only works on Unix-like systems!
+  local ok, tty_path = pcall(M.tty_name)
+  if not ok then
+    return nil, tty_path
+  end
+
+  -- Open the tty so we can write our query
+  tty_fd, err = uv.fs_open(tty_path, 'r+', 438)
+  if not tty_fd then
+    return nil, err
+  end
+
+  -- Write query to terminal.
+  local success, write_err = uv.fs_write(tty_fd, query, -1)
+  if not success then
+    cleanup()
+    return nil, write_err
+  end
+
+  -- Read response with timeout.
+  local buffer = ''
+  local start_time = uv.now()
+
+  while uv.now() - start_time < timeout do
+    local data, read_err = uv.fs_read(tty_fd, 512, -1)
+    if data then
+      buffer = buffer .. data
+      local result = handler(buffer)
+      if result then
+        cleanup()
+        return result
+      end
+    elseif read_err ~= 'EAGAIN' then
+      cleanup()
+      return nil, read_err
+    end
+    uv.sleep(1)
+  end
+
+  cleanup()
+  return nil, 'Timeout'
+end
+
+return M