@remixmate/cli 0.1.0 → 0.1.1

package/skills/web-capture/scripts/_media_screenshot/browser.py

@@ -0,0 +1,86 @@
+"""Browser context / locator / wait helpers."""
+from __future__ import annotations
+
+from typing import Any
+
+from . import js_loader
+from .bootstrap import ensure_chromium
+
+
+def pick_browser_type(p, name: str | None):
+    if name == "firefox":
+        return p.firefox
+    if name == "webkit":
+        return p.webkit
+    return p.chromium
+
+
+def build_context_options(p, cfg: dict, record_video_dir: str | None) -> dict:
+    opts: dict[str, Any] = {}
+    if cfg.get("device"):
+        d = p.devices.get(cfg["device"])
+        if not d:
+            raise SystemExit(f"unknown device: {cfg['device']}")
+        opts.update(d)
+    elif isinstance(cfg.get("viewport"), (list, tuple)) and len(cfg["viewport"]) == 2:
+        opts["viewport"] = {
+            "width": int(cfg["viewport"][0]),
+            "height": int(cfg["viewport"][1]),
+        }
+    if cfg.get("colorScheme"):
+        opts["color_scheme"] = cfg["colorScheme"]
+    if cfg.get("userAgent"):
+        opts["user_agent"] = cfg["userAgent"]
+    if cfg.get("ignoreHttpsErrors"):
+        opts["ignore_https_errors"] = True
+    if cfg.get("storageState"):
+        opts["storage_state"] = cfg["storageState"]
+    if record_video_dir:
+        opts["record_video_dir"] = record_video_dir
+        if opts.get("viewport"):
+            opts["record_video_size"] = opts["viewport"]
+    return opts
+
+
+def launch_with_browser_install(p, browser_name: str | None, launch_kwargs: dict | None = None):
+    btype = pick_browser_type(p, browser_name)
+    try:
+        return btype.launch(**(launch_kwargs or {}))
+    except Exception as e:
+        msg = str(e)
+        if "Executable doesn't exist" in msg or "playwright install" in msg.lower():
+            ensure_chromium()
+            return btype.launch(**(launch_kwargs or {}))
+        raise
+
+
+def apply_pre_action_waits(page, cfg: dict) -> None:
+    if cfg.get("waitForSelector"):
+        page.wait_for_selector(cfg["waitForSelector"], timeout=cfg.get("timeout", 0))
+    if isinstance(cfg.get("waitForTimeout"), (int, float)):
+        page.wait_for_timeout(cfg["waitForTimeout"])
+
+
+def wait_until_settled(page, cfg: dict) -> None:
+    try:
+        page.wait_for_load_state("networkidle", timeout=20000)
+    except Exception:
+        pass
+    try:
+        page.wait_for_function(js_loader.load("settled_check"), timeout=15000)
+    except Exception:
+        pass
+    for sel in cfg.get("waitForReadySelectors") or []:
+        try:
+            page.wait_for_selector(sel, state="visible", timeout=10000)
+        except Exception:
+            pass
+    page.wait_for_timeout(cfg.get("settleMs", 800))
+
+
+def resolve_locator(page, selector: str):
+    locator = page.locator(selector).first
+    locator.wait_for(state="visible", timeout=15000)
+    locator.scroll_into_view_if_needed()
+    page.wait_for_timeout(250)
+    return locator

package/skills/web-capture/scripts/_media_screenshot/cli_args.py

@@ -0,0 +1,111 @@
+"""Argparse helpers shared by ``screenshot.py`` and ``record.py``."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import tempfile
+from pathlib import Path
+
+
+def add_common_args(ap: argparse.ArgumentParser) -> None:
+    """Add the args common to both screenshot and record entry points."""
+    ap.add_argument(
+        "-b", "--browser", choices=["chromium", "firefox", "webkit"],
+        default="chromium", help="浏览器内核（默认 chromium）",
+    )
+    ap.add_argument("--device", help='设备模拟名，如 "iPhone 15 Pro"、"Pixel 7"')
+    ap.add_argument(
+        "--viewport",
+        help='viewport "宽,高"，如 "1280,800"；与 --device 互斥时以 --device 为准',
+    )
+    ap.add_argument("--wait-for-selector", help="动作前等待该 CSS 选择器出现")
+    ap.add_argument("--wait-for-timeout", type=int, help="动作前固定等待毫秒数")
+    ap.add_argument(
+        "--color-scheme", choices=["light", "dark", "no-preference"],
+        help="模拟 prefers-color-scheme",
+    )
+    ap.add_argument("--user-agent", help="覆盖 User-Agent")
+    ap.add_argument(
+        "--timeout", type=int, help="Playwright 全局动作超时（ms，默认无超时）",
+    )
+    ap.add_argument(
+        "--ignore-https-errors", action="store_true", help="忽略 HTTPS 证书错误",
+    )
+    ap.add_argument("--storage-state", help="storageState JSON 文件路径")
+    ap.add_argument(
+        "--cookies",
+        help='Playwright cookies JSON 字符串或 JSON 文件路径（顶层为数组）',
+    )
+
+
+def parse_cookies(raw: str) -> list[dict]:
+    p = Path(raw)
+    if p.exists() and p.is_file():
+        try:
+            data = json.loads(p.read_text())
+        except json.JSONDecodeError as e:
+            raise SystemExit(f"--cookies 文件不是合法 JSON：{e}")
+    else:
+        try:
+            data = json.loads(raw)
+        except json.JSONDecodeError:
+            raise SystemExit(
+                "--cookies 需为 JSON 字符串或 JSON 文件路径，顶层为 cookie 数组。"
+            )
+    if not isinstance(data, list):
+        raise SystemExit("--cookies 顶层应为数组（Playwright cookies 格式）。")
+    return data
+
+
+def build_storage(args) -> tuple[str | None, bool]:
+    """Returns (storage_state_path, is_temp). Caller must unlink if is_temp."""
+    if getattr(args, "storage_state", None):
+        return args.storage_state, False
+    if getattr(args, "cookies", None):
+        cookies = parse_cookies(args.cookies)
+        fd, path = tempfile.mkstemp(prefix="pw_storage_", suffix=".json")
+        with os.fdopen(fd, "w") as f:
+            json.dump({"cookies": cookies, "origins": []}, f)
+        return path, True
+    return None, False
+
+
+def parse_viewport(raw: str) -> list[int]:
+    parts = [s.strip() for s in raw.split(",")]
+    if len(parts) != 2:
+        raise SystemExit('--viewport 需为 "宽,高"')
+    try:
+        return [int(p) for p in parts]
+    except ValueError:
+        raise SystemExit("--viewport 必须是整数")
+
+
+def parse_clip(raw: str) -> list[float]:
+    parts = [s.strip() for s in raw.split(",")]
+    if len(parts) != 4:
+        raise SystemExit('--clip 需为 "x,y,w,h" 四个数字')
+    try:
+        return [float(p) for p in parts]
+    except ValueError:
+        raise SystemExit("--clip 的四个值必须是数字")
+
+
+def common_args_to_cfg(args, cfg: dict) -> None:
+    """Merge the common-args values into a cfg dict (shared by entry points)."""
+    if args.device:
+        cfg["device"] = args.device
+    if args.viewport:
+        cfg["viewport"] = parse_viewport(args.viewport)
+    if args.color_scheme:
+        cfg["colorScheme"] = args.color_scheme
+    if args.user_agent:
+        cfg["userAgent"] = args.user_agent
+    if args.timeout is not None:
+        cfg["timeout"] = args.timeout
+    if args.ignore_https_errors:
+        cfg["ignoreHttpsErrors"] = True
+    if args.wait_for_selector:
+        cfg["waitForSelector"] = args.wait_for_selector
+    if args.wait_for_timeout is not None:
+        cfg["waitForTimeout"] = args.wait_for_timeout

package/skills/web-capture/scripts/_media_screenshot/js/arrow.js

@@ -0,0 +1,86 @@
+// Draw a curved SVG arrow from `from` to `to` with an arrowhead, optional label.
+// Both endpoints are page-fixed coordinates (computed in Python from bounding boxes).
+({ from, to, color, lineWidth, label }) => {
+  const root = document.getElementById('__pw_overlay_root');
+  if (!root) return;
+  const NS = 'http://www.w3.org/2000/svg';
+
+  const svg = document.createElementNS(NS, 'svg');
+  Object.assign(svg.style, {
+    position: 'fixed',
+    left: '0',
+    top: '0',
+    width: '100%',
+    height: '100%',
+    pointerEvents: 'none',
+    overflow: 'visible',
+  });
+  svg.setAttribute('viewBox', `0 0 ${window.innerWidth} ${window.innerHeight}`);
+  svg.setAttribute('preserveAspectRatio', 'none');
+
+  const markerId = `__pw_arrow_head_${Math.random().toString(36).slice(2, 8)}`;
+  const defs = document.createElementNS(NS, 'defs');
+  const marker = document.createElementNS(NS, 'marker');
+  marker.setAttribute('id', markerId);
+  marker.setAttribute('viewBox', '0 0 10 10');
+  marker.setAttribute('refX', '8');
+  marker.setAttribute('refY', '5');
+  marker.setAttribute('markerWidth', '6');
+  marker.setAttribute('markerHeight', '6');
+  marker.setAttribute('orient', 'auto-start-reverse');
+  const tri = document.createElementNS(NS, 'path');
+  tri.setAttribute('d', 'M0,0 L10,5 L0,10 z');
+  tri.setAttribute('fill', color);
+  marker.appendChild(tri);
+  defs.appendChild(marker);
+  svg.appendChild(defs);
+
+  const dx = to.x - from.x;
+  const dy = to.y - from.y;
+  const mx = (from.x + to.x) / 2;
+  const my = (from.y + to.y) / 2;
+  const len = Math.hypot(dx, dy) || 1;
+  const curve = Math.min(80, len * 0.22);
+  const ox = (-dy / len) * curve;
+  const oy = (dx / len) * curve;
+
+  const path = document.createElementNS(NS, 'path');
+  path.setAttribute('d', `M ${from.x} ${from.y} Q ${mx + ox} ${my + oy} ${to.x} ${to.y}`);
+  path.setAttribute('stroke', color);
+  path.setAttribute('stroke-width', String(lineWidth));
+  path.setAttribute('fill', 'none');
+  path.setAttribute('stroke-linecap', 'round');
+  path.setAttribute('marker-end', `url(#${markerId})`);
+
+  const dashLen = len * 1.15 + curve;
+  path.setAttribute('stroke-dasharray', String(dashLen));
+  path.setAttribute('stroke-dashoffset', String(dashLen));
+  path.style.transition = 'stroke-dashoffset 600ms ease-out';
+  svg.appendChild(path);
+  root.appendChild(svg);
+  requestAnimationFrame(() => path.setAttribute('stroke-dashoffset', '0'));
+
+  if (label) {
+    const lbl = document.createElement('div');
+    lbl.textContent = label;
+    Object.assign(lbl.style, {
+      position: 'fixed',
+      left: `${from.x}px`,
+      top: `${from.y - 36}px`,
+      transform: 'translateX(-50%)',
+      padding: '6px 12px',
+      background: color,
+      color: '#fff',
+      fontSize: '15px',
+      fontWeight: '600',
+      borderRadius: '6px',
+      fontFamily: 'system-ui, -apple-system, "PingFang SC", "Helvetica Neue", sans-serif',
+      boxShadow: '0 4px 12px rgba(0,0,0,0.25)',
+      whiteSpace: 'nowrap',
+      opacity: '0',
+      transition: 'opacity 400ms ease 200ms',
+    });
+    root.appendChild(lbl);
+    requestAnimationFrame(() => (lbl.style.opacity = '1'));
+  }
+};

package/skills/web-capture/scripts/_media_screenshot/js/caption.js

@@ -0,0 +1,27 @@
+// Slide a caption strip in from the top or bottom edge.
+({ text, position, bg, fg, fontSize }) => {
+  const root = document.getElementById('__pw_overlay_root');
+  if (!root) return;
+  const isTop = position === 'top';
+  const strip = document.createElement('div');
+  strip.textContent = text;
+  Object.assign(strip.style, {
+    position: 'fixed',
+    left: '0',
+    right: '0',
+    [isTop ? 'top' : 'bottom']: '0',
+    padding: '14px 28px',
+    background: bg,
+    color: fg,
+    fontSize: `${fontSize}px`,
+    fontWeight: '600',
+    fontFamily: 'system-ui, -apple-system, "PingFang SC", "Helvetica Neue", sans-serif',
+    textAlign: 'center',
+    transform: `translateY(${isTop ? '-100%' : '100%'})`,
+    transition: 'transform 400ms cubic-bezier(0.22, 0.61, 0.36, 1)',
+    boxShadow: isTop ? '0 4px 16px rgba(0,0,0,0.3)' : '0 -4px 16px rgba(0,0,0,0.3)',
+    lineHeight: '1.4',
+  });
+  root.appendChild(strip);
+  requestAnimationFrame(() => (strip.style.transform = 'translateY(0)'));
+};

package/skills/web-capture/scripts/_media_screenshot/js/clear_overlay.js

@@ -0,0 +1,5 @@
+// Empty the overlay root without removing it (fade element survives).
+() => {
+  const r = document.getElementById('__pw_overlay_root');
+  if (r) r.replaceChildren();
+}

package/skills/web-capture/scripts/_media_screenshot/js/cursor_bootstrap.js

@@ -0,0 +1,26 @@
+// Mount a singleton fake cursor on documentElement (outside overlay root so it
+// survives inter-scene fades). Idempotent.
+() => {
+  if (window.__pwCursor && window.__pwCursor.el && document.body.contains(window.__pwCursor.el)) {
+    return;
+  }
+  const c = document.createElement('div');
+  c.id = '__pw_cursor';
+  Object.assign(c.style, {
+    position: 'fixed',
+    left: '20px',
+    top: '20px',
+    width: '28px',
+    height: '28px',
+    pointerEvents: 'none',
+    zIndex: '2147483647',
+    transition: 'left 0ms linear, top 0ms linear',
+    filter: 'drop-shadow(0 2px 4px rgba(0,0,0,0.45))',
+  });
+  c.innerHTML =
+    '<svg width="28" height="28" viewBox="0 0 28 28" xmlns="http://www.w3.org/2000/svg">' +
+    '<path d="M3 2 L3 22 L9 16 L13 25 L17 23 L13 14 L21 14 Z" ' +
+    'fill="white" stroke="black" stroke-width="1.5" stroke-linejoin="round"/></svg>';
+  document.documentElement.appendChild(c);
+  window.__pwCursor = { el: c, pos: { x: 20, y: 20 } };
+};

package/skills/web-capture/scripts/_media_screenshot/js/cursor_hide.js

@@ -0,0 +1,6 @@
+// Remove the singleton cursor. Safe to call when not mounted.
+() => {
+  const c = window.__pwCursor;
+  if (c && c.el && c.el.parentNode) c.el.parentNode.removeChild(c.el);
+  window.__pwCursor = undefined;
+};

package/skills/web-capture/scripts/_media_screenshot/js/cursor_move.js

@@ -0,0 +1,12 @@
+// Animate the singleton cursor to (x, y) over `ms`. Python side then waits the
+// same amount; this JS just kicks off the CSS transition.
+({ x, y, ms }) => {
+  const c = window.__pwCursor;
+  if (!c) return;
+  c.el.style.transition =
+    `left ${ms}ms cubic-bezier(0.22,0.61,0.36,1), top ${ms}ms cubic-bezier(0.22,0.61,0.36,1)`;
+  c.el.getBoundingClientRect();
+  c.el.style.left = `${x}px`;
+  c.el.style.top = `${y}px`;
+  c.pos = { x, y };
+};

package/skills/web-capture/scripts/_media_screenshot/js/cursor_ripple.js

@@ -0,0 +1,25 @@
+// Emit a ring-shaped ripple at the cursor's current position.
+({ color, ms }) => {
+  const c = window.__pwCursor;
+  if (!c) return;
+  const r = document.createElement('div');
+  Object.assign(r.style, {
+    position: 'fixed',
+    left: `${c.pos.x - 4}px`,
+    top: `${c.pos.y - 4}px`,
+    width: '8px',
+    height: '8px',
+    borderRadius: '999px',
+    border: `2px solid ${color}`,
+    pointerEvents: 'none',
+    zIndex: '2147483647',
+    opacity: '0.9',
+    transition: `transform ${ms}ms ease-out, opacity ${ms}ms ease-out`,
+  });
+  document.documentElement.appendChild(r);
+  requestAnimationFrame(() => {
+    r.style.transform = 'scale(8)';
+    r.style.opacity = '0';
+  });
+  setTimeout(() => r.remove(), ms + 100);
+};

package/skills/web-capture/scripts/_media_screenshot/js/element_zoom.js

@@ -0,0 +1,72 @@
+// Element-level zoom: scale the element itself with a spring transition,
+// optionally dimming the rest of the page. Original styles are stashed on
+// the element's dataset for later restoration by element_zoom_restore.js.
+({ selector, targetScale, rampMs, color, label, dim, lineWidth }) => {
+  const el = document.querySelector(selector);
+  if (!el) return;
+  const rect = el.getBoundingClientRect();
+  const cx = rect.left + rect.width / 2;
+  const cy = rect.top + rect.height / 2;
+  el.dataset.__pwOrigTransform = el.style.transform || '';
+  el.dataset.__pwOrigTransition = el.style.transition || '';
+  el.dataset.__pwOrigOrigin = el.style.transformOrigin || '';
+  el.dataset.__pwOrigZ = el.style.zIndex || '';
+  el.dataset.__pwOrigPos = el.style.position || '';
+  el.dataset.__pwOrigBg = el.style.backgroundColor || '';
+  el.dataset.__pwOrigOutline = el.style.outline || '';
+  el.dataset.__pwOrigRadius = el.style.borderRadius || '';
+
+  const root = document.getElementById('__pw_overlay_root');
+  if (dim) {
+    const dimEl = document.createElement('div');
+    dimEl.id = '__pw_zoom_dim';
+    Object.assign(dimEl.style, {
+      position: 'fixed', inset: '0', background: 'rgba(0,0,0,0)',
+      transition: `background ${rampMs}ms ease`, zIndex: '2147483640',
+      pointerEvents: 'none',
+    });
+    root.appendChild(dimEl);
+    requestAnimationFrame(() => {
+      dimEl.style.background = 'rgba(0,0,0,0.55)';
+    });
+  }
+
+  const computed = window.getComputedStyle(el);
+  if (computed.position === 'static') el.style.position = 'relative';
+  el.style.zIndex = '2147483645';
+  el.style.transformOrigin = `${cx - rect.left}px ${cy - rect.top}px`;
+  el.style.transition = `transform ${rampMs}ms cubic-bezier(0.34, 1.4, 0.64, 1), background-color ${rampMs}ms ease, outline-color ${rampMs}ms ease`;
+  el.style.transform = 'scale(1)';
+  el.style.outline = `${lineWidth}px solid rgba(255,149,0,0)`;
+  el.style.borderRadius = el.dataset.__pwOrigRadius || '6px';
+  requestAnimationFrame(() => {
+    el.style.transform = `scale(${targetScale})`;
+    el.style.outline = `${lineWidth}px solid ${color}`;
+  });
+
+  if (label) {
+    const lbl = document.createElement('div');
+    lbl.id = '__pw_zoom_label';
+    lbl.textContent = label;
+    const finalH = rect.height * targetScale;
+    Object.assign(lbl.style, {
+      position: 'fixed',
+      left: `${cx}px`,
+      top: `${cy + finalH / 2 + 24}px`,
+      transform: 'translateX(-50%) translateY(8px)',
+      padding: '10px 18px',
+      background: color, color: '#fff',
+      fontSize: '20px', fontWeight: '700', borderRadius: '8px',
+      fontFamily: 'system-ui, -apple-system, "Helvetica Neue", sans-serif',
+      boxShadow: '0 6px 18px rgba(0,0,0,0.4)',
+      whiteSpace: 'nowrap', opacity: '0',
+      transition: 'opacity 280ms ease, transform 280ms ease',
+      zIndex: '2147483646', pointerEvents: 'none',
+    });
+    root.appendChild(lbl);
+    setTimeout(() => {
+      lbl.style.opacity = '1';
+      lbl.style.transform = 'translateX(-50%) translateY(0)';
+    }, Math.max(0, rampMs * 0.6));
+  }
+}

package/skills/web-capture/scripts/_media_screenshot/js/element_zoom_restore.js

@@ -0,0 +1,21 @@
+// Restore the inline styles stashed by element_zoom.js on the target element.
+(selector) => {
+  const el = document.querySelector(selector);
+  if (!el) return;
+  el.style.transform = el.dataset.__pwOrigTransform || '';
+  el.style.transition = el.dataset.__pwOrigTransition || '';
+  el.style.transformOrigin = el.dataset.__pwOrigOrigin || '';
+  el.style.zIndex = el.dataset.__pwOrigZ || '';
+  el.style.position = el.dataset.__pwOrigPos || '';
+  el.style.backgroundColor = el.dataset.__pwOrigBg || '';
+  el.style.outline = el.dataset.__pwOrigOutline || '';
+  el.style.borderRadius = el.dataset.__pwOrigRadius || '';
+  delete el.dataset.__pwOrigTransform;
+  delete el.dataset.__pwOrigTransition;
+  delete el.dataset.__pwOrigOrigin;
+  delete el.dataset.__pwOrigZ;
+  delete el.dataset.__pwOrigPos;
+  delete el.dataset.__pwOrigBg;
+  delete el.dataset.__pwOrigOutline;
+  delete el.dataset.__pwOrigRadius;
+}

package/skills/web-capture/scripts/_media_screenshot/js/fade_out_overlays.js

@@ -0,0 +1,10 @@
+// Fade every child of the overlay root to opacity 0 over `duration` ms.
+// Page content underneath stays visible — this is the inter-scene transition.
+(duration) => {
+  const root = document.getElementById('__pw_overlay_root');
+  if (!root) return;
+  for (const child of root.children) {
+    child.style.transition = `opacity ${duration}ms ease, transform ${duration}ms ease`;
+    child.style.opacity = '0';
+  }
+}

package/skills/web-capture/scripts/_media_screenshot/js/focus.js

@@ -0,0 +1,38 @@
+// Spotlight effect: dim everything except a rounded cut-out around `box`.
+({ box, pad, label, color }) => {
+  const root = document.getElementById('__pw_overlay_root');
+  if (!root) return;
+  const hole = document.createElement('div');
+  Object.assign(hole.style, {
+    position: 'fixed',
+    left: `${box.x - pad}px`,
+    top: `${box.y - pad}px`,
+    width: `${box.width + pad * 2}px`,
+    height: `${box.height + pad * 2}px`,
+    borderRadius: '12px',
+    boxShadow: '0 0 0 9999px rgba(0,0,0,0.65)',
+    border: `3px solid ${color}`,
+    transition: 'box-shadow 400ms ease',
+  });
+  root.appendChild(hole);
+  if (label) {
+    const lbl = document.createElement('div');
+    lbl.textContent = label;
+    Object.assign(lbl.style, {
+      position: 'fixed',
+      left: `${box.x + box.width / 2}px`,
+      top: `${box.y + box.height + pad + 16}px`,
+      transform: 'translateX(-50%)',
+      padding: '10px 18px',
+      background: color,
+      color: '#fff',
+      fontSize: '20px',
+      fontWeight: '700',
+      borderRadius: '8px',
+      fontFamily: 'system-ui, -apple-system, "Helvetica Neue", sans-serif',
+      boxShadow: '0 6px 18px rgba(0,0,0,0.4)',
+      whiteSpace: 'nowrap',
+    });
+    root.appendChild(lbl);
+  }
+}

package/skills/web-capture/scripts/_media_screenshot/js/highlight.js

@@ -0,0 +1,97 @@
+// Draw a rectangle around `box` with an optional label badge.
+//   drawOnMs > 0  → SVG rect with stroke-dashoffset animation: traces from the
+//                   top-left clockwise (top edge sweeps left→right first).
+//   drawOnMs <= 0 → original CSS-border box with a soft pulse loop.
+({ box, pad, color, lw, label, drawOnMs }) => {
+  const root = document.getElementById('__pw_overlay_root');
+  if (!root) return;
+
+  const x = box.x - pad;
+  const y = box.y - pad;
+  const w = box.width + pad * 2;
+  const h = box.height + pad * 2;
+  const rx = 8;
+
+  const animated = drawOnMs && drawOnMs > 0;
+
+  if (animated) {
+    const NS = 'http://www.w3.org/2000/svg';
+    const svg = document.createElementNS(NS, 'svg');
+    Object.assign(svg.style, {
+      position: 'fixed',
+      left: `${x - lw}px`,
+      top: `${y - lw}px`,
+      width: `${w + lw * 2}px`,
+      height: `${h + lw * 2}px`,
+      overflow: 'visible',
+      pointerEvents: 'none',
+      filter: `drop-shadow(0 0 14px ${color})`,
+    });
+    const rect = document.createElementNS(NS, 'rect');
+    rect.setAttribute('x', String(lw));
+    rect.setAttribute('y', String(lw));
+    rect.setAttribute('width', String(w));
+    rect.setAttribute('height', String(h));
+    rect.setAttribute('rx', String(rx));
+    rect.setAttribute('ry', String(rx));
+    rect.setAttribute('fill', 'none');
+    rect.setAttribute('stroke', color);
+    rect.setAttribute('stroke-width', String(lw));
+    rect.setAttribute('stroke-linecap', 'round');
+
+    const dashLen = 2 * (w + h);
+    rect.style.strokeDasharray = String(dashLen);
+    rect.style.strokeDashoffset = String(dashLen);
+    svg.appendChild(rect);
+    root.appendChild(svg);
+    // Web Animations API: way more reliable than CSS transitions on SVG
+    // presentation attributes (Chrome quietly drops the transition if the
+    // initial state hasn't been painted yet).
+    rect.animate(
+      [{ strokeDashoffset: dashLen }, { strokeDashoffset: 0 }],
+      { duration: drawOnMs, easing: 'cubic-bezier(0.4, 0, 0.2, 1)', fill: 'forwards' }
+    );
+  } else {
+    const rect = document.createElement('div');
+    Object.assign(rect.style, {
+      position: 'fixed',
+      left: `${x}px`,
+      top: `${y}px`,
+      width: `${w}px`,
+      height: `${h}px`,
+      border: `${lw}px solid ${color}`,
+      borderRadius: '8px',
+      boxShadow: `0 0 0 9999px rgba(0,0,0,0.0), 0 0 24px ${color}`,
+      animation: 'pwPulse 1.2s ease-in-out infinite',
+    });
+    const style = document.createElement('style');
+    style.textContent =
+      '@keyframes pwPulse { 0%,100%{transform:scale(1);opacity:1} 50%{transform:scale(1.04);opacity:0.85} }';
+    root.appendChild(style);
+    root.appendChild(rect);
+  }
+
+  if (label) {
+    const lbl = document.createElement('div');
+    lbl.textContent = label;
+    Object.assign(lbl.style, {
+      position: 'fixed',
+      left: `${x}px`,
+      top: `${Math.max(8, y - 40)}px`,
+      padding: '6px 12px',
+      background: color,
+      color: '#fff',
+      fontSize: '16px',
+      fontWeight: '600',
+      borderRadius: '6px',
+      fontFamily:
+        'system-ui, -apple-system, "PingFang SC", "Helvetica Neue", sans-serif',
+      boxShadow: '0 4px 12px rgba(0,0,0,0.25)',
+      whiteSpace: 'nowrap',
+      opacity: '0',
+      transition: 'opacity 300ms ease',
+    });
+    root.appendChild(lbl);
+    setTimeout(() => (lbl.style.opacity = '1'), animated ? Math.floor(drawOnMs * 0.7) : 0);
+  }
+};

package/skills/web-capture/scripts/_media_screenshot/js/overlay_bootstrap.js

@@ -0,0 +1,19 @@
+// Inject the fixed overlay layers used by every storyboard scene.
+// Idempotent: a no-op if already mounted (e.g. across multiple scenes).
+(() => {
+  if (window.__pwOverlayReady) return;
+  const root = document.createElement('div');
+  root.id = '__pw_overlay_root';
+  Object.assign(root.style, {
+    position: 'fixed', inset: '0', pointerEvents: 'none', zIndex: '2147483646',
+  });
+  const fade = document.createElement('div');
+  fade.id = '__pw_overlay_fade';
+  Object.assign(fade.style, {
+    position: 'fixed', inset: '0', background: '#000', opacity: '0',
+    transition: 'opacity 400ms ease', pointerEvents: 'none', zIndex: '2147483647',
+  });
+  document.documentElement.appendChild(root);
+  document.documentElement.appendChild(fade);
+  window.__pwOverlayReady = true;
+})();