build: check Sharp runtime before compiling the application

Dockerfile

@@ -17,6 +17,9 @@ RUN --mount=type=cache,id=portfolio-npm-node22,target=/root/.npm,sharing=locked
     --replace-registry-host=registry.npmjs.org \
     --include=optional
 
+COPY scripts/check-image-runtime.mjs ./scripts/check-image-runtime.mjs
+RUN node scripts/check-image-runtime.mjs
+
 FROM dependencies AS verification
 
 COPY . .

scripts/check-image-runtime.mjs

@@ -0,0 +1,26 @@
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+// Check the fallback directly: Sharp 0.35.4 can hide its load error behind
+// an unrelated `err.code.endsWith` exception on unsupported native CPUs.
+try {
+  require('@img/sharp-wasm32/sharp.node');
+  console.log('Sharp WebAssembly binding loaded.');
+} catch (error) {
+  console.error('Sharp WebAssembly binding failed to load:', error);
+  process.exit(1);
+}
+
+try {
+  const { default: sharp } = await import('sharp');
+  const input = await sharp({ create: { width: 8, height: 8, channels: 3, background: '#336699' } }).webp().toBuffer();
+  const metadata = await sharp(input).metadata();
+  if (metadata.format !== 'webp' || metadata.width !== 8 || metadata.height !== 8) {
+    throw new Error('Image encode/decode verification failed');
+  }
+  console.log('Sharp ESM import and image processing passed.');
+} catch (error) {
+  console.error('Sharp image runtime failed:', error);
+  process.exit(1);
+}