auvrynt 1.0.2 → 1.0.5

package/extensions/auvrynt_bridge/live_effects.lua

@@ -0,0 +1,91 @@
+local C = require("live_common")
+local M = {}
+
+local function draw_symmetry(sprite, params)
+  local count = C.sequence_length(params.points)
+  if not count or count < 1 or count > 8192 then C.fail("points must contain 1-8192 entries") end
+  if type(params.color) ~= "string" then C.fail("color is required") end
+  local layer, frame_number = C.active_target(sprite, params)
+  local pixel = C.color_to_pixel(sprite, C.color_from_hex(params.color))
+  local axis_x = tonumber(params.axisX) or ((sprite.width - 1) / 2)
+  local axis_y = tonumber(params.axisY) or ((sprite.height - 1) / 2)
+  local mirror_x = params.horizontal ~= false
+  local mirror_y = params.vertical == true
+  local coordinates, unique = {}, {}
+  local function add(x, y)
+    x, y = C.integer(x, -1), C.integer(y, -1)
+    if x < 0 or y < 0 or x >= sprite.width or y >= sprite.height then return end
+    local key = x .. ":" .. y
+    if unique[key] then return end
+    unique[key] = true
+    coordinates[#coordinates+1] = {x=x,y=y}
+  end
+  for index=1,count do
+    local point = params.points[index]
+    local x, y = C.integer(point.x, -1), C.integer(point.y, -1)
+    add(x, y)
+    if mirror_x then add(math.floor(2*axis_x-x+0.5), y) end
+    if mirror_y then add(x, math.floor(2*axis_y-y+0.5)) end
+    if mirror_x and mirror_y then add(math.floor(2*axis_x-x+0.5), math.floor(2*axis_y-y+0.5)) end
+  end
+  local written = 0
+  app.transaction("Auvrynt Live Symmetry", function()
+    local cel = C.get_canvas_cel(sprite, layer, frame_number, true)
+    for _, point in ipairs(coordinates) do
+      if C.selection_allows(sprite, point.x, point.y) then
+        cel.image:drawPixel(point.x, point.y, pixel)
+        written = written + 1
+      end
+    end
+  end)
+  return { written=written, layer=layer.name, frame=frame_number, axisX=axis_x, axisY=axis_y, horizontal=mirror_x, vertical=mirror_y }
+end
+
+local BAYER = {
+  [2]={0,2,3,1},
+  [4]={0,8,2,10,12,4,14,6,3,11,1,9,15,7,13,5},
+  [8]={
+    0,32,8,40,2,34,10,42,48,16,56,24,50,18,58,26,
+    12,44,4,36,14,46,6,38,60,28,52,20,62,30,54,22,
+    3,35,11,43,1,33,9,41,51,19,59,27,49,17,57,25,
+    15,47,7,39,13,45,5,37,63,31,55,23,61,29,53,21,
+  },
+}
+
+local function apply_dither(sprite, params)
+  if type(params.colorA) ~= "string" or type(params.colorB) ~= "string" then C.fail("colorA and colorB are required") end
+  local matrix_size = C.integer(params.matrixSize, 4)
+  if not BAYER[matrix_size] then C.fail("matrixSize must be 2, 4, or 8") end
+  local amount = C.clamp(tonumber(params.amount) or 0.5, 0, 1)
+  local region = params.region or {}
+  local x = C.clamp(C.integer(region.x, 0), 0, sprite.width-1)
+  local y = C.clamp(C.integer(region.y, 0), 0, sprite.height-1)
+  local width = C.clamp(C.integer(region.width, sprite.width-x), 1, sprite.width-x)
+  local height = C.clamp(C.integer(region.height, sprite.height-y), 1, sprite.height-y)
+  local layer, frame_number = C.active_target(sprite, params)
+  local a = C.color_to_pixel(sprite, C.color_from_hex(params.colorA))
+  local b = C.color_to_pixel(sprite, C.color_from_hex(params.colorB))
+  local matrix = BAYER[matrix_size]
+  local changed = 0
+  app.transaction("Auvrynt Live Ordered Dither", function()
+    local cel = C.get_canvas_cel(sprite, layer, frame_number, true)
+    for yy=y,y+height-1 do
+      for xx=x,x+width-1 do
+        if C.selection_allows(sprite, xx, yy) then
+          local index = (yy % matrix_size) * matrix_size + (xx % matrix_size) + 1
+          local threshold = (matrix[index] + 0.5) / (matrix_size * matrix_size)
+          cel.image:drawPixel(xx, yy, threshold < amount and b or a)
+          changed = changed + 1
+        end
+      end
+    end
+  end)
+  return { changed=changed, matrixSize=matrix_size, amount=amount, region={x=x,y=y,width=width,height=height}, layer=layer.name, frame=frame_number }
+end
+
+M.handlers = {
+  draw_symmetry=draw_symmetry,
+  apply_dither=apply_dither,
+}
+
+return M

package/extensions/auvrynt_bridge/live_palette_template.lua

@@ -0,0 +1,167 @@
+local C = require("live_common")
+local M = {}
+
+local function get_palette(sprite, _)
+  local palette = sprite.palettes[1]
+  local colors = {}
+  for index=0,#palette-1 do
+    local color = palette:getColor(index)
+    local alpha = index == sprite.transparentColor and 0 or color.alpha
+    colors[index+1] = C.color_to_hex(Color{r=color.red,g=color.green,b=color.blue,a=alpha})
+  end
+  return { size=#palette, transparentIndex=sprite.transparentColor, colors=colors }
+end
+
+local function set_palette_color(sprite, params)
+  if type(params.color) ~= "string" then C.fail("color is required") end
+  local palette = sprite.palettes[1]
+  local index = C.integer(params.index, -1)
+  if index < 0 or index > 255 then C.fail("Palette index must be between 0 and 255") end
+  app.transaction("Auvrynt Live Palette Entry", function()
+    if index >= #palette then palette:resize(index + 1) end
+    palette:setColor(index, C.color_from_hex(params.color))
+  end)
+  return { index=index, color=C.color_to_hex(palette:getColor(index)), size=#palette }
+end
+
+local function set_palette(sprite, params)
+  local count = C.sequence_length(params.colors)
+  if not count or count < 1 or count > 256 then C.fail("colors must contain 1-256 entries") end
+  local palette = sprite.palettes[1]
+  app.transaction("Auvrynt Live Set Palette", function()
+    palette:resize(count)
+    for index=1,count do palette:setColor(index - 1, C.color_from_hex(params.colors[index])) end
+  end)
+  return get_palette(sprite, {})
+end
+
+local function generate_color_ramp(sprite, params)
+  if type(params.startColor) ~= "string" or type(params.endColor) ~= "string" then C.fail("startColor and endColor are required") end
+  local start, finish = C.color_from_hex(params.startColor), C.color_from_hex(params.endColor)
+  local steps = C.clamp(C.integer(params.steps, 5), 2, 256)
+  local colors = {}
+  for index=0,steps-1 do
+    local t = index / (steps - 1)
+    colors[index+1] = C.color_to_hex(Color {
+      r=math.floor(start.red + (finish.red-start.red)*t + 0.5),
+      g=math.floor(start.green + (finish.green-start.green)*t + 0.5),
+      b=math.floor(start.blue + (finish.blue-start.blue)*t + 0.5),
+      a=math.floor(start.alpha + (finish.alpha-start.alpha)*t + 0.5),
+    })
+  end
+  if params.apply == true then
+    local palette, start_index = sprite.palettes[1], C.clamp(C.integer(params.startIndex, 0), 0, 255)
+    if start_index + steps > 256 then C.fail("Color ramp exceeds the 256-entry palette limit") end
+    app.transaction("Auvrynt Live Color Ramp", function()
+      if #palette < start_index + steps then palette:resize(start_index + steps) end
+      for index=1,steps do palette:setColor(start_index + index - 1, C.color_from_hex(colors[index])) end
+    end)
+  end
+  return { colors=colors, steps=steps, applied=params.apply == true }
+end
+
+local function sort_palette(sprite, params)
+  local palette = sprite.palettes[1]
+  local sort_by = tostring(params.sortBy or "hue")
+  local reverse = params.reverse == true
+  local entries = {}
+  for index=0,#palette-1 do
+    local color = palette:getColor(index)
+    entries[#entries+1] = { old=index, color=color }
+  end
+  local function value(entry)
+    local color = entry.color
+    if sort_by == "hue" then return color.hslHue
+    elseif sort_by == "saturation" then return color.hslSaturation
+    elseif sort_by == "lightness" or sort_by == "brightness" then return color.hslLightness
+    elseif sort_by == "red" then return color.red
+    elseif sort_by == "green" then return color.green
+    elseif sort_by == "blue" then return color.blue
+    elseif sort_by == "alpha" then return color.alpha
+    else C.fail("sortBy must be hue, saturation, lightness, brightness, red, green, blue, or alpha") end
+  end
+  table.sort(entries, function(a, b)
+    local av, bv = value(a), value(b)
+    if av == bv then return a.old < b.old end
+    return reverse and av > bv or av < bv
+  end)
+  local mapping = {}
+  for new_index, entry in ipairs(entries) do mapping[entry.old] = new_index - 1 end
+  local old_transparent = sprite.transparentColor
+  app.transaction("Auvrynt Live Sort Palette", function()
+    if sprite.colorMode == ColorMode.INDEXED then
+      local seen = {}
+      for _, cel in ipairs(sprite.cels) do
+        if not cel.layer.isTilemap then
+          local image = cel.image
+          local key = tostring(image.id)
+          if not seen[key] then
+            seen[key] = true
+            for y=0,image.height-1 do
+              for x=0,image.width-1 do
+                local old = image:getPixel(x, y)
+                image:drawPixel(x, y, mapping[old] or old)
+              end
+            end
+          end
+        end
+      end
+    end
+    for new_index, entry in ipairs(entries) do palette:setColor(new_index - 1, entry.color) end
+    if sprite.colorMode == ColorMode.INDEXED then sprite.transparentColor = mapping[old_transparent] or old_transparent end
+  end)
+  local result = get_palette(sprite, {})
+  result.sortBy = sort_by
+  result.reverse = reverse
+  return result
+end
+
+local function create_character_template(_, params)
+  local width = C.clamp(C.integer(params.width, params.size or 64), 8, 512)
+  local height = C.clamp(C.integer(params.height, params.size or 64), 8, 512)
+  local sprite = Sprite(width, height, ColorMode.RGB)
+  app.activeSprite = sprite
+  local definitions = params.animations
+  local count = C.sequence_length(definitions)
+  if not count or count == 0 then
+    definitions = {
+      { name="idle", frames=4, durationMs=140 },
+      { name="run", frames=8, durationMs=90 },
+      { name="attack", frames=6, durationMs=80 },
+    }
+    count = 3
+  end
+  local total_frames = 0
+  for index=1,count do total_frames = total_frames + C.clamp(C.integer(definitions[index].frames, 1), 1, 64) end
+  app.transaction("Auvrynt Character Template", function()
+    sprite.layers[1].name = "04 Body"
+    local shadow = sprite:newLayer() shadow.name = "01 Shadow" shadow.stackIndex = 1 shadow.opacity = 128
+    local silhouette = sprite:newLayer() silhouette.name = "02 Silhouette"
+    local outfit = sprite:newLayer() outfit.name = "03 Outfit"
+    local weapon = sprite:newLayer() weapon.name = "05 Weapon"
+    local effects = sprite:newLayer() effects.name = "06 Effects"
+    for frame=2,total_frames do sprite:newEmptyFrame(frame) end
+    local offset = 1
+    for index=1,count do
+      local definition = definitions[index]
+      local frames = C.clamp(C.integer(definition.frames, 1), 1, 64)
+      local duration = C.clamp(C.integer(definition.durationMs, 100), 1, 60000) / 1000
+      local tag = sprite:newTag(offset, offset + frames - 1)
+      tag.name = tostring(definition.name or ("animation_" .. index))
+      for frame=offset,offset+frames-1 do sprite.frames[frame].duration = duration end
+      offset = offset + frames
+    end
+  end)
+  return { id=tostring(sprite.id), width=width, height=height, frames=#sprite.frames, tags=#sprite.tags }
+end
+
+M.handlers = {
+  get_palette=get_palette,
+  set_palette_color=set_palette_color,
+  set_palette=set_palette,
+  generate_color_ramp=generate_color_ramp,
+  sort_palette=sort_palette,
+  create_character_template=create_character_template,
+}
+
+return M

package/extensions/auvrynt_bridge/live_selection.lua

@@ -0,0 +1,110 @@
+local C = require("live_common")
+local M = {}
+
+local function apply_mask(sprite, mask, mode)
+  local selection = sprite.selection
+  mode = mode or "replace"
+  if mode == "replace" then selection:select(mask)
+  elseif mode == "add" then selection:add(mask)
+  elseif mode == "subtract" then selection:subtract(mask)
+  elseif mode == "intersect" then selection:intersect(mask)
+  else C.fail("Unsupported selection mode") end
+end
+
+local function selection_result(sprite)
+  local selection = sprite.selection
+  if not selection or selection.isEmpty then return { empty=true } end
+  local bounds = selection.bounds
+  return {
+    empty=false,
+    x=bounds.x,
+    y=bounds.y,
+    width=bounds.width,
+    height=bounds.height,
+  }
+end
+
+local function get_selection(sprite, _)
+  return selection_result(sprite)
+end
+
+local function select_all(sprite, _)
+  sprite.selection:selectAll()
+  return selection_result(sprite)
+end
+
+local function deselect(sprite, _)
+  sprite.selection:deselect()
+  return { empty=true }
+end
+
+local function invert_selection(sprite, _)
+  local inverted = Selection(Rectangle(0, 0, sprite.width, sprite.height))
+  if not sprite.selection.isEmpty then inverted:subtract(sprite.selection) end
+  sprite.selection:select(inverted)
+  return selection_result(sprite)
+end
+
+local function select_ellipse(sprite, params)
+  local x = C.integer(params.x, 0)
+  local y = C.integer(params.y, 0)
+  local width = C.integer(params.width, 1)
+  local height = C.integer(params.height, 1)
+  if width < 1 or height < 1 then C.fail("width and height must be positive") end
+  local mask = Selection()
+  local rx, ry = width / 2, height / 2
+  local cx = x + (width - 1) / 2
+  local cy = y + (height - 1) / 2
+  for row=0,height-1 do
+    local dy = ((y + row) - cy) / ry
+    local inside = 1 - dy * dy
+    if inside >= 0 then
+      local half = math.floor(rx * math.sqrt(inside))
+      local left = math.max(0, math.floor(cx - half))
+      local right = math.min(sprite.width - 1, math.ceil(cx + half))
+      local yy = y + row
+      if yy >= 0 and yy < sprite.height and right >= left then
+        mask:add(Rectangle(left, yy, right - left + 1, 1))
+      end
+    end
+  end
+  apply_mask(sprite, mask, params.mode)
+  return selection_result(sprite)
+end
+
+local function select_by_color(sprite, params)
+  if type(params.color) ~= "string" then C.fail("color is required") end
+  if sprite.width * sprite.height > 1048576 then C.fail("Color selection is limited to 1,048,576 canvas pixels") end
+  local image = C.read_canvas(sprite, params)
+  local target = C.color_to_pixel(sprite, C.color_from_hex(params.color))
+  local mask = Selection()
+  local matched = 0
+  for y=0,sprite.height-1 do
+    local run_start = nil
+    for x=0,sprite.width do
+      local equal = x < sprite.width and image:getPixel(x, y) == target
+      if equal and run_start == nil then run_start = x end
+      if not equal and run_start ~= nil then
+        mask:add(Rectangle(run_start, y, x - run_start, 1))
+        matched = matched + (x - run_start)
+        run_start = nil
+      end
+    end
+  end
+  apply_mask(sprite, mask, params.mode)
+  local result = selection_result(sprite)
+  result.matched = matched
+  result.composite = params.composite == true
+  return result
+end
+
+M.handlers = {
+  get_selection=get_selection,
+  select_all=select_all,
+  deselect=deselect,
+  invert_selection=invert_selection,
+  select_ellipse=select_ellipse,
+  select_by_color=select_by_color,
+}
+
+return M

package/extensions/auvrynt_bridge/live_structure.lua

@@ -0,0 +1,129 @@
+local C = require("live_common")
+local M = {}
+
+local BLEND_MODES = {
+  normal=BlendMode.NORMAL, multiply=BlendMode.MULTIPLY, screen=BlendMode.SCREEN,
+  overlay=BlendMode.OVERLAY, darken=BlendMode.DARKEN, lighten=BlendMode.LIGHTEN,
+  addition=BlendMode.ADDITION, subtract=BlendMode.SUBTRACT, divide=BlendMode.DIVIDE,
+}
+
+local function target_any_layer(sprite, params)
+  local layer = params.layer and C.find_layer(sprite.layers, params.layer) or app.activeLayer
+  if not layer then C.fail("Layer was not found") end
+  return layer
+end
+
+local function set_layer_properties(sprite, params)
+  local layer = target_any_layer(sprite, params)
+  app.transaction("Auvrynt Live Layer Properties", function()
+    if params.name ~= nil then layer.name = tostring(params.name) end
+    if params.visible ~= nil then layer.isVisible = params.visible == true end
+    if params.editable ~= nil then layer.isEditable = params.editable == true end
+    if params.opacity ~= nil then layer.opacity = C.clamp(C.integer(params.opacity, layer.opacity), 0, 255) end
+    if params.blendMode ~= nil then
+      local mode = BLEND_MODES[tostring(params.blendMode)]
+      if not mode then C.fail("Unsupported blend mode") end
+      layer.blendMode = mode
+    end
+  end)
+  return { id=tostring(layer.id), name=layer.name, visible=layer.isVisible, editable=layer.isEditable, opacity=layer.opacity, blendMode=tostring(layer.blendMode) }
+end
+
+local function reorder_layer(sprite, params)
+  local layer = target_any_layer(sprite, params)
+  local siblings = layer.parent and layer.parent.layers or sprite.layers
+  local index = C.clamp(C.integer(params.stackIndex, layer.stackIndex), 1, #siblings)
+  app.transaction("Auvrynt Live Reorder Layer", function() layer.stackIndex = index end)
+  return { id=tostring(layer.id), name=layer.name, stackIndex=layer.stackIndex }
+end
+
+local function get_cel(sprite, params)
+  local layer = C.target_layer(sprite, params)
+  local frame_number = C.target_frame_number(sprite, params)
+  local cel = layer:cel(frame_number)
+  if not cel then return { exists=false, layer=layer.name, frame=frame_number } end
+  return { exists=true, layer=layer.name, frame=frame_number, x=cel.position.x, y=cel.position.y, width=cel.image.width, height=cel.image.height, opacity=cel.opacity, zIndex=cel.zIndex }
+end
+
+local function set_cel(sprite, params)
+  local layer = C.target_layer(sprite, params)
+  local frame_number = C.target_frame_number(sprite, params)
+  local cel = layer:cel(frame_number)
+  if not cel and params.create ~= true then C.fail("Cel does not exist; set create=true") end
+  app.transaction("Auvrynt Live Cel Properties", function()
+    cel = cel or C.get_canvas_cel(sprite, layer, frame_number, true)
+    if params.x ~= nil or params.y ~= nil then cel.position = Point(C.integer(params.x, cel.position.x), C.integer(params.y, cel.position.y)) end
+    if params.opacity ~= nil then cel.opacity = C.clamp(C.integer(params.opacity, cel.opacity), 0, 255) end
+    if params.zIndex ~= nil then cel.zIndex = C.integer(params.zIndex, cel.zIndex) end
+  end)
+  return get_cel(sprite, { layer=layer.name, frame=frame_number })
+end
+
+local function find_tag(sprite, name)
+  for _, tag in ipairs(sprite.tags) do if tag.name == name then return tag end end
+  return nil
+end
+
+local ANI_DIRECTIONS = {
+  forward=AniDir.FORWARD, reverse=AniDir.REVERSE,
+  ping_pong=AniDir.PING_PONG, ping_pong_reverse=AniDir.PING_PONG_REVERSE,
+}
+
+local function apply_tag_fields(sprite, tag, params)
+  if params.name ~= nil then tag.name = tostring(params.name) end
+  if params.from ~= nil or params.to ~= nil then
+    local from = C.clamp(C.integer(params.from, tag.fromFrame.frameNumber), 1, #sprite.frames)
+    local to = C.clamp(C.integer(params.to, tag.toFrame.frameNumber), from, #sprite.frames)
+    tag.fromFrame, tag.toFrame = sprite.frames[from], sprite.frames[to]
+  end
+  if params.direction ~= nil then
+    local direction = ANI_DIRECTIONS[tostring(params.direction)]
+    if not direction then C.fail("Unsupported tag direction") end
+    tag.aniDir = direction
+  end
+  if params.repeats ~= nil then tag.repeats = C.clamp(C.integer(params.repeats, 0), 0, 65535) end
+  if params.color ~= nil then tag.color = C.color_from_hex(params.color) end
+end
+
+local function tag_result(tag)
+  return { name=tag.name, from=tag.fromFrame.frameNumber, to=tag.toFrame.frameNumber, direction=tostring(tag.aniDir), repeats=tag.repeats, color=C.color_to_hex(tag.color) }
+end
+
+local function create_tag(sprite, params)
+  local from = C.clamp(C.integer(params.from, 1), 1, #sprite.frames)
+  local to = C.clamp(C.integer(params.to, from), from, #sprite.frames)
+  local tag
+  app.transaction("Auvrynt Live Create Tag", function()
+    tag = sprite:newTag(from, to)
+    tag.name = tostring(params.name or "tag")
+    apply_tag_fields(sprite, tag, params)
+  end)
+  return tag_result(tag)
+end
+
+local function update_tag(sprite, params)
+  local tag = find_tag(sprite, tostring(params.tag or params.name or ""))
+  if not tag then C.fail("Tag was not found") end
+  app.transaction("Auvrynt Live Update Tag", function() apply_tag_fields(sprite, tag, params) end)
+  return tag_result(tag)
+end
+
+local function delete_tag(sprite, params)
+  local tag = find_tag(sprite, tostring(params.tag or params.name or ""))
+  if not tag then C.fail("Tag was not found") end
+  local name = tag.name
+  app.transaction("Auvrynt Live Delete Tag", function() sprite:deleteTag(tag) end)
+  return { deleted=name }
+end
+
+M.handlers = {
+  set_layer_properties=set_layer_properties,
+  reorder_layer=reorder_layer,
+  get_cel=get_cel,
+  set_cel=set_cel,
+  create_tag=create_tag,
+  update_tag=update_tag,
+  delete_tag=delete_tag,
+}
+
+return M

package/extensions/auvrynt_bridge/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "auvrynt-bridge",
+  "displayName": "Auvrynt Bridge",
+  "description": "Authenticated local bridge for structured Auvrynt access to the active Aseprite editor.",
+  "version": "1.2.0",
+  "author": "Auvrynt",
+  "license": "MIT",
+  "categories": ["Scripts"],
+  "contributes": {
+    "scripts": [
+      {
+        "id": "auvrynt-bridge",
+        "path": "./auvrynt_bridge.lua"
+      }
+    ]
+  }
+}

package/guides/ASEPRITE_AGENT_GUIDE.md

@@ -0,0 +1,133 @@
+# ASEPRITE_AGENT_GUIDE.md
+
+## Scope
+
+Use this guide for Aseprite source assets and pixel-art work, including:
+
+- `.aseprite` and `.ase` documents
+- exact pixel edits
+- frame-by-frame 2D animation
+- layers, palettes, tags, and frame timing
+- sprite-sheet and metadata export
+- format conversion, nearest-neighbor scaling, crop, and trim
+
+Auvrynt uses Aseprite's native executable, batch CLI, and parameterized Lua API. A GUI plugin is not required for these operations.
+
+## Detection
+
+Configure either the executable directly or the source/build directory:
+
+```text
+AUVRYNT_ASEPRITE_PATH=C:\path\to\aseprite.exe
+AUVRYNT_ASEPRITE_SOURCE_PATH=C:\path\to\aseprite
+```
+
+For a source directory, Auvrynt checks:
+
+```text
+build/bin/aseprite.exe
+bin/aseprite.exe
+aseprite.exe
+```
+
+The equivalent config keys are:
+
+```json
+{
+  "executables": {
+    "aseprite": "C:\\path\\to\\aseprite.exe",
+    "asepriteSource": "C:\\path\\to\\aseprite"
+  },
+  "integrations": {
+    "aseprite": true
+  }
+}
+```
+
+## Tools
+
+Auvrynt exposes 36 grouped Aseprite tools.
+
+Detection, inspection, capture, and QA:
+
+- `aseprite_detect` — executable, source path, version, and process state.
+- `aseprite_live_editor` — install/status the authenticated extension bridge and inspect or control the current unsaved editor state.
+- `aseprite_capture_current` — capture the visible Aseprite window with editor UI.
+- `aseprite_capture_canvas` — capture only the live unsaved canvas at native or nearest-neighbor scale.
+- `aseprite_inspect_file` — document structure, timing, tags, slices, and palette size.
+- `aseprite_read_pixels` — exact RGBA or indexed pixel readback, regions, histograms, and alpha bounds.
+- `aseprite_audit_sprite` — isolated/semi-transparent pixels, duplicate/empty frames, palette waste, tags, linked cels, and canvas occupancy.
+- `aseprite_compare_documents` — structural and per-frame pixel comparison of two `.aseprite` documents.
+- `aseprite_animation_audit` — timing outliers, silhouette/anchor movement, duplicates, and loop continuity.
+
+Source safety and maintenance:
+
+- `aseprite_file_safety` — SHA-256 status/assertion, checkpoints, rollback, and checkpoint deletion.
+- `aseprite_maintenance` — decode validation, repaired copy, and lossy-format round-trip analysis.
+- `aseprite_batch_process` — bounded dry-run or batch audit, convert, export, and repair.
+- `aseprite_recovery` — list/archive/discard native recovery sessions or open Aseprite's recovery UI.
+- `aseprite_extensions` — inspect resources/extensions/startup errors and explicitly manage user extensions.
+
+Pixel drawing and regions:
+
+- `aseprite_create_sprite` — create a document.
+- `aseprite_set_pixels` — surgical exact-coordinate edits.
+- `aseprite_draw_shapes` — points, Bresenham lines, and rectangles.
+- `aseprite_draw_stroke` — native brushes, pencil/eraser/bucket, inks, pixel-perfect mode, symmetry, and tiled drawing.
+- `aseprite_draw_advanced` — ellipse, polygon, gradient, outline, and flood fill.
+- `aseprite_edit_region` — copy/composite/scale/rotate/flip regions across files, layers, and frames.
+- `aseprite_manage_mask` — persistent rectangular/color/content masks and masked move/clear/fill operations.
+- `aseprite_run_safe_command` — curated allowlisted document commands; never arbitrary Lua.
+
+Document structure and animation:
+
+- `aseprite_manage_layers` — basic layer creation, naming, visibility, deletion, and opacity.
+- `aseprite_compose_layers` — groups, duplicate/merge/flatten, background conversion, ordering, locking, blending, and soloing.
+- `aseprite_manage_frames` — add, duplicate, delete, and retime frames.
+- `aseprite_manage_animation` — frame movement/copy/reversal, bulk timing, tag range/direction/repeat updates, and guarded cel-position tweening with linear/ease-in/ease-out/smoothstep easing.
+- `aseprite_manage_tags` — basic tag creation, rename, and deletion.
+- `aseprite_manage_cels` — inspect/create/delete/move/duplicate/link/unlink cels and edit opacity/z-index.
+- `aseprite_manage_document` — resize/crop/trim, grid, pixel ratio, user data, slices, pivots, and nine-slice data.
+
+Color, palettes, tilemaps, import, and export:
+
+- `aseprite_set_palette` — replace the complete document palette.
+- `aseprite_manage_color` — inspect/edit palette entries, transparent index, remap colors, ICC profiles, palette files, quantization, dithering, and built-in Game Boy, PICO-8, CGA, C64, DawnBringer16, grayscale, and monochrome presets.
+- `aseprite_import_sprite_sheet` — convert a gridded image into frames, timing, and tags.
+- `aseprite_manage_tilemap` — native tilesets, tilemap layers, tile pixels, map cells/flip flags, metadata, import, and export.
+- `aseprite_export_sprite_sheet` — standard sheet and JSON export.
+- `aseprite_manage_export_preset` — reusable full-option export presets, repeat export, and output validation.
+- `aseprite_convert_file` — nearest-neighbor conversion, crop, trim, palette, frame/tag/layer filtering, and color mode.
+
+## Required Workflow
+
+1. Call `open_workspace` for the project containing the sprite sources.
+2. Call `aseprite_detect` once.
+3. Inspect with `aseprite_inspect_file`; use `aseprite_read_pixels` or the audit tools when exact evidence matters.
+4. Call `aseprite_file_safety` with `action="status"` and retain the returned SHA-256 version.
+5. Pass `expectedVersion` into destructive calls. Leave `checkpoint` enabled unless the user explicitly rejects backups.
+6. Make the smallest focused edit.
+7. Re-inspect and run the relevant audit or comparison.
+8. Export with a project preset and validate the result.
+9. Keep project inputs/outputs inside the workspace. Global recovery or extension mutations require explicit `allowGlobalWrite=true`.
+
+## Drawing Rules
+
+- Use integer coordinates only.
+- Use `#RRGGBB` or `#RRGGBBAA` colors.
+- Prefer `aseprite_set_pixels` for surgical corrections and cluster construction.
+- Prefer `aseprite_draw_shapes` for deliberate geometric primitives, not organic automatic tracing.
+- Preserve the document palette and pixel scale unless the user asks to change them.
+- Do not resample pixel art with smoothing. Aseprite CLI scaling is nearest-neighbor.
+- Inspect neighboring frames before changing animation silhouettes.
+- Do not overwrite source documents with exported sheets.
+
+## Native Integration and Live Bridge
+
+Native CLI/Lua remains the default for deterministic saved-file operations. The bundled `auvrynt-bridge` extension adds structured access to the already-running editor without opening a network port. It uses an authenticated filesystem request queue under Aseprite's user-data directory.
+
+Use `aseprite_live_editor` for active unsaved document state, document/tab selection, save/undo/redo, playback, onion skin, zoom, active tool/brush/colors, selection, live pixel/stroke edits, and constrained safe commands. Bridge v1.2 adds 46 allowlisted `run_live_command` operations covering exact pixel/image readback; lines, shapes, fill, replace, clear and outline; layer/cel/tag edits; palette ramps and character templates; ellipse/by-color/invert selections; frame duplication/reversal/timing; cel shifting, sprite flip/rotation and cross-document copying; live resize/crop/flatten/grid and tileset templates; symmetry and ordered dithering; palette sorting that preserves indexed pixel appearance; plus live bounds, color statistics, frame comparison and animation validation. Use `aseprite_capture_canvas` for a clean canvas-only capture.
+
+The dashboard uses three distinct states. **Connected** means the live bridge answered an authenticated status request. **Available** means the native executable is usable, or Aseprite is running without a responding bridge. Merely detecting `aseprite.exe` is not a live connection. The bridge is installed by `auvrynt setup aseprite ...` and self-healed at Auvrynt startup; Aseprite must be restarted once after first installation or a bridge upgrade so the extension code is loaded.
+
+MCP clients can cache their tool catalog. After enabling Aseprite or upgrading Auvrynt, reconnect the MCP connector when `aseprite_*` tools do not appear even though the dashboard reports the profile enabled. Auvrynt sends the standard tool-list-changed notification, but not every client refreshes dynamically.