Playwright custom matchers (toMatchFigma, toMatchPage, toMatchUrl) for Figma-to-web and web-to-web visual verification, plus a CLI for browsing and gating the evidence they produce.

Framelia does not own navigation, authentication, or browser-context creation — a developer's own @playwright/test suite does, and calls a framelia matcher at the point it wants to capture and diff. @framelia/playwright's Reporter drives a live dashboard during that run and persists a portable artifact afterward; the CLI never coordinates capture itself.

flowchart LR
  Dev["Developer's Playwright test<br/>(own navigation/auth)"] --> Matcher["toMatchFigma / toMatchPage / toMatchUrl"]
  Matcher --> Figma["Figma baseline"]
  Matcher --> Capture["Navigation-free capture"]
  Figma --> Pipeline["Compare + attach"]
  Capture --> Pipeline
  Pipeline --> Reporter["Playwright Reporter"]

  Reporter --> Events["Live results"]
  Events --> Server["Hono + SSE server<br/>(@framelia/dashboard-server)"]
  Server --> Dashboard["Vue dashboard"]
  Reporter --> Artifact["Versioned artifact<br/>(figma-baselined results only)"]

  Artifact --> Open["framelia open"]
  Artifact --> Report["framelia report"]
  Artifact --> DoneGate["framelia done-gate"]

Artifact remains source of truth. Live events only update progress before final artifact lands. No database, hosted service, account, or cloud state.

apps/
└── dashboard/               # Vue/Vite + Nuxt UI; depends only on contracts
packages/
├── contracts/               # versioned request, artifact, dashboard, event contracts
├── verify/                  # baseline resolution, capture primitive, compare, done-gate
├── dashboard-server/        # Hono/SSE server + result-projection, shared by cli and playwright
├── playwright/              # toMatchFigma / toMatchPage / toMatchUrl matchers + Reporter
└── cli/                     # framelia binary: init, contract create, status, schema,
    │                        # open, report, dashboard, fetch-gold, compare, done-gate
    └── dist/dashboard/      # generated dashboard bundled in npm package

Package dependency and build direction:

flowchart LR
  Contracts["@framelia/contracts"] --> Verify["@framelia/verify"]
  Contracts --> Dashboard["@framelia/dashboard"]
  Verify --> DashServer["@framelia/dashboard-server"]
  Verify --> CLI["framelia CLI"]
  DashServer --> CLI
  Verify --> PW["@framelia/playwright"]
  DashServer --> PW
  Dashboard -. "production build" .-> Bundle["CLI dist/dashboard"]
  PW -. "peerDependency" .-> PWTest["@playwright/test<br/>(consumer's own copy)"]

framelia remains public compatibility package and CLI distribution. It re-exports @framelia/contracts and @framelia/verify; dashboard source never imports CLI or engine internals. @framelia/verify never depends on hono/@hono/node-server — that HTTP dependency lives only in @framelia/dashboard-server, so neither @framelia/verify nor a matcher-only @framelia/playwright consumer's core capture/compare path pulls it in for that reason alone.

Requirements: Node.js 22.13+, pnpm 11.18+, Chromium for Playwright.

pnpm install
pnpm exec playwright install chromium
pnpm validate

Run dashboard with mock evidence and HMR; no contract or backend required:

pnpm dev:dashboard

Open URL printed by Vite. Mock covers passed, failed, blocked, Figma baseline, viewport capture, and element capture.

Build dashboard bundled into CLI:

pnpm build

Exercise a real matcher run with the live dashboard, from any project that has @framelia/playwright registered (see packages/playwright/README.md for a full quickstart):

// playwright.config.ts
export default defineConfig({
  reporter: [["@framelia/playwright/reporter"], ["html"]],
});

npx playwright test

The Reporter prints the dashboard URL and keeps the server up until the Playwright process exits.

Open an existing artifact without rerunning:

pnpm framelia open \
  --artifact /absolute/path/to/visual-verification.json

Use mock mode above for normal UI work. To debug real artifact/API integration, start archived dashboard backend first:

pnpm build
pnpm framelia open \
  --artifact /absolute/path/to/visual-verification.json \
  --no-open

Command prints backend URL such as http://127.0.0.1:43127. Keep process running. In second terminal, pass URL to Vite proxy:

FRAMELIA_API_ORIGIN=http://127.0.0.1:43127 pnpm dev:dashboard

Open Vite URL, normally http://localhost:5173. Vite proxies /api, /artifacts, and /events to CLI backend; Vue changes update through HMR.

pnpm typecheck
pnpm test
pnpm build
pnpm validate

Inspect CLI commands:

pnpm framelia --help

Detailed contract, command, artifact, and dashboard documentation lives in packages/cli/README.md.

Playwright matcher, Reporter, and getting-started quickstart documentation lives in packages/playwright/README.md.

Dashboard-specific development and HMR instructions live in apps/dashboard/README.md.

This repository owns verification engine, CLI, dashboard, artifacts, tests, and npm releases. Agent skills and plugin adapters remain in hungify/skills and consume released framelia commands.