libretto 0.1.4 → 0.2.0

package/dist/shared/visualization/ghost-cursor.cjs

@@ -0,0 +1,174 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var ghost_cursor_exports = {};
+__export(ghost_cursor_exports, {
+  ensureGhostCursor: () => ensureGhostCursor,
+  getGhostCursorPosition: () => getGhostCursorPosition,
+  ghostClick: () => ghostClick,
+  hideGhostCursor: () => hideGhostCursor,
+  moveGhostCursor: () => moveGhostCursor,
+  moveGhostCursorWithDistance: () => moveGhostCursorWithDistance
+});
+module.exports = __toCommonJS(ghost_cursor_exports);
+const DEFAULTS = {
+  style: "minimal",
+  color: "rgba(255, 70, 70, 0.9)",
+  size: 20,
+  zIndex: 2147483646,
+  easing: "cubic-bezier(0.16, 1, 0.3, 1)",
+  minDurationMs: 100,
+  maxDurationMs: 600,
+  speedPxPerMs: 1.5
+};
+const CURSOR_ID = "__libretto_ghost_cursor__";
+function buildCursorSvg(style, color, size) {
+  if (style === "dot") {
+    return `<div style="width:${size}px;height:${size}px;border-radius:50%;background:${color};"></div>`;
+  }
+  if (style === "screenstudio") {
+    return `<div style="width:${size * 1.4}px;height:${size * 1.4}px;border-radius:50%;background:${color};box-shadow:0 0 ${size * 0.6}px ${color};opacity:0.7;"></div>`;
+  }
+  return `<svg width="${size}" height="${size}" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+		<path d="M5 3L19 12L12 13L9 20L5 3Z" fill="${color}" stroke="rgba(0,0,0,0.3)" stroke-width="1"/>
+	</svg>`;
+}
+function buildInitScript(opts) {
+  const svg = buildCursorSvg(opts.style, opts.color, opts.size);
+  return `
+(function() {
+	if (document.getElementById("${CURSOR_ID}")) return;
+	var el = document.createElement("div");
+	el.id = "${CURSOR_ID}";
+	el.style.cssText = "position:fixed;top:0;left:0;z-index:${opts.zIndex};pointer-events:none;transform:translate3d(-100px,-100px,0);transition:none;will-change:transform,opacity;opacity:0;";
+	el.innerHTML = ${JSON.stringify(svg)};
+	document.documentElement.appendChild(el);
+})();
+`;
+}
+const installedPages = /* @__PURE__ */ new WeakSet();
+async function ensureGhostCursor(page, options) {
+  const existingOpts = page.__librettoGhostCursorOpts;
+  const opts = { ...DEFAULTS, ...existingOpts ?? {}, ...options };
+  const initScript = buildInitScript(opts);
+  if (!installedPages.has(page)) {
+    installedPages.add(page);
+    await page.addInitScript({ content: initScript });
+  }
+  page.__librettoGhostCursorOpts = opts;
+  try {
+    await page.evaluate(new Function(initScript));
+  } catch {
+  }
+}
+async function moveGhostCursor(page, target) {
+  const opts = page.__librettoGhostCursorOpts ?? DEFAULTS;
+  const durationMs = target.durationMs ?? Math.min(
+    opts.maxDurationMs,
+    Math.max(opts.minDurationMs, 200)
+    // default ~200ms if no distance info
+  );
+  try {
+    await page.evaluate(
+      ({ id, x, y, duration, easing }) => {
+        const el = document.getElementById(id);
+        if (!el) return;
+        el.style.opacity = "1";
+        el.style.transition = `transform ${duration}ms ${easing}`;
+        el.style.transform = `translate3d(${x}px, ${y}px, 0)`;
+      },
+      { id: CURSOR_ID, x: target.x, y: target.y, duration: durationMs, easing: opts.easing }
+    );
+    await page.waitForTimeout(durationMs);
+  } catch {
+  }
+}
+async function moveGhostCursorWithDistance(page, from, to) {
+  const opts = page.__librettoGhostCursorOpts ?? DEFAULTS;
+  const dx = to.x - from.x;
+  const dy = to.y - from.y;
+  const distance = Math.sqrt(dx * dx + dy * dy);
+  const durationMs = Math.min(
+    opts.maxDurationMs,
+    Math.max(opts.minDurationMs, distance / opts.speedPxPerMs)
+  );
+  await moveGhostCursor(page, { x: to.x, y: to.y, durationMs });
+}
+async function ghostClick(page, target) {
+  try {
+    await page.evaluate(
+      ({ id, x, y }) => {
+        const el = document.getElementById(id);
+        if (!el) return;
+        el.style.transform = `translate3d(${x}px, ${y}px, 0) scale(0.93)`;
+        el.style.transition = "transform 80ms ease-out";
+      },
+      { id: CURSOR_ID, x: target.x, y: target.y }
+    );
+    await page.waitForTimeout(100);
+    await page.evaluate(
+      ({ id, x, y }) => {
+        const el = document.getElementById(id);
+        if (!el) return;
+        el.style.transform = `translate3d(${x}px, ${y}px, 0) scale(1)`;
+        el.style.transition = "transform 120ms ease-out";
+      },
+      { id: CURSOR_ID, x: target.x, y: target.y }
+    );
+    await page.waitForTimeout(130);
+  } catch {
+  }
+}
+async function hideGhostCursor(page) {
+  try {
+    await page.evaluate(
+      ({ id }) => {
+        const el = document.getElementById(id);
+        if (!el) return;
+        el.style.transition = "opacity 300ms ease-out";
+        el.style.opacity = "0";
+      },
+      { id: CURSOR_ID }
+    );
+  } catch {
+  }
+}
+async function getGhostCursorPosition(page) {
+  try {
+    return await page.evaluate(({ id }) => {
+      const el = document.getElementById(id);
+      if (!el) return null;
+      const match = el.style.transform.match(
+        /translate3d\(\s*([\d.-]+)px\s*,\s*([\d.-]+)px/
+      );
+      if (!match) return null;
+      return { x: parseFloat(match[1]), y: parseFloat(match[2]) };
+    }, { id: CURSOR_ID });
+  } catch {
+    return null;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ensureGhostCursor,
+  getGhostCursorPosition,
+  ghostClick,
+  hideGhostCursor,
+  moveGhostCursor,
+  moveGhostCursorWithDistance
+});

package/dist/shared/visualization/ghost-cursor.d.cts

@@ -0,0 +1,37 @@
+import { Page } from 'playwright';
+
+type GhostCursorStyle = "minimal" | "dot" | "screenstudio";
+type GhostCursorOptions = {
+    style?: GhostCursorStyle;
+    color?: string;
+    size?: number;
+    zIndex?: number;
+    easing?: string;
+    minDurationMs?: number;
+    maxDurationMs?: number;
+    speedPxPerMs?: number;
+};
+declare function ensureGhostCursor(page: Page, options?: GhostCursorOptions): Promise<void>;
+declare function moveGhostCursor(page: Page, target: {
+    x: number;
+    y: number;
+    durationMs?: number;
+}): Promise<void>;
+declare function moveGhostCursorWithDistance(page: Page, from: {
+    x: number;
+    y: number;
+}, to: {
+    x: number;
+    y: number;
+}): Promise<void>;
+declare function ghostClick(page: Page, target: {
+    x: number;
+    y: number;
+}): Promise<void>;
+declare function hideGhostCursor(page: Page): Promise<void>;
+declare function getGhostCursorPosition(page: Page): Promise<{
+    x: number;
+    y: number;
+} | null>;
+
+export { type GhostCursorOptions, type GhostCursorStyle, ensureGhostCursor, getGhostCursorPosition, ghostClick, hideGhostCursor, moveGhostCursor, moveGhostCursorWithDistance };

package/dist/shared/visualization/ghost-cursor.d.ts

@@ -0,0 +1,37 @@
+import { Page } from 'playwright';
+
+type GhostCursorStyle = "minimal" | "dot" | "screenstudio";
+type GhostCursorOptions = {
+    style?: GhostCursorStyle;
+    color?: string;
+    size?: number;
+    zIndex?: number;
+    easing?: string;
+    minDurationMs?: number;
+    maxDurationMs?: number;
+    speedPxPerMs?: number;
+};
+declare function ensureGhostCursor(page: Page, options?: GhostCursorOptions): Promise<void>;
+declare function moveGhostCursor(page: Page, target: {
+    x: number;
+    y: number;
+    durationMs?: number;
+}): Promise<void>;
+declare function moveGhostCursorWithDistance(page: Page, from: {
+    x: number;
+    y: number;
+}, to: {
+    x: number;
+    y: number;
+}): Promise<void>;
+declare function ghostClick(page: Page, target: {
+    x: number;
+    y: number;
+}): Promise<void>;
+declare function hideGhostCursor(page: Page): Promise<void>;
+declare function getGhostCursorPosition(page: Page): Promise<{
+    x: number;
+    y: number;
+} | null>;
+
+export { type GhostCursorOptions, type GhostCursorStyle, ensureGhostCursor, getGhostCursorPosition, ghostClick, hideGhostCursor, moveGhostCursor, moveGhostCursorWithDistance };

package/dist/shared/visualization/ghost-cursor.js

@@ -0,0 +1,145 @@
+const DEFAULTS = {
+  style: "minimal",
+  color: "rgba(255, 70, 70, 0.9)",
+  size: 20,
+  zIndex: 2147483646,
+  easing: "cubic-bezier(0.16, 1, 0.3, 1)",
+  minDurationMs: 100,
+  maxDurationMs: 600,
+  speedPxPerMs: 1.5
+};
+const CURSOR_ID = "__libretto_ghost_cursor__";
+function buildCursorSvg(style, color, size) {
+  if (style === "dot") {
+    return `<div style="width:${size}px;height:${size}px;border-radius:50%;background:${color};"></div>`;
+  }
+  if (style === "screenstudio") {
+    return `<div style="width:${size * 1.4}px;height:${size * 1.4}px;border-radius:50%;background:${color};box-shadow:0 0 ${size * 0.6}px ${color};opacity:0.7;"></div>`;
+  }
+  return `<svg width="${size}" height="${size}" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+		<path d="M5 3L19 12L12 13L9 20L5 3Z" fill="${color}" stroke="rgba(0,0,0,0.3)" stroke-width="1"/>
+	</svg>`;
+}
+function buildInitScript(opts) {
+  const svg = buildCursorSvg(opts.style, opts.color, opts.size);
+  return `
+(function() {
+	if (document.getElementById("${CURSOR_ID}")) return;
+	var el = document.createElement("div");
+	el.id = "${CURSOR_ID}";
+	el.style.cssText = "position:fixed;top:0;left:0;z-index:${opts.zIndex};pointer-events:none;transform:translate3d(-100px,-100px,0);transition:none;will-change:transform,opacity;opacity:0;";
+	el.innerHTML = ${JSON.stringify(svg)};
+	document.documentElement.appendChild(el);
+})();
+`;
+}
+const installedPages = /* @__PURE__ */ new WeakSet();
+async function ensureGhostCursor(page, options) {
+  const existingOpts = page.__librettoGhostCursorOpts;
+  const opts = { ...DEFAULTS, ...existingOpts ?? {}, ...options };
+  const initScript = buildInitScript(opts);
+  if (!installedPages.has(page)) {
+    installedPages.add(page);
+    await page.addInitScript({ content: initScript });
+  }
+  page.__librettoGhostCursorOpts = opts;
+  try {
+    await page.evaluate(new Function(initScript));
+  } catch {
+  }
+}
+async function moveGhostCursor(page, target) {
+  const opts = page.__librettoGhostCursorOpts ?? DEFAULTS;
+  const durationMs = target.durationMs ?? Math.min(
+    opts.maxDurationMs,
+    Math.max(opts.minDurationMs, 200)
+    // default ~200ms if no distance info
+  );
+  try {
+    await page.evaluate(
+      ({ id, x, y, duration, easing }) => {
+        const el = document.getElementById(id);
+        if (!el) return;
+        el.style.opacity = "1";
+        el.style.transition = `transform ${duration}ms ${easing}`;
+        el.style.transform = `translate3d(${x}px, ${y}px, 0)`;
+      },
+      { id: CURSOR_ID, x: target.x, y: target.y, duration: durationMs, easing: opts.easing }
+    );
+    await page.waitForTimeout(durationMs);
+  } catch {
+  }
+}
+async function moveGhostCursorWithDistance(page, from, to) {
+  const opts = page.__librettoGhostCursorOpts ?? DEFAULTS;
+  const dx = to.x - from.x;
+  const dy = to.y - from.y;
+  const distance = Math.sqrt(dx * dx + dy * dy);
+  const durationMs = Math.min(
+    opts.maxDurationMs,
+    Math.max(opts.minDurationMs, distance / opts.speedPxPerMs)
+  );
+  await moveGhostCursor(page, { x: to.x, y: to.y, durationMs });
+}
+async function ghostClick(page, target) {
+  try {
+    await page.evaluate(
+      ({ id, x, y }) => {
+        const el = document.getElementById(id);
+        if (!el) return;
+        el.style.transform = `translate3d(${x}px, ${y}px, 0) scale(0.93)`;
+        el.style.transition = "transform 80ms ease-out";
+      },
+      { id: CURSOR_ID, x: target.x, y: target.y }
+    );
+    await page.waitForTimeout(100);
+    await page.evaluate(
+      ({ id, x, y }) => {
+        const el = document.getElementById(id);
+        if (!el) return;
+        el.style.transform = `translate3d(${x}px, ${y}px, 0) scale(1)`;
+        el.style.transition = "transform 120ms ease-out";
+      },
+      { id: CURSOR_ID, x: target.x, y: target.y }
+    );
+    await page.waitForTimeout(130);
+  } catch {
+  }
+}
+async function hideGhostCursor(page) {
+  try {
+    await page.evaluate(
+      ({ id }) => {
+        const el = document.getElementById(id);
+        if (!el) return;
+        el.style.transition = "opacity 300ms ease-out";
+        el.style.opacity = "0";
+      },
+      { id: CURSOR_ID }
+    );
+  } catch {
+  }
+}
+async function getGhostCursorPosition(page) {
+  try {
+    return await page.evaluate(({ id }) => {
+      const el = document.getElementById(id);
+      if (!el) return null;
+      const match = el.style.transform.match(
+        /translate3d\(\s*([\d.-]+)px\s*,\s*([\d.-]+)px/
+      );
+      if (!match) return null;
+      return { x: parseFloat(match[1]), y: parseFloat(match[2]) };
+    }, { id: CURSOR_ID });
+  } catch {
+    return null;
+  }
+}
+export {
+  ensureGhostCursor,
+  getGhostCursorPosition,
+  ghostClick,
+  hideGhostCursor,
+  moveGhostCursor,
+  moveGhostCursorWithDistance
+};

package/dist/shared/visualization/highlight.cjs

@@ -0,0 +1,134 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var highlight_exports = {};
+__export(highlight_exports, {
+  clearHighlights: () => clearHighlights,
+  ensureHighlightLayer: () => ensureHighlightLayer,
+  showHighlight: () => showHighlight
+});
+module.exports = __toCommonJS(highlight_exports);
+const HIGHLIGHT_DEFAULTS = {
+  color: "rgba(59, 130, 246, 0.25)",
+  zIndex: 2147483645
+};
+const LAYER_ID = "__libretto_highlight_layer__";
+function buildHighlightInitScript(opts) {
+  return `
+(function() {
+	if (document.getElementById("${LAYER_ID}")) return;
+	var el = document.createElement("div");
+	el.id = "${LAYER_ID}";
+	el.style.cssText = "position:fixed;top:0;left:0;width:100%;height:100%;z-index:${opts.zIndex};pointer-events:none;overflow:hidden;";
+	document.documentElement.appendChild(el);
+})();
+`;
+}
+const installedPages = /* @__PURE__ */ new WeakSet();
+async function ensureHighlightLayer(page, options) {
+  const existingOpts = page.__librettoHighlightOpts;
+  const zIndex = options?.zIndex ?? existingOpts?.zIndex ?? HIGHLIGHT_DEFAULTS.zIndex;
+  const initScript = buildHighlightInitScript({ zIndex });
+  if (!installedPages.has(page)) {
+    installedPages.add(page);
+    await page.addInitScript({ content: initScript });
+  }
+  page.__librettoHighlightOpts = {
+    color: options?.color ?? existingOpts?.color ?? HIGHLIGHT_DEFAULTS.color,
+    zIndex
+  };
+  try {
+    await page.evaluate(new Function(initScript));
+  } catch {
+  }
+}
+async function showHighlight(page, params) {
+  const opts = page.__librettoHighlightOpts ?? HIGHLIGHT_DEFAULTS;
+  const color = params.color ?? opts.color;
+  const durationMs = params.durationMs ?? 350;
+  try {
+    await page.evaluate(
+      ({ layerId, box, color: color2, label, durationMs: durationMs2 }) => {
+        const layer = document.getElementById(layerId);
+        if (!layer) return;
+        const rect = document.createElement("div");
+        rect.className = "__libretto_highlight_rect__";
+        rect.style.cssText = `
+					position:absolute;
+					left:${box.x}px;
+					top:${box.y}px;
+					width:${box.width}px;
+					height:${box.height}px;
+					background:${color2};
+					border:2px solid ${color2.replace(/[\d.]+\)$/, "0.6)")};
+					border-radius:3px;
+					pointer-events:none;
+					transition:opacity 200ms ease-out;
+					opacity:1;
+				`;
+        if (label) {
+          const labelEl = document.createElement("div");
+          labelEl.textContent = label;
+          labelEl.style.cssText = `
+						position:absolute;
+						top:-22px;
+						left:0;
+						font:11px/1.2 -apple-system,BlinkMacSystemFont,sans-serif;
+						color:#fff;
+						background:rgba(0,0,0,0.7);
+						padding:2px 6px;
+						border-radius:3px;
+						white-space:nowrap;
+						pointer-events:none;
+					`;
+          rect.appendChild(labelEl);
+        }
+        layer.appendChild(rect);
+        setTimeout(() => {
+          rect.style.opacity = "0";
+          setTimeout(() => rect.remove(), 250);
+        }, durationMs2);
+      },
+      {
+        layerId: LAYER_ID,
+        box: params.box,
+        color,
+        label: params.label,
+        durationMs
+      }
+    );
+  } catch {
+  }
+}
+async function clearHighlights(page) {
+  try {
+    await page.evaluate(({ layerId }) => {
+      const layer = document.getElementById(layerId);
+      if (!layer) return;
+      const rects = layer.querySelectorAll(".__libretto_highlight_rect__");
+      rects.forEach((r) => r.remove());
+    }, { layerId: LAYER_ID });
+  } catch {
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  clearHighlights,
+  ensureHighlightLayer,
+  showHighlight
+});

package/dist/shared/visualization/highlight.d.cts

@@ -0,0 +1,22 @@
+import { Page } from 'playwright';
+
+type HighlightOptions = {
+    color?: string;
+    zIndex?: number;
+};
+declare function ensureHighlightLayer(page: Page, options?: HighlightOptions): Promise<void>;
+type ShowHighlightParams = {
+    box: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    label?: string;
+    color?: string;
+    durationMs?: number;
+};
+declare function showHighlight(page: Page, params: ShowHighlightParams): Promise<void>;
+declare function clearHighlights(page: Page): Promise<void>;
+
+export { type HighlightOptions, type ShowHighlightParams, clearHighlights, ensureHighlightLayer, showHighlight };

package/dist/shared/visualization/highlight.d.ts

@@ -0,0 +1,22 @@
+import { Page } from 'playwright';
+
+type HighlightOptions = {
+    color?: string;
+    zIndex?: number;
+};
+declare function ensureHighlightLayer(page: Page, options?: HighlightOptions): Promise<void>;
+type ShowHighlightParams = {
+    box: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    label?: string;
+    color?: string;
+    durationMs?: number;
+};
+declare function showHighlight(page: Page, params: ShowHighlightParams): Promise<void>;
+declare function clearHighlights(page: Page): Promise<void>;
+
+export { type HighlightOptions, type ShowHighlightParams, clearHighlights, ensureHighlightLayer, showHighlight };

package/dist/shared/visualization/highlight.js

@@ -0,0 +1,108 @@
+const HIGHLIGHT_DEFAULTS = {
+  color: "rgba(59, 130, 246, 0.25)",
+  zIndex: 2147483645
+};
+const LAYER_ID = "__libretto_highlight_layer__";
+function buildHighlightInitScript(opts) {
+  return `
+(function() {
+	if (document.getElementById("${LAYER_ID}")) return;
+	var el = document.createElement("div");
+	el.id = "${LAYER_ID}";
+	el.style.cssText = "position:fixed;top:0;left:0;width:100%;height:100%;z-index:${opts.zIndex};pointer-events:none;overflow:hidden;";
+	document.documentElement.appendChild(el);
+})();
+`;
+}
+const installedPages = /* @__PURE__ */ new WeakSet();
+async function ensureHighlightLayer(page, options) {
+  const existingOpts = page.__librettoHighlightOpts;
+  const zIndex = options?.zIndex ?? existingOpts?.zIndex ?? HIGHLIGHT_DEFAULTS.zIndex;
+  const initScript = buildHighlightInitScript({ zIndex });
+  if (!installedPages.has(page)) {
+    installedPages.add(page);
+    await page.addInitScript({ content: initScript });
+  }
+  page.__librettoHighlightOpts = {
+    color: options?.color ?? existingOpts?.color ?? HIGHLIGHT_DEFAULTS.color,
+    zIndex
+  };
+  try {
+    await page.evaluate(new Function(initScript));
+  } catch {
+  }
+}
+async function showHighlight(page, params) {
+  const opts = page.__librettoHighlightOpts ?? HIGHLIGHT_DEFAULTS;
+  const color = params.color ?? opts.color;
+  const durationMs = params.durationMs ?? 350;
+  try {
+    await page.evaluate(
+      ({ layerId, box, color: color2, label, durationMs: durationMs2 }) => {
+        const layer = document.getElementById(layerId);
+        if (!layer) return;
+        const rect = document.createElement("div");
+        rect.className = "__libretto_highlight_rect__";
+        rect.style.cssText = `
+					position:absolute;
+					left:${box.x}px;
+					top:${box.y}px;
+					width:${box.width}px;
+					height:${box.height}px;
+					background:${color2};
+					border:2px solid ${color2.replace(/[\d.]+\)$/, "0.6)")};
+					border-radius:3px;
+					pointer-events:none;
+					transition:opacity 200ms ease-out;
+					opacity:1;
+				`;
+        if (label) {
+          const labelEl = document.createElement("div");
+          labelEl.textContent = label;
+          labelEl.style.cssText = `
+						position:absolute;
+						top:-22px;
+						left:0;
+						font:11px/1.2 -apple-system,BlinkMacSystemFont,sans-serif;
+						color:#fff;
+						background:rgba(0,0,0,0.7);
+						padding:2px 6px;
+						border-radius:3px;
+						white-space:nowrap;
+						pointer-events:none;
+					`;
+          rect.appendChild(labelEl);
+        }
+        layer.appendChild(rect);
+        setTimeout(() => {
+          rect.style.opacity = "0";
+          setTimeout(() => rect.remove(), 250);
+        }, durationMs2);
+      },
+      {
+        layerId: LAYER_ID,
+        box: params.box,
+        color,
+        label: params.label,
+        durationMs
+      }
+    );
+  } catch {
+  }
+}
+async function clearHighlights(page) {
+  try {
+    await page.evaluate(({ layerId }) => {
+      const layer = document.getElementById(layerId);
+      if (!layer) return;
+      const rects = layer.querySelectorAll(".__libretto_highlight_rect__");
+      rects.forEach((r) => r.remove());
+    }, { layerId: LAYER_ID });
+  } catch {
+  }
+}
+export {
+  clearHighlights,
+  ensureHighlightLayer,
+  showHighlight
+};