off-camber-open-frame 0.2.0__tar.gz → 0.2.2__tar.gz

{off_camber_open_frame-0.2.0/src/off_camber_open_frame.egg-info → off_camber_open_frame-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: off-camber-open-frame
-Version: 0.2.0
+Version: 0.2.2
 Summary: Open-source recognition and action for anything on a display.
 Author: Off-Camber
 License-Expression: Apache-2.0
@@ -32,6 +32,9 @@ Provides-Extra: agent
 Requires-Dist: anthropic; extra == "agent"
 Provides-Extra: mcp
 Requires-Dist: mcp<2,>=1.0; extra == "mcp"
+Provides-Extra: template
+Requires-Dist: Pillow; extra == "template"
+Requires-Dist: numpy; extra == "template"
 Dynamic: license-file
 
 <p align="center">
@@ -62,7 +65,7 @@ Open Frame is the deterministic execution layer behind AI agents, not the agent
 
 ## Status
 
-**Beta** (`v0.2.0`) — macOS-first. Available on PyPI as
+**Beta** (`v0.2.2`) — macOS-first. Available on PyPI as
 [`off-camber-open-frame`](https://pypi.org/project/off-camber-open-frame/).
 Evidence for this release comes from CI plus a local macOS live gate (including
 MCP stdio smoke); see [release gates](docs/RELEASE_GATES.md). Changelog:
@@ -79,7 +82,7 @@ MCP stdio smoke); see [release gates](docs/RELEASE_GATES.md). Changelog:
 ### 1. Install
 
 ```bash
-pip install "off-camber-open-frame[mcp,ocr,act,flow]"
+pip install "off-camber-open-frame[mcp,ocr,act,flow,template]"
 brew install tesseract
 ```
 
@@ -123,7 +126,7 @@ python -m openframe.cli doctor
 ```bash
 python3.11 -m venv .venv
 source .venv/bin/activate
-pip install -e ".[dev,ocr,act,flow,mcp]"
+pip install -e ".[dev,ocr,act,flow,mcp,template]"
 open-frame doctor
 open-frame mcp list-tools --json
 ```
@@ -138,6 +141,7 @@ brew install python@3.11
 
 - [MCP server setup](docs/MCP_SERVER.md) — Claude Desktop / Cursor config.
 - [Flow setup](docs/FLOW_SETUP.md) — define and run YAML flows.
+- [Template setup](docs/TEMPLATE_SETUP.md) — optional icon/image matching.
 - [API](docs/API.md) — use `Session` and MCP-oriented integration guidance.
 - [Act setup](docs/ACT_SETUP.md) and [Verify setup](docs/VERIFY_SETUP.md) — run safely with evidence.
 - [Full docs index](docs/README.md) — contributor and planning docs.

{off_camber_open_frame-0.2.0 → off_camber_open_frame-0.2.2}/README.md

@@ -26,7 +26,7 @@ Open Frame is the deterministic execution layer behind AI agents, not the agent
 
 ## Status
 
-**Beta** (`v0.2.0`) — macOS-first. Available on PyPI as
+**Beta** (`v0.2.2`) — macOS-first. Available on PyPI as
 [`off-camber-open-frame`](https://pypi.org/project/off-camber-open-frame/).
 Evidence for this release comes from CI plus a local macOS live gate (including
 MCP stdio smoke); see [release gates](docs/RELEASE_GATES.md). Changelog:
@@ -43,7 +43,7 @@ MCP stdio smoke); see [release gates](docs/RELEASE_GATES.md). Changelog:
 ### 1. Install
 
 ```bash
-pip install "off-camber-open-frame[mcp,ocr,act,flow]"
+pip install "off-camber-open-frame[mcp,ocr,act,flow,template]"
 brew install tesseract
 ```
 
@@ -87,7 +87,7 @@ python -m openframe.cli doctor
 ```bash
 python3.11 -m venv .venv
 source .venv/bin/activate
-pip install -e ".[dev,ocr,act,flow,mcp]"
+pip install -e ".[dev,ocr,act,flow,mcp,template]"
 open-frame doctor
 open-frame mcp list-tools --json
 ```
@@ -102,6 +102,7 @@ brew install python@3.11
 
 - [MCP server setup](docs/MCP_SERVER.md) — Claude Desktop / Cursor config.
 - [Flow setup](docs/FLOW_SETUP.md) — define and run YAML flows.
+- [Template setup](docs/TEMPLATE_SETUP.md) — optional icon/image matching.
 - [API](docs/API.md) — use `Session` and MCP-oriented integration guidance.
 - [Act setup](docs/ACT_SETUP.md) and [Verify setup](docs/VERIFY_SETUP.md) — run safely with evidence.
 - [Full docs index](docs/README.md) — contributor and planning docs.

{off_camber_open_frame-0.2.0 → off_camber_open_frame-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "off-camber-open-frame"
-version = "0.2.0"
+version = "0.2.2"
 description = "Open-source recognition and action for anything on a display."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -51,6 +51,10 @@ agent = [
 mcp = [
   "mcp>=1.0,<2",
 ]
+template = [
+  "Pillow",
+  "numpy",
+]
 
 [tool.setuptools]
 package-dir = { "" = "src" }

{off_camber_open_frame-0.2.0 → off_camber_open_frame-0.2.2/src/off_camber_open_frame.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: off-camber-open-frame
-Version: 0.2.0
+Version: 0.2.2
 Summary: Open-source recognition and action for anything on a display.
 Author: Off-Camber
 License-Expression: Apache-2.0
@@ -32,6 +32,9 @@ Provides-Extra: agent
 Requires-Dist: anthropic; extra == "agent"
 Provides-Extra: mcp
 Requires-Dist: mcp<2,>=1.0; extra == "mcp"
+Provides-Extra: template
+Requires-Dist: Pillow; extra == "template"
+Requires-Dist: numpy; extra == "template"
 Dynamic: license-file
 
 <p align="center">
@@ -62,7 +65,7 @@ Open Frame is the deterministic execution layer behind AI agents, not the agent
 
 ## Status
 
-**Beta** (`v0.2.0`) — macOS-first. Available on PyPI as
+**Beta** (`v0.2.2`) — macOS-first. Available on PyPI as
 [`off-camber-open-frame`](https://pypi.org/project/off-camber-open-frame/).
 Evidence for this release comes from CI plus a local macOS live gate (including
 MCP stdio smoke); see [release gates](docs/RELEASE_GATES.md). Changelog:
@@ -79,7 +82,7 @@ MCP stdio smoke); see [release gates](docs/RELEASE_GATES.md). Changelog:
 ### 1. Install
 
 ```bash
-pip install "off-camber-open-frame[mcp,ocr,act,flow]"
+pip install "off-camber-open-frame[mcp,ocr,act,flow,template]"
 brew install tesseract
 ```
 
@@ -123,7 +126,7 @@ python -m openframe.cli doctor
 ```bash
 python3.11 -m venv .venv
 source .venv/bin/activate
-pip install -e ".[dev,ocr,act,flow,mcp]"
+pip install -e ".[dev,ocr,act,flow,mcp,template]"
 open-frame doctor
 open-frame mcp list-tools --json
 ```
@@ -138,6 +141,7 @@ brew install python@3.11
 
 - [MCP server setup](docs/MCP_SERVER.md) — Claude Desktop / Cursor config.
 - [Flow setup](docs/FLOW_SETUP.md) — define and run YAML flows.
+- [Template setup](docs/TEMPLATE_SETUP.md) — optional icon/image matching.
 - [API](docs/API.md) — use `Session` and MCP-oriented integration guidance.
 - [Act setup](docs/ACT_SETUP.md) and [Verify setup](docs/VERIFY_SETUP.md) — run safely with evidence.
 - [Full docs index](docs/README.md) — contributor and planning docs.

{off_camber_open_frame-0.2.0 → off_camber_open_frame-0.2.2}/src/off_camber_open_frame.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ src/off_camber_open_frame.egg-info/entry_points.txt
 src/off_camber_open_frame.egg-info/requires.txt
 src/off_camber_open_frame.egg-info/top_level.txt
 src/openframe/__init__.py
+src/openframe/cancel.py
 src/openframe/cli.py
 src/openframe/doctor.py
 src/openframe/flow.py
@@ -25,6 +26,7 @@ src/openframe/agent/providers/__init__.py
 src/openframe/agent/providers/anthropic_provider.py
 src/openframe/capture/__init__.py
 src/openframe/capture/macos.py
+src/openframe/capture/sidecar.py
 src/openframe/integrations/__init__.py
 src/openframe/integrations/mcp/__init__.py
 src/openframe/integrations/mcp/adapter.py
@@ -33,12 +35,15 @@ src/openframe/recognize/__init__.py
 src/openframe/recognize/base.py
 src/openframe/recognize/coords.py
 src/openframe/recognize/debug.py
+src/openframe/recognize/defaults.py
 src/openframe/recognize/locator.py
 src/openframe/recognize/match.py
 src/openframe/recognize/a11y/__init__.py
 src/openframe/recognize/a11y/macos.py
 src/openframe/recognize/ocr/__init__.py
 src/openframe/recognize/ocr/tesseract.py
+src/openframe/recognize/template/__init__.py
+src/openframe/recognize/template/matcher.py
 src/openframe/verify/__init__.py
 src/openframe/verify/base.py
 src/openframe/verify/core.py
@@ -49,11 +54,14 @@ tests/test_agent_cost.py
 tests/test_agent_runner.py
 tests/test_calibration_fixture.py
 tests/test_capture.py
+tests/test_capture_geometry.py
 tests/test_cli.py
 tests/test_doctor.py
 tests/test_examples.py
 tests/test_flow.py
+tests/test_geometry_checks.py
 tests/test_imports.py
+tests/test_market_validation_tools.py
 tests/test_match.py
 tests/test_mcp_adapter.py
 tests/test_mcp_server.py
@@ -63,6 +71,7 @@ tests/test_recognize_locator.py
 tests/test_runner.py
 tests/test_selector_parity.py
 tests/test_session_api.py
+tests/test_template_recognizer.py
 tests/test_tesseract_recognizer.py
 tests/test_verify.py
 tests/test_window_state.py

{off_camber_open_frame-0.2.0 → off_camber_open_frame-0.2.2}/src/off_camber_open_frame.egg-info/requires.txt

@@ -18,3 +18,7 @@ mcp<2,>=1.0
 [ocr]
 Pillow
 pytesseract
+
+[template]
+Pillow
+numpy

{off_camber_open_frame-0.2.0 → off_camber_open_frame-0.2.2}/src/openframe/act/core.py

@@ -6,6 +6,7 @@ import time
 from collections.abc import Callable
 from typing import Literal
 
+from openframe.cancel import raise_if_tool_cancelled
 from openframe.recognize.coords import target_uses_physical_pixels
 from openframe.types import Frame, Target
 
@@ -29,13 +30,15 @@ class Actuator:
         *,
         anchor: ClickAnchor = "center",
         scale_factor: float = 1.0,
+        origin: tuple[int, int] = (0, 0),
     ) -> tuple[int, int]:
         """Map target bounds to a click point.
 
-        Recognizers report target bounds in captured-image pixels (physical
-        pixels on Retina displays). Mouse actuation works in logical screen
-        points. ``scale_factor`` (display physical/logical ratio, e.g. 2.0 on
-        Retina) converts the mapped point into logical click space.
+        Recognizers report image matches in captured-image pixels. Mouse
+        actuation works in logical screen points. ``scale_factor`` converts
+        those pixels, then ``origin`` (the capture's logical top-left) places
+        the point on the screen. Accessibility targets are already logical
+        screen points, so ``origin`` is not added for them.
         """
         if scale_factor <= 0:
             raise ValueError("scale_factor must be greater than zero.")
@@ -54,7 +57,8 @@ class Actuator:
             raise ValueError(f"Unsupported click anchor: {anchor}")
 
         if target_uses_physical_pixels(target):
-            return (round(px / scale_factor), round(py / scale_factor))
+            origin_x, origin_y = origin
+            return (round(px / scale_factor) + origin_x, round(py / scale_factor) + origin_y)
         return (px, py)
 
     def click_target(
@@ -64,14 +68,18 @@ class Actuator:
         anchor: ClickAnchor = "center",
         kind: ClickKind = "click",
         scale_factor: float = 1.0,
+        origin: tuple[int, int] = (0, 0),
     ) -> tuple[int, int]:
         """Click a target at a mapped point in logical click space."""
-        x, y = self.point_for_target(target, anchor=anchor, scale_factor=scale_factor)
+        x, y = self.point_for_target(
+            target, anchor=anchor, scale_factor=scale_factor, origin=origin
+        )
         self.click_point(x, y, kind=kind)
         return (x, y)
 
     def click_point(self, x: int, y: int, *, kind: ClickKind = "click") -> None:
         """Click at absolute screen coordinates."""
+        raise_if_tool_cancelled()
         if self.dry_run:
             return
 
@@ -89,6 +97,7 @@ class Actuator:
 
     def type_text(self, text: str, *, interval: float = 0.0) -> None:
         """Type plain text at current focus."""
+        raise_if_tool_cancelled()
         if self.dry_run:
             return
         pyautogui = _load_pyautogui()
@@ -96,6 +105,7 @@ class Actuator:
 
     def key_combo(self, *keys: str) -> None:
         """Press a key combination, e.g. ('command', 'v')."""
+        raise_if_tool_cancelled()
         if self.dry_run:
             return
         if not keys:
@@ -105,6 +115,7 @@ class Actuator:
 
     def press_key(self, key: str) -> None:
         """Press a single key."""
+        raise_if_tool_cancelled()
         if self.dry_run:
             return
         if not key:
@@ -113,7 +124,11 @@ class Actuator:
         pyautogui.press(key)
 
     def scroll(self, clicks: int, *, x: int | None = None, y: int | None = None) -> None:
-        """Scroll at a point (or current cursor position)."""
+        """Scroll at a point (or current cursor position).
+
+        Positive ``clicks`` scroll up; negative scroll down (pyautogui convention).
+        """
+        raise_if_tool_cancelled()
         if self.dry_run:
             return
         pyautogui = _load_pyautogui()
@@ -122,6 +137,26 @@ class Actuator:
             return
         pyautogui.scroll(clicks)
 
+    def drag(
+        self,
+        start_x: int,
+        start_y: int,
+        end_x: int,
+        end_y: int,
+        *,
+        duration: float = 0.2,
+        button: Literal["left", "middle", "right"] = "left",
+    ) -> None:
+        """Drag from one screen point to another in logical coordinates."""
+        raise_if_tool_cancelled()
+        if duration < 0:
+            raise ValueError("duration must be >= 0")
+        if self.dry_run:
+            return
+        pyautogui = _load_pyautogui()
+        pyautogui.moveTo(start_x, start_y)
+        pyautogui.dragTo(end_x, end_y, duration=duration, button=button)
+
     def wait_ms(self, milliseconds: int) -> None:
         """Wait for a fixed duration."""
         if milliseconds < 0:

off_camber_open_frame-0.2.2/src/openframe/cancel.py

@@ -0,0 +1,42 @@
+"""Cooperative cancellation for a timed-out MCP tool call.
+
+The MCP adapter binds one :class:`threading.Event` for the worker thread. On
+timeout it sets the event. Actuation and the flow runner check it and refuse
+to start another click, keystroke, scroll, drag, or flow step.
+"""
+
+from __future__ import annotations
+
+import threading
+from contextvars import ContextVar, Token
+
+
+class ToolCancelled(RuntimeError):
+    """The current tool call was cancelled after its wall-clock timeout."""
+
+
+_cancellation: ContextVar[threading.Event | None] = ContextVar(
+    "openframe_tool_cancellation", default=None
+)
+
+
+def bind_tool_cancellation(event: threading.Event) -> Token[threading.Event | None]:
+    """Bind ``event`` for the current thread. Reset with the returned token."""
+    return _cancellation.set(event)
+
+
+def reset_tool_cancellation(token: Token[threading.Event | None]) -> None:
+    """Restore the cancellation state captured by :func:`bind_tool_cancellation`."""
+    _cancellation.reset(token)
+
+
+def tool_cancelled() -> bool:
+    """Return True when the current tool call has been cancelled."""
+    event = _cancellation.get()
+    return event is not None and event.is_set()
+
+
+def raise_if_tool_cancelled() -> None:
+    """Raise when the current tool call has been cancelled."""
+    if tool_cancelled():
+        raise ToolCancelled("Tool call was cancelled after timeout; refusing to actuate.")

{off_camber_open_frame-0.2.0 → off_camber_open_frame-0.2.2}/src/openframe/capture/macos.py

@@ -11,6 +11,7 @@ import tempfile
 from pathlib import Path
 from typing import Any
 
+from openframe.capture.sidecar import write_frame_sidecar
 from openframe.types import Frame
 
 
@@ -18,6 +19,9 @@ class CaptureError(RuntimeError):
     """Raised when a capture operation fails."""
 
 
+_SUBPROCESS_TIMEOUT_SEC = 30
+
+
 def screen(out_path: str | Path | None = None) -> Frame:
     """Capture the primary display to PNG and return frame metadata."""
     _ensure_macos()
@@ -26,7 +30,10 @@ def screen(out_path: str | Path | None = None) -> Frame:
     _run_command(["screencapture", "-x", "-D", "1", str(image_path)])
 
     width, height = _read_png_dimensions(image_path)
-    scale_factor = _detect_scale_factor(width)
+    left, top, logical_width, _logical_height = _main_display_bounds()
+    scale_factor = _scale_from_logical_width(
+        physical_width=width, logical_width=logical_width
+    )
     metadata = {
         "backend": "screencapture",
         "display_index": 1,
@@ -34,14 +41,18 @@ def screen(out_path: str | Path | None = None) -> Frame:
         "physical_height": height,
     }
 
-    return Frame(
+    frame = Frame(
         width=width,
         height=height,
         scale_factor=scale_factor,
         source="screen:1",
         image_path=str(image_path),
         metadata=metadata,
+        origin_x=left,
+        origin_y=top,
     )
+    write_frame_sidecar(frame)
+    return frame
 
 
 def window(
@@ -54,11 +65,22 @@ def window(
     _ensure_macos()
 
     selected = _select_window_info(title=title, window_id=window_id)
+    bounds = selected.get("bounds") if isinstance(selected.get("bounds"), dict) else {}
+    logical_width = int(bounds.get("width") or 0)
+    logical_height = int(bounds.get("height") or 0)
+    if logical_width <= 0 or logical_height <= 0:
+        raise CaptureError("Window bounds are missing, so the capture scale is unknown.")
+    origin_x = int(bounds.get("x") or 0)
+    origin_y = int(bounds.get("y") or 0)
+
     image_path = _resolve_output_path(out_path)
-    _run_command(["screencapture", "-x", "-l", str(selected["id"]), str(image_path)])
+    # -o drops the window shadow so the PNG maps onto the window bounds.
+    _run_command(["screencapture", "-x", "-o", "-l", str(selected["id"]), str(image_path)])
 
     width, height = _read_png_dimensions(image_path)
-    scale_factor = _detect_scale_factor(width)
+    scale_factor = _scale_from_logical_width(
+        physical_width=width, logical_width=logical_width
+    )
     metadata = {
         "backend": "screencapture",
         "window_id": selected["id"],
@@ -66,16 +88,22 @@ def window(
         "window_owner": selected["owner"],
         "physical_width": width,
         "physical_height": height,
+        "logical_width": logical_width,
+        "logical_height": logical_height,
     }
 
-    return Frame(
+    frame = Frame(
         width=width,
         height=height,
         scale_factor=scale_factor,
         source=f"window:{selected['id']}",
         image_path=str(image_path),
         metadata=metadata,
+        origin_x=origin_x,
+        origin_y=origin_y,
     )
+    write_frame_sidecar(frame)
+    return frame
 
 
 def region(
@@ -96,7 +124,7 @@ def region(
     _run_command(["screencapture", "-x", "-R", region_spec, str(image_path)])
 
     physical_width, physical_height = _read_png_dimensions(image_path)
-    scale_factor = _detect_scale_factor(physical_width)
+    scale_factor = _scale_from_logical_width(physical_width=physical_width, logical_width=width)
     metadata = {
         "backend": "screencapture",
         "region": {"x": x, "y": y, "width": width, "height": height},
@@ -104,14 +132,18 @@ def region(
         "physical_height": physical_height,
     }
 
-    return Frame(
+    frame = Frame(
         width=physical_width,
         height=physical_height,
         scale_factor=scale_factor,
         source=f"region:{x},{y},{width},{height}",
         image_path=str(image_path),
         metadata=metadata,
+        origin_x=x,
+        origin_y=y,
     )
+    write_frame_sidecar(frame)
+    return frame
 
 
 def list_windows() -> list[dict[str, Any]]:
@@ -170,7 +202,18 @@ def _resolve_output_path(out_path: str | Path | None) -> Path:
 
 
 def _run_command(command: list[str]) -> subprocess.CompletedProcess[str]:
-    completed = subprocess.run(command, check=False, capture_output=True, text=True)
+    try:
+        completed = subprocess.run(
+            command,
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=_SUBPROCESS_TIMEOUT_SEC,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise CaptureError(
+            f"Capture command timed out after {_SUBPROCESS_TIMEOUT_SEC:g}s: {' '.join(command)}"
+        ) from exc
     if completed.returncode != 0:
         stderr = completed.stderr.strip() or "unknown error"
         raise CaptureError(f"Capture command failed: {' '.join(command)} ({stderr})")
@@ -272,7 +315,8 @@ def _read_png_dimensions(path: Path) -> tuple[int, int]:
     return width, height
 
 
-def _detect_scale_factor(physical_width: int) -> float:
+def _main_display_bounds() -> tuple[int, int, int, int]:
+    """Return the main display as left, top, width, height in logical points."""
     try:
         completed = _run_command(
             [
@@ -281,24 +325,35 @@ def _detect_scale_factor(physical_width: int) -> float:
                 'tell application "Finder" to get bounds of window of desktop',
             ]
         )
-    except CaptureError:
-        return 1.0
+    except CaptureError as exc:
+        raise CaptureError(
+            "Cannot read the main display size, so the capture scale is unknown."
+        ) from exc
 
     values = [segment.strip() for segment in completed.stdout.strip().split(",")]
     if len(values) != 4:
-        return 1.0
+        raise CaptureError("Cannot read the main display size, so the capture scale is unknown.")
 
     try:
-        left, _top, right, _bottom = (int(value) for value in values)
-    except ValueError:
-        return 1.0
+        left, top, right, bottom = (int(value) for value in values)
+    except ValueError as exc:
+        raise CaptureError(
+            "Cannot read the main display size, so the capture scale is unknown."
+        ) from exc
 
     logical_width = right - left
-    if logical_width <= 0:
-        return 1.0
+    logical_height = bottom - top
+    if logical_width <= 0 or logical_height <= 0:
+        raise CaptureError("Cannot read the main display size, so the capture scale is unknown.")
+    return left, top, logical_width, logical_height
+
 
+def _scale_from_logical_width(*, physical_width: int, logical_width: int) -> float:
+    """Return physical pixels per logical point for sizes that are already known."""
+    if physical_width <= 0 or logical_width <= 0:
+        raise CaptureError("Cannot compute scale: width must be positive.")
     ratio = physical_width / logical_width
     for expected in (1.0, 2.0, 3.0):
-        if abs(ratio - expected) < 0.15:
+        if abs(ratio - expected) <= 0.02:
             return expected
     return round(ratio, 2)

off_camber_open_frame-0.2.2/src/openframe/capture/sidecar.py

@@ -0,0 +1,49 @@
+"""Metadata written beside a capture so a later click can map image pixels."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from openframe.types import Frame
+
+SIDECAR_SUFFIX = ".openframe.json"
+
+
+def sidecar_path(image_path: Path) -> Path:
+    """Return the metadata path for a capture PNG."""
+    return Path(str(image_path) + SIDECAR_SUFFIX)
+
+
+def write_frame_sidecar(frame: Frame) -> None:
+    """Write scale and origin next to ``frame.image_path``."""
+    if not frame.image_path:
+        return
+    payload = {
+        "width": frame.width,
+        "height": frame.height,
+        "scale_factor": frame.scale_factor,
+        "origin_x": frame.origin_x,
+        "origin_y": frame.origin_y,
+        "source": frame.source,
+    }
+    path = sidecar_path(Path(frame.image_path))
+    path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+
+def load_frame_sidecar(image_path: Path) -> Frame | None:
+    """Load a frame from its sidecar, or None when the sidecar is absent."""
+    path = sidecar_path(image_path)
+    if not path.is_file():
+        return None
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    return Frame(
+        width=int(payload["width"]),
+        height=int(payload["height"]),
+        scale_factor=float(payload["scale_factor"]),
+        source=str(payload.get("source") or f"file:{image_path.name}"),
+        image_path=str(image_path),
+        origin_x=int(payload.get("origin_x", 0)),
+        origin_y=int(payload.get("origin_y", 0)),
+        metadata={"input": "file", "sidecar": str(path)},
+    )