@goodandready/dsh-image-gen 0.11.25 → 0.11.27

package/lib/frontend-assets.js

@@ -1,3 +1,4 @@
+import sharp from 'sharp'
 // @ts-check
 import path from 'node:path'
 import fs from 'node:fs/promises'
@@ -64,13 +65,12 @@ export function getContrastRatio(hex1, hex2) {
 }
 
 /**
- * Extract palette sample colors from raw image bytes.
- * Scans byte frequencies and samples color anchors across buffer.
- * @param {Buffer} buffer
- * @returns {string[]} Hex colors
+ * Extract dominant palette colors from decoded image pixels with alpha awareness (#372).
+ * @param {Buffer|Uint8Array} buffer
+ * @returns {Promise<string[]>} Hex colors
  */
-export function extractSampleColorsFromBuffer(buffer) {
-  if (!buffer || buffer.length < 16) {
+export async function extractSampleColorsFromBuffer(buffer) {
+  if (!buffer || buffer.length < 8) {
     return ['#0f172a', '#3b82f6', '#10b981', '#f59e0b', '#ef4444', '#f8fafc']
   }
 
@@ -95,42 +95,80 @@ export function extractSampleColorsFromBuffer(buffer) {
     }
   }
 
-  // Sample bytes from buffer chunks
-  const step = Math.max(4, Math.floor(buffer.length / 500))
-  const samples = []
-  for (let i = 64; i < buffer.length - 8; i += step) {
-    const r = buffer[i]
-    const g = buffer[i + 1]
-    const b = buffer[i + 2]
-    samples.push({ r, g, b })
-  }
-
-  if (samples.length === 0) {
-    return ['#0f172a', '#3b82f6', '#10b981', '#f59e0b', '#ef4444', '#f8fafc']
-  }
+  // Decode raster container to raw RGBA pixels via Sharp
+  try {
+    const { data, info } = await sharp(buffer)
+      .raw()
+      .ensureAlpha()
+      .toBuffer({ resolveWithObject: true })
+
+    const totalPixels = info.width * info.height
+    const step = Math.max(1, Math.floor(totalPixels / 2048))
+    const colorBuckets = new Map()
+
+    for (let i = 0; i < totalPixels; i += step) {
+      const off = i * 4
+      const r = data[off]
+      const g = data[off + 1]
+      const b = data[off + 2]
+      const a = data[off + 3]
+
+      // Ignore fully or mostly transparent pixels
+      if (a < 128) continue
+
+      // Quantize to 16-level RGB bins to cluster nearby nuances
+      const qr = Math.round(r / 16) * 16
+      const qg = Math.round(g / 16) * 16
+      const qb = Math.round(b / 16) * 16
+      const key = `${qr},${qg},${qb}`
+
+      let bucket = colorBuckets.get(key)
+      if (!bucket) {
+        bucket = { count: 0, rSum: 0, gSum: 0, bSum: 0 }
+        colorBuckets.set(key, bucket)
+      }
+      bucket.count++
+      bucket.rSum += r
+      bucket.gSum += g
+      bucket.bSum += b
+    }
 
-  samples.sort((a, b) => (a.r * 299 + a.g * 587 + a.b * 114) - (b.r * 299 + b.g * 587 + b.b * 114))
-
-  const anchors = []
-  const bucketSize = Math.floor(samples.length / 6)
-  for (let b = 0; b < 6; b++) {
-    const start = b * bucketSize
-    const end = b === 5 ? samples.length : start + bucketSize
-    let sumR = 0, sumG = 0, sumB = 0
-    for (let j = start; j < end; j++) {
-      sumR += samples[j].r
-      sumG += samples[j].g
-      sumB += samples[j].b
+    if (colorBuckets.size > 0) {
+      const sorted = Array.from(colorBuckets.values()).sort((a, b) => b.count - a.count)
+      const dominant = sorted.slice(0, 6).map((b) => {
+        return rgbToHex(b.rSum / b.count, b.gSum / b.count, b.bSum / b.count)
+      })
+
+      const result = [...dominant]
+      if (result.length < 5) {
+        const primaryRgb = hexToRgb(result[0])
+        const isNearBlack = primaryRgb.r === 0 && primaryRgb.g === 0 && primaryRgb.b === 0
+        if (isNearBlack) {
+          const darkShades = ['#1a1a1a', '#333333', '#4d4d4d', '#666666', '#808080']
+          for (const s of darkShades) {
+            if (result.length >= 6) break
+            if (!result.includes(s)) result.push(s)
+          }
+        } else {
+          const factors = [0.2, 0.4, 0.6, 0.8, 1.2, 1.4]
+          for (const factor of factors) {
+            if (result.length >= 6) break
+            const shade = rgbToHex(
+              Math.min(255, Math.round(primaryRgb.r * factor)),
+              Math.min(255, Math.round(primaryRgb.g * factor)),
+              Math.min(255, Math.round(primaryRgb.b * factor)),
+            )
+            if (!result.includes(shade)) result.push(shade)
+          }
+        }
+      }
+      return result.slice(0, 6)
     }
-    const count = Math.max(1, end - start)
-    anchors.push(rgbToHex(sumR / count, sumG / count, sumB / count))
+  } catch (_err) {
+    // If sharp cannot decode or buffer is non-image, fallback
   }
 
-  const unique = Array.from(new Set(anchors))
-  while (unique.length < 5) {
-    unique.push('#3b82f6')
-  }
-  return unique
+  return ['#0f172a', '#3b82f6', '#10b981', '#f59e0b', '#ef4444', '#f8fafc']
 }
 
 /**
@@ -394,9 +432,57 @@ export const ${componentName}: React.FC<${componentName}Props> = ({ size = 24, c
   }
 }
 
+export function buildIcoBuffer(pngFrames) {
+  const count = pngFrames.length
+  const headerLen = 6 + count * 16
+  let currentOffset = headerLen
+
+  const entries = []
+  for (const item of pngFrames) {
+    entries.push({
+      width: item.width >= 256 ? 0 : item.width,
+      height: item.height >= 256 ? 0 : item.height,
+      size: item.buffer.length,
+      offset: currentOffset,
+      buffer: item.buffer,
+    })
+    currentOffset += item.buffer.length
+  }
+
+  const out = Buffer.alloc(currentOffset)
+  // Header: reserved 0, type 1 (icon), count
+  out.writeUInt16LE(0, 0)
+  out.writeUInt16LE(1, 2)
+  out.writeUInt16LE(count, 4)
+
+  let entryPos = 6
+  for (const entry of entries) {
+    out.writeUInt8(entry.width, entryPos)
+    out.writeUInt8(entry.height, entryPos + 1)
+    out.writeUInt8(0, entryPos + 2) // color count
+    out.writeUInt8(0, entryPos + 3) // reserved
+    out.writeUInt16LE(1, entryPos + 4) // planes
+    out.writeUInt16LE(32, entryPos + 6) // bpp
+    out.writeUInt32LE(entry.size, entryPos + 8) // size
+    out.writeUInt32LE(entry.offset, entryPos + 12) // offset
+    entry.buffer.copy(out, entry.offset)
+    entryPos += 16
+  }
+  return out
+}
+
+async function getDefaultIconBytes(name, themeColor) {
+  const initial = (name || 'A').trim().charAt(0).toUpperCase() || 'A'
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 512 512">
+    <rect width="512" height="512" rx="100" fill="${themeColor || '#0f172a'}"/>
+    <text x="50%" y="54%" font-family="system-ui, -apple-system, sans-serif" font-size="280" font-weight="bold" fill="#ffffff" dominant-baseline="middle" text-anchor="middle">${initial}</text>
+  </svg>`
+  return sharp(Buffer.from(svg)).png().toBuffer()
+}
+
 /**
- * Issue #190: generate_pwa_icon_suite
- * Generates standard PWA icon suite metadata, web app manifest.json, and icon configuration.
+ * Issue #190 & #387: generate_pwa_icon_suite
+ * Generates standard PWA icon suite, web app manifest.json, multi-resolution favicon.ico, and HTML snippet.
  */
 export async function generatePwaIconSuite({
   name = 'App',
@@ -405,7 +491,20 @@ export async function generatePwaIconSuite({
   backgroundColor = '#ffffff',
   iconsDir = 'icons',
   sourcePath = null,
+  imageBytes = null,
+  outDir = null,
 } = {}) {
+  // 1. Resolve source image buffer
+  let source = imageBytes
+  if (!source && sourcePath) {
+    try {
+      source = await fs.readFile(sourcePath)
+    } catch (_err) { source = null }
+  }
+  if (!source) {
+    source = await getDefaultIconBytes(name, themeColor)
+  }
+
   const iconSizes = [
     { size: 16, rel: 'icon', filename: `${iconsDir}/favicon-16x16.png`, purpose: 'any' },
     { size: 32, rel: 'icon', filename: `${iconsDir}/favicon-32x32.png`, purpose: 'any' },
@@ -416,6 +515,53 @@ export async function generatePwaIconSuite({
     { size: 512, rel: 'manifest', filename: `${iconsDir}/icon-512x512-maskable.png`, purpose: 'maskable' },
   ]
 
+  // 2. Render all PNG icons via Sharp
+  const generatedIcons = []
+  const icoFrames = []
+
+  for (const item of iconSizes) {
+    let pngBuf
+    if (item.purpose === 'maskable') {
+      // Safe zone requires 10% padding on each side -> inner icon is 80% of canvas (#387)
+      const innerSize = Math.max(1, Math.round(item.size * 0.8))
+      const inner = await sharp(source)
+        .resize(innerSize, innerSize, { fit: 'contain', background: { r: 0, g: 0, b: 0, alpha: 0 } })
+        .png()
+        .toBuffer()
+
+      pngBuf = await sharp({
+        create: {
+          width: item.size,
+          height: item.size,
+          channels: 4,
+          background: backgroundColor || '#ffffff',
+        },
+      })
+        .composite([{ input: inner, gravity: 'center' }])
+        .png()
+        .toBuffer()
+    } else {
+      pngBuf = await sharp(source)
+        .resize(item.size, item.size, { fit: 'contain', background: { r: 0, g: 0, b: 0, alpha: 0 } })
+        .png()
+        .toBuffer()
+    }
+
+    generatedIcons.push({
+      ...item,
+      bytes: pngBuf,
+    })
+
+    if ([16, 32, 48].includes(item.size) && item.rel === 'icon') {
+      icoFrames.push({ width: item.size, height: item.size, buffer: pngBuf })
+    }
+  }
+
+  // 3. Multi-resolution favicon.ico containing 16, 32, 48 px PNG frames (#387)
+  const faviconIcoBuffer = buildIcoBuffer(icoFrames)
+  const faviconIcoFilename = `${iconsDir}/favicon.ico`
+
+  // 4. Manifest JSON
   const manifest = {
     name,
     short_name: shortName,
@@ -423,7 +569,7 @@ export async function generatePwaIconSuite({
     display: 'standalone',
     background_color: backgroundColor,
     theme_color: themeColor,
-    icons: iconSizes
+    icons: generatedIcons
       .filter((i) => i.rel === 'manifest')
       .map((i) => ({
         src: i.filename,
@@ -432,8 +578,11 @@ export async function generatePwaIconSuite({
         purpose: i.purpose,
       })),
   }
+  const manifestJson = JSON.stringify(manifest, null, 2)
 
+  // 5. HTML snippet
   const htmlHeadSnippet = [
+    `<link rel="icon" href="/${faviconIcoFilename}" sizes="any">`,
     `<link rel="icon" type="image/png" sizes="16x16" href="/${iconsDir}/favicon-16x16.png">`,
     `<link rel="icon" type="image/png" sizes="32x32" href="/${iconsDir}/favicon-32x32.png">`,
     `<link rel="apple-touch-icon" sizes="180x180" href="/${iconsDir}/apple-touch-icon.png">`,
@@ -441,13 +590,39 @@ export async function generatePwaIconSuite({
     `<meta name="theme-color" content="${themeColor}">`,
   ].join('\n')
 
+  // 6. Write files to outDir if provided
+  const exportedFiles = []
+  if (outDir) {
+    const fullIconsDir = path.resolve(outDir, iconsDir)
+    await fs.mkdir(fullIconsDir, { recursive: true })
+
+    for (const item of generatedIcons) {
+      const filePath = path.resolve(outDir, item.filename)
+      await fs.writeFile(filePath, item.bytes)
+      exportedFiles.push(filePath)
+    }
+
+    const icoPath = path.resolve(outDir, faviconIcoFilename)
+    await fs.writeFile(icoPath, faviconIcoBuffer)
+    exportedFiles.push(icoPath)
+
+    const manifestPath = path.resolve(outDir, 'manifest.json')
+    await fs.writeFile(manifestPath, manifestJson)
+    exportedFiles.push(manifestPath)
+  }
+
+  // Strip internal bytes property from public icons list to avoid huge JSON serialization
+  const cleanIcons = generatedIcons.map(({ bytes, ...rest }) => rest)
+
   return {
     name,
     shortName,
     themeColor,
     backgroundColor,
-    icons: iconSizes,
-    manifestJson: JSON.stringify(manifest, null, 2),
+    icons: cleanIcons,
+    faviconIco: faviconIcoFilename,
+    manifestJson,
     htmlHeadSnippet,
+    exportedFiles,
   }
 }

package/lib/index.js

@@ -44,6 +44,7 @@ import { registerImageCommand } from './commands.js'
 import { registerAllTools } from './register-tools.js'
 import { registerPluginUpdater } from './updater.js'
 import { registerVaultRoutes } from './vault.js'
+import { registerLiveProgressRoutes } from './live-progress.js'
 import { registerSettingsRoutes } from './settings-route.js'
 import { clearAllAnchors } from './anchor-helpers.js'
 import { resetLoopGuard, getLoopGuardState } from './loop-guard.js'
@@ -418,6 +419,9 @@ export function apply(ctx, rawConfig) {
   // Vault route (#159)
   registerVaultRoutes(ctx)
 
+  // Live events route (#379)
+  registerLiveProgressRoutes(ctx)
+
   // Reset loop guard when user sends a new message (#370)
   if (typeof ctx.on === 'function') {
     ctx.on('chat/message', (session) => {

package/lib/live-progress.js

@@ -0,0 +1,278 @@
+// lib/live-progress.js — Live progress event hub & presentation transport (#147, #329, #379)
+
+import { isTrustedLocalRequest } from './security.js'
+
+const activeSessions = new Map()
+
+/**
+ * Creates or resets a live progress session for a tool call.
+ *
+ * @param {string} callId
+ * @param {{ signal?: AbortSignal, onProgress?: Function }} [options]
+ * @returns {object}
+ */
+export function createLiveProgressSession(callId, options = {}) {
+  if (!callId) return null
+  const existing = activeSessions.get(callId)
+  if (existing) {
+    existing.listeners.clear()
+  }
+
+  const session = {
+    callId,
+    stage: 'Starting...',
+    step: undefined,
+    progress: undefined,
+    draftUrl: undefined,
+    done: false,
+    error: undefined,
+    timestamp: Date.now(),
+    listeners: new Set(),
+  }
+
+  if (options.signal) {
+    options.signal.addEventListener(
+      'abort',
+      () => {
+        abortLiveProgress(callId, 'Execution aborted')
+      },
+      { once: true },
+    )
+  }
+
+  activeSessions.set(callId, session)
+  return session
+}
+
+/**
+ * Publishes an incremental update to a live progress session.
+ *
+ * @param {string} callId
+ * @param {{ stage?: string, step?: string, progress?: number, draftUrl?: string }} update
+ */
+export function publishLiveProgress(callId, update = {}) {
+  if (!callId) return
+  let session = activeSessions.get(callId)
+  if (!session) {
+    session = createLiveProgressSession(callId)
+  }
+  if (session.done) return
+
+  if (update.stage !== undefined) session.stage = update.stage
+  if (update.step !== undefined) session.step = update.step
+  if (update.progress !== undefined) {
+    session.progress = typeof update.progress === 'number'
+      ? Math.min(100, Math.max(0, Math.round(update.progress)))
+      : undefined
+  }
+  if (update.draftUrl !== undefined) session.draftUrl = update.draftUrl
+  session.timestamp = Date.now()
+
+  const payload = {
+    callId,
+    stage: session.stage,
+    step: session.step,
+    progress: session.progress,
+    draftUrl: session.draftUrl,
+    done: false,
+  }
+
+  for (const listener of session.listeners) {
+    try {
+      listener(payload)
+    } catch (_err) {
+      // Listener notification failure ignored
+    }
+  }
+}
+
+/**
+ * Marks a session as complete and notifies subscribers.
+ *
+ * @param {string} callId
+ * @param {object} [finalData]
+ */
+export function completeLiveProgress(callId, finalData = {}) {
+  if (!callId) return
+  const session = activeSessions.get(callId)
+  if (!session || session.done) return
+
+  session.done = true
+  session.stage = 'Complete'
+  session.progress = 100
+  session.timestamp = Date.now()
+
+  const payload = {
+    callId,
+    stage: 'Complete',
+    progress: 100,
+    draftUrl: session.draftUrl,
+    done: true,
+    ...finalData,
+  }
+
+  for (const listener of session.listeners) {
+    try {
+      listener(payload)
+    } catch (_err) {
+      // Listener notification failure ignored
+    }
+  }
+  session.listeners.clear()
+
+  // Retain briefly for trailing SSE disconnects, then purge
+  setTimeout(() => {
+    activeSessions.delete(callId)
+  }, 15000)
+}
+
+/**
+ * Marks a session as aborted or errored.
+ *
+ * @param {string} callId
+ * @param {string} [reason]
+ */
+export function abortLiveProgress(callId, reason = 'Cancelled') {
+  if (!callId) return
+  const session = activeSessions.get(callId)
+  if (!session || session.done) return
+
+  session.done = true
+  session.error = reason
+  session.timestamp = Date.now()
+
+  const payload = {
+    callId,
+    error: reason,
+    done: true,
+  }
+
+  for (const listener of session.listeners) {
+    try {
+      listener(payload)
+    } catch (_err) {
+      // Listener notification failure ignored
+    }
+  }
+  session.listeners.clear()
+
+  setTimeout(() => {
+    activeSessions.delete(callId)
+  }, 10000)
+}
+
+/**
+ * Returns current snapshot of a live progress session.
+ *
+ * @param {string} callId
+ * @returns {object|null}
+ */
+export function getLiveProgress(callId) {
+  if (!callId) return null
+  const session = activeSessions.get(callId)
+  if (!session) return null
+  return {
+    callId: session.callId,
+    stage: session.stage,
+    step: session.step,
+    progress: session.progress,
+    draftUrl: session.draftUrl,
+    done: session.done,
+    error: session.error,
+  }
+}
+
+/**
+ * Subscribes a listener to progress events for a callId.
+ * Calls listener with current state immediately if present.
+ *
+ * @param {string} callId
+ * @param {Function} listener
+ * @returns {Function} unsubscribe
+ */
+export function subscribeLiveProgress(callId, listener) {
+  if (!callId || typeof listener !== 'function') return () => {}
+  let session = activeSessions.get(callId)
+  if (!session) {
+    session = createLiveProgressSession(callId)
+  }
+
+  session.listeners.add(listener)
+
+  // Initial event replay
+  listener({
+    callId: session.callId,
+    stage: session.stage,
+    step: session.step,
+    progress: session.progress,
+    draftUrl: session.draftUrl,
+    done: session.done,
+    error: session.error,
+  })
+
+  return () => {
+    session.listeners.delete(listener)
+  }
+}
+
+/**
+ * Registers the /dsh-image-gen/live-events SSE route on DSH web server.
+ *
+ * @param {object} ctx cordis context
+ */
+export function registerLiveProgressRoutes(ctx) {
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-image-gen/live-events',
+    handler: async (req, res) => {
+      if (req.method !== 'GET' && req.method !== 'HEAD') {
+        res.writeHead(405, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ error: 'GET only' }))
+        return
+      }
+      if (!isTrustedLocalRequest(req)) {
+        res.writeHead(403, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ error: 'forbidden' }))
+        return
+      }
+
+      const u = new URL(req.url, 'http://localhost')
+      const callId = u.searchParams.get('callId') || ''
+      if (!callId) {
+        res.writeHead(400, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ error: 'callId query parameter required' }))
+        return
+      }
+
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache, no-transform',
+        'Connection': 'keep-alive',
+        'Access-Control-Allow-Origin': '*',
+      })
+
+      res.write(': connected\n\n')
+
+      const unsubscribe = subscribeLiveProgress(callId, (data) => {
+        try {
+          res.write(`data: ${JSON.stringify(data)}\n\n`)
+          if (data.done) {
+            setTimeout(() => {
+              try {
+                res.end()
+              } catch (_err) {
+                // Response end failure ignored
+              }
+            }, 300)
+          }
+        } catch (_err) {
+          // SSE write failure ignored
+        }
+      })
+
+      req.on('close', () => {
+        unsubscribe()
+      })
+    },
+  }), 'dsh-image-gen: live events route')
+}

package/lib/pattern-helpers.js

@@ -1,3 +1,4 @@
+import sharp from 'sharp'
 // Pure helpers for generate_seamless_pattern (#178)
 
 export function buildSeamlessPrompt(motif, style, density) {
@@ -85,3 +86,19 @@ export function tilePixels(pixels, width, height, channels, cols, rows) {
   }
   return { pixels: out, width: outW, height: outH }
 }
+
+/**
+ * Decodes image container to raw RGBA pixels and scores edge wrap continuity (#371).
+ * Returns 0..1 (1 = identical opposite edges).
+ * @param {Buffer|Uint8Array} imageBytes
+ * @returns {Promise<number>}
+ */
+export async function scoreImageEdgeWrap(imageBytes) {
+  if (!imageBytes || imageBytes.length === 0) return 0
+  try {
+    const { data, info } = await sharp(imageBytes).raw().ensureAlpha().toBuffer({ resolveWithObject: true })
+    return scoreEdgeWrap(data, info.width, info.height, info.channels)
+  } catch {
+    return 0
+  }
+}