clickcast 0.1.0__py3-none-any.whl

clickcast/__init__.py

@@ -0,0 +1,12 @@
+"""clickcast — drive a browser, return a reel + AI-readable feedback sidecar."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from clickcast.reel import AsyncReel, Reel, discover
+
+try:
+    __version__ = version("clickcast")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["AsyncReel", "Reel", "__version__", "discover"]

clickcast/__main__.py

@@ -0,0 +1,4 @@
+from clickcast.cli import app
+
+if __name__ == "__main__":
+    app()

clickcast/annotate/__init__.py

@@ -0,0 +1,5 @@
+"""Frame annotator — overlay ripples, labels, cursor trail, progress bar."""
+
+from clickcast.annotate.annotator import AnnotateConfig, Annotator
+
+__all__ = ["AnnotateConfig", "Annotator"]

clickcast/annotate/annotator.py

@@ -0,0 +1,251 @@
+"""Frame annotator — composite click ripples, labels, cursor trail, progress bar."""
+
+from __future__ import annotations
+
+import io
+from dataclasses import dataclass
+from importlib.resources import files
+from pathlib import Path
+from typing import Literal
+
+from PIL import Image, ImageDraw, ImageFont
+
+__all__ = ["AnnotateConfig", "Annotator"]
+
+_BUNDLED_FONT = "DejaVuSans.ttf"
+
+
+@dataclass(slots=True)
+class AnnotateConfig:
+    """Toggles + tunables for every annotation layer.
+
+    Every field is safe to override in isolation; defaults produce a
+    legible-on-any-background overlay at ~1280x800.
+    """
+
+    # Layer toggles ------------------------------------------------------
+    clicks: bool = True
+    labels: bool = True
+    cursor: bool = True
+    progress: bool = True
+
+    # Font ---------------------------------------------------------------
+    font_path: str | Path | None = None  # None → bundled DejaVuSans.ttf
+    font_size: int = 20
+
+    # Label bar ----------------------------------------------------------
+    label_max_chars: int = 60
+    label_padding_x: int = 24
+    label_padding_y: int = 12
+    label_bg_color: tuple[int, int, int, int] = (20, 20, 20, 192)
+    label_fg_color: tuple[int, int, int, int] = (255, 255, 255, 255)
+    label_radius: int = 8
+    label_position: Literal["top", "bottom"] = "bottom"
+    label_margin: int = 32
+
+    # Click ripple -------------------------------------------------------
+    ripple_stages: int = 3
+    ripple_radius_min: int = 12
+    ripple_radius_max: int = 48
+    ripple_color: tuple[int, int, int] = (255, 255, 255)
+    ripple_alpha_start: int = 128
+    ripple_width: int = 3
+
+    # Cursor + trail -----------------------------------------------------
+    cursor_color: tuple[int, int, int, int] = (255, 220, 100, 240)
+    cursor_size: int = 14
+    cursor_trail_length: int = 6
+    cursor_trail_alpha_max: int = 160
+
+    # Progress bar -------------------------------------------------------
+    progress_height: int = 4
+    progress_color: tuple[int, int, int, int] = (100, 200, 255, 220)
+    progress_bg_color: tuple[int, int, int, int] = (255, 255, 255, 40)
+
+
+def _load_font(config: AnnotateConfig) -> ImageFont.FreeTypeFont | ImageFont.ImageFont:
+    if config.font_path:
+        return ImageFont.truetype(str(config.font_path), config.font_size)
+    resource = files("clickcast.annotate").joinpath("fonts").joinpath(_BUNDLED_FONT)
+    try:
+        data = resource.read_bytes()
+    except (FileNotFoundError, OSError):
+        # Last-resort fallback — bitmap font, tiny. Signals a packaging bug.
+        return ImageFont.load_default()
+    return ImageFont.truetype(io.BytesIO(data), config.font_size)
+
+
+class Annotator:
+    """Overlay annotations on captured frames.
+
+    Never mutates the input frame in place — `annotate()` writes to a new
+    file (`out_path` if given, otherwise `<stem>.annotated.png` next to the
+    input). Cursor trail state is maintained across calls; use
+    :meth:`reset_cursor` when starting a new scenario.
+    """
+
+    def __init__(self, config: AnnotateConfig | None = None) -> None:
+        self.config = config or AnnotateConfig()
+        self._font = _load_font(self.config)
+        self._cursor_history: list[tuple[int, int]] = []
+
+    def reset_cursor(self) -> None:
+        self._cursor_history.clear()
+
+    def annotate(
+        self,
+        frame_path: str | Path,
+        *,
+        out_path: str | Path | None = None,
+        step_index: int = 0,
+        total_steps: int = 1,
+        label: str | None = None,
+        cursor_xy: tuple[int, int] | None = None,
+        click_at: tuple[int, int] | None = None,
+        ripple_stage: int = 0,
+    ) -> Path:
+        """Composite the enabled layers onto ``frame_path``; return output Path.
+
+        ``ripple_stage`` is 1..``ripple_stages`` for the N frames after a
+        click; pass 0 when there was no click on this frame.
+        """
+        src = Path(frame_path)
+        dst = Path(out_path) if out_path else src.with_name(f"{src.stem}.annotated.png")
+        dst.parent.mkdir(parents=True, exist_ok=True)
+
+        with Image.open(src) as base:
+            canvas = base.convert("RGBA")
+
+        if cursor_xy is not None:
+            self._cursor_history.append(cursor_xy)
+            history_cap = max(self.config.cursor_trail_length + 1, 1)
+            while len(self._cursor_history) > history_cap:
+                self._cursor_history.pop(0)
+
+        if self.config.progress:
+            self._draw_progress(canvas, step_index, total_steps)
+        if self.config.clicks and click_at is not None and ripple_stage > 0:
+            self._draw_ripple(canvas, click_at, ripple_stage)
+        if self.config.cursor and self._cursor_history:
+            self._draw_cursor(canvas)
+        if self.config.labels and label:
+            self._draw_label(canvas, label)
+
+        canvas.convert("RGB").save(dst, format="PNG")
+        return dst
+
+    # ------------------------------------------------------------------
+    # Layers
+    # ------------------------------------------------------------------
+
+    def _draw_progress(self, canvas: Image.Image, step_index: int, total_steps: int) -> None:
+        cfg = self.config
+        w, h = canvas.size
+        overlay = Image.new("RGBA", canvas.size, (0, 0, 0, 0))
+        od = ImageDraw.Draw(overlay)
+        y = h - cfg.progress_height
+        od.rectangle([0, y, w, h], fill=cfg.progress_bg_color)
+        frac = (step_index + 1) / max(total_steps, 1)
+        od.rectangle([0, y, int(w * frac), h], fill=cfg.progress_color)
+        canvas.alpha_composite(overlay)
+
+    def _draw_ripple(
+        self,
+        canvas: Image.Image,
+        at: tuple[int, int],
+        stage: int,
+    ) -> None:
+        cfg = self.config
+        # stage 1..N — radius grows, alpha fades
+        t = min(1.0, stage / max(cfg.ripple_stages, 1))
+        radius = int(cfg.ripple_radius_min + t * (cfg.ripple_radius_max - cfg.ripple_radius_min))
+        alpha = max(0, int(cfg.ripple_alpha_start * (1 - t)))
+        overlay = Image.new("RGBA", canvas.size, (0, 0, 0, 0))
+        od = ImageDraw.Draw(overlay)
+        od.ellipse(
+            [at[0] - radius, at[1] - radius, at[0] + radius, at[1] + radius],
+            outline=(*cfg.ripple_color, alpha),
+            width=cfg.ripple_width,
+        )
+        canvas.alpha_composite(overlay)
+
+    def _draw_cursor(self, canvas: Image.Image) -> None:
+        cfg = self.config
+        overlay = Image.new("RGBA", canvas.size, (0, 0, 0, 0))
+        od = ImageDraw.Draw(overlay)
+
+        trail = self._cursor_history[:-1]
+        if trail:
+            for i, pos in enumerate(trail):
+                # Older = fainter
+                fade = (i + 1) / len(trail)
+                alpha = int(cfg.cursor_trail_alpha_max * fade)
+                r = max(2, cfg.cursor_size // 3)
+                od.ellipse(
+                    [pos[0] - r, pos[1] - r, pos[0] + r, pos[1] + r],
+                    fill=(*cfg.cursor_color[:3], alpha),
+                )
+
+        cx, cy = self._cursor_history[-1]
+        s = cfg.cursor_size
+        od.polygon(
+            [
+                (cx, cy - s // 2),
+                (cx + s // 2, cy),
+                (cx, cy + s // 2),
+                (cx - s // 2, cy),
+            ],
+            fill=cfg.cursor_color,
+            outline=(0, 0, 0, 220),
+        )
+        canvas.alpha_composite(overlay)
+
+    def _draw_label(self, canvas: Image.Image, text: str) -> None:
+        cfg = self.config
+        wrapped = _wrap(text, cfg.label_max_chars)
+
+        measure = ImageDraw.Draw(canvas)
+        bbox = measure.multiline_textbbox((0, 0), wrapped, font=self._font)
+        text_w = bbox[2] - bbox[0]
+        text_h = bbox[3] - bbox[1]
+
+        box_w = text_w + 2 * cfg.label_padding_x
+        box_h = text_h + 2 * cfg.label_padding_y
+
+        img_w, img_h = canvas.size
+        x = max(0, (img_w - box_w) // 2)
+        y = img_h - box_h - cfg.label_margin if cfg.label_position == "bottom" else cfg.label_margin
+
+        overlay = Image.new("RGBA", canvas.size, (0, 0, 0, 0))
+        od = ImageDraw.Draw(overlay)
+        od.rounded_rectangle(
+            [x, y, x + box_w, y + box_h],
+            radius=cfg.label_radius,
+            fill=cfg.label_bg_color,
+        )
+        # Draw text on the same overlay for correct compositing
+        od.multiline_text(
+            (x + cfg.label_padding_x, y + cfg.label_padding_y - bbox[1]),
+            wrapped,
+            font=self._font,
+            fill=cfg.label_fg_color,
+        )
+        canvas.alpha_composite(overlay)
+
+
+def _wrap(text: str, max_chars: int) -> str:
+    if len(text) <= max_chars:
+        return text
+    lines: list[str] = []
+    current = ""
+    for word in text.split():
+        candidate = word if not current else f"{current} {word}"
+        if len(candidate) <= max_chars:
+            current = candidate
+        else:
+            if current:
+                lines.append(current)
+            current = word
+    if current:
+        lines.append(current)
+    return "\n".join(lines)

clickcast/annotate/fonts/DejaVuSans-LICENSE.txt

@@ -0,0 +1,78 @@
+Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Upstream-Name: DejaVu fonts
+Upstream-Author: Stepan Roh <src@users.sourceforge.net> (original author),
+                  see /usr/share/doc/fonts-dejavu-core/AUTHORS for full list
+Source: https://dejavu-fonts.github.io/
+
+Files: *
+Copyright: Copyright (c) 2003 by Bitstream, Inc. All Rights Reserved. 
+ Bitstream Vera is a trademark of Bitstream, Inc.
+ DejaVu changes are in public domain.
+License: bitstream-vera
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of the fonts accompanying this license ("Fonts") and associated
+ documentation files (the "Font Software"), to reproduce and distribute the
+ Font Software, including without limitation the rights to use, copy, merge,
+ publish, distribute, and/or sell copies of the Font Software, and to permit
+ persons to whom the Font Software is furnished to do so, subject to the
+ following conditions:
+ .
+ The above copyright and trademark notices and this permission notice shall
+ be included in all copies of one or more of the Font Software typefaces.
+ .
+ The Font Software may be modified, altered, or added to, and in particular
+ the designs of glyphs or characters in the Fonts may be modified and
+ additional glyphs or characters may be added to the Fonts, only if the fonts
+ are renamed to names not containing either the words "Bitstream" or the word
+ "Vera".
+ .
+ This License becomes null and void to the extent applicable to Fonts or Font
+ Software that has been modified and is distributed under the "Bitstream
+ Vera" names.
+ .
+ The Font Software may be sold as part of a larger software package but no
+ copy of one or more of the Font Software typefaces may be sold by itself.
+ .
+ THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+ OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT,
+ TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL BITSTREAM OR THE GNOME
+ FOUNDATION BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING
+ ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES,
+ WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
+ THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE
+ FONT SOFTWARE.
+ .
+ Except as contained in this notice, the names of Gnome, the Gnome
+ Foundation, and Bitstream Inc., shall not be used in advertising or
+ otherwise to promote the sale, use or other dealings in this Font Software
+ without prior written authorization from the Gnome Foundation or Bitstream
+ Inc., respectively. For further information, contact: fonts at gnome dot
+ org.
+
+Files: debian/*
+Copyright: (C) 2005-2006 Peter Cernak <pce@users.sourceforge.net> 
+           (C) 2006-2011 Davide Viti <zinosat@tiscali.it>
+           (C) 2011-2013 Christian Perrier <bubulle@debian.org>
+           (C) 2013 Fabian Greffrath <fabian+debian@greffrath.com>
+License: GPL-2+
+ This program is free software; you can redistribute it
+ and/or modify it under the terms of the GNU General Public
+ License as published by the Free Software Foundation; either
+ version 2 of the License, or (at your option) any later
+ version.
+ .
+ This program is distributed in the hope that it will be
+ useful, but WITHOUT ANY WARRANTY; without even the implied
+ warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+ PURPOSE.  See the GNU General Public License for more
+ details.
+ .
+ You should have received a copy of the GNU General Public
+ License along with this package; if not, write to the Free
+ Software Foundation, Inc., 51 Franklin St, Fifth Floor,
+ Boston, MA  02110-1301 USA
+ .
+ On Debian systems, the full text of the GNU General Public
+ License version 2 can be found in the file
+ /usr/share/common-licenses/GPL-2'.

clickcast/capture/__init__.py

@@ -0,0 +1,5 @@
+"""Frame capture pipeline."""
+
+from clickcast.capture.recorder import FrameRef, Recorder
+
+__all__ = ["FrameRef", "Recorder"]

clickcast/capture/recorder.py

@@ -0,0 +1,194 @@
+"""Frame capture pipeline — turn a stream of actions into an ordered stream of PNGs."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from types import TracebackType
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from clickcast.core.actions import ActionResult, BaseStep
+    from clickcast.core.session import Session
+
+
+__all__ = ["FrameRef", "Recorder"]
+
+
+@dataclass(slots=True, frozen=True)
+class FrameRef:
+    path: Path
+    step_index: int
+    sub_index: int
+    cursor_xy: tuple[int, int] | None
+
+
+class Recorder:
+    """Owns a temp directory of PNG frames and produces a `frames.json` manifest.
+
+    Usage::
+
+        with Recorder(fps=12) as rec:
+            for step in scenario.steps:
+                await rec.pre_action(session)
+                result = await execute(step, session)
+                await rec.post_action(session, result, step)
+            paths = rec.flush()   # writes frames.json, returns ordered paths
+            encoder.encode(rec.frames_dir, out="tour.gif")   # (in #9)
+    """
+
+    def __init__(
+        self,
+        *,
+        fps: int = 12,
+        default_dwell: float = 1.0,
+        keep: bool = False,
+        out_dir: Path | str | None = None,
+    ) -> None:
+        if fps <= 0:
+            raise ValueError("fps must be positive")
+        if default_dwell < 0:
+            raise ValueError("default_dwell must be non-negative")
+
+        self.fps = fps
+        self.default_dwell = default_dwell
+        self.keep = keep
+        self.out_dir: Path = Path(out_dir) if out_dir is not None else Path("frames")
+
+        self._tmp: tempfile.TemporaryDirectory[str] | None = None
+        self._tmp_path: Path | None = None
+        self._frames: list[FrameRef] = []
+        self._step_index: int = -1
+        self._sub_index: int = 0
+        self._entered: bool = False
+
+    def __enter__(self) -> Recorder:
+        self._tmp = tempfile.TemporaryDirectory(prefix="clickcast-frames-")
+        self._tmp_path = Path(self._tmp.name)
+        self._entered = True
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        try:
+            if self.keep and self._tmp_path is not None:
+                self._persist()
+        finally:
+            if self._tmp is not None:
+                self._tmp.cleanup()
+            self._tmp = None
+            self._tmp_path = None
+            self._entered = False
+
+    @property
+    def frames(self) -> list[FrameRef]:
+        return list(self._frames)
+
+    @property
+    def frames_dir(self) -> Path:
+        if self._tmp_path is None:
+            raise RuntimeError("Recorder is not open — use `with Recorder(...) as rec:`")
+        return self._tmp_path
+
+    async def pre_action(self, session: Session) -> Path:
+        """Capture one frame BEFORE the action executes, opening a new step."""
+        self._step_index += 1
+        self._sub_index = 0
+        return await self._capture(session, cursor_xy=None)
+
+    async def post_action(
+        self,
+        session: Session,
+        result: ActionResult,
+        step: BaseStep,
+    ) -> list[Path]:
+        """Capture the post-state frame + padding copies for `dwell * fps`.
+
+        The action's own timing does not produce frames — its dwell period is
+        held on the post-state so the reel plays smoothly at `fps`.
+        """
+        dwell = step.dwell if step.dwell > 0 else self.default_dwell
+        n = max(1, round(dwell * self.fps))
+        first = await self._capture(session, cursor_xy=result.cursor_xy)
+        paths = [first]
+        for _ in range(1, n):
+            copy_path = self._next_path()
+            shutil.copyfile(first, copy_path)
+            self._record(copy_path, cursor_xy=result.cursor_xy)
+            paths.append(copy_path)
+        return paths
+
+    async def pad(
+        self,
+        session: Session,
+        frames: int,
+        cursor_xy: tuple[int, int] | None = None,
+    ) -> list[Path]:
+        """Force N padding frames of the current page state."""
+        if frames <= 0:
+            return []
+        first = await self._capture(session, cursor_xy=cursor_xy)
+        paths = [first]
+        for _ in range(1, frames):
+            copy_path = self._next_path()
+            shutil.copyfile(first, copy_path)
+            self._record(copy_path, cursor_xy=cursor_xy)
+            paths.append(copy_path)
+        return paths
+
+    def flush(self) -> list[Path]:
+        """Write `frames.json` next to the frames and return their ordered paths."""
+        if self._tmp_path is None:
+            raise RuntimeError("Recorder is not open — use `with Recorder(...) as rec:`")
+        manifest = {
+            "fps": self.fps,
+            "count": len(self._frames),
+            "frames": [
+                {
+                    "path": f.path.name,
+                    "step_index": f.step_index,
+                    "sub_index": f.sub_index,
+                    "cursor_xy": list(f.cursor_xy) if f.cursor_xy is not None else None,
+                }
+                for f in self._frames
+            ],
+        }
+        (self._tmp_path / "frames.json").write_text(json.dumps(manifest, indent=2))
+        return [f.path for f in self._frames]
+
+    async def _capture(self, session: Session, *, cursor_xy: tuple[int, int] | None) -> Path:
+        path = self._next_path()
+        await session.screenshot(path=path)
+        self._record(path, cursor_xy=cursor_xy)
+        return path
+
+    def _record(self, path: Path, *, cursor_xy: tuple[int, int] | None) -> None:
+        self._frames.append(
+            FrameRef(
+                path=path,
+                step_index=self._step_index,
+                sub_index=self._sub_index,
+                cursor_xy=cursor_xy,
+            )
+        )
+        self._sub_index += 1
+
+    def _next_path(self) -> Path:
+        if self._tmp_path is None:
+            raise RuntimeError("Recorder is not open — use `with Recorder(...) as rec:`")
+        step_idx = max(self._step_index, 0)
+        return self._tmp_path / f"frame-{step_idx:04d}-{self._sub_index:03d}.png"
+
+    def _persist(self) -> None:
+        assert self._tmp_path is not None
+        self.out_dir.mkdir(parents=True, exist_ok=True)
+        for entry in self._tmp_path.iterdir():
+            dst = self.out_dir / entry.name
+            shutil.copy2(entry, dst)