@ljwei-stak/dsh-compositor 0.0.0-stage → 0.1.0

package/.dsh-plugin/shared/comp-png.mjs

@@ -0,0 +1,209 @@
+/**
+ * Minimal PNG support for .comp projects, pure Node (zlib only).
+ *
+ * encodePngRgba / encodePngGray write 8-bit PNGs exactly as the Compositor
+ * format expects (layer images RGBA, masks 8-bit grayscale). readPngHeader
+ * decodes just the IHDR so validation can check bit depth and color type
+ * without a full decode. Layer PNG generation (solid / linear / radial) is
+ * built on the encoders.
+ */
+import { deflateSync } from 'node:zlib'
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+
+const CRC_TABLE = (() => {
+  const table = new Int32Array(256)
+  for (let n = 0; n < 256; n++) {
+    let c = n
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1
+    table[n] = c
+  }
+  return table
+})()
+
+function crc32(...buffers) {
+  let c = 0xffffffff
+  for (const buffer of buffers) for (const byte of buffer) c = CRC_TABLE[(c ^ byte) & 0xff] ^ (c >>> 8)
+  return (c ^ 0xffffffff) >>> 0
+}
+
+function chunk(type, data) {
+  const length = Buffer.alloc(4)
+  length.writeUInt32BE(data.length)
+  const typeBuffer = Buffer.from(type, 'ascii')
+  const crc = Buffer.alloc(4)
+  crc.writeUInt32BE(crc32(typeBuffer, data))
+  return Buffer.concat([length, typeBuffer, data, crc])
+}
+
+function ihdr(width, height, bitDepth, colorType) {
+  const data = Buffer.alloc(13)
+  data.writeUInt32BE(width, 0)
+  data.writeUInt32BE(height, 4)
+  data.writeUInt8(bitDepth, 8)
+  data.writeUInt8(colorType, 9)
+  // compression 0 (deflate), filter 0, interlace 0 (progressive not written)
+  return data
+}
+
+function encode(width, height, rawRows, bitDepth, colorType) {
+  // rawRows already includes the per-scanline filter byte (0) where needed
+  const idat = deflateSync(rawRows, { level: 6 })
+  return Buffer.concat([
+    PNG_SIGNATURE,
+    chunk('IHDR', ihdr(width, height, bitDepth, colorType)),
+    chunk('IDAT', idat),
+    chunk('IEND', Buffer.alloc(0)),
+  ])
+}
+
+/** Encode 8-bit RGBA pixels (Buffer of width*height*4) as a PNG layer image. */
+export function encodePngRgba(width, height, pixels) {
+  if (!Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1) throw new Error(`invalid PNG dimensions ${width}x${height}`)
+  if (pixels.length !== width * height * 4) throw new Error(`pixel buffer is ${pixels.length} bytes, expected ${width * height * 4}`)
+  const stride = width * 4
+  const rows = Buffer.alloc((stride + 1) * height)
+  for (let y = 0; y < height; y++) {
+    rows[y * (stride + 1)] = 0
+    pixels.copy(rows, y * (stride + 1) + 1, y * stride, (y + 1) * stride)
+  }
+  return encode(width, height, rows, 8, 6)
+}
+
+/** Encode 8-bit grayscale pixels (Buffer of width*height) as a PNG mask. */
+export function encodePngGray(width, height, pixels) {
+  if (!Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1) throw new Error(`invalid PNG dimensions ${width}x${height}`)
+  if (pixels.length !== width * height) throw new Error(`pixel buffer is ${pixels.length} bytes, expected ${width * height}`)
+  const rows = Buffer.alloc((width + 1) * height)
+  for (let y = 0; y < height; y++) {
+    rows[y * (width + 1)] = 0
+    pixels.copy(rows, y * (width + 1) + 1, y * width, (y + 1) * width)
+  }
+  return encode(width, height, rows, 8, 0)
+}
+
+/** Decode the IHDR of a PNG buffer. Returns null when it is not a PNG. */
+export function readPngHeader(buffer) {
+  if (!Buffer.isBuffer(buffer) || buffer.length < 33 || !buffer.subarray(0, 8).equals(PNG_SIGNATURE)) return null
+  if (buffer.readUInt32BE(8) !== 13 || buffer.toString('ascii', 12, 16) !== 'IHDR') return null
+  return {
+    width: buffer.readUInt32BE(16),
+    height: buffer.readUInt32BE(20),
+    bitDepth: buffer.readUInt8(24),
+    colorType: buffer.readUInt8(25),
+    compression: buffer.readUInt8(26),
+    filter: buffer.readUInt8(27),
+    interlace: buffer.readUInt8(28),
+  }
+}
+
+export function isPngBuffer(buffer) {
+  return Buffer.isBuffer(buffer) && buffer.length >= 8 && buffer.subarray(0, 8).equals(PNG_SIGNATURE)
+}
+
+/** OpenEXR magic: 0x76 0x2f 0x31 0x01 followed by a version dword. */
+export function isExrBuffer(buffer) {
+  return Buffer.isBuffer(buffer) && buffer.length >= 8 && buffer[0] === 0x76 && buffer[1] === 0x2f && buffer[2] === 0x31 && buffer[3] === 0x01
+}
+
+export const PNG_COLOR_TYPES = { 0: 'grayscale', 2: 'truecolor', 3: 'palette', 4: 'grayscale+alpha', 6: 'truecolor+alpha' }
+
+export function describeImage(buffer, expected) {
+  if (isExrBuffer(buffer)) return { format: 'exr', note: 'OpenEXR (HDR) image' }
+  const header = readPngHeader(buffer)
+  if (!header) return { format: 'unknown', note: 'neither PNG nor EXR' }
+  const color = PNG_COLOR_TYPES[header.colorType] ?? `color type ${header.colorType}`
+  return {
+    format: 'png',
+    width: header.width,
+    height: header.height,
+    bitDepth: header.bitDepth,
+    colorType: header.colorType,
+    interlace: header.interlace,
+    note: `${header.bitDepth}-bit ${color}${header.interlace ? ' interlaced' : ''} PNG`,
+    ...(expected === 'mask' && (header.colorType !== 0 || header.bitDepth !== 8) ? { maskWarning: 'masks must be 8-bit grayscale' } : {}),
+  }
+}
+
+
+function clamp255(value) {
+  return value < 0 ? 0 : value > 255 ? 255 : Math.round(value)
+}
+
+function parseColor(input, fallback) {
+  if (Array.isArray(input)) {
+    const [r, g, b, a] = input
+    return {
+      r: clamp255(Number(r ?? fallback[0])),
+      g: clamp255(Number(g ?? fallback[1])),
+      b: clamp255(Number(b ?? fallback[2])),
+      a: clamp255(Number(a ?? 255)),
+    }
+  }
+  if (typeof input === 'number') return { r: clamp255(input), g: clamp255(input), b: clamp255(input), a: 255 }
+  if (typeof input === 'string') {
+    const hex = input.trim().replace(/^#/, '')
+    if (/^[0-9a-fA-F]{6}$/.test(hex) || /^[0-9a-fA-F]{8}$/.test(hex)) {
+      return {
+        r: parseInt(hex.slice(0, 2), 16),
+        g: parseInt(hex.slice(2, 4), 16),
+        b: parseInt(hex.slice(4, 6), 16),
+        a: hex.length === 8 ? parseInt(hex.slice(6, 8), 16) : 255,
+      }
+    }
+  }
+  return { r: fallback[0], g: fallback[1], b: fallback[2], a: 255 }
+}
+
+function lerp(a, b, t) {
+  return a + (b - a) * t
+}
+
+/**
+ * Generate a layer image or mask buffer. mode: 'solid' | 'linear' | 'radial'.
+ * For kind 'image' colors are [r,g,b,(a)] 0-255; for kind 'mask' from/to are
+ * gray levels 0-255 (white reveals, black hides).
+ */
+export function generatePixels({ width, height, mode = 'solid', color, from, to, angle = 90, center, radius }) {
+  if (!Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1) throw new Error('width and height must be positive integers')
+  if (width * height > 100_000_000) throw new Error('refusing to generate more than 100 million pixels')
+  const start = parseColor(from ?? color, [0, 0, 0])
+  const end = parseColor(to ?? color, [255, 255, 255])
+  const pixels = Buffer.alloc(width * height * 4)
+  // the gradient travels along (cos, sin) of `angle` in screen coordinates
+  // (y grows downward): 0° = left→right, 90° = top→bottom
+  const radians = ((Number(angle) || 0) * Math.PI) / 180
+  const dx = Math.cos(radians)
+  const dy = Math.sin(radians)
+  const extent = Math.abs((width / 2) * dx) + Math.abs((height / 2) * dy)
+  const span = 2 * extent || 1
+  const cx = Number(center?.[0]) || width / 2
+  const cy = Number(center?.[1]) || height / 2
+  const maxR = Number(radius) || Math.hypot(Math.max(cx, width - cx), Math.max(cy, height - cy))
+  let i = 0
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      let t = 0
+      if (mode === 'radial') t = Math.min(1, Math.max(0, Math.hypot(x + 0.5 - cx, y + 0.5 - cy) / maxR))
+      else if (mode === 'linear') {
+        const px = x + 0.5 - width / 2
+        const py = y + 0.5 - height / 2
+        t = Math.min(1, Math.max(0, (px * dx + py * dy + extent) / span))
+      }
+      pixels[i] = clamp255(lerp(start.r, end.r, t))
+      pixels[i + 1] = clamp255(lerp(start.g, end.g, t))
+      pixels[i + 2] = clamp255(lerp(start.b, end.b, t))
+      pixels[i + 3] = clamp255(lerp(start.a, end.a, t))
+      i += 4
+    }
+  }
+  return pixels
+}
+
+/** 8-bit grayscale variant used for masks (from/to are gray levels). */
+export function generateGrayPixels({ width, height, mode = 'solid', color, from, to, angle = 90, center, radius }) {
+  const rgba = generatePixels({ width, height, mode, color, from: from ?? color, to: to ?? color, angle, center, radius })
+  const gray = Buffer.alloc(width * height)
+  for (let p = 0, g = 0; p < rgba.length; p += 4, g++) gray[g] = rgba[p] // use the red channel
+  return gray
+}

package/.dsh-plugin/shared/comp-preview.mjs

@@ -0,0 +1,276 @@
+/**
+ * Best-effort flattened preview of a .comp project.
+ *
+ * Decodes layer images with sharp (an optional dependency — when it is not
+ * installed the tool reports that instead of failing) and composites the
+ * stack in JavaScript: transforms (origin/size/rotation/flips/sampling),
+ * opacity with folder pass-through, raster masks, unlinked maskPlacement,
+ * folder masks, clipping masks (maskSourceID) and all 24 blend modes.
+ * Adjustment layers and layer effects are NOT rendered — they are listed in
+ * `skipped` so nobody mistakes the preview for the app's output.
+ */
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { compositePixel } from './comp-blend.mjs'
+import { isExrBuffer } from './comp-png.mjs'
+
+const MAX_PLACED_PIXELS = 96_000_000
+
+async function loadSharp() {
+  try {
+    const module = await import('sharp')
+    return module.default ?? module
+  } catch {
+    return null
+  }
+}
+
+async function decodeRgba(sharp, buffer) {
+  // → { width, height, data: Buffer RGBA 8-bit } or null (unsupported)
+  const image = sharp(buffer, { failOn: 'none' }).ensureAlpha().toColourspace('srgb')
+  const { data, info } = await image.raw().toBuffer({ resolveWithObject: true })
+  if (info.channels === 4 && info.depth === 'uchar') return { width: info.width, height: info.height, data }
+  // normalize 16-bit or odd channel counts to 8-bit RGBA
+  const out = Buffer.alloc(info.width * info.height * 4)
+  const depthMax = info.depth === 'ushort' ? 65535 : 255
+  for (let p = 0, q = 0; p < info.width * info.height; p++, q += info.channels) {
+    out[p * 4] = Math.round((data[q] / depthMax) * 255)
+    out[p * 4 + 1] = Math.round((data[q + 1] / depthMax) * 255)
+    out[p * 4 + 2] = Math.round((data[q + 2] / depthMax) * 255)
+    out[p * 4 + 3] = Math.round(((data[q + 3] ?? 255) / depthMax) * 255)
+  }
+  return { width: info.width, height: info.height, data: out }
+}
+
+function bilinear(image, x, y) {
+  if (x < 0 || y < 0 || x >= image.width - 1 || y >= image.height - 1) {
+    const px = Math.min(image.width - 1, Math.max(0, Math.round(x)))
+    const py = Math.min(image.height - 1, Math.max(0, Math.round(y)))
+    const i = (py * image.width + px) * 4
+    return [image.data[i], image.data[i + 1], image.data[i + 2], image.data[i + 3]]
+  }
+  const x0 = Math.floor(x), y0 = Math.floor(y)
+  const fx = x - x0, fy = y - y0
+  const at = (px, py) => (py * image.width + px) * 4
+  const mix4 = (channel) => {
+    const top = image.data[at(x0, y0) + channel] * (1 - fx) + image.data[at(x0 + 1, y0) + channel] * fx
+    const bottom = image.data[at(x0, y0 + 1) + channel] * (1 - fx) + image.data[at(x0 + 1, y0 + 1) + channel] * fx
+    return top * (1 - fy) + bottom * fy
+  }
+  return [mix4(0), mix4(1), mix4(2), mix4(3)]
+}
+
+function rotatedBounds(transform) {
+  const [ox, oy] = transform.origin ?? [0, 0]
+  const [w, h] = transform.size
+  const theta = ((transform.rotation ?? 0) * Math.PI) / 180
+  const cx = ox + w / 2, cy = oy + h / 2
+  const cos = Math.abs(Math.cos(theta)), sin = Math.abs(Math.sin(theta))
+  const bw = w * cos + h * sin, bh = w * sin + h * cos
+  return { x0: Math.floor(cx - bw / 2), y0: Math.floor(cy - bh / 2), x1: Math.ceil(cx + bw / 2), y1: Math.ceil(cy + bh / 2) }
+}
+
+/**
+ * Sample a mask (grayscale PNG decoded to RGBA; red channel used) at
+ * document coordinates through an optional document-space rectangle.
+ */
+function sampleMask(maskImage, docX, docY, placement) {
+  let u = docX, v = docY
+  if (placement) {
+    const [px, py, pw, ph] = placement
+    u = (docX - px) / (pw || 1)
+    v = (docY - py) / (ph || 1)
+  } else {
+    // linked mask: reuse the caller's layer UV
+    return null
+  }
+  if (u < 0 || v < 0 || u >= 1 || v >= 1) return 0
+  const [r] = bilinear(maskImage, u * (maskImage.width - 1), v * (maskImage.height - 1))
+  return r
+}
+
+/**
+ * Render the flattened stack. manifest/target from resolveCompPath + read.
+ * Returns { ok, png: Buffer, width, height, skipped: [...], warnings: [...] }
+ * or { ok: false, reason }.
+ */
+export async function renderPreview(target, manifest, { maxWidth = 1600, onlyLayerIds = null, signal } = {}) {
+  const sharp = await loadSharp()
+  if (!sharp) return { ok: false, reason: 'sharp is not installed in this profile; the preview needs it for PNG decode/encode (pnpm add sharp in the profile, or install the plugin with its optionalDependencies)' }
+  const canvasW = manifest.width, canvasH = manifest.height
+  if (!Number.isInteger(canvasW) || !Number.isInteger(canvasH) || canvasW <= 0 || canvasH <= 0) return { ok: false, reason: 'manifest.width/height are not usable' }
+  const layers = Array.isArray(manifest.layers) ? manifest.layers : []
+  const byId = new Map(layers.filter(layer => layer?.id).map(layer => [layer.id, layer]))
+  const ancestors = id => {
+    const chain = []
+    let cursor = byId.get(id)
+    const seen = new Set([id])
+    while (cursor?.parentID && !seen.has(cursor.parentID)) { seen.add(cursor.parentID); chain.push(byId.get(cursor.parentID)); cursor = byId.get(cursor.parentID) }
+    return chain.filter(Boolean)
+  }
+  const isVisible = layer => {
+    if (layer?.isVisible === false) return false
+    return ancestors(layer.id).every(group => group.isVisible !== false)
+  }
+  const groupOpacity = layer => ancestors(layer.id).reduce((product, group) => product * (typeof group.opacity === 'number' ? group.opacity : 1), 1)
+
+  const warnings = []
+  const skipped = []
+  const imageCache = new Map()
+  const alphaFieldCache = new Map()
+  let placedPixels = 0
+
+  const loadImage = async layer => {
+    if (!layer?.imageFile) return null
+    if (imageCache.has(layer.id)) return imageCache.get(layer.id)
+    let entry = null
+    try {
+      const buffer = await readFile(join(target.imagesDir, layer.imageFile))
+      if (isExrBuffer(buffer)) { skipped.push(`adjustment/EXR layer "${layer.name ?? layer.id}" image not decoded (EXR needs the app)`); entry = { unsupported: true } }
+      else {
+        const decoded = await decodeRgba(sharp, buffer)
+        entry = decoded
+        placedPixels += decoded.width * decoded.height
+      }
+    } catch (error) {
+      warnings.push(`cannot decode ${layer.imageFile}: ${error.message}`)
+      entry = { unsupported: true }
+    }
+    imageCache.set(layer.id, entry)
+    return entry
+  }
+
+  const loadMask = async layer => {
+    if (!layer?.maskFile || layer.maskEnabled === false) return null
+    if (imageCache.has(`mask:${layer.id}`)) return imageCache.get(`mask:${layer.id}`)
+    let entry = null
+    try {
+      entry = await decodeRgba(sharp, await readFile(join(target.imagesDir, layer.maskFile)))
+      placedPixels += entry.width * entry.height
+    } catch (error) {
+      warnings.push(`cannot decode mask ${layer.maskFile}: ${error.message}`)
+      entry = null
+    }
+    imageCache.set(`mask:${layer.id}`, entry)
+    return entry
+  }
+
+  /** Alpha field (coverage) of a layer in document space, for clipping. */
+  const alphaField = async layer => {
+    if (alphaFieldCache.has(layer.id)) return alphaFieldCache.get(layer.id)
+    const field = new Uint8Array(canvasW * canvasH)
+    const image = await loadImage(layer)
+    const mask = await loadMask(layer)
+    if (image && !image.unsupported && layer.transform?.size) {
+      const transform = layer.transform
+      const bounds = rotatedBounds(transform)
+      const theta = ((transform.rotation ?? 0) * Math.PI) / 180
+      const cos = Math.cos(theta), sin = Math.sin(theta)
+      const [ox, oy] = transform.origin ?? [0, 0]
+      const [sw, sh] = transform.size
+      const opacity = (typeof layer.opacity === 'number' ? layer.opacity : 1)
+      for (let y = Math.max(0, bounds.y0); y < Math.min(canvasH, bounds.y1); y++) {
+        for (let x = Math.max(0, bounds.x0); x < Math.min(canvasW, bounds.x1); x++) {
+          const lx = x + 0.5 - ox - sw / 2, ly = y + 0.5 - oy - sh / 2
+          const rx = lx * cos + ly * sin, ry = -lx * sin + ly * cos
+          let u = (rx + sw / 2) / sw, v = (ry + sh / 2) / sh
+          if (transform.flipX) u = 1 - u
+          if (transform.flipY) v = 1 - v
+          if (u < 0 || v < 0 || u >= 1 || v >= 1) continue
+          let coverage = bilinear(image, u * (image.width - 1), v * (image.height - 1))[3] / 255
+          coverage *= opacity
+          if (mask && layer.maskLinked !== false) coverage *= bilinear(mask, u * (mask.width - 1), v * (mask.height - 1))[0] / 255
+          else if (mask && layer.maskPlacement) coverage *= sampleMask(mask, x + 0.5, y + 0.5, layer.maskPlacement) / 255
+          field[y * canvasW + x] = Math.round(Math.min(1, Math.max(0, coverage)) * 255)
+        }
+      }
+    }
+    // clipping chain: the source's own maskSourceID contributes too
+    if (layer.maskSourceID && byId.has(layer.maskSourceID)) {
+      const upstream = await alphaField(byId.get(layer.maskSourceID))
+      for (let p = 0; p < field.length; p++) field[p] = Math.round((field[p] / 255) * (upstream[p] / 255) * 255)
+    }
+    alphaFieldCache.set(layer.id, field)
+    return field
+  }
+
+  const canvas = Buffer.alloc(canvasW * canvasH * 4)
+  const groupMasks = new Map()
+  const loadGroupMask = async group => {
+    if (!group.maskFile || group.maskEnabled === false) return null
+    if (groupMasks.has(group.id)) return groupMasks.get(group.id)
+    let entry = null
+    try {
+      entry = { image: await decodeRgba(sharp, await readFile(join(target.imagesDir, group.maskFile))), placement: group.transform?.size ? group.transform.origin ?? [0, 0] : [0, 0], size: group.transform?.size ?? [canvasW, canvasH] }
+    } catch (error) { warnings.push(`cannot decode group mask ${group.maskFile}: ${error.message}`) }
+    groupMasks.set(group.id, entry)
+    return entry
+  }
+
+  for (const layer of layers) {
+    if (signal?.aborted) return { ok: false, reason: 'aborted' }
+    if (onlyLayerIds && !onlyLayerIds.includes(layer.id)) continue
+    if (layer.adjustment) { skipped.push(`adjustment layer "${layer.name ?? layer.id}" (${layer.adjustment.kind}) not rendered`); continue }
+    if (layer.isGroup === true) continue // folders contribute opacity/masks via their children
+    if (layer.effects && Object.keys(layer.effects).length) skipped.push(`layer effects on "${layer.name ?? layer.id}" not rendered`)
+    if (!isVisible(layer)) continue
+    const image = await loadImage(layer)
+    if (!image) continue // blank layer
+    if (image.unsupported) continue
+    const transform = layer.transform
+    if (!transform?.size) { warnings.push(`layer "${layer.name ?? layer.id}" has no usable transform; skipped`); continue }
+    if (placedPixels > MAX_PLACED_PIXELS) { warnings.push('pixel budget reached; remaining layers skipped'); break }
+
+    const bounds = rotatedBounds(transform)
+    const theta = ((transform.rotation ?? 0) * Math.PI) / 180
+    const cos = Math.cos(theta), sin = Math.sin(theta)
+    const [ox, oy] = transform.origin ?? [0, 0]
+    const [sw, sh] = transform.size
+    const opacity = (typeof layer.opacity === 'number' ? layer.opacity : 1) * groupOpacity(layer)
+    const blendMode = layer.blendMode ?? 'Normal'
+    const mask = await loadMask(layer)
+    const ancestorMasks = []
+    for (const group of ancestors(layer.id)) {
+      const groupMask = await loadGroupMask(group)
+      if (groupMask) ancestorMasks.push(groupMask)
+    }
+    let clipField = null
+    if (layer.maskSourceID && byId.has(layer.maskSourceID)) clipField = await alphaField(byId.get(layer.maskSourceID))
+
+    for (let y = Math.max(0, bounds.y0); y < Math.min(canvasH, bounds.y1); y++) {
+      for (let x = Math.max(0, bounds.x0); x < Math.min(canvasW, bounds.x1); x++) {
+        const lx = x + 0.5 - ox - sw / 2, ly = y + 0.5 - oy - sh / 2
+        const rx = lx * cos + ly * sin, ry = -lx * sin + ly * cos
+        let u = (rx + sw / 2) / sw, v = (ry + sh / 2) / sh
+        if (u < 0 || v < 0 || u >= 1 || v >= 1) continue
+        if (transform.flipX) u = 1 - u
+        if (transform.flipY) v = 1 - v
+        const nearest = transform.sampling === 'Nearest'
+        const px = nearest ? Math.min(image.width - 1, Math.max(0, Math.round(u * (image.width - 1)))) : u * (image.width - 1)
+        const py = nearest ? Math.min(image.height - 1, Math.max(0, Math.round(v * (image.height - 1)))) : v * (image.height - 1)
+        const rgba = bilinear(image, px, py)
+        if (rgba[3] <= 0) continue
+        let coverage = opacity
+        if (mask && layer.maskLinked !== false) coverage *= bilinear(mask, u * (mask.width - 1), v * (mask.height - 1))[0] / 255
+        else if (mask && layer.maskPlacement) coverage *= sampleMask(mask, x + 0.5, y + 0.5, layer.maskPlacement) / 255
+        for (const groupMask of ancestorMasks) {
+          const [gx, gy, gw, gh] = [groupMask.placement[0], groupMask.placement[1], groupMask.size[0], groupMask.size[1]]
+          coverage *= sampleMask(groupMask.image, x + 0.5, y + 0.5, [gx, gy, gw, gh]) / 255
+        }
+        if (clipField) coverage *= clipField[y * canvasW + x] / 255
+        if (coverage <= 0) continue
+        // compositePixel applies the source pixel's own alpha to `coverage`
+        scratch[0] = Math.round(rgba[0]); scratch[1] = Math.round(rgba[1]); scratch[2] = Math.round(rgba[2]); scratch[3] = Math.round(rgba[3])
+        compositePixel(canvas, (y * canvasW + x) * 4, scratch, 0, blendMode, Math.min(1, coverage))
+      }
+    }
+  }
+
+  let png = sharp(canvas, { raw: { width: canvasW, height: canvasH, channels: 4 } })
+  if (maxWidth && canvasW > maxWidth) png = png.resize({ width: maxWidth })
+  const output = await png.png().toBuffer()
+  const meta = await sharp(output).metadata()
+  return { ok: true, png: output, width: meta.width, height: meta.height, canvas: [canvasW, canvasH], skipped, warnings }
+}
+
+const scratch = Buffer.alloc(4)

package/.dsh-plugin/shared/comp-project.mjs

@@ -0,0 +1,152 @@
+/**
+ * Reading, atomically writing and cleaning .comp packages.
+ *
+ * The write path follows the rule the Compositor docs prescribe for editing
+ * a project while it is open: PNGs land in images/ first (the agent's job),
+ * then the manifest is written to a temporary file inside the package and
+ * renamed over manifest.json — a rename is atomic, so the open app only ever
+ * sees a complete manifest.
+ */
+import { randomUUID } from 'node:crypto'
+import { mkdir, readdir, readFile, rename, rm, writeFile, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+import { resolveCompPath } from './comp-paths.mjs'
+
+const MANIFEST_READ_LIMIT = 128 * 1024
+
+export { resolveCompPath }
+
+export function newLayerId() {
+  return randomUUID().toUpperCase()
+}
+
+export async function readManifest(target) {
+  const text = await readFile(target.manifestPath, 'utf8')
+  return { manifest: JSON.parse(text), text, bytes: Buffer.byteLength(text) }
+}
+
+function layerOneLiner(layer, index) {
+  const bits = [`#${index}`]
+  if (layer.isGroup === true) bits.push('group')
+  if (layer.adjustment) bits.push(`adjustment:${layer.adjustment.kind ?? '?'}`)
+  if (layer.text) bits.push('text')
+  bits.push(layer.name ?? layer.id)
+  if (layer.isVisible === false) bits.push('hidden')
+  if (typeof layer.opacity === 'number' && layer.opacity !== 1) bits.push(`opacity ${layer.opacity}`)
+  if (layer.blendMode && layer.blendMode !== 'Normal') bits.push(layer.blendMode)
+  if (layer.parentID) bits.push(`in ${layer.parentID}`)
+  if (layer.maskFile) bits.push('masked')
+  if (layer.maskSourceID) bits.push(`clips ${layer.maskSourceID}`)
+  const transform = layer.transform
+  if (transform?.size) bits.push(`at ${transform.origin ?? [0, 0]} size ${transform.size}`)
+  if (layer.imageFile) bits.push(layer.imageFile)
+  return bits.join(' | ')
+}
+
+/** Summarize a manifest for token-efficient reading; full only when small. */
+export function summarizeManifest(manifest, text, { layerIndex = null } = {}) {
+  const layers = Array.isArray(manifest.layers) ? manifest.layers : []
+  if (layerIndex !== null) {
+    const layer = layers[layerIndex]
+    return { layer: layer ?? null, layerCount: layers.length }
+  }
+  const full = text.length <= MANIFEST_READ_LIMIT
+  return {
+    canvas: { width: manifest.width, height: manifest.height, resolution: manifest.resolution, colorSpace: manifest.colorSpace },
+    version: manifest.version,
+    documentID: manifest.documentID,
+    activeLayerID: manifest.activeLayerID ?? null,
+    layerCount: layers.length,
+    guides: Array.isArray(manifest.guides) ? manifest.guides.length : 0,
+    stack: 'bottom to top — layers[0] paints first, the last layer paints on top',
+    layerLines: layers.map((layer, index) => layerOneLiner(layer, index)),
+    ...(full ? { manifest } : { note: `manifest is ${text.length} bytes; ask with layerIndex for one layer's full record` }),
+  }
+}
+
+/**
+ * Fill in what an agent usually forgets, without changing intent:
+ * missing layer ids get fresh UUIDs; imageFile/maskFile are normalized to
+ * `<id>.png` / `<id>.mask.png`; a few top-level defaults are added when absent.
+ * Returns { manifest, fixes: [...] }.
+ */
+export function autoFixManifest(manifest, { fixIds = true, fixFilenames = true, defaultVersion = 11 } = {}) {
+  const fixes = []
+  const out = structuredClone(manifest)
+  if (out.format === undefined) { out.format = 'com.compositor.project'; fixes.push('set format = "com.compositor.project"') }
+  if (out.version === undefined) { out.version = defaultVersion; fixes.push(`set version = ${defaultVersion} (newest conservative version; raise it only for 16-bit/EXR layers)`) }
+  if (out.colorSpace === undefined) { out.colorSpace = 'sRGB'; fixes.push('set colorSpace = "sRGB"') }
+  if (out.resolution === undefined) { out.resolution = 72; fixes.push('set resolution = 72') }
+  if (!Array.isArray(out.layers)) out.layers = []
+  for (const layer of out.layers) {
+    if (!layer || typeof layer !== 'object') continue
+    if (fixIds && !layer.id) {
+      layer.id = newLayerId()
+      fixes.push(`gave layer "${layer.name ?? '(unnamed)'}" the id ${layer.id}`)
+    }
+    if (!layer.id) continue
+    if (fixFilenames && layer.imageFile !== undefined && layer.imageFile !== `${layer.id}.png` && layer.imageFile !== `${layer.id}.exr`) {
+      const extension = /\.(png|exr)$/i.exec(layer.imageFile)?.[1]?.toLowerCase() ?? 'png'
+      fixes.push(`layers "${layer.name ?? layer.id}": imageFile "${layer.imageFile}" → "${layer.id}.${extension}" — image files must be named after their layer id`)
+      layer.imageFile = `${layer.id}.${extension}`
+    }
+    if (fixFilenames && layer.maskFile !== undefined && layer.maskFile !== `${layer.id}.mask.png`) {
+      fixes.push(`layer "${layer.name ?? layer.id}": maskFile "${layer.maskFile}" → "${layer.id}.mask.png"`)
+      layer.maskFile = `${layer.id}.mask.png`
+    }
+  }
+  if (out.activeLayerID === undefined && out.layers.length) {
+    out.activeLayerID = out.layers[out.layers.length - 1]?.id ?? null
+    if (out.activeLayerID) fixes.push(`set activeLayerID = ${out.activeLayerID} (top layer)`)
+  }
+  return { manifest: out, fixes }
+}
+
+/**
+ * Write the manifest atomically: temp file inside the package, then rename.
+ * `docs`-validated manifests only — pass skipValidation to override.
+ */
+export async function writeManifestAtomic(target, manifest, { validate, tempPrefix = '.manifest' } = {}) {
+  const text = JSON.stringify(manifest, null, 2) + '\n'
+  const tempPath = join(target.compDir, `${tempPrefix}.json.tmp-${process.pid}-${Date.now()}`)
+  await mkdir(target.imagesDir, { recursive: true })
+  await writeFile(tempPath, text, 'utf8')
+  // prove the round-trip parses before swapping it in
+  JSON.parse(await readFile(tempPath, 'utf8'))
+  await rename(tempPath, target.manifestPath)
+  return { manifestPath: target.manifestPath, bytes: Buffer.byteLength(text) }
+}
+
+/**
+ * Remove what the project no longer needs: image files in images/ the
+ * manifest does not reference, and the QuickLook folder (the docs ask for
+ * this after every change so Finder does not preview a stale picture).
+ */
+export async function cleanPackage(target, manifest, { apply = false } = {}) {
+  const referenced = new Set()
+  for (const layer of Array.isArray(manifest.layers) ? manifest.layers : []) {
+    if (typeof layer?.imageFile === 'string') referenced.add(layer.imageFile)
+    if (typeof layer?.maskFile === 'string') referenced.add(layer.maskFile)
+  }
+  const unusedImages = []
+  const entries = await readdir(target.imagesDir).catch(() => [])
+  for (const name of entries) {
+    if (referenced.has(name) || !/\.(png|exr)$/i.test(name)) continue
+    const fileStat = await stat(join(target.imagesDir, name)).catch(() => null)
+    if (fileStat?.isFile()) unusedImages.push({ name, bytes: fileStat.size })
+  }
+  const quickLook = await stat(join(target.compDir, 'QuickLook')).catch(() => null)
+  const hasQuickLook = quickLook?.isDirectory() === true
+  const result = { unusedImages, quickLook: hasQuickLook, applied: apply, removed: [] }
+  if (apply) {
+    for (const image of unusedImages) {
+      await rm(join(target.imagesDir, image.name), { force: true })
+      result.removed.push(`images/${image.name}`)
+    }
+    if (hasQuickLook) {
+      await rm(join(target.compDir, 'QuickLook'), { recursive: true, force: true })
+      result.removed.push('QuickLook/')
+    }
+  }
+  return result
+}