@rathnasgala2/template 3.1.0 → 3.2.0

package/src/core/internal/media/gif-probe.js

@@ -0,0 +1,162 @@
+/**
+ * Bounded GIF container validation and declared-dimension extraction.
+ *
+ * Scope decision (documented, not silently assumed, and identical in spirit
+ * to `webp-probe.js` and `avif-probe.js`): GIF is validated, never decoded
+ * or re-encoded. This renderer carries no GIF encoder, so an animated GIF
+ * cannot be resized without losing its animation; GIF is therefore admitted
+ * as a *source* reference (recorded, digest-verified, dimension-bounded)
+ * with no generated responsive derivative, and its original bytes pass
+ * through unmodified as the sole asset entry. Because the bytes are never
+ * rewritten, any comment or application extension the file carries is
+ * served as authored.
+ *
+ * What this module enforces, fully: the exact `GIF87a`/`GIF89a` signature;
+ * the logical screen's declared width/height, and every frame's declared
+ * width/height, within the shared dimension/pixel ceilings; every colour
+ * table, extension and image-data sub-block chain inside the buffer; a
+ * known block introducer for every block; at least one image; and the
+ * trailer as the file's exact last byte (no trailing payload, so a GIF
+ * cannot smuggle a second file past this pipeline). Animation is admitted.
+ *
+ * The walk is bounded: at most 4,096 top-level blocks are visited (the same
+ * container-structure bound `avif-probe.js` applies to boxes), and every
+ * sub-block chain advances by at least one byte per step, so a malformed or
+ * adversarial file cannot cause an out-of-bounds read or an unbounded walk.
+ */
+
+import { MediaPipelineError } from '../../errors.js';
+import { assertDimensionsWithinCeiling } from './limits.js';
+
+const MAX_BLOCKS_VISITED = 4096;
+const HEADER_BYTES = 6;
+const LOGICAL_SCREEN_DESCRIPTOR_BYTES = 7;
+const IMAGE_DESCRIPTOR_BYTES = 9;
+const EXTENSION_INTRODUCER = 0x21;
+const IMAGE_SEPARATOR = 0x2c;
+const TRAILER = 0x3b;
+/** LZW codes are at most 12 bits wide, so the minimum code size is at most 11. */
+const MAX_LZW_MINIMUM_CODE_SIZE = 11;
+
+/**
+ * @param {string} message what is malformed
+ * @param {string} referencePath the source path, for error messages
+ * @returns {MediaPipelineError} a `MEDIA_FORMAT_INVALID` rejection
+ */
+function malformed(message, referencePath) {
+  return new MediaPipelineError('MEDIA_FORMAT_INVALID', message, referencePath);
+}
+
+/**
+ * The byte length of a colour table whose packed field is `packed`, or `0`
+ * when its presence flag (bit 7) is clear.
+ *
+ * @param {number} packed the descriptor's packed field
+ * @returns {number} the table's byte length
+ */
+function colorTableBytes(packed) {
+  return (packed & 0x80) === 0 ? 0 : 3 * 2 ** ((packed & 0x07) + 1);
+}
+
+/**
+ * Skip one data sub-block chain (size byte, that many bytes, repeated until
+ * a zero-size terminator), returning the offset just past the terminator.
+ *
+ * @param {Buffer} bytes the GIF bytes
+ * @param {number} offset the offset of the chain's first size byte
+ * @param {string} referencePath the source path, for error messages
+ * @returns {number} the offset after the chain's terminator
+ */
+function skipSubBlocks(bytes, offset, referencePath) {
+  let cursor = offset;
+  for (;;) {
+    if (cursor >= bytes.length) {
+      throw malformed('GIF data sub-blocks run past the end', referencePath);
+    }
+    const size = bytes[cursor];
+    cursor += 1;
+    if (size === 0) return cursor;
+    cursor += size;
+  }
+}
+
+/**
+ * Validate a GIF file and return its logical screen dimensions.
+ *
+ * @param {Buffer} bytes complete GIF file bytes
+ * @param {string} referencePath the source path, for error messages
+ * @returns {{width: number, height: number}} the declared dimensions
+ */
+export function probeGif(bytes, referencePath) {
+  const signature = bytes.subarray(0, HEADER_BYTES).toString('ascii');
+  if (
+    bytes.length < HEADER_BYTES + LOGICAL_SCREEN_DESCRIPTOR_BYTES + 1 ||
+    (signature !== 'GIF87a' && signature !== 'GIF89a')
+  ) {
+    throw malformed('missing GIF87a/GIF89a signature', referencePath);
+  }
+  const width = bytes.readUInt16LE(HEADER_BYTES);
+  const height = bytes.readUInt16LE(HEADER_BYTES + 2);
+  assertDimensionsWithinCeiling(width, height, referencePath, 'GIF');
+
+  let cursor =
+    HEADER_BYTES +
+    LOGICAL_SCREEN_DESCRIPTOR_BYTES +
+    colorTableBytes(bytes[HEADER_BYTES + 4]);
+  let images = 0;
+  for (let visited = 0; visited < MAX_BLOCKS_VISITED; visited += 1) {
+    if (cursor >= bytes.length) {
+      throw malformed('GIF ends without a trailer', referencePath);
+    }
+    const introducer = bytes[cursor];
+    if (introducer === TRAILER) {
+      if (images === 0) {
+        throw malformed('GIF carries no image', referencePath);
+      }
+      if (cursor + 1 !== bytes.length) {
+        throw malformed(
+          'GIF has bytes after its trailer; no trailing payload is admitted',
+          referencePath,
+        );
+      }
+      return { width, height };
+    }
+    if (introducer === EXTENSION_INTRODUCER) {
+      // Introducer, label, then the extension's own data sub-blocks.
+      cursor = skipSubBlocks(bytes, cursor + 2, referencePath);
+    } else if (introducer === IMAGE_SEPARATOR) {
+      if (cursor + IMAGE_DESCRIPTOR_BYTES + 1 > bytes.length) {
+        throw malformed('GIF image descriptor is truncated', referencePath);
+      }
+      assertDimensionsWithinCeiling(
+        bytes.readUInt16LE(cursor + 5),
+        bytes.readUInt16LE(cursor + 7),
+        referencePath,
+        'GIF frame',
+      );
+      cursor += IMAGE_DESCRIPTOR_BYTES + 1 + colorTableBytes(bytes[cursor + 9]);
+      const lzwMinimumCodeSize = bytes[cursor];
+      if (
+        lzwMinimumCodeSize === undefined ||
+        lzwMinimumCodeSize < 1 ||
+        lzwMinimumCodeSize > MAX_LZW_MINIMUM_CODE_SIZE
+      ) {
+        throw malformed(
+          'GIF image data has no valid LZW minimum code size',
+          referencePath,
+        );
+      }
+      cursor = skipSubBlocks(bytes, cursor + 1, referencePath);
+      images += 1;
+    } else {
+      throw malformed(
+        `unknown GIF block introducer 0x${introducer.toString(16)}`,
+        referencePath,
+      );
+    }
+  }
+  throw malformed(
+    `GIF has more than ${MAX_BLOCKS_VISITED} blocks`,
+    referencePath,
+  );
+}

package/src/core/internal/media/limits.js

@@ -40,6 +40,27 @@ export const MAX_IMAGE_PIXELS = 16_777_216;
 /** Maximum admitted decoded RGBA8 output buffer size, in bytes. */
 export const MAX_DECODED_RGBA_BYTES = 67_108_864;
 
+/**
+ * The most bytes per pixel the `jpeg-js` decoder holds while decoding one
+ * image, all of which its own `maxMemoryUsageInMB` knob counts: per
+ * component (at most four, CMYK) every 8x8 coefficient block as a 32-bit
+ * integer per sample (4 bytes), one output-line byte and one interleaved
+ * byte per sample, plus the 4-byte RGBA output: (4 + 1 + 1) x 4 + 4 = 28,
+ * rounded up to 32 to leave room for MCU padding and table allocations.
+ */
+export const JPEG_DECODE_BYTES_PER_PIXEL = 32;
+
+/**
+ * The `jpeg-js` working-set ceiling: an image at the pixel ceiling, at the
+ * worst-case per-pixel cost above (536,870,912 bytes). The decoded RGBA8
+ * output itself stays bounded by {@link MAX_DECODED_RGBA_BYTES} through the
+ * pixel ceiling; this bound only stops the decoder's own intermediate
+ * buffers from being mistaken for the output buffer, which rejected every
+ * JPEG above roughly three to five megapixels.
+ */
+export const MAX_JPEG_DECODE_WORKING_SET_BYTES =
+  MAX_IMAGE_PIXELS * JPEG_DECODE_BYTES_PER_PIXEL;
+
 /**
  * Maximum admitted raster source byte length: the smaller of this
  * renderer's raster-specific cap (16,777,216) and its general

package/src/core/internal/media/pipeline.js

@@ -12,9 +12,11 @@
  *
  * Every distinct image/font reference in the publication (publication
  * default image, each author's avatar, each content record's hero and
- * social image, the appearance package's brand mark, wordmark and font
- * assets) is collected once, deduplicated by path, processed independently,
- * and turned into one or more content-addressed output files under
+ * social image, every content image a rendered body references (resolved
+ * by `content-images.js` before this pipeline runs), the appearance
+ * package's brand mark, wordmark and font assets) is collected once,
+ * deduplicated by path, processed once per distinct source digest, and
+ * turned into one or more content-addressed output files under
  * `assets/media/` in the candidate output directory plus one
  * `manifestAsset`-shaped row per output file. `manifestAsset` has no field
  * for a separate source/transform/output digest triple or for width/height
@@ -44,6 +46,7 @@ import { decodePng, encodePng } from './png-codec.js';
 import { applyExifOrientation, resizeRaster } from './resize.js';
 import { MEDIA_TYPE_BY_FORMAT, sniffMediaFormat } from './sniff.js';
 import { probeAvif } from './avif-probe.js';
+import { probeGif } from './gif-probe.js';
 import { probeWebp } from './webp-probe.js';
 
 /** @type {Readonly<Record<string, string>>} media type -> file extension */
@@ -52,6 +55,7 @@ const EXTENSION_BY_MEDIA_TYPE = Object.freeze({
   'image/jpeg': 'jpg',
   'image/webp': 'webp',
   'image/avif': 'avif',
+  'image/gif': 'gif',
   'font/woff2': 'woff2',
 });
 
@@ -59,16 +63,24 @@ const EXTENSION_BY_MEDIA_TYPE = Object.freeze({
  * @typedef {{path: string, sourceDigest: string}} ImageReference
  */
 
+/**
+ * One output file of a processed image: its output path and pixel size.
+ *
+ * @typedef {{path: string, width: number, height: number}} MediaVariant
+ */
+
 /**
  * Collect every distinct image reference in `buildInput`, deduplicated by
  * path (rejecting a path reused with a conflicting digest).
  *
  * @param {import('../../../../types/index.d.ts').NormalizedBuildInput} buildInput
  *   the validated build input
+ * @param {readonly ImageReference[]} contentImages the assets rendered
+ *   bodies reference, already resolved by `content-images.js`
  * @returns {ImageReference[]} the distinct image references, in
  *   first-seen order
  */
-function collectImageReferences(buildInput) {
+function collectImageReferences(buildInput, contentImages) {
   /** @type {Map<string, ImageReference>} */
   const byPath = new Map();
   /** @type {(ref: ImageReference | undefined) => void} */
@@ -91,6 +103,7 @@ function collectImageReferences(buildInput) {
     if (record.frontmatter.hero) add(record.frontmatter.hero.file);
     add(record.frontmatter.socialImage);
   }
+  for (const reference of contentImages) add(reference);
   add(buildInput.appearance.brandMark);
   add(buildInput.appearance.wordmark);
 
@@ -192,9 +205,9 @@ function derivativePath(sourceDigest, variant, extension) {
  *
  * @param {Buffer} bytes verified source bytes
  * @param {ImageReference} reference the reference these bytes back
- * @returns {{files: PipelineOutputFile[], width: number, height: number}}
- *   the output files this reference produces and the canonical original's
- *   pixel dimensions
+ * @returns {(PipelineOutputFile & {width: number, height: number})[]} the
+ *   output files this reference produces, each with its pixel size: the
+ *   canonical original first, then every derivative in ascending width
  */
 function processImage(bytes, reference) {
   const format = sniffMediaFormat(bytes);
@@ -213,24 +226,21 @@ function processImage(bytes, reference) {
     );
   }
 
-  if (format === 'webp' || format === 'avif') {
-    // Bounded container/dimension validation only; see webp-probe.js and
-    // avif-probe.js module documentation for the documented scope decision.
-    const size =
-      format === 'webp'
-        ? probeWebp(bytes, reference.path)
-        : probeAvif(bytes, reference.path);
+  if (format === 'webp' || format === 'avif' || format === 'gif') {
+    // Bounded container/dimension validation only, and the original bytes
+    // pass through unmodified; see webp-probe.js, avif-probe.js and
+    // gif-probe.js module documentation for the documented scope decision.
+    const probe = { webp: probeWebp, avif: probeAvif, gif: probeGif }[format];
+    const size = probe(bytes, reference.path);
     const extension = EXTENSION_BY_MEDIA_TYPE[MEDIA_TYPE_BY_FORMAT[format]];
-    return {
-      files: [
-        {
-          path: derivativePath(reference.sourceDigest, 'original', extension),
-          bytes,
-        },
-      ],
-      width: size.width,
-      height: size.height,
-    };
+    return [
+      {
+        path: derivativePath(reference.sourceDigest, 'original', extension),
+        bytes,
+        width: size.width,
+        height: size.height,
+      },
+    ];
   }
 
   /** @type {{width: number, height: number, rgba: Buffer}} */
@@ -250,11 +260,12 @@ function processImage(bytes, reference) {
     extension = 'jpg';
   }
 
-  /** @type {PipelineOutputFile[]} */
   const outputs = [
     {
       path: derivativePath(reference.sourceDigest, 'original', extension),
       bytes: encode(oriented),
+      width: oriented.width,
+      height: oriented.height,
     },
   ];
 
@@ -264,9 +275,11 @@ function processImage(bytes, reference) {
     outputs.push({
       path: derivativePath(reference.sourceDigest, `${width}w`, extension),
       bytes: encode(resized),
+      width: resized.width,
+      height: resized.height,
     });
   }
-  return { files: outputs, width: oriented.width, height: oriented.height };
+  return outputs;
 }
 
 /**
@@ -275,16 +288,22 @@ function processImage(bytes, reference) {
  *
  * @param {import('../../../../types/index.d.ts').NormalizedBuildInput} buildInput
  *   the validated build input
- * @param {{sourceDirectory: string}} options the media pipeline's own
- *   options
- * @returns {Promise<{assets: import('../../../../types/index.d.ts').ManifestAssetEntry[], files: PipelineOutputFile[], dimensions: Record<string, {width: number, height: number}>}>}
- *   the asset manifest rows, the output files backing them, and the pixel
+ * @param {{sourceDirectory: string, contentImages?: readonly ImageReference[]}} options
+ *   the media pipeline's own options: the read-only source root, and the
+ *   assets rendered bodies reference (`content-images.js`)
+ * @returns {Promise<{assets: import('../../../../types/index.d.ts').ManifestAssetEntry[], files: PipelineOutputFile[], dimensions: Record<string, {width: number, height: number}>, variants: Record<string, MediaVariant[]>}>}
+ *   the asset manifest rows, the output files backing them, the pixel
  *   dimensions of each image's canonical original keyed by its output path
  *   (`manifestAsset` has no width/height field, so this is the one place the
- *   renderer learns them, for `<img width height>` and structured data)
+ *   renderer learns them, for `<img width height>` and structured data),
+ *   and every output file of each image keyed by its source digest, in
+ *   ascending width (for `srcset`)
  */
-export async function processMedia(buildInput, { sourceDirectory }) {
-  const imageReferences = collectImageReferences(buildInput);
+export async function processMedia(
+  buildInput,
+  { sourceDirectory, contentImages = [] },
+) {
+  const imageReferences = collectImageReferences(buildInput, contentImages);
   if (imageReferences.length > MAX_IMAGES_PER_PUBLICATION) {
     throw new MediaPipelineError(
       'MEDIA_RESOURCE_EXCEEDED',
@@ -305,19 +324,33 @@ export async function processMedia(buildInput, { sourceDirectory }) {
   const files = [];
   /** @type {Record<string, {width: number, height: number}>} */
   const dimensions = {};
+  /** @type {Record<string, MediaVariant[]>} */
+  const variants = {};
   let totalBytes = 0;
 
   for (const reference of imageReferences) {
     const bytes = await readAndVerify(sourceDirectory, reference);
-    const processed = processImage(bytes, reference);
-    for (const output of processed.files) {
+    // Output paths are content-addressed: two paths with identical bytes
+    // produce identical files, so each distinct digest is processed (and
+    // emitted) once.
+    if (Object.hasOwn(variants, reference.sourceDigest)) continue;
+    const outputs = processImage(bytes, reference);
+    for (const output of outputs) {
       totalBytes += output.bytes.byteLength;
-      files.push(output);
+      files.push({ path: output.path, bytes: output.bytes });
     }
-    dimensions[processed.files[0].path] = {
-      width: processed.width,
-      height: processed.height,
+    const [original] = outputs;
+    dimensions[original.path] = {
+      width: original.width,
+      height: original.height,
     };
+    variants[reference.sourceDigest] = outputs
+      .map(({ path: outputPath, width, height }) => ({
+        path: outputPath,
+        width,
+        height,
+      }))
+      .sort((a, b) => a.width - b.width);
   }
 
   for (const reference of fontReferences) {
@@ -364,5 +397,5 @@ export async function processMedia(buildInput, { sourceDirectory }) {
     });
   });
 
-  return { assets, files, dimensions };
+  return { assets, files, dimensions, variants };
 }

package/src/core/internal/media/sniff.js

@@ -60,6 +60,17 @@ function isAvif(bytes) {
   return bytes.subarray(8, 12).toString('ascii') === 'avif';
 }
 
+/**
+ * @param {Buffer} bytes candidate file bytes
+ * @returns {boolean} true when `bytes` starts with a `GIF87a` or `GIF89a`
+ *   signature
+ */
+function isGif(bytes) {
+  if (bytes.length < 6) return false;
+  const signature = bytes.subarray(0, 6).toString('ascii');
+  return signature === 'GIF87a' || signature === 'GIF89a';
+}
+
 /**
  * Detect whether `bytes` looks like SVG/XML markup, scanning only the first
  * 4096 bytes (bounded: this classification exists purely to reject, never to
@@ -82,7 +93,7 @@ function looksLikeSvg(bytes) {
 }
 
 /**
- * @typedef {'png' | 'jpeg' | 'webp' | 'avif' | 'svg' | 'unknown'} SniffedFormat
+ * @typedef {'png' | 'jpeg' | 'webp' | 'avif' | 'gif' | 'svg' | 'unknown'} SniffedFormat
  */
 
 /**
@@ -97,13 +108,15 @@ export function sniffMediaFormat(bytes) {
   if (isJpeg(bytes)) return 'jpeg';
   if (isWebp(bytes)) return 'webp';
   if (isAvif(bytes)) return 'avif';
+  if (isGif(bytes)) return 'gif';
   return 'unknown';
 }
 
-/** @type {Readonly<Record<'png' | 'jpeg' | 'webp' | 'avif', string>>} */
+/** @type {Readonly<Record<'png' | 'jpeg' | 'webp' | 'avif' | 'gif', string>>} */
 export const MEDIA_TYPE_BY_FORMAT = Object.freeze({
   png: 'image/png',
   jpeg: 'image/jpeg',
   webp: 'image/webp',
   avif: 'image/avif',
+  gif: 'image/gif',
 });

package/src/core/internal/messages.js

@@ -46,7 +46,7 @@ const CATALOGS = Object.freeze({
     /** @type {(displayName: string) => string} */
     byLineLabel: (displayName) => `By ${displayName}`,
     footerCopyrightPrefix: '©',
-    footerAttributionLabel: 'Published with the Galascribe template renderer.',
+    footerAttributionLabel: 'Made with Galascribe',
     errorPageHeading: 'Page not found',
     errorPageBody:
       'The page you were looking for could not be found. It may have been ' +
@@ -113,6 +113,15 @@ const CATALOGS = Object.freeze({
     articleCountLabel: (count) =>
       count === '1' ? '1 article' : `${count} articles`,
     emptyListingLabel: 'No articles yet.',
+    editionsNavigationLabel: 'Editions',
+    editionOriginalLabel: 'Original',
+    editionQuickReadLabel: 'Quick read',
+    editionStandardLabel: 'Standard',
+    editionDeepDiveLabel: 'Deep dive',
+    editionNoticeLabel:
+      'Generated edition, reviewed by the author; the original is the reference',
+    /** @type {(title: string, edition: string) => string} */
+    editionPageTitle: (title, edition) => `${title} (${edition})`,
     aboutPageTitle: 'About',
     /** @type {(date: string) => string} */
     updatedLabel: (date) => `Updated ${date}`,