Turn an existing page into a professionally designed version, then keep iterating on
element-pinned feedback until a human reviewer approves it. Treat the page's purpose,
content, brand, and behavior as constraints; there is no ground-truth design to copy.
-
Run pingfusi doctor. Locate the real source, build/test commands, responsive
breakpoints, and any brand constraints. If review login is missing, stop and have the
user run pingfusi setup; there is no offline review substitute.
-
Build the untouched page. Publish that static output through Pingfusi hosting and
save the immutable receipt, then capture a screenshot at the viewport(s) the final
proof will use:
pingfusi publish <built-dir> --name <name>-before \
--record .pingfusi/beautify/<name>/before.json --json
-
Improve the page in its own source. Work in this order: hierarchy and composition;
typography; spacing and alignment rhythm; color, contrast, and surfaces; responsive
behavior; states and finishing details. Prefer one coherent visual idea over a pile of
effects. If motion materially helps, add one restrained, purposeful beat and honor
prefers-reduced-motion.
-
Build and test at desktop and phone widths. Publish the current static output through
Pingfusi hosting, using a new URL for every round:
pingfusi publish <built-dir> --name <name>-current \
--record .pingfusi/beautify/<name>/current.json --json
Use a verified tunnel only if the production app genuinely requires a live server
and cannot produce a self-contained build. Never tunnel merely because development
happens through npm run dev.
-
File one custom round against the current public URL. Keep it within the service caps
(20 steps; 300 characters per step; 40 per option). Use one result for the normal
loop; use more only when the user explicitly wants higher-confidence review.
const fs = require("node:fs");
const path = require("node:path");
const { execFileSync } = require("node:child_process");
const kit = execFileSync("pingfusi", ["where"], { encoding: "utf8" }).trim();
const core = require(path.join(kit, "packages/core"));
const stateFile = path.resolve(".pingfusi/beautify/<name>/review.json");
fs.mkdirSync(path.dirname(stateFile), { recursive: true });
const currentDraft = JSON.parse(fs.readFileSync(".pingfusi/beautify/<name>/current.json", "utf8"));
const currentPublicUrl = currentDraft.url;
const verdicts = ["Professionally polished", "Needs another pass"];
const { ping_id } = await core.review.file(stateFile, {
url: currentPublicUrl,
title: "Is this page professionally designed?",
instructions: "Judge the current page on its own purpose. Add sticky comments or draw on exact current-page regions that still feel generic, messy, inconsistent, or hard to use.",
steps: [
{ text: "First impression: does this feel intentionally and professionally designed?", options: ["Clearly polished", "Almost there", "Still rough"], check: null },
{ text: "Check hierarchy, typography, spacing, alignment, color, and contrast. Pin a sticky comment or draw on every current-page region that needs a specific change.", check: null },
{ text: "Check desktop and phone layouts, interaction states, and any motion. Note clipping, awkward wrapping, weak affordances, or distracting effects.", check: null },
{ text: "FINAL REQUIRED STEP — verdict. Pick one exactly.", options: verdicts, check: null },
],
verdict_options: verdicts,
approve_verdicts: [verdicts[0]],
n_target: 1,
require_evidence: "none",
});
-
The filing command automatically chains client-safe wait legs until feedback. If a
raw MCP leg returns pending, immediately call pingfusi_wait again; never return
pending to the user or file a duplicate. The user does not request this continuation.
Passive result/verify reads do not renew the lease.
-
Fetch fresh with core.review.verify(stateFile). Read every structured comment and
selector, fix each pin in the project's own source, rebuild, republish to a new
immutable current URL, and file another round. Put a concise “changed since the last
review” step near the start of each refile. Each refile owns its own wait.
-
After approval, rerun the project's tests and capture the after screenshot at exactly
the before viewport(s). Keep raw round state and comments private; publish only a
sanitized before/after visual and approval receipt.
