@bitvea/feedback-toolbar 0.0.1

package/dist/rasterise.js

@@ -0,0 +1,490 @@
+// Turning the current viewport into pixels, with no permission prompt and no
+// dependency.
+//
+// The technique is the platform's own: clone the visible DOM, write the styles
+// that matter onto the clones as inline style, wrap the result in an SVG
+// `<foreignObject>`, and let the browser decode that SVG as an image and draw
+// it into a canvas. Everything here is synchronous DOM work plus one image
+// decode, so it costs the reviewer nothing and asks them for nothing.
+//
+// Known and accepted limits, all of them consequences of how an SVG image is
+// rendered - it is a sealed document that may not load external resources:
+//
+//   - Web fonts do not load, so text falls back down its font stack. Metrics
+//     shift; the layout does not.
+//   - Cross-origin images and `background-image` URLs do not load. Same-origin
+//     and CORS-enabled `<img>` content is inlined below, so the common case
+//     survives; the rest render as empty boxes rather than broken icons.
+//   - Only the properties in `COPIED_PROPERTIES` are carried over. Copying all
+//     ~340 computed properties per element is correct but produces megabytes of
+//     CSS for an ordinary page, and the data URL that has to carry it grows
+//     faster still. The allowlist is the visual set.
+//
+// The spec puts cross-browser screenshot fidelity under exotic CSS out of scope
+// for v1, and these are exactly that class of gap. A screenshot that is
+// recognisably the page, taken silently, beats a pixel-exact one that costs a
+// modal dialog per submission.
+/** Elements that never contribute pixels, or that must not be in the shot. */
+const SKIPPED_TAGS = new Set([
+    "SCRIPT",
+    "STYLE",
+    "LINK",
+    "META",
+    "TITLE",
+    "NOSCRIPT",
+    "TEMPLATE",
+    "BASE",
+]);
+/**
+ * The toolbar's own root carries this attribute. A screenshot of the page the
+ * reviewer is reporting on should not have the reporting UI sitting in it.
+ */
+const TOOLBAR_ROOT_ATTRIBUTE = "data-bitvea-feedback-toolbar";
+/**
+ * Past this many elements the clone-and-restyle walk stops being something a
+ * reviewer would sit through. Bail rather than freeze the page they are trying
+ * to comment on; a null screenshot is a supported outcome, a hung tab is not.
+ */
+const MAX_ELEMENTS = 12_000;
+/**
+ * Attributes worth carrying onto a clone. Everything else either only mattered
+ * through a stylesheet the SVG document cannot see, or is a framework
+ * attribute whose name is not valid XML.
+ */
+const KEPT_ATTRIBUTES = new Set([
+    "colspan",
+    "rowspan",
+    "span",
+    "dir",
+    "alt",
+    "start",
+    "reversed",
+    "type",
+    "value",
+    "checked",
+    "selected",
+    "open",
+    "lang",
+]);
+/** How long to wait for the browser to decode the SVG before giving up. */
+const DECODE_TIMEOUT_MS = 5_000;
+/**
+ * The properties written onto each clone. Longhands only: `getComputedStyle`
+ * resolves to longhands, and asking it for a shorthand is not portable.
+ */
+const COPIED_PROPERTIES = [
+    // Box
+    "display",
+    "position",
+    "top",
+    "right",
+    "bottom",
+    "left",
+    "float",
+    "clear",
+    "z-index",
+    "box-sizing",
+    "width",
+    "height",
+    "min-width",
+    "min-height",
+    "max-width",
+    "max-height",
+    "aspect-ratio",
+    "margin-top",
+    "margin-right",
+    "margin-bottom",
+    "margin-left",
+    "padding-top",
+    "padding-right",
+    "padding-bottom",
+    "padding-left",
+    "overflow-x",
+    "overflow-y",
+    "visibility",
+    "opacity",
+    // Border and outline
+    "border-top-width",
+    "border-right-width",
+    "border-bottom-width",
+    "border-left-width",
+    "border-top-style",
+    "border-right-style",
+    "border-bottom-style",
+    "border-left-style",
+    "border-top-color",
+    "border-right-color",
+    "border-bottom-color",
+    "border-left-color",
+    "border-top-left-radius",
+    "border-top-right-radius",
+    "border-bottom-left-radius",
+    "border-bottom-right-radius",
+    "outline-width",
+    "outline-style",
+    "outline-color",
+    "outline-offset",
+    // Paint
+    "background-color",
+    "background-image",
+    "background-size",
+    "background-position",
+    "background-repeat",
+    "background-clip",
+    "background-origin",
+    "box-shadow",
+    "filter",
+    "mix-blend-mode",
+    "clip-path",
+    "transform",
+    "transform-origin",
+    // Type
+    "color",
+    "font-family",
+    "font-size",
+    "font-style",
+    "font-weight",
+    "font-variant",
+    "font-stretch",
+    "letter-spacing",
+    "line-height",
+    "text-align",
+    "text-decoration-line",
+    "text-decoration-color",
+    "text-decoration-style",
+    "text-indent",
+    "text-transform",
+    "text-shadow",
+    "white-space",
+    "word-break",
+    "overflow-wrap",
+    "vertical-align",
+    "text-overflow",
+    "direction",
+    // Flex and grid
+    "flex-direction",
+    "flex-wrap",
+    "flex-grow",
+    "flex-shrink",
+    "flex-basis",
+    "justify-content",
+    "justify-items",
+    "justify-self",
+    "align-content",
+    "align-items",
+    "align-self",
+    "order",
+    "gap",
+    "row-gap",
+    "column-gap",
+    "grid-template-columns",
+    "grid-template-rows",
+    "grid-auto-flow",
+    "grid-auto-columns",
+    "grid-auto-rows",
+    "grid-column-start",
+    "grid-column-end",
+    "grid-row-start",
+    "grid-row-end",
+    // Tables, lists, media
+    "table-layout",
+    "border-collapse",
+    "border-spacing",
+    "caption-side",
+    "list-style-type",
+    "list-style-position",
+    "object-fit",
+    "object-position",
+    "fill",
+    "stroke",
+    "stroke-width",
+];
+/**
+ * Rasterise the visible viewport to a PNG data URL, or null if the browser
+ * would not produce one.
+ *
+ * @param maxDataUrlLength Longest data URL the API will accept. The image is
+ *   re-encoded at half scale, twice, before giving up, so a very large or very
+ *   dense viewport degrades in quality rather than disappearing.
+ */
+export async function rasteriseViewport(maxDataUrlLength) {
+    return rasteriseRegion(maxDataUrlLength, null);
+}
+/**
+ * Rasterise ONE element to a PNG data URL, or null if the browser would not
+ * produce one.
+ *
+ * A reviewer pointing at a broken button wants a picture of the button, not of
+ * the page it is on: the whole-viewport shot puts the thing they are reporting
+ * somewhere in a 1512x916 image and leaves the reader to find it. This is the
+ * camera in the composer.
+ *
+ * An element with no box - `display: none`, or detached - yields null rather
+ * than a 1x1 image, because a blank attachment is worse than none.
+ */
+export async function rasteriseElement(element, maxDataUrlLength) {
+    const rect = element.getBoundingClientRect();
+    if (rect.width < 1 || rect.height < 1)
+        return null;
+    return rasteriseRegion(maxDataUrlLength, rect);
+}
+/**
+ * The shared half. `region` is null for the viewport, or a rectangle in
+ * viewport coordinates for one element.
+ *
+ * @param maxDataUrlLength Longest data URL the API will accept. The image is
+ *   re-encoded at half scale, twice, before giving up, so a very large or very
+ *   dense capture degrades in quality rather than disappearing.
+ */
+async function rasteriseRegion(maxDataUrlLength, region) {
+    if (typeof document === "undefined" || !document.body)
+        return null;
+    const width = Math.max(1, Math.floor(region ? region.width : window.innerWidth));
+    const height = Math.max(1, Math.floor(region ? region.height : window.innerHeight));
+    const origin = region ? { x: region.x, y: region.y } : { x: 0, y: 0 };
+    // Ask for the drawing surface before doing any work: where there is no 2D
+    // context there is no screenshot, and finding that out first keeps the
+    // failure cheap.
+    const canvas = document.createElement("canvas");
+    const ctx = canvas.getContext("2d");
+    if (!ctx)
+        return null;
+    const svg = buildViewportSvg(width, height, origin);
+    if (svg === null)
+        return null;
+    const image = await decodeSvg(svg);
+    if (!image)
+        return null;
+    const background = resolvePageBackground();
+    let scale = Math.min(window.devicePixelRatio || 1, 2);
+    for (let attempt = 0; attempt < 3; attempt++) {
+        canvas.width = Math.max(1, Math.round(width * scale));
+        canvas.height = Math.max(1, Math.round(height * scale));
+        ctx.fillStyle = background;
+        ctx.fillRect(0, 0, canvas.width, canvas.height);
+        ctx.drawImage(image, 0, 0, canvas.width, canvas.height);
+        const dataUrl = canvas.toDataURL("image/png");
+        if (dataUrl.length <= maxDataUrlLength)
+            return dataUrl;
+        scale /= 2;
+    }
+    return null;
+}
+/**
+ * Serialise the visible page as an SVG document string, or null if the page is
+ * too large to walk. Exported for the unit tests: it is pure DOM work with no
+ * canvas or image decoding in it, so it is the part that is provable in jsdom.
+ */
+export function buildViewportSvg(width, height, 
+/**
+ * Where in the viewport the picture starts. `{x: 0, y: 0}` is the viewport
+ * shot; an element shot passes its own top-left, and the body clone shifts
+ * by the same amount so the element lands at the picture's origin.
+ *
+ * Cropping by MOVING THE WHOLE PAGE rather than by cloning only the element
+ * is the decision here. An element does not carry its own layout: its width
+ * may come from a flex parent, its colour from a `.dark` ancestor, its font
+ * from `html`. Cloning it alone reproduces none of that, and the picture
+ * that comes back is not the thing the reviewer pointed at. The page is
+ * cloned exactly as it is and the viewport is narrowed instead.
+ */
+origin = { x: 0, y: 0 }) {
+    if (document.body.getElementsByTagName("*").length > MAX_ELEMENTS) {
+        return null;
+    }
+    const clone = cloneStyled(document.body);
+    if (!clone)
+        return null;
+    // Placing the body clone at the viewport coordinates of the real body is
+    // what folds scroll position, body margins and body offset into one number
+    // each. Descendants then lay themselves out normally inside it, and
+    // `position: fixed` descendants resolve against the SVG viewport, which is
+    // the browser viewport - so a sticky header stays where it looks.
+    const rect = document.body.getBoundingClientRect();
+    clone.style.setProperty("position", "absolute");
+    clone.style.setProperty("left", `${rect.left - origin.x}px`);
+    clone.style.setProperty("top", `${rect.top - origin.y}px`);
+    clone.style.setProperty("width", `${rect.width}px`);
+    clone.style.setProperty("height", `${rect.height}px`);
+    clone.style.setProperty("margin", "0");
+    const container = document.createElement("div");
+    container.setAttribute("style", [
+        "position:relative",
+        `width:${width}px`,
+        `height:${height}px`,
+        "overflow:hidden",
+        `background:${resolvePageBackground()}`,
+    ].join(";"));
+    container.appendChild(clone);
+    const body = new XMLSerializer().serializeToString(container);
+    return (`<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" ` +
+        `viewBox="0 0 ${width} ${height}">` +
+        `<foreignObject x="0" y="0" width="100%" height="100%">${body}</foreignObject>` +
+        `</svg>`);
+}
+/* ── The walk ─────────────────────────────────────────────────────────── */
+function cloneStyled(source) {
+    if (SKIPPED_TAGS.has(source.tagName))
+        return null;
+    if (source.hasAttribute(TOOLBAR_ROOT_ATTRIBUTE))
+        return null;
+    const computed = window.getComputedStyle(source);
+    // `display: none` contributes nothing, and skipping it prunes whole subtrees
+    // - closed menus and offscreen drawers are usually most of a page's DOM.
+    if (computed.getPropertyValue("display") === "none")
+        return null;
+    // Inline SVG - icons, mostly - is already an XML island whose attributes are
+    // its geometry. Take the whole subtree verbatim and only add the inherited
+    // paint, which is what `currentColor` needs to resolve to.
+    if (source instanceof SVGElement) {
+        const svgClone = source.cloneNode(true);
+        svgClone.setAttribute("style", inlineStyleFor(source, computed));
+        return svgClone;
+    }
+    // A canvas paints from its bitmap, not its children, so it becomes an image.
+    const clone = (source instanceof HTMLCanvasElement
+        ? document.createElement("img")
+        : source.cloneNode(false));
+    // Most attributes only mattered through stylesheets the SVG document cannot
+    // see, and framework attributes (`@click`, `[ngIf]`, `x-on:click`) are not
+    // valid XML names, so serialising them would break the whole document. Keep
+    // the few that still drive layout or content.
+    for (const name of [...clone.getAttributeNames()]) {
+        if (!KEPT_ATTRIBUTES.has(name))
+            clone.removeAttribute(name);
+    }
+    clone.setAttribute("style", inlineStyleFor(source, computed));
+    if (!inlineReplacement(source, clone)) {
+        for (const child of Array.from(source.childNodes)) {
+            if (child.nodeType === Node.TEXT_NODE) {
+                clone.appendChild(child.cloneNode(false));
+            }
+            else if (child.nodeType === Node.ELEMENT_NODE) {
+                const childClone = cloneStyled(child);
+                if (childClone)
+                    clone.appendChild(childClone);
+            }
+            // Comments, processing instructions and the rest paint nothing.
+        }
+    }
+    return clone;
+}
+function inlineStyleFor(source, computed) {
+    const declarations = [];
+    for (const property of COPIED_PROPERTIES) {
+        const value = computed.getPropertyValue(property);
+        if (value === "")
+            continue;
+        declarations.push(`${property}:${value}`);
+    }
+    // An element scrolled internally shows its scrolled content, and nothing in
+    // the computed style says so.
+    if (source.scrollTop || source.scrollLeft) {
+        declarations.push(`transform:translate(${-source.scrollLeft}px, ${-source.scrollTop}px)`);
+    }
+    return declarations.join(";");
+}
+/**
+ * Elements whose pixels are not in their child nodes. Returns true when the
+ * clone has been dealt with and must not be walked into.
+ */
+function inlineReplacement(source, clone) {
+    if (source instanceof HTMLImageElement) {
+        const inlined = toDataUrl(source);
+        // No `src` at all beats a broken-image glyph where the picture was.
+        if (inlined)
+            clone.setAttribute("src", inlined);
+        return true;
+    }
+    if (source instanceof HTMLCanvasElement) {
+        // `clone` is an `<img>` standing in for the canvas; see `cloneStyled`.
+        const inlined = safeCanvasDataUrl(source);
+        if (inlined)
+            clone.setAttribute("src", inlined);
+        return true;
+    }
+    if (source instanceof HTMLInputElement ||
+        source instanceof HTMLTextAreaElement) {
+        // What the reviewer typed is often the point of the report, and a value
+        // set by script lives in the property, not the attribute.
+        if (source instanceof HTMLTextAreaElement) {
+            clone.textContent = source.value;
+        }
+        else if (source.type !== "password") {
+            clone.setAttribute("value", source.value);
+            clone.setAttribute("type", source.type);
+        }
+        return true;
+    }
+    return false;
+}
+function toDataUrl(image) {
+    if (image.currentSrc.startsWith("data:"))
+        return image.currentSrc;
+    if (!image.complete || image.naturalWidth === 0)
+        return null;
+    try {
+        const canvas = document.createElement("canvas");
+        canvas.width = image.naturalWidth;
+        canvas.height = image.naturalHeight;
+        const ctx = canvas.getContext("2d");
+        if (!ctx)
+            return null;
+        ctx.drawImage(image, 0, 0);
+        // Throws a SecurityError on a cross-origin image without CORS. That is the
+        // expected outcome for a third-party image, not an error worth surfacing.
+        return canvas.toDataURL("image/png");
+    }
+    catch {
+        return null;
+    }
+}
+function safeCanvasDataUrl(canvas) {
+    try {
+        return canvas.toDataURL("image/png");
+    }
+    catch {
+        return null;
+    }
+}
+/* ── Decoding ─────────────────────────────────────────────────────────── */
+function decodeSvg(svg) {
+    return new Promise((resolve) => {
+        const image = new Image();
+        let settled = false;
+        const settle = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            window.clearTimeout(timer);
+            resolve(value);
+        };
+        // A malformed clone makes the decode fail rather than throw, and an
+        // environment that never loads anything (jsdom, a blocked document) makes
+        // it do neither - hence the timeout as well as the error handler.
+        const timer = window.setTimeout(() => settle(null), DECODE_TIMEOUT_MS);
+        image.onload = () => settle(image);
+        image.onerror = () => settle(null);
+        image.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
+    });
+}
+/**
+ * The colour behind the page. `body` is usually transparent and the paint is
+ * on `html`, or on neither, in which case the browser's canvas is white.
+ */
+function resolvePageBackground() {
+    for (const element of [document.documentElement, document.body]) {
+        if (!element)
+            continue;
+        const colour = window
+            .getComputedStyle(element)
+            .getPropertyValue("background-color");
+        if (colour &&
+            colour !== "transparent" &&
+            !colour.includes("rgba(0, 0, 0, 0)")) {
+            return colour;
+        }
+    }
+    return "#ffffff";
+}
+//# sourceMappingURL=rasterise.js.map

package/dist/rasterise.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rasterise.js","sourceRoot":"","sources":["../src/rasterise.ts"],"names":[],"mappings":"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"}

package/dist/selector.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Build a selector that resolves back to `el`. Returns null when no selector
+ * can be built, which the caller treats as "this element cannot be pinned"
+ * rather than storing an anchor that will not resolve.
+ */
+export declare function buildSelector(el: Element): string | null;
+/** Resolve a stored selector, or null when the element is no longer there. */
+export declare function resolveSelector(selector: string): Element | null;
+/** Where inside an element a click landed, as fractions of its box. */
+export declare function offsetWithin(el: Element, clientX: number, clientY: number): {
+    offsetX: number;
+    offsetY: number;
+};
+/** Viewport position of a stored anchor, or null when it no longer resolves. */
+export declare function locatePin(selector: string, offsetX: number, offsetY: number): {
+    x: number;
+    y: number;
+} | null;
+//# sourceMappingURL=selector.d.ts.map

package/dist/selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector.d.ts","sourceRoot":"","sources":["../src/selector.ts"],"names":[],"mappings":"AAiDA;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAsCxD;AAwBD,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAMhE;AAED,uEAAuE;AACvE,wBAAgB,YAAY,CAC1B,EAAE,EAAE,OAAO,EACX,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAUtC;AAED,gFAAgF;AAChF,wBAAgB,SAAS,CACvB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CASjC"}

package/dist/selector.js

@@ -0,0 +1,142 @@
+// Turning an element into something that still finds it after a reload.
+//
+// This is the part of pinning that decides whether a pin survives, so it is a
+// pure DOM function with no React in it and its own tests. The strategy, in
+// order of how much it can be trusted:
+//
+//   1. `id`, when there is one and it looks stable.
+//   2. `data-testid`, which a team puts on things it intends to keep.
+//   3. A path of tag + nth-of-type steps up to the nearest anchor above.
+//
+// Class names are deliberately not used. A build that hashes CSS module names
+// changes every class on every deploy, and a pin anchored to `.css-1x2y3z`
+// would break on the next commit, which is precisely the pin that matters.
+/** Attributes considered stable enough to anchor to, most trusted first. */
+const STABLE_ATTRIBUTES = ["data-testid", "data-test-id", "data-qa"];
+/** An id a bundler generated is not an anchor, however unique it is. */
+function looksGenerated(value) {
+    // Long hex-ish or random-looking runs: React's useId (":r1:"), CSS modules,
+    // and most component libraries' generated ids.
+    return (value.length > 40 ||
+        /^:r[0-9a-z]+:$/i.test(value) ||
+        /^[0-9a-f]{16,}$/i.test(value) ||
+        /^(radix|headlessui|mui|chakra)-/i.test(value));
+}
+function escapeIdent(value) {
+    // CSS.escape exists everywhere the toolbar runs, but jsdom in older setups
+    // and a stray non-browser import should not throw.
+    const cssEscape = globalThis
+        .CSS?.escape;
+    return cssEscape ? cssEscape(value) : value.replace(/[^\w-]/g, "\\$&");
+}
+/** The step that identifies one element among its siblings. */
+function nthOfTypeStep(el) {
+    const tag = el.tagName.toLowerCase();
+    const parent = el.parentElement;
+    if (!parent)
+        return tag;
+    const sameTag = Array.from(parent.children).filter((c) => c.tagName === el.tagName);
+    if (sameTag.length === 1)
+        return tag;
+    return `${tag}:nth-of-type(${sameTag.indexOf(el) + 1})`;
+}
+/**
+ * Build a selector that resolves back to `el`. Returns null when no selector
+ * can be built, which the caller treats as "this element cannot be pinned"
+ * rather than storing an anchor that will not resolve.
+ */
+export function buildSelector(el) {
+    if (el.id && !looksGenerated(el.id)) {
+        const candidate = `#${escapeIdent(el.id)}`;
+        if (resolvesUniquely(candidate, el))
+            return candidate;
+    }
+    for (const attr of STABLE_ATTRIBUTES) {
+        const value = el.getAttribute(attr);
+        if (value) {
+            const candidate = `[${attr}="${cssStringEscape(value)}"]`;
+            if (resolvesUniquely(candidate, el))
+                return candidate;
+        }
+    }
+    // Walk up, prepending steps, and stop as soon as the path is unique. Anchor
+    // on an id or test id above if one turns up, which keeps the selector short
+    // and unaffected by anything that changes outside that subtree.
+    const steps = [];
+    let current = el;
+    while (current && current !== document.documentElement) {
+        steps.unshift(nthOfTypeStep(current));
+        const parent = current.parentElement;
+        if (parent) {
+            const anchor = anchorFor(parent);
+            if (anchor) {
+                const candidate = `${anchor} > ${steps.join(" > ")}`;
+                if (resolvesUniquely(candidate, el))
+                    return candidate;
+            }
+        }
+        const candidate = steps.join(" > ");
+        if (resolvesUniquely(candidate, el))
+            return candidate;
+        current = parent;
+    }
+    const full = steps.join(" > ");
+    return resolvesUniquely(full, el) ? full : null;
+}
+function anchorFor(el) {
+    if (el.id && !looksGenerated(el.id))
+        return `#${escapeIdent(el.id)}`;
+    for (const attr of STABLE_ATTRIBUTES) {
+        const value = el.getAttribute(attr);
+        if (value)
+            return `[${attr}="${cssStringEscape(value)}"]`;
+    }
+    return null;
+}
+function cssStringEscape(value) {
+    return value.replace(/["\\]/g, "\\$&");
+}
+function resolvesUniquely(selector, el) {
+    try {
+        const found = document.querySelectorAll(selector);
+        return found.length === 1 && found[0] === el;
+    }
+    catch {
+        return false;
+    }
+}
+/** Resolve a stored selector, or null when the element is no longer there. */
+export function resolveSelector(selector) {
+    try {
+        return document.querySelector(selector);
+    }
+    catch {
+        return null;
+    }
+}
+/** Where inside an element a click landed, as fractions of its box. */
+export function offsetWithin(el, clientX, clientY) {
+    const rect = el.getBoundingClientRect();
+    // Fractions rather than pixels so the dot stays where the reviewer put it
+    // when the element is a different size on a different viewport.
+    const offsetX = rect.width > 0 ? (clientX - rect.left) / rect.width : 0.5;
+    const offsetY = rect.height > 0 ? (clientY - rect.top) / rect.height : 0.5;
+    return {
+        offsetX: Math.min(1, Math.max(0, offsetX)),
+        offsetY: Math.min(1, Math.max(0, offsetY)),
+    };
+}
+/** Viewport position of a stored anchor, or null when it no longer resolves. */
+export function locatePin(selector, offsetX, offsetY) {
+    const el = resolveSelector(selector);
+    if (!el)
+        return null;
+    const rect = el.getBoundingClientRect();
+    if (rect.width === 0 && rect.height === 0)
+        return null;
+    return {
+        x: rect.left + rect.width * offsetX,
+        y: rect.top + rect.height * offsetY,
+    };
+}
+//# sourceMappingURL=selector.js.map