@joycostudio/iris 0.0.0-stage → 0.0.1

package/dist/react.js

@@ -0,0 +1,611 @@
+"use client";
+
+// packages/react/index.tsx
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useState as useState2
+} from "react";
+
+// packages/browser/index.ts
+function inspectImageElement(image, manifest = {}, lcpElements = /* @__PURE__ */ new Set(), timing = null) {
+  const rect = image.getBoundingClientRect();
+  const renderedWidth = image.clientWidth || rect.width;
+  const renderedHeight = image.clientHeight || rect.height;
+  const id = image.dataset.iris || image.currentSrc || image.src;
+  const source = manifest[image.dataset.irisSrc || id] ?? manifest[id] ?? manifest[image.currentSrc] ?? manifest[image.src] ?? null;
+  const candidates = parseSrcSet(image.srcset, renderedWidth);
+  const selectedUrl = image.currentSrc || image.src;
+  const selectedWidth = selectedCandidateWidth(selectedUrl, candidates);
+  const dpr = window.devicePixelRatio || 1;
+  const idealWidth = Math.ceil(renderedWidth * dpr);
+  const declaredSlotWidth = resolveSizes(image.sizes);
+  const resource = resourceTiming(selectedUrl);
+  const diagnostics = diagnoseRuntime({
+    source,
+    renderedWidth,
+    renderedHeight,
+    visualWidth: rect.width,
+    visualHeight: rect.height,
+    idealWidth,
+    selectedWidth,
+    availableWidths: candidates.map((candidate) => candidate.width),
+    declaredSlotWidth,
+    objectFit: getComputedStyle(image).objectFit
+  });
+  return {
+    id,
+    source,
+    renderedWidth,
+    renderedHeight,
+    visualWidth: rect.width,
+    visualHeight: rect.height,
+    naturalWidth: image.naturalWidth,
+    dpr,
+    idealWidth,
+    selectedWidth,
+    selectedUrl,
+    availableWidths: candidates.map((candidate) => candidate.width),
+    declaredSizes: image.sizes,
+    declaredSlotWidth,
+    loading: image.loading,
+    objectFit: getComputedStyle(image).objectFit,
+    transferBytes: resource?.transferSize ?? null,
+    duration: resource?.duration ?? null,
+    timing,
+    isLcp: lcpElements.has(image),
+    diagnostics
+  };
+}
+function createIrisDebugger(options = {}) {
+  const reports = /* @__PURE__ */ new Map();
+  const lcpElements = /* @__PURE__ */ new Set();
+  let mutationObserver = null;
+  let resizeObserver = null;
+  let performanceObserver = null;
+  let frame = 0;
+  let tableTimer = null;
+  let lastTableSignature = "";
+  const pending = /* @__PURE__ */ new Set();
+  const timelines = /* @__PURE__ */ new WeakMap();
+  const selector = options.scope === "document" ? "img" : "img[data-iris]";
+  const measure = (image) => {
+    const report2 = inspectImageElement(
+      image,
+      options.manifest,
+      lcpElements,
+      timelines.get(image) ?? null
+    );
+    reports.set(image, report2);
+    scheduleTable();
+  };
+  const table = () => logReportTable(report(), options.console ?? "warnings");
+  const scheduleTable = () => {
+    if (options.console === "silent") return;
+    if (tableTimer) clearTimeout(tableTimer);
+    tableTimer = setTimeout(() => {
+      tableTimer = null;
+      const signature = reportSignature(report());
+      if (signature === lastTableSignature) return;
+      lastTableSignature = signature;
+      table();
+    }, 250);
+  };
+  const schedule = (image) => {
+    pending.add(image);
+    if (frame) return;
+    frame = requestAnimationFrame(() => {
+      frame = 0;
+      for (const pendingImage of pending) measure(pendingImage);
+      pending.clear();
+    });
+  };
+  const observe = (root = document) => {
+    resizeObserver = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        if (entry.target instanceof HTMLImageElement) schedule(entry.target);
+      }
+    });
+    const register = (image) => {
+      resizeObserver?.observe(image);
+      image.addEventListener("load", () => schedule(image), { once: true });
+      if (image.complete) schedule(image);
+    };
+    root.querySelectorAll(selector).forEach(register);
+    mutationObserver = new MutationObserver((records) => {
+      for (const record of records) {
+        for (const node of record.addedNodes) {
+          if (!(node instanceof Element)) continue;
+          if (node.matches(selector)) register(node);
+          node.querySelectorAll(selector).forEach(register);
+        }
+      }
+    });
+    mutationObserver.observe(root, { childList: true, subtree: true });
+    if (typeof PerformanceObserver !== "undefined") {
+      performanceObserver = new PerformanceObserver((list) => {
+        for (const entry of list.getEntries()) {
+          const element = entry.element;
+          if (element) {
+            lcpElements.add(element);
+            if (element instanceof HTMLImageElement) schedule(element);
+          }
+        }
+      });
+      try {
+        performanceObserver.observe({
+          type: "largest-contentful-paint",
+          buffered: true
+        });
+      } catch {
+        performanceObserver = null;
+      }
+    }
+    return api;
+  };
+  const disconnect = () => {
+    mutationObserver?.disconnect();
+    resizeObserver?.disconnect();
+    performanceObserver?.disconnect();
+    cancelAnimationFrame(frame);
+    if (tableTimer) clearTimeout(tableTimer);
+    tableTimer = null;
+    frame = 0;
+    pending.clear();
+  };
+  const report = () => [...reports.values()];
+  const startTimeline = (image) => {
+    timelines.set(image, {
+      blurMs: null,
+      previewMs: null,
+      finalMs: null,
+      startedAt: null,
+      previewAt: null,
+      finalAt: null
+    });
+  };
+  const markPreview = (image, preview, at = performance.now()) => {
+    const timing = timelines.get(image);
+    if (!timing) return;
+    timing.startedAt = resourceTiming(preview.currentSrc || preview.src)?.startTime ?? at;
+    timing.previewAt = at;
+    timing.blurMs = roundDuration(at - timing.startedAt);
+    schedule(image);
+  };
+  const markFinal = (image, at = performance.now()) => {
+    const timing = timelines.get(image);
+    if (!timing) return;
+    const finalStartedAt = resourceTiming(image.currentSrc || image.src)?.startTime ?? at;
+    timing.finalAt = at;
+    timing.finalMs = roundDuration(at - finalStartedAt);
+    if (timing.previewAt === null) {
+      timing.startedAt = finalStartedAt;
+      timing.blurMs = timing.finalMs;
+    } else timing.previewMs = roundDuration(at - timing.previewAt);
+    schedule(image);
+  };
+  const summary = () => ({
+    inspected: reports.size,
+    healthy: report().filter((item) => item.diagnostics.length === 0).length,
+    warnings: report().flatMap((item) => item.diagnostics).filter((item) => item.severity === "warning").length,
+    errors: report().flatMap((item) => item.diagnostics).filter((item) => item.severity === "error").length
+  });
+  const api = {
+    observe,
+    disconnect,
+    report,
+    table,
+    summary,
+    startTimeline,
+    markPreview,
+    markFinal
+  };
+  return api;
+}
+function roundDuration(value) {
+  return Math.round(value * 10) / 10;
+}
+function resourceTiming(url) {
+  const normalized = normalizeUrl(url);
+  const entries = performance.getEntriesByType(
+    "resource"
+  );
+  for (let index = entries.length - 1; index >= 0; index--) {
+    if (normalizeUrl(entries[index].name) === normalized) return entries[index];
+  }
+  return void 0;
+}
+function parseSrcSet(srcset, renderedWidth) {
+  return srcset.split(",").map((value) => value.trim().split(/\s+/)).map(([url, descriptor]) => ({
+    url,
+    width: descriptor?.endsWith("w") ? Number.parseInt(descriptor, 10) : descriptor?.endsWith("x") ? Math.round(Number.parseFloat(descriptor) * renderedWidth) : 0
+  })).filter((candidate) => candidate.url && candidate.width > 0);
+}
+function selectedCandidateWidth(selectedUrl, candidates) {
+  const selected = normalizeUrl(selectedUrl);
+  const candidate = candidates.find(
+    (item) => normalizeUrl(item.url) === selected
+  );
+  if (candidate) return candidate.width;
+  const queryWidth = new URL(
+    selectedUrl,
+    window.location.href
+  ).searchParams.get("w");
+  return queryWidth ? Number(queryWidth) : null;
+}
+function normalizeUrl(url) {
+  try {
+    return new URL(url, window.location.href).href;
+  } catch {
+    return url;
+  }
+}
+function diagnoseRuntime(input) {
+  const diagnostics = [];
+  if (input.visualWidth !== void 0 && input.renderedWidth > 0 && Math.abs(input.visualWidth - input.renderedWidth) / input.renderedWidth > 0.02) {
+    diagnostics.push(
+      runtimeDiagnostic(
+        "css-transform-affects-visual-size",
+        "info",
+        "high",
+        "A CSS transform changes the visual width; responsive selection still uses the untransformed layout slot.",
+        {
+          renderedWidth: input.renderedWidth,
+          visualWidth: input.visualWidth
+        }
+      )
+    );
+  }
+  if (input.declaredSlotWidth && input.renderedWidth > 0) {
+    const pixelDifference = input.declaredSlotWidth - input.renderedWidth;
+    const difference = pixelDifference / input.renderedWidth;
+    const isMaterialMismatch = Math.abs(pixelDifference) >= 32;
+    if (difference < -0.1 && isMaterialMismatch) {
+      diagnostics.push(
+        runtimeDiagnostic(
+          "sizes-understates-layout",
+          "warning",
+          "high",
+          "The active sizes slot is smaller than the rendered CSS width.",
+          {
+            declaredSlotWidth: input.declaredSlotWidth,
+            renderedWidth: input.renderedWidth,
+            pixelDifference,
+            difference
+          }
+        )
+      );
+    } else if (difference > 0.25 && isMaterialMismatch) {
+      diagnostics.push(
+        runtimeDiagnostic(
+          "sizes-overstates-layout",
+          "warning",
+          "high",
+          "The active sizes slot is substantially larger than the rendered CSS width.",
+          {
+            declaredSlotWidth: input.declaredSlotWidth,
+            renderedWidth: input.renderedWidth,
+            pixelDifference,
+            difference
+          }
+        )
+      );
+    }
+  }
+  if (input.source && input.source.width < input.idealWidth) {
+    diagnostics.push(
+      runtimeDiagnostic(
+        "source-too-small",
+        "error",
+        "high",
+        "The source is smaller than the rendered width \xD7 DPR target.",
+        {
+          sourceWidth: input.source.width,
+          idealWidth: input.idealWidth
+        }
+      )
+    );
+  }
+  if (input.selectedWidth && input.selectedWidth < input.idealWidth) {
+    const hasLarger = input.availableWidths.some(
+      (width) => width >= input.idealWidth
+    );
+    diagnostics.push(
+      runtimeDiagnostic(
+        hasLarger ? "browser-downselected" : "missing-useful-candidate",
+        hasLarger ? "info" : "warning",
+        "high",
+        hasLarger ? "The browser selected below the theoretical target although a larger candidate exists." : "No available candidate reaches the theoretical target.",
+        { selectedWidth: input.selectedWidth, idealWidth: input.idealWidth }
+      )
+    );
+  }
+  if (input.source && input.objectFit === "cover") {
+    const sourceRatio = input.source.width / input.source.height;
+    const renderedRatio = input.renderedWidth / input.renderedHeight;
+    if (Math.abs(sourceRatio - renderedRatio) / sourceRatio > 0.02) {
+      diagnostics.push(
+        runtimeDiagnostic(
+          "cropped-image",
+          "info",
+          "high",
+          "object-fit: cover crops part of the downloaded source.",
+          {
+            sourceAspectRatio: sourceRatio,
+            renderedAspectRatio: renderedRatio
+          }
+        )
+      );
+    }
+  }
+  return diagnostics;
+}
+function resolveSizes(sizes) {
+  if (!sizes || sizes.trim() === "auto") return null;
+  for (const rule of splitTopLevel(sizes)) {
+    const value = rule.trim();
+    let length = value;
+    if (value.startsWith("(")) {
+      const end = matchingParenthesis(value);
+      if (end < 0) continue;
+      if (!matchMedia(value.slice(0, end + 1)).matches) continue;
+      length = value.slice(end + 1).trim();
+    }
+    if (!length || length === "auto") continue;
+    const probe = document.createElement("div");
+    probe.style.cssText = `position:fixed;visibility:hidden;pointer-events:none;width:${length};height:0`;
+    document.body.append(probe);
+    const width = probe.getBoundingClientRect().width;
+    probe.remove();
+    return Number.isFinite(width) && width > 0 ? width : null;
+  }
+  return null;
+}
+function splitTopLevel(value) {
+  const output = [];
+  let depth = 0;
+  let start = 0;
+  for (let index = 0; index < value.length; index++) {
+    if (value[index] === "(") depth++;
+    if (value[index] === ")") depth--;
+    if (value[index] === "," && depth === 0) {
+      output.push(value.slice(start, index));
+      start = index + 1;
+    }
+  }
+  output.push(value.slice(start));
+  return output;
+}
+function matchingParenthesis(value) {
+  let depth = 0;
+  for (let index = 0; index < value.length; index++) {
+    if (value[index] === "(") depth++;
+    if (value[index] === ")" && --depth === 0) return index;
+  }
+  return -1;
+}
+function runtimeDiagnostic(code, severity, confidence, message, evidence) {
+  return { code, severity, confidence, message, evidence };
+}
+function logReportTable(reports, mode) {
+  if (mode === "silent") return;
+  const visible = reports.filter(
+    (report) => mode === "all" || report.diagnostics.some((diagnostic) => diagnostic.severity !== "info")
+  );
+  if (visible.length === 0) return;
+  console.table(
+    visible.map((report) => ({
+      asset: report.id,
+      stage: imageStage(report),
+      rendered: `${Math.round(report.renderedWidth)}\xD7${Math.round(report.renderedHeight)}`,
+      selected: report.selectedWidth,
+      ideal: report.idealWidth,
+      bytes: report.transferBytes,
+      blurMs: report.timing?.blurMs ?? null,
+      previewMs: report.timing?.previewMs ?? null,
+      finalMs: report.timing?.finalMs ?? null,
+      lazy: report.loading === "lazy",
+      lcp: report.isLcp,
+      status: diagnosticStatus(report),
+      diagnostics: report.diagnostics.map((diagnostic) => diagnostic.code).join(", ")
+    }))
+  );
+}
+function imageStage(report) {
+  if (report.timing?.finalAt !== null && report.timing?.finalAt !== void 0)
+    return "final";
+  if (report.timing?.previewAt) return "preview";
+  if (report.timing) return "blur";
+  return report.naturalWidth > 0 ? "final" : "loading";
+}
+function diagnosticStatus(report) {
+  if (report.diagnostics.some((item) => item.severity === "error"))
+    return "error";
+  if (report.diagnostics.some((item) => item.severity === "warning"))
+    return "warning";
+  if (report.diagnostics.some((item) => item.severity === "info")) return "info";
+  return "healthy";
+}
+function reportSignature(reports) {
+  return reports.map(
+    (report) => [
+      report.id,
+      imageStage(report),
+      report.selectedWidth,
+      report.transferBytes,
+      report.timing?.blurMs,
+      report.timing?.previewMs,
+      report.timing?.finalMs,
+      diagnosticStatus(report)
+    ].join(":")
+  ).join("|");
+}
+
+// packages/react/plan-image.tsx
+import {
+  useCallback,
+  useRef,
+  useState
+} from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+function IrisPlanImage(props) {
+  const { plan } = props;
+  const key = JSON.stringify([
+    plan.src,
+    plan.final.url,
+    plan.preview?.url,
+    plan.placeholder?.url,
+    plan.placeholder?.blur
+  ]);
+  return /* @__PURE__ */ jsx(PlanImage, { ...props }, key);
+}
+function PlanImage({
+  plan,
+  alt,
+  className,
+  style,
+  onLoad,
+  onError,
+  loading = "lazy",
+  ...props
+}) {
+  const [finalReady, setFinalReady] = useState(false);
+  const [previewReady, setPreviewReady] = useState(false);
+  const previewDecoding = useRef(false);
+  const previewShown = useRef(false);
+  const finalRef = useCallback((image) => {
+    if (image?.complete && image.naturalWidth) setFinalReady(true);
+  }, []);
+  const revealPreview = useCallback(async (image) => {
+    if (previewDecoding.current || previewShown.current) return;
+    previewDecoding.current = true;
+    try {
+      await image.decode?.();
+    } catch {
+    }
+    previewDecoding.current = false;
+    if (image.isConnected && image.naturalWidth && !previewShown.current) {
+      previewShown.current = true;
+      setPreviewReady(true);
+    }
+  }, []);
+  const previewRef = useCallback(
+    (image) => {
+      if (image?.complete && image.naturalWidth) void revealPreview(image);
+    },
+    [revealPreview]
+  );
+  const progressive = Boolean(plan.final.progressive);
+  const surface = {
+    position: "relative",
+    display: "block",
+    ...style
+  };
+  return /* @__PURE__ */ jsxs("span", { className, "data-slot": "iris-image", style: surface, children: [
+    /* @__PURE__ */ jsx(
+      "img",
+      {
+        ...props,
+        ref: finalRef,
+        src: plan.final.url,
+        alt,
+        width: plan.final.width,
+        height: plan.final.height,
+        "data-slot": "iris-final",
+        "data-iris-src": plan.src,
+        loading,
+        style: {
+          position: "relative",
+          display: "block",
+          width: "100%",
+          height: "auto"
+        },
+        onLoad: (event) => {
+          setFinalReady(true);
+          onLoad?.(event);
+        },
+        onError
+      }
+    ),
+    !progressive && !finalReady && !previewReady && plan.placeholder && /* @__PURE__ */ jsx(
+      "span",
+      {
+        "aria-hidden": "true",
+        "data-slot": "iris-placeholder",
+        "data-stage": "blur",
+        style: {
+          position: "absolute",
+          inset: 0,
+          backgroundImage: `url(${JSON.stringify(plan.placeholder.url)})`,
+          backgroundSize: "100% 100%",
+          filter: `blur(${plan.placeholder.blur}px)`,
+          clipPath: "inset(0)",
+          pointerEvents: "none",
+          zIndex: 2
+        }
+      }
+    ),
+    !progressive && plan.preview && !finalReady && /* @__PURE__ */ jsx(
+      "img",
+      {
+        ref: previewRef,
+        src: plan.preview.url,
+        alt: "",
+        "aria-hidden": "true",
+        "data-slot": "iris-preview",
+        width: plan.final.width,
+        height: plan.final.height,
+        loading,
+        decoding: props.decoding,
+        crossOrigin: props.crossOrigin,
+        referrerPolicy: props.referrerPolicy,
+        style: {
+          position: "absolute",
+          inset: 0,
+          width: "100%",
+          height: "100%",
+          objectFit: "contain",
+          pointerEvents: "none",
+          zIndex: 1,
+          opacity: previewReady ? 1 : 0
+        },
+        onLoad: (event) => void revealPreview(event.currentTarget)
+      }
+    )
+  ] });
+}
+
+// packages/react/index.tsx
+import { jsx as jsx2 } from "react/jsx-runtime";
+var IrisDebuggerContext = createContext(null);
+function IrisProvider({
+  children,
+  enabled = true,
+  manifest,
+  scope = "marked",
+  console: consoleMode = "warnings"
+}) {
+  const [iris] = useState2(
+    () => typeof window === "undefined" ? null : createIrisDebugger({ manifest, scope, console: consoleMode })
+  );
+  useEffect(() => {
+    if (!enabled || !iris) return;
+    iris.observe(document);
+    window.__IRIS__ = iris;
+    return () => {
+      iris.disconnect();
+      if (window.__IRIS__ === iris) delete window.__IRIS__;
+    };
+  }, [enabled, iris]);
+  return /* @__PURE__ */ jsx2(IrisDebuggerContext.Provider, { value: enabled ? iris : null, children });
+}
+function useIrisDebugger() {
+  return useContext(IrisDebuggerContext);
+}
+export {
+  IrisPlanImage,
+  IrisProvider,
+  useIrisDebugger
+};
+//# sourceMappingURL=react.js.map