claude-dev-env 8.89.0 → 8.90.0

package/.agents/skills/pr-visual/scripts/render.py

@@ -0,0 +1,133 @@
+"""Validate evidence-backed diagram scenes and render a portable HTML visual."""
+import argparse
+import copy
+import json
+import re
+from pathlib import Path
+from urllib.parse import quote
+
+from metrics import prepare_chart, prepare_embedded_charts
+from visual_config.config import constants as c
+
+
+class RenderRunFatal(ValueError):
+    """Stop rendering when scene structure or evidence is invalid."""
+
+
+def _validate_drilldown(node: dict) -> None:
+    flow = node.get("drilldown")
+    if not flow or not flow.get("title") or not c.MINIMUM_DRILLDOWN_STEPS <= len(flow.get("steps", [])) <= c.MAXIMUM_DRILLDOWN_STEPS:
+        raise RenderRunFatal("Every node needs a titled drilldown with two to six steps.")
+    for each_step in flow["steps"]:
+        if not each_step.get("label") or not each_step.get("icon"):
+            raise RenderRunFatal("Every drilldown step needs a label and icon.")
+    for each_edge in flow.get("edges", []):
+        if not 0 <= each_edge["from"] < len(flow["steps"]) or not 0 <= each_edge["to"] < len(flow["steps"]) or each_edge["from"] == each_edge["to"]:
+            raise RenderRunFatal("Invalid drilldown edge.")
+
+
+def _validate_graph(scene: dict) -> None:
+    node_ids = [each_node["id"] for each_node in scene["nodes"]]
+    if len(set(node_ids)) != len(node_ids):
+        raise RenderRunFatal("Duplicate diagram node IDs.")
+    for each_edge in scene["edges"]:
+        if each_edge["from"] not in node_ids or each_edge["to"] not in node_ids:
+            raise RenderRunFatal("Edge refers to a missing node.")
+        if not re.fullmatch(c.SVG_PATH_PATTERN, each_edge["path"]):
+            raise RenderRunFatal("Invalid SVG path.")
+    for each_node in scene["nodes"]:
+        if not scene.get("chart") and (not c.MINIMUM_NODE_X <= each_node["x"] <= c.MAXIMUM_NODE_X or not c.MINIMUM_NODE_Y <= each_node["y"] <= c.MAXIMUM_NODE_Y):
+            raise RenderRunFatal("Node lies outside diagram bounds.")
+        if not each_node.get("sources"):
+            raise RenderRunFatal("Every node needs source evidence.")
+        _validate_drilldown(each_node)
+
+
+def _source_evidence(source: dict, snapshot: dict, snapshot_path: Path) -> None:
+    side = source.get("side", c.HEAD_SIDE)
+    if side not in c.ALL_SOURCE_SIDES:
+        raise RenderRunFatal("Source side must be head or base.")
+    source_root = snapshot_path.parent / side
+    source_path = (source_root / source["path"]).resolve()
+    if not source_path.is_relative_to(source_root):
+        raise RenderRunFatal("Source path leaves snapshot.")
+    all_lines = source_path.read_text(encoding="utf-8-sig").splitlines()
+    first, last = source["line"], source.get("end", source["line"])
+    if not 1 <= first <= last <= len(all_lines):
+        raise RenderRunFatal("Invalid source line range.")
+    source["excerpt"] = c.NEWLINE.join(c.SOURCE_LINE.format(number=each_index + first, line=each_line) for each_index, each_line in enumerate(all_lines[first - 1:last]))
+    revision = snapshot.get("diff_base", snapshot[c.BASE_SIDE]) if side == c.BASE_SIDE else snapshot[c.HEAD_SIDE]
+    source["url"] = c.SOURCE_LINK.format(repo=snapshot["repo"], revision=revision, path=quote(source["path"], safe="/"), first=first, last=last)
+
+
+def _prepare_sources(scene: dict, snapshot: dict, snapshot_path: Path) -> None:
+    for each_node in scene["nodes"]:
+        for each_source in each_node["sources"]:
+            _source_evidence(each_source, snapshot, snapshot_path)
+
+
+def prepare(path: Path) -> dict:
+    """Bind a diagram to captured source and populate immutable evidence links.
+
+    Args:
+        path: Scene JSON path with a relative snapshot reference.
+
+    Returns:
+        The scene with PR identity, original summary, and source excerpts.
+
+    Raises:
+        RenderRunFatal: The scene or an evidence reference is invalid.
+    """
+    scene = json.loads(path.read_text(encoding="utf-8"))
+    snapshot_path = (path.parent / scene["snapshot"]).resolve()
+    snapshot = json.loads(snapshot_path.read_text(encoding="utf-8"))
+    scene["pr"] = {each_key: snapshot[each_key] for each_key in ("number", "url", "repo", "state", "head", "base", "observed_at")}
+    scene["pr"].update(draft=snapshot["metadata"]["draft"], merged=snapshot["metadata"].get("merged", False), changed_files=len(snapshot["files"]), title=snapshot["metadata"]["title"])
+    scene["summary"] = snapshot["metadata"]["body"] or "No PR description."
+    _validate_graph(scene)
+    _prepare_sources(scene, snapshot, snapshot_path)
+    prepare_chart(scene, snapshot_path)
+    prepare_embedded_charts(scene, snapshot_path)
+    return scene
+
+
+def _omit_private_payload(scene: dict) -> None:
+    scene.pop("summary", None)
+    for each_node in scene["nodes"]:
+        for each_source in each_node["sources"]:
+            each_source.pop("excerpt", None)
+
+
+def render(all_scenes: list[dict], artifact_path: Path, is_links_only: bool = False) -> None:
+    """Write a standalone interactive diagram or tabbed gallery.
+
+    Args:
+        all_scenes: Prepared diagrams with captured source evidence.
+        artifact_path: Destination HTML file.
+        is_links_only: Omit original descriptions and code excerpts.
+
+    Raises:
+        RenderRunFatal: The HTML exceeds the host size limit.
+    """
+    all_scenes = copy.deepcopy(all_scenes)
+    if is_links_only:
+        for each_scene in all_scenes:
+            _omit_private_payload(each_scene)
+    payload = json.dumps(all_scenes, ensure_ascii=False).replace("<", "\\u003c").replace(">", "\\u003e").replace("&", "\\u0026")
+    template = c.VIEWER_PATH.read_text(encoding="utf-8")
+    icons = c.ICONS_PATH.read_text(encoding="utf-8")
+    rendered_html = template.replace("__ICONS__", icons).replace("__SCENES__", payload)
+    if len(rendered_html.encode()) > c.MAXIMUM_HTML_BYTES:
+        raise RenderRunFatal("HTML exceeds the host visualization limit.")
+    artifact_path.parent.mkdir(parents=True, exist_ok=True)
+    artifact_path.write_text(rendered_html, encoding="utf-8")
+    print(f"{artifact_path}: {len(all_scenes)} diagrams, {len(rendered_html.encode())} bytes")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("scenes", type=Path, nargs="+")
+    parser.add_argument("--out", type=Path, required=True)
+    parser.add_argument("--links-only", action="store_true", help="Omit original descriptions and code excerpts for hosted display.")
+    arguments = parser.parse_args()
+    render([prepare(each_path) for each_path in arguments.scenes], arguments.out, arguments.links_only)

package/.agents/skills/pr-visual/scripts/test_collect.py

@@ -0,0 +1,58 @@
+"""Check immutable capture and stale-head rejection with synthetic GitHub data."""
+import base64
+import copy
+import hashlib
+import json
+import sys
+from pathlib import Path
+from unittest.mock import Mock
+
+import pytest
+
+SCRIPTS_DIRECTORY = Path(__file__).resolve().parent
+sys.path.insert(0, str(SCRIPTS_DIRECTORY))
+
+import collect
+
+REPOSITORY = "example/project"
+PR_URL = "https://github.com/example/project/pull/1"
+HEAD_SHA = "b" * 40
+BASE_SHA = "c" * 40
+MERGE_BASE_SHA = "a" * 40
+CONTENT = b"print('captured')\n"
+METADATA = {"head": {"sha": HEAD_SHA, "repo": {"full_name": REPOSITORY}}, "base": {"sha": BASE_SHA, "repo": {"full_name": REPOSITORY}}, "changed_files": 1, "state": "open"}
+CHANGED_FILES = [{"filename": "handler.py", "status": "modified", "patch": "fixture patch"}]
+BLOB = {"encoding": "base64", "content": base64.b64encode(CONTENT).decode()}
+
+
+def test_capture_uses_merge_base_and_hashes_saved_bytes(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """Both saved sides match the immutable revisions used by the diff."""
+    github = Mock(side_effect=[METADATA, {"merge_base_commit": {"sha": MERGE_BASE_SHA}}, CHANGED_FILES, BLOB, BLOB, METADATA])
+    monkeypatch.setattr(collect, "_api", github)
+    collect.collect(PR_URL, tmp_path)
+    destination = tmp_path / "pr-1" / HEAD_SHA
+    snapshot = json.loads((destination / "snapshot.json").read_text())
+    assert snapshot["diff_base"] == MERGE_BASE_SHA
+    for each_side in ("base", "head"):
+        assert (destination / each_side / "handler.py").read_bytes() == CONTENT
+        assert snapshot["files"][0]["captures"][each_side]["sha256"] == hashlib.sha256(CONTENT).hexdigest()
+    all_endpoints = [each_call.args[0] for each_call in github.call_args_list]
+    assert any(each_endpoint.endswith(f"?ref={MERGE_BASE_SHA}") for each_endpoint in all_endpoints)
+
+
+def test_moved_head_never_saves_a_complete_snapshot(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """A changed PR head requires another capture before rendering."""
+    moved = copy.deepcopy(METADATA)
+    moved["head"]["sha"] = "d" * 40
+    github = Mock(side_effect=[METADATA, {"merge_base_commit": {"sha": MERGE_BASE_SHA}}, CHANGED_FILES, BLOB, BLOB, moved])
+    monkeypatch.setattr(collect, "_api", github)
+    with pytest.raises(collect.CaptureRunFatal, match="changed during capture"):
+        collect.collect(PR_URL, tmp_path)
+    assert not list(tmp_path.rglob("snapshot.json"))
+
+
+def test_incomplete_changed_file_list_fails(monkeypatch: pytest.MonkeyPatch) -> None:
+    """A truncated file listing cannot imply complete coverage."""
+    monkeypatch.setattr(collect, "_api", Mock(return_value=[]))
+    with pytest.raises(collect.CaptureRunFatal, match="incomplete"):
+        collect._changed_files(REPOSITORY, "1", 1)

package/.agents/skills/pr-visual/scripts/test_metrics.py

@@ -0,0 +1,47 @@
+"""Verify embedded chart provenance and passive Python literal extraction."""
+import copy
+import sys
+from pathlib import Path
+
+import pytest
+
+SCRIPTS_DIRECTORY = Path(__file__).resolve().parent
+sys.path.insert(0, str(SCRIPTS_DIRECTORY))
+
+from metrics import MetricRunFatal, _coordinate, prepare_embedded_charts
+from render import prepare
+
+FIXTURES = SCRIPTS_DIRECTORY.parents[0] / "fixtures"
+ALL_LITERAL_CASES = (("assert metric == 2.0", {}, 2.0), ("Pair(90, 180)", {"argument": 1}, 180), ("peaks = (1, 2, 10)", {"element": 2}, 10))
+
+
+@pytest.mark.parametrize("source_text,selector,expected", ALL_LITERAL_CASES)
+def test_numeric_literals_are_read_without_executing_source(source_text: str, selector: dict, expected: float, tmp_path: Path) -> None:
+    """Executable statements in the source remain inert during chart preparation."""
+    source_root = tmp_path / "head"
+    source_root.mkdir()
+    (source_root / "example.py").write_text('raise RuntimeError("Source must remain inert")\n' + source_text + "\n")
+    node = {"sources": [{"path": "example.py", "line": 2}]}
+    assert _coordinate({"source": 0, "python_line": 2, **selector}, node, tmp_path / "snapshot.json") == expected
+
+
+def test_step_chart_uses_reviewed_values() -> None:
+    """Step cards and expansions use captured fixture measurements."""
+    scene = prepare(FIXTURES / "integrated.scene.json")
+    assert [each_point["values"]["y"] for each_point in scene["nodes"][0]["chart"]["points"]] == [12, 20, 17]
+
+
+def test_ungrounded_embedded_numbers_are_rejected() -> None:
+    """Author-entered chart coordinates cannot replace source references."""
+    scene = copy.deepcopy(prepare(FIXTURES / "integrated.scene.json"))
+    scene["nodes"][0]["chart"]["points"][0].pop("metrics")
+    with pytest.raises(MetricRunFatal):
+        prepare_embedded_charts(scene, FIXTURES / "snapshot.json")
+
+
+def test_python_numbers_outside_cited_lines_are_rejected(tmp_path: Path) -> None:
+    """A measurement must be covered by its displayed evidence link."""
+    (tmp_path / "head").mkdir()
+    (tmp_path / "head/example.py").write_text("assert metric == 2\nassert metric == 10\n")
+    with pytest.raises(MetricRunFatal, match="outside"):
+        _coordinate({"source": 0, "python_line": 2}, {"sources": [{"path": "example.py", "line": 1}]}, tmp_path / "snapshot.json")

package/.agents/skills/pr-visual/scripts/test_render.py

@@ -0,0 +1,77 @@
+"""Exercise numerical provenance, evidence boundaries, and portable rendering."""
+import copy
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+SCRIPTS_DIRECTORY = Path(__file__).resolve().parent
+sys.path.insert(0, str(SCRIPTS_DIRECTORY))
+from metrics import MetricRunFatal, prepare_chart
+from render import RenderRunFatal, _source_evidence, prepare, render
+
+FIXTURES = Path(__file__).resolve().parents[1] / "fixtures"
+FORMATS = ("flow", "bar", "line", "scatter")
+EXPECTED_Y = [12, 20, 17]
+INVALID_VALUES = (True, None, "12", float("nan"), float("inf"))
+
+
+@pytest.mark.parametrize("kind", FORMATS)
+def test_render_source_backed_format(kind: str, tmp_path: Path) -> None:
+    """Every format retains immutable evidence and interactive detail data."""
+    scene = prepare(FIXTURES / f"{kind}.scene.json")
+    artifact_path = tmp_path / "visual.html"
+    render([scene], artifact_path)
+    assert "__SCENES__" not in artifact_path.read_text()
+    assert scene["nodes"][0]["sources"][0]["url"].endswith("/metrics.json#L4-L5")
+    if kind != "flow":
+        assert [each_node["values"]["y"] for each_node in scene["nodes"]] == EXPECTED_Y
+
+
+@pytest.mark.parametrize("value", INVALID_VALUES)
+def test_chart_rejects_nonnumeric_measurements(value: object, tmp_path: Path) -> None:
+    """Missing and nonnumeric observations cannot become plotted values."""
+    scene = json.loads((FIXTURES / "bar.scene.json").read_text())
+    (tmp_path / "head").mkdir()
+    (tmp_path / "head/metrics.json").write_text(json.dumps({"samples": [{"duration_ms": value}]}))
+    with pytest.raises(MetricRunFatal):
+        prepare_chart(scene, tmp_path / "snapshot.json")
+
+
+def test_missing_pointer_fails_instead_of_zero() -> None:
+    """A missing observation cannot imply a zero measurement."""
+    scene = prepare(FIXTURES / "bar.scene.json")
+    scene["nodes"][0]["metrics"]["y"]["pointer"] = "/missing"
+    with pytest.raises(MetricRunFatal):
+        prepare_chart(scene, FIXTURES / "snapshot.json")
+
+
+@pytest.mark.parametrize("source", [{"path": "../../outside", "line": 1}, {"path": "metrics.json", "line": 0}, {"path": "metrics.json", "line": 1, "side": "other"}])
+def test_source_boundary_rejects_invalid_references(source: dict) -> None:
+    """Evidence must remain inside a captured side and a valid line range."""
+    snapshot = json.loads((FIXTURES / "snapshot.json").read_text())
+    with pytest.raises(RenderRunFatal):
+        _source_evidence(source, snapshot, FIXTURES / "snapshot.json")
+
+
+def test_links_only_is_private_and_does_not_mutate_scene(tmp_path: Path) -> None:
+    """Hosted output drops payload excerpts without modifying the prepared scene."""
+    scene = prepare(FIXTURES / "flow.scene.json")
+    original = copy.deepcopy(scene)
+    artifact_path = tmp_path / "visual.html"
+    render([scene], artifact_path, is_links_only=True)
+    payload = artifact_path.read_text().split("data-scenes>", 1)[1].split("</script>", 1)[0]
+    public = json.loads(payload)[0]
+    assert "summary" not in public
+    assert all("excerpt" not in each_source for each_node in public["nodes"] for each_source in each_node["sources"])
+    assert scene == original
+
+
+def test_embedded_text_cannot_close_script(tmp_path: Path) -> None:
+    """Captured prose remains data even when it contains HTML closing tags."""
+    scene = prepare(FIXTURES / "flow.scene.json")
+    scene["summary"] = "</script><script>window.untrusted=1</script>"
+    artifact_path = tmp_path / "visual.html"
+    render([scene], artifact_path)
+    assert scene["summary"] not in artifact_path.read_text()

package/.agents/skills/pr-visual/scripts/verify.py

@@ -0,0 +1,218 @@
+"""Exercise docked panels, mini-diagrams, source disclosures, and isolation."""
+import argparse
+import json
+import re
+import shutil
+from pathlib import Path
+
+from playwright.sync_api import Locator, Page, sync_playwright
+from visual_config.config import constants as c
+
+
+def _panel_layout(root: Locator, is_mobile: bool = False) -> None:
+    stage_box = root.locator(c.STAGE_SELECTOR).bounding_box()
+    panel_box = root.locator(c.DRAWER_SELECTOR).bounding_box()
+    assert stage_box is not None and panel_box is not None
+    if is_mobile:
+        assert panel_box["y"] + panel_box["height"] <= stage_box["y"] + 1
+    else:
+        assert stage_box["x"] + stage_box["width"] <= panel_box["x"] + 1
+
+
+def _check_node(root: Locator, node: dict) -> None:
+    assert root.locator(c.DRAWER_SELECTOR).is_visible()
+    assert root.locator(".drawer .detail-map").is_visible()
+    assert root.locator(".drawer .detail-map use").count() == len(node["drilldown"]["steps"])
+    assert not root.locator(c.EXACT_SELECTOR).evaluate(c.DISCLOSURE_OPEN_EXPRESSION)
+    _panel_layout(root)
+    assert root.locator(".drawer [data-embedded-chart]").count() == int(bool(node.get("chart")))
+    root.locator(c.DISCLOSURE_SELECTOR).click()
+    assert root.locator(".exact-source a").count() == len(node["sources"])
+    assert root.locator(".exact-source p").count() == len(node["detail"])
+    assert (root.locator(".exact-source pre").count() > 0) == bool(node["sources"][0].get("excerpt"))
+
+
+def _navigate_related(root: Locator) -> None:
+    jumps = root.locator(c.JUMP_SELECTOR)
+    if jumps.count():
+        target = jumps.first.get_attribute("data-detail-target")
+        jumps.first.click()
+        assert root.locator(c.NODE_TARGET_SELECTOR.format(target=target)).get_attribute("aria-expanded") == "true"
+        assert not root.locator(c.EXACT_SELECTOR).evaluate(c.DISCLOSURE_OPEN_EXPRESSION)
+
+
+def _toolbar_details(root: Locator, node_count: int) -> None:
+    for each_label in c.ALL_TOOLBAR_DETAIL_LABELS:
+        root.get_by_role("button", name=each_label, exact=True).click()
+        assert root.locator(".drawer .detail-map").is_visible()
+        assert root.locator(c.JUMP_SELECTOR).count() == node_count
+        root.locator(c.DISCLOSURE_SELECTOR).click()
+        assert root.locator(".exact-source p").count() > 0
+        root.get_by_role("button", name=c.CLOSE_BUTTON_LABEL).click()
+
+
+def _keyboard_and_zoom(page: Page, root: Locator) -> None:
+    first_node = root.locator(c.NODE_SELECTOR).first
+    first_node.focus()
+    page.keyboard.press("Enter")
+    page.keyboard.press("Escape")
+    assert first_node.evaluate("(n)=>n===document.activeElement")
+    root.get_by_role("button", name=c.ZOOM_BUTTON_LABEL, exact=True).click()
+    assert root.locator(c.CANVAS_SELECTOR).evaluate(c.CANVAS_WIDTH_EXPRESSION)
+    root.get_by_role("button", name="Fit", exact=True).click()
+    assert root.locator(c.CANVAS_SELECTOR).evaluate(c.CANVAS_WIDTH_EXPRESSION) == ""
+    assert not root.locator(".canvas svg text").evaluate_all(c.OVERFLOW_EXPRESSION)
+
+
+def _scene_screenshots(page: Page, root: Locator, scene: dict, proof_directory: Path, scene_index: int) -> None:
+    page.screenshot(path=str(proof_directory / c.PR_SCREENSHOT_NAME.format(number=scene["pr"]["number"], index=scene_index)), full_page=True)
+    all_nodes = root.locator(c.NODE_SELECTOR)
+    all_nodes.first.click()
+    page.screenshot(path=str(proof_directory / c.DETAIL_SCREENSHOT_NAME.format(number=scene["pr"]["number"], index=scene_index)), full_page=True)
+    if all_nodes.count() > 1:
+        all_nodes.nth(1).click()
+        assert root.locator(c.DETAIL_TITLE_SELECTOR).inner_text() == c.SPACE_SEPARATOR.join(scene["nodes"][1]["label"])
+    page.keyboard.press("Escape")
+
+
+def _verify_scene(page: Page, root: Locator, scene: dict, scene_index: int, proof_directory: Path) -> dict:
+    root.get_by_role("tab").nth(scene_index).click()
+    all_nodes = root.locator(c.NODE_SELECTOR)
+    for each_index, each_node in enumerate(scene["nodes"]):
+        all_nodes.nth(each_index).click()
+        _check_node(root, each_node)
+        _navigate_related(root)
+        page.keyboard.press("Escape")
+        assert root.locator(c.DRAWER_SELECTOR).is_hidden()
+        assert root.locator(c.SELECTED_NODE_SELECTOR).count() == 0
+    _toolbar_details(root, len(scene["nodes"]))
+    _keyboard_and_zoom(page, root)
+    _scene_screenshots(page, root, scene, proof_directory, scene_index)
+    return {"pr": scene["pr"]["number"], "nodes_checked": all_nodes.count(), "docked_panel": "pass", "mini_diagrams": "pass", "related_navigation": "pass", "collapsed_sources": "pass", "keyboard_and_zoom": "pass"}
+
+
+def _dashboard(page: Page, root: Locator, all_scenes: list[dict], proof_directory: Path) -> None:
+    tabs = root.get_by_role("tab")
+    assert tabs.count() == len(all_scenes)
+    assert root.locator(".tabs svg").count() == 0
+    assert root.locator(c.DASHBOARD_SELECTOR).bounding_box()["height"] <= c.MAXIMUM_DASHBOARD_HEIGHT
+    for each_index, each_scene in enumerate(all_scenes):
+        tabs.nth(each_index).click()
+        assert tabs.nth(each_index).get_attribute("aria-selected") == "true"
+        assert root.locator(c.DRAWER_SELECTOR).is_hidden()
+        assert root.locator("[data-step-chart]").count() == (0 if each_scene.get("chart") else sum(bool(each_node.get("chart")) for each_node in each_scene["nodes"]))
+    tabs.first.click()
+    root.screenshot(path=str(proof_directory / c.DASHBOARD_SCREENSHOT_NAME))
+
+
+def _verify_mobile(page: Page, root: Locator, proof_directory: Path) -> None:
+    all_tabs = root.get_by_role("tab")
+    all_tabs.first.focus()
+    if all_tabs.count() > 1:
+        page.keyboard.press("ArrowRight")
+        assert all_tabs.nth(1).get_attribute("aria-selected") == "true"
+    page.set_viewport_size(c.ALL_MOBILE_VIEWPORT)
+    root.locator(c.NODE_SELECTOR).first.click()
+    _panel_layout(root, is_mobile=True)
+    assert root.locator(c.STAGE_SELECTOR).evaluate(c.SCROLLABLE_EXPRESSION)
+    root.locator(c.STAGE_SELECTOR).evaluate(c.SCROLL_MAP_EXPRESSION)
+    assert root.locator(c.STAGE_SELECTOR).evaluate(c.READ_SCROLL_EXPRESSION) > 0
+    page.screenshot(path=str(proof_directory / c.MOBILE_SCREENSHOT_NAME), full_page=True)
+    page.keyboard.press("Escape")
+
+
+def _mount_two_widgets(page: Page, source: str) -> str:
+    page.set_viewport_size(c.ALL_DESKTOP_VIEWPORT)
+    page.set_content(c.HOST_FIXTURE_HTML)
+    background = page.locator(c.HOST_FIXTURE_SELECTOR).evaluate(c.BACKGROUND_EXPRESSION)
+    fragment = re.search(c.MAIN_FRAGMENT_PATTERN, source, re.DOTALL).group()
+    style = re.search(c.STYLE_FRAGMENT_PATTERN, source, re.DOTALL).group()
+    for each_instance in range(2):
+        page.evaluate(c.MOUNT_WIDGET_EXPRESSION, style + fragment)
+    return background
+
+
+def _verify_isolation(page: Page, source: str) -> None:
+    background = _mount_two_widgets(page, source)
+    all_roots = page.locator(c.ROOT_SELECTOR)
+    all_roots.nth(0).locator(c.NODE_SELECTOR).first.click()
+    assert all_roots.nth(0).locator(c.DRAWER_SELECTOR).is_visible()
+    assert all_roots.nth(1).locator(c.DRAWER_SELECTOR).is_hidden()
+    all_roots.nth(1).get_by_role("button", name=c.ZOOM_BUTTON_LABEL, exact=True).click()
+    assert all_roots.nth(0).locator(c.CANVAS_SELECTOR).evaluate(c.CANVAS_WIDTH_EXPRESSION) == ""
+    assert all_roots.nth(0).get_by_role("tab").first.get_attribute("aria-selected") == "true"
+    assert page.locator(c.HOST_FIXTURE_SELECTOR).evaluate(c.BACKGROUND_EXPRESSION) == background
+    all_ids = page.locator("[id]").evaluate_all(c.READ_IDS_EXPRESSION)
+    assert len(all_ids) == len(set(all_ids)), "Widget instances share SVG or control IDs"
+    _verify_host_contrast(page, all_roots.nth(0))
+
+
+def _luminance(color: str) -> float:
+    channels = [int(each_component) / c.RGB_CHANNEL_MAXIMUM for each_component in re.findall(c.RGB_COMPONENT_PATTERN, color)]
+    linear = [each_channel / c.SRGB_LINEAR_DIVISOR if each_channel <= c.SRGB_LINEAR_THRESHOLD else ((each_channel + c.SRGB_OFFSET) / c.SRGB_SCALE) ** c.SRGB_EXPONENT for each_channel in channels]
+    return sum(each_channel * each_weight for each_channel, each_weight in zip(linear, c.ALL_LUMINANCE_WEIGHTS, strict=True))
+
+
+def _verify_host_contrast(page: Page, root: Locator) -> None:
+    page.add_style_tag(content=c.HOST_THEME_STYLES)
+    assert page.locator("body").evaluate(c.CONTROL_STYLES_EXPRESSION)["scheme"] == "dark"
+    assert page.locator(c.HOST_FIXTURE_SELECTOR).evaluate(c.CONTROL_STYLES_EXPRESSION)["color"] == c.WHITE_COLOR
+    assert root.evaluate(c.CONTROL_STYLES_EXPRESSION)["scheme"] == "light"
+    all_controls = root.locator("button")
+    for each_index in range(all_controls.count()):
+        control = all_controls.nth(each_index)
+        styles = control.evaluate(c.CONTROL_STYLES_EXPRESSION)
+        assert styles["opacity"] == "1" and styles["shadow"] == "none"
+        foreground, background = sorted((_luminance(styles["color"]), _luminance(styles["background"])))
+        assert (background + c.CONTRAST_OFFSET) / (foreground + c.CONTRAST_OFFSET) >= c.MINIMUM_TEXT_CONTRAST
+        children = control.locator("span")
+        for each_child in range(children.count()):
+            assert children.nth(each_child).evaluate(c.CONTROL_STYLES_EXPRESSION)["color"] == styles["color"]
+    close = root.get_by_role("button", name=c.CLOSE_BUTTON_LABEL)
+    assert close.evaluate(c.CONTROL_STYLES_EXPRESSION)["color"] == c.TEAL_COLOR
+    assert close.evaluate(c.CONTROL_STYLES_EXPRESSION)["border"] == c.CONTROL_BORDER_COLOR
+    page.keyboard.press("Tab")
+    close.focus()
+    assert close.evaluate(c.CONTROL_STYLES_EXPRESSION)["outline"] == c.TEAL_COLOR
+    root.get_by_role("button", name="Fit", exact=True).focus()
+    assert root.get_by_role("button", name="Fit", exact=True).evaluate(c.CONTROL_STYLES_EXPRESSION)["outline"] == c.LIME_COLOR
+
+
+def verify(path: Path, proof_directory: Path, browser_path: str | None = None, should_disable_sandbox: bool = False) -> None:
+    """Exercise the rendered artifact in desktop, mobile, and shared-host layouts.
+
+    Args:
+        path: Rendered HTML artifact.
+        proof_directory: Directory receiving screenshots and the verification report.
+        browser_path: Optional Chromium executable; otherwise detect or use Playwright.
+        should_disable_sandbox: Disable Chromium sandbox only in an isolated container.
+    """
+    proof_directory.mkdir(parents=True, exist_ok=True)
+    with sync_playwright() as driver:
+        browser_path = browser_path or shutil.which("chromium") or shutil.which("google-chrome")
+        browser = driver.chromium.launch(executable_path=browser_path, headless=True, args=["--no-sandbox"] if should_disable_sandbox else [])
+        page = browser.new_page(viewport=c.ALL_DESKTOP_VIEWPORT, device_scale_factor=1)
+        all_errors = []
+        page.on("pageerror", lambda each_error: all_errors.append(str(each_error)))
+        page.set_content(path.read_text(encoding="utf-8"))
+        root = page.locator(c.ROOT_SELECTOR)
+        all_scenes = root.locator(c.DATA_SCENES_SELECTOR).evaluate(c.READ_SCENES_EXPRESSION)
+        _dashboard(page, root, all_scenes, proof_directory)
+        all_verdicts = [_verify_scene(page, root, each_scene, each_index, proof_directory) for each_index, each_scene in enumerate(all_scenes)]
+        _verify_mobile(page, root, proof_directory)
+        _verify_isolation(page, path.read_text(encoding="utf-8"))
+        assert not all_errors, all_errors
+        browser.close()
+    report = {"input": str(path), "diagrams": all_verdicts, "browser_errors": all_errors, "mobile_stacked_panel": "pass", "multiple_widget_isolation": "pass", "dark_host_contrast": "pass"}
+    (proof_directory / c.REPORT_NAME).write_text(json.dumps(report, indent=c.JSON_INDENT), encoding="utf-8")
+    print(json.dumps(report, indent=c.JSON_INDENT))
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("html", type=Path)
+    parser.add_argument("--out", type=Path, default=Path(c.DEFAULT_PROOF_DIRECTORY))
+    parser.add_argument("--browser-path", help="Chromium executable; defaults to a detected browser or Playwright Chromium.")
+    parser.add_argument("--no-sandbox", action="store_true", help="Use only when the browser runs in an isolated container.")
+    arguments = parser.parse_args()
+    verify(arguments.html, arguments.out, arguments.browser_path, arguments.no_sandbox)

package/.agents/skills/pr-visual/scripts/visual_config/config/constants.py

@@ -0,0 +1,104 @@
+"""Capture limits, artifact names, and diagram boundaries."""
+from pathlib import Path
+
+SKILL_ROOT = Path(__file__).resolve().parents[3]
+PAGE_SIZE = 100
+SOURCE_WORKERS = 4
+JSON_INDENT = 2
+NEWLINE = "\n"
+PARAGRAPH_BREAK = "\n\n"
+ALL_SOURCE_SIDES = ("base", "head")
+HEAD_SIDE = "head"
+BASE_SIDE = "base"
+PR_URL_PATTERN = r"https://github\.com/([\w.-]+/[\w.-]+)/pull/([1-9]\d*)/?"
+PR_ENDPOINT = "repos/{repo}/pulls/{number}"
+COMPARE_ENDPOINT = "repos/{repo}/compare/{base}...{head}"
+FILES_ENDPOINT = "repos/{repo}/pulls/{number}/files?per_page={size}&page={page}"
+CONTENTS_ENDPOINT = "repos/{repo}/contents/{path}?ref={revision}"
+SOURCE_LINK = "https://github.com/{repo}/blob/{revision}/{path}#L{first}-L{last}"
+DIFF_SECTION = "--- {filename}\n{patch}"
+SOURCE_LINE = "{number:4}  {line}"
+SNAPSHOT_NAME = "snapshot.json"
+DIFF_NAME = "changes.diff"
+DEFAULT_EVIDENCE_DIRECTORY = "evidence"
+SVG_PATH_PATTERN = r"[MmLlHhVvQqCcSsTtAaZz0-9.,\s-]+"
+MINIMUM_NODE_X = 60
+MAXIMUM_NODE_X = 1380
+MINIMUM_NODE_Y = 200
+MAXIMUM_NODE_Y = 760
+MINIMUM_DRILLDOWN_STEPS = 2
+MAXIMUM_DRILLDOWN_STEPS = 6
+MAXIMUM_HTML_BYTES = 256 * 1024
+VIEWER_PATH = SKILL_ROOT / "assets" / "viewer.html"
+ICONS_PATH = SKILL_ROOT / "assets" / "icons.symbols"
+ALL_DESKTOP_VIEWPORT = {"width": 1440, "height": 1200}
+ALL_MOBILE_VIEWPORT = {"width": 390, "height": 844}
+ROOT_SELECTOR = "[data-pr-visual]"
+DRAWER_SELECTOR = ".drawer"
+STAGE_SELECTOR = ".stage"
+CANVAS_SELECTOR = ".canvas"
+EXACT_SELECTOR = ".exact-source"
+DISCLOSURE_SELECTOR = ".exact-source summary"
+DETAIL_TITLE_SELECTOR = "[data-detail-title]"
+NODE_SELECTOR = "[data-node]"
+JUMP_SELECTOR = "[data-detail-target]"
+DATA_SCENES_SELECTOR = "[data-scenes]"
+CANVAS_WIDTH_EXPRESSION = "(n)=>n.style.width"
+DISCLOSURE_OPEN_EXPRESSION = "(n)=>n.open"
+SOURCE_HAS_EXCERPTS_EXPRESSION = "s=>s.nodes.some(n=>n.sources.some(r=>r.excerpt))"
+BACKGROUND_EXPRESSION = "(n)=>getComputedStyle(n).backgroundColor"
+SCROLLABLE_EXPRESSION = "(n)=>n.scrollWidth>n.clientWidth"
+SCROLL_MAP_EXPRESSION = "(n)=>n.scrollLeft=600"
+READ_SCROLL_EXPRESSION = "(n)=>n.scrollLeft"
+READ_SCENES_EXPRESSION = "(n)=>JSON.parse(n.textContent)"
+READ_IDS_EXPRESSION = "(nodes)=>nodes.map(n=>n.id)"
+NODE_TARGET_SELECTOR = '[data-node="{target}"]'
+SELECTED_NODE_SELECTOR = '[data-node][aria-expanded=true]'
+PR_SCREENSHOT_NAME = "scene-{index}-pr-{number}.png"
+DETAIL_SCREENSHOT_NAME = "scene-{index}-pr-{number}-detail.png"
+MOBILE_SCREENSHOT_NAME = "mobile-detail.png"
+REPORT_NAME = "verification.json"
+DEFAULT_PROOF_DIRECTORY = "proof"
+SPACE_SEPARATOR = " "
+ZOOM_BUTTON_LABEL = "Zoom in"
+CLOSE_BUTTON_LABEL = "Close details"
+ALL_TOOLBAR_DETAIL_LABELS = ("Summary vs code", "Review notes")
+OVERFLOW_EXPRESSION = "(nodes)=>nodes.filter(n=>{const b=n.getBBox(); return b.x<0||b.x+b.width>1440||b.y<0||b.y+b.height>1020}).map(n=>n.textContent)"
+MAIN_FRAGMENT_PATTERN = r"<main data-pr-visual>.*?</main>"
+STYLE_FRAGMENT_PATTERN = r"<style>.*?</style>"
+HOST_FIXTURE_HTML = '<div class="toolbar" id="host-toolbar">Host toolbar</div>'
+HOST_FIXTURE_SELECTOR = "#host-toolbar"
+HOST_THEME_STYLES = 'body{color-scheme:dark;color:white;background:#121212}button{color:white;opacity:.45;text-shadow:0 0 2px white}span{color:#cccccc}'
+CONTROL_STYLES_EXPRESSION = '(n)=>{const s=getComputedStyle(n);return {color:s.color,background:s.backgroundColor,opacity:s.opacity,shadow:s.textShadow,scheme:s.colorScheme,border:s.borderTopColor,outline:s.outlineColor}}'
+TEAL_COLOR = "rgb(23, 53, 63)"
+WHITE_COLOR = "rgb(255, 255, 255)"
+LIME_COLOR = "rgb(216, 246, 135)"
+CONTROL_BORDER_COLOR = "rgb(135, 155, 142)"
+MINIMUM_TEXT_CONTRAST = 4.5
+RGB_COMPONENT_PATTERN = r"\d+"
+RGB_CHANNEL_MAXIMUM = 255
+SRGB_LINEAR_THRESHOLD = 0.04045
+SRGB_LINEAR_DIVISOR = 12.92
+SRGB_OFFSET = 0.055
+SRGB_SCALE = 1.055
+SRGB_EXPONENT = 2.4
+ALL_LUMINANCE_WEIGHTS = (0.2126, 0.7152, 0.0722)
+CONTRAST_OFFSET = 0.05
+MOUNT_WIDGET_EXPRESSION = 'html=>{const t=document.createElement("template");t.innerHTML=html;const scripts=[...t.content.querySelectorAll("script:not([type])")];scripts.forEach(n=>n.remove());document.body.append(t.content);scripts.forEach(old=>{const script=document.createElement("script");script.textContent=old.textContent;document.querySelectorAll("[data-pr-visual]").item(document.querySelectorAll("[data-pr-visual]").length-1).append(script)})}'
+
+ALL_CHART_KINDS = ("bar", "line", "scatter")
+ALL_CHART_AXES = ("x", "y")
+CHART_Y_AXIS = "y"
+METRIC_SOURCE_INDEX = "source"
+
+PYTHON_LINE_FIELD = "python_line"
+PYTHON_ARGUMENT_FIELD = "argument"
+PYTHON_ELEMENT_FIELD = "element"
+CHART_X_AXIS = "x"
+ALL_CHART_BASES = ("captured", "source-example")
+ALL_EMBEDDED_CHART_FIELDS = ("title", "caption", "x_label", "y_label", "points")
+
+DASHBOARD_SCREENSHOT_NAME = "dashboard.png"
+MAXIMUM_DASHBOARD_HEIGHT = 120
+
+DASHBOARD_SELECTOR = ".tabs"