# Mirrorframe

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-byte271-mirrorframe-mirrorframe`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [byte271](https://agentstack.voostack.com/s/byte271)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [byte271](https://github.com/byte271)
- **Source:** https://github.com/byte271/mirrorframe

## Install

```sh
agentstack add skill-byte271-mirrorframe-mirrorframe
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Mirrorframe — capture → genome → reconstruct → converge

Deterministic pipeline (no LLM in the loop). Everything runs from this skill directory
with Node.js ≥ 18.

## Setup (once per machine)

```bash
cd 
npm install     # postinstall downloads the Playwright Chromium binary
```

If `playwright install chromium` did not run (offline installs), run it manually.

## Run the whole pipeline (the normal path)

One command runs all four stages and prints the verification report:

```bash
node scripts/mirrorframe.js run --dir /path/to/page-directory --out ./mf-out/name
# or, for a live URL you have rights to:
node scripts/mirrorframe.js run --url https://example.com --out ./mf-out/name
# optional viewport: --width 1280 --height 800   (defaults shown)
```

- `--dir` expects a directory containing an `index.html`; it is served over a local
  ephemeral HTTP server automatically.
- Only run against pages the user owns or that are permissively licensed
  (see `references/limitations.md`, "Legal / provenance").

The stages, in order (all automatic within `run`):

1. **Capture** → `/capture.json`. Headless Chromium walks the DOM recording
   computed styles per node, keyframe animations, transitions, hover rules; a scroll
   probe detects scroll-reveal state machines; a synthetic click probe discovers
   click-driven state machines (accordion/tabs/modal) and screenshots each recovered
   state as ground truth (`state-*.png`). Assets (images, background-images, web
   fonts, video sources/posters) are downloaded and bundled locally; canvases are
   snapshotted as stills; a frame sampler records rAF-driven motion at every
   animation frame for a bounded window (v0.2). Reveal mutations are timestamped
   for sequential-stagger recovery, and a virtual-mouse agent grid-samples the
   pointer to recover mouse-movement choreography (parallax/tilt/magnetic) plus
   each node's smoothing time constant, with ground-truth pointer checkpoints
   (`original-pointer-*.png`) (v0.3).
2. **Genome** → `/genome.json`. Clusters tokens (color/type/spacing/radius/shadow),
   compiles motion DNA (animations/transitions) and interaction DNA (`interaction.
   behaviors[]` — recovered state machines typed `reveal`/`toggle`/`exclusive`/`pair`;
   see `references/behavior-patterns.md` for what each type means).
3. **Reconstruct** → `/recon-app/`. Generates a self-contained React app
   (`app.jsx`, `styles.css`, `bundle.js`, `index.html`) with the recovered state
   machines re-wired as real listeners/observers. Open `recon-app/index.html` directly
   in a browser to inspect it.
4. **Converge** → `/convergence.json` + `/summary.json`. Re-renders the
   reconstruction at the identical viewport and verifies it (see next section).

After "Done.", the CLI prints the contents of `summary.json` as JSON — it is the same
data as the file, not an additional artifact.

## How to read the verification result

The CLI prints, and `convergence.json` contains, three levels — always read the
per-node level first; never report only the aggregate:

- **Per node** (`nodes[]`): each tracked node gets `similarity` (0–1) and a `status`:
  - `pass` — pixel similarity ≥ 0.98 for that node's region.
  - `style-verified` — pixel residual, but every tracked computed style matches
    exactly (sub-pixel text anti-aliasing on tiny nodes). Treat as OK.
  - `corrected` — node initially failed; a per-node CSS patch was auto-applied and it
    passed re-verification. The patch is appended to `recon-app/styles.css`.
  - `failed` — node still fails after one correction attempt. This is a real fidelity
    failure; report it explicitly with its similarity, never average it away.
  - `animated-unstable` — node has an infinite animation; pixels depend on screenshot
    phase, so it is excluded from pass/fail. Expected, not a failure.
  - `time-varying-replicated` (v0.2) — bundled video/canvas or frame-sampled motion:
    the mechanism IS reproduced in the reconstruction, but the pixels depend on the
    playback instant, so the region is masked (reason `time-varying-media`).
    Expected, not a failure.
  - `hidden-at-capture` — node starts hidden (closed accordion/modal, inactive tab
    panel); verified via state replay instead. Expected, not a failure. Its
    `similarity` is `null` because no initial-screenshot pixels exist to compare.
  - `skipped` — node is out of scope, carrying one reason from the fixed taxonomy in
    `scripts/lib/reasons.js` (e.g. `cross-origin-content` for inaccessible iframes,
    `unclassified-behavior` for timer-driven mutations like autoplay carousels,
    `probe-error` for a candidate whose synthetic probe threw in page script).
    Its region is masked from the pixel diff and its layout footprint is preserved
    by a placeholder. Expected on real pages; report the reasons, never hide them.
- **Per interaction state** (`states[]`): each recovered behavior state is replayed on
  the reconstruction with a real click and diffed against the original's ground-truth
  state screenshot; pass threshold 0.98. A state `fail` means the recovered behavior
  does not visually reproduce — report it.
- **Per pointer state** (`pointerStates[]`, v0.3): each recovered pointer checkpoint is
  replayed on the reconstruction with the same real mouse move (settle time scaled to
  the largest recovered smoothing tau) and diffed; pass threshold 0.98.
- **Aggregate** (`summary.similarity.fold` / `.full`): whole-viewport and full-page
  similarity. Report these *alongside* the per-node results, never instead of them.

Success = zero `failed` nodes and zero failed interaction/scroll/pointer states. `style-verified`,
`animated-unstable`, `hidden-at-capture`, `time-varying-replicated`, and
`skipped` (with its reason) are
acceptable statuses when explained. The whole-page outcome is in `summary.json`
(`pageStatus`: `success` / `partial` / `skipped` / `crash`; exit codes 0/3/4).
A page that never loads is `skipped:network-timeout`, not a crash.

To validate against a batch of live URLs (nothing is bundled from them):
`node scripts/batch-verify.js --urls urls.txt --out mf-out/batch` — prints a
per-page outcome table plus aggregate stats; the aggregate never hides a page.

## Verify the skill itself (regression gate)

```bash
npm run verify   # runs the pipeline on all bundled fixtures; exit 1 on any failure
```

Bundled fixtures: `fixtures/northlight` (scroll reveal + keyframes + hover),
`fixtures/accordion` (toggle), `fixtures/tabs` (exclusive), `fixtures/modal` (pair),
plus stress fixtures `stress-scale` (230 nodes), `stress-edgecss` (container
queries/`:has()`), `stress-iframe` (same-origin + sandboxed), `stress-flaky`
(404/hung assets), `stress-carousel` (autoplay → skipped, not learned), and
`stress-frames` (rAF inline-style motion + animated canvas → frame tracks +
stills + time-varying masking; v0.2), `stress-stagger` (CSS-delay + JS-timer
sequential scroll reveals → per-element curve + stagger recovery; v0.3), and
`stress-pointer` (parallax layers, 3D tilt card, smooth lerp follower → pointer
field fitting + tau recovery + pointer-state replay; v0.3).

## When to consult references/

- `references/behavior-patterns.md` — what each recovered behavior type
  (reveal/toggle/exclusive/pair) means, how it is detected, its genome shape, and what
  behavior graphing does NOT cover.
- `references/limitations.md` — hard scope limits (no live canvas/WebGL re-render,
  React-only output, single viewport), expected non-pass statuses, and
  legal/provenance rules. Read before promising results on an arbitrary site.
- `references/roadmap.md` — what is planned vs. research-level; consult when a user
  asks for something out of scope.

## Failure triage

- Reconstruction looks empty → the page likely loads cross-origin styles or paints
  everything into WebGL without DOM (check `references/limitations.md`); plain
  canvases and videos reconstruct as stills/bundled media since v0.2.
- A behavior was not recovered → it probably isn't a class-toggle machine driven by
  click/scroll; check `capture.json`'s probe evidence and the pattern catalog.
- `failed` nodes → inspect `/diff-*.png` residual maps and the node's entry in
  `convergence.json` (it lists the mismatched properties when known).

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [byte271](https://github.com/byte271)
- **Source:** [byte271/mirrorframe](https://github.com/byte271/mirrorframe)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-byte271-mirrorframe-mirrorframe
- Seller: https://agentstack.voostack.com/s/byte271
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.