web-picker 0.2.0__py3-none-any.whl

web_picker/__init__.py

@@ -0,0 +1,7 @@
+"""Web Picker — render multiple HTML previews, let the human pick one."""
+
+__version__ = "0.2.0"
+
+from web_picker.app import main
+
+__all__ = ["main"]

web_picker/__main__.py

@@ -0,0 +1,4 @@
+"""支持 python -m web_picker <html1> <html2> ..."""
+from web_picker.app import main
+
+main()

web_picker/app.py

@@ -0,0 +1,557 @@
+"""Web Picker — render multiple HTML previews, let the human pick one."""
+
+import argparse
+import os
+import sys
+import webbrowser
+from pathlib import Path
+
+# PySide6 运行时保护 —— 一些精简安装只带 Essentials,没有 QtWebEngineWidgets
+try:
+    from PySide6 import QtWebEngineWidgets  # noqa: F401
+except ImportError:
+    print(
+        "[web-picker] QtWebEngineWidgets is not available in this install.\n"
+        "  On minimal installs, run:  pip install PySide6-Addons\n",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+from PySide6.QtCore import Qt, QUrl
+from PySide6.QtGui import QGuiApplication
+from PySide6.QtWidgets import (
+    QApplication, QMainWindow, QWidget, QFrame,
+    QVBoxLayout, QHBoxLayout, QLabel, QPushButton, QSplitter, QSlider,
+)
+from PySide6.QtWebEngineCore import QWebEngineSettings
+from PySide6.QtWebEngineWidgets import QWebEngineView
+
+
+# 主题字典 —— 与 svg-picker 完全一致
+THEMES = {
+    "cream": {
+        "BG_BASE":       "#f5f0e1",
+        "BG_CARD":       "#fbf6e4",
+        "BG_HOVER":      "#ede2bf",
+        "BORDER":        "#d8c79f",
+        "BORDER_HOVER":  "#b9a578",
+        "TEXT_PRIMARY":  "#2c2418",
+        "TEXT_MUTED":    "#8a7a5e",
+        "ACCENT":        "#6366f1",
+        "ACCENT_HOVER":  "#818cf8",
+        "ACCENT_SEL_BG": "rgba(99,102,241,0.15)",
+    },
+    "sky": {
+        "BG_BASE":       "#e0f2fe",
+        "BG_CARD":       "#f0f9ff",
+        "BG_HOVER":      "#bae6fd",
+        "BORDER":        "#7dd3fc",
+        "BORDER_HOVER":  "#38bdf8",
+        "TEXT_PRIMARY":  "#0c4a6e",
+        "TEXT_MUTED":    "#64748b",
+        "ACCENT":        "#0284c7",
+        "ACCENT_HOVER":  "#0ea5e9",
+        "ACCENT_SEL_BG": "rgba(2,132,199,0.15)",
+    },
+    "dark": {
+        "BG_BASE":       "#0f1117",
+        "BG_CARD":       "#0f1117",
+        "BG_HOVER":      "#1e2130",
+        "BORDER":        "#2e3347",
+        "BORDER_HOVER":  "#3d4260",
+        "TEXT_PRIMARY":  "#e2e4ea",
+        "TEXT_MUTED":    "#7a7f99",
+        "ACCENT":        "#6366f1",
+        "ACCENT_HOVER":  "#818cf8",
+        "ACCENT_SEL_BG": "rgba(99,102,241,0.2)",
+    },
+}
+
+BG_BASE       = THEMES["cream"]["BG_BASE"]
+BG_CARD       = THEMES["cream"]["BG_CARD"]
+BG_HOVER      = THEMES["cream"]["BG_HOVER"]
+BORDER        = THEMES["cream"]["BORDER"]
+BORDER_HOVER  = THEMES["cream"]["BORDER_HOVER"]
+TEXT_PRIMARY  = THEMES["cream"]["TEXT_PRIMARY"]
+TEXT_MUTED    = THEMES["cream"]["TEXT_MUTED"]
+ACCENT        = THEMES["cream"]["ACCENT"]
+ACCENT_HOVER  = THEMES["cream"]["ACCENT_HOVER"]
+ACCENT_SEL_BG = THEMES["cream"]["ACCENT_SEL_BG"]
+
+
+def apply_theme(name):
+    """根据主题名更新模块级颜色常量。"""
+    if name not in THEMES:
+        raise ValueError(f"Unknown theme '{name}'. Choose from {list(THEMES)}")
+    for key, value in THEMES[name].items():
+        globals()[key] = value
+
+
+MAX_OPTIONS = 9
+
+
+def pick_layout(n):
+    """根据选项数选择网格布局。N 必须在 1-9 之间。"""
+    if n == 1: return (1, 1)
+    if n == 2: return (1, 2)
+    if n == 3: return (1, 3)
+    if n == 4: return (2, 2)
+    if n in (5, 6): return (2, 3)
+    return (3, 3)  # 7-9
+
+
+class WebPageCard(QFrame):
+    """一张可点击的卡片,内含一个 QWebEngineView + 文件名标签。
+
+    设计要点:
+    - QWebEngineView 设了 WA_TransparentForMouseEvents —— 它只负责"看",不接收鼠标。
+      所有鼠标事件(包括在内嵌 iframe 上方的)都传给本卡片,QFrame.mousePressEvent 统一处理。
+    - 三种状态:idle(默认)、hover(QSS)、selected(强调色边框 + 淡色背景)。
+    - 点击 → 通知主窗口"我被选中了",由主窗口统一协调(只能选中一张)。
+    """
+
+    def __init__(self, html_path, on_click, slider_handle=0, parent=None):
+        super().__init__(parent)
+        self.html_path = html_path
+        self._on_click = on_click
+        self._selected = False
+        self.setFrameShape(QFrame.Shape.StyledPanel)
+        self.setCursor(Qt.CursorShape.PointingHandCursor)
+        self.setFocusPolicy(Qt.FocusPolicy.NoFocus)  # 主窗口统一管键盘
+        self.setMinimumSize(220, 180)  # 拖手柄不能拖到太小
+
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(6, 6, 6, 6)
+        layout.setSpacing(4)
+
+        # 标题栏 —— 单行:左 slider + 百分比,右 filename
+        title_bar = QHBoxLayout()
+        title_bar.setContentsMargins(2, 0, 2, 0)
+        title_bar.setSpacing(6)
+
+        self.zoom_slider = QSlider(Qt.Orientation.Horizontal)
+        self.zoom_slider.setRange(25, 200)  # 25% – 200%
+        self.zoom_slider.setValue(100)      # 默认 100%
+        self.zoom_slider.setPageStep(25)
+        self.zoom_slider.setSingleStep(5)
+        self.zoom_slider.setFixedWidth(110)
+        self.zoom_slider.setToolTip("缩放:拖动调整预览大小")
+        self.zoom_slider.valueChanged.connect(self._on_zoom_changed)
+        # 用户传了 --slider-handle → 显式加宽拖把,触控板/触屏好抓
+        # 颜色用 TEXT_PRIMARY(各主题自带的"前景色",跟背景协调),
+        # 不用 ACCENT,避免米黄主体里冒出蓝色拖把
+        if slider_handle > 0:
+            self.zoom_slider.setStyleSheet(f"""
+                QSlider::groove:horizontal {{
+                    height: 4px;
+                    background: {BORDER};
+                    border-radius: 2px;
+                }}
+                QSlider::handle:horizontal {{
+                    background: {TEXT_PRIMARY};
+                    border: none;
+                    width: {slider_handle}px;
+                    height: {slider_handle + 4}px;
+                    margin: -{(slider_handle + 4 - 4) // 2}px 0;
+                    border-radius: 3px;
+                }}
+                QSlider::handle:horizontal:hover {{
+                    background: {TEXT_PRIMARY};
+                    border: 2px solid {ACCENT};
+                }}
+            """)
+        title_bar.addWidget(self.zoom_slider)
+
+        self.zoom_label = QLabel("100%")
+        self.zoom_label.setFixedWidth(40)
+        self.zoom_label.setAlignment(Qt.AlignmentFlag.AlignCenter)
+        self.zoom_label.setStyleSheet(
+            f"color: {TEXT_MUTED}; font-size: 11px; font-weight: 500; "
+            f"background: transparent;"
+        )
+        title_bar.addWidget(self.zoom_label)
+
+        title_bar.addStretch()
+
+        title = QLabel(html_path.name)
+        title.setStyleSheet(
+            f"color: {TEXT_MUTED}; font-size: 12px; font-weight: 600; "
+            f"padding: 2px 4px; background: transparent;"
+        )
+        title.setAttribute(Qt.WidgetAttribute.WA_TransparentForMouseEvents, True)
+        title_bar.addWidget(title)
+
+        layout.addLayout(title_bar)
+
+        # Webview —— 只渲染,不接收事件
+        self.webview = QWebEngineView()
+        self.webview.setAttribute(
+            Qt.WidgetAttribute.WA_TransparentForMouseEvents, True
+        )
+        self.webview.setFocusPolicy(Qt.FocusPolicy.NoFocus)
+        # 隐藏 Chromium 渲染的滚动条
+        self.webview.page().settings().setAttribute(
+            QWebEngineSettings.WebAttribute.ShowScrollBars, False
+        )
+        self.webview.setUrl(QUrl.fromLocalFile(str(html_path)))
+        layout.addWidget(self.webview, 1)  # stretch=1,占满剩余空间
+
+        self._apply_style()
+
+    def _apply_style(self):
+        if self._selected:
+            self.setStyleSheet(f"""
+                QFrame {{
+                    background: {ACCENT_SEL_BG};
+                    border: 2px solid {ACCENT};
+                    border-radius: 8px;
+                }}
+            """)
+        else:
+            self.setStyleSheet(f"""
+                QFrame {{
+                    background: {BG_CARD};
+                    border: 2px solid {BORDER};
+                    border-radius: 8px;
+                }}
+                QFrame:hover {{
+                    background: {BG_HOVER};
+                    border: 2px solid {BORDER_HOVER};
+                }}
+            """)
+
+    def set_selected(self, selected: bool):
+        """切换选中态并刷新样式。"""
+        if self._selected == selected:
+            return
+        self._selected = selected
+        self._apply_style()
+
+    def _on_zoom_changed(self, value: int):
+        """Slider 拖动 → 调整 webview 缩放 + 同步百分比标签。
+        放大超过 100% 时临时开启滚动条,好让用户能看到超出视口的部分。"""
+        self.webview.setZoomFactor(value / 100.0)
+        self.zoom_label.setText(f"{value}%")
+        show_scroll = value > 100
+        self.webview.page().settings().setAttribute(
+            QWebEngineSettings.WebAttribute.ShowScrollBars, show_scroll
+        )
+
+    def mousePressEvent(self, event):
+        if event.button() == Qt.MouseButton.LeftButton:
+            self._on_click(self.html_path)
+        super().mousePressEvent(event)
+
+    def mouseDoubleClickEvent(self, event):
+        """双击:用系统默认浏览器打开该 HTML(便于看真实尺寸/动画)。"""
+        if event.button() == Qt.MouseButton.LeftButton:
+            webbrowser.open(self.html_path.as_uri())
+        super().mouseDoubleClickEvent(event)
+
+
+class MainWindow(QMainWindow):
+    def __init__(self, html_paths, width=None, height=None, slider_handle=0):
+        super().__init__()
+        self.html_paths = html_paths
+        self._picked = None
+        self._selected_index = None  # 0-based,当前高亮选中的卡片
+        self._cards = []
+        self._slider_handle = slider_handle  # zoom slider 拖把宽度;0 = 用 Qt 默认
+
+        n = len(html_paths)
+        rows, cols = pick_layout(n)
+        self.setWindowTitle(f"web-picker — {n} option{'s' if n != 1 else ''}")
+        self.setMinimumSize(800, 600)
+
+        # 窗口尺寸:用户显式传入 → 用用户的;否则按屏幕 85% 自适应
+        screen = QGuiApplication.primaryScreen()
+        if screen:
+            rect = screen.availableGeometry()
+            auto_w = min(int(rect.width() * 0.85), max(1200, cols * 600))
+            auto_h = min(int(rect.height() * 0.85), max(800, rows * 450))
+            target_w = width if width is not None else auto_w
+            target_h = height if height is not None else auto_h
+            self.resize(target_w, target_h)
+            self.move(rect.center() - self.rect().center())
+        else:
+            self.resize(
+                width if width is not None else 1200,
+                height if height is not None else 800,
+            )
+
+        self._setup_ui(rows, cols)
+
+    def _setup_ui(self, rows, cols):
+        cw = QWidget()
+        self.setCentralWidget(cw)
+
+        outer = QVBoxLayout(cw)
+        outer.setContentsMargins(0, 0, 0, 0)
+        outer.setSpacing(0)
+
+        # 顶部 header —— 左侧说明 + 右侧 Confirm 按钮
+        header = QFrame()
+        header.setStyleSheet(
+            f"QFrame {{ background: {BG_BASE}; border-bottom: 1px solid {BORDER}; }}"
+        )
+        header.setFixedHeight(58)
+        hlayout = QHBoxLayout(header)
+        hlayout.setContentsMargins(16, 0, 16, 0)
+        hlayout.setSpacing(12)
+
+        hint = QLabel(
+            f"Click to select (or press 1-{len(self.html_paths)}). "
+            f"Drag handles to resize. "
+            f"Double-click to open in your default browser. "
+            f"Confirm (or Enter) commits; Esc cancels."
+        )
+        hint.setStyleSheet(
+            f"color: {TEXT_PRIMARY}; font-size: 14px; background: transparent;"
+        )
+        hlayout.addWidget(hint)
+        hlayout.addStretch()
+
+        self.confirm_btn = QPushButton("Confirm")
+        self.confirm_btn.setFixedWidth(120)
+        self.confirm_btn.setEnabled(False)
+        self.confirm_btn.setCursor(Qt.CursorShape.PointingHandCursor)
+        self.confirm_btn.clicked.connect(self._on_confirm)
+        self._apply_confirm_style()
+        hlayout.addWidget(self.confirm_btn)
+        outer.addWidget(header)
+
+        # 卡片区 —— 用嵌套 QSplitter,卡片之间有可拖动手柄
+        # 单行(rows=1): 一个水平 splitter
+        # 多行: 一个垂直 splitter,每行内部是水平 splitter
+        container = QWidget()
+        container.setStyleSheet(f"background: {BG_BASE};")
+        clayout = QVBoxLayout(container)
+        clayout.setContentsMargins(12, 12, 12, 12)
+        clayout.setSpacing(0)
+        outer.addWidget(container, 1)
+
+        if rows == 1:
+            root_splitter = QSplitter(Qt.Orientation.Horizontal)
+        else:
+            root_splitter = QSplitter(Qt.Orientation.Vertical)
+
+        self._style_splitter(root_splitter)
+
+        for r in range(rows):
+            if rows == 1:
+                row_splitter = root_splitter
+            else:
+                row_splitter = QSplitter(Qt.Orientation.Horizontal)
+                self._style_splitter(row_splitter)
+                root_splitter.addWidget(row_splitter)
+
+            for c in range(cols):
+                idx = r * cols + c
+                if idx >= len(self.html_paths):
+                    break
+                card = WebPageCard(
+                    self.html_paths[idx],
+                    lambda p, i=idx: self._on_card_selected(i),
+                    slider_handle=self._slider_handle,
+                )
+                self._cards.append(card)
+                row_splitter.addWidget(card)
+
+        clayout.addWidget(root_splitter)
+
+    def _style_splitter(self, splitter: QSplitter):
+        """卡片间细分隔线,2px,hover 时变强调色提示可拖。
+
+        cursor 由 Qt 默认提供(横向/纵向 resize 光标)。
+        """
+        splitter.setHandleWidth(2)
+        splitter.setChildrenCollapsible(False)
+        splitter.setStyleSheet(f"""
+            QSplitter::handle {{
+                background-color: {BORDER};
+            }}
+            QSplitter::handle:hover {{
+                background-color: {ACCENT};
+            }}
+            QSplitter::handle:horizontal {{
+                width: 2px;
+            }}
+            QSplitter::handle:vertical {{
+                height: 2px;
+            }}
+        """)
+
+    def _apply_confirm_style(self):
+        """根据 enabled 状态切换 Confirm 按钮样式。"""
+        if self.confirm_btn.isEnabled():
+            self.confirm_btn.setStyleSheet(f"""
+                QPushButton {{
+                    background: {ACCENT};
+                    color: white;
+                    border: none;
+                    border-radius: 6px;
+                    padding: 8px 20px;
+                    font-size: 14px;
+                    font-weight: 600;
+                }}
+                QPushButton:hover {{ background: {ACCENT_HOVER}; }}
+            """)
+        else:
+            self.confirm_btn.setStyleSheet(f"""
+                QPushButton {{
+                    background: {BORDER};
+                    color: {TEXT_MUTED};
+                    border: none;
+                    border-radius: 6px;
+                    padding: 8px 20px;
+                    font-size: 14px;
+                    font-weight: 600;
+                }}
+            """)
+
+    def _on_card_selected(self, idx: int):
+        """点击/按数字键 → 高亮该卡片。"""
+        # 取消之前的选中
+        if self._selected_index is not None:
+            self._cards[self._selected_index].set_selected(False)
+        # 选中新的
+        self._selected_index = idx
+        self._cards[idx].set_selected(True)
+        # 启用 Confirm
+        if not self.confirm_btn.isEnabled():
+            self.confirm_btn.setEnabled(True)
+            self._apply_confirm_style()
+
+    def _on_confirm(self):
+        if self._selected_index is None:
+            return
+        self._picked = self.html_paths[self._selected_index]
+        print(str(self._picked))
+        QApplication.instance().quit()
+
+    def keyPressEvent(self, event):
+        key = event.key()
+        if key == Qt.Key.Key_Escape:
+            self.close()
+            return
+        if key in (Qt.Key.Key_Return, Qt.Key.Key_Enter):
+            if self._selected_index is not None:
+                self._on_confirm()
+                event.accept()
+                return
+        if Qt.Key.Key_1 <= key <= Qt.Key.Key_9:
+            idx = key - Qt.Key.Key_1
+            if 0 <= idx < len(self.html_paths):
+                self._on_card_selected(idx)
+                event.accept()
+                return
+        super().keyPressEvent(event)
+
+    def closeEvent(self, event):
+        """用户主动关闭(按 X / Esc / Alt+F4)—— 写一行机器可读的取消标记。"""
+        if self._picked is None:
+            print(
+                "[web-picker] cancelled: window closed without selection",
+                file=sys.stderr,
+            )
+        event.accept()
+        QApplication.instance().quit()
+
+
+def main():
+    # 项目级 .env —— 让用户钉一个默认主题,不必每次 --theme
+    # 自动建空文件,跟 svg-picker 行为一致
+    env_file = Path(".env")
+    if not env_file.is_file():
+        env_file.write_text(
+            "# web-picker config —— 取消注释并改值即可覆盖默认\n"
+            "# WEB_PICKER_THEME = sky\n",
+            encoding="utf-8",
+        )
+
+    env_from_file = {}
+    for line in env_file.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        k, _, v = line.partition("=")
+        env_from_file[k.strip()] = v.strip().strip('"').strip("'")
+
+    parser = argparse.ArgumentParser(
+        prog="web-picker",
+        description="Render 1-9 HTML previews in a native grid; human clicks "
+                    "(or presses 1-9) to highlight, then clicks Confirm "
+                    "(or presses Enter) to commit. The picked file path is "
+                    "printed to stdout.",
+    )
+    parser.add_argument(
+        "htmls", nargs="+",
+        help=f"1-{MAX_OPTIONS} HTML files to compare",
+    )
+    parser.add_argument(
+        "--theme", "-t",
+        choices=list(THEMES.keys()),
+        default=None,
+        help="背景主题。可选: " + ", ".join(THEMES)
+             + "。优先级: CLI > $WEB_PICKER_THEME > .env > 默认 cream",
+    )
+    parser.add_argument(
+        "--width", type=int, default=None,
+        help="窗口宽度(像素)。不传则按屏幕自适应 (默认: 自动)",
+    )
+    parser.add_argument(
+        "--height", type=int, default=None,
+        help="窗口高度(像素)。不传则按屏幕自适应 (默认: 自动)",
+    )
+    parser.add_argument(
+        "--maximize", action="store_true",
+        help="打开时最大化窗口,占满屏幕可用区域",
+    )
+    parser.add_argument(
+        "--slider-handle", type=int, default=0,
+        help="缩放 slider 拖把宽度(像素)。默认 0 = 用 Qt 默认 (推荐 14-24,触控板/触屏用更大)",
+    )
+    args = parser.parse_args()
+
+    if args.width is not None and args.width < 100:
+        parser.error(f"--width 必须 >= 100,got {args.width}")
+    if args.height is not None and args.height < 100:
+        parser.error(f"--height 必须 >= 100,got {args.height}")
+    if args.maximize and (args.width is not None or args.height is not None):
+        parser.error("--maximize 不能与 --width/--height 同时使用")
+    if args.slider_handle < 0 or args.slider_handle > 40:
+        parser.error(f"--slider-handle 必须在 0-40 之间,got {args.slider_handle}")
+
+    if not 1 <= len(args.htmls) <= MAX_OPTIONS:
+        parser.error(
+            f"web-picker supports 1-{MAX_OPTIONS} variants, "
+            f"got {len(args.htmls)}. Refine the candidates and rerun."
+        )
+
+    paths = []
+    for arg in args.htmls:
+        p = Path(arg).resolve()
+        if not p.is_file():
+            print(f"[web-picker] error: not a file: {arg}", file=sys.stderr)
+            sys.exit(1)
+        paths.append(p)
+
+    # 主题优先级:CLI > 环境变量 > .env > 内置默认 cream
+    theme = (
+        args.theme
+        or os.environ.get("WEB_PICKER_THEME")
+        or env_from_file.get("WEB_PICKER_THEME")
+        or "cream"
+    )
+    apply_theme(theme)
+
+    app = QApplication(sys.argv)
+    app.setStyle("fusion")
+
+    win = MainWindow(paths, width=args.width, height=args.height, slider_handle=args.slider_handle)
+    if args.maximize:
+        win.showMaximized()
+    else:
+        win.show()
+
+    sys.exit(app.exec())

web_picker-0.2.0.dist-info/METADATA

@@ -0,0 +1,280 @@
+Metadata-Version: 2.5
+Name: web-picker
+Version: 0.2.0
+Summary: A native GUI tool for AI agents to ask humans to visually pick one of N HTML variants
+Project-URL: Homepage, https://github.com/human-picker/web-picker
+Project-URL: Source, https://github.com/human-picker/web-picker
+Project-URL: Issues, https://github.com/human-picker/web-picker/issues
+Author-email: RinKokawa <rin@rinco.cc>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,compare,gui,html,human-in-the-loop,picker,preview,pyside6,qt,web
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Environment :: X11 Applications :: Qt
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: pyside6>=6.5
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Requires-Dist: twine>=4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# web-picker
+
+[![PyPI version](https://img.shields.io/pypi/v/web-picker)](https://pypi.org/project/web-picker/)
+[![Python versions](https://img.shields.io/pypi/pyversions/web-picker)](https://pypi.org/project/web-picker/)
+[![License](https://img.shields.io/pypi/l/web-picker)](https://github.com/human-picker/web-picker/blob/main/LICENSE)
+[![Downloads](https://img.shields.io/pypi/dm/web-picker)](https://pypistats.org/packages/web-picker)
+
+**A Human-in-the-Loop Visual Comparator for AI Agents**
+
+> Companion to [svg-picker](https://pypi.org/project/svg-picker/), inspired by [HULA: Human-In-the-Loop Software Development Agents](https://arxiv.org/abs/2411.12924) (ICSE SEIP 2025)
+
+---
+
+## What Is This?
+
+When AI agents write web code, they often propose multiple visual approaches in text — *"should the hero be a left-aligned image with caption, or a centered headline with gradient, or a video background?"* Describing these in markdown is hard for the human to evaluate.
+
+**web-picker turns those text descriptions into actual rendered previews.** The AI writes 2-9 candidate HTML files, calls `web-picker a.html b.html c.html`, and a native window opens showing every candidate side-by-side. The human clicks the one they prefer (or presses `1`/`2`/`3`). The picked file path is printed to stdout, which the AI reads to continue with the chosen design.
+
+**The human provides visual judgment. The AI handles everything else.**
+
+---
+
+## Background: Why "Human-in-the-Loop"?
+
+The paper [HULA: Human-In-the-Loop Software Development Agents](https://arxiv.org/abs/2411.12924) (Takerngsaksiri et al., ICSE SEIP 2025) demonstrates a critical insight:
+
+> Existing LLM-based coding agents rarely incorporate human feedback at intermediate stages. When humans can intervene during plan generation and code writing — not just review final output — development time and effort decrease significantly.
+
+web-picker applies this principle to a specific, narrow task: **HTML variant selection**. It is the visual-design counterpart to [svg-picker](https://pypi.org/project/svg-picker/), which solves icon selection. Together they form a minimal toolkit for AI agents to consult humans on small, reversible design decisions without dragging them into a full review loop.
+
+---
+
+## How It Works
+
+```
+User/CI:  web-picker opt1.html opt2.html opt3.html
+            │
+            ▼
+   ┌────────────────────────────────┐
+   │  Native window (PySide6)       │
+   │  ┌─────────┐ ┌─────────┐ ┌────┐│
+   │  │  opt1   │ │  opt2   │ │op3 ││
+   │  │  HTML   │ │  HTML   │ │HTML││
+   │  │ preview │ │ preview │ │prv ││
+   │  └─────────┘ └─────────┘ └────┘│
+   │  ← Human clicks / presses 1-3  │
+   │       (highlights the card)    │
+   │  ← Then clicks Confirm or ↩    │
+   └──────────────────┬─────────────┘
+                      │
+                      ▼
+        Picked path → stdout → AI reads it
+```
+
+Two-step pick: clicking a card (or pressing `1`-`9`) **highlights** it; only clicking **Confirm** (or pressing `Enter`) commits the choice. This gives hesitant users a moment to look, then change their mind, before committing. The page itself is **view-only** — iframe interactivity is intentionally sacrificed so a click on the card surface always means "select this one".
+
+---
+
+## Features
+
+- **Native GUI** — PySide6 window, no browser popup
+- **HTML rendering** — each option rendered via embedded Chromium (`QWebEngineView`)
+- **Adaptive grid** — 1-9 options laid out to maximize per-card area
+- **Draggable resize** — drag the handles between cards to make any preview wider/taller
+- **Open in real browser** — double-click a card to open it in your system default browser for full-size inspection
+- **Two-step pick** — click a card to highlight, then Confirm (or `Enter`) to commit; users can change their mind before committing
+- **Keyboard shortcuts** — `1`-`9` to highlight, `Enter` to confirm, `Esc` to cancel
+- **Cancellation signal** — closing the window writes `[web-picker] cancelled: ...` to stderr
+- **Themable** — `cream` / `sky` / `dark` via `--theme`
+- **One-step install** — `pip install web-picker`, single command
+- **Zero config** — no API keys, no servers, no infrastructure
+
+---
+
+## Install
+
+```bash
+pip install web-picker
+```
+
+Or for development:
+```bash
+pip install -e .
+```
+
+**Troubleshooting**: if you see `QtWebEngineWidgets is not available in this install`, run `pip install PySide6-Addons`. Some minimal PySide6 installs ship only the Essentials subset.
+
+---
+
+## Usage
+
+```bash
+web-picker <file1.html> [file2.html ...]    # 1-9 files
+```
+
+### Options
+
+| Flag | Description |
+|---|---|
+| `-t`, `--theme <name>` | Background theme. Choices: `cream` (default), `sky`, `dark` |
+| `--width <px>` | Override window width in pixels (default: auto-fit screen) |
+| `--height <px>` | Override window height in pixels (default: auto-fit screen) |
+| `--maximize` | Open the window maximized to fill the screen (cannot combine with `--width`/`--height`) |
+| `--slider-handle <px>` | Zoom-slider knob width in pixels (default: `0` = Qt default; recommended `14`-`24` for trackpad/touch) |
+
+#### Default Theme via `.env`
+
+Don't want to type `--theme dark` every time? Drop a `.env` in the directory you launch `web-picker` from:
+
+```env
+# Uncomment to override the default theme
+# WEB_PICKER_THEME = sky
+```
+
+Precedence: `--theme` CLI flag > `$WEB_PICKER_THEME` shell variable > `.env` file > built-in `cream`.
+
+The `.env` file is created automatically on first launch with the options commented out.
+
+### Examples
+
+```bash
+web-picker hero-a.html hero-b.html hero-c.html     # 3 hero variants
+web-picker landing.html                             # confirm a single design
+web-picker card.html card-dark.html card-outline.html card-flat.html --theme dark
+web-picker hero-a.html hero-b.html --maximize       # fill the screen for easier preview
+web-picker hero-a.html hero-b.html --width 1920 --height 1080   # pin to a specific size
+web-picker hero-a.html hero-b.html hero-c.html --slider-handle 20 # chunky zoom knobs for trackpad use
+```
+
+### The HTML Input Contract
+
+Each file passed to `web-picker` MUST be a **complete, standalone HTML document** — `<!DOCTYPE html>` through `</html>`. The agent is responsible for writing them; web-picker does no rendering magic.
+
+Relative paths (CSS, images, fonts) work fine because each file is loaded via `file://`. Inline styles, external CDNs, and even `<script>` blocks are all permitted and rendered as-is. Each option is a real browser tab — animations, hover effects, the works.
+
+A minimal example (each file is a full HTML page):
+
+```html
+<!-- hero-a.html -->
+<!DOCTYPE html>
+<html><body style="margin:0; font-family:sans-serif">
+  <div style="height:100vh; display:grid; place-items:center; background:#1e3a8a; color:white">
+    <h1>Welcome to Acme</h1>
+  </div>
+</body></html>
+```
+
+### Layout Strategy
+
+| Options | Grid |
+|---|---|
+| 1 | 1×1 |
+| 2 | 1×2 |
+| 3 | 1×3 |
+| 4 | 2×2 |
+| 5-6 | 2×3 |
+| 7-9 | 3×3 |
+
+More than 9 options is rejected — the human can't meaningfully compare that many at once, and 10+ `QWebEngineView` instances will exhaust your RAM.
+
+### Steps
+
+1. Window opens, every option rendered side-by-side
+2. **Drag** the handles between cards to resize any preview — if a card feels too narrow, pull it wider to inspect the detail
+3. **Double-click** a card to open it in your system default browser (useful when an embedded preview is too small to judge typography or animations)
+4. **Click** a card (or press its number key `1`-`9`) to highlight it — a purple border marks your current selection
+5. **Click another card** to change your selection, or click **Confirm** (top-right) / press `Enter` to commit
+6. Window closes; the picked file's absolute path is on stdout
+7. **Close the window** (X) or press `Esc` to cancel — a `[web-picker] cancelled: ...` line is written to stderr
+
+---
+
+## For AI Agents
+
+### As a Claude Code Skill
+
+Place this file as `~/.claude/skills/web-picker.md`:
+
+```markdown
+# web-picker
+
+Compare 2-9 HTML variants and let the human visually pick one.
+
+Usage: web-picker <file1.html> [file2.html ...]
+
+The human clicks a card (or presses 1-9) to highlight, then clicks
+Confirm (or presses Enter) to commit. The picked file's absolute
+path is printed to stdout. If the window is closed without confirming,
+a "[web-picker] cancelled: ..." line is written to stderr — read stderr
+to distinguish cancel from crash.
+```
+
+### Programmatic Usage
+
+```python
+import subprocess
+
+result = subprocess.run(
+    ["web-picker", "hero-a.html", "hero-b.html", "hero-c.html"],
+    capture_output=True, text=True,
+)
+
+if result.returncode != 0:
+    raise RuntimeError(f"web-picker crashed: {result.stderr}")
+
+if "[web-picker] cancelled" in result.stderr:
+    # 用户主动关闭窗口,没选
+    print("User cancelled without picking")
+else:
+    # 正常完成 —— result.stdout 是被选中的文件绝对路径
+    chosen_path = result.stdout.strip()
+    print(f"User picked: {chosen_path}")
+```
+
+---
+
+## Comparison
+
+| | web-picker | svg-picker | HULA (Atlassian) |
+|---|---|---|---|
+| Decision type | HTML variant (1 of N) | SVG icon (N of M) | Full software dev |
+| Visual surface | Embedded web pages | Icon thumbnails | Plan + code review |
+| Scope | Single tool, single task | Single tool, single task | Full agent framework |
+| Human role | Visual design judge | Visual icon judge | Plan + code reviewer |
+| Deployment | `pip install` | `pip install` | Jira plugin |
+| Target | AI agents | AI agents | Human engineers |
+
+web-picker and svg-picker share the same philosophy: **the human only intervenes on narrow, reversible, visual decisions** — everything else stays with the agent.
+
+---
+
+## Related Work
+
+- [HULA: Human-In-the-Loop Software Development Agents](https://arxiv.org/abs/2411.12924) — ICSE SEIP 2025
+- [svg-picker](https://pypi.org/project/svg-picker/) — sibling tool for icon selection
+- [acte](https://github.com/j66n/acte) — Framework for GUI-like Agent Tools
+- [OpenUI](https://github.com/thesysdev/openui) — Open Standard for Generative UI
+
+---
+
+## License
+
+MIT

web_picker-0.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+web_picker/__init__.py,sha256=vdMibxOuY_9t8OR8x4Ypw0ydmKq3B8F225BdoScsfuQ,152
+web_picker/__main__.py,sha256=YfjoadGknsNg1NA49mNlre72X9ow2OhDjSPStoo8x2o,94
+web_picker/app.py,sha256=iqdwntUkwgBlb2zRjRn8gPYTVmx04oFQSDk54xLlLj8,20340
+web_picker-0.2.0.dist-info/METADATA,sha256=F14amVzlsmYIMI8KbMx3Vk41dOwQWesLEM-AlPfreK8,12020
+web_picker-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+web_picker-0.2.0.dist-info/entry_points.txt,sha256=x84tsbgdohSsSmS7OL_edN03LRf0duCFB_mt0f9l7lU,51
+web_picker-0.2.0.dist-info/licenses/LICENSE,sha256=keU11UEIUMTVEQHCrIjNASMypSyYEijEq-1MzqD9_0k,1066
+web_picker-0.2.0.dist-info/RECORD,,

web_picker-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

web_picker-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+web-picker = web_picker.app:main

web_picker-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RinKokawa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.