@ossy/media-tasks 3.2.0 → 3.4.0

package/README.md

@@ -8,9 +8,15 @@ Tasks in this package are registered with `TaskService.RegisterTask()` at API st
 
 | Task id | Trigger | Description |
 |---------|---------|-------------|
-| `@ossy/media-tasks/tasks/resize-common-web` | `@ossy/platform/schema/file` `Created` (`content.ContentType: image/*`) | Generates common web thumbnail and gallery sizes using `sharp` |
+| `@ossy/media-tasks/tasks/resize-common-web` | `@ossy/platform/schema/file` `Created` (`content.ContentType: image/*`) | Generates common web thumbnail and gallery sizes using `sharp`, then patches `content.blurhash` / `content.width` / `content.height` |
 | `@ossy/media-tasks/tasks/visual-content-descriptors` | `@ossy/platform/schema/file` `Created` (`image/*`, `video/*`) | Uses GPT-4o to generate title, description, tags, and alt text |
 
+## Image placeholders (BlurHash)
+
+After derivatives upload, `resize-common-web` encodes a [BlurHash](https://blurha.sh/) string and natural pixel size onto the file resource via `@ossy/resources/actions/patch-content` (ADR 0008 `Patched` deep merge — does not replace `sizes`).
+
+Consumers (`Image` / `ImageCard`) prefer `content.blurhash` for an instant local placeholder, and still fall back to `sizes['loader-square-blurred-after']`. `width` / `height` set CSS `aspect-ratio` to reduce layout shift.
+
 ## Schemas
 
 Task outcome schemas live in `src/*.schema.js` and are auto-discovered at build time:
@@ -44,6 +50,7 @@ export async function run ({ event, sdk }) { ... }
 
 ## Dependencies
 
-- **`sharp`** (peer) — image resizing in `resize-common-web`
+- **`sharp`** (peer) — image resizing + metadata in `resize-common-web`
+- **`blurhash`** — encode compact placeholders after resize
 - **`openai`** (peer) — GPT-4o vision in `visual-content-descriptors`
 - **`@ossy/platform`** — `StorageClient.load` for reading uploaded file bytes (provided at runtime by the platform server)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/media-tasks",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "description": "Changestream-triggered media processing tasks (image resize, AI descriptors)",
   "type": "module",
   "main": "./src/index.js",
@@ -12,11 +12,13 @@
     "src": "./src"
   },
   "scripts": {
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest --verbose",
     "typecheck": "echo \"No TypeScript in media-tasks package\" && exit 0"
   },
   "dependencies": {
     "@ossy/observability": "^3.0.9",
-    "@ossy/resources": "^3.2.0"
+    "@ossy/resources": "^3.4.0",
+    "blurhash": "^2.0.5"
   },
   "peerDependencies": {
     "openai": ">=4",
@@ -32,5 +34,5 @@
   ],
   "author": "Ossy <yourfriends@ossy.se> (https://ossy.se)",
   "license": "MIT",
-  "gitHead": "b045f1fd7f2fe00c776b9ea96f76083b93fd8556"
+  "gitHead": "d36b69444268d172bc3e8e1dc77e67afc63f8650"
 }

package/src/encode-blurhash.js

@@ -0,0 +1,37 @@
+/**
+ * Encode a BlurHash and read natural dimensions from an image buffer via sharp.
+ *
+ * @param {import('sharp')} sharp
+ * @param {Buffer} sourceBuffer
+ * @param {{ componentX?: number, componentY?: number, maxSide?: number }} [options]
+ * @returns {Promise<{ blurhash: string, width: number, height: number }>}
+ */
+export async function encodeBlurhashFromBuffer (sharp, sourceBuffer, options = {}) {
+  const componentX = options.componentX ?? 4
+  const componentY = options.componentY ?? 3
+  const maxSide = options.maxSide ?? 32
+
+  const metadata = await sharp(sourceBuffer).metadata()
+  const width = metadata.width
+  const height = metadata.height
+  if (!width || !height) {
+    throw new Error('encodeBlurhashFromBuffer: image metadata missing width/height')
+  }
+
+  const { data, info } = await sharp(sourceBuffer)
+    .ensureAlpha()
+    .resize(maxSide, maxSide, { fit: 'inside' })
+    .raw()
+    .toBuffer({ resolveWithObject: true })
+
+  const { encode } = await import('blurhash')
+  const blurhash = encode(
+    new Uint8ClampedArray(data),
+    info.width,
+    info.height,
+    componentX,
+    componentY,
+  )
+
+  return { blurhash, width, height }
+}

package/src/encode-blurhash.spec.js

@@ -0,0 +1,29 @@
+import sharp from 'sharp'
+import { decode } from 'blurhash'
+import { encodeBlurhashFromBuffer } from './encode-blurhash.js'
+
+describe('encodeBlurhashFromBuffer', () => {
+  it('encodes a blurhash and returns natural dimensions', async () => {
+    const sourceBuffer = await sharp({
+      create: {
+        width: 80,
+        height: 40,
+        channels: 3,
+        background: { r: 20, g: 120, b: 200 },
+      },
+    })
+      .png()
+      .toBuffer()
+
+    const result = await encodeBlurhashFromBuffer(sharp, sourceBuffer)
+
+    expect(result.width).toBe(80)
+    expect(result.height).toBe(40)
+    expect(typeof result.blurhash).toBe('string')
+    expect(result.blurhash.length).toBeGreaterThan(6)
+
+    const pixels = decode(result.blurhash, 4, 4)
+    expect(pixels).toBeInstanceOf(Uint8ClampedArray)
+    expect(pixels.length).toBe(4 * 4 * 4)
+  })
+})

package/src/resize-common-web.task.js

@@ -1,6 +1,7 @@
 import { createLogger } from '@ossy/observability'
 import { StorageClient } from '@ossy/platform'
-import { GetResource } from '@ossy/resources'
+import { GetResource, PatchResourceContent } from '@ossy/resources'
+import { encodeBlurhashFromBuffer } from './encode-blurhash.js'
 
 const log = createLogger('media-tasks')
 
@@ -13,6 +14,16 @@ const Sizes = [
   { width: 4, height: undefined, name: 'loader-square-blurred-after' },
 ]
 
+/** Created fires before the client finishes PUT; wait briefly for blob bytes. */
+async function loadSourceBuffer (key, { attempts = 20, delayMs = 250 } = {}) {
+  for (let i = 0; i < attempts; i++) {
+    const { buffer, exists } = await StorageClient.load(key)
+    if (exists && buffer) return buffer
+    await new Promise(resolve => setTimeout(resolve, delayMs))
+  }
+  return null
+}
+
 export const metadata = {
   id: '@ossy/media-tasks/tasks/resize-common-web',
   triggers: [
@@ -36,8 +47,8 @@ export async function run ({ event, sdk }) {
     throw new Error(`[media-tasks/tasks/resize-common-web] missing storage key for ${resourceId}`)
   }
 
-  const { buffer: sourceBuffer, exists } = await StorageClient.load(key)
-  if (!exists || !sourceBuffer) {
+  const sourceBuffer = await loadSourceBuffer(key)
+  if (!sourceBuffer) {
     throw new Error(`[media-tasks/tasks/resize-common-web] missing file bytes for ${resourceId}`)
   }
 
@@ -56,4 +67,16 @@ export async function run ({ event, sdk }) {
       throw error
     }
   }
+
+  try {
+    const { blurhash, width, height } = await encodeBlurhashFromBuffer(sharp, sourceBuffer)
+    log.info(`[media-tasks/tasks/resize-common-web] Patching blurhash for ${resourceId}`)
+    await sdk.invoke(PatchResourceContent, {
+      id: resourceId,
+      content: { blurhash, width, height },
+    })
+  } catch (error) {
+    log.error(`[media-tasks/tasks/resize-common-web] Error encoding blurhash for ${resourceId}`, undefined, error)
+    throw error
+  }
 }