screengraft 0.13.1

package/LICENSE

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

package/README.md

@@ -0,0 +1,127 @@
+# screengraft
+
+**Put a UI screenshot onto a photographed screen so the perspective is exactly right.**
+
+![A Figma screen composited onto a photographed iPhone](docs/hero.png)
+
+![The fitting workbench: photo with the screen quad on the left, live composite on the right, and a magnified strip across the edge below](docs/social-preview.png)
+
+Every device mockup is a compromise. Templates give you three angles and someone
+else's lighting. Generative tools give you a screen that looks *like* your design
+without being it — text reflowed, a button moved, a logo subtly wrong.
+
+screengraft takes your photograph and your screenshot and computes the projective
+transform between them. The screenshot lands on the glass because the geometry
+says it must, not because a model thought it looked about right. Same inputs,
+same output, every time.
+
+---
+
+## What it does
+
+- **Any angle.** A homography handles arbitrary perspective — a phone leaning on
+  a wall, a laptop half-turned, a tablet held at 40°.
+- **Your pixels, unaltered.** The screenshot is resampled once and warped once.
+  9px legal copy stays legible.
+- **Rounded corners that actually follow the bezel**, measured from the photo or
+  taken from a device preset.
+- **Realism pass** *(optional)* — matches the screen's white balance and grain to
+  the light in the room, and can lift the device's real reflections from a
+  screen-off frame of the same shot.
+- **You confirm every fit.** Detection is advisory and says so; you drag the four
+  edges onto the glass with a magnified loupe. A silent misdetection producing a
+  confident, wrong result is the one failure this tool refuses to have.
+
+## Requirements
+
+`python3` with **OpenCV** and **numpy**. OpenCV is the engine — nothing runs
+without it. The installer provisions an isolated venv at `~/.screengraft/venv`
+and never touches your system Python.
+
+## Install as a Claude Code / Cowork plugin
+
+```
+/plugin marketplace add seq000/screengraft
+/plugin install screengraft@fraczyk-tools
+```
+
+That route tracks versions and updates itself. If you would rather not add a
+marketplace, download `screengraft-<version>.plugin` from
+[the latest release](https://github.com/seq000/screengraft/releases/latest) and
+open it, or clone this repo and point Claude Code at the folder.
+
+Then ask Claude to inject a screenshot onto a photo. It opens a local page in
+your browser, you fit the edges, press Save, and the composite lands in your
+project folder. Nothing is uploaded anywhere; the page is served from
+`127.0.0.1`.
+
+## Or use it without Claude
+
+```bash
+npx screengraft --out-dir ./mockups
+```
+
+npm is a delivery mechanism here, not a claim about the language: the tool is
+Python and OpenCV, and `bin/screengraft.js` is a launcher. It installs nothing
+behind your back — if the engine is missing it prints the one command that
+builds it (`npx screengraft --install`) and exits.
+
+From a clone:
+
+```bash
+python3 scripts/preflight.py --install        # one-time: creates the venv
+python3 scripts/ui.py --out-dir ./mockups     # opens the fitting page
+```
+
+Headless, if you already know the corners:
+
+```bash
+python3 scripts/warp.py --photo shot.jpg --screenshot ui.png \
+  --corners "945,504 1310,475 1501,1408 1135,1459" \
+  --radius-frac 0.14 --out composite.png
+```
+
+Corners are `TL TR BR BL` in photo pixels.
+
+## Why not just use AI
+
+A diffusion model cannot guarantee the screenshot lands on the screen's four
+corners, because nothing in it is solving for that. A projective transform can,
+by construction — it is the same maths a document scanner uses to flatten a page.
+So the pipeline is computer vision and projective geometry end to end, and it is
+deterministic: re-run it and you get a byte-identical file.
+
+Generative AI has exactly one optional job in the design, and it is strictly
+outside the screen mask. It never touches the pixels you designed.
+
+## How it works
+
+1. **Corner acquisition** — an advisory detector proposes a quad; you correct it
+   by dragging *edges* (a rounded corner has no point to aim at; the straight
+   edges either side are unambiguous), with a rectified strip loupe at ~5×.
+2. **Warp** — the screenshot is area-averaged down to its destination footprint,
+   then warped once at the photo's resolution. Prefiltering matters: OpenCV's
+   warp never area-averages, so warping a 1206×2622 screenshot into a 226×454
+   quad without it turns body text into noise.
+3. **Realism pass** *(optional)* — white balance and exposure toward the
+   surrounding light, grain matched to the photo's own noise floor, real
+   speculars lifted from a screen-off reference.
+
+## Roadmap
+
+Done: manual warp, advisory detectors, the fitting workbench, the realism pass.
+
+Open: video tracking (M3), SAM 2 auto-detect (M4 — built and measured in a
+separate repo; it currently segments the phone body rather than the glass, so it
+is not shipped), occluder matte (M5), so a finger in front of the screen stays in
+front.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). The short version: there are tests, they
+run in CI, and a change to the compositing engine needs a measurement, not an
+opinion.
+
+## Licence
+
+MIT. The bundled Mona Sans subset is SIL OFL — see `ui/fonts/OFL.txt`.

package/bin/screengraft.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/*
+ * screengraft — launcher.
+ *
+ * This package is a delivery mechanism, not a JavaScript library. The tool is
+ * Python and OpenCV; npm is here because `npx screengraft` is the shortest path
+ * from "I have a photo" to a fitting page, with nothing installed permanently.
+ * It says so out loud rather than pretending otherwise, and it never installs
+ * anything behind your back: if the Python side is missing you get the exact
+ * command to run, and a non-zero exit.
+ */
+'use strict';
+
+const { spawn, spawnSync } = require('node:child_process');
+const path = require('node:path');
+const process = require('node:process');
+
+const ROOT = path.join(__dirname, '..');
+const PREFLIGHT = path.join(ROOT, 'scripts', 'preflight.py');
+const UI = path.join(ROOT, 'scripts', 'ui.py');
+
+const argv = process.argv.slice(2);
+if (argv.includes('-h') || argv.includes('--help')) {
+  process.stdout.write(
+    'screengraft — put a UI screenshot onto a photographed device screen.\n\n' +
+    'Usage:  npx screengraft [--out-dir DIR] [--port N] [--no-open]\n\n' +
+    '  --out-dir DIR   where Save writes (default ~/Desktop/screengraft)\n' +
+    '  --port N        0 picks a free port (default)\n' +
+    '  --no-open       do not open a browser tab\n' +
+    '  --install       build the Python venv this needs, then exit\n\n' +
+    'Needs python3 with OpenCV and numpy. The first run offers to build an\n' +
+    'isolated venv at ~/.screengraft/venv (~60 MB); your system Python is left\n' +
+    'alone. Docs: https://github.com/seq000/screengraft\n');
+  process.exit(0);
+}
+
+function python() {
+  for (const exe of ['python3', 'python']) {
+    const r = spawnSync(exe, ['--version'], { stdio: 'ignore' });
+    if (!r.error && r.status === 0) return exe;
+  }
+  return null;
+}
+
+const py = python();
+if (!py) {
+  process.stderr.write(
+    'screengraft needs python3, and none was found on PATH.\n' +
+    'Install Python 3.10 or newer, then run this again.\n');
+  process.exit(1);
+}
+
+if (argv.includes('--install')) {
+  process.exit(spawnSync(py, [PREFLIGHT, '--install'], { stdio: 'inherit' }).status ?? 1);
+}
+
+// Preflight reports which interpreter actually has OpenCV — the venv's, usually,
+// not the one running this check.
+const pre = spawnSync(py, [PREFLIGHT], { encoding: 'utf8' });
+let report;
+try {
+  report = JSON.parse(pre.stdout);
+} catch {
+  process.stderr.write('screengraft: preflight did not report cleanly.\n' + (pre.stderr || pre.stdout || ''));
+  process.exit(1);
+}
+
+if (!report.ready) {
+  process.stderr.write(
+    'screengraft needs OpenCV, and it is not installed.\n\n' +
+    'OpenCV is the engine here, not an enhancement: without it there is no\n' +
+    'degraded mode, there is no mode. Missing: ' + (report.missing || []).join(', ') + '\n\n' +
+    'To build an isolated venv at ~/.screengraft/venv (about 60 MB, and it\n' +
+    'touches nothing else on your machine):\n\n' +
+    '    npx screengraft --install\n\n');
+  process.exit(1);
+}
+
+// report.python is the interpreter that has the engine.
+const child = spawn(report.python, [UI, ...argv], { stdio: 'inherit' });
+child.on('exit', (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+for (const sig of ['SIGINT', 'SIGTERM']) process.on(sig, () => child.kill(sig));

package/mcp/server.py

@@ -0,0 +1,322 @@
+#!/usr/bin/env python3
+"""screengraft MCP server — lets the browser UI reach the agent.
+
+WHY THIS EXISTS
+---------------
+The UI is a local web page. When the designer pastes a Figma link or presses
+"Import to Claude", something has to happen *in the agent*. The agent cannot
+poll: it runs in turns, and between turns nothing of it is executing. The old
+SKILL.md told it to "poll job.json every few seconds", which was never
+achievable, and the page told the user "(it watches this job)", which was
+false. The user sat waiting for an agent that was not running.
+
+The fix is to invert it. The agent cannot poll, but it CAN block: a tool call
+may take as long as the host allows (measured 4 Sep 2026: 94s returns cleanly;
+the bash cap on the same host is 600s). So the page gets an outbox and the
+agent gets a blocking inbox. `wait_for_job` parks until the user presses a
+button and returns within ~150ms of the press.
+
+DESIGN CONSTRAINTS
+------------------
+1. **Stdlib only, system python3.** A plugin's MCP server starts when the
+   plugin is enabled — which is before preflight has necessarily built
+   ~/.screengraft/venv. Importing cv2, numpy or the `mcp` package here would
+   make the server fail to load on a fresh install, and the tools would simply
+   be missing with no good error. So: no third-party imports in this file.
+2. **Threaded dispatch.** Blocking inside the stdin read loop would stall the
+   host's own traffic (ping, tools/list) for the length of the wait, and a host
+   that gets no reply may treat the server as dead. Each request is handled on
+   its own thread; stdout writes are serialised by a lock.
+3. **No state of its own.** The session dir on disk is the only truth. The
+   server can be restarted mid-job and lose nothing.
+"""
+
+import json
+import os
+import sys
+import threading
+import time
+
+HOME = os.path.expanduser("~")
+ROOT = os.path.join(HOME, ".screengraft")
+CURRENT = os.path.join(ROOT, "current.json")
+
+POLL_S = 0.15          # how often the wait loop looks at the outbox
+DEFAULT_TIMEOUT = 90   # measured safe; also bounds how long a chat message waits
+# The host kills an MCP tool call well before the shell tool's own cap. Measured
+# 4 Sep 2026: a bash call blocked 94s cleanly and the bash cap is 600s, so 300
+# looked safe here -- but a real wait_for_job(300) was killed by the host at
+# exactly 180s. The orphaned call loses no data (an unanswered job stays pending
+# and the next wait picks it up) but the agent misses the wake it was parked
+# for, which is the one thing this server exists to deliver. So: stay clearly
+# under the observed ceiling rather than at it, and clamp rather than trust the
+# caller, because the caller is an agent reading a description.
+HOST_CALL_CEILING = 180
+MAX_TIMEOUT = 150
+
+_out_lock = threading.Lock()
+
+
+# ---------------------------------------------------------------- transport
+
+def _send(msg):
+    """One JSON-RPC message per line on stdout, serialised across threads."""
+    with _out_lock:
+        sys.stdout.write(json.dumps(msg) + "\n")
+        sys.stdout.flush()
+
+
+def _result(req_id, payload):
+    _send({"jsonrpc": "2.0", "id": req_id, "result": payload})
+
+
+def _error(req_id, code, message):
+    _send({"jsonrpc": "2.0", "id": req_id, "error": {"code": code, "message": message}})
+
+
+def _text(payload):
+    """MCP tool results are content blocks; we always return one JSON block."""
+    return {"content": [{"type": "text", "text": json.dumps(payload, indent=1)}]}
+
+
+# ------------------------------------------------------------------ session
+
+def _read_json(path):
+    """Tolerant read: a torn file is treated as absent, not as an error.
+
+    ui.py writes atomically (tmp + os.replace) so this shouldn't happen, but a
+    half-read here would surface as a crashed tool call rather than a retry,
+    and the retry is free — we're in a poll loop.
+    """
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except (OSError, ValueError):
+        return None
+
+
+def _pid_alive(pid):
+    try:
+        os.kill(int(pid), 0)
+    except (OSError, TypeError, ValueError):
+        return False
+    return True
+
+
+def current_session():
+    """The UI instance the agent should be talking to, or None.
+
+    A pointer file left behind by a crashed UI is worse than no pointer: the
+    agent would wait out a full timeout against a session nobody is looking at.
+    So the pid is checked on every read and a dead pointer is reported as gone.
+    """
+    cur = _read_json(CURRENT)
+    if not cur:
+        return None
+    if not _pid_alive(cur.get("pid")):
+        return None
+    if not os.path.isdir(cur.get("session") or ""):
+        return None
+    return cur
+
+
+# -------------------------------------------------------------------- tools
+
+TOOLS = [
+    {
+        "name": "wait_for_job",
+        "description": (
+            "Block until the screengraft UI asks the agent to do something, then return "
+            "that request. Call this immediately after launching the UI and again after "
+            "each completed job, so a button press is picked up without the user having "
+            "to type anything in chat.\n\n"
+            "Returns one of:\n"
+            "  status=job        — a request to handle. `job.type` is 'figma_export' "
+            "(export job.url via the Figma MCP at 3x PNG, save to job.save_to, then call "
+            "complete_job) or 'present' (show job.paths to the user with present_files, "
+            "then call complete_job).\n"
+            "  status=timeout    — nothing happened within timeout_s. The UI is still up; "
+            "call again to keep waiting.\n"
+            "  status=ui_closed  — the UI exited. Stop waiting and tell the user.\n"
+            "  status=no_ui      — no UI is running. Launch it first.\n\n"
+            "Blocking is the point: the agent cannot poll between turns, so this call is "
+            "how a local web page reaches it."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "timeout_s": {
+                    "type": "number",
+                    "description": f"Seconds to block before returning status=timeout "
+                                   f"(default {DEFAULT_TIMEOUT}, max {MAX_TIMEOUT} \u2014 the host kills a tool call at "
+                                   f"~{HOST_CALL_CEILING}s, so anything larger is clamped). Shorter "
+                                   f"timeouts return control sooner so the user's own chat "
+                                   f"messages are not delayed behind the wait.",
+                }
+            },
+        },
+    },
+    {
+        "name": "complete_job",
+        "description": (
+            "Report the outcome of the job most recently returned by wait_for_job. The page "
+            "is polling for this and will not move on until it arrives — always call it, "
+            "including on failure, or the user is left watching a spinner."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "status": {"type": "string", "enum": ["done", "error"]},
+                "path": {"type": "string", "description": "For figma_export: the saved PNG."},
+                "message": {"type": "string", "description": "For status=error: what went wrong, in a sentence the designer can act on."},
+                "job_id": {"type": "string",
+                           "description": "The `id` from the job wait_for_job returned. Pass it: it "
+                                          "stops a late completion from landing on a different job "
+                                          "the user has since started."},
+            },
+            "required": ["status"],
+        },
+    },
+]
+
+
+def tool_wait_for_job(args):
+    timeout = args.get("timeout_s")
+    try:
+        timeout = float(timeout) if timeout is not None else DEFAULT_TIMEOUT
+    except (TypeError, ValueError):
+        timeout = DEFAULT_TIMEOUT
+    timeout = max(1.0, min(timeout, MAX_TIMEOUT))
+
+    cur = current_session()
+    if not cur:
+        return {"status": "no_ui",
+                "hint": "No screengraft UI is running. Launch it with scripts/launch.sh."}
+
+    job_path = os.path.join(cur["session"], "job.json")
+    deadline = time.time() + timeout
+    while True:
+        job = _read_json(job_path)
+        if job and job.get("status") == "pending":
+            return {"status": "job", "job": job, "session": cur["session"],
+                    "out_dir": cur.get("out_dir")}
+        if not current_session():
+            return {"status": "ui_closed",
+                    "hint": "The UI exited. Anything not yet saved is gone; say so rather than waiting."}
+        if time.time() >= deadline:
+            return {"status": "timeout", "waited_s": round(timeout, 1),
+                    "hint": "Still up, nothing pressed. Call wait_for_job again to keep waiting."}
+        time.sleep(POLL_S)
+
+
+def tool_complete_job(args):
+    cur = current_session()
+    if not cur:
+        return {"ok": False, "error": "no UI running"}
+    job_path = os.path.join(cur["session"], "job.json")
+    job = _read_json(job_path)
+    if not job:
+        return {"ok": False, "error": "no job to complete"}
+
+    status = args.get("status")
+    if status not in ("done", "error"):
+        return {"ok": False, "error": "status must be 'done' or 'error'"}
+
+    # Guard against completing something other than what was handed out. The
+    # page refuses to enqueue over a pending job, so this only bites when the
+    # agent is slow and the user has reloaded and started again — but silently
+    # marking the new job done would leave them waiting on a spinner forever.
+    want = args.get("job_id")
+    if want and str(job.get("id")) != str(want):
+        return {"ok": False,
+                "error": f"job {want} is no longer current (the session is on {job.get('id')}). "
+                         f"The user has started something else; do not complete this one."}
+    if job.get("status") != "pending":
+        return {"ok": False,
+                "error": f"this job is already {job.get('status')}, nothing to complete"}
+
+    job["status"] = status
+    job["completed"] = time.time()
+    if status == "done":
+        path = args.get("path")
+        # figma_export is the only job whose completion carries a file; for a
+        # 'present' job there is nothing to hand back and path is meaningless.
+        if job.get("type") == "figma_export":
+            if not path or not os.path.isfile(path):
+                return {"ok": False,
+                        "error": f"figma_export needs `path` to be a file that exists (got {path!r})"}
+            job["path"] = path
+    else:
+        job["message"] = args.get("message") or "The agent could not complete this."
+
+    tmp = job_path + ".tmp"
+    with open(tmp, "w") as f:
+        json.dump(job, f, indent=1)
+    os.replace(tmp, job_path)
+    return {"ok": True, "status": status}
+
+
+DISPATCH = {"wait_for_job": tool_wait_for_job, "complete_job": tool_complete_job}
+
+
+# ----------------------------------------------------------------- protocol
+
+def handle(req):
+    method = req.get("method")
+    req_id = req.get("id")
+
+    # Notifications carry no id and must never be answered.
+    if req_id is None:
+        return
+
+    if method == "initialize":
+        params = req.get("params") or {}
+        # Echo the client's protocol version rather than pinning one: this
+        # server uses nothing version-specific, and echoing avoids a mismatch
+        # rejection when the host moves forward.
+        version = (params.get("protocolVersion")
+                   if isinstance(params.get("protocolVersion"), str) else "2025-06-18")
+        return _result(req_id, {
+            "protocolVersion": version,
+            "capabilities": {"tools": {}},
+            "serverInfo": {"name": "screengraft", "version": "0.7.0"},
+        })
+
+    if method == "ping":
+        return _result(req_id, {})
+
+    if method == "tools/list":
+        return _result(req_id, {"tools": TOOLS})
+
+    if method == "tools/call":
+        params = req.get("params") or {}
+        name = params.get("name")
+        fn = DISPATCH.get(name)
+        if not fn:
+            return _error(req_id, -32602, f"unknown tool: {name}")
+        try:
+            return _result(req_id, _text(fn(params.get("arguments") or {})))
+        except Exception as e:                                    # noqa: BLE001
+            # A tool that raises should report a failed tool call, not kill the
+            # server — the UI may still be mid-job.
+            return _result(req_id, {**_text({"error": str(e)}), "isError": True})
+
+    return _error(req_id, -32601, f"method not found: {method}")
+
+
+def main():
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            req = json.loads(line)
+        except ValueError:
+            continue
+        # One thread per request so a 90s wait_for_job cannot stall ping or
+        # tools/list behind it.
+        threading.Thread(target=handle, args=(req,), daemon=True).start()
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "screengraft",
+  "version": "0.13.1",
+  "description": "Put a UI screenshot onto a photographed device screen with the perspective exactly right \u2014 a homography you confirm by hand, not a generative guess.",
+  "keywords": [
+    "mockup",
+    "device-frame",
+    "homography",
+    "perspective",
+    "compositing",
+    "screenshot",
+    "design",
+    "portfolio",
+    "figma"
+  ],
+  "homepage": "https://github.com/seq000/screengraft#readme",
+  "bugs": "https://github.com/seq000/screengraft/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/seq000/screengraft.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Dariusz Fraczyk",
+    "url": "https://fraczyk.design"
+  },
+  "type": "commonjs",
+  "bin": {
+    "screengraft": "bin/screengraft.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "ui/",
+    "mcp/",
+    "skills/",
+    "README.md",
+    "LICENSE",
+    "!scripts/build-plugin.sh",
+    "!scripts/deadcode.py",
+    "!scripts/check_leaks.py",
+    "!scripts/check_marketplace.py",
+    "!scripts/check_package.py",
+    "!scripts/leak-patterns.local",
+    "!scripts/contrast_audit.py",
+    "!**/__pycache__/**",
+    "!**/*.pyc"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "scripts": {
+    "start": "node bin/screengraft.js"
+  }
+}