pagyra-js 0.0.1

package/src/image/base-decoder.ts

@@ -0,0 +1,149 @@
+import type { ImageInfo } from "./types.js";
+
+export interface DecodeOptions {
+  maxWidth?: number;
+  maxHeight?: number;
+  scale?: number;
+}
+
+export class DataReader {
+  private view: DataView;
+  private offset: number = 0;
+
+  constructor(buffer: ArrayBuffer) {
+    this.view = new DataView(buffer);
+  }
+
+  public seek(offset: number): void {
+    this.offset = offset;
+  }
+
+  public tell(): number {
+    return this.offset;
+  }
+
+  public hasMore(): boolean {
+    return this.offset < this.view.byteLength;
+  }
+
+  public getUint8(): number {
+    const value = this.view.getUint8(this.offset);
+    this.offset += 1;
+    return value;
+  }
+
+  public getUint16(littleEndian: boolean = false): number {
+    const value = this.view.getUint16(this.offset, littleEndian);
+    this.offset += 2;
+    return value;
+  }
+
+  public getUint32(littleEndian: boolean = false): number {
+    const value = this.view.getUint32(this.offset, littleEndian);
+    this.offset += 4;
+    return value;
+  }
+
+  public getString(length: number): string {
+    let str = "";
+    for (let i = 0; i < length; i++) {
+      str += String.fromCharCode(this.getUint8());
+    }
+    return str;
+  }
+
+  public getView(length: number): DataView {
+    const view = new DataView(this.view.buffer, this.view.byteOffset + this.offset, length);
+    this.offset += length;
+    return view;
+  }
+}
+
+export class BitReader {
+  private view: DataView;
+  private bytePos: number = 0;
+  private bitPos: number = 0;
+
+  constructor(view: DataView) {
+    this.view = view;
+  }
+
+  public readBits(n: number): number {
+    let value = 0;
+    for (let i = 0; i < n; i++) {
+      if (this.bytePos >= this.view.byteLength) return value;
+      const byte = this.view.getUint8(this.bytePos);
+      const bit = (byte >> this.bitPos) & 1;
+      value |= bit << i;
+      this.bitPos++;
+      if (this.bitPos === 8) {
+        this.bitPos = 0;
+        this.bytePos++;
+      }
+    }
+    return value;
+  }
+}
+
+export abstract class BaseDecoder {
+  protected static calculateDimensions(
+    width: number,
+    height: number,
+    options: DecodeOptions
+  ): { targetWidth: number; targetHeight: number } {
+    let targetWidth = width;
+    let targetHeight = height;
+
+    if (options.scale && options.scale > 0) {
+      targetWidth = Math.max(1, Math.round(width * options.scale));
+      targetHeight = Math.max(1, Math.round(height * options.scale));
+    } else if (options.maxWidth || options.maxHeight) {
+      const scale = Math.min(
+        options.maxWidth ? options.maxWidth / width : Infinity,
+        options.maxHeight ? options.maxHeight / height : Infinity
+      );
+
+      if (scale > 0 && scale < 1) {
+        targetWidth = Math.max(1, Math.round(width * scale));
+        targetHeight = Math.max(1, Math.round(height * scale));
+      }
+    }
+
+    return { targetWidth, targetHeight };
+  }
+
+  // Optimized nearest-neighbor resize
+  protected static resizeNN(
+    src: Uint8Array,
+    sw: number,
+    sh: number,
+    tw: number,
+    th: number,
+    channels: number,
+  ): Uint8Array {
+    if (sw === tw && sh === th) return src;
+
+    const dst = new Uint8Array(tw * th * channels);
+    const xRatio = sw / tw;
+    const yRatio = sh / th;
+
+    for (let y = 0; y < th; y++) {
+      const sy = Math.min(sh - 1, Math.floor(y * yRatio));
+      const srcRowOffset = sy * sw * channels;
+      const dstRowOffset = y * tw * channels;
+
+      for (let x = 0; x < tw; x++) {
+        const sx = Math.min(sw - 1, Math.floor(x * xRatio));
+        const si = srcRowOffset + sx * channels;
+        const di = dstRowOffset + x * channels;
+
+        for (let c = 0; c < channels; c++) {
+          dst[di + c] = src[si + c];
+        }
+      }
+    }
+    return dst;
+  }
+
+  public abstract decode(buffer: ArrayBuffer, options?: DecodeOptions): Promise<ImageInfo>;
+}

package/src/image/image-service.ts

@@ -0,0 +1,188 @@
+import { JpegDecoder } from './jpeg-decoder.js';
+import { PngDecoder } from './png-decoder.js';
+import { WebpDecoder } from './webp-decoder.js';
+import type { ImageInfo, ImageDecodeOptions } from './types.js';
+import type { Environment } from '../environment/environment.js';
+import { NodeEnvironment } from '../environment/node-environment.js';
+import { getGlobalEnvironment } from '../environment/global.js';
+
+/**
+ * Image Service following SOLID principles:
+ * - Single Responsibility: Handles all image operations
+ * - Open/Closed: Extensible for new image formats
+ * - Dependency Inversion: Depends on abstractions, not concrete implementations
+ */
+export class ImageService {
+  private static instance: ImageService;
+  private readonly env: Environment;
+  private imageCache = new Map<string, ImageInfo>();
+  private readonly jpegDecoder = new JpegDecoder();
+  private readonly pngDecoder = new PngDecoder();
+  private readonly webpDecoder = new WebpDecoder();
+
+  private constructor(env?: Environment) {
+    this.env = env ?? globalEnvironmentFallback();
+  }
+
+  /**
+   * Singleton pattern implementation
+   */
+  public static getInstance(env?: Environment): ImageService {
+    if (!ImageService.instance) {
+      ImageService.instance = new ImageService(env);
+    }
+    return ImageService.instance;
+  }
+
+  /**
+   * Loads an image from file path
+   */
+  public async loadImage(path: string, options?: ImageDecodeOptions): Promise<ImageInfo> {
+    const normalizedPath = this.normalizeSource(path);
+    // Check cache first
+    const cacheKey = this.generateCacheKey(normalizedPath, options);
+    if (this.imageCache.has(cacheKey)) {
+      return this.imageCache.get(cacheKey)!;
+    }
+
+    try {
+      const arrayBuffer = await this.env.loader.load(normalizedPath);
+      const imageInfo = await this.decodeImage(arrayBuffer, options);
+
+      // Cache the result
+      this.imageCache.set(cacheKey, imageInfo);
+      return imageInfo;
+    } catch (error) {
+      throw new Error(`Failed to load image from ${normalizedPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Decodes image data from buffer
+   */
+  public async decodeImage(buffer: ArrayBuffer, options?: ImageDecodeOptions): Promise<ImageInfo> {
+    // Detect image format by checking file signatures
+    const format = this.detectImageFormat(buffer);
+    
+    switch (format) {
+      case 'jpeg':
+        return this.jpegDecoder.decode(buffer, options);
+      case 'png':
+        return this.pngDecoder.decode(buffer, options);
+      case 'gif':
+        // Placeholder for GIF decoder
+        return this.decodeGif(buffer, options);
+      case 'webp':
+        // Placeholder for WebP decoder
+        return this.decodeWebp(buffer, options);
+      default:
+        throw new Error(`Unsupported image format: ${format}`);
+    }
+  }
+
+  /**
+   * Detects image format by magic numbers
+   */
+  private detectImageFormat(buffer: ArrayBuffer): 'jpeg' | 'png' | 'gif' | 'webp' {
+    const view = new DataView(buffer);
+    
+    // JPEG signature: FF D8 FF
+    if (buffer.byteLength >= 3 && 
+        view.getUint8(0) === 0xFF && 
+        view.getUint8(1) === 0xD8 && 
+        view.getUint8(2) === 0xFF) {
+      return 'jpeg';
+    }
+    
+    // PNG signature: 89 50 4E 47 0D 0A 1A 0A
+    if (buffer.byteLength >= 8 && 
+        view.getUint8(0) === 0x89 && 
+        view.getUint8(1) === 0x50 && 
+        view.getUint8(2) === 0x4E && 
+        view.getUint8(3) === 0x47 && 
+        view.getUint8(4) === 0x0D && 
+        view.getUint8(5) === 0x0A && 
+        view.getUint8(6) === 0x1A && 
+        view.getUint8(7) === 0x0A) {
+      return 'png';
+    }
+    
+    // GIF signature: GIF87a or GIF89a
+    if (buffer.byteLength >= 6) {
+      const gifSignature = new TextDecoder().decode(buffer.slice(0, 6));
+      if (gifSignature.startsWith('GIF')) {
+        return 'gif';
+      }
+    }
+    
+    // WebP signature: RIFF + WEBP
+    if (buffer.byteLength >= 12 && 
+        view.getUint32(0, false) === 0x52494646 && // "RIFF"
+        view.getUint32(8, false) === 0x57454250) { // "WEBP"
+      return 'webp';
+    }
+    
+    throw new Error('Unknown image format');
+  }
+
+
+  /**
+   * Placeholder GIF decoder
+   */
+  private decodeGif(_buffer: ArrayBuffer, options?: ImageDecodeOptions): ImageInfo {
+    // For now, return placeholder data
+    const width = options?.maxWidth || 100;
+    const height = options?.maxHeight || 100;
+    const pixelCount = width * height;
+    const imageData = new ArrayBuffer(pixelCount * 4); // RGBA
+
+    return {
+      width,
+      height,
+      format: 'gif',
+      channels: 4,
+      bitsPerChannel: 8,
+      data: imageData
+    };
+  }
+
+  /**
+   * WebP decoder
+   */
+  private async decodeWebp(buffer: ArrayBuffer, options?: ImageDecodeOptions): Promise<ImageInfo> {
+    return this.webpDecoder.decode(buffer, options);
+  }
+
+  /**
+   * Generates a cache key for image options
+   */
+  private generateCacheKey(path: string, options?: ImageDecodeOptions): string {
+    const optionsStr = options ? 
+      `_${options.maxWidth || 0}_${options.maxHeight || 0}_${options.scale || 1}` : 
+      '_default';
+    return `${path}${optionsStr}`;
+  }
+
+  /**
+   * Clears the image cache
+   */
+  public clearCache(): void {
+    this.imageCache.clear();
+  }
+
+  private normalizeSource(source: string): string {
+    return source;
+  }
+}
+
+function globalEnvironmentFallback(): Environment {
+  const maybeEnv = getGlobalEnvironment();
+  if (maybeEnv) return maybeEnv;
+
+  const hasProcess = typeof process !== "undefined" && !!process.versions?.node;
+  if (hasProcess) {
+    return new NodeEnvironment();
+  }
+
+  throw new Error("Environment not provided to ImageService and no global __PAGYRA_ENV__ set");
+}

package/src/image/jpeg-decoder.ts

@@ -0,0 +1,73 @@
+import type { ImageInfo } from "./types.js";
+import { BaseDecoder, type DecodeOptions } from "./base-decoder.js";
+
+/**
+ * Minimal JPEG parser that extracts metadata and returns the original bytes.
+ * The implementation does not perform full decoding; instead it surfaces the
+ * intrinsic dimensions found in the SOF0 marker so the layout engine can size
+ * the image correctly while keeping the compressed payload for embedding.
+ */
+export class JpegDecoder extends BaseDecoder {
+  private static readonly SOI_MARKER = 0xffd8;
+  private static readonly EOI_MARKER = 0xffd9;
+  private static readonly SOF0_MARKER = 0xffc0;
+
+  public async decode(
+    buffer: ArrayBuffer,
+    options: DecodeOptions = {},
+  ): Promise<ImageInfo> {
+    const view = new DataView(buffer);
+
+    if (view.getUint16(0, false) !== JpegDecoder.SOI_MARKER) {
+      throw new Error("Invalid JPEG: missing SOI marker");
+    }
+
+    let offset = 2;
+    let width = 0;
+    let height = 0;
+    let channels = 3;
+    let precision = 8;
+
+    while (offset + 4 < buffer.byteLength) {
+      const marker = view.getUint16(offset, false);
+      offset += 2;
+
+      if (marker === JpegDecoder.EOI_MARKER) {
+        break;
+      }
+
+      const length = view.getUint16(offset, false);
+
+      if (marker === JpegDecoder.SOF0_MARKER) {
+        precision = view.getUint8(offset + 2);
+        height = view.getUint16(offset + 3, false);
+        width = view.getUint16(offset + 5, false);
+        channels = view.getUint8(offset + 7);
+        break;
+      }
+
+      offset += length;
+    }
+
+    if (width === 0 || height === 0) {
+      throw new Error("Invalid JPEG: missing SOF0 marker");
+    }
+
+    const { targetWidth, targetHeight } = JpegDecoder.calculateDimensions(
+      width,
+      height,
+      options
+    );
+
+    const dataCopy = buffer.slice(0);
+
+    return {
+      width: targetWidth,
+      height: targetHeight,
+      format: "jpeg",
+      channels,
+      bitsPerChannel: precision,
+      data: dataCopy,
+    };
+  }
+}