Requirements

• Node.js 22.13.0 or newer
• Paper Desktop for live Paper mirroring
• A phone and computer on the same trusted local network

The server and local-file mode support macOS, Linux/Unix, and Windows. Live Paper mode also requires a Paper Desktop release that exposes its local MCP endpoint on the host platform.

Smooth shader playback uses the structured get_children and get_jsx tools available in Paper Desktop MCP 0.5.3. Older MCP versions and shader layer arrangements that cannot be composed safely continue to use native screenshots. Topmost shaders render directly; bottommost shaders can preserve up to eight foreground layers through bounded transparent captures.

Quick start

Install Paper Mirror:

npm i -g @adrianmg/paper-mirror

Open your mobile design in Paper, select the frame you want to preview, and run:

paper-mirror

Scan the QR code with your phone to open the preview.

Paper Mirror follows the active Paper tab without adding another steady-state polling loop. File and selection checks alternate within one adaptive metadata budget, and renders remain scoped to the detected file.

For a full-screen app experience, add the preview to your Home Screen:

• iPhone or iPad: In Safari, choose Share > Add to Home Screen, enable Open as Web App, and tap Add.
• Android: Open the browser menu and choose Install app or Add to Home screen.

To run Paper Mirror without installing it globally:

npx @adrianmg/paper-mirror@latest

To mirror a local image instead:

paper-mirror --source ./frame.png

Run paper-mirror --help for all options.

Troubleshooting

The Home Screen app says "Not Found"

Your Home Screen icon saves the exact pairing URL. That URL can stop working after:

• moving to a different computer;
• changing the computer's hostname;
• switching networks when the URL uses an IP address instead of a .local hostname;
• running paper-mirror --rotate-token or resetting Paper Mirror's settings;
• changing --port or --public-host.

Start Paper Mirror, scan the current QR code, and confirm the preview opens in the browser. Then remove the old Home Screen icon and add the new page again.

On the same Mac, the default .local URL should usually survive ordinary Wi-Fi changes. Paper Mirror cannot connect when the phone and computer are on different networks.

The phone cannot connect

• Confirm Paper Mirror is still running and both devices are on the same trusted local network.
• Avoid guest, hotel, or corporate Wi-Fi that blocks communication between devices.
• Temporarily disconnect VPNs and allow Node.js through the computer's firewall.
• If the QR code uses the wrong network address, provide the computer's local IP:

paper-mirror --public-host 192.168.1.42

Paper or its frames are not found

Open Paper Desktop with a design file open. Select one frame or artboard, or create one if the document is empty. Live mirroring also requires a Paper Desktop version that exposes its local MCP endpoint.

If updates stop after switching apps, bring the preview back to the foreground. iOS may suspend Home Screen apps and browser tabs in the background.

Port 4173 is already in use

Stop the previous Paper Mirror process, or choose another port:

paper-mirror --port 4174

A different port creates a different pairing URL, so scan the new QR code and replace any existing Home Screen icon.

"Install app" is not available

On iPhone and iPad, installation is always manual through Safari's Share > Add to Home Screen action. On Android, local HTTP pages may show Add to Home screen instead of Install app; either option creates a shortcut to the preview.

Security and privacy

Paper Mirror binds to the local network by default so a phone can connect. A random pairing token protects viewer, frame, manifest, and WebSocket routes. Frames remain in memory and are not uploaded by Paper Mirror.

Paper Mirror sends anonymous product-usage events to Umami Cloud after a successful launch. They contain app and Paper versions, coarse host and viewer platforms, browser family, browser/PWA mode, source and output types, and bucketed frame count, orientation, rendered area, payload size, render latency, updates, duration, time to the first viewer, and connected-device count. Navigation is recorded as a boolean. HD state is summarized, while Cover/1:1 and dark/light canvas values are recorded only after those controls are changed. These become coarse values such as both, never click histories. Startup data is sent after launch, viewer context is sent once per connected page for each companion run, and usage summaries are aggregated in memory and sent every 15 minutes and on clean shutdown.

Analytics never include designs, names, paths, actual URLs, pairing tokens, raw user agents, exact dimensions, or persistent identifiers. Umami receives ordinary network metadata for each request. Disable analytics with:

paper-mirror --no-telemetry

Paper Mirror also respects DO_NOT_TRACK=1.

Treat the QR code and pairing URL as credentials. Use --rotate-token to revoke an existing URL, and never expose the server port to the public internet. Use --host 127.0.0.1 when LAN access is not needed.

The token is stored under XDG_CONFIG_HOME when configured, under APPDATA on Windows, and otherwise under ~/.paper-mirror.

License

MIT (c) 2026 Adrian Mato Gondelle. Paper Mirror is an independent project and is not affiliated with or endorsed by Paper.