clipwright-overlay 0.1.0__py3-none-any.whl

clipwright_overlay/__init__.py

@@ -0,0 +1,3 @@
+"""clipwright-overlay: MCP tool for adding image overlays to an OTIO timeline."""
+
+__version__ = "0.1.0"

clipwright_overlay/overlay.py

@@ -0,0 +1,781 @@
+"""overlay.py — clipwright-overlay orchestration layer.
+
+Handles the full flow: input validation -> load timeline -> validate options
+-> idempotency check -> add image_overlay marker -> save timeline -> return envelope.
+
+Design decisions:
+- _add_overlay_inner() is the raising implementation; add_overlay() is the public
+  boundary that catches ClipwrightError and converts to error_result.
+- Value-range validation is performed manually (OQ-1) for precise error hints.
+- image_path is stored as a RELATIVE posix path under the output timeline parent
+  dir (V2-3) to ensure round-trip stability across project moves.
+- x/y allowlist ^[A-Za-z0-9_()+\\-*/. ]+$ prevents filtergraph injection (V2-5).
+- Idempotency: exact duplicate (all metadata fields match) -> no-op with warning.
+  Comparison uses the stored relative image_path string (V2-3).
+- Non-destructive: input OTIO bytes are never modified; output is always new.
+- Rate determination: first clip source_range -> existing image_overlay marker
+  rate -> fallback 1000.0 with warning.
+- Boundary check _check_output_within_timeline_dir is a local copy of the
+  clipwright-text implementation to avoid cross-package imports.
+  When changing the logic here, ensure behaviour remains in sync with
+  clipwright-text's _check_output_within_timeline_dir; the two functions must
+  enforce the same boundary contract.
+- This module is subprocess-free (annotation layer; no ffmpeg/ffprobe calls).
+"""
+
+from __future__ import annotations
+
+import collections.abc
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+import opentimelineio as otio
+from clipwright.envelope import error_result, ok_result
+from clipwright.errors import ClipwrightError, ErrorCode
+from clipwright.otio_utils import add_marker, get_markers, load_timeline, save_timeline
+from clipwright.schemas import RationalTimeModel, TimeRangeModel, ToolResult
+
+from clipwright_overlay import __version__
+from clipwright_overlay.schemas import AddOverlayOptions
+
+# ---------------------------------------------------------------------------
+# Module constants
+# ---------------------------------------------------------------------------
+
+# Control-character pattern for image_path and position expressions.
+# Includes: NUL-US (\x00-\x1f), DEL (\x7f).
+_CONTROL_CHAR_PATTERN = re.compile(r"[\x00-\x1f\x7f]")
+
+# x/y allowlist: permits alphanumeric, underscore, parentheses, arithmetic
+# operators, dot, and space. Rejects : ; [ ] , ' and control characters (V2-5).
+# This covers ffmpeg overlay expressions such as (W-w)/2, (H-h)/2,
+# main_w-overlay_w-10, and simple numeric positions like 0 or 100.
+_XY_ALLOWLIST = re.compile(r"^[A-Za-z0-9_()+\-*/. ]+$")
+
+# Allowed image file extensions for overlay (case-insensitive check via .lower()).
+_ALLOWED_IMAGE_EXTENSIONS: frozenset[str] = frozenset(
+    {".png", ".jpg", ".jpeg", ".webp"}
+)
+
+# Tolerance for float comparison in idempotency checks (rate-invariant).
+_IDEMPOTENCY_EPS: float = 1e-6
+
+# Maximum number of image_overlay markers allowed per timeline (V2-9 / DoS guard).
+_MAX_IMAGE_OVERLAYS: int = 64
+
+
+# ===========================================================================
+# Path boundary helpers (local copies; keep in sync with clipwright-text)
+# ===========================================================================
+
+
+def _check_output_within_timeline_dir(timeline: Path, output: Path) -> None:
+    """Verify that output is within the timeline's parent directory tree.
+
+    Mirrors clipwright-text _check_output_within_timeline_dir boundary contract.
+    Allows recursive subdirectories; raises PATH_NOT_ALLOWED only when the
+    resolved output is outside the timeline directory tree.
+
+    Intentionally re-implemented locally to avoid cross-package import of
+    clipwright-text (NR-L-4: cross-package imports between satellite tools
+    create tight coupling and break independent packaging/deployment).
+
+    Args:
+        timeline: Path to the input OTIO timeline file.
+        output: Output path to validate against the boundary.
+
+    Raises:
+        ClipwrightError: PATH_NOT_ALLOWED when output is outside the
+            timeline's parent directory tree.
+    """
+    try:
+        allowed_base = timeline.parent.resolve()
+        target_resolved = output.resolve()
+        target_str = str(target_resolved)
+        base_str = str(allowed_base)
+        if not (
+            target_str == base_str
+            or target_str.startswith(base_str + "/")
+            or target_str.startswith(base_str + "\\")
+        ):
+            raise ClipwrightError(
+                code=ErrorCode.PATH_NOT_ALLOWED,
+                message="Output path points outside the project boundary.",
+                hint=(
+                    "Place the output file within the same directory as the "
+                    "OTIO timeline, or in a subdirectory of it."
+                ),
+            )
+    except ClipwrightError:
+        raise
+    except OSError:
+        # resolve() failed (network path, symlink loop, etc.): fall back to
+        # absolute()-based best-effort comparison.
+        try:
+            allowed_base_abs = str(timeline.parent.absolute())
+            target_abs = str(output.absolute())
+            if not (
+                target_abs == allowed_base_abs
+                or target_abs.startswith(allowed_base_abs + "/")
+                or target_abs.startswith(allowed_base_abs + "\\")
+            ):
+                raise ClipwrightError(
+                    code=ErrorCode.PATH_NOT_ALLOWED,
+                    message="Output path points outside the project boundary.",
+                    hint=(
+                        "Place the output file within the same directory as the "
+                        "OTIO timeline, or in a subdirectory of it."
+                    ),
+                )
+        except ClipwrightError:
+            raise
+        except OSError:
+            # Skip only when absolute() also fails (truly unresolvable path).
+            pass
+
+
+def _check_within_image_overlay_dir(output_otio_path: Path, resolved: Path) -> None:
+    """Verify the resolved image path is within the output timeline's parent dir tree.
+
+    Uses the same boundary contract as _check_output_within_timeline_dir but
+    applied to the image file: the allowed base is the output OTIO's parent dir
+    (V2-3 / ADR-OV-3). This ensures that render-side re-validation (which uses
+    the timeline parent as the base) will also pass, since the output timeline
+    is the input to render.
+
+    Args:
+        output_otio_path: Path to the output OTIO file (determines allowed base).
+        resolved: Resolved absolute path to the image file to validate.
+
+    Raises:
+        ClipwrightError: PATH_NOT_ALLOWED when the image is outside the
+            output timeline's parent directory tree.
+    """
+    try:
+        allowed_base = output_otio_path.resolve().parent
+        target_str = str(resolved)
+        base_str = str(allowed_base)
+        if not (
+            target_str == base_str
+            or target_str.startswith(base_str + "/")
+            or target_str.startswith(base_str + "\\")
+        ):
+            raise ClipwrightError(
+                code=ErrorCode.PATH_NOT_ALLOWED,
+                message="Image path points outside the project boundary.",
+                hint=(
+                    "Place the image file within the same directory as the "
+                    "output OTIO timeline, or in a subdirectory of it."
+                ),
+            )
+    except ClipwrightError:
+        raise
+    except OSError:
+        try:
+            allowed_base_abs = str(output_otio_path.absolute().parent)
+            target_abs = str(resolved)
+            if not (
+                target_abs == allowed_base_abs
+                or target_abs.startswith(allowed_base_abs + "/")
+                or target_abs.startswith(allowed_base_abs + "\\")
+            ):
+                raise ClipwrightError(
+                    code=ErrorCode.PATH_NOT_ALLOWED,
+                    message="Image path points outside the project boundary.",
+                    hint=(
+                        "Place the image file within the same directory as the "
+                        "output OTIO timeline, or in a subdirectory of it."
+                    ),
+                )
+        except ClipwrightError:
+            raise
+        except OSError:
+            pass
+
+
+# ===========================================================================
+# Validation helpers
+# ===========================================================================
+
+
+def _validate_overlay_fields(options: AddOverlayOptions, output: str) -> None:
+    """Validate value-range, image_path (4-stage), and position expression fields.
+
+    Validation order (fixed to keep error messages deterministic — ADR-OV-2):
+      1. Value ranges (start_sec, duration_sec, scale, opacity, fade_in_sec,
+         fade_out_sec, fade sum)
+      2. image_path 4-stage:
+         a. path safety: single-quote or control char (INVALID_INPUT)
+            — checked before resolve() to prevent ValueError from control chars
+              and to ensure safety always precedes existence/extension checks
+         b. co-location (PATH_NOT_ALLOWED)
+         c. existence (FILE_NOT_FOUND, basename only)
+         d. extension allowlist (INVALID_INPUT)
+      3. x/y allowlist (INVALID_INPUT) (V2-5)
+
+    Path safety is placed before co-location because:
+    - control chars in the path cause Path.resolve() to raise ValueError on Windows
+    - single-quotes in the path must be rejected before the file's existence is
+      checked (the file is typically absent with a bad path)
+    All violations raise ClipwrightError on the first failure.
+
+    Args:
+        options: AddOverlayOptions to validate.
+        output: Output OTIO file path (used for co-location boundary).
+
+    Raises:
+        ClipwrightError: On the first validation failure.
+    """
+    out = Path(output)
+
+    # --- 1. Value ranges ---
+    if options.start_sec < 0:
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Overlay start time must be 0 or greater.",
+            hint="Set start_sec to a non-negative value.",
+        )
+    if options.duration_sec <= 0:
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Overlay duration must be greater than 0.",
+            hint="Set duration_sec to a positive number of seconds.",
+        )
+    # Manual recheck for scale (V2-9): schema is first line of defence; manual
+    # recheck provides a precise hint for values that slip through or are set
+    # programmatically after construction.
+    if options.scale <= 0 or options.scale > 8.0:
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Scale must be in the range (0, 8.0].",
+            hint=(
+                "Set scale to a positive value no greater than 8.0 "
+                "(e.g. 1.0 for original size)."
+            ),
+        )
+    if options.opacity < 0 or options.opacity > 1.0:
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Opacity must be between 0.0 and 1.0.",
+            hint="Set opacity to a value in the range [0.0, 1.0].",
+        )
+    if options.fade_in_sec < 0:
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Fade-in duration must be 0 or greater.",
+            hint="Set fade_in_sec to a non-negative value.",
+        )
+    if options.fade_out_sec < 0:
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Fade-out duration must be 0 or greater.",
+            hint="Set fade_out_sec to a non-negative value.",
+        )
+    if options.fade_in_sec + options.fade_out_sec > options.duration_sec:
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Fade-in plus fade-out exceeds the overlay duration.",
+            hint=(
+                "Reduce fade durations or increase duration_sec so fades fit within it."
+            ),
+        )
+
+    # --- 2. image_path 4-stage validation ---
+
+    # 2a. path safety: single-quote or control char — checked BEFORE resolve() to:
+    #     (1) avoid ValueError from control chars embedded in the path on Windows,
+    #     (2) ensure safety violations surface before existence/extension checks.
+    if "'" in options.image_path:
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Image path must not contain single-quote characters.",
+            hint=(
+                "Remove single-quotes from the image file path "
+                "(they would corrupt filtergraph quoting)."
+            ),
+        )
+    if _CONTROL_CHAR_PATTERN.search(options.image_path):
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Image path must not contain control characters.",
+            hint="Remove control characters from the image file path.",
+        )
+
+    resolved = Path(options.image_path).resolve()
+
+    # 2b. co-location: image must be within the output timeline's parent dir tree (V2-3)
+    _check_within_image_overlay_dir(out, resolved)
+
+    # 2c. existence
+    if not resolved.exists():
+        raise ClipwrightError(
+            code=ErrorCode.FILE_NOT_FOUND,
+            message=f"Image file not found: {Path(options.image_path).name}",
+            hint="Verify the image path and ensure the file exists.",
+        )
+
+    # 2d. extension allowlist
+    if resolved.suffix.lower() not in _ALLOWED_IMAGE_EXTENSIONS:
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message=(
+                f"Image extension '{resolved.suffix}' is not supported. "
+                f"Allowed: {', '.join(sorted(_ALLOWED_IMAGE_EXTENSIONS))}."
+            ),
+            hint="Use a supported image format: .png, .jpg, .jpeg, or .webp.",
+        )
+
+    # --- 3. x/y allowlist (V2-5) ---
+    if not _XY_ALLOWLIST.fullmatch(options.x):
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="x expression contains forbidden characters.",
+            hint=(
+                "Use only alphanumeric characters, underscores, parentheses, "
+                "arithmetic operators (+, -, *, /), dot, and space. "
+                "Forbidden: : ; [ ] , ' and control characters."
+            ),
+        )
+    if not _XY_ALLOWLIST.fullmatch(options.y):
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="y expression contains forbidden characters.",
+            hint=(
+                "Use only alphanumeric characters, underscores, parentheses, "
+                "arithmetic operators (+, -, *, /), dot, and space. "
+                "Forbidden: : ; [ ] , ' and control characters."
+            ),
+        )
+
+
+# ===========================================================================
+# Metadata and idempotency helpers
+# ===========================================================================
+
+
+def _overlay_metadata_dict(
+    options: AddOverlayOptions,
+    output: str,
+    version: str,
+) -> dict[str, Any]:
+    """Build the clipwright metadata dict for an image_overlay marker.
+
+    Stores the image_path as a RELATIVE posix path from the output timeline
+    parent dir (V2-3): this ensures round-trip stability when the project is
+    moved, as long as the relative layout between the timeline and image is
+    preserved. render reconstructs the absolute path as:
+      (Path(timeline_path).resolve().parent / rel).resolve()
+
+    Args:
+        options: Validated AddOverlayOptions.
+        output: Output OTIO file path (determines the relative base).
+        version: Package version string to embed in metadata.
+
+    Returns:
+        Dict to store under marker.metadata["clipwright"].
+
+    Raises:
+        ClipwrightError: PATH_NOT_ALLOWED if relpath contains '..', which
+            indicates the image is outside the output parent tree (defense-in-depth).
+    """
+    resolved = Path(options.image_path).resolve()
+    timeline_parent = Path(output).resolve().parent
+    try:
+        rel_str = os.path.relpath(resolved, timeline_parent)
+    except ValueError:
+        # Different drive on Windows: relpath raises ValueError -> co-location violation
+        raise ClipwrightError(
+            code=ErrorCode.PATH_NOT_ALLOWED,
+            message="Image path points outside the project boundary.",
+            hint=(
+                "Place the image file within the same directory as the "
+                "output OTIO timeline, or in a subdirectory of it."
+            ),
+        ) from None
+    rel = Path(rel_str).as_posix()
+    # Defense-in-depth (V2-3): if co-location check passed but relpath still yields
+    # a '..' prefix, treat as PATH_NOT_ALLOWED.
+    if rel.startswith(".."):
+        raise ClipwrightError(
+            code=ErrorCode.PATH_NOT_ALLOWED,
+            message="Image path points outside the project boundary.",
+            hint=(
+                "Place the image file within the same directory as the "
+                "output OTIO timeline, or in a subdirectory of it."
+            ),
+        )
+    return {
+        "tool": "clipwright-overlay",
+        "version": version,
+        "kind": "image_overlay",
+        "image_path": rel,
+        "start_sec": options.start_sec,
+        "duration_sec": options.duration_sec,
+        "x": options.x,
+        "y": options.y,
+        "scale": options.scale,
+        "opacity": options.opacity,
+        "fade_in_sec": options.fade_in_sec,
+        "fade_out_sec": options.fade_out_sec,
+    }
+
+
+def _is_duplicate_overlay(
+    marker: otio.schema.Marker, options: AddOverlayOptions, output: str
+) -> bool:
+    """Return True if marker is an exact duplicate of the given options.
+
+    Compares all AddOverlayOptions fields stored in marker.metadata["clipwright"]
+    against the current options. Uses approximate float comparison for numeric
+    fields to be rate-invariant. image_path comparison is done on the relative
+    posix string (V2-3): both the stored value and the computed relative path
+    of the new options must match exactly.
+
+    Args:
+        marker: An existing image_overlay marker to compare.
+        options: Current AddOverlayOptions to check for duplication.
+        output: Output OTIO file path (for computing relative image_path).
+
+    Returns:
+        True if all fields match (complete duplicate -> no-op).
+    """
+    cw = marker.metadata.get("clipwright", {})
+    if not isinstance(cw, collections.abc.Mapping):
+        return False
+    if cw.get("kind") != "image_overlay":
+        return False
+
+    # Compute the relative posix path for the new options
+    try:
+        resolved = Path(options.image_path).resolve()
+        timeline_parent = Path(output).resolve().parent
+        try:
+            rel_str = os.path.relpath(resolved, timeline_parent)
+        except ValueError:
+            return False
+        new_rel = Path(rel_str).as_posix()
+        if new_rel.startswith(".."):
+            return False
+    except Exception:
+        return False
+
+    # String fields: exact match (image_path as relative, x, y)
+    if cw.get("image_path") != new_rel:
+        return False
+    if cw.get("x") != options.x:
+        return False
+    if cw.get("y") != options.y:
+        return False
+
+    # Float fields: approximate comparison (rate-invariant tolerance)
+    def _approx_eq(a: object, b: float) -> bool:
+        if not isinstance(a, (int, float)):
+            return False
+        return abs(float(a) - b) <= _IDEMPOTENCY_EPS
+
+    if not _approx_eq(cw.get("start_sec"), options.start_sec):
+        return False
+    if not _approx_eq(cw.get("duration_sec"), options.duration_sec):
+        return False
+    if not _approx_eq(cw.get("scale"), options.scale):
+        return False
+    if not _approx_eq(cw.get("opacity"), options.opacity):
+        return False
+    if not _approx_eq(cw.get("fade_in_sec"), options.fade_in_sec):
+        return False
+    return _approx_eq(cw.get("fade_out_sec"), options.fade_out_sec)
+
+
+# ===========================================================================
+# Rate resolution
+# ===========================================================================
+
+
+def _resolve_rate(
+    video_track: otio.schema.Track,
+) -> tuple[float, list[str]]:
+    """Determine the rate for RationalTime construction.
+
+    Priority:
+      1. source_range.rate of the first Clip in the V1 track.
+      2. marked_range.start_time.rate of the first existing image_overlay marker.
+      3. Fallback: 1000.0 with a warning.
+
+    Args:
+        video_track: The first Video track from the loaded timeline.
+
+    Returns:
+        Tuple of (rate: float, warnings: list[str]). warnings is non-empty only
+        when the fallback rate is used.
+    """
+    # Priority 1: first clip's source_range rate
+    for item in video_track:
+        if isinstance(item, otio.schema.Clip) and item.source_range is not None:
+            return float(item.source_range.start_time.rate), []
+
+    # Priority 2: existing image_overlay marker rate
+    for marker in video_track.markers:
+        cw = marker.metadata.get("clipwright", {})
+        if (
+            isinstance(cw, collections.abc.Mapping)
+            and cw.get("kind") == "image_overlay"
+        ):
+            return float(marker.marked_range.start_time.rate), []
+
+    # Priority 3: fallback
+    return 1000.0, [
+        "Could not determine timeline rate from clips or existing markers; "
+        "using fallback rate 1000.0. Consider providing a timeline with clips."
+    ]
+
+
+# ===========================================================================
+# Core implementation
+# ===========================================================================
+
+
+def _add_overlay_inner(
+    timeline: str,
+    output: str,
+    options: AddOverlayOptions,
+) -> ToolResult:
+    """Internal implementation of add_overlay. Raises ClipwrightError on failure.
+
+    Validation order:
+      1. output suffix == .otio
+      2. output parent directory exists
+      3. output boundary check (PATH_NOT_ALLOWED when outside timeline dir)
+      4. output != timeline
+      5. field validation (_validate_overlay_fields, including image_path 4-stage)
+      6. load timeline (FILE_NOT_FOUND / OTIO_ERROR propagate)
+      7. first TrackKind.Video track exists
+      8. rate determination
+      9. _MAX_IMAGE_OVERLAYS cap check (V2-9)
+     10. idempotency check (exact duplicate -> no-op)
+     11. add marker (image_{n}, all metadata fields, relative image_path)
+     12. save timeline atomically
+     13. return ok_result
+
+    Args:
+        timeline: Input OTIO timeline file path.
+        output: Output OTIO file path.
+        options: Validated AddOverlayOptions.
+
+    Returns:
+        ToolResult from ok_result.
+
+    Raises:
+        ClipwrightError: On any validation or I/O failure.
+    """
+    out = Path(output)
+    inp = Path(timeline)
+
+    # --- Step 1: output suffix validation ---
+    if out.suffix.lower() != ".otio":
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Output path must have a .otio extension.",
+            hint="Change the output file extension to .otio (e.g., 'result.otio').",
+        )
+
+    # --- Step 2: output parent directory exists ---
+    if not out.parent.exists():
+        raise ClipwrightError(
+            code=ErrorCode.FILE_NOT_FOUND,
+            message="Output directory does not exist.",
+            hint="Create the output directory before calling clipwright_add_overlay.",
+        )
+
+    # --- Step 3: output boundary check ---
+    _check_output_within_timeline_dir(inp, out)
+
+    # --- Step 4: output != timeline ---
+    if out.resolve() == inp.resolve():
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Output path must differ from the input timeline path.",
+            hint=(
+                "Provide a distinct output path (e.g., append '_overlay' before .otio)."
+            ),
+        )
+
+    # --- Step 5: field validation (value ranges + image_path 4-stage + x/y) ---
+    _validate_overlay_fields(options, output)
+
+    # --- Step 6: load timeline ---
+    if not inp.exists():
+        raise ClipwrightError(
+            code=ErrorCode.FILE_NOT_FOUND,
+            message=f"Timeline file not found: {inp.name}",
+            hint="Verify the timeline path and ensure the file exists.",
+        )
+    timeline_obj = load_timeline(timeline)
+
+    # --- Step 7: find first Video track ---
+    video_track: otio.schema.Track | None = None
+    for track in timeline_obj.tracks:
+        if track.kind == otio.schema.TrackKind.Video:
+            video_track = track
+            break
+
+    if video_track is None:
+        raise ClipwrightError(
+            code=ErrorCode.UNSUPPORTED_OPERATION,
+            message="No video track found in the timeline.",
+            hint=(
+                "clipwright_add_overlay requires a timeline with at least one "
+                "video track to attach image overlay markers."
+            ),
+        )
+
+    # --- Step 8: rate determination ---
+    rate, rate_warnings = _resolve_rate(video_track)
+
+    # --- Step 9: _MAX_IMAGE_OVERLAYS cap (V2-9) ---
+    existing_markers = get_markers(timeline_obj, kind="image_overlay")
+    if len(existing_markers) >= _MAX_IMAGE_OVERLAYS:
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Too many image overlays on this timeline.",
+            hint=(
+                f"The timeline already has {len(existing_markers)} image overlays "
+                f"and the maximum is {_MAX_IMAGE_OVERLAYS}. "
+                f"Remove some image_overlay markers before adding more."
+            ),
+        )
+
+    # --- Step 10: idempotency check ---
+    for existing in existing_markers:
+        if _is_duplicate_overlay(existing, options, output):
+            # Exact duplicate: save a copy of the timeline and return no-op result
+            save_timeline(timeline_obj, output)
+            overlay_count = len(existing_markers)
+            basename = Path(options.image_path).name
+            return ok_result(
+                summary=(
+                    f"Image overlay '{basename}' at {options.start_sec}s for "
+                    f"{options.duration_sec}s already exists; no marker added. "
+                    f"Timeline has {overlay_count} image overlay(s). "
+                    f"Output: {out.name}."
+                ),
+                data={
+                    "applied": 0,
+                    "overlay_count": overlay_count,
+                    "start_sec": options.start_sec,
+                    "duration_sec": options.duration_sec,
+                },
+                artifacts=[
+                    {
+                        "role": "timeline",
+                        "path": str(out.resolve()),
+                        "format": "otio",
+                    }
+                ],
+                warnings=["Identical image overlay already exists; no marker added."],
+            )
+
+    # --- Step 11: add marker ---
+    # Count existing image_overlay markers to determine name index
+    n = len(existing_markers)
+    marker_name = f"image_{n}"
+
+    # Build marker metadata with relative image_path (V2-3)
+    metadata = _overlay_metadata_dict(options, output, __version__)
+
+    # Build marked_range using the resolved rate
+    marked_range = TimeRangeModel(
+        start_time=RationalTimeModel(
+            value=options.start_sec * rate,
+            rate=rate,
+        ),
+        duration=RationalTimeModel(
+            value=options.duration_sec * rate,
+            rate=rate,
+        ),
+    )
+
+    add_marker(
+        video_track,
+        marked_range=marked_range,
+        name=marker_name,
+        color=None,
+        metadata=metadata,
+    )
+
+    # --- Step 12: save timeline ---
+    save_timeline(timeline_obj, output)
+
+    # --- Step 13: build result ---
+    overlay_count = n + 1
+    out_resolved = out.resolve()
+    basename = Path(options.image_path).name
+    summary = (
+        f"Added image overlay '{basename}' at {options.start_sec}s for "
+        f"{options.duration_sec}s. "
+        f"Timeline now has {overlay_count} image overlay(s). "
+        f"Output: {out.name}."
+    )
+
+    all_warnings = list(rate_warnings)
+
+    return ok_result(
+        summary=summary,
+        data={
+            "applied": 1,
+            "overlay_count": overlay_count,
+            "start_sec": options.start_sec,
+            "duration_sec": options.duration_sec,
+        },
+        artifacts=[
+            {
+                "role": "timeline",
+                "path": str(out_resolved),
+                "format": "otio",
+            }
+        ],
+        warnings=all_warnings if all_warnings else None,
+    )
+
+
+def add_overlay(
+    timeline: str,
+    output: str,
+    options: AddOverlayOptions | None,
+) -> dict[str, Any]:
+    """Add an image_overlay marker to an OTIO timeline.
+
+    Non-destructive: does not modify the input timeline file.
+    Idempotent: calling with the same options on an already-annotated timeline
+    produces applied=0 and a warning rather than duplicating the marker.
+
+    The image_path is stored as a relative posix path in the marker metadata
+    (V2-3) to ensure round-trip stability across project directory moves.
+
+    Returns a plain dict (ToolResult.model_dump()) so callers can use both
+    dict-style access (``result["ok"]``, ``result.get(...)``) and
+    ``isinstance(result, dict)`` checks.  server.py wraps this in ToolResult
+    for FastMCP's typed outputSchema.
+
+    Args:
+        timeline: Input OTIO timeline file path.
+        output: Output OTIO file path (must end in .otio, must differ from timeline).
+        options: AddOverlayOptions with required image_path/start_sec/duration_sec
+            and optional style fields. None returns INVALID_INPUT.
+
+    Returns:
+        dict with the ToolResult envelope keys: ok, summary, data, artifacts, warnings,
+        error.
+    """
+    if options is None:
+        return error_result(
+            "INVALID_INPUT",
+            "options is required but was not provided.",
+            "Pass an AddOverlayOptions with at least image_path, start_sec, "
+            "and duration_sec.",
+        ).model_dump()
+    try:
+        return _add_overlay_inner(timeline, output, options).model_dump()
+    except ClipwrightError as exc:
+        return error_result(exc.code, exc.message, exc.hint).model_dump()

clipwright_overlay/schemas.py

@@ -0,0 +1,85 @@
+"""schemas.py — Pydantic schema for AddOverlayOptions.
+
+Defines the options model for image overlay annotation. Core shared types
+(MediaRef, Artifact, ToolResult) are imported from clipwright.schemas and must
+not be redefined here (§6 convention contract).
+
+Value-range validation (start_sec>=0, duration_sec>0, opacity 0..1, etc.) is
+intentionally NOT enforced here via Pydantic constraints, except for scale which
+uses Field(gt=0, le=8.0) per V2-9. All other range checks are validated manually
+inside overlay.py so that the error envelope carries a precise hint (decision OQ-1).
+AddOverlayOptions uses extra="forbid" so unknown keys are rejected at the schema
+boundary before business logic runs.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class AddOverlayOptions(BaseModel):
+    """Options for adding an image overlay marker to an OTIO timeline.
+
+    image_path, start_sec, and duration_sec are required. All other fields are
+    optional with sensible defaults for a centered watermark-style overlay.
+
+    Value-range validation (start_sec>=0, duration_sec>0, opacity 0..1, etc.)
+    is performed manually in _add_overlay_inner to produce precise error hints —
+    not via Pydantic constraints (decision OQ-1), except scale which has
+    Field(gt=0, le=8.0) per V2-9 (schema is the first line of defence for scale).
+
+    x/y expressions are validated against the allowlist ^[A-Za-z0-9_()+\\-*/. ]+$
+    in overlay.py (V2-5): this rejects `:;[],'` and control characters.
+    """
+
+    model_config = ConfigDict(extra="forbid", allow_inf_nan=False)
+
+    image_path: str
+    """Path to the image file to overlay.
+
+    Must be co-located in the output parent dir tree.
+    """
+
+    start_sec: float
+    """Start time in seconds from the beginning of the timeline. Must be >= 0."""
+
+    duration_sec: float
+    """Duration of the image overlay in seconds. Must be > 0."""
+
+    x: str = "(W-w)/2"
+    """Horizontal position as an ffmpeg overlay expression (uses CAPITAL W/w).
+
+    Default: horizontally centered. Validated against allowlist in overlay.py (V2-5).
+    """
+
+    y: str = "(H-h)/2"
+    """Vertical position as an ffmpeg overlay expression (uses CAPITAL H/h).
+
+    Default: vertically centered. Validated against allowlist in overlay.py (V2-5).
+    """
+
+    scale: float = Field(default=1.0, gt=0, le=8.0)
+    """Scale factor for the overlay image. Must be in range (0, 8.0] (V2-9).
+
+    1.0 = original size. Values > 1.0 enlarge; < 1.0 shrink.
+    Schema enforces gt=0 and le=8.0 as the first line of defence (V2-9).
+    overlay.py also validates this range manually to emit a precise hint (OQ-1).
+    """
+
+    opacity: float = 1.0
+    """Opacity of the overlay image.
+
+    Range [0.0, 1.0] validated manually in overlay.py.
+    """
+
+    fade_in_sec: float = 0.3
+    """Fade-in duration in seconds. Must be >= 0.
+
+    Sum of fade_in_sec + fade_out_sec must not exceed duration_sec.
+    """
+
+    fade_out_sec: float = 0.3
+    """Fade-out duration in seconds. Must be >= 0.
+
+    Sum of fade_in_sec + fade_out_sec must not exceed duration_sec.
+    """

clipwright_overlay/server.py

@@ -0,0 +1,87 @@
+"""server.py — MCP server for clipwright-overlay image overlay annotation.
+
+Exposes a single MCP tool: clipwright_add_overlay.
+Delegates all business logic to overlay.add_overlay; no logic here.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from clipwright.envelope import error_result
+from clipwright.schemas import ToolResult
+from mcp.server.fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+from pydantic import Field
+
+from clipwright_overlay.overlay import add_overlay
+from clipwright_overlay.schemas import AddOverlayOptions
+
+mcp = FastMCP("clipwright-overlay")
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=False,
+    )
+)
+def clipwright_add_overlay(
+    timeline: Annotated[str, Field(description="Input OTIO timeline file path.")],
+    output: Annotated[
+        str,
+        Field(
+            description=(
+                "Output OTIO file path where the annotated timeline is written. "
+                "Must end in .otio and differ from the input timeline path."
+            )
+        ),
+    ],
+    options: Annotated[
+        AddOverlayOptions | None,
+        Field(
+            description=(
+                "Image overlay options. image_path, start_sec, and duration_sec are "
+                "required; all other fields have sensible defaults."
+            )
+        ),
+    ] = None,
+) -> ToolResult:
+    """Add an image_overlay marker to an OTIO timeline.
+
+    readOnlyHint=True: this tool writes only a new .otio output file; the input
+    media and the input timeline are never modified. The new-file write is outside
+    the readOnly scope per the MCP annotation contract — readOnly refers to
+    existing resources, and the output is a freshly created file.
+
+    Later rendering by clipwright-render materializes image_overlay markers as
+    ffmpeg overlay filters. Idempotent: calling with identical options on an
+    already-annotated timeline produces applied=0 with a warning rather than
+    duplicating the marker. Multiple distinct calls accumulate image_0/image_1/...
+    markers which clipwright-render reads to apply overlay filters.
+    """
+    if options is None:
+        return error_result(
+            "INVALID_INPUT",
+            "options is required but was not provided.",
+            (
+                "Pass options with at least image_path, start_sec, and duration_sec "
+                '(e.g., {"image_path": "/path/to/logo.png", "start_sec": 1.0, '
+                '"duration_sec": 3.0}).'
+            ),
+        )
+    result = add_overlay(timeline=timeline, output=output, options=options)
+    if isinstance(result, ToolResult):
+        return result
+    return ToolResult.model_validate(result)
+
+
+def main() -> None:
+    """Entry point for the clipwright-overlay MCP server (stdio transport)."""
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

clipwright_overlay-0.1.0.dist-info/METADATA

@@ -0,0 +1,300 @@
+Metadata-Version: 2.3
+Name: clipwright-overlay
+Version: 0.1.0
+Summary: MCP tool for adding image overlays to an OTIO timeline.
+Author: satoh-y-0323
+Author-email: satoh-y-0323 <shoma.papa.0323@gmail.com>
+License: MIT
+Requires-Dist: clipwright>=0.3.0
+Requires-Dist: mcp[cli]>=1.27.2
+Requires-Dist: opentimelineio>=0.18
+Requires-Dist: pydantic>=2
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# clipwright-overlay
+
+MCP tool that annotates an OTIO timeline with a static image overlay (logo,
+watermark, lower-third graphic, end card) for materialisation by `clipwright-render`.
+
+## Overview
+
+`clipwright-overlay` writes an `image_overlay` marker to the first video track (V1)
+of an OTIO timeline. The marker stores the image path, position, scale, opacity, and
+timing. `clipwright-render` reads the marker and inserts the image as an extra `-i`
+input, building an FFmpeg filter chain that composites the image onto the video during
+the single render pass.
+
+**Design principle** (separation of annotation and realisation):
+`clipwright-overlay` writes only the OTIO; it does not invoke FFmpeg or touch media
+files. All image compositing is deferred to `clipwright-render`.
+
+## Prerequisites
+
+- Python 3.11 or later
+- `clipwright` core package (shared types, envelope, OTIO utils)
+- No FFmpeg is needed at annotation time. FFmpeg is only invoked by `clipwright-render`
+  at realisation time.
+
+> **Note — clipwright-render >= 0.10.0 required for materialisation.**
+> `clipwright-overlay` only *annotates* the OTIO timeline; it never invokes FFmpeg.
+> The actual image compositing is performed by `clipwright-render`. Image overlay support
+> was added in `clipwright-render` **0.10.0** — earlier versions will ignore the
+> `image_overlay` markers and produce output without the overlay.
+> Install or upgrade before calling `clipwright_render` on an annotated timeline:
+>
+> ```bash
+> pip install "clipwright-render>=0.10.0"
+> ```
+
+## MCP Tool: `clipwright_add_overlay`
+
+### Parameters
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `timeline` | `string` | required | Input OTIO timeline file path (`.otio`). The parent directory is the co-location root for the image file. |
+| `output` | `string` | required | Output OTIO timeline file path (`.otio`). Must differ from `timeline`. |
+| `image_path` | `string` | required | Path to the overlay image. Must be co-located under the output timeline's parent directory (see Co-location Constraint). Supported formats: `.png`, `.jpg`, `.jpeg`, `.webp`. |
+| `start_sec` | `float` | required | Start time in seconds (≥ 0) when the overlay becomes visible. |
+| `duration_sec` | `float` | required | Duration in seconds (> 0) that the overlay remains visible. |
+| `x` | `string` | `"(W-w)/2"` | Horizontal position expression (FFmpeg overlay filter syntax). `W` = base video width, `w` = overlay width. Default centres the overlay horizontally. |
+| `y` | `string` | `"(H-h)/2"` | Vertical position expression. `H` = base video height, `h` = overlay height. Default centres the overlay vertically. |
+| `scale` | `float` | `1.0` | Overlay scale factor relative to the original image size. Range: `(0, 8]`. `1.0` = original size. |
+| `opacity` | `float` | `1.0` | Opacity of the overlay. Range: `[0.0, 1.0]`. `1.0` = fully opaque. |
+| `fade_in_sec` | `float` | `0.3` | Fade-in duration in seconds (≥ 0). `0.0` = no fade-in (overlay appears immediately). |
+| `fade_out_sec` | `float` | `0.3` | Fade-out duration in seconds (≥ 0). `0.0` = no fade-out. `fade_in_sec + fade_out_sec` must not exceed `duration_sec`. |
+
+### Return value
+
+```json
+{
+  "ok": true,
+  "summary": "Added image overlay 'logo.png' at 5.0s for 10.0s. Timeline now has 1 image overlay(s). Output: output.otio.",
+  "data": {
+    "applied": 1,
+    "overlay_count": 1,
+    "start_sec": 5.0,
+    "duration_sec": 10.0
+  },
+  "artifacts": [{"role": "timeline", "path": "/absolute/path/to/output.otio", "format": "otio"}],
+  "warnings": []
+}
+```
+
+When an identical overlay is submitted again (same parameters), `applied` returns `0`
+and a warning is added; no duplicate marker is written (idempotency).
+
+### Error codes (annotation time)
+
+| Code | Cause |
+|------|-------|
+| `INVALID_INPUT` | `start_sec < 0`, `duration_sec ≤ 0`, `scale ≤ 0` or `scale > 8`, `opacity` outside `[0, 1]`, `fade_in_sec < 0`, `fade_out_sec < 0`, or `fade_in_sec + fade_out_sec > duration_sec` |
+| `INVALID_INPUT` | `image_path` extension is not `.png`, `.jpg`, `.jpeg`, or `.webp` |
+| `INVALID_INPUT` | `image_path` or `x` / `y` expression contains a control character or a prohibited character (`: ; [ ] , '`) |
+| `INVALID_INPUT` | `output` path is identical to `timeline` path |
+| `INVALID_INPUT` | Timeline already has 64 `image_overlay` markers (per-timeline limit) |
+| `FILE_NOT_FOUND` | `image_path` does not exist |
+| `PATH_NOT_ALLOWED` | `image_path` is outside the output timeline's parent directory tree |
+| `UNSUPPORTED_OPERATION` | The input timeline has no V1 video track |
+
+### Error codes (render time, raised by `clipwright-render`)
+
+| Code | Cause |
+|------|-------|
+| `SUBPROCESS_FAILED` | The overlay image could not be decoded by FFmpeg (corrupt file or unsupported encoding). Message shows the image basename only (CWE-209). Hint: `"The overlay image may be corrupt or an unsupported format; provide a valid .png/.jpg/.jpeg/.webp."` |
+
+## Co-location Constraint
+
+The `image_path` **must be located under the same directory as the output `.otio` file**
+(or in a recursive subdirectory of it).
+
+**Why this rule exists:**
+`clipwright-render` enforces the same co-location boundary for all resources referenced
+in an OTIO timeline (sources, subtitles, image overlays). If the image were outside that
+boundary, the annotation would succeed but render would immediately fail with
+`PATH_NOT_ALLOWED`.
+
+By enforcing co-location at annotation time, `clipwright-overlay` guarantees that any
+`.otio` it produces will pass through `clipwright-render` without a `PATH_NOT_ALLOWED`
+error.
+
+**Relative-path storage (V2-3 round-trip portability):**
+The image path is stored in the OTIO marker as a POSIX relative path from the output
+timeline's parent directory (e.g. `images/logo.png`). When `clipwright-render` reads the
+marker, it reconstructs the absolute path using the timeline file's parent directory as the
+base. This means projects remain portable when the entire directory tree is moved or copied
+to another location, as long as the relative positions of the timeline and image files are
+preserved.
+
+```
+project/
+  logo.png           ← allowed (same directory, stored as "logo.png")
+  assets/
+    watermark.png    ← allowed (subdirectory, stored as "assets/watermark.png")
+  output.otio        ← output timeline
+```
+
+```
+/other/path/logo.png  ← PATH_NOT_ALLOWED
+```
+
+## Position Expressions
+
+`x` and `y` accept FFmpeg overlay filter expressions. The following variables are
+available at render time:
+
+| Variable | Meaning |
+|----------|---------|
+| `W` | Base video width in pixels |
+| `H` | Base video height in pixels |
+| `w` | Overlay image width (after scaling) |
+| `h` | Overlay image height (after scaling) |
+| `main_w` | Alias for `W` |
+| `main_h` | Alias for `H` |
+| `overlay_w` | Alias for `w` |
+| `overlay_h` | Alias for `h` |
+
+### Common position examples
+
+| Position | `x` | `y` |
+|----------|-----|-----|
+| Centre | `(W-w)/2` (default) | `(H-h)/2` (default) |
+| Top-left (10 px margin) | `10` | `10` |
+| Top-right (10 px margin) | `W-w-10` | `10` |
+| Bottom-left (10 px margin) | `10` | `H-h-10` |
+| Bottom-right (10 px margin) | `W-w-10` | `H-h-10` |
+| Bottom-centre | `(W-w)/2` | `H-h-10` |
+
+**Allowed characters in `x` / `y`:** letters, digits, `_`, `(`, `)`, `+`, `-`, `*`,
+`/`, `.`, and space. Characters `: ; [ ] , '` and control characters are prohibited to
+prevent FFmpeg filtergraph injection.
+
+## `readOnlyHint` Rationale
+
+`clipwright_add_overlay` carries `readOnlyHint=true` in its MCP annotations.
+
+`clipwright-overlay` writes only a new `.otio` file; the input media, the input
+timeline, and the image file are never modified. The new-file write is outside the
+readOnly scope (consistent with `clipwright-sequence`, `clipwright-trim`,
+`clipwright-silence`, and other annotation tools). This signals to AI orchestrators
+that the tool is safe for speculative execution and automatic retry without side effects.
+
+## Fade Chain
+
+The opacity and fade effect are implemented in a single filter chain per overlay:
+
+```
+[{N}:v]scale=iw*{scale}:-2,format=rgba,colorchannelmixer=aa={opacity},
+fade=t=in:st={start}:d={fade_in}:alpha=1,fade=t=out:st={end-fade_out}:d={fade_out}:alpha=1[ov{i}];
+{base}[ov{i}]overlay=x='{x}':y='{y}':enable='between(t,{start},{end})'[outvimg{i}]
+```
+
+- `scale=iw*{scale}:-2` — scale the image width by `scale`; height is computed
+  automatically with even rounding (`-2`) for yuv420p compatibility.
+- `format=rgba` — add an alpha channel to the image.
+- `colorchannelmixer=aa={opacity}` — set constant opacity (`aa` accepts a constant
+  double only; time-varying expressions are not supported by FFmpeg).
+- `fade=t=in:...:alpha=1` — ramp the alpha from 0 to 1 over `fade_in_sec`. When
+  `fade_in_sec == 0` this segment is omitted entirely (no degenerate `d=0` filter).
+- `fade=t=out:...:alpha=1` — ramp the alpha from 1 to 0 over `fade_out_sec`. Omitted
+  when `fade_out_sec == 0`.
+- The `fade:alpha=1` flag multiplies the existing alpha channel, so the effective
+  alpha ramps from `0 → opacity → 0` across the fade windows.
+- `overlay=x='{x}':y='{y}':enable='between(t,{start},{end})'` — composite the
+  prepared image onto the base video within the time window. `x` / `y` are
+  single-quoted (consistent with `enable` and `drawtext`).
+
+This chain is inserted after the `drawtext` filter, so image overlays appear on top
+of text overlays.
+
+## Two-Phase Workflow
+
+```
+clipwright_add_overlay(timeline, output, image_path, ...)   # Phase 1 — annotate OTIO
+        │
+        ▼  OTIO timeline with image_overlay marker
+clipwright_render(timeline, output_media)                   # Phase 2 — composite and encode
+        │
+        ▼  video with image/logo composited
+```
+
+### Stacking multiple overlays
+
+Multiple calls accumulate overlays on the same timeline:
+
+```python
+# Add a channel logo (top-right, always visible)
+r1 = await session.call_tool("clipwright_add_overlay", {
+    "timeline":      "/project/edit.otio",
+    "output":        "/project/with_logo.otio",
+    "image_path":    "/project/assets/logo.png",
+    "start_sec":     0.0,
+    "duration_sec":  120.0,
+    "x":             "W-w-20",
+    "y":             "20",
+    "scale":         0.15,
+    "opacity":       0.8,
+    "fade_in_sec":   0.0,
+    "fade_out_sec":  0.0
+})
+
+# Add a lower-third graphic at a specific moment
+r2 = await session.call_tool("clipwright_add_overlay", {
+    "timeline":      "/project/with_logo.otio",
+    "output":        "/project/with_logo_lowerthird.otio",
+    "image_path":    "/project/assets/lower_third.png",
+    "start_sec":     15.0,
+    "duration_sec":  5.0,
+    "x":             "(W-w)/2",
+    "y":             "H-h-80",
+    "scale":         0.6,
+    "opacity":       1.0,
+    "fade_in_sec":   0.3,
+    "fade_out_sec":  0.3
+})
+
+# Render
+render_result = await session.call_tool("clipwright_render", {
+    "timeline": "/project/with_logo_lowerthird.otio",
+    "output":   "/project/final.mp4"
+})
+```
+
+## MCP Client Registration
+
+`clipwright-overlay` does not require FFmpeg at annotation time, so no environment
+variables are needed in the MCP server entry. Register it in your MCP client
+configuration (`.mcp.json` / `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "clipwright-overlay": {
+      "command": "clipwright-overlay"
+    }
+  }
+}
+```
+
+`clipwright-render` (which materialises the OTIO into video) still requires
+`CLIPWRIGHT_FFMPEG`.
+
+## Installation
+
+Within a uv workspace:
+
+```bash
+uv run --package clipwright-overlay clipwright-overlay
+```
+
+Or install from PyPI:
+
+```bash
+pip install clipwright-overlay
+clipwright-overlay
+```
+
+## License
+
+MIT — See [LICENSE](../LICENSE) for details.

clipwright_overlay-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+clipwright_overlay/__init__.py,sha256=YoC3SnGwU0geJPwPQdJUt5yE9XvOlLX0UXqf9dVNwY4,105
+clipwright_overlay/overlay.py,sha256=-CSo1qMEPLw7PTxEQsB3hCKb2kdrg-JcisYeHwq4VgY,30432
+clipwright_overlay/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clipwright_overlay/schemas.py,sha256=-e6-twohoMJ7EGH68ejivCQ-XEWcMIpjMQiPbrALKLE,3116
+clipwright_overlay/server.py,sha256=csS4W7tPsGOxzv4ZJZkfsJ8Hlx82NzNbFERMFZkuYtU,2980
+clipwright_overlay-0.1.0.dist-info/WHEEL,sha256=oBsDExVIEya4llboy9Ce1l6on8xt3GrtT29y6pYVypw,81
+clipwright_overlay-0.1.0.dist-info/entry_points.txt,sha256=FvA4M4qt0YofBsjdgAcPvEFgopWXon0UrJYxVz7pvko,71
+clipwright_overlay-0.1.0.dist-info/METADATA,sha256=9ScbvDlradLvx8nsuoN-1xQptaG9nW1Z752G7Msd1oY,12140
+clipwright_overlay-0.1.0.dist-info/RECORD,,

clipwright_overlay-0.1.0.dist-info/WHEEL

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

clipwright_overlay-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+clipwright-overlay = clipwright_overlay.server:main
+