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

package/dist/builtins/image-delivery.js

@@ -0,0 +1,115 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { generateThumbHash } from "ts-images";
+import { createImageDeliveryCatalog } from "ts-images/delivery";
+const RASTER_EXTENSIONS = new Set([".avif", ".jpeg", ".jpg", ".png", ".webp"]), DEFAULT_WIDTHS = [320, 640, 960, 1280, 1920], DELIVERY_URL = "/_stx/images";
+let deliveryCatalog = new Map;
+function publicUrl(relativePath) {
+  return `/${relativePath.split(path.sep).map(encodeURIComponent).join("/")}`;
+}
+function catalogName(relativePath) {
+  const extension = path.extname(relativePath), readable = relativePath.slice(0, -extension.length).replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, ""), pathHash = createHash("sha256").update(relativePath).digest("hex").slice(0, 8);
+  return `${readable || "image"}-${pathHash}`;
+}
+async function collectRasterImages(root, directory = root) {
+  const entries = await fs.promises.readdir(directory, { withFileTypes: !0 });
+  entries.sort((a, b) => a.name.localeCompare(b.name));
+  const files = [];
+  for (const entry of entries) {
+    const absolutePath = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await collectRasterImages(root, absolutePath));
+      continue;
+    }
+    if (!entry.isFile() || !RASTER_EXTENSIONS.has(path.extname(entry.name).toLowerCase()))
+      continue;
+    files.push({ absolutePath, relativePath: path.relative(root, absolutePath) });
+  }
+  return files;
+}
+function deliveryEntries(files) {
+  return files.map((file) => ({
+    key: publicUrl(file.relativePath),
+    input: file.absolutePath,
+    name: catalogName(file.relativePath)
+  }));
+}
+async function decodableFiles(files) {
+  const supported = [], concurrency = 8;
+  for (let offset = 0;offset < files.length; offset += concurrency) {
+    const batch = files.slice(offset, offset + concurrency), results = await Promise.all(batch.map(async (file) => {
+      try {
+        await generateThumbHash(file.absolutePath);
+        return file;
+      } catch {
+        console.warn(`[stx-images] Skipping unreadable raster: ${file.relativePath}`);
+        return null;
+      }
+    }));
+    supported.push(...results.filter((file) => file !== null));
+  }
+  return supported;
+}
+function normalizeLookupSource(src) {
+  if (!src || src.startsWith("data:") || src.startsWith("blob:") || /^https?:\/\//i.test(src) || src.startsWith("//"))
+    return;
+  const sourcePath = src.split(/[?#]/, 1)[0];
+  if (!sourcePath)
+    return;
+  try {
+    return `/${sourcePath.replace(/^\/+/, "").split("/").map(decodeURIComponent).map(encodeURIComponent).join("/")}`;
+  } catch {
+    return;
+  }
+}
+export function getImageDelivery(src) {
+  const key = normalizeLookupSource(src);
+  return key ? deliveryCatalog.get(key) : void 0;
+}
+export function clearImageDeliveryCatalog() {
+  deliveryCatalog = new Map;
+}
+export async function prepareImageDelivery(publicDir, outputDir) {
+  if (!publicDir || !fs.existsSync(publicDir)) {
+    clearImageDeliveryCatalog();
+    return { count: 0, fingerprint: "" };
+  }
+  const files = await collectRasterImages(publicDir);
+  if (files.length === 0) {
+    clearImageDeliveryCatalog();
+    return { count: 0, fingerprint: "" };
+  }
+  const catalogOptions = {
+    outDir: path.join(outputDir, "_stx", "images"),
+    baseUrl: DELIVERY_URL,
+    widths: DEFAULT_WIDTHS,
+    formats: ["avif", "webp"],
+    quality: { avif: 70, webp: 78, jpeg: 82, png: 100 },
+    includeOriginal: !1,
+    placeholder: !0,
+    batchConcurrency: 4,
+    concurrency: 4
+  };
+  let optimizedFiles = files, catalog;
+  try {
+    catalog = await createImageDeliveryCatalog({
+      ...catalogOptions,
+      entries: deliveryEntries(files)
+    });
+  } catch (error) {
+    optimizedFiles = await decodableFiles(files);
+    if (optimizedFiles.length === files.length)
+      throw error;
+    if (optimizedFiles.length === 0) {
+      clearImageDeliveryCatalog();
+      return { count: 0, fingerprint: "" };
+    }
+    catalog = await createImageDeliveryCatalog({
+      ...catalogOptions,
+      entries: deliveryEntries(optimizedFiles)
+    });
+  }
+  deliveryCatalog = new Map(Object.entries(catalog.entries));
+  return { count: optimizedFiles.length, fingerprint: catalog.fingerprint };
+}

package/dist/builtins/image-placeholder.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Real placeholders for `<StxImage>`, derived from the image's own pixels.
+ *
+ * `placeholder="blur"` used to render a flat grey rectangle — the same one for
+ * every image on the page, because the component had no way to look at the file
+ * it was pointing at. It renders synchronously; reading and decoding a JPEG does
+ * not. So the work moves earlier: the build warms a cache from disk, and the
+ * component reads it with a synchronous lookup.
+ *
+ * What lands in the HTML is a thumbhash (evanw/thumbhash) rendered as a blurred
+ * SVG mesh, with the image's average colour painted underneath it. Both are
+ * inline, so there is no second request and nothing to wait for — and no
+ * JavaScript, which is the point. A placeholder that needs a script has already
+ * lost to the image it was supposed to cover for.
+ *
+ * Size was the deciding constraint. thumbhash's own 32×32 PNG is ~4.2KB per
+ * image; nine of those roughly doubles a page here. The mesh below carries the
+ * same information as twelve colours and gzips against its neighbours, because
+ * every one of them is the same markup with different hex — about 480 bytes for
+ * nine images, against 3.3KB for the PNGs.
+ *
+ * @module builtins/image-placeholder
+ */
+/** A placeholder ready to be dropped into markup. */
+export interface ImagePlaceholder {
+    /** `data:image/svg+xml;base64,…` — the blurred mesh. */
+    dataUrl: string;
+    /** `#rrggbb` average, painted under the mesh and used alone as a fallback. */
+    color: string;
+}
+/**
+ * The placeholder for `src`, or undefined when there is none.
+ *
+ * Synchronous by requirement: builtin components render inside a synchronous
+ * pass. A miss is normal and never an error — an unwarmed build, an image
+ * outside the public directory, or a remote URL all land here, and the caller
+ * falls back to what it did before.
+ */
+export declare function getImagePlaceholder(src: string): ImagePlaceholder | undefined;
+/** Whether {@link warmImagePlaceholders} has run in this process. */
+export declare function placeholdersWarmed(): boolean;
+/** Drop everything, for tests and for a watch-mode rebuild. */
+export declare function clearImagePlaceholders(): void;
+/**
+ * Register a placeholder directly. Used by the warm below, and by tests that
+ * would rather not decode a real JPEG to check the markup.
+ */
+export declare function setImagePlaceholder(urlPath: string, placeholder: ImagePlaceholder): void;
+/**
+ * A blurred SVG mesh from decoded thumbhash pixels.
+ *
+ * Four by three is deliberate. It is enough cells to carry where the light and
+ * the subject are — which is all a placeholder has to say — and few enough that
+ * the markup stays shorter than the image it stands in for. The Gaussian blur
+ * does the rest, so the cell edges never show.
+ */
+export declare function meshSvg(rgba: Uint8Array | Uint8ClampedArray | number[], width: number, height: number, cols?: number, rows?: number): string;
+/** Base64 rather than percent-encoding: the same SVG, roughly 400 bytes shorter. */
+export declare function svgDataUrl(svg: string): string;
+export interface WarmOptions {
+    /** Where the on-disk cache lives. Omit to recompute every build. */
+    cachePath?: string;
+    /** Skip files larger than this. Decoding a 40MB source costs more than it returns. */
+    maxBytes?: number;
+    /** Stop after this many images, so an enormous asset tree cannot stall a build. */
+    limit?: number;
+}
+/**
+ * Derive placeholders for every image under `publicDir` and hold them for
+ * {@link getImagePlaceholder}.
+ *
+ * Called once per build, before any page renders. Failures are per-file and
+ * silent by design: a placeholder is decoration, and one unreadable image must
+ * not take a build down with it.
+ *
+ * Returns how many placeholders are available afterwards.
+ */
+export declare function warmImagePlaceholders(publicDir: string, options?: WarmOptions): Promise<number>;

package/dist/builtins/image-placeholder.js

@@ -0,0 +1,137 @@
+import fs from "node:fs";
+import path from "node:path";
+const IMAGE_EXTENSIONS = new Set([".jpg", ".jpeg", ".png", ".webp", ".avif"]), placeholders = new Map;
+let warmed = !1;
+export function getImagePlaceholder(src) {
+  if (!src)
+    return;
+  const clean = src.split("?")[0].split("#")[0];
+  return placeholders.get(clean);
+}
+export function placeholdersWarmed() {
+  return warmed;
+}
+export function clearImagePlaceholders() {
+  placeholders.clear();
+  warmed = !1;
+}
+export function setImagePlaceholder(urlPath, placeholder) {
+  placeholders.set(urlPath, placeholder);
+  warmed = !0;
+}
+function averageColor(rgba) {
+  let r = 0, g = 0, b = 0, n = 0;
+  for (let i = 0;i < rgba.length; i += 4) {
+    r += rgba[i];
+    g += rgba[i + 1];
+    b += rgba[i + 2];
+    n++;
+  }
+  if (n === 0)
+    return "#e5e7eb";
+  const hex = (v) => Math.round(v / n).toString(16).padStart(2, "0");
+  return `#${hex(r)}${hex(g)}${hex(b)}`;
+}
+export function meshSvg(rgba, width, height, cols = 4, rows = 3) {
+  const cells = [];
+  for (let y = 0;y < rows; y++)
+    for (let x = 0;x < cols; x++) {
+      const x0 = Math.floor(x * width / cols), x1 = Math.max(x0 + 1, Math.floor((x + 1) * width / cols)), y0 = Math.floor(y * height / rows), y1 = Math.max(y0 + 1, Math.floor((y + 1) * height / rows));
+      let r = 0, g = 0, b = 0, n = 0;
+      for (let yy = y0;yy < y1; yy++)
+        for (let xx = x0;xx < x1; xx++) {
+          const i = (yy * width + xx) * 4;
+          r += rgba[i];
+          g += rgba[i + 1];
+          b += rgba[i + 2];
+          n++;
+        }
+      const hex = (v) => Math.round(v / n).toString(16).padStart(2, "0");
+      cells.push(`<rect x="${x}" y="${y}" width="1" height="1" fill="#${hex(r)}${hex(g)}${hex(b)}"/>`);
+    }
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${cols} ${rows}" preserveAspectRatio="none"><filter id="b"><feGaussianBlur stdDeviation=".6"/></filter><g filter="url(#b)">${cells.join("")}</g></svg>`;
+}
+export function svgDataUrl(svg) {
+  return `data:image/svg+xml;base64,${Buffer.from(svg, "utf8").toString("base64")}`;
+}
+function readCache(cachePath) {
+  try {
+    return JSON.parse(fs.readFileSync(cachePath, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function writeCache(cachePath, cache) {
+  try {
+    fs.mkdirSync(path.dirname(cachePath), { recursive: !0 });
+    fs.writeFileSync(cachePath, JSON.stringify(cache));
+  } catch {}
+}
+function collectImages(dir, baseUrl, out = []) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: !0 });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      collectImages(full, `${baseUrl}/${entry.name}`, out);
+      continue;
+    }
+    if (!IMAGE_EXTENSIONS.has(path.extname(entry.name).toLowerCase()))
+      continue;
+    out.push([`${baseUrl}/${entry.name}`, full]);
+  }
+  return out;
+}
+export async function warmImagePlaceholders(publicDir, options = {}) {
+  const { cachePath, maxBytes = 33554432, limit = 2000 } = options;
+  if (!publicDir || !fs.existsSync(publicDir)) {
+    warmed = !0;
+    return placeholders.size;
+  }
+  let tsImages;
+  try {
+    tsImages = await import("ts-images");
+  } catch {
+    warmed = !0;
+    return placeholders.size;
+  }
+  const cache = cachePath ? readCache(cachePath) : {};
+  let cacheDirty = !1;
+  const images = collectImages(publicDir, "").slice(0, limit), CONCURRENCY = 8, derive = async ([urlPath, filePath]) => {
+    let stat;
+    try {
+      stat = fs.statSync(filePath);
+    } catch {
+      return;
+    }
+    if (stat.size > maxBytes)
+      return;
+    const cached = cache[urlPath];
+    if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+      placeholders.set(urlPath, { dataUrl: cached.dataUrl, color: cached.color });
+      return;
+    }
+    try {
+      const { hash } = await tsImages.generateThumbHash(filePath);
+      if (!hash)
+        return;
+      const { rgba, w, h } = tsImages.thumbHashToRGBA(hash), placeholder = {
+        dataUrl: svgDataUrl(meshSvg(rgba, w, h)),
+        color: averageColor(rgba)
+      };
+      placeholders.set(urlPath, placeholder);
+      cache[urlPath] = { mtimeMs: stat.mtimeMs, size: stat.size, ...placeholder };
+      cacheDirty = !0;
+    } catch {}
+  };
+  for (let i = 0;i < images.length; i += CONCURRENCY)
+    await Promise.all(images.slice(i, i + CONCURRENCY).map(derive));
+  if (cachePath && cacheDirty)
+    writeCache(cachePath, cache);
+  warmed = !0;
+  return placeholders.size;
+}

package/dist/builtins/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Builtin Components Barrel
+ *
+ * These are engine-level builtins that need deep template processing
+ * integration or inject runtime globals. Presentational UI components
+ * live in packages/components instead.
+ *
+ * @module builtins
+ */
+export { StxLinkBuiltin } from './stx-link';
+export { StxImageBuiltin } from './stx-image';
+export { SafeImageBuiltin } from './safe-image';
+export { StxLoadingIndicatorBuiltin } from './stx-loading-indicator';
+export { StxToastBuiltin } from './toast';
+export { StxModalBuiltin } from './modal';
+export { StxDrawerBuiltin } from './drawer';
+export { IconBuiltin, preloadIconCollection } from './icon';
+export { getTooltipRuntime } from './tooltip';
+export { SuspenseBuiltin } from './suspense';
+export { TransitionGroupBuiltin } from './transition-group';
+import type { ComponentRegistry } from '../component-registry';
+/**
+ * Register all builtin components with the supplied registry, or with the
+ * package singleton when no target is supplied.
+ */
+export declare function registerBuiltins(target?: ComponentRegistry): void;

package/dist/builtins/index.js

@@ -0,0 +1,34 @@
+export { StxLinkBuiltin } from "./stx-link.js";
+export { StxImageBuiltin } from "./stx-image.js";
+export { SafeImageBuiltin } from "./safe-image.js";
+export { StxLoadingIndicatorBuiltin } from "./stx-loading-indicator.js";
+export { StxToastBuiltin } from "./toast.js";
+export { StxModalBuiltin } from "./modal.js";
+export { StxDrawerBuiltin } from "./drawer.js";
+export { IconBuiltin, preloadIconCollection } from "./icon.js";
+export { getTooltipRuntime } from "./tooltip.js";
+export { SuspenseBuiltin } from "./suspense.js";
+export { TransitionGroupBuiltin } from "./transition-group.js";
+import { registry } from "../component-registry.js";
+import { StxLinkBuiltin } from "./stx-link.js";
+import { StxImageBuiltin } from "./stx-image.js";
+import { SafeImageBuiltin } from "./safe-image.js";
+import { StxLoadingIndicatorBuiltin } from "./stx-loading-indicator.js";
+import { StxToastBuiltin } from "./toast.js";
+import { StxModalBuiltin } from "./modal.js";
+import { StxDrawerBuiltin } from "./drawer.js";
+import { IconBuiltin } from "./icon.js";
+import { SuspenseBuiltin } from "./suspense.js";
+import { TransitionGroupBuiltin } from "./transition-group.js";
+export function registerBuiltins(target = registry) {
+  target.registerBuiltin(StxLinkBuiltin);
+  target.registerBuiltin(StxImageBuiltin);
+  target.registerBuiltin(SafeImageBuiltin);
+  target.registerBuiltin(StxLoadingIndicatorBuiltin);
+  target.registerBuiltin(StxToastBuiltin);
+  target.registerBuiltin(StxModalBuiltin);
+  target.registerBuiltin(StxDrawerBuiltin);
+  target.registerBuiltin(IconBuiltin);
+  target.registerBuiltin(SuspenseBuiltin);
+  target.registerBuiltin(TransitionGroupBuiltin);
+}

package/dist/builtins/modal.d.ts

@@ -0,0 +1,26 @@
+/**
+ * StxModal Builtin Component
+ *
+ * Renders a hidden modal dialog with slot content. Opened/closed via
+ * the runtime `modal.open(id)` / `modal.close(id)` globals.
+ *
+ * Usage:
+ *   <StxModal id="settings">
+ *     <h2>Settings</h2>
+ *     <p>Modal content here</p>
+ *   </StxModal>
+ *
+ *   <StxModal id="delete-confirm" size="sm" closeOnBackdrop="false">
+ *     <h3>Are you sure?</h3>
+ *   </StxModal>
+ *
+ * Props:
+ *   - id (required) — unique modal identifier
+ *   - size — 'sm' | 'md' | 'lg' | 'xl' | 'full' (default: 'md')
+ *   - closeOnBackdrop — whether clicking backdrop closes modal (default: true)
+ *   - closeOnEscape — whether Escape key closes modal (default: true)
+ *
+ * @module builtins/modal
+ */
+import type { BuiltinComponentDef } from '../component-registry';
+export declare const StxModalBuiltin: BuiltinComponentDef;

package/dist/builtins/modal.js

@@ -0,0 +1,38 @@
+import { escapeAttr } from "./escape.js";
+function resolveProp(props, key) {
+  if (props.serverDynamic[key] !== void 0)
+    return String(props.serverDynamic[key]);
+  const val = props.static[key];
+  if (typeof val === "string")
+    return val;
+  return;
+}
+const SIZE_WIDTHS = {
+  sm: "max-width:24rem",
+  md: "max-width:32rem",
+  lg: "max-width:42rem",
+  xl: "max-width:56rem",
+  full: "max-width:calc(100vw - 2rem);max-height:calc(100vh - 2rem)"
+};
+export const StxModalBuiltin = {
+  name: "StxModal",
+  aliases: ["stx-modal"],
+  render(props, slotContent, _ctx) {
+    const rawId = resolveProp(props, "id");
+    if (!rawId) {
+      console.warn('[stx] <StxModal> requires an "id" prop');
+      return "<!-- StxModal: missing id prop -->";
+    }
+    const id = escapeAttr(rawId), size = resolveProp(props, "size") || "md", closeOnBackdrop = resolveProp(props, "closeOnBackdrop") !== "false", closeOnEscape = resolveProp(props, "closeOnEscape") !== "false", maxWidth = SIZE_WIDTHS[size] || SIZE_WIDTHS.md;
+    return `<div id="stx-modal-${id}" class="stx-modal-backdrop" data-stx-modal="${id}" data-close-backdrop="${closeOnBackdrop}" data-close-escape="${closeOnEscape}" style="display:none;position:fixed;inset:0;z-index:99999;align-items:center;justify-content:center;background:rgba(0,0,0,0.5);backdrop-filter:blur(2px);opacity:0;transition:opacity 0.2s ease" aria-modal="true" role="dialog">
+  <div class="stx-modal-panel" style="${maxWidth};width:100%;margin:1rem;border-radius:0.75rem;box-shadow:0 20px 60px rgba(0,0,0,0.3);overflow:hidden;transform:scale(0.95) translateY(8px);transition:transform 0.2s ease,opacity 0.2s ease;opacity:0;background:var(--stx-modal-bg,#fff);color:var(--stx-modal-text,#1f2937)">
+    <div style="padding:1.5rem">${slotContent}</div>
+  </div>
+</div>
+<style>
+@media(prefers-color-scheme:dark){[data-stx-modal]{--stx-modal-bg:#1f2937;--stx-modal-text:#f3f4f6}}
+.stx-modal-backdrop[data-stx-modal-open]{display:flex!important;opacity:1}
+.stx-modal-backdrop[data-stx-modal-open] .stx-modal-panel{transform:scale(1) translateY(0);opacity:1}
+</style>`;
+  }
+};

package/dist/builtins/safe-image.d.ts

@@ -0,0 +1,44 @@
+/**
+ * SafeImage Builtin Component
+ *
+ * Drop-in `<img>` replacement with a declarative broken-image fallback.
+ * Third-party image URLs (external-CDN avatars, user content that gets
+ * deleted, seed data pointing at links that 404) fail frequently in
+ * production; without intervention the browser draws the alt text inside
+ * whatever layout frame the `<img>` had — round avatar frames in
+ * particular look broken.
+ *
+ * SafeImage wires an inline `onerror=` handler that swaps to a fallback
+ * image (and optionally swaps the class string) when the primary src
+ * fails to load.
+ *
+ * Usage:
+ *   <SafeImage src="/avatars/u.png" alt="User" fallback="/avatars/default.svg" />
+ *   <SafeImage :src="judge.photo" :alt="judge.name"
+ *              className="h-12 w-12 rounded-full grayscale filter"
+ *              fallbackClassName="h-12 w-12 rounded-full"
+ *              fallback="/images/avatars/default-judge.svg" />
+ *
+ * Why inline `onerror=` rather than a delegated capture-phase listener:
+ * `error` events don't bubble, so a listener attached by a component's
+ * `<script client>` IIFE runs AFTER the element's first load attempt —
+ * cached 404s and offline first paint slip past it. The inline HTML
+ * `onerror=` attribute is parsed-and-attached synchronously with the
+ * element by the browser's HTML parser, before the image request fires.
+ * That's the only race-free option for the error path.
+ *
+ * Why a single window-level handler rather than per-instance inline
+ * closures: keeps rendered HTML small (a ~35-byte attribute vs. a
+ * ~120-byte inline function body per `<img>`). The handler is emitted
+ * once per page render (gated on a render-context flag) and registered
+ * once per browser session (gated on the `window.__stxSafeImageHandler`
+ * existence check, so it's also idempotent across SPA navigation).
+ * Per-instance config travels via `data-*` attributes, so the handler
+ * stays stateless.
+ *
+ * Resolves stacksjs/stx#1732.
+ *
+ * @module builtins/safe-image
+ */
+import type { BuiltinComponentDef } from '../component-registry';
+export declare const SafeImageBuiltin: BuiltinComponentDef;

package/dist/builtins/safe-image.js

@@ -0,0 +1,45 @@
+import { forwardResolvedAttrs, forwardStaticAttrs } from "./attrs.js";
+const DEFAULT_FALLBACK = "/images/safe-image-default.svg";
+function escapeAttr(value) {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function resolveProp(props, key) {
+  if (props.serverDynamic[key] !== void 0)
+    return String(props.serverDynamic[key]);
+  const val = props.static[key];
+  if (typeof val === "string")
+    return val;
+  return;
+}
+const HANDLER_SCRIPT = `<script>window.__stxSafeImageHandler||(window.__stxSafeImageHandler=function(i){if(i.__stx_fb)return;i.__stx_fb=1;var f=i.getAttribute('data-fallback')||'${DEFAULT_FALLBACK}';var c=i.getAttribute('data-fallback-class');i.src=f;if(c)i.className=c;});</script>`;
+export const SafeImageBuiltin = {
+  name: "SafeImage",
+  aliases: ["safe-image", "safe-img"],
+  render(props, _slotContent, ctx) {
+    const src = resolveProp(props, "src") || "", alt = resolveProp(props, "alt") || "", fallback = resolveProp(props, "fallback") || DEFAULT_FALLBACK, className = resolveProp(props, "class") || resolveProp(props, "className") || "", fallbackClassName = resolveProp(props, "fallbackClassName") || "", imgAttrs = [];
+    imgAttrs.push(`src="${escapeAttr(src)}"`);
+    imgAttrs.push(`alt="${escapeAttr(alt)}"`);
+    if (className)
+      imgAttrs.push(`class="${escapeAttr(className)}"`);
+    imgAttrs.push(`data-fallback="${escapeAttr(fallback)}"`);
+    if (fallbackClassName)
+      imgAttrs.push(`data-fallback-class="${escapeAttr(fallbackClassName)}"`);
+    imgAttrs.push('onerror="window.__stxSafeImageHandler(this)"');
+    const consumed = new Set([
+      "src",
+      "alt",
+      "fallback",
+      "class",
+      "className",
+      "fallbackClassName"
+    ]);
+    imgAttrs.push(...forwardStaticAttrs(props, consumed));
+    imgAttrs.push(...forwardResolvedAttrs(props, consumed));
+    const imgTag = `<img ${imgAttrs.join(" ")} />`, renderCtx = ctx.context;
+    if (!renderCtx.__safeImageHandlerEmitted) {
+      renderCtx.__safeImageHandlerEmitted = !0;
+      return `${HANDLER_SCRIPT}${imgTag}`;
+    }
+    return imgTag;
+  }
+};

package/dist/builtins/stx-image.d.ts

@@ -0,0 +1,29 @@
+/**
+ * StxImage Builtin Component
+ *
+ * Full-featured image component matching NuxtImage capabilities:
+ *
+ * - Auto `loading="lazy"` + `decoding="async"`
+ * - Responsive `srcset` + `sizes` auto-generation from breakpoints
+ * - Density descriptors (`1x`, `2x`, `3x`)
+ * - `<picture>` wrapper with format negotiation (avif, webp fallback)
+ * - Blur-up / color / empty placeholder modes
+ * - Aspect ratio preservation (CLS prevention)
+ * - Preload hint injection (`<link rel="preload">`)
+ * - CDN provider support (Cloudinary, imgix, custom)
+ *
+ * Usage:
+ *   <StxImage src="/images/hero.jpg" alt="Hero" />
+ *   <StxImage src="/images/hero.jpg" alt="Hero" width="800" height="600" />
+ *   <StxImage src="/images/hero.jpg" alt="Hero" sizes="sm:100vw md:50vw lg:33vw" />
+ *   <StxImage src="/images/hero.jpg" alt="Hero" densities="1x 2x" />
+ *   <StxImage src="/images/hero.jpg" alt="Hero" format="webp" />
+ *   <StxImage src="/images/hero.jpg" alt="Hero" placeholder="blur" />
+ *   <StxImage src="/images/hero.jpg" alt="Hero" placeholder="thumbhash" />
+ *   <StxImage src="/images/hero.jpg" alt="Hero" preload />
+ *   <StxImage src="/images/hero.jpg" alt="Hero" provider="cloudinary" />
+ *
+ * @module builtins/stx-image
+ */
+import type { BuiltinComponentDef } from '../component-registry';
+export declare const StxImageBuiltin: BuiltinComponentDef;