@replohq/sandbox-runtime 1.18.0 → 1.19.0

package/heatmaps/heatCore.d.ts

@@ -0,0 +1,34 @@
+/** Heat drawn over one document: heat canvas or scroll bands, revenue badges, focus ring and revenue clicks. */
+import type { PageHeatmapElementSection, PageHeatmapSetMessage } from "../_vendor/schemas/generated/pageHeatmap";
+export declare const HEAT_LAYER_HOST_ID = "replo-heat-layer";
+export type HeatLayerSet = Omit<PageHeatmapSetMessage, "type" | "protocolVersion">;
+export interface HeatLayerDrawn {
+    setId: string;
+    placedWeight: number;
+    unplacedWeight: number;
+    sections: PageHeatmapElementSection[];
+}
+export interface HeatLayer {
+    /** Draws `set` (null clears the layer and stops observing the page). */
+    show: (set: HeatLayerSet | null) => void;
+    /** Outlines one element and scrolls it into view when it's off screen; null hides the outline. */
+    focus: (selector: string | null) => void;
+    destroy: () => void;
+}
+/**
+ * Draws heat sets over `document`, which can be this page or a same-origin
+ * iframe's. Inert until the first `show`.
+ */
+export declare function createHeatLayer({ document: doc, onDrawn, onElementClicked, shouldIgnoreClick, paintAsImage, }: {
+    document: Document;
+    /** Fires when what was placed changes, not on every re-measure. */
+    onDrawn: (drawn: HeatLayerDrawn) => void;
+    /** Revenue mode: the innermost badged element under a page click, or null. */
+    onElementClicked: (selector: string | null) => void;
+    shouldIgnoreClick?: (target: Node) => boolean;
+    /**
+     * A document without scripting (a sandboxed site snapshot) renders a canvas's fallback content, not
+     * its bitmap, so the heat is drawn off-page and shown as an image.
+     */
+    paintAsImage?: boolean;
+}): HeatLayer;

package/heatmaps/heatCore.js

@@ -0,0 +1,465 @@
+import { exhaustiveSwitch } from "../_vendor/replo-utils/lib/misc.mjs";
+import { findClickedSelector, findSection, renderBadges } from "./heatBadges";
+import {
+  drawHeatPoints,
+  drawMarkLine,
+  drawScrollBands,
+  getReachMarks,
+  getScrollReach
+} from "./heatRender";
+const HEAT_LAYER_HOST_ID = "replo-heat-layer";
+const HEAT_LAYER_Z_INDEX = 2147483644;
+const REMEASURE_DEBOUNCE_MS = 250;
+const MAX_CANVAS_PIXELS = 16e6;
+const CLICK_RADIUS_PX = 16;
+const FOCUS_RING_PADDING_PX = 6;
+const REVENUE_HEAT_OPACITY = "0.4";
+function isNode(value) {
+  return typeof value === "object" && value !== null && "nodeType" in value;
+}
+function createHeatLayer({
+  document: doc,
+  onDrawn,
+  onElementClicked,
+  shouldIgnoreClick = () => false,
+  paintAsImage = false
+}) {
+  let heatSet = null;
+  let focusSelector = null;
+  let lastDrawnReport = null;
+  let nodes = null;
+  let remeasureFrameId = null;
+  let remeasureDebounceId = null;
+  let resizeObserver = null;
+  let mutationObserver = null;
+  let observedView = null;
+  let clickView = null;
+  let badgedElements = [];
+  let imageUrl = null;
+  let imagePaint = 0;
+  const releaseImage = () => {
+    imagePaint += 1;
+    if (imageUrl) {
+      URL.revokeObjectURL(imageUrl);
+      imageUrl = null;
+    }
+  };
+  const paintImage = ({
+    canvas,
+    image
+  }) => {
+    image.style.cssText = `${canvas.style.cssText}; max-width: none; max-height: none`;
+    const paint = ++imagePaint;
+    canvas.toBlob((blob) => {
+      if (!blob || paint !== imagePaint || !image.isConnected) {
+        return;
+      }
+      const previous = imageUrl;
+      imageUrl = URL.createObjectURL(blob);
+      image.src = imageUrl;
+      if (previous) {
+        URL.revokeObjectURL(previous);
+      }
+    });
+  };
+  const ensureNodes = () => {
+    if (nodes?.host.isConnected) {
+      return nodes;
+    }
+    if (!doc.body) {
+      return null;
+    }
+    const host = doc.createElement("div");
+    host.id = HEAT_LAYER_HOST_ID;
+    host.setAttribute("aria-hidden", "true");
+    host.style.cssText = [
+      "position: absolute",
+      "top: 0",
+      "left: 0",
+      "width: 0",
+      "height: 0",
+      "margin: 0",
+      "padding: 0",
+      "pointer-events: none",
+      `z-index: ${HEAT_LAYER_Z_INDEX}`
+    ].join(";");
+    const canvas = doc.createElement("canvas");
+    canvas.style.cssText = [
+      "position: absolute",
+      "top: 0",
+      "left: 0",
+      "pointer-events: none"
+    ].join(";");
+    const focusRing = doc.createElement("div");
+    focusRing.style.cssText = [
+      "display: none",
+      "box-sizing: border-box",
+      "border-radius: 8px",
+      "pointer-events: none",
+      "box-shadow: 0 0 0 3px #fff, 0 0 0 6px rgba(17, 17, 17, 0.85)"
+    ].join(";");
+    const badges = doc.createElement("div");
+    badges.style.cssText = "position: absolute; top: 0; left: 0; pointer-events: none";
+    const image = paintAsImage ? doc.createElement("img") : null;
+    if (image) {
+      image.alt = "";
+    }
+    host.append(image ?? canvas, focusRing, badges);
+    doc.body.append(host);
+    nodes = { host, canvas, image, focusRing, badges };
+    return nodes;
+  };
+  const removeNodes = () => {
+    releaseImage();
+    nodes?.host.remove();
+    nodes = null;
+  };
+  const getPageSize = (host) => {
+    host.style.display = "none";
+    const root = doc.documentElement;
+    const width = Math.max(root.scrollWidth, doc.body.scrollWidth);
+    const height = Math.max(root.scrollHeight, doc.body.scrollHeight);
+    host.style.display = "";
+    return { width, height };
+  };
+  const hasFixedAncestor = (element) => {
+    const view = doc.defaultView;
+    let current = element;
+    while (current && current !== doc.documentElement) {
+      if (view?.getComputedStyle(current).position === "fixed") {
+        return true;
+      }
+      current = current.parentElement;
+    }
+    return false;
+  };
+  const findElement = (selector) => {
+    try {
+      return doc.querySelector(selector);
+    } catch {
+      return null;
+    }
+  };
+  const getScrollOffset = () => {
+    const scrollingElement = doc.scrollingElement;
+    return {
+      left: scrollingElement?.scrollLeft ?? doc.defaultView?.scrollX ?? 0,
+      top: scrollingElement?.scrollTop ?? doc.defaultView?.scrollY ?? 0
+    };
+  };
+  const getPageRect = (element) => {
+    const domRect = element.getBoundingClientRect();
+    if (domRect.width === 0 && domRect.height === 0) {
+      return null;
+    }
+    const isFixed = hasFixedAncestor(element);
+    const scroll = isFixed ? { left: 0, top: 0 } : getScrollOffset();
+    return {
+      x: domRect.x + scroll.left,
+      y: domRect.y + scroll.top,
+      width: domRect.width,
+      height: domRect.height,
+      isFixed
+    };
+  };
+  const createElementLookup = () => {
+    const elements = /* @__PURE__ */ new Map();
+    return (selector) => {
+      let element = elements.get(selector);
+      if (element === void 0) {
+        element = findElement(selector);
+        elements.set(selector, element);
+      }
+      return element;
+    };
+  };
+  const getClickPoints = ({
+    set,
+    lookup
+  }) => {
+    const rectsBySelector = /* @__PURE__ */ new Map();
+    const points = [];
+    let placedWeight = 0;
+    let unplacedWeight = 0;
+    for (const click of set.clicks) {
+      let rect = rectsBySelector.get(click.selector);
+      if (rect === void 0) {
+        const element = lookup(click.selector);
+        rect = element ? getPageRect(element) : null;
+        rectsBySelector.set(click.selector, rect);
+      }
+      if (!rect) {
+        unplacedWeight += click.weight;
+        continue;
+      }
+      placedWeight += click.weight;
+      points.push({
+        x: rect.x + click.rx * rect.width,
+        y: rect.y + click.ry * rect.height,
+        weight: click.weight
+      });
+    }
+    return { points, placedWeight, unplacedWeight };
+  };
+  const drawSet = ({
+    set,
+    canvas,
+    page,
+    lookup
+  }) => {
+    const resolution = Math.min(
+      1,
+      Math.sqrt(MAX_CANVAS_PIXELS / Math.max(1, page.width * page.height))
+    );
+    canvas.width = Math.max(1, Math.round(page.width * resolution));
+    canvas.height = Math.max(1, Math.round(page.height * resolution));
+    canvas.style.width = `${page.width}px`;
+    canvas.style.height = `${page.height}px`;
+    const context = canvas.getContext("2d", { willReadFrequently: true });
+    const toCanvas = (point) => ({
+      x: point.x * resolution,
+      y: point.y * resolution,
+      weight: point.weight
+    });
+    canvas.style.opacity = set.mode === "revenue" ? REVENUE_HEAT_OPACITY : "1";
+    const drawClicks = () => {
+      const resolved = getClickPoints({ set, lookup });
+      if (context) {
+        drawHeatPoints({
+          context,
+          points: resolved.points.map(toCanvas),
+          radius: CLICK_RADIUS_PX * resolution
+        });
+      }
+      return {
+        placedWeight: resolved.placedWeight,
+        unplacedWeight: resolved.unplacedWeight
+      };
+    };
+    const result = exhaustiveSwitch({ type: set.mode })({
+      revenue: drawClicks,
+      clicks: drawClicks,
+      scroll: () => {
+        if (context) {
+          const reach = getScrollReach(set.scroll);
+          drawScrollBands({ context, reach });
+          for (const mark of getReachMarks({ reach, height: canvas.height })) {
+            drawMarkLine({
+              context,
+              y: mark.y,
+              label: `${Math.round(mark.share * 100)}% of visitors reach here`,
+              dashed: true,
+              scale: resolution
+            });
+          }
+        }
+        return { placedWeight: 0, unplacedWeight: 0 };
+      }
+    });
+    if (context && set.fold !== null && set.fold < page.height) {
+      drawMarkLine({
+        context,
+        y: set.fold * resolution,
+        label: "End of the first screen",
+        dashed: false,
+        scale: resolution
+      });
+    }
+    return result;
+  };
+  const positionFocusRing = (focusRing) => {
+    const element = focusSelector ? findElement(focusSelector) : null;
+    const rect = element ? getPageRect(element) : null;
+    if (!rect) {
+      focusRing.style.display = "none";
+      return null;
+    }
+    focusRing.style.display = "block";
+    focusRing.style.position = rect.isFixed ? "fixed" : "absolute";
+    focusRing.style.left = `${rect.x - FOCUS_RING_PADDING_PX}px`;
+    focusRing.style.top = `${rect.y - FOCUS_RING_PADDING_PX}px`;
+    focusRing.style.width = `${rect.width + FOCUS_RING_PADDING_PX * 2}px`;
+    focusRing.style.height = `${rect.height + FOCUS_RING_PADDING_PX * 2}px`;
+    return element;
+  };
+  const drawBadges = ({
+    set,
+    container,
+    lookup
+  }) => {
+    if (set.mode !== "revenue") {
+      badgedElements = [];
+      container.replaceChildren();
+      return;
+    }
+    badgedElements = set.badges.flatMap((badge) => {
+      const element = lookup(badge.selector);
+      return element ? [{ selector: badge.selector, element }] : [];
+    });
+    renderBadges({
+      container,
+      badges: set.badges,
+      rectFor: (selector) => {
+        const element = lookup(selector);
+        return element ? getPageRect(element) : null;
+      }
+    });
+  };
+  const findSections = ({
+    set,
+    lookup
+  }) => {
+    const selectors = /* @__PURE__ */ new Set([
+      ...set.clicks.map((click) => click.selector),
+      ...set.badges.map((badge) => badge.selector)
+    ]);
+    return [...selectors].flatMap((selector) => {
+      const element = lookup(selector);
+      const section = element ? findSection(element) : null;
+      return section ? [{ selector, section }] : [];
+    });
+  };
+  const handleRevenueClick = (event) => {
+    const target = event.target;
+    if (!isNode(target) || shouldIgnoreClick(target)) {
+      return;
+    }
+    event.preventDefault();
+    event.stopPropagation();
+    const selector = findClickedSelector({ target, badged: badgedElements });
+    focusSelector = selector;
+    if (nodes) {
+      positionFocusRing(nodes.focusRing);
+    }
+    onElementClicked(selector);
+  };
+  const syncClickInterception = () => {
+    const view = heatSet?.mode === "revenue" ? doc.defaultView : null;
+    if (view === clickView) {
+      return;
+    }
+    clickView?.removeEventListener("click", handleRevenueClick, true);
+    view?.addEventListener("click", handleRevenueClick, true);
+    clickView = view;
+  };
+  const scheduleRemeasure = () => {
+    remeasureFrameId ??= requestAnimationFrame(() => {
+      remeasureFrameId = null;
+      render();
+    });
+  };
+  const scheduleDebouncedRemeasure = () => {
+    if (remeasureDebounceId !== null) {
+      clearTimeout(remeasureDebounceId);
+    }
+    remeasureDebounceId = setTimeout(scheduleRemeasure, REMEASURE_DEBOUNCE_MS);
+  };
+  const stopObserving = () => {
+    observedView?.removeEventListener("resize", scheduleDebouncedRemeasure);
+    observedView = null;
+    resizeObserver?.disconnect();
+    resizeObserver = null;
+    mutationObserver?.disconnect();
+    mutationObserver = null;
+    if (remeasureDebounceId !== null) {
+      clearTimeout(remeasureDebounceId);
+      remeasureDebounceId = null;
+    }
+    if (remeasureFrameId !== null) {
+      cancelAnimationFrame(remeasureFrameId);
+      remeasureFrameId = null;
+    }
+  };
+  const syncObservers = () => {
+    const shouldObserve = heatSet !== null;
+    if (shouldObserve === (mutationObserver !== null)) {
+      return;
+    }
+    if (!shouldObserve) {
+      stopObserving();
+      return;
+    }
+    observedView = doc.defaultView;
+    observedView?.addEventListener("resize", scheduleDebouncedRemeasure);
+    if (typeof ResizeObserver !== "undefined") {
+      resizeObserver = new ResizeObserver(scheduleDebouncedRemeasure);
+      resizeObserver.observe(doc.body);
+    }
+    mutationObserver = new MutationObserver((records) => {
+      const host = nodes?.host;
+      const hasForeignMutation = records.some((record) => {
+        return !host || !host.contains(record.target);
+      });
+      if (hasForeignMutation) {
+        scheduleDebouncedRemeasure();
+      }
+    });
+    mutationObserver.observe(doc.body, { childList: true, subtree: true });
+  };
+  function render() {
+    if (!heatSet) {
+      removeNodes();
+      badgedElements = [];
+      syncObservers();
+      syncClickInterception();
+      return;
+    }
+    const layer = ensureNodes();
+    if (!layer) {
+      return;
+    }
+    const lookup = createElementLookup();
+    const page = getPageSize(layer.host);
+    const weights = drawSet({
+      set: heatSet,
+      canvas: layer.canvas,
+      page,
+      lookup
+    });
+    if (layer.image) {
+      paintImage({ canvas: layer.canvas, image: layer.image });
+    }
+    drawBadges({ set: heatSet, container: layer.badges, lookup });
+    positionFocusRing(layer.focusRing);
+    const sections = findSections({ set: heatSet, lookup });
+    const report = JSON.stringify([heatSet.setId, weights, sections]);
+    if (report !== lastDrawnReport) {
+      lastDrawnReport = report;
+      onDrawn({ setId: heatSet.setId, ...weights, sections });
+    }
+    syncObservers();
+    syncClickInterception();
+  }
+  const show = (set) => {
+    heatSet = set;
+    if (!set) {
+      focusSelector = null;
+    }
+    lastDrawnReport = null;
+    render();
+  };
+  return {
+    show,
+    focus(selector) {
+      focusSelector = selector;
+      if (!heatSet || !nodes) {
+        return;
+      }
+      const element = positionFocusRing(nodes.focusRing);
+      if (!element) {
+        return;
+      }
+      const viewportRect = element.getBoundingClientRect();
+      const viewportHeight = doc.defaultView?.innerHeight ?? 0;
+      const isInView = viewportRect.top >= 0 && viewportRect.bottom <= viewportHeight;
+      if (!isInView) {
+        element.scrollIntoView({ block: "center", behavior: "smooth" });
+      }
+    },
+    destroy: () => show(null)
+  };
+}
+export {
+  HEAT_LAYER_HOST_ID,
+  createHeatLayer
+};

package/heatmaps/heatLayer.d.ts

@@ -0,0 +1 @@
+export declare function initHeatLayer(): void;

package/heatmaps/heatLayer.js

@@ -0,0 +1,85 @@
+import { exhaustiveSwitch } from "../_vendor/replo-utils/lib/misc.mjs";
+import {
+  PAGE_HEATMAP_PROTOCOL_VERSION,
+  pageHeatmapParentMessageSchema
+} from "../_vendor/schemas/pageHeatmap.mjs";
+import {
+  isAllowedEditorMessage,
+  isAllowedEditorOrigin
+} from "../annotations/bridgeGate";
+import { ANNOTATION_CONTAINER_ID } from "../select-mode/annotationFrames";
+import { displayModeStore } from "../select-mode/displayModeStore";
+import { createHeatLayer } from "./heatCore";
+let isInitialized = false;
+let editorOrigin = null;
+let layer = null;
+function postToEditor(message) {
+  if (!editorOrigin) {
+    return;
+  }
+  window.parent.postMessage(message, editorOrigin);
+}
+function getLayer() {
+  layer ??= createHeatLayer({
+    document,
+    onDrawn: (drawn) => {
+      postToEditor({ type: "replo:heatmap:drawn", ...drawn });
+    },
+    onElementClicked: (selector) => {
+      postToEditor({ type: "replo:heatmap:elementClicked", selector });
+    },
+    shouldIgnoreClick: (target) => {
+      return displayModeStore.getSnapshot() === "selection" || Boolean(
+        document.getElementById(ANNOTATION_CONTAINER_ID)?.contains(target)
+      );
+    }
+  });
+  return layer;
+}
+function handleMessage(event) {
+  if (!isAllowedEditorMessage(event)) {
+    return;
+  }
+  const parsed = pageHeatmapParentMessageSchema.safeParse(event.data);
+  if (!parsed.success) {
+    return;
+  }
+  editorOrigin = event.origin;
+  exhaustiveSwitch(parsed.data)({
+    "replo:heatmap:set": (message) => {
+      getLayer().show(message);
+    },
+    "replo:heatmap:focus": (message) => {
+      getLayer().focus(message.selector);
+    },
+    "replo:heatmap:clear": () => {
+      getLayer().show(null);
+    },
+    "replo:heatmap:requestReady": () => {
+      postToEditor({
+        type: "replo:heatmap:ready",
+        protocolVersion: PAGE_HEATMAP_PROTOCOL_VERSION
+      });
+    }
+  });
+}
+function initHeatLayer() {
+  if (isInitialized || window.self === window.top) {
+    return;
+  }
+  isInitialized = true;
+  window.addEventListener("message", handleMessage);
+  const referrerOrigin = URL.canParse(document.referrer) ? new URL(document.referrer).origin : null;
+  if (referrerOrigin && isAllowedEditorOrigin(referrerOrigin)) {
+    window.parent.postMessage(
+      {
+        type: "replo:heatmap:ready",
+        protocolVersion: PAGE_HEATMAP_PROTOCOL_VERSION
+      },
+      referrerOrigin
+    );
+  }
+}
+export {
+  initHeatLayer
+};

package/heatmaps/heatRender.d.ts

@@ -0,0 +1,36 @@
+/** Heat drawing: alpha-summed discs recoloured through a thermal palette, or scroll-reach bands. */
+export interface HeatPoint {
+    x: number;
+    y: number;
+    weight: number;
+}
+/** Points are in canvas pixels; `radius` too. */
+export declare function drawHeatPoints({ context, points, radius, }: {
+    context: CanvasRenderingContext2D;
+    points: HeatPoint[];
+    radius: number;
+}): void;
+/** `reach[p]` is the share of page views that saw p% of the page, from each view's deepest point. */
+export declare function getScrollReach(buckets: {
+    pct: number;
+    views: number;
+}[]): number[];
+export declare function drawScrollBands({ context, reach, }: {
+    context: CanvasRenderingContext2D;
+    reach: number[];
+}): void;
+/** Page y (canvas px) where reach first drops below each mark. */
+export declare function getReachMarks({ reach, height, }: {
+    reach: number[];
+    height: number;
+}): {
+    share: number;
+    y: number;
+}[];
+export declare function drawMarkLine({ context, y, label, dashed, scale, }: {
+    context: CanvasRenderingContext2D;
+    y: number;
+    label: string;
+    dashed: boolean;
+    scale: number;
+}): void;