@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/image-optimization/auto-sibling.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Auto-Sibling Image Discovery
+ *
+ * NuxtImage-style sugar: if a `.webp` (or `.avif`) sits next to a `.jpg`/
+ * `.png` on disk, rewrite plain `<img src="hero.jpg">` into
+ *
+ *   <picture>
+ *     <source type="image/avif" srcset="/images/hero.avif">
+ *     <source type="image/webp" srcset="/images/hero.webp">
+ *     <img src="/images/hero.jpg" alt="…">
+ *   </picture>
+ *
+ * No consumer change required — drop the optimized format next to the
+ * original asset and capable browsers pick it up.
+ *
+ * Skipped intentionally:
+ *   - `<img>` already inside a `<picture>` (don't double-wrap)
+ *   - Remote URLs (http://, https://, protocol-relative `//cdn/…`)
+ *   - data: URIs
+ *   - sources whose extension isn't a known raster format
+ *   - images whose resolved path is outside `publicDir` (we don't probe
+ *     arbitrary paths on disk)
+ */
+export interface AutoSiblingOptions {
+    /** Filesystem root for resolving src URLs (typically the stx config's `publicDir`). */
+    publicDir: string;
+    /** Sibling formats to probe for, in priority order (most-preferred first). */
+    formats?: Array<{
+        ext: string;
+        mime: string;
+    }>;
+}
+/**
+ * Scan `html` for plain `<img>` tags whose src resolves to a real file
+ * inside `publicDir`, probe for sibling-format files (e.g. `hero.webp`
+ * next to `hero.jpg`), and wrap matches in `<picture>` with `<source>`
+ * entries for each sibling that actually exists on disk.
+ *
+ * Returns the rewritten HTML. If no `<img>` matches or no siblings are
+ * found, returns the input unchanged (no allocations beyond the scan).
+ */
+export declare function rewriteImagesWithSiblings(html: string, options: AutoSiblingOptions): Promise<string>;

package/dist/image-optimization/auto-sibling.js

@@ -0,0 +1,88 @@
+import path from "node:path";
+const RASTER_EXTS = new Set([".jpg", ".jpeg", ".png", ".gif"]), DEFAULT_FORMATS = [
+  { ext: ".avif", mime: "image/avif" },
+  { ext: ".webp", mime: "image/webp" }
+];
+export async function rewriteImagesWithSiblings(html, options) {
+  const formats = options.formats ?? DEFAULT_FORMATS;
+  if (!options.publicDir)
+    return html;
+  const pictureRanges = collectPictureRanges(html), patches = [], imgRe = /<img\b[^>]*?>/gi, matches = [];
+  let m;
+  while ((m = imgRe.exec(html)) !== null) {
+    const raw = m[0], srcMatch = raw.match(/\bsrc=["']([^"']+)["']/i);
+    if (!srcMatch)
+      continue;
+    if (isInsideRange(m.index, pictureRanges))
+      continue;
+    matches.push({ idx: m.index, length: raw.length, src: srcMatch[1], raw });
+  }
+  if (matches.length === 0)
+    return html;
+  const probes = await Promise.all(matches.map(async (match) => {
+    const sources = await findSiblings(match.src, options.publicDir, formats);
+    return { match, sources };
+  }));
+  for (const { match, sources } of probes) {
+    if (sources.length === 0)
+      continue;
+    const replacement = `<picture>${sources.map((s) => `<source type="${s.mime}" srcset="${escapeAttr(s.url)}">`).join("")}${match.raw}</picture>`;
+    patches.push({ start: match.idx, end: match.idx + match.length, replacement });
+  }
+  if (patches.length === 0)
+    return html;
+  let out = "", cursor = 0;
+  for (const p of patches) {
+    out += html.slice(cursor, p.start);
+    out += p.replacement;
+    cursor = p.end;
+  }
+  out += html.slice(cursor);
+  return out;
+}
+async function findSiblings(srcUrl, publicDir, formats) {
+  if (!shouldProbe(srcUrl))
+    return [];
+  const ext = path.extname(srcUrl).toLowerCase();
+  if (!RASTER_EXTS.has(ext))
+    return [];
+  if (!srcUrl.startsWith("/"))
+    return [];
+  const fsBase = path.join(publicDir, srcUrl.slice(1)), fsDir = path.dirname(fsBase), fsBaseName = path.basename(fsBase, ext), resolvedDir = path.resolve(fsDir), resolvedPublic = path.resolve(publicDir);
+  if (!resolvedDir.startsWith(resolvedPublic))
+    return [];
+  const urlDir = path.posix.dirname(srcUrl), checks = formats.map(async (fmt) => {
+    const siblingPath = path.join(fsDir, `${fsBaseName}${fmt.ext}`);
+    if (!await Bun.file(siblingPath).exists())
+      return null;
+    return { url: path.posix.join(urlDir, `${fsBaseName}${fmt.ext}`), mime: fmt.mime };
+  });
+  return (await Promise.all(checks)).filter((s) => s !== null);
+}
+function shouldProbe(srcUrl) {
+  if (!srcUrl)
+    return !1;
+  if (srcUrl.startsWith("http://") || srcUrl.startsWith("https://"))
+    return !1;
+  if (srcUrl.startsWith("//"))
+    return !1;
+  if (srcUrl.startsWith("data:"))
+    return !1;
+  return !0;
+}
+function collectPictureRanges(html) {
+  const ranges = [], re = /<picture\b[^>]*>[\s\S]*?<\/picture>/gi;
+  let m;
+  while ((m = re.exec(html)) !== null)
+    ranges.push([m.index, m.index + m[0].length]);
+  return ranges;
+}
+function isInsideRange(idx, ranges) {
+  for (const [start, end] of ranges)
+    if (idx >= start && idx < end)
+      return !0;
+  return !1;
+}
+function escapeAttr(value) {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+}

package/dist/image-optimization/build-plugin.d.ts

@@ -0,0 +1,54 @@
+import { type ImageOptions, type ImageFormat, type ProcessedImage, type ImageVariant } from './processor';
+import type { BuildPlugin } from '../production-build';
+/**
+ * Create the image optimization build plugin
+ */
+export declare function createImagePlugin(options?: ImageBuildOptions): BuildPlugin;
+/**
+ * Optimize a single image
+ */
+export declare function optimizeImage(inputPath: string, outputDir: string, options?: ImageOptions): Promise<ProcessedImage>;
+/**
+ * Optimize all images in a directory
+ // eslint-disable-next-line pickier/no-unused-vars
+ */
+export declare function optimizeDirectory(inputDir: string, outputDir: string, options?: ImageBuildOptions): Promise<{
+  processed: ProcessedImage[]
+  stats: ImageBuildContext['stats']
+}>;
+/**
+ * Generate image manifest for build
+ */
+export declare function generateImageManifest(images: ProcessedImage[]): Record<string, { variants: ImageVariant[]; placeholder?: string }>;
+/**
+ * Write image manifest to file
+ */
+export declare function writeImageManifest(images: ProcessedImage[], outputPath: string): Promise<void>;
+// ============================================================================
+// Types
+// ============================================================================
+export declare interface ImageBuildOptions {
+  inputDirs?: string[]
+  outputDir?: string
+  baseUrl?: string
+  defaults?: ImageOptions
+  cache?: boolean
+  cacheDir?: string
+  concurrency?: number
+  referencedOnly?: boolean
+  formats?: ImageFormat[]
+  widths?: number[]
+  quality?: number
+  placeholder?: 'blur' | 'dominant-color' | 'none'
+  verbose?: boolean
+}
+export declare interface ImageBuildContext {
+  imageReferences: Set<string>
+  processedImages: Map<string, ProcessedImage>
+  stats: {
+    totalImages: number
+    optimizedImages: number
+    savedBytes: number
+    variants: number
+  }
+}

package/dist/image-optimization/build-plugin.js

@@ -0,0 +1,241 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  DEFAULT_FORMATS,
+  DEFAULT_QUALITY,
+  DEFAULT_WIDTHS,
+  processImage,
+  isImageFile,
+  isImageBackendAvailable,
+  isSharpAvailable,
+  formatSize,
+  getTotalSize
+} from "./processor.js";
+export function createImagePlugin(options = {}) {
+  const {
+    inputDirs = ["public", "src/assets", "assets"],
+    outputDir = "dist/images",
+    baseUrl = "/images",
+    formats = DEFAULT_FORMATS,
+    widths = DEFAULT_WIDTHS,
+    quality = DEFAULT_QUALITY,
+    placeholder = "none",
+    concurrency = 4,
+    cache = !0,
+    cacheDir = ".stx/image-cache",
+    referencedOnly = !1,
+    verbose = !1
+  } = options, ctx = {
+    imageReferences: new Set,
+    processedImages: new Map,
+    stats: {
+      totalImages: 0,
+      optimizedImages: 0,
+      savedBytes: 0,
+      variants: 0
+    }
+  };
+  return {
+    name: "stx-image-optimization",
+    async setup(build) {
+      if (!await isImageBackendAvailable()) {
+        console.warn("[stx-images] no image backend available, optimization disabled");
+        return;
+      }
+      if (cache)
+        await fs.promises.mkdir(cacheDir, { recursive: !0 });
+      if (verbose) {
+        const hasSharp = await isSharpAvailable();
+        console.log("[stx-images] Plugin initialized");
+        console.log(`  Backend: ${hasSharp ? "sharp (native fast path) + ts-images" : "ts-images (pure TS)"}`);
+        console.log(`  Input dirs: ${inputDirs.join(", ")}`);
+        console.log(`  Output dir: ${outputDir}`);
+        console.log(`  Formats: ${formats.join(", ")}`);
+        console.log(`  Widths: ${widths.join(", ")}`);
+      }
+    },
+    async buildStart() {
+      ctx.imageReferences.clear();
+      ctx.processedImages.clear();
+      ctx.stats = {
+        totalImages: 0,
+        optimizedImages: 0,
+        savedBytes: 0,
+        variants: 0
+      };
+    },
+    async transform(code, id) {
+      if (id.endsWith(".html") || id.endsWith(".stx")) {
+        const refs = extractImageReferences(code);
+        for (const ref of refs)
+          ctx.imageReferences.add(ref);
+      }
+      if (code.includes("<Image") || code.includes("@image"))
+        return await transformImageReferences(code, {
+          formats,
+          widths,
+          quality,
+          placeholder,
+          outputDir,
+          baseUrl,
+          processedImages: ctx.processedImages
+        });
+      return code;
+    },
+    async buildEnd(result) {
+      if (!await isImageBackendAvailable())
+        return;
+      await fs.promises.mkdir(outputDir, { recursive: !0 });
+      const imagesToProcess = [];
+      for (const dir of inputDirs) {
+        if (!fs.existsSync(dir))
+          continue;
+        const images = await collectImages(dir);
+        imagesToProcess.push(...images);
+      }
+      const finalImages = referencedOnly ? imagesToProcess.filter((img) => isImageReferenced(img, ctx.imageReferences)) : imagesToProcess;
+      ctx.stats.totalImages = finalImages.length;
+      if (verbose)
+        console.log(`[stx-images] Processing ${finalImages.length} images...`);
+      const chunks = chunkArray(finalImages, concurrency);
+      for (const chunk of chunks)
+        await Promise.all(chunk.map(async (imagePath) => {
+          try {
+            const processed = await processImage(imagePath, {
+              formats,
+              widths,
+              quality,
+              placeholder,
+              outputDir,
+              baseUrl
+            });
+            ctx.processedImages.set(imagePath, processed);
+            ctx.stats.optimizedImages++;
+            ctx.stats.variants += processed.variants.length;
+            const originalSize = fs.statSync(imagePath).size, optimizedSize = getTotalSize(processed.variants);
+            ctx.stats.savedBytes += Math.max(0, originalSize - optimizedSize / processed.variants.length);
+            if (verbose)
+              console.log(`  \u2713 ${path.basename(imagePath)} \u2192 ${processed.variants.length} variants`);
+          } catch (error) {
+            console.error(`[stx-images] Error processing ${imagePath}:`, error);
+          }
+        }));
+      console.log("[stx-images] Optimization complete:");
+      console.log(`  Images: ${ctx.stats.optimizedImages}/${ctx.stats.totalImages}`);
+      console.log(`  Variants: ${ctx.stats.variants}`);
+      if (ctx.stats.savedBytes > 0)
+        console.log(`  Saved: ~${formatSize(ctx.stats.savedBytes)}`);
+    }
+  };
+}
+function extractImageReferences(content) {
+  const refs = [], srcPattern = /src=["']([^"']+\.(jpg|jpeg|png|webp|avif|gif))["']/gi;
+  let match;
+  while ((match = srcPattern.exec(content)) !== null)
+    refs.push(match[1]);
+  const imageCompPattern = /<Image[^>]+src=["']([^"']+)["']/gi;
+  while ((match = imageCompPattern.exec(content)) !== null)
+    refs.push(match[1]);
+  const directivePattern = /@image\s*\(\s*['"]([^'"]+)['"]/gi;
+  while ((match = directivePattern.exec(content)) !== null)
+    refs.push(match[1]);
+  const bgPattern = /background(?:-image)?:\s*url\(["']?([^"')]+\.(jpg|jpeg|png|webp|avif|gif))["']?\)/gi;
+  while ((match = bgPattern.exec(content)) !== null)
+    refs.push(match[1]);
+  return refs;
+}
+function isImageReferenced(imagePath, references) {
+  const basename = path.basename(imagePath);
+  for (const ref of references)
+    if (ref.endsWith(basename) || ref.includes(basename))
+      return !0;
+  return !1;
+}
+async function transformImageReferences(content, options) {
+  return content;
+}
+async function collectImages(dir) {
+  const images = [];
+  async function walk(currentDir) {
+    const entries = await fs.promises.readdir(currentDir, { withFileTypes: !0 });
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+      if (entry.isDirectory())
+        await walk(fullPath);
+      else if (entry.isFile() && isImageFile(fullPath))
+        images.push(fullPath);
+    }
+  }
+  await walk(dir);
+  return images;
+}
+function chunkArray(array, size) {
+  const chunks = [];
+  for (let i = 0;i < array.length; i += size)
+    chunks.push(array.slice(i, i + size));
+  return chunks;
+}
+export async function optimizeImage(inputPath, outputDir, options = {}) {
+  if (!await isImageBackendAvailable())
+    throw Error("No image backend available \u2014 install sharp or ensure ts-images is bundled");
+  return processImage(inputPath, {
+    ...options,
+    outputDir
+  });
+}
+export async function optimizeDirectory(inputDir, outputDir, options = {}) {
+  const {
+    formats = DEFAULT_FORMATS,
+    widths = DEFAULT_WIDTHS,
+    quality = DEFAULT_QUALITY,
+    placeholder = "none",
+    concurrency = 4,
+    verbose = !1
+  } = options;
+  if (!await isImageBackendAvailable())
+    throw Error("No image backend available \u2014 install sharp or ensure ts-images is bundled");
+  await fs.promises.mkdir(outputDir, { recursive: !0 });
+  const images = await collectImages(inputDir), processed = [], stats = {
+    totalImages: images.length,
+    optimizedImages: 0,
+    savedBytes: 0,
+    variants: 0
+  }, chunks = chunkArray(images, concurrency);
+  for (const chunk of chunks) {
+    const results = await Promise.all(chunk.map(async (imagePath) => {
+      try {
+        const result = await processImage(imagePath, {
+          formats,
+          widths,
+          quality,
+          placeholder,
+          outputDir,
+          baseUrl: "/"
+        });
+        stats.optimizedImages++;
+        stats.variants += result.variants.length;
+        if (verbose)
+          console.log(`  \u2713 ${path.basename(imagePath)}`);
+        return result;
+      } catch (error) {
+        console.error(`Error processing ${imagePath}:`, error);
+        return null;
+      }
+    }));
+    processed.push(...results.filter((r) => r !== null));
+  }
+  return { processed, stats };
+}
+export function generateImageManifest(images) {
+  const manifest = {};
+  for (const img of images)
+    manifest[img.src] = {
+      variants: img.variants,
+      placeholder: img.placeholder
+    };
+  return manifest;
+}
+export async function writeImageManifest(images, outputPath) {
+  const manifest = generateImageManifest(images);
+  await Bun.write(outputPath, JSON.stringify(manifest, null, 2));
+}

package/dist/image-optimization/component.d.ts

@@ -0,0 +1,46 @@
+import { type ImageFormat, type ImageVariant, type ProcessedImage } from './processor';
+/**
+ * Render an optimized <Image> component
+ */
+export declare function renderImageComponent(props: ImageComponentProps, context?: ImageRenderContext): ImageRenderResult;
+/**
+ * Parse Image component from template
+ */
+export declare function parseImageComponent(content: string): ImageComponentProps | null;
+/**
+ * Process Image components in template content
+ */
+export declare function processImageComponents(content: string, processor: (props: ImageComponentProps) => Promise<ImageRenderResult>): Promise<{ html: string; preloadLinks: string[]; styles: string[] }>;
+// ============================================================================
+// Types
+// ============================================================================
+export declare interface ImageComponentProps {
+  src: string
+  alt: string
+  width?: number | string
+  height?: number | string
+  sizes?: string | Record<string, string>
+  loading?: 'lazy' | 'eager'
+  priority?: boolean
+  quality?: number
+  placeholder?: 'blur' | 'color' | 'thumbhash' | 'none'
+  formats?: ImageFormat[]
+  widths?: number[]
+  class?: string
+  style?: string
+  decoding?: 'sync' | 'async' | 'auto'
+  fetchpriority?: 'high' | 'low' | 'auto'
+  objectFit?: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down'
+  objectPosition?: string
+}
+export declare interface ImageRenderContext {
+  processedImage?: ProcessedImage
+  variants?: ImageVariant[]
+  optimize?: boolean
+  isDev?: boolean
+}
+export declare interface ImageRenderResult {
+  html: string
+  preloadLink?: string
+  placeholderCss?: string
+}