paper-snapshot-cli 0.1.0

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "paper-snapshot-cli",
+  "version": "0.1.0",
+  "description": "Paper Snapshot as a CLI. Copy and paste your real site directly into Paper as editable layers. No more screenshots.",
+  "keywords": [
+    "ai-agents",
+    "claude-code",
+    "cli",
+    "coding-agents",
+    "design-tools",
+    "effect",
+    "paper",
+    "paper-design",
+    "paper-snapshot",
+    "snapshot"
+  ],
+  "homepage": "https://github.com/jeremyosih/paper-snapshot#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jeremyosih/paper-snapshot.git"
+  },
+  "bin": {
+    "paper-snapshot": "dist/bin.mjs"
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "bun src/bin.ts",
+    "check": "vp check && bun run typecheck && bun run knip",
+    "lint": "vp lint --report-unused-disable-directives",
+    "format": "vp fmt",
+    "fmt:check": "vp fmt --check",
+    "typecheck": "tsc --noEmit",
+    "knip": "knip",
+    "staged": "vp staged",
+    "hooks:setup": "vp config",
+    "setup": "effect-tsgo patch"
+  },
+  "dependencies": {
+    "playwright-core": "1.64.1"
+  },
+  "devDependencies": {
+    "@effect/platform-node": "4.0.6",
+    "@effect/tsgo": "0.57.0",
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "@oxlint/plugins": "1.82.0",
+    "@types/node": "^26.2.0",
+    "effect": "4.0.6",
+    "fflate": "0.8.2",
+    "knip": "6.34.0",
+    "oxlint": "1.82.0",
+    "typescript": "7.0.2",
+    "vite-plus": "0.3.1"
+  },
+  "overrides": {
+    "@effect/platform-node-shared": "4.0.6",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.1"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "bun@1.4.2"
+}

package/skills/paper-snapshot/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: paper-snapshot
+description: Snapshot web UI into Paper as editable layers. Use when a URL, local dev server, set of app screens, or live browser state should land in a Paper file, or when Paper artboards need refreshing from the app.
+---
+
+# paper-snapshot
+
+`paper-snapshot` serializes pages with Paper Snapshot's own serializer and writes each as an artboard into the file open in the Paper app. Every behaviour is a flag; `paper-snapshot --help` is the reference.
+
+## Steps
+
+1. **Pick the source.**
+   - URLs, public or localhost: `paper-snapshot <url> [<url or /path>…]`. It launches the installed Chrome headlessly.
+   - A state that takes interaction to reach and that page-state flags (step 2) cannot set up: get a browser there, then capture its tab without a URL.
+     - agent-browser: `paper-snapshot` (captures the tab agent-browser is on).
+     - The user's everyday Chrome, also what Chrome DevTools MCP drives with `--autoConnect`: `paper-snapshot --source chrome --tab <text in the tab's URL or title>`. The user must approve it in Chrome; see **Human checkpoints**.
+     - Playwriter: `--source playwriter --tab <text>`. Any other CDP browser: `--cdp <endpoint>`.
+
+2. **Set up the state.** Sign-in: `--storage-state auth.json`, or `--cookie "name=value"`. Theme and flags that apps keep in storage: `--local-storage key=value` (`--color-scheme dark` alone only flips the media query). Menus and dialogs: `--click <selector>`, repeatable, in order. `--eval` covers anything else.
+
+3. **Scope it.** `-s <css>` captures one element; the default is the whole page. Internal scroll containers (`h-screen` shells) are unclipped automatically. Match the device with `--width`/`--height`.
+
+4. **Place it.** One screen: optional `--name`, `--page-id`, `--x/--y`, `--below <artboardId>` or `--right-of <artboardId>`. Several screens: pass several URLs, or a `--manifest` JSON file whose items set per-screen fields (`name`, `colorScheme`, `localStorage`, `x`, `below`, `replace`, …). They share one browser and one Paper connection and are arranged by `--layout row|column|grid`. Refreshing a screen after the app changed: `--replace <artboardId>`, which keeps the artboard's id, position and name.
+
+5. **Run with `--json`.** Stdout carries one JSON line per artboard: `artboardId`, `fileId`, `x`, `y`, `width`, `height`, and `warnings`. A failed capture prints `{"index", "url", "error"}`, the batch continues, and the exit code is 1.
+
+6. **Verify.** Read each line's `warnings`; any non-zero count names what imported badly (`emptySvgs`, `unresolvedSprites`, `clippedScrollContainers`, `unresolvedImages`, `lostColspans`). Screenshot flagged artboards with the Paper MCP `get_screenshot`. Done when every artboard shows the intended state with zero warnings, or the remaining ones are explained.
+
+## Human checkpoints
+
+Tell the user before running a command that waits on them, and name what they will see.
+
+- **Chrome "Allow remote debugging?" dialog** (`--source chrome`, and auto without a URL when agent-browser is absent). One-time setup: the user turns on remote debugging at `chrome://inspect/#remote-debugging`; Chrome then shows "Server running at 127.0.0.1:9222". Every run opens a fresh connection, so Chrome shows "Allow remote debugging?" each time, on the machine where Chrome runs. The command blocks until the user clicks **Allow**, for up to `--chrome-approval-timeout` (2 min). **Cancel** fails the run. While attached, Chrome shows a "controlled by automated test software" banner. A batch asks once. On a remote machine, the person at that screen has to click.
+- **Paper app.** It must be running with a file open, or pass `--file-id`. Pushing needs no approval.
+- **agent-browser / Playwriter.** No prompt, but an agent-browser session must be open (`agent-browser open <url>`), or Playwriter's extension must be connected to its relay.
+- **First run.** paper-snapshot downloads the Paper Snapshot extension once (network required). Without an installed Chrome, Edge, Brave or Chromium it also downloads headless Chromium once.
+
+## Gotchas
+
+- When `paper-snapshot` isn't on PATH, run it as `npx -y paper-snapshot-cli …` with the same arguments.
+
+- The Paper app must be running: the push goes through its MCP relay at `~/.paper/bin/paper`. `--file-id` and `--page-id` target a specific file and page.
+- Snapshots run to several MB. Let paper-snapshot carry the HTML; `--out` writes it to disk (a directory for several captures).
+- Images on localhost and private hosts are inlined automatically because Paper cannot reach them. Use `--inline-images always` for assets behind auth.
+- Sections that animate in on scroll can come out blank: give them time with `--settle 2000`, or force the final state with `--eval`.
+- Attached browsers stay open. Passing a URL while attached opens a temporary tab and closes it afterwards.
+- `--quiet` keeps stderr to warnings and errors across long batches.